Micro Focus Enterprise Developer 4.0 for Eclipse

Welcome to Enterprise Developer

  • Where do I start?
  • Product Editions and Licenses
  • Develop Applications on the Mainframe
  • Product Information

What's New

  • New Features in the 4.0 Release
  • Updating from an Earlier Release

Featured Sections

  • Making the Most Out of the Editor
  • Working With a Large Code Base
  • Developing Local and Remote Applications
  • Using Java and COBOL Together
  • Performance Programming
  • Deploying Applications

Tutorials and Demonstrations

  • Enterprise Developer Tutorials Guide
  • Demonstrations of Mainframe Subsystem Support
  • Cheat Sheets
  • Free Web-Based Training at our Training Store

Code Samples

  • Demonstrations of COBOL

Online Resources

  • Micro Focus Home Page
  • Micro Focus Channel on YouTube
  • Micro Focus SupportLine
  • Micro Focus Product Updates
  • Micro Focus Knowledge Base
  • Micro Focus Community Forums
  • Micro Focus Training Store

Provide Feedback

  • Contacting Micro Focus
  • Email us feedback regarding this Help


Welcome

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

This Welcome section includes information for new and existing customers about how to install and license the product, an overview of application development, changes from previous releases, any tutorials and samples.

If you are new to Enterprise Developer, check Where do I start? in this section.

You should also read the Help on Help topic for details on how to use this documentation.

Product Overview

Enterprise Developer supports IBM COBOL, IBM PL/I, IBM Assembler, IBM CICS, IBM IMS, IBM JCL, IBM DB2, IBM z/OS file formats and common batch utilities, including SORT. This means that you can develop and maintain the core mainframe online and batch applications under Enterprise Developer. You can then deploy these applications back on the mainframe or migrate them onto one of the Micro Focus Linux, UNIX or Windows-based production platforms.

The Application Workflow Manager section in General Reference explains the mainframe integration and mainframe modelling features of Enterprise Developer for z Systems.

Types of Licenses

Micro Focus offers Enterprise Developer with the following licensing options that unlock different functionality:

  • Micro Focus Enterprise Developer Connect

    Enterprise Developer Connect is for customers looking to use modern and productive Eclipse-based tooling to develop mainframe applications directly on the mainframe. Close integration to mainframe configuration management systems and the ability to easily customize the Eclipse-based IDE to include mainframe-based tools and processes means developers can take full advantage of modern development tools without having to learn new development processes.

  • Micro Focus Enterprise Developer

    Enterprise Developer is for customers looking to develop and modernize mainframe applications in a productive and modern Windows-based development environment, targeted for deployment onto an alternate server platform. Developers have the choice of either the Visual Studio or the Eclipse-based IDE and development and test tools are provided for all target environments currently supported by Micro Focus.

  • Micro Focus Enterprise Developer for z Systems

    Enterprise Developer for z Systems gives customers the choice to develop directly on the mainframe or under Windows. Mainframe applications can be developed, maintained and modernized regardless of where they will be deployed, either back onto the mainframe or onto an alternative server environment. Support is provided for both the Visual Studio and Eclipse-based IDEs and for all the development and test tools for every target environment currently supported by Micro Focus - including z/Linux, AIX and x86 environments.

    Enterprise Developer for z Systems combines all the capabilities of Enterprise Developer Connect and Enterprise Developer.

    Full mainframe integration and the Application Workflow Manager are only available in the Eclipse-based IDE.

Note:
  • The Enterprise Developer Personal Edition option is not available with this release.

    You can use the Personal Edition option if you install the previous release, Enterprise Developer Personal Edition 2.1 Update 1. When you start the product, follow the links in the Micro Focus Enterprise Developer Product Licensing dialog box to activate the free product.

  • If you are currently using the Personal Edition variant and you want to use the full functionality of Enterprise Developer or upgrade to Enterprise Developer for z Systems, please contact your Micro Focus representative and ask for a free evaluation license.
  • Updating from an Earlier Release
  • Where do I start?
    Find the information you need in order to get started depending on which aspects of the product you need to get to grips with first.
  • Overview of application development in Eclipse
  • Overview of Remote Mainframe Development
    Enterprise Developer for z Systems enables you to edit, compile and execute jobs directly on the mainframe all directly from within Eclipse.
  • Enterprise Developer Tutorials Guide
  • Technology Preview Features
    Links to features provided as technology preview only.
  • Enterprise Developer Editions and Licenses
    Different product licensing options are available depending on what functionality you want to use.
  • Product Information
    Includes information about installing and licensing this product, any known issues, and about how to contact Micro Focus.
  • Sample Programs
  • Cheat Sheets
  • The Micro Focus Community
  • Help on Help
Parent topic: Micro Focus Enterprise Developer 4.0 for Eclipse


Updating from an Earlier Release

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

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


New Features

  • Features Added in Enterprise Developer 4.0
  • Features Added in Enterprise Developer 3.0
  • Features Added in Enterprise Developer 2.3 Update 2
  • Features Added in Enterprise Developer 2.3 Update 1
  • Features Added in Enterprise Developer 2.3
  • Features Added in Enterprise Developer 2.2 Update 2
  • Features Added in Enterprise Developer 2.2 Update 1
  • Features Added in Enterprise Developer 2.2
  • Features Added in Enterprise Developer 2.1 Update 1
  • Features Added in Enterprise Developer 2.1
  • Features Added in Enterprise Developer 2.0
Parent topic: Updating from an Earlier Release


Features Added in Enterprise Developer 4.0

This release provides enhancements in the following areas:

  • Integration with Eclipse
  • Application Server JCA Support for Enterprise Server
  • Application Workflow Manager
  • AppMaster Builder
  • Build Tools for Windows
  • Code Coverage
  • Codeset support
  • Compiler directives
  • Data File Tools
  • Debugging
  • Docker
  • Documentation on working with large applications
  • Enterprise Server
  • File Handler
  • HCO for DB2 LUW
  • IMS support
  • JCL support
  • Mainframe Access
  • Managed COBOL
  • Library routines
  • Micro Focus Unit Test Framework
  • OpenESQL
  • Platform support
  • PL/I support
  • Web Service Clients
  • XML Extensions

Integration with Eclipse

Back to Top

This release provides the following general enhancements:

  • Support for Eclipse 4.7 Oxygen (64-bit) and 64-bit project templates - the 64-bit Eclipse 4.7 is now installed by default. Project templates are available for both 32-bit and 64-bit applications. You can set a default project template (either 32-bit or 64-bit) to use so that all future new projects will use that as the preference. On platforms only capable of building to 64-bit, the 64-bit templates are the default ones.

    The 32-bit Eclipse is still supported on 64-bit Windows platforms, however you need to manually install it and a 32-bit Java.

    Support for Eclipse 4.4 and 4.5 has been discontinued.

  • Starting with release 4 Patch Update 4, you can plug Enterprise Developer into Eclipse 4.8 (either 32-bit or 64-bit) installed on your machine. On Red Hat, this requires that you have Red Hat 7 or later.
  • Support for SUSE 12 - only the 64-bit SUSE 12 platform is supported and you can only use the 64-bit Eclipse with 64-bit projects on it.
  • (Native COBOL projects only) The Project Settings page in the project's properties now include a search option. This enables you to find files and build configurations that have settings different from the ones set at project level.
  • Remove File Directives - a context menu command in the explorer view enables you to reset a file's directives.
  • IVP diagnostic tool enhancements - it is now possible to run the server-side IVP diagnostic tool for diagnosing issues with a remote connection from within Eclipse installed at the client side. The IVP tool now also performs a check for whether XTERM is installed on the remote machine.
  • IMTK service mappings are now automatically regenerated if you make a change to the interface fields in the underlying program.

The following enhancements are available for JVM COBOL projects and package handling:

  • New wizards for creating ENUM, DELEGATE and VALUETYPE types.
  • Additional code snippets for Method-Id and Property-Id.
  • Showing and grouping packages in the COBOL Explorer view - use the COBOL JVM Project Presentation command from the View menu in the explorer to either display COBOL categories or packages.
  • Refactoring by renaming the package name - available from the context menus in the COBOL Editor and in COBOL Explorer.
  • Refactoring by moving source folders, packages or compilation units - available from the explorer context menu.
  • Support for switching off the package name mapping using the Each part of the package name corresponds to a subdirectory option in the Build Configuration page.
  • Support for packaging .class files in a .jar file when building COBOL JVM projects.
  • Open Type Hierarchy and Open Call Hierarchy context menu commands - available in the COBOL editor, COBOL Explorer and in the outline views while seeing the packages presentation in the IDE.

The following editor improvements are available:

  • A Properties context menu command - enables you to access a file's properties directly from the editor.
  • A Show In context menu command - enables you to locate the file in the COBOL or the PL/I Explorer.
  • Edit > Convert Tabs to Spaces command - enables you to convert any tabs in your COBOL source files to a specified number of spaces.

Automatic relinking of applications created with Enterprise Developer 3.0:

  • Enterprise Developer 4.0 can automatically relink existing projects created with Enterprise Developer 3.0 that have executable link artefacts. Eclipse displays a warning in the Problems view that the project requires relinking. It then offers a Quick Fix action for you to execute that will link your project with the most recent version of the run-time system.

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

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.

Application Workflow Manager

Back to Top

Improvements have been made in the following areas:

  • Model editor - now includes:
    • A new Edit action. Enables you to edit any model component instead of working with the Properties view. The new action enables you to change the attribute values of several model components at a time.
    • An Outline and a Relationship Hierarchy view.
    • Improved backwards and forwards navigation in the model.
    • Automated sequence numbering in the model.
    • The context menu of the model editor has been restructured for more clarity.
    • Context help.
    • Tool creation has been improved. Dependent components are generated from the function package tool definition.
  • Development of models:
    • Newly created empty models now contain all categories. The new models also validate without any errors or warnings.
    • A new AWM system type, “Custom System”, is available. This system type supports the model development process by facilitating the creation, change, load and reload of a model.
  • New modelling features:
    • The “Return Property Value” tool in the function package now supports several additional use cases.
    • The “Transfer File” tool in the function package offers improved support for mass processing.
    • Support for properties with an application-wide scope.
    • A modelling capability to structure the local file cache for copybooks and include files downloaded by the background parser in the editor. Additional tools are provided to check the existence of or clear the file cache for copybooks and include files.
  • The product help includes some tutorials showing how to create new models and extend the functionality of existing models. See the Tutorials Guide.
  • A number of template models are now available and can be used as a base to develop your own models.

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

AppMaster Builder

Back to Top

This release includes the following new features:

  • AppMaster Builder is now available in the Team Developer Perspective (Technology Preview) - this perspective provides a development environment for your AMB projects that includes much of the functionality available from the AppMaster Builder perspective plus access to the AMB Endevor Interface (Technology Preview).
  • AMB Endevor Interface (Technology Preview) - enables you to share and synchronize resources between an AMB project and mainframe Endevor datasets.
  • A renumber/unnumber feature in the Data Structure Editor.

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

Build Tools for Windows

Back to Top

This release includes Enterprise Developer Build Tools for Windows, a separately-installable component of Enterprise Developer that has been designed to be used in environments where you want to work with your COBOL and PL/I projects but you don't want the overheads associated with the Eclipse IDE.

Build Tools provide a lightweight, easy-to-install development environment that is well-suited for use in Docker containers and continuous integration or continuous delivery systems.

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

Code coverage

Back to Top

This release provides the following enhancements:

  • Support has been added in Eclipse for code coverage for procedural copybooks.

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

Codeset support

Back to Top

Support has been added to enable codeset mapping to additionally be configured to use IBM's Conversion Tables directly instead of the Micro Focus supplied tables. You need to download IBM's conversion tables from IBM's Web site. Then you can use the MFCODESET environment variable to convert between IBM's CCSIDs.

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.

Debugging

Back to Top

This release includes the following enhancements:

  • Debugging CICS channels and containers - you can now debug CICS COBOL applications that use channels and containers. The debugger now enables you to view the contents of any channels and containers, and to change content as you debug.

The following enhancements have been made to reverse debugging and live recording:

  • Reverse debugging and live recording have been enhanced significantly, and are now considered GA features. You can now debug using watchpoints and conditional breakpoints, and reset execution points. Debugging multi-threaded applications is now supported, and so are programs that contain OSVS performs and nested programs.
  • A command line utility, cobeslr, has been introduced to enable you to configure live recording for particular services or application instances of an enterprise server region.
  • You can now use the CBL_DEBUG_START and CBL_DEBUG_STOP library routines to start and stop a live recording session.

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

Docker

Back to Top

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

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

Documentation on working with large applications

Back to Top

The product help now includes a new section, Working with a Large Code Base, that includes recommendations and best practices for working with large applications inside the IDE. It includes tips on how to structure your projects, how to optimize the performance of the IDEs, and step-by-step workflow showing how to move an existing legacy application into Enterprise Developer.

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

Enterprise Server

Back to Top

The following enhancements have been made to Enterprise Server:

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

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

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

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

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

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

File Handler

Back to Top

This release provides the following enhancements:

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

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

HCO for DB2 LUW

Back to Top

This release includes the following new features:

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

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

IMS support

Back to Top

This release introduces the following new features:

  • The IMS Database Forward Recovery feature has been updated to provide point-in-time forward recovery that enables you to recover all database transactions completed up to a specified point in time, including date and time of day.
  • IMS support now includes MFS code for Light Pen devices. In your MFS, include a DEV statement with the FEAT=PEN parameter, and set the ATTR property on appropriate fields to DET or IDET to make them detectable by a light pen. See your IBM documentation for details.
    Note: MFS that contains light pen code must be regenerated to take effect if the MFS is part of an Enterprise Developer project created using an earlier release.
  • Support for export and import of IMS-configured enterprise server regions through Server Explorer.

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

JCL support

Back to Top

This release introduces the following new features and enhancements:

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

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

Library routines

Back to Top

The following library routines contain new functionality:

  • CBL_GET_OS_INFO - this library routine can now detect if the program is running within a Docker container: cblte-osi-rts-capabilities parameter, bit 7.
  • CBL_DEBUG_START and CBL_DEBUG_STOP - these library routines have been enhanced to start and stop a live recording session.

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

Mainframe Access

Back to Top

The installation process has been changed as follows:

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

Enhancements are available in the following areas:

  • The Mainframe Call Generator now runs in an independent address space. Previously, it was possible for code run in the MFA address space to enter a supervisor state. MCGLIB is now the new address space's STEPLIB. This enables other user modules to be called without placing them in MFA's STEPLIB, as was previously necessary. See Mainframe Call Generator: Calling Programs on the Mainframe for more information.

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.

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

Micro Focus Unit Test Framework

Back to Top

This release provides support for the following functionality:

  • Generation of unit test stubs for selected entry points within your program.

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

OpenESQL

Back to Top

This release provides the following new features:

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

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

Platform support

Back to Top

Note the following changes in platform support for this release:

  • Windows 8 and Windows Server 2012 are no longer supported for developing applications. They are still supported for deployment. Windows 8.1 and Windows Server 2012 R2 are supported.
  • SUSE platforms - this release only supports SUSE Linux 12 SP2, 64-bit.

    On this platform, you can only build COBOL and PL/I programs to 64-bit executables. This applies when using Eclipse on SUSE or with remote projects when Micro Focus Enterprise Developer UNIX Components is installed on SUSE.

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

PL/I support

Back to Top

Note: PL/I applications that were created using Enterprise Developer 3.0 and earlier must be recompiled in Enterprise Developer 4.0 to ensure they will compile and execute properly.

Support has been added for the following features in PL/I debugging:

  • Displaying complex data structures in the Expressions and Variables views.
  • Viewing the console window on non-Windows platforms so that output and input can be seen or entered.
  • The Outline view in the default Debug perspective.
  • Watchpoints on variables on the line where the variable has been declared.
  • Conditional breakpoints.
  • Skipping variables a defined number of times before the execution stops.
  • Adding expressions to the Expressions view from the Outline view.
  • Inspecting variables when referenced as part of a macro argument.
  • Signals and conditions.

PL/I compiler and Run-Time System enhancements:

  • Support for the following built-in functions - CHARVAL(), COMPARE(), CURRENTSIZE(), EDIT(), PICSPEC(), SOURCEFILE() and SOURCELINE().
  • Support for additional DATETIME() format strings.
  • Support for the FLUSH FILE(*), ITERATE, and RESIGNAL statement.
  • Support for the XMLOMIT and XMOLATTR attributes on variable declarations.
  • Support for the MARGINI compiler option.
  • Support for the SIZE and STRINGSIZE prefix conditions.
  • Improved support for the repeat factor on arrays of AREA variables.
  • Improved pointer arithmetic on 64-bit platforms.
  • Where necessary, MFPLX now recognizes selected *PROCESS statements and passes them to the appropriate preprocessors.

PL/I EXEC preprocessor:

  • The EXEC preprocessor now honors the -margins setting for the output MDECK in addition to the input file. This provides an improved experience in the Eclipse IDE when using the Outline view and other PL/I features provided by the background parser.

PL/I macro preprocessor:

  • The Micro Focus macro preprocessor now provides a new default behavior that mimics IBM's RESCAN(ASIS) behavior. In addition, a new option, rescan_upper, has been introduced to enable you to optionally mimic IBM's RESCAN(UPPER) behavior.

Improvements in compatibility with IBM's Macro Preprocessor:

  • Allows OTHER as an acceptable abbreviation for OTHERWISE on a macro SELECT statement.
  • Supports the SCAN/NOSCAN option on declaration of macro variables.
  • Implements the NOSCAN option on ANSWER statements.
  • The %NOTE message format has been modified to match IBM's behavior.
  • The SYSVERSION built-in function has been modified to always return a value of 22 bytes in length (space padded, if necessary).
  • Relaxed diagnostics for scenarios where Enterprise Developer is generating a warning message and IBM does not.

(Technical Preview) Generating PL/I test coverage reports:

  • The PL/I Compiler and Run-Time System now support capturing of information showing which lines in the program have been executed, and the generation of human-readable reports at the conclusion of a run.

(Technical Preview) Interaction with COBOL AMODE and 370 Assembler programs (Windows 32-bit only):

  • A new compiler option is available which enables Open PL/I to interact with 370 Assembler, and with COBOL programs compiled with AMODE. See the product help for the current limitations to this support.

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

Web service clients

Back to Top

This release provides the following enhancements for Web service clients:

  • Improved support for larger, more-complex WSDL files, including:
    • Configurable generation of variable arrays and repeated structures by specifying the Inline-Array-Size-Limit parameter.
    • Generation selection for service, port, and one or more operations.
  • Support for SOAP version 1.2 in addition to version 1.1.

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: New Features
Related reference
Application Workflow Manager
ASCIISOSI
GNTLITLINKSTD
Build Tools for Windows
CICS Channels and Containers
Code Coverage
Compiler Directives
Configuring Multiple Catalogs
Data File Tools
Debugging Using a Live Recording
Debugging Commands and Options
Defining XA Resource Entry
Docker Support
Enterprise Server security facility
Filter the Data File
Functions
Handling spaces and whitespace in XML
Mainframe Call Generator
Micro Focus FTP Utility
Micro Focus Unit Testing Framework
MVSSPLPB API
Tutorials
Working With a Large Code Base
ES_WRITE_CUSTOM_HSF
ESCSTHSF


Features Added in Enterprise Developer 3.0

This release provides enhancements in the following areas:

  • Integration with Eclipse
  • Application Server JCA support for Enterprise Server
  • Application Workflow Manager in Enterprise Developer
  • AppMaster Builder
  • Building applications
  • Character encoding
  • CICS Web services
  • COBOL language enhancements
  • Code analysis
  • Code coverage
  • Compiler control
  • Data File Tools
  • Database access - HCO for DB2 LUW
  • Database access - HCOSS
  • Database access - MySQL
  • Database access - OpenESQL
  • Debugging applications
  • Deployment on multiple platforms
  • Documentation
  • Enterprise COBOL 6.1 compatibility
  • Enterprise Server
  • iFileshare
  • IMS support
  • Mainframe Access (MFA)
  • Micro Focus Unit Testing Framework
  • PL/I support
  • Rumba terminal emulator
  • XML processing
  • z/Server

Integration with Eclipse

This release provides enhancements in the following areas:

  • Support for Eclipse 4.6 - Enterprise Developer now ships with the 64-bit Eclipse 4.6. By default, Eclipse is configured to compile applications for 32-bit and the default target platform for new projects is 32-bit.
    Note: Applications that were created using Enterprise Developer 2.3 Update 2 and earlier must be recompiled in Enterprise Developer 3.0 to ensure they will compile and execute properly.

    The 32-bit Eclipse is still supported on 64-bit Windows platforms and you need to manually install the 32-bit IDE and a 32-bit Java

    You can install the Enterprise Developer plugin in other instances of Eclipse (32-bit or 64-bit). Support for Eclipse 4.2 and 4.3 has been discontinued.

  • Rename refactoring - enables you to rename COBOL elements such as variables and identifiers, section and paragraph names, classes, and methods across a program or a workspace. Renaming helps improve the readability of an item or make its purpose clearer. Two preferences for renaming are supported in Eclipse - directly in the editor or using a Rename dialog box that offers a preview.
  • Dependency paths - it is now possible to specify dependency paths to folders that are outside the project folder.
  • Standalone files:
    • It is now possible to specify the locations where the IDE will search for the program symbol files (.idy) for standalone files: Window > Preferences > Micro Focus > COBOL > Standalone Files > Program Symbols (.IDY).
    • It is now possible to use the Eclipse debug configurations to debug standalone files, including core dump files.

    In previous versions of Enterprise Developer, standalone files were known as "single files". References to "single files" in the IDE and the product help have been changed to "standalone files".

  • Error reporting - errors reported in the Console view now include a link for opening the source file at the line where the error originates.
  • Editor improvements - an option for removing trailing whitespaces has been added to the IDE preferences for the COBOL and the PL/I editor.

Back to Top

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

Application Server JCA support for Enterprise Server

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

Back to Top

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

Application Workflow Manager in Enterprise Developer

This release includes improvements in the following areas:

  • Application Workflow Manager model editor:
    • The definition of linked element types and properties has been improved. Some required model objects and relationships are now generated automatically.
    • The editor now detects unused references in a model.
  • Application Workflow Manager modeling:
    • Basic resource processing has been extended to support mass processing where appropriate.
    • The AWM function package now includes the following new tools:
      • "Return Property Value" - enables you to map the values of input parameters to output parameters.
      • "Validate Value" - enables you to validate a filename against a specified naming convention.
    • You can now specify enabling conditions in a more granular way. An additional condition type has been introduced to hide actions or properties. For example, hiding an action from the context menu of an element.
    • The Eclipse linked element type now enables the label and label decorator to be automatically set to mirror their representation in other Eclipse views if they are not explicitly modeled.
    • Table columns can be modeled as a combination of two or more properties - for example, to combine a date and time property value.
    • Additional standard icons.
  • Mainframe Access (MFA) integration and the MVS function package:
    • MVS resources are now available as linked element types.
    • The following tools have been added to the MVS function package:
      • Delete MVS data set or member
      • Rename MVS data set or member
      • Copy MVS file to clipboard, Paste MVS file from clipboard
      • Get data set or member attributes
    • Improvements have been made to copy and paste support in the MVS Explorer.
    • File mapping between z/OS and local files now supports additional local code pages.
    • The editor context menu contains a "Submit to Mainframe" action when a file is opened from the MVS Explorer with an extension which is mapped to JCL in the File Mappings view.
    • Some of the new MVS function package tools replace existing ISPF function package tools resulting in improved performance of the tools.
    • The sample model "MVS Projects Sample Application" has been improved by including some of the new AWM MVS function package features.
  • AWM is now available as a standalone feature which you can install into a separate instance of the Eclipse IDE installed on your machine.

Back to Top

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

AppMaster Builder

The AMB Program Painter has been enhanced to enable collapsing and expanding multiple-line paragraphs and working-storage such as WS01.

Building applications

This release provides the following improvements:

  • Support for faster, parallel building on multi-CPU machines - support has been added for multi-processor compilation of the sources in native COBOL projects on multi-CPU machines.

    You can specify the maximum number of concurrent compilations from the IDE preferences - Window > Preferences > Micro Focus > Builder.

Back to Top

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

Character Encoding

A new utility, cobutf8, is available. cobutf8 enables you to seamlessly run applications that require non-UTF-8 character encodings in a UNIX environment that is using a UTF-8 locale.

Back to Top

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

CICS Web Services

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

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

Back to Top

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

COBOL language enhancements

This release includes the following enhancements to the COBOL syntax:

  • The DISPLAY-OF and NATIONAL-OF intrinsic functions are now able to process conversions using any IBM CCSID value. See To install a CCSID Table for details on installing the required CCSID table.

The following enhancements are available in managed COBOL:

  • To avoid an exception being thrown if an explicit conversion fails, use the AS IF syntax, which results in the target object being set to null and no exception thrown. See cast expressions in the Expressions topic for more information.

Back to Top

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

Code analysis

This release provides the following improvements:

  • A new group of predefined rule sets for 64-bit readiness is now included in Enterprise Developer.
  • Support for importing code analysis reports produced with one of Micro Focus's advanced tools for code analysis, Enterprise Analyzer or COBOL Analyzer.

Back to Top

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

Code coverage

The following improvements are available within the IDE:

  • Information about unexecuted programs - the code coverage reports in the Code Coverage window now show the unexecuted programs.
  • Code coverage support for standalone COBOL files - you can import existing code coverage reports in the Code Coverage window and use it to supply code coverage information for standalone files.
  • Remote code coverage files - in the Code Coverage window in Eclipse, it is now possible to import code coverage report files that are stored in remote locations.
  • Test coverage files - it is now possible to use a test coverage file to debug applications.

If you are using Test Coverage from the command line, you can now use the following features:

  • A new Compiler directive, COLLECTION - the directive enables test coverage to gather information about unexecuted programs. In the IDE, this directive is automatically set on a project when you enable code coverage for it.
  • A new command line utility, tcutil - the utility enables you to convert the test coverage binary results file into XML format.
  • It is now possible to integrate test coverage in a Continuous Integration (CI) system. You can use tcutil and an XSLT processor to transform test coverage data into a format suitable for including in a CI.

Back to Top

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

Compiler control

The following Compiler directive are new in this release:

  • COLLECTION - provides a mechanism for code coverage to identify unexecuted programs.

The following Compiler directives have been updated:

  • ALIGN - this directive has new parameters (FIXED and OPT) that can be used in conjunction with the integer taken, which can aid performance. The default is ALIGN"8 OPT"; see the Comments section of the ALIGN Compiler directive topic for details of its affect on memory boundaries.
  • ARITH - this directive emulates the IBM mainframe option of the same name. Defines the maximum number of digits for numeric data items.
  • FASTINIT - this directive is now on by default when setting the MF dialect; it remains not set by default for other dialects.
  • SSRANGE - this directive now has an additional option (3), which permits zero-length reference modified items at run time when bounds checking.
  • XMLPARSE - includes a change in the way entities are processed when XMLPARSE(COMPAT) is set

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 and PL/I structure files.
  • Automatic timeout - if no internal operations or external actions (such as a mouse click) have been detected for 30 minutes, Data File Tools now displays a countdown message. If the user does not take any decision within the specified period, Data File Tools closes all opened files.

Back to Top

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

Database access - HCO for DB2 LUW

This release provides a new DB2(QUALIFY-CALL) Compiler directive that enables stored procedure invocations to include a schema name.

Back to Top

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

Database access - HCOSS

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

Back to Top

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

Database access - MySQL

This release provides support for MySQL with ODBC.

Back to Top

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

Database access - OpenESQL

This release provides the following new features:

  • Statement prefixes for the SQL(CHECK) Compiler directive that enable the creation of temporary tables and other SQL objects at compile time, ensuring full SQL syntax checking during compilation.
  • SQL(OPTIMIZECURSORS) Compiler directive that enhances processing for traditional embedded SQL cursors that use WITH HOLD and FOR UPDATE clauses.
  • SQL(CLOSE_ON_COMMIT) Compiler directive to leave cursors open for further result set processing after a commit.
  • SQL(GEN-SQLCA) Compiler directive that generates an SQLCA similar to the z/OS DB2 directive STDSQL(YES).

Back to Top

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

Debugging applications

This release provides the following new features:

  • Debugging core dump files without a project.
  • Reverse debugging (Technology Preview) - it is now possible to step backwards through an application to view a recording of the previous steps executed in the current debug session. Input is not accepted while viewing recorded execution.
    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.

  • COBOL Live Recording debug configuration (Technology Preview) - it is now possible to record an application execution and view its execution path in the debugger. This method of debugging enables stepping both forwards and backwards, but does not accept input.
    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.

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.
  • Configuring an SSL Client Connection to a Mainframe - includes instructions about how to configure client applications to connect to MFA and z/Server mainframe via AT-TLS in a zOS environment.

Back to Top

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

Enterprise COBOL 6.1 compatibility

The following features have been added to support Enterprise COBOL 6.1:

  • A new statement, JSON GENERATE, which enables you to convert data to JSON format.
  • A new special register, JSON-CODE, and its resulting exception codes to support the new statement.
  • Two further new statements, ALLOCATE and FREE, to obtain and release dynamic storage.
  • A new MF level, MFLEVEL"19", which contains the following new additions to the reserved words list:
    • JSON
    • END-JSON
    • ALLOCATE
    • FREE
    • INITIALIZED (context-sensitive reserved word)
    Note: These keywords are also in effect under the ENT dialect.
  • The SSRANGE Compiler directive has an additional option (3), which permits zero-length reference modified items at run time when bounds checking.
  • Support for the INITIALIZE statement under the ENT dialect has been enhanced.

Back to Top

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

Enterprise Server

Improvements are available in the following areas:

Integration with Eclipse:

  • Exporting an enterprise server definition from the IDE in XML format.
  • Importing an enterprise server into the IDE using its definition file.

EXEC CICS TRANSFORM:

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

JCL spool

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

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

Long user IDs and passwords:

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

Multi-factor sign-on:

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

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

SHA-256 support in DemoCA:

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

Syslog auditing:

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

Back to Top

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

iFileshare

iFileshare is no longer considered an Early Adopter Program, and contains the following enhancements in this release:
  • An improved failover and recovery process. iFileshare now supports full recovery of nodes in the group. For high availability (HA-VSAM) groups, servers can now rejoin the group without the entire group having to be restarted. In addition:
    • A primary failover now results in a takeover from the most suitable node.
    • If configured, external clients will automatically reconnect to the new primary and will issue a notification if the transaction has been lost.
    • A failed node, when restarted, will rejoin the group, recover its files and request a log update from the current primary. Once this task has completed it will be considered an active hot-standby and will continue to process replication requests as normal.
    • Users will experience a higher level of uptime/availability with their Fileshare configuration and will be able to recover from errors more easily.
  • A new exit procedure, ifsexitproc.cbl, can be configured to automate some aspects of iFileshare behavior.
  • The iFileshare Control page in ESMAC contains details of the current iFileshare high availability group.
  • The following new iFileshare-specific environment variables are available:
    • FSWRKDIR - enables you to specify the Fileshare working directory, overriding the default, which is the system directory of the region.
    • FSCHKLFH - determines if a check is performed when a high availability group is started, to test the consistency of the data files within the group.
  • The database reference file (dbase.ref) now supports wildcard matching for filenames, allowing you to perform operations on multiple files at once; for example: fs /d dbase.ref /f data\* adds the entire contents of the data directory to the database reference file.

Back to Top

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

IMS support

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

Back to Top

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

Mainframe Access (MFA)

This release provides the following improvements:

  • Running MFA client in 64-bit processes - you can now call the MFA client modules from 64-bit applications and take advantage of the wider memory addressing available to those modules.
  • MFA client CTF tracing - MFDAS now supports CTF tracing. This provides better diagnostics of issues and helps increase turnaround on issues. CTF is common to a number of Micro Focus modules so cross-component logging can be turned on from a single place.
  • MFA and z/Server holder close coupling - MFA server can now start the z/Server holder as a subtask in its own address space. This helps improve the performance as MFA can hand-off AWM sessions directly to the z/Server scheduler without instructing AWM to redirect them.
  • Endevor functions - the following functions are now available to Enterprise Sync and MFDAS: DELETE, DIRX, GENERATE, GETENQI, LIST, MOVE, SIGNIN and TRANSFER.

Back to Top

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

The Micro Focus Unit Testing Framework

The Micro Focus Unit Testing Framework is now available from within the IDE. It includes much of the architecture you would expect of an xUnit framework to create, compile, run and debug unit tests, including the following features:

  • A unit test project template.
  • A test creation wizard that enables you to generate tests from your source code.
  • Code templates for each element of a test case.
  • Support for running tests with Code Coverage enabled.
  • The Micro Focus Unit Testing view, where you can manage your test runs and view test output.

There has been a number of enhancements to the command line version of the Micro Focus Unit Testing Framework. Support has been added for:

  • Running test fixture files using Apache Ant.
  • Applying traits to your test cases, then performing a test run based on those traits.
  • Applying a high, medium, or low priority to test cases, which affects the order in which they are run.
  • Adding coded command line options directly into your test code.
  • Using a test run-specific configuration file, in which you can set environment variables.

Back to Top

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

PL/I support

Enhancements are available in the following areas:

PL/I debugging

  • New Eclipse-based PL/I debugger - the CodeWatch debugger has been replaced with the debugger within the industry standard Eclipse User Interface. New features such as true remote debugging are now available along with a much simplified user debugging experience that works in exactly the same way as the debugger works for COBOL (and Java). This can help improve the productivity of PL/I application developers who are adding new features or migrating existing applications to a distributed world.

    A selection of features which are now supported includes:

    • Attaching to a running PL/I process, waiting for attachment from a PL/I process
    • Breakpoint-setting in the editor
    • Stepping through PL/I code and querying the contents of PL/I data items
    • Viewing the execution stack, resetting the executions point, and running to a selected line
    • Remote debugging of PL/I applications running on Linux or AIX machines

PL/I compiler and run-time system

Support has been added to enable the following:
  • The UNSIGNED data type - the PL/I Compiler now supports the UNSIGNED attribute for FIXED BINARY data items. In addition to the basic language support, the SIGNED, UNSIGNED, ISIGNED, and IUNSIGNED new built-in functions have been implemented. These features offer an improved compatibility with other languages such as C or C++.
  • New built-in functions - UTF8(), UTF8TOCHAR(), UTF8TOWCHAR(), and SUBTRACT(). These new build-in functions make it easier to modernize migrated PL/I applications.
  • The ENTRY LIMITED data attribute - the Open PL/I Compiler now accepts and fully supports the LIMITED attribute on ENTRY declarations. This increases the compatibility of the Micro Focus PL/I Compiler with IBM's PL/I for applications that you are migrating from the mainframe.
  • Support for processing of JSON data - a number of new built-in functions are available for processing JSON text. This enables you to modernize your PL/I applications by enabling them to interpret, create and process JSON data.
    JSONGETARRAYEND | JSONPUTARRAYEND | JSONGETMEMBER
    JSONGETARRAYSTART | JSONPUTARRAYSTART | JSONGETVALUE
    JSONGETCOLON | JSONPUTCOLON | JSONPUTMEMBER
    JSONGETCOMMA | JSONPUTCOMMA | JSONPUTVALUE
    JSONGETOBJECTEND | JSONPUTOBJECTEND | JSONVALID
    JSONGETOBJECTSTART | JSONPUTOBJECTSTART

PL/I macro preprocessor

A number of enhancements have been made to improve the compatibility between the PL/I macro preprocessor and IBM's macro preprocessor which helps ease the effort required to migrate PL/I applications to new platforms. Support is available for:

  • RESCAN in the ANSWER statement.
  • The shorthand "<>" syntax for indicating "Not Equal To".
  • Break characters in hex literal constants to improve readability of code.
  • A new option, -tagdbg, that annotates macros and %FILE/%ENDFILE statements with line numbers and the source file which injected them.
  • The -caseasis option which allows source code to flow through to the mdeck.pp file retaining the case as entered.
  • Macros with a null parameter list.
  • The LEAVE statement.
  • Improved macro preprocessing speed.
  • New built-in functions: SYSENDIAN() and MFPHOSTNAME().

Back to Top

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

Rumba terminal emulator

Enterprise Developer now ships with Micro Focus Rumba 9.5.

Back to Top

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

XML processing

XML PARSE now works in a purely managed COBOL environment. It is now supported in JVM COBOL and, in both .NET and JVM COBOL, it has a fully managed implementation. XML PARSE working without calling out to native code ensures it can be used in restricted rights environments.

Back to Top

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

z/Server

The z/Server configuration has been simplified through the use of a unified scheduler. This replaces the three different types of scheduler, STC, CEA and JOB, that were used previously for starting different types of user servers.

Back to Top

Parent topic: New Features
Related reference
Where do I start?
ED VC - Significant Changes in Behavior or Usage
Technology Preview Features
cobutf8
CBL GET PROGRAM INFO
Classic Data File Tools Command Line Utility
Compiler Directives
Configuring AutoCorrect
CONTMVS
Deployment on Multiple Platforms
Extracting COBOL code to a copybook
IFileshare
Library Routines
Micro Focus Unit Testing Framework
NATIONAL
The JSON GENERATE Statement
ALIGN
ALLOCATE
FASTINIT
INITIALIZE Statement
Reserved Words Table
SSRANGE
The Free Statement
The XML PARSE Statement
XMLPARSE
To Install a CCSID Translation Table
Expressions


Features Added in Enterprise Developer 2.3 Update 2

This release provides enhancements in the following areas:

  • Integration with Eclipse
  • Application Workflow Manager (AWM)
  • CICS Web services (Early Adopter Program)
  • COBOL language enhancements
  • Classic Data File Tools
  • Compiler directives
  • Database access - DSNREXX
  • Editor writing assistance
  • File handling
  • IMS support
  • Interface Mapping Toolkit
  • Library routines
  • PL/I support
  • Tutorials

Integration with the Eclipse IDE

Back to Top

Enhancements are available in the following areas:

  • The following settings have been added to the BMS page in the project's and file properties - Redefine Input, SDF Map Size, and Hyphenate Field Suffix.
  • Using the search facility, Search > Micro Focus, you can now limit the search to the copybooks used by the current program rather than all copybooks in the project or the entire workspace.
  • The editor provides a new context menu command, Extract COBOL code to copybook, that enables you to move a selected segment of the code to a new copybook file in your project. The segment of code moved to a copybook is replaced with a COPY statement in the original program.
  • Support for Eclipse 4.5 - after installing Enterprise Developer, you can add it as a plugin into a separate instance of Eclipse 4.5. See your product's Installation notes.

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

Application Workflow Manager (AWM)

Back to Top

This release provides enhancements in the following areas:

AWM model editor:

  • It is now possible to use drag and drop not only for objects of the same type but in all cases where this is relevant. For example, it is now possible to drag tool descriptors onto an action descriptor which will create an "Action Descriptor has Tool" relationship. Dragging a File_Descriptor_has_Property relationship onto an element list structure will create an Element_List_Structure_has_Column relationship.
  • It is now possible to group any major modelling objects such as action descriptors, properties and tool descriptors in the AWM model editor.

AWM modelling:

  • The Eclipse function package includes a new tool, "Build Project", and the MVS function package includes a new tool, "Refresh DataSet".
  • "Edit MVS File" now provides a parameter to the editor ID.
  • The AWM meta model has the following enhancements:
    • New model objects for configuring the decoration of labels displayed in the Team Developer Tree view.
    • Visible conditions for enabled conditions. You can use the visible conditions to specify whether an action should be shown on an element's context menu.
    • A new application-specific attribute, INITIAL_PARSE, enables you to specify whether the background parse process of the editor should start when a file is opened in the editor.
    • The Eclipse function package includes a new category of linked properties that support the Eclipse team properties.
    • The Eclipse linked element types now support the "Run As", "Debug As" and "Profile As" context menu actions.

AWM z/OS extensions:

  • The Micro Focus z/Server connection now provides an Owner filter.
  • The Micro Focus z/Server connections support case sensitive input of passwords.
  • The IDz function package provides a new tool which opens MVS resources depending on the RSED connection defined in the Micro Focus z/Server connection. This now enables you to download copybooks in IDz environments using the Micro Focus z/Server connection.

Micro Focus model extensions:

Support is available in the Micro Focus model extensions (the Enterprise Development Projects model and the SCM models for Endevor, ChangeMan, SCLM and SVN) for:

  • The Eclipse team linked properties
  • Grouping modelling objects in the editor
  • Visible conditions
  • The "Run As", "Debug As" and "Profile As" commands

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

CICS Web services (Early Adopter Program)

Back to Top

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

This release provides an initial support for CICS Web services (CWS) using an SOAP-based provider and requester modes and using HTTP or MQ as the transport mechanism. CICS Web services support the Coded Character Set Identifier (CCSID) and configuring the CCSID is a prerequisite for CWS in all environments.

Restriction: Security and Web Service Atomic Transactions (WSAT) are not currently supported.

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

COBOL language enhancements

Back to Top

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

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

Classic Data File Tools

Back to Top

A new command line utility is available which enables you to initiate the following actions: open data files, create or open record layout files, create or open segment layout files, and open IMS databases using a DBD or PSB file. Note that although you can initiate these actions from the command line, you must complete them from within the IDE.

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:

  • 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. This offers equivalent functionality to the command_line_linkage tunable.
  • EBC-COL-SEQ - controls the behavior of an EBCDIC collating sequence, specified in a NATIVE"EBCDIC" program. EBC-COL-SEQ"1" (the default) maintains use of the long-standing fixed (platform-independent) EBCDIC collating sequence. EBC-COL-SEQ"2" prompts use of the latest CODESET table, which varies according to platform and user-controlled MFCODESET environment variable setting.
  • NATIONAL - enables you to specify numeric, edited and external floating point items as USAGE NATIONAL.

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

Database access - DSNREXX

Back to Top

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

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

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

Editor writing assistance

Back to Top

This release provides the following enhancements:
  • Colorization of conditional compilation regions - by default, inactive code is now colored the same as Compiler directive elements. Inactive code is defined as code within conditional blocks that do not evaluate with the applied Compiler settings.
  • $REGION statement - support is provided for the $REGION Compiler-control statement. You can use $REGION - $END-REGION to surround blocks of code that you want to fold or expand in the editor.
  • AutoCorrect - you can configure the editor to automatically fix the most frequently misspelled words. You use the IDE preferences to specify a list of words that you sometimes mistype, and the correct spellings for them. Whenever you misspell that word, the editor automatically replaces it with correct version. This feature is enabled by default and can be configured from a new preference page in Window > Preferences > Micro Focus > COBOL > Editor > AutoCorrect.

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

File handling

Back to Top

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

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

IMS support

Back to Top

This release supports the PROMPT keyword in MFS source files.

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

Interface Mapping Toolkit

Back to Top

This release supports JSON schemas for the generation of REST Web service clients in the Eclipse IDE.

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

Library routines

Back to Top

The following library routine contains new functionality:

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

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

PL/I support

Back to Top

This release provides the following enhancements:

  • New built-in functions - support has been added for the ONCONDID() and SAMEKEY() built-in functions.
  • Support for strings declared with the VARYINGZ attribute - the Open PL/I compiler and run-time system now support the use of VARYINGZ strings as variables, parameters, and targets for built-in functions. This provides an improved compatibility with IBM's mainframe compiler, and the ability to more easily interact with other languages such as ANSI C.
  • Improved PL/I macro preprocessor compatibility - the Open PL/I compiler now supports all macro preprocessor built-in functions used by IBM's PL/I Macro Preprocessor.
  • Improved compatibility with IBM's Structure Alignment rules - the -zalign option of the Open PL/I compiler now maps structure elements of the BIT data type that do not consume a full byte to the same boundaries as IBM's PL/I compiler. This helps make the migration of mainframe data files to a distributed platform easier and improves the program execution compatibility.
  • Improved floating point support - the Open PL/I Code Generator now utilizes the newer Intel floating point operands for improved speed. In addition, the Code Generator now provides improved compatibility with passing parameters between C and COBOL.
  • PL/I editor improvements:
    • A new context menu command in the editor, Extract PL/I code to an include file, which enables you to move a selection of code in the editor into a new include file. The extracted code is replaced with an %INCLUDE statement which references the include file.

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

Tutorials

Back to Top

The product help includes the following new tutorials:

  • Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server - that walks you through the process of deploying an EJB that contains JVM COBOL code.
  • Tutorial: DSNREXX, that walks you through the process of executing DB2 LUW queries using DSNREXX.

Parent topic: New Features
Related concepts
Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Related reference
Application Workflow Manager
CBL GET PROGRAM INFO
Classic Data File Tools Command Line Utility
Compiler Directives
Configuring AutoCorrect
Extracting COBOL code to a copybook
Library Routines
NATIONAL
PL/I Programming
SELECT - ICETOOL emulation
Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server


Features Added in Enterprise Developer 2.3 Update 1

This release provides enhancements in the following areas:

  • Integration with Eclipse
  • Application Workflow Manager
  • Application Server JCA support for Enterprise Server
  • AppMaster Builder
  • Code analysis
  • Code coverage
  • Compiler directives
  • Enterprise Server
  • Data File Tools
  • Database Access - HCO for SQL Server
  • Database Access - Mainframe Batch Database Tools (MBDT)
  • Database Access - SQL Option for DB2
  • Drag and Drop
  • Editor writing assistance
  • File Handling
  • iFileshare - Fileshare under Enterprise Server (Early Adopter Product)
  • Library routines
  • Mainframe support and emulation
  • Micro Focus Unit Testing Framework
  • Managed COBOL syntax
  • Native COBOL syntax
  • PL/I support
  • Rosetta Stone for COBOL, .NET and Java Developers
  • SourceConnect
  • z/Server Configuration Utility

Integration with Eclipse

Back to Top

This release provides enhancements in the following areas:

Editors:

  • COBOL editor:
    • You can now specify the increment for the COBOL and the standard line numbering from Window > Preferences > Micro Focus > COBOL > Editor > Line numbering.
    • You can now toggle single or multiple lines between commented and uncommented states.
  • JCL editor - the Unnumber and Renumber commands are now supported for the JCL editor. You can specify the line number increments from the IDE preferences in Window > Preferences > Micro Focus > JCL > Editor > Line numbering.
  • PL/I editor:
    • The Unnumber and Renumber commands are now supported for the PL/I editor. You can specify the line number increments from the IDE preferences in Window > Preferences > Micro Focus > PL/I > Editor > Line numbering.
    • You can now toggle single or multiple lines between commented and uncommented states.

Building applications:

  • Environment variables - a new page, Build Environment, in the project's properties enables you to specify environment variables for your applications. You can also specify environment variables that only apply at run time on the run or debug configuration for the application.

See Related Information at the end of this topic.

Application Workflow Manager

Back to Top

New features and enhancements are available in the following areas:

  • AWM modelling:
    • It is now possible to associate keyboard shortcuts with modeled actions. The key sequence is displayed in the corresponding context menu at run time.

      Currently, it is not possible to persistently overwrite any modelled key bindings with user key bindings.

    • Support is provided for table row updates in modeled AWM dialogs - it is now possible to use table row actions in in the modeled AWM dialogs to modify table rows similarly to how this is done in the Team Developer Tree or in the Table views. The supported modifications are copy, delete, insert and update of selected rows.
    • It is now possible to hide element properties in an AWM element's property view using the "Element Type has Property" condition.
    • The "Get Children" attribute of an element type has been replaced by the "Element Type has Get Children Action" relationship between an element type and an action descriptor which enables you to check whether an AWM container element can be expanded.
  • Full support and a seamless integration is now available in the IDE for the AWM SCM models for ChangeMan, Endevor and SCLM. You can now check out sources from the SCM system directly into your COBOL or PL/I projects in the IDE and vice versa.
  • AWM Run-Time:
    • A single port for server connection - starting with this release you now only need to specify one port, the Mainframe Access (MFA) server port, for the Micro Focus z/Server connection type in the Remote System view. All other required ports are configured centrally in the server configuration on the mainframe. You must install the latest version of z/Server.

      It is still possible to connect to an earlier supported version of z/Server. There is a backward compatibility flag that must be enabled to be able to specify the three ports that are required with the earlier z/Server version.

    • SSL support - it is now possible to specify a SSL/TLS configuration when defining a new Micro Focus z/Server connection in the Remote System view. The client then uses the configured SSL/TLS certificates for the communication with the server. The mainframe must support SSL/TLS tunneling (such as AT-TLS from IBM).
    • RACF passticket support - AWM clients now include an extension point which you can use to provide user credentials from an external application. When connecting to a Micro Focus mainframe server system (either MFA or z/Server), the password dialog is then bypassed. This enhancement enables you to integrate a login mechanism that uses RACF passtickets instead of RACF passwords.
    • Support for binary download and upload of files - it is now possible to specify a Transfer Mode (either text or binary) in the file mapping dialog of the File Mappings view when transferring files between the mainframe and the local machine such as when editing files or during a drag and drop operation:
      • Text - the configured code pages are respected.
      • Binary - no code page translation is applied. You must use binary mode when transferring mainframe load modules.
    • The SVN attachment is now an integrated part of the Enterprise Developer and is installed as part of the product. This enables you to use the tools from the SVN function package in an AWM model. For example, you can extend an existing model by adding the check-in and check-out functions for sources in an SVN repository. A sample model that includes a full integration of SVN support in the Enterprise Development Project model is available.
    • A new AWM "MVS Projects Sample Application" is available with the installation of z/Server. The application uses the tools from the MVS and ISPF function package and is designed as a template AWM application for project-based access to MVS data.
  • The AWM Enterprise Development Projects Application now provides the following enhancements:
    • Web Services support for COBOL applications in the Team Developer perspective.
    • Context menu commands for performing code analysis on demand of the sources in your projects from the Team Developer Tree and Table views.
    • An Open in context action for COBOL copybooks in the Team Developer Tree and Table views.
    • An Import and Export are wizards from the context menus of the Team Developer Tree and Table views.
    • Error markers in the Team Developer Tree and Table view on project, folder and file level when the sources compile with errors.
    • A "Link with Editor" function in the Team Developer Tree view for such files that you viewed when you expanded the tree view.
    • Support for using filters (using Customize View > Filters) in the Team Developer Tree and Table views to specify what entries should be displayed.
    • An improved support for drag and drop between the Team Developer Tree and Table view and the standard Eclipse views (such as Project Explorer and the Navigator view), the Remote Systems view (from the local and the Micro Focus z/Server connections), and Microsoft's Windows Explorer.
  • The product help now includes a new section, AWM API Programming and Extension Points, that describes the published AWM API classes and interfaces and the extension points provided by the AWM client. Use cases for the usage of the AWM API and extension points and a detailed tutorial showing how to extend the main AWM extension point, com.microfocus.awm.model.extension, are also available.

See Related Information at the end of this topic.

Application Server JCA support for Enterprise Server

Back to Top

This release provides support for:

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

AppMaster Builder

Back to Top

This release provides an additional AppMaster Builder Output preference, Use default APRPROG if none found, that creates a temporary APRPROG file during program generation in the case where no APRPROG file is found.

Code analysis

Back to Top

This release provides support for performing code analysis at the command line using Ant which enables the integration of code analysis in CI frameworks. Features include:

  • Support for performing code analysis at the command line using the project's .cobolBuild Ant script and specifying a target.
  • New Ant targets for code analysis - analyze and build.and.analyze. These enable you to only run analysis and produce analysis data or to build and produce build artifacts as well as analysis data.
  • New Micro Focus Ant task, analysis, for the .cobolBuild file. A parameter for this task enables you to specify whether the build fails or continues when code analysis results are received.
  • New parameters for code analysis for the cobol Ant task - analysisData, analysisDataDir.
  • New Ant type, ruleList, for the .cobolBuild file - enables you to specify the rules to execute.
  • Support for running analysis using a custom .cobolBuild file from outside of the project directory or the workspace.

See the Micro Focus Ant User Manual in the Micro Focus Infocenter for more details on the new task, types and parameters.

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

Code coverage

Back to Top

The code coverage reports are now integrated with the IDE and with the editor. Features include:

  • A new Code Coverage view (Eclipse) showing the statistics of what percentage of the code has executed.
  • Navigation from the Code Coverage view (Eclipse) to the missed and covered blocks in the editor.
  • Colorization in the editor of blocks that were executed (covered blocks) or not (missed blocks).

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

Compiler directives

Back to Top

The following Compiler directives contain new parameters in this release:

  • ILMAIN - you now specify the main entry point for the executable program, which can 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.

    This directive is now available for JVM COBOL.

  • OOCTRL - a new parameter, +/-A, as been added. Set this parameter to -A to allow ActiveX controls in your COBOL application to use classes and methods in the OLE class library. The default is +A, which does not allow it.

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

Data File Tools

Back to Top

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

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

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

Database Access - HCO for SQL Server

Back to Top

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

Database Access - Mainframe Batch Database Tools (MBDT)

Back to Top

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

This release provides MBDT support for DB2 LUW partitioned tables.

It also provides support for 32-bit MBDT for use with DB2 LUW on the following platforms:

  • IBM System p running AIX
  • x86-64 running SUSE Linux
  • x86-64 running Red Hat Linux

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

Database Access - SQL Option for DB2

Back to Top

This release provides the following new features:

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

Drag and Drop

Back to Top

  • The Drag and Drop command line utility contains new syntax that enables you to perform the following:
    • Retrieve current enqueue information for a PDS or QSAM data set; see Retrieving Enqueue Information.
    • Unlock resources that are currently locked under your user name; see Unlocking Resources.

Eclipse editor coding assistance

Back to Top

This release includes various improvements in the Content Assist support for COBOL in the following areas:

  • Native COBOL - support is now available for OCCURS statements
  • Managed COBOL - suggestions are now available in the working storage section and in the following scenarios:
    • Arithmetic expressions in method arguments
    • Casting variables and some expressions
    • Creating arrays using the TABLE OF expression and indexers
    • Generics
    • Implements and inherits
    • Javadoc comments are now displayed (Eclipse)
    • Type name filtering in constructs and attributes
    • Managed type headers, method heathers and index headers.
    • Nested types
    • SIZE OF expressions
    • String concatenations
    • TYPE OF constructs
    • Unqualified members access - using the SELF:: or SUPER:: syntax
  • Support for float literals has been enhanced.
  • Suggestions are now available for more COBOL verbs such as TRY and RAISE (in managed COBOL) and EXAMINE, INSPECT, SEARCH, GO TO, INITIALIZE, INVOKE, and UNLOCK (in native COBOL).
  • There are new IDE configuration settings for inserting suggestions and for case handling.

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

Enterprise COBOL 5.2

Back to Top

With the introduction of Enterprise COBOL 5.2, the following features are supported:

  • The VOLATILE keyword is supported within the data entry description; although, this is treated as documentary. It has also become a reserved word when under the ENTCOBOL dialect.
  • Format 2 of the SORT statement no longer treats the COLLATING SEQUENCE clause as documentary-only.
  • The SUPPRESS clause of the XML GENERATE statement has been enhanced.
  • The IBM z/OS JSON parser API, as documented for the IBM z/OS client web enablement toolkit.

Enterprise Server

Back to Top

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

File Handling

Back to Top

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

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

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

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

Back to Top

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

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

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

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

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

Library routines

Back to Top

The following library routines are new in this release:

  • CBL_CODESET_SET_MAPPING - enables you to change the codeset in effect.
  • CBL_RUNTIME_ERROR - forces an application to terminate with a run-time error condition.

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

Mainframe support and emulation

Back to Top

This release provides the following enhancements:
  • Enterprise Developer includes a new utility, MFJPTPCH, that emulates the IEBPTPCH mainframe utility for printing or punching datasets.
  • Support for using multiple catalog files (up to 32).
  • Support for storing the spool files in a location that differs from the location of the catalog file.
  • Enhanced support for searching the catalog using wildcards.

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

Micro Focus Unit Testing Framework

Back to Top

This release provides the following enhancements:

  • Updates to the test runner command line options:
    • Using the -testcases: option, you can now specify a list of test cases to execute.
    • The new -report:markdown option enables you to produce test reports in github style markdown format (.md).

      You can use various Third-Party utilities such as pandoc to convert .md files into HTML or PDF format.

  • Support for running test suites using dynamic metadata - you use an entry point in the test case and, when it is called during the preparation stage of the test case, you can change various fields exposed through mfunit.cpy to update the metadata of the test case.

    This is an alternative to specifying metadata for a test case in the text fixture file (.mfu).

  • Support is now available for creating and debugging test cases written in procedural managed COBOL (procedural code compiled as managed). The following new test runners are supplied:
    • mfurunil, for .NET COBOL code
    • mfurunj (Windows) and cobmfurunj (UNIX) for JVM COBOL code.

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

Managed COBOL syntax

Back to Top

The following enhancements have been made to the managed COBOL syntax:

  • A new command line utility, mfjarprogmap, is available to allow you to create the necessary Java property file when calling COBOL programs that have been compiled as part of a package.
  • You can now create generic iterators.
  • You can now use the Profiler utility to obtain detailed statistics on the run-time performance of managed COBOL applications.

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

Native COBOL Syntax

Back to Top

The following items are new features of the native COBOL syntax:

Class condition tests
New and updated class condition tests are available for DBCS, KANJI, and JAPANESE.

PL/I support

Back to Top

Support is available for the following features:

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

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

Rosetta Stone for COBOL, .NET and Java Developers

Back to Top

The product Help now includes a quick and easy to use syntax guide for developers who need to learn OO COBOL syntax when modernizing COBOL applications for the Java or .NET platforms. The guide includes side-by-side equivalent syntax for COBOL, C#, VB and Java.

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

SourceConnect

Back to Top

It is now possible to use SourceConnect to link to mainframe locations and to define mainframe datasets and members. The datasets and members then appear in your project's directory structure within the IDE.

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

z/Server

Back to Top

The z/Server Configuration Utility is now installed as part of Enterprise Server and is not a Technology Preview download. The user interface has been streamlined for the creation of a default working configuration.

Parent topic: New Features
Related reference
COBOL Editor
Code Analysis
Code Coverage
Comparison of COBOL with Other Managed Languages
Compiling JVM COBOL Applications
Compiler Directives
Data File Tools
IFileshare
JCL Editor
Library Routines
Mainframe Batch Database Tools (MBDT)
Micro Focus Unit Testing Framework
MFJPTPCH Utility
Setting Environment Variables in the Build Environment
SourceConnect
PL/I Editor
PL/I Programming


Features Added in Enterprise Developer 2.3

This release provides enhancements in the following areas:

  • Integration with the Eclipse IDE
  • General IDE enhancements - Eclipse
  • Application Workflow Modeller
  • Building JVM COBOL Projects Incrementally in Eclipse
  • COBOL editor in Eclipse
  • CICS Web services (Technology Preview)
  • Code analysis
  • Code coverage
  • Command line compilation and linkage
  • Compiler directives
  • Data File Structure command line utility
  • Data File Tools (Technology Preview)
  • Database access
  • Environment variables
  • File handling
  • File locking
  • iFileshare - Fileshare support under Enterprise Server (Technology Preview)
  • JCL parsing editor
  • Library routines
  • Mainframe compatibility
  • Managed COBOL syntax
  • Micro Focus FTP utility
  • Micro Focus Rumba
  • Micro Focus Unit Testing Framework
  • PL/I support
  • Preprocessors
  • Profiler
  • Remote connections
  • Remote PL/I applications
  • REST service interfaces
  • RPM UNIX installer
  • Single file support
  • Spooler housekeeping
  • Transaction class (TRANCLASS) support
  • Tunables
  • Updated run-time system
  • z/Server installation and configuration

Integration with the Eclipse IDE

Back to list

This release ships with Eclipse version 4.4.2.

Support for Eclipse versions 3.7 and 3.8 has been deprecated. This affects any applications that were created using an earlier version of Enterprise Developer that have a JVM COBOL part. Such applications must be rebuilt using Enterprise Developer 2.3 to avoid receiving errors during compilation or execution.

In addition, when Enterprise Developer is installed, you can optionally install the Enterprise Developer plugin in other instances of Eclipse installed on your machine (supported versions of Eclipse are 4.2, 4.3 and 4.4 for the 32-bit IDE).

See Related Information at the end of this topic.

General IDE enhancements - Eclipse

Back to list

  • The Variables view now shows the file status of an internal file name.
  • The Find All References and Go To Definition commands are now supported for JVM COBOL applications.
  • Support is provided for the SOCKS5 proxy server for debugger communication over SSL.

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

Application Workflow Manager

Back to list

  • IDE integration improvements:
    • The Team Developer perspective (TDP) is now the default perspective within Enterprise Developer. Some of the views supplied with TDP are:
      • a property view displaying main properties of a selected project entry.
      • a table view which displays project entries in a table format and allows column sorting.
      • a filter view which enables you to search projects and project entries based on specific search criteria.

      Using the Team Developer perspective for all kind of Enterprise Developer projects makes the User Interface fully customizable. As all COBOL and PLI projects are now based on an Application Workflow Manager model it is possible to adapt or extend the supplied functionality to the needs of the customers or to merge the functionality of various Application Workflow Manager application models.

      This supports an easy and seamless integration of all kind of Windows, Eclipse or mainframe tools necessary to support the client's development process.

      For example: combining SCM tools like Accurev, Starteam, SVN, Endevor, ChangeMan, SCLM with Micro Focus projects.

    • Enterprise Development Projects is provided as the Application Workflow Manager default application within the TDP. This application includes the functionality of the COBOL and the PL/I perspectives so that you can directly define and work with all kinds of Enterprise Developer projects using the TDP.
    • An Application Workflow Manager default configuration is used when starting Enterprise Developer. This configuration includes some initial settings and preconfigured file mappings which are visible in the file mappings view.

      You can extend the default configuration file with your preferred settings and deploy Enterprise Developer with some default configuration settings such as the correct predefined mainframe connection and file mappings which are used to map the your mainframe dataset naming standards to Eclipse file suffixes.

  • The Application Workflow Manager model has been extended by introducing function packages.

    The Application Workflow Manager tool types are now grouped by the following function packages:

    • Application Workflow Manager function package - supports various modelling of Application Workflow Manager-specific tool types such as "Edit Opener".
    • Micro Focus Project function package (not supported in Enterprise Developer Connect) - supports modelling of Enterprise Developer project-specific tool types such as "Single Compile".
    • Micro Focus Editor function package - supports modelling of editor-specific tool types such as "Reparse".
    • Micro Focus Enterprise Server function package (not supported in Enterprise Developer Connect) - supports modelling of Enterprise Server-specific tool types such as "Submit to ES".
    • Eclipse function package - supports a powerful set of tool types which enable modelling of standard Eclipse functions such as wizards, Eclipse projects, folders and file selection dialogs, icons and decorators, and the automatic synchronization of Eclipse project entries with Application Workflow Manager elements.
    • MVS function package (requires Enterprise Developer Connect or Enterprise Developer for z Systems) - supports the modelling of native MVS tool types which do not need an ISPF environment such as "Submit JCL", "Edit MVS file", and catalog services.
    • USS function package (requires Enterprise Developer Connect or Enterprise Developer for z Systems) - supports the modelling of USS tool types such as USS directory and file services, edit, and browse.
    • ISPF (requires Enterprise Developer Connect or Enterprise Developer for z Systems) - supports the modelling of tool types that require an ISPF environment such as calling REXX procedures in ISPF and ISPF dialog services.
    • OS function package - supports the modelling of Windows tool types such as a command executor and a dialog to select folders or files from the Windows file system.
    • RDz function package (requires RDz and Enterprise Developer Connect) - supports some RDz-specific tools.

    You can develop and install your own custom function packages that have extra modelling capabilities. For example, they can enable you to support new tool types, linked properties and icons, extend the Application Workflow Manager model editor with new tool-specific attributes, support templates when defining a new tool type, extending the validation rules within the model editor or synchronize external objects with Application Workflow Manager-modelled elements.

  • The Application Workflow Manager model now supports:
    • The modelling of password fields
    • A new attribute for enabling conditions that can be used to hide actions or dialog input fields if a condition is not true (instead of grey-out).
    • Modelling application actions - this enables you to model actions which are displayed on the context menu of the application entry.
    • An option to define bulk output parameters for a tool type during bulk processing.
  • Application Workflow Manager client improvements:
    • The MVS Explorer now supports some additional MVS dataset properties (for example - VSAM properties).
    • It is now possible to edit MVS files that contain non-displayable characters. If such files are loaded into the Eclipse editor, the non-displayable characters are preserved when saving the file back to z/OS.
    • An extension point is supplied by which a third party vendor or a customer can integrate a tool to provide a pass ticket for mainframe login.
    • The Team Developer Job view now includes a Submit Time column for jobs submitted from a modelled application.
    • The Team Developer Error View now supports local or network file paths. If an error feedback file is returned from any of the non-mainframe tools (such that are running in an Enterprise Server environment), the Team Developer Error view is now able to display the entries, which do not point to mainframe file.
    • The Team Developer Table view now includes a new Find function which can be used to hide non-matching table rows.
  • An improved integration into the mainframe source control management systems:
    • Endevor - the Application Workflow Manager bulk processing is implemented so that multiple elements can be processed in a single step. This also supports long element names (where the names are longer than eight characters).
    • ChangeMan - provides support for ZMF baseline versions and an improved user interface. You can now see some extra details such as date and time, or changes, and view any delta versions. An action to display the promotion history for a package is also available.
    • SCLM - provides an improved user interface. When expanding members in the tree view or displaying members in the table view, you receive a dialog that enables you to specify a member filter or to use a hierarchy search.
  • Application Workflow Manager remote precompiler:

    A support for the integration of mainframe COBOL precompilers is now available. This enables you to edit COBOL files in the precompiler format. Any errors that are reported refer to the lines of the precompiler source.

    This support is available for modelled applications in remote edit scenarios. Out-of-the box support is provided for all types of mainframe precompilers, as long as the standard ISPF comparison tool, which compares the pre-compiler input and output file, creates delta information that can be used in the COBOL editor. In case you are using some very complex precompilers, there is a special exit which can used to create more meaningful delta information.

    For customers who do not work with native COBOL on the mainframe but still need an additional mainframe precompiler that generates native COBOL code, such COBOL dialects are supported now when opening the file in the COBOL editor with remote edit. This enables you to use all the available powerful COBOL editor functions such as syntax checking, Content Assist, Outline view, Copybook Dependencies view with the COBOL code.

  • z/Explorer Improvements:
    • The MVS Explorer now supports some additional MVS dataset properties (for example - VSAM properties) and enables you to browse data files using the Classic Data File Tools editor.
    • zExplorer in the Remote Systems view now provides a USS (UNIX System Services) Explorer. This provides some additional USS mainframe server-side functionality (such as rename, copy, move, search or set permissions) that enables the Application Workflow Manager client to take advantage of the new USS Explorer UI.

      The USS Explorer enables you to define filters to explore the z/OS USS file system and work with USS directories and files.

    • Embedded HEX values in the source code are preserved after the code is downloaded from or uploaded to mainframe.
  • Security administration enhancements:
    • Calling ESF administration user exits - it is now possible to enable Security Manager "referential integrity" policies to be implemented and enforced using customizable ESF administration user exits. A sample exit is supplied.
    • A LISTREFERENCES ESF administration facility - enables you to determine any relationships among security objects and rules. This is available using the existing ESFADMIN command line tool and also using the new ESF LDAP Security Administration Web Interface.
    • An ESF LDAP Security Administrator Web Interface - a new modern, scalable web interface enables you to administer the Micro Focus Enterprise Developer user, user group and security resource data stored on third-party LDAP-based Security Managers. Faster and more functional than the existing MFDS-based interface, it also provides a dedicated interface for the security administrator role which does not interfere with Enterprise Server's runtime or region configuration operation.
    • New ESFADMIN commands - the new commands ADDMEMBER, DELMEMBER, ADDACE, DELACE and ALTACE help simplify the manipulation of the multi-valued attributes for group membership and ACLs.
    • "username substitution" MLDAP ESM resource access rule feature - the MLDAP ESM module has been updated with a new algorithm for identifying the best-matching resource-access rule and ACE for resource-access security checks. The new algorithm also provides an optional "username substitution" feature.

See Related Information at the end of this topic.

Building JVM COBOL projects incrementally

Back to list

To minimize the number of modules to compile when building JVM COBOL projects, Enterprise Developer now enables you to configure your projects so that they are built incrementally - the IDE only rebuilds the files that have changed.

To enable incremental builds for JVM COBOL applications that contain namespaces, check the Use incremental build (Technical preview feature) option on the project build configuration tab in the project's properties.

For JVM COBOL applications that do not contain namespaces, you can use the Use dynamic calls option available on the build configuration tab in the project's properties. When the project is built with this setting, calls to modules are resolved at run time rather than during compilation. This has the effect of not requiring every module to be compiled when rebuilding the application.

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

COBOL editor

Back to list

Content Assist support for COBOL includes various enhancements and is now also available in JVM COBOL:

  • Context sensitive proposal - Content Assist only shows proposal that are relevant for the position of the cursor in the code or for the type of project
  • Enhanced proposal lists - lists include any relevant COBOL verbs, clauses and words, copybooks, code templates, data items and section and paragraph names
  • Intelligent assistance with completing statements - when you have entered a COBOL verb, Content Assist shows proposals for the relevant clauses and identifiers that you can use to complete the statement.
  • Automatic completion for items - Content Assist automatically inserts single suggestions in the code.
  • Qualifying non-unique names - Content Assist qualifies data items whose names are not unique.
  • Configuration preferences for Content Assist - enable you to configure what suggestions appear in the completion lists, whether suggestions are added in insert or overwrite mode, and the case of the inserted words.
  • Code templates - code templates are now included in the Content Assist proposals.

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

CICS Web services (Technology Preview)

Back to list

Enterprise Server has been extended to provide a CICS Web Services capability compatible with the mainframe.

A new CICS Web Service wizard enables you to generate CICS Web service providers and requesters using either a CICS COBOL application or a WSDL file as input. This enables you to develop and test, including end-to-end testing, CICS Web Services for deployment to the mainframe.

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

Code analysis

Back to list

Enterprise Developer now offers more advanced code analysis features and enables you to run various analysis queries (rules and groups of rules called rule sets) against your code to ensure adherence to standards such as standards for coding or performance.

You can run analysis rules against programs in a project in the IDE at user request or you can run analysis rules at the end of a project's build.

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

Code coverage

Back to list

Enterprise Developer now provides support for code coverage of native COBOL applications directly from within the IDE where code coverage uses the Test Coverage functionality. You can produce code coverage reports for applications running in the COBOL run-time and for applications that run in Enterprise Server.

To produce reports, you need to enable code coverage in a project's, a build configuration's, or a file's properties, compile your application and then run your application with code coverage to produce the relevant reports. For applications that require an Enterprise Server instance, you start the enterprise server with code coverage.

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

Command line compilation and linkage

Back to list

When using the cbllink command to compile and link, there is a new -y option. Use this option to create an executable that includes support to be able to run on Windows XP and Windows Server 2003.

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

Compiler directives

Back to list

The following Compiler directives are new in this release:
EOF-1A
Treats a 0x1a character in the source file as the end of file.
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.
NLS-CURRENCY-LENGTH
Specifies the number of bytes to allocate for the currency symbol in a PIC field.
NULL-ESCAPE
Treats a 0x00 character in the source file as an escape character for other non-printable characters in the source code.

The following Compiler directives contain new parameters in this release:

DBSPACE
The new parameter "MIXED" extends the DBSPACE directive to be able to evaluate data items in programs that contain a mix of single-byte and double-byte strings.

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

Data File Structure command line utility

Back to list

The Data File Structure Command Line (DFSTRCL) utility is a DOS-based command line utility that enables you to create record layout (.str) files from COBOL debug information (.idy) files. You can use the utility to process a single .idy file or batch process up to 100 .idy files.

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

Data File Tools (Technology Preview)

Back to list

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

The Data File Tools (Technology Preview) is a new standalone text editor in which you can create and edit data files. By nature of it being a 'technology preview' product, it does not currently include all the functionality that was available in the previous version of Data File Tools - now referred to as Classic Data File Tools. If you require any of the functionality not provided in this version, you can still use the classic version by accessing it in the usual way.

To run Data File Tools (Technology Preview), type mfdatatools2 from Enterprise Developer's command prompt (Windows) or a terminal (UNIX).

To use the new editor directly from the Eclipse IDE, use the Open with option on the shortcut menu when selecting a data file or structure file, and select Data File Tools. Eclipse remembers the last tool used for a particular file type, and so will use Data File Tools (Technology Preview) until you select a different editor.

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

Database access

Back to list

This release provides the following enhancements to database access:

COBSQL
This release provides:
  • Selection and configuration of the Oracle Pro*COBOL preprocessor for compiling COBSQL applications in project properties on the SQL Preprocessor tab and in the build configuration settings.
  • Support for COBOL directives SOURCEFORMAT=TERMINAL and SOURCEFORMAT=VARIABLE for Pro*COBOL applications.
HCO for DB2 LUW
This release provides:
  • GUI versions of data migration tooling (Windows platforms)
  • A new tool that enables you to bind or rebind all packages. See BindAll Packages Tool for details.
  • Support for MFHCO mode across all platforms by default via the new HCO (NOHCO) DB2 compiler directive option. See the HCO DB2 compiler directive option topic for details.
  • A new DB2 compiler directive option, OPTPER (NOOPTPER), that enhances performance for CHARSET EBCDIC processing. See the OPTPER DB2 compiler directive option topic for details.
  • A new DB2 directive option, BINDDIR, which specifies an alternative directory in which to write the DBRM file created during compilation. You can set BINDDIR from the command line or specify it in your project properties. See the BINDDIR DB2 compiler directive option topic, and the Binding topic for details.
  • 64-bit support for PL/I on appropriate platforms. See Additional Software Requirements on Windows and Additional Software Requirements on UNIX for details.
HCO for SQL Server
This release provides:
  • Support for the DATA-CHANGE-TABLE-REFERENCE clause.
  • Context Help is now provided for:
    • Options for HCO for SQL Server tools
    • Each tool in the HCO for SQL Server user interface
OpenESQL
Date/Time Processing
This release provides streamlined datetime processing for ODBC and JDBC.
OpenESQL Assistant
OpenESQL Assistant Options are now set via the Eclipse IDE from Window > Preferences > Micro Focus > Database > OpenESQL Assistant (applies to Windows environments only).
Performance
This release includes a new SQL compiler directive option, OPTPER (NOOPTPER), that enhances performance for CHARSET EBCDIC processing. See the OPTPER SQL compiler directive option topic for details.
PL/I
This version provides 64-bit support for PL/I on appropriate platforms. See Additional Software Requirements on Windows or Additional Software Requirements on UNIX for details.
PostgreSQL
In this release, PostgreSQL 9.4 has been tested with OpenESQL and OpenESQL Assistant using the following PostgreSQL software:
Server software
PostgreSQL EnterpriseDB version 9.4.4
Client software
  • psqlODBC driver version 09.03.04.00
  • JDBC41 PostgreSQL driver version 9.4-1201
PostgreSQL 9.4 has been tested with OpenESQL and OpenESQL Assistant on the following Windows platforms:
  • Windows 32-bit
  • Windows 64-bit
PostgreSQL 9.4 has been tested with OpenESQL on the following UNIX platforms:
  • X86-64 running Red Hat Linux, 32- and 64-bit
  • X86-64 running SuSE Linux, 32- and 64-bit
Note: Micro Focus provides compatibility for PostgreSQL but does not directly contribute to or support the PostgreSQL open source project. Any issues relating to PostgreSQL functionality should be addressed through an open source support vendor.
SQL Server
This release provides support for the SQL Server OUTPUT clause.
Mainframe Batch Database Tools (Technology Preview)
Windows only. This release includes mainframe batch database tools (MBDT) that provide the following functionality for Oracle, DB2 LUW, and SQL Server agnostically, as well as specifically for HCO for SQL Server:
  • DSNTEP2
  • DSNUTILB LOAD
  • DSNUTILB UNLOAD
  • 32-bit and 64-bit support
  • New batch configuration utility
SQL Option for DB2
This release provides the following enhancements:
  • Initial support for XML data type in XDB Server, in addition to XDB Link
  • Better performance on table expressions and joins using literal strings
  • JDBC driver supports result set processing
  • SQL Wizard provides better LOB data type support
  • z/OS DB2 version 10:
    • Extended support for implicit casting
    • Greater timestamp precision for applications
    • Support for TIMESTAMP WITH TIME ZONE (applies to Windows environments only)
XA Switch Modules
In this release, the XA interface has been redesigned to provide:
  • Consistent look and feel for SQL Server, DB2, and Oracle user personalization
  • Consistent look and feel for both RM dynamic and static registration (SQL Server, DB2, Oracle, generic one-phase commit for ODBC)
  • Additional support for two instances of the same switch module using Web Services applications via the new XAID compiler directive
  • Using a specified XA resource only with batch applications executing under Enterprise Server

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

Environment variables

Back to list

The following new environment variables are available:

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

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

File handling

Back to list

This release contains the following new configuration options:

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

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

File locking

Back to list

In versions prior to Enterprise Developer 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.

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

iFileshare - Fileshare support under Enterprise Server (Technology Preview)

Back to list

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

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

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

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

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

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

JCL parsing editor

Back to list

A new parsing JCL editor provides assistance with writing JCL code to users who are not experienced mainframe programmers. This is especially useful when using the Enterprise Developer Connect to edit source files on a remote mainframe machine. Features include:

  • Block selection - use the button from the toolbar to toggle the mode.
  • Content assist for JCL constructs.
  • Configurable background syntax parsing
  • Configuration settings for the editor - you can hide or show the horizontal ruler, turn on or off visible lines for the margins, and configure the syntax coloring and the smart edit mode.
  • Folding support - enables you to collapse and expand blocks of code.
  • Horizontal ruler
  • Locate definitions
  • Margins
  • Outline view - shows a structure of the procedure and structure declarations within a program. Clicking on an item in the Outline view positions the cursor on that item in the code and vice versa.
  • Renumber and Unnumber - support for renumbering and unnumbering lines of code.
  • Submit JCL command directly from the editor.
  • Smart edit mode - defines the word wrapping behavior when breaking lines or around margins, moving the cursor using the Home and End keys.
  • Syntax colorization
  • Syntax error reporting - uses red squiggles to denote errors in the code.
  • Task creation - inserting a TODO or a FIXME in a comment in the code automatically creates a task that appears in the Task view.
  • Templates for the most common JCL constructs.
Note: The following limitations apply:
  • There is no support for VSE dialect statements in the editor. JES2 and JES3 are supported.
  • PROCS is not supported in the editor so that it is not possible to read in libraries of JCL routines from a PDS.

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

Library routines

Back to list

The following library routines are new in this release:

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.

The following library routines contain new parameters in this release:

CBL_LOCATE_FILE
You can now specify a file name that is a null-terminating string, which has resulted in three new values available for the user-mode parameter.

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

Mainframe compatibility

Back to list

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

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

Managed COBOL syntax

Back to list

The following enhancements have been made to the managed COBOL syntax:

  • The TYPE OF type-name[ANY...] syntax enables you to obtain the System.Type (.NET) or java.lang.Class (JVM) object for a generic class, interface, or delegate.
  • The self:: or super:: syntax is no longer required to access inherited data within a subclass.
  • The ATTRIBUTE-ID syntax enables you to define new attribute types, which can be used in various contexts.

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

Micro Focus FTP utility

Back to list

A new utility, Micro Focus FTP (MFFTP), provides FTP support for JCL-enabled enterprise servers within Micro Focus Enterprise Server. The MFFTP utility provides a support mechanism for batch processes that takes advantage of FTP from JCL on the mainframe.

Support is available for:
  • Fixed Block (FB) files
  • Variable Block (VB) files
  • Generation Data Group (GDG) files
  • Configuring third party FTP clients
  • Input and output temporary file handling
  • Configuring the end-of-line markers
  • Configuring the error codes
  • Configuring the text messages

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

Micro Focus Rumba

Back to list

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

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

Micro Focus Unit Testing Framework

Back to list

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability, but it is not intended for production use and 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. During the preview, you are encouraged to share your feedback and experiences via the Micro Focus community forum - http://community.microfocus.com/microfocus/).

The Micro Focus Unit Testing Framework is an xUnit style testing framework, available from the command line, for procedural COBOL applications.

It includes much of the architecture you would expect in an xUnit framework. The test runner is a 32- or 64-bit executable that you run from an Enterprise Developer command or shell prompt. A test fixture or suite is a COBOL program compiled to .dll (Windows) or .so (UNIX) that can include the setup, the test case code, and the teardown associated with the test case.

Test results 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 on the command line to produce reports in JUnit format.

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

PL/I support

Back to list

This release provides the following enhancements to PL/I support in Enterprise Developer:

  • 64-bit support - Enterprise Developer provides a full 64-bit environment for developing PL/I applications on Windows, Solaris(SPARC), Red Hat Linux, and SUSE Linux to enable you to take advantage of any 64-bit features such as 64-bit address space or interact with 64-bit relational databases when modernizing your applications.
  • Data types - support has been added for GRAPHIC data type, including GRAPHIC, GRAPHIC VARYING, GRAPHIC VARYING BIGENDIAN, Gx and G constants. This enables you use GRAPHIC data within your applications to migrate to Open PL/I running under Enterprise Server.
  • PL/I debugger:
    • The cwgui debugger is no longer available. You can now use the cw_java debugger which provides a richer graphical debugging experience.
    • The debugger has been enhanced to support the evaluation of the following built-in functions: CENTER, CENTERLEFT, CENTERRIGHT, HEX, LEFT, LOWERCASE, MAXLENGTH, PACKAGENAME, RIGHT, REVERSE, ROUND, SEARCH, SEARCHR, TALLY, and UPPERCASE.
  • New -systemmvs, -systemims, and -systemcics link options - the mfplx and linker logic has been enhanced to decouple the -cics, -ims, and -mvs flags from the link options. If you have PL/I CICS EXCI applications, this enables you to compile and link your applications more easily to run under the control of JCL or IMS.

    In addition, the macro preprocessor SYSTEM() built-in function will now correctly return the value of the "SYSTEM" in effect (for example: IMS, CICS or MVS).

  • The Open PL/I macro preprocessor now supports the following:
    • The Open PL/I macro statement ANSWER. This enables the migration of PL/I code which uses ANSWER in its PL/I macros.
    • The use of arrays of FIXED and CHAR macro variables. This simplifies the migration and maintenance of PL/I Macro preprocessor code that uses variable arrays.
  • IBM Structure Alignment (-zalign) - the Open PL/I compiler has been enhanced to provide an option which causes ALIGNED structures to map data elements at the same offsets as IBM's compiler. This facilitates the migration of applications and data to Open PL/I running under the control of Enterprise Server.

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

Preprocessors

Back to list

Support has been added in the IDE for enabling and using multiple preprocessors with your projects.

A new page, Additional Preprocessors, has been added to the project's and the files' properties of native COBOL applications to enable you to choose one or more preprocessors to use when building your application and to specify their order of execution.

New reporting capability is now available for user preprocessors: resp-main code 18 indicates that a 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.

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

Profiler

Back to list

Enterprise Developer now provides support for Profiler for native COBOL applications directly from within the IDE. To produce reports, you need to:

  1. Enable Profiler in the COBOL property page for a project, a build configuration, or a file.
  2. Compile your application to apply the changes.
  3. Create a run configuration that has Profiler enabled.
  4. Run your application with Profiler to produce the relevant reports.

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

Remote connections

Back to list

This release provides the following enhancements:

  • An improved diagnostic tooling to help determine connection problems - enhancements are available for both the client and the server installations.
  • It is now possible to specify the Remote System Explorer (RSE) type of connections to create remote mainframe COBOL and PL/I projects. This is to cater for scenarios when it is not possible to use SAMBA or NFS connections within your environment.
    Note: The following features and utilities are not supported when remote projects use the RSE connection type:
    • The file layout editor and the file editor in the Classic Data File Tools and Data File Tools (Technology Preview) utilities.
    • The BMS compiler and painter.
    • The IMS layout editor and the IMS database editor.
    • Mainframe Assembler.
  • Changing the type of a remote connection - it is now possible to change the type of the remote connection from RSE to NFS and vice versa using the Remote Settings for remote projects.

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

Remote PL/I applications

Back to list

Support is provided in Eclipse for editing, compiling and debugging of 32-bit and 64-bit PL/I applications running on remote UNIX and Linux machines.

All PL/I editor features available for local projects are present in the editor for remote PL/I applications. Improvements have been made to the syntax recognition of the PL/I editor parser.

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

REST service interfaces

Back to list

RESTful service interfaces utilizing JSON as the media type in request and response messages are now supported using the Interface Mapping Toolkit. This enables you to extend COBOL applications using modern transport payloads and protocols.

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

RPM UNIX installer

Back to list

In addition to its proprietary installer for installing Enterprise Developer on UNIX and Linux, Micro Focus provides a standard RPM installer for installing Enterprise Developer 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 Enterprise Developer supports all the RPM functionality.

For instructions on how to install using the RPM installer, refer to the Installation section in your product help.

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

Single file support

Back to list

The recommended way to work with files within Enterprise Developer is to include them in a project. For situations where you might want to quickly open edit a single file, Enterprise Developer now provides support for native COBOL files in the IDE when the file is not opened as part of a project. There is limited support for the IDE editing, compiling and debugging features as full support requires a project file.

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

Spooler housekeeping

Back to list

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

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

Transaction class (TRANCLASS) support

Back to list

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

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

Tunables

Back to list

This release of Enterprise Developer contains the following new tunables:

putenv_interface
Provides backward compatibility for UNIX systems in which the operating system's putenv() function is required when setting environment variables.
strict_file_locking
Enables a new, more reliable method of file locking for UNIX systems. See File Locking for more information.

This release of Enterprise Developer contains the following updates to tunables:

default_cancel_mode
A new parameter, and default, has been introduced for this tunable; see default_cancel_mode for more information.
subsystem_cancel_mode
A new parameter has been introduced for this tunable; see subsystem_cancel_mode for more information.

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

Updated run-time system

Back to list

Enterprise Server has been updated to provide 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 previous version of Enterprise Developer, you should ensure that the executable is rebuilt and packaged with the new run-time system. This does not affect mainframe subsystem projects deployed to Enterprise Developer. You can rebuild from the IDE or the command line.

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

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

z/Server installation and configuration

Back to list
  • XML configuration files - a single XML configuration file replaces the five separate configuration files that were used in previous releases. This helps reduce the complexity of the z/Server installation and configuration. An XML schema is supplied and enforced. The input parameter values for type and range are checked at execution time and can also be externally verified using standard or custom tooling before they are applied.
  • z/Server Configuration Utility (Technical Preview only) - this release provides a technical preview of a new web-based z/Server Configuration Utility.
    Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.
  • The Application Workflow Manager now requires that you have both z/Server and Mainframe Access Server (MFA) installed.

Parent topic: New Features
Related concepts
BindAll Packages Tool
Binding
Micro Focus Unit Testing Framework
Related reference
Attribute specification
BINDDIR
COBOL Properties
Code Analysis
Code Coverage in the IDE
Compiling JVM COBOL
Content Assist and COBOL
Data File Structure Command Line Utility
Data File Tools (Technology Preview)
File Handler Configuration Options
HCO
iFileshare ESMAC page
JCL Editor
JCL-Specific Environment Variables
Micro Focus FTP Utility MFFTP
OPTPER
Profiler in the IDE
RPM Installer
Runtime Tunables
Specifying the Preprocessors' Stacking Order
Spooler Housekeeping
strict_file_locking
To create a COBOL remote project
To create a remote mainframe project
To change the connection type of a remote project
Tutorial: REST Service Interface
Types and Conversion (with conrefs)
Views in the Debug Perspective


Features Added in Enterprise Developer 2.2 Update 2

This release provides enhancements in the following areas:

Eclipse

Enterprise Developer provides the following new functionality and improvements:

  • Support for Eclipse 4.2 and 4.3 - Enterprise Developer ships with Eclipse 3.8 but also supports Eclipse 4.2 and 4.3 (the 32-bit IDE only). To use Enterprise Developer with a newer version of Eclipse, you need to install Enterprise Developer first and then use the installeclipseplugins.bat script in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\installer (UNIX). See Installing into other instances of Eclipse for more details.
  • Remote JVM COBOL projects - this release provides enhanced support for remote JVM COBOL projects.
  • Remote project connections - the diagnosis tool for remote connection issues has been improved. There is now a client-side diagnosis tool and a server-side diagnosis tool for diagnosing connection problems to remote projects and connections to your Micro Focus Enterprise Developer UNIX Components. You should run both tools for a complete diagnosis.

Character Set Enhancements

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

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

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

Code Analysis

This release of Enterprise Developer provides Dead Code analysis for COBOL programs that enables you to find unreferenced items or any piece of code that can't be reached .

AppMaster Builder

The AppMaster Builder Database View and maintenance support (known as Data Views) is now provided within the Eclipse framework for Enterprise Developer, rather than relying on invoking the AMB database view interface that was part of Mainframe Express Enterprise Edition. You must install the AMB Eclipse plug-in to be able to use this feature.

Data Views enable you to create and maintain database views, as well as add and compile PSB and DBD sources in a COBOL project, all while working within the Eclipse framework.

Database Access

The following new features are available in database access support:

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

Enterprise COBOL 5.1 compatibility

There have been a number of enhancements to make this version of Enterprise Developer more compatible with Enterprise COBOL 5.1.

Note: These enhancements are available under both DIALECT(MF) and DIALECT(ENTCOBOL).
  • The following phrases have been added to the XML GENERATE statement:
    • NAME
    • SUPPRESS
    • TYPE
  • The following intrinsic functions have been added:
    • ULENGTH
    • UPOS
    • USUBSTR
    • USUPPLEMENTARY
    • UVALID
    • UWIDTH
  • A number of reserved and context-sensitive reserved words have been added; see the topics Reserved Words Table and Context-sensitive Words Table for complete lists.

External Call Interface (ECI)

Enhancements to the ECI include:

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

External Security Facility (ESF)

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

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

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

IMS Connect

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

PL/I General Enhancements

Enhancements are provided in the following areas:

  • Attributes - the PL/I DECLARE statement now supports the OPTIONAL attribute as part of the parameter-descriptor list or as an attribute in a parameter declaration. This provides an improved functionality and a greater language compatibility for customers looking to migrate applications from z/OS environments.
  • Built-in functions - the PL/I Compiler and run-time system now support the PRESENT and OMITTED built-in functions which provides an improved functionality and a greater language compatibility if you are looking to migrate applications from z/OS environments.
  • CodeWatch - this release includes the following enhancements:
    • CodeWatch is now supported in native 64-bit environments which ensures that the CodeWatch debugger runs properly in native 64-bit mode. This enables the PL/I debugger to take advantage of faster speeds and to debug larger programs which have access to larger amounts of storage.
    • Notifications for the CodeWatch conditions - you can use the command line and the UI to turn notifications on or off for all of the currently documented PL/I conditions. The use of notifications enables you to investigate the state of programs and optionally set breakpoints before continuing program execution.
  • Compound operators - the PL/I macro preprocessor now supports the compound operators += , -=, *=, and /= within macro assignment statements.
  • Error handling - you can now use the EXEC CICS HANDLE ABEND check which provides a consistent error handling technique for PL/I programs running under CICS that is consistent with error handling on the mainframe. EXEC CICS HANDLE ABEND determines error handling for programs running under CICS. Conditions detected by CICS cause an abend if established using EXEC CICS HANDLE ABEND, and PL/I ON units do not get control. If EXEC CICS HANDLE ABEND is not established, CICS defines that the action taken will be as defined by CICS, which normally leads to a transaction abend.
  • PL/I data structures - this release provides enhanced support for PL/I data structures in the Data File Tools. You can now easily generate a PL/I structure map (.str) from within the IDE, and the Data File Tools can then use to generate a formatted layout for a PL/I data file. This enables you to see what is in each field within a PL/I Data File Record, and to modify the records in a logical way without having to know the offset, length and raw format of the data item.

PL/I Editor Enhancements

This release provides a new and improved PL/I editor within Eclipse. Features include:

  • Configurable background syntax parsing.
  • Syntax error reporting - uses red squiggles to denote errors in the code.
  • Configuration settings for the editor - you can hide or show the horizontal ruler, turn on or off visible lines for the margins (at columns 2 and 72 for Mainframe Subsystem projects, and only at column 72 for native projects), and configure the syntax coloring and the smart edit mode.
  • Smart edit mode - defines the word wrapping behavior when breaking lines or around margins, moving the cursor using the Home and End keys.
  • Folding - support for collapsing and expanding regions for procedures and blocks within procedures.
  • Content Assist - provides assistance with inserting PL/I keywords, variables and syntax templates.
  • Syntax templates for the most commonly used PL/I statements.
  • Block selection - use the button from the toolbar to toggle the mode.
  • Breadcrumbs navigation - enables you to quickly navigate between source programs and the dependent include files.
  • Outline view - shows a structure of the procedure and structure declarations within a program. Clicking on an item in the Outline view positions the cursor on that item in the code and vice versa.
  • Include Dependency View - shows where in the source file's structure the INCLUDE statements appear, and which include files they reference.
  • Opening include files directly from the editor using F3.
  • Task creation - inserting a TODO or a FIXME in a comment in the code automatically creates a task that appears in the Task view.

Rumba 9.2

This release of Enterprise Developer includes Micro Focus Rumba 9.2 which you can optionally install as part of the setup process. The license for Enterprise Developer will license all components of Rumba.

Transaction classes (Technology Preview)

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

Tunables

This release includes the following new tunable:

  • reduce_java_signals - specifies the options that are passed to a JVM when mixing Java and COBOL.
Parent topic: New Features
Related reference
Alphabetical list of environment variables
AppMaster Builder
Code Analysis
Context-sensitive Words Table
Definitions of Functions
ECI Java Interface
Installing and Licensing Micro Focus Rumba
Server-side connection tests
Client-side connection tests
Reduce_java_signals
Reserved words table
Running Applications in a TN3270 Mainframe Display
The XML GENERATE statement


Features Added in Enterprise Developer 2.2 Update 1

This release provides enhancements in the following areas:

Micro Focus Heartbleed Update

This product includes OpenSSL version 1.0.2n.

AppMaster Builder

This release provides updated AppMaster Builder support that integrates more fully into the Eclipse IDE. In addition, the following enhancements have been added:
  • Code generation and compilation in an Eclipse COBOL project
  • Enhanced Program Painter
  • Enhanced Job Queue

Assembler Support

This release provides Assembler support from within the Eclipse IDE on Windows platforms. Features include:

  • Support for creating Assembler programs (.mlc extension), macro files (.mac or .cpy extensions) or Assembler linker files (.lin) from within the IDE.
  • Support for building Assembler programs and for linking Assembler linker files from within the IDE. You can choose to exclude certain files from the build.
  • Assembler editors for Assembler and macro files - includes content assist for reserved words and colorization.
  • Support for using Ant for building .asm, .mlc and .cap files and for linking .lin files.
  • IDE support for configuring the Assembler compiler and linker options on project, build configuration and file levels.
  • Configuring the macro paths.

Btrieve Support

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

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

COBOL Source Information

The Quick Browse option is now available as a context menu command in the editor.

Compare and Synchronization Monitor

Note: This feature is only available in a Windows environment.

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

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

Compiler Directives

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

Database Access

The following new features have been added as part of database access support:

HCO for DB2 LUW
  • Support added for DB2 LUW version 10.5.
  • Enhanced RETURN-CODE processing.
  • The HCO DDL processor now accepts column names with a length greater than 18 characters.
  • The HCO Import Data tool now processes CLOB data less than 32K in size.
  • The HCO Import Data tool can now convert DSNTIAUL import files to delimited format, enabling the actual import to be done by DB2 LUW IMPORT and LOAD utilities. This is done using the new SAVEDEL and CHARDEL parameters.
HCO for SQL Server (HCOSS)
  • Support for the mainframe SET CURRENT SQLID statement.
  • Support for the mainframe LEFT and RIGHT scalar functions.
  • Data Migration tools now support the mainframe ALIAS and SYNONYM objects.
OpenESQL
  • Enhanced internationalization support for UNICODE, DBCS and MBCS.
  • Enhanced GET DIAGNOSTICS statement support.
  • Enhanced LOB support for CLOB, BLOB and DBCLOB data types.
  • Enhanced IDE support for OPTION directives.
  • Now provides support for the creation of save points and rolling back to save points.
XA Switch Modules
Restriction: This feature applies only when the Enterprise Server feature is enabled.
  • New two-phase commit module for SQL Server based on Microsoft's XA switch. This provides support for xa_recover.
  • Support for DB2 LUW version 10.5.
  • Support for Oracle version 12.1.

Eclipse IDE

Assigning memory to Linkage Section items
If the debugger steps on a line with an unassigned linkage item (for example, if you are debugging only a part of your application and no memory has been allocated to that linkage item), debugging terminates. To assign linkage to that data item and continue debugging, you need to select the data item, right-click it and click Inspect COBOL. When prompted, confirm and assign a value to the data item. Alternatively, to assign linkage, you can right-click the data item in the Variables view and click Change Value.
Debugging Windows Services
It is now possible to debug Windows services. You must be logged on to the console of the computer running the service and can debug either using just-in-time debugging and a CBL_DEBUGBREAK call, or using library routines and a "COBOL Wait for Application Attachment" debug session having added a call to CBL_DEBUGBREAK or CBL_DEBUG_START to the application.
Indicating that a file is a copybook or a COBOL program
In COBOL Explorer, you can now use two new file context menu commands to indicate that a COBOL program is a copybook (Transform Program to Copybook) and that a copybook is a COBOL program (Transform Copybook to Program). You may need to use these in situations when you imported existing COBOL source code in the Eclipse IDE and some of the files were incorrectly identified as either a copybook or a COBOL program.

Enterprise Server Integration in the IDE

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

Enterprise Server MQ-IMS Bridge

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

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

Environment Variables

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

Fileshare Recovery

Recovery of Fileshare data files has been enhanced.

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

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

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

Line Numbering for COBOL Programs

This release provides options for auto-inserting or removing line numbers in source files open the editor. Features include:

  • COBOL numbering - line numbers are inserted in the sequence area of the code (columns 1 - 6), starting by default at 000100 at the first line, incrementing by 100 by default.

    Micro Focus recommends that you use COBOL numbering only if your files are in fixed or variable source format.

  • Standard numbering - line numbers are inserted immediately to the right of area B, in columns 73 - 80, starting by default at 00000100 at the first line, incrementing by 100 by default.

    Micro Focus recommends that you use Standard numbering only if your files are in fixed format.

  • The Renumber and Unnumber commands available from the context menu in the editor.

Local Catalog

From within Server Explorer in the IDE, you can add one or more local catalogs, and then use them in conjunction with Drag and Drop to drag down data set items from your mainframe, edit them and then move them back to the mainframe or to your testing environment.

IMTK

You can now use the Interface Mapping Toolkit to create Web Services and Java Interfaces for remote COBOL projects.

Working with the Mainframe

This release includes the “Launch ISPF” functionality as a technical preview. This feature is supported only under z/OS 1.13.

Mainframe Emulation

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

Mainframe Subsystem

New editors
Enterprise Developer now provides special editors for REXX, TSO CLIST and Easytrieve programs. The editors include colorization and content assistance. Syntax checking is not available.

Managed COBOL

Enterprise Developer now provides support for Java managed beans (MBean) in JVM COBOL code that enable you to manage and monitor RunUnits, and to identify certain issues such as leaks and long-running RunUnits.

  • You can enable an MBean only for a particular RunUnit level or for all RunUnits you create.
  • You can view and use MBeans from programs such as Oracle's Java Mission Control or JConsole.
  • MBeans include the LogicalRunUnitCount and LiveRunUnitCount attributes that enable a visual indication of how many RunUnits are live. If the values of these two attributes are different, this might indicate some issues.

This release also includes the following tutorials for JVM COBOL:

Deploying JVM COBOL to an Application Server
Using some ready-made sample projects, this tutorial guides you through implementing your JVM COBOL code into an Enterprise JavaBean (EJB), then deploying it to a JBoss application server. Instructions are also included on how to deploy the application to WebSphere and WebLogic application servers.

Managed COBOL Syntax

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

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

PL/I

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

  • Support for new built-in functions

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

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

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

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

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

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

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

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

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

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

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

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

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

  • Support for the –initcall Compiler directive.

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

  • Support for the “F” option in PLIDUMP.

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

  • Early Adopter support for PL/I data structures Data File Tools.

    In the IDE, you can now generate a PL/I structure map (.str) which can be utilized by the Data File Tools utility to generate a formatted layout for a PL/I Data File. The PL/I data structure must be compiled in advance with the -adt Compiler directive. This enables you to see what is in each field within a PL/I data file record, and to modify them in a logical way without having to know the offset, length and raw format of the data item.

  • Support for PL/I debugger notification for ON Unit invocation.

    You can now request that the debugger stops when a PL/I ON Unit is about to be triggered. This enables you to locate the ON Unit, establish appropriate breakpoints within the ON Unit and determine the cause of the ON Unit being triggered.

  • Support for PL/I debugger notifications for the load of shared libraries and .dll files.

    You can now request that the debugger issues a notification when a shared object or a .dll file has been dynamically loaded. This enables you to stop a program when a dynamic program has been loaded and to establish the appropriate breakpoints, watch lists, etc.

  • Alternative Index Performance Improvements for the CASSPOOL command.
  • Support of the SHAREOPTIONS property in a VSAM cluster.
  • Support for setting directives automatically for PL/I files.

    In Eclipse, click Window > Preferences > Micro Focus > PL/I > Directives Determination.

  • A new page in the project and file properties enables you to set SQL directives on PL/I source files.

Preprocessors

A guide for third-party vendors and administrators showing how to integrate additional preprocessors with Enterprise Developer is now available in the product help in the General Reference > Integrated Preprocessor Interface section.

Project and Item Templates

Support is now available for using existing projects and files as custom templates to create new projects and files. You create and configure projects that include the files and settings you would like to use as templates.

Remote Connections

Enterprise Developer now provides a new connection type, Micro Focus DevHub using SSH, that uses a Secure Shell daemon process to launch a server on the remote host.

You can use this type of connection when the UNIX machine you are connecting to uses LDAP authentication which is not supported by the DevHub daemon.

Using this connection also means you do not need to run the DevHub daemon process with root privileges. It also gives you greater flexibility in setting environment variables needed for building or debugging on the remote server.

Rumba Integration with Eclipse

This release provides enhanced integration with the Micro Focus Rumba application for running and debugging Mainframe Subsystem applications that require a TN3270 emulator to run. You can now configure Eclipse to launch a Rumba mainframe display embedded in the IDE or a mainframe session of Rumba Desktop.

Run-time Launch Configuration Files

Note: This feature is only supported in a Windows environment.

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

Terminfo Files

The following terminfo files have been added:

  • ansi80x25 - this is based on the old ansi file. A newer version of ansi exists in this release that has no function key support, which is consistent with ansi terminfo files on various other UNIX platforms. If you currently use ansi and require function key support, you should instead set the TERM environment variable to ansi80x25 to continue previous behavior.
  • xterm-color and kterm-color - these are now available on all UNIX platforms - previously, they were only available on Linux.
  • aixterm-old (AIX systems only) - this has similar capabilities to the AIX OS terminfo file of the same name. It differs from the existing aixterm file, because it has no line drawing capability. Line drawing is only possible with aixterm if it is displayed on an appropriate display (X server).
  • vt220-w - this is the wide (132-column) version of the vt220 file, and is based on the vt100-w file. For more information, see Wide Terminal Mode in the documentation referenced at the bottom of this section.

There have been a number of additions and fixes to existing terminfo files; refer to the Terminfo Database and Terminal Devices section of the documentation for full details.

There have also been a number of terminfo files that have been removed; refer to the Backward Compatibility section for a complete list.

Parent topic: New Features
Related reference
AppMaster Builder
Assembler Support
Btrieve
Using preprocessors
Running Applications in a TN3270 Mainframe Display
Integrating Preprocessors into Enterprise Developer
Backward Compatibility with Earlier Micro Focus Products
Terminfo Database and Terminal Devices
ILPARAMS
INIT-BY-TYPE
Run-time Launch Configuration Files
strictvsam
Using SMS MGMT Classes
Compare and Synchronize Monitor
Fileshare Recovery Utility
Local catalog
Deploying JVM COBOL to an Application Server
Using Java Managed Beans to Manage and Monitor COBOL Applications
Debugging Windows Services
To launch a server on the remote host using a Secure Shell daemon process


Features Added in Enterprise Developer 2.2

COBOL copybook project types

You can use the COBOL Copybook and Remote COBOL Copybook project types to create project that hold several copybook files. In these projects you can only create new or add existing .cpy and .cbl files but files with the .cbl extension are treated as copybooks.

You can then add these projects as dependent projects to the build path of other projects that include the source files. Copybook projects are not compiled, thus saving processing time and resources.

COBOL Source Information (CSI)

COBOL Source Information (CSI) provides a quick and easy way of providing you with information about your program when you are working on it. You enter a query in the Quick Browse dialog box and CSI returns the results of the query in the Search view.

Compiler directives

The following Compiler directives are new:

ACU-UNDERSCORE
This directive treats underscores in COBOL words as hyphens.
ILSHOWPERFORMOVERLAP
This managed COBOL-only directive generates a warning when an overlapping PERFORM range is detected in the program.
ILEXPONENTIATION
This managed COBOL-only directive enables you to optimize exponential arithmetic operations by specifying the calculation method used.
EXITPROGRAM
This directive determines how the EXIT PROGRAM statement is executed.

The following Compiler directives have changed:

CHANGE-MESSAGE
The scope of this directive has been widened to allow you to change the severity of different types of error messages, not just syntax checking messages.
DIALECT"RM"
DIALECT"RM" now sets PERFORM-TYPE"RM". If you recompile an application that uses DIALECT"RM", the behavior may change for nested PERFORM statements. If that is the case, explicitly set PERFORM-TYPE"MF" after DIALECT"RM" to continue with the previous behavior.
HIDE-MESSAGE
The scope of this directive has been widened to allow you to hide different types of error messages, not just syntax checking messages.
PRESERVECASE
This directive now defaults to PRESERVECASE when compiling native COBOL; managed COBOL compilation already defaults to PRESERVECASE. This results in externally visible identifiers preserving their case instead of being converted to uppercase.

Consolidated copybook paths dialog box

You now set the paths for COBOL, IMS, and PL/I copybooks (where available for the project type) in a single Dependency Paths page of the project properties dialog box.

Consolidated Tracing Facility

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

CTF for JVM COBOL applications

CTF tracing is now supported in JVM COBOL applications.

Emitters

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

Emitter properties and variables

The following support has been added to existing emitters.

The following property has been added to the BINFILE emitter:

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

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

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

Documentation

The following guide is now available, among other updates to the product help for this release:

Object-Oriented Programming
A guide that provides a basic introduction to Object-Oriented Programming (OOP) for COBOL developers, An Introduction to Object-Oriented Programming for COBOL Developers, is now available from the Product Documentation section on the Micro Focus SupportLine Web site - click here to download it.

Eclipse 3.8

Enterprise Developer is shipped with Eclipse 3.8, and can also be installed in existing instances of Eclipse 3.7 and 3.8.

Enhanced Enterprise Server integration with the IDE

This release provides the following enhancements:

  • Creating a server from a template directly from the Server Explorer window.
  • Automatically starting the associated server and enabling dynamic debugging for it when you start debugging.
  • Showing the spool and the catalog of the associated server from the context menu for the project in COBOL Explorer.
  • Debugging applications using a temporary server when the project has no association with any of the existing enterprise servers.

File Handling

New features include:

  • The DATEDIFF function as part of the DFSORT emulation. There are some limitations of its use in Enterprise Developer.
  • Converting and editing Vision and RM/COBOL indexed data files using the Data File tools.
  • Access to data files (either sequential or indexed) through AcuServer.
  • Access to Vision and RM/COBOL indexed data files through Enterprise Server.

HCO for SQL Server (HCOSS)

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

IMTK

Improved IMTK usability
The Interface Mapping Toolkit (IMTK) perspective and associated views and commands have been removed and the functionality integrated into the COBOL perspective.
EJB transactions
Enterprise Developer now supports EJB services that execute as a transaction.

IMS

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

Java Web services support

Enterprise Developer supports the development, compilation, debugging, and deployment of JVM COBOL web archives to JVM servlet APIs and common Java Enterprise Edition (JEE) application servers.

JVM COBOL Web services support

Support for calling COBOL programs from JSPs and servlets has been expanded to offer more COBOL features, improved IDE tools, and more runtime support.

Mainframe Access Drag and Drop

This release provides the integrated Drag and Drop utility - based on the traditional standalone version of Drag and Drop, you can now transfer files to and from the mainframe from within the IDE using the Micro Focus Mainframe Explorer. This version also enables you to view and edit mainframe files.

The standalone version can no longer be invoked using the command line command mfdasmx2; use the command mfdasmx instead.

Mainframe snippets

A number of code snippets for inserting EXEC CICS and EXEC DLI statements in the code are now available for Mainframe Subsystem applications. You can insert code snippets from the context menu in the editor or by pressing Control + Space and selecting a keyword. You can modify the keywords for the mainframe snippets in the IDE from Window > Preferences > Micro Focus > COBOL > Editor > Templates.

Mainframe Subsystem Support

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

Managed COBOL

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

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

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

PL/I Parsing Editor (Early Adopter Program) - available with Enterprise Developer 2.2 HotFix 3 (January 2014)

With the Enterprise Developer Connect and Enterprise Developer licensing options, you now receive a new and enhanced PL/I Parsing Editor alongside the standard PL/I editor. The new editor is designed for editing remote mainframe programs and enables you to perform syntax check of the code before it is compiled on the mainframe.

To invoke the new editor to edit your sources – in the IDE, right-click a PL/I program in your project, and click Open With > PL/I Parsing Editor (Early Adopter).

Features of the PL/I Parsing Editor include:

  • Colorization - you can configure the print margins, syntax colorization or the code snippet templates to use in the editor in the IDE from Windows > Preferences > Micro Focus > Early Adopter Program > PL/I Parser Editor.
  • Syntax checking support – use the PL/I local syntax check context menu command to start a syntax check of the PL/I sources.
  • Navigation in the PL/I sources using:
    • The PL/I jump to procedure (or F10) context menu command on CALL statements in the code to navigate to the place in the code where the procedure in the CALL statement is defined.
    • The Outline view shows the structure of the PL/I source that you are currently editing.

The PL/I Parsing editor is a work-in-progress and might change in future releases of the product.

PL/I support

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

Problems view

The Problems view now has a 'Program' column that displays the name of the program in which the problem occurred. Click this column heading to sort the errors by program.

If the column is not present in the view by default, you can add it through the Configure Columns dialog box in the View Menu.

Quickfix for missing copybooks

When paths containing copybooks are added to a project, they are not automatically added to the copypath. This can cause confusion when a copybook is in the project but the program is not compiling. The Eclipse Quickfix feature now hints how to resolve the problem, and offers a solution (which is to add the path onto the copypath).

SQL

Eclipse IDE
SQL tooling has been integrated into the Eclipse IDE:
  • HCO for SQL Server tools
  • OpenESQL Assistant
  • Options for the level of background parsing for DB2, XDB, and OpenESQL statements
EXEC SQL GET DIAGNOSTICS Statement
Enables you to get diagnostic information for the last OpenESQL statement executed.
External Compiler Modules (ECM)
ECM support has been expanded and includes OpenESQL, HCO for DB2 LUW, and XDB.
OPTION compiler directive option
New parameters have been added to handle additional host variable types.
SQL Option for DB2
Several updates have been made to the XDB tools:
  • Initial delivery of z/OS DB2 10 emulation engine:
    • A new XDB location version has been implemented
    • Support has been added for TIMESTAMP with TIME ZONE data type
  • Online analytical processing (OLAP) specifications support has been added for XDB V9 and V10 emulation
  • XDB Link has been updated to support the DRDA Version 5 architecture using SQL Application Manager DDM Level 10
XA switch modules
This release includes support for XA switch modules that enable CICS- and JES-initiated transactions to run under Microsoft SQL Server using different user credentials than those specified within the XA open string.

Viewing copybook dependencies

By expanding a source file node in COBOL Explorer, you can see a list of all copybooks referenced in the source code, and nested within them any other copybooks referenced by those copybooks.

You can also use the Copybook Dependency view to show where in the source file's structure the COPY statements appear, and which copybooks they reference.

Click a copybook reference in the Copybook Dependency view to open the file containing the associated COPY statement at the appropriate line.

Double-click a copybook reference in COBOL Explorer or Copybook Dependency view to open the copybook file.

XML Extensions

You can now use XML Extensions in your managed COBOL projects.

Parent topic: New Features
Related reference
ACU-UNDERSCORE
CHANGE-MESSAGE
Configuring Access to Data Files Through AcuServer
Delegates and Events
DIALECT
EXITPROGRAM
HIDE-MESSAGE
ILEXPONENTIATION
ILSHOWPERFORMOVERLAP
The Consolidated Tracing Facility
PRESERVECASE
Procedure Division Header
Viewing Copybooks in Context


Features Added in Enterprise Developer 2.1 Update 1

Note: There are differences between the variants of Enterprise Developer you might have installed. Enterprise Developer Personal Edition provides a development environment that supports analysis, editing and syntax checking of COBOL and mainframe programs outside of the mainframe environment. It does not, however, support off-mainframe debugging, unit testing, or building of projects. To build, debug, and execute the demonstration application, you need Enterprise Developer.

Compiler Directives

You can now set SQL and PL/I-related Compiler directives and their values more easily, using a grid in a project’s Properties dialog box.

Enterprise Server

The following new features and enhancements are available:

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

HCO for DB2 LUW

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

HCO for SQL Server

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

Mainframe Compatibility

Enterprise Developer for z Systems is compatible with IBM System zEC12 mainframe hardware and later.

OpenESQL Assistant

Support for generation of PL/I SQL queries and copybooks.

Oracle OCI

Support for all PL/I platforms.

PL/I Support

This release of Enterprise Developer includes support for developing, compiling and debugging PL/I applications, including PL/I-specific project types, file categories, and editors.

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

SQL Option for DB2

  • Background parsing support
  • Enhanced XDB engine LOB support
  • UTF-8 support for client-side expressions
  • Support for indices on expressions

Debugging

You can create a breakpoint for any program in the workspace that your application uses by clicking Run > Add Program Breakpoint, or clicking the [image] icon in the Breakpoints view, and entering the name of the file.

Parent topic: New Features


Features Added in Enterprise Developer 2.1

Note: There are differences between the variants of Enterprise Developer you might have installed. Enterprise Developer Personal Edition provides a development environment that supports analysis, editing and syntax checking of COBOL and mainframe programs outside of the mainframe environment. It does not, however, support off-mainframe debugging, unit testing, or building of projects. To build, debug, and execute the demonstration application, you need Enterprise Developer.

Enterprise Developer Enhancements

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

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

Compiler directives

The following new Compiler directives are now available:

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

The following Compiler directive has changed:

  • DATAMAP - Two new parameters allow you to display either the address or offset values for data items in your program.

Enterprise Server

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

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

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

    Where:

    [repository type]
    • 1 = file:///
    • 5 = XML
    [server name]
    * = export all servers
    <opts>
    • D = (default) do not delete or overwrite any existing repository contents at specified location
    • O = delete and overwrite any existing repository contents at specified location
    • S = export server and security manager configuration
    <user id> and <password>
    the MFDS credentials required if administration access is restricted
  • The new –g option is used to allow XML format repository import. The syntax is as follows:
    mfds -g [repository type] [repository address] <opts> <user id> <password>
    [repository type]
    5 = XML
    <opts>
    Not currently in use.
  • XML repository import - extends the MFDS repository export to XML and import from XML introduced in Enterprise Developer 2.0 to UNIX platforms. This allows administrators to export, modify and then reimport Enterprise Server instance configuration data in XML format.

Mainframe Access

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

HCO for SQL Server

HCOSS now supports rowset cursors.

IMS support

  • Mainframe projects contain categories for IMS resources (.dbd, .mfs, and .psb files), in which files with these extensions are automatically put when you add them to the project. Each file type has its own editor that colorizes tokens to aid development. Building a project containing these file types automatically generates DBD. PSB, and MFS files.
  • Non-discardable message exit (early release) - provides you with functionality present in Mainframe IMS that allows messages destined for an abended IMS application program to be deleted, put on the suspend queue, requeued to the original transaction, or routed to an alternate destination.
  • IMS printer support (early release) - IMS application LU1, LU3 MFS, or LTERM output can now be spooled to printers using TCP/IP protocols. You now have the ability to print IMS output on local or networked printers.
    Note: Print spool API support is not available. Users are responsible for associating printers with a user or a department.

Just-in-time debugging

Eclipse now supports "Just-in-time" debugging: when a run-time error occurs, or an application calls CBL_DEBUGBREAK, Eclipse starts automatically with the debugger attached to the failed process.

OpenESQL

JDBC
JDBC has been enhanced to support two new directives:
JNDI
Enables you to specify a JNDI class that looks up connection strings.
JNDIENC
Enables applications to use the JNDI Environment Naming Context (ENC) when looking up JDBC data source names using JNDI.
ODBC
Added support for a generic one-phase commit for ODBC XA switch module.
SQL Compiler Directive Options
OpenESQL has been enhanced to support the the following new SQL compiler directive options:
DATE
Controls the reformatting of date values in output parameters and in input parameter character host variables when DETECTDATE is also specified.
TIME
Controls the reformatting of date values in output parameters and in input parameter character host variables when DETECTDATE is also used.
DATEDELIM
Specifies a single character as the delimiter between the year, month, and day components to override the default delimiter determined by the HCOSS DIALECT or DATE directive specification.
TIMEDELIM
Specifies a single character as the delimiter between the hour, minute, and second components to override the default delimiter determined by the HCOSS DIALECT or TIME directive specification.
TSTAMPSEP
Specifies a single character as the separator between the date and time parts of timestamp and date/time data.
OpenESQL Assistant
OESQL Assistant now supports updateable cursors.
SQL Server
We now support Microsoft SQL Server 2012.

Open PL/I

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

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

Tutorials

The following tutorial is now available in the Getting Started section in your product help:

Tutorial: Assembler
AACT is a sample CICS 3270 transaction that comprises several Assembler programs and a single BMS map, and uses the resource definitions in the file dfhdrdat. This tutorial walks you through the steps required to implement and test the AACT transaction.
Managing the Mainframe in Eclipse
This tutorial shows you how to develop and debug applications on or off the Mainframe. The tutorial is based on the Bankdemo sample application.

UNIX and Linux platforms support

Micro Focus Enterprise Developer UNIX Components enables you connect to remote UNIX machines and use them to create, edit, and debug all project types. The following systems are supported:

  • POWER running AIX 6.1 TL7 SP5/7.1 TL1 SP5 - 32/64-bit
  • x86-64 running Red Hat Linux 5.5/5.8/5.9/6.3/6.4, Oracle Linux 6.3 with Red Hat Kernel compatibility mode, Oracle Linux 6.3 with Unbreakable Enterprise Kernel - 32/64-bit
  • SPARC running Solaris 10/11/11.1 - 32/64-bit
  • x86-64 running SUSE SLES 11/11 SP2/11 SP3 - 32/64-bit
  • System Z running SUSE SLES 11 SP2/11 SP3 - 32/64-bit
  • System Z running Red Hat Linux 6.2/6.3- 32/64-bit
  • HP IA 11.31 - 32/64-bit

Working with mainframes

Enterprise Developer for z Systems now includes direct access to the mainframe from within Eclipse. This functionality provides the following features:

Direct access to the mainframe
The mainframe environment is integrated directly into the Eclipse IDE. Developers can use the Remote Systems Explorer view to the mainframe and directly access it with the JES Explorer and MVS Explorer views to:
  • Browse and edit their data sets
  • Edit and Submit jobs for execution
  • Run ISPF dialogs
  • Review Job output on the spool or catalog
Remote mainframe development
Developers now have full control of development activities directly on the mainframe. This means from within a single IDE you can:
  • Integrate directly to mainframe source control systems to check out, check in, and promote members directly to your personal mainframe area.
  • Use smart editing capabilities such as - Background Parsing to detect syntax errors as they are entered; Content Assist when writing COBOL code; Source Outline view and navigation when editing programs that are on the mainframe.
  • Syntax check and compile applications directly on the mainframe while the error messages are output to the Eclipse editor which ensures compilation issues can be quickly viewed and resolved.
  • Unit test applications on the mainframe, and even run debug sessions directly from the Eclipse IDE if you have the debugging tools on the mainframe.
Easy customization
Enterprise Developer for z Systems includes a unique component called Workflow Manager, a graphical modeling tool that allows you to customize quickly the Enterprise Developer Eclipse-based User Interface and directly integrate tools, such as source control, either directly on the mainframe, or on the workstation. This means that your development environment is fully customizable and you can integrate familiar development workflow in Eclipse. Workflow Manager means:
  • Complete integration with major source control systems out-of-the-box becomes possible.
  • You can create predefined models to support different development processes. These can be managed and deployed centrally.
  • There is no requirement to develop Eclipse Java plugins in order to extend the IDE User Interface which puts you in control.
  • Comprehensive and deep integration becomes affordable.
  • Developer acceptance is high and productivity gains are realized.

General Enhancements

JVM auto-runtime

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

Managed code enhancements

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

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

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

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

Specifying Properties
In previous versions of the products, properties declared using the PROPERTY keyword on a data item were generated as final properties. Starting with this release, they are generated as virtual properties by default. In order to make the properties final, you need to specify the word FINAL following PROPERTY. This change may affect the generation of Proxy classes, for example, if you are using WCF.
Parent topic: New Features
Related concepts
Compiled File Types
Delegates and Events
IBM External Call Interface (ECI)
Starting the debugger automatically using just-in-time debugging
Getting Started


Features Added in Enterprise Developer 2.0

Eclipse as the Integrated Development Environment

Eclipse is the core IDE for maintaining and developing applications that have been migrated from the mainframe and that still use CICS and JCL. You use Eclipse to develop, compile as native or managed COBOL code, and debug your applications. The Eclipse editor has been extended in a number of ways to enhance its support for COBOL, including standard Eclipse features for program navigation are exploited for COBOL applications.

Features Include:

Latest Version of the Eclipse IDE
Enterprise Developer supports the latest version of Eclipse - Eclipse 3.7.1 Indigo.
COBOL-Aware Eclipse Editor
Includes various features such as syntax colorization and background parsing, COBOL comment structures, column block marking. The editor displays the COBOL margins and utilizes the Eclipse program navigation features in COBOL such as the Outline view, Find References and in-place copybook expansion.

The Eclipse debugger fully supports COBOL in data queries, watch windows etc. and control over the program execution flow both for native code and COBOL JVM.

COBOL Explorer View
Provides a logical view of the files in your projects and allows you to navigate around COBOL projects in a more useful and convenient way than the default Eclipse Navigator view.
COBOL File Search
Makes it easier to find certain files within your projects.
Copybook Context
Enables you to choose in which program context a copybook displays.
Auto-completion and Content Assist
The IDE includes auto-completion and content assist editing features.
Automatic Directives Detection and Setting
The IDE automatically determines and sets the COBOL dialect, and the CICS and SQL directives on local or remote native COBOL projects. You can also start a directives scan from within COBOL Explorer - select Determine Directives from the context menu for the projects or the COBOL source files. This triggers a scan to determine the COBOL dialect, the CICS and SQL settings, and sets them as Compiler directives on a file or project level respectively. At the end of the scan, you view the results and choose to apply the changes.
COBOL Projects
Supports creating, debugging and running of COBOL projects in the IDE. You can set the charset of new projects to ASCII or EBCDIC, and also set the COBOL dialect (for example, EntCOBOL, VSC2, OSVS). The following project types are available:
  • Mainframe Subsystem projects - enable you to build Mainframe Subsystem applications and provide support for BMS, JCL and Macro files.
    Note: This release does not provide support for IMS applications.
  • COBOL projects - enable you to create native COBOL applications.
  • COBOL JVM projects - enable you to create managed COBOL applications which compile to JVM byte code (.class files) so that they can be run on a JVM.
Compiling Single Files
You can compile individual COBOL source files without rebuilding your entire project. Build Automatically on the Project menu must be turned off.
Support for Editing .DAT Files
You can edit .dat files in a text editor in the IDE, or using the Micro Focus Data File Tools utility.
Note: This release does not provide support for IMS applications.
Enterprise Server integrated into the IDE
Features include:
  • A Server Explorer view that enables you to manage the instances of Enterprise Server on multiple hosts.
  • Direct access to the Enterprise Server Administration page from within Server Explorer.
  • Ability to associate a project with an Enterprise Server instance.
  • Submission of JCL to selected Enterprise Server instance.
  • A debug launch configuration for Enterprise Server debugging. This enables you to debug programs started from CICS or JCL sessions on an Enterprise Server instance.
Mainframe Subsystem Support in the Eclipse IDE
Features Include:
  • MSS-specfic project template, including BMS, JCL and Macro file support:
    • COBOL Explorer view offers additional categories for BMS, JCL and Macro files.
    • The COBOL Search feature recognises BMS, JCL and Macro file types
  • Automatic determination of CICS COBOL programs.
  • Automatic determination of the COBOL dialects.
  • Ability to set CICS and BMS settings on project, configuration, or on file level.
  • Support for CICS ECM.
  • Compilation of CICS COBOL programs.
  • Editing BMS mapsets - in a text editor in the IDE with Content Assist, or using the external Micro Focus BMS Painter tool.
  • Outline View of BMS mapsets.
  • Compilation of BMS files and error reporting location.
  • Editing of JCL files in the text editor with Content Assist.

Enterprise Server

Features include:

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

Mainframe Access (MFA) Client Capabilities

Enterprise Developer and Enterprise Test Server provide Mainframe Access (MFA) client capabilities.

When migrating applications, this ensures source and data can be transferred from the mainframe and projects can be setup more efficiently within the Enterprise Developer environment to make it easier to demonstrate rapid progress to key stake holders. Once projects are set up, the synchronization with mainframe artifacts can be automated to deliver significant gains in efficiency.

When rehosting testing workload to Windows, this provides:

  • Seamless but secure access to mainframe application source code and data simplifies set up and deployment of the Test Server platform.
  • Significantly increases the breadth of applications that can be tested within the Enterprise Test Server environment as jobs, programs and utilities that cannot be rehosted to Windows can be remotely accessed on the mainframe.
  • Allows source synchronization with mainframe source control systems. Test Server can then be configured to automatically compile changes as they are checked into source libraries. This provides early exposure to test teams performing smoke or regression testing.
  • Data can continue to reside on the mainframe. COBOL programs running under Test Server can directly access mainframe files. This not only allows multiple test levels against different subsets of data, it means that sensitive or archive data can remain in position.
  • MFA Synchronisation and Control Monitor (aka "Syncmon") – synchronises selected source components between mainframe hosted source and a Windows development or test environment
  • Automatic Synchronise and Compile to automatically compile modules after source code synchronisation.
  • Remote Job (JCL) Step Execution to enable execution of jobs on mainframe that cannot be rehosted to Windows
  • Mainframe Call Generator – enables remote execution of mainframe programs that cannot be re-hosted to Windows.
  • SourceConnect – allows direct access to source hosted on mainframe.
  • DataConnect – allows COBOL file access to data files hosted on mainframe.

Service Interfaces Using the IMTK

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

The IMTK enables you to create an interface between a legacy COBOL application running on an ESI as a service, such as a Web service or Java service, and a non-COBOL client, such as a Web service client or a JSP client. The interface you create is called a service interface. In your service interface, you can expose as much or as little of the original legacy application functionality as you choose. Because legacy applications often perform a wide variety of functions, the creation of a service interface enables you to limit your end users to access only the functions they need.

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

  • Java Interface
  • Web Service from WSDL
  • Web Service from request-response JSON schemas
  • RESTful Web Service from JSON schema
Attention: To deploy or generate a client for a Java Interface, you must install and configure the Java JDK and a Java application server. See the Application Server JCA support for Enterprise Server section in the Additional Software Requirements on Windows topic.

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

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

Support for the PL/I Language

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

    Features include:

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

SQL

The SQL technology that was present in previous products is seamlessly integrated within the Eclipse development environment. When you develop COBOL SQL applications in the new IDE, you can use the same development environment to extend and modernize your COBOL assets.

Features include:

  • Improved IDE integration for all SQL technologies - now supports handling of deprecated and removed directives. Also supports filtering of the choices offered to the user by product type, project type, and platform
  • SQL Option for DB2 technology that provides mainframe DB2 compatibility with its own DBMS, tooling and COBOL preprocessor
  • HCO for DB2 LUW technology that provides mainframe DB2 compatibility with its own tooling and COBOL preprocessor
  • HCO for SQL Server (HCOSS) - HCOSS makes it simple to migrate both COBOL code and data from mainframe DB2 to SQL Server.
Parent topic: New Features
Related concepts
Assembler Support
Related information
Managed COBOL Programming
Converting Projects to Eclipse Projects
Using Eclipse for COBOL Development
Configuration and Administration
Mainframe Subsystem Support Developer Introduction
Developing SQL Applications


Significant Changes in Behavior or Usage

This section describes significant changes in behavior or usage in the current and past releases of Enterprise Developer for Eclipse. 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 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 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).

  • CICS
  • Compiling
  • Enterprise Server security
  • Executables may require relinking or recompiling
  • HCO for SQL Server (HCOSS)
  • IMTK runtime configuration
  • Application Server JCA Support for Enterprise Server
  • JES restart behavior
  • Test Coverage results

CICS

Starting with version 4.0 Patch Update 2, all applications that use WEB CONVERSE or WEB SEND SESSTOKEN explicitly with the AUTHENTICATE, BASICAUTH, or NONE options, and that do not use a URIMAP that specifies the AUTHENTICATE attribute, must be recompiled. (This does not affect applications that use a URIMAP that specifies the AUTHENTICATE attribute.)

Compiling

The Compiler now produces an E level message - COBCH1888 Typedef is defined differently in another external program - if different external programs have conflicting definitions of the same typedef name. To restore the previous behavior, where the earlier definition was ignored, use the directive HIDEMESSAGE"1888".

Enterprise Server security

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

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

An example of the new resource class and resource definitions can be found in the es_default_ldap_msuser.ldf (Windows), or es_default_ldap_unix.ldf (UNIX) file, which is located in the bin (Windows), or etc (UNIX) sub-directory of your product directory.

Executables may require relinking or recompiling

Note: Windows-only.

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

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

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

HCO for SQL Server (HCOSS)

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

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

IMTK runtime configuration

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

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

JES restart behavior

The following changes have been made to the MF_UCC11 environment variable:

  • The default behavior of MF_UCC11=Y has changed, in that DISP=NEW is changed to DISP=MOD only when a job is restarted (not when first run).
  • A new option, MF_UCC11=YA, reverts to the previous behavior of changing DISP=NEW to DISP=MOD even when the job is first run.

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

  • CICS
  • JES-enabled enterprise servers
  • Compatibility AddPack
  • Compiler Directives
  • JES security - the PHYSFILE resource class
  • Managed COBOL
  • OpenESQL
  • Reserved words

CICS

Starting with version 3.0 update 11, all applications that use WEB CONVERSE or WEB SEND SESSTOKEN explicitly with the AUTHENTICATE, BASICAUTH, or NONE options, and that do not use a URIMAP that specifies the AUTHENTICATE attribute, must be recompiled. (This does not affect applications that use a URIMAP that specifies the AUTHENTICATE attribute.)

JES-enabled enterprise servers

Back to the list

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

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

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

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

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

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

To run the spool conversion utility

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

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

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

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

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

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

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

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

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

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

Reverting to the previous JES spool repository

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

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

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

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

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

Exporting the spool files to Enterprise Server for .NET

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

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

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

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

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

Compatibility AddPack for Visual COBOL

Back to the list

Compatibility AddPack for Visual COBOL is now deprecated and will not be available with release 3.0 and later.

The Dialog System GUI and run-time components and Dialog System Character Mode (on Windows and UNIX) which were part of the AddPack are now installed as part of Enterprise Developer for Visual Studio. The run-time components are installed as part of Enterprise Server. These are only included for backward compatibility and Micro Focus does not recommend that you use them for new development.

The other components which were part of the AddPack, the Character-Based Data File Editor, CSBIND and Screens, will be available upon request from Micro Focus SupportLine.

Compiler Directives

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

JES security - the PHYSFILE resource class

Back to the list

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

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

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

Managed COBOL

Back to the list

References to types within an assembly other than mscorlib need to be explicitly referenced. You can achieve this by using the ILREF Compiler directive.

Previously, in certain circumstances, the Compiler would allow access to types within the System.dll assembly without the need for an ILREF"System" directive.

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

  • AppMaster Builder
  • Compiler
  • Enterprise Server
  • IDE
  • JCL Support
  • Micro Focus Directory Server
  • Monitoring and Management
  • PL/I Support
  • Run-Time System

AppMaster Builder

Back to the list

  • To correct a problem with generating programs when no APRPROG member is present, a new Output Generation preference has been added that, when enabled, creates a temporary APSPROG member at generation time if none is found. In addition, a new customizable APRPROG template is available to enable customization of the temporary APSPROG member.

    2849347 (1103014)

Compiler

Back to the list

  • In previous product releases, the scoping rules for nested programs (as defined in ANS85 COBOL), were not enforced in managed COBOL (.NET and JVM). This meant that, in cases where program A contained programs B1 and B2, and programs B1 and B2 contained C1 and C2, respectively, it was possible to call program C2 from C1, for example. The lack of scoping rules also meant that it was not possible for B1 and B2 both to contain a program with the same name.

    This product release enforces the correct ANS85 scoping rules for nested programs, including COMMON programs, and makes it possible to have multiple programs with the same name at different levels of the nesting hierarchy. In this way, the behavior in managed COBOL is now compatible with the behavior of native COBOL programs.

  • Replacing a partial token no longer causes the second part of the token to appear on a new line. This could happen if the new text was larger than the text being replaced.

    2869185 (1105763)

  • There is no longer a problem opening an RM/COBOL indexed file when the program has a RECORD CONTAINS n CHARACTERS clause and there are record descriptions with lengths less than n. This situation previously caused a 39 error on the OPEN (other than OPEN OUTPUT) because there was a mismatch in the minimum record length.

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.

IDE

Back to the list

  • This update modifies any existing connections defined in an Eclipse workspace. If the connections had any non-default values, those values could revert to their original default setting. After installing this release, before you use any remote connections for the first time, you need to check the settings and amend them as necessary.

    2852872 (1103699)

Micro Focus Directory Server

Back to the list

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

    2816871 (1099564)

Monitoring and Management

Back to the list

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

    2854207 (1103659)

JCL Support

Back to the list

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

    2852302 (1103304)

PL/I Support

Back to the list

  • A problem with PUT STRING when compiled with the -bigendian option in effect has been fixed. Note that when upgrading your application from a version of Enterprise Developer earlier than 2.3 Update 2, you must recompile any program using PUT STRING.

    2857374 (1104039)

  • Previously, if using the -incafter option of the macro preprocessor to infuse a %INCLUDE with macro logic, you were required to schedule a second macro pass to preprocess the contents of the %INCLUDE. This is no longer necessary and the macro logic will be preprocessed on the first macro pass as if it was part of the original source.
  • Previously, if writing output to a CTLASA (PRINT) file with the optional LINE(x) parameter having a value of x that was less than the current line, PL/I did not generate ASA Control characters to end of page and emit the output on the first line of the new page. This no longer occurs.

    2871278 (1106114)

  • Previously, if SIGPIPE was triggered when a PL/I program was in the callstack, then PL/I error handling got control and processed the ERROR. This no longer occurs. Users who rely upon catching SIGPIPE can re-enable it by adding a call to cobpostsighandler() to their code to turn it back on.

    2859980 (1104399)

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

  • Application Workflow Modeller
  • AppMaster Builder
  • Communications Server
  • Data Tools
  • Editor Writing Assistance
  • Enterprise Server
  • IBM Language Environment for OS/390 & VM Support
  • IDE
  • JCL Support
  • Run-Time System
  • SQL: OpenESQL
  • SQL Option for DB2

Application Workflow Modeller

Back to the list

  • Tools used in the File_Descriptor_Has_Action relationship now support Resource Processing. This means tools defined within a dialog table action can modify properties of the selected table rows.

    2835290 (1101493)

  • The standard Enterprise Developer project model now contains additional context menu actions under "Open With..." for IMS DBD and PSP files to open either the DBD, the PSP or the IMS Database editors.
  • You no longer receive a REXX error when recompiling a component from a baseline.

AppMaster Builder

Back to the list

  • A new checkbox, "Use File Tailoring for Dataview generation", has now been added to the Database View dialog box in the AppMaster Builder (AMB) preferences. When checked, the Database Views will be generated using File Tailoring files and the AMB Builder Server.

    2820090 (1099354)

Communications Server

Back to the list

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

Data Tools

Back to the list

  • When filtering a data file, if there is no valid temporary directory set, you are prompted to set one using the option in the Preferences dialog box.
  • The editor no longer allows you to open a file if the file size (without header size) is not a multiple of the record size on disk; an error is produced instead.
  • The level numbers displayed in a record layout correspond to the levels used in the .idy file that was used when the structure file was created.

Editor Writing Assistance

Back to the list

  • IntelliSense (Visual Studio) or Content Assist (Eclipse) suggestions are no longer offered if you start typing numbers and automatic triggering of suggestions is enabled.

Enterprise Server

Back to the list

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

    2839272 (1101672)

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

    2835112 (1101201)

IBM Language Environment for OS/390 & VM Support

Back to the list

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

    2841220 (1101955)

IDE

Back to the list

  • When compiling to multiple executables from the command line, you must specify the -logger parameter to enable the correct log to be output to the console.

    2848855 (1102932)

  • For a file added to a JVM COBOL project by adding the folder that stores the file (using the Source tab on the Micro Focus > JVM Build Path > Source page in the projects' properties), there is now a new context-menu command, Copy to Output Directory, in COBOL Explorer. Choosing this command on a file triggers a build of the project and copies the file into the output directory.

    2699374 (1094326)

JCL Support

Back to the list

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

    2834206 (1101079)

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

    2698700 (1094266)

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

    2831984 (1100883)

Run-Time System

Back to the list

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

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

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

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

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

    2838689 (1101685)

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

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

    • IS [NOT] KANJI

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

    • IS [NOT] JAPANESE

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

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

    2812895 (1098401)

SQL: OpenESQL

Back to the list

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

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

    2843818 (1102248)

SQL Option for DB2

Back to the list

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

    2830383 (1100609)

Changes in Behavior in Release 2.3

Back to Top

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

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

  • AppMaster Builder
  • Assembler Support
  • CAS Security
  • CAS XA Switch modules
  • Compiler
  • Data Tools
  • Discontinued Support for cwgui
  • File Handling
  • File Locking
  • IDE
  • J2EE Connector
  • JCL Support
  • Mainframe Access
  • MF Server Administrator (GUI)
  • PL/I Support
  • SQL - HCO for SQL Server
  • Updated Run-Time System

AppMaster Builder

Back to the list

  • Loading PSBs sometimes caused an error that prevented the building of DDI symbols required for generation.

    2813119 (1098471)

Assembler Support

Back to the list

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

    2806239 (1097738)

CAS Security

Back to the list

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

    2807531 (1097783)

CAS XA Switch modules

Back to the list

  • The XA switch modules now support dynamic registration.

    2682101 (1092325)

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

    2664675 (1091082)

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

    2786397 (1095265)

Compiler

Back to the list

  • For native COBOL, the size limit of the Data Division now stands at 2GB -1.

    2796076 (1096384)

  • COBDATA has no effect on compilation. The output of the Compiler is the same location regardless of whether COBDATA is set.

    Previously, it was not possible to specify sign(EBCDIC) with sign-fixup, host-num-move or with host-num-compare. This combination is now supported in native COBOL but remains invalid for managed COBOL code. This is applicable to version 2.2 U2 HotFix 10 onwards.

    2824577 (1100823)

Data Tools

Back to the list

  • DFCONV now returns the correct return-code; previously, it would always return 0.

Discontinued support for cwgui

Back to the list

  • The cwgui debugger is no longer available. You can now use the cw_java debugger which provides a richer graphical debugging experience.

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

IDE

Back to the list

  • Enterprise Developer for Eclipse now ships with Eclipse 4.4.2 (Luna). A consequence of this is that if your application also contains JVM COBOL code that was built with a version of Enterprise Developer prior to version 2.3, those parts of your application must be rebuilt; otherwise you will experience errors at either compilation or run time.
  • Enterprise Developer for Eclipse now ships with Eclipse 4.4.2 (Luna). If your applications contain JVM COBOL code that was built with a previous version of the product, those parts of your application must be rebuilt; otherwise you will experience errors at either compilation or run time.

    (609469)

  • A project can have one of two connection modes: NFS/Samba, where the target location is mounted as a local drive, and RSE, which is a purely remote connection to the target location. For project types such as Mainframe COBOL, NFS/Samba is required to use some tools which do not support RSE. For most other projects, it is possible to switch between connection modes using the Remote Settings context menu option. In the dialog box, there are radio buttons allowing for selection of connection modes. On changing mode, you must select an existing connection of the appropriate type, or create a new one. If switching to NFS/Samba mode, you must specify the local path to the project.

    2792882 (1096196)

  • By setting "-Denable.projectrepair=true" in the eclipse.ini file, .cobolProj and .pliProj files will be repaired to reflect the workspace on project refresh.

    2696707 (1095994)

J2EE Connector

Back to the list

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

    2799213 (1096684)

JCL Support

Back to the list

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

    2816179 (1098882)

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

    2815695 (1098825)

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

    2814249 (1098636)

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

    2812899 (1098412)

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

    2812899 (1099966)

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

    2812878 (1098417)

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

    2794881 (1096221)

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

    2789939 (1095803)

Mainframe Access

Back to the list

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

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

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

MF Server Administrator (GUI)

Back to the list

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

    2792382 (1096011)

PL/I Support

Back to the list

  • For BASED variables declared using the form BASED (ADDR(x)), storage checking is now performed on the base reference “x”. This behavior requires the compiler option –nolaxbased. See the Open-PLI User guide for more information on the options –[no]laxbased and –[no]laxdefined.

    2819663 (1099293)

  • The behavior of the –zp1 option has been reverted to that of before Enterprise Developer 2.2 Update 1, with an additional correction relating to Char Varying data items. For a full description of the –zp1 option, refer to the Open-PLI User’s Guide in your product help. If you are installing Enterprise Developer 2.2 U1 HF5 as an upgrade to Enterprise Developer 2.2 U1, you must rebuild any applications that are compiled using the –zp1 option after the upgrade.

    2789213 (1095636)

  • Previously, when using any of the complier options -mvs, -dli, -ims, or -cics, the BINARY attribute was incorrectly applied if the FIXED attribute is specified without BINARY or DECIMAL. The default attribute DECIMAL is now applied.
  • The BIGENDIAN attribute, when explicitly applied to a structure, is now propagated to its CHAR VARYING and WIDECHAR VARYING members.
  • Declarations using DEFINED storage are now checked for compatible types between the DEFINED variable and its base variable. This behavior requires the compiler option –nolaxdefined. See the Open-PLI User guide for more information on the options –[no]laxbased and –[no]laxdefined.
  • The PL/I Macro preprocessor has been enhanced to support the use of the ANSWER statement from within a PL/I Macro.

    2698537 (1094243)

  • The macro preprocessor has been enhanced to support arrays of CHAR and FIXED variables. New macro builtin functions have been implemented (HBOUND, LBOUND, DIMENSION).

    2696129 (1094011)

SQL: HCO for SQL Server

Back to the list

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

    2804069 (1097253)

Updated Run-Time System

Back to the list

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

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

Changes in Behavior in Release 2.2 Update 2

Back to Top

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

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

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

CICS Support

Back to the list

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

    2663890 (1091979)

Compiler

Back to the list

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

    2697615 (1094527)

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

Documentation

Back to the list

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

    2697571 (1094370)

Enterprise Server

Back to the list

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

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

    2807531 (1097783)

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

    Where:

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

    Where:

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

    Where:

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

File Handling

Back to the list

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

    2784949 (1095190)

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

    2784622 (1095971)

Host Compatibility Option for SQL Server (HCOSS)

Back to the list

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

  • Run a DSN bind against the customer database.

    Or:

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

    Additionally:

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

2804069 (1097253)

J2EE Connector

Back to the list

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

IMS Support

Back to the list

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

    2579600 (1084675)

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

    (606142)

JCL Support

Back to the list

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

    2651654 (1090287)

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

    2660651 (1091290)

PL/I Support

Back to the list

  • Important: If you are installing this release as an upgrade to Enterprise Developer 2.2 Update 1, after the upgrade you must rebuild any applications that are compiled using the –zp1 option.

    The behavior of the –zp1 option has been reverted to that of versions of Enterprise Developer earlier than 2.2 Update 1, with an additional correction relating to Char Varying data items. For a full description of the –zp1 option, refer to the Open PL/I User’s Guide in the product help

    This fix restores the behavior in Enterprise Developer versions earlier than 2.2 where, when compiling with –zp1, all parameters are treated as unaligned. (In Enterprise Developer 2.2 Update 1, the behavior when compiling with –zp1 was to not treat parameters as if unaligned).

    When using the –zp1 compiler option, all Character Varying data items are now treated as if unaligned. In previous versions of Open PL/I, for Character Varying data items, the –zp1 unaligned requirement was applied only to structure members and parameters.

    To illustrate the change, consider the following example:

    zptest: proc options(main);

   dcl 1 st1,
     2 c char,
     2 x(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl y(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl sub entry ((4) char(7) var);

   call sub (x);

   call sub (y);

end;

sub: proc (z);

   dcl z(4) char(7) var;

   dcl i fixed bin(31);

  do i = 1 to hbound(z);
      z(i)  = 'x';
  end;

end;

    Where:

    • For x and z, each char (7) var item is 7 plus 2 bytes which equals 9 and then multiplied by 4 equals 36.
    • If y were aligned on half-word by default, each array element is half-word aligned and each equals 10 bytes (9 + 1 pad byte), and the total size equals 40 bytes.
    • At call sub (x), the calling argument and parameter are matched.
    • At the call sub (y), the y element size (10 bytes) is mismatched against the parameter z element size (9 bytes) due to –zp1. This is incorrect and causes unexpected program behavior.

    Due to this correction of treating all Char Varying data items as if unaligned when using –zp1, the size of CHAR VARYING arrays now differs from previous versions of Open-PL/I. For example:

       dcl X(4) char(7) var;

   Put skip list (size(X))  /* size is 36 bytes vs. 40 bytes in previous versions of Open-PL1 */

    2789213 (1095636)

  • Previously, the SRC list in the debugger only included the source filename without the path to the file. If a source file did not exist in the current directory, the debugger could not find it using the filename as it always expects a fully qualified filename. The SRC list now contains the fully qualified file name which includes the path. Also, when changing the SRC or ENV values the source is updated correctly.

    2783734 (1094988)

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
  • File Handler
  • JCL Support
  • PL/I Support

COBSQL

Back to the list

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

    2673619 (1093197)

File Handling

Back to the list

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

    2692826 (1093604)

JCL Support

Back to the list

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

    2671175 (1091627)

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

    2642115 (1089055)

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

    2664639 (1090992)

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

    2659555 (1090759)

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

    (592452)

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

    2686149 (1093587)

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

    2665006 (1091034)

PL/I Support

Back to the list

  • On Intel platforms, the -bitsltr Compiler option can be used to store bit strings left-to-right within each byte. This is similar to Big Endian bit ordering on Intel platforms. The Intel default is to store bit strings right-to-left within each byte similar to the Intel hardware bit ordering.

    2675860 (1092098)

  • The libraries libmf.so, libespli.so and libespliz.so are no longer delivered. This is transparent if linking PL/I objects using mfplx or ldpli, and no changes are needed to your build process.

    However, if linking PL/I objects using either the UNIX ld command or the Enterprise Developer cob command, you must include the libraries libmfpli.so when linking stand-alone Open PL/I objects (executed outside of Enterprise Server), or libmfpliz.so when linking PL/I objects executed under the control of Enterprise Server.

    To do this, use the option -lmfpli for stand-alone Open PL/I objects or -lmfpliz, respectively, for PL/I executed under Enterprise Server. These options replace the –lmf option.

  • Open PL/I applications must be recompiled and re-linked in order to use them with this release.
  • The debugger now stops before an ON UNIT triggers. This lets you perform debugging on the ON UNIT itself. You can configure the ON UNITS the debugger stops on.

    2674783 (1092319)

  • Writing to SYSPRINT when running outside of Enterprise Server now drives output directly to the terminal and does not buffer the I/O.

    2477031 (1076203)

Changes in Behavior in Release 2.2

Back to Top

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

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

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

Assembler Support

Back to the list

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

Common Communications Interface

Back to the list

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

    2195519 (1062800)

Compiler

Back to the list

  • The default for the NSYMBOL directive under DIALECT(ENTCOBOL) has been changed to NSYMBOL(NATIONAL) to emulate the equivalent IBM default.

    2657471 (1090355)

  • To improve RM/COBOL and ACUCOBOL compatibility, the SIGN clause at a group level is no longer applied to non-DISPLAY usage signed numeric data items within the group, just as it is not applied to unsigned numeric data items and non-numeric data items within the group.

    2549904 (1082171)

  • Previously, even though no code was generated, the Compiler allowed the ON EXCEPTION and NOT ON EXCEPTION phrases in the DISPLAY statement in formats that do not allow these phrases. As a result, if the DISPLAY statement was in the ON EXCEPTION phrase of another statement, the NOT ON EXCEPTION phrase would bind incorrectly with the DISPLAY statement instead of with the intended containing statement - for example, ACCEPT or CALL.

Enterprise Server

Back to the list

  • Previously, on cancelling an active JCL job on UNIX (after you have used STOP on the ESMAC > SEPs page to stop the INITIATOR that it is running in), the INITIATOR was terminated and a new one was restarted in its place. Now, the new INITIATOR will not be started, as the STOP request was received before the CANCEL.

    2559087 (1084226)

File Handling

Back to the list

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

    2643384 (1088993)

IDE

Back to the list

  • The Problems view now has a 'Program' column that displays the name of the program in which the problem occurred. If the column is not present in the view by default, it can be added through the Configure Columns dialog box in the View Menu.

    2608496 (1088530)

  • The outline of the ruler in the COBOL editor now changes on modelChanged depending on the current source format.

    2488419 (1077143)

  • Deleting a Web service or a Java interface mapping now deletes the files relating to it from the repos directory and, if it is empty after the files have been deleted, will remove the repos directory itself.
  • The IDE now performs an automatic directive determination when files are added to a project. You can also use a command to perform directive determination of the project manually.

Interface Mapping Toolkit

Back to the list

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

IMS Support

Back to the list

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

JCL Support

Back to the list

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

    2646770 (1089380)

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

    2610362 (1087601)

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

    2619050 (1089095)

MF Directory Server

Back to the list

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

    2641890 (1088838)

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

    2487164 (1081693)

MF Server Administrator (GUI)

Back to the list

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

    2562118 (1083203)

Micro Focus Batch Scheduler Integration

Back to the list

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

    2655482 (1090444)

PL/I Support

Back to the list

  • Open PL/I applications must be recompiled and re-linked in order to use them with this release.

    2675860 (1092098)

  • If using the -cics, -ims, or -mvs options when compiling on a little endian platform, the possibility for errors existed. Starting with this release, using the -cics, -ims, or -mvs options automatically uses -bigendian, thereby eliminating the possibility for these errors. Evaluate any applications that were built with a prior release to determine any impact on any data files being used, or where programs compiled with the -mvs option pass data to sub-programs compiled without it. The -bigendian option can be suppressed by adding the -native option after the -cics, -ims, or -mvs options.
  • CodeWatch no longer attempts to use an incorrect directory when starting. Also, CodeWatch is now the default debugger when no other debugger is specified, and is the only debugger available when using -optexec plitest.

    2655906 (1090193)

  • Support for the evaluation of X, NX, Z, A, and E constants nas been added to CodeWatch.
  • A problem with possible truncation or trailing zeroes within PICTURE assignments has been fixed. As the fix depends on changes to both the Compiler and the run-time, you must perform a complete rebuild of all your source code (recompile and relink) in order to apply it.

    2662261 (1090768)

  • Previously, when taking a PLIDUMP, if the .PDB file needed for a PLIDUMP was not in the same directory as the .DLL and the .STB files, and they were not in the first CAS_BATCH_PATH subdirectory, then the PLIDUMP was not successfully generated and an S0C4 abend could occur.

    2615412 (1090483)

  • The Open PL/I debugger no longer loses its place and behaves erraticly when debugging code containing the same PL/I macro multiple times within the same source routine, even if the -nodebuginfo and -pp options are not specified.

    2612530 (1087809)

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

  • Documentation
  • Enterprise Server
  • IDE
  • JCL Support
  • OpenESQL

Documentation

Back to the list

  • To ensure no loss of functionality when accessing Vision and RM/COBOL data files, you should use the appropriate IDXFORMAT Compiler directive setting or file handling option, and not use the CALLFH(ACUFH) Compiler directive. See 'Configuring Access to Vision Files' and 'Configuring Access to RM/COBOL Data Files' for more information.

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)

IDE

Back to the list

  • You can now set program breakpoints as follows - click "Add Program Breakpoint" in the Run menu or on the Breakpoints view toolbar, and enter the program name in the dialog that is displayed.

    2606838 (1087239)

  • Local Enterprise Server regions without secure user credentials are now started with casstart and stopped with casstop commands.

    2606835 (1087238)

JCL Support

Back to the list

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

    (594968)

OpenESQL

Back to the list

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

    2593798 (1085945)

Changes in Behavior in Release 2.1

Back to Top

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

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

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

CICS Support

Back to the list

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

    2550800 (1082337)

IDE

Back to the list

  • You can now specify in the IDE whether directories that you add to the project should be added to the copypath. You configure this in the project's properties under Micro Focus COBOL > Build Paths, and on the Copybook Paths tab.

    (589096)

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

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

Compiler

Back to the list

  • The scope of the ILUSING Compiler directive when used in a $set command has changed. The scope of the directive is now limited only to the source file it is set in, and not globally. This new behavior may mean that your source files no longer compile. To resolve this, add the required ILUSING statements to the required individual source files, or add the ILUSING directive on the command line. Alternatively, use the IDE to achieve the required behavior: in Visual Studio, use the Namespaces tab; in Eclipse, set the directive in the Additional Directives field.

HCO for DB2 LUW

Back to the list

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

    2549058 (1082441)

File Handling

Back to the list

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

    2518330 (1079491)

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

    2525670 (1080092)

IDE

Back to the list

  • Typing in the sequence area moves text after the cursor to the right and doesn't delete the characters at area end. To overwrite characters in the area, switch to insert mode by pressing the Insert key. Pressing the Tab key in the sequence area indents the text if the option "Pressing Tab in the sequence number area moves caret to area A" is not selected. Pressing the Tab key when there is a multiline selection aligns the text to the area margins.
  • Typing in the sequence area now works like typing in a regular text editor - it moves to the right all the text after the cursor and doesn't delete the charaters at area end. If you want to overwrite characters in the area, you can switch insert mode to overwrite by using "Insert" key.

Run-Time System

Back to the list

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


Where do I start?

Now that you have installed Enterprise Developer, 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 Eclipse
  • New to COBOL
  • New to PL/I
  • Upgrading from Mainframe Express
  • Upgrading from Net Express
  • Upgrading from Server Express
  • Upgrading from Studio Enterprise Edition
  • Want to deploy an application
  • Upgrading to Enterprise Developer for Eclipse
Parent topic: Welcome


New to Eclipse

Enterprise Developer uses a proven industry Integrated Development Environment that provides advanced features for COBOL editing and debugging for application developers. Continuous background compilation, code analysis, code search, and remote compiling and debugging are just a few of the many developer tools available to streamline application delivery. In addition, you can utilize REST and JSON to build new web services, create new user interfaces using HTML-5 and combine COBOL with Java and other Java Virtual Machine (JVM) languages - all within one IDE.

Where to start?

If you've never used Eclipse before, this product help includes the following resources to help you get started:
  • Eclipse Basics, an overview of the Eclipse Integrated Development Environment.
  • A tutorial, Create your first Hello COBOL World application, that demonstrates how you create an Eclipse project for a COBOL program and demonstrates the basic features of the IDE.
  • Advanced Details, section to learn about the Eclipse resource system and what the development life cycle in Eclipse is.
  • A tutorial, Configure the Hello COBOL World application, that demonstrates how to configure a project and resolve some build issues.
  • A tutorial, Debug the Hello COBOL World application, that demonstrates how debugging works in Eclipse.

What next?

Enterprise Developer is a powerful development environment with a variety of features and tools suited to help you get on with your programming effectively and efficiently.

  • Enterprise Developer for Eclipse – Essentials - A free which introduces Micro Focus Enterprise Developer and provides the mainframe developer with a practical working knowledge of how the development and testing of Mainframe Applications can be effectively used on the Workstation, using the Enterprise Developer for Eclipse development tools.
  • See the tutorials for examples of applications you can create with Enterprise Developer.
  • See Developing Applications for more information about creating applications.
  • Find out more about the various ways you can debug applications.
  • Read about how to create remote applications.

A number of Micro Focus videos are available on YouTube showing you how to perform various programming tasks. For example, the following videos show how you can expose COBOL applications as Web services:

  • Implementing a COBOL program as a SOAP Web service
  • Implementing a COBOL program as a REST Web service
Note: These videos use Visual COBOL but equally apply to Enterprise Developer.

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

Parent topic: Where do I start?


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.

    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.

    Though the course uses Visual COBOL to demonstrate the programming concepts, all of the information applies equally to Enterprise Developer.

    This is a standard COBOL programming course. It does not include instructions about how to create applications that use Mainframe Subsystem Support (such as CICS, IMS, JCL and PL/I).

  • Once you have completed the course, continue by Creating Your First Hello COBOL World Application.

What next?

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

  • COBOL Programming for Business Success - a web-based training course teaching you how to design and code COBOL programs.
  • Check the available tutorials for examples of applications that help you solve particular programming cases.
  • See the samples - click Start > All Programs > Micro Focus Enterprise Developer > Samples > Visual COBOL Samples.
  • Check Procedural COBOL Compared with Managed COBOL which covers introductory information about the COBOL language including the difference between native and managed code.
  • 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 JVM. It offers support for object-orientation and access to the JVM. For more 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.
    • Managed COBOL Reference
    • Comparison of COBOL with Other Managed Languages
    • Tutorial: Creating a COBOL JVM Application
Parent topic: Where do I start?


New to PL/I

Programming Language One (PL/I) is a procedural computer programming language designed for creating scientific and business applications as well as systems programming applications.

PL/I is known for its block structure. It has a free form and no reserved words. It can be used for data processing, numerical computation, scientific computing, and system programming.

Where to start?

Micro Focus provides the following resources to help you get started with PL/I programming:

  • A tutorial, Create your first Hello PL/I World application, that demonstrates how to create a project, add a program and build it to produce an application executable.
  • A tutorial, Debug the Hello PL/I World application, that demonstrates how to debug PL/I applications.
  • The section Using Eclipse for PL/I development in this product help that details many of the programming tasks using the IDE.

What next?

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

  • See the available samples - click Start > All Programs > Micro Focus Enterprise Developer > Samples > Mainframe Samples and select the PL/I category in the left-hand pane.
  • Explore the concepts of PL/I Programming.
  • Check the Open PL/I Language Reference Manual.
Parent topic: Where do I start?


Upgrading from Mainframe Express

Enterprise Developer enables you to develop applications that are stored on the mainframe as well as offload applications from the mainframe and develop them locally on Windows. If you are upgrading from Mainframe Express, you can move your existing applications to Enterprise Developer and continue to develop them in the new environment.

Where to start?

Enterprise Developer includes a number of resources to help you get started with developing applications with Mainframe Subsystem support:

  1. If you've never used Eclipse before, see Eclipse Basics.
  2. Complete the Tutorial: Getting Started with Offload Development of Mainframe Applications that demonstrates techniques and features of Enterprise Developer for creating and maintaining mainframe applications.
  3. See the Tutorial: Remote Mainframe Development that demonstrates how to use Enterprise Developer to develop an application directly on the mainframe.
  4. See the available Tutorials: Mainframe Applications for more examples of applications you can create with Enterprise Developer.

What next?

Once you are familiar with the IDE, you can import your existing code into Enterprise Developer:

  • See How to upgrade an application created with Mainframe Express for an explanation of what you need to install and an overview of the process of upgrading existing applications.
  • See the Upgrading to Enterprise Developer guide for full details on upgrading your applications from Mainframe Express to Enterprise Developer, the differences between the two products and what technologies are not supported or have been superseded.
  • See Backward Compatibility with Earlier Micro Focus Products for information about the differences in behavior and terminology between the earlier Micro Focus products and Enterprise Developer.
Parent topic: Where do I start?


Upgrading from Net Express

Where to start?

  • If you've never used Eclipse before, see New to Eclipse.
  • See Developing Applications for more information about creating applications.

Ready to import your existing applications?

Once you are familiar with the IDE, you can import your existing code into Enterprise Developer.

  • Enterprise Developer provides an import wizard to help you convert your existing Net Express projects to Visual Studio projects. For an overview of the process of importing Net Express projects into Visual Studio see Converting Net Express projects to Eclipse projects.
  • See the Upgrading to Enterprise Developer for Eclipse guide for full details on upgrading your applications from Net Express to Enterprise Developer, the changes between the two products and what technologies are not supported or have been superseded.
  • Also, see Backward Compatibility with Earlier Micro Focus Products.

What next?

You can continue to maintain your applications in Enterprise Developer as before. You can also employ new technologies such as JVM COBOL and Web Services to 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
  • Tutorial: Creating a Basic COBOL JVM Application
Parent topic: Where do I start?


Upgrading from Server Express

Enterprise Developer for Eclipse enables you to develop applications that were created using Server Express.

Where to start?

  • If you've never used Eclipse before, see New to Eclipse.
  • Watch a Micro Focus YouTube video explaining what the steps are for upgrading from Server Express.
  • See Developing Applications for more information about creating applications.

Ready to import your existing applications?

Once you are familiar with the IDE, you can import your existing code into Enterprise Developer:

  • See the Upgrading from Server Express guide 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 Enterprise Developer.
  • See Backward Compatibility with Earlier Micro Focus Products for information about the differences in behavior and terminology between the earlier Micro Focus products and Enterprise Developer.

What next?

You can continue to maintain your applications in Enterprise Developer as before. You can also employ new technologies such as JVM COBOL and Web Services to 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
  • Tutorial: Creating a Basic COBOL JVM Application
Parent topic: Where do I start?


Upgrading from Studio Enterprise Edition

Studio Enterprise Edition comes in two variants - Studio Enterprise Edition (Windows) and Studio Enterprise Edition (UNIX). These are the paths to upgrade your applications created with them:

  • Studio Enterprise Edition (Windows) used Visual Studio 2008. You upgrade your projects created with it to Enterprise Developer for Visual Studio - see its product help available from Upgrading from Studio Enterprise Edition.
  • Studio Enterprise Edition (UNIX) was used to create applications for Linux and UNIX. You upgrade such applications to Enterprise Developer for Eclipse. The process you use for upgrading your applications also applies when you upgrade applications created with Server Express.

Where to start?

  • If you've never used Eclipse before, see New to Eclipse.
  • See Developing Applications for more information about creating applications.

Ready to import your existing applications?

Once you are familiar with the IDE, you can import your existing code into Enterprise Developer:

  • See Upgrading from Studio Enterprise Edition for an explanation of what you need to install and an overview of the process of upgrading existing applications.
  • See Backward Compatibility with Earlier Micro Focus Products for information about the differences in behavior and terminology between the earlier Micro Focus products and Enterprise Developer.

What next?

Enterprise Developer is a powerful development environment with a variety of features and tools suited to help you program your applications in an efficient and effective way.
  • See the tutorials for examples of applications you can create with Enterprise Developer.
  • Find out more about the various ways you can debug applications.
Parent topic: Where do I start?


Want to deploy an application

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

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

Where to start?

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

  • Start with a brief Overview of deploying applications.
  • Discover various ways you can ship the Micro Focus COBOL run-time system.
  • See Deploying native applications for considerations about how to create a setup program and how to set up your application and Enterprise Server.
  • 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:

  • See the tutorials for examples of various application types and deployment scenarios.
  • 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
Note: Some of the videos use Visual COBOL but the information equally applies to Enterprise Developer.

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

Parent topic: Where do I start?


Upgrading to Enterprise Developer for Eclipse

This guide provides information on upgrading applications from earlier Micro Focus mainframe development environments to Enterprise Developer for Eclipse. It highlights the differences between the old and new products, and offers solutions on how to keep your application working in the same way as before. The guide also introduces the new concepts and features of the Integrated Development Environment.

Note:
  • This documentation uses the name Enterprise Developer to refer to Enterprise Developer for Visual Studio and Enterprise Developer for Eclipse. The full product names are used only when it is necessary to differentiate between the two products.

Benefits of Upgrading

You get a number of important benefits by upgrading to Enterprise Developer from earlier Micro Focus development systems or other COBOL systems.

Enterprise Developer uses a proven industry Integrated Development Environment that supports thousands of clients for developing and deploying critical business applications. Enterprise Developer enables unified, collaborative, and cost-effective development through rich, industry-standard tooling and at the same time it helps minimize skills shortages, expands market reach and accelerates time-to-delivery to meet today’s agile business requirements.

  • Licensing Changes
    Micro Focus is using a new standard industry technology for license management in Enterprise Developer.
  • Resolving conflicts between reserved keywords and data item names
    Micro Focus continues to enhance the COBOL language, for example, by expanding the list of reserved COBOL words and adding new keywords to it as part of new levels of the COBOL language. Each Micro Focus release corresponds to a particular level. You can use the MFLEVEL Compiler directive to enable Micro Focus-specific reserved words in your code and change the behavior of certain features to be compatible with a specific level of the language.
  • Importing Existing COBOL Code into Enterprise Developer
    You can open, edit, compile and debug individual COBOL files in Enterprise Developer or you can use the Net Express Project Import Wizard in Enterprise Developer that converts Net Express projects into Enterprise Developer projects and imports the COBOL source code into the IDE.
  • Recompile all source code
    Application executables that were compiled using earlier Micro Focus products must be recompiled from the sources using Enterprise Developer.
  • Upgrading from Mainframe Express to Enterprise Developer
    Explains the guiding principles when moving your mainframe projects in Mainframe Express to Micro Focus Enterprise Developer.
  • Upgrading from Studio Enterprise Edition (Windows)
  • Upgrading from Server Express and Studio Enterprise Edition (UNIX)
  • Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express
    You can upgrade COBOL applications that were developed in Net Express, Server Express to Visual COBOL or Studio Enterprise Edition and Mainframe Express to Enterprise Developer without the need to change their code.
  • Upgrading from ACUCOBOL-GT
    There are conceptual and behavioral differences between Enterprise Developer and ACUCOBOL-GT, part of the Micro Focus extend® product family, and these differences can affect the way you upgrade existing applications to Enterprise Developer.
  • Upgrading from RM/COBOL®
    Describes some of the important differences you may encounter when upgrading existing RM/COBOL applications to Enterprise Developer.
  • 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: Where do I start?


Licensing Changes

For a number of years Micro Focus used the Micro Focus License Management System on Windows and Micro Focus License System Administration on UNIX 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: Upgrading to Enterprise Developer for Eclipse


Resolving conflicts between reserved keywords and data item names

Micro Focus continues to enhance the COBOL language, for example, by expanding the list of reserved COBOL words and adding new keywords to it as part of new levels of the COBOL language. Each Micro Focus release corresponds to a particular level. You can use the MFLEVEL Compiler directive to enable Micro Focus-specific reserved words in your code and change the behavior of certain features to be compatible with a specific level of the language.

If you use Enterprise Developer to compile applications created with an older Micro Focus product, and these applications use data names that are now reserved keywords in Enterprise Developer, you receive a COBOL syntax error COBCH0666 ("Reserved word used as data name or unknown data description qualifier"). To work around this issue and continue using some of the reserved words as data names in your source code, you can either:

  • use the REMOVE Compiler directive to remove individual keywords from the reserved words list
  • set the MFLEVEL Compiler directive to a lower level which corresponds to the level your applications are at (see the information about MFLEVEL of some Micro Focus products further down this section). This removes all reserved keywords which have been added for levels above that level from the reserved words list.

You can set both directives from the command line, in your source code, or in the Additional Directives field in the project's COBOL properties.

Setting directives from the command line

To use REMOVE from an Enterprise Developer command prompt, type the following:

cobol myprogram.cbl 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 Net Express v5.1 WrapPack 5, use this command line:

cobol myprogram.cbl mflevel"15" ;

Setting directives in the source code

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

$set remove "ReservedWord"

Or:

$set mflevel"nn"

Setting directives in the IDE

To set either one of the directives in the project's properties:

  1. In the IDE, click Project > Properties > Micro Focus > Project Settings > COBOL.
  2. Type MFLEVEL"nn" or REMOVE "ReservedWord" in the Additional directives field.
  3. Click Apply and then OK.
Parent topic: Upgrading to Enterprise Developer for Eclipse
Related reference
MF, MFLEVEL
Related information
Reserved Words


Importing Existing COBOL Code into Enterprise Developer

You can open, edit, compile and debug individual COBOL files in Enterprise Developer or you can use the Net Express Project Import Wizard in Enterprise Developer that converts Net Express projects into Enterprise Developer projects and imports the COBOL source code into the IDE.

To load a file in the IDE

You can open your existing COBOL files in Enterprise Developer as standalone files and edit them without a project. Either double-click such a file in Windows Explorer or, in the IDE click File > Open File and browse to select the file and open it.

There is basic support in the IDE for editing, compiling and debugging of files that are not part of a project. To take advantage of all features that the IDE offers for compiling, editing and debugging, , it is recommended to add the file to a project. The easiest way to add a standalone file to a project is to right-click in the editor, click Create COBOL Project and then specify your preferences for the new projects.

To import Net Express projects

The Net Express project format is not the same as the project format in Enterprise Developer for Eclipse so it is not possible to edit Net Express projects in Enterprise Developer directly.

You can use the Import and Convert Net Express Projects wizard to convert existing Net Express projects into Eclipse projects, and to import the COBOL source into the IDE. Click File > Import > Micro Focus > Convert NetExpress Projects. The wizard analyzes your Net Express project, converts it to the appropriate project type and sets Compiler directives as needed.

To import files into an existing project

In Eclipse, you import files into your project using File > Import. This automatically adds to the project all files from the project directory, the subdirectories and from any linked directories. To prevent a file from being compiled, right-click the file and click Build Action > Ignore.

To scan files and set Compiler directives

After importing your existing sources into a project in the new IDE, you need to set the required Compiler directives.

In Eclipse, to set Compiler directives on COBOL files, use the file properties, or the Determine Directives command from the context menu for the files in COBOL Explorer. This triggers file scanning and sets directives as specified in Window > Preferences > Micro Focus > COBOL > Directives Determination

Parent topic: Upgrading to Enterprise Developer for Eclipse


Recompile all source code

Application executables that were compiled using earlier Micro Focus products must be recompiled from the sources using Enterprise Developer.

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

You can recompile from the IDE or the command line.

Parent topic: Upgrading to Enterprise Developer for Eclipse


Upgrading from Mainframe Express to Enterprise Developer

  • Advantages to upgrading to Enterprise Developer
  • Approaches to upgrading your applications
  • Considerations when upgrading to Enterprise Developer
  • How to upgrade an application created with Mainframe Express to Enterprise Developer
  • Further Information and Assistance
Parent topic: Upgrading to Enterprise Developer for Eclipse


Advantages to upgrading to Enterprise Developer

Micro Focus recognizes the investment that our mainframe clients have made in Mainframe Express - and the great working partnerships we have established as these products have evolved. It is these close working relationships that have formed the development and release of the new generation of mainframe development applications.

In Enterprise Developer we have created a product that represents the natural evolution of Mainframe Express: it's a seamless transition into the next generation of mainframe IDEs. It protects your existing investment and future-proofs your operation going forwards. Lapsed Mainframe Express users will quickly become converts - this is a feature-rich product with appeal right across the board.

Whatever your level of engagement with Mainframe Express, as an existing Micro Focus customer we developed Enterprise Developer to maximize the investment you have made in our technology and protect it moving forward.

Using the Enterprise Developer enhancements and modern IDEs have numerous advantages such as, among others:

Improved productivity
This is achieved through:
  • Using the very latest IDE technology in a powerful integrated development environment
  • Replicating mainframe environment on Windows; through easier sharing of development resources.
  • Ready access to mainframe-based elements while removing unnecessary burden on the host.
  • Fast and easy customization with major source control systems, integration with existing development lifecycle, and built-in extended IDE user interface for higher developer acceptance and productivity gains.
  • Providing the tools to allow you to edit, compile, debug, execute and test COBOLapplications on all supported Micro Focus UNIX and Linux environments including z/Linux, AIX, HP-UX etc. One development tool can now meet your development requirements today and in the future.
  • Enabling cross-language application development which results in better quality and increased competitiveness.
  • Full control of development activities directly on the mainframe through the Eclipse IDE to edit, execute, debug and unit test applications.
  • Achieving faster time to market
  • Using workstations to shorten the mainframe development and unit test cycles, and deliver new products and features faster.
Improved efficiency (COBOL only)
Improve efficiency when performing day to day mainframe development activities on or off mainframe, enabling access to standard IDEs of choice, smart editor, instantaneous compilations, advanced test and debugging capabilities.
Address mainframe skills shortage
Using COBOL from within standard IDEs helps reduce the gap between the mainframe COBOL and Java or C# developers by providing a unifying, collaborative and dynamic development environment. Non-COBOL developers, can quickly and easily adapt to the COBOL language, and get up to speed in no time.

For a full list of the advantages of using Enterprise Developer, see the Enterprise Developer data sheet and white papers on the Micro Focus Web site.

Parent topic: Upgrading from Mainframe Express to Enterprise Developer


Approaches to upgrading your applications

There are different approaches to upgrading existing mainframe applications to Enterprise Developer in order to modernize them.

Starting over and rewriting your application in Enterprise Developer is not recommended as this means more costs, the need to do more testing and, potentially, incurs more risks.

You can keep the existing application intact and only create new front ends in Enterprise Developer that will interact with the application.

Or, and this might be the best approach and lower risk one in most situations, is to upgrade your applications and processes using incremental steps. In order to reduce the maintenance backlog and ensure that the applications have the flexibility and agility that the business needs. Using this approach:

  • You upgrade your application one small step at a time, testing the change and planning for the next one on each phase.
  • Start by only moving a small subset of the files in Enterprise Developer. This could mean only a small number of the people on your teams are involved with making the changes.
  • Maintain the application using both Enterprise Developer and Mainframe Express.
Parent topic: Upgrading from Mainframe Express to Enterprise Developer


Considerations when upgrading to Enterprise Developer

The following describes how you can move existing files and data from Mainframe Express to Enterprise Developer:

Sources

You copy the COBOL programs and copybooks in the Enterprise Developer project directory or, alternatively, from the Enterprise Developer you link to them in the original location where they are used by Mainframe Express.

Data

  • Data files - you can reuse the .dat files in Enterprise Developer. There is a Data File Tools utility for editing data files.
  • DB2
  • IMS files - you can reuse the existing .dbd, .psb, and .mfs files after recompiling them in Enterprise Developer.
  • XDB

Metadata

  • Data catalog - you need to create a new catalog in Enterprise Developer.
  • CICS resource definition files (dfhdrdat.*) - you can copy the existing files and use them in Enterprise Developer after performing a caspcupg to upgrade them.

Configuration

  • Regions - now available as instances of Enterprise Server which you need to create and configure.

Accessing the Mainframe

Enterprise Developer uses its own version of Mainframe Access OS/390 and z/OS Server that provides access to host resources for environments. A single installation of Mainframe Access can support all of these products, providing connectivity to any number of DB2, IMS, and CICS systems located anywhere in an enterprise. It can also provide access to JES facilities, VSAM and non-VSAM data sets, and data controlled by external library management products such as Panvalet, Librarian and Endevor. It includes the Drag and Drop utility, the Remote Job Step Execution (RJSE) facility for execution of one or more steps of a job on a remote z/OS host, Compare and Synchronization Monitor, and SourceConnect.

Enterprise Developer for Eclipse also provides a mainframe z/Server that provides the mainframe integration. You use the Remote Systems view to access the mainframe.

Parent topic: Upgrading from Mainframe Express to Enterprise Developer


How to upgrade an application created with Mainframe Express to Enterprise Developer

The following provides an outline of the incremental approach to upgrading a Mainframe Express application to Enterprise Developer where you use both development products to maintain the application while gradually moving the sources to the new IDE.

Tasks to perform in Mainframe Express

Review your Mainframe Express application:
  1. Create an inventory of the sources it uses, the copybook dependencies, data files, SQL, JCL and IMS files, third party utilities, integrated preprocessors.
  2. Check what workgroups are used and what the workflow processes are, what repositories are used to store the sources, what the build scripts and command line parameters are, how the application accesses the mainframe.
    Note: Use the MFECL command-line utility of Mainframe Express to export the project details to an .xml file which will include all project details at a glance - files in use, workgroups, output and dependency folders, Compiler directives, project and file options. The command to use is:
    mfecl /exportxml project-name.mvp [ xml-filename.xml]
  3. Review the XML file to see what information it includes:

    The file provides details about the project and file settings, as well as of the workgroup levels. You are going to use this information when you are configuring the new projects in Enterprise Developer.

  4. Analyze the strengths and weaknesses of your application in the Mainframe Express environment and to what extent it meets the business requirements. The application might be a good candidate for being modernized by upgrading it to Enterprise Developer.
Select a subset of source files:
Initially, we recommend that you identify a small group of source files from a larger Mainframe Express application to move over to Enterprise Developer. For example, select the source files responsible for a single operation of an application. As you become familiar with this process, you can more readily identify appropriate file groupings regardless of size.
Prepare your original application:
  1. Replace any hard-coded paths in your Mainframe Express project with concatenated ones – to do this, in Mainframe Express, click Project > Convert Paths to Relative.
  2. Back up the sources.

Tasks to perform in Enterprise Developer

Create a Mainframe COBOL Project
For your initial subset of source files, create a single Enterprise Development project. You can add projects you continue to populate your Mainframe Express sources into Enterprise Developer.
  1. Make sure that the Team Developer Perspective is the active Eclipse perspective, and that the Enterprise Development Projects application appears in the Application Explorer view; if the Enterprise Development Projects application is not displayed in the Application Explorer view, see the Integrated Enterprise Development Project Application topic for further instructions.
  2. In the Application Explorer view, right-click Enterprise Development Projects and select New COBOL Project > Mainframe COBOL Project.
  3. Type a name for the project into the Project name field; then click Finish.
Tip: To emulate workgrouping behavior in Eclipse, you can use copybook projects to define the copybook paths for each level, and you can add these projects as dependency projects to the ones for the source files. See Emulating workgroups in Eclipse for details.
Configure the project in Enterprise Developer:
  1. In the Application Explorer view, right-click the project; then select Properties from the context menu.
  2. In the left pane, expand Micro Focus.
  3. Using the entries under Micro Focus, specify the same project properties as are specified for the original Mainframe Express project, listed in that project's xml-filename.xml file.
  4. Click Apply and Close.
Import the source files:
Use linking to add source files to the new project. This enables you to keep the source files in their original location, and does not create copies of the files in the Enterprise Developer project directory.
  1. In the Application Explorer view, right-click the project; then select one of the following:
    • New > Folder - to add all sources in a single folder
    • New > File - to add a single source file
  2. Click Advanced; then, based on your selection in step 1, click one of the following:
    • Link to alternate location (Linked Folder) - to link to a single folder containing multiple source files
    • Link to File in the file system - to link to a single source file
  3. Browse to the folder in your Mainframe Express project that includes the files or file you want to add.
  4. Select the folder or the file to add; then click Finish.
Set individual file properties:
  • In the Application Explorer view, right-click a file in your project; then select Properties from the context menu.
  • Set the properties for the selected file as specified in the xml-filename.xml file.
  • Click Apply and Close.
Set Enterprise Server options:
  1. From the Eclipse menu, click Window > Preferences, expand Micro Focus, and then click Enterprise Server.

    All options are set to Prompt, which means that Eclipse prompts you before executing the option behavior.

  2. To set these options to execute automatically, change the following options to Always:
    • Automatically start the associated server
    • Automatically restart the server when project output locations change
    • Automatically enable dynamic debugging
  3. Click Save and Apply.
  4. If the Preference Recorder dialog box appears, click OK to record your preferences.
Verify Rumba options:
For CICS and IMS applications, you use the Micro Focus Rumba TN3270 emulator to connect to and run your application. Rumba is provided with Enterprise Developer. To ensure that Eclipse is configured to use the embedded Rumba emulator:
  1. In Eclipse, click Window > Preferences.
  2. Expand Micro Focus > Enterprise Server, and click TN3270.
  3. Ensure that Enable display, Rumba (Embedded) and Connect automatically are all selected.
  4. Click Apply and Close.
Build the project:
By default, Eclipse performs a build automatically as add source files and update configurations. Be sure to check the Console view for any build errors.

Tasks to perform in Enterprise Server

Create an enterprise server region
Using the Server Explorer, create an enterprise server region on which to run compiled applications. Select the template most appropriate for your CICS, IMS, or JCL application. Associate the new enterprise server region with your project. See To create a new enterprise server for details.
Configure the enterprise server region
Based on the settings in the xml-filename.xml file, configure the enterprise server region to match. See Configuring the Server Instance Environment for details.

Run the application

Run the application from Enterprise Developer in debug mode. To do this:

JCL applications
  1. Right-click the JCL file in your project; then select Submit to Enterprise Server from the context menu.

    This starts the enterprise server region and submits your JCL.

  2. Debug the application to thoroughly test it.
CICS and IMS applications
  1. On the Server Explorer view, right-click your enterprise server region; then select Show TN3270 Display from the context menu.

    This starts the enterprise server region, starts the Rumba Mainframe Display view, and connects to your application running on theenterprise server region.

  2. Debug the application to thoroughly test it.

Configure Mainframe Access (MFA)

If your application uses sources on the mainframe, configure MFA to access them. See the Mainframe Access Installation Guide and the Working with Mainframe Files topic for details.

Distribution tasks

Once you have an application running smoothly in all areas, you can distribute it to your development and QA teams, making it available for others to import into Enterprise Developer.

Distributing a project
In your workspace, copy the project folder with all the files. You can store this on a shared network location. Users need to import the existing project and sources locally in their workspaces.
Distributing an enterprise server region
You can export an existing enterprise server region to make it available for import into another %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates environment. To do this, see To export an enterprise server instance and To import an enterprise server .
Parent topic: Upgrading from Mainframe Express to Enterprise Developer
Related concepts
Integrated Enterprise Development Project Application
Emulating workgroups in Eclipse
Configuring the Server Instance Environment
Mainframe Access Installation Guide
Working with Mainframe Files
Related tasks
To create a new enterprise server
To export an enterprise server instance
To import an enterprise server


Further Information and Assistance

Tutorials

To get up-to-speed with using Enterprise Developer to edit and maintain your mainframe applications, check the Getting Started book in the help and, more specifically, the Mainframe tutorials. Start with the tutorial "Getting Started with Enterprise Developer" which provides basic understanding of how the product operates. Move on to the other tutorials which provide details about developing CICS, JCL and IMS applications.

Assistance

If you consider upgrading your development environment to Enterprise Developer, you can contact Micro Focus' Technical Services for assistance.

In addition, please note:

  • Mainframe Express Functionality That Works Differently in Enterprise Developer for Eclipse
  • Emulating workgroups in Eclipse
    Describes how you can emulate a workgrouping environment with Enterprise Developer for Eclipse.
Parent topic: Upgrading from Mainframe Express to Enterprise Developer


Mainframe Express Functionality That Works Differently in Enterprise Developer for Eclipse

Some features of Mainframe Express work differently in Enterprise Developer or are superseded by features provided by the new IDE. The following list shows some of these differences:

Feature in Mainframe Express | Feature in Enterprise Developer
Analysis Option | Enterprise Developer offers integrated code analysis functionality.
AppMaster Builder (AMB) and Structured COBOL (S-COBOL) source code | AppMaster Builder is integrated into Enterprise Developer. The functionality is available when you install the Micro Focus AppMaster Builder AddPack. For details, see AppMaster Builder in Eclipse IDE vs. AppMaster Builder in Mainframe Express IDE.
Automatic Catalog Import | Available through the MFA Drag and Drop interface as well as the option to catalog from the command line. Data connect functionality is being checked.
CICS resource definitions You can reuse any existing CICS resource definitions in Enterprise Developer after executing the caspcupg command.

Cut-down resource definitions (PCT, FCT, PPT) are not supported.

Command line utility (MFECL) | The equivalent to MFECL is not available in Enterprise Developer; however, command-line options for much of the tooling are available. In addition, you can use the standard facilities of the IDE. For example, you can use Ant scripts to compile the code.
Database Access | If your application running under Enterprise Server accesses a database but contains no explicit connection logic, you must define the database as an XA resource (XAR) in your enterprise server instance.
Easytrieve

Mainframe Express provided integrated support for Easytrieve through an add-on option which allowed Easytrieve applications to be edited, compiled and tested within the Mainframe Express IDE.

Easytrieve is now available. Contact Micro Focus SupportLine for details.
Editor Autofix | The editor in Enterprise Developer includes an AutoCorrect feature. Other editor features that can help increase your productivity in writing code are Content Assist proposals and code templates.
Interactive AMS | Not available.
IMS TM Enterprise Developer does not support the following IMS TM and communication features:
  • The IMS Message exit
  • The IMS MFS Display exit
  • The Mainframe Express IMS to CICS LU6.2 Bridge
  • IMS86ALT
MAS SDK

a collection of utilities to automatically compile downloaded source and provide reports on the outcome. These are part of Mainframe Express and Studio 6.0 (Net Express) and were developed for Windows.

Not available.
MFA Server | A newer version of MFA Server is available with Enterprise Developer.
MFENTMAP, the Entry Point Mapping facility | Run-time system support for MFENTMAP is available and any existing configuration files will work.
Outline View | Includes an Outline view that shows the program structure. Copybook dependencies are shown in the COBOL Explorer as well as in the Copybook Dependency view.
PL/I PL/I application development is fully supported within Enterprise Developer, and PL/I applications are supported using CICS, IMS or JCL.

The PL/I language, Micro Focus Open PL/I, is fully integrated.

Regions | Enterprise Developer provides support for full, multi-tasking enterprise server regions.
Source code control systems

Mainframe Express used the Microsoft Common Source Code Control (SCC) Interface to enable you to use the functions of a SCC-compliant source control manager with your IDE.

Enterprise Developer comes with an industry-standard integrated development environment that provides access to any SCC tooling with the appropriate plugin. For example:
  • Enterprise Developer provides integration with Micro Focus Enterprise Sync, a change management system for mainframe development.
  • Enterprise Developer provides integration with Endevor, a full-function change control system for the mainframe with signout controls and extensive user customization.
  • A number of plugins are available that integrate the IDE with the version control system you are using - for example, subclipse for connecting to SVN, or eGIT for connecting to git.
Template projects In Enterprise Developer, you can create templates from both projects and regions and distribute them to your developers.

Export and import commands for regions are available from Server Explorer inside the IDE.

Note: To distribute projects created with Enterprise Developer, you need to provide users with all content contained in the entire project folder in the Eclipse workspace. Users then import the project into their own Eclipse workspace.
Third-party preprocessors You can embed Third-party preprocessors in Enterprise Developer in a manner similar to how this was done in Mainframe Express. See Additional Preprocessors for details.

Syntax checking is supported for ECMs and for COBSQL.

Time-Sharing Option (TSO)

Mainframe Express supported the use of TSO commands, CLISTs and REXX execs, which could be run in TSO interactive (or foreground) sessions or in TSO batch (or background) sessions, using the IDAEFT01 (IKJEFF01) utility.

Enterprise Developer supports TSO batch (IKJEFTxx).

You can emulate TSO interactive in Enterprise Developer. To do this, you need to use AWM to model an action calling a tool from the ISPF function package. This action would accept a REXX procedure or some CLIST plus parameters and execute them as a TSO batch job or online in the server.

WinRunner

A screen capture utility that was supplied with some versions of Mainframe Express.

You can now use the products from the Micro Focus Silk portfolio.
Workgrouping | Workgrouping behavior can be emulated. See Emulating workgroups in Eclipse for details.
XDB tooling | Fully supported as a Start option, and can also be accessed from within the IDE.
Tip: After upgrading, we suggest that you start with the Getting started with Micro Focus Enterprise Developer tutorial to help you become familiar with the new IDE. Afterwards, move on to the tutorials that provide details for using ED to develop mainframe applications, such as the CICS, JCL, and IMS tutorials.
Parent topic: Further Information and Assistance
Related concepts
Endevor
AppMaster Builder in Eclipse IDE vs. AppMaster Builder in Mainframe Express IDE
AppMaster Builder in Eclipse IDE vs. AppMaster Builder in Mainframe Express IDE
Additional Preprocessors
Emulating workgroups in Eclipse


Emulating workgroups in Eclipse

The following is an example of how you can set workgroup levels Enterprise Developer. There are numerous other ways in which the projects can be configured to work in this type of system. You can add a larger number of additional directories to each copybook project (either as relative paths to the workspace variable or as variables in their own right) which would allow for even more configurability.

Introduction

Enterprise Developer does not provide the Mainframe Express workgrouping mechanism out-of-the-box. It can be emulated, though.

There are a number of features in the Eclipse framework, many of them relating to how projects are created and operate together, which can help in creating a workgroup environment.

Using COBCPY

The Micro Focus Compiler uses the COBCPY environment variable to find all of the copybooks used in a program compilation. Setting up a workgrouping environment by setting COBCPY so that the IDE can inherit the settings has a few disadvantages.

  • The IDE is not aware of any of the copybook locations used in the application which can lead to undefined behavior.
  • The COBCPY path is typically of such a length that some of the tools cannot handle, which could lead to unexpected behavior.
  • Each paths defined in COBCPY will always be searched during a when a compilation is performed. With Eclipse using a background parse to provide a number of key features, this can cause excessive delays in everyday operation. Though background parse can be switched off, this means you are not going to receive the instant feedback in the editor.

Using copybook projects

Another approach you can take to include copybooks is to use copybook projects to store your copybook directories. You can then add these projects as dependent projects to any other source projects which allows the IDE to identify the copybooks for build operations.

As you can add multiple paths to each copybook project, each one of these projects can then represent a "level" in the workgroup hierarchy. Multiple copybook projects can then be used to represent the set of levels in a potential workgrouping environment. There are many ways in which the final organisation can be arranged; the important thing is that the IDE 'knows' about the files to be used for compilation.

The following sections show how you can recreate the various workgroup levels and use copybook projects to manage the levels.

Creating folders for the workgroup levels

In your workspace, create folders that will represent your workgroup levels. For example:

  • <workspace_dir>\PROD
  • <workspace_dir>\TEST
  • <workspace_dir>\DEV

Set up the project variables

To avoid having to set too many hardcoded paths, you can use the workspace local variables (visible to all projects) to locate the root directories of the code.

  1. In the IDE, click the Windows >Preferences.
  2. Expand General > Workspace, and click Linked Resources.

    This opens the Linked Resource configuration page:

  3. Click New to create a variable pointing to the root level of the workgroup level you want to use.

    You can use a mapped drive letter, UNC name or a predefined location (such as c:\source\prod) which then allows the projects to be shared among multiple users without having to make any changes:

  4. Repeat for each level that you need to set:

  5. Click OK.

Remember that workspace variables are each defined on a per workspace basis - in a multi-user environment, each user needs to perform this step themselves for each workspace they need when developing their application.

Create the copybook projects

For each level in the workgroup, you need to create a copybook project. To do this, use the COBOL Copybook Project type and, for each project, give a name which reflects the name of the workgroup level you want it to represent (for example, PROD, INT, DEV).

If you check the properties of a copybook project, you can notice there are no Builders set for it. This means no compilation operation will take place if source code is found in the project location.

Adding files to the copybook projects

The quickest way to do this is by adding a single linked directory item which points to the physical location of the root of the copy file location on disk. If you have never encountered linked resources in Eclipse before, they work in a similar manner to a UNIX/Linux symbolic link.

  1. Click File >New > Folder.
  2. Click Advanced and click Link to alternate location (Linked Folder).
  3. Click Variables.
  4. Select the workspace variable that you created earlier which matches up with the root directory of your workgroup level. In this case, our variable was called PROD. Click OK and it should populate the folder dialog as shown below:

  5. Click Finish.

The IDE inspects the directory hierarchy for recognised COBOL types so they can be identified at a later time when working with your source code.

This project can be treated as a normal COBOL project and can have any directories it contains added to the copy path as well as the ordering of any such directories altered.

  1. Open the project properties dialog, expand Micro Focus > Build Path, and then click the Dependency Paths tab.
  2. Set Path type to COBOL Copybook Paths tab item

    The set of paths that will be added to the copybook path is shown. If necessary, you can reorder the paths as well as enable or disable directories.

    The default is not to include any paths so some paths almost certainly have to be switched on. Here is a typical entry for the copybook paths:

You have now created one level of your workgroup. You have created a single project with a workspace variable pointing to the top level of the physical location of the code for your level in the workgroup. You have also filtered out the COBOL source code items and have defined the copybook directory ordering for this level.

Repeat the same process for each level of your workgroup that you wish to use. In this particular example, there are seven levels defined.

Add the copybook projects as a dependency to a COBOL project

Once you have defined all your copybook projects, you can add them as dependent project to a COBOL project for the source files:

  1. Create a COBOL project to hold your source files.
  2. Add the source code items which you are going to working with.

    You do not need to add every item in the entire application - just the one with which you are likely to be changing and/or debugging.

  3. In the project properties, expand Micro Focus, and click Build Paths.
  4. Click the Projects tab, and then click Add.

    This enables you to select the projects on which this one depends. The following example shows seven levels have been added:

  5. Click the Dependency Paths tab and ensure Path type is set to COBOL Copybook Paths.
  6. You can alter the order of the copybook projects as well as turn levels on and off according to what workgroup levels you may be working with. This provides a highly configurable and user friendly way in which to alter the copybook paths:

Distributing the copybook projects to multiple users

Once created, you can use the copybook projects as any other projects. Due to the way in which they utilize workspace variables, if all users in a multi-user environment are using the same locations for the source code on their local machines (or similarly named mapped drives) then the projects can be easily shared.

If a user imports the copybook projects into their own workspace (provided that they have also defined the workspace variables), then it should be a quick task to configure a workgroup hierarchy for all of your teams. The copybook projects can be committed to SVN (or any other SCCS) and should not have to be changed once created.

Parent topic: Further Information and Assistance
Related concepts
Endevor
AppMaster Builder in Eclipse IDE vs. AppMaster Builder in Mainframe Express IDE
Related information
Mainframe Express Functionality That Works Differently in Enterprise Developer for Eclipse


Upgrading from Studio Enterprise Edition (Windows)

Studio Enterprise Edition (Windows) used Visual Studio 2008. You upgrade projects created with it to Enterprise Developer for Visual Studio.

For more details on how to upgrade see the product help of Enterprise Developer for Visual Studio.

Parent topic: Upgrading to Enterprise Developer for Eclipse


Upgrading from Server Express and Studio Enterprise Edition (UNIX)

You upgrade existing distributed applications created with Server Express to Visual COBOL for Eclipse.

Similarly, you upgrade mainframe applications created with Studio Enterprise Edition (UNIX) to Enterprise Developer.

The Enterprise Developer suite includes the following two independent products that are designed to be used together for maximizing the developers' productivity:

  • Micro Focus Enterprise Developer UNIX Components is the counterpart of Server Express and must be installed on the machine that has your application sources.
  • Enterprise Developer for Eclipse provides a rich and highly effective integrated development environment that can be connected to Micro Focus Enterprise Developer UNIX Components to enable you to edit, build and debug the applications' sources directly on the remote machine.
Note: The process of upgrading Server Express and Studio Enterprise Edition (UNIX) is very similar. Therefore, references to Visual COBOL for Eclipse and Visual COBOL Development Hub apply equally to Enterprise Developer for Eclipse and Enterprise Developer UNIX Components, respectively.

The following sections provide information on how to upgrade.

  1. Advantages of Upgrading to Enterprise Developer
  2. Upgrading Your COBOL Application
  3. Best Practice in Development Using Eclipse
  4. Modernize Your Applications and Processes
Parent topic: Upgrading to Enterprise Developer for Eclipse


Advantages of Upgrading to Enterprise Developer

Enterprise Developer offers numerous enhancements and a modern IDE that offers advantages such as:

Improved productivity
This is achieved through:
  • Using the very latest technology of integrated development environments (IDEs) in a powerful IDE.
  • Fast and easy customization with major source control systems, simplifying integration with existing development lifecycle leading to higher developer acceptance and productivity gains.
  • Providing the tools to allow you to edit, compile, debug, execute and test COBOL applications on all supported Micro Focus UNIX and Linux environments. One development tool can now meet your development requirements today and in the future.
  • Enabling cross-language application development which results in better quality and increased competitiveness.
  • Full control of the development activities directly on the mainframe through the Eclipse IDE to edit, execute, debug and unit test applications.
  • Achieving faster time to market.
Improved efficiency
(COBOL only)
Improve efficiency when performing day-to-day development activities, enabling access to Eclipse, smart editor, instantaneous compilations, advanced test and debugging capabilities.
Addressing of the COBOL skills shortage
Using COBOL from within a standard IDE helps reduce the gap between the COBOL and Java or C# developers by providing a unifying, collaborative and dynamic development environment. Non-COBOL developers can quickly and easily adapt to the COBOL language, and get up to speed in no time.

For a full list of the advantages of using Enterprise Developer, see the Enterprise Developer data sheet and white papers on the Micro Focus Web site.

Parent topic: Upgrading from Server Express and Studio Enterprise Edition (UNIX)
Next topic: Upgrading Your COBOL Application


Upgrading Your COBOL Application

Note: Upgrading your existing applications might be a complex task, therefore we recommend you contact Micro Focus Professional Services for assistance with this process.

If you've never used Eclipse before, Micro Focus recommends that you read the chapter Introduction to Eclipse in this product help to get familiar with the IDE before you start upgrading your applications.

Prerequisites

In most situations when you are upgrading to Enterprise Developer, you will:

  • Keep your source code on the UNIX machine. You need to install Micro Focus Enterprise Developer UNIX Components on this machine.
  • Install Enterprise Developer for Eclipse on the your local Windows machine. You need to create a connection in Enterprise Developer to the remote UNIX machine and then create remote projects for the application's source files.

Upgrading your applications

The following outline shows an example approach to upgrading an application to Enterprise Developer:

  1. Assess your existing processes for building and testing your applications.

    Discover any similarities and differences between your existing applications and what programming issues they resolve. Determine what project types and scenarios you need to handle in Enterprise Developer for Eclipse.

    Review the Compiler directives that are used to build the applications. Review these to ensure they are still valid.

    Note: You can use Micro Focus COBOL Analyzer to check your existing applications and assess what might need be to changed or what functionality is no longer supported.
  2. Compile your existing sources at the command line:
    1. Ensure Micro Focus Enterprise Developer UNIX Components is installed on the machine that stores your sources.
    2. From a terminal window, set the environment for Micro Focus Enterprise Developer UNIX Components and build the existing application. Resolve any compilation issues and ensure that the application behaves as it did previously.
  3. Create a Enterprise Developer project to handle your source code:
    1. Install Enterprise Developer for Eclipse on a local Windows machine.
    2. In Eclipse, create a connection to the machine that includes your sources and create a remote project.
    3. Add the application sources to the new project and set the following Compiler directives on the project:
      • SOURCETABSTOP"8"
      • COPYEXT",CBL,CPY"
    4. Add the Compiler directives that were used to compile the original project and are still valid to the new project.
    5. Build and debug the application using Eclipse.

      Ensure you get the same results using Eclipse as you did when you used Micro Focus Enterprise Developer UNIX Components on the remote machine (see step 2b).

  4. Add more projects, programs and copybooks as required.
  5. Review the Best Practice in Development Using Eclipse information in this document to ensure you achieve maximum productivity.
  6. Experiment with various debugging options to find those that best meet your requirements.
  7. Compile for debug and for release and ensure that the application performs as expected.
  8. Create one or more template projects and distribute those across the entire development team.
  9. Examine ways in which Eclipse can help to modernize your applications and processes.

For more details about these steps see the following sections and the Related Information.

  • Compile Your Existing Programs without a Project
  • Create a Project and Import Your Sources
Parent topic: Upgrading from Server Express and Studio Enterprise Edition (UNIX)
Previous topic: Advantages of Upgrading to Enterprise Developer
Next topic: Best Practice in Development Using Eclipse
Related concepts
Modernize Your Applications and Processes


Compile Your Existing Programs without a Project

Enterprise Developer includes a lot of enhancements and changes and this is why applications that were compiled using earlier Micro Focus products must be recompiled from the sources using Enterprise Developer.

Micro Focus recommends you first compile without a project as you would have done in Server Express. This will help you focus on resolving any compilation issues following the changes in the environment. Then, you can look at creating a Enterprise Developer project in order to take advantage of all the benefits offered by the IDE.

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

  1. Ensure that Micro Focus Enterprise Developer UNIX Components is installed on the remote machine where you store your existing COBOL programs.
  2. Log onto the remote machine and from a terminal window, configure the environment 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 Enterprise Developer 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 Enterprise Developer.

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 Enterprise Developer. 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
  • COBIDY
  • 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 (or later in the editor in Eclipse), type the following:

cobol myprogram.cbl 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:

cobol myprogram.cbl mflevel"15" ;

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

$set remove "title"

Or:

$set mflevel"15"
Parent topic: Upgrading Your COBOL Application


Create a Project and Import Your Sources

Once you have ensured your programs compile cleanly in the Enterprise Developer environment, you can create a project for them so that you can take full advantage of all of the benefits offered by the Eclipse debugging environment. You need Enterprise Developer for Eclipse installed on your local Windows machine and you need to create a connection in it to the remote UNIX machine.

Connect Enterprise Developer to the remote machine

From your local installation of Enterprise Developer create a new remote connection to Micro Focus Enterprise Developer UNIX Components on the UNIX machine which has your existing COBOL programs. See Creating connections to remote hosts in this product help.

Create a remote project

You need to create a project that will store the source files on the remote machine:

  1. Start Enterprise Developer.

    If this is the first time you have started Enterprise Developer you see the Welcome page in the IDE. You can also open the Welcome page by clicking Help > Welcome.

  2. Click Open COBOL perspective in the Welcome page.

    In this perspective, Eclipse offers you the views and commands that are best suited for COBOL development.

  3. Click File > New > Remote COBOL Project.

    Choose the remote connection to use and follow the instructions to create a remote native COBOL project in a directory on the remote machine.

Import the COBOL source files

Add the source files on the remote machine to your project as follows:

  1. Right-click your project in the COBOL Explorer view and click Import > Import.
  2. In the Import wizard, expand General, click File System, and then click Next.
  3. Click Browse, navigate to the location of your source files on the remote machine, and click OK to confirm the path.
  4. In the Import wizard, enable the check boxes for the files you want to import in your project, and click Finish.

    This adds the files to your project and, if Eclipse uses the default settings, starts a build. You might need to set some Compiler directives to resolve any compilation issues, similarly to when you resolved any issues when compiling from a terminal window.

Configure your project

To configure your project and specify any Compiler directives:

  1. Right-click your project in COBOL Explorer, and click Micro Focus > Project Settings > COBOL.
  2. In the Additional directives field, specify any directives that you had to use to resolve any issues that occurred when you compiled without a project. These could be the Compiler directives that were used to compile the application in Server Express prior to the upgrade or new ones.
  3. Also specify the following Compiler directives:
    • SOURCETABSTOP"8"
    • COPYEXT",CBL,CPY"

    If your source code contains tab stops, compilation might fail, because although a COBOL tab is eight characters long, the IDE's tab is four characters long, and lines of code might be starting in the sequence number and indicator areas section (columns one to seven) of the program instead of from column eight.

    You can fix this problem using the SOURCETABSTOP(n) Compiler directive, where n is the number of space characters by which to expand tab characters during compilation.

  4. Click OK.

Build the project

By default, Eclipse builds your source files each time you make a configuration change or add or edit the files. If you have changed this preference, to build the project click Project > Build Project.

Add copybooks

To add existing copybooks to your project, right-click the project and use the Import > Import command.

Copybooks are not compiled at build time and the files' Build Action property is automatically set to None. (You can also set this property for COBOL source files to keep a file in the project but not include a built version in any output.)

By default, Enterprise Developer identifies files as copybooks by their .cpy extension. You can specify other file extensions as copybooks in the IDE preferences - click Window > Preferences > Content Types, click COBOL Copybook and add any new file associations using this dialog box.

Parent topic: Upgrading Your COBOL Application


Best Practice in Development Using Eclipse

Here is a list of recommendations about how to make the most of using Eclipse in real-life scenarios.

Break down large projects

Projects that contain a large number of source files and build artefacts can be hard to navigate and slow to build. If you find this is the case with your application, Micro Focus recommends that you review the contents of large projects and split them into separate projects in which you group items that are logically related.

For example:
  • If you have different versions of a product for different customers, keep common source in one project and have a separate project for each customer.
  • If you have core code that is rarely changed or recompiled, keep that in one project and have separate projects for those areas that change regularly.

Reference common sources

Use the COBOL Copybook project type to store all your copybooks and add this project as a dependency to the projects that contain any source programs that reference the copybooks. Use this approach in preference to using linked resources.

Use linked folders to reference resources where it is not possible to restructure your projects (to use the COBOL Copybook project type) or use a remote project (to access any sources on remote machines).

Use existing Compiler directives files

To avoid repetition and reduce maintenance effort, consider keeping all your Compiler directive settings in a directives file. To reference this file in each project, specify the USE"filename" Compiler directive in the Additional directives field in each project's properties.

Use relative paths

Keep your sources relative to a base path and avoid specifying full paths in you projects. This ensures your code is portable and easy to use with source control systems.

Access sources on remote machines

  • For optimal performance, create a remote project from the available project types to access any sources on remote machines.
  • Use RSE or SSH in preference to Samba type remote connections. Only use the Samba type connection when it is not possible to use the other types of connections. This is because the Samba connection has the slowest performance.
  • Avoid using network shares or drives to directly access any resources on remote machines from your local projects.

    If for some reason, it is not possible to use local versions of the sources, you can use network shares as linked folders but the connection will be very slow. In such cases, you might be able to improve the performance by splitting the remote shared folder into smaller chunks then set the COBCPY environment variable before you start Enterprise Developer for Eclipse on your local machine.

Eclipse workspace

  • To avoid performance issues, your Eclipse workspace must not be on a shared drive.
  • Do not commit the Eclipse workspaces into a source control system, as they contain metadata which is updated frequently.

Configure Enterprise Developer

To boost your productivity, enable some additional views in Eclipse that are suitable for the programming tasks you're dealing with within the current active perspective. To do this click Window > Show View and either select a view from the ones that are displayed, or click Other to choose from all available ones.

For example, in the Debug perspective, enable the Expressions view that lists any data items you want to monitor. Or enable the Remote Systems view to see all remote systems that have a connection defined in Eclipse and to launch terminal sessions from within the IDE.

Parent topic: Upgrading from Server Express and Studio Enterprise Edition (UNIX)
Previous topic: Upgrading Your COBOL Application
Next topic: Modernize Your Applications and Processes


Modernize Your Applications and Processes

Following industry-standard development practices

Many source code control systems and Agile tools can be integrated into the Eclipse IDE.

You should also consider using continuous integration, which involves the automatic building and testing of an application after a change occurs to the source code. This method traps errors sooner in the development life cycle and can greatly improve efficiency and reduce costs.

Multi-user applications

Enterprise Developer includes a Run Unit API to enable multiple users to simultaneously use an application based on COBOL code that was designed originally for a single user.

Developing Web-based applications

You can use Enterprise Developer to migrate existing, core applications to a service-oriented architecture as Web services, and deploy them using Micro Focus COBOL Server and Enterprise Server, so that you can develop COBOL-based software components to be invoked across the Web.

Developing JVM applications

You can compile both new and existing COBOL as JVM COBOL managed code. This enables you to:

  • Reuse existing COBOL business logic and data access in the Java Virtual Machine
  • Access Java classes and features from COBOL applications
  • Create and extend composite applications consisting of COBOL and Java code
  • Reuse and extend Open ESQL applications

Both procedural and Object-Oriented (OO) COBOL are supported within the JVM. OO COBOL classes can inherit classes written in Java and vice versa.

The managed COBOL syntax includes many extensions to the COBOL language to support Java features; for example, the TRY ... CATCH syntax to enable exception handling in COBOL.

There are also certain directives that help integrate your managed COBOL with Java. For example, you can now expose the Linkage Section and entry points in your COBOL to other managed languages by compiling with the ILSMARTLINKAGE directive.

Parent topic: Upgrading from Server Express and Studio Enterprise Edition (UNIX)
Previous topic: Best Practice in Development Using Eclipse


Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express

You can upgrade COBOL applications that were developed in Net Express, Server Express to Visual COBOL or Studio Enterprise Edition and Mainframe Express to Enterprise Developer 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, Mainframe Express and Enterprise Developer in the following areas:

Compiling and building
Having created a project in Enterprise Developer, you can either use the IDE or the command line to build.
Run-time systems
There are some differences between the run-time systems supplied with Enterprise Developer and those supplied with Net Express, Server Express and Mainframe Express. This, however, will not affect your existing applications and they will continue to run under Enterprise Developer - you only need to recompile the applications from the source code with Enterprise Developer.
Run-time system technologies
Some technologies behave differently and require some upgrade work.
Restrictions and unsupported features
Some features of Net Express, Server Express and Mainframe Express are not available in Enterprise Developer. However, there are alternative techniques for many of these features.
Editing and debugging
Much of the Net Express, Server Express and Mainframe Express functionality for editing and debugging is available in Enterprise Developer, but sometimes with a different name and with a slightly different behavior. In addition there are some new features such as background parsing, which highlights errors as you type and code completion techniques that provide easy access to language elements, enabling you to select and insert them simply.
Eclipse integration
Enterprise Developer is integrated with the Eclipse IDE. The development environment provides all the functionality to manage projects and debug applications.

Applications previously built in Net Express, Server Express and Mainframe Express can be developed and run within the Eclipse IDE.

  • Summary of Differences
    The majority of the applications created with Net Express, Mainframe Express or Server Express will continue to work in Enterprise Developer without any changes. However, there are some differences between these development systems you should consider when you upgrade to Enterprise Developer.
  • Backward Compatibility with Earlier Micro Focus Products
  • Compiling and Building Differences
    There are several aspects of compiling and building applications that behave differently in Enterprise Developer. 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 Enterprise Developer and those supplied with Net Express, Server Express and Mainframe Express. These, however, do not affect your existing applications if you recompile them from the source code in Enterprise Developer.
  • Restrictions and Unsupported Features
    Some features in earlier Micro Focus products are not available in Enterprise Developer. However there are alternative techniques for many of these features.
  • Run-Time Technology Differences
    Some technologies behave differently in Enterprise Developer and this might affect how you upgrade existing applications.
  • Editing and Debugging Differences
    Much of the edit and debug functionality in Net Express, Server Express and Mainframe Express is available in Enterprise Developer, but some of it has a different name or slightly different behavior. In addition there are some new features such as background parsing.
  • Tips: Eclipse IDE Equivalents to IDE Features in Earlier Products
    Many IDE features have different names and locations in Enterprise Developer.
Parent topic: Upgrading to Enterprise Developer for Eclipse


Summary of Differences

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

Compiling and Building Differences

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

Output File Formats
Each project compiles into a single file (.dll, .so or .exe), or to multiple files of the same file type with one output file for each source file (.dll, .so, .exe, .int, or .gnt). As well as an .lbr file, which contains a collection of .int and .gnt files on Windows, you now can use a .dll as the container for application components.
Compiler directives
When you upgrade your source code to Enterprise Developer 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.
Linking
The static run-time system and the single-threaded run-time system on Windows are no longer required and they are not shipped with Enterprise Developer. Applications built with Enterprise Developer are now linked to the shared or dynamic run-time systems. On UNIX, you can link to the single-threaded or multi-threaded shared or dynamic run-time system.
Called Programs and Dependencies
At run time, called programs are found in the same way as before. However, there are some new ways to set COBPATH and copy files into a common folder.
File Handler
The File Handler .obj files are not available in Enterprise Developer. Enterprise Developer uses the File handler packaged in the mffh.dll file instead.
Makefile Conversion
You cannot use existing makefiles from inside Enterprise Developer for Eclipse without changing some Eclipse defaults and adopting a modified build process. Where makefiles invoke commands supported by Enterprise Developer they will continue to work as before. Please contact Micro Focus for more information on using existing makefiles.
OpenESQL Assistant
The OpenESQL Assistant data source names (DSNs) in Enterprise Developer must be configured as ODBC or
SQL Compiler Directive Options
When you upgrade your to Enterprise Developer, some SQL applications could require additional SQL Compiler directive options to avoid compiler errors.
XML PARSE Statement
In Net Express, 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 Enterprise Developer, 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 Enterprise Developer and those supplied with Net Express, Server Express and Mainframe Express. These, however, do not affect your existing applications if you recompile them from the source code in Enterprise Developer.

OpenESQL
Enterprise Developer sets the BEHAVIOR SQL Compiler directive option to MAINFRAME by default to provide optimal performance. To revert to the default behavior exhibited in Net Express, Server Express, set the BEHAVIOR directive to UNOPTIMIZED.
Single-Threaded Run-Time System
The single-threaded run-time system is not available in Enterprise Developer on Windows. Instead, both single-threaded and multi-threaded applications run using the multi-threaded run-time system. This has no effect on your existing applications. On UNIX, the single-threaded run-time system is available, so that applications can link with third-party code.
Static-Linked Run-Time System
The static-linked run-time system is not available in Enterprise Developer. 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.
Enterprise Developer Co-existing with Earlier Micro Focus Products
Some additional configuration is required to ensure Enterprise Developer and Studio Enterprise Edition work properly when installed on the same machine.

Restrictions and Unsupported Features

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

CBL2XML Utility
The CBL2XML utility is currently available as a command line tool only.
DBMS Preprocessors
Earlier Micro Focus products supported DBMS preprocessor versions that are not supported in Enterprise Developer. For a list of currently supported DBMS preprocessors, see the Database Access Support with Native COBOL topic.
Dialog System
Dialog System applications are not supported in Eclipse but you can upgrade the non-GUI components of an application to Eclipse, and then recreate the GUI components using the GUI tools in Eclipse.
Form Designer
Form Designer is the Net Express tool for creating user interfaces for CGI-based Internet and intranet applications. Form Designer and the HTML page wizard are not available in Enterprise Developer.
GNT Analyzer
GNT Analyzer is not available in Enterprise Developer. It has been replaced by Test Coverage.
Host Compatibility Option (HCO)
Mainframe Express provided a user interface for the Host Compatibility Option (HCO) feature. This user interface is not available in Enterprise Developer; however the HCO Create Database, DDL Processor, DCLGEN, Export Data, and Import Data tools are available via batch command line invocation.
INTLEVEL Support
The INTLEVEL directive is rejected by the Compiler in Enterprise Developer.
NSAPI
There is no support for NSAPI in Enterprise Developer.
Online Help System
Net Express provided the Online Help System for creating online help from character-based applications, and displaying it on screen. It is not available in Enterprise Developer and the Online Help System information file type (.HNF) is not supported.
OpenESQL
In both Net Express and Studio Enterprise Edition, support is provided for Oracle OCI in OpenESQL. Enterprise Developer does not support Oracle OCI in OpenESQL.
SQL Option for DB2
In the Mainframe Express and Net Express IDEs, you could invoke SQL Option for DB2 from the main menu within the IDE. For Enterprise Developer, SQL Option for DB2 is not available from the main menu in the IDE. Instead, all SQL Option for DB2 tools are available from Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2.

Run-Time Technology Differences

Some technologies behave differently in Enterprise Developer 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 Enterprise Developer and for Net Express and Server Express .
Java and COBOL
The cobsje script is not available in Enterprise Developer for Eclipse on UNIX. Enterprise Developer 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. Code coverage for native COBOL applications available from within the IDE in Enterprise Developer integrates the Test Coverage functionality.

Editing and Debugging Differences

Much of the edit and debug functionality in Net Express, Server Express and Mainframe Express is available in Enterprise Developer, but some of it has a different name or slightly different behavior. In addition there are some new features such as background parsing.

Interface Mapping Toolkit
The Interface Mapping Toolkit is available in Enterprise Developer for Eclipse; however it does not support CICS or IMS service interfaces.
Mixed Language Debugging
With Net Express you could debug mixed language applications. In Enterprise Developer, you can debug native COBOL and Java or native COBOL and C with some additional configuration.
Program Breakpoints
Program breakpoints are breakpoints that stop execution each time a specified program or entry point within the program is called. They are supported in Enterprise Developer, but by default their behavior is different from their behavior in Net Express
Remote Debugging
The Net Express animserv utility used for debugging programs remotely has been replaced by cobdebugremote (or cobdebugremote64 when debugging 64-bit processes) in Enterprise Developer.
Source Pool View
The source pool view in Net Express showed all source files available in the project directory, regardless of whether or not they are used in the current build type. This view is not available in Enterprise Developer.
Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


Backward Compatibility with Earlier Micro Focus Products

COBOL applications developed and built using previous Micro Focus products can be developed and built with Enterprise Developer. However, there are some differences in behavior and in terminology.

Executables requiring recompilation

If you are on the AIX platform, due to an internal change in version 2.0 of your product, you must recompile and/or relink your programs compiled prior to this version, to make them compatible with this run-time system.

Terminfo files

The following terminfo files have been removed:

  • AT&T
    • att605
    • tty5420
  • IBM
    • ibm3151
  • Qume
    • qvt102
  • Wyse
    • wy120
    • wy120-25
    • wy50
    • wy60
    • wy60-w
    • wy75
    • wy85

Diagnostic tools

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

  • faultfind_level
  • faultfind_outfile
  • faultfind_recsize
  • faultfind_config
  • faultfind_cache_enable

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

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

Backward Compatibility with Studio Enterprise Edition

File Control Description (FCD)
The FCD format for file handling operations in 32-bit applications defaults to FCD3 in Enterprise Developer; in Studio Enterprise Edition, it defaulted to FCD2.
Copybook name changes
A number of COBOL copybook files that were part of Studio Enterprise Edition had names in uppercase, whereas, in Enterprise Developer, most copybooks are provided with lowercase names.

This affects the following copybooks - DFHAFCD, IDADDSA, IDADTCA, IDAS99RB, IDAS99TU, IEESMCA, IEFJFCBN, IEFJSSIB, IEFTIOT1, IEZJSCB, IHAACEE, IHAASCB, IHAASVT, IHAASXB, IHACDE, IHAPSA, IKJTCB, MFJCTLBC, MFJDCUSR, MFJDSXIT, MFJDXIT, MVSFINDM, MVSGETCT, SPOOLHK.

If your code refers to any of these files in uppercase, and you are compiling with Enterprise Developer on UNIX, this may result in the code failing to compile, because it cannot locate the copybooks.

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

  1. Change the names of the copybooks referred to from your code to lowercase.
  2. Create copies of the copybooks, and save them with uppercase names.
  3. Set up symbolic links to point the uppercase names to their lowercase equivalents as follows:
    1. Create a script file, copylink.sh, which creates symbolic links for the above copybooks.
    2. Paste the following contents into the file:
      ln -s dfhafcd.cpy   DFHAFCD.CPY
ln -s idaddsa.cpy   IDADDSA.CPY
ln -s idadtca.cpy   IDADTCA.CPY
ln -s idas99rb.cpy  IDAS99RB.CPY
ln -s idas99tu.cpy  IDAS99TU.CPY
ln -s ieesmca.cpy   IEESMCA.CPY
ln -s iefjfcbn.cpy  IEFJFCBN.CPY
ln -s iefjssib.cpy  IEFJSSIB.CPY
ln -s ieftiot1.cpy  IEFTIOT1.CPY
ln -s iezjscb.cpy   IEZJSCB.CPY
ln -s ihaacee.cpy   IHAACEE.CPY
ln -s ihaascb.cpy   IHAASCB.CPY
ln -s ihaasvt.cpy   IHAASVT.CPY
ln -s ihaasxb.cpy   IHAASXB.CPY
ln -s ihacde.cpy    IHACDE.CPY
ln -s ihapsa.cpy    IHAPSA.CPY
ln -s ikjtcb.cpy    IKJTCB.CPY
ln -s mfjctlbc.cpy  MFJCTLBC.CPY
ln -s mfjdcusr.cpy  MFJDCUSR.CPY
ln -s mfjdsxit.cpy  MFJDSXIT.CPY
ln -s mfjdxit.cpy   MFJDXIT.CPY
ln -s mvsfindm.cpy  MVSFINDM.CPY
ln -s mvsgetct.cpy  MVSGETCT.CPY
ln -s spoolhk.cpy   SPOOLHK.CPY
    3. As superuser, execute the script in the folder which contains the copybooks ($COBDIR/cpylib).

Backward Compatibility with Earlier Versions of Enterprise Developer

File Locking
In versions prior to Enterprise Developer 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.
Fileshare through Enterprise Server
On UNIX systems, Fileshare through Enterprise Server should use the TCP/IP protocol (CCITCP) in preference to CCI Named Pipes (CCINAMPU), because support for CCINAMPU is deprecated.
Updated run-time system

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

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

JVM COBOL
Enterprise Developer for Eclipse now ships with Eclipse 4.7 (Oxygen). A consequence of this is that if your application contains JVM COBOL code that was built with a version of Enterprise Developer prior to version 2.3, those parts of your application must be rebuilt; otherwise you will experience errors at either compilation or run time.
Casspool recovery
Following the detection of an unrecoverable file status error on the casspool file, a message is displayed on the console and an ACCEPT statement is issued. This stops processing, allowing you to fix the underlying file problem, before continuing the job.
ACUCOBOL-GT and RM/COBOL file handling under Enterprise Server
Two file handling configuration options have been introduced that enable or disable all types of file handling for ACUCOBOL-GT and RM/COBOL data files.
ACUFH has overall control, but is enabled by default, which means that there should be no change in behavior when handling files when not running under enterprise server. However, ESACUFH enables and disables file handling of these types under enterprise server, and is disabled by default. To continue handling ACUCOBOL-GT and RM/COBOL data files, ensure both options are enabled in your file handling configuration file.
Using parentheses in member reference
In managed COBOL syntax, you may only use parentheses when referencing methods. You can no longer specify parentheses when referencing fields or properties, as this will produce a syntax error.

For example:

set intLength to testString::Length()

must change to:

set intLength to testString::Length
Calling program search order
In previous versions of Enterprise Developer (and earlier Micro Focus products) you could use a run-time tunable to define a specific order in which the run-time system searches for called sub-programs. Due to changes in the run-time system, there is only one viable specific search order, and therefore the program_search_order tunable is no longer available; remove the tunable from any configuration you have set. The default (and only) order used is:
  • 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.
  • On Windows platforms, if you are calling dynamic link libraries (.dll files) without a specific path, the COBPATH environment variable is searched.
  • The path of the calling program is searched.

If the sub-program cannot be located using one of the above methods, a run-time error is produced.

Calling RM/COBOL compatible library routines
Previously, to call an RM/COBOL compatible library routine, you had to set the DIALECT"RM" Compiler directive, which ensured the correct call-convention was used. To set this functionality now, you must explicitly use the correct call-convention in the CALL statement.
CALLFH
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.
DIALECT"ENTCOBOL"
DIALECT"ENTCOBOL" now sets NSYSMBOL"NATIONAL"; previously, this set NSYMBOL"DBCS".
DIALECT"RM"
DIALECT"RM" now sets PERFORM-TYPE"RM". If you recompile an application that uses DIALECT"RM", the behavior may change for nested PERFORM statements. If that is the case, explicitly set PERFORM-TYPE"MF" after DIALECT"RM" to continue with the previous behavior.
FLAGCD
This Compiler directive is no longer available in Enterprise Developer. Remove it from your code, otherwise you receive a COBCH0053 Directive invalid or not allowed here error.
ILREF
Previously, you could specify .jar files and other formats as a parameter when using this Compiler directive. Now, you can only specify .class files.
ILUSING
If you set this Compiler directive 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.
JVMDECIMAL
Note: This is applicable to JVM COBOL only.
This Compiler directive now controls how the following items are exposed in Java:
  • Data items of type DECIMAL
  • Non-integral data items exposed as the result of ILSMARTLINKAGE
  • Non-integral data items exposed as the result of a PROPERTY keyword
Previously, these items would each be exposed as a ScaledInteger, which is still possible using JVMDECIMAL, but the directive's default is to expose each item as a BigDecimal.
Compatible ACUCOBOL-GT file handling environment variables
The following environment variables, introduced for ACUCOBOL-GT compatibility, have been replaced with other environment variables or configuration options that you add to your File Handler configuration file. No other ACUCOBOL-GT file handling environment variables are supported.
Redundant variable | Replaced 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

Setting these environment variables will have no effect.

Open PL/I Compiler
Important: If you are installing this release as an upgrade to Enterprise Developer 2.2 Update 1, after the upgrade you must rebuild any applications that are compiled using the –zp1 option.

The behavior of the –zp1 option has been reverted to that of versions of Enterprise Developer earlier than 2.2 Update 1, with an additional correction relating to Char Varying data items.

The behavior has been restored to that in Enterprise Developer versions earlier than 2.2 where, when compiling with –zp1, all parameters are treated as unaligned. (In Enterprise Developer 2.2 Update 1, the behavior when compiling with –zp1 was to not treat parameters as if unaligned).

When using the –zp1 compiler option, all Character Varying data items are now treated as if unaligned. In previous versions of Open PL/I, for Character Varying data items, the –zp1 unaligned requirement was applied only to structure members and parameters.

To illustrate the change, consider the following example:

zptest: proc options(main);

   dcl 1 st1,
     2 c char,
     2 x(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl y(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl sub entry ((4) char(7) var);

   call sub (x);

   call sub (y);

end;

sub: proc (z);

   dcl z(4) char(7) var;

   dcl i fixed bin(31);

  do i = 1 to hbound(z);
      z(i)  = 'x';
  end;

end;

Where:

  • For x and z, each char (7) var item is 7 plus 2 bytes which equals 9 and then multiplied by 4 equals 36.
  • If y were aligned on half-word by default, each array element is half-word aligned and each equals 10 bytes (9 + 1 pad byte), and the total size equals 40 bytes.
  • At call sub (x), the calling argument and parameter are matched.
  • At the call sub (y), the y element size (10 bytes) is mismatched against the parameter z element size (9 bytes) due to –zp1. This is incorrect and causes unexpected program behavior.

Due to this correction of treating all Char Varying data items as if unaligned when using –zp1, the size of CHAR VARYING arrays now differs from previous versions of Open-PL/I. For example:

   dcl X(4) char(7) var;

   Put skip list (size(X))  /* size is 36 bytes vs. 40 bytes in previous versions of Open-PL1 */

Backward Compatibility with the Net Express and Mainframe Express IDE

The main differences between the Net Express, Mainframe Express and Eclipse IDEs are:

  • Perspectives. The Team Developer perspective shows the views and menus relevant to COBOL and PL/I development, such as the Application Explorer view, Program Outline, Outline and Console views. There are other perspectives for Debugging, the Interface Mapper and CTF.
  • Project > Build automatically. Whenever changes to a resource are saved, an incremental build starts, which rebuilds all the resources modified since the last build. You can force a rebuild by using Project > Clean.
  • Build settings. These are available in three places:
    • Project > Properties > Micro Focus > Project Settings. You can specify any additional directives to be passed to the compiler at build time. These settings do not depend on the active build configuration and are always passed to the compiler.
    • Project > Properties > Micro Focus > Build Configurations. You can have multiple build configurations for different build scenarios and swap between them. You choose the configuration you want to use, by setting it as the current active configuration. This then overrides the project language settings.
    • Properties on the context menu for a single file. To set this, right-click the COBOL file in the Application Explorer view. The settings are specifically for this file and they override the currently active build configuration and the Project Language Settings.
  • Debug and run configurations. You need one of these before you can debug or run a program. They are available from:
    • Project > Properties > Micro Focus > Run-time Configuration. These are the run-time settings for this project, such as run-time arguments, run-time tunables, COBOL switches and so on.
    • Run > Debug Configurations. Like build configurations, you can have multiple debug configurations and swap between them. These override the project run-time configuration.
    • Run > Run Configurations. These behave in the same way as debug configurations, but provide slightly different options.
  • Cheat sheets. These are like tutorials and give step-by-step instructions on how to do a task, together with brief explanations. See Help > Cheat Sheets > COBOL Development. There are cheat sheets to:
    • Create a project to say "Hello COBOL World".
    • Import existing COBOL files into Eclipse
    • Debug a program

Changes in some options and files delivered with the product include:

Treatment of DBCS literals
In Net Express, under the NCHAR directive, if an alphanumeric literal contained only DBCS characters, then the literal was treated as class NCHAR. In Enterprise Developer, this is not true, and you are required to prefix literals in the procedure division with N to achieve equivalent behavior (for example: IF N"dbcs-chars" = data-item-1.), which is significant when performing comparisons, where NCHAR literals get padded with double byte spaces. In Enterprise Developer, all literals that are surrounded by quotes without any character specified (B", N", etc...) are always treated as alphanumeric.
Note: In the following scenario, the literal is still treated as a NCHAR literal:
01 data-item pic N value "dbcs-charaters".
ADIS
In earlier Micro Focus products, the default location for the ADISCTRL file was $COBDIR. The default location of the file in Enterprise Developer is $COBDIR/etc.
Default working mode
In Server Express and in versions of Visual COBOL R4 and earlier, the default working mode set by the COBMODE environment variable was 32-bit. With the current release of Visual COBOL and Enterprise Developer, it is 64-bit.
Format of the index files
In Net Express and Server Express, the default setting of the IDXFORMAT option was 4. With the current release of Enterprise Developer, it is 8.
FILEMAXSIZE File Handler configuration option

In Net Express and Server Express, the default setting for FILEMAXSIZE was 4. With the current release of Enterprise Developer, it is 8.

Coexisting with Earlier Micro Focus Products

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

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

To work around this issue, ensure that Enterprise Developer 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 COBCONFIG_) or set it to another configuration file that does not contain the invalid tunable for the particular session you are running in.
Licensing error due to environment settings (applies to Windows environments only)
The message "Micro Focus License Manager service is not running" can occur when you invoke a Net Express, Mainframe Express or Studio Enterprise Edition utility from Enterprise Developer. This happens when the tool is invoked with Enterprise Developer environment settings while it requires the Net Express or Studio Enterprise Edition ones.

This happens when you edit files such as .dat that have a file association with Net Express or Studio Enterprise Edition.

Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


Compiling and Building Differences

There are several aspects of compiling and building applications that behave differently in Enterprise Developer. You might need to change the project properties and update some of the Compiler directives and settings that you previously used.
  • Output File Formats
    Each project compiles into a single file (.dll, .so or .exe), or to multiple files of the same file type with one output file for each source file (.dll, .so, .exe, .int, or .gnt). As well as an .lbr file, which contains a collection of .int and .gnt files on Windows, you now can use a .dll as the container for application components.
  • Compiler directives
    When you upgrade your source code to Enterprise Developer 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.
  • Linking
    The static run-time system and the single-threaded run-time system on Windows are no longer required and they are not shipped with Enterprise Developer. Applications built with Enterprise Developer are now linked to the shared or dynamic run-time systems. On UNIX, you can link to the single-threaded or multi-threaded shared or dynamic run-time system.
  • Called Programs and Dependencies
    At run time, called programs are found in the same way as before. However, there are some new ways to set COBPATH and copy files into a common folder.
  • File Handler
    The File Handler .obj files are not available in Enterprise Developer. Enterprise Developer uses the File handler packaged in the mffh.dll file instead.
  • Makefile Conversion
    You cannot use existing makefiles from inside Enterprise Developer for Eclipse without changing some Eclipse defaults and adopting a modified build process. Where makefiles invoke commands supported by Enterprise Developer they will continue to work as before. Please contact Micro Focus for more information on using existing makefiles.
  • OpenESQL Assistant
    The OpenESQL Assistant data source names (DSNs) in Enterprise Developer must be configured as ODBC or XDB DSNs.
  • SQL Compiler Directive Options
    When you upgrade your to Enterprise Developer, some SQL applications could require additional SQL Compiler directive options to avoid compiler errors.
  • XML PARSE Statement
    In Net Express, 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 Enterprise Developer, the default is XMLPARSE(XMLSS), which returns information and events for IBM Enterprise COBOL Version 4.
Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


Output File Formats

Supported file formats - .exe and .dll

Each project compiles into a single file (.dll, .so or .exe), or to multiple files of the same file type with one output file for each source file (.dll, .so, .exe, .int, or .gnt). As well as an .lbr file, which contains a collection of .int and .gnt files on Windows, you now can use a .dll as the container for application components.

Building to multiple output files

Each project compiles into a single file (.dll, .so or .exe), or to multiple files of the same file type with one output file for each source file.

Instead of an .lbr file, which contained a collection of .int and .gnt files on Windows, you now use a .dll as the container for application components.

Your application can consist of multiple projects, each one building a single output file, with the projects linked together so that they can access each other. This is how you link to files outside of your project:
  1. Click File > New > Other.
  2. Expand General and click File.
  3. Enter the name to use for the linked resource. You can enter an alias.
  4. Click Advanced.
  5. Select Link to file in the file system and browse to the file to link. You can also click Variables and define a path variable, so that you can link to files using a relative path.
Parent topic: Compiling and Building Differences


Compiler directives

When you upgrade your source code to Enterprise Developer 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

COBOL programs that interface with Assembler modules must be compiled with the AMODE directive. The AMODE directive was set by default in MSS; it is not set by default in Enterprise Developer.

Parent topic: Compiling and Building Differences
Related information
Compiler Directives


Linking

The static run-time system and the single-threaded run-time system on Windows are no longer required and they are not shipped with Enterprise Developer. Applications built with Enterprise Developer are now linked to the shared or dynamic run-time systems. On UNIX, you can link to the single-threaded or multi-threaded shared or dynamic run-time system.

Linking from the command line

You can link applications from the Enterprise Developer command prompt with the cbllink or cblnames commands. For example, to produce an .exe file, use:

cbllink myprogram.cbl

To compile and link your code to produce a .dll file, use:

cbllink -d myprogram.cbl

With these commands, the single-threaded and static-linking options are automatically mapped onto the multi-threaded and shared run-time systems respectively.

Linking from the IDE

To specify what to link:

  1. Click Project > Properties.
  2. Expand Micro Focus > Build Configurations.
  3. Click Link and specify your link settings.
Parent topic: Compiling and Building Differences
Related information
Command line reference


Called Programs and Dependencies

At run time, called programs are found in the same way as before. However, there are some new ways to set COBPATH and copy files into a common folder.

To build the called programs

When you build the called programs into a .dll or .so file, you can set a property to output the built file into the same folder as the main application executable. To do this the called programs and the application main program must be in the same project. To set this:

  1. Create a project that contains the programs that are called.
  2. In the project properties, expand Micro Focus > Build Configurations and click COBOL.
  3. In Target Settings, select Single Native Library File.
  4. Set the Output Path to the subfolder where the main application executable is output.
  5. If you want to debug the .dll file together with the application, expand Override COBOL project settings, check Enable configuration specific settings, and ensure Compile for debugging is checked.
  6. Click Apply and then click OK.
  7. Build the project.

To set the COBPATH environment variable

Add the COBPATH environment variable to the run-time configuration, as follows:

  1. In the properties of the calling application project, expand Micro Focus > Run-time Configuration > Environment Variables.
  2. Click Add to add the COBPATH variable and specify the full path to your called files.
Parent topic: Compiling and Building Differences


File Handler

The File Handler .obj files are not available in Enterprise Developer. Enterprise Developer uses the File handler packaged in the mffh.dll file instead.

If the application you are upgrading from Net Express used the File Handler .obj files, when you link your application in Enterprise Developer the linker will emit a warning. The application will continue to operate as before provided that you supply the mffh.dll file with it.

Parent topic: Compiling and Building Differences


Makefile Conversion

You cannot use existing makefiles from inside Enterprise Developer for Eclipse without changing some Eclipse defaults and adopting a modified build process. Where makefiles invoke commands supported by Enterprise Developer they will continue to work as before. Please contact Micro Focus for more information on using existing makefiles.

Enterprise Developer for Eclipse uses an ANT script, .cobolBuild, to build COBOL projects. This script is automatically generated from the .cobolProj project file. It is not possible to configure the IDE so that it uses existing external build scripts (such as makefiles, msbuild, shell scripts or others) for building COBOL applications.

You can still use existing build scripts to build COBOL applications outside of the IDE. You can set your own shell scripts as pre-build and post-build events and they will execute as part of the .cobolBuild ANT script before or after compiling.

  1. Right-click on your project in the Navigator view and select Properties.
  2. Expand Micro Focus COBOL > Build Configurations and click Events for the desired configuration.
  3. Type the code of the script in the Pre-build event command line field or Post-build event command line field.
  4. Click Apply and then OK.

To set pre-build and post-build events:

Please contact Micro Focus for more information on using existing makefiles.

Parent topic: Compiling and Building Differences


OpenESQL Assistant

The OpenESQL Assistant data source names (DSNs) in Enterprise Developer must be configured as ODBC or XDB DSNs.
Parent topic: Compiling and Building Differences


SQL Compiler Directive Options

If you get errors in Enterprise Developer when compiling an object application that was created in Net Express , Server Express or Studio Enterprise Edition, 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 Net Express, 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 Enterprise Developer, the default is XMLPARSE(XMLSS), which returns information and events for IBM Enterprise COBOL Version 4.

To emulate the Net Express, Server Express behavior in Enterprise Developer, 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 Enterprise Developer documentation.

Parent topic: Compiling and Building Differences


Run-time System Differences

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

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

  • OpenESQL
    Enterprise Developer sets the BEHAVIOR SQL Compiler directive option to MAINFRAME by default to provide optimal performance. To revert to the default behavior exhibited in Net Express, Server Express, set the BEHAVIOR directive to UNOPTIMIZED.
  • Single-Threaded Run-Time System
    The single-threaded run-time system is not available in Enterprise Developer on Windows. Instead, both single-threaded and multi-threaded applications run using the multi-threaded run-time system. This has no effect on your existing applications. On UNIX, the single-threaded run-time system is available, so that applications can link with third-party code.
  • Static-Linked Run-Time System
    The static-linked run-time system is not available in Enterprise Developer. 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.
  • Enterprise Developer Co-existing with Earlier Micro Focus Products
    Some additional configuration is required to ensure Enterprise Developer and Studio Enterprise Edition work properly when installed on the same machine.
Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


OpenESQL

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


Single-Threaded Run-Time System

The single-threaded run-time system is not available in Enterprise Developer on Windows. Instead, both single-threaded and multi-threaded applications run using the multi-threaded run-time system. This has no effect on your existing applications. On UNIX, the single-threaded run-time system is available, so that applications can link with third-party code.
Parent topic: Run-time System Differences


Static-Linked Run-Time System

The static-linked run-time system is not available in Enterprise Developer. 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 Enterprise Developer for Eclipse 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


Enterprise Developer Co-existing with Earlier Micro Focus Products

If you have Enterprise Developer and Net Express or Studio Enterprise Edition installed on the same machine, you sometimes receive a run-time system error if either the COBCONFIG or COBCONFIG_ environment variable is set when you run Enterprise Developer applications the configuration file it refers to contains entries that are not valid for Enterprise Developer.

To work around this issue, ensure that Enterprise Developer 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 COBCONFIG_) or set it to another configuration file that does not contain the invalid tunable for the particular session you are running in.
Parent topic: Run-time System Differences


Restrictions and Unsupported Features

Some features in earlier Micro Focus products are not available in Enterprise Developer. However there are alternative techniques for many of these features.
  • CBL2XML Utility
    The CBL2XML utility is currently available as a command line tool only.
  • DBMS Preprocessors
    Earlier Micro Focus products supported DBMS preprocessor versions that are not supported in Enterprise Developer. For a list of currently supported DBMS preprocessors, see the Database Access Support with Native COBOL topic.
  • Dialog System
    Dialog System applications are not supported in Eclipse but you can upgrade the non-GUI components of an application to Eclipse, and then recreate the GUI components using the GUI tools in Eclipse.
  • Form Designer
    Form Designer is the Net Express tool for creating user interfaces for CGI-based Internet and intranet applications. Form Designer and the HTML page wizard are not available in Enterprise Developer.
  • GNT Analyzer
    GNT Analyzer is not available in Enterprise Developer. It has been replaced by Test Coverage.
  • Host Compatibility Option (HCO)
    Mainframe Express provided a user interface for the Host Compatibility Option (HCO) feature. This user interface is not available in Enterprise Developer; however the HCO Create Database, DDL Processor, DCLGEN, Export Data, and Import Data tools are available via batch command line invocation.
  • INTLEVEL Support
    The INTLEVEL directive is rejected by the Compiler in Enterprise Developer.
  • NSAPI
    There is no support for NSAPI in Enterprise Developer.
  • Online Help System
    Net Express provided the Online Help System for creating online help from character-based applications, and displaying it on screen. It is not available in Enterprise Developer and the Online Help System information file type (.HNF) is not supported.
  • OpenESQL
    In both Net Express and Studio Enterprise Edition, support is provided for Oracle OCI in OpenESQL. Enterprise Developer does not support Oracle OCI in OpenESQL.
  • SQL Option for DB2
    In the Mainframe Express and Net Express IDEs, you could invoke SQL Option for DB2 from the main menu within the IDE. For Enterprise Developer, SQL Option for DB2 is not available from the main menu in the IDE. Instead, all SQL Option for DB2 tools are available from Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2.
Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


CBL2XML Utility

The CBL2XML utility is currently available as a command line tool only.
Parent topic: Restrictions and Unsupported Features


DBMS Preprocessors

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


Dialog System

Dialog System applications are not supported in Eclipse but you can upgrade the non-GUI components of an application to Eclipse, and then recreate the GUI components using the GUI tools in Eclipse.
Parent topic: Restrictions and Unsupported Features


Form Designer

Form Designer is the Net Express tool for creating user interfaces for CGI-based Internet and intranet applications. Form Designer and the HTML page wizard are not available in Enterprise Developer.

In Enterprise Developer for Eclipse, you can install one of the available plug-ins to replicate these features.

Parent topic: Restrictions and Unsupported Features


GNT Analyzer

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


Host Compatibility Option (HCO)

Mainframe Express provided a user interface for the Host Compatibility Option (HCO) feature. This user interface is not available in Enterprise Developer; however the HCO Create Database, DDL Processor, DCLGEN, Export Data, and Import Data tools are available via batch command line invocation.
Parent topic: Restrictions and Unsupported Features


INTLEVEL Support

The INTLEVEL directive is rejected by the Compiler in Enterprise Developer.

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 Enterprise Developer.
Parent topic: Restrictions and Unsupported Features


Online Help System

Net Express provided the Online Help System for creating online help from character-based applications, and displaying it on screen. It is not available in Enterprise Developer and the Online Help System information file type (.HNF) is not supported.
Parent topic: Restrictions and Unsupported Features


OpenESQL

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


SQL Option for DB2

In the Mainframe Express and Net Express IDEs, you could invoke SQL Option for DB2 from the main menu within the IDE. For Enterprise Developer, SQL Option for DB2 is not available from the main menu in the IDE. Instead, all SQL Option for DB2 tools are available from Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2.
Parent topic: Restrictions and Unsupported Features


Run-Time Technology Differences

Some technologies behave differently in Enterprise Developer 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 Enterprise Developer and for Net Express and Server Express .
  • Java and COBOL
    The cobsje script is not available in Enterprise Developer for Eclipse on UNIX. Enterprise Developer 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. Code coverage for native COBOL applications available from within the IDE in Enterprise Developer integrates the Test Coverage functionality.
Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


File Handling

The way you integrate your own security modules into Fileshare has changed. Also, the FILEMAXSIZE setting is different for Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer for Eclipse on UNIX. Enterprise Developer 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. Code coverage for native COBOL applications available from within the IDE in Enterprise Developer integrates the Test Coverage functionality.

Test Coverage is also available from the command line.

Parent topic: Run-Time Technology Differences
Related concepts
Code Coverage


Editing and Debugging Differences

Much of the edit and debug functionality in Net Express, Server Express and Mainframe Express is available in Enterprise Developer, but some of it has a different name or slightly different behavior. In addition there are some new features such as background parsing.
  • Interface Mapping Toolkit
    The Interface Mapping Toolkit is available in Enterprise Developer for Eclipse; however it does not support CICS or IMS service interfaces.
  • Mixed Language Debugging
    With Net Express you could debug mixed language applications. In Enterprise Developer, you can debug native COBOL and Java or native COBOL and C with some additional configuration.
  • Program Breakpoints
    Program breakpoints are breakpoints that stop execution each time a specified program or entry point within the program is called. They are supported in Enterprise Developer, but by default their behavior is different from their behavior in Net Express
  • Remote Debugging
    The Net Express animserv utility used for debugging programs remotely has been replaced by cobdebugremote (or cobdebugremote64 when debugging 64-bit processes) in Enterprise Developer.
  • Source Pool View
    The source pool view in Net Express showed all source files available in the project directory, regardless of whether or not they are used in the current build type. This view is not available in Enterprise Developer.
Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


Interface Mapping Toolkit

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


Mixed Language Debugging

With Net Express you could debug mixed language applications. In Enterprise Developer, you can debug native COBOL and Java or native COBOL and C with some additional configuration.

To debug applications that contain programs in different languages, you need to debug the native COBOL and the non-COBOL code separately.

In Enterprise Developer for Eclipse, you can debug mixed native COBOL and Java using all COBOL target types.

You can debug native COBOL and C at the same time provided that the COBOL code has been compiled to .int code. In the COBOL Application debug configuration, you must uncheck the following option on the General tab and in the Debug Options section: Allow debugging of all COBOL target types (and disable mixed language debugging).

Parent topic: Editing and Debugging Differences


Program Breakpoints

Program breakpoints are breakpoints that stop execution each time a specified program or entry point within the program is called. They are supported in Enterprise Developer, but by default their behavior is different from their behavior in Net Express

In Net Express, a program breakpoint caused execution to stop only when the Procedure Division entry point is called, while in Enterprise Developer, a program breakpoint causes execution to stop on any entry point to the program and on return to the program from a call.

Parent topic: Editing and Debugging Differences


Remote Debugging

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

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

To debug remotely-developed programs on a remote machine:

  • You use a local Enterprise Developer installation to develop remote projects on a remote UNIX machine that has Micro Focus Enterprise Developer UNIX Components 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 Enterprise Developer for Eclipse product help.

Parent topic: Editing and Debugging Differences


Source Pool View

The source pool view in Net Express showed all source files available in the project directory, regardless of whether or not they are used in the current build type. This view is not available in Enterprise Developer.

Parent topic: Editing and Debugging Differences


Tips: Eclipse IDE Equivalents to IDE Features in Earlier Products

The following table shows Mainframe Express and Net Express IDE features and their corresponding equivalents and locations in Eclipse.

Functionality | In Mainframe Express | In Net Express | In Enterprise Developer for Eclipse
Project Control
Project filename | *.MVP | *.APP | .cobolProj in Project directory
Add file to project | To create a new file from the supported types in the project directory, click File > New, specify the type of file to create, and click OK. Click Project > Add Files to add existing files to the project. | To create a new file from the supported types in the project directory, click File > New, specify the type of file to create, and click OK. Click Project > Add Files to Project to add existing files to the project. | All files in the project directory and its subdirectories are automatically part of the project. You can exclude programs or subdirectories from a build using the Build Action option on the context menu.
Copybook path | Via Workgrouping | Click Project > Properties, then click IDE and specify the COBCPY environment variable. | By default, all directories within a project and their subdirectories are included in the initial copybook path. To make changes, click Project > Project Properties > Micro Focus > Build Path and select the Dependency Paths tab.
Build settings for the project:
  • COBOL
  • CICS including BMS
  • Preprocessor
  • Additional directives
ALT+F7 or click Project > Build Setting for Project and select the corresponding tabs. ALT+F7 or click Project > Build Setting and select the corresponding tabs. Right-click the project name and select Properties, (or click Project > Properties from the main menu).
Execution environment settings:
  • General
  • Assembler
  • COBOL
  • JCL
Click Project > Project Settings and then click the Execution tab The execution environment is Micro Focus Server. The execution environment is Enterprise Server.
Debug settings:
  • DateWarp
  • Stored Procedures
  • Click Debug > DateWarp.
  • Click Debug > Debug Settings and check Enable Stored Procedures Debugging.
  • Click Debug > DateWarp.
DateWarp is present in the debug launch configurations.
Editing
Suggest Word/Content Assist | CTRL+G | CTRL+G | CTRL+Space
Locate | F12 (or context menu Locate) | F12 (or context menu Locate) | F3 (or context menu Goto Definition)
COBOL Find | CTRL+Shift+F12 (or context menu COBOL Find) | CTRL+Shift+F12 (or context menu COBOL Find) | CTRL+Shift+G (or context menu Find References)
Compress | Tool bar compress Tool Bar Compress (or context menu Compress) | Tool bar compress Tool Bar Compress (or context menu Compress) | Double-click on an item in the search result to jump to the line in the program.
Bookmark | CTRL+F2 | CTRL+F2 | Click Edit > Add Bookmark.
Compiling
Single file Compile CTRL+F7 (or click check mark Check Mark) CTRL+F7 (or click check mark Check Mark) Right-click a program name and select Single File Compile.
Note: This applies to native code only.
Build | F7 (or click build Build) | F7 (or click build Build) | By default, Eclipse automatically builds projects to keep them up to date. You can also build on request. To turn off the automatic build, click Project > Build Automatically.
Build All | ALT+B A | ALT+B A | Cleaning a project forces a rebuild. To access this, click Project > Clean.
Debugging
Start Debugging | Alt+D A | Alt+D A | Choose Debug or F11 Before launching the session, create an appropriate debug launch configuration.
Stop Debugging | Shift+F5 | Shift+F5 | CTRL+F2 (or context menu Terminate) Terminate
Restart Debugging | Ctrl+Shift+F5 | Ctrl+Shift+F5 | From the executable in the debug stack view, right-click and select Relauch from the context menu.
Run | F5 | F5 | CTRL+F11
Step | F11 (or click step Step) | F11 (or click step Step) | F5
Step All | Ctrl+F5 | Ctrl+F5 | Click Resume Resume on the debug toolbar.
Run Thru | F10 | F10 | F6 (or Step Over Step Over)
Run Return | Shift+F11 | Shift+F11 | F7 (or Step Return Step Return)
Run to Cursor | Shift+F10 (or context menu) | Shift+F10 (or context menu) | CTRL+R (or context menu Run to Line Run to Line)
Skip to Cursor | CTRL+Shift+F10 | CTRL+Shift+F10 | ALT+F12, R (or Reset Execution Point Reset Execution Point)
Skip Statement | ALT+D, I or click Debug > Skip Statement . | Click Debug > Skip Statement. | No equivalent. Use ALT+F12, R (or Reset Execution Point Reset Execution Point)
Skip Return | ALT+D, K or Click Debug > Skip Return | Click Debug > Skip Return. | No equivalent. Use ALT+F12, R (or Reset Execution Point Reset Execution Point)
Examine ' data item' | Shift+F9 | Shift+F9 | The Variables View automatically shows variable values on the current and previous lines.
Breakpoint set | F9 | F9 | Double click in the left margin to toggle a breakpoint.
Conditional Breakpoint | Click Debug > Breakpoint > Set Advanced. | Click Debug > Breakpoint > Set Advanced. | From the Breakpoints View, select a breakpoint and edit the properties.
Break on Data Change | Via list view | Via list view | To set a WatchPoint, double-click in the margin of line containing a WS item, or set it from the Outline View context menu.
Parent topic: Differences between Enterprise Developer and Net Express, Server Express and Mainframe Express


Upgrading from ACUCOBOL-GT

There are conceptual and behavioral differences between Enterprise Developer and ACUCOBOL-GT, part of the Micro Focus extend® product family, and these differences can affect the way you upgrade existing applications to Enterprise Developer.
Refer to the Compatibility with ACUCOBOL-GT section for guidance and best practice on moving your applications to Enterprise Developer. It covers:
  • Supported ACUCOBOL-GT features, including detailed information on support for compiler options and standard library routines.
  • Syntactical differences between the two COBOL dialects, including workarounds or equivalent syntax where applicable.
  • Detailed support of compatible ACUCOBOL Windowing syntax.
  • Details on how to configure your applications to continue using your Vision data files.
  • Details on converting your GUI projects using an import wizard (AddPack required).
Parent topic: Upgrading to Enterprise Developer for Eclipse
Related information
Compatibility with ACUCOBOL-GT


Upgrading from RM/COBOL®

There are a number of settings in Enterprise Developer that are designed specifically to ensure that your existing RM/COBOL source code can compile and run in Enterprise Developer.

Refer to the Compatibility with RM/COBOL section for guidance and best practice on moving your applications to Enterprise Developer. It covers:
  • Supported RM/COBOL features, including detailed information on support for data types and subprograms.
  • Syntactical differences between the two COBOL dialects, including workarounds or equivalent syntax where applicable.
  • Details on how to configure your applications to continue using your RM/COBOL data files.
Parent topic: Upgrading to Enterprise Developer for Eclipse
Related information
Compatibility with RM/COBOL


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. This is the COBOL that will have been 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 COBOL the compiler generates managed code: .class or .jar for JVM which will run 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 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 JVM 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 Enterprise Server.

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

Parent topic: Upgrading to Enterprise Developer for Eclipse
Parent topic: Getting Started


Overview of application development in Eclipse

Enterprise Developer is a contemporary development suite for Eclipse that allows mainframe developers to maintain, develop and modernize mainframe applications regardless of whether these are to be deployed back on the mainframe or onto alternative platforms.

When you develop applications in Eclipse, you use Eclipse features such as perspectives and views, as well as background checking of syntax and build, debug and run configurations. Like in other Micro Focus products, you use specific project types, familiar functionality for editing and debugging, and comprehensive help.

You can develop COBOL applications locally where source code and the Eclipse IDE are hosted on your client machine or, remotely, where you use a remote server to host your source code and use the Eclipse IDE on your local machine as the development interface.

The features of this development environment include, for COBOL:

  • Perspectives to show the appropriate panes and views in the IDE such as the COBOL and Debug perspectives.
  • Editing that supports:
    • Background parse for syntax checking
    • Code templates by pressing ctrl space
    • Program outline view
    • Copybook Dependency view
    • Code completion
    • Collapse/expand of copybooks and tagged lines
    • Code colorization
  • Project handling, such as:
    • Automatic building
    • Dependency checking
    • ANT as the engine
    • Build Precedence ordering for directories
    • SQL directive support
    • Multiple build configurations
  • Debug configurations, which you can reuse for different debugging scenarios. For example, you can have one configuration for debugging a local application and one for a remote application. These include:
    • Attach to local process
    • Core dump
    • Enterprise Server service debugging
    • Remote application (including 64bit)
    • Wait for application
    • Attach to a remote running application. This allows you to attach a debugger to an already running remote COBOL application
    • Wait for attachment. This process starts a debugger and waits for a remote COBOL application to attach
  • Debugging using features such as:
    • Breakpoints
    • Expressions view
    • Stack trace
    • Stepping
    • Variables view
    • Watchpoints

Tutorials

There are a number of tutorials that guide you through creating mainframe and COBOL applications using the Eclipse IDE. The source files for some of the tutorials are installed in subfolders of the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples folder by default.

To complete the remote mainframe development tutorial you must download the supporting files from the Micro Focus Web site at http://supportline.microfocus.com/examplesandutilities/zEntTutorial.aspx.

Parent topic: Welcome
Related information
Developing Applications in the IDE
List of Tutorials


Overview of Remote Mainframe Development

Enterprise Developer for z Systems enables users to edit, compile and execute jobs directly on the mainframe all directly from within the Eclipse IDE. It also allows you to model your mainframe development process directly into Eclipse without the need for custom Java plug-in development. This functionality is provided by the following additional components:

z/Server
is a z/OS server program that allows Enterprise Developer users to develop directly on the mainframe. The z/Server is a mainframe-started task which needs to be installed on your mainframe to enable remote development on the mainframe.
z/Server is now installed as part of the Mainframe Access Server installer. Existing customers need to perform a full Mainframe Access Server installation in order to update to the latest version of z/Server.
Two manuals are provided with this product help to assist you with the z/Server installation - see Related reference:
  • Mainframe Access Installation Guide - see Configuring z/Server feature support
  • z/Server Messages and Diagnostics
Application Workflow Manager
is available within all Enterprise Developer variants and provides all the capabilities and tools to develop and maintain Application Workflow models. These models allow you to integrate tools and processes directly into Enterprise Developer.
You can use the Application Workflow Manager with the following products:
  • Enterprise Developer - the Enterprise Developer setup file automatically installs the Application Workflow Manager.
  • IBM Developer for z Systems (IDz) - see the topic Installing Application Workflow Manager into IBM Developer for z Systems (IDz) in this product help. This requires that Enterprise Developer Connect is installed and licensed.

The following manuals are provided with this product help to assist you with using and configuring the Application Workflow Manager component:

  • Workflow Manager Modelling Guide
  • Workflow Manager Troubleshooting
  • Workflow Manager Messages

For training about how to use a workflow modeller, contact Micro Focus Professional Services.

Enterprise Developer for z Systems is compatible with IBM System zEC12 mainframe hardware and later.

Parent topic: Welcome
Related reference
Application Workflow Manager
Known Issues
Mainframe Access Installation Guide
Tutorial: Remote mainframe development
Workflow Manager Messages
z/Server messages and Diagnostics


Enterprise Developer Tutorials Guide

There are a number of tutorials that guide you through creating mainframe and COBOL applications using the Eclipse IDE. The source files for some of the tutorials are installed in subfolders of the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples folder by default. On older versions of Windows the samples might be installed in a different folder, such as for Windows XP, C:\Documents and Settings\All Users\Documents\Micro Focus\Enterprise Developer\Samples. These can be installed but are not supported.

The following tutorials are available:

Getting started

Tutorial | Shows you how to
Getting started with Micro Focus Enterprise Developer for Eclipse | Developing and maintain mainframe applications in the Eclipse IDE. An introduction in using Enterprise Developer for offline development.
Tutorial: Remote mainframe development | Develop, maintain and test mainframe applications directly on the host, using the Eclipse IDE.

Tutorials on the mainframe subsystem

Tutorial | Shows you how to
Tutorial: Assembler | AACT is a sample CICS 3270 transaction that comprises several Assembler programs and a single BMS map, and uses the resource definitions in the file dfhdrdat. This tutorial walks you through the steps required to implement and test the AACT transaction.
Tutorial: CICS | Create a CICS project in Eclipse. You associate the project with Enterprise Server, deploy the CICS application to the server and debug in Eclipse.
Tutorial: Web-enabled CICS Acting as a Web Server | Create a Web-enabled version of a CICS project in Eclipse.
Tutorial: Web-enabled CICS Acting as a Web Client | Create a CICS Web client project in Eclipse.
Tutorial: JCL | Create a JCL project in Eclipse and submit it to an Enterprise Server.
Tutorial: DSNREXX | Execute DB2 statements from within a DSNREXX procedure.
Tutorial: IMS Support | Create an IMS project in Eclipse and deploy the application to an Enterprise Server.
Tutorials: CICS Web Services | Generate and run several CICS Web services.

Tutorials on native COBOL

Tutorial | Shows you how to
Tutorial: Creating a Native COBOL Application | Develop and maintain native COBOL applications in Eclipse. This is a basic tutorial introducing the Eclipse IDE.
Tutorials: OpenESQL Assistant | Configure OpenESQL Assistant to enable the build and testing of an SQL query and embed it into a COBOL program.
Tutorial: Running Unit Tests in the IDE | Create a unit test project, then within it create a test case that directly links to one of the sample applications supplied with Enterprise Developer. This enables you to directly test your application source code.
Tutorial: Interface Mapping Toolkit | Create a project to define a Java or Enterprise JavaBean service interface to access a COBOL application and deploy the service to an enterprise server. Create, deploy and run a JSP client to access the service.
Tutorial: Data File Tools | View a variable length sequential file formatted and unformatted, and then create and edit an indexed file.
Tutorial: Classic Data File Tools | Convert a data file to a variable length indexed sequential file and view in various formats using Data File Editor.
Tutorial: Using the Callable File Handler | Use the Callable File Handler to perform a number of common file handling operations.

Tutorials on managed COBOL

Tutorial | Shows you how to
Tutorial: Creating COBOL JVM Applications in Eclipse | Create and debug a simple JVM COBOL application in Eclipse.
Tutorial: Deploying JVM COBOL to an Application Server | Reuse existing JVM COBOL logic within an Enterprise JavaBean, then deploy it to an application server.
Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server | Reuse an existing SQL Server COBOL application using the Red Hat JBoss application server.
Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface | Create an application to create, read, modify, and delete contact information from a file. The interactions are made through a user interface created using the JavaFX library.
Tutorial: Packaging JVM COBOL | Create, compile, and package JVM COBOL to be used as a library in another project.
Tutorial: Compiling a COBOL Program to JVM Byte Code | Compile a COBOL Program to JVM byte code.

Tutorials on Web services

Other tutorials that include in-depth descriptions of how to deploy an existing COBOL application as a Web service within the JBoss Application Server, and how to use a COBOL program in a JVM JSP application, are available on the Micro Focus Community Web site.

Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment | Use a COBOL program in a JVM JSP application.
Tutorial: Reusing Existing SQL Programs in a Java Environment | Reuse an SQL COBOL application using an SQL Server and the Tomcat 7 application server.

Tutorial on PL/I programming

Tutorial | Shows you how to
Tutorial: Developing a PL/I application using Eclipse | Create PL/I mainframe projects and submit JCL in Eclipse.

Tutorial on Application Workflow Modeller

Tutorial | Shows you how to
Tutorial: Creating an AWM Model with AWM Element Types | Walks you through the process of creating an AWM model that uses AWM element types to create a workflow that integrates an issue tracking system into your workbench
Tutorial: Creating an AWM Model with AWM Linked Element Types | Walks you through the process of creating an AWM model that uses AWM linked element types from the Eclipse function package.
Tutorial: Adding a New Action to an Existing AWM Model | Walks you through the process of adding a new context menu to an existing AWM model. In this case, you will modify the project's model.

Tutorials for the AppMaster Builder

These tutorials require that you have installed the AppMaster Builder AddPack.

Tutorial | Shows you how to
Tutorials: AppMaster Builder | Use AppMaster Builder to create a program and screen for an online application, generate the application code, compile the code, and run the application.
  • Getting Started
Parent topic: Welcome


Getting Started

  • Mainframe Tutorials
    This section contains tutorials for developing on a mainframe, including how to develop CICS, IMS, JCL and Open PL/I applications.
  • Native COBOL Tutorials
    This section contains tutorials covering the production of native COBOL.
  • Managed COBOL Tutorials
    This section contains tutorials covering the production of managed COBOL.
  • Web Services Tutorials
    This section contains tutorials covering web services.
  • 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: Enterprise Developer Tutorials Guide
Related concepts
Features Added in Enterprise Developer 2.1
Compiled File Types
Delegates and Events
IBM External Call Interface (ECI)
Starting the debugger automatically using just-in-time debugging


Mainframe Tutorials

  • Getting started with Micro Focus Enterprise Developer for Eclipse
    This set of tutorials guides you through the use of Micro Focus Enterprise Developer for Eclipse. They provide a basic understanding of how the product operates.
  • Using the Rumba Screen Designer
    If you use Rumba for terminal emulation, you can use the Rumba Screen Designer to customize host sessions and provide a modern interface with new features and capabilities.
  • Tutorial: Remote mainframe development
    Enterprise Developer for z Systems allows you to use the Eclipse IDE to edit, compile and test mainframe applications directly on the host, as well as providing a full-function mainframe development environment under Windows. In this tutorial, we will demonstrate some of the remote mainframe development capabilities.
  • Tutorials: HCO for SQL Server (HCOSS)
  • Tutorial: Assembler
  • Tutorials: CICS
  • Tutorials: IMS
    Includes tutorials for basic IMS support features and for using the IMS Segment Layout Editor and IMS Database Editor data tools.
  • Tutorial: JCL
    This tutorial takes you step by step through the process of configuring an enterprise server to run JCL applications, and then deploying and running a JCL application. This is intended both as an introduction to using JCL with the Enterprise Developer and Enterprise Server environments and as an Installation Verification Procedure (IVP) to confirm that JCL support is correctly installed.
  • Tutorial: DSNREXX
    This tutorial shows how to execute DB2 statements from within a DSNREXX procedure. This is done by creating a JCL project and then associating it with an XA resource, enabling you to run a DSNREXX procedure using sample JCL provided with Enterprise Developer.
  • Tutorials: PL/I
  • Tutorials: AppMaster Builder
    Define a basic online application using AppMaster Builder; then generate code, compile the code, and run the application.
Parent topic: Getting Started


Getting started with Micro Focus Enterprise Developer for Eclipse

This set of tutorials guides you through the use of Micro Focus Enterprise Developer 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 Eclipse Integrated Development Environment (IDE). The tutorials provide a basic understanding of the features offered in Enterprise Developer 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, %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples 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\Enterprise Developer\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 %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\BankDemo\MFETDUSER folder into the new C:\MFETDUSER folder.

As part of this tutorial, you use the supplied standard Eclipse COBOL project in the sample to set up a development environment for this application. The tutorials show how you can:

  • Create a project for your application
  • Edit the source files
  • Compile the source code
  • Execute and debug the application

Prerequisites

You must have the following software installed:

  • Micro Focus Rumba or an equivalent TN3270 terminal emulator is required to run the CICS application.
    Note: A license for Micro Focus Rumba is included with Enterprise Developer. If you do not have Rumba 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: Windows XP is not officially supported. If you are, however, using Microsoft Windows XP and have installed Service Pack 2, you might find that you cannot see certain Enterprise Server Administration pages, because of firewall restrictions. To get round this, you need to enable access to the ports you are using, for example, 86 for the Enterprise Server Administration Home page and 9003 for the default enterprise server, ESDEMO. Use the Windows Security Center to do this.
  1. Starting the Eclipse Integrated Development Environment (IDE)
    The main Eclipse window includes a number of views. The views and their layout depend on whether you have used Eclipse before. You can move, resize and minimize views which is why they might not look exactly as described here.
  2. Creating a Project and Adding the Source Files
    You are going to use the project supplied with the BankDemo sample as a template to create a project for this demonstration. You will then add the source files to the project to be able to build, develop and test the application.
  3. Editing Source Files
    This topic describes the editing features for the various file types (COBOL, JCL, IMS, BMS, and Data Files).
  4. Compiling the Source Code
    By default, the Eclipse IDE is set to build projects automatically. Whenever you add new COBOL or BMS files to the Bankdemo project, the IDE starts an automatic build (compilation).
  5. Unit Testing the Batch Application
    The first thing you need to do is check that the Bankdemo application is executing correctly.
  6. Unit Testing the Online Application
    In the previous step, Unit Testing the Batch Application, you used the Bankdemo enterprise server. You are going to use it again for online testing.
  7. Debugging the Batch Application
    You are going to debug the batch Bankdemo application.
  8. Debugging the Online Application
    You are going to debug the online Bankdemo Application.
Parent topic: Mainframe Tutorials


Starting the Eclipse Integrated Development Environment (IDE)

  1. To start the Eclipse IDE, click Start > All Programs > Micro Focus Enterprise Developer > Enterprise Developer for Eclipse.

    This opens the Eclipse Launcher which enables you to choose a location for Eclipse to store your projects.

  2. Specify C:\MFETDUSER\BankDemo\Projects\Eclipse in the Workspace field and click Launch.

    If this is the first time you start Enterprise Developer, you are presented with the Eclipse Welcome page. Click Open Team Developer Perspective to close the Welcome page and see the main Eclipse window.

    If the Welcome page is not opened, click Window > Perspective > Open Perspective > Other, select the Team Developer (default) and click Open.

    The views you see open in Eclipse and their layout depend on whether you have used Eclipse before. You can move, resize and minimize views which is why they might not look exactly as described here. If this is the first time you have used Eclipse, you should see the following views in the IDE, although most of the views are currently empty:

    • The Application Explorer view in the upper left part of the IDE gives a logical view of your applications. You are going to use the Application Explorer view most of the time. This tree view should already display an Enterprise Developer system entry. If not, right-click in this view, select Add System(s) and then select ED System and click OK. This view now displays a system entry used to support the standard Enterprise Developer projects. Expand this system entry and an application entry named Enterprise Development Projects is displayed. Right-click this application entry and select Load Application. If you are using this Eclipse workspace for the first time, there are no projects associated with this application.
    • The Properties, Outline, and Program Outline tabbed views in the bottom left part of the IDE provide more information about selected tree or table entries, and outline information on various types in your sources when you start editing COBOL or PL/I programs or JCL.
    • A series of tabbed views in the bottom right part of the IDE (Table Results view, Error Feedback view, Jobs view, File Mappings view, Console, Problems, Tasks) show for example sources in a table structure, the results of compiling and tasks.
    • The IDE provides a Server Explorer view, where you can view the underlying execution environment. This view is displayed as a tab in the upper left part of the IDE.
    • The Filter Definitions view in the upper right part of the IDE is used to manage search criteria within a loaded application.
    • The Remote Systems view is used to connect to the mainframe system z/OS and provides access to all mainframe resources like MVS or USS files and MVS jobs. This view is displayed as a tab in the upper right part of the IDE.
    • The main activity window in the top middle part of the IDE, the Editor, is where you edit or debug the sources.
    • Apart from the Eclipse menus, there are a number of buttons on the toolbar, which vary depending on what you are currently doing with Eclipse.
  3. Experiment with resizing, minimizing and restoring the views.
  4. If you close a view, click Window > Show View > View Name to restore it.
  5. At any time, you can reset the complete layout of the Team Developer Perspective to its default using Window > Reset Perspective.
Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Next topic: Creating a Project and Adding the Source Files


Creating a Project and Adding the Source Files

You are going to use the project supplied with the BankDemo sample as a template to create a project for this demonstration. You will then add the source files to the project to be able to build, develop and test the application.

The source files of the demonstration application are stored in subfolders named after the file type (for example, bms, cbl, copybook, jcl) in the C:\MFETDUSER\Bankdemo\Sources directory.

Creating a Project for the BankDemo application

You use the BankDemo project supplied with the sample to create your project in the Eclipse workspace that has the same settings as the sample project:

  1. In the Application Explorer view, right-click Enterprise Development Projects, which is the node for the standard application.
  2. Click New Project from Template.

  3. Click Retrieve next to Template Path.

  4. Browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\Bankdemo\Workspace\Bankdemo folder, and click OK.
  5. Type Bankdemo in the project name field and click OK.

    This creates a copy of the Bankdemo project in your Eclipse workspace and adds the project to the application in the Application Explorer view. If the Bankdemo project entry is not displayed in the tree view, refresh the Enterprise Development Projects entry.

  6. Expand the Bankdemo project in the Application Explorer view.

The Bankdemo Project

Your project is pre-configured so that the build process creates the output files in a location that is used by the Enterprise Server logical server. To check which folder will include the built files:

  1. In the Application Explorer view, right-click the Bankdemo project, and click Properties.
  2. Expand Micro Focus, Build Configurations and then click COBOL.
  3. Note that the Output Path field points to the loadlib directory which will be created in the project directory at build time.
  4. You can cancl the project properties dialog box.

Adding the Demo Source Files

In most cases, to add files to an Eclipse project, you use the Import command. This creates local copies of file sources in the workspace. Optionally, you can leave the source files in the original location and create links to them. To do this:

  1. In Application Explorer view, right-click the Bankdemo project, and click New > Folder> Folder.
  2. Click Advanced and check Link to alternate location (Linked Folder).
  3. Browse to C:\MFETDUSER\BankDemo\Sources, and click OK.
  4. Click Finish.

    This adds the folders storing the source files to your project as linked resources:

    By default, Eclipse is set to build projects automatically (see Project > Build Automatically), so it immediately compiles the files you have just added.

    Check the Console and Problems views and see that some of the programs failed to compile. In Application Explorer view, you can select a program and check the error and warning count property in the Properties view to indicate that there are compilation problems.

    The errors are due to the correct copybook paths not being specified in the project properties.

Setting Compiler Directives

To perform a scan of the COBOL programs in your project to determine and then set the appropriate Compiler directives:

  1. Right-click Bankdemo and click Determine Directives.

    The IDE performs a scan of the files and shows a report of what directives for dialect and for CICS must be set on the programs in your project in order for them to compile cleanly.

  2. Click OK to set the directives.

    If you are prompted to delete some user files, choose No.

Setting the missing Compiler directives triggers a full rebuild of the project. There are still some errors in the COBOL sources due to the fact that the project cannot resolve the paths to the copybook files.

Specifying the Copybook Paths for the Project

To specify the copybook paths for the project:

  1. In Application Explorer view, right-click the Bankdemo project, and click Properties.
  2. Expand Micro Focus, and then click Build Path.
  3. Click the Dependency Paths tab and ensure Type is set to COBOL Copybook Paths.
  4. Check the Bankdemo/Sources/copybook entry in the list, and then click Apply and Close.

    Eclipse rebuilds the project and now all COBOL programs should compile cleanly.

Adding Data Files

The demonstration application includes a number of data files used. To see how you can edit data files, you only need to look at one of these files so you do not need to add a folder for it to the project. To add the data file to your project:

  1. In the Application Explorer view, right-click the Bankdemo project and click New > File > Other File.
  2. Click Advanced and check Link to file in the file system.
  3. Browse to the C:\MFETDUSER\BankDemo\System\catalog\data folder.
  4. Select EBC.BNKACC.DAT, and then click Open.
  5. Click Finish.

    This adds the file to the Bankdemo project and also automatically opens it in the Micro Focus Data Files Tools utility. You can close the utility for now.

  6. Repeat steps 1 to 5 to add the following files to the project:
    • EBC.BANKACC.PRO
    • EBC.BNKACC.STR

Summary

You created an Eclipse project and added references in it to the COBOL files, the copybooks, the BMS and the JCL files of the demonstration program.

Next, you are going to edit some of these source files.

Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Previous topic: Starting the Eclipse Integrated Development Environment (IDE)
Next topic: Editing Source Files


Editing Source Files

This topic describes the editing features for the various file types (COBOL, JCL, IMS, BMS, and Data Files).
Important: We recommend that you create backup copies of all files before you start editing them.

Editing COBOL Files

You are going to explore some of the COBOL editing features using the ZBNKPRT1.cbl program which produces a report from a sequential data file.

  1. In the Application Explorer view, double-click ZBNKPRT1.cbl in the Sources/cbl folder of the project.

    This opens the file in the COBOL editor in Eclipse.

Copybooks
  1. Scroll down the file until you see some COPY statements.
  2. Press F4 to open the file in COBOL Copy View, which shows the code of the copybooks expanded in the source file.

    The COBOL Copy View is read-only and you cannot edit the code in it. The screen background changes from white to pale yellow.

  3. Press Ctrl+F4 to close the COBOL Copy View.
  4. To edit a copybook, position the cursor on the COPY statement and press F3 (Go To Definition).

    This opens the copybook file in a new tab in the editor.

Copybook Dependencies
By expanding a source file node in the Application Explorer view, you can see a list of all copybooks referenced in the source code, and nested within them any other copybooks referenced by those copybooks. Double-click a copybook to open it in the editor.

Use the Copybook Dependency view to show where in the source file's structure the COPY statements appear, and which copybooks they reference. If the Copybook Dependency view is not displayed in the Team Developer perspective, to open this view click Window > Show View > Other > Micro Focus > Copybook Dependency.

Copybook Dependency view

Click a copybook reference in the Copybook Dependency view to locate the associated COPY statement at the appropriate line in the source code.

Unused data
Notice that some data items in the Data Division are crossed out. This is because they are not referenced in the Procedure Division.
Program outline
  1. Right-click anywhere in the COBOL editor and select Quick Outline.

    This opens a pop-up with the outline of the program similar to what the Outline view shows.

  2. Press Ctrl+O in the pop-up to see a more detailed outline similar to the Program Outline view.
  3. Double-click an item in the outline to see how the cursor positions itself on the line of code that this outline item refers to.
  4. Click on the permanent Outline view.

  5. Expand and collapse various lines in the Outline view.
  6. Double-click items in the Outline view to see how the cursor positions itself on the respective line of code that each one of these outline items refers to and highlights the referenced item in the editor window.
  7. Click the Sort button ( [image]) for the Outline to toggle between a physical or alphabetical sequence.
Hyperlinks
  1. In the editor, scroll down the file to a line in the Procedure Division.
  2. Press and hold Ctrl and move your mouse around the code.

    This turns the data items and the paragraph names you hover over into hyperlinks.

  3. Click one of the hyperlinks to position the cursor on the definition of the respective data item or paragraph.
Viewing data definitions
  1. Hover over a data item in the Procedure Division to see information about the data item and how many times it is used in the program.
  2. Clicking a data item or paragraph name highlights all their occurrences in the code.
Breadcrumbs
The Toggle Context Breadcrumbs icon ( [image]) in the toolbar lets you see another view of the program showing the copybooks.
  1. Click the icon to enable breadcrumbs.

    This opens a new toolbar in the editor with the name of your COBOL program.

  2. Click the arrow to the right of the program name to see a list of copybooks the program uses.
  3. Click one of these copybooks to load it in a new tab in the editor.
Marking text and block mode
You can either use the mouse to mark a block of text or click Toggle Block Selection Mode to enable Toggle Block Selection Mode and select square blocks of text. When a selection is made, you can cut or copy it.
Rename
You can use rename refactoring to rename all occurrences of a variable:
  1. Scroll down to line 022000 in the file.
  2. Double-click WS-EXEC-PARM-LL to select it and click Refactor > Rename.

    A pop-up is displayed prompting you to enter a new name for the variable.

  3. Click the down arrow to show the context menu and click Open Rename Dialog.
  4. Specify WS-EXEC-PARM as a New name in the dialog box and click Preview.

    This opens the Rename COBOL Element dialog box that enables you to preview and approve

  5. Click Cancel as you are not going to apply these changes for this demo.

You can change your Eclipse preferences and rename without the Rename COBOL Element dialog box. To do this, go to Window > Preferences > Micro Focus > COBOL > Editor and uncheck Rename in editor without dialog.

Smart editing
Next, we are going to look at smart editing with background COBOL parsing. First you'll check the IDE preferences for suggestions that Content Assist offers you in the editor:
  1. Click Window > Preferences > Micro Focus > COBOL > Editor > Content Assist.
  2. Check Enable auto activation then click OK.
  3. Scroll down to line 025000 in the code and start typing the following, starting in area A of the code, one character at a time:
    MOVE W TO

    Notice how the words you type change in the editor. Once a word is recognized as a reserved word or a data item, its color changes. If a line of code contains invalid COBOL syntax, a red cross appears to the left of the line and the word is underlined with a wavy red line.

    Also, Content Assist automatically displays a pop-up with suggested keywords and names of data items appears as you type.

  4. Change the line to:
    MOVE 34 TO WS-

    If the IDE preferences for auto-activation of Content Assist have not been changed, Content Assist opens a list of potential data names that start with WS- to choose from. If Content Assist does not display a list, to open it manually click Ctrl+Space.

  5. Finally, if you have changed this COBOL program, copy the backup version back in again.
Renumbering the COBOL sources
You can use the commands Renumber and Unnumber to insert and remove line numbers from your code. Your sources include some comments beyond column 73, so you need to configure the line numbering in order to ensure you only apply changes to the COBOL sequence area:
  1. Click Window > Preferences > Micro Focus > COBOL > Editor > Line Numbering.
  2. Ensure that only the COBOL (left-hand margin) option is enabled.
  3. Click OK.

You can now remove the line numbers from your code:

  1. Right-click the ZBNKPRT1.cbl file in the editor, and click Source > Unnumber. Alternatively, click Unnumber in the Eclipse toolbar.

    This removed the line numbers from the COBOL sequence area.

To reinsert the line numbers in your code:

  1. Right-click the ZBNKPRT1.cbl file in the editor, and click Source > Renumber. Alternatively, click Renumber in the Eclipse toolbar.

To insert line numbers beyond the end of area B:

  1. In the IDE preferences for line numbering, check Standard (right-hand margin).
  2. Click OK.
  3. Right-click the ZBNKPRT1.cbl file in the editor, and click Source > Renumber.

    You should now see line numbers running down both sides of the source code:

    COBOL line numbering
  4. Click Edit > Undo Typing as necessary to revert your changes to the file.

JCL and IMS editing

  1. Double-click the JCL file in the Bankdemo project to open it in the associated editor.

    The editor supports background parsing, syntax checking, content assist and an outline view like the COBOL Editor does.

    Note: You can open and edit DBD, PSB, and MFS files in the same way. The editors open these files in text view and offer a basic level of colorization for items such as reserved words and comments.

BMS editing

There are two ways to edit BMS files. The first one is to use the basic BMS text editor available in the IDE. The other is to use a WYSIWYG version, the Micro Focus BMS Painter, which is available as a separate utility installed with this product.

To open the BMS file in the IDE text view:

  1. In the Application Explorer view, right-click MBANK10.bms in the bms folder and click Open With > BMS Text Editor.

Although you can use this basic text editor to make small changes, it is quite difficult to edit BMS files in text view.

A much more suitable and less error-prone way to edit BMS files is to use the BMS Painter.

  1. Close the BMS text editor. In the Application Explorer view, right-click MBANK10.bms in the bms folder and click Open With > BMS Paint.

    This starts the external Micro Focus BMS Painter.

  2. In BMS Painter, you can click fields and move them by dragging.

    For example, double-click the data field immediately following the text “User Id” and move it to a different position on the map.

  3. To add a field, click in the desired place in the window and start typing.
  4. To change a field's properties, right-click it and select Properties.
  5. To change the properties of the map or mapset, right-click the item and select Properties.

    For example, do this for the MBANK10 mapset and the BANK10A map.

  6. Click File > Exit to close the utility and do not save the file.

Editing data files

You can edit data files using one of two available Micro Focus data editors - the Classic Data File Tools which was available with Net Express and a newer one, called Data File Tools.

  1. In the Application Explorer view, right-click the .dat file and click Open With > Classic Data File Tools.

    Close the utility now as we are going to use the new one for this demonstration.

To use the new editor:

  1. In the Application Explorer view, right-click the .dat file and click Open With > Data File Tools.

    This starts the Data File Editor and loads the .dat file in the Open Data File dialog box.

  2. Click Open Exclusive to load the file.
  3. Data File Editor loads the data file and shows two views:
    • The left-hand pane shows the raw form of the file. Because many of the field are COMP-3 fields, the data in these fields is presented in an ASCII view.
    • The right-hand pane shows the record layout for the file in its detailed field view and the COMP-3 fields are shown in a much better, editable form.

  4. Change the value of BAC-REC-BALANCE from 91.14 to 132.76 as follows:
    1. Click the line for BAC-REC-BALANCE in the right pane and then click Edit Record, Edit Record.

      This highlights the record.

    2. Double-click in the Value field for BAC-REC-BALANCE.
    3. Type 132.76 then click Save Record, Save Record.
    4. Confirm you want to save the changes to this record.
    5. Using the same method, restore the previous value of BAC-REC-BALANCE.
  5. Close the Data File Tools utility.
Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Previous topic: Creating a Project and Adding the Source Files
Next topic: Compiling the Source Code


Compiling the Source Code

By default, the Eclipse IDE is set to build projects automatically. Whenever you add new COBOL or BMS files to the Bankdemo project, the IDE starts an automatic build (compilation).
Important: You need Enterprise Developer or Enterprise Developer for z Systems to create executables. Building projects is not supported in Enterprise Developer Connect.

To turn the automatic build off:

  • Click Project and disable Build Automatically.

To start a build manually:

  • Click Project > Build Project.

The build in this case checks for any files that have changed and does two things:

  • Compiles any files affected by the changes
  • Relinks the built files if necessary

Turn the automatic build on:

  • Click Project and enable Build Automatically.

COBOL Compiler control

The Micro Focus COBOL Compiler can compile many different COBOL dialect variations. It can also compile COBOL code that contains EXEC CICS or EXEC SQL statements. The Compiler is controlled through a series of "directives" which are passed to the Compiler at build time. You can set directives at either a project or component level.

Often the directives can be set only at the project level, which means that all component files in the project use them. Sometimes, you have a component which you need to compile with different directives. In this case, you can set the directives at the component level which overrides the project settings.

For example, most of the programs in your project could be using Enterprise COBOL for z/OS and only a few could use VS COBOL II. In this case, you would set directives for Enterprise COBOL for z/OS at the project level, and VS COBOL II at the respective COBOL programs.

The Bankdemo application already has the required Compiler directives set on the files. At build time, the IDE invokes the COBOL compiler to compile the sources and create a number of files. These "built" files can vary, but each COBOL program in the Bankdemo application compiles to produce the following three types of file:

File type | Function
.dll - dynamic link library | Effectively the executable module the Compiler creates for each program.
.idy - debugger information | The file created by the Compiler which allows debugging of the module.
.obj - object file | A temporary file the Compiler creates while producing the .dll. You can delete these files.

BMS Compiler control

In the same way as for COBOL, the BMS compilation is controlled both at project and at component level.

The BMS Compiler produces the following two types of file:

File type | Function
.mod - BMS executable | A file created by the BMS compiler which is the executable module relating to the BMS source.
.cpy - copybook | A copybook that contains the BMS mapping for use in a COBOL program.

Producing a Compiler listing

You can configure the IDE to create a fully expanded Compiler listing file during the build. The following is also an example of setting a directive at component level:

  1. In the Application Explorer view, right-click ZBNKPRT1.cbl and click Properties.
  2. Click COBOL in the left-hand pane and check Enable file specific settings.
  3. Check Generate listing file and click Apply and Close.

During the build, the Compiler produces a source listing file, ZBNKPRT1.lst, in a Listing subfolder in the project directory (C:\MFETDUSER\Bankdemo\Projects\Eclipse\Bankdemo\Listing in this case). The listing file includes a fully expanded source file together with some Compiler system information at the start and with any Compiler errors highlighted with asterisks. You can view this listing from within the IDE: double-click the .lst file in the Listing folder.

Example of compiling a COBOL program with errors

You can introduce some Compiler errors into one of the programs to see how the Compiler handles them:

  1. In the Application Explorer view, double-click ZBNKPRT1.cbl.
  2. Page down the program a few pages to the start of the Procedure Division around line 021600.
  3. Introduce a few syntax errors as follows:
    • On line 21800 change RUN-TIME to RUN-TME
    • On line 22100 change SPACES to SPOCES
    • On line 22900 place a period after the END-IF
    • Move one of the copybooks from c:\MFETDUSER\Bankdemo\Sources\Copybook to c:\MFETDUSER\Bankdemo\Sources\jcl using the MOVE... action from the context menu of the copybook entry.

    The errors are underlined with red wavy lines and a colored bar is added to the left of each line that includes an error.

  4. Hover over an underlined item to view a pop-up with an explanation of what the error is.
  5. Save the program.

    This triggers a build of the project which will also update the listing file. The messages in the Console view indicate that there are build errors.

  6. Click the Problems tab to view the list of errors.

    If it is hidden you can open it by clicking Window > Show View > Problems.

    Tip: Click the column headings to sort the list into an appropriate order; for example, click the Program heading to order the errors by program.
  7. Double-click an error in the list to position the cursor on the line of code that contains the error.
  8. To fix the copybook error:
    1. Locate the error related to the unknown copybook in the Problems view and double-click that line in the list of errors.

      This positions the cursor on the line that contains the COPY statement for this copybook.

    2. Right-click the COPY statement, then select Quick Fix.

      The Quick Fix window appears.

    3. Double-click Enable copybook path....

      This displays a message that the directory containing the copybook is not on the copybook path for the project.

    4. Click Yes to add the c:\MFETDUSER\Bankdemo\Sources\jcl folder where you moved the copybook to the copybook path of the project.

      This triggers a rebuild of the project which now compiles cleanly as it now locates the copybook.

  9. Check the errors in the listing file, ZBNKPRT.lst as follows:
    1. Double-click the .lst file in the Listing folder.

    The lines that include syntax errors are marked with asterisks (**).

  10. In the IDE, fix the errors and save the file.

    There should be no errors in the build now.

    Note: Move the copybook back to its original directory in case other projects are expecting to locate it there.
Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Previous topic: Editing Source Files
Next topic: Unit Testing the Batch Application


Unit Testing the Batch Application

The first thing you need to do is check that the Bankdemo application is executing correctly.

To execute the JCL, you need to run the application in an instance of the Micro Focus Enterprise Server (sometimes abbreviated to Enterprise Server). This demonstration includes a pre-configured enterprise server instance called Bankdemo which you need to import in Enterprise Server and start before you execute the Bankdemo application.

Important: You need Enterprise Developer or Enterprise Developer for z Systems to execute the application as running applications is not supported in Enterprise Developer Connect.

Importing the Bankdemo server

To import the definition of the Bankdemo logical server (LSER):

  1. Click the Server Explorer tab in the upper left pane of the IDE.

    If the tab is not visible, click Window > Show View > Other. Select Micro Focus > Server Explorer and then click OK.

  2. In Server Explorer, right-click Local [localhost:86] and click Open Administration Page.
    Note: On versions of Windows Vista or later, if you experience issues connecting to localhost, connect to 127.0.0.1 instead.
  3. Click Import in the left upper corner of Enterprise Server Administration.
  4. On the Import server information page and under Recent directories click the directory for the BANKDEMO server.

    This adds the path to the Selected source directory containing server data to restore field.

  5. Click Next three times, and then click OK to import the BANKDEMO server.
  6. The system returns to the main Enterprise Server Administration page.

    You can see the Bankdemo server appears in the list of servers. You need to start it before you can execute the online Bankdemo application.

Associate the Bankdemo Enterprise Server with your project

Ensure your application is associated with the BankDemo server:

  1. In Server Explorer, right-click Local, and click Refresh to show the BankDemo server.
  2. Right-click the BANKDEMO server, point to Associate with project, then select BankDemo.

Configure the IDE settings for Enterprise Server

Configure the IDE to start the associated BankDemo server automatically as follows:

  1. Click Window > Preferences.
  2. Expand Micro Focus, and click Enterprise Server.
  3. Set the following options on this page to Always in order to enable the IDE to start or stop the associated server, and to enable dynamic debugging, for when it is not enabled in the server:
    • Automatically start the associated server - this ensures the IDE will start the server if it is not running when you execute the application.
    • Automatically stop servers started by Eclipse when closing Eclipse - this enables the IDE to stop servers when you close Eclipse.
    • Automatically enable dynamic debugging - this ensures the IDE will check whether the server has dynamic debugging enabled and, if it is not, will enable it when you start debugging.
  4. Click Apply and Close.

Starting the Bankdemo Enterprise Server and Showing the Server Log

These are the steps to start the server manually, and are included for completeness. You do not have to start the server manually, as you have configured the IDE to start the server automatically.

  1. In Server Explorer, right-click BANKDEMO, then click Start.
    Note: You might receive an Enterprise Server Sign On dialog prompting you to provide connection details for the BANKDEMO server. This is a standard security dialog. Click OK without specifying any sign on details. Also, you may skip enabling password recovery.

    You may receive a Windows Security Alert blocking the MF Communications process. Click Allow access.

    You can check the Console view to ensure that the BANKDEMO server has started successfully.

  2. Right-click the BANKDEMO server in Server Explorer, and click Show Console Log.

    Check the Console view as it now shows the messages from the server log:

  3. Right-click the BANKDEMO server again, and then click Refresh to see that the server has started.

    After several seconds, the server status on the Enterprise Server Administration page also changes to Started. You are now ready to execute the JCL.

Executing JCL

The JCL provided in your demo causes the COBOL application to read a file, sort the data and produce a report. The .jcl file, ZBNKSTMT.jcl, is in the Sources > jcl folder of the project. To submit this job:

  1. In the Application Explorer view, expand the jcl folder.
  2. Right-click the .jcl file and select Submit JCL to associated Server.
    Note: If you have not started the Bankdemo server yet, since you configured the IDE to start the server automatically, you receive a notification that the server will be started. Click Yes to confirm this.

    Check the Console view in the Eclipse IDE to see that this job has been submitted.

  3. Click one of the links to show the spool details for the job.

You now need to check the results of submitting the job.

Viewing the Catalog and the Spool

You can open the catalog and the spool directly from within the IDE.

To view the catalog:

  1. In Server Explorer, right-click the BANKDEMO server and click Show Catalog.

    This opens the catalog.

  2. Click List to view all file entries in the catalog.

  3. Click a file name (for example, EBC.BNKACC) to preview the contents of the file.

To view the spool:

  1. In Server Explorer, right-click the BANKDEMO server, and click Show Spool.

    This shows the spool with the Complete button selected to see a list of all jobs in the completed queue. Your job is the last in the list.

  2. Check the check box next to your job, and click Display.

    This opens a page with a variety of information for the job progress, showing return condition code (COND) of 0000:

    In the details, there are:

    • Two SYSOUT results (one for the Extract and one for the SORT). Click these to see the details:

      Again, if you cannot see your SYSOUT files, click Printed on the Spool page.

    • To return to the previous page, press the backspace key.
    • The PRINTOUT which is the final printed results created by your job. Click PRINTOUT to see the results:

You can now start to look at how to run the online application.

Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Previous topic: Compiling the Source Code
Next topic: Unit Testing the Online Application


Unit Testing the Online Application

In the previous step, Unit Testing the Batch Application, you used the Bankdemo enterprise server. You are going to use it again for online testing.

As with JCL, execution of the jobs requires a previously configured Micro Focus enterprise server.

Important: You need Enterprise Developer or Enterprise Developer for z Systems to execute the application as running applications is not supported in Enterprise Developer Connect.

Starting the Bankdemo enterprise server

If the enterprise server is not yet started, you need to start it as follows:

  1. Click the Server Explorer tab.

    If the tab is not visible, click Window > Show View > Other. Select Micro Focus > Server Explorer and then click OK.

  2. In the Server Explorer window, right-click the Bankdemo server and then click Start.

    Wait until the server has started. In the list of servers in Server Explorer, BANKDEMO still has a red square next to it. This is a refresh delay.

  3. In Server Explorer window, right-click and click Refresh to confirm the server has started.

Executing the CICS application

The CICS application requires that you use a 3270 terminal emulator. The installation of Enterprise Developer includes the Micro Focus Rumba emulator. Rumba is available as a standalone application, Rumba Desktop, and is also available as a TN3270 Mainframe Display embedded within the IDE. As part of this tutorial, you are going to use the embedded display to run the application.

Configuring the TN3270 settings in the IDE

To check the IDE preferences and ensure that the embedded Rumba display is selected:

  1. In the IDE, click Window > Preferences.
  2. Expand Micro Focus > Enterprise Server, and click TN3270.
  3. Ensure that Enable display, Rumba (Embedded) and Connect automatically are all selected.
  4. Click OK.

Starting the Rumba Mainframe Display view

  1. Right-click the BANKDEMO server in Server Explorer, and click Show TN3270 Display.

    This opens the Rumba Mainframe Display view and automatically establishes a 3270 terminal connection to the BANKDEMO server. You can see the starting page of the ES/MTO region BANKDEMO.

  2. You can drag the Rumba Mainframe Display view to reposition it.

Executing the Enterprise Server Demonstration

  1. Press Ctrl+Shift+Z to clear this window.
  2. Type in the transaction id BANK and press Enter to navigate to an application logon window.
  3. Type your logon details and press Enter.

    A suitable User Id is b0001. You can type anything as a Password - the field must not be empty though.

    Bankdemo login screen

  4. Type / against Display your account balances and press Enter to see the details for this customer.

    Bankdemo application options

  5. You can explore this application further if you wish or press F3 to terminate it.

If the Rumba Mainframe Display view disconnects from the server, you can connect again manually as follows:

  1. Click the New Rumba Mainframe Display button, New Rumba Mainframe Display, in the toolbar of the Rumba Mainframe Display view.
  2. Specify the host name and the TN3270 port number for the Bankdemo server as follows:

    Bakdemo tutorial - new TN3270 connection

  3. Click Connect.

    This connects the display to the Bankdemo server and loads the start screen of the application.

  4. Follow the steps described earlier in this topic to execute the application in the Rumba Mainframe Display view.

Stopping the enterprise server

You can stop the Bankdemo server from within Server Explorer. You can leave it running though, if you wish to continue this tutorial.

Note: In production, enterprise servers are long-running processes that are usually run for many months without stopping and starting.
Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Previous topic: Unit Testing the Batch Application
Next topic: Debugging the Batch Application


Debugging the Batch Application

You are going to debug the batch Bankdemo application.
Important: You need Enterprise Developer or Enterprise Developer for z Systems to debug applications as this feature is not supported in Enterprise Developer Connect.

Starting the server

If the enterprise server is not yet started, you need to start it as follows:

  1. Open the Server Explorer view.

    If the view is not visible, click Window > Show View > Other. Select Micro Focus > Server Explorer and then click OK.

  2. In Server Explorer, right-click the Bankdemo server and then click Start.

    Wait until the server has started. In the list of servers in Server Explorer, BANKDEMO still has a red square next to it. This is a refresh delay.

Viewing the debug configurations

The project has two pre-configured debug configurations; a CICS Debug and a JCL Debug one, that you will use to debug the batch and the online application.

  1. In the Application Explorer view, select the BANKDEMO project and then click Run > Debug Configurations.
  2. In the left-hand pane of the Debug Configurations dialog box expand COBOL Enterprise Server.
  3. Click CICS Debug.
  4. Click the different tabs in the right-hand pane to see what debug settings are enabled for this configuration. Note that this configuration will be used with the BANKDEMO server.
  5. Click JCL Debug under COBOL Enterprise Server.
  6. Click the different tabs in the right-hand pane to see what debug settings are enabled for this configuration.
  7. Click Close to close the Debug Configurations dialog box without saving any changes.

Starting the debugger

You can now start the debugger. It starts in the background until a program which is debuggable is triggered. The demonstration application includes around 60 programs and just eight of them, the ones which are included in the project, are debuggable. To start the debugger:

  1. In the Application Explorer view, select the BANKDEMO project and then select Run > Debug Configurations from the menu bar.
  2. In the left-hand pane of the Debug Configurations dialog expand COBOL Enterprise Server.
  3. Click JCL Debug and then click Debug.
  4. You might receive a message about opening the Debug perspective when it launches. If you do, click Yes.

    This opens a new Debug pane, saying it is waiting for attachment. In addition, in the top right of the main screen, the view has changed from Team Developer to Debug:

    Click the respective icon to switch between the two perspectives.

  5. Click the Team Developer icon for now.
  6. In Server Explorer, right-click the BANKDEMO enterprise server and click Refresh.

    The application is now waiting for an event that will trigger debugging.

Simple debugging

You are going to look at some simple features inside the debugger. Start by submitting the JCL job:

  1. In the Application Explorer view, expand the Sources folder.
  2. Right-click ZBNKSTMT.jcl and click Submit JCL to associated Server.
  3. Depending on what you have done before, you may receive a message to Confirm Perspective Switch. If you receive it, check Remember my decision and click Yes. If Eclipse does not switch to the Debug perspective automatically, click the Debug button, [image], in the right upper corner of the main Eclipse window to switch the perspective.

    This starts the debugger and opens ZBNKEXT1.cbl for debugging, with the execution point set on the first line of Procedure Division.

Stepping through the code

The highlighted line of code is the one the IDE will execute next.

  1. Press F5 to execute the line.

    The PERFORM statement executes and takes you to the line starting with IF TIMER. You can also see that a Variables view is now open in the IDE showing the current value of a data item on the line of code which is about to be executed.

  2. Press F5 slowly a few more times until you reach line 18000. Watch the code as you step through it and notice how the values of the variables change inside the Variables view.

Looking at data values

  1. Scroll to line 24700 of ZBNKEXT1.cbl.
  2. Hover the WS-RECORD-COUNTER2 data item.

    This provides you with details of the location, the size, the format, the number of times the field is used in the program, and the current value of the data item.

  3. To change the value of WS-RECORD-COUNTER2, right-click the data item and click Inspect COBOL.

    This opens a pop-up window showing the value of the data item. Currently, it is 00000.

  4. Click Add to Expressions View in the pop-up.

    This opens the Expressions tabbed view and adds the data item to it.

  5. On the row for WS-RECORD-COUNTER2, click the arrow next to the data item to expand it.
  6. In the repeated version of the field name, change the value from 00000 to 00006.

    The new value is used from this point.

Running CSI queries

You can use the COBOL Source Information (CSI) functionality and its Quick Browse dialog to obtain information about your program when you are debugging it. This example shows details for data items starting WS-, such as the name, definition, and amount of times each item occurs in the program.

  1. Click the Quick Browse button ( Quick Browse button) on the toolbar to start the Quick Browse dialog box.
  2. Enter a simple query such as WS-*.

  3. Click OK to run the query.

    The results are shown in the Search view.

    To see more examples of CSI queries, start the Quick Browse dialog box again and press F1 to open the product help.

Setting a simple breakpoint

Check the Breakpoints view at the top right of the screen. Currently, there are no breakpoints set in the program. To set a simple breakpoint:

  1. Scroll down the code to line 019100.
  2. Double-click in the grey area to the left of this line or right-click in the same place and click Toggle Breakpoint.

  3. Do the same for line 019700.
    Note: You can enable and disable the breakpoints from the Breakpoints view.

  4. Use F5 to step through the code and F8 to execute it. Press F8 now.

    The execution of the code stops at the first breakpoint.

  5. Press F8 to resume the execution.

    You can see that ZBNKEXT1.cbl finishes and the debugger starts to debug the second program defined in the JCL.

    This program executes to completion and the job completes.

Stop debugging

Although the job has completed, the debugger is still waiting for the next event. To stop debugging:

  1. Click Run > Terminate or click the terminate button, [image], in the debugger toolbar.

  2. Finally, switch back to the Team Developer Perspective.
Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Previous topic: Unit Testing the Online Application
Next topic: Debugging the Online Application


Debugging the Online Application

Important: You need Enterprise Developer or Enterprise Developer for z Systems to debug applications as this feature is not supported in Enterprise Developer Connect.

Starting the server

If the enterprise server is not yet started, you should start it as follows:

  1. Click the Server Explorer tab in the bottom right pane of the IDE.

    If the tab is not visible, click Window > Show View > Other.... Select Micro Focus COBOL > Server Explorer and then click OK.

  2. In Server Explorer, right-click the Bankdemo server and then click Start.

    Wait until the server has started. If in the list of servers in Server Explorer BANKDEMO still has a red square next to it, right-click it and click Refresh.

Starting the debugger

You can now start the debugger. It starts in the background until a program which is debuggable is triggered. The demonstration application includes around 60 programs and just eight of them, the ones which are included in the project, are debuggable. To start the debugger:

  1. In the Application Explorer view, select the BANKDEMO project and then select Run > Debug Configurations... from the menu bar.
  2. In the left-hand pane of the Debug Configurations dialog box, expand COBOL Enterprise Server.
  3. Click CICS Debug and then click Debug.
  4. You might receive a message about opening the Debug perspective. Click Yes.

    This opens a new Debug pane, showing the debugger that is waiting for an attachment:

    Bakdemo tutorial - wait for attachment

    In addition, in the top right corner of the main screen, the perspective has changed from Team Developer to Debug: Bakdemo tutorial - COBOL and Debug perspectives. You can click on these tabs to switch between the Debug and Team Developer perspectives.

    Your Eclipse application is now waiting for an event to happen that will trigger the debugging.

  5. In the toolbar, click the downward arrow next to the debug icon, [image].

    You can see that the pre-configured CICS and JCL debug configurations have now appeared in the menu.

  6. In the Debug view, right-click the Micro Focus Debugger thread, and click Show Rumba Terminal.

    This opens the Rumba Mainframe Display view within the IDE.

  7. Click the New Rumba Mainframe Display button, New Rumba Mainframe Display, in the toolbar of the Rumba Mainframe Display view.
  8. Specify the host name and the TN3270 port number for the Bankdemo server as follows:

    Bakdemo tutorial - new TN3270 connection

  9. Click Connect.

    This connects the display to the Bankdemo server and loads the start screen of the application.

  10. Press CTRL+SHIFT+Z to clear the screen of the emulator.
  11. Enter transaction id BANK and press Enter.

    The program SBANK00P starts to execute on line 001600.

    Bakdemo tutorial - step into the code

Simple debugging

You use the same features as previously to debug the application.

  1. Click Run > Step Into or press F5 a few times to go through executing the code.
  2. Watch how the values of the variables shown in the Variable view change.

    Bakdemo tutorial - variables view

Stopping debugging

  1. Click Run > Terminate or click the terminate button, Terminate, in the debugger toolbar to stop debugging.

    Bakdemo tutorial - terminate debugging

  2. Finally, click the Team Developer perspective button Bakdemo tutorial - COBOL and Debug perspectives, to switch back to editing your application.
Parent topic: Getting started with Micro Focus Enterprise Developer for Eclipse
Previous topic: Debugging the Batch Application


Using the Rumba Screen Designer

You use the Screen Designer to create or manage a screen customization project. You can do this in one or both of the following ways:

Using screens
Each screen in the specific host session is uniquely identified and is customized individually.
Using rules
The data of each screen of a specific host session is passed through a set of rules to produce modern controls on the screen.

The Rumba Screen Designer offers the following features:

  • Screen identification creating a unique screen identifier for each screen.
  • Modern WPF controls added to green screen applications to modernize input fields, buttons, choosers, and other window elements.
  • Use green screen application data to launch external applications such as VOIP or Google Maps.
  • Extend the reach of green screen applications with three Rumba+ clients: Windows, iPad, or Web.
  • Code-free modernization. Add WPF controls to green screen applications with no programming requirements.
  • Natural language modernization rules engine enabling contextual and conditional controls over multiple green screens, without specialized programming requirements.

For a comprehensive tutorial and reference information, download the Rumba Screen Designer User Guide from the Product Documentation section of the Micro Focus SupportLine Web site.

A set of training videos is also available on the Micro Focus YouTube page - click here.

Note: The Screen Designer is only available with a full installation of Rumba.
Parent topic: Mainframe Tutorials


Tutorial: Remote mainframe development

Enterprise Developer for z Systems allows you to use the Eclipse IDE to edit, compile and test mainframe applications directly on the host, as well as providing a full-function mainframe development environment under Windows. In this tutorial, we will demonstrate some of the remote mainframe development capabilities.

Before attempting this tutorial set, you should complete the Getting Started tutorial set. These tutorials cover the setting up of elements that are used in this tutorial set.

  • Installing the BankDemo Application
  • Running the BankDemo Application
Parent topic: Mainframe Tutorials


Installing the BankDemo Application

Before commencing this tutorial set, ensure the following software is installed and configured correctly:
  • z/Server on the mainframe
  • Mainframe Access on the mainframe
  • Enterprise Developer for z Systems on the client

When these components are working correctly, install the sample application in your mainframe environment:

  1. Installing the Application on the Mainframe
    Install the BankDemo COBOL application on the mainframe.
  2. Customizing the Application on the Mainframe
    Customize the tutorial datasets to work in your z/OS mainframe environment.
  3. Validating the Installation
    After installation and customization, confirm the connection to the z/OS environment, via the z/Server and Mainframe Access (MFA) software, is correctly configured. Also, check file mappings for certain types of file, to ensure they are executed correctly on the mainframe.
Parent topic: Tutorial: Remote mainframe development


Installing the Application on the Mainframe

To run through the mainframe tutorial, you first need to install some demo files on your mainframe. These files are delivered in an XMIT file, containing the source files required to run the tutorial.

The z/Server installation contains a JCL file RECBNKDM which can be used to submit the necessary TSO RECEIVE commands. You will find this file in the data set hlq.ZSERVER.JCL.

Note: Your z/Server installation dataset first qualifiers might be different.

Customize this JCL file before submitting:

  • add a valid job card.
  • change the string "userid" to your TSO userid.
  • change the string hlq.ZSERVER.SAMPLIB to your installation z/Server installation SAMPLIB dataset name.

Submit this JCL, and verify in the job output that all RECEIVE commands were successfully executed.

Note: To use a PL/I sample, in addition, customize and submit the jcl RECSTFDM.
Parent topic: Installing the BankDemo Application
Next topic: Customizing the Application on the Mainframe


Customizing the Application on the Mainframe

An administrator should check the following one-time customizations to ensure the BankDemo tutorial runs in your z/OS environment and is available to all users.
  1. This sample application uses the REXX procedures TAUTOXCC for compiling COBOL batch and CICS programs, and the REXX procedure TAUTOXCA for compiling Assembler programs. To point to the right compiler load libraries and the CICS pre-processor, both REXX procedures have to be customized, which should have been already done after the z/Server installation. For details see ISPF Exits in the Workflow Manager Modeling Guide. If this is not customized, the remote syntax check action used in this demo will not work properly. If you are using the PL/I sample as well, the REXX procedure TAUTOXCP is used to compile PL/I sources.
  2. This tutorial uses the AWM "MVS Projects Sample Application" which is part of the z/Server installation. The corresponding AWM model MVSCONF is by default already part of the AWM master configuration file. For details see Master Configuration in the Workflow Manager Modeling Guide and Enable Model Configuration in the z/Server Installation Guide. The entries below are required in the master configuration file, with the dataset names adapted to your installation names. The syslib entries entered here are default values for this application. Don't change the string "&userid." which will be replaced with the TSO userid at run time. The datasets &userid..BANKVSAM.MACLIB and &userid..BANKVSAM.COPYLIB have been installed when executing the RECEIVE job for this tutorial. The PL/I syslib entry is only relevant for this tutorial, if you have installed the PL/I sample as well.
    *
* YOUR zOS System
*
* Enter a unique logical name for this mainframe system
*
System: My System Name
*
*
* MVS Projects Sample Application
*
User:
* application name
Appl: MVS Projects Sample Application
* location of the application configuration file
Conf: mvs:'++HLQ++.ZSERVER.XML(MVSCONF)'
* property settings
Property: MVS_PROP_STATIC_SYSLIB_ASM=SYS1.MACLIB;SYS1.MODGEN;&userid..BANKVSAM.MACLIB
Property: MVS_PROP_STATIC_SYSLIB_COBOL=&userid..BANKVSAM.COPYLIB
Property: MVS_PROP_STATIC_SYSLIB_PLI=&userid..STAFF.INCLUDE
Info:
EndAppl:
EndUser:
Parent topic: Installing the BankDemo Application
Previous topic: Installing the Application on the Mainframe
Next topic: Validating the Installation
Related information
ISPF Exits
Master Configuration
Enable Model Configuration


Validating the Installation

After installation and customization, confirm the connection to the z/OS environment, via the z/Server and Mainframe Access (MFA) software, is correctly configured. Also, check file mappings for certain types of file, to ensure they are executed correctly on the mainframe.
  1. Click Start > All Programs > Micro Focus Enterprise Developer > Enterprise Developer for Eclipse.
  2. Open the workspace that was created during the Getting Started... tutorial.
  3. If the Team Developer perspective is not already displayed, click Window > Open Perspective > Other > Team Developer.
  4. Click the Remote Systems tab.

  5. Create a remote system (mainframe) connection:
    1. On the Remote Systems tab, click [image], or right-click the Remote Systems pane. If a connection to your mainframe has not been pre-configured and is therefore not listed, choose New > Connection and create the connection manually using the following steps.
    2. Select Micro Focus z/Server, then click Next.
    3. Enter the details of the mainframe that has z/Server and MFA server installed.

    4. Click Next, enter the MFA port number for the installation on the mainframe, and edit the host codepages, as required.

      Note: Your systems administrator will have configured the port during the mainframe installation of the software.
    5. Click Finish.
  6. In the bottom pane, click the File Mappings tab.
    Note: If the File Mappings view is not displayed, click Window > Show View > Other > Remote Systems > File Mappings.
  7. If the following file mappings have not been pre-configured, right-click and choose Add Mapping, then create the following file mappings:
    • Generic Name: *.JCL, Extension: jcl
    • Generic Name: *.COBOL, Extension: cbl
    • Generic Name: *.COPYLIB, Extension: cpy
    • Generic Name: *.ASM, Extension: asm
    • Generic Name: *.MACLIB, Extension: mac
    • Generic Name: *.BMS, Extension: bms
    • Generic Name: *.PLI, Extension: pli
    • Generic Name: *.INCLUDE, Extension: inc
    • Generic Name: *, Extension: txt

    The generic file mapping name "*" must be the last one in the file mappings list. The .pli and .inc extensions are not necessary, if you haven't installed the PL/I sample.

  8. Right-click on the connection in the Remote Systems view and click Connect. You are prompted to log on to the mainframe.
    Tip: The first time you connect, check the box to remember your userid for future logons.
  9. Log on with your normal mainframe user ID and password. The MVS, JES and USS Explorer entries are displayed in green to indicate you have logged on successfully.

  10. If the system has not been added to the Application Explorer view, right-click the Application Explorer view and choose Add System(s).
  11. In the Add System(s) dialog box, select the connection that you just defined, then click OK. The Application Explorer view displays the available applications, one of which is the MVS Projects Sample Application.
  12. Right-click MVS Projects Sample Application and select Load Application.
  13. Expand the application entry, right-click MVS Projects and select Create Data Set Filter.
  14. In the Filter dialog window, enter the filter description Bankdemo Sample Data Sets and the filter criterion userid.BANKVSAM.*, then click OK and expand this defined filter in the tree view. The tutorial's data sets are displayed.

  15. If you have installed and want to use the PL/I Staff Sample application, create an additional filter with the filter criterion userid.STAFF.*.
The installation and verification of the BankDemo tutorial is complete. You are ready to run the application.
Parent topic: Installing the BankDemo Application
Previous topic: Customizing the Application on the Mainframe


Running the BankDemo Application

To run the BankDemo application in the Eclipse IDE, you need to connect to the mainframe that you validated in the previous section.

  1. Right-click your mainframe connection in the Remote Systems pane and choose Connect.

    You are prompted to log on to the mainframe.

  2. Log on with your normal mainframe user ID and password.

    The MVS, JES and USS Explorer entries are displayed in green to indicate you have logged on successfully.

When you have successfully connected to the mainframe, there are two panes of the IDE that enable you to interface with your mainframe:
  • The Remote Systems view, which allows you to filter a view of MVS datasets, USS files and JES output.
  • The Team Developer views, which provide a project-orientated environment for developing mainframe applications on and off the host.

Use these panes when performing the following tasks:

  1. Creating a Filter to View Jobs
    Create a filter that displays all jobs for a particular user ID.
  2. Creating a Filter to View Datasets
    Create a filter that displays all the datasets for a particular user ID.
  3. Creating a Filter to View USS Files
  4. Submitting a Job from the MVS Explorer
    Submit JCL jobs from the MVS Explorer for execution directly on the mainframe.
  5. Opening a Mainframe Application
    Enterprise Developer for z Systems provides a project-based view that allows developers to develop both on and off the mainframe.
  6. Displaying and Editing COBOL Code from the Mainframe
    Within the Team Developer perspective you can now use the full editing capabilities within the Enterprise Developer for z Systems Eclipse IDE to edit mainframe source files.
  7. Checking the Syntax Remotely (COBOL)
    As well as editing files on the mainframe, you can use Enterprise Developer for z Systems to compile applications directly on the mainframe.
  8. Checking the syntax remotely (Assembler)
    As well as editing files on the mainframe, you can use Enterprise Developer for z Systems to compile applications directly on the mainframe.
  9. Transferring a Mainframe Source to a Local Workspace
    In this final section, you will move source members from the mainframe to your local mainframe development environment running under Windows. This enables you to edit, compile, debug and unit test applications locally without relying on the mainframe.
Parent topic: Tutorial: Remote mainframe development


Creating a Filter to View Jobs

The Remote System view allows you to view mainframe datasets, USS files and JES spool items, based on customized filters. The JES Explorer applies filters for jobs in the Spool, based on a mainframe ID. All filters respect the RACF rules you have defined on your mainframe.
  1. In the Remote Systems pane, expand the entry for your mainframe.
  2. In the JES Explorer, create a new filter:
    1. Right-click JES Explorer, point to New and click Filter.

      The New Filter screen appears.

    2. Enter a filter string in the format shown below, substituting MYUSER with your job name prefix .

    3. Enter a name for the filter (for example My Jobs), and then click Finish.
  3. From the JES Explorer, expand the My Jobs filter. A list of jobs in the Spool that are under your jobcard name (mainframe ID) appear.

    Double-clicking on a job enables you to browse the complete job. Expanding a job and double-clicking on a job enables you to browse the job part.

  4. Double-click on a job part. The output appears in the editor.

  5. It is possible to display the jobs in a table view and to refresh the job status periodically. To do this, right-click on the job filter My Jobs and select Monitor. A table view opens, displays the jobs and allows you to define a poll configuration.

    You can create as many filters as you need to allow you to view different jobs on the mainframe.

Parent topic: Running the BankDemo Application
Next topic: Creating a Filter to View Datasets


Creating a Filter to View Datasets

Much like the JES Explorer, the MVS Explorer view allows you to create filters against dataset names. You can create any number of filters to allow you to view only the datasets you are interested in. All filters respect the RAC/F rules you have defined on your mainframe.

  1. In the Remote System pane, right-click MVS Explorer, point to New and click Filter.

    The New Filter screen appears.

  2. Enter a filter string in the format shown below, substituting MYUSER for your mainframe user ID, then click Next.

  3. Enter a name for the filter, then click Finish.

    The filter displays any datasets under your user ID, as well as the tutorial datasets.

    The filter shows a number of datasets. You can also view the dataset list in a table view within the IDE. The table view allows you to see more information for each dataset.

  4. Right-click My Datasets and choose Show in Table. A table view appears in the bottom pane.

  5. In MVS Explorer, expand the BANKVSAM.COBOL dataset.
  6. Right-click BBANK10P and choose Browse. The module, which is stored on the mainframe, is opened as read-only in the Eclipse IDE.

    If the COBOL editor is called from the MVS Explorer, it does not support the full COBOL editor capabilities because the editor is not called from a project context. For example, the editor does not know where to find the copybooks and therefore cannot support full syntax checking.

  7. The dataset context menu in the Remote Systems view offers a lot of standard dataset functions, like creating, deleting, renaming datasets, inserting members in partitioned datasets, text searching in dataset members and others.

  8. You can right-click a dataset and choose Show in Table to display a member list in a table view:

  9. Right-click a member to see which actions are supported on a member level:

Parent topic: Running the BankDemo Application
Previous topic: Creating a Filter to View Jobs
Next topic: Creating a Filter to View USS Files


Creating a Filter to View USS Files

The USS Explorer applies filters for the z/OS UNIX subsystem USS.

  1. In the Remote Systems pane, expand the entry for your mainframe.
  2. In the USS Explorer, create a new filter:
    1. Right-click USS Explorer, point to New and click Filter.

    2. To define a filter which displays all USS folders and files, enter a slash character in the folder field as shown below and click Next:

    3. Enter a name for the filter (for example All for all jobs), and then click Finish.

  3. From the USS Explorer, expand the All filter a few times and navigate through the USS directory.

  4. USS functions like edit, browse, copy, move, paste, delete, rename and others are supported and can be selected from the context menu (right-click a USS entry). For copy and paste, cross-system support is available.
Parent topic: Running the BankDemo Application
Previous topic: Creating a Filter to View Datasets
Next topic: Submitting a Job from the MVS Explorer


Submitting a Job from the MVS Explorer

Submit JCL jobs from the MVS Explorer for execution directly on the mainframe.
  1. In the Remote Systems pane, expand the entry for your mainframe.
  2. Under MVS Explorer, expand the userid.BANKVSAM.JCL dataset either in the tree or table view.
  3. Right-click the JCL member to show the Submit option that will execute the job.

    We are not going to submit this member for execution, but try this functionality on your own JCL file and then use the JES Explorer to review the results.

Parent topic: Running the BankDemo Application
Previous topic: Creating a Filter to View USS Files
Next topic: Opening a Mainframe Application


Opening a Mainframe Application

Enterprise Developer for z Systems provides a project-based view that allows developers to develop both on and off the mainframe.
The development workflow can be easily customized to meet an organization's specific development processes. Your administrator is normally responsible for defining and maintaining this workflow within the Workflow Manager tool.

In this part of the tutorial, we will be using the Application Explorer view with the mainframe application that we installed in the first part of this tutorial.

The first thing we need to do is load the model into the Application Explorer view.

  1. From the Application Explorer view, expand your mainframe system entry and load the MVS Projects Sample Application, if not already loaded.
  2. Expand the application entry, then expand the entry MVS Projects. This displays the filter entry Bankdemo Sample Datasets. This filter was created during the installation verification. See Installation Verification for details of how to create this entry, if it is missing.
  3. Expand the filter Bankdemo Sample Datasets to view its datasets.
  4. Expand userid.BANKVSAM.COBOL, then right-click the data set and select Show Members in Table.
    Note: userid is the data set qualifier specified when the tutorial files were set up on the mainframe, which is normally your TSO userid (see Installation).
    The project's COBOL members are listed in the tree and table view, and if you click a member, its properties are displayed in the properties view.

Parent topic: Running the BankDemo Application
Previous topic: Submitting a Job from the MVS Explorer
Next topic: Displaying and Editing COBOL Code from the Mainframe
Related information
Validating the Installation


Displaying and Editing COBOL Code from the Mainframe

Within the Team Developer perspective you can now use the full editing capabilities within the Enterprise Developer for z Systems Eclipse IDE to edit mainframe source files.
  1. In the Application Explorer view, right-click the ZBNKPRT1 member and choose Edit. The MVS ZBNKPRT1 member is opened in the editor.

    When the file is opened in the editor, the following occurs:
    • The file is locked for editing on the mainframe.
    • A background parse is performed (even though the member and its dependent files, such as copybooks, physically reside on the mainframe).

    The background parsing is exactly the same as the functionality demonstrated in the Editing Source Files tutorial (of the Getting Started... tutorial set), which means that a number of editor features are enabled to assist with programmer productivity, including:

    • Content Assist - editing features to help you write syntactically correct procedural code and to look up working storage data names.
    • Outline view - you can see the structure of the program that you are editing, which is useful for navigating large programs; for example, click an item in the Data Division section to jump to that item in the editor.

    • Breadcrumbs - breadcrumbs enable you to view copybooks in the context of the program in which they are referenced. When you view or edit a copybook, you need to see it in the context of the program that references it, because its appearance and usage can change depending on the program. Data items that are not used in the program are struck through, and horizontal lines indicating the start and end of code lines are shown depending on the source format of the program.

      When focus is on a copybook, the Eclipse window's title bar shows the location of the file and the program currently associated with it.

      A trail at the top of the editor indicates which program and copybooks are currently in context - click [image] (Toggle Context Breadcrumbs) on the Eclipse toolbar and use the drop-down list to view and open the dependent copybooks.

  2. Within this edit session, use the knowledge gained during the earlier tutorials to explore and edit this COBOL program.

    The tools available are the same whether you are editing source locally or on the host.

    Remember that you are editing a program that resides on the mainframe, and so your changes may affect other users.

Parent topic: Running the BankDemo Application
Previous topic: Opening a Mainframe Application
Next topic: Checking the Syntax Remotely (COBOL)


Checking the Syntax Remotely (COBOL)

As well as editing files on the mainframe, you can use Enterprise Developer for z Systems to compile applications directly on the mainframe.
Before you begin, ensure the ZBNKPRT1 program is still open, remove the ) on the WS-FIRST-REC data item on line 008100, and then save the code. This saves the changes on the mainframe.
Since a new change was made, another background parse is performed and errors noted in the margin. As you hover the mouse over the red markers, the syntax error for that line is displayed.

Even though the errors in the source are clearly displayed from the background parse, you should perform a syntax check of the COBOL program with the Enterprise COBOL dialect set, on the mainframe. You can use the Workflow Manager to model remote compilation for languages other than COBOL too.

  1. In Application Explorer view, right-click the ZBNKPRT1 member and choose Remote Syntax Check.

    A dialog box appears, prompting you for additional compiler directives. This allows you to specify additional directives for the mainframe compiler, and the CICS and DB2 preprocessors.

  2. Click OK.

    The code is compiled on the mainframe, using the mainframe compiler. If any syntax errors are detected, they are displayed in the Error Feedback view, shown below:

  3. To go directly to the error you created within the source file, double-click the syntax error with ID IGYDS1168. You are prompted to associate the error with the source member.

  4. Click Yes. The syntax error is shown in the editor, along with the error code. This allows you to locate and fix errors quickly.
  5. Correct the error, save, then repeat step 1. The code now compiles cleanly.
Parent topic: Running the BankDemo Application
Previous topic: Displaying and Editing COBOL Code from the Mainframe
Next topic: Checking the syntax remotely (Assembler)


Checking the syntax remotely (Assembler)

As well as editing files on the mainframe, you can use Enterprise Developer for z Systems to compile applications directly on the mainframe.
Before you begin, open the UTWOSCMP Assembler member of the .ASM PDS in the Editor. Change "LA" on Line 30 to be "LAX" and then save the code. This saves the changes on the mainframe.
  1. In Application Explorer view, right-click the UTWOSCMP member and click Remote Syntax Check.

    A dialog box appears, prompting you for additional compiler directives.

  2. Click OK.

    The code is compiled on the mainframe, using the mainframe Assembler. If any syntax errors are detected, they are displayed in the Error Feedback view, shown below:

  3. To go directly to the error you created within the source file, double-click the syntax error with ID ASMA029E. You are prompted to associate the error with the source member.

  4. Click Yes. The syntax error is shown in the editor, along with the error code. This allows you to locate and fix errors quickly.
  5. Correct the error, save, then repeat step 1. The code now compiles cleanly.
Parent topic: Running the BankDemo Application
Previous topic: Checking the Syntax Remotely (COBOL)
Next topic: Transferring a Mainframe Source to a Local Workspace


Transferring a Mainframe Source to a Local Workspace

In this final section, you will move source members from the mainframe to your local mainframe development environment running under Windows. This enables you to edit, compile, debug and unit test applications locally without relying on the mainframe.
Before you begin, ensure you have created and loaded the local BankDemo application, as detailed in the Importing the BankDemo Project and Adding the Source Files tutorial.
Note: The local BankDemo application is a separate AWM application and currently not integrated in the MVS Projects Sample application. It is straightforward AWM modeling work to merge both applications and to provide the full power of working on and off the mainframe in only one application, including the necessary actions for transferring the sources from MVS projects into local projects and vice versa. Without this integration, it is still possible to transfer the mainframe sources into the local BankDemo project using the drag and drop support. This can be used to copy sources from the MVS Explorer into a local project displayed in the Application Explorer view. This tutorial shows the drag and drop support only, because the applications are not merged.
  1. In the Application Explorer view, navigate to the COBOL folder within your loaded local BankDemo project.
  2. In the MVS Explorer, navigate to the COBOL source BBANK10P.
  3. Now drag and drop BBANK10P from the MVS Explorer onto the COBOL folder in the Application Explorer view.

In an offload development scenario, a developer would now edit and test the changes made using the same features and techniques that were described in the Getting Started tutorial. After testing, a developer would transfer the changes back into the mainframe project and build the application on the mainframe.

For a combined development scenario off and on the mainframe, an administrator responsible for the development process would probably provide only one Workflow Manager application which supports both development approaches.

Parent topic: Running the BankDemo Application
Previous topic: Checking the syntax remotely (Assembler)


Tutorials: HCO for SQL Server (HCOSS)

The HCO for SQL Server tutorials provide you with an opportunity to use the HCOSS toolset to perform a DB2 database migration, and to use the Mainframe Batch Database Tools (MBDT) to perform a DB2 database migration. They also provide three different scenarios in which you migrate a DB2 application to a SQL Server application.

Note: These tutorials assume that you are not using Windows UAC.

Prerequisite Third-party Software

To complete any of the HCOSS tutorials, you must have Microsoft SQL Server, including the SQL Server Management Studio, installed. See Additional Software Requirements on Windows for details.

Requirements

To complete any of the DB2 Database Migration or Application Migration tutorials, you must first complete the following tutorials in the order listed:

  1. Tutorial: Create a SQL Server Database
  2. Tutorial: Create a SQL Server Database Connection

Additional requirements that apply to specific tutorials appear in the Requirements section of each.

DB2 Database Migration Tutorials

We provide two DB2 migration tutorials to from which to choose. Both take you through the steps of migrating a DB2 database to a SQL Server database:
  • Tutorial: DB2 Database Migration
  • Tutorial: DB2 Database Batch Migration

Application Migration Tutorials

To complete any of the Application Migration tutorials, you must have an established SQL Server database named HCO_Test containing the required PROD and TEST schemas, and a connection to the HCO_Test database. You can accomplish this by completing Tutorial: DB2 Database Migration, or, as a short cut, completing the Tutorial: Setup for Application Migration Tutorials instead. The Application Migration tutorials include:
  • Tutorial: Setup for Application Migration Tutorials
  • Tutorial: Application Migration - Switching Package Sets
  • Tutorial: Application Migration - Converting Labeled Duration Calculations
  • Tutorial: Application Migration - Adding Function Emulation
  • Database Migration
    Tutorials that walk you through the process of migrating a DB2 database to SQL Server.
  • Application Migration
    Tutorials that walk you through the process of migrating COBOL applications from DB2 to SQL Server.
Parent topic: Mainframe Tutorials
Related concepts
Additional Software Requirements on Windows


Database Migration

Each of these tutorials walk you through the process of migrating a DB2 database to SQL Server:

  • Prerequisites
    Describes the requirements that must be in place before running either of the Database Migration tutorials.
  • Tutorial: DB2 Database Migration
    This tutorial takes you through each step in the process of migrating a mainframe-based DB2 database to a Microsoft SQL Server database using HCO for SQL Server database migration tools.
  • Tutorial: DB2 Database Batch Migration
    This tutorial takes you through each step in the process of migrating a mainframe-based DB2 table on the mainframe to a local SQL Server using Mainframe Batch Database Tools (MBDT). This process can be done for all the tables in your DB2 database.
Parent topic: Tutorials: HCO for SQL Server (HCOSS)


Prerequisites

Before progressing to either of the DB2 Database... tutorials, complete the following tutorials in the order listed:

  • Tutorial: Create a SQL Server Database
    This tutorial takes you through the process of using Microsoft SQL Server Management Studio to create a SQL Server database.
  • Tutorial: Create a SQL Server Database Connection
    This tutorial takes you through the process of creating a connection to your SQL Server database using the HCOSS Manage Connections tool.
Parent topic: Database Migration


Tutorial: Create a SQL Server Database

  1. Open SQL Server Management Studio.
  2. Connect to the server where you want to create your database.
    Note: The user ID and password you provide must log you on to SQL Server with dbadmin or sysadmin permissions that enable you to create a SQL Server database.
  3. Create a SQL Server database named HCO_Test.
  4. Close SQL Server Management Studio.

This completes the tutorial. Next, please complete Tutorial: Create a SQL Server Database Connection.

Parent topic: Prerequisites
Parent topic: Prerequisites
Related concepts
Tutorial: Create a SQL Server Database Connection
Tutorial: DB2 Database Migration
Tutorial: Application Migration - Switching Package Sets
Tutorial: Application Migration - Converting Labeled Duration Calculations
Tutorial: Application Migration - Adding Function Emulation


Tutorial: Create a SQL Server Database Connection

This tutorial takes you through the process of creating a connection to your SQL Server database using the HCOSS Manage Connections tool.

Requirements

Before attempting this tutorial, you must complete Tutorial: Create a SQL Server Database.

Create the Connection

  1. Start Enterprise Developer as an administrator. If you need instructions, see To start Enterprise Developer as an administrator.
  2. From Eclipse, click Run > Tools > Data Tools > HCO for SQL Server.
  3. From the HCO for SQL Server interface, click Manage Connections.
  4. Select the User Connection Type.
  5. From the Connection List tab, click New SQL Server Connection. This takes you to the SQL Server Connection tab.
  6. In the Data Source Name field, type HCODemo.
  7. Click Integrated Windows Authentication to select it. This means that SQL Server uses your Windows logon credentials to access the database.
  8. In the SQL Server Instance field, type the name of your SQL Server instance. If you have a default instance, this could be . or (local). If you have a named instance, use the combined server name and instance name. For example: mysqlserver\myinstance.
  9. Click Confirm Server to confirm that HCOSS can locate your specified SQL Server Instance.
  10. Check Use a database other than the default database:.
  11. From the Database drop-down menu, select the HCO_Test destination database that you created in SQL Server Management Studio.
  12. Click Test. If the test fails, review your field entries, make corrections accordingly, and try again. When you have a successful connection, click OK.
  13. Click Save to save the connection. This takes you back to the Connection List tab where you should now see your SQL Server connection listed.
This completes the tutorial. Next, you can move on to any of these tutorials:
  • Tutorial: DB2 Database Migration
  • Tutorial: DB2 Database Batch Migration
  • Tutorial: Setup for Application Migration Tutorials
Parent topic: Prerequisites
Parent topic: Prerequisites
Related concepts
Tutorial: Create a SQL Server Database
Tutorial: DB2 Database Migration
Tutorial: Application Migration - Switching Package Sets
Tutorial: Application Migration - Converting Labeled Duration Calculations
Tutorial: Application Migration - Adding Function Emulation
Related tasks
To start Enterprise Developer as an administrator


Tutorial: DB2 Database Migration

This tutorial takes you through each step in the process of migrating a mainframe-based DB2 database to a Microsoft SQL Server database using HCO for SQL Server database migration tools.

Requirements

Before attempting this tutorial, you must first complete the following tutorials to ensure you have an established SQL Server database named HCO_Test and a connection to that database:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create a SQL Server Database Connection
To complete this tutorial, you need access to and connection information for a mainframe-based DB2 database. This includes:
  • Computer address and port number
  • Initial catalog and Package collection name
  • User ID and password that grant you read access to the SYSIBM system database tables
  • Standard schema provided with DB2, named DSNversion-id, where version-id depends on the version of DB2 you are using.

Phase 1: Start Enterprise Developer and HCO for SQL Server

If Enterprise Developer is already running as an administrator and HCOSS for SQL Server was started from Eclipse, skip this phase.

  1. Start Enterprise Developer as an administrator. If you need instructions, see To start Enterprise Developer as an administrator.
  2. From Eclipse, click Run > Tools > Data Tools > HCO for SQL Server.

Phase 2: Create a DB2 Database Connection

You need to establish a connection to a DB2 database on your mainframe so that you can access its SYSIBM tables.
  1. Be sure you have installed the Microsoft OLEDB Provider for DB2.
  2. From the HCO for SQL Server interface, click Manage Connections. This takes you to the Connection List tab.
  3. Click New DB2 Connection. This takes you to the DB2 Connection tab.
  4. In the Data Source Name field, type mainframeDB2 to provide a name for the connection.
  5. Provide values for all remaining fields on this tab. Valid entries for all fields are required to ensure a valid connection. If you do not know the correct values required, contact your DB2 administrator.
  6. Click Test.

    A prompt appears showing the name of the schema that contains your mainframe system catalogs. By default, this is SYSIBM. If the schema name provided is incorrect, type the name of the correct schema.

  7. Click OK.
  8. If the test fails, review your field entries, make corrections accordingly, and try again. When you have a successful connection, click OK.
  9. Click Save to create the connection. This takes you back to the Connection List tab where you should now see your DB2 connection listed.

Phase 3: Extract a DB2 Schema

In this phase, you download the standard DSN schema from your DB2 database in the form of an XML file that contains its information, and view that file in a text editor. The standard schema name varies depending on your version of DB2:

DB2 Version | DSN Schema Name
9 | DSN8910
10 | DSN8010
11 | DSN8110
Extract the DSN schema
  1. From the HCO for SQL Server interface, click Extract Schema. This takes you to the Schema Extract tab.
  2. Click New.
  3. In the Schema Extract Name field, type schema-name where schema-name is the DSN schema name for your version of DB2; then click OK.
  4. From the DB2 Connection drop-down list, select the DB2 data source that you specified when creating your connection with the Manage Connections tool.

    Depending on your DB2 database connection specifications, you might be prompted for a user ID and password. If so, enter the user ID and password you supplied when creating the DB2 connection.

  5. Click Local. This sets the Extract Schema tool to save the generated schema extract file to the directory specified by the Local HCOSS Directory HCOSS option.
  6. On the Select schema(s) to extract list, check the box that corresponds to the schema that corresponds to your version of DB2.
  7. In the Table Row Count group, select Estimated using schema statistics. This option estimates the table row count based on the most recent statistics available, and returns results faster than the other option, Both Estimated and Actual (COUNT(*)), which additionally performs a COUNT_BIG(*) on the selected table or tables.
  8. Click Extract. This initiates the extract schema process, writing the schema-name.hcodbs XML file, and takes you to the Results tab. Here you can see the results of the extraction.
View the schema-name.hcodbs File
  1. From the HCO for SQL Server interface, click Options.
  2. Note the path specification for the Local HCOSS Directory. The default is %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss.
  3. Start a text editor and open the following file:

    localHCOSSDirectory\Schemas\schema-name.hcodbs

    Where localHCOSSDirectory is the path specification for the Local HCOSS Directory option.

  4. When you have finished looking at the file, close the text editor. Do not save any changes if prompted.

Phase 4: Create a Transfer List

In this phase, you create a list of objects from the DB2 schema you extracted. In a later phase, HCOSS uses this transfer list to identify the objects associated with this extraction and migration.

  1. From the HCO for SQL Server interface, click Define Lists.
  2. On the Transfer Lists tab, click New.
  3. In the Name field, type schema-name where schema-name is the DSN schema name for your version of DB2.
  4. From the Schema Extract drop-down list, select schema-name. This populates the Available Objects list.
  5. Click Add All to add all available schema objects to the Selected Objects list.
  6. Click Save.

Phase 5: Generate DDL and Verify

In this phase of the migration process, you generate DDL from the schema objects in your object transfer list. You use this DDL in the next phase to define the structure of your new SQL Server database, including tables, views, indexes, and foreign key relationships.

Generate DDL
  1. From the HCO for SQL Server interface, click Generate DDL. This takes you to the DDL Tasks tab.
  2. Click New to create a new DDL task.
  3. In the Name field, type schema-nametest.
  4. From the Transfer List drop-down list, select schema-name.
  5. From the Connection for Execute drop-down list, select HCODemo.
  6. To map the extracted schema to a SQL Server schema:
    1. Click Schema Mappings. This takes you to the Schema Mappings tab.
    2. In the SQL Server Schema Name field, type TEST.
  7. Click the DDL Tasks tab; then click Save.
  8. Click Execute to execute the task to generate the DDL.
Verify the SQL Server Database Structure
  1. Open the Server Explorer in Eclipse and add a connection for your SQL Server server.
  2. Verify that the appropriate objects were created in the SQL Server database by expanding the entry for your HCO_Test database and its Tables sub-entry. You should see the objects created in the TEST schema. If you don't see the objects, click on the database name and then refresh.
Repeat the Process
  1. Map the extracted schema to a different SQL Server schema by repeating the procedure, using the following information:
    DDL task name | schema-nameprod
    Associated transfer list | schema-name
    Connection for execute | HCODemo
    SQL Server schema name | PROD
  2. Save, execute, and verify.

Phase 6: Transfer Data and Verify

You now use the HCOSS Transfer Data tool to populate the schema objects in your SQL Server database with data from your DB2 database.

Transfer Data
  1. From the HCO for SQL Server interface, click Transfer Data. This takes you to the Transfer Data Tasks tab.
  2. Click New to create a new transfer data task.
  3. In the Name field, type schema-nametest.
  4. From the DDL Task drop-down list, select schema-nametest.
  5. Click OK.
  6. From the Source Connection drop-down list, select mainframeDB2, which is the name of your DB2 connection.
  7. From the Destination Connection drop-down list, select HCODemo, which is the name of your SQL Server connection.
  8. Click Save to save the task.
  9. Click Transfer to transfer the list. This takes you to the Results tab where you can view log messages as the transfer takes place.
Verify the Data Transfer
  • In the Eclipse Server Explorer, view the table data for the HCO_Test database's TEST.DEPT table.
Repeat the Process
  1. Transfer data for a different DDL task by repeating the procedure, using the following information:
    Transfer Data task name | schema-nameprod
    Associated DDL task | schema-nameprod
    Source connection | mainframeDB2
    Destination connection | HCODemo
  2. Save, transfer, and verify.

Phase 7: Compare Data

In this final phase, you compare the data in the DB2 database to the data transferred into the SQL Server database using the HCOSS Compare Data tool.

Compare Data
  1. From the HCO for SQL Server interface, click Compare Data.
  2. Select an appropriate Source Connection and Destination Connection.
  3. Click New to create a new compare data task.
  4. In the Name field, type schema-nametest.
  5. From the DDL Task drop-down list, select schema-nametest.
  6. Click OK.
  7. Click Save to save the compare data task.
  8. Click Compare to compare the data. This takes you to the Results tab where you can view messages as the tool compares the data.
Repeat the Process
  1. Compare data for another DDL task by repeating the procedure, using the following information:
    Compare Data task name | schema-nameprod
    Associated DDL task | schema-nameprod
    Source connection | mainframeDB2
    Destination connection | HCODemo
  2. Save and compare.

This completes the tutorial. Next, please complete one or more Application Migration tutorials. These tutorials use the TEST and PROD schemas you created in this tutorial.

Parent topic: Database Migration
Related concepts
Tutorial: Create a SQL Server Database
Tutorial: Create a SQL Server Database Connection
Tutorial: Application Migration - Switching Package Sets
Tutorial: Application Migration - Converting Labeled Duration Calculations
Tutorial: Application Migration - Adding Function Emulation
Related tasks
To start Enterprise Developer as an administrator


Tutorial: DB2 Database Batch Migration

This tutorial takes you through each step in the process of migrating a mainframe-based DB2 table on the mainframe to a local SQL Server using Mainframe Batch Database Tools (MBDT). This process can be done for all the tables in your DB2 database.

Requirements

You must have the Micro Focus Rumba product installed and have it configured to connect to your mainframe.

Before attempting this tutorial, you must first complete the following tutorials to ensure you have an established SQL Server database named HCO_Test and a connection to that database:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create a SQL Server Database Connection

Phase 1: Create a SQL Server schema

You need to create a schema in SQL Server where you can place your migrated DB2 tables.

  • Using SQL Server Management Studio, create a SQL Server schema named DSN8910.

Phase 2: Create unloaded data and the LOAD control statement on the mainframe with DB2

Here, you UNLOAD the sample table, DSN8910.EMP, using Micro Focus Rumba to create and submit the appropriate JCL.

  1. Start Rumba from your desktop by navigating to and selecting Micro Focus Rumba Desktop from the Start menu or by selecting the Micro Focus Rumba Desktop tile from the Start page, depending on your Windows version.
  2. In the Create New Session group, click Mainframe Display.
  3. Click Connection > Connect to start a mainframe session.
  4. In the Application field, type TSO; then press Return.
  5. Type your mainframe user ID; then press Return.
  6. In the Password field, type your mainframe password; then press Return.
  7. In the Option field, type 2; then press Return.
  8. In the Member field of the Edit Entry Panel, type EMPDEMO to create the JCL; then press Return.
  9. Code the JCL required to unload the data from the DSN8910.EMP table using DSNUTILB, and to download the LOAD control statement. For example, here you use the following z/OS mainframe job where the mainframe user is MFIXCH:
    //MFIXCH02 JOB (DB2JOB),'DB2 JOB',REGION=4M,
//     CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//UNLOAD1  EXEC PGM=DSNUTILB,REGION=0M,PARM='DB9R,MFIXCH'
//STEPLIB  DD DSN=DSN910.SDSNLOAD,DISP=SHR
//SYSREC   DD DSN=MFIXCH.UTILBTS.SYSREC1,
//       DISP=(MOD,CATLG),
//       UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSPUNCH DD DSN=MFIXCH.UTILBTS.PUNCH1,
//       UNIT=SYSDA,SPACE=(TRK,(1,1)),DISP=(MOD,CATLG)
//SYSPRINT DD SYSOUT=*
//UTPRINT  DD  DUMMY
//SORTOUT  DD  UNIT=SYSDA,SPACE=(4000,(20,20),,,ROUND)
//SYSDISC  DD  DUMMY
//SYSERR   DD  UNIT=SYSDA,SPACE=(4000,(20,20),,,ROUND)
//SYSMAP   DD  UNIT=SYSDA,SPACE=(4000,(20,20),,,ROUND)
//SYSUT1   DD  UNIT=SYSDA,SPACE=(4000,(20,20),,,ROUND)
//SYSIN    DD *
UNLOAD DATA FROM TABLE DSN8910.EMP
/*
//
  10. To save and submit your JCL, enter SAVE into the Command field, and then enter SUB into the Command field.

Phase 3: Create and configure an enterprise server instance

Now you want to use Enterprise Server to create an enterprise server instance with Mainframe Subsystem (MSS). MSS enterprise servers support JCL applications in Enterprise Developer.

Create an MSS enterprise server instance
  • Follow all of the instructions presented in the Configure an Enterprise Server for JCL Support section of the JCL tutorial in this documentation; however, substitute DSNUTILS wherever JCLDEMO is specified.
Set up XA resources
Now that the enterprise server is created and started, you need to set up the XA resources.
  1. Ensure that you have returned to the Enterprise Server Administration Home page.
  2. Click the Details button that corresponds to the started DSNUTILS enterprise server.
  3. Click Server > Properties > XA Resources; then click Add.
  4. Populate the fields on the XA Resources tab as follows:
    ID | HCOD
    Name | HCODEMO
    Module | esodbcxa.dll
    Open string | DSN=HCODEMO
  5. Click Add to complete the XA resources setup.
Create aliases for MBDT
  1. Click Server > Control; then click ES Monitor and Control.
  2. From the Resources menu in the left pane, click JES; then click Alias.
  3. Create the following aliases:
    Program | Alias
    HCOTEP2 | SQLTP2
    HCOUTILB | SQLUTB
  4. Click Update to save the aliases.

Phase 4: Copy the LOAD control statement

In this phase, you copy the LOAD control statement from the mainframe to your Windows machine using Micro Focus Mainframe Access Drag and Drop.

  1. Start Windows Explorer, and browse to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.
  2. Double-click mfdasmx.exe to launch Micro Focus Mainframe Access Drag and Drop.
  3. In the User Identification field, type your mainframe user ID.
  4. In the Current field, type your mainframe password.
  5. In the Catalog search criteria field, enter the PDS prefix for the PDS that contains your LOAD control statement; then click OK.
  6. Click Configure > Options.
  7. In the EBCDIC/ASCII translation group, check Sequential; then click OK.
  8. Drag and drop the mainframeID.UTILBTS.PUNCH1 file from the right pane to a destination folder in the left pane.
  9. Click OK on each popup notice.
  10. Close Mainframe Access Drag and Drop.

Phase 5: Copy and catalog the unloaded DB2 data

Using Micro Focus Mainframe Access command-line tools, you copy the unloaded DB2 data to your Windows machine, and catalog the data there.

  1. Start an Enterprise Developer command prompt as an administrator. If you need instructions, see To start an Enterprise Developer command prompt as an administrator.
  2. At the command prompt, enter the following to copy the unloaded data in mainframeID.UTILBTS.SYSREC1 to a data file, DSN8910_EMP.DAT, and catalog mainframeID.UTILBTS.SYSREC1 in your DSNUTILS enterprise server instance:
    MFDAS IMPORT datFilePath\DSN8910_EMP.DAT FROM QSAM
mainframeID.UTILBTS.SYSREC1 /CATLOC=ESWorkArea\DSNUTILS\catalog.dat
    Where:
    mainframeID | The dataset qualifier
    datFilePath | The local path to the directory where you want to store the extracted data file
    DSN8910_EMP.DAT | The name of the data file containing extracted data
    ESWorkArea | Your Enterprise Server WORKAREA folder, which by default is %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA
    DSNUTILS | The name of your enterprise server instance
    catalog.dat | The name of the enterprise server catalog data file
    After the command has completed, the mainframeID.UTILBTS.SYSREC1 data set has been copied to the DSN8910_EMP.DAT file and cataloged as mainframeID.UTILBTS.SYSREC1 in your enterprise server.

Phase 6: Load the SQL Server database

To enhance the performance of LOAD DATA into SQL Server databases, you divide the creation of schema objects into two steps. In the first DSNTEP2 step, before you load the actual data, you create tables and primary keys only, because when creating primary keys, SQL Server automatically creates a clustered index for each primary key. A clustered index helps the performance of LOAD DATA and minimizes the use of disk space. In another step you create constraints and indexes. After you load the data, you execute another DSNTEP2 step where you create constraints and indexes.

Create an Eclipse project
  1. Start Enterprise Developer.
  2. Click File > New > Mainframe COBOL Project.
  3. In the Project name field, type JCL1; then click Finish to create a new JCL application project.
Associate the DSNUTILS enterprise server with the JCL1 project
  1. To start the Server Explorer, click Window > Show View > Other > Micro Focus COBOL > Server Explorer; then click OK.
  2. From Server Explorer, expand Localhost to see a list of available enterprise servers.
  3. Right-click the DSNUTILS enterprise server; then click Associate with project > JCL1.
  4. If not already started, right-click the DSNUTILS enterprise server; then select Start.
  5. On the sign-on dialog box, click OK; then click No to disable password recovery.
Run the MBDT Configuration Utility
  1. From Enterprise Developer, click Run > Tools > MBDT Configuration Utility.
  2. In the Database Selection group, select HCOSS
  3. Click Save to exit the MBDT Configuration Utility.
Create DB2 tables in the SQL Server database using SQLTP2
The SQLTP2 utility creates the appropriate DB2 tables in your new SQL Server database. You execute the SQLTP2 alias in JCL using the HCOTEP2 program name. In this phase, you create the JCL in your JCL1 project, and execute it from your JCL1 project.
  1. From the COBOL Explorer, right-click the JCL1 project, and select New > JCL File.
  2. In the New file name field, type JCLTEP2.jcl; then click Finish.
  3. Open the JCLTEP2.jcl file, and replace its contents with the JCLTEP2 job shown below. This assumes you have setup the XA resource HCOD and created alias SQLTP2 for program HCOTEP2, all of which is required for successful execution later:
    //JCLTEP2  JOB
//RESETDB  EXEC PGM=IKJEFT01
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSPUNCH DD  SYSOUT=*
//SYSREC00 DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSTSIN  DD  *
 DSN SYSTEM(HCOD)
 RUN  PROGRAM(HCOTEP2)
 END
/*
//SYSIN DD *
CREATE TABLE DSN8910.EMP (
    EMPNO       CHAR(6) NOT NULL,
    FIRSTNME    VARCHAR(12) NOT NULL,
    MIDINIT     CHAR(1) NOT NULL,
    LASTNAME    VARCHAR(15) NOT NULL,
    WORKDEPT    CHAR(3),
    PHONENO     CHAR(4),
    HIREDATE    DATE,
    JOB         CHAR(8),
    EDLEVEL     SMALLINT,
    SEX         CHAR(1),
    BIRTHDATE   DATE,
    SALARY      DECIMAL(9,2),
    BONUS       DECIMAL(9,2),
    COMM        DECIMAL(9,2),
    PRIMARY KEY (EMPNO)
)
IN DATABASE DBNATS;

/*
//
  4. Save and close the JCL file.
  5. In the COBOL Explorer, right-click JCLTEP2.jcl; then select Submit to Enterprise Server from the context menu.
  6. When the job has completed, open SQL Server Management Studio and verify that the DSN8910.EMP table and clustered index definitions are correct.
Load DB2 Data into SQL Server
Now you load the DB2 data into the new SQL Server database using SQLUTB with the LOAD card generated on the mainframe.
  1. From the COBOL Explorer, right-click the JCL1 project, and select New > JCL File.
  2. In the New file name field, type JCLUTILB.jcl; then click Finish.
  3. Open the JCLUTILB.jcl file, and replace its contents with the JCLUTILB job shown below, replacing MFIXCH with your mainframeID. This assumes you have setup the XA resource HCOD and created alias SQLUTB for program HCOUTILB, all of which is required for successful execution later:
    //JCLUTILB JOB
//DSNUPROC EXEC PGM=HCOUTILB,PARM='HCOD,SH      '
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//STPRIN01 DD   SYSOUT=*
//IDIOFF   DD   DUMMY
//*
//SYSUT1   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSUT1
//SORTOUT  DD   DISP=MOD,DSN=SH.DSNUTILB.SYSOUT
//SYSMAP   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSMAP
//SYSERR   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSERR
//SYSREC   DD   DISP=SHR,DSN=MFIXCH.UTILBTS.SYSREC1
//SYSIN    DD   *
LOAD DATA INDDN SYSREC LOG NO RESUME NO REPLACE
EBCDIC  CCSID(00037,00000,00000)
 INTO TABLE
 "DSN8910".
 "EMP"
 WHEN(00001:00002) = X'0012'
 NUMRECS                   42
 ( "EMPNO"
  POSITION(  00003:00008) CHAR(00006)
 , "FIRSTNME"
  POSITION(  00009:00022) VARCHAR
 , "MIDINIT"
  POSITION(  00023:00023) CHAR(00001)
 , "LASTNAME"
  POSITION(  00024:00040) VARCHAR
 , "WORKDEPT"
  POSITION(  00042:00044) CHAR(00003)
                          NULLIF(00041)=X'FF'
 , "PHONENO"
  POSITION(  00046:00049) CHAR(00004)
                          NULLIF(00045)=X'FF'
 , "HIREDATE"
  POSITION(  00051:00060) DATE EXTERNAL
                          NULLIF(00050)=X'FF'
 , "JOB"
  POSITION(  00062:00069) CHAR(00008)
                          NULLIF(00061)=X'FF'
 , "EDLEVEL"
  POSITION(  00071:00072) SMALLINT
                          NULLIF(00070)=X'FF'
 , "SEX"
  POSITION(  00074:00074) CHAR(00001)
                          NULLIF(00073)=X'FF'
 , "BIRTHDATE"
  POSITION(  00076:00085) DATE EXTERNAL
                          NULLIF(00075)=X'FF'
 , "SALARY"
  POSITION(  00087:00091) DECIMAL
                          NULLIF(00086)=X'FF'
 , "BONUS"
  POSITION(  00093:00097) DECIMAL
                          NULLIF(00092)=X'FF'
 , "COMM"
  POSITION(  00099:00103) DECIMAL
                          NULLIF(00098)=X'FF'
 )

/*
//
  4. Save and close the JCL file.
  5. In the COBOL Explorer, right-click JCLUTILB.jcl; then select Submit to Enterprise Server from the context menu.
  6. When the job has completed, open SQL Server Management Studio and verify that the data in mainframeID.UTILBTS.SYSREC1 has been successfully loaded into the DSN8910.EMP table.
Execute DDL to create DB2 constraints and indexes
You execute SQLTP2 again to create the DB2 constraints and indexes in the SQL Server database.
  1. From the COBOL Explorer, right-click the JCL1 project, and select New > JCL File.
  2. In the New file name field, type JCLINDX.jcl; then click Finish.

  3. Open the JCLINDX.jcl file, and replace its contents with the JCLINDX job shown below:

    //JCLINDX JOB
//RESETDB  EXEC PGM=IKJEFT01
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSPUNCH DD  SYSOUT=*
//SYSREC00 DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSTSIN  DD  *
 DSN SYSTEM(HCOD)
 RUN  PROGRAM(HCOTEP2)
 END
/*
//SYSIN DD *
ALTER TABLE DSN8910.EMP
   ADD CONSTRAINT MIN_SALARY CHECK (SALARY > 15000.00);
CREATE INDEX DSN8910.XEMP2 ON DSN8910.EMP(WORKDEPT);

/*
//
  4. Save and close the JCL file.
  5. In the COBOL Explorer, right-click JCLINDX.jcl; then select Submit to Enterprise Server from the context menu.
  6. When the job has completed, open SQL Server Management Studio and verify the constraints and indexes under the DSN8910.EMP. In particular, see that the DSN8910 qualifier in the XEMP2 index has been removed in SQL Server.
Parent topic: Database Migration
Related tasks
To start an Enterprise Developer command prompt as an administrator


Application Migration

These tutorials walk you through three different methods you can use to migrate COBOL applications from DB2 to SQL Server.

  • Prerequisites
    Describes the requirements that must be in place before running any of the Application Migration tutorials.
  • Tutorial: Application Migration - Switching Package Sets
    This tutorial takes you through the process of migrating a DB2 application to a SQL Server application, using HCOSS to switch package sets and alternate fetching data using a single cursor name.
  • Tutorial: Application Migration - Converting Labeled Duration Calculations
    This tutorial takes you through the process of migrating a DB2 application to a SQL Server application, using HCOSS to convert labeled duration calculations and managing date formats.
  • Tutorial: Application Migration - Adding Function Emulation
    This tutorial takes you through the process of migrating a DB2 application to a SQL Server application, using HCOSS to add function emulation.
Parent topic: Tutorials: HCO for SQL Server (HCOSS)


Prerequisites

Before progressing to any of the Application Migration... tutorials, complete the following tutorials in the order listed:

  • Tutorial: Create a SQL Server Database
    This tutorial takes you through the process of using Microsoft SQL Server Management Studio to create a SQL Server database.
  • Tutorial: Create a SQL Server Database Connection
    This tutorial takes you through the process of creating a connection to your SQL Server database using the HCOSS Manage Connections tool.
  • Tutorial: Setup for Application Migration Tutorials
    As a quick alternative to completing Tutorial: DB2 Database Migration as a prerequisite for the Application Migration tutorials, this tutorial takes you through the process of setting up the DB2 database components required to enable completion of the Application Migration tutorials without having to do a complete migration.
Parent topic: Application Migration


Tutorial: Setup for Application Migration Tutorials

As a quick alternative to completing Tutorial: DB2 Database Migration as a prerequisite for the Application Migration tutorials, this tutorial takes you through the process of setting up the DB2 database components required to enable completion of the Application Migration tutorials without having to do a complete migration.

All three Application Migration tutorials require that you have access to a migrated DB2 database. In this tutorial you run an SQL script that creates the appropriate DB2 migration files.

  1. Start Microsoft SQL Server Management Studio.
  2. Connect to the HCODemo SQL Server connection you created in the Create a SQL Server Database Connection tutorial.
  3. Click File > Open > File.
  4. Browse to the CreateAndLoadHCO_Test.sql SQL script, located by default in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\SQL\hcoss directory.
  5. Double-click CreateAndLoadHCO_Test.sql to open it.
  6. Click Execute on tool bar.
  7. Close SQL Server Management Studio.
This completes the tutorial. You are ready to move on to any of these Application Migration tutorials:
  • Tutorial: Application Migration - Switching Package Sets
  • Tutorial: Application Migration - Converting Labeled Duration Calculations
  • Tutorial: Application Migration - Adding Function Emulation
Parent topic: Prerequisites
Related concepts
Tutorial: Application Migration - Switching Package Sets
Tutorial: Application Migration - Converting Labeled Duration Calculations
Tutorial: Application Migration - Adding Function Emulation


Tutorial: Application Migration - Switching Package Sets

This tutorial takes you through the process of migrating a DB2 application to a SQL Server application, using HCOSS to switch package sets and alternate fetching data using a single cursor name.

This tutorial also demonstrates how, with HCOSS, you can bind the application using the HCOSS Manage Packages and Plans tool.

Requirements

Before attempting this tutorial, you must first complete the following tutorials to ensure you have an established SQL Server database named HCO_Test containing the required PROD and TEST schemas and a connection to the HCO_Test database:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create a Database Connection
  • Tutorial: DB2 Database Migration or Tutorial: Setup for Application Migration Tutorials

Eclipse Project

The Eclipse project we provide for this tutorial contains the TwoPackageSet project, which is a native COBOL project.

Phase 1: Start Enterprise Developer and HCO for SQL Server

If Enterprise Developer and HCOSS for SQL Server tools are already running, skip this phase.

  1. Start Enterprise Developer as an administrator. This procedure varies depending on your Windows version. If you need instructions, see To start Enterprise Developer as an administrator.
  2. In Eclipse, click Run > Tools > Data Tools > HCO for SQL Server.

Phase 2: Analyze the Native Application

  1. From the Eclipse IDE, click File > Import.
  2. Expand General, and select Existing Projects into Workspace; then click Next.
  3. Select Set root directory; then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\Eclipse\SQL\hcoss\TwoPackageSet directory, and click OK.
  4. On the Projects list, check TwoPackageSet.
  5. Check Copy projects into workspace.
  6. Click Finish. Eclipse loads the project and builds it automatically.
  7. From the COBOL Explorer, expand TwoPackageSet > COBOL Programs; then double-click the TwoPackageSet.cbl file to view its contents. Pay particular attention to the EXEC SQL statements.
  8. Close the code editor.
  9. Open the project properties for the TwoPackageSet project.
  10. Expand Micro Focus > Project Settings > COBOL; then select SQL Settings. Several OpenESQL compiler directives have been set for you. The following table offers a brief description of each:
    SQL(BEHAVIOR=OPTIMIZED) | Optimizes ambiguous cursor declarations
    SQL(DBMAN=ODBC) | Uses an ODBC connection
    SQL(TARGETDB=MSSQLSERVER) | Target database is SQL Server
    SQL(DB=HCODemo) | SQL Server connection name is HCODemo
    SQL(DIALECT=MAINFRAME) | HCOSS database syntax conversion is enabled
    SQL(DBRMLIB) | EXEC-SQL commands are extracted and placed in database request module (DBRM)
    SQL(DETECTDATE) | Converts date/time strings
    SQL(INIT) | Initiates the database connection
    SQL(MARS) | Enables multiple active results sets
    SQL(QUALIFIER=TEST) | Schema qualifier is TEST
    SQL(NOCHECK) | No SQL compile-time checking performed
  11. Close the Properties window.

Phase 3: Bind the Native Application

Here, you bind the application to the DBRM generated when the application was built. You do this using the HCOSS Manage Packages and Plans tool to create two packages and a plan. Each package you create is in its own collection and has a unique qualifier, but both point to the same source member and library. You then bind both packages into one plan.

Start the Manage Packages and Plans Tool
  1. From the HCO for SQL Server interface, click Manage Packages and Plans.
  2. From the SQL Server Connection drop-down list, select HCODemo.
Create Two Packages
  1. Click New Package. Then specify the following:
    Property | Value
    Collection Name | TEST
    Library Name | <Default>
    Member Name | TWOPACKAGESET
    Default Qualifier | TEST
    Action | Replace
  2. Click Execute. This creates the package in the database.
  3. Change the Collection Name to PROD and the Default Qualifier to PROD.
  4. Click Execute. This creates a second package.
  5. Switch to the Bind Scripts tab. Notice the BIND script commands that were created as a result of creating each package.
Bind the Two Packages into a Plan
  1. Click New Plan.
  2. In the Plan Name field, type TWOPACKAGESET.
  3. On the Available Collections list, click PROD.
  4. On the Available Packages list, click TWOPACKAGESET.
  5. Click Add to add this package to the Selected Packages list.
  6. Repeat steps 3 through 5, substituting TEST instead of PROD, to add the TEST.TWOPACKAGESET package to the Selected Packages list.
  7. In the Action group, click Replace.
  8. Click Execute to add the BIND PLAN entry to the script and to also bind the plan.
Verify the Results
  1. Using Microsoft SQL Server Management Studio, connect to your SQL Server instance.
  2. On the Object Explorer, expand Databases > HCO_Test > Programmability > Stored Procedures to see the stored procedures HCOSS created when you executed your packages and plan.
  3. Open one of the stored procedures that contains PKG as part of its name.

    In this, you see the SQL from your application code. You also see SQL Server function calls to UPPER. These were converted from DB2 function calls to UCASE. This is due to having set the SQL(DIALECT=MAINFRAME) directive when you compiled.

Phase 4: Run the Native Application

  1. From the COBOL Explorer in Eclipse, open the TwoPackageSet.cbl source file.
  2. Set a break point on the STOP RUN line.
  3. Click Run > Debug to start debugging.
  4. If prompted with the Debug As dialog box, select COBOL Application; then click OK.
  5. When prompted to open the Debug perspective, click Yes.
  6. Click Resume to continue to your breakpoint.

You should see from the output that alternating rows are coming from different database schemas. This demonstrates the use of a single cursor to switch package sets, pulling data from different schemas.

Note: If the output window is not visible, minimize Eclipse to reveal it.

This completes the tutorial.

Parent topic: Application Migration
Related concepts
Tutorial: Create a SQL Server Database
Tutorial: Create a SQL Server Database Connection
Tutorial: Setup for Application Migration Tutorials
Tutorial: DB2 Database Migration
Related tasks
To start Enterprise Developer as an administrator


Tutorial: Application Migration - Converting Labeled Duration Calculations

This tutorial takes you through the process of migrating a DB2 application to a SQL Server application, using HCOSS to convert labeled duration calculations and managing date formats.

SQL Server does not support labeled duration calculations directly. HCOSS handles the conversion to T-SQL to implement the DB2 syntax of an EXEC SQL statement using labeled durations.

This tutorial also demonstrates binding the application using a post-build event in Eclipse.

Requirements

Before attempting this tutorial, you must first complete the following tutorials to ensure you have an established SQL Server database named HCO_Test containing the required PROD and TEST schemas and a connection to the HCO_Test database:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create a Database Connection
  • Tutorial: DB2 Database Migration or Tutorial: Setup for Application Migration Tutorials

Eclipse Project

The Eclipse project we provide for this tutorial contains the LBLDURATION project, which is a native COBOL project.

Phase 1: Start Enterprise Developer and HCO for SQL Server

If Enterprise Developer and HCOSS for SQL Server tools are already running, skip this phase.

  1. Start Enterprise Developer as an administrator. This procedure varies depending on your Windows version. If you need instructions, see To start Enterprise Developer as an administrator.
  2. In Eclipse, click Run > Tools > Data Tools > HCO for SQL Server.

Phase 2: Analyze, Build, and Bind the Native Application

Analyze the Native Application
  1. From the Eclipse IDE, click File > Import.
  2. Expand General, and select Existing Projects into Workspace; then click Next.
  3. Select Set root directory; then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\Eclipse\SQL\hcoss\LBLDURATION directory, and click OK.
  4. On the Projects list, check LBLDURATION.
  5. Check Copy projects into workspace.
  6. Click Finish. Eclipse loads the project and builds it automatically.
  7. From the COBOL Explorer, expand LBLDURATION > COBOL Programs; then double-click the LBLDURATION.cbl file to view its contents. Pay particular attention to the following EXEC SQL statement:
               EXEC SQL
               DECLARE CSR69 CURSOR FOR SELECT
                A.PROJNO
               ,A.PROJNAME
               ,A.PRSTDATE
               ,A.PRENDATE
               ,(((DAYS(A.PRENDATE) - DAYS(A.PRSTDATE) ) / 7) + 1) * 40
               AS MANHOURS
               FROM PROJ A
               ORDER BY A.PROJNAME
           END-EXEC
    This contains your labeled duration calculation:
    ,(((DAYS(A.PRENDATE) - DAYS(A.PRSTDATE) ) / 7) + 1) * 40
    In this case, you are using the DAYS labeled duration in a calculation where you:
    • Start with the number of days between the start and end date for projects
    • Divide that number by 7 to get the number of weeks
    • Add 1 to account for truncation of a partial week
    • Multiply that result by 40 to get the number of hours needed to complete the project
  8. Close the code editor.
  9. Open the project properties for the LBLDURATION project.
  10. Expand Micro Focus > Project Settings > COBOL; then select SQL Settings. Several OpenESQL compiler directives have been set for you. The following table offers a brief description of each:
    SQL(DBMAN=ODBC) | Uses an ODBC connection
    SQL(TARGETDB=MSSQLSERVER) | Target database is SQL Server
    SQL(DB=HCODemo) | SQL Server connection name is HCODemo
    SQL(DIALECT=MAINFRAME) | HCOSS database syntax conversion is enabled
    SQL(DBRMLIB) | EXEC-SQL commands are extracted and placed in database request module (DBRM)
    SQL(DATE=USA) | Date output is in USA format
    SQL(INIT) | Initiates the database connection
    SQL(QUALIFIER=TEST) | Schema qualifier is TEST
    SQL(NOCHECK) | No SQL compile-time checking performed
    SQL(BEHAVIOR=OPTIMIZED) | Optimizes migration process
Define a Post-Build Event
  1. In the Properties window, expand Micro Focus > Build Configurations > Events.
  2. In the Post build event command line field, type the following command:
    DSN SYSTEM(HCODemo) @"LBLDURATION.hcodsn"

    This command calls the DSN Bind utility, specifies the SQL database connection to use, and states the location and name of a bind script file. Eclipse executes this event immediately after building the application, automatically binding the application at that time.

  3. Click OK. Eclipse builds the native application automatically.
View the Contents of the Bind Script File
  • From the COBOL Explorer, open and review the content of LBLDURATION.hcodsn. This bind script file contains one BIND PLAN command that binds the LBLDURATION member into a plan named LBLDURATION.
Verify the Results
  1. Using Microsoft SQL Server Management Studio, connect to your SQL Server instance.
  2. On the Object Explorer, expand Databases > HCO_Test > Programmability > Stored Procedures to see the stored procedures HCOSS created when you executed your packages and plan.
  3. Open the stored procedure named PLN:LBLDURATION.LBLDURATIONconsistency-token$0, where consistency-token is the value of the generated consistency token.

    In this, you see the SQL from your application code. You also see that HCOSS has converted the original DB2 DAYS expression into T-SQL syntax that recreates the same functionality in SQL Server. This is due to having set the SQL(DIALECT=MAINFRAME) directive when you compiled.

Phase 3: Run the Native Application

  1. From the COBOL Explorer, open the LBLDURATION.cbl source file.
  2. Set a break point on the GO BACK line.
  3. Click Run > Debug to start debugging.
  4. If prompted with the Debug As dialog box, select COBOL Application; then click OK.
  5. When prompted to open the Debug perspective, click Yes.
  6. Click Resume to continue to your breakpoint.

You see from the output that your results show the hours required to complete each project. All output dates are in USA format.

Note: If the output window is not visible, minimize Eclipse to reveal it.

This completes the tutorial.

Parent topic: Application Migration
Related concepts
Tutorial: Create a SQL Server Database
Tutorial: Create a SQL Server Database Connection
Tutorial: Setup for Application Migration Tutorials
Tutorial: DB2 Database Migration
Related tasks
To start Enterprise Developer as an administrator


Tutorial: Application Migration - Adding Function Emulation

This tutorial takes you through the process of migrating a DB2 application to a SQL Server application, using HCOSS to add function emulation.
This tutorial demonstrates adding function emulation by taking you through the process of:
  • Adding math functions to SQL Server that represent standard math functions in DB2.
  • Mapping the DB2 functions to the new SQL Server functions using the Customize SQL Name Mapping tool.

This tutorial also demonstrates binding the application using a post-build event in Eclipse.

Requirements

Before attempting this tutorial, you must first complete the following tutorials to ensure you have an established SQL Server database named HCO_Test containing the required PROD and TEST schemas and a connection to the HCO_Test database:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create a Database Connection
  • Tutorial: DB2 Database Migration or Tutorial: Setup for Application Migration Tutorials

Eclipse Project

The Eclipse project we provide for this tutorial contains the FunctionEmulation project, which is a native COBOL project.

Phase 1: Create User-Defined Functions

  1. Launch SQL Server Management Studio, and select the HCO_Test database.
  2. Navigate to and open the FunctionEmulation.sql file, located in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\Eclipse\SQL\hcoss\FunctionEmulation directory.

    This file contains a script that creates some user defined math functions needed by the example code.

  3. Click Execute.
  4. From the Object Explorer expand and select HCO_Test > Programmability > Functions > Scalar-Valued Functions and Refresh this folder. You should now see the newly created functions.

Phase 2: Start Enterprise Developer and HCO for SQL Server

If Enterprise Developer and HCOSS for SQL Server tools are already running, skip this phase.

  1. Start Enterprise Developer as an administrator. This procedure varies depending on your Windows version. If you need instructions, see To start Enterprise Developer as an administrator.
  2. In Eclipse, click Run > Tools > Data Tools > HCO for SQL Server.

Phase 3: Map the Functions for HCOSS

  1. From the HCO for SQL Server interface, click Customize SQL Name Mappings.
  2. Scroll to the bottom of the grid and double-click in the first empty cell to activate it for editing. Type the following information in the appropriate rows and columns, and check the corresponding Is Function box for each:
    DB2 Function/Special Register | SQL Server Equivalent
    atanh | dbo.atanh
    cosh | dbo.cosh
    sinh | dbo.sinh
    tanh | dbo.tanh
  3. Click Save to save the mappings.

Phase 4: Analyze, Build, and Bind the Native Application

Analyze the Native Application
  1. From the Eclipse IDE, click File > Import.
  2. Expand General, and select Existing Projects into Workspace; then click Next.
  3. Select Set root directory; then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\SQL\hcoss\FunctionEmulation directory, and click OK.
  4. On the Projects list, check FunctionEmulation.
  5. Check Copy projects into workspace.
  6. Click Finish. Eclipse loads the project and builds it automatically.
  7. From the COBOL Explorer, expand FunctionEmulation > COBOL Programs; then double-click the FunctionEmulation.cbl file to view its contents.Pay particular attention to the EXEC SQL statement that references the user-defined functions.
  8. Close the code editor.
  9. Open the project properties for the FunctionEmulation project.
  10. Expand Micro Focus > Project Settings > COBOL; then select SQL Settings. Several OpenESQL compiler directives have been set for you. The following table offers a brief description of each:
    SQL(TARGETDB=MSSQLSERVER) | Target database is SQL Server
    SQL(DB=HCODemo) | SQL Server connection name is HCODemo
    SQL(DIALECT=MAINFRAME) | HCOSS database syntax conversion is enabled
    SQL(DBRMLIB) | EXEC-SQL commands are extracted and placed in database request module (DBRM)
    SQL(INIT) | Initiates the database connection
    SQL(NOCHECK) | No SQL compile-time checking performed
    SQL(BEHAVIOR=OPTIMIZED) | Optimizes migration process
Define a Post-Build Event
  1. In the Properties window, expand Micro Focus > Build Configurations > Events.
  2. In the Post build event command line field, type the following command:
    DSN SYSTEM(HCODemo) @"FunctionEmulation.hcodsn"

    This command calls the DSN Bind utility, specifies the SQL database connection to use, and states the location and name of a bind script file. Eclipse executes this event immediately after building the application, automatically binding the application at that time.

  3. Click OK. Eclipse builds the native application automatically.
View the Contents of the Bind Script File
  • From the COBOL Explorer, open and review the content of FunctionEmulation.hcodsn. This bind script file contains one BIND PLAN command that binds the FunctionEmulation member into a plan named FunctionEmulation.
Verify the Results
  1. Using Microsoft SQL Server Management Studio, connect to your SQL Server instance.
  2. On the Object Explorer, expand Databases > HCO_Test > Programmability > Stored Procedures to see the stored procedures HCOSS created when you executed your packages and plan.
  3. Open one of the stored procedures that contains PLN as part of its name.

    In this, you see your application code making the calls to the user-defined functions.

Phase 5: Run the Native Application

  1. From the COBOL Explorer, open the FunctionEmulation.cbl source file.
  2. Set a break point on the line containing if sqlcode = 0.
  3. Click Run > Debug to start debugging.
  4. If prompted with the Debug As dialog box, select COBOL Application; then click OK.
  5. When prompted to open the Debug perspective, click Yes.
  6. Click Resume to continue to your breakpoint.

You should see from the output that the results are calculations performed by your user-defined functions.

Note: If the output window is not visible, minimize Eclipse to reveal it.

This completes the tutorial.

Parent topic: Application Migration
Related concepts
Tutorial: Create a SQL Server Database
Tutorial: Create a SQL Server Database Connection
Tutorial: Setup for Application Migration Tutorials
Tutorial: DB2 Database Migration
Related tasks
To start Enterprise Developer as an administrator


Tutorial: Assembler

AACT is a sample CICS 3270 transaction that comprises several Assembler programs and a single BMS map, and uses the resource definitions in the file dfhdrdat. This tutorial walks you through the steps required to implement and test the AACT transaction.

Prerequisites

To complete this tutorial in Enterprise Developer you also need:
  • Micro Focus Rumba or another TN3270 emulator - this is supplied with the Enterprise Developer installer
  • A Team Edition license for Enterprise Developer
  • This tutorial assumes that your Enterprise Developer project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Demonstration Application

The CICS application that you use in this tutorial is the AACT demonstration application, the standard example application that IBM supplies with CICS systems. The AACT application executables are supplied with Enterprise Developer.

  1. Create a Project
  2. Import Files from the Demonstration Program
  3. Create an Enterprise Server
  4. Configure the Enterprise Server
  5. Start the AACT Enterprise Server
  6. Run the AACT Transaction
Parent topic: Mainframe Tutorials


Create a Project

You create a project that comprises all the parts of your application. In this case, the Assembler source and BMS files.

  1. Start Eclipse with workspace directory c:\tutorials.
  2. On the Welcome page, click Open Team Developer Perspective.

    In the perspective, you should see the Enterprise Developer system in the Application Explorer view. If the system is not shown, to load it:

    1. Right-click in the Application Explorer view and click Add System(s).
    2. In the Add System(s) dialog box, select ED System and click OK.
    3. Expand the top-level Enterprise Developer entry in the Application Explorer view.
    4. Right-click Enterprise Developer Projects; then click Load Application.
  3. Expand the top-level Enterprise Developer entry in the Application Explorer view.
  4. Right-click Enterprise Developer Projects in the Application Explorer view, and click New COBOL Project > Mainframe COBOL Project .
  5. Specify the project name AACT and click Finish.

    Eclipse creates the project in the c:\tutorials\AACT directory, and the Application Explorer view shows the AACT project.

  6. Right-click the AACT project in the Application Explorer view, and click New > Folder > Folder.
  7. Specify loadlib as the folder name, and click Finish.

    This is the folder for the files generated by your project. You now need to configure the project to produce the generated files in the loadlib subfolder.

  8. Right-click the project in the Application Explorer view, and click Properties.
  9. Expand Micro Focus > Build Configurations and click COBOL.
  10. In the Output Path field, click Browse, select the loadlib folder; then click Apply and Close.
Parent topic: Tutorial: Assembler
Next topic: Import Files from the Demonstration Program


Import Files from the Demonstration Program

In this step, you import the files from the AACT demonstration transaction into your project, and copy the resource definition file to the project.

  1. In Eclipse, select the AACT project in the Application Explorer view, and then select File > Import from the main menu.
  2. Expand General, click File System, and click Next.
  3. Browse to and select the directory that stores the AACT sample files, %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\Assembler\Classic\AACT, and click OK.

    This displays the list of the files available in the in the AACT directory.

  4. in the left pane, check AACT.
  5. In the right pane, scroll down an uncheck Readme.xml.
  6. Click Finish.

    This action adds the AACT application files to the project folder, creates the SYSTEM project subfolder (not visible from the Eclipse IDE), and adds the default dfhdrdat resource definition file to the SYSTEM subfolder. In addition, Eclipse automatically builds the project (see Prerequisites in the Tutorial: Assember topic). In this case, the build fails because you need to set some project properties to specify that the Assembler programs use CICS.

  7. Right-click the AACT project in the Application Explorer view, and click Properties.
  8. In the Properties for AACT dialog box, expand Micro Focus > Project Settings > Assembler Compiler and click CICS Preprocessor.
  9. Check Use CICS Preprocessor, and click Apply and Close.

    This triggers a rebuild of the project, and this time it is successful.

  10. Start an Enterprise Developer command prompt. If you need instructions, see To start an Enterprise Developer command prompt.
  11. Enter the following to upgrade the default dfhdrdat resource definition file to include CICS resources:
    caspcupg /dp=c:\tutorials\aact\system
Parent topic: Tutorial: Assembler
Previous topic: Create a Project
Next topic: Create an Enterprise Server
Related tasks
To start an Enterprise Developer command prompt


Create an Enterprise Server

To successfully run your new AACT application, you must first create a new enterprise server instance configured for Mainframe Subsystem Support, and with Assembler enabled.

  1. In Eclipse, open the Server Explorer view.

    If it is not visible, to display it click Window > Show View > Other, type Server Explorer, select the view and click OK.

  2. Right-click Local [localhost:86] in Server Explorer and click New > Enterprise Server.
  3. In the New Enterprise Server dialog box, specify AACT in the Name field.
    Note: At some point in the process of creating a new enterprise server region, you might be prompted to provide connection details by an Enterprise Server Sign On dialog box. This is a standard security dialog box. Click OK without specifying any sign on details. Also, if prompted to disable password recovery, click No.
  4. Click the browse button on the row of the Template field.

    This opens the location of the Enterprise Server templates shipped with Enterprise Developer - by default, these are in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates.

  5. Select the CICSTemplate.xml file, and click Open.

    This template creates an enterprise server with Mainframe Subsystem Support configured for CICS.

  6. Check the AACT box to associate the new enterprise server region with the AACT project.
  7. Click Finish to create the server.

    Server Explorer refreshes the localhost node to show the AACT server. You now need to configure the server.

  8. In Server Explorer, right-click Local [localhost:86] and click Open Administration Page.

    This opens the home page of Enterprise Server Administration in the IDE.

  9. Click Edit on the row for AACT.
  10. You need to set these two environment variables:
    BASE=c:\tutorials\AACT | Provides your enterprise server with the path to your project files
    ES_MFASM_SUPPORT=Y | Enables Assembler for CICS regions
    To do this, type the following into the Configuration Information field on the General page:
    [ES-Environment]
BASE=c:\tutorials\AACT
ES_MFASM_SUPPORT=Y
  11. Click Apply.
  12. Click the Listeners tab.
  13. Click Edit on the row for the TN3270 listener.
  14. Change the Endpoint Address field to *:9004 and click OK.

    This is the port number used when you connect to the enterprise server with your TN3270 emulator.

  15. Click the Server tab.
  16. In the Description field, type a description of the new enterprise server, for example Assembler AACT Tutorial.
  17. Click OK at the bottom of the page, and then click Home in the upper left corner.

    This displays the Enterprise Server Administration Home page with your new AACT server in the list of the available enterprise servers.

Parent topic: Tutorial: Assembler
Previous topic: Import Files from the Demonstration Program
Next topic: Configure the Enterprise Server


Configure the Enterprise Server

Now you need to configure your enterprise server instance to enable it to run AACT Assembler/CICS application.

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the AACT enterprise server.
  2. Go to the Server > Properties > MSS > CICS tab.

    Some of the values on this page have definitions that come from the enterprise server template you used. You need to replace them with values that are needed for your application.

  3. Type ASMSIT into the System Initialization Table field. The ASMSIT is provided for you and contains all of the resource information necessary to run the AACT application.
  4. In the Transaction Path field, specify the location of the generated output files:

    $BASE\loadlib

  5. In the File Path field, specify the location of the AACT files:

    $BASE

  6. In the Map Path field, specify the location for BMS output files:

    $BASE\loadlib

  7. In the Resource Definition File Path field, specify the location of your dfhdrdat resource definition file:

    $BASE\system

  8. Click Apply.

    At this point you have enabled Assembler and CICS support for this enterprise server and specified the appropriate resources and locations of the relevant files.

  9. In Enterprise Developer, close Enterprise Server Administration.
Parent topic: Tutorial: Assembler
Previous topic: Create an Enterprise Server
Next topic: Start the AACT Enterprise Server


Start the AACT Enterprise Server

You must start your enterprise server before you can access your application. You will also view the log from the Enterprise Server Console Daemon to see each module that is loading.

  1. In Server Explorer, expand Local [localhost:86].
  2. Right-click the AACT server, and click Start.
    Note: You might be prompted with an Enterprise Server Sign On dialog box, prompting you to provide connection details for the AACT server. This is a standard security dialog box. Click OK without specifying any sign-on details. Also, if prompted to disable password recovery, click No.
  3. Right-click the AACT server again, and click Show Console Log.

    This displays the messages from the server console log in the Console view. You should see the message MFASM support loaded successfully. This means that Assembler is enabled for your enterprise server.

    In the Server Explorer window, you can see that the icon for the AACT server has changed and indicates that the server has started.

Parent topic: Tutorial: Assembler
Previous topic: Configure the Enterprise Server
Next topic: Run the AACT Transaction


Run the AACT Transaction

Now that the transaction is built, and you have an enterprise server running it, we can test it by connecting to it and interacting with it using a TN3270 emulator. If you installed Micro Focus Rumba with Enterprise Developer, you can use the embedded TN3270 mainframe display from within the IDE:

  1. Click Window > Preferences; then expand Micro Focus > Enterprise Server, and click TN3270.
  2. In the right frame, ensure that Enable display is checked.

    If you installed Rumba as part of your Enterprise Developer installation, this automatically selects Rumba (embedded) and checks all of its corresponding options.

  3. Close the Preferences page.
  4. In Server Explorer, right-click AACT; then select Show TN3270 Display..

    This starts the embedded TN3270 display and automatically connects it to the AACT enterprise server using port 9004 as you configured in the server.

  5. Clear the screen of your TN3270 emulator.
    Note: If you are using Rumba, press Ctrl+Shift+Z to clear the screen.

    If this is your first time running the transaction, you must create an AACTFIL file.

  6. Type CFCR AACTFIL at the prompt on your TN3270 emulator screen, press Enter, then clear the screen. After doing this the first time, you do not need to do it when you run the application again.
  7. Enter AACT. The following shows the initial screen of our transaction:

    AACT Main Menu

    As you can see from this screen, this transaction lets you display, add, delete, print, or modify information in the file. To show how the transaction runs, you'll add a record and then retrieve it.

  8. Tab to the REQUEST TYPE field and type A.
  9. In the ACCOUNT field, type 11111.
  10. Press Enter.
  11. Complete the fields on the NEW RECORD screen as follows. Of the three ADDRESS fields, complete only the first two. Fields not represented here are not mandatory so please skip over them.
    SURNAME | Washington
    FIRST | George
    TITLE | Pres
    TELEPHONE | 8005551212
    ADDRESS | Mt. Vernon Estate
    Mt. Vernon, VA
    NO. CARDS ISSUED | 1
    DATE ISSUED | 070476
    REASON | N
    CARD CODE | 1
    APPROVED BY | ME
  12. Press Enter.
  13. Tab to the REQUEST TYPE field.
  14. Type D to display a record.
  15. In the ACCOUNT field, type 11111.
  16. Press Enter. The following display shows the record retrieved from the file:

    ACCT Record Display

  17. Clear the screen of your TN3270 emulator to return to the main menu, then clear the screen again to exit the transaction.
  18. You can now stop the enterprise server: in Server Explorer, right-click the AACT server, and click Stop.
Parent topic: Tutorial: Assembler
Previous topic: Start the AACT Enterprise Server


Tutorials: CICS

  • Tutorial: CICS
    This tutorial walks you through the process of implementing and running the sample ACCT CICS transaction.
  • Tutorial: Web-enabled CICS Acting as a Web Server
    This tutorial walks you through the process of implementing and running the Web-enabled version of the ACCT sample transaction.
  • Tutorial: Web-enabled CICS Acting as a Web Client
    This tutorial walks you through the process of building and running a version of the sample ACCT CICS transaction that acts as a Web client.
  • Tutorials: CICS Web Services
    These tutorials walk you through the process of using Enterprise Developer and Enterprise Server to generate and run several CICS Web services.
Parent topic: Mainframe Tutorials


Tutorial: CICS

ACCT is a sample CICS 3270 transaction that comprises several COBOL programs and a single BMS map, and uses the resource definitions in the file dfhdrdat. This tutorial walks you through the steps required to implement and test the ACCT transaction.

Prerequisites

To complete this tutorial, you need the following software in addition to Enterprise Developer:

  • Enterprise Developer for Eclipse
  • Micro Focus Rumba 9.5 or later
    Note: Micro Focus Rumba is an installation option when installing Enterprise Developer. If you do not have it installed on your machine, see your systems administrator.
  1. Create a project
  2. Import Sample Application Files
    Import the components of the ACCT sample application into your new project.
  3. Create a Build Configuration
    Create the ACCT build configuration, which defines build settings, preprocessor selection, and path specifications.
  4. Specify Project Properties
    Set COBOL and BMS specifications for the ACCT project.
  5. Create and Start an Enterprise Server Region
    Create the ESACCT enterprise server region, and start the region preparatory to running the ACCT transaction.
  6. Run the ACCT Application
    Run the ACCT transaction in the Rumba TN3270 emulator, add two data records, and display one of the records.
  7. Debug the Application
    Set Enterprise Server options and create a debug configuration in Eclipse; then debug the ACCT transaction from Eclipse.
Parent topic: Tutorials: CICS


Create a project

You create a project that comprises all the parts of your application, for example the COBOL source and BMS files. You build the demonstration application in Enterprise Developer, and deploy and run it on an enterprise server region.

  1. Start Enterprise Developer. If you need instructions, see To start Enterprise Developer.
  2. When prompted, specify c:\tutorials as your workspace location.
  3. In Eclipse, be sure that the Team Developer perspective is the active Eclipse perspective and the Enterprise Developer system is loaded into the Application Explorer view.
  4. From the Application Explorer view, expand the Enterprise Developer system.
  5. Right-click Enterprise Development Projects and select New COBOL Project > Mainframe COBOL Project from the context menu.
  6. Type ACCT into the Project Name field.

    The default location for storing new projects is the workspace you specified when you started Eclipse. If you wanted to change this, you could uncheck Use default location and specify a different location; however, you use the default location in this tutorial.

  7. Click Finish.

    The ACCT project is created and appears in the Application Explorer view. By default, its COBOL dialect is Enterprise COBOL for z/OS and the character set is EBCDIC.

Parent topic: Tutorial: CICS
Next topic: Import Sample Application Files
Related tasks
To start Enterprise Developer


Import Sample Application Files

Import the components of the ACCT sample application into your new project.
  1. In Eclipse, select your project in the Application Explorer view.
  2. Click File > Import.
  3. In the Import dialog box, expand General, select File System, and then click Next.
  4. Click the Browse button that corresponds to the From directory field, and navigate to the demonstration project folder, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\ACCT.
  5. Click OK.
  6. In the left panel, expand the ACCT folder.
  7. Check the boxes next to the following folders:
    • bms
    • cbl
    • cpy
  8. Click Finish.

    This imports all required files into your project, creates the .dll, .idy and .mod files in the loadlib directory, generates a .cpy file from the BMS (this is stored in the cpy folder), and attempts to build the project; however, the build fails because the path to the generated copybook must be included in the project properties.

  9. Right-click the ACCT project name; then select Properties from the context menu.
  10. Expand Micro Focus; then click Build Path.
  11. On the Dependency Paths tab, select COBOL Copybook Paths from the Type drop-down list.
  12. Check ACCT/cpy, which is the path to the imported copybooks.
  13. Click Apply and Close.
    Note: If a Delete User Files prompt appears, click No.

    By default, Eclipse builds the project automatically every time you make a change.

Parent topic: Tutorial: CICS
Previous topic: Create a project
Next topic: Create a Build Configuration


Create a Build Configuration

Create the ACCT build configuration, which defines build settings, preprocessor selection, and path specifications.
  1. In the Application Explorer view, right-click the ACCT project and click Properties.
  2. Expand Micro Focus.
  3. Click Build Configurations and then click Manage Configurations.
  4. Click the pencil icon to rename the current build configuration.
  5. Replace New Configuration with ACCT Build.
  6. Click Finish.
  7. In the Properties window, expand Build Configurations; then click COBOL.
  8. In the Output Path text field, replace New Configuration.bin with loadlib.
  9. Ensure Target Type is set to All Native Library Files.
  10. Click Apply.

    Do not close the Properties window yet.

Parent topic: Tutorial: CICS
Previous topic: Import Sample Application Files
Next topic: Specify Project Properties


Specify Project Properties

Set COBOL and BMS specifications for the ACCT project.
  1. In the Properties window, expand Project Settings under Micro Focus.
  2. Click BMS.
  3. In the right pane, scroll down and locate the DSECT Output Path field.
  4. Type .\cpy into the DSECT Output Path field.
  5. Type .\loadlib into the Binary Output Path field.
  6. Click Apply.
  7. Under Project Settings again, expand COBOL; then select CICS Preprocessor.
  8. In the right pane, check Use CICS Preprocessor.
  9. Click Apply and Close.
Parent topic: Tutorial: CICS
Previous topic: Create a Build Configuration
Next topic: Create and Start an Enterprise Server Region


Create and Start an Enterprise Server Region

Create the ESACCT enterprise server region, and start the region preparatory to running the ACCT transaction.
Create the ESACCT enterprise server region
  1. In Eclipse, open the Server Explorer view.

    If it is hidden, click Window > Show View > Other. Expand Micro Focus, click Server Explorer and then OK.

    You should be see the default directory server connection Local [localhost:86] in the view. If it is not visible, to display it:

    1. Right-click in the Server Explorer view, and click New > Directory Server Connection.
    2. Type localhost in both the Name and the Server address (IP/Hostname) fields.
    3. Leave the port as the default value of 86 and click Finish.
  2. In the Server Explorer view, right-click Local [localhost:86]; then select New > Enterprise Server from the context menu.

    This starts the New Enterprise Server dialog box.

  3. Type ESACCT into the Name field.
  4. Click the Browse button next to the Template field.

    This opens the location of the Enterprise Developer server templates.

  5. Double-click the CICSTemplate XML file to select it.
  6. On the New Enterprise Server dialog box, check ACCT in the Associate with projects field; then click Finish.

    This creates the ESACCT server and adds it under the Local [localhost:86] directory server connection in Server Explorer.

  7. In the Server Explorer view, expand Local [localhost:86] to check that the ESACCT enterprise server region has been added to the list.
Start the ESACCT enterprise server region
  1. On the Server Explorer view, right-click the ESACCT enterprise server region; then select Start from the context menu.
    Note: If you see the Enterprise Server Sign On dialog box, click OK without filling in any details; then click No when prompted to create a master password. Also, allow access for the Micro Focus Communications Process, if you receive a Windows Security Alert.

    The Console view shows that the region has started.

  2. On the Server Explorer view, right-click ESACCT; then select Show Console Log from the context menu.

    The Console view shows the details from the Enterprise Server console log.

Parent topic: Tutorial: CICS
Previous topic: Specify Project Properties
Next topic: Run the ACCT Application


Run the ACCT Application

Run the ACCT transaction in the Rumba TN3270 emulator, add two data records, and display one of the records.

Having created, configured, and started an enterprise server region for the ACCT application, you can now use the Rumba TN3270 mainframe emulator to run it.

Verify Rumba Options
Ensure that Eclipse is configured to use the embedded Rumba emulator to run mainframe applications:
  1. In Eclipse, click Window > Preferences.
  2. Expand Micro Focus > Enterprise Server, and click TN3270.
  3. Ensure that Enable display, Rumba (Embedded) and Connect automatically are all selected.
  4. Click Apply and Close.
Open the Rumba Mainframe Display View
Start the Rumba Mainframe Display view as follows:
  1. In the Server Explorer, right-click ESACCT; then select from the context menu.

    This opens the and connects it to the ACCT application running on the ESACCT enterprise server region.

Initialize the ACCTFIL VSAM File
Before you can run the ACCT transaction, you need to initialize its VSAM file.
  1. In the Rumba Mainframe Display view, press Ctrl+Shift+Z to clear the CESN login screen.
  2. Enter CFCR ACCTFIL.

    If this is the first time you have run a CICS tutorial, you should see a message indicating that the ACCTFIL VSAM file was created successfully. Otherwise, the message explains that the ACCTFIL file already exists.

Start the ACCT transaction
Now you are ready to access the application.
  1. In the Rumba Mainframe Display view, press Ctrl+Shift+Z to clear the VSAM message.
  2. Enter ACCT.

    This invokes the initial screen for the ACCT transaction.

Add two records
  1. Tab to the REQUEST TYPE field and type A.
  2. In the ACCOUNT field, type 11111 .
  3. Press Enter.
  4. Complete the fields on the NEW RECORD screen. As you do this:
    • Of the three ADDRESS fields, complete only the first two.
    • Skip over fields that are not represented in this table.
    • Keep in mind that data presented here is provided for test purposes only. You can substitute any valid data you choose.
    • If you inadvertently lock the application screen, stop and restart the enterprise server region; then start the ACCT transaction again.
    SURNAME | Washington
    FIRST | George
    TITLE | Pres
    TELEPHONE | 7037802000
    ADDRESS Mt. Vernon Estate

    Mt. Vernon, VA 22121

    NO. CARDS ISSUED | 1
    DATE ISSUED | 07 04 76
    REASON | N
    CARD CODE | 1
    APPROVED BY | JF
  5. Press Enter.
  6. Repeat steps 1 and 2, substituting 11112 in the ACCOUNT field.
  7. Repeat steps 3 and 4, substituting the following data:
    SURNAME | Washington
    FIRST | Martha
    TITLE | Mrs
    TELEPHONE | 7037802000
    ADDRESS Mt. Vernon Estate

    Mt. Vernon, VA 22121

    NO. CARDS ISSUED | 1
    DATE ISSUED | 07 04 76
    REASON | N
    CARD CODE | 1
    APPROVED BY | NF
  8. Press Enter to return to the menu.
Display a record
  1. Tab to the REQUEST TYPE field.
  2. Type D to display a record.
  3. In the ACCOUNT field, type 11111.
  4. Press Enter. This displays the record retrieved from the database.
Exit the application
  • Press Ctrl+Shift+Z twice to exit the application.
Parent topic: Tutorial: CICS
Previous topic: Create and Start an Enterprise Server Region
Next topic: Debug the Application


Debug the Application

Set Enterprise Server options and create a debug configuration in Eclipse; then debug the ACCT transaction from Eclipse.
  1. Set Enterprise Server Options
    Set options that turn on some Enterprise Server behaviors automatically such as starting the enterprise server region at runtime, and dynamic debugging.
  2. Create a Debug Configuration
    Create a debug configuration for the ACCT transaction running on the ESACCT enterprise server region.
  3. Debug the ACCT Application
    Run the Enterprise Developer debugger to interact with the ACCT application running on the ESACCT enterprise server region.
Parent topic: Tutorial: CICS
Previous topic: Run the ACCT Application
Related concepts
Running Applications in a Mainframe Display When Debugging


Set Enterprise Server Options

Set options that turn on some Enterprise Server behaviors automatically such as starting the enterprise server region at runtime, and dynamic debugging.
  1. To stop the ESACCT enterprise server region, in Server Explorer, right-click ESACCT on the list of servers, and then click Stop.
  2. From the Eclipse menu, click Window > Preferences, expand Micro Focus, and then click Enterprise Server.

    All options are set to Prompt, which means that Eclipse prompts you before executing the option behavior.

  3. To set these options to execute automatically, change the following options to Always:
    • Automatically start the associated server
    • Automatically restart the server when project output locations change
    • Automatically enable dynamic debugging
  4. Click Save and Apply.
  5. If the Preference Recorder dialog box appears, click OK to record your preferences.
Parent topic: Debug the Application
Next topic: Create a Debug Configuration


Create a Debug Configuration

Create a debug configuration for the ACCT transaction running on the ESACCT enterprise server region.
  1. In Eclipse, click Run > Debug Configurations.
  2. Right-click COBOL Enterprise Server; then select New from the context menu.
  3. In the Name field, type ACCT Debug.
  4. Click Browse next to the COBOL Project field.
  5. Select the ACCT project; then click OK.
  6. In the Debugging type section, on the CICS tab, type ACCT into the Transaction field.
  7. Click Apply.

    Do not close the Debug Configurations dialog box before proceeding to the next topic.

  8. Click Debug to start debugging the application.

    Based on the debug options set previously, this starts the ESACCT server automatically.

    Note:
    • If prompted to confirm a switch to the Debug perspective, click Yes.
    • If you see a Windows Security Alert blocking the Micro Focus Debugger Proxy V2, click Allow access to enable it.
Parent topic: Debug the Application
Previous topic: Set Enterprise Server Options
Next topic: Debug the ACCT Application


Debug the ACCT Application

Run the Enterprise Developer debugger to interact with the ACCT application running on the ESACCT enterprise server region.
  1. If you closed the Rumba Mainframe Display, start it from the Debug view as follows:
    1. Right-click the COBOL Debugger thread.
    2. Click Show Rumba Terminal

    This opens the Rumba Mainframe Display view and loads the CICS application in it.

    Note: If the display does not connect automatically:
    1. Click the New Rumba Mainframe Display button, New Rumba Mainframe Display, in the toolbar of the Rumba Mainframe Display view.
    2. Specify the host name, localhost, and the TN3270 port number, 5239, for the ESACCT server.
    3. Click Connect.

      This connects the Rumba Mainframe Display view to the ESACCT server and loads the CICS application in it.

  2. Press Ctrl+Alt+Z in the Rumba Mainframe Display view to clear the CICS login screen.
  3. Enter ACCT to execute the CICS application.

    In Eclipse, the debugger stops the execution of the process and positions the cursor in the Procedure Division of the ACCT00.cbl file.

  4. Step through the CICS application in the usual manner.
  5. To stop debugging, right-click the session in the Debug pane, and then click Terminate.
  6. To stop the server, right-click ESACCT in Server Explorer, and click Stop.
Parent topic: Debug the Application
Previous topic: Create a Debug Configuration


Tutorial: Web-enabled CICS Acting as a Web Server

This tutorial walks you through the process of implementing and running the Web-enabled version of the ACCT sample transaction.

ACCT is a sample CICS transaction used in Tutorial: CICS to demonstrate accessing a CICS transaction in TN3270 mode. In this tutorial, the sample ACCT transaction code, ACCTWEB, has been modified to Web-enable the SEARCH BY NAME function. This walkthrough takes you through the steps required to implement and test this web-enabled version of ACCT.

The ACCT transaction comprises several COBOL programs and a BMS map, and uses the dfhdrdat resource definition file. In this Web-enabled version, all the components of the transaction are unchanged except for acct01.cbl.

Note: Because the ACCTWEB sample application supports only the SEARCH BY NAME function of ACCT, it is not possible to add or modify individual records from the Web interface.

Prerequisites

To complete this tutorial, you need the following software:

  • Micro Focus Enterprise Developer
  • Micro Focus Rumba TN3270 emulator.
    Note: Rumba is provided as an installation option when you install Enterprise Developer. If Rumba is not installed, see your systems administrator.

In addition, this tutorial requires that you use the Eclipse Team Developer perspective.

  1. Create and Configure a Project
    Create and configure a mainframe-enabled COBOL project for a CICS Web-enabled application.
  2. Create and Configure an Enterprise Server Region
    Create and configure a mainframe-enabled enterprise server region on which to run a CICS Web-enabled application.
  3. Run the ACCTWEB Application in TN3270 Mode
    Run the ACCTWEB application in the Rumba TN3270 terminal display, and add two data records. This sets up the application data such that you can access it from a Web browser later in the tutorial.
  4. Run the ACCTWEB Application in a Web Browser
    Run the ACCTWEB application from a Web browser, and access the data you added while interacting with the application in TN3270 mode.
  5. Debug the Application
    In this step, you debug your CICS Web-enabled application.
Parent topic: Tutorials: CICS


Create and Configure a Project

Create and configure a mainframe-enabled COBOL project for a CICS Web-enabled application.
  1. Create the ACCTWEB Project
    Create the ACCTWEB mainframe-enabled COBOL project for this tutorial.
  2. Import the ACCTWEB Sample Application
    Import the CICS Web-enabled version of the ACCT transaction source files into your ACCTWEB project.
  3. Set Project Properties
    Here, you specify the properties for the ACCTWEB project, which include creation of a build configuration, preprocessor selection, and path specifications.
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Server
Next topic: Create and Configure an Enterprise Server Region


Create the ACCTWEB Project

Create the ACCTWEB mainframe-enabled COBOL project for this tutorial.

To create a project to hold the sample application files:

  1. Start Eclipse using a workspace location of your choice.
  2. In Eclipse, be sure that the Team Developer Perspective is your active perspective.
  3. From the Application Explorer view, right-click Enterprise Development Projects; then select New COBOL Project > Mainframe COBOL Project.

    This starts the New Mainframe COBOL Project wizard.

  4. Type ACCTWEB into the Project Name field.
  5. Click Finish.

    The ACCTWEB project appears in the Application Explorer view. By default, the COBOL dialect is Enterprise COBOL for z/OS and the character set is EBCDIC.

Parent topic: Create and Configure a Project
Next topic: Import the ACCTWEB Sample Application


Import the ACCTWEB Sample Application

Import the CICS Web-enabled version of the ACCT transaction source files into your ACCTWEB project.

To import the ACCTWEB sample application files into your project:

  1. In Eclipse, select your project in the Application Explorer view.
  2. From the main menu, click File > Import.
  3. In the Import dialog box, expand General, click File System and then click Next.
  4. Click the Browse button that corresponds to the From directory field, and then navigate to the ACCTWEB sample files, located by default in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\ACCTWEB directory.
  5. Click OK.
  6. In the left panel, expand the ACCTWEB folder.
  7. Check the boxes next to all of the listed folders, which include:
    • bms
    • cbl
    • cpy
    • data
    • html
    • repos
    • system
  8. Click Finish.

    This imports all required files into your project, creates the .dll, .idy and .mod files in the loadlib directory, generates a .cpy file from the BMS, and builds the project.

    Note: The project build fails at this point because you have not set any project properties. You do this in the next phase of this tutorial.
Parent topic: Create and Configure a Project
Previous topic: Create the ACCTWEB Project
Next topic: Set Project Properties


Set Project Properties

Here, you specify the properties for the ACCTWEB project, which include creation of a build configuration, preprocessor selection, and path specifications.
Open the Project Properties page
  • In the Application Explorer view, right-click the ACCTWEB project; then select Properties.
Create a build configuration
  1. In the left pane, expand Micro Focus.
  2. Click Build Configurations.
  3. In the right pane, click Manage Configurations.
  4. Click the pencil icon to rename the current build configuration.
  5. Replace New Configuration with ACCTWEB Build.
  6. Click Finish.
Specify build paths and targets
  1. In the left pane, expand Build Configurations.
  2. Click the COBOL entry under Build Configurations.
  3. In the right pane, replace the New Configuration.bin value in the Output Path with loadlib.
  4. Ensure Target Type is set to All Native Library Files.
  5. Click Apply.
  6. In the left pane, click Build Path.
  7. In the right pane, click the Dependency Paths tab.
  8. Check ACCTWEB and ACCTWEB/cpy.
Specify the CICS preprocessor
  1. In the left pane, expand Project Settings > COBOL.
  2. Click the CICS Preprocessor entry under COBOL.
  3. In the right pane, check Use CICS Preprocessor.
  4. Click Apply and Close.

At this point, Eclipse automatically rebuilds the project, this time without errors.

Parent topic: Create and Configure a Project
Previous topic: Import the ACCTWEB Sample Application


Create and Configure an Enterprise Server Region

Create and configure a mainframe-enabled enterprise server region on which to run a CICS Web-enabled application.
  1. Create an Enterprise Server Region
    Using the Server Explorer in Eclipse, create the ACCTWEB enterprise server region on which to run the ACCTWEB application.
  2. Configure and Start the ACCTWEB Region
    Configure the newly created enterprise server region to support the ACCTWEB application, and start the region in preparation for running the application.
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Server
Previous topic: Create and Configure a Project
Next topic: Run the ACCTWEB Application in TN3270 Mode


Create an Enterprise Server Region

Using the Server Explorer in Eclipse, create the ACCTWEB enterprise server region on which to run the ACCTWEB application.
  1. In Eclipse, activate the Server Explorer view.
    Note: If Server Explorer view is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type ACCTWEB. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field.
  5. Double-click the CICSTemplate XML file. This populates the Template field.
    Note: If the CICSTemplate XML file is not there initially, browse to the etc\ServerTemplates directory of your Enterprise Developer installation to locate the file.
  6. On the list next to Associate with projects, check ACCTWEB.
  7. Click Finish.

    After refreshing, the Server Explorer shows the ACCTWEB enterprise server region listed under Local [localhost:86].

    Note: If ACCTWEB is not showing, expand Local [localhost:86].
Parent topic: Create and Configure an Enterprise Server Region
Next topic: Configure and Start the ACCTWEB Region


Configure and Start the ACCTWEB Region

Configure the newly created enterprise server region to support the ACCTWEB application, and start the region in preparation for running the application.
Start Enterprise Server Administration
  • From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page. This starts Enterprise Server Administration.
    Note: If a Secure Storage prompt appears, click No.

    On the Home page, you should see the ACCTWEB enterprise server region listed.

Define environment variables
  1. On the Enterprise Server Administration Home page, click the Edit button that corresponds to the ACCTWEB region.
  2. On the Server, Properties, General tab, type the following into the Configuration Information field:
    [ES-Environment]

    This indicates that the information that follows defines environment variables that are specific to the region. Next, you define an environment variable to represent your project directory.

  3. On the next line down, type:
    IDE_PROJECT_LOC=EclipseWorkspacePath\ACCTWEB

    Where EclipseWorkspacePath is the fully qualified path to your Eclipse workspace.

    To use a defined environment variable in the value definition of another environment variable or as the value in other Enterprise Server Administration fields, you precede the name of the variable with a dollar sign ($). You can use the IDE_PROJECT_LOC environment variable to help define the next variable.

  4. On the next line down, type:
    ES_DOCTEMPLATE_PATH=$IDE_PROJECT_LOC\html

    This variable is used in the template definition for the DOCUMENT created in this tutorial: ACCTMP1, defined in the DFHWEB resource group.

    Note: When you create your enterprise server region using the CICS template as you have done in this tutorial, Enterprise Server generates and stores several environment variables based on the information in the associated project. For example, in this region, the IDE_LOADLIB environment variable has been generated and is set to the directory you defined as the output directory in the ACCTWEB Enterprise Developer project. Therefore, IDE_LOADLIB is equal to the loadlib subdirectory of your project directory, or EclipseWorkSpacePath\ACCTWEB\loadlib. The definitions for generated environment variables do not show in the Configuration Information field, however.
  5. Click Apply.
Set the location of your resource definition file
Earlier in this tutorial, you imported the resource definition file, dfhdrdat, as you imported the demonstration application. Now you need to tell the ACCTWEB region where to find that file.
  1. On the Server, Properties, General tab, click the MSS and then CICS tabs.
  2. In the Resource Definition File Path field, type:
    $IDE_PROJECT_LOC\system
  3. Click Apply.
Set the TN3270 listener port
In this tutorial, you use the Rumba TN3270 emulator to access the CICS application. To enable communication with your enterprise server region, you need to set a port number where Enterprise Server listens for TN3270 messages.
  1. From the Server, Properties, General, MSS, CICS tab, click the Listeners tab at the top of the page.
  2. Click the Edit button that corresponds to TN3270.
  3. In the Endpoint Address field, replace the second asterisk (*) with 5239 so that the entry reads *:5239.
  4. Click Apply.
  5. To return to the Enterprise Server Administration Home page, click Home at the top of the menu ribbon.
Start the ACCTWEB region
  • Back on the Server Explorer view in Eclipse, right-click ACCTWEB; then select Start.

    When the region is up and running, both the Server Explorer view and the entry in Enterprise Server Administration show that it is in started mode.

Parent topic: Create and Configure an Enterprise Server Region
Previous topic: Create an Enterprise Server Region


Run the ACCTWEB Application in TN3270 Mode

Run the ACCTWEB application in the Rumba TN3270 terminal display, and add two data records. This sets up the application data such that you can access it from a Web browser later in the tutorial.

The ACCTWEB Web interface supports data search by the Surname field only. You need to interact with the application in TN3270 mode to add data records. Later in this tutorial, you can do a data search from the Web interface to display the records you add here.

Verify Rumba Options
Ensure that Eclipse is configured to use the embedded Rumba emulator to run mainframe applications:
  1. In Eclipse, click Window > Preferences.
  2. Expand Micro Focus > Enterprise Server, and click TN3270.
  3. Ensure that Enable display, Rumba (Embedded) and Connect automatically are all selected.
  4. Click Apply and Close.
Open the Rumba Mainframe Display View
With the enterprise server region started, you can now run the ACCT transaction and interact with it via the Rumba TN3270 display. To start Rumba:
  • On the Server Explorer view, right-click the ACCTWEB enterprise server region; then select Show TN3270 Display from the context menu.

    This starts the Rumba Mainframe Display view and connects it to the ACCTWEB application running on the ACCTWEB enterprise server region.

Initialize the ACCTFIL VSAM File
Before you can run the ACCT transaction, you need to initialize its VSAM file.
  1. In the Rumba Mainframe Display view, press Ctrl+Shift+Z to clear the CESN login screen.
  2. Enter CFCR ACCTFIL.

    If this is the first time you have run a CICS tutorial, you should see a message indicating that the ACCTFIL VSAM file was created successfully. Otherwise, the message explains that the ACCTFIL file already exists.

Start the ACCT transaction
Now you are ready to access the application.
  1. In the Rumba Mainframe Display view, press Ctrl+Shift+Z to clear the VSAM message.
  2. Enter ACCT.

    This invokes the initial screen for the ACCT transaction.

Add two records
  1. Tab to the REQUEST TYPE field and type A.
  2. In the ACCOUNT field, type 11111 .
  3. Press Enter.
  4. Complete the fields on the NEW RECORD screen. As you do this:
    • Of the three ADDRESS fields, complete only the first two.
    • Skip over fields that are not represented in this table.
    • Keep in mind that data presented here is provided for test purposes only. You can substitute any valid data you choose.
    • If you inadvertently lock the application screen, stop and restart the enterprise server region; then start the ACCT transaction again.
    SURNAME | Washington
    FIRST | George
    TITLE | Pres
    TELEPHONE | 7037802000
    ADDRESS Mt. Vernon Estate

    Mt. Vernon, VA 22121

    NO. CARDS ISSUED | 1
    DATE ISSUED | 07 04 76
    REASON | N
    CARD CODE | 1
    APPROVED BY | JF
  5. Press Enter.
  6. Repeat steps 1 and 2, substituting 11112 in the ACCOUNT field.
  7. Repeat steps 3 and 4, substituting the following data:
    SURNAME | Washington
    FIRST | Martha
    TITLE | Mrs
    TELEPHONE | 7037802000
    ADDRESS Mt. Vernon Estate

    Mt. Vernon, VA 22121

    NO. CARDS ISSUED | 1
    DATE ISSUED | 07 04 76
    REASON | N
    CARD CODE | 1
    APPROVED BY | NF
  8. Press Enter to return to the menu.
Exit the application
  • Press Ctrl+Shift+Z to exit the application.
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Server
Previous topic: Create and Configure an Enterprise Server Region
Next topic: Run the ACCTWEB Application in a Web Browser


Run the ACCTWEB Application in a Web Browser

Run the ACCTWEB application from a Web browser, and access the data you added while interacting with the application in TN3270 mode.

Now that you have added data, you can access it by running the application from a Web browser.

  1. Open a browser and enter the following URL: http://localhost:55220/ACCTWEB. The name ACCTWEB is case sensitive. This takes you to the ACCTWEB page.
  2. In the Surname field, type the first letter of a surname for a record you added. For example, if you used the supplied test data, type W (upper case).
  3. Click Submit. You should see all records you added that have a surname starting with the letter you submitted. If you used the supplied test data, you should see both Washington records.
  4. Close the browser.
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Server
Previous topic: Run the ACCTWEB Application in TN3270 Mode
Next topic: Debug the Application


Debug the Application

You can start debugging a CICS application by using the Enterprise Server Dynamic Debugging facility, which enables you to debug a service on a local or remote enterprise server.

Note: When you have finished debugging, you must stop the debugger before you stop the enterprise server. This stops all the active transactions and ensures the enterprise server stops cleanly.
  1. Create a Debug Configuration for Your Project
  2. Debug ACCTWEB
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Server
Previous topic: Run the ACCTWEB Application in a Web Browser


Create a Debug Configuration for Your Project

  1. Click Run > Debug Configurations.
  2. Right-click COBOL Enterprise Server and click New.
  3. Specify ACCTWEB Debug in the Name field.
  4. Click the General tab.
  5. Click Browse next to the COBOL Project field.
  6. Select the ACCTWEB project and click OK.
  7. In the Debugging type section, click the CICS tab.
  8. Type ACCTWEB in the Link-level program text box.

    This configures the IDE to debug the Web server program.

  9. Click Apply.

    Do not close the Debug Configurations dialog box before proceeding to the next topic.

Parent topic: Debug the Application
Next topic: Debug ACCTWEB


Debug ACCTWEB

  1. On the Debug Configurations dialog box, click Debug.
  2. Click Yes when prompted to switch to the Debug perspective.
  3. Enter the following URL into a browser: http://localhost:9003/ACCTWEB, to run the ACCTWEB application.
  4. In Eclipse, step through the CICS application in the usual manner.
  5. To stop debugging, right-click the session in the Debug pane and then click Terminate.
  6. To stop the server, switch back to the Team Developer perspective; then right-click ACCTWEB in Server Explorer and click Stop.
Parent topic: Debug the Application
Previous topic: Create a Debug Configuration for Your Project
Related reference
Running Applications in a Mainframe Display When Debugging


Tutorial: Web-enabled CICS Acting as a Web Client

This tutorial uses a modified and extended version of the ACCT demonstration application.

In this version, it uses the CICS Web client APIs to act as a Web client, and converses with a Web server to submit and retrieve account information. For this reason, a server program is also included that acts as the back end for the demonstration application.

Prerequisites

To complete this tutorial, you need the following software:

  • Micro Focus Enterprise Developer
  • Micro Focus Rumba TN3270 emulator.
    Note: Rumba is provided as an installation option when you install Enterprise Developer. If Rumba is not installed, see your systems administrator.

In addition, this tutorial requires that you use the Eclipse Team Developer perspective.

  1. Create and Configure a Project
    Create and configure a mainframe-enabled COBOL project for a CICS client for a CICS Web-enabled application.
  2. Create and Configure an Enterprise Server Region
    Create and configure a mainframe-enabled enterprise server region on which to run a CICS client for a Web-enabled application.
  3. Run the ACCTCLNT Application
    Run the ACCTCLNT application in the Rumba TN3270 terminal display, and add two data records.
  4. Debug the Application
    In this step, you debug your CICS Web-enabled application.
Parent topic: Tutorials: CICS


Create and Configure a Project

  1. Create the ACCTCLNT Project
    Create the ACCTCLNT mainframe-enabled COBOL project for this tutorial.
  2. Import the ACCTCLNT Sample Application
    Import the CICS Web-enabled version of the ACCT transaction source files into your ACCTCLNT project.
  3. Set Project Properties
    Here, you specify the properties for the ACCTCLNT project, which include creation of a build configuration, preprocessor selection, and path specifications.
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Client
Next topic: Create and Configure an Enterprise Server Region


Create the ACCTCLNT Project

Create the ACCTCLNT mainframe-enabled COBOL project for this tutorial.

To create a project to hold the sample application files:

  1. Start Eclipse using a workspace location of your choice.
  2. In Eclipse, be sure that the Team Developer Perspective is your active Eclipse perspective; then right-click Enterprise Development Projects in the Application Explorer view and select New COBOL Project > Mainframe COBOL Project.

    This starts the New Mainframe COBOL Project wizard.

  3. Type ACCTCLNT into the Project Name field.
  4. Click Finish.

    The ACCTCLNT project appears in the Application Explorer view. By default, its COBOL dialect is Enterprise COBOL for z/OS and the character set is EBCDIC.

Parent topic: Create and Configure a Project
Next topic: Import the ACCTCLNT Sample Application


Import the ACCTCLNT Sample Application

Import the CICS Web-enabled version of the ACCT transaction source files into your ACCTCLNT project.

To import the ACCTCLIENT sample application files into your project:

  1. In Eclipse, select your project in the Application Explorer view.
  2. Click File > Import on the main menu.
  3. In the Import dialog box, expand General, click File System and then click Next.
  4. Click Browse, and then navigate to the ACCTCLNT sample files, located by default in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\ACCTCLNT directory.
  5. Click OK.
  6. In the left panel, expand the ACCTCLNT folder.
  7. Check the boxes next to all of the listed folders, which include:
    • bms
    • cbl
    • cpy
    • data
    • html
    • repos
    • system
  8. Click Finish.

    This imports all required files into your project, creates the .dll, .idy and .mod files in the loadlib directory, generates a .cpy file from the BMS, and builds the project.

    Note: The project build fails at this point because you have not set any project properties. You do this in the next phase of this tutorial.
Parent topic: Create and Configure a Project
Previous topic: Create the ACCTCLNT Project
Next topic: Set Project Properties


Set Project Properties

Here, you specify the properties for the ACCTCLNT project, which include creation of a build configuration, preprocessor selection, and path specifications.
Open the Project Properties page
  • In the Application Explorer view, right-click the ACCTCLNT project; then select Properties.
Create a build configuration
  1. In the left pane, expand Micro Focus.
  2. Click Build Configurations.
  3. In the right pane, click Manage Configurations.
  4. Click the pencil icon to rename the current build configuration.
  5. Replace New Configuration with ACCTCLNT Build.
  6. Click Finish.
Specify build paths and targets
  1. In the left pane, expand Build Configurations.
  2. Click the COBOL entry under Build Configurations.
  3. In the right pane, replace the New Configuration.bin value in the Output Path with loadlib.
  4. Ensure Target Type is set to All Native Library Files.
  5. Click Apply.
  6. In the left pane, click Build Path.
  7. In the right pane, click the Dependency Paths tab.
  8. Check ACCTCLNT and ACCTCLNT/cpy.
Specify Project Settings
  1. In the left pane, expand Project Settings > COBOL.
  2. Click the CICS Preprocessor entry under COBOL.
  3. In the right pane, check Use CICS Preprocessor.
  4. Click Apply.
  5. In the left pane, click the BMS entry under Project Settings.
  6. Scroll down to the Outputs section.
  7. Type cpy into the DSECT Output text field.
  8. Type loadlib into the Binary Output text field.
  9. Click Apply and Close.

At this point, Eclipse automatically rebuilds the project, this time without errors.

Parent topic: Create and Configure a Project
Previous topic: Import the ACCTCLNT Sample Application


Create and Configure an Enterprise Server Region

Create and configure a mainframe-enabled enterprise server region on which to run a CICS client for a Web-enabled application.
  • Create an Enterprise Server Region
    Use the Server Explorer in Enterprise Developer to create an enterprise server region on which to run the application.
  • Configure the ACCTCLNT Region
    Now that you have created an enterprise server region for the CICS application, you need to start Enterprise Server Administration, define environment variables, start the region, and add resources.
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Client
Previous topic: Create and Configure a Project
Next topic: Run the ACCTCLNT Application


Create an Enterprise Server Region

Use the Server Explorer in Enterprise Developer to create an enterprise server region on which to run the application.
  1. From Enterprise Developer, activate the Server Explorer.
    Note: If Server Explorer is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type ACCTCLNT. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field.
  5. Double-click the CICSTemplate XML file. This populates the Template field.
    Note: If the CICSTemplate XML file is not there initially, browse to the etc\ServerTemplates directory of your Enterprise Developer installation to locate the file.
  6. On the list next to Associate with projects, check ACCTCLNT.
  7. Click Finish.

    After refreshing, the Server Explorer shows the ACCTCLNT enterprise server region listed under Local [localhost:86].

    Note: If ACCTCLNT is not showing, expand Local [localhost:86].
Parent topic: Create and Configure an Enterprise Server Region


Configure the ACCTCLNT Region

Now that you have created an enterprise server region for the CICS application, you need to start Enterprise Server Administration, define environment variables, start the region, and add resources.
Start Enterprise Server Administration
  • From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page. This starts Enterprise Server Administration.
    Note: If a Secure Storage prompt appears, click No.

    On the Home page, you should see the ACCTCLNT enterprise server region listed.

Define environment variables
  1. On the Enterprise Server Administration Home page, click the Edit button that corresponds to the ACCTCLNT region.
  2. On the Server, Properties, General tab, type the following into the Configuration Information field:
    [ES-Environment]

    This indicates that the information that follows defines environment variables that are specific to the region. Next, you define an environment variable to represent your project directory.

  3. On the next line down, type:
    IDE_PROJECT_LOC=IDE_PROJECT_LOC=EclipseWorkspacePath\ACCTCLNT

    Where EclipseWorkspacePath is the fully qualified path to your Eclipse workspace.

    To use a defined environment variable in the value definition of another environment variable or as the value in other Enterprise Server Administration fields, you precede the name of the variable with a dollar sign ($). You can use the IDE_PROJECT_LOC environment variable to help define the next variable.

  4. On the next line down, type:
    ES_DOCTEMPLATE_PATH=$IDE_PROJECT_LOC\html

    This variable is used in the template definition for the DOCUMENT created in this tutorial: ACCTMP1, defined in the DFHWEB resource group.

    Note: When you create your enterprise server region using the CICS template as you have done in this tutorial, Enterprise Server generates and stores several environment variables based on the information in the associated project. For example, in this region, the IDE_LOADLIB environment variable has been generated and is set to the directory you defined as the output directory in the ACCTCLNT Enterprise Developer project. Therefore, IDE_LOADLIB is equal to the loadlib subdirectory of your project directory, or EclipseWorkSpacePath\ACCTCLNT\loadlib. The definitions for generated environment variables do not show in the Configuration Information field, however.
  5. Click Apply.
Set the location of your resource definition file
Earlier in this tutorial, you copied the resource definition file, dfhdrdat, from the Enterprise Developer installation area to your project area. Now you need to tell the ACCTCLNT region where to find that file.
  1. On the Server, Properties, General tab, click the MSS and then CICS tabs.
  2. In the Resource Definition File Path field, type:
    $IDE_PROJECT_LOC\system
  3. Click Apply.
Set the TN3270 listener port
In this tutorial, you use the Rumba TN3270 emulator to access the CICS application. To enable communication with your enterprise server region, you need to set a port number where Enterprise Server listens for TN3270 messages.
  1. From the Server, Properties, General, MSS, CICS tab, click the Listeners tab at the top of the page.
  2. Click the Edit button that corresponds to TN3270.
  3. In the Endpoint Address field, replace the second asterisk (*) with 5239 so that the entry reads *:5239.
  4. Click Apply.
Parent topic: Create and Configure an Enterprise Server Region


Run the ACCTCLNT Application

Verify Rumba Options
Ensure that Eclipse is configured to use the embedded Rumba emulator to run mainframe applications:
  1. In Eclipse, click Window > Preferences.
  2. Expand Micro Focus > Enterprise Server, and click TN3270.
  3. Ensure that Enable display, Rumba (Embedded) and Connect automatically are all selected.
  4. Click Apply and Close.
Open the Rumba Mainframe Display View
With the enterprise server region started, you can now run the ACCT transaction and interact with it via the Rumba TN3270 display. To start Rumba:
  • On the Server Explorer view, right-click the ACCTWEB enterprise server region; then select Show TN3270 Display from the context menu.

    This starts the Rumba Mainframe Display view and connects it to the ACCTWEB application running on the ACCTWEB enterprise server region.

Initialize the ACCTFIL VSAM File
Before you can run the ACCT transaction, you need to initialize its VSAM file.
  1. In the Rumba Mainframe Display view, press Ctrl+Shift+Z to clear the CESN login screen.
  2. Enter CFCR ACCTFIL.

    If this is the first time you have run a CICS tutorial, you should see a message indicating that the ACCTFIL VSAM file was created successfully. Otherwise, the message explains that the ACCTFIL file already exists.

Start the ACCT transaction
Now you are ready to access the application.
  1. In the Rumba Mainframe Display view, press Ctrl+Shift+Z to clear the VSAM message.
  2. Enter ACCT.

    This invokes the initial screen for the ACCT transaction.

Add two records
  1. Tab to the REQUEST TYPE field and type A.
  2. In the ACCOUNT field, type 11111 .
  3. Press Enter.
  4. Complete the fields on the NEW RECORD screen. As you do this:
    • Of the three ADDRESS fields, complete only the first two.
    • Skip over fields that are not represented in this table.
    • Keep in mind that data presented here is provided for test purposes only. You can substitute any valid data you choose.
    • If you inadvertently lock the application screen, stop and restart the enterprise server region; then start the ACCT transaction again.
    SURNAME | Washington
    FIRST | George
    TITLE | Pres
    TELEPHONE | 7037802000
    ADDRESS Mt. Vernon Estate

    Mt. Vernon, VA 22121

    NO. CARDS ISSUED | 1
    DATE ISSUED | 07 04 76
    REASON | N
    CARD CODE | 1
    APPROVED BY | JF
  5. Press Enter.
  6. Repeat steps 1 and 2, substituting 11112 in the ACCOUNT field.
  7. Repeat steps 3 and 4, substituting the following data:
    SURNAME | Washington
    FIRST | Martha
    TITLE | Mrs
    TELEPHONE | 7037802000
    ADDRESS Mt. Vernon Estate

    Mt. Vernon, VA 22121

    NO. CARDS ISSUED | 1
    DATE ISSUED | 07 04 76
    REASON | N
    CARD CODE | 1
    APPROVED BY | NF
  8. Press Enter to return to the menu.
Exit the application
  • Press Ctrl+Shift+Z to exit the application.
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Client
Previous topic: Create and Configure an Enterprise Server Region
Next topic: Debug the Application


Debug the Application

You can start debugging a CICS application by using the Enterprise Server Dynamic Debugging facility, which enables you to debug a service on a local or remote enterprise server.

Note: When you have finished debugging, you must stop the debugger before you stop the enterprise server. This stops all the active transactions and ensures the enterprise server stops cleanly.
  1. Create a Debug Configuration for Your Project
  2. Debug ACCTCLNT
Parent topic: Tutorial: Web-enabled CICS Acting as a Web Client
Previous topic: Run the ACCTCLNT Application


Create a Debug Configuration for Your Project

  1. Click Run > Debug Configurations.
  2. Right-click COBOL Enterprise Server and click New.
  3. Specify ACCTCLNT Debug in the Name field.
  4. Click Browse next to the COBOL Project field.
  5. Select the ACCTCLNT project and click OK.
  6. Enter ACCTCLNT into the Link-level program text box.
  7. Click Apply.

    Do not close the Debug Configurations dialog box before proceeding to the next topic.

Parent topic: Debug the Application
Next topic: Debug ACCTCLNT


Debug ACCTCLNT

  1. On the Debug Configurations dialog box, click Debug.
  2. Click Yes when prompted to switch to the Debug perspective.
  3. In Rumba, run the ACCT transaction.
  4. On the ACCOUNT FILE: MENU screen, enter the first letter of a surname for a record you added into the Surname field. For example, if you used the supplied test data, type W (upper case).
  5. Step through the application in the usual manner.

    When you have stepped through the appropriate code, a list of records that start with W appears on the screen.

  6. To stop debugging, right-click the session in the Debug pane and then click Terminate.
  7. To stop the server, switch back to the Team Developer perspective; then right-click ACCTCLNT in Server Explorer and click Stop.
Parent topic: Debug the Application
Previous topic: Create a Debug Configuration for Your Project
Related reference
Running Applications in a Mainframe Display When Debugging


Tutorials: CICS Web Services

These tutorials walk you through the process of using Enterprise Developer and Enterprise Server to generate and run several CICS Web services.
Restriction: This topic applies to Windows environments only.

Prerequisite

Before attempting these CICS Web Services tutorials, you must first install the IBM-37, IBM-437, and 002501B5 CCSID tables. See To install CCSID tables for instructions.

  • Demonstration Applications
    Describes the sample projects provided for the CICS Web Services tutorials.
  • Tutorial: CICS Web Service Provider from WSDL, Top-down Method
    Walks you through the steps required to create a new CICS Web service provider application starting with an existing WSDL file. The resulting Web service uses the SOAP protocol.
  • Tutorial: CICS Web Service Requester from WSDL, Top-down Method
    Walks you through the steps required to create a new CICS Web service requester (client) application from an existing WSDL file. The resulting Web service uses the SOAP protocol.
  • Tutorial: CICS Web Service Provider from WSDL, Bottom-up Method
    Walks you through the steps required to expose an existing CICS COBOL application as a Web service described by WSDL. The resulting Web service uses the SOAP protocol.
  • Tutorial: CICS Web Service Provider from JSON, Request-Response Top-down Method
    Walks you through the steps required to create a new CICS Web service provider application from a set of request and response JSON files.
  • Tutorial: CICS Web Service Requester from JSON, Linkable Interface Top-down Method
    Walks you through the steps required to create a new CICS Web service requester application as a linkable interface.
  • Tutorial: CICS Web Service Provider from JSON, Request-Response Bottom-up Method
    Walks you through the steps required to expose an existing CICS COBOL application as a Web service described by a set of request and response JSON files.
  • Tutorial: CICS Web Service Provider from JSON, RESTful
    Walks you through the steps required to create a new CICS RESTful Web service provider application from a JSON schema file.
Parent topic: Tutorials: CICS
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Demonstration Applications

Restriction: This topic applies to Windows environments only.

Enterprise Developer provides several sample projects that contain the components required to complete the CICS Web Services tutorials for both WSDL and JSON. Components of the Reverse, InvokeReverse, LoanDemo, ReverseJSON, LoanDemoJSON, and filmsREST applications are provided for these tutorials.

Reverse Application
The Reverse application is a CICS COBOL application that takes one or more character strings as input, reverses each of them, and sends the reversed strings as output.
InvokeReverse Application
The InvokeReverse application is generated from an existing WSDL file. With it, you invoke the Reverse application running in an enterprise server region.
ReverseJSON Application
The ReverseJSON application is a CICS COBOL application that takes a character string as input, reverses it, and sends the reversed string as output.
LoanDemo and LoanDemoJSON Applications
LoanDemo consist of a CICS application, LOANPAYM, that simply accepts a Principal amount, a Loan Term amount, and a Rate amount. These three input values are required to calculate and return a Monthly Payment amount.
filmsREST
The filmsREST application is a CICS COBOL application that stores and retrieves film records, which include the title, year released, director, and media format for each film.

Demonstration Files

The demonstration files for WSDL tutorials are provided by means of a project template named CICSWebServicesProjectTemplate_Eclipse. This template is located in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS directory by default.

The demonstration files for JSON tutorials are provided by sample projects that are also used by the Samples Browser. They also reside in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS directory by default.

Each provided project contains several folders and files required to complete the tutorials; however not all of the files are used in every tutorial:

.cobolBuild, .cobolProj, and .project
Eclipse template files used to create each tutorial project.
RESTLogic.cpy
A copybook that contains the logic required to create a RESTful Web service provider.
LOANPAYM.cbl
A CICS COBOL program used to create a CICS Web service provider using the bottom-up method.
LOANINP.cpy
A copybook that contains the input structure for the LOANPAYM program.
LOANOUT.cpy
A copybook that contains the output structure for the LOANPAYM program.
revLogic.cpy
For WSDL tutorials, a copybook that contains the business logic for the generated Web service.
revLogicJ.cpy
For JSON tutorials, a copybook that contains the business logic for the generated JSON Web service.
CICSWebServicesProjectTemplate.xml
An Enterprise Server template used to create an enterprise server region on which to run CICS Web services.
films.json
A JavaScript Object Notation (JSON) file that describes a RESTful CICS Web service.
reverse.json
A JavaScript Object Notation file that describes both the input and the output structures for a CICS Web Service.
loadlib
As you work through the tutorials, you create this folder to contain files generated by Enterprise Developer. Initially, it does not appear listed on the project.
dfhdrdat
A resource definition file that defines the resources required to run the Web service on Enterprise Server.
reverse.wsdl
A Web Service Description Language (WSDL) file that describes a CICS Web service.
basicsoap11provider.xml
A basic SOAP configuration file used for the provider pipeline.
basicsoap11requester.xml
A basic SOAP configuration file used for the requester pipeline.
JSONConfig.xml
A basic JSON configuration file used for the provider pipeline.

Project Configuration

Projects created using the provided template and sample projects are configured to use the following settings. All other settings remain set to their respective defaults:

Output path
This is set to write generated files to the loadlib project folder.
Build path
Includes the cpy project subfolder, ensuring that the compiler finds all included copybooks.
Preprocessor
Set to build the project using the CICS preprocessor.
Character set
Set to use the ASCII character set.
Dialect
Set to use the Micro Focus COBOL dialect.
Mode
Sets the mode to word-storage by setting the IBMCOMP compiler directive.
Parent topic: Tutorials: CICS Web Services


Tutorial: CICS Web Service Provider from WSDL, Top-down Method

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the top-down method to create a Web service provider that sends one or more character strings in the form of a SOAP request to a generated CICS application. The application reads and then reverses each string, and sends the reversed strings back to the Web service as a SOAP response message.

To use the top-down method, you supply a WSDL file that describes the CICS application you want to access. The project template used in this tutorial to create your Enterprise Developer project contains the reverse.wsdl file for this purpose.

Prerequisites

If you have not done so already, you must install the IBM-37, IBM-437, and 002501B5 CCSID tables before attempting this tutorial. See To install CCSID tables for instructions.

To complete the Test the Reverse Web service provider section of this tutorial, we recommend that you download and install the SoapUI Open Source testing tool, available from here.

This tutorial assumes that your Enterprise Developer project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Create the Reverse project

Use the CICSWebServicesProjectTemplate template project to create a project for your CICS Web service provider.

  1. Extract the CICSWebServicesProjectTemplate_Eclipse.zip file, located in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS directory by default, to a temporary directory.
  2. In Eclipse, start the COBOL Explorer.
  3. From the Enterprise Developer main menu, click File > New > Mainframe COBOL Project.
    Note: If Mainframe COBOL Project is not listed:
    1. Select Other.
    2. Expand Micro Focus COBOL.
    3. Select Mainframe COBOL Project; then click Next.
  4. In the Project name field, type Reverse.
  5. Check Browse for template.
  6. Click the Browse button that corresponds to the Location field, and browse to the location where you extracted the CICSWebServicesProjectTemplate_Eclipse.zip file.
  7. Select CICSWebServicesProjectTemplate template folder; then click OK.
  8. Check Use default location; then click Finish.

    The COBOL Explorer now shows the Reverse project, which is created in a Reverse subdirectory of your current Eclipse workspace, and is built automatically.

Generate CICS Web Service provider components

Use the New CICS Web Service wizard to generate the components of your Web service provider.

  1. From the COBOL Explorer, click the Reverse project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed:
    1. Select Other.
    2. Expand Micro Focus Service Interface.
    3. Select CICS Web Service; then click Next.
  3. From the Service type drop-down list, select CICS Web Service Provider (Top-Down); then click Next.

    The Project field should already show the Reverse project name.

  4. Click the Browse button that corresponds to the Service definition field, and browse to the reverse.wsdl file located in the wsdl project folder.
  5. Double-click reverse.wsdl. This populates the Service definition field.
  6. In the Program name field, type reverse, which is the program name for the generated COBOL skeleton program.

    You need to provide a URI that Enterprise Server can use to identify and locate the appropriate Web service upon receiving a request or a response. This information goes into the Service location field.

  7. In the Service location field, type /cwsDemo/reverseMe.

    The Request file prefix and Response file prefix fields are completed for you by default. These are the names of the generated copybooks that support the generated skeleton program file, one for request data structures, and one for response data structures.

    The Program interface field enables you to specify the generation of either a COMMAREA or a CHANNEL interface in the skeleton program. In this tutorial, you want to generate a CHANNEL interface.

  8. From the Program interface drop-down list, select CHANNEL. This activates the Container name field.

    The default container name is DFHWS-DATA, which is the top-level container used in service provider applications for CICS Web services.

  9. Click Finish.

Enterprise Developer generates the following CICS Web service components:

COBOL Programs\reverse.cbl
A skeleton CICS program.
Copybooks\REQ01.cpy
A copybook containing the COBOL data structures required to send a SOAP request as input.
Copybooks\RESP01.cpy
A copybook containing the COBOL data structures required to receive a SOAP response message as output.
loadlib\reverse.wsbind
A bind file that maps the SOAP request to the data structure in REQ01.cpy, and maps the data structure in RESP01.cpy to the SOAP response message.

Implement the service

The generated skeleton program, reverse.cbl, contains some basic functionality that is common to any CICS Web service that uses the Channel interface, such as:

  • It checks the operation name by retrieving the content of the DFHWS-OPERATION container.
  • If the returned operation name matches the name expected by the program (in this case, reverserequest), the program:
    • Populates the request data structure (in REQ01.cpy) with the content of the DFHWS-DATA container.
    • Populates the DFHWS-DATA container with the content of the response data structure (in RESP01.cpy).

To provide the required operation logic, you must code it manually by editing the program.

  1. From the COBOL Explorer, double-click reverse.cbl to open it in the COBOL editor.
  2. Declare the following two variables in the Working-Storage section:
    01 ws-string-len               pic x(4) comp-5.
01 ws-reversedString-len       pic x(4) comp-5.
  3. Scroll to the bottom of the program and add the following COPY statement after the last exit program. statement:
    copy 'revLogic.cpy'.
  4. Scroll up to the WS-OP-1 paragraph, and add the following PERFORM statement between the EXEC CICS GET and the EXEC CICS PUT statements:
    Perform reverse-logic
    Note: reverse.cbl contains two comment lines between the two EXEC CICS statements. You can place your PERFORM statement between the comment lines.
  5. Click File > Save.
  6. Close the COBOL editor.

    Eclipse automatically builds the project to include your changes.

Create an enterprise server region

Here you use the Server Explorer in Enterprise Developer to create an enterprise server region on which to run the Web service.

  1. From Enterprise Developer, activate the Server Explorer.
    Note: If Server Explorer is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type CWSPROV. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesProjectTemplate.xml file located in the ESTemplates project folder.
  5. Double-click CICSWebServicesProjectTemplate.xml. This populates the Template field.
  6. On the list next to Associate with projects, check Reverse.
  7. Click Finish.

    The Server Explorer should now show the CWSPROV enterprise server region listed under Local [localhost:86].

    Note: If CWSPROV is not showing, expand Local [localhost:86].

Configure CWSPROV resources

All enterprise server regions require access to certain resources, depending on the types of applications they run. Resources that are defined on a region's startup list are loaded during the startup routine, making them available for as long as the region is running.

CICS Web services use the underlying resources provided by the standard Enterprise Server CICS Web interface (CWI) and CICS Web Services (CWS) support. However, the CICSWebServicesProjectTemplate used to create the CWSPROV region does not include these resources on the startup list; therefore, you need to add them manually. The CWI resources reside in a predefined resource group named DFHWEB. The CWS resources are in the predefined DFHPIPE group.

In addition, you need to create and define a resource group, MYCWSPRV, to contain the resources required by the Reverse program.

Start Enterprise Server Administration
  1. From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page. This starts Enterprise Server Administration.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box. If a Secure Storage prompt appears, click No.

    On the Home page, you should see the CWSPROV enterprise server region listed.

  2. Back on the Server Explorer, right-click CWSPROV ; then select Start.

    As the region is starting, the Enterprise Server Administration Home page should show log information in the region's Status Log column. When the region is fully started, this is indicated in the region's Status column.

Start ES Monitor and Control (ESMAC)
  1. After CWSPROV has started, on the Administration Home page, click the Details button located in the Status column for the CWSPROV region.
  2. On the Server > Control page, click ES Monitor & Control. This starts the ESMAC utility where you can edit the startup list.
Open the DEMOSTRT startup list
  1. On the ESMAC menu, click the drop-down list located under Resources; then select by Group.
  2. Click Startup. This invokes a list of CICS Startup Lists in the right pane.

    The CWSPROV region uses the default startup list, named DEMOSTRT.

  3. Click the Details button that corresponds to DEMOSTRT. This takes you to the CICS STARTUP - DEMOSTRT page.
Add resource groups
Here, you add the DFHWEB and DFHPIPE resource groups to the startup list, and add the MYCWSPRV resource group name to the startup list. At this point, you have neither created nor defined the MYCWSPRV group and its respective resources. Those tasks are completed in the next few sections of this tutorial.
  1. On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type DFHWEB into the empty field at the bottom; then click Apply. ESMAC adds the DFHWEB group, and adds another empty field at the end of the list.
  2. In the new empty field, type DFHPIPE; then click Apply.
  3. In the new empty field, type MYCWSPRV; then click Apply.
Create the MYCWSPRV resource group
  1. On the ESMAC menu, click the Groups button located under Resources.
  2. On the CICS Resource Groups page, click New.
  3. In the Name field, type MYCWSPRV.
  4. In the Description field, type CICS Web Services Provider Resources; then click Add. This invokes the CICS Group MYCWSPRV page where you can create and define resources for the group.
Define MYCWSPRV resources
The Reverse program requires a resource for TCP/IP service, and a resource to support a pipeline.
  1. On the CICS Group MYCWSPRV page, click TCPIPSv.
  2. Complete these fields:
    Name | CWSTCPIP
    Description | My TCP/IP Service
    Port No | 5482
  3. Click Add. Enterprise Server returns Add successful.
  4. Click Apply. Enterprise Server returns Update successful.
  5. Click Group List to return to the CICS Group MYCWSPRV page.
  6. Click Pipeline.
  7. Complete these fields:
    Name | PROVPIPE
    Description | My CICS Provider Pipeline
    Resp Wait | DEFT | This is the number of seconds that an application waits for a response from the service. DEFT indicates the default value, which is 10 seconds for HTTP and 60 seconds for MQ.
    Config file | $IDE_XML_LOC\basicsoap11provider.xml | The IDE_XML_LOC environment variable in CWSPROV points to the xml project folder.1
    WebSvc Dir | $IDE_LOADLIB\ | The IDE_LOADLIB environment variable points to the loadlib project folder.2

    1 To see a list of environment variables defined for CWSPROV , from the Administration Home page, click the Edit button that corresponds to the CWSPROV region. The list appears in the Configuration Information field on the Server > Properties > General page.

    2 The IDE_LOADLIB environment variable is set automatically when you start the enterprise server region from the Enterprise Developer Server Explorer.

  8. Click Add. Enterprise Server returns Add successful.
  9. Click Apply. Enterprise Server returns Update successful.
  10. Click Home to return to the Administration Home page.

    You can install the new resources by stopping and starting the region.

  11. From the Enterprise Developer Server Explorer, right-click CWSPROV ; then select Restart. This stops and then starts the CWSPROV enterprise server region, automatically installing and loading the newly added resources on the startup list.

Verify Resources

After CWSPROV is started, you can verify that the resources you have defined are installed and active.

  1. Start ESMAC.
  2. On the ESMAC menu, select Active from the drop-down list located under Resources.
  3. On the ESMAC menu, click the WebSvc button. You should see the Reverse Web service listed and marked as ENABLED.
  4. Click the Details button that corresponds to the reverse Web service.

    Notice the value for WSBIND. This value is taken from the information you provided when you created the Web service.

  5. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to PROVPIPE. The Pipeline resource sets the response wait period, identifies the SOAP configuration file, and the Web Service directory.
  6. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cwsDemo/reverseMe.

    Enterprise Server generates URIMAPs to provide CICS with the information it needs to process requests. The name of each generated URIMAP begins with a pounds sterling symbol (£).

    To run your provider CICS Web service, you send a SOAP request to an endpoint URL that routes the request to your enterprise server region. The endpoint URL contains a URI value. The incoming request reads the installed URIMAPs to identify the map whose Path value matches the URI value of the endpoint URL. When the correct URIMAP is identified, CICS uses the data defined in the URIMAP, such as the name of the Web Service and its associated Pipeline, to process the request.

Test the Reverse Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a SOAP request to run the Web service. You can do this using any SOAP requester tool such as the SOAPui Eclipse plug-in.

  1. Create a SOAP request that contains the following:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:cws="http://tempuri.org/reverse">
   <soapenv:Header/>
   <soapenv:Body>
      <cws:reverseRequest>
         <cws:InputStrings>
            <cws:myString>dlroW olleH</cws:myString>
            <cws:myString>esaelP eM esreveR</cws:myString>
         </cws:InputStrings>
      </cws:reverseRequest>
   </soapenv:Body>
</soapenv:Envelope>
  2. Submit the SOAP request to the following endpoint URL:

    http://localhost:5482/cwsDemo/reverseMe

    You should receive the following SOAP response:

    <SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:cws="http://tempuri.org/reverse"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <reverseResponse xmlns="http://tempuri.org/reverse">
         <OutputStrings>
            <reversedString>Hello World</reversedString>
            <reversedString>Reverse Me Please</reversedString>
         </OutputStrings>
      </reverseResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Tutorial: CICS Web Service Requester from WSDL, Top-down Method

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the top-down method to create a Web service requester that runs the provider Web service you created in the previous tutorial.

Prerequisites

If you have not done so already, you must install the IBM-37, IBM-437, and 002501B5 CCSID tables before attempting this tutorial. See To install CCSID tables for instructions.

Before attempting to complete this tutorial, you must first complete Tutorial: CICS Web Service Provider from WSDL, Top-down Method. This tutorial picks up where it left off.

The Test the InvokeReverse Web service requester section of this tutorial requires that you have access to a TN3270 emulator such as Rumba.

This tutorial assumes that your Eclipse project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Create the InvokeReverse project

Use the CICSWebServicesProjectTemplate template project to create an Eclipse project for your CICS Web service requester.

  1. From the Enterprise Developer main menu, click File > New > Mainframe COBOL Project.
    Note: If Mainframe COBOL Project is not listed:
    1. Select Other.
    2. Expand Micro Focus COBOL.
    3. Select Mainframe COBOL Project; then click Next.
  2. In the Project name field, type InvokeReverse.
  3. Check Browse for template.
  4. Click the Browse button that corresponds to the Location field, and browse to and select the CICSWebServicesProjectTemplate template project folder, located in the temporary directory where you extracted the CICSWebServicesProjectTemplate_Eclipse.zip file in the previous tutorial; then click OK.
  5. Check Use default location; then click Finish.

    The COBOL Explorer now shows the InvokeReverse project, which is built automatically.

Generate CICS Web Service requester components

Use the New CICS Web Service wizard to generate the components of your Web service requester.

  1. From the COBOL Explorer, click the InvokeReverse project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed, select Other; then locate and select CICS Web Service.
  3. From the Service type drop-down list, select CICS Web Service Requester (Top-Down); then click Next.

    The Project field should already show the InvokeReverse project name.

  4. Click the Browse button that corresponds to the Service definition field, and navigate to the reverse.wsdl file located in the wsdl project folder.
  5. Double-click reverse.wsdl. This populates the Service definition field.
  6. In the Program name field, type invkRev, which is the program name for the generated COBOL skeleton program.
  7. Click Finish.

Enterprise Developer generates the following CICS Web service components:

COBOL Programs\invkRev.cbl
A skeleton CICS program.
Copybooks\REQ01.cpy
A copybook containing the COBOL data structures required to send a SOAP request as input.
Copybooks\RESP01.cpy
A copybook containing the COBOL data structures required to receive a SOAP response message as output.
loadlib\invkRev.wsbind
A bind file that maps the SOAP request to the data structure in REQ01.cpy, and maps the data structure in RESP01.cpy to the SOAP response message.

Implement the service requester

The generated skeleton program, invkRev.cbl, contains some basic functionality that is common to any CICS Web service requester. In this case, it:

  • Puts the reverseRequest-input-parms data structure into the DFHWS-DATA container.
  • Invokes the reverserequest operation from the reverse Web service provider.
  • Populates the reverseRequest-output-parms data structure from the response in DFHWS-DATA.

To provide the program with a URI and port that directs the request to the enterprise server region that is running your Web service provider, you must edit the code.

  1. From the COBOL Explorer, double-click invkRev.cbl to open it in the COBOL editor.
  2. In the LOCAL-STORAGE SECTION, change the value of ls-uri to:
    "http://localhost:5482/cwsDemo/reverseMe"
  3. In the PROCEDURE DIVISION, WS-OP-1 section, add the following MOVE statements before the EXEC CICS PUT CONTAINER statement:
    move 1                      to myString-occurs
move 'esaelPeMesreveR'      to myString(1)
  4. After the EXEC CICS GET CONTAINER command for DFHWS-DATA, add the following code to send the reversed string back to the terminal:
     exec cics send text
      from(reversedString(1))
      freekb
 end-exec
  5. Save the program and exit the editor.

    Eclipse automatically builds the project to include your changes.

Create an enterprise server region

Here you use Enterprise Server to create an enterprise server region on which to run the Web service.

  1. From Enterprise Developer, activate the Server Explorer.
    Note: If Server Explorer is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type CWSREQ. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesProjectTemplate.xml file located in the ESTemplates project folder.
  5. Double-click CICSWebServicesProjectTemplate.xml. This populates the Template field.
  6. On the list next to Associate with projects, check InvokeReverse.
  7. Click Finish.

    The Server Explorer should now show the CWSREQ enterprise server region listed under Local [localhost:86].

    Note: If CWSREQ is not showing, expand Local [localhost:86].

Configure CWSREQ resources

As with the CWSPROV enterprise server region created in the previous tutorial, you need to add the appropriate resources to the startup list and add and configure additional resources required by the CICS program.

Start the CWSREQ enterprise server region
  1. Start Enterprise Server Administration from Server Explorer.
  2. On Server Explorer, right-click CWSREQ; then select Start.
    Note: If an Enterprise Server Sign On dialog appears, click OK. The new enterprise server region does not use specific server credentials.
Start ES Monitor and Control (ESMAC)
  1. After CWSREQ has started, on the Administration Home page, click the Details button located in the Status column for the CWSREQ region.
  2. On the Server > Control page, click ES Monitor & Control.
Add resource groups
Here, you add the DFHWEB and DFHPIPE resource groups to the startup list, and add the MYCWSPRV resource group name to the startup list. At this point, you have neither created nor defined the MYCWSPRV group and its respective resources. Those tasks are completed in the next few sections of this tutorial.
  1. On the ESMAC menu ribbon, click the Resources drop-down list; then select by Group.
  2. Click Startup.
  3. Click the Details button that corresponds to the DEMOSTRT startup list.
  4. On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type DFHWEB into the empty field at the bottom; then click Apply. ESMAC adds the DFHWEB group, and adds another empty field at the end of the list.
  5. In the new empty field, type DFHPIPE; then click Apply.
  6. In the new empty field, type MYCWSPRV; then click Apply.

    As with the previous tutorial, you need to create the MYCWSREQ resource group.

Create the MYCWSREQ resource group
  1. On the ESMAC menu, click the Groups button located under Resources.
  2. On the CICS Resource Groups page, click New.
  3. In the Name field, type MYCWSREQ.
  4. In the Description field, type CICS Web Services Requester Resources; then click Add.
Create and verify resources
The InvokeReverse program requires a resource to support a pipeline, and a PCT resource used to invoke the Reverse Web service from a TN3270 terminal emulator.
  1. On the CICS Group MYCWSREQ page, click Pipeline.
  2. Complete these fields:
    Name | REQPIPE
    Description | My CICS Requester Pipeline
    Resp Wait | DEFT
    Config file | $IDE_XML_LOC\basicsoap11requester.xml
    WebSvc Dir | $IDE_LOADLIB\
  3. Click Add; then click Apply.
  4. Click Group List to return to the CICS Group MYCWSREQ page.
  5. Click PCT.
  6. Complete these fields:
    Name | INVK
    Description | CWS transaction to invoke the reverse service
    Program Name | INVKREV
  7. Click Add; then click Apply.
  8. To return to the Administration Home page, click Home at the top of the ESMAC menu.

    You can install the new resources by stopping and starting the region.

  9. From the Enterprise Developer Server Explorer, right-click CWSREQ; then select Restart. This stops and then starts the CWSREQ enterprise server region, automatically installing and loading the newly added resources on the startup list.
  10. After CWSREQ is started, use the ESMAC Active feature to verify that the MYCWSREQ resources are installed and active.

Start the CWSPROV Region

Because your new CICS Web service requester sends requests to the CICS Web service provider you created in the previous tutorial, start the CWSPROV region before proceeding.

Test the InvokeReverse Web service requester

Now that you have your Web service requester running with all of its resources active, you are ready to run it from a TN3270 terminal emulator.

  1. From the Enterprise Developer Server Explorer, right-click CWSREQ; then select Show TN3270 display.
  2. If using Rumba, press F3 to bypass the CICS logon screen.
  3. Enter INVK.
    The emulator should return your input string, reversed:
    ReverseMePlease
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Tutorial: CICS Web Service Provider from WSDL, Bottom-up Method

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the bottom-up method to expose an existing CICS COBOL application, LOANPAYM, as a Web service. The LOANPAYM application accepts a principal amount, a loan term, and a rate as input values; then returns the calculated monthly loan payment.

Prerequisites

If you have not done so already, you must install the IBM-37, IBM-437, and 002501B5 CCSID tables before attempting this tutorial. See To install CCSID tables for instructions.

To complete the Test the LOANPAYM Web service provider section of this tutorial, we recommend that you download and install the SoapUI Open Source testing tool, available from here.

This tutorial assumes that your Eclipse project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Create the LoanDemo project

Use the CICSWebServicesProjectTemplate template project to create an Eclipse project for your CICS Web service.

  1. From the Enterprise Developer main menu, click File > New > Mainframe COBOL Project.
  2. In the Project name field, type LoanDemo.
  3. Check Browse for template.
  4. Click the Browse button that corresponds to the Location field, and browse to and select the CICSWebServicesProjectTemplate template project folder; then click OK.
  5. Check Use default location; then click Finish.

    The COBOL Explorer now shows the LoanDemo project, which is built automatically by Eclipse.

Generate WSDL and WSBIND files

Use the New CICS Web Service wizard to generate the components of your Web service.

  1. From the COBOL Explorer, click the LoanDemo project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed, select Other; then locate and select CICS Web Service.
  3. From the Service type drop-down list, select CICS Web Service (Bottom-Up); then click Next.

    The Project field should already show the LoanDemo project name.

  4. Click the Browse button that corresponds to the Program location field, and navigate to the LOANPAYM.cbl file located in the cbl project folder.
  5. Double-click LOANPAYM.cbl. This populates the Program location field, and populates the Program name field with the name defined in the program.
  6. In the Service location field, type:

    http://localhost:5482/cics/services/loanpaym

    This is the endpoint URL that you use to invoke the Web service. It specifies the server, port, and a URI used to identify the Web service in Enterprise Server.

    The LOANPAYM program contains a COMMAREA interface; therefore, you can accept the default setting in the Program Interface field.

  7. Click Next.

    By default, the wizard assigns an operation name that consists of the program name followed immediately by Operation.

    The request and response structures for your Web service are contained in the LoanDemo project's two copybooks.

  8. Click the Browse button that corresponds to the Request structures field, and browse to the cpy project folder.
  9. Select LOANINP; then click OK.
  10. Repeat the process in the previous two steps to add the LOANOUT copybook to the Response structures field.
  11. Click Finish.

In your LoanDemo project, you should now see an entry for Web Services > LOANPAYM > LOANPAYMOperation.

The loadlib project folder should now contain the following generated files:

LOANPAYM.wsbind
A bind file that maps the SOAP request to the data structure in LOANIN.cpy, and maps the data structure in LOANOUT.cpy to the SOAP response message.
LOANPAYM.wsdl
The Web service definition file that describes the LOANPAYM application.

Configure the enterprise server region

This tutorial uses the CWSPROV enterprise server region created in Tutorial: CICS Web Service Provider from WSDL, Top-down Method to run the Web service provider.

Do one of the following:

  • If you did not complete Tutorial: CICS Web Service Provider from WSDL, Top-down Method, skip the instructions in this section, go back to Tutorial: CICS Web Service Provider from WSDL, Top-down Method, and complete the sections titled Create an enterprise server region and Configure CWSPROV resources. However, when selecting a project with which to associate the new region, check the LoanDemo project instead of the Reverse project.
  • If you created and configured CWSPROV while completing Tutorial: CICS Web Service Provider from WSDL, Top-down Method, follow the steps in this section to update the dfhdrdat file and properly associate CWSPROV with the LoanDemo project.
Update the dfhdrdat file
When you create an enterprise server region from the Enterprise Developer Server Explorer, it stores some configuration information in the project's system\dfhdrdat file. Therefore, to update the LoanDemo project with this information, you can copy the file from the Reverse project to the LoanDemo project:
  1. On COBOL Explorer, expand the Reverse project and locate the system\dfhdrdat file.
  2. Right-click dfhrdat; then select Copy.
  3. Expand the LoanDemo project and locate its system\dfhdrdat file.
  4. Right-click dfhrdat; then select Paste.
  5. Answer Yes to the prompt to overwrite the existing file.
Associate the LoanDemo project
In previous tutorials, you have associated your project with an enterprise server region as part of the steps to create the region. Because the region you are using here was previously associated with the Reverse project, you need to change the association to the LoanDemo project.
  1. On the Server Explorer, right-click CWSPROV; then select Associate with project.
    Note: If a check mark shows next to Reverse, click Reverse to remove the association; then repeat this step and continue with step 2.
  2. Click LoanDemo to create an association.
  3. If you are prompted to restart the server, answer Yes; if you are not prompted, right-click CWSPROV and select Start from the context menu.

Verify Resources

After CWSPROV is started, you can verify that the resources you have defined are installed and active.

Start Enterprise Server Administration
  1. From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box. If a Secure Storage prompt appears, click No.

    On the Home page, you should see the CWSPROV enterprise server region listed.

Start ES Monitor and Control (ESMAC)
  1. On the Enterprise Server Administration Home page, click the Details button located in the Status column for the CWSPROV region.
  2. On the Server > Control page, click ES Monitor & Control. This starts the ESMAC utility where you can view the defined resources.
View defined resources
  1. On the ESMAC menu, select Active from the drop-down list located under Resources.
  2. Click the WebSvc button. You should see the LOANPAYM Web service listed and marked as INSERVICE.
  3. Click the Details button that corresponds to the LOANPAYM Web service.

    Notice the value for WSBIND. This value is determined by the information stored in your project.

  4. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to PROVPIPE. The Pipeline resource sets the response wait period, identifies the SOAP configuration file, and the Web Service directory.
  5. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cics/services/loanpaym.

    Enterprise Server generates URIMAPs to provide CICS with the information it needs to process requests. The name of each generated URIMAP begins with a pounds-sterling symbol (£).

    To run your provider CICS Web service, you send a SOAP request to an endpoint URL that routes the request to your enterprise server region. The endpoint URL contains a URI value. The incoming request reads the installed URIMAPs to identify the map whose Path value matches the URI value of the endpoint URL. When the correct URIMAP is identified, CICS uses the data defined in the URIMAP, such as the name of the Web Service and its associated Pipeline, to process the request.

Test the LOANPAYM Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a SOAP request to run the Web service. You can do this using any SOAP requester tool such as the SOAPui Eclipse plug-in.

  1. Create a SOAP request that contains the following:
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:loan="http://tempuri.org/LOANPAYM">
   <soapenv:Header/>
   <soapenv:Body>
      <loan:LOANPAYMOperation>
         <loan:LOANINP>
            <loan:principal>50000</loan:principal>
            <loan:loanterm>180</loan:loanterm>
            <loan:rate>5.56</loan:rate>
         </loan:LOANINP>
      </loan:LOANPAYMOperation>
   </soapenv:Body>
</soapenv:Envelope>
  2. Submit the SOAP request to the following endpoint URL:

    http://localhost:5482/cics/services/LOANPAYM

    You should receive the following SOAP response:

    <SOAP-ENV:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:loan="http://tempuri.org/LOANPAYM"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Body>
      <LOANPAYMOperationResponse xmlns="http://www.LOANPAYM.com">
         <LOANOUT>
            <monthlyPayment>$410.13</monthlyPayment>
         </LOANOUT>
      </LOANPAYMOperationResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Tutorial: CICS Web Service Provider from JSON, Request-Response Top-down Method

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the top-down method to create a CICS Web service provider application that receives a character string in the form of a JSON request. The application reverses the string, and sends the reversed string back to the requester as a JSON response message.

To use the top-down method to create a CICS Web service provider, you start with request and response JSON that describes request and response data structures. From the JSON, you generate a skeleton CICS COBOL provider application, and a WSBIND file that provides mapping between the JSON and the COBOL data structures.

The sample project used in this tutorial to create your Enterprise Developer for Eclipse project contains the reverse.json schema, which describes both the request and response data structures.

Prerequisites

To complete this tutorial, review the information in the Configuration Requirements for CICS Web Services topic.

To complete the Test the ReverseJSON Web service provider section of this tutorial, we recommend that you install a JSON requester tool.

This tutorial assumes that your Enterprise Developer project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Import the ReverseJSON project

  1. In Eclipse, start the Team Developer Application Explorer.
  2. From the main menu, click File > Import.
  3. Expand General, and select Existing Projects into Workspace; then click Next.
  4. Select Set root directory, then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\JSON\Provider\TopDown directory; then click OK.
  5. On the Projects list, ensure that ReverseJSON is checked.
  6. Under Options, check Copy projects into workspace; then click Finish.

    The Application Explorer now shows the ReverseJSON project, which is created in a ReverseJSON subdirectory of your current Eclipse workspace, and is built automatically.

Generate CICS Web Service provider components

Use the New CICS Web Service wizard to generate the components of your Web service provider.

  1. From the Application Explorer, click the ReverseJSON project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed:
    1. Select Other.
    2. Expand Micro Focus Service Interface.
    3. Select CICS Web Service; then click Next.
  3. Under Service type, select JSON message processing.
  4. From the drop-down list, select CICS Web Service Provider (Top-Down, Request-Response); then click Next.

    The Project field is already populated with the name of the current project, ReverseJSON.

  5. Click the Browse button that corresponds to the JSON request field.
  6. Navigate to and select the reverse.json file, located in your project's schema folder.
  7. Click the Browse button that corresponds to the JSON response field.
  8. Navigate to and select the reverse.json file, located in your project's schema folder.

    You need to provide a URI that Enterprise Server can use to identify and locate the appropriate Web service upon receiving a request or a response. This information goes into the Service location field.

  9. In the Service location field, type /cics/services/json/reverse.
  10. Select CHANNEL from the Program interface drop-down list.

    The default container name is DFHWS-DATA, which is the top-level container used in service provider applications for CICS Web services.

  11. Click Next.
  12. In the Output artifacts group, type reverseJ into the Program name field. This is the name of the generated COBOL skeleton program.

    The file prefixes you supply for the Request file prefix and Response file prefix fields become the first part of the filenames of the generated copybooks that support the generated skeleton program file; one for request data structures, and one for response data structures.

  13. In the Request file prefix field, type REQ.
  14. In the Response file prefix field, type RESP.

    Enterprise Developer generates a WSBIND file that maps the JSON request to the data structure in the generated request copybook and maps the JSON response to the data structure in the generated response copybook. You need to provide a folder and filename for this file.

  15. Click the Browse button that corresponds to the WSBIND file field.
  16. On the Browse for WSBIND file dialog, click New folder.
  17. In the field for the folder name, overwrite New folder with loadlib; then press Enter.
  18. Double-click the loadlib folder.
  19. In the File name field, type ReverseJ; then click Open.
  20. Click Finish.

Enterprise Developer generates the following CICS Web service components:

reverseJ.cbl
A skeleton CICS program.
reverseJ.svi
A service interface file.
REQ01.CPY
A copybook containing the COBOL data structures required to send a JSON request as input. This file is generated but does not appear in the Solution Explorer.
RESP01.CPY
A copybook containing the COBOL data structures required to receive a JSON response message as output.

Implement the service

The generated skeleton program, reverseJ.cbl, contains some basic functionality that is common to any CICS Web service that uses the Channel interface. The Web service:

  • Populates the request data structure (in REQ01.CPY) with the content of the DFHWS-DATA container.
  • Populates the DFHWS-DATA container with the content of the response data structure (in RESP01.CPY).

To provide the required operation logic, you must code it manually by editing the program.

  1. From the Application Explorer, double-click reverseJ.cbl to open it in the COBOL editor.
  2. Declare the following two variables in the Working-Storage section:
    01 ws-string-len               pic x(4) comp-5.
01 ws-reversedString-len       pic x(4) comp-5.

    The provided revLogicJ.cpy copybook contains one PERFORM statement that populates the request and response data structures. You need to include the copybook in the program and execute the PERFORM statement.

  3. reverseJ.cbl contains two comment lines between the EXEC CICS GET and the EXEC CICS PUT statements. Code the following PERFORM statement between the comment lines:
    perform reverse-logic
  4. Scroll down to the bottom of the program, and add the following copy statement after the exit program statement:
    copy 'revLogicJ.cpy'.
  5. Click File > Save.
  6. Close the COBOL editor.

    Eclipse automatically builds the project to include your changes.

Create an enterprise server region

Here you use Enterprise Server to create an enterprise server region on which to run the Web service.

  1. In Enterprise Developer, activate the Server Explorer.
    Note: If Server Explorer is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type JSONPROV. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesTemplate.xml file located in the ReverseJSON project folder.
  5. Double-click CICSWebServicesTemplate.xml. This populates the Template field.
  6. On the list next to Associate with projects, check ReverseJSON.
  7. Click Finish.

    The Server Explorer should now show the JSONPROV enterprise server region listed under Local [localhost:86].

    Note: If JSONPROV is not showing, expand Local [localhost:86].

Configure JSONPROV resources

All enterprise server regions require access to certain resources, depending on the types of applications they run. Resources that are defined on a region's startup list are loaded during the startup routine, making them available for as long as the region is running.

JSON CICS Web services use the underlying resources provided by the standard Enterprise Server CICS Web interface (CWI) and CICS Web Services (CWS) support. However, the resource definition file supplied with the project does not include these resources; therefore, you need to add them manually. The CWI resources reside in a predefined resource group named DFHWEB. The CWS resources are in the predefined DFHPIPE group.

In addition, you need to create and define a resource group, JSONPROV, to contain the resources required by the reverseJ program.

Start Enterprise Server Administration
  1. From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page. This starts Enterprise Server Administration.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box. If a Secure Storage prompt appears, click No.

    On the Home page, you should see the JSONPROV enterprise server region listed.

  2. Back on the Server Explorer, right-click JSONPROV; then select Start.

    As the region is starting, the Enterprise Server Administration Home page should show log information in the region's Status Log column. When the region is fully started, this is indicated in the region's Status column.

Start ES Monitor and Control (ESMAC)
  1. After JSONPROV has started, on the Administration Home page, click the Details button located in the Status column for the JSONPROV region.
  2. On the Server > Control page, click ES Monitor & Control. This starts the ESMAC utility where you can edit the startup list.
Open the DEMOSTRT startup list
  1. On the ESMAC menu, click the drop-down list located under Resources; then select by Group.
  2. Click Startup. This invokes a list of CICS Startup Lists in the right pane.

    The JSONPROV region uses the default startup list, named DEMOSTRT.

  3. Click the Details button that corresponds to DEMOSTRT. This takes you to the CICS STARTUP - DEMOSTRT page.
Add resource groups
CICS Web Services are built on top of the CICS Web Interface (CWI) support, so you need to ensure that all CWS and CWI resources are available. These reside in the DFHPIPE and DFHWEB resource groups respectively, which are already defined, but not included in the startup list. Here you add these resource groups to the startup list.
In addition, you need to add a new resource group for the CICS provider resources named JSONPROV. At this point, the JSONPROV resource group is neither created nor defined. Those tasks are completed in the next few sections of this tutorial.
  1. On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type DFHWEB into the empty field at the bottom; then click Apply. ESMAC adds the DFHWEB group, and adds another empty field at the end of the list.
  2. In the new empty field, type DFHPIPE; then click Apply.
  3. In the new empty field, type JSONPROV; then click Apply.
Create the JSONPROV resource group
  1. On the ESMAC menu, click the Groups button located under Resources.
  2. On the CICS Resource Groups page, click New.
  3. In the Name field, type JSONPROV.
  4. In the Description field, type CICS Web Services Provider Resources; then click Add. This invokes the CICS Group JSONPROV page where you can create and define resources for the group.
Define JSONPROV resources
The reverseJ program requires a resource for TCP/IP service, and a resource to support a pipeline.
  1. On the CICS Group JSONPROV page, click TCPIPSv.
  2. Complete these fields:
    Name | CWSTCPIP
    Description | My TCP/IP Service
    Port No | 5482
  3. Click Add. Enterprise Server returns Add successful.
  4. Click Apply. Enterprise Server returns Update successful.
  5. Click Group List to return to the CICS Group JSONPROV page.
  6. Click Pipeline.
  7. Complete these fields:
    Name | JSONPIPE
    Description | My CICS JSON Provider Pipeline
    Resp Wait | DEFT | This is the number of seconds that an application waits for a response from the service. DEFT indicates the default value, which is 10 seconds for HTTP and 60 seconds for MQ.
    Config file | $IDE_XML_LOC\JSONConfig.xml | The IDE_XML_LOC environment variable in JSONPROV points to the xml project folder.1
    WebSvc Dir | $IDE_LOADLIB\ | The IDE_LOADLIB environment variable points to the loadlib project folder, which contains the WSBIND file.1

    1 To see a list of environment variables defined for JSONPROV, from the ESMAC menu, click Env.Vars..

  8. Click Add. Enterprise Server returns Add successful.
  9. Click Apply. Enterprise Server returns Update successful.
  10. Click Home to return to the Administration Home page.

    You can install the new resources by stopping and starting the region.

  11. From the Enterprise Developer Server Explorer, right-click JSONPROV; then select Restart. This stops and then starts the JSONPROV enterprise server region, automatically installing and loading the newly added resources on the startup list.

Verify Resources

After JSONPROV is started, you can verify that the resources you have defined are installed and active.

  1. In Enterprise Server, start ESMAC for the JSONPROV region.
  2. On the ESMAC menu, select Active from the drop-down list located under Resources.
  3. On the ESMAC menu, click the WebSvc button. You should see the reverseJ Web service listed and marked as INSERVICE.
  4. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to JSONPIPE. The Pipeline resource sets the response wait period, identifies the JSON configuration file, and the Web Service directory.
  5. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cics/services/json/reverse.

    Enterprise Server generates URIMAPs to provide CICS with the information it needs to process requests. The name of each generated URIMAP begins with a pounds sterling symbol (£).

    To run your provider CICS Web service, you send a JSON request to an endpoint URL that routes the request to your enterprise server region. The endpoint URL contains a URI value. The incoming request reads the installed URIMAPs to identify the map whose Path value matches the URI value of the endpoint URL. When the correct URIMAP is identified, CICS uses the data defined in the URIMAP, such as the name of the Web Service and its associated Pipeline, to process the request.

Test the ReverseJSON Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a JSON request to run the Web service. You can do this using any JSON requester tool.

  1. Create a JSON request with the following endpoint URL:
    http://localhost:5482/cics/services/json/reverse
  2. Set the Method to POST.
  3. Enter the following JSON request:
    {"myStrings":["olleH"]}

    You should receive the following JSON response:

    {"myStrings":[ "Hello" ]}
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Tutorial: CICS Web Service Requester from JSON, Linkable Interface Top-down Method

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the top-down method to create a Web service requester that runs the provider Web service you created in the previous tutorial.

Prerequisites

If you have not done so already, you must install the IBM-37, IBM-437, and 002501B5 CCSID tables before attempting this tutorial. See To install CCSID tables for instructions.

Before attempting to complete this tutorial, you must first complete Tutorial: CICS Web Service Provider from JSON, Request-Response Top-down Method. This is required because the requester generated in this tutorial runs the provider Web service you created in the previous tutorial and that runs on the JSONPROV enterprise server region.

The Test the invkRevJ Web service requester section of this tutorial requires that you have access to a TN3270 emulator such as Rumba.

This tutorial assumes that your Eclipse project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Import the InvokeReverseJSON project

  1. In Eclipse, start the Team Developer Application Explorer.
  2. From the main menu, click File > Import.
  3. Expand General, and select Existing Projects into Workspace; then click Next.
  4. Select Set root directory, then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\JSON\Requester\TopDown directory; then click OK.
  5. On the Projects list, ensure that InvokeReverseJSON is checked.
  6. Under Options, check Copy projects into workspace; then click Finish.

    The Application Explorer now shows the InvokeReverseJSON project, which is created in an InvokeReverseJSON subdirectory of your current Eclipse workspace, and is built automatically.

Generate CICS Web Service requester components

Use the New CICS Web Service wizard to generate the components of your Web service requester.

  1. From the Application Explorer, click the InvokeReverseJSON project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed, select Other; then locate and select CICS Web Service.
  3. Under Service type, select JSON message processing.
  4. From the drop-down list, select CICS Web Service Requester (Top-Down, Linkable Interface); then click Next.

    The Project field is already populated with the name of the current project, InvokeReverseJSON.

  5. In the Service name field, type invkRevJ; then click Next.
  6. Click the Browse button that corresponds to the JSON schema field.
  7. Navigate to and select the reverse.json file, located in your project's schema folder.
  8. In the Output artifacts group, type REQ into the Request file prefix field.
  9. Click the Browse button that corresponds to the Bundle field.
  10. Navigate to your project directory.
  11. Click Make New Folder.
  12. Name the new folder bundles; then press Enter.
  13. Click the bundles folder.
  14. Using the same method as before, create a new folder under bundles named REQBNDL.
  15. Select the REQBNDL folder; then press Enter.
  16. Click OK.
  17. In the JSON transform field, type REVREQUEST; then click Next.
  18. Click the Browse button that corresponds to the JSON schema field.
  19. Navigate to and select the reverse.json file, located in your project's schema folder.
  20. In the Response file prefix field, type RESP.
  21. Click the Browse button that corresponds to the Bundle field.
  22. Navigate to your project's bundles directory.
  23. Using the same method as before, create a new directory under bundles named RESPBNDL.
  24. Select the RESPBNDL folder; then press Enter.
  25. Click OK.
  26. In the JSON transform field, type REVRESPONSE; then click Finish.

Enterprise Developer generates the following CICS Web Service components:

REQ01.CPY
A COBOL copybook that contains the request data structure.
RESP01.CPY
A COBOL copybook that contains the response data structure.
bundles\REQBNDL\
jsbinds\reverse.json
The JSON schema that describes the request data structure.
jsbinds\REVREQUEST.jsbind
The JSON binding file that used to transform the COBOL request data into JSON.
META-INF\cics.xml
A manifest file that defines the type of bundle, it's location, and filename. In this case, the type is JSONTRANSFRM and its name is REVREQUEST.
REVREQUEST.log
A log file that contains information about the content of the REVREQUEST.jsbind file. This log file can be useful to Micro Focus SupportLine to help diagnose problems should they arise.
bundles\RESPBNDL\
jsbinds\reverse.json
The JSON schema that describes the response data structure.
jsbinds\REVRESPONSE.jsbind
The JSON binding file that used to transform the COBOL response message into COBOL.
META-INF\cics.xml
A manifest file that defines the type of bundle, it's location, and filename. In this case, the type is JSONTRANSFRM and its name is REVRESPONSE.
REVRESPONSE.log
A log file that contains information about the content of the REVRESPONSE.jsbind file. This log file can be useful to Micro Focus SupportLine to help diagnose problems should they arise.

Analyze the invkRevJ.cbl program

The supplied invkRevJ.cbl program already contains the functionality that is required to invoke the reverseJ service. Any JSON application that uses a linkable interface, including invkRevJ.cbl, is required to do the following:

  • Populate the request structure.
  • PUT that data into a CONTAINER named DFHJSON-DATA.
  • PUT the name of the JSONTRANSFRM resource used to transform the COBOL request data to JSON into a CONTAINER named DFHJSON-TRANSFRM.
  • LINK to DFHJSON, which includes:
    • Locating the appropriate JSBIND file by using the JSONTRANSFRM resource named in the DFHJSON-TRANSFRM CONTAINER.
    • Transforming the content of the DFHJSON-DATA CONTAINER into JSON using the JSBIND file and placing it into the DFHJSON-JSON CONTAINER.
  • SEND the request and RECEIVE the response, which includes:
    • Using WEB OPEN to open a connection to the server hosting the service.
    • Using WEB CONVERSE to SEND the request to the server and RECEIVE the response. This is done by supplying the request message via the DFHJSON CONTAINER and receiving the response message into the same CONTAINER.
    • Using WEB CLOSE to close the connection to the server.
  • PUT the name of the JSONTRANSFRM resource used to transform the JSON response message to COBOL into a CONTAINER named DFHJSON-TRANSFRM.
  • LINK to DFHJSON, which repeats the same procedure as before.
  • Populates the response structure by GETting the content of the DFHJSON-DATA CONTAINER.
  1. From the Application Explorer, double-click invkRevJ.cbl to open it in the COBOL editor.
  2. Browse through the code, noting each block of code that corresponds to the JSON application linkable interface requirements.

Create an enterprise server region

Here you use Server Explorer to create an enterprise server region on which to run the requester Web service.

  1. On the Server Explorer, right-click Local [localhost:86]; then select New > Enterprise Server.
  2. In the Name field, type JSONREQ.
  3. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesProjectTemplate.xml file located in the InvokeReverseJSON project folder.
  4. Double-click CICSWebServicesProjectTemplate.xml.
  5. On the list next to Associate with projects, check InvokeReverseJSON.
  6. Click Finish.

    The Server Explorer should now show the JSONREQ enterprise server region listed under Local [localhost:86].

Configure JSONREQ resources

Start Enterprise Server Administration
  1. On the Server Explorer, right-click JSONREQ; then select Start.
Start ES Monitor and Control (ESMAC)
  1. After JSONREQ has started, on the Enterprise Server Administration Home page, click the Details button located in the Status column for the JSONREQ region.
  2. On the Server > Control page, click ES Monitor & Control.
Open the DEMOSTRT startup list
  1. On the ESMAC menu, click the drop-down list located under Resources; then select by Group.
  2. Click Startup.
  3. Click the Details button that corresponds to DEMOSTRT.
Add resource groups
As with the JSONPROV enterprise server region, the JSONREQ region requires the DFHWEB and DFHPIPE resource groups, and a resource group to contain the requester resources Here, you add these resource groups to the startup list.
  1. On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type DFHWEB into the empty field at the bottom; then click Apply. ESMAC adds the DFHWEB group, and adds another empty field at the end of the list.
  2. In the new empty field, type DFHPIPE; then click Apply.
  3. In the new empty field, type JSONREQ; then click Apply.
Create the JSONREQ resource group
  1. On the ESMAC menu, click the Groups button located under Resources.
  2. On the CICS Resource Groups page, click New.
  3. In the Name field, type JSONREQ.
  4. In the Description field, type CICS Web Services JSON Requester Resources; then click Add.
Create and verify resources
The invkRevJ program requires a URIMap resource, a pair of Bundle resources, and a PCT resource used to invoke the Reverse Web service from a TN3270 terminal emulator.
  1. On the CICS Group JSONREQ page, click URIMap.
  2. Complete these fields:
    Name | REVRSURI
    Description | URIMAP for JSON reverseJ request
    Usage | Client
    Port | 5482
    Host | localhost
    Path | /cics/services/json/reverse
  3. Click Add; then click Apply.
  4. Click Group List to return to the CICS Group JSONREQ page.
  5. Click Bundle.
  6. Complete these fields:
    Name | REQBNDL
    Description | Input bundle to map the data structure to a JSON request
    Bundle Dir | $IDE_BUNDLE_LOC\REQBNDL
  7. Click Add; then click Apply.
  8. Click Group List to return to the CICS Group JSONREQ page.
  9. Click Bundle.
  10. Complete these fields:
    Name | RESPBNDL
    Description | Output bundle to map the JSON response to a data structure
    Bundle Dir | $IDE_BUNDLE_LOC\RESPBNDL
  11. Click Add; then click Apply.
  12. Click Group List to return to the CICS Group JSONREQ page.
  13. Click PCT.
  14. Complete these fields:
    Name | INVJ
    Description | CWS transaction to invoke the reverse service
    Program Name | invkRevJ
  15. Click Add; then click Apply.
  16. To return to the Administration Home page, click Home at the top of the ESMAC menu.

    You can install the new resources by stopping and starting the region.

  17. From the Enterprise Developer Server Explorer, right-click JSONREQ; then select Restart. This stops and then starts the CWSJSON enterprise server region, automatically installing and loading the newly added resources on the startup list.
  18. After JSONREQ is started, use the ESMAC Active feature to verify that the JSONREQ resources are installed and active.

Test the invkRevJ Web service requester

Now that you have your Web service requester running with all of its resources active, you are ready to run it from a TN3270 terminal emulator.

  1. If not already started, start the JSONPROV enterprise server region from the Server Explorer.
  2. Optionally, test to confirm that the ReverseJSON provider is running by repeating the Test the ReverseJSON Web service provider section in the Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method tutorial.
  3. From the Enterprise Developer Server Explorer, right-click JSONREQ; then select Show TN3270 display.
  4. If using Rumba, press F3 to bypass the CICS logon screen.
  5. Enter INVJ.
    The emulator should return your input string, reversed:
    Hello
JSON
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Tutorial: CICS Web Service Provider from JSON, Request-Response Bottom-up Method

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the bottom-up method to expose an existing CICS COBOL application, LOANPAYM, as a Web service. The LOANPAYM application accepts a principal amount, a loan term, and a rate as input values; then returns the calculated monthly loan payment.

Prerequisites

If you have not done so already, you must install the IBM-37, IBM-437, and 002501B5 CCSID tables before attempting this tutorial. See To install CCSID tables for instructions.

To complete the Test the loanPaym Web service provider section of this tutorial, we recommend that you install a JSON requester tool.

Import the LoanDemoJSON project

  1. In Eclipse, start the Team Developer Application Explorer.
  2. From the main menu, click File > Import.
  3. Expand General, and select Existing Projects into Workspace; then click Next.
  4. Select Set root directory, then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\JSON\Provider\BottomUp directory; then click OK.
  5. On the Projects list, ensure that LoanDemoJSON is checked.
  6. Under Options, check Copy projects into workspace; then click Finish.

    The Application Explorer now shows the LoanDemoJSON project, which is created in a LoanDemoJSON subdirectory of your current Eclipse workspace, and is built automatically.

Generate CICS Web Service provider components

Use the New CICS Web Service wizard to generate the components of your Web service provider.

  1. From the Application Explorer, click the LoanDemoJSON project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed:
    1. Select Other.
    2. Expand Micro Focus Service Interface.
    3. Select CICS Web Service; then click Next.
  3. Under Service type, select JSON message processing.
  4. From the drop-down list, select CICS Web Service Provider (Bottom-Up, Request-Response); then click Next.

    The Project field is already populated with the name of the current project, LoanDemoJSON.

  5. Click the Browse button that corresponds to the Program location field.
  6. Navigate to and select the loanPaym.cbl file, located in the LoanDemoJSON folder; then click OK.
  7. In the Service location field, type /cics/services/json/loanpaym.
  8. Select COMMAREA from the Program interface drop-down list; then click Next.

    In the Mapping group, you specify the copybooks that contain request and response data structures.

  9. Click the Browse button that corresponds to the Request structure field.
  10. Navigate to and select the LOANINP.cpy file, located in the LoanDemoJSON folder; then click OK.
  11. Similarly, find and select the LOANOUT.cpy file to populate the Response structure field.

    In the Output artifacts group, you specify names and locations for request and response schema files and the location for the WSBIND file.

  12. Click the Browse button that corresponds to the JSON request field.
  13. Navigate to your project directory.
  14. Click Make New Folder.
  15. Name the new folder schema; then press Enter.
  16. Double-click the schema folder to select it.
  17. In the File name field, type loanDemoReq; then click Open.
  18. Click the Browse button that corresponds to the JSON response field.
  19. Navigate to the new schema folder.
  20. In the File name field, type loanDemoResp; then click Open.
  21. Click the Browse button that corresponds to the WSBIND file field.
  22. On the Browse for WSBIND file dialog, create a new folder named loadlib; then open the new folder.
  23. In the File name field, type loanPaym; then click Open.
  24. Click Finish.

Configure the enterprise server region

This tutorial uses the JSONPROV enterprise server region created in Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method to run the Web service provider.

Do one of the following:

  • If you did not complete Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, skip the instructions in this section, go back to Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, and complete the sections titled Create an enterprise server region and Configure JSONPROV resources. However, when selecting a project with which to associate the new region, check the LoanDemoJSON project instead of the ReverseJSON project.
  • If you created and configured JSONPROV while completing Tutorial: CICS Web Service Provider, JSON Request-Response Top-down Method, follow the steps in this section to update the dfhdrdat file and properly associate JSONPROV with the LoanJSON project.
Update the dfhdrdat file
When you create an enterprise server region from the Enterprise Developer Server Explorer, it stores some configuration information in the project's system\dfhdrdat file. Therefore, to update the LoanDemoJSON project with this information, you can copy the file from the ReverseJSON project to the LoanDemoJSON project:
  • Using Windows Explorer or at a command prompt, copy the dfhdrdat file located in the ReverseJSON project's system directory to the LoanDemoJSON project's system directory, overwriting the existing file.
Associate the LoanDemoJSON project
In previous tutorials, you have associated your project with an enterprise server region as part of the steps to create the region. Because the region you are using here was previously associated with the ReverseJSON project, you need to change the association to the LoanDemoJSON project.
  1. On the Server Explorer, right-click JSONPROV; then select Associate with project.
  2. Click LoanDemoJSON to create an association.
  3. If you are prompted to restart the server, answer Yes; if you are not prompted, right-click JSONPROV and select Start from the context menu.

Verify Resources

After JSONPROV is started, you can verify that the resources you have defined are installed and active.

Start Enterprise Server Administration
  1. From Server Explorer, right-click Micro Focus Servers; then select Administration.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box. If a Secure Storage prompt appears, click No.

    On the Home page, you should see the JSONPROV enterprise server region listed.

Start ES Monitor and Control (ESMAC)
  1. On the Enterprise Server Administration Home page, click the Details button located in the Status column for the JSONPROV region.
  2. On the Server > Control page, click ES Monitor & Control. This starts the ESMAC utility where you can view the defined resources.
View defined resources
  1. On the ESMAC menu, select Active from the drop-down list located under Resources.
  2. Click the WebSvc button. You should see the loanPaym Web service listed and marked as INSERVICE.
  3. Click the Details button that corresponds to the loanPaym Web service.

    Notice the value for WSBIND. This is determined by the information stored in your project.

  4. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to JSONPIPE. The Pipeline resource sets the response wait period, identifies the JSON configuration file, and the Web Service directory.
  5. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cics/services/json/loanpaym.

    Enterprise Server generates URIMAPs to provide CICS with the information it needs to process requests. The name of each generated URIMAP begins with a pounds-sterling symbol (£).

    To run your provider CICS Web service, you send a JSON request to an endpoint URL that routes the request to your enterprise server region. The endpoint URL contains a URI value. The incoming request reads the installed URIMAPs to identify the map whose Path value matches the URI value of the endpoint URL. When the correct URIMAP is identified, CICS uses the data defined in the URIMAP, such as the name of the Web Service and its associated Pipeline, to process the request.

Test the loanPaym Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a JSON request to run the Web service. You can do this using any JSON requester tool.

  1. Create a JSON POST request that contains the following:
    {
 "loanpaym" :
 {
  "LOANINP" :
  {
   "principal" : "5000",
   "loanterm" : "36",
   "rate" : "5.5"
  }
 }
}
  2. Submit the JSON request to the following endpoint URL:

    http://localhost:5482/cics/services/json/loanpaym

    You should receive the following JSON response:

    {"loanPaymResponse": {"LOANOUT": {"monthlyPayment": "$410.13"}}}
Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Tutorial: CICS Web Service Provider from JSON, RESTful

Restriction: This topic applies to Windows environments only.

In this tutorial, you use the top-down method to create a RESTful Web service provider that receives POST and GET requests. These requests are sent to a wrapper program that passes the requests on to the filmREST program. The filmREST program creates a film record on a POST request, and returns a film record on a GET request.

Prerequisites

If you have not done so already, you must install the IBM-37, IBM-437, and 002501B5 CCSID tables before attempting this tutorial. See To install CCSID tables for instructions.

To complete the Test the filmWeb service provider section of this tutorial, we recommend that you install a JSON requester tool.

This tutorial assumes that your Enterprise Developer project is set to Build Automatically. If not, turn this feature on by clicking Project > Build Automatically from the main menu.

Import the filmsREST project

  1. In Eclipse, start the Team Developer Application Explorer.
  2. From the main menu, click File > Import.
  3. Expand General, and select Existing Projects into Workspace; then click Next.
  4. Select Set root directory, then browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\CICS\Classic\CWS\JSON\Provider\REST directory; then click OK.
  5. On the Projects list, ensure that filmsREST is checked.
  6. Under Options, check Copy projects into workspace; then click Finish.

    The Application Explorer now shows the filmsREST project, which is created in a filmsREST subdirectory of your current Eclipse workspace, and is built automatically.

Generate CICS Web Service provider components

Use the New CICS Web Service wizard to generate the components of your Web service provider.

  1. From the Application Explorer, click the filmREST project to select it.
  2. Click File > New > CICS Web Service. This starts the New CICS Web Service Wizard.
    Note: If CICS Web Service is not listed:
    1. Select Other.
    2. Expand Micro Focus Service Interface.
    3. Select CICS Web Service; then click Next.
  3. Under Service type, select JSON message processing.
  4. From the drop-down list, select CICS Web Service Provider (Top-Down, RESTful); then click Next.

    The Project field is already populated with the name of the current project, filmsREST.

  5. Click the Browse button that corresponds to the JSON schema field.
  6. Navigate to and select the films.json file, located in your project's schema folder.
  7. In the Service location field, type /cics/services/json/film/*.
  8. Under HTTP methods, check GET, POST, PUT, and DELETE.
  9. Select CHANNEL from the Program interface drop-down list.

    The default container name is DFHWS-DATA, which is the top-level container used in service provider applications for CICS Web services.

  10. Click Next.
  11. In the Output artifacts group, type filmREST into the Program name field. This is the name of the generated COBOL skeleton program.

    The file prefix you supply for the Copy file prefix field becomes the first part of the filename of the generated copybook that supplies the generated skeleton program file with both request data structures and response data structures.

  12. In the Copy file prefix field, type film.

    Enterprise Developer generates a WSBIND file that maps the JSON request and response data structures in the generated copybook. You need to provide a folder and filename for this file.

  13. Click the Browse button that corresponds to the WSBIND file field.
  14. On the Browse for WSBIND file dialog, click New folder.
  15. In the field for the folder name, overwrite New folder with loadlib; then press Enter.
  16. Double-click the loadlib folder.
  17. In the File name field, type filmREST; then click Open.
  18. Click Finish.

Enterprise Developer generates the following CICS Web service components:

filmREST.cbl
A skeleton CICS program for a RESTful service.
film01.cpy
A copybook containing data structures.
loadlib\filmREST.wsbind
The binary file that maps JSON messages to and from COBOL.

Implement the service

The generated skeleton program, filmREST.cbl, contains some basic functionality that is common to any CICS Web service that uses the Channel interface, such as:

  • It retrieves the type of request being made from the DFHHTTPMETHOD container, and evaluates it.
  • For a GET request, it populates the DFHWS-DATA container with the content of the response data structure (in film01.cpy).
  • For a POST or PUT request, it populates the request data structure (in film01.cpy) with the contents of the DFHWS-DATA container.

To provide the required operation logic, you must code it manually by editing the program.

  1. From the Application Explorer, double-click filmREST.cbl to open it in the COBOL editor.
  2. Within the when "GET" statement, just before the exec cics put container statement, add:
    perform GET-logic
  3. Within the when "PUT" statement, just after the exec cics get container statement, add:
    perform POST-logic
  4. Scroll down to the bottom of the program, and add the following copy statement at the very end of the program:
    copy "RESTLogic.cpy".
  5. Close the COBOL editor.

Create an enterprise server region

Here you use Enterprise Server to create an enterprise server region on which to run the Web service.

  1. In Enterprise Developer for Eclipse, activate the Server Explorer.
    Note: If Server Explorer is not showing, click Window > Show View > Other > Micro Focus > Server Explorer.
  2. Right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type CWSREST. This is the name for the new enterprise server region.
  4. Click the Browse button that corresponds to the Template field, and navigate to the CICSWebServicesProjectTemplate.xml file located in the project folder.
  5. Double-click CICSWebServicesProjectTemplate.xml. This populates the Template field.
  6. On the list next to Associate with projects, check filmREST.
  7. Click Finish.

    The Server Explorer should now show the CWSREST enterprise server region listed under Local [localhost:86].

    Note: If CWSREST is not showing, expand Local [localhost:86].

Configure CWSREST resources

All Enterprise Server regions require access to certain resources, depending on the types of applications they run. Resources that are defined on a region's startup list are loaded during the startup routine, making them available for as long as the region is running.

CICS Web services use the underlying resources provided by the standard Enterprise Server CICS Web interface (CWI) and CICS Web Services (CWS) support. However, the CICSWebServicesProjectTemplate used to create the CWSREST region does not include these resources on the startup list; therefore, you need to add them manually. The CWI resources reside in a predefined resource group named DFHWEB. The CWS resources are in the predefined DFHPIPE group.

In addition, you need to create and a resource group to contain the resources required by the filmREST program, and also add the new group to the startup list.

Start Enterprise Server Administration
  1. From Server Explorer, right-click Local [localhost:86]; then select Open Administration Page. This starts Enterprise Server Administration.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box. If a Secure Storage prompt appears, click No.

    On the Home page, you should see the CWSREST enterprise server region listed.

  2. Back on the Server Explorer, right-click CWSREST; then select Start.

    As the region is starting, the Enterprise Server Administration Home page should show log information in the region's Status Log column. When the region is fully started, this is indicated in the region's Status column.

Start ES Monitor and Control (ESMAC)
  1. After CWSREST has started, on the Administration Home page, click the Details button located in the Status column for the CWSREST region.
  2. On the Server > Control page, click ES Monitor & Control. This starts the ESMAC utility where you can edit the startup list.
Open the DEMOSTRT startup list
  1. On the ESMAC menu, click the drop-down list located under Resources; then select by Group.
  2. Click Startup. This invokes a list of CICS Startup Lists in the right pane.

    The CWSREST region uses the default startup list, named DEMOSTRT.

  3. Click the Details button that corresponds to DEMOSTRT. This takes you to the CICS STARTUP - DEMOSTRT page.
Add resource groups
Here, you add the DFHWEB and DFHPIPE resource groups to the startup list, and add the CWSRESTP resource group name to the startup list. At this point, you have you have neither created nor defined the CWSRESTP group and its respective resources. Those tasks are completed in the next few sections of this tutorial.
  1. On the CICS STARTUP - DEMOSTRT page, scroll down to the end of the list and type DFHWEB into the empty field at the bottom; then click Apply. ESMAC adds the DFHWEB group, and adds another empty field at the end of the list.
  2. In the new empty field, type DFHPIPE; then click Apply.
  3. In the new empty field, type CWSRESTP; then click Apply.
Create the CWSRESTP resource group
  1. On the ESMAC menu, click the Groups button located under Resources.
  2. On the CICS Resource Groups page, click New.
  3. In the Name field, type CWSRESTP.
  4. In the Description field, type CICS Web Services JSON Provider Resources; then click Add. This invokes the CICS Group CWSRESTP page where you can create and define resources for the group.
Define CWSRESTP resources
The BookREST program requires a resource for TCP/IP service, and a resource to support a pipeline.
  1. On the CICS Group CWSRESTP page, click TCPIPSv.
  2. Complete these fields:
    Name | RSTTCPIP
    Description | My TCP/IP Service
    Port No | 5482
  3. Click Add. Enterprise Server returns Add successful.
  4. Click Apply. Enterprise Server returns Update successful.
  5. Click Group List to return to the CICS Group CWSRESTP page.
  6. Click Pipeline.
  7. Complete these fields:
    Name | RESTPIPE
    Description | My CICS Provider Pipeline
    Resp Wait | DEFT | This is the number of seconds that an application waits for a response from the service. DEFT indicates the default value, which is 10 seconds for HTTP and 60 seconds for MQ.
    Config file | $IDE_XML_LOC\JSONConfig.xml | The IDE_XML_LOC environment variable in CWSREST points to the xml project folder.1
    WebSvc Dir | $IDE_LOADLIB\ | The IDE_LOADLIB environment variable points to the loadlib project folder.1

    1 To see a list of environment variables defined for CWSREST, from the ESMAC menu, click Env.Vars..

  8. Click Add. Enterprise Server returns Add successful.
  9. Click Apply. Enterprise Server returns Update successful.
  10. Click Home to return to the Administration Home page.

    You can install the new resources by stopping and starting the region.

  11. From the Enterprise Developer Server Explorer, right-click CWSREST; then select Restart. This stops and then starts the CWSREST enterprise server region, automatically installing and loading the newly added resources on the startup list.

Verify Resources

After CWSREST is started, you can verify that the resources you have defined are installed and active.

  1. In Enterprise Server, start ESMAC for the CWSREST region.
  2. On the ESMAC menu, select Active from the drop-down list located under Resources.
  3. On the ESMAC menu, click the WebSvc button. You should see the filmREST Web service listed and marked as INSERVICE.
  4. On the ESMAC menu, click Pipeline; then click the Details button that corresponds to RESTPIPE. The Pipeline resource sets the response wait period, identifies the JSON configuration file, and the Web Service directory.
  5. On the ESMAC menu, click URIMAP; then click the Details button that corresponds to PIPELINE and /cics/services/json/filmrest/*.

    Enterprise Server generates URIMAPs to provide CICS with the information it needs to process requests. The name of each generated URIMAP begins with a pounds sterling symbol (£).

    To run your RESTful CICS Web service, you can either send an HTTP GET request to retrieve an existing film record or an HTTP PUT request to create a new film record. The request is sent to an endpoint URL that routes the request to your enterprise server region. The endpoint URL contains a URI value. The incoming request reads the installed URIMAPs to identify the map whose Path value matches the URI value of the endpoint URL. When the correct URIMAP is identified, CICS uses the data defined in the URIMAP, such as the name of the Web Service and its associated Pipeline, to process the request.

Test the film Web service provider

Now that you have your Web service provider running with all of its resources active, you are ready to send a POST and a GET request to run the Web service. You can do this using any JSON requester tool.

  1. Create and submit a JSON request with the following endpoint URL:
    http://localhost:5482/cics/services/json/film
  2. Set the method to POST.
  3. Enter the following JSON request and send it to create a new film record:
    {"film-details": [{
   "title": "Jaws", "year": "1975",
   "director": "Steven Spielberg", "format": "VHS"
}]}

    The response should be a status code of 200, and the body should contain the string /cics/services/json/film/Jaws. This is the string placed into the DFHRESPONSE container by the application.

  4. Set the method to GET.
  5. Create and submit a JSON request with the following endpoint URL:
    http://localhost:5482/cics/services/json/film/jaws

    The response should be a JSON message containing the film details placed into the DFHWS-DATA container by the application.

Parent topic: Tutorials: CICS Web Services
Related concepts
CCSID Conversion Tables
Related tasks
To install CCSID tables


Tutorials: IMS

Includes tutorials for basic IMS support features and for using the IMS Segment Layout Editor and IMS Database Editor data tools.
  • Tutorial: IMS Support
    This tutorial takes you step by step through the main features of Enterprise Developer and Enterprise Server IMS support. You start by importing an IMS demonstration application into Enterprise Developer, and finish by running the application on Enterprise Server.
  • Tutorials: IMS Data Tools
Parent topic: Mainframe Tutorials


Tutorial: IMS Support

This tutorial takes you step by step through the main features of Enterprise Developer and Enterprise Server IMS support. You start by importing an IMS demonstration application into Enterprise Developer, and finish by running the application on Enterprise Server.
Note: You can follow this tutorial in lieu of performing the steps outlined in IMS Installation Verification Procedure (IVP), which effectively produces the same end result using the command line instead of the Enterprise Developer user interface.

Prerequisites

To complete this tutorial, you need the following software in addition to Enterprise Developer:

  • Micro Focus Rumba TN3270 emulator, supplied with the Enterprise Developer installer.
    Note: If you did not choose to install Rumba when you installed Enterprise Developer, either uninstall and then rerun the installer with the Install Rumba option checked, or use an alternative TN3270 emulator. If you choose to use a different TN3270 emulator, be aware that all instructions in this tutorial assume that you are using the embedded Rumba emulator.

Demonstration Application

This tutorial uses the MFDEMO demonstration, located by default in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\IVP (for 32-bit) or IVP64 (for 64-bit) directory.

MFDEMO is a COBOL IMS TM application for creating and maintaining an IMS DB tabular database. User-defined tables are organized by table element within table name. The following components are used by this application:

IMS components:

  • DEMO03DD.DBD
  • DEMO03DD.DBU
  • DEMO001T.PSB
  • DEMO90.MFS
  • DEMO91.MFS
  • DEMO92.MFS
  • TRANCODE.TXT - IMS Stage 1 file

COBOL components:

  • DEMO001T.CBL
  • RGHTJUST.CBL

Outline

In this tutorial you perform the steps typically required in implementing and running IMS applications. Follow the steps in these topics in the order presented here:

  1. Create and Configure a Project
    Complete the steps required to create an Enterprise Developer project, import the MFDEMO IMS application into the project, set the project properties, and perform additional required steps to enable the application to run in Enterprise Server.
  2. Configure IMS
    Register the resource definition file, load the IMS database, and import IMS transactions. These three procedures are required to successfully run and interact with an IMS application on Enterprise Server.
  3. Create and Configure an IMS Enterprise Server
    Create and configure an enterprise server region on which to run the MFDEMO IMS application.
  4. Run MFDEMO
    Use the Rumba TN3270 emulator to run the MFDEMO application on the IMSDEMO enterprise server region.
  5. Debug MFDEMO
    Debug the MFDEMO application in Enterprise Developer.
Parent topic: Tutorials: IMS
Related concepts
IMS Installation Verification Procedure (IVP)
Tutorial: IMS Segment Layout Editor


Create and Configure a Project

Complete the steps required to create an Enterprise Developer project, import the MFDEMO IMS application into the project, set the project properties, and perform additional required steps to enable the application to run in Enterprise Server.

Create the project

  1. Start Enterprise Developer and select the default workspace, which is c:\Users\username\workspace where username is your operating system login ID.
  2. In Eclipse, be sure that the Team Developer perspective is the active Eclipse perspective, and that your Enterprise Development Projects are loaded in the Application Explorer view. See To load projects into the Team Developer perspective for more information.
  3. Right-click Enterprise Development Projects; then select New COBOL Project > Mainframe COBOL Project.

    This starts the COBOL Project wizard.

  4. Type IMSTutorial in the Project Name field.

    The default location for storing new projects is the workspace you selected when you started Enterprise Developer.

  5. Click Finish.

    The IMSTutorial project is created and appears in the Application Explorer view.

Add Folders

For this tutorial, you need to add two folders to your project; one for generated files, and one for system files used by Enterprise Server.

  1. In the Application Explorer view, right-click the IMSTutorial project; then click New > Folder > Folder.
  2. In the Folder name field, type loadlib; then click Finish.
  3. Using the same method, add a folder named system.
Note: The loadlib folder does not appear on the list in the Application Explorer view until you set the output directory to loadlib in the Set Project Properties section of this tutorial. The system folder is used by the project but does not appear on the list in the Application Explorer view.

Set Project Properties

  1. In the Application Explorer view, right-click the IMSTutorial project; then select Properties
  2. Expand Micro Focus > Build Configurations; then click COBOL.
  3. Set the following; then click Apply:
    • In the Output path field, replace NewConfiguration.bin with loadlib.
    • Set Platform target to 32 bit.
      Note: If you are on a 64-bit platform and intend to do this tutorial using the 64-bit demonstration files, set Platform target to 64 bit instead.
  4. In the left pane, expand Project Settings; then click COBOL
  5. Set the following; then click Apply:
    • Character set to ASCII
    • Language dialect to Enterprise COBOL for z/OS
    • Source Format to Fixed
    • Check Compile for debugging
  6. In the left pane, click Project Settings > IMS.
  7. Type loadlib into the Generated Files field.
  8. In the IMS Database field, type the full path to the loadlib folder, or use Browse to select it. If using the default workspace, this consists of the path to your workspace location followed by \IMSTutorial\loadlib.
    Note: The Generated Files setting is relative to the current project, but the IMS Database setting must be an absolute path.
  9. Click Apply.
  10. Expand Project Settings > IMS; then click DBD Settings.
  11. Check Generate Map for DBD; then click Apply.
  12. In the left pane, click MFS Settings
  13. Type loadlib into the MFS Output field; then click Apply and Close to save all changes to the project properties.

Import demonstration application files

  1. In the Application Explorer view, select your project; then click File > Import > General > File System.
  2. Click Next.
  3. Browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\IVP or IVP64 (for 64-bit) directory (default location).
  4. Select the following files to add; then click Finish.
    • DEMO001T.CBL
    • DEMO001T.PSB
    • DEMO03DD.DBD
    • DEMO03DD.DBU
    • DEMO90.MFS
    • DEMO91.MFS
    • DEMO92.MFS
    • RGHTJUST.CBL
    • TRANCODE.TXT

    This creates copies of the files in the project directory.

    Because Eclipse is configured to build the project automatically, adding the files triggers a build. Build output files are created in the loadlib folder, and include:

    • DBDGEN2.DAT
    • DBDGEN2F.DAT
    • PSBGEN3.DAT
    • DEMO001T.ACB
    • DEMO03DD.ACB
    • The MFS files generation creates some .mid, .mod, .dif and .dof files. These files contain system configuration data. You should move them only if you know how to configure your enterprise server.
    • Building the DBD and the PSB files produces respectively dbdgen2.dat, dbdgen2f.dat, psbgen3.dat as well as some .acb files.
Parent topic: Tutorial: IMS Support
Next topic: Configure IMS
Related concepts
Tutorial: IMS Segment Layout Editor


Configure IMS

Register the resource definition file, load the IMS database, and import IMS transactions. These three procedures are required to successfully run and interact with an IMS application on Enterprise Server.

Register the Resource Definition File

IMS supports two transactions named /CICS and /IMS respectively. They are defined in a provided resource definition file, dfhdrdat. When you register this resource definition file, it enables your enterprise server region to switch back and forth between CICS and IMS modes. This is required to run the MFDEMO application.

In general, we recommend that you leave the provided dfhdrdat file intact in its default location, and copy a new instance of the file into each project that requires it.

  1. Copy the default resource definition file installed with Enterprise Developer, dfhdrdat, from its installation directory to your project's system directory. The default installation directory for dfhdrdat is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas.
  2. At an Enterprise Developer command prompt, change to your project's system directory.
  3. Enter the following command:
    caspcupg /dp=.

Load the IMS database

  1. In the Application Explorer view, right-click DEMO03DD.DBD; then select Database Utilities > Load.

    This starts the Load IMS Database window.

  2. In the Input/Output file name field, type DEMO03DD.DBU; then click OK.
  3. View the Console view for confirmation of the load.

Import IMS transactions

When you migrate an IMS application from the mainframe to Enterprise Developer, one of the required mainframe files is the stage 1 file containing your IMS transactions. In this demonstration, we have downloaded the MFDEMO stage 1 file for you, and then exported its contents to a flat text file, trancode.txt, which is part of your project. You need to import this flat text file into the standard data file used by Enterprise Server, named imsgen2.dat. You do this by running the mfims stage1imp command as follows:

  1. In the Application Explorer view, right-click the TRANCODE.TXT file, select Move and then select the loadlib subfolder and click OK.
  2. At your Enterprise Developer command prompt, change to your project's loadlib directory.
  3. Enter the following command:
    mfims stage1imp trancode.txt

    This command creates or updates the imsgen2.dat file in your project's loadlib directory.

Parent topic: Tutorial: IMS Support
Previous topic: Create and Configure a Project
Next topic: Create and Configure an IMS Enterprise Server
Related concepts
Tutorial: IMS Segment Layout Editor


Create and Configure an IMS Enterprise Server

Create and configure an enterprise server region on which to run the MFDEMO IMS application.

Create an IMS enterprise server region

We provide a template that you can use to create an MSS- and IMS-enabled enterprise server region configured with the most common features required to run an IMS application or service.

  1. In Eclipse, open the Server Explorer.

    If it is hidden, display it by choosing Window > Show View > Server Explorer.

  2. Right-click Local [localhost:86], and click New > Enterprise Server
  3. Type IMSDEMO into the Name field.
  4. Leave the 64-bit box unchecked.
  5. Click the Browse button associated with the Template field.

    By default, this opens to the location of the Enterprise Server template files.

    Note: The default location for Enterprise Server templates is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates. If necessary, browse to this location.
  6. Double-click IMSTemplate.xml to select it.
  7. In the Associate with projects field, check the entry that matches your project name.
  8. Click Finish.

Start Enterprise Server Administration

  • In Server Explorer, right-click Local [localhost:86]; then click Open Administration Page.

Configure IMSDEMO

An enterprise server region created using the IMSTemplate template, as has been done for IMSDEMO, is pre-configured with the most common settings used to run IMS applications. Most of the fields and controls cited in this section have been populated with default settings. Most paths are represented by a variable that starts with a dollar sign ($). These are Enterprise Server environment variables, each resolving to a path derived from your IMSTutorial project properties. Because you set your project properties to use the loadlib project folder for all output, each of these variables that point to an output folder resolve to your project's loadlib directory. Later in the tutorial, you can look at the configuration settings to see the actual value of each variable.

Tip: For a description of each field and control on any page of Enterprise Server Administration, click the This Page link in the Help group near the bottom of the sidebar.
Edit the IMSDEMO region
  • In Enterprise Server Administration, click the Edit button that corresponds to the IMSDEMO entry in the list of servers.

    By default, this action opens the following hierarchy of tabs for editing: Server, Properties, and General.

Set general settings
  1. Verify that Allow Dynamic Debugging is checked.
  2. In the Description field, type IMS Tutorial.
  3. Click Apply.
Verify and set IMS general settings
  1. Click the Server, Properties, MSS, IMS, and General tabs.
  2. Verify the following:
    IMS enabled | checked
    Codeset bias | ASCII
    ACB file directory | $IDE_IMSGENPATH
  3. In the Gen file directory field, replace the value with $IDE_LOADLIB.
  4. Click Apply.
Verify general transaction manager settings
  1. Click the Server, Properties, MSS, IMS, TM, and General tabs.
  2. Verify the following:
    MFS path | $IDE_MODPATH
    Application path | $IDE_LOADLIB
  3. Click Apply.
Verify the automatic message processing region
To run an IMS application in an enterprise server region, you need at least one specialized service execution process (SEP) called a message processing region (MPR). To specify that a message processing region starts each time an enterprise server starts, it must be included in a resource group that is specified by the startup list in the SIT used by the enterprise server.
  1. Click the Server, Properties, MSS, IMS, TM, and MPRs tabs.
  2. Verify the following:
    Name | MPR01
    Transaction Class | 001
    Description | MPR for class 1
Verify the database path
  1. Click the Server, Properties, MSS, IMS, DB, and General tabs.
  2. Verify that Database path is set to $IDE_IMSDATA.
Define resources
The resource definition file that you registered previously in this tutorial enables you to switch back and forth between CICS and IMS modes. The configuration settings for this and the system initialization table (SIT) used with IMS are on the CICS tab associated with mainframe subsystem configuration.
  1. Click the Server, Properties, MSS, and CICS tabs.
  2. Verify the following:
    System Initialization Table | IMSSIT
    Transaction Path | $IDE_LOADLIB
  3. In the Resource Definition File Path field, type the full path to your project's system directory.
  4. Click Apply.
  5. On the sidebar, click Home to return to the Enterprise Server Administration Home page.
Configure the TN3270 listener

You need to specify a communications port to be used by the TN3270 listener to accept incoming client requests.

  1. In the Communications Processes column for the list of servers, click the Details button that corresponds to the IMSDEMO entry.
  2. Click the Edit button that corresponds to TN3270.
  3. Change the contents of the Endpoint Address field to *:9004.
  4. Click OK.
  5. On the sidebar, click Home to return to the Enterprise Server Administration Home page.

Start IMSDEMO

  1. On the Server Explorer, expand Local [localhost:86] to see a list of available enterprise server regions.
  2. Right-click IMSDEMO; then select Start from the context menu.
    Note: The first time you start the IMSDEMO region, the Enterprise Server Sign On dialog box prompts you to enter connection details. Because the server is not secured, just click OK to continue.

    The Console view shows the progress of the Start command.

View environment variable values

Enterprise Server provides a utility, ES Monitor & Control (ESMAC), that enables you to see the full configuration for your enterprise server region. Here you access ESMAC to view the values for the environment variables specified in your configuration. Each environment variable set in your configuration resolves to the corresponding value represented in ESMAC.

  1. Once IMSDEMO has started, return to the Enterprise Server Administration Home page.
  2. Click the Details button in the Status column for the IMSDEMO enterprise server region.
  3. Click ES Monitor & Control.
  4. On the sidebar menu click Env. Vars.
  5. Scroll down the list of environment variables, and note the values for all variables that begin with IDE.
  6. When you are finished, close the Enterprise Server Administration tab in Eclipse.
Note: If you intend to complete the remainder of this tutorial during your current session, keep IMSDEMO in its Started state in preparation for running the MFDEMO application as outlined in the next topic.
Parent topic: Tutorial: IMS Support
Previous topic: Configure IMS
Next topic: Run MFDEMO


Run MFDEMO

Use the Rumba TN3270 emulator to run the MFDEMO application on the IMSDEMO enterprise server region.

With the IMSDEMO enterprise server region started in Enterprise Server (see the Start IMSDEMO section in the previous topic), you can now run the MFDEMO application from the Rumba TN3270 mainframe display, and add data to the IMS database.

The installation of Enterprise Developer includes the Micro Focus Rumba emulator. The Rumba TN3270 Mainframe Display is embedded within Enterprise Developer. As part of this tutorial, you use the embedded Rumba display to run the application.

Configure the TN3270 settings in Enterprise Developer

Here, you check your Enterprise Developer options and ensure that the embedded Rumba display is selected:

  1. In the IDE, click Window > Preferences.
  2. Expand Micro Focus > Enterprise Server, and click TN3270.
  3. Ensure that Enable display, Rumba (Embedded) and Connect automatically are all selected.
  4. Click Apply and Close.

Start the Rumba Mainframe Display View

  • In Server Explorer, right-click IMSDEMO; then select Show TN3270 Display.

    This opens the Rumba Mainframe Display view and connects Rumba to the IMSDEMO enterprise server using a TN3270 connection. You can see the login page of the IMSDEMO application.

    Note: If the Rumba Mainframe Display view does not connect automatically, click [image] (Connect).

Start the MFDEMO Application

Note: Before interacting with the Rumba display, be sure that Enterprise Server Administration is not open in an Enterprise Developer tab.
  1. On the IMS sign-on screen, type SYSAD into both the USERID and PASSWORD fields using the Tab key to move from one to the other; then press Enter.
  2. Press Ctrl+Shift+Z to clear the Rumba Mainframe Display screen.
  3. Enter MFDEMO with a trailing space.

    Rumba shows the MFDEMO initial menu screen, DEMO91.

Add Data

In the sections that follow, each set of instructions includes a screen shot showing the terminal emulator with required fields in green and red.

Tip: To navigate between fields on a terminal emulator screen, press Tab to move to the next field, and Shift+Tab to move to the previous field.
Create a TESTDEPT table
  1. In the FUNCTION CODE field, type A to select the <A>DD function.

    This action advances your cursor to the TABLE-ID field.

  2. In the TABLE-ID field, type TESTDEPT.
    Add table in the IMS application
  3. Press Enter.

    This action advances you to the DEMO92 input screen.

Input records
  1. Complete the following fields as indicated:
    DESCRIPTION | A TABLE OF TEST DEPARTMENTS
    NUMBER OF CHARACTERS IN ELEMENT KEY | 20
    NUMBER OF CHARACTERS IN ELEMENT | 50
    PASSWORD PROTECT | N
  2. Tab to the first entry field under ELEMENT KEY; then add the following records:
    ELEMENT KEY | ELEMENT VALUE/DESCRIPTION
    123 | DEPARTMENT 123
    234 | DEPARTMENT 234
  3. Tab to the RETURN field; then type X.
    Add Testept Elements
  4. Press Enter to return to the main menu.
Add an additional record
  1. In the FUNCTION CODE field, type C to select the <C>HANGE function.

    This action advances your cursor to the TABLE-ID field.

  2. In the TABLE-ID field, type TESTDEPT.
    Change Testdept Table
  3. Press Enter.

    This action advances you to the DEMO92 input screen.

  4. Tab to the first field in the third row under FUNC; then add the following record:
    FUNC | ELEMENT KEY | ELEMENT VALUE/DESCRIPTION
    A | 345 | DEPARTMENT 345
  5. Tab to the RETURN field; then type X.
    Add Testept Elements
  6. Press Enter to return to the main menu.
Add the TESTERS table and records
  1. Using the same methods as you did to create the TESTDEPT table and add records, add the TESTERS table using these values:
    DESCRIPTION | A TABLE OF TESTERS
    NUMBER OF CHARACTERS IN ELEMENT KEY | 20
    NUMBER OF CHARACTERS IN ELEMENT | 50
    PASSWORD PROTECT | N
  2. Then add the following records:
    ELEMENT KEY | ELEMENT VALUE/DESCRIPTION
    JOHN SMITH | IMS DC TEST TECHNICIAN
    JANE JONES | IMS DB TEST TECHNICIAN

    Add Testers Elements
  3. Press Enter to return to the main menu.
Exit MFDEMO
  1. On the main menu, type E into the FUNCTION CODE field; then press Enter.

    This action takes you to the TRANCODE - MFDEMO - ENDED screen.

    MFDEMO - ENDED
  2. Disconnect from the TN3270 display. To do this in Rumba, click Disconnect on the toolbar [image].
Parent topic: Tutorial: IMS Support
Previous topic: Create and Configure an IMS Enterprise Server
Next topic: Debug MFDEMO
Related concepts
Running Applications in a TN3270 Mainframe Display


Debug MFDEMO

Debugging requires that your project is associated with the IMSDEMO enterprise server and that IMSDEMO is configured to use dynamic debugging. Both of these requirements were met earlier in this tutorial.

Set Breakpoints

  1. In the Application Explorer view, expand the IMSTutorial project; then double-click DEMO001T.cbl to start the COBOL editor.
  2. Scroll down to line number 551 and set a breakpoint. The code on line 551 is:
     IF DEMO91-FUNCTION = 'I' OR 'i'
    Note:
    • To enable line numbers in the editor, click Window > Preferences, expand General > Editors. On the Test Editors page, check Show line numbers and click OK.
    • To set a breakpoint, on the line of code where you want to break, put your cursor in the far left column and double-click.

Set Debug Properties

  1. In the Application Explorer view, right-click DEMO001T.cbl; then select Properties.
  2. In the left pane, click COBOL.
  3. In the right pane, check Enable file specific settings.
  4. Check Compile for debugging; then click OK.

Create a Debug Launch Configuration

  1. In the Application Explorer view, click the IMSTutorial project to select it.
  2. From the main menu, click Run > Debug Configurations.
  3. On the tree view, click COBOL Application.
  4. On the Debug Configurations toolbar, click New launch configuration New launch configuration.
  5. In the Name field, type COBOL_IMS_Tutorial.
  6. On the General tab, expand Main Program.
  7. If checked, uncheck Program is part of project build configuration.
  8. Click the Browse button under Main Program.
  9. Browse to and select the DEMO001T.dll file located in your project's loadlib folder.
  10. Click Apply and then Close to apply changes and close the Debug Configurations dialog box.

Start Debugging

  1. From the Eclipse menu, click Run > Debug As > IMS on COBOL Enterprise Server. Enterprise Developer:
    • Builds the project.
    • If stopped, starts the IMSDEMO enterprise server region. If prompted, click OK.
    • Opens the debugger.
  2. In Server Explorer, right-click IMSDEMO; then select Show TN3270 Display.
    Note: If the Rumba Mainframe Display view does not connect automatically, click [image] (Connect) in the Rumba Mainframe Display view.
  3. In the terminal emulator, log into IMS and start MFDEMO just as you did to run the MFDEMO application as described in the previous topic.

    In Enterprise Developer, the debugger shows the current line of code execution:

    IMS Debug
  4. On the Enterprise Developer toolbar, click Resume (Resume).

    This transfers control back to the terminal emulator and advances the application to its main menu.

  5. On the main menu in the terminal emulator, type I into the FUNCTION CODE field to select the <I>NQUIRE function.

    This action advances your cursor to the TABLE-ID field.

  6. In the TABLE-ID field, type TESTDEPT; then press Enter.

    The application advances to the details screen and shows the contents of the TESTDEPT table.

  7. On the Enterprise Developer toolbar, click Resume (Resume).

    The debugger advances to your breakpoint. From here you can continue debugging if desired. When you have finished, continue with the next step from whatever screen you are on.

  8. Tab to the RETURN field.
  9. Type X; then press Enter.
  10. On the main menu, type E into the FUNCTION CODE field; then press Enter.

    This action takes you to the TRANCODE - MFDEMO - ENDED screen.

Stop Debugging

  1. From the Rumba Mainframe TN3270 Display toolbar, click [image] (Disconnect); then close Rumba.
  2. In Enterprise Developer, click Terminate (Terminate).
Parent topic: Tutorial: IMS Support
Previous topic: Run MFDEMO
Related concepts
Running Applications in a TN3270 Mainframe Display


Tutorials: IMS Data Tools

  • Tutorial: IMS Segment Layout Editor
    Walks you through the process of using the IMS Segment Layout Editor to create COBOL layouts for an IMS database.
  • Tutorial: IMS Database Editor
    Walks you through several features of the IMS Database Editor, including browsing the database, adding, modifying, and deleting a record, searching the database, adding and finding a segment bookmark, and setting up an SSA.
Parent topic: Tutorials: IMS


Tutorial: IMS Segment Layout Editor

Walks you through the process of using the IMS Segment Layout Editor to create COBOL layouts for an IMS database.

The IMS demonstration database used in this tutorial contains data for which you create segment layouts using the Segment Layout Editor. Data formatted in the segments created here are then viewed and edited in the Tutorial: IMS Database Editor topic.

Prerequisites

This tutorial uses the same project used in Tutorial: IMS Support. If you have already completed Tutorial: IMS Support, nothing further is required. However, if you have not completed Tutorial: IMS Support, complete all steps included in the Create and Configure a Project topic, and all steps in the Load the Database section of the Configure IMS topic before proceeding.

Create a Default Segment Layout

You can define one default segment layout for each segment type. You can also define one or more conditional segment layouts for the same segment type. The IMS Database Editor uses the default segment layout to format data for those segment occurrences that do not match any of the conditional segment layouts.

Create a default segment layout for DEMOHDRS
  1. In the Eclipse Project Explorer, expand IMSTutorial > COBOL Programs.
  2. Right-click DEMO00I1.CBL; then select Create Segment Layout File from the context menu.

    The Segment Layout Editor extracts the COBOL layout information from the selected COBOL file's corresponding debug information (.idy) file.

    The New IMS Layout dialog box opens and displays a list of IMS databases. Here, you select the IMS database for which you want to create segment layouts.

  3. As the demo database DEMO03DD is the only database listed, click Create.

    The Segment Layout Editor opens. The left pane of the Segment Layout Editor window displays the Data Division of demo00I1.idy. The right pane is empty because, as yet, you have no segment layouts defined.

    In the next step, you select the DEMOHDRS COBOL layout and apply it to the DEMOHDRS segment type in the DEMO03DD database. Here, the layout and the segment type share the same name (DEMOHDRS), but the two names can be different.

  4. Drag 01 DEMOHDRS from the left pane of the window across to the right pane.
    Note: 01 DEMOHDRS is located near the bottom of the WORKING-STORAGE SECTION list, so you might need to resize the Segment Layout Editor, or scroll down the list to see it.

    This action invokes the New Segment Layout Wizard where you can create a default segment layout for DEMOHDRS based on the 01 DEMOHDRS COBOL layout that you have just dropped into the right pane.

  5. Select the DEMOHDRS segment name; then click Next.
  6. As Default Layout is already selected, click Next.
  7. Click Finish.

    The wizard adds the layout you have just defined for DEMOHDRS to the right pane of the window. As this is the default layout for the segment type DEMOHDRS, the word "DEFAULT" is appended to the segment-name DEMOHDRS.

  8. Click [image] next to DEMOHDRS-DEFAULT.
  9. Click [image] next to 01 DEMOHDRS.

    The COBOL layout starts to expand.

  10. Click [image] against each group item until you can see the entire COBOL layout.
Save the segment layout
Here you name the segment file to match the database file, and save it in the loadlib project subfolder.
  1. Click Save ( [image]).
  2. Browse to the loadlib subfolder of your IMSTutorial project.
  3. In the File name field, type DEMO03DD.
  4. Click Save.
  5. Click the x [image] icon on the Micro Focus Data File Tools window to close it.

View the Segment Layout

In this section, you view the new DEMOHDRS-DEFAULT segment layout in the IMS DB Editor. Because you have defined this segment layout, when you open the IMS Database Editor, the DEMOHDRS-DEFAULT layout loads automatically and the data for the DEMOHDRS segment is formatted. This means that from this point on, you can view and edit formatted data in DEMOHDRS segment occurrences.

Start the IMS Database Editor
  1. In the Solution Explorer, right-click the DEMO03DD DBD file; then select Edit Database from the context menu.

    This starts the IMS Database Editor, showing formatted data for the DEMOHDRS segment in the right pane. The key fields are highlighted in red.

Advance to the next segment
  • On the tool bar, click [image] twice to move to the next segment occurrence, which belongs to segment type DEMOELES.

    Because you have not yet defined a segment layout for DEMOELES, the Field Layout View in the right pane empties. The next thing to do, therefore, is to return to the Segment Layout Editor and define a default layout for the DEMOELES segment.

Close Micro Focus Data File Tools
  • From the Micro Focus Data File Tools menu, click File > Exit to close the window.

Create a Second Default Segment Layout

To create a default segment layout for DEMOELES, you edit the DEMO03DD.SLF segment layout file and add a second segment layout to it.

Open the Segment Layout File
  1. In the Project Explorer, right-click DEMO00I1.CBL; then select Create Segment Layout File from the context menu.
  2. As the demo database DEMO03DD is the only database listed, click Create.
  3. Click File > Open.
  4. If not already in the loadlib project subfolder, browse to it.
  5. From the Files of type drop-down list, select All Files (*.*).
  6. Double-click DEMO03DD.SLF.
  7. Click Yes at the prompt.
Load program information
  1. Right-click DEMOHDRS-DEFAULT; then select Load program information from the context menu.
  2. Double-click DEMO00IT.idy.
Create a default segment layout for DEMOELES
  1. Drag 01 DEMOELES from the left pane of the window across to the right pane.
  2. Select the DEMOELES segment name; then click Next.
  3. As Default Layout is already selected, click Next.
  4. Click Finish.

    The wizard adds the layout you have just defined for DEMOELES to the right pane of the window. As this is the default layout for the segment type DEMOELES, the word "DEFAULT" is appended to the segment-name DEMOELES.

  5. Click [image] (Save) to save the new segment in DEMO03DD.SLF.

Create a Conditional Segment Layout

So far, you have created a default segment layout for each of the segment types DEMOHDRS and DEMOELES. You can create additional segment layouts for these segment types and specify the conditions under which those layouts should be used. These other layouts are referred to as conditional segment layouts.

You are going to create a conditional segment layout with a test field for the DEMOELES segment type. The test field determines which DEMOELES segment occurrences use the conditional layout rather than the default layout.

The demo Data Division has only one layout that is suitable for formatting data for DEMOELES segment occurrences. For the purposes of demonstrating conditional segment layouts only, you use this layout again to create a conditional layout for DEMOELES.

  1. Drag 01 DEMOELES from the left pane of the window across to the right pane.
  2. Select the DEMOELES segment name; then click Next.
  3. As Conditional Layout is already selected, click Next.
  4. Click Finish.

    The Segment Layout Editor window now includes the new conditional segment layout for DEMOELES in the right pane.

    As this is not a default layout, the name of the layout is appended by the name of the layout in the COBOL source file. The segment type in the IMS database and the COBOL source layout share the same name which is DEMOELES. Therefore, the new conditional segment layout is named DEMOELES-DEMOELES.

Define a Test for the Conditional Segment Layout

The test field is the field for which you want to set up a condition. To define a test, you need to expand the segment layout DEMOELES-DEMOELES in the right pane and expose the test field.

  1. Expand the conditional segment layout DEMOELES-DEMOELES in the right pane by clicking [image] until you can see the test field 03 FILLER PIC X(133). This test field is under the group item 02 DEMOELES-ELE-DATA.
  2. Right-click 03 FILLER PIC X(133); then select Properties from the context menu.
  3. From the IF drop-down list, select IS = TO.
  4. In the box to the right of the IF list box, type IMS DC TEST TECHNICIAN.

    Whatever you type in here is used by the IMS Database Editor when deciding which segment layouts to apply to which segment occurrences.

    If you had selected a condition that required two values, you would also type in a second value into the box on the far right.

  5. Click OK.

    In the right pane, the Segment Layout Editor window displays [image] next to the test field.

  6. Click [image] (Save) to save the conditional segment in DEMO03DD.SLF.
  7. Close the Micro Focus Data File Tools window.
Parent topic: Tutorials: IMS Data Tools
Related concepts
Tutorial: IMS Support
Create and Configure a Project
Configure IMS
Tutorial: IMS Database Editor


Tutorial: IMS Database Editor

Walks you through several features of the IMS Database Editor, including browsing the database, adding, modifying, and deleting a record, searching the database, adding and finding a segment bookmark, and setting up an SSA.

Prerequisites

This tutorial uses the three segment layouts created in Tutorial: IMS Segment Layout Editor. If you have not already run that tutorial, you must do so before proceeding.

Get Familiar with the IMS Database Editor

Start the IMS Database Editor
Here you start the IMS Database Editor, which shows formatted data for the first of two default segment layouts you created in the previous tutorial, with the key fields highlighted in red.
  1. In the Project Explorer, expand IMSTutorial > DBD Files.
  2. Right-click the DEMO03DD DBD file; then select Open With > IMS Database Editor from the context menu.
Note: If the right pane is obscured, reveal it by dragging the vertical bar located at the far right of the window leftwards across the window. Similarly, if the Tree view is obscured, drag the bottom of the DBD window downwards to reveal it.
Explore the IMS Database Editor Window
All of the components of the IMS Database Editor main window are shown and described in the topic IMS Database Editor window. Study that topic to become familiar with each component and the functionality it provides.
Browse Through Segment Occurrences
To browse through segment occurrences from your current database position to the end of the database:
  1. To make sure you are positioned at the start of the database, click [image] on the IMS Database Editor toolbar.

    The Current Segment Arrow [image] is pointing to DEMOHDRS.

  2. Right-click in the Tree view and select Start browse from the context menu.

    A Browse window opens in the left pane, showing a list of segment occurrences starting from your current position at the start of the database. In the right pane, the Field Layout View shows formatted data.

  3. In the left pane, where the Field Layout View shows formatted data for the Test Department, click JANE JONES.

    The right pane updates to show formatted data for Jane Jones.

    Note: When you double-click a segment occurrence in the Browse window, you change your current position in the database to that segment occurrence.
  4. Double-click JANE JONES.

    The Browse window closes. In the Tree view, the Current Segment Arrow ( [image]) has moved to DEMOELES.

Add a Twin Segment Occurrence

At present, the database has only one record, which consists of the Test Department and two Test Technicians. Here you add a new DEMOHDRS segment occurrence for the Development Department. This new DEMOHDRS segment occurrence is a twin of the Test Department TESTDEPT segment occurrence:

  1. Click [image] on the IMS Database Editor toolbar to move to the start of the database.

    You are now positioned at the start of the database on the first segment occurrence, TESTDEPT.

  2. In the right pane of the window, look for DEMOHDRS-KEY in the Field Name column. Click inside this row in the Value column.

    The field DEMOHDRS-KEY is now open for editing. Currently, the value shown is TESTDEPT.

  3. Change TESTDEPT to DEVDEPT.

    As you begin to edit, an update warning appears.

  4. Check Switch update warning off; then click Yes and complete the change.

    The update warning is disabled for the rest of the editing session.

  5. Press Enter to add the edit to the segment buffer.
  6. Click inside the Value column for the 03 FILLER item, located below 02 DEMOHDRS-TABLE-DESCRIPTOR.
  7. Replace the current text with A TABLE OF SOFTWARE DEVELOPERS; then press Enter to add the edit to the segment buffer.
  8. Click [image] on the IMS Database Editor toolbar.

    This inserts a new DEMOHDRS segment occurrence for the Development Department.

Add the First Child Segment Occurrence

The next thing to do is add the first DEMOELES child for the Development Department:

  1. In the left pane of the window, click DEMOELES in the tree view.

    The data empties from the Field Layout View and the Segment Data and Field Data areas. The Field Layout View adopts the default segment layout you created for DEMOELES.

  2. Click Edit > IMS DB Editor > Initialize Segment.

    When you initialize a segment occurrence, alphanumeric fields are initialized to spaces and numeric fields are initialized to zeros.

  3. In the right pane of the window, click inside the Value column that corresponds to 03 DEMOELES-KEY in the Field Name column.
  4. Type HELEN PARRY; then press Enter to add the edit to the segment buffer.
  5. Click [image] on the IMS Database Editor toolbar.

    This inserts the first child DEMOELES segment occurrence for the Development Department.

Modify a Segment Occurrence

To edit the data in a segment occurrence:

  1. On the IMS Database Editor toolbar, click [image] two times.

    This positions you at the DEMOELES segment occurrence for FRED SMITH.

  2. In the right pane of the window, click inside the Value column on the row that shows 03 FILLER PIC X (133).
  3. Replace the existing text with IMS DC TEST LEAD; then and press Enter.
  4. Click [image] on the IMS Database Editor toolbar.

    The segment occurrence for FRED SMITH is updated.

Delete a Segment Occurrence

To delete a segment occurrence:

  1. To select the next segment occurrence, click [image] on the IMS Database Editor toolbar.

    This positions you at the DEMOELES segment occurrence for JANE JONES.

  2. Click [image] on the IMS Database Editor toolbar.

    A warning message appears.

  3. Click Yes to delete the segment occurrence for JANE JONES.

    As this is the last segment in the database, a message asking if you want to reset your position to the start of the database is displayed.

  4. Click Yes to return to the start of the database.

Search the Database

To open the IMS Database Find bar and locate a search string:

  1. From the Micro Focus Data File Tools menu, click Search > IMS DB Editor > Find.
  2. On the IMS Database Find bar, uncheck Match case, if it is not already unchecked.
  3. In the Find field, type in the word Table.
  4. From the End drop-down list, select at end of database.
  5. Click Find.

    The IMS Database Editor searches the database from your current position at the start of the database. In the Segment Data area in the left pane of the IMS Database Editor Window, you can see that the cursor is positioned at the start of the first occurrence of the string TABLE. If you look at the Field Layout View, you can see that this is in the segment occurrence for A TABLE OF SOFTWARE DEVELOPERS.

  6. Click Find again.

    The Segment Data area displays the second occurrence of TABLE. In the Field Layout View, you can see that this is in the segment occurrence for A TABLE OF SOFTWARE TESTERS.

  7. Click Find again.

    As there are no more occurrences of the word Table in the database, a prompt appears indicating that no more occurrences could be found.

  8. Click OK.
  9. To close the IMS Database Find bar, click the Close button [image] in the top right of the window.

    Whether a search operation fails or succeeds, your current position in the database changes to the last segment searched.

  10. Click [image] on the IMS Database Editor toolbar to move to the start of the database.

Add and Find a Bookmark

With the IMS Database Editor, you can navigate your way forwards but not backwards through the database. To help you, the IMS Database Editor provides a bookmarking utility so that you can mark any segment occurrences that you want to go back to. This saves you from having to issue a number of DL/I calls to position yourself at that segment occurrence again.

Add a bookmark
To add a bookmark in the database:
  1. Click [image] to position yourself at the DEMOELES segment occurrence for HELEN PARRY.
  2. Right-click inside the tree view and click Add Bookmark on the popup menu.
  3. In the text field on the Add bookmark dialog box, type First developer segment; then click OK.
  4. On the IMS Database Editor toolbar, click [image] to select the next segment.

    As there is only one developer in the Table of Developers, this takes you to the next DEMOHDRS segment occurrence which is the Table of Software Testers.

Find a Bookmark
Now suppose that you want to jump back to the segment occurrence for HELEN PARRY. If this was a large database, it could take some time to go to the end of the database and work your way through from the start. However, because you inserted a bookmark at the first developer occurrence, you can use the bookmark to move directly there.
  1. Right-click inside the tree view and click Goto Bookmark on the popup menu.
  2. On the Bookmarks dialog box, click on the DEMOELES bookmark and then click Goto bookmark.

    This repositions you back at the segment occurrence for HELEN PARRY.

Set up an SSA

The IMS Database Editor can store the SSAs that you create for up to the last ten databases edited. To define an SSA:

  1. Click [image] on the IMS Database Editor toolbar to move to the start of the database.

    This positions you at the top of the first DEMOHDRS segment occurrence which is the Table of Software Developers.

    On the SSA List, the SSA column for the DEMOHDRS segment shows None, indicating that DEMOHDRS has no SSAs.

  2. On the SSA list, double-click the DEMOHDRS segment.
  3. On the Define SSA dialog box, click Unqualified SSA for DEMOHDRS; then click OK.

    On the SSA list, the SSA column changes to DEMOHDRS*-.

  4. Click [image] on the IMS Database Editor toolbar.

    Because you just defined an unqualified SSA, Get Next With Hold ( [image]) returns another DEMOHDRS segment rather than the next DEMOELES segment.

  5. Click [image] on the IMS Database Editor toolbar.

    As there are no more DEMOHDRS segments, a message prompt appears, indicating that you have reached the end of database.

  6. Click Yes to reset to the start of the database.
  7. On the SSA list, double-click on DEMOHDRS.
  8. On the Define SSA dialog box, click No SSA and click OK.

    This removes the unqualified SSA from DEMOHDRS. On the SSA list, the SSA column now shows None.

Close the Database and Data File Tools

To close the database and Micro Focus Data File Tools:

  • Click File > Exit.
Parent topic: Tutorials: IMS Data Tools
Related concepts
Tutorial: IMS Segment Layout Editor
Related reference
IMS Database Editor window


Tutorial: JCL

JCL applications written to run on a z/OS or VSE mainframe can be run with the Enterprise Server environment. In this tutorial, you will use your IDE to create a JES-enabled enterprise server and a JCL application project. After the two components are associated with each other, you can submit a JCL job to run the application, and then view its progress and results in the spool queues and catalog, all from within the IDE.

  1. Configure an Enterprise Server for JCL Support
    Create and configure an enterprise server that is JES-enabled, which will allow you to submit and run JCL jobs.
  2. Create and Build a JCL Application
    Create a native mainframe COBOL project comprising all the components required to run a JCL application, such as the COBOL source programs and a JCL batch file. Then, associate the project with the enterprise server region that you previously created and configured.
  3. Submit and Run a JCL Job
    Submit the JCL job to the associated enterprise server region.
  4. View the Spool Queues
    From within the IDE, you can view your job in the JES spool queues on the enterprise server.
  5. View the Catalog
    From within the IDE, you can view the resulting data set in the catalog of the enterprise server region.
  6. Debug Dynamically under Enterprise Server
    From within the IDE, you can debug the COBOL program as it runs on the enterprise server.
Parent topic: Mainframe Tutorials


Configure an Enterprise Server for JCL Support

To enable JCL support for an enterprise server, you need to perform the following tasks:

  1. Create an MSS-enabled Enterprise Server
  2. Edit the MSS-enabled Enterprise Server
  3. Configure JES Support
  4. Configure the Program Paths
  5. Define a Batch Initiator SEP
Parent topic: Tutorial: JCL
Next topic: Create and Build a JCL Application


Create an MSS-enabled Enterprise Server

To create an MSS-enabled enterprise server:

  1. Launch Eclipse using the workspace c:\tutorials.
  2. If this is the first time that you start Eclipse, you are presented with the Welcome page. Click Open Team Developer Perspective.
  3. Open the Server Explorer tabbed view.

    If it is hidden, display it by choosing Window > Show View > Server Explorer.

  4. Right-click Local [localhost:86], and click New > Enterprise Server.
    Tip: If you are not currently signed on to the current enterprise server, the Enterprise Server Sign On dialog box appears: click OK to sign on as the SYSAD user. (Alternatively, click Use specific server credentials, then enter a valid username and password.)

    The New Enterprise Server dialog box appears.

  5. Type JCLDEMO in the Name field.
  6. If you plan to create a 64-bit JCL application, check the 64-bit box, otherwise leave it unchecked.
  7. Click the browse button next to the Template field.

    This opens the location of the Enterprise Developer server templates, which is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates by default.

  8. Select JCLTemplate.xml, and click Open.
  9. Click Finish.

    In Server Explorer, expand Local [localhost:86] to check to see that the server has been added. By using the template, the server already has the necessary options selected for MSS enablement.

Parent topic: Configure an Enterprise Server for JCL Support
Next topic: Edit the MSS-enabled Enterprise Server


Edit the MSS-enabled Enterprise Server

  1. In Server Explorer, right-click Local [localhost:86] and choose Open Administration Page from the context menu.

    The Enterprise Server Administration page appears.

  2. Click Edit on the row for JCLDEMO.

    This opens the Server > Properties > General page.

    It is useful to have the character-mode console daemon window showing when the JCLDEMO region is running.

  3. To set the console daemon to show when the region is running, on the Server > Properties > General page, check Show Local Console.
  4. In the Configuration Information field type the following to create an environment variable for the path to the project directory:
    [ES-Environment]
JCLPROJ=c:\tutorials\jcl

    This is the location where the project required for this tutorial is created in a later procedure.

  5. Click OK.
Parent topic: Configure an Enterprise Server for JCL Support
Previous topic: Create an MSS-enabled Enterprise Server
Next topic: Configure JES Support


Configure JES Support

To configure the JES support for the enterprise server:

  1. On the Enterprise Server Administration page, click Edit next to the JCLDEMO row in the table of servers.

    This opens the Server > Properties > General page.

  2. Select the MSS tab and then the JES tab.
  3. If not already checked, check Job Entry Subsystem enabled.
    Note: This should already be selected, because you used the JCL template to create the enterprise server.

    Don't click Apply yet — there is more to do on this page.

Parent topic: Configure an Enterprise Server for JCL Support
Previous topic: Edit the MSS-enabled Enterprise Server
Next topic: Configure the Program Paths


Configure the Program Paths

You need to specify the directories and other details needed for the enterprise server to find deployed programs. To do this:

  1. From the JES > General tab, enter the following values into the following fields. (The paths you enter here point to your project directories.)
    Field Value to enter: Details
    JES Program Path | $JCLPROJ\New_Configuration.bin | Path for the directory containing executable files to be run by your JCL jobs. This is the output build path of your project that contains the .dll and .idy files.
    System Catalog $JCLPROJ\catalog\catalog.dat Path and name of the system catalog. This is a file that holds the details of data files, their attributes and locations.
    Note: The catalog directory is created later in the tutorial.
    Default Allocated Dataset Location $JCLPROJ\catalog\datasets The default path for the directory where new data sets are to be created if you do not specify a directory.
    Note: The catalog directory is created later in the tutorial.
    System Procedure Library | SYS1.PROCLIB | Set of cataloged PDS data set names that will be searched to resolve JCL procedure names.
  2. Click Apply.
  3. Click Home to display the Enterprise Server Administration page.
Parent topic: Configure an Enterprise Server for JCL Support
Previous topic: Configure JES Support
Next topic: Define a Batch Initiator SEP


Define a Batch Initiator SEP

JCL execution uses the following types of Service Execution Processes (SEPs):

  • Batch initiator (often abbreviated to simply "initiator") — for running JCL jobs
  • Batch printer SEP (often abbreviated to simply "printer") — for sending the output from a JCL job to a printer

You can define initiators and printers to start up automatically whenever the enterprise server region is started, and you can also create ones that last only for the current session.

The JCL template that you used to create an enterprise server includes a default initiator named INITALL. You need to modify INITALL for your application.

To modify INITALL to be a class be initiator that starts automatically:

  1. On the Enterprise Server Administration home page, click Edit next to JCLDEMO.
  2. Make sure the Server and Properties tabs are selected, and click MSS > JES > Initiators.
  3. Click Edit on the row for INITALL and change the initiator as follows:
    Field | Value | Comment
    Name | INITB | Not case sensitive – gets folded to upper case
    Class | B | Not case sensitive – gets folded to upper case
    Description | Initiator for class B job
  4. Click OK, and then click Home to return to the Enterprise Server Administration home page.

This concludes the configuration of the JES-enabled enterprise server. Next, you need to create and build the JCL application that will run on the enterprise server - see Create and Build a JCL Application.

Parent topic: Configure an Enterprise Server for JCL Support
Previous topic: Configure the Program Paths
Related information
Create and Build a JCL Application


Create and Build a JCL Application

These are the steps required to create a project comprising all the parts of your application, such as the COBOL source and the JCL batch files. You build the demonstration application in Eclipse, and run it on the JCLDEMO enterprise server region, then debug the application in Eclilpse.

  1. Create a Project
  2. Import the Files from the Demonstration Program
  3. Specify the Project Properties
  4. Build the Application
  5. Associate your Project with the JCL Enterprise Server
  6. Start your Enterprise Server
  7. Deploy to Enterprise Server
Parent topic: Tutorial: JCL
Previous topic: Configure an Enterprise Server for JCL Support
Next topic: Submit and Run a JCL Job


Create a Project

To create a native COBOL project to hold the JCL demonstration program:

  1. If you have closed Eclipse, launch it again using the workspace c:\tutorials .

    Make sure that the Team Developer Perspective is the active Eclipse perspective, and that the Enterprise Development Projects application appears in the Application Explorer view; if the Enterprise Development Projects application is not displayed in the Application Explorer view, see the Integrated Enterprise Development Project Application topic for further instructions.

  2. In the Application Explorer view, right-click Enterprise Development Projects and select New COBOL Project > Mainframe COBOL Project.
  3. In the Project name field, type jcl.
  4. In the Select a project template list, select the template with the appropriate bitism: that is, if you created a 32-bit enterprise server region during the earlier steps, select Micro Focus template [32 bit]; if you created a 64-bit enterprise server region, select Micro Focus template [64 bit].
  5. Ensure Use default location is selected.
  6. Click Finish.

    This creates a jcl folder in your workspace that holds your project.

Parent topic: Create and Build a JCL Application
Next topic: Import the Files from the Demonstration Program
Related reference
Integrated Enterprise Development Project Application


Import the Files from the Demonstration Program

To import the files from the JCL demonstration program into your project:

  1. In the Application Explorer view, select your project and select File > Import, then on the Import dialog box, select General > File System, and then click Next.
  2. On the File system screen, click Browse to the right of the From directory field.
  3. Browse to %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\JCL\Classic\jcldemo, then click OK.
  4. Select ESJCL.jcl, JCLCREAT.cbl, and JCLREAD.cbl.
  5. Click Finish.

    The files are added to the project. By default, Eclipse is configured to build the project automatically after any change in the code and this also triggers a build. You can check the Console view to ensure the build was completed successfully.

  6. In the Application Explorer view, right-click the jcl project, choose New > Folder > Folder..., then create a folder called catalog and click Finish.

    Your project requires this folder to submit the JCL successfully.

Parent topic: Create and Build a JCL Application
Previous topic: Create a Project
Next topic: Specify the Project Properties


Specify the Project Properties

To specify the project properties:

  1. In the Application Explorer view, right-click the project and choose Properties.
  2. On the Micro Focus > Project Settings > COBOL page, ensure that Source format is set to Fixed.
  3. Ensure that Language dialect is set to Enterprise COBOL for z/OS.
  4. Set Character set to ASCII.
  5. Click Apply and Close to save the changes in the project properties.
Parent topic: Create and Build a JCL Application
Previous topic: Import the Files from the Demonstration Program
Next topic: Build the Application


Build the Application

Building creates the application's .dll and .idy files in the New_Configuration.bin subfolder of your project.

By default Eclipse builds your project automatically whenever you save a file. If you haven't configured Eclipse to do this, you can build a project at any time by selecting the project, then on the Project menu, select Build Project; you can also select Build All to build all projects in the current workspace, or Build Working Set to build a subset of the projects in the workspace. To turn off automatic building, select Window > Preferences > General > Workspace and clear the Build automatically check box.

Parent topic: Create and Build a JCL Application
Previous topic: Specify the Project Properties
Next topic: Associate your Project with the JCL Enterprise Server


Associate your Project with the JCL Enterprise Server

The IDE enables you to associate your project with an enterprise server. To associate your project with the JCLDEMO enterprise server that you created earlier:

  1. Open Server Explorer.
  2. Right-click JCLDEMO, and click Associate with project > jcl.
Parent topic: Create and Build a JCL Application
Previous topic: Build the Application
Next topic: Start your Enterprise Server


Start your Enterprise Server

You can now start JCLDEMO:

  1. In Server Explorer, right-click JCLDEMO, then choose Start.

    The Enterprise Server Sign On dialog box appears, because it is the first time the server has been started.

  2. Click OK.

    As Store Credentials is selected, this dialog box does not appear next time you start the enterprise server, unless you select the Clear Credentials option, available on the server's right-click menu.

  3. Check the Output window to ensure that the server has started.

    You'll also see the Enterprise Server Console Daemon window outside of the IDE showing the details of the server being started.

Parent topic: Create and Build a JCL Application
Previous topic: Associate your Project with the JCL Enterprise Server
Next topic: Deploy to Enterprise Server


Deploy to Enterprise Server

In fact, deployment of this JCL application is not required! This is because you configured the JES program path to be the New_Configuration.bin sub-directory of your project directory. Using that setting, the enterprise server automatically finds the application files that it needs to run.

Now that the application is compiled, and the associated enterprise server is configured and started, you can submit the JCL job file that starts the application running. To learn how to do this, proceed to Submit and Run a JCL Job.

Parent topic: Create and Build a JCL Application
Previous topic: Start your Enterprise Server
Related information
Submit and Run a JCL Job


Submit and Run a JCL Job

To submit the JCL application to JCLDEMO:

  1. In the Application Explorer view, right-click ESJCL.jcl, and click Submit JCL to associated Server.
    The JCL job performs the following actions:
    • Uses the IDCAMS utility to delete any previous instance of the data set that will be created.
    • Runs a simple COBOL program (JCLCREAT.cbl) that creates and populates a simple data set.
    • Uses the IEBGENER utility to populate a temporary data set.
    • Runs a simple COBOL program (JCLREAD.cbl) to write the contents of the temporary data set to SYSOUT.

Check the Console view to see the output messages, including a link to view the job result. Click the link in the Console view to see the details of the job. You can also check the Enterprise Server Console Daemon window running outside of the IDE for the result of running the JCL job.

Parent topic: Tutorial: JCL
Previous topic: Create and Build a JCL Application
Next topic: View the Spool Queues


View the Spool Queues

The Enterprise Server Monitor and Control (ESMAC) works in conjunction with Enterprise Server Administration and enables you to view and control enterprise servers, and the services, packages, and handlers that run on those servers. The spooler is another name for the job entry subsystem, JES. It maintains a number of spool queues, showing the status of jobs in the system.

The IDE enables direct access to the Spool and Catalog on the ESMAC pages.

To see the spool queues:

  1. In Server Explorer, right-click JCLDEMO.
  2. Select Show Spool from the context menu.

    The page that appears shows one of the spooler queues. The Output checkbox is enabled which means you are viewing the Complete queue, which is the queue containing all jobs that have an Output status.

  3. Check the box to the left of the JCLTEST entry, and click Display.

    This shows details of the job.

  4. Click Details on the line for each particular step.
  5. On that details page, click Display to view the output from the step.

    The output from this step consists of a small number of simple records.

Parent topic: Tutorial: JCL
Previous topic: Submit and Run a JCL Job
Next topic: View the Catalog


View the Catalog

The catalog file holds the details of data sets required by the JCL jobs that run in an enterprise server. To view the catalog:

  1. In Server Explorer, right-click JCLDEMO and choose Show Catalog.
  2. Click List in the page that appears.

    This shows the catalog file, MFIJCL.OUTFILE.DATA, created by the example job. If this file isn't shown, check Cataloged Only.

  3. Click the DCB link to see the catalog entry.

    Note that Codeset for the file is ASCII.

  4. To view the file, click Display.

    The file contents are displayed.

Parent topic: Tutorial: JCL
Previous topic: View the Spool Queues
Next topic: Debug Dynamically under Enterprise Server


Debug Dynamically under Enterprise Server

The IDE enables you to debug a job running on an enterprise server, either locally or remotely.

It is not possible to debug the JCL file itself, but you can debug the COBOL programs that are invoked by the job (that is, EXEC PGM=COBOL-prog-name). Breakpoints within these invoked programs are honored in the same way as when debugged locally.

You can also set breakpoints on the JCL, at project level: specify a job name, a job number, a step name or the top-level program on the JCL Debugging type options in the debug configuration and execution breaks at the first available point after the criteria is met. These choices are useful when performing remote debugging, and support multiple users debugging on the same region.

In this section, we will set the breakpoints directly in the COBOL code, on the enterprise server we created locally. See the links at the bottom of the page for further reading on enabling some of the other functionality.

  1. Set Enterprise Server Preferences
  2. Start Debugging
  3. View the List of Attached Debuggers
Parent topic: Tutorial: JCL
Previous topic: View the Catalog
Related reference
To connect to a remote enterprise server


Set Enterprise Server Preferences

Before you can debug within Eclipse, the dynamic debugging feature must be enabled within an enterprise server region. Dynamic debugging is enabled already in the JCLDEMO enterprise server region because it was enabled by the template you used to create JCLDEMO. However, as an alternative to enabling dynamic debugging for each individual enterprise server, you can also set the Enterprise Server preferences in Eclipse to automatically enable dynamic debugging for all enterprise server regions as each starts, regardless of the setting on each individual server. In addition, you can set preferences to automatically start the associated enterprise server region when an application is run, and to stop all started enterprise server regions when you exit Eclipse.

To do this:

  1. In Eclipse, click Window > Preferences, and then on the Preferences dialog box, select Micro Focus > Enterprise Server.
  2. Set the following options to Always, then click Apply and Close:
    • Automatically start the associated server
    • Automatically stop servers started by Eclipse when closing Eclipse
    • Automatically enable dynamic debugging
Note: These Enterprise Server preferences apply to all enterprise servers listed on the Enterprise Server Administration page. To enable dynamic debugging on an individual server, edit the server and check Allow Dynamic Debugging on the Server > Properties > General page; you must restart the server for a changed setting to take effect.
Parent topic: Debug Dynamically under Enterprise Server
Next topic: Start Debugging


Start Debugging

Debugging requires no changes to your program code. It requires that your project is associated with the JCLDEMO enterprise server and that the enterprise server is configured to enable dynamic debugging, which you performed in the previous steps.

  1. Ensure you are in the Team Developer perspective.
  2. Double-click the JCLREAD.cbl and JCLCREAT.cbl files in the jcl project, from Application Explorer view, to open them.
  3. Introduce breakpoints in both files:

    On a line in the Procedure Division, double-click in the left margin to insert a breakpoint.

    For example, in JCLREAD.cbl, set a breakpoint on the line for OPEN INPUT INFILE. In JCLCREAT.cbl, set a breakpoint for the line for OPEN OUTPUT OUTFILE.

  4. Choose Run > Debug or press F11.
  5. Click JCL on COBOL Enterprise Server in the Debug As dialog box, and click OK.

    This starts the JCLDEMO server and also prompts you to confirm the switch to the Debug perspective. Click Yes to switch to the Debug perspective.

  6. Submit the JCL file. (You will need to switch from the Debug Perspective in the IDE to the Team Developer Perspective to do this.)

    The debugger stops in your JCLCREAT program at the breakpoint.

  7. Step through a few lines and press F8 to continue.
    The debugger should stop again in the JCLREAD program.
    Tip: If you want to view the list of attached debuggers, work through the next topic before performing the next step.
  8. Once you’ve completed your debug session, select Run > Terminate.

Notice the messages that have appeared in the Console.

Parent topic: Debug Dynamically under Enterprise Server
Previous topic: Set Enterprise Server Preferences
Next topic: View the List of Attached Debuggers


View the List of Attached Debuggers

You can view the list of debuggers waiting to attach to your region using ESMAC:

  1. Start debugging.
  2. Click Edit on the row for JCLDEMO on the Enterprise Server Administration page.
  3. Click the Control tab under Server.
  4. Click ES Monitor & Control.

    This opens the ESMAC page.

  5. Click the Dyn.Debug button at the bottom left of the page.

A list of active debuggers appears. You can also remove these debuggers from the list.

Parent topic: Debug Dynamically under Enterprise Server
Previous topic: Start Debugging


Tutorial: DSNREXX

This tutorial shows how to execute DB2 statements from within a DSNREXX procedure. This is done by creating a JCL project and then associating it with an XA resource, enabling you to run a DSNREXX procedure using sample JCL provided with Enterprise Developer.

Prerequisites

To complete this tutorial, you need the following software in addition to Enterprise Developer:

  • IBM's DB2 Database for Linux, UNIX, and Windows (LUW). See Additional Software Requirements on Windows for more information. You can download a version of DB2 to use in the tutorial from IBM's website - click here.
  • Windows Software Development Kit (SDK) installed for your version of Windows. You can download the Windows 10 SDK from the Windows Dev Center website - click here.
Note: You need to ensure that you use 32-bit versions for the following tools and utilities:
  • ODBC Data Source Administrator (32-bit) or ODBC Data Sources (32-bit), depending on your version of Windows.
  • Enterprise Developer command prompt (32-bit).
  • The LIB environment variable should contains the path to your Windows SDK LIB directory (x86) containing odbc32.lib.

Installing DB2

For the purposes of this tutorial you can install a copy of DB2 Express-C. The following points can help you install DB2 for use in this tutorial:

  1. When prompted in the installation setup, select the typical installation type.
  2. You do not need to save your settings in a response file but this may be useful when using DB2 in future.
  3. Use the default installation directory.
  4. Leave the default settings when you select the IBM SSH server installation folder and startup option.
  5. Always secure your DB2 administration server with a strong password.
  6. You do not need to configure the DB2 instances, use the default instance configuration.

Creating a DB2 LUW sample database

If you do not already have a sample database you will need to create one. You can create a sample database by running the db2sampl utility. The utility is part of the DB2 installation:
  1. Start a Enterprise Developer command prompt (32-bit) by clicking Run as administrator.
  2. Type db2sampl -sql
  3. To verify that the database can be connected to, start a DB2 Command Window.
  4. Type DB2 CONNECT TO SAMPLE USER user-id USING password
    You are presented with database connection information, for example:
       Database Connection Information

 Database server        = DB2/NT64 11.1.0
 SQL authorization ID   = user-id
 Local database alias   = SAMPLE
Note: See the DB2 LUW documentation for more information on how to create or catalog the SAMPLE database. Click Start, and type DB2 Information Center. Choose DB2 Information Center, and search for "Create Sample database" or "Catalog database" as required.

Catalog the sample database as an ODBC data source

If your sample database has not been cataloged as an ODBC data source, then perform the following steps:

  1. From your Windows desktop, click Start or use the shortcut keys Ctrl+Esc. In the search field, type ODBC.
  2. In the search results list, select ODBC Data Source Administrator (32-bit) or ODBC Data Sources (32-bit), depending on your version of Windows.

    This opens the 32-bit version of the ODBC Data Source Administrator tool.

  3. Click System DSN tab.
  4. Click Add.

    This opens the Create New Data Source dialog box.

  5. Click IBM DB2 ODBC DRIVER.
  6. Click Finish.

    This opens the ODBC IBM DB2 Driver - Add dialog box.

  7. In the Data source name field, type SAMPLE
  8. In the Database alias list, select the SAMPLE database.
    • Optionally, in the Description field, type a description for your data source.
  9. Click OK, and then click OK.

Create an ODBC XA switch module

If you have not already created the ODBC XA switch module, perform the following steps:
Note: To build the ODBC XA switch module, you must have the Windows Software Development Kit (SDK) installed for your version of Windows. Before building the switch module, ensure that your LIB environment variable contains the path to your Windows SDK LIB directory containing odbc32.lib.
  1. Start an Enterprise Developer command prompt (32-bit) by clicking Run as administrator.
  2. Change to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.
  3. Enter build odbc
    Note: Make a note of the switch module name created, it is used in subsequent steps.

Create the project's workspace

  1. Create the working directory on your machine, for example C:\User\Public\REXXSAMPLE

Import the sample MSS project

To import the sample Mainframe Subsystem (MSS) project:

  1. Start Enterprise Developer for Eclipse.
  2. When prompted for a workspace, specify the path created above C:\Users\Public\REXXSAMPLE
  3. Click OK.
  4. On the Welcome page, click Open Team Developer Perspective.
  5. Click File > Import.

    This opens the Import dialog box.

  6. Expand General, and click Existing Projects into Workspace.
  7. Click Next.
  8. On the Import Projects page, click Browse next to Select root directory.
  9. Choose %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\SQL\OpenESQL\DSNREXX\Test1
  10. Click OK.
  11. In the Projects list, check Test1.
  12. Check Copy projects into workspace.
  13. Click Finish.

Create an MSS-enabled Enterprise Server

Now you want to create an enterprise server region with MSS for JCL use:

  1. In Application Explorer view, right-click the Test1 project.
  2. Click New > Enterprise Server.
    This opens the New Enterprise Server dialog box.
    Note: If you are prompted with an Enterprise Server Sign On dialog box, click OK without specifying any sign-on details. This is a standard security dialog box. Also, if prompted to disable password recovery, click No.
  3. In the Name field, type REXX32
  4. Click Browse next to the Template field.
  5. In the Select template file dialog box, click JCLTemplate.
  6. Click Open.
  7. In the Associate with projects field, check Test1.
  8. Click Finish.

Add an XA resource for REXX procedures pointing to the DB2 LUW SAMPLE database

Now that the enterprise server region is created, you need to set up an XA resource:

  1. In Server Explorer, right-click Local [localhost:86].
  2. Click Open Administration Page.
  3. Click Edit next to the REXX32 region name.
  4. Click Server > Properties > XA Resources.
  5. Click Add.
  6. In the ID field, type DB2T
  7. In the Name field, type REXXPROC
  8. In the Module field, type the location and name of the ODBC XA switch module created in the earlier steps, for example:

    C:\Program Files (x86)\Micro Focus\Enterprise Developer\src\enterpriseserver\xa\ESODBCXA.dll

    Note: When specifying the location and name of the ODBC XA switch module, do not enter an environment variable such as %ProgramFiles(x86)%. Ensure that you use an expanded path.
  9. In the Open string field, type DSN=SAMPLE

    Where SAMPLE is the Data source name specified in the ODBC Data Source Administrator.

    • You may need to add the ID and PASSWORD if connecting to a remote database. See Generic one-phase commit for ODBC xa_open string for more information.
  10. Click Add.

See To define an XA resource (XAR) for an enterprise server region for more information.

Configure the program paths for data set catalog

You need to specify the JES program paths so that Enterprise Server automatically finds the application files that it needs to run:

  1. Click Server > Properties > MSS > JES > General.
  2. In the JES Program Path field, leave the default value unchanged, $IDE_LOADLIB.
  3. In the System Catalog field, type C:\Users\Public\REXXSAMPLE\Test1\catalog.dat
  4. In the Default Allocated Dataset Location field, type C:\Users\Public\REXXSAMPLE\Test1
  5. In the System Procedure Library field, leave the default value unchanged, SYS1.PROCLIB
  6. Click Apply.

Start the enterprise server region

  1. In Server Explorer, expand Local [localhost:86].
  2. Right-click REXX32, and then click Start.
    Note: The Enterprise Server Sign On dialog box might prompt you to provide connection details for the server. This is a standard security dialog box. Click OK without specifying any sign-on details. Also, if prompted to disable password recovery, click No.
    • If you receive a Windows Security Alert for the MF Communications Process, click Allow access.

Catalog the directories that have the REXX procedures

You need to specify the catalog file that holds details of the data sets required by the JCL job that run in an enterprise server region. To do this you need to create a Dynamic PDS. See Dynamic PDSs for more information.

  1. In Server Explorer, right-click REXX32 under Local [localhost:86].
  2. Click Show Catalog.
  3. Click List.
  4. Click New.
  5. In the DS Name field, type USER.TEST.EXEC
  6. In the Physical File field, type C:\Users\Public\REXXSAMPLE\Test1\Scripts
  7. From the DS Org list, select PO.
  8. From the RECFM list, select LSEQ.
  9. Check Dynamic PDS.
  10. In the PDS Exts field, type rex
  11. Click Apply.

To run the JCL job

  1. In Application Explorer view, expand the project to show the Test1.jcl file.
  2. Right-click the Test1.jcl file, and then click Submit JCL to associated Server.

View the spool output

You can check the result of submitting the JCL job by viewing the spool:

  1. In Server Explorer, expand Local [localhost:86].
  2. Right-click REXX32.
  3. Click Show Spool.
  4. Click REXXTEST.

    This provides more information on the job submitted.

  5. Click SYSTSPRT for either of the steps to see more information.
    The following message or similar is displayed for STEP10:

DROPPING REXTEST1 TABLE
INSERTING DATA
PREPARING S1
FETCHING DATA
TEST PASSED  -33329.3333
INSERTING DATA USING INSQLDA
PREPARING S3
FETCHING DATA USING OUTSQLDA
TEST PASSED  -33329.3333

In this tutorial, you learned how to execute a DSNREXX procedure containing DB2 statements from JCL. You cataloged an ODBC connection and built an ODBC XA switch module. You imported a sample mainframe subsystem project, created an Enterprise Server region for it, and defined an XA resource to use your ODBC connection. You set up the region's program paths and created a dynamic PDS catalog file. After running the JCL, you viewed the DSNREXX output from the Enterprise Server spool for the job.

Parent topic: Mainframe Tutorials


Tutorials: PL/I

  • Creating Your First Hello PL/I World Application
  • Debug the Hello PL/I World Application
  • Tutorial: Developing a PL/I application using Eclipse
    This tutorial shows you how to compile, link and debug PL/I programs running under the control of JCL in Enterprise Server.
Parent topic: Mainframe Tutorials


Creating Your First Hello PL/I World Application

Now that we've covered the basic features of the Eclipse IDE, and created a simple Hello World COBOL application, it is time for you to create the equivalent PL/I application:

Create a project

  1. Start Enterprise Developer.

    By default, when you start Eclipse, it displays the Eclipse Launcher dialog box prompting you to specify a path for the Eclipse workspace. Specify a path and click Launch.

    If this is the first time you start Eclipse, you now see the Eclipse Welcome page. See The Eclipse Welcome Page in this Introduction.

    Click Open PL/I Perspective as this perspective is the most suitable one for PL/I development.

  2. Select File > New > PL/I Project.
    Note: For UNIX, you need to select Remote PL/I Project. For more information see Creating Remote PL/I Projects.
  3. Specify a name for your project such as HelloPLIWorld and click Finish.

    By default, the project will be created in the workspace that you selected when you started the Eclipse session.

Add a source file

You need to create a program in your project to hold the PL/I source code:

  1. Select your project in the PL/I Explorer view and click File > New > PL/I Source File.

    The New PL/I Source File wizard is displayed.

  2. In the New file name field type helloworld.pli.
  3. Click Finish.

    This adds a template PL/I file to your project and opens it in the editor.

  4. Copy and paste the following code into the editor, overwriting the existing text:
    HelloWorld: proc options (main);
  put skip list("Hello PL/I World!");
end HelloWorld;
  5. Click File > Save.

    By default, Eclipse builds your project automatically. If you haven't configured Eclipse to do this, you can build a project at any time by clicking Project > Build Project.

    The progress of the project build is displayed in the Console view.

    When your project has been built, a folder called New_Configuration.bin is created in your project. Expand the folder in the PL/I Explorer view to see the executable and some .obj (Windows) or .o (UNIX) files.

You can now run the application.

Run Hello PL/I world

Applications you create in Eclipse need a launch configuration to execute. You are going to create a run configuration for the Hello PL/I world application as follows:

  1. Select your project in the PL/I Explorer view and from the main menu click Run > Run Configurations.
  2. Create a new launch configuration. You can do this in two ways:
    • Double-click the PL/I Application tree item.
    • Click PL/I Application tree item, and then click the New launch configuration icon.

    A default PL/I Launch Configuration is created in the wizard showing HelloPLIWorld as the project to run and New_Configuration.bin/HelloPLIWorld.exe (Windows) or New_Configuration.bin/HelloPLIWorld (UNIX) as the main program to run.

  3. Click Run.

    This opens a console window with Hello PL/I World! printed in it.

  4. Press any key to close the console.

Preserve this project because you are going to use it again for a different demonstration included in this Introduction.

What Next?

Continue with the next tutorial, Debugging the Hello PL/I World Application, which demonstrates how to debug applications in Eclipse.

Parent topic: Tutorials: PL/I
Parent topic: Eclipse Basics
Previous topic: Creating Your First Hello COBOL World Application


Debug the Hello PL/I World Application

Modify your application

You are going to add some extra code to your application that will help demonstrate some of the debugging features:

  1. Open the helloworld.pli program in the editor.
  2. Add the following code before the line for the PUT SKIP LIST statement: :
      DCL SourceString    CHAR(10);
  DCL testchar        CHAR;
  DCL loop            FIXED BIN(8);

  SourceString = "AAbbAAbbCC";
  DO loop = 1 TO 10 BY 1;
    testchar = SUBSTR(SourceString, loop, 1);
    IF testchar = "A" THEN
      SUBSTR(SourceString, loop, 1) = "D";
  END;
  PUT SKIP LIST(SourceString);

  loop = 1;
  DO WHILE (loop < 10) UNTIL (SUBSTR(SourceString, loop, 1) = "C");
    SUBSTR(SourceString, loop, 1) = "Q";
    loop = loop + 1;
  END;

The SourceString variable is a string that has an initial value of "AAbbAAbbCC". Some of the string characters are replaced during the execution of this program.

Create a debug configuration

  1. Select HelloPLIWorld in PL/I Explorer and from the main menu click Run > Debug Configurations.
  2. Double-click the PL/I Application tree item to create a new debug configuration.
  3. Specify HelloPLIWorld as the name of the configuration.

    This configuration uses HelloPLIWorld as the project to run and New_Configuration.bin/HelloPLIWorld.exe (Windows) or New_Configuration.bin/HelloPLIWorld (UNIX) as the main program to run.

  4. Click Debug.

    You are prompted to save and launch before you start debugging. Click OK.

    You are prompted to switch to the debug perspective. Click Yes to confirm. This starts the debugger and it stops on the first line of the program - on the PROC statement.

    Some of the views of the Debug perspective you can see are:

    • Debug view - shows the currently active threads.
    • Editor - shows the helloworld.pli program and the position of the debugger in the program.
    • Expressions - to monitor expressions.
    • Outline - shows an outline of the structure of the program you're stepping through.
    • Breakpoints - to monitor breakpoints.

Step through the code

You can now step through the code and see how the value of the SourceString changes:

  1. Press F5, Step Into, to start stepping the code.

    The first line in the program executes and the cursor moves to the next line in the code.

  2. Open the Expressions view.
  3. Click the + in it and type SourceString as you are going to monitor this variable during debugging.
  4. Press F5 again.

    This executes the statement which initializes the value for SourceString.

  5. Step through the next few lines in the same way and see how the value of the SourceString variable changes in the Expressions view.
  6. Press F8 to exit the program.

    Debugging stops.

You can save the project for future reference.

What Next?

Continue with the section Using Eclipse for PL/I development.

Parent topic: Tutorials: PL/I
Parent topic: Development Life Cycle


Tutorial: Developing a PL/I application using Eclipse

  1. Eclipse PL/I tutorial overview
  2. Create a PL/I Project
  3. Create a PL/I source file, opdemo.pli
  4. Create a build configuration
  5. Create a PL/I source file, opdemo2.pli
  6. Create a JCL file
  7. Configure an enterprise server to run PLI programs under JCL
  8. Submit and run a JCL job
  9. View the spool queues
  10. View the catalog
  11. Debug the program
  12. Stop the Enterprise Server (Eclipse JCL)
Parent topic: Tutorials: PL/I


Eclipse PL/I tutorial overview

In this tutorial, you create a project that compiles and links PL/I programs for execution under the control of JCL. You also create an enterprise server instance and configure it to run PL/I programs under JCL. You then proceed to debug the programs.

Parent topic: Tutorial: Developing a PL/I application using Eclipse
Next topic: Create a PL/I Project


Create a PL/I Project

To create a project:

  1. Start Eclipse using the workspace c:\tutorials.
    1. If you have started Eclipse with another workspace, click File > Switch Workspace > Other, and enter c:\tutorials.
    2. Click OK. Eclipse now exits and restarts with the new workspace as the development folder.
  2. When Eclipse starts, select Window > Perspective > Open Perspective > Other > PL/I.
  3. Select File > New > Mainframe PL/I Project.
  4. Enter PLIJCLdemo in the Project Name field.
  5. Select the Use default location check box. This should use C:\tutorials and the project name (PLIJCLdemo) as the location, as shown in the Location field. If it does not, clear the Use default location check box and click Browse to browse to that location.
  6. Click Finish.

    This adds the project in the Application Explorer view view.

Next you will add some programs to your project.

Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Eclipse PL/I tutorial overview
Next topic: Create a PL/I source file, opdemo.pli


Create a PL/I source file, opdemo.pli

  1. Right-click the project in the Application Explorer view and select New > PL/I Source File.
  2. In the New file name field, enter opdemo.pli. Click Finish. The editor appears with skeleton code for opdemo.pli.
  3. Overwrite the skeleton contents with the following code:
    Note: Make sure the first line of the following code begins in column 2.
     OPDEMO: PROC(JCLPARM) OPTIONS(MAIN) REORDER;

 DCL JCLPARM CHAR(20) VARYING;

 /*-------------------------------------------------------------------*/
 /*                        F I L E S                                  */
 /*-------------------------------------------------------------------*/

  DCL SYSIN FILE RECORD INPUT  ENVIRONMENT(FB RECSIZE(80));

  DCL SYSUT1 FILE RECORD INPUT  ENVIRONMENT(FB RECSIZE(80));

  DCL SYSUT2 FILE RECORD OUTPUT ENVIRONMENT(FB RECSIZE(80));

  DCL SYSPRINT FILE STREAM OUTPUT PRINT ENV (F RECSIZE (132));

 /*-------------------------------------------------------------------*/
 /*            S T R U C T U R E S    &    A R R A Y S                */
 /*-------------------------------------------------------------------*/
 /*-------------------------------------------------------------------*/
 /*                E X T E R N A L    E N T R I E S                   */
 /*-------------------------------------------------------------------*/

 /*-------------------------------------------------------------------*/
 /*                 O T H E R    V A R I A B L E S                    */
 /*-------------------------------------------------------------------*/

 DCL ACCUMULATOR     FIXED BIN(31) INIT(1);

 DCL ASCII_ALPHABET char(38)
   init('!ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 ');

 DCL chTemp char(1);

 DCL EBCDIC_ALPHABET char(38) init
   ('5AC1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9'x ||
    'F0F1F2F3F4F5F6F7F8F940'x);

 DCL EOF_SYSIN      CHAR(1) INIT('0');

 DCL EOF_SYSUT1     CHAR(1) INIT('0');

 DCL ITERATIONS     FIXED BIN(31) INIT(0);

 DCL JCLTRANS       CHAR(20) VARYING;

 DCL REC_BUFF       char(80);

 DCL REPLY_STR      CHAR(120) VARYING;

 DCL STATIC_STR     CHAR(200) varying
   init('Hi Dave - this is your static string');

 DCL SYSIN_NUM_RECS PIC '9999';

 DCL SYSPRINT_BUFF  CHAR(132);

 DCL VAR_NUMERIC    PIC '9999';

 /*-------------------------------------------------------------------*/
 /*              B U I L T I N     F U N C T I O N S                  */
 /*-------------------------------------------------------------------*/

 DCL PLIRETC BUILTIN;
 DCL TRANSLATE BUILTIN;
 DCL DELAY   BUILTIN;

 /*-------------------------------------------------------------------*/
 /*                   M O D U L E     L O G I C                       */
 /*-------------------------------------------------------------------*/

  on error begin;
    PUT SKIP LIST('On Error Triggered' || oncode());
    goto AFTERON;
  end;

  on conversion begin;
    PUT SKIP LIST('On Conversion Triggered');
    goto AFTERON;
  end;

  ON ENDFILE (SYSIN)
     begin;
       EOF_SYSIN = '1';
       put skip list('SYSIN EOF Reached - Num Recs: ' ||
                     sysin_num_recs);
     end;

  ON ENDFILE (SYSUT1)
     begin;
       EOF_SYSUT1 = '1';
       put skip list('SYSUT1 EOF Reached');
     end;

 SYSPRINT_BUFF = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 26 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 52 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 78 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 104 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 130 */
                 '12';
 open file(sysprint);
 PUT SKIP LIST(SYSPRINT_BUFF);

 put skip list('Length of JCLPARM: ' || length(jclparm));
 PUT DATA(JCLPARM);
 PUT SKIP;

 if (JCLPARM = 'DISPLAYREPLY') then
   do;
     DISPLAY('STARTING OPDEMO.PLI') REPLY(reply_str);
     put skip list('Reply String: ' || reply_str);
   end;
 else
   do;

     /* Read SYSIN to EOF */
     sysin_num_recs = '0';
     open input file(sysin);
     do while(eof_sysin = '0');
         read file(sysin) into (rec_buff);
         if (eof_sysin = '0') then
           sysin_num_recs = sysin_num_recs + 1;
     end;
     close file(sysin);

   end;

 /***********************************************************/
 /*  Open SYSUT1 and read until EOF translating records and */
 /*  Writing them to SYSUT2                                 */
 /***********************************************************/

 open file(sysut1) input;
 open file(sysut2) output;

 do while(eof_sysut1 = '0');
    read file(sysut1) into(rec_buff);
    if (eof_sysut1 = '0') then
      do;
        rec_buff = Translate(rec_buff, ascii_alphabet, ebcdic_alphabet);
        write file(sysut2) from(rec_buff);
      end;
 end;

 close file(sysut1);
 close file(sysut2);

 STARTIT:

 PUT SKIP DATA(ACCUMULATOR);
 ACCUMULATOR = ACCUMULATOR + 15;
 PUT SKIP DATA(ACCUMULATOR);

 PUT SKIP LIST('Triggering ON Unit');
 VAR_NUMERIC = 'DAVE';
 PUT SKIP DATA(VAR_NUMERIC);

 AFTERON:
 PUT SKIP LIST('SLEEPING for 3 Seconds');

 Delay(3000);  /*  Sleep for 3 seconds */

 Iterations = Iterations + 1;

 /*  Let's run for about 6 seconds */
 If Iterations < 2 then
   goto startit;

 END;
  4. Save the file.

By default, saving a file automatically triggers a build of the project. You can see the progress of the build process in Eclipse's Console view.

Note: If any build errors occur, check if you've typed everything correctly and that the code begins in column 2.
Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Create a PL/I Project
Next topic: Create a build configuration


Create a build configuration

The build configuration needs to set the path and location of the program that the JCL and enterprise server are expecting. Other settings required for JCL applications, such as an output type of "All executable native libraries" and a mainframe system of MVS, are set by default.

  1. Right-click your project in the Application Explorer view and select Properties.
  2. Expand the Micro Focus node and choose Build Configurations.
  3. Click Manage Configurations.
  4. Click the Create a new configuration button [image].
  5. Select this new configuration and click the Rename button [image]. Change the configuration name to PLIJCLbuild.
  6. Mark this configuration as Active and click Finish.
  7. In the Build Configurations dialog box, enter PLIJCLbuild.bin as the Output directory name and click Apply.
  8. Select the Build Configurations > PL/I Compile Settings node, then select the Enable configuration specific settings check box.
  9. In the list of settings, make sure that the value of External vars in data section is set to Yes.
  10. Select Build Configurations > PL/I Link Settings and make sure Platform Target is set to 64 Bit

Click OK or Apply. The project builds, with the output saved in a new PLIJCLbuild.bin folder.

Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Create a PL/I source file, opdemo.pli
Next topic: Create a PL/I source file, opdemo2.pli


Create a PL/I source file, opdemo2.pli

  1. Create a new PL/I source file called opdemo2.pli.
  2. Overwrite the skeleton contents with the following code:
     OPDEMO2: PROC(JCLPARM) OPTIONS(MAIN) REORDER;

 DCL JCLPARM CHAR(20) VARYING;

 /*-------------------------------------------------------------------*/
 /*                        F I L E S                                  */
 /*-------------------------------------------------------------------*/

  DCL SYSIN FILE RECORD INPUT  ENVIRONMENT(FB RECSIZE(80));

  DCL SYSUT1 FILE RECORD INPUT  ENVIRONMENT(FB RECSIZE(80));

  DCL SYSUT2 FILE RECORD OUTPUT ENVIRONMENT(FB RECSIZE(80));

  DCL SYSPRINT FILE STREAM OUTPUT PRINT ENV (F RECSIZE (132));

 /*-------------------------------------------------------------------*/
 /*            S T R U C T U R E S    &    A R R A Y S                */
 /*-------------------------------------------------------------------*/
 /*-------------------------------------------------------------------*/
 /*                E X T E R N A L    E N T R I E S                   */
 /*-------------------------------------------------------------------*/

 /*-------------------------------------------------------------------*/
 /*                 O T H E R    V A R I A B L E S                    */
 /*-------------------------------------------------------------------*/

 DCL ACCUMULATOR     FIXED BIN(31) INIT(1);

 DCL ASCII_ALPHABET char(38)
   init('!ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 ');

 DCL chTemp char(1);

 DCL EBCDIC_ALPHABET char(38) init
   ('5AC1C2C3C4C5C6C7C8C9D1D2D3D4D5D6D7D8D9E2E3E4E5E6E7E8E9'x ||
    'F0F1F2F3F4F5F6F7F8F940'x);

 DCL EOF_SYSIN      CHAR(1) INIT('0');

 DCL EOF_SYSUT1     CHAR(1) INIT('0');

 DCL ITERATIONS     FIXED BIN(31) INIT(0);

 DCL JCLTRANS       CHAR(20) VARYING;

 DCL REC_BUFF       char(80);

 DCL REPLY_STR      CHAR(120) varying;

 DCL SYSIN_NUM_RECS PIC '9999';

 DCL SYSPRINT_BUFF  CHAR(132);

 DCL VAR_NUMERIC    PIC '9999';

 /*-------------------------------------------------------------------*/
 /*              B U I L T I N     F U N C T I O N S                  */
 /*-------------------------------------------------------------------*/

 DCL DELAY BUILTIN;
 DCL PLIRETC BUILTIN;
 DCL TRANSLATE BUILTIN;

 /*-------------------------------------------------------------------*/
 /*                   M O D U L E     L O G I C                       */
 /*-------------------------------------------------------------------*/

  on error begin;
    PUT SKIP LIST('On Error Triggered');
    goto AFTERON;
  end;

  on conversion begin;
    PUT SKIP LIST('On Conversion Triggered');
    goto AFTERON;
  end;

  ON ENDFILE (SYSIN)
     begin;
       EOF_SYSIN = '1';
       put skip list('SYSIN EOF Reached - Num Recs: ' ||
                     sysin_num_recs);
     end;

  ON ENDFILE (SYSUT1)
     begin;
       EOF_SYSUT1 = '1';
       put skip list('SYSUT1 EOF Reached');
     end;

 SYSPRINT_BUFF = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 26 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 52 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 78 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 104 */
                 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 130 */
                 '12';
 open file(sysprint);
 PUT SKIP LIST(SYSPRINT_BUFF);

 put skip list('Length of JCLPARM: ' || length(jclparm));
 PUT DATA(JCLPARM);

 PUT SKIP;

 if (JCLTRANS = 'DISPLAYREPLY') then
   DISPLAY('STARTING OPDEMO.PLI') REPLY(reply_str);
 else
   do;

     /* Read SYSIN to EOF */
     sysin_num_recs = '0';
     open input file(sysin);
     do while(eof_sysin = '0');
         read file(sysin) into (rec_buff);
         if (eof_sysin = '0') then
           sysin_num_recs = sysin_num_recs + 1;
     end;
     close file(sysin);

   end;

 /***********************************************************/
 /*  Open SYSUT1 and read until EOF translating records and */
 /*  Writing them to SYSUT2                                 */
 /***********************************************************/

 open file(sysut1) input;
 open file(sysut2) output;

 do while(eof_sysut1 = '0');
    read file(sysut1) into(rec_buff);
    if (eof_sysut1 = '0') then
      do;
        rec_buff = Translate(rec_buff, ascii_alphabet, ebcdic_alphabet);
        write file(sysut2) from(rec_buff);
      end;
 end;

 close file(sysut1);
 close file(sysut2);

 STARTIT:

 PUT SKIP DATA(ACCUMULATOR);
 ACCUMULATOR = ACCUMULATOR + 15;
 PUT SKIP DATA(ACCUMULATOR);

 PUT SKIP LIST('Triggering ON Unit');
 VAR_NUMERIC = 'DAVE';
 PUT SKIP DATA(VAR_NUMERIC);

 AFTERON:
 PUT SKIP LIST('SLEEPING for 3 Seconds');

 Delay(3000);  /*  Sleep for 3 seconds */

 Iterations = Iterations + 1;

 /*  Let's run for about 6 seconds */
 If Iterations < 2 then
   goto startit;

 END;
  3. Save the file. When the project builds, the output folder includes two .dll files, one for each .pli file. This is because the default output type is "All executable native libraries" in the build configuration.
Note: If any build errors occur, check if you've typed everything correctly and that the code begins in column 2.
Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Create a build configuration
Next topic: Create a JCL file


Create a JCL file

  1. Click File > New > JCL File.
  2. In the New file name field, enter opdemo.jcl.
  3. Overwrite the skeleton contents with the following code:
    //OPDEMO  JOB 'OPDEMO',CLASS=A,MSGCLASS=A
//**************************************************************
//*  Demonstrates a simple PL/I program running under
//*  the control of JCL.
//**************************************************************
//* Copyright (C) 1985-2017 Micro Focus International Ltd.
//* All rights reserved.
//**************************************************************
//STEP00   EXEC PGM=IEFBR14
//SYSUT2   DD DSN=OPDEMO.SYSUT2,DISP=(MOD,DELETE,DELETE)
//*
//*  Execute the first step with an Open PL/I Binary
//*
//STEP10   EXEC PGM=OPDEMO,PARM='HEAP(80M,4M,ANY,KEEP)/NODISPLAYREPLY'
//SYSUT1   DD *
INPUT RECORD NUMBER 1
INPUT RECORD NUMBER 2
INPUT RECORD NUMBER 3
/*
//SYSIN    DD *
SYSIN RECORD 1
SYSIN RECORD 2
SYSIN RECORD 3
SYSIN RECORD 4
/*
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132),HOLD=Y
//SYSUT2   DD DSN=OPDEMO.SYSUT2,DISP=(NEW,CATLG),
//            DCB=(DSORG=PS,LRECL=80,RECFM=FB)
//*
//*  Once is fun, twice is a even better
//*
//STEP20   EXEC PGM=OPDEMO2,
//         PARM='HEAP(80M,4M,ANY,KEEP)/SOME STRING HERE'
//SYSUT1   DD *
INPUT RECORD NUMBER 3
INPUT RECORD NUMBER 4
INPUT RECORD NUMBER 5
/*
//SYSIN    DD *
SYSIN RECORD 1
/*
//*SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*,DCB=(RECFM=F,LRECL=132),HOLD=Y
//SYSUT2   DD DSN=OPDEMO.SYSUT2,DISP=MOD
//*
  4. Save the file.
Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Create a PL/I source file, opdemo2.pli
Next topic: Configure an enterprise server to run PLI programs under JCL


Configure an enterprise server to run PLI programs under JCL

These are the steps to create and configure an enterprise server to execute PL/I programs under the control of JCL.

  1. Configure an MSS-enabled enterprise server
    This topic shows you how to configure an enterprise server with enabled Mainframe Subsystem Support (MSS).
  2. Enable JES
    Describes how to configure the Job Entry Subsystem (JES) environment after you have created an enterprise server for the PL/I JCL tutorial.
  3. Configure program paths
    This topic shows you how to configure the program paths.
  4. Add an initiator
    Shows how to add an initiator for the PL/I JCL tutorial.
  5. Enable PL/I Support
  6. Associate your project with the enterprise server
  7. Start the enterprise server
Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Create a JCL file
Next topic: Submit and run a JCL job


Configure an MSS-enabled enterprise server

  1. In Eclipse, choose Window > Show View > Other. The Show View dialog box appears.
  2. In the Show view dialog box, select Micro Focus > Server Explorer. A Server Explorer tab appears in the Views pane.
  3. Right-click the Local node and choose Open Administration Page. The Enterprise Server Administration page appears as a tab in the Editor pane.
  4. On the Home page of Enterprise Server Administration, click Add at the bottom of the table of servers.
  5. On the first Add Server page, type PLIDEMO in the Server Name field.
  6. Make sure 64-bit is selected in the Working Mode section, and click Next.
  7. Select Micro Focus Enterprise Server with Mainframe Subsystem Support, and click Next.
  8. Under Creation Options, clear the Create TN3270 listener check box.
  9. Type the following in the Configuration Information field:
    [ES-Environment]
PLIJCLDEMO=c:\tutorials\PLIJCLdemo
    Note: The value for PLIJCLDEMO must match the location being used for this tutorial. If using a location other than shown in the tutorial, be sure to set the value to the location being used.
  10. Enter a meaningful Description, such as "JCL server for tutorial".
  11. Click Add.

The Home page displays, and a row for the new enterprise server is visible in the table of servers.

Parent topic: Configure an enterprise server to run PLI programs under JCL
Next topic: Enable JES


Enable JES

  1. On the Enterprise Server Administration home page, click Edit next to the PLIDEMO row in the table of servers.

    The Edit page appears displaying a hierarchy of tabs.

  2. Make sure the Server and Properties tabs are selected, then select the MSS and JES tabs.
  3. Check the Job Entry Subsystem enabled check box.

    Don't click Apply yet - there is more to do on this page. Go to the next topic in this tutorial to specify location details for deployed programs.

Parent topic: Configure an enterprise server to run PLI programs under JCL
Previous topic: Configure an MSS-enabled enterprise server
Next topic: Configure program paths


Configure program paths

You need to specify the directories and other details needed for the enterprise server to find deployed programs. To do this:
  1. Make sure the Server, Properties and MSS tabs are selected, then enter values into the fields on the JES > General tab, as shown in the table below. The paths you enter here point to the directory of your project.
    Field: Value to enter: Details:
    JES Program Path | $PLIJCLDEMO\PLIJCLbuild.bin | Path for the directory containing executable files to be run by your JCL jobs. This is the path to the folder of your project that contains the PL/I .dll files.
    System Catalog | $PLIJCLDEMO\CATALOG.DAT | Path and name of the system catalog. This is a file that holds the details of data files, their attributes and locations. If the catalogue file does not exist, it will be created with the name given when the JCL is submitted.
    Default Allocated Dataset Location | $PLIJCLDEMO | The default path for the directory where new data sets are to be created.
  2. Click Apply to save the changes.
Parent topic: Configure an enterprise server to run PLI programs under JCL
Previous topic: Enable JES
Next topic: Add an initiator


Add an initiator

Initiator (or batch initiator) is a Service Execution Process for running JCL jobs. You can define initiators to start up automatically whenever the enterprise server is started, and you can also create ones that last only for the current session. This procedure for this tutorial defines one initiator to start automatically.

  1. Go to the Initiators tab.
  2. Click Add.
  3. Type INIT1 in the Name field.
  4. Type abcdefghijklmnopqrstuvwxyz0123456789 in the Class field.
  5. Click Add.
  6. Click Home on the Enterprise Server Administration page.
Parent topic: Configure an enterprise server to run PLI programs under JCL
Previous topic: Configure program paths
Next topic: Enable PL/I Support


Enable PL/I Support

  1. On the Enterprise Server Administration home page, click Edit next to the row for PLIDEMO in the table of servers.
  2. Make sure the Server and Properties tabs are selected, click MSS, and then click the PL/I tab.
  3. Select the PL/I enabled check box.
  4. Specify the following paths:
    Field: Value to enter: Details:
    Codewatch source path(s) | $PLIJCLDEMO | The project directory.
    Codewatch STB path(s) | $PLIJCLDEMO\PLIJCLbuild.bin | The project output folder.
    PL/I Configuration directory | $PLIJCLDEMO | The project directory.
  5. Click Apply, and then click Home in the top left corner of the page.

    The PL/I is enabled for the server and specified locations are added. The Enterprise Server Administration home page appears.

Parent topic: Configure an enterprise server to run PLI programs under JCL
Previous topic: Add an initiator
Next topic: Associate your project with the enterprise server


Associate your project with the enterprise server

To associate your project with the enterprise server:

  1. Right-click PLIDEMO in Server Explorer and choose Associate with project > PLIJCLdemo.

Deploying to the enterprise server

You do not need to deploy the application to your PLIDEMO enterprise server as you configured the search path of the server to be the PLIJCLbuild.bin subfolder of your project. The enterprise server automatically finds the application files that it needs to run.

Parent topic: Configure an enterprise server to run PLI programs under JCL
Previous topic: Enable PL/I Support
Next topic: Start the enterprise server


Start the enterprise server

  1. Expand the Local node in the Server Explorer view in Eclipse.
  2. Right click on PLIDEMO in the list of servers and choose Start. If Store Credentials is not selected, check it. Checking Store Credentials prevents this dialog box from showing by default when you subsequently start an enterprise server instance. Then click OK.
Important: While you could use Enterprise Server Administration and click Start in the Status column corresponding to PLIDEMO, you must stop your enterprise server region using the same means as you started it, either by Enterprise Server Administration or Server Explorer. Starting with one method and stopping with the other can cause problems.
Parent topic: Configure an enterprise server to run PLI programs under JCL
Previous topic: Associate your project with the enterprise server


Submit and run a JCL job

To submit the JCL application to the running JCL-configured enterprise server:

  1. Right-click opdemo.jcl in the Application Explorer view.
  2. Click Submit to Enterprise Server.

You can see the progress of the JCL submission as messages in the console.

Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Configure an enterprise server to run PLI programs under JCL
Next topic: View the spool queues


View the spool queues

The Enterprise Server Monitor and Control (ESMAC) works in conjunction with Enterprise Server Administration and enables you to view and control Enterprise Servers, and the services, packages, and handlers that run on those servers. The spooler is part of the job entry subsystem, JES. It maintains a number of spool queues, showing the status of jobs in the system.

The IDE enables direct access to the Spool and Catalog on the ESMAC pages.

To see the spool queues:

  1. In Server Explorer, right-click PLIDEMO.
  2. Select Show Spool from the context menu.

    The page that appears shows one of the spooler queues.

  3. Click the Complete radio button.

    The Out Hold checkbox is enabled which means you are viewing the Complete queue which contains the jobs with an Out Hold status. (You might have to refresh the list to see it.)

  4. Select the check box to the left of the OPDEMO entry, and click Display.

    This shows some information about the job.

  5. Click Details and then Display to view further information and the output from each step.
    Tip: You can right-click on the tab displaying the spool queue information and select Back to quickly navigate between the output information for each step.
Tip: Right-click the server name at any time in the Server Explorer and choose Show Spool to return to the Complete queue.
Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Submit and run a JCL job
Next topic: View the catalog


View the catalog

The catalog file holds the details of datasets required by the JCL jobs that run in an enterprise server region. To view the catalog:

  1. In Server Explorer, right-click PLIDEMO and choose Show Catalog.

    Click List. The page that opens shows the catalog file, OPDEMO.SYSUT2, created by the example job.

  2. Select the check box beside the catalog file.
  3. Click Details to see the catalog entry.

    Note that Codeset for the file is ASCII.

  4. To view the file, click Display on the page showing the catalog entry.

    The file contents are displayed as a page in the browser.

Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: View the spool queues
Next topic: Debug the program


Debug the program

In this section you debug PL/I programs running under the control of JCL.

  • Debug Configuration
  • Start debugging
  • Debug opdemo.pli
Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: View the catalog
Next topic: Stop the Enterprise Server (Eclipse JCL)


Debug Configuration

You need a debug configuration before you can debug a program.

  1. Click Run > Debug Configurations.
  2. In the left side pane of the Debug Configurations dialog box double-click PL/I Enterprise Server.
  3. Change the name from New_configuration to something meaningful like PLIJCLdemo.
  4. Make sure that the selected connection is Local and the server is PLIDEMO.
  5. In the Debugging type section select the JCL tab.
  6. In the Top-level program field type OPDEMO.
  7. Click Apply.
  8. Click Debug.
  9. If a dialog asking whether to enable dynamic debugging is displayed, select Remember my decision and click Yes.
Parent topic: Debug the program


Start debugging

  1. Right-click opdemo.jcl in the PL/I Explorer tree.
  2. Select Submit to Enterprise Server.
  3. If a dialog asking whether to automatically switch to the debug perspective is displayed, select Remember my decision and click Yes.
Parent topic: Debug the program


Debug opdemo.pli

When the PL/I perspective switches to the debug perspective, the source file opdemo.pli should automatically display with the OPDEMO: PROC(JCLPARM) OPTIONS(MAIN) REORDER; line highlighted as the current line of execution.

  1. If line numbers are not turned on in the source window, right-click in the left column of the source pane and select Show Line Numbers.
  2. Click [image] or press F5 to step into the program. This takes you to line 77 that reads:
    on error begin;
  3. Double-click the line or click Run > Toggle Breakpoint to set a breakpoint. The line appears in the Breakpoints pane in the top right part of the debug perspective.
  4. Click [image] two more times to get to the line that reads:
    ON ENDFILE (SYSIN)
  5. Hold the mouse pointer over SYSIN and the following displays as a Text Hover:
    OPDEMO, SYSIN FILE RECORD INPUT  ENVIRONMENT(FB RECSIZE(80)); Refs=4.
  6. Right-click SYSIN and select Inspect item or use Ctrl+Shift+I to inspect the variable.
  7. Click Add to Expressions View and SYSIN and its current value appear in the Expressions pane.
  8. Click [image] two more times to get to the line that reads:
    SYSPRINT_BUFF = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' || /* 26 */
  9. Add it to Expressions pane as you did with SYSIN and check its current value.
  10. Click [image] and see how the value of SYSPRINT_BUFF changes to ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ12.
  11. Click [image] a few more times until you reach the line that reads:
    sysin_num_recs = '0';

    This line initiates the SYSIN_NUM_RECS variable.

  12. Add SYSIN_NUM_RECS to the Expressions pane and notice that its value is pU.a.
  13. Click [image] and check the value of SYSIN_NUM_RECS in the Expressions pane. It has changed to 0000.
  14. Click [image] a few more times until you reach the line that reads:
    sysin_num_recs = sysin_num_recs + 1;
  15. Step into it and notice how the value changes to 0001.
  16. Go to the last line of opdemo.pli where the END statement is and put the cursor on it.
  17. Click [image] (or CTRL+R) to run the program to that line.

    When the debugger reaches the END statement, you can see from the final value of SYSIN_NUM_RECS (0004) that the program has processed five records.

  18. The debugging will end automatically when the program is done running. If you want to stop debugging before that, click [image].
Parent topic: Debug the program


Stop the Enterprise Server (Eclipse JCL)

Now that you have finished debugging, you can stop the associated enterprise server.

  1. Go back to the PL/I perspective.
  2. Right-click PLIDEMO in the Server Explorer view and select Stop.
  3. Check the Output window for messages that the server has been stopped. A number of messages also appear in the Enterprise Server Console Daemon window before it closes down.
Parent topic: Tutorial: Developing a PL/I application using Eclipse
Previous topic: Debug the program


Tutorials: AppMaster Builder

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

These tutorials take you through the process of using AppMaster Builder to create a program and screen for an online application, generate the application code, compile the code, and run the application. They are arranged sequentially in this documentation with each tutorial presenting tasks that build on those presented in the previous tutorial. Therefore, complete each tutorial in the order in which it is presented.

We suggest that you begin with a review of the demonstration application, and then proceed through the tutorials after becoming familiar with the application.

Note: If you would like to learn more about a particular feature described in a tutorial, click one or more of the related links at the bottom of the topic.
  • Demonstration Application
    Describes the BLDRAPPL demonstration application used in these tutorials.
  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
    Walks you through the process of starting the AppMaster Builder perspective from the Enterprise Developer for Eclipse IDE.
  • Tutorial: Create a User Area
    Create a directory for storing your AMB work files.
  • Tutorial: Create Projects
    Create an AppMaster Builder project and an Enterprise Developer COBOL project.
  • Tutorial: Add Objects to the AMB Project
    Add global objects required for the BLDRAPPL application, and add a new program and screen to develop in AppMaster Builder.
  • Tutorial: Set Preferences and View Properties
    Set the output preferences for your AMB project, and view the properties for the BLDRAPPL application and the BLDRUPD program.
  • Tutorial: Learn Screen Painter Techniques
    Learn the Screen Painter skills you need to complete the tutorials.
  • Tutorial: Paint a Screen
    Use the Screen Painter to paint the BLDRCU screen.
  • Tutorial: Assign Screen Field Edits
    Assign field edits to the fields on the BLDRCU screen.
  • Tutorial: Code a User Rule
    Create a Customizer User Rule that calculates inventory value.
  • Tutorial: Map Screen Fields
    Use Online Express to map screen fields from the BLDRCU screen to working-storage fields in the BLDRUPD program.
  • Tutorial: Define Program Actions
    Define program actions and events using Online Express.
  • Tutorial: Define Database Access
    Define database calls and customize database access.
  • Tutorial: Generate and Compile the Application
    Generate the BLDRAPPL application in AppMaster Builder, and automatically compile in Enterprise Developer.
Parent topic: Mainframe Tutorials


Demonstration Application

Describes the BLDRAPPL demonstration application used in these tutorials.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The demonstration application provided for this tutorial is a basic, online application named BLDRAPPL. It is missing some components that you create and/or define in AppMaster Builder.

As you work to develop, generate, and run the BLDRAPPL application, you are introduced to the primary features of AppMaster Builder. The tutorial uses CICS/VSAM as the development target because it is commonly used in production. In concept, however, the material covered in this tutorial works for all AMB target environments.

The BLDRAPPL application performs the following functions:

  • Presents a selection menu
  • Enables you to add, update, query, and delete records
  • Calculates the total value of your inventory
  • Provides an exit

We provide two programs and their associated screens. You add a third program and screen, among other things, to complete the application.

  • Main Menu Program and Screen
  • Customer Record Maintenance Program and Screen
  • Part Inventory List Program and Screen
Parent topic: Tutorials: AppMaster Builder


Main Menu Program and Screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

BLDRCMNU is a menu program that interacts with a screen, BLDRCM, to provide access to the other two program screens and to exit the application. The program and screen are provided for you.

Figure 1. Main Menu Screen
Main Menu Screen
Parent topic: Demonstration Application


Customer Record Maintenance Program and Screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The BLDRCADD program interacts with a screen, BLDRCA, enabling your end user to add parts information and records to a database, and then return to the main menu. This program and screen are provided for you.

Figure 1. Parts Add Screen
Parts Add Screen
Parent topic: Demonstration Application


Part Inventory List Program and Screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

As part of this tutorial, you create the BLDRUPD program and BLDRCU screen. When complete, this program and screen combination enable your end users to:

  • Query, update, and delete multiple part records
  • Keep a running total of inventory value
  • Exit to the main menu
Figure 1. Parts Update Screen
Parts Update Screen
Parent topic: Demonstration Application


Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse

Walks you through the process of starting the AppMaster Builder perspective from the Enterprise Developer for Eclipse IDE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Start Enterprise Developer for Eclipse. If you need instructions, see To start Enterprise Developer.
  2. If the Welcome page is opened in the main Eclipse window, close it.
  3. From the Enterprise Developer for Eclipse IDE, click Window > Perspective > Open Perspective > Other.
  4. Select AppMaster Builder; then click OK.

This opens the AppMaster Builder perspective, which includes the Project Explorer and the Database View Explorer tabs. The Project Explorer provides a tree view of your current AMB project. You define your project from the Project Explorer, and use the objects on the tree view to kick off certain AMB processes.

This completes the tutorial. Next, please complete Tutorial: Create a User Area.

Parent topic: Tutorials: AppMaster Builder


Tutorial: Create a User Area

Create a directory for storing your AMB work files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Requirements

Before attempting this tutorial, you must complete Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Create the user area
Before you start creating applications, AMB needs to know where you want to store your generated code, and also needs you to define an AMB user ID to identify your jobs in the Job Queue. You do these by creating an AMB user area.
  1. With the AppMaster Builder perspective active, click User > User Area > Create.

    The User area directory field shows the default AMB user area parent directory, which is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\AMBWorkArea.

  2. In the User name field, type your name, or a name you want to use as your AMB user ID. This user name is your AMB user ID.
  3. Click Create.

    AMB creates a new directory of the same name as your provided AMB user ID. This new directory is a subdirectory to the AMB user area parent directory shown in the User area directory field.

  4. Click Exit to close the Create User Area dialog box.

This completes the tutorial. Next, please complete Tutorial: Create Projects.

Parent topic: Tutorials: AppMaster Builder
Related concepts
AppMaster Builder User Areas
Related reference
User Area Directories
Job Queue


Tutorial: Create Projects

Create an AppMaster Builder project and an Enterprise Developer COBOL project.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You need an AppMaster Builder project in which to develop your application, and an Enterprise Developer project in which to compile and run the application. Here we create both projects, and populate the AMB project with the demonstration application files needed to complete the tutorials.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Create an AppMaster Builder project

When you create an AppMaster Builder project, AMB creates and populates a directory structure containing the files required to develop an application. Each project subdirectory contains specific files and file types.

  1. With the AppMaster Builder perspective active, click Admin > Project > Create.
  2. In the Administrator Password field, type ambadmin; then click OK.
    Important: This tutorial assumes you can use the default AMB administrator password. However, you might be required to supply an alternative password if it has been changed.
  3. In the Qualifier field, type c:\amb_tutorials. This represents the full path to a directory that serves as a parent to contain your AppMaster Builder projects.
  4. In the Project field, replace the default text with BLDRAPPL, which is the name of the demonstration application.
  5. In the Group field, replace the default text with dev1 to represent a development group name.
  6. Click Create. A message appears in the dialog header indicating that the project was created.
  7. Click Exit.
Copy demonstration files
  • Using Windows Explorer or a command prompt, copy all of the subdirectories under %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\AMB-Main\Mainframe\AMB\Classic to the c:\amb_tutorials\BLDRAPPL\dev1 directory, overwriting the contents. For example, at a command prompt from the c:\amb_tutorials\BLDRAPPL\dev1 subdirectory, enter:
    xcopy "%PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\AMB-Main\Mainframe\AMB\Classic" /s/y
Set the project path
  1. From the Eclipse IDE, click Window > Preferences.
  2. Expand Micro Focus; then click AppMaster Builder.
  3. In the Project path field, type in or browse to and select the c:\amb_tutorials\BLDRAPPL\dev1 directory; then click Apply.
Create an Enterprise Developer COBOL project
We need an Enterprise Developer project in which to store the code we generate from AppMaster Builder. From the Enterprise Developer project, we can compile and run the generated code.
  1. From the AppMaster Builder perspective, click AppMaster Builder preferences page AppMaster Builder preferences page.
  2. On the AppMaster Builder Preferences page, check Compile in COBOL Project.
  3. Click New.
  4. In the Project name field, type AMB BLDRAPPL; then click Finish. If you are asked whether or not to open the COBOL perspective, choose either option.

    Enterprise Developer creates the project in your default Eclipse workspace, and AppMaster Builder populates the field with the path to the new COBOL project.

  5. Click Apply and Close.
View the new projects
  1. Switch to the AppMaster Builder perspective. The BLDRAPPL project now appears on the Project Explorer tab.
  2. Switch to or open the Eclipse COBOL perspective. You should see the new Enterprise Developer AMB BLDRAPPL project on the tree view.

This completes the tutorial. Next, please complete Tutorial: Add Objects to the AMB Project.

Parent topic: Tutorials: AppMaster Builder
Related concepts
AppMaster Builder Projects
Administration
Related reference
Project Files and Directories


Tutorial: Add Objects to the AMB Project

Add global objects required for the BLDRAPPL application, and add a new program and screen to develop in AppMaster Builder.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Add Global Objects
Here we add a global data view object and a global user rule object to our project. We supply the data view definition, but you create the user rule definition later in this tutorial.
  1. From the AppMaster Builder Project Explorer, expand the BLDRAPPL application.
  2. Right-click GLOBAL; then select Add > Data View from the context menu.
  3. In the Name field, type APSUPD.
  4. Click OK. This returns you to the Project Explorer.
  5. Right-click GLOBAL; then select Add > User Rule from the context menu.
  6. In the Name field, type CALCINV. This is the name of the user rule we will create later in the tutorial. The user rule calculates inventory.
  7. Click OK.
Add a program

We need to add a third program to the project that we will define using the AMB Online Express feature.

  1. From the AppMaster Builder Project Explorer, right-click the BLDRAPPL application; then select Add > Online Express Program from the context menu.
  2. In the Name field, type BLDRUPD; then click OK.

The Project Explorer shows the new BLDRUPD program.

Add a screen

We need to create and associate a screen with the new BLDRUPD program.

  1. From the AppMaster Builder Project Explorer, right-click the BLDRUPD program; then select Add > Screen from the context menu.
  2. In the Name field, type BLDRCU; then click OK.
  3. On the Project Explorer, expand the BLDRUPD program to see the added BLDRCU screen.

This completes the tutorial. Next, please complete Tutorial: Set Preferences and View Properties.

Parent topic: Tutorials: AppMaster Builder
Related concepts
Object Types


Tutorial: Set Preferences and View Properties

Set the output preferences for your AMB project, and view the properties for the BLDRAPPL application and the BLDRUPD program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Set output preferences
  1. If it isn't already active, in Eclipse, switch to the AppMaster Builder perspective.
  2. Click AppMaster Builder Preferences page [image].
  3. From the list of preferences pages, select Output.
  4. Under Save options, check Save COBOL.

    Save COBOL instructs AMB to save COBOL output in your project. In this case, because we have a CICS application defined, Save COBOL saves COBOL output to the COBCICS subdirectory.

  5. Check Generate non-OS/VS COBOL (default), and List generated code.
    Generate non-OS/VS code | Generates COBOL instead of OS/VS COBOL
    List generated code | Produces a code listing in report format when you generate a program or application.
  6. Click Apply and Save.
View application properties
The BLDRAPPL demonstration application is a CICS/VSAM application. Its application properties have been set for you. To view them:
  1. From the AppMaster Builder Project Explorer, expand the C:\amb_tutorials\BLDRAPPL\dev1 project.
  2. Right-click the BLDRAPPL application; then select Properties from the context menu.
  3. Click Settings and take note of the User Interface, MOD Size, and Databases settings.
  4. Click Cancel.
View program properties
When you add a program to an AMB project, it is created with a default set of properties. The BLDRUPD program that you added previously does not require that you change any of the default settings; however, you should view them to become familiar with these settings.
  1. From the AppMaster Builder Project Explorer, expand the C:\amb_tutorials\BLDRAPPL\dev1 project and the BLDRAPPL application.
  2. Right-click the BLDRUPD program; then select Properties from the context menu.
  3. In particular, click Settings and take note that the Program type is set to Online Express.
  4. Click Cancel.

This completes the tutorial. Next, please complete Tutorial: Learn Screen Painter Techniques.

Parent topic: Tutorials: AppMaster Builder
Related concepts
Object Properties
AppMaster Builder Preferences


Tutorial: Learn Screen Painter Techniques

Learn the Screen Painter skills you need to complete the tutorials.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This tutorial presents basic skills you need to move and resize fields in the Screen Painter. Use this tutorial as a reference for performing the tasks in Tutorial: Paint a Screen. The tools cited in this tutorial are available from the Screen Painter toolbar. Hover over the toolbar icons to see tooltips that describe each.

Requirements

It is not strictly necessary that you complete any of the other AMB tutorials before completing this tutorial, which is intended to familiarize you with some important Screen Painter techniques. Review rather than perform the tasks presented here.

Selection Tool

The Selection tool is the default Screen Painter tool. When active, the mouse pointer appears as one of three symbols:

  • Cross hairs
  • Hand
  • Double-sided arrow

Each symbol is used to perform a different function relating to moving or resizing a field.

By default, the selection tool is immediately active when you start the Screen Painter. Also as a default, it becomes active immediately after you finish using a different tool.

If you need to activate the selection tool, click its toolbar icon Selection Tool, or click Tools > Selection.

Select a Field
  1. Place the selection tool over a field.
  2. Click once. Anchor blocks appear around the field, indicating that it is selected.
Select multiple fields
The Screen Painter provides two methods for selecting more than one field.
Method 1
This method is ideal for grouping fields that you want to move in one block, or that you want to align relative to each other.
  1. Place the selection tool higher on the screen than, and to the left of, the group of fields you want to select.
  2. Click and drag the selection tool down the screen and to the right until all fields you want to select are contained within the box. This is called the group box. When you release the mouse button, all fields are enclosed by anchor blocks.

    The primary field is indicated by solid anchor blocks, all others by hollow anchor blocks. You use the primary field as a constant when performing one task on the whole group.

Method 2
This method is best for selecting fields that are not in close proximity to each other on the screen.
  1. To select the first field, position the pointer over the field and click once.
  2. To select another field, position the pointer over the field, hold down the Shift key, and click once.
  3. Repeat step 2 for all subsequent fields.
Move a field
Use this procedure to move a field from one area of your painted screen to another.
  1. Using the selection tool, place the pointer over the field you want to move. The pointer changes to a hand.
  2. Click and drag the field to the desired position, then release the mouse button to drop the field.

To move more than one field at a time, select multiple fields using one of the methods outlined in Select multiple fields and then perform the above procedure.

Resize a field
  1. Using the selection tool, place the pointer over a field. The pointer changes to a hand.
  2. Click once on the field. This activates the anchor blocks.
  3. Move the pointer to any field border. The pointer changes to a double-sided arrow.
  4. Click and drag the border in either direction to resize; then release the mouse button.

This completes the tutorial. Next, please complete Tutorial: Paint a Screen.

Parent topic: Tutorials: AppMaster Builder


Tutorial: Paint a Screen

Use the Screen Painter to paint the BLDRCU screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project
  • Tutorial: Set Preferences and View Properties
  • Tutorial: Learn Screen Painter Techniques

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To paint the BLDRCU (Parts Update) screen, we start the Screen Painter from the AppMaster Builder perspective, paint the text and entry fields, assign a field for system messages, paint a field to save the database key, and title the screen.

Start the Screen Painter
  1. From the Project Explorer tab, expand c:\amb_tutorials\BLDRAPPL\dev1 > BLDRAPPL > BLDRUPD.
  2. Double-click the BLDRCU screen entry. This starts the Screen Painter.
Show the grid
To help you align screen fields, set the Screen Painter grid to show. If the grid is already showing, skip this step.
  • In the Screen Painter, click Options > Show grid.
Draw static text fields
Use the static text tool to drop static text fields onto the BLDRCU screen. Some of the static text fields serve as text labels for entry fields. Others serve as screen title labels. Use the Static Text Fields figure as your guide for this procedure.
Figure 1. Static Text Fields
Static Text Fields
  1. To toggle sticky mode on, click Tools > Sticky Mode. When sticky mode is toggled on, the tool you select next stays active until you toggle sticky mode off or select another tool.
  2. Click Tools > Static Text, or click the Static Text Tool icon on the toolbar Static Text Tool. The mouse pointer changes to the static text tool.
  3. Using the Static Text Fields figure as your guide, position the tool on the top center area of the screen, where you want to paint the first screen title.
  4. Click to drop the field.
  5. Repeat steps 3 and 4 to drop the nine remaining static text fields. At this point, all fields read Text. Do not be concerned if the fields are not properly aligned.
  6. To toggle sticky mode off, click Tools > Sticky Mode.
Increase static text field sizes
Before you can assign descriptive text to these fields, you must first increase the size of each to accommodate the text. Use the Static Text Field Lengths table and the Labeled Static Text Fields figure as your guides for this procedure. While the table indicates the label for the fields, we will not actually put the labels onto the fields until the next section.
Table 1. Static Text Field Lengths
Static Text Field Label | Length
AMB DEMONSTRATION SYSTEM | 25
PARTS UPDATE SCREEN | 20
FUNCTION: 10
(Q=QUERY, U=UPDATE, D=DELETE) | 30
PART NUMBER: 13
DESCRIPTION: 13
UNITS: 7
BASE PRICE: 12
DIMENSIONS: 12
INVENTORY VALUE: 17
HIT F3 TO BYPASS FIELDS AND RETURN TO MAIN MENU SCREEN | 55
Figure 2. Labeled Static Text Fields
Labeled Static Text Fields
  1. First, activate the Tracking option. To do this, click Options > Show tracking. The bottom right field on the Screen Painter dialog box shows Track, indicating that tracking is active.
  2. On the BLDRCU screen, click the first screen title field, located at the top center. The anchor blocks appear. This field must accommodate the text AMB DEMONSTRATION SYSTEM, which is 24 characters in length.
  3. Move the mouse pointer to the right border of the field. The pointer changes to a double-sided arrow.
  4. Drag the border to the right until the LEN specification in the Screen Painter Tracking field reads LEN=24.
  5. Using the Static Text Field Lengths table and the Labeled Static Text Fields figure as your guides, repeat steps 2 through 4 for each text field.
Label static text fields
Next, label the fields with descriptive text. Use the Labeled Static Text Fields figure as your guide for this procedure.
  1. Double-click the AMB Demonstration System field on the top center of the screen. The Text Attributes dialog box appears.
  2. Highlight the word Text in the Text field, located on the top right column of the Text Attributes dialog box.
  3. Type AMB DEMONSTRATION SYSTEM to replace it.
  4. Click the check mark Screen Painter check mark to accept the change.
  5. Close the Text Attributes dialog box by clicking the x icon in the upper right corner.
  6. Using the Labeled Static Text Fields figure as your guide, repeat steps 1 through 5 for each static text field, substituting the appropriate label text in step 3.
Draw entry fields
Use the Entryfield tool to drop entry fields onto the BLDRCU screen. Use the Entry Fields figure as your guide for this procedure.
Figure 3. Entry Fields
Entry Fields
  1. To toggle sticky mode on, click Tools > Sticky Mode.
  2. Click Tools > Entryfield, or click the Entryfield tool icon Entryfield Tool from the toolbar. The mouse pointer changes to the Entryfield tool.
  3. Position the tool to the right of the FUNCTION static text field.
  4. Click to drop the entry field.
  5. Using Figure 3 as your guide, position and drop the remaining entry fields. Do not be concerned if all fields are not aligned.
  6. To toggle sticky mode off, click Tools > Sticky Mode.
Resize entry fields
Because the Screen Painter default length for entry fields is 4, all of your entry fields are now four characters in length. You need to make them the size needed for data entry. Use the Entry Field Lengths table to determine field lengths.
Table 2. Entry Field Lengths
Field | Length
Function | 1
Part Number | 8
Description | 20
Units | 2
Base Price | 7
Dimensions | 8
Inventory Value | 12
Savekey (located below and to the left of the Dimensions field) | 9
System Message (located below the Savekey field) | 79
  1. Click the FUNCTION entry field. The anchor blocks appear.
  2. Move the mouse pointer to the right border of the field. The pointer changes to a double-sided arrow.
  3. Drag the border to the left until the LEN specification in the Screen Painter Tracking field reads LEN=1, and release the mouse.
  4. Repeat steps 1 through 3 for each entry field, dragging each border to the left or the right as necessary, using the Entry Field Lengths table to determine field lengths.
  5. Now is a good time to save your work. Click File > Save.
Assign field attributes
With the fields painted and labeled, we can now assign attributes to each field.
Assign field attributes to DATA fields
  1. Double-click the entry field next to the FUNCTION text field. The Field Attributes dialog box appears.
  2. In the Name field, change DATA1 to function.
  3. Check Cursor. This positions the cursor in the Function field when you run the application.
  4. Click the check mark Screen Painter check mark to accept the change.
  5. Close the Field Attributes dialog box.
  6. Repeat steps 1, 2, 4, and 5 once for each remaining entry field, using the following table to determine field names.

    For the field with this label . . .

    Change DATAx1 to . . .

    FUNCTION:

    function

    PART NUMBER:

    part-nbr

    DESCRIPTION:

    short-desc

    UNITS:

    units-instock

    BASE PRICE:

    base-price

    DIMENSIONS:

    dimensions

    INVENTORY VALUE:

    inv-value

    1 x represents the number generated for the default name of the field.
Assign attributes to the Savekey field
  1. Double-click the Savekey field.
  2. In the Name field, change DATAx to savekey.
  3. Check Protected. This prohibits the end user from entering data.
  4. From the Intensity drop-down list, click Dark. This changes the field from normal intensity to dark (hidden) so that the field does not display on the screen that the end user sees.
  5. Click the check mark Screen Painter check mark to accept the changes.
  6. Close the Field Attributes dialog box.
Assign attributes to the System Message field
  1. Double-click the System Message field.
  2. In the Name field, change DATAx to system.
  3. Check Protected. This prohibits the end user from entering data.
  4. Click the check mark Screen Painter check mark to accept the changes.
  5. Close the Field Attributes dialog box.
Assign Screen Parameters
In this procedure, you assign screen parameters to the BLDRCU screen. First, we specify an internal screen title to appear in all generated BLDRAPPL reports. Then, we assign a system message field to accept and display messages from the application. And finally, we assign a CICS transaction ID to the screen. When you run the application, the transaction ID identifies the screen to CICS.
Assign an internal screen title
  1. Double-click on a blank portion of the screen. The Screen Parameters dialog box appears.
  2. In the Title field, type Parts Update.
Assign the System Message field
  1. On the Screen Parameters dialog box tool bar, click EDITS. The Field Edit Messages and Attributes dialog box appears.
  2. From the Message Display Field drop-down list, select SYSTEM.
  3. Click OK. This returns you to the Screen Parameters dialog box.
Assign a transaction ID for the screen
  1. On the Screen Parameters dialog box tool bar, click CICS. The CICS Generation Parameters dialog box appears.
  2. In the Transaction ID field, type BLDU.
  3. Click OK. This returns you to the Screen Parameters dialog box.
  4. Click OK. This returns you to the Screen Painter.
Note: The CICS transaction IDs for the BLDRCA and BLDRCM screens have been set for you.
Align fields
In this section, you use the alignment features of Screen Painter to clean up the appearance of the BLDRCU screen.
Center the title fields
  1. Using one of the methods presented in the Select multiple fields section of the Learn Screen Painter Basics tutorial, select the AMB Demonstration System and Parts Update text fields.
  2. Click Arrange > Alignment. The Alignment dialog box appears.
  3. On the horizontal list, click Center.
  4. On the vertical list, click None.
  5. Click OK to make the alignment. The Screen Painter centers the screen title fields relative to the screen and each other.
Align the Function and Units text fields with the Part Number text field
  1. Using one of the methods presented in the Select multiple fields section of the Learn Screen Painter Basics tutorial, select the Function, Part Number, and Units text fields.
  2. To set the Part Number field as the primary field, click on it. Its anchor blocks become solid.
  3. Click Arrange > Alignment. The Alignment dialog box appears.
  4. On the horizontal list, click Left.
  5. On the vertical list, click None.
  6. Click OK to make the alignment. AMB left aligns the Function and Units fields with the Part Number field.
Align remaining fields
Figure 4. Completed Parts Update Screen
Completed Parts Update Screen
  1. Using the techniques you have learned in this tutorial and in Tutorial: Learn Basic Screen Painter Techniques, continue to adjust fields on the screen until they appear as shown in the Completed Parts Update Screen figure.
  2. Click File > Save to save your work.
  3. Click the x icon in the upper right corner to close the Screen Painter.

This completes the tutorial. Next, please complete Tutorial: Assign Screen Field Edits.

Parent topic: Tutorials: AppMaster Builder
Related concepts
Screen Painter
Related reference
Field and Text Attributes
Field Edit Messages and Attributes
Screen Parameters
Alignment
CICS Generation Parameters


Tutorial: Assign Screen Field Edits

Assign field edits to the fields on the BLDRCU screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In this tutorial, you assign field edits to entry fields on the Parts Update screen, and then set up a PF key that enables the end user to bypass screen edits. Screen field edits enable you to define the type of and format for data that a field can accept or output. The following table describes the edits you will assign in this tutorial:

Field Type Edit(s)
Function Character
  • Require data entry.
  • Do not allow embedded spaces or punctuation.
Part Number Character
  • Store data as an 8-byte alphanumeric number.
  • Require data entry.
  • Define input picture as NNNNNNN9.
  • Define output picture as XXXXXXX9.
Units Numeric
  • Allow data between 0 and 50.
  • Move zeros to field if data not entered.
  • Remove special characters.
  • Specify an error message that says VALID VALUES FOR UNITS ARE 0 THROUGH 50.
  • Define output picture as Z9.
Base Price Numeric
  • Store data as a 4-digit number with 2 decimal places.
  • Move zeros to field if data not entered.
  • Remove special characters.
  • Define output picture as ZZZ9.99.
Inventory Value Numeric
  • Store data as a 12-digit number with 2 decimal places and a $ to represent monetary value.
  • Computational field.
  • Move zeros to field if data not entered.
  • Define output picture as $$$$$$$$9.99

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project
  • Tutorial: Set Preferences and View Properties
  • Tutorial: Learn Screen Painter Techniques
  • Tutorial: Paint a Screen

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Assign Screen Edits to BLDRCU Fields

Complete the following procedures to assign screen edits to the BLDRCU fields you painted in Tutorial: Paint a Screen.

Function
In this procedure, you assign field edits to the FUNCTION field on the Parts Update screen. The edits you assign here set the field to require input from the end user.
  1. Click on the Function entry field to select it.
  2. Click Edit > Field Edits. The Field Edit Data Type dialog box appears.
  3. To accept the default Character Local Data Class and Character String (Fixed) Local Data Type, click OK. These selections define the internal representation for the field. The Field Edits window appears, showing default edits for the field.
  4. Click Input. The Input Representation dialog box appears. Here, you specify format and data requirements that the end user must adhere to when entering data into the field.
  5. Check Input Required. When checked, this option requires the end user to enter data for the field.
  6. Uncheck Embedded Spaces.
  7. Click OK. This returns you to the Field Edits window.
  8. Click OK. This returns you to your painted screen.
Part Number
In this procedure, you assign field edits to the Part Number entry field on the Parts Update screen.
Accept default class and type
  1. Click the Part Number entry field to select it.
  2. Click Edit > Field Edits. The Field Edit Data Type dialog box appears.
  3. To accept the default Character Local Data Class and Character String (Fixed) Local Data Type, click OK. The Field Edits summary dialog box appears, showing default edits for the field.
Define user inputs
  1. Click Input. The Input Representation window appears.
  2. Check Input Required.
  3. Click Use Input Mask.
  4. In the Input Mask field, type nnnnnnn9 (7 n's).
  5. Click OK. The Field Edits window reappears.
Define outputs
  1. Click Output. The Output Representation dialog box appears. Here, you can specify format requirements for displaying the data.
  2. Click Use Output Mask.
  3. In the Output Mask entry field (located below the Type drop-down list), enter xxxxxxx9 (7 x's).
  4. Click OK. This returns you to the Field Edits window.
  5. Click OK. This returns you to your painted screen.
Units
In this procedure, you assign field edits to the Units field on the Parts Update screen.
  1. Click on the Units entry field to select it.
  2. From the Edit menu select Field Edits. The Field Edit Data Type dialog box appears.
Set local data
  1. On the Local Data Class list, click Numeric.
  2. On the Local Data Type list, click COBOL Display.
  3. Click OK. The Field Edits dialog box appears.
Assign input edits
  1. Click Input. The Input Representation window appears. The Use Characteristics radio button is selected by default.
  2. Check Zero When Blank. Checking this option moves zeroes to the field if the end user does not enter data.
  3. Check Ensure Computational. Checking this option prevents premature termination of the program if a user enters non-numeric data into the field.
Assign an error message
  1. Click Message. The Input Messages and Attributes dialog box appears. Here you can specify error messages to display if the field fails input edits or if data for a required field is not entered.
  2. In the Error field, type Valid values are 0 through 50.
  3. In the Attributes field, type pos+brt. This positions the cursor at the beginning of the field when invalid data is entered, and assigns a bright intensity to the error message.
  4. Click OK. This returns you to the Input Representation window.
  5. Click OK. This returns you to the Field Edits window.
View default output edits (optional)
  1. Click Output. The Output Representation dialog box appears.
  2. After viewing the information on this window, click Cancel. This returns you to the Field Edits window.
Specify values and conversions
  1. Click Values. The Values and Conversions dialog box appears. Here you can specify that only certain values, ranges of values, or conversion values can be entered.
  2. To assign a range of acceptable input values, type 0 to 50 on the first value entry line.
  3. Click OK. This returns you to the Field Edits window.
  4. Click OK. This returns you to your painted screen.
Base Price
In this procedure, you assign field edits to the Base Price field on the Parts Update screen.
  1. Click on the Base Price entry field to select it.
  2. Click Edit > Field Edits. The Field Edit Data Type dialog box appears.
Set local data
  1. On the Local Data Class list, click Numeric.
  2. On the Local Data Type list, click COBOL Display.
  3. Click OK. The Field Edits dialog box appears.
Define internal edits
  1. Click Internal. The Internal Representation dialog box appears. Here, you can define storage requirements for the field.
  2. You originally painted this field as 7 bytes. To account for the decimal point in this field, in the Total field, type 6.
  3. In the Right of Decimal field, type 2. This specifies that this field has 2 decimal places.
  4. Click OK. An internal Pic message appears.
  5. Click OK to clear the message. This returns you to the Field Edits window.
Define input edits
  1. Click Input. The Input Representation dialog box appears.
  2. In the Max column of the Left Input Digits field, type 4.
  3. In the Max column of the Decimal Digits field, type 2.
  4. Check Zero When Blank.
  5. Check Ensure Computational.
  6. Click OK. This returns you to the Field Edits window.
Define output edits
  1. Click Output. The Output Representation dialog box appears.
  2. In the Output Mask field, change ZZZZZZ9 to zzz9.99.
  3. Click OK. This returns you to the Field Edits window.
  4. Click OK. This returns you to your painted screen.
Inventory Value
In this procedure, you assign field edits to the Inventory Value field on the Parts Update screen.
  1. Click on the Inventory Value entry field to select it.
  2. Click Edit > Field Edits. The Field Edit Data Type dialog box appears.
Set local data
  1. On the Local Data Class list, click Numeric.
  2. On the Local Data Type list, click COBOL Display.
  3. Click OK. The Field Edits dialog box appears.
Define internal edits
  1. Click Internal. The Internal Representation dialog box appears. Here, you can define storage requirements for the field.
  2. You originally painted this field as 12 bytes. To account for the decimal point in this field, in the Total field, type 11.
  3. In the Right of Decimal field, type 2. This specifies that this field has 2 decimal places.
  4. Click OK. An internal Pic message appears.
  5. Click OK to clear the message. This returns you to the Field Edits window.
Define input edits
  1. Click Input. The Input Representation dialog box appears.
  2. Check Ensure Computational.
  3. Check Zero When Blank.
  4. Click OK. This returns you to the Field Edits window.
Define output edits
  1. Click Output. The Output Representation dialog box appears.
  2. In the Output Mask field, change ZZZZZZZZZZZ9 to $$$$$$$$9.99 (8 $s).
  3. Click OK. This returns you to the Field Edits window.
  4. Click OK. This returns you to your painted screen.

Now is a good time to save your work. Click File > Save.

Bypass Assigned Field Edits

You might wonder why you would want to bypass field edits. If, for example, a user accesses the BLDRCU screen by mistake, escaping the screen is impossible until he enters valid data into the Function field, because you assigned the Required field edit to the Function field.

For the BLDRCU screen, you set up the PF3 key to bypass all input edits on the screen. Then, in the Online Express tutorial, you assign it a termination function that enables an end user to escape from the screen without affecting the database. When you bypass edits, you bypass all the field edits and all the screen edit routines.

  1. Double-click on any empty portion of the painted screen. The Screen Parameters dialog box appears.
  2. On the tool bar, click EDITS. The Field Edit Messages and Attributes dialog box appears.
  3. On the tool bar, click Bypass. The Field Edit Bypass Criteria dialog box appears.
  4. Check PF03.
  5. Click OK. This returns you to the Field Edit Messages and Attributes window.
  6. Click OK. This returns you to the Screen Parameters window.
  7. Click OK. This returns you to the Screen Painter.

Exit the Screen Painter

You have now completed your work in the Screen Painter and can exit back to the AppMaster Builder perspective.

  1. In the Screen Painter, click File > Exit.
  2. Click Yes on the prompt to save all of your work.

This completes the tutorial. Next, please complete Tutorial: Code a User Rule.

Parent topic: Tutorials: AppMaster Builder
Related concepts
Defining Field Edits
Related reference
Field Edit Data Type
Values and Conversions
Field Edit Bypass Criteria
Field Edit Messages and Attributes
Field Edits
Input Messages and Attributes
Input Representation
Internal Representation
Output Representation


Tutorial: Code a User Rule

Create a Customizer User Rule that calculates inventory value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

When we defined the BLDRAPPL application in AppMaster Buider, we created a global user rule object named CALCINV. Because CALCINV is global, all programs generated from our application automatically include the CALCINV rule. In this tutorial, we populate the user rule object with code. In a later tutorial, we call the rule from Online Express.

We use the following code to populate the CALCINV user rule. We have added line numbers so that each line is easily identified for the purpose of discussing what this user rule does:

0001       % DEFINE $CALC-INV-VALUE( &PRE,
0002       % ...  &PRICE-FLD, &UNITS-FLD )
0003           % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
0004               % &PART-INVENTORY-SEEN = 1
0005               % SET WORKING-STORAGE
0006               &08+01 WS-INVENTORY-VALUE     PIC S9(08)V99.
0007               % SET PROCEDURE
0008           % END
0009           IF &PRE+-&PRICE-FLD = ZERO
0010           ...  OR &PRE+-&UNITS-FLD = ZERO
0011               MOVE ZERO TO WS-INVENTORY-VALUE
0012           ELSE
0013               COMPUTE WS-INVENTORY-VALUE =
0014               ... &PRE+-&PRICE-FLD
0015               ... * &PRE+-&UNITS-FLD
0016       % END

Lines 0001 - 0002:

       % DEFINE $CALC-INV-VALUE( &PRE,
       % ...  &PRICE-FLD, &UNITS-FLD )

These lines identify the name of the rule, $CALC-INV-VALUE, and three parameters, &PRE, &PRICE-FLD, and &UNITS-FLD. All user rule names begin with a dollar sign ($). Values for the three parameters must be supplied when the rule is called. In this case, the user rule is looking for a prefix, which in this case represents a prefix for the Working-Storage field names, the remainder of the name of a Working-Storage field that contains the price of an item (&PRICE-FIELD), and remainder of the name of the Working-Storage field that contains the number of units being ordered (&UNITS-FLD).

The two lines here comprise one logical line of code, continued on a second line using the % sign to identify the line as Customizer code, and ellipses (...) to indicate the continuation.

Lines 0003 - 0008:

0003           % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
0004               % &PART-INVENTORY-SEEN = 1
0005               % SET WORKING-STORAGE
0006               &08+01 WS-INVENTORY-VALUE     PIC S9(08)V99.
0007               % SET PROCEDURE
0008           % END

Here we have an IF structure comprised of MFG structures. MFG structures are identified by the percent (%) sign in column 8 of each line. This % IF structure does the following:

Lines 0003 - 0004
0003           % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
0004               % &PART-INVENTORY-SEEN = 1

If the parameter &PART-INVENTORY-SEEN is not defined, &PART-INVENTORY-SEEN is defined and its value set to 1. If this Customizer rule is encountered again in the generation process, the MFG will not execute the remainder of the % IF structure, preventing the code it generates from being generated twice.

Line 0005
0005               % SET WORKING-STORAGE

The MFG is set to create a Working-Storage structure. Because this code appears in our program in the Procedure Division, it is necessary to temporarily assign the code generator back to Working Storage so that the structure created appears in the proper section of the generated code.

Line 0006
0006               &08+01 WS-INVENTORY-VALUE     PIC S9(08)V99.

In the Working-Storage section, on a new line beginning in column 8, the MFG writes an 01-level data structure for WS-INVENTORY-VALUE. This data structure holds the value that is eventually sent to the INV-VALUE screen field.

Line 0007
0007               % SET PROCEDURE

The MFG is reset to continue in the Procedure Division.

Line 0008
0008           % END

Indicates the end of the % IF structure.

Lines 0009 - 0015:

0009           IF &PRE+-&PRICE-FLD = ZERO
0010           ...  OR &PRE+-&UNITS-FLD = ZERO
0011               MOVE ZERO TO WS-INVENTORY-VALUE
0012           ELSE
0013               COMPUTE WS-INVENTORY-VALUE =
0014               ... &PRE+-&PRICE-FLD
0015               ... * &PRE+-&UNITS-FLD

This IF/ELSE structure is comprised of COBOL syntax, using the variables defined in lines 0001 and 0002 of this user rule. This IF component of the structure checks to see if the value in the Working-Storage fields that store the price of an item or the number of units is zero (0). If so, zero is moved to the WS-INVENTORY-VALUE field. If the value in either field is not zero, the ELSE component of the structure calculates the value of the inventory and puts that value into the WS-INVENTORY-VALUE field.

The MFG writes this IF/ELSE structure to the generated program, substituting the parameter values you provide when you call the user rule.

Line 0016:

0016       % END

Indicates the end of the user rule.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project
  • Tutorial: Set Preferences and View Properties
  • Tutorial: Learn Screen Painter Techniques
  • Tutorial: Paint a Screen
  • Tutorial: Assign Screen Field Edits

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Code the CALCINV user rule
  1. On the Project Explorer, expand c:\amb_tutorials\BLDRAPPL\dev1 > BLDRAPPL > GLOBAL.
  2. Double-click the CALCINV user rule. This starts the Program Painter.
  3. Type the following, starting in column 8:
           % DEFINE $CALC-INV-VALUE( &PRE,
       % ...  &PRICE-FLD, &UNITS-FLD )
           % IF NOT &DEFINED( &PART-INVENTORY-SEEN )
               % &PART-INVENTORY-SEEN = 1
               % SET WORKING-STORAGE
               &08+01 WS-INVENTORY-VALUE    PIC S9(08)V99.
               % SET PROCEDURE
           % END
           IF &PRE+-&PRICE-FLD = ZERO
           ...  OR &PRE+-&UNITS-FLD = ZERO
               MOVE ZERO TO WS-INVENTORY-VALUE
           ELSE
               COMPUTE WS-INVENTORY-VALUE =
               ... &PRE+-&PRICE-FLD
               ... * &PRE+-&UNITS-FLD
       % END
  4. Close the Program Painter, and click Yes when prompted to save the file. AppMaster Builder saves the file in the USERMACS project subdirectory.

This completes the tutorial. Next, please complete Tutorial: Map Screen Fields.

Parent topic: Tutorials: AppMaster Builder
Related concepts
Customizer/Micro Focus Generator (MFG)


Tutorial: Map Screen Fields

Use Online Express to map screen fields from the BLDRCU screen to working-storage fields in the BLDRUPD program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In this session, you map screen fields to database and working-storage fields using Online Express, a menu-driven painter with a graphical user interface. Online Express is for any type of online application. It references the information that you have specified, and prompts you to define the processing logic for those specifications.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project
  • Tutorial: Set Preferences and View Properties
  • Tutorial: Learn Screen Painter Techniques
  • Tutorial: Paint a Screen
  • Tutorial: Assign Screen Field Edits
  • Tutorial: Code a User Rule

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Map BLDRCU Screen Fields

Complete the following procedures to map the BLDRCU screen fields to the BLDRUPD program.

Start Online Express
  1. From the Project Explorer tab, expand c:\amb_tutorials\BLDRAPPL\dev1 > BLDRAPPL.
  2. Double-click the BLDRUPD program entry. This starts Online Express. Online Express and its Action/Event Browser appear. The Action/Event Browser shows the names of all fields you defined when you painted the BLDRCU screen.
    Note: If a validation message appears, click OK to clear the message.
Access the Field Mapping dialog box
  • From Online Express, click File > Field Mapping. The Field Mapping dialog box appears, listing the screen fields you defined in the Screen Painter.
Create working-storage fields
Because the BLDRAPPL application uses a VSAM database, Online Express provides only the key field in the Field list box of the Field Mapping dialog box. Therefore, you must add working-storage items for the remaining fields on the PART-MASTER-REC record.
  1. Click Field Mapping > Add User Variable. The Create Working Storage Field dialog box appears.
  2. In the Name field, type ws-base-price.
  3. Click OK.
  4. Repeat steps 2 and 3 one time for each of the following fields:
    • ws-dimensions
    • ws-short-desc
    • ws-units-instock
    • ws-inventory-value
  5. Click Cancel. This returns you to the Field Mapping window.
Map screen fields to working-storage fields
Map the BASE-PRICE field
  1. On the Control list, place the mouse over the BASE-PRICE control.
  2. Click and hold the mouse button. The pointer changes to a plug.
  3. Drag the plug to the WS-BASE-PRICE field, and release the mouse. AMB creates a two-way map between the BASE-PRICE control and the WS-BASE-PRICE field.
Map remaining controls
  • Repeat the steps presented in Map the BASE-PRICE field one time for each of the controls listed in the following table.

    Control Name

    Field Name

    DIMENSIONS

    WS-DIMENSIONS

    PRT-NBR

    PM-PRT-NBR

    SHORT-DESC

    WS-SHORT-DESC

    UNITS-INSTOCK

    WS-UNITS-INSTOCK

Change mapping direction
By default, Online Express draws a connecting line with an arrow at each end, indicating that the mapping is two-way. That is, the program moves data from the working-storage field or database record to the screen field, and vice versa. We want our mappings to be one-way instead of two-way.
  1. To create a one-way mapping from the WS-INVENTORY-VALUE working-storage field and the INV-VALUE screen field, click WS-INVENTORY-VALUE, drag the mouse plug to the INV-VALUE field, and drop.
  2. For all other controls, click the control; then click Field Mapping > Mapping Direction > One-way.
  3. Click Apply.
Save your work
  1. Close the Field Mapping dialog box. This returns you to the Action/Event Browser.
  2. Click File > Save.
  3. Click OK to clear any validation messages.

This completes the tutorial. Next, please complete Tutorial: Define Program Actions.

Parent topic: Tutorials: AppMaster Builder
Related concepts
Field Mapping
Related reference
Field Mapping
Create Working Storage Field


Tutorial: Define Program Actions

Define program actions and events using Online Express.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In AppMaster Builder, you define program logic using Online Express to create events and assign actions to those events. Some actions are pre-defined or reserved by AppMaster Builder, and you can define custom actions as well.

When you have completed this tutorial, the BLDRUPD program will perform the following actions:

Action | Description
Query | Reads database records and moves data to screen fields
Update | Updates the records by moving data from screen fields to the records
Delete | Deletes database records
Term | Terminates the program

The end user executes these database and teleprocessing actions by entering a function code in the screen entry field named Function. Users can also return to the Main Menu program of the application by pressing the F3 function key.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project
  • Tutorial: Set Preferences and View Properties
  • Tutorial: Learn Screen Painter Techniques
  • Tutorial: Paint a Screen
  • Tutorial: Assign Screen Field Edits
  • Tutorial: Code a User Rule
  • Tutorial: Map Screen Fields

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective and, from the Project Explorer, double-click the BLDRUPD program to start Online Express.

Define Program Actions for the BLDRUPD Program

Start the Action/Event Editor
  1. On the Control Type list, click Function Field.
  2. On the Control Name list, double-click Function. The Action/Event Editor appears.
Define Query database action
  1. From the Function Field drop-down list box, click Function.
  2. Click Edit > Create. A new function line appears on the Action/Event Editor.
  3. In the Event field, type Q.
  4. From the Action drop-down list, click Reserved.
  5. From the Argument drop-down list, click *QUERY.
Define remaining database actions
  • Repeat steps 2 through 5 in Define Query database action one time for each action listed in the following table, substituting the appropriate event, action, and argument for each:
    Event | Action | Argument
    U | Reserved | *UPDATE
    D | Reserved | *DELETE
    C | Reserved | *CLEAR
    E | Reserved | *TERM
Complete program actions
  1. On the Action/Event Editor, click Apply.
  2. Close the Action/Event Editor. The Action/Event Browser shows all assigned actions.
Assign an action to the PF3 key
Previously, we assigned the PF3 key to bypass field edits. In this section, we assign the PF3 key to also escape from the Parts Update program and transfer you back to the Main Menu program.
  1. From the Control Type list, choose KEYS.
  2. On the Control Name list, double-click PF1-PF12. The Action/Event Editor dialog box appears.
  3. Click the PF3 row.
  4. From the Action drop-down list, select XCTL.
  5. In the Argument field, type bldrcmnu.
  6. Click Apply.
  7. Close the Action/Event Editor. The Action/Event Browser reappears.
Code working-storage fields
The screen fields that we created using the Screen Painter and mapped to working-storage fields in a previous tutorial need corresponding working-storage fields in our program. In Online Express we can code a record for these fields as Miscellaneous User Code using the S-COBOL language, which is a short-hand version of COBOL. S-COBOL is read by the Micro Focus Generator (MFG) and translated into native COBOL. The record coded here receives the data from our VSAM file.
  1. On the Action/Event Browser on the Control Type list, click All.
  2. On the Control Name list, click All.
  3. Click Action/Event > Edit Miscellaneous User Code. This brings up your default editor.
  4. Code the following S-COBOL record into the editor. Code the WS on the first line in column 4. Continue the line starting in column 12. Indent the code for the remainder of the record under the first line. Use the field on the bottom right of the editor to be sure you have the code placed in the proper columns.
       WS      WS-MASTER-RECORD
             WS-PART-NUMBER      9(8)
             WS-SHORT-DESC       X20
             WS-UNITS-INSTOCK    99
             WS-BASE-PRICE       9(4)V99
             WS-DIMENSIONS       X8
             FILLER              X36
  5. To save your source code, click File > Save.
  6. Exit the editor. This returns you to the Action/Event Editor.

This completes the tutorial. Next, please complete Tutorial: Define Database Access.

Parent topic: Tutorials: AppMaster Builder
Related concepts
Field Mapping
Related reference
Action/Event Browser
Action/Event Editor


Tutorial: Define Database Access

Define database calls and customize database access.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

An Online Express database call defines which record(s) or table(s) to read, and which database actions to perform on them. Each field action that you specify in the Action/Event Editor requires a corresponding database action that defines the field action.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project
  • Tutorial: Set Preferences and View Properties
  • Tutorial: Learn Screen Painter Techniques
  • Tutorial: Paint a Screen
  • Tutorial: Assign Screen Field Edits
  • Tutorial: Code a User Rule
  • Tutorial: Map Screen Fields
  • Tutorial: Define Program Actions

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective and, from the Project Explorer, double-click the BLDRUPD program to start Online Express.

Assign a database call
  1. From Online Express, click File > Database Access. The Database Access Summary dialog box appears. The dialog box is initially blank. From here you access other dialog boxes to define the database call specifications.
  2. Click Edit > Create. The Attributes dialog box appears. Here, you can view or override attributes of the call.
  3. Click OK to accept all default attributes. The Record Selection dialog box appears, showing the record name, PART-MASTER-REC, defined in the APSUPD data view.
  4. To define a call to the record that enables end users to obtain data, modify data, or delete data, check Obtain, Modify, and Erase.
  5. Click Next. The Add/Delete Fields for Qualification dialog box appears, showing PART-MASTER-REC in the Record Name field and PM-PART-NBR in the Cobol Name field.
  6. Click Select All to activate the PART-MASTER-REC record.
  7. Click Next. The Qualification dialog box appears with the Record and Field names supplied from the action just completed.
    Note: The = operator indicates that the values for the fields in the Field and Value fields must match. Therefore, the value that the end user enters into the PART-NBR field on the Parts Update screen must be equal to a part number in the database record.
  8. Click Finish. This returns you to the Database Access Summary window, which now shows the database access call defined for this program. The OME in the Actions field indicates that this program can Obtain, Modify, and Erase PART-MASTER-REC records.
Set database call generation options
We need to set the Online Express generation options to make sure that the MFG generates the database call and code to then clear the screen.
  1. Click File > Express Generation Options. The Express Generation Options dialog box appears.
  2. On the Express Generation Options dialog box, be sure the following options are checked or selected:
    Generate Control Point Comments
    Generates comments in programs identifying control events.
    Generate Database calls
    Generates your database access specifications into database calls. When testing the program teleprocessing functions without accessing a database, you can deactivate this option to suppress the generation of database calls.
    Clear Screen with Spaces
    Clears all screen entry fields with spaces.
  3. On the System Message Field drop-down list, click SYSTEM. This sets the SYSTEM field as the system message field.
  4. Click OK. This returns you to the Database Access Summary window.
Define Obtain normal status
We now need to customize the Obtain database call event to:
  • Move the information in the VSAM database record to the appropriate Working-Storage fields
  • Call the Customizer user rule we coded in a previous tutorial
  • Move the information calculated by the user rule to its appropriate screen field
  1. Click Database Access > Call Tailoring. The DB Call Tailoring Browser appears.
  2. On the Database Actions list, double-click Obtain. The DB Call Tailoring Editor appears.
  3. In the Events column, click Normal Status.
  4. On the Action drop-down list, click Local Code.
  5. Click Edit Code. The default editor appears.
    Note: If prompted to create a file, click No.
  6. Type in the following code, starting in column 12:
               MOVE PART-MASTER-REC TO WS-MASTER-RECORD
           CALC-INV-VALUE WS BASE-PRICE
           ... UNITS-INSTOCK
           MOVE WS-INVENTORY-VALUE TO BLDRCU-INV-VALUE

    The second and third lines of this code call the CALCINV Customizer rule and supply its three required parameters. CALC-INV-VALUE is the name of the rule, WS is the value for the &PRE parameter, and BASE-PRICE and UNITS-INSTOCK are the values for &PRICE-FIELD and &UNITS-FIELD respectively. This code expands into the following native COBOL:

               IF WS-BASE-PRICE = ZERO
                OR WS-UNITS-INSTOCK = ZERO
               MOVE ZERO TO WS-INVENTORY-VALUE
           ELSE
               COMPUTE WS-INVENTORY-VALUE =
                   WS-BASE-PRICE
                   * WS-UNITS-INSTOCK
  7. To save your source code, click File > Save.
  8. Close the editor. The DB Call Tailoring Editor reappears, showing the value PAINTED in the Argument field.
  9. Click Apply.
  10. To close the Database Call Tailoring Editor, click the x icon in the upper right corner of the dialog box. This returns you to the Database Call Tailoring Browser.
Define Obtain error status
To further customize the Obtain call, we define its error status:
  • Override the standard error message for the Obtain call with a text message
  • Provide code that clears the screen fields when an error is encountered
  • Ensure that the program aborts when it encounters an error
  1. In the Events column of the DB Call Tailoring Editor, click Error Status.
  2. On the Action drop-down list, click Local Code.
  3. Click Edit Code. The default editor appears.
    Note: If prompted to create a file, click No.
  4. To clear the screen fields, type the following native COBOL code, starting each MOVE statement in column 12.
                MOVE SPACES TO BLDRCU-SHORT-DESC-INPT
            MOVE SPACES TO BLDRCU-UNITS-INSTOCK-INPT
            MOVE SPACES TO BLDRCU-BASE-PRICE-INPT
            MOVE SPACES TO BLDRCU-DIMENSIONS-INPT
  5. To save your source code, click File > Save.
  6. Close the editor. The DB Call Tailoring Editor reappears, showing the value PAINTED in the Argument field.
  7. In the Error Message entry field, type Part number entered not found.
  8. To indicate that the error message is text, click Text on the Error Message Type drop-down list.
  9. Ensure that Abort On Error is checked (default).
  10. Click Apply.
  11. To close the Database Call Tailoring Editor, click the x icon in the upper right corner of the dialog box. This returns you to the Database Call Tailoring Browser.
Define Modify before access
Here, we provide local code for the Modify call that ensures data is populated into the proper fields.
  1. On the Database Actions list, double-click Modify. The DB Call Tailoring Editor appears.
  2. In the Events column, click Before Access.
  3. On the Action drop-down list, click Local Code.
  4. Click Edit Code. The default editor appears.
    Note: If prompted to create a file, click No.
  5. Type in the following code, starting in column 12:
               PM-SHORT-DESC = WS-SHORT-DESC
           PM-UNITS-INSTOCK = WS-UNITS-INSTOCK
           PM-BASE-PRICE = WS-BASE-PRICE
           PM-DIMENSIONS = WS-DIMENSIONS
  6. To save your source code, click File > Save.
  7. Close the editor.
  8. On the DB Call Tailoring Editor, click Apply.
  9. Close the DB Call Tailoring Editor. The DB Call Tailoring Browser reappears, showing a summary of the database call customization.
  10. Close the Database Call Tailoring Browser and the Database Access Summary dialog box.
Note: The Erase call requires no tailoring because the default logic supplied by AMB for each is sufficient for the purposes of our sample application.
Assign a savekey
Finally, we define database access for the savekey field we painted on the BLDRCU screen.
  1. Click File > Savekey Specification. The Express Savekey Data dialog box appears.
  2. From the Non Repeated Savekey list box, click SAVEKEY.
  3. Click OK. This returns you to the Action/Event Browser.
  4. Close Online Express.
  5. Click Yes to save your changes. This returns you to the AppMaster Builder perspective.

This completes the tutorial. Next, please complete Tutorial: Generate and Compile the Application.

Parent topic: Tutorials: AppMaster Builder
Related reference
Database Access Summary
Attributes
Record Selection
Add/Delete Fields for Qualification
Qualification
Express Generation Options
Express Savekey Data
Database Call Tailoring Browser


Tutorial: Generate and Compile the Application

Generate the BLDRAPPL application in AppMaster Builder, and automatically compile in Enterprise Developer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

We set the generation options for the BLDRAPPL application when we defined the application in AppMaster Builder. BLDRAPPL is configured to put generated code into a specified Enterprise Developer project, where it is compiled automatically.

Requirements

Before attempting this tutorial, you must complete:

  • Tutorial: Start AppMaster Builder in Enterprise Developer for Eclipse
  • Tutorial: Create a User Area
  • Tutorial: Create Projects
  • Tutorial: Add Objects to the AMB Project
  • Tutorial: Set Preferences and View Properties
  • Tutorial: Learn Screen Painter Techniques
  • Tutorial: Paint a Screen
  • Tutorial: Assign Screen Field Edits
  • Tutorial: Code a User Rule
  • Tutorial: Map Screen Fields
  • Tutorial: Define Program Actions
  • Tutorial: Define Database Access

If you have closed Enterprise Developer, start it; then open the AppMaster Builder perspective.

Generate and compile BLDRAPPL
  1. From the Project Explorer, expand c:\amb_tutorials\BLDRAPPL\dev1.
  2. Right-click BLDRAPPL; then select Generate Application.
  3. To watch the generation processing, click Window > Show View > Console.
View generated code
  1. In Eclipse, open the COBOL Explorer.
  2. Expand the AMB_BLDRAPPL project.
  3. Expand COBOL Programs, Copybooks, and BMS Source Files.
  4. Double-click an object in any of these folders to see the generated source code.
This completes the series of AppMaster Builder tutorials. From here, you can:
  • Debug the application from the Enterprise Developer COBOL perspective. See Debugging in Eclipse for more information.
  • Deploy and run the application on Enterprise Server. See Deploying COBOL Applications for more information.
  • Deploy the application to the mainframe.
Parent topic: Tutorials: AppMaster Builder
Related concepts
Generating Code


Native COBOL Tutorials

  • Tutorial: Creating a Native COBOL Application
  • Tutorial: Running Unit Tests in the IDE
    Using the Micro Focus Unit Testing Framework, you can create, run, and debug unit tests that test the application logic in the native AirportDemo sample supplied with Enterprise Developer.
  • Tutorials: Interface Mapping Toolkit
  • Tutorials: OpenESQL Assistant
    Use OpenESQL Assistant to generate a COBOL application that contains SQL queries.
  • Tutorial: Data File Editor
  • Tutorial: Classic Data File Tools
    Shows you how to convert a data file to a variable length indexed sequential file, and then view it in various ways, formatted and unformatted, using the Classic Data File Editor.
  • Tutorial: Using the Callable File Handler
Parent topic: Getting Started


Tutorial: Creating a Native COBOL Application

This tutorial is an introduction to developing applications using Enterprise Developer. It walks you through the main steps of creating a COBOL application:

  1. Creating a local Eclipse COBOL project
  2. Creating a COBOL program, adding it to the project, then compiling the source code
  3. Running and then debugging the application

The code for this demonstration is a COBOL program for the Tictac game. The code uses a number of features that demonstrate the particular aspects of your product and it's recommended that you use this program for the tutorial. You can, of course, use your own COBOL program.

The tutorial follows a logical sequence of application development. Use the Next and Previous links to move between the tutorial steps.

Note: This product Help provides an introduction to Eclipse, its features and an overview of the development lifecycle in the IDE. See Introduction to Eclipse for more details.
  1. Creating a Project
  2. Adding Source Code and Building the Project
  3. Create a build configuration
  4. Running the Application
  5. Launch a Debug Session
Parent topic: Native COBOL Tutorials


Creating a Project

The first step in creating an application is to create an Eclipse project. You are going to create a local project as you will develop and run the application on your machine.

To do this:

  1. Launch Enterprise Developer. Specify a path for the Eclipse workspace when prompted.

    If this is the first time you start Eclipse, the IDE displays the Eclipse Welcome page. Click Open Team Developer Perspective which is the default perspective in Enterprise Developer.

    If the IDE does not start in the Team Developer perspective, to change to it, click Window > Perspective > Open Perspective > Other, click Team Developer (default), and then click OK.

    Perspectives are an Eclipse concept and they include the views, menus and options relevant to your activity. The Team Developer perspective shows the Application Explorer view, Outline and Console views, among others. The perspective is customizable, so you can choose your own views.

  2. Select File > New > Other .

    The New dialog box is displayed.

  3. Expand Micro Focus COBOL folder, and then click COBOL Project.
  4. Click Next.

    The New COBOL Project dialog box is displayed.

  5. In the Project name field, type tictac.
  6. By default, the project will be created in the workspace that you selected when you started the Eclipse session. You can change this by un-checking Use default location and selecting a different location.
  7. Click Finish.
You have now created a COBOL project and it is displayed in the Application Explorer view under the Enterprise Development Projects.
Parent topic: Tutorial: Creating a Native COBOL Application
Next topic: Adding Source Code and Building the Project


Adding Source Code and Building the Project

Once you have created a project, you need to add the source files to it and then compile the project. To add a new file to the project:

  1. In the Application Explorer view, expand Enterprise Developer@Windows n > Enterprise Development Projects.

    This displays your new project.

  2. Select your project in the Application Explorer view and click File > New > COBOL Program .

    This starts the New COBOL Program wizard.

  3. In the New file name field, type tictac.cbl.
  4. Click Finish.

    This creates a new COBOL source file from the default template and opens it in the editor. The file is shown under the project in the Application Explorer view.

  5. Copy and paste the following COBOL code into the editor, overwriting the existing text:
           identification division.
           program-id. tictac.
       environment division.
       configuration section.
           source-computer. ibm-pc.
           object-computer. ibm-pc.
       special-names.
           console is crt.

       working-storage section.
       01 tictac-00.
        02 tictac-q.
           03 game             pic x(10) value spaces.
           03 filler-0         pic x(70) value spaces.
           03 question         pic x(20) value spaces.
        02 filler.
           03 filler-1         pic x(414) value all spaces.
      *    03 tictac-00-0735   pic x(17) value "7º      8º      9".
           03 tictac-00-0735   pic x(17) value "7|      8|      9".
           03 filler-2         pic x(64) value all spaces.
           03 tictac-00-0836   pic x(09) value "|       |".
           03 filler-3         pic x(71) value all spaces.
           03 tictac-00-0936   pic x(09) value "|       |".
           03 filler-4         pic x(64) value all spaces.
           03 tictac-00-1029 pic x(23) value "-----------------------".
           03 filler-5         pic x(63) value all spaces.
           03 tictac-00-1135   pic x(17) value "4|      5|      6".
           03 filler-6         pic x(64) value all spaces.
           03 tictac-00-1236   pic x(09) value "|       |".
           03 filler-7         pic x(71) value all spaces.
           03 tictac-00-1336   pic x(09) value "|       |".
           03 filler-8         pic x(64) value all spaces.
           03 tictac-00-1429 pic x(23) value "-----------------------".
           03 filler-9         pic x(63) value all spaces.
           03 tictac-00-1535   pic x(17) value "1|      2|      3".
           03 filler-10        pic x(64) value all spaces.
           03 tictac-00-1636   pic x(09) value "|       |".
           03 filler-11        pic x(71) value all spaces.
           03 tictac-00-1736   pic x(09) value "|       |".
           03 filler-12        pic x(595) value all spaces.
       01 entry-array.
           03 entry-char       pic x               occurs 9 times.
       01 check-array.
           03 check            pic s99     comp  occurs 9 times.
       01 xcount               pic 9(2)    comp.
       01 ocount               pic 9(2)    comp.
       01 factor               pic s9(2)   comp.
       01 char                 pic x  value x"9c".
       01 char9 redefines char pic 9.
       01 idx                  pic 9(2)    comp.
       01 result               pic 9(2)    comp.
       01 cursor-pos.
           03 row              pic 9(2)    comp  value 99.
           03 filler           pic 9(2)    comp  value 99.
       01 address-init.
           03 filler           pic 9(4)    value   1732.
           03 filler           pic 9(4)    value   1740.
           03 filler           pic 9(4)    value   1748.
           03 filler           pic 9(4)    value   1332.
           03 filler           pic 9(4)    value   1340.
           03 filler           pic 9(4)    value   1348.
           03 filler           pic 9(4)    value   0932.
           03 filler           pic 9(4)    value   0940.
           03 filler           pic 9(4)    value   0948.
       01 address-array        redefines   address-init.
           03 addr             pic 9(4)    occurs 9 times.
       01 location             pic 9(4).
       01 game-lines value     "147123311113332436978979".
           03 a                pic 9       occurs 8 times.
           03 b                pic 9       occurs 8 times.
           03 c                pic 9       occurs 8 times.
       01 i                    pic 9(2)    comp.
       01 j                    pic 9(2)    comp.
       01 moves                pic 9(2)    comp.

       78 clear-screen        value x"e4".
       78 sound-bell          value x"e5".

       procedure division.
       play-game section.
       play-1.
           perform with test after
               until char not = "Y" and char not = "y"
               call clear-screen

               display
                   "To select a square type a number between 1 and 9"
                   upon crt
               perform init
               move "Shall I start ? " to question
               perform get-reply
               if char = "Y" or char = "y"
                     move 10 to check(5)
                   perform put-move
               end-if
               perform new-move until game not = spaces
               move "Play again ?    " to question
               perform get-reply
           end-perform.

       play-stop.
           display space
           stop run.

       get-reply section.
           display tictac-q at 0201
           accept char at 0317 with no-echo auto-skip
           move spaces to question
           display tictac-00 at 0201.

       init section.
           move "y" to char
           move spaces to entry-array
           move low-values to check-array
           move spaces to game
           move zero to moves.

       new-move section.
           perform get-move with test after until char9 not = 0
           perform move-check
           if game not = "stalemate"
               move low-values to check-array
               perform check-line varying i from 1 by 1
                               until i > 8 or game not = spaces
               if game not = "You win"
                   perform put-move
               end-if
               if game = "I win" or game = "You win"
                     perform varying idx from a(j) by b(j)
                                                until idx > c(j)
                         move addr(idx) to location
                         move entry-char(idx) to char
                         display char at location with blink highlight
                     end-perform
               end-if
           end-if.

       check-line section.
           move zero to xcount,ocount,factor
           perform count-up varying idx from a(i) by b(i)
                                            until idx > c(i)
           if ocount = 0 or xcount = 0
               evaluate true
               when ocount = 2
                   if i = 4
                       move 6 to j
                       move zero to xcount,ocount
                       perform count-up varying idx from a(j) by b(j)
                                                until idx > c(j)
                       if xcount = 3
                           move 6 to i
                       end-if
                   end-if
                   if xcount not = 3
                       move 50 to factor
                       move "I win" to game
                       move i to j
                   end-if
               when xcount = 2
                   move 20 to factor
               when ocount = 1
                   move  4 to factor
               when xcount = 1
                   if entry-char(5) = "x"
                       move  1 to factor
                   else
                       move -1 to factor
                   end-if
               when ocount = 0
                   if xcount = 0
                       move  2 to factor
                   end-if
               end-evaluate
           end-if
           if xcount = 3
               move "You win" to game
               move i to j
           else
               perform varying idx from a(i) by b(i) until idx > c(i)
                   if entry-char(idx) = space
                       add factor to check(idx)
                   end-if
               end-perform
           end-if.

       count-up section.
           if entry-char(idx) = "X"        add 1 to xcount
           else if entry-char(idx) = "O"   add 1 to ocount.

       put-move section.
           move zero to idx
           move -99 to factor
           perform find-pos varying i from 1 by 1 until i > 9
           move "O" to entry-char(idx)
           perform move-check.

       move-check section.
           move addr(idx) to location
           move entry-char(idx) to char
           display char at location
           add 1 to moves
           if moves > 8 and game = spaces
               move "stalemate" to game
           end-if.

       find-pos section.
           if entry-char(5) = space
               move check(5) to factor
               move 5 to idx
           else
               if check(i) not < factor and entry-char(i) = space
                   move check(i) to factor
                   move i to idx
               end-if
           end-if.

       get-move section.
           display "Please select an empty square" at 0201
           move 0 to char9
           accept char9 at 0231 with auto-skip
           if char9 = 0
               call sound-bell
           else
               move char9 to idx
               if entry-char(idx) = space
                   move "X" to entry-char(idx)
               else
                   move 0 to char9
                   call sound-bell
               end-if
           end-if.
  6. Click File > Save . By default, Eclipse is configured to build projects automatically. If this option has been changed, to manually start a build, select the project in the Application Explorer view and click Project > Build Project.
The progress of the project build is displayed in the Console view.

Building the project creates a new folder in your project - New_Configuration.bin. Expand the folder in the Application Explorer view to see the executable and the .obj (Windows) or .o (UNIX) files.

Parent topic: Tutorial: Creating a Native COBOL Application
Previous topic: Creating a Project
Next topic: Create a build configuration


Create a build configuration

The build configuration settings for the project enable you to specify settings that are passed to the compiler, including pre- and post-build events, and additional library and resource files. This tutorial requires that your project is enabled for debugging.
  1. Right-click your project in the Application Explorer view and select Properties.
  2. Expand Micro Focus and select Build Configurations > COBOL.
  3. Ensure New Configuration [Active] is selected.
  4. Ensure that the settings for your project match these:
    Field | Value
    Output Path | New Configuration.bin
    Target Type | "Single Executable File"
    Enable configuration specific settings (in the Override Project COBOL settings section) | Selected
    Compile for debugging | Selected
  5. Click OK.
Parent topic: Tutorial: Creating a Native COBOL Application
Previous topic: Adding Source Code and Building the Project
Next topic: Running the Application


Running the Application

Running an application that you develop in Eclipse requires that you first create a launch configuration. To create a run configuration and run the application:
  1. Select your project in the Application Explorer view and from the main menu click Run > Run Configurations

    The Run Configurations dialog box is displayed.

  2. Create a new launch configuration in one of the following ways:
    • Double-click the COBOL Application tree item, or
    • Click the COBOL Application tree item, and then click New launch configuration (New launch configuration).
    This creates a new COBOL launch configuration with tictac loaded as the project to use and New_Configuration.bin/tictac.exe (Windows) or New_Configuration.bin/tictac (UNIX) as the main program to run.
  3. Click Run.

    This starts the application by opening a console window. Follow the instructions in the window to play the game.

  4. To stop the application, close the console window.
Parent topic: Tutorial: Creating a Native COBOL Application
Previous topic: Create a build configuration
Next topic: Launch a Debug Session


Launch a Debug Session

There are several debug options and configurations. In the following steps, you create a local debug session.
  1. Select your project in the Application Explorer view view and from the main menu click Run > Debug Configurations

    This starts the Debug Configurations dialog box and selects the run configuration you created before. You can either use this configuration or create a new one, especially for debugging.

  2. Create a new debug configuration. You can do this in two ways:
    • Double-click the COBOL Application tree item, or
    • Click the COBOL Application tree item, and then click New launch configuration (New launch configuration).
  3. Ensure that settings for your configuration match these:
    Field | Value
    Name | "tictac_configuration"
    COBOL Project | "tictac"
    Program is part of project build configuration | Selected, and with a value of "New Configuration"
    Main program or executable to debug | "New_Configuration.bin/tictac.exe (Windows) or New_Configuration.bin/tictac (UNIX)"
  4. Click Debug.

    By default, a Confirm Perspective Switch dialog box is displayed. This is because Eclipse offers a different perspective for debugging that has views that provide relevant information that you might need. Click Yes to confirm the switch and start debugging.

    Some of the view that you see in this perspective are:

    • The Debug view shows the threads that are running in the application. For each thread, the status execution positions are shown. In addition, an application window opens where the specific steps in your application will be displayed as debugging takes place.
    • The Variables view displays data items and internal file names that are referenced on the current line and in the previous stepped statement. This allows you to view the before and after values or statuses of a particular item. You can set breakpoints by double-clicking in the margin at the far left of the source view and then run the program to the breakpoint by clicking Run > Resume.

    For more information on debugging your application, see Debugging Features and Techniques in Eclipse.

  5. To stop debugging, click Terminate. Alternatively, press Ctrl+F2.
  6. To change back to the Team Developer perspective, click Team Developer at the top right corner.
Parent topic: Tutorial: Creating a Native COBOL Application
Previous topic: Running the Application


Tutorial: Running Unit Tests in the IDE

Note: This tutorial is applicable to Windows platforms only.

This tutorial utilizes the native AirportDemo sample that is supplied with Enterprise Developer.

The project contains two programs: main.cbl is the main program that contains the user interface code, but aircode.cbl is the program that contains the main application logic, and it is this program that we want to put under test.

In this tutorial, you will create a unit test project and test fixture file that directly calls into aircode.cbl and tests the logic within it. You will create a test case that directly runs one of the functions of the demo (calculating the distance between two airports), and code some test assertions that check for the correct answer. You will also debug the test case, to troubleshoot any problems.

  1. Create a Workspace
  2. Importing the AirportDemo Sample
  3. Creating a Unit Test Project
  4. Creating a Test Fixture
  5. Running the Test
  6. Running the Test Under Code Coverage
  7. Enhancing the Test
  8. Debugging the Failed Test
  9. Fixing and Rerunning the Failed Test
Parent topic: Native COBOL Tutorials
Related concepts
Unit Testing in the IDE


Create a Workspace

For the sake of the tutorial, create a new workspace in which to import the AirportDemo sample and create a unit test project.
  1. Start Eclipse.

    The Eclipse Launcher dialog box appears.

  2. In the Workspace field, type c:\UnitDemo, then click Launch.
    Note: If the dialog box does not appear (because you have elected to load a default workspace each time Eclipse is opened), when the default workspace has loaded, click File > Switch Workspace > Other to display it.

    The directory does not need to already exist; it will be created, if required.

The workspace is created and opened using the Team Developer perspective. The rest of the instructions in this tutorial assume you are using the COBOL perspective, and so you may want to switch to it now, by clicking [image] and selecting COBOL; it is possible to run the tutorial from the Team Developer perspective, but some keystrokes/menu options may be slightly different to the ones noted in the following topics.

If the Welcome page is opened, you can close it using the close icon on the Welcome tab.

Parent topic: Tutorial: Running Unit Tests in the IDE
Next topic: Importing the AirportDemo Sample


Importing the AirportDemo Sample

The AirportDemo application is a good example to use as it is structured in such a way that the application logic that you want to test is separate from the rest of the application (i.e. the main program runner and the interface code).

  1. From within the UnitDemo workspace, click File > Import.

    The Import dialog box appears.

  2. Choose General > Existing Projects into Workspace, and click Next.
  3. In the Select root directory field, click Browse and navigate to your samples folder and click OK.

    The default location for the samples is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Eclipse.

  4. Click Deselect All.

    No projects are selected in the Projects pane.

  5. In the Projects pane, select AirportDemo.
  6. Select Copy projects into workspace.
  7. Click Finish.

    A copy of the project (not the original version) is added to the workspace. For it to work with a unit test project, you need to change the target type of the project.

  8. Change the project target type:
    1. In COBOL Explorer, select AirportDemo, then on the Project menu, click Properties.

      The Properties for AirportDemo dialog box appears.

    2. Select Micro Focus > Build Configurations > COBOL.
    3. On the COBOL screen, click Single Executable Type, and select Single Native Library File.

      Unit test projects are also compatible with projects built to All Int/Gnt Files.

    4. Click Apply and Close.

    If you have the Build Automatically option set (Project menu), the AirportDemo project is automatically built using the compatible target type. If you do not already have this option set, click Project > Build Automatically.

Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Create a Workspace
Next topic: Creating a Unit Test Project


Creating a Unit Test Project

Test fixture files (and the test cases within them) can only be created in a unit test project.

  1. While in the COBOL perspective, select File > New > COBOL Unit Test Project.

    The New COBOL Unit Test Project dialog box appears.

  2. In the Project name field, type TestAirportDemo.
  3. Click Finish.

    The project is created, and displayed in COBOL Explorer.

    Before you add a test fixture file to the project and run it (during which, a COBOL Unit Test run configuration is created), you'll add the environment variable that enables the test run to locate the data file used by the unit tests. (If you do not create the variable before the run configuration is created, you must manually configure it from the Environment tab within the run configuration details once the run configuration has been created.)

  4. Select Project > Properties.

    The Properties for TestAirportDemo dialog box appears.

  5. Click Micro Focus > Run-time Configuration > Environment Variables.
  6. On the Environment Variables page, click Add, then add the following values and click OK:
    • Variable: dd_airports
    • Value: ..\..\AirportDemo\airports.dat
  7. Click OK.
  8. Click Apply and Close.

    Test cases within this unit test project will now use the original data file used by the AirportDemo application.

Next you must add the test fixture file that will contain your test cases.

Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Importing the AirportDemo Sample
Next topic: Creating a Test Fixture


Creating a Test Fixture

You now need to add a test fixture file to the unit test project.

  1. In COBOL Explorer, ensure that the TestAirportDemo project is selected, then select File > New > COBOL Unit Test.

    The New COBOL Unit Test dialog box is displayed.

  2. In the Containing project field, ensure that it states the TestAirportDemo project.
  3. In the New file name field, type DistanceTest.
  4. Select Create unit test from program, click Browse, select the aircode.cbl program (from within the AirportDemo project), then click OK.
  5. Click Finish.

    The DistanceTest.cbl test fixture file is created within the TestAirportDemo unit test project.

  6. Before you can run the unit test project, you need to ensure that it shares the same platform target value as the project under test. In this case, the AirportDemo project is 32 bit, and so the TestAirportDemo project also needs to be set to 32 bit:
    1. Right-click TestAirportDemo and select Properties.
    2. Select Micro Focus > Build Configurations > COBOL.
    3. Ensure that Platform Target is set to 32 bit, then click Apply and Close.
  7. Review the following items that have been added to the resulting fixture file. They are all required to allow you to call into the AirportDemo project:
    • The two copybooks required by the Micro Focus Unit Testing Framework are copied into the project.

    • A test setup and a test case have been created.

    • A procedure pointer has been added to the test setup that enables you to call into the source code, and a level 78 constant for the test case name has been added (to help when creating the different elements of the test case).

    • The Linkage section from the source program has been replicated in the Working-storage section, initialized, and a CALL statement coded in the test case.

    • The project containing the program under test is added to the Projects tab of the Build Path properties.

Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Creating a Unit Test Project
Next topic: Running the Test


Running the Test

By default, the Micro Focus Unit Testing view displays the test cases for the last unit test project that was run, or is empty if a unit test project is yet to be run.
  1. Click the Micro Focus Unit Testing tab. (If it is not already displayed, click Window > Show View > Micro Focus Unit Testing.)

    You will notice that the view does not yet show any test cases. You must first run the unit test project that contains them. Only then will you see the test fixtures (the .cbl files within the project), and test cases within them.

  2. In COBOL Explorer, select TestAirportDemo, then on the Eclipse toolbar, click [image] (Run).

    The project runs and the tests are loaded into the Micro Focus Unit Testing view. This project currently contains one test fixture file (DistanceTest.cbl), which contains one test case (MFUT_TESTAIRCODE). The test case automatically ran when you ran the unit test project.

  3. Select the test case to display the test output in the Test Results pane.

    The test case passes, but that is because it does not actually do anything meaningful yet. In the Enhancing the Test step, we will enhance the test by adding some code to it.

Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Creating a Test Fixture
Next topic: Running the Test Under Code Coverage


Running the Test Under Code Coverage

To produce code coverage statistics during the test run, you must first compile the source application (the project that contains the code to be tested) with code coverage enabled.

  1. First, you need to enable code coverage for the project under test:
    1. In COBOL Explorer, select AirportDemo, then on the Project menu, click Properties.

      The Properties for AirportDemo dialog box appears.

    2. Click Micro Focus > Build Configurations > COBOL.
    3. On the COBOL page, expand the Override project COBOL settings section, check Enable configuration specific settings, then check Enable code coverage.

    4. Click Apply and Close.

      Code coverage is enabled for the AirportDemo project.

  2. Next, you need to enable code coverage in the run configuration that will be launched when the tests are run.
    1. In COBOL Explorer, right-click TestAirportDemo, point to Run As and select Run Configurations.

      The Run Configurations dialog box appears.

    2. In the left-hand pane, select the TestAirportDemo run configuration.

      The details for the run configuration appear in the right-hand pane.

    3. Select the Dynamic Analysis tab.
    4. Check Enable code coverage, click Apply, then click Close.

      Code coverage is enabled for the run configuration used to run the tests.

  3. In the Micro Focus Unit Testing view, click [image] (Run All).

    The test case runs and produces some code coverage statistics.

  4. Select the Code Coverage tab.

    The code coverage details are displayed in the Code Coverage view, grouped under each program name in the AirportDemo project.

  5. Expand AirportDemo > aircode to show the sections.

    As you can see, the test run did not cover much of the source code. Take note of the distance-between-airports section, as we will enhance the test to run this section, and will see different results after the next test run.

Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Running the Test
Next topic: Enhancing the Test


Enhancing the Test

The passing test case does not currently run any meaningful tests on the source code, and so you are going to enhance the test so that it does. You will add code that calculates the distance between two airports, and then check that the correct distance is returned.
  1. In COBOL Explorer, double-click DistanceTest.cbl.

    The program appears in the editor.

  2. The test case code will use a variable called errormessage, and so add the following to the working-storage section:
           01 errormessage pic x(200).
  3. Jump to the MFU-TC-SETUP-PREFIX & TEST-TESTAIRCODE entry point, and then after the comment line that reads *> Add any other test setup code here, add the following code:
               move 4 to lnk-function
           call "aircode" using
                       by value lnk-function
                       by value lnk-airport1
                       by value lnk-airport2
                       by value lnk-prefix-text
                       by reference lnk-rec
                       by reference lnk-distance-result
                       by reference lnk-matched-codes-array
           end-call

    This code makes a call to the code under test, which attempts to open the data file.

  4. Now jump to the MFU-TC-PREFIX & TEST-TESTAIRCODE entry point, and add the following lines of code before the first call statement:
             move 2 to lnk-function
         move "LHR" to lnk-airport1 *> London Heathrow
         move "SEA" to lnk-airport2 *> Seattle
  5. Within the same section, after the comment line that reads *> Verify the outputs here, add the following code:
              *> Assertions to check that the correct distance is returned
           if function numval(distance-miles) not equal 4787
               string "Incorrect distance in miles returned - "
                       distance-miles delimited by size
                       x"0" delimited by size
                       into errormessage
               end-string
               call MFU-ASSERT-FAIL-Z using errormessage
           end-if

           if function numval(distance-km) not equal 4787
               string "Incorrect distance in kilometers returned - "
                       distance-km delimited by size
                       x"0" delimited by size
                       into errormessage
               end-string
               call MFU-ASSERT-FAIL-Z using errormessage
           end-if

    These are the assertions that check that the correct values are calculated for the distance (in miles and km) between the two airports, and if the calculation is incorrect, the test fails.

  6. Finally, position the cursor immediately after the test setup section (just before the InitializeLinkageData section), type testteardown, press Ctrl+Space, press Enter, then select TEST-TESTAIRCODE from the list of level-78 items offered.

    An MFU-TC-TEARDOWN-PREFIX & TEST-TESTAIRCODE entry point is added to the program.

  7. Within this section, add the following code:
               move 5 to lnk-function
           call "aircode" using
                       by value lnk-function
                       by value lnk-airport1
                       by value lnk-airport2
                       by value lnk-prefix-text
                       by reference lnk-rec
                       by reference lnk-distance-result
                       by reference lnk-matched-codes-array
           end-call

    This closes the data file after the test case has run.

  8. To run the test case, in the Micro Focus Unit Testing view, click [image] (Rerun Tests From Last Run).

    The test case reruns, but should fail with the following output:

Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Running the Test Under Code Coverage
Next topic: Debugging the Failed Test


Debugging the Failed Test

To debug the test case, you must set a breakpoint, then use the Debug option within the Micro Focus Unit Testing view.
  1. Just as you would when debugging any other program, you need to set a breakpoint beforehand; if DistanceTest.cbl is not already displayed in the editor, open it from COBOL Explorer.

    The test program is displayed in the editor.

  2. Set a breakpoint by double-clicking on the marker bar to the left of the line that starts:
    string "Incorrect distance in kilometers returned...
  3. In the Micro Focus Unit Testing view, right-click MFUT_TESTAIRCODE, then select Debug.
  4. If you are prompted to launch the Debug perspective, click Yes.

    The debug engine starts, and test execution stops at the breakpoint.

  5. Hover over the distance-km variable to see the distance between the two airports (Heathrow and Seattle).

    The distance has been calculated as 7,703 (which happens to be the correct distance), and so the code is executing as it should. It is also asserting a failure correctly, but that is because the wrong value (4,787) was being tested for, as you can see from the following line:

    if function numval(distance-km) not equal 4787...
  6. Press Ctrl+F2 to stop debugging.
Now that you know why the test failed, you can fix the code to test for the correct values.
Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Enhancing the Test
Next topic: Fixing and Rerunning the Failed Test


Fixing and Rerunning the Failed Test

You need to fix the test so that it is checking for the correct distance.
  1. Switch back to the COBOL perspective by clicking [image].

    Your workspace is displayed using the COBOL perspective.

  2. With DistanceTest.cbl displayed in the editor, replace the value 4787 with 7703, so that the IF statement now reads:
               if function numval(distance-km) not equal 7703
               string "Incorrect distance in kilometers returned - "
                       distance-km delimited by size
                       x"0" delimited by size
                       into errormessage
               end-string
               call MFU-ASSERT-FAIL-Z using errormessage
           end-if
  3. Press Ctrl+S to save the changes.
  4. In the Micro Focus Unit Testing view, click [image] (Run Failed).

    The failed test is rerun, and now passes.

  5. Select the Code Coverage tab, and expand AirportDemo > aircode again. Notice how the statistics have changed since we enhanced the test, especially the coverage for distance-between-airports, which was 0% when we last checked.

This concludes the tutorial.
Parent topic: Tutorial: Running Unit Tests in the IDE
Previous topic: Debugging the Failed Test


Tutorials: Interface Mapping Toolkit

Restriction: This topic applies to Windows environments (local development) only.
  • Set Build and Interface Mapper Preferences
    Set Eclipse and Interface Mapper preferences required to complete these tutorials.
  • Tutorial: SOAP Service Interface
    Walks you through the process of defining a SOAP service interface using the Interface Mapping Toolkit (IMTK), deploying it to an enterprise server instance, and generating and running a client to access it.
  • Tutorial: EJB Service Interface
    Walks you through the process of defining an Enterprise Java Bean (EJB) service interface using the Interface Mapping Toolkit (IMTK), deploying it to an enterprise server instance, and generating and running a client to access it.
  • Tutorial: REST Service Interface
    Walks you through the process of defining a Representational State Transfer (REST) service interface using the Interface Mapping Toolkit (IMTK), deploying it to an enterprise server instance, and generating and running a client to access it.
Parent topic: Native COBOL Tutorials


Set Build and Interface Mapper Preferences

Set Eclipse and Interface Mapper preferences required to complete these tutorials.
Restriction: This topic applies to Windows environments (local development) only.

Set Interface Mapper Preferences

Before you begin the tutorials, you need to set the properties for the Interface Mapper to show both the Reusable Fields and COBOL Assignments panes. You use one or both of these panes while working through the tutorials.

  1. From the Main Menu in Eclipse, click Window > Preferences.
  2. Expand Micro Focus > Service Interfaces; then click Interface Mapper.
  3. Check both Show Reusable Fields pane and Show COBOL Assignments pane; then click OK.
    Note: If a Preference Synchronization dialog box appears, click No - Preferences will be saved locally.; then click OK.

Set Build Automatically

In Eclipse, you can set your project to build automatically each time a change is made to the project. These tutorials assume that Build Automatically is turned on. To ensure that this is the case:

  1. From the Main Menu, click Project.
  2. Do one of the following:
    • If the Build Automatically menu option has a check mark to its left, it is already turned on. No further action is required.
    • If the Build Automatically menu option does not have a check mark to its left, click the option to turn it on.
Parent topic: Tutorials: Interface Mapping Toolkit
Related concepts
Prerequisites
Prerequisite


Tutorial: SOAP Service Interface

Walks you through the process of defining a SOAP service interface using the Interface Mapping Toolkit (IMTK), deploying it to an enterprise server instance, and generating and running a client to access it.
Restriction: This topic applies to Windows environments (local development) only.

Prerequisite

Before beginning this tutorial, complete the instructions in Set Build and Interface Mapper Preferences .

Overview

In this tutorial, you work through the following tasks:

  • Review the code in the COBOL demonstration application to become familiar with how it works
  • Create a project for the COBOL program service interface
  • Define a Web Services service interface to access the COBOL application
  • Deploy the service interface to the enterprise server
  • Generate and deploy a Web Services client to access the service
  • Run the client, accessing the service

If you are not familiar with the concept and implementation of a service interface, take some time to review the introductory information and other relevant topics for the IMTK before beginning the tutorial.

Complete this tutorial by following the instructions in the following topics in the order listed here. The bottom of each topic provides Next topic and Previous topic navigational links to help you proceed through the tutorial in its proper sequence:

  1. Prerequisite
    Describes the setup required to complete this tutorial.
  2. Demonstration Application
    Describes the Schedule demo application used in this tutorial.
  3. Create a Project
    Walks you through the process of creating an Enterprise Developer project for the ScheduleDemo application and its service interface.
  4. Create a Service Interface
    Walks you through the process of creating a SOAP service interface for the ScheduleDemo application.
  5. Define Service Interface Operations
    Walks you through the process of defining service interface details for the ScheduleDemo application.
  6. Create and Configure ESSOAP
    Walks you through the process of creating and configuring an enterprise server instance, ESSOAP, to use in this tutorial.
  7. Deploy a Service Interface
    Walks you through the steps required to associate an enterprise server instance with your project, build the project, set deployment properties, deploy the service interface, and verify the deployment results.
  8. Generate a COBOL Client
    Walks you through the process of generating a COBOL client for the MakeCheckAppt service interface.
  9. Run the MakeCheckAppt Web Service
    Walks you through the process of creating a debug configuration for your new service, and running the client application to access and debug the service.
Parent topic: Tutorials: Interface Mapping Toolkit


Prerequisite

Describes the setup required to complete this tutorial.
Restriction: This topic applies to Windows environments (local development) only.

Before beginning this tutorial, be sure to set up your Enterprise Developer environment as specified in the Set Build and Interface Mapper Preferences topic.

Parent topic: Tutorial: SOAP Service Interface
Next topic: Demonstration Application


Demonstration Application

Describes the Schedule demo application used in this tutorial.
Restriction: This topic applies to Windows environments (local development) only.

The COBOL application that you use in this tutorial is the Schedule demonstration application. The application executables are installed with Enterprise Developer in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Interface Mapping Toolkit\ServiceInterfaces\ScheduleDemo directory by default.

The Schedule demonstration application is a system for scheduling and viewing appointments. The application uses the following source and data members:

  • schedule.cbl
  • common.cpy
  • common_78.cpy
  • common_ex.cpy
  • common_ws.cpy
  • consultants.cpy
  • customerinfo.cpy
  • stores.cpy
  • appoint.dat
  • consultants.dat
  • customers.dat

Using the application, you can either schedule a new appointment, or look up an existing appointment. We recommend that you review the application source code to become familiar with how it works.

Parent topic: Tutorial: SOAP Service Interface
Previous topic: Prerequisite
Next topic: Create a Project


Create a Project

Walks you through the process of creating an Enterprise Developer project for the ScheduleDemo application and its service interface.
Restriction: This topic applies to Windows environments (local development) only.

Create the ProgramSOAP Project

Create a project for your service interface, and add files to the project. This section assumes that Enterprise Developer is started. If you need instructions to get it started, see To start Enterprise Developer. We also assume that the Application Explorer view is showing in Eclipse. In the Application Explorer view, you should see the Enterprise Developer system. If the system is not shown, to load it:

  1. Right-click in the Application Explorer view, and then click Add System(s).
  2. In the Add System(s) dialog box, select ED System and click OK.
  3. Expand the top-level Enterprise Developer entry in the Application Explorer view.
  4. Right-click Enterprise Developer Projects; then click Load Application.

To create the project:

  1. In Eclipse, click File > New > Other.

    This opens the New dialog box.

  2. Expand the Micro Focus COBOL folder, and then click COBOL Project.
  3. Click Next.

    This opens the New COBOL Project Wizard.

  4. In the Project name field, type ProgramSOAP.
  5. Check Use default location; then click Finish.
    Note: If Eclipse prompts you to open the COBOL perspective, click Open Perspective.

    The Application Explorer view now shows the ProgramSOAP project under the Enterprise Developer > Enterprise Development Projects node.

  6. From the Application Explorer view, right-click the ProgramSOAP project and select Import from the context menu.

    This opens the Import dialog box.

  7. Expand General and click File System.
  8. Click Next.
  9. Click the Browse button that corresponds to the From directory field, and browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Interface Mapping Toolkit\ServiceInterfaces\ScheduleDemo directory.
  10. Click Select Folder.
  11. On the list of files, check all files except the Readme XML files.
  12. Click Finish.

    This adds the files to the project and builds the project automatically.

Set the COBOL Build Configuration

This IMTK project requires the build action to produce a dynamic link library (.dll) file for the schedule program. To ensure this behavior:

  1. In the Application Explorer view, right-click the ProgramSOAP project; then select Properties from the context menu.
  2. Expand Micro Focus > Build Configurations; then click COBOL.
  3. From the Target Type drop-down list, select All Native Library Files; then click Apply and Close.
Parent topic: Tutorial: SOAP Service Interface
Previous topic: Demonstration Application
Next topic: Create a Service Interface


Create a Service Interface

Walks you through the process of creating a SOAP service interface for the ScheduleDemo application.
Restriction: This topic applies to Windows environments (local development) only.

Create a service interface for the new project.

  1. In the Application Explorer view, right-click the ProgramSOAP project; then select New > Interface > SOAP Web Service from the context menu.
    Note: If SOAP Web Service is not on the menu:
    1. Click Other.
    2. Expand Micro Focus Service Interface
    3. Select SOAP Web Service; then click Next.
  2. In the Web service name field, type MakeCheckAppt.
  3. Select None as the Mapping option.
  4. Click the Browse button associated with Program to map, and navigate to and select the schedule.cbl file in your ProgramSOAP project folder.
  5. Click OK.
  6. Click Finish.

    This starts the Interface Mapper.

Parent topic: Tutorial: SOAP Service Interface
Previous topic: Create a Project
Next topic: Define Service Interface Operations


Define Service Interface Operations

Walks you through the process of defining service interface details for the ScheduleDemo application.
Restriction: This topic applies to Windows environments (local development) only.

Each service interface you create is comprised of a set of operations. In this tutorial, you create one operation for each of the two functions provided by the application.

MakeAppt Operation

The purpose of the MakeAppt operation is to create an appointment and store it in the system.

Create the MakeAppt Operation
  1. From the Application Explorer view, expand ProgramSOAP > Web Services.
  2. Right-click the MakeCheckAppt Web service and select New > Operation from the context menu.
  3. In the Operation name field, type MakeAppt.

    This application contains only one program, schedule.cbl. This program contains one entry point, SCHEDULE, from which to create the operation. By default, SCHEDULE appears in the Entry point field.

  4. Click OK.
  5. From the Application Explorer view, expand MakeCheckAppt.
  6. Double-click MakeAppt.

In the Interface Mapper, you now see that the entry point fields have been placed into the Linkage Section pane on the left.

Define Interface Fields
The Schedule program needs several input items to create an appointment, including variable information such as the customer's name, the identification number of the consultant with whom the appointment is to be made, the date of the proposed appointment, and the desired time slot. You define interface fields to hold this information so that the client can send it to the application.
  1. Drag the following fields from the Linkage Section pane to the MakeAppt Operation - Interface Fields pane:
    • lnk-customer-name
    • lnk-consultant-id
    • lnk-date
    • lnk-time-slot

    This creates interface field names similar to those of the entry point fields from which they were created. The difference is that all dashes (-) are automatically replaced with underscores (_). In addition, a mapping is automatically created between each new interface field and its corresponding entry point field.

    The purpose of the lnk_customer_name, lnk_consultant_id, lnk_date, and lnk_time_slot fields are to hold data that is sent to the application for processing; therefore, they are input fields. The default mapping direction for each of these, Input, is correct.

    Once the Schedule program receives the input information from the client, it sends back a code to indicate whether or not the requested appointment is available. The program field that receives this code is lnk-op-ok. Therefore, you need to create a corresponding interface field, and change its mapping direction from Input (default) to Output.

  2. Drag the lnk-op-ok field from the Linkage Section pane to the MakeAppt Operation - Interface Fields pane.
  3. Double-click lnk_op_ok in the MakeAppt Operation - Interface Fields pane.
  4. Click Output; then click OK.
Define COBOL Assignments
Because the MakeAppt operation executes only one program function, the value required to initialize that function remains constant. In this case, you create a COBOL Assignment field rather than an interface field, and assign it the value required by the program to ensure the execution of the specific function.

From looking at the program source code, you know that when the value in the lnk-operation field is 0, the program executes the set-appt code. Therefore, you want to assign the lnk-operation field a value of 0.

  1. In the Linkage Section pane, right-click the lnk-operation field, and select New Assignment from the context menu.
  2. In the Value field, type 0; then click OK.

    For this particular service, you want to make appointments only for one specific store. When the Schedule program executes, it reads the value in the lnk-id field to identify the store where the appointment is to be made. Therefore, you can provide the same store identification number each time the service runs by assigning a constant value.

  3. In the Linkage Section pane, expand the lnk-store-info group.
  4. In the Linkage Section pane, right-click the lnk-id field, and select New Assignment from the context menu.
  5. In the Value field, type 08780; then click OK.
  6. Click File > Save to save the service interface.
Completed MakeAppt Operation

CheckAppt Operation

The purpose of the CheckAppt operation is to look up an existing appointment and return its details.

Create the CheckAppt Operation
  1. From the Application Explorer view, expand ProgramSOAP > Web Services.
  2. Right-click the MakeCheckAppt Web service and select New > Operation from the context menu.
  3. In the Operation name field, type CheckAppt.

    Once again, the Entry point list shows only the SCHEDULE program, but this time it is already selected for you. This is because each service interface must use the same program across all operations, and you specified the SCHEDULE program in the MakeAppt operation you defined earlier for this same service interface.

  4. Click OK.
  5. From the Application Explorer view, expand MakeCheckAppt.
  6. Double-click CheckAppt.
    Note: If CheckAppt does not appear in the tree view, right-click MakeCheckAppt; then select Refresh from the context menu.

In the Interface Mapper, the entry point fields once again appear in the Linkage Section pane on the left.

Define Interface Fields
The CheckAppt operation uses most of the same interface fields as does the MakeAppt operation, and in addition includes an output array in which the queried appointment appears, if found. Follow these steps:
  1. Drag the following fields from the Linkage Section pane to the CheckAppt Operation - Interface Fields pane:
    • lnk-customer-name
    • lnk-consultant-id
    • lnk-date
    • lnk-op-ok
  2. In the Linkage Section pane, expand the lnk-day group.
  3. Drag the lnk-cust-id field to the CheckAppt Operation - Interface Fields pane. The lnk-cust-id field is an array.

    Because lnk-op-ok and lnk-cust-id are both output fields, you need to change the direction of each from Input to Output.

  4. Double-click lnk_op_ok in the CheckAppt Operation - Interface Fields pane.
  5. Click Output; then click OK.
  6. Apply the two preceding steps to the lnk_cust_id interface field.
Define COBOL Assignments
The CheckAppt operation needs to execute the read-appt application code. Therefore, you need to assign the lnk-operation field a value of 1.
  1. Drag the lnk-operation field from the Linkage Section pane to the COBOL Assignments pane.
  2. In the Value field, type 1; then click OK.

    Just as you did for the MakeAppt operation, you want to assign a constant value for the lnk-id field so you are sure to query the same store each time.

  3. Drag the lnk-id field from the Linkage Section pane to the COBOL Assignments pane.
  4. In the Value field, type 08780; then click OK.
  5. Click File > Save to save the service interface.
The Completed CheckAppt Operation

Parent topic: Tutorial: SOAP Service Interface
Previous topic: Create a Service Interface
Next topic: Create and Configure ESSOAP


Create and Configure ESSOAP

Walks you through the process of creating and configuring an enterprise server instance, ESSOAP, to use in this tutorial.
Restriction: This topic applies to Windows environments (local development) only.

To successfully deploy and run (debug) a Web Services service interface, you must have an enterprise server instance started in Enterprise Server. For these tutorials, you create and configure the ESSOAP enterprise server instance.

Create ESSOAP

In this section, you create the ESSOAP enterprise server instance from the Server Explorer in Enterprise Developer.

  1. If the Server Explorer is not loaded, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. On the Server Explorer, right-click Local [localhost:86]; then select New > Enterprise Server.
  3. In the Name field, type ESSOAP.
  4. Click the Browse button associated with the Template field.

    The default location for Enterprise Server templates is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates.

  5. Double-click ESTemplate.xml to select it.
    Note: If the Template field does not show the path and ESTemplate.xml file, browse to the default location for Enterprise Server templates to find and select the file.
  6. Check the box next to ProgramSOAP to associate the project with the new enterprise server instance.
  7. Click Finish.

Start Enterprise Server Administration

  1. From the Server Explorer, right-click Local [localhost:86]; then click Open Administration Page.

    The Enterprise Server Administration Home page starts in an Enterprise Developer integrated browser.

Configure a Listener Port

When you create a service interface, it is configured by default to use port number 9003 to send messages to Enterprise Server, which listens for incoming messages on its Web Services and J2EE listener. You need to set the endpoint address for the Web Services and J2EE listener to match the port number for the service interface.

  1. On the Enterprise Server Administration Home page, in the Communications Processes column for the ESSOAP server, click the Details button.

    This takes you to the Communications Processes page for Enterprise Server listeners.

  2. Click the Edit button that corresponds to Web Services and J2EE Listener.
  3. Change the contents of the Endpoint Address field to *:9003.
  4. Click OK.

    This returns you to the Communications Processes page.

  5. Click the Edit button that corresponds to Web listener.
  6. Change the value of the New Status field to Stopped. This enables the listener used to deploy the service interface to the ESSOAP server.
  7. Click OK.
  8. Click Home to return to the Home page.
    Important: If you do not have Administrator privileges to the Enterprise Developer installation directory, continue with the configuration. Otherwise, configuration for the ESSOAP enterprise server instance is complete at this point.

Create and Configure a Deployment Folder

Note: The default deployment folder used by Enterprise Server is a subfolder to your Enterprise Developer installation folder. If you have Administrator privileges to the Enterprise Developer installation structure, or if you started Enterprise Developer using Run as Administrator, you are not required to complete this section of the tutorial. Otherwise, you must complete this section to create and configure an alternative deployment folder.
Create the deploy folder
Without Administrator privileges, you cannot deploy to Enterprise Server from the default Enterprise Developer deployment folder. To ensure successful deployment, create a deploy folder in your ProgramSOAP project.
  1. In the Application Explorer view, right-click the project; then select New > Folder > Folder from the context menu.
  2. In the Folder name field, type deploy; click Finish.
Import the .mfdeploy File
The new deploy folder must contain the .mfdeploy configuration file. You import the file from the Application Explorer view.
  1. From the Application Explorer view, right-click the project folder; then select Import from the context menu.
  2. Expand General; then click double-click File System.
  3. Click the Browse button that corresponds to the From directory field, and navigate to
    InstallFolder\deploy

    where InstallFolder is your Enterprise Developer installation folder. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer.

  4. Click Select Folder.
  5. Check .mfdeploy in the right pane.
  6. Click Finish to import the file into the project.
Define the Deployment Folder
Now you need to configure the ESSOAP enterprise server instance by defining the new deploy project folder as the deployment folder.
  1. On the Enterprise Server Administration Home page in the Communications Processes column for your enterprise server instance, click the Details button that corresponds to Listeners.
  2. Click the Listeners tab.
  3. In the row for the Web listener name, click Edit.
  4. Scroll down to the Configuration Information field; then within the field, scroll down until you find the relevant code, then change:
    uploads=<ES>/deploy

    to:

    uploads=ProjectFolder/deploy
    where ProjectFolder is the full path to your project folder, using forward slashes to separate subfolders. For example:
    uploads=c:/Users/Bob/workspace/project-name/deploy
  5. Click OK.
  6. Click Home to return to the Home page.
Parent topic: Tutorial: SOAP Service Interface
Previous topic: Define Service Interface Operations
Next topic: Deploy a Service Interface


Deploy a Service Interface

Walks you through the steps required to associate an enterprise server instance with your project, build the project, set deployment properties, deploy the service interface, and verify the deployment results.
Restriction: This topic applies to Windows environments (local development) only.

To successfully deploy a SOAP service interface to an enterprise server instance, you need to first set some options in Enterprise Developer.

Set Deployment Properties

To ensure that the deployment process runs smoothly, you must set some options that tell Enterprise Developer the name of your enterprise server instance, and where to find certain files.

  1. From the Application Explorer view, expand ProgramSOAP > Web Services
  2. Right-click the MakeCheckAppt Web service; then select Web Service Properties from the context menu.
  3. On the Deployment Server tab, click the Change button that corresponds to the Enterprise Server name field.
  4. In the Server column, click ESSOAP; then click OK.
  5. On the Application Files tab, click Legacy application needs deploying; then click Add Files to add the following files:
    Files | Location | Description
    • appoint.dat
    • consultants.dat
    • customers.dat

    Your project's ProgramSOAP folder

            Data files accessed by the service.
    schedule.dll | Your project's New_Configuration.bin folder | The executable file you need to debug the service.
    These files are copied to the enterprise server instance when you deploy. The .dat files hold the data accessed by the service. The .dll is the executable file you need to debug the service.

Stop Enterprise Server Instances

To ensure that your enterprise server instance does not encounter any port conflicts with other enterprise server instances that use the same listener port, stop all started enterprise server instances as follows:

  1. If the Server Explorer in Enterprise Developer is not active, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. From the Server Explorer, expand Local [localhost:86] to see a list of enterprise server instances.
  3. Right-click each started enterprise server instance, and stop it by selecting Stop from the context menu. Started enterprise server instances show with a green icon Started enterprise server instance.

Start the ESSOAP Enterprise Server Instance

Before deploying your service interface, you must start the ESSOAP instance where the MakeCheckAppt service will run.

  1. If the Server Explorer in Enterprise Developer is not active, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. From the Server Explorer, expand Local [localhost:86] to see a list of available enterprise server instances.
  3. Right-click ESSOAP; then select Start from the context menu.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box.

The Enterprise Server Daemon is then invoked via the Console, starting the enterprise server instance.

Deploy the MakeCheckAppt Web Service

  1. From the Application Explorer view, right-click the MakeCheckAppt Web Service; then click Deploy.
  2. In Eclipse, click the Console tab.
  3. On the icon bar, click the down arrow associated with Display Selected Console Display Selected Console.
  4. Click Service Interfaces Console.

The Console view shows the progression of the deployment process. If deployment was successful, you should see a message: Deployment completed with warnings. If you scroll up to see the log output, notice that the deployment process changed the direction of the slashes in some directory specifications. This is normal behavior for successful deployment.

Note: If the console switches to the Micro Focus Build view after deployment, switch the view back to Service Interfaces Console to review the deployment log.

If deployment ever fails, you should find a message in the Console view indicating why it failed. Also, the failure message contains the path to the deployment log file. You can type the address into a browser and view the log file from there.

View deployment results

Now that your service interface has been deployed as a service running on the ESSOAP enterprise server, you can look at the details of the deployed service Enterprise Server Administration page.

  1. If you have closed the Enterprise Server Administration window in Enterprise Developer, start it again.

    In the row showing information for the ESSOAP enterprise server instance, you should see that the Objects column shows the number of services that this enterprise server instance runs.

  2. Click the Details button for the ESSOAP Services.

    In the row showing your new service, MakeCheckAppt, you'll notice that the Current Status column shows both operations as Available. This means that the service is ready to be accessed by a client.

Parent topic: Tutorial: SOAP Service Interface
Previous topic: Create and Configure ESSOAP
Next topic: Generate a COBOL Client


Generate a COBOL Client

Walks you through the process of generating a COBOL client for the MakeCheckAppt service interface.
Restriction: This topic applies to Windows environments (local development) only.

You can now generate a COBOL client to access the MakeCheckAppt service that you deployed to the ESSOAP enterprise server instance.

  1. From the Application Explorer view, right-click the MakeCheckAppt Web Service; then select Generate Client from the context menu.
  2. On the Generate Client dialog box, click Current project; then click OK.

You can watch the generation process in the Service Interfaces Console. When it is complete, the message "The client generation completed successfully" is displayed, after which Eclipse rebuilds the project. The following files are added to the project in the client folder:

  • MakeCheckAppt-app.cbl
  • MakeCheckAppt-proxy.cbl
  • MakeCheckAppt-copy.cpy
Parent topic: Tutorial: SOAP Service Interface
Previous topic: Deploy a Service Interface
Next topic: Run the MakeCheckAppt Web Service


Run the MakeCheckAppt Web Service

Walks you through the process of creating a debug configuration for your new service, and running the client application to access and debug the service.
Restriction: This topic applies to Windows environments (local development) only.

Create a Debug Configuration

  1. In the Application Explorer view, click the ProgramSOAP project.
  2. From the main menu, click Run > Debug Configurations.
  3. In the left pane, right-click COBOL Enterprise Server; then select New from the context menu.
  4. At the very top of the right pane, type ProgramSOAP into the Name field.
  5. On the General tab click the Browse button that corresponds to the Connection and Server fields.
  6. Select ESSOAP; then click OK.
    Note: If the ESSOAP enterprise server instance is the only instance defined in Enterprise Server, these fields are completed for you.
  7. Under Debugging type, click the Web Service tab.

    This shows that all debug Web services are invoked by a request from the client.

  8. Click Apply; then click Debug.
  9. Answer Yes to any prompts to open views or perspectives.
  10. In the Debug view, you should now see an entry for debugging ProgramSOAP [COBOL Enterprise Server].

Set Breakpoints

You want to be able to see when the client program hands off control to the service running in Enterprise Server. Because the program hands off control at two points in its execution – first to run the MakeAppt operation, and second to run the CheckAppt operation – you set a breakpoint at each hand-off point in the code so you can step through the program.

The code that calls the service is contained in the MakeCheckAppt-proxy.cbl file:

call "InvokeService02"

It appears twice in the program. You want to set a breakpoint just before each of these call statements.

  1. From the Application Explorer view, expand ProgramSOAP > client.
  2. Double-click MakeCheckAppt-proxy.cbl. This places the source code into the COBOL editor.
  3. Press Ctrl+F to search for the following code:
    move 256 to wsc-srvc-faultcode-len
  4. Place your mouse pointer in the left-most column at that line of code and double-click to set a breakpoint.
    Note: When the breakpoint has been set, a dot appears in the left-most column.
  5. Search for the next instance of:
    move 256 to wsc-srvc-faultcode-len
    and set another breakpoint.

Run the COBOL Client

  1. From the Application Explorer view, expand ProgramSOAP > client.
  2. Right-click MakeCheckAppt-app.cbl; then select Debug As > COBOL Application from the context menu.
    Note: If a Confirm Perspective Switch message appears, click Yes.

    This places an entry into the Debug view for the client application.

  3. In the Debug view, right-click the bottom-most entry; then select Resume.
  4. The client invokes a console named runm, and waits for input. In the runm console, complete the fields as follows to set an appointment slot:
    Service Address | leave blank
    Username | leave blank
    Password | leave blank
    Operation | 1
    lnk_customer_name | Benton Riley
    lnk_consultant_id | 8706
    lnk_date.lnk_yyyy | 2525
    lnk_date.lnk_mm | 1
    lnk_date.lnk_dd | 1
    lnk_time_slot | 5

    The client application then resumes execution, and pauses on the move 256 to wsc-srvc-faultcode-len statement.

  5. Switch back to the Debug view.
  6. Press F6 multiple times to step through the code until you have stepped just past the call "InvokeService02" statement.
  7. On the Debug view, expand entries under all Application Thread entries. You should see that the deployed schedule application is now being accessed from Enterprise Server.
  8. Press F8 to resume and terminate execution.

Rerun the COBOL Client

Here you rerun the client, selecting the other operation to see that the appointment has been made.

  1. In the Debug view, right-click the MakeCheckAppt-app.dll entry marked as <terminated>; then select Relaunch from the context menu.
  2. In the Debug view, right-click the bottom-most entry; then select Resume.
  3. Complete the runm fields as follows:
    Service Address | leave blank
    Username | leave blank
    Password | leave blank
    Operation | 2
    lnk_customer_name | Benton Riley
    lnk_consultant_id | 8706
    lnk_date.lnk_yyyy | 2525
    lnk_date.lnk_mm | 1
    lnk_date.lnk_dd | 1

    The client application then resumes execution, and pauses on the move 256 to wsc-srvc-faultcode-len statement.

  4. Press F6 multiple times to step through the code until the appointment you set appears on the list in the runm client. You should see it on line [00005] because it is the fifth appointment set for that day.
  5. From the Debug view, press F8 to resume and terminate execution.
Parent topic: Tutorial: SOAP Service Interface
Previous topic: Generate a COBOL Client


Tutorial: EJB Service Interface

Walks you through the process of defining an Enterprise Java Bean (EJB) service interface using the Interface Mapping Toolkit (IMTK), deploying it to an enterprise server instance, and generating and running a client to access it.
Restriction: This topic applies to Windows environments (local development) only.
In this tutorial, we take you through the following tasks:
  • Review the code in the COBOL demonstration application to become familiar with how it works
  • Create a project for the COBOL program service interface
  • Define a Java/EJB service interface to access the COBOL application
  • Deploy the service interface to the enterprise server as an EJB
  • Generate and deploy a JSP client to access the service
  • Deploy the resource adapter to JBoss
  • Run the JSP client, accessing the service
If you are not familiar with the concept and implementation of a service interface, take some time to review the introductory information and other relevant topics for the IMTK before beginning the tutorial.

Complete this tutorial by following the instructions in the following topics in the order listed here. The bottom of each topic provides Next topic and Previous topic navigational links to help you proceed through the tutorial in its proper sequence:

  1. Prerequisites
    Describes the setup requirements and third-party software required to complete the tutorial.
  2. Demonstration Application
    Describes the BookDemo application used in this tutorial.
  3. Create a Project
    Walks you through the process of creating an Enterprise Developer project for the BookDemo application and its service interface.
  4. Create a Service Interface
    Walks you through the process of creating a service interface for the BookDemo application.
  5. Define Service Interface Operations
    Walks you through the process of defining service interface details for the BookDemo application.
  6. Configure ESDEMO
    Walks you through the process of creating a deployment folder and configuring ESDEMO to use it.
  7. Deploy a Service Interface
    Walks you through the steps required to associate an enterprise server instance with your project, build the project, set deployment properties, deploy the service interface, and verify the deployment results.
  8. Generate and Deploy a JSP Client
    Walks you through the process of generating a JSP client for the ProgramEJB service interface, and deploying it to your JBoss application server.
  9. Deploy the Resource Adapter to JBoss
    Walks you through the steps required to deploy the Micro Focus resource adapter to JBoss.
  10. Run the JSP Client
    Walks you through the process of running the generated JSP client to access the new service.
Parent topic: Tutorials: Interface Mapping Toolkit


Prerequisites

Describes the setup requirements and third-party software required to complete the tutorial.
Restriction: This topic applies to Windows environments (local development) only.

Preferences

Before beginning this tutorial, be sure to set up your Enterprise Developer environment as specified in the Set Build and Interface Mapper Preferences topic.

Third-party Software

To successfully deploy and access a Java service, you must have the Java Development Kit (JDK) and a Java application server installed.

This tutorial provides instructions for using JBoss Application Server version EAP 6.4. Therefore, to complete the tutorial successfully, install and configure the JDK and JBoss software as required.

JDK 1.8
The Java JDK version 1.8 is installed automatically with Enterprise Developer. No further configuration is required.
JBoss EAP 6.4
Using any text editor, edit the standalone.xml configuration file located in standalone/configuration, under your JBoss installation directory.
Edit the <archive-validation>, child of the <subsystem xmlns="urn:jboss:domain:jca:1.1"> element, to disable it:

<archive-validation enabled="false" fail-on-error="true" fail-on-warn="false"/>

As a child of <profile>, add the following <subsystem> to standalone.xml:
<subsystem xmlns="urn:jboss:domain:resource-adapters:1.1">
    <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>
Parent topic: Tutorial: EJB Service Interface
Next topic: Demonstration Application
Related concepts
Set Build and Interface Mapper Preferences


Demonstration Application

Restriction: This topic applies to Windows environments (local development) only.

The demonstration application provided for this tutorial represents a legacy application, that is, one that has already been in production use for some time. Legacy applications are great candidates for improvement using the IMTK because the service you create based on the application enables you to access the application using a new, more modern interface.

The IMTK is designed to use COBOL programs that are subprograms in an application, that is, programs with a Linkage Section. The book.cbl program supplied with the demonstration COBOL legacy application is just such a program. It maintains an indexed file, which is a stock file such as might be in use at a book retailer.

To follow the tutorial you need to understand the outline logic of the book.cbl program and its parent program, booktest.cbl even though we do not directly use the parent program. You might want to look at the COBOL source to get familiar with it. By default, it is in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Interface Mapping Toolkit\ServiceInterfaces\BookDemo (Windows) or $COBDIR/demo/Interface Mapping Toolkit/ServiceInterfaces/BookDemo (UNIX) directory. You can display it in Eclipse or any text editor.

book.cbl performs four actions:
  • Read record
  • Add record
  • Delete record
  • Next record
Using the following parameters or data:
  • The action required - a value supplied by the user
  • The data to be processed - contained in a specified data file
  • A data item to return to the program - retrieved from the data file
Parent topic: Tutorial: EJB Service Interface
Previous topic: Prerequisites
Next topic: Create a Project


Create a Project

Walks you through the process of creating an Enterprise Developer project for the BookDemo application and its service interface.
Restriction: This topic applies to Windows environments (local development) only.

Create the ProgramEJB Project

Create a project for your service interface, and add files to the project:

  1. Start Enterprise Developer.

    If this is the first time you start the application, you see the Welcome page in Eclipse. Click Open Team Developer Perspective which is the default perspective for the product.

    If you have already started Eclipse, click Window > Show View > Application Explorer view.

  2. From the Eclipse main menu, click File > New > Other.

    This opens the New dialog dox.

  3. Expand Micro Focus COBOL folder, and then click COBOL Project.
  4. Click Next.

    This opens the New COBOL Project dialog box.

  5. In the Project name field, type ProgramEJB.
  6. Check Use default location, then click Finish.

    The Application Explorer view now shows the ProgramEJB project.

  7. From the Application Explorer view, right-click the ProgramEJB project and select Import from the context menu.

    This opens the Import dialog box.

  8. Expand General and click File System.
  9. Click Next.
  10. Click the Browse button that corresponds to the From directory field, and browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Interface Mapping Toolkit\ServiceInterfaces\BookDemo directory.
  11. Click OK.
  12. On the list of files, check the following:
    • book.cbl
    • book-rec.cpy
    • bookfile.dat
    • bookfile.idx
  13. Click Finish.

    This adds the files to the project and builds the project automatically.

Set the COBOL Build Configuration

This IMTK project requires the build action to produce a dynamic link library (.dll) file for the book program. To ensure this behavior:

  1. In the Application Explorer view, right-click the ProgramEJB project; then select Properties from the context menu.
  2. Expand Micro Focus > Build Configurations, then click COBOL.
  3. From the Target Type list, select All Native Library Files, then click OK.
Parent topic: Tutorial: EJB Service Interface
Previous topic: Demonstration Application
Next topic: Create a Service Interface


Create a Service Interface

Walks you through the process of creating a service interface for the BookDemo application.
Restriction: This topic applies to Windows environments (local development) only.

Create a Java type service interface (EJB) that uses the source program book.cbl:

  1. In the Application Explorer view, right-click the ProgramEJB project; then select New > Other from the context menu.
  2. Expand Micro Focus Service Interface, and select Java Interface; then click Next.
  3. In the Java interface name field, type ProgramEJB.
  4. Select None as the Mapping option.
  5. Click the Browse button associated with Program to map.

    This opens the COBOL Source File dialog box.

  6. Navigate to the book.cbl file in your ProgramEJB project folder.
  7. Click OK.
  8. Click Finish.

    This starts the Interface Mapper.

Parent topic: Tutorial: EJB Service Interface
Previous topic: Create a Project
Next topic: Define Service Interface Operations


Define Service Interface Operations

Walks you through the process of defining service interface details for the BookDemo application.
Restriction: This topic applies to Windows environments (local development) only.

A service interface is defined as a series of operations. In each operation, you create service interface fields that correspond to your COBOL program's entry point fields. At runtime, data is sent between the service and the program via these fields.

In COBOL, you describe a data item's data type precisely, using its picture clause. Java uses its own set of data types. The Interface Mapper enables you to create mappings between the COBOL types in your program and the types available in Java.

You use the Interface Mapper to define streamlined access to your program by defining an operation for each of the program's four possible actions - Read record, Add record, Delete record, and Next record. Each operation requires the client to send just the data needed by that particular operation.

Add Operation

The first logical operation to define for your service interface is one that enables us to add a record. The process entails identifying the COBOL program that contains the Add action, identifying the COBOL Entry point code for that program, determining which fields send and receive information, and defining your operation to interact with the program, specifying the Add action.

Create the Add operation
First, you create the operation, giving it a name and identifying the program and entry point with which you want to interact. In this case, you want to create an operation that enables us to add a record:
  1. From the Application Explorer view, expand ProgramEJB > Java Interfaces.
  2. Right-click the ProgramEJB Java interface and select New > Operation from the context menu.
  3. In the Operation name field, type Add.

    From studying the COBOL code in the application, you know that the book.cbl program performs the add record action.

  4. From the Entry point list, select BOOK.
  5. Click OK.
Define an Interface Field
You see from the book.cbl source that the lnk-file-status field returns the status of the last file input/output action. You need to create an interface field to contain the value so the client can send it to the application:
  1. From the Application Explorer view, expand Java Interfaces > ProgramEJB; then double-click Add. This shows the Add operation in the Interface Mapper.
  2. Drag lnk-file-status from the Linkage Section pane to the Add Operation - Interface Fields pane.

    This creates an interface field called lnk_file_status. A mapping is automatically created between the new field and the entry point field it was created from. The purpose of this field is to relay information back to the user; you need to change its direction from Input to Output.

  3. Double-click lnk_file_status in the Add Operation - Interface Fields pane.

    This opens the Field Properties dialog box.

  4. Click Output, and then click OK.
Define a Group of Interface Fields
You see from the COBOL source that to add a record, the client must supply all the data needed to add the new record to the indexed file. The Book program receives the data in the group item lnk-b-details. For this operation, you need to define a set of interface fields to hold this data:
  1. Drag lnk-b-details from the Linkage Section pane to the Add Operation - Interface Fields pane.

    The default direction, Input, is what you want because this group of fields receives data and then pass it on to the data items in lnk-b-details.

    By default, the name of the new interface field group created is lnk_b_details. However, in this case you should change the default name. You need to use this same group of source fields to create similar groups of interface fields in other operations in this same service interface. The Interface Mapper requires that interface field groups have unique names across operations in the same service interface. Because the default name for each of these would be identical in each operation, you must change the name in each operation to ensure that each is different from that used in other operations.

  2. In the Add Operation - Interface Fields pane, double-click lnk_b_details

    This opens the Group Properties dialog box.

  3. In the Name field, type addop_details.
  4. Click OK.
Change a Type
When defining a service interface, knowledge of the application and how it is used can enable you to make refinements to the new interface. For example, looking at the Linkage Section pane, notice that the retail price field lnk-b-retail is defined as 9(2)V9(2). If you fully expand the tree for addop_details in the Add Operation - Interface Fields pane, you see that lnk_b_retail has defaulted to BigDecimal. Imagine that you know from your experience with the application that the retail prices are in fact always in whole numbers of dollars, and that lnk_b_retail can be an int. You change the type of the lnk-b-retail interface field to reflect this:
  1. If not already expanded, fully expand the tree for addop_details in the Add Operation - Interface Fields pane.
  2. Double-click the lnk_b_retail field.
  3. Select int from the Type list; then click OK.
Define a COBOL Assignment
When the Book program executes, it uses the value in the lnk-function field to determine which action to perform. In cases like this where the value required to initialize an action is known, you create a COBOL Assignment field rather than an interface field, and assign it the value required by the program to ensure a specific action.

For the Add operation, you want the program to perform the add-record action. From looking at the source code, you know that when the value in the lnk-function field is 2, the program performs an add-record action:

  1. In the Linkage Section pane, right-click the lnk-function field, and select New Assignment from the context menu.

    This opens the COBOL Assignment Properties dialog box.

  2. In the Value field, type 2; then click OK.
  3. Click File > Save to save the service interface.
The Completed Add Operation

The Add Operation (EJB)

Looking in a little more detail at what this means.

The correspondence between the COBOL Entry Point fields and interface fields is set up when you do the drag-and-drop. If you right-click an elementary interface field, such as lnk_file_status, and click Mapping, you see a dialog box showing the COBOL Entry point field associated with it. This correspondence is not affected by the names or order of interface fields. You can use the dialog box to alter the mapping if you want.

In the messages passed between the service and a client, the interface fields are identified by keywords. Their names in the Interface Fields pane are used as the keywords. Their order in the Interface Fields pane is the order in which they are seen by a client, so it is good practice to be aware of this order. You can re-order fields by dragging them.

Next Operation

In your indexed file, the primary key is the stock number. The program action that gets the next record takes a stock number as input, finds the record in the data file that has that stock number, and returns the next record found.

The program uses the COBOL Entry Point field lnk-b-details as both an input and an output field, although on input lnk-b-stockno is the only part of lnk-b-details actually used. In your operation, you use the same field to access the program action that gets the next record in the data file.

Create and define the Next operation
  1. Right-click the ProgramEJB Java interface and select New > Operation from the context menu.
  2. In the Operation name field, type Next.

    The Entry point list shows only the BOOK program, which is already selected for you. This is because each service interface can use only one program, and you specified the BOOK program in the Add operation you defined earlier for this same service interface.

  3. Click OK.

    The Next operation is added to the list of Java Interfaces in the Application Explorer view.

  4. Double-click the Next operation to refresh the Interface Mapper.

    The Next Operation - Interface Fields pane is blank in anticipation of new definitions for this operation.

  5. Based on the instructions for the Add operation, define a COBOL Assignment for the lnk-function field and set its value to 4. This is the value that instructs the program to get the next record.
  6. Create an interface field named lnk_file_status from the COBOL Entry Point field link-file-status; then set its direction to Output.

    The program action that retrieves the next record gets the required record from the data file and returns it. So you need a set of output fields into which the fields of this record return.

  7. Drag lnk-b-details from the Linkage Section pane to the Next Operation - Interface Fields pane.

    The new interface field created is called lnk_b_details. As you did when defining the Add operation, you must change the field name to ensure that it is different from the name used for similar groupings in the other operations for this interface.

  8. Double-click the lnk_b_details field name in the Next Operation - Interface Fields.
  9. Change the name to nextop_details, and change the direction to Output; then click OK.
  10. Fully expand the tree for nextop_details, and change the type of lnk_b_retail from BigDecimal to int, just as you did for the Add operation.

    In the application, the lnk_b_stockno field serves as an output field and is also the field in which the key identifying the required record is input. To handle this, you create an input interface field to accept the key.

  11. In the Linkage Section pane, fully expand lnk_b_details.
  12. Drag lnk-b-stockno from the Linkage Section pane to the Next Operation - Interface Fields pane and drop it. In the Next Operation - Interface Fields pane, rearrange the fields by moving lnk-b-stockno to the top of the list. This ensures that the new interface field is first on the list and thus the first field to supply its value to the program.
  13. Click File > Save to save the service interface.
The Completed Next Operation

The Next Operation (EJB)

Read Operation

For the program action that reads a record, the caller supplies a book's stock reference number, title, or author in the appropriate field in the lnk-b-details group. The program looks it up in the indexed file and returns the data back to the lnk-b-details group. The program uses the fields contained in the lnk-b-details group as both input and output. On input, the program expects the stock number, title, or author to be supplied; the other data items in lnk-b-details are ignored. On output, lnk-b-details is used to return the record indicated by the supplied stock number, title, or author.

Create and define the Read operation
  1. Create a new operation named Read that uses the BOOK entry point.
  2. Create a COBOL Assignment for the lnk-function field and set its value to 1. This is the value that instructs the program to read a record.
  3. Create an interface field named lnk_file_status from the COBOL Entry Point field lnk-file-status; then set its direction to Output.

    The program functionality that reads a record gets the required record from the data file and returns it. You need a set of output fields in which to return the fields of this record.

  4. Drag lnk-b-details from the Linkage Section pane to the Read Operation - Interface Fields pane.
  5. Change the name of the lnk_b_details interface field to readop_details, and change its direction to Output.
  6. Expand the tree for readop_details and change the type of lnk_b_retail from BigDecimal to int.
  7. Save the service interface.
Define a reusable field
You now need to define your input fields. In doing this, you demonstrate another feature of the Interface Mapper -- Reusable Fields. You create reusable fields from COBOL entry point fields for the purpose of using them across operations. In Java terms, a reusable field is a custom record according to the CustomRecord interface defined in the Common Client Interface (CCI) from Sun. For Java-based service interfaces, the Interface Mapper assigns a custom data type to interface fields created from reusable fields based on the CCI. Here you create a group of reusable fields that contains only the fields used by the service interface, eliminating those that are not:
  1. Drag lnk-b-details to the Reusable Fields pane.
  2. Fully expand the tree under lnk_b_details in the Reusable Fields pane.
  3. Ungroup lnk_b_text_details so that all the items are at the same level. To do this, right-click each of the fields under lnk_b_text_details; then click Ungroup for each.
  4. Delete each elementary field in the Reusable Fields pane except lnk_b_title, lnk_b_author and lnk_b_stockno. To delete a field, either click it and press Delete or right-click it and select Delete from the context menu. If the tree view contracts, expand it to see what you have created.

    You have defined a group of reusable fields as shown here:
    The Reusable Mapping Created for your EJB

  5. Drag lnk_b_details from the Reusable Fields pane to the Interface Fields pane. Be sure not to drop it amongst the fields that are subordinate to readop_details.

    This creates an interface field of type lnk_b_details. By default, its name is also lnk_b_details.

    Note: If the new interface field does not appear automatically, double-click the entry for the Read operation in Application Explorer view. This refreshes the Interface Mapper panes.
  6. Because Java requires that group fields have unique names across operations, change the name of lnk_b_details interface field to readop_input.
  7. Save the service interface.
The Completed Read Operation

The Read Operation (EJB)

Delete Operation

Like the program action that reads a record, the action that deletes a record expects the stock number, title, or author to be supplied. The other data items in lnk-b-details are ignored. It deletes the record indicated by the supplied stock number, title, or author.

Create and define the Delete operation
  1. Create a new operation named Delete that uses the BOOK entry point.
    Note: Reusable fields you created in a different operation remain visible in the Interface Mapper for all operations.
  2. Create a COBOL Assignment for the lnk-function field and set its value to 3. This is the value that instructs the program to delete a record.
  3. Create an interface field named lnk_file_status from the COBOL Entry Point field lnk-file-status; then set the direction to Output. This is the only required output field.
  4. Drag lnk_b_details from the Reusable Fields pane to the Interface Fields pane and rename the new interface field delete_input.
  5. Save the service interface; then close the Interface Mapper.
The Completed Delete Operation

The Delete Operation (EJB)
Parent topic: Tutorial: EJB Service Interface
Previous topic: Create a Service Interface
Next topic: Configure ESDEMO


Configure ESDEMO

Walks you through the process of creating a deployment folder and configuring ESDEMO to use it.
Restriction: This topic applies to Windows environments (local development) only.

To successfully deploy and run or debug a Java service interface, you must have an enterprise server instance started in Enterprise Server. For these tutorials, we provide the ESDEMO enterprise server instance. If you do not have Administrator privileges to the Enterprise Developer installation folder, or if you have not started Enterprise Developer as an administrator, before completing the remainder of these tutorials you must create a deployment folder and then configure ESDEMO to enable successful deployment.

Start Enterprise Server Administration

  1. To start the Server Explorer, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. From Server Explorer in Enterprise Developer, right-click Local [localhost:86]; then click Open Administration Page.

    The Enterprise Server Administration Home page starts in an Enterprise Developer window.

Configure a Deployment Directory

Note: The default deployment folder used by Enterprise Server is a subfolder to your Enterprise Developer installation folder. If you have Administrator privileges to the Enterprise Developer installation structure, or if you started Enterprise Developer using Run as Administrator, you are not required to complete this section of the tutorial. Otherwise, you must complete this section to create and configure an alternative deployment folder.
Create the deploy folder
Without Administrator privileges, you cannot deploy to Enterprise Server from the default Enterprise Developer deployment folder. To ensure successful deployment, create a deploy folder in your ProgramEJB project.
  1. In the Application Explorer view, right-click the project; then select New > Folder > Folder from the context menu.
  2. In the Folder name field, type deploy; click Finish.
Import the .mfdeploy File
The new deploy folder must contain the .mfdeploy configuration file. You import the file from the Application Explorer view.
  1. From the Application Explorer view, right-click the project folder; then select Import from the context menu.
  2. Expand General; then click double-click File System.
  3. Click the Browse button that corresponds to the From directory field, and navigate to
    InstallFolder\deploy

    where InstallFolder is your Enterprise Developer installation folder. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer.

  4. Click Select Folder.
  5. Check .mfdeploy in the right pane.
  6. Click Finish to import the file into the project.
Define the Deployment Directory
Now you need to configure the ESDEMO instance by defining the new deploy project folder as the deployment folder.
  1. On the Enterprise Server Administration Home page in the Communications Processes column for your enterprise server instance, click the Details button that corresponds to Listeners.
  2. Click the Listeners tab.
  3. In the row for the Web listener name, click Edit.
  4. Change the value of the New Status field to Stopped. This enables the listener used to deploy the service interface to the ESDEMO server.
  5. Scroll down to the Configuration Information field; then within the field, scroll down until you find the relevant code, then change:
    uploads=<ES>/deploy

    to:

    uploads=ProjectFolder/deploy
    where ProjectFolder is the full path to your project folder, using forward slashes to separate subfolders. For example:
    uploads=c:/Users/Bob/workspace/project-name/deploy
  6. Click OK.
  7. Click Home to return to the Home page.
Parent topic: Tutorial: EJB Service Interface
Previous topic: Define Service Interface Operations
Next topic: Deploy a Service Interface


Deploy a Service Interface

Walks you through the steps required to associate an enterprise server instance with your project, build the project, set deployment properties, deploy the service interface, and verify the deployment results.
Restriction: This topic applies to Windows environments (local development) only.

To successfully deploy a Java service interface to an enterprise server instance, you need to first set some options in Enterprise Developer.

Set Deployment Properties

To ensure that the deployment process runs smoothly, you must set some options that tell Enterprise Developer the name of your enterprise server instance, what application server to use, and where to find certain files.

  1. From the Application Explorer view in the ProgramEJB project, expand Java Interfaces
  2. Right-click the ProgramEJB Java interface; then select Java Properties from the context menu.
  3. On the General tab, click EJB Generation (default).
  4. On the Deployment Server tab, click Change that corresponds to the Enterprise Server name field.

    This opens the Select Enterprise Server dialog box.

  5. Select the ESDEMO Server, and then click OK.
  6. On the Application Files tab, click Legacy application needs deploying; then click Add Files to add the following files:
    File | Project Folder
    bookfile.dat | ProgramEJB
    bookfile.idx | ProgramEJB
    book.dll | ProgramEJB > New_Configuration.bin
    These files are copied to the enterprise server instance when you deploy. The .dat and .idx files are the data and index parts of the indexed file accessed by the service. The .dll is the executable file you need to debug the service.
  7. On the EJB Generation tab, use the lists to set the Application Server to JEE 6 and JBoss EAP 6.4.
  8. Uncheck Transactional.
  9. In the Java compiler field, type the location of your javac.exe.
  10. Click Browse that corresponds to the Java EE Class Path field, and type following EJB connector class file paths, they are located in the following subfolders:
    • jboss-eap-6.4\modules\system\layers\base\javax\resource\api\main\jboss-connector-api_1.6_spec-1.0.1.Final-redhat-3.jar
    • jboss-eap-6.4\modules\system\layers\base\javax\ejb\api\main\jboss-ejb-api_3.1_spec-1.0.2.Final-redhat-3.jar
    • jboss-eap-6.4\modules\system\layers\base\javax\servlet\api\main\jboss-servlet-api_3.0_spec-1.0.2.Final-redhat-2.jar

    In addition, add the javac.exe from your Java installation bin folder.

  11. Click OK.

Stop Enterprise Server Instances

To ensure that your enterprise server instance does not encounter any port conflicts with other enterprise server instances that use the same listener port, stop all started enterprise server instances as follows:

  1. If the Server Explorer in Enterprise Developer is not active, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. From the Server Explorer, expand Local [localhost:86] to see a list of enterprise server instances.
  3. Right-click each started enterprise server instance, and stop it by selecting Stop from the context menu. Started enterprise server instances show with a green icon Started enterprise server instance.

Start the ESDEMO Enterprise Server Instance

Before deploying your service interface, you must start the ESDEMO instance where the ProgramEJB service will run.

  1. If the Server Explorer in Enterprise Developer is not active, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. From the Server Explorer, expand Local [localhost:86] to see a list of available enterprise server instances.
  3. To start the ESDEMO enterprise server instance, right-click it; then click Start.

    ESDEMO provides a default user name and password that you can customize. For this tutorial, you use the default information.

  4. If a sign-on dialog box appears, click OK; then click No to disable password recovery.

The Enterprise Server Daemon is then invoked via the Console, starting the enterprise server instance.

Deploy the ProgramEJB Java interface

  1. From Application Explorer view, right-click the ProgramEJB Java interface; then click Deploy.
  2. In Eclipse, click the Console tab.
  3. On the icon bar, click the down arrow associated with Display Selected Console Display Selected Console.
  4. Click Service Interfaces Console.

The Console shows the progression of the deployment process. If deployment was successful, you should see a message indicating success.

Note: If the console switches to the Micro Focus Build view after deployment, switch the view back to Service Interfaces Console to review the deployment log.

If deployment ever fails, you should find a message in the output window indicating why it failed. Also, the failure message contains the path to the deployment log file. You can type the address into a browser and view the log file from there.

View deployment results

Now that your Java interface has been deployed as a service running on the ESDEMO enterprise server, you can look at the details of the deployed service Enterprise Server Administration page.

  1. If you have closed Enterprise Server Administration, start it again from the from the Server Explorer.

    In the row showing information for the ESDEMO enterprise server, you should see that the Objects column shows the number of services that this enterprise server runs. In this case, the number of running services should be at least 9. These are the five that come standard with the ESDEMO enterprise server, plus the one service you added containing four operations. You might see more if you have deployed other services to the ESDEMO enterprise server.

  2. Click the Details button for the ESDEMO Services.

    In the row showing your new service, ProgramEJB, you see that the Current Status column shows all four operations as Available. This means that the service is ready to be access by a client.

Parent topic: Tutorial: EJB Service Interface
Previous topic: Configure ESDEMO
Next topic: Generate and Deploy a JSP Client


Generate and Deploy a JSP Client

Walks you through the process of generating a JSP client for the ProgramEJB service interface, and deploying it to your JBoss application server.
Restriction: This topic applies to Windows environments (local development) only.

For an EJB to access a COBOL service running on an enterprise server, you must have the EJB and a JSP client running on an application server. You now generate an EJB and a JSP client for the ProgramEJB service you deployed and configure your JBoss application server to run them.

  1. From Application Explorer view, right-click the ProgramEJB Java interface; then click Generate Client.

    The Console tells you when the client has generated successfully.

  2. In Eclipse, click the Console tab.
  3. On the icon bar, click the down arrow associated with Display Selected Console Display Selected Console.
  4. Click Service Interfaces Console.
  5. Copy the ProgramEJB.ear file, located in your project's repos\ProgramEJB.deploy directory, to your JBoss installation's standalone\deployments directory.
Parent topic: Tutorial: EJB Service Interface
Previous topic: Deploy a Service Interface
Next topic: Deploy the Resource Adapter to JBoss


Deploy the Resource Adapter to JBoss

Walks you through the steps required to deploy the Micro Focus resource adapter to JBoss.
Restriction: This topic applies to Windows environments (local development) only.

Before you can run your JSP client, you must first deploy the resource adapter to JBoss.

  • Copy the following resource adapter files from your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee\javaee6\jboss64EAP directory to your JBoss EAP 6.4 deployment directory standalone\deployments directory:
    • mfcobol-notx.rar
Parent topic: Tutorial: EJB Service Interface
Previous topic: Generate and Deploy a JSP Client
Next topic: Run the JSP Client


Run the JSP Client

Walks you through the process of running the generated JSP client to access the new service.
Restriction: This topic applies to Windows environments (local development) only.

Now you are ready to run the JSP client in JBoss. When you run the JSP client, it takes a request from the end user and passes it to the EJB you generated. The EJB in turn passes the request to the enterprise server, ESDEMO. The original COBOL program runs on the enterprise server and processes the request, returning the results back to the JSP.

  1. From a command prompt, change to your JBoss installation's bin directory and enter Run.
  2. When the JBoss startup script has completed, start a Web browser, and enter the following address:

    http://localhost:8080/ProgramEJB/ProgramEJBMain.jsp

  3. Click Read.
  4. In the read_readop_input_lnk_b_stockno field, type 1111; then click Go!.

    The service returns the record that corresponds to the 1111 stock number.

  5. Experiment with running the Add, Next, and Delete options, providing the input required.

This completes the EJB Service Interface tutorial.

Note: If you plan to continue with another IMTK tutorial, stop the ESDEMO enterprise server instance before continuing.
Parent topic: Tutorial: EJB Service Interface
Previous topic: Deploy the Resource Adapter to JBoss


Tutorial: REST Service Interface

Walks you through the process of defining a Representational State Transfer (REST) service interface using the Interface Mapping Toolkit (IMTK), deploying it to an enterprise server instance, and generating and running a client to access it.
Restriction: This topic applies to Windows environments (local development) only.

In this tutorial, you walk through the steps required to define a service interface using the Interface Mapping Toolkit (IMTK), deploy it to an enterprise server instance, and generate and run a client to access it.

Complete this tutorial by following the instructions in the following topics in the order listed here:

  1. Prerequisite
    Describes the setup required to complete this tutorial.
  2. Demonstration Application
    Describes the Schedule demo application used in this tutorial.
  3. Create a Project
    Walks you through the process of creating an Enterprise Developer project for the ScheduleDemo application and its service interface.
  4. Create a Service Interface
    Walks you through the process of creating a service interface for the Schedule application.
  5. Define Service Interface Operations
    Walks you through the process of defining the service interface details for the ScheduleDemo application.
  6. Create and Configure ESREST
    Walks you through the process of creating and configuring an enterprise server instance, ESREST, to use in this tutorial.
  7. Deploy a Service Interface
    Walks you through the steps required to associate an enterprise server instance with your project, build the project, set deployment properties, deploy the service interface, and verify the deployment results.
  8. Generate a COBOL Client
    Walks you through the process of generating a COBOL client for the MakeCheckAppt service interface.
  9. Run the MakeCheckAppt Web Service
    Walks you through the process of creating a debug configuration for your new service, and running the client application to access the service.
Parent topic: Tutorials: Interface Mapping Toolkit


Prerequisite

Describes the setup required to complete this tutorial.
Restriction: This topic applies to Windows environments (local development) only.

Before beginning this tutorial, be sure to set up your Enterprise Developer environment as specified in the Set Build and Interface Mapper Preferences topic.

Parent topic: Tutorial: REST Service Interface
Next topic: Demonstration Application
Related concepts
Set Build and Interface Mapper Preferences


Demonstration Application

Describes the Schedule demo application used in this tutorial.
Restriction: This topic applies to Windows environments (local development) only.

The COBOL application that you use in this tutorial is the Schedule demonstration application. The application executables are installed with Enterprise Developer in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Interface Mapping Toolkit\ServiceInterfaces\ScheduleDemo directory by default.

The Schedule demonstration application is a system for scheduling and viewing appointments. The application uses the following source and data members:

  • schedule.cbl
  • common.cpy
  • common_78.cpy
  • common_ex.cpy
  • common_ws.cpy
  • consultants.cpy
  • customerinfo.cpy
  • stores.cpy
  • appoint.dat
  • consultants.dat
  • customers.dat

Using the application, you can either schedule a new appointment, or look up an existing appointment. We recommend that you review the application source code to become familiar with how it works.

Parent topic: Tutorial: REST Service Interface
Previous topic: Prerequisite
Next topic: Create a Project


Create a Project

Walks you through the process of creating an Enterprise Developer project for the ScheduleDemo application and its service interface.
Restriction: This topic applies to Windows environments (local development) only.

Create the ProgramREST Project

Create a project for your service interface, and add files to the project.

  1. Start Enterprise Developer.

    If this is the first time you start the application, you see the Welcome page in Eclipse. Click Open Team Developer Perspective which is the default perspective for the product.

    If you have already started Eclipse, click Window > Show View > Application Explorer view.

  2. From the maim menu in Eclipse, click File > New > Other.

    This opens the New dialog dox.

  3. Expand Micro Focus COBOL folder, and then click COBOL Project.
  4. Click Next.

    This opens the New COBOL Project dialog box.

  5. In the Project name field, type ProgramREST.
  6. If not already checked, check Use default location; then click Finish.

    The Application Explorer view now shows the ProgramREST project.

  7. From the Application Explorer view, right-click the ProgramREST project and click Import from the context menu.
  8. Expand General; then double-click File System.
  9. Click the Browse button that corresponds to the From directory field, and browse to the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Interface Mapping Toolkit\ServiceInterfaces\ScheduleDemo directory; then click OK.
  10. In the left pane, check ScheduleDemo to select all files listed in both panes.
  11. In the right pane, uncheck Readme-Ec.xml and Readme.xml. These files are used by the Samples Browser.
  12. Click Finish.

    Enterprise Developer adds the files and builds the project automatically.

Set the COBOL Build Configuration

This IMTK project requires the build action to produce a dynamic link library (.dll) file for the schedule program. To ensure this behavior:

  1. In the Application Explorer view, right-click the ProgramREST project; then select Properties from the context menu.
  2. Expand Micro Focus > Build Configurations; then click COBOL.
  3. From the Target Type drop-down list, select All Native Library Files; then click OK.
Parent topic: Tutorial: REST Service Interface
Previous topic: Demonstration Application
Next topic: Create a Service Interface


Create a Service Interface

Walks you through the process of creating a service interface for the Schedule application.
Restriction: This topic applies to Windows environments (local development) only.

Create a service interface for the new project.

  1. In the Application Explorer view, right-click the ProgramREST project; then select New > Interface > REST Web Service from the context menu.
    Note: If REST Web Service is not on the menu:
    1. Click Other.
    2. Expand Micro Focus Service Interface
    3. Select REST Web Service; then click Next.
  2. In the Web service name field, type MakeCheckAppt.
  3. Select None as the Mapping option.
  4. Click the Browse button associated with Program to map, and navigate to and select the schedule.cbl file in your ProgramREST project folder.
  5. Click OK.
  6. Click Finish.

    This starts the Interface Mapper.

Parent topic: Tutorial: REST Service Interface
Previous topic: Create a Project
Next topic: Define Service Interface Operations


Define Service Interface Operations

Walks you through the process of defining the service interface details for the ScheduleDemo application.
Restriction: This topic applies to Windows environments (local development) only.

Each service interface you create is comprised of a set of operations. In this tutorial, you create one operation for each of the two functions provided by the application.

MakeAppt Operation

The purpose of the MakeAppt operation is to create an appointment and store it in the system.

Create the MakeAppt Operation
  1. From the Application Explorer view, expand ProgramREST > Web Services.
  2. Right-click the MakeCheckAppt Web service and select New > Operation from the context menu.
  3. In the Operation name field, type MakeAppt.

    This application contains only one program, schedule.cbl. This program contains one entry point, SCHEDULE, from which to create the operation. By default, SCHEDULE appears in the Entry point field.

  4. Click OK.
  5. From the Application Explorer view, expand the MakeCheckAppt Web Service.
  6. Double-click MakeAppt.

In the Interface Mapper, you now see that the entry point fields have been placed into the Linkage Section pane on the left.

Define Interface Fields
The Schedule program needs several input items to create an appointment, including variable information such as the customer's name, the identification number of the consultant with whom the appointment is to be made, the date of the proposed appointment, and the desired time slot. You define interface fields to hold this information so that the client can send it to the application.
  1. Drag the following fields from the Linkage Section pane to the MakeAppt Operation - Interface Fields pane:
    • lnk-customer-name
    • lnk-consultant-id
    • lnk-date
    • lnk-time-slot

    This creates interface field names similar to those of the entry point fields from which they were created. The difference is that all dashes (-) are automatically replaced with underscores (_). In addition, a mapping is automatically created between each new interface field and its corresponding entry point field.

    The purpose of the lnk_customer_name, lnk_consultant_id, lnk_date, and lnk_time_slot fields are to hold data that is sent to the application for processing; therefore, they are input fields. The default mapping direction for each of these, Input, is correct.

    Once the Schedule program receives the input information from the client, it sends back a code to indicate whether or not the requested appointment is available. The program field that receives this code is lnk-op-ok. Therefore, you need to create a corresponding interface field, and change its mapping direction from Input (default) to Output.

  2. Drag the lnk-op-ok field from the Linkage Section pane to the MakeAppt Operation - Interface Fields pane.
  3. Double-click lnk_op_ok in the MakeAppt Operation - Interface Fields pane.
  4. Click Output; then click OK.
Define COBOL Assignments
Because the MakeAppt operation executes only one program function, the value required to initialize that function remains constant. In this case, you create a COBOL Assignment field rather than an interface field, and assign it the value required by the program to ensure the execution of the specific function.

From looking at the program source code, you know that when the value in the lnk-operation field is 0, the program executes the set-appt code. Therefore, you want to assign the lnk-operation field a value of 0.

  1. In the Linkage Section pane, right-click the lnk-operation field, and select New Assignment from the context menu.
  2. In the Value field, type 0; then click OK.

    For this particular service, you want to make appointments only for one specific store. When the Schedule program executes, it reads the value in the lnk-id field to identify the store where the appointment is to be made. Therefore, you can provide the same store identification number each time the service runs by assigning a constant value.

  3. In the Linkage Section pane, expand the lnk-store-info group.
  4. In the Linkage Section pane, right-click the lnk-id field, and select New Assignment from the context menu.
  5. In the Value field, type 08780; then click OK.
  6. Click File > Save to save the service interface.
Completed MakeAppt Operation

CheckAppt Operation

The purpose of the CheckAppt operation is to look up an existing appointment and return its details.

Create the CheckAppt Operation
  1. From the Application Explorer view, expand ProgramREST > Web Services.
  2. Right-click the MakeCheckAppt Web service and select New > Operation from the context menu.
  3. In the Operation name field, type CheckAppt.

    The Entry point list shows only the SCHEDULE program, which is already selected for you. This is because each service interface can use only one program, and you specified the SCHEDULE program in the MakeAppt operation you defined earlier for this same service interface.

  4. Click OK.
  5. From the Application Explorer view, expand the MakeCheckAppt Web Service.
  6. Double-click CheckAppt.

In the Interface Mapper, the entry point fields once again appear in the Linkage Section pane on the left.

Define Interface Fields
The CheckAppt operation uses most of the same interface fields as does the MakeAppt operation, and in addition includes an output array in which the queried appointment appears, if found. Follow these steps:
  1. Drag the following fields from the Linkage Section pane to the CheckAppt Operation - Interface Fields pane:
    • lnk-customer-name
    • lnk-consultant-id
    • lnk-date
    • lnk-op-ok
  2. In the Linkage Section pane, expand the lnk-day group.
  3. Drag the lnk-cust-id field to the CheckAppt Operation - Interface Fields pane. The lnk-cust-id field is an array.

    Because both lnk-op-ok and lnk-cust-id are both output fields, you need to change the direction of each from Input to Output.

  4. Double-click lnk_op_ok in the CheckAppt Operation - Interface Fields pane.
  5. Click Output; then click OK.
  6. Apply the two preceding steps to the lnk-cust-id field.
Define COBOL Assignments
The CheckAppt operation needs to execute the read-appt application code. Therefore, you need to assign the lnk-operation field a value of 1.
  1. Drag the lnk-operation field from the Linkage Section pane to the COBOL Assignments pane.
  2. In the Value field, type 1; then click OK.

    Just as you did for the MakeAppt operation, you want to assign a constant value for the lnk-id field so you are sure to query the same store each time.

  3. Drag the lnk-id field from the Linkage Section pane to the COBOL Assignments pane.
  4. In the Value field, type 08780; then click OK.
  5. Click File > Save to save the service interface.
The Completed CheckAppt Operation

Parent topic: Tutorial: REST Service Interface
Previous topic: Create a Service Interface
Next topic: Create and Configure ESREST


Create and Configure ESREST

Walks you through the process of creating and configuring an enterprise server instance, ESREST, to use in this tutorial.
Restriction: This topic applies to Windows environments (local development) only.

To successfully deploy and run (debug) a Web Services service interface, you must have an enterprise server instance started in Enterprise Server. For these tutorials, you create the ESREST enterprise server instance, set its listener port, and configure a deployment folder for it to use.

Start Enterprise Server Administration

  1. From Server Explorer in Enterprise Developer, right-click Local [localhost:86]; then click Open Administration Page.

    The Enterprise Server Administration Home page starts in an Enterprise Developer window.

Create ESREST

In this section, you create the ESREST enterprise server instance from the Home page in Enterprise Server Administration.

  1. From the Enterprise Server Administration Home page, click Add.
  2. In the Server Name field, type ESREST.
  3. Click Next.
  4. Under Server Type, select Micro Focus Enterprise Server; then click Next.
  5. On the Add server (Page 3 of 3) page, click Add.

Configure ESREST

By default, your new enterprise server instance is already configured for the REST architectural style; however, you must make some adjustments, which include enabling dynamic debugging, setting an endpoint address for the Web Services and J2EE Listener, and if you do not have Administrator privileges to the Enterprise Developer installation folder, defining a deployment folder.

Enable Dynamic Debugging
  1. On the Enterprise Server Administration Home page in the table of servers, click the Edit button that corresponds to the ESREST server.
  2. On the Server > Properties > General page (default) in the Startup Options group, check Allow Dynamic Debugging; then click OK.

    This returns you to the Home page.

Configure the Web Services and J2EE Listener
  1. On the Enterprise Server Administration Home page, in the Communications Processes column for the ESREST server, click the Details button.

    This takes you to the Communications Processes page for Enterprise Server listeners.

  2. Click the Edit button that corresponds to Web Services and J2EE Listener.
  3. Change the contents of the Endpoint Address field to *:9003.
  4. Click Apply.

    This returns you to the Communications Processes page.

  5. Click the Edit button that corresponds to Web listener.
  6. Change the value of the New Status field to Stopped. This enables the listener used to deploy the service interface to the ESREST server.
  7. Click OK.
  8. Important: If you do not have Administrator privileges to the Enterprise Developer installation folder, continue with the configuration. Otherwise, configuration for the ESREST enterprise server instance is complete at this point.
    Click Home to return to the Home page.
Define a Deployment Folder
The default deployment folder used by Enterprise Server is a subfolder to your Enterprise Developer installation folder. If you have Administrator privileges to the Enterprise Developer installation structure, or if you started Enterprise Developer using Run as Administrator, you are not required to complete this section of the tutorial.
  1. Back on the Communications Processes page, click the Edit button that corresponds to the Web listener.
  2. Scroll down to the Configuration Information field; then within the field, scroll down until you find the relevant code, then change:
    uploads=<ES>/deploy

    to:

    uploads=ProjectFolder/deploy
    where ProjectFolder is the full path to your project folder, using forward slashes to separate subfolders. For example:
    uploads=c:/Users/Bob/workspace/project-name/deploy
  3. Click OK.
  4. Click Home to return to the Enterprise Server Administration Home page.

Create and Configure a Deployment Folder

The default deployment folder used by Enterprise Server is a subfolder to your Enterprise Developer installation folder. If you have Administrator privileges to the Enterprise Developer installation structure, or if you started Enterprise Developer using Run as Administrator, you are not required to complete this section of the tutorial.

Create the deploy folder
Without Administrator privileges, you cannot deploy to Enterprise Server from the default Enterprise Developer deployment folder. To ensure successful deployment, create a deploy folder in your ProgramREST project.
  1. In the Application Explorer view, right-click the project; then select New > Folder > Folder from the context menu.
  2. In the Folder name field, type deploy; click Finish.
Import the .mfdeploy File
The new deploy folder must contain the .mfdeploy configuration file. You import the file from the Application Explorer view.
  1. From the Application Explorer view, right-click the project folder; then select Import from the context menu.
  2. Expand General; then click double-click File System.
  3. Click the Browse button that corresponds to the From directory field, and navigate to
    InstallFolder\deploy

    where InstallFolder is your Enterprise Developer installation folder. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer.

  4. Click Select Folder.
  5. Check .mfdeploy in the right pane.
  6. Click Finish to import the file into the project.
Parent topic: Tutorial: REST Service Interface
Previous topic: Define Service Interface Operations
Next topic: Deploy a Service Interface


Deploy a Service Interface

Walks you through the steps required to associate an enterprise server instance with your project, build the project, set deployment properties, deploy the service interface, and verify the deployment results.
Restriction: This topic applies to Windows environments (local development) only.

To successfully deploy a REST service interface to an enterprise server instance, you need to first set some options in Enterprise Developer.

Set Deployment Properties

To ensure that the deployment process runs smoothly, you must set some options that tell Enterprise Developer where to find certain files.

  1. From the Application Explorer view, expand ProgramREST > Web Services
  2. Right-click the MakeCheckAppt Web service; then select Web Service Properties from the context menu.
  3. On the Deployment Server tab, click the Change button that corresponds to the Enterprise Server name field.
  4. In the Server column, click ESREST; then click OK.
  5. On the Application Files tab, click Legacy application needs deploying; then click Add Files to add the following files:
    Files | Location | Description
    • appoint.dat
    • consultants.dat
    • customers.dat

    Your project's ProgramREST folder

            Data files accessed by the service.
    schedule.dll | Your project's New_Configuration.bin folder | The executable file you need to debug the service.

    These files are copied to the enterprise server when you deploy.

  6. Click OK.

Stop Enterprise Server Instances

To ensure that your enterprise server instance does not encounter any port conflicts with other enterprise server instances that use the same listener port, stop all started enterprise server instances as follows:

  1. If the Server Explorer in Enterprise Developer is not active, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. From the Server Explorer, expand Local [localhost:86] to see a list of enterprise server instances.
  3. Right-click each started enterprise server instance, and stop it by selecting Stop from the context menu. Started enterprise server instances show with a green icon Started enterprise server instance.

Start the ESREST Enterprise Server Instance

Before deploying your service interface, you must start the ESREST instance where the MakeCheckAppt service will run.

  1. If the Server Explorer in Enterprise Developer is not active, click Window > Show View > Other > Micro Focus > Server Explorer; then click OK.
  2. From the Server Explorer, expand Local [localhost:86] to see a list of available enterprise server instances.
  3. Right-click ESREST; then select Start from the context menu.
    Note: If this is the first time you have started the server you see a sign-on dialog box. If Server is secured is checked, uncheck it; then click OK. Unchecking Server is secured prevents this dialog box from showing when you subsequently start the region. If Server is secured is not checked, simply click OK to clear the dialog box.

The Enterprise Server Daemon is then invoked via the Console, starting the ESREST enterprise server instance.

Deploy the MakeCheckAppt Web Service

  1. From the Application Explorer view, right-click the MakeCheckAppt Web Service; then click Deploy.
  2. In Eclipse, click the Console tab.
  3. On the icon bar, click the down arrow associated with Display Selected Console Display Selected Console.
  4. Click Service Interfaces Console.

The Console view shows the progression of the deployment process. If deployment was successful, you should see a message: Deployment completed with warnings. If you scroll up to see the log output, notice that the deployment process changed the direction of the slashes in some directory specifications. This is normal behavior for successful deployment.

Note: If the console switches to the Micro Focus Build view after deployment, switch the view back to Service Interfaces Console to review the deployment log.

If deployment ever fails, you should find a message in the Console view indicating why it failed. Also, the failure message contains the path to the deployment log file. You can type the address into a browser and view the log file from there.

View Deployment Results

Now that your service interface has been deployed as a service running on the ESREST enterprise server, you can look at the details of the deployed service via the Enterprise Server Administration page.

  1. If you have closed the Enterprise Server Administration window in Enterprise Developer, start it again.

    In the row showing information for the ESREST enterprise server instance, you should see that the Objects column shows the number of services that this enterprise server instance runs.

  2. Click the Details button for the ESREST Services.

    In the row showing your new service, MakeCheckAppt, you'll notice that the Current Status column shows both operations as Available. This means that the service is ready to be accessed by a client.

  3. Close Enterprise Server Administration.
Parent topic: Tutorial: REST Service Interface
Previous topic: Create and Configure ESREST
Next topic: Generate a COBOL Client


Generate a COBOL Client

Walks you through the process of generating a COBOL client for the MakeCheckAppt service interface.
Restriction: This topic applies to Windows environments (local development) only.

You can now generate a COBOL client to access the ProgramREST service that you deployed to the ESREST enterprise server instance.

  1. From the Application Explorer view, right-click the MakeCheckAppt Web Service; then select Generate Client from the context menu.
  2. On the Generate Client dialog box, click Current project; then click OK.

You can watch the generation process in the Service Interfaces Console. When it is complete, you'll see the message "The client generation completed successfully" after which Eclipse rebuilds the project. You should see that the following files have been added to the project in the client folder:

  • MakeCheckAppt-app.cbl
  • MakeCheckAppt-proxy.cbl
  • MakeCheckAppt-copy.cpy
Parent topic: Tutorial: REST Service Interface
Previous topic: Deploy a Service Interface
Next topic: Run the MakeCheckAppt Web Service


Run the MakeCheckAppt Web Service

Walks you through the process of creating a debug configuration for your new service, and running the client application to access the service.
Restriction: This topic applies to Windows environments (local development) only.

Create a Debug Configuration

  1. In the Application Explorer view, click the ProgramREST project.
  2. From the main menu, click Run > Debug Configurations.
  3. In the left pane, right-click COBOL Enterprise Server; then select New from the context menu.
  4. At the very top of the right pane, type ProgramREST into the Name field.
  5. On the General tab click the Browse button that corresponds to the Connection and Server fields.
  6. Select ESREST; then click OK.
    Note: If the ESREST enterprise server instance is the only instance defined in Enterprise Server, these fields are completed for you.
  7. Under Debugging type, click the Web Service tab.

    This shows that all debug Web services are invoked by a request from the client.

  8. Click Apply; then click Debug.
  9. Answer Yes to any prompts to open views or perspectives.
  10. In the Debug view, you should now see an entry for debugging ProgramREST [COBOL Enterprise Server].

Set Breakpoints

You want to be able to see when the client program hands off control to the service running in Enterprise Server. Because the program hands off control at two points in its execution, first to run the MakeAppt operation, and second to run the CheckAppt operation, you set a breakpoint at each hand-off point in the code so you can step through the program.

The code that calls the service is contained in the MakeCheckAppt-proxy.cbl file:

call "InvokeService02"

It appears twice in the program. You want to set a breakpoint just before each of these call statements.

  1. From the Application Explorer view, expand ProgramREST > client.
  2. Double-click MakeCheckAppt-proxy.cbl. This places the source code into the COBOL editor.
  3. Press Ctrl+F to search for the following code:
    move 256 to wsc-srvc-faultcode-len
  4. Place your mouse pointer in the left-most column at that line of code and double-click to set a breakpoint.
    Note: When the breakpoint has been set, a dot appears in the left-most column.
  5. Search for the next instance of:
    move 256 to wsc-srvc-faultcode-len
    and set another breakpoint.

Run the COBOL Client

  1. From the Application Explorer view, expand ProgramREST > client.
  2. Right-click MakeCheckAppt-app.cbl; then select Debug As > COBOL Application from the context menu.
    Note: If a Confirm Perspective Switch message appears, click Yes.

    This places an entry into the Debug view for the client application.

  3. In the Debug view, right-click the bottom-most entry; then select Resume.
  4. The client invokes a console named runm, and waits for input. Complete the fields as follows to set an appointment slot:
    Service Address | leave blank
    Username | leave blank
    Password | leave blank
    Operation | 1
    lnk_customer_name | Benton Riley
    lnk_consultant_id | 8706
    lnk_date.lnk_yyyy | 2525
    lnk_date.lnk_mm | 1
    lnk_date.lnk_dd | 1
    lnk_time_slot | 5

    The client application then resumes execution, and pauses on the move 256 to wsc-srvc-faultcode-len statement.

  5. Switch back to the Debug view.
  6. Press F6 multiple times to step through the code until you have stepped just past the call "InvokeService02" statement.
  7. On the Debug view, expand entries under all Application Thread entries. You should see that the deployed schedule application is now being accessed from Enterprise Server.
  8. Press F8 to resume and terminate execution.

Rerun the COBOL Client

Here you rerun the client, selecting the other operation to see that the appointment has been made.

  1. In the Debug view, right-click the MakeCheckAppt-app.dll entry marked as <terminated>; then select Relaunch from the context menu.
  2. In the Debug view, right-click the bottom-most entry; then select Resume.
  3. Complete the runm fields as follows:
    Service Address | leave blank
    Username | leave blank
    Password | leave blank
    Operation | 2
    lnk_customer_name | Benton Riley
    lnk_consultant_id | 8706
    lnk_date.lnk_yyyy | 2525
    lnk_date.lnk_mm | 1
    lnk_date.lnk_dd | 1

    The client application then resumes execution, and pauses on the move 256 to wsc-srvc-faultcode-len statement.

  4. Press F6 multiple times to step through the code until the appointment you set appears on the list in the runm client. You should see it on line [00005] because it is the fifth appointment set for that day.
  5. From the Debug view, press F8 to resume and terminate execution.
Parent topic: Tutorial: REST Service Interface
Previous topic: Generate a COBOL Client


Tutorials: OpenESQL Assistant

In this set of tutorials, you create an application using OpenESQL Assistant to generate a skeleton COBOL program, an SQL query to embed into that program, and to generate and embed an INCLUDE statement for a generated copybook that defines host variables. It also takes you through the process of customizing the program code, and debugging the resulting application.

Tutorial Requirements

To complete the OpenESQL Assistant tutorials, you must have the following software installed:

  • Enterprise Developer for Eclipse
  • Microsoft SQL Server 2008 or later, including the SQL Server Management Studio

Additional requirements that apply to a specific tutorial, if any, appear in a Requirements section in the tutorial topic.

Order

You must complete this series of tutorials in the following order:

  1. Tutorial: Create a SQL Server Database
    Create a SQL Server database using Microsoft SQL Server Management Studio.
  2. Tutorial: Create and Configure an Eclipse Project
    Create and configure Eclipse COBOL project in which to create an application.
  3. Tutorial: Set OpenESQL Assistant Configuration Options
    Set configuration options for the OpenESQL Assistant.
  4. Tutorial: Catalog a Connection
    Catalog a connection to the database you created in a previous tutorial.
  5. Tutorial: Build and Test a Query
    Use the OpenESQL Assistant to build and test an SQL query.
  6. Tutorial: Generate and Embed an SQL Program
    Use OpenESQL Assistant to generate a generic SQL program to run the query, and embed it into an existing COBOL program.
  7. Tutorial: Provide Additional Code
    Add code to the generated SQL program to include a generated copybook and to send the returned data to the console in a readable format.
  8. Tutorial: Debug the Application
    Set a break point, and debug the application.
Parent topic: Native COBOL Tutorials
Related concepts
OpenESQL Assistant


Tutorial: Create a SQL Server Database

This tutorial takes you through the process of using Microsoft SQL Server 2008 Management Studio to create a SQL Server database and to create the schemas and tables required to complete the OpenESQL Assistant tutorials.

  1. Go to CreateAndLoadOESQLDemo.txt.

    This SQL script creates the SQL Server database.

  2. Using your browser's Save As feature, save this as a flat text file on a local drive. Name the file CreateAndLoadOESQLDemo.sql.
    Note: If your browser adds any extraneous text, edit the script file to remove the extraneous text.
  3. Start the Microsoft SQL Server Management Studio.
  4. Connect to the server where you want to create your database.
    Note: The user ID and password you provide must log you on to SQL Server with dbadmin or sysadmin permissions that enable you to create a SQL Server database.
  5. Open and execute CreateAndLoadOESQLDemo.sql.

    This SQL script creates a SQL Server database named OESQLDemo, and creates the schemas and tables required to complete the OpenESQL Assistant tutorials.

  6. Close SQL Server Management Studio.
Note: As an alternative, you can create the SQL Server database from the command line as follows:
  1. At a command prompt, change to the directory where you saved the CreateAndLoadOESQLDemo.sql file.
  2. Enter:

    sqlcmd -S . -E -i CreateAndLoadOESQLDemo.sql

Parent topic: Tutorials: OpenESQL Assistant
Next topic: Tutorial: Create and Configure an Eclipse Project


Tutorial: Create and Configure an Eclipse Project

In this tutorial, you create an Eclipse COBOL project to use as you complete the remainder of these tutorials.

Requirements
Before attempting this tutorial, you must complete Tutorial: Create a SQL Server Database.
Launch Enterprise Developer for Eclipse
This procedure varies depending on your Windows version. If you need instructions, see To start Enterprise Developer.
Create a New COBOL Project
In this set of tutorials, you create a COBOL application that uses ODBC, and the OpenESQL ODBC runtime.
  1. Start Enterprise Developer. If you need instructions, see To start Enterprise Developer.
  2. From the Eclipse IDE, click File > New > COBOL Project.
  3. In the Name field, type OESQLAssistantTutorial.
  4. In the Location field, specify a directory in which to store the project; then click OK.

    Eclipse creates a new project named OESQLAssistantTutorial.

Create a COBOL Program
The new project contains no programs, so you need to add a new program to use in a later tutorial.
  1. From the COBOL Explorer, right-click the OESQLAssistantTutorial project and select New > COBOL Program.
  2. Click OK. This creates a default COBOL program named Program1.cbl and compiles it automatically.
  3. Close the Program1.cbl file.
Set Project Properties
By default, this application connects to the database via ODBC. To provide optimal cursor behavior, including isolation level and lock concurrency settings, you must set the BEHAVIOR parameter for the SQL BEHAVIOR compiler directive option.
  1. From the COBOL Explorer, right-click the OESQLAssistantTutorial project and select Properties.
  2. Expand Micro Focus > Project Settings > COBOL > SQL Settings.
  3. Check EXEC SQL.
  4. From the Preprocessor Type drop-down list, select OpenESQL.
  5. Scroll down the Settings list, and select BEHAVIOR.
  6. From the Value drop-down list, select ANSI.
  7. Click Apply.
Parent topic: Tutorials: OpenESQL Assistant
Previous topic: Tutorial: Create a SQL Server Database
Next topic: Tutorial: Set OpenESQL Assistant Configuration Options
Related tasks
To start Enterprise Developer


Tutorial: Set OpenESQL Assistant Configuration Options

You can configure several features within OpenESQL Assistant, but for the purposes of this tutorial, you change just the value of the Type COBOL Variable setting. This setting determines the method used at runtime to resolve host variable definitions. By setting this option to SQL Type, your compiled application communicates with the OpenESQL ODBC runtime, improving performance.

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create and Configure an Eclipse Project
Set the Type COBOL Variable Option
  1. In Eclipse, click Window > Preferences; then expand Micro Focus > Database and select OpenESQL Assistant.
  2. Change the value of Type COBOL Variable from Standard to SQL Type.
  3. Be sure Mode is set to ODBC; then click OK.
Parent topic: Tutorials: OpenESQL Assistant
Previous topic: Tutorial: Create and Configure an Eclipse Project
Next topic: Tutorial: Catalog a Connection


Tutorial: Catalog a Connection

Before you can connect to the SQL Server database you created earlier, you must catalog it using the ODBC Data Source Administrator (32-bit).

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create and Configure an Eclipse Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
Start the ODBC Data Source Administrator (32-bit)
This tool is available from your Start menu or Start > Apps page, depending on your Windows operating system.
Start > Apps Page
Go to your Start > Apps page, and click the ODBC Data Source Administrator (32-bit) tile that appears under Micro Focus Enterprise Developer.
Start Menu
Click Start > All Programs > or All Apps > Micro Focus Enterprise Developer > Enterprise Developer for Eclipse > Data Tools > Data Connections > ODBC Data Source Administrator (32-bit).
Catalog the OESQLDemo Connection
Using the ODBC Data Source Administrator, you catalog a 32-bit connection to your SQL Server database.
  1. From the ODBC Data Source Administrator, click the System DSN tab; then click Add.
  2. From the list of drivers, select the most recently installed version of SQL Server Native Client; then click Finish.
  3. In the Name field, type OESQLDemo. This is the name of the ODBC connection.
  4. From the drop-down list, select a SQL Server, or type the name of a server such as (local) or (localdb\v11.0), depending on what SQL Server product you have installed; then click Next.
  5. On the Authenticity dialog box, click Next to use Windows authentication.
  6. Change the default database to OESQLDemo; then click Next.
  7. Click Finish to save your changes.
  8. Click Test Data Source to ensure that the connection works properly.
  9. Click OK to clear the message.
  10. Click OK twice to exit the ODBC Data Source Administrator.
Refresh the Database Connection
For OpenESQL Assistant to recognize the connection you have cataloged, you must refresh the connection list in the OpenESQL Assistant.
  • In the OpenESQL Assistant, click Refresh list of data sources [image].

This completes the tutorial. Next, please complete Tutorial: Build and Test a Query.

Parent topic: Tutorials: OpenESQL Assistant
Previous topic: Tutorial: Set OpenESQL Assistant Configuration Options
Next topic: Tutorial: Build and Test a Query


Tutorial: Build and Test a Query

We are now ready to build a query that we can embed into a COBOL program and run. In this scenario, we are interested in retrieving the first and last names of our employees and the salary for each. So we'll build the query to access the EMP table and return the data from three columns: FIRSTNME, LASTNAME, and SALARY.

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create and Configure an Eclipse Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
  • Tutorial: Catalog a Connection
Start OpenESQL Assistant
If you have closed the OpenESQL Assistant, start it up again:
  • In Eclipse, click Run > Tools > Data Tools > OpenESQL Assistant.
Select a Table
  1. On the OpenESQL Assistant tree view, check the box adjacent to the OESQLDemo entry. This expands to show all available tables in the database.
    Note: The time required to connect to SQL Server can vary depending on the type and location of the SQL Server database to which you are connecting.
  2. Check the box next to EMP(dbo).

    The Select Type of Query to Create dialog box enables you to choose the type of query you want to generate. In this case, you want to create a simple SELECT CURSOR statement. OpenESQL Assistant generates a default cursor name that you can override; however, in this case you should accept the default.

  3. Click SELECT (cursor); then click OK.

    The OpenESQL Assistant marks the table with check mark, generates the query, and places the generated code on the Query tab.

    The columns in your selected table appear on the tree view with an alias of "A" prepended to the column name. For SELECT queries only, OpenESQL Assistant assigns the alias of A to the first table you select for a query, B to the second table if you join another table to the query, C for the next, etc. By prepending the table alias to each column name, you can easily identify the table to which a column belongs even if the same column name appears in more than one table.

Select Columns
You want this SQL query to return the first and last name of each employee along with the pay rate for each.
  • Check the following column names:
    • A.FIRSTNME
    • A.LASTNAME
    • A.SALARY

    OpenESQL Assistant updates the Query tab with the appropriate code.

Test the Query
The SQL query is complete at this point, so you can test it.
  • Click Run Query Run Query.

    The OpenESQL Assistant shows the results of the query on the Results tab.

Parent topic: Tutorials: OpenESQL Assistant
Previous topic: Tutorial: Catalog a Connection
Next topic: Tutorial: Generate and Embed an SQL Program


Tutorial: Generate and Embed an SQL Program

Now that the SQL query has been generated, you can use OpenESQL Assistant to generate a generic COBOL program and embed the query right into it.

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create and Configure an Eclipse Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
  • Tutorial: Catalog a Connection
  • Tutorial: Build and Test a Query
Generate a Generic SQL Program
  1. In the OpenESQL Assistant, click the Auxiliary Code tab.
  2. From the Statement Type drop-down list, select Generic SQL Program.

    OpenESQL Assistant generates a generic SQL program in the Generated Auxiliary Code box on the Auxiliary Code tab.

Embed the Generic SQL Program into the Eclipse Project
We're now ready to embed our generic SQL program into the current Eclipse project.
  1. From the Auxiliary Code tab, click Add Query to temporary file Add Query to temporary file.
  2. Click Save temporary file to disk Save temporary file to disk, and browse to the directory contains the Program1.cbl file you created earlier.
  3. Select program1.cbl; then click Save. A prompt appears, asking if you want to replace the current file.
  4. Click Yes.
  5. Change to the Eclipse IDE. A prompt appears to tell you that the file contents have changed.
  6. Click Yes. The program now appears in the Eclipse IDE program editor. Eclipse automatically saves the file.
Embed the SQL Query
Next, you embed the generated SQL query into Program1.cbl.
  1. From the OpenESQL Assistant, click the Query tab; then click Add Query to temporary file Add Query to temporary file.
  2. In the COBOL Editor, place the cursor on the line just after the comment:
    *> Put your program logic/SQL statements here
  3. Right-click; then select Paste.

    OpenESQL Assistant inserts the query into the program.

Parent topic: Tutorials: OpenESQL Assistant
Previous topic: Tutorial: Build and Test a Query
Next topic: Tutorial: Provide Additional Code


Tutorial: Provide Additional Code

Your new application will not compile and run unless you provide code that declares the table, provides a COBOL record to receive the data, and provides a COBOL record for indicator variables. You can use OpenESQL Assistant to generate a copybook that contains all of this code and an INCLUDE statement to call the copybook. You can also use OpenESQL Assistant to embed the INCLUDE statement into the program.

You want to send the output from the application to the console in a readable format. This requires additional code that you enter into the program manually.

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create and Configure an Eclipse Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
  • Tutorial: Catalog a Connection
  • Tutorial: Build and Test a Query
Generate a Copybook
You can generate a copybook using the Host Variable Declarations feature on the Auxiliary Code tab of the OpenESQL Assistant.
  1. From the OpenESQL Assistant tree view, click the EMP(dbo) table to select it; then right-click and select Generate DCLGEN from the context menu.

    OpenESQL Assistant generates the copybook and brings up the Generate Host Variable Declarations dialog box, giving you the opportunity to name it. The default name of the copybook is tablename.cpy. In this case, the name of the generated copybook is EMP.cpy.

  2. Save emp.cpy to the default folder, which is your current Eclipse project folder.

    On the Auxiliary Code tab, you see that OpenESQL Assistant has also generated an INCLUDE statement to call the copybook from the program.

The following shows the code generated in the EMP.cpy copybook:
       *> -------------------------------------------
       *> 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 System.DateTime.
       01  EMP-JOB                            STRING.
       01  EMP-EDLEVEL                        BINARY-SHORT.
       01  EMP-SEX                            STRING.
       01  EMP-BIRTHDATE                      type System.DateTime.
       01  EMP-SALARY                         DECIMAL.
       01  EMP-BONUS                          DECIMAL.
       01  EMP-COMM                           DECIMAL.
       *> -------------------------------------------
       *> COBOL INDICATOR VARIABLES FOR TABLE EMP
       *> -------------------------------------------
       01  EMP-WORKDEPT-NULL                  BINARY-SHORT.
       01  EMP-PHONENO-NULL                   BINARY-SHORT.
       01  EMP-HIREDATE-NULL                  BINARY-SHORT.
       01  EMP-JOB-NULL                       BINARY-SHORT.
       01  EMP-EDLEVEL-NULL                   BINARY-SHORT.
       01  EMP-SEX-NULL                       BINARY-SHORT.
       01  EMP-BIRTHDATE-NULL                 BINARY-SHORT.
       01  EMP-SALARY-NULL                    BINARY-SHORT.
       01  EMP-BONUS-NULL                     BINARY-SHORT.
       01  EMP-COMM-NULL                      BINARY-SHORT.
Embed the INCLUDE statement
You need to embed the generated INCLUDE statement into your program.
  1. From the Auxiliary Code tab, click Add Query to temporary file Add Query to temporary file.
  2. In the COBOL Editor, place the cursor on the line just after the EXEC SQL INCLUDE SQLCA statement, in the same column.
  3. Right-click; then select Paste.

    OpenESQL Assistant inserts the query into the program.

  4. Save the OESQLAssistantTutorial project. Eclipse automatically rebuilds the project.
  5. Close the OpenESQL Assistant.
Add Code to Format Output
When you run this application, you want to be able to see the results of the query as easily as you can see them on the Results tab in the OpenESQL Assistant. To achieve this, you need to add some code to the program that formats SALARY data, and code that sends all data to the console in a readable format.
  1. In the COBOL Editor, type the following working-storage record after the EXEC SQL INCLUDE EMP END-EXEC statement:
    01  EDIT-PAY     PIC Z,ZZ99.99.
  2. Scroll down to the following IF statement:
    IF SQLCODE=0
  3. Place your cursor on the next line down and insert the following MOVE statement:
    MOVE EMP-SALARY TO EDIT-PAY
  4. Replace the following DISPLAY statement:
    DISPLAY 'ROW FOUND'

    with

    DISPLAY 'NAME: ' EMP-LASTNAME ', ' EMP-FIRSTNME '   SALARY: ' EDIT-PAY UPON CONSOLE
  5. Save the OESQLAssistantTutorial project. Eclipse automatically rebuilds the project.
Parent topic: Tutorials: OpenESQL Assistant
Previous topic: Tutorial: Generate and Embed an SQL Program
Next topic: Tutorial: Debug the Application


Tutorial: Debug the Application

Requirements
Before attempting this tutorial, you must complete the following tutorials in the order listed:
  • Tutorial: Create a SQL Server Database
  • Tutorial: Create and Configure an Eclipse Project
  • Tutorial: Set OpenESQL Assistant Configuration Options
  • Tutorial: Catalog a Connection
  • Tutorial: Build and Test a Query
  • Tutorial: Generate and Embed an SQL Program
  • Tutorial: Provide Additional Code
Add a Break Point
The program sends output to the console, and you want the application to pause at the point where you can see the output.
  1. In the COBOL Editor, scroll down to the following statement:
    EXEC SQL DISCONNECT CURRENT END-EXEC
  2. In the gray area to the left of the statement, double click to toggle a break point.
  3. Save the OESQLAssistantTutorial project. Eclipse automatically rebuilds the project.
Debug the Application
  1. Press F11 to start debugging.
  2. Press either F5 or F6 to execute statements until you get to your break point.
  3. If the console is not visible, minimize the Eclipse IDE. You should see the console output.
  4. Press F5 or F6 again to complete the debugging process.

This completes the OpenESQL Assistant tutorials.

Parent topic: Tutorials: OpenESQL Assistant
Previous topic: Tutorial: Provide Additional Code


Tutorial: Data File Editor

Note: This tutorial is only applicable to Windows platforms.

This tutorial utilizes the demonstration application that was used for the Classic Data File Tools version. It guides you through using the Data File Editor to: view the existing data file in the demonstration application; edit that data file, including applying a number of record layouts to the file; create and edit a new indexed data file.

During this tutorial, you are required to use the Classic Data File Tools to create a structure file, which is then applied to a data file and used in the new Data File Tools.

  1. Import and Build Sample Project
  2. Start Data File Editor
  3. View the Data File Unformatted
  4. Create a Record Layout
  5. View the Data File Formatted
  6. Filter the Data File
  7. Edit a Record
  8. Create a New Data File
  9. Create a New Record
  10. Insert a Record
  11. Delete a Record
Parent topic: Native COBOL Tutorials
Related concepts
Data File Editor


Import and Build Sample Project

  1. Start Eclipse.
  2. Click File > Import.
  3. Expand General, then click Existing Projects into Workspace.
    Note: Be sure you know the location of your Eclipse workspace. The default is %USERPROFILE%\workspace.
  4. Click Next.
  5. Click Browse next to Select root directory and navigate to the DataToolsDemo samples directory installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\ClassicDataToolsDemo, then click OK.
  6. In the Projects box, ensure the ClassicDataToolsDemo project is checked.
  7. Check Copy projects into workspace, then click Finish.

    This creates a ClassicDataToolsDemo subdirectory in your workspace location, and displays the ClassicDataToolsDemo project in the Application Explorer.

  8. Right-click the project and select Rename, then type DataToolsDemo in the New name field and click OK. By default, Eclipse builds the project automatically and creates the dfdstaff.idy file in the New_Configuration.bin project subfolder; if it has not, on the Project menu, select Build Automatically. You will need dfdstaff.idy later in this tutorial.
Parent topic: Tutorial: Data File Editor
Next topic: Start Data File Editor


Start Data File Editor

To start Data File Editor from your Windows desktop, click Start > All Programs > <product-name> > Data Tools > Data File Tools.

To start Data File Editor from your Enterprise Developer command prompt, type mfdatatools2.

Parent topic: Tutorial: Data File Editor
Previous topic: Import and Build Sample Project
Next topic: View the Data File Unformatted


View the Data File Unformatted

To view the data file supplied with the project, load it into Data File Editor:

  1. From the Micro Focus Data File Tools window, click File > Open > File, then navigate to the DataToolsDemo project directory.
  2. Select datavseq.dat, then click Open.

    The Open Data File dialog box appears.

  3. Ensure the Structure File (optional) field is empty.

    Note that the File Details section is populated with values; these are taken from the file header of the .dat file.

  4. Click Open Shared.

    datavseq.dat is opened in Shared mode and its contents are displayed. In Shared mode, the file is opened with a file locking status of shared, allowing other users to open the file in Shared mode.

    Each record is unformatted; that is, it is shown as one continuous line of text. Records are easier to view and edit if they are formatted; for that, you need to create a record layout within a structure file, then apply it to the data file.

    Note: Some characters that cannot be displayed correctly are displayed as a period. You can still display the hexadecimal code for each of these characters, by clicking [image] (Toggle Hex).
Parent topic: Tutorial: Data File Editor
Previous topic: Start Data File Editor
Next topic: Create a Record Layout


Create a Record Layout

You can create a record layout file from the Data Division of a COBOL program that uses the data file. By using the .idy file from the compiled program, you can display the records in a structured way, where the fields are formatted to their intended size.

The datavseq.dat data file contains three types of record: employee, manager, and executive. You need to create a layout for each type of record, and then set criteria for when a particular layout is used. Of the three layouts, you define one as the default; all others are defined as conditional.

In order to create a record layout, you must create a structure file using the Classic Data File Tools editor.

  1. From an Enterprise Developer command prompt, type mfdatatools, then press Enter.

    The Classic Data File Tools editor is opened.

  2. Click File > New > Record Layout and click OK.
  3. Navigate to the dfdstaff.idy file (located in the output path of the DataToolsDemo project ), then click Open.

    A Layout window appears, containing the Data Division of dfdstaff.cbl.

  4. From the left-hand pane, right-click 01 EMPLOYEE-REC from the FD MF-File Section, then select New Layout.
  5. Select Default Layout, Next, then click Finish.

    The default layout is displayed in the right-hand pane.

  6. In the left-hand pane again, right-click 01 MANAGER-REC, then select New Layout.
  7. Select Conditional Layout, Next, then click Finish.

    The MANAGER-REC conditional layout is displayed in the right-hand pane.

  8. Expand 01 MANAGER-REC > MN-CODE, then right-click 03 MN-POSITION and select Properties.

    The Field Properties dialog box appears.

  9. From the Condition section, select IS = TO.
  10. In the middle field, type M (upper case), then click OK.

    This M indicates a Manager record type.

  11. Repeat steps 6 through 10 to create a conditional layout for the Executive record type; substituting the previous structures for 01 EXECUTIVE-REC, EX-CODE, and 03 EX-POSITION, and using E to indicate the record type.
  12. Click [image] (Save).

    The Save As dialog box appears.

  13. Navigate to the location of datavseq.dat, then in the File name field, enter datavseq.str and click Save.

    The structure file containing three layouts is now created, which means you can now view the corresponding data file formatted. You can now close Classic Data File Tools.

Parent topic: Tutorial: Data File Editor
Previous topic: View the Data File Unformatted
Next topic: View the Data File Formatted


View the Data File Formatted

To view the records formatted, you must apply the record layout file to the data file, which you do when opening the data file.

  1. If datavseq.dat is still open in Data File Editor, click [image] on the tab to close it.
  2. From the Micro Focus Data File Tools window, click File > Open > File, then navigate to the DataToolsDemo project folder.
  3. Select datavseq.dat again, then click Open.

    The Open Data File dialog box appears.

    Because you saved the structure file with the same name as the data file, and in the same location, it is already selected in the Structure File (optional) field. (If you had saved it elsewhere or named it differently, you would need to click Browse and select it.)

  4. Click Open Shared.

    The data file is opened in Shared mode, and the records are displayed using the record layouts in the structure file:

  5. Scroll through the records, and notice how the layout changes depending on the value in the MN-POSITION, EX-POSITION, and EM-POSITION fields.
Parent topic: Tutorial: Data File Editor
Previous topic: Create a Record Layout
Next topic: Filter the Data File


Filter the Data File

You can filter the records displayed based on one or more criteria within the record.

  1. In the Filter group, click [image] (Filter).

    The Filter dialog box appears.

    Filters are constructed by adding one or more conditions.

  2. Click New Ref.

    The basic reference elements appear.

  3. In the Field fields, enter 10 as the start position, and 3 as the number of positions on from that in which to filter within each record.

  4. Ensure the Operator field is set to =.
  5. In the Value field, enter "mr ".
    Note: Ensure that you include the space shown at the end of the string.
  6. Click New Field.

    The basic field elements appear.

    Note: The New Field option is only available when a structure file has been applied to the data file.
  7. Click [image] to the right of EM-POSITION and select MN-AGE.
  8. Change the Operator field to <.
  9. In the Value field, enter 40.
  10. Ensure Match All is selected.

    This means that only records that match both criteria are displayed.

  11. Click Filter.

    The results filter on the records for all male managers under 40 years of age:

  12. To remove the filter, click [image] in the Filter group and select None.

    All records in the data file are redisplayed.

Parent topic: Tutorial: Data File Editor
Previous topic: View the Data File Formatted
Next topic: Edit a Record
Related reference
Filter Operators
Filtering a Data File


Edit a Record

The file is still open in Shared mode, and so cannot be edited until you switch to Exclusive mode; although, you will only be able to enter Exclusive mode if no other user has the file open (in either Shared or Exclusive mode).

  1. With datavseq.dat displayed using the record layouts, in the File group, click [image] (Switch to Exclusive Mode).

    The file lock status now changes to Exclusive, and the icon in the File group changes to [image] (Switch to Shared Mode).

  2. Select the record for Mr Plastow, then click [image] (Edit Record) in the Record group.

    Notice how the record is using the default layout, because the first field is not set to 'M' or 'E' (either of which would result in a conditional layout being used).

  3. Select the value for 03 EM-JOB-TITLE field.
  4. Type 'Lead Developer', then click [image] (Save Record).
    Note: When editing from within a layout, the edit mode is always Overwrite.
  5. Click Yes to confirm.

    The record is edited and saved.

Parent topic: Tutorial: Data File Editor
Previous topic: Filter the Data File
Next topic: Create a New Data File


Create a New Data File

You are now going to create a new indexed data file, including the index keys required of an indexed file.

  1. In the File group, click [image] (New File).

    The Create New File dialog box appears.

  2. In the Filename field, enter the path to the DataToolsDemo project folder and append \dataidx.dat.
  3. In the File Details section, select the following:
    Field | Setting
    Organization | Indexed
    Format | 8 - IDXFORMAT8
    Encoding | ANSI
    Max Length | 10
  4. Click Define Keys.

    The Key Information dialog box appears.

  5. Click [image] (Insert Before).

    A component is created for the primary key.

  6. Click the Component tab.
  7. Select Component 0 for the primary key, then alter the length of the key component to 3.

  8. On the Key tab, click [image] (Insert After).

    Alt Key 1 is created in the Key Structure pane.

  9. On the Component tab, select Component 0 for the alternate key, and set the values to Offset: 3, Length: 10, then click OK.

    Notice how the Max Length field has been increased (from 10) based on the length values of your keys.

  10. Click Create File.

    The empty file is created and displayed in the editor. Next, you can add records to it.

Parent topic: Tutorial: Data File Editor
Previous topic: Edit a Record
Next topic: Create a New Record


Create a New Record

  1. With the new indexed file in the editor, click [image] (Insert Record) in the Record group.

    As you do not have a layout applied to the data file, you must use the free text editing field in the bottom pane.

  2. Type 001Monday, then click [image] (Save Record).
  3. Click Yes to confirm.
  4. Repeat the previous steps with the following details to create a further five records.
    Record text
    002Tuesday
    004Thursday
    005Friday
    006Saturday
    007Sunday

    The records should be displayed in ascending order, using the primary key, which is displayed in red.

Parent topic: Tutorial: Data File Editor
Previous topic: Create a New Data File
Next topic: Insert a Record


Insert a Record

  1. With the new file still open in the editor, select the record that starts 004, then right-click and select Insert Indexed Record.

  2. In the free text editing field, type 003Wednesday, then click [image] (Save Record).
  3. Click Yes to confirm.

    The new record is inserted above the selected record.

Parent topic: Tutorial: Data File Editor
Previous topic: Create a New Record
Next topic: Delete a Record


Delete a Record

  1. With the new file still open in the editor, select the record that starts 007, then right-click and select Delete Record.
  2. Click Yes to confirm.

    The record is deleted.

  3. Click [image] in the File group to close the file.

    This concludes the tutorial.

Parent topic: Tutorial: Data File Editor
Previous topic: Insert a Record


Tutorial: Classic Data File Tools

Shows you how to convert a data file to a variable length indexed sequential file, and then view it in various ways, formatted and unformatted, using the Classic Data File Editor.

You use the Classic Data File Tools to convert, browse, edit and create data files used by an application.

Using the Classic Data File Tools, you can examine data files to see how an application has updated them, or create and edit a file to provide test data for an application. Files can be in any COBOL format and you can view them at both the record and field levels. You can convert between formats and character sets.

Demonstration Application

The demonstration application used in this tutorial consists of a data file and the COBOL source program that maintains it. The data file is a variable length sequential file, containing details of staff in three record types: employee, manager and executive. In this session you convert it to a variable length indexed sequential file, and then view it in various ways, formatted and unformatted, using the Data File editor.

Order

Complete the tutorial in the following order:

  1. Import and Build an Eclipse Project
  2. Convert a File
  3. View a Data File Unformatted
  4. Create a Record Layout File
  5. Create the Default Record Layout
  6. Create the Conditional Record Layouts
  7. Save the Record Layout File
  8. View a Data File Formatted
  9. Access Information about a Record Layout File
  10. View Files in Hexadecimal
  11. Print a Data File
  12. Edit Multiple Data Files
  13. Create a New Data File
  14. Convert a File's Character Set
  15. View the EBCDIC File
Parent topic: Native COBOL Tutorials


Import and Build an Eclipse Project

To enable you to work on the data files for an application, you need to import the application files from the demonstration program into an Eclipse project where Eclipse builds the application automatically.

  1. Start Enterprise Developer.
  2. Click File > Import.
  3. Expand General; then click Existing Projects into Workspace.
    Note: Be sure you know the location of your Eclipse workspace. The default is %USERPROFILE%\workspace.
  4. Click Next.
  5. Click Browse next to Select root directory and navigate to the ClassicDataToolsDemo samples directory installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\ClassicDataToolsDemo; then click OK.
  6. In the Projects box, ensure the ClassicDataToolsDemo project is checked.
  7. Check Copy projects into workspace; then click Finish.

    This creates a ClassicDataToolsDemo subdirectory to your workspace location and adds the ClassicDataToolsDemo project to Application Explorer view. By default, Eclipse builds the project automatically and creates the dfdstaff.idy file in the New_Configuration.bin project subfolder. You use dfdstaff.idy later in this tutorial.

  8. To start Classic Data File Tools, do one of the following:
    Windows 7 and Earlier
    • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > Classic Data File Tools.
    Windows 8.1
    • From the Windows Start screen, click the Classic Data File Tools tile.
    Windows 10 and Later
    • From your Windows desktop, click Start > Micro Focus Enterprise Developer > Classic Data File Tools.
Parent topic: Tutorial: Classic Data File Tools
Next topic: Convert a File


Convert a File

To make an indexed sequential copy of the supplied sequential file:

  1. In Classic Data File Tools, click Tools > Convert.
  2. To supply the input file details, click the Browse button and use the Open dialog box to select the file datavseq.dat from the ClassicDataToolsDemo project directory.

    The details for the input file and the output file are initialized with the information read from the file header for datavseq.dat.

  3. In the lower part of the dialog box, enter the following details for the output file (leave the remaining fields unchanged):
    Filename: staff.dat
    Format: Micro Focus
    Organization: Indexed Sequential
  4. Click Define Keys; then click Insert Key.

    The field to be used as the key is at the beginning of the record, and is seven bytes long.

  5. Set Key Offset to 0 and Key Length to 7; then click OK.
  6. Click Convert.
  7. Click OK on the message saying the data file conversion is complete.

    The Data File Convert dialog box reappears so you can convert more files.

  8. Click Cancel.
  9. Check the ClassicDataToolsDemo project directory. The Data File Converter has created the new files staff.dat, which contains the record data, and staff.idx, which contains the record key information.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Import and Build an Eclipse Project
Next topic: View a Data File Unformatted


View a Data File Unformatted

To view the data file you just created, load it into the Data File Editor:

  1. In Classic Data File Tools, click File > Open and navigate to the ClassicDataToolsDemo project folder.
  2. Select staff.dat; then click Open.

    Depending on options set, either the Data File Editor window appears immediately or a message box appears, explaining that all edits to indexed and relative file types are applied immediately.

  3. If the message appears, and you want to prevent it from appearing again, check Do not show this message again; then click OK.

    The Data File Editor loads the contents of staff.dat and displays them as shown here:

    Figure 1. Data File Editor Window
    The IDE with a Data File Editor Window

    Each record is shown as one line. Because the Data File Editor does not know the lengths of the fields in the record, each line is simply a continuous line of text; the records are unformatted. Non-character fields such as COMP items generally display as non-standard characters or, if they don't correspond to any printable character, as The IDE with a Data File Editor Window.

  4. Experiment with any of the following editing features:
    • Edit the file by typing over the existing data.
    • Click Search > Data File Editor and use any of the following methods to search the data file:
      • Data File Find and Replace
      • Find On Current Key

        This option is available for indexed files only. Depending on whether the Data File Editor window is open and, if so, the current key of reference, this option name can also read as Find on prime key and Find on alternate key number n.

      • Goto record
      • Locate Field

        Use this option to find a field within the current record. This option is available only when you have a formatted view available for the data file. To obtain a formatted view involves loading a record layout file which we shall do later on in this tutorial.

    • Become familiar with the information on the status line at the bottom of the main window. The status line shows various statistics, depending on the file details:
      • Relative record number (relative files only)
      • Length of the selected record, followed by (minimum length, maximum length) if variable length
      • Number of records (sequential files only)
      • Cursor position - line number and column position, both starting at 0
  5. Right-click in the Data File Editor window and select File Information from the context menu. The File Information window displays information such as the file format and organization.
  6. To view more information about the file, click the Keys and the General tabs.
  7. Click Cancel to close the File Information window, but do not close the Data File Editor.
Note: The Data File Editor window might have a pane visible on the right side, displaying A record layout file must be loaded before using this window. We use this option in a later section of this tutorial.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Convert a File
Next topic: Create a Record Layout File


Create a Record Layout File

If it knows the layout of the fields, the Data File Editor can display file contents formatted. You create a record layout file from the Data Division of a COBOL program that uses the file. The program must be compiled for the Data File Editor to access the necessary information, which is why it was necessary to compile the demo application at the start of this tutorial.

Our data file, staff.dat, contains three record types: employee, manager, and executive. To differentiate between the types, you define the layout of each type of record, and how to identify the type. Of the three record types, you can define one type as the default; all others are defined as conditional.

  1. In Classic Data File Tools, click File > New.
  2. Select Record Layout; then click OK.
  3. Navigate to the New_Configuration.bin project subfolder.
  4. Select dfdstaff.idy; then click Open.

    The Record Layout Editor window opens, showing a tree view of the Data Division of dfdstaff.cbl.

Parent topic: Tutorial: Classic Data File Tools
Previous topic: View a Data File Unformatted
Next topic: Create the Default Record Layout
Related tasks
View the EBCDIC File
View a Data File Formatted


Create the Default Record Layout

  1. On the Record Layout Editor tree view, expand the FD MF-FILE entry.
  2. Right-click 01 EMPLOYEE-REC; then click New Layout on the context menu.

  3. Default Layout should be selected automatically as you have not yet defined a default layout; however, if it is not, click Default Layout to set EMPLOYEE-REC as the default record layout.
  4. Click Next; then click Finish.

    The EMPLOYEE-REC-DEFAULT layout appears in the right pane.

Parent topic: Tutorial: Classic Data File Tools
Previous topic: Create a Record Layout File
Next topic: Create the Conditional Record Layouts


Create the Conditional Record Layouts

  1. On the Record Layout Editor tree view, right-click 01 MANAGER-REC; then click New Layout on the context menu.
  2. Conditional Layout should be selected automatically as you have already defined a default layout; however, if it is not, then you have not correctly defined the default record layout. In this case, return to the Create the Default Record Layout topic in this tutorial.
  3. Click Next; then click Finish. This adds MANAGER-REC as a conditional layout as seen in the right pane.

    You now need to specify the field and condition that identifies this conditional record type.

  4. In the right pane, expand MANAGER-REC > 01 MANAGER-REC > 02 MN-CODE.
  5. Right-click 03 MN-POSITION; then click Properties on the context menu. The Field Properties dialog box appears.
  6. From the Condition drop-down list, select IS = TO.
  7. In the Condition box directly to the right of the drop-down list, type M (upper case). This M indicates a Manager record type. The two characters below the dotted line are the hexadecimal equivalent, arranged vertically. They should be 4 and D because M in ANSI is hex 4D.
  8. Click OK. A small red IF appears by 03 MN-POSITION in the right pane.
  9. Repeat steps 1 through 8 to create a conditional record layout for the Executive record type; substituting equivalent structures from 01 EXECUTIVE-REC and using E to indicate the record type. The hex equivalent for E is 45.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Create the Default Record Layout
Next topic: Save the Record Layout File


Save the Record Layout File

When the Data File Editor loads a data (.dat) file, it looks in the same folder for a record layout file with the same name as the data file but with extension .str. Our data file is named staff.dat; therefore you need to save the record layout file in the ClassicDataToolsDemo project folder and name it staff.str.

  1. Click File > Save; then navigate back up to the ClassicDataToolsDemo project folder.
  2. In the File Name field, type staff.str; then click Save.
  3. Click File > Close to close the Record Layout Editor.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Create the Conditional Record Layouts
Next topic: View a Data File Formatted


View a Data File Formatted

In this tutorial, the Data File Editor is already open with the staff.dat data file loaded. Here, we load the staff.str record layout file to apply it to the staff.dat data file.

Note: When the Data File Editor loads a data file, it looks in the current directory for a record layout file with the same prefix, and if found, automatically loads that record layout file and applies it to the data file. To apply a record layout file to a data file that is already open or whose name does not match that of the record layout file, you must load it explicitly.
  1. On the Data File Editor window that you left open earlier, click File > Data File Editor > Load Record Layouts.
  2. Select staff.str; then click Open.

    A new pane appears on the right where the Data File Editor has applied the formatting information from the record layout file. This pane shows a formatted view of a single record. The record layout name is at the top of the pane. At the top right are two navigation controls: the small up-arrow takes you to the previous record and the small down-arrow takes you to the next record.

    The pane on the left shows only the first few columns of the data file, but you can use the slider at the bottom to see the additional columns. As before, the data is shown as unformatted, one per line.

    Figure 1. The Data File Editor Window with a Record Layout Loaded

  3. In the right pane, you can type over the existing information in the Value column to change it. In addition, you can also use the editing features explained in the View a Data File Unformatted topic of this tutorial. These are the same for both formatted and unformatted data.
  4. Click a record in the left pane to view its formatted data in the right pane.
  5. Click each record in the left pane sequentially and notice how the formatted view in the right pane changes to match the selected record type as you move through the file.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Save the Record Layout File
Next topic: Access Information about a Record Layout File
Related tasks
View the EBCDIC File
Create a Record Layout File


Access Information about a Record Layout File

You can access information that is associated with a data file, including its corresponding record layout file and the conditions applied by each conditional layout:

  1. Right-click in the Data File Editor window; then click File Information on the context menu.

    Because a record layout file is now associated with the data file staff.dat, the File Information window has a new tab: Record Layouts.

  2. Click the Record Layouts tab.

    This tab displays information about the record layout file staff.str that is associated with staff.dat. The top of the tab shows the name and location of the record layout file.

  3. Under Layout Name, click MANAGER-REC.

    The Conditions box shows that, for Manager records, the field MN-POSITION is equal to M.

  4. Under Layout Name, click EXECUTIVE-REC.

    The Conditions box shows that, for Executive records, the field EX-POSITION is equal to E.

  5. Click Cancel to close the File Information window.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: View a Data File Formatted
Next topic: View Files in Hexadecimal


View Files in Hexadecimal

You can use Data File Editor to view and edit your data in hexadecimal:

  1. Right-click anywhere in the Data File Editor window and select Show Hex on the context menu.

    New panes appear at the bottom of the window. The left pane shows the selected record from the top left pane, with the hex beneath. For group and elementary field items only, the right pane shows the selected field from the top right pane, with the hex beneath.

    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. If you can't see both lines of hex, make the window bigger by dragging its bottom edge downward.

  2. Right-click within the Data File Editor window and click Show Hex on the popup menu.

    The check mark by this menu item disappears, and the hex panes disappear.

Parent topic: Tutorial: Classic Data File Tools
Previous topic: Access Information about a Record Layout File
Next topic: Print a Data File


Print a Data File

You can print a data file from the Data File Editor using the Print function. To see what the data file would look like if printed, you can use the Print Preview function. You can print either the formatted or unformatted view, and you can also choose whether to print the current record, all records or partial records.

To preview a print of the unformatted view of a data file:

  1. Click in the left pane of the Data File Editor window; then click File > Print Setup.
  2. Set Orientation to Landscape; then click OK.
  3. Select File > Print Preview.
  4. Check Header Text and type Print of Data File STAFF.DAT into the corresponding field.
  5. Check the following:
    • Page numbers
    • Ruler
    • Record numbers
    • Hexadecimal values
  6. In the Print range group, select All records and Whole record.
  7. Click Preview.

    A Preview window appears. You can use the buttons on the toolbar to zoom in and out, move around the window, and print.

  8. Click Close.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: View Files in Hexadecimal
Next topic: Edit Multiple Data Files


Edit Multiple Data Files

In Classic Data File Tools, you can use Data File Editor to display and edit several files at once, choosing various ways to position their windows within the main Data File Tools window.

To edit two data files, positioning their windows one above the other:

  1. Click File > Open, then navigate to and select datavseq.dat.

    A new Data File Editor window opens for datavseq.dat. Only the unformatted pane appears, as no record layout is associated with this file. The staff.dat file should already be open from the previous steps; if it isn't, repeat this step, selecting staff.dat as well.

  2. Click Window > Tile Horizontally.

    You can now see the Data File Editor windows for both datavseq.dat and staff.dat.

  3. Toggle between the windows by clicking alternatively on the tags for datavseq.dat and staff.dat near the bottom of the main window.
  4. Close both Data File Editor windows.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Print a Data File
Next topic: Create a New Data File


Create a New Data File

To create a fixed length sequential file:

  1. Click File > New
  2. Select Data File; then click OK.
  3. Click Browse, navigate to the ClassicDataToolsDemo project folder, then type newfile.dat into the File name field and click Save.
  4. In the Record details section, enter 20 into the Maximum Length field; then click Create.

    Because a fixed-length sequential file does not have a file header, you are prompted to save the file header details you have just entered.

  5. Click Yes.

    File header details are saved in a profile file in the same directory as the data file. Having a profile saves you from having to enter the file header details the next time you open the data file. Profile files have the same prefix as the data file with a .pro extension. Therefore, the profile file for this new data file is newfile.pro.

    A Data File Editor window appears, displaying File Empty.

    Now you can add and delete a few records.

  6. Right-click in the Data File Editor window and select Insert Record After on the context menu.

    The cursor is positioned at the start of the file.

  7. Type abc.
  8. Right-click in the Data File Editor window; then click Repeat Record on the context menu.

    A second record containing abc is added to the file.

  9. Click on the first record to select the record and type x.

    An update warning is displayed because you are attempting to change the record.

  10. Click No on the update warning message box.
  11. Right-click in the Data File Editor window; then click Delete Record on the context menu; then and click Yes on the Delete warning message box.

    The new record is deleted from the file and the cursor is positioned on the next record.

  12. Click File > Save.
  13. Close the Data File Editor window.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Edit Multiple Data Files
Next topic: Convert a File's Character Set


Convert a File's Character Set

To make an EBCDIC copy of the supplied sequential file:

  1. Click Tools > Convert.
  2. To supply the input file details, click the Browse button and use the Open dialog box to select the file datavseq.dat.

    The details for the input file and the output file are initialized with the information read from the file header for datavseq.dat.

  3. Check Convert character set.

    The character set for the output file, shown in the lower half of the dialog box, changes from ANSI to EBCDIC.

  4. Check Records contain non-text data items.

    The converter needs to know where the non-text data items (items such as COMP fields) are, so as not to convert them. Therefore, you need to specify a record layout file. You have already created one describing datavseq.dat.

  5. Click Select layout for conversion, and use the Browse button on the Select layout for conversion dialog box to select staff.str; then click OK.
  6. In the lower half of the dialog box, type ebcvseq.dat as the name of the new file; then click Convert.
  7. Click OK on the message saying the conversion is complete; then click Cancel.

    The new file, ebcvseq.dat, is created.

Parent topic: Tutorial: Classic Data File Tools
Previous topic: Create a New Data File
Next topic: View the EBCDIC File


View the EBCDIC File

When the Data File Editor is open, Classic Data File Tools shows an extra toolbar that includes a drop-down list you can use to switch the Data File Editor window between ANSI and EBCDIC. To display the EBCDIC file you just created:

  1. Click File > Open.
  2. Select ebcvseq.dat; then click Open.

    Garbage is displayed because Data File Editor is expecting ANSI.

  3. On the toolbar, use the drop-down list to change the character set from ANSI to EBCDIC.

    The file is displayed correctly.

    This field on the toolbar affects only the current display in the Data File Editor window.

    To look at the file in formatted view, you can use the record layout file you created earlier as the condition field value used to determine the record type is converted as required.

  4. To create an EBCDIC record layout file from the ANSI character set program you need to change Data Tools default character set to EBCDIC.
  5. Click Options > Data Tools; then click the General tab.
  6. Using the drop-down list, change the Character Set field to EBCDIC; then click OK.

    This makes the Data File Editor read and write all files in EBCDIC. You can now create and use a new record layout file, in the same way as you did in the previous topics of this tutorial.

  7. When finished, close the Data File Editor window.
  8. If you generally use the ANSI character set, click Options > Data Tools and change the character set back to ANSI; then click OK.
Parent topic: Tutorial: Classic Data File Tools
Previous topic: Convert a File's Character Set
Related tasks
Create a Record Layout File
View a Data File Formatted


Tutorial: Using the Callable File Handler

In the following tutorial you will walk through creating a single COBOL program that directly calls the File Handler API (often referred to as the Callable File Handler) to perform a number of file handling operations. The program will demonstrate how to perform a number of File Handling operations without the need to use the conventional COBOL file handling statements such as SELECT, OPEN, READ, and CLOSE.

By the end of the tutorial, you should have created a COBOL program that is similar to the one found in Appendix A, and running it will:

  • Create an indexed file.
  • Write a number of records to the file.
  • Close the file.
  • Rewrite an existing record and display the results
  • Tutorial
  • Appendices
Parent topic: Native COBOL Tutorials
Related reference
Appendix A - the source code


Tutorial

Follow the steps below to create the COBOL program:

  1. Create a Native COBOL Project
  2. Set the Project Properties
  3. Define the Operation Codes and FCD
  4. Define the Filename Area
  5. Define the Key Definition Block
  6. Define the Record Area
  7. Set up the FCD
  8. Call the Callable File Handler and Check the File Status
  9. Create, Write To, and Close an Indexed File
  10. Read From and Rewrite To the File
  11. Run the Application
Parent topic: Tutorial: Using the Callable File Handler


Create a Native COBOL Project

This tutorial is going to be run from within the IDE; although the program you will build will work perfectly well from the command line as well.

  1. Launch Enterprise Developer for Eclipse, and select an appropriate workspace.
  2. While in the COBOL perspective, click File > New > COBOL Project.

    The New COBOL Project dialog box appears.

  3. In the Project name field, type a name for the project.
  4. Click Finish.

    The project is created, and displayed in the COBOL Explorer pane.

  5. Click File > New > COBOL Program

    The New COBOL Program dialog box appears.

  6. In the Program name field, type a name for the program.
  7. Click Finish.

    The program is created, and displayed in the COBOL Explorer pane, under the COBOL Programs sub-folder of the project folder.

  8. Double-click the program to display it, and then in the editor, delete the line goback from near the end of the program.

    Program termination steps will be added back into the source code as you work through the rest of the tutorial.

Parent topic: Tutorial
Next topic: Set the Project Properties


Set the Project Properties

Some of the source code that you will paste into your program extends beyond column 72; therefore, changing the source format will avoid errors being generated due to truncated lines of code.
  1. In COBOL Explorer, ensure that your project is selected, then on the Project menu, click Properties.

    The Properties for <project-name> dialog box appears.

  2. Select Micro Focus > Project Settings > COBOL.
  3. On the COBOL screen, click the Source format field and then select Variable.
  4. Click Apply and Close.

    The source format is applied to the program.

You are now ready to add the code to your program, starting with the coding of the working-storage section.

Parent topic: Tutorial
Previous topic: Create a Native COBOL Project
Next topic: Define the Operation Codes and FCD


Define the Operation Codes and FCD

Before you create or open a file, you must set up a data area for the file's FCD. For ease of use, this program also sets up a number of pre-defined operation code values that you can call upon.

  1. In the working-storage section of Program1.cbl, paste the following code:
           01  opcode                       pic x(2).
         78  OP-QUERY-FILE              value x"0006".
         78  OP-OPEN-INPUT              value x"fa00".
         78  OP-OPEN-OUTPUT             value x"fa01".
         78  OP-OPEN-I-O                value x"fa02".
         78  OP-WRITE                   value x"faf3".
         78  OP-RELEASE                 value x"faf3".
         78  OP-REWRITE                 value x"faf4".
         78  OP-READ-NEXT               value x"faf5".
         78  OP-START-EQUAL             value x"fae9".
         78  OP-CLOSE                   value x"fa80".

    The opcode variable will be used throughout the running of this example, each time using one of the level-78 constant values shown to perform a specific operation.

  2. Just beneath the op codes, still in the working-storage section, paste the following code:
           01 fcd.
           copy "xfhfcd3.cpy".

    xfhfcd3.cpy is a copybook that is supplied with your product, defining all the possible fields that you may use to set up the FCD for the file that you will create. The tutorial will only use a small selection of the fields available.

  3. Press Ctrl+S to save the changes so far.
Next you'll define the name of the data file that you will create.
Parent topic: Tutorial
Previous topic: Set the Project Properties
Next topic: Define the Filename Area
Related reference
Operation Codes
File Control Description (FCD)


Define the Filename Area

Another pre-requisite of using the callable file handler is to set up a filename area: a data item containing the name of the data file, and depending on the type of file you are dealing with, a data item for the separate index file.
  1. Again, in the working-storage section, beneath the FCD definition, paste the following code:
           01 ex-filename                  pic x(260) value "idxfile.dat".
       01 ex-index-name	               pic x(100).

    These variables define the data file name and the separate indexed file (if the data file format uses one). Later, when setting up the FCD, you will set fcd-filename-address to the address of ex-filename, and fcd-idxname-adress to the address of ex-index-name.

    Note: This tutorial uses an IDXFORMAT8 file, which does not use a separate index file (.idx file); therefore, the ex-index-name variable is not necessary in the running of this tutorial, but is included to demonstrate its use if you were to use a data file that required a separate index file (for example, IDXFORMAT12).
  2. Press Ctrl+S to save the changes so far.

As you are going to be creating an indexed file, you also need to define a key definition block, which defines the index keys used in file operations on indexed files.

Parent topic: Tutorial
Previous topic: Define the Operation Codes and FCD
Next topic: Define the Key Definition Block
Related reference
Filename Area


Define the Key Definition Block

The key definition block has three distinct areas:
  • The Global Information area - this defines the size of the area that contains the key definitions, and the number of keys being defined.
  • The Key Definition area - this defines the characteristics of each key in the block
  • The Component Definition area - this defines the details of each component within each key defined in the previous area.
  1. Beneath the filename area definition, paste the following code:
           01 ex-keydef.
          47 key2length                pic 9(4)  comp-x.
          47 key-version               pic 9(2) comp-x value 2.
          47 filler                    pic 9(6)  comp-x. *> reserved
          47 key-count                 pic 9(4)  comp-x.
          47 filler                    pic 9(13) comp-x. *> reserved
  2. Next you need to paste the following key definition area:
          *  key-specification is repeated for the number of keys defined by
      *  key-count
          47 key-specification.
             49 component-count        pic 9(4) comp-x.
      * The offset for the component-specification for this key
             49 component-defs         pic 9(4) comp-x.
             49 key-flags              pic 9(2) comp-x.
                  78 KEY2KEYFLAG-DUPS-IN-ORDER        value h"40".
                  78 KEY2KEYFLAG-PRIME                value h"10".
                  78 KEY2KEYFLAG-SPARSE-KEY           value h"02".
             49 key-compression        pic 9(2) comp-x.
                  78 KEY2COMPRESS-TRAILING-NULLS      value h"08".
                  78 KEY2COMPRESS-TRAILING-SPACES     value h"04".
                  78 KEY2COMPRESS-IDENTICAL-CHARS     value h"02".
                  78 KEY2COMPRESS-FOLLOWING-DUP       value h"01".
                  78 KEY2COMPRESS-NO-COMPRESSION      value h"00".
                  78 KEY2COMPRESS-DEFAULT        value KEY2COMPRESS-NO-COMPRESSION.
             49 sparse-characters      pic x(2).
             49 filler                 pic x(8). *> reserved
  3. Finally, you need to paste the component definition area to complete the key definition block:
          *  component-specifications for all keys follows after the key-specifications
      *  for all the keys.
          47 component-specification.
             49 component-flags        pic 9(2) comp-x.
             49 component-type         pic 9(2) comp-x.
                  78 KEY2PARTTYP-NUMERIC              value h"80".
                  78 KEY2PARTTYP-SIGNED               value h"40".
                  78 KEY2PARTTYP-COMP                 value h"20".
                  78 KEY2PARTTYP-COMP-3               value h"21".
                  78 KEY2PARTTYP-COMP-X               value h"22".
                  78 KEY2PARTTYP-COMP-5               value h"23".
                  78 KEY2PARTTYP-FLOAT                value h"24".
                  78 KEY2PARTTYP-COMP-6               value h"25".
                  78 KEY2PARTTYP-DISPLAY              value h"00".
                  78 KEY2PARTTYP-SIGN-TRAIL-INCL      value h"00".
                  78 KEY2PARTTYP-SIGN-TRAIL-SEP       value h"01".
                  78 KEY2PARTTYP-SIGN-LEAD-INCL       value h"02".
                  78 KEY2PARTTYP-SIGN-LEAD-SEP        value h"03".
                  78 KEY2PARTTYP-SIGN-LEAD-FLOAT      value h"04".
             49 component-offset       pic 9(9) comp-x.
             49 component-length       pic 9(9) comp-x.

Later in the tutorial, a set-keydefinitions section is added that populates the values in this block.

Finally, you need to define a group for the records that will be written to and read from the data file.
Parent topic: Tutorial
Previous topic: Define the Filename Area
Next topic: Define the Record Area
Related reference
Key Definition Block


Define the Record Area

  1. In the working-storage section of the program, beneath the file name and key definitions, paste the following code:
           01 ex-record.
               03 record-key           pic 9(5).
               03 record-data          pic x(95).

    This area is used when reading and writing records to and from the data file. When setting up the FCD later in this tutorial, you set fcd-record-address to the address of ex-record.

  2. Press Ctrl+S to save the changes.
The working-storage section is now complete, next you will create the necessary source code in the procedure division.
Parent topic: Tutorial
Previous topic: Define the Key Definition Block
Next topic: Set up the FCD
Related reference
Record Area


Set up the FCD

You need to set the appropriate information in the FCD according to the operation codes that you will use. The following block sets the details required for the opening of the file.

  1. In the procedure division, paste the following code:
               set-fcd section.
      *> Initially sets up FCD for OPEN op
           move low-values to fcd
           move length of fcd to fcd-length
           move fcd--version-number    to fcd-version
           move fcd--indexed-org       to fcd-organization
           move fcd--dynamic-access    to fcd-access-mode
           move fcd--open-closed       to fcd-open-mode *> When opening a file this should be set to fcd--open-closed
           move fcd--recmode-variable  to fcd-recording-mode
           move fcd--format-big        to fcd-file-format
           move fcd--auto-lock-bit     to fcd-lock-mode
           move 12                     to fcd-name-length
           set fcd-filename-address    to address of ex-filename
           set fcd-idxname-address     to address of ex-index-name
           set fcd-key-def-address     to address of ex-keydef
           move 10                     to fcd-max-rec-length
           move 5                      to fcd-min-rec-length
           set fcd-record-address      to address of ex-record
           perform set-keydefinitions
           .

    This section populates the FCD data area with the details required to perform an OPEN. The last line performs another section that will populate the key definition block that you defined in the last step; that section is below.

  2. Paste the following code underneath the set-fcd section:
               set-keydefinitions section.
           move low-values to ex-keydef
           move length of ex-keydef to key2length
           move 1 to key-count
           set component-defs to length of key-specification
           add 14 to component-defs
           move 1 to component-count
           move 0 to component-offset *> start of key
           move 5 to component-length *> key length
           .

    This section states that there will be only one key (move 1 to key-count), and that will contain only one component (move 1 to component-count), 5 bytes in length (move 5 to component-length).

Next step is to code the call to the file handler.

Parent topic: Tutorial
Previous topic: Define the Record Area
Next topic: Call the Callable File Handler and Check the File Status
Related reference
File Control Description (FCD)


Call the Callable File Handler and Check the File Status

Add the following sections to include a generic call to the callable file handler; that way, you can perform this section a number of times to execute a number of different operations, depending on the value of opcode. It is also good practice to code a section that checks the file status after each file operation, in case there are problems accessing the intended file.
  1. In the procedure division, paste the following code:
               call-file-handler section.
           call "EXTFH" using opcode, fcd
           .

    This section will be performed a number of times during the demonstration, each time to perform a different operation.

  2. Beneath the previous section, paste the following code:
               display-file-status section.
           if fcd-status-key-1 = "9"
              display "file-status = " fcd-status-key-1 "/" fcd-binary
           else
              display "file-status = " fcd-status-key-1 "/" fcd-status-key-2
           end-if
           .

    After each operation, this section will be performed to check that the operation was successful.

Now that the working storage has been defined, and you have the code in place to call the file handler, you can create a file and start performing file handling operations on it.

Parent topic: Tutorial
Previous topic: Set up the FCD
Next topic: Create, Write To, and Close an Indexed File
Related reference
Extended File Status Codes


Create, Write To, and Close an Indexed File

Now it's time to add the code that will create the indexed file, then write to it.
  1. On the first line of the procedure division (that is, before the sections you have just added), paste the following code:
          *> Create an indexed file
      *>   open output an indexed file call "idxfile.dat"
           display "Create new indexed file"
           perform set-fcd
           move OP-OPEN-OUTPUT to opcode
           perform call-file-handler
           perform display-file-status.

    This code performs the three sections that you coded in the previous steps. The operation code is set so that when call-file-handler is performed, the details in the FCD result in an indexed file, named idxfile.dat, is created.

  2. Beneath the previous code, paste the following:
          *> Write 5 records increasing record length by 1 each time
           move all "A" to record-data
           move 0 to record-key
           move 5 to fcd-current-rec-len
           move OP-WRITE to opcode
           perform 5 times
              add 1 to record-key
              add 1 to fcd-current-rec-len
              perform call-file-handler
           end-perform.

    This paragraph writes (using op-code OP-WRITE) five records to the open file.

  3. Beneath the previous code, paste the following:
          *> Now close the file
           move OP-CLOSE to opcode
           perform call-file-handler
           perform display-file-status
           display "file closed".

    Now the op-code changes to OP-CLOSE and the file is closed, and a file-status check is performed to confirm that the file has been closed successfully.

Now that you have created and populated an indexed file, the next steps demonstrate how to open it and update it.

Parent topic: Tutorial
Previous topic: Call the Callable File Handler and Check the File Status
Next topic: Read From and Rewrite To the File


Read From and Rewrite To the File

Now that an indexed file (idxfile.dat) has been created, you can reuse some of the previous code to perform other file handling operations, by updating the op-code.

  1. In the procedure division, after the last section in the program (just before the end program statement), paste the following code:
               read-all-records section.
           display "Open the file and read all the records".
           move OP-OPEN-INPUT         to opcode
           move fcd--open-closed      to fcd-open-mode
           perform call-file-handler
           if fcd-status-key-1 not = "0"
              display "Failed to open file"
              goback
           end-if
           move 1 to record-key
           move OP-START-EQUAL to opcode
           perform call-file-handler
           move OP-READ-NEXT to opcode
           perform until fcd-status-key-1 not = "0"
             perform call-file-handler
             if fcd-status-key-1 = "0"
                display ex-record(1:fcd-current-rec-len)
             end-if
           end-perform
           move OP-CLOSE to opcode
           perform call-file-handler
           if fcd-status-key-1 not = "0"
              display "Close failed"
              goback
           end-if
           .

    When this section is performed, it opens the newly written-to indexed file (op-code OP-OPEN-INPUT), and then reads the records (op-codes OP-START-EQUAL to start at the first key, and OP-READ-NEXT to move on to the next record), displaying them to the screen; after which, the file is closed (op-code OP-CLOSE).

  2. Beneath the previous section, paste the following code:
               rewrite-first-record section.
           move OP-OPEN-I-O to opcode
           perform call-file-handler
           move 1 to record-key
           move OP-START-EQUAL to opcode
           perform call-file-handler
           move OP-READ-NEXT to opcode
           perform call-file-handler
           if fcd-status-key-1 = "0"
              move "Fred" to record-data
              move 9 to fcd-current-rec-len
              move OP-REWRITE to opcode
              perform call-file-handler
              if fcd-status-key-1  = "0"
               display "Record update : Success"
              else
               display "Record update : Failed"
             end-if
           end-if
           move OP-CLOSE to opcode
           perform call-file-handler
           if fcd-status-key-1 not = "0"
              display "Close failed"
              goback
           end-if
           .

    This time the file is opened I-O (op-code OP-OPEN-I-O) and when the first record has been successfully read, it changes its contents (to "Fred") and rewrite the record (op-code OP-REWRITE); after which, the file is closed.

    Now add the two paragraphs that will perform these read and rewrite sections.

  3. In the procedure division, after the paragraph that closes the file (the line that states display "file closed"), paste the following code:
          *> Query the file to retrieve file information
           move low-values to fcd
           set  fcd-filename-address  to address of ex-filename
           move 80                    to fcd-name-length
           move fcd--determine-org    to fcd-organization
           move fcd--version-number   to fcd-version
           set fcd-filename-address   to address of ex-filename
           set fcd-idxname-address    to address of ex-index-name
           set fcd-key-def-address    to address of ex-keydef
           set fcd-record-address     to address of ex-record
           move OP-QUERY-FILE         to opcode
           perform call-file-handler
           perform display-file-status
           display "file open, ready to read"
           perform read-all-records
           perform rewrite-first-record.
  4. Beneath the previous section, paste the following code:
          *> Now read all the records again
           perform read-all-records
           goback
           stop run.

    The final perform is to re-read the data file to display the edited record.

  5. Press Ctrl+S to save the changes so far.

Finally, you are ready to compile and run your program.

Parent topic: Tutorial
Previous topic: Create, Write To, and Close an Indexed File
Next topic: Run the Application


Run the Application

  1. Select your project in the COBOL Explorer view and from the main menu click Run > Run Configurations.

    The Run Configurations dialog box is displayed.

  2. Create a new launch configuration in one of the following ways:
    • Double-click the COBOL Application tree item; or
    • Click the COBOL Application tree item, and then click [image] (New launch configuration).

    This creates a new COBOL launch configuration for your project.

  3. Click Run.

    The application runs and you can see the annotated output as a number of operations are performed on the data file.

    Tip: To take a closer look at how the callable file handler is utilized, run the program through the debugger. You can also open the data file in the data file editor to see the contents that this program has just created.
This ends the tutorial, where you have successfully used the callable file handler to perform a number of file handling operations without using any of the conventional file handling COBOL syntax. Refer to Calling the File Handler for full details of the syntax available when using this method of file operation.
Parent topic: Tutorial
Previous topic: Read From and Rewrite To the File
Related reference
Calling the File Handler


Appendices

  • Appendix A - the source code
    The resulting source code.
Parent topic: Tutorial: Using the Callable File Handler


Appendix A - the source code

If you have followed the tutorial correctly, you end up with something similar to the following source code:
      $set source-format"variable".
       working-storage section.
       01  opcode                       pic x(2).
       78  OP-QUERY-FILE                     value x"0006".
       78  OP-OPEN-INPUT                     value x"fa00".
       78  OP-OPEN-OUTPUT                    value x"fa01".
       78  OP-OPEN-I-O                       value x"fa02".
       78  OP-WRITE                          value x"faf3".
       78  OP-RELEASE                        value x"faf3".
       78  OP-REWRITE                        value x"faf4".
       78  OP-READ-NEXT                      value x"faf5".
       78  OP-START-EQUAL                    value x"fae9".
       78  OP-CLOSE                          value x"fa80".
       01 fcd.
           copy "xfhfcd3.cpy".
       01 ex-filename                  pic x(260) value "idxfile.dat".
       01 ex-index-name	               pic x(100).
       01 ex-keydef.
          47 key2length                pic 9(4)  comp-x.
          47 key-version               pic 9(2) comp-x value 2.
          47 filler                    pic 9(6)  comp-x. *> reserved
          47 key-count                 pic 9(4)  comp-x.
          47 filler                    pic 9(13) comp-x. *> reserved
      *  key-specification is repeated for the number of keys defined by
      *  key-count
          47 key-specification.
             49 component-count        pic 9(4) comp-x.
      * The offset for the component-specification for this key
             49 component-defs         pic 9(4) comp-x.
             49 key-flags              pic 9(2) comp-x.
                  78 KEY2KEYFLAG-DUPS-IN-ORDER        value h"40".
                  78 KEY2KEYFLAG-PRIME                value h"10".
                  78 KEY2KEYFLAG-SPARSE-KEY           value h"02".
             49 key-compression        pic 9(2) comp-x.
                  78 KEY2COMPRESS-TRAILING-NULLS      value h"08".
                  78 KEY2COMPRESS-TRAILING-SPACES     value h"04".
                  78 KEY2COMPRESS-IDENTICAL-CHARS     value h"02".
                  78 KEY2COMPRESS-FOLLOWING-DUP       value h"01".
                  78 KEY2COMPRESS-NO-COMPRESSION      value h"00".
                  78 KEY2COMPRESS-DEFAULT        value KEY2COMPRESS-NO-COMPRESSION.
             49 sparse-characters      pic x(2).
             49 filler                 pic x(8). *> reserved
      *  component-specifications for all keys follows after the key-specifications
      *  for all the keys.
          47 component-specification.
             49 component-flags        pic 9(2) comp-x.
             49 component-type         pic 9(2) comp-x.
                  78 KEY2PARTTYP-NUMERIC              value h"80".
                  78 KEY2PARTTYP-SIGNED               value h"40".
                  78 KEY2PARTTYP-COMP                 value h"20".
                  78 KEY2PARTTYP-COMP-3               value h"21".
                  78 KEY2PARTTYP-COMP-X               value h"22".
                  78 KEY2PARTTYP-COMP-5               value h"23".
                  78 KEY2PARTTYP-FLOAT                value h"24".
                  78 KEY2PARTTYP-COMP-6               value h"25".
                  78 KEY2PARTTYP-DISPLAY              value h"00".
                  78 KEY2PARTTYP-SIGN-TRAIL-INCL      value h"00".
                  78 KEY2PARTTYP-SIGN-TRAIL-SEP       value h"01".
                  78 KEY2PARTTYP-SIGN-LEAD-INCL       value h"02".
                  78 KEY2PARTTYP-SIGN-LEAD-SEP        value h"03".
                  78 KEY2PARTTYP-SIGN-LEAD-FLOAT      value h"04".
             49 component-offset       pic 9(9) comp-x.
             49 component-length       pic 9(9) comp-x.
       01 ex-record.
               03 record-key           pic 9(5).
               03 record-data          pic x(95).
       procedure division.
      *> Create an indexed file
      *>   open output an indexed file call "idxfile.dat"
           display "Create new indexed file"
           perform set-fcd
           move OP-OPEN-OUTPUT to opcode
           perform call-file-handler
           perform display-file-status.
      *> Write 5 records increasing record length by 1 each time
           move all "A" to record-data
           move 0 to record-key
           move 5 to fcd-current-rec-len
           move OP-WRITE to opcode
           perform 5 times
              add 1 to record-key
              add 1 to fcd-current-rec-len
              perform call-file-handler
           end-perform.
      *> Now close the file
           move OP-CLOSE to opcode
           perform call-file-handler
           perform display-file-status
           display "file closed".

      *> Query the file to retrieve file information
           move low-values to fcd
           set  fcd-filename-address  to address of ex-filename
           move 80                    to fcd-name-length
           move fcd--determine-org    to fcd-organization
           move fcd--version-number   to fcd-version
           set fcd-filename-address   to address of ex-filename
           set fcd-idxname-address    to address of ex-index-name
           set fcd-key-def-address    to address of ex-keydef
           set fcd-record-address     to address of ex-record
           move OP-QUERY-FILE         to opcode
           perform call-file-handler
           perform display-file-status
           display "file open, ready to read"
           perform read-all-records
           perform rewrite-first-record.
      *> Now read all the records again
           perform read-all-records
           goback
           stop run.
           set-fcd section.
      *> Initially sets up FCD for OPEN op
           move low-values to fcd
           move length of fcd to fcd-length
           move fcd--version-number    to fcd-version
           move fcd--indexed-org       to fcd-organization
           move fcd--dynamic-access    to fcd-access-mode
           move fcd--open-closed       to fcd-open-mode *> When openining a file this should be set to fcd--open-closed
           move fcd--recmode-variable  to fcd-recording-mode
           move fcd--format-big        to fcd-file-format
           move fcd--auto-lock-bit     to fcd-lock-mode
           move 12                     to fcd-name-length
           set fcd-filename-address    to address of ex-filename
           set fcd-idxname-address     to address of ex-index-name
           set fcd-key-def-address     to address of ex-keydef
           move 10                     to fcd-max-rec-length
           move 5                      to fcd-min-rec-length
           set fcd-record-address      to address of ex-record
           perform set-keydefinitions
           .
           set-keydefinitions section.
           move low-values to ex-keydef
           move length of ex-keydef to key2length
           move 1 to key-count
           set component-defs to length of key-specification
           add 14 to component-defs
           move 1 to component-count
           move 0 to component-offset *> start of key
           move 5 to component-length *> key length
           .

           call-file-handler section.
           call "EXTFH" using opcode, fcd
           .
           display-file-status section.
           if fcd-status-key-1 = "9"
              display "file-status = " fcd-status-key-1 "/" fcd-binary
           else
              display "file-status = " fcd-status-key-1 "/" fcd-status-key-2
           end-if
           .
           read-all-records section.
           display "Open the file and read all the records".
           move OP-OPEN-INPUT         to opcode
           move fcd--open-closed      to fcd-open-mode
           perform call-file-handler
           if fcd-status-key-1 not = "0"
              display "Failed to open file"
              goback
           end-if
           move 1 to record-key
           move OP-START-EQUAL to opcode
           perform call-file-handler
           move OP-READ-NEXT to opcode
           perform until fcd-status-key-1 not = "0"
             perform call-file-handler
             if fcd-status-key-1 = "0"
                display ex-record(1:fcd-current-rec-len)
             end-if
           end-perform
           move OP-CLOSE to opcode
           perform call-file-handler
           if fcd-status-key-1 not = "0"
              display "Close failed"
              goback
           end-if
           .
           rewrite-first-record section.
           move OP-OPEN-I-O to opcode
           perform call-file-handler
           move 1 to record-key
           move OP-START-EQUAL to opcode
           perform call-file-handler
           move OP-READ-NEXT to opcode
           perform call-file-handler
           if fcd-status-key-1 = "0"
              move "Fred" to record-data
              move 9 to fcd-current-rec-len
              move OP-REWRITE to opcode
              perform call-file-handler
              if fcd-status-key-1  = "0"
               display "Record update : Success"
              else
               display "Record update : Failed"
             end-if
           end-if
           move OP-CLOSE to opcode
           perform call-file-handler
           if fcd-status-key-1 not = "0"
              display "Close failed"
              goback
           end-if
           .
Parent topic: Appendices


Managed COBOL Tutorials

  • Tutorial: Creating a Basic JVM COBOL Application
  • Tutorial: Deploying JVM COBOL to an Application Server
  • Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
    As an extension to Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server, this tutorial shows you how to do the same thing with a SQL Server COBOL application using the Red Hat JBoss application server.
  • Tutorial: Calling JVM COBOL programs as part of an Axis Web service
  • Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
  • Tutorial: Packaging JVM COBOL
  • Tutorial: Compiling a COBOL Program to JVM Byte Code
Parent topic: Getting Started


Tutorial: Creating a Basic JVM COBOL Application

This tutorial is an introduction to developing managed COBOL applications using Enterprise Developer.

JVM COBOL applications are written in managed COBOL but compile to Java byte code. This enables you to use all the Objected-Oriented language features of managed COBOL that provide seamless interoperation between COBOL and Java.

The tutorial follows a logical sequence of application development tasks to create a simple COBOL class that displays a message when run.

Use the Next and Previous links to move between the tutorial steps.

  1. Create a COBOL JVM Project
  2. Create a Class and Build Your Project
  3. Run the JVM Application
  4. Debug the Application
Parent topic: Managed COBOL Tutorials


Create a COBOL JVM Project

The first step in creating an application is to create a project. From the IDE take the following steps:
  1. In the Team Developer perspective, click File > New > Project . This opens the New Project dialog box.
  2. Click Micro Focus COBOL > COBOL JVM Project, and then click Next. This opens the New COBOL JVM Project dialog box.
  3. In the Project name field, type HelloJVMworld.
  4. Select the location to save your project. By default, the project is created in the workspace that you selected when you started the Eclipse session. You can change this by unchecking the Use default location checkbox and selecting a different location.
  5. Click Finish.
    Note: If you are prompted to open the COBOL perspective, click Open Perspective.
You have now created a COBOL JVM project and it is displayed in the Application Explorer view.
Tip: As well as the .cobolBuild, .cobolProj, and .project files that are automatically created with a COBOL project, there is also a .classpath file. This is an XML file that contains all the paths to user-defined classes and packages. By default, these files are not listed, but you can show them by opening the Application Explorer view menu, click [image] (View Menu), and then click Filters and Customization. This opens the Filters and Customization dialog box. Click the Filters tab and uncheck .*resources, and then click OK.
Parent topic: Tutorial: Creating a Basic JVM COBOL Application
Next topic: Create a Class and Build Your Project


Create a Class and Build Your Project

Now that you have created a project, you need to provide the COBOL code for the application in a new COBOL class. To do this:
  1. Select the project in the Application Explorer view, and then click File > New > Other.
  2. Expand Micro Focus COBOL, and then click COBOL JVM Class.
  3. Click Next. This opens the New COBOL JVM Class dialog box.
  4. Enter the following details:
    Field | Value
    Source folder | HelloJVMworld/src
    Package* | com.microfocus.example
    Name | JVMWorldClass
    Note: * A Java package is a mechanism for organizing Java classes, interfaces, and types into namespaces. These entities are stored in a directory structure specified by its package name. In this case, the value "com.microfocus.example" creates the structure <source folder>\com\microfocus\example (Windows) or <source folder>/com/microfocus/example (UNIX).
  5. Click Finish.

    This creates a new COBOL program from the supplied templates to hold the code for the class in the src > com > microfocus > example folder in your project. The program also opens in the editor.

  6. Copy and paste the following code into the editor, overwriting the existing text:
          $set ilusing(com.microfocus.example)
       class-id com.microfocus.example.JVMWorldClass public.

       working-storage section.

       method-id main static.

       01 class1 type JVMWorldClass.

       procedure division using by value args as String occurs any.
           set class1 to new JVMWorldClass
           invoke class1::instanceMethod
           stop run.
       end method.

       method-id instanceMethod.

       procedure division.
           display "Hello world".
           goback.
       end method.

       end class.
  7. Click File > Save . By default, Eclipse is configured to build projects automatically. If this option has been changed, to manually start a build, select the project in the Application Explorer view and click Project > Build Project.
Parent topic: Tutorial: Creating a Basic JVM COBOL Application
Previous topic: Create a COBOL JVM Project
Next topic: Run the JVM Application


Run the JVM Application

  1. In the Application Explorer view, right-click your project, and then click Run As > COBOL JVM Application.
  2. This opens the Select COBOL JVM Application dialog box, which requires you to choose the item containing the project's Main class, select com.microfocus.example.JVMWorldClass and click OK.
The project then runs, and displays "Hello world" in the Console view.
Parent topic: Tutorial: Creating a Basic JVM COBOL Application
Previous topic: Create a Class and Build Your Project
Next topic: Debug the Application


Debug the Application

To be able to debug your application program, you need to ensure the project is compiled for debugging. You then need to create a debug configuration suitable for your application and use it to start a debug session.
  1. Click your project in the Application Explorer view and from the main menu click Project > Properties , expand the Micro Focus node and choose Build Configuration.
  2. Ensure Compile for debugging is checked and click OK.

    By default, Eclipse builds the project each time you change the code or the project's properties. The build produces an updated .class file and an .idy file which is required for debugging.

    You need to configure how debugging will work.

  3. Select your project in the Application Explorer view and click Run > Debug Configurations

    This opens the Debug Configurations dialog.

  4. Expand COBOL JVM Application in the left pane. A debug configuration called JVMWorldClass is displayed.
  5. In the Main tab, check Stop in main.
  6. Click Debug.

    By default, a Confirm Perspective Switch dialog box is displayed. This is because Eclipse offers a different perspective for debugging that has views that provide relevant information that you might need. Click Yes to confirm the switch and start debugging.

    The application starts running, and stops at the first instruction in the Main method of the class set class1 to new JVMWorldClass.

    The Debug view shows the threads that are running in the application. Each thread can be expanded to show the call stack for that thread, together with the source code positions. If the sources are available, you can double-click on a call stack entry to go to that location of code, and see the values of local variables as they were on the stack at that point in the execution. In addition, an application window opens where the specific steps in your application will be displayed as debugging takes place.

    The Variables view displays data items and internal file names that are referenced on the current line and in the previous stepped statement. This allows you to view the before and after values or statuses of a particular item. You can set breakpoints by double-clicking in the margin at the far left of the source view and then run the program to the breakpoint by clicking Run > Resume. Alternatively, press F8 to resume debug.

  7. To stop debugging, click Terminate (Terminate).
Parent topic: Tutorial: Creating a Basic JVM COBOL Application
Previous topic: Run the JVM Application


Tutorial: Deploying JVM COBOL to an Application Server

It is possible to preserve your existing JVM COBOL business logic when deploying to an application server.

In order to build a multi-user application suited for an application server, you build your existing JVM COBOL code into the Enterprise JavaBeans (EJB) architecture (version 3.x or later).

A broad overview of the process is as follows:

  1. From a Java class that implements the EJB interface, you can call JVM COBOL business logic by wrapping it in a Micro Focus RunUnit class, which will provide the required multi-user environment.
  2. To ensure the JVM COBOL run-time system works correctly, each .jar file that is built into your packaged application must be deployed with a cobconfig.properties file with the contents:
    ejb=true
  3. Package this information into a deployable format, such as an enterprise archive file (.ear) or Web archive file (.war) and deploy it to your application server.

For a more detailed explanation of the process, using JBoss as the application server, see Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server.

In addition to the resources built into your deployed application, you must also consider how you are going to deploy the JVM COBOL run-time system.

  • Run-time Considerations
  • Restrictions
  • Install and Configure an Application Server
  • Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Parent topic: Managed COBOL Tutorials
Related information
Multiple user COBOL applications in .NET or Java


Run-time Considerations

When choosing how to deploy the JVM COBOL run-time system that is required by JVM application code, consider the deployment options illustrated in this diagram:

Shared Runtime Deployment Style
Deploy the run-time system separately, as a shared module or object in your application server.
Per Bean Runtime Deployment Style
Package the run-time system in a deployed archive file, such as an enterprise archive file (.ear) or web archive file (.war).

Each Runtime Deployment Style has its advantages:

Shared Per Bean
  • Uses less memory, because the run-time file (mfcobolrts.jar) is shared by all applications.
  • Tracing can be performed centrally.
  • For application servers that provide versioning, you can deploy multiple versions of the run-time system.
  • Administrative rights are not required to configure the application server.
  • For application servers that do not provide versioning, you can deploy different applications that use different run-time systems.
  • Remote deployment is easier as all required resources are self-contained.

In this tutorial, you deploy your JVM COBOL runtime using the Per Bean Runtime Deployment Style, meaning that the runtime is packaged as an archive file and deployed with the application.

Parent topic: Tutorial: Deploying JVM COBOL to an Application Server
Related concepts
Install and Configure an Application Server


Restrictions

When using a class that implements the EJB specification to run your JVM COBOL code, the following are not currently supported:
  • COBOL file handling (including ACUCOBOL-GT file handling and Fileshare)
  • COBOL database handling
  • 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
Parent topic: Tutorial: Deploying JVM COBOL to an Application Server


Install and Configure an Application Server

If you decide to deploy the JVM COBOL run-time system as part of your application server, you need to add it to the application server, and then add an application configuration file to one or more projects in your application.

The configuration for each different application server is different. The following sections contain the details for the most common application servers:

  • Configuring JBoss
  • Configuring WebLogic
  • Configuring WebSphere
Parent topic: Tutorial: Deploying JVM COBOL to an Application Server
Related concepts
Run-time Considerations


Configuring JBoss

To install the JVM COBOL run-time system (mfcobolrts.jar) in JBoss or later, you must configure it as a module of the application server.
  1. Set the environment variable JBOSS_HOME to point to the JBoss EAP 6.4 installation location, for example: %Program Files%\JBoss\jboss-version (Windows) or /usr/jboss/jboss-version (UNIX).
  2. Create the following folder structure: JBOSS_HOME\modules\system\layers\base\com\microfocus\cobol\runtime\main (Windows) or JBOSS_HOME/modules/system/layers/base/com/microfocus/cobol/runtime/main (UNIX).
  3. Copy mfcobolrts.jar from the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin (Windows) or $COBDIR/bin (UNIX) folder to the main folder created in the previous step.
  4. In the main folder, create a new file called module.xml, and add the following to it:
    <module xmlns="urn:jboss:module:1.1" name="com.microfocus.cobol.runtime">
    <dependencies>
        <module name="javaee.api"/>
    </dependencies>
    <resources>
        <resource-root path="mfcobolrts.jar"/>
    </resources>
</module>

    The main folder should contain the following files:

    • mfcobolrts.jar
    • module.xml
Parent topic: Install and Configure an Application Server
Related concepts
Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server


Configuring WebLogic

Note:
  • These details only explain how to enable use of the JVM COBOL run-time system with WebLogic; any other WebLogic configuration is out of the scope of this topic.
  • The manifest file (manifest.mf) in mfcobolrts.jar already contains the information required to be recognized as a shared library in WebLogic.

To install the JVM COBOL run-time system (mfcobolrts.jar) in WebLogic 12.1.1 or later, you can add it as a shared library from the weblogic.Deployer command line utility.

To install the run-time system from the command line

Note: The weblogic.Deployer utility only registers the JVM COBOL run-time system with the application server; it does not copy it to the server's directory structure.
  1. Ensure the application server is running.
  2. To set up your environment for the command line tool, run the setWLSEnv.cmd (Windows) or setWSLEnv.sh (UNIX) script, located in the server\bin (Windows) or server/bin (UNIX) sub-directory of the WebLogic server installation directory.
  3. Copy mfcobolrts.jar from %COBDIR%\bin (Windows) or $COBDIR/bin (UNIX) to a new location.
  4. Enter the following command:
    java weblogic.Deployer -adminurl t3://localhost:7001 -username USER_NAME
                       -password PASSWORD -deploy -library PATH\mfcobolrts.jar

    Replace USER_NAME and PASSWORD with details supplied by the administrator of the application server. Replace PATH with the path that you used in the previous step.

Configure the application configuration file

In Eclipse, in the project that will be deployed, in the META-INF directory, add a weblogic-application.xml file that contains the following code - 2.3 is the version of Enterprise Developer:

<weblogic-application
xmlns="http://xmlns.oracle.com/weblogic/weblogic-application"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
  <library-ref>
    <library-name>mfcobolrts</library-name>
    <specification-version>2.3</specification-version>
    <implementation-version>2.3</implementation-version>
    <exact-match>false</exact-match>
  </library-ref>
</weblogic-application>
Note: 2.3 in this file is the version of Enterprise Developer. If you bind your application to a newer version of the COBOL run-time system than was supplied in a more recent version of Enterprise Developer, that must be reflected in the specification-version and implementation-version settings.

To uninstall the run-time system from the command line

  1. Ensure the application server is running.
  2. Enter the following command:
    java weblogic.Deployer -adminurl t3://localhost:7001 -username USER_NAME
                       -password PASSWORD -undeploy  -name mfcobolrts

Replace USER_NAME and PASSWORD with details supplied by the administrator of the application server.

Parent topic: Install and Configure an Application Server


Configuring WebSphere

Note: These details only explain how to enable use of the JVM COBOL run-time system with WebSphere; any other WebSphere configuration is out of the scope of this topic.

To install the JVM COBOL run-time system (mfcobolrts.jar) in WebSphere 8.5 or later, you can add it as a shared library either through the application server management console or from the wsadmin command line utility.

Note: The manifest file (manifest.mf) in mfcobolrts.jar already contains the information required to be recognized as a shared library in WebSphere.

To install the run-time system using the management console

To install the JVM COBOL run-time system, refer to the IBM documentation for instructions on creating and managing a shared library:

Managing shared libraries

To install the run-time system from the command line

Note: The wsadmin utility only registers the JVM COBOL run-time system with the application server; it does not copy it to the server's directory structure.
  1. Ensure the application server is running.
  2. Copy mfcobolrts.jar from %COBDIR%\bin (Windows) or $COBDIR/bin (UNIX) to a new location.
  3. Enter the following command:
    wsadmin –lang jython –c AdminResources.createSharedLibrary("SERVER_NODE_NAME"
                                          ,"SERVER_NAME","mfcobolrts","PATH\mfcobolrts.jar”)

    Replace SERVER_NODE_NAME and SERVER_NAME with details supplied by the administrator of the application server. Replace PATH with the path that you used in the previous step.

Configure the application configuration file

In Eclipse, in the project that will be deployed, in the META-INF directory, add a MANIFEST.MF file, that contains the following:

Manifest-Version: 1.0
Extension-Name: mfcobolrts
Specification-Title: Micro Focus COBOL JVM Runtime System
Specification-Version: 2.3
Specification-Vendor: microfocus.com
Implementation-Version: 2.3
Note: 2.3 in this file is the version of Enterprise Developer. If you bind your application to a newer version of the COBOL run-time system than was supplied in Enterprise Developer, that must be reflected in the Specification-Version and Implementation-Version settings.

To uninstall the run-time system from the command line

  1. Ensure the application server is running.
  2. Enter the following command:
    wsadmin –lang jython -c AdminConfig.remove(AdminConfig.getid('/Library:mfcobolrts'))
Parent topic: Install and Configure an Application Server


Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server

The following tutorial guides you through deploying a dynamic web project that implements the EJB 3.0 specification, and that has JVM COBOL business logic at its heart, to a JBoss application server.

  1. Tutorial Prerequisites
  2. Copying the Tutorial Files
  3. Creating the Workspace
  4. Importing the Project Files
  5. Stepping through the Projects
  6. Deploying the JVM COBOL Run-time System within the Application
  7. Deploying the Application
  8. Showing the Server Status
  9. Running the Application
  10. Debugging the Application
Parent topic: Tutorial: Deploying JVM COBOL to an Application Server
Related concepts
Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server


Tutorial Prerequisites

This tutorial guides you through three projects that have been configured to work together to form one deployed application. For that reason, a lot of the tutorial steps are highlighting pertinent actions that have already been performed.

However, to complete this tutorial, a certain degree of experience is still required in a number of areas.

Firstly, some project configuration may be required outside of these steps, because the projects were configured to work in a certain Java environment (using JRE 1.8, installed with Enterprise Developer by default). Where your environment differs (for example, you use a different Java run-time version), you may be required to reconfigure project settings to suit your environment.

Also, familiarity with the EJB specifications, REST services, and other Java EE APIs may be required to fully understand the configurations.

Before you start the tutorial, ensure you have the following prerequisites installed and/or configured:

  • Java 8
  • JBoss EAP 6.4 application server - this tutorial assumes that the application server is already correctly configured, running in standalone mode.
  • The Eclipse JBoss Tools plugin - this can be installed as part of the tutorial, as detailed in Creating the Workspace.
  • The Eclipse plugin WTP 3.3.2 or later - this is included as part of Enterprise Developer.
  • If you are deploying the JVM COBOL run-time system as a standalone module, configure the application server; refer to Configuring JBoss for more information.
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Next topic: Copying the Tutorial Files
Related tasks
Configuring JBoss
Creating the Workspace


Copying the Tutorial Files

The source files required to run the tutorial are available from the Micro Focus Community web site.

Note: To copy 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. Create a folder on your machine in which you will copy the tutorial files.
  2. Visit the Micro Focus Community web site.
  3. Click Download.
  4. Save the file, and then extract the contents of the .zip file to the folder that you created earlier.

    The folder now includes the folders for the following projects:

    • TemperatureConverter - The JVM COBOL project containing the business logic of the application.
    • TemperatureConverterEJB - The EJB implementation that uses the RunUnit specification to wrap around the JVM COBOL code.
    • TemperatureConverterPrj - The dynamic web project that packages the other two projects in a .war file, and is deployed to the application server.
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Tutorial Prerequisites
Next topic: Creating the Workspace


Creating the Workspace

You need to create and configure an Eclipse workspace capable of interacting with the JBoss application server when you are running or debugging the application.
  1. Launch Enterprise Developer for Eclipse.
  2. When prompted for a workspace, specify the path to the folder that you extracted the source files to.
  3. If you are presented with the Welcome page, click Open Team Developer Perspective.

    This loads a set of views within the IDE that are associated with COBOL and PL/I development. The Project Explorer shows that the workspace is empty as you have not yet imported the projects into Eclipse.

  4. If you have not already installed the JBoss tools plugin:
    1. Click Help > Eclipse Marketplace
      This opens the Eclipse Marketplace dialog box.
    2. In the Find field, type JBoss Tools, and then press Enter.
    3. Find the JBoss Tools 4.5.3.Final plugin in the returned results list, and then click Install.
    4. In the Confirm Selected Features page, click Confirm.
    5. Accept the license agreement, and then click Finish.
      If you receive a security warning, click Install anyway.
    6. When prompted to restart Eclipse, click Restart Now.
      Note: If this is the first time the workspace settings have been changed then Eclipse might prompt you to store preference information.
  5. Once you have downloaded the JBoss tools plugin you need to add the server runtime environment:
    1. Click Window > Preferences > Server > Runtime Environments.
    2. Click Add.
      This opens the New Server Runtime Environment dialog box.
    3. Expand Red Hat JBoss Middleware, and then click Red Hat JBoss Enterprise Application Platform 7.1 Runtime.
    4. Click Next.
      This opens the New Server Runtime Environment dialog box.
    5. Next to the Home Directory field, click Browse, and then select the folder containing JBoss EAP.
    6. Click OK.
    7. Ensure that you are using a Java 8 JRE runtime.
    8. Click Finish.
    9. Click Apply and Close.
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Copying the Tutorial Files
Next topic: Importing the Project Files


Importing the Project Files

  1. Ensure Eclipse is open in the workspace that you created in the previous step.
  2. On the File menu, choose Import.

    The Import dialog box appears.

  3. Choose General > Existing Projects into Workspace, then click Next.
  4. On the Import Projects pane, click Browse to the right of Select root directory and choose the directory in which you extracted the projects.

  5. Ensure all three projects are selected, then click Finish.

    The workspace now contains the three projects.

    If Eclipse is set to build projects automatically, the three projects build successfully.

  6. Click the Project Explorer view to see all three projects:
    Project Explorer view
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Creating the Workspace
Next topic: Stepping through the Projects


Stepping through the Projects

The following projects combine to produce an Enterprise JavaBean with JVM COBOL business logic at the heart of it, deployable to a Java Enterprise application server.

  • The COBOL Project - TemperatureConverter
    The JVM COBOL project that contains the business logic for the application.
  • The EJB Project - TemperatureConverterEJB
    The Java EJB project that contains a stateless EJB 3.0 Java class. It uses the RunUnit class to wrap around the JVM COBOL code.
  • The Dynamic Web Project - TemperatureConverterPrj
    The Dynamic Web project that packages up the other two projects into a Web application archive (.war file), which is then deployed to the application server.
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Importing the Project Files
Next topic: Deploying the JVM COBOL Run-time System within the Application


The COBOL Project - TemperatureConverter

The JVM COBOL project that contains the business logic for the application.

The following steps introduce you to the features that enable you to deploy this project alongside the other two projects.

  1. In the Project Explorer pane, navigate to TemperatureConverter > COBOL Sources > src > com > microfocus > converter and double-click TemperatureConverter.cbl.

    The JVM COBOL program appears.

  2. Open the Outline pane to show the two methods. Click each entry to jump to the code in the editor.

    The toCelsius and toFahrenheit methods both contain the conversion algorithms, accepting and returning primitive data types compatible with Java.

    The toFahrenheit method

  3. In the Project Explorer pane, navigate to TemperatureConverter > resource and double-click cobconfig.properties.

    This file is required to ensure the JVM COBOL run-time system works correctly in the EJB environment; each .jar file that is packaged into the deployed .war file requires one of these files. If one does not exist, use the File > New > File options to add a new resource file.

  4. You must ensure that the resource file cobconfig.properties is deployed as part of the project:
    1. Right-click TemperatureConverter then choose Properties.
    2. Choose Deployment Assembly.

      The cobconfig.properties file is in the resource directory, and so is set to be included in the assembly when it is deployed.

    3. Click Cancel to close the Properties page.
Parent topic: Stepping through the Projects
Related information
The EJB Project - TemperatureConverterEJB
The Dynamic Web Project - TemperatureConverterPrj


The EJB Project - TemperatureConverterEJB

The Java EJB project that contains a stateless EJB 3.0 Java class. It uses the RunUnit class to wrap around the JVM COBOL code.

The following steps introduce you to the features that enable you to deploy this project alongside the other two projects.

  1. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic and double-click TemperatureConverterBean.java.

    This opens the Java class in an editor.

    This is the EJB class, as denoted by the @Stateless annotation. It imports the com.microfocus.cobol.runtimeservices API, which provides the Micro Focus RunUnit class. The following code shows a TemperatureConverter instance being wrapped in a RunUnit. Each instantiated RunUnit contains its own resources that enable it to run independent of other RunUnit instances, thus enabling the application to provide a multi-user environment.

    import com.microfocus.cobol.runtimeservices.*;
...
private TemperatureConverter createTemperatureConverter()
 {
  rununit = new RunUnit();
  TemperatureConverter tempConverter = new TemperatureConverter();
  rununit.Add(tempConverter);
  return tempConverter;
 }
    The RunUnit syntax includes a try...finally block containing a call to the StopRun method, ensuring that the resources used by the JVM COBOL are freed up when required, even in the event of an exception.
    ...
TemperatureConverter temperatureConverter = createTemperatureConverter();
 try
 {
     c  = temperatureConverter.toCelsius(f);
 }
 finally
 {
  rununit.StopRun();
 }
...
  2. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.business and double-click ITemperatureConverter.java.

    The interface implemented by the previous class appears.

    The interface imports the JAX-WS-RS API to create a RESTful application. This can be seen by the annotations (@GET, @Path, @Produces) used throughout the TemperatureConverterBean class. For example, the following toCelsius method uses the annotations to configure how the request is handled:

    The annotations help to build the URL that forms the request in the deployed application. The return phrase indicates that the response to the client will be returned in JSON format using a simple Temperature class.

  3. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic and double-click Temperature.java.

    The class is annotated with @XmlRootElement (name = "Temperature" ), which allows the build() API to use reflection on the class to build up the JSON output based on the fields and their values. The build() method then adds the appropriate header information to pass back to the client.

  4. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic and double-click TemperatureConverterApp.java.

    This is the wrapper class that enables the EJB to be deployed to the application server.

    @ApplicationPath("/")
public class TemperatureConverterApp extends javax.ws.rs.core.Application {
@Override
 public Set<Class<?>> getClasses(){
  Set<Class<?>> s = new HashSet<Class<?>>();
  s.add(TemperatureConverterBean.class);
  return s;
 }
}

    By extending the JAX-WS-RS API this time, it uses the getClasses() method to register the TemperatureConverterBean EJB class with the application server, as a REST Web service.

  5. In the Project Explorer pane, navigate to TemperatureConverterEJB > resource.

    As with the JVM COBOL project, this project contains a cobconfig.properties file configured in the same way. If one does not exist, use the File > New > File options to add a new resource file.

  6. You must ensure that cobconfig.properties is deployed as part of the project:
    1. Right-click TemperatureConverterEJB, then choose Properties.
    2. Choose Deployment Assembly.

      The cobconfig.properties file is in the resource directory, and so is set to be included in the assembly when it is deployed.

      Deployment Assembly
    3. Click Cancel to close the Properties page.
Parent topic: Stepping through the Projects
Related information
The COBOL Project - TemperatureConverter
The Dynamic Web Project - TemperatureConverterPrj
Multiple user COBOL applications in Java


The Dynamic Web Project - TemperatureConverterPrj

The Dynamic Web project that packages up the other two projects into a Web application archive (.war file), which is then deployed to the application server.
  1. In the Project Explorer pane, navigate to TemperatureConverterPrj.
  2. If you are not deploying the JVM COBOL run-time system as part of the application (that is, the application uses the shared run-time system in the application server), in the Project Explorer pane, navigate to TemperatureConverterPrj > WebContent > META-INF and double-click MANIFEST.MF.

    The project manifest file appears:

    Manifest-Version: 1.0
Dependencies: com.microfocus.cobol.runtime
Class-Path:
    Note: If you are including the JVM Runtime System as part of your .war file then this dependency is not needed in the MANIFEST.MF file.

    If the Dependencies entry is not set as shown above, you must add it.

    Note: Ensure the order of the properties is as shown here.
  3. Ensure that the MANIFEST.MF file, and the two other projects are deployed as part of this project, and to the correct paths:
    1. Right-click TemperatureConverterPrj, then choose Properties.
    2. Choose Deployment Assembly.

      The MANIFEST.MF file is in the WebContent directory, and so is set to be included in the assembly when it is deployed.

    3. Click Cancel to close the Properties page.
Parent topic: Stepping through the Projects
Related information
The COBOL Project - TemperatureConverter
The EJB Project - TemperatureConverterEJB


Deploying the JVM COBOL Run-time System within the Application

In this tutorial, you are deploying the run-time system on a per-bean basis. Therefore, you must deploy it from within the dynamic Web project.
Note: Outside of this tutorial, if you are deploying the JVM COBOL run-time system (mfcobolrts.jar) as a shared module in the application server, you do not need to perform these steps.
  1. To ensure that the application does not attempt to locate the run-time system on the application server:
    1. In the Project Explorer pane, navigate to TemperatureConverterPrj > WebContent > META-INF, then double-click MANIFEST.MF.

      The manifest file for the application appears.

    2. If present, delete the line that starts Dependencies:, then save the file.
  2. Add the run-time system to the project:
    1. Right-click TemperatureConverterPrj then choose Properties.

      The Properties for TemperatureConverterPrj dialog box appears.

    2. Click Java Build Path.
    3. On the Libraries tab, click Add Library.

      The Add Library dialog box appears.

    4. Choose COBOL JVM Runtime System, click Next, then click Finish.
    5. Click OK to save the changes.
  3. Set the run-time system to be deployed with the application:
    1. In the Properties for TemperatureConverterPrj dialog box, click Deployment Assembly.

      The Web Deployment Assembly pane appears.

    2. Click Add.

      The New Assembly Directive dialog box appears.

    3. Click Java Build Path Entries, then click Next.
    4. Click COBOL JVM Runtime System, then click Finish.

      The JVM COBOL Runtime System will be deployed with the Web application.

    5. Click OK to save the changes and close the Properties page.
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Stepping through the Projects
Next topic: Deploying the Application


Deploying the Application

  1. In the Project Explorer pane, right-click TemperatureConverterPrj, then choose Run As > Run on server.

    This opens the Run On Server dialog box.

  2. Click Red Hat JBoss EAP 7.1.
  3. Click Finish.

    The application server is started and the application is deployed. Details of these steps are relayed to the Console pane.

    If publishing on the server fails, check to ensure the server is using the JBoss EAP 7.1 runtime:

    1. In the Servers view, double-click Red Hat JBoss EAP 7.1.

      This opens the server's overview page.

    2. Look in the General Information section on the server page and ensure that the Runtime Environment field is set to JBoss EAP 7.x Runtime.
    3. Save your changes then repeat from Step 1.
    Note: Depending on your default browser, you may receive an HTTP 404 error; this is because the application does not contain a user interface, and so has no screen to display on startup. You can ignore this error and proceed with running the application.
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Deploying the JVM COBOL Run-time System within the Application
Next topic: Showing the Server Status


Showing the Server Status

  1. On the Window menu, click Show View > Other

    The Show View dialog box appears.

  2. Choose Server > Servers, then click OK.

    The Servers view appears showing the JBoss server and it status:

  3. To display server details, double-click the server entry.

    Details for the server appear in the main pane.

Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Deploying the Application
Next topic: Running the Application


Running the Application

Eclipse has a built-in browser window that opens when the server is started, but you can use any external browser to enter the URLs.

In your browser, enter the following URLs:

  • To run the Fahrenheit (212°F) to Celsius conversion, enter:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getCelsius?fahrenheit=212
  • To run the Celsius (36.8°C) to Fahrenheit conversion, enter:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getFahrenheit?celsius=36.8

Depending on your browser, the results are either returned in the browser or you are prompted to save the results to a text file.

Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Showing the Server Status
Next topic: Debugging the Application


Debugging the Application

You can debug both the JVM COBOL and Java code in the same process.
  1. Set a breakpoint in the JVM COBOL code:
    1. In the Project Explorer, choose TemperatureConverter > src > com.microfocus.converter > TemperatureConverter.cbl.

      The JVM COBOL business logic appears in the main pane.

    2. Double-click the marker bar to the left of the compute statement in the toCelsius method.

    The breakpoint is set.
  2. Set a breakpoint in the Java code:
    1. In the Project Explorer pane, choose TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic > TemperatureConverterBean.java.

      The Java code appears in the main pane.

    2. Double-click the marker bar to the left of the c declaration in the toCelsius method.

    The breakpoint is set.
  3. Right-click TemperatureConverterPrj, then choose Debug As > Debug on Server.

    This opens the Debug On Server dialog box.

  4. Ensure that Red Hat JBoss EAP 7.1 is selected and click Finish.

    You receive a notification that the server is not running in debug mode.

  5. Ensure Switch mode (will restart if necessary) is selected and click OK.
    The server is restarted in debug mode. A browser window is opened in the IDE, showing the following URL:
    http://localhost:8080/TemperatureConverterPrj/
    . You can ignore the HTTP Status code message. EJB does not have a landing page and you need to enter the URL for the application manually.
  6. In the browser window, load to the following URL:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getCelsius?fahrenheit=212
  7. If you are prompted to switch to the Debug perspective, click Yes.

    The breakpoint is hit and execution breaks in the Java program. At this point, you can step through the program as normal.

  8. Press F8 to resume execution.
    The compute breakpoint is hit and execution breaks in the JVM COBOL program.
    Note: If you get a Source not found message, perform the following steps:
    1. Click Edit Source Lookup Path.

      This opens the Edit Source Lookup Path dialog box.

    2. Click Add.
    3. Click COBOL Project.
    4. Click OK.

      This opens the Selection Needed dialog box.

    5. Check the TemperatureConverter project.
    6. Click OK.
    7. Click OK.
  9. Continue debugging, or press Ctrl+F2 to terminate. You can click COBOL in the right upper corner of the IDE to switch back to the Team Developer perspective.
Parent topic: Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Running the Application


Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server

As an extension to Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server, this tutorial shows you how to do the same thing with a SQL Server COBOL application using the Red Hat JBoss application server.

The code logic in this tutorial differs from the Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server tutorial in that it uses a SQL Server SELECT statement in a COBOL file that does not use a FROM clause. This SELECT statement replaces a COMPUTE statement using an expression for the conversion calculation.

Restrictions

For a list of restrictions that apply to JVM COBOL and application server support, see the Application Servers section of the JVM COBOL Support topic under Known Issues and Restrictions > JVM Code.

Prerequisites

This tutorial begins where Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server left off, using the JBoss application server, and the same TemperatureConverter, TemperatureConverterEJB, and TemperatureConverterPrj projects. Therefore, you must complete that tutorial in its entirety, using the JBoss application server, before starting this tutorial. See Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server for complete instructions.

You must also install Microsoft SQL Server 2008 or later, configured for SQL Server authentication.

Outline

After completing the prerequisite tutorial, complete this tutorial by following the instructions in the following topics:

  1. Install and Configure a JDBC Driver
    Download and install a SQL Server JDBC driver to use in this tutorial; then make the driver available to the JBoss application server.
  2. Create and Load a SQL Server Database
    Create a SQL Server database and define a database connection.
  3. Modify COBOL Source
    Modify the COBOL source code in the TemperatureConverter project with new code to access your SQL Server database.
  4. Deploy the COBOL JVM Runtime
    Deploy the COBOL JVM runtime with the SQL runtime required to run the application.
  5. Run the JSP Application
    Run the TemperatureConverterJsp application on JBoss.
Parent topic: Managed COBOL Tutorials
Related concepts
Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server


Install and Configure a JDBC Driver

Download and install a SQL Server JDBC driver to use in this tutorial; then make the driver available to the JBoss application server.

Install a JDBC Driver

As this tutorial uses SQL Server, you need a SQL Server-compatible JDBC driver. Download a Microsoft JDBC SQL Server Type 4 driver using this link, and install it using the Install Instructions on the download page:

Download JDBC Drivers

The name of the driver file is sqljdbc4[n].jar where n is a single digit and is appended to the filename for some versions of the driver. Be sure to take note of the location of this file after installing it.

Configure the JDBC Driver in JBoss

To make the JDBC driver available to JBoss, you must place it in the appropriate directory, and configure it by creating an XML configuration file.

Copy the JDBC Driver to JBoss
To run your application, the JBoss application server must find an SQL Server JDBC driver file in a specific subdirectory of your JBoss installation directory. You must create the subdirectory and copy the sqljdbc4.jar file as follows:
  1. At a command prompt or using Explorer, change to your JBoss installation's modules\com directory.
  2. Create the following subdirectory structure:

    microsoft\sqlserver\main

  3. Change to the modules\com\microsoft\sqlserver\main directory.
  4. Copy the downloaded sqljdbc4.jar file to the modules\com\microsoft\sqlserver\main directory.
Create a module.xml file
The module.xml file provides JDBC driver configuration required by JBoss.
  1. In the modules\com\microsoft\sqlserver\main directory, create a new file, module.xml, using any text editor.
  2. Copy the following contents into the file:
    <module xmlns="urn:jboss:module:1.0" name="com.microsoft.sqlserver">
     <resources>
          <resource-root path="sqljdbc4.jar"/>
     </resources>
     <dependencies>
          <module name="javax.api"/>
          <module name="javax.transaction.api"/>
     </dependencies>
</module>
  3. Save the file and exit the editor.
Parent topic: Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Next topic: Create and Load a SQL Server Database


Create and Load a SQL Server Database

Create a SQL Server database and define a database connection.

Create the PUBS SQL Server Database

Using SQL Server Management Studio, create a new SQL Server database, PUBS, on your local default instance of SQL Server, and configure it to use SQL Server authentication by providing a user ID and password. See your SQL Server documentation for instructions.

Start Enterprise Developer

If you have closed Enterprise Developer since completing Tutorial: Reusing Existing COBOL Programs in a Java Environment, open it again; then open the Java EE perspective and the Project Explorer.

Catalog a JDBC Connection in JBoss

Now that the JDBC driver is available for JBoss, you must catalog a connection that uses the driver, providing a DSN for the connection that you specify in an EXEC SQL CONNECT statement:

  1. Using any text editor, edit the standalone.xml located in your JBoss installation's standalone\configuration directory.
  2. In the editor, locate the following set of tags:
    <subsystem xmlns="urn:jboss:domain:datasources:1.0">
    <datasources>
  3. To define a JDBC connection named pubs, add the following code just below <datasources>, replacing SQLServerUserName and SQLServerPassword respectively with the user name and password required for SQL Server authentication:
    <datasource jndi-name="java:/pubs" pool-name="pubs-Pool">
     <connection-url>jdbc:sqlserver://localhost:1433;databaseName=Pubs</connection-url>
     <driver>sqlserver</driver>
     <pool>
          <min-pool-size>10</min-pool-size>
          <max-pool-size>10</max-pool-size>
          <prefill>true</prefill>
     </pool>
     <security>
          <user-name>SQLServerUserName</user-name>
          <password>SQLServerPassword</password>
     </security>
</datasource>
  4. Locate the <drivers> tag just before the closing </datasources> tag.
  5. Just below the <drivers> tag, add the following:
    <driver name="sqlserver" module="com.microsoft.sqlserver"/>
  6. Save and close the file.
Parent topic: Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Install and Configure a JDBC Driver
Next topic: Modify COBOL Source


Modify COBOL Source

Modify the COBOL source code in the TemperatureConverter project with new code to access your SQL Server database.

Here you replace the COBOL source in the TemperatureConverter.cbl file with COBOL source that accesses the SQL Server database.

  1. In the Project Explorer under TemperatureConverter > src > com.microfocus.converter, double-click TemperatureConverter.cbl to open it in the file editor.
  2. Replace the entire contents of the file with the following:
    $set sql(dbman=jdbc)
  class-id com.microfocus.converter.TemperatureConverter public.
  01 text1 pic x(10). *> to force implements IObjectControl
  exec sql include sqlca end-exec.
  method-id toCelsius.
  procedure division using by value fahrenheit as float-short returning celsius as float-short.
  exec sql connect to pubs end-exec.
      exec sql
           select (:fahrenheit - 32) * 5 / 9 into :celsius
      end-exec.
      exec sql disconnect pubs end-exec.
      goback.
 end method.
 method-id toFahrenheit.
 procedure division using by value celsius as float-short returning fahrenheit as float-short.
      exec sql connect to pubs end-exec.
      exec sql
           select (:celsius * 9 / 5) + 32 into :fahrenheit
      end-exec.
      exec sql disconnect pubs end-exec.
      goback
 end method.
 end class.
  3. Click File > Save to save your changes.
Parent topic: Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Create and Load a SQL Server Database
Next topic: Deploy the COBOL JVM Runtime


Deploy the COBOL JVM Runtime

Deploy the COBOL JVM runtime with the SQL runtime required to run the application.
The Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server tutorial walks you through deploying the COBOL JVM Runtime System using a per-bean model. The COBOL JVM Runtime System library that is added to the TemperatureConverterPrj deployment project as a deployment assembly contains several .jar files comprising the runtime. In this tutorial, the mfsqljvm.jar file makes up the SQL runtime. The following instructions enhance the instructions provided in the original tutorial by describing additional changes needed to deploy the SQL runtime using a shared model for JBoss AS 7.1:
  1. At a command prompt or using Explorer, go to your %JBOSS_HOME%\modules\com\microfocus directory.
  2. Create a subdirectory named openesql.
  3. Under the new openesql subdirectory, create a subdirectory named main.
  4. Copy mfsqljvm.jar from the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory to the %JBOSS_HOME%\modules\com\microfocus\openesql\main directory.
  5. In the %JBOSS_HOME%\modules\com\microfocus\openesql\main directory, create a new module.xml file that contains the following code, which names the SQL runtime mfsqljvm.jar file as a resource:

<module xmlns="urn:jboss:module:1.1" name="com.microfocus.openesql">
  <dependencies>
    <module name="javaee.api"/>
    <module name="com.microfocus.cobol.runtime"/>
  </dependencies>
  <resources>
    <resource-root path="mfsqljvm.jar"/>
  </resources>
</module>

    Unlike the non-SQL version of this tutorial, with SQL you must update the MANIFEST.FM file to list the SQL runtime namespace as a dependency.

  6. In the Eclipse Navigator pane, navigate to TemperatureConverterPrj > WebContent > META-INF; then double-click MANIFEST.MF to open it in the editor.
  7. Either add a Dependencies: line or edit the existing Dependencies: line to read as follows:
    Dependencies: com.microfocus.cobol.runtime, com.microfocus.openesql
  8. Save the file and close the editor.
Parent topic: Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Modify COBOL Source
Next topic: Run the JSP Application
Related concepts
Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server


Run the JSP Application

Run the TemperatureConverterJsp application on JBoss.
  1. In the Project Explorer, right-click the TemperatureConverterPrj project; then select Run As > Run on Server from the context menu.
  2. On the Run On Server dialog box, be sure that JBoss AS 7.1 is selected; then click Finish.

    Eclipse generates an HTTP Status 404 message, indicating that it is unable to find the http://localhost:8080/TemperatureConverterPrj/ URL. This is expected because the application uses two different URLs to call the two conversion routines with arguments.

    Eclipse has a built-in browser window that opens when the server is started, but you can use any external browser to enter the URLs.

  3. In the Eclipse browser address field, enter the following to run the Fahrenheit to Celsius conversion:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getCelsius?fahrenheit=212

    Eclipse presents a .json file dialog box.

  4. Click Open to view the results of the method call.
  5. Repeat steps 3 and 4, substituting the following URL to test the Celsius to Fahrenheit conversion:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getFahrenheit?celsius=36.8
    Note: You can change the values of the fahrenheit and celsius arguments to see different results.
  6. To test in an external browser, open a browser of your choice; then enter each of the same URLs.

    Depending on your browser, the results are either returned in the browser or you are prompted to save the results to a text file.

Parent topic: Tutorial: SQL - Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Previous topic: Deploy the COBOL JVM Runtime


Tutorial: Calling JVM COBOL programs as part of an Axis Web service

  • Introduction
  • Prerequisites
  • Create a Web Service Description Language document
  • Create the JVM project
  • Create the wrapper project
  • Create the dynamic Web project
  • Using JBoss
  • Configure for deployment
  • Run the application
  • Use the Web Service Explorer
  • Debug the Web service
Parent topic: Managed COBOL Tutorials


Introduction

This tutorial walks through the process of deploying an existing COBOL application as a Web service within the JBoss Application Server. To achieve this, the COBOL application is deployed as Java byte code so that it is easily accessible by a Java class that provides the Web service interface.

The web service interface is designed by reviewing the interface to the COBOL program. From this the Web service operations and parameters are created using a visual editor. Once the Web service is designed, a Java class can be automatically generated that represents the implementation of the Web service.

The overall Web service application comprises:
  • A project that contains an unmodified legacy COBOL program.
  • A small wrapper COBOL program that makes the file status more helpful to a caller. This wrapper program uses smart linkage, which makes it possible to call a procedural COBOL program from Java by exposing the linkage parameters as native Java types.
  • A project that contains the definition of the Web service to the outside world.
  • A Web project that contains the Java server code which interfaces with the outside world and a Java class to bridge the gap between the service code and the COBOL application.
  • The client, an automatically generated test harness.

About the Book application

This tutorial uses the BookLegacy.cbl application to demonstrate several modernization options available with Visual COBOL. BookLegacy.cbl is a simple stock control system for a library or bookstore and provides standard operations to create, read, update and delete entries which are stored using an indexed file. The interface to this application has several parameters:
procedure division using by value     lnk-function
                         by reference lnk-b-details
                               by reference lnk-file-status.
Input parameters
lnk-function 01 pic x.
Corresponds to either:
1
read-record
2
add-record
3
delete-record
4
next-record
Input/output parameter
lnk-b-details 01 group.
Contains the author, title, and related information.
Output parameter
lnk-file-status 01 pic xx.
The Micro Focus file status code.

Four operations are represented by this interface: add book, next book, read book and delete book. These operations are exposed as part of the Web service. The part of the design process that represents this COBOL interface in a manner more suitable for a Web service is called a WSDL.

Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Prerequisites

You must install and configure the following in order to complete this tutorial:
  • This tutorial requires your projects to target Java 8.
  • JBoss Tools, a plugin that enables Eclipse to manage the JBoss Runtime.
  • JBoss EAP 6.4, for hosting Web services.
  • Apache Axis2 1.7.8, a tool to generate server and client code to handle Web services protocols.
  • The JVM Micro Focus COBOL Runtime.
  • You also need to download from the Micro Focus Community Web site a .zip file containing source files.

JBoss Tools

Before installing JBoss Runtime you must download and install the JBoss Tools from the Eclipse Marketplace:
  1. Click Help > Eclipse Marketplace

    This opens the Eclipse Marketplace dialog box.

  2. In the Find field, type JBoss Tools, and then press Enter.
  3. Find the JBoss Tools 4.5.3.Final plugin in the returned results list, and then click Install.
  4. In the Confirm Selected Features page, click Confirm.
  5. Accept the license agreement, and then click Finish.

    If you receive a security warning, click Install anyway.

  6. When prompted to restart Eclipse, click Restart Now.
    Note: If this is the first time the workspace settings have been changed then Eclipse might prompt you to store preference information.

JBoss

Download and install JBoss EAP

  1. In a browser, open the 3.3. DOWNLOAD AND INSTALL JBOSS EAP USING THE ZIP page located on the Red Hat Web site.
  2. Follow the instructions provided to download and install the Red Hat JBoss Enterprise Application Platform. See Additional Software Requirements for more information on supported versions.
    Note: This download might require a Red Hat subscription.

Install JBOSS AS tools in Eclipse

To enable Eclipse to manage JBoss Application Server, you need to add the server runtime environment:

  1. Start Eclipse.
  2. Click Window > Preferences > Server > Runtime Environments.
  3. Click Add.

    This opens the New Server Runtime Environment dialog box.

  4. Expand Red Hat JBoss Middleware, and then click Red Hat JBoss Enterprise Application Platform 7.1 Runtime.
  5. Click Next.

    This opens the New Server Runtime Environment dialog box.

  6. Next to the Home Directory field, click Browse, and then select the folder containing JBoss EAP.
  7. Click OK.
  8. Ensure that you are using a Java 8 JRE runtime.
  9. Click Finish.
  10. Click Apply and Close.

Configure JBoss for each new workspace

  1. Start Eclipse.
  2. Click Window > Preferences > Web Services > Server and Runtime
  3. In the Server runtime list, click JBoss version.
  4. Click OK.

Micro Focus COBOL Runtime

The JVM Micro Focus COBOL Runtime (mfcobolrts.jar) is located by default in the Micro Focus COBOL install directory %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin (Windows) or $COBDIR/bin (UNIX).

The COBOL Runtime file must be added to the Deployment Assembly later in the tutorial.

Axis2

To download Axis2:

  1. Click here to download Axis2.
  2. Click axis2-1.7.8-bin.zip, and download from a suitable mirror site.
  3. Extract into a directory.

You need to configure Axis2 for each new workspace in Enterprise Developer:

  1. Click Window > Preferences > Web Services > Axis2 Preferences.
  2. On the Axis2 Runtime tab, click Browse and navigate to the Axis2 top-level folder.
  3. Click Apply and Close.
  4. Click Window > Preferences > Web Services > Server and Runtime.
  5. In the Web service runtime list, click Apache Axis2.
  6. Click Apply and Close.

Source files

  1. On the Micro Focus Community Web site, click Download.
  2. Save the .zip file and extract its content into a directory.
    Note: The extract directory is referred to in this tutorial as <tutorial_source_folder>.
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service
Related concepts
Additional Software Requirements on Windows


Create a Web Service Description Language document

A Web service is defined within an XML document using the Web Services Description Language (WSDL). This document describes all the operations, their parameters, an optional endpoint URL and what protocol to use. The WSDL document is used by tooling to generate code both for the server side implementation of the Web service as well as client side code to access the service.

  • About the Web service description
  • Create the WSDL document using the editor
  • Setting the service endpoint
  • Create the addBook operation with parameters
  • Create the BookDetail type
  • Create the BookReturn type
  • Add the rest of the operations
  • Binding information
  • Validate the WSDL
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


About the Web service description

The COBOL program contains four separate functions, read, add, delete and next. These functions are exposed by a single entry point in a program. The functions are broken out into separate discrete operations.

The parameters to these operations are based upon the parameters required by the COBOL program for the specified operation. You can express some parameters differently, for example, the file status code can be changed to a more readable error message.

The following tables show the operations of the Web service and the parameters used by each operation:

Operations
Operation | Input data type | Output data type
nextBook | string | BookReturn
addBook | BookDetail | BookReturn
deleteBook | string | BookReturn
readBook | string | BookReturn
BookDetail type
Parameter | Data type
Title | string
Type | string
Author | string
StockNo | string
ISBN | long
Retail | string
Onhand | int
Sold | int
BookReturn type
Parameter | Data type
Book | BookDetail
Status | string
StatusNo | int

With these operations, only StockNo is being used for readBook, even though the Book application is capable of looking up records based on other fields. You can create other operations that enable you to retrieve records using different fields.

Parent topic: Create a Web Service Description Language document


Create the WSDL document using the editor

You need to create the WSDL document using the Eclipse WSDL Editor. You need to start by creating a workspace to hold all the projects for this tutorial.

Remember: In the topics describing how to use the WSDL Editor, the phrase "double-click" means one click to select the required box and another click to place the cursor in the text box for editing.
  1. Start Enterprise Developer.
  2. Change the perspective to JAVA EE, click Window > Perspective > Open Perspective > Other.

    This opens the Open Perspective dialog box.

  3. Click Java EE, and then click Open.
  4. Click File > New > Other > General > Project, and then click Next.

    This opens the New Project dialog box.

  5. In the Project name field, type wsdl, and then click Finish.
  6. In the Project Explorer, right-click the wsdl project, then click New > Other.

    This opens the New dialog box.

  7. Type wsdl, and then click WSDL File.
  8. Click Next.
  9. In the File name field, type BookLegacy.wsdl.
  10. Click Next.
  11. In the Target namespace field, type http://project.company.com/BookLegacy/.

    This URL makes the types unique to the web service. Update the URL keeping the "BookLegacy" part.

  12. Use the other defaults and then click Finish.
This opens a new WSDL document in the WSDL editor, giving a template with one operation.
Note: Click the Design tab to see the WSDL diagram.
Parent topic: Create a Web Service Description Language document


Setting the service endpoint

The service endpoint is the URL used by the client to locate the implementation of the Web service at run time. To set the endpoint:
  1. In the Design tab of the WSDL editor, overwrite the BookLegacySOAP address property of the BookLegacy service with the location of your JBoss server. This is typically http://localhost:8080.
    Note: If BookLegacy.wsdl is not open in the WSDL editor, double-click on BookLegacy.wsdl. Alternatively, right-click BookLegacy.wsdl, and then click Open With > WSDL Editor.
  2. Click File > Save.
Parent topic: Create a Web Service Description Language document


Create the addBook operation with parameters

To define the first operation:

  1. In the second row of the BookLegacy operations table, double-click NewOperation, and then type addBook.
  2. To give the parameter a name, in the input row, double-click parameters and type newBook.
  3. To set the element in the third column, double-click the addBook list, and then click New.

    This opens a New Element dialog box.

  4. In the Name field, type newBook and then click OK.
  5. In the output row, double-click parameters and type bookReturn.
  6. In the output row, double-click the addBookResponse list, and then click New.

    This opens the New Element dialog box.

  7. In the Name field, type BookReturnE, and then click OK.
  8. Click File > Save.
Parent topic: Create a Web Service Description Language document


Create the BookDetail type

You now need to create the BookDetail type for the addBook operation input:

  1. At the end of each row in the operations diagram is an arrow pointing right. Click on the arrow next to newBook input element.

    This opens an Inline Schema editor showing the newBook element.

  2. Right-click anywhere in the view, and then click Set Type > New.

    This opens the New Type dialog box.

  3. Click Complex Type (the default).
  4. In the Name field, type BookDetail, and then click OK.

    This adds a new diagram to the editor.

  5. Right-click BookDetail, and then click Add Element.

    This creates a new row.

  6. The editor automatically highlights the text NewElement enabling you to edit it. Type Title, and leave the type as string.
    Note: If focus is lost, double-click NewElement and type Title.
  7. Right-click BookDetail (the header row), click Add Element, and then type Type.
  8. Repeat step 7 to add two more elements, Author and StockNo. All of these elements should be of type string.
  9. Create one more element named ISBN. This element must be type long.
  10. Right-click string, and then click Set Type > Browse.

    This opens the Set Type dialog box.

  11. In the Types list, click long, and then click OK.
  12. Add the following three elements and set their type by double-clicking string and selecting from the list:
    Element Name | Data Type
    Retail | string
    Onhand | int
    Sold | int
    Your diagram should now contain:
    Element Name | Data Type
    Title | string
    Type | string
    Author | string
    StockNo | string
    ISBN | long
    Retail | string
    Onhand | int
    Sold | int
  13. Click File > Save and close the Inline Schema editor.
Parent topic: Create a Web Service Description Language document


Create the BookReturn type

  1. In the BookLegacy.wsdl editor (operations diagram), click on the arrow next to BookReturnE output element.

    This opens an Inline Schema editor showing the element BookReturnE.

  2. Right-click anywhere in the view, and then click Set Type > New.

    This opens the New Type dialog box.

  3. Click Complex Type (the default).
  4. In the Name field, type BookReturn, and then click OK.

    This adds a new diagram to the editor.

  5. Right-click BookReturn, and then click Add Element.

    This creates a new row.

  6. In the highlighted NewElement field, type Book.
  7. To change the type, right-click on the row and click Set Type > Browse.

    This opens the Set Type dialog box.

  8. In the Name field, type Book.

    This lists the BookDetail and BookReturn types.

  9. Click BookDetail in the Types list, and then click OK.
  10. Continue to add the following elements:
    Element Name | Data Type
    Status | string
    StatusNo | int
    Your diagram should now contain:
    Element Name | Data Type
    Book | BookDetail
    Status | string
    StatusNo | int
  11. Click File > Save, and then close the Inline Schema editor.
Parent topic: Create a Web Service Description Language document


Add the rest of the operations

You now need to create the three remaining operations, nextBook, deleteBook, readBook:

  1. In the BookLegacy.wsdl editor, right-click addBook, and then click Add Operation.

    This creates new input and output rows.

  2. The text NewOperation should be highlighted, type nextBook.
  3. In the input row, double-click parameters and type stockNo.
  4. In the input row, right-click nextBook, and then click Set Element > New Element.

    This opens the New Element dialog box.

  5. In the Name field, type stockNo, and then click OK.
  6. Click on the arrow next to the stockNo input element.

    This opens an Inline Schema editor showing the stockNo element.

  7. Right-click the stockNo element, and then click Set Type > New.

    This opens the New Type dialog box.

  8. Click Simple Type.
  9. In the Name field, type stockNo.
  10. Click OK.
    Note: The default type for the element is string.
  11. Click File > Save, and close the Inline Schema editor.
  12. In the output row, double-click parameters and change to bookReturn.
  13. In the output row, right-click nextBookResponse, and then click Set Element > Existing Element.

    This opens the Set element reference dialog box.

  14. In the Name field, type BookReturnE.
  15. In the Elements list, click BookReturnE.
  16. Click OK.

    Here we are reusing a previous element and its type.

  17. To add the remaining two operations deleteBook and readBook repeat the steps 1 through 10. At step 4, click Existing Element, and then click stockNo in the Elements list.
  18. Click File > Save.

The completed diagram should look like this:

Parent topic: Create a Web Service Description Language document


Binding information

Each operation needs to be linked to the server URL.

  1. Right-click [image] and then click Generate Binding Content.

    This opens the Binding Wizard dialog box.

  2. You can use the default values, click Finish.

You can see the generated XML in the Source tab of the WSDL Editor:

  <wsdl:binding name="BookLegacySOAP" type="tns:BookLegacy">
      <soap:binding style="document"
          transport="http://schemas.xmlsoap.org/soap/http" />
Parent topic: Create a Web Service Description Language document


Validate the WSDL

It is important to use the validation tool to ensure the WSDL conforms to the standards, otherwise you might encounter issues during the creation of the server code from the Axis2 tool.

  1. From Project Explorer, right-click BookLegacy.wsdl, and then click Validate.

    This opens the Validation Results dialog box, reporting any warnings or errors. You can see the detail of the warnings and errors in the Markers view.

You should only have one warning:

WS-I: (BP2120) A binding has operations that are not unique.

This is an incorrectly presented message that indicates there are multiple operations which have the same parameter types. It is not an issue for this application and the warning can be ignored. See Eclipse Bug 70481 for more information.

This completes the creation of the WSDL, it is used later to generate the server side code.

Parent topic: Create a Web Service Description Language document


Create the JVM project

First you need to create a project to contain the procedural COBOL program and make it available for execution from a Java program:

Create the project

  1. Click File > New > Other.

    This opens the New dialog box.

  2. Expand Micro Focus COBOL, and then click COBOL JVM Project.
  3. Click Next.

    This opens the New COBOL JVM Project dialog box.

  4. In the Project name field, type CobolBook.
  5. Ensure Use default location is checked.
  6. Ensure that the project is set up to use a Java 8 JRE.
  7. Click Finish.
This creates a blank JVM COBOL project to contain the procedural COBOL program that you are to import into the Web application.
Note: If Eclipse prompts you to switch to the COBOL perspective then do so. In general, any action that uses the CobolBook project is expected to be carried out in the COBOL perspective. The dynamic web project that comes later in this tutorial is expected to be done in the Java EE perspective. To change perspectives later, click on the appropriate option in the top right of the Eclipse main window.

Add the COBOL source files

The project uses two source files, BookLegacy.cbl and book-rec.cpy, that need to be imported into your project:

Important: Before you import the files from the file system you need to rename <tutorial_source_folder>\COBOLBook\src\book.cbl to BookLegacy.cbl.
  1. In Application Explorer, right-click the CobolBook project, and then click Import.

    This opens the Import dialog box.

  2. Expand General folder, and then click File System.
  3. Click Next.
  4. Click Browse and navigate to <tutorial_source_folder>\COBOLBook\src.
  5. Click OK.
  6. Check src in the left pane.
  7. Click Finish.

    This imports the files into the project.

Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Create the wrapper project

The BookWrapper.cbl interface has a similar interface to BookLegacy.cbl but updated to turn the file status into a string and a numeric value, and pass it back in lnk-status-group. The setup-status section does the conversion.

procedure division using by value lnk-function by reference lnk-b-details lnk-status-group.

The BookWrapper.cbl program is compiled with the ILSMARTLINKAGE directive which creates classes to represent the PROCEDURE DIVISION parameters. In the bin folder are the Details.class and StatusGroup.class files. These files are used in the creation of the bridge code between the server code and the COBOL application.

Create the project

To create the wrapper project:

  1. In the COBOL perspective, click File > New > COBOL JVM Project.

    This opens the New COBOL JVM Project dialog box.

  2. In the Project name field, type BookWrapper
  3. Click Finish.

    To set the compiler directives:

  4. Right-click the BookWrapper project, and then click Properties.

    This opens the Properties for BookWrapper dialog box.

  5. Click Micro Focus > Build Configuration.
  6. In the Additional directives field, type:

    ilnamespace(com.microfocus.bookwrapper) ilsmartlinkage ilcutprefix(lnk-b) ilcutprefix(lnk-) jvmdecimal(scaledinteger) warnings(3)

  7. Click Apply and Close.

Add the COBOL source files

The project uses one source file, BookWrapper.cbl, that needs to be imported into your project:

  1. In the COBOL Explorer, expand the BookWrapper project, and then right-click src.
  2. Click Import > Import.

    This opens the Import dialog box.

  3. Click General > File System.
  4. Click Next.
  5. Next to the From directory field, click Browse and navigate to <tutorial_source_folder>\BookWrapper\src.
  6. Click OK.
  7. Check src in the left pane.
  8. Click Finish.

    This import the files into the project.

Set the copybook path

The copybook path needs to be set to point to the CobolBook project:

  1. Open the BookWrapper project's Properties dialog box.
  2. Click Micro Focus > JVM Build Path.
  3. Click the Projects tab, and then click Add.

    This opens the Required Project Selection dialog box.

  4. Check CobolBook, and then click OK.
  5. Click Apply and Close.
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Create the dynamic Web project

Next you need to create a project that implements the Web service operations defined in the WSDL document. Axis2 automatically generates the Java code for this.

  • Create a new project
  • Generate the server-side code
  • Add the bridge code
  • Configure the project
  • Update the BookLegacySkeleton class
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Create a new project

The project configuration stage involves selecting the appropriate Java, JBoss, Servlet, and Axis2 versions.
Important: Problems may arise at this stage due to incorrectly installed and configured Axis2 or JBoss AS, see Before you start for more information.
  1. Change to the JAVA EE perspective. Click Window > Perspective > Open Perspective > Other.

    This opens the Open Perspective dialog box.

  2. Click Java EE, and then click OK.
  3. Click File > New > Dynamic Web Project.

    This opens the New Dynamic Web Project dialog box.

  4. In the Project name field, type DynWebTest1.
  5. Click New Runtime.

    This opens the New Server Runtime Environment dialog box.

  6. Expand Red Hat JBoss Middleware, and then click Red Hat JBoss Enterprise Applcation Platform 7.1 Runtime.
  7. Click Next.
  8. Next to the Home Directory field, click Browse and navigate to the root folder where JBoss EAP has been installed.
  9. Click OK
  10. Ensure the Runtime JRE is set to a Java 8 JRE.
  11. Click Finish.
  12. In the Dynamic web module version list, click 2.5.
  13. Click Modify.

    This opens the Project Facets dialog box.

  14. Check Axis2 Web Service.
  15. In the Java row, click the Version list, and then click 1.8.
  16. Click OK.
  17. Click Finish.

    This generates the project.

Parent topic: Create the dynamic Web project


Generate the server-side code

Next the WSDL is put through the Axis2 tool to generate the server code. This server code contains logic to receive XML from the HTTP server using SOAP (which contains the input data), parse it, and create the types to pass to the main application. It also contains code to turn these types back to XML and return to the Web server, which returns a SOAP response.

You must start the JBoss EAP 7.1 server before generating the server-side code:

  1. Click Window > Show View > Servers.
  2. Right-click in the Servers tab, and then click New > Server.

    This opens the New Server dialog box.

  3. Click Red Hat JBoss Middleware > Red Hat JBoss Enterprise Application Platform 7.1.
  4. Click Next.
  5. Click Finish.
  6. Right-click Red Hat JBoss EAP 7.1 on the Server tab.
  7. Click Start.
    You must wait till the server has started before continuing with the steps to generate the server-side code.
    Tip: You can check that the server has started successfully by looking in the console tab.

To generate the server-side code:

  1. In Project Explorer, right-click BookLegacy.wsdl.
  2. Click New > Other.
  3. Expand Web Services, and then click Web Service.
  4. Click Next.
    This opens the Web Service dialog box.
    Note: If the Web service runtime was correctly configured then it displays Apache Axis2. If it does not click on the link it to change it. This opens the Service Deployment Configuration dialog box. Click Apache Axis2, and then click OK. By default, the Web services type field should be set to Top down Java bean Web Service and the Service definition field should be set to /wsdl/BookLegacy.wsdl.
  5. Click Finish.

    A progress bar might appear while it generates the code.

    Important: When using Axis2 1.7 and onwards, you might generate the following exception:
    Exception occurred during code generation for the WSDL  : java.lang.NoClassDefFoundError:

    This is because Eclipse does not copy the xmlschema-core-n.n.n.jar file to your dynamic Web project. To avoid this exception, copy the xmlschema-core-n.n.n.jar file located in your $AXIS2_HOME/lib folder to the DynWebTest1/WebContent/WEB-INF/lib folder. You need to restart Eclipse before attempting to run the server-side code generation steps again.

  6. Once the code is generated the file BookLegacySkeleton.java should appear in an editor pane.
  7. It is a good idea to reformat the source code at this point. Right-click in the editor pane, select Source > Format.
  8. Click File > Save.

Comments

The classes BookDetails, BookReturn, BookReturnE, NewBook, and StockNo hold instances of the types represented in the WSDL.

In the outline view for BookLegacySkeleton.java are four methods, nextBook(), readBook(), deleteBook(), and addBook(). These are the methods that are called by the web service for the operations that were defined and is where you place your code.

Because you might want to regenerate this code, it is a good idea to keep the user code in this file to a minimum and have all the logic in a separate class. Each of these methods contain one line to invoke an appropriate method in a new class called BookOperation. The next step is to create this class which interfaces between the Web service and the COBOL application.

Parent topic: Create the dynamic Web project


Add the bridge code

The project uses a Java class, BookOperation.java, that needs to be imported into your project.

This code converts the instance data types from the Web service to types for the COBOL application and do the appropriate initialization for the COBOL application.

  1. In the DynWebTest1 project, right-click on the Java Resources\src folder in Project Explorer, and then click Import > Import.

    This opens the Import dialog box.

  2. Click General > File System.
  3. Click Next.
  4. Next to the From directory field, click Browse and navigate to <tutorial_source_folder>\DynWebTest1\src\.
  5. Click OK.
  6. Expand src > com > company > project.
  7. Highlight Book.
  8. Check BookOperation.java in the right pane.
  9. Click Finish to import the file into the project.
  10. Open BookOperation.java in the editor.
  11. Near the top of the file, update the following line with the location of bookfile.dat:
     public static final String BOOK_FILE = "<tutorial_source_folder>\\DataFiles\\bookfile.dat";
    Note: Ensure that you use double backslashes so that the path has a valid escape sequence.
  12. Click File > Save.

    The project builds automatically, but in this case the code compiles with errors. This is because some of the types used are in the COBOL projects.

Comments

In the outline view are the methods readBook(), nextBook(), deleteBook(), and addBook(), which receive the instance data from the Web service. Each in turn calls a doOperation() method which then converts the data into type of a similar structure for the COBOL application.

The conversion to COBOL is made easier by the types created by SMARTLINKAGE (Details and StatusGroup) enabling a transfer of fields between the Web service types and the ones for the COBOL application. These transfers are done in the methods getDetails() and getBookReturnE().

The final method of note is the overload of doOperation().

static private BookReturnE doOperation(String action, Details details, IRunUnit runUnit)
    {
             StatusGroup statusGroup = getObject(StatusGroup.class, runUnit);

             BookWrapper bookWrapper = getObject(BookWrapper.class, runUnit);
             bookWrapper.setfilename(BOOK_FILE);
             bookWrapper.BookWrapper(action, details, statusGroup);

             return getBookReturnE(details, statusGroup);
    }

The method invoke bookWrapper.BookWrapper(action, details, statusGroup); calls into the COBOL application and was added to the class by the SMARTLINKAGE feature.

The methods of this class can be static as they do not have any instance data and it reduces the number of objects that are created and garbage collected.

Note: Run units are used to isolate one Web service request from another. Each COBOL program, the sub-programs it calls, and any resources such as data files are all self-contained within the run unit and separate from other run units using the same programs.

The next step is to update the four methods in the BookLegacySkeleton class to call the appropriate methods in the BookOperation class.

Parent topic: Create the dynamic Web project


Configure the project

To add the class folder to the project's build path:

  1. In Project Explorer, right-click the DynWebTest1 project, and then click Properties.
  2. Click Java Build Path.
  3. Click the Libraries tab.
  4. Click Add Class Folder.

    This opens the Class Folder Selection dialog box.

  5. Check the bin folders under BookWrapper and CobolBook.
  6. Click OK.
  7. Click Add Library.

    This opens the Add Library dialog box.

  8. Click COBOL JVM Runtime System, and then click Next.
  9. Click Finish.
  10. Click Apply and Close.

    The project rebuilds without error.

Parent topic: Create the dynamic Web project


Update the BookLegacySkeleton class

  1. In the DynWebTest1 project, open BookLegacySkeleton.java in the editor.
  2. To enable the methods that are being added to be found, after the package line type:
    import com.company.project.Book.BookOperation;
  3. Each of the methods have the following code:
    // TODO : fill this with the necessary business logic
 throw new java.lang.UnsupportedOperationException( "Please implement "
         + this .getClass().getName() + "#nextBook" );
    Replace the appropriate throw statement with the appropriate return statement.
    Important: Axis2 may generate the methods in a different order and so care is needed when pasting the return statement into the correct method. Alter the stockNo n parameter so that it fits with the one in that particular method.
    public com.company.project.booklegacy.BookReturnE nextBook(
            com.company.project.booklegacy.StockNoE stockNon) {
        return BookOperation.nextBook(stockNon);
    }

    public com.company.project.booklegacy.BookReturnE readBook(
            com.company.project.booklegacy.StockNoE stockNon) {
        return BookOperation.readBook(stockNon);
    }

    public com.company.project.booklegacy.BookReturnE deleteBook(
            com.company.project.booklegacy.StockNoE stockNon) {
        return BookOperation.deleteBook(stockNon);
    }

    public com.company.project.booklegacy.BookReturnE addBook(
            com.company.project booklegacy.NewBook newBook) {
        return BookOperation.addBook(newBook);
}
  4. Click File > Save All.

Everything builds cleanly.

Parent topic: Create the dynamic Web project


Using JBoss

JBoss Configuration View

Once a Dynamic Web Project has been created and Eclipse is in Java EE Perspective, a Servers tab is available. JBoss can be started and stopped in the Servers tab with the green circle and red square icons.

In the Servers tab, expand Red Hat JBoss EAP 7.1 This displays the applications that have been deployed.

Double-click Red Hat JBoss EAP 7.1 opens a JBoss Information and Configuration view in Eclipse.

Starting JBoss

When starting JBoss there are known issues with classes from the Axis2 .jar files conflicting with the same named classes in the JBoss .jar files. JBoss issues warning messages for these which may be ignored. The large number of exceptions generated may hide other more serious issues.

One solution is to delete the org/w3c/dom directory from DynWebTest1\WebContent\WEB-INF\lib\xmlbeans-2.3.0.jar.

A neater solution is to exclude these classes from being loaded by adding the file jboss-classloading.xml to the DynWebTest1\WebContent\WEB-INF directory with the following XML:

<classloading xmlns="urn:jboss:classloading:1.0"
 domain="DynWebTest1.war"
 parent-domain="DefaultDomain"
 export-all="NON_EMPTY"
 import-all="true"
 parent-first="false"
 excluded="org.w3c.dom">
</classloading >
See the discussions on the JBoss community Web pages for more information:
  • https://community.jboss.org/thread/178170
  • https://community.jboss.org/thread/160881?_sscc=t
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Configure for deployment

You now need to configure the environment ready for deployment:

  • Include the class files
  • Export the content
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Include the class files

You need to include the class files from the COBOL projects and the cobconfig.properties file to enable resources from different projects to be deployed together:

  1. In Project Explorer, right-click on the DynWebTest1 project, and then click Properties.

    This opens the Properties for DynWebTest1 dialog box.

  2. Click Deployment Assembly.
  3. On the Deployment Assembly tab, click Add.

    This opens the New Assembly Directive dialog box.

  4. Click Java Build Path Entries, and then click Next.
  5. Select bin - \CobolBook, bin - \BookWrapper, and COBOL JVM Runtime System.
    Note: You can use Ctrl+Click to select multiple paths.
  6. Click Finish.
  7. Click Apply and Close.
Parent topic: Configure for deployment


Export the content

To export the content as a .war file into the JBoss deployment folder:

  1. Make sure Eclipse is in the Java EE perspective, click Window > Perspective > Open Perspective > Other. Click Java EE and then click Open.
  2. In Project Explorer, right-click the DynWebTest1 project.
  3. Click Export > WAR file.

    This opens the Export dialog box.

  4. Click Browse.

    This opens the Save As dialog box.

  5. Navigate to the [jboss-installation]\standalone\deployments folder.
  6. Click Save.
  7. Click Finish.

The application is now deployed to the JBoss EAP server. In the Servers tab, right-click Red Hat JBoss EAP 7.1 Runtime server and then click Start.

Parent topic: Configure for deployment


Run the application

To run the application:

  1. In Project Explorer, right-click the DynWebTest1 project, click Run As > Run On Server.

    The first time this is done a Run On Server dialog box is displayed with a list of the available servers.

  2. Click Red Hat JBoss EAP 7.1 Runtime server, and then click Finish.

    This opens a browser within Eclipse and displays an Apache Software Foundation welcome page.

  3. Click Services in the Web page to see information about the BookLegacy service.
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Use the Web Service Explorer

You can use the Web Services Explorer in Eclipse to see the Web service in action:

  1. In the list of available services, click BookLegacy .

    This displays the WSDL in XML format.

  2. Copy the URL http://localhost:8080/DynWebTest1/services/BookLegacy?wsdl from the field at the top of the browser.
  3. Click Run > Launch the Web Services Explorer.

    This opens the Web Services Explorer view.

  4. In the top-right of the Web Service Explorer page, click WSDL Page icon [image].
    Note: You need to click the Refresh icon [image] if the operation or action is not displayed first time.

    This displays WSDL Main in the Navigator pane of the Web Service Explorer.

  5. Click WSDL Main.

    This displays Open WSDL in the Actions pane of the Web Service Explorer.

  6. Paste the copied URL into the WSDL URL field, and then click Go.

    This displays the WSDL Binding Details, which includes a list of all the operations and endpoints.

  7. In the Name column, click readBook.

    This displays Invoke a WSDL Operation in the Actions pane.

  8. In the stockNo field, type 1111, and then click Go.
  9. The results are displayed in the Status pane of the Web Service Explorer.
  10. Clicking on addBook brings up a form to enter the details for a new book. You can see how the Explorer has used the WSDL to generate a form for this operation.
  11. Enter the details of this book and click Go.
    Title: The Hobbit
    Type: Fiction
    Author: J. R. R. Tolkien
    StockNo: 7777
    ISBN: 0007487282
    Retail: 9.99
    Onhand: 10
    Sold: 20
  12. The book details should be returned in the Status pane.
  13. Try the other operations in the Navigator pane.
Note: In the Status pane there is a Source link to view the SOAP Request and Response Envelopes. The XML displayed which is sent via HTTP POST and received back from the server.
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Debug the Web service

The web service can be debugged in both the Java and COBOL programs.

  1. Stop the JBoss Server.
    1. Click the Servers tab.
    2. Right-click Red Hat JBoss EAP 7.1, and then click Stop.
  2. Set some breakpoints:
    1. Set a break point in the return statement of the readBook() method in the BookLegacySkeleton.java file. Right-click in the margin and select Toggle Breakpoint.
    2. In the COBOLBook project set a break point in the do-read-record section of BookLegacy.cbl.
  3. Right-click on the DynWebTest1 project and select Debug As > Debug on Server.

    This opens a Debug On Server dialog box.

  4. Click Finish.
  5. Click Run > Launch the Web Services Explorer.
  6. Click on readBook. This brings up an Invoke a WSDL Operation page.
  7. Type 1111 into the stockNo field and click Go. The Eclipse Debugger should now stop in the readBook() method in BookLegacySkeleton.java.
  8. Open the Variables view from Window > Show View > Variables. As debugging proceeds through the applications current variables are displayed.
  9. Press F8 (Resume) to continue to the next breakpoint. Eclipse shows a "Source not found" message with an Edit Source Path button.
  10. Click on Edit Source Path bringing up the Edit Source Lookup Path dialog box.
  11. Select Add.
  12. Select COBOL Project then OK.
  13. Click Select All then click OK, then OK a second time to close the dialog box.

    Now the COBOL source code for BookLegacy.cbl is displayed.

  14. Use F5 to step through the application to investigate further.
  15. Press F8 to complete the operation and show the results in the Status pane of the Web Services Explorer.
  16. Use the Navigator pane in the Web Service Explorer to try other operations.
Parent topic: Tutorial: Calling JVM COBOL programs as part of an Axis Web service


Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface

This tutorial takes you through the steps to create a native COBOL program that uses copybooks to enable you to create, read, modify, and delete contact information from a file. You are taken through the steps to create native COBOL test cases that interact through a user interface created using the JavaFX library. You will compile the native COBOL programs as JVM Managed source.

Note: All projects discussed in this tutorial are available in the samples folder %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples.

Prerequisites

You must have installed Enterprise Developer for Eclipse and a version of Oracle's Java that contains the JavaFX libraries.

  1. Customizing the COBOL Perspective
  2. Creating a COBOL JVM Project
  3. Creating a COBOL JVM Unit Test Project
  4. Creating a Project to Expose the Record Functions
  5. Creating a Java JUnit Testing Project
  6. Creating a Project to Handle the User Interface
  7. Running the Application
Parent topic: Managed COBOL Tutorials


Customizing the COBOL Perspective

In this tutorial you will use the COBOL perspective:

To use the COBOL perspective

To change to the COBOL perspective:

  1. Click Window > Perspective > Open Persepective > Other.

    This opens the Open Perspective dialog box.

  2. Click COBOL.
  3. Click Open.

To customize the COBOL perspective

To view the folders and files that you create you need to customize the COBOL Explorer view:

  1. In the COBOL Explorer, click View Menu View Menu, and then click Filters and Customization.

    This opens the Filters and Customizations dialog box.

  2. In the Filters tab, uncheck Empty folders outside categories, Non-COBOL projects, and Non-Micro Focus projects.
  3. Click OK.
Parent topic: Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
Next topic: Creating a COBOL JVM Project


Creating a COBOL JVM Project

In the COBOL Explorer view, create a COBOL JVM project:
  1. Click File > New > COBOL JVM Project

    This opens the New COBOL JVM Project dialog box.

  2. In the Project name field, type AddressBookJVM.
  3. Click Use default JRE.
  4. Click Finish.

You now need to import the native COBOL procedural code for the address book sample:

  1. Importing Native COBOL Procedural Code
Parent topic: Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
Previous topic: Customizing the COBOL Perspective
Next topic: Creating a COBOL JVM Unit Test Project


Importing Native COBOL Procedural Code

To import the COBOL programs and copybooks into the project's source folder:

  1. In the COBOL Explorer view, expand the AddressBookJVM project.
  2. Right-click the src folder, and then click Import > Import.

    This opens the Import dialog box.

  3. Click General > File System.
  4. Click Next.
  5. Click Browse next to the From directory field.

    This opens the Import from directory dialog box.

  6. Navigate to the Eclipse\jvm_cobol\AddressBookDemo\addressBookJVM\src folder in the samples directory installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples.
  7. Click OK.
  8. In the left pane, check the src folder.
  9. Click Finish.
Note: The project should build automatically. If not, click Project > Build Automatically.
Parent topic: Creating a COBOL JVM Project


Creating a COBOL JVM Unit Test Project

In the COBOL Explorer view, create a COBOL JVM Unit Test Project:

  1. Click File > New > COBOL JVM Unit Test Project.

    This opens the New COBOL JVM Unit Test Project dialog box.

  2. In the Project name field, type AddressBookJVMTest.
  3. Click Use default JRE.
  4. Click Finish.

You need to configure and import the source code that run the tests:

  1. Configuring Project Dependencies
  2. Importing Source Code into the COBOL JVM Unit Test Project
  3. Running the Tests
Parent topic: Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
Previous topic: Creating a COBOL JVM Project
Next topic: Creating a Project to Expose the Record Functions


Configuring Project Dependencies

The AddressBookJVMTest project has dependencies on the AddressBookJVM project. To configure the dependencies:

  1. Right-click the AddressBookJVMTest project, and then click Properties.

    This opens the Properties for AddressBookJVMTest dialog box.

  2. Click Micro Focus > JVM Build Path.
  3. Click the Projects tab, and then click Add.

    This opens the Required Project Selection dialog box.

  4. Click AddressBookJVM.
  5. Click OK.
  6. Click Apply and Close.
Parent topic: Creating a COBOL JVM Unit Test Project
Next topic: Importing Source Code into the COBOL JVM Unit Test Project


Importing Source Code into the COBOL JVM Unit Test Project

You now need to import the COBOL program that contains the test cases. To import the TestRecordsProgram.cbl program into the AddressBookJVMTest project's source folder:

  1. In the COBOL Explorer view, expand the AddressBookJVMTest project.
  2. Right-click the src folder, and then click Import > Import.

    This opens the Import dialog box.

  3. Click General > File System.
  4. Click Next.
  5. Click Browse next to the From directory field.

    This opens the Import from directory dialog box.

  6. Navigate to the Eclipse\jvm_cobol\AddressBookDemo\addressBookJVMTest\src folder in the samples directory installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples.
  7. Click OK.
  8. In the left pane, check the src folder.
  9. Click Finish.

    Expand src > (default package) to display the TestRecordsProgram.cbl program.

Note: The project should build automatically. If not, click Project > Build Automatically.
Parent topic: Creating a COBOL JVM Unit Test Project
Previous topic: Configuring Project Dependencies
Next topic: Running the Tests


Running the Tests

To run the tests:

  1. In COBOL Explorer, Right-click the AddressBookJVMTest project.
  2. Click Run As > COBOL JVM Unit Test

    This opens the Micro Focus Unit Testing view.

  3. In the left pane, expand AddressBookJVMTest > TestRecordsProgram.cbl
  4. Click MFUT_TestrecordsProgram.

    In the Test Results pane, the results massage PASSED is displayed.

    Test Results
Parent topic: Creating a COBOL JVM Unit Test Project
Previous topic: Importing Source Code into the COBOL JVM Unit Test Project


Creating a Project to Expose the Record Functions

To create a Object Oriented COBOL JVM project that exposes read, write, and delete record functions:

  1. Click File > New > COBOL JVM Project.

    This opens the New COBOL JVM Project dialog box.

  2. In the Project name field, type addressBookWrapper.
  3. Click Use default JRE.
  4. Click Finish.

You now need to create a new package, and class that describes the properties of a record:

  1. Configuring Project Dependencies
  2. Creating a New COBOL JVM Package
  3. Creating a New COBOL JVM Class
  4. Creating a COBOL JVM Interface
  5. Creating an Implementation of the IWrapper Interface
Parent topic: Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
Previous topic: Creating a COBOL JVM Unit Test Project
Next topic: Creating a Java JUnit Testing Project


Configuring Project Dependencies

The addressBookWrapper project has dependencies on the AddressBookJVM project. To configure the dependencies:

  1. Right-click the addressBookWrapper project, and then click Properties.

    This opens the Properties for addressBookWrapper dialog box.

  2. Click Micro Focus > JVM Build Path.
  3. Click the Projects tab, and then click Add.

    This opens the Required Project Selection dialog box.

  4. Click AddressBookJVM.
  5. Click OK.
  6. Click Apply and Close.
Parent topic: Creating a Project to Expose the Record Functions
Next topic: Creating a New COBOL JVM Package


Creating a New COBOL JVM Package

To create a new COBOL JVM package in the AddressBookWrapper project:

  1. Right-click the addressBookWrapper project, and then click New > COBOL JVM Package.

    This opens the New COBOL JVM Package dialog box.

  2. In the Name field, type com.addressBookWrapper.
  3. Click Finish.
Parent topic: Creating a Project to Expose the Record Functions
Previous topic: Configuring Project Dependencies
Next topic: Creating a New COBOL JVM Class


Creating a New COBOL JVM Class

You need to create a new COBOL JVM Class in the addressBookWrapper project which will hold the record data:

  1. Right-click addressBookWrapper, and then click New > COBOL JVM Class

    This opens the New COBOL JVM Class dialog box.

  2. In the Name field, type RecordDTO
  3. Click Finish.

    This opens the RecordDTO.cbl program in a COBOL editor.

  4. In the working-storage section, define the public properties that describe a record - its name, address, phone number, and so forth. Your program should look like this:
           class-id com.addressBookWrapper.RecordDTO public.

       working-storage section.
         01 recordID binary-long property with no set public value 0.
         01 #name string property public value "".
         01 family string property public value "".
         01 postalCode binary-long property public value 0.
         01 city string property public value "".
         01 street string property public value "".
         01 phone string property public value "".
       method-id instanceMethod.
       local-storage section.
       procedure division.

           goback.
       end method.

       end class.
  5. Define a constructor that can receive id as an integer and that sets the recordID property to the id:
           method-id New protected.
           procedure division using by value #id as binary-long.
           set recordID to #id
           goback.
       end method.
    Note: Type met and then use Content Assist on the context menu. Alternatively, press Ctrl+Space.
  6. Click File > Save.
Parent topic: Creating a Project to Expose the Record Functions
Previous topic: Creating a New COBOL JVM Package
Next topic: Creating a COBOL JVM Interface


Creating a COBOL JVM Interface

To create an COBOL JVM interface:

  1. In COBOL Explorer, expand addressBookWrapper > src.
  2. Right-click com.addressBookWrapper.
  3. Click New > COBOL JVM Interface.

    This opens the New COBOL JVM Interface dialog box.

  4. In the Name field, type IWrapper.
    Note: The Source folder and Package fields, will already contain addressBookWrapper/src and com.addressBookWrapper respectively.
  5. Click Finish.

    This opens the IWrapper.cbl program in a COBOL editor.

  6. Rename the existing abstract method from interfaceMethod to openConnection.
  7. Using the same syntax, add the method closeConnection, type the following:
           method-id closeConnection.
       procedure division.
       end method.
    Note: Type met and then use Content Assist on the context menu. Alternatively, press Ctrl+Space.
  8. Create methods for creating, updating, and deleting a record using a RecordID and a method to retrieve all records.
    Note: When you declare input and return types you can use either a linkage section as used in the RecordDTO class, or you can declare the type using the as type syntax.

    Your IWrapper.cbl program should look something like this:

           interface-id com.addressBookWrapper.IWrapper public.

       method-id openConnection.
       procedure division.
       end method.

       method-id closeConnection.
       procedure division.
       end method.

       method-id createRecord.
       procedure division returning return-value as type RecordDTO.
       end method.

       method-id updateRecord.
       procedure division using by value dto as type RecordDTO.
       end method.

       method-id deleteRecord.
       procedure division using by value dto as type RecordDTO.
       end method.

       method-id getAllRecords.
       procedure division returning return-value as list[type RecordDTO].
       end method.

       method-id maxNumberOfRecords.
       procedure division returning return-value as binary-long.
       end method.

       end interface.
  9. Click File > Save.
Parent topic: Creating a Project to Expose the Record Functions
Previous topic: Creating a New COBOL JVM Class
Next topic: Creating an Implementation of the IWrapper Interface


Creating an Implementation of the IWrapper Interface

Create the AddressBookWrapper Class

To create an implementation of the IWrapper interface called AddressBookWrapper:

  1. In COBOL Explorer, expand addressBookWrapper > src.
  2. Right-click com.addressBookWrapper.
  3. Click New > COBOL JVM Class.
    This opens the New COBOL JVM Class dialog box.
    Note: The Source folder field is already filled with AddressBookWrapper/src and the Package is already filled with com.addressBookWrapper.
  4. In the Name field, type AddressBookWrapper.
  5. Click Finish.

    This opens the AddressBookWrapper.cbl program in a COBOL editor.

  6. Update the class declaration to acknowledge the interface inheritance:
    class-id com.addressBookWrapper.AddressBookWrapper public
                implements type IWrapper.
  7. In the working-storage section declare a procedure pointer that points to the procedural code in the recordsProgram.cbl from the AddressBookJVM project, together with the required parameters:
           working-storage section.
       *> procedural cobol pointer
       01 pp procedure-pointer private.
       *> private values
       01 #index binary-long value 0 private.
       78 PROCEDURAL_PROGRAM value "recordsProgram" private.
       01 func                     pic 99 private.
       copy "functions.cpy".
  8. You need to create a constructor and initialize the function and the procedure pointer. The procedure function needs to accept three parameters. The first parameter is mandatory and the second two are optional, depending on the function call being made:
           method-id New protected.
       procedure division.
           initialize func
           set pp to entry PROCEDURAL_PROGRAM
           goback.
       end method.
  9. You need a method that enables you to connect with a data store file and can calculate the maximum number of records:
           method-id openConnection.
       procedure division.
           move openFile to func
           call pp using func omitted omitted
           set #index to self::maxNumberOfRecords()
           goback.
       end method.
  10. In the same way, create a close connection method using the closeFile function parameter.
  11. You need to specify a method to create a record without requiring input parameters:
    1. You can create your own implementation of a getUniqueID() method. Alternatively, you can use the code provided in the sample folder.
    2. Create a RecordDTO object and translate it to a procedural record (DTOtoRecord).
    3. Write the rec variable to the data store file using writeRecord.
    4. Return the RecordDTO object to the client.

    You need to explicitly define the rec variable in the local-storage section in the same way it is used in procedural COBOL code. Your code should look something like this:

           method-id createRecord.
       local-storage secion.
       01 rec.
          copy "records.cpy".
       procedure division returning return-value as type RecordDTO.
           declare #id as binary-long = self::getUniqueID()
           declare dto = new RecordDTO(#id)
           set rec to self::DTOtoRecord(dto)
           move writeRecord to func
           call pp using func rec omitted
           set return-value to dto
           goback.
       end method.

    Here is an example of the object record translation:

           method-id DTOtoRecord private.
       linkage section.
       01 rec.
          copy "records.cpy".
       procedure division using by value dto as type RecordDTO
                          returning rec.
           initialize rec
           set recordId of rec to dto::recordID
           set recordName of rec to dto::name
           set recordFamily of rec to dto::family
           set recordCode of rec to dto::postalCode
           set recordCity of rec to dto::city
           set recordStreet of rec to dto::street
           set recordPhone of rec to dto::phone

           goback.
  12. In the same way, create methods for updateRecord and deleteRecord and a private method recordToDTO() that converts the record to an DTO object.
  13. To implement a getAllRecords method:
    1. Declare an arrayParent variable to store the array of records. You will use the variable as an input parameter to the method call.
    2. Declare a rec variable to store a single record while iterating over the results of the method call.
    3. Initialize the arrayParent variable and move the readAllRecords variable to func, and then call the function.
    4. Use a perform operation to loop over the resulting array converting it into RecordDTO objects. Add the objects to a list called return-value that is returned by the method.

    Your code should look something like this:

           method-id getAllRecords.
       local-storage section.
       01 arrayParent.
           03 array occurs 0 to 1000 depending on #index.
           copy "records.cpy".
       01 rec.
           copy "records.cpy".
       procedure division returning return-value as list[type RecordDTO].
           initialize arrayParent
           move readAllRecords to func
           call pp using func omitted arrayParent
           create return-value
           declare i as binary-long.
           perform varying i from 1 by 1 until i >= #index
               set rec to array(i)
               if recordId of rec not= 0
                   declare dto = self::recordToDTO(rec)
                   invoke return-value::add(dto)
               end-if
           end-perform.

           goback.
       end method.
    Note: You can import a complete example of the AddressBookWrapper.cbl program from the samples folder Samples\Eclipse\jvm_cobol\AddressBookDemo\addressBookWrapper\src\com\addressBookWrapper\AddressBookWrapper.cbl
    .

Create the WrapperProvider Class

You need to create a class WrapperProvider, to handle the creation of the IWrapper implementation. It should contain a single static method to handle the operation:

  1. In the addressBookWrapper project, right-click com.addressBookWrapper.
  2. Click New > COBOL JVM Class.
    This opens the New COBOL JVM Class dialog box.
    Note: The Source folder field is already filled with AddressBookWrapper/src and the Package is already filled with com.addressBookWrapper.
  3. In the Name field, type WrapperProvider.
  4. Click Finish.

    This opens the WrapperProvider.cbl program in a COBOL editor.

  5. Copy and paste the following COBOL code into the editor:
           class-id com.addressBookWrapper.WrapperProvider public.

       method-id getWrapper static.
       procedure division returning return-value as type IWrapper.
           set return-value to new AddressBookWrapper()
           goback.
       end method.

       end class.
  6. Click File > Save.
Parent topic: Creating a Project to Expose the Record Functions
Previous topic: Creating a COBOL JVM Interface


Creating a Java JUnit Testing Project

You need to create a Java JUnit testing project to test the newly created COBOL JVM wrapper project. The following is a list of test cases that you might want to create:

  1. Test connection is open/closed.
  2. Create a record.
  3. Update the record.
  4. Create a second record.
  5. Delete the first record.
  6. Delete the second record.
  7. Verify the record content after steps 2 through 6.

You can use the project from the sample folder:

  1. In the COBOL Explorer, click File > Import.

    This opens the Import dialog box.

  2. Click General > Existing Projects into Workspace.
  3. Click Next.
  4. Click Browse next to the Select root directory field.

    This opens the Browse For Folder dialog box.

  5. Navigate to the Eclipse\jvm_cobol\AddressBookDemo\addressBookWrapperTest folder in the samples directory installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples.
  6. Click OK.
  7. In the Projects list, ensure that the addressBookWrapperTest is checked.
  8. Check the Copy projects into workspace.
  9. Click Finish.
Note: You need to add the COBOL JVM Runtime System to the projects libraries to run the tests.
Parent topic: Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
Previous topic: Creating a Project to Expose the Record Functions
Next topic: Creating a Project to Handle the User Interface


Creating a Project to Handle the User Interface

You will import a project that uses the JavaFX library to implement a user interface:

Importing the addressBookFX project

To import the project:

  1. Click File > Import.

    This opens the Import dialog box.

  2. Click General > Existing Projects into Workspace.
  3. Click Next.
  4. Click Browse next to the Select root directory field.

    This opens the Browse For Folder dialog box.

  5. Navigate to the Eclipse\jvm_cobol\AddressBookDemo folder in the samples directory installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples.
  6. Click OK.
  7. In the Projects list, ensure that just the addressBookFX is checked.
  8. Click Copy projects into workspace.
  9. Click Finish.

Add the COBOL JVM Runtime System

Ensure that the COBOL JVM Runtime System has been added to the addressBookFX project's Java Build Path libraries:

  1. In COBOL Explorer, right-click addressBookFX, and then click Properties.

    This opens the Properties for addressBookFX dialog box.

  2. Click Java Build Path.
  3. Click the Libraries tab.
  4. Click Add Library.

    This opens the Add Library dialog box.

  5. Click COBOL JVM Runtime System.
  6. Click Next.
  7. Click Finish.
  8. Click Apply and Close.
Parent topic: Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
Previous topic: Creating a Java JUnit Testing Project
Next topic: Running the Application


Running the Application

To run the application:

  1. In the COBOL Explorer, right-click addressBookFX, and then click Run As > 1 Java Application

    This opens the Select Java Application dialog box.

  2. In the Matching items list, click MainClass - com.addressBookFX.
  3. Click OK.

    The Address Book COBOL Demo application is displayed. It should look similar to this:

    Address Book COBOL Demo

    You can now use the Add, Edit, and Delete commands to modify records.

Parent topic: Tutorial: Creating a JVM COBOL Application Using a JavaFX Interface
Previous topic: Creating a Project to Handle the User Interface


Tutorial: Packaging JVM COBOL

This tutorial walks you through the steps required to compile and package JVM COBOL so that it can be used as a library in another project.

This tutorial assumes that you have COBOL JVM projects that you want to expose to a Java project in the form of a jar dependency.

Note: All projects discussed in this tutorial are available in the samples folder %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples.

Prerequisites

You must install the following:

  • Enterprise Developer for Eclipse.
  • Java JDK 1.8.0, the JDK is used by the specified version of Ant.
  • Apache Ant 1.10.2, Apache Ant is used to build Java applications.

Apache Ant

To download Apache Ant 1.10.2:

  1. Click here, in the left pane click Binary Distributions.
  2. Click apache-ant-1.10.2-bin.zip to download.
  3. Extract the content of the zip file to a new folder.
  1. Customizing the COBOL Perspective
  2. Importing the Projects
  3. Creating a JAR File Output Folder
  4. Building the AddressBookJVM and AddressBookWrapper Projects
  5. Updating the addressBookFX Project to use .jar Files and COBOL JVM Runtime
  6. Running the Application
  7. Packaging the JVM COBOL Application from the Command Line
Parent topic: Managed COBOL Tutorials


Customizing the COBOL Perspective

In this tutorial you will use the COBOL perspective:

To use the COBOL perspective

To change to the COBOL perspective:

  1. Click Window > Perspective > Open Persepective > Other.

    This opens the Open Perspective dialog box.

  2. Click COBOL.
  3. Click Open.

To customize the COBOL perspective

You need to customize the filters on the COBOL Explorer to ensure that all the projects are displayed:

  1. In the COBOL Explorer, click View Menu View Menu, and then click Filters and Customization.

    This opens the Filters and Customization dialog box.

  2. In the Filters tab, uncheck , Non-COBOL projects.
  3. Click OK.
Parent topic: Tutorial: Packaging JVM COBOL
Next topic: Importing the Projects


Importing the Projects

You start by importing three projects that can be found in the samples folder installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples:

  1. Click File > Import.

    This opens the Import dialog box.

  2. Click General > Existing Projects into Workspace.
  3. Click Next.
  4. Click Browse next to the Select root directory field.

    This opens the Browse For Folder dialog box.

  5. Navigate to the Eclipse\jvm_cobol\AddressBookDemo folder in the samples directory installed with Enterprise Developer, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples.
  6. Click OK.
  7. In the Projects list, ensure that just the following projects are checked:
    • addressBookFX
    • addressBookJVM
    • addressBookWrapper
  8. Click Copy projects into workspace.
  9. Click Finish.
Parent topic: Tutorial: Packaging JVM COBOL
Previous topic: Customizing the COBOL Perspective
Next topic: Creating a JAR File Output Folder


Creating a JAR File Output Folder

Create a folder to be used as a JAR output folder. The JARs will be created by a build at a later point:

  1. In the COBOL Explorer, right-click the addressBookFX project, and then click New > Folder.

    This opens the New Folder dialog box.

  2. In the Folder name field, type lib.
  3. Click Finish.
  4. In the COBOL Explorer, right-click the addressBookJVM project, and then click Properties.

    This opens the Properties for addressBookJVM dialog box.

  5. Click Micro Focus > Packaging Configuration.

    This displays the Packaging Configuration options in the right pane.

  6. Check Create packaging target in the build script.
  7. Check Create JAR file after build.
  8. Click Apply and Close.
  9. Repeat steps 4 through 8 for the addressBookWrapper project.
Parent topic: Tutorial: Packaging JVM COBOL
Previous topic: Importing the Projects
Next topic: Building the AddressBookJVM and AddressBookWrapper Projects


Building the AddressBookJVM and AddressBookWrapper Projects

Build the addressBookJVM and addressBookWrapper projects. If your projects are set to build automatically then the following files are create in the dist folders:

  • addressbookjvm.jar - in the addressBookJVM project.
  • addressbookwrapper.jar - in the addressBookWrapper project.

Otherwise:

  1. Click the project to be built.
  2. Click Project > Build Project.

    This creates the files in the dist folder.

Copy the two .jar files into the lib folder of the addressBookFX project.

Parent topic: Tutorial: Packaging JVM COBOL
Previous topic: Creating a JAR File Output Folder
Next topic: Updating the addressBookFX Project to use .jar Files and COBOL JVM Runtime


Updating the addressBookFX Project to use .jar Files and COBOL JVM Runtime

  1. In the COBOL Explorer, right-click addressBookFX.
  2. Click Properties.

    This opens the Properties for addressBookFX dialog box.

  3. Click Java Build Path.
  4. In the Projects tab, click addressBookWrapper.
  5. Click Remove.
  6. In the Libraries tab, click Add Library.

    This opens the Add Library dialog box.

  7. Click COBOL JVM Runtime System, and then click Next.
  8. Click Finish.

    This adds the COBOL JVM Runtime System to the build path.

  9. Click Add JARs.

    This opens the JAR Selection dialog box.

  10. Expand addressBookFX > lib.
  11. While pressing Ctrl, click addressbookjvm.jar and addressbookwrapper.jar.
  12. Click OK.
  13. Click Apply and Close.
Parent topic: Tutorial: Packaging JVM COBOL
Previous topic: Building the AddressBookJVM and AddressBookWrapper Projects
Next topic: Running the Application


Running the Application

To run the application:

  1. In the COBOL Explorer, right-click addressBookFX, and then click Run As > 1 Java Application

    This opens the Select Java Application dialog box.

  2. In the Matching items list, click MainClass - com.addressBookFX.
  3. Click OK.

    The Address Book COBOL Demo application is displayed. It should look similar to this:

    Address Book COBOL Demo

    You can now use the Add, Edit, and Delete commands to modify records.

Parent topic: Tutorial: Packaging JVM COBOL
Previous topic: Updating the addressBookFX Project to use .jar Files and COBOL JVM Runtime
Next topic: Packaging the JVM COBOL Application from the Command Line


Packaging the JVM COBOL Application from the Command Line

The build.xml file provides instructions to build the product, the build target, and to package it, the create_jar target.

  1. If a build.xml file does not already exist in the root of the addressBookJVM project then create it:
    1. Click the addressBookFX project.
    2. Click File > New > Other

      This opens the New dialog box.

    3. Click XML > XML File, and then click Next.

      This opens the New XML File dialog box.

    4. In the File name field, type build.xml.
    5. Click Finish.
  2. If a build.xml file does not already exist in the root of the addressBookWrapper project then create it.

    Use the above steps, a through e.

  3. If a build.xml file does not already exist in the root of the addressBookFX project then create it.

    Use the above steps, a through e.

Prepare the environment to be compiled:

  1. Click Start > Micro Focus Enterprise Developer > Enterprise Developer Command Prompt (32-bit) or Enterprise Developer Command Prompt (64-bit).
    This opens the command prompt.
    Note: This path is for Windows 10. The path may vary between versions of Windows. See To start Enterprise Developer command prompt for more information.
  2. Set the JAVA_HOME environment variable to point at Java JDK 1.8.0, at the command prompt, enter:
    set JAVA_HOME=java_installation_folder
  3. Add the path to the Java JDK installation to the PATH environment variable, at the command prompt, enter:
    set PATH=%JAVA_HOME%\bin;%PATH%
  4. Set the ANT_HOME environment variable to points to the Ant installation folder, at the command prompt, enter:
    set ANT_HOME=ant_installation_folder
  5. Add the path to the Ant installation to the PATH environment variable, at the command prompt, enter:
    set PATH=%ANT_HOME%\bin;%PATH%
  6. Set the mfant.jar to be used. This is required to compile JVM COBOL projects.

    Ensure that mfant.jar is in your CLASSPATH variable, if not then enter:

    set CLASSPATH=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar;%CLASSPATH%

    Alternatively, add the following parameter when calling ant:

    -lib "%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar"
  7. You need to compile the three projects in the order addressBookJVM, addressBookWrapper, and addressBookFX. In the command prompt, change your folder location to match the workspace path. To compile the addressBookJVM project, at the command prompt, enter:
    ant -f addressBookJVM\build.xml

    This builds the addressBookJVM project. You will see BUILD SUCCESSFUL displayed in the command prompt. It creates the addressbookjvm.jar in the dist folder.

  8. To compile the addressBookWrapper project, at the command prompt, enter:
    ant -f addressBookWrapper\build.xml

    This creates the addressbookwrapper.jar in the dist folder.

  9. To compile the addressBookFX project, at the command prompt, enter:
    ant -f addressBookFX\build.xml

    Creates the dist folder and the addressbookfx.jar is added.

  10. Add the three jar files that you have created to the CLASSPATH. At the command prompt, enter:
    set CLASSPATH=%CD%\addressBookFX\dist\addressbookfx.jar;%CD%\addressBookWrapper\dist\addressbookwrapper.jar;%CD%\addressBookJVM\dist\addressbookjvm.jar;%CLASSPATH%
  11. You can now run the application from the command prompt, enter:
    java com.addressBookFX.MainClass

    The Address Book COBOL Demo application is displayed. It should look similar to this:

    Address Book COBOL Demo

    You can now use the Add, Edit, and Delete commands to modify records.

Parent topic: Tutorial: Packaging JVM COBOL
Previous topic: Running the Application


Tutorial: Compiling a COBOL Program to JVM Byte Code

This tutorial takes you through the creation of a simple COBOL program and its subsequent use from a Java project in Enterprise Developer for the Eclipse IDE.

Prerequisites

You must have installed Enterprise Developer for Eclipse. There are no other prerequisites.

  1. Customizing the COBOL Perspective
  2. Creating a COBOL JVM Project
  3. Creating a Java Project to Use the Application From
  4. Running the Application
Parent topic: Managed COBOL Tutorials


Customizing the COBOL Perspective

In this tutorial you will use the COBOL perspective:

To use the COBOL perspective

To change to the COBOL perspective:

  1. Click Window > Perspective > Open Persepective > Other.

    This opens the Open Perspective dialog box.

  2. Click COBOL.
  3. Click Open.

To customize the COBOL perspective

To correctly view the projects that you create you need to customize the COBOL Explorer view:

  1. In the COBOL Explorer, click View Menu View Menu, and then click Filters and Customization.

    This opens the Filters and Customizations dialog box.

  2. In the Filters tab, uncheck Non-COBOL projects.
  3. Click OK.
Parent topic: Tutorial: Compiling a COBOL Program to JVM Byte Code
Next topic: Creating a COBOL JVM Project


Creating a COBOL JVM Project

To create a new COBOL JVM Project:

  1. Click File > New > COBOL JVM Project.

    This opens the New COBOL JVM Project dialog box.

  2. In the Project name field, type CJVM.
  3. Click Finish.
  1. Creating a New Package
  2. Creating a COBOL Program
Parent topic: Tutorial: Compiling a COBOL Program to JVM Byte Code
Previous topic: Customizing the COBOL Perspective
Next topic: Creating a Java Project to Use the Application From


Creating a New Package

To create a new package:

  1. In the COBOL Explorer, right-click the CJVM project.
  2. Click New > COBOL JVM Package.
    This opens the New COBOL JVM Package dialog box.
    Note: The Source folder field already contains CJVM/src.
  3. In the Name field, type my.pack.
  4. Click Finish.

    This creates my.pack in the src folder.

Parent topic: Creating a COBOL JVM Project
Next topic: Creating a COBOL Program


Creating a COBOL Program

Create the following COBOL program in the my.pack package:

  1. In the COBOL Explorer, expand CJVM > src.
  2. Right-click my.pack.
  3. Click New > COBOL Program.

    This opens the New COBOL Program dialog box. The Source folder field already contains CJVM/src. The Package field already contains my.pack.

  4. In the Name field, type Calculator.cbl.
  5. Click Finish.

    This opens the Calculator.cbl program in a COBOL editor.

  6. Copy and paste the following COBOL code into the editor, overwriting the existing text:
           $set ilnamespace "my.pack"
       program-id. Calculator as "Calculator".

       data division.
       working-storage section.

       linkage section.
       01 lnk-arg1           pic 9(5) comp-3.
       01 lnk-arg2           pic 9(5) comp-3.
       01 lnk-sum            pic 9(5) comp-3.

       procedure division using by value lnk-arg1,
                                by value lnk-arg2,
                                by value lnk-sum.
           add lnk-arg1 to lnk-arg2 giving lnk-sum.
           goback.

       end program Calculator.
    Note: The use of $set ilnamespace "my.pack", is equivalent to package identification in Java.
    Tip: It is good practice to create a package structure of your preference.
    Restriction: Files that are compiled into a default package are not accessible from Java due to compiler restrictions.
Parent topic: Creating a COBOL JVM Project
Previous topic: Creating a New Package


Creating a Java Project to Use the Application From

To create the Java project you intend to use the application from:

  1. In the COBOL Explorer, click File > New > Other.
  2. Click Java > Java Project.
  3. Click Next.

    This opens the New Java Project dialog box.

  4. In the Project name field, type Calc.
  5. Click Use default JRE.
  6. Click Finish.

    When you are prompted to open the associated perspective, click No.

  1. Updating the Project's Dependencies
  2. Creating a New Class to Contain the Main Method
  3. Using the COBOL Program from Java
Parent topic: Tutorial: Compiling a COBOL Program to JVM Byte Code
Previous topic: Creating a COBOL JVM Project
Next topic: Running the Application


Updating the Project's Dependencies

In order to see the JVM COBOL code during development, update the project's dependencies:

  1. In COBOL Explorer, right-click the Calc project.
  2. Click Properties.

    This opens the Properties for Calc dialog box.

  3. Click Java Build Path.
  4. Click the Projects tab.
  5. Click Classpath, and then click Add.

    This opens the Required Project Selection dialog box.

  6. Check the CJVM project.
  7. Click OK.
  8. Click Apply and Close.
Parent topic: Creating a Java Project to Use the Application From
Next topic: Creating a New Class to Contain the Main Method


Creating a New Class to Contain the Main Method

You now need to create a new class file to contain the main method:

  1. Click the Calc project, and then click File > New > Other.

    This opens the New dialog box.

  2. Click Class.
  3. Click Next.

    This opens the New Java Class dialog box.

  4. In the Package field, type com.calc
  5. In the Name field, type MainClass.
  6. Click Finish.

    This opens the MainClass.java in an editor.

  7. You can now import the my.pack.Calculator class and access it from this Java project. Copy and paste the following code into the editor, overwriting the existing text:
    package com.calc;

import my.pack.Calculator;

public class MainClass {

    public static void main(String[] args) {
        Calculator calc = new Calculator();
        int result = 0;
        calc.Calculator(1,2,result);
        System.out.println(result);
    }

}
  8. The Calculator class has a method that correspond to the procedure divisions in the Calculator.cbl program:
    long my.pack.Calculator.Calculator(int lnk-arg1, int lnk-arg2, int lnk-sum)
    The result variable will always be equal to 0 because it uses the by value option for the lnk-sum argument in the procedure division of the Calculator.cbl program. To get a return value, set the variable used for result to be passed as by reference. Modify the procedure division in the Calculator.cbl file to:
           procedure division using by value lnk-arg1,
                                by value lnk-arg2,
                                by reference lnk-sum.
  9. At this point you get a problem marker with a description saying The type com.microfocus.cobol.program.Reference cannot be resolved.. To resolve this, you need to add the COBOL JVM Runtime System library. Right-click the Calc project, and then click Properties > Java Build Path.
  10. Click the Libraries tab, and then click Classpath.
  11. Click Add Library.

    This opens the Add Library dialog box.

  12. Click COBOL JVM Runtime System, and then click Next.

    This displays the path to the runtime to be used.

  13. Click Finish.
  14. Click Apply and Close.
  15. Instead of a reference type, you can specify the ILSMARTLINKAGE directive. This exposes the linkage section and entry points to the managed code by creating types. In the Calculator.cbl file, on the first line at column 7, type:
    $set ILSMARTLINKAGE "my.pack"
    Note: The each $set must be on a newline.
    • Alternatively, you can add the directive to the project's build configuration:
      1. Right-click the CJVM project, and then click Properties > Micro Focus > Build Configuration.
      2. In the Additional directives field, type ILSMARTLINKAGE “my.pack”.
      3. Click Apply and Close.
      Note: Using this method applies the directive to all programs in the project.
    Using this directive results in a new class being created, called LnkSum, which is created in the my.pack package. You can see this in the COBOL Explorer by expanding the Calculator.cbl file:
    LnkSum
  16. The calculator's method now requires the following signature:
    (int lnk-arg1, int lnk-arg2, LnkSum my.pack.LnkSum)
    Modify the main method in the MainClass.java file:
        public static void main(String[] args) {
        Calculator calc = new Calculator();
        LnkSum sum = new LnkSum();
        calc.Calculator(1,2,sum);
        System.out.println(sum.getLnkSum());
    }
    Also, ensure that you add the following import:
    import my.pack.LnkSum;
Parent topic: Creating a Java Project to Use the Application From
Previous topic: Updating the Project's Dependencies
Next topic: Using the COBOL Program from Java


Using the COBOL Program from Java

You can use the ILCUTPREFIX directive to remove a specified prefix from the COBOL data items. In this case, you can use it to remove the Lnk prefix. This results in the class becoming Sum. To do this insert the following line at the top of the Calculator.cbl program:
$set ILCUTPREFIX "lnk-"

You can also use ILSMARTNEST, in conjunction with ILSMARTLINKAGE directive, to manage code as nested classes of the program class in which they are defined. In this case, it results in the LnkSum class becoming an internal class inside the Calculator class (my.pack.Calculator.LnkSum).

The default option for input arguments is by reference. If both by value and by reference are omitted then the Compiler accepts the arguments as by reference type.

To simplify the method signature you can group the arguments together. Your Calculator.cbl program should now look like:

       $set ilsmartlinkage "my.pack"
       $set ilnamespace "my.pack"
       $set ilcutprefix "lnk-"
       program-id. Calculator as "Calculator".

       data division.
       working-storage section.

       linkage section.
       01 args
           03 lnk-arg1           pic 9(5) comp-3.
           03 lnk-arg2           pic 9(5) comp-3.
           03 lnk-sum            pic 9(5) comp-3.

       procedure division using args.
           add lnk-arg1 to lnk-arg2 giving lnk-sum.
           goback.

       end program Calculator.

Your MainClass.java should now look like:

package com.calc;

import my.pack.Calculator;
import my.pack.Args;

public class MainClass {

    public static void main(String[] args) {
        Calculator calc = new Calculator();
        Args arguments = new Args();
        arguments.setArg1(4);
        arguments.setArg2(2);
        calc.Calculator(arguments);
        System.out.println(arguments.getSum());
    }
}
Parent topic: Creating a Java Project to Use the Application From
Previous topic: Creating a New Class to Contain the Main Method


Running the Application

To run the application:

  1. In the COBOL Explorer, right-click the Calc project.
  2. Click Run As > 1 Java Application.

    This opens the Select Java Application dialog box.

  3. Click MainClass.
  4. Click OK.

    In the Console tab, the result of the calculation is displayed (6).

Parent topic: Tutorial: Compiling a COBOL Program to JVM Byte Code
Previous topic: Creating a Java Project to Use the Application From


Web Services Tutorials

  • Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
  • Tutorial: Reusing Existing SQL Programs in a Java Environment
    As an extension to Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment, this tutorial shows you how to do the same thing with an SQL COBOL application using SQL Server and the Tomcat 7 application server. Additional information regarding DB2 LUW and Oracle applications is also provided.
Parent topic: Getting Started


Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment

  1. Introduction
  2. Tutorial Project Goals
  3. Setting Up the Tutorial Environment
  4. Copying the Tutorial Files
    To enable you to work through this tutorial, you need to download the sample files from the Micro Focus Community Web site. The download contains all the files you need to complete the tutorial.
  5. Creating the COBOL Components
  6. Creating the Java Components
  7. Running and debugging
  8. Summary
    Tutorial summary.
Parent topic: Web Services Tutorials
Related concepts
Tutorial: Reusing Existing SQL Programs in a Java Environment


Introduction

With the advent of the World Wide Web and modern programming languages such as Java, the on-going importance of COBOL is sometimes misunderstood in today's culture of mobile technology. This tutorial shows how you can protect the investment in your COBOL business logic in a low-cost, risk-free manner.

Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Next topic: Tutorial Project Goals


Tutorial Project Goals

The goal of this tutorial is to show you how to invoke an existing COBOL program in a Java environment.

In this tutorial, you will learn how to:
  • Install supplementary software for the server runtime and web projects.
  • Obtain the COBOL and Java tutorial files.
  • Compile a legacy COBOL program in an Eclipse project.
  • Create the various Java components in the dynamic web project that drives the COBOL program.
  • Configure Java to recognize the COBOL JVM runtime.
  • Run and debug both the COBOL and Java elements using Eclipse.

Skills Requirements

To succeed with this tutorial, you need a basic understanding of COBOL and Java programming. A good knowledge of the Eclipse IDE will help as well - see Introduction to Eclipse.

Audience

This tutorial is intended for COBOL programmers who wish to modernize their legacy systems using Java in a web-based environment.

System Requirements

Before running this tutorial, you need to have the following software installed:
  • A Java Enterprise Edition server. The tutorial explains how to obtain and install a server.

Expectations

On completion of this tutorial, you will have gained experience of using Enterprise Developer for Eclipse to compile, run and debug a COBOL program in a web-based Java environment, thereby assisting you to modernize your current systems. In addition, you will have an understanding of the workings of the Micro Focus Run Unit Manager and the Micro Focus smart linkage facility.

Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Previous topic: Introduction
Next topic: Setting Up the Tutorial Environment


Setting Up the Tutorial Environment

Before you can run the tutorial, you must download and install some additional software and the tutorial files. The following sections describe the tasks you need to perform to do this. Once you complete these tasks, the tutorial is ready to use.

Installing a Java Server

You install a Java Enterprise Edition (JEE) server or servlet container so that the Micro Focus JVM COBOL runtime, under which your COBOL program runs, may be mapped to the server. Subsequently, your COBOL program is accessible in that environment.

Enterprise Developer includes the Web Tools Platform (WTP), which is a component of Eclipse that is designed for the creation of web applications. In particular, it has support for the JEE stack. Micro Focus COBOL JVM projects can interact with the WTP to expose COBOL functionality in JEE Web services.

Upon completion of the Java server installation, you will have the ability to create a dynamic web project.

Before You Begin

Determine which Java server or servlet container to install. You need install only one, and you need to choose which server best suits your requirements. The Micro Focus JVM COBOL runtime supports many of these: refer to the Application server support for JVM COBOL section of the Additional Software Requirements topic for your platform.

Note: The server selected might require a specific version of Java to run correctly. See Additional Software Requirements for more information.

If you are new to Java, Micro Focus recommends that you choose Apache Tomcat, as it is a lightweight, open-source servlet container.

Support for other servers is also included, but is not detailed here. If you wish to install an alternate server, you will need to refer to the external supplier's documentation. In addition, you may need to configure your projects differently.

Your projects must target that same Java version used by the server you choose. By default, this tutorial uses Java 8 which is provided with Enterprise Developer:

  • Installing Apache Tomcat
    This section details the steps you take to install Apache Tomcat version 7.
  • Installing JBoss Enterprise Application Platform
    This section details the steps you take to install JBoss Enterprise Application Platform (EAP).
  • Installing the IBM WebSphere Plug-in
    This section details the steps you take to install the IBM WebSphere server plug-in.
  • Installing the Oracle WebLogic Plug-in
    This section details the steps you take to install the Oracle WebLogic server plug-in.
Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Previous topic: Tutorial Project Goals
Next topic: Copying the Tutorial Files
Related reference
Additional Software Requirements (Development products Windows)
Additional Software Requirements (Hub Unix)


Installing Apache Tomcat

This section details the steps you take to install Apache Tomcat version 7.
Procedure
  1. Create a new folder on your computer (for example, C:\Tomcat (Windows) or ~/tomcat/ (UNIX)).
  2. You need to install Apache Tomcat - click here to download the software. If the link fails, do a web search for "apache tomcat 7 download".
  3. Navigate to the Binary Distributions - Core section and click on 32-bit Windows zip or 64-bit Windows zip depending on your OS (Windows), or zip or tar.gz (UNIX).
  4. Extract the distribution files into the folder created in step 1.
    Note: Ensure that the option to retain folder names is selected.
On UNIX and Linux platforms no further action is required at this stage, but on Windows you need to register the service. Do this by taking the following steps:
  1. Launch a command prompt (cmd.exe) with administrator privileges.
  2. Change to the bin folder of your Apache Tomcat installation (for example, C:\Tomcat\InstalledVersionPath\bin, where InstalledVersionPath is the folder name of the installed version from the zip file).
  3. Before you run the next command, you need to set either of these environment variables: JRE_HOME or JAVA_HOME. Micro Focus suggests that you set JRE_HOME, and ensure that it points to your Java Runtime Environment (JRE) folder. Typically, in a 32-bit system, the command is:
    set JRE_HOME=C:\Program Files (x86)\Java\jre7
    Note: Ensure that the file path is not enclosed in quotation marks.
  4. Register the service with the command:
    service.bat install
Parent topic: Setting Up the Tutorial Environment


Installing JBoss Enterprise Application Platform

This section details the steps you take to install JBoss Enterprise Application Platform (EAP).

Download and install JBoss

  1. In a browser, open the 3.3. DOWNLOAD AND INSTALL JBOSS EAP USING THE ZIP page located on the Red Hat Web site.
  2. Follow the instructions provided to download and install the Red Hat JBoss Enterprise Application Platform. For a list of supported versions, see Additional Software Requirements.
    Note: This download might require a Red Hat subscription.

Install JBOSS tools plugins in Eclipse

To enable Eclipse to manage JBoss Application Server, you need to install the JBoss tools plugin in Eclipse:

  1. Start Eclipse.
  2. Click Help > Eclipse Marketplace

    This opens the Eclipse Marketplace dialog box.

  3. In the Find field, type JBoss Tools, and then press Enter.
  4. Find the JBoss Tools 4.5.3.Final plugin in the returned results list, and then click Install.
  5. In the Confirm Selected Features page, click Confirm.
  6. Accept the license agreement, and then click Finish.

    If you receive a security warning, click Install anyway.

  7. When prompted to restart Eclipse, click Restart Now.
    Note: If this is the first time the workspace settings have been changed then Eclipse might prompt you to store preference information.

Install JBOSS AS tools in Eclipse

To enable Eclipse to manage JBoss Application Server, you need to add the server runtime environment:

  1. Click Window > Preferences > Server > Runtime Environments.
  2. Click Add.

    This opens the New Server Runtime Environment dialog box.

  3. Expand Red Hat JBoss Middleware, and then click Red Hat JBoss Enterprise Application Platform 7.1 Runtime.
  4. Click Next.

    This opens the New Server Runtime Environment dialog box.

  5. Next to the Home Directory field, click Browse, and then select the folder containing JBoss EAP.
  6. Click OK.
  7. Ensure that you are using a Java 8 JRE runtime.
  8. Click Finish.
  9. Click Apply and Close.
Parent topic: Setting Up the Tutorial Environment
Related concepts
Additional Software Requirements on Windows


Installing the IBM WebSphere Plug-in

Installation

The Eclipse Web Tools Platform (WTP) has support for only a limited number of deployment targets by default. To enable the use of IBM WebSphere with JVM COBOL Web services, you need to install a plug-in, which is available via the Eclipse Marketplace. To install the plug-in:

  1. Launch an instance of Eclipse.
  2. Click Help > Eclipse Marketplace.
  3. In the Find field, type IBM WebSphere Application Server and press Enter.
  4. Click Install next to the adapter called IBM WebSphere Application Server v8.5 Developer Tools for Oxygen.
  5. On the Confirm Selected Features page, click Confirm.
  6. On the Review Licenses page, accept the license agreement, then click Finish.

    The WebSphere Developer Tools are installed for Eclipse.

  7. Click Yes when prompted to restart Eclipse, to finish the installation.

You now have the ability to create a dynamic web project, which links to an IBM WebSphere server instance.

Note: This is not a full installation of IBM WebSphere; it simply allows you to enable WebSphere with JVM COBOL Web services. The full installation of IBM WebSphere is beyond the scope of this tutorial.
Parent topic: Setting Up the Tutorial Environment


Installing the Oracle WebLogic Plug-in

Installation

The Eclipse Web Tools Platform (WTP) has support for only a limited number of deployment targets by default. To enable the use of Oracle WebLogic with JVM COBOL Web services, you need to install a plug-in, which is available via the Eclipse Marketplace. To install the plug-in:

  1. Launch an instance of Eclipse.
  2. Click Help > Eclipse Marketplace.
  3. In the Find box, type WebLogic and press Enter.
  4. Click Install next to the adapter called Oracle WebLogic Server Tools.
  5. On the Confirm Selected Features page, uncheck Oracle WebLogic Scripting Tools, and ensure Oracle WebLogic Server Tools is selected.
  6. Click Confirm.
  7. On the Review Licenses page, accept the license agreement, then click Finish.

    The WebSphere Developer Tools are installed for Eclipse.

  8. Click Restart Now when prompted to restart Eclipse, to finish the installation.

You now have the ability to create a dynamic web project, which links to an Oracle WebLogic server instance. If you cannot see the dynamic web project option, click Show All Wizards in the new project window. The software installation can sometimes disable certain project options, but you can enable them this way.

Note: This is not a full installation of Oracle WebLogic; it simply allows you to enable WebLogic with JVM COBOL Web services. The full installation of Oracle WebLogic is beyond the scope of this tutorial.
Parent topic: Setting Up the Tutorial Environment


Copying the Tutorial Files

To download your sample files:

  1. Create a folder to contain the sample files, for example, C:\myfiles (Windows) or ~/myfiles/ (UNIX)).
  2. You can download the sample files from the Micro Focus Community Web site, click here.
  3. Click Download.
  4. Extract all the files in the archive to the folder that you created in step 1.
    Note: The archive contains folder names for the tutorial files. You do not have to keep these folder names, as you will be creating the project from the start.
Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Previous topic: Setting Up the Tutorial Environment
Next topic: Creating the COBOL Components


Creating the COBOL Components

You now have a Java server and the tutorial files. In this section you learn how to build the COBOL components in a JVM COBOL project.
  1. Creating the JVM COBOL Project
  2. Creating the Copybook File
  3. Creating the COBOL Program
  4. Setting the COBOL Compiler Directives
  5. Adding the Data File
Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Previous topic: Copying the Tutorial Files
Next topic: Creating the Java Components


Creating the JVM COBOL Project

First you need to create a project to contain the procedural COBOL program, and make it available for execution from a Java program:
  1. Start Enterprise Developer for Eclipse.
  2. When prompted for the workspace name, type the name of a folder into which you wish to store the tutorial project (for example, C:\projects (Windows) or ~/projects/ (UNIX)).
  3. If you are presented with the Welcome page, click Open Team Developer Perspective.
  4. In the Application Explorer view, expand the Enterprise Developer node and click Enterprise Development Projects.
  5. Click File > New > Other.

    This opens the New dialog box.

  6. Click Micro Focus COBOL > COBOL JVM Project.
  7. Click Next.

    This opens the New COBOL JVM Project dialog box.

  8. Type CobolBook in the Project name field.
  9. In the JRE section, select a Java 8 JRE. If Java 8 JRE is not already available, click Configure JREs and add one.
  10. Click Finish.

This creates a JVM COBOL project to contain the sample procedural COBOL program that you will import into the Web application later in this tutorial.

Specifying a Java package

By default, COBOL programs are placed in the default root Java package. JVM servlet containers do not always allow root package classes to be loaded, so you must set up a package for the program.
Note: The Java package system is equivalent to the JVM COBOL namespace system; these two terms are interchangeable.
To set up the package:
  1. In the Application Explorer view, right-click the CobolBook project, and click New > Folder > COBOL JVM Package.

    This opens the New COBOL JVM Package dialog box.

  2. Type com.microfocus.book in the Name field. Click Finish to create the package.
    Note: To see the new folder structure in the Application Explorer view:
    1. Click View Menu > Filters and Customzation.

      This opens the Filters and Customization dialog box.

    2. Uncheck Empty folders outside categories.
    3. Click OK.

This process creates a folder structure in the workspace, in which to store the COBOL program, and informs Java where to find it. You are now ready to set up the COBOL program.

Parent topic: Creating the COBOL Components
Next topic: Creating the Copybook File


Creating the Copybook File

In this section you create a COBOL copybook. This file is created from the sample archive file that you downloaded previously.

  1. In the Application Explorer view, right-click the CobolBook project, and click New > File > COBOL Copybook.
  2. Ensure that the Containing project field contains CobolBook/src.
  3. Type book-rec.cpy in the New file name field. Click Finish to create the copybook.
  4. Replace the contents of the opened file with the downloaded copy of book-rec.cpy.
  5. Click File > Save.
Parent topic: Creating the COBOL Components
Previous topic: Creating the JVM COBOL Project
Next topic: Creating the COBOL Program


Creating the COBOL Program

In this section you create a COBOL program. This file is created from the sample archive file that you downloaded previously.
  1. Right-click the CobolBook project in Application Explorer view, and click New > File > COBOL Program.
  2. Ensure that the Source folder field contains CobolBook/src.
  3. Ensure that the Package field contains com.microfocus.book.
  4. Type book.cbl in the Name field. Click Finish to create the COBOL program.
  5. The file opens in the COBOL editor view with some skeleton text. Replace the entire contents of the program with the downloaded copy of book.cbl.
  6. Click File > Save. The project is built.

In addition to building the project, the compilation generates a class file, BookLegacy.class, which interacts with Java, and is located in the bin folder.

The bin folder is not the correct location, and, as such, the program will not execute successfully. You need to correct this problem by setting the COBOL Compiler directives.

Parent topic: Creating the COBOL Components
Previous topic: Creating the Copybook File
Next topic: Setting the COBOL Compiler Directives


Setting the COBOL Compiler Directives

The ILNAMESPACE Directive

COBOL Compiler directives are statements that determine how the program is compiled and behaves. To ensure that the program in the tutorial executes as expected, you need to set these. To do this, you need to:

  • Alter the program to specify the correct namespace as a qualified program name.
  • Alternatively, set a Compiler directive, either globally to the project or in the program using the $SET syntax.

For this tutorial you set a global Compiler directive.

You need to specify the ILNAMESPACE directive to ensure that you put the program in the right folder structure, and use the right package. When you import the program into Java, the namespace will then interact correctly with Java packages.

Procedure:
  1. In the Application Explorer view, right-click the CobolBook project, and then click Properties.
  2. Click Micro Focus > Build Configuration.
  3. Uncheck Each part of the package name corresponds to a subdirectory.
  4. In the Additional directives field, type:
    ilnamespace(com.microfocus.book)
  5. Click Apply and Close.

    The project is rebuilt.

Checkpoint:

This time, the COBOL program is built in the specified namespace. Observe that the file, BookLegacy.class, is now located in the bin/com/microfocus/book folder.

The ILSMARTLINKAGE Directive

In addition, you need to specify the ILSMARTLINKAGE directive to ensure that the linkage between the COBOL program and the Java code is handled correctly. The Micro Focus SmartLinkage tool converts between traditional COBOL group item types and Java types. For example, a field defined as PIC X(99) will be exposed as a Java STRING, and a COMP-5 field will become a Java int. This feature makes calling COBOL programs from Java much easier.

Procedure

  1. Repeat the steps you performed to specify the ILNAMESPACE directive, only this time add the following as another new line in the Additional directives field:
    ilsmartlinkage
  2. Click Apply and Close.

    The project is rebuilt.

Checkpoint

You will see additional files in bin/com/microfocus/book. These are LnkBDetails.class, LnkFilename.class, and LnkFileStatus.class. These are classes generated to represent the linkage items in the book.cbl program. The BookLegacy.class file will now have an entry point that takes these wrapper classes rather than just taking a generic reference class that gives direct byte access.

The ILCUTPREFIX Directive

Micro Focus recommends that you specify the ILCUTPREFIX directive. You use this directive to remove any prefixes that may be present in COBOL linkage section data-names. This feature ensures legibility in the generated code.

If you open book.cbl and press F4, you can see the contents of the copybooks in this program. If you navigate down to the linkage section there are group items lnk-filename, lnk-file-status, and lnk-b-details. These map directly onto the generated classes mentioned above.

Procedure

  1. Repeat the steps you performed to specify directives, only this time add the following lines in the Additional directives field:
    ilcutprefix(lnk-b-)
    and
    ilcutprefix(lnk-)
  2. Click Apply and Close.

    The project is rebuilt.

Checkpoint

Observe the class files in bin/com/microfocus/book. These files are now called Details.class, BookLegacy.class, and FileStatus.class. Note that the prefixes LnkB and Lnk are no longer present in the class filenames.

The JVMDECIMAL Directive

You need to specify the JVMDECIMAL directive. You use this directive to ensure that COBOL decimal data type is treated as an integer numeric item. The use of this directive is a result of specifying the ILSMARTLINKAGE directive.

Procedure

  1. Repeat the steps you performed to specify the ILNAMESPACE directive, only this time add the following as another new line in the Additional directives field:
    jvmdecimal(scaledinteger)
  2. Click Apply and Close.

    The project is rebuilt.

Parent topic: Creating the COBOL Components
Previous topic: Creating the COBOL Program
Next topic: Adding the Data File


Adding the Data File

The sample program, book.cbl, reads an indexed file to satisfy its I/O requests. You need to add this file to the project. It is located in the archive file that you downloaded previously.

Procedure

  1. In the Application Explorer view, right-click the CobolBook project, and then click Import.

    This opens the Import dialog box.

  2. Expand General, and click File System. Click Next.
  3. Click Browse against the From directory field to locate the folder containing the bookfile.dat file (for example, C:\myfiles\COBOL_JSP_2_2_SRC\CobolBook (Windows), or /home/myfiles/ (UNIX)). Click OK.
  4. Ensure that the entry for bookfile.dat is the only checked item. Click Finish.

    The file is added to the project.

This section completes the creation of the COBOL project.

Parent topic: Creating the COBOL Components
Previous topic: Setting the COBOL Compiler Directives


Creating the Java Components

Previously, you created a number of components in a COBOL JVM project. You are now ready to create your first Web application using Java, and specifically using Java Server Pages (JSP). In this section you learn how to build the Java components in a dynamic web project. In addition, you learn how to incorporate the COBOL components into the dynamic web project.

  1. Understanding Run Units and Sessions
  2. Creating the Dynamic Web Project
  3. Creating a JSP View
  4. Creating the Java Bean
  5. Converting Status Codes to Exceptions
  6. Creating a Session Management Class
  7. Creating the Servlet
  8. The Servlet Deployment Descriptor
Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Previous topic: Creating the COBOL Components
Next topic: Running and debugging


Understanding Run Units and Sessions

Before you delve into the fundamentals of Web applications, you need to understand the concept of Micro Focus run units and sessions.

Many COBOL applications are single-user programs, so adapting these programs into a multi-user Java environment can be problematic. You may experience a problem such as file locking or memory isolation breaking down because the same resource set is being used by many users. Often, fixing this contention requires a significant rewriting of code.

Micro Focus solves this with a construct called a run unit, and is specified by the JVM COBOL runtime class com.microfocus.cobol.runtimeservices.RunUnit. Each run unit is a new session object, and contains its own memory space and file lock table. A JVM COBOL program in one run unit will not normally access the memory of a program in another run unit. There is isolation between them. In addition, file locks are held for each run unit. If a program in one run unit holds a file lock, it will not be accessible to a file handling program in another run unit in the same process.

This feature is implemented using the concept of a Run Unit Manager. Each manager controls the life-cycle of run unit objects in Java environments with a notion of a session. A manager:

  • creates a run unit when a session starts
  • retrieves a run unit already attached to a session
  • ensures that a run unit is stopped and its resources cleaned up when a session ends

The class com.microfocus.cobol.runtimeservices.servlet.ServletRunUnitManager in the JVM COBOL runtime exists to handle the life-cycle of run units in the context of servlet API HttpSession objects.

Parent topic: Creating the Java Components
Next topic: Creating the Dynamic Web Project


Creating the Dynamic Web Project

Create a new project

As you will be using features such as servlets and JSP files in this tutorial, you need to create a dynamic web project to contain these resources. This is in contrast to a static web project that does not contain any dynamic content.

  1. Click File > New > Other.
  2. Expand the Web node and select Dynamic Web Project. Click Next.
  3. Enter JSPBookDemo in the Project name field.
  4. Ensure Use default location is selected.
  5. In the Target runtime field, either select an already existing servlet container runtime, or, if you have <None> showing, set one up as follows:
    1. Click New Runtime.
    2. You now need to choose the runtime of the Java servlet that you installed previously, then click Next:
      • Tomcat - Expand Apache, and select Apache Tomcat v7.0.
      • JBoss - Expand Red Hat JBoss Middleware, and select Red Hat JBoss Enterprise Application Platform 7.1 Runtime.
      • IBM - Select WebSphere Application Server v8.5 or later.
      • Oracle - Select Oracle WebLogic Server 12.1.1 or later.
    3. In the Home Directory (or Tomcat installation directory) field, click Browse and choose the location where you installed the servlet for Apache Tomcat, JBoss or IBM WebSphere, or enter the installation path for Oracle WebLogic.
    4. For Apache Tomcat or IBM WebSphere, select an appropriate JRE (usually the same one as the project).
    5. Click Finish.
  6. Set the Dynamic web module version to 2.5.
  7. Click Finish.

    Open the Java EE perspective if prompted to do so; all commands involving JSPBookDemo will be expected in the Java EE perspective.

Add appropriate references to the JVM COBOL project

You need to add a reference to the COBOL project in both the build options, so that the Java compiler can find the appropriate classes to build against, and in the deployment assembly, so that the JVM COBOL program will be exported into the created Web archive. To do this:

  1. In the Project Explorer, right-click the JSPBookDemo project, and then click Properties.
  2. Click Java Build Path, and then click the Projects tab.
  3. In the Required projects on the build path list, click Classpath.
  4. Click Add.

    This opens the Required Project Selection dialog box.

  5. Check the CobolBook project, and then click OK.
  6. Click the Libraries tab.
  7. In the JARs and class folders on the build path list, click Classpath.
  8. Click Add Library.

    This opens the Add Library dialog box.

  9. Click COBOL JVM Runtime System, and then click Next
  10. Click Finish.
  11. Click Apply.
  12. While you are still in the properties for JSPBookDemo, click Deployment Assembly.
  13. Click Add, then select Project, and click Next.
  14. On the next page click CobolBook, and then click Finish.

    This adds an entry to the Web Deployment Assembly list to indicate that the CobolBook project classes are included in the WEB-INF/lib directory of the Web archive. The project is also built.

  15. Click Add, then select Java Build Path Entries, and then click Next.
  16. On the next page, select COBOL JVM Runtime System, and then click Finish.
  17. Click Apply and Close to exit the project's properties dialog box. Once again, the project is built.

With these steps you created a dynamic Web project that incorporates your COBOL project.

Parent topic: Creating the Java Components
Previous topic: Understanding Run Units and Sessions
Next topic: Creating a JSP View


Creating a JSP View

Java Server Pages (JSPs) are a technology used to create dynamically generated web pages based on HTML, XML, or other document types. The standard way to create a view in a JSP application is to have a JSP that takes a Java bean, which is an ordinary Java data class, as an attribute. The JSP then inserts the properties from that bean into the appropriate places in the output HTML.

In this tutorial you now create a JSP view to map the book application.
  1. Expand the JSPBookDemo project, right-click the WebContent node, and click New > JSP File.
  2. Type BookJsp.jsp in the File name field.
  3. Click Finish.
  4. Overwrite the skeleton contents of the file with the BookJsp.jsp file that you downloaded previously (located in C:\myfiles\COBOL_JSP_DEMO_2_2_SRC\JSPBookDemo\WebContent).
  5. Click File > Save.

Comments

Examine the BookJsp.jsp file, and you will see several variables, which are elements that start with a $ sign and are enclosed in braces, for example ${book.stockno}. The example variable states that the JSP will insert the value contained in the stockno property of the book attribute at this point.

There are also other non-book variables, an example of which is ${rununitid}. These variables are more direct text attributes that are not directly related to a book entry, and are kept separate. In the case of ${rununitid}, the program is demonstrating its use in the title of the display.

Once all the variables have been processed, the JSP becomes a simple HTML page containing a form.

Parent topic: Creating the Java Components
Previous topic: Creating the Dynamic Web Project
Next topic: Creating the Java Bean


Creating the Java Bean

You now create a Java bean, which is associated with the view that you have just created.

  1. In Project Explorer, right-click Java Resources in the JSPBookDemo project, and select New > Class.
  2. Type com.microfocus.book in the Package field, and BookBean in the Name field.
  3. Click Finish to create the BookBean class file.
  4. Overwrite the skeleton contents of the file with the contents from the BookBean.java file that you downloaded previously (the file is stored in C:\myfiles\COBOL_JSP_DEMO_2_2_SRC\JSPBookDemo\src\com\microfocus\book).
  5. Click File > Save.

Comments

A bean is used to separate the business logic from the presentation logic, and a bean is simply an instance of a class. This class contains the information that will be displayed in the JSP view.

In this tutorial, at run time, the dispatching servlet binds an appropriate bean to the attribute "book" before calling the JSP. For example, in the book.stockno variable that was created previously in the JSP file, the JSP invokes the getStockno method on BookBean, and inserts the return value into the JSP output.

Parent topic: Creating the Java Components
Previous topic: Creating a JSP View
Next topic: Converting Status Codes to Exceptions


Converting Status Codes to Exceptions

Error handling in Java is different from procedural languages such as COBOL. Java uses exceptions, as opposed to error codes or status codes, to deal with failure and unexpected conditions. As the COBOL book tutorial program returns a status code, you need to convert this status code into a Java exception to make it suitable for the JVM.
  1. Create a new Java class using the same package as the bean, but call it JavaBookException.

    If you cannot remember how to create a new class, refer to the previous topic, Creating the Java Bean.

  2. Change the Superclass to java.lang.Exception.
  3. Click Finish to create the file.
  4. Overwrite the skeleton contents of the file with the contents of the JavaBookException.java file that you downloaded previously (the file is stored in C:\myfiles\COBOL_JSP_DEMO_2_2_SRC\JSPBookDemo\src\com\microfocus\book).
  5. Click File > Save.

Comments

In this Java code sample, note that there is a constructor that takes a string:
public JavaBookException(String statusCode)
The following string maps the file status field in the COBOL program:
01 ls-file-status   pic xx.
Using this statusCode construct, the Java program translates known COBOL status codes to appropriate error messages via its Map<String, String> construct, with a static string for any unknown error. Finally, the error exception is passed to the superclass constructor, and the status code is stored internally.
Note: The element serialVersionUId is used by the Java serialization mechanism to distinguish between different versions of a class, and it has no impact on the program.
Parent topic: Creating the Java Components
Previous topic: Creating the Java Bean
Next topic: Creating a Session Management Class


Creating a Session Management Class

This part of the tutorial details the most relevant class for invoking a JVM COBOL program from a JSP Web application. This class handles session management and integration into a Java environment. It also handles the interaction between the view bean (BookJsp.jsp) and the COBOL program's smart details linkage class, which was generated when you used the ILSMARTLINKAGE compiler directive previously.
  1. Create a new Java class as before. Put it in the com.microfocus.book package, and give it the name BookInterface.
  2. Overwrite the skeleton contents of the file with the BookInterface.java file that you downloaded previously (the file is stored in C:\myfiles\COBOL_JSP_DEMO_2_2_SRC\JSPBookDemo\src\com\microfocus\book).
  3. Click Edit > Find/Replace to find the BOOK_FILE definition:
    private static final String BOOK_FILE =
  4. Change the path to match the location of the bookfile.dat file that you downloaded previously.
    Note: Windows users must use a forward slash to delineate folder names; using a back slash results in an error.
  5. Click File > Save.

Specifying the Java Build Path

To ensure that the BookInterface.java does not contain errors you need to add the COBOL JVM runtime system library and the CobolBook project to the build path. To do this:

  1. In Project Explorer, right-click the JSPBookDemo project, and then click Properties.

    This opens the Properties for JSPBookDemo dialog box.

  2. Click Java Build Path, and then click the Projects tab.
  3. Click Add.

    This opens the Required Project Selection dialog box.

  4. Click CobolBook.
  5. Click OK.
  6. Click the Libraries tab, and then click Add Library.

    This opens the Add Library dialog box.

  7. Click COBOL JVM Runtime System, and then click Next.
  8. Click Finish.
  9. Click Apply and Close.

Comments

The sample code contains some important concepts, which are explained here. Note the two constructors listed below:

  public BookInterface(HttpSession session)
  {
    this(ServletRunUnitManager.getManager().GetSessionRunUnit(session));
  }

  public BookInterface(IRunUnit runUnit)
  {
    this.runUnit = runUnit;
    BookLegacy bookLegacy = (BookLegacy) runUnit.GetInstance(BookLegacy.class);

    if(bookLegacy == null)
    {
      bookLegacy = new BookLegacy();
      runUnit.Add(bookLegacy);
    }

    this.bookLegacy = bookLegacy;
  }
These constructors handle two separate functions:
  • The first constructor deals with the servlet's HTTP session object (HttpSession) and its run unit manager (ServletRunUnitManager).
  • The second constructor handles the linking of this interface class to a run unit, and gets the program instance of BookLegacy.
The interaction here is: get the ServletRunUnitManager (which is a singleton) and then call GetSessionRunUnit with the session object. The manager will create a run unit if this is the first call with this particular session. It will also manage the shutdown handling routines, so that when this session is invalidated the manager will call StopRun on the run unit attached to that session. In summary, this short section of code manages both program isolation and session life cycles.
Note also that the function parameter has been split into separate method calls:
public BookBean readBook(String stockNo) throws JavaBookException
public BookBean addBook(BookBean book) throws JavaBookException
public BookBean deleteBook(String stockNo) throws JavaBookException
public BookBean nextBook(String stockNo) throws JavaBookException
This style ensures compact and discrete functions, and is good coding practice.
Parent topic: Creating the Java Components
Previous topic: Converting Status Codes to Exceptions
Next topic: Creating the Servlet


Creating the Servlet

The servlet is the final Java class that you need to create for this tutorial. The servlet interprets the incoming POST and GET requests, and dispatches them to the correct interface method. The servlet also binds the output BookBean into the request, and forwards that request to the JSP for response.
  1. Create a new Java class as before. Put it in the com.microfocus.book package, and give it the name BookServlet.
  2. Overwrite the skeleton contents of the file with the BookServlet.java file that you downloaded previously (the file is stored in C:\myfiles\COBOL_JSP_DEMO_2_2_SRC\JSPBookDemo\src\com\microfocus\book).
  3. Click File > Save.

Comments

As before, the sample code contains some important concepts, which are explained here. There are four significant parts to the servlet class.
The interpretation of the POST parameters
The doProcessing method includes the following code
    String subValue = req.getParameter(SUBMIT_PARAMETER);

    ...

    if(subValue.equals(READ_PARAMETER))
    {
      performRead(req, res);
    }
    else if(subValue.equals(ADD_PARAMETER))
    {
      performAdd(req, res);
    }
    else if(subValue.equals(DELETE_PARAMETER))
    {
      performDelete(req, res);
    }

This code interprets the value of the submit parameter from the request object, and invokes the appropriate method in the application for each known request. An example of one of the methods is performRead, and is explained next.

The resulting calls into BookInterface
The performRead method contains the following code:
    BookInterface bookInterface = getBookInterface(req.getSession());
    String bookId = getStockNo(req, res);

    try
    {
      BookBean book = bookInterface.readBook(bookId);

      outputBook(req, res, book);
    }
    catch(JavaBookException e)
    {
      outputBookException(req, res, e);
    }
    catch (Exception e)
    {
      outputException(req, res, e);
    }

This code defines a BookInterface class by passing the session object from the request object to the constructor of BookInterface.java. Then it gets the stock number from the request parameters, and makes a call to readBook on the interface. Finally, it registers the BookBean object with the JSP by calling outputBook.

Binding an output BookBean into the request attributes
The outputBook method includes the following code:
private void outputBook(HttpServletRequest req, HttpServletResponse res,
      BookBean book)
    if(book != null)
    {
          req.setAttribute("book", book);
    }
    else
    {
          req.setAttribute("book", BookBean.msgBook("ERROR! book is null in output book"));
    }

This method binds the book as a request attribute to our JSP view, namely BookJsp.jsp. The JSP unpacks this book object and outputs its values.

Forwarding the request onto the JSP so it can create the response
The doProcessing method also contains the following code:
    RequestDispatcher dispatcher = getServletContext().getRequestDispatcher(VIEW_URL);
    try
    {
      dispatcher.forward(req, res);
    }
    catch(Exception e)
    {
      throw new RuntimeException(e);
    }

This method gets a dispatch object for the JSP view, and then forwards the request to it. With all the necessary attributes set up, the JSP view can output the book record correctly.

Parent topic: Creating the Java Components
Previous topic: Creating a Session Management Class
Next topic: The Servlet Deployment Descriptor


The Servlet Deployment Descriptor

The deployment descriptor is the file used by the servlet container to define which servlets match up with which URLs. It also defines which servlet or resource provides the landing page for the root of the service.

If it doesn't already exist, create the file web.xml in the JSPBookDemo project:
  1. Expand WebContent, right-click the WEB-INF folder in Project Explorer, and then click New > File.
  2. Type web.xml in the File name field, and click Finish.
    Note: If Finish is greyed out, check for the message 'web.xml' already exists, and click Cancel. Expand WEB-INF to locate the file.
  3. Open the file, and ensure it is in source mode by clicking the Source tab at the bottom left side of the XML Editor window.
  4. Overwrite the skeleton contents of the file with the web.xml file that you downloaded previously (the file is in C:\myfiles\COBOL_JSP_DEMO_2_2_SRC\JSPBookDemo\WebContent\WEB-INF). Perform this task even if the file exists.
  5. Save the file.
This is a deployment descriptor with the following elements:
<web-app>
Defines the specific version of the servlet API in use.
<display-name>
Defines the internal name of this web application that will appear in the servlet container management system.
<servlet>
Binds a name to a particular servlet class, in this case BookServlet.
<servlet-mapping>
Binds a particular servlet to a URL from the root of the servlet. As such, any call to localhost:8080/JSPBookDemo/view, for example, is directed to BookServlet.
<welcome-file-list>
Defines a set of files to use as the landing page for the servlet. In this case, the view is set to be the landing page.
Parent topic: Creating the Java Components
Previous topic: Creating the Servlet


Running and debugging

Run the application

Now that you have created and built the COBOL and Java programs in Eclipse projects, you can run the completed application.

To run the application:
  1. Ensure that you are in the Java EE perspective.
  2. Right-click on JSPBookDemo, and click Run As > Run on Server.

    Eclipse displays a window containing the servlet containers it knows about.

  3. Select the one you want to deploy to, which in this case is Apache Tomcat v7.0 Server, and click Finish.

    This action launches the servlet container, builds the Web application, and deploys it to the server. It then opens a Web page displaying the application.

  4. To test it, type 1111 in the Stock Number field, and click Read.

If you have followed the instructions carefully, and built the projects correctly, the system will respond by displaying the book Oliver Twist by Charles Dickens. If so, click End Session and proceed to the debug task.

If, for some reason, the application fails to deploy, you will need to retrace your steps and re-check what you have done. It may be necessary to start from the beginning.

Debug the application

Having successfully run the sample application, you can now use the debugger to control the execution of both the Java and COBOL code by setting breakpoints, step through the code, and examine the contents of variables.

  1. While in the JavaEE perspective, set some break points in the source files by double-clicking in the left hand margin of the editor next to a line you want to stop at. For example:
    • Set a break point in BookServlet.java in the performRead function
    • Set another in BookInterface.java in the readBook method
    • Set a third in book.cbl in the do-read-record section
  2. To launch the debugger, right-click on the JSPBookDemo project, and click Debug As > Debug on Server.
  3. If you are debugging immediately following running the application, the server is already running, and you need take no action. Otherwise, select the one you used for running the application previously. Click Finish.
  4. If you are asked to switch modes, click OK to do so.

    The web interface appears.

  5. Type 1111 in the Stock Number field, and click Read.
  6. Click Yes to confirm perspective switch.

    If you have set the break points as instructed, the debugger will stop in BookInterface.java in the readBook method.

  7. Press F6 to step through line by line.
  8. Press F8 to resume execution. The debugger stops at the break points that you selected, and eventually switches from Java code into the COBOL program.
  9. Press F6 to step over the open instruction.
  10. Hover over ls-file-status to examine its value.
  11. Click Run > Terminate to stop the session.

You have now completed the tutorial.

Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Previous topic: Creating the Java Components
Next topic: Summary


Summary

In this tutorial you have learned how to add a COBOL program to an Eclipse project, and build the program with appropriate compiler directives for use in a web-based environment. You then learned how to incorporate this COBOL project into a dynamic web project, in which you created a JSP and a bean as a view of the COBOL program. In addition, using the Micro Focus session management class you learned how to create a Java interface class to the COBOL program, a servlet and a deployment descriptor to drive the COBOL program in a web-based environment. Finally, you learned how to debug both the COBOL and Java code in Eclipse.

Parent topic: Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Previous topic: Running and debugging


Tutorial: Reusing Existing SQL Programs in a Java Environment

As an extension to Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment, this tutorial shows you how to do the same thing with an SQL COBOL application using SQL Server and the Tomcat 7 application server. Additional information regarding DB2 LUW and Oracle applications is also provided.

Prerequisites

This tutorial begins where Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment left off, using the Apache Tomcat application server, and the same CobolBook and JSPBookDemo projects. Therefore, you must complete that tutorial in its entirety, using the Tomcat 7 application server, before starting this tutorial. See Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment for complete instructions.

You must also install Microsoft SQL Server 2008 or later, configured for SQL Server authentication.

Outline

After completing the prerequisite tutorial, complete this tutorial by following the instructions in topics 1 through 6 in the order listed. These topics walk you through the demonstration using a SQL Server database. If you want to use a DB2 database, start with Modifications for DB2 LUW. To use an Oracle database, start with Modifications for Oracle.

  1. Install and Configure a JDBC Driver
    Download and install a SQL Server JDBC driver to use in this tutorial; then make the driver available to the Apache Tomcat application server.
  2. Create a SQL Server Database and Connection
    Create a SQL Server database, define a database connection to the database, and load the database using a provided SQL script.
  3. Modify COBOL Source
    Modify the COBOL source code in the CobolBook project, or replace the existing COBOL source with new code to access your SQL Server database.
  4. Modify Java Source
    Modify the Java source code in the JSPBookDemo project to access the SQL Server database.
  5. Add and Modify XML
    Create a new context.xml file, and modify the existing web.xml file.
  6. Run the JSP Application
    Run the JSPBookDemo application on Tomcat 7.
  7. Modifications for DB2 LUW
    Modifications to the tutorial for using a DB2 LUW database instead of a SQL Server database.
  8. Modifications for Oracle
    Modifications to the tutorial for using an Oracle database instead of a SQL Server database.
Parent topic: Web Services Tutorials
Related concepts
Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment


Install and Configure a JDBC Driver

Download and install a SQL Server JDBC driver to use in this tutorial; then make the driver available to the Apache Tomcat application server.

Install a JDBC Driver

As this tutorial uses SQL Server, you need a SQL Server-compatible JDBC driver. Download a Microsoft JDBC SQL Server Type 4 driver using this link, and install it using the Install Instructions on the download page:

Download JDBC Drivers

The name of the driver file is sqljdbc4[n].jar where n is a single digit and is appended to the filename for some versions of the driver. Be sure to take note of the location of this file after installing it.

Copy the JDBC Driver to Tomcat

To run your application, the Tomcat application server must find an SQL Server JDBC driver file in the Apache Tomcat installation lib subdirectory. To ensure that Tomcat finds the file there, copy the installed sqljdbc4[n].jar file to the lib subdirectory of your Apache Tomcat installation.

Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Next topic: Create a SQL Server Database and Connection


Create a SQL Server Database and Connection

Create a SQL Server database, define a database connection to the database, and load the database using a provided SQL script.

Create the PUBS SQL Server Database

Using SQL Server Management Studio, create a new SQL Server database, PUBS, on your local default instance of SQL Server, and configure it to use SQL Server authentication by providing a user ID and password. See your SQL Server documentation for instructions.

Start Enterprise Developer

If you have closed Enterprise Developer since completing Tutorial: Reusing Existing COBOL Programs in a Java Environment, open it again; then open the Java EE perspective and the Project Explorer.

Define a SQL Server Connection

Using the Data Source Explorer in Eclipse, create a JDBC connection to the SQL Server PUBS database.

  1. From the Main Menu, select Window > Show View > Other > Data Management > Data Source Explorer.
  2. In the Data Source Explorer, right-click Database Connections; then select New from the context menu.
  3. Select the SQL Server profile type from the list; then click Next.
  4. Click New Driver Definition New Database Connection.
  5. On the Name/Type tab, select the Microsoft SQL Server 2008 JDBC Driver template.
  6. In the Driver name field, type a unique name to identify the connection.
  7. On the JAR List tab, click Add JAR/Zip.
  8. Browse to the directory where the sqljdbc4.jar is installed; then double-click the file to select it.

    This places the full path and file onto the Driver files list.

  9. If the Driver files list contains an sqljdbc.jar file, select the file; then click Remove JAR/Zip.
  10. On the Properties tab complete the properties specifications as follows:
    Property | Value
    Connection URL | jdbc:sqlserver://localhost:1433;databaseName=PUBS
    Database Name | PUBS
    Driver Class | com.microsoft.sqlserver.jdbc.SQLServerDriver
    Password | SQLServerPassword
    User ID | SQLServerUserID

    Where SQLServerUserID and SQLServerPassword are the user ID and password you supplied for authentication when creating the PUBS SQL Server database.

  11. Click OK.

    This returns you to the New Connection Profile dialog box.

  12. Check Save password.
  13. Click Test Connection to verify the connection.
  14. When the connection succeeds, clear the message box; then click Finish to save the connection and close the New Connection Profile dialog box.

Add an SQL Script

We provide an SQL script for you to run against the PUBS database. This script creates the required table and loads it with data. Because you run the script from the Project Explorer, you must first add it to the project.

  1. In the Project Explorer, expand CobolBook.
  2. Right-click src; then select New > Other.
  3. Expand General; then select File.
  4. Click Next.
  5. In the File name field, type SetupSQLBooks.sql; then click Finish.

    This opens the empty SetupSQLBooks.sql file in the file editor.

  6. Copy the following SQL script and paste it into the SetupSQLBooks.sql file:
    USE PUBS;
GO

CREATE TABLE BOOKS (
    TITLE		VARCHAR(50) NOT NULL,
    TYPE		VARCHAR(20) NOT NULL,
    AUTHOR		VARCHAR(50) NOT NULL,
    STOCKNO 		CHAR(4) PRIMARY KEY,
    ISBN    		DECIMAL (13, 0) NOT NULL,
    RETAIL		DECIMAL(4,2) NOT NULL,
        ONHAND		INT NOT NULL,
        SOLD		INT NOT NULL
)

INSERT INTO BOOKS VALUES(
    'OLIVER TWIST',
    'CHARLES DICKENS',
    'CLASSIC',
    '1111',
    9780140620467,
    5.00,
    10,
    30
)

INSERT INTO BOOKS VALUES(
    'A GAME OF THRONES',
    'GEORGE R. R. MARTIN',
    'FANTASY',
    '1112',
    7428545,
    3.86,
    17,
    75
)

INSERT INTO BOOKS VALUES(
    'A CLASH OF KINGS',
    'GEORGE R. R. MARTIN',
    'FANTASY',
    '1113',
    7447833,
    6.49,
    17,
    75
)

INSERT INTO BOOKS VALUES(
    'THE DAY OF THE JACKAL',
    'FREDERICK FORSYTH',
    'ADVENTURE',
    '1114',
    99552710,
    2.00,
    26,
    75
)

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE PHILOSOPHER''S STONE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1116',
    747558191,
    5.24,
    48,
    100
)

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE CHAMBER OF SECRETS',
    'J. K. ROWLING',
    'ADVENTURE',
    '1117',
    747562180,
    5.24,
    44,
    100
)

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE PRISONER OF AZKABAN',
    'J. K. ROWLING',
    'ADVENTURE',
    '1118',
    747573760,
    5.24,
    49,
    100
)

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE GOBLET OF FIRE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1119',
    747582386,
    6.74,
    44,
    100
)

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE ORDER OF THE PHOENIX',
    'J. K. ROWLING',
    'ADVENTURE',
    '1120',
    747591261,
    6.74,
    37,
    100
)

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE HALF-BLOOD PRINCE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1121',
    747598460,
    6.74,
    41,
    100
)

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE DEATHLY HALLOWS',
    'J. K. ROWLING',
    'ADVENTURE',
    '1122',
    1408810298,
    6.74,
    40,
    100
)

INSERT INTO BOOKS VALUES(
    'THE FELLOWSHIP OF THE RING',
    'J. R. R. TOLKIEN',
    'FANTASY',
    '1123',
    7123825,
    4.95,
    23,
    100
)

INSERT INTO BOOKS VALUES(
    'THE TWO TOWERS',
    'J. R. R. TOLKIEN',
    'FANTASY',
    '1124',
    261102362,
    7.99,
    28,
    100
)

INSERT INTO BOOKS VALUES(
    'LORD OF THE FLIES',
    'WILLIAM GOLDING',
    'SCARY',
    '2222',
    9780571191475,
    4.50,
    30,
    100
)

INSERT INTO BOOKS VALUES(
    'CATCH 22',
    'JOSEPH HELLER',
    'WAR',
    '3333',
    9780099477310,
    6.50,
    50,
    200
)

INSERT INTO BOOKS VALUES(
    'THE HITCHHIKER''S GUIDE TO THE GALAXY',
    'DOUGLAS ADAMS',
    'COMEDY',
    '4444',
    9780345453747,
    6.73,
    100,
    360
)

INSERT INTO BOOKS VALUES(
    'TO KILL A MOCKINGBIRD',
    'HARPER LEE',
    'CLASSIC',
    '5555',
    9780099466734,
    4.87,
    50,
    75
)

SELECT * FROM BOOKS
  7. Click File > Save to save the SQL script.

Execute the SQL Script

  1. In the Eclipse file editor window that contains the SetupSQLBooks.sql file, use the drop-down list at the top to set the Type to SQL Server_2008.
  2. Select the name of your SQL Server connection from the Name drop-down list.
  3. Right-click on any blank area in the body of the script; then select Execute All from the context menu.
Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Previous topic: Install and Configure a JDBC Driver
Next topic: Modify COBOL Source


Modify COBOL Source

Modify the COBOL source code in the CobolBook project, or replace the existing COBOL source with new code to access your SQL Server database.

Replace book.cbl with sqlbook.cbl

  1. In the Project Explorer, expand CobolBook > src > (default package).
  2. Right-click book.cbl; then select Delete from the context menu.
  3. Click OK to delete the file.
  4. Again in the Project Explorer, right-click the src entry; then select New > Other.
  5. Expand General; then select File.
  6. Click Next.
  7. In the File name field, type sqlbook.cbl; then click Finish.

    This opens the empty sqlbook.cbl file in the file editor.

  8. Copy the following COBOL SQL program and paste it into the sqlbook.cbl file:
    ********************************************************************************************************
      *
      *  Copyright (C) Micro Focus IP Development Limited 2010-2011. All rights reserved.
      *
      *  This sample code is supplied for demonstration purposes only on an "as is" basis and "is for use at
      *  your own risk".
      *
      ********************************************************************************************************
      $set sql(dbman=jdbc, behavior=mainframe)
      $set SQL(JNDIENC=java:/comp/env)
       program-id. BookLegacy.

       working-storage section.

           exec sql include sqlca end-exec.

       01 record-count pic 99.

       linkage section.
       01 lnk-function       pic x.
           88 read-record    value "1".
           88 add-record     value "2".
           88 delete-record  value "3".
           88 next-record    value "4".
       01 lnk-sqlstate       pic x(5).
       01 lnk-sqlmessage     pic x(80).

       copy "book-rec.cpy" replacing ==(prefix)== by ==lnk-b==.

       procedure division using by value lnk-function
                                by reference lnk-b-details
                                by reference lnk-sqlstate
                                by reference lnk-sqlmessage.
       main section.

           exec sql connect to PUBS end-exec
           if sqlcode not >= 0
               move sqlstate to lnk-sqlstate
               move sqlerrmc(1:sqlerrml) to lnk-sqlmessage
               move 'Connection error' to lnk-b-title
               move sqlstate to lnk-b-author
               move '00000' to lnk-sqlstate
               move sqlerrmc(1:sqlerrml) to lnk-sqlmessage
               goback
           end-if

           evaluate true
               when read-record
                   perform do-read-record
               when add-record
                   perform do-add-record

               when delete-record
                   perform do-delete-record
               when next-record
                   perform do-next-record
           end-evaluate

           move sqlstate to lnk-sqlstate
           move sqlerrmc(1:sqlerrml) to lnk-sqlmessage

           exec sql disconnect end-exec

           exit program
           stop run
           .

       do-read-record section.

           evaluate true
                when lnk-b-stockno <> spaces
                    exec sql
                       select TITLE, TYPE, AUTHOR, STOCKNO, ISBN, RETAIL, ONHAND, SOLD
                           into :lnk-b-title, :lnk-b-type, :lnk-b-author, :lnk-b-stockno, :lnk-b-isbn, :lnk-b-retail, :lnk-b-onhand, :lnk-b-sold
                       from BOOKS where STOCKNO = :lnk-b-stockno
                    end-exec

                when lnk-b-title <> spaces
                    exec sql
                       select TITLE, TYPE, AUTHOR, STOCKNO, ISBN, RETAIL, ONHAND, SOLD
                           into :lnk-b-title, :lnk-b-type, :lnk-b-author, :lnk-b-stockno, :lnk-b-isbn, :lnk-b-retail, :lnk-b-onhand, :lnk-b-sold
                       from BOOKS where TITLE = :lnk-b-title
                    end-exec

                when lnk-b-author <> spaces
                    exec sql
                       select TITLE, TYPE, AUTHOR, STOCKNO, ISBN, RETAIL, ONHAND, SOLD
                           into :lnk-b-title, :lnk-b-type, :lnk-b-author, :lnk-b-stockno, :lnk-b-isbn, :lnk-b-retail, :lnk-b-onhand, :lnk-b-sold
                       from BOOKS where AUTHOR = :lnk-b-author
                    end-exec

                when other
      *>------------No key specified - return unsuccessful read
                     move "02000" to sqlstate
                     move "Record not found" to sqlerrmc
                     move 15 to sqlerrml

           end-evaluate

           if sqlcode not = 0
               initialize lnk-b-details
               *>move all '*' to lnk-b-title lnk-b-author lnk-b-type
           end-if
           .

       do-next-record section.
           exec sql
               select TITLE, TYPE, AUTHOR, STOCKNO, ISBN, RETAIL, ONHAND, SOLD
                   into :lnk-b-title, :lnk-b-type, :lnk-b-author, :lnk-b-stockno, :lnk-b-isbn, :lnk-b-retail, :lnk-b-onhand, :lnk-b-sold
               from BOOKS where STOCKNO > :lnk-b-stockno
           end-exec

           if sqlcode <> 0 AND sqlcode NOT EQUAL 1
               initialize lnk-b-details
               *>move all '*' to lnk-b-title lnk-b-author lnk-b-type
           end-if
           .

       do-add-record section.

           exec sql
               insert into BOOKS (TITLE, TYPE, AUTHOR, STOCKNO, ISBN, RETAIL, ONHAND, SOLD)
               values (:lnk-b-title, :lnk-b-type, :lnk-b-author, :lnk-b-stockno, :lnk-b-isbn, :lnk-b-retail, :lnk-b-onhand, :lnk-b-sold)
           end-exec
           if sqlcode = 0
               exec sql commit end-exec
           end-if
           .

       do-delete-record section.

           evaluate true
               when lnk-b-stockno <> spaces
                   exec sql delete from BOOKS where STOCKNO = :lnk-b-stockno end-exec

               when lnk-b-title <> spaces
                   exec sql delete from BOOKS where TITLE = :lnk-b-title end-exec

               when lnk-b-author <> spaces
                   exec sql delete from BOOKS where AUTHOR = :lnk-b-author end-exec

               when other
      *>------------No key specified - return unsuccessful read
                   move "02000" to sqlstate
                   move "Record not found" to sqlerrmc
                   move 15 to sqlerrml
           end-evaluate
           if sqlcode = 0
               exec sql commit end-exec
           end-if
  9. Click File > Save to save the program.

Modify book-rec.cpy

  1. In the Project Explorer under CobolBook > src, double-click book-rec.cpy to open it in the file editor.
  2. Replace the last line of code with the following:
    03 (prefix)-sold          pic s9(5) comp-3.
  3. Click File > Save to save your changes.
Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Previous topic: Create a SQL Server Database and Connection
Next topic: Modify Java Source


Modify Java Source

Modify the Java source code in the JSPBookDemo project to access the SQL Server database.

Modify BookBean.java

  1. In the Project Explorer expland JSPBookDemo > Java Resources > src.
  2. Double-click BookBean.java to open it in the file editor.
  3. Replace the entire contents of the file with the following:
    package com.microfocus.book;

import com.microfocus.cobol.program.ScaledInteger;

public class BookBean
{
  private final String _stockno;
  private final String _isbn;
  private final String _title;
  private final String _author;
  private final String _type;
  private final String _price;
  private final String _onhand;
  private final String _sold;
  private final String _stockval;

  BookBean(String stockno, String isbn, String title, String author,
      String type, String price, String onhand, String sold, String stockval)
  {
    this._stockno = stockno;
    this._isbn = isbn;
    this._title = title;
    this._author = author;
    this._type = type;
    this._price = price;
    this._onhand = onhand;
    this._sold = sold;
    this._stockval = stockval;
  }

  public String getStockno()
  {
    return _stockno;
  }

  public String getIsbn()
  {
    return _isbn;
  }

  public String getTitle()
  {
    return _title;
  }

  public String getAuthor()
  {
    return _author;
  }

  public String getType()
  {
    return _type;
  }

  public String getPrice()
  {
    return _price;
  }

  public String getOnhand()
  {
    return _onhand;
  }

  public String getSold()
  {
    return _sold;
  }

  public String getStockval()
  {
    return _stockval;
  }

  public void toDetails(Details details)
  {
    details.setStockno(_stockno);
    details.setIsbn(Long.parseLong(_isbn));
    details.setTitle(_title);
    details.setAuthor(_author);
    details.setType(_type);
    details.setRetail(ScaledInteger.parseScaledInteger(_price));

    int onHandInt = Integer.parseInt(_onhand);
    if(onHandInt < 0)
      throw new RuntimeException("The number of books on hand must be 0 or positive");
    details.setOnhand(onHandInt);

    int soldInt = Integer.parseInt(_sold);
    if(soldInt < 0)
      throw new RuntimeException("The number of books sold must be 0 or positive");
    details.setSold(soldInt);
  }

  public static BookBean fromDetails(Details details)
  {
    String stockno = details.getStockno().trim();
    String isbn = "" + details.getIsbn();
    String title = details.getTitle().trim();
    String author = details.getAuthor().trim();
    String type = details.getType().trim();
    String price = details.getRetail().toString();
    String onhand = "" + details.getOnhand();
    String sold = "" + details.getSold();
    ScaledInteger stockvalInt = details.getRetail().multiply(new ScaledInteger(details.getOnhand(), 0));
    String stockval = stockvalInt.toString();

    return new BookBean(stockno, isbn, title, author, type, price, onhand, sold, stockval);
  }

  public static BookBean blankBook()
  {
    return msgBook("*************************************");
  }

  public static BookBean msgBook(String msg)
  {
    String stockno    = "****";
    String isbn       = "*************";
    String title      = msg;
    String author     = "*************************************";
    String type       = "****";
    String price      = "****";
    String onhand     = "****";
    String sold       = "****";
    String stockval   = "****";

    return new BookBean(stockno, isbn, title, author, type, price, onhand, sold, stockval);
  }
}
  4. Click File > Save to save your changes.

Modify BookInterface.java

  • Using the same technique, replace the contents of BookInterface.java with the following:
    package com.microfocus.book;

import javax.servlet.http.HttpSession;

import com.microfocus.cobol.program.IObjectControl;
import com.microfocus.cobol.runtimeservices.IRunUnit;
import com.microfocus.cobol.runtimeservices.servlet.ServletRunUnitManager;

public class BookInterface
{
    public static final String READ_RECORD   = "1";
    public static final String ADD_RECORD    = "2";
    public static final String DELETE_RECORD = "3";
    public static final String NEXT_RECORD   = "4";

    public final IRunUnit runUnit;
    public final BookLegacy bookLegacy;

  public BookInterface(HttpSession session)
  {
    this(ServletRunUnitManager.getManager().GetSessionRunUnit(session));
  }

  public BookInterface(IRunUnit runUnit)
  {
    this.runUnit = runUnit;
    BookLegacy bookLegacy = (BookLegacy) runUnit.GetInstance(BookLegacy.class);

    if(bookLegacy == null)
    {
      bookLegacy = new BookLegacy();
      runUnit.Add(bookLegacy);
    }

    this.bookLegacy = bookLegacy;
  }

  public BookBean readBook(String stockNo) throws JavaBookException
  {
    Details details = getObject(Details.class);
    Sqlstate status = getObject(Sqlstate.class);
    Sqlmessage message = getObject(Sqlmessage.class);

    details.setStockno(stockNo);
    bookLegacy.BookLegacy(READ_RECORD, details, status, message);

    throwExceptionIfError(status, message);

    return BookBean.fromDetails(details);
  }

  public BookBean addBook(BookBean book) throws JavaBookException
  {
    Details details = getObject(Details.class);
    Sqlstate status = getObject(Sqlstate.class);
    Sqlmessage message = getObject(Sqlmessage.class);

    book.toDetails(details);
    bookLegacy.BookLegacy(ADD_RECORD, details, status, message);

    throwExceptionIfError(status, message);

    return BookBean.fromDetails(details);
  }

  public BookBean deleteBook(String stockNo) throws JavaBookException
  {
    Details details = getObject(Details.class);
    Sqlstate status = getObject(Sqlstate.class);
    Sqlmessage message = getObject(Sqlmessage.class);

    details.setStockno(stockNo);
    bookLegacy.BookLegacy(DELETE_RECORD, details, status, message);

    throwExceptionIfError(status, message);

    return BookBean.fromDetails(details);
  }

  public BookBean nextBook(String stockNo) throws JavaBookException
  {
    Details details = getObject(Details.class);
    Sqlstate status = getObject(Sqlstate.class);
    Sqlmessage message = getObject(Sqlmessage.class);

    details.setStockno(stockNo);
    bookLegacy.BookLegacy(NEXT_RECORD, details, status, message);

    throwExceptionIfError(status, message);

    return BookBean.fromDetails(details);
  }

  private static void throwExceptionIfError(Sqlstate status, Sqlmessage message) throws JavaBookException
  {
    String sqlstate = status.getSqlstate();
    if(!"00000".equals(sqlstate) && !"02000".equals(sqlstate) && !"21000".equals(sqlstate))
    {
        throw new JavaBookException(status.getSqlstate() + message.getSqlmessage());
    }
  }

  private <T extends IObjectControl> T getObject(Class<T> cls)
  {
    try
    {
      T output = cls.newInstance();
      runUnit.Add(output);

      return output;
    }
    catch (Throwable t)
    {
      throw new RuntimeException(t);
    }
  }
}

Modify BookServlet.java

  • Using the same technique, replace the contents of BookServlet.java with the following:
    package com.microfocus.book;

import java.io.PrintWriter;
import java.io.StringWriter;

import javax.servlet.RequestDispatcher;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;

import com.microfocus.cobol.runtimeservices.IRunUnit;
import com.microfocus.cobol.runtimeservices.servlet.ServletRunUnitManager;

public class BookServlet extends HttpServlet
{
  private static final long serialVersionUID = -3563065100184185678L;

  public static final String STOCK_NO_ATTRIBUTE   = "stockno";
  public static final String TITLE_ATTRIBUTE      = "title";
  public static final String AUTHOR_ATTRIBUTE     = "author";
  public static final String TYPE_ATTRIBUTE     = "type";
  public static final String ISBN_ATTRIBUTE     = "isbn";
  public static final String PRICE_ATTRIBUTE      = "price";
  public static final String ONHAND_ATTRIBUTE     = "onhand";
  public static final String SOLD_ATTRIBUTE     = "sold";
  public static final String STATUS_ATTRIBUTE     = "status";
  public static final String RUN_UNIT_ID_ATTRIBUTE  = "rununitid";

  public static final String SUBMIT_PARAMETER     = "submit";
  public static final String READ_PARAMETER     = "Read";
  public static final String ADD_PARAMETER      = "Add";
  public static final String DELETE_PARAMETER     = "Delete";
  public static final String NEXT_PARAMETER     = "Next";
  public static final String END_PARAMETER      = "End Session";
  public static final String ERROR_VALUE        = "ERROR";
  public static final String DEFAULT_VALUE      = "DEFAULT";
  public static final String VIEW_URL         = "/BookJsp.jsp";

  protected void doProcessing(HttpServletRequest req, HttpServletResponse res, boolean isGet)
  {
    String subValue = req.getParameter(SUBMIT_PARAMETER);

    if(subValue == null)
    {
      subValue = DEFAULT_VALUE;
    }

    setRunUnitId(req);

  if(subValue.equals(READ_PARAMETER))
  {
    performRead(req, res);
  }
  else if(subValue.equals(ADD_PARAMETER))
  {
    performAdd(req, res);
  }
  else if(subValue.equals(DELETE_PARAMETER))
  {
    performDelete(req, res);
  }
  else if(subValue.equals(NEXT_PARAMETER))
  {
    performNext(req, res);
  }
  else if(subValue.equals(END_PARAMETER))
  {
    performEndSession(req, res);
  }
  else
  {
    outputBlankBook(req, res);
  }

    RequestDispatcher dispatcher = getServletContext().getRequestDispatcher(VIEW_URL);
    try
  {
    dispatcher.forward(req, res);
  }
  catch(Exception e)
  {
    throw new RuntimeException(e);
  }
  }

  @Override
  protected void doGet(HttpServletRequest req, HttpServletResponse res)
  {
    doProcessing(req, res, true);
  }

  @Override
  protected void doPost(HttpServletRequest req, HttpServletResponse res)
  {
    doProcessing(req, res, false);
  }

  private void performRead(HttpServletRequest req, HttpServletResponse res)
  {
    BookInterface bookInterface = getBookInterface(req.getSession());
    String bookId = getStockNo(req, res);

    if(bookId == null)
    {
      bookId = ERROR_VALUE;
    }

    try
    {
      BookBean book = bookInterface.readBook(bookId);

      outputBook(req, res, book);
    }
    catch(JavaBookException e)
    {
      outputBookException(req, res, e);
    }
    catch (Exception e)
    {
      outputException(req, res, e);
    }
  }

  private void performAdd(HttpServletRequest req, HttpServletResponse res)
  {
    BookInterface bookInterface = getBookInterface(req.getSession());

    try
    {
      BookBean book = getBook(req, res);

      book = bookInterface.addBook(book);

      outputBook(req, res, book);
    }
    catch(JavaBookException e)
    {
      outputBookException(req, res, e);
    }
    catch (Exception e)
    {
      outputException(req, res, e);
    }
  }

  private void performDelete(HttpServletRequest req, HttpServletResponse res)
  {
    BookInterface bookInterface = getBookInterface(req.getSession());
    String bookId = getStockNo(req, res);

    if(bookId == null)
    {
      bookId = ERROR_VALUE;
    }

    try
    {
      BookBean book = bookInterface.deleteBook(bookId);

      outputBook(req, res, book);
    }
    catch(JavaBookException e)
    {
      outputBookException(req, res, e);
    }
    catch (Exception e)
    {
      outputException(req, res, e);
    }
  }

  private void performNext(HttpServletRequest req, HttpServletResponse res)
  {
    BookInterface bookInterface = getBookInterface(req.getSession());
    String bookId = getStockNo(req, res);

    if(bookId == null)
    {
      bookId = ERROR_VALUE;
    }

    try
    {
      BookBean book = bookInterface.nextBook(bookId);

      outputBook(req, res, book);
    }
    catch(JavaBookException e)
    {
      outputBookException(req, res, e);
    }
    catch (Exception e)
    {
      outputException(req, res, e);
    }
  }

  private void performEndSession(HttpServletRequest req, HttpServletResponse res)
  {
      HttpSession session = req.getSession();
      session.invalidate();

      outputError(req, res, "Session invalidated");
  }

  private void outputBlankBook(HttpServletRequest req, HttpServletResponse res)
  {
        outputBook(req, res, BookBean.blankBook());
  }

  private void outputBookException(HttpServletRequest req, HttpServletResponse res, JavaBookException jbe)
  {
        outputError(req, res, jbe.getMessage());
  }

  private void outputException(HttpServletRequest req, HttpServletResponse res, Exception e)
  {
    String msg = e.getClass().getName() + " [" + e.getMessage() + "]";
    StringWriter strWriter = new StringWriter();
    PrintWriter printWriter = new PrintWriter(strWriter);
    e.printStackTrace(printWriter);
    req.setAttribute(STATUS_ATTRIBUTE, strWriter.toString());
    outputError(req, res, msg);
  }

  private void outputBook(HttpServletRequest req, HttpServletResponse res, BookBean book)
  {
    if(book != null)
    {
      req.setAttribute("book", book);
    }
    else
    {
      req.setAttribute("book", BookBean.msgBook("ERROR! book is null in output book"));
    }
  }

  private void outputError(HttpServletRequest req, HttpServletResponse res, String msg)
  {
    outputBook(req, res, BookBean.msgBook(msg));
  }

  private BookBean getBook(HttpServletRequest req, HttpServletResponse res)
  {
    return new BookBean
    (
      getStockNo(req, res),
      getIsbn(req, res),
      getTitle(req, res),
      getAuthor(req, res),
      getType(req, res),
      getPrice(req, res),
      getOnhand(req, res),
      getSold(req, res),
      ""
    );
  }

  private String getAttribute(HttpServletRequest req, HttpServletResponse res, String attribute)
  {
    String stockNoStr;
    stockNoStr = req.getParameter(attribute);
    if(stockNoStr == null)
    {
        stockNoStr = ERROR_VALUE;
    }

    return stockNoStr;
  }

  private String getStockNo(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, STOCK_NO_ATTRIBUTE);
  }

  private String getTitle(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, TITLE_ATTRIBUTE);
  }

  private String getAuthor(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, AUTHOR_ATTRIBUTE);
  }

  private String getType(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, TYPE_ATTRIBUTE);
  }

  private String getIsbn(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, ISBN_ATTRIBUTE);
  }

  private String getPrice(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, PRICE_ATTRIBUTE);
  }

  private String getOnhand(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, ONHAND_ATTRIBUTE);
  }

  private String getSold(HttpServletRequest req, HttpServletResponse res)
  {
    return getAttribute(req, res, SOLD_ATTRIBUTE);
  }

  private IRunUnit getRunUnit(HttpSession session)
  {
    return ServletRunUnitManager.getManager().GetSessionRunUnit(session);
  }

  private void setRunUnitId(HttpServletRequest req)
  {
    HttpSession session = req.getSession();
    IRunUnit runUnit = getRunUnit(session);
    String ruid = "" +  runUnit.getRunUnitID();
    req.setAttribute(RUN_UNIT_ID_ATTRIBUTE, ruid);
  }

  private BookInterface getBookInterface(HttpSession session)
  {
    BookInterface output = new BookInterface(session);

    return output;
  }
}

Modify JavaBookException.java

  • Using the same technique, replace the contents of JavaBookException.java with the following:
    package com.microfocus.book;

import java.util.*;

public class JavaBookException extends Exception
{

  /**
     *
     */
  private static final long serialVersionUID = -3882735817601888938L;

  private static final Map<String, String> messages;
  private static final String unknownErrorMessage = "Unknown Error: ";

  public final String statusCode;

  public JavaBookException(String statusCode)
  {
    super(messages.containsKey(statusCode) ? messages.get(statusCode)
        : unknownErrorMessage + statusCode);
    this.statusCode = statusCode;
  }

  static
  {
    messages = new HashMap<String, String>();
    messages.put("35", "Error: Data file not found");
    messages.put("23", "Error: Stock item not found");
    messages.put("46", "No more items left");
    messages.put("99", "Error: Item already exists");
    messages.put("01", "Error: File error");
    messages.put("B1", "Error: No key entered");
  }
}
Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Previous topic: Modify COBOL Source
Next topic: Add and Modify XML


Add and Modify XML

Create a new context.xml file, and modify the existing web.xml file.

Add context.xml

We provide the XML code that sets the configuration of the PUBS database. You must add the XML to your project.

  1. In the Project Explorer, expand JSPBookDemo > WebContent.
  2. Right-click META-INF; then select New > Other.
  3. Expand XML; then select XML File.
  4. Click Next.
  5. In the File name field, type context.xml; then click Finish.

    This opens the empty context.xml file in the file editor.

  6. Copy the following XML code and paste it into the context.xml file:

<Context>

<!-- maxActive: Maximum number of database connections in pool. Make sure you
         configure your mysqld max_connections large enough to handle
         all of your db connections. Set to -1 for no limit.
         -->
       <!-- maxIdle: Maximum number of idle database connections to retain in pool.
         Set to -1 for no limit.  See also the DBCP documentation on this
         and the minEvictableIdleTimeMillis configuration parameter.
         -->
       <!-- maxWait: Maximum time to wait for a database connection to
         become available in ms, in this example 10 seconds.
         An Exception is thrown if this timeout is exceeded.
         Set to -1 to wait indefinitely.
         -->
       <!-- username and password: username and password for the connection -->
       <!-- driverClassName: Class name for the JDBC driver -->
       <!-- url: The JDBC connection url for connecting to the database -->

       <Resource name="PUBS" auth="Container" type="javax.sql.DataSource"
               maxActive="10" maxIdle="10" maxWait="10000"
               username="SQLServerUserName" password="SQLServerPassword"
               driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
               url="jdbc:sqlserver://localhost;database=PUBS;"
       />
</Context>

    Replacing SQLServerUserName and SQLServerPassword respectively with the user name and password required for SQL Server authentication

  7. Click File > Save to save the file.

Modify web.xml

The web.xml file requires modification to accommodate the SQL Server database.

  1. In the Project Explorer expand JSPBookDemo > WebContent > WEB-INF.
  2. Double-click web.xml to open it in the file editor.
  3. Replace the entire contents of the file with the following:

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">
  <display-name>JSPBookDemo</display-name>
  <servlet>
    <servlet-name>BookServlet</servlet-name>
    <servlet-class>com.microfocus.book.BookServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>BookServlet</servlet-name>
    <url-pattern>/view</url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>view</welcome-file>
  </welcome-file-list>
  <resource-ref>
      <description>DB Connection</description>
      <res-ref-name>PUBS</res-ref-name>
      <res-type>javax.sql.DataSource</res-type>
      <res-auth>Container</res-auth>
  </resource-ref>
</web-app>
  4. Click File > Save to save your changes.
Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Previous topic: Modify Java Source
Next topic: Run the JSP Application


Run the JSP Application

Run the JSPBookDemo application on Tomcat 7.
  1. In the Project Explorer, right-click the JSPBookDemo project; then select Run As > Run on Server from the context menu.
  2. On the Run On Server dialog box, be sure that Tomcat v7.0 Server at localhost is selected; then click Finish.

    This starts the Web form.

  3. In the Stock Number field, type 1111; then click Read.

    The Web form shows the database information for the Oliver Twist title.

  4. Click End Session and close the Web form.
Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Previous topic: Add and Modify XML
Next topic: Modifications for DB2 LUW


Modifications for DB2 LUW

Modifications to the tutorial for using a DB2 LUW database instead of a SQL Server database.

Prerequisites

This tutorial begins where Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment left off, using the Apache Tomcat application server, and the same CobolBook and JSPBookDemo projects. Therefore, you must complete that tutorial in its entirety, using the Tomcat 7 application server, before starting this tutorial. See Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment for complete instructions.

You must also install IBM DB2 LUW version 10 Express-C 32-bit.

Modifications

This section explains the modifications you need to make to the SQL Server version of the tutorial so that the application works with DB2 LUW instead of SQL Server.

Install and Configure a JDBC Driver
Install a JDBC Driver
This tutorial uses the IBM DB2 LUW 10.5 Express-C JDBC driver included with the database system installer; therefore, no download or installation is required.
Copy the JDBC Driver to Tomcat
Follow the instructions provided in the Copy the JDBC Driver to Tomcat section of the Install and Configure a JDBC Driver topic, but copy the db2jcc.jar and db2jcc_license_cu.jar files to the lib subdirectory of your Apache Tomcat installation.
Create and Load a DB2 LUW Database
Create the SAMPLE DB2 LUW Database
The tutorial uses the SAMPLE database you can create using the DB2 LUW First Steps tool. See your DB2 LUW documentation for further instructions.
Start Enterprise Developer
If you have closed Enterprise Developer since completing Tutorial: Reusing Existing COBOL Programs in a Java Environment, open it again; then open the Java EE perspective and the Project Explorer.
Define a DB2 Connection
Follow the instructions provided in the Define a SQL Server Connection section of the Create and Load a SQL Server Database topic, with the following modifications:
  • Connection Profile dialog box, select the DB2 for Linux, Unix, and Windows profile type.
  • On the New Driver Definition dialog box Name/Type tab, select IBM Data Server Driver for JDBC and SQLJ.
  • On the JAR List tab, follow these instructions:
    1. On the Driver file list, select the db2jcc.jar file; then click Edit JAR/Zip.
    2. Browse to the java subdirectory of your DB2 LUW installation, and double-click the db2jcc.jar file located there.

      This replaces the db2jcc.jar file on the list, and prompts you to update the other .jar file paths to use the same location. Because you are just adding a single .jar file in an alternative directory, updating the path for other files is not required.

    3. Click No.
    4. On the Driver file list, select the db2jcc_license_cisuz.jar file; then click Remove JAR/Zip.
    5. Click Add JAR/Zip.
    6. Browse to the java subdirectory of your DB2 LUW installation, and double-click the db2jcc_license_cu.jar file.

      This adds the file to the Driver file list.

  • On the Properties tab, use the following information:
    Property | Value
    Connection URL | jdbc:db2://localhost:50000/SAMPLE
    Database Name | SAMPLE
    Driver Class | com.ibm.db2.jcc.DB2Driver
    Password | blank
    User ID | blank
  • Follow these steps on the New Connection Profile dialog box:
    1. Check Save password.
    2. In the User name and Password fields respectively, type your DB2 user name and password credentials.
      Note: If your DB2 database does not use its own user name and password, type in your Windows authentication credentials instead.
    3. Click Test Connection.
    4. When the connection succeeds, clear the message box; then click Finish to save the connection and close the New Connection Profile dialog box.
Add an SQL Script
Follow the instructions provided in the Add an SQL Script section of the Create and Load a SQL Server Database topic, with the following modifications:
  • Name the new script file SetupDB2Books.sql.
  • Add the following contents:
    DROP TABLE BOOKS;

CREATE TABLE BOOKS (
    TITLE	VARCHAR(50) NOT NULL,
    TYPE    	VARCHAR(20) NOT NULL,
    AUTHOR  	VARCHAR(50) NOT NULL,
    STOCKNO CHAR(4) NOT NULL PRIMARY KEY,
    ISBN    	DECIMAL (13, 0) NOT NULL,
    RETAIL	DECIMAL(4,2) NOT NULL,
        ONHAND	INT NOT NULL,
        SOLD	INT NOT NULL
);

INSERT INTO BOOKS VALUES(
    'OLIVER TWIST',
    'CHARLES DICKENS',
    'CLASSIC',
    '1111',
    9780140620467,
    5.00,
    10,
    30
);

INSERT INTO BOOKS VALUES(
    'A GAME OF THRONES',
    'GEORGE R. R. MARTIN',
    'FANTASY',
    '1112',
    7428545,
    3.86,
    17,
    75
);

INSERT INTO BOOKS VALUES(
    'A CLASH OF KINGS',
    'GEORGE R. R. MARTIN',
    'FANTASY',
    '1113',
    7447833,
    6.49,
    17,
    75
);

INSERT INTO BOOKS VALUES(
    'THE DAY OF THE JACKAL',
    'FREDERICK FORSYTH',
    'ADVENTURE',
    '1114',
    99552710,
    2.00,
    26,
    75
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE PHILOSOPHER''S STONE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1116',
    747558191,
    5.24,
    48,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE CHAMBER OF SECRETS',
    'J. K. ROWLING',
    'ADVENTURE',
    '1117',
    747562180,
    5.24,
    44,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE PRISONER OF AZKABAN',
    'J. K. ROWLING',
    'ADVENTURE',
    '1118',
    747573760,
    5.24,
    49,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE GOBLET OF FIRE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1119',
    747582386,
    6.74,
    44,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE ORDER OF THE PHOENIX',
    'J. K. ROWLING',
    'ADVENTURE',
    '1120',
    747591261,
    6.74,
    37,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE HALF-BLOOD PRINCE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1121',
    747598460,
    6.74,
    41,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE DEATHLY HALLOWS',
    'J. K. ROWLING',
    'ADVENTURE',
    '1122',
    1408810298,
    6.74,
    40,
    100
);

INSERT INTO BOOKS VALUES(
    'THE FELLOWSHIP OF THE RING',
    'J. R. R. TOLKIEN',
    'FANTASY',
    '1123',
    7123825,
    4.95,
    23,
    100
);

INSERT INTO BOOKS VALUES(
    'THE TWO TOWERS',
    'J. R. R. TOLKIEN',
    'FANTASY',
    '1124',
    261102362,
    7.99,
    28,
    100
);

INSERT INTO BOOKS VALUES(
    'LORD OF THE FLIES',
    'WILLIAM GOLDING',
    'SCARY',
    '2222',
    9780571191475,
    4.50,
    30,
    100
);

INSERT INTO BOOKS VALUES(
    'CATCH 22',
    'JOSEPH HELLER',
    'WAR',
    '3333',
    9780099477310,
    6.50,
    50,
    200
);

INSERT INTO BOOKS VALUES(
    'THE HITCHHIKER''S GUIDE TO THE GALAXY',
    'DOUGLAS ADAMS',
    'COMEDY',
    '4444',
    9780345453747,
    6.73,
    100,
    360
);

INSERT INTO BOOKS VALUES(
    'TO KILL A MOCKINGBIRD',
    'HARPER LEE',
    'CLASSIC',
    '5555',
    9780099466734,
    4.87,
    50,
    75
);

SELECT * FROM yourSchema.BOOKS;
SELECT CURRENT SCHEMA FROM SYSIBM.SYSDUMMY
  • On the second to last line of the script, replace yourSchema with the name of the schema that your SAMPLE database was created under.
Execute the SQL Script
Follow the instructions provided in the Execute the SQL Script section of the Create and Load a SQL Server Database topic, with the following modifications:
  • Use the SetupDB2Books.sql file.
  • Set the Type to DB2 UDB_V9.1.
  • Set the Name to the name of your DB2 connection.
  • In the Database field, select SAMPLE.
Modify COBOL Source
Following the instructions in the Modify COBOL Source topic, with these modifications:
Replace book.cbl with sqlbook.cbl
Follow the instructions provided in the Replace book.cbl with sqlbook.cbl of the Modify COBOL Source topic.
Note: If you have previously done this tutorial and replaced the book.cbl with the sqlbook.cbl file, skip this step and continue with Modify the EXEC SQL Statement.
Modify the EXEC SQL Statement
  1. In the Project Explorer, double-click the sqlbook.cbl entry to open the file in the editor.
  2. Change:
    exec sql connect to PUBS end-exec

    To:

    exec sql connect to db2 end-exec
  3. Save sqlbook.cbl.
Modify book-rec.cpy
Follow the instructions provided in the Modify book-rec.cpy section of the Modify COBOL Source topic. No modifications are required.
Note: If you have previously done this tutorial and modified the book-rec.cpy, skip this step and continue with Modify Java Source.
Modify Java Source
Complete all sections of the Modify Java Source topic.
Note: If you have previously done this tutorial and modified the java source, skip this step and continue with Modify XML Source.
Add and Modify XML
Add context.xml
Following the instructions in the Add context.xml section of the Add and Modify XML topic, with this modification:
  • Copy and paste the following code into the context.xml file:
    <Resource name="db2" auth="Container" type="javax.sql.DataSource"
               maxActive="10" maxIdle="10" maxWait="10000"
               username="db2UserName" password="db2Password"
               driverClassName="com.ibm.db2.jcc.DB2Driver"
               url="jdbc:db2://localhost:50000/sample:retrieveMessagesFromServerOnGetMessage=true;"/>

    Replacing db2UserName and db2Password with your DB2 database credentials, or if applicable, your Windows authentication credentials.

Note: If you have previously done this tutorial and added the context.xml file, simply replace the contents of the file with the code shown here.
Modify web.xml
Follow the instructions in the Modify web.xml section of the Add and Modify XML topic with the following modification:
  • Replace the entire contents of web.xml with the following:

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">
  <display-name>JSPBookDemo</display-name>
  <servlet>
    <servlet-name>BookServlet</servlet-name>
    <servlet-class>com.microfocus.book.BookServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>BookServlet</servlet-name>
    <url-pattern>/view</url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>view</welcome-file>
  </welcome-file-list>
  <resource-ref>
      <description>DB Connection</description>
      <res-ref-name>db2</res-ref-name>
      <res-type>javax.sql.DataSource</res-type>
      <res-auth>Container</res-auth>
  </resource-ref>
</web-app>
Run the JSP Application
No modifications are required for DB2 LUW. Follow the instructions in the Run the JSP Application topic.
Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Previous topic: Run the JSP Application
Next topic: Modifications for Oracle
Related concepts
Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Install and Configure a JDBC Driver
Create a SQL Server Database and Connection
Modify COBOL Source
Modify Java Source
Add and Modify XML
Run the JSP Application


Modifications for Oracle

Modifications to the tutorial for using an Oracle database instead of a SQL Server database.

Prerequisites

This tutorial begins where Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment left off, using the Apache Tomcat application server, and the same CobolBook and JSPBookDemo projects. Therefore, you must complete that tutorial in its entirety, using the Tomcat 7 application server, before starting this tutorial. See Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment for complete instructions.

You must also install Oracle Database 11g Express Edition.

Modifications

This section explains the modifications you need to make to the SQL Server version of the tutorial so that the application works with Oracle instead of SQL Server.

Install and Configure a JDBC Driver
Install a JDBC Driver
This tutorial uses the Oracle Database 11g Release 2 JDBC driver to connect to Oracle 11g Express Edition. Follow these instructions instead of the instructions in the Install a JDBC Driver section of the Install and Configure a JDBC Driver topic:
  • Open the Oracle download page in your Web browser using this URL:

    http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html

  • Under JDBC Thin for All Platforms, download the ojdbc6.jar file to your local machine, noting the directory where it is saved.
Copy the JDBC Driver to Tomcat
Follow the instructions provided in the Copy the JDBC Driver to Tomcat section of the Install and Configure a JDBC Driver topic, but copy the ojdbc6.jar file to the lib subdirectory of your Apache Tomcat installation.
Change the Tomcat HTTP Port
By default, Oracle uses port 8080 which is the same as Tomcat. To avoid conflict, change the Tomcat HTTP port as follows:
  1. In Project Explorer, expand Servers > Tomcat v7.0 Server at localhost-config.
  2. Double-click server.xml to open it in the editor.
  3. Change:
    <Connector connectionTimeout="20000"
port="8080" protocol="HTTP/1.1" redirectPort="8443"/>

    To:

    <Connector connectionTimeout="20000"
port="9000" protocol="HTTP/1.1" redirectPort="8443"/>
  4. Click File > Save to save server.xml.
Define a Connection and Load an Oracle Database
Create the Oracle Database
The tutorial uses the standard Oracle XE database that is included in the product; therefore, you do not need to create a database for this tutorial.
Start Enterprise Developer
If you have closed Enterprise Developer since completing Tutorial: Reusing Existing COBOL Programs in a Java Environment, open it again; then open the Java EE perspective and the Project Explorer.
Define an Oracle Connection
Follow the instructions provided in the Define a SQL Server Connection section of the Create and Load a SQL Server Database topic, with the following modifications:
  • Connection Profile dialog box, select the Oracle profile type.
  • On the New Driver Definition dialog box Name/Type tab, select Oracle Thin Driver (for System Version 11).
  • On the JAR List tab, follow these instructions:
    1. Click Add JAR/Zip.
    2. Browse to the local directory that contains your downloaded ojdbc6.jar file, and double-click the file to select it.

      This adds the file to the Driver file list.

  • On the Properties tab, use the following information:
    Property | Value
    SID | Xe
    Host | Localhost
    Port number | 1521
    User name | Scott 1
    Password | tiger 1,2
    Connection URL | jdbc:oracle:thin:@localhost:1521:xe

    1 Connection credentials used for this tutorial.

    2 Password is case sensitive.

  • Follow these steps on the New Connection Profile dialog box:
    1. Click Test Connection.
    2. When the connection succeeds, clear the message box; then click Finish to save the connection and close the New Connection Profile dialog box.
Add an SQL Script
Follow the instructions provided in the Add an SQL Script section of the Create and Load a SQL Server Database topic, with the following modifications:
  • Name the new script file SetupOraBooks.sql.
  • Add the following contents:
    DROP TABLE BOOKS;
CREATE TABLE BOOKS (
    TITLE	VARCHAR2(50) NOT NULL,
    TYPE    	VARCHAR2(20) NOT NULL,
    AUTHOR  	VARCHAR2(50) NOT NULL,
    STOCKNO 	CHAR(4) PRIMARY KEY,
    ISBN    	DECIMAL (13, 0) NOT NULL,
    RETAIL	DECIMAL(4,2) NOT NULL,
       ONHAND	INT NOT NULL,
        SOLD	INT NOT NULL
   );

INSERT INTO BOOKS VALUES(
    'OLIVER TWIST',
    'CHARLES DICKENS',
    'CLASSIC',
    '1111',
    9780140620467,
    5.00,
    10,
    30
);

INSERT INTO BOOKS VALUES(
    'A GAME OF THRONES',
    'GEORGE R. R. MARTIN',
    'FANTASY',
    '1112',
    7428545,
    3.86,
    17,
    75
);

INSERT INTO BOOKS VALUES(
    'A CLASH OF KINGS',
    'GEORGE R. R. MARTIN',
    'FANTASY',
    '1113',
    7447833,
    6.49,
    17,
    75
);

INSERT INTO BOOKS VALUES(
    'THE DAY OF THE JACKAL',
    'FREDERICK FORSYTH',
    'ADVENTURE',
    '1114',
    99552710,
    2.00,
    26,
    75
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE PHILOSOPHER''S STONE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1116',
    747558191,
    5.24,
    48,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE CHAMBER OF SECRETS',
    'J. K. ROWLING',
    'ADVENTURE',
    '1117',
    747562180,
    5.24,
    44,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE PRISONER OF AZKABAN',
    'J. K. ROWLING',
    'ADVENTURE',
    '1118',
    747573760,
    5.24,
    49,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE GOBLET OF FIRE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1119',
    747582386,
    6.74,
    44,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE ORDER OF THE PHOENIX',
    'J. K. ROWLING',
    'ADVENTURE',
    '1120',
    747591261,
    6.74,
    37,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE HALF-BLOOD PRINCE',
    'J. K. ROWLING',
    'ADVENTURE',
    '1121',
    747598460,
    6.74,
    41,
    100
);

INSERT INTO BOOKS VALUES(
    'HARRY POTTER AND THE DEATHLY HALLOWS',
    'J. K. ROWLING',
    'ADVENTURE',
    '1122',
    1408810298,
    6.74,
    40,
    100
);

INSERT INTO BOOKS VALUES(
    'THE FELLOWSHIP OF THE RING',
    'J. R. R. TOLKIEN',
    'FANTASY',
    '1123',
    7123825,
    4.95,
    23,
    100
);

INSERT INTO BOOKS VALUES(
    'THE TWO TOWERS',
    'J. R. R. TOLKIEN',
    'FANTASY',
    '1124',
    261102362,
    7.99,
    28,
    100
);

INSERT INTO BOOKS VALUES(
    'LORD OF THE FLIES',
    'WILLIAM GOLDING',
    'SCARY',
    '2222',
    9780571191475,
    4.50,
    30,
    100
);

INSERT INTO BOOKS VALUES(
    'CATCH 22',
    'JOSEPH HELLER',
    'WAR',
    '3333',
    9780099477310,
    6.50,
    50,
    200
);

INSERT INTO BOOKS VALUES(
    'THE HITCHHIKER''S GUIDE TO THE GALAXY',
    'DOUGLAS ADAMS',
    'COMEDY',
    '4444',
    9780345453747,
    6.73,
    100,
    360
);

INSERT INTO BOOKS VALUES(
    'TO KILL A MOCKINGBIRD',
    'HARPER LEE',
    'CLASSIC',
    '5555',
    9780099466734,
    4.87,
    50,
    75
);

SELECT * FROM BOOKS;
/* create user SCOTT identified by tiger
grant dba to SCOTT */
Execute the SQL Script
Follow the instructions provided in the Execute the SQL Script section of the Create and Load a SQL Server Database topic, with the following modifications:
  • Use the SetupOraBooks.sql file.
  • Set the Type to Oracle_11.
  • Set the Name to the name of your Oracle connection.
  • In the Database field, select xe.
Modify COBOL Source
Following the instructions in the Modify COBOL Source topic, with these modifications:
Replace book.cbl with sqlbook.cbl
Follow the instructions provided in the Replace book.cbl with sqlbook.cbl of the Modify COBOL Source topic.
Note: If you have previously done this tutorial and replaced the book.cbl with the sqlbook.cbl file, skip this step and continue with Modify the EXEC SQL Statement.
Modify the EXEC SQL Statement
  1. In the Project Explorer, double-click the sqlbook.cbl entry to open the file in the editor.
  2. Change:
    exec sql connect to PUBS end-exec

    To:

    exec sql connect to ora end-exec
  3. Save sqlbook.cbl.
Modify book-rec.cpy
Follow the instructions provided in the Modify book-rec.cpy section of the Modify COBOL Source topic. No modifications are required.
Note: If you have previously done this tutorial and modified the book-rec.cpy, skip this step and continue with Modify Java Source.
Modify Java Source
Complete all sections of the Modify Java Source topic.
Note: If you have previously done this tutorial and modified the java source, skip this step and continue with Modify XML Source.
Add and Modify XML
Add context.xml
Following the instructions in the Add context.xml section of the Add and Modify XML topic, with this modification:
  • Copy and paste the following code into the context.xml file:
    <Resource name="ora" auth="Container" type="javax.sql.DataSource"
               maxActive="10" maxIdle="10" maxWait="10000"
               username="SCOTT" password="tiger"
               driverClassName="oracle.jdbc.driver.OracleDriver"
               url="jdbc:oracle:thin:@localhost:1521/XE" />
Note: If you have previously done this tutorial and added the context.xml file, simply replace the contents of the file with the code shown here.
Modify web.xml
Follow the instructions in the Modify web.xml section of the Add and Modify XML topic with the following modification:
  • Replace the entire contents of web.xml with the following:

<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">
  <display-name>JSPBookDemo</display-name>
  <servlet>
    <servlet-name>BookServlet</servlet-name>
    <servlet-class>com.microfocus.book.BookServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>BookServlet</servlet-name>
    <url-pattern>/view</url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>view</welcome-file>
  </welcome-file-list>
  <resource-ref>
      <description>DB Connection</description>
      <res-ref-name>pubs</res-ref-name>
      <res-type>javax.sql.DataSource</res-type>
      <res-auth>Container</res-auth>
  </resource-ref>
</web-app>
Run the JSP Application
No modifications are required for Oracle. Follow the instructions in the Run the JSP Application topic.
Parent topic: Tutorial: Reusing Existing SQL Programs in a Java Environment
Previous topic: Modifications for DB2 LUW
Related concepts
Tutorial: Reusing Existing COBOL Programs in a Java Web Services Environment
Install and Configure a JDBC Driver
Create a SQL Server Database and Connection
Modify COBOL Source
Modify Java Source
Add and Modify XML
Run the JSP Application


Technology Preview Features

Some features in this product are provided as technology preview features only. They are being made available to allow you to test and provide feedback on the new capabilities; however, they are not intended for production use and are not supported as such.

  • IMS support for signing onto multiple LUs simultaneously using the same user ID. This feature is implemented using the ES_IMS_SINGLE and ES_IMS_LTERM_PREFIX IMS-specific environment variables.
Parent topic: Welcome
Related concepts
Developing Applications in the Team Developer Perspective (Technology Preview)
AMB Endevor Interface (Technology Preview)
Workflow Manager AMB Attachment (Technology Preview)
OpenESQL Support for Oracle PL/I Applications (Technology Preview)
Related reference
ILINCREMENTALBUILD (Technology Preview)
CASSI0015I ES support for CICS WEBSERVICES is enabled
CASSI0017W ES support for CICS WEBSERVICES is disabled. CCSID tables Source CCSID to Target CCSID not found
Compiling JVM COBOL
DSNREXX Support (Technology Preview)


Enterprise Developer Editions and Licenses

Enterprise Developer is a contemporary development suite for Microsoft Visual Studio or Eclipse that allows mainframe developers to maintain, develop and modernize mainframe applications environments regardless of whether these are to be deployed back on the mainframe or onto an alternative platform.

Enterprise Developer supports IBM COBOL, IBM PL/I, IBM Assembler, IBM CICS, IBM IMS, IBM JCL, IBM DB2, IBM z/OS file formats and common batch utilities, including SORT. This means that you can develop and maintain the core mainframe online and batch applications under Enterprise Developer. You can then deploy these applications back on the mainframe or migrate them onto one of the Micro Focus Linux, UNIX or Windows-based production platforms.

Micro Focus offers Enterprise Developer with the following licensing options that unlock different functionality:

Micro Focus Enterprise Developer Connect
Enterprise Developer Connect is for customers looking to use modern and productive Eclipse-based tooling to develop mainframe applications directly on the mainframe. Close integration to mainframe configuration management systems and the ability to easily customize the Eclipse-based IDE to include mainframe-based tools and processes means developers can take full advantage of modern development tools without having to learn new development processes.
Micro Focus Enterprise Developer
Enterprise Developer is for customers looking to develop and modernize mainframe applications in a productive and modern Windows-based development environment, targeted for deployment onto an alternate server platform. Developers have the choice of either the Visual Studio or the Eclipse-based IDE and development and test tools are provided for all target environments currently supported by Micro Focus.
Micro Focus Enterprise Developer for z Systems
Enterprise Developer for z Systems gives customers the choice to develop directly on the mainframe or under Windows. Mainframe applications can be developed, maintained and modernized regardless of where they will be deployed, either back onto the mainframe or onto an alternative server environment. Support is provided for both the Visual Studio and Eclipse-based IDEs and for all the development and test tools for every target environment currently supported by Micro Focus - including z/Linux, AIX and x86 environments. Enterprise Developer for z Systems combines all the capabilities of Enterprise Developer Connect and Enterprise Developer.

Full mainframe integration and the Application Workflow Manager are only available in the Eclipse-based IDE.

Note: The Enterprise Developer Personal Edition option is not available with this release. You can use the Personal Edition with Enterprise Developer 2.1 Update 1 - you can register for it on the Enterprise Developer Personal Edition section on the Micro Focus Web site.

Both Enterprise Developer for z Systems and Enterprise Developer are available for evaluation from Micro Focus and both have concurrent and named user license options.

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

You can also apply your license file or authorization code directly within the product from the Micro Focus Product Name Licensing dialog.

See Related Concepts for more information about how to license this product.

  • To buy and activate a full license
  • To obtain more licenses
Parent topic: Welcome
Related concepts
Managing Licenses


To buy and activate a full license

To buy a license for Enterprise Developer, contact your sales representative or Micro Focus SupportLine.

For instructions on using the Micro Focus License Administration Tool, see Licensing in the Enterprise Developer help.

Activating the license from the IDE

When you have bought your license you are given a license file or an authorization code with which to activate the product.

  1. Start Enterprise Developer.

    If you have not installed a license for Enterprise Developer, starting the IDE for the first time after you install the product opens the Micro Focus Enterprise Developer Product Licensing dialog box. If you cancel this dialog box, you can invoke it again from Help > Micro Focus > Product Licensing.

  2. To install your license:
    • If you have a license file - click Browse next to the License file field, select the license file (with an .mflic extension), and click Open. Click Finish to install the license.
    • If you have an authorization code - paste the code in the Authorization code field, and then click Finish.
  3. Restart Eclipse to complete the activation process.
Parent topic: Enterprise Developer Editions and Licenses
Related concepts
Managing Licenses
Related information
To obtain more licenses


To obtain more licenses

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

Parent topic: Enterprise Developer Editions and Licenses
Related concepts
To buy and activate a full license


Product Information

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

  • Installation
  • Managing Licenses
  • Updates and Product Support
  • Micro Focus End User License Agreement
  • Known Issues and Restrictions
  • Contacting Micro Focus
Parent topic: Welcome


Installation

  • Before Installing
  • Basic Installation
  • Advanced Installation Tasks
  • After Installing
  • Installing Enterprise Developer Development Hub
Parent topic: Product Information


Before Installing

  • Downloading the Product
  • On Windows
  • On UNIX
Parent topic: Installation


Downloading the Product

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

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

Parent topic: Before Installing


On Windows

  • System Requirements
  • Product Co-Existence
  • Installation Restrictions and Requirements
Parent topic: Before Installing


System Requirements

  • Hardware Requirements
  • Operating Systems Supported
  • Software requirements
  • Additional Software Requirements on Windows
Parent topic: On Windows


Hardware Requirements

Enterprise Developer has the following requirements in addition to the requirements of Eclipse. See the Eclipse documentation for details of its requirements.

In general, most modern machines will have the required processor and available RAM to run the Micro Focus products under Windows effectively. For planning purposes, you should consider having a minimum of 2GB of RAM though Micro Focus recommends at least 4GB of RAM for optimal performance.

The disk space requirements for Windows are, approximately:

Enterprise Developer
3.5GB
Note: The disk space requirements include the size of the Eclipse IDE and the version of Java and the .NET Framework provided with the Enterprise Developer setup file. This includes the space needed to cache information locally so that you can modify the installation without the original source media.

z/Server requirements

z/Server has the following hardware requirements:

  • IBM mainframe model zEC12 or later is required for installing and using MFA Server. If your hardware does not meet these requirements please contact Micro Focus support.
Parent topic: System Requirements
Related information
Operating Systems Supported
Software requirements
Additional Software Requirements on Windows


Operating Systems Supported

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

Note:
  • Support for development on Windows 8 and Windows Server 2012 has been discontinued. These platforms are still supported for deployment. Windows 8.1 and Windows Server 2012 R2 are supported.
  • Enterprise Developer installs fully only on 64-bit Windows platforms. On 32-bit Windows, the setup file does not install some of the components. See Issues with the Installation in Known Issues and Restrictions.
  • Enterprise Developer enables you to produce both 64-bit and 32-bit applications on 64-bit operating systems.
  • This product can be installed on earlier versions of Windows but it has not been tested on them.
Parent topic: System Requirements
Related information
Hardware Requirements
Software requirements
Additional Software Requirements on Windows


Software requirements

Note: This product includes OpenSSL version 1.0.2n.

The setup file will check your machine for whether the prerequisite software is installed and will install any missing prerequisites and the product components.

Eclipse requirements

  • The setup file installs Enterprise Developer and the 64-bit Eclipse 4.7.

    Some earlier versions of Eclipse are also supported. See Installing Enterprise Developer into other instances of Eclipse in the Advanced Installation Tasks.

  • Enterprise Developer installs fully only on 64-bit Windows platforms. On 32-bit Windows, the setup file does not install some of the components. See Issues with the Installation in Known Issues and Restrictions.
  • Enterprise Developer supports both the 32-bit and the 64-bit Eclipse. You can use the 64-bit Eclipse to create both 32-bit and 64-bit applications.

Software requirements on Windows

  • Oracle's Java Platform (64-bit) version 1.8 or later, or AdoptOpenJDK's OpenJDK 8 (64-bit) are required to run the Eclipse IDE. The recommended minimum version is Java 1.8.162 (64-bit), which the Windows product installation will install if it detects an older version. Oracle's implementation of Java 7, 8 (32 or 64-bit versions), and Java 9 (64-bit version only), and AdoptOpenJDK's OpenJDK 8 are supported for executing JVM COBOL code, and for native COBOL and Java interoperability. You can download Oracle's Java from Oracle's Web site and install it anywhere on your machine. Alternatively, you can download AdoptOpenJDK's OpenJDK 8 with Hotspot from AdoptOpenJDK's Web site and unpack the archive anywhere on your machine.
    Note: To skip installing Java 1.8.162 as part of the product installation, run the setup file with the skipjre=1 command line option.
  • Enterprise Developer requires:
    • A 32-bit Java installation if using the 32-bit Eclipse.
    • A 64-bit Java installation if using the 64-bit Eclipse.
  • The setup file also installs .NET Framework v4.6.1 and the Microsoft's Visual C++ 2010 and 2012 Redistributables.

See Java Support Restrictions in the product help for any considerations when using Eclipse and Java.

Other Requirements

Important: For local servers, you do not need to install the Micro Focus License Administration tool separately, as the setup file installs a new Enterprise Developer client and a new licensing server on the same machine.

If you have a network server, you must update the license server before installing the product as the client is not able to communicate with license servers of versions older than 10000.2.660. On Windows, you can check the version of your license server by clicking Help > About in the Micro Focus License Administration tool. 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 tasks
Remote Development
JVM COBOL support
Related reference
Java Support Restrictions
Installing Enterprise Developer into other instances of Eclipse
Related information
Hardware Requirements
Operating Systems Supported
Additional Software Requirements on Windows


Additional Software Requirements on Windows

To ensure full functionality for some Enterprise Developer features, you might be required to obtain and install additional third-party software in addition to the prerequisite software installed automatically by the Enterprise Developer 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
  • AppMaster Builder Distributed Generation Server
  • CICS Web Services
  • Code Analysis
  • Consolidated Trace Facility
  • Database Access - COBSQL (Pro*COBOL)
  • Database Access - HCO for DB2 LUW
  • Database Access - HCO for SQL Server (HCOSS)
  • Database Access - Mainframe Batch Database Tools (MBDT)
  • Database Access - OpenESQL
  • Database Access - SQL Option for DB2
  • Java Development Kit (JDK)
  • JCL Support - DSNREXX
  • Mainframe Access - Endevor Support
  • Micro Focus Rumba
  • WebSphere MQ

Application Server support for JVM COBOL

Back to Top

The following application servers are supported using the following JDKs:

Application Servers | JDK version | Containers support version
Tomcat 7.0.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

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.

Support for the following Java application servers using the following JDKs is planned for future release:

Application Servers | JDK (vendor) | Java EE | COBOL RA | CICS RAs and ECI
JBoss EAP 7.0 | 1.8 (Oracle), 1.8 (OpenJDK) | 7 | X | X
IBM WebSphere 8.5.5 (UNIX: all platforms) | 1.7, 1.8 (IBM) | 6 | X |
Tomcat 8.5.x* | 1.7, 1.8 (Oracle), 1.8 (OpenJDK) |  |  |
*Apache Tomcat is an HTTP server and servlet container supporting Java Servlet and JavaServer Pages (JSP). Micro Focus Tomcat non-transactional support includes servlet generation with J2SE Beans; no transactional support is provided. Tomcat does not support the use of Enterprise Java Beans (EJBs) or resource adapters (RAs).
Note: If you experience any incompatibility issues when using these third-party products with Enterprise Developer, please report them to SupportLine. Until full support is available, a timely effort to resolve incompatibility issues will be made; however, Micro Focus does not guarantee full compatibility until we have fully tested our software updates against these products.

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

Various Java EE versions are supported for the deployment of EJBs generated using the Interface Mapping Toolkit, as follows:

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

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

Application Servers | JDK (vendor) | Java EE | COBOL RA | CICS RAs and ECI
JBoss EAP 6.4 (AS 7.5) | 1.6, 1.7, 1.8 (Oracle), 1.8 (OpenJDK) | 6 | X | X
Oracle WebLogic 10.3.x | 1.6, 1.7 (Oracle) | 5 | X |
Oracle WebLogic 12.1.x | 1.6, 1.7, 1.8 (Oracle) | 6 | X |
Oracle WebLogic 12.2.1 | 1.8 (Oracle) | 7 | X |
IBM WebSphere 8.5 | 1.6, 1.7 (IBM) | 6 | X | X
IBM WebSphere 9.0 | 1.8 (IBM) | 7 | X |
Tomcat 7.0.x * | 1.6, 1.7, 1.8 (Oracle), 1.8 (OpenJDK) |  |  |
*Apache Tomcat is an HTTP server and servlet container supporting Java Servlet and JavaServer Pages (JSP). Micro Focus Tomcat non-transactional support includes servlet generation with J2SE Beans; no transactional support is provided. Tomcat does not support the use of Enterprise Java Beans (EJBs) or resource adapters (RAs).

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.

Support for the following Java application servers using the following JDKs is planned for future release:

Application Servers | JDK (vendor) | Java EE | COBOL RA | CICS RAs and ECI
JBoss EAP 7.0 | 1.8 (Oracle), 1.8 (OpenJDK) | 7 | X | X
IBM WebSphere 8.5.5 (UNIX: all platforms) | 1.7, 1.8 (IBM) | 6 | X |
Tomcat 8.5.x* | 1.7, 1.8 (Oracle), 1.8 (OpenJDK) |  |  |
*Apache Tomcat is an HTTP server and servlet container supporting Java Servlet and JavaServer Pages (JSP). Micro Focus Tomcat non-transactional support includes servlet generation with J2SE Beans; no transactional support is provided. Tomcat does not support the use of Enterprise Java Beans (EJBs) or resource adapters (RAs).
Note: If you experience any incompatibility issues when using these third-party products with Enterprise Developer, please report them to SupportLine. Until full support is available, a timely effort to resolve incompatibility issues will be made; however, Micro Focus does not guarantee full compatibility until we have fully tested our software updates against these products.

AppMaster Builder Distributed Generation Server

Back to Top

Restriction: This feature applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

IBM WebSphere MQ version 7 and later.

CICS Web Services

Back to Top

To use CICS Web Services, you must first install the IBM CCSID conversion tables. See CCSID Conversion Tables for details.

Code Analysis

Back to Top

Apache Ant is required to perform code analysis from the Enterprise Developer command line. You can download Apache Ant from Apache's Web site.

Consolidated Trace Facility

Back to Top

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

Note: The setup file installs .NET Framework v4.5.2.

Database Access - COBSQL (Pro*COBOL)

Back to Top

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

Note: COBSQL (Pro*COBOL) is supported for native COBOL only.
Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Windows | X | X
XA Switch Module
The Oracle XA switch module is provided for COBSQL (Pro*COBOL), and is available on the same platforms as are indicated in the Availability section above.
Certification of RDBMS Precompilers for Native COBOL
Certification of RDBMS precompilers with Micro Focus products is the responsibility of the RDBMS vendor, rather than Micro Focus. Certification information can be found within the relevant Oracle documentation. If you have an Oracle MetaLink account, document # 43208.1 provides details of all language compilers certified by Oracle for use with their precompilers.
Preprocessors
COBSQL supports the following database preprocessors:
  • Sybase Open Client Embedded SQL/COBOL Version 11.1 or later
  • Oracle Pro*COBOL Version 11.2, 12.1, and 12.2
  • Informix Embedded SQL/COBOL Version 7.3 or later
Compiling
On x86 and x86-64 platforms, when compiling with COBSQL for use with Oracle, do not use the COBSQL directive option NOMAKESYN, since this directive results in COMP host variables, and on Intel platforms these are incompatible with the native byte order expected by Oracle.
Testing
For this version, COBSQL was tested with Oracle 11.2, 12.1, and 12.2.

Database Access - HCO for DB2 LUW

Back to Top

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

Note: HCO for DB2 LUW is supported for native COBOL only.
Availability
Feature/Platform | Native COBOL 32-bit | Native COBOL 64-bit | PL/I 32-bit | PL/I 64-bit
x86-64 running Windows | X | X | X | X
XA Switch Module
The DB2 XA switch module is provided and is available on the same platforms as are indicated in the Availability section above.
Certification of RDBMS Precompilers for Native COBOL
Certification of RDBMS precompilers with Micro Focus products is the responsibility of the RDBMS vendor, rather than Micro Focus. You can find IBM document certification information for DB2/COBOL applications within the IBM Information Center for DB2, in the topic Support for database application development in COBOL.
Preprocessor
HCO for DB2 LUW supports the following database preprocessors:
  • IBM DB2 LUW Version 9.7 or later
  • IBM DB2 Connect Version 9.7 or later
Host Compatibility Option (HCO)
Host Compatibility Option requires that you have one of the following software products installed and configured:
  • IBM DB2 Connect - Personal, Enterprise, Application Server or Unlimited Edition
  • IBM DB2 LUW - Workgroup or Enterprise Server Editions including Advanced versions
  • IBM DB2 LUW - Express or Express-C Edition
  • IBM Data Server Client (assumes installation of a remote DB2 LUW Server product)
Testing
For this version, HCO for DB2 LUW was tested with versions 9.7, 10.1, 10.5, and 11.1.

Database Access - HCO for SQL Server (HCOSS)

Back to Top

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

Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Windows | X | X
Database Migration
  • SQL Server 2008 R2 or later, any edition
  • Microsoft .NET Framework 4.0
  • Microsoft OLE DB Provider for DB2 version 5.0 or later
    Note: Be sure to configure the OLE DB Provider to connect to the mainframe. See your Microsoft documentation for details.
  • Mainframe DB2
Note:
  • We support only the mainframe DB2 versions that are currently under IBM support.
  • If you intend to develop applications on your local machine, but deploy applications to a SQL Server database on a remote machine, configure the remote machine using the requirements listed in the Deploying Native Applications > Deployment Machine section below.
Deploying Native Applications
Development Machine
Install one of the following combinations:
  • For SQL Server 2008 R2 and SQL Server 2012 databases, install SQL Server Native Client 10.x or later
  • For SQL Server 2008 R2 and SQL Server 2012 databases, install SQL Server along with the Microsoft ODBC Driver version 11.0.
  • For SQL Server 2014 databases, you must install both SQL Server 2014 and the Microsoft ODBC Driver 11.0 for SQL Server.
  • For SQL Server 2016 databases, you must install both SQL Server 2016 and the Microsoft ODBC Driver 13.0 for SQL Server.
Development SQL Server Machine
SQL Server 2008 R2 or later
Note: This can be the same machine as the development machine, but is not required to be.
Deployment Machine
  • Enterprise Server or Enterprise Test Server
  • For SQL Server 2008 R2 and SQL Server 2012 databases, install SQL Server along with the Microsoft ODBC driver version 11.0.
  • For SQL Server 2014 databases, you must install both SQL Server 2014 and the Microsoft ODBC Driver 11.0 for SQL Server.
  • For SQL Server 2016 databases, you must install both SQL Server 2016 and the Microsoft ODBC Driver 13.0 for SQL Server.
If you want to bind your application from the deployment machine, install the following additional software:
  • Microsoft .NET 3.5 framework, or later
  • SQL Server 2008 R2 or later System CLR Types
  • SQL Server 2008 R2 or later Shared Management Objects
Deployment SQL Server Machine
SQL Server 2008 R2 or later
Note: This can be the same machine as the deployment machine, but is not required to be.
Testing
For this version, HCO for SQL Server was tested with SQL Server 2008 R2, 2012, 2014, 2016,and 2017.

Database Access - Mainframe Batch Database Tools (MBDT)

Back to Top

Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Windows | X | X
OpenESQL
The MBDT toolset consists of OpenESQL applications, and are native code using ODBC. Please see the Database Access - OpenESQL section for further details.
Testing
For this version, MBDT was tested with:
  • DB2 LUW 10.5
  • Oracle 12.1
  • SQL Server 2012

Database Access - OpenESQL

Back to Top

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

Availability
Feature/Platform | Native and JVM COBOL 32-bit | Native and JVM COBOL 64-bit | PL/I 32-bit | PL/I 64-bit
x86-64 running Windows | X | X | X | X
XA Switch Module
The ODBC One-phase Commit, SQL Server, and PostgreSQL switch modules are provided and available on the same platforms as are indicated in the Availability section above.
Native COBOL and PL/I
  • OpenESQL supports access to relational databases using ODBC 3.0-compliant drivers
  • Refer to your driver vendor's documentation to determine whether your driver is suitable for use with OpenESQL
JVM COBOL
OpenESQL supports access to relational databases using JDBC 4.0-compliant JDBC drivers. The following table shows the tested DBMSs and their corresponding JDBC driver filenames:
Tested DBMS Versions | JDBC 4.0 Compliant Drivers
DB2 LUW 9.7

DB2 LUW 10.1

DB2 LUW 10.5

DB2 LUW 11.1

db2jcc4.jar (and db2jcc_license_cu.jar)
Oracle 11.2

Oracle 12.1

ojdbc6.zip1

ojdbc7.zip1

Microsoft SQL Server 2008 R2

Microsoft SQL Server 2012

Microsoft SQL Server 2014

Microsoft SQL Server 2016

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

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

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

  • If you are using a Java application server, it includes a JNDI server you can use to configure DataSource objects. This process is described in the Java documentation for the application server.
  • If you are not using a Java application server, or if you require a standalone JNDI server to configure DataSource objects for initial evaluation and development, see the To install and configure Simple-JNDI topic in this documentation set for instructions on downloading, installing, and configuring the open source JNDI server Simple-JNDI for this purpose.
Testing
For this version, OpenESQL was tested with:
  • Oracle 11.2 and 12.1
  • DB2 LUW 9.7, 10.1, 10.5, and 11.1
  • SQL Server 2008 R2, 2012, 2014, 2016, and 2017
  • EDB PostgreSQL 9.6
  • MySQL 5.7 (5.3 ODBC drivers only)
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.

Database Access - SQL Option for DB2

Back to Top

Availability
Feature/Platform | 32-bit
x86-64 running Windows | X
XA Switch Module
XDB XA switch modules are provided and are available for the Windows x86-64 32-bit platform.

Java Development Kit (JDK)

Back to Top

For COBOL JVM code and Java Interoperability, Oracle's Java Platform, Standard Edition (Java SE) 7, 8 (32 or 64-bit versions), and Java 9 (64-bit version only), and AdoptOpenJDK's OpenJDK 8 with Hotspot are supported. Oracle's Java Platform (64-bit) version 1.8 or later, or AdoptOpenJDK's OpenJDK 8 with Hotspot is required to run the Eclipse IDE. The minimum recommended version is Java 1.8.162 (64-bit), which the Windows product installation will install if it detects an older version. You can download Oracle's Java SE from Oracle's Web site and install it anywhere on your machine. Alternatively, you can download AdoptOpenJDK's OpenJDK 8 with Hotspot from AdoptOpenJDK's Web site and unpack the archive anywhere on your machine.

JCL Support - DSNREXX

Back to Top

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such.
Availability
Feature/Platform | 32-bit | 64-bit
x86-64 running Windows | X | X
OpenESQL
DSNREXX is supported in OpenESQL applications, and is native code using ODBC. See the Database Access - OpenESQL section in this topic for additional software requirements, and the DSNREXX Support topics for complete details.
Testing
For this version, DSNREXX was tested with:
  • DB2 LUW 10.5
  • SQL Server 2012

Mainframe Access - Endevor Support

Back to Top

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

Micro Focus Rumba

Back to Top

  • On Windows 8, in order to install Micro Focus Rumba you must have the Microsoft .NET Framework 3.5 Service Pack 1 installed.

WebSphere MQ

Back to Top

This product supports IBM WebSphere MQ version 7 and later.

Parent topic: System Requirements
Related concepts
Oracle RM Switch Module
Database Access
CCSID Conversion Tables
Deploying Native Applications
DSNREXX Support (Technology Preview)
Building RM Switch Modules
Related tasks
To install and configure Simple-JNDI
Related reference
Java Support Considerations for the Eclipse IDE
Related information
Hardware Requirements
Operating Systems Supported
Software requirements


Product Co-Existence

  • Enterprise Developer and Enterprise Server (or Enterprise Test Server) cannot coexist on the same machine.
  • Visual COBOL and Enterprise Developer cannot coexist on the same machine regardless of which IDE (Visual Studio or Eclipse) you install.
Parent topic: On Windows


Installation Restrictions and Requirements

Before starting the installation you should consider the following:

  • You need to be logged in with a user-ID that has write access to the registry structure under HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, and HKEY_CURRENT_USER so the installation software can set the environment appropriately. You also need to be logged on with Administrator privileges.
Parent topic: On Windows


On UNIX

  • System Requirements
Parent topic: Before Installing


System Requirements

  • Hardware Requirements
  • Operating Systems Supported
  • Software Requirements for Micro Focus Enterprise Developer UNIX Components
  • Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components
  • UNIX and Linux Installer Issues
  • Hardware Requirements
  • Software Requirements
Parent topic: On UNIX
Parent topic: Before Installing


Hardware Requirements

The disk space requirements for Micro Focus Enterprise Developer UNIX Components 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 | 533 MB | 2.13 GB | 1.07 GB | 41 MB
HP IA | Micro Focus | 953 MB | 3.81 GB | 1.90 GB | 79 MB
System Z running Red Hat Linux | Micro Focus | 425 MB | 1.70 GB | 850 MB | 39 MB
System Z running Red Hat Linux | RPM | 117 MB | 468 MB | 234 MB | 39 MB
x86-64 running Red Hat Linux | Micro Focus | 540 MB | 2.16 GB | 1.08 GB | 50 MB
x86-64 running Red Hat Linux | RPM | 154 MB | 616 MB | 308 MB | 50 MB
ppc64le running Red Hat Linux | Micro Focus | 303 MB | 1.21 GB | 606 MB | 1 MB
ppc64le running Red Hat Linux | RPM | 62 MB | 248 MB | 124 MB | 1 MB
SPARC running Solaris | Micro Focus | 519 MB | 2.08 GB | 1.04 GB | 38 MB
x86-64 running Solaris | Micro Focus | 472 MB | 1.89 GB | 944 MB | 33 MB
System Z running SUSE SLES | Micro Focus | 306 MB | 1.22 GB | 612 MB | 39 MB
System Z running SUSE SLES | RPM | 59 MB | 236 MB | 118 MB | 39 MB
x64 running SUSE SLES | Micro Focus | 384 MB | 1.54 GB | 768 MB | 50 MB
x64 running SUSE SLES | RPM | 76 MB | 304 MB | 152 MB | 50 MB
ppc64le running SUSE SLES | Micro Focus | 272 MB | 1.09 GB | 544 MB | 1 MB
ppc64le running SUSE SLES | RPM | 50 MB | 200 MB | 100 MB | 1 MB
Parent topic: System Requirements


Operating Systems Supported

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

Parent topic: System Requirements
Related information
Hardware Requirements
Software Requirements
Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components


Software Requirements on UNIX

Software Requirements for Micro Focus Enterprise Developer UNIX Components

These are the software requirements for Micro Focus Enterprise Developer UNIX Components:

  • The "ed", "sed" and "tar" utilities must be installed and added to the PATH.
  • 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.

    Library | 32-bit Library Name | 64-bit Library Name | Platform
    s390 | SUSE 12 | Red Hat 6.x | Red Hat 7
    glibc | glibc-*.i686 | glibc-*.x86_64 | glibc-*.s390 | X | X
    libgcc | libgcc-*.i686 | libgcc-*.x86_64 | libgcc-*.s390 | X | X
    libstdc++ | libstdc++-*.i686 | libstdc++-*.x86_64 | libstdc++-*.s390 | X | X
    glibc-locale | glibc-locale-32bit | glibc-locale-2 | X
    glibc-devel | glibc-devel-*.i686 | glibc-devel-*.x86_64 | glibc-devel-*.s390 | X | X
    elfutils-libelf | elfutils-libelf.i386 or elfutils-libelf.i686 | elfutils-libelf.x86-64 | N/A | X | X
    libelf-devel | elfutils-devel.i386 or elfutils-devel.i686 | elfutils-devel.x86-64 | N/A | X | X
    libelf-devel | libelf-devel-32bit-0.137-8.19 | libelf-devel-0.137-8.19 | N/A | X
    libelf1 | libelf1-32bit-0.137-8.19 | libelf1-0.137-8.19 | N/A | X
    gcc2 | gcc*.i686 | gcc*x86_64 | X | X | X | X
    ld2 | Binutils*.i686 | Binutils*x86_64 | X | X | X | X
    • ¹ On SUSE 12, you can only install the 64-bit version of Enterprise Developer. The glibc-locale-32bit library is still required by the SafeNet Sentinel licensed components.
    • * Additional libraries required to use the core_on_error runtime variable. The gdb packages (for the GNU Project Debugger) can be installed from the install media for your OS.
    • ** Operating system libraries required for PL/I support on both SUSE and Red Hat.
    • 2 On Red Hat these libraries are required to enable COBOL and PL/I to compile.
    • Libraries marked with an 'X' are not included in the platform and need to be installed separately.

    Visit the Red Hat Web site for more information.

  • 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.
  • Oracle's Java Platform (64-bit) version 1.8 or later, or AdoptOpenJDK's OpenJDK 8 (64-bit) are required to run the Eclipse IDE. The recommended minimum version is Java 1.8.162 (64-bit), which the Windows product installation will install if it detects an older version. Oracle's implementation of Java 7, 8 (32 or 64-bit versions), and Java 9 (64-bit version only), and AdoptOpenJDK's OpenJDK 8 are supported for executing JVM COBOL code, and for native COBOL and Java interoperability. You can download Oracle's Java from Oracle's Web site and install it anywhere on your machine. Alternatively, 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.
  • GNOME menus and buttons have been standardized across all applications so that icons are not displayed by default. To keep the icons and the look and feel of previous versions, enable the menus_have_icons property with the command:
    gconftool-2 --type boolean --set /desktop/gnome/interface/menus_have_icons true
Parent topic: System Requirements


Additional Software Requirements on UNIX

Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components

To ensure full functionality for some Enterprise Developer features, you might be required to obtain and install additional third-party software in addition to the prerequisite software installed automatically by the Enterprise Developer 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
  • CICS Web Services
  • Java Development Kit (JDK)
  • Database Access
  • Database Access - COBSQL (Pro*COBOL)
  • Database Access - HCO for DB2 LUW
  • Database Access - Mainframe Batch Database Tools (MBDT)
  • Database Access - OpenESQL
  • JCL Support - DSNREXX
  • 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, or AdoptOpenJDK's OpenJDK 8. 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. You can download AdoptOpenJDK's OpenJDK from AdoptOpenJDK's Web site.

Application server JCA support for Enterprise Server

Back to Top

Various Java EE versions are supported for the deployment of EJBs generated using the Interface Mapping Toolkit, as follows:

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

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

Application Servers | JDK (vendor) | Java EE
JBoss EAP 6.4 (AS 7.5) | 1.6, 1.7, 1.8 (Oracle), 1.8 (OpenJDK) | 6
Oracle WebLogic 10.3.5 | 1.5 (Oracle) | 5
Oracle WebLogic 12.1.1 | 1.6, 1.7, 1.8 (Oracle) | 6
Oracle WebLogic 12.2.1 | 1.8 (Oracle) | 7
IBM WebSphere 8.5 | 1.6, 1.7 (IBM) | 6
IBM WebSphere 8.5.5 | 1.7 (IBM) | 6
IBM WebSphere 9.0 | 1.8 (IBM) | 7
Tomcat 7.0.x* | 1.6, 1.7, 1.8 (Oracle), 1.8 (OpenJDK) |
*Apache Tomcat is an HTTP server and servlet container supporting Java Servlet and JavaServer Pages (JSP). Micro Focus Tomcat non-transactional support includes servlet generation with J2SE Beans; no transactional support is provided. Tomcat does not support the use of Enterprise Java Beans (EJBs) or resource adapters (RAs).

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 and CICS 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 6.4 | WebSphere 8.5 | WebSphere 8.5.5 | WebSphere 9.0 | WebLogic 10.3.5 | WebLogic 12.1.1, 12.2.1 | Tomcat 7.0.x1
AIX 6.1 on RS6000 | 32-bit2 | 32-bit2 |  | 32-bit | 32-bit | 32-bit | 32-bit
HP/UX 11.31 on Intel IA64 | 32- and 64-bit2 | 64-bit2 |  | 64-bit | 32- and 64-bit | 32- and 64-bit | 64-bit
Red Hat EL 6.2 on IBM390 | 32-bit2 | 32-bit2 |  | 32-bit | 32-bit | 32-bit | 32-bit
Red Hat EL 5.5 on AMD Opteron | 32-bit2 | 32-bit2 |  | 32-bit | 32-bit | 32-bit | 32-bit
Solaris 11 on AMD Opteron | 32- and 64-bit2 |  |  |  | 32- and 64-bit | 32- and 64-bit |
Solaris 10 on SPARC | 32- and 64-bit2 |  |  |  | 32- and 64-bit | 32- and 64-bit |
SUSE SLES 11 SP1 on IBM390 | 32-bit2 | 32-bit* |  | 32-bit | 32-bit | 32-bit | 32-bit
SUSE SLES 11 on AMD Opteron | 32-bit2 | 32-bit2 |  | 32-bit | 32-bit | 32-bit | 32-bit
SUSE SLES12 on PowerLinux LE |  |  | 64-bit |  |  |  |
1 Apache Tomcat is an HTTP server and servlet container supporting Java Servlet and JavaServer Pages (JSP). Micro Focus Tomcat non-transactional support includes servlet generation with J2SE Beans; no transactional support is provided. Tomcat does not support the use of Enterprise Java Beans (EJBs) or resource adapters (RAs). 2Supports both COBOL and CICS resource adapters. Also supports ECI.

Support for the following Java application servers using the following JDKs is planned for future release:

Application Servers | JDK (vendor) | Java EE | COBOL RA | CICS RAs and ECI
JBoss EAP 7.0 | 1.8 (Oracle), 1.8 (OpenJDK) | 7 | X | X
IBM WebSphere 8.5.5 (UNIX: all platforms) | 1.7, 1.8 (IBM) | 6 | X |
Tomcat 8.5.x* | 1.7, 1.8 (Oracle), 1.8 (OpenJDK) |  |  |
*Apache Tomcat is an HTTP server and servlet container supporting Java Servlet and JavaServer Pages (JSP). Micro Focus Tomcat non-transactional support includes servlet generation with J2SE Beans; no transactional support is provided. Tomcat does not support the use of Enterprise Java Beans (EJBs) or resource adapters (RAs).
Note: If you experience any incompatibility issues when using these third-party products with Enterprise Developer, please report them to SupportLine. Until full support is available, a timely effort to resolve incompatibility issues will be made; however, Micro Focus does not guarantee full compatibility until we have fully tested our software updates against these products.

CICS Web Services

Back to Top

To use CICS Web Services, you must first install the IBM CCSID conversion tables. See Install and Configure CCSID Conversion Tables for details.

Java Development Kit (JDK)

Back to Top

For COBOL JVM code and Java Interoperability, Oracle's Java Platform, Standard Edition (Java SE) 7, 8 (32 or 64-bit versions), and Java 9 (64-bit version only), and AdoptOpenJDK's OpenJDK 8 with Hotspot are supported. Oracle's Java Platform (64-bit) version 1.8 or later, or AdoptOpenJDK's OpenJDK 8 with Hotspot is required to run the Eclipse IDE. The minimum recommended version is Java 1.8.162 (64-bit), which the Windows product installation will install if it detects an older version. You can download Oracle's Java SE from Oracle's Web site and install it anywhere on your machine. Alternatively, you can download AdoptOpenJDK's OpenJDK 8 with Hotspot from AdoptOpenJDK's Web site and unpack the archive anywhere on your machine.

Database Access

Back to Top

Before you can use Enterprise Developer to develop and deploy SQL applications that use COBSQL, HCO for DB2 LUW, 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
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.
Certification of RDBMS Precompilers for Native COBOL
Certification of RDBMS precompilers with Micro Focus products is the responsibility of the RDBMS vendor, rather than Micro Focus. Certification information can be found within the relevant Oracle documentation. If you have an Oracle MetaLink account (http://metalink.oracle.com), document # 43208.1 provides details of all language compilers certified by Oracle for use with their precompilers.
Preprocessors
COBSQL supports the following database preprocessors:
  • Sybase Open Client Embedded SQL/COBOL Version 11.1 or later
  • Oracle Pro*COBOL Version 11.2 (11gR2) or later
  • Informix Embedded SQL/COBOL Version 7.3 or later
Compiling
On x86 and x86-64 platforms, when compiling with COBSQL for use with Oracle, do not use the COBSQL directive option NOMAKESYN, since this directive results in COMP host variables, and on Intel platforms these are incompatible with the native byte order expected by Oracle.
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 (applies to UNIX environments only). 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 11.2, 12.1, and 12.2. Oracle 12.2 is available and tested on the following platforms:
  • x86-64 running Red Hat Linux
  • x86-64 running SUSE Linux
  • x86-64 running Solaris
  • SPARC running Solaris

Database Access - HCO for DB2 LUW

Back to Top

Note: HCO for DB2 LUW is supported for native COBOL only.
Availability
Feature/Platform | Native COBOL 32-bit | Native COBOL 64-bit | PL/I 32-bit | PL/I 64-bit
x86-64 running Red Hat Linux | X | X | X | X
x86-64 running SUSE Linux | X | X | X | X
IBM System p running AIX | X | 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 | X | X
XA Switch Module
The DB2 XA switch module is provided and is available on the same platforms as are indicated in the Availability section above.
Certification of RDBMS Precompilers for Native COBOL
Certification of RDBMS precompilers with Micro Focus products is the responsibility of the RDBMS vendor, rather than Micro Focus. You can find IBM document certification information for DB2/COBOL applications within the IBM Information Center for DB2, in the topic Support for database application development in COBOL.
Preprocessor
HCO for DB2 LUW supports the following database preprocessors:
  • IBM DB2 LUW Version 9.7 or later
  • IBM DB2 Connect Version 9.7 or later
Host Compatibility Option (HCO)
Host Compatibility Option requires that you have one of the following software products installed and configured:
  • IBM Database Connect
  • IBM DB2 LUW Personal Edition or DB2 Express-C
  • DB2 LUW Workgroup or Enterprise Edition

You must also install the DB2 Application Development Client (formerly called DB2 SDK) or you will not be able to compile any DB2 programs.

Testing
For this version, HCO for DB2 LUW was tested with versions 9.7, 10.1, 10.5, and 11.1.

JCL Support - DSNREXX

Back to Top

Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such.
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
OpenESQL
DSNREXX is supported in OpenESQL applications, and is native code using ODBC. See the Database Access - OpenESQL section in this topic for additional software requirements, and the DSNREXX Support topics for complete details.
Testing
For this release, DSNREXX was tested with DB2 LUW 10.5.

Database Access - Mainframe Batch Database Tools (MBDT)

Back to Top

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
OpenESQL
The MBDT toolset consists of OpenESQL applications, and are native code using ODBC. Please see the Database Access - OpenESQL section for further details.
Testing
For this release, MBDT was tested with DB2 LUW 10.5 and Oracle 12.1

Database Access - OpenESQL

Back to Top

COBOL 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
PLI Availability
Feature/Platform | PL/I 32-bit | PL/I 64-bit
x86-64 running Red Hat Linux | X | X
x86-64 running SUSE Linux | X | X
IBM System p running AIX | X
SPARC running Solaris | X | X
XA Switch Module
The ODBC One-phase Commit switch module is provided and is available on the same platforms as are indicated in the COBOL 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 and PL/I
  • OpenESQL supports access to relational databases using ODBC 3.0-compliant drivers
  • Refer to your driver vendor's documentation to determine whether your driver is suitable for use with OpenESQL
JVM Managed COBOL
OpenESQL supports access to relational databases using JDBC 4.0-compliant JDBC drivers. The following table shows the tested DBMSs and their corresponding JDBC driver filenames:
Tested DBMS Versions | JDBC 4.0 Compliant Drivers
DB2 LUW 9.7

DB2 LUW 10.1

DB2 LUW 10.5

DB2 LUW 11.1

db2jcc4.jar (and db2jcc_license_cu.jar)
Oracle 11.2

Oracle 12.1

ojdbc6.zip*

ojdbc7.zip*

Microsoft SQL Server 2008 R2

Microsoft SQL Server 2012

Microsoft SQL Server 2014

Microsoft SQL Server 2016

sqljdbc4.jar
EDB PostgreSQL 9.6 | 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 11.2 and 12.1
  • DB2 LUW 9.7,10.1,10.5, and 11.1
  • SQL Server 2008 R2, 2012, 2014, 2016, and 2017
  • PowerLinux LE using DB2 LUW 10.5 only
  • EDB PostgreSQL 9.6 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.

WebSphere MQ

Back to Top

IBM WebSphere MQ version 7 and later.

Parent topic: System Requirements
Related concepts
IBM DB2 RM Switch Module
Database Access
DSNREXX Support (Technology Preview)
Related tasks
To install and configure Simple-JNDI
Related information
Hardware Requirements
Operating Systems Supported
Software Requirements


UNIX and Linux Installer Issues

Installing on Linux

On Linux, the RPM installer for Enterprise Developer for Eclipse installs a 64-bit version of Java. When you start the installation, if the 32-bit version of Java is already installed on your Linux machine, you might not be able to install Enterprise Developer. This is a known issue with the Oracle Java installers for Linux which prevents you from installing both the 32-bit and the 64-bit versions of Java on the same machine. To work around this problem:

  • Download the 64-bit Java distribution in a compressed .tar format from the Oracle Web site.
  • Untar the distribution into a location different from the one used for the 32-bit Java version. For example, untar in /usr/local/java64 and not in /usr/local/java.
  • Set JAVA_HOME and LD_LIBRARY_PATH to the 64-bit version of Java so that it is used to install and run Enterprise Developer.

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 Enterprise Developer 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: System Requirements
Parent topic: Before Installing
Parent topic: Known Issues and Restrictions


Basic Installation

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

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

  • Installing on Windows
  • Installing Micro Focus Enterprise Developer UNIX Components
Parent topic: Installation


Installing on Windows

Note:
  • This version of the product is a full install.
  • If you have an earlier version of Enterprise Developer installed on your machine, check Installing as an Upgrade before you start the installation.

These are the steps to install Enterprise Developer:

  1. Run the ede_40.exe file and follow the wizard instructions to complete the installation.

    By default, this installs Enterprise Developer in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer folder and installs a full version of Eclipse 4.7 64-bit, with the Micro Focus plugins already installed, in the C:\Users\Public\Micro Focus\Product Name\eclipse directory.

    The setup file installs any missing prerequisite software as listed in the topic Software Requirements.

Note: See Advanced Installation Tasks for information about non-default installation tasks. For example, to stop the product installation from installing the version of Java shipped with the product, run the setup file from the command line with the skipjre=1 command line option; otherwise, if the installation detects a version of Java older than the shipped version, it will install the shipped version.
Parent topic: Basic Installation
Related reference
System Requirements
Installing as an Upgrade


Installing on UNIX

Installing Micro Focus Enterprise Developer UNIX Components

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_entdev_4.0_platform
  2. Run the installer from the Process User ID login:
    ./setup_entdev_4.0_platform

    When the installer starts it will prompt you to enter the superuser password so it can perform operations that require root permissions.

    The COBOL environment is installed by default into /opt/microfocus/EnterpriseDeveloper, (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_entdev_4.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
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.

  • On Windows
  • On UNIX
  • Installing on Microsoft Terminal Server and Citrix
  • Mainframe Access Installation Guide
Parent topic: Installation


On Windows

  • Installing as an Upgrade
  • Enterprise Developer Installation Options
    You can install Micro Focus products silently by specifying /q at the command line and using command line parameters to specify the installation directory (installfolder=path), user information, and which features to install. You must execute the command with superuser permissions.
  • Installing and Licensing Micro Focus Rumba
  • Installing Enterprise Developer into other instances of Eclipse
Parent topic: Advanced Installation Tasks


Installing as an Upgrade

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

  • If you have been using the mainframe components of Enterprise Developer for z Systems, see Installing z/Server as an Upgrade for recommendations about how to upgrade your z/Server installation. Also, check Backward Compatibility of AWM Models for information about changes that affect your existing AWM models.
  • Before installing this release as an upgrade, ensure you create a back-up of your Enterprise Server configuration. To do this, on the Enterprise Server Administration home page, click Export and then select Export Enterprise Server configuration and Security Manager definitions. This creates a backup folder in the c:\programdata\micro focus\Enterprise Developer\MFDS. You can restore the Enterprise Server configuration after installing this release - click Import on the Enterprise Server Administration home page.
Parent topic: On Windows
Related tasks
JVM COBOL support


Enterprise Developer Installation Options

You can install Micro Focus products silently by specifying /q at the command line and using command line parameters to specify the installation directory (installfolder=path), user information, and which features to install. You must execute the command with superuser permissions.

To see what parameters you can use, execute the following from the command line:

install-file /help

where install-file for the following products is as follows:

Enterprise Developer
ede_40.exe

See the Examples section further in this topic for examples of some of the parameters you can use.

Directory considerations

  • You must have read and write access for every directory accessed during the installation.
  • You can override the default installation folder using the InstallFolder parameter.
  • Installing creates a group of log files prefixed Micro_Focus_ in the %temp% folder, by default. To change the location or name, use the /log parameter on your Setup command line and specify the path and file name, for example:
    /log drive:\path\LogFilename

Installing silently

Use the /q parameter to install silently:

start /wait install-file.exe /q [parameters]

Examples

  • To silently install Enterprise Developer into a directory other than the default:
    start /wait ede_40.exe /q InstallFolder=c:\DirectoryName
  • If you want to silently install the Eclipse IDE in a location other than the default, execute:
    start /wait ede_40.exe /q InstallFolder2=c:\EclipseInstallDirectory
  • To skip installing JRE when installing Enterprise Developer:
    start /wait ede_40.exe /q skipjre=1
  • To silently install Rumba during the silent install of Enterprise Developer:
    start /wait ede_40.exe /q RumbaCheckbox=1
Parent topic: On Windows


Installing and Licensing Micro Focus Rumba

The Enterprise Developer setup file includes Micro Focus Rumba 9.5 which you can install as an optional component. The license for Enterprise Developer also licenses all components of Rumba (for example, Rumba Office, Rumba for Mainframe, UNIX, AS400, and the TN3270 mainframe display within Enterprise Developer).

Note: Micro Focus Rumba versions 8.3 or later provide integration with Enterprise Developer where you can use a Rumba TN3270 Mainframe Display within the IDE in order to run applications.

Installation considerations:

  • If you are installing Enterprise Developer onto a machine that does not have Rumba installed, it is recommended that you select the Rumba option when you start the installation. This installs all of the components of Rumba including the one you need to establish a mainframe 3270 connection (Rumba for Mainframe).
  • Installing Rumba 9.5 as part of this release of Enterprise Developer will update any older version of Rumba installed and licensed on your machine.
    Note: Micro Focus recommends that you upgrade older versions of Rumba to the one installed with Enterprise Developer. However, if you want to keep an older version of Rumba, you can choose not to install Rumba when you start the Enterprise Developer installation. In this case, the TN3270 Mainframe Display will not be available for use from within Enterprise Developer.
  • If a version of Rumba more recent than version 9.5 is installed and licensed on your machine, you can choose not to install Rumba as part of the Enterprise Developer installation. The TN3270 Mainframe Display provided with this version of Rumba may be supported within Enterprise Developer but might not have been tested.
Parent topic: On Windows


Installing into other instances of Eclipse

Installing Enterprise Developer into other instances of Eclipse

Enterprise Developer ships with Eclipse 4.7 (64-bit).

After installing Enterprise Developer, you can then also install it in other instances of Eclipse available on the same machine. The supported version of Eclipse are 4.6, 4.7, and 4.8 (requires Enterprise Developer 4.0 Patch Update 4 or later) for both 32-bit and 64-bit Eclipse.

Note: You must use the Eclipse IDE for Java EE Developers package. This includes all the tools that Enterprise Developer requires.

To assist you with automatically installing the Micro Focus plug-ins into other instances of Eclipse, Enterprise Developer provides an installation utility, installeclipseplugins.bat available in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\installer folder.

To install Enterprise Developer into another instance of Eclipse:

  1. Start an Enterprise Developer command prompt.
  2. At the command prompt, navigate to the location of the install utility: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\installer.
  3. Run the install utility from the command prompt using the following syntax:
    installeclipseplugins -eclipse <EclipsePath> -version <version> [-cobdir <CobdirPath>] [-nosplash] [-installsubclipse]

    where:

    EclipsePath
    Full path to the installation directory of the instance of Eclipse you are installing into.
    version
    Version number of the instance of Eclipse that you are installing into. The valid version numbers are 4.6, and 4.7 for both 32-bit and 64-bit Eclipse.
    CobdirPath
    Optional - the full path to the installation directory of Enterprise Developer. If this is not specified, the COBDIR environment variable is used.
    -nosplash
    Optional - if set, the installation does not replace the existing splash screen. A non-default Eclipse splash screen is not replaced, regardless of this setting.
    -installsubclipse
    Optional - if set, Subclipse is installed to the specified Eclipse location.
    Note: To install into a 32-bit version of Eclipse, ensure that your PATH is set to a 32-bit version of Java. When installing into a 64-bit version of Eclipse, ensure that your PATH is set to a 64-bit version of Java. If you are installing into Eclipse Neon then you must use Java 1.8 for the installation to function correctly. The default COBDIR location on Windows is C:\Program Files (x86)\Micro Focus\Enterprise Developer. Alternatively, you can specify COBDIR from the command line.

    Running the utility installs the Enterprise Developer plug-ins into the specified version of Eclipse.

    For example, to install Enterprise Developer into an instance of Eclipse 4.6 available in the c:\eclipse folder, run the install utility with the following parameters:
    installeclipseplugins -eclipse c:\eclipse -version 4.6 -nosplash
Parent topic: On Windows
Related concepts
Software requirements
Related tasks
Remote Development
JVM COBOL support
Related reference
Java Support Restrictions


On UNIX

  • Installing as an Upgrade
  • Micro Focus Enterprise Developer UNIX Components Installation Options
  • RPM Installer
Parent topic: Advanced Installation Tasks


Installing as an Upgrade

This release works concurrently with the previous version of Micro Focus Enterprise Developer UNIX Components, 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 Micro Focus Enterprise Developer UNIX Components installer with the –installlocation option:

  1. Execute the following command:
    ./InstallFile -installlocation="/opt/microfocus/EnterpriseDeveloper"
    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: On UNIX
Parent topic: Advanced Installation Tasks


UNIX Installation Options

Micro Focus Enterprise Developer UNIX Components 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_entdev_4.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: On UNIX
Parent topic: Advanced Installation Tasks


RPM Installer

In addition to its proprietary installer for installing Enterprise Developer on UNIX and Linux, Micro Focus provides a standard RPM installer for installing Enterprise Developer 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 Enterprise Developer supports all the RPM functionality.

  • Using the RPM Installer
  • Other RPM Installer Options
  • Uninstalling Using the RPM Installer
Parent topic: On UNIX
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 Enterprise Developer 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 Enterprise Developer:

  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:

On SuSE 11 only:

cd $HOME
mkdir -p $HOME/rpmdb
rpm --initdb --dbpath $HOME/rpmdb
MFCMD="-noroot" rpm --root $HOME --dbpath rpmdb -i --nodeps --prefix=$HOME/VisualCOBOL

On SuSE 12 and Red Hat platforms:

cd $HOME
mkdir -p $HOME/rpmdb
rpm --initdb --dbpath $HOME/rpmdb
MFCMD="-noroot" rpm --dbpath $HOME/rpmdb -i --nodeps --prefix=$HOME/VisualCOBOL

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


Installing on Microsoft Terminal Server and Citrix

Note: This document is a work-in-progress. Check the documentation for Enterprise Developer in the Product Documentation section of the Enterprise Developer SupportLine Web site for its most recent version.

Microsoft Terminal Server and Citrix (TS/Citrix) are environments for running multiple instances of a single user product. They are not platforms where a single-user product can be made to perform as a multi-user product.

When running Enterprise Developer on TS/Citrix machine, there might be some implications to components of Enterprise Developer which could cause potential conflicts between a ‘per-user session’ compared to the standard ‘per machine’ setup. The following components of Enterprise Developer require special configuration:

  • Eclipse workspaces and projects
  • The Enterprise Server component - the Run-Time System product for JCL, CICS and IMS operations
  • The database management service

You can use Enterprise Developer with TS or with any Citrix version certified for use with Eclipse; however, a separate end-user license is required for each user who accesses Enterprise Developer, even if it is running on a single machine. See your End User License Agreement for clarification.

Note: Micro Focus Enterprise Developer does not officially support TS/Citrix. However, it will run on any prerequisite Operating System that is supported under TS/Citrix.

Capacity planning

Multi-user capacity planning for TS/Citrix does not scale linearly, and the calculations required for this planning are not directly related or specific to any Micro Focus technology. Micro Focus recommends that you consult with Microsoft or Citrix Systems, respectively, about the server sizing and capacity planning, based on hosting the required number of “rich” Windows 7 or Windows 8 desktops (e.g. using a singleton desktop build as a baseline).

Installing Enterprise Developer

To install Enterprise Developer for use with TS/Citrix:

  1. Log on to the physical terminal or Citrix server with a user ID that has administrator privileges.
  2. Use the download links in your Electronic Product Delivery email.
  3. Follow the links for the installation instructions and the End User License Agreement.

Configuring Enterprise Developer

Follow the links below for details on how to configure the individual Enterprise Developer components.

  • Customizing the Installation, the Workspace and the Projects
  • Enterprise Server Installation Options
  • Configuring SQL Option for DB2 (XDB) for Multi-User Environments
  • Configuring Other Components
Parent topic: Advanced Installation Tasks


Customizing the Installation, the Workspace and the Projects

Using Enterprise Developer for Eclipse under TS/Citrix

For considerations about how to use Eclipse under TS/Citrix refer to the Eclipse product help.

Micro Focus recommends you set up Enterprise Developer for Eclipse so that each user has their own configuration area and you make the configuration folder within the Eclipse installation read-only. (Enterprise Developer for Eclipse is installed on the TS/Citrix machine into %ProgramFiles(x86)%\Micro Focus\Enterprise Developer with the Eclipse installation stored in C:\Users\Public\Micro Focus\Enterprise Developer\eclipse.)

To ensure that each user will have their own configuration area, you need to set up Eclipse as follows:

  1. On the TS/Citrix machine, start Enterprise Developer once, make any required customizations to the IDE and then close it.
  2. Using Windows Explorer, navigate to C:\Users\Public\Micro Focus\Enterprise Developer\eclipse and open the eclipse.ini file with an editor.
  3. Add the following code before the -vmargs entry:
    -configuration
@user.home\EclipseConfig
  4. Using Windows Explorer, navigate to the Eclipse installation folder and from the folder properties make the configuration folder Read Only for the group that will work with Enterprise Developer for Eclipse.

This ensures that each user that starts Enterprise Developer for Eclipse under TS/Citrix can only see their own workspaces and that they have their own EclipseConfig folder specified by the eclipse.ini file.

Eclipse workspaces

An Eclipse workspace is a folder on the disk where the project and application files are stored. The default location for an Eclipse workspace is in the user's area (for example, c:\users\username\). It is not possible to share workspaces so each user must have their own.

We suggest that you create Eclipse workspaces in an area on a shared network drive, naming each workspace folder with an individual user ID.

Also provide a startup script that maps the drive dynamically using share names derived from the user ID.
Tip: Use the net use command to connect to, remove and configure the connections to the mapped drives.

Template projects

Create and configure template projects to distribute among your users. Templates must not include fully qualified paths. You can store the projects in a source control system and make them available so that individual users can import them into their own workspace.

Parent topic: Installing on Microsoft Terminal Server and Citrix


Enterprise Server Installation Options

When you install Enterprise Developer, the setup file also installs the Enterprise Server component on the same machine. There are different ways in which you can configure and use Enterprise Server regions in TS/Citrix environments. This topic outlines two of the methods and explains what the implications of choosing them are:

  • Use the Enterprise Server component as part of Enterprise Developer installed on the TS/Citrix machine
  • Install Enterprise Server or Enterprise Test Server on a separate server

Use the Enterprise Server component as part of Enterprise Developer installed on the TS/Citrix machine

On the client machines, the developers each use a clone of Enterprise Developer. They also use a clone of Enterprise Server to create and manage multiple server instances as required.

While this option provides the greatest flexibility, it also consumes the largest footprint per user.

Install Enterprise Server or Enterprise Test Server on a separate server

You can install Enterprise Server 1 or Enterprise Test Server2 on a separate server that does not have TS/Citrix installed. By default, Enterprise Server installs and runs as a single-instance product and, within an Enterprise Server, you can operate a number of server instances. Each server provides session and state management for COBOL applications, as well as optionally interfacing with external resource managers to coordinate resource updates.

There are two ways to provide server instances to the developers using Enterprise Developer on the TS/Citrix machine:

  • Configure and configure one server instance per developer by specifying different ports. We recommend defining five-digit port numbers where digits one through three identify the developer and four through five identify a unique port. For example: port number 10123 defines a TN3270 listener for developer 1, and port number 10223 defines a TN3270 listener for developer 2.

    This option provides a dedicated enterprise server for testing purposes for each developer, but restricts each developer to that one enterprise serve instance.

    This scenario creates the largest footprint per developer.

    Or:

  • Create and configure one server instance per application for use by a single development team. Use a different port number for each instance as explained above, using the first three digits to differentiate between applications.

Parent topic: Installing on Microsoft Terminal Server and Citrix
1 Micro Focus Enterprise Server provides full application server support for COBOL applications that require high-performance and mainframe subsystem emulation. Enterprise Server is designed as a multi-user environment.
2 Micro Focus Enterprise Test Server is an IBM mainframe application test execution environment on Windows. Enterprise Test Server enables mainframe IT organizations to perform a variety of pre-production testing on low cost commodity hardware, avoiding unnecessary cost and delay. Built on proven technology, Enterprise Test Server exponentially expands the test capacity and enables testing to scale up easily to meet delivery timelines and quality standards driven by today's business requirements.


Configuring SQL Option for DB2 (XDB) for Multi-User Environments

SQL Option for DB2 in Enterprise Developer supports scenarios where multiple users use a single XDB Server installed on a TS/Citrix server. Typically, users in such environments would require their own private working locations so they can be isolated from each other's activity on the TS/Citrix server and might require different XDB configuration settings. SQL Option for DB2 provides support for this.

The configuration options for XDB Server are stored in the xdb.ini configuration file installed in the Windows protected area in C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg.

xdb.ini contains both client-side and server-side settings for the XDB tools.

Changing the server-side settings

In most cases, it is not necessary to change XDB Server's server-side settings. If you need to change these settings, however, it is important that you use the XDB tools to modify the xdb.ini file as the tools run with administrator's privileges. This helps avoid some possible issues with Windows virtualizing files in the protected areas that you try to edit without administrator's privileges.

See Changing the Main XDB Server Configuration File.

Changing the client-side settings

In multi-user environments such as TS/Citrix, it is important to provide individual users with their own client-side configuration options for XDB. To cater for that, Enterprise Developer provides a utility, XDBSetup, which creates a private XDB configuration file for each user in their local Windows folder on the TS/Citrix machine.

Users would run XDBSetup before they start using any of the XDB components on the TS/Citrix server. They can then use the XDB Client Options utility (XOPT40N) to customize their own version of xdb.ini and specify any required client-side run-time options and a temporary space for the client-side tools. For example, they might want to customize various options such as the isolation level, the lock timeout (for example, if they want a longer record lock timeout for testing), the data formats (if they want a different date format to test the software for internationalization issues), the SQLWizard configuration, and the private area for saved files.

XDBSetup also creates some entries in the user's specific area in the registry which point to the location of the private xdb.ini file. This ensures that XDB Server will use the main xdb.ini file installed under the c:\ProgramData folder, while any of the XDB tools that individual users start will use the private xdb.ini files that users might have customized according to their own preferences.

See Creating a Private XDB Configuration File in a Multi-User Environment.

Configuring the private XDB Server options in batch

If all users must have the same environment and use a specific standard set of client-side options in their private xdb.ini files, a system administrator can set this up for them using a batch file. The batch file would execute XDBSetup to create the private xdb.ini files and then it would execute BOPT40N, the batch version of the XDB Client Options utility, to specify the same client-side options in each private xdb.ini file.

See Changing the Private XDB Server Configuration Files in Batch.

  • Creating a Private XDB Configuration File in a Multi-User Environment
  • Changing the Main XDB Server Configuration File
  • Changing the Private XDB Server Configuration Files in Batch
Parent topic: Installing on Microsoft Terminal Server and Citrix


Creating a Private XDB Configuration File in a Multi-User Environment

Before using XDB Server on a TS/Citrix machine, all users must first run the XDBSetup utility to create a private XDB Server configuration file, xdb.ini, in their local Windows folders.

To run the utility:

  1. Log in to the TS/Citrix machine using the Windows Remote Desktop Connection.
  2. Execute the following from an Enterprise Developer command prompt:
    XDBSetup

    See Syntax of the XDBSetup command for more details.

This creates a standard xdb.ini file in the user's Windows home directory, in c:\Users\username\AppData\Roaming\Micro Focus\Enterprise Developer\mfsql\, for which the user does not need administrator's credentials to change the file.

This also creates some registry entries in the user's specific area which point to the location of the private xdb.ini file. When any of the XDB tools are executed, they check the user's registry settings for whether there is a private configuration file before they check the local machine registry settings which store the location of the main XDB Server configuration file.

Syntax of the XDBSetup command

The XDBSetup utility can run in either an interactive or unattended mode. Use the following syntax to execute the utility:

XDBSetup [-u|--unattended]

Where you can specify the following options:

No options
XDBSetup executes in an interactive mode. You receive some pop-up windows confirming whether the operation completed successfully, prompting whether to overwrite a previously installed xdb.ini, and possibly showing any status or error messages.
-u, --unattended
XDBSetup executes in an unattended mode.

Log files:

  1. A log of the commands activity is output to the standard error output handle.
  2. If you need to receive any standard errors, specify ">" to redirect the standard output. To redirect any standard errors, use "2>" as a redirection symbol. If this is not specified, any messages are displayed in the command prompt.
Parent topic: Configuring SQL Option for DB2 (XDB) for Multi-User Environments


Changing the Main XDB Server Configuration File

The XDB Server configuration file, xdb.ini, is installed in a Windows protected location - in C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg, by default. You need administrator's privileges to edit the file to help avoid some problems that Windows file virtualization can cause.

Micro Focus recommends that you use the XDB tools to edit xdb.ini because the XDB tools include a Windows manifest that requests administrative credentials for updating files in the Windows protected areas. You need to run the tools from the command line and specify xdb.ini as an argument. For example, if you use the XDB Client Options utility, execute:

XOPT40N /i"C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\xdb.ini"

Avoiding Windows virtualization issues

Files that reside in the Windows protected locations, such as xdb.ini, that reside in the Windows protected locations require that you edit them with administrative privileges. If you use utilities such as Notepad that do not request administrator's credentials, Windows file virtualization does not save the modifications in the actual file you edit but creates a copy of the file in the %userprofile%\AppData\Local\VirtualStore folder.

From then on, programs that run without administrative credentials use the file in the VirtualStore folder while those that run with administrative credentials use the actual xdb.ini file which can lead to some confusing results.

Parent topic: Configuring SQL Option for DB2 (XDB) for Multi-User Environments


Changing the Private XDB Server Configuration Files in Batch

The XDB Client Batch Options command, BOPT40N, is a batch version of the XDB Client Options utility, XOPT40N.

You can use BOPT40N to modify the options in the xdb.ini file in batch. The syntax of the command is as follows:

bopt40n /pSection.Variable=Value

Where:

Section, Variable and Value indicate a section in xdb.ini, a variable in that section and the value you want to set the variable to.

Note: If any of Section, Variable or Value include any spaces, you must use quotes around the entire argument. In the following example, the connection name has an embedded space in the section name so you need to use quotes around the entire argument in the command as follows:
bopt40n "/pConnection MYSERVER.CurrentLocation=MYLOC"
Parent topic: Configuring SQL Option for DB2 (XDB) for Multi-User Environments


Configuring Other Components

Micro Focus Rumba

To use Micro Focus Rumba on a TS/Citrix machine, ensure you install a license for this type of environment. Contact Micro Focus Sales for more information.

ViewNow Installation

To use ViewNow on a TS/Citrix machine, ensure you install a license for this type of environment. Contact Micro Focus Sales for more information.

Parent topic: Installing on Microsoft Terminal Server and Citrix


Mainframe Access Installation Guide

  • Introduction
  • Migration information
  • Installation requirements
  • Mainframe Access Configuration Utility
  • Host Installation
  • Troubleshooting
  • Customizing Data Connect
  • Configuring Access to External Library Management Systems
  • Configuring Access to Enterprise Server Mainframe Subsystem Support
  • Configuring z/Server feature support
  • Console Commands
  • Mainframe Access Messages
  • Configuration reference
Parent topic: Advanced Installation Tasks


Introduction

Mainframe Access is the OS/390 and z/OS server for Micro Focus development environments. It is a common component providing access to host resources for environments. One installation of Mainframe Access can support all of these products, providing connectivity to any number of DB2, IMS, and CICS systems located anywhere in an enterprise. It can also provide access to JES facilities, VSAM data sets, non-VSAM data sets, and data controlled by external library management products such as Panvalet, Librarian and Endevor.

Note: Mainframe Access is supported on z/OS and OS/390 environments. Unless specifically stated otherwise, references to z/OS also apply to OS/390.

Mainframe Access is data and transaction middleware that exploits the best features of workgroup and enterprise architectures. Micro Focus client programs can achieve the same performance levels, security, and data integrity that native mainframe applications deliver. The technology requires no changes to existing mainframe security, database, and transaction processing systems.

Mainframe Access provides access to:

  • DB2 for z/OS and OS/390 from clients.
  • CICS transactions and data from clients.
  • IMS data from clients via the Remote IMS Serve.
  • Non-relational data sets (VSAM, sequential, partitioned, etc.) from Mainframe Access Client.
  • Mainframe source control systems the Mainframe Access Client.
  • JES2 and JES3 from the Mainframe Access Client.

The figure below illustrates the relationships between Mainframe Access, its client systems and the z/OS services it provides.

Mainframe Access Architecture
  • Communications
  • Security
  • Data Set Services
  • Administration
  • Dependent Address Space Services
  • Mainframe Access Services
  • z/Server Feature
Parent topic: Mainframe Access Installation Guide


Communications

Mainframe Access provides comprehensive support for communications between PC clients and mainframe servers. Mainframe Access supports both TCP/IP and LU6.2 protocols. Mainframe Access' ability to bridge client TCP/IP connections to SNA LU6.2 server connections eliminates the need to install, configure and maintain SNA software packages on your client and server workstations. You can even access any DB2 for z/OS and OS/390 database using TCP/IP client connections, without the need for specific levels of DB2 software. Normally, DB2 Version 5.1, or later, is required for TCP/IP access. Mainframe Access, however, dynamically associates TCP/IP client connections with traditional LU6.2 DRDA connections to the DB2 systems.

Details are as follows:

  • TCP/IP Communications

    Mainframe Access has two TCP/IP socket listeners, one for TCP/IP clients using proprietary protocols and one for HTTP clients. The listeners accept client connection requests and examine the request data to determine the target server or internal destination for the request. When the target server is external, the client connection is then associated with an LU6.2 connection to the target server. For each target server type, Mainframe Access creates an initial number of tasks (z/OS TCBs) to handle the client/server connection association and processing. As each connection request arrives, Mainframe Access scans all available tasks for the target server and assigns the new connection request to the task with the lightest load. Mainframe Access' TCP/IP communications support can be used with IBM's z/OS TCP/IP implementation.

  • LU6.2 Communications

    When the first client request for an LU6.2 target server is received, Mainframe Access establishes the LU6.2 connection to the target server and negotiates session limits for the mode name associated with conversations (user transactions) to the target server. Mainframe Access then prepares an LU6.2 Function Management Header 5 (FMH-5) and allocates a conversation to the target server. The FMH-5 includes any LU6.2 security subfields (user ID and password) provided by the client and an LUW ID (SNA Logical Unit of Work ID) generated by Mainframe Access to manage the unit of work. Packaged user data to be processed by the transaction program follows the FMH-5. Acceptance of the conversation request by the target server starts the execution of the remote transaction program that will process the request. Response data from the remote transaction program is received by Mainframe Access and returned to the requesting client through the TCP/IP connection. If an LU6.2 communications error occurs during the request processing, Mainframe Access creates a special packet containing the LU6.2 error information and returns this to the requesting client.

Parent topic: Introduction


Security

Mainframe Access provides security features that interact with existing mainframe, operating system, and software security schemes. They are:

  • System Authorization Facility (SAF) interface

    Mainframe Access' security component uses the z/OS SAF interface to verify the user IDs and passwords and to check the authorization of users to access and update z/OS data sets. The Password Expiration Manager (PEM) feature of Mainframe Access is used by some client products; PEM allows PC end users to change their mainframe password using the SAF interface. Mainframe Access uses the SAF RACROUTE interface, and therefore exploits the existing security definitions in your external security manager, such as IBM's RACF, CA-ACF-2, and CA-Top Secret.

  • Encryption

    Mainframe Access and its associated products use several methods of encryption and encoding, including 32-bit private key algorithms, to manage the encryption and decryption of passwords and data.

  • Access List Checking

    You can use this optional feature to restrict client connections based on the IP address of the incoming client. You create an access list that specifies which client IP addresses, or ranges of addresses, are allowed or disallowed. Once you have enabled access list checking, Mainframe Access always validates the incoming client's IP address using your specifications and rejects unauthorized connection attempts.

  • Audit Logging

    Mainframe Access' optional audit logging facility records client login and logout information to a VSAM file. The information that is recorded includes user ID, login and logout times, target server, security status, and other data.

Parent topic: Introduction


Data Set Services

Mainframe Access' Data Set Services component uses state-of-the-art z/OS data management interfaces and facilities to provide file services for z/OS data sets. Data Set Services is designed to support the data access and security requirements of VSAM and non-VSAM data sets in a high-performance, multi-user environment.

Parent topic: Introduction


Administration

Mainframe Access provides functions to monitor and control the processing of work, for example:

  • Client Timeout Management

    Mainframe Access monitors the activity of clients that have a persistent connection to Mainframe Access for activity and disconnects them from the system after a length of idle time that you specify. It also releases all of the associated client resources on the mainframe, including LU6.2 conversations with server systems.

  • Trace Facility

    The tracing facility of Mainframe Access traces both the client flow (usually TCP/IP) and server flow (usually LU6.2) simultaneously, recording all control information and data to a single output destination. The trace information is very useful for diagnosing client/server communication problems. You can turn tracing on and off dynamically while Mainframe Access is running.

Mainframe Access provides a set of simple commands that you can use to monitor and control its run-time operations. You can use the commands from an z/OS console or from a Telnet client; for further information see the chapter Administration Using Console Commands.

You can use Mainframe Access' administrative interfaces to obtain comprehensive displays of current system activity and internal components of the system. The information provided extends from overall systems operation down to details about individual client/server connections. You can update important operational definitions and functions of the system, such as target server parameters, idle timeout value, access list specifications and trace activity while the system is running.

Parent topic: Introduction
Related information
Console Commands


Dependent Address Space Services

Mainframe Access' Dependent Address Space Services component uses standard z/OS facilities to create and manage auxiliary Application Server address spaces for program execution. This feature is used to automatically start a Mainframe Access Data Connect server address space during Mainframe Access initialization. The Data Connect server is also stopped automatically during Mainframe Access shutdown.

Parent topic: Introduction


Mainframe Access Services

Mainframe Access Drag & Drop and Source Connect functions are seamlessly integrated into the overall server workload. Mainframe Access' high-performance task, communications, transaction and data set management services are leveraged to increase the speed, reliability and scalability for these functions.

Parent topic: Introduction


z/Server Feature

Mainframe Access server fully incorporates the features provided by z/Server. See Configuring z/Server feature support for more information.

Parent topic: Introduction


Migration information

There have been some changes in the way that Mainframe Access is configured.

The first is combining MFA Server and the z/Server feature into a single installation package called Mainframe Access.

The second is that Mainframe Access Server now uses a XML configuration file, this has many benefits such as:

  • Reducing the number of configuration files required from four to one.
  • Making MFA Server easy to configure be defaulting parameters.
  • Making the configuration file easy to validate using an XML schema.

Micro Focus recommends using the new XML configuration file for new installations and have provided a command line migration utility that takes your old MFA Server configuration files (and z/Server XML configuration file, if required) and produces a new equivalent XML configuration file for you to use. See Migrating old configurations to new XML configuration for more information.

The new XML configuration file also contains the configuration required for the z/Server feature. It has strict requirements that you must be using the unified scheduler (and not the legacy STC Scheduler or CEA Scheduler) and that the holder task must be started as part of MFA Server and not be a standalone address space. Migration actions for these changes can be found in the Micro Focus Enterprise Developer 3.0 product Help.

Legacy configuration files are still supported (for both MFA Server and z/Server) and you are not required to change any of your existing JCL procedures. If you want to continue to use them, full details of their use are contained in the Micro Focus Enterprise Developer product Help.

  • General migration actions
  • Migration to use the XML configuration file
  • Additional migration for z/Server feature support
Parent topic: Mainframe Access Installation Guide


General migration actions

Changes to the product layout require that you make matching changed in your existing JCL procedures.

The changes can be summarized as:

  • For the MFA Started Task JCL Procedure:
    • Change DSNQUAL to point to HLQ.MFA
  • For MFAS Started Task JCL Procedure:
    • Change DSNQUAL to point to HLQ.MFA
  • For MFAAS Started Task JCL Procedure:
    • Change DSNQUAL to point to HLQ.MFA
  • Migration actions for MFA Started Task JCL procedure
  • Migration actions for MFAS Started Task JCL procedure
  • Migration actions for MFAAS Started Task JCL Procedure
Parent topic: Migration information


Migration actions for MFA Started Task JCL procedure

The following modification needs to be made to your existing JCL procedure:
  • Change DSNQUAL to point to HLQ.MFA

The change is highlighted in bold:

//MFA     PROC DSNQUAL='HLQ.MFA',
//             TAUQUAL='HLQ.ZSERVER',
//*            EAUTULIB='CAI.NDVRR15.CSIQAUTU',
//*            EAUTHLIB='CAI.NDVRR15.CSIQAUTH',
//*            ECONLIB='CAI.NDVRR15.CSIQLOAD',
//*            LIBRIAN='CAI.CAILIB',
//             TCPDATA='TCPIP.OS390.TCPDATA'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - MFA Started Task                  *
//*                                                                  *
//*------------------------------------------------------------------*
//* Q u i c k   C o n f i g u r a t i o n                            *
//*------------------------------------------------------------------*
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*                                                                  *
//* Change the TCPDATA value on the PROC statement to specify the    *
//* data set name used at your installation.  For CA TCPAccess you   *
//* may remove this symbolic parameter and the associated            *
//* DD statement.                                                    *
//*                                                                  *
//*------------------------------------------------------------------*
//* A d v a n c e d   C o n f i g u r a t i o n                      *
//*------------------------------------------------------------------*
//*                                                                  *
//* Endevor Considerations                                           *
//* ----------------------                                           *
//* If you will be using the Mainframe Access Server Endevor         *
//* support, change the EAUTHLIB and ECONLIB values                  *
//* on the PROC statement to specify the data set names of your      *
//* Endevor AUTHLIB and CONLIB program libraries.                    *
//* Remove the comment asterisks from the two PROC statements        *
//* and from the two DD statements in the STEPLIB concatenation.     *
//*                                                                  *
//* Librarian Considerations                                         *
//* ------------------------                                         *
//* If you will be using the Mainframe Access Server Librarian       *
//* support, change the LIBRIAN value on the PROC statement          *
//* to specify the data set name of your Librarian program library.  *
//* Remove the comment asterisk from the PROC statement and from     *
//* the DD statement in the STEPLIB concatenation.                   *
//*                                                                  *
//* Mainframe Call Generator Considerations                          *
//* ---------------------------------------                          *
//* If you will be using the Mainframe Call Generator feature,       *
//* remove the comment asterisk from the supplied MCGLIB DD          *
//* statement (the DD name must be MCGLIB) and change the data set   *
//* name to the name of your program library.                        *
//* If you have more than one program library for MCG the MCGLIB     *
//* DD can specify a concatenation of progam libraries.              *
//*                                                                  *
//* DBCS Code Page Considerations                                    *
//* -----------------------------                                    *
//* If you want DBCS code page support you must uncomment the EZA*   *
//* DD statments. The TCPIP.SEZADBCX data set is supplied by IBM     *
//* as a part of TCP/IP.                                             *
//*                                                                  *
//* z/Server Holder Considerations                                   *
//* -----------------------------                                    *
//* If you want to start the z/Server holder under MFA uncomment     *
//* the z/Server DD statements including on the STEPLIB.             *
//*                                                                  *
//*                                                                  *
//*                          Change Log                              *
//*                                                                  *
//*                                                                  *
//* ChangeID  Description                                            *
//* --------  -------------------------------------------------------*
//* V3.10     New DD statement - //ABNLIGNR DD DUMMY                 *
//* V4.00     Endevor changes                                        *
//* V5.00     zServer support                                        *
//* V6.00     Mainframe Access XML configuration support             *
//*------------------------------------------------------------------*
//*
//MFA     EXEC PGM=MFMFM,REGION=64M
//STEPLIB  DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//         DD  DISP=SHR,DSN=&TAUQUAL..AUTHLIB
//*---------------------------------------------------
//* Optional site-dependent Librarian program library
//*---------------------------------------------------
//*        DD  DISP=SHR,DSN=&LIBRIAN
//*---------------------------------------------------
//* Optional site-dependent Endevor program libraries
//*---------------------------------------------------
//*        DD  DISP=SHR,DSN=&EAUTULIB
//*        DD  DISP=SHR,DSN=&EAUTHLIB
//*CONLIB  DD  DISP=SHR,DSN=&ECONLIB
//DLL      DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//TABLES   DD  DISP=SHR,DSN=&DSNQUAL..TABLES
//XDBIN    DD  DISP=SHR,DSN=&DSNQUAL..CNTL(PARMS)
//SERVERS  DD  DISP=SHR,DSN=&DSNQUAL..CNTL(SERVERS)
//XDBACC   DD  DISP=SHR,DSN=&DSNQUAL..CNTL(ACCESS)
//CEEOPTS  DD  DISP=SHR,DSN=&DSNQUAL..CNTL(CEEOPTS)
//SYSPRINT DD  SYSOUT=A
//SYSTERM  DD  SYSOUT=A
//SYSUDUMP DD  SYSOUT=A
//XDBOUT   DD  SYSOUT=A
//DSNTRACE DD  SYSOUT=A
//DUMMY    DD  DUMMY
//ABNLIGNR DD  DUMMY                  revoke ABENDAID
//*
//*--------------------------------
//* zServer Holder
//*--------------------------------
//*
//*SYSEXEC  DD DISP=SHR,DSN=&TAUQUAL..EXEC
//*CONFXML  DD DISP=SHR,DSN=&DSNQUAL..CNTL(MFAXML)
//*CONFOSR  DD DISP=SHR,DSN=&TAUQUAL..OSR(MFAOSR)
//*DSPPRT   DD SYSOUT=*,LRECL=255
//*SYSOUT   DD SYSOUT=*
//*SYSTSIN  DD DUMMY
//*SYSTSPRT DD SYSOUT=*
//*
//*--------------------------------
//* Site-dependent TCP/IP data set
//*--------------------------------
//*
//SYSTCPD  DD  DISP=SHR,DSN=&TCPDATA
//*
//*-----------------------------
//* Optional audit log data set
//*-----------------------------
//*
//XDBAUDIT DD  DUMMY,DISP=SHR,DSN=&DSNQUAL..AUDIT
//*
//*---------------------------------------------------
//* Optional Mainframe Call Generator program library
//*---------------------------------------------------
//*
//*MCGLIB  DD  DISP=SHR,DSN=YOUR.MCG.PROGRAM.LIBRARY
//*
//*---------------------------------------------------
//* Optional DBCS code pages
//*---------------------------------------------------
//*
//*EZACHLAT DD  DSN=TCPIP.SEZADBCX(EZACHLAT),DISP=SHR
//*EZAHGLAT DD  DSN=TCPIP.SEZADBCX(EZAHGLAT),DISP=SHR
//*EZAKJLAT DD  DSN=TCPIP.SEZADBCX(EZAKJLAT),DISP=SHR
//*EZASCLAT DD  DSN=TCPIP.SEZADBCX(EZASCLAT),DISP=SHR
Parent topic: General migration actions


Migration actions for MFAS Started Task JCL procedure

The following modifications need to be made to your existing JCL procedure:

  • Change DSNQUAL to point to HLQ.MFA

The change is highlighted in bold:

//MFAS    PROC DSNQUAL='HLQ.MFA'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - Data Connect / FILESHARE          *
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*------------------------------------------------------------------*
//MFAS     EXEC PGM=MFDSTART,PARM='APPLID=MFA62ACB',
//         REGION=0M,TIME=1440
//STEPLIB  DD DISP=SHR,DSN=&DSNQUAL..LOADLIB
//         DD DSNAME=CEE.SCEERUN,DISP=SHR
//         DD DSNAME=CEE.SCEERUN2,DISP=SHR
//CEEOPTS  DD DISP=SHR,DSN=&DSNQUAL..CNTL(CEEOPTS)
//SYSUDUMP DD SYSOUT=*
//FSMSGA   DD SYSOUT=*             for IDCAMS
//FSMSGC   DD SYSOUT=*             for APPC errors
//FSMSGL   DD SYSOUT=*             for FileShare log
//VSAMCTL  DD DISP=SHR,DSN=&DSNQUAL..MFAVCTL
//ABNLIGNR DD DUMMY                        Turn off ABENDAID if present
//*--------------------------------------------------------------------
//* Place user DD cards beginning here
//*--------------------------------------------------------------------
Parent topic: General migration actions


Migration actions for MFAAS Started Task JCL Procedure

The following modifications need to be made to your existing JCL procedures:

  • Change DSNQUAL to point to HLQ.MFA

These changes are highlighted in bold:

//MFAAS   PROC DSNQUAL='HLQ.MFA',
//             TAUQUAL='HLQ.ZSERVER',
//*            EAUTULIB='CAI.NDVRR15.CSIQAUTH',
//*            EAUTHLIB='CAI.NDVRR15.CSIQAUTH',
//*            ECONLIB='CAI.NDVRR15.CSIQLOAD',
//*            CCMNZMF='YOUR.CMNZMF.LOAD',
//*            CSERCOMC='YOUR.SERCOMC.LOAD',
//*            EBIZLIB='YOUR.EBIZ.LOADLIB',
//             TCPDATA='TCPIP.OS390.TCPDATA'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - Application Server started task   *
//*                                                                  *
//*------------------------------------------------------------------*
//* Q u i c k   C o n f i g u r a t i o n                            *
//*------------------------------------------------------------------*
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*                                                                  *
//* Change the TCPDATA value on the PROC statement to specify the    *
//* data set name used at your installation.  For CA TCPAccess you   *
//* may remove this symbolic parameter and the associated            *
//* DD statement.                                                    *
//*                                                                  *
//*------------------------------------------------------------------*
//* A d v a n c e d   C o n f i g u r a t i o n                      *
//*------------------------------------------------------------------*
//*                                                                  *
//* Endevor Considerations                                           *
//* ----------------------                                           *
//* If you will be using this Application Server JCL to process      *
//* Endevor requests, change the EAUTHLIB and ECONLIB values         *
//* on the PROC statement to specify the data set names of your      *
//* Endevor AUTHLIB and CONLIB program libraries.                    *
//* Remove the comment asterisks from the two PROC statements        *
//* and the two DD statements in the STEPLIB concatenation.          *
//* If you are planning to use Procedure Groups to compile and       *
//* relink automatically, then increase DYNAMNBR=300 and eliminate   *
//* the pre-allocation of SYSPRINT and SYSTERM which conflict with   *
//* standard compile output names.                                   *
//*                                                                  *
//* Component Generator IMS Support                                  *
//* -------------------------------                                  *
//* If you will be using this Application Server JCL to run          *
//* your Component Generator eBiz programs,                          *
//* change the EBIZLIB value on the PROC statement to specify the    *
//* data set name of the load module library containing your eBiz    *
//* programs.  Remove the comment asterisks from the PROC statement  *
//* and the EBIZLIB DD statement.                                    *
//* If you have more than one eBiz program library you can change    *
//* EBIZLIB to be a concatenation of program library data sets.      *
//*                                                                  *
//* ChangeMan Considerations                                         *
//* -------------------------                                        *
//* If you will be using this Application Server JCL to process      *
//* ChangeMan requests, change the CCMNZMF and CSERCOMC values       *
//* on the PROC statement to specify the data set names of your      *
//* ChangeMan CMNZMF and SERCONC program libraries.                  *
//* Remove the comment asterisks from the two PROC statements        *
//* and also remove the comment asterisks from the two corresponding *
//* DD statements in the STEPLIB concatenatin.                       *
//* Remove the asterisks from the SERPRINT and SER#PARM DD           *
//* statements in the special ChangeMan section at the end of this   *
//* procedure.  You will need to change the data set name in the     *
//* SER#PARM statement to the name of your ChangeMan TCPIPORT data   *
//* set.                                                             *
//* The XMLIN and XMLOUT DD statements will not be needed if you     *
//* are using the default ChangeMan interface routine, SERXMLAC.     *
//*                                                                  *
//*                                                                  *
//*                          Change Log                              *
//*                                                                  *
//* ChangeID  Description                                            *
//* --------  -------------------------------------------------------*
//* V6.00     MAINFRAME ACCESS XML CONFIGURATION SUPPORT             *
//*------------------------------------------------------------------*
//*
//MFAAS   EXEC PGM=MFMFM,REGION=64M,PARM='/ASJOB'
//STEPLIB  DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//         DD  DISP=SHR,DSN=&TAUQUAL..AUTHLIB
//         DD  DSNAME=CEE.SCEERUN,DISP=SHR
//         DD  DSNAME=CEE.SCEERUN2,DISP=SHR
//*-----------------------------------------------------
//* Optional site-dependent ChangeMan program libraries
//*-----------------------------------------------------
//*        DD  DISP=SHR,DSN=&CCMNZMF
//*        DD  DISP=SHR,DSN=&CSERCOMC
//*---------------------------------------------------
//* Optional site-dependent Endevor program libraries
//*---------------------------------------------------
//*        DD  DISP=SHR,DSN=&EAUTULIB
//*        DD  DISP=SHR,DSN=&EAUTHLIB
//*CONLIB  DD  DISP=SHR,DSN=&ECONLIB
//DLL      DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//TABLES   DD  DISP=SHR,DSN=&DSNQUAL..TABLES
//XDBIN    DD  DISP=SHR,DSN=&DSNQUAL..CNTL(PARMSAS)
//CEEOPTS  DD  DISP=SHR,DSN=&DSNQUAL..CNTL(CEEOPTS)
//SYSPRINT DD  SYSOUT=A
//SYSTERM  DD  SYSOUT=A
//SYSUDUMP DD  SYSOUT=A
//XDBOUT   DD  SYSOUT=A
//*
//*--------------------------------
//* Site-dependent TCP/IP data set
//*--------------------------------
//*
//SYSTCPD  DD  DISP=SHR,DSN=&TCPDATA
//*
//*----------------------------------------------
//* Optional site-dependent eBiz program library
//*----------------------------------------------
//*
//*EBIZLIB  DD  DISP=SHR,DSN=&EBIZLIB
//*
//*----------------------------------------------
//* Optional site-dependent ChangeMan data sets
//*----------------------------------------------
//*
//*SERPRINT DD  SYSOUT=A
//*SER#PARM DD  DISP=SHR,DSN=your.TCPIPORT
//*XMLIN    DD  DISP=SHR,DSN=xml.input.dataset
//*XMLOUT   DD  DISP=SHR,DSN=xml.output.dataset
//*
Parent topic: General migration actions


Migration to use the XML configuration file

If you want to use the XML configuration file you need to make some changes to your existing JCL procedures. You also need to create and configure a new XML configuration file (MFAXML). It is important you have already followed the migration actions specified in the General migration actions topic.

The changes can be summarized as:

  • Create new XML configuration file for use by MFA Server by doing one of the following:
    • Use the command line utility to convert your existing configuration into the new XML configuration file.
    • Use the new Mainframe Access Configuration Utility to customize the new hlq.MFA.CNTL(MFAXML) configuration member.
  • For the MFA Started Task JCL Procedure:
    • Add hlq.ZSERVER.AUTHLIB to the STEPLIB
    • Comment out XBDIN and SERVERS DD statements
    • Add (or change) CONFXML and CONFOSR DD statements
  • For MFAAS Started Task JCL Procedure:
    • Add PARM='/ASJOB' to EXEC
    • Add hlq.ZSERVER.AUTHLIB to the STEPLIB
    • Comment out XBDIN DD statement
    • Add CONFXML and CONFOSR DD statements
  • Migrating old configurations to new XML configuration
  • Migration actions for MFA Started Task JCL procedure
  • Migration actions for MFAAS Started Task JCL Procedure
Parent topic: Migration information


Migrating old configurations to new XML configuration

In order to ease migration from the existing MFA configuration files, including the existing z/Server XML configuration file, Micro Focus have provided a command line migration utility that performs the conversion for you.

The tool is called MFA Config Migration Utility (mfacmu), and can be executed from a Micro Focus Enterprise Developer command prompt by invoking mfacmu.exe. By executing the command with no parameters you should see the help as below:

Copyright(c) 2018 Micro Focus. All rights reserved.
MFA Config Migration Utility Version 1.0.0.1
Syntax Help:

mfacmu -Output <OutputPath> -Main <MFAMainTaskConfig> -Server <MFAServersConfig
> [-ZServ <zServerConfig> -ENDV <EndevorConfig> -AMSQ  <AMSConfig> -CHGX <Chang
eManConfig> -CGMQ <CGMQOTMAConfig>,<CGMQOTMAConfig>,... -Default <DefaultConfig
>] -Schema <ConfigSchema>

Where:

    <outputPath>        - The filename/location of the new config.

    <MFAMainTaskConfig> - The path to the MFA main task config.
    <MFAServersConfig>  - The path to the MFA servers config.

And optionally:

    <zServerConfig>     - The path to the zServer xml config.
    <EndevorConfig>     - The path to the Endevor config.
    <AMSConfig>         - The path to the AMS config.
    <ChangeManConfig>   - The path to the ChangeMan config.
    <CGMQOTMAConfig>    - A path to a CGMQOTMA config or comma delimited list o
                          f paths.
    <DefaultConfig>     - The path to a config to be used by all application se
                          rvers unless a specific one has been specified.
    <ConfigSchema>      - Path to the Config schema to validate against. when n
                          not set this defaults to finding the file in the prod
                          uct.

Examples:
mfacmu -Output newconf.txt -Main C:\Config\PARMS.TXT -Server C:\Config\SERVERS.
TXT

mfacmu -Output C:\Config\newconf.txt -Main C:\Config\PARMS.TXT -Server C:\Confi
g\SERVERS.TXT -ZServ "C:\zserver config\IVPXML.XML" -AMSQ C:\Config\PARMSAMS.TX
T

The job of mfacmu is to take your existing MFA configurations files from MFA Started Task, any other MFAAS Started Tasks and even the existing z/Server XML configuration file if used and convert that to a new valid XML configuration file that can be used straight away.

Before you use the utility you need to gather the following information:

  1. The PARMS file used by MFA Started Task. This is typically located in hlq.MFA.CNTL(PARMS), but can be found by looking at the XDBIN DD statement in your JCL procedure.
  2. The SERVERS file used by MFA Started Task. This is typically located in hlq.MFA.CNTL(SERVERS), but can be found by looking at the SERVERS DD statement in your JCL procedure.
  3. For each MFAAS Started Task (for Endevor, ChangeMan and AMS and so on) you will need the PARMSAS file. This is typically located in hlq.MFA.CNTL(PARMSAS), but can be found by looking at the XDBIN DD statement in your JCL procedure. You need to keep a note of the purpose of the MFAAS Started Task (ChangeMan or Endevor and so on) so that the correct file can correctly specified to the mfacmu tool.
  4. If you are using the z/Server feature you will need the existing IVPXML configuration file. This is typically located in hlq.ZSERVER.CONFIG(IVPXML), but can be found by looking at the CONFXML DD statement in your JCL procedure.

These files need to be download to your client ready for use by the mfacmu tool. For a typical installation you may have the following:

  1. MFA Started Task - MFA Server
  2. MFAS Started Task - Data Connect Server
  3. MFAAS Started Task - Endevor Application Server
  4. MFAAS Started Task - AMS Application Server
  5. z/Server - z/Server feature

In which case you have downloaded four files. PARMS and SERVERS from MFA Server, nothing from Data Connect, the PARMSAS file from Endevor and the PARMSAS file from AMS. It is entirely possible to use the same PARMSAS file for each MFAAS Started Task, in which case you will only need to download it once. You will also need to download the z/Server XML configuration file.

Download the files into the following structure:

MFA Server

  • C:\FILES\MFAServer\PARMS.txt
  • C:\FILES\MFAServer\SERVERS.txt

Endevor

  • C:\FILES\Endevor\PARMSAS.txt

AMS

  • C:\FILES\AMS\PARMSAS.txt

z/Server

  • C:\FILES\ZServer\IVPXML.xml

Save the resultant XML configuration file as:

  • C:\FILES\XMLConfiguration\MFAXML.xml

Invoke the mfacmu utility as follows:

mfacmu -Output C:\FILES\XMLConfiguration\MFAXML.xml -Main C:\FILES\MFAServer\PARMS.txt -Server C:\FILES\MFAServer\SERVERS.txt -ENDV C:\FILES\Endevor\PARMSAS.TXT –AMSQ C:\FILES\AMS\PARMSAS.txt –Zserv C:\FILES\ZServer\IVPXML.xml

The following or similar output is displayed:

Copyright(c) 2018 Micro Focus. All rights reserved.
MFA Config Migration Utility Version 1.0.0.1
ASTYPE parameter is now implicitly determined.
MTP004W: The following parameter has an empty value: DSNQUALIFIER_ENDEVOR=
    --- ENDEVOR DSN QUALIFIER
MTP003W: The following parameter statement is ignored, has no value: MFA_ACCEPT_
EMPTY_FILES         --- DOWNLOAD EMPTY DATA SETS (YES,NO)
MTP003W: The following parameter statement is ignored, has no value: MFA_GUI_BLA
NKPASSWORD          --- CLEAR PASSWORD FIELD (YES,NO)
MTP003W: The following parameter statement is ignored, has no value: MFA_GUI_IGN
OREUSERCTO          --- DISABLE INACTIVITY TIMEOUT (YES,NO)
MTP003W: The following parameter statement is ignored, has no value: MFA_JOBNAME
_CHECK              --- BATCH JOB STARTS WITH SUBMITTER'S ID (YES,NO)
MTP004W: The following parameter has an empty value: CHANGEMAN_SSID=
    --- CHANGEMAN SUBSYSTEM ID X ("SERX")
MTP004W: The following parameter has an empty value: CHANGEMAN_DSNQUALIFIER=
    --- CHANGEMAN DSN QUALIFIER
MTP003W: The following parameter statement is ignored, has no value:
TCP LINK FEATURE parameter is now implicitly determined.
MFA FEATURE parameter is now implicitly determined.
MCO FEATURE parameter is now implicitly determined.
REMOTE IMS FEATURE parameter is now implicitly determined.
ES/MTO OUTBOUND FEATURE parameter is now implicitly determined.
ASSERVER parameter is now implicitly determined.
ASGROUPID parameter is now implicitly determined.
ASSERVER parameter is now implicitly determined.
ASGROUPID parameter is now implicitly determined.
ASSERVER parameter is now implicitly determined.
ASGROUPID parameter is now implicitly determined.
ASSERVER parameter is now implicitly determined.
ASGROUPID parameter is now implicitly determined.
ASTYPE parameter is now implicitly determined.
ORGANIZATION parameter is now implicitly determined.
MAP002W: Attribute not in white list: MAX_PUBLIC_FILES
MAP002W: Attribute not in white list: CHANGEMAN_SSID
MAP002W: Attribute not in white list: CHANGEMAN_INTERFACE
ASTYPE parameter is now implicitly determined.
ORGANIZATION parameter is now implicitly determined.
MAP002W: Attribute not in white list: MAX_PUBLIC_FILES
MAP002W: Attribute not in white list: CHANGEMAN_SSID
MAP002W: Attribute not in white list: CHANGEMAN_INTERFACE
ASTYPE parameter is now implicitly determined.
ORGANIZATION parameter is now implicitly determined.
MAP002W: Attribute not in white list: MAX_PUBLIC_FILES
MAP002W: Attribute not in white list: CHANGEMAN_SSID
MAP002W: Attribute not in white list: CHANGEMAN_INTERFACE

Warnings have an error code ending in W and are yellow, these can be safely ignored. Errors have an error code ending in E and are red and need to be resolved. Contact Micro Focus support for assistance. An example of an error might be:

Copyright(c) 2018 Micro Focus. All rights reserved.
MFA Config Migration Utility Version 1.0.0.1
MCW001E: Unable to find schema. Config will be written but not validated.

The mfacmu tool returns 0 on success and 1 on failure. If the tool returns 1 then you need to contact Micro Focus support for assistance. On success the generated XML file can be used in your MFA Started Task JCL procedure by uploading it. You need to change the CONFXML DD statement to point to it.

You can now use the Mainframe Access Configuration Utility to view and modify this XML configuration file in a Web User Interface. See Mainframe Access Configuration Utility for more information.

Parent topic: Migration to use the XML configuration file


Migration actions for MFA Started Task JCL procedure

To enable the new XML configuration file you need to make the following changes:

  • Add TAUQUAL to point to HLQ.ZSERVER
  • Add &TAUQUAL..AUTHLIB to the STEPLIB
  • Comment out XDBIN and SERVERS DD statements
  • Add (or change) CONFXML DD to point to &DSNQUAL..CNTL(MFAXML)
  • Add (or change) CONFOSR DD to point to &TAUQUAL..OSR(MFAOSR)

The change is highlighted in bold:

//MFA     PROC DSNQUAL='HLQ.MFA',
//             TAUQUAL='HLQ.ZSERVER',
//*            EAUTULIB='CAI.NDVRR15.CSIQAUTU',
//*            EAUTHLIB='CAI.NDVRR15.CSIQAUTH',
//*            ECONLIB='CAI.NDVRR15.CSIQLOAD',
//*            LIBRIAN='CAI.CAILIB',
//             TCPDATA='TCPIP.OS390.TCPDATA'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - MFA Started Task                  *
//*                                                                  *
//*------------------------------------------------------------------*
//* Q u i c k   C o n f i g u r a t i o n                            *
//*------------------------------------------------------------------*
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*                                                                  *
//* Change the TCPDATA value on the PROC statement to specify the    *
//* data set name used at your installation.  For CA TCPAccess you   *
//* may remove this symbolic parameter and the associated            *
//* DD statement.                                                    *
//*                                                                  *
//*------------------------------------------------------------------*
//* A d v a n c e d   C o n f i g u r a t i o n                      *
//*------------------------------------------------------------------*
//*                                                                  *
//* Endevor Considerations                                           *
//* ----------------------                                           *
//* If you will be using the Mainframe Access Server Endevor         *
//* support, change the EAUTHLIB and ECONLIB values                  *
//* on the PROC statement to specify the data set names of your      *
//* Endevor AUTHLIB and CONLIB program libraries.                    *
//* Remove the comment asterisks from the two PROC statements        *
//* and from the two DD statements in the STEPLIB concatenation.     *
//*                                                                  *
//* Librarian Considerations                                         *
//* ------------------------                                         *
//* If you will be using the Mainframe Access Server Librarian       *
//* support, change the LIBRIAN value on the PROC statement          *
//* to specify the data set name of your Librarian program library.  *
//* Remove the comment asterisk from the PROC statement and from     *
//* the DD statement in the STEPLIB concatenation.                   *
//*                                                                  *
//* Mainframe Call Generator Considerations                          *
//* ---------------------------------------                          *
//* If you will be using the Mainframe Call Generator feature,       *
//* remove the comment asterisk from the supplied MCGLIB DD          *
//* statement (the DD name must be MCGLIB) and change the data set   *
//* name to the name of your program library.                        *
//* If you have more than one program library for MCG the MCGLIB     *
//* DD can specify a concatenation of progam libraries.              *
//*                                                                  *
//* DBCS Code Page Considerations                                    *
//* -----------------------------                                    *
//* If you want DBCS code page support you must uncomment the EZA*   *
//* DD statments. The TCPIP.SEZADBCX data set is supplied by IBM     *
//* as a part of TCP/IP.                                             *
//*                                                                  *
//* z/Server Holder Considerations                                   *
//* -----------------------------                                    *
//* If you want to start the z/Server holder under MFA uncomment     *
//* the z/Server DD statements including on the STEPLIB.             *
//*                                                                  *
//*                                                                  *
//*                          Change Log                              *
//*                                                                  *
//*                                                                  *
//* ChangeID  Description                                            *
//* --------  -------------------------------------------------------*
//* V3.10     New DD statement - //ABNLIGNR DD DUMMY                 *
//* V4.00     Endevor changes                                        *
//* V5.00     zServer support                                        *
//* V6.00     Mainframe Access XML configuration support             *
//*------------------------------------------------------------------*
//*
//MFA     EXEC PGM=MFMFM,REGION=64M
//STEPLIB  DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//         DD  DISP=SHR,DSN=&TAUQUAL..AUTHLIB
//*---------------------------------------------------
//* Optional site-dependent Librarian program library
//*---------------------------------------------------
//*        DD  DISP=SHR,DSN=&LIBRIAN
//*---------------------------------------------------
//* Optional site-dependent Endevor program libraries
//*---------------------------------------------------
//*        DD  DISP=SHR,DSN=&EAUTULIB
//*        DD  DISP=SHR,DSN=&EAUTHLIB
//*CONLIB  DD  DISP=SHR,DSN=&ECONLIB
//DLL      DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//TABLES   DD  DISP=SHR,DSN=&DSNQUAL..TABLES
//*XDBIN    DD  DISP=SHR,DSN=&DSNQUAL..CNTL(PARMS)
//*SERVERS  DD  DISP=SHR,DSN=&DSNQUAL..CNTL(SERVERS)
//XDBACC   DD  DISP=SHR,DSN=&DSNQUAL..CNTL(ACCESS)
//CEEOPTS  DD  DISP=SHR,DSN=&DSNQUAL..CNTL(CEEOPTS)
//SYSPRINT DD  SYSOUT=A
//SYSTERM  DD  SYSOUT=A
//SYSUDUMP DD  SYSOUT=A
//XDBOUT   DD  SYSOUT=A
//DSNTRACE DD  SYSOUT=A
//DUMMY    DD  DUMMY
//ABNLIGNR DD  DUMMY                  revoke ABENDAID
//*
//*--------------------------------
//* zServer Holder
//*--------------------------------
//*
//*SYSEXEC  DD DISP=SHR,DSN=&TAUQUAL..EXEC
//CONFXML  DD DISP=SHR,DSN=&DSNQUAL..CNTL(MFAXML)
//CONFOSR  DD DISP=SHR,DSN=&TAUQUAL..OSR(MFAOSR)
//*DSPPRT   DD SYSOUT=*,LRECL=255
//*SYSOUT   DD SYSOUT=*
//*SYSTSIN  DD DUMMY
//*SYSTSPRT DD SYSOUT=*
//*
//*--------------------------------
//* Site-dependent TCP/IP data set
//*--------------------------------
//*
//SYSTCPD  DD  DISP=SHR,DSN=&TCPDATA
//*
//*-----------------------------
//* Optional audit log data set
//*-----------------------------
//*
//XDBAUDIT DD  DUMMY,DISP=SHR,DSN=&DSNQUAL..AUDIT
//*
//*---------------------------------------------------
//* Optional Mainframe Call Generator program library
//*---------------------------------------------------
//*
//*MCGLIB  DD  DISP=SHR,DSN=YOUR.MCG.PROGRAM.LIBRARY
//*
//*---------------------------------------------------
//* Optional DBCS code pages
//*---------------------------------------------------
//*
//*EZACHLAT DD  DSN=TCPIP.SEZADBCX(EZACHLAT),DISP=SHR
//*EZAHGLAT DD  DSN=TCPIP.SEZADBCX(EZAHGLAT),DISP=SHR
//*EZAKJLAT DD  DSN=TCPIP.SEZADBCX(EZAKJLAT),DISP=SHR
//*EZASCLAT DD  DSN=TCPIP.SEZADBCX(EZASCLAT),DISP=SHR
Parent topic: Migration to use the XML configuration file


Migration actions for MFAAS Started Task JCL Procedure

To enable the new XML configuration file you need to make the following changes:

  • Add (or change) PARM statement
  • Add TAUQUAL to point to HLQ.ZSERVER
  • Add &TAUQUAL..AUTHLIB to the STEPLIB
  • Comment out XDBIN DD statements
  • Add (or change) CONFXML DD to point to &DSNQUAL..CNTL(MFAXML)
  • Add (or change) CONFOSR DD to point to &TAUQUAL..OSR(MFAOSR)

The changes are highlighted in bold:

//MFAAS   PROC DSNQUAL='HLQ.MFA',
//             TAUQUAL='HLQ.ZSERVER',
//*            EAUTULIB='CAI.NDVRR15.CSIQAUTH',
//*            EAUTHLIB='CAI.NDVRR15.CSIQAUTH',
//*            ECONLIB='CAI.NDVRR15.CSIQLOAD',
//*            CCMNZMF='YOUR.CMNZMF.LOAD',
//*            CSERCOMC='YOUR.SERCOMC.LOAD',
//*            EBIZLIB='YOUR.EBIZ.LOADLIB',
//             TCPDATA='TCPIP.OS390.TCPDATA'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - Application Server started task   *
//*                                                                  *
//*------------------------------------------------------------------*
//* Q u i c k   C o n f i g u r a t i o n                            *
//*------------------------------------------------------------------*
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*                                                                  *
//* Change the TCPDATA value on the PROC statement to specify the    *
//* data set name used at your installation.  For CA TCPAccess you   *
//* may remove this symbolic parameter and the associated            *
//* DD statement.                                                    *
//*                                                                  *
//*------------------------------------------------------------------*
//* A d v a n c e d   C o n f i g u r a t i o n                      *
//*------------------------------------------------------------------*
//*                                                                  *
//* Endevor Considerations                                           *
//* ----------------------                                           *
//* If you will be using this Application Server JCL to process      *
//* Endevor requests, change the EAUTHLIB and ECONLIB values         *
//* on the PROC statement to specify the data set names of your      *
//* Endevor AUTHLIB and CONLIB program libraries.                    *
//* Remove the comment asterisks from the two PROC statements        *
//* and the two DD statements in the STEPLIB concatenation.          *
//* If you are planning to use Procedure Groups to compile and       *
//* relink automatically, then increase DYNAMNBR=300 and eliminate   *
//* the pre-allocation of SYSPRINT and SYSTERM which conflict with   *
//* standard compile output names.                                   *
//*                                                                  *
//* Component Generator IMS Support                                  *
//* -------------------------------                                  *
//* If you will be using this Application Server JCL to run          *
//* your Component Generator eBiz programs,                          *
//* change the EBIZLIB value on the PROC statement to specify the    *
//* data set name of the load module library containing your eBiz    *
//* programs.  Remove the comment asterisks from the PROC statement  *
//* and the EBIZLIB DD statement.                                    *
//* If you have more than one eBiz program library you can change    *
//* EBIZLIB to be a concatenation of program library data sets.      *
//*                                                                  *
//* ChangeMan Considerations                                         *
//* -------------------------                                        *
//* If you will be using this Application Server JCL to process      *
//* ChangeMan requests, change the CCMNZMF and CSERCOMC values       *
//* on the PROC statement to specify the data set names of your      *
//* ChangeMan CMNZMF and SERCONC program libraries.                  *
//* Remove the comment asterisks from the two PROC statements        *
//* and also remove the comment asterisks from the two corresponding *
//* DD statements in the STEPLIB concatenatin.                       *
//* Remove the asterisks from the SERPRINT and SER#PARM DD           *
//* statements in the special ChangeMan section at the end of this   *
//* procedure.  You will need to change the data set name in the     *
//* SER#PARM statement to the name of your ChangeMan TCPIPORT data   *
//* set.                                                             *
//* The XMLIN and XMLOUT DD statements will not be needed if you     *
//* are using the default ChangeMan interface routine, SERXMLAC.     *
//*                                                                  *
//*                                                                  *
//*                          Change Log                              *
//*                                                                  *
//* ChangeID  Description                                            *
//* --------  -------------------------------------------------------*
//* V6.00     MAINFRAME ACCESS XML CONFIGURATION SUPPORT             *
//*------------------------------------------------------------------*
//*
//MFAAS   EXEC PGM=MFMFM,REGION=64M,PARM='/ASJOB'
//STEPLIB  DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//         DD  DISP=SHR,DSN=&TAUQUAL..AUTHLIB
//         DD  DSNAME=CEE.SCEERUN,DISP=SHR
//         DD  DSNAME=CEE.SCEERUN2,DISP=SHR
//*-----------------------------------------------------
//* Optional site-dependent ChangeMan program libraries
//*-----------------------------------------------------
//*        DD  DISP=SHR,DSN=&CCMNZMF
//*        DD  DISP=SHR,DSN=&CSERCOMC
//*---------------------------------------------------
//* Optional site-dependent Endevor program libraries
//*---------------------------------------------------
//*        DD  DISP=SHR,DSN=&EAUTULIB
//*        DD  DISP=SHR,DSN=&EAUTHLIB
//*CONLIB  DD  DISP=SHR,DSN=&ECONLIB
//DLL      DD  DISP=SHR,DSN=&DSNQUAL..LOADLIB
//TABLES   DD  DISP=SHR,DSN=&DSNQUAL..TABLES
//*XDBIN    DD  DISP=SHR,DSN=&DSNQUAL..CNTL(PARMSAS)
//CEEOPTS  DD  DISP=SHR,DSN=&DSNQUAL..CNTL(CEEOPTS)
//SYSPRINT DD  SYSOUT=A
//SYSTERM  DD  SYSOUT=A
//SYSUDUMP DD  SYSOUT=A
//XDBOUT   DD  SYSOUT=A
//*
//*--------------------------------
//* Site-dependent TCP/IP data set
//*--------------------------------
//*
//SYSTCPD  DD  DISP=SHR,DSN=&TCPDATA
//*
//*----------------------------------------------
//* Optional site-dependent eBiz program library
//*----------------------------------------------
//*
//*EBIZLIB  DD  DISP=SHR,DSN=&EBIZLIB
//*
//*----------------------------------------------
//* Optional site-dependent ChangeMan data sets
//*----------------------------------------------
//*
//*SERPRINT DD  SYSOUT=A
//*SER#PARM DD  DISP=SHR,DSN=your.TCPIPORT
//*XMLIN    DD  DISP=SHR,DSN=xml.input.dataset
//*XMLOUT   DD  DISP=SHR,DSN=xml.output.dataset
//*
//CONFXML  DD DISP=SHR,DSN=&DSNQUAL..CNTL(MFAXML)
//CONFOSR  DD DISP=SHR,DSN=&TAUQUAL..OSR(MFAOSR)
Parent topic: Migration to use the XML configuration file


Additional migration for z/Server feature support

In order to take advantage of the single Mainframe Access XML configuration file you must have taken all the actions specified in Migration to use the XML configuration file topic, and be using the unified scheduler and using MFA Server to start the holder task internally. This is equivalent to having set ZSERVER FEATURE=HOLDER in the MFA Server configuration file in Enterprise Developer 3.0 and earlier. These migration actions can be found in the Micro Focus Enterprise Developer 3.0 product Help.

Parent topic: Migration information


Installation requirements

  • Machine requirements
  • Software requirements
  • Recommended versions of z/Server for Enterprise Developer
Parent topic: Mainframe Access Installation Guide


Machine requirements

IBM mainframe model zEC12 or later is required for installing and using MFA Server. If your hardware does not meet these requirements please contact Micro Focus support.

Parent topic: Installation requirements


Software requirements

An IBM supported operating system z/OS (V2.1 or later) is required. If your operating system version does not meet these requirements please contact Micro Focus support.

Mainframe Access requirements:

  • IBM Communications Server
  • Two APPLIDs, and one TCP/IP port
  • Availability of APF security authorization support personnel
  • Access to a network share with acceptable space for source and data, as well as the ability to access the IP address and ports used to access MFA

Mainframe Access z/Server feature requirements:

  • ISPF
  • Binder
  • High Level Assembler
  • Language Environment
  • RACF or an equivalent product
  • z/OS Communications Server - IP Services
  • IBM REXX Library

To run user applications requested via TCP/IP client calls, there may be additional optional software requirements depending on the application. Typical optional requirements are:

  • IBM Enterprise COBOL for z/OS
  • IBM Enterprise PL/I
  • IBM DB2 for z/OS

Support for Error Feedback (displaying compiler error messages in an Enterprise Developer error view) requires the following additional compiler options:

  • For COBOL: EXIT(ADEXIT('/N 100 /W 50',TAURTOCX)), ADATA
  • For PL/I: XINFO(XML)
  • For Assembler: EXIT(ADEXIT(TAURTOAX('/N 100 /W 25'))),ADATA

To compile CICS applications, a compiler supporting the CICS Transaction Server 2.1 or later is required:

  • COBOL applications compiled using any of:
    • IBM® COBOL for OS/390® &VM, Version 2 Release 2, program number 5648-A25, with APAR PQ49375 applied.
    • IBM Enterprise COBOL for z/OS and OS/390, Version 3 Release 1, program number 5655-G53, and later COBOL releases.
  • PL/I applications compiled using any of:
    • IBM VisualAge PL/I for OS/390 Version 2 Release 2.1, program number 5655-B22, with APAR PQ45562 applied.
    • IBM Enterprise PL/I for z/OS and OS/390, Version 3 Release 1, program number 5655-H31, and later PL/I releases.
Parent topic: Installation requirements


Recommended versions of z/Server for Enterprise Developer

The following table shows the versions of z/Server delivered with the different Enterprise Developer releases. These are also the recommended version of z/Server to use with a particular Enterprise Developer release.

Enterprise Developer Version | z/Server Version | Date Released
2.1 | z/Server V2R0M06 and V2R0M07 (including performance testing) | October 2012
2.1.1 | z/Server V2R0M07 | April 2013
2.2 | z/Server V2R2M00 | October 2013
2.2 Update 1 | z/Server V2R2M02 | May 2014
2.3 | z/Server V2R3 | September 2015
2.3 Update 1 | z/Server V2R3M01 | March 2016
3.0 | z/Server V3R0 | June 2017
4.0 | z/Server V4R0 | June 2018

Important: An Enterprise Developer client can communicate with a version of z/Server from the same delivery or newer, but not vice versa. For example, an Enterprise Developer 2.3 client can communicate with z/Server delivered with Enterprise Developer 2.3, 2.3 Update 1, 3.0, or 4.0.
Parent topic: Installation requirements


Mainframe Access Configuration Utility

The Mainframe Access configuration utility is a web-based utility that simplifies the process of configuring the XML file that controls how MFA Server operates. The utility guides you through the steps required to create a new XML file, specifying MFA Start Task, Application Servers and Services elements. It validates the specified parameters and values ensuring that the XML file is well-formed. You can modify a basic configuration file adding advanced or custom parameters before uploading it to the mainframe ready for use with MFA Server. You can also download and modify existing XML files directly from the mainframe.

Features

The Mainframe Access configuration utility has the following features:

  • Web-based user interface.
  • Validation of XML configuration files.
  • Parameter and value validation at the point of entry.
  • Grouped parameters for holder, scheduler and user server configuration.
  • Ability to upload or download configuration files directly to the mainframe.

Limitations

The Mainframe Access configuration utility has the following limitations:

  • Supports configuration of XML files created with Enterprise Developer 4.0 or greater.
  • Internet Explorer does not support saving the XML configuration file directly to the browser's download folder. The XML file is displayed in a browser popup. You can copy from the popup and paste to a new location.
  • The web-based utility is restricted to password lengths that are 8 characters or fewer.
  • Prerequisites
  • Starting the Mainframe Access Configuration Utility
  • Operation
  • Configuration parameters reference
Parent topic: Mainframe Access Installation Guide


Prerequisites

The Mainframe Access configuration utility 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)
Parent topic: Mainframe Access Configuration Utility


Starting the Mainframe Access Configuration Utility

To start the Mainframe Access configuration utility, perform the following steps:

  1. Click Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt
  2. At the command prompt, type mfaconfig.bat.
  3. Press Enter.

    This opens the Mainframe Access configuration utility in you default Web browser, with the URL http://localhost:2345.

Parent topic: Mainframe Access Configuration Utility


Operation

The Mainframe Access configuration utility has two modes of operation:

  • Creating a new XML configuration file. The interface takes you through the steps for specifying the MFA Server parameters as well as Application Server and Services parameters. Once you have specified the basic configuration file you can choose to:
    • Upload the file to a mainframe location or you can save it locally in your browser's download directory.
    • Edit your initial MFA Server XML configuration, found in hlq.MFA.CNTL(MFAXML), and customize it for your needs.
  • Downloading an XML configuration file from a mainframe location. Once you have downloaded the configuration file you can choose to:
    • Upload the file to an alternative mainframe location or you can save it locally in your browser's download directory.
    • Review the downloaded configuration file. This is performed in stages:
      1. Review the existing MFA Server parameters.
      2. Review the existing RIMS, MCO, MFA and ES-MTO Services parameters.
      3. Review the existing DataConnect, Endevor, ChangeMan, AMS and z/Server Application Server parameters.
      4. Once you have reviewed the configuration you can upload the file to a mainframe location or you can save it locally in your browser's download directory.
  • Creating a new XML configuration file
  • Downloading an existing XML configuration file
  • Edit Configuration page
Parent topic: Mainframe Access Configuration Utility


Creating a new XML configuration file

To create a new XML configuration file, perform the following steps:

  1. Click Create.
  2. Review and modify the default MFA Server parameters, and then click NEXT.

    See MFA Server Parameters for more information.

  3. Review and modify that Data Connect Application Server parameters, and then click NEXT.

    See Data Connect Application Server Parameters for more information.

    • Optionally, you can add more Application Server definitions by clicking ADD MORE, and then choosing your Application Server from the list. See Endevor Application Server Parameters, ChangeMan Application Server Parameters, and AMS Application Server Parameters for more information.
  4. Review and modify the MFA Data Connect Service parameters, and then click NEXT.

    See MFA Data Connect Service Parameters for more information.

    • Optionally, review and modify the z/Server feature parameters, and then click NEXT.

      See z/Server Feature Parameters for more information.

    • Optionally, review and modify the z/Server Scheduler Application Server parameters, and then click NEXT.

      See z/Server Scheduler Application Server Parameters for more information.

  • To upload your XML configuration file to a mainframe
Parent topic: Operation


To upload your XML configuration file to a mainframe

To upload your XML configuration file to the mainframe, perform the following steps:

  1. In the NODE field, type your host name or IP address.
  2. In the PORT field, type your MFA port number. Alternatively, you can use the up and down arrows to increment or decrement the port number.
  3. In the USER field, type your username.
  4. In the PASSWORD field, type your password.
  5. In the DATASET field, type the fully qualified PDS library name of your XML configuration file.
  6. In the MEMBER field, type the member name you want your XML configuration file to have.
  7. To upload the XML file to the mainframe, click UPLOAD.
  8. If successful, an UPLOAD COMPLETE dialog box is displayed, you can then choose to SHUTDOWN, RESTART or go BACK.
Parent topic: Creating a new XML configuration file


Downloading an existing XML configuration file

To download an existing XML configuration file, perform the following steps:

  1. Click DOWNLOAD.
  2. In the NODE field, type your host name or IP address.
  3. In the PORT field, type your MFA port number. Alternatively, you can use the up and down arrows to increment or decrement the port number, respectively.
  4. In the USER field, type in your username.
  5. In the PASSWORD field, type your password.
  6. In the DATASET field, type the fully qualified PDS library name of your XML configuration file.
  7. In the MEMBER field, type the member name containing the XML configuration file you wish to download.
  8. Click NEXT.

    The XML configuration file can now be reviewed. See Reviewing an XML configuration file for more information.

Parent topic: Operation


Edit Configuration page

At this point you can choose where to save your XML configuration file, start a new configuration or shutdown the utility:

  • To upload your XML configuration file to the mainframe:
    • Click UPLOAD.

      See To upload your XML configuration to a mainframe for more information.

  • To save your XML configuration file to your browser's download directory:
    • Click SAVE.
  • To delete the configuration that you have created and start again:
    • Click RESTART.
  • To shutdown the configuration utility:
    • Click SHUTDOWN.

See Starting the z/Server Configuration Utility for more information on how to start the z/Server configuration utility again.

Parent topic: Operation


Configuration parameters reference

See Configuration reference for more information on the parameters in your XML configuration file.

  • MFA Server parameters
  • Data Connect Application Server parameters
  • Endevor Application Server parameters
  • ChangeMan Application Server Parameters
  • AMS Application Server Parameters
  • MFA Data Connect Service parameters
  • RIMS Service Parameters
  • MCO Service Parameters
  • ES-MTO Service Parameters
  • z/Server feature Parameters
  • z/Server Scheduler Application Server Parameters
Parent topic: Mainframe Access Configuration Utility


MFA Server parameters

Standard parameters:

TCP_PORT
The port number to accept connections from Micro Focus clients.
NETWORK_ID
The SSCP network ID used by ACF/VTAM on this z/OS system.
ORGANIZATION
Your company name or other meaningful identifier up to 40 characters in length.
Parent topic: Configuration parameters reference


Data Connect Application Server parameters

PROCEDURE
The name of the started task JCL procedure that can be used to start address spaces for this group. Sample JCL procedure MFAAS provides the basic JCL for an application server address space, and MFAAMS for the AMS application server address space. Specify a JCL procedure name of up to eight characters.
Parent topic: Configuration parameters reference


Endevor Application Server parameters

PROCEDURE
The name of the started task JCL procedure that can be used to start address spaces for this group. Sample JCL procedure MFAAS provides the basic JCL for an application server address space, and MFAAMS for the AMS application server address space. Specify a JCL procedure name of up to eight characters.
JOBNAME
The jobname prefix to be used for address spaces that are started for this group. For multiple-instance address spaces this is a prefix of 1 to 4 characters and Mainframe Access Server will pad this prefix to a full 8-character jobname by appending a 4 to 7 digit sequence number. For example, JOBNAME="MFAE" will result in jobnames MFAE0001, MFAE0002, etc. The sample prefix MFAE can be changed to meet the needs of your installation. If you do change the suggested prefix you will need to review the security subsystem definition for the Mainframe Access started tasks. The configuration process uses a generic STARTED task definition (the generic name specified during Quick Configuration is MFA*.*) that covers generated jobnames such as MFAExxxx, in addition to the MFA (the MFA Server control region) and MFAS (the MFA Server for Data Connect) started task names. Specify a jobname prefix of up to four characters.
MAXIMUM
Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification. Mainframe Access server issues messages (to the XDBOUT data set) when a client request must be queued to wait for an available processing address space. Increase the MAXIMUM value (by 1) when you observe frequent queueing of client requests.
MINIMUM
Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification.
Parent topic: Configuration parameters reference


ChangeMan Application Server Parameters

PROCEDURE
The name of the started task JCL procedure that can be used to start address spaces for this group. Sample JCL procedure MFAAS provides the basic JCL for an application server address space, and MFAAMS for the AMS application server address space. Specify a JCL procedure name of up to eight characters.
JOBNAME
The jobname prefix to be used for address spaces that are started for this group. For multiple-instance address spaces this is a prefix of 1 to 4 characters and Mainframe Access Server will pad this prefix to a full 8-character jobname by appending a 4 to 7 digit sequence number. For example, JOBNAME="MFAE" will result in jobnames MFAE0001, MFAE0002, etc. The sample prefix MFAE can be changed to meet the needs of your installation. If you do change the suggested prefix you will need to review the security subsystem definition for the Mainframe Access started tasks. The configuration process uses a generic STARTED task definition (the generic name specified during Quick Configuration is MFA*.*) that covers generated jobnames such as MFAExxxx, in addition to the MFA (the MFA Server control region) and MFAS (the MFA Server for Data Connect) started task names. Specify a jobname prefix of up to four characters.
MAXIMUM
Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification. Mainframe Access server issues messages (to the XDBOUT data set) when a client request must be queued to wait for an available processing address space. Increase the MAXIMUM value (by 1) when you observe frequent queueing of client requests.
MINIMUM
Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification.
Parent topic: Configuration parameters reference


AMS Application Server Parameters

PROCEDURE
The name of the started task JCL procedure that can be used to start address spaces for this group. Sample JCL procedure MFAAS provides the basic JCL for an application server address space, and MFAAMS for the AMS application server address space. Specify a JCL procedure name of up to eight characters.
JOBNAME
The jobname prefix to be used for address spaces that are started for this group. For multiple-instance address spaces this is a prefix of 1 to 4 characters and Mainframe Access Server will pad this prefix to a full 8-character jobname by appending a 4 to 7 digit sequence number. For example, JOBNAME="MFAE" will result in jobnames MFAE0001, MFAE0002, etc. The sample prefix MFAE can be changed to meet the needs of your installation. If you do change the suggested prefix you will need to review the security subsystem definition for the Mainframe Access started tasks. The configuration process uses a generic STARTED task definition (the generic name specified during Quick Configuration is MFA*.*) that covers generated jobnames such as MFAExxxx, in addition to the MFA (the MFA Server control region) and MFAS (the MFA Server for Data Connect) started task names. Specify a jobname prefix of up to four characters.
MAXIMUM
Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification. Mainframe Access server issues messages (to the XDBOUT data set) when a client request must be queued to wait for an available processing address space. Increase the MAXIMUM value (by 1) when you observe frequent queueing of client requests.
MINIMUM
Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum will be started in response to transaction load, up to the maximum allowed by this specification.
Parent topic: Configuration parameters reference


MFA Data Connect Service parameters

ID
Data Connect client requests do not specify a target server ID and Mainframe Access always looks for the DEFAULT Mainframe Access Data Connect target server definition.
LUNAME
The LU name of the Mainframe Access Data Connect server (also known as the ACBNAME or VTAM APPLID).
MODENAME
The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the Mainframe Access Data Connect server. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
TPNAME
The transaction program name for Mainframe Access Data Connect server requests.
SYNCLEVEL
The SNA LU6.2 sync level option to be used on conversations with the Mainframe Access Data Connect server. Conversations use LU6.2 CONFIRM protocols.
SECURITY
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the Mainframe Access Data Connect server. Mainframe Access forwards security subfield information as provided by the Data Connect client and sets the FMH-5 fields accordingly.
Parent topic: Configuration parameters reference


RIMS Service Parameters

ID
If an IMS Option client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT IMS target server, if one has been defined. This IMS target server ID name is used in the configuration of the client. When a Remote IMS request is sent this name is sent in the request data and is used to locate the target server definition for the IMS system that will receive the request. Specify DEFAULT or an ID of up to four alphanumeric characters.
LUNAME
The LU name of the IMS server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters. This name must match the ACBNAME defined in an APPC/MVS LU definition for the target IMS system.
MODENAME
The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the IMS server. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
TPNAME
The IMS server transaction program name for IMS Option transactions. This is the LU6.2 transaction program name that will be sent to the IMS server in SNA Attach FMH-5 requests to begin an IMS Option transaction. Specify the APPC/MVS transaction program name that was specified in the APPC/MVS definitions during installation of Remote IMS.
SYNCLEVEL
The SNA LU6.2 sync level option to be used on conversations with the IMS server.
SECURITY
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the IMS server. Mainframe Access forwards security subfield information as provided by the IMS Option client and sets the FMH-5 fields accordingly.
Parent topic: Configuration parameters reference


MCO Service Parameters

ID
If a CICS client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT CICS target server, if one has been defined. This CICS target server ID name is used in the configuration of the client. When a CICS request is sent to Mainframe Access this name is sent in the request data and is used to locate the target server definition for the CICS system that will receive the request.
LUNAME
The LU name of the CICS server (also known as the ACBNAME or VTAM APPLID).
MODENAME
The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with mainframe CICS. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
TPNAME
The server transaction program name for CICS requests. This is the LU6.2 transaction program name that will be sent to CICS in SNA Attach FMH-5 requests to begin a CICS transaction. Specify a transaction program name of up to eight characters or specify * to cause Mainframe Access to use the transaction program name provided by the CICS client. The CICS client prepares a partial FMH-5 request that specifies the standard CICS transaction program names for function shipping, distributed program linking and so on.
SYNCLEVEL
The SNA LU6.2 sync level option to be used on conversations with CICS.
SECURITY
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the CICS server. Mainframe Access forwards security subfield information as provided by the CICS client and sets the FMH-5 fields accordingly.
Parent topic: Configuration parameters reference


ES-MTO Service Parameters

ID
The ID can be one to four characters in length and must match the SYSID of the ES/MSS server being defined. The initial connection messages exchanged by MFA Server and ES/MSS use this ID.
ACBNAME
The name of the VTAM ACB associated with this ES/MSS server. MFA Server OPENs and initializes this ACBNAME during startup. The z/OS CICS system(s) must be configured to communicate with this ES/MSS server through this VTAM ACB name using CICS CONNECTION and SESSIONS definition statements.
IPADDRESS
The internet host name or IP address of the ES/MSS server. Specify either the host name that resolves to the correct IP address or the actual IP address in standard dotted-decimal format. The combination of IPADDRESS and PORT from this definition provides MFA Server with the information it needs to originate a socket connection to ES/MSS and to verify the authenticity of a socket connection request from ES/MSS.
PORT
The port number where ES/MSS is listening for ISC connections.
SESSIONS
Specifies the number of concurrent conversations MFA Server can initiate to the ES/MSS server over a single socket connection. If ES/MSS has a different definition for the number of concurrent sessions, the session count is negotiated to a common value at the time a socket connection is established. Specify a value that supports the required number of concurrently active conversations for your application.
SOCKETS
Specifies the maximum number of concurrent socket connections between MFA Server and the ES/MSS server. ES/MSS support is currently limited to a single socket connection between MFA Server and an ES/MSS server; therefore, specify a value of 1.
Parent topic: Configuration parameters reference


z/Server feature Parameters

IPSTACK
Specifies the name of the IP stack used for processing.
SVC_NO
Specifies the SVC number for the type-3 SVC routine to be dynamically installed at holder address space startup.
DSP_TOKEN
Specifies the token name that each address space for one z/Server uses to address the data space with the user administration control structures.
Parent topic: Configuration parameters reference


z/Server Scheduler Application Server Parameters

Scheduler

SCHEDULER_NAME
Specifies the job start of the started task.
LISTENER_PORT
Specifies the IP port that the scheduler listens on for incoming work requests.
FIRST_PORT
Specifies the low end of the port range that the scheduler address space owns and assigns to a user server address space when the user server is started for IP communication.
LAST_PORT
Specifies the high end of the port range that the scheduler address space owns and assigns to a user server address space when the user server is started for IP communication.
CCSID
Specifies the code page used by z/Server (for example, 37 for US, or 1141 for German).
USER_SERVER_JOBNAME
Specifies the name of the user server start procedure used in a z/OS start command.
CEA_ACCOUNT
Specifies the name of the account to be used by all users of this scheduler.
CEA_LOGONPROC
Specifies the name of the TSO/E logon procedure used to start a CEA-launched TSO address space.

User Server

CCSID
Specifies the code page used by z/Server (for example, 37 for US, or 1141 for German).
Parent topic: Configuration parameters reference


Host Installation

  • Preparing the Installation
  • Installation procedure
Parent topic: Mainframe Access Installation Guide


Preparing the Installation

  • Before you begin
  • SVC Routine
Parent topic: Host Installation


Before you begin

The following list details important configuration data that you need to know in order to complete the quick configuration. Review these items and determine the appropriate values before you proceed with customization:

userid
TSO user ID that can update proclib, update vtamlst, update RACF, and issue z/OS system commands through SDSF. Alternatively, the cooperation of individuals with the appropriate authorities.
hlq
High level qualifier that was given to all Mainframe Access data sets when the FRESTORE job was run.
clientport
A TCP/IP port number on the mainframe that you will reserve for Mainframe Access and client connections.
stcuserid
RACF user ID that you want to associate with the Mainframe Access started tasks.
stcgroup
RACF group ID that you want to associate with the Mainframe Access started tasks.
tcpdata
Data set name of the IBM TCP/IP "TCPIP.DATA" data set that provides configuration information to programs that use TCP/IP.
proclib
Data set name of a system procedure library.
vtamlst
Data set name of the active VTAMLST definitions data set.
netid
VTAM SNA network id used on your system. See NETID= in the active ATCSTRxx vtamlst member.
Parent topic: Preparing the Installation


SVC Routine

MFA z/Server feature supports requires a type-3 SVC routine for all authorized commands. You need to call this routine TAURAUTH and reserve a number for it. 238 is the default specified in the configuration files that come with z/Server.

Parent topic: Preparing the Installation
Parent topic: Preparing for configuration


Installation procedure

  • Upload the software
  • Receive the software
  • Configuration overview
  • Quick Configuration
  • Advanced Configuration Activities
  • Running Multiple Instances of Mainframe Access Server
Parent topic: Host Installation


Upload the software

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

To load Mainframe Access Server:

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

    7. On the mainframe, verify that all files transferred successfully and that for each xxxxxxxx file in the \Upload directory there is a corresponding member in the hlq.UPLOAD data set. There should be 19 members.

Parent topic: Installation procedure


Receive the software

In hlq.UPLOAD you now have a partitioned dataset with 19 members. Each member except FRESTORE is a dataset in transmit format. You need to execute TSO RECEIVE commands on the datasets to create the Mainframe Access datasets.

Member | Description | Received to
AUTHLIB | z/Server load library that needs to be APF authorized. | hlq.ZSERVER.AUTHLIB
CONFIG | z/Server default configuration members and XML schema. | hlq.ZSERVER.CONFIG
DATA | z/Server XML sample documents. | hlq.ZSERVER.DATA
EXEC | z/Server REXX procedures run as ISPF applications called from a client via TCP/IP. | hlq.ZSERVER.EXEC
F1 | The load module library for Mainframe Access server that needs to be APF authorized. | hlq.MFA.LOADLIB
F2 | Samples for Mainframe Access server. These include JCL for jobs to be run, JCL for started task procedures and parameter files. The members in this data set are referred to frequently in these configuration instructions. | hlq.MFA.CNTL
F3 | Translation tables used by Mainframe Access server. | hlq.MFA.TABLES
F4 | Product source and object files that you may need during setup of the Remote IMS Server feature. | hlq.MFA.RIMS
FRESTORE | JCL to receive all other members. |
JCL | z/Server JCL samples. | hlq.ZSERVER.JCL
LOADLIB | z/Server load library. | hlq.ZSERVER.LOADLIB
MASTER | z/Server master configuration file. | hlq.ZSERVER.MASTER
MSGS | z/Server ISPF message library belonging to the ISPF applications in EXEC. | hlq.ZSERVER.MSGS
OSR | Optimized schema representation used for internal XML validation. | hlq.ZSERVER.OSR
PANELS | z/Server ISPF panel library belonging to the ISPF applications in EXEC. | hlq.ZSERVER.PANELS
REXX | z/Server REXX procedures and REXX samples. | hlq.ZSERVER.REXX
SAMPLIB | z/Server Sample programs. | hlq.ZSERVER.SAMPLIB
SKELS | z/Server ISPF skeleton library belonging to the ISPF applications in EXEC. | hlq.ZSERVER.SKELS
XML | z/Server Sample models (PDS Explorer). | hlq.ZSERVER.XML

On the mainframe, edit member FRESTORE in the upload library, hlq.UPLOAD. Follow the instructions in that member to customize the JCL and then submit that job to restore the product libraries from the uploaded files and populate your new product runtime libraries.

Parent topic: Installation procedure


Configuration overview

There are two types of configuration tasks that you must complete before you can start and use Mainframe Access. These are:

  • Updating the z/OS mainframe system to create an execution environment for Mainframe Access.
  • Setting parameters to meet your requirements.

The process of configuring Mainframe Access is separated into two distinct procedures. See Quick Configuration and Advanced Configuration Activities for more information.

Quick configuration is performed using the UpQuick instructions as indicated during the installation process. These configuration steps must be completed for all installations. Quick configuration takes care of all of the z/OS customization and many basic Mainframe Access customizations. This quick configuration is the only Mainframe Access setup required for Mainframe Access Drag and Drop, SQL Option for DB2, and basic Mainframe Access Data Connect server functions.

Additional setup is required if:

  • You are going to be using Mainframe Access Data Connect server and you need to use the file name mapping table and/or alter the processing in the SAF security exits.
  • You are going to be using the following features:
    • Remote IMS
    • ES/MSS support
    • Mainframe Access's access list checking
    • Mainframe Access's audit log
    • Mainframe Access's support for external library management systems
    • z/Server support

The section on advanced configuration describes these additional customizations.

If you have completed the installation process, including the UpQuick configuration steps, and if you are not going to use features that require additional setup, your configuration is complete.

If you have uploaded and restored the Mainframe Access data sets but you have not completed the UpQuick configuration, you should begin with the Quick Configuration topic.

If you have completed the configuration and testing of your basic Mainframe Access server and you need to customize for an advanced feature, you should continue at the Advanced Configuration Activities topic.

  • Mainframe Access Data Sets
  • Mainframe Access Samples
Parent topic: Installation procedure


Mainframe Access Data Sets

Following the UpQuick instructions from the installation package, you should have already completed the upload and restore of the Mainframe Access data sets. During that process you selected a high level qualifier to be used for all of your Mainframe Access data sets. This guide refers to the qualifier that you selected as <hlq> or hlq. The data sets that you restored are listed in the following table:

Data Set | Description
hlq.ZSERVER.AUTHLIB | z/Server load library that needs to be APF authorized.
hlq.ZSERVER.CONFIG | z/Server default configuration members and XML schema.
hlq.ZSERVER.DATA | z/Server XML sample documents.
hlq.ZSERVER.EXEC | z/Server REXX procedures run as ISPF applications called from a client via TCP/IP.
hlq.MFA.LOADLIB | The load module library for Mainframe Access server that needs to be APF authorized.
hlq.MFA.CNTL | Samples for Mainframe Access server. These include JCL for jobs to be run, JCL for started task procedures and parameter files. The members in this data set are referred to frequently in these configuration instructions.
hlq.MFA.TABLES | Translation tables used by Mainframe Access server.
hlq.MFA.RIMS | Product source and object files that you may need during setup of the Remote IMS Server feature.
hlq.ZSERVER.JCL | z/Server JCL samples.
hlq.ZSERVER.LOADLIB | z/Server load library.
hlq.ZSERVER.MASTER | z/Server master configuration file.
hlq.ZSERVER.MSGS | z/Server ISPF message library belonging to the ISPF applications in EXEC.
hlq.ZSERVER.OSR | Optimized schema representation used for internal XML validation.
hlq.ZSERVER.PANELS | z/Server ISPF panel library belonging to the ISPF applications in EXEC.
hlq.ZSERVER.REXX | z/Server REXX procedures and REXX samples.
hlq.ZSERVER.SAMPLIB | z/Server Sample programs.
hlq.ZSERVER.SKELS | z/Server ISPF skeleton library belonging to the ISPF applications in EXEC.
hlq.ZSERVER.XML | z/Server Sample models (PDS Explorer).
Parent topic: Configuration overview


Mainframe Access Samples

The installation procedure places many samples in the <hlq>.MFA.CNTL data set. If a sample is provided for a configuration task, use it as a starting point for your configuration. Usually you need to edit the sample, replacing provided information with information that is unique to your system.

The following table summarizes the samples that are provided for Mainframe Access:

Member | Description
ACCESS | List used to restrict access to Mainframe Access consisting of the IP addresses of connecting clients. The access list also contains the list of user IDs that are authorized to access the Mainframe Access administration functions through the Web browser interface. You should add the IP addresses and user IDs for your system. See Editing Access List Definitions for more information.
AUDIT | JCL for creating and initializing a Mainframe Access audit log data set. The audit log is a VSAM key sequenced data set (KSDS). You should edit the sample to include JOB card information, data set names and a volume serial number.
AUDRPT | JCL for running the Mainframe Access audit log report program to list the contents of the audit log data set. You should edit the sample to include JOB card information and data set names.
FRESTORE | A copy of the FRESTORE job for reference purposes. This job was originally transferred from the client to the <hlq>.UPLOAD data set during installation. The job was customized and submitted to allocate the permanent Mainframe Access data sets and restore the data set content from other uploaded files.
GTFCNTL | Input control statements referenced by the sample JCL procedure in member MFAGTF.
INSTALL | A copy of the installation upload instructions for reference purposes. These are the instructions that describe how to allocate the <hlq>.UPLOAD data set and transfer the CD content into that data set.
MFA | JCL for executing Mainframe Access. You should edit the sample to include your data set names. This JCL contains references to the ACCESS, PARMS and SERVERS sample members.
MFAAS | JCL for executing a Mainframe Access Application Server. Application servers are auxiliary address spaces that process specific types of client requests such as Endevor transactions. You should edit the sample to include your data set names. This JCL contains a reference to the PARMSAS sample member.
MFAAMS | JCL for executing a Mainframe Access Application Server for AMS support. Application servers are auxiliary address spaces that process specific types of client requests such as AMS requets. You should edit the sample to include your data set names. This JCL contains a reference to the PARMSAS sample member.
MFAGTF | JCL for running IBM's Generalized Trace Facility (GTF). GTF provides high-performance recording of diagnostic data and can be useful during problem determination. You should edit the sample to include your data set names.
MFANLS | JCL for re-compiling the default code page that may be configured at a client workstation. This is equivalent to the MFLSCTRN load module of Mainframe Access Version 2. During installation the default is set to use code pages E037/A437 for EBCDIC/ASCII translation. The sample JCL contains instructions for changing the default code pages selected by installation.
MFAS | JCL for executing the Mainframe Access Data Connect server. You should edit the sample to include your data set names.
MFAVTAM | Definition of VTAM applications for Mainframe Access, Mainframe Access Data Connect, ES/MSS and Remote IMS Server. You can edit the sample to include your own ACB names and network names. See VTAMLST Definitions for more information.
MFAXML | An XML configuration that contains parameters that are read when Mainframe Access and Mainframe Access Application Server is initialized. The sample JCL for executing Mainframe Access refers to this member for parameter input. You will need to edit some of these parameters. See Editing Mainframe Access Parameters for more information. It also contains definitions that describe the z/OS subsystems that will be providing service in response to client requests. The servers are your IMS and CICS subsystems, the Mainframe Access Data Connect server and ES/MSS servers. You must edit the sample to include information specific to your servers and also coordinate the information with definitions in the client packages.
PVSUFFX | JCL for executing a migration tool which extracts a text definition from the MFLSCPAN load module of Mainframe Access Version 2. See Panvalet for more information.
TSOXMIT | Sample job that uses TSO XMIT to package diagnostic data for transmission.
UPQUICK | A copy of the quick configuration instructions for reference purposes. These are the instructions that describe how to quickly configure z/OS and Mainframe Access to create an operational Mainframe Access server system. See Quick Configuration for more information.
Parent topic: Configuration overview


Quick Configuration

After you have uploaded the mainframe files and successfully run the FRESTORE job, there are some basic customization tasks that must be completed. Quick configuration works through these configuration tasks quickly and gets you to the point where the software can be started and a basic installation verification check can be performed. After the installation verification check, continue with Advanced Configuration Activities if there are additional features that you need to set up.

You should be familiar with TSO, ISPF, SDSF, z/OS system commands, JCL procedures and proclibs, VTAMLST definitions and RACF.

Note: These instructions refer to RACF as the security subsystem. Mainframe Access does use the SAF interface to the security subsystem and is compatible with other security products that provide the SAF API. When these instructions refer to RACF-related customizations, please refer to your security product documentation to determine the corresponding security subsystem changes.

If you are using the ISPF editor to make the configuration changes, use the change command once to make the first update to the hlq value and then use ISPF's Rchange command (usually PF6) to apply the same change in all the members that you need to update. For example: use "c HLQ MY.HIGH.LEVEL" the first time and then PF6 to apply the same change in other places. Changes to other parameters are easily accomplished by overtyping the preset value.

  • MFA Started Task JCL Procedure
  • MFAAS Started Task JCL Procedure
  • MFAS Started Task JCL Procedure
  • MFAAMS Started Task JCL Procedure
  • Mainframe Access MFAXML
  • VTAMLST Definitions
  • Add Started Task JCL Procedures to Proclib
  • APF-Authorize the Load Module Libraries
  • Define Mainframe Access to the Security Subsystem
  • Starting Mainframe Access
  • Stopping Mainframe Access
Parent topic: Installation procedure


MFA Started Task JCL Procedure

Customize member MFA in the CNTL data set. This is the started task JCL procedure for Mainframe Access server. Use the ISPF change command to change HLQ to your qualifier (hlq).

If you are using IBM's TCP/IP, overtype TCPIP.OS390.TCPDATA with the name of your installation's "TCPIP.DATA" data set (tcpdata). This is the data set used by client programs to obtain the name of the TCP/IP started task and other installation-dependent TCP/IP information.

To enable DBCS support, you need to edit the procedure by uncommenting the following four statements:

//*---------------------------------------------------
//* Optional DBCS code pages
//*---------------------------------------------------
//*
//*EZACHLAT DD  DSN=TCPIP.SEZADBCX(EZACHLAT),DISP=SHR
//*EZAHGLAT DD  DSN=TCPIP.SEZADBCX(EZAHGLAT),DISP=SHR
//*EZAKJLAT DD  DSN=TCPIP.SEZADBCX(EZAKJLAT),DISP=SHR
//*EZASCLAT DD  DSN=TCPIP.SEZADBCX(EZASCLAT),DISP=SHR

To start the z/Server holder under MFA, you need to edit the procedure by uncommenting the following five statements.

//*--------------------------------
//* zServer Holder
//*--------------------------------
//*
//*SYSEXEC  DD DISP=SHR,DSN=&TAUQUAL..EXEC
//CONFXML  DD DISP=SHR,DSN=&DSNQUAL..CNTL(MFAXML)
//CONFOSR  DD DISP=SHR,DSN=&TAUQUAL..OSR(MFAOSR)
//*DSPPRT   DD SYSOUT=*,LRECL=255
//*SYSOUT   DD SYSOUT=*
//*SYSTSIN  DD DUMMY
//*SYSTSPRT DD SYSOUT=*
Parent topic: Quick Configuration


MFAAS Started Task JCL Procedure

Customize member MFAAS in the CNTL data set. This is the started task JCL procedure for Mainframe Access Application Servers such as Endevor, ChangeMan, and AMS. Use the ISPF change command to change HLQ to your qualifier (hlq).

If you are using IBM's TCP/IP, overtype TCPIP.OS390.TCPDATA with the name of your installation's "TCPIP.DATA" data set (tcpdata).

Parent topic: Quick Configuration


MFAS Started Task JCL Procedure

Customize member MFAS in the CNTL data set. This is the started task JCL procedure for Mainframe Access Data Connect server. Use the ISPF Rchange command to change HLQ to your qualifier (hlq).

Parent topic: Quick Configuration


MFAAMS Started Task JCL Procedure

Customize member MFAAMS in the CNTL data set. This is the started task JCL procedure for using Access Method Services, required for dataset renaming using MVS Explorer in the eclipse client. Use the ISPF change command to change HLQ to your qualifier (hlq).

If you are using IBM's TCP/IP, overtype TCPIP.OS390.TCPDATA with the name of your installation's "TCPIP.DATA" data set (tcpdata).

Parent topic: Quick Configuration


Mainframe Access MFAXML

Customize member MFAXML in the CNTL data set. These are the Mainframe Access server initialization parameters referenced by the Mainframe Access started task JCL and Mainframe Access Application Server started task JCL.

Change TCP_PORT="2020" to TCP_PORT="clientport". This is the port number that Micro Focus client software should be configured to use.

Change NETWORK_ID="DDINET1" to NETWORK_ID="netid", the VTAM SNA network id of your system.

Parent topic: Quick Configuration


VTAMLST Definitions

Copy member MFAVTAM to vtamlst. This application major node definition contains APPL definitions for Mainframe Access server, Mainframe Access Data Connect server and Remote IMS Server. Use the z/OS VARY command to activate the definition:

V NET,ACT,ID=MFAVTAM
Note:
  • If you change any ACBNAME= values or the PRTCT= value in the MFAVTAM sample you must make corresponding changes:
    • in member MFAXML (if ACBNAME=MFM62ACB is changed)
    • in member MFAXML (if PRTCT=MFM62PSW is changed)
    • in member MFAS (if ACBNAME=MFA62ACB is changed)
  • You will want to add MFAVTAM into the vtamlst (ATCCONxx) member so that this application major node is automatically activated during VTAM initialization.
Parent topic: Quick Configuration


Add Started Task JCL Procedures to Proclib

Copy members MFA, MFAAS and MFAS to proclib.

Note:
  • If you store proc MFAS in proclib using a different name, you must also change PROCDURE attribute of DataConnect in member MFAXML to specify that new procedure name.
  • If you store proc MFAAS in proclib using a different name, you must also change PROCEDURE attribute of the relevant Application Server in member MFAXML to specify that new procedure name.
Parent topic: Quick Configuration


APF-Authorize the Load Module Libraries

Use z/OS SETPROG commands to APF-authorize the load libraries:

SETPROG APF,ADD,DSNAME=hlq.MFA.LOADLIB,VOLUME=loadvolser
Note: Add these APF library definitions to a SYS1.PARMLIB(PROGxx) member so that these same authorizations are automatically activated during z/OS system initialization.
Parent topic: Quick Configuration


Define Mainframe Access to the Security Subsystem

Use RACF TSO commands to define the Mainframe Access started tasks (MFA, MFAAS and MFAS) and assign a userid and groupid to the tasks. The stcuserid should have appropriate access to the Mainframe Access data sets and should also have a basic OMVS RACF segment defined. At a minimum, the stcuserid OMVS segment must have a UID. The stcgroup must also have an OMVS segment with a GID. The following REDEFINE will provide the necessary definition for all of the started tasks (MFA, MFAAS and MFAS).

RDEFINE STARTED MFA*.* STDATA(USER(stcuserid) GROUP(stcgroup))
   OWNER(stcuserid)
SETROPTS RACLIST(STARTED) REFRESH

If you are using another security product such as CA-ACF2 or CA-Top Secret you will need to make similar updates to your security system definitions. MFA, MFAAS and MFAS will need a started task definition with an OMVS segment and they will need access to the SAF API for security subsystem calls. Please refer to your security product documentation.

Parent topic: Quick Configuration


Starting Mainframe Access

When you have completed all of the tasks described in the preceding sections you are ready to start Mainframe Access to perform some simple installation verification tests. Start Mainframe Access by issuing the following z/OS START command at a system console or using the TSO/ISPF SDSF command facility:

S MFA

Here is an example that shows the messages displayed during startup. The start command is issued for MFA, the name of the started task JCL sample that has been customized and copied into a system procedure library. The MFAXML sample also defines the Mainframe Access Data Connect server as an application server address space that should be started automatically by Mainframe Access during initialization. Mainframe Access issues an internal start command for MFAS, the name of the started task JCL sample for the Mainframe Access Data Connect server.

04:11:52.41 XXXXXXXX 00000290  S MFA
04:11:52.47 STC03887 00000090  £HASP100 MFA   ON STCINRDR
04:11:52.55 STC03887 00000290  IEF695I START MFA   WITH JOBNAME MFA   IS ASSIGNED TO USER XXXXXXXX
                                , GROUP XXXXXXXX
04:11:52.55 STC03887 00000090  £HASP373 MFA   STARTED
04:11:52.56 STC03887 00000090  IEF403I MFA - STARTED - TIME=04.11.52
04:11:53.06 STC03887 00000090  MFM0063I: MFA Direct is active
04:11:53.06 STC03887 00000090  MFM0064I: MFA Direct number of processing tasks is 10
04:11:53.09 STC03887 00000090  MFM0134I: ES/MTO Outbound feature is active
04:11:53.10 STC03887 00000090  MFM0127I: ChangeMan subsystem ID is SERA
04:11:53.20 STC03887 00000090  MFMDS008I DBCS code page support enabled
04:11:53.22 STC03887 00000090  MFMDS051I CA/LIBrarian Ready
04:11:53.27 STC03887 00000090  MFMDS052I CA/PanValet Ready
04:11:53.29 STC03887 00000090  MFMDS053I CA/ENDEVOR API REL=B1700C,ESI=N,UID=N
04:11:53.46 STC03887 00000090  MFMDS055I MCG/RPC feature active
04:11:53.46 STC03887 00000090  MFMDS001I DSS Server Ready
04:11:54.32 STC03888 00000090  £HASP100 MFAS  ON STCINRDR
04:11:54.39 STC03888 00000090  £HASP373 MFAS  STARTED
04:11:54.40 STC03888 00000090  IEF403I MFAS - STARTED - TIME=04.11.54
04:11:54.48 STC03888 00000090  MFA302I.MFAS.MFDSTART / ATTACHING VTAM PROCESSOR
04:11:54.48 STC03888 00000090  MFA303I.MFAS.MFDSTART / MFA/DATACONNECT V6.00 - 04000000 COPYRIGHT
                               (C) 1987-2018 MICRO FOCUS INTERNATIONAL LTD.
04:11:54.49 STC03888 00000090  MFA110I.MFAS.MFAFSQ00 / VTAM PROCESSOR ACTIVE USING VTAMAPPL MFA62ACB
04:11:59.29 STC03887 00000090  MFM0001I: Mainframe Access V6.00    (04000000) is active
Parent topic: Quick Configuration


Stopping Mainframe Access

Stop Mainframe Access by issuing the following z/OS STOP command at a system console or using the TSO/ISPF SDSF command facility:

P MFA

Here is an example that shows the messages displayed during shutdown. The stop command is issued only for Mainframe Access, the Mainframe Access server. Mainframe Access issues an internal stop command for MFAS, the application server address space for Mainframe Access Data Connect that was defined in the SERVERS member and started automatically by Mainframe Access. MFAS ends first and then Mainframe Access completes its shutdown processing.

04:50:44.70 XXXXXXXX 00000290  P MFA
04:50:50.72 STC01318 00000090  MFMDS005I DSS Server shutdown
04:51:01.02 STC01318 00000290  P MFAS
04:51:01.03 STC01319 00000090  MFA112I.MFAS.MFAFSQ00 / VTAM PROCESSOR HAS TERMINATED
04:51:02.04 STC01319 00000090  MFA317I.MFAS.MFDSTART / HAS BEEN TERMINATED
04:51:02.06 STC01319 00000090  IEF404I MFAS - ENDED - TIME=04.51.02
04:51:02.06 STC01319 00000090  £HASP395 MFAS  ENDED - RC=0000
04:51:12.54 STC01318 00000090  MFM0011I: Mainframe Access shutdown completed
04:51:12.59 STC01318 00000090  IEF404I MFA - ENDED - TIME=04.51.12
04:51:12.60 STC01318 00000090  £HASP395 MFA   ENDED - RC=0000
Parent topic: Quick Configuration


Advanced Configuration Activities

Mainframe Access is a general purpose server supporting a variety of Micro Focus client products. The Quick Configuration process that you have completed enables a large number of Mainframe Access server features that will satisfy most access requirements. This section describes the customizations (beyond the quick configuration) that are needed to enable various additional features of Mainframe Access server.

The following table summarizes the required updates on a per-feature basis. This will help you to select the correct configuration activities for a specific feature.

Feature | Customization
Audit Log | Refer to Allocating and Initializing an Audit Log Data Set to prepare the data set. Then see Editing Mainframe Access Parameters and update the audit log parameter to AUDIT_LOG="1".
Access List | Refer to Editing Access List Definitions for guidance in defining IP addresses and address ranges. Then see Editing Mainframe Access Parameters and update the access list check parameter to ACCESS_LIST_CHECK="1".
CICS support | Using CICS support, clients can interact with z/OS CICS servers for file access, remote program execution, transaction execution, etc. Activate support for this feature by setting MCOLINK_MAXTASKS="2". The number of tasks supporting this feature can be increased in the future as your usage dictates. To complete the setup for this feature you will need to customize your client and the z/OS CICS server.
Remote IMS Option | Using the Remote IMS Option, clients can execute DL/I calls that are processed by a z/OS IMS server. Activate support for this feature by setting IMSLINK_MAXTASKS="2". The number of tasks supporting this feature can be increased in the future as your usage dictates. To complete the setup for this feature you will need to customize your client and the z/OS IMS server. You must also install the Remote IMS server software in the target z/OS IMS server and enable APPC/MVS communications for that IMS server. All of the machine-readable installation materials for your Remote IMS Server can be found in the <hlq>.RIMS data set.
List DB2 | Mainframe Access' List DB2 feature dynamically identifies z/OS DB2 and IMS servers that are active on the z/OS system where Mainframe Access server is executing. This information can be helpful when defining these systems to Mainframe Access server and clients. Activate support for this feature by setting LIST_DB2="1".
Data Connect | Quick Configuration installs the Mainframe Access Data Connect server with SAF security checking active and without special customizations for PC to mainframe file name mapping. If you need to alter this basic setup see the appendix Data Connect.
Enterprise Server/Mainframe Subsystem Support | Enterprise Server/Mainframe Subsystem Support (ES/MSS) enables Mainframe Access server to accept CICS ISC requests initiated by z/OS CICS and route them to an ES/MSS server for execution. The combination of ES/MSS support and the CICS support creates a bi-directional ISC connection between ES/MSS and z/OS CICS. To complete the setup for this feature you need to customize your ES/MSS server(s) and the z/OS CICS server(s). See your Enterprise Server documentation and IBM z/OS CICS publications for help with these customizations.
ChangeMan interface | Mainframe Access' Source Connect feature works with ChangeMan to provide client access to ChangeMan-managed files. For more information see the section ChangeMan ZMF in the appendix External Library Management Systems.
Panvalet interface | Mainframe Access' Source Connect feature works with Panvalet to provide client access to Panvalet-managed files. For more information see the section Panvalet in the appendix External Library Management Systems.
Librarian interface | Mainframe Access' Source Connect feature works with Librarian to provide client access to Librarian-managed files. For more information see the section Librarian in the appendix External Library Management Systems.
Endevor interface | Mainframe Access' Source Connect feature works with Endevor to provide client access to Endevor-managed files. For more information see the section Endevor in the appendix External Library Management Systems.
z/Server support | Mainframe Access' z/Server feature ….. For more information about configuring z/Server see the section Configuring Access to z/Server.
Note: As noted in the preceding customization summaries, you also need to prepare the external servers and clients that Mainframe Access works with.
  • Editing Mainframe Access Parameters
  • Editing Mainframe Access Application Server Parameters
  • Editing Access List Definitions
  • Allocating and Initializing an Audit Log Data Set
  • Adding Mainframe Access to TCP/IP's Autolog List
  • Setting Up a Mainframe Access GTF Procedure
  • Defining RACF Profiles for JES Spool Access
Parent topic: Installation procedure


Editing Mainframe Access Parameters

You edit the Mainframe Access parameter definitions located in member MFAXML to customize them for your system. The sample parameter definitions are provided here as a convenient reference while you read. MFAXML is an XML formatted file, so any lines that are surrounded by the XML comment characters <!-- and --> are treated as comments and are skipped in processing.

<Configuration
                     TCP_PORT="2020"
                     NETWORK_ID="DDINET1"
                     LU62_APPLID="MFM62ACB"
                     APPLID_PASSWORD="MFM62PSW"
                     TRACING="0"
             ORGANIZATION="YOUR_COMPANY_NAME"
>

    <!-- Application Server address space definitions  -->
    <ApplicationServers>
        <!-- Mainframe Access Server (Data Connect) address space -->
        <DataConnect PROCEDURE="MFAS"
        />

        <!-- Mainframe Access Application Server(s) for Endevor -->
        <Endevor     PROCEDURE="MFAAS" MAXIMUM="2" JOBNAME="MFAE"
        />

        <!-- IDCAMS address space - needed for data set RENAME support -->
        <AMS         PROCEDURE="MFAMS" MAXIMUM="1" JOBNAME="MFAA"
        />

        <!-- z/Server Scheduler -->
        <!--
        <Scheduler   SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200"
                     FIRST_PORT="1201" LAST_PORT="1249"
                     USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
                     DEFAULT="1"
        >
            <UserServer CCSID="037" />
        </Scheduler>
        -->
    </ApplicationServers>

    <!-- Service Configuration -->
    <Services>
        <!-- MFA Data Connect server - only one DEFAULT server is supported -->
        <MFA         ID="DEFAULT" LUNAME="MFA62ACB" MODENAME="#INTER"
                     TPNAME="FILESHR2" SYNCLEVEL="1" SECURITY="0"
        />

        <!-- Sample IMS servers - multiple servers may be defined -->
        <!--
        <RIMS        ID="IMSA" LUNAME="IMSSYSA" MODENAME="IBMRDB"
                     TPNAME="MFDBTP6" SYNCLEVEL="0" SECURITY="0"
        />

        <RIMS        ID="DEFAULT" LUNAME="IMSTEST" MODENAME="IBMRDB"
                     TPNAME="MFDBTP6" SYNCLEVEL="0" SECURITY="0"
        />
        -->

        <!-- Sample CICS servers - multiple servers may be defined -->
        <!--
        <MCO         ID="CICA" LUNAME="CICSSYSA" MODENAME="#INTER"
                     TPNAME="*" SYNCLEVEL="0" SECURITY="0"
        />

        <MCO         ID="DEFAULT" LUNAME="CICSTEST" MODENAME="#INTER"
                     TPNAME="*" SYNCLEVEL="0" SECURITY="0"
        />
        -->

        <!-- Sample ES/MTO servers - multiple servers may be defined -->
        <!--
        <ES-MTO      ID="MTO1" ACBNAME="MFAMTO1" IPADDRESS="YOUR.MTO.HOSTNAME"
                     PORT="2200" SESSIONS="4" SOCKETS="1"
        />

        <ES-MTO      ID="MTO2" ACBNAME="MFAMTO2" IPADDRESS="101.102.103.104"
                     PORT="3300" SESSIONS="4" SOCKETS="1"
        />
        -->
    </Services>
</Configuration>

The section in bold above highlights the area of the XML file that you can edit, add or remove parameters to in order to control Mainframe Access behaviour. See Configuration reference for more information on the available parameters.

Parent topic: Advanced Configuration Activities


Editing Mainframe Access Application Server Parameters

The MFAXML member also contains definitions that describe both application servers and services. Service definitions such as RIMS, MCO, MFA and ES-MTO provide an ID label and the LU 6.2 parameters needed to contact the server using SNA LU 6.2 protocols. The ID label is used in some client configurations to select a specific target server.

Application servers definitions such as DataConnect, Endevor, ChangeMan and AMS define address spaces that can be started and controlled by Mainframe Access server. The definition provides a JCL procedure name that can be used to start the address space, a server program name, values that govern the number of address spaces that can be started, etc.

If you will be using CICS Option or IMS Option, you must edit the Mainframe Access sample services definitions to customize them for your system. The application server and service definitions for the Mainframe Access Data Connect server will need to be edited only if you have changed the JCL procedure name or the VTAM APPL ACBNAME, or if the default logmode name cannot be used.

The sample definitions for services that you will not be using can be commented out and they will not affect the operation of Mainframe Access with services that you have customized. For example, if you are not using CICS Option you can leave the sample CICS target server definitions unchanged; or you can delete them altogether.

The sample server definitions are provided here as a convenient reference while you read. Lines that begin with an asterisk are treated as comments and are skipped in processing.

<Configuration
                     TCP_PORT="2020"
                     NETWORK_ID="DDINET1"
                     LU62_APPLID="MFM62ACB"
                     APPLID_PASSWORD="MFM62PSW"
                     TRACING="0"
             ORGANIZATION="YOUR_COMPANY_NAME"
>

    <!-- Application Server address space definitions  -->
    <ApplicationServers>
        <!-- Mainframe Access Server (Data Connect) address space -->
        <DataConnect PROCEDURE="MFAS"
        />

        <!-- Mainframe Access Application Server(s) for Endevor -->
        <Endevor     PROCEDURE="MFAAS" MAXIMUM="2" JOBNAME="MFAE"
        />

        <!-- IDCAMS address space - needed for data set RENAME support -->
        <AMS         PROCEDURE="MFAMS" MAXIMUM="1" JOBNAME="MFAA"
        />

        <!-- z/Server Scheduler -->
        <!--
        <Scheduler   SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200"
                     FIRST_PORT="1201" LAST_PORT="1249"
                     USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
                     DEFAULT="1"
        >
            <UserServer CCSID="037" />
        </Scheduler>
        -->
    </ApplicationServers>

    <!-- Service Configuration -->
    <Services>
        <!-- MFA Data Connect server - only one DEFAULT server is supported -->
        <MFA         ID="DEFAULT" LUNAME="MFA62ACB" MODENAME="#INTER"
                     TPNAME="FILESHR2" SYNCLEVEL="1" SECURITY="0"
        />

        <!-- Sample IMS servers - multiple servers may be defined -->
        <!--
        <RIMS        ID="IMSA" LUNAME="IMSSYSA" MODENAME="IBMRDB"
                     TPNAME="MFDBTP6" SYNCLEVEL="0" SECURITY="0"
        />

        <RIMS        ID="DEFAULT" LUNAME="IMSTEST" MODENAME="IBMRDB"
                     TPNAME="MFDBTP6" SYNCLEVEL="0" SECURITY="0"
        />
        -->

        <!-- Sample CICS servers - multiple servers may be defined -->
        <!--
        <MCO         ID="CICA" LUNAME="CICSSYSA" MODENAME="#INTER"
                     TPNAME="*" SYNCLEVEL="0" SECURITY="0"
        />

        <MCO         ID="DEFAULT" LUNAME="CICSTEST" MODENAME="#INTER"
                     TPNAME="*" SYNCLEVEL="0" SECURITY="0"
        />
        -->

        <!-- Sample ES/MTO servers - multiple servers may be defined -->
        <!--
        <ES-MTO      ID="MTO1" ACBNAME="MFAMTO1" IPADDRESS="YOUR.MTO.HOSTNAME"
                     PORT="2200" SESSIONS="4" SOCKETS="1"
        />

        <ES-MTO      ID="MTO2" ACBNAME="MFAMTO2" IPADDRESS="101.102.103.104"
                     PORT="3300" SESSIONS="4" SOCKETS="1"
        />
        -->
    </Services>
</Configuration>

The section in bold above highlights the area of the XML file that you can edit, add or remove parameters to in order to control Mainframe Access behaviour in regard to application servers and services. See Configuration reference for more information on the available parameters.

  • Application Servers
  • Services
Parent topic: Advanced Configuration Activities


Application Servers

  • Application Server Parameters for the Mainframe Access Data Connect Server
  • Application Server Parameters for Endevor support
  • Application Server Parameters for AMS/IDCAMS support
  • Application Server Parameters for ChangeMan support
  • Application Server Parameters for z/Server Scheduler support
Parent topic: Editing Mainframe Access Application Server Parameters


Application Server Parameters for the Mainframe Access Data Connect Server

An example of the DataConnect configuration:

<!-- Mainframe Access Server (Data Connect) address space -->
<DataConnect PROCEDURE="MFAS"
/>

Use the following parameters to configure Data Connect:

PROCEDURE
The JCL procedure name that will be used when the address space is started.

See Configuration reference for more information on the parameters available for a Data Connect application server.

Parent topic: Application Servers


Application Server Parameters for Endevor support

An example of the Endevor configuration:

<!-- Mainframe Access Server (Data Connect) address space -->
<Endevor PROCEDURE="MFAAS" MAXIMUM="2" JOBNAME="MFAE"
/>

Use the following parameters to configure ChangeMan:

PROCEDURE
Specifies the JCL procedure name that is used when the address space is started.
MAXIMUM
Specifies the maximum number of address spaces that Mainframe Access server starts for Endevor support.
JOBNAME
Specifies the jobname prefix to be used for address spaces that are started for Endevor support.

See Configuration reference for more information on the parameters available for an Endevor application server.

Parent topic: Application Servers


Application Server Parameters for AMS/IDCAMS support

If you are planning to use the MFA Server z/Server feature it is required that you must also configure an AMS Application Server.

An example of the AMS configuration:

<!-- IDCAMS address space – needed for data set RENAME support -->
<AMS PROCEDURE="MFAAMS" MAXIMUM="1" JOBNAME="MFAA"
/>

Use the following parameters to configure AMS:

PROCEDURE
Specifies the JCL procedure name that is used when the address space is started.
MAXIMUM
Specifies the maximum number of address spaces that Mainframe Access server starts for IDCAMS support.
JOBNAME
Specifies the jobname prefix to be used for address spaces that are started for Endevor support.

See Configuration reference for more information on the parameters available for an AMS application server.

Parent topic: Application Servers


Application Server Parameters for ChangeMan support

An example of the ChangeMan configuration:

<!-- Mainframe Access Server (Data Connect) address space -->
<ChangeMan PROCEDURE="MFAAS"
/>

Use the following parameters to configure ChangeMan:

PROCEDURE
Specifise the JCL procedure name that is used when the address space is started.

See Configuration reference for more information on the parameters available for a ChangeMan application server.

Parent topic: Application Servers


Application Server Parameters for z/Server Scheduler support

An example of the z/Server scheduler configuration:

<!-- z/Server Scheduler -->
<Scheduler   SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200"
             FIRST_PORT="1201" LAST_PORT="1249"
             USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
             DEFAULT="1"
>
    <UserServer CCSID="037" />
</Scheduler>

See Configuring z/Server feature support for more information on configuring Mainframe Access z/Server feature support.

Parent topic: Application Servers


Services

  • Service Parameters for ES/MSS
  • Service Parameters for Mainframe Access Data Connect Server
  • Service Parameters for IMS Option (Remote IMS)
  • Service Parameters for CICS
Parent topic: Editing Mainframe Access Application Server Parameters


Service Parameters for ES/MSS

An example of the ES/MSS configuration:

<!-- Sample ES/MSS servers - multiple servers may be defined -->
<ES-MTO      ID="MTO1" ACBNAME="MFAMTO1" IPADDRESS="YOUR.MTO.HOSTNAME"
             PORT="2200" SESSIONS="4" SOCKETS="1"
/>

<ES-MTO      ID="MTO2" ACBNAME="MFAMTO2" IPADDRESS="101.102.103.104"
             PORT="3300" SESSIONS="4" SOCKETS="1"
/>

These statements define an ES/MSS server and provide MFA Server with the information needed to establish a TCP/IP socket connection to the ES/MSS server. This definition also creates a VTAM ACB that represents the ES/MSS server to the z/OS CICS system(s). Use the following parameters to configure ES-MTO:

ID
Specifies the SYSID of the ES/MSS server being defined.
ACBNAME
Specifies the name of the VTAM ACB associated with this ES/MSS server.
IPADDRESS
Specifies the internet host name or IP address of the ES/MSS server.
PORT
Specifies the port number where ES/MSS is listening for ISC connections.
SESSIONS
Specifies the number of concurrent conversations MFA Server can initiate to the ES/MSS server over a single socket connection.
SOCKETS
Specifies the maximum number of concurrent socket connections between MFA Server and the ES/MSS server.

See Configuration reference for more information on the parameters available for an ES/MSS services.

Parent topic: Services


Service Parameters for Mainframe Access Data Connect Server

An example of the ES/MSS configuration:

<!-- MFA Data Connect server - only one DEFAULT server is supported -->
<MFA         ID="DEFAULT" LUNAME="MFA62ACB" MODENAME="#INTER"
             TPNAME="FILESHR2" SYNCLEVEL="1" SECURITY="0"
/>

These statements define an ES/MSS server and provide MFA Server with the information needed to establish a TCP/IP socket connection to the ES/MSS server. This definition also creates a VTAM ACB that represents the ES/MSS server to the z/OS CICS system(s). Use the following parameters to configure ES-MTO:

ID
Data Connect client requests do not specify a target server ID and Mainframe Access always looks for the DEFAULT Mainframe Access Data Connect target server definition. Specify DEFAULT.
LUNAME
The LU name of the Mainframe Access Data Connect server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters.
MODENAME
The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the Mainframe Access Data Connect server.
TPNAME
The transaction program name for Mainframe Access Data Connect server requests. Specify FILESHR2.
SYNCLEVEL
The SNA LU6.2 sync level option to be used on conversations with the Mainframe Access Data Connect server.
SECURITY
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the Mainframe Access Data Connect server.

See Configuration reference for more information on the parameters available for an MFA Data Connect service.

Parent topic: Services


Service Parameters for IMS Option (Remote IMS)

An example of the RIMS configuration:

<!-- Sample IMS servers - multiple servers may be defined -->
<RIMS        ID="IMSA" LUNAME="IMSSYSA" MODENAME="IBMRDB"
             TPNAME="MFDBTP6" SYNCLEVEL="0" SECURITY="0"
/>

<RIMS        ID="DEFAULT" LUNAME="IMSTEST" MODENAME="IBMRDB"
             TPNAME="MFDBTP6" SYNCLEVEL="0" SECURITY="0"
/>

Use the following parameters to configure RIMS:

ID
If an IMS Option client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT IMS target server, if one has been defined. This IMS target server ID name is used in the configuration of the client. When a Remote IMS request is sent this name is sent in the request data and is used to locate the target server definition for the IMS system that will receive the request. Specify DEFAULT or an ID of up to four alphanumeric characters.
LUNAME
The LU name of the IMS server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters. This name must match the ACBNAME defined in an APPC/MVS LU definition for the target IMS system.
MODENAME
The SNA log mode name that will be used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the IMS server.
TPNAME
The IMS server transaction program name for IMS Option transactions.
SYNCLEVEL
The SNA LU6.2 sync level option to be used on conversations with the IMS server. Specify 0.
SECURITY
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the IMS server.

See Configuration reference for more information on the parameters available for a Remote IMS service.

Parent topic: Services


Service Parameters for CICS

An example of the CICS configuration:

<!-- Sample CICS servers - multiple servers may be defined -->
<MCO         ID="CICA" LUNAME="CICSSYSA" MODENAME="#INTER"
             TPNAME="*" SYNCLEVEL="0" SECURITY="0"
/>

<MCO         ID="DEFAULT" LUNAME="CICSTEST" MODENAME="#INTER"
             TPNAME="*" SYNCLEVEL="0" SECURITY="0"
/>

Use the following parameters to configure RIMS:

ID
If a CICS client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT CICS target server, if one has been defined. This CICS target server ID name is used in the configuration of the client. When a CICS request is sent to Mainframe Access this name is sent in the request data and is used to locate the target server definition for the CICS system that will receive the request. Specify DEFAULT or an ID of up to four alphanumeric characters.
LUNAME
Specifies the LU name of the CICS server (also known as the ACBNAME or VTAM APPLID). Specify a LU name of up to eight characters.
MODENAME
Specifies the SNA log mode name that is used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with mainframe CICS.
TPNAME
Specifies the server transaction program name for CICS requests.
SYNCLEVEL
Specifies the SNA LU6.2 sync level option to be used on conversations with CICS. Specify 0.
SECURITY
Specifies the security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the CICS server.
Parent topic: Services


Editing Access List Definitions

You must edit the access list definitions located in member ACCESS to customize them for your installation. The definitions in this list are:

  • PERMIT and REJECT lines - these specify the IP addresses from which client connections are allowed or rejected. Client connection requests are checked only if the Mainframe Access parameter ACCESS_LIST_CHECK is set to YES. You must customize the PERMIT and REJECT lines with appropriate values for your implementation

The sample access list definitions are provided here as a convenient reference while you read. Lines that begin with an asterisk are treated as comments and are skipped in processing:

*--------------------------------------------------------------------*
*                                                                    *
* Micro Focus Mainframe Access - Access List                         *
*                                                                    *
*--------------------------------------------------------------------*
*
*--------------------------------------------------------------------*
* Permission list                                                    *
*--------------------------------------------------------------------*
*
PERMIT=111.111.111
*
*--------------------------------------------------------------------*
* Rejection list                                                     *
*--------------------------------------------------------------------*
*
REJECT=222.222.222
*
END
  • Permission and Rejection Lists
Parent topic: Advanced Configuration Activities


Permission and Rejection Lists

If you specify ACCESS LIST CHECK=YES in the Mainframe Access parameter file and specify the access list filename in an //XDBACC DD statement in the Mainframe Access startup JCL, client connection requests are accepted or rejected according to the values you specify for the PERMIT and REJECT parameters:

PERMIT=ipaddress
REJECT=ipaddress

The format of the IP address is the familiar dotted decimal notation. A complete Internet address consists of four decimal numbers or address groups, each in the range 0 through 255, with the groups being separated by decimal points.

You can specify complete Internet addresses to permit or reject individual clients.

You can also specify a range of consecutive Internet addresses in a single statement, by omitting one or more trailing address groups. This is known as a masked address specification. To decide whether or not a particular request is to be allowed, Mainframe Access first shortens the client address by removing trailing address groups that correspond to address groups omitted in the specification, then compares the shortened address with the masked address.

If you are using the access list mechanism, client connection requests from all addresses not specified in PERMIT or REJECT parameters are rejected.

Here are two example sets of access list parameters

  • Example 1
  • Example 2
Parent topic: Editing Access List Definitions


Example 1

PERMIT = 111.111.148
REJECT = 111.111.148.244

The effect of these parameter values is that all client connection requests from IP addresses in the range 111.111.148.0 to 111.111.148.255 are accepted with the exception of client address 111.111.148.244. Client connections from all other IP addresses are rejected.

Parent topic: Permission and Rejection Lists


Example 2

PERMIT = 11.1.82
REJECT = 11.1.82.4
PERMIT = 111.202.111.18

The effect of these parameter values is that all client connection requests from IP addresses in the range 11.1.82.0 through 11.1.82.255 are accepted with the exception of client address 11.1.82.4. Client connections requests from the address 11.202.111.18 are also accepted. Connection requests from all other IP addresses are rejected

Parent topic: Permission and Rejection Lists


Allocating and Initializing an Audit Log Data Set

The Mainframe Access audit log feature uses a VSAM data set to record client login and logout information. The information that is logged includes the user ID, client IP address, login and logout times, target server name and encryption usage. If you want to use the audit log feature you need to prepare the audit log data set and update the Mainframe Access JCL procedure.

Sample member AUDIT contains the JCL to allocate and initialize a Mainframe Access audit log VSAM data set. Edit the JOB card, data set names and volume serial number information, then submit the job and verify that the condition code for the INITLOG step is 0 (zero). Note that a condition code of 8 for the ALLOCLOG step is normal the first time that you run this job.

When editing the data set names you may use a global change command to change all instances of HLQ to the high level qualifier that you selected for Mainframe Access data sets during the installation procedure.

Edit the Mainframe Access startup JCL to make the audit log data set available. Do this by removing the keyword DUMMY and the trailing comma (DUMMY,) from the XDBAUDIT DD statement:

    //*
    //*-----------------------------
    //* Optional audit log data set
    //*-----------------------------
    //*
    //XDBAUDIT DD  DUMMY,DISP=SHR,DSN=&DSNQUAL..AUDIT
Parent topic: Advanced Configuration Activities


Adding Mainframe Access to TCP/IP's Autolog List

If you are using IBM's TCP/IP, you can add the Mainframe Access started task name (the name of the Mainframe Access JCL procedure in the system procedure library) to the TCP/IP autolog list. TCP/IP will then automatically start Mainframe Access when it starts and stop Mainframe Access when it stops. Do not perform this update until you have finished configuring Mainframe Access and are satisfied with the way Mainframe Access is running.

Parent topic: Advanced Configuration Activities


Setting Up a Mainframe Access GTF Procedure

Mainframe Access provides sample members MFAGTF and GTFCNTL to assist you when you need to use IBM's Generalized Trace Facility (GTF) to obtain trace data for problem determination. In some problem situations our Product Support will request a VTAM trace of an application LU, usually the Mainframe Access server LU.

  • Adding the GTF Procedure to a System Procedure Library
  • Testing the Mainframe Access GTF Procedure
Parent topic: Advanced Configuration Activities


Adding the GTF Procedure to a System Procedure Library

Sample JCL to run GTF as a started task is provided in member MFAGTF. Edit this JCL to customize the data set names for your installation and then copy the JCL into a system procedure library that is available when z/OS START commands are processed. Member GTFCNTL contains GTF control statements that are referenced by the sample GTF JCL procedure. The USR=(FF1,FEF,0E9) statement in this member specifies the recording of VTAM buffer trace records (FF1 and FEF) and Mainframe Access server trace records (0E9).

Note: If you change the Mainframe Access EID="00E9" parameter setting, you should update member GTFCNTL with the new value. See Editing Mainframe Access Parameters for more information.
Parent topic: Setting Up a Mainframe Access GTF Procedure
Related information
Editing Mainframe Access Parameters


Testing the Mainframe Access GTF Procedure

After you customize and install procedure MFAGTF you can test out the procedure by issuing the following z/OS START command at a system console or using the TSO/ISPF SDSF command facility:

S MFAGTF.MYGTF

GTF will start and read the GTFCNTL parameter file. When the initialization complete message is issued GTF is ready to record trace data.

S MFAGTF.MYGTF
$HASP100 MFAGTF   ON STCINRDR
IEF695I START MFAGTF WITH JOBNAME MFAGTF IS ASSIGNED TO USER RWITEK, GROUP CSIDVLP
$HASP373 MFAGTF   STARTED
IEF403I MFAGTF - STARTED - TIME=19.08.44
AHL121I  TRACE OPTION INPUT INDICATED FROM MEMBER GTFCNTL OF PDS
<hlq>.CNTL
TRACE=USRP
USR=(FF1,FEF,0E9)
END
AHL103I  TRACE OPTIONS SELECTED --USR=(FEF,FF1,0E9)
AHL906I THE OUTPUT BLOCK SIZE OF    27998 WILL BE USED FOR OUTPUT 228
        DATA SETS:
          <hlq>.TRACE
AHL080I GTF STORAGE USED FOR GTF DATA: 229
        GTFBLOCK STORAGE       82K BYTES (BLOK=        40K)
        PRIVATE STORAGE      1038K BYTES
        SADMP HISTORY          54K BYTES (SADMP=       40K)
        SDUMP HISTORY          54K BYTES (SDUMP=       40K)
        ABEND DUMP DATA         0K BYTES (ABDUMP=       0K)
AHL031I GTF INITIALIZATION COMPLETE

You stop GTF by issuing the following z/OS STOP command at a system console or using the TSO/ISPF SDSF command facility:

P MYGTF

GTF acknowledges the stop command and closes down, as shown in the following example:

P MYGTF
AHL006I GTF ACKNOWLEDGES STOP COMMAND
IEF404I MFAGTF - ENDED - TIME=19.10.31
$HASP395 MFAGTF   ENDED
$HASP250 MFAGTF PURGED -- (JOB KEY WAS B9C101AA)
Parent topic: Setting Up a Mainframe Access GTF Procedure


Defining RACF Profiles for JES Spool Access

MFA now uses the RACF classes JESSPOOL and JESJOBS to check a user's authority to read or delete a job on the spool. See z/OS Security Server RACF Security Administrator's Guide for more information. When a request to read (IMPORT) a job or SYSOUT is received the following JESSPOOL profile is checked:

nodename.userid.jobname.jobid.dsidentifier.name

When a CANCEL, HOLD, or RELEASE command is received one of the following JESJOBS profiles are checked:

CANCEL.nodename.userid.jobname
HOLD.nodename.userid.jobname
RELEASE.nodename.userid.jobname

If no profile is defined then MFA reverts to checking the job's ownership.

Parent topic: Advanced Configuration Activities


Running Multiple Instances of Mainframe Access Server

Mainframe Access server is a robust server that is designed to efficiently handle all of the different client access requirements in high-volume usage. A single instance of Mainframe Access server will most likely meet the needs of your installation. It is, however, possible to run multiple instances of Mainframe Access server on your z/OS system. This might be desirable for establishing test and production servers, isolating specific user groups in their own server, isolating specific feature activations, etc.

Once you have a successful Mainframe Access server installation you can easily create additional instances as follows:

  • Create and activate VTAMLST APPL definitions for a new Mainframe Access server and a new Mainframe Access Data Connect server.
  • Reserve a unique TCP/IP port for the new Mainframe Access server (a TCP_PORT).
  • Create unique MFAXML and ACCESS members for the new instance and customize them appropriately. You will definitely need to create a unique PARMS member and assign unique values to the LU62_APPLID="" and TCP_PORT="" parameters. It is possible to share ACCESS definitions, if that will meet the needs of your configuration. An alternative method would be to create a copy of the CNTL data set and retain the original member names.
  • Allocate a unique audit log data set for the new instance if you are using this feature.
  • Create a copy of the MFA proc in the proclib data set and update the JCL to reference the new MFAXML and ACCESS members for this instance. Also, update the audit log data set name if you are using this feature.
  • Create a copy of the MFAS proc in the proclib data set and update the JCL EXEC statement PARM field to specify the new MFAS ACBNAME in the APPLID="" parameter. Also, update the VSAMCTL DD statement data set name if you want to allocate and manage a different set of mapping members for this instance.
  • Update the MFAXML definition for the new instance with the name of the new proc that was created from the MFAS proc (that is, update the PROCEDURE="MFAS" value).
Parent topic: Installation procedure


Troubleshooting

This chapter contains information that will help you to diagnose software problems related to Mainframe Access.

  • Abend Codes
  • LU6.2 Diagnostic Information
  • Mainframe Access Host Error Codes
  • Mainframe Access Remote IMS Error Codes
  • IBM SAF and RACF Error Codes
  • Mainframe Access Audit Report Program
  • Obtaining a VTAM Buffer Trace
Parent topic: Mainframe Access Installation Guide


Abend Codes

An abend, or abnormal end, is the most obvious way for a software problem to be indicated. The z/OS processing for an abend normally creates a dump of the failing program's address space storage for use in problem determination. An abend can be initiated by Mainframe Access itself or by other software components of the z/OS system. Although a program abend is most often the result of a software error within the failing program, abend conditions can also be caused by other software and hardware components of the system.

  • System Abend Codes
  • Mainframe Access User Abend Codes
Parent topic: Troubleshooting


System Abend Codes

Many software failures are detected by z/OS and its components. These conditions are normally reported as system abends using a code consisting of the letter S identifying a system abend and three hexadecimal digits, for example, S0C4. Complete descriptions of these conditions can found in the IBM publications for your specific version of z/OS. If a system abend is reported for Mainframe Access, it is important to review the abend description. This will help you to make an initial determination as to whether this is most likely a Mainframe Access program failure or a failure caused by other system conditions that have affected the execution of Mainframe Access.

Parent topic: Abend Codes


Mainframe Access User Abend Codes

When Mainframe Access detects a condition that prevents the program from continuing, it requests z/OS to begin abend processing for a user abend. Many of these conditions are detected by Mainframe Access initialization or by the item library format utility. z/OS reports user abends using a code consisting of the letter U identifying a user abend and four decimal digits, for example, U2111. The user abend codes that can be issued by Mainframe Access and recommended actions are listed in the following table.

User Abend Code | Description of Cause | Recommended Action
99 | Issued when a Data Set Services ISPI module cannot determine the invocation reason. | Contact our Product Support.
801 | Processing to establish or remove a Mainframe Access ESTAEX error recovery routine has failed. | Contact our Product Support.
996 | The MFA Server DSS Services component failed to initialize properly. This is a should not occur condition. | Contact our Product Support.
997 | An Endevor error has occurred in the application server address space. Common causes include a general setup failure, MSGLOG allocation failure, or the Endevor C1DEFLTS module could not be found. Endevor requests cannot be processed. | Examine the joblog and syslog for system messages and server messages that can help identify the specific error. Contact our Product Support if you are unable to resolve the problem
998 | There is a difference between the Endevor support modules available to the MFA Server control region and the Endevor support modules available in the MFA Server application server region(s). Different versions of Endevor are being referenced by the regions. Endevor requests cannot be processed. | This is most likely caused by differences in the STEPLIB or JOBLIB concatenations in the JCL used to start the regions. Contact our Product Support if you are unable to resolve the problem.
999 | This abend code indicates that the Endevor support modules are not available to MFA Server. Endevor requests cannot be processed. | The Endevor AUTHLIB and CONLIB data sets must be included in the MFA started task JCL (for both the control region and the application server regions) or these data sets must be available in the standard system LNKLST specifications. Contact our Product Support if you are unable to resolve the problem.
2100 | Processing to establish or remove a Mainframe Access ESTAEX error recovery routine has failed. | Contact our Product Support.
3100 | Processing associated with Mainframe Access' dependent addresss space services has encountered a should not occur condition. | Contact our Product Support.
3101 | Work order allocation for a dependent address space service has failed. This is a should not occur condition. | Contact our Product Support.
3102 | Allocation for a dependent address space service program call block has failed. This is a should not occur condition. | Contact our Product Support.
3103 | Work order queuing for a dependent address space service has failed. This is a should not occur condition. | Contact our Product Support.
Parent topic: Abend Codes


LU6.2 Diagnostic Information

Mainframe Access uses IBM's VTAM APPCCMD interface for LU6.2 communication with many of the target server systems, such as CICS, IMS and DB2. When problems arise and an error is reported for LU6.2 communication with one of these systems, the exact conditions of the error are indicated to Mainframe Access as return values from the APPCCMD call. These return values are logged to Mainframe Access' XDBOUT SYSOUT data set and can help you to identify and correct the situation. The following tables summarize the return value information. If you need more information, see the z/OS Communications Server SNA Programmer's LU 6.2 Reference manual for your level of z/OS and VTAM.

  • RTNCD and FDB2 Return Values for LU6.2 APPCCMD Calls
  • RCPRI and RCSEC Return Values for LU6.2 APPCCMD Calls
Parent topic: Troubleshooting


RTNCD and FDB2 Return Values for LU6.2 APPCCMD Calls

The RTNCD (return code) and FDB2 (feedback two) values are the major return values associated with an APPCCMD call. The following table summarizes these major return values.

RTNCD | FDB2 | Explanation
X'00' | X'0B' | An error occurred during the execution of the APPCCMD call. The specific nature of the error is indicated by secondary return values, RCPRI and RCSEC, as documented in the next section
X'04' | X'05' | Symbolic name known by network-qualified name only
X'10' | X'13' | Attempt to start 6.2 session: request rejected
X'10' | X'14' | Attempt to start 6.2 session: pending session terminated
X'10' | X'15' | An APPCCMD must be issued
X'14' | X'7F' | Policing error: non-APPC macro
Parent topic: LU6.2 Diagnostic Information


RCPRI and RCSEC Return Values for LU6.2 APPCCMD Calls

The RPL extension contains two fields in which return code information is passed to the application program at the completion of an LU6.2 APPCCMD macroinstruction execution. The RCPRI field returns a primary return code to the application; the RCSEC field returns a secondary return code to the application.

RCPRI | RCSEC | Explanation
X'0000' | X'0000' | OK; no errors
X'0000' | X'0001' | As specified; CNOS values were accepted
X'0000' | X'0002' | As negotiated; CNOS values changed by negotiation
X'0000' | X'0003' | Receive specific rejected
X'0000' | X'0004' | Partner LU supports single session
X'0000' | X'0005' | Internal VTAM error
X'0000' | X'0006' | Restore unnecessary; no modes to restore
X'0000' | X'0007' | Restore complete; input work area too small
X'0000' | X'0008' | No immediately available information
X'0000' | X'0009' | Request terminated by end of conversation
X'0000' | X'000A' | Sessions will use appl name, generic name requested
X'0000' | X'000B' | Sessions will use generic name, appl name requested
X'0000' | X'000C' | As specified, partner LU known by different name
X'0000' | X'000D' | As negotiated, partner LU known by different name
X'0004' | ALL | Allocation error
X'0004' | X'0000' | Allocation failure no retry
X'0004' | X'0001' | Allocation failure retry
X'0004' | X'0002' | Conversation type mismatch
X'0004' | X'0003' | PIP not allowed
X'0004' | X'0004' | PIP not specified correctly
X'0004' | X'0005' | Security not valid
X'0004' | X'0006' | Sync level not supported by LU
X'0004' | X'0007' | Sync level not supported by program
X'0004' | X'0008' | Transaction program name (TPN) not recognized
X'0004' | X'0009' | Transaction program name (TPN) not available; no retry
X'0004' | X'000A' | Transaction program name (TPN) not available; retry
X'0004' | X'000B' | Cannot reconnect transaction program; no retry
X'0004' | X'000C' | Cannot reconnect transaction program; retry
X'0004' | X'000D' | Reconnect not supported by program
X'0004' | X'000E' | Mode must be restored before using
X'0004' | X'000F' | Deallocation requested
X'0004' | X'0010' | Allocation error - sync level not valid for full duplex
X'0004' | X'0011' | Allocation error - LU pair not supporting FDX conversation
X'0008' | ALL | CNOS failure
X'0008' | X'0000' | Allocation failure; retry
X'0008' | X'0001' | Allocation failure; no retry
X'0008' | X'0002' | Transaction program not available; retry
X'0008' | X'0003' | Transaction program not available; no retry
X'0008' | X'0004' | Conversation type mismatch
X'0008' | X'0005' | Security not valid
X'0008' | X'0006' | Mode must be restored before using
X'0008' | X'0007' | Network qualified name mismatch
X'000C' | X'0000' | CNOS resource failure; no retry
X'0010' | X'0000' | Partner granted retry
X'0010' | X'0001' | Control operator for local LU retried
X'0010' | X'0002' | Partner CNOS in progress
X'0010' | X'0003' | LU in pending single state
X'0010' | X'0004' | Partner LU starting session
X'0014' | X'0000' | Deallocate abend program
X'0018' | X'0000' | Deallocate abend service
X'001C' | X'0000' | Deallocate abend timer
X'0020' | X'0000' | CNOS failure; retry
X'0024' | X'0000' | Logical record boundary error
X'0028' | X'0000' | LU mode session limit closed
X'002C' | ALL | Parameter error
X'002C' | X'0000' | Invalid LU name or network identifier
X'002C' | X'0001' | Invalid mode
X'002C' | X'0002' | Invalid conversation
X'002C' | X'0003' | Invalid LL
X'002C' | X'0004' | Invalid values for SNASVCMG mode
X'002C' | X'0005' | Invalid DRAINL change
X'002C' | X'0006' | SNASVCMG mode cannot currently be reset
X'002C' | X'0007' | MINWINL plus MINWINR exceeds SESSLIM
X'002C' | X'0008' | Supplied length insufficient
X'002C' | X'0009' | Incomplete structure supplied
X'002C' | X'000A' | Incomplete FMH5 supplied
X'002C' | X'000B' | Incomplete GDS variable supplied
X'002C' | X'000C' | Zero EXIT field
X'002C' | X'000D' | Zero ECB field
X'002C' | X'000E' | Request invalid for address space
X'002C' | X'000F' | Control block invalid
X'002C' | X'0010' | Invalid data address or length
X'002C' | X'0011' | Previous macroinstruction outstanding
X'002C' | X'0012' | Buffer list length invalid
X'002C' | X'0013' | No corresponding mode in LM table
X'002C' | X'0014' | Invalid BIND parameters
X'002C' | X'0015' | Invalid TPN
X'002C' | X'0016' | No corresponding LU in LM table
X'002C' | X'0017' | Invalid mode specified
X'002C' | X'0018' | Invalid limit specified
X'002C' | X'0019' | SNASVCMG mode already initialized
X'002C' | X'001A' | All modes specified on single session LU
X'002C' | X'001B' | SNASVCMG or CPSVCMG mode for single session LU
X'002C' | X'001C' | Single session, mode already initialized
X'002C' | X'001E' | CID invalid
X'002C' | X'001F' | APPCCMD issued for non-APPC
X'002C' | X'0020' | Previous REJECT request outstanding
X'002C' | X'0021' | Abnormal deallocate rejected; retry
X'002C' | X'0022' | Invalid CONTROL or QUALIFY value
X'002C' | X'0023' | Invalid session instance identifier
X'002C' | X'0024' | PS header not supplied
X'002C' | X'0025' | PS header length is insufficient
X'002C' | X'0026' | Session instance identifier and conversation identifier mismatch
X'002C' | X'0027' | Invalid deactivation type code
X'002C' | X'0028' | Cryptography not allowed on mode
X'002C' | X'0029' | Invalid LIST value specified on APPCCMD for restore
X'002C' | X'002A' | Invalid CGID value specified
X'002C' | X'002B' | Network-qualified name required
X'002C' | X'002C' | Parameter error; invalid expedited data length
X'002C' | X'002D' | Parameter error; invalid sense code value specified
X'002C' | X'002E' | Vector area not valid
X'002C' | X'002F' | Vector area length insufficient
X'002C' | X'0030' | Parameter error; storage type not valid
X'002C' | X'0031' | Parameter error; SENDRCV specified with OPTCD=BUFFLST/XBUFLST
X'002C' | X'0032' | Parameter error; unexpected vector provided on APPCCMD
X'002C' | X'0033' | Parameter error; required vector not provided or incorrect
X'002C' | X'0034' | Password substitution value set in error
X'0030' | X'0000' | Program error; no truncation
X'0034' | X'0000' | Program error purging
X'0038' | X'0000' | Program error truncating
X'003C' | X'0000' | Service error; no truncation
X'0040' | X'0000' | Service error purging
X'0044' | X'0000' | Service error truncating
X'0048' | X'0000' | Resource failure; no retry
X'004C' | X'0000' | Resource failure; retry
X'0050' | X'0000' | State error
X'0054' | X'0000' | Unrecognized mode name
X'0058' | X'0000' | Unsuccessful; session not available
X'005C' | ALL | User error code received
X'005C' | X'0000' | Following negative response
X'005C' | X'0001' | Without negative response
X'0060' | X'0000' | No FMH5 available
X'0064' | X'0000' | Activation failure
X'0068' | X'0000' | LU mode session limit exceeded
X'006C' | X'0000' | Session not pending
X'0070' | X'0000' | Temporary storage shortage or resource shortage
X'0074' | X'0000' | Halt issued
X'0078' | X'0000' | VTAM inactive for your ACB
X'007C' | X'0000' | Request aborted
X'0080' | X'0000' | Deallocate normal
X'0084' | X'0000' | Storage shortage
X'0088' | X'0000' | Canceled by reject or abnormal deallocate
X'008C' | X'0000' | Partner committed protocol violation
X'0090' | X'0000' | Application not APPC capable
X'0094' | X'0000' | Invalid condition for sending data
X'0098' | X'0000' | Temporary storage shortage while sending data
X'009C' | X'0000' | Restore rejected - restore issued before SETLOGON start
X'00A0' | ALL | Request not allowed
X'00A0' | X'0001' | LU pair does not support sending expedited data
X'00A0' | X'0002' | Request blocked
X'00A0' | X'0003' | Execution of request terminated
X'00A0' | X'0004' | CONTROL/QUALIFY value invalid for full-duplex conversation
X'00A0' | X'0005' | Response has not been received for a previous SENDEXPD request
X'00A0' | X'0006' | Program not authorized for requested function
X'00A4' | X'0000' | Mode must be restored before using
X'00A8' | ALL | Environment error
X'00A8' | X'0000' | OS level does not support request function
X'00A8' | X'0001' | Suspend failure
X'00A8' | X'0002' | Resume failure
X'00AC' | ALL | Error indication received
X'00AC' | X'0001' | Deallocate abend program
X'00AC' | X'0002' | Deallocate abend service
X'00AC' | X'0003' | Deallocate abend time
X'00AC' | X'0004' | Allocation error
X'00AC' | X'0005' | Unknown error code
X'00AC' | X'0006' | Resource failure; retry
X'00AC' | X'0007' | Resource failure; no retry
X'00B0' | ALL | Name resolution error
X'00B0' | X'0001' | LU name found in a variant name entry
X'00B0' | X'0002' | Name returned differs from associated name
X'00B0' | X'0003' | Name returned found in variant name entry
X'00B0' | X'0004' | Name returned found in supplied name entry
X'00B0' | X'0005' | Partner network name mismatch
X'00B0' | X'0006' | LU name found in an unusable name entry
X'00B0' | X'0007' | Name returned found in an unusable name entry
X'00B0' | X'0008' | LU name found in a disassociated name entry
X'00B4' | ALL | CSM detected error
X'00B4' | X'0001' | CSM detected error - not specified
X'00B4' | X'0002' | CSM detected error - invalid buffer token specified
X'00B4' | X'0003' | CSM detected error - invalid instance id specified
Parent topic: LU6.2 Diagnostic Information


Mainframe Access Host Error Codes

The return code and reason code values documented in the following table may appear in error responses sent from Mainframe Access to client products.

Return Code | Reason Code | Explanation | Action
X'00000008' | X'00000001' | XERROR_ALLOC The LU6.2 session allocation failed. | Check the target DB2 APPLID or MODNAME.
X'00000008 | X'00000002' | XERROR_ALLOC The LU6.2 session allocation failed without a conversation block. | Check the APPLID and MODNAME for the target DB2.
X'00000009' | X'00000001' | XERROR_INVALIDPACKET An invalid packet type; the correct packet is an allocation packet. | Check the client program.
X'00000009' | X'00000002' | XERROR_INVALIDPACKET An invalid packet type; the correct packet is a dellocation data packet. | Contact our Product Support.
X'00000010' | X'FFFFFFFF' | XERROR_SEND The maximum number of concurrent users was reached. | Contact a Micro Focus sales representative to purchase more seats for your license.
X'00000011' | X'00000001' | XERROR_RECEIVE The LU6.2 session failed in the receive mode. | Contact our Product Support.
X'00000013' | X'00000001' | XERROR_FUNCTIONNOTALLOWED The IMS/VSAM access feature is not available at your site. | Contact a Micro Focus sales representative to purchase a license for this feature.
X'00000013' | X'00000002' | XERROR_FUNCTIONNOTALLOWED The PEM feature is not available at your site. | Contact a Micro Focus sales representative to purchase a license for this feature.
X'00000014' | X'00000001' | XERROR_INVALIDTRAN The transaction type in the first packet is invalid. | Contact our Product Support.
X'00000015' | X'00000001' | XERROR_CONV The LU6.2 session lost the conversation control block. | Contact our Product Support.
X'00000017' | X'00000rpl' | XERROR_SENDRPL The LU6.2 session failed with the RPL code in the reason code block. | Contact our Product Support.
X'00000018' | X'00000rpl' | XERROR_RECEIVERPL The LU6.2 session failed in receive mode with the RPL code in the reason code block. | Contact our Product Support.
X'00000100' | X'00000100' | XERROR_INTERNAL Unknown request type. | Contact our Product Support.
Parent topic: Troubleshooting


Mainframe Access Remote IMS Error Codes

Return Code | Reason Code | Description of Cause | Action
400 | Bad request type | TYPE=ALLOCERR: Request type is invalid | The first packet's request type must be ALLOC. Resubmit an ALLOC packet.
400 | Bad request, ID block is missing | TYPE=ALLOCERR: Mainframe Access does not have the configuration for the IMSID | Check the IMSID and resubmit.
505 | Version not supported | TYPE=ALLOCERR: The client is not supported by Mainframe Access | Contact our Product Support.
602 | IMS Applid is not valid | TYPE=ALLOCERR: Either IMS is not available or IMS/APPC is not enabled. | Contact our Product Support.
604 | IMS Alloc Failure, RC = rc | TYPE=ALLOCERR: Routine failed to initiate a conversation with the target IMS system. rc is the decimal number of the return code from VTAM. | Contact our Product Support.
606 | Receive Error | TYPE=RPL,CODE=rc: Conversation to IMS has failed during a receive operation with RPL code. rc is the return code. The first two bytes are the RPL primary code; the next two bytes are the RPL secondary code. | Check the entries, correct any errors, and resubmit request.
606 | Send Error | TYPE=RPL,CODE=rc: Conversation to IMS has failed during a send operation with RPL code. The first two bytes are the RPL primary code; the next two bytes are the RPL secondary code. | Check the entries, correct any errors, and resubmit request.
606 | LU6.2 Error | TYPE=RPL,CODE=rc: Conversation to IMS has failed with RPL code. The first two bytes are the RPL primary code; the next two bytes are the RPL secondary code. | Check the entries, correct any errors, and resubmit request.
613 | Userid/Password Required | TYPE=ALLOCERR: Security is enforced in the configuration and user ID or password in the request packet is missing. | Check and correct user ID and password and resubmit request packet.
699 | Mainframe Access HTTP Parsing Error | TYPE=ALLOCERR: The input HTTP packet has invalid record or format. | Check the record or format of the HTTP packet and resubmit.
Parent topic: Troubleshooting


IBM SAF and RACF Error Codes

The return code and reason code values documented in the following table may appear in error messages associated with z/OS security subsystem request failures.

  • Error Codes for VERIFY Requests
  • Error Codes for AUTH Requests
Parent topic: Troubleshooting


Error Codes for VERIFY Requests

The return code and reason code values documented in the following table are associated with RACROUTE REQUEST=VERIFY requests that are issued to authenticate a user based on the userid and password that were submitted.

SAF Return Code | RACF Return Code | RACF Reason Code | Description
X'00' | X'00' | X'0000' | Request completed successfully.
X'00' | X'04' | X'000C' | Request completed successfully. TOKNIN was specified but the length was too large.
X'00' | X'04' | X'0010' | Request completed successfully. STOKEN was specified but the length was too large.
X'04' | X'00' | X'0000' | Request could not be completed. No RACF decision was possible. ENVIR=VERIFY was specified without SAF installation exit processing.
X'04' | X'04' | X'0000' | Request could not be completed. No RACF decision was possible. The user profile is not defined to RACF.
X'04' | X'20' | X'0000' | Request could not be completed. No RACF decision was possible. RACF is not active.
X'04' | X'58' | X'0000' | Request could not be completed. No RACF decision was possible. RJE or NJE operator FACILITY class profile not found.
X'08' | X'04' | X'0000' | Request failed. The user profile is not defined to RACF.
X'08' | X'08' | X'0000' | Request failed. The password is not authorized.
X'08' | X'0C' | X'0000' | Request failed. The password has expired.
X'08' | X'10' | X'0000' | Request failed. The new password is not valid.
X'08' | X'14' | X'0000' | Request failed. The user is not defined to the group.
X'08' | X'18' | X'0000' | Request failed. RACROUTE REQUEST=VERIFY was failed by the installation exit routine.
X'08' | X'1C' | X'0000' | Request failed. The user's access has been revoked.
X'08' | X'24' | X'0000' | Request failed. The user's access to the specified group has been revoked.
X'08' | X'28' | X'0000' | Request failed. OIDCARD parameter is required but not supplied.
X'08' | X'2C' | X'0000' | Request failed. OIDCARD parameter is not valid for specified user.
X'08' | X'30' | X'0000' | Request failed. The user is not authorized to the port of entry in the TERMINAL, JESINPUT, or CONSOLE class. Indicates the user is not authorized to the port of entry.
X'08' | X'30' | X'0004' | Request failed. The user is not authorized to the port of entry in the TERMINAL, JESINPUT, or CONSOLE class. Indicates the user is not authorized to access the system on this day, or at this time of day.
X'08' | X'30' | X'0008' | Request failed. The user is not authorized to the port of entry in the TERMINAL, JESINPUT, or CONSOLE class. Indicates the port of entry may not be used on this day, or at this time of day.
X'08' | X'34' | X'0000' | Request failed. The user is not authorized to use the application.
X'08' | X'38' | X'0004' | Request failed. SECLABEL checking failed. MLACTIVE requires a SECLABEL; none was specified.
X'08' | X'38' | X'0008' | Request failed. SECLABEL checking failed. Indicates the user is not authorized to the SECLABEL.
X'08' | X'38' | X'000C' | Request failed. SECLABEL checking failed. The system was in a multilevel secure status, and the dominance check failed.
X'08' | X'38' | X'0010' | Request failed. SECLABEL checking failed. Neither the user's nor the submitter's SECLABELs dominate. They are disjoint.
X'08' | X'44' | X'0000' | Request failed. A default token is used as input token.
X'08' | X'48' | X'0000' | Request failed. Indicates that an unprivileged user issued a RACROUTE REQUEST=VERIFY in a tranquil state (MLQUIET).
X'08' | X'4C' | X'0000' | Request failed. NODES checking failed. Submitter's node is not allowed access to execution node.
X'08' | X'4C' | X'0004' | Request failed. NODES checking failed. NJE failure: UACC of NONE for USERID type of NODES profile.
X'08' | X'4C' | X'0008' | Request failed. NODES checking failed. NJE failure: UACC of NONE for GROUP type of NODES profile.
X'08' | X'4C' | X'000C' | Request failed. NODES checking failed. NJE failure: UACC of NONE for SECLABEL type of NODES profile.
X'08' | X'4C' | X'0010' | Request failed. NODES checking failed. NJE failure: No local submit node specified.
X'08' | X'4C' | X'0014' | Request failed. NODES checking failed. NJE failure: Reverification of translated values failed.
X'08' | X'50' | X'0004' | Request failed. Indicates that a surrogate submit attempt failed. Indicates the SURROGAT class was inactive.
X'08' | X'50' | X'0008' | Request failed. Indicates that a surrogate submit attempt failed. Indicates the submitter is not permitted by the user's SURROGAT class profile.
X'08' | X'50' | X'000C' | Request failed. Indicates that a surrogate submit attempt failed. Indicates that the submitter is not authorized to the SECLABEL under which the job is to run.
X'08' | X'54' | X'0000' | Request failed. Indicates that a JESJOBS check failed.
X'08' | X'64' | X'0000' | Request failed. Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=VERIFY macro; however, the list form of the macro does not have the same release parameter. Macro processing terminates.
Parent topic: IBM SAF and RACF Error Codes


Error Codes for AUTH Requests

The return code and reason code values documented in the following table are associated with RACROUTE REQUEST=AUTH requests. AUTH requests are issued to check the authorization of an already verified user to access a protected resource. The most common use of AUTH is to check if a user is authorized to access a specific data set.

SAF Return Code RACF Return Code RACF Reason Code Description
X'00' X'00' X'0000' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource.

X'00' X'00' X'0004' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. Indicates one of the following:

  • STATUS=ERASE was specified and the data set is to be erased when scratched
  • the warning status of the resource was requested by the RACROUTE REQUEST=AUTH issuer's setting bit X'10' at offset 12 decimal in the request-specific portion of the RACROUTE REQUEST=AUTH parameter list with the resource in warning mode.
X'00' X'00' X'0010' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. When CLASS=TAPEVOL, indicates the TAPEVOL profile contains a TVTOC.

X'00' X'00' X'0020' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. When CLASS=TAPEVOL, indicates that the TAPEVOL profile can contain a TVTOC, but currently does not (for a scratch pool volume).

X'00' X'00' X'0024' Request completed successfully.

The user is authorized by RACF to obtain use of a RACF-protected resource. When CLASS=TAPEVOL, indicates that the TAPEVOL profile does not contain a TVTOC.

X'00' X'14' X'00XX' Request completed successfully.

Requested function with STATUS=ACCESS specified has completed successfully. The user's highest access to the specified resource is indicated by one of the following reason codes:

  • 00

    The user has no access.

  • 04

    The user has READ authority.

  • 08

    The user has UPDATE authority.

  • 0C

    The user has CONTROL authority.

  • 10

    The user has ALTER authority.

X'04' X'00' X'0000' Request could not be completed.

No RACF decision was possible. No security decision could be made. RACF is not installed -or- the specified requester, subsystem, or class is not in the RACF router table -or- the specified class is not in the RACF class descriptor table.

X'04' X'04' X'0000' Request could not be completed. No RACF decision was possible.

The specified resource is not protected by RACF.

Note: Note:

If PROTECTALL is active, no profile is found, and the user ID whose authority was checked does not have the SPECIAL attribute, RACF returns a return code X'08' instead of a return code X'04' and denies access.

One of the following has occurred:

  • There is no RACF profile protecting the resource
  • RACF is not active
  • Specified class is not active
  • Specified class requires SETROPTS RACLIST option to be active and it is not.
  • CLASS TEMPDSN was active and the dataset is a temporary dataset.
X'04' X'04' X'0004' Request could not be completed.

No RACF decision was possible. The specified resource is not protected by RACF.

Indicates STATUS=ERASE was specified and the data set is to be erased when scratched.

X'08' X'08' X'0000' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates a normal completion. A possible cause would be PROTECTALL is active, no profile is found, and the user ID whose authority was checked does not have the SPECIAL attribute.

X'08' X'08' X'0004' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates STATUS=ERASE was specified and the data set is to be erased when scratched.

X'08' X'08' X'0008' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates DSTYPE=T or CLASS=TAPEVOL was specified and the user is not authorized to use the specified volume.

X'08' X'08' X'000C' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates the user is not authorized to use the data set.

X'08' X'08' X'0010' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates DSTYPE=T or CLASS=TAPEVOL was specified and the user is not authorized to specify TAPELBL=(,BLP).

X'08' X'08' X'0014' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates the user is not authorized to open a non-cataloged data set.

X'08' X'08' X'0018' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

Indicates the user is not authorized to issue RACROUTE REQUEST=AUTH when system is in tranquil state (MLQUIET).

X'08' X'08' X'001C' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

A user with EXECUTE authority to the data set profile specified ATTR=READ, and RACF failed the access attempt.

X'08' X'08' X'0020' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

The user's security label does not dominate that of the resource; it fails SECLABEL authorization checking.

X'08' X'08' X'0024' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

The user's security label can never dominate that of the resource.

X'08' X'08' X'0028' Request failed. The user is not authorized by RACF to obtain use of the specified RACF-protected resource.

The resource must have a security label, but does not have one.

X'08' X'0C' X'0000' Request failed.

The OLDVOL specified was not part of the multivolume data set defined by VOLSER, or it was not part of the same tape volume defined by ENTITY.

X'08' X'10' X'00XX' Request failed.

RACROUTE REQUEST=VERIFY was issued by a third party, and RACROUTE REQUEST=AUTH failed. The reason code 00XX value is the RACF return code from the RACROUTE REQUEST=VERIFY.

X'08' X'64' X'0000' Request failed.

Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=AUTH macro; however, the list form of the macro does not have the same RELEASE parameter. Macro processing terminates.

Parent topic: IBM SAF and RACF Error Codes


Mainframe Access Audit Report Program

Mainframe Access' optional audit log feature records client logon and logoff information to a VSAM data set. For a description of how to allocate the audit log data set and enable the recording see the section Allocating and Initializing an Audit Log Data Set in the chapter Configuration. Mainframe Access also provides a batch reporting program to list the audit log records. This section describes the use of the audit log report program.

  • Running the Audit Report Program
  • Audit Report Abend Codes
  • Audit Report Diagnostic Messages
Parent topic: Troubleshooting
Related information
Allocating and Initializing an Audit Log Data Set


Running the Audit Report Program

Member AUDRPT in the Mainframe Access <hlq>.CNTL data set is a sample job for running the audit report program. Customize this job with a valid JOB card and the correct data set qualifier for your installation. The sample member is shown below.

//MFASETUP JOB (MFA),'RUN AUDIT REPORT',CLASS=A,MSGCLASS=A
//*
//AUDITRPT PROC DSNQUAL='HLQ'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - Run the Audit Log Report          *
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*------------------------------------------------------------------*
//*
//*------------------------------------------------------------------*
//* Step 1: Run the audit report utility to list the records in the  *
//*         audit log dataset.                                       *
//*------------------------------------------------------------------*
//*
//AUDITRPT EXEC PGM=AUDITRPT,REGION=0M
//STEPLIB  DD   DSN=&.DSNQUAL..LOADLIB,DISP=SHR
//AUDITIN  DD   DSN=&.DSNQUAL..AUDIT,DISP=SHR
//SYSPRINT DD   SYSOUT=*
//SYSTERM  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//         PEND
//AUDITRPT EXEC AUDITRPT

When you have customized the job, submit it for execution. A report similar to the following is written to a SYSOUT data set.

                                                            Audit Log Report

  Report date and time: FRI JUL 25 16:37:57 2003

  Audit data set: <hlq>.AUDIT

  Type     Record    Sess  User      IP Address       Partner    Date+Time                Type of
  of       Sequence  ID    ID                         LU                                  Encryption used (see note)
  Record

  Logoff        1    00000 CSIRLW2   10.24.11.15      MFADIR     FRI JUL 25 16:02:51 2003
  Logoff        3    00000 CSIRLW1   10.24.11.15      MFADIR     FRI JUL 25 16:03:33 2003
  Logoff        5    00000                                       FRI JUL 25 16:04:22 2003 N
  Logoff       10    00000                                       FRI JUL 25 16:35:48 2003 N
  Logon         0    00001 CSIRLW2   10.24.11.15      MFADIR     FRI JUL 25 16:02:27 2003
  Logon         2    00002 CSIRLW1   10.24.11.15      MFADIR     FRI JUL 25 16:03:20 2003
  Logon         4    00003 CSIRLW1   10.24.11.15      LUDB27R    FRI JUL 25 16:03:59 2003 P
  Logon         6    00004           10.24.11.15      CICSTSR7   FRI JUL 25 16:34:32 2003 N
  Logon         7    00005           10.24.11.15      CICSTSR6   FRI JUL 25 16:34:33 2003 N
  Logon         8    00006           10.24.11.15      CICSTSR3   FRI JUL 25 16:34:34 2003 N
  Logon         9    00007 CSIRLW1   10.24.11.15      IMS6PPC    FRI JUL 25 16:35:42 2003 N

  Note: Encryption values   N = None, P = Password, X = Packet encryption, C = Compression is in use

  Total type 0 records =         11
  Total logon records  =          7
  Total logoff records =          4
Parent topic: Mainframe Access Audit Report Program


Audit Report Abend Codes

The following table lists the user abends that may be issued by the audit report program.

User Abend Code | Description of Cause | Recommended Action
1211 | This abend is issued when a GETMAIN request fails. A console message is also issued to indicate the failure condition. A program dump is not requested. | Increase the region size for the audit report program. If the problem persists contact our Product Support.
Parent topic: Mainframe Access Audit Report Program


Audit Report Diagnostic Messages

The following messages may be issued by the audit report program when error conditions occur.

AUD0001E: DDNAME xxxxxxxx WAS NOT FOUND

This message appears when either the SYSPRINT or AUDITIN DD statements are missing. Add the missing DD statements to the JCL for the job.

AUD0002E: OPEN FAILED FOR xxxxxxxx FILE

This message appears when either SYSPRINT or AUDITIN fails to open. Examine associated system error messages to determine the reason for the failure.

AUD0003E: VSAM ACB FAILED FOR xxxxxxxx
AUD0003E: RETURN CODE IS xxxxxxxx
AUD0003E: REASON CODE IS xxxxxxxx

These messages appear when a critical error occurs while accessing the AUDITIN VSAM data set. The program terminates with the return code 16. Examine any associated system error messages and the VSAM return code and reason code values to determine the reason for the failure.

Parent topic: Mainframe Access Audit Report Program


Obtaining a VTAM Buffer Trace

During the process of resolving a problem, our Product Support may require you to obtain and submit a VTAM buffer trace (and possibly other VTAM trace data). This section describes how to use IBM's Generalized Trace Facility (GTF) to capture the relevant data.

The procedure for gathering the trace is as follows:

  1. Make sure that Mainframe Access, the clients and the target servers are all ready and at a point where you want to start tracing. For example, if the problem is associated with a specific CICS distributed transaction, bring the client up to the point where the transaction will be issued.
  2. Start GTF (see the section Starting GTF)
  3. Activate the VTAM trace (see the section Activating the VTAM Trace)
  4. Perform the activity that you want to trace (for example, run the transaction that fails)
  5. Deactivate the VTAM trace (see the section Deactivating the VTAM Trace)
  6. Stop GTF (see the section Stopping GTF)
  7. Package the raw GTF trace data set for transmission to our Product Support.
  8. Use the File Transfer Protocol (FTP) utility to send the packaged trace to Micro Focus. Use binary mode for the transfer.
  • Starting GTF
  • Activating the VTAM Trace
  • Deactivating the VTAM Trace
  • Stopping GTF
  • Formatting VTAM GTF Trace Records
  • Obtaining an SVC Dump of Mainframe Access
  • Packaging and Transmitting Diagnostic Data
Parent topic: Troubleshooting
Related information
Starting GTF
Activating the VTAM Trace
Deactivating the VTAM Trace
Stopping GTF


Starting GTF

Mainframe Access provides a sample procedure, MFAGTF, for running GTF; its use is described in the section Adding the GTF Procedure to a System Procedure Library in the chapter Configuration. You may want to pre-allocate a permanent GTF trace data set on DASD that can be reused each time you start MFAGTF. If you do so, update the MFAGTF procedure to use this data set.

A PDS member is normally used to automate the specification of GTF options when GTF is started and the sample procedure uses parameters from another sample member, GTFCNTL. This sample is set up to start GTF for recording Mainframe Access' activity trace (USR '0E9' records) and VTAM's buffer trace (USR 'FEF' and 'FF1' records).

A sample system log for the startup of GTF is shown below. Remember to have Mainframe Access and other software components that are part of the tracing activity already running, connected and ready to go, if possible.

  S MFAGTF.MYGTF
  $HASP100 MFAGTF   ON STCINRDR
  IEF695I START MFAGTF WITH JOBNAME MFAGTF IS ASSIGNED TO USER RWITEK, GROUP CSIDVLP
  $HASP373 MFAGTF   STARTED
  IEF403I MFAGTF - STARTED - TIME=16.34.12
  AHL121I  TRACE OPTION INPUT INDICATED FROM MEMBER GTFCNTL  OF PDS
  <hlq>.CNTL
  TRACE=USRP
  USR=(FF1,FEF,0E9)
  END
  AHL103I  TRACE OPTIONS SELECTED --USR=(FEF,FF1,0E9)
  AHL906I THE OUTPUT BLOCK SIZE OF    27998 WILL BE USED FOR OUTPUT 997
          DATA SETS:
            <hlq>.TRACE
  AHL080I GTF STORAGE USED FOR GTF DATA: 998
          GTFBLOCK STORAGE       82K BYTES (BLOK=        40K)
          PRIVATE STORAGE      1038K BYTES
          SADMP HISTORY          54K BYTES (SADMP=       40K)
          SDUMP HISTORY          54K BYTES (SDUMP=       40K)
          ABEND DUMP DATA         0K BYTES (ABDUMP=       0K)
  AHL031I GTF INITIALIZATION COMPLETE

GTF is now up and running and ready to record type 'FEF' and 'FF1' records from VTAM. z/OS may also force some USR records into the trace data set for system components. GTF wraps trace data when writing trace records to a DASD data set. This means that you can leave GTF tracing on for a long time to catch an intermittent problem, then stop the trace soon after the problem occurs. However, if you do not stop the trace soon after the problem occurs, the trace data that you collected may be overwritten by trace data from other system components.

Parent topic: Obtaining a VTAM Buffer Trace
Related information
Adding the GTF Procedure to a System Procedure Library


Activating the VTAM Trace

When you are ready to perform an action that you want to trace, activate the VTAM buffer trace for the Mainframe Access ACB. You do this using a z/OS Modify command to VTAM. In this example the VTAM JCL procedure name is VTAM. The name may be different on your z/OS system. The only other thing you may want to change is the ID= parameter so that it specifies the name of your Mainframe Access VTAM ACB.

  F VTAM,TRACE,TYPE=BUF,ID=MFM62ACB,AMOUNT=FULL
  IST097I MODIFY ACCEPTED
  IST1515I BUFFER TRACE ACTIVE
  IST1144I TRACE INITIATED FOR DDINET1.MFM62ACB 316
  IST1045I NODE TYPE = APPL
  IST314I END

GTF should now be up and running and VTAM should be creating TYPE=BUF trace records for any activity associated with MFM62ACB. If someone has previously started a TYPE=BUF trace for another VTAM resource and did not bother to stop the trace, these records may also appear in the trace data set and complicate the analysis of what you are tracing.

Parent topic: Obtaining a VTAM Buffer Trace


Deactivating the VTAM Trace

When you have finished performing the activity to be traced, turn off the VTAM TYPE=BUF trace for the Mainframe Access ACB. Use the z/OS Modify command as follows:

  F VTAM,NOTRACE,TYPE=BUF,ID=MFM62ACB
  IST097I MODIFY ACCEPTED
  IST1143I TRACE TERMINATED FOR DDINET1.MFM62ACB 349
  IST1045I NODE TYPE = APPL
  IST314I END
Parent topic: Obtaining a VTAM Buffer Trace


Stopping GTF

Stop the GTF process using the z/OS Stop (P) command. In this example GTF was started using "S MFAGTF.MYGTF" where the .MYGTF is assigned as an identifier for the GTF process that is then specified in the Stop command.

  P MYGTF
  AHL006I GTF ACKNOWLEDGES STOP COMMAND
  AHL904I THE FOLLOWING TRACE DATASETS CONTAIN TRACE DATA : 353
            <hlq>.TRACE
  IEF404I MFAGTF - ENDED - TIME=11.48.15
  $HASP395 MFAGTF   ENDED
  $HASP250 MFAGTF PURGED -- (JOB KEY WAS B5A444E4)

The trace data set, <hlq>.TRACE in this example, now has the raw GTF data.

Parent topic: Obtaining a VTAM Buffer Trace


Formatting VTAM GTF Trace Records

There may be times when you need, or want, to examine the GTF trace data. In this case, the raw data collected by GTF needs to be processed by a formatting program such as IBM's Interactive Problem Control System (IPCS). You can run IPCS either using a TSO command under ISPF or as a batch job. To run IPCS you need an IPCS dump directory VSAM data set. If you do not already have a dump directory, you can allocate one using a job similar to the following.

//jobname JOB (accounting),'name',CLASS=?,MSGCLASS=?,NOTIFY=userid
//--------------------------------------------------------------------
//* Allocate an IPCS dump directory VSAM data set
//--------------------------------------------------------------------
//IDCAMS   EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
 DELETE <hlq>.DIR
 DEFINE CLUSTER (NAME(<hlq>.DIR)                -
                SHAREOPTIONS(1)                 -
                RECSZ(256 3072)                 -
                KEYS(128 0)                     -
                VOLUMES(volser)
          INDEX (NAME(<hlq>.DIRINDEX)           -
                TRK(15 5))                      -
          DATA  (NAME(<hlq>.DIRDATA)            -
                CYLINDERS(5 1)                  -
                CISZ(X'1000'))

This example JCL runs IPCS to print all 'FEF' and 'FF1' records from the GTF trace data set.

//jobname JOB (accounting),'name',CLASS=?,MSGCLASS=?,NOTIFY=userid
//--------------------------------------------------------------------
//* Run IPCS batch to print GTF trace records
//--------------------------------------------------------------------
//IPCSBAT  EXEC PGM=IKJEFT01,DYNAMNBR=20,REGION=0M
//IPCSDDIR DD DSN=<hlq>.DIR,DISP=SHR
//IPCSPRNT DD SYSOUT=*
//TRACE    DD DSN=<hlq>.TRACE,DISP=SHR
//SYSTSPRT DD SYSOUT=*
//SYSTSIN  DD *
 IPCS NOPARM
 DROPDUMP DDNAME(TRACE)
 SETDEF DDNAME(TRACE) NOCONFIRM
 GTFTRACE DDNAME(TRACE),USR(FEF,FF1),TERMINAL,NOPRINT
 END
Parent topic: Obtaining a VTAM Buffer Trace


Obtaining an SVC Dump of Mainframe Access

During the process of resolving a problem, our Product Support may require you to obtain and submit a dump of the Mainframe Access address space. This section describes how to use IBM's DUMP command to create the dump data set. Using the following procedure, you can obtain a dump without stopping or canceling the Mainframe Access address space.

The procedure for creating the dump is as follows:

  1. Issue the DUMP command
  2. Respond to the DUMP command options request
  3. Package the dump data set for transmission to our Product Support
  4. Use the File Transfer Protocol (FTP) utility to send the packaged dump to Micro Focus. Use binary mode for the transfer.

The following example shows a DUMP command and the response to the request for operands in bold face. You use the COMM parameter of the DUMP command to specify a meaningful title for the dump. The operands specified in the sample reply, SDATA=(RGN,LSQA,PSA,SUM,SWA,TRT,CSA,LPA), are normally needed for any Mainframe Access dump; you should specify them as shown. Technical support may request additional, or different, options for a specific problem. After the options have been entered it will take the system anywhere from a few seconds to a few minutes to complete the dump. The IEA611I COMPLETE DUMP message indicates successful completion of the command and it identifies the dump data set that needs to be saved and packaged up for transmission. In this example, the system has created data set SYS1.CSIA.DMP00032 to contain the dump data.

  DUMP COMM=(MFA DUMP JULY 28 2003)
  *63 IEE094D SPECIFY OPERAND(S) FOR DUMP COMMAND
  R 63,JOBNAME=MFA,SDATA=(RGN,LSQA,PSA,SUM,SWA,TRT,CSA,LPA)
   IEE600I REPLY TO 63 IS;JOBNAME=MFA,SDATA=(RGN,LSQA,PSA,SUM,SWA,TRT
   IEA794I SVC DUMP HAS CAPTURED: 138
   DUMPID=032 REQUESTED BY JOB (*MASTER*)
   DUMP TITLE=MFA DUMP JULY 28 2003
   IEF196I IGD100I 0309 ALLOCATED TO DDNAME SYS00036 DATACLAS (        )
   IEF196I IEF285I   SYS1.CSIA.DMP00032                           CATALOGED
   IEF196I IEF285I   VOL SER NOS= DUMP01.
   IEA611I COMPLETE DUMP ON SYS1.CSIA.DMP00032 142
   DUMPID=032 REQUESTED BY JOB (*MASTER*)
   FOR ASID (00A5)
   INCIDENT TOKEN: ROCKPLEX CSIA     07/28/2003 21:56:11
Parent topic: Obtaining a VTAM Buffer Trace


Packaging and Transmitting Diagnostic Data

This section provides suggestions and guidelines that will help if you need to send diagnostic data to our Product Support. When you need to send relatively small amounts of text data (for example, short Mainframe Access activity traces, parameter settings, excerpts from the system log, excerpts from a dump listing, etc.), it is often convenient to simply include the text in an email or as a text file attachment to an email. Large amounts of data and non-textual information should be packaged and transmitted as described in the following paragraphs.

After gathering large amounts of diagnostic data (for example, SVC dumps, GTF traces, Mainframe Access activity traces, system log contents, etc.), the most expedient way to send the information is using the TCP/IP File Transfer Protocol (FTP) utility. Before you send the data, it is good practice to package the data for transmission. This will reduce transmission time by compressing the data and it will facilitate the handling of data when it is received.

Our Product Support can accommodate data that is packaged using the TSO Interactive Data Transmission Facility (the TSO XMIT and RECEIVE commands) or data that is packaged using IBM's TRSMAIN program (the terse utility). Mainframe Access sample TSOXMIT provides a job that demonstrates the use of TSO XMIT to package a data set for transmission. If you want to use TRSMAIN, we recommend that you start by asking the z/OS systems programming staff at your company if TRSMAIN is already installed and available for use. If it is not, you can download the IBM TRSMAIN program from the ftp.software.ibm.com Web site using FTP. You can access the download using the anonymous user ID with your email address provided as the password. Use change directory commands to locate the TRSMAIN downloads in /s390/mvs/tools/packlib at this IBM ftp site. You should find a single binary file and both plain text and HTML explanations of the procedure for installing the utility.

When your data is ready for transmission, our Product Support can provide additional instructions for sending your data to the ftp.microfocus.com site. This may include specific directory locations, filenames, etc. that should be used. After you have transferred the data, please send a follow-up email to your support representative. This note should list the files that you have sent, the packaging tool(s) that you have used, and the z/OS data set characteristics of both the packaged files and the data sets that will be created when the packages are opened. The z/OS data set characteristics should include the RECFM, LRECL, BLKSIZE, primary space allocation and secondary space allocation.

Parent topic: Obtaining a VTAM Buffer Trace


Customizing Data Connect

This section describes advanced configuration for the Mainframe Access Data Connect server.

  • Introduction
  • Samples for Configuration
  • JCL Change for Data Connect
Parent topic: Mainframe Access Installation Guide


Introduction

At the completion of Mainframe Access installation and quick configuration, the Mainframe Access Data Connect server is ready to use for most Data Connect applications. This chapter will help you with the necessary customization if you need to change the default user verification and data set authorization checking. This chapter also describes how to customize a FSTAB file mapping table and the MFAVCTL file mapping data set.

Parent topic: Customizing Data Connect


Samples for Configuration

The installation procedure places several samples in the <hlq>.MFA.MFACNTL data set. If a sample is provided for a configuration task, use it as a starting point for your configuration. Usually you need to edit the sample, replacing provided information with information that is unique to your system.

The following table summarizes the samples that are provided for Mainframe Access Data Connect server.

MEMBER | DESCRIPTION
FSTAB | Assembler language macro used by the MFASFTAB sample.
MFASFTAB | Sample job and source statements for creating your own FSTAB module for file name mapping operations.
Parent topic: Customizing Data Connect


JCL Change for Data Connect

In order to supply all MFA and Data Connect function within one authorized library, the Data Connect module names have been renamed, and slightly reorganized as static load modules rather than dynamic overlays. All Data Connect load modules now begin with the prefix MFD.

//MFAS    PROC DSNQUAL='HLQ.MFA'
//*
//*------------------------------------------------------------------*
//*                                                                  *
//* Micro Focus Mainframe Access - Data Connect / FILESHARE          *
//*                                                                  *
//* Change the DSNQUAL value on the PROC statement to the correct    *
//* value for your installation.                                     *
//*------------------------------------------------------------------*
//MFAS     EXEC PGM=MFDSTART,PARM='APPLID=MFA62ACB',
//         REGION=0M,TIME=1440
//STEPLIB  DD DISP=SHR,DSN=&DSNQUAL..LOADLIB
//         DD DSNAME=CEE.SCEERUN,DISP=SHR
//         DD DSNAME=CEE.SCEERUN2,DISP=SHR
//CEEOPTS  DD DISP=SHR,DSN=&DSNQUAL..CNTL(CEEOPTS)
//SYSUDUMP DD SYSOUT=*
//FSMSGA   DD SYSOUT=*             for IDCAMS
//FSMSGC   DD SYSOUT=*             for APPC errors
//FSMSGL   DD SYSOUT=*             for FileShare log
//VSAMCTL  DD DISP=SHR,DSN=&DSNQUAL..MFAVCTL
Parent topic: Customizing Data Connect


Configuring Access to External Library Management Systems

This section describes the Mainframe Access support for external library management systems and change management systems.

  • About External Library Management
  • Panvalet
  • Librarian
  • Endevor
  • ChangeMan ZMF
Parent topic: Mainframe Access Installation Guide


About External Library Management

Mainframe Access provides seamless access to objects housed in repositories controlled by the following external management systems:

  • Panvalet from Computer Associates (www.cai.com)
  • Librarian from Computer Associates (www.cai.com)
  • Endevor from Computer Associates (www.cai.com)
  • ChangeMan ZMF

Contact the appropriate vendor for further information about these products.

Parent topic: Configuring Access to External Library Management Systems
Related information
www.cai.com


Panvalet

Panvalet is a direct access library system marketed by Computer Associates. It's primary use is as a source control system for software development.

  • About Panvalet
  • References
  • Panvalet Suffix Table
  • Suffix Table Override
  • Panvalet Security Exit
Parent topic: Configuring Access to External Library Management Systems


About Panvalet

With Panvalet, all source members are managed as fixed length records. The default size is the historical card image of 80 bytes. Panvalet may be used to manage any fixed-length data up to 4096 characters in length.

Panvalet provides licensed users with programmable access to their repository services via the PAM API. This is a read-only interface which permits multiple concurrent access for Mainframe Access threads to browse source members residing in Panvalet repositories. During Server initialization, Mainframe Access attempts to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Panvalet services are offered. Startup initialization messages indicate if Panvalet is available.

It is a customer responsibility to provide a suitable STEPLIB concatenation which enables selection of the desired release and version of the Panvalet components. At most sites, PANVALET is installed as an MVS Subsystem. Therefore the API is available within SYS1.LINKLIB. No override would be necessary unless a new version is being tested.

     //STEPLIB DD DSN=hlq.MFA.LOADLIB,DISP=SHR
     //        DD DSN=CAI.PANV144.CAILIB,DISP=SHR

The following messages are typical of the information written to the SYSLOG during Mainframe Access startup:

       MFM0063I: MFA Direct is active
       MFM0064I: MFA Direct number of processing tasks is 5
       MFMDS051I CA/LIBrarian Ready
       MFMDS052I CA/PanValet Ready
       MFMDS053I CA/ENDEVOR API 39 Ready
       MFMDS055I MCG/RPC feature active
       MFMDS001I DSS Server Ready
       MFM0001I: Mainframe Access V6.00    (04000000) is active

For source additions or updates under Panvalet, Mainframe Access must invoke the standard Panvalet batch utility PAN#1. Access to this utility is serialized, since Panvalet does not support multiple, concurrent access to this service. In some cases, you may have renamed the Batch Update utility PAN#1. If this is the case, the new name at this site must be defined to Mainframe Access as a parameter override.

Parent topic: Panvalet


References

  • PANVALET System Management Guide
  • PANVALET Messages Guide
  • PANVALET Installation Guide
  • PANVALET User Guide
  • PANVALET Extended Features Guide
Parent topic: Panvalet


Panvalet Suffix Table

Panvalet recognizes the following programming language or object types:

  • BAL
  • COBOL
  • DATA
  • FORTRAN
  • JCL
  • PL/I
  • RPG

Specification of such a native language type allows Panvalet to format the source files, and automatically add or remove the sequence numbers in the appropriate position for that language. In order to automate this language selection process, Mainframe Access has introduced a Panvalet Suffix Table to specify the language type based upon the file suffix as used on the workstation. In addition, the Suffix Table also specifies the default options to be specified on the ADD command of the PAN#1 batch update utility.

SUFFIX | ++ADD Options
(default) | DATA,LIST,NOFORMAT
ASM | BAL,LIST,NOFORMAT
ASSEM | BAL,LIST,NOFORMAT
BAL | BAL,LIST,NOFORMAT
BMS | BAL,LIST,NOFORMAT
CBL | COBOL,LIST,NOFORMAT
CNTL | JCL,LIST,NOFORMAT
COB | COBOL,LIST,NOFORMAT
COBOL | COBOL,LIST,NOFORMAT
COP | COBOL,LIST,NOFORMAT
COPY | COBOL,LIST,NOFORMAT
CPY | COBOL,LIST,NOFORMAT
DATA | DATA,LIST,NOFORMAT
DBD | BAL,LIST,NOFORMAT
JCL | JCL,LIST,NOFORMAT
JOB | JCL,LIST,NOFORMAT
MAC | BAL,LIST,NOFORMAT
MFS | BAL,LIST,NOFORMAT
PLI | PL/1,LIST,NOFORMAT
PL1 | PL/1,LIST,NOFORMAT
PSB | BAL,LIST,NOFORMAT

The above table describes the default Suffix Table as provided within Mainframe Access. If no changes are desired, no further customization is necessary.

Parent topic: Panvalet


Suffix Table Override

The built-in Panvalet Suffix Table may be replaced by including a special DD card in the Mainframe Access task JCL as follows:

     //PANSUFX  DD  DSN=hlq.MFA.CNTL(PANVALET),DISP=SHR

During initialization, this text file is analyzed and a new Suffix Table is created dynamically. The first entry defines a default language type to be used if no match is found in the table. The following extract illustrates the free-form format of the text file:

      *
      * MFA PANVALET CONFIGURATION CONVERSION TOOL
      *      AS ON 06/07/2003 AT 12:40
      *
      * SUFFIX TYPE     ++ADD OPTIONS
      ******** ******** ***********************
      *
      DEFAULT  DATA     LIST,NOFORMAT
      ASM      BAL      LIST,NOFORMAT
      ASSEM    BAL      LIST,NOFORMAT
      BAL      BAL      LIST,NOFORMAT
      BMS      BAL      LIST,NOFORMAT
      DBD      BAL      LIST,NOFORMAT
      MAC      BAL      LIST,NOFORMAT
      MFS      BAL      LIST,NOFORMAT
      MLC      BAL      LIST,NOFORMAT
      PSB      BAL      LIST,NOFORMAT
      CBL      COBOL    LIST,NOFORMAT
      COB      COBOL    LIST,NOFORMAT
      COBOL    COBOL    LIST,NOFORMAT
      COP      COBOL    LIST,NOFORMAT
      COPY     COBOL    LIST,NOFORMAT
      CPY      COBOL    LIST,NOFORMAT
      JCL      JCL      LIST,NOFORMAT
      JOB      JCL      LIST,NOFORMAT
      PLI      PL/I     LIST,NOFORMAT
      PL1      PL/I     LIST,NOFORMAT

In this way, customers may change the search order, the suffix name, and the Panvalet ADD options to meet their needs. You may have already compiled a custom Suffix Table from Mainframe Access Version 2. A migration tool is provided to convert this configuration back into a text file which may be presented to Mainframe Access Version 3.

 //jobname  JOB (MFA),'PANVALET SUFFIX',CLASS=A,MSGCLASS=X
 //***************************************************************
 //*        EXTRACT PANVALET SUFFIX FROM MFA SERVER V2
 //***************************************************************
 //*
 //PVSUFFX  EXEC PGM=MFAUTL01,REGION=1M
 //STEPLIB   DD  DISP=SHR,DSN=hlq.MFA.V3.LOADLIB
 //MFALIB    DD  DISP=SHR,DSN=hlq.MFA.V2.LOADLIB
 //MFAPARM   DD  DISP=SHR,DSN=hlq.MFA.CNTL(PANVALET)
Parent topic: Panvalet


Panvalet Security Exit

MFA supports a customized user exit (MFAPVXIT) that enables you to implement member-level security within your Panvalet repositories. This user exit is required because security is not available via RACF, and a proprietary Panvalet exit (PSPILXIT) is only available under TSO dialogs.

MFAPVXIT is automatically invoked to approve access rights for all Panvalet activity: import, export, and directory requests. A sample exit and test harness is provided within the .CNTL file shipped with the MFA product libraries:

Member | Description
MFAPVXIT | Sample Panvalet member security exit
PVTESTX | Test harness for MFAPVXIT
ASMPVT | Assemble and link PVTESTX
ASMPVX | Assemble and link MFAPVXIT

MFA provides the user ID, member name, and Panvalet master file name to MFAPVXIT, and interprets a return code of zero to mean that access is permitted. Any other return code results in access being denied. This means that the MFAPVXIT can create a directory filter based on the access rights of the individual or his department. The algorithm is entirely up to the site, and will be based on table-driven data compiled into the exit. The sample exit demonstrates how naming conventions, or tables of authorized users can be used to accomplish this.

Parent topic: Panvalet


Librarian

Librarian is a powerful change management system for source modules and data records.

  • About Librarian
  • References
  • Librarian Exit Table
Parent topic: Configuring Access to External Library Management Systems


About Librarian

Under Librarian, all source is stored within proprietary Librarian master files in a highly compressed format. Individual source modules may be stored and retrieved by name. Multiple master files may be defined and shared among the user groups.

Librarian provides licensed users with programmable access to source modules via the File Access Interface Routines (FAIR) API. This is a read-only interface which permits multiple concurrent access for Mainframe Access threads to browse source members residing in a Librarian master file. During Server initialization, Mainframe Access attempts to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Librarian services are offered. Startup initialization messages are indicated if Librarian is available. It is a customer responsibility to provide a suitable STEPLIB concatenation which enables selection of the desired release and version of the Librarian components.

        //STEPLIB DD DSN=hlq.MFA.LOADLIB,DISP=SHR
        //        DD DSN=CAI.LIBR43.CAILIB,DISP=SHR

For source additions or updates under Librarian, Mainframe Access invokes the standard Librarian batch utility AFOLIBR. Access to this utility is serialized, since Librarian does not support multiple, concurrent access to this service from the same address space. In some cases, you may have renamed the Batch Update utility AFOLIBR. If this is the case, the new name at this site must be defined to Mainframe Access as a parameter override.

        MFA_LIBRARIAN_HISTORY=”1”             - MFA default
        MFA_LIBRARIAN_UPD_MODULE=”LIBRUPD”    - site override
Parent topic: Librarian


References

  • Librarian Command Reference Guide
  • Librarian File Access Interface Routines
  • Librarian Messages Guide
  • Librarian Installation Guide
  • Librarian User Guide
  • Librarian Systems Services Guide
  • Librarian Security Administration Guide
Parent topic: Librarian


Librarian Exit Table

Librarian does support user exits under its Batch Update facility. The user exit may be common, or may be assigned to a specific master file. In order to configure this option, MFA references a reserved DD named LIBXIT$. If specified in the JCL, MFA builds a memory table to specify the Output Exit to be used for the given master file.

*  Librarian Exit Table (fixed format)
*
*  EXIT columns 1-8 is an exit module name
*       found in the STEPLIB, JOBLIB, LINKLIB concatenation
*  LIBRARIAN MASTER name resides in columns 11-54
*       any master file with this prefix will invoke the exit
*
* EXIT    Librarian Master file prefix or full name
********  ********************************************
LIBREXIT  PROD.LIB
LBXIT02   MY.LIBRARIAN.MASTER
Parent topic: Librarian


Endevor

Endevor is a full function change control system with signout controls and extensive user customization.

  • About Endevor
  • References
  • Endevor Dependent Regions
  • Endevor C1DEFLTS File
  • Endevor Setup Errors
Parent topic: Configuring Access to External Library Management Systems


About Endevor

Through the use of Exits and Processor Groups, it is possible to automatically re-compile the changed objects, and re-link any components which require those objects. Endevor also has several optional system features such as External Security, and alternate RACF user ID support.

Starting with Release 39, Endevor provides licensed users a powerful Endevor Services API (ENA$NDVR). This interface permits full-function access to read or update source objects residing in an Endevor repository. During Server initialization, Mainframe Access will attempt to load this interface into memory. If this API interface is available through the standard search order (STEPLIB, JOBLIB, or SYS1.LINKLIB at the customer site) then Endevor services will be offered. Startup messages will indicate if Endevor is available. It is a customer responsibility to provide a suitable STEPLIB concatenation for selection of the desired release and version of the Endevor components. Mainframe Access will examine the Endevor C1DEFLTS table to determine the version of Endevor being used. This is necessary because the control structures used by the Endevor API versions are not fully downward-compatible. Mainframe Access must build the API request using the format demanded by the version in effect at your site. If no C1DEFLTS table is found, Endevor support will not be enabled.

        //STEPLIB DD DSN=hlq.MFA.LOADLIB,DISP=SHR
        //        DD DSN=CAI.NDVRR16.CSIQAUTU,DISP=SHR
        //        DD DSN=CAI.NDVRR16.CSIQAUTH,DISP=SHR
        //CONLIB  DD DSN=CAI.NDVRR16.CSIQLOAD,DISP=SHR

Note that the Endevor API was designed to be a batch-oriented service. It is a file-based interface, not a record-based interface. That is, an object is moved from an Endevor-managed repository, to a specified work file; or vice-versa. Mainframe Access will dynamically create the necessary files as required. A transaction history log is likewise written to a log file. Mainframe Access may optionally be configured to retain a full Endevor transaction log to be used as an audit trail. Access to the Endevor interface is serialized since Endevor does not support concurrent accesses from the same address space. At the same time, all Endevor user exits and packages are operational. This means that site customization will affect the response time for an end-user accessing Endevor data under Mainframe Access. This may require adjustments to the timeout parameters on the clients.

Since all data movement is facilitated through temporary files, Mainframe Access is not able to support the Dsname Validation feature of Endevor. The temporary file used by Mainframe Access is deleted as soon as the transaction (Import or Export) ends. For those sites employing this feature, users could use the Endevor dialog tools under TSO to move their members into their own PDS. Then Mainframe Access could be used to move the PDS member from the mainframe to the workstation, and vice-versa. A subsequent promotion to Endevor would then indeed come from the exact same PDS that received the file at sign-out.

Mainframe Access does maintain the user ID security context for each active thread using the standard IBM security environment and standard SAF calls. Mainframe Access will always invoke the Endevor API interface using the security credentials of the end-user as provided during client logon. To minimize some administrative overhead, Micro Focus recommends the adoption of an Alternate RACF user ID to simplify the administration of RACF access rights for the user population. Access security remains a SITE responsibility. This is no different than standard BATCH or TSO access under Endevor. Mainframe Access will not schedule any Endevor access using the Mainframe Access started-task profile. Also be mindful that some change control "processors" might better be managed by specialist personnel using the Endevor ISPF panels rather than being triggered repeatedly by online Mainframe Access users.

Endevor support is available for R14 and later.

Parent topic: Endevor


References

  • Endevor Administration Guide
  • Endevor API Guide
  • Endevor Error Codes and Messages
  • Endevor Exits Guide
  • Endevor Footprints Guide
  • Endevor Installation Guide
  • Endevor Packages Guide
  • Endevor Security Guide
  • Endevor User Guide
  • Endevor Utilities Guide
Parent topic: Endevor


Endevor Dependent Regions

In order to isolate the Endevor run-time environment from the Mainframe Access address space, and improve the concurrency (and hence scalability) of Endevor accesses, Mainframe Access will schedule the execution of the Endevor API in an independent processing region referred to as an Endevor Dependent Region. This is a special purpose address space that Mainframe Access creates dynamically and shares with all Mainframe Access/Endevor users. It is serially assigned to whatever thread is in need of Endevor API services.

Multiple Endevor dependent regions may be started to meet your throughput requirements. The sample SERVERS member contains a definition for an Endevor address space group that allows a maximum of 2 address spaces to be started for Endevor processing. This value can be increased if the demands of your Endevor usage will benefit from greater concurrency.

You will need to update the started task JCL for dependent regions before you can use the Endevor support. Review the sample JCL member MFAAS and follow the instructions in that member to add your Endevor AUTHLIB and CONLIB program libraries to the STEPLIB concatenation. If you use Processor Groups to compile and relink automatically, specify DYNAMNBR=300 on the EXEC statement and eliminate the pre-allocation of SYSPRINT and SYSTERM which conflict with Endevor procedures to allocate compile and link output files.

For those sites where the logged in users may not have the authority to create transient files using their USERID as the high-level qualifier, there is a configuration parameter to set that high-level qualifier to some other value where all users have READ/WRITE/ALTER access.

ENDEVOR_DSNQUALIFIER="prefix"         --- OVERRIDE FOR ENDEVOR ACCESS

This must be specified within the configuration parameters specified by DD=XDBIN both in the MFA Control region, and the MFA Endevor Dependant Region.

In addition, the Endevor Dependent Region will automatically shutdown after a pre-defined idle period. The default is 30 minutes. This automatic shutdown feature allows Endevor resource allocation to quiesce with non-use, and thereby permits overnight backups to run without manual intervention. This idle period is defined as two scan intervals as specified in the Dependent Region parameter file:

DSS_SCAN_INTERVAL="15"                --- idle timeout for shutdown

By default, the Endevor Dependent Region will create a new VIO file (DDNAME=ENDVMSG) to be used as the Endevor transaction log for all subsequent transactions within that dependent region. The DCB attributes are:

PS,FBA,LRECL=133,UNIT=VIO,DISP=(NEW,DELETE),DSN=&MSGLOG

This file will effectively be a memory resident file, buffered by JES. Note that during initialization there is no end-user profile in effect. That means the VIO file will be owned by the started task. Therefore, the started task security profile must allow any end-user to write to this file. Endevor will OPEN the file as the transaction log. This behavior can be taken as the default, or specified by:

VIO_FOR_ENDEVOR_LOG=”1”         default VIO

If this causes a security violation at your site, you may configure the log to be disk-resident, provided the high-level qualifier will allow universal READ/WRITE access to the log. To override the default, use:

VIO_FOR_ENDEVOR_LOG=”0”          use DISK

Now Mainframe Access will supply overrides to disk as follows:

UNIT=SYSALLDA,DSNAME=prefix.jobname.ASnnnnn.MSGLOG

where the jobname and address space number will ensure uniqueness. The prefix will be taken from the ENDEVOR_ DSNQUALIFIER described above.

Parent topic: Endevor


Endevor C1DEFLTS File

It may be necessary to modify the C1DEFLTS table to facilitate the Endevor support in a multi-user environment. If you do modify the C1DEFLTS table, the resulting C1DEFLTS load module should be stored in the STEPLIB of the MFA server start-up JCL to allow for a custom usage. Your Endevor administrator will have the current C1DEFLTS source and corresponding JCL.

The following C1DEFLTS table change is required:

  • The BATCHID= parameter must be 1. This permits signout and security accesses to be based on the security profile of the user, not the MFA Server started task.
C1DEFLTS TYPE=MAIN,
         ACCSTBL=,       ACCESS SECURITY TABLE           X
         APRVFLG=N,      APPROVAL PROCESSING (Y/N)       X
         ASCM=0,         ASCM CONTROL PASSWORD           X
         BATCHID=1,      BATCH UID FROM JOBNAME/USER=    X
         CIPODSN=,       CCID VALIDATION DSNAME          X
          .
          .
          .
          .
C1DEFLTS TYPE=END
END
Parent topic: Endevor


Endevor Setup Errors

Several environmental conditions are validated when the first transaction is processed on an Endevor Dependent Region. Failure to provide a consistent run-time environment will result in the following abends:

Abend | Description
996 | MFAS startup error - no DSS environment found
997 | Endevor DR setup error - no MSGLOG established
998 | Endevor version mismatch between CR and DR
999 | No Endevor support found in STEPLIB or JOBLIB
Parent topic: Endevor


ChangeMan ZMF

Micro Focus's ChangeMan ZMF is a comprehensive mainframe specific solution that provides reliable, streamlined implementation of changes in z/OS environments. Its version, build and release management functions can be used to manage system changes from development to deployment.

  • About ChangeMan ZMF
  • Customization
  • References
  • AppMaster Builder Support using APS Components
Parent topic: Configuring Access to External Library Management Systems


About ChangeMan ZMF

ChangeMan ZMF 5.3 introduced the ChangeMan ZMF XML Services, an open interface for interoperability and data interchange with ChangeMan ZMF. This new interface is intended to replace the RPC and API interfaces that were used with earlier releases of ChangeMan. Mainframe Access Server implements the ChangeMan functions using the XML Services interface.

Mainframe Access requires ChangeMan Version 5.5.6 or later.

Parent topic: ChangeMan ZMF


Customization

The customizations required in Mainframe Access Server are simple and deal primarily with defining the interface to the ChangeMan ZMF subsystem. There are four MFA Server startup parameters for defining this interface and they are described in detail below. The parameters are also documented in the section Editing Mainframe Access Parameters in the chapter Configuration.

The Server's ChangeMan interface uses Mainframe Access Application Server address spaces (also known as dependent regions) to provide isolation for the ChangeMan processing. Separating the processing from the MFA Server control region avoids potential interference with other client requests being processed in the control region.

Both the control region and the dependent region(s) have startup parameter requirements for the ChangeMan interface definition. The sample control region parameters are found in member PARMS and the sample dependent region parameters are found in member PARMSAS. Review the startup parameter information in the sections that follow and update your parameter definitions with values appropriate for your installation.

  • Control Region Startup Parameters
  • Control Region Started Task JCL
  • Dependent Region Started Task JCL
Parent topic: ChangeMan ZMF
Related information
Editing Mainframe Access Parameters


Control Region Startup Parameters

CHANGEMAN_COMMON_BUILD | Specifies whether or not Mainframe Access accommodates group builds submitted under AppMaster Builder. Specify 1 to enable group builds or 0 to disable them. The default is 0. When enabled for group builds, MFA modifies the build options for each member of the AMB group to match the component name and type submitted, ensuring that each build request in the group is properly executed.
CHANGEMAN_DSNQUALIFIER Specifies a high-level qualifier for dynamically allocated data sets created by MFA Server to hold input files during the staging process. MFA Server creates these data sets dynamically as card-image sequential data sets that are deleted when the associated client request completes. The default qualifier is the login ID of the current user. You should set an alternate qualifier if your installation's SERNET does not have RACF authority to read or write data into files stored in data sets named with the current user's login ID as the high-level qualifier.

If an alternate qualifier is required, see your ChangeMan administrator or your security administrator for assistance in selecting a proper value.

If your ChangeMan functionality is restricted by security subsystem authorizations, you might need to specify your dataset high-level qualifier such that read access to the data sets is always permitted.

CHANGEMAN_INTERFACE Specifies the name of the ChangeMan ZMF module. During ChangeMan request processing, MFA Server loads and branch enters this module. Valid values are SERXMLBC and SERXMLAC. The default is SERXMLAC.

The preferred interface module is SERXMLAC, which is not documented in ChangeMan ZMF; however, it provides better interface performance than SERXMLBC by using virtual storage instead of data sets for XML input and output exchange between MFA Server (the requester) and ChangeMan ZMF.

ChangeMan ZMF documents only the SERXMLBC interface, which is the XML services batch client. SERXMLBC is intended for use in a batch job stream and requires XMLIN and XMLOUT DD statements to define its required data sets. The MFAAS JCL sample provides sample DD statements for XMLIN and XMLOUT; however, they are commented out. If you must use SERXMLBC, contact SupportLine for assistance with data set definitions.

CHANGEMAN_SSID Initializes the Mainframe Access ChangeMan interface by providing the final character of the z/OS subsystem ID used to identify ChangeMan. Omit this parameter to bypass Mainframe Access initialization for the ChangeMan interface. Valid values are any single alphabetic or numeric character. The character specified is appended to the subsystem ID string "SER", completing the four-character ID. For example, if you specify CHANGEMAN_SSID="A", the z/OS subsystem ID becomes "SERA".

Your ChangeMan administrator can help you to determine the correct subsystem ID to use.

CHANGEMAN_TEST_OPTION | Specify whether or not MFA uses the XML trace option. Specify 1 to enable XML trace or 0 to disable it. The default is 0. When enabled, SERNET logs information in XML format into the standard SERPRINT DD file. This file can be used to identify problems and to validate MFA services. Enabling XML trace is not recommended for production systems due to the large volume of log data generated.
CHANGEMAN_XMS_SIZE | Specifies the size in megabytes of the cross-memory buffer used by MFA for transmitting XML requests and responses to the ChangeMan dependant Region. A single integer in the range of 1 through 8 is accepted. Note that about 2500 directory entries, or 10,000 lines of source code may be passed in 1 megabyte. If your requirements exceed these limits, then you can configure a more appropriate value. The default value with no configuration is 1 megabyte.
Parent topic: Customization


Control Region Started Task JCL

You can customize the sample JCL procedure for the MFA Server started task with required and optional DD statements for the ChangeMan interface.

  • CMNOPTS
  • CMNLIB$
  • CMNJOB$
Parent topic: Customization


CMNOPTS

Include and customize this DD to provide MFA with your site-dependent user options and your default build options. MFA reads the XML file you specify, using only the options defined for field names that correspond to build and user options. These options enable MFA to properly check out and stage ChangeMan components. See your ChangeMan ZMF documentation for ZDD Build Options for more information.

//CMNOPTS DD  DSN=youroptions.xml,DISP=SHR

Where youroptions represents a filename prefix of your choice.

The following is an example of an XML file containing user and build options:

<?xml version="1.0"?>
<options name="BUILD">
 <profile application="*" language="*" procname="*" libtype="*">
  <field name="Language"       editable="Y" default="CBL"/>
  <field name="BuildProc"      editable="Y" default="CMNCOB2/>
  <field name="Db2PreCompile"  editable="Y" default="N" />
  <field name="Db2Subsystem"   editable="Y" default="DSN7" />
  <field name="CompileOptions" editable="Y" default="RENT,LIST,XREF(SHORT)" />
  <field name="LinkOptions"    editable="Y" default="RENT,MAP,XREF" />
  <field name="UserOption01"   editable="Y" default="N"
     tag="Compile only"  required="Y"  validation="YN"   />
  <field name="UserOption02"   editable="Y" default="N"
     tag="IMS DLIT entry"  required="N"  validation="YN"   />
  <field name="UserOption03"   editable="Y" default="N"
     tag="CICS precompile"  required="N"  validation="YN"   />
  <field name="UserOption04"   editable="Y" default="N"
     tag="Drop INCLUDEs"  required="Y"  validation="YN"   />
  <field name="UserOption05"   editable="Y" default="N"
     tag="Easytrieve"  required="Y"  validation="YN"   />
  <field name="UserOption06"   editable="Y" default="N"
     tag="AMB Generation"  required="Y"  validation="YN"   />
 </profile>
</options>

The user build options tags <UserOptionnn> support a special keyword for validation. If the valuation="text" corresponds to a reserved keyword as described by ChangeMan ZMF, then a generic test will be made for NUMERIC, ALPHABETIC, or ALPHANUMERIC text. Otherwise, the "text" characters themselves will be become the customized set of characters to be used as the validation string. Only a character found in this string will be allowed to act as the User Option value.

Parent topic: Control Region Started Task JCL


CMNLIB$

Optionally include and customize this DD to enable MFA to determine which component types are buildable, depending on the language type and build procedures specified. This not only identifies which Library types Drag & Drop may build, but also provides default language names for new components which have no component history which would otherwise provide this information.

//CMNLIB$ DD  DSN=hlq.MFA.CNTL(CMNLIB$),DISP=SHR

Where hlq is a high level qualifier that was given to all Mainframe Access data sets when the FRESTORE job was run.

The following is the default data:

*  ChangeMan Library Table (fixed format)
*          Like Source only
* L
* I BLDPROC  LANGUAGE
* B  NAME     Name
*** ******** ********
ASM CMNASM   ASM
COB CMNCOB2  COBOL
APS DGSAPCOM COBOL
ASC DGSAPSCR COBOL
Parent topic: Control Region Started Task JCL


CMNJOB$

Optionally include and customize this DD to define up to four job cards ChangeMan can submit for a build request, which is scheduled as an independent job by SERNET as part of the staging process.

//CMNJOB$ DD DSN=hlq.MFA.CNTL(CMNJOB$),DISP=SHR

Where hlq is a high level qualifier that was given to all Mainframe Access data sets when the FRESTORE job was run.

The default job card contains:

//useridB  JOB (MFA),'CMN-BUILD',CLASS=A,MSGCLASS=X
//*
//*
//*
Parent topic: Control Region Started Task JCL


Dependent Region Started Task JCL

The MFAAS sample JCL procedure contains JCL statements you must customize and enable for the ChangeMan interface. If you update sample JCL in the MFA Server samples data set, be sure to copy it to the system procedure library.

Parent topic: Customization


References

  • ChangeMan ZMF XML Services User Guide
  • ZMF Administrator Guide
  • ZMF Messages Guide
Parent topic: ChangeMan ZMF


AppMaster Builder Support using APS Components

ChangeMan contains an optional feature for managing APS file types in a ChangeMan application. This support is incompatible with the AppMaster Builder support for APS components as provided by Micro Focus as it does not allow you to over-ride the Build procedures to invoke the AppMaster Builder Generation process.

As a result, when configuring ChangeMan for use with applications and packages used by AppMaster Builder, ChangeMan Administration should not configure the file types using the Selectable Option column, as shown in the following screen shot from the ChangeMan Administration Panels under TSO:

--------------------- WAC4 - LIBRARY TYPES PART 1 OF 2 ----------- Row 1 of 65
 COMMAND ===>                                                  SCROLL ===> PAGE

 Enter END command to save changes or CANCEL to exit.
 Enter * in line command field for global staging libraries selection list.

      LIB                                               LIKE  DEFER TARGET SEL.
      TYPE DESCRIPTION                               (S/C/L/P)(Y/N)  TYPE  OPT.
 '''' COB  Cobol_______________________________________  S     Y     LOD   __
 '''' CPY  Copy Books__________________________________  C     Y     ___   __
 '''' JCL  Job Control Language________________________  P     Y     ___   __
 '''' CTC  Control cards_______________________________  P     Y     ___   __
 '''' LOD  Load Library________________________________  L     Y     ___   __
 '''' ACI  APS COBCICS_________________________________  S     Y     LCI   __
 '''' ACN  APS APSCNTL_________________________________  P     Y     ___   __
 '''' ADA  APS APSDATA_________________________________  P     Y     ___   __
 '''' ADE  APS APSDE___________________________________  P     Y     ___   __
 '''' ADG  APS COBDLG__________________________________  S     Y     LDG   __
 '''' AEX  APS APSEXPS_________________________________  P     Y     ___   __
 '''' AFE  APS APSSCFE_________________________________  P     Y     ___   __
 '''' AID  APS COBIDMS_________________________________  S     Y     LOD   __
 '''' AIM  APS COBIMS__________________________________  S     Y     LIM   __
 '''' AIO  APS APSCNIO_________________________________  P     Y     LOD   __
 '''' AIS  APS COBISPF_________________________________  S     Y     LOD   __
 '''' AMA  APS APSMACS_________________________________  C     N     ___   __
 '''' AMS  APS AMSERV__________________________________  P     Y     ___   __
 '''' AMV  APS COBMVS__________________________________  S     Y     LOD
Parent topic: ChangeMan ZMF


Configuring Access to Enterprise Server Mainframe Subsystem Support

Mainframe Subsystem Support (MSS) is an Enterprise Server feature that provides an execution environment for CICS transaction programs on Windows and UNIX platforms. These programs can be ones migrated from the z/OS platform, or entirely new applications, developed specifically for the Enterprise Server MSS environment.

Mainframe Access runs on z/OS and functions as middleware, providing a transparent bridge between your ES/MSS systems and your z/OS CICS systems and enabling a full range of peer ISC communications between these systems including transaction routing, function shipping, distributed program link and distributed transaction processing. The configuration elements in MFA Server create the relationship between MSS and CICS and enable MFA Server to convert between MSS's TCP/IP-based protocol and CICS's LU6.2-based ISC protocol.

This section presents a step-by-step approach to completing the Mainframe Access Server customizations for ES/MSS support. Use this section to work through the customizations.

  • Prerequisites
  • MFA Server Configuration for ES/MSS
  • Technical Details
Parent topic: Mainframe Access Installation Guide


Prerequisites

Be sure to complete the basic configuration and installation testing of your Mainframe Access Server before you start the advanced configuration activities for ES/MSS support. See the section Quick Configuration in the Configuration chapter for information on the basic configuration. The configuration described in this appendix assumes that you have completed all of the quick configuration steps that establish your parameter file, server definitions, JCL procedures, etc. Also complete the installation verification testing to ensure that you have a running configuration.

Parent topic: Configuring Access to Enterprise Server Mainframe Subsystem Support


MFA Server Configuration for ES/MSS

The diagram below shows a single MSS to CICS connection. The MFA Server configuration statements that enable this bi-directional connection are highlighted in the diagram. Keep in mind that there are corresponding configuration requirements in MSS and CICS, and the entire configuration relies on the communications infrastructure provided by your TCP/IP stack and VTAM SNA server.

ES/MSS runs on a Windows or UNIX platform and is connected to your z/OS system by TCP/IP communications. The other software elements reside on a z/OS platform(s). MFA Server runs on z/OS and functions as middleware, providing a transparent connection between ES/MSS and the CICS system. MFA Server is normally installed on the same z/OS system as CICS, although this is not a requirement. The connection between MFA Server and CICS uses standard CICS ISC LU6.2 protocols and MFA Server and CICS may reside in different systems on your SNA network. ES/MSS and MFA Server participate in the TCP/IP network by starting socket listeners, and by accepting and originating socket connection requests. CICS and MFA Server participate in the VTAM SNA network as Logical Units (LUs) by creating and opening a VTAM Access Method Control Block (ACB), and by allocating and managing LU6.2 conversations.

The MFA Server configuration is easy. There are three distinct parts to the configuration, numbered 1, 2, and 3 in the diagram. Part 1 is a simple enabling, or activation, statement. Part 2 defines your z/OS CICS system and provides the information needed for a VTAM SNA connection to this system. Part 3 defines your ES/MSS system and provides the information needed for a TCP/IP connection to this system. All of these statements can be found in the PARMS (Part 1) and SERVERS (Parts 2 and 3) members of your MFA Server <hlq>.CNTL data set. The definitions shown here for ES/MSS and CICS are two of the actual samples from that data set. When you understand the configuration requirements and have determined the correct values for your systems, complete your configuration using a text editor to update these sample definitions with your values. There is no pre-processor or configuration utility used with the MFA Server definitions and there is no configuration information maintained by MFA Server across restarts. So, each time MFA Server is started, your current definitions will be read in during start up, processed and activated. If you need to make changes during your testing, simply update the configuration statements and restart MFA Server.

The following subsections describe the customizations needed for your ES/MSS - CICS connection. The discussion refers to sample definitions that are provided by MFA Server installation and if this is your first ES/MSS configuration it will be easy to update the sample definitions as described.

  • Enable ES/MSS Support
  • Define the Target z/OS CICS System
  • Define the Target ES/MSS Server
  • Restart MFA Server
Parent topic: Configuring Access to Enterprise Server Mainframe Subsystem Support


Enable ES/MSS Support

MFA Server automatically activates the outbound feature and processes other definition statements for the MSS feature when it detects a valid (uncommented) MCO configuration in the MFAXML member.

Parent topic: MFA Server Configuration for ES/MSS


Define the Target z/OS CICS System

Your MFAXML member in the MFA Server <hlq>.CNTL data set contains two sample CICS server definitions, one being the CICA sample shown here:

<MCO         ID="CICA" LUNAME="CICSSYSA" MODENAME="#INTER"
             TPNAME="*" SYNCLEVEL="0" SECURITY="0"
/>
ID="CICA"
Identifies the start of a z/OS CICS target server definition and provides the SYSID value for that server. Change this value to the SYSID of your z/OS CICS system. Specify the same SYSID when you define this CICS to your ES/MSS server in a connection definition.
LUNAME="CICSSYSA"
Provides the SNA LU name (also referred to as the VTAM ACB name or VTAM APPL name) of your CICS system. Change the value to the LU name of your CICS system.
TPNAME="*"
Identifies the transaction program name used in LU6.2 requests. The actual transaction program name used in each LU6.2 request depends on the function that is requested, and the value is supplied by the system that originates a request. MFA Server adapts depending on the value supplied. Leave this parameter as-is.
MODENAME="#INTER"
Provides the name of the VTAM SNA logmode used for LU6.2 sessions. If necessary, change the value to the name of the VTAM SNA logmode you want to use for your LU6.2 sessions. This same logmode name should be used in your CICS SESSIONS definition for the ES/MSS server.
SYNCLEVEL="0"
Sets the synchronization level for LU6.2 requests and is supplied by the system that originates a request. MFA adapts depending on the value supplied. Leave this parameter as-is.
SECURITY="0"
Sets the security level for LU6.2 requests and is supplied by the system that originates a request. MFA adapts depending on the value supplied. Leave this parameter as-is.
Parent topic: MFA Server Configuration for ES/MSS


Define the Target ES/MSS Server

Your MFAXML member in the MFA Server <hlq>.CNTL data set contains two sample ES/MSS server definitions, one being the MSS1 sample shown here:

<ES-MTO      ID="MTO1" ACBNAME="MFAMTO1" IPADDRESS="YOUR.MTO.HOSTNAME"
             PORT="2200" SESSIONS="4" SOCKETS="1"
/>
ID="MTO1"
Identifies the start of an ES/MSS target server definition and provides the ES/MSS SYSID needed to identify the ES/MSS system to MFA Server. Change this value to the SYSID of your ES/MSS server. Specify the same SYSID for the CONNECTION(name) when you define this ES/MSS server to your z/OS CICS system.
ACBNAME="MFAMTO1"
Assigns a VTAM ACB name (also referred to as the SNA LU name or VTAM APPL name) to the ES/MSS server. You can define more than one ES/MSS server and each server you define must have its own ACBNAME, giving it a unique identity in the z/OS CICS system. MFA Server provides two VTAM APPL definitions for ES/MSS servers - MFAMTO1 and MFAMTO2. These are installed and activated in your VTAM SNA configuration during MFA Server installation. If you are defining only one ES/MSS server, leave the ACBNAME as MFAMTO1. Use the MFAMTO2 ACB name if you define a second server. To define more than two ES/MSS servers, you must first install additional VTAM APPL definitions.
IPADDRESS="YOUR.MTO.HOSTNAME"
Identifies the internet address of your ES/MSS server machine. Change this value to either the machine name of the server where you're running ES/MSS or the internet IP address of the server.
PORT="2200"
Identifies the TCP/IP port on your ES/MSS server that has been configured as an ISC listener. Change this value to the the ISC listener PORT number on your ES/MSS server.
SESSIONS="4"
Identifies the maximum number of transaction processing sessions that will be managed on a single socket connection. Each active LU6.2 conversation requires a session and the session traffic is interleaved on the MSS to MFA socket connection. For testing purposes, leave this value as-is. However, you might need to adjust it upwards to satisfy your installation's demand as usage increases.
SOCKETS="1"
Identifies the number of sockets available for each MSS to CICS connection. Because ES/MSS requires a single socket for each connection to CICS, leave this value as-is.
Parent topic: MFA Server Configuration for ES/MSS


Restart MFA Server

When you complete the configuration steps, save your updated definitions and restart your MFA Server to activate the definitions. Be sure to complete the related configuration activites in ES/MSS and z/OS CICS before you begin testing.

Parent topic: MFA Server Configuration for ES/MSS


Technical Details

The more detailed tecnical information in this section will increase your understanding of the configuration requirements. You will also be better prepared to respond to operational issues that may arise during the testing of this feature.

  • How ES/MSS Understands the Connection
  • How z/OS CICS Understands the Connection
Parent topic: Configuring Access to Enterprise Server Mainframe Subsystem Support


How ES/MSS Understands the Connection

The communication between ES/MSS and MFA Server uses a proprietary TCP/IP protocol that conveys the necessary LU6.2 protocol information in TCP/IP packets. The SYSIDs used in the MFA Server configuration are the key to this communication. In the example definitions, the target z/OS CICS system is identified as CICA and the target ES/MSS server is identified as MTO1. The initial connection messages between ES/MSS and MFA Server use these SYSID values to exactly identify the two target systems.

If ES/MSS initiates the socket connection to MFA Server, ES/MSS will send a "bind" packet for SYSID CICA. The bind packet also contains the SYSID of the originating MSS, MTO1. The initial packet from ES/MSS is identical to the initial packet from a CICS support client, so MFA Server needs to identify the type of requester. If MFA Server finds a definition for an ES/MSS server with a SYSID of MTO1 (the ID parameter in the MCO definition) and the request originated from the IP address specified in that definition, then MFA Server recognizes this as a request from an ES/MSS server. Otherwise, the connection is recognized as a request from a CICS support client.

At this point, it is important to note that support for CICS has been available in earlier versions of MFA Server and this support allows MFA Server clients to originate requests INTO a z/OS CICS system. This same level of support has also been used by ES/MSS systems, before the availability of the ES/MSS outbound feature. This level of support does not require a definition for the ES/MSS server and it does not require the ES/MSS outbound feature support. In this case, the only definition required is the definition of the target z/OS CICS system (number 2 in the diagram). If your only need is for ES/MSS requests into CICS, you may continue to configure your MFA Server in this way. However, our recommendation is that you follow the configuration requirements as outlined in this appendix and define a complete bi-directional connection for the systems that uses MFA Server's ES/MSS outbound feature. The extra effort is minimal and your systems will be ready to support CICS requests into ES/MSS, when they are needed. The complete configuration also results in each ES/MSS having a unique identity from the perspective of the z/OS CICS systems.

Once the initial connection is established, the ES/MSS and CICS definitions have been selected and MFA Server has all of the information it needs to accept a request from ES/MSS and send it into z/OS CICS over an LU6.2 ISC connection. MFA Server will allocate LU6.2 conversations using the MFAMTO1 ACB that has been defined for this ES/MSS. The conversation partner will be the z/OS CICS system that is using the ACB named CICSSYSA and the SNA session for the conversation will use the #INTER SNA logmode. The VTAM SNA logmodes are part of your VTAM SNA configuration and the suggested name can be changed to any other logmode name used for LU6.2 ISC connections in your system. Just be sure that the specified logmode definition is available to both MFA Server and CICS. The MFAMTO1 ACB name used in this sample definition is defined to the VTAM SNA network using a VTAM APPL definition. The APPL definition for MFAMTO1 is provided in another MFA Server sample, the MFAVTAM member in your <hlq>.CNTL data set. This member is installed in your VTAMLST definitions and activated during MFA Server installation.

Each ES/MSS server that you define must have its own ACBNAME and it is this ACBNAME that gives each server a unique identity in the z/OS CICS system(s).

Parent topic: Technical Details


How z/OS CICS Understands the Connection

The communication between z/OS CICS and MFA Server uses standard LU6.2 ISC protocol as implemented by CICS. The SNA logical unit names used in the MFA Server configuration are the key to this communication. In the example, the target z/OS CICS system is identified as CICSSYSA (LUNAME="CICSSYSA") and the target ES/MSS server is identified as MFAMTO1 (ACBNAME= "MFAMTO1").

Our target z/OS CICS initiates work to ES/MSS when a request is directed to an external CICS SYSID that is associated with the MFAMTO1 LU name by CICS definitions. A CICS CONNECTION defines the MFAMTO1 LU name and assigns an external SYSID. A CICS SESSIONS definition for that connection defines the SNA logmode to be used for the ISC conversations. It is important to note that the SYSID values known to z/OS CICS do not have to match the SYSID values known to MFA Server and ES/MSS, however, MFA Server and ES/MSS must agree in their definitions. Although the SYSID values known to CICS can be different from the ES/MSS and MFA Server definitions, we recommend that the same SYSID values be used throughout the definitions.

CICS handles the request to the external SYSID by establishing the LU6.2 sessions that support the ISC exchanges, if they are not already established. CICS then sends the initial FMH-5 Attach request for the conversation to MFAMTO1. MFA Server recognizes this request as a conversation for ES/MSS because CICS used the MFAMTO1 LU name. MFA Server also checks that the request originated in a defined CICS server by locating the definition for the originator's LU name (CICSSYSA) and logmode name (#INTER) combination. Having located the two sets of definitions, MFA Server can forward the request on to the target ES/MSS server. If there is currently no socket connection to ES/MSS, MFA Server has the IP address and port number needed to contact ES/MSS's ISC listener. Now the request can be forwarded to ES/MSS over the socket connection associated with the MTO1-CICA SYSID combination.

Parent topic: Technical Details


Configuring z/Server feature support

  • Introduction
  • Program materials
  • Configuration overview
  • Preparing for configuration
  • Steps to activate z/Server
  • z/Server startup and installation verification
  • Optional: Adaptations to the IBM Developer for System z RSED installation
Parent topic: Mainframe Access Installation Guide


Introduction

z/Server V4R0 consists of mainframe components which have to be installed in a z/OS environment.

This document is intended for system programmers installing and configuring the z/Server software on their z/OS host system.

  • z/Server overview
  • The z/Server configuration file
Parent topic: Configuring z/Server feature support


z/Server overview

z/Server supports the execution of mainframe programs called from a client via TCP/IP requests.

z/Server provides:

  • A multi-tasking scheduling server (called scheduler)
  • An initialized LE environment
  • Automatic code page translation
  • Task level security
  • XML support
  • User servers running an ISPF environment
  • Command support
  • MVS catalog and data set access
  • JESx access
Parent topic: Introduction


The z/Server configuration file

XML configuration file

The configuration for z/Server is now part of the Mainframe Access Server XML configuration file and is used to store all of the configuration and properties that control how Mainframe Access Server and the z/Server feature operates. It's these parameters that you need to review before you can get your z/Server feature setup.

In order to take advantage of the new single Mainframe Access XML configuration file you must have taken all the actions in the Migration to use the XML configuration file, be using the unified scheduler and using MFA Server to start the holder task internally (equivalent to having set ZSERVER FEATURE=HOLDER in the old MFA Server configuration file). These migration actions can be found in the Micro Focus Enterprise Developer 3.0 product Help.

See Migrating old configurations to new XML configuration for more information on how to migrate your existing configuration files.

Legacy configuration files

Legacy configuration files are still supported. If you want to continue to use them, full details of their use are contained in the version of the z/Server Installation Guide that accompanied Enterprise Developer for z Systems 3.0, available from the Micro Focus Product Documentation web pages.

Parent topic: Introduction


Program materials

In hlq.ZSERVER you will find the z/Server software components (machine-readable material) and the following samples in hlq.ZSERVER.SAMPLIB:

TAUSACOB
Demonstrating an ISPF tool written in COBOL. The tool returns the parameters passed to it using the ISPF Shared Pool variable TAUTOPM.
TAUSAPL1
Demonstrating an ISPF tool written in Open PL/I. The tool returns the parameters passed to it using the ISPF Shared Pool variable TAUTOPM.
TAUSACLA
Demonstrating an ISPF tool written in CLIST that adds two input values and returns their sum.
TAUSACLI
Demonstrating an ISPF tool written in CLIST that returns the input value that is entered.
Parent topic: Configuring z/Server feature support


Configuration overview

To configure the z/Server feature with a minimum of customization, use the following guidelines:

  1. Define the necessary started tasks:
    • A z/Server scheduler address space
    • User server address spaces (batch TSO address space)
  2. Optional: Define a logon procedure for user servers as CEA-launched TSO address spaces.
  3. Before z/Server address spaces can be started, you must customize a minimum configuration that consists of:
    • The MFA Server holder task configuration:
      • Specify the SVC number (default 238)
      • Specify the data space token (default TAURSERV)
      • Specify the name of the IP stack used for processing (default TCPIP)
    • The scheduler configuration:
      • Specify the general listener port (default 1200)
      • Specify the user server port range (default 1201-1249)
      • Specify the name of the user server started tasks (default IVPUSRT)
    • Optional: For CEA scheduler support:
      • Specify the name of the logon procedure (default CEAPROC)
      • Specify the name of the initial command REXX procedure (default ZCEAICMD)
  4. Issue a command to MFA to start the z/Server holder, which in turn will start the scheduler address space(s).
  5. Run the installation verification procedure hlq.ZSERVER.JCL(IVPVERI) for scheduler.
  6. Run the TAU REXX procedure to verify user server startup. This is limited to support of port numbers up to a length of four characters.
  7. Edit the master model configuration file hlq.ZSERVER.MASTER:
    • Enter a unique system name after "System:", for example, LPAR1.
    • Customize the dataset names pointing to the models after "Conf:".
  8. Edit the REXX procedure hlq.ZSERVER.EXEC(TAUZCAPP) and specify the correct name of the master model configuration file hlq.ZSERVER.MASTER after "sysdsn=".
Parent topic: Configuring z/Server feature support


Preparing for configuration

  • Before You Begin
  • SVC Routine
  • Address spaces
  • Dataset renaming
Parent topic: Configuring z/Server feature support


Before You Begin

The following table lists important configuration data that you need to know in order to complete the quick configuration. Review these items and determine the appropriate values before you proceed with customization:

ITEM | DESCRIPTION
hlq | High level qualifier that was given to all Mainframe Access data sets when the FRESTORE job was run.
taurispf | The JCL procedure and jobname of the z/Server STC scheduler started task. The default value is TAURISPF.
ivpusrt | The JCL procedure name of the z/Server STC user server started task.
svc_no | The type-3 supervisor call routine number reserved for TAURAUTH. The default value is 238.
listener_port | The TCP port reserved for the z/Server STC scheduler. The default value is 1200.
first_port | The first TCP port that defines the range of ports available for the STC user servers. The default value is 1201.
last_port | The last TCP port that defines the range or ports available for the STC user servers. The default value is 1249.

Optionally, for CEA:

ITEM | DESCRIPTION
ceaproc | The JCL procedure of the CEA user server.
cea_account | The accounting number used by all TSO users who use the CEA scheduler.
Parent topic: Preparing for configuration


Address spaces

There are different types of address spaces that come with z/Server:

  • One or more scheduler address spaces (jobname taurispf).
  • One or more STC user server address spaces per TSO user/ Eclipse client (STC).

If you want to use the CEA-launched address space you need the following address spaces:

  • One or more CEA user server address spaces per TSO user/Eclipse client (TSO address space).

They need an associated user ID:

  • Scheduler use the assigned user ID.
  • STC user servers start out with the assigned user ID, which is then switched to the user ID of the client that requested execution of some application via TCPIP and started them.

If you want to use the CEA-launched address space you will also need the following:

  • CEA user servers are started with the TSO user ID of the client.

The scheduler address space defines a LISTENER_PORT that listens for incoming requests from the client, and a further port range (defined by FIRST_PORT through LAST_PORT) that will be assigned to different user servers as required. The combination of ports specified by the scheduler (both LISTENER_PORT and the range specified by FIRST_PORT through LAST_PORT) must be opened in the firewall protecting the z/OS host system. These ports should not be assigned to the scheduler. Instead, if desired, an appropriate RACF profile in the SERVAUTH needs to be defined. Please refer to IBM's TCPIP documentation. The default port range specified by the configuration file that comes with z/Server is 1200 to 1249.

User servers use the port assigned to them by the scheduler, to listen for incoming requests.

Parent topic: Preparing for configuration


Dataset renaming

To be able to use the rename data set functionality in the AWM Eclipse client you must have configured MFA Server to have an AMS/IDCAMS Application Server. See MFAAMS Started Task JCL Procedure and Application Server Parameters for AMS/IDCAMS support for more information .

Parent topic: Preparing for configuration


Steps to activate z/Server

A running z/Server consists of at least two started tasks:

  • z/Server holder address space (TAURHLD)
  • z/Server STC scheduler address space (TAURISPF)
  • Zero or more z/Server STC user server address spaces (wtsouid, with "w" a configurable prefix and tsouid the TSO user ID of the client). See TSOE_JOBCHAR for more information on this configuration. They are started as IVPUSRT by the scheduler address space
  • Optional: z/Server CEA scheduler address space for CEA-launched TSO user address spaces (TAURCEA)
  • Optional: Zero or more CEA-launched TSO user address spaces (TSO user id)

The holder address space TAURHLD provides the necessary infrastructure and user administration control structures using a common access data space. It is non-swappable. It is also used to start and stop the scheduler and the user server address spaces.

The scheduler address space provides the requested client services or starts other z/Server user server address spaces to run a user specific ISPF application. There can be more than one scheduler running under the umbrella of the same holder address space.

A user server address space is started first to download the master configuration file to the Eclipse client and whenever the Eclipse client requests a specific REXX exec to be run. Each client can have more than one user server running for that TSO user ID.

A z/Server scheduler address space for CEA-launched TSO user address spaces (CEA scheduler in short) provides the services to start a TSO user address space. It is started when the Eclipse client calls the action “Launch ISPF” from zExplorer’s context menu in Remote Systems View, provided the port specified in the MVS Explorer settings under “ISPF launcher port” maps the parameter PORT specified in the CEA scheduler (CEASCHED) configuration.

The CEA-launched TSO user address space runs like any TSO address space under the user id of the connected user. The client communicates with this address space using the CEA scheduler and a z/OS USS message queue.

The holder can be started under MFA by specifying the ZSERVER FEATURE mainframe access parameter. Starting the holder under MFA results in improved performance. See Editing Mainframe Access Parameters for more information.

  • Defining a client connection to z/Server
  • Define Started Tasks to z/OS
Parent topic: Configuring z/Server feature support


Defining a client connection to z/Server

In order to test the connection to z/Server from an EDz client you must define a Micro Focus z/Server connection in the Remote Systems view:

  1. Click Define a connection to remote system.

    This opens the New Connection dialog box.

  2. Click Micro Focus z/Server.
  3. Click Next.

    You need to specify the z/Server connection information:

  4. In the Host name field, type the logical name or IP address of the z/OS system you want to connect to.
  5. In the Connection name field, type the connection name that will be listed in the Remote Systems view.

    Optionally, in the Description field, type a description for the connection.

  6. Click Next.

    This takes you to the Server Settings and Encoding step.

  7. In the Local Code Page list, select the code page which you want to use on the client side.
    Note: Currently, only UTF-8 is supported as the local code page.
  8. In the Remote Code Page list, select the code page which you want to use on the server side to represent a source file.

    A source file downloaded from the mainframe is translated using the code page specified by Remote Code Page and Local Code Page.

  9. In the Port field, type the port of the MFA server to which the z/Server installation is mapped by default.
    Note: Do not specify the port on which the z/Server in running.
  10. In the Scheduler Name field, leave the value as DEFAULT if you want to use the z/Server that your MFA server is mapped to by default.

    You only need to change this field if you want to use z/Server instance other than the one specified in the default mapping of your MFA server. To use another z/Server instance, type the name of the z/Server STC scheduler.

  11. Only check the Enable Backward Compatibility check box if you want to connect to a z/Server prior to 2.3 Update 1.

    After checking Enable Backward Compatibility:

    1. In the Port field, type the port number which the z/Server is running on.
    2. In the MFA Port field, type the port number which the MFA server is running on.
    3. In the ISPF Launcher Port filed, type the port number which the CEA server scheduler of the z/Server is running on.
  12. The CCI Key list is only relevant if the z/Server is configured to use SSL/TLS encryption. In this case, the CCI Key list contains all the SSL/TLS configurations defined in your local CCI.ini file for the port specified by the Port field. Select the SSL/TLS connection from the CCI Key list that you want to work with.
Parent topic: Steps to activate z/Server


Define Started Tasks to z/OS

  • Define started tasks to RACF and ACF2
  • APF authorizations
  • Define started tasks to WLM
  • Customizing the MFA Server address space JCL (MFA)
  • Customizing an STC scheduler address space JCL (TAURISPF)
  • Customizing a user server address space JCL (IVPUSRT)
  • Optional: Customizing a CEA-launched TSO user address space JCL (CEAPROC)
  • Configuring z/Server
  • Customizing GTF tracing
  • User authorizations
  • Enable model configuration
  • Optional customization
Parent topic: Steps to activate z/Server


Define started tasks to RACF and ACF2

Each of the started tasks needs to be defined to the security product. We recommend that you run all z/Server STCs using the same ID. Work done for the client is run using the TSO user ID credentials of the client (task level security). All user IDs to be used with z/Server need a valid OMVS segment (required by TCP/IP).

READ access to the z/Server datasets is needed.

Depending on your installation, there may be more authorization needed (see User authorizations).

Assuming that RACF is the security product, the definitions could look like this:

AU usrname DATA('z/SERVER Userid') NOPASSWORD DFLTGRP(grpname) OWNER(grpname) OMVS(AUTOUID HOME('/u/usrname'))

ALU usrname NOPASSPHRASE
RDEF STARTED TAURHLD.* STDATA(USER(usrname)) OWNER(grpname)
RDEF STARTED TAURISPF.* STDATA(USER(usrname)) OWNER(grpname)
RDEF STARTED IVPUSRT.* STDATA(USER(usrname)) OWNER(grpname)
SETR RACLIST(STARTED) REFRESH
ADDSD 'hlq.ZSERVER.**' OWNER(grpname) UACC(NONE)
PE 'hlq.ZSERVER.**' ACCESS(READ) CLASS(DATASET) ID(usrname)

The RACF definitions for a CEA scheduler could look like this:

RDEFINE TSOPROC CEAPROC OWNER(SYS1) UACC(NONE)
PE CEAPROC CLASS(TSOPROC) ACCESS(READ) ID(all-required-groups)
SETROPTS RACLIST(TSOPROC) REFRESH

If ACF2 is the security product, to allow READ access to the z/Server datasets, the equivalent definitions for class STARTED could look like this:

SET CONTROL(GSO)
INSERT STC.TAURHLD  LOGONID(usrname)
INSERT STC.TAURISPF LOGONID(usrname)
INSERT STC.IVPUSRT  LOGONID(usrname)  STCID(********)
F ACF2,REFRESH(ALL)

The holder address space administers the port range to be used for the scheduler and the user servers, but does not use them. The default port range specified in the configuration files that come with z/Server is 1100 to 1200. This port range needs to be opened in the firewall protecting the z/OS host system.

The scheduler address space listens for incoming requests from clients on the port designated as PORT in the scheduler configuration file. PORT=1111 is set as default. The scheduler assigns ports to different user servers from the port range defined for that scheduler (TSOE_FIRST_PORT .. TSOE_LAST_PORT).

Since the holder address space starts and stops the scheduler and stops user servers, and the scheduler address space starts and stops user servers, the associated user ID needs the appropriate access rights in the OPERCMDS class to these system commands.

Parent topic: Define Started Tasks to z/OS


APF authorizations

The data set hlq.ZSERVER.AUTHLIB must be APF authorized in the PARMLIB concatenation, for example, SYS1.PARMLIB(PROGxx).

Note: APF authorizations can be set dynamically with the following console command:
SETPROG APF,ADD,DSN=hlq.ZSERVER.AUTHLIB,SMS

or, if it is not an SMS managed data set:

SETPROG APF,ADD,DSN= hlq.ZSERVER.AUTHLIB,VOL=volser
Parent topic: Define Started Tasks to z/OS


Define started tasks to WLM

As a server, the importance of the MFA Server address space should be set below TCPIP but above the scheduler address space TAURISPF. This setting comes into play when MFA Server starts up and terminates or when commands are executed against the MFA Server address space.

The scheduler and the user server address spaces should have the same importance, with the user servers classified like any TSO user address space using the response time goal of TSO. All transactions executing within scheduler and user server are TSO transactions.

Keep in mind that these address spaces are STCs, so the classification must be done under the STC subsystem.

Parent topic: Define Started Tasks to z/OS


Customizing the MFA Server address space JCL (MFA)

The MFA Server address space MFA is used to install the SVC routine and to set up a common access data space that contains user administration control structures needed for communication.

The type 3 SVC routine is installed whenever the address space starts, and is deleted from the system SVC table when it is stopped.

Customize the sample JCL procedure that is used to start MFA Server. This is located in hlq.MFA.CNTL(MFA). You must uncomment the following four lines highlighted below:

//*--------------------------------
//* zServer Holder
//*--------------------------------
//*
//*SYSEXEC  DD DISP=SHR,DSN=&TAUQUAL..EXEC
//CONFXML  DD DISP=SHR,DSN=&DSNQUAL..CNTL(MFAXML)
//CONFOSR  DD DISP=SHR,DSN=&TAUQUAL..OSR(MFAOSR)
//*DSPPRT   DD SYSOUT=*,LRECL=255
//*SYSOUT   DD SYSOUT=*
//*SYSTSIN  DD DUMMY
Parent topic: Define Started Tasks to z/OS


Customizing an STC scheduler address space JCL (TAURISPF)

The z/Server scheduler task TAURISPF is responsible for the communication with a client and listens for incoming client requests on the port designated as LISTENER_PORT in the scheduler configuration file. The scheduler also defines a range of ports that are used, as needed, when a user server is started, and routes some of the incoming work to the appropriate user server address space. It is essentially a batch TSO address space. Configuring these ports is covered in Configuring z/Server.

Customize the sample hlq.ZSERVER.JCL(IVPISPFJ) and copy it to the PROCLIB concatenation and named as taurispf.

Verify and customize the high level qualifier defined for TAURHLQ, and also TCPDATA to make sure it specifies the correct TCPIP configuration data set:

//TAURISPF PROC
//TAURHLQ  SET  TAURHLQ=HLQ.ZSERVER
//TCPDATA  SET  TCPDATA=TCPIP.TCPDATA
//IVPISPF  EXEC PGM=IKJEFT01,PARM='TAURIP',
//       DYNAMNBR=200,REGION=0M,TIME=NOLIMIT
//STEPLIB  DD  DISP=SHR,DSN=&TAURHLQ..LOADLIB
//ZSRVAUTH DD  DISP=SHR,DSN=&TAURHLQ..AUTHLIB
//*SYSABEND DD  SYSOUT=*,DSN=&&SYSUDUMP
//SYSUDUMP DD  SYSOUT=*,DSN=&&SYSUDUMP
//SYSPRINT DD  SYSOUT=*,DSN=&&SYSPRINT
//SYSTSPRT DD  SYSOUT=*,DSN=&&SYSTSPRT
//ZCOTSPRT DD  SYSOUT=*,DSN=&&SYSTSPRT
//SYSTSIN  DD  DUMMY
//ZCOTSIN  DD  DUMMY
//*IPCONFIG DD  DISP=SHR,DSN=&TAURHLQ..CONFIG(IVPISPFJ)
//READER   DD  SYSOUT=(*,INTRDR)
//SYSEXEC  DD  DISP=SHR,DSN=&TAURHLQ..REXX
//SYSTCPD  DD  DISP=SHR,DSN=&TCPDATA
//*MAILHDR  DD  DISP=SHR,DSN=&TAURHLQ..SAMPLIB(IVPMHDR)
Note: Notice that the IPCONFIG DD statement is commented out. This must not be enabled if you are using the new XML configuration file.

The SYSTCPD DD statement has been added to provide information about the IP stack on your host to the started task.

DD statement MAILHDR names the sample dataset from which to copy the pattern for email notification addressees if email notification is configured. Email notification is intended to send an email to predefined recipients in case of an error situation. It requires that an SMTP server is available which forwards the generated emails.

Parent topic: Define Started Tasks to z/OS


Customizing a user server address space JCL (IVPUSRT)

A z/Server STC user server IVPUSRT is started by the scheduler address space to execute REXX execs or ISPF applications. It is essentially a two-step batch TSO address space. The first step executes under the general z/Server user ID and switches the security environment to the user ID of the client that had requested the user server to be started. The second step (the actual batch TSO address space) then uses this specific TSO user ID.

Customize the sample hlq.ZSERVER.JCL(IVPUSRT) and copy it to the PROCLIB concatenation and named as ivpusrt .

Verify and customize the high level qualifier defined for both TAURHLQ and ISPFHLQ, and also TCPDATA to make sure it specifies the correct TCPIP configuration data set. Make sure that the ISPF high level qualifier is ISF. Similar to a logon procedure, add all required libraries for things such as panels, messages, and REXX execs that are necessary to run the user’s required ISPF applications.

The initial REXX procedure IVPINIT1 must be located in the z/Server REXX dataset. This REXX exec should be customized by the installation to fit the installation's needs (see Optional customization).

Note: The dataset hlq.ZSERVER.REXX must be allocated using DDNAME SYSEXEC (not SYSPROC).
//TAURHLQ  SET TAURHLQ=HLQ.ZSERVER
//ISPFHLQ  SET ISPFHLQ=ISP
//TCPDATA  SET TCPDATA=TCPIP.TCPDATA
//*********************************************************************
//*    START TSO/E-ISPF-SESSION AS STARTED JOB
//*********************************************************************
//*  SET ACEE FOR USER
//*********************************************************************
//TAURSJOB EXEC PGM=TAURSJOB
//STEPLIB  DD DISP=SHR,DSN=&TAURHLQ..LOADLIB
//ZSRVAUTH DD DISP=SHR,DSN=&TAURHLQ..AUTHLIB
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//*IPCONFIG DD DISP=SHR,DSN=&TAURHLQ..CONFIG(IVPACEE)
//*********************************************************************
//*    START TSO/E-ISPF-SESSION BATCH
//*    MOVE TEMP ALLOCATIONS TO IVPINIT1 RPI 611619
//*********************************************************************
//IVPISPF  EXEC PGM=IKJEFT1B,PARM='%IVPINIT1',
//            DYNAMNBR=200,REGION=0M,TIME=NOLIMIT,COND=(4,LT)
//STEPLIB  DD DSN=&TAURHLQ..LOADLIB,DISP=SHR
//ZSRVAUTH DD DISP=SHR,DSN=&TAURHLQ..AUTHLIB
//*IPCONFIG DD DISP=SHR,DSN=&TAURHLQ..CONFIG(IVPUSR)
//SYSTCPD  DD DISP=SHR,DSN=&TCPDATA
//SYSEXEC  DD DSN=&TAURHLQ..EXEC,DISP=SHR
//         DD DSN=&TAURHLQ..REXX,DISP=SHR
//ISPPLIB  DD DSN=&TAURHLQ..PANELS,DISP=SHR
//         DD DSN=&ISPFHLQ..SISPPENU,DISP=SHR
//         DD DSN=ISF.SISFPLIB,DISP=SHR
//ISPSLIB  DD DSN=&TAURHLQ..SKELS,DISP=SHR
//         DD DSN=&ISPFHLQ..SISPSENU,DISP=SHR
//         DD DSN=ISF.SISFSLIB,DISP=SHR
//ISPMLIB  DD DSN=&ISPFHLQ..SISPMENU,DISP=SHR
//         DD DSN=ISF.SISFMLIB,DISP=SHR
//ISPTLIB  DD DSN=&ISPFHLQ..SISPTENU,DISP=SHR
//         DD DSN=ISF.SISFTLIB,DISP=SHR
//ISPLOG   DD SYSOUT=*,DCB=(RECFM=VA,LRECL=125)
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//ZCOTSPRT DD SYSOUT=*
//SYSTSIN  DD DUMMY
//ZCOTSIN  DD DUMMY
//SYSOUT   DD SYSOUT=*
//CEEAPI03 DD SYSOUT=*
//CEEREX30 DD SYSOUT=*
//ISPDPTRC DD SYSOUT=*
//         PEND

Temporary data set references have been removed from the above JCL and can now be found in the IVPINIT1 REXX procedure.

Note: Notice that the IPCONFIG DD statement is commented out. This must not be enabled if you are using the new XML configuration file.

The SYSTCPD DD statement has been added to provide information about the IP stack on your host to the started task.

Parent topic: Define Started Tasks to z/OS


Optional: Customizing a CEA-launched TSO user address space JCL (CEAPROC)

A z/Server user server started as a CEA-launched TSO user address space CEAPROC is started by the z/Server scheduler address space. It behaves like a foreground TSO address space running with the TSO user ID of the client user who requested the start of the user server. Terminal input and screen output is read from and written to the associated USS message queue.

Customize the sample hlq.ZSERVER.JCL(CEAPROC) and copy it to the PROCLIB concatenation and name as ceaproc.

Verify and customize the high level qualifier defined for TAURHLQ, and also TCPDATA to make sure it specifies the correct TCPIP configuration data set. Similar to a logon procedure, add all required libraries for things such as panels, messages, and REXX execs that are necessary to run the user's required ISPF applications.

The initial REXX procedure CEALOGON must be located in the z/Server REXX data set.

Note: The data set hlq.ZSERVER.REXX has to be allocated using DDNAME SYSEXEC (not SYSPROC).
//CEAPROC  PROC
//CEAPROC  EXEC PGM=IKJEFT01,DYNAMNBR=175,
//             PARM='%CEALOGON',TIME=120
//TAURHLQ  SET  TAURHLQ=hlq.ZSERVER
//TCPDATA  SET  TCPDATA=TCPIP.TCPDATA
//********************************************************************
//* Z/SERVER
//*********************************************************************
//STEPLIB  DD  DISP=SHR,DSN=&TAURHLQ..LOADLIB
//ZSRVAUTH DD  DISP=SHR,DSN=&TAURHLQ..AUTHLIB
//*IPCONFIG DD DISP=SHR,DSN=&TAURHLQ..CONFIG(CEAUSER)
//SYSTCPD  DD  DISP=SHR,DSN=&TCPDATA
//CEEREX30 DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//CEATSPRT DD SYSOUT=*
//ZCOTSPRT DD TERM=TS
//ZCOTSIN  DD TERM=TS
//READER   DD  SYSOUT=(*,INTRDR)
//MAINTASK DD SYSOUT=*
//T0000001 DD SYSOUT=*
//CMDTASK  DD SYSOUT=*
//SRVTASK  DD SYSOUT=*
//CEATASK  DD SYSOUT=*
//CEAISPF  DD SYSOUT=*
//LISTENER DD  SYSOUT=*
//*********************************************************************
//*      ADD YOUR OWN LOGON PROCEDURE HERE
//*      BUT KEEP ALL &TAURHLQ DATA SETS IN THE RIGHT PLACES
//*********************************************************************
//SYSUADS  DD  DISP=SHR,DSN=SYS1.UADS
//SYSLBC   DD  DISP=SHR,DSN=SYS1.BRODCAST
//SYSPROC  DD  DISP=SHR,DSN=ISP.SISPCLIB
//         DD  DISP=SHR,DSN=SYS1.SBLSCLI0
//SYSEXEC  DD  DISP=SHR,DSN=&TAURHLQ..EXEC
//         DD  DISP=SHR,DSN=&TAURHLQ..REXX
//         DD  DISP=SHR,DSN=ISP.SISPEXEC
//SYSHELP  DD  DISP=SHR,DSN=SYS1.HELP
//         DD  DISP=SHR,DSN=ISP.SISPHELP
//ISPMLIB  DD  DISP=SHR,DSN=ISP.SISPMENU
//         DD  DISP=SHR,DSN=SYS1.SBLSMSG0
//         DD  DISP=SHR,DSN=ISF.SISFMLIB
//         DD  DISP=SHR,DSN=&TAURHLQ..MSGS
//ISPEXEC  DD  DISP=SHR,DSN=ISP.SISPEXEC
//ISPLLIB  DD  DISP=SHR,DSN=&TAURHLQ..LOADLIB
//ISPPLIB  DD  DISP=SHR,DSN=ISP.SISPPENU
//         DD  DISP=SHR,DSN=&TAURHLQ..PANELS
//         DD  DISP=SHR,DSN=SYS1.SBLSPNL0
//         DD  DISP=SHR,DSN=ISF.SISFPLIB
//ISPSLIB  DD  DISP=SHR,DSN=&TAURHLQ..SKELS
//         DD  DISP=SHR,DSN=ISP.SISPSLIB
//         DD  DISP=SHR,DSN=ISP.SISPSENU
//         DD  DISP=SHR,DSN=ISF.SISFSLIB
//         DD  DISP=SHR,DSN=SYS1.SBLSKEL0
//ISPTLIB  DD  DISP=SHR,DSN=ISP.SISPTENU
//         DD  DISP=SHR,DSN=SYS1.SBLSTBL0
//         DD  DISP=SHR,DSN=ISF.SISFTLIB
//ISPCTL1  DD  DISP=NEW,UNIT=SYSALLDA,SPACE=(CYL,(1,1)),
//             DCB=(LRECL=80,BLKSIZE=800,RECFM=FB)
//ISPCTL2  DD  DISP=NEW,UNIT=SYSALLDA,SPACE=(CYL,(1,1)),
//             DCB=(LRECL=80,BLKSIZE=800,RECFM=FB)
//ISPLST1  DD  DISP=NEW,UNIT=SYSALLDA,SPACE=(CYL,(1,1)),
//             DCB=(LRECL=121,BLKSIZE=1210,RECFM=FBA)
//ISPLST2  DD  DISP=NEW,UNIT=SYSALLDA,SPACE=(CYL,(1,1)),
//             DCB=(LRECL=121,BLKSIZE=1210,RECFM=FBA)
//SDSFMENU DD  DSN=ISF.SISFPLIB,DISP=SHR
//         PEND

Parameter P1 have been added to support parameters required for startup to the CEA user server:

  • P1 is an internal parameter the CEA user server uses. This must match the CEA_LOGONPROC of the CEA user server.

The SYSTCPD DD statement has been added to provide information about the IP stack on your host to the started task.

The name of the job step in the JCL procedure must match the same value you entered as the CEA_LOGONPROC in the configuration of either the Unified scheduler or the CEA scheduler. Failure to do so results in the User Server starting, but the client is unable to connect to it.

For example, if you have CEA_LOGONPROC="MYPROC" in your configuration then it would look like:

//MYPROC   PROC
//MYPROC   EXEC PGM=IKJEFT01,DYNAMNBR=175,
//             PARM='%CEALOGON,TIME=120
//TAURHLQ  SET  TAURHLQ=hlq.ZSERVER
//TCPDATA  SET  TCPDATA=TCPIP.TCPDATA
...
Parent topic: Define Started Tasks to z/OS


Configuring z/Server

Once you have reviewed and modified all of the JCL you can move on to configuring the z/Server feature itself. The configuration for z/Server is stored in XML format and is in hlq.MFA.CNTL(MFAXML).

<Configuration
                     TCP_PORT="2020"
                     NETWORK_ID="DDINET1"
                     LU62_APPLID="MFM62ACB"
                     APPLID_PASSWORD="MFM62PSW"
                     TRACING="0"
                     ORGANIZATION="YOUR_COMPANY_NAME"
                     SVC_NO="NNN"
                     DSP_TOKEN="TAURSERV"
                     IPSTACK="TCPIP"
>
...
    <!-- Application Server address space definitions  -->
    <ApplicationServers>
        <!-- z/Server Scheduler -->
        <Scheduler   SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200"
                     FIRST_PORT="1201" LAST_PORT="1249"
                     USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
                     DEFAULT="1"
        >
            <UserServer CCSID="037" />
        </Scheduler>
    </ApplicationServers>
...
</Configuration>

The aspects of z/Server's behavior that you want to modify determine the parts of the XML that you need to edit.

  • General configuration
  • Scheduler configuration
  • Troubleshooting the z/Server configuration
Parent topic: Define Started Tasks to z/OS


General configuration

The following general configuration parameters apply to both unified and individual schedulers:

SVC_NO
Change the SVC number from NNN to the required value for your host. The default is 238.
IPSTACK
Specifies the name of the IP stack used for processing.
DSP_TOKEN
If you are running multiple z/Server instances DSP_TOKEN must be different from any other token used by any other MFA Server holder task. Make sure that the MAXCADS definition in the IEASYSxx member of the parmlib concatenation specifies a sufficiently high value to allow for the creation of that common access data space.

Use the z/OS health checker to see how many common access data spaces are in use. If the value is too low, the data space creation will fail. The value in IEASYSxx can only be increased via IPL.

See Configuration reference for more information on configuration parameters.

Parent topic: Configuring z/Server


Scheduler configuration

The scheduler combines the functionality of for STC and CEA into one started task.

For example:

<Scheduler
        SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200" FIRST_PORT="1201"
        LAST_PORT="1249" USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
        DEFAULT="1"
>
       <UserServer CCSID="037" />
</Scheduler>
Note: If you have change the name of the STC scheduler JCL procedure (TAURISPF) in the PROCLIB you must change the SCHEDULER_NAME value to match.

If you have change the name of the STC user server JCL procedure (IVPUSRT) in the PROCLIB you must change the USER_SERVER_JOBNAME value to match.

Default Scheduler

By specifying DEFAULT="1" in a scheduler you are instructing the MFA Server that this is the Scheduler to use when the AWM client has entered the value of "DEFAULT" in the Scheduler Name field of the New Connection dialog box. Only one scheduler should be marked as the default.

You can have multiple Schedulers defined and you can specify their names in the Scheduler Name field of the New Connection dialog box.

If you type DEFAULT in the Scheduler Name field of the New Connection dialog box, and there is no default defined you will get the following message saying there is no default scheduler defined:

No default z/Server Scheduler configured.

If you specify a Scheduler Name that does not exist you get an error message saying that a matching scheduler could not be found:

Unable to find matching server details for z/Server Scheduler named Scheduler Name.

Legacy Clients

For clients supplied with versions of Enterprise Developer earlier than 3.0 the scheduler is unable to determine what type of user server the client requires. By default, the scheduler attempts to start an STC user server. You can specify the default user server to be started by the scheduler by adding the DEF_USRSRV_MODE parameter with the value of STC or CEA.

For CEA

To configure the scheduler for CEA, you need to add the following to the configuration:

CEA_LOGONPROC
This points to the logon procedure to be used when a CEA-launched TSO user address space is started. See Optional: Customizing a CEA-launched TSO user address space (CEAPROC) for information on how to configure this logon procedure.
CEA_ACCOUNT
This must be set to a valid accounting number that all TSO users that use this scheduler have access to. The accounting number used must be defined in general resource class ACCTNUM. All TSO users that use the CEA Scheduler.

For example:

<Scheduler
        SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200" FIRST_PORT="1201"
        LAST_PORT="1249" USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
    CEA_LOGONPROC=”CEAPROC” CEA_ACCOUNT=”ACCT#”
>
       <UserServer CCSID="037" />
</Scheduler>
Note: If you change the name of the CEA user server JCL procedure (CEAPROC) in the PROCLIB you must change the CEA_LOGONPROC value to match.

Optionally, if you have uncommented MAILHDR in the scheduler procedure, you need to add the MAIL_NOTIFY="1" attribute to the scheduler section.

For example:

<Scheduler
        SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200" FIRST_PORT="1201"
        LAST_PORT="1249" USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
    MAIL_NOTIFY=”1”
>
       <UserServer CCSID="037" />
</Scheduler>

See Configuration parameters reference for more information on the available parameters for a scheduler address space.

See Configuration reference for more information on the parameters applicable to a CEA scheduler.

Parent topic: Configuring z/Server


Troubleshooting the z/Server configuration

You can use the following diagnostic tools and information to troubleshoot issues with the z/Server configuration:

Mainframe Access Configuration Utility

The z/Server Configuration Utility makes it easier to download, validate and edit a configuration file. This utility is available from the Product Updates section of the Micro Focus SupportLine Web site. To download the utility, once you have logged in to the SupportLine site, navigate to the latest version of Enterprise Developer and select z/Server Configuration Utility.

Error messages

Use the information in any error messages to determine what the possible issues might be.

For example, trying to start the MFA Server holder process with an invalid XML results in the MFA Server holder failing to start and you receive a message indicating there is a problem with the XML validation. For example:

XCO0021E  10:50:59.846 XML Validation has failed. Reason = 8800. Error offset into XML document = 00000020.

Such messages include a reason code and an error offset:

Reason
The Reason code indicates a specific problem with the XML code - check the section Reason codes listed by value in IBM's "z/OS V2R1.0 XML System Services User's Guide and Reference" (SA38-0681).
Error offset
The location in hexadecimal from the start of the XML document where the error occurred.

The error message quoted earlier is caused by the following invalid XML code:

<Configuration
                     TCP_PORT="2020"
                     NETWORK_ID="DDINET1"
                     LU62_APPLID="MFM62ACB"
                     APPLID_PASSWORD="MFM62PSW"
                     TRACING="0"
                     ORGANIZATION="YOUR_COMPANY_NAME"
                     SVC_NO="NNN"
                     DSP_TOKEN="TAURSERV"
                     IPSTACK="TCPIP"
>
...
    <!-- Application Server address space definitions  -->
    <ApplicationServers>
        <!-- z/Server Scheduler -->
        <Scheduler   SCHEDULER_NAME="TAURISPF" LISTENER_PORT="1200"
                     FIRST_PORT="1201" LAST_PORT="1249"
                     USER_SERVER_JOBNAME="IVPUSRT" CCSID="037"
                     DEFAULT="1"
        >
            <UserServer CCSID="037" />
        </Scheduler>
    </ApplicationServers>
...
</Configuration>

Use the reason code and the offset shown in this message to determine the cause of the error. In this example, the offset points to a location in the first line of the XML configuration file. Here there is an invalid attribute value in the <Configuration> section - SVC_NO="NNN" is invalid because SVC_NO must be a numeric value.

XML validation tools

You can use any third-party XML validation tool to check the XML configuration file against the XML schema file available in hlq.ZSERVER.CONFIG(MFASCHEM).

Parent topic: Configuring z/Server


Customizing GTF tracing

If SupportLine asks for a GTF trace of z/Server and your installation does not have its own customized procedure, then customize the hlq.ZSERVER.JCL(IVPGTF) and copy it to the PROCLIB concatenation. z/Server writes GTF trace user records with number 3E8.

//TAUGTF  PROC M=IVPGTF,
//             CYL=100,
//             PROG=AHLGTF
//IEFPROC EXEC PGM=&PROG,
//             PARM='MODE=EXT,DEBUG=NO,TIME=YES,NOPROMPT',
//             REGION=0M
//IEFRDER DD   DSNAME=HLQ.GTFTRACE.&M..D&LYYMMDD..T&LHHMMSS,
//             SPACE=(CYL,(&CYL),,CONTIG),
//             RECFM=VB,
//             DISP=(NEW,CATLG)
//SYSLIB  DD   DSNAME=HLQ.ZSERVER.DATA(&M),DISP=SHR

Make sure that the IEFRDER data set can be allocated without RACF errors.

Activation of GTF for user record 3E8 alters the way z/Server writes messages. There is no need to set a specific trace level; all events are now traced. The trace output is written to a GTF trace data set, no longer to the JESx job log. Also, not all messages from trace level 0 will appear in the JESx job log.

Note: If more than one z/Server is running, starting GTF trace for user record 3E8 will automatically set the trace level to full tracing for all servers that are running. To avoid JESx spool problems, the trace level of the unaffected address spaces should be reduced to the desired value x using the operator command
F <scheduler|userserver>,TRACE,LEVEL=x
Parent topic: Define Started Tasks to z/OS


User authorizations

As stated above, all users need an OMVS segment for TCPIP to work correctly. In addition, the scheduler task and the holder task must be authorized in class OPERCMDS to issue the following operator commands:

Function/Configuration Parameter | Type | Command
START/STOP/CANCEL | MVS command | START <scheduler> START <userserver> STOP <scheduler> STOP <userserver> CANCEL <scheduler> CANCEL <userserver>
PORTCHECK=1 (Port check function) | MVS command | DISPLAY TCPIP
TSOE_CLEANUP=1 | JESx command | JES2: $C JES3: *F
Note: If the configuration parameters listed above are not in use (which means they are set to 0), the appropriate commands are not executed and do not need to be authorized.

If the JESSPOOL RACF class is active, a RACF general resource profile of the following format must be defined for each user:

<NODENAME>.<STCUSR>.<USERSERVER>.**

where:

<NODENAME>
is the installation’s node name
<STCUSR>
is the started task user ID of the user server
<USERSERVER>
is the job name of the user server (TSO user ID plus TSOE_JOBCHAR)

Every TSO user must have UPDATE access to this profile allowing every TSO user to allocate spool datasets that begin with a high level qualifier equal to the STC user ID.

Example: Assuming the node id is NODE, the user ID of the z/Server started tasks is TAUUSR, TSOE_JOBCHAR is Z, and the user ID is USR123, then the RACF general resource profile should be defined as follows:

NODE.TAUUSR.ZUSR123.**

If the installation protects the use of Extended MCS consoles, then every scheduler address space must be authorized to activate an EMCS console. The naming convention for these consoles is aaaaxxxx with aaaa the first to fourth character of the system name and xxxx the address space ID of the address space establishing the EMCS console in hexadecimal notation.

Parent topic: Define Started Tasks to z/OS


Enable model configuration

Using an Eclipse client, ISPF applications can be modeled. For more information, see Attaching ISPF tools in the Workflow Manager Configuration Guide. To enable modeling, the master configuration data set hlq.ZSERVER.MASTER must be customized:

********************************************************
* System and Application Workflow Model Definitions
* Do not change the key words:
*    System:
*    Appl:
*    Conf:
*    Version:
*    INFO:
*    User:
*
* Enter an unique logical name for this mainframe system
*
System: XXXXXXXXXX
*
* MVS PROJECTS EXAMPLE APPLICATION
*
User:
* application name
Appl: MVS Projects Sample Application
* location of the application configuration file
Conf: mvs:'hlq.ZSERVER.XML(MVSCONF)'
* application version number
Version: 2.3.1
* process information
Property: MVS_PROP_STATIC_SYSLIB_ASM=SYS1.MACLIB;SYS1.MODGEN;&userid..BANKVSAM.MACLIB
Property: MVS_PROP_STATIC_SYSLIB_COBOL=&userid..BANKVSAM.COPYLIB
Property: MVS_PROP_STATIC_SYSLIB_PLI=&userid..STAFF.INCLUDE
INFO:
* end of application definition. do not delete this line
EndAppl:
EndUser:
*
* AWM dialog sample application
*
User:
* application name
Appl: ISPF Dialogs
* location of the application configuration file
Conf: MVS:'hlq.zserver.XML(TAUDIALG)'
* application version number
Version: 1.4
* process information
INFO:
* end of application definition. do not delete this line
EndAppl:
EndUser:

Specify a system name after "System:", for example, LPAR1. Replace every occurrence of hlq.zserver after "Conf:" with the high level qualifier chosen for the installation.

There is a REXX exec in hlq.ZSERVER.EXEC named TAUZCAPP which reads the master configuration data set and sends the content to the client in formatted form. Replace hlq.ZSERVER after "sysdsn=" with the high level qualifier chosen for the installation.

When a client logs on using a new connection for the first time, the master configuration is sent from z/Server to the client and shows up in the Application Explorer view. This is done in the background, and a user server address space is started to send this master configuration. On subsequent logons (when the master configuration is already available), no user server is started. A user server address space is only started when a client request requires an ISPF environment, for example, when an AWM ISPF tool is called.

Parent topic: Define Started Tasks to z/OS


Optional customization

  • ISPF user profile
  • Usage in a parallel sysplex
Parent topic: Define Started Tasks to z/OS


ISPF user profile

z/Server allows more than one user server per TSO user to be run in parallel. Each user server needs its own exclusive ISPF environment. This implies the allocation of an ISPF user profile dataset. The allocation of the user profile dataset is done in the sample REXX exec IVPINIT1 and should be customized to adhere to the installation's standards.

ISPF user profile allocation is done as follows:

  • DD statement ISPPROF is allocated to a temporary dataset. If a z/Server ISPF profile dataset named userid.TAUZCISP.PROFILE already exists for the TSO user, the content of this ISPF profile is copied using IEBGENER to a temporary dataset allocated under the ISPPROF DD statement.
  • ISPF is started and control is passed to REXX exec IVPINIT2.
  • When the ISPF session terminates, control returns to REXX exec IVPINIT1, and the temporary ISPF profile is copied back to z/Server profile dataset userid.TAUZCISP.PROFILE.
  • The temporary ISPF profile dataset is deleted.

We recommend that you allocate the temporary ISPF profile dataset to an SMS managed temporary dataset pool, which is automatically deleted according to installations' standards. In that case, the deletion of the temporary ISPF profile dataset in the REXX IVPINIT1 can be omitted.

Parent topic: Optional customization


Usage in a parallel sysplex

z/Server itself does not use any sysplex services. It relies on the ability to connect to an IP address specified using a TCPIP header. This is normally done under the covers by an Eclipse client:

  1. The Eclipse client asks for "Connect" to an IP address (or symbolic name) using a port specified in the client. This port corresponds to the PORT parameter that the scheduler address space listens on. As a response, z/Server sends back the IP address of the system that this particular scheduler address space runs on.
  2. The next transaction initiated from the client (which includes the TCPIP function connect - different from the function "Connect" in 1.) uses this IP address for further communication and (IP-)connection.
  3. As long as the network is set up in such a way that usage of this IP address will guarantee connection to the same host system, the first connection used (from the Eclipse function "Connect") z/Server functions without problems.

Note that it is mandatory to have a one-to-one relation between the IP address and the system name. A configuration where an IP address can resolve to different systems (for load balancing, for instance) is not supported. (See also VIPA).

Parent topic: Optional customization


z/Server startup and installation verification

Now you can start z/Server. By issuing the start MFA Server command, MFA Server then begins to start and automatically starts any schedulers defined in the XML configuration file.

Example starting the MFA Server task:

 S MFA

By default, during MFA Server startup z/Server automatically starts any schedulers defined in the XML configuration file. If you want to disable this and start the schedulers independently of the MFA Server holder, add the AUTOSTART="0" XML attribute to the <Configuration /> section of your XML configuration file.

  • Verifying z/Server feature support startup
  • Verifying scheduler startup
  • Verifying user server startup
  • Verifying CEA user servers (optional)
Parent topic: Configuring z/Server feature support


Verifying z/Server feature support startup

In addition to the regular JESx DD statements, the job log of a running MFA Server address space contains the DD names MAINTASK and SYSTSPRT.

DD MAINTASK shows if the data space was created correctly and the SVC routine installed. The MFA Server address space MFA initializes z/Server feature support correctly when HLD0002I is the last message.

 HLD0090I  15:35:24.879 Holder called as subroutine
                        Function.: S
                        Parms....: ,,
 HLD0001I  15:35:24.916 zServer holder task 04000000 startup
 HLD0009I  15:35:25.039 TSO-Environment successful created
                        A(Comand-Processor-Parameter-List) : 009B9CD0
 HLD0078I  15:35:25.040 Read   of NT-Pair E9E2D9E500F864804040404040404040 ended with RC 00000004 (hex).
 ZCF0036I  15:35:25.040 Parameter for z/Server: ,,
 ZCF0038I  15:35:25.044 zServer configuration utility is using
                        Token ......... not specified
                        Config key .... not specified
 ZCF0060I  15:35:25.100 Using configuration style XML
 ZCF0058I ========================================================================
          Completing configuration TAURISPF
          ========================================================================
 ZCF0024W  15:35:25.100 Server is limited server due to specification of TSOE_STCID
 ZCF0025W  15:35:25.100 The following configuartion parameters are not used due to specification od TSOE_STCID
                        TSOE_CLEANUP
                        TSOE_JOBPREFIX
                        TSOE_JOBSEARCH
 ZCF0058I ========================================================================
          Completing configuration IVPUSR
          ========================================================================
 ZCF0024W  15:35:25.100 Server is limited server due to specification of TSOE_STCID
 ZCF0025W  15:35:25.100 The following configuartion parameters are not used due to specification od TSOE_STCID
                        TSOE_CLEANUP
                        TSOE_JOBPREFIX
                        TSOE_JOBSEARCH
 ZCF0058I ========================================================================
          Completing configuration CEAPROC
          ========================================================================
 ZCF0024W  15:35:25.100 Server is limited server due to specification of TSOE_STCID
 ZCF0025W  15:35:25.100 The following configuration parameters are not used due to specification of TSOE_STCID
                        TSOE_CLEANUP
                        TSOE_JOBPREFIX
                        TSOE_JOBSEARCH
 HLD0069I  15:35:25.100 Holder task configuration
                        Size data space specified....:       262144      Blocks
                        Size data space required.....:          168      Blocks
                        Delay .......................:          500      csecs
                        Trace level..................:            0
                        Modify limit.................:            1
                        Size RESTAB in blocks........:          160
                        Max. # of entries in RESTAB..:         5120
                        Reply........................: NO
 HLD0018I -----------------------------------------------------------------------
          Installing User-SVC 0238
          -----------------------------------------------------------------------
 HLD0019I  15:35:25.103 User-SVC 0238 successfully installed.
                        Pgm : TAURAUTH EpAddr : 8E2CC8A8
 HLD0021I -----------------------------------------------------------------------
          Creating Common-Dataspace TAURSERV
          -----------------------------------------------------------------------
 HLD0003I  15:35:25.103 Creating Dataspace
                        Dataspace-Name    :  TAURSERV
                        Dataspace-Size    :        262144 Blocks
                        Dataspace-StgKey  :  00
 HLD0025I  15:35:25.103 Function Create Dataspace     ended successful
 HLD0025I  15:35:25.103 Function Create Alet          ended successful
 HLD0025I  15:35:25.103 Function Create Name/Token    ended successful
 HLD0025I  15:35:25.103 Function Create Name/Token 2  ended successful
 HLD0033I  15:35:25.103 Server Information
                        Lowest  port over all Servers   :         5151
                        Highest port over all Servers   :         5199
                        Maximum numbers of    Servers   :            1
 HLD0035I  15:35:25.103 Initializing data space for user administration
 HLD0076I  15:35:25.103 Resource table size increased to         5120 entries
 HLD0048I -----------------------------------------------------------------------
          Starting Server
          -----------------------------------------------------------------------
 HLD0049I  15:35:25.116 Starting server TAURISPF
 HLD0002I  15:35:25.125 zServer holder task ready for commands
Parent topic: z/Server startup and installation verification


Verifying scheduler startup

If the MFA Server holder has successfully started it will also have started your scheduler. You can now verify that the scheduler has started correctly.

In addition to the regular JESx DD statements and SYSTSPRT/ZCOTSPRT, the job log of a running scheduler address space should contain the following DD names:

DD Name | Function
MAINTASK | (LE) Messages from MAINTASK.
LISTENER | (LE) Listener for client requests.
CMDTASK | (LE) Messages from CMDTASK; contains command output.
SRVTASK | (LE) Messages from SRVTASK.
MSGTASK | (LE) Task to queue messages to a USS message queue.
T000000x, x=1..NUMTCB | (LE) Messages from T000000x, the worker tasks.
MAILBOX | If email notification is configured.

A number of messages reference these DD statements as "LE message files".

A scheduler address space has started successfully when the hardcopy log shows:

+TAU0067I  zServer startup completed for TAURISPF  for JESx and ASID nnnn

To verify that the scheduler is responding to work requests you can customize and submit the verification job hlq.ZSERVER.JCL(IVPVERI):

//TAURHLQ  SET TAURHLQ=hlq.ZSERVER
//JOBLIB   DD DISP=SHR,DSN=&TAURHLQ..LOADLIB
//*-----------------------------------------------------------------*
//*- Install Verification Job                                      -*
//*-                                                               -*
//*- Valid Selects                                                 -*
//*- ===========================================================   -*
//*- 1                    EXEC REXX IVPREXXE  (echo rexx)          -*
//*-----------------------------------------------------------------*
//TAURIVP  EXEC PGM=TAURIVP
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSIN    DD *
IVP_SELECT = 1
IVP_Server = 'nnn.nnn.nnn.nnn'
IVP_Port   = 1200;
IVP_COMPAT = 2
IVP_IPNAME = 'TCPIP'
;
/*
You need to do the following to customize hlq.ZSERVER.JCL(IVPVERI):
  • Add a valid job card.
  • Specify the data set prefix defined (TAURHLQ).
  • Specify the correct IP address of the host system (IVP_Server).
  • Specify the port the scheduler address space is listening on (IVP_Port).
  • Specify the name of the IP stack used (IVP_IPNAME).

The IVPVERI output should look like this:

IVP0002I Selection code for IVP was :   1
         EXEC IVPREXXI (echo REXX)
IVP0003I call to zServer ended with  RC :       0
===================================================================
Answer from zServer is       203 Bytes long.
===================================================================
00000000   000000CB 4CD4E2C7 40C6C1C3 C9C47E7F   *    <MSG FACID="*
00000010   D3C9C37F 40D4E2C7 D5D67E7F F0F0F1F0   *LIC" MSGNO="0010*
00000020   7F40E2C5 E5C5D9C9 E3E87E7F C57F6E40   *" SEVERITY="E"> *
00000030   F0F97AF4 F87AF3F7 4BF0F8F9 40D38983   *09:48:37.089 Lic*
00000040   85958385 40A58996 9381A389 96957A40   *ence violation: *
00000050   E38889A2 40A28599 A5859940 83819540   *This server can *
00000060   969593A8 40828540 A4A28584 40A38899   *only be used thr*
00000070   96A48788 40819540 E3C1E4D9 E4E24083   *ough a licenced *
00000080   93898595 A34B4040 40404040 40404040   *client.         *
00000090   40404040 40404040 40404040 40404040   *                *
000000A0   40404040 40404040 40404040 40404040   *                *
000000B0   40404040 40404040 40404040 40404040   *                *
000000C0   40404040 404C61D4 E2C76E00 00000000   *     </MSG>     *

If you receive a return code of 49 in message IVP0003I, check if numbering was inadvertently turned on in the member from which this job was submitted. If it was, turn off numbering.

Parent topic: z/Server startup and installation verification


Verifying user server startup

To verify the user server startup you must start a user server, as these are only started on demand. Instructions on starting a user server are below.

We strongly recommended that you execute the following installation verification procedure for a z/Server user server before trying to connect from an Eclipse client. This procedure verifies that the configuration in the z/OS system is correct, without possible added complications from the network configuration.

The start of a z/Server user server can be tested by executing the REXX procedure TAU located in the REXX library. This is limited to support of port numbers up to a length of four characters.

Type EX in front of member TAU to execute the REXX exec. The "zServer Host -Driver" panel should open:

The "zServer Host-Driver" Panel

Verify that the IP stack used is TCPIP. If it is not, change the name in the last line under TCPName to the correct IP stack name. Press Enter. A message will confirm that another IP stack name is now used.

Set the IP address (IP-Addr) to the "home" IP address of the IP stack used.

Set the field Port to the listener port configured in the configuration dataset of the z/Server scheduler task.

Type "addusrv" (without the quotes) in the line named Command or select the point and shoot field AdduSrv in the panel header. A popup panel is shown prompting for the TSO password of the TSO user ID used. After entering the correct password and submitting the information, a z/Server user server should be started. Address space creation takes some time, so after a while, a response like the following is displayed:

Answer from Server for Message   1 is       204 Bytes long.
====================================================================

00000000   000000CC 4CD4E2C7 40C6C1C3 C9C47E7F   *...¦<MSG FACID="*
00000010   E2D3D97F 40D4E2C7 D5D67E7F F0F0F2F3   *SLR" MSGNO="0023*
00000020   7F40E2C5 E5C5D9C9 E3E87E7F C97F6E40   *" SEVERITY="I"> *
00000030   F1F27AF1 F37AF0F1 4BF0F7F8 40E3E2D6   *12:13:01.078 TSO*
00000040   61C540A2 8599A585 9940E9E2 D6C6D1D2   */E server Wxxxxx*
00000050   404040A6 89A38840 D1D6C2C9 C440E2E3   *   with JOBID ST*
00000060   C3F0F8F3 F6F14086 969940A4 A2859940   *C08361 for user *
00000070   E2D6C6D1 D2404040 40A2A482 9489A3A3   *xxxxx    submitt*
00000080   85844B40 40404040 40404040 40404040   *ed.             *
00000090   40404040 40404040 40404040 40404040   *                *
000000A0   40404040 40404040 40404040 40404040   *                *
000000B0   40404040 40404040 40404040 40404040   *                *
000000C0   40404040 40404C61 D4E2C76E            *      </MSG>    *

If the response is not as shown above, then something went wrong during the start of the user server and you need to determine what that was:

  • Check the JCL of the user server started task (IVPUSRT). There may be a JCL error in this procedure (e.g. a mistyped dataset name).
  • Check for RACF problems in the hardcopy log.
  • Check the MAINTASK DD statement in the user server joblog for problems and act accordingly.

Now you can confirm that the user server has started correctly. The joblogs can be found under the JOB names defined, by default, as the character W prefixed to your TSO userid. In addition to the regular JESx DD statements and SYSTSPRT/ZCOTSPRT, the job log of a running scheduler address space should contain the following DD names. Note that a user server address space has two MAINTASK JESx DD statements, one for each step in the user server startup process:

DD Name | Function
MAINTASK | (LE) Messages from MAINTASK from step one of user server startup.
MAINTASK | (LE) Messages from MAINTASK from step two of user server startup.
LISTENER | (LE) Listener for client requests.
CMDTASK | (LE) Messages from CMDTASK; contains command output.
SRVTASK | (LE) Messages from SRVTASK.
T0000001 | (LE) Messages from T0000001, the worker task.
ISPLOG | (ISPF) Log file.

A number of messages reference these DD statements as "LE message files".

A scheduler address space has started successfully when the hardcopy log shows the following, where XXXX is your TSO user ID:

+TAU0067I  zServer startup completed for WXXXX  for JESx and ASID 005E

If the user server was started successfully, a "Logoff" command should be sent afterwards to stop the user server again. Type "logoff" on the command line or select the point and shoot field Logoff in the panel header. The password is prompted for again. When the request is submitted with the correct password, a response like this should be displayed:

Answer from Server for Message   1 is       124 Bytes long.
======================================================================

00000000   0000007C 4CD4E2C7 40C6C1C3 C9C47E7F   *...§<MSG FACID="*
00000010   E2D3D97F 40D4E2C7 D5D67E7F F0F0F2F6   *SLR" MSGNO="0026*
00000020   7F40E2C5 E5C5D9C9 E3E87E7F C97F6E40   *" SEVERITY="I"> *
00000030   F1F77AF0 F57AF5F3 4BF8F4F1 40E2A396   *17:05:53.841 Sto*
00000040   97408396 94948195 84408696 9940A4A2   *p command for us*
00000050   859940E2 D6C6D1D2 40404040 81838385   *er xxxxx    acce*
00000060   97A38584 4B404040 40404040 40404040   *pted.           *
00000070   40404040 40404C61 D4E2C76E            *      </MSG>    *
Parent topic: z/Server startup and installation verification


Verifying CEA user servers (optional)

Make sure you also test the start of a CEA-launched TSO address space by changing the field Port to the listener port of the CEA scheduler and repeating the procedure for verifying a user server. Output similar to the one below in the hardcopy log indicates successful initialization of the CEA-launched TSO user server. Make sure the user server is terminated again using the logoff command as before.

$HASP373 userid    STARTED
IEF125I userid - LOGGED ON - TIME=16.01.44
+ISPWB000  Client requested ISPF session initialization 585
           Userid: userid   ASIDX: 006D
           Message Queue: 0000655407 CCSID: 00037
+TAU0001I  zServer userid    02030000  startup Tuesday   , 11 Mar 2014
16:01:49.04
+TAU0067I  zServer startup completed for userid    for JES2 and ASID 006D

If this message does not appear in hardcopy log, problem determination will become very difficult. Use the logon procedure specified by CEA_LOGONPROC and attempt to logon to TSO to make sure there are no JCL or ISPF errors during dataset allocation. The initial REXX exec CEALOGON is not executed, so no ISPF profile dataset is available. At the TSO READY prompt, use the following command to allocate the ISPF profile (with the correct naming conventions for the installation):

alloc dd(ISPPROF) dsn(userid.ISPF.ISPPROF)

Then call ISPF. If the logon procedure is correct, the ISPF primary option menu will be shown. Otherwise, correct any errors and repeat.

Parent topic: z/Server startup and installation verification


Optional: Adaptations to the IBM Developer for System z RSED installation

Customers who install the Micro Focus AWM feature into an IBM Developer for z Systems (IDz) client have a technology choice between the previously described z/Server and IBM Developer for z Systems RSED. The RSE daemon (RSED) is shipped with an IDz installation.

If RSED is used as server technology, the following changes have to be made to the RSED configuration.

  • ISPF Client Gateway
  • Master configuration
  • Host installation verification
Parent topic: Configuring z/Server feature support


ISPF Client Gateway

Allocate the REXX data set delivered with z/Server V2R2M01 to the ISPF Client Gateway using DDNAME SYSEXEC or SYSPROC.

Allocate the SKELS data set delivered with z/Server V2R2M01 to the ISPF Client Gateway using DDNAME ISPSLIB.

Detailed information on how to configure the ISPF.conf file can be found in the IDz Host Configuration Guide.

If new data sets are added to ISPF.conf, make sure that all users of the ISPF Client Gateway (IDz users) have at least READ access to the data sets allocated by the client gateway.

ISPF.conf is a USS file, for example:

Parent topic: Optional: Adaptations to the IBM Developer for System z RSED installation


Master configuration

To work with AWM applications, a master configuration file must exist.

REXX procedure TAULAPPL must be customized to contain the data set name of the master configuration data set. The default name is hlq.SYSTEM.CONFIG.

The REXX TAULAPPL can be found on the installation EXEC library.

Change the following line in TAULAPPL according to the high level qualifier used for the installation:

sysdsn= 'hlq.SYSTEM.CONFIG'                 /* master config file */

A sample master configuration data set has been delivered as hlq.ZSERVER.MASTER. The contents of this master configuration data set contain a sample application “PDS Explorer”:

********************************************************************
*
* TAURUS System and Application Definition
*
* Do not change the key words:
*    System:
*    Appl:
*    Conf:
*    Version:
*    INFO:
*
* Change Activity:
*   date    name    comment
*
********************************************************************
*
* TAURUS SYSTEM
*
* Enter a unique logical name for this mainframe system
*
System: TAURUS_Custom_System
*
* TAURUS PDS EXPLORER EXAMPLE APPLICATION
*
User:
* application name
Appl: PDS Explorer
* location of the application configuration file
Conf: mvs:'hlq.TAURUS.XML(PDSECONF)'
* application version number
Version: 1.4
* process information
INFO:
* end of application definition. do not delete this line
EndAppl:
EndUser:

You can customize the reference to the PDS Explorer XML application model and enter a unique system name, for example, your logical LPAR name.

An AWM user needs READ access to the master configuration file and to all XML files referenced; the AWM administrator needs UPDATE access.

Parent topic: Optional: Adaptations to the IBM Developer for System z RSED installation


Host installation verification

Access to the Master Configuration File

No AWM client installation is needed to verify the AWM host installation.

Call the REXX procedure TAULAPPL from the ISPF command menu:

TSO EX ‘hlq.TAURUS.EXEC(TAULAPPL)

Or, if the TAURUS REXX library is allocated to SYSPROC or SYSEXEC

TSO TAULAPPL

The terminal output looks like this:

TAU System: TAURUS_Custom_System
TAU Appl: PDS Explorer
TAU Conf: mvs: 'hlq.TAURUS.XML(PDSECONF)'
TAU Version: 1.4
TAU INFO:
TAU RC: 0

Verify ISPF Client Gateway

Start IDz and navigate to the “Remote projects perspective”.

Select Launch TSO in the context menu for the “MVS Files” entry:

Launching the IDz TSO command window

The IDz TSO command window opens.

Enter TAUTODBG and press Enter. The following message can be seen:

Message RC=20 invalid command means that the REXX procedure TAUTODBG was not found. In this case, verify that the AWM REXX procedures are allocated through the ISPF Client Gateway using the SYSPROC or SYSEXEC DDNAME.

Parent topic: Optional: Adaptations to the IBM Developer for System z RSED installation


Console Commands

  • Introduction
  • Console Commands
Parent topic: Mainframe Access Installation Guide


Introduction

Mainframe Access provides a number of console commands that you can use to control execution and display the operational status of Mainframe Access. To use these commands, you must be authorized to use z/OS system console commands. Most of the commands are variants of the z/OS Modify (F) command, with the general format:

F <your-procedure-name>,<command-text>

where:

<your-procedure-name>
The name of your Mainframe Access startup JCL. See Mainframe Access Data Sets for more information.
<command-text>
See Console Commands for more information on the commands available.

To use the z/OS Start (S) command to start Mainframe Access:

S <your-procedure-name>

To use the z/OS Stop (P) command to stop Mainframe Access:

P <your-procedure-name>

You can enter the commands in any of the following ways:

  • From an z/OS system console.
  • Using an interface that allows the entry of z/OS system commands, such as IBM's TSO/ISPF SDSF (System Display and Search Facility).
Parent topic: Console Commands


Console Commands

  • General Mainframe Access Server commands
  • Mainframe Access z/Server feature commands
Parent topic: Console Commands


General Mainframe Access Server commands

  • Start
  • Stop
  • TRACE ON and TRACE SHORT
  • REFRESH ACCESSLIST
  • DISPLAY LU
  • DISPLAY TCPSTATUS
  • DISPLAY CONVERSATION
  • C CONV=id
  • FLUSH XDBOUT
  • RESET TIMEOUT=n
  • SET TIMEOUT=n
Parent topic: Console Commands


Start

Starts the Mainframe Access task. Mainframe Access automatically starts the Mainframe Access Data Connect server, MFAS, during initialization.

Here is an example of a Start command and the response:

15:49:32.45 CSIRLW1  00000290  S MFA
15:49:32.47 STC05579 00000090  $HASP100 MFA ON STCINRDR
15:49:32.55 STC05579 00000290  IEF695I START MFA WITH JOBNAME MFA IS ASSIGNED TO USER RWITEK, GROUP DEVELOP
15:49:32.55 STC05579 00000090  $HASP373 MFA  STARTED
15:49:32.55 STC05579 00000090  IEF403I MFA - STARTED - TIME=15.49.32
15:49:32.85 STC05579 00000090  MFM0014I: Mainframe Access V3.01 (ga) for YOUR_COMPANY_NAME
15:49:32.85 STC05579 00000090  MFM0066I: Address space type is CTLRGN
15:49:32.86 STC05579 00000090  MFM0057I: GTF user record id (eid) is 00E9
15:49:32.86 STC05579 00000090  MFM0012I: TCP port number is 1503
15:49:32.86 STC05579 00000090  MFM0013I: Admin port number is 1504
15:49:32.86 STC05579 00000090  MFM0047I: DSS maximum shared public files is 10
15:49:32.86 STC05579 00000090  MFM0055I: DSS scan interval is 2 minutes
15:49:32.86 STC05579 00000090  MFM0054I: SMF recording is off, record id is zero or invalid
15:49:32.87 STC05579 00000090  MFM0063I: MFA Direct is active
15:49:32.87 STC05579 00000090  MFM0064I: MFA Direct number of processing tasks is 5
15:49:33.16 STC05579 00000090  MFMDS052I CA/PanValet Ready
15:49:33.21 STC05579 00000090  MFMDS055I MCG/RPC feature inactive
15:49:33.22 STC05579 00000090  MFMDS001I DSS Server Ready
15:49:36.92 STC05579 00000090  MFM0001I: Mainframe Access V3.01 (ga) is active
15:49:37.00 STC05580 00000090  $HASP100 MFAS ON STCINRDR
15:49:37.06 STC05580 00000090  $HASP373 MFAS  STARTED
15:49:37.06 STC05580 00000090  IEF403I MFAS - STARTED - TIME=15.49.37
15:49:37.23 STC05580 00000090  MFA302I.MFAS.MFARSC00 / ATTACHING VTAM PROCESSOR
15:49:37.24 STC05580 00000090  MFA303I.MFAS.MFARSC00 / MFA/MVS V3.01 - PTF 2001PTF6 COPYRIGHT (C)
                               1987-2003 MICRO FOCUS INTERNATIONAL LTD.
15:49:37.24 STC05580 00000090  MFA110I.MFAS.MFAFSQ00 / VTAM PROCESSOR ACTIVE USING VTAMAPPL MFA62ACB
Parent topic: General Mainframe Access Server commands


Stop

Stops the Mainframe Access task. Mainframe Access automatically stops the Mainframe Access Data Connect server, MFAS, during shutdown. Shutdown may take anywhere from 30 seconds to a few minutes, depending on the level of activity in the system.

Here is an example of a Stop command and the response:

16:44:18.52 CSIRLW1  00000290  P MFA
16:44:21.52 STC05579 00000290  P MFAS
16:44:21.53 STC05580 00000090  MFA112I.MFAS.MFAFSQ00 / VTAM PROCESSOR HAS TERMINATED
16:44:21.68 STC05580 00000090  MFA317I.MFAS.MFARSC00 / HAS BEEN TERMINATED
16:44:21.69 STC05579 00000090  MFMDS005I DSS Server shutdown
16:44:21.70 STC05580 00000090  IEF404I MFAS - ENDED - TIME=16.44.21
16:44:21.70 STC05580 00000090  $HASP395 MFAS  ENDED
16:44:32.77 STC05579 00000090  MFM0011I: Mainframe Access shutdown completed
16:44:32.82 STC05579 00000090  IEF404I MFA - ENDED - TIME=16.44.32
16:44:32.82 STC05579 00000090  $HASP395 MFA  ENDED
Parent topic: General Mainframe Access Server commands


TRACE ON and TRACE SHORT

Activates detailed tracing of all Mainframe Access activity. Trace output is directed to the destination (SYSPRINT, GTF or CONSOLE) specified by the TRACE parameter during Mainframe Access startup. For more information about these options see the entry for the TRACE parameter in the section Editing Mainframe Access Parameters in the chapter Configuration. For a tip about viewing trace data sent to SYSPRINT interactively see the FLUSH XDBOUTcommand description

Here is an example of a TRACE ON command and the response:

F MFA,TRACE ON
MFM0015I: MFM0025I: Trace set to data level on

The TRACE SHORT command activates the same detailed tracing as does the TRACE ON command. The SHORT option limits the display of send data, receive data and storage areas to 256 characters. This can be useful in reducing the amount of trace output, particularly when the message sizes are large.

Here is an example of a TRACE SHORT command and the response:

F MFA,TRACE SHORT
MFM0015I: MFM0025I: Trace set to data level on
Parent topic: General Mainframe Access Server commands
Related information
Editing Mainframe Access Parameters
FLUSH XDBOUT


REFRESH ACCESSLIST

Directs Mainframe Access to re-read the access list from the currently active access list data set (the access list identified by the //XDBACC DD statement in the Mainframe Access startup JCL). You can update the access list by adding, removing or updating PERMIT, REJECT and ADMUSER lines, as described in the section Editing Access List Definitions in the chapter Configuration. When your updates are complete, use REFRESH ACCESSLIST to replace the currently active access list with your updated list without stopping and restarting Mainframe Access.

Here is an example of a REFRESH ACCESSLIST command and the response:

F MFA,REFRESH ACCESSLIST
MFM0015I: Refresh Access List has completed
Parent topic: General Mainframe Access Server commands
Related information
Editing Access List Definitions


DISPLAY LU

Displays information about the target servers which Mainframe Access has successfully connected to by establishing one or more LU6.2 sessions in response to client requests. Target servers are known to Mainframe Access by their SNA LU name or APPLID.

Here is an example of a DISPLAY LU command and the resulting display:

F MFA,DISPLAY LU
MFM0015I:  ***************************************************
MFM0015I:  *                   PLU Status                    *
MFM0015I:  ***************************************************
MFM0015I:
MFM0015I:  ******* Partner LU Status
MFM0015I:  LU Name..........LUDB27R
MFM0015I:     Mod Entry........IBMRDB
MFM0015I:     Status...........Active
MFM0015I:  LU Name..........MFA62ACB
MFM0015I:     Mod Entry........#INTER
MFM0015I:     Status...........Active
Parent topic: General Mainframe Access Server commands


DISPLAY TCPSTATUS

Displays basic TCP/IP configuration information from the Mainframe Access parameters (port number, company name and connection backlog) followed by the information displayed by the DISPLAY LU and DISPLAY CONVERSATION commands.

Here is an example of a DISPLAY TCPSTATUS command and the resulting display:

F MFA,DISPLAY TCPSTATUS
MFM0015I:  ***************************************************
MFM0015I:  *                   TCP Status                    *
MFM0015I:  ***************************************************
MFM0015I:
MFM0015I:  Server Port Number.......1503
MFM0015I:  Web Server Port Number...1504
MFM0015I:  OID....................YOUR_COMPANY_NAME
MFM0015I:  Number of Backlogs.......5
MFM0015I:  ******* Partner LU Status
MFM0015I:  LU Name..........LUDB27R
MFM0015I:     Mod Entry........IBMRDB
MFM0015I:     Status...........Active
MFM0015I:  LU Name..........MFA62ACB
MFM0015I:     Mod Entry........#INTER
MFM0015I:     Status...........Active
MFM0015I:  ******* Conversation Status
MFM0015I:  Conversation ID..1AA14028
MFM0015I:     Conv Address.....1AC79968
MFM0015I:     Alloc Address....1A928DC0
MFM0015I:     Task Address.....1AA4CE28
MFM0015I:     Conv Status......Active
MFM0015I:     TCP/IP Status....Send
MFM0015I:     User Id..........CSIRLW1
MFM0015I:     Target LU........LUDB27R
MFM0015I:     Peer IP address..10.10.11.130
MFM0015I:     Socket Number....9
MFM0015I:     Start Time.......07/17/03 15:10:32
MFM0015I:     LUW Id...........DDINE.MFM62ACB.B9BBC4F618400001
MFM0015I:     Packets Sent.....14
Parent topic: General Mainframe Access Server commands
Related information
DISPLAY LU
DISPLAY CONVERSATION


DISPLAY CONVERSATION

Displays detailed information about every active conversation between Mainframe Access and the target servers.

Here is an example of a DISPLAY CONVERSATION command and the resulting display:

F MFA,DISPLAY CONVERSATION
MFM0015I:  ***************************************************
MFM0015I:  *               Conversation Status               *
MFM0015I:  ***************************************************
MFM0015I:
MFM0015I:  ******* Conversation Status
MFM0015I:  Conversation ID..1AA14028
MFM0015I:     Conv Address.....1AC79968
MFM0015I:     Alloc Address....1A928DC0
MFM0015I:     Task Address.....1AA4CE28
MFM0015I:     Conv Status......Active
MFM0015I:     TCP/IP Status....Send
MFM0015I:     User Id..........CSIRLW1
MFM0015I:     Target LU........LUDB27R
MFM0015I:     Peer IP address..10.10.11.130
MFM0015I:     Socket Number....9
MFM0015I:     Start Time.......07/17/03 15:10:32
MFM0015I:     LUW Id...........DDINE.MFM62ACB.B9BBC4F618400001
MFM0015I:     Packets Sent.....14
MFM0015I:     Packets Rcv'd....27
MFM0015I:  Conversation ID..1ABFF2E0
MFM0015I:     Conv Address.....1ACD0968
MFM0015I:     Alloc Address....1A928BA0
MFM0015I:     Task Address.....1AA4CA78
MFM0015I:     Conv Status......Active
MFM0015I:     TCP/IP Status....Send
MFM0015I:     User Id..........CSIRLW1
MFM0015I:     Target LU........MFA62ACB
MFM0015I:     Peer IP address..10.10.11.130
MFM0015I:     Socket Number....13
MFM0015I:     Start Time.......07/17/03 15:11:40
MFM0015I:     LUW Id...........DDINET1.MFM62ACB.B9BBC538B9410001
MFM0015I:     Packets Sent.....4
Parent topic: General Mainframe Access Server commands


C CONV=id

Cancels a specific conversation. Theid parameter is a conversation identifier of eight hexadecimal characters as shown in the information displayed by DISPLAY CONVERSATION and DISPLAY TCPSTATUS commands. Canceling a conversation ends the LU6.2 conversation to the target server and releases the LU6.2 session for use by other conversations. It also disconnects the client by closing the client socket associated with the conversation and cancels the DDF thread if the conversation partner is DB2.

Here is an example of the CANCEL CONVERSATION command that cancels the second conversation shown in the DISPLAY CONVERSATION example:

F MFA,C CONV=1ABFF2E0
MFM0015I: Cancel Command accepted
Parent topic: General Mainframe Access Server commands


FLUSH XDBOUT

Flushes trace data and operational messages to the //XDBOUT DD SYSOUT data set. Operational data is written to XDBOUT during normal operation; trace data is written to XDBOUT only when tracing is switched on and the trace destination is SYSPRINT. The FLUSH command causes any partially filled buffer to be written to the SYSOUT data set, making the output available for browsing. This can be helpful when you are testing and trying to view trace data interactively as the test progresses.

Here is an example of a FLUSH XDBOUT command and the response:

F MFA,FLUSH XDBOUT
MFM0015I: Flush XDBOUT completed
Parent topic: General Mainframe Access Server commands


RESET TIMEOUT=n

Changes the TIME OUT FOR CONNECTION parameter value without you having to stop and restart Mainframe Access. The n parameter is the number of minutes that a client connection can remain idle before the connection will be broken and Mainframe Access resources dedicated to the client will be released. Resources that are released when an idle client is disconnected include allocated storage, TCP/IP resources and LU6.2 conversations to target servers such as DB2, IMS, CICS and Mainframe Access Data Connect. Specify 0 (zero) to disable the client timeout feature and allow unlimited idle time.

If you use the RESET TIMEOUT command to establish a new timeout value, rather than SET TIMEOUT, both the Mainframe Access timeout and any Mainframe Access client timeout remain in effect. The connection partner (Mainframe Access client or Mainframe Access) having the smaller timeout value initiates the disconnection first.

Here is an example of a RESET TIMEOUT command and the response:

F MFA,RESET TIMEOUT=30
MFM0015I: Timeout parameter reset to 30
Parent topic: General Mainframe Access Server commands


SET TIMEOUT=n

Changes the TIME OUT FOR CONNECTION parameter value without you having to stop and restart Mainframe Access. The n parameter is the number of minutes that a client connection can remain idle after which the connection will be broken and Mainframe Access resources dedicated to the client will be released. Resources that are released when an idle client is disconnected include allocated storage, TCP/IP resources and LU6.2 conversations to target servers such as DB2, IMS, CICS and Mainframe Access Data Connect. Specify 0 (zero) to disable the client timeout feature and allow unlimited idle time.

If you use the SET TIMEOUT command to establish a new timeout value, rather than RESET TIMEOUT, then when a Mainframe Access client subsequently starts up, Mainframe Access' connection timeout is disabled, and only the inactivity timeout period specified by the Mainframe Access client is in effect.

Here is an example of a SET TIMEOUT command and the response:

F MFA,SET TIMEOUT=20
MFM0015I: Timeout parameter set to 20
Parent topic: General Mainframe Access Server commands


Mainframe Access z/Server feature commands

  • Starting and stopping the z/Server feature
  • Starting and stopping a z/Server scheduler address space
  • Display commands for TSO information
  • Diagnostic commands
  • REXX commands
  • Administrative commands
Parent topic: Console Commands


Starting and stopping the z/Server feature

To starts the z/Server feature:

F MFA,ZSRV:{HSTART|HSTOP}

To restart the z/Server feature:

F MFA,ZSRV:HRESTART
Parent topic: Mainframe Access z/Server feature commands


Starting and stopping a z/Server scheduler address space

To start and stop a z/Server scheduler use the following syntax:

F MFA,ZSRV:{START|STOP},SCHED=<scheduler>

With the keyword START, a scheduler address space is started. It does not need to be defined in the MFAXML configuration member. The character string <scheduler> is used as the name of an address space to be started.

The keyword STOP terminates the named scheduler by first terminating all active user servers belonging to that scheduler and then the scheduler task itself.

  • Stopping a specific user server address space
  • Stopping all user servers for a Specific user ID
  • Stopping all user servers for a Specific Scheduler address space
Parent topic: Mainframe Access z/Server feature commands


Stopping a specific user server address space

To stop a specific user server address space, the port that user server listens to must be known. The port can be determined by using the command:

F <scheduler>,TSO,DISPLAY,USER=ALL

The command response in CMDTASK will have one line with message SLR0036I for every user that is currently using scheduler services. The last column shows the port nnnnn the address space listens on. Then the user server address space can be terminated:

F MFA,ZSRV:STOP,PORT=<nnnnn>
Parent topic: Starting and stopping a z/Server scheduler address space


Stopping all user servers for a Specific user ID

To stop all user servers for a specific user ID use the following syntax:

F MFA,ZSRV:STOP,USER=<tsouid>

All user servers for that <tsouid> are stopped across all schedulers.

Note: The name of the user server address space is prefixed by TSOE_JOBCHAR while this command requires only the TSO user ID to be specified.
Parent topic: Starting and stopping a z/Server scheduler address space


Stopping all user servers for a Specific Scheduler address space

To stop all user servers for a specific scheduler address space, use the following syntax:

F MFA,ZSRV:STOP,SCHED=<scheduler>,USERONLY

All user server address spaces for the named scheduler are terminated.

Parent topic: Starting and stopping a z/Server scheduler address space


Display commands for TSO information

To get information about TSO users address the scheduler address space with the keywords TSO and DISPLAY:

F <scheduler>,TSO,DISPLAY,{ STATS|VPOOL}

The STATS parameter of the DISPLAY command shows statistics of actions done in response to client requests.

The VPOOL parameter of the DISPLAY command shows the variable pool contents.

  • Display TSO statistics
  • Display VPOOL
Parent topic: Mainframe Access z/Server feature commands


Display TSO statistics

F <scheduler>,TSO,DISPLAY,STATS

results in the following output in the CMDTASK DD statement of the scheduler address space:

SLR0040I ===============================================
         Server Statistics
         ===============================================
SLR0041I Submit      Count .........             0 times
         Stop        Count .........             7 times
         Communicate Count .........             1 times
         Error       Count .........             0 times

The lines in SLR0041I have the following meaning:

Column | Meaning
Submit count | Number of times any user server address space was started.
Stop count | Number of times any user server address space was stopped.
Communicate count | Number of IP messages scheduled to the user server address space for processing (i.e. number of client requests handled in that user server).
Error | Number of errors during processing.
Parent topic: Display commands for TSO information


Display VPOOL

F <scheduler>,TSO,DISPLAY,VPOOL

results in the following output in the CMDTASK DD statement of the scheduler address space:

SPR0011I Pool-Address      : 2FB7EF00
         Pool-Size         :         4096
         Pool-Freespace    :         3973 Bytes
         No of Variables   :            5 Bytes
         Variable-Pool-Information
=========================== Pool Content =============================
         Var-Typ     Var-Name    Var-Content
======================================================================
SPR0013I  SYS         CLASS      0
SPR0013I  SYS         JPREFIX    W
SPR0013I  SYS         SCMSPATH   1
SPR0013I  SYS         SCMSTAT    X
SPR0013I  SYS         SCMSREXX   MX0RSC01
Parent topic: Display commands for TSO information


Diagnostic commands

To get information about special areas in either a scheduler address space or user server address spaces, address the address space concerned with the keyword DUMP:

F <scheduler|userserver>,DUMP,{CONFIG|SVCD|AREA=ALL|ADDR=<addr>,LEN=<length>}

The CONFIG parameter of the DUMP command enables you to see the current configuration of the address space.

The SVCD parameter of the DUMP produces an SVC dump of the address space titled "zServer SVCDUMP".

Certain or all areas of an address space are dumped using the parameter AREA.

  • Configuration Dump
  • SVC Dump
  • Important storage areas
  • Selected storage areas
  • Display data space information
  • Setting IPTRACE level
  • Turn Off LE Error Handling
Parent topic: Mainframe Access z/Server feature commands


Configuration Dump

F <scheduler|userserver>,DUMP,CONFIG

writes the current configuration to the CMDTASK DD statement.

Parent topic: Diagnostic commands


SVC Dump

F <scheduler|userserver>,DUMP,SVCD

writes a standard SVCD dump. Such a dump could also be taken using a regular MVS DUMP command.

Parent topic: Diagnostic commands


Important storage areas

F <scheduler|userserver>,DUMP,AREA=ALL

writes all information z/Server deems relevant storage areas to DD statement CMDTASK of the address space. These areas include the TAUCA (the main z/Server control block) and control blocks named SUBTASK, one for each of the NUMTCB worker tasks.

Parent topic: Diagnostic commands


Selected storage areas

F <scheduler|userserver>,DUMP,ADDR=xxxxxxxx,LEN=yyy

writes the storage content starting at address xxxxxxxx in length yyy to DD statement CMDTASK of the address space. Keep in mind that the only areas dumped are those that z/Server owns, in other words, this command cannot be used to show the content of all storage allocated in the address space.

Parent topic: Diagnostic commands


Display data space information

The holder task allocates and manages a common access data space (CADS). The following command displays the information in this data space:

F MFA,ZSRV:DISPLAY,DSP,{FORMAT|DUMP}

In order to use this command, the holder task must contain a DD statement:

//DSPPRT   DD  SYSOUT=*,LRECL=255

The output for this display command is written to DSPPRT. If necessary, you might need to scroll to the extreme right to see the full output.

Sub parameter DUMP writes the unformatted storage areas from the data space, when using the keyword FORMAT the information is written in human readable form. Below is an example of a user entry:

Userid   JobName  JobId    SYS  Port  L F1 F2 F3 F4 F5 JP  CRP
--------------------------------------------------------------
user1    Vuser1   STCTIMEO syst 01215 M 00 80 80 00 00 00 0006
user2    Vuser2   STC04711 syst 01216 M 00 60 80 00 00 00 0008

Ip-Addr-Client  Ip/Port Scheduler     Creator  ClientId Asid
---------------------------------------------------------------
nnn.nnn.nnn.nnn nnn.nnn.nnn.nnn  1111 TAURISPF 00000003 004C
nnn.nnn.nnn.nnn nnn.nnn.nnn.nnn  1111 TAURISPF 00000006 0037

Start-Time     LastCmd LastCmd-Time   Last Timeout
----------------------------------------------------
mm/dd hh:mm:ss Modify  07/22 hh:mm:ss mm/dd hh:mm:ss
mm/dd hh:mm:ss Modify  07/22 hh:mm:ss mm/dd hh:mm:ss

Column JOBID contains a valid JESx job ID when a user server is running and listening on the port specified in column PORT. The (not valid) JESx job ID of STCTIMEO is set either when a user server had terminated (for instance due to inactivity - timeout) or when a client logged on but did not need to start a user server yet. This is called deferred logon. Once the client requests a service that can only run in a user server, that user server is "restarted" using the indicated port.

Parent topic: Diagnostic commands


Setting IPTRACE level

The IPTRACE level is set using the configuration parameter IPTRACE at startup. It is recommended to run at the lowest possible trace level. IPTRACE can be changed dynamically using the following command:

F MFA,ZSRV:TRACE,LEVEL=x
F <scheduler|userserver>,TRACE,LEVEL=x

where x is a positive integer between 0 and 6. Zero denotes no tracing, 6 is full tracing. Every subsequent trace level includes all lower trace levels.

DD statement CMDTASK (for scheduler and user server) or MAINTASK (for the holder address space) show confirmation:

F <scheduler>,TRACE,LEVEL=4
IPC0066I  12:27:46.579 Trace level changed to            4

Full tracing in a highly loaded z/Server system can generate a large amount of output data and can lead to JESx spool problems.

Parent topic: Diagnostic commands


Turn Off LE Error Handling

When a problem occurs, z/Server creates a dump in DD statement ZCOMDUMP. When z/Server relies on LE recovery, then LE might write a CEEDUMP. In severe cases an SVC dump is written.

The command

F <scheduler|userserver>,RECOVERY,{ON|OFF}

can be used to turn of LE error handling. If there is a SYSUDUMP/SYSABEND/SYSMDUMP DD statement in the JCL, such a dump would get written instead of a CEEDUMP.

Note: Switch off recovery only if requested by SupportLine.
Parent topic: Diagnostic commands


REXX commands

When a REXX exec is executing in either a user server or a scheduler address space, the following REXX commands are available, addressing the REXX exec environment (see SA22-7790-xx: TSO/E REXX Reference):

f <scheduler|userserver>,REXX,{HI|HT|RT|TS},SUBTASK={x|ALL}

The abbreviations stand for

  • HI = Halt Interpretation
  • HT = Halt Typing
  • RT = Resume Typing
  • TS = Trace Start

Parameter subtask specifies the number of the worker task (T000000x). There are at most NUMTCB worker tasks. Specifying ALL would address all worker tasks simultaneously.

Parent topic: Mainframe Access z/Server feature commands


Administrative commands

The following administrative commands are available for day-to-day operations:

F <scheduler>,TSO,DELETE,USER=user
F <scheduler|userserver>,SPFDEQ,DSN=<datasetname>[,mem=<member>]
F MFA,ZSRV:TRACE,LEVEL=x
F <scheduler|userserver>,TRACE,LEVEL=x
F <scheduler|userserver>,RECOVERY,{ON|OFF}
F MFA,DISPLAY,DSP,{FORMAT|DUMP}
F <scheduler|userserver>,REFRESH,PGM=nn

They are mostly used in error scenarios.

  • Delete a TSO User in user administration
  • Releasing the SPFEDIT serialization ENQ
  • Port skip
  • Refresh a load module
Parent topic: Mainframe Access z/Server feature commands


Delete a TSO User in user administration

It is possible that a user server address space terminated without first doing clean-up in the user administration control structures. This can happen if the address space was forced (MVS FORCE command) and no address space related clean-up ran. In this case the command:

F <scheduler>,TSO,DELETE,USER=userid

enables unconditional removal of the TSO user ID from the user administration control structures to free the entries and the port the user server address space was listening on. The CMDTASK DD statement of the scheduler address space shows:

SLR0039W  13:53:19.557 User USERID  deleted.

If the specified user is not found in the user administration control structures, the following message is issued:

F <scheduler>,TSO,DELETE,USER=ALL
SLR0038W  13:53:08.239 User ALL      not found. Delete command ignored.
Note: This command will unconditionally remove the specified user ID from the control structures, even if the client is currently working normally and no problem had occurred before. That means that the client/user server cannot work further without causing other problems. The user server address space also cannot terminate anymore without manual intervention (it must be cancelled):
+SLR0092E  14:11:40.508 User servers with Timeout_Action=STOP must be
started with POLICY=1 (Started Jobs). Timeout is ignored.
Parent topic: Administrative commands


Releasing the SPFEDIT serialization ENQ

When a client starts to edit a member of a partitioned dataset, z/Server locks that member against simultaneous edit from a 3270 TSO user by serializing against the resource SPFEDIT/data_set_name(member_name). That ENQ is held by the command task of the scheduler address space the user server belongs to.

If for some reason the client does not finish the edit process, the member stays locked. In the past another client used the Dequeue function from the context menu for the dataset member to release someone else's serialization. To reduce the integrity exposure of this (client) function, the following command can be used:

F <scheduler|userserver>,SPFDEQ,DSN=<datasetname>,MEM=<member>

It will release the ENQ that protects against parallel updates of the same dataset / member by different users. The CMDTASK DD statement will contain the following messages acknowledging deletion of the resource:

F <scheduler>,SPFDEQ,DSN=DATASET.NAME,MEM=MEMBER
SLR0044I  08:46:21.693 Dequeue for Major-Name SPFEDIT  and Minor-Name DATASET.NAME                                MEMBER
SLR0046I  08:46:21.694 Dequeue successful
Warning: Only use this command if you have made sure that the original owner will not edit the dataset or member any further. Otherwise you risk the data integrity of your datasets.
Parent topic: Administrative commands


Port skip

When a user server address space had allocated a port and does not terminate properly or port ranges were invalidly defined, then it can happen that a port is not available to a newly started user server address space. If that port was the first in the range of the scheduler, this could mean that no user server could get started anymore. With port skip active (PORTCHECK="1" set in the scheduler configuration parameters), z/Server tests the availability of the port. If it is already in use by someone, the message:

+SLR0055E  [001] Port [002] is not available.

is issued, followed by:

+SLR0135S  [001] Port [002] for z/Server scheduler [003] locked because port was not available.

In this context, "port is not available" means that TCPIP returned a response of "the port is in use and has the state LISTEN". There is an entry in the user administration control structures of z/Server for every port defined to the scheduler. The entry that was not available is now marked as LOCKED and will not be used any longer to allocate conversations with a client. This can be displayed by using the command:

F MFA,ZSRV:display,dsp,format

IN the DD named DSPPRT of the MFA Server task the following output can be found:

--------------------------------------
Userid   JobName  JobId    SYS    Port
--------------------------------------
user     jobname  jobid    system nnnnn

If a user server has stalled and not terminated and hence still has the port allocated, it needs to get terminated, probably via an operator force arm or force command. That will make the port available for reuse. The port is still in a "locked" state in the user administration part of z/Server, however. It needs to be unlocked manually using the command:

F <scheduler>,TSO,UNLOCK,PORT=nnnnn

This cleans up the LOCKED state of the port entry, and the port can be used again by the scheduler.

If the port was not allocated to a stalled user server, then the system administrator needs to determine who has the port allocated (for example, using the netstat command). There is probably some sort of definition error in the port ranges for this scheduler/MFA Server holder that needs to get corrected. If ports were defined incorrectly to the scheduler/MFA Server holder, the scheduler/MFA Server holder will need to be restarted with the corrected definitions.

If you only unlock the port in the user administration without first making sure that it really is available to be allocated again, port skip will immediately issue messages SLR0055E and SLR0135S again and relock the port in the user administration control structures.

Parent topic: Administrative commands


Refresh a load module

If SupportLine provided a Patch Update that would need a restart of z/Server, and customer support also specified that the load modules affected can be refreshed,

F <scheduler|userserver>,REFRESH,PGM=nn

with nn a positive integer between 02 and 99 allows reloading the load module and installing the Patch Update without restarting z/Server.

Note: It is not possible to refresh all load modules running in a z/Server address space.
Parent topic: Administrative commands


Mainframe Access Messages

Mainframe Access and the z/OS operating system use messages to document both normal and abnormal conditions while Mainframe Access is running. The z/OS system log, the Mainframe Access job log and the Mainframe Access SYSOUT data sets are all possible destinations for important messages about Mainframe Access operation. You should already be familiar with z/OS system messages.

  • Mainframe Access Server Messages
  • Status Codes and Error Messages
Parent topic: Mainframe Access Installation Guide


Mainframe Access Server Messages

Some Mainframe Access messages are directed to system consoles as specified by the ROUTE Mainframe Access configuration parameter. Other messages are directed to the job log for the started task or to the XDBOUT file (or both). If you experience problems with Mainframe Access operation, it is important that you review the various message destinations for information that may help you diagnose the problem. This section includes an explanation of each of these messages, ordered by message number.

  • Mainframe Access Operational Messages Format
  • Mainframe Access Messages
  • Data Set Services Messages
  • MFA Direct Messages
  • Data Connect Messages
  • Drag and Drop Error Messages
    Error messages relating to Drag and Drop are prefixed MFDAS.
Parent topic: Mainframe Access Messages


Mainframe Access Operational Messages Format

Mainframe Access operational messages are of the form:

mm/dd/yy hh:mm:ss.t taskname taskid MFMnnnna text

or

mm/dd/yy hh:mm:ss.t taskname taskid MFMDSnnna-text

where

mm/dd/yy | indicates the date when the message was issued.
hh:mm:dd.t | indicates the time when the message was issued.
taskname | is the name of the Mainframe Access task that issued the message.
taskid | is a two hexadecimal digit task identifier that helps to uniquely identify the Mainframe Access task for tasks that share a common task name. For instance, task name XDBMFADM processes Mainframe Access Direct client requests and there may be several instances of this task, each managing the work of a different subset of client connections. When examining XDBOUT trace messages for a specific client, trace messages from other clients and their processing tasks may be interleaved with the trace messages for the client that is of interest. The taskid value helps to identify the messages associated with a particular task.
DS | indicates that the message was produced by the Data Set Services (DSS) component of Mainframe Access, which provides all file allocation and record access services.
nnnn | is an integer in the range 0001 through 9999
a | is I if the message is for information only, or E if the message indicates an error condition
text | is the error message text

Messages may be issued that do not have the MFMnnnna or MFMDSnnna message prefix. These messages are diagnostic and/or trace messages that are not documented in this messages section. They are intended for use by Product Support.

Parent topic: Mainframe Access Server Messages


Mainframe Access Messages

MFM0001I: Mainframe Access version (service) is active

Issued when Mainframe Access initialization completes. version identifies the Mainframe Access product version and service indicates the current maintenance level that has been applied to Mainframe Access.

MFM0002I: listener socket number is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This message identifies the socket number n that has been allocated for listening and accepting the client connections.

MFM0003I: getsockopt return code is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. n is the return code from the TCP/IP getsockopt call and a value of zero indicates that startup is proceeding normally.

A non-zero value may indicate a problem. Refer to your TCP/IP provider's socket API return code documentation for an explanation of the non-zero value.

MFM0004I: setsockopt reus return code is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. n is the return code from the TCP/IP setsockopt REUS call and a value of zero indicates that startup is proceeding normally.

A non-zero value may indicate a problem. Refer to your TCP/IP provider's socket API return code documentation for an explanation of the non-zero value.

MFM0005I: setsockopt linger return code is n

Issued during startup by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. n is the return code from the TCP/IP setsockopt call and a value of zero indicates that startup is proceeding normally.

A non-zero value may indicate a problem. Refer to your TCP/IP provider's socket API return code documentation for an explanation of the non-zero value.

MFM0006E: Tcpm socket error, sd=n1, function=name, errno=n2

Issued by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This process establishes the client connection and then assigns the client to a processing subtask based on the client type (for example, CICS Option client, IMS client, Telnet client). This message indicates that an error has occurred during the processing of a socket API call associated with this connection establishment process. name identifies the specific socket API call, n1 identifies the socket (either the listening socket or a new socket created when a client request is accepted) and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0007E: Tcpm socket error, sd=n1, function=name, errno=n2

Issued by the process that serves client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This process establishes the client connection and then assigns the client to a processing subtask based on the client type (for example, CICS Option client, IMS client, Telnet client). This message indicates that an error has occurred during the processing of a socket API call associated with this connection establishment process. name identifies the specific socket API call, n1 identifies the socket (either the listening socket or a new socket created when a client request is accepted) and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0008E: Parameter initialization has failed

Issued during initialization if parameters processed from the active configuration data set specified by the //XDBIN data definition statement contain errors that make it impossible for Mainframe Access to complete startup. Mainframe Access shuts itself down after issuing this message.

Review the startup messages to identify and correct any configuration errors before restarting Mainframe Access.

MFM0009E: APF authorization has failed

Issued during initialization if Mainframe Access finds that it is not executing as an z/OS authorized program. Mainframe Access must execute as an z/OS authorized program and the z/OS TESTAUTH service is used to verify this during startup. Mainframe Access shuts itself down with a U2199 abend after issuing this message.

Check each program library name in the //STEPLIB data definition statement and make sure that each is identified to z/OS' Authorized Program Facility as an authorized program library. Common mistakes are misspelled data set names and incorrect DASD volume identifications.

MFM0010E: Global data area initialization failed

Issued during initialization if Mainframe Access cannot load required service modules and initialize its global data areas. Mainframe Access shuts itself down with a U2202 abend after issuing this message.

If you see this message contact our Product Support.

MFM0011I: Mainframe Access shutdown completed

This is the last message issued during shutdown to indicate that all processes have been stopped. The Mainframe Access job or started task should end immediately after issuing this message. If the Mainframe Access stop command is issued and you do not see this message within a reasonable amount of time (approximately 30 seconds) there is most likely a problem quiescing one or more of the Mainframe Access processes. This may be due to a Mainframe Access problem or it may be the result of other problems in the system.

If such a condition occurs frequently and no associated system condition can be identified, contact our Product Support for assistance.

MFM0012I: TCP port number is n

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the TCP port number for client connections, as specified in your Mainframe Access configuration parameter TCP_PORT.

MFM0014I: Mainframe Access version (service) for company

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. version identifies the Mainframe Access product version and company is your company name as specified in your Mainframe Access configuration parameter ORGANIZATION.

MFM0015I: message text

Message MFM0015I is a blank template that is used during the creation of Mainframe Access displays in response to administrative commands. message text is a self-explanatory line of display information created by command processing routines. For examples of how this message is used see the sample command output in the chapter Console Commands.

MFM0016E: Tcps socket error, sd=n1, function=name, errno=n2

Issued by the process that serves clients that use DB2 connectivity. This message indicates that an error has occurred during the processing of a socket API call associated with client communication. name identifies the specific socket API call, n1 identifies the client socket and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0017E Tcps socket error, sd=n1, function=name, errno=n2

Issued by the process that serves clients that use DB2 connectivity. This message indicates that an error has occurred during the processing of a socket API call associated with client communication. name identifies the specific socket API call, n1 identifies the client socket and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0018I: name-address Task initialization has completed

Issued during startup by Mainframe Access' specialized z/OS processing subtasks as they successfully complete initialization. name identifies the type of subtask and address is the address of Mainframe Access' task control block for the process.

MFM0019I: name-address Task shutdown has completed

Issued during shutdown by Mainframe Access' specialized z/OS processing subtasks as they complete shutdown. name identifies the type of subtask and address is the address of Mainframe Access' task control block for the process. These messages can sometimes help to identify the general nature of a Mainframe Access shutdown delay or failure by identifying the processes that have successfully finished their cleanup procedures.

MFM0020E: Wwwm socket error, sd=n1, function=name, errno=n2

Issued by the process that serves HTTP client requests arriving on the administration port. This process establishes the client connection and then assigns the client to a processing subtask based on the HTTP request (for example, simple resource retrieval of a page or image, or ISPI program request). This message indicates that an error has occurred during the processing of a socket API call associated with this connection establishment process. name identifies the specific socket API call, n1 identifies the socket (either the listening socket or a new socket created when a client request is accepted) and n2 is the TCP/IP errno value that was reported for the call.

Refer to your TCP/IP provider's socket API return code documentation for an explanation of the errno value for the specified function.

MFM0023E: Conversation id returned null for socket blockaddress

Issued by the processes that serve Remote IMS and CICS Option client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This message indicates that an error occurred when Mainframe Access tried to access the LU6.2 conversation associated with this client's IMS or CICS connection. address identifies the Mainframe Access socket block associated with the requesting client.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0024E: Client data length error, length is 0

Issued by the processes that serve Remote IMS and CICS Option client requests arriving on the TCP port, as specified in your Mainframe Access configuration parameter TCP_PORT. This message indicates that an error occurred when Mainframe Access received a request message from the client.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0025I: Trace set to data level on

Issued in response to the Trace On command to confirm that Mainframe Access activity tracing has been initiated. Trace data is written to the destination specified by the configuration parameter TRACE, or to the default destination, the XDBOUT data set.

MFM0026I: Trace set to data level off

Issued in response to the Trace Off command to confirm that Mainframe Access activity tracing has been stopped.

MFM0027I: Telnet mode on

Issued to confirm that Mainframe Access is accepting Telnet client connection requests.

MFM0028I: Telnet mode off

Issued to confirm that Mainframe Access is not accepting Telnet client connection requests.

MFM0029E: Command is not allowed

Issued to indicate that the previously entered command could not be processed although it was entered correctly.

MFM0030E: name invalid command, please reenter

Issued to indicate that the previously entered command name could not be processed due to an error in the format of the command parameters.

Reenter the command with correct parameters.

MFM0031E: Wtrm task shutdown initiated for unrecoverable error

Issued by the Mainframe Access task that processes operator commands. This message indicates that a severe error occurred during the processing of a command. Commands can originate from the system console (z/OS Modify command) and Telnet clients.

Restart Mainframe Access after shutdown is complete. If this problem occurs frequently, contact our Product Support for assistance.

MFM0032E: Wtrm task is recovered

Issued by the Mainframe Access task that processes operator commands. This message indicates that a severe error occurred during the processing of a command and Mainframe Access was able to resume normal processing. Commands can originate from the system console (z/OS Modify command) and Telnet clients.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0042E: DLL DD name is missing

Issued when a request for an ISPI program is received and Mainframe Access' ISPI program loader cannot find a data definition statement for the ISPI program libraries (the //DLL DD statement). An error response is sent to the requester.

Stop Mainframe Access, add the missing //DLL data definition statements to the Mainframe Access startup JCL and then restart Mainframe Access.

MFM0043E: Open DLL file has failed

Issued when a request for an ISPI program is received and Mainframe Access' ISPI program loader receives an error indication from z/OS when opening the ISPI program libraries identified by the //DLL DD statements. An error response is sent to the requester.

Examine the system log and job log for I/O error messages associated with this failure and use that information to correct the problem. If the problem persists or cannot be identified, contact our Product Support for assistance.

MFM0045E: Unable to allocate LU6.2 conversation with target CICS

Issued by the process that serves CICS Option client requests arriving on the TCP port, as specified in your configuration parameter TCP_PORT. This message indicates that an error has occurred while Mainframe Access was attempting to allocate an LU6.2 conversation to the target CICS region. In some cases the actual error may have occurred during session establishment with the target CICS system and preceding error messages may contain LU6.2 return code information that will be helpful in diagnosing the problem.

Verify that all of the Mainframe Access target server configuration parameters for the CICS region are correct. Also check that the CICS definitions for Mainframe Access are correct and that the VTAM log mode specified in the target server configuration is available to both CICS and Mainframe Access. If this problem occurs frequently, contact Micro Focus Product Support for assistance.

MFM0046E: Function ship error, errno=n, desc=text, data=string

Issued by the process that serves CICS Option client requests arriving on the TCP port, as specified in your configuration parameter TCP_PORT. This message indicates that an error has occurred while Mainframe Access was communicating with the target CICS region. n is an error code assigned by Mainframe Access. text provides a short description of the type of error or the current state of processing. string provides additional error information appropriate for the type of error being reported.

If this problem occurs frequently, contact our Product Support for assistance.

MFM0047I: DSS maximum shared public files is n

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the value specified in the configuration parameter MAX_PUBLIC_FILES. This value indicates the maximum number of shared files that can be concurrently open.

MFM0049I: DLL name scheduled for MFM0049I: DLL name scheduled for refresh

Issued in response to the ISPI module refresh command to confirm that Mainframe Access has accepted the refresh request. A new copy of the requested ISPI load module will be brought into storage using the z/OS LOAD service and used to process subsequent HTTP requests for the program.

MFM0053I: SMF recording is on, record id is n

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the value specified in the configuration parameter SMF_RECORDID. This is a valid user SMF record id and recording is activated.

MFM0054E: SMF recording is off, record id is zero or invalid

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. If the configuration parameter SMF_RECORDID was specified as 0 (zero), you have elected to disable SMF recording. If the configuration parameter SMF_RECORDID was specified as a non-zero value, the value is not valid for SMF user records. In this case, SMF recording is disabled.

If SMF recording is required, stop Mainframe Access, correct the parameter value and then restart Mainframe Access.

MFM0055I: DSS scan interval is n minutes

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. n is the value specified in the configuration parameter DSS_SCAN_INTERVAL.

MFM0056E: DSS scan interval is not valid, defaults to 2 minutes

Issued during initialization as parameters are processed from the active configuration data set specified by the //XDBIN data definition statement. An invalid value was specified for the configuration parameter DSS_SCAN_INTERVAL. The default value of two minutes was substituted for the invalid parameter value.

If two minutes is not an acceptable value, stop Mainframe Access, correct the parameter value and then restart Mainframe Access.

MFM0059E: BLDL for ISPI DLL module name failed

A request to execute ISPI module name was received from an HTTP client. The z/OS BLDL service was unable to locate this load module in the program library concatenation specified by the //DLL data definition statement.

Check that the load module name is correct and that all required program libraries are available.

MFM0060E: LOAD for ISPI DLL module name failed rc=n1 reason=n2

A request to execute ISPI module name was received from an HTTP client. The z/OS LOAD service reported a failure when reading the load module from the program library concatenation specified by the //DLL data definition statement. Return code n1 is the z/OS system completion code that would normally be reported as an abend failure by the z/OS LOAD service and n2 is the additional reason code associated with the abend code. Both values are given as hexadecimal numbers.

Refer to the z/OS system codes manual for your level of z/OS to interpret the return code/reason code pair and take appropriate corrective action.

MFM0061E: ISPI DLL module name unavailable due to rc=n1 reason=n2

A request to execute ISPI module name was received from an HTTP client. This ISPI module has been logically disabled by Mainframe Access due to a previous error condition associated with the module. The previous error may have been an z/OS LOAD service failure or a module execution failure. Return code n1 is the z/OS completion code that was reported for the original failure and n2 is the additional specific reason code associated with the completion code. Both values are given as hexadecimal numbers.

If the completion code value is of the form 00xxx000, xxx is an z/OS system completion code and you should refer to the z/OS system codes manual for your level of z/OS to interpret the return code/reason code pair and take appropriate corrective action. If the completion code value is of the form 00000xxx, the xxx value is a hexadecimal user abend code. User abend codes are normally documented as decimal values and you should convert the xxx hexadecimal value to decimal, if necessary. Refer to the program documentation for the meaning of the user abend code.

MFM0062E: Initialization failed (by name - explanation)

During initialization processing a condition was encountered that would prevent proper execution of Mainframe Access. For example, Mainframe Access' listening process for client connections was unable to allocate and/or open a socket for TCP_PORT. The component that detected the condition has initiated shutdown processing. The name identifies the task that detected the condition and explanation provides a concise statement of the problem.

Examine associated error messages in the system log, joblog and XDBOUT data set to determine the cause of the initialization failure. In most cases, the related error messages can be found just before this message in the XDBLOG data set. Correct the problem and restart Mainframe Access.

MFM0063I: MFA Direct is active

This message is issued during initialization to acknowledge that MFADIRECT=YES was specified in the parameter file.

MFM0064I: MFA Direct number of processing tasks is n

This message is issued during initialization to acknowledge that the MFADIRECT_MAXTASKS=n parameter file specification has been processed. Mainframe Access will start n z/OS tasks for Mainframe Access request processing. During execution Mainframe Access will create up to n additional tasks for Mainframe Access request processing if the transaction rate and processing load warrant.

MFM0065I: usage port number for client connections is n

This message is issued during initialization to acknowledge that the TCP_PORT parameter file specifications have been processed. The usage indicates that the "Enterprise Server" (for TCP_PORT) will be listening on port number n for client connections.

MFM0066I: Address space type is astype

This message is issued during initialization to acknowledge that the ASTYPE parameter file specification has been processed. The address space type can be "STANDARD", "CTLRGN" or "APPSERVER". The "STANDARD" address space is a stand-alone Mainframe Access server. The "CTLRGN" is a Mainframe Access server capable of starting application server regions such as the Mainframe Access Data Connect server. The "APPSERVER" address space is lightweight subset of the Mainframe Access server that is started and managed by a CTLRGN.

MFM0068I: parmname parameter specification invalid

This message is issued during initialization to indicate that the usage of parameter parmname is incorrect and this parameter was not successfully processed.

Correct the parameter specification and restart Mainframe Access.

MFM0069E: MFADirect not configured - rejecting sd=n ip=addr

Issued by the TCP/IP listener for TCP_PORT when a client connection request for Mainframe Access services is received and MFADirect services have not been configured in the initialization parameters. The client (from IP address addr on socket n) is disconnected.

Check that MFADirect services are enabled by the MFADIRECT and MFADIRECT_MAXTASKS initialization parameter settings. Restart Mainframe Access if parameter settings are changed.

MFM0070E: MFA Data Connect not configured - rejecting sd=n ip=addr

Issued by the TCP/IP listener for TCP_PORT when a client connection request for Mainframe Access Data Connect services is received and the Mainframe Access Data Connect server has not been configured in the initialization parameters. The client (from IP address addr on socket n) is disconnected.

Check that the Mainframe Access Data Connect server is enabled by the Mainframe Access FEATURE, MFALINK_MAXTASKS and ASTYPE initialization parameter settings. Restart Mainframe Access if parameter settings are changed.

MFM0071E: process access list check condition client ipaddr

This message may be issued by the TCP/IP port listeners when access list checking is active. If process is XDBTCPM, this is a connection attempt through the TCP_PORT for Micro Focus clients. Each client's IP address (ipaddr) is checked against the PERMIT and REJECT specifications in the access list. If the condition reported is "rejected", the client IP address was found to match a reject specification in the access list. In this case the client's connection request is immediately rejected. If the condition reported is "warning for", no matching reject or accept specification was found in the access list. In this case the client connection is accepted. You may wish to add an access list specification for this client or an appropriate range of similar client IP addresses.

MFM0072E: Shutdown starting due to failure (in taskname)

This message is issued when one of the Mainframe Access tasks encounters a software failure and ESTAEX processing is unable to fully recover and guarantee the integrity of subsequent processing in the address space. In this case, the ESTAEX recovery routine processing will start an automatic shutdown of Mainframe Access.

Examine the XDBOUT data set, joblog and system log for associated error messages. This may identify a problem that requires you to take a corrective action. Restart Mainframe Access and report the incident to Product Support.

MFM0074E: The following parameter statement is rejected (line n)

This message is issued during startup when an invalid parameter is found in the Mainframe Access configuration parameter file. The statement containing the invalid parameter is displayed in the message line that follows.

Mainframe Access Server completes processing of the parameter file and then shuts down due to the parameter error. Correct the invalid parameter and restart Mainframe Access Server.

MFM0077E: CG production log (ddname) open failed, errno=n _msgno=m

This message is issued during startup when the data set specified by Mainframe Access configuration parameter CGMQOTMA LOGDD cannot be OPENed.

MFM0079I: CG production log closed

This message is issued during shutdown to confirm that the data set specified by the Mainframe Access configuration parameter CGMQOTMA LOGDD has been successfully closed.

MFM0080I: MQ message queue configuration information
MFM0083I: Cross-memory initialization starting (dac=address)

This message is issued during startup when dependent address spaces are configured. Mainframe Access is preparing to create the z/OS cross-memory resources that allow Mainframe Access address spaces to communicate using Program Call. The control region is first to initialize and it establishes the cross-memory environment that allows dependent regions to call back into the control region. As dependent regions initialize (either at startup or on-demand) each dependent creates a cross-memory environment that allows the control region to call into the dependent region. This creates a bi-directional calling mechanism between the control region and each dependent region. The DAC is the primary control table for dependent address space services.

MFM0084I: Cross-memory initialization complete

This message is issued during startup when Mainframe Access has completed the setup of z/OS cross-memory resources that allow Mainframe Access address spaces to communicate using Program Call.

MFM0085I: > Start_Program sent to [rcvd from] stcname (seq=n grp=cccc pgm=cccccccc uid=cccccccc)

This message is issued when Program Call is used to pass a Start Program request to a dependent address space. The control region issues the "sent" form of the message and the dependent region issues the "rcvd" form of the message. seq= is the request sequence number used to correlate the cross-memory activity grp= is the ASGROUP name for the dependent region pgm= is the name of the program to be called uid= is the user id that will provide the program execution security environment

MFM0086I: > Program_Complete sent to [rcvd from] stcname (seq=n ServerRC=n ProgramRC=xxxxxxxx)

This message is issued when Program Call is used to pass a Program Complete indication to the control region. The Program Complete indication returns the result of a Program Call request that was passed to the dependent region. seq= is the request sequence number used to correlate the cross-memory activity ServerRC= is the Mainframe Access return code 0 = the requested program was called and executed succesfully (ProgramRC contains the return code) 1 = the requested program abended (ProgramRC contains the ABEND code) 2 = the dependent region could not load the requested program module 3 = the dependent region Mainframe Access load and call service failed 4 = the call request was not successfully passed to a dependent processing region 5 = the user credentials (userid and password) were invalid ProgramRC= is the return code value from the called program (if the ServerRC is zero)

MFM0087I: Cross-memory environment created

This message is issued during startup to confirm that the z/OS cross-memory Program Call infrastructure was successfully created in this address space.

MFM0088I: Asparm extracted (length=n)
This message is issued during startup of a dependent region to confirm that information needed to establish cross-memory communication was successfully passed from the control region to this dependent region. The asparm data is displayed in dump format following this message.
MFM0089E: Cross-memory start failed (Da_Start rc=n rs=xxxxxxxx)

This message is issued during startup if Mainframe Access is unable to create the z/OS cross-memory Program Call infrastructure.

Mainframe Access ABENDs with code U3100. Contact product support if you cannot resolve the reason for the initialization failure by examining related messages, etc.

MFM0090I: Waiting for server task to initialize

This message is issued during startup when the dependent region has received a request and the required processing task has not yet complete initialization.

This message is issued repeatedly (every second) until the server task completes initialization and is ready to accept the request.

MFM0091I: < Appserver_Started received from stcname (dab=xxxxxxxx)

This message is issued by the control region when a started dependent region has completed its cross-memory initialization and issued a confirming Program Call back to the control region. The dependent's call provides the cross-memory information that the control region needs to Program Call into the dependent region.

MFM0092I: Appserver stcname connected (dab=xxxxxxxx)

This message is issued by the control region when a started dependent region has been successfully contacted by the control region using the dependent's cross-memory Program Call information.

MFM0093E: Appserver stcname connection failed (Da_Conn rc=n rs=xxxxxxxx)

This message is issued by the control region when a started dependent region could not be contacted by the control region using the dependent's cross-memory Program Call information.

Contact product support if this problem persists.

MFM0094I: < Ctlrgn_Acknowledgement received from stcname

This message is issued by the dependent region when the control region contacts the dependent by using the cross-memory Program Call information provided by the dependent.

MFM0095I: < Start_Shutdown received from stcname

This message is issued by the dependent region when the control region uses Program Call to start shutdown processing in the dependent region.

MFM0096I: Cross-memory cleanup complete

This message is issued during shutdown to confirm that all of the z/OS cross-memory resources allocated by this address space have been successfully released.

MFM0097E: Cross-memory cleanup failed (DA_Stop rc=n rs=xxxxxxxx)

This message is issued during shutdown to report that some z/OS cross-memory resources allocated by this address space were not successfully released.

Contact product support if this problem persists.

MFM0098I: Appserver stcname is being shutdown (dab=xxxxxxxx)

This message is issued during shutdown by the control region when an active dependent region is selected to receive a Start_Shutdown Program Call. After the call the PC linkage for the dependent is removed from the control region.

This message is also issued when a dependent region is being shut down in response to a request processing ABEND in that region. When a processing ABEND occurs the control region will shut down the associated dependent region because that address space is considered unstable. For example, storage contents may be corrupted, excessive storage allocations may be accumulating, etc. A new instance of a dependent region will be automatically started when one is needed for subsequent request processing.

MFM0099I: Appserver stcname disconnected (dab=xxxxxxxx)

This message is issued during shutdown by the control region to confirm that the named dependent region has received the Start_Shutdown Program Call and its PC linkage has been removed from the control region.

This message is also issued to confirm the shutdown of an dependent region that has become unstable due to a previous processing ABEND.

MFM0100E: Appserver stcname disconnect failed (Da_Ashut rc=n rs=xxxxxxxx)

This message is issued during shutdown by the control region when the cross-memory linkage to the named dependent region cannot be successfully removed.

Contact product support if this problem persists.

MFM0101I: groupname address space group successfully created (dag=xxxxxxxx)

This message is issued during startup by the control region when the definition for an address space group has been successfully processed. This message confirms that the control structures for managing the group's address spaces have been successfully created. Message MFM0102I follows and displays the parameter values for the group. Address space group definitions are read from the Mainframe Access SERVERS file during initialization.

This message does not confirm that all values in the address space group definition are valid and usable. For example, the JCL procedure name in the definition may not exist in the proclib or the JCL procedure may have syntactical errors that will prevent it from starting.

MFM0102I: groupname - Proc(name) STCprefix(cccc) GroupID(n) Min(n) Max(n) Server(name)

This message is issued during startup by the control region and follows message MFM0101I for a successful address space group creation. This message displays the parameter values from the SERVERS definition for the group.

MFM0103I: groupname is the default address space group

This message is issued during startup by the control region when an address space group definition with GroupID=1 is processed. GroupID=1 specifies that this is the definition for a default group that will be selected if the group name or group id in a request cannot be found in an active address space group definition.

MFM0104I: No default address space group has been defined

This message is issued during startup by the control region when all address space group definitions have been processed and no default group was defined. GroupID=1 is used in a group definition to indicate the default group. There is no requirement to define a default group and system operation can proceed normally without a default group definition. Processing requests that do not specify a valid active group name or group id will be rejected.

MFM0105I: Address space stcname started for group groupname (dab=xxxxxxxx)

This message is issued by the control region when a new dependent address space is started. The stcname is the started task name assigned to the job. The groupname identifies the address space group for which this address space was started.

MFM0106E: Address space for groupname could not be started (Da_Ascre rc=n rs=xxxxxxxx)

This message is issued by the control region when a new dependent address space cannot be started. The return code and reason code from the address space creation routine are reported in the message.

The most common reason, indicated by rc=5, indicates that the maximum number of address spaces defined for the group has been reached. When rc=5 is reported, the request that initiated the address space creation must be queued to wait for one of the existing address spaces to become available.

If rc=5 is frequently reported for your system you should increase the ASMAXIMUM value for the address space group by 1. This allows an additional address space to be started and reduces the queueing delays for client requests. Contact product support if the problem persists.

MFM0107E: Definition failed for group groupname (Da_Mkgrp rc=n rs=xxxxxxxx)

This message is issued during startup by the control region when the control structures for an address space group definition cannot be successfully created.

Mainframe Access ABENDs with code U3100. Contact product support if you cannot resolve the reason for the initialization failure by examining related messages, etc.

MFM0108I: > Start_Tran sent[rcvd] to groupname (seq=n pri=n len=n1+n2 grp=cccc src=n.n.n.n)

This message is issued when Program Call is used to pass a Start Transaction request to a dependent address space. The control region issues the "sent" form of the message and the dependent region issues the "rcvd" form of the message. seq= is the request sequence number used to correlate the cross-memory activity pri= is the priority assigned to the transaction by the originator len= shows the header length (n1) and the content length (n2) grp= is the ASGROUP name for the dependent region src= is the IP address of the originator

MFM0109I: > Tran_Complete sent to [rcvd from] groupname (seq=n ServerRC=n ProgramRC=xxxxxxxx)

This message is issued when Program Call is used to pass a Transaction Complete indication to the control region. The Transaction Complete indication returns the result of a Start Transaction request that was passed to the dependent region. seq= is the request sequence number used to correlate the cross-memory activity

ServerRC is the Mainframe Access return code 0 -> the requested transaction was called and executed succesfully (ProgramRC contains the transaction return code) 1 -> the requested transaction abended (ProgramRC contains the ABEND code) 2 -> the client socket connection could not be obtained by the dependent region

ProgramRC is the return code value from the called transaction program (if the ServerRC is zero)

MFM0110I: Request queued for group groupname (qcount=n dapc=xxxxxxxx rc=n rs=xxxxxxxx)

This message is issued when a request (Start Program or Start Transaction) is received and no dependent address space is immediately available to process the request. The request is queued to the address space group to wait for an available dependent address space. If the maximum number of address spaces for the group have not been started, a new dependent region will be started to process this request. qcount= is the current number of requests waiting in the queue for this address space group dapc= is the address of the control structure that represents the unit of work rc= and rs= are the return and reason code values from the Da_Qwork service .

If this message occurs frequently, your system may perform better if you update the servers definition file for the indicated group. Increasing the ASMAXIMUM value of the group by 1 will provide an additional address space for processing client requests. This should reduce the frequency of request queueing which should result in improved response time for requests that would otherwise be queued.

MFM0111I: SAF logon for userid (sd=n (xxxxxxxx) rc=n type=n aaausr=xxxxxxxx acee=xxxxxxxx)

This message is issued when a user at a Mainframe Access client successfully authenticates by providing a userid and password that are accepted by the z/OS SAF authentication routines. Security resources, including a z/OS SAF ACEE control block, are obtained to create a security environment for this user.

MFM0112I: SAF logoff for userid (sd=n (xxxxxxxx) rc=n type=n)

This message is issued when a previously authenticated user at a Mainframe Access client changes user ids or disconnects from the server. This message confirms that the z/OS SAF ACEE and related security resources have been released.

MFM0113E: SAF error for userid (sd=n (xxxxxxxx) SafRC=n RacfRC=n RacfRS=n

This message is issued when the userid and password submitted by a Mainframe Access client are rejected by z/OS SAF authentication routines. The specific SAF and RACF return and reason codes are reported in the message. The SAF and RACF return and reason code definitions are summarized elsewhere in this seciton.

MFM0114E: Timeout for sd=n n.n.n.n at mm/dd/yy hh:mm:ss, last time: mm/dd/yy hh:mm:ss

This message is issued when a Mainframe Access client is idle for the number of minutes specified by the TIME OUT FOR CONNECTION parameter. The idle client is disconnected and associated resources are released. sd= is the socket number of the client connection n.n.n.n is the IP address of the client mm/dd/yy hh:mm:ss is the date and time when the time out occurred The "last time" is the date and time when the last client TCP/IP activity occurred.

MFM0115E: Access list I/O task initialization has failed

This message is issued during initialization if the access list file (DDNAME XDBACC) is not usable.

Disregard this error message for dependent regions. Dependent regions do not use an access list data set. If the error message is for the control region, examine related Mainframe Access and system message to determine the cause of the error. Contact product support if the problem persists.

MFM0116E: Access list DDname is missing

This message is issued during initialization if a data definition statement for DDNAME XDBACC is not found in the started task JCL.

Disregard this error message for dependent regions. Dependent regions do not use an access list data set. If the error message is for the control region, correct the started task JCL for the Mainframe Access control region and restart Mainframe Access Server. Contact product support if the problem persists.

MFM0117I: Mainframe Access ParmBlock is located at xxxxxxxx

This message is issued during initialization to display the address of the Mainframe Access Server primary control table, the ParmBlock.

MFM0118I: type [parameter definition statement]

This message is issued during initialization to display the active parameter definitions when LIST PARMS=YES is specified in the Mainframe Access startup parameters. All statements from the XDBIN parameter file (type "Parms") and the SERVERS definition file (type "Srvrs") are echoed to the XDBOUT sysout data set.

MFM0119I: Mainframe Access jobname is cccccccc

This message is issued during initialization to display the jobname assigned to this Mainframe Access address space.

MFM0120E: Servers definition for MCOID=mcoid not found sd=n (xxxxxxxx)

This message indicates that an error has occurred while Mainframe Access was processing the initial client request to bind a target CICS region to the current socket connection. The mcoid contained in the client request did not match any of the defined CICS servers and no default CICS server was defined.

Verify that the MCOID is specified correctly in the client configuration. Also verify that the Mainframe Access Server definition for that target CICS system is correct. The "Connect id" in the CICS Resource Definition should match the MCOID in the Mainframe Access Server definition. You may also create a default CICS server definition that is to be used when the client-specified MCOID does not exist. If the definitions are correct and this problem persists, contact Micro Focus Product Support for assistance

MFM0121E: MFA startup error: no DSS environment

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to validate that Global Storage has been assigned for Endevor use. This messages indicates that MFA initialization has failed, and no global work areas have been pre-assigned for Endevor.

MFM0122E: Endevor setup error: No MSGLOG established

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to validate that an Endevor transaction message log has been successfully allocated to this job. This is either dynamically created as jobname.CR_jobname.MFA.ENDEVOR.MSGLOG or pre-defined by the site within the DR started task JCL:

  //ENDVMSG  DD DISP=NEW,DSN=&&MSGLOG,UNIT=VIO,
//            DCB=(RECFM=FBA,LRECL=133,BLKSIZE=13300),
  //            SPACE=(13300,(10,10))

An Endevor transaction cannot be processed without a MSGLOG file.

MFM0123E: Endevor version mismatch between CR and DR

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to validate that the same Endevor API version was used in both address spaces. This is necessary because the Endevor API is not downward compatible. The transaction is aborted if the version does not match. The STEPLIB concatenation must specify the same Endevor load library version in both address spaces.

MFM0124E: No Endevor API modules found

When a transaction arrives at an Endevor Dependant Region, MFA will attempt to load the module ENA$NDVR. This the entry point of the Endevor API. The transaction is aborted if the Endevor API cannot be located.

MFM0125E: name-address Task shutdown forced

Issued during shutdown when one of the Mainframe Access subtasks does end properly. name identifies the type of subtask and address is the address of Mainframe Access' task control block for the process.

This message is normal when the associated task has had a processing failure prior to shutdown. Contact product support if this message appears frequently.

MFM0126E: Tasks (n) forced during shutdown forced

Issued during shutdown when one or more of the Mainframe Access subtasks does not end properly (see message MFM0125E).

This message is normal when the associated tasks have had processing failures prior to shutdown. Contact product support if this message appears frequently.

MFM0128I MCG subtask MCGEXEC cc xxxxxxxx started for XDBMFADM cc xxxxxxxx

This is a normal operational message to log the fact that a new subtask was started for Mainframe Call Generator program execution.

MFM0128E MCG Non-zero return from IGZERRE set call; rc=ddd

The IBM IGZERRE module was called to establish a COBOL run time environment but has indicated there is a problem by returning with a non-zero return code. See the section IGZERRE Entry Conditions and Return Codes in the appendix Mainframe Call Generator for information on the return code values.

MFM0128E MCG Module IGZERRE is not available for set call

This message indicates that the IBM IGZERRE module was not loaded during startup and could therefore not be called to establish a COBOL run time environment.

MFM0128E MCG Non-zero return from IGZERRE reset call; rc=ddd

The IBM IGZERRE module was called to terminate a COBOL runtime environment during Mainframe Call Generator cleanup but has indicated there is a problem by returning with a non-zero return code. See the section IGZERRE Entry Conditions and Return Codes in the appendix Mainframe Call Generator for information on the return code values.

MFM0128E MCG No IGZERRE COBOL environment found for reset

The Mainframe Call Generator cleanup service found that no COBOL environment was previously established for the Mainframe Call Generator session that is ending.

MFM0129E MCG Unable to execute user program cccccccc

An execute request could not be completed for the named program. The preceding error messages will identify the exact cause.

MFM0129E MCG Unable to find or load user program cccccccc

The z/OS BLDL or LOAD operation for the named program failed. The preceding error messages will identify the exact cause.

MFM0129E MCG Request message sequence error

An unexpected Mainframe Call Generator request message was received from the client. The Mainframe Call Generator request is not appropriate for the current state of the remote execution operation. Start the Mainframe Access Server trace facility and recreate the problem to create a log of messages showing the sequence of messages being exchanged.

MFM0129E MCG Request message not recognized

An unexpected request message was received from the client. The request message could not be identified as a Mainframe Call Generator request. Start the Mainframe Access Server trace facility and recreate the problem to log the erroneous message.

MFM0130E MCG cccccccc ABENDed, System=Sxxxx Reason=xxxxxxxx User=Udddd

This message is issued after the Mainframe Call Generator ESTAE extension has trapped and recovered from an ABEND condition. The message provides the system (hexadecimal) or user (decimal) ABEND code. System reason codes are also logged for system ABENDs. If a SYSUDUMP (or SYSMDUMP) DD statement is available to the server, a dump is recorded for the ABEND.

MFM0130E MCG unable to call cccccccc, iSvcRC=dddd iSvcRS=dddd

This message is issued when server preparation for the Mainframe Call Generator call operation encounters an internal logic error. The MD_MCGEXEC_RUN service was called to execute the user program but this service ended with an error indicated by the return code and reason code values. The preceding error messages identify the exact cause.

MFM0130E MCG cleanup failed, iSvcRC=dddd iSvcRS=dddd

This message is issued if the MD_MCGEXEC_CLEANUP service encounters an internal logic error. The preceding error messages identify the exact cause.

MFM0131E Task cccccccc xxxxxxxx TCB xxxxxxxx terminated Udddd; callrtm rc=ddd

This message is issued when a subtask is forcibly terminated by Mainframe Access Server. The Udddd user ABEND code will be U201 for forced terminations of a MCGEXEC subtask. This could occur when the end user logs off or terminates the client while a Mainframe Call Generator session is active.

Parent topic: Mainframe Access Server Messages


Data Set Services Messages

  • MFMDS001I DSS Server Ready
  • MFMDS002I DSS Initialization failed
  • MFMDS003I Cell pool build failed
  • MFMDS004I Public File non-VSAM
  • MFMDS005I DSS Server shutdown
  • MFMDS006I DSS Server unidentified request
  • MFMDS007I
  • MFMDS008I Online ITEM LIBRARY=data-set-name
  • MFMDS009I Offline ITEM LIBRARY=data-set-name
  • MFMDS010I DAIR reas/info DSN=data-set-name
  • MFMDS011I TIOT ENQ INTERFERENCE
  • MFMDS012I M=member ENQ FAILURE RC=nnn
  • MFMDS013E OPEN FAILED FOR SNAP | READER | SYSOUT
  • MFMDS020E Invalid z/OS file format
  • MFMDS021E LRECL too high
  • MFMDS022E Invalid file handle
  • MFMDS024E Invalid file name
  • MFMDS026E LRECL EXCEEDS DEFINITION FOR DSN=dsname
  • MFMDS029E RECALL FAILURE=nnnnn FOR DSN=dsname
  • MFMDS030E STOW error RC=nn Reason=nnnn M=member
  • MFMDS031I DSN=data-set-name
  • MFMDS032E FIND error RC=nn Reason=nnnM=member
  • MFMDS033E BLDL error RC=nnReason=nnn M=member
  • MFMDS034E Directory error RC=nn Reason=nnnn
  • MFMDS035E QSAM abend Sxxx-yy
  • MFMDS040E VSAM error DD=ddname RC=nn FB=nnn REQ=verb
  • MFMDS041E VSAM open error DD-ddname RC=nnFB=nnn
  • MFMDS050E DSS services not available
  • MFMDS052I CAPANVALET READY
  • MFMDS053I CAENDEVOR API REL Brrvvv ESI
  • MFMDS054I Librarian Exit Table active
  • MFMDS055I MCGRPC feature (in)active
  • MFMDS056I ChangeMan DD=CMNxxxx Open failure
  • MFMDS057I CAPANVALET member security exit loaded
  • MFMDS058I Librarian ELIPSGEN not found
Parent topic: Mainframe Access Server Messages


MFMDS001I DSS Server Ready

Mainframe Access has successfully initialized the DSS component. Any pre-allocated item libraries are now ready for use.

Parent topic: Data Set Services Messages


MFMDS002I DSS Initialization failed

Mainframe Access failed to initialize the DSS component. The services normally provided by DSS are therefore not available.

Parent topic: Data Set Services Messages


MFMDS003I Cell pool build failed

The DSS component was unable to acquire enough virtual memory to build a pool of reusable resources.

Adjust the configuration or memory allocation for the Mainframe Access started task.

Parent topic: Data Set Services Messages


MFMDS004I Public File non-VSAM

The DSS component was unable to initialize a shared public file because the file specified was not a VSAM key-sequenced data set. DSS discards the request and continues processing. All item libraries are shared public files.

Ensure that all item libraries are created as VSAM key-sequenced data sets.

Parent topic: Data Set Services Messages


MFMDS005I DSS Server shutdown

The DSS server has been successfully shut down as part of the Mainframe Access shutdown procedure.

Parent topic: Data Set Services Messages


MFMDS006I DSS Server unidentified request

The DSS server detected an invalid request. DSS discards the request and continues processing.

If you see this message contact Micro Focus SupportLine.

Parent topic: Data Set Services Messages


MFMDS007I

Parent topic: Data Set Services Messages


MFMDS008I Online ITEM LIBRARY=data-set-name

The item library named is now online and available.

Parent topic: Data Set Services Messages


MFMDS009I Offline ITEM LIBRARY=data-set-name

The item library named has been taken offline and is no longer available.

Adjust the configuration or memory allocation for the Mainframe Access started task.

Ensure that all item libraries are created as VSAM key-sequenced data sets.

If you see this message contact Micro Focus SupportLine.

Parent topic: Data Set Services Messages


MFMDS010I DAIR reas/info DSN=data-set-name

DSS encountered a dynamic allocation error while attempting to allocate the specified data set. Here are some possible reason and information codes:

Reason | Info | Description
02xx |  | Environmental errors: memory or authorization
0352 | 0002 | Invalid data set name
 | 0003 | Invalid member name
 | 0004 | Invalid disposition
1708 | 0002 | Unable to locate data set name in catalog

All reason codes and information codes are in hexadecimal notation. For a full list of errors and further information on z/OS dynamic allocation errors, see Chapter 26 of the IBM manual MVS Authorized Assembler Services Guide.

Parent topic: Data Set Services Messages


MFMDS011I TIOT ENQ INTERFERENCE

A dynamic allocation request has been aborted because another system service request within this task has already locked access to the TIOT (Task Input/Output Table). The request will be re-tried after a 50 millisecond delay. For further information on OS/390 Dynamic Allocation errors, refer to Chapter 26 of the IBM publication (GC27-1763) MVS Authorized System Services Guide.

Parent topic: Data Set Services Messages


MFMDS012I M=member ENQ FAILURE RC=nnn

A member of a PDS was to be locked for exclusive access by this operation. However, the PDS member could not be locked at this time due to competion from another user. This request has already been retried several times over a three second period, and now the transaction is being aborted due to BLOCKED status. For further information on OS/390 ENQ errors, refer to the IBM publication MVS Assembler Services Reference (GC28-1910).

RC | Description ENQ RET=USE
04 | Resource not available
08 | Task already has control of this resource
12 | Task has previously failed to acquire this resource
Parent topic: Data Set Services Messages


MFMDS013E OPEN FAILED FOR SNAP | READER | SYSOUT

A transient file was not opened properly for subsequent use by MFA resource cleanup (SNAP) or job submission (READER) or logging (SYSOUT). The request is aborted. Additional IBM messages may have been displayed on the SYSLOG to explain the nature of the failure. The MFA Direct server continues to run with degraded services.

Parent topic: Data Set Services Messages


MFMDS020E Invalid z/OS file format

The file named in the associated message MFMDS031 has a file format that is not currently supported by MFA. This includes such formats as ISAM, HFS files, direct-access keyed files, and various spanned record formats.

Parent topic: Data Set Services Messages


MFMDS021E LRECL too high

DSS detected an attempt to write a logical record which exceeded the maximum logical record size for the file named in the associated message MFMDS031.

Parent topic: Data Set Services Messages


MFMDS022E Invalid file handle

DSS detected an invalid parameter list passed by a calling program.

If you see this message contact Micro Focus SupportLine.

Parent topic: Data Set Services Messages


MFMDS024E Invalid file name

DSS detected an attempt to create an invalid filename.

If you see this message contact Micro Focus SupportLine.

Parent topic: Data Set Services Messages


MFMDS026E LRECL EXCEEDS DEFINITION FOR DSN=dsname

During an update operation, a logical record was too large to be written to the selected file. The operation was aborted.

Parent topic: Data Set Services Messages


MFMDS029E RECALL FAILURE=nnnnn FOR DSN=dsname

An internal error occurred during an attempt to recall a file from IBM's HSM (Hierarchical Storage Manager). See the product documentation DFSMShsm Managing Your Own Data (SC35-0420) for details.

RC | Description
100 | DFSMShsm not available
400 | Invalid request
402 | Dataset not found
403 | Invalid dataset name
806 | Service module not found
Parent topic: Data Set Services Messages


MFMDS030E STOW error RC=nn Reason=nnnn M=member

DSS encountered an error while writing to the PDS directory for the file named in the associated message MFMDS031. The first eight characters of the member name are displayed. Here are some possible return code (RC) and reason values:

RC | Reason | Description
4 | 0 | Member name specified already exists
8 | 0 | Member name specified could not be found
12 | 0 | No space remains in the directory
16 | 01 | Permanent physical error
 | 02 | Unable to add EOF marker to directory
 | 04 | Unable to flush system buffers
 | 3383 | SD37 failure: no secondary space available
 | 3639 | SE37 failure: no secondary space available

For a full list of return codes and reasons, see the IBM manual Macro Instructions

Parent topic: Data Set Services Messages


MFMDS031I DSN=data-set-name

This information message may accompany other system messages to indicate which data set is affected. The data set name appears as a string of up to 44 characters.

Parent topic: Data Set Services Messages


MFMDS032E FIND error RC=nn Reason=nnnM=member

DSS encountered an error while locating a member in the PDS directory for the file named in the associated message MFMDS031. The first eight characters of the member name are displayed. Here are some possible return code (RC) and reason values:

RC | Reason | Description
4 | 0 | Member name specified could not be found
 | 4 | Insufficient RACF authority for this request
 | 8 | Share options not granted on this PDSE
 | 12 | This PDSE already open for output on another member
8 | 0 | Permanent physical error
 | 4 | Insufficient virtual storage available
 | 8 | Invalid DEB (data extent block) or data set owned by another task
 | 12 | Physical error on buffer flush
 | 16 | Invalid DCB
Parent topic: Data Set Services Messages


MFMDS033E BLDL error RC=nnReason=nnn M=member

DSS encountered an error while building directory information from the PDS directory for the file named in the associated message MFMDS031. The first eight characters of the member name are displayed. Here are some possible return code (RC) and reason values:

RC | Reason | Description
4 | 8 | Member name specified could not be found
8 | 0 | Permanent physical error
 | 4 | Insufficient virtual storage available
 | 8 | 8 Invalid DEB (data extent block) or data set owned by another task

For a full list of return codes and reasons, see the IBM manual Macro Instructions for Data Sets.

Parent topic: Data Set Services Messages


MFMDS034E Directory error RC=nn Reason=nnnn

DSS encountered an error while trying to identify the PDS member for the file named in the associated message MFMDS031. Here are some possible return code (RC) and reason values:

RC | Reason | Description
8 | 1012 | No members found in directory
12 | 1041 | Invalid parameter list
 | 1054 | Invalid DEB (data extent block)
 | 1057 | PDS is not open
 | 1058 | Invalid DCB

For a full list of return codes and reasons, see the topic DESERV (Directory Entry Services) in the IBM manual Macro Instructions for Data Sets.

Parent topic: Data Set Services Messages


MFMDS035E QSAM abend Sxxx-yy

DSS has detected a QSAM failure and has directed QSAM to ignore the failure. The failure occurred while DSS was processing the file named in the associated message MFMDS031. Sxxx is the abend or system completion code and yy is the reason code. These codes are presented in hexadecimal format. Possible failures include:

Abend | Reason | Description
C37 | 4 | Invalid extents found on end-of-volume
D37 | 4 | No secondary space specified on this file, and the primary space has been entirely used. Reallocate the file to allow secondary extents or a larger primary extent.
E37 | 4 | No secondary space was available on this volume, or the number of extents has already reached 16 for this file. Reallocate the file to use larger secondary extents or move the file to a different volume where space is available.
Parent topic: Data Set Services Messages


MFMDS040E VSAM error DD=ddname RC=nn FB=nnn REQ=verb

DSS has detected a VSAM error probably associated with an input/output operation on an item library. Possible values for verb include:
Verb | Description
GET | Read a record
PUT | Write a record
CHECK | Verify completion of an event
POINT | Position to a specific location
ENDREQ | Cancel an operation
ERASE | Erase a record

Common return code (RC) values and feedback code (FB) values include:

RC | FB | Description
8 | 8 | Attempt to store a duplicate key
 | 12 | Conflicting options specified violate stored sequence
 | 16 | Record not found
 | 20 | Physical locking conflict
 | 24 | Volume not available
 | 28 | Insufficient space on volume to extend the
 | 32 | Invalid relative byte address specified
 | 36 | Key range specified in definition excludes this key
 | 40 | Insufficient virtual storage in the Mainframe Access address space
 | 48 | Conflicting options on VSAM request
 | 64 | No virtual storage to handle this level of concurrency
 | 68 | File not open for type of processing requested
 | 72 | Keyed request made to an ESDS
 | 88 | Invalid switch to sequential processing without positioning
 | 92 | Invalid replace or erase without key
 | 96 | Attempt to modify a key on update
 | 104 | Conflicting RPL options
 | 108 | Invalid record length specified
 | 112 | Invalid key length specified
 | 4 | Read error on data component of file
 | 8 | Read error on index component of file
 | 16 | Write error on data component of file
 | 20 | Write error on index component of file

For a full list of return codes and reason codes see the IBM publication DFSMS/MVS Macro Instructions for Data Sets.

Parent topic: Data Set Services Messages


MFMDS041E VSAM open error DD-ddname RC=nnFB=nnn

DSS has detected an error while attempting to open a VSAM data set. This message is accompanied by the z/OS system message IEC161I to describe the problem further. Common return code (RC) values and feedback code (FB) values include:

RC | FB | Description
4 | 116 | Warning: file was not closed properly after previous use and has not been recovered using an internal VSAM verify
 | 118 | Warning: file was not closed properly after previous use but has been recovered using an internal VSAM verify
8 | 128 | No DD statement was found for this file
 | 136 | Not enough virtual storage to complete the open processing
 | 144 | I/O error while reading the catalog
 | 152 | RACF denied open access
 | 160 | Inconsistent open options specified
 | 168 | File already open by another user

For a full list of return codes and reason codes see the IBM publication DFSMS/MVS Macro Instructions for Data Sets. VSAM system messages are documented in the IBM manual z/OS System Messages Volume 4.

For a full list of abend codes and reasons, see the IBM manual MVS System Codes.

Parent topic: Data Set Services Messages


MFMDS050E DSS services not available

An attempt has been made to use DSS; however, it is not currently available. This may be due to a failure during initialization or configuration, or it may have been terminated during system shutdown while a transaction is still running.

Review the z/OS system log and the Mainframe Access job log and SYSOUT data sets for messages related to the failure. If you need further assistance contact Micro Focus SupportLine.

Parent topic: Data Set Services Messages


MFMDS052I CAPANVALET READY

MFA has initialized full access to CA/Panvalet services.

Parent topic: Data Set Services Messages


MFMDS053I CAENDEVOR API REL Brrvvv ESI

MFA has initialized full access to CA/Endevor API services using the release and version specified, and noting whether the External Security (ESI) or Alternate User ID (UID) features are active.

Parent topic: Data Set Services Messages


MFMDS054I Librarian Exit Table active

MFA has created a memory table to describe the selected exits to be specified during batch updates against the corresponding Librarian master file.

Parent topic: Data Set Services Messages


MFMDS055I MCGRPC feature (in)active

Indicates whether the MCGLIB DD card was specified as the LOAD library for remote calls as used by the Mainframe Call Generator (MCG) interface.

Parent topic: Data Set Services Messages


MFMDS056I ChangeMan DD=CMNxxxx Open failure

Access to site overrides specified for DD=CMNLIB$ and DD=CMNOPTS (to define default build procedures and site options repectively) failed during MFA startup.

Parent topic: Data Set Services Messages


MFMDS057I CAPANVALET member security exit loaded

The user exit MFAPVXIT was found and loaded to provide member-level security for Import, Export, and Directory access calls agains Panvalet master files.

Parent topic: Data Set Services Messages


MFMDS058I Librarian ELIPSGEN not found

This site configuration file is used to validate library types and language names for establishing Librarian run-time parameters. Without this information, new objects will default to TYPE=COB.

Parent topic: Data Set Services Messages


MFA Direct Messages

  • MFA0101I LOGON USER=userid TIME=hhmm DAY=nnn ID=nnnnnnn VER=nn
  • MFA0102I LOGOFF USER=userid ID=nnnnnnn
  • MFA0103I AUTH FAIL USER=userid RC=rc RACF=rr/ss
  • MFA0105I {AUTH or FAIL} USER=userid INTENT=action AM=method DSN=dsname
  • MFA0111E MFA INVALID DISPATCHING VERB
  • MFA0112E MFA MCB Environment failure
  • MFA0113E MFA TSA already in use
  • MFA0801E JES/SAPI RC=xx REASON=yy
  • MFA0802E I/O ERROR ON INTERNAL READER
  • MFA0803E JES SSI ERROR FUNC=xx RC=yy
  • MFA0804E JES STATUS RC=xx REASON=yy
  • MFA1034I CSI CATALOG ERROR nn RC=nnn REASON=nnn (ID) filter
  • MFA1035I CATALOG ERROR RC=nnn VOL=volid DSN=dsname
  • MFA1036I CSI VSAM ERROR RC=nnn REASON=nnn DSN=dsname
  • MFA1037I CSI GDGB ERROR RC=nnn REASON=nnn DSN=dsname
  • MFA4001E CA/LIBRARIAN ERROR REQ=aaaa RC=nnn
  • MFA4002E OPEN FAILED ON LIBRARIAN UPDATE
  • MFA4003E WRITE ERROR ON LIBRARIAN UPDATE
  • MFA5001E CA/PANVALET ERROR REQ=aaaa RC=nnn MSG=PVnnn
  • MFA5002E CA/PANVALET LICENSE FAILURE: access quiesced
  • MFA5003E CA/PANVALET PAN#1 error RC=nnnnn
  • MFA5004E I/O ERROR on PANVALET Temporary file
  • MFA6001E ENDEVOR API ERROR REQ=aaaa RC=nnn/rrrr/msgid
  • MFA6002E I/O ERROR ON ENDEVOR TEMPORARY FILE
  • MFA6003E SYNTAX ERROR ON ENDEVOR ENVIRONMENT STRING
  • MFA6004E ENDEVOR INTERFACE ABEND: abend-reason userid session-id
Parent topic: Mainframe Access Server Messages


MFA0101I LOGON USER=userid TIME=hhmm DAY=nnn ID=nnnnnnn VER=nn

This information message indicates the time and date that a user session was established with the MFA Direct component. The time is specified using 24-hour clock notation, and the day is the day of the year. The ID represents the relative session number so as to differentiate when the same user has logged on multiple times.

Parent topic: MFA Direct Messages


MFA0102I LOGOFF USER=userid ID=nnnnnnn

A user has logged off the system. This message is added to both the MFALOG and the SYSLOG.

Parent topic: MFA Direct Messages


MFA0103I AUTH FAIL USER=userid RC=rc RACF=rr/ss

A user logon failed to pass security authorization. The reason codes are tabulated below. MFA also inserts a logon failure message into the AUDIT log. Similarly, an IBM system diagnostic (RACF) may be added to the SYSLOG

RC | RACF | Description
04 | 04/00 | No decision made
 | 04/04 | No RACF profile found
 | 04/08 | Request failed
08 | 08/00 | Not authorized to logon
Parent topic: MFA Direct Messages


MFA0105I {AUTH or FAIL} USER=userid INTENT=action AM=method DSN=dsname

where:
action | is READ, WRITE or ALTER
method | is QSAM, BPAM, VSAM, LIBR, PANV, IMS or DB2
dsname | is the file being accessed

The results of a user access attempt are logged in the MFALOG. This provides an audit trail of the individual file accesses processed by MFA Direct. The information is only accumulated for those systems configured with the parameter: MFA_SAF_HISTORY=YES

Parent topic: MFA Direct Messages


MFA0111E MFA INVALID DISPATCHING VERB

MFA Direct has been scheduled with an invalid request. The request will not be serviced. This represents an internal protocol error by MFA. Please contact Micro Focus support if the problem persists.

Parent topic: MFA Direct Messages


MFA0112E MFA MCB Environment failure

MFA Direct is unable to initialize a new thread due to an unexpected environmental error. The new thread is rejected. Please contact Micro Focus support to report the problem.

Parent topic: MFA Direct Messages


MFA0113E MFA TSA already in use

An MFA thread has been unexpectedly re-dispatched while it is still processing a prior request. The new request is rejected. Please contact Micro Focus support to report the problem.

Parent topic: MFA Direct Messages


MFA0801E JES/SAPI RC=xx REASON=yy

A request using the JES Sysout API to retrieve a held file from JES spool has failed. Return codes and reason codes are documented in the IBM publication: Using the Subsystem Inferface (SC28-1879) A partial list is provided below:

RC | Reason | Description
08 |  | Invalid search argument(s)
12 |  | Unable to process now
16 |  | Duplicate job name
20 |  | Invalid destination
32 |  | Logic error
 | 32 | Conflicting arguments
 | 36 | Invalid destination arguments
 | 40 | Invalid job number
 | 44 | Invalid form
 | 96 | SAPI request header error
36 |  | Invalid CLASS
40 |  | Invalid disposition options
Parent topic: MFA Direct Messages


MFA0802E I/O ERROR ON INTERNAL READER

A request to submit a job to the JES internal reader has failed. The action is aborted. There may be an associated IBM system diagnostic on the SYSLOG indicating the nature of the failure.

Parent topic: MFA Direct Messages


MFA0803E JES SSI ERROR FUNC=xx RC=yy

A request using the JES Subsystem interface has failed. The only functions issued by MFA are FUNC=79 (SYSOUT API) or FUNC=80 (Extended Status API). Return codes and reason codes are described in the IBM publication: Using the Subsystem Interface (SC28-1879) A partial list is provided below:

RC | Description
04 | Function not supported
08 | JES not available
12 | JES does not exist
16 | Fatal error
20 | Logic error
24 | SSI not initialized
Parent topic: MFA Direct Messages


MFA0804E JES STATUS RC=xx REASON=yy

A request using the JES Extended Status API to acquire details of the next held output on JES spool has failed. Return codes and reason codes are documented in the IBM publication: Using the Subsystem Interface (SC28-1879) A partial list is provided below:

RC | Reason | Description
04 |  | Invalid search argument(s)
08 |  | Logic error
 | 04 | Invalid destination
 | 08 | Job ID low invalid
 | 0C | Job ID high invalid
 | 10 | Job ID high too low
 | 14 | Invalid Job class
 | 20 | Unable to access Job queue
 | 24 | Invalid control structure
 | 28 | Invalid length
 | 2C | Invalid job name
 | 30 | Invalid user name
 | 34 | Invalid system name
Parent topic: MFA Direct Messages


MFA1034I CSI CATALOG ERROR nn RC=nnn REASON=nnn (ID) filter

An error occurred within the Catalog Search Interface as provided by IBM as part of the DF/SMS z/OS middleware. The ID represents an internal IBM software module ID, and the filter is the Catalog Search argument derived from the client input. The return codes are described in the IBM publication DF/SMS Managing Catalogs (SC26-7401), but a partial list is shown below. Most other return codes and reason codes are documented as part of IBM System Message IDC3009I and can also be found using the IBM Web Service LOOKAT.

RC | REASON | Description
100 | 04 | Access error on catalog
122 | 04 | Invalid filter key
Parent topic: MFA Direct Messages


MFA1035I CATALOG ERROR RC=nnn VOL=volid DSN=dsname

An error occurred attempting to OBTAIN a catlog record for the specified dsname on the specified volume ID. The dsname may no longer be catalogued on that volume, and MFA is unable to determine the file attributes. It is possible that the volume is simply not mounted, or is no longer in active service. This file will be ignored and processing will continue. The return codes are described in the IBM publication DFSMSdfp Advanced Services (SC26-7400)

RC | Description
04 | Volume not mounted
08 | The format-1 DSCB was not found in the VTOC of the specified volume
12 | A permanent I/O error was encountered reading the VTOC of the specified volume
16 | An invalid workarea pointer was encountered
Parent topic: MFA Direct Messages


MFA1036I CSI VSAM ERROR RC=nnn REASON=nnn DSN=dsname

An error occurred attempting to use the CSI interface to identify the VSAM attributes of the specified dataset. This file will be ignored and processing continues. The return codes are as described for message MFA1034I.

Parent topic: MFA Direct Messages


MFA1037I CSI GDGB ERROR RC=nnn REASON=nnn DSN=dsname

An error occurred attempting to use the CSI interface to identify the file attributes of the specified generation data group. This file will be ignored and processing continues. The return codes are as described for message MFA1034I.

Parent topic: MFA Direct Messages


MFA4001E CA/LIBRARIAN ERROR REQ=aaaa RC=nnn

An internal CA/Librarian error occurred while processing the FAIR API request identified as: aaaa={OPN or LOC or MOD or REC or CLS} The return codes are described in the CA licensed documentation CA/Librarian File Access Interface Routines Guide. A partial list is provided below:

REQ | RC | Description
OPN | 1 | Invalid filename or unauthorized
 | 2 | DDname missing
 | 8 | Invalid parameter
 | 9 | Not enough storage to process
LOC | 1 | Required module not found
 | 2 | Caller not authorized for request
 | 6 | Disk access failure
 | 7 | Format error on access
 | 8 | Invalid parameter
 | 9 | Not enough storage to process
MOD | 1 | No modules found
 | 2 | Caller not authorized for request
 | 3 | Module not archived
 | 6 | Disk access failure
 | 7 | Format error on access
 | 8 | Invalid parameter
 | 9 | Virtual storage shortfall
REC | 1 | End of module
 | 6 | Disk access error
 | 7 | Format error on access
 | 8 | Invalid parameter
 | 9 | Virtual storage shortfall
CLS | 81 | Close failed
Parent topic: MFA Direct Messages


MFA4002E OPEN FAILED ON LIBRARIAN UPDATE

The system was unable to open a temporary work file for use with the batch update utility AFOLIBR in an attempted Librarian update operation. Additional information may be available on the SYSLOG if an associated IBM internal system problem was encountered. As well, a small MFA snap dump will be issued to provide additional problem determination data. No batch update will be attempted. If you are unable to resolve the problem, open an incident with Micro Focus product support, and include the Snap Dump and the MFALOG as part of the problem description.

Parent topic: MFA Direct Messages


MFA4003E WRITE ERROR ON LIBRARIAN UPDATE

The system was unable to write to a temporary work file for use with the batch update utility AFOLIBR. Additional information may be available on the SYSLOG if an associated IBM data access error was encountered. As well, a small MFA snap dump will be issued to provide additional problem determination data. No batch update will be attempted. The probable cause here is an attempt to write a record (from the workstation) which exceeds the logical record size of the work file.

Parent topic: MFA Direct Messages


MFA5001E CA/PANVALET ERROR REQ=aaaa RC=nnn MSG=PVnnn

An internal Panvalet error occurred while processing a PAM API request identified as: aaa={OPEN or CLS or READ or SRCH} The return codes and PanValet message numbers are documented within the CA licensed documentation: CA/Panvalet Messages Guide CA/Panvalet System Management Guide An incomplete summary follows:

Message | Description
PV001 | Invalid command
PV002 | Member name invalid
PV003 | Invalid sequence number
PV004 | Excessive parameters
PV005 | Required parameter missing
PV006 | Numeric parameter too large
PV007 | Parameter exceeds 10 characters
PV008 | Unsupported language format
PV009 | Invalid parameter
PV012 | No statement found
PV023 | Name not found
PV032 | Sequence error
PV033 | Library error
PV036 | Access error: member locked
PV043 | Library storage exceeded
PV046 | Panvalet library empty
PV047 | Virtual storage shortfall
PV051 | Invalid Library file
PV066 | Function terminated due to errors
PV070 | Statement truncated
PV095 | Invalid DCB for Library
PV118 | LRECL must be 80 for this language type
PV124 | Invalid file
Parent topic: MFA Direct Messages


MFA5002E CA/PANVALET LICENSE FAILURE: access quiesced

This site is not licensed to access the PanValet API. Further attempts to access PanValet will be suspended by MFA to avoid repetitive errors. Contact PanValet support to re-establish your license keys. Re-starting MFA will resume PanValet access attempts.

Parent topic: MFA Direct Messages


MFA5003E CA/PANVALET PAN#1 error RC=nnnnn

An internal Panvalet error was encountered while processing a batch update request using the PAN#1 utility. The return codes are described within the CA licensed documentation: CA/Panvalet Messages Guide CA/Panvalet User Guide

Parent topic: MFA Direct Messages


MFA5004E I/O ERROR on PANVALET Temporary file

A QSAM error was encountered while writing a temporary file needed as a pre-requisite for the PAN#1 batch update utility. Normally, an IBM system error will appear on the SYSLOG to describe the actual reason, The probable cause is an attempt to write a logical record from the workstation which exceeds the logical record size of the host file.

Parent topic: MFA Direct Messages


MFA6001E ENDEVOR API ERROR REQ=aaaa RC=nnn/rrrr/msgid

An Endevor internal processing error occurred while processing an API request identified as: aaaa={ERET or LELM or EADD} A copy of the actual Endevor error message is inserted into the MFALOGE listing if MFA_ENDEVOR_LOGGING is active. The return code, reason code, and Endevor message numbers are described in the licensed CA/Endevor documentation: Endevor for z/OS Messages and Codes Endevor for z.OS API Guide

Parent topic: MFA Direct Messages


MFA6002E I/O ERROR ON ENDEVOR TEMPORARY FILE

A QSAM error was encountered while writing a temporary file needed as a pre-requisite for an Endevor API request. Normally, an IBM system error will appear on the SYSLOG to describe the actual reason, The probable cause is an attempt to write a logical record from the workstation which exceeds the logical record size of the temporary file.

Parent topic: MFA Direct Messages


MFA6003E SYNTAX ERROR ON ENDEVOR ENVIRONMENT STRING

An invalid environment string was encountered during an Endevor request. The transaction is aborted. Use you client software to re-specify the Endevor prompts and properties correctly.

Parent topic: MFA Direct Messages


MFA6004E ENDEVOR INTERFACE ABEND: abend-reason userid session-id

The Mainframe Access ESTAE recovery routines detected an abend while processing an Endevor transaction. The transaction is aborted. The above message appears in the MFALOG showing the diagnostic abend code and reason code.

Parent topic: MFA Direct Messages


Data Connect Messages

  • MFA100E ESTAE ENTERED ABEND CODE Uxxx/Sxxx
  • MFA101E LIMIT OF 256 PROCESSES EXCEEDED
  • MFA110I VTAM PROCESSOR ACTIVE USING VTAMAPPL applid
  • MFA111W VTAM ACB CLOSE FAILURE
  • MFA112I VTAM PROCESSOR HAS TERMINATED
  • MFA113E USING VTAMAPPL applid ACB OPEN ERROR X"xx"
  • MFA114E APPC SESSION REJECTED PRI=xxxxxxxx SEC=xxxxxxxx
  • MFA115E MFA DOES NOT SUPPORT 3270 DATASTREAMS
  • MFA201W ERROR OPENING DDNAME=VSAMCTL
  • MFA202I ERROR READING VSAMCTL FOR membername
  • MFA299E ADDRESS SPACE NOT AUTHORIZED
  • MFA301E JCL PARM INVALID OR OMITTED
  • MFA302I ATTACHING VTAM PROCESSOR
  • MFA303I MFA/DATACONNECT V4.00 - vers
  • MFA310E INVALID OPERATOR REQUEST IGNORED
  • MFA311W PROCESS ALREADY RUNNING
  • MFA317I jobname HAS BEEN TERMINATED
Parent topic: Mainframe Access Server Messages


MFA100E ESTAE ENTERED ABEND CODE Uxxx/Sxxx

Data Connect has detected an abend. The client software is notified and the dump is normally suppressed. See the MVS console log for additional imformation.

Parent topic: Data Connect Messages


MFA101E LIMIT OF 256 PROCESSES EXCEEDED

Logic within Data Connect can manage up to 256 concurrent sessions. It is unable to retain positioning and recovery information for additional sessions.

Parent topic: Data Connect Messages


MFA110I VTAM PROCESSOR ACTIVE USING VTAMAPPL applid

Data Connect has successfully created a VTAM connection and is available to service message traffic using APPLID=applid.

Parent topic: Data Connect Messages


MFA111W VTAM ACB CLOSE FAILURE

Data Connect was unable to close the VTAM connection successfully. This may be a VTAM environmental problem. See the MVS console log for additional information. Shutdown processing continues without VTAM access.

Parent topic: Data Connect Messages


MFA112I VTAM PROCESSOR HAS TERMINATED

Data Connect is no longer servicing VTAM message traffic. Shutdown processing continues normally.

Parent topic: Data Connect Messages


MFA113E USING VTAMAPPL applid ACB OPEN ERROR X"xx"

Data Connect was unable to open the specified APPLID. Therefore, access cannot be provided to network clients. Common errors are identified as described below.

Error | Description
54 | APPLID not defined to VTAM
58 | APPLID already in use
5A | APPLID inactive to VTAM
Parent topic: Data Connect Messages


MFA114E APPC SESSION REJECTED PRI=xxxxxxxx SEC=xxxxxxxx

Data Connect was unable to complete the logon attempt. See the VTAM APPC documentation for a description of the primary and secondary return codes provided by IBM.

Parent topic: Data Connect Messages


MFA115E MFA DOES NOT SUPPORT 3270 DATASTREAMS

Data Connect does not support LU2 3270 data stream connections. Only APPC VTAM message traffic is supportted.

Parent topic: Data Connect Messages


MFA201W ERROR OPENING DDNAME=VSAMCTL

A file open error was encountered for the VSAM control file. Verify that DDNAME was provided in the Data Connect started task as shown in the sample JCL as MFAS. See the z/OS console log for additional error messages.

Parent topic: Data Connect Messages


MFA202I ERROR READING VSAMCTL FOR membername

A file read error was encountered for the indicated member name. The physical data may be corrupted. See the z/OS console log for additional error information.

Parent topic: Data Connect Messages


MFA299E ADDRESS SPACE NOT AUTHORIZED

The Data Connect modules must reside in an authorized library. The STEPLIB concatenation probably contains at least one load library which is not APF-authorized. Please call your system programmer to authorize your libraries.

Parent topic: Data Connect Messages


MFA301E JCL PARM INVALID OR OMITTED

The parm passed on the // EXEC PGM=MFDSTART,PARM='...' is invalid. The only keyword supported is APPLID=applid. Correct the JCL before resubmitting this job.

Parent topic: Data Connect Messages


MFA302I ATTACHING VTAM PROCESSOR

Data Connect is now initializing APPC access for client messages as relayed through the Host Connectivity interface.

Parent topic: Data Connect Messages


MFA303I MFA/DATACONNECT V4.00 - vers

This message identifies the Data Connect version and copyright information.

Parent topic: Data Connect Messages


MFA310E INVALID OPERATOR REQUEST IGNORED

An invalid operator command was sent to Data Connect. The command is being ignored.

Parent topic: Data Connect Messages


MFA311W PROCESS ALREADY RUNNING

VTAM APPC support is already active. It is not possible to re-cycle comminations while the APPLID is still active.

Parent topic: Data Connect Messages


MFA317I jobname HAS BEEN TERMINATED

The Data Connect task has been successfully terminated.

Parent topic: Data Connect Messages


Drag and Drop Error Messages

Refer to the table below for a list of possible error messages:

  • MFDAS01: Mainframe access problem.
  • MFDAS02: Cannot import multiple files to a single file.
  • MFDAS03: Cannot export multiple files to a single file.
  • MFDAS04: Module 'MFLSC' is missing or inaccessible.
  • MFDAS05: File had no length, or does not exist.
  • MFDAS06: Call to module 'DFCONV' failed. Unable to convert the VSAM/QSAM file.
  • MFDAS07: Value is not a valid number.
  • MFDAS08: For VSAM/QSAM files, extensions of PRO, DAT, or IDX are reserved.
  • MFDAS09: Rename to file failed.
  • MFDAS10: The allocation of failed with message number.
  • MFDAS11: The allocation of differs from the mainframe.
  • MFDAS12: One or more of the fields have not been properly entered.
  • MFDAS13: The PC file name cannot have more than 4 subdirectory levels.
  • MFDAS14: Mismatch between new and repeat passwords.
  • MFDAS15: Unable to make the directory.
  • MFDAS16: Unable to remove directory.
  • MFDAS17: Call to module 'PCIMS' failed. Unable to convert the IMS database.
  • MFDAS18: A catalog search criteria must be entered.
  • MFDAS19: A real workstation drive must be used.
  • MFDAS22: Call to module 'SQL-Wizard' failed. Unable to convert the XDB table.
  • MFDAS23: Cannot establish connection to the mainframe server.
  • MFDAS24: Network communication problems with blocks of size.
  • MFDAS25: CCI module was not found.
  • MFDAS26: Module is not a CCI module.
  • MFDAS27: Unable to delete file.
  • MFDAS28: Either recall this dataset or assign a type.
  • MFDAS29: Assign a type to this dataset.
  • MFDAS30: The workstation dataset is connected to the mainframe
  • MFDAS31: Copy of file failed.
  • MFDAS32: Paste of file failed.
  • MFDAS33: PCIMS is not available. Unable to convert the IMS database
  • MFDAS01: Mainframe access problem.
  • MFDAS02: Cannot import multiple files to a single file.
  • MFDAS03: Cannot export multiple files to a single file.
  • MFDAS04: Module 'MFLSC' is missing or inaccessible.
  • MFDAS05: File had no length, or does not exist.
  • MFDAS06: Call to module 'DFCONV' failed. Unable to convert the VSAM/QSAM file.
  • MFDAS07: Value is not a valid number.
  • MFDAS08: For VSAM/QSAM files, extensions of PRO, DAT, or IDX are reserved.
  • MFDAS09: Rename to file failed.
  • MFDAS10: The allocation of failed with message number.
  • MFDAS11: The allocation of differs from the mainframe.
  • MFDAS12: One or more of the fields have not been properly entered.
  • MFDAS13: The PC file name cannot have more than 4 subdirectory levels.
  • MFDAS14: Mismatch between new and repeat passwords.
  • MFDAS15: Unable to make the directory.
  • MFDAS16: Unable to remove directory.
  • MFDAS17: Call to module 'PCIMS' failed. Unable to convert the IMS database.
  • MFDAS18: A catalog search criteria must be entered.
  • MFDAS19: A real workstation drive must be used.
  • MFDAS22: Call to module 'SQL-Wizard' failed. Unable to convert the XDB table.
  • MFDAS23: Cannot establish connection to the mainframe server.
  • MFDAS24: Network communication problems with blocks of size.
  • MFDAS25: CCI module was not found.
  • MFDAS26: Module is not a CCI module.
  • MFDAS27: Unable to delete file.
  • MFDAS28: Either recall this dataset or assign a type.
  • MFDAS29: Assign a type to this dataset.
  • MFDAS30: The workstation dataset is connected to the mainframe
  • MFDAS31: Copy of file failed.
  • MFDAS32: Paste of file failed.
  • MFDAS33: PCIMS is not available. Unable to convert the IMS database
Parent topic: Mainframe Access Server Messages
Parent topic: Drag and Drop
Related information
Enterprise


MFDAS01: Mainframe access problem.

Return Code

1001

Description

A communication problem has been detected. Refer to the MFAERROR.LOG file for more information.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS02: Cannot import multiple files to a single file.

Return Code

1002

Description

An illogical request has been made, in that the user is attempting to import more than one file into a single file.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS03: Cannot export multiple files to a single file.

Return Code

1003

Description

An illogical request has been made, in that the user is attempting to export more than one file into a single file.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS04: Module 'MFLSC' is missing or inaccessible.

Return Code

1004

Description

The required module MFLSC cannot be found. This is most likely an installation problem.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS05: File had no length, or does not exist.

Return Code

1005

Description

The file had either a zero length, or had been deleted but the display was not refreshed.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS06: Call to module 'DFCONV' failed. Unable to convert the VSAM/QSAM file.

Return Code

1006

Description

A bad return code was given by the converter program. Run the dfconv program on its own to determine the error.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS07: Value is not a valid number.

Return Code

1007

Description

A non-numeric value was given when a numeric value was expected.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS08: For VSAM/QSAM files, extensions of PRO, DAT, or IDX are reserved.

Return Code

1008

Description

You cannot use a restricted extension for a file transfer.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS09: Rename to file failed.

Return Code

1009

Description

An error was returned when trying to rename a file.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS10: The allocation of failed with message number.

Return Code

1010

Description

An error message has been returned from the COBOL development environment. See the product documentation for a description of the message.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS11: The allocation of differs from the mainframe.

Return Code

1011

Description

The DCB information for the COBOL development environment dataset differs from that of the mainframe.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS12: One or more of the fields have not been properly entered.

Return Code

1012

Description

Insufficient or incorrect information has been provided in the panel.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS13: The PC file name cannot have more than 4 subdirectory levels.

Return Code

1013

Description

The COBOL development environment is unable to support more than 4 subdirectory levels.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS14: Mismatch between new and repeat passwords.

Return Code

1014

Description

The new and repeat passwords given do not match.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS15: Unable to make the directory.

Return Code

1015

Description

An error was returned when trying to create a directory.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS16: Unable to remove directory.

Return Code

1016

Description

An error was returned when trying to remove a directory.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS17: Call to module 'PCIMS' failed. Unable to convert the IMS database.

Return Code

1017

Description

A bad return code was given by the PCIMS program. Run the PCIMS program on its own to determine the error.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS18: A catalog search criteria must be entered.

Return Code

1018

Description

You must enter one or more mainframe catalog search criteria. If specifying more than one, then separate them by commas. This catalog search criteria is similar to that when using ISPF 3.4.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS19: A real workstation drive must be used.

Return Code

1019

Description

The drive selected for the COBOL development environment dataset does not exist on this workstation.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS22: Call to module 'SQL-Wizard' failed. Unable to convert the XDB table.

Return Code

1022

Description

A bad return code was given by the SQL wizard program. Run the SQL wizard program on its own to determine the error.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS23: Cannot establish connection to the mainframe server.

Return Code

1023

Description

Unable to connect to the mainframe server.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS24: Network communication problems with blocks of size.

Return Code

1024

Description

The user's network is unable to transport a data block of the size specified. This is most likely a router configuration problem. To temporarily circumvent the problem, you can specify the MFAMAXSENDLENGTH environment variable, with the value set to a size below the size in error.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS25: CCI module was not found.

Return Code

1025

Description

The CCI communications file is not found.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS26: Module is not a CCI module.

Return Code

1026

Description

The module specified is not a CCI communications file.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS27: Unable to delete file.

Return Code

1027

Description

An error was returned when trying to delete a file.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS28: Either recall this dataset or assign a type.

Return Code

1028

Description

This dataset is migrated. Either use the right-mouse context to recall it, or assign a specific type.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS29: Assign a type to this dataset.

Return Code

1029

Description

Unknown DSORG for this dataset. You need to use the right-mouse context to assign a specific type.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS30: The workstation dataset is connected to the mainframe

Return Code

1030

Description

This workstation dataset you are tying to access is redirection to a mainframe dataset.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS31: Copy of file failed.

Return Code

1031

Description

Unable to copy from the Windows clipboard.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS32: Paste of file failed.

Return Code

1032

Description

Unable to paste the file to the Windows clipboard.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


MFDAS33: PCIMS is not available. Unable to convert the IMS database

Return Code

1033

Description

The PCIMS.LBR routines could not be found, or a project was not open.

Parent topic: Drag and Drop Error Messages
Parent topic: Drag and Drop Error Messages


Status Codes and Error Messages

This section contains a list of status codes that Mainframe Access servers can return to a client program. It also documents the anomalies in file status settings based upon the environment in which the I/O statements are executed.

Note: For additional information on MFA messages, see your Mainframe Access Administrator's Guide.
  • Status Codes Returned by the MVS Server
  • File Status Comparisons
Parent topic: Mainframe Access Messages


Status Codes Returned by the MVS Server

Table 1. File Status Codes Returned by the MVS Server
Status Code | Description
0/0 | The MVS server returns a status of 0/0 when writing a record to an indexed file which results in two or more records with identical keys. Both IBM VS COBOL II batch processing and Micro Focus COBOL return a status of 0/2 when such a condition arises.
0/5 | A file status 0/5 indicates an open operation was successful, but the file is empty. A file status of 0/5 is returned in some cases where IBM VS COBOL II returns a status of 0/0 and in other cases where IBM VS COBOL II returns a status of 3/5. See the appendix File Status Comparisons for some examples of the conditions under which this status code is returned during open processing.
4/3 | A status code of 4/3 is returned if an attempt is made to delete a VSAM record via an alternate index, if another record in that file contains the same key as the record being deleted.
4/6 | If an I/O operation is attempted which requires a previous I/O operation to have set the current record pointer, and the previous I/O operation failed, a file status of 4/6 is returned. It is also issued if the MVS server loses track of the current record position, probably due to an invalid sequence of I/O statements.
9/100 | A file status of 9/100 is returned if the MVS server receives an operation code that it does not support. This status is also returned when the server attempts to execute a command at a time when that command is invalid. In this case, the operation code received by the server was valid, but the I/O operation was invalid given the type of operation requested and the nature of the previous I/O operations executed for the file.
9/125 | A status code of 9/125 will be returned when the maximum number of concurrent Users has been exceeded.
9/242 | The requested function or component has not been licensed.
Parent topic: Status Codes and Error Messages
Related information
Enterprise


File Status Comparisons

This section documents the anomalies in file status settings based upon the environment in which the I/O statements are executed. Expected results, including expected anomalies (for example, the order of records returned when reading an alternate index in reverse order), are not included in this list unless they help clarify the conditions under which the anomalies were detected.

These results were compiled from a set of test programs executed in the following three environments:

  • MVS-batch using IBM VS COBOL II accessing VSAM datasets
  • OS/2 using Micro Focus COBOL accessing sequential
  • Relative and indexed files

The test programs used an extensive combination of file definitions (organization and access mode), open types (INPUT, I/O, OUTPUT, EXTEND, etc.), and I/O verbs for example READ, WRITE, REWRITE) to examine the behavior of execution environment and the results of the file status information returned to the test programs.

In the Cross Reference of File Status Setting table that follows, file status information obtained for the tests in each environment is displayed in the format 'a/b', where 'a' represents the first byte of the file status (file status 1) and 'b' represents the second byte of the file status (file status 2).

For run-time errors, the first byte displayed is '9' and the value for the second byte is the ordinal value of the file status 2 field (e.g. 9/100). When an I/O operation is invalid, a key of 'N/A' is used. When an I/O operation is valid but was not tested because of the results of an earlier I/O operations, a file status of '-/-' is used.

  • Cross Reference of File Status Setting
Parent topic: Status Codes and Error Messages


Cross Reference of File Status Setting

READ SEQUENTIAL TEST WITH EMPTY FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
SEQ SEQ | OPEN I/O | 3/5 | 0/5 | 0/5
 | READ NEXT | -/- | 1/0 | 1/0
SEQ SEQ | OPEN I/O REVERSED | N/A | 0/0 | 0/5
 | READ NEXT | -/- | 1/0 | 1/0
REL SEQ | OPEN I/O | 3/5 | 0/5 | 0/5
 | READ NEXT | -/- | 1/0 | 1/0
REL SEQ | OPEN I/O | 3/5 | 0/5 | 0/5
 | START RRN=20 | -/- | 2/3 | 2/3
REL SEQ | OPEN I/O | 3/5 | 0/0 | 3/5
 | START RRN=0 | -/- | 2/3 | -/-
IDX SEQ | OPEN INPUT | 0/0 | 3/5 | 0/0
 | READ NEXT | 1/0 | -/- | 1/0
IDX SEQ | OPEN I/O | 0/0 | 0/5 | 0/0
 | START KEY < VALUE | N/A | 2/3 | 2/3

When Micro Focus COBOL attempts to open a sequential dataset for I/O REVERSED processing and that dataset does not exist, a status code of 3/5 is returned. If the dataset does exist but is empty, a status code of 0/0 is returned on the open request.

WRITE SEQUENTIAL TEST WITH EMPTY FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX SEQ | OPEN OUTPUT | 0/0 | 0/0 | 0/0
 | WRITE (RECORD W/DUPLICATE ALT KEY) | 0/2 | 0/2 | 0/0
IDX SEQ | OPEN EXTEND | 0/0 | 0/0 | 0/0
 | WRITE (RECORD W/DUPLICATE ALT KEY) | 0/2 | 0/2 | 0/0

The CICS server cannot determine if the result of this write operation would cause any alternate indexes to have two or more records with the same key value.

DELETE SEQUENTIAL TEST

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX SEQ | OPEN I/O | 0/0 | 0/0 | 0/0
 | START ALT KEY GTEQ LOW-VALUES | 0/0 | 0/2 | 0/0
 | DELETE | 0/0 | 0/0 | 1/0

The CICS server does not permit the deletion of a record via the alternate index if another record in the file has the same key for the alternate index. A status code of 4/3 is returned. The current record position is unaffected by the failed request.

RANDOM WRITE TEST

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX RAN | OPEN I/O | 0/0 | 0/0 | 0/0
 | WRITE (RECORD W/DUPLICATE ALT KEY) | 0/2 | 0/2 | 0/0

The CICS server cannot determine if the result of this write operation would cause any alternate indexes to have two or more records with the same key value.

READ SEQUENTIAL TEST WITH DATA IN FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX SEQ | OPEN INPUT | 0/0 | 0/0 | 0/0
 | START KEY GTEQ HIGH-VALUES | 2/3 | 2/3 | 0/0
 | READ NEXT | -/- | -/- | 1/0

VSAM treats this as: 'position the current record pointer to the end of the file'; a subsequent READ PREVIOUS request would return the last record in the file.

READ DYNAMIC TEST WITH DATA IN FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX DYN | OPEN INPUT | 0/0 | 0/0 | 0/0
 | START KEY GTEQ HIGH-VALUES | 2/3 | 2/3 | 0/0
 | READ NEXT | -/- | -/- | 1/0

VSAM treats this as: 'position the current record pointer to the end of the file'; a subsequent READ PREVIOUS request would return the last record in the file.

DELETE DYNAMIC TEST WITH DATA IN FILES

FILE ORG-ACC | I/O statements | MVS-BATCH COBOL II | OS/2 MF/COBOL | CICS server
IDX DYN | OPEN I/O | 0/0 | 0/0 | 0/0
 | START ALT KEY GTEQ LOW-VALUES | 0/0 | 0/0 | 0/0
 | READ NEXT (DUPLICATE KEY) | 0/2 | 0/2 | 0/2
 | READ NEXT (LAST OF DUPLICATE KEY) | 0/0 | 0/0 | 0/0
 | DELETE (LAST OF DUPLICATE KEY) | 0/0 | 0/0 | 4/3

The CICS server does not permit the deletion of a record via the alternate index if another record in the file has the same key for the alternate index. A status code of 4/3 is returned. The current record position is unaffected by the failed request.

Parent topic: File Status Comparisons


Configuration reference

You can configure many aspects of z/Server's behavior by using any of z/Server's configuration parameters.

  • Mainframe Access Server configuration parameters
  • Mainframe Access Server z/Server feature configuration parameters
Parent topic: Mainframe Access Installation Guide


Mainframe Access Server configuration parameters

  • Configuration parameters - quick reference
  • Configuration parameters - alphabetical list
Parent topic: Configuration reference


Configuration parameters - quick reference

The following list provides Mainframe Access Server configuration parameters and for each parameter, which servers and services it applied to:

Parameter | General | Application Servers |  |  |  | Services
 |  | Data Connect | Endevour | ChangeMan | AMS | RIMS | MCO | MFA | ES-MTO
ACBNAME | N | N | N | N | N | N | N | N | Y
ACCESS_LIST_CHECK | Y | N | Y | Y | Y | N | N | N | N
APPLID_PASSWORD | Y | N | N | N | N | N | N | N | N
AUDIT_LOG | Y | N | N | N | N | N | N | N | N
BACK_LOG | Y | N | N | N | N | N | N | N | N
BIND_NETADDR | Y | N | N | N | N | N | N | N | N
BUFFER_SIZE | Y | N | Y | Y | Y | N | N | N | N
CHANGEMAN_COMMON_BUILD | Y | N | N | N | N | N | N | N | N
CHANGEMAN_DSNQUALIFIER | Y | N | N | N | N | N | N | N | N
CHANGEMAN_INTERFACE | Y | N | N | N | N | N | N | N | N
CHANGEMAN_SSID | Y | N | N | N | N | N | N | N | N
CHANGEMAN_TEST_OPTION | Y | N | N | N | N | N | N | N | N
CHANGEMAN_XMS_SIZE | Y | N | N | N | N | N | N | N | N
COMPRESSION | Y | N | Y | Y | Y | N | N | N | N
DSS_SCAN_INTERVAL | Y | N | Y | Y | Y | N | N | N | N
EID | Y | N | Y | Y | Y | N | N | N | N
ENDEVOR_DSNQUALIFIER | Y | N | N | N | N | N | N | N | N
ES-MTO_MAXTASKS | Y | N | N | N | N | N | N | N | N
ID | N | N | N | N | N | Y | Y | Y | Y
IMSLINK_MAXTASKS | Y | N | N | N | N | N | N | N | N
IPADDRESS | N | N | N | N | N | N | N | N | Y
JES_BUFFER_TRACE | Y | N | N | N | N | N | N | N | N
JES_CONCHAR | Y | N | N | N | N | N | N | N | N
JOBNAME | N | N | Y | Y | Y | N | N | N | N
LIST_DB2 | Y | N | N | N | N | N | N | N | N
LIST_PARAMETERS | Y | N | Y | Y | Y | N | N | N | N
LU62_APPLID | Y | N | N | N | N | N | N | N | N
LUNAME | N | N | N | N | N | Y | Y | Y | N
MAX_DS_ALLOCATIONS | Y | N | N | N | N | N | N | N | N
MAX_PUBLIC_FILES | Y | N | N | N | N | N | N | N | N
MAXIMUM | N | N | Y | Y | Y | N | N | N | N
MCOLINK_MAXTASKS | Y | N | N | N | N | N | N | N | N
MFA_ACCEPT_EMPTY_FILES | Y | N | N | N | N | N | N | N | N
MFA_ENDEVOR_HISTORY | Y | N | N | N | N | N | N | N | N
MFA_ENDEVOR_INTERFACE | Y | N | N | N | N | N | N | N | N
MFA_GUI_ACCEPT_PASSPHRASES | Y | N | N | N | N | N | N | N | N
MFA_GUI_BLANKPASSWORD | Y | N | N | N | N | N | N | N | N
MFA_GUI_IGNOREUSERCTO | Y | N | N | N | N | N | N | N | N
MFA_JOBNAME_CHECK | Y | N | N | N | N | N | N | N | N
MFA_LIBRARIAN_DIR_INFO | Y | N | N | N | N | N | N | N | N
MFA_LIBRARIAN_HISTORY | Y | N | N | N | N | N | N | N | N
MFA_LIBRARIAN_INTERFACE | Y | N | N | N | N | N | N | N | N
MFA_LIBRARIAN_UPD_MODULE | Y | N | N | N | N | N | N | N | N
MFA_MCG_DB2CONNECTION | Y | N | N | N | N | N | N | N | N
MFA_PANVALET_HISTORY | Y | N | N | N | N | N | N | N | N
MFA_PANVALET_INTERFACE | Y | N | N | N | N | N | N | N | N
MFA_PANVALET_UPD_MODULE | Y | N | N | N | N | N | N | N | N
MFA_SAF_HISTORY | Y | N | N | N | N | N | N | N | N
MFA_SYSOUT_CLASS | Y | N | N | N | N | N | N | N | N
MFA_SYSOUT_DEST | Y | N | N | N | N | N | N | N | N
MFADIRECT | Y | N | N | N | N | N | N | N | N
MFADIRECT_MAXTASKS | Y | N | N | N | N | N | N | N | N
MFALINK_MAXTASKS | Y | N | N | N | N | N | N | N | N
MINIMUM | N | N | Y | Y | Y | N | N | N | N
MODENAME | N | N | N | N | N | Y | Y | Y | N
NETWORK_ID | Y | N | N | N | N | N | N | N | N
ORGANIZATION | Y | N | N | N | N | N | N | N | N
PEM_FEATURE | Y | N | N | N | N | N | N | N | N
PORT | N | N | N | N | N | N | N | N | Y
PROCEDURE | N | Y | Y | Y | Y | N | N | N | N
RACF_APPLID | Y | N | N | N | N | N | N | N | N
ROUTE | Y | N | Y | Y | Y | N | N | N | N
SECURITY | N | N | N | N | N | Y | Y | Y | N
SESSIONS | N | N | N | N | N | N | N | N | Y
SMF_RECORDID | Y | N | Y | Y | Y | N | N | N | N
SOCKETS | N | N | N | N | N | N | N | N | Y
SYNCLEVEL | N | N | N | N | N | Y | Y | Y | N
SYSOUT | Y | N | Y | Y | Y | N | N | N | N
TCP_PORT | Y | N | N | N | N | N | N | N | N
TCPLINK_MAXTASKS | Y | N | N | N | N | N | N | N | N
TIMEOUT_FOR_CONNECTION | Y | N | Y | Y | Y | N | N | N | N
TIMEOUT_FOR_INITIAL_RECEIVE | Y | N | N | N | N | N | N | N | N
TPNAME | N | N | N | N | N | Y | Y | Y | N
TRACE | Y | N | Y | Y | Y | N | N | N | N
TRACING | Y | N | Y | Y | Y | N | N | N | N
VIO_FOR_ENDEVOR_LOG | N | N | Y | N | N | N | N | N | N
Parent topic: Mainframe Access Server configuration parameters


Configuration parameters - alphabetical list

  • ACBNAME
  • ACCESS_LIST_CHECK
  • APPLID_PASSWORD
  • AUDIT_LOG
  • BACK_LOG
  • BIND_NETADDR
  • BUFFER_SIZE
  • CHANGEMAN_COMMON_BUILD
  • CHANGEMAN_DSNQUALIFIER
  • CHANGEMAN_INTERFACE
  • CHANGEMAN_SSID
  • CHANGEMAN_TEST_OPTION
  • CHANGEMAN_XMS_SIZE
  • COMPRESSION
  • DSS_SCAN_INTERVAL
  • EID
  • ENDEVOR_DSNQUALIFIER
  • ES-MTO_MAXTASKS
  • ID
  • IMSLINK_MAXTASKS
  • IPADDRESS
  • JES_BUFFER_TRACE
  • JES_CONCHAR
  • JOBNAME
  • LIST_DB2
  • LIST_PARAMETERS
  • LU62_APPLID
  • LUNAME
  • MAX_DS_ALLOCATIONS
  • MAX_PUBLIC_FILES
  • MAXIMUM
  • MCOLINK_MAXTASKS
  • MFA_ACCEPT_EMPTY_FILES
  • MFA_ENDEVOR_HISTORY
  • MFA_ENDEVOR_INTERFACE
  • MFA_GUI_ACCEPT_PASSPHRASES
  • MFA_GUI_BLANKPASSWORD
  • MFA_GUI_IGNORUSERCTO
  • MFA_JOBNAME_CHECK
  • MFA_LIBRARIAN_DIR_INFO
  • MFA_LIBRARIAN_HISTORY
  • MFA_LIBRARIAN_INTERFACE
  • MFA_LIBRARIAN_UPD_MODULE
  • MFA_MCG_DB2CONNECTION
  • MFA_PANVALET_HISTORY
  • MFA_PANVALET_INTERFACE
  • MFA_PANVALET_UPD_MODULE
  • MFA_SAF_HISTORY
  • MFA_SYSOUT_CLASS
  • MFA_SYSOUT_DEST
  • MFADIRECT
  • MFADIRECT_MAXTASKS
  • MFALINK_MAXTASKS
  • MINIMUM
  • MODENAME
  • NETWORK_ID
  • ORGANIZATION
  • PEM_FEATURE
  • PORT
  • PROCEDURE
  • RACF_APPLID
  • ROUTE
  • SECURITY
  • SESSIONS
  • SMF_RECORDID
  • SOCKETS
  • SYNCLEVEL
  • SYSOUT
  • TCP_PORT
  • TCPLINK_MAXTASKS
  • TIMEOUT_FOR_CONNECTION
  • TIMEOUT_FOR_INITIAL_RECEIVE
  • TPNAME
  • TRACE
  • TRACING
  • VIO_FOR_ENDEVOR_LOG
  • AUTOSTART
  • BUFFERSIZE
  • CCSID
  • CEA_ACCOUNT
  • CEA_CHARSET
  • CEA_CODEPAGE
  • CEA_INIT_CMD
  • CEA_LOGONPROC
  • CEA_REGION_SIZE
  • CEA_SCR_SIZE
  • DEF_USRSRV_MODE
  • DELAY
  • DIALOG_TIMEOUT
  • DSP_PROTECT
  • DSP_TOKEN
  • ECB_TIMEOUT
  • FIRST_PORT
  • IPSTACK
  • IPTRACE
  • ISPF_STATS
  • JOBNAME
  • LAST_PORT
  • LISTENER_PORT
  • LOGON_EXIT
  • MAIL_CLASS
  • MAIL_MSGCNT
  • MAIL_NOTIFY
  • MAIL_SEVERITY
  • MAIL_WRITER
  • MAXUSRV
  • MSGCLASS
  • MULTI_REXX_S
  • MULTI_REXX_U
  • NOFTASK
  • NUMTCB
  • PORTCHECK
  • RACF_APPLID
  • RACF_STATS
  • SCHEDULER_NAME
  • SUBMIT_DELAY
  • SVC_NO
  • TIMEOUT
  • TSOE_JOBCHAR
  • TSOE_NOTIFY
  • USER_SERVER_JOBNAME
  • USRSRV_TIMEOUT
  • USS_DUBPROCESS
  • VIPA
  • VPOOLSIZE
Parent topic: Mainframe Access Server configuration parameters
Parent topic: Mainframe Access Server z/Server feature configuration parameters


ACBNAME

Name
ACBNAME
Summary
The name of the VTAM ACB associated with this ES/MSS server. MFA Server OPENs and initializes this ACBNAME during startup. The z/OS CICS system(s) must be configured to communicate with this ES/MSS server through this VTAM ACB name using CICS CONNECTION and SESSIONS definition statements.
Default
NULL
Supported Values
Value | Description
acbname | A valid VTAM ACBNAME.
Example
ACBNAME="acbname"
Parent topic: Configuration parameters - alphabetical list


ACCESS_LIST_CHECK

Name
ACCESS_LIST_CHECK
Summary
Indicates whether or not the access list feature is to be activated for clients. This enables you to restrict access to Mainframe Access according to the connecting client's IP address. See Editing Access List Definitions for more information. Specify 0 to accept all client connection requests, regardless of the client's IP address. Specify 1 to permit client connections based on the PERMIT and REJECT rules for IP addresses defined in your access list.
Default
0
Supported Values
Value | Description
0 | Allow client access regardless if the clients IP address.
1 | Restrict client access based on PERMIT and REJECT rules.
Example
ACCESS_LIST_CHECK="1"
Parent topic: Configuration parameters - alphabetical list


APPLID_PASSWORD

Name
APPLID_PASSWORD
Summary
The ACF/VTAM ACB password to be used when Mainframe Access opens its VTAM ACB. Specify a password consisting of between one and eight characters. This value must match the password value specified by the PRTCT parameter in the Mainframe Access VTAM application program major node definition in VTAMLST.
Default
MFM62PSW
Supported Values
Value | Description
applidpswd | A valid VTAM APPLID password.
Example
APPLID_PASSWORD="applidpswd"
Parent topic: Configuration parameters - alphabetical list


AUDIT_LOG

Name
AUDIT_LOG
Summary
Indicates whether or not the audit log is to be activated. Specify 1 to activate or 0 to deactivate. If audit logging is selected, be sure to complete the tasks described in Allocating and Initializing an Audit Log Data Set.
Default
0
Supported Values
Value | Description
0 | Deactivate audit logging.
1 | Activate audit logging.
Example
AUDIT_LOG="1"
Parent topic: Configuration parameters - alphabetical list


BACK_LOG

Name
BACK_LOG
Summary
The number of pending TCP/IP connection requests that the TCP/IP network software should hold while Mainframe Access is processing the current connection request. Connection processing is typically handled very quickly and a small backlog of between 5 and 10 should be adequate for most installations. If you have an unusually high number of concurrent connection requests, some end users might receive a connection reject message. Specify a positive integer value in the range 5 through 50.
Default
5
Minimum Value
5
Maximum Value
50
Example
BACK_LOG="10"
Parent topic: Configuration parameters - alphabetical list


BIND_NETADDR

Name
BIND_NETADDR
Summary
Selects the network address(es) to which the Mainframe Access listening port (TCP_PORT) should be bound. Specify 0.0.0.0 (or omit this parameter) to bind the ports to all network addresses assigned to the host system. Specify a specific network address or a logical host name (64-character maximum) to restrict Mainframe Access to a single, specific host network address.
Default
0.0.0.0
Supported Values
Value | Description
bindnetaddr | A valid IP address or logical host name.
Example
BIND_NETADDR="bindnetaddr"
Parent topic: Configuration parameters - alphabetical list


BUFFER_SIZE

Name
BUFFER_SIZE
Summary
The maximum amount of data that Mainframe Access should send or receive through the TCP/IP network software in one send or receive operation. Specify 0 (zero) to allow Mainframe Access to use the optimum buffer size; this is recommended, as it will reduce the number of send or receive calls made to the TCP/IP network software. Specify an explicit value in the range 512 to 32767 only if you have diagnosed a problem with your TCP/IP network software that is associated with large message sizes.
Default
0
Minimum Value
512
Maximum Value
32767
Example
BUFFER_SIZE="600"
Parent topic: Configuration parameters - alphabetical list


CHANGEMAN_COMMON_BUILD

Name
CHANGEMAN_COMMON_BUILD
Summary
Specifies whether or not Mainframe Access accommodates group builds submitted under AppMaster Builder. Specify 1 to enable group builds or 0 to disable them. The default is 0. When enabled for group builds, MFA modifies the build options for each member of the AMB group to match the component name and type submitted, ensuring that each build request in the group is properly executed.
Default
0
Supported Values
Value | Description
0 | Disable group builds.
1 | Enable group builds.
Example
CHANGEMAN_COMMON_BUILD="1"
Parent topic: Configuration parameters - alphabetical list


CHANGEMAN_DSNQUALIFIER

Name
CHANGEMAN_DSNQUALIFIER
Summary
Specifies a high-level qualifier for dynamically allocated data sets created by MFA Server to hold input files during the staging process. MFA Server creates these data sets dynamically as card-image sequential data sets that are deleted when the associated client request completes. The default qualifier is the login ID of the current user. You should set an alternate qualifier if your installation's SERNET does not have RACF authority to read or write data into files stored in data sets named with the current user's login ID as the high-level qualifier.

If an alternate qualifier is required, see your ChangeMan administrator or your security administrator for assistance in selecting a proper value.

If your ChangeMan functionality is restricted by security subsystem authorizations, you might need to specify your dataset high-level qualifier such that read access to the data sets is always permitted.

Default
NULL
Supported Values
Value | Description
changemands | A valid dataset HLQ.
Example
CHANGEMAN_DSNQUALIFIER="changemandsn"
Parent topic: Configuration parameters - alphabetical list


CHANGEMAN_INTERFACE

Name
CHANGEMAN_INTERFACE
Summary
Specifies the name of the ChangeMan ZMF module. During ChangeMan request processing, MFA Server loads and branch enters this module. Valid values are SERXMLBC and SERXMLAC. The default is SERXMLAC.

The preferred interface module is SERXMLAC, which is not documented in ChangeMan ZMF. It provides better interface performance than SERXMLBC by using virtual storage instead of data sets for XML input and output exchange between MFA Server (the requester) and ChangeMan ZMF.

ChangeMan ZMF documents only the SERXMLBC interface, which is the XML services batch client. SERXMLBC is intended for use in a batch job stream and requires XMLIN and XMLOUT DD statements to define its required data sets. The MFAAS JCL sample provides sample DD statements for XMLIN and XMLOUT which are commented out by default. If you must use SERXMLBC, contact SupportLine for assistance with data set definitions.

Default
SERXMLAC
Supported Values
Value | Description
SERXMLAC | Use XML to interface with ChangeMan.
SERXMLBC | Use batch client to interface with ChangeMan.
Example
CHANGEMAN_INTERFACE="SERXMLBC"
Parent topic: Configuration parameters - alphabetical list


CHANGEMAN_SSID

Name
CHANGEMAN_SSID
Summary
Initializes the Mainframe Access ChangeMan interface by providing the final character of the z/OS subsystem ID used to identify ChangeMan. Omit this parameter to bypass Mainframe Access initialization for the ChangeMan interface. Valid values are any single alphabetic or numeric character. The character specified is appended to the subsystem ID string "SER", completing the four-character ID. For example, if you specify CHANGEMAN_SSID=A, the z/OS subsystem ID becomes "SERA".

This parameter is required in both the PARMS member and the PARMSAS member used by application server address spaces.

Your ChangeMan administrator can help you to determine the correct subsystem ID to use.

Default
NULL
Supported Values
Value | Description
changemanssid | Any single alphabetic or numeric character.
Example
CHANGEMAN_SSID="changemanssid"
Parent topic: Configuration parameters - alphabetical list


CHANGEMAN_TEST_OPTION

Name
CHANGEMAN_TEST_OPTION
Summary
Specify whether or not MFA uses the XML trace option. Specify 1 to enable XML trace or 0 to disable it. The default is 0. When enabled, SERNET logs information in XML format into the standard SERPRINT DD file. This file can be used to identify problems and to validate MFA services. Enabling XML trace is not recommended for production systems due to the large volume of log data generated.
Default
0
Supported Values
Value | Description
0 | Disable MFA ChangeMan XML tracing.
1 | Enable MFA ChangeMan XML tracing.
Example
CHANGEMAN_TEST_OPTION="1"
Parent topic: Configuration parameters - alphabetical list


CHANGEMAN_XMS_SIZE

Name
CHANGEMAN_XMS_SIZE
Summary
The size of the XML buffer used to receive members when using ChangeMan.
Default
1
Minimum Value
1
Maximum Value
8
Example
CHANGEMAN_XMS_SIZE="5"
Parent topic: Configuration parameters - alphabetical list


COMPRESSION

Name
COMPRESSION
Summary
Indicates whether or not Mainframe Access should apply data compression when communicating with SQL Option for DB2 clients. Specify 1 to activate data compression or 0 to deactivate it.
Default
0
Supported Values
Value | Description
0 | Deactivate data compression.
1 | Activate data compression.
Example
COMPRESSION="1"
Parent topic: Configuration parameters - alphabetical list


DSS_SCAN_INTERVAL

Name
DSS_SCAN_INTERVAL
Summary
The time period in minutes between Data Set Services checks for abandoned buffers or open files. Due to unforeseen environmental errors, transactions may abnormally terminate while holding open files and other I/O resources. These scans locate idle resources and return them to an available status and ensure that no file is held idle for more than two consecutive scan intervals. Specify the number of minutes as an integer value between 30 and 90. The default is 30 minutes.
Default
30
Minimum Value
30
Maximum Value
90
Example
DSS_SCAN_INTERVAL="80"
Parent topic: Configuration parameters - alphabetical list


EID

Name
ACBNAME
Summary
The event ID of Mainframe Access GTF user trace records. The EID must be available for exclusive use by Mainframe Access and must match the USR=(eid) parameter specified to GTF when GTF is started (see the sample member GTFCNTL). This parameter is valid only when TRACE="GTF" is specified. Specify a hexadecimal number of up to four bytes that GTF recognizes as a valid user trace record identifier.
Default
00E9
Supported Values
Value | Description
eid | A valid four byte hexadecimal number that GTF recognizes.
Example
EID ="eid"
Parent topic: Configuration parameters - alphabetical list


ENDEVOR_DSNQUALIFIER

Name
ENDEVOR_DSNQUALIFIER
Summary
Specifies a high-level qualifier for dynamically allocated data sets created by MFA Server to hold input files during the staging process. For those sites where the logged in users may not have the authority to create transient files using their USERID as the high-level qualifier, there is a configuration parameter to set that high-level qualifier to some other value where all users have READ/WRITE/ALTER access.
Default
NULL
Supported Values
Value | Description
endevordsn | A valid data set HLQ.
Example
ENDEVOR_DSNQUALIFIER="endevordsn"
Parent topic: Configuration parameters - alphabetical list


ES-MTO_MAXTASKS

Name
ES-MTO_MAXTASKS
Summary
The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from ES/MTO clients. Specify 0 (zero) or a positive integer value between 1 and 50.
Default
0
Minimum Value
1
Maximum Value
50
Example
ES-MTO_MAXTASKS="25"
Parent topic: Configuration parameters - alphabetical list


ID

Name
ID
Summary
ES-MTO:
The ID can be one to four characters in length and must match the SYSID of the ES/MSS server being defined. The initial connection messages exchanged by MFA Server and ES/MSS use this ID.
IMS:
If an IMS Option client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT IMS target server, if one has been defined. This IMS target server ID name is used in the configuration of the client. When a Remote IMS request is sent this name is sent in the request data and is used to locate the target server definition for the IMS system that will receive the request. Specify DEFAULT or an ID of up to four alphanumeric characters.
MCO:
If a CICS client request does not specify a target server ID or the specified target server ID does not exist, Mainframe Access selects the DEFAULT CICS target server, if one has been defined. This CICS target server ID name is used in the configuration of the client. When a CICS request is sent to Mainframe Access this name is sent in the request data and is used to locate the target server definition for the CICS system that will receive the request. Specify DEFAULT or an ID of up to four alphanumeric characters.
MFA:
Data Connect client requests do not specify a target server ID and Mainframe Access always looks for the DEFAULT Mainframe Access Data Connect target server definition. Specify DEFAULT.
Supported Values
Value | Description
id | A valid ID according to the rules above.
Example
ID ="id"
Parent topic: Configuration parameters - alphabetical list


IMSLINK_MAXTASKS

Name
IMSLINK_MAXTASKS
Summary
The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from IMS Option (Remote IMS) clients. Specify 0 (zero) or a positive integer value between 1 and 50.
Default
0
Minimum Value
1
Maximum Value
50
Example
IMSLINK_MAXTASKS="25"
Parent topic: Configuration parameters - alphabetical list


IPADDRESS

Name
IPADDRESS
Summary
The internet host name or IP address of the ES/MSS server. Specify either the host name that resolves to the correct IP address or the actual IP address in standard dotted-decimal format. The combination of IPADDRESS and PORT from this definition provides MFA Server with the information it needs to originate a socket connection to ES/MSS and to verify the authenticity of a socket connection request from ES/MSS.
Default
NULL
Supported Values
Value | Description
ipaddress | A valid IP address or logical host name.
Example
IPADDRESS="ipaddress"
Parent topic: Configuration parameters - alphabetical list


JES_BUFFER_TRACE

Name
JES_BUFFER_TRACE
Summary
Enables tracing of interactions between MFA and the JES subsystem. This may be useful for diagnostic purposes.
Default
0
Supported Values
Value | Description
0 | Disable MFA JES tracing.
1 | Enable MFA JES tracing.
Example
JES_BUFFER_TRACE="1"
Parent topic: Configuration parameters - alphabetical list


JES_CONCHAR

Name
JES_CONCHAR
Summary
Specifies the character that is used to identify JES2 commands from local consoles.
Default
$
Supported Values
Value Description
conchar

A valid CONCHAR character as defined in IBM manual JES2 Initialization and Tuning Reference SA32-0992.

Example
JES_CONCHAR ="conchar"
Parent topic: Configuration parameters - alphabetical list


JOBNAME

Name
JOBNAME
Summary
The jobname prefix to be used for address spaces that are started for this group. For multiple-instance address spaces this is a prefix of 1 to 4 characters and Mainframe Access Server will pad this prefix to a full 8-character jobname by appending a 4 to 7 digit sequence number. For example, JOBNAME="MFAE" results in jobnames MFAE0001, MFAE0002, and so forth. The sample prefix MFAE can be changed to meet the needs of your installation. If you do change the suggested prefix you need to review the security subsystem definition for the Mainframe Access started tasks. The configuration process uses a generic STARTED task definition (the generic name specified during Quick Configuration is MFA*.*) that covers generated jobnames such as MFAExxxx, in addition to the MFA (the MFA Server control region) and MFAS (the MFA Server for Data Connect) started task names. Specify a jobname prefix of up to four characters.
Supported Values
Value | Description
jobname | A alphanumeric string up to 4 characters long.
Example
JOBNAME="jobname"
Parent topic: Configuration parameters - alphabetical list


LIST_DB2

Name
LIST_DB2
Summary
Indicates whether or not the Mainframe Access LIST DB2 feature is to be activated. This obtains information about the DB2 and IMS subsystems. Specify 1 to activate LIST DB2 or 0 to deactivate it.
Default
0
Supported Values
Value | Description
0 | Deactivate retrieval of DB2 and IMS subsystem information.
1 | Activates retrieval of DB2 and IMS subsystem information.
Example
LIST_DB2="1"
Parent topic: Configuration parameters - alphabetical list


LIST_PARAMETERS

Name
LIST_PARAMETERS
Summary
Controls the listing of Mainframe Access parameter definitions on the XDBOUT sysout data set. The parameter listing is helpful when you need to examine the active configuration settings. Specify 1 to echo parameter definitions to the XDBOUT sysout data set or 0 to inhibit the listing.
Default
1
Supported Values
Value | Description
0 | Do not echo parameter definitions to XDBOUT data set.
1 | Echo parameter definitions to XDBOUT data set.
Example
LIST_ PARAMETERS="0"
Parent topic: Configuration parameters - alphabetical list


LU62_APPLID

Name
LU62_APPLID
Summary

The ACF/VTAM ACBNAME to be used by Mainframe Access. This ACBNAME must match the ACBNAME parameter of an active VTAM application major node. See Editing Mainframe Access Server Definitions for more information. Mainframe Access issues a VTAM OPEN request for this ACBNAME during start up and initialization fails if the OPEN is not successful. This ACBNAME (or possibly a different "network name" specified in the VTAM application major node definition) is the SNA LU name that identifies Mainframe Access to other applications in your SNA network. Specify the ACBNAME that has been defined and activated for Mainframe Access.

Default
MFM62ACB
Supported Values
Value | Description
lu62applid | A valid VTAM APPLID.
Example
LU62_APPLID ="lu62applid"
Parent topic: Configuration parameters - alphabetical list


LUNAME

Name
LUNAME
Summary
IMS:
The LU name of the IMS server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters. This name must match the ACBNAME defined in an APPC/MVS LU definition for the target IMS system.
MCO:
The LU name of the CICS server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters.
MFA:
The LU name of the Mainframe Access Data Connect server (also known as the ACBNAME or VTAM APPLID). Specify an LU name of up to eight characters.
Default
NULL
Supported Values
Value | Description
luname | A LU name of up to 8 characters.
Example
LUNAME="luname"
Parent topic: Configuration parameters - alphabetical list


MAX_DS_ALLOCATIONS

Name
MAX_DS_ALLOCATIONS
Summary
Controls the maximum number of simultaneous data set allocations (24-bit memory constraint, max 512).
Default
128
Minimum Value
128
Maximum Value
512
Example
MAX_DS_ALLOCATIONS="300"
Parent topic: Configuration parameters - alphabetical list


MAX_PUBLIC_FILES

Name
MAX_PUBLIC_FILES
Summary
Specifies the maximum number of shared public files that Mainframe Access Data Set Services will keep available. When the maximum is reached the next request for a new public file is rejected, and you must close one of the item libraries to make space for the new one. Specify an integer value between 24 and 64. Defaults to 32.
Default
32
Minimum Value
24
Maximum Value
64
Example
MAX_PUBLIC_FILES="40"
Parent topic: Configuration parameters - alphabetical list


MAXIMUM

Name
MAXIMUM
Summary
Specifies the maximum number of address spaces that Mainframe Access server starts for a multiple-instance group. Additional address spaces beyond the minimum is started in response to transaction load, up to the maximum allowed by this specification. Mainframe Access server issues messages (to the XDBOUT data set) when a client request must be queued to wait for an available processing address space. Increase the MAXIMUM value (by 1) when you observe frequent queueing of client requests. Specify a value from 1 to 10.
Default
0
Minimum Value
1
Maximum Value
10
Example
MAXIMUM="5"
Parent topic: Configuration parameters - alphabetical list


MCOLINK_MAXTASKS

Name
MCOLINK_MAXTASKS
Summary
The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from CICS clients. Specify 0 (zero) or a positive integer value between 1 and 50.
Default
0
Minimum Value
1
Maximum Value
50
Example
MCOLINK_MAXTASKS="25"
Parent topic: Configuration parameters - alphabetical list


MFA_ACCEPT_EMPTY_FILES

Name
MFA_ACCEPT_EMPTY_FILES
Summary
Indicates whether or not empty VSAM or VB data sets can be downloaded. Set to 1 to allow empty files to be downloaded, or set to 0 to restrict this. When the files are downloaded, they are converted to MF format using DFCONV. The default value is 1.
Default
1
Supported Values
Value | Description
0 | Disallow downloading empty files.
1 | Allow downloading empty files.
Example
MFA_ACCEPT_EMPTY_FILES="0"
Parent topic: Configuration parameters - alphabetical list


MFA_ENDEVOR_HISTORY

Name
MFA_ENDEVOR_HISTORY
Summary
This dynamically creates a cumulative Endevor transaction history file (MFALOGE) to house the access history of all file access attempts using Endevor. The Endevor API interface produces this log for each access requested.
Default
1
Supported Values
Value | Description
0 | Do not create Endevor transaction history file MFALOGE.
1 | Create Endevor transaction history file MFALOGE.
Example
MFA_ENDEVOR_HISTORY="0"
Parent topic: Configuration parameters - alphabetical list


MFA_ENDEVOR_INTERFACE

Name
MFA_ENDEVOR_INTERFACE
Summary
By default, the MFA Server offers access to Endevor services.
Default
1
Supported Values
Value | Description
0 | Prevent MFA Server offering Endevor access.
1 | Permit MFA Server offering Endevor access.
Example
MFA_ENDEVOR_INTERFACE="0"
Parent topic: Configuration parameters - alphabetical list


MFA_GUI_ACCEPT_PASSPHRASES

Name
MFA_GUI_ACCEPT_PASSPHRASES
Summary
Enables MFA Server to support 20-byte passphrases.
Default
0
Supported Values
Value | Description
0 | Disable passphrase support in MFA Server.
1 | Enable passphrase support in MFA Server.
Example
MFA_GUI_ACCEPT_PASSPHRASES="1"
Parent topic: Configuration parameters - alphabetical list


MFA_GUI_BLANKPASSWORD

Name
MFA_GUI_BLANKPASSWORD
Summary
Set to 1 to clear the password input field on the Drag and Drop user dialog.
Default
0
Supported Values
Value | Description
0 | Do not blank password input field on the Drag and Drop user dialog.
1 | Blank password input field on the Drag and Drop user dialog.
Example
MFA_GUI_BLANKPASSWORD="1"
Parent topic: Configuration parameters - alphabetical list


MFA_GUI_IGNORUSERCTO

Name
MFA_GUI_IGNOREUSERCTO
Summary
Set to 1 to disable the inactivity timeout on the Drag and Drop user dialog.
Default
0
Supported Values
Value | Description
0 | Enable the inactivity timeout on the Drag and Drop user dialog.
1 | Disable the inactivity timeout on the Drag and Drop user dialog.
Example
MFA_GUI_IGNOREUSERCTO="1"
Parent topic: Configuration parameters - alphabetical list


MFA_JOBNAME_CHECK

Name
MFA_JOBNAME_CHECK
Summary
Set to 1 to check that the batch job name starts with the submitter's userid.
Default
0
Supported Values
Value | Description
0 | Do not check batch job name start with submitter's userid.
1 | Check batch job name start with submitter's userid.
Example
MFA_JOBNAME_CHECK="1"
Parent topic: Configuration parameters - alphabetical list


MFA_LIBRARIAN_DIR_INFO

Name
MFA_LIBRARIAN_DIR_INFO
Summary
LONG is the default. This directs MFA Server to request complete member information from Librarian. The LONG specification significantly increases response time when accessing Librarian master files containing over 1,000 members. Specify SHORT to reduce the amount of member information requested from Librarian.
Default
LONG
Supported Values
Value | Description
SHORT | Only retrieve a small amount of member information from Librarian.
LONG | Retrieve a large amount of member information from Librarian.
Example
MFA_LIBRARIAN_DIR_INFO="SHORT"
Parent topic: Configuration parameters - alphabetical list


MFA_LIBRARIAN_HISTORY

Name
MFA_LIBRARIAN_HISTORY
Summary
By default, this will include a summary audit trail of all LIBRARIAN data accesses as part of the MFALOG output log.
Default
1
Supported Values
Value | Description
0 | Do not create summary audit trail of Librarian data access in MFALOG.
1 | Create summary audit trail of Librarian data access in MFALOG.
Example
MFA_LIBRARIAN_HISTORY="0"
Parent topic: Configuration parameters - alphabetical list


MFA_LIBRARIAN_INTERFACE

Name
MFA_LIBRARIAN_INTERFACE
Summary

By default, MFA Server offers access to Librarian services.

Default
1
Supported Values
Value | Description
0 | Prevent MFA Server offering Librarian access.
1 | Permit MFA Server offering Librarian access.
Example
MFA_LIBRARIAN_INTERFACE="0"
Parent topic: Configuration parameters - alphabetical list


MFA_LIBRARIAN_UPD_MODULE

Name
MFA_LIBRARIAN_UPD_MODULE
Summary
The name of the Librarian Batch update utility originally shipped as AFOLIBR by Computer Associates. If this module has not been renamed, then this parameter need not be specified.
Default
AFOLIBR
Supported Values
Value | Description
updmodule | Name of the Librarian Batch update utility.
Example
MFA_LIBRARIAN_UPD_MODULE="updmodule"
Parent topic: Configuration parameters - alphabetical list


MFA_MCG_DB2CONNECTION

Name
MFA_MCB_DB2CONNECTION
Summary
Controls which attachment facility is used by Mainframe Access Server for DB2 connections. Specify CAF (to use the DB2 call attach facility) or RRSAF (to use the DB2 Recoverable Resource Manager Services attachment facility). RRSAF is the default if this parameter is omitted.
Default
RRSAF
Supported Values
Value | Description
CAF | Use DB2 Call attach facility.
RRSAF | Use DB2 Recoverable Resource Manager Services attachment facility.
Example
MFA_MCB_DB2CONNECTION="CAF "
Parent topic: Configuration parameters - alphabetical list


MFA_PANVALET_HISTORY

Name
MFA_PANVALET_HISTORY
Summary
By default, this will include a summary audit trail of all user accesses to Panvalet as part of the MFALOG output log.
Default
1
Supported Values
Value | Description
0 | Do not create summary audit trail of Panvalet data access in MFALOG.
1 | Create summary audit trail of Panvalet data access in MFALOG.
Example
MFA_PANVALET_HISTORY="0"
Parent topic: Configuration parameters - alphabetical list


MFA_PANVALET_INTERFACE

Name
MFA_PANVALET_INTERFACE
Summary
By default, the MFA Server offers access to Panvalet services.
Default
1
Supported Values
Value | Description
0 | Prevent MFA Server offering Panvalet access.
1 | Permit MFA Server offering Panvalet access.
Example
MFA_PANVALET_INTERFACE="0"
Parent topic: Configuration parameters - alphabetical list


MFA_PANVALET_UPD_MODULE

Name
MFA_PANVALET_UPD_MODULE
Summary
The name of the Panvalet Batch update utility originally shipped as PAN#1 by Computer Associates. If this module has not been renamed, then this parameter need not be specified.
Default
PAN#1
Supported Values
Value | Description
updmodule | Name of the Panvalet Batch update utility.
Example
MFA_PANVALET_UPD_MODULE="updmodule"
Parent topic: Configuration parameters - alphabetical list


MFA_SAF_HISTORY

Name
MFA_SAF_HISTORY
Summary
By default, this will include a summary audit trail of all file access authorizations as part of the MFALOG output log.
Default
1
Supported Values
Value | Description
0 | Do not create summary audit trail of file access in MFALOG.
1 | Create summary audit trail of file access in MFALOG.
Example
MFA_SAF_HISTORY="0"
Parent topic: Configuration parameters - alphabetical list


MFA_SYSOUT_CLASS

Name
MFA_SYSOUT_CLASS
Summary
By default, this sets the SYSOUT class as "A" for any held data produced by Mainframe Access. This includes MFALOG, MFALOGE, and SNAPDUMP message files.
Default
A
Supported Values
Value | Description
class | A valid job class character.
Example
MFA_SYSOUT_CLASS="class"
Parent topic: Configuration parameters - alphabetical list


MFA_SYSOUT_DEST

Name
MFA_SYSOUT_DEST
Summary
By default, the value LOCAL is used as the SYSOUT destination for any held data produced by Mainframe Access. This includes MFALOG, MFALOGE, and SNAPDUMP message files.
Default
LOCAL
Supported Values
Value | Description
sysoutdest | A valid SYSOUT destination.
Example
MFA_SYSOUT_DEST="sysoutdest "
Parent topic: Configuration parameters - alphabetical list


MFADIRECT

Name
MFADIRECT
Summary
Indicates whether or not Mainframe Access Source Connect and Drag & Drop services are to be activated. Specify 1 to activate these services or 0 to disable these services. The default value is YES (the recommended setting).
Default
1
Supported Values
Value | Description
0 | Deactivate Mainframe Access Source Connect and Drag & Drop services.
1 | Activate Mainframe Access Source Connect and Drag & Drop services.
Example
MFADIRECT="0"
Parent topic: Configuration parameters - alphabetical list


MFADIRECT_MAXTASKS

Name
MFADIRECT_MAXTASKS
Summary
The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from Mainframe Access Drag & Drop and Source Connect clients, including Mainframe Access client functions and other development environment clients. Specify 0 (zero) or a positive integer value between 1 and 50. The default value is 5.
Default
5
Minimum Value
1
Maximum Value
50
Example
MFADIRECT_MAXTASKS="25"
Parent topic: Configuration parameters - alphabetical list


MFALINK_MAXTASKS

Name
MFALINK_MAXTASKS
Summary
The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from Mainframe Access Data Connect clients including Mainframe Access client functions originating in COBOL development environment clients. Specify 0 (zero) or a positive integer value between 1 and 50.
Default
0
Minimum Value
1
Maximum Value
50
Example
MFALINK_MAXTASKS="25"
Parent topic: Configuration parameters - alphabetical list


MINIMUM

Name
MINIMUM
Summary
Specifies the maximum number of address spaces that Mainframe Access server will start for a multiple-instance group. Additional address spaces beyond the minimum is started in response to transaction load, up to the maximum allowed by this specification.
Default
0
Minimum Value
1
Maximum Value
10
Example
MINIMUM="5"
Parent topic: Configuration parameters - alphabetical list


MODENAME

Name
MODENAME
Summary
IMS:
The SNA log mode name that is used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the IMS server. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
MCO:
The SNA log mode name that is used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with mainframe CICS. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
MFA:
The SNA log mode name that is used by Mainframe Access to indirectly specify SNA session parameters when Mainframe Access initiates sessions with the Mainframe Access Data Connect server. Specify a log mode name for LU6.2 sessions of up to eight characters. This log mode name must be present in the VTAM log mode table available to Mainframe Access. IBM's default log mode table, ISTINCLM, typically provides several standard log modes that can be used by Mainframe Access, including both IBMRDB and #INTER LU6.2 log modes.
Default
NULL
Supported Values
Value | Description
modename | A valid SNA log mode name that matches the VTAM definition.
Example
MODENAME="modename"
Parent topic: Configuration parameters - alphabetical list


NETWORK_ID

Name
NETWORK_ID
Summary
The SSCP network ID used by ACF/VTAM on this z/OS system. This parameter must match the NETID parameter in the active ATCSTRxx VTAM start parameters member of VTAMLST. This Network ID value is used by Mainframe Access to build an LUWID (SNA Logical Unit of Work ID for LU6.2) when an LU6.2 conversation is allocated to the DB2 DDF. Specify the 1 to 8 character Network ID from ACF/VTAM's startup parameters.
Default
DDINET1
Supported Values
Value | Description
networkid | A valid VTAM NETID.
Example
NETWORK_ID="networkid"
Parent topic: Configuration parameters - alphabetical list


ORGANIZATION

Name
ORGANIZATION
Summary
Your company name or other meaningful identifier up to 40 characters in length. Spaces are not permitted. Use underscores or other non-blank characters to separate words if necessary.
Default
YOUR_COMPANY_NAME
Supported Values
Value | Description
oraganization | A non spacey alphanumeric string up to 40 characters.
Example
ORGANIZATION="organization"
Parent topic: Configuration parameters - alphabetical list


PEM_FEATURE

Name
PEM_FEATURE
Summary
Indicates whether or not the Mainframe Access Password Expiration Manager (PEM) feature is to be activated.

PEM is used in some Micro Focus client products to enable users of the client software on PCs to change passwords for their z/OS user IDs without logging on directly to z/OS. This is especially useful when the security subsystem indicates that the current password is expired and must be replaced. Specify 1 (this setting is recommended) to activate the PEM feature or 0 to deactivate it.

Default
1
Supported Values
Value | Description
0 | Disable clients from changing user passwords.
1 | Enable clients to change user password.
Example
PEM_FEATURE ="0"
Parent topic: Configuration parameters - alphabetical list


PORT

Name
PORT
Summary
The port number where ES/MSS is listening for ISC connections.
Default
0
Minimum Value
1
Maximum Value
65525
Example
PORT="3030"
Parent topic: Configuration parameters - alphabetical list


PROCEDURE

Name
PROCEDURE
Summary
The name of the started task JCL procedure that can be used to start address spaces for this group. Sample JCL procedure MFAAS provides the basic JCL for an application server address space, and MFAAMS for the AMS application server address space. Specify a JCL procedure name of up to eight characters.
Supported Values
Value | Description
procedure | A valid JCL procedure name up to eight characters.
Example
PROCDURE="procedure"
Parent topic: Configuration parameters - alphabetical list


RACF_APPLID

Name
RACF_APPLID
Summary
Specifies the use of passtickets with functions that require a password.
Default
NULL
Supported Values
Value | Description
NULL | MFA Server uses a userid and password to protect the system.
applname | MFA Server uses a password or passticket to protect the system.
Example
RACF_APPLID ="applname"
Parent topic: Configuration parameters - alphabetical list


ROUTE

Name
ROUTE
Summary
The message route codes to be used by Mainframe Access when console messages are issued using the z/OS WTO (Write to Operator) and WTOR (Write to Operator with Reply) services. See your IBM system documentation for valid values.
Default
(2,1)
Supported Values
Value | Description
routcde | A valid ROUTCDE.
Example
ROUTE="routcde"
Parent topic: Configuration parameters - alphabetical list


SECURITY

Name
SECURITY
Summary
IMS:
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the IMS server. Mainframe Access forwards security subfield information as provided by the IMS Option client and sets the FMH-5 fields accordingly. Specify 0.
MCO:
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the CICS server. Mainframe Access forwards security subfield information as provided by the CICS client and sets the FMH-5 fields accordingly. Specify 0.
MFA:
The security level to be indicated in SNA LU6.2 Attach FMH-5 requests sent to the Mainframe Access Data Connect server. Mainframe Access forwards security subfield information as provided by the Data Connect client and sets the FMH-5 fields accordingly. Specify 0.
Default
0
Supported Values
Value | Description
0 | Disable security on LU6.2 connections.
1 | Enable security on LU6.2 connections.
Example
SECURITY="1"
Parent topic: Configuration parameters - alphabetical list


SESSIONS

Name
SESSIONS
Summary
Specifies the number of concurrent conversations MFA Server can initiate to the ES/MSS server over a single socket connection. If ES/MSS has a different definition for the number of concurrent sessions, the session count is negotiated to a common value at the time a socket connection is established. Specify a value that supports the required number of concurrently active conversations for your application.
Default
4
Minimum Value
1
Maximum Value
8
Example
SESSIONS="5"
Parent topic: Configuration parameters - alphabetical list


SMF_RECORDID

Name
SMF_RECORDID
Summary
The SMF user record ID that Mainframe Access should use when writing SMF (IBM's System Management Facility) records to the z/OS SMF data sets. If an SMF user record ID is specified, that ID value should be assigned to Mainframe Access exclusively. Specify a valid SMF user record ID number to activate the Mainframe Access SMF support. Specify 0 (zero), or omit the parameter altogether, to disable the writing of SMF records.
Default
0
Supported Values
Value | Description
0 | Disable writing of SMF records.
smfrecordid | A valid SMF user record ID number.
Example
SMF_RECORDID="smfrecordid"
Parent topic: Configuration parameters - alphabetical list


SOCKETS

Name
SOCKETS
Summary
Specifies the maximum number of concurrent socket connections between MFA Server and the ES/MSS server. ES/MSS support is currently limited to a single socket connection between MFA Server and an ES/MSS server, specify a value of 1.
Default
1
Minimum Value
1
Maximum Value
1024
Example
SOCKETS="5"
Parent topic: Configuration parameters - alphabetical list


SYNCLEVEL

Name
SYNCLEVEL
Summary
IMS:
The SNA LU6.2 sync level option to be used on conversations with the IMS server. Specify 0.
MCO:
The SNA LU6.2 sync level option to be used on conversations with CICS. Specify 0.
MFA:
The SNA LU6.2 sync level option to be used on conversations with the Mainframe Access Data Connect server. Specify 1. Conversations use LU6.2 CONFIRM protocols.
Default
NULL
Minimum Value
0
Maximum Value
2
Example
SYNCLEVEL="1"
Parent topic: Configuration parameters - alphabetical list


SYSOUT

Name
SYSOUT
Summary
The SYSOUT class for the XDBOUT data set if it is dynamically allocated. Mainframe Access operational messages and trace data (when TRACE="SYSPRINT" is specified and tracing is active) are written to this data set. XDBOUT is dynamically allocated to this SYSOUT class if an XDBOUT DD statement is not present in the Mainframe Access JCL. Specify a SYSOUT class designator that is valid for your z/OS system.
Default
A
Supported Values
Value | Description
class | A valid SYSOUT class character.
Example
SYSOUT="class"
Parent topic: Configuration parameters - alphabetical list


TCP_PORT

Name
TCP_PORT
Summary
The port number to accept connections from Micro Focus clients.
Default
2020
Minimum Value
1
Maximum Value
65525
Example
TCP_PORT="3030"
Parent topic: Configuration parameters - alphabetical list


TCPLINK_MAXTASKS

Name
TCPLINK_MAXTASKS
Summary
The number of z/OS subtasks (TCBs) to be started and dedicated to processing requests from SQL Option for DB2 clients. Specify a positive integer value between 1 and 50.
Default
2
Minimum Value
1
Maximum Value
50
Example
TCPLINK_MAXTASKS="25"
Parent topic: Configuration parameters - alphabetical list


TIMEOUT_FOR_CONNECTION

Name
TIMEOUT_FOR_CONNECTION
Summary
The number of minutes that a client connection can remain idle, after which the connection will be broken and Mainframe Access resources dedicated to the client will be released. Resources that are released when an idle client is disconnected include allocated storage, TCP/IP resources and connections to server subsystems such as DB2, IMS, CICS and Mainframe Access. Specify 0 (zero) to disable the client timeout feature and allow unlimited idle time, or a positive integer value.
Default
30
Minimum Values
0
Maximum Value
35791394
Example
TIMEOUT_FOR_CONNECTION="25"
Parent topic: Configuration parameters - alphabetical list


TIMEOUT_FOR_INITIAL_RECEIVE

Name
TIMEOUT_FOR_INITIAL_RECEIVE
Summary
The number of seconds that the listener process (Micro Focus client listener or Web Server listener) waits to receive the initial client message after a socket connection has been accepted from a new client. If the time value expires before a complete initial message is received, the client is disconnected and the listening process prepares to accept another client connection request. The default value of 3 seconds is appropriate for all installations. This low value helps keep the listeners running smoothly, even during occasional network and/or client malfunctions. Specify a positive integer value between 1 and 59 (inclusive) to alter the time out value. This may be useful for diagnostic purposes.
Default
10
Minimum Value
1
Maximum Value
59
Example
TIMEOUT_FOR_INITIAL_RECEIVE="25"
Parent topic: Configuration parameters - alphabetical list


TPNAME

Name
TPNAME
Summary
IMS:
The IMS server transaction program name for IMS Option transactions. This is the LU6.2 transaction program name that is sent to the IMS server in SNA Attach FMH-5 requests to begin an IMS Option transaction. Specify the APPC/MVS transaction program name that was specified in the APPC/MVS definitions during installation of Remote IMS.
MCO:
The server transaction program name for CICS requests. This is the LU6.2 transaction program name that is sent to CICS in SNA Attach FMH-5 requests to begin a CICS transaction. Specify a transaction program name of up to eight characters or specify * to cause Mainframe Access to use the transaction program name provided by the CICS client. The CICS client prepares a partial FMH-5 request that specifies the standard CICS transaction program names for function shipping, distributed program linking and so on.
MFA:
The transaction program name for Mainframe Access Data Connect server requests. Specify FILESHR2.
Default
NULL
Supported Values
Value | Description
tpname | A valid LU6.2 transaction program name.
Example
TPNAME="tpname"
Parent topic: Configuration parameters - alphabetical list


TRACE

Name
TRACE
Summary
The destination for trace data when tracing is activated:
  • Specify SYSPRINT to send print formatted trace output to the data set identified by the XDBOUT DD statement, normally a SYSOUT data set. Micro Focus recommends this setting during initial product testing and when you are performing controlled problem determination.
  • Specify GTF to trace a very active Mainframe Access that is processing a high transaction volume. Trace data collected by GTF is written to external storage (tape or DASD) in a raw data format while tracing is active. You can use IBM's IPCS (Interactive Problem Control System) to format the data for analysis after tracing has been completed. Trace records are sent to the console if GTF is not available when TRACE=GTF is specified.
  • Specify CONSOLE to send trace output to the system log and console (not recommended because of the large volume of messages).
Default
SYSPRINT
Supported Values
Value | Description
CONSOLE | Send trace to system log.
GTF | Send trace to GTF.
SYSPRINT | Send trace to SYSPRINT identified by XDBOUT DD statement.
Example
TRACE="GTF"
Parent topic: Configuration parameters - alphabetical list


TRACING

Name
TRACING
Summary
Specifies whether or not detailed tracing of Mainframe Access Server program activity should be started during initialization processing. Normally, tracing should be turned off during initialization and during normal product operation. Activity tracing writes detailed information to the XDBOUT sysout data set and this can slow down performance in a busy server. Tracing is normally controlled by the TRACE ON and TRACE OFF commands after initialization is complete. The TRACING parameter makes it possible to trace the initialization activity, before the server is ready to accept TRACE ON/OFF commands. Activity trace started by the TRACING parameter can be stopped later using the TRACE OFF command. Specify 1 to activate tracing during initialization or specify 0 to inhibit activity tracing until a TRACE ON command is issued.
Default
0
Supported Values
Value | Description
0 | Disable MFA Server tracing.
1 | Enable MFA Server tracing.
Example
TRACING="1"
Parent topic: Configuration parameters - alphabetical list


VIO_FOR_ENDEVOR_LOG

Name
VIO_FOR_ENDEVOR_LOG
Summary
By default, the Endevor Dependent Region creates a new VIO file (DDNAME=ENDVMSG) to be used as the Endevor transaction log for all subsequent transactions within that dependent region. The DCB attributes are:
PS,FBA,LRECL=133,UNIT=VIO,DISP=(NEW,DELETE),DSN=&MSGLOG

This file is effectively be a memory resident file, buffered by JES.

Note: During initialization there is no end-user profile in effect. That means the VIO file is owned by the started task. Therefore, the started task security profile must allow any end-user to write to this file. Endevor will OPEN the file as the transaction log. This is the default behaviour.

If this causes a security violation at your site, you may configure the log to be disk-resident, provided the high-level qualifier allows universal READ/WRITE access to the log. This is allocated as:

UNIT=SYSALLDA,DSNAME=prefix.jobname.ASnnnnn.MSGLOG

Where the jobname and address space number ensures uniqueness. The prefix is taken from the DSNQUALIFIER_ENDEVOR parameter

Default
1
Supported Values
Value | Description
0 | MFA Server allocates a data set for the Endevor transaction log.
1 | MFA Server uses the default VIO file for Endevor transaction log stored in ENDVMSG.
Example
VIO_FOR_ENDEVOR_LOG="0"
Parent topic: Configuration parameters - alphabetical list


Mainframe Access Server z/Server feature configuration parameters

  • Configuration parameters - quick reference
  • Configuration parameters - alphabetical list
Parent topic: Configuration reference


Configuration parameters - quick reference

The following list shows all z/Server configuration parameters and for each parameter, indicates whether it applies to general, schedulers, or user servers.

Parameter | General | Scheduler | User Server
AUTOSTART | Y |  |
BUFFERSIZE |  | Y | Y
CCSID |  | Y | Y
CEA_ACCOUNT |  | Y |
CEA_CHARSET |  | Y |
CEA_CODEPAGE |  | Y |
CEA_INIT_CMD |  | Y |
CEA_LOGONPROC |  | Y |
CEA_REGION_SIZE |  | Y |
CEA_SCR_SIZE |  | Y |
DEF_USRSRV_MODE |  |  |
DELAY | Y |  |
DIALOG_TIMEOUT |  |  | Y
DSP_PROTECT | Y |  |
DSP_TOKEN | Y |  |
ECB_TIMEOUT |  | Y | Y
FIRST_PORT |  | Y |
IPSTACK | Y |  |
IPTRACE | Y | Y | Y
ISPF_STATS |  | Y |
JOBNAME |  | Y |
LAST_PORT |  | Y |
LISTENER_PORT |  | Y |
LOGON_EXIT |  | Y | Y
MAIL_CLASS |  | Y | Y
MAIL_MSGCNT |  | Y | Y
MAIL_NOTIFY |  | Y | Y
MAIL_SEVERITY |  | Y | Y
MAIL_WRITER |  | Y | Y
MAXUSRV |  | Y |
MSGCLASS |  | Y |
MULTI_REXX_S |  | Y |
MULTI_REXX_U |  |  | Y
NOFTASK |  | Y | Y
NUMTCB |  | Y | Y
PORTCHECK |  | Y | Y
RACF_APPLID | Y |  |
RACF_STATS |  | Y | Y
SCHEDULER_NAME |  | Y |
SUBMIT_DELAY |  | Y |
SVC_NO | Y |  |
TIMEOUT |  | Y | Y
TSOE_JOBCHAR |  | Y |
TSOE_NOTIFY |  | Y |
USER_SERVER_JOBNAME |  | Y |
USRSRV_TIMEOUT |  | Y |
USS_DUBPROCESS |  | Y | Y
VIPA |  | Y |
VPOOLSIZE |  | Y | Y
Parent topic: Mainframe Access Server z/Server feature configuration parameters


AUTOSTART

Name
AUTOSTART
Summary
Specifies whether the holder address space will automatically start the scheduler address space(s) associated with it.
Default
1
Supported Values
Value | Description
0 The holder address space does not automatically start the scheduler address space(s) associated with it.

Each scheduler address space must be started manually using an MVS START command.

1 | The holder address space automatically starts the scheduler address space(s) associated with it.
Example
AUTOSTART="0"
Parent topic: Configuration parameters - alphabetical list


BUFFERSIZE

Name
BUFFERSIZE
Summary
Specifies the size of the IP send/receive buffer for each worker task in a scheduler or user server address space.
Default
10M
Minimum Value
2M (or 2048K)
Maximum Value
100M
Supported Values
An integer followed by either the character "K" or "M". There must be no space between the integer and the character.
Additional Information
The size of a message to or from a client cannot exceed the defined buffer size.

The buffers are used for dataset content to be edited or JESx data to be browsed and must be large enough to contain the associated data. For example, a 20.000 line source program requires a 1.6MB buffer. The buffers are allocated in LE heap storage (above the line).

The CMDTASK DD statement contains the confirmation of the buffer sizes: TAU0025I hh:mm:ss.ttt Inp-Msg-Area for subtask allocated at 29649028 Out-Msg-Area for subtask allocated at 2A04A028 Wrk-Msg-Area for subtask allocated at 2AA4B028 Each area is 10485760 Bytes long If the defined buffers are too small for an incoming or outgoing request message, TAU0050E is written to the LE message file: TAU0050E hh:mm:ss.ttt Input-Msg-Len with 00001030 Bytes is greater than ... Increase Buffer-Size and restart server !

Example
BUFFERSIZE="15M"
Parent topic: Configuration parameters - alphabetical list


CCSID

Name
CCSID
Summary
Specifies the code page used by z/Server (for example, 37 for US, or 1141 for German).
Default
37
Supported Values
Any of the code pages supported by z/Server: 37, 273, 277, 278, 280, 284, 285, 297, 500, 871, 1047, 1140, 1141, 1142, 1143, 1144, 1145, 1146, 1147, 1148, 1149
Example
CCSID="1047"
Parent topic: Configuration parameters - alphabetical list


CEA_ACCOUNT

Name
CEA_ACCOUNT
Summary
Specifies the name of the account to be used by all users of this scheduler.
Default
ACCT#
Supported Values
A character string with maximum length of 40 characters. The string can contain any alphanumeric characters or any special characters supported by the current codeset/codepage.
Additional Information
The account specified by CEA_ACCOUNT must be defined in general resource class TSOACCT, and all potential TSO users must have access to it. The configured default is ACCT#.
Example
CEA_ACCOUNT="ACCT#"
Parent topic: Configuration parameters - alphabetical list


CEA_CHARSET

Name
CEA_CHARSET
Summary
Specifies the character set used for the caller's CEA-launched TSO address space.
Default
697
Supported Values
Any character set supported by z/OS.
Additional Information
The value specified by CEA_CHARSET is used by the applications running in the TSO/E address space to convert messages and responses from UTF-8 to EBCDIC.
Example
CEA_CHARSET="698"
Parent topic: Configuration parameters - alphabetical list


CEA_CODEPAGE

Name
CEA_CODEPAGE
Summary
Specifies the codepage used for the caller's CEA-launched TSO address space.
Default
37
Supported Values
Any codepage supported by z/OS.
Additional Information
The value specified by CEA_CODEPAGE is used by applications running in the TSO/E address space to convert messages and responses from UTF-8 to EBCDIC.
Example
CEA_CODEPAGE="1141"
Parent topic: Configuration parameters - alphabetical list


CEA_INIT_CMD

Name
CEA_INIT_CMD
Summary
Specifies the REXX exec used for a CEA initial request or split screen request.
Default
ZCEAICMD
Supported Values
A character string with maximum length of 8 characters. The first character of the string must be alphabetic. The remaining characters must be alphanumeric.
Additional Information
A CEA initial request should be the first application requested by a client after a CEA-launched TSO user address space is started.
Example
CEA_INIT_CMD="ZCEAIREX"
Parent topic: Configuration parameters - alphabetical list


CEA_LOGONPROC

Name
CEA_LOGONPROC
Summary
Specifies the name of the TSO/E logon procedure used to start a CEA-launched TSO address space.
Default
CEAPROC
Supported Values
A character string with maximum length of 8 characters. The first character of the string must be alphabetic. The remaining characters must be alphanumeric.
Additional Information
The procedure specified by CEA_LOGONPROC must be defined to general resource class TSOPROC and potential TSO users must have access to it. If more than one CEA scheduler is run on a given system, every CEA scheduler needs its own logon procedure, because the IPCONFIG DD statement contained in this procedure will be different for every scheduler.

The logon procedure should be tested like any TSO logon procedure before using it. When it is used outside of z/Server, the initial REXX exec CEALOGON will not have run, resulting in no ISPF profile, and the TSO user being returned to the TSO READY prompt.

Use the following command to allocate the ISPF profile (with the correct naming conventions for the installation):

alloc dd(ISPPROF) dsn(userid.ISPF.ISPPROF)

Then call ISPF. If the logon procedure is correct, the ISPF primary option menu will be shown. Otherwise correct any errors.

This is a mandatory parameter for CEA scheduler address spaces.

Example
CEA_LOGONPROC="CEAPROC"
Parent topic: Configuration parameters - alphabetical list


CEA_REGION_SIZE

Name
CEA_REGION_SIZE
Summary
Specifies the region size used to start the CEA-launched TSO user address space.
Default
2047M
Minimum Value
150M
Maximum Value
2047M
Supported Values
An integer followed by the character "M". There must be no space between the integer and the "M".
Additional Information
Any specification provided in the JCL statement will be overwritten by this parameter.
Example
CEA_REGION_SIZE="1000000"
Parent topic: Configuration parameters - alphabetical list


CEA_SCR_SIZE

Name
CEA_SCR_SIZE
Summary
Describes the screen characteristics for the ISPF session.
Default
24x80
Supported Values
24x80, 32x80, 43x80, 27x132, or 62x160
Additional Information
These screen sizes are usually set in a 3270 emulation and queried by VTAM at the start of a 3270 TSO session.

The values specified here are used if the Eclipse client did not specify other screen sizes in the preferences section, which would then be used during the start of a CEA-launched TSO user address space.

Example
CEA_SCR_SIZE="62x160"
Parent topic: Configuration parameters - alphabetical list


DEF_USRSRV_MODE

Name
DEF_USRSRV_MODE
Summary
Specifies the default working mode of a user server started by a scheduler. This is used when connecting with legacy clients.
Default
STC
Supported Values
STC, CEA, JOB
Additional Information
Example
DEF_USRSRV_MODE=CEA
Parent topic: Configuration parameters - alphabetical list


DELAY

Name
DELAY
Summary
Specifies the time, in seconds, that the holder task waits until canceling a user server/scheduler when the stop command didn't terminate the address space and the time between terminating the last scheduler task and the holder task itself.
Default
5
Minimum Value
5
Maximum Value
300
Additional Information
When specifying a value for DELAY, bear in mind that the time necessary to terminate an address space can vary with the CPU load on the system.
Example
DELAY="10"
Parent topic: Configuration parameters - alphabetical list


DIALOG_TIMEOUT

Name
DIALOG_TIMEOUT
Summary
Specifies the timeout, in seconds, for dialog responses.
Default
3600
Minimum Value
20
Maximum Value
86400
Additional Information
A dialog response in this context is the time a user server address space waits for a client response.

After the specified time expires, a running ISPF dialog (in a user server address space) receives an error message and must be restarted from the client. z/Server will cancel the user server address space that had encountered the timeout.

When a scheduler address space does not get a timely response from a user server, the following message is issued:

SLR0084E hh:mm:ss.ttt User server [002] did not response for [003] seconds. Connection terminated due to timeout!
Example
DIALOG_TIMEOUT="40"
Parent topic: Configuration parameters - alphabetical list


DSP_PROTECT

Name
DSP_PROTECT
Summary
Specifies whether the data space should reside in protected memory.
Default
Y
Supported Values
Y or N
Additional Information
Micro Focus strongly recommends that you set DSP_PROTECT="Y" in the holder address space configuration.
Example
DSP_PROTECT="Y"
Parent topic: Configuration parameters - alphabetical list


DSP_TOKEN

Name
DSP_TOKEN
Summary
Specifies the token name that each address space for one z/Server uses to address the data space with the user administration control structures.
Default
TAURSERV
Supported Values
A character string with maximum length of 16 characters. The first character must be in the range "J" through "Z". The remaining characters must be alphanumeric. The first three characters of the string must not be "SYS".
Example
DSP_TOKEN="TAURSERV"
Parent topic: Configuration parameters - alphabetical list


ECB_TIMEOUT

Name
ECB_TIMEOUT
Summary
Specifies, in seconds, how long the listener waits for the completion of the command and service task.
Default
30
Minimum Value
10
Maximum Value
120
Additional Information
If a timeout occurs, message TAU0174I is issued and the server startup terminates.
Parent topic: Configuration parameters - alphabetical list


FIRST_PORT

Name
FIRST_PORT
Summary
Specifies the low end of the port range that the scheduler address space owns and assigns to a user server address space when the user server is started for IP communication.
Default
1201
Minimum Value
1
Maximum Value
65535
Additional Information
Specify the high end of the port range using LAST_PORT.

The port range (LAST_PORT - FIRST_PORT) specifies the maximum number of user server address spaces that can run in parallel.

Example
FIRST_PORT="1240"
Parent topic: Configuration parameters - alphabetical list


IPSTACK

Name
IPSTACK
Summary
Specifies the name of the IP stack used for processing.
Default
TCPIP
Supported Values
A character string with maximum length of 8 characters. The first character of the string must be alphabetic. The remaining characters must be alphanumeric.
Additional Information
This parameter is mandatory.
Example
IPSTACK="TCPIP"
Parent topic: Configuration parameters - alphabetical list


IPTRACE

Name
IPTRACE
Summary
Specifies the level of tracing to use.
Default
0
Supported Values
Value | Description
0 | Normal message traffic for best performance.
1 | Warning, error and severe error messages are written.
2 | Informational messages are also written.
3 | All data sent and received using IP is traced.
4 | Calls to EZASOCKET are traced.
5 | Full trace.
6 | Code page translation and BASE64 encode/decode are traced.
Additional Information
The IPTRACE level can be set at startup. The trace level can later be changed via operator command. A higher trace level includes all lower trace levels.
Note: A high trace level may cause JESx spool shortages due to the amount of output written to the JESx job log. Use higher trace levels with caution.
Example
IPTRACE="3"
Parent topic: Configuration parameters - alphabetical list


ISPF_STATS

Name
ISPF_STATS
Summary
Specifies the level of ISPF statistics that z/Server returns.
Default
1
Supported Values
Value | Description
0 | z/Server returns basic ISPF statistics on read requests to be displayed in the client.
1 | z/Server returns basic ISPF statistics on read requests to be displayed in the client, and writes/updates basic ISPF statistics when writing/updating a member of a partitioned dataset.
Additional Information
Extended ISPF statistics are not supported. If an installation uses extended ISPF statistics, they will be replaced with basic ISPF statistics.

The STATS setting in the ISPF profile of the TSO user is ignored.

Example
ISPF_STATS="0"
Parent topic: Configuration parameters - alphabetical list


JOBNAME

Name
JOBNAME
Summary
Specifies whether the JOBNAME of a user server consists of the user ID prefixed or suffixed with TSOE_JOBCHAR.
Default
PREFIX
Supported Values
PREFIX, SUFFIX
Parent topic: Configuration parameters - alphabetical list


LAST_PORT

Name
LAST_PORT
Summary
Specifies the high end of the port range that the scheduler address space owns and assigns to a user server address space when the user server is started for IP communication.
Default
1249
Minimum Value
1
Maximum Value
65535
Additional Information
Specify the low end of the port range using FIRST_PORT.

The port range (LAST_PORT - FIRST_PORT) specifies the maximum number of user server address spaces that can run in parallel.

Example
LAST_PORT="1270"
Parent topic: Configuration parameters - alphabetical list


LISTENER_PORT

Name
LISTENER_PORT
Summary
Specifies the IP port that the scheduler listens on for incoming work requests.
Default
1200
Minimum Value
1
Maximum Value
65535
Parent topic: Configuration parameters - alphabetical list


LOGON_EXIT

Name
LOGON_EXIT
Summary
Specifies the user exit that is invoked every time an ACEE for a user is created or deleted.
Default
SPACE
Supported Values
A character string with maximum length of 8 characters. The first character of the string must be alphabetic. The remaining characters must be alphanumeric.
Additional Information
The exit specified LOGON_EXIT can change or set the userid and password. The exit may also be used to generate a pass ticket for a given user ID.
Parent topic: Configuration parameters - alphabetical list


MAIL_CLASS

Name
MAIL_CLASS
Summary
Specifies the JESx message class that the emails are forwarded to.
Default
F
Supported Values
A single-character string. The character must be alphanumeric.
Additional Information
The message class specified by MAIL_CLASS must match the message class that is configured as LOCALCLASS for the SMTP server.
Example
MAIL_CLASS="G"
Parent topic: Configuration parameters - alphabetical list


MAIL_MSGCNT

Name
MAIL_MSGCNT
Summary
Specifies how many messages are to be combined into one email.
Default
20
Minimum Value
1
Maximum Value
100
Additional Information
At scheduler shutdown, any messages buffered are always sent when the server is shut down.
Example
MAIL_MSGCNT="25"

This example results in the 26th message causing the previously accumulated 25 messages to be sent as one email.

Parent topic: Configuration parameters - alphabetical list


MAIL_NOTIFY

Name
MAIL_NOTIFY
Summary
Specifies whether notification emails are to be sent about errors with a severity greater than or equal to the value specified using the MAIL_SEVERITY parameter.
Default
0
Supported Values
Value | Description
0 | Email notifications are deactivated.
1 | Email notifications are activated.
Example
MAIL_NOTIFY="1"
Parent topic: Configuration parameters - alphabetical list


MAIL_SEVERITY

Name
MAIL_SEVERITY
Summary
Specifies the severity of the messages that cause an email to be sent.
Default
2
Supported Values
Value | Severity
1 | Warnings
2 | Errors
3 | Severe errors
Example
MAIL_SEVERITY="3"
Parent topic: Configuration parameters - alphabetical list


MAIL_WRITER

Name
MAIL_WRITER
Summary
Specifies the name of the z/OS task address space that emails are forwarded to.
Default
SMTP
Supported Values
A character string with maximum length of 8 characters. The first character of the string must be alphabetic. The remaining characters must be alphanumeric.
Example
MAIL_WRITER="SMTP"
Parent topic: Configuration parameters - alphabetical list


MAXUSRV

Name
MAXUSRV
Summary
Specifies the maximum number of user server address spaces that can be started for one TSO user or client.
Default
5
Minimum Value
1
Maximum Value
5000
Example
MAXUSRV="5"
Parent topic: Configuration parameters - alphabetical list


MSGCLASS

Name
MSGCLASS
Summary
Specifies the JESx message class to be used for the job log DD statements that are dynamically created.
Default
X
Supported Values
A single-character string. The character must be alphanumeric.
Example
MSGCLASS="K"
Parent topic: Configuration parameters - alphabetical list


MULTI_REXX_S

Name
MULTI_REXX_S
Summary
Specifies if re-entrant REXX environments are to be made available in addition to the non re-entrant REXX environment that is created by default.
Default
1
Supported Values
Value | Description
0 | No re-entrant REXX environments are available. REXX execs executing in the default environment write their output to DD statement SYSTSPRT in JESx job log.
1 | Each REXX exec is executed in its own REXX environment. Every z/Server subtask has both a non re-entrant and a re-entrant REXX environment available. REXX execs executing in the re-entrant environment write their output to DD statement ZCOTSPRT in JESx job log. This setting is recommended for scheduler address spaces.
2 | CMDTASK and SRVTASK execute in a re-entrant REXX environment. All other subtasks share the default non re-entrant environment.
Example
MULTI_REXX_S="2"
Parent topic: Configuration parameters - alphabetical list


MULTI_REXX_U

Name
MULTI_REXX_U
Summary
Specifies if re-entrant REXX environments are to be made available in addition to the non re-entrant REXX environment that is created by default.
Default
2
Supported Values
Value | Description
0 | No re-entrant REXX environments are available. REXX execs executing in the default environment write their output to DD statement SYSTSPRT in JESx job log.
1 | Each REXX exec is executed in its own REXX environment. Every z/Server subtask has both a non re-entrant and a re-entrant REXX environment available. REXX execs executing in the re-entrant environment write their output to DD statement ZCOTSPRT in JESx job log.
2 | CMDTASK and SRVTASK execute in a re-entrant REXX environment. All other subtasks share the default non re-entrant environment. This setting is recommended for a user server address space.
Example
MULTI_REXX_U="1"
Parent topic: Configuration parameters - alphabetical list


NOFTASK

Name
NOFTASK
Summary
Specifies the behavior of LISTENER task when no worker task is available to handle incoming client requests.
Default
For CEA schedulers, M.

For STC schedulers, WM.

Supported Values
Value | Description
M | If no worker task is available, LISTENER returns message TAU0171E to the client. It does not wait for a worker task to become available.
W | If no worker task is available, LISTENER waits until one becomes available.
WM | If no worker task is available, LISTENER waits until one becomes available. Additionally, message TAU0009E is written to the hardcopy log.
Example
NOFTASK="WM"
Parent topic: Configuration parameters - alphabetical list


NUMTCB

Name
NUMTCB
Summary
Specifies how many worker tasks (TCBs) are started simultaneously to process incoming connections from a client.
Default
For schedulers, 5.

For user servers, 1.

Minimum Value
1
Maximum Value
35
Additional Information
Each worker task has its own DD statement Tnnnnnnn in the JESx job log. For every worker task started, the main task writes message TAU0010I to the MAINTASK DD statement:
TAU0010I 14:47:07.563 Subtask 1 started A(TCB) : 008B33B0 A(ECB) :
2236C0E0
TAU0010I 14:47:07.563 Subtask 2 started A(TCB) : 008B3120 A(ECB) :
2236C144
TAU0010I 14:47:07.563 Subtask 3 started A(TCB) : 0089EE78 A(ECB) : 2236C1A8

This message contains the address of the TCB (Task Control Block) and ECB (Event Control Block) for the worker task. When a worker task is posted for an incoming request, message TAU0011I is written to the MAINTASK DD statement:

TAU0011I 15:10:17.883 Subtask 1 posted A(TCB) : 008B33B0 A(ECB) : 2236C0E0

When all worker tasks are busy processing client requests and no worker task can be posted for a new client request, TAU0009E is written to the MAINTASK DD statement and the main task waits for one of the worker tasks to become available again:

TAU0009E 15:10:20.882 No free ECB available. Waiting for next free ECB.

If this message appears too often, the number of worker tasks NUMTCB should be increased.

Note: Each subtask requires private storage to send and receive data (see BUFFERSIZE), and the storage required for the application. Storage is allocated when the worker task is established at scheduler address space startup.

The number of tasks is calculated by the formula: NUMTCB + 4 (CMDTASK + SRVTASK + MSGTASK + LISTENER).

Do not set NUMTCB higher than 33 (when using BUFFERSIZE="10M", as the size of the private region will be insufficient otherwise.

Parent topic: Configuration parameters - alphabetical list


PORTCHECK

Name
PORTCHECK
Summary
Specifies whether the availability of a port should be tested before a user server address space is started.
Default
1
Supported Values
Value | Description
0 | No checking is done.
1 z/Server issues the following command (visible in SYSTSPRT DD statement):
D TCPIP,,N,CONN,PORT

The command response can be found in the hardcopy log. When the port is not available, for instance, when it is in status LISTEN, TIMEWT, or FINWT2, the response to the DISPLAY command is useful for analysis.

Additional Information
It is strongly recommended to set PORTCHECK="1" in the scheduler address space configuration.
Example
PORTCHECK="1"
Parent topic: Configuration parameters - alphabetical list


RACF_APPLID

Name
RACF_APPLID
Summary
Specifies the use of passtickets with functions that require a password.
Default
NULL
Supported Values
Value | Description
NULL | The holder address space uses a userid and password to protect the system.
applname | The holder address space uses a password or passticket to protect the system.
Additional Information
Permission to generate a passticket is granted to a userid of the scheduler by using IRRPTAUTH profiles in the PTKTDATA class:
RDEFINE PTKTDATA applname SSIGNON(KEYMASKED(secure-signon-key)) UACC(NONE)
RDEFINE PTKTDATA IRRPTAUTH.applname.* UACC(NONE)
PERMIT IRRPTAUTH.applname.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(userid)
Example
RACF_APPLID=applname
Parent topic: Configuration parameters - alphabetical list


RACF_STATS

Name
RACF_STATS
Summary
Specifies whether message ICH70001I is suppressed.
Default
0
Supported Values
Value | Description
0 | Message ICH70001I is not suppressed.
1 | Message ICH70001I is suppressed for RACROUTE and RACINIT REQUEST=VERIFY
Additional Information
Message ICH70001I is issued whenever a client connects a scheduler with a request for service.
Example
RACF_STATS="0"
Parent topic: Configuration parameters - alphabetical list


SCHEDULER_NAME

Name
SCHEDULER_NAME
Summary
Specifies the job start of the started task.
Default
TAURISPF
Supported Values
A character string with maximum length of 8 characters. The first character of the string must be alphabetic. The remaining characters must be alphanumeric.
Example
SCHEDULER_NAME="TAURISPF"
Parent topic: Configuration parameters - alphabetical list


SUBMIT_DELAY

Name
SUBMIT_DELAY
Summary
Specifies the time, in seconds, until a scheduler address space checks if a just-started user server is ready to accept commands.
Default
5
Minimum Value
1
Maximum Value
30
Additional Information
The check is repeated 10 times before an error message similar to the following is issued:
SLR0131E hh:mm:ss.ttt User-Server did not signal READY after a wait period of 10 X [002] milliseconds.
Command was not routed to the user server.
Please wait a moment and retry

If address space creation on a system routinely takes longer than 10 seconds, SUBMIT_DELAY should be increased.

Example
SUBMIT_DELAY="25"
Parent topic: Configuration parameters - alphabetical list


SVC_NO

Name
SVC_NO
Summary
Specifies the SVC number for the type-3 SVC routine to be dynamically installed at holder address space startup.
Default
238
Minimum Value
200
Maximum Value
255
Additional Information
This parameter is mandatory.
Example
SVC_NO="238"
Parent topic: Configuration parameters - alphabetical list


TIMEOUT

Name
TIMEOUT
Summary
Specifies the length of time, in minutes, that the address space tolerates without IP activity before terminating.
Default
For user servers started as STC, 20.
For all other servers, 0 (no timeout).
Minimum Value
0
Maximum Value
1440
Additional Information
This parameter has similar a similar effect to the JCL TIME parameter for CPU consumed.
Example
TIMEOUT="20"
Parent topic: Configuration parameters - alphabetical list


TSOE_JOBCHAR

Name
TSOE_JOBCHAR
Summary
Specifies the job character for JOBNAME.
Default
W
Supported Values
A single-character string. The character must be alphabetic.
Parent topic: Configuration parameters - alphabetical list


TSOE_NOTIFY

Name
TSOE_NOTIFY
Summary
Specifies whether a notify statement is generated in the start command for the STC user server.
Default
0
Supported Values
Value | Description
0 | Do not generate a notify statement.
1 | Generate a notify statement.
Example
TSOE_NOTIFY="1"
Parent topic: Configuration parameters - alphabetical list


USER_SERVER_JOBNAME

Name
USER_SERVER_JOBNAME
Summary
Specifies the name of the user server start procedure used in a z/OS start command.
Default
IVPUSRT
Supported Values
A character string with maximum length of 8 characters. The first character of the string must be alphabetic. The remaining characters must be alphanumeric.
Additional Information
The PROCLIB concatenation must contain a member with this name in order to start user server address spaces.
Example
USER_SERVER_JOBNAME="IVPUSRT"
Parent topic: Configuration parameters - alphabetical list


USRSRV_TIMEOUT

Name
USRSRV_TIMEOUT
Summary
Specifies the timeout, in seconds, for a server.
Default
45
Minimum Value
45
Maximum Value
86400
Additional Information
If no input message is received by the specified idle time, the server will shutdown automatically.
Parent topic: Configuration parameters - alphabetical list


USS_DUBPROCESS

Name
USS_DUBPROCESS
Summary
Specifies whether subtasks are dubbed as threads in a caller's process or as new processes.
Default
0
Supported Values
Value | Description
0 | The subtask of the caller is dubbed as a thread in the caller's process when the subtask issues its first z/OS UNIX service call.
1 | The subtask of the caller is dubbed as a new process when the subtask issues its first z/OS UNIX service call.
Additional Information
If USS commands such as FTP are to be executed, USS_DUBPROCESS must be set to 1, otherwise the following error will occur:
CEE5101C During initialization the callable service BPX1MSS failed.
The system return code was 156, the reason code was 0D070200
Note: With USS_DUBPROCESS="1", a user server address space does not support ISPF dialogs.
Parent topic: Configuration parameters - alphabetical list


VIPA

Name
VIPA
Summary
Specifies a symbolic name to use instead of z/Server's IP address when connecting to the client.
Default
No default.
Supported Values
Any valid DNS hostname.
Additional Information
By default, during connection z/Server sends its own IP address back to the client, which is then used by the client for further communication. However, when the client connects through NAT'ed addresses, the IP address that the scheduler address space knows about might be completely different from the IP address that the client must use. In this case, the symbolic name provided by the VIPA parameter (and translated using a DNS server) should be specified to ensure communication.
Note: The VIPA parameter cannot be used when no fixed unique IP address is assigned to the symbolic name, for example, when VIPA is used for load distribution.
Example
VIPA="custom.com"
Parent topic: Configuration parameters - alphabetical list


VPOOLSIZE

Name
VPOOLSIZE
Summary
Specifies the size of the pool of variables processed with VGET, VPUT and VDEL services. This is similar to the ISPF profile pool.
Default
4K
Minimum Value
4K
Maximum Value
40K
Supported Values
An integer followed by the character "K". There must be no space between the integer and the "K".
Additional Information
The value specified for VPOOLSIZE must be a multiple of 4K.
Example
VPOOLSIZE="16K"
Parent topic: Configuration parameters - alphabetical list


After Installing

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

Also, note the following:

  • Configuring Enterprise Developer
  • On Windows
  • On UNIX
Parent topic: Installation


Configuring Enterprise Developer

If you have used Eclipse from the same workspace before, the Eclipse perspective settings are not reset after installing any Micro Focus product. To pick up any new features, you must reset the perspective you are working with after installation:

  1. Open the existing workspace with this product.

    You may receive some warnings or errors which you can ignore.

  2. Make sure you are in the perspective you need to reset by clicking Window > Perspective > Open Perspective > Other.
  3. From the Open Perspective dialog box, click the perspective you want to reset.
  4. Click OK.
  5. Click Window > Perspective > Reset Perspective.
  6. When prompted, click Yes.
  7. Reapply any customizations.
Parent topic: After Installing


On Windows

  • Installing X Windows on Windows
  • Repairing on Windows
  • Uninstalling
Parent topic: After Installing


Installing X Windows on Windows

Some features of Enterprise Developer for Eclipse on Windows require an X Windows installation, hence Micro Focus ViewNowX is provided with the product.

To install ViewNowX:

  1. Using Windows Explorer, navigate to the folder that contains the ViewNowX executable. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\ViewNowX.
  2. Execute ViewNow_X_Server.exe and then vnx_HF_11327.msp in that folder.

ViewNowX requires that your client machine has Microsoft Visual C++ 2008 SP1 Redistributable Package (x86) installed. If it is missing from your machine, the ViewNowX installation will offer a link to download the package.

Parent topic: On Windows


Repairing on Windows

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

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

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


Uninstalling

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

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

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

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

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

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

Some registry entries are not removed by the uninstallation process and you need to manually delete them.

The following folders might not be removed:

  • The Micro Focus Product Name folder in the Start menu - you can delete it manually.
  • %systemdrive%\Users\Public\Documents\Micro Focus - includes the binaries and the log files of the samples which you have built.
  • %ProgramData%\Micro Focus - includes some data files used by the Micro Focus licensing system.
  • %Program Files%\Micro Focus - you can delete it manually.

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

start /wait install-file.exe /quiet /uninstall

In addition, the following registry entries are not removed. These are created the first time that an Enterprise Server that has been enabled for performance monitoring starts up:

  • Micro Focus Server\Performance\Active Servers
  • Micro Focus Server\Performance\PerfIniFile
Parent topic: On Windows


On UNIX

  • Configuring the Remote System Explorer Support
  • Repairing on UNIX
  • Uninstalling
Parent topic: After Installing


Configuring the Remote System Explorer Support

The remote development support from the Eclipse IDE relies upon Enterprise Developer running on the UNIX machine and handling all requests from the IDE for building and debugging programs. Enterprise Developer 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 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 1.7 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: On UNIX
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: On UNIX
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_EnterpriseDeveloper4.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: On UNIX
Parent topic: After Installing


Installing Enterprise Developer Development Hub

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


Before Installing

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


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 Micro Focus Enterprise Developer UNIX Components


Software Requirements

Note: This product includes OpenSSL version 1.0.2n.

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 "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 Enterprise Developer.
  • 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 6.x | Red Hat 7
    glibc | glibc-*.i686 | glibc-*.x86_64 | glibc-*.s390 | X | X
    libgcc | libgcc-*.i686 | libgcc-*.x86_64 | libgcc-*.s390 | X | X
    libstdc++ | libstdc++-*.i686 | libstdc++-*.x86_64 | libstdc++-*.s390 | X | X
    glibc-locale | glibc-locale-32bit | glibc-locale-2 | X
    glibc-devel | glibc-devel-*.i686 | glibc-devel-*.x86_64 | glibc-devel-*.s390 | X | X
    elfutils-libelf-** | X | X | X
    libelf-devel-0.137-8.19 ** | X | X | X
    libelf1-0.137-8.19** | X | X | X
    libelf1-32bit-0.137-8.19** | libelf1-32bit-0.137-8.19** | X | X | X
    gcc2 | gcc*.i686 | gcc*x86_64 | X | X | X | X

    Visit the Red Hat Web site for more information.

    • ¹ On SuSe 12, you can only install the 64-bit version of Enterprise Developer. 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 and PL/I to compile.
  • Oracle's Java Platform (64-bit) version 1.8 or later, or AdoptOpenJDK's OpenJDK 8 (64-bit) are required to run the Eclipse IDE. The recommended minimum version is Java 1.8.162 (64-bit). Oracle's implementation of Java 7, 8 (32 or 64-bit versions), and Java 9 (64-bit version only), and AdoptOpenJDK's OpenJDK 8 are supported for executing JVM COBOL code, and for native COBOL and Java interoperability. You can download Oracle's Java EE from Oracle's Web site and install it anywhere on your machine. Alternatively, 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 Enterprise Developer client and a new licensing server on the same machine.

If you have a network server, you must update the license server before installing the product as the client is not able to communicate with license servers of versions older than 10000.2.660. On Windows, you can check the version of your license server by clicking Help > About in the Micro Focus License Administration tool. 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 Micro Focus Enterprise Developer UNIX Components


Basic Installation

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

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

  • Installing Micro Focus Enterprise Developer UNIX Components
Parent topic: Installing Enterprise Developer Development Hub


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
  • Micro Focus Enterprise Developer UNIX Components Installation Options
  • RPM Installer
Parent topic: Installing Enterprise Developer Development Hub


After Installing

  • The information about Micro Focus Enterprise Developer UNIX Components is part of the Enterprise Developer for Eclipse product help.
  • 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 Enterprise Developer 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/Enterprise Developer/.
  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


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

Windows

Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus License Manager > License Administration
Windows 8.1
  • From the Windows Start screen, click the License Administration tile
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus License Manager > License Administration

UNIX

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

Windows

  1. Start Micro Focus License Administration.
  2. Click the Install tab.
  3. Do one of the following:
    • Click Browse next to the License file field and select the license file (which has an extension of .mflic).
    • Drag and drop the license file from Windows Explorer to the License file field.
    • Open the license file in a text editor, such as Notepad, then copy and paste the contents of the file into the box below the License file field.
  4. Click Install Licenses.

Alternatively, you can install the license file from within the IDE as follows:

  1. Start Enterprise Developer.
  2. Click Help > Micro Focus > Product Licensing to open the Product Licensing dialog box.
  3. Ensure I have a full Enterprise Developer Team Edition license is checked.
  4. Click Browse next to the License file field.
  5. Select the license file (which has an extension of .mflic), and then click Open.
  6. Click Finish to install the license.

UNIX

  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.

Windows

  1. Start Micro Focus License Administration.
  2. Click the Install tab.
  3. Type the authorization code in the Enter authorization code field.
  4. Click Authorize.

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

UNIX

  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.

Windows

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

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

  5. Type the authorization code in the Authorization Code field. The authorization code is a 16-character alphanumeric string supplied when you purchased your product.
  6. Type the Machine ID in the Machine ID field.
  7. Type your email address in the Email Address field.
  8. Click Generate.
  9. Copy the generated license string (or copy it from the email) and paste it into the box under the License file field on the Install page.
  10. Click Install Licenses.

UNIX

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.

Windows

  1. Start Micro Focus License Administration.
  2. Select Options > Advanced Configuration.
  3. Click Change next to License server.
  4. In the New value field, type the IP address or server name for the network license server.
  5. Click Save.
  6. Close the Advanced Configuration window.
  7. Click File > Exit.

UNIX

  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:

Windows

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

    For 32-bit Windows environments:

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

    For 64-bit Windows environments:

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

    For 32-bit Windows environments:

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

    For 64-bit Windows environments:

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

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

UNIX

  • 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
Related information
License Manager


Viewing installed licenses

Windows

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

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

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.

UNIX

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

Windows

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

UNIX

  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.

Windows

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

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

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

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

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

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

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

  4. Copy the whole character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box.
  5. Paste the string into an email and send it to your SupportLine representative.

UNIX

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.

Windows

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

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

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

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

  8. Copy the whole character string displayed in the text box at the bottom of the Revoke Product Licenses dialog box.
  9. Paste the string into an email and send it to your SupportLine representative.

UNIX

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
  • Installing License Manager without Sentinel RMS
  • Setting up network licensing with COBOL server
Parent topic: Managing Licenses


Installing a local license server

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

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

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

  1. 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 Windows
  • Installing on UNIX and Linux
Parent topic: Installing License Manager


Installing on Windows

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


Standard installation

  1. Run the License Manager installer to install the licensing infrastructure.
  2. Start the Licensing System Administration tool. To do this, select:

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

    The Micro Focus License Administration window appears.

    You can now manage licenses on the machine.

Parent topic: Installing on Windows


Silent installation

Type:

start /wait msiexec /qn /i lmsetupxx.msi

where:

xx is 32 or 64, depending on whether you are using 32-bit or 64-bit Windows.

Parent topic: Installing on Windows


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


Installing License Manager without Sentinel RMS

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

The following procedures install a basic infrastructure (the licensing daemon and relevant configuration files) without the Sentinel RMS license server infrastructure.

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


Standard installation

Do one of the following:

  • If you are using the lmsetup.exe installer, type:

    start /wait lmsetup.exe /v” NOSAFENET=1”

  • If you are using the lmsetup.msi installer, type:

    msiexec /i lmsetup.msi NOSAFENET=1

Parent topic: Installing License Manager without Sentinel RMS


Silent installation

Do one of the following:

  • If you are using the lmsetup.exe installer, type:

    start /wait lmsetup.exe /s /v”/qn NOSAFENET=1”

  • If you are using the lmsetup.msi installer, type:

    start /wait msiexec /qn /i lmsetup.msi NOSAFENET=1

Parent topic: Installing License Manager without Sentinel RMS


Setting up network licensing with COBOL server

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

https://community.microfocus.com/microfocus/cobol/visual_cobol/w/knowledge_base/20026.set-up-networked-licensing-with-cobol-server-2-1-to-run-native-non-net-applications.aspx

Parent topic: Installing License Manager


Trial licenses

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

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

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

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

Parent topic: Managing Licenses


Commuter licenses

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

You obtain and manage commuter licenses by using the Micro Focus License Administration tool. If there are any commutable licenses on your network server, a Commuter tab is displayed in the Administration tool window (Windows) or you can view a list of them by selecting the Commuter/Return Licenses option (UNIX).

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

Windows

  1. Start Micro Focus License Administration.
  2. Click the Commuter tab.

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

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

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

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

UNIX

  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

Windows

  1. Start Micro Focus License Administration.
  2. Click the Commuter tab.
  3. Select the appropriate product and press Return License.

UNIX

  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:
  • Windows XP: C:\Documents and Settings\All Users\Application Data\Micro Focus
  • Windows 7: C:\ProgramData\Micro Focus
  • UNIX: /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 service (Windows) or daemon (UNIX) 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 service (Windows) or daemon (UNIX) is running.

Windows

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

(UNIX)

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.
Note: This message applies to UNIX environments only.
Ensure that these values are added to the /etc/hosts file. You can find the hostname by typing hosntame from a command prompt. To obtain the IP address, type /sbin/ipconfig from a command prompt.
Parent topic: Licensing Error Messages


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

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


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

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


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

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


Unable to authorize (cause)

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


Updates and Product Support

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

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

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

To log in:

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

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

  2. Click Login.

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

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

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

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

You can access Product Support on the Micro Focus SupportLine Web site by clicking Help > Welcome > Web Resources in the IDE.

Parent topic: Product Information


Micro Focus End User License Agreement

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

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: Dynamic System Domains (DSD) -- enabled by Dynamic Reconfiguration (DR), 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, and VMware.

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

Java. The Licensed Software may contain or require Licensee to separately obtain the Java™ Platform, Standard Edition Runtime Environment (JRE), and in such event any use of the JRE shall be governed by the license agreement accessible at http://www.oracle.com/technetwork/java/javase/terms/license/index.html. Use of the Commercial Features for any commercial or production purpose requires a separate license from Oracle. "Commercial Features" means those features identified Table 1-1 (Commercial Features In Java SE Product Editions) of the Java SE documentation accessible at http://www.oracle.com/technetwork/java/javase/documentation/index.html.

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
  • Issues with Application Workflow Manager
    The following topic lists issues with the Application Workflow Manager functionality.
  • AppMaster Builder
  • 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
  • Eclipse IDE
  • JVM Code
  • Mainframe Programming and Management
  • Issues with Remote Mainframe Development
    The following topic lists issues with the remote mainframe development functionality.
  • Issues with Resource Adapters
Parent topic: Product Information
Related information
Updates and Product Support


Application Server JCA Support for Enterprise Server

  • Starting with Enterprise Developer 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.

  • EJBs generated for WebLogic 10.3.5 do not support local interfaces. This is because this version of WebLogic does not make business local interfaces available on the global JNDI tree.
  • IBM WebSphere issues various warnings when running some applications. These are WebSphere problems. For example:
    07/12/10 11:35:55:843 JST] 00000056 PrivExAction W
J2CA0144W: Could not find
a mappingConfigAlias for the connection ...
07/12/10 11:35:55:908 JST] 00000056 PrivExAction W
J2CA0114W: Could not fing a container managed credential alias ...

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

  • 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
Related reference
ECI Implementation (mfccl.jar)


Issues with Application Workflow Manager

The following topic lists issues with the Application Workflow Manager functionality.
  • If you receive exceptions after loading a new model:
    1. Use Validate within the Model Editor to verify your model.
    2. Clear the cache from the application context menu.
    3. Clear the cache in the Navigator View.
  • If your ISPF Dialog Applications do not work:
    1. Clear the Dialog process list from the application context menu.
    2. Disconnect, then connect to the Mainframe and restart Eclipse.
  • If you receive an error when opening the Model Editor, this might be caused by a codepage problem - the model might have been saved with a codepage different from the one it was opened with.
  • In an Application Workflow Manager modelled action, you retrieve a file from the remote zOS system directly into a COBOL project. You must set the text file encoding of the COBOL project to UTF-8 in the project properties in order for the Compiler to correctly process the source code. To set the encoding, in the project properties of the COBOL project and on the Micro Focus > Project Settings > COBOL, specify the source-encoding"utf8" Compiler directive in the Additional directives field.
  • If you are using the Application Workflow Manager with IBM's IDz and with Remote Server Explorer, the ISPF Dialog Support facility does not work.
  • When using the Application Workflow Manager with IBM's IDz and with z/Server as the server, remote copybook resolution is not supported in the editor.
  • Global Workbench Actions do not work in Eclipse 4.n. This is caused by a known issue with the Eclipse IDE (search the Web site of the Eclipse Foundation for Bug 411765).
Parent topic: Known Issues and Restrictions


AppMaster Builder

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Analysis Option
  • COBOL
  • Distributed Generation Server
  • Project Explorer
  • Workgroups
Parent topic: Known Issues and Restrictions


Analysis Option

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You cannot terminate an Analysis Option build using the "terminate build" toolbar button; you must use Build > Analysis Option > Stop Build.

Parent topic: AppMaster Builder


COBOL

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

COBOL programs with paragraphs containing IF/ELSE-IF structures that have 90 or more ELSE-IF statements cannot be generated with the Generate non-OS/VS code option checked on the Output AppMaster Builder preferences page. Generate programs containing IF/ELSE-IF structures of this size with Generate non-OS/VS code unchecked.

Parent topic: AppMaster Builder


Distributed Generation Server

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Mainframe
  • A console message (IEC141I 013-18) is issued each time a member is not found and a logrec is written for each occurrence. If a logrec dataset is being used instead of logstream, enlarge the dataset.
  • Screens that access data elements are not currently supported.
  • An IEC141I 013-18" error occurs if the mapset name given for CICS Screen generation is incorrect.
PC
  • Values specified for a mapset name are overridden by the mapset stored in the APSSCRN file.
  • If you need to change the interface for WebSphere MQ settings after initially starting the Distributed Generation Server, you must shut down the Distributed Generation Server and restart it.
  • The first time the Distributed Generation Server receives a generation request, you are prompted for a mainframe logon ID and password. This remains in effect for the duration of your Windows session. Ensure the logon ID has proper mainframe access authority for accessed datasets.
  • Most AppMaster Builder preferences are used by the Distributed Generation Server.
  • The AppMaster Builder preference Compile in COBOL project is ignored by the Distributed Generation Server.
  • If the AppMaster Builder Distributed Generation Server is shut down and then restarted, it starts as an AppMaster Builder Server. You need to then restart it as a Distributed Generation Server.
  • The Distributed Generation Server automatically changes your project path setting to the Mainframe\IDE subdirectory of your User Area for downloading APSAPPL, APRAPPL, APRPROG, APSPROG and APSSCRN files during generation. After generation, the original project path setting is restored.
Parent topic: AppMaster Builder
Related concepts
AMBCOMP Program
The WebSphere MQ DGS Interface
Related tasks
To set AppMaster Builder preferences
Related reference
JCL Example


Project Explorer

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • AppMaster Builder applications display in the Project Explorer tree structure only if they reside in the primary (local) project; AppMaster Builder applications that reside in a workgroup library outside of the project do not display.
  • Reports generated for objects that display on the Project Explorer are only available for objects physically stored in the primary project. Any attempt to generate reports for objects stored in workgroups results in a “not yet painted” message.
Parent topic: AppMaster Builder


Workgroups

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To generate programs and screens using workgroups, the Micro Focus Generator environment option must be checked on the Environment AppMaster Builder preferences page.

Parent topic: AppMaster Builder


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


COBOL Programming

  • Boolean Data Items
  • CBL2XML Utility
  • Interface Mapping Toolkit
  • Enhanced ACCEPT/DISPLAY Syntax (Adis)
  • Filenames
  • Gateway Profile Utility
  • 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


Interface Mapping Toolkit

  • The IMTK does not generally support the ODOSLIDE compiler directive. In addition, the ODOOSVS compiler directive and several DIALECT directive settings automatically set ODOSLIDE; therefore, if your program does not require that you compile using the ODOSLIDE directive, specify the NOODOSLIDE compiler directive to avoid possible compiler errors.
  • To compile a program that contains nested OCCURS DEPENDING ON clauses, which require the ODOSLIDE directive to compile, change the OCCURS DEPENDING ON syntax to OCCURS COUNT IN. This change removes the ODOSLIDE directive requirement for compiling for the IMTK, and also leaves the code valid for compilation with ODOSLIDE outside of the IMTK environment.
  • On AIX v7.2, you must install IBM's patch APAR IJ04075 in order for imtkmake -genclient to work correctly. See http://www.microfocus.com/docs/links.asp?vc=IBM_APAR_IJ04075 for details about how to install the patch.
  • REST/JSON IMTK implementation - HTTP requests sent from scripts within a web browser to REST services deployed on an enterprise server might fail due to the same-origin policy (SOP). Some browsers might implement (or support plugins that implement) techniques for relaxing SOP such as cross-origin resource sharing (CORS) that enable sending cross-origin requests successfully. For REST services, Enterprise Server does not implement a method for relaxing SOP. This means that browsers that implement CORS (or any other SOP relaxation technique) might still forbid requests made from scripts due to Enterprise Server not implementing the equivalent technique on the server side.
  • Each group field (i.e. field containing subitems) in a Java interface must have a name that is unique across all operations of that interface. Where this is not the case, client generation may fail.
  • If you encounter an error message >>> COBOL Interface generation failed Could not find a part of the path <path> when generating test clients for service interfaces, the likely cause is that Microsoft Internet Information Server (IIS) is not installed on your system.
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


Gateway Profile Utility

Context Help
You might not be able to access context help in the IDE on some versions of Windows such as Vista or Windows 7. This is because these versions of Windows do not ship with the Windows Help Program (WinHlp32.exe) which is used to open context help files, .HLP. You need to install the Windows Help Program separately - click here for more information.
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:

  • Dialog System (Character and GUI) - Dialog System applications are not supported in Eclipse but you can upgrade the non-GUI components of an application to Eclipse, and then recreate the GUI components using the GUI tools in Eclipse.
  • 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 either the COBCONFIG or COBCONFIG_ environment variable is set when you run Enterprise Developer applications or when you use Enterprise Developer to edit or create projects and the configuration file it refers to contains entries that are not valid for Enterprise Developer.

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

To work around this issue, ensure that Enterprise Developer 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 COBCONFIG_) or set it to another configuration file that does not contain the invalid tunable for the particular session you are running in.
Licensing error due to environment settings (applies to Windows environments only)
The message "Micro Focus License Manager service is not running" can occur when you invoke a Net Express, Mainframe Express or Studio Enterprise Edition utility from Enterprise Developer. This happens when the tool is invoked with Enterprise Developer environment settings while it requires the Net Express or Studio Enterprise Edition ones.

This happens when you edit files such as .dat that have a file association with Net Express or Studio Enterprise Edition.

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.
  • The setup file will install Enterprise Developer fully only on 64-bit Windows. On 32-bit Windows, not all product components will install. This is because some of the components require a 64-bit Java 8 which requires a 64-bit Windows.

    You can still run the setup file on 32-bit Windows which installs the command line support for COBOL and PL/I. The following components will not be available:

    • The Eclipse IDE
    • The 64-bit Enterprise Developer Command Prompt
    • The Enterprise Developer product Help

    On 32-bit Windows, you can manually install the Enterprise Developer functionality into an existing 32-bit installation of Eclipse. See Installing Enterprise Developer into other instances of Eclipse.

  • When installing into other instances of Eclipse you must use the Eclipse IDE for Java EE Developers package. This includes all the tools that Enterprise Developer requires. See Installing Enterprise Developer into other instances of Eclipse.
Parent topic: Known Issues and Restrictions


Data Access

  • Classic Data File Tools
  • COBSQL
  • HCO for DB2 LUW
  • File Handling
  • OpenESQL
  • Records with Alternate Keys
Parent topic: Known Issues and Restrictions


Classic Data File Tools

Open PL/I Support
When converting a record layout or segment layout file from one character set to another, the DFCONV utility and the IMS Database loader could cause corruption if the file contains Open PL/I to COBOL data item type mappings for CHAR VARYING, BIT, WIDECHAR, or WIDECHAR VARYING.
National Data Items
National data items are not supported in record or segment layouts.
Parent topic: Data Access
Related concepts
Classic Data File Tools


COBSQL

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

  • Using sequence numbers inside Sybase Embedded SQL statements causes COBSQL to lose its position in the source. This leads to the message "Premature end of expanded source" being displayed and means the code cannot be checked.
  • 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.
  • When Pro*COBOL is not installed on your local machine and you are using the local machine to access an Eclipse project on a remote machine that does have Pro*COBOL installed, background parsing can fail during compilation. You can avoid this by setting the COBSQL directive either in your Eclipse project properties, or by coding a $SET statement into the source itself. However, if you prefer to specify the COBSQL directive in a directive file only, you must specify the SQLBGP compiler directive option in the directive file as well. For example:
    p(cobsql) SQLBGP MAKESYN CSQLT=ORACLE8 end-c p(cp) endp
Parent topic: Data Access
Related reference
SQLBGP


HCO for DB2 LUW

  • Starting with Enterprise Developer 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.
  • If you have a remote COBOL project under Eclipse that uses DB2 ECM in Visual COBOL or HCO for DB2 LUW in Enterprise Developer and the DB2 software is not installed on the client machine where you are using the Eclipse IDE, you receive background parsing errors in your application. To resolve the issue, you can do either one of the following:
    • Disable background parsing Window > Preferences > Micro Focus > COBOL > Editor and disabling the checkbox for Background parsing.
    • Install the IBM DB2 client-side software on the machine on which you are running Eclipse. Go to the IBM Support Home and locate the page entitled "IBM Download Fix Packs for IBM Data Server Client Packages" .
Parent topic: Data Access
Parent topic: Mainframe Programming and Management


File Handling

  • Using Btrieve, a START operation cannot be performed with a part-key. The whole key must be used.
  • In Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer 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 Enterprise Developer: if any applications compiled prior to Enterprise Developer 2.2 share files with applications compiled with this version, you must recompile your older applications.
Parent topic: Data Access


OpenESQL

Compiling

To compile OpenESQL applications that use a 64-bit Data Source Name (DSN) for 32-bit platforms, and for which you specify the CHECK or DB compiler directive options, you must explicitly create a 32-bit DSN of the same name as the 64-bit DSN. Do this using the ODBC Data Source Administrator (32-bit). The execution process continues to use the 64-bit DSN. This applies to Windows environments (local development) only.

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.

Windows:

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

From the IDE, before compiling or recompiling:

  1. From the Application Explorer view, right-click the project; then select Properties from the context menu.
  2. Expand Micro Focus > Build Configurations > Link; then click Additional Link Files.
  3. Click Add External Files.
  4. Browse to the installDir\lib (for 32-bit) or installDir\lib64 (for 64-bit) directory, where installDir is the path to your Enterprise Developer installation, which by default is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer.
  5. Double-click oesqlebc.lib to select it and add it to the list; then click OK.

From a command prompt, after compiling:

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

UNIX:

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.

Embedded SQL Statements

Any EXEC SQL statement that specifies a table or column name containing one or more special characters must have that table or column name enclosed in quotes to prevent a preprocessor error. A special character is an ASCII character with a value greater than 128 or a hexadecimal character with a value greater than x"80".

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

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.

OpenESQL ODBC Native 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.

PostgreSQL Recommendations

  • PostgreSQL does not accept NULL date, time, or timestamp values from PIC X host variables. You must either use CAST(:hostvar as TIMESTAMP) in the SQL or use SQL TYPE TIMESTAMP in the application.
  • PostgreSQL supports embedded NULL characters in binary columns only; it does not support embedded NULL characters in character columns.
  • When using PostgreSQL with ODBC and a negative SQL code is returned to a calling application, PostgreSQL aborts transactions implicitly unless you change the default behavior of the ODBC driver. In addition, PostgreSQL does not support the ODBC API call SQLSetPos, which impedes the performance of updateable cursors.

    To work around these shortcomings, consider modifying the psqlODBC driver Configuration Options. To do this:

    1. Invoke the PostgreSQL ANSI or UNICODE ODBC Driver (psqlODBC) Setup dialog box.
    2. Click Datasource.
    3. On Advanced Options page 1, check Use Declare/Fetch.
    4. Click Page 2.
    5. On Advanced Options page 2, set the Level of rollback on errors option to Statement, and uncheck Updatable Cursors.
Parent topic: Data Access
Related concepts
OpenESQL Embedded SQL Cursor Behavior and Performance
Related tasks
To start an Enterprise Developer command prompt
Related reference
CALL
BINARY SQL Type


Records with Alternate Keys

Restriction: This topic applies to Windows environments only.
  • A write of a record with an alternate key where the alternate key is the first value for that key may now return a 0/2 file status rather than a 0/0 status if a record with that alternate key value has been deleted by uncommitted transaction (possibly the same transaction as that performing the write).
Parent topic: Data Access


Debugging, Problem Determination and Diagnostic Tools

  • Debugging in Eclipse
  • Development Remote Connection
    Kerberos security settings can lead to a failure to validate and create remote projects. This topic describes steps to identify and amend security settings to enable validation and creation of remote projects.
  • Error markers
  • Language Service
  • Remote Debugging
  • Reverse Debug and Live Recording
  • Test Coverage
  • Just-in-time debugging
Parent topic: Known Issues and Restrictions


Debugging in Eclipse

  • When debugging .gnt code on early builds of Windows 10 and Windows Server 2016, execution fails to stop at COBOL breakpoints. To resolve this, you should install the most recent Windows updates for your operating system, as this problem is only known to be present with the earlier versions.
  • The debugger ignores a COBOL watchpoint that is hit if there is no statement following the statement that modifies the data on which that watchpoint is set.
  • If you delete a project while you are debugging it, the delete action will only be partially successful and errors will occur. You must stop the debug process before deleting a project.
  • A core dump file is not created for a stack overflow condition.
  • There is an issue with "Wait for attachment" when you use Enterprise Developer for Eclipse to debug applications that run on some UNIX/Linux platforms. Eclipse connects to the debugger on the remote machine, but might not attach to the process to debug the code.

    To work around this issue, ensure that on the remote machine the TMPDIR environment variable is unset or has the same value for both Micro Focus Enterprise Developer UNIX Components server and for the running process you wish to debug. The Micro Focus Enterprise Developer UNIX Components server is the server which you started either directly with the $COBDIR/remotedev/startrdoserver script or indirectly using the daemon which is started with the $COBDIR/remotedev/startrdodaemon script.

    To check the variable used by the Micro Focus Enterprise Developer UNIX Components server:

    1. Open Remote Systems view in Eclipse on the Windows machine.
    2. Right-click the Shells element of the server connection to be tested and click Launch Shell.
    3. In the Remote Shell view, type echo $TMPDIR in the Command field, and press Enter.

      The value of the TMPDIR environment variable is shown - ensure it is the same as the one used by the process to be debugged.

      Note: The value of TMPDIR used by the Development Hub server cannot be changed in the remote shell and must be set before you start the daemon or server.
Parent topic: Debugging, Problem Determination and Diagnostic Tools


Development Remote Connection

Creating a project on a remote machine can fail to validate and hang due to the configuration of the Kerberos security settings.

To confirm that this is the issue, take the following steps:

  1. Start Eclipse using eclipsec.exe located by default at C:\Users\Public\Micro Focus\Product Name\eclipse.
    Follow the steps for creating a remote project. Validation of a remote project occurs at the end of the project configuration process. If the issue is cause by Kerberos security settings the following message will be displayed in the console used to start eclipsec.exe:
    Kerberos Username [userid]
  2. Press Enter.

    This displays a password prompt.

  3. Press Enter.

    This allows the validation to proceed and the project is created successfully.

Once you have identified the issue using the method described above you can implement a workaround. This requires you to disable the gssapi-with-mic authentication method in the Network Connections preferences. To do this:
  1. Click Window > Preferences > General > Network Connections > SSH2.
  2. On the Authentication Methods tab, uncheck gssapi-with-mic.
  3. Click Apply.
  4. Click OK
  5. Repeat the project creation process.
Parent topic: Debugging, Problem Determination and Diagnostic Tools


Error markers

The IDE does not set correctly the error markers in files that are not associated with the Micro Focus COBOL project types. Instead of setting the markers on the exact lines that cause a problem, the IDE sets all of them on the first line of the respective files. To work around this issue, you need to add the unknown file extensions or the file names as file associations for the COBOL project types. To do this, click Window > Preferences. In the left-hand pane, click General > Content Types. In the list of types, expand Text > Micro Focus Project Types. Add the file extensions in the File associations pane.

Parent topic: Debugging, Problem Determination and Diagnostic Tools


Language Service

The COBOL language service does not support tooltips for reference modified items when debugging. To view value for data items add them to the Watch or QuickWatch windows.

Parent topic: Debugging, Problem Determination and Diagnostic Tools


Remote Debugging

  • If, when you try to start debugging a remote application, you are logged on the remote machine (using connectremote) and X server is running, the debugger may encounter an error launching the application and return Debugger Error Code: -1. This may occur if you have started the RDO daemon from a user session on your hub (remote) machine.

    To work around this issue, you need to do the following:

    • Stop the startrdodaemon daemon and disconnect the RSE connection in Eclipse.
    • Either stop X server on the remote machine or establish a new connection to the remote machine using SSH.
    • Start the startrdodaemon daemon and debug the remote application.
  • When debugging a remote program, the performance of the network, specifically the latency between the local and remote machines, will have an effect on the responsiveness of Eclipse. Whenever Eclipse has to show the new execution position, a number of messages are sent from the remote machine, over the network, to get the required information. The effect of this is that it can take a few seconds after a Step command is issued before Eclipse has updated the screen and is ready for the next command.

    You can mitigate this delay by closing any unnecessary debug views. For instance, by closing the Expressions view and the Variables view, the number of messages that are sent is reduced, which allows Eclipse to update quicker.

  • Large programs can suffer from a large delay the first time that the program is displayed in the debugger and an expression is evaluated. You can reduce this delay by following these steps:
    1. Create a text file called debugconfig.xml.
    2. Add the following lines, and then save the file:
      <?xml version="1.0" encoding="utf-8" ?>
<NativeDebuggerOptions>
  <DebugOption Option="REMOTECHECKER" Value="yes"/>
</NativeDebuggerOptions>
    3. At a command or shell prompt, set the environment variable DEBUG_CONFIG to the full path name for debugconfig.xml.
    4. Start Eclipse from the same command or shell prompt.
  • Remote debugging does not work for programs running on AIX or HP machines, if you are trying to debug using Enterprise Developer installed on a Linux machine.
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


Just-in-time debugging

Just-in-time debugging can be used with native COBOL applications only. It is not supported for COBOL JVM applications.

Parent topic: Debugging, Problem Determination and Diagnostic Tools


Docker Known Issues and Restrictions

You should be aware of the following limitations when using Enterprise Developer with Docker:

Debugging

  • You must be using Visual Studio 2017 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.
  • Using the Micro Focus SupportLine Support Scan Utility, MFSupportInfo, in a container is not supported on Windows.
  • The microsoft/windowsservercore image only supports the English language so you cannot use any other languages in images based on that image.

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

Operating Systems

Enterprise Developer 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
  • Windows 10 (Pro or Enterprise editions) with Hyper-V enabled
  • Windows Server 2016
Note: Docker cannot be used on a PC that has VirtualBox or VMware installed.

Use with Micro Focus Products

  • It is not possible to containerize a COBOL application that runs under Enterprise Server for .NET .
  • There is no support for building or managing Docker images from the Enterprise Developer IDE.
Parent topic: Known Issues and Restrictions
Related information
Introduction to Docker


Documentation

Feedback link

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


Eclipse IDE

  • Background Parsing
  • Building Applications
  • Code Analysis
  • Eclipse Help Viewer
  • Eclipse Projects
  • Editing Symbolically Linked Files
  • Enterprise Server sign on credentials
  • Java Support Considerations for Eclipse
  • Leaking File Handles
  • Restrictions in Micro Focus Unit Testing Framework
    The Micro Focus Unit Testing Framework has a number of restrictions on the syntax that a test case can contain.
  • Remote Development
  • Refactoring
  • Restrictions When Working With Standalone COBOL Files
    Most editing, compiling and debugging features within the IDE require that your files are part of a project. When working with standalone files, some of the features are not available or are not fully supported.
  • WTP Tools
Parent topic: Known Issues and Restrictions


Background Parsing

When you work with a remote COBOL project, most of the processing such as program compilation and debugging takes place on the remote server. However, background parsing takes place on your local client machine and this architecture might result in parsing errors due to differences in local and remote environments.

The following are examples of when you might encounter parsing errors:
Using copybooks
The source code environments are different.
Using environment variables
If the project build is using environment variables, it is likely that they are different in the local and remote environments.
Using the Pre-complier
The software environment used in the build is different in the local and remote environments.

These parsing errors do not affect the program build. However, you can remedy the problem depending on the nature of the parsing error. For example, if you encounter parsing errors when using copybooks, you can create a softlink to the copybook on the remote machine.

From a command line prompt on the remote machine do the following:

  1. Change to the project directory:
    cd projectdir
  2. Create a softlink on the required directory or individual file:
    1. On a directory:
      ln -s $COBDIR/cpylib/ cpylib
    2. On an individual file:
      ln -s $COBDIR/cpylib/copybook.cpy copybook.cpy

Background parsing does not trigger in all cases

This happens only to files that are already opened and are being edited in the COBOL Editor. The background parsing is not triggered (in all cases). Sometimes it shows errors that do not exist or hides existing ones.

For example:

  1. Open two COBOL classes in the editor (CobolClass1 and CobolClass2. And CobolClass1 uses an artefact (A2) from CobolClass2).
  2. Delete A2 from CobolClass2.
  3. Switch to the CobolClass1 window in the editor.

    No error will be displayed in the editor until background parser is triggered for CobolClass1 (when you edit CobolClass1 or reopen it).

Note: If you start a build the error won't be visible in the Problems view and the Console but the error will still be visible in the editor until the background parser is triggered.
Parent topic: Eclipse IDE


Building Applications

  • Multi-processor compilation of the sources in a project is only supported for native COBOL and is not supported for JVM COBOL applications.
  • Multi-processor compilation should be avoided for native Object-Oriented COBOL applications.
Parent topic: Eclipse IDE


Code Analysis

The following restrictions apply to the code analysis functionality:

Branch prediction

Branch prediction is not enabled. For example, this will not be detected as unreachable code by Dead Code Analysis:
if 0 equals 1
               display "Unreachable code"
           else
               display "World"
           end-if

Supported languages

Only the COBOL language is supported.

Conditional compilation

Conditional compilation is not supported.

ENTRY defined through variable

ENTRY statements defined through variables are not supported, and the ENTRY's statements will be marked as dead even if they can be called.

working-storage section.
       78 entry-name value "my-entry-name".

       procedure division.

       entry entry-name
           display "this is my-entry-name"
           goback
       .

In the example above, the DISPLAY statement will be marked as dead even if it can be called.

Local variable declarations

Local variable declarations are not supported.

Managed code support

Managed code and the new OO COBOL statements are not supported.

Parent topic: Eclipse IDE


Eclipse Help Viewer

  • A known issue in JRE 1.7.0_45 (issue JDK-8028111) causes problems with searching and indexing the help in the Eclipse help viewer if you are running Eclipse on a machine that has this version of JRE installed.
  • Clicking the Help button on the new project wizard page results in an error and the dynamic help window is not displayed. This is a known issue with the Eclipse IDE on some Linux platforms.
Parent topic: Eclipse IDE


Eclipse Projects

  • If you are upgrading your license from Enterprise Developer for Eclipse Personal Edition (v2.2 or earlier) to Enterprise Developer, or from Enterprise Developer Connect (v2.2.1 or later) to Enterprise Developer, any existing projects compiled to either .exe or .dll files using the old license must be updated in order to recreate the .cobolBuild file. You can do this done by adding or removing files from the project or by deleting the .cobolBuild file. Updating the project in this way ensures Eclipse will fully build the executable files.
  • Opening a COBOL or a PL/I project in Enterprise Developer modifies the .cobolProj and .pliProj files. Once modified the .cobolProj and .pliProj files are no longer backward compatible with older versions of Enterprise Developer. This prevents you from opening the same projects in earlier versions of Enterprise Developer.
    Note: Micro Focus recommend that you backup your .cobolProj and .pliProj files before opening projects created in earlier versions of Enterprise Developer.
Parent topic: Eclipse IDE


Editing Symbolically Linked Files

Modifying the target of a symbolically linked COBOL source file does not force a recompile of the program when refreshed in the Eclipse IDE. In addition, if the file is open in an editor while the target linked source file is edited then the changes are not automatically refreshed in the editor. Micro Focus recommends that you do not use symbolically linked files with Eclipse projects.

Note: This behavior applies to Windows and UNIX environments.
Parent topic: Eclipse IDE


Enterprise Server sign on credentials

Enterprise Server sign on credentials which were created on Windows when using the 32-bit versions of Enterprise Developer or Visual COBOL for Eclipse are not compatible with the 64-bit versions of those products, and vice versa.

Users are required to re-enter credentials which are not compatible with the current version of the product. You only need to do this the first time they are used in the current product.

Parent topic: Eclipse IDE


Java Support Restrictions

Java Support Considerations for Eclipse

The following restrictions apply when installing Enterprise Developer with the default version of Eclipse shipped with it:

  • Eclipse requires 64-bit Java 8 or 64-bit Java 9.
  • Eclipse does not support Java 6 or Java 7. However, Enterprise Developer can still use Java 7 or later to compile and run JVM COBOL or Java code.
Parent topic: Eclipse IDE


Leaking File Handles

The startrdodaemon daemon leaks file handles on every RSE connect and disconnect. As a result, the number of file handles increases until the limit for a process in reached and an error is reported.

It is recommended that you increase the number of file descriptors per process. Consult your operating system documentation for guidelines on how to do this.

Parent topic: Eclipse IDE


Restrictions in Micro Focus Unit Testing Framework

The Micro Focus Unit Testing Framework has a number of restrictions on the syntax that a test case can contain.

The following syntax is not currently supported within a test case:

  • Procedural managed COBOL only supported from the command line utility
  • OO COBOL code
  • User interface syntax
  • PL/I syntax
  • Mainframe emulation components, such as CICS batch
Parent topic: Eclipse IDE
Parent topic: The Micro Focus Unit Testing Framework


Remote Development

Remote Development using Remote System Explorer

The following problems can occur when you are developing a project using Remote System Explorer (RSE) to browse the file system of a remote machine.

  • You might get poor performance of RSE if you have the Web Standards Tool (WST) Eclipse plug-in installed.
  • If you close Eclipse while a remote project is open, the following errors occur when you restart Eclipse:
    Parent Error: Workspace restored, but some problems occurred.
Error1: Could not read metadata for '<remote project name>'.
    When this happens you must reopen the project.
  • Some features that are available in the Eclipse IDE rely on the time between your client and the remote system to be synchronized. Features such as the dragging and dropping of files or incremental project builds rely on this, and if the times differ, those features may produce unexpected results.
Parent topic: Eclipse IDE
Related concepts
Software requirements
Related reference
Installing Enterprise Developer into other instances of Eclipse


Refactoring

The following restrictions apply to rename refactoring:

  • It is not possible to rename identifiers in a copybook which is referenced using the COBCPY environment variable but is not located in the workspace.
  • It is not possible to rename identifiers in copybooks referenced using a COPY... REPLACING statement.
  • It is not possible to rename data items in JCL or BMS files.
  • It is not possible to rename typedef members.
  • It is not possible to rename identifiers in any resources that are outside the current workspace.
  • It is not possible to rename identifiers defined using the AS phrase.
  • It is not possible to rename a program name or an entry-point.
  • Rename using a COBOL reserved word is not supported. The IDE does not issue a warning if you use a reserved word to rename an identifier and will rename the instances of the identifier. Trying to build your application, however, will fail.

The following restrictions apply to native COBOL only:

  • It is not possible to rename copybooks from the editor. You can rename copybooks from COBOL Explorer. This, however, does not change any of the references to the copybooks in the code.
Parent topic: Eclipse IDE


Restrictions When Working With Standalone COBOL Files

Most editing, compiling and debugging features within the IDE require that your files are part of a project. When working with standalone files, some of the features are not available or are not fully supported.

Support for editing, compiling and debugging of standalone files is only available for native COBOL programs.

The following features and technologies are not supported:

  • Automatic compile when saving the file.

    You need to recompile the file manually.

  • Linking programs to .exe or .dll files.
  • Pre- or post-build events.
  • Compiling to managed COBOL
  • Compiling of Assembler, PL/I programs or other Mainframe Subsystem Support programs (CICS, JCL or IMS).

In addition:

  • Compiling standalone files only produces an .int or a .gnt file.
  • Breakpoints, Program breakpoints and Watchpoints are not preserved when you close the file.
  • To open a copybook referenced from a standalone file, they must be stored in the directory that contains the standalone file, or in a directory specified by COPYPATH.
  • Any Compiler directives you set on the files are not persisted automatically.

    If you compile a file, the Compiler directives are included in the .idy file. However, ensure that Eclipse can locate the .idy file. If it is not in the same folder as the source file, click Window > Preferences > Micro Focus > COBOL > Standalone Files > Program Symbols to add the location where the file is stored.

Parent topic: Eclipse IDE
Related concepts
Accessing Source Code Without a Project


WTP Tools

Some features provided with WTP Tools can slow down the performance when you are working with large projects. For example, the label decorator “Web Service Decorator” affects the performance of the “Link with Editor” feature ( [image]) of COBOL Explorer and Project Explorer. To work around this issue, go to Windows > Preferences, expand General > Appearance > Label Decorations, and disable Web Service Decorator.

Parent topic: Eclipse IDE


JVM Code

  • JVM COBOL support
  • Adding Projects to a COBOL JVM Project's Java Build Path
  • Editing Remote JRE Settings
  • OpenESQL
  • Using Java and JVM COBOL Together
  • COBCH0015S Procedure division too large
Parent topic: Known Issues and Restrictions


JVM COBOL support

Java Virtual Machine

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:

  • JVM COBOL is not supported in Mainframe Subsystem applications.
  • 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.
  • COBOL JVM projects require Java 7 or later. Trying to build a COBOL JVM project that targets a version of Java earlier than version 7 while having it installed in Eclipse results in a COBOL syntax error COBCH1561S ("JVM support not found: are you using a supported version of the JRE?"). You can use the Quick Fix command to resolve the problem and link to a supported version of Java:
    1. In Problems view, right-click the row containing the error.
    2. Click Quick Fix. Alternatively, you can press Ctrl+1. This opens the Quick Fix dialog box with a suggested fix for the problem.
    3. Select the fix that replaces the old JRE with a supported JRE version.
    4. Click Finish.
    If a supported JRE is installed on your machine, you receive a message that the JRE has been successfully replaced. If no supported JRE build path is available on your machine, then you need to add it, see Compiling JVM COBOL for more details.
  • 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.

Application Servers

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 Code
Related concepts
Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server
Related reference
Compiling JVM COBOL
Installing Enterprise Developer into other instances of Eclipse
Installing as an Upgrade
Software requirements
COBCH1561S JVM support not found: are you using a supported version of the JRE?


Adding Projects to a COBOL JVM Project's 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.

Parent topic: JVM Code


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 Code


OpenESQL

JDBC

  • You cannot directly enable integrated authentication for Microsoft SQL Server in Enterprise Developer. 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 Code
Related concepts
OpenESQL Embedded SQL Cursor Behavior and Performance


Using Java and JVM COBOL Together

  • On Linux, you need to use the Java/COBOL launcher, cobjrun, to call COBOL from Java. However, an attempt to call COBOL from Java using the Eclipse IDE might fail with error "Specified executable /opt/microfocus/EnterpriseDeveloper/bin/cobjrun does not exist for jdkversion". This is because Java searches for the cobjrun executable in the bin directory of the JDK installation. To work around this, you need to add a symbolic link to cobjrun in the bin directory of the JDK installation and then specify this link as the JAVA executable. Read Java/COBOL Application Launcher for more.
  • When calling a COBOL method from Java, even if it is known that the COBOL method may throw exceptions, it is not possible to use a catch block in the Java to catch that particular exception. It is possible to catch java.lang.Exceptions in the Java, and from there to determine the actual exception type.
Parent topic: JVM Code
Related information
Using the Java/COBOL Application Launcher from the Eclipse IDE


COBCH0015S Procedure division too large

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.
Parent topic: JVM Code


Mainframe Programming and Management

  • Assembler Emulation
  • CICS
  • CICS Web Interface
  • CICS Web Services
  • DOCUMENT APIs
  • Enterprise Server
  • HCO for DB2 LUW
  • HCO for SQL Server (HCOSS)
  • Historical Statistics Facility (HSF)
  • IMS Support
  • JCL
  • Mainframe Call Generator
  • Mainframe Subsystem Support (MSS)
  • PL/I Support
  • Run-time Behavior
  • SQL Option for DB2
Parent topic: Known Issues and Restrictions


Assembler Emulation

MFASM, the mainframe assembler emulator for IBM High Level Assembler programs, has the following restrictions and limitations:

  • E15 and E35 Assembler sort exits are not supported.
  • The IMS2ASM routine is not supported.
  • The Assembler debugger requires that you set the configuration variable ES_SERVER_CONSOLE=YES in any enterprise server that will be used to debug Assembler modules.
Parent topic: Mainframe Programming and Management


CICS

  • An EXEC CICS DELAY statement may sometimes produce a difference of one second.

CICS file control has the following limitations:

  • Neither CICS- nor user-maintained data tables are supported. From an application programming point of view, this limitation has little or no impact. From a systems programming perspective, you will not have the ability to eliminate disc I/O activity by defining user-maintained tables.
Parent topic: Mainframe Programming and Management


CICS Web Interface

Enterprise Server now supports CICS web-enabled application programs.

The CICS Web Interface APIs have the following limitations:

  • Only BASIC authentication is supported
  • Trailer HTTP headers are not supported
  • Conversion of codesets and codepages is not supported
  • Converter programs are not supported
  • You cannot connect to an HTTP server through a proxy
  • The Action(Expect) option of a WEB SEND request is ignored
Parent topic: Mainframe Programming and Management


CICS Web Services

  • CWS does not support CICS applications that use both COMP and COMP-5 items. By default, the mapping module generate COMP-5 SYNC items rather than COMP. CWS supports CICS applications that use COMP declarations when the ES_CWS_WSBIND_COMP environment variable is set to Y.
  • CICS Web services in Enterprise Developer supports the COBOL programming language exclusively.
  • Features that are not supported by CICS Web services in Enterprise Developer include but are not limited to the following:
    • Web Services security
    • Web Services addressing
    • MTOM/XOP optimization of binary data
    • Web Services Atomic Transactions
    • Pipeline exits
    • xsd:any
    • xsd:anytype
    • base64Binary type
    • Nillable attribute
    • Run-time validation
Parent topic: Mainframe Programming and Management


DOCUMENT APIs

Enterprise Server now supports the following DOCUMENT API:
  • CREATE
  • INSERT
  • RETRIEVE
  • DELETE
  • SET

If the templates used by your application are defined as members of a PDS where the PDS defaults to DFHHTML, you need to setup the environment variable DFHHTML. This variable allows concatenation of up to 20 PDS names, where the names can be separated by a semi-colon. For example:

DFHHTML=MYPDS.HTML.LEVEL1;MYPDS.HTML.LEVEL2; MYPDS.HTML.LEVEL3;... MYPDS.HTML.LEVEL20
DOCUMENT support has the following limitations:
  • DOCUMENT CREATE and DOCUMENT INSERT do not support HOSTCODEPAGE
  • DOCUMENT RETRIEVE does not support CHARACTERSET and CLNTCODEPAGE
  • You cannot create a document from, or insert into a document, a previously-retrieved document which contains tags embedded by CICS.
  • DOCUMENT CREATE and DOCUMENT INSERT do not support the #include command within a template.
  • RECFM V is not supported for PDS associated to a DOCTEMPLATE definition. You must use RECFM Line sequential or Fixed instead.
Parent topic: Mainframe Programming and Management


Enterprise Server

  • On Windows 10, if you are using Microsoft's EDGE browser to access the Enterprise Server Administration GUI, issues with EDGE can cause the automatic refresh feature to display a dialog asking whether you want to resubmit a form. To work around this issue, cancel the resubmit request and then refresh the server list page or the Home page of Enterprise Server Administration. You can also turn off the automatic refresh by setting the Auto-refresh interval setting on the Home page of Enterprise Server Administration to 0.
  • User ID and password constraints:

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

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

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

  • The Historical Statistics Facility may generate incorrect records for SSTM-enabled enterprise servers.
  • In Enterprise Developer 2.3, some job scheduling tools from third-party vendors might stop communicating with Enterprise Server. This might have an impact on our external partners who integrate with Enterprise Server such as job schedulers which do not use MFBSI. The issue might occur with job schedulers such as Zena, CA, ASG or UC4, if these are run outside of a COBOL environment with the path set. Click here for more information about the issue and how to work around it.
  • There is currently no template for a PL/I-configured enterprise server.
  • When running Enterprise Server applications on HP Itanium in 32-bit mode, you could receive an error such as "CASCD1057S JES Initiator for Server ... abended by signal 00004". In this case, set the environment value COBMAINSTACK to a value greater than 500000 to increase the default stack size.
  • Starting a region on Windows Vista or Windows 2008 Server via the CAS administration page starts the server under the SYSTEM account, which does not have desktop access. Messages are displayed to CASCD which causes the Interactive Services Detection dialog box to be repeatedly displayed. To prevent this from occurring you can perform the following configuration:
    1. Click Start > Control Panel, and then click Administrative Tools.
    2. Double-click Services.
    3. In the service list, double-click Micro Focus Directory Server.

      This opens the Micro Focus Directory Server Properties dialog box.

    4. On the Log On tab, uncheck Allow service to interact with desktop.
    5. Click OK.
    6. Restart the Micro Focus Directory Server.
Parent topic: Mainframe Programming and Management


HCO for SQL Server (HCOSS)

  • HCOSS applications do not support dynamic SQL using the SQL Descriptor Area (SQLDA) when the application calls a SQL CLR stored procedure.
  • Under Enterprise Developer, no project templates are available for HCOSS applications at this time. For information on creating COBOL projects for HCOSS applications, see the tutorials in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\sql\hcoss directory. You can also view the samples in the Mainframe Samples Browser. See To start the Samples Browser for more information.
  • HCOSS SQL Server databases created with an Enterprise Developer version of 2.2 Update 2 HotFix 3 or earlier might be missing HCOSS-provided scalar functions. To ensure your scalar functions are up to date, run the InstallDigitsFunction.sql script against each of your HCOSS databases. The script is located by default in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory. The user running the script must have read, update, and create permissions for the database SYSIBM and dbo schemas.
  • Starting with Enterprise DeveloperEnterprise Developer 2.2 Update 1, HCOSS is not backwardly compatible with HCOSS databases created in earlier versions, and that also fit the following description:
    • Use a 64-bit Enterprise Server
    • SQL Server stored procedures called from an ODBC application
    • Use DBRMLIB

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

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

  • Because z/OS DB2 supports date/time arithmetic using regular addition and subtraction operators but SQL Server requires the use of built-in functions to achieve the same results, you might be required to edit DB2 conversion functions for date/time special registers and labeled durations to provide clarification:

    Remove parentheses

    Change:

    (CURRENT DATE) - (other_column)

    To:

    CURRENT_DATE - other_column

    Add a DATE expression

    Change:

    column1 - column2

    To:

    DATE(column1) - DATE(column2)

    These rewritten expressions are still valid mainframe SQL, ensuring that portability is not sacrificed.

Parent topic: Mainframe Programming and Management


Historical Statistics Facility (HSF)

You can create records for tasks that have been executed and completed under Enterprise Server using the Historical Statistics Facility (HSF).

HSF has the following known issues:

  • HSF doesn't populate the Program field in ESMAC or Prog field in the .csv file for IMS records.
  • The User field (containing the user id) is not populated when the user has the default user name - for example CICSUSER.
  • All fields with time values are measured in hundredths of a second. A side effect of this is that cumulative times, such as the total time a transaction accesses a file or temporary storage queue, will display as zero if each access took less than a hundredth of a second but the total is greater than a hundredth of a second.
  • If a JCL file is only deleted (and not opened or closed), then the DDName for that JCLF record will be blank.
  • If a JCL file is opened multiple times in the same job, then the values in the DSType and DSAccessType fields for that JCLF record will relate to the final time that it was opened.
  • JCLF records are not shown in ESMAC.
  • JCLF records are ignored by the aggregation utility casfhsf.
  • If a job step abends, then the total response time shown in the job's END record will exceed the response time of all the steps. This anomaly is due to the time taken to write a console message after the step abends and before the job ends.
  • If a job step abends because a data set was not found, no HSF record is created for that step.
Parent topic: Mainframe Programming and Management


IMS Support

IMS MFS Displays

In some circumstances the TN3270 stream sent when an IMS message screen is requested does not display as expected. This can happen if you have private copies of the system MFS objects. These objects are distributed in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ims (Windows) or $COBDIR/etc/ims (UNIX).

If you encounter this problem, delete any local copies of these objects. The system objects are:

  • 427FdFSDF1.DIF
  • 427FDFSDF1.DOF
  • 427FdFSDF2.DIF
  • 427FDFSDF2.DOF
  • 427FdFSIGN.DIF
  • 427FDFSIGN.DOF
  • 477FdFSDF1.DIF
  • 477FDFSDF1.DOF
  • 477FdFSDF2.DIF
  • 477FDFSDF2.DOF
  • 477FdFSIGN.DIF
  • 477FDFSIGN.DOF
  • DFSDSPO1.MOD
  • DFSIGNI.MID
  • DFSIGNP.MOD
  • DFSMI1.MID
  • DFSMI2.MID
  • DFSMO1.MOD
  • DFSMO2.MOD
  • DFSMO3.MOD

GSAM Databases

Enterprise Developer does not support the following:

  • GSAM Record Search Arguments (RSAs)
  • GSAM undefined length records
Parent topic: Mainframe Programming and Management


JCL

JCL VSE:

  • When running Enterprise Server applications on HP Itanium in 32-bit mode, if you receive an error such as "CASCD1057S JES Initiator for Server ... abended by signal 00004", you need to set the environment value COBMAINSTACK to a value greater than 500000 to increase the default stack size.

JCL utilities:

  • Calling MFFJUXIT after a parsing error B539260 results in corrupting the JCL file name in -U-pc-fname. The file name is missing some leading characters.
  • You cannot restart jobs that have been hard-killed, as they no longer possess the job information required for a restart.

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

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

Parent topic: Mainframe Programming and Management


Mainframe Call Generator

Not all mainframe programs are suitable for remote execution using the Mainframe Call Generator. Before using the Mainframe Call Generator for an application, check that the application does not use any of the following features:

  • MVS control blocks, passing back a control block to Enterprise Developer on the calling Windows machine will result in unexpected behavior.
  • Multiple programs invoked in a multi-step JCL stream. Each program calls a subroutine (Assembler) to detect in which step it is running. If the Assembler subroutine is the remote program (that can not be offloaded to the Windows machine), this will result in unexpected behavior, as the JCL on the mainframe will be a task started by the Mainframe Access Server, rather than the JCL started by Enterprise Developer.
  • Allocation of OS/390 data sets. Allocations made in Enterprise Developer do not translate to allocations in the remote subroutine that is run by the task started by the Mainframe Access Server. Only those allocations available to Mainframe Access Server are available to the subroutine.
Parent topic: Mainframe Programming and Management


Mainframe Subsystem Support (MSS)

Using the ECI interface with the CICS Transaction Gateway

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

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

The default is 4.

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

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

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

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

Mainframe utilities

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

The casstart command

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

Parent topic: Mainframe Programming and Management


PL/I Support

Open PL/I was designed to be, and still is, an ANSI standard PL/I compiler. Customers interested in migrating need to assume changes to existing PL/I applications may be required to remove any proprietary mainframe syntax and/or deal with differences in behavior in order to make programs portable.

Compiler

  • PL/I can be compiled, linked and debugged in 32-bit and 64-bit mode on Windows and the following UNIX platforms: Solaris (SPARC), Red Hat Linux (Intel), and SUSE Linux (Intel). On AIX, only 32-bit mode is supported. Solaris (Intel), Oracle Linux, HP-UX Itanium and z/Linux are not currently supported.
  • As no PL/I compiler implementation exists on HP-UX Itanium or the z/Linux platforms, then any remote compilation of PL/I programs to those platforms from the Eclipse IDE is not possible. You will still be able to create a remote connection to those platforms and create PL/I programs and include files. However, when attempting to compile, the Ant build will fail. The same problem will occur on AIX too.
  • On SUSE, the PL/I CodeWatch debugger does not display output with MicroFocus ViewNowX. To resolve this issue, you need to install a HotFix of ViewNowX - contact Micro Focus SupportLine for more details.

Macro Preprocessor

  • The Micro Focus PL/I Macro Preprocessor supports the majority of the IBM PP(MACRO) functions. The only support for PP(PLX) is for the deprecated KEYS option. There are no plans to further extend the existing support for PLX.

Syntax

  • In the AIX version of Open PL/I, the ABS function returns incorrect values for very small floating point operands.
  • The internal representations of floating point constants on the Sun versions of Open PL/I are sometimes different from those on the IBM RS6000.
  • The compiler does not diagnose a mismatch between actual parameters and the parameter list in the entry declaration when the dimension attribute is used in the parameter list.
  • No diagnostic is generated when you pass an array argument to a non-array parameter.
  • Static initialization of a pointer to the address of a static data item is not supported.
  • The PUT FILE statement adds an extra character in front of the data being written into a file.
  • Prior to Enterprise Developer 2.2, if using the -cics, -ims, or -mvs options when compiling with mfplx on a little endian platform, the possibility for errors existed. Starting with Enterprise Developer 2.2,-cics, -ims, or -mvs options when compiling with mfplx automatically also uses -bigendian, thereby eliminating the possibility for these errors.

    Evaluate any applications built using a prior release to determine any impact on any data files being used.

CodeWatch

  • The sample demo sessions in the back of the CodeWatch User's Guide may not match exactly with this version of CodeWatch.
  • CodeWatch is unable to evaluate an array in a based structure when the dimensions of the array are declared using the REFER option.
  • Problems may arise when evaluating expressions containing certain built-in functions, especially when given incorrect arguments (for example, wrong type or wrong number of).
  • EVALUATE of BASED and CONTROLLED arrays do not work when using CodeWatch.
  • When using CodeWatch, EVALUATE can not use the POSITION attribute.
  • On platforms where the WIDECHAR data type is supported, CodeWatch allows evaluation of WIDECHAR variables only. Evaluation of WIDECHAR expressions is currently not supported.

    For WIDECHAR variable evaluation, half byte-pairs outside the ASCII range display as a '.' character. Use the EVALUATE command with the /h option to display hexadecimal values for each byte-pair. For example:

    dcl wc wchar (16) init('003900370038'Wx);

...

eval wc

WC = .9.7.8. . . . . . . . . . . . .  {widechar (16)}

eval /h wc

WC = 00 39 00 37 00 38 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 00 20 (hex)  {widechar (16)}

Eclipse PL/I Debugger

  • The variables for the current line of execution are not automatically displayed in the Variables pane. The workaround is to manually enter variables in the Expressions pane.
  • Setting a variable watchpoint by setting a breakpoint on the line of the DCL statement is not possible in this release. Variable watchpoints can be set by selecting the variable(s) in the Outline pane.
  • The Expressions pane will not display arrays that contain more than 100 elements. If you need to view an array that contains more than 100 elements, add the individual array elements to the Expressions pane instead.
  • Although Eclipse allows breakpoints to be set in include files, they will not be honored by the debugger as there are no debug symbols available to support for them.
  • On UNIX, no output window is being displayed for viewing output or entering input.
Parent topic: Mainframe Programming and Management


Run-time Behavior

  • Enterprise Developer does not support environment variables with names containing embedded spaces.
  • When running .int code, you get incorrect results when you query data items in the Thread-Local-Storage Section if the program has not yet accessed Thread-Local-Storage.
  • In mainframe emulation of DFSORT, the run-time system error COBRT252 Memory corruption detected (Fatal), might occur when performing a SORT FIELDS=COPY on a file with a record format of VB.
Parent topic: Mainframe Programming and Management


SQL Option for DB2

  • You must have administrator privileges and you must enable server security before you can delete a user from the XDB Server. Otherwise, XDB Server returns the error "X124 Illegal operation on system object".
  • SQL Option for DB2 only supports 32-bit environments. Therefore, you must be sure that all projects compiled using the SQL Option for DB2 preprocessor (XDBECM) are 32-bit projects. To do this:
    1. In Eclipse, open the project properties.
    2. Expand Micro Focus > Build Configurations; then select COBOL.
    3. In the Platform Target group, select 32 bit; then click OK.
Parent topic: Mainframe Programming and Management


Issues with Remote Mainframe Development

The following topic lists issues with the remote mainframe development functionality.
Port not saved after restarting Eclipse
Sometimes, after the first connection definition, the port you use to connect to the Mainframe is not saved. To work around this issue:
  1. After you have defined your mainframe connection, explicitly connect and disconnect from the Mainframe.
  2. After the first restart of Eclipse, ensure that the port is correct.
The tree view in MVS Explorer does not open
You receive an internalGetChildren error when you try to open the tree view in MVS Explorer. To resolve this problem:
  1. Verify your filter definition, disconnect and then connect to the Mainframe.
  2. If this does not solve the problem, restart Eclipse.
Panels containing Panel REXX processing produce a panel error

Customers using the Launch ISPF function under the MVS Explorer in the ED Remote System view need the IBM PTF for APAR "OA46529: ISPP336 ERROR DISPLAYING PANEL WITH *REXX PROCESSING" to be installed on z/OS.

Without this PTF, panels containing Panel REXX processing produce a panel error.

The IBM PTF is expected to be available on Jan 16th 2015.

z/Server
IBM's PTF UA75804 causes ISPF dialogs in a user server to stop working. If you have this PTF installed, contact Micro Focus SupportLine to obtain a fix for this issue.

-2814867 (1098663)

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 in the subject line and body of your Electronic Product Delivery Notice email that you received from Micro Focus.

On Windows, if you are reporting a protection violation you might be asked to provide a dump ( .dmp) file. To produce a dump file you use the Unexpected Error dialog box that is displayed when a protection violation occurs. Unless requested by Micro Focus SupportLine, leave the dump setting as Normal (recommended), click Dump, then specify a location and name for the dump file. Once the dump file has been written you can email it to Micro Focus SupportLine.

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 Windows, you can use the Micro Focus SupportLine Support Scan Utility, MFSupportInfo, to create either:

  • a .log file that contains the details about your environment, Micro Focus SupportLine products, and settings.
  • a .zip archive that includes the same information as the .log file plus some product configuration files from c:\ProgramData and the product installation log files.

MFSupportInfo.exe is stored in <install-dir>\bin.

To run MFSupportInfo:

  1. Start a 32-bit Enterprise Developer command prompt.
  2. Enter MFSupportinfo at the command prompt to start the utility.
  3. Create a .log file or a .zip archive as follows:
    1. To create a .log file, click File > Save.

      This prompts to save the .log file, MFSupportInfo_Log_MachineName_YYYY-MM-DD_HH-MM-SS.log, in the %temp% directory.

    2. To create a .zip archive, click Tools > Create Zip Package.

      This creates a .zip archive, MFSupportInfo_Log_MachineName_YYYY-MM-DD_HH-MM-SS.zip, in the %temp% directory.

  4. Send the diagnostic information to your Micro Focus SupportLine representative:

    The following requires an Internet connection and an Email client:

    1. Click Tools > Email Log to SupportLine to open the Email Log dialog box.
    2. Fill in the required fields and click Send.

    If the machine is not connected to the Internet or if there are no Email clients installed, copy either the .log file or the .zip archive to a machine that is connected to the Internet. Use your Email client to email the files to Micro Focus SupportLine at supportline@microfocus.com together with the Support Incident (SI) number, if available, and any additional details that might be useful to diagnose the issues that you are experiencing.

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.

If COBDIR is set to a location that does not contain etc/cobver or COBDIR is not set, mfsupport gives you the option to search your machine for possible product locations. Note that the search can take some time if you have a large amount of disc storage and files.

Parent topic: Contacting Micro Focus


Contact information

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

Additional technical information or advice is available from several sources.

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

To connect, enter http://www.microfocus.com in your browser to go to the Micro Focus home page, then click Services & Support > Support Resources > All Support Resources. In the Browse by Product field, click the product you require support for. 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


Sample Programs

We supply a number of demonstration programs to help you better understand some of the concepts involved when working with COBOL projects in Eclipse.

Windows: You use the Samples Browser tool to access the available samples. For instructions on accessing the Samples Browser, see To start the Samples Browser.

The demonstration programs are installed in subfolders under %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples by default.

UNIX: The sample programs are contained in a .jar file that you import into your Eclipse workspace. There are also several demonstrations that we supply that contain a makefile or scripts to enable compilation from a command line.

  • To start the Samples Browser
  • Demonstrations of Mainframe Subsystem Support
  • Demonstrations of COBOL
  • Using the Command Line Demonstrations
Parent topic: Welcome


To start the Samples Browser

Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Mainframe Samples or Visual COBOL Samples
Windows 8.1
  • From the Windows Start screen, click either the Mainframe Samples or the Visual COBOL Samples tile
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > Mainframe Samples or Visual COBOL Samples
Parent topic: Sample Programs
Related concepts
Demonstration Applications
Demonstration Applications
Demonstration Applications
Demonstration Application
Sample Programs


Demonstrations of Mainframe Subsystem Support

We provide a number of demonstration programs designed to help you to better understand some of the concepts involved when developing Mainframe Subsystem Applications.

The following demonstrations are supplied:

Assembler - ACCT Demo
AACT is a sample CICS 3270 transaction that comprises several Assembler programs and a single BMS map, and uses the resource definitions in the file dfhdrdat. A tutorial, Tutorial: Assembler in the Getting Started section of your product Help shows you how to implement and test the AACT transaction.
Assembler - QSAM Demo
Shows you how to work with QSAM files.
Assembler - VSAM Demo
Shows you how to work with VSAM files.
CICS Classic - ACCT Demo
Shows you how to run and debug an Eclipse project for CICS on an Enterprise Server instance.
CICS Classic - ACCTCLNT Demo
Shows how you can run and debug a Mainframe Subsystem project for CICS as an HTTP client on an Enterprise Server instance. The demonstration is also used by a tutorial in your product help, which contains further detail about the setup of an enterprise server and a COBOL project.
CICS Classic - ACCTWEB Demo
Shows how to build and run the Web-enabled version of the sample transaction ACCT.
CICS Classic - CLUSTER Demo
Shows how to JCL jobs with shared datasets (catalog and spool shared by multiple servers) in an enterprise server maintaining the dataset integrity.
CICS Classic - CTGDEMO Demo
Shows how to run and debug CTG client and server programs.
Data Tools Demo
Shows how to work with data files in the Data File Tools utility.
HCO for DB2 LUW - Getting Started
Shows how to use the Host Compatibility Option.
HCOSS Eclipse - Function Emulation
Shows how to add some maths functions that emulate standard maths functions in DB2 to the SQL server.
HCOSS Eclipse - Labeled Durations
Shows how HCOSS manages DB2 date formats and labeled duration calculations.
HCOSS Eclipse - TwoPackageSet
Shows how to use HCOSS to switch package sets and alternate fetching data using a single cursor name. Also shows how to bind the application using the HCOSS Manage Packages and Plans tool.
IMS - Installation Verification Program
Shows how to configure an enterprise server to run IMS applications, and then build and run an IMS application. It also demonstrates the Installation Verification Procedure (IVP) to confirm that the IMS support is correctly installed.
JCL - Classic JCL Demo
Shows how to create a JCL application and then run it on an enterprise server.
JCL - Examples
Includes a number of additional files that demonstrate JCL functionality. For more details, see the comments in the code.
Parent topic: Sample Programs


Demonstrations of COBOL

Windows

You can use the Samples Browser tool to access the available samples. In the main window of Samples Browser you have:

  • The pane on the left lists the categories of samples.
  • The central pane lists the demonstration programs for each category.
  • Click on a sample in the list to preview its readme in the bottom pane.
  • Click Open sample folder to open the folder containing the files of the sample in Windows Explorer.

To access the demonstrations:

  1. Click Start > All Programs > Micro Focus Enterprise Developer > Samples > Visual COBOL Samples. This opens the Samples Browser form.
  2. Select a sample in the central pane and click Open sample folder.

    This opens the folder that contains the files of the sample. Copy the full path to the folder.

  3. To open the sample in Eclipse, start Enterprise Developer.
  4. Click File > Import.
  5. Choose General > Existing Projects into Workspace and click Next.
  6. In the Select root directory field, specify the location of the sample and press Enter.

    This loads the list of the sample projects available in the specified location.

  7. Select the samples you want from the list, check Copy projects into workspace, and click Finish.

UNIX

The demonstrations programs are contained in a .jar file that needs to be imported into your Eclipse workspace.

To access the demonstrations:

  1. Select File > Import.
  2. Choose General > Existing Projects into Workspace and click Next.
  3. Choose Select archive file and browse to /opt/microfocus/EnterpriseDeveloper/demo and double-click samples.jar.

    This opens the list of sample projects.

  4. Select the samples you want from the list and click Finish.
This loads the selected projects into your workspace.

The following samples are supplied:

Airport Demo (Managed)
Shows a Java Web application with a managed COBOL back-end that runs on an Apache Tomcat server.
Airport Demo (Native)
Shows how to use native COBOL to handle indexed data items. The demonstration is a console application that helps calculate the distance between two airports. The airport codes are stored in the airports.dat file.
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.
DB2 ECM - Connect
Shows the syntax variants for connecting to and disconnecting from a DB2 database using Type 1 CONNECTs that DB2 LUW supports.
DB2 ECM - Dynamic
Shows how to use dynamic SQL with DB2 LUW to perform various SQL operations.
DB2 ECM - LOB Data Types
Shows how to use the LOB LOCATOR and VALUES functions to retrieve Lob data from DB2 LUW.
DB2 ECM - Select
Shows how to use the singleton SELECT and the cursor-based FETCH statements with DB2 LUW.
DB2 ECM - Whenever
Shows how to use EXEC SQL WHENEVER for error handling, and DB2(MSGAREA) to specify a COBOL variable for retrieving error messages larger than 70 bytes.
Delegate Combining (JVM)
Shows how to combine delegates using the '+' and '-' operators.
Delegates (JVM)
Shows how to use delegates in COBOL for JVM.
Enums (JVM)
Demonstrates how to use enumeration in COBOL for JVM.
Events (JVM)
Shows how to attach a method to an event and then - to detach it.
Exception Handling (JVM)
Shows methods of exception handling in COBOL for JVM.
Extension Methods (JVM)
Demonstrates how to extend methods in COBOL for JVM.
IMTK - COBOL Program Tutorial
Shows how to create a service interface from a COBOL program, and then deploy it as a service.
Indexers (JVM)
Demonstrates how to use indexers in COBOL for JVM.
Iterators (JVM)
Demonstrates how to use iterators in COBOL for JVM.
JVM COBOL to Native COBOL Interop
Demonstrate how COBOL for JVM can interoperate with native COBOL.
Local Variables (JVM)
Demonstrates how to declare local variables in COBOL for JVM.
OESQL - Getting Started
Shows how to use static SQL with OpenESQL to perform various SQL operations.
OESQL - Getting Started with JDBC (JVM)
Shows how to use OpenESQL with JDBC and how to connect to a database using either Connection Strings or Data Sources.
OESQL - Behavior
Shows how to use the OpenESQL Compiler directives to assist in migrating database applications from the mainframe for offload development.
OESQL - Catalog
Shows the information about all data types supported by the data source, a list of all tables in the data dictionary, and information about the columns in the table 'orders'.
OESQL - Connect
Shows how to use static SQL with OpenESQL to perform various SQL operations.
OESQL - Dynamic
Shows how to use dynamic SQL with OpenESQL to perform various SQL operations.
OESQL - Select
Shows how to use singleton SELECT and cursor-based FETCH statements with OpenESQL.
OESQL - Whenever
Shows how to use EXEC SQL WHENEVER for error handling, and MFSQLMESSAGETEXT to retrieve error messages larger than 70 bytes.
Operator Overloading (JVM)
Demonstrates operator overloading in COBOL for JVM.
Optional Parameters (JVM)
Shows how to define methods with optional parameters and various ways to call such methods, including the use of named parameters.
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.
tictac
Demonstrates how to develop native COBOL applications.

UNIX installations have the following additional samples:

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.

Windows installations also have demonstrations of mainframe subsystem support.

Parent topic: Sample Programs
Related information
Command Line Demonstrations of COBOL for JVM


Using the Command Line Demonstrations

Restriction: This topic applies to UNIX environments only.

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: Sample Programs


Command Line Demonstrations of COBOL for JVM

Restriction: This topic applies to UNIX environments only.

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


Command Line Demonstrations of Native COBOL

Restriction: This topic applies to UNIX environments only.

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


Command Line Demonstrations of COBOL used with SQL

Restriction: This topic applies to UNIX environments only.

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


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

Restriction: This topic applies to UNIX environments only.

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


Cheat Sheets

Try the COBOL cheat sheets on the Help menu by clicking Help > Cheat Sheets > COBOL Development. Cheat sheets are like tutorials and give step-by-step instructions on how to do a task, together with brief explanations. There are cheat sheets to:

  • Choose which file types to build.
  • Show how to use the Consolidated Tracing Facility.
  • Convert Net Express projects.
  • Create a project to say "Hello COBOL World".
  • Create a remote project.
  • Debug a program.
  • Import existing COBOL files into Eclipse.
  • Work with data items.

You can also write your own cheat sheets and make these available to your users. See the Platform Plug-in Developer Guide in the Eclipse Help.

Parent topic: Welcome


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


Help on Help

The latest up-to-date Help is available on the Micro Focus SupportLine Web site. Alternatively, you can display the Help locally from the Help menu in the IDE, or from the Start menu.

COBOL Help within the IDE

Tips on getting Help on COBOL when using the IDE:

  • COBOL syntax, library routines and Compiler directives. In the COBOL editor, put the cursor anywhere within the reserved word, routine or directive, and then press F1.
  • Error messages. In the output pane, put the cursor on the error message number and press F1.
  • Tooltips. Hover over an item in the COBOL code or over a field or control, by leaving the mouse pointer on it for a moment. A brief description of it may be displayed, either beside it or at the bottom of the window.
Note: Context help in the IDE that is provided as context help files, .HLP, might not work on versions of Windows such as Vista or later. This is because .HLP files require the Windows Help Program (WinHlp32.exe) which is not available in these versions of Windows. You need to install the Windows Help Program separately - click here to download the program.

Release Notes

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

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

Readmes

This documentation includes two types of readmes:

  • 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 in the IDE

  • Starting Eclipse
  • Introduction to Eclipse
    Provides a description of the major IDE features together with an overview of the development life-cycle and some useful tips on developing applications.
  • Configuring Eclipse
  • Using Eclipse for COBOL Development
  • Creating COBOL Projects
  • Building COBOL applications
    To build an application, you need to compile its programs and link them to a run-time system. In the IDE, you use a build configuration to define how to do this.
  • Code Coverage (Native COBOL)
    Code coverage for native COBOL in Enterprise Developer integrates the Micro Focus Test Coverage facility.
  • Code Analysis
  • Debugging COBOL applications
    Your COBOL development system provides a debugging environment where the source code of each program is displayed in a separate window.
  • Code Refactoring
  • Running COBOL Applications
  • Using Eclipse for PL/I development
  • Using Enterprise Server from within the IDE
Parent topic: Micro Focus Enterprise Developer 4.0 for Eclipse


Starting Eclipse

  • To start Enterprise Developer
  • To start Enterprise Developer as an administrator
  • To start an Enterprise Developer command prompt
  • To start an Enterprise Developer command prompt as an administrator
Parent topic: Developing Applications in the IDE


To start Enterprise Developer

Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Enterprise Developer for Eclipse.
Windows 8.1
  • From the Windows Start screen, click the Enterprise Developer for Eclipse tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > Enterprise Developer for Eclipse.
Parent topic: Starting Eclipse


To start Enterprise Developer as an administrator

Depending on the files you create or edit using Enterprise Developer, you might need to start Enterprise Developer as an administrator. To do this:

This topic applies to Windows environments only.

Windows 7 and Earlier
  1. From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer .
  2. Right-click Enterprise Developer for Eclipse; then select Run as administrator from the context menu.
  3. If prompted, click Yes.
Windows 8.1
  1. From the Windows Start screen, right-click the Enterprise Developer for Eclipse tile.
  2. On the bottom of the page, click Run as administrator.
  3. If prompted, click Yes.
Windows 10 and Later
  1. From your Windows desktop, click Start > Micro Focus Enterprise Developer.
  2. Right-click Enterprise Developer for Eclipse.
  3. On the context menu, click More > Run as administrator.
Parent topic: Starting Eclipse


To start an Enterprise Developer command prompt

Restriction: This topic applies to Windows environments only.
Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt (32-bit) or Enterprise Developer Command Prompt (64-bit).
Windows 8.1
  • From the Windows Start screen, click either the Enterprise DeveloperEnterprise Server Command Prompt (32-bit) or the Enterprise Developer Command Prompt (64-bit) tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > Enterprise Developer Command Prompt (32-bit) or Enterprise Developer Command Prompt (64-bit).
Parent topic: Starting Eclipse
Related concepts
TLOG Files
Related tasks
To run the MBDT Configuration Utility from a command prompt
Related reference
mbdtconfig command
Related information
Starting an Enterprise Developer Build Tools for Windows Command Prompt


To start an Enterprise Developer command prompt as an administrator

Restriction: This topic applies to Windows environments only.

Depending on the location of files created from an Enterprise Developer command prompt, you might need to start it as an administrator. To do this:

Windows 7 and Earlier
  1. From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Tools.
  2. Depending on your operating system, right-click either Enterprise Developer Command Prompt (32-bit) or Enterprise Developer Command Prompt (64-bit); then select Run as administrator from the context menu.
  3. If prompted, click Yes.
Windows 8.1
  1. From the Windows Start screen, right-click either the Enterprise Developer Command Prompt (32-bit) or the Enterprise Developer Command Prompt (64-bit) tile.
  2. On the bottom of the page, click Run as administrator.
  3. If prompted, click Yes.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer, right-click Enterprise Developer Command Prompt (32-bit) or Enterprise Developer Command Prompt (64-bit) and click More > Run as Administrator.
Parent topic: Starting Eclipse
Related information
Starting an Enterprise Developer Build Tools for Windows Command Prompt


Introduction to Eclipse

The Eclipse Integrated Development Environment (IDE) differs from other IDEs in significant ways. This introduction, though not a complete guide, is aimed at Micro Focus users who are new to Eclipse and provides a description of the major IDE features together with an overview of the development life-cycle and some useful tips on developing applications.

Micro Focus recommends you read this document through from beginning to end. However, you can dip in and read sections that may be of interest to you.

A lot of the information in this Introduction is presented in greater detail in the rest of the section Developing Applications in the IDE.

  • Eclipse Basics
  • Advanced Details
Parent topic: Developing Applications in the IDE


Eclipse Basics

Read through the topics in this section to get familiar with the basic elements and features of the Eclipse environment. Complete this section by following the tutorial at the end to create a project and your first COBOL application.

  1. Workspaces
    A workspace can be thought of as a logical grouping of projects, settings, preferences and metadata.
  2. IDE Preferences
    Preferences is the Eclipse term for user-configurable options, and you can use them to control many aspects of the IDE behavior.
  3. Projects
    A project is a representation of the source files (with dependencies) and build commands used to create your application or program.
  4. Selecting a Project Template
  5. Remote Projects
    From your local Enterprise Developer, you can create and maintain projects that are stored on a remote AIX, HP-UX, Linux or Solaris machine.
  6. Using the Windows and Menus
    The main Eclipse window consist of number of subwindows that form the current perspective - a general name for the set of subwindows that target a particular development task.
  7. Navigation Shortcuts
    Although you can find all of the commands on the user menus and buttons, there are often ways that invoke some of the commands quicker.
  8. Creating Your First Hello COBOL World Application
  9. Creating Your First Hello PL/I World Application
Parent topic: Introduction to Eclipse


Workspaces

When you first start Eclipse, the IDE prompts you to choose a workspace directory.

A workspace can be thought of as a logical grouping of projects, settings, preferences and metadata. Much like a real desk, a workspace is a place where work is done though that does not infer any relationship between the things on the desk.

Having multiple projects in a workspace does not imply any relationship between the projects. Neither do projects have to be located under the workspace directory, although you can choose to do that.

A workspace can only be used by one instance of Eclipse at any one time but it is perfectly reasonable to run multiple instances of Eclipse each using a separate workspace.

When running multiple instances of Eclipse, you can change the title of each Eclipse window, which gives you an easy way to identify which Eclipse is using which workspace. To do this, click Window > Preferences, then click the General > Workspace tabs in the Preferences dialog box, and specify a name in the Workspace name (shown in window title) field.

To change the workspace the current instance of Eclipse is using, click File > Switch Workspace and either select one of the available workspaces from the menu, or click > Other and specify the path to a different folder you want to use.

Generally, we do not recommend that you commit workspaces into a source control system, as they contain metadata which is updated frequently.

Note: A workspace is not equivalent to a Visual Studio solution which is a container holding one or more projects that work together to create an application.
Parent topic: Eclipse Basics
Next topic: IDE Preferences


IDE Preferences

Preferences is the Eclipse term for user-configurable options, and you can use them to control many aspects of the IDE behavior. To access the IDE preferences, click Window > Preferences to start the Preferences dialog box.

Within the Preferences dialog box the various preferences are displayed in a tree of categorized pages. The pages under the Micro Focus category relate to Micro Focus functionality.

Changes made to the IDE preferences are stored in the workspace. This means that, if you switch workspaces, you might want to change the preferences again.

A number of dialog boxes that appear in the IDE have a Remember my decision check box which can be useful if you want to stop the dialog box from appearing in future. You can change these decisions using the appropriate preference page.

Parent topic: Eclipse Basics
Previous topic: Workspaces
Next topic: Projects


Projects

A project is a representation of the source files (with dependencies) and build commands used to create your application or program.

An Eclipse project consists of a directory, project settings files and at least the contents of the directory. This means that only one Eclipse project can exist in any one directory. Eclipse projects build their sources to just one form of output (such as an executable, an .exe, or a dynamically loaded library, a .dll) which you control using the project's build configurations.

Projects have a type (such as Mainframe COBOL or JVM COBOL) and you create them using a wizard for the appropriate project type. The type of the project determines how the project node is decorated (what icon is used for it) and what view it is opened in inside the main Eclipse window - for example, the COBOL Explorer view for COBOL projects or the PL/I Explorer view for PL/I projects.

Parent topic: Eclipse Basics
Previous topic: IDE Preferences
Next topic: Selecting a Project Template


Selecting a Project Template

When creating a new project, choose a template based on the type of application you want to create.

To access the available project types, click either File > New in the COBOL or the PL/I perspective, or by clicking File > New > Other and choosing one of the templates prefixed with Micro Focus.

If you are in the Team Developer perspective, click File > New > Other and choose one of the templates prefixed with Micro Focus. Alternatively, you can right-click Enterprise Development Projects in the Application Explorer view and choose from New COBOL Project or New PLI Project.

Enterprise Developer provides the following project types:

Project Type | Created Using Wizard | Project is used
COBOL | COBOL Project | To develop a COBOL application on the local machine that is compiled to native file formats (such as .int and .gnt).
COBOL JVM | COBOL JVM Project | To develop a COBOL application compiled to Java byte code.
COBOL JVM Unit Test | COBOL JVM Unit Test Project | To develop JUnit-style unit tests for JVM COBOL sources.
COBOL Remote | Remote COBOL Project Set COBOL compilation target to Native code. | To develop a COBOL application on a remote UNIX or Linux machine that is compiled to native file formats (such as .int and .gnt).
COBOL Remote JVM | Remote COBOL Project Set COBOL compilation target to JVM byte code. | To develop a COBOL application on a remote UNIX or Linux machine that is compiled to Java byte code.
COBOL Unit Test | COBOL Unit Test Project | To develop JUnit-style unit tests for native COBOL sources.
Copybook | COBOL Copybook Project | As a container for copybooks probably referenced by more than one project. This project type does not build any files itself.
Mainframe COBOL | Mainframe COBOL Project | To develop mainframe COBOL applications including support for mainframe-related file types on the local machine.
Mainframe PL/I | Mainframe PL/I Project | To develop a mainframe PL/I application that includes support for mainframe-related file types on the local machine.
PL/I | PL/I Project | To develop a PL/I application on the local machine.
Remote Copybook project | Remote COBOL Copybook Project | As a container on a remote UNIX or Linux machine for copybooks probably referenced by more than one project.
Remote Mainframe COBOL | Remote Mainframe COBOL Project | To develop mainframe COBOL applications that include support for mainframe-related file types on a remote UNIX or Linux machine.
Parent topic: Eclipse Basics
Previous topic: Projects
Next topic: Remote Projects
Related concepts
Unit Testing in the IDE


Remote Projects

Remote projects enable you to develop AIX, HP-UX, Linux or Solaris COBOL and PL/I applications using Eclipse running on Windows or a different Linux machine. The remote machine must have Micro Focus Enterprise Developer UNIX Components installed.

Parent topic: Eclipse Basics
Previous topic: Selecting a Project Template
Next topic: Using the Windows and Menus
Related concepts
Creating Remote Projects


Using the Windows and Menus

The main Eclipse window consist of number of subwindows that form the current perspective - a general name for the set of subwindows that target a particular development task.
  • The Eclipse Welcome Page
  • Views
  • Perspectives
  • Menus and Toolbars
  • Controlling Views and Editors
Parent topic: Eclipse Basics
Previous topic: Remote Projects
Next topic: Navigation Shortcuts


The Eclipse Welcome Page

When you first open Eclipse there is a Welcome page that contains a number of useful links to information sources. Follow the links to the information you are interested in, or click a link to open to the perspective that is most suitable for you.

If you do not want to do either of these, close the Welcome page (by clicking the Close button in the toolbar of the Welcome page, Welcome page toolbar). You can always display the Welcome page later by clicking Help > Welcome.

Parent topic: Using the Windows and Menus
Related information
Views
Perspectives
Menus and Toolbars
Controlling Views and Editors


Views

The Eclipse IDE provides a variety of subwindows called views that provide specific functionality. Default views for Eclipse are:

  • Application Explorer view - shows a hierarchical view of the projects and files in your workspace.
  • Navigator view - provides an exact representation of the project folder and files as on disk. Not used in COBOL
  • Project Explorer view - shows a hierarchical view of the files in your projects
  • Console view - show the result of a process such as during building or debugging an application.
  • Problems view - shows errors and warnings from the projects in your workspace.

Enterprise Developer provides a number of COBOL- and PL/I-specific views and windows that appear by default in the Team Developer, COBOL or the PL/I perspectives.

Note: The following views have been renamed in Enterprise Developer 3.0:
Old View Name | New View Name
Team Developer Tree view | Application Explorer view
Team Developer Table view | Table Results view
Team Developer Filter view | Filter Definitions view
Team Developer Job view | Jobs view
Team Developer Error List | Error Feedback view
Team Developer File Mappings view | File Mapping view
  • COBOL Views
    The following shows examples of views that are available by default for the COBOL perspective.
  • PL/I Views
    The following shows examples of views that are available by default for the PL/I perspective.
  • Team Perspective Views
    The following shows examples of views that are available by default for the Team Developer perspective.
Parent topic: Using the Windows and Menus
Related information
The Eclipse Welcome Page
Perspectives
Menus and Toolbars
Controlling Views and Editors


COBOL Views

The following shows examples of views that are available by default for the COBOL perspective.

COBOL Editor

The COBOL editor provides numerous features to help you write your code such as:

  • Background parsing underlines errors as you type, while hovering over the item gives information on the error.

  • Content Assist provides context sensitive proposals for typing COBOL code in the editor.
    Showing Content Assist proposals
  • You can search for references to any variable in your code. In the Outline view, right-click the variable, and then click Reference.

  • The Outline view shows the structure of the file you are editing. This view enables you to navigate around the file. For example, if you want to go to a particular COBOL section or a data item in the Editor view, just click on it in the Outline view.

  • In the Outline and Program Outline views you can open the Type Hierarchy and Call Hierarchy view for JVM COBOL. Right-click the item and then click Open Type Hierarchy or Open Call Hierarchy as required.
  • You can use block selection to move blocks of text. Press Alt+Shift+A to switch to block selection mode, then click and drag to select.

  • By using the COBOL Copy View you can view copybooks inline, enabling you to see the effects of COPY … REPLACING, as in the following example. You can open COBOL Copy View when working in the COBOL editor by pressing F4.

COBOL Explorer

The COBOL Explorer view includes the following features to help you manage your projects:
  • For COBOL Project, Remote Project, and Mainframe COBOL Project types, COBOL Explorer adds category folders that automatically group together your project's COBOL programs, copybooks, and output files. (These folders are not physical folders on the disk, but effectively headings for certain file types.)
  • You can filter the tree view by typing strings in the COBOL Explorer search filter. Wildcard characters can be used in the search strings. The question mark character (?) matches a single character. An asterisk (*) matches a number of characters. The search field can store the previous 10 search strings.
  • By default, the COBOL Explorer displays COBOL JVM projects in package presentation. This is where COBOL JVM is organized in the same way as a Java package. So that Java classes, interfaces, and types are displayed in their namespaces. For example, the package com.microfocus.example is displayed as:
    COBOL JVM PRoject Presentation Package

    To change the presentation to display COBOL categories, click [image] (View Menu), and then click COBOL JVM Project Presentation > COBOL Categories. The same class file is now displayed as:
    COBOL JVM Project Presentation COBOL Categories

  • You can open the Call Hierarchy view for JVM COBOL projects, folders, programs. To open the view, right-click the item in the COBOL Explorer, and then click Open Call Hierarchy. Alternatively, press Ctrl+Alt+H. The view enables you to see the callers and callees hierarchy for the selected JVM COBOL member.
  • You can open the Type Hierarchy view for JVM COBOL type. To open the view, right-click the type in the COBOL Explorer, and then click Open Type Hierarchy. Alternatively, press Alt+Shift+H. The view enables you to see classes, subclasses and members and their supertypes, or their subtypes.
  • To simplify navigation around your project, you can hide some files that are part of the project, such as the .cobolBuild, .cobolProj, and .project files, and the .settings folder and its content in JVM projects. In the COBOL Explorer, click [image] and then click Customize View and choose from the options.
    Filters
    Choose types of content to hide in COBOL Explorer:
    Option | Description
    .*resources | Any files of type .* such as .cobolBuild, .cobolProj.
    COBOL Copybook projects | Any COBOL Copybook projects.
    COBOL JVM output folders
    Closed projects | Resources in closed projects never display, but you can choose to hide all closed project icons [image] too.
    Derived COBOL programs | Programs that have been generated by COBOL preprocessors.
    Empty categories | COBOL Projects that do not contain COBOL program or copybook files.
    Empty folders inside categories | Folders mapped to the COBOL Programs and Copybooks that contain no COBOL program or copybook files.
    Empty folders outside categories | Folders not mapped to the COBOL Programs and Copybooks that contain no COBOL program or copybook files.
    Empty packages | All empty packages are removed from the view.
    Empty parent packages | All empty parent packages are removed from the view.
    Internal Micro Focus project | Internal Micro Focus projects.
    Internal TD Project | Internal Team Developer projects.
    Non-COBOL projects | Projects of types other than those under Micro Focus COBOL - for example AspectJ, Plug-in, or Update-site projects.
    Non-Micro Focus projects | Non-Micro Focus projects.
    Non-public members | All non-public members are removed from the view.
    PL/I Include projects | PL/I include projects.
    RSE Internal projects | Projects generated by the RSE plug-in.
    Synthetic members | All synthetic members, such as $0, are removed from the view.
    Content
    Choose types of content to show in COBOL Explorer:
    Option | Description
    Working Sets | Working sets are subsets of workspace resources you can choose to show or perform options on. To define a working set, click Project > Build Working Set > Select Working Set > New.
    COBOL Elements Non-resource types that are COBOL-specific:
    1. x
    2. Category folders, including those for COBOL programs and copybooks, and BMS macro source files
    3. Icons for the different types of COBOL files.
    4. Overlays for build errors and warnings
    5. Some context menu items
    COBOL JVM Package Presentation | By default, this option is checked. This option, when combined with the View Menu > COBOL JVM Project Presentation > Package, displays COBOL JVM projects in package presentation view. If this is not checked then the content of the COBOL JVM project is displayed as they are in the file system.
    Resources | COBOL projects, COBOL programs and copybooks. Has effect only if the COBOL Elements option is unchecked.
  • COBOL Explorer helps you fix problems by using icons to identify files and containers that cause build errors and warnings.
    • A file that generates a warning, and any containing folders and categories, is marked with a yellow warning sign. For example:

    • A file that causes an error, and any containing folders and categories, is marked with a cross. In this example the icons indicate the most severe problem is the error caused by Program4.cbl, and the folders are marked with error icons despite Program5.cbl generating a warning:

    • A project that suffers from a dependency error is marked with a red exclamation point; its contents remain unmarked. In this example the project depends on another project that is closed, causing a build path problem:

Parent topic: Views


PL/I Views

The following shows examples of views that are available by default for the PL/I perspective.

PL/I Editor

The PL/I editor provides numerous features to help you write your code such as:

  • Background parsing underlines errors as you type, while hovering over the item gives information on the error.

  • Content Assist provides context sensitive proposals for typing PL/I code in the editor.

  • You can search for references to any variable in your code.

  • The Outline view shows the structure of the file you are editing. This view enables you to navigate around the file. For example, if you want to go to a particular PL/I section or a data item in the Editor view, just click on it in the Outline view.

  • You can use block selection to move blocks of text. Press Alt+Shift+A to switch to block selection mode, then click and drag to select.

PL/I Explorer

The PL/I Explorer view includes the following features to help you manage your projects:
  • For PL/I Project, Remote PL/I Project, and Mainframe PL/I Project types, PL/I Explorer adds category folders that automatically group together your project's PL/I programs and output files. These folders are not physical folders on the disk, but effectively headings for certain file types.
  • You can filter the tree view by typing strings in the PL/I Explorer search filter. Wildcard characters can be used in the search strings. The question mark character (?) matches a single character. An asterisk (*) matches a number of characters. The search field can store the previous 10 search strings.
  • To simplify navigation around your project, you can hide some files that are part of the project, such as the .pliBuild, .pliProj, and .project files. In the PL/I Explorer, click [image] and then click Customize View and choose from the options.
    Filters
    Choose types of content to hide in the PL/I Explorer:
    Option | Description
    .*resources | Any files of type .* such as .pliBuild, .pliProj.
    COBOL Copybook projects | Any COBOL Copybook projects.
    Closed projects | Resources in closed projects never display, you can hide all closed project icons [image] too.
    Derived COBOL programs | Programs that have been generated by COBOL preprocessors.
    Empty categories | PL/I Projects that do not contain PL/I program files.
    Empty folders inside categories | Folders mapped to PL/I Programs that contain no PL/I program files.
    Empty folders outside categories | Folders not mapped to the PL/I Programs that contain no PL/I program files.
    Internal TD Project | Internal Team Developer projects.
    Non-Micro Focus projects | Non-Micro Focus projects.
    Non-PL/I projects | Projects of types other than those under Micro Focus PL/I - for example AspectJ, Plug-in, or Update-site projects.
    RSE Internal Projects | Projects generated by the RSE plug-in.
    Content
    Choose types of content to show in PL/I Explorer:
    Option | Description
    Working Sets | Working sets are subsets of workspace resources you can choose to show or perform options on. To define a working set, click Project > Build Working Set > Select Working Set > New.
    COBOL Elements Non-resource types that are PL/I-specific:
    1. x
    2. Category folders, including those for PL/I programs, and BMS macro source files.
    3. Icons for the different types of PL/I files.
    4. Overlays for build errors and warnings.
    5. Some context menu items.
    Resources | PL/I projects, and PL/I programs. Has effect only if the COBOL Elements option is unchecked.
  • PL/I Explorer helps you fix problems by using icons to identify files and containers that cause build errors and warnings.
    • A file that generates a warning, and any containing folders and categories, is marked with a yellow warning sign. For example:

    • A file that causes an error, and any containing folders and categories, is marked with a cross. In this example the icons indicates a problem caused by opdemo.pli, and the folders are marked with error icons despite opdemo2.pli generating a warning:

    • A project that suffers from a dependency error is marked with a red exclamation point; its contents remain unmarked. In this example the project depends on another project that is closed, causing a build path problem:

Parent topic: Views


Team Perspective Views

The following shows examples of views that are available by default for the Team Developer perspective.

COBOL Editor

The COBOL editor provides numerous features to help you write your code such as:

  • Background parsing underlines errors as you type, while hovering over the item gives information on the error.

  • Content Assist provides context sensitive proposals for typing COBOL code in the editor.
    Showing Content Assist proposals
  • You can search for references to any variable in your code.

  • The Outline view shows the structure of the file you are editing. This view enables you to navigate around the file. For example, if you want to go to a particular COBOL section or a data item in the Editor view, just click on it in the Outline view.

  • You can use block selection to move blocks of text. Press Alt+Shift+A to switch to block selection mode, then click and drag to select.

  • By using the COBOL Copy View you can view copybooks inline, enabling you to see the effects of COPY … REPLACING, as in the following example. You can open COBOL Copy View when working in the COBOL editor by pressing F4.

Application Explorer view

The Application Explorer view includes the following features to help you manage your projects:
  • To simplify navigation around your project, you can hide some files that are part of the project, such as the .cobolBuild, .cobolProj, and .project files, and the .settings folder and its content in JVM projects. In the COBOL Explorer, click [image] and then click Customize View and choose from the options.
    Filters
    Choose types of content to hide in Application Explorer view:
    Option | Description
    .*resources | Any files of type .* such as .cobolBuild, .cobolProj.
    COBOL Copybook projects | Any COBOL Copybook projects.
    Closed projects | Resources in closed projects never display, but you can choose to hide all closed project icons [image] too.
    Derived COBOL programs | Programs that have been generated by COBOL preprocessors.
    Internal Micro Focus project | Internal Micro Focus projects
    Non-Micro Focus projects | Non-Micro Focus projects.
    RSE Internal projects | Projects generated by the RSE plug-in.
    Content
    Choose types of content to show in Application Explorer view:
    Option | Description
    AWM Tree Content | AWM Tree Content
  • Application Explorer helps you fix problems by using icons to identify files and containers that cause build errors and warnings.
    • A file that generates a warning, and any containing folders, is marked with a yellow warning sign. For example:

    • A file that causes an error, and any containing folders, is marked with a cross. In this example the icons indicate the most severe problem is the error caused by Program4.cbl, and the folders are marked with error icons despite Program5.cbl generating a warning:

    • A project that suffers from a dependency error is marked with a red exclamation point; its contents remain unmarked. In this example the project depends on another project that is closed, causing a build path problem:

Parent topic: Views


Perspectives

A perspective is a set of subwindows (most of which are views) that are focused upon a set of tasks, such as COBOL development or debugging. Each perspective comes with a default set of views in a default layout. Any changes that you make to a perspective, such as adding or removing views or changing the layout of the views, are persisted between Eclipse sessions.

The currently selected, and other active perspectives, are shown at the top right corner of your Eclipse window. Clicking a perspective name switches to that perspective. This is quick and easy, and means that you do not need to have space taken on screen by irrelevant views at any time in the development process.

Clicking the Open Perspective button (the icon with the twinkle, Open Perspective) opens a dialog box that enables you to choose from other perspectives that you might want to open.

You can always return a perspective to its default state by right-clicking the perspective button in the right top corner of the Eclipse IDE and clicking Reset. Note that this operation cannot be undone.

If you change the layout of any of the subwindows or the content of a perspectives, the changes are retained even when you switch to another perspective, or restart eclipse. The changes will only be lost when the perspective is reset or closed.

Parent topic: Using the Windows and Menus
Related information
The Eclipse Welcome Page
Views
Menus and Toolbars
Controlling Views and Editors


Menus and Toolbars

Across the top of Eclipse there is a menu bar. The contents of this bar, and the contents of the menus or enablement of menu items, can change according to various criteria, such as the perspective, which editor is open, or what the currently selected item is.

Menu bar in Eclipse

If a menu item has a keyboard shortcut, this is shown against that menu item. You can see all the key bindings and change them using the General > Keys page in the IDE preferences (click Window > Preferences).

Below the menu bar is a toolbar of icons allowing quick access to a number of functions. Hovering over an icon displays a tooltip that describes the functions. If the function has a keyboard shortcut, that is also included in the tooltip.

Toolbar in Eclipse

If an icon includes a downward-pointing triangle on its right-hand side, click the triangle to show a drop-down menu of functions to choose from.

You can see that groups of icons are separated by a vertical line of gray dots. Grabbing and dragging a vertical line moves that group of icons.

The toolbar contents and icon enablement also changes depending on criteria such as the current perspective, which editor is open, or what the currently selected item is.

In many places context menus are available. Right-click an item inside the IDE to see its context menu.

Parent topic: Using the Windows and Menus
Related information
The Eclipse Welcome Page
Views
Perspectives
Controlling Views and Editors


Controlling Views and Editors

Sometimes, you might want to see only the contents of a particular subwindow, such as the editor subwindow. If you double-click the tab that you are interested in, the tab is maximized within the Eclipse window. The rest of the views that were open are minimized and an icon for each one of them appears on a sidebar in the Eclipse window.

You can make other views visible by clicking an icon in one of the sidebars.

To return to normal, double-click the tab again. You can do this with any view within Eclipse.

To change the relative size of views and editors within Eclipse, move the mouse to the boundary between them, then grab and drag the boundary.

If there is more than one view in an area of the screen, multiple tabs are shown.

You can move a view from one area to another by grabbing and dragging its tab. As you move it around you see visual clues to show how it would be located. What is not immediately obvious is that you can drop it outside the main Eclipse window so that it becomes a freestanding window. To undo that, just grab and drag the tab back to the main window.

Many views have a toolbar across the top, some with icon buttons, and some with a downward-pointing triangle which gives access to a menu. On some, such as COBOL Explorer and Application Explorer view, you can use this to set filters that change whether certain types of item are shown in the view. So, if your view is getting a bit crowded, you can explore the filters by clicking Customize View.

Customizations and filters

There are many more views available in addition to those that are shown by default. To see all of the views that are available, click Window > Show View > Other. Alternatively, click the Add View button, Add view, which by default is in the bottom left corner of Eclipse.

Parent topic: Using the Windows and Menus
Related information
The Eclipse Welcome Page
Views
Perspectives
Menus and Toolbars


Navigation Shortcuts

Although you can find all of the commands on the user menus and buttons, there are often ways that invoke some of the commands quicker.

Opening Files

Double-clicking a file in the COBOL Explorer causes the file to be opened with the appropriate editor for that file type.

If there is a choice of what editors you can use, the Open With context menu item on the file to select a different editor and Eclipse will remember this next time you open the same file.

Resources

Press Ctrl+Shift+R to open the Open Resource dialog box. Type the name of a resource into the field at the top of the dialog box to show matching possibilities. Select the resource that you are interested in, click Open, and the selected resource opens.

Note that you do not need to specify the whole name of the resource, as resources are dynamically matched as you type. Also, if your filenames are mixed case, you can type just the uppercase characters (optionally followed by just some of the immediately following lower case characters) and the resource will be found.

Searches

Options on the Search menu provide a number of different forms of searches, whose results are shown in a search results view.

If you are sorting through many results you might find it helpful to use the Remove Selected Matches context menu item - select one or more items in the Search view and select the command from the context menu. This does not remove any files or lines of code, but just removes the matches from the search results.

Type Search

If you are working with Java classes or COBOL classes compiled to JVM you might find the Type Search facility helpful. You can access this facility using the Ctrl+Shift+T shortcut, and it operates in the same manner as the Open Resource dialog box described above.

Go to Line

If you want to go to a particular line of code, either type Ctrl+L or double-click the line number in the status bar at the bottom, then enter the line number.

Go to Line

If you have an error in the Problems view, double-clicking that takes you directly to the line of code. Similarly, double-clicking on a search result takes you to the line concerned.

Parent topic: Eclipse Basics
Previous topic: Using the Windows and Menus
Next topic: Creating Your First Hello COBOL World Application


Creating Your First Hello COBOL World Application

Now that we've covered the basic features of the Eclipse IDE, it is time for you to create your first simple Hello COBOL World application:

Create a project

  1. Start Enterprise Developer.

    By default, when you start Eclipse, it displays the Eclipse Launcher dialog box prompting you to specify a path for the Eclipse workspace. Specify a path and click Launch.

    If this is the first time you start Eclipse, you now see the Eclipse Welcome page. See The Eclipse Welcome Page in this Introduction.

    Click Open COBOL Perspective as this perspective is the most suitable one for COBOL development.

  2. Select File > New > COBOL Project.
  3. Specify a name for your project such as HelloCOBOLWorld and click Finish.

    By default, the project will be created in the workspace that you selected when you started the Eclipse session.

Add a source file

You need to create a program in your project to hold the COBOL source code:

  1. Select your project in the COBOL Explorer view and click File > New > COBOL Program.

    The New COBOL Program wizard is displayed.

  2. In the New file name field type helloworld.cbl.
  3. Click Finish.

    This adds a template COBOL program to your project and opens it in the editor.

  4. Copy and paste the following COBOL code into the editor, overwriting the existing text:
           program-id. helloworld as "helloworld".

       environment division.
       configuration section.

       data division.
       working-storage section.

       procedure division.

           display 'Hello COBOL World!'.

           goback.

       end program helloworld.
  5. Click File > Save.

    By default, Eclipse builds your project automatically. If you haven't configured Eclipse to do this, you can build a project at any time by clicking Project > Build Project.

    The progress of the project build is displayed in the Console view.

    When your project has been built, a folder called New_Configuration.bin is created in your project. Expand the folder in the COBOL Explorer view to see the executable and some .obj (Windows) or .o (UNIX) files.

You can now run the application.

Run Hello COBOL world

Applications you create in Eclipse need a launch configuration to execute. You are going to create a run configuration for the Hello COBOL world application as follows:

  1. Select your project in the COBOL Explorer view and from the main menu click Run > Run Configurations.
  2. Create a new launch configuration. You can do this in two ways:
    • Double-click the COBOL Application tree item.
    • Click COBOL Application tree item, and then click the New launch configuration icon.

    A default COBOL Launch Configuration is created in the wizard showing HelloCOBOLWorld as the project to run and New_Configuration.bin/HelloCOBOLWorld.exe (Windows) or New_Configuration.bin/HelloCOBOLWorld (UNIX) as the main program to run.

  3. Click Run.

    This opens a console window with Hello COBOL World! printed in it.

  4. Press any key to close the console.

Preserve this project because you are going to use it again for a different demonstration included in this Introduction.

What Next?

Continue with the next section, Advanced Details, which includes information about configuring the IDE and your projects, and on editing, building, running and debugging applications in Eclipse.

Parent topic: Eclipse Basics
Previous topic: Navigation Shortcuts
Next topic: Creating Your First Hello PL/I World Application
Related concepts
Advanced Details
Configuring the Hello COBOL World Application
Debug the Hello COBOL World Application
Related reference
The Eclipse Welcome Page


Advanced Details

This section provides information about the different types of applications you can create, how to configure your projects, edit, build and debug applications and how to extend Eclipse with plug-ins.

  1. The Eclipse Resource System
  2. Development Life Cycle
  3. Additional Eclipse Functionality
Parent topic: Introduction to Eclipse


The Eclipse Resource System

Views within Eclipse that show the workspace and the existing projects such as COBOL Explorer present what looks and feels like a view of the file system. It is important to note that it is not a direct representation or mapping of the file system. Some items are not actually present on a file system, and some may be on another system, or in a place that is outside the project.

  • Resources
    Eclipse maintains its own representation of the file system within the workspace metadata.
  • Linked Resources
    You need to use linked resources to make your project use files or directories that are not located under the project directory.
  • Configuring Projects
    The Eclipse IDE offers various settings to help you configure your projects, specify other projects your application depends on, the way your applications build, or include the projects in a Working Set.
  • Configuring the Hello COBOL World Application
Parent topic: Advanced Details
Next topic: Development Life Cycle


Resources

Eclipse maintains its own representation of the file system within the workspace metadata.

Changes made to the file system outside of Eclipse (such as by copying files or updating source code using a source control system) might not be automatically detected by Eclipse so newly-copied files might not appear in a project. To synchronize Eclipse’s view of the file system with the actual file system, click File > Refresh or right-click the project and click Refresh on the context menu.

Parent topic: The Eclipse Resource System


Linked Resources

You need to use linked resources to make your project use files or directories that are not located under the project directory.

To add a linked folder to your project, click File > New > Folder to display the New Folder dialog box. Click Advanced, select Link to alternate location (Linked Folder), and then navigate to the folder that you want to link to.

Here are some examples of when you need to use linked resources:

Copybooks that are not stored in the project

You must use linked folders to access COBOL copybooks outside the project rather than individual linked files.

Existing Source Structures

If you have an existing structure of sources which does not match the Eclipse model of one project per directory, you might find that linked resources are the best solution.

Linked resources enable you to use the sources without having to move them or co-locate them with the project files. You can even set the output folder to be a linked folder, so that your build artefacts could be located somewhere outside the project.

Using linked resources with project or workspace variables

You can specify the location as an absolute path, but this might not be convenient if multiple users on separate machines work on the same project shared though a source control system. In such cases, it is helpful to configure project or workspace variables.

For example, consider the following file system:

/root-folder
         /checkout-folder/
                   /shared_files
                   /project

Where the folders shared_files and project contain the sources for your application.

Different users could checkout the sources (shared_files and project) under a different directory structure on their local machines. This means if the project itself needs to make use of the sources in the shared_files folder, you could configure a linked folder such that the alternate location is a new variable whose value is ${PROJECT_LOC}/../shared_files. To add the variable, on the New Folder dialog box, click Advanced and then the click Variables.

Parent topic: The Eclipse Resource System


Configuring Projects

The default IDE and project settings might not always be the most appropriate for your projects. You might need to manually configure your projects in order to specify things such as:

  • how the projects is built - for example, what settings are to be used if building for a debug or a release build
  • the build precedence and which files are built
  • whether your project depends on other projects in the workspace
  • which folders the project should check for copybooks
  • whether newly-added folders are searched for copybooks

Read through the topics in this section to learn more about the configuration settings. After that, practice what you've learned with the tutorial that follows, Configuring the Hello COBOL World Application.

  • Properties
  • Project Build Path
  • Build Precedence
  • Inter-Project Dependencies
  • Dependency Paths
  • Including Files and Folders
  • Working Sets
Parent topic: The Eclipse Resource System


Properties

Use project properties to define build precedence, copybook paths, run-time configurations and more. Build configurations determine how a project is built. Within the configuration interface, you can, for example, set target files, and define any pre and post build events.

Project Properties

To open the project properties page, right-click the project and click Properties on the context menu.

Project properties are presented as a tree of categorized pages. All the properties introduced by Micro Focus' products are under the Micro Focus node. The exact list of property pages varies with the type of the project. In general though, any language-specific pages are at the Project Settings level, but also under the Build Configurations level.

Build Configuration properties

Typical build configurations are Debug and Release, where only a few settings are different, but most language settings are inherited from the project level. it is possible to override project level settings at both the build configuration level (click Micro Focus > Build Configurations in the project's properties), and at the file level.

File properties

Generally, files inherit the properties specified at project or build configuration level. You can specify some individual file properties and, in most cases, these override the properties set for the project or the build configuration.

Parent topic: Configuring Projects
Related information
Project Build Path
Build Precedence
Inter-Project Dependencies
Dependency Paths
Including Files and Folders
Working Sets


Project Build Path

The Build Path page in the project’s properties (click Micro Focus > Build Path) configures which files are built and where the Compilers searches for dependent files such as COBOL copybooks. The Build Path page consists of several tabs which each control a different aspect of behavior.

Parent topic: Configuring Projects
Related information
Properties
Build Precedence
Inter-Project Dependencies
Dependency Paths
Including Files and Folders
Working Sets


Build Precedence

The Build Precedence tab in the project’s properties (click Micro Focus > Build Path) controls which folders contain main source files that should be compiled.

If more than one folder in the project contains a source file with the same name, the first one in the Build Precedence order is compiled. The order is controlled using this tab.

Parent topic: Configuring Projects
Related information
Properties
Project Build Path
Inter-Project Dependencies
Dependency Paths
Including Files and Folders
Working Sets


Inter-Project Dependencies

Having more than one project in a workspace does not imply any dependence between the projects.

Dependencies must be configured using the Projects tab in the project’s properties (click Micro Focus > Build Path).

Once a dependency has been set up, you can use the Dependency Paths tab to control the source include path and where in the search path order the folders of the dependent project should be included.

The build output directories of dependent projects are automatically added to the executable search path when debugging COBOL and PL/I applications.

Parent topic: Configuring Projects
Related information
Properties
Project Build Path
Build Precedence
Dependency Paths
Including Files and Folders
Working Sets


Dependency Paths

The compiler searches for dependent files such as COBOL copybooks in the folders defined on the Dependency Paths tab of the Build Path page in the project’s properties (click Micro Focus > Build Path in the project’s properties). This tab enables you to include specific folders and also to control the search order.

If you have imported copybooks using a virtual folder in your project, you need to add them to the project's dependencies. To do this navigate to Micro Focus > Build Path in the project's properties then on the Dependency Paths tab check the copybook paths that correspond to the folders that include the imported copybooks, and then click OK.

To add dependency paths

You can specify folders outside your project or at a remote location. To add a new path:

  1. Click Add.

    This opens the Add File System Directory dialog box.

  2. In the Directory field, type the path to the folder required. Alternatively, you can click Browse to open the Browse For Folder dialog box.
    Note: For a network file system such as NFS or Samba, the Directory value should be the UNIX or Linux representation of the path. For example, a location of X:NFS-mounted-drive location\project name can be represented by a remote location of /home/users/my-folder.
    • If you want to search subfolders as part of the dependency path, click Include subfolders.
  3. Click Finish.
Note: Paths are specified as absolute paths, so if you share projects between users you need to ensure that the same path structure is used on each users's computer.
Parent topic: Configuring Projects
Related information
Properties
Project Build Path
Build Precedence
Inter-Project Dependencies
Including Files and Folders
Working Sets


Including Files and Folders

All files under the project folder are automatically regarded as part of the project, which is in contrast to how older Micro Focus products worked. However, unless turned on in the IDE preferences (in Window > Preferences > Micro Focus Builder and see the Automatically add new directories to dependency paths), newly-added folders are not automatically added to the Dependency Paths search path.

Parent topic: Configuring Projects
Related information
Properties
Project Build Path
Build Precedence
Inter-Project Dependencies
Dependency Paths
Working Sets


Working Sets

If you have many projects in a workspace but only work on a few at a time, you might want to explore the Working Sets feature to control the visibility of projects. You can configure one or more working sets and quickly switch between them.

To do this, click the downward-pointing triangle in the toolbar of the COBOL Explorer, and click Select Working Set. Click New, select Resource as the Working set type and specify which projects and files should be part of it.

Once you have created a working set, it appears on the menu displayed by clicking the downward-pointing triangle in the toolbar of the COBOL Explorer view, as does Deselect Working Set (which takes you back to the default view of the workspace).

When you are have enabled a working set, Eclipse performs a full build of the projects that are part of that working set or have a file that is part of the working set.

Parent topic: Configuring Projects
Related information
Properties
Project Build Path
Build Precedence
Inter-Project Dependencies
Dependency Paths
Including Files and Folders


Configuring the Hello COBOL World Application

After taking a look at how Eclipse uses resources and the configuration options available in the IDE, you are going to see how to configure a project to locate copybooks that are not in the project directory. COBOL applications often consist of COBOL source files and copybooks that are not necessarily in the same location as the source files.

You are going to modify and configure the Hello COBOL World application which you created as part of the Eclipse Basic section to use a copybook which is part of another project. This is what you are going to do as part of this tutorial:

  1. Create a COBOL Copybook project in the same workspace with a single copybook.
  2. Move a part of the code of the helloworld program from your HelloCOBOLWorld project to the copybook in the copybook project.
  3. Replace the original code in helloworld with a copy statement.
  4. Use project references and define a project dependency to the copybook project to resolve the build issues that appear in HelloCOBOLWorld after you've modified the project.

Create a copybook project

  1. Open Enterprise Developer starting at the workspace in which you created your HelloCOBOLWorld project.
  2. Click File > New > COBOL Copybook Project.
  3. Specify a name for your project such as CopybookProj and click Finish.

    This creates the CopybookProj project in the same workspace and displays it in COBOL Explorer alongside the HelloCOBOLWorld project.

Add a source file

You need to create a program in your project to hold the COBOL source code:

  1. Right-click CopybookProj in COBOL Explorer and click File > New > COBOL Copybook.

    This starts the New COBOL Copybook wizard.

  2. Specify Hello.cpy as the file name and click Finish.

    This adds the copybook file to the project and opens it in the editor. Copybooks do not compile so the COBOL Copybook project type is not configured to build.

    You are now going to add some code to the file from the HelloCOBOLWorld project.

  3. Expand HelloCOBOLWorld in COBOL Explorer view and double-click helloworld.cbl to open it in the editor.
  4. Copy the following line from the file:
               display 'Hello COBOL World!'.
  5. Paste the code in the Hello.cpy.
  6. Back in helloworld.cbl, replace the line that you just copied with a COPY statement:
               COPY Hello.cpy.
  7. Save your changes.

    This starts a build that no longer compiles cleanly. There are some errors reported in the Output view and some error markers are added to the project in COBOL Explorer as well as in the editor.

    In situations such as this, you need to check all of the error messages Eclipse reports. Then, you need to try and eliminate the causes for them one by one until the project compiles cleanly again.

  8. Check the Problems view and expand the Errors list to see exactly what the error messages are.

    Alternatively, hover the error marker (or any of the error markers) in the editor and see the error message in a tooltip. The error that is reported is that there is an unknown copybook.

  9. Click the error message in Problems view and press F1 to search the product help for more details.

    This opens the Help view with the topic that corresponds to the error message. The reason for this problem is that Hello.cpy is unknown to the HelloCOBOLWorld project.

Create a project dependency

In order for HelloCOBOLWorld to recognize the copybook file, the project needs to have a dependency on the copybook project. Here's how you define the dependency:

  1. In COBOL Explorer, right-click HelloCOBOLWorld and click Properties.
  2. Expand Micro Focus and click Build Path.

    You can click the tabs in this pane to see what settings you can specify on these pages.

  3. Click the Projects tab.

    This is the tab where you add other projects your project depends on.

  4. Click Add and in the dialog box that starts check CopybookProj, then click OK.
  5. Click the Dependency Paths tab and ensure that the copybook path for CopybookProj is checked.
  6. Click OK to create the dependency.

    This triggers a build of HelloCOBOLWorld and, because the project now locates the copybook, the build completes without any errors.

Preserve these projects because you are going to use them for a demonstration of how to debug an application.

What Next?

Continue with the next section in this introduction to learn about what the development life cycle using Eclipse is.

Parent topic: The Eclipse Resource System
Related concepts
Creating Your First Hello COBOL World Application
Debug the Hello COBOL World Application
Related reference
Development Life Cycle


Development Life Cycle

The development cycle within Eclipse involves the following:

  • Creating and configuring a project for your source code
  • Building the application
  • Running the application

This section explores the IDE features that help you do this.

  • Adding Projects to Your Workspace
  • Adding Existing Source Files into a Project
  • Specifying Compiler Directives and Project Settings
  • Editing
  • Building
  • Running and Debugging
  • Debug the Hello COBOL World Application
  • Debug the Hello PL/I World Application
Parent topic: Advanced Details
Previous topic: The Eclipse Resource System
Next topic: Additional Eclipse Functionality


Adding Projects to Your Workspace

There are a number of ways to add projects to your workspace. For example:

  • Import an existing project.

    To do this, click File > Import, expand General and click Existing Projects into Workspace. Follow the wizard instructions to import the project.

  • Create a new project using one of the wizards described in the topic Project Types.
  • Convert an existing Net Express project.

    To do this, click File > Import, expand Micro Focus and click Convert NetExpress Projects. This reads a Net Express project file and creates one or more new native COBOL projects with the same settings, referencing the existing source files.

  • Create a remote COBOL project based on an existing local COBOL project.

    To do this, click File > Import, expand Micro Focus and click Convert Local Micro Focus Projects to Remote Projects. The new remote COBOL project created this way has the same settings as the local project, and the source is also copied from the local to the remote machine.

  • Import an existing remote COBOL project.

    To do this, click File > Import, expand Micro Focus and click Remote COBOL Projects.

Parent topic: Development Life Cycle


Adding Existing Source Files into a Project

You can add source into a project in any of the following ways:

  • Create new source files using the appropriate wizard - right-click your project in Application Explorer view, and click New > file-type.
  • Import the source code - click File > Import, expand General and click File System to import a directory and its contents into a project.
  • If a project is created in a directory that contains source files, they automatically become part of the project.
  • Drag and drop the files inside COBOL Explorer or Application Explorer view and onto your project, either from another project or the file system.
  • Copy and paste the files inside COBOL Explorer or Application Explorer view and onto your project, either from another project or the file system.
Parent topic: Development Life Cycle


Specifying Compiler Directives and Project Settings

You use a project's properties, the project build configuration properties or a file's properties to control the build behavior of projects. You access these by choosing Properties on the context menu for projects, folders and files. This is how setting these properties works:

  • In general, you need to set Compiler directives and settings that always apply at the project level.
  • Build configurations should be used to override the project settings with settings that are relevant only to a particular build configuration.
  • File-level settings override the other settings set at a project or build configuration level.

You can set SQL and CICS preprocessor directives at the project level, even when the project settings are not configured to run the preprocessors. The use of the preprocessors can then be turned on at the file level, which inherits the project level preprocessor directives. This enables you to use the project level as a template for file-level settings.

When COBOL sources are copied into a project from outside the workspace, by default, a process known as directives determination is performed automatically. The IDE detects and sets the correct dialect and use of preprocessors.

You can also trigger directives determination manually using the Determine Directives context menu command for projects, folder and programs in the Application Explorer view, COBOL Explorer or the PL/I Explorer view. You can turn off or configure this behavior using the Micro Focus > COBOL > Directives Determination page in the IDE preferences (click Window > Preferences). For PL/I projects, you can configure the directives determination from the Micro Focus > PL/I > Directives Determination page in the IDE preferences.

Overridden Project Settings

You can display the project settings that have been overridden by build configurations and/or file settings by:
  1. Right-click the project.
  2. Click Micro Focus > Project Settings.
  3. Click Search to search the project for overridden options.

    This displays the Overridden options list.

The groupings displayed in the Overridden options list are by Micro Focus file types and build configurations. You can expand individual categories to explore the associated overridden options. Double-clicking a node in the Overridden options list opens the respective file properties or build configurations dialog box.
Note: Any changes made in the file or build configuration settings are not automatically refreshed in the overridden options list. You must rerun the search to display any changes made.

Dependency Path Handling

The Automatically add new directories to dependency paths preference on the Window > Micro Focus > Builder page in the IDE preferences (click Window > Preferences) controls whether adding a directory to a project also causes the directory to be added as an enabled item onto the dependency paths of the project. If you add a new copybook in a new folder and your build fails, you should check whether this preference is enabled or disabled and also check the project dependency paths settings.

Parent topic: Development Life Cycle


Editing

Eclipse provides some powerful editor functionality to help you be more productive and efficient when writing code in the editor. Here are a few examples of functionality which is available in the COBOL editor:

  • Content Assist - Eclipse can accelerate the edit experience by offering a list of possible completions when you press Ctrl+Space. In some editors, it also offers templates of code - code snippets.

  • Block Edit - clicking the Block Edit icon on the toolbar, Block edit ,switches the current editor into block edit mode. In this mode, if a multi-line area is selected then an insert or delete operation performed, the operation is performed for each of the lines selected.

    Selecting a zero-width multi-line block, then inserting spaces can be a handy way of indenting a whole block.

  • Go to Line - If you want to go to a particular line of code, either type Ctrl+L or double-click the line number in the status bar at the bottom, then enter the line number.

    Go to Line

    If you have an error in the Problems view, double-clicking that takes you directly to the line of code. Similarly, double-clicking on a search result takes you to the line concerned.

  • Outlines - There are a number of outline views in the main window:
    • The Outline view shows you a structural outline of your program in the current file.
    • The Program Outline view does the same but shows elements of other files that are in the same program.

    • Quick outline - while the cursor is in the editor, pressing Ctrl+O gives you a quick outline view - the dialog box goes away as soon as focus is lost. Pressing Ctrl+O again causes a quick view of the Program Outline to be shown.

      The quick outline views allow filtering of data and procedure items so can be useful for quick navigation around the program - clicking on an item in an outline takes you to that item in an editor.

  • Hyperlinks - holding down the Ctrl button while hovering over a name in an editor treats that name as a hyperlink, which when clicked, moves the cursor to the definition of the item in the editor.

Alternative Editors

Most of the time, the default editor used when you double-click a file is the editor that is required to edit the file. However, when it is not, you can right-click the file and click Open With to select one of the other available editors.

One of the more commonly-used non-default editors is the COBOL Copy View editor, which shows the entire COBOL program with all the COPY statements resolved along with the effects of any REPLACE or COPY REPLACING statements. COBOL Copy View is a read-only editor, and you can open it by pressing F4 while in the COBOL editor or by selecting Open in COBOL Copy View from the context menu of the editor. To navigate back to the standard editor, press F4 again.

Multiple Editors

In Eclipse you can have the same file opened in two or more separate editors at the same time. For example, you can have both a standard COBOL editor open and the COBOL Copy View, and changes made in the standard editor are reflected in the COBOL Copy View as you type.

A file can be opened in as many editors as you like - Eclipse can cope with more than 100 editors. To view multiple editors at the same time, you can rearrange the editor window - click on the editor tab that is currently visible and drag it to the edge of the editor area - a highlighted frame shows how the window will be repositioned when you drop it.

Parent topic: Development Life Cycle


Building

By default Eclipse is configured to perform a build whenever a file is saved. If you do not want this behavior you can turn it off by deselecting the Project > Build Automatically menu item.

The Run/Debug > Launching page in the IDE preferences (click Window > Preferences) has an option to perform a build before launching, if needed - see the General Options section on this preferences page.

Build Errors

Errors are shown in the Problems view as well as being embedded amongst all the other build output in the Console view.

If the error in the Console view has a link, click this for the IDE to open the source file and display the lines of code that are causing the error.

If the error in the Problems view has a line number, double-clicking it takes you to that line. In the editor, errors are shown by red squiggles under the code with the error (or yellow squiggles for warnings). Additionally, files with errors or warnings have an overlay on their icon in the COBOL Explorer, as do their parent directories and projects, enabling you to see at a glance where programs with errors are located.

Errors in COBOL Explorer

Eclipse can fix some errors for you, and in the Problems view these errors are indicated by a light bulb. Using the context menu or pressing Ctrl+1 starts the Quick Fix process, as does pressing Ctrl+1 while on the error in the editor.

For example, if you try to build a program to 32 bit when your platform only supports 64 bit, then a message is displayed in the console log:

Building COBOL to 32 bit is not currently supported on this platform

To fix this, in the Problems view, press Ctrl+1. This opens the Quick Fix dialog box. In the Select a fix list, it gives you the following options:

  • Change the target platform in the active build configuration
  • Clone current build configuration and change target platform in the clone

If you have created a 64 bit build configuration that you are not currently using then an additional option is presented asking if you want the 64 bit build configuration to be the active configuration. Select the most appropriate option, and then click Finish.

Parent topic: Development Life Cycle


Running and Debugging

Applications you create with Eclipse need a launch configuration to execute. A launch configuration describes the way an application should be run or debugged.

Some launch configurations apply to running and debugging, while some apply only to debugging. It is possible to configure multiple launch configurations of the same, or different types, and you can give them meaningful names.

You create configurations by clicking Run > Run Configurations or Debug > Debug Configurations - the dialog box that these open enables you to manage the launch configurations. Click a type of configuration in the pane on the left-hand side of the dialog box - a description of the intended usage of the type is shown in the banner at the top.

  • The most recently-used configurations are shown in the run and debug options on the toolbar. You can save launch configurations within a project which enables you to share the configurations between developers.

  • The behavior of the Run and Debug toolbar buttons can also be configured in the IDE preferences - click Window > Preferences > Run/Debug > Launching page. The buttons can either repeat the last launch or launch the currently-selected resource.
  • Note that the key bindings used for common functions while debugging (such as Step and Continue) are different from those used in other IDEs. To quickly find the key binding, hover over the appropriate icon in the toolbar and the key binding is shown in the tooltip.
  • To share launch configurations - click Run > Run Configurations or Run > Debug Configurations, click the Common tab of the launch configuration and select the Shared file option.

Debugging applications

Debugging your program opens the Debug perspective. You can step through code in the Debug view or use the Run to cursor feature to run from the current execution point to where you have placed the cursor.

The IDE offers a flexible debugging environment. When you debug the code you can step through it so that each line of the source is highlighted in turn as each statement is executed, showing the effect of each statement. You can interrupt execution to examine and change data items.

You can set breakpoints to control the way The following breakpoint are available:

  • Standard breakpoints, breakpoint - these are set against a line of code in the Procedure Division of the code and have properties which control when the breakpoint is activated.
  • Program breakpoints, program breakpoint - these activate when a program of the given name is called.
  • Watchpoints, watchpoint - these activate when a data item changes value.

    Note that since execution breaks when the item has been changed, the cursor position will be on the statement after the statement that caused the data item to change value.

The Debug perspective comes with a number of views tailored to support the debugging process:

  • Debug view - when debugging, the Debug view shows details of what is being debugged. Specifically, it shows a hierarchy where the first level is the launch configuration used, next is the built article that is being debugged (process), then the thread, and within that are the layers of performs and/or calls (stack frames).

    A number of debugger functions are sensitive to the item that is selected in the Debug view (so as to cope with different scopes for variables, and the debugging of multiple threads), so if a function that you expect to be enabled is not, check which item is selected in the view. If you want to step, you need to have selected the first code line within the thread.

    Selecting different stack frames controls which variables are shown in the variables view, and also switches the editor to the relevant line of code.

  • Other views in debugging - the following views in the Debug perspective enable you to monitor how the data and variables change in your applications:
    • The Breakpoints view shows all the current breakpoints. From here you can disable all breakpoints with a single click.

    • The Expressions view shows the value of any variables that you add to it, as evaluated in the context of the current location selected in the Debug view.
    • The Variables view shows the values of variables and file statuses of internal file names in use on the current or previous line of code. Those which have just changed in the last statement executed are highlighted. Again, the values displayed are sensitive to the current location selected in the Debug view.

    • The Memory view shows the memory at any given address. Note that the Memory view is not shown by default. To display it, click Window > Show View > Other and type Memory to locate the view.

      You can directly enter a numerical address or the name of a pointer variable. Alternatively, you can enter the name of a non-pointer variable and the memory of that variable is shown. Both ASCII and EBCDIC renderings are available for the memory along with the default hexadecimal rendering - click the New Renderings tab in the toolbar of the view to add new rendering.

Debugging techniques

There are various ways in which you can debug an application depending on its type and whether it resides on the local or a remote machine. See Debugging COBOL applications in your product help for detailed explanation of the different debugging scenarios.

What next?

Now that you have read this brief introduction into running and debugging applications, practice what you've learned with the tutorial that follows, Debugging the Hello COBOL World Application.

Parent topic: Development Life Cycle


Debug the Hello COBOL World Application

This tutorial uses the Hello COBOL World application which you created earlier to demonstrate how debugging works in Eclipse.

Modify your application

You are going to add some extra code to your application that will help demonstrate some of the debugging features:

  1. Open the helloworld.cbl program in the editor.
  2. Add the following code in the Working-Storage section:
    01 source-string pic x(10) value "AAbbAAbbCC".
  3. Add the following code in the Procedure Division section before the line for the COPY statement:
    inspect source-string replacing all 'A' by 'D'
display source-string
inspect source-string replacing characters by 'Q'
        before initial 'C'
display source-string

The source-string variable is a string that has an initial value of "AAbbAAbbCC". Some of the string characters are replaced during the execution of this program.

Create a debug configuration

  1. Select HelloCOBOLWorld in COBOL Explorer and from the main menu click Run > Debug Configurations.
  2. Double-click the COBOL Application tree item to create a new debug configuration.
  3. Specify HelloCOBOLWorld as the name of the configuration.

    This configuration uses HelloCOBOLWorld as the project to run and New_Configuration.bin/HelloCOBOLWorld.exe (Windows) or New_Configuration.bin/HelloCOBOLWorld (UNIX) as the main program to run.

  4. Click Debug.

    You get prompted to switch to the debug perspective. Click Yes to confirm. This starts the debugger and it stops on the first line in the PROCEDURE DIVISION.

    Some of the views of the Debug perspective you can see are:

    • Debug view - shows the currently active threads.
    • Editor - shows the helloworld.cbl program and the position of the debugger in the program.
    • Variables - shows the SOURCE-STRING variable and its initial value.
    • Outline - shows an outline of the structure of the program you're stepping through.
    • Breakpoints -

Step through the code

You can now step through the code and see how the value of the SOURCE-STRING changes:

  1. Press F5, Step Into, to start stepping the code.

    The first line in the program executes and the cursor moves to the next line in the code.

  2. Check the Variables view to see that the value of SOURCE-STRING has changed as instructed by the first line of code.
  3. Press F5 again.

    This executes the DISPLAY statement. Check the Windows Task bar for the application's console window which now also displays the value of SOURCE-STRING.

  4. Step through the next two lines in the same way and see how the value of the SOURCE-STRING variable changes.

    The cursor moves to the line that has the COPY statement and the debugger opens the HELLO.cpy copybook.

  5. Press F5 to return to the COBOL program and press it one more time to exit the program.

    Debugging stops and if you want to see the project, click the COBOL button in the right upper corner of Eclipse to change the perspective to the COBOL one.

You can save the project for future reference.

What Next?

Complete this Introduction with the following chapter on how to extend Eclipse with additional plug-ins.

Parent topic: Development Life Cycle
Related concepts
Creating Your First Hello COBOL World Application
Configuring the Hello COBOL World Application
Related reference
Additional Eclipse Functionality


Additional Eclipse Functionality

There are many bundles of extra functionality that you can add to Eclipse. Most of those which are available for free, you can find and download from https://www.eclipse.org/. Others are available from vendors directly. The bundles are usually provided as UpdateSites which you can apply by clicking Help > Install New Software.

Due to the large number of choices of additional functionality available, Micro Focus cannot test with them all. We are aware, however, that a number of source control systems make direct use of the operating system file system rather than working through the Eclipse File System. As a result, they do not work correctly with remote COBOL projects that use the Remote File System (RSE) file system option. You select the Remote File System (RSE) option in the New Remote COBOL Project dialog when initially creating a remote project. In such cases you need to use the Network file system option for the projects.

In the same way that other functionality can be added to the instance of Eclipse installed as part of your Micro Focus product, it is possible to install the Enterprise Developer UpdateSites into a pre-existing Eclipse installation. You can find details on how to do this in the installation instructions in your product help or in the release notes in the section Installing into different Eclipse packages. There are some restrictions regarding the versions of Eclipse that we support.

What next?

Now that you have finished reading this introduction, we recommend you check the section Developing Applications in the IDE for more information about how to create, run and debug applications.

Parent topic: Advanced Details
Previous topic: Development Life Cycle
Related concepts
Creating Remote Projects


Configuring Eclipse

You can configure the general Eclipse behavior for all projects by specifying options on the different property pages in Window > Preferences and on Window > Preferences > Micro Focus, in particular. All preferences that differ from the default ones are stored in the current workspace and might need to be reapplied, if you change the workspace.

You can use the Eclipse preferences to configure a variety of aspects of the Micro Focus projects such as:

  • The builder preferences for projects
  • Code analysis
  • Code coverage
  • The editor behavior
  • Profiler preferences
  • Preferences for compiling and working with standalone files
  • Preferences of the Consolidated Tracing Facility
  • Database preferences for the background parse behavior and for the OpenESQL Assistant
  • Debug preferences for the default X11 server display to use when you work with remote projects
  • The remote JREs to use
  • Any saved Micro Focus search queries
  • Interface Mapper general properties
  • Templates - the default project and file templates and their location
  • Micro Focus Builder Preferences
  • Build Directives for Standalone Editing
    Enables you to specify any Compiler directives to be used when compiling standalone COBOL files when no associated program symbols files (.idy) are found.
  • File Extensions
    You can also associate a file extension with the content type of a COBOL file, using Window > Preferences > General > Content Types.
Parent topic: Developing Applications in the IDE
Related reference
Eclipse Basics - IDE Preferences


Micro Focus Builder Preferences

The settings you specify on the Builder preferences page (Window > Preferences > Micro Focus > Builder) enable you to configure how building works in Eclipse and apply to all projects.

Default Platform Target
Specify if the program should be compiled as a 32 bit or 64 bit version. This will depend on platform support and your requirements.
Delete user files in output folder
Specify what to do with any files in the output folder which were not produced by the build.
Delete build artifacts in output folder when project settings change
Specify whether the existing output files should be deleted when your project's settings change before the project is rebuilt.
COBOL indexer options
Specify whether the IDE should detect copybook usage within your COBOL programs. This information is used by the Copybook Dependency view.
  • Enable indexer - enabled by default.
Console output
Specify whether to limit the number of characters in the notifications in the Console view. Using an unlimited or a very large buffer can affect build performance.
  • Limit console output - enabled by default.
  • Console buffer size (characters) - set to 80000 by default.
Dependency paths
Specify whether Eclipse should automatically add any new directories in your project to the Dependency paths tab in the project's properties (Micro Focus > Build Path > Dependency paths for native and Mainframe COBOL projects and Micro Focus > Dependency paths for JVM COBOL projects):
  • Automatically add new directories to dependency paths - disabled by default.
Multi-processor compilation/linking
On multi-CPU machines, use this setting to enable faster, parallel compilation of the sources in your native and mainframe projects. The maximum number of cores to be used is the number of cores of the machine on which the build is being run.
  • Maximum number of compilations/links to execute concurrently - set to 1 by default.
COBOL JVM options
By default, this specifies that each part of the package name corresponds to a subdirectory.
  • Each part of the package name corresponds to a subdirectory - enabled by default.
Parent topic: Configuring Eclipse


Build Directives for Standalone Editing

When working with a standalone COBOL file, the IDE first searches for an associated program symbols file (.idy) to provide the Compiler directives required to compile the source code.

If no .idy file is found in any of the locations specified in Window > Preferences > Micro Focus > COBOL > Standalone Files > Program Symbols (.IDY), the IDE uses the Compiler directives specified on this preferences page.

By default, the IDE uses the following Compiler directives:

  • nognt int() anim for the 32-bit Eclipse.
  • nognt int() anim P64 for the 64-bit Eclipse.

You can specify any Compiler directives here as required. For example, to specify the locations of any copybooks referenced by the standalone COBOL program that are not in the same location as the program, set the COPYPATH Compiler directive - COPYPATH(<location1>;<location2>;...).

If you have changed these directives, to reset them to the default values, click Restore Defaults.

Parent topic: Configuring Eclipse
Parent topic: Project Properties
Related concepts
Writing Code Efficiently in the COBOL Editor
Related information
Build Paths
Build Settings
BMS Properties
File Extensions
Run-Time Configuration Properties


File Extensions

The IDE currently provides support for the following COBOL content types:

  • COBOL Source File - this file is syntax colorized when it is loaded into the COBOL editor, optionally background parsed, and compiled using the COBOL compiler. The default extensions are .cbl and .cob.
  • COBOL Copybook - this file is syntax colorized when it is loaded into the COBOL editor, and is optionally background parsed. The default extensions are .cbl and .cpy.
Parent topic: Configuring Eclipse
Parent topic: Project Properties
Related information
Build Paths
Build Settings
BMS Properties
Build Directives for Standalone Editing
Run-Time Configuration Properties


Using Eclipse for COBOL Development

You can create, debug and run COBOL applications on your local machine or on a remote server. You use Eclipse features such as the COBOL and Remote Systems Explorer perspectives within the IDE to background check syntax as well as build and debug your COBOL programs. As in other Micro Focus products, you use COBOL-specific projects to aid your everyday development activities within the IDE. This provides familiar functionality for editing, compiling, and debugging, complete with comprehensive COBOL Help.

The features of the COBOL development system include:

  • Perspectives to show the appropriate panes and views in the IDE such as the Remote System Explorer, COBOL, and Debug.
  • Editing features such as:
    • Background parse for syntax checking
    • Code templates by pressing ctrl space
    • Outline view
    • Code completion
    • Collapse/expand
    • Code colorization
  • Project handling, such as:
    • Automatic building
    • Dependency checking
    • ANT as the engine
    • Build Precedence ordering for directories
    • SQL directive support
    • Multiple build configurations
  • Debug configurations, which you can reuse for different debugging scenarios. In addition to standard debugging you can:
    • Attach to a running application. This allows you to attach a debugger to an already running COBOL application.
    • Wait for attachment. This process starts a debugger a waits for a COBOL application to attach.
  • Comprehensive debugging features such as:
    • Breakpoints
    • Expressions view
    • Stack trace
    • Stepping
    • Variables view
    • Watchpoints
Note: When working with local SQL applications on UNIX, ensure the RDBMS environment is set before you start Eclipse. Refer to your RDBMS vendor's documentation for details.

Developing applications remotely

When you develop COBOL remote applications, you use a remote server running Micro Focus Enterprise Developer UNIX Components to host your source code, and use the Eclipse IDE on your local machine as the development interface.

Working with a remote machine allows you to develop and host applications on UNIX and Linux servers while using a Windows or Linux hosted Eclipse IDE. In this scenario, all source code is maintained on the remote server. In addition, no actual build processing occurs on the machine hosting the Eclipse IDE. Instead, all processing tasks including editing, compilation and debugging are performed on the remote server. Copying files between the local client and the remote server using FTP for example, is not required.

  • Overview of Creating COBOL applications in Eclipse
  • Tips and Tricks with the IDE
  • Working With a Large Code Base
Parent topic: Developing Applications in the IDE


Overview of Creating COBOL applications in Eclipse

The following steps outline the process of creating COBOL applications in Eclipse:

  1. Create a COBOL project.
  2. Either create new programs for your project, or import existing ones.
  3. Configure and build the project. Your build configuration specifies items such as Compiler directives and the target file types, and whether to compile for debugging.
  4. Create a debug configuration.
  5. Choose the type of application or scenario, such as COBOL Application, COBOL Attach to Application or COBOL Wait for Application Attachment.
  6. Debug the program.
  7. Configure the run-time environment and run the application. Your run-time configuration specifies items such as the search order for called programs, memory allocation, how to handle ANSI displays and so on.
Parent topic: Using Eclipse for COBOL Development
Related concepts
Creating a Debug Configuration
Creating and importing COBOL projects
Setting Compiler Directives for COBOL
Overview of the process of debugging
Running COBOL Applications


Tips and Tricks with the IDE

  • COBOL Perspectives and Projects
  • Writing Code Efficiently in the COBOL Editor
  • Searching using Micro Focus Search
    You can use Search > Micro Focus to search for files by file type or for files that cause build errors or warnings. You can also use Search > Run Stored Micro Focus Search Query.
  • Viewing Copybooks in Context
Parent topic: Using Eclipse for COBOL Development


COBOL Perspectives and Projects

The first step in developing COBOL in Eclipse is to create a COBOL project. COBOL projects in Eclipse are like other Eclipse projects. A COBOL project is a representation of the source files (with dependencies) and build commands used to create your application or program. You create a project using a wizard and the resulting project is displayed in the COBOL Explorer view, from where you can open your source files.

When you create or open a COBOL project, a COBOL perspective is automatically opened. Perspectives are an Eclipse concept. They present the views, menus and options relevant to your activity. The COBOL perspective shows the COBOL Explorer, Outline and Console views, among others. The perspective is customizable, so you can choose your own views.

Among the other perspectives you can use while you develop COBOL in Eclipse are the Consolidated Tracing Facility (CTF) and the Debug perspectives.

Parent topic: Tips and Tricks with the IDE


Writing Code Efficiently in the COBOL Editor

The COBOL editor is the default editor for editing files with extensions associated with COBOL. It offers a variety of features to help you write code quickly and efficiently.

AutoCorrect

Enables you to specify a list of words and their commonly mistyped versions. When you type the misspelled version in the editor, AutoCorrect automatically corrects them. By default, AutoCorrect is enabled and contains a predefined list of commonly misspelled words. You can edit and add to the predefined list of words and their misspelled versions from Window > Preferences > Micro Focus > COBOL > Editor > AutoCorrect. You can also export or import lists allowing you to apply bulk edits and share with colleagues. To disable AutoCorrect, uncheck Enable AutoCorrect. See Configuring AutoCorrect for more information.

Note: AutoCorrect does not correct text in comments or strings.

Block selection

Allows you to select specific blocks of text from your code. The selection mode is toggled using the [image] button from the toolbar or shortcut key Alt+Shift+A.

Call Hierarchy view

You can open the Call Hierarchy view for JVM COBOL programs. To open the view, right-click in the editor, and then click Open Call Hierarchy. Alternatively, press Ctrl+Alt+H. The view enables you to see the callers and callees hierarchy for the selected JVM COBOL member.

COBOL Copy view

COBOL Copy view allows inline expansion of copybooks so you are able to see your code and copybooks in a single view. While some of the features available in the COBOL editor, including finding references and locating definitions, are available in COBOL Copy view, it is a read-only source viewer and you cannot use it to edit code. You also use the debugging facilities from this view.

You can open COBOL Copy view when working in the COBOL Editor view by pressing F4. Pressing F4 again switches you back to the COBOL Editor. You can open COBOL Copy view when editing either a program or a copybook; if you open it when editing a copybook, it shows the content of the copybook inside the program you have chosen to be its default context. You choose this context by right-clicking the copybook in COBOL Explorer and selecting Open In Context.

Code templates

Provides you a snippet of code for the statement you are typing. Press Ctrl+Space to see content assist proposals that include the available code templates. Select and insert a code snippet and it gives you an outline of the syntax for you to fill in the blanks. You can add more templates from the IDE preferences - Window > Preferences > Micro Focus > COBOL > Editor > Templates.

Content Assist

Content assist provides writing assistance that enables you to write syntactically correct code quickly. Content assists provides proposal lists that include procedural and managed COBOL keywords and data items as well as Java types. You can configure the preferences for content assist in COBOL from Window > Preferences > Micro Focus > COBOL > Editor > Content Assist.

For full description about how content assist works, see Editing Assistance in the COBOL Editor.

Copybook Dependency view

Use the Copybook Dependency view to show where in the source file's structure the COPY statements appear, and which copybooks they reference.

Click a copybook reference in the Copybook Dependency view to locate the associated COPY statement at the appropriate line in the source code.

Editing standalone files

This only applies to native COBOL. The recommended way to work with Enterprise Developer is to include all source files in a project because this enables full support for the IDE editing, compiling and debugging features. There is limited support in the IDE for standalone files - such that are not part of a project.

To open a file in the IDE without a project, click File > Open File.

The IDE searches the Program Symbols (.IDY) page in Window > Preferences > Micro Focus > COBOL > Standalone Files

Edit the file in the usual way. Note, however, that background syntax checking is not available so no errors are reported as you type. You need to recompile in order for the IDE to check your code and report any issues.

When starting the IDE from the command line, also set the COBCPY environment variable to point to the folders where the IDE should search for copybooks.

To specify the locations of any copybooks used by the standalone file when the copybooks are not in the same location, set the COPYPATH Compiler directive in the IDE on the Compile page in Window > Preferences > Micro Focus > COBOL > Standalone Files as COPYPATH(<location1>;<location2>;...). You then need to recompile the file.

Check Known Errors and Restrictions for information about the level of support for standalone files.

Extracting COBOL code to a copybook

You can extract highlighted lines to a copybook by right-click in the editor, and clicking Refactor > Extract to Copybook. See Extracting COBOL code to a copybook for more information.

Folding

Hides or shows sections of the program, such as the File section, Linkage section and so on. You can hover over a collapsed section to show it expanded. You can configure your folding preferences from Window > Preferences > Micro Focus > COBOL > Editor > Folding.

Go To Definition

You can use this feature in both native and JVM COBOL projects to find where an item is defined. Right-click an item and click Go To Definition. Alternatively, press F3. The cursor moves to the line of code where the item is defined. The item is also highlighted in the Outline view. You can find the definition for fields, events, types, methods and properties.

You can also navigate to an item that has been declared in Java from a JVM COBOL source. This applies to fields, types and methods.

Go to Matching Block/Bracket

You can use this feature to locate the bracket that matches the one at your current cursor position. To move the cursor to the matching bracket, right-click in the COBOL editor, and then click Go to Matching Block/Bracket. Alternatively, press Ctrl+Shift+P.

Mark occurrences

Marks the occurrences of the selected element (data item or section) in the current file. You can switch this feature on/off when a COBOL Editor/Copy view is opened by pressing Alt+Shift+O.

Open Type

Brings up the Open Type dialog to open a type in the editor. The Open Type selection dialog shows all types existing in the workspace. It's accessible from Navigate > Open Type, or by pressing Ctrl+Shift+T.

Enter a type name, or prefix, or the first characters of the type you want to select. It is displayed in the list. When you select it and double click it you see it displayed in the COBOL editor.

Open Type in Hierarchy

Brings up the Open Type dialog to open a type in the editor and the Type Hierarchy view. The Open Type selection dialog shows all types that exist in the workspace. It's accessible from Navigate > Open Type in Hierarchy or by pressing Ctrl+Shift+H. This option lets you see where a selected type stands in the type hierarchy.

Outline view

Shows the structure of the program you are editing. This is useful for navigating large programs, for example by clicking on a Data Division item, a COBOL section or a paragraph to go to it in the code. You can also right-click an item and choose from a range of relevant options.

The Outline view shows only items from the current editor - if the program is opened in the COBOL editor only items from the current program are visible and not from its copybooks. If the program is opened in the Copy view all items are visible in the editor (the Copy view is a read-only editor) and in the outline.

Program Outline view

Similar to Outline view. When you click a data item declaration in the Program Outline view and this opens the relevant copybook and goes to the relevant line. The Program Outline view always shows the whole program structure, including the elements that are in other files.

Quick Outline view

Similar to Outline view. To start it press Ctrl+O or select Navigate > Quick Outline for an in-place outline of the current source file. When you type while Quick Outline view is displayed you filter the list of displayed elements for easier navigation. Pressing Ctrl+O while Quick Outline view is active displays the same information as in Program Outline.

Read-Only background colorization

When you open a file in read-only mode (in the editor or if you open the COBOL Copy View), the background is colored in light yellow to remind you that you cannot use it for editing files.

Light yellow is the default color but you can change it according your personal preference. To do so, open Window > Preferences > Micro Focus > COBOL > Editor, select a background color from the palette in the Read-Only mode section of the page. Click Apply and then OK.

References

You can use this feature in both native and JVM COBOL projects to find references to an item.

In a native COBOL project, place the cursor on the item, right-click, and select References. Alternatively, press Ctrl+Shift+G. The Search tab displays all the references found in the search. You can explore the results returned, double-clicking on the item moves the cursor to that position in the relevant file.

In a JVM COBOL project you can also specify the scope of the search. Place the cursor on the item being referenced, right-click, and select References. Choose the scope of the search; Workspace, Project or Hierarchy. The Search tab displays all the references found in the scope of the search, with default grouping by package.
Note: The Hierarchy relates to the type or class.

Remove Trailing Whitespace

By default, trailing whitespace is not removed when you save a COBOL file. You can remove trailing whitespace after column 80 or remove all trailing whitespace when you save your file. To configure your preferences to remove trailing whitespace, click Window > Preferences > Micro Focus > COBOL > Editor. In the Remove trailing whitespace group, click your preference, and then click Remove trailing whitespace on save.

To remove all trailing whitespace, click Source > Remove Trailing Whitespace. Alternatively, right-click in the COBOL editor, and then click Source > Remove Trailing Whitespace.

Rename refactoring

Rename refactoring enables you to rename all or selected occurrences of a variable, a paragraph or a section name or an identifier in your code. Right-click the name to change in the editor and click Refactor > Rename. To configure the IDE preferences for rename refactoring, click Window > Preferences > Micro Focus > COBOL > Editor and either check or uncheck Rename in editor without dialog.

Syntax Coloring

Syntax coloring enables you to choose from a list of predefined syntax coloring schemes. You can customize a coloring scheme by specifying your preferred color and style for a particular code element, such as Compiler directives, reserved words, data items and so on.

You can configure your syntax coloring preferences from Window > Preferences > Micro Focus > COBOL > Editor > Syntax Coloring. By default, inactive code is colored the same as compiler directive elements. Inactive code is defined as code within conditional blocks that can never evaluate to true. An example of this is provided in the Preview pane:
      $if 1 = 0
           MOVE 1 TO var-1
      $else
           MOVE 2 TO var-1
      $end
If you want to disable colorization of inactive code, uncheck Colorize inactive code as directive. See Configuring Syntax Coloring for more information.

Tasks

You can manage tasks by adding the default TODO or FIXME tags in the COBOL code comments. Eclipse visualizes these tags in the Task tab. Any text that follows the TODO or FIXME tags appears in the task description. To view the Task tab, click Window > Show View > Tasks or Windows > Show View > Other, expand General, click Tasks, then click OK. Double-clicking on the line in the Task tab takes you to the highlighted line in the editor.

Both TODO and FIXME tag lines are marked on the left margin of the editor with a clipboard icon ( [image]). Rows in the Task tab that are tagged TODO are high priority tasks and are highlighted with an exclamation point ( [image]).

You can customize the tags from Window > Preferences > Micro Focus > COBOL > Editor > Task Tags. You can add, remove or edit tags, specifying their priority as high, normal or low.

Toggle Comments

Enables you to toggle single or multiple lines between a commented and uncommented state. Pressing Ctrl+/ toggles the highlighted lines between states. Commenting a line applies a leading asterisk, uncommenting removes the leading asterisk.

Type Hierarchy view

You can open the Type Hierarchy view for JVM COBOL programs. To open the view, right-click in the editor, and then click Open Type Hierarchy. Alternatively, press Alt+Shift+H. The view enables you to see classes, subclasses and members and their supertypes, or their subtypes.

  • Configuring AutoCorrect
  • Customizing the Editor
  • Configuring Background Parsing
  • Configuring Syntax Coloring
  • Configuring Smart Edit Mode
  • Editing Assistance in the COBOL Editor
    Enterprise Developer supports Content Assist for both native and managed COBOL.
  • Inserting and Removing Line Numbers (Renumber and Unnumber)
  • Using COBOL Code Templates
Parent topic: Tips and Tricks with the IDE
Related reference
Configuring Syntax Coloring
Extracting COBOL code to a copybook
Build Directives for Standalone Editing


Configuring AutoCorrect

AutoCorrect can be configured to correct your commonly mistyped words:

Adding an AutoCorrect item

To add an additional mistyped word and its correct spelling:

  1. Click Window > Preferences > Micro Focus > COBOL > Editor > AutoCorrect.
  2. Click Add.

    This opens the Add AutoCorrect Item dialog box.

  3. In the Replace field, type the mistyped word to be replaced.
  4. In the With field, type the correct spelling.
  5. Click OK.
  6. Click Apply.
  7. Click OK.

Exporting the AutoCorrect item list

In addition to editing and removing existing AutoCorrect items, you can perform a bulk export of all items in the list. This allows you to modify large lists rather than making numerous individual additions or edits. It also enables you or your organization to share lists. To export the full list of AutoCorrect items to an XML-formatted file, perform the following steps:

  1. Click Window > Preferences > Micro Focus > COBOL > Editor > AutoCorrect.
  2. Click Export.
  3. Browse to the directory location you want to save the file.
  4. In the File name field, type an output file name.
  5. Click Save.

The exported file has the following format:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<autocorrect>
    <autocorrectitem right="correctly_spelled_word" wrong="incorrectly_spelled_word"/>
    <autocorrectitem right="..." wrong="..."/>
</autocorrect>

Importing an XML-formatted AutoCorrect item list

To import an XML-formatted file containing a list of AutoCorrect items:

  1. Click Window > Preferences > Micro Focus > COBOL > Editor > AutoCorrect.
  2. Click Import.
  3. Browse to the location of your XML-formatted AutoCorrect file and select it.
    Note: The imported file must have the same format as the exported format as described in the section Exporting the AutoCorrect item list.
  4. Click Open.
Parent topic: Writing Code Efficiently in the COBOL Editor
Related information
Customizing the Editor
Configuring Background Parsing
Configuring Syntax Coloring
Configuring Smart Edit Mode
Editing Assistance in the COBOL Editor
Inserting and Removing Line Numbers (Renumber and Unnumber)
Using COBOL Code Templates


Customizing the Editor

The editor is customizable from Window > Preferences > Micro Focus > COBOL > Editor. You can change the above features, as well as colors, line numbers, margins and more.

You can associate a file extension with the COBOL editor. See Window > Preferences > General > Editors > File Associations. You can also associate a file extension with the content type of a COBOL file.

Parent topic: Writing Code Efficiently in the COBOL Editor
Related information
Configuring AutoCorrect
Configuring Background Parsing
Configuring Syntax Coloring
Configuring Smart Edit Mode
Editing Assistance in the COBOL Editor
Inserting and Removing Line Numbers (Renumber and Unnumber)
Using COBOL Code Templates


Configuring Background Parsing

The code you type is parsed continuously to identify errors. The errors are underlined with red squiggly lines.

Regardless of whether background parsing is enabled, error information is generated during project builds.

CAUTION:
You can turn off background parsing, but many of the IDE features depend on it (for example Outline/Program outline, colorization, and Copy View). If it is switched off they will not work and might cause unexpected problems.
Switching off or delaying background parsing when Eclipse is running
You can turn off background parsing in the Preferences dialog box (select Window > Preferences > Micro Focus > COBOL > Editor and deselect Background parsing).

Parsing is triggered when there is a pause in editing code; by default this is 500 milliseconds. By keeping Background parsing selected and entering a larger value in the Trigger delay field, you can make sure your code is parsed less frequently, and improve performance when developing projects with large numbers of source files.

Switching off background parsing before you start Eclipse
Use the property disable.cobol.indexing to switch off background parsing when you start Eclipse.
If you start Eclipse from the command line, you do this by using the command:
eclipse.exe -vmargs -Ddisable.cobol.indexing=true
If you start Eclipse from the Start menu or a shortcut, edit the eclipse.ini file and add the line:
-Ddisable.cobol.indexing=true
to the -vmargs section.
Switching off or limiting background parsing for specific databases
You can limit background parsing for code relating to DB2, OpenESQL, and XDB processing, which can improve performance if you are developing large projects that use these databases. Select Window > Preferences > Micro Focus > COBOL > Editor and choosing your preferred level of parsing in the DB2 Background Parse, OpenESQL Background Parse, and XDB Background Parse pages).

Basic background parsing is a minimal check of EXEC SQL statement structure and doesn't require a database connection. Errors that are not detected by a basic check will result in runtime errors..

Complete background parsing uses a database server to perform additional checks. This detects more errors at compile time but requires more resources and works best with small projects and a connection to a database on the local machine. In addition to a database connection, the database schema used by the application must be present.

Note:

The COBOL Indexer runs in a background thread, scanning all programs to work out what copy books each program uses. If a file thought to be a program is actually found to use a copybook, the file's type is changed to copybook. The Indexer is only executed when determining directives, typically when files are added to a project, and gleans index information from the build output. This can mean a delay in the information being updated compared to earlier releases of the product, but reduces the amount of indexing performed and thereby increases performance.

The Background Parser either runs directly in the COBOL indexing thread or in a thread invoked separately by the Editor when a change is made to a program. By default it is invoked by the Editor half a second after you stop typing. When you first open an Editor window, if an .idy file can be found then no background parse is performed and the Team Developer perspective views populated with information from the .idy file.

The Parser is also used for COBOL JVM projects. The Java Indexer invokes the background parser when it needs information about a class (such as method declarations and inner classes), which is cached by the Java Indexer in the workspace.

Parent topic: Writing Code Efficiently in the COBOL Editor
Related information
Configuring AutoCorrect
Customizing the Editor
Configuring Syntax Coloring
Configuring Smart Edit Mode
Editing Assistance in the COBOL Editor
Inserting and Removing Line Numbers (Renumber and Unnumber)
Using COBOL Code Templates


Configuring Syntax Coloring

You can specify default color schemes or customize your own:
  1. Click Window > Preferences > Micro Focus > COBOL > Editor > Syntax Coloring.
  2. Choose your preferred color scheme from the Color Scheme list.

    The coloring of the code in the Preview pane changes to the selected scheme.

    • You can customize elements in the scheme. In the Elements list, click the element you want to customize:
      • To customize the color:
        1. Click Color Editor.

          This opens the Color dialog box.

        2. Click the color of your choice from the selection of basic colors.
          • Alternatively, click Define Custom Colors, and choose your preferred color from a more extensive palette.
        3. Click OK.

          The element color changes in the Preview pane.

      • To customize the element font style, check one or more of the style check boxes.
    • To disable the colorization of inactive code, uncheck Colorize inactive code as directive.
      Note: Colorization of inactive code requires background parsing to be enabled.
  3. Click Apply.
  4. Click OK.
Parent topic: Writing Code Efficiently in the COBOL Editor
Related concepts
Writing Code Efficiently in the COBOL Editor
Related information
Configuring AutoCorrect
Customizing the Editor
Configuring Background Parsing
Configuring Smart Edit Mode
Editing Assistance in the COBOL Editor
Inserting and Removing Line Numbers (Renumber and Unnumber)
Using COBOL Code Templates


Configuring Smart Edit Mode

Smart edit mode controls the behavior of word wrapping and indentation in the different COBOL areas. With it enabled, you can change the following configuration options in the Typing preferences dialog box: select Window > Preferences > Micro Focus > COBOL > Editor > Typing.

Wrapping
  • Wrap code when area B end is reached - lines wrap when you reach the end of area A/B.
  • Wrapping moves the text in the right hand area to the new line - any comments in the right-hand area stay in the right-hand area but move to the next line when wrapping in the A/B area occurs.
  • Wrap lines when deleting forwards and backwards - when you press Delete after the last non-white space in the area, the line beneath moves up (and where possible wraps in the A/B area), and comments in the right-hand area stay with the associated line of code. Similarly, when you press Backspace in column 1, the current line moves up (and where possible wraps in the A/B area), and comments in the right-hand area stay with the associated line of code.
Indentation
  • Enter key and smart wrapping adjust the indentation on the new line - automatic indentation options.
  • Pressing home/end moves caret to the beginning/end of the area - changes the way the Home and End keys move the cursor in the COBOL editor. Pressing Home repeatedly first moves the cursor immediately before the first non-white space in the current area, then at the beginning of the area, or to the first non-white space in the preceding area. Pressing End repeatedly first moves the cursor immediately after the last non-white space in the current area, and then at the start of the following area.
Parent topic: Writing Code Efficiently in the COBOL Editor
Related information
Configuring AutoCorrect
Customizing the Editor
Configuring Background Parsing
Configuring Syntax Coloring
Editing Assistance in the COBOL Editor
Inserting and Removing Line Numbers (Renumber and Unnumber)
Using COBOL Code Templates


Editing Assistance in the COBOL Editor

Content Assist is an Eclipse feature that provides context-sensitive proposals for typing COBOL code in the editor. In Enterprise Developer, Content Assist is available for both native and managed COBOL.

You can change your preferences for Content Assist from within the IDE in Window > Preferences > Micro Focus > COBOL > Editor > Content Assist and specify options such as the case of the inserted words, whether to show the proposal lists or insert single proposals automatically, or whether proposals should be added in overwrite mode or as insertions. See Configuring Content Assist for COBOL for more details.

Content Assist in native COBOL

The following describes the writing assistance that Content Assist provides in native COBOL.

Content Assist enables you to write syntactically correct code, to complete words quickly and to look up available elements.

Content Assist only offers assistance for the data items that are in scope based on the current position of the cursor.

Features include:

Proposal lists
By default, Content Assist does not display a proposal list (a pop-up with suggestions) immediately after you start typing - press Ctrl+Space to display the proposal list.
Note: You can enable auto-activation from the IDE preferences - see Window > Preferences > COBOL > Editor > Content Assist. Ctrl+Space is the default key combination for invoking Content Assist and you change it also from the IDE preferences.

The following list summarizes how proposal lists work:

  • Proposals are context sensitive - the proposal lists only include suggestions that are relevant to the position of the cursor in the code and the type of project.

    For example, proposal lists only show COBOL verbs in the Procedure Division section and not in the Working-Storage section, and the verbs are only relevant to native code. Proposal lists for MSS projects include Mainframe Subsystem code snippets. For files with FIXED or VARIABLE source format, proposals are only available in the writing area.

  • Proposals start with the letters you entered with the best match highlighted in the Content Assist pop-up. The list auto-updates as you type.
  • Proposals might include COBOL keywords ( keyword), copybooks ( Copybook) in the proposal lists for the COPY statement, code templates ( code snippet), data items ( variable), 78 level items ( 78 level item), or sections and paragraphs ( section)

    By default, Content Assist opens a proposal list that only shows the relevant COBOL keywords and identifiers. To view if there are any code templates that could be inserted at the current position of the cursor, you need to press Ctrl+Space once more.

  • Proposal lists include the COPY statement.
  • Proposal lists are available in copybooks.

    If a copybook is opened in the editor in the context of a program, the proposal lists in the copybook include the variables as defined in the program.

Completing statements
Content Assist provides intelligent assistance for completing COBOL statements. When you are entering a statement, Content Assist shows proposals for the relevant clauses and the identifiers that you can use to complete the statement. The proposals take into account the syntax rules that apply to the statement in the selected COBOL dialect and the identifiers in scope.

To complete a statement:

  1. Start typing the first verb of a COBOL statement.
  2. Press Ctrl+Space to display the proposal list that includes the clauses and identifiers that you can use.
  3. Choose a proposal from the list and press either Enter or Space to insert it in the code.
  4. Press Ctrl+Space to see further proposals.
Completing COPY statements
After entering a COPY statement and pressing Space, the first proposals list that appears includes any copybooks.

You need to choose a copybook from the list for Content Assist to insert after the COPY statement. After the copybook is inserted, the proposals list that appears gives you the option of terminating the statement with a period (.) or continuing it with one of the clauses IN, OF, REPLACING or SUPPRESS.

By default, proposals for COPY statements only include the copybooks that are found in the directories specified on the Dependency Paths tab on the Micro Focus > Build Path page in the project's properties and also includes copybooks from the active dependency paths of any projects referenced by your project, but you can change this so that the proposals also include system copybooks. System copybooks are ones that are not included in the project but are included using the COBCPY environment variable before starting Eclipse. To include the system copybooks, change the Content Assist preferences from Tools > Options > Text Editor > Micro Focus COBOL > Content Assist.

Automatic completion
If a proposal list includes a single proposal, pressing Ctrl+Space automatically inserts that proposal in the code. You can turn off this option from the IDE preferences (go to Window > Preferences > Micro Focus > COBOL > Editor > Content Assist).
Qualifying non-unique names
If variable names are not unique, Content Assist qualifies the names.

Consider the example of a program that defines two group items - StudentRecord and TeacherRecord. Both group items include a number of PIC X elementary items with the same names - for example, FirstName, Surname, Phone and so on. In such a case, Content Assist qualifies the elementary items as follows:

  1. In the Procedure Division, type move and press Space.

    The proposals list that pops-up includes COBOL keywords, the group items defined in your program, and the elementary items that are present in both group items.

  2. Select one of the elementary items, for example Surname of StudentRecord, and insert it in your code.
  3. Press Space which offers to insert the TO clause.

    Content Assist has helped you specify the exact elementary item to use in your code:

    move Surname of StudentRecord to...

Content Assist in JVM COBOL

Note: The following applies to JVM COBOL only.

In JVM COBOL, Content Assist shows proposals that include any methods, fields, properties, types and so on that are available when you declare items or type an object name followed by a double colon or an opening bracket in the Procedure Division.

You can choose an item from the list to complete the code rather than typing it yourself.

The following are examples of where Content Assist pops up:

  • Type Listings - When you start declaring a type, such as 01 my-string type, Content Assist pops up a list of the namespaces and types available to your program, as soon as you press Ctel+Space after the word type. These namespaces are obtained from each of the references to packages you’ve added to your project using the ILUSING directive or using the project's properties (on the Micro Focus > JVM Build Path page).

    As you type a package name, Content Assist shows all the types within that package name. For example, when you type:

    • 01 my-string type - all the available prefixes of the higher-level packages are listed, for example - com, java, javafx.
    • 01 my-string type java. - all the intermediate packages that are children of the java package.
    • 01 my-string type java.lang. - all the types and subpackages within the java.lang package are listed.
  • Member Listings - when you invoke an object, Content Assist pops up a list of methods, fields, properties and events that are available for that object. This happens when you use inline style of invoke statements (with the double colon ::), such as:
    invoke exception-object::
  • Configuring Content Assist for COBOL Programming
Parent topic: Writing Code Efficiently in the COBOL Editor
Related reference
Configuring Content Assist for COBOL Programming
Related information
Configuring AutoCorrect
Customizing the Editor
Configuring Background Parsing
Configuring Syntax Coloring
Configuring Smart Edit Mode
Inserting and Removing Line Numbers (Renumber and Unnumber)
Using COBOL Code Templates


Configuring Content Assist for COBOL Programming

You configure the behavior of Content Assist in the COBOL editor from Window > Preferences > Micro Focus > COBOL > Editor > Content Assist. See Editing Assistance in the COBOL Editor for more details.

Proposals

By default, Content Assist automatically shows list of proposals when you start typing in the Procedure Division of a program. If Enable auto activation is disabled, to show proposals, you need to press Ctrl+Space.

Proposal lists include COBOL statements, identifiers and, for COPY statements, any copybooks that are part of the project. You can optionally configure for the following to be included in the proposal lists:

Include system copybooks in copybook proposals
Check this for the proposal lists for COPY statements to also include copybooks that are external to the workspace but are included in the project using the COBCPY environment variable.
Include reserved words
Check this to see COBOL reserved words in the proposals list. Enabled by default.
Include code templates
Check this to see COBOL code templates in the proposals list. Enabled by default.
Include extension methods
Check this to see any available extension methods in the proposal lists.
Include XML special registers
Enables the display of the XML special registers as identifiers in the IntelliSense lists.
Enable legacy fuzzy matching
Disabled by default. With this checked, you receive proposals of words that not only start with the letters you type but that might be spelled differently but are similar to what you are typing. This can help receive relevant proposals in cases when words are misspelled.

If this is unchecked, you only receive proposals that start with the letters you have typed.

Insertion

You can specify whether Content Assist adds items from the proposal lists that you select in insert or in overwrite mode. To switch between the two modes in the editor, press and hold Ctrl while you are typing.

Completion inserts
Click this to enter proposals in the code in insert mode. When this option is selected, you can force overwrite mode while you type by pressing and holding Ctrl.
Completion overwrites
Click this to enter proposals in the code in overwrite mode. When this option is selected, you can force insert mode while you type by pressing and holding Ctrl.
Insert single proposals automatically
Check this to automatically insert a proposal in the code, if it is the only item in the list.
Completion overwrite foreground
Font color to use to highlight the text to overwrite. Only applies when Completion overwrites is enabled.
Completion overwrite background
Background color to use to highlight the text to overwrite. Only applies when Completion overwrites is enabled.
Case of reserved words
Specifies the case of reserved words that will be inserted in the code:
  • By dialect - Default. Content Assist inserted reserved words using the case required by the COBOL dialect of the project or the program.
  • Upper case - Content Assist inserts reserved words in upper case.
  • Lower case - Content Assist inserts reserved words in lower case.
Case of identifiers
Specifies the case of identifiers that will be inserted in the code:
  • As declared - the case of the inserted identifiers is as in their declaration.
  • Upper case - Content Assist inserts identifiers in upper case.
  • Lower case - Content Assist inserts identifiers in lower case.

Auto Activation

Enable auto activation
Checked by default. Enables Content Assist to automatically display a list of proposals for statements and identifiers when you start typing. The list updates as you type.

If this option is disabled, to see Content Assist proposals, you need to press Ctrl+Space.

Auto activation delay (ms)
Specify the time delay (in milliseconds) between typing a character and receiving Content Assist proposals.
Parent topic: Editing Assistance in the COBOL Editor
Related concepts
Editing Assistance in the COBOL Editor


Inserting and Removing Line Numbers (Renumber and Unnumber)

There are editor commands for inserting COBOL line numbers (left side of the code) or standard line numbers (right side of the code):

  • COBOL numbering - line numbers are inserted in the sequence area of the code (columns 1 - 6), starting by default at 000100 at the first line, incrementing by 100 by default.

    Micro Focus recommends that you use COBOL numbering only if your files are in fixed or variable source format.

  • Standard numbering - line numbers are inserted immediately to the right of area B, in columns 73 - 80, starting by default at 00000100 at the first line, incrementing by 100 by default.

    Micro Focus recommends that you use Standard numbering only if your files are in fixed format.

  • To specify line numbering options
  • To number or renumber lines in source code
  • To remove line numbers from source code
Parent topic: Writing Code Efficiently in the COBOL Editor
Related information
Configuring AutoCorrect
Customizing the Editor
Configuring Background Parsing
Configuring Syntax Coloring
Configuring Smart Edit Mode
Editing Assistance in the COBOL Editor
Using COBOL Code Templates


To specify line numbering options

You can configure the IDE options for line numbering as follows:

  1. In Enterprise Developer, click Windows > Preference.
  2. Expand Micro Focus > COBOL > Editor, and click Line Numbering.
  3. Check one or both options for the style in which you want your source numbered:
    • COBOL (left-hand margin) - numbers run down the left-hand side of the source.
    • Standard (right-hand margin) - numbers run down the right-hand side of the source.
  4. You can specify the number of lines incremented between new lines; this can be set as an integer between 1 through 1000, the default is 100.
    • Line number increment (1 - 1000) - type the number to be incremented between new lines.
  5. Click Apply, then click OK.
Parent topic: Inserting and Removing Line Numbers (Renumber and Unnumber)
Related information
To number or renumber lines in source code
To remove line numbers from source code


To number or renumber lines in source code

To number or renumber the lines in a COBOL source file that is open in the editor:

  • Right-click the source code in the COBOL editor, and click Source > Renumber.

    If the source code has not been previously numbered, Renumber numbers it.

Alternatively, click Renumber in the Eclipse toolbar.

The style of the line numbers is specified in Window > Preferences > Micro Focus > COBOL > Editor > Line Numbering.

Parent topic: Inserting and Removing Line Numbers (Renumber and Unnumber)
Related information
To specify line numbering options
To remove line numbers from source code


To remove line numbers from source code

You use the unnumber command to remove the COBOL line numbers from source code:

  1. Open a source file in the editor.
  2. Right-click the source code in the COBOL editor, and click Source > Unnumber. Alternatively, click Unnumber in the Eclipse toolbar.

    This removes any numbers and text that are in the area for the selected line numbering style.

For example, if you have configured the editor to use COBOL line numbering, unnumbering removes all text from the COBOL sequence area.

You can use Undo to revert the changes.

The style of the line numbers is specified in Window > Preferences > Micro Focus > COBOL > Editor > Line Numbering.

Parent topic: Inserting and Removing Line Numbers (Renumber and Unnumber)
Related information
To specify line numbering options
To number or renumber lines in source code


Using COBOL Code Templates

Code templates in Eclipse enable you to write programs quickly. Enterprise Developer provides code templates for the most commonly used code constructs in native and managed COBOL as well as templates for writing mainframe CICS and DLI constructs .

To insert a code template in your program:

  1. In the editor, position the cursor in the code where you want to add the code template.
  2. Either type the name of a code template as defined in the IDE preferences or invoke Content Assist - for example, by pressing Ctrl + Space.

    This opens a list with suggestions for the COBOL keywords and templates that are supported at this place in the program.

  3. While the list is still visible, press Ctrl + Space to filter the suggestions and only show the supported code templates.
  4. Select a template from the list and press Enter to insert it in your program.

To view a full list of the code templates available for COBOL and to add new templates, click Window > Preferences > Micro Focus > COBOL > Editor > Templates.

Parent topic: Writing Code Efficiently in the COBOL Editor
Related information
Configuring AutoCorrect
Customizing the Editor
Configuring Background Parsing
Configuring Syntax Coloring
Configuring Smart Edit Mode
Editing Assistance in the COBOL Editor
Inserting and Removing Line Numbers (Renumber and Unnumber)


Searching using Micro Focus Search

You can use the Micro Focus search feature to make it easier to find files within your projects:

  • Select Search > Micro Focus, and type the file search pattern.

    You can filter results based on:

    • File type: choose from COBOL programs, copybooks, PL/I files, JCL files, and BMS and macro source files.
    • Only those files that cause build errors.
    • Only those files that cause build warnings.

    You can control the scope of your search:

    • Workspace - searches entire workspace.
    • Selected resources - searches only the resource currently being edited or highlighted in the tree view.
    • Enclosing projects - if the editor is focussed on a resource or resources are highlighted in the tree view, then the search is within the entire project containing the resources.
    • Current program - searches the resource currently being edited, as well as within any copybooks or include files used by the resource.
    • Working set - see Working Sets for more information.
  • Select Search > Run Stored Micro Focus Search Query and choose to find either:
    • Only those files that cause build errors.
    • Only those files whose properties override the project's properties (for example Language dialect or Compile for debugging settings).

Whichever way you use the Micro Focus search the results are shown in the Search view.

After you have performed a search you can edit the properties of any of the program files listed in the search view. You can even simultaneously edit the properties of multiple program files which have compilation settings available on them, that is program files rather than copybooks or include files. Highlight the files you want to change, right-click Properties, and then check Enable file specific settings. Change the file properties as required and then click OK.

You can save your search criteria and give it a label which is added to the list of stored queries available when you select Search > Run Stored Micro Focus Search Query:
  1. In the Search tab, click [image] Save the Current Search.

    This opens the Add Micro Focus Search dialog box.

  2. In the Search label field, type a search label.
    • You can assign a keyboard shortcut by typing the required keystrokes in the Binding field.
    • Optionally, you can modify the current search criteria.
  3. Click OK.

    The search label is added to the list under Search > Run Stored Micro Focus Search Query.

You can also add, edit, and remove your searches from Window > Preferences > Micro Focus > Search.

Note: Do not open the Keys preferences page (Window > Preferences > General > Keys) while editing the binding in the Search preferences page. Opening the Keys preferences page will prevent any changes you make to the search bindings from being saved.
Parent topic: Tips and Tricks with the IDE


Viewing Copybooks in Context

When you view or edit a copybook, you need to see it in the context of the program that references it, as its appearance and usage can change depending on the program. For example, data items that are not used in the program are struck through, and horizontal lines indicating the start and end of code lines can show depending on the source format of the program. The Program Outline view can differ between contexts too.

If there is an error in the copybook that does not occur in all contexts, it still indicates an error - no matter which context you view it in.

Showing the context

When focus is on a copybook, the Eclipse window's title bar shows the location of the file and the program currently associated with it.

A breadcrumb trail at the top of the Editor indicates which program and copybooks are the current context - click Toggle Context Breadcrumbs [image] in the Eclipse toolbar and use the drop-down list to view and open the dependent copybooks.

You can also check what context a copybook is displaying in by hovering over the tab in the COBOL Editor.

Opening in a context

You can choose which context to open a copybook by right-clicking on the file in Application Explorer view and selecting Open In Context. A list is displayed of all the programs that include a COPY statement referencing the copybook. You can also choose to open the copybook in no particular context.

Whichever you choose becomes the copybook's context whenever you right-click the copybook in Application Explorer view and select Open. It also determines which program it is displayed within when you right-click in the copybook source and select Open in Copy View.

Changing the context

When a copybook is open in the COBOL Editor with a particular context, you can change to a different one by right-clicking in the Editor view and selecting Switch Context. A list is displayed of all the programs that include a COPY statement referencing the copybook.

If a copybook is open in a context and you remove the COPY statement in the referring program (or delete the program), you are prompted to switch context.

Viewing copybook dependencies

By expanding a source file node in Application Explorer view, you can see a list of all copybooks referenced in the source code, and nested within them any other copybooks referenced by those copybooks. Double-click a copybook reference in Application Explorer view to open the copybook file.

Use the Copybook Dependency view to show where in the source file's structure the COPY statements appear, and which copybooks they reference.

Click a copybook reference in the Copybook Dependency view to locate the associated COPY statement at the appropriate line in the source code.

Parent topic: Tips and Tricks with the IDE
Related concepts
Features Added in Enterprise Developer 2.2


Working With a Large Code Base

Traditional COBOL applications often include a large number of source files and make thousands of lines of code.

This document provides general best practice recommendations about how to work with Eclipse and recommendations that will help you make the most of the IDE when working with large applications. It includes advice on how to create and configure your projects, and what to configure in the IDE in order to achieve optimum performance. You can select the configuration that works best for you.

It also includes directions on how you can import your existing legacy applications into Enterprise Developer.

  • Working with Projects and a Large Code Base
  • Accessing Source Code Without a Project
  • Optimizing the Performance of the IDE
  • Configuring Large Projects
  • Large Projects and Remote Development
  • Building Applications in Eclipse
  • Building Applications Outside of Eclipse
  • Best Practice When Upgrading a Legacy Application
  • Steps to Upgrading Your Application
Parent topic: Using Eclipse for COBOL Development


Working with Projects and a Large Code Base

Benefits of using projects

Micro Focus recommends that you create and use Eclipse projects for your source code. There is a number of benefits to using projects, such as:

  • Projects take full advantage of the numerous time-saving and productivity features of the IDE. Features such as Content Assist proposals and syntax checking in the editor are not fully available if you are using the files without a project.
  • Project files store the details of any changes you make in the IDE.
  • The .cobolBuild and .pliBuild project files are Ant files. You can use them to build the files in the project outside of Eclipse - at the command line, in your build scripts or in a CI system.

The following sections include recommendations on how to create and configure your projects, especially when you are working with a large number of files.

Large projects

The definition of a large code base and a large project depends on various factors such as the number and size of files that comprise your application, the complexity and dependencies of the code base as well as the capacity of your machine. A large project could include hundreds or thousands of files and typically you experience performance issues when using Eclipse to load the projects, navigate the source code and when editing, compiling and debugging.

This section of the product help includes a number of recommendations and best practices to help you structure your code in the best possible way and optimize the performance of the IDE when you are working with a large code base.

Structuring your projects

The following list gives tips on how to structure your projects, especially if your applications consist of a large number of files:

Recommendation | Benefits
Create multiple smaller projects and make them dependent on each other, rather than keeping all the code in one very big project.

Smaller projects are:

  • easier to manage
  • quicker to load into the IDE
  • quicker to compile

In addition, keeping your projects smaller helps achieve quicker response times in the editor.

Create projects only for the source files you are working on. | This helps keep your projects smaller.
Create one project per functional area of your application and create dependencies as required. | This helps keep the projects smaller, making it easier to understand the logical structure of your application and edit only those areas that require a change.
Store copybooks and include files outside of the projects for the source code in copybook and include projects You can then add these projects as dependent projects to the build path of other projects that include the source files. Copybook projects are not compiled, thus saving processing time and resources.
  • This improves performance because the IDE does not have to process the copybooks and resolve the file dependencies.
  • This helps keep the project size smaller.
Close projects not in use (click Project > Close Project) | This helps reduce the amount of memory Eclipse uses.
Do not use source files and copybooks from a network drive. | Network drives are remote folders that are mapped to virtual local drives. This is associated with the NFS/Samba connection type which contributes to a slower performance compared with RSE connections. You should either use files from local folders or, if the files are located on a remote machine, create remote projects using the RSE connection type.
Use folders and packages for COBOL JVM applications to organise code within a project | This helps organize and make navigation of the files in your projects easier by creating a hierarchical structure.
Use paths relative to the project location in the project's properties - for example, for paths for the build output, or for linked resources. | This helps make the project portable to other machines.

Limit the number of files stored in a single project

It is hard to provide a strict recommendation for the maximum number of files to store in a single project. This number will depend on many factors related to your particular development scenario such as:

  • Size of the files and of the programs, and their complexity and interdependency
  • Number and size of any copybooks
  • Number of people working on the same project
  • Whether the project is a managed or a native one
  • Whether your applications use incremental linking
  • The existing structure of the source code

Keeping the size of your projects smaller helps avoid various performance issues. As the size of a project increases:

  • The poorer the user experience inside Eclipse
  • The more difficult the project is to manage
  • The longer the times to load and rebuild projects
  • The longer the times to perform background syntax checking, code analysis, or to scan files for Compiler directives (using Determine Directives).

Limit the number of projects stored in a workspace

Micro Focus recommends that you avoid having a large number of projects in your workspace. The reasons are the same as the ones for limiting the number of files within a single project.

It is hard to provide a strict recommendation for the maximum number of projects to store in the workspace. Keeping the number of projects smaller helps avoid various performance issues and improves the times for:

  • Loading the projects in Eclipse
  • Rebuilding the projects, especially when there are dependencies
  • Performing background syntax checking
  • Resolving any references
  • Scanning files for Compiler directives (using Determine Directives)

Use working sets

Create and use working sets within Eclipse to work on and only see a smaller number of projects in your workspace. Working sets enable you to work on and only see a selected number of projects in Eclipse.

You can select to build only the projects that are in the current working set although this will build any project which has a file present in the working set.

See Working Sets for more information.

Make your projects portable

Ensure your projects are easy to share between different development teams:

  • Use relative paths in order to avoid hardcoded paths to the local machines in your projects.
  • Import existing projects into Eclipse with Copy projects into workspace disabled. For example, if you are using a Source Control System (SCM), you will be editing the project in the sandbox rather than a copy of it in the workspace. This helps to ensure you are committing all changes back into the SCM repository.
  • Share any run and debug configurations, and breakpoints - this ensures consistency across the environments of different users. You can keep these in an SCM and share with your development teams.

    To export configurations or breakpoints:

    • Click File > Export > Run/Debug > Launch Configurations or click File > Export > Run/Debug > Breakpoints.

    To import breakpoints

    • Click File > Import > Run/Debug > Launch Configurations or click File > Import > Run/Debug > Breakpoints.

    You can also export a run or a debug configuration in your workspace as follows:

    1. Click Run > Run Configurations.
    2. On the Common tab in the run or debug configuration click Shared file.
    3. Specify the folder in which you want to save the launch configuration and click Apply.

Only link individual files and folders

If linking sources into a project, only link individual source files and folders that will be used and not all of the available source files.

When using linked files, Micro Focus recommends that you create your project in a physical folder which is close on disk to the source files. This reduces the complexity of any relative paths used for linking and makes the projects more portable. Alternatively, create workspace variables that substitute the path to a project to make the configuration easier.

For example, if your source files are in /path/source then create any projects in /path/projects.

Use a Source Control Management system

Micro Focus recommends that you use a source control system, SCM, to store and share your application's sources. Using an SCM has various benefits:

  • It enables multiple users to work on the same code base independently.
  • You are checking out and working on the source code on your local machine. This helps avoid the need to connect to another machine to make changes over a remote connection which might affect the performance.
  • Your projects in the SCM sandbox will be imported in the Eclipse workspace. When you update the sandbox, any changes are directly reflected in the workspace.

See the recommendations for making the projects portable to make working in a shared environment easier.

Parent topic: Working With a Large Code Base


Accessing Source Code Without a Project

As described elsewhere, Micro Focus recommends that you always use projects when using Enterprise Developer, as most of the functionality in Eclipse requires a project file. If you must work without a project, however, this section includes advice on doing so when you have a large number of files.

You can use Eclipse to edit, compile and debug standalone COBOL programs without creating a project file first. This is a quick way to start editing, compiling and debugging your application code in Enterprise Developer. The IDE is preconfigured with the most commonly used Compiler directives for COBOL development. Working with standalone files can be useful when you have a large code base and you only need to edit a small number of the source files.

Open standalone files

To open standalone files in Eclipse:

  1. In Eclipse, click File > Open > File.
  2. Navigate to and select a source file and click Open.

Eclipse offers limited support for developing standalone files compared with the functionality available if you are using a project. See Related Information for information on any restrictions, on which Compiler directives Eclipse uses for standalone files, and for how to compile and debug standalone files.

Parent topic: Working With a Large Code Base
Related concepts
Setting Compiler Directives on Individual Files
Compile for Debugging
Overview of the process of debugging
Related reference
Restrictions When Working With Standalone COBOL Files


Optimizing the Performance of the IDE

Working with a large number of files could affect the performance of Eclipse. There are some tasks and features that you can switch off, if they are not required, to minimize the impact on performance. You can also increase the memory allocation for Eclipse.

These are the areas to consider:

Editing

Working with a large code base could affect the performance of the editor. You can disable some of the IDE settings, especially the ones that are not in use, to help improve the performance.

For example, if you have large source files, you can switch off background parsing in the editor or use a larger Trigger delay - background parsing can generate a significant overhead, especially when dealing with a large code base. See Configuring Background Parsing for how to disable it.

Compiling

To reduce the compilation time and the number of files in a project, ensure that the following project properties are disabled, if you do not need them:

  • On the Micro Focus > Project Settings > COBOL page in the project's properties:
    • Generate directives file
    • Generate listing file
    • Enable code coverage
    • Enable profiler
  • On the Micro Focus > Project Settings > COBOL > Code Analysis page in the project's properties:
    • Run active rule sets after build

See Building Applications in Eclipse for more details.

Disable the automatic directives determination

By default, Eclipse is configured to perform a Compiler directives scan of any files you add to your projects. The automated scanning could slow down the IDE when you have a very large source code base. If you do not want the IDE to perform a directives scan automatically, disable the feature as follows:

  • In Eclipse, click Window > Preferences > Micro Focus > COBOL > Directives Determination.
  • Uncheck Perform automatic directives determination.
  • Do the same for PL/I, from Window > Preferences > Micro Focus > PL/I > Directives Determination.

You can use Determine Directives from the context menu on files to trigger the scan manually and only when needed.

Increase the heap size

To monitor how Eclipse is using memory, turn on the heap visualizer as follows:

  1. In Eclipse, click Window > Preferences > General.
  2. Enable Show heap status.

If you regularly receive out-of-memory exceptions in Eclipse or operations are slow, especially when working with a large code base, you can increase the amount of memory Eclipse can use as follows:

  1. Locate the eclipse.ini file in C:\Users\Public\Micro Focus\Enterprise Developer\eclipse and open it in a text editor.
  2. Use the following options in the file to allocate more memory to Eclipse:
    --launcher.defaultAction openFile
-vmargs
-Xms512m
-Xmx1024m ( or -Xmx3000m)
-XX:+UseParallelGC

Tools

Switch off any functionality that is not in use but can affect performance such as the WTP tools.

Parent topic: Working With a Large Code Base


Configuring Large Projects

Micro Focus has the following recommendations for configuring your projects in Eclipse for a large code base:

Define fewer lookup paths

Ensure only the folders which are required are enabled on the Build Path pages in the project's properties. This reduces the time it takes Eclipse to search for files.

Set Compiler directives at project level

Set Compiler directives at project level rather than at file level where possible. This is because file-level settings override any settings specified at project level settings, and it can be difficult to track, maintain and manage them, especially with a larger code base.

Tip: To access a file's properties when the file is opened in the editor, right-click the code in the editor and click Properties. This would be easier than having to search for the file in COBOL Explorer.

Use the IDE settings to specify Compiler directives

The project's and file's IDE property pages in Enterprise Developer provide a wide range of COBOL and Mainframe Subsystem-specific settings.

The IDE settings are easy to edit and easy to port. Once you use them to configure your projects, they apply both inside Eclipse and when you build the projects outside of Eclipse.

Micro Focus recommends that to set Compiler directives you use the IDE property pages in preference to any other method. Specifically, you should avoid the following:

  • Manually editing the COBOL project file, .cobolProj.
  • Mixing .bat files with build scripts.
  • Manually entering a Compiler directive in Additional directives in either the file or the project's properties, if an IDE setting for the directive exists. Use the GUI setting instead.

    You might end up setting the same directive using both the GUI controls and Additional Directives which could lead to errors.

    For example, you could manually type CICSECM in Additional Directives at the project level. At the same time, it could also be set to None in a file's GUI controls. As a result, there's an ambiguity as to which of the settings actually applies.

    You should only specify a directive in Additional Directives when no corresponding IDE setting exists.

Note: The Determine Directives command sets any required directives on file level only and not at project level. Micro Focus recommends that you move any file directives to project level, if possible, to help avoid any confusion.

Avoid $SET statements in the source files

Avoid setting any $SET statements directly in the source files. Instead, use the project's properties pages inside the IDE to set the corresponding Compiler directive. The reasons for this are:

  • $SET statements in the code are not easily visible, especially when you are working with a large number of files.
  • Eclipse visualizes the directives that are specified at the project or file level. However, it does not show any of the $SET statements that are in the code. This could lead to unexpected behavior, if your source code has any Compiler directives set with $SET statements that are different from the ones set using the GUI properties.

Avoid external files with Compiler directives

Micro Focus recommends that you avoid using any external files (such as .dir) to store any required Compiler directives. The reasons for this are:

  • There is no easy way to see the contents of a .dir file from within Eclipse. In scenarios where there are multiple projects, it is not easy to see which of the projects use a directives file.
  • A mix of directives specified as both projects' properties and in a .dir file could lead to confusion.
Parent topic: Working With a Large Code Base


Large Projects and Remote Development

Micro Focus has the following additional recommendations when you are developing applications with a large code base stored on a remote machine.

Choose the RSE connection type

Micro Focus recommends that you use RSE instead of NFS/Samba as the connection type. This is because NFS/Samba connections, which use a network drive, are substantially slower.

Note: Note that remote mainframe subsystem projects which need to build BMS files do not support the RSE connection type.

If your projects already use the NFS/Samba connection, you can change this to RSE to help improve the performance. To access the connection properties:

  1. Right-click your remote project in COBOL Explorer and click Remote Settings.
  2. See To change the connection type of a remote project for more details.

Avoid using Determine Directives

Avoid using the Determine Directives command to scan your sources and set Compiler directives on files, when the source code is located on a remote machine. This is because directives scanning can be slow over a remote connection.

Copying files to the remote machine

Avoid using Eclipse to copy (using drag and drop or simply copying) a large number of files from your local machine to the remote one. This operation in the IDE could take a long time. Use a tool such as RCP or FTP to do this and then add your sources to the remote project.

You can, however, use the Remote System Explorer view that has a built-in SFTP functionality.

Use Source Control Management

To improve the performance, Micro Focus recommends that you store and use the source files from a Source Control Management (SCM) system and not access them over a remote connection.

You check out the sources on your local machine and work with local projects avoiding any downtime created by the remote connection. You then check the changed sources back into the SCM. To deploy the changes to the remote machine you update the SCM sandbox.

Parent topic: Working With a Large Code Base
Related tasks
To change the connection type of a remote project


Building Applications in Eclipse

The following recommendations can help improve the performance of Eclipse when you use it to build large applications:

Disable automatic builds

Micro Focus recommends that you disable automatic builds so changes you make to your projects or in the code do not start a build automatically:

  • Click Project and uncheck Build Automatically.

Only build selected files or selected projects

Avoid building all projects in your workspace or all files within the project.

To build only selected projects:

  1. Ensure automatic builds are switched off.
  2. Select one or more projects in COBOL Explorer, right-click the selection and click Build Project.

To build only selected files:

  1. Ensure automatic builds are switched off.
  2. Select one or more files in your project, right-click the selection and click Compile.

Configure Eclipse to clean and build only selected projects:

  1. Click Project > Clean.
  2. Uncheck Clean projects selected below.
  3. Ensure Start a build immediately is checked and click Build only the selected projects.
  4. Select the projects that you want to rebuild.

Do not rebuild all artifacts

Configure Eclipse so it does not delete the build artefacts when you change the project's properties settings. This means you will not have to rebuild the project and build all artifacts.

  1. Click Window > Preferences > Micro Focus > Builder
  2. Set Delete build artifacts in output folder when project settings change to Prompt.
Warning: Switching this option off means that some of the project's settings might not be reflected in the build artefacts. Ensure that you rebuild any artefacts when you need to use them.

Build native COBOL projects in parallel

On multi-CPU machines, you can enable faster, parallel multi-processor compilation of multiple files in native COBOL projects. To do this:

  1. Click Window > Preferences > Micro Focus > Builder.
  2. Specify a number for "Maximum compilations/links to execute concurrently in Set Multi-processor compilation/linking that correspond to the number of CPUs.

See Building COBOL Applications for more information.

Build COBOL JVM applications incrementally

You can configure a JVM COBOL project to build incrementally meaning Eclipse builds only the files that have changed, so reducing the build overhead.

See Compiling JVM COBOL for details on how to enable incremental builds.

Build without code coverage or profiler information

If not needed, do not build your applications with code coverage or profiler information as these settings mean the builds take longer to complete. Note that changing these settings in the project will trigger a project build if Eclipse is configured to build projects automatically.

Parent topic: Working With a Large Code Base
Related concepts
Building COBOL applications
Compiling JVM COBOL


Building Applications Outside of Eclipse

The .cobolBuild and .pliBuild project files are built using Apache Ant. You can use external build scripts such as makefiles, shell scripts and others with an Ant build script to build one or more projects outside of Eclipse.

The benefits of this are:

  1. It helps avoids building in Eclipse and any memory restrictions that might arise from the fact that you are building a very large code base.
  2. If the scripts already exists, it means less configuration work to set the builds up.

Build using scripts

When using scripts to build a project outside of Eclipse, Micro Focus recommends that you disable its builder in Eclipse so that the IDE does not build it. To do this:

  1. In Eclipse, right-click the project that you do not want to build inside the IDE.
  2. Click Properties > Builders, and uncheck Micro Focus Project Builder.

If you do not disable the builder, there might be situations in which both Eclipse and the external scripts build the same project. If you refresh the project inside Eclipse, it will pick up the build output files that were changed outside of the IDE. Since the files are different, IDE then triggers a rebuild of the project which can cause a slowdown. To avoid this you can configure the external build scripts to produce the build output in a different location from the project's output directory.

Build in parallel or incrementally

You can compile your source code faster on multi-CPU machines if you use parallel compilation. You can also build JVM COBOL applications incrementally. See To Build a Project Using Apache Ant.

Parent topic: Working With a Large Code Base
Related tasks
To Build a Project Using Apache Ant


Best Practice When Upgrading a Legacy Application

There are different ways in which you can start using Enterprise Developer to develop your applications created with a legacy Micro Focus product such as Net Express, Server Express, or Mainframe Express.

The quickest approach would be to open individual files in Eclipse and use the IDE to edit, compile and debug them. The approach that Micro Focus recommends is to create a project and take advantage of the many project-handling features offered by Enterprise Developer.

The following sections highlight stages of the development process where Micro Focus has recommendations about the best way to proceed when upgrading large projects.

Create a project for your source code

Regardless of whether you have used a project file before, Micro Focus recommends that you create one or more projects in Enterprise Developer for your application files. Using a project file means all of the Eclipse productivity features will be available to you. See Working with Projects for more information.

If you have a Net Express project for your application, note the following:

  • Eclipse projects are not direct mappings of existing Net Express projects.
  • A convenient way to import the project into Eclipse is to use the Net Express Project Import wizard. The wizard analyzes your existing Net Express projects, creates a solution with one or more projects and sets any Compiler directives that were used in the Net Express project.
  • The wizard helps you quickly and easily move your sources from Net Express to Eclipse. It might not create a perfectly-optimized project, and you might need to rethink and restructure the initial Eclipse projects once you have moved your source files to them.

Import your sources into an Eclipse project

Use one of the following approaches to to create Eclipse projects and add your source files to them:

  • Use the Net Express Project Import wizard - uses an existing Net Express project. Analyzes the project, creates one or more Eclipse projects that use the settings used in Net Express, and adds source files to them.
  • Create an Eclipse project and add your source files to them.

Choosing a project type

Enterprise Developer provides the following project types:

Eclipse project type | Description
COBOL project | Choose this type for your existing legacy applications that do not use Mainframe Subsystem Support.
COBOL JVM project Choose this project type if you want to take advantage of the functionality of the JVM and extend your applications.

Your existing native COBOL applications should compile in a managed (JVM) COBOL project without any changes required.

The benefits of switching to a managed project include:

  • The JVM COBOL dialect makes more COBOL language features adapted for the JVM available to you.
  • Easier interaction with other managed languages such as Java.
  • The ability to take advantage of a number of widely-used Java framework features.
Restriction: Code analysis is not available in managed projects.
Mainframe COBOL Project | Choose this type if your legacy application uses Mainframe Subsystem Support such as CICS, IMS, BMS, Assembler or any other mainframe components.

Using tabs in your files

Tab size in legacy Micro Focus products (such as Net Express) defaulted to eight spaces while it is four spaces by default in Eclipse. This means that you might get Compiler errors when you try to compile your COBOL sources in Enterprise Developer.

If you have your application's Net Express project, you can use the Net Express Project Import wizard in Enterprise Developer to upgrade the application. The wizard automatically converts the tabs to four spaces.

You can also convert tabs to spaces in one of the following ways:

  • Ensure that on the Windows > Preferences > Micro Focus > COBOL > Editor page, Insert spaces for tabs is enabled. When you import files into Eclipse, the tabs will be converted automatically.
  • Set the SOURCETABSTOP"4" Compiler directive that converts tabs to four spaces.
  • Click Source > Convert Tabs to Spaces from the main menu when the file is open in the editor.

Do not change the size of the tabs in the Eclipse preferences, as these preferences apply to all other programming languages you might be working on in the IDE.

Micro Focus recommends that you use spaces instead of tabs in Enterprise Developer.

Rename variables that are now reserved words

Micro Focus continues to enhance the COBOL language. New Micro Focus product releases use newer levels of the COBOL language where each level has new words added to the list of reserved COBOL keywords.

When you are upgrading an application from a product that uses an earlier level of the COBOL language, you might find that some of the variable names are now reserved words. See the Upgrade Guide for how you can solve this problem.

To avoid confusion, Micro Focus recommends that you rename the variables whose names are now reserved words.

Functionality not supported in Enterprise Developer

Note that some functionality that was available in older Micro Focus products might work differently or be superseded in Enterprise Developer. See Differences between Enterprise Developer and Net Express and Mainframe Express in the Upgrade Guide for more.

Parent topic: Working With a Large Code Base


Steps to Upgrading Your Application

The following steps describe an example process of importing your existing source files into Eclipse:

Tip:
  • If your application consists of a large number of files, consider starting by creating a project solely for the source files you are working on.
  • You can add any non-COBOL files (such as data files, HTML pages) to your projects. This enables you to edit and build them inside the IDE. However, if there are a lot of them, Micro Focus recommends you only add the files that are frequently used in your project.
  1. Organise your application's source code outside of Eclipse.

    Micro Focus recommends that you create a logical folder structure where individual folders store files of the same type such as:

    • source files
    • shared copybooks
    • binaries
    • data files
    Note:
    • Consider creating folders to group any logical components that can form projects.
    • Organize the folders in such a way that it is easy to use relative paths in your projects.
    • Make a note of any dependencies in your source code.
    • If it is not possible to store the source code in individual folders, make a note of any files you need to link to from your projects.
    • Plan for how to organize your code in separate projects.
  2. Disable the automatic builds in Eclipse to avoid rebuilding the entire workspace when adding files or making any changes.
  3. Start creating projects:
    1. Click File > New and select the project type.
      Tip: Use the COBOL Copybook or PL/I Include project for projects that are only going to store copybooks or include files.
    2. In the new project wizard, uncheck Use default location and specify the location where you want to store the project, outside of the Eclipse workspace.

      If the location specified is an existing folder, it will be turned into a project that contains all files and folders contained within it. This is useful if you have already created folders that represent the projects you want to create.

  4. In the project's properties (click Project > Properties) specify relative paths for the following:
    • Source files
    • Copybooks - go to the Copybooks page in the properties
    • Build output - specify in Output path on the COBOL page in the properties
  5. Add files to projects using one of the following methods:
    • Copying or linking - if you link the files, then they remain in their original location and are not copied into the project folder. You can use relative paths in order to make the projects portable.
    • Drag-and-drop - use this to move one or more files to your project. You can choose whether to copy the files or create links for them.

      Avoid using this for a large number of files as this can make the IDE unresponsive.

    • Importing - click File > Import > General > File System. Navigate to a folder and specify the files to import in your project. You can either copy or link to the files.

      Use the PROJECT_LOC environment variable to help make your project easily portable.

      This is the preferred method when your application has a large number of files or when the files to add to a single project are spread across multiple folders under a shared parent.

  6. Use the Determine Directives command on the projects, if necessary.

    Note that any required Compiler directives will be set on individual files and not at the project level which might be confusing. If the directives safely apply to all of the files in the project, you can disable automatic directives determination and set the directives manually at the project level.

  7. Add any non-COBOL files (such as data or HTML files) to your project so you can easily edit them in Eclipse. If there is a large number of these files, you can add only the ones that are frequently used to your project.

    If you do not want to store these files in the project folder, you can store and use them from a folder outside of the project folder.

    You can use filters to hide these files from the Explorer view and remove them from the project - right-click the project and click Properties > Resource > Resource Filters > Add Filter.

Parent topic: Working With a Large Code Base


Creating COBOL Projects

  • Creating and importing COBOL projects
  • Creating and importing resources
  • Using source files from outside your project
  • To create a project or a file from a custom template
  • Indicating Whether a File is a Copybook or a COBOL Program
  • Configuring the Project, Build Configuration and File Properties
  • Developing applications on remote machines
Parent topic: Developing Applications in the IDE
Related concepts
Using Eclipse for PL/I development


Creating and importing COBOL projects

  • To create a COBOL project
  • To import an existing Eclipse project
    To load existing Eclipse projects in the IDE, you need to import them into the Eclipse workspace.
  • Creating service interface projects
  • Converting Net Express projects to Eclipse projects
    The Import and Convert NetExpress Projects wizard enables you to convert existing Net Express projects into Eclipse projects so you can use them with Enterprise Developer. The wizard analyzes the Net Express project file and its configuration settings, creates Eclipse projects based on this information, imports the existing source code into them and sets the requisite project and file properties from the original Net Express project.
  • To load projects into the Team Developer perspective
Parent topic: Creating COBOL Projects
Related concepts
Developing applications on remote machines
Creating a PL/I project
Related information
Creating and importing resources
Using source files from outside your project
To create a project or a file from a custom template
Indicating Whether a File is a Copybook or a COBOL Program
Configuring the Project, Build Configuration and File Properties


To create a COBOL project

To create a COBOL project:

  1. While in the Team Developer perspective, click File > New > Other.
  2. In the New dialog box, expand Micro Focus COBOL.
  3. Click COBOL Project, and then click Next.
  4. In the New COBOL Project dialog box, type a project name.
  5. Select a project template, if required. Alternatively, check Browse for template and type the location or click Browse to navigate to the location of the template.
    Note: By default, two templates are available for you to choose from Micro Focus template [32 bit] or Micro Focus template [64 bit]. Select a template that best suits your requirements.
  6. In the Location field, type the path of the project or click Browse and use the Browse For Folder dialog box to browse the file system.
  7. Click Finish.

    The project is created and appears in the Application Explorer view.

Parent topic: Creating and importing COBOL projects
Related information
To import an existing Eclipse project
Creating service interface projects
Converting Net Express projects to Eclipse projects
To load projects into the Team Developer perspective


To import an existing Eclipse project

To load existing Eclipse projects in the IDE, you need to import them into the Eclipse workspace.

To import a project stored on your local machine or on a remote machine when you are using the network file system (NFS):

  1. Click File > Import > General.
  2. Click Existing Projects into Workspace.

    You can edit the project directly in its original location or choose to create a copy of the project in the workspace.

If you are importing a remote project and you use the remote file system (RSE):

  1. Before you start the import, Enterprise Developer create a remote connection to be used to access the remote server.

    This must be the connection that was used to create the remote project.

  2. Click File > Import > Micro Focus > Remote Projects.
  3. Click Browse.
  4. Set Connection to the appropriate connection name.
  5. Select the directory that contains the projects you want to import.
  6. Click Finish.

    This imports the projects into the current workspace and loads them in the IDE.

Restriction: It is not possible to import remote mainframe projects using RSE.
Parent topic: Creating and importing COBOL projects
Related information
To create a COBOL project
Creating service interface projects
Converting Net Express projects to Eclipse projects
To load projects into the Team Developer perspective


Creating service interface projects

The Interface Mapper is the tool that enables you to define your service interfaces. You can define a service interface for a COBOL application from the COBOL source code. The service interfaces you define can cover a broad range – from those that provide access to a subset of the functions performed by your application, to interfaces that do more than your application in its original form. This is done by associating, or "mapping", the fields in your legacy application to the fields you create in the service interface.

In order to use the service interfaces feature, you must first create a native COBOL project configured to support them. Once this project is in place, you use Eclipse IDE functionality to do the following:

  • Add your COBOL application files to the project, such as COBOL programs and copybooks: right-click your project and choose New > COBOL Program or COBOL Copybook.
  • Create and edit a service interface: right-click your project and choose New > Other > Micro Focus IMTK > Java Interface or Web Service.
  • Import an existing service interface, either a service interface created using different software such as Net Express or a service interface from a different project right-click project and choose Import > Import > Micro Focus Interface Mapper > Service Interfaces.
  • Deploy service interfaces to run as services on an enterprise server: right-click a service interface and choose Deploy.
  • Generate clients to access deployed services: right-click service interface and choose Generate Client.

The Interface Mapper user interface for COBOL Program service interfaces is split into two parts. The left side shows COBOL LINKAGE section fields, and the right shows interface fields, reusable fields, and COBOL assignments.

Parent topic: Creating and importing COBOL projects
Related information
To create a COBOL project
To import an existing Eclipse project
Converting Net Express projects to Eclipse projects
To load projects into the Team Developer perspective


Converting Net Express projects to Eclipse projects

Overview

Restriction: This topic applies to Windows environments only.

The Import and Convert NetExpress Projects wizard enables you to convert existing Net Express projects into Eclipse projects so you can use them with Enterprise Developer. The wizard analyzes the Net Express project file and its configuration setting. It then creates the required Eclipse projects, imports the source files into them and sets the required project and file properties from the original Net Express project for one of its build types.

  • Net Express projects can have different types of build, each one of which could include different files and different project and file-level settings. Eclipse projects only support one set of file settings that are used for all build configurations. Because of this, the Import and Convert NetExpress Projects wizard only imports the files and settings for one build type of a Net Express project at a time. This build type is used as the default build configuration for the new Eclipse project. If the project includes more than one build type, you need to repeat the import process to create Eclipse projects that have the set of files and settings for the other build types.
  • An Eclipse project can have only one target type per build configuration, so if the Net Express project builds into more than one target types, the wizard suggests to create multiple Eclipse projects.
  • The wizard creates a single Eclipse project for all the .int and .gnt targets produced by the Net Express project, and the Target Type for this Eclipse project is set as All Int/Gnt Files.
The properties that are set during the import include:
  • the type of application that is being built, such as a console application or a library
  • the paths for copybooks that aren't in known locations such as the project directory, and the cpylib folder in the installation
  • the Compiler directives and build settings
  • how the application starts, such as any command line arguments

If the Net Express project builds more than one type of target, the wizard suggests the creation of multiple Eclipse projects.

Tip: If you have any questions or comments about the Import and Convert NetExpress Projects wizard or upgrading to Enterprise Developer, please use the Micro Focus Community pages (http://community.microfocus.com/) to get in touch with us and other Enterprise Developer users.

To import a Net Express project into Eclipse

  1. Ensure that your Net Express project and all relevant files are available and in one location.
  2. In the Eclipse IDE, click File > Import, expand Micro Focus, click Convert NetExpress Projects, and click Next.
  3. In the Import and Convert NetExpress Projects dialog box, click Browse to navigate to and select the Net Express project you want to convert.

    If your Net Express project built to .int and .gnt files, you can change the target types so that you have just .dll and .exe build configurations. To do this, check Upgrade projects to use executable/library targets.

  4. Click Finish.

    The wizard analyzes the Net Express project and lists the Eclipse projects it will create, which Net Express Type of Build will be used for the new projects, and the file settings that will be used.

    You can change the target type at any time after you have converted the project. If you don't want a project for a particular build target (for example, if you want to use a debug configuration instead of having a separate project for an .int file in the Net Express project), you can choose not to create a project from that target.

  5. For each Eclipse project, verify that the Net Express type of build is the one you want to use as a basis for the new project.
  6. Click OK.

    Depending on the build configurations and the target types of the Net Express project, the wizard creates one or more Eclipse projects and a conversion report file in a new folder, eclipse, in the same directory as the Net Express project folder. The source files of the Net Express project are not copied into the eclipse folder. They are stored in the Net Express folder and are linked to from the Eclipse projects.

If your Net Express project uses resource files, you should move the files from the MainProjectSource group in COBOL Explorer to the relevant new Enterprise Developer project folder.

Note: Resource files provide a way of adding non-executable binary data such as bitmaps, cursors and menus to an executable file. Within these files the data can be stored in full, or indirectly as a pointer to another named file that contains the actual data. Resource files have the extension .rc.

Restrictions and limitations

  • The following Net Express Compiler directives are obsolete and are ignored during the import:
    • 01SHUFFLE
    • 64KPARA
    • 64KSECT
    • AUXOPT
    • CHIP
    • COBIDY
    • DATALIT
    • EANIM
    • EDITOR
    • ENSUITE
    • EXPANDDATA
    • FIXING
    • FLAG-CHIP
    • MASM
    • MODEL
    • OPTSIZE
    • OPTSPEED
    • PARAS
    • PROTMODE
    • REGPARM
    • SEGCROSS
    • SEGSIZE
    • SIGNCOMPARE
    • SMALLDD
    • TABLESEGCROSS
    • TRICKLECHECK
    • WB2
    • WB3
    • WB
  • The pseudovariables of the following Net Express environment variables are obsolete and are ignored during the import:
    • BASENAME
    • FILENAME
    • PATH
    • TARGETDIR
    Other pseudovariables are replaced with the closest possible value and any substitutions are reported in the log file.
  • If you import a Net Express project that uses functionality that is not supported in Enterprise Developer, the wizard still produces an Eclipse project. In some cases you might be able to perform additional steps (such as editing source files, installing AddPacks, or reworking parts of the application) in order to successfully compile and run it.

For more on migrating Net Express applications to Enterprise Developer, see Upgrading to Enterprise Developer.

Parent topic: Creating and importing COBOL projects
Related information
To create a COBOL project
To import an existing Eclipse project
Creating service interface projects
To load projects into the Team Developer perspective


To load projects into the Team Developer perspective

  1. In Eclipse, open the Team Developer perspective.
  2. Anywhere in the Application Explorer view, right click; then select Add Systems from the context menu.
  3. Select ED System; then click OK.
  4. In the Application Explorer view, expand Enterprise Developer@Windows.
  5. Right-click Enterprise Development Projects; then select Load Application from the context menu.
  6. Expand Enterprise Development Projects to view the loaded projects.
Parent topic: Creating and importing COBOL projects
Related information
To create a COBOL project
To import an existing Eclipse project
Creating service interface projects
Converting Net Express projects to Eclipse projects


Creating and importing resources

  • To create a new file
  • To create a new file from a custom template
  • To import a file into a project
  • To import a copybooks into a virtual folder
  • To associate a file extension with COBOL
  • Extracting COBOL code to a copybook
  • To create a COBOL JVM Enum type
  • To create a COBOL JVM Delegate
  • To create a COBOL JVM Value type
Parent topic: Creating COBOL Projects
Related concepts
Developing applications on remote machines
Related information
Creating and importing COBOL projects
Using source files from outside your project
To create a project or a file from a custom template
Indicating Whether a File is a Copybook or a COBOL Program
Configuring the Project, Build Configuration and File Properties


To create a new file

To add new files to the project, click File > New and specify the type of file you want to create - such as a COBOL program or a copybook.

If you are creating a new COBOL class or an interface in a COBOL JVM Project, you also need to specify the following details:

  1. Specify the path to the source folder in which you want to create the class or the interface.
  2. Specify the name of the package.
  3. Specify a name for the class or the interface.
  4. Specify a modifier - either public or internal (visible only inside the package) and, additionally, for classes check either abstract, final, or static.
  5. If you are creating a class, optionally click Browse next to the Superclass field and select an appropriate class.
  6. Click Add and specify the interfaces the new class or interface inherits.
  7. Click Finish.
Parent topic: Creating and importing resources
Related information
To create a new file from a custom template
To import a file into a project
To import a copybooks into a virtual folder
To associate a file extension with COBOL
Extracting COBOL code to a copybook
To create a COBOL JVM Enum type
To create a COBOL JVM Delegate
To create a COBOL JVM Value type


To create a new file from a custom template

You can create new files in your project using your own file templates. See Using custom project and file templates for details about how to create file templates.

To create a file from a template:

  1. Right-click your project in COBOL Explorer, click New and either specify COBOL Program or COBOL Copybook.
  2. Specify a name for the file in the New file name field.
  3. Select the template you want to use.

    The dialog shows the default Micro Focus template and any custom templates you might have enabled.

    • If you have not configured the IDE to use custom templates, click Configure template preferences. This starts the Preferences dialog that enables you to specify any custom templates to use.
    • If you want to use another existing file as a template, check Browse for template and click Browse to navigate to the location of the file and to select it.
  4. Click Finish to create the new file in your project.
Parent topic: Creating and importing resources
Related information
To create a new file
To import a file into a project
To import a copybooks into a virtual folder
To associate a file extension with COBOL
Extracting COBOL code to a copybook
To create a COBOL JVM Enum type
To create a COBOL JVM Delegate
To create a COBOL JVM Value type


To import a file into a project

Follow these steps to import files into your project:

  1. Select your project in COBOL Explorer.
  2. Click File > Import.
  3. Click File System and click Next.

    You can choose to import files from a remote server and either copy the project into your workspace or refer to it in its existing location.

Alternatively, you can:

  • Use the file system or Windows Explorer to copy existing COBOL files into your project folder.
  • Link to the source files, rather than importing them into the project. To do this, click File > New > Other > General > File and follow the wizard.
Parent topic: Creating and importing resources
Related information
To create a new file
To create a new file from a custom template
To import a copybooks into a virtual folder
To associate a file extension with COBOL
Extracting COBOL code to a copybook
To create a COBOL JVM Enum type
To create a COBOL JVM Delegate
To create a COBOL JVM Value type


To import a copybooks into a virtual folder

You can import copybooks into a virtual folder of your project:

  1. Select your project in COBOL Explorer.
  2. Click File > Import.

    This opens the Import dialog box.

  3. Expand General and click File System, then click Next.
  4. Click Browse and navigate to the directory that contains the copybooks you want to import.
  5. Click OK.
  6. In the Import dialog box, check the copybooks to be imported.
  7. Check Create top-level folder under Options.
  8. Click Advanced.
  9. Check Create links in workspace.
  10. Ensure Create virtual folders is checked.
  11. Click Finish.

To ensure the project builds successfully, you must also add the location of the copybooks to the project's dependencies:

  1. Navigate to Micro Focus > Build Path in the project's properties.
  2. Click the Dependency Paths tab and check the folder that includes the imported copybooks.
Parent topic: Creating and importing resources
Related concepts
Dependency Paths
Related information
To create a new file
To create a new file from a custom template
To import a file into a project
To associate a file extension with COBOL
Extracting COBOL code to a copybook
To create a COBOL JVM Enum type
To create a COBOL JVM Delegate
To create a COBOL JVM Value type


To associate a file extension with COBOL

Enterprise Developer is pre-configured to associate certain file extensions as specific COBOL file types. For example, the following extensions are recognized as COBOL programs - .cbl, .cob, .eco, .pco or .sqb; .cpy and .cbl are recognized as copybooks.

To add file associations for other file extensions:

  1. In the IDE, click Window > Preferences.
  2. Choose General > Content Types.
  3. In the Content type pane, expand Text and click Micro Focus Project Types.
  4. Click on any of the types prefixed COBOL in the list to see which file extensions are associated with that particular type.
  5. To associate a new extension with any particular type, click Add, specify the Content type and then click OK.
Parent topic: Creating and importing resources
Related information
To create a new file
To create a new file from a custom template
To import a file into a project
To import a copybooks into a virtual folder
Extracting COBOL code to a copybook
To create a COBOL JVM Enum type
To create a COBOL JVM Delegate
To create a COBOL JVM Value type


Extracting COBOL code to a copybook

To help reduce data structure duplication across your COBOL applications you can extract a block of COBOL code to a copybook. To extract the code, perform the following steps:

  1. In the COBOL editor, highlight the lines that you want to extract to a copybook.
  2. Right-click in the COBOL editor, and then click Refactor > Extract to Copybook. Alternatively, from the main menu, click Refactor > Extract to Copybook.

    This opens the Extract to Copybook dialog box where Containing project contains the current project.

  3. In the New file name field, type a copybook file name with either a .cpy or .cbl file extension.
  4. Optionally, click Preview to view the changes to be performed. In the Changes to be performed pane, you are presented with a list of the actions to be taken. By default, all actions are checked. You can uncheck actions to obtain the required results. Clicking on the actions displays the result of the actions in the Original Source and Refactored Source panes.
  5. Click OK.

    By default this extracts the highlighted source code to the specified copybook and refactors the original source, leaving a COPY statement referencing the newly-created copybook.

Parent topic: Creating and importing resources
Parent topic: Code Refactoring
Related concepts
Writing Code Efficiently in the COBOL Editor
Related information
To create a new file
To create a new file from a custom template
To import a file into a project
To import a copybooks into a virtual folder
To associate a file extension with COBOL
To create a COBOL JVM Enum type
To create a COBOL JVM Delegate
To create a COBOL JVM Value type


To create a COBOL JVM Enum type

A COBOL JVM Enum type is a data type that enables you to specify a variable to be a set of predefined constants.

To create a COBOL JVM Enum type:

  1. Click File > New > Other.

    This opens the New dialog box.

  2. Click Micro Focus COBOL > COBOL JVM Enum, and then click Next.

    This opens the New COBOL JVM Enum dialog box.

  3. In the Source folder field, type the path to the source folder you want to use. Alternatively, click Browse to navigate to a source folder.
    Note: By default, the Source folder field contains the source folder of the element that was selected when the wizard was started.
  4. In the Package field, type the path to the package to be used. Alternatively, click Browse to choose a package.
    Note: Micro Focus recommends that you do not use the default package.
  5. In the Name field, type a name for the COBOL JVM Enum type.
  6. Select an access modifier for the new COBOL JVM Enum type. This can be either public or internal.
  7. Click Finish.

    This creates a COBOL file and opens it in the COBOL editor.

Parent topic: Creating and importing resources
Related information
To create a new file
To create a new file from a custom template
To import a file into a project
To import a copybooks into a virtual folder
To associate a file extension with COBOL
Extracting COBOL code to a copybook
To create a COBOL JVM Delegate
To create a COBOL JVM Value type


To create a COBOL JVM Delegate

A COBOL JVM Delegate type is a data type that refers to method. The delegate must have a signature and return type compatible with the method being referenced.

To create a COBOL JVM Delegate type:

  1. Click File > New > Other.

    This opens the New dialog box.

  2. Click Micro Focus COBOL > COBOL JVM Delegate, and then click Next.

    This opens the New COBOL JVM Delegate dialog box.

  3. In the Source folder field, type the path to the source folder you want to use. Alternatively, click Browse to navigate to a source folder.
    Note: By default, the Source folder field contains the source folder of the element that was selected when the wizard was started.
  4. In the Package field, type the path to the package to be used. Alternatively, click Browse to choose a package.
    Note: Micro Focus recommends that you do not use the default package.
  5. In the Name field, type a name for the COBOL JVM Delegate type.
  6. Select an access modifier for the new COBOL JVM Delegate type. This can be either public or internal.
  7. Click Finish.

    This creates a COBOL file and opens it in the COBOL editor.

Parent topic: Creating and importing resources
Related information
To create a new file
To create a new file from a custom template
To import a file into a project
To import a copybooks into a virtual folder
To associate a file extension with COBOL
Extracting COBOL code to a copybook
To create a COBOL JVM Enum type
To create a COBOL JVM Value type


To create a COBOL JVM Value type

A COBOL JVM Value Type enables you to specify your own primitive types.

To create a COBOL JVM Value type:

  1. Click File > New > Other.

    This opens the New dialog box.

  2. Click Micro Focus COBOL > COBOL JVM Value Type, and then click Next.

    This opens the New COBOL JVM Value Type dialog box.

  3. In the Source folder field, type the path to the source folder you want to use. Alternatively, click Browse to navigate to a source folder.
    Note: By default, the Source folder field contains the source folder of the element that was selected when the wizard was started.
  4. In the Package field, type the path to the package to be used. Alternatively, click Browse to choose a package.
    Note: Micro Focus recommends that you do not use the default package.
  5. In the Name field, type a name for the COBOL JVM Value Type.
  6. Select an access modifier for the new COBOL JVM Value Type. This can be either public or internal.
  7. Select an interfaces that the COBOL JVM Value Type implements:
    1. Click Add.

      This opens the Implemented Interfaces Selection dialog box.

    2. In the Choose interfaces field, start typing the name of the interface you want to use. This creates a list of interface names in the Matching items list.
    3. In the Matching items list, click the interface names you want to use.
    4. Click OK.
  8. Click Finish.

    This creates a COBOL file and opens it in the COBOL editor.

Parent topic: Creating and importing resources
Related information
To create a new file
To create a new file from a custom template
To import a file into a project
To import a copybooks into a virtual folder
To associate a file extension with COBOL
Extracting COBOL code to a copybook
To create a COBOL JVM Enum type
To create a COBOL JVM Delegate


Using source files from outside your project

You can create links to sources that are outside the project, thereby saving you from copying the sources into the project, and enabling to share resources with others. Linking to COBOL copybooks or copybook projects can be useful, particularly if the copybooks are used by multiple projects.

Project dependencies

When a project uses sources from another project or build artefacts generated by another project, the project that contains the sources or generates the artefacts is referred to as a project dependency of the project that uses them.

COBOL projects can depend on other COBOL projects. Java projects can depend on Java and JVM COBOL projects. JVM COBOL projects can depend on JVM COBOL and Java projects.

There are two main types of project dependencies.

Source dependency
When Project A uses a source (a copybook, for example) from Project B, Project B is a dependency of Project A and the dependency created is a source dependency.

When you add a dependant project (Project B) all its copybook paths are added to the copybook paths of the project (Project A) and thus allows using any copybook from Project B in Project A.

Build artefacts dependency
When Project A uses build artefacts from Project B, Project B is a dependency of Project B and the dependency is called build artefacts dependency.

An example of build artefact dependency is when an .exe file from Project A loads a .dll from Project B at runtime or when an .exe file from Project A links statically a .dll from Project B.

Regardless of the dependency type, the build order of the projects changes automatically to ensure that dependent projects will be built first. Thus when Project B is a dependency of Project A, Project B is built first. This is needed to ensure that the build artefacts of Project B are up-to-date before Project A uses them.

To check the build order open Window > Preferences > General > Workspace > Build Order.

Linking to copybooks or sources

Tip: Linked resources are an Eclipse concept and are supported for COBOL projects, but Micro Focus recommends you use project dependencies where possible, and create projects to contain the resources and define an appropriate dependency between them.

You can link to individual source files and to folders containing sources. You can specify absolute paths to the sources. Alternatively, you can use a variable to define a path and then you can link to sources using a relative path. Linked resources like these show in the project in the COBOL Explorer as file icons decorated with a square with an arrow link.

In addition, you can create a copybook project or remote copybook project, and link to the project rather than individual copybooks it contains.

You can define the order in which folders and projects are searched for copybooks, by defining it in the project's properties.

Linked resources are built in the background, just like other files in the project. You can see this happening in the COBOL Build console. As with any other file, you can choose to ignore linked resources when you build.

  • To create project dependencies
  • To remove project dependencies
  • To link to copybooks or sources outside the project
  • To link to mainframe locations
Parent topic: Creating COBOL Projects
Related concepts
Developing applications on remote machines
Related information
Creating and importing COBOL projects
Creating and importing resources
To create a project or a file from a custom template
Indicating Whether a File is a Copybook or a COBOL Program
Configuring the Project, Build Configuration and File Properties
Order in Which Copybooks are Searched For


To create project dependencies

CAUTION:
Circular or missing dependency definitions cause a build error. You need to fix the error before you proceed with the build.

To create project dependencies for a native COBOL project

  1. Select your project in Application Explorer view.
  2. On the Project menu, click Properties.

    The Properties for <project-name> dialog box appears.

  3. Click Micro Focus > Build Path.
  4. Click the Projects tab.
  5. Click Add.

    A dialog box containing all compatible projects appears.

    Note: Local projects can use sources and build artefacts only from other local project(s). Remote projects can use resources only from remote projects that are using the same remote connection.
  6. Select the projects containing the resources needed to build the current project, then click OK.
  7. Click OK on the Properties for <project-name> dialog box to save the changes.

To create project dependencies for a JVM COBOL project

  1. Select your project in Application Explorer view.
  2. On the Project menu, click Properties.

    The Properties for <project-name> dialog box appears.

  3. Click Micro Focus > JVM Build Path.
  4. Click the Projects tab.
  5. Click Add.

    This displays a dialog box with all compatible projects.

    Note: Local projects can use sources and build artefacts only from other local project(s). Remote projects can use resources only from remote projects that are using the same remote connection. JVM COBOL projects can use sources and build artifacts from other JVM COBOL projects as well as from Java projects.
  6. Select the projects containing the resources needed to build the current project, then click OK.
  7. Click OK on the Properties for <project-name> dialog box to save the changes.
Parent topic: Using source files from outside your project


To remove project dependencies

To remove project dependencies from a native COBOL project

  1. Select your project in Application Explorer view.
  2. On the Project menu, click Properties.

    The Properties for <project-name> dialog box appears.

  3. Click Micro Focus > Build Path .
  4. Click the Projects tab.
  5. Select the project you want to remove from the list of project dependencies, then click Remove.

    The selected project dependency is removed.

  6. Click OK on the Properties for <project-name> dialog box to save the changes.

To remove project dependencies from a JVM COBOL project

  1. Select your project in Application Explorer view.
  2. On the Project menu, click Properties.

    The Properties for <project-name> dialog box appears.

  3. Click Micro Focus > JVM Build Path.
  4. Click the Projects tab.
  5. Select the project you want to remove from the list of project dependencies, then click Remove.

    The selected project dependency is removed.

  6. Click OK on the Properties for <project-name> dialog box to save the changes.
Parent topic: Using source files from outside your project


To link to copybooks or sources outside the project

Important: Linked resources are an Eclipse concept and are supported for COBOL projects, but Micro Focus recommends you use project dependencies where possible, and create projects to contain the resources and define an appropriate dependency between them.

You can link to individual source files and to folders containing sources. You can specify absolute paths to the sources. Alternatively, you can use a variable to define a path and then you can link to sources using a relative path.

Tip: You can prevent linked folders, copybooks, or other sources from being built by right-clicking them in COBOL Explorer and clicking Build Action > Ignore.

To link to a file

Restriction: You cannot link to an individual copybook file. To link to a copybook, you must link to the containing folder instead.
  1. Click File > New > Other.
  2. Expand General and click File.
  3. Enter the name to use for the linked resource. You can enter an alias.
  4. Click Advanced.
  5. Select Link to file in the file system and browse to the file to link. You can also click Variables and define a path variable, so that you can link to files using a relative path.

To link to a folder containing copybooks

  1. Click File > New > Other.
  2. Expand General and click Folder.
  3. Enter the name to use for the folder containing the copybooks or linked resources. You can enter an alias.
  4. Click Advanced.
  5. Select Link to alternate location and browse to the folder to link. You can also click Variables and define a path variable, so that you can link to folders using a relative path.

To link to a copybook project

You can link to a COBOL Copybook or Remote COBOL Copybook project if one exists in your workspace:

  1. Select your project.
  2. Right-click and select Properties.
  3. Expand Micro Focus > Build Path and click Projects.
  4. Click Add.

    This opens the Select projects dialog box.

  5. Check the copybook or remote copybook projects that you wish to link to.
  6. Click OK twice.
Parent topic: Using source files from outside your project


To link to mainframe locations

You can link to mainframe locations using SourceConnect to define mainframe datasets so they appear in your project directory structure.

Prerequisites

Before linking to a folder or file on the mainframe, ensure that you have configured a node and catalog filter for the mainframe using Server Access Configuration. See Adding a Mainframe Node and Configure Mainframe Drives. To configure an MFA Server connection, see Defining a connection.

To link a folder

To link a mainframe folder and the files it contains to your project, perform the following steps:

  1. Right-click your project.
  2. Click New > Folder.
    Note: In the Application Explorer view, click New > Folder > Folder.

    This opens the New Folder dialog box.

  3. Click Advanced.
  4. Check Link to alternate location (Linked Folder).
  5. In the Choose file system list, select RSE.
  6. Click Browse.

    This opens the Browse for File dialog box.

    • If you have already specified an MFA Server connection in the Remote System view:
      1. In the Connection list, select your MFA Server connection name.

        This displays the filtered files system specified in the drive and catalog of the SourceConnect tab of the Mainframe Access Configuration tool.

      2. Expand the tree and click the required folder.
      3. Click OK.
    • If you need to create an MFA Server connection, click New, see Defining a connection for more information.
      1. In the Browse For File dialog box, expand the tree and click the required folder.
      2. Click OK.

    This populates the Folder name field with the mainframe folder and server details.

  7. In the Folder name field, type a valid folder name.
  8. Click Finish.

To link a file

To link a mainframe file to a folder in your project, perform the following steps:

  1. Right-click a folder in your project.
  2. Click New > File.
    Note: In the Application Explorer view, click New > File, and then click the required file type.

    This opens the New File dialog box.

  3. Click Advanced.
  4. Check Link to file in the file system.
  5. In the Choose file system list, select RSE.
  6. Click Browse.

    This opens the Browse for File dialog box.

    • If you have already specified an MFA Server connection in the Remote System view:
      1. In the Connection list, select your MFA Server connection name.

        This displays the filtered files system specified in the drive and catalog of the SourceConnect tab of the Mainframe Access Configuration tool.

      2. Expand the tree and click the required file.
      3. Click OK.
    • If you need to create a MFA Server connection, click New, see Defining a connection for more information.
      1. In the Browse For File dialog box, expand the tree and click the required folder.
      2. Click OK.

    This populates the File name field with the mainframe file and server details.

  7. In the File name field, type a valid file name and extension.
  8. Click Finish.
Parent topic: Using source files from outside your project
Related reference
Adding a Mainframe Node
Configure Mainframe Drives
Defining a connection


To create a project or a file from a custom template

  1. Click File > New to select a project type or right-click your project in Application Explorer view, click New > File and select the type of file you want to create.
  2. Specify a name.
  3. Select a template:
    • If you have not configured the IDE to use custom templates, you are presented with the default Micro Focus template.
    • If you changed the IDE preferences to use custom templates, these are now available.
    • If you want to use another existing project as a template, check Browse for template and use Browse to navigate to the location of the project and select either the .project file or the source file as appropriate.
  4. Click Finish to create the project or the file.
  • Using custom project and file templates
  • To create a custom project template
    You can create your own project templates to use in the IDE to create applications.
  • To create a custom file template
  • To configure the IDE to use custom templates
Parent topic: Creating COBOL Projects
Related concepts
Developing applications on remote machines
Related information
Creating and importing COBOL projects
Creating and importing resources
Using source files from outside your project
Indicating Whether a File is a Copybook or a COBOL Program
Configuring the Project, Build Configuration and File Properties


Using custom project and file templates

Enterprise Developer provides a range of COBOL project templates for the main types of applications for you to start with and build upon.

Your organization might employ a complicated application development life cycle that involves multiple users (for example, development and testing teams) that cooperate with each other in a workgrouping environment and share the same source code.

In these cases your administrator can create templates based on the most commonly-used projects and distribute these projects to every user. Using templates in this way speeds up the development process and minimizes the risk of errors and inconsistencies caused by different people using different settings.

Enterprise Developer enables you to use existing pre-configured projects and files as templates in the wizards for creating new projects and files.

To create a template, your administrator would create and configure the projects to be used as a base, add the required source programs, and then share that project across your organization - for example, by storing it in a folder in your version control system. To use the templates, each users has to download that folder from source control onto their machines and configure Enterprise Developer to search for templates in that location.

Note: Using custom file templates is not supported for COBOL programs, COBOL JVM classes or interfaces in the COBOL JVM projects.
Parent topic: To create a project or a file from a custom template


To create a custom project template

You can create your own project templates to use in the IDE to create applications.

A custom template is actually an existing project so, first, you need to create and configure a project that includes required source files and settings. You can store the project in a dedicated templates folder on your machine (or a folder in your source control system). Once you have created your custom template, you need to configure your IDE to search for templates in your templates folder.

Note: A project template can only be used to produce projects of the same project type.

To create a project to use as a custom template:

  1. In the IDE, create a project of the desired project type.
  2. Add existing files to the project or add new ones to it, and add the required source code to them.
  3. Configure the project and the file properties.
    Note: Ensure that the Default Platform Target in the builder preferences is set appropriately for the platform and your requirements.
  4. Build the project and ensure there are no build errors.

    The project is stored in a subfolder of the current workspace. This subfolder includes the source programs and the build output, the .project file and some other files with information about the project and the build and debug configurations.

To save the project in a templates folder:

  1. On your file system, navigate to the project folder in your workspace.
  2. If you do not want to distribute the build output files (such as .gnt, .dll, exe) as part of the template, either delete the output folder or the individual files.
  3. Copy and paste the project folder into your templates folder (such as c:\myprojecttemplates).

Instead of saving the project in the templates folder in this way, you could export it from the IDE as follows:

  1. In the IDE, select your project in the PL/I, COBOL Explorer or Application Explorer view.
  2. Click File > Export.
  3. In the Export dialog box, expand General, click File System, then click Next.
  4. Ensure the check box for your project is enabled in the left-hand pane.
  5. In the right-hand pane, ensure you have selected only the source files and not the output files.
  6. In the To directory field, specify the path to your dedicated templates folder (c:\myprojecttemplates).
  7. Click Finish.

    This stored the project file and the selected source files in your templates folder.

Note: It is a good practice to use a single folder to store all of your templates. You can use any subfolder structure within that location. When you want to use the templates, you need to configure the IDE preferences to search for templates in the templates folder. The IDE will scan all subfolders of the templates folder, and will display the relevant project and file types in a tree structure.
Parent topic: To create a project or a file from a custom template


To create a custom file template

You can create templates for any file type that Enterprise Developer provides a new file wizard for.

Note: Using custom file templates is not supported for COBOL programs, COBOL JVM classes or interfaces in the COBOL JVM projects.

When you prepare a source file template, you can use a placeholder for the program name. This is replaced with the actual program name when you are using the template to create new files.

To prepare to use a file as a template:

  1. In the IDE, create a file of the desired file type in your project and type in it the required code.
  2. You can replace the program name in any source files (COBOL or PL/I) with the following string <ProgramName>.

    This is a placeholder that will be replaced with the actual filename when you are using the file as a template.

  3. Save the file.

To save the file to a templates folder:

  1. On your file system, navigate to the project folder in your workspace.
  2. Copy and paste the file into a templates folder (such as c:\myfiletemplates).

Instead of saving the file in this way, you could export it from the IDE to your templates folder:

  1. In the IDE, select your project in COBOL Explorer.
  2. Click File > Export.
  3. In the Export dialog box, expand General, click File System, and then click Next.
  4. Ensure the check box for your project is enabled in the left-hand pane.
  5. In the right-hand pane only select the file you would like to use as a template.
  6. In the To directory field, specify the path to your dedicated templates folder (such as c:\myfiletemplates).
  7. Click Finish.

    This saves the file to your templates folder.

Note: It is a good practice to use a single folder to store all of your templates. You can use any subfolder structure within that location. When you want to use the templates, you need to configure the IDE preferences to search for templates in the templates folder. The IDE will scan all subfolders of the templates folder, and will display the relevant project and file types in a tree structure.
Parent topic: To create a project or a file from a custom template


To configure the IDE to use custom templates

Once you have created your custom templates, you need to configure the IDE so that it shows them alongside the Micro Focus templates in the wizards for creating projects or files. You can also set a custom project or file to be the default option.

  1. In the IDE, click Window > Preferences.
  2. Expand Micro Focus, and click Templates.
  3. In the Project templates and the Source file templates sections, click Browse to select the folders where you have saved your custom project and file templates.
  4. If you want to change the default template, select a project or file category from the Default template drop-down fields.
  5. In the pane below the lists, click the template you want to use as the default.
  6. Click Apply, and then click OK.

    Next time you create a project or a file of the same project type, your custom template is the one selected by default.

Parent topic: To create a project or a file from a custom template


Indicating Whether a File is a Copybook or a COBOL Program

When you import existing COBOL sources into Enterprise Developer, the IDE scans each imported file to determine whether it is a COBOL program or a copybook. Based on the settings specified in Window > Preferences > Micro Focus > COBOL > Directives Determination, the IDE sets Compiler directives only on the files identified as COBOL programs.

In certain situations, the IDE may identify a COBOL program as a copybook (or vice versa) which means it is not possible to set the appropriate Compiler directives on that file and the project fails to compile. In such cases, you can use the Transform Copybook to Program and Transform Program to Copybook context menu commands to manually indicate the correct file type.

Note: It is not possible to transform files with a .cpy extension as they are always copybooks, or files with a .cob extension as they are always COBOL programs. Files with a .cbl extension may be either COBOL programs or copybooks.

To indicate that a file is a COBOL program:

  • In COBOL Explorer, right-click the file that you want to convert in the Copybooks category, and click Transform Copybook to Program.

    This updates the information in the project about this file and moves the file to the COBOL Programs category of the project.

Alternatively, you can do one of the following:

  • Use drag and drop in COBOL Explorer to move the file from the Copybooks category to the COBOL Programs category of the project.
  • Copy the file from the Copybooks category and paste it into the COBOL Programs category of the project.

    Copying moves the file.

To indicate that a file is a copybook:

  • In COBOL Explorer, right-click the file that you want to convert in the COBOL Programs category, and click Transform Program to Copybook.

    This updates the information in the project about this file and moves the file to the Copybooks category of the project.

Alternatively, you can do one of the following:

  • Use drag and drop in COBOL Explorer to move the file from the COBOL Programs category to the Copybooks category of the project.
  • Copy the file from the COBOL Programs category and paste it into the Copybooks category of the project.
Parent topic: Creating COBOL Projects
Related concepts
Developing applications on remote machines
Related information
Creating and importing COBOL projects
Creating and importing resources
Using source files from outside your project
To create a project or a file from a custom template
Configuring the Project, Build Configuration and File Properties


Configuring the Project, Build Configuration and File Properties

You can specify the project, build configuration and file properties to control the way you build your applications.

  • Project Properties
  • File Properties
  • To set file properties using directive scanning
Parent topic: Creating COBOL Projects
Related concepts
Developing applications on remote machines
Configuring Projects
Related information
Creating and importing COBOL projects
Creating and importing resources
Using source files from outside your project
To create a project or a file from a custom template
Indicating Whether a File is a Copybook or a COBOL Program
Using Preprocessors


Project Properties

A project's properties hold all the information to build and run your application, such as:

  • Build Paths
    Defines the order in which the directories of files are built, and the order in which locations are searched for copybooks.
  • Build Settings
    These include information such as the types of target files to build, the target platform and so on.
  • BMS Properties
    The BMS page in the project properties lets you specify build settings for BMS compilations.
  • Build Directives for Standalone Editing
    Enables you to specify any Compiler directives to be used when compiling standalone COBOL files when no associated program symbols files (.idy) are found.
  • File Extensions
    You can also associate a file extension with the content type of a COBOL file, using Window > Preferences > General > Content Types.
  • Run-Time Configuration Properties
    These include options such as the search order for called programs, run-time arguments, run-time tunables, COBOL switches and so on.
Parent topic: Configuring the Project, Build Configuration and File Properties
Related information
File Properties
To set file properties using directive scanning
Setting Compiler Directives on Individual Files
Setting Project-Wide Build Properties and Compiler Directives


Build Paths

The search order here takes precedence over the COBCPY environment variable setting. To add copybook paths to this list, specify the paths as linked resources.

Tip: In order to increase the speed of indexing and background parsing, we recommend you deselect paths that don't contain copybooks.
Parent topic: Project Properties
Related information
Build Settings
BMS Properties
Build Directives for Standalone Editing
File Extensions
Run-Time Configuration Properties


Build Settings

These include information such as the types of target files to build, the target platform and so on.

The build settings occur in the following places:

  • Project > Properties > Micro Focus > Project Settings. These build settings are for this project. They can be overridden by the currently active build configuration.
  • Project > Properties > Micro Focus > Build Configurations. You can have multiple build configurations for different build scenarios and swap between them. You choose the configuration you want to use, by setting it as the current active configuration. This then overrides the project language settings. When you create a build configuration, you cannot give it a name containing any of the characters $ \ {} () % ' " .
Parent topic: Project Properties
Related information
Build Paths
BMS Properties
Build Directives for Standalone Editing
File Extensions
Run-Time Configuration Properties


BMS Properties

The BMS page in the project properties lets you specify build settings for BMS compilations.
Note: To enable file-specific properties on a BMS file, that differ from the BMS properties set on project level, right-click the .bms file in COBOL Explorer, and click Enable file specific settings. To switch to using the project properties, disable this setting.

SYSPARM

MAP
Specify whether the build should create a MAP load module containing screen-handling code when the mapset type is set to TYPE=&&SYSPARM.
DSECT
Specify whether the build should create a copybook, or an include file or an Assembler DSECT file when the mapset type is set to TYPE=&&SYSPARM.

General

Enable SDF features
Specify whether to use SDF comments for parse and compile.
Align Data Items on Half-Word Boundaries
Specify that data items are to be aligned on half-word boundaries.
Verbose
Check this to enable showing informational and warning messages during the compilation of the .bms files.
Additional Directives
Specify any additional directives to pass to the BMS compiler. Use space to separate the directives.

Advanced

Use MAP name
Specify the name for the map file. Only available in the BMS file properties.
Use DSECT name
Specify the filename you want to use for the copybook to be created when the .bms file is compiled. Only available in the BMS file properties.
Levels
Specify the levels to use when the copybook is generated (copybook start level and increment).
Use SDF prefix
Specify the prefix to be used for data items generated in the copybook.
Decimal Point Character
Specify a single character to be used as the decimal point in the .bms files - either . (period) or , (comma).
Currency Character
Specify a single character to be used as the currency sign.
Allow Long Macro Label Names
Specify whether to use long labels for macros in the .bms files. Equivalent to the setting the HLL directive of the BMS Compiler.
Redefine Input
Specify if each field's attribute byte should redefine the flag byte in the input map. This is equivalent to setting DFHMSD STORAGE to AUTO.
SDF Map Size
Specify whether to generate map length in the copybook for SDF mapsets.
Hyphenate Field Suffix
Specify whether to enable hyphenated suffixes for fields.

Output

DSECT Output Path
Specify the path to the directory in which the build generates the DSECT files. If no path is specified, the files are generated in the project directory.
Binary Output Path
Specify the path to the directory in which the build generates copybooks for the BMS files in your project. If no path is specified, the files are generated in the project directory.
Parent topic: Project Properties
Related information
Build Paths
Build Settings
Build Directives for Standalone Editing
File Extensions
Run-Time Configuration Properties


Run-Time Configuration Properties

These include options such as the search order for called programs, run-time arguments, run-time tunables, COBOL switches and so on.

Again, you can set the configuration in more than one way:

  • Project > Properties > Micro Focus > Run-time Configuration. These settings apply to the project. They are the defaults and are overridden by any run-time settings in the general run-time configuration (described below)
  • Run > Run Configurations. Like build configurations, you can have multiple run configurations and swap between them. These run-time settings override the project settings.

When you run the application, the IDE creates a .gcf file which includes the run-time IDE settings.

Parent topic: Project Properties
Related information
Build Paths
Build Settings
BMS Properties
Build Directives for Standalone Editing
File Extensions
Run-time configuration settings available in the IDE
Run-time Switches
Environment variables (Windows)


File Properties

Files in your projects inherit the properties set on project level.

You can change some of the settings for individual files so that these override the settings specified for the project and for the currently active build configuration. To do this:

  1. Right-click the file in COBOL Explorer and click Properties.
  2. In the pane in the left-hand side of the file properties, click one of the available tabs (for example, COBOL).
  3. Check Enable file specific settings.

    This enables you to set file settings that differ from the ones set at project level.

  4. Change the settings as required.
  5. Click Apply and then click OK.
Note: For individual files, you can only enable an SQL preprocessor or Additional Preprocessors if there are no preprocessors enabled in project settings or for the build configuration. The preprocessor that is available at file level is the one that has been selected last at project or build configuration level.

You can change the preprocessor that is available at file level by first selecting it at project level (or in the build configuration settings) and then removing it from the project's settings.

Parent topic: Configuring the Project, Build Configuration and File Properties
Related information
Project Properties
To set file properties using directive scanning
Setting Compiler Directives on Individual Files
Setting Project-Wide Build Properties and Compiler Directives


To set file properties using directive scanning

You can use a directives scan to ensure dialect-related properties for individual COBOL source files are correct. You can configure the directives scan from Window > Preferences > Micro Focus > COBOL > Directives Determination.

Important: If the project already has the requisite setting, the scan does not set it on a file.

Do the following to perform a directives scan:

  1. Select a file, group of files, directory, or project in COBOL Explorer.
  2. Right-click and choose Determine Directives from the menu.
The following can be set in this way:
Language dialect (COBOL settings)
The scan examines each file to determine a list of possible dialects. These are then compared with:
  • The project dialect. If one of the possible dialects matches the project dialect, the Dialect option doesn't change.
  • A list of dialects in priority order. The most likely dialect is chosen and Dialect set on the file.
CICS settings
Files that contain EXEC CICS statements have the EXEC CICS option set. The scan sets no other CICS preprocessor options.
SQL settings
If the files contain any EXEC SQL statements, the EXEC SQL and Preprocessor Type options are set accordingly. The scan sets none of the additional directive's options.

A window showing the proposed changes opens after the scan. You choose to accept the changes by clicking OK, or to ignore the changes by clicking Cancel.

Parent topic: Configuring the Project, Build Configuration and File Properties
Related information
Project Properties
File Properties


Developing applications on remote machines

Restriction: You must have Micro Focus Enterprise Developer UNIX Components installed on the remote machine.
  • Creating connections to remote hosts
    To develop applications on a remote host, you need to configure a connection to it. Once created and configured, a connection can be used for more than one remote project.
  • To launch a server on the remote host
    Launching a server is a part of the initial set up process on the remote machine. If you need to start the server again, you can do that from the Remote Systems perspective in the IDE.
  • Working with file systems on remote machines
    When establishing a connection to a remote machine, you must select the type of file system to use for the connection.
  • Creating remote projects
    You can create different types of remote COBOL projects from scratch, or use an existing local project and convert it to a remote project.
Parent topic: Creating COBOL Projects
Related information
Creating and importing COBOL projects
Creating and importing resources
Using source files from outside your project
To create a project or a file from a custom template
Indicating Whether a File is a Copybook or a COBOL Program
Configuring the Project, Build Configuration and File Properties


Creating connections to remote hosts

To develop applications on a remote host, you need to configure a connection to it. Once created and configured, a connection can be used for more than one remote project.
Restriction: You must have Micro Focus Enterprise Developer UNIX Components installed on the remote machine.

You create and manage connections from the Remote Systems Explorer perspective. You can then select the existing connection when creating a remote project.

You can also create and configure new connections when creating new remote projects, or when converting local projects to remote projects.

  • To create a connection to a remote host
    Create and manage your connections to remote hosts from the Remote Systems Explorer perspective.
  • To diagnose client-side problems when connecting to a remote host
    If you are experiencing problems opening your remote projects, run the connection diagnostics tool to narrow down the problem.
  • To diagnose server-side problems when connecting to a remote host
    If you are experiencing problems opening your remote projects or establishing remote connections, run the connection diagnostics tool on your development hub to narrow down the problem. The tool runs a number of server-side tests.
  • To create a connection to a remote UNIX host running behind a firewall
    If the remote host is running a firewall but is accessible via SSH, you can configure Eclipse to route its network traffic through a SOCKS proxy client such as PuTTY. The client forwards network traffic via the SSH daemon to the remote host machine.
Parent topic: Developing applications on remote machines


To create a connection to a remote host

Important: If you use one of the non-Micro Focus connection types (for example 'Linux' or 'Unix') from the Remote System Explorer perspective to create a connection, choose SSH as the file system provider if you intend to use the connection for remote projects whose file system is RSE. You do this by selecting ssh.files in the Configuration box at the Files step of the wizard. Selecting a different file system provider will cause performance and stability problems. The remote host must have SSH installed and enabled.
  1. From the Remote Systems Explorer perspective, click Define a connection to a remote system (Define a connection to a remote system).

    The New Connection wizard appears.

  2. Choose whether to use a remote file system (RSE) or a network file system (Samba, NFS) to interact with the remote host.
    Restriction: The Classic Data File Tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type.

    The Network File System (NFS) protocol allows a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.

  3. Click Next.

    The System Connection details appear.

  4. In the Host name field, enter the name or IP address of the remote host.
  5. In the Connection name field, enter a unique name for the connection.
  6. In the Description field, enter a description for the connection (not mandatory).
  7. If you want to test the connection to the remote host before the connection details are saved, click Verify host name.
  8. Click Finish.
    Note: You can click Next to view further settings, but they can be left at their default state.

    If you selected Verify host name, an attempt to verify the host name is made; if a connection cannot be established, you must enter valid details before the connection can be saved.

To change any of the connection settings afterwards, open the Remote Systems Explorer perspective, right click on the connection and select Properties. You can view and edit the connection details on the Connector Services and Host tabs.

Parent topic: Creating connections to remote hosts
Related concepts
To diagnose client-side problems when connecting to a remote host
To diagnose server-side problems when connecting to a remote host
To create a connection to a remote UNIX host running behind a firewall


To diagnose client-side problems when connecting to a remote host

If you are experiencing problems opening your remote projects, run the connection diagnostics tool to narrow down the problem.
Note: There is also a server-side diagnostics tool that you should run from the Development Hub server to troubleshoot connection problems.

The diagnostics tool is only available for remote projects and remote connections, and is run from within the Eclipse IDE: select a remote project (in COBOL Explorer) or a remote connection (in Remote Systems Explorer), then right-click and choose Diagnose Connection Problems to run the tool.

Note: You can cancel the running of the tool at any time, by clicking Cancel.

The tool runs a series of tests, which result in a pass or a fail. If a failure occurs, the rest of the tests are not run. Some test fails that are not fatal produce a warning message, and the tool will continue to run the subsequent tests. See the details below for a brief description of each test, and possible reasons for its failure.

  • Client-side connection tests
Parent topic: Creating connections to remote hosts
Related concepts
To diagnose server-side problems when connecting to a remote host
To create a connection to a remote UNIX host running behind a firewall
Related tasks
To create a connection to a remote host


Client-side connection tests

When you run the client-side connection diagnosis tool from the Eclipse IDE, the following tests are run:
Retrieving Development Hub Server IP Address
The test checks whether the remote host's IP address can be established.
The test fails if the client machine cannot resolve the IP address using the name given in the Host name field.
Pinging remote host
The test attempts to ping the server.
If the test fails, your client machine cannot ping the server, which suggests some sort of network configuration issue (such as a failed DNS lookup, or a firewall or routing issue). Contact your network administrator to troubleshoot further.
Verifying username and password
The test checks whether the logon credentials (user ID and password) provided in the connection are valid.
If the test fails, update the connection with the correct user ID, specifying the correct password on connection.
Accessing SSH on the remote host
Note: This test is only applicable for connections in which the remote file system is SSH, or the remote shell is SSH.

The test checks whether the remote host accepts SSH commands.

The test fails if the remote host does not support SSH commands. SSH must be enabled on the remote host.
Check whether the remote port is open
Note: This test is only applicable to those connections in which the server launcher type is Daemon.

The test checks whether the remote daemon port specified in the connection is open.

This test fails if the daemon port is not available. Ensure the daemon is running on the port specified in the connection properties:

Port connection number

Connecting to the remote daemon
Note: This test is only applicable to those connections in which the server launcher type is Daemon and the remote shell type is DStore.

The test checks whether your client can make a connection to the daemon running on the remote host.

The test fails if the client fails to make a connection to the remote daemon. The check first tries to connect with SSL enabled, and if it fails to make a connection, it again tries with SSL disabled.
If SSL is enabled on the remote host and your client has not saved the SSL certificates, you are prompted to save them.
Launching a new server
Note: This test is only applicable if the server launch type is either SSH or Daemon.

The test checks whether a server can be launched on the remote host.

The test fails if a server cannot be launched from the daemon. For RSE connection types, check that the daemon specified in the connection is running, on the port specified, on the remote host. To see which port is specified, right-click the connection, then choose Properties > Connector Services > DStore Connector Services > Remote Server Launcher > Launcher Properties > Daemon Port.
For SSH connection types, check that the server launch command is referencing the correct product and pathname: right-click the connection, then choose Properties > Connector Services > DStore Connector Services > Remote Server Launcher > Launcher Properties > Server Launch Command. The test first tries to connect with SSL enabled, and if it fails to make a connection, it tries again with SSL disabled.
If SSL is enabled on the remote host and your client has not saved the SSL certificates, you are prompted to save them.
Checking whether X Server is running

The test checks whether an X Window can be opened, using the location taken from the Debug Preferences page (Window > Preferences > Micro Focus > Debug).

If the Default X Server (DISPLAY) field is empty, clientMachineName:0.0 is used as default.

The test generates a warning if the X Server cannot be contacted. The warning contains the details of the DISPLAY it is trying to contact. Edit the Default X Server (DISPLAY) field if the details are incorrect.

Checking the write access in home directory

The test checks whether the user, specified in the connection user ID, has write access in the home directory on the remote host.

The test fails if the user does not have the write permission in the /home/user ID directory. You must update the permissions on the remote host.
Compiling to 32-bit
The test checks whether a program can be compiled to 32 bit on the remote host.
The test generates a warning if a program cannot be compiled to 32 bit. Check whether the remote host supports 32-bit compilation.
Compiling to 64-bit
The test checks whether a program can be compiled to 64 bit on the remote host.
The test generates a warning if a program cannot be compiled to 64 bit. Check whether the remote host supports 64-bit compilation.
Checking the product version
The test checks whether the product version of the Micro Focus Enterprise Developer UNIX Components on the remote host and the product version of Enterprise Developer are compatible.
This test generates a warning if there is a compatibility issue with the products installed. The warning also specifies both product versions. It is possible to continue working, but if you find issues, it is advisable to update to compatible versions.
Creating and modifying files
The test checks whether a file can be created via one mechanism and modified by another on the remote host. This checks whether a file created by Samba/NFS or RSE can be modified at the remote end. It also checks whether a file created at the remote end can be modified by Samba/NFS or RSE.
The test fails if the file created with one mechanism cannot be modified by another mechanism.
UDP
The test checks whether the client can communicate with the remote host using the UDP protocol.
If the test fails, check whether UDP packets are being blocked by the firewall at the client end, and if so, contact your network administrator to troubleshoot further.
A lack of UDP support means that features such as ES/MFDS and IMTK deployment may not work.
Note: To view your connection properties:
  1. Click Window > Show View > Other > Remote Systems > Remote Systems.

    This opens the Remote Systems view.

  2. Right-click the connection, and then click Properties.

    This opens your connection's Properties dialog box.

Parent topic: To diagnose client-side problems when connecting to a remote host


To diagnose server-side problems when connecting to a remote host

If you are experiencing problems opening your remote projects or establishing remote connections, run the connection diagnostics tool on your development hub to narrow down the problem. The tool runs a number of server-side tests.
Note: There is also a client-side diagnostics tool that you should run from the Eclipse IDE to troubleshoot connection problems.
Note: By default, the diagnostics tool is installed in $COBDIR/remotedev.

Run the diagnostics tool from the command line, with super user privileges, using the following syntax:

ivp [options] [eclipse-client[:display-number]]
where [options] are:
-h
Displays the valid syntax that you can use.
-d port-number
The port number used by the development hub daemon.
-u user name
The name of the user connecting to the development hub.
Note: Not all tests can be run if you do not supply the user name.
-p password
The password for the user name.
Note: If you do not want to enter the password on the command line, you can omit it. You are prompted for it during the appropriate test.
-v
Displays verbose output for appropriate tests. For example, the required tools test lists the individual tools that are required.
And [eclipse-client[:display-number]] is:
eclipse-client
The Eclipse client that is unable to connect.
display-number
Defaults to 0 (zero) if not specified.

The tool runs a series of tests, which result in a pass or a fail. If a failure occurs, the rest of the tests are not run. Some test fails that are not fatal produce a warning message, and the tool will continue to run the subsequent tests. See the details below for a brief description of each test, and possible reasons for its failure.

  • Server-side connection tests
Parent topic: Creating connections to remote hosts
Related concepts
To diagnose client-side problems when connecting to a remote host
To create a connection to a remote UNIX host running behind a firewall
Related tasks
To create a connection to a remote host


Server-side connection tests

When you run the server-side connection diagnosis tool from the Development Hub server, the following tests are run:

Eclipse test machine
The test attempts to ping the client machine specified by eclipse-client.
When the -v flag is also set, the ping results are displayed. If no client machine is specified, the test is skipped.
If the test fails, the server cannot ping the client machine, which suggests some sort of network configuration issue (such as a failed DNS lookup, or a firewall or routing issue). Contact your network administrator to troubleshoot further.
Development Hub daemon status
The test checks that the Development Hub daemon is running. The daemon is required if you are using either the Micro Focus Development Hub using RSE or the Micro Focus Development Hub using SAMBA, NFS etc connection type. If you are using another type of connection, the test is skipped.
If the test fails, see To launch a server on the remote host using a daemon process for details on restarting the daemon.
Development Hub daemon connect
The test checks that it can connect to the daemon.
If the test fails, it could suggest a firewall problem, in which case, temporarily turn off the firewall and rerun the test. We also advise stopping and restarting the daemon; see Configuring the Remote System Explorer Support for details.
JVM version
The test checks that the version of Java is from one of the supported vendors, and a supported version.
If the test fails, you should check the version of Java against the list of supported versions listed in Additional Software Requirements for Micro Focus Visual COBOL Development Hub.
Required tools
The test checks that all the required tools are present on the Development Hub. When the -v flag is also set, a list of the required tools is displayed.

If the test fails, re-install the tools highlighted as missing.

Note: If the test indicates that sed or ed is missing, we advise that you also reinstall the Development Hub after the required tools have been re-installed.
SE Linux
The test checks if the SE Linux security module is enabled. This module is not supported with the Development Hub.
If the test fails, you must disable the SE Linux module.
License daemons
The test checks that the license daemons are running during compilation and run time.
If the test fails, you must start the license daemons by logging in with super user privileges and running:
/var/microfocuslicensing/bin/startmfcesd.sh
Password crypt

The test checks if the password supplied is valid for the user ID.

Note: The test uses the etc/passwd function as its authentication model.

If the test fails, check the user credentials using the substitute user (su) command.

Compile & run
The test checks that it can compile and run a program.
If the test fails, rerun the test with the -v flag set to provide more information, then troubleshoot as you would for a standard compilation or run-time problem.
X Display
The test checks that an X Server installation is running on the client machine.
If the test fails, it indicates that either the specified X Server is not running or not configured to allow remote connections. Either start the X Server on the client machine, or if it is already running, configure it to allow remote connections. Refer to your X Server installation documentation for details on allowing remote connections.
Shell.pm

The test checks if a Perl module called Shell.pm can be located.

If the test fails, it means that Shell.pm is not found using @INC. To solve this, you could define the PERLLIB or PERL5LIB environment variable to specify the path to the missing module, and then restart the daemon.
su to user
The test checks that it can execute the su command for the specified user name.
If the test fails, contact your network administrator to troubleshoot further.
Parent topic: To diagnose server-side problems when connecting to a remote host


To create a connection to a remote UNIX host running behind a firewall

If the remote host is running a firewall but is accessible via SSH, you can configure Eclipse to route its network traffic through a SOCKS proxy client such as PuTTY. The client forwards network traffic via the SSH daemon to the remote host machine.
You need the latest version of the PuTTY Telnet and SSH client. Download it from the PuTTY website - click here.
The following example shows the two aspects of the configuration. Firstly, you need to configure the PuTTY Telnet and SSH client to act as a proxy client. Secondly, you will need to configure Eclipse to use the SOCKS network connection type to communicate network traffic.

Configuring PuTTY as the proxy server

  1. In the PuTTY Telenet and SSH client, in the left panel, click Connection > SSH > Tunnels.

    This displays the Options controlling SSH port forwarding panel.

  2. Type an available listening port in the Source port field.
  3. Click Dynamic.
  4. Click Add.

    This adds the port number prefixed with a "D" in the Forwarded ports field.

  5. In the left panel, click Connection > SSH > X11.

    This displays the Options controlling SSH X11 forwarding panel.

  6. Check Enable X11 forwarding.
  7. In the X display location field, type localhost:0.
  8. In the left panel, click Session.

    This displays the Basic options for your PuTTY session panel.

  9. In the Host Name (or IP address) field, type the name or IP address of the remote server you want to connect to.
  10. In the Saved Sessions field, type a descriptive name for the session.
  11. Click Save.

    This creates an entry in the Saved Sessions list.

  12. Click Open.

    This starts a terminal session. Type the username and password when prompted.

  13. In the terminal window, type echo $DISPLAY and press Enter.
    You should get a response similar to:
    localhost:10.0

    Make a note of the value that is displayed. It is required when configuring the Debug preferences.

    Note: If you get a blank response to the echo $DISPLAY command, right-click on the PuTTY terminal window header, and then click Event Log. This opens the PuTTY Event Log dialog. Scroll upwards from the bottom and make a note of any messages relating to access denied, forwarding refused or no program. Pass these details to your system administrator for resolution.

Configuring the Eclipse network connection

  14. In Eclipse, click Window > Preferences > General > Network Connections.

    This opens the Network Connections preferences dialog box.

  15. In the Active Provider list, select Manual.
  16. In the Proxy entries table, click the SOCKS row.

    This highlights the row.

  17. Click Edit.

    This opens the Edit Proxy Entry dialog box.

  18. In the Host field, type localhost.
  19. In the Port field, type the port number used in the Source port field in PuTTY.
  20. Click OK.

    This populates the Host and Port cells in the Proxy entries table.

  21. Click Window > Preferences > Micro Focus > Debug.

    This opens the debug preferences.

  22. In the Default X Server (DISPLAY) field, type the DISPLAY value returned by the remote machine in step 13.
  23. Click Apply.
  24. Click OK.
    Note: Steps 13, and 21-24 need to be performed each time the proxy server is started.
When you have completed the configuration you need to create a remote project. Specify Remote file system (RSE) and select Micro Focus DevHub using RSE when choosing the remote system type. See Creating remote projects for more details on creating a remote project.
Parent topic: Creating connections to remote hosts
Related concepts
To diagnose client-side problems when connecting to a remote host
To diagnose server-side problems when connecting to a remote host
Related tasks
To create a connection to a remote host
Related information
Debugging Using a Remote Machine


To launch a server on the remote host

Restriction: You must have Micro Focus Enterprise Developer UNIX Components installed on the remote machine.
Note: This process is part of the initial set up of Micro Focus Enterprise Developer UNIX Components on the remote host. The steps required to configure the remote server are included in the installation notes for Enterprise Developer and should be executed at installation time.

You can launch a server on the remote host by using the startrdodaemon script. This is the most common approach and it launches the server via a daemon process. With this script you are able to specify the port number to be used.

If you want to launch a remote server which does not use the daemon process, you can configure a new connection by using the startrdoserver script in the New Connection dialog in the Remote Systems perspective in the Eclipse IDE.

To ensure that your connection to the server recognises changes in your configuration - for example, changing the value of an environment variable - you need to disconnect and then reconnect to the server. You can do this by restarting Eclipse or by disconnecting and reconnecting using the Connection context menu within the Eclipse IDE.

  • To launch a server on the remote host using a daemon process
  • To launch a server on the remote host without a daemon process
  • To launch a server on the remote host using a Secure Shell daemon process
Parent topic: Developing applications on remote machines
Related information
To create a remote COBOL project


To launch a server on the remote host using a daemon process

This is the most common approach to launching a server on a remote host.

Any servers launched by this daemon are assigned the ID of the connecting user, taken from the authentication details used when the connection was established. Any subsequent compiling and debugging processes are run as this user.

To start the daemon, you need a version of both Perl on your Unix machine and a version of Java.

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

Parent topic: To launch a server on the remote host
Related concepts
To launch a server on the remote host without a daemon process
Related information
To launch a server on the remote host using a Secure Shell daemon process


To launch a server on the remote host without a daemon process

If you want to launch a remote server which does not use a daemon process take the following steps:

Using the Rexec service

Rexec must be enabled on the remote host.

  1. From the Remote Systems perspective click File > New > Other.
  2. Expand Remote System Explorer.
  3. Click Connection.
  4. Click Next.
  5. Select the connection type, then click Next.
    Note: The connection type must be one of the following: Linux, Micro Focus DevHub using SAMBA, NFS etc, or Unix.
  6. Enter Host and Connection name then click Next.
  7. In the Files dialog, check the dstore.files box and select Launcher Properties.
  8. In the Properties dialog on the right hand page, select Rexec for the Launcher property.
  9. In the Server launch command dialog, supply configuration data specific to your requirements. You can provide these in a script or as a list of values.
    sh -c scriptname
    sh -c "PATH=java install directory/bin:$PATH; export PATH; COBOL install directory/remotedev/startrdoserver"
  10. Complete the Processes and Shells dialogs with the same configuration data, as appropriate.
  11. Click Finish.

Without using the Rexec service

  1. From the Remote Systems perspective click File > New > Other.
  2. Expand Remote System Explorer.
  3. Click Connection.
  4. Click Next.
  5. Select the connection type then click Next.
    Note: The connection type must be one of the following: Linux, Micro Focus DevHub using SAMBA, NFS etc, or Unix.
  6. Enter Host and Connection name then click Next.
  7. In the Files dialog, check the ssh.files box and select Launcher Properties.
  8. In the Processes dialog, check the dstore.processes box and select Launcher Properties.
  9. In the Properties dialog on the right hand page, select Running for the Launcher property.
  10. Click Finish.
  11. In the Remote Systems perspective, right click on the Processes item of the new connection and select Properties then Subsystem.
  12. Clear the Port value by clicking the [image] button and enter an available port number for the server to use.
  13. Log on to the remote host, for example using telnet or an SSH Terminal from within Eclipse.
  14. In the terminal session, set any environment variables (for example to ensure the Java executable is found on $PATH) and run the startrdoserver script, specifying the port number you entered in the Subsystem properties. You can optionally specify a timeout in milliseconds (the default is 120000).
    COBOL install directory/remotedev/startrdoserver port timeout
  15. Connect to the server within the timeout period.
Parent topic: To launch a server on the remote host
Related information
To launch a server on the remote host using a daemon process
To launch a server on the remote host using a Secure Shell daemon process


To launch a server on the remote host using a Secure Shell daemon process

If the remote UNIX machine you are connecting to uses LDAP authentication which is not supported by the DevHub daemon, the only way to launch a server on the remote host is to use a Secure Shell daemon process to do this.

This type of connection also has the following benefits:

  • It does not require you to run the DevHub daemon process with root privileges.
  • It provides more flexibility in setting environment variables needed for building or debugging on the remote server.

To configure and establish a connection to a remote host using an SSH daemon process:

  1. In Eclipse, click File > New > Remote COBOL Project.
  2. In the New Remote Project dialog box, specify a name for your project.
  3. Click Next twice.
  4. On the row for Connection name, click New Connection.

    This starts the New Connection wizard.

  5. Click Micro Focus DevHub using SSH, and click Next.
  6. Specify a Host name and a Connection name, and click Next.

    This opens the Processes page.

  7. In the Available Services pane, click Launcher Properties.
  8. Take a look at the Properties pane that shows the details of the launcher and the Server launch command.
  9. In the Server launch command dialog, supply configuration data specific to your requirements. You can provide these in a script or as a list of values.

    The default command, provided that Java is on your PATH variable, is:

    sh -c "/opt/microfocus/EnterpriseDeveloper/remotedev/startdoserver 0"

    The full command that takes into account the case when Java is not on your PATH variable and Enterprise Developer is not installed in the default location is:

    sh -c "PATH=java install directory/bin:$PATH; export PATH; COBOL install directory/remotedev/startdoserver [<port> | <low port>-<high port>] "

    Where:

    • <port> is the port number the server 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 4033.

      For example,

      $COBDIR/remotedev/startdoserver 4999

      This command will start a server listening on port 4999.

      $COBDIR/remotedev/startdoserver 0

      A value of 0 for <port> indicates the command will start a server listening on a random port.

    • <low port>-<high port> is the range of ports on which the server should use to communicate with Eclipse on the client machine if a port of 0 is specified.

      For example,

      $COBDIR/remotedev/startdoserver 4090-4999

      This command will start a server listening on an available port in the range 4090 to 4999.

  10. Complete the Processes and Shells dialogs with the same configuration data, as appropriate.
  11. Click Finish.
Parent topic: To launch a server on the remote host
Related concepts
To launch a server on the remote host without a daemon process
Related information
To launch a server on the remote host using a daemon process


Working with file systems on remote machines

When establishing a connection to a remote machine, you must select the type of file system to use for the connection.
Restriction: You must have Micro Focus Enterprise Developer UNIX Components installed on the remote machine.
  • Using Remote System Explorer (RSE)
  • Using NFS
  • Using Samba
Parent topic: Developing applications on remote machines


Using Remote System Explorer (RSE)

Restriction: This functionality requires Micro Focus Enterprise Developer UNIX Components.
The Remote System Explorer (RSE) is a perspective and toolkit in the Eclipse IDE Workbench that allows you to connect and work with a variety of remote systems. With the predefined plug-ins you can:
  • look at remote file systems
  • transfer files between hosts
  • perform remote searches
  • execute commands
  • work with processes
Important: If you use one of the non-Micro Focus connection types (for example 'Linux' or 'Unix') from the Remote System Explorer perspective to create a connection, choose SSH as the file system provider if you intend to use the connection for remote projects whose file system is RSE. You do this by selecting ssh.files in the Configuration box at the Files step of the wizard. Selecting a different file system provider will cause performance and stability problems. The remote host must have SSH installed and enabled.

RSE is a feature supplied by the Eclipse Foundation. Extensive documentation on RSE, including architecture, API, tutorials and reference can be found on the Eclipse website.

Restriction: The following tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type:
  • BMS Painter
  • BMS Compiler
  • All Classic Data File Tools
  • IMS Database editor and segment layout editor
  • Mainframe Assembler compiler
  • Remote System Explorer logging
Parent topic: Working with file systems on remote machines
Related concepts
Using NFS
Using Samba


Remote System Explorer logging

Restriction: This functionality requires Micro Focus Enterprise Developer UNIX Components.

You can configure RSE logging to trace and highlight issues with the server.

The logging configuration file is called rsecomm.properties and is hosted on the remote server under $COBDIR/remotedev/rseserver/rseserver-3.5.

Edit the file to configure:
  • the logging level
  • the log location

The log location can be to standard output stream (stdout) or a file location. The various logging levels are described in the configuration file. A log file is created for each user that makes a connection and is found, when logged in as that user, in ~/.eclipse/RSE/rsecomm.log.

Parent topic: Using Remote System Explorer (RSE)


Using NFS

The Network File System (NFS) protocol allows a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed. The protocol is common with client/server installations running UNIX and Linux.

NFS requires configuration on both the client and server machines. Each client machine accessing the server needs an entry in the /etc/exports on the server and the remote drive mounted on the client machine.

The topicTo verify that NFS is running contains important pre-requisite information on setting up NFS. It is recommended that you read this topic before you attempt the specific server and client set up tasks.

The NFS help provided with your product allows you to create a simple configuration and has been tested on Red Hat Linux 4.x and 5.x using kernel 2.6. For other aspects of NFS, for example, security, and for operating system specifics, it is recommended that you consult your operating system documentation.

  • To verify that NFS is running
  • To set up an NFS server
  • To set up an NFS client
Parent topic: Working with file systems on remote machines
Related concepts
Using Remote System Explorer (RSE)
Using Samba


To verify that NFS is running

Running NFS on the server depends on the portmapper daemon - called either portmap or rpc.portmap. In addition, there are 5 other daemons that are associated with the service:
  • rpc.nfsd
  • rpc.lockd
  • rpc.statd
  • rpc.mountd
  • rpc.rquotad
Most Linux distributions will have startup scripts for these daemons and typically they are found in /etc/init.d.
To check for these daemons, enter the following from a command prompt:
ps aux | grep rpc
Depending on the rpc services running, the result of the ps command will be similar to the following:
 rpc       3338  0.0  0.0   1816   552 ?        Ss   00:31   0:00 portmap
 root      3364  0.0  0.0      0     0 ?        S<   00:31   0:00 [rpciod/0]
 root      3370  0.0  0.0   1868   744 ?        Ss   00:31   0:00 rpc.statd
 root      3394  0.0  0.0   5820   648 ?        Ss   00:31   0:00 rpc.idmapd
 root      3624  0.0  0.0   3940   248 ?        Ss   00:31   0:00 rpc.rquotad
 root      3652  0.0  0.0   1924   284 ?        Ss   00:31   0:00 rpc.mountd
 root      4359  0.0  0.0   3920   684 pts/2    R+   00:34   0:00 grep rpc
You can also check by using the rpcinfo command. From a command prompt, enter the following:
usr/sbin/rpcinfo -p
The following sample output from this command demonstrates that nfs is running versions 2, 3 and 4.
    program vers proto   port
    100000    2   tcp    111  portmapper
    100000    2   udp    111  portmapper
    100024    1   udp   1005  status
    100024    1   tcp   1008  status
    100011    1   udp    833  rquotad
    100011    2   udp    833  rquotad
    100011    1   tcp    836  rquotad
    100011    2   tcp    836  rquotad
    100003    2   udp   2049  nfs
    100003    3   udp   2049  nfs
    100003    4   udp   2049  nfs
    100021    1   udp  55689  nlockmgr
    100021    3   udp  55689  nlockmgr
    100021    4   udp  55689  nlockmgr
    100003    2   tcp   2049  nfs
    100003    3   tcp   2049  nfs
    100003    4   tcp   2049  nfs
    100021    1   tcp  39321  nlockmgr
    100021    3   tcp  39321  nlockmgr
    100021    4   tcp  39321  nlockmgr
    100005    1   udp    860  mountd
    100005    1   tcp    863  mountd
    100005    2   udp    860  mountd
    100005    2   tcp    863  mountd
    100005    3   udp    860  mountd
    100005    3   tcp    863  mountd

If you do not see entries for portmapper, nfs and mountd when you run the command on your own server installation, you will need to start the daemons.

The following table details files that are associated with the NFS service and the information they provide:
/etc/exports | Information about how file systems should be exported by exportfs.
/var/lib/nfs/etab | Information about what filesystems should be exported, to what user, and what level of security.
/var/lib/nfs/rmtab | Lists filesystems that are currently mounted and by what clients.
/proc/fs/nfs/exports | Information about filesystems that are currently exported to an actual client (not subnet).
/var/lib/nfs/xtab | Contains the same information as /proc/fs/nfs/exports but is maintained by nfs-utils instead of directly by the kernel. It is only used if /proc is not mounted.
Parent topic: Using NFS


To set up an NFS server

To set up the NFS server you need to set up the configuration files and start NFS.

Setting up the configuration files

There are three main configuration files you will need to edit to set up an NFS server:
  • /etc/exports
  • /etc/hosts.allow
  • /etc/hosts.deny

For NFS to work, you only need to edit /etc/exports. However, this might result in an insecure setup and it is strongly recommended that the relevant changes are made to /etc/hosts.allow and /etc/hosts.deny to prevent security problems.

The /etc/exports file contains a list of entries indicating a shared volume and how it is shared. For a detailed description of setup options for the file type man export at the command prompt. To add a new entry to the file:
  1. Open the file with a file editor.
  2. Add the following line:
    directory client(option[,option...])
where:
  • directory is the directory that you want to share. If you share a directory, then all directories under it within the same file system will be shared as well.
  • client is the client machine that will have access to the directory. It can be listed by DNS or IP address.
  • option is a listing for the client machine that describes the access that machine will have to the directory. For a full list of options type man exports at the command prompt. Some of the more common options include:
    ro | The default value. The directory is shared read only and the client machine will not be able to write it.
    rw | The client machine will have read and write access to the directory.
    no_root_squash By default, any file request made by user root on the client machine is treated as if it is made by user nobody on the server. If this option is selected is selected, then root on the client machine will have the same level of access to the files on the system as root on the server.
    Note: Please note the potential security implications with this option.
For example:
/home/user1/eclipse_workspace 192.168.0.1(rw,no_root_squash)

Starting the server

The portmap and associated rpc daemons need to be running before you can start NFS. Refer to the topicTo verify that NFS is running.

To start NFS, from a command prompt type:
/etc/init.d/nfs start

Changes to /etc/exports

If you make changes to /etc/exports and the NFS server is already running, you will need to force nfsd to read /etc/exports to apply the changes. From a command prompt type:
usr/sbin/exportfs -ra
Parent topic: Using NFS
Related tasks
To verify that NFS is running


To set up an NFS client

The client machine must be configured in /etc/exports on the server machine and the NFS service must be started. You must also ensure that:
  • the mount command is version 2.1 or later. To check the version, enter the following at a command prompt:
    mount -V
  • the NFS file system is supported. The /proc/filesystems file should contain a line with an "nfs" string. If not, run the following command:
    insmod nfs
The following steps describe how you mount the remote server directory on your client machine.
From a command prompt enter the following:
mount server:remote_dir local_dir
where:
  • server is the IP address of the server with a running NFS service.
  • remote_dir is the remote directory you want to mount on your client machine.
  • local_dir is the local directory. It must already exist on the local machine.

For example:

mount 10.123.11.189:/home/user1/workspace /home/user1/mnt/
Parent topic: Using NFS


Using Samba

Restriction: This functionality requires Micro Focus Enterprise Developer UNIX Components.

A Samba drive works like any other drive connected to the machine: for example Windows Explorer and drag and drop functionality are all available. Dragging a file onto a remote Eclipse project will add the file to the project and transfer the file to the server with correct CRLF settings.

If a project is created on a remote drive, the drive must be available for the project to open in Eclipse. If the drive is disconnected and off the network then the project will remain closed until the connection is reestablished.

Parent topic: Working with file systems on remote machines
Related concepts
Using Remote System Explorer (RSE)
Using NFS


Creating remote projects

Restriction: You must have Micro Focus Enterprise Developer UNIX Components installed on the remote machine.
You can create the following types of remote COBOL project:
  • COBOL (native and managed)
  • Mainframe
  • Copybook

Alternatively, you can take an existing project, stored locally on your machine, and convert it to a remote project. The remote project is stored, edited, debugged and run on the remote machine. The source project also remains in its original location, on your machine.

If you are using PL/I there are remote PL/I projects, too. See Creating Remote PL/I projects for more information.

  • To create a remote COBOL project
  • To create a remote mainframe project
  • To create a remote COBOL copybook project
  • To change the connection type of a remote project
    Steps required to alternate the connection type of a remote project.
  • To convert a local COBOL project to a remote COBOL project
Parent topic: Developing applications on remote machines


To create a remote COBOL project

Restriction: This feature requires that Micro Focus Enterprise Developer UNIX Components is installed on the remote machine.
  1. While in the Team Developer perspective, click File > New > Other.
  2. Expand Micro Focus COBOL.
  3. Click Remote COBOL Project, and then click Next.
  4. In the Remote COBOL Project wizard, type a project name.
  5. Choose whether to use a remote file system (RSE) or a network file system (Samba, NFS) to interact with the remote host.
    Restriction: The Classic Data File Tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type.

    The Network File System (NFS) protocol allows a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.

  6. If you want to create a JVM COBOL remote project, choose JVM byte code as the COBOL compilation target.
  7. Click Next. If prompted, select the required project template and click Next.
    Note: By default, two templates are available for you to choose from Micro Focus template [32 bit] or Micro Focus template [64 bit]. Select a template that best suits your requirements.
  8. If you chose the network file system (Samba, NFS), in the Location field, specify the path to the project.
    Tip: Select Use default location to use your current workspace.
  9. In the Remote settings section, in the Connection name field, choose the remote host.
    Note: If the remote host connection is not listed when you click the Connection name field, click New Connection and use the New Connection wizard to create a new connection.
  10. In the Remote location field, enter the location of the project on the remote host. You can use the Browse dialog box to browse the remote host's file system.

    For a network file system such as NFS or Samba, the Remote location value should be the UNIX/Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive-location\project-name should be represented by a remote location of /home/users/my-folder.

  11. If you are creating a native project, click Finish; otherwise, click Next.
  12. For JVM COBOL projects, you must select a JRE to run on the host. Select a specific JRE or use the default JRE for the remote host.
    Note: If the JRE you require is not listed, click Configure remote JREs and use the Remote JREs section to add the required JRE.
  13. Click Finish.

    The project is created and appears in the Team Developer view.

To change any of the connection settings afterwards, open the Remote Systems Explorer perspective, right-click on the connection and select Properties > Connector Services.

Important: If you use one of the non-Micro Focus connection types (for example 'Linux' or 'Unix') from the Remote System Explorer perspective to create a connection, choose SSH as the file system provider if you intend to use the connection for remote projects whose file system is RSE. You do this by selecting ssh.files in the Configuration box at the Files step of the wizard. Selecting a different file system provider will cause performance and stability problems. The remote host must have SSH installed and enabled.

RSE is a feature supplied by the Eclipse Foundation. Extensive documentation on RSE, including architecture, API, tutorials and reference can be found on the Eclipse website.

Parent topic: Creating remote projects
Related concepts
To change the connection type of a remote project
Related tasks
To create a remote mainframe project
To create a remote COBOL copybook project
To convert a local COBOL project to a remote COBOL project
Related information
To launch a server on the remote host


To create a remote mainframe project

Restriction: This feature requires that Micro Focus Enterprise Developer UNIX Components is installed on the remote machine.
  1. While in the Team Developer perspective, click File > New > Other.
  2. Expand Micro Focus COBOL.
  3. Click Remote Mainframe COBOL Project, and then click Next.
  4. In the Remote Mainframe COBOL Project wizard, type a project name.
  5. In the Choose file system list, select the file system you want to use and click Next.
    Restriction: The following tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type:
    • BMS Painter
    • BMS Compiler
    • All Classic Data File Tools
    • IMS Database editor and segment layout editor
    • Mainframe Assembler compiler
  6. If you have created your own COBOL project templates, you can select one of them from the Select a project template box. Alternatively, check Browse for template and click Browse to navigate to the location of the template and select it; then click Next.
    Note: By default, two templates are available for you to choose from Micro Focus template [32 bit] or Micro Focus template [64 bit]. Select a template that best suits your requirements.
    • If you specify a network file system (Samba or NFS) project:
      1. Check the Use default location to populate the Location field with the default workspace path and project name. Alternatively, type the full project path in the Location field or click Browse to select the location.
      2. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
        Note: For network file systems such as NFS or Samba, the Location value should be the UNIX/Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive location\project name should be represented by a remote location of /home/users/my-folder.
    • If you specify a remote file system (RSE) project:
      1. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
  7. Click Finish.

    The project is created and appears in the Application Explorer view.

To change any of the connection settings afterwards, open the Remote Systems Explorer perspective, right-click on the connection and select Properties > Connector Services.

RSE is a feature supplied by the Eclipse Foundation. Extensive documentation on RSE, including architecture, API, tutorials and reference can be found on the Eclipse website.

If you are creating a Micro Focus Mainframe COBOL Project or Remote Mainframe Project
By default, the COBOL Explorer view shows JCL programs (which have an extension of .jcl), BMS mapset files (.bms), macros (.mac), and IMS resources (.dbd, .mfs, and .psb files) grouped into corresponding categories. Files with these extensions are automatically put in the requisite categories when you add them to the project.
Note: Files are not grouped into categories when viewed in Application Explorer view.
When you build the project:
  • .bms files are compiled to .MOD files and added to the bin folder for that particular build configuration.
  • if there are any .dbd files, dbd_filename.ACB, DBDGEN2.DAT, DBDGEN2F.DAT and dbd_filename.LST are created and added to the project.
  • if there are any .psb files, PSBGEN3.DAT and psb_filename.LST are created and added to the project.
  • if there are any .mfs files, mfs_filename.LST is created and added to the project.
Parent topic: Creating remote projects
Related concepts
To change the connection type of a remote project
Related tasks
To create a remote COBOL project
To create a remote COBOL copybook project
To convert a local COBOL project to a remote COBOL project


To create a remote COBOL copybook project

Restriction: This feature requires that Micro Focus Enterprise Developer UNIX Components is installed on the remote machine.
  1. While in the Team Developer perspective, click File > New > Other.
  2. Expand Micro Focus COBOL.
  3. Click Remote COBOL Copybook Project, and then click Next.

    The Remote COBOL Copybook Project wizard appears.

  4. In the Remote COBOL Copybook Project wizard, type a project name.
  5. Choose whether to use a remote file system (RSE) or a network file system (Samba or NFS) to interact with the remote host, then click Next.
    Restriction: The Classic Data File Tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type.

    The Network File System (NFS) protocol allows a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.

  6. Select the required project template, then click Next.
  7. If you chose the network file system (Samba or NFS), in the Location field, specify the path to the project.
    Tip: Select Use default location to use your current workspace.
  8. In the Remote settings section, in the Connection name field, choose the remote host.
    Note: If the remote host connection is not listed when you click the Connection name field, click New Connection and use the New Connection wizard to create a new connection.
  9. In the Remote location field, enter the location of the project on the remote host. Click Browse to browse the remote host's file system.

    For a network file system such as NFS or Samba, the Remote location value should be the UNIX/Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive location\project name should be represented by a remote location of /home/users/my-folder.

  10. Click Finish.

    The project is created and appears in the Application Explorer view.

Parent topic: Creating remote projects
Related concepts
To change the connection type of a remote project
Related tasks
To create a remote COBOL project
To create a remote mainframe project
To convert a local COBOL project to a remote COBOL project


To change the connection type of a remote project

If you have SSH connection types, you can change the connection mode of remote projects from remote file system (RSE) to network file system like Samba or NFS and vice versa. For example, you might need to do this if you want to add your project to Subversion, which requires a Samba connection.

To change the connection type:

  1. In COBOL Explorer, right-click your remote project and click Remote Settings.

    This starts the Remote Project Connection Details dialog box.

    1. To change the Connection mode to RSE, click Remote file system (RSE):
      1. If a remote file system (RSE) connection already exists, you can select it from the Connection name drop-down list. If there are no RSE connections, you need to create one. To create a new connection, click New Connection.
      2. In Remote location, specify the path to the project on the remote machine or click Browse to navigate to and select the directory on the remote machine that holds your project.
    2. To change the Connection mode to network file system, click Network file system:
      1. If a network file system connection already exists, you can select it from the Connection name drop-down list. If there are no network file system connections, you need to create one. To create a new connection, click New Connection.
      2. In Remote location, specify the path to the project on the remote machine or click Browse to navigate to and select the directory on the remote machine that holds your project. The Remote location value should be the UNIX/Linux representation of the path as specified in Local location.
      3. In Local location, specify the path to the project on your machine. This can be any UNC path. Alternatively, click Browse to navigate to and select the directory on your machine that holds your project.
        Note: Local location can point to a folder on a mapped or a mounted drive.
  2. Click OK.
Note: Changing the project's connection type can result in the project losing the connection to its version control system. To re-establish connection, perform the following steps:
  1. Right-click your project.
  2. Click Team > Share Project.

    This opens the Share Project dialog box.

  3. Click the repository type you want to re-establish connection with.
  4. Click Next.

    This opens the Share Project Wizard dialog box.

  5. Select the required repository location.
  6. Click Finish.
Parent topic: Creating remote projects
Related tasks
To create a remote COBOL project
To create a remote mainframe project
To create a remote COBOL copybook project
To convert a local COBOL project to a remote COBOL project


To convert a local COBOL project to a remote COBOL project

Restriction: This feature requires that Micro Focus Enterprise Developer UNIX Components is installed on the remote machine.
  1. In the Team Developer perspective, click File > Import.
  2. Expand the Micro Focus folder, select Convert Local Micro Focus Projects to Remote Projects, then click Next.

    The Convert Local Micro Focus Projects to Remote Projects wizard appears.

  3. Click Browse, select the workspace containing the project, then check the project to convert or click Select All if you want to import multiple projects.
  4. Choose whether to use a remote file system (RSE) or a network file system (Samba or NFS) to interact with the remote host.
    Restriction: The following tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type:
    • BMS Painter
    • BMS Compiler
    • All Classic Data File Tools
    • IMS Database editor and segment layout editor
    • Mainframe Assembler compiler

    The Network File System (NFS) protocol allows a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.

    • Click Next.
      • If you specify a network file system (Samba, NFS) project:
        1. Check Use default location to populate the Location field with the default workspace path and project name. Alternatively, type the full project path in the Location field or click Browse to select the location.
        2. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
          Note: For network file systems such as NFS or Samba, the Remote location value should be the UNIX/Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive-location\project-name should be represented by a remote location of /home/users/my-folder.
      • If you specify a remote file system (RSE) project:
        1. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
        2. Click OK.
  5. If you are converting a native project, click Finish; otherwise, click Next.
  6. For JVM COBOL projects, you must select a JRE to run on the host. Select a specific JRE or use the default JRE for the remote host.
    Note: If the JRE you require is not listed, click Configure remote JREs and use the Remote JREs section to add the required JRE.
  7. Click Finish.

    The project is created and appears in the Application Explorer view.

RSE is a feature supplied by the Eclipse Foundation. Extensive documentation on RSE, including architecture, API, tutorials and reference can be found on the Eclipse website.

Parent topic: Creating remote projects
Related concepts
To change the connection type of a remote project
Related tasks
To create a remote COBOL project
To create a remote mainframe project
To create a remote COBOL copybook project


Building COBOL applications

To build an application, you need to compile its programs and link them to a run-time system. In the IDE, you use a build configuration to define how to do this.

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

Note: When working with local SQL applications on UNIX, ensure the RDBMS environment is set before you start Eclipse. Refer to your RDBMS vendor's documentation for details.

Enterprise Developer Build Tools for Windows

Enterprise Developer Build Tools for Windows is a separately-installable component of Enterprise Developer that has been designed to be used in environments where you want to work with your COBOL and PL/I projects but you don't want the overheads associated with the Eclipse IDE.

For more information see Enterprise Developer Build Tools for Windows.

Compiling the Files in a Project in Parallel

Restriction: Multi-processor compilation of the sources in a project is only supported for native COBOL and is not supported for JVM COBOL applications. It should be avoided for native Object-Oriented COBOL applications.

You can compile your source code faster on multi-CPU machines if you enable parallel compilation in the IDE. This option works with a full project build and not with the Compile context menu command.

Click Window > Preferences > Micro Focus > Builder and specify the Maximum number of compilations to execute concurrently. The maximum number of cores to be used is the number of cores of the machine on which the build is being run.

  • Compiling COBOL Applications
  • Linking Native COBOL Code (Windows)
  • Linking (UNIX)
  • To clean a project
    Cleaning a project discards all build problems and build states.
  • Tips: Building COBOL projects
  • How To in the IDE
Parent topic: Developing Applications in the IDE
Related concepts
Building Applications in Eclipse
Compiling JVM COBOL
Compiling and building a PL/I project
Related information
Enterprise Developer Build Tools for Windows


Compiling COBOL Applications

Before you can run a program, you have to compile the source code.

  • Compiling COBOL code
  • Compiled File Types
  • Compiling JVM COBOL
  • To Build a Project Using Apache Ant
  • Setting Compiler Directives for COBOL
  • Using Environment Variables
  • Order in Which Copybooks are Searched For
  • Temporary Files Used when Compiling Native COBOL
  • Techniques for Compiling Quickly
  • Using Preprocessors
    Choose either an SQL or another additional preprocessor to compile your applications with. These include preprocessors installed with Enterprise Developer, or any third-party preprocessors available on your machine.
Parent topic: Building COBOL applications
Related information
Command line reference
Order in Which Copybooks are Searched For
Setting Directives Outside the IDE
Compiling and Linking from the Command Line (UNIX)
The cobol command
cbllink


Compiling COBOL code

Before you can run a program, you have to compile the source code.

By default, your project is built automatically, every time you save the project. This ensures that whenever a resource changes, an incremental build starts and all resources modified since the last build are rebuilt. You can force a manual build too, by cleaning the project.

You can configure the compilation using the following techniques:

  • Build Configurations. You specify the build settings in either the project language settings or the build configuration. Click Project > Properties, expand Micro Focus and select Build Configurations. The configuration that will be used is marked as [Active]. To change the active configuration, click Manage Configurations and select the required configuration from the list.
  • 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 produce 32- and 64-bit applications from the same source code by setting the Platform Target option in the IDE. You can also compile bit-specific output from the command line by using the cobol command from the 32-bit or 64-bit command prompt (Windows), or by using the cob32, cob64 or cobol (in conjunction with the COBMODE environment variable) commands (UNIX).
  • 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 in the IDE, and also 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.

    On multi-CPU machines, you can enable faster, parallel multi-processor compilation of multiple files in native COBOL projects from Window > Preferences > Micro Focus > Builder.

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. On Windows, this means setting the system locale in the 'Region and Language' section of Control Panel.

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 in the IDE

By default, Eclipse is configured to build projects automatically whenever you save a file or change a file's or the project's properties. You can turn off automatic building from Window > Preferences > General > Workspace and unchecking Build automatically.

If automatic builds are not disabled, you can build a project at any time by selecting the project in the Application Explorer view and clicking Project and then Build Project to build the currently selected project, Build All to build all projects in the current workspace, or Build Working Set to build a subset of the projects in the workspace.

Important: For applications that use a RDBMS, you might need to set some additional directives in your build configuration.

Compiling from the command line

Using the command line, you can compile without linking using the cobol command (Windows), or compile and link your program in one step using the cbllink utility (Windows) or cob (UNIX) 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.

Errors reported during a build

Eclipse reports any errors found in your sources in the Problems and in the Console views.

To navigate to the line of code that generates an error, double-click on the error in the Problems view that has a line number.

Alternatively, follow the link for the source file that has the error in the Console view. In most scenarios, if the error occurred in copybook, following the link in the Console view will open the copybook in context of the source file that references it. If the copybook is referenced by a remote standalone source file, however, then it will not be opened in context.

A limit of 10,000 build errors is set for this product. If this number is reached, Eclipse aborts the build to prevent the build from taking up too much memory on the machine. Some of the source files might not compiled. To compile your application, you need to fix the issues that are reported and then rebuild the entire project.

Parent topic: Compiling COBOL Applications
Related reference
Command line reference


Compiled File Types

Before you can run or debug your program it must be in a form that can be executed. The Compiler can produce the following types of files:

Executable code
You produce executable code by compiling and linking in one step.

An executable file has a filename extension of .exe (Windows) or no filename extension (UNIX).

To create executable code, you need either a COBOL project or a remote COBOL project. Select Project > Properties > Micro Focus > Build Configuration and create or edit a configuration, choosing a Target types option of All Executable Files or Single Executable File.

Object code
Object code files are created when you build your project. 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 .obj (Windows) or .o (UNIX).

Object code files must be linked to create .exe or .dll files (Windows) or executable, callable shared object or shared library files (UNIX).

Java bytecode
Java bytecode can be executed on a Java Virtual Machine (JVM).

You create a JVM COBOL project in the IDE in a similar way as you create any COBOL project and many of the configuration options are common to both. Select File > New > COBOL JVM Project.

A Java bytecode file has a filename extension of .class.

Intermediate code
Restriction: It is not possible to build JVM COBOL code to .int files.
Intermediate code files are usually for testing and debugging. The Compiler creates the intermediate code file during its first phase, when it checks the program syntax. The Compiler also creates a dictionary file, which is used by the debugger. Intermediate code files compile quickly.

Intermediate code files have the extension .int.

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

To compile to intermediate code files, set the following properties:
  1. Click Project > Properties > Micro Focus > Build Configuration and create or edit a configuration, choosing a Target types option of All Int/Gnt Files.
  2. Click Project > Properties > Micro Focus > Project Settings > COBOL and make sure Compile to .gnt is not selected.
Tip: You can check Override Project Settings in the build configuration properties and specify to produce a set of either .int or .gnt files for a specific build configuration. To produce a mixture of .int and .gnt files from one build configuration, modify the individual file properties - right-click on individual files and check Override Project Settings. Then, either check or clear Compile to .gnt to compile to .int or .gnt, respectively.
Generated code
Restriction: It is not possible to build JVM COBOL code to .gnt files.

The Compiler creates the generated code, on request, during its second phase. Generated code is slower to compile than intermediate code but the resulting code runs faster.

Use generated code files for testing and debugging. As generated code runs faster than intermediate code, it can be useful in debugging for large programs, or for debugging programs where the distance between breakpoints is large, for example.

Generated code files have the extension .gnt.

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

To compile generated code files set the following properties:
  1. Click Project > Properties > Micro Focus > Build Configuration and create or edit a configuration, choosing a Target types option of All Int/Gnt Files.
  2. Click Project > Properties > Micro Focus > Project Settings > COBOL and select Compile to .gnt.
Dynamic Link Libraries (Windows) or Callable shared objects (UNIX)
Dynamic link libraries (Windows) or callable shared objects (UNIX) are dynamically loaded at run time when required; that is, when referenced as a main entry point (for example, by run (Windows) or cobrun (UNIX)) or by the COBOL CALL syntax. When all the entry points in a Dynamic Link Library (Windows) or a callable shared object (UNIX) 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 (Windows) or a callable shared object (UNIX) can contain more than one COBOL program and can also contain other language programs, such as C and C++. Dynamic link libraries (Windows) or callable shared objects (UNIX) 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 Dynamic Link Library (Windows) has a filename extension of .dll.

A callable shared object file (UNIX) has a filename extension of .so.

To create dynamic link libraries (Windows) or callable shared objects (UNIX), you need either a COBOL project or a remote COBOL project. Select Project > Properties > Micro Focus > Build Configuration and create or edit a configuration, choosing a Target types option of All Native Library Files or Single Native Library File.

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:

  1. Click Project > Properties > Micro Focus > Build Configuration and create or edit a configuration, choosing a Target types option of All Int/Gnt Files.
  2. Select Package as .lbr.
Next time you build your project, the project builds .int or .gnt files as normal, and also includes them all into an .lbr file.
Restriction: You cannot compile .lbr files for JVM or mainframe projects.
Parent topic: Compiling COBOL Applications
Related concepts
Features Added in Enterprise Developer 2.1
Delegates and Events
IBM External Call Interface (ECI)
Starting the debugger automatically using just-in-time debugging
Getting Started


Compiling JVM COBOL

Important:

The IDE runs a Clean command before each build that deletes all .class files in the output folder of the JVM COBOL project.

JVM COBOL Classpath

Usually, programs in JVM COBOL projects use types that come from external artefacts like .class and .jar files. To successfully compile and build such projects, you must set a JVM COBOL classpath. You set this in the projects' properties on the Libraries tab in Micro Focus > Java Build Path.

Setting the JAVA Installation Directory

If you are developing a Java or JVM COBOL project, you do not have to set the Java installation directory using the JAVA_HOME variable. Follow these steps to identify the JRE using the Properties dialog box:

  1. Click Project > Properties.
  2. Click JVM Build Path and select the Libraries tab.
  3. Click JRE System Library and click the Edit button.
  4. Select Alternate JRE and then click Installed JREs to select the JRE you want to use.

Building JVM COBOL Projects Incrementally

By default, Eclipse automatically recompiles all sources in your project every time you save the project or when you change the project or file properties. This, however, could mean a considerable overhead when you have large projects. To avoid this, you can configure your project to only build the sources that have changed since the last time the project was built - this is known as incremental building.

In Enterprise Developer, you can specify that a JVM COBOL project is built incrementally. How you specify this depends on the following:

  • JVM COBOL projects containing any mixture of procedural COBOL and class programs.

    To enable this feature, you need to specify the Use incremental build (Technical preview feature) setting. This is equivalent to setting the ILINCREMENTALBUILD Compiler directive. When this directive is specified, Eclipse only recompiles programs that have changed and programs that refer to types or programs within those programs that have changed. Incremental builds will only take effect once you have a clean build environment with no errors. Having build errors will result in a failure to generate class files, a full build will continue until the errors are resolved.

    Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.
    1. Right-click your project in COBOL Explorer and click Properties.
    2. Click Micro Focus > Build Configuration.
    3. Check Use incremental build (Technical preview feature).
    4. Click Apply then click OK.

      Next time you make a change in the project, Eclipse only rebuilds the files that have changed.

    The build also creates a directory within the project output directory called JVMDependencies that stores dependency information for all the programs in your project. The JVMDependencies folder is not intended for distribution. If you want to package the contents of the output directory into a jar file, Micro Focus recommends that you turn off the incremental build feature and do a full clean rebuild.

    You can force a complete rebuild of the project manually by selecting Project > Clean.

    Note:

    Micro Focus recommends that you clean your project and build before packaging for distribution.

  • JVM COBOL projects that contain procedural code or extensions that take advantage of features of the managed frameworks including object-oriented (OO) syntax, and that compile as a JVM COBOL applications to Java byte code:

    You can enable the use of dynamic calls, which is equivalent to setting the ILDYNCALL Compiler directive that ensures that files in the project are compiled one at a time and that the build does not compile all files for one single compile command. It resolves calls to modules at run time rather than compile time; this has the effect of not requiring every module to be built.

    To enable dynamic calls:

    1. Right-click your project in COBOL Explorer and click Properties.
    2. Click Micro Focus > Build Configuration.
    3. Check Use dynamic calls.
    4. Click Apply then click OK.

      Next time you make a change in the project, Eclipse only rebuilds the files that have changed.

    You can force a complete rebuild of the project manually by selecting Project > Clean.

    Tip: For maximum efficiency, Micro Focus recommends that you turn off the Use dynamic calls option, and clean your project before building and packaging it for distribution.
Parent topic: Compiling COBOL Applications
Related concepts
Technology Preview Features
Related tasks
JVM COBOL support
Related reference
ILDYNCALL


To Build a Project Using Apache Ant

Setting up Apache Ant

Before you use Apache Ant you need to perform the following set up:

  • For UNIX, a version of Apache Ant is included with the product. This can be found in the $COBDIR/remotedev/ant folder. To configure Ant for use:
    1. Set ANT_HOME to the root directory of the Apache Ant distribution:
      export ANT_HOME=$COBDIR/remotedev/ant/apache-ant-1.9.9
    2. Add the bin directory to the PATH so that Ant can be executed:
      export PATH=$ANT_HOME/bin:$PATH
  • For Windows, you need to download and install Apache Ant version 1.7.1 or later. To download Apache Ant 1.10.2:
    1. Click here, in the left pane click Binary Distributions.
    2. Click apache-ant-1.10.2-bin.zip to download.
    3. Extract the content of the zip file to a new folder.
    4. Set ANT_HOME to the root directory of the Apache Ant distribution:
      SET ANT_HOME=<ant_path>
    5. Add the Ant binary directory to the PATH environment variable:
      SET PATH=%PATH%;<ant_path>\bin

Building using Apache Ant

Enterprise Developer uses an Apache Ant script, .cobolBuild, to build COBOL projects. This script is automatically generated from the .cobolProj project file.

Existing external build scripts such as makefiles, MSBuild, shell scripts and others can build COBOL applications using .cobolBuild as an Ant build file.

If you use an Ant file from a project developed on a remote machine using the Micro Focus Enterprise Developer UNIX Components, the application is built on the machine running Ant. This is how you use .cobolBuild to perform a full build of a project:
From a Windows command prompt:
ant -lib %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar -f .cobolBuild
From a UNIX command prompt:
ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild

You can compile your source code faster on multi-CPU machines if you use parallel compilation. To do this, you must add the threadCount=nn parameter. Where nn specifies the number of CPU threads to use:

From a Windows command prompt:
ant -lib %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar -f .cobolBuild -DthreadCount=2
From a UNIX command prompt:
ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild -DthreadCount=2
Restriction: Multi-processor compilation of the sources in a project is only supported for native COBOL. It is not recommended to use with native Object-Oriented COBOL applications.
To perform an incremental build:
From a Windows command prompt:
ant -lib %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar -f .cobolBuild -DforceCompile=false
From a UNIX command prompt:
ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild -DforceCompile=false
Note: You can avoid having to specify the -lib option by adding the mfant.jar to your CLASSPATH.

For UNIX:

export CLASSPATH=$CLASSPATH:$COBDIR/lib/mfant.jar

For Windows:

SET CLASSPATH=%CLASSPATH%;%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar
You can combine the threadCount and forceCompile parameters to perform a faster incremental build.
Note: When compiling to multiple executables from the command line, you must specify the -logger parameter to enable the correct log to be output to the console:
-logger com.microfocus.ant.CommandLineLogger
Alternatively, you can specify the -logger option as an environment variable as follows:

For Windows:

set ANT_ARGS=-logger com.microfocus.ant.CommandLineLogger

For UNIX:

export ANT_ARGS=-logger com.microfocus.ant.CommandLineLogger
From the Eclipse IDE:
  1. Click Window > Preferences > Run/Debug > Launching and clear the Build (if required) before launching option, if you do not want to trigger an Eclipse build before each Ant build.
  2. In COBOL Explorer, right-click the .cobolBuild file and click Run As > Ant Build.

You can set your own shell scripts as pre- or post-build events and they execute as part of the .cobolBuild Ant script before or after compiling.

To set pre- or post-build events:

  1. Right-click your project in the COBOL Explorer view and click Properties.
  2. Expand Micro Focus > Build Configurations and click Events for the desired configuration.
  3. Type the code of the script either in the Pre-build event command line or in the Post-build event command line field.
  4. Click Apply and then click OK.
Note:

If you reference variables in the Events field, you must prefix any linked resource path variables with ${pathVar. and terminate the variable with }. For example, code PROJECT_LOC as ${pathVar.PROJECT_LOC}.

Linked resources path variables are defined in the project's properties as follows:

  1. Right-click your project in COBOL Explorer, then click Properties > Resource > Linked Resources.
  2. See the variables listed on the Path Variables tab.
Parent topic: Compiling COBOL Applications


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.

You can set Compiler directives at three levels within the IDE from the project's properties:

  • Micro Focus > Project Settings - These settings apply to all programs in a single project.
  • Micro Focus > Build Configurations - These settings apply to a specific build configuration. Each project is associated with one or more build configurations, and directives set here override or add to those set in Project Settings.
  • COBOL and COBOL > SQL Preprocessor at the program level - the settings you specify at the COBOL page of the file properties override or add to both the project settings and the build configuration settings. You can only specify an SQL preprocessor at file level, if no preprocessor is enabled for the project or for the build configuration.
    Important: You invoke the COBOL and COBOL > SQL Preprocessor pages for an individual file by right-clicking the file and selecting Properties. Do not confuse this with the COBOL and COBOL > SQL Preprocessor pages available under Project Settings and Build Configurations.

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

Important: For applications that use an RDBMS, you might need to set some additional directives in your build configuration.
  • Setting Project-Wide Build Properties and Compiler Directives
    You can set directives that affect all files in a project during compilation.
  • Setting Compiler Directives on Individual Files
    Files in your project inherit the properties set on the project level. You can specify properties on individual files that differ from and override the project's and the build configuration properties.
  • Setting Compiler Directives from the Command Line
  • Setting Compiler Directives in a Response to a Prompt
  • Setting Compiler Directives in Source Code
  • Setting Compiler Directives in a Directives File
Parent topic: Compiling COBOL Applications
Related information
Setting Project-Wide Build Properties and Compiler Directives
Compiling from the Command Line (Windows)
Compiler Directives
Setting Directives Outside the IDE
Building DB2 Applications with Eclipse
Building COBSQL Applications with Eclipse
COBSQL Compiler Directive Options
DB2 Compiler Directive Options
Setting Compiler Directives on Individual Files


Setting Project-Wide Build Properties and Compiler Directives

Project Settings

All directives specified are used when a project compiles, apart from those overridden by settings for individual files or build configurations.

  1. Click Project > Properties.
  2. Expand Micro Focus.
  3. Expand Project Settings.
  4. Use the dialog boxes to choose your settings:
    COBOL
    1. Click COBOL.
    2. Type the directives into the Additional directives text box. Separate each directive with a space.
    3. If you do not require SQL Preprocessor compiler directives, click OK; otherwise, click Apply.
    COBOL > SQL Preprocessor
    Enables you to choose an SQL Preprocessor and the compiler directives you want to use.
    1. Expand COBOL; then click SQL Preprocessor.
    2. Check Use SQL Preprocessor.

      You can only specify an SQL preprocessor at file level, if no preprocessor is enabled for the project or for the build configuration. In this case, the preprocessor that is available at file level is the last one used at project level.

    3. From the Preprocessor Type drop-down list, choose a preprocessor.
    4. On the Directives grid, complete the Value field for each directive you want to set; then click Apply.

      The SQL Compiler directives you have selected appear in the SQL Directives text box.

    5. Click OK.

Build Configurations

Enables you to configure the output of the build process, including names and locations of output files and whether the build is for debugging purposes. You can also specify further directives for linking and command line processing. Build configurations override project settings:

  1. Click Project > Properties.
  2. Expand Micro Focus.
  3. Click Build Configurations and choose a configuration, or create a new one by clicking Manage Configurations, then Add Build Configuration.
  4. To override directives set in Project Settings, use the COBOL and SQL Preprocessor entries under Build Configurations:
    COBOL
    1. Click COBOL.
    2. Expand Override project COBOL settings.
    3. Check Enable configuration specific settings.
    4. Type the directives into the Additional directives text box. Separate each directive with a space.
    5. If you do not require SQL Preprocessor compiler directives, click OK; otherwise, click Apply.
    COBOL > SQL Preprocessor
    1. Expand COBOL; then click SQL Prepocessor.
    2. Check Enable configuration specific settings and Use SQL Preprocessor.
    3. From the Preprocessor Type drop-down list, choose a preprocessor.
    4. On the Directives grid, complete the Value field for each directive you want to set; then click Apply.

      The SQL Compiler directives you have selected appear in the SQL Directives text box.

    5. Click Apply.
    6. Build configurations can use further directives for linking and command line processing. Use the following dialog boxes to choose your settings, otherwise, click OK:
    Events
    Enables you to write command line entries to be run before and after the build takes place. Include directives as part of any command line instruction you enter in the Pre-build event command line and Post-build event command line text boxes.
    Note:

    If you reference path variables within Events, you must prefix any variable with ${pathVar. and terminate the variable with }, for example - you must code PROJECT_LOC as ${pathVar.PROJECT_LOC}.

    To use environment variables in events you must set (Windows) or export (UNIX) the variables in the operating system, before starting Eclipse. The scope of a changed environment variable is limited to the build event in which it is made and lasts for the duration of that event.

    Link
    Enables you to configure how the application links to the run-time system, including resource files and other items to be linked. Expand Additional Link Directives and enter the directives in the text box.

The Compiler directives are saved with the project, so that they are used on all files in the project the next time you build the project.

Most directives are overridden by directives specified for individual source files. You can only specify an SQL preprocessor or an additional preprocessor at file level, if no preprocessor is enabled for the project or for the build configuration. In this case, the preprocessor that is available at file level is the last one used at project level.

Parent topic: Setting Compiler Directives for COBOL
Related information
Compiling from the Command Line (Windows)
Compiler Directives
Setting Directives Outside the IDE


Setting Compiler Directives on Individual Files

Files in your project inherit the properties set on the project level. You can specify properties on individual files that differ from and override the project's and the build configuration properties.

Files that are part of a project

To set properties on individual files in a project:

  1. In the COBOL Explorer view, right-click the file you want to change.
  2. Click Properties > COBOL.
  3. Do one or more of the following:
    • To set COBOL properties and directives:
      • Check Enable file specific settings.
      • Set properties using the appropriate fields and controls.
      • Click in the Additional directives field and type the directives to be used when compiling this file. Separate each directive with a space.

        To guarantee that a directive set in a project or build configuration does not apply to a particular file, you must explicitly specify NO<DIRECTIVE> (for example, NOLOCALSOURCEFORMAT or NODATAMAP).

      • Click OK.
    • To set a preprocessor and SQL compiler directive options:
      1. Expand COBOL and click SQL Settings.
      2. Check Enable file specific settings and EXEC SQL.
      3. From the Preprocessor Type drop-down list, select the preprocessor you want to use.
      4. On the Directives grid, complete the Value field for each directive you want to set; then click Apply.

        The SQL compiler directives you have selected appear in the SQL Directives text box.

      5. Click OK.
  4. To specify whether or not to compile the file, right-click the file and click Build Action > Compile or Build Action > Ignore as required. By default, files with a .cbl extension are compiled and copybooks (.cpy) are not.

Standalone files

The following functionality is only supported for native COBOL.

Standalone files are files that are opened in the IDE without a project.

When compiling a standalone COBOL program, the IDE first searches for the program's symbols file (.idy) which includes the Compiler directives to use. It searches for the file either in the location of the COBOL program or in any directory specified in Window > Preferences > Micro Focus > COBOL > Standalone Files > Program Symbols (.IDY). If no program symbols file is found, the IDE uses the Compiler directives specified on the Compile properties page in Window > Preferences > Micro Focus > COBOL > Standalone Files.

To specify Compiler directives for compiling standalone files in the IDE:

  1. Open a COBOL program in the editor using File > Open File.
  2. Click Window > Preferences > Micro Focus > COBOL > Standalone Files > Compile and ensure the Compiler directives to use with standalone files are as required. The default directives are as follows:
    • nognt int() anim for the 32-bit Eclipse.
    • nognt int() anim P64 for the 64-bit Eclipse.

    For example, to specify the locations of any copybooks used in the standalone file when the copybooks are not in the same location, set the COPYPATH Compiler directive, COPYPATH(<location1>;<location2>;...).

    If you have changed these directives, to reset them to the default values, click Restore Defaults.

  3. Ensure the Compiler directives are as required, then click OK.
Parent topic: Setting Compiler Directives for COBOL
Related concepts
Compile for Debugging
Overview of the process of debugging


Setting Compiler Directives from the Command Line

When you compile from the command line using the cobol (Windows) or cob (UNIX) command, you include any directives as part of the command. This applies to command line fields in the IDE (for example the Command line arguments field of a Debug Configuration's Start Options) and any compilation started from a prompt.

Parent topic: Setting Compiler Directives for COBOL


Setting Compiler Directives in a Response to a Prompt

Restriction: This topic applies to Windows environments only.

You can supply all or part of the command line as a response file, which is an ASCII text file containing options for the command. You give the name of the response file on the command line, preceded by an at character (@). This name is replaced in the command by the contents of the file. Within the response file, the end of a line is equivalent to a comma separating filenames or a space between directives beyond the last comma.

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:
    • In the project's properties, click Micro Focus > Project Settings > COBOL.
    • Specify the following in the Additional directives field:
      USE"path\directivesfile"

      where path can be relative to the project.

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


Using Environment Variables

To use environment variables with your applications, you need to specify them on the Build Environment properties page in the project's or the build configuration's settings. Building the project adds the information about the variables to the application.

You can also specify environment variables that only apply at run time. You specify these in the run or debug configuration of the application and specify that the configuration inherits the values from the project's build configuration properties or specify variables that are different to these.

  • To specify environment variables for an application
  • Editing variables in the build environment
    You can edit environment variables in the project settings and build configurations.
  • Removing variables in the build environment
    You can remove environment variables in the project settings and build configurations.
  • To specify environment variables in a run configuration
Parent topic: Compiling COBOL Applications


To specify environment variables for an application

You can specify environment variables to use with your applications either at a project level or for a build configuration.

  1. Click Project > Properties.
    • To specify environment variables that apply to the entire project:
      1. Expand Micro Focus > Project Settings > Build Environment.
    • To specify environment variables that only apply to a build configuration:
      1. Expand Micro Focus > Build Configurations > Build Environment.
      2. Select Build Configuration.
      3. Check Enable configuration specific settings.
  2. Specify a variable to use with your project or build configuration:
    • To manually add a variable:
      1. Click Add.

        This opens the Add variable dialog box.

      2. In the Variable field, type your variable name.
        Note: The name must not be blank and must not contain the '=' character.
      3. In the Value field, type the variable value.
      4. Click OK.
    • To specify a script that contains the environment variables to use:
      1. In the Environment script to execute field, click Browse to navigate and select the script to use.

        The script must contain the variables in the following format - set variable=value, and must not require user interaction.

      2. Click OK.
      Restriction: The script should not allow user interaction.
  3. Click Apply.
  4. Click OK.

Building the project adds the information about the variables to the application.

Note: Click Restore Defaults to remove all variables or scripts from this page.
Parent topic: Using Environment Variables


Editing variables in the build environment

  1. Click Project > Properties.
    • If you are editing the environment variables in the project settings, perform the following steps:
      1. Expand Micro Focus > Project Settings > Build Environment
    • If you are editing the environment variables for a build configuration, perform the following steps:
      1. Expand Micro Focus > Build Configurations > Build Environment
      2. Select Build Configuration.
  2. Click the row containing the variable you want to edit.

    This highlights the row.

  3. Click Edit.

    This opens the Edit variable dialog box.

  4. Edit the Variable and Value field as required.
  5. Click OK.
  6. Click Apply.
  7. Click OK.
Parent topic: Using Environment Variables


Removing variables in the build environment

Removing environment variables for your project settings or build configuration

  1. Click Project > Properties.
    • If you are removing an environment variable in the project settings, perform the following steps:
      1. Expand Micro Focus > Project Settings > Build Environment.
    • If you are removing an environment variable for a build configuration, perform the following steps:
      1. Expand Micro Focus > Build Configurations > Build Environment.
      2. Select Build Configuration.
  2. Click the row containing the variable you want to remove.
  3. Click Remove.

    Alternatively, click Restore Defaults to remove all variables and script entries from the Build Environment properties.

  4. Click Apply.
  5. Click OK.
Parent topic: Using Environment Variables


To specify environment variables in a run configuration

You can specify environment variables in a run configuration. These variables then apply only when running your application. You can either specify that the configuration uses the variables as set in the project's properties or specify other variables

To specify environment variables to use at run time:

  1. Right-click your project in COBOL Explorer and click Run As > Run Configurations.

    This opens the Run Configurations dialog box.

  2. Double-click COBOL Application.

    This creates a new run configuration for your application.

  3. In the Name field, type a name for the run configuration.
  4. Click the Environment tab.
  5. Set environment variables for the configuration as follows:
    • Click Add to specify a variable manually,

      If you specify a variable which is also specified in the project's properties, the value specified in the run configuration overrides the value specified in the project's properties.

      Or:

    • Check Inherit values from the build environment of the associated project for the configuration to use the variables set at project level.

      The configuration inherits the variables specified at project level in the following order - from the build configuration settings, or if there are no variables set in the build configuration settings, then the ones specified in the project's settings.

  6. Click Apply.
  7. To run the configuration, click Run.
Parent topic: Using Environment Variables


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.

You can define the location of your copybooks outside the project directory by specifying the copybook paths in project properties on the Dependency Paths tab, by adding copybook projects as project dependencies on the properties Projects tab, by adding them to the project as linked files or folders, or by setting the environment variable COBCPY.

Tip: Linked resources are an Eclipse concept and are supported for COBOL projects, but Micro Focus recommends you use project dependencies where possible, and create projects to contain the resources and define an appropriate dependency between them.
You can choose the order in which to search these copybook locations by clicking Project > Properties > Micro Focus > Build Configurations > Build Path > Dependency Paths and arranging the folders into the required order.
Tip: In order to increase the speed of indexing and background parsing, we recommend you deselect paths that don't contain copybooks.

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 the paths specified in the Dependency Paths list in the project properties.

    If you have included any copybook projects as project dependencies, they are included in this list.

  4. 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
Related concepts
COPYEXT
Using source files from outside your project


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 TMP (Windows) or TMPDIR (UNIX) environment variable. If this environment variable does not exist, the files are created in the current directory (Windows) or a system defined temporary directory, typically /var/tmp or /tmp (UNIX).

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


Using Preprocessors

Choose either an SQL or another additional preprocessor to compile your applications with. These include preprocessors installed with Enterprise Developer, or any third-party preprocessors available on your machine.
  • SQL Preprocessors
    Choose from the SQL Preprocessors supplied with Enterprise Developer to compile your applications.
  • Additional Preprocessors
    In the IDE, you can enable additional preprocessors to process your COBOL source code before passing it to the Compiler. You can choose from the preprocessors installed with Enterprise Developer or you can specify your own, or other, third-party preprocessors installed on your machine.
Parent topic: Compiling COBOL Applications


SQL Preprocessors

Choose from the SQL Preprocessors supplied with Enterprise Developer to compile your applications.
OpenESQL
Before compiling from within Enterprise Developer:
  1. Open your project properties and expand Micro Focus > Project Settings > COBOL > SQL Preprocessor.
    Note: You can also set compiler directive options under Micro Focus > Build Configurations > COBOL > SQL Preprocessor. If you do this, the setting applies only when the build configuration is active, and the compiler directive option is not set to something else in the Project Settings or on the program level.
  2. If unchecked, check Enable configuration specific settings and Use SQL Preprocessor.
  3. From the Preprocessor Type drop-down list, select OpenESQL.
  4. Type the name of your database into the Value field of the DB setting.
  5. To specify the type of database access you want, use the grid to set the value of the DBMAN directive to ODBC or JDBC.
  6. Click Apply.
  7. Use the grid to select additional directive options and set appropriate values. Click Apply after each setting.

Alternatively, you can enter the preprocessor specification and options as additional directives:

  1. Open your project properties and expand Micro Focus > Project Settings > COBOL.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. Click in the Additional directives field and type:
    SQL(DBMAN=dbaType [SQLdirOpt])

    Where dbaType is ODBC or JDBC, and SQLdirOpts is one or more additional directive options.

DB2 ECM
  1. Open your project properties and expand Micro Focus > Project Settings > COBOL > SQL Preprocessor.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL > SQL Preprocessor. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. Check Enable configuration specific settings and Use SQL Preprocessor.
  3. From the Preprocessor Type drop-down list, select HCO for DB2 LUW.
  4. Type the name of your database into the Value field of the DB setting.
    Note: If you leave the value for DB blank, the compiler uses the database specified by the value of the DB2DBDFT environment variable.
  5. Click Apply.

Alternatively, you can enter the preprocessor specification and options as additional directives:

  1. Open your project properties and expand Micro Focus > Project Settings > COBOL.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. Click in the Additional directives field and type:
    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.
XDB (Windows)
  1. Open your project properties and expand Micro Focus > Project Settings > COBOL > SQL Preprocessor.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL > SQL Preprocessor. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. Check EXEC SQL.
  3. From the Preprocessor Type drop-down list, select XDB.
  4. Configure the database in the Client Options console (Click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2 > Configuration > Client Options).
COBSQL
Before compiling from within Enterprise Developer:
Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL > SQL Preprocessor. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the project settings or at the program level.

For Oracle Pro*COBOL, you can set the COBSQL preprocessor and compiler directives from the project's properties:

  1. Expand Micro Focus > Project Settings > COBOL > SQL Preprocessor.
  2. Check Use SQL Preprocessor.
  3. From the Preprocessor Type list, select Oracle Pro*COBOL(COBSQL).
  4. Under Setting choose a directive and specify its value under Value.
  5. Repeat the previous step to add additional directives.
  6. Click Apply, then click OK.
Note: Ensure that no conflicting preprocessor directives are set in Additional Directives.
Note: Adding the Oracle Pro*COBOL (COBSQL) preprocessor to the SQL Preprocessor file, build configuration or project property page automatically adds a read-only entry to the top of the preprocessors list in the Additional Preprocessors 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.
Parent topic: Using Preprocessors


Additional Preprocessors

In the IDE, you can enable additional preprocessors to process your COBOL source code before passing it to the Compiler. You can choose from the preprocessors installed with Enterprise Developer or you can specify your own, or other, third-party preprocessors installed on your machine.
Restriction: You can only use additional preprocessors with native COBOL applications.

A preprocessor edits the source code before passing it to the Compiler. You can use multiple preprocessors to make consecutive edits to your COBOL source code. For multiple preprocessors to function correctly during a background syntax check in the IDE, each preprocessor must conform to the stacking protocol detailed in the section Multiple Preprocessors.

As you specify preprocessors to be used the IDE creates a list that gives the order in which the preprocessesors are invoked. When you have multiple preprocessors defined, compiling a program causes the Compiler to call the first preprocessor in the list which then edits a line of source code. The line is then passed to the next preprocessor in the list. When all preprocessors in the stack have parsed the line, it is passed to the Compiler to compile it. The Compiler calls the preprocessors for the next line of code until all source code has been parsed through the preprocessors and is compiled

You can specify that an additional preprocessor is to be used for an entire project, only for specific build congifurations, or for individual files.

Note: If the additional preprocessors are integrated with Enterprise Developer, they appear in the IDE and you can select them from the project and file properties. See Integrating Preprocessors into Enterprise Developer for instructions about how to integrate an additional preprocessor with Enterprise Developer.

You can use the Additional Preprocessors properties page to specify and configure the preprocessors to use with your COBOL files, build configuration or project or with files in your project. You can specify either a single or multiple preprocessor.

  • Specifying an additional preprocessor
  • Editing an additional preprocessor
  • Specifying the order of execution for multiple preprocessors
  • Removing an additional preprocessor
Parent topic: Using Preprocessors
Related concepts
Multiple Preprocessors
Related reference
Integrating a Preprocessor with Enterprise Developer
Related information
Mainframe Express Functionality That Works Differently in Enterprise Developer for Eclipse


Specifying an additional preprocessor

Specify a preprocessor to use with your project

To specify an additional preprocessor for use with your project:

  1. Click Project > Properties.
  2. Click Micro Focus > Project Settings > COBOL > Additional Preprocessors.
  3. Specify a preprocessor to use with your project:
    • To specify your own or third-party preprocessor to use with your project:
      1. Click New. This displays the Add Custom Preprocessor dialog box.
      2. Type the name of the preprocessor in the Name field.
      3. Specify the location of the preprocessor in the Location field. Alternatively, click Browse and navigate to the preprocessor location.
      4. Type the directives in the Directives field. Use space to separate multiple directives.
    • To specify an installed preprocessor to use with your project:
      1. Click Installed, this will display the Add Installed Preprocessor dialog box.
      2. In the Name list, select the installed preprocessor to use.
      3. Type any required directives in the Directives field.
      4. Click OK.

        If you name the preprocessor the same as an existing preprocessor, the IDE prompts you for confirmation to overwrite the existing preprocessor.

      Note: It is not possible to combine the "Micro Focus - EHTML Preprocessor" and "Micro Focus - XML Preprocessor" with other preprocessors. Selecting one of these preprocessors will prevent you from adding any other additional preprocessors. See Integrating Preprocessors into Enterprise Developer for instructions about how to integrate an additional preprocessor with the list in Enterprise Developer.
  4. Click OK to save your changes.

Each preprocessor you add is inserted at the top of the list on the Preprocessor page. The order of execution of preprocessors is from the top to the bottom of the list.

Specify a preprocessor to use with a build configuration

To enable an additional preprocessor for a build configuration:

  1. Click Project > Properties.
  2. Expand Micro Focus > Build Configurations > COBOL.
  3. Click Additional Preprocessors.
  4. Select the Build Configuration.
  5. Check Enable configuration specific settings.
  6. Specify a preprocessor to use with your selected build configuration:
    • To specify your own or third-party preprocessor to use with your build configuration:
      1. Click New, this will display the Add Custom Preprocessor dialog box.
      2. Type the name of the preprocessor in the Name field.
      3. Specify the location of the preprocessor in the Location field. Alternatively, click Browse and navigate to the preprocessor location.
      4. Type the directives in the Directives field. You can add multiple directives by creating a space separated list.
    • To specify an installed preprocessor to use with your build configuration:
      1. Click Installed, this will display the Add Installed Preprocessor dialog box.
      2. In the Name list, select the installed preprocessor to use.
      3. Type any required directives in the Directives field.
      4. Click OK.

        If you name the preprocessor the same as an existing preprocessor, the IDE will prompt you for confirmation to overwrite the existing preprocessor.

      Note: It is not possible to combine the "Micro Focus - EHTML Preprocessor" and "Micro Focus - XML Preprocessor" with other preprocessors. Selecting one of these preprocessors will prevent you from adding any other additional preprocessors. See Integrating Preprocessors into Enterprise Developer for instructions about how to integrate an additional preprocessor with the list in Enterprise Developer.
  7. Click OK to save your changes.

Each preprocessor you add is inserted at the top of the list on the Preprocessor page. The order of execution of preprocessors is from the top to the bottom of the list.

Specify a preprocessor to use with a file

To enable an additional preprocessor for an individual file in your project:

  1. In COBOL Explorer, right-click a COBOL program in your project, and click Properties.
  2. Click COBOL > Additional Preprocessors.
  3. Check Enable file specific settings.
  4. Specify a preprocessor to use with the selected file:
    • To specify your own or third-party preprocessor to use with your file:
      1. Click New, this will display the Add Custom Preprocessor dialog box.
      2. Type the name of the preprocessor in the Name field.
      3. Specify the location of the preprocessor in the Location field. Alternatively, click Browse and navigate to the preprocessor location.
      4. Type the directives in the Directives field. You can add multiple directives by creating a space separated list.
    • To specify an installed preprocessor to use with your file:
      1. Click Installed, this will display the Add Installed Preprocessor dialog box.
      2. In the Name list, select the installed preprocessor to use.
      3. Type any required directives in the Directives field.
      4. Click OK.

        If you name the preprocessor the same as an existing preprocessor, the IDE will prompt you for confirmation to overwrite the existing preprocessor.

      Note: It is not possible to combine the "Micro Focus - EHTML Preprocessor" and "Micro Focus - XML Preprocessor" with other preprocessors. Selecting one of these preprocessors will prevent you from adding any other additional preprocessors. See Integrating Preprocessors into Enterprise Developer for instructions about how to integrate an additional preprocessor with the list in Enterprise Developer.
  5. Click OK to save your changes.

Each preprocessor you add is inserted at the top of the list on the Preprocessor page. The order of execution of preprocessors is from the top to the bottom of the list.

Parent topic: Additional Preprocessors


Editing an additional preprocessor

Editing a preprocessor for a project

To configure a preprocessor for a project:

  1. Click Project > Properties.
  2. Expand Micro Focus > Project Settings > COBOL.
  3. Click Additional Preprocessors.
  4. Choose a preprocessor to edit in your project:
    • To edit your own or third-party preprocessor used in your project:
      1. Click on a custom preprocessor.
      2. Click Edit, this will open the Edit Custom Preprocessor dialog box.
      3. Type a new preprocessor name in the Name field, if required.
      4. Specify a new location for the preprocessor in the Location field. Alternatively, click Browse and navigate to the new preprocessor location.
      5. Type the new directives in the Directives field, if required.
      6. Click OK.
    • To edit an installed preprocessor used in your project:
      1. Click on an installed preprocessor.
      2. Click Edit, this will open the Edit Installed Preprocessor dialog box.
      3. Type the new directives in the Directives field.
      4. Click OK.
  5. Click OK to save your changes.

Editing a preprocessor for a build configuration

To configure a preprocessor for a build configuration:

  1. Click Project > Properties.
  2. Expand Micro Focus > Build Configurations > COBOL.
  3. Click Additional Preprocessors.
  4. Select the Build Configuration.
  5. Choose a preprocessor to edit for your build configuration:
    • To edit your own or third-party preprocessor used in your build configuration:
      1. Click on a custom preprocessor.
      2. Click Edit, this will open the Edit Custom Preprocessor dialog box.
      3. Type a new preprocessor name in the Name field, if required.
      4. Specify a new location for the preprocessor in the Location field. Alternatively, click Browse and navigate to the new preprocessor location.
      5. Type the new directives in the Directives field, if required.
      6. Click OK.
    • To edit an installed preprocessor used in your build configuration:
      1. Click on an installed preprocessor.
      2. Click Edit, this will open the Edit Installed Preprocessor dialog box.
      3. Type the new directives in the Directives field.
      4. Click OK.
  6. Click OK to save your changes.

Editing a preprocessor for a file

To configure a preprocessor for a file:

  1. In COBOL Explorer, right-click a COBOL program in your project, and click Properties.
  2. Click COBOL > Additional Preprocessors.
  3. Choose a preprocessor to edit for your file:
    • To edit your own or third-party preprocessor used for a file:
      1. Click on a custom preprocessor.
      2. Click Edit, this will open the Edit Custom Preprocessor dialog box.
      3. Type a new preprocessor name in the Name field, if required.
      4. Specify a new location for the preprocessor in the Location field. Alternatively, click Browse and navigate to the new preprocessor location.
      5. Type the new directives in the Directives field, if required.
      6. Click OK.
    • To edit an installed preprocessor used for a file:
      1. Click on an installed preprocessor.
      2. Click Edit, this will open the Edit Installed Preprocessor dialog box.
      3. Type the new directives in the Directives field.
      4. Click OK.
  4. Click OK to save your changes.
Parent topic: Additional Preprocessors


Specifying the order of execution for multiple preprocessors

Specifying the order of execution of multiple preprocessors for a project

If you enable multiple preprocessors, they are executed in the order specified in the Additional Preprocessors properties. The preprocessor at the top of the list is executed first, moving sequentially down the list.

To change the position of a preprocessor in the list:

  1. Click Project > Properties.
  2. Expand Micro Focus > Project Settings > COBOL.
  3. Click Additional Preprocessors.
  4. Select the preprocessor whose position you want to change.
  5. Click Up to move the preprocessor up the list and execution order.
  6. Click Down to move the preprocessor down the list and execution order.
  7. Check the Preprocessors directives field to verify the order of execution of the selected preprocessors.
  8. Click OK

Specifying the order of execution of multiple preprocessors for a build configuration

If you enable multiple preprocessors, they are executed in the order specified in the Additional Preprocessors properties. The preprocessor at the top of the list is executed first, moving sequentially down the list.

To change the position of a preprocessor in the list:

  1. Click Project > Properties.
  2. Expand Micro Focus > Build Configurations > COBOL.
  3. Click Additional Preprocessors.
  4. Select the Build Configuration.
  5. Select the preprocessor whose position you want to change.
  6. Click Up to move the preprocessor up the list and execution order.
  7. Click Down to move the preprocessor down the list and execution order.
  8. Check the Preprocessors directives field to verify the order of execution of the selected preprocessors.
  9. Click OK

Specifying the order of execution of multiple preprocessors for a file

If you enable multiple preprocessors, they are executed in the order specified in the Additional Preprocessors properties. The preprocessor at the top of the list is executed first, moving sequentially down the list.

To change the position of a preprocessor in the list:

  1. In COBOL Explorer, right-click a COBOL program in your project, and click Properties.
  2. Click COBOL > Additional Preprocessors.
  3. Select the preprocessor whose position you want to change.
  4. Click Up to move the preprocessor up the list and execution order.
  5. Click Down to move the preprocessor down the list and execution order.
  6. Check the Preprocessors directives field to verify the order of execution of the selected preprocessors.
  7. Click OK
Parent topic: Additional Preprocessors


Removing an additional preprocessor

Removing a preprocessor from your project

To remove a preprocessor from your project's properties:

  1. Click Project > Properties.
  2. Expand Micro Focus > Project Settings > COBOL.
  3. Click Additional Preprocessors.
  4. In the list of preprocessors, click the preprocessor that you want to remove.
  5. Click Remove.
  6. Click OK.

Removing a preprocessor from your build configuration

To remove a preprocessor from your build configuration:

  1. Click Project > Properties.
  2. Expand Micro Focus > Build Configurations > COBOL.
  3. Click Additional Preprocessors.
  4. Select the Build Configuration.
  5. In the list of preprocessors, click the preprocessor that you want to remove.
  6. Click Remove.
  7. Click OK.

Removing a preprocessor from your file

To remove a preprocessor from your file:

  1. In COBOL Explorer, right-click a COBOL program in your project, and click Properties.
  2. Click COBOL > Additional Preprocessors.
  3. In the list of preprocessors, click the preprocessor that you want to remove.
  4. Click Remove.
  5. Click OK.
Parent topic: Additional Preprocessors


Linking Native COBOL Code (Windows)

There are several ways to link to the run-time system. The way you link depends on the type of application.

  • Overview of Linking Native COBOL Applications and Run-time Systems
  • Shared Run-time System for Running Native COBOL Applications
  • Dynamically Binding Run-time Systems to Your Native COBOL Applications
  • Order of Program Loading and Run-time System Usage for Native COBOL
  • Loading a Dynamic Link Library Built as Native COBOL Code
  • Application Performance with Dynamic Binding for Native COBOL
  • Specifying non-default link options in the IDE
Parent topic: Building COBOL applications
Related concepts
Linking PL/I programs


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.

Parent topic: Linking Native COBOL Code (Windows)
Related information
Run-time System Configuration
cbllink


Shared Run-time System for Running Native COBOL Applications

Note: The following information applies to native code only.

The shared run-time system comprises multiple .dll files, each of which can be separately loaded when required, whenever a program linked with it runs. All separately linked subprograms call the same copy of the run-time system, avoiding duplicate code. In addition, programs running in separate sessions use the same run-time system, reducing memory usage.

When a program linked to the shared run-time system runs, external calls are made to the run-time system and the required part of the run-time system is loaded.

To run a program linked with the shared run-time system, you might need to provide some other files, such as a trigger program or some run-time support modules.

When an .int file or .gnt file runs, it uses the shared run-time system.

Parent topic: Linking Native COBOL Code (Windows)


Dynamically Binding Run-time Systems to Your Native COBOL Applications

Note: The following information applies to native code only.

If you ship an application to a site where other applications are already installed, your application might conflict with the existing ones if your application uses a different version of the run-time system from the existing ones. For example, your application uses version 4 of the run-time system and the existing applications use version 3. Normally, you would need to ship the version 4 run-time system. You would also need to set the paths on your user's system so that each application used its own version of the run-time system: the version 4 application used the version 4 run-time system and the version 3 application used the version 3 run-time system.

To solve these problems, you can dynamically bind a run-time system to your programs. Dynamic run-time system binding enables you to:

  • Create system executables that can use any installed run-time system, whatever its version
  • Create system executables that can recognize whether they are compatible with the versions of available run-time systems
  • Create dynamic link libraries that can dynamically bind to any run-time system that exists within a process

Dynamic run-time system binding is enabled using a glue library, called cblrtsg.lib. When you choose to dynamically bind an application, your system executable is linked to the glue library rather than directly to a run-time system. If your executable is a .dll file, it can then run in a process that has loaded the run-time system. If your executable is an .exe file, it dynamically binds to either the required version of the run-time system, or the system default run-time system. As long as the system to which you are shipping your system executable file already has a run-time system installed, you need to ship only the executable file. How your system executable interacts with the installed run-time system depends on how you linked your program to the glue library.

You can create a dynamically bound executable by using the Cbllink utility.

Parent topic: Linking Native COBOL Code (Windows)
Related information
cbllink


Order of Program Loading and Run-time System Usage for Native COBOL

Note: The following information applies to native code only.

In dynamically bound applications , the order in which programs are loaded affects which run-time systems are searched for and the use of the run-time system. For example:

  • The .exe file and the first .dll file determine which run-time system is loaded
  • The level of run-time system specified when you link ensures that the run-time system is compatible and provides the features required by the executable
  • Further .dll files bind to the existing run-time system within the process

.exe Files and First .dll Files

A "first" COBOL .dll file is the first loaded component of an application that needs a COBOL run-time system for execution. In the following description, the term ".exe file" also implies the term "first .dll file".

When the application runs, the .exe file locates and loads a compatible run-time system, depending on how the application was linked. If the application was:

  • Linked normally (that is, without using dynamic binding), the .exe file looks for a run-time system on the path specified by the PATH environment variable. If more than one run-time system is installed, this can cause a conflict.
  • Linked using dynamic binding, the .exe file dynamically binds to a run-time system by consulting the Windows registry for installed and compatible run-time systems. If a run-time system cannot be found, then the current setting of the PATH environment variable is used to load a default run-time system.

Compatible Run-time Systems

When you create a dynamically bound executable file you can specify what level of run-time system the executable file is allowed to work with. This enables you to specify that the executable can work with any newer version of the run-time system than the one you linked it with, or whether the executable is restricted to the current release of the run-time system only.

The level and threading mode of a run-time system is checked as follows:

  • The level of the run-time system is identified as a version number in the registry. For example, for version 6.0 of the COBOL development system, the run-time system level is 6.0.
  • The path used to load the run-time system is determined from the registry value:
    \HKEY_LOCAL_MACHINE\SOFTWARE
\Micro Focus\Enterprise Developer\x.y\COBOL\Environment\PATH

    where:

    x.y
    is the installed version of the COBOL system.

    If the executable was restricted to the current release level when it was created, x.y must be greater than or equal to the development system version with which the executable was created.

  • If none of the above techniques works, the default setting of PATH is used to load the run-time system.

In any case, when the run-time system has been loaded a version and type check is performed and any incompatibilities reported.

Further .dll Files

When a second or further .dll file is loaded into a same process, it must bind to the existing run-time system within the process. If you create an application that does not use dynamic binding, then you must make sure that all programs in an application are linked to the same run-time system, otherwise conflicts could occur that would result in the application failing.

If you use dynamic binding when you create the second or further .dll files in your application then you can specify that they will either bind to any loaded and compatible run-time system, or will fail cleanly with informative diagnostic messages.

Parent topic: Linking Native COBOL Code (Windows)


Loading a Dynamic Link Library Built as Native COBOL Code

Note: The following information applies to native code only.

.dll files must be loaded into memory before they can be used. If you use dynamic linking, your program should load each .dll file as necessary before attempting to call entry points in it:

  • If the .dll file contains a single public entry point and you use the name of the .dll file in the CALL statement, the file is loaded automatically when called.

    For example, if a file mydll.dll contains a single public entry point, the file is loaded and the call executed by a CALL "mydll" statement.

  • If the .dll file contains several public entry points, use the SET procedure-pointer-name TO ENTRY program-name statement before you call the entry point. For example:
    set mypointer to entry "mybigdll"
call "My-third-entry-point"

You need to load a dynamic link library the first time you use it only, unless the .dll file is no longer in memory.

Canceling a Program and Unloading a .dll

A .dll file is automatically removed from memory when a COBOL program within it is canceled and this results in all COBOL programs in the .dll file being either in an uncalled or a canceled state.

For example, consider a .dll file called sub.dll which contains three COBOL programs: sub.cbl, sub1.cbl and sub2.cbl.

  1. Program sub.cbl is called from the main program.
  2. Program sub2.cbl is called.
  3. Program sub.cbl is then canceled.

    The .dll file is not removed from memory because sub2.cbl has not yet been canceled.

  4. Program sub2.cbl is canceled.

    The .dll file is removed, because all programs within it are now either canceled (sub.cbl and sub2.cbl) or not called (sub1.cbl).

The way you load OO .dll files depends on whether they contain a single class or several classes.

Parent topic: Linking Native COBOL Code (Windows)


Application Performance with Dynamic Binding for Native COBOL

Note: The following information applies to native code only.

The call speed of a dynamically bound application is roughly the same as an application directly linked to the shared run-time systems.

The first call to the run-time system by a dynamically bound application invokes the dynamic binder. The dynamic binder queries .dll files within the process, accesses the machine registry, and finally, if necessary loads the appropriate run-time system, determining the entry point address. Following this, first-time calls to other entry points also go through the dynamic binder, but they need to determine the entry point address only. Successive calls to previously called entry-points go directly to the bound entry-point.

Applications that use dynamic run-time system binding might be slightly larger than applications linked in the normal way. This is because a dynamically bound application requires the binding code and strings for each run-time system entry point referenced in the application.

Parent topic: Linking Native COBOL Code (Windows)


Specifying non-default link options in the IDE

Note: This applies only to native code.

For situations where you need to specify link options that are not available on the build configuration Link page in your project's properties, you can use the Link Command Line Override field to specify a non-default link command.

Important: The command you specify in this field overrides any other settings that are selected on the Link page.
  1. Navigate to the project’s properties and click Micro Focus > Build Configurations > Link.
  2. In the Link Command Line Override field, enter the non-default link options.

You must specify the entire link command, typically using the cbllink (Windows) or cob (UNIX/Linux) command.

The following ant variables are available for use:

${objectfile} ${destdir}  ${destfile}  ${entrypoint}  ${dllext} ${exeext} ${additionalOptions}

The following is an example override command:

cob -x -e ${destfile} -o ${destfile} ${objectfile}

If the link command is to create an output from a number of object files, you need to specify each file explicitly, each being prefixed with the base directory and explicit output folder:

${basedir}/output_folder/
Parent topic: Linking Native COBOL Code (Windows)
Parent topic: Linking (UNIX)


Linking (UNIX)

  • Introduction to Linking
  • Linking and Linked File Types
  • Linking and Binding
  • Dynamic Loading
  • Specifying non-default link options in the IDE
Parent topic: Building COBOL 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 (UNIX)


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. This applies to UNIX environments (remote development) only.
Shared library files
These are system linkable files that can be linked into executable files. They cannot be directly executed themselves. This applies to UNIX environments (remote development) only.
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. This applies to UNIX environments (remote development) only.

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


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 (UNIX)
Related concepts
Creating Executables that Use the Dynamic Loader


To clean a project

Cleaning a project discards all build problems and build states.
By default Eclipse automatically builds a project every time you save resources, but doesn't clean it.
Tip: To turn off automatic building, select Window > Preferences > General > Workspace and clear the Build automatically check box.
  1. Make sure your project is highlighted in the COBOL Explorer view, and click Project > Clean .

    The Clean wizard is displayed.

  2. If you have not configured Eclipse to build automatically you will have the additional options:
    • Clean all projects
    • Start a build immediately
    • Build the entire workspace
  3. Click OK.
Parent topic: Building COBOL applications


Tips: Building COBOL projects

Here are some tips on handling projects and building COBOL applications in the Eclipse IDE.

Add files to a project | File > Import.
Build automatically | Project > Build Automatically. With this set, whenever a resource changes, an incremental build starts and all resources modified since the last build are rebuilt.
Build settings and build types | Project > Properties > Micro Focus > Project Settings and Project > Properties > Micro Focus > Build Configurations > COBOL. The currently active build configuration overrides the project language settings. You can create multiple build configurations for different build scenarios and swap between them.
COBOL settings | Project > Properties > Micro Focus > Project Settings. Use this to set the dialect, character set, source format, and directives for the whole project. You can override these for an individual file by right-clicking the file in the COBOL Explorer or Application Explorer view and clicking Properties > COBOL Settings.
Content type | Window > Preferences > General > Content Types. Use this to associate a file extension with the content type of a COBOL file, to colorize it in the editor, background parse it and compile it, if appropriate to the type of file.
Copybook paths | Project > Properties > Micro Focus > Build Configuration > Build Paths > Dependency Paths. The search order here takes precedence over the COBCPY environment variable setting. To add copybook paths to this list, specify the paths as linked resources. Tip: In order to increase the speed of indexing and background parsing, we recommend you deselect paths that don't contain copybooks.
Linked resources | Linked resources enable you to link to sources rather than including them in the project. They show in the project in the COBOL Explorer and Application Explorer view as file icons decorated with a square with an arrow link.
Run-time Environment Settings | Project > Properties > Micro Focus > Run-time Configuration. From here you can set a range of environment settings, including run-time switches and environment variables.
Stop a build in progress | Click the red square, Terminate in the Progress view. To turn on this view, click Window > Show View > Other > General > Progress.
Pre and Post build events | Configure these within the Build Configuration wizard. You can use then, for example, to set build environments and prerequisite, cleanup tasks and deploying build artifacts. You can specify shell scripts and single commands within the dialog box. Single commands should be placed on separate lines.
Delete build artifacts when project settings change | By default, Eclipse is configured to always delete the build artifacts when the project settings change. You can change this behaviour from Window > Preferences > Micro Focus > Builder and change the settings for the Delete build artifacts when project settings change preference. The IDE then displays a notification when changes are made that would normally trigger artifacts to be deleted.
Improve performance and avoid running out of memory | If a large amount of data is output to the build console, you can get memory-related errors or slow builds. You can limit the size of the console buffer to help avoid these problems. To do this, right-click in the build console and select Preferences > Limit console output and enter a number of characters. You can also click the Clear Console button in the build console to free up memory during the build.
Parent topic: Building COBOL applications


How To in the IDE

  • To set Compiler directives on a COBOL file
Parent topic: Building COBOL applications


To set Compiler directives on a COBOL file

Note: The following applies to native COBOL only.

To specify Compiler directives on an individual COBOL file which is part of a project:

  1. In COBOL Explorer, right-click the file on which you want to set the directives.
  2. Click Properties.
  3. Go to the COBOL page.
  4. Check Enable file specific settings.
  5. In Additional Directives, type the directives to set. Separate each directive with a space.
  6. Click OK.

The next time you compile the file or the entire project, the directives are applied.

Important: The directives set on individual files override those that are specified for the entire project.
Parent topic: How To in the IDE


Code Coverage (Native COBOL)

Code coverage for native COBOL in Enterprise Developer integrates the Micro Focus Test Coverage facility.
Note: This facility is supported in native COBOL only.

These are the steps to enable code coverage for your applications and then run them to produce code coverage reports:

  1. Enable code coverage in the properties of a project, a build configuration's or a file.
    Note: If different from the project settings, the build configuration settings take precedence over the project settings when you build your application. If you enabled code coverage at project level but do not receive any results when you run the application, it might be because the application was executed in a build configuration which does not have code coverage enabled. To work around this, always ensure code coverage is enabled for the build configuration you are running your application in.
  2. Compile your project to apply the changes.
  3. Create a launch configuration that has code coverage enabled and execute your application in it.

While an application is running with code coverage, code execution is logged for each program and sub-program that has been compiled with code coverage enabled. The results are stored in a binary results file which has the filename extension .tcz. In the IDE, you can specify your preferences for what level of details test coverage should write into the results file depends on how you configure test coverage.

For example, you can tag statements in your source code and use code 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.

For convenience, Enterprise Developer visualizes the code coverage information from the results file by showing statistics about covered (executed) or missed (unexecuted) blocks and programs in a Code Coverage view and by highlighting the covered and missed blocks in the editor in different colors. You can produce code coverage reports in HTML format.

Covered and missed blocks

A block is a section of code that, when executed, is executed consecutively and linearly. This means you can assume that if one part of the block executes, then the rest of the block has been executed as well.

Code that is not executed linearly (such as IF THEN ELSE statements, where the individual clauses in the statement are not executed in a single pass) includes more than one block of code.

Blocks of code that are executed are referred to as covered, while blocks of code that are not executed are referred to as missed.

Restrictions

Code coverage in the IDE utilizes the Test Coverage command line utility. The following restrictions of the Test Coverage utility also apply to code 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 code coverage in a production system because of the increased requirements on system resources when running in code coverage mode. However, you can compile with code 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.

  • Enabling Code Coverage
  • Running an Application with Code Coverage
  • Viewing the Code Coverage Information
  • Code Coverage HTML Reports
Parent topic: Developing Applications in the IDE
Related concepts
Using Test Coverage from the Command Line
Related tasks
Enabling Code Coverage


Enabling Code Coverage

Note: This facility is supported in native COBOL only.

Before you run an application in code coverage mode and produce code coverage statistics, you must enable code coverage in the properties of your project, a project's build configuration or in the properties of the project's files. You then need to build your application.

To enable code coverage for your project:

  1. Open your project's properties, expand Micro Focus > Project Settings and click the COBOL tab.
    Note: If different from the project settings, the build configuration settings take precedence over the project settings when you build your application. If you enabled code coverage at project level but do not receive any results when you run the application, it might be because the application was executed in a build configuration which does not have code coverage enabled. To work around this, always ensure code coverage is enabled for the build configuration you are running your application in.
  2. Check Enable code coverage.
  3. Click Apply and then click OK.

To enable code coverage for a build configuration of your project:

  1. Open your project's properties, expand Micro Focus > Build Configurations and click the COBOL tab.
  2. Expand Override project COBOL settings and check Enable configuration specific settings.
  3. Check Enable code coverage.
  4. Click Apply and then click OK.

To enable code coverage for individual files in your project:

  1. Open a file's properties and click the COBOL tab.
  2. Check Enable file specific settings and check Enable code coverage.
  3. Click Apply and then click OK.
Note: If Build Automatically is not enabled in the IDE, you need to build your project manually.

If your application executes in an enterprise server, you also need to configure the server to run in code coverage mode:

  1. In the IDE, open Server Explorer.
  2. Right-click the server that is associated with your application and click Configure Analysis > Code Coverage.

To enable code coverage to produce reports in HTML format in addition to producing statistics, specify your preferences on the Code Coverage page in Window > Preferences > Micro Focus > COBOL. See Configuring the Code Coverage HTML Reports.

Parent topic: Code Coverage (Native COBOL)
Related concepts
Code Coverage (Native COBOL)
Using Test Coverage from the Command Line


Running an Application with Code Coverage

Note: This facility is supported in native COBOL only.

Having enabled code coverage for a project (see Enabling Code Coverage), you need to execute the application in code coverage mode in order to generate the coverage data. There is a different approach to this depending on whether or now the application requires an enterprise server to run.

If your application does not require an enterprise server, to run it in code coverage mode:

  1. In COBOL Explorer, right-click your project and click Run As > Run Configurations.
  2. Create a new COBOL Application configuration, or select an existing one.
  3. In the right side of the dialog box, click the Dynamic Analysis tab.
  4. Check Enable code coverage.
  5. If you want to combine the results of multiple runs of the application with test coverage, check Accumulate data from successive runs,
  6. If necessary, specify names for the directories in your project that will contain the log files and the results files that are different than the default ones - Coverage and CoverageResults.
  7. Click Apply and then click Run to execute your application.
  8. Stop your application.

    After the execution stops, the IDE automatically opens the Code Coverage view that shows the statistics about what percentage of the code has executed. The code in the editor is colorized to indicate covered and missed blocks.

    Running the application with code coverage also produces a binary results file, filename.tcz in the Results directory specified on the launch configuration.

    If Generate reports upon run completion is checked in the IDE preferences for code coverage, Enterprise Developer also produces an HTML report. If no preferences are specified for the HTML report, you also receive a Code Coverage Report Generation Options dialog box prompting you to specify how this report should be configured.

If your application requires an enterprise server, to run it in code coverage mode:

  1. In the IDE, ensure code coverage is enabled in your project's properties.
  2. Ensure that the enterprise server is configured to run in Code Coverage mode.

    See Enabling Code Coverage.

  3. Start the server from Server Explorer.

    You might be promoted to specify directories for the generated coverage files. Click OK to confirm your preferences.

  4. Execute your application in the usual manner.
  5. Stop the server in Server Explorer.

    You must stop the server for the IDE to produce the code coverage information. After the execution stops, the IDE automatically opens the Code Coverage view that shows the statistics about what percentage of the code has executed. The code in the editor is colorized to indicate covered and missed blocks.

    Running the application with code coverage also produces a binary results file, filename.tcz in the Results directory specified on the launch configuration.

    If Generate reports upon run completion is checked in the IDE preferences for code coverage, Enterprise Developer also produces an HTML report. You might receive a Code Coverage Report Generation Options dialog box for you to specify how this HTML report should be configured.

See Viewing the Code Coverage information.

Parent topic: Code Coverage (Native COBOL)
Related tasks
Code Coverage HTML Reports
Configuring the Code Coverage HTML Reports


Viewing the Code Coverage Information

Note: This facility is supported in native COBOL only.

Running an application with code coverage produces a .tcz report file. Enterprise Developer uses the information in this file to provide statistics in the Code Coverage view about what percentage of the code has been executed as well as to colorize the code in the editor to indicate covered (executed) and missed (not executed) blocks as well as covered and unexecuted programs.

From the Code Coverage view, you can navigate to the covered and missed blocks of code in the editor, import code coverage data from existing .tcz files or merge the report files produced from different runs of the application, and relaunch the application in code coverage mode.

Code coverage statistics

After executing an application with code coverage, the IDE automatically opens the Code Coverage view to display the code coverage information. (If the view is not visible, to display it click Window > Show View (or Show View > Other), expand Micro Focus, click Code Coverage, then click OK).

The view visualizes the code coverage information from the filename.tcz results file produced during the latest run with code coverage. The code coverage information can be displayed in two different views:

  • Coverage per Programs ( [image])
  • Coverage per Files ( [image])

By default, the coverage per programs view is displayed. It displays the paragraphs and the sections within the program and what percentage of the code has been covered in the context of blocks:

Coverage per Programs

To change to the file view, click [image] (Coverage per Files). This view displays a list of files (both programs and copybooks) with their percentage of code which has been covered in the context of statements:

Coverage per Files

Covered and missed blocks

To view the covered and missed blocks, either scroll down the code of a COBOL program or double-click the lines of the program's structure in the Code Coverage view:

Covered and missed blocks
Note: The highlighted code will vary depending on the context of the COBOL program or copybook being displayed. In particular the context of a copybook opened for different programs.

By default, covered code is green, covered code in a global context is blue, and code not covered is red. You can specify your color preferences for the colorization of covered and missed blocks as follows:

  1. In the IDE, click Window > Preferences > General > Editors > Text Editors > Annotations.
  2. Specify your preferences for the Covered Block, Covered Block in Global Context, and Missed Block items in the Annotation types list.

Editing the code after producing coverage results

The information displayed in the Code Coverage view and the colorization of the editor reflect the state of the application at the time it was executed to produce that specific coverage results file. If you then make a change in the code and compile it, this might move the code in the editor. As a result, the colorization in the editor might not accurately match the information displayed in the Code Coverage view. The data displayed in the Code Coverage View will still reflect the historical state of the program when the data was generated.

Other situations where the colorization in the editor might not accurately represent the information in the code coverage view include:

  • The results from running with code coverage are accumulated in a single results file (Accumulate data successive runs is enabled on the Dynamic Analysis tab in the application's launch configuration).
  • When loading a merged results file that includes the data from different runs with code coverage.
  • When loading a results file from running the application with code coverage before you changed the code.

Importing existing code coverage results

To import the code coverage information from an existing .tcz results file:

  1. In the Code Coverage view, click Import Session (Import Session).
  2. Use the Connection list to specify whether the file is on your local disk or on a remote machine.
  3. Navigate to and select an existing code coverage report .tcz file, then click OK.

    This imports the code coverage statistics from the .tcz file into the Code Coverage view and adds colorization to your source files indicating the missed and the covered blocks.

Note: If, after producing the code coverage data for an application, you then change a program and compile it, this does not automatically update the code coverage information displayed in the IDE. The code coverage file that was generated before the change still provides the older data and colorization of lines might not be able to do anything that's correct - it won't be able to understand the change and adjust for it. Note that, though the colorization in the editor might be incorrect, the data shown in the code coverage view is still correct.

Situations in which this behavior might occur are:

  1. You have checked the Accumulate data successive runs checkbox on the Dynamic Analysis tab in the launch configuration which you use for running the application.
  2. If you have merged multiple results files available in the code coverage history and the program has changed the different runs with code coverage that produced code coverage data.
  3. If you have selected to load and display the results from running the application with code coverage before you changed your program.

Also, when importing code coverage results for remote projects that no longer belong to your workspace, unexecuted programs are no longer displayed in the results.

Rerunning the application with code coverage

After making changes to your application, to rerun the application with code coverage results:

  1. In the Code Coverage view, click Relaunch (Relaunch).

    This starts the application.

  2. Run and then exit the application to produce new code coverage results.

Deleting code coverage results

To delete the coverage results currently displayed in the Code Coverage view:

  1. In the Code Coverage view, click [image] (Remove Current Coverage Results).

To delete all code coverage results:

  1. In the Code Coverage view, click [image] (Remove All Coverage Results).

Merging the code coverage results from different runs

You can merge the results file from different executions with code coverage. This provides combined statistics of running the application in different scenarios. To merge the results:

  1. In the Code Coverage view, click Merge History Items (Merge History Items).
  2. In the Code Coverage Merge History Items dialog box, check the results files you want to merge, specify a name for the new results file, then click OK.

    This creates a new results file that includes the combined statistics and opens it in the Code Coverage view.

Viewing previous code coverage results

Enterprise Developer preserves the history of the previous results of running the application with code coverage.

Click Manage History (Manage History) to view and load the statistics from previous runs with code coverage, to remove previous results, or to configure how many items are preserved in the history.

Showing unexecuted programs

The Code Coverage view displays information about any programs that were not executed. Click Manage History (Show Unexecuted Program Information) to toggle the display of unexecuted programs.

Showing files with no statements

When in the coverage per files view, you can filter out files from the display list that do not contain statements that are covered. To filter files, click [image] (Show Files with no Statements) to toggle the display of files containing no statements. By default, filtering is not applied.

Link code coverage with editor

By default, the code coverage is linked with the editor. Double-click the element in the Code Coverage tab to open the file in the appropriate editor. Click [image] (Link with Editor) to toggle the link between the Code Coverage tab and the editor.

Filtering views by search strings

To filter the rows displayed in either view, type a string in the search filter field in the Code Coverage tab. You can use the "?" wildcard character to match a single character and the "*" to match any number of characters. By default, no filtering is applied.

Parent topic: Code Coverage (Native COBOL)


Code Coverage HTML Reports

Note: This facility is supported in native COBOL only.

If running with code coverage does not produce an index report file in HTML format, TCIndex.htm automatically, you can generate that file manually from the filename.tcz results file as follows:

  1. Right-click the filename.tcz in your project and click Generate Coverage Report.
  2. If prompted, specify any options for generating the report and click OK.

    Enterprise Developer creates the TCIndex.htm report file and opens it in the editor.

The picture below shows an example TCIndex.htm index report.

Figure 1. Test Coverage Report
Test Coverage Report

Click on of the links at the end of the TCIndex.htm file to view the individual reports.

The Contents section lists all of the programs in this report. If, in the IDE preferences you have specified to produce a single HTML report file or have had specified the COMBINE option when using Test Coverage from the command line, 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 aircode.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 aircode.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.

In this example, 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.

  • Configuring the Code Coverage HTML Reports
Parent topic: Code Coverage (Native COBOL)
Related tasks
Running an Application with Code Coverage
Configuring the Code Coverage HTML Reports


Configuring the Code Coverage HTML Reports

Note: This facility is supported in native COBOL only.

You can use the IDE preferences to configure whether the IDE produces code coverage reports in HTML format in addition to the code coverage statistics shown in the Code Coverage view. The preferences you specify apply to all projects that you execute with code coverage.

To specify your preferences for what the HTML code coverage report files should include :

  1. In the IDE, click Window > Preferences > Micro Focus > COBOL > Code Coverage.

You can specify the following preferences:

Generate reports upon run completion
Check this for the IDE to automatically show the code coverage report at the end of executing your application with code coverage enabled. If this is not checked, you can locate the file manually in a subfolder of your project which is defined as the Results directory specified on the Dynamic Analysis tab of the launch configuration in which you executed the application.
Always use the default report generation options
Check this if you want to always use the report generation options specified in these IDE preferences. If this is not enabled, you are prompted to specify code coverage report generation options every time you execute an application that has code coverage enabled.

You can choose any of the following report generation options:

Produce a single HTML file, instead of one per program
Check this for code coverage to produce a single reports file, instead of individual ones on a per program basis.
Display the basic block number of each statement in the rightmost column
Check this for the report to display 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.
Display a summary of called subroutines
Check this to include a summary of about CALLed subroutines in the report. Called subprograms are listed alphabetically. The CALL overhead in COBOL can be considerable, and this lets users identify the most commonly called routines.
Display the total execution count for each data item in the program
Check this for the report to include 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.
Display a summary of COBOL verbs used
Check this to include a summary of the COBOL verbs used in the report. 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
Include only lines containing specific text in column 1-6:
Specify the tags in your source code for which you want the report to generate specific information. You can use a space as a separator.
Parent topic: Code Coverage HTML Reports
Related tasks
Running an Application with Code Coverage
Code Coverage HTML Reports


Code Analysis

Code analysis helps you understand and optimize your COBOL applications. Enterprise Developer offers the following types of analysis:

Rules-based analysis

Enterprise Developer provides a variety of analysis queries (rules) that you can execute on individual COBOL programs or on an entire project to gain statistics to help improve the productivity.

Restriction: Rule-based analysis is only available for local and remote native COBOL projects on Windows platforms only. It is not supported for programs opened using the Application Workflow Modeller.

COBOL Source Information

COBOL Source Information (CSI) provides a quick and easy way of providing you with information about your program when you are working on it. You enter a query in the Quick Browse dialog box and CSI returns the results of the query in the Search view.

Restriction: COBOL Source Information (CSI) is only supported for native COBOL.
  • The Micro Focus Code Analysis View
  • Rule-Based Analysis
  • Using COBOL Source Information
    COBOL Source Information (CSI) provides a quick and easy way of providing you with information about your program when you are working on it.
Parent topic: Developing Applications in the IDE
Related concepts
Restrictions in Code Analysis
Features Added in Enterprise Developer 2.3


The Micro Focus Code Analysis View

When you run code analysis or CSI queries on your code, the IDE automatically opens the Micro Focus Code Analysis view to display the results. (If you cannot see the window, you can open it manually by clicking Window > Show View > Other and choosing the Micro Focus > COBOL Analysis category.)

The following list shows some of the different operations that you can perform from Micro Focus Code Analysis view:

Show previous analyses
Click Show Previous Analyses (Show Previous Analyses) to open the Previous Analyses dialog box. Alternatively, to execute a past query, click [image] and select one of the past queries.
Rerun a query
Analyze AgainClick Analyze Again ().
Show the details for all files listed in a report
Right-click in the view, and click Expand All or click Expand All in the toolbar.
Hide the details from the report
Right-click in the view, and click Collapse All or click Collapse All in the toolbar.
Navigate to the code
Double-click a line in the details for a file to navigate to the source code in the editor.
Arrange the results
Toggle between the two different ways of arranging the results - click Group By Program (Group By Program) to group the results by program or click Group By Rule (Group By Rule) to group them by rule.
Copy lines from the report
Right-click the line in the results, and click Copy.
Parent topic: Code Analysis
Related tasks
Performing Code Analysis on Demand
Performing Code Analysis when Building a Project in the IDE


Rule-Based Analysis

Note:
  • Rule-based analysis is only available for local and remote native COBOL projects on Windows platforms only. It is not supported for programs opened using the Application Workflow Modeller.

Enterprise Developer provides a variety of analysis queries (rules) that you can execute on individual COBOL programs or on an entire project to gain statistics to help improve the productivity.

Code analysis queries are referred to as rules and groups of rules are referred to as rule sets. In the IDE, you can run code analysis on individual COBOL programs or an entire project by executing a rule or an entire rule set on them. You can also enable code analysis to run each time a project is built.

Outside of the IDE, you can run code analysis when building projects using MSBuild at the using Ant targets. This enables you to include code analysis in your continuous integration (CI) processes.

Enterprise Developer comes with a set of rules and rule sets that include some of the most-commonly used analysis queries. These are generally organized in the following categories:

  • 64 bit readiness - includes code analysis queries to help check whether your code is going to perform as expected when compile for 64-bit platforms.
  • Coding Standards - includes code analysis queries to help identify places in the code that could possibly violate coding standards or places in the code that might be candidates for further analysis in reducing complexity or unnecessary code.
  • Performance - includes code analysis queries to help verify your code and determine where you could use more efficient constructs.
  • Within Entire Program - includes code analysis queries that check the code across an entire application such as queries for finding unexecuted statements, unreachable paragraphs, or data that is defined but is never used.
  • General Queries - includes code analysis queries not covered by the other categories

In addition to the rules supplied with the installation, you can import more rules and rule sets into Enterprise Developer. Micro Focus Enterprise Analyzer includes many more standard rules which you can reuse within the Enterprise Developer and this gives you the option to be able to customize these to create your own site-specific analyst functions which you can then publish out to your development teams. Contact Micro Focus for further information.

  • Performing Code Analysis when Building a Project in the IDE
    You can enable code analysis to run for a project each time the project is built in the IDE.
  • Performing Code Analysis on Demand
    You can run code analysis rules or rule sets on projects or files in the IDE to perform code analysis without building the sources.
  • Performing Code Analysis from the Command Line
    You can perform code analysis from the command line using Apache Ant.
  • Including Code Analysis in a Continuous Integration Process
  • Configuring Rules and Rule Sets
  • Importing Rule Sets into the IDE
  • Importing Existing Code Analysis Reports
Parent topic: Code Analysis
Related concepts
Restrictions in Code Analysis


Performing Code Analysis when Building a Project in the IDE

Restriction: This topic applies to Windows environments only.

Before you build a project, enable code analysis in the project's or a build configuration's properties as follows:

  1. In COBOL Explorer, navigate to your project's properties.
  2. Expand Micro Focus > Project Settings > COBOL (or Micro Focus > Project Settings > Build Configurations) and click Code Analysis.
  3. Check Run active rule sets after build and one or more rule sets.

    To view and modify the set of rules that will be executed with each rule set, click Code Analysis Preferences.

  4. Click OK.

Having enabled code analysis for a project, to run code analysis on it you simply need to build the project. By default, Eclipse builds the project automatically, but if that option is disabled, click Project > Build Project.

Building a project with code analysis enabled produces analysis reports. Any messages from the code analysis are displayed in the Console view alongside the build messages and the reports are automatically displayed in the Micro Focus Code Analysis view. See The Micro Focus Code Analysis Window for details about how to view and navigate the reports.

Parent topic: Rule-Based Analysis
Related reference
The Micro Focus Code Analysis View


Performing Code Analysis on Demand

You can run code analysis rules or rule sets on projects or files in the IDE to perform code analysis without building the sources.
Restriction: This topic applies to Windows environments only.

To run code analysis on demand:

  1. In COBOL Explorer, right-click a COBOL program, a selection of programs, or the entire project.

    Alternatively, right-click a COBOL program in the editor to perform analysis of that individual file.

  2. Click Code Analysis > rule or Code Analysis > rule set.

    This runs the selected rule or the rules enabled for a rule set on the source you have selected.

    To select rules that are not available on the context menu, click Code Analysis > Other. Select the rules that apply and click OK.

The Code Analysis reports are automatically displayed in the Micro Focus Code Analysis view. See The Micro Focus Code Analysis View for details about how to view and navigate the reports.

Parent topic: Rule-Based Analysis
Related reference
The Micro Focus Code Analysis View


Performing Code Analysis from the Command Line

You can perform code analysis from the command line using Apache Ant.

Properties for code analysis in the .cobolBuild script

Enterprise Developer uses the information stored in an Apache Ant script, .cobolBuild, to build COBOL projects.

.cobolBuild is part of your project. It is stored in the project's directory alongside the .cobolProj file and, in Eclipse, you can access it if you explore the project in the Navigator view.

The script is automatically regenerated when when you change the project's properties or rebuild the project file, .cobolProj.

Enabling code analysis for a project adds the following elements to the .cobolBuild script:

  • An Ant task, analysis.

    The task requires the FailOnError attribute that specifies whether the build fails or continues when code analysis returns any results.

    This also requires the ruleList type with rule nested elements which specify the rules to execute. If you have enabled rules that are imported into the IDE from a non-default location, the details about these rules are added to the ruleList.custom type.

    The mffilelist type specifies the COBOL files to run code analysis on.

  • The analysisData and analysisDataDir parameters in the cobol Ant task.
  • The analyze and build.and.analyze Ant targets.

    You must specify one of these targets when performing code analysis at the command line:

    • analyze - specifies that only code analysis is to be carried out on the source files.
    • build.and.analyze - specifies that both an analysis and a build are to be carried out on the source files.
  • Code analysis searches for rules in the product installation director. The folder to look for is added in the rulesDir tag.

    If you have imported additional rules into the IDE from a different folder, that folder is stored in the rulesDir.custom tag.

You can explore these parameters if you create a native COBOL project, enable code analysis for it from the project's properties, and open the .cobolBuild file in the editor.

Syntax of the Ant command for code analysis

You can perform code analysis of your source files at the command line using Apache Ant and the .cobolBuild script. The following is an overview of the process:

  1. You must have Apache Ant installed on your machine. Download Ant from http://ant.apache.org/.
  2. In Eclipse, enable and configure code analysis from your project's properties.
  3. Start an Enterprise Developer command prompt - click Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt.
  4. At the command prompt, navigate to the project's directory.
  5. Execute the following command to set the CLASSPATH environment variable:
    CLASSPATH=product-install-dir\bin\mfant.jar;%CLASSPATH%

    For example, if Enterprise Developer is installed in the default location:

    CLASSPATH=%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar;%CLASSPATH%
  6. Execute the following command to perform code analysis on the project using the .cobolBuild script and an Ant target for code analysis:
    Ant-install-dir\bin\ant -f .cobolBuild Ant-target -DanalysisFailOnError=value

    Where:

    • Ant-install-dir is the Ant installation directory. You can add Ant-dir\bin to the PATH environment variable to avoid having to specify the full path to the Ant executable.
    • Ant-target is one of the targets enabling code analysis adds to the project's .cobolBuild script:
      analyze
      Ant only analyzes the sources.
      build.and.analyze
      Ant builds the project, creates a build output, and then analyzes the source files.
    • FailOnError takes a value of either true or false:
      true
      Specifies that analyzing (or bulding and analyzing) the code should stop if running any of the analysis rules returns results.
      false
      Specifies that analyzing (or bulding and analyzing) the code should continue if running any of the analysis rules returns results.

    For example:

    c:\tools\antdir\bin\ant -f .cobolBuild build.and.analyze -DanalysisFailOnError=true

Customizing the .cobolBuild script

When you change the settings for code analysis in the project's properties, this changes the .cobolBuild script file. Alternatively, you can open the .cobolBuild script in the editor and make any changes to the code analysis settings manually (though, these changes are reverted if the IDE rebuilds the project).

You can use the .cobolBuild script file from outside of the workspace to perform code analysis, provided that the script and the source files are stored in the same location. This can be useful if you want to integrate your code analysis tasks into a continuous integration (CI) framework or when you store your applications outside of the workspace - for example, in a version control system such as Subversion.

In this case, you can manually modify the file to create more complex code analysis targets. You would not be able to edit the script if it is opened as part of a project as the IDE rebuilds the script each time it rebuilds the project.

See the section, Properties for Code Analysis in the .cobolBuild script, in this topic for the .cobolBuild script parameters that must be present. Ensure that the rulesDir and rulesDir.custom tags point to the locations of the files that contain the code analysis rules to execute.

Results from a code analysis job

The results of running code analysis from the command line are shown in the command prompt window alongside all the build messages.

The messages have the following format:

[Filename and full path] [LocationInFile (start line, column, end line, column)] : [ErrorMessage (error/warning + output code)] :  [RuleSetName] :  [Rule] :  [Code snippet the location refers to]

For example:

C:\Tutorials\Projects\MyProject\MyProgram.cbl (14,8,14,33): warning MFCA0001 : Within Entire Program : Dead Statements : display "Some Message"
Parent topic: Rule-Based Analysis


Including Code Analysis in a Continuous Integration Process

There are various way you can integrate code analysis into a continuous integration (CI) framework and a number of plugins that enhance the features. The following examples provide some guidelines on how you can do this:

Example with CruiseControl.NET (CCNet)

The following example provides some guidelines on how to configure CCNet for analyzing COBOL projects created in Enterprise Developer for Visual Studio.

You must have a machine that has Enterprise Developer for Visual Studio installed, and the machine must be attached to CCNet.

Configure CCNet to run MSBuild build tasks using the MSBuild parameters for code analysis described in Performing Code Analysis from the Command Line. For details, see the documentation of CruiseControl.NET.

Example with Jenkins

The following example provides some guidelines on how to configure Jenkins for analyzing Eclipse COBOL projects. Before you start, you must have a machine that has Enterprise Developer for Eclipse installed. The machine must be attached to Jenkins and must have Apache Ant installed.

To integrate code analysis in Jenkins:

  1. Create a Jenkins job for analyzing COBOL projects.
  2. Configure the job that so it runs the following commands from a Windows batch command:
    rem use the following script to set the COBOL environment:
call "product-install-dir\CreateEnv.bat"
rem change to the directory on the machine that stores the COBOL sources and the .cobolBuild file:
cd workspace-dir
rem set the classpath environment variable:
set CLASSPATH=product-install-dir\bin\mfant.jar;%CLASSPATH%
rem perform code analysis using the .cobolBuild script:
ant -f .cobolBuild build.and.analyze -DanalysisFailOnError=true
  3. Optionally, you can use any suitable plugins for Jenkins to customize things such as the reports from code analysis. For example, you can use the free Log Parser Plugin (available from the Jenkins Web site) to provide better formatting of the reports.
Parent topic: Rule-Based Analysis


Configuring Rules and Rule Sets

You can configure code analysis and specify which rules are enabled for a rule set and which rules and rule sets appear on the context menus. You can also import new rules and rule sets.

You can use the following options on the Code Analysis page in Window > Preferences > Micro Focus > COBOL:

Available code analysis rules
Use this pane to enable or disable rules within a rule set and to enable or disable rule sets.
Show on Menu
Click this to specify which rules and rule sets appear on the context menu for files and projects in COBOL Explorer.
Hide from Menu
Click this to specify which rules and rule sets should not appear on the context menu for files and projects in COBOL Explorer.
Folder for additional rules definition files
Enables you to select a directory that includes additional rules definition files and import these into the IDE.
Code Analysis Enablement
Click this to hide or show the code analysis functionality within the IDE. Changing this option requires a restart of the IDE.
Parent topic: Rule-Based Analysis


Importing Rule Sets into the IDE

Enterprise Developer comes with a set of predefined rules and rule sets for a number of code analysis queries to run on COBOL applications. In addition to these, Enterprise Developer provides an import mechanism to enable you to add more rules and rule sets into the IDE.

Note: In addition to the rules supplied with the installation, you can import more rules and rule sets into Enterprise Developer. Micro Focus Enterprise Analyzer includes many more standard rules which you can reuse within the Enterprise Developer and this gives you the option to be able to customize these to create your own site-specific analyst functions which you can then publish out to your development teams. Contact Micro Focus for further information.

To import new rules and rule sets into the IDE:

  1. Copy the .xml files that contain the new rules into a directory on your machine.
  2. In the IDE, click Window > Preferences > Micro Focus > COBOL > Code Analysis.
  3. Click Edit in the Directory for additional rules definition files section.
  4. In the Edit Directory dialog box, click Browse and navigate to the directory that contains the .xml files with the new rules you want to import.
  5. Click Finish.

    This imports the files into Enterprise Developer and adds the newly imported rules and rule sets to the list on the Code Analysis preferences page.

Parent topic: Rule-Based Analysis


Importing Existing Code Analysis Reports

Enterprise Developer provides integration with some of the code analysis reports produced with either Micro Focus COBOL Analyzer or Micro Focus Enterprise Analyzer, advanced tools for code analysis.

To perform a more in-depth analysis of your code, run a Code Search Report on it in COBOL Analyzer or Enterprise Analyzer. You can export the results in XML format and then import them in Enterprise Developer to use with a project for the same source code. The results are displayed in the Code Analysis view.

To import and use the Code Search Report results into Enterprise Developer:

  1. Open the project for your source code.
  2. Navigate to the Code Analysis view.

    If it is not visible, click View > Micro Focus Code Analysis to open it.

  3. Click Import Results (Import Results) in the Code Analysis view.
  4. Navigate to and select the Code Search Report results file (.xml) and click Open.

    This loads the code analysis

  5. You can double-click on lines in the results to navigate to the source code.

    You can use the rest of the commands in the window except for rerunning the report as it is produced using a different product. The rerun option, Import Results, is disabled in this case.

Parent topic: Rule-Based Analysis


Using COBOL Source Information

COBOL Source Information (CSI) provides a quick and easy way of providing you with information about your program when you are working on it.
  • Introduction to COBOL Source Information
  • CSI Queries
Parent topic: Code Analysis


Introduction to COBOL Source Information

COBOL Source Information (CSI) provides a quick and easy way of providing you with information about your program when you are working on it. You enter a query in the Quick Browse dialog box and CSI returns the results of the query in the Search view.

CSI queries can provide a wide range of information about the makeup of a program, such as:

  • Where data items are defined, used, and modified.
  • Where paragraphs and sections are executed.
  • Which procedures a paragraph or section executes.
  • Where subprograms are called.
  • The copybook structure of your program.
  • To run a CSI query
  • CSI Query Results
  • The Quick Browse Dialog Box
Parent topic: Using COBOL Source Information
Related information
To run a CSI query
CSI Query Results


To run a CSI query

To run a CSI query:

  1. Position the cursor anywhere within the program that you want to query.
  2. Click the COBOL Source Information button ( Quick Browse button) on the toolbar. Alternatively, press Ctrl+Alt+Q or right-click in the COBOL editor and click Quick Browse.

    The Quick Browse dialog box is displayed.

  3. Specify the CSI query that you want to run, then click OK.

    The results from the query are shown in the Search view.

Every time a CSI query is made it is added to the available query list. You can select a query from the query list by clicking [image] and choosing from the available list. Over time the list can become less relevant to the type of queries you want to run or too large to use efficiently. You can clear your query list history by clicking Clear History in the Quick Browse dialog box.

Note: Background parsing needs to be enabled in order to run a CSI query. Background parsing is enabled by default, but if you have disabled it you need to re-enable it before you can run CSI queries.
Parent topic: Introduction to COBOL Source Information
Related information
CSI Queries
CSI Query Results


CSI Query Results

When you run a CSI query the results are displayed in the Search view. Exactly what is displayed in the Search view depends on the sort of query that you ran. For instance, if you query a data item the Search view shows information such as how many times the data item is referenced, how the data item is used, and the size of the data item.

The COBOL Editor displays the program source listing, highlighting lines related to the query. Where appropriate, double-clicking on a line in the Search view positions the cursor on the relevant line in the source code.

See the descriptions of the different types of query for more information on the results that are displayed for them

Parent topic: Introduction to COBOL Source Information
Related information
To run a CSI query
CSI Queries


CSI Queries

The following types of query are available:

  • Data Items
  • Procedures (Paragraphs and Sections)
  • Called Subprograms
  • COBOL Verbs
  • Special Queries
  • Wildcards
Parent topic: Using COBOL Source Information
Related information
To run a CSI query


Data Items

The term data item, as used here, includes data-names, conditions (level-88 items), constants (level-78 items) and files.

To query a data item, enter its name in the Quick Browse dialog box. Querying a data item returns the following information in the Search view:

Number of references
The number of references to this data item that have been located in the source.
Usage Indication
A letter follows the number of references, as follows:
d | The data item has no references in the Procedure Division
u | The data item is referenced in the Procedure Division, but none of these references causes modification of the item
m | The data item has references in the Procedure Division that cause modification.
Related items
The data items related to the target data item are listed.
Occurrences
All source lines containing occurrences of the data items listed are highlighted.

Additional information is returned for the following types of data item:

  • Data-name:
    • Size in bytes.
    • Section containing the data item's definition (File, Working-Storage, Linkage, Local or Special, where Special indicates a special register).
    • Level indicator for level-01 or level-77 items.
    • Subscripted indicator for items subject to an OCCURS clause.
  • Filename:
    • Type of file.
    • Minimum and maximum record sizes.
  • Level-78 item:
    • Size of the item (in alphanumeric characters).
    • The value of the constant (up to a maximum of 30 characters).

In addition to a simple data item query you can specify a complex data item query (to include only certain types of COBOL verb and/or a range of lines or procedures) or a qualified data item query.

Parent topic: CSI Queries
Related information
Wildcards
Complex Data Item Queries
Qualified Names
Examples of Data Item Queries


Complex Data Item Queries

When querying a data item you can restrict the occurrences that are highlighted to include only certain types of COBOL verb and/or to a range of lines or procedures. The syntax of the query to do this is as follows:

Syntax for Search Restriction

where range is the scope of the query and is defined as follows:

Parent topic: Data Items
Related information
Qualified Names
Examples of Data Item Queries


Qualified Names

CSI supports qualified data-names. When you query an item, you can specify A OF B as opposed to A OF C. If CSI is unable to uniquely resolve the data-name that you specify, it provides a list of synonyms of the item.

For example, if you have the following data declaration:

  01  B.
      03  A   PIC X.
  01  C.
      03  A   PIC X.

and query the name "A", CSI reports that "A" is an ambiguous name and displays the synonyms A of B and A of C.

Parent topic: Data Items
Related information
Complex Data Item Queries
Examples of Data Item Queries


Examples of Data Item Queries

Occurrences of A in procedures P1 through P3:

A AT P1 THRU P3

Occurrences of A in lines 100 through 2000:

A AT 100 THRU 2000

Occurrences of A in MOVE and SET statements:

A MOVE SET

Occurrences of A in I/O statements:

A I-O

Occurrences of A in lines 120 through 340 inclusive:

A AT #120 THRU #340
Parent topic: Data Items
Related information
Complex Data Item Queries
Qualified Names


Procedures (Paragraphs and Sections)

To query a procedure, enter its name in the Quick Browse dialog box. Querying a procedure returns the following information in the Search view:

Name | Name of the procedure.
Type | Paragraph or section, followed by the segment overlay number if the program is segmented and the procedure is not in the root overlay.
Executed from | The procedures and programs from which this procedure item is executed and the type of COBOL statement used to reference it (GO TO, PERFORM, and so on). The source lines containing the relevant statements are highlighted, and marked as "EFrom" (executed-from).
Executes | The procedures and subprograms executed from the procedure-name queried, and the type of COBOL statement involved (such as CALL or PERFORM). The corresponding source lines are highlighted.
Procedure Data | The data items used, modified and tested by the queried procedure, and those items modified many levels of PERFORM below the queried procedure.
Parent topic: CSI Queries
Related information
Wildcards


Called Subprograms

To query a subprogram, enter its name in the Quick Browse dialog box. Querying a subprogram returns the following information in the Search view:

Name /number | Name of the subprogram.
Type | Call-by-name, call-by-number (to a library routine), or to a data item. The program-name corresponding to a data item can be determined only at run time.
Executed from | The procedures which CALL/CHAIN this subprogram, and highlights the source lines containing the relevant statements.
Parent topic: CSI Queries
Related information
Wildcards


COBOL Verbs

To query a COBOL verb, enter a query of the following form in the Quick Browse dialog box:

Syntax for Finding COBOL verbs

where:

verb type
Can be one of:
  • One of the recognized COBOL verbs listed below:
    • ACCEPT
    • ADD
    • ALTER
    • CALL
    • CANCEL
    • CHAIN
    • CLOSE
    • COMMIT
    • COMPUTE
    • CONTINUE
    • DELETE
    • DISABLE
    • DISPLAY
    • DIVIDE
    • ELSE
    • ENABLE
    • END
    • END-EVALUATE
    • END-IF
    • END-INVOKE
    • END-PERFORM
    • END-SET
    • ENTER
    • ENTRY
    • EVALUATE
    • EXAMINE
    • EXEC
    • EXECUTE
    • EXHIBIT
    • EXIT
    • GENERATE
    • GO
    • GOBACK
    • IF
    • INITIALIZE
    • INITIATE
    • INSPECT
    • INVOKE
    • MERGE
    • MOVE
    • MULTIPLY
    • NEXT
    • NOTE
    • ON
    • OPEN
    • OTHERWISE
    • PERFORM
    • READ
    • READY
    • RECEIVE
    • RECOVER
    • RELEASE
    • RESET
    • RETURN
    • REWRITE
    • ROLLBACK
    • SEARCH
    • SEND
    • SERVICE
    • SET
    • SORT
    • START
    • STOP
    • STRING
    • SUBTRACT
    • SUPPRESS
    • TERMINATE
    • TRANSFORM
    • UNLOCK
    • UNSTRING
    • WHEN
    • WRITE
  • One of the following words that refers to COBOL syntax:
    Word | Syntax
    DEPENDING | GO TO ... DEPENDING ON ..
    EXCEPTION | Exception conditions such as ON SIZE ERROR and AT END
    EXIT-PROGRAM | EXIT PROGRAM (not EXIT)
    INLINE | In-line PERFORM statements
    PREPROCESSED | Statements that have been replaced by an integrated preprocessor, such as CICS
    STOP-RUN | STOP RUN (not STOP "message")
    THRU | PERFORM ... THRU
    WHEN-OTHER | WHEN OTHER (not WHEN)
    EXIT-PERFORM | EXIT PERFORM
    EXIT-CYCLE | EXIT PERFORM CYCLE
    EXIT-PARA | EXIT PARAGRAPH
    EXIT-SECTION | EXIT SECTION

  • One of the following words that identifies groups of verbs:

    Word | Group of Verbs
    ARITH | Arithmetic statements: COMPUTE, ADD, MULTIPLY, DIVIDE, and SUBTRACT.
    END-SCOPE | ANSI'85 END-verbs. For example, END-IF and END-READ.
    I-O | File operations: OPEN, CLOSE, READ, WRITE, DELETE, START, and REWRITE.
    PGMEXIT | Program exits: STOP RUN, EXIT PROGRAM, and GOBACK.
range
Is the scope of the query and is defined as follows:
Parent topic: CSI Queries
Related information
Examples of COBOL Verb Queries


Examples of COBOL Verb Queries

All COMPUTE statements:

COMPUTE

I/O statements in the procedure READ-FILES:

I-O AT READ-FILES

All arithmetic statements:

ARITH

All program exits (EXIT PROGRAM, STOP RUN, GOBACK):

PGMEXIT

All ADD statements in lines 120-340:

ADD AT #120 THRU #340
Parent topic: COBOL Verbs


Special Queries

In addition to the queries for data items, procedures, subprograms, and verbs there are a number of queries that return a wide range of information about a program.

  • CALL
    Provides a list of all the called subprograms.
  • COPY
    Displays the structure of the copybooks forming the COBOL program.
  • DEADDATA
    Provides a list of all potentially dead data items in the program.
  • LABEL
    Lists all the procedure-names in the program.
  • TIMES
    Presents a list of program statistics.
  • UNDECL
    Provides a list of all the undeclared procedures, showing where they are referenced.
  • UNEXEC
    Provides a list of all procedure-names which are not referenced explicitly by the program.
  • UNREF
    Provides a list of all data items which are not referenced explicitly by name in the Procedure Division.
Parent topic: CSI Queries


CALL

Provides a list of all the called subprograms.

Syntax:

Syntax for Restricting the List of Subprograms

Examples:

CALL

All called subprograms.

CALL DATA

All calls to data items. These are less efficient than other calls and should be avoided if possible.

If no words follow CALL, the list includes subprograms of every type.

Parent topic: Special Queries


COPY

Displays the structure of the copybooks forming the COBOL program. Nested copybooks are indented. The source lines which begin and end each copybook are highlighted.
Parent topic: Special Queries


DEADDATA

Provides a list of all potentially dead data items in the program. A data item is regarded as dead if neither it, nor any of its related data items, are referenced in the Procedure Division. This generally gives a very good indication of whether an item declared in the Data Division is actually required by the program or not. Care should be taken with:
  • Data items used by conditionally compiled code.
  • Data items defined in special clauses and not referenced explicitly in the Procedure Division (for example, FILE STATUS IS ...) and Screen Section (TO, FROM).
Parent topic: Special Queries


LABEL

Lists all the procedure-names in the program.
Parent topic: Special Queries


TIMES

Presents a list of program statistics. This consists of the following information:
Lines of Source | Total number of source lines
Lines of Code | Lines of Procedure Division code
Comment Lines | Number of comments (both * in column 7 and end of line comments "*>")
Text Comments | Number of comments containing at least character A-Z, a-z, or 0-9. This generally provides a better indication of the number of meaningful comments in a program
Comment Ratio | Number of text comments for every 100 source lines
Section | Number of section-names
Statements | Total number of COBOL statements
Paragraphs | Number of paragraph-names
Files | Number of files (FDs)
Data Items | Number of data items
Conditions | Number of conditions (level-88 items)
Screen-names | Number of screen-names (Screen Section syntax)
Report | Number of report-names (Report Writer syntax)
Constant | Number of level-78 items
Call (by name) | Number of call-by-name subprograms used
Call (by number) | Number of call-by-number routines used
Call (data item) | Number of data items used as called subprogram-names
Verb counts | Number of verbs for each type of statement, including the number of statements for each type of group (for example, Program Exits, Arithmetic)
Arithmetic | Total number of all ADD, COMPUTE, DIVIDE, MULTIPLY, SUBTRACT statements in the code.
Maximum Nesting | Maximum nesting level of in-line constructs; such as IF, EVALUATE, in-line PERFORM
Overlapping Performs | Number of paragraphs/sections that lie in more than one PERFORM...THRU range
Program Volume An assessment of the number of operators and operands in the program. It is calculated as (N1 + N2) LOG2 (n1 + n2)

where the parameters are:

N1
Total number of statements
N2
Number of references to all identifier-names
n1
Number of unique verb types
n2
Number of identifier-names
Total Data | Data size of .int code
INT Code | Procedure size of .int code (root segment only)
Linkage 01s | Level-01 items in the Linkage Section

Comments:

The values of these statistics might not be strictly accurate for those programs compiled with an integrated preprocessor, and can vary slightly depending on the COBOL language dialect specified when you syntax-checked your program.

Parent topic: Special Queries


UNDECL

Provides a list of all the undeclared procedures, showing where they are referenced. This is generally empty, unless the result of syntax-checking your program is one or more syntax error COBCH0348 messages ("Procedure name procedure-name undeclared, first used on line line-number").
Parent topic: Special Queries
Related information
COBCH0348 Procedure name procedure-name undeclared, first used on line line-number


UNEXEC

Provides a list of all procedure-names which are not referenced explicitly by the program. These procedure-names are not necessarily redundant since they might affect the end of PERFORM ranges, but this information can help you locate dead procedures.
Parent topic: Special Queries


UNREF

Provides a list of all data items which are not referenced explicitly by name in the Procedure Division.
Parent topic: Special Queries


Wildcards

If you include the wildcards "*" or "?" in the name that you query, a list of all the names that match the wildcard string is produced, and their source line definitions are highlighted.

Note:
  • "*" can only be used once and must be the first or last character of the query
  • "?" can be used more than once and can occur anywhere within the query
Parent topic: CSI Queries


Debugging COBOL applications

Your COBOL development system provides a debugging environment where the source code of each program is displayed in a separate window.

When you debug the code you can step through it so that each line of the source is highlighted in turn as each statement is executed, showing the effect of each statement. You can interrupt execution to examine and change data items, in a number of ways.

The features available while debugging include:

  • Running all or part of the program, and stepping through the program one statement at a time
  • Executing the program until it reaches a specified point, such as the end of a procedure or a breakpoint that you specify
  • Skipping statements you do not want to execute, such as a procedure call and the corresponding procedure.
  • Examining and manipulating data items while debugging
  • Examining the threads that are running and switching execution between them

There are a number of ways to debug code, such as compiling the source yourself first or letting it happen automatically or making available the necessary files created during an earlier compilation. For example you can:

  • Automatically start debugging when the application fails
  • Debug non-COBOL programs in mixed language applications
  • Debug a remote program that is running on a different computer
  • Debug services and applications that are running on a local or a remote enterprise server

You control the way debugging works by using Debug configurations.

  • Overview of the process of debugging
  • Preparing a Project for Debugging
  • Debugging Features and Techniques in Eclipse
  • Debugging Scenarios
Parent topic: Developing Applications in the IDE


Overview of the process of debugging

Enterprise Developer offers some powerful tools to help you debug local and remote projects. It also supports debugging of standalone files which are not part of a project. This is a brief overview of how to prepare and debug an application.

Debugging applications that have a project

  1. Ensure that the current active build configuration is compiling the project for debugging. See Compile for Debugging.
  2. Compile the source code - by default, Eclipse compiles your projects automatically when the projects change.

    If Project > Build Automatically is turned off, to compile click Project > Build Project.

  3. Choose or create a debug configuration by clicking Run > Debug Configurations. Different types of COBOL debug configurations are available for different types of debug sessions, where each type of configuration offers different options and requires different specifications. Like build configurations, you can have multiple debug configurations and swap between them. These settings override the project's run-time settings.
  4. Click Debug.

    Eclipse opens the Debug perspective that provides views that facilitate debugging.

  5. Use the options on the Run menu to step through the program, stop at breakpoints and query data item values and so on.

    See Debugging Features and Techniques in Eclipse for tips on the commands and features that are available during debugging.

  6. To stop debugging, click Run > Terminate.
  7. To return to either the COBOL or the Team Developer perspective, click COBOL Perspective, COBOL, or Team Developer Perspective, Team Developer, at the top right of the Eclipse window.

Debugging standalone files

You can use the IDE to debug a standalone native COBOL program that is not a part of a project. The file must be compiled for debugging first to produce the information that the debugger requires.

To debug a standalone file:

  1. If necessary, compile the program in the IDE by right-clicking in the editor and clicking Compile.

    Eclipse either used the Compiler directives provided by the associated program symbols file (.idy) or, if no .idy file is present, uses the directives specified in Window > Preferences > Micro Focus > COBOL > Standalone Files > Compile.

  2. Right-click the file in the editor and click Debug As > COBOL Application.

    This starts debugging and the IDE switches to the Debug perspective.

  3. Step through the program in the usual way.
Parent topic: Debugging COBOL applications
Related concepts
Setting Compiler Directives on Individual Files
Compile for Debugging
Debugging Commands and Options
Related tasks
Compile for Debugging


Preparing a Project for Debugging

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

  • Compile for Debugging
  • Creating a Debug Configuration
  • Preparing Remote Projects for Debugging
Parent topic: Debugging COBOL applications


Compile for Debugging

To debug a program, you need to configure the build process to create all the files needed for debugging.

Compile a project for debugging

You do this by using a build configuration for your project with the Compile for debugging option selected. To see your current build configurations, and create new ones:

  1. Right-click on your project in COBOL Explorer
  2. Click Properties > Micro Focus > Build Configurations.
  3. Select a build configuration and click the COBOL tab.
  4. Check Enable configuration specific settings and ensure Compile for debugging is checked.
  5. Build your project.

Compile a standalone file for debugging

When working with standalone COBOL programs (such that are opened in the IDE without a project), the IDE first searches for the program symbols files to provide debug information.

If no .idy files are found in any of the locations specified on the Program Symbols (.IDY) page in Window > Preferences > Micro Focus > COBOL > Standalone Files, you need to manually recompile the file to produce the debug information. You can recompile from the command line or from within the IDE. To compile for debugging in the IDE:

  1. Check the Compiler directives for compiling standalone files - click Window > Preferences > Micro Focus > COBOL > Standalone Files > Compile.
  2. Ensure that the anim Compiler directive is included then click OK.
  3. Right-click your standalone file in the editor and click Compile.
Parent topic: Preparing a Project for Debugging
Related concepts
Setting Compiler Directives on Individual Files
Overview of the process of debugging
Related tasks
Overview of the process of debugging


Creating a Debug Configuration

You need a debug configuration before you can debug a program. This configuration defines items such as the search order for called programs, run-time arguments, run-time tunables, and COBOL switches.

  1. Click Run > Debug Configurations.
  2. Select the type of configuration you want in the pane on the left click New launch configuration,New launch configuration, to create the new configuration.

    Depending on the configuration you have selected, different options will be displayed in the right hand pane. If you are creating an application configuration you can set any required environment variables, run-time arguments, and COBOL switches using the options in the appropriate tabs.

    Depending on the type of project you are debugging, many of the configuration fields will be automatically filled.

See the topics below for information about some of the debug configurations for COBOL applications and their options:

  • COBOL Application, COBOL Attach to Process, and COBOL Wait for Application Attachment
  • COBOL Core Dump
  • COBOL Live Recording
  • COBOL JVM Application and COBOL JVM Remote Application
Parent topic: Preparing a Project for Debugging
Related reference
CBL_DEBUG_START


COBOL Application, COBOL Attach to Process, and COBOL Wait for Application Attachment

Use COBOL Attach to Process to debug an application when it has been called by another application already running. Use COBOL Wait for Application Attachment to wait for a COBOL application to be run and attach to it when it is started. Any remote application must have been compiled for debugging.

General tab

The options common to the General tab in the Debug Configurations dialog box for these configurations are:

COBOL Project
The project that will be used while debugging.
Connection Properties
Enter values for these fields if you want to debug your project or the application when it is running on a remote machine.
Remote Host
The name or IP address of the remote machine.
Specify the port on which cobdebugremote process will listen on the remote host
When you are debugging an application on a remote machine, the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) needs to be running on that machine.
If you are developing the application on the remote machine
If you are using Micro Focus Enterprise Developer UNIX Components, the IDE starts the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) automatically on the remote machine when you start debugging. You do not need to select a port as a random one is picked when the process starts, but if you select this option you can assign a specific port in the cobdebugremote port field. If you do specify a port, the process starts automatically on that port.
If you are developing the application on the local machine and debugging remotely
You must first start the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) from a command prompt.
The process takes the following options:
no options
Starts the process and opens a random port for remote connections. The port number is displayed in the console.
machine=name
Specify the machine that the process is running on. Only valid with the stop option.
port
port=nnnnn
Specify the port to use to listen for connection requests.
port=nnnnn-yyyyy
Specify the range of ports to use. If port nnnnn is in use, the next port is tried until a free port is found. If no free ports are found in the range, the utility returns an error.
Note: You must enter the same number you set as the port option in the cobdebugremote port field of your debug configuration.
repeat
After the debug session has been completed, start listening for another connection. If no option is specified, the process exits after the debug session has completed.
stop
Causes the process that is listening on the port to exit. Must be used with the port option. This is only valid when the process is waiting for a connection.
If you run the process with no options, you must enter the port number displayed in the console in the cobdebugremote port field.
X Server (DISPLAY)
If you are debugging an application on a remote UNIX machine using Micro Focus Enterprise Developer UNIX Components, enter the identifier for the X server that will display the remote program output on a local Windows machine. The default value is client machine name:0.0.
Before debugging, make sure that the X server is running and that the remote machine xhost configuration has the correct access permissions. You can use the xhost + command to add your host or username to the list of those permitted.
Debug Options
Use these options to further control the debugging process.
  • To ensure debugging works correctly, you must indicate when the application you are debugging is 64-bit or graphical.
  • Select Suspend at 'stop run' to keep debugging your program by suspending it, rather than terminating it, when a STOP RUN command is executed.
  • To specify that a program breakpoint causes execution to stop only when the Procedure Division entry point is called, check Program breakpoint on main entry point only. With this option unchecked, which is the default, a program breakpoint causes execution to stop on any entry point to the program and on return to the program from a call.
  • To allow you to move forwards and backwards through the execution path whilst debugging, select Enable reverse debugging.
    Note: You can only select this option if you have selected a project/program located on a platform that supports reverse debugging - see Reverse Debug and Live Recording for a list of supported platforms.
The following settings are only applicable to COBOL Application debug configurations:
Main Program
Select the main executable in your project. If you have already selected this in a build configuration you only need enter the build configuration name, otherwise you can browse to the program's location in your project.
Start Options
Enter the arguments to pass to the program when it starts. You can also indicate the working directory of the application if the project doesn't explicitly specify its location.
Run Options
Check Pause after running the application to prevent the application terminal from automatically closing once it has completed running. This option gives you time to note any terminal output. Press Enter to close the terminal.
Debug Options
  • Select Allow debugging of all COBOL target types in order to debug any executable compiled with COBOL code. If you do not select this option, only .int code will be debugged. If you choose this type of debugging, you cannot debug non-COBOL projects that have both COBOL and non-COBOL programs calling each other.
  • All Windows programs run in multi-threaded run-time systems. For UNIX programs, select Use multi-thread run-time system to do the same, otherwise the single-threaded system is used.
The following settings are only applicable to COBOL Wait for Application Attachment debug configurations:
Matching Options
Specifies which programs the debugger attaches to when the program starts:
  • Any - the debugger attaches to any process that is enabled for debugging. For instance, using the environment variable COBSW=+A or by a call to CBL_DEBUG_START.
    Note: This option is only available when debugging applications running on Windows.
  • Program identifier - specify the identifier of the program the debugger should attach to. The matching program identifier value should be passed as a parameter to the CBL_DEBUG_START library routine called by the application to be debugged - see CBL_DEBUG_START.
  • Executables stored in directory:
    • On Windows platforms, specify the directory which contains the main executable used to start the process.
    • On UNIX platforms, specify the current directory of the process.
Return to waiting state when debugger disconnects
If you select this the debugger will wait until a debuggable program attaches to it again. If you do not select it, debugging terminates when it disconnects from the program.

Source tab

The options common to the Source tab in the Debug Configurations dialog box for these configurations are:

Source Lookup Path
Enables you to specify the locations and order in which the debugger looks for source files.

Click Add to add locations:

COBOL Project
Click this to choose the projects to search. Any folders and dependent projects specified on the Micro Focus > Build Path tab in the projects' properties is also searched.
Environment Variable
Click this to select one or more variables that include the folders that must be searched.
File System Directory
Click this to specify a specific file system folder to be searched that may exist outside the workspace.
Paths From Debugger Information Files
Click this to enable the debugger to locate the source file using the path specified in the .idy file, this is the path stored when the program was compiled. The source file can be outside of the workspace and means that the project containing the source file does not need to be added to the source lookup.
Project
Click this to enable folders in a specific project to be searched.
Remote File System Directory
Click this to specify a specific remote file system folder located on the remote project's host. This option is only available if you have specified the Remote Host field in the Connection Properties group on the General tab.
Working Set
Click this to add the source lookup path for all the visible projects defined in a working set, see Working Sets.
Workspace
Click this to search all folders within the current workspace.
Workspace Folder
Click this to enable you to specify a specific folder within your workspace as a source lookup path.

Debug Symbols tab

The options available in the Debug Symbols tab in the Debug Configurations dialog box for these configurations are:

Debug Symbols Lookup Path
Enables you to specify the locations and order in which the debugger looks for debug symbols containers and files.

Click Add to add locations:

Environment Variable
Click this to select one or more variables that include the folders that must be searched.
File System Directory
Click this to specify a specific file system folder to be searched that may exist outside the workspace.
Project
Click this to enable folders in a specific project to be searched.
Remote File System Directory
Click this to open the Add File System Directory dialog box. Specify or browse to a specific remote file system folder located on the remote project's host. Check Search subfolders if you want to search recursively through subfolders. This option is only available if you have specified the Remote Host field in the Connection Properties group on the General tab.
Workspace Folder
Click this to enable you to specify a specific folder within your workspace as a debug symbols lookup path.
Note: Debug symbols containers length must not exceed 32,725 characters.
Parent topic: Creating a Debug Configuration
Related concepts
Reverse Debug and Live Recording


COBOL Core Dump

Use a COBOL Core Dump debug configuration to save a core dump file when your application crashes. You must do this in combination with the run-time tunable core_on_error, which specifies in what circumstances a core file is produced. The options are:

COBOL Project
The project that will be used while debugging.

You can debug a core dump file without a project. You need to specify the location of the debug symbols file (.idy) on the other tabs of the debug configuration.

Core Dump File
Enter the location of where a core dump is stored. If you only specify the directory, and no core dump filename, Eclipse will prompt you for the filename when the debugger starts. The filename is cblcore by default, but you can change this using the run-time tunable core_filename.
Executables Location
Identify a working directory. You can set this automatically to whichever directory you chose to store the core dump file.
Parent topic: Creating a Debug Configuration


COBOL Live Recording

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.

Note: Windows users: to debug a live recording file, you must connect to Micro Focus Enterprise Developer UNIX Components running on one of the supported platforms listed above.

Use a COBOL Live Recording debug configuration to debug a live recording file (.mfr file). Once the recording is loaded into the debugger, you can step forwards and backwards to follow the execution.

Unlike a conventional debug scenario, debugging a live recording file only allows you to step forwards/backwards through the path that the application took when it was recorded; you cannot change the execution path within the debug engine.

COBOL Project
The project to use while debugging.
Connection Properties
If your live recording file is located on a Micro Focus Enterprise Developer UNIX Components, specify the connection details.
Live Recording File
The name and location of a live recording file to debug.
Executables Location
The directory that contains the application executable files that were run to create the live recording file.
Source Files
The location of the application source files that were used to build the executables.
Debug Symbols
The location of the debug symbols (.idy) files that were generated when the executable files were built.
Parent topic: Creating a Debug Configuration
Related concepts
Debugging Using a Live Recording
Reverse Debug and Live Recording


COBOL JVM Application and COBOL JVM Remote Application

Use these debug configuration to control debugging of Java Virtual Machine applications. COBOL JVM Remote Application refers to JVM applications developed on a remote machine.

The options are:

COBOL Project
The project that will be used to locate the program source while debugging.
Main class
The class to be used as the main Java class. When you click Search you can choose a class from a list of those in your application. Select Include system libraries when searching for a main class or Include inherited mains when searching for a main class to show additional classes in your workspace.
Stop in main
Select this if you want the program to stop in the main method when the program is launched in debug mode.
Connection Properties (COBOL JVM Remote Application only)
The properties used to connect to the remote host when the debug configuration is launched. As the remote host connection details are already known, you cannot update the remote host name, but you can change the port on which to debug and the location of your X Server implementation:
Specify the port on which the Java debugger will start on the remote host
If you want to specify a specific port, select this option, then enter the port number in the Java debug port field.
X Server (DISPLAY)
The identifier for the X Server that will display the remote program output on your local Windows machine. This defaults to client machine name:0.0.
Before debugging, make sure that the X Server is running and that the remote machine xhost configuration has the correct access permissions. You can use the xhost + command to add your host or user name to the list of those permitted.
Parent topic: Creating a Debug Configuration


Preparing Remote Projects for Debugging

You use a COBOL Application debug configuration to debug projects developed on a remote UNIX machine. Before you can debug the remote application, you need to have an X window implementation installed and running, so that the output of a remote application running on a UNIX machine can be viewed on your local machine. You do not need X window for other debug configuration types.

Windows:

Micro Focus ViewNow X is provided as part of Enterprise Developer. See Installing X Windows on Windows in the Installation section. Find the ViewNow X documentation on the Micro Focus SupportLine dropdown menu.

UNIX:
Ensure the local X11 server can receive connections from the remote machine. You can do this using the xhost + command or by enabling SSH port forwarding. Alternatively, enable TCP/IP connections for X11 by setting a value in a configuration file in a manner appropriate to your operating system. For example:
  • Red Hat: run the gdmsetup utility and deselect Deny TCP connections to Xserver in the Security tab (this configures DisallowTCP=false in /etc/gdm/custom.conf)
  • SUSE: set DISPLAYMANAGER_XSERVER_TCP_PORT_6000_OPEN="yes" in /etc/sysconfig/displaymanager

Specify the details about the display that the X11 server tries to contact in the IDE preferences as follows:

  1. Click Window > Preferences > Micro Focus > Debug.
  2. Type the display details in the Default X Server (DISPLAY) field.

    The default Default X Server (DISPLAY) value is clientMachineName:0.0. This configuration applies to both remote COBOL and PL/I projects.

Parent topic: Preparing a Project for Debugging


Debugging Features and Techniques in Eclipse

  • Views in the Debug Perspective
  • Using Breakpoints and Watchpoints
  • Debugging Commands and Options
  • Debugging in COBOL Copy View
Parent topic: Debugging COBOL applications


Views in the Debug Perspective

When you start debugging, the Debug perspective is displayed, with the views useful for debugging. The default views are listed below; you can display them by clicking Window > Show View.

Debug view
This view gives a dynamic view of all the threads. For each thread, this view shows the call/perform stack, showing where the current statement was called from or performed from, and where previous calls and performs came from. You can move the execution point, by right-clicking a thread and choosing an option from the menu.
Variables view
Shows the values of variables and file statuses of internal file names in use on the current or previous line of code. Those which have just changed in the last statement executed are highlighted.
You can configure the contents of this view in Preferences > Micro Focus > COBOL > Debug, to display values as hexadecimal, for example.
For procedural COBOL: Shows the data items in the previous and current statements, together with the data items' values.

For OO COBOL: Shows all the local data items and parameters and the SELF item (containing all fields).

You can change values of the variables in this view. Select a variable from the list, right-click and select Change Value. A dialog box is displayed.

Breakpoints View
Shows the breakpoints and the watchpoints you have set, and enables you to set a breakpoint for any program the application calls. You can set actions to take when a breakpoint is hit, by setting the actions in the breakpoint's properties. You can add watchpoints so that execution suspends when the data item changes.

You can set a breakpoint or watchpoint by double clicking in the margin of the code view.

You can create a breakpoint for any program in the workspace that your application uses by clicking Run > Add Program Breakpoint, or clicking the [image] icon in the Breakpoints view, and entering the name of the file.
Expressions view
Shows the values of data items that you choose to monitor, whether or not they are directly accessed by the current execution statement while debugging.

During a debug session, you can add a data item to this view by selecting it in the code view, right-clicking and choosing Inspect COBOL and then choosing Add to Expressions.

You can also add an arbitrary expression in the view by clicking Add new expression or [image] in the Expressions view. The added expression can be any string, but to be evaluated it needs to be a valid expression.

Restriction: Currently we support evaluation of data items only, and not complex expressions.
Memory view
You can use the Memory view to monitor or change the value of a data item or for data in a specified address. You can display the contents of the memory in Hex, ASCII or EBCDIC format rendering.
CICS Channel view
Shows an expandable list of channels and the containers they contain, and also provides a view of the data stored in each container.

You can also debug in COBOL Copy View, which expands copybooks in line, so you can use it to perform debugging of your code and copybooks in a single view.

Parent topic: Debugging Features and Techniques in Eclipse


Using Breakpoints and Watchpoints

A breakpoint indicates a line of code or program at which you want the execution of an application to pause, a watchpoint indicates a data item whose change in value causes the execution of your application to pause. When the application is paused, you can view and change the values of data items at that particular step. The Breakpoints property view shows details of all bound breakpoints and watchpoints, and enables you to configure them.

You set breakpoints and watchpoints by:

  • Double-clicking on the marker bar to the left of the requisite line of executable source code for a breakpoint, or to the left of the requisite Working Storage item for a watchpoint.
  • Right-clicking on the marker bar and choosing either Toggle Breakpoint or Toggle Watchpoint from the context menu.
  • Right-clicking on a paragraph name, section name, or data item name in the Outline view and choosing Toggle Breakpoint or Toggle Watchpoint from the context menu.
  • Using the above methods to create a breakpoint at the Procedure Division heading creates a program breakpoint.

    You can create a breakpoint for any program in the workspace that your application uses by clicking Run > Add Program Breakpoint, or clicking the [image] icon in the Breakpoints view, and entering the name of the file.

The [image] icon appears in the marker bar when a breakpoint is set, and the [image] icon when a watchpoint is set. A tick mark is added to these icons when the breakpoint [image] or watchpoint [image] is bound to the program. A program breakpoint is indicated by the [image] icon.

Note: Breakpoints in Eclipse are set in source files, not in programs (as they are in other Micro Focus products). This means that a single breakpoint may actually be encountered many times if the source file is used in multiple programs or used multiple times in the same program. For example:

Main.cbl:

Procedure division.
       Copy "Code.cpy".
       …
       Copy "Code.cpy".

Code.cpy:

       Add 1 to count		// set breakpoint here

When a breakpoint is set before debugging is started, or no program that uses the copybook is active, the breakpoint is pending. This means that it has not been resolved to a real code position. When debugging is started or a new program is called, the debugger attempts to resolve all pending breakpoints and bind them to actual code positions.

In the above example, when the main executable is loaded by the debugger it binds the single (pending) breakpoint to two actual (bound) breakpoints. The breakpoints are then shown with a plus sign added to the breakpoint icon [image], both in the margin of the editor and in the Breakpoints view.

  • Setting Conditional Breakpoints and Watchpoints
    Set conditional breakpoints and conditional watchpoints, which only break execution when a coded condition or a hit count is satisfied.
Parent topic: Debugging Features and Techniques in Eclipse


Setting Conditional Breakpoints and Watchpoints

Conditional breakpoints and conditional watchpoints only break execution when a coded condition or a hit count is satisfied. You can combine both a condition and a hit count, where both must be satisfied before execution will break.

To set a conditional breakpoint or watchpoint:

  1. Set a breakpoint or watchpoint using one of the methods outlined in Using Breakpoints and Watchpoints.
  2. Right-click the breakpoint icon ( [image]) or watchpoint icon ( [image]) in the marker bar, and then select Breakpoint Properties.

    This opens a Properties dialog box.

  3. To add a hit count, select Hit count, click [image] and select the required operator, and then enter the required value.
  4. To add a condition, click Condition, and then in the Conditional statement field, type your statement.
    Tip: To help you construct a condition, press Ctrl + Space to display the code assist list: a list of valid COBOL syntax and defined data items.
  5. Click Apply and Close.

    The conditional breakpoint or watchpoint is set, as indicated in the marker bar, and will in effect the next time you debug the application.

    When debugging conditional watchpoints, since execution breaks when the item has been changed, the cursor position will be on the statement after the statement that caused the data item to change value.

Parent topic: Using Breakpoints and Watchpoints


Debugging Commands and Options

The Eclipse IDE offers a number of debugging features and techniques:

Breakpoint-setting
Run > Toggle Breakpoint or double-click in the left margin.
Tip: To set or toggle a program breakpoint, double-click in the left margin next to the Procedure Division heading, or use the Breakpoints view. Program breakpoints are supported in native COBOL only, and are not supported with nested programs.

By default, a program breakpoint causes execution to stop on any entry point to the program and on return to the program from a call. To specify that a program breakpoint causes execution to stop only when the Procedure Division entry point is called, open the launch configuration of the project (click Run > Run Configurations), and check Program breakpoint on main entry point only on the General tab of the configuration.

Data item values
To display a data item's value, you can hover over it, or alternatively right-click it and click Inspect COBOL.
Debug configurations
Run > Debug Configurations. You can have multiple debug configurations and swap between them. These settings here override the project run-time settings
Main program to debug
Run > Debug. On the General tab, specify the main program file.
Reset execution
Moves the execution point to the cursor position. The shortcut key is Alt+F12, R.
Preferences
Window > Preferences > Micro Focus > COBOL > Debug. Among other things, you can choose to display hexadecimal and byte values of data items.
Run to line
You can position your cursor anywhere in your code to instruct the debugger to run from the current execution point to the line on which the cursor is positioned. The feature can save time when debugging as you do not have to use the step functions to step through individual lines of code. You can use Run to line in both the main source code and copybook code. To use, position the cursor in the code and the click Run > Run to line or use the shortcut CTRL+R.
Reverse debugging
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.

Note: Windows users: to use this option, you must connect to Micro Focus Enterprise Developer UNIX Components running on one of the supported platforms listed above.

When the Enable reverse debug box on the Debug Configurations dialog is checked for the active debug configuration, the Enterprise Developer debugger records your debug session as you step forward through a program or application. You can then access the recorded information by stepping backwards through the application. Stepping backwards puts you into reverse mode where what you see is from a recording, and is not live. Therefore, input is not accepted when running in reverse mode. You can also step forwards within the recorded session, and proceed in live mode when you reach the point at which you first stepped back. Once in live mode, input is again accepted.

When in reverse mode, the debugger behaves much the same as it does in live mode, showing program position, stage of debugging, and variable names and values.

Stop debugging
Run > Terminate. You can also click the red square at the top
Watchpoint-setting
Run > Toggle Watchpoint or double-click in the left margin.
Restriction: This feature is not supported for JVM COBOL.
Inspect COBOL variables
Allows you to inspect COBOL variables. The cursor in the editor has to be positioned on a data item, or a data item can be selected. Inspecting works like Expressions view - any text can be selected in the editor (COBOL Editor or Copy View) for evaluation.
  • For native (local and remote projects): Run > Inspect COBOL item
  • For JVM COBOL projects: Run > Inspect
Inspect can also be triggered from a context menu in the editor or by using the Ctrl+Shift+I shortcut.
Restriction: Only inspection of data items is supported. More complex expressions like arithmetic operations or method calls are not currently supported.
Keyboard shortcuts - debugging
  • F5 = Step into the next statement at the current line of code and suspend execution. Equivalent of clicking [image].
  • F6 = Step over the next statement at the currently executing line of code without entering it, and suspend execution. The method will be executed normally. Equivalent of clicking [image].
  • F7 = Return from a method or paragraph that has been stepped into, and suspend execution. The remainder of the code inside the method is executed normally. Equivalent of clicking [image].
  • F8 = Resume execution of the program from a suspended line of code. Equivalent of clicking [image].
You can also click the Drop to Frame button [image] to reposition you at the start of the current method.
Keyboard shortcuts - Reverse debugging
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.

When the Enable reverse debug Debug Option is checked, the following shortcuts are also available:
  • Ctrl+F5 = Step into the previous statement at the current line of code. Equivalent of clicking [image].
  • Ctrl+F6 = Step over the previous statement at the current line of code without entering it. Equivalent of clicking [image].
  • Ctrl+F7 = Return from a method or paragraph that has been stepped back into in reverse mode. Equivalent of clicking [image].
  • Ctrl+F8 = Resume execution in reverse mode. Execution stops when it reaches the start of the recording or encounters a breakpoint. Equivalent of clicking [image].
Querying the value of a data item or the file status of an internal file name
Hold the mouse pointer over a data item or internal file name and the current value or file status displays as a Text Hover. The values of variables and file statuses of internal file names contained on the current execution line and previous line are displayed in Variables View (usually displayed in the top right of the IDE).
Dealing with unassigned linkage items

If the debugger steps on a line with an unassigned linkage item (for example, if you are debugging only a part of your application and no memory has been allocated to that linkage item), debugging terminates. To assign linkage to that data item and continue debugging, you need to select the data item, right-click it and click Inspect COBOL. When prompted, confirm and assign a value to the data item. Alternatively, to assign linkage, you can right-click the data item in the Variables view and click Change Value.

Parent topic: Debugging Features and Techniques in Eclipse
Related concepts
Overview of the process of debugging
Reverse Debug and Live Recording


Debugging in COBOL Copy View

You can debug a project using the COBOL Copy View that enables you to see both your source files and any copybook that they use in a single view.

To enable debugging in COBOL Copy View:

  1. Click Window > Preferences > Micro Focus > COBOL > Debug.
  2. Click COBOL Copy View in the Debugging source viewer options, then click OK.

It is not possible to change the source viewer after a debugging session has started. To change the source viewer, you must first stop the debug session, choose the preferred viewer, and then restart the debug session.

Parent topic: Debugging Features and Techniques in Eclipse


Debugging Scenarios

The following section includes a list of some of the ways you can debug applications using Eclipse:

  • Start the debugger automatically - you can either use library routines for this, which is suitable for debugging dynamic link libraries that are called by other programs, or use just-in-time debugging, suitable when Eclipse is not running and a run-time error in the code occurs.
  • Debug using a core dump - 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. This is useful when an application crashes in a production environment that doesn't have Enterprise Developer installed.
  • Debug Windows services - you can use library routines or JIT debugging.
  • Debug mixed language applications - there are various ways you can create a debug configuration for debugging mixed Java and COBOL applications.
  • Debug MSS applications on Enterprise Server - your enterprise server instance must be configured for dynamic debugging.
  • Starting the Debugger Automatically
  • Debugging Windows Services
  • Debugging Using a Core Dump
    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.
  • Debugging Using a Live Recording
  • Debugging Using a Remote Machine
  • Debugging CICS Channels and Containers
    Describes using the CICS Channels view as you debug COBOL that uses CICS channels and containers.
  • Debugging Mixed Language Applications
  • Debugging Mainframe Applications and Services on Enterprise Server
    To debug applications and services you need to run them on an enterprise server that has the Dynamic Debugging option set.
  • Debugging Enterprise Server Services and Applications Using a Live Recording
  • Debugging with Character Animator
Parent topic: Debugging COBOL applications


Starting the Debugger Automatically

  • Starting the Debugger automatically using library routines
  • Starting the debugger automatically using just-in-time debugging
Parent topic: Debugging Scenarios


Starting the Debugger automatically using library routines

You can cause debugging to be triggered at a specific point in your code by using the CBL_DEBUGBREAK and CBL_DEBUG_START library routines. This is particularly useful for debugging Windows dynamic link libraries that are called by other programs.

These statements are often included through conditional compilation so that they can be enabled or disabled by setting a directive. In the example below, CBL_DEBUGBREAK is called only if the user sets CONSTANT DEBUG(1) as a compiler directive before building the application.

Use CBL_DEBUGBREAK to invoke the debugger (Windows) or Animator (UNIX).

Alternatively use CBL_DEBUG_START and CBL_DEBUG_STOP to respectively attach and detach the debugger to the application. These routines include parameters that give you more control over debugging, such as identifying which debugger process should start and how long to wait for it to do so.

  1. Add calls to the routines at the relevant points in your programs, and rebuild your application.
  2. Click Run > Debug Configurations.
  3. Click COBOL Wait for Application Attachment .
  4. Select the configuration you want or enter a name for a new configuration.
  5. Select the debug options you require.
  6. On the Debug Symbols tab, specify the location of the COBOL symbol (.idy) files.
  7. Click Debug.

The debugger remains in a wait state until CBL_DEBUGBREAK or CBL_DEBUG_START is executed. If you use CBL_DEBUG_START you can then use CBL_DEBUG_STOP to detach the debugger from the application, which resumes running without the debugging features.

CBL_DEBUGBREAK Example

            perform with test after
               until char not = "Y" and char not = "y"
               call clear-screen

               display
                   "To select a square type a number between 1 and 9"
                   upon crt
               perform init
               move "Shall I start ? " to question
               perform get-reply
                  $if DEBUG defined
                     call "CBL_DEBUGBREAK"
                  $end
               if char = "Y" or char = "y"
                     move 10 to check(5)
                   perform put-move
               end-if
               perform new-move
               until game not = spaces
               move "Play again ?    " to question
               perform get-reply
           end-perform.

CBL_DEBUG_START/STOP Example

       working-storage section.
       copy 'cbltypes.cpy'.

       01 dbg.
           02 flgs             cblt-os-flags.
           02 tmout            cblt-os-ssize.
           02 identifier       pic x(80) value "XsessID ".
           02 st-code          pic x(2) COMP-5.

       01 transaction          pic x(80).

       01 stop-flags           cblt-os-flags.

       01 argument             pic x(80).

       procedure division.
          move "transaction" to argument

           *> Set CBL_DEBUG_START flags to :-
           *> Start debugging via a waiting debugger,
           *> when a debuggable program is entered.
           *> Error if no debugger is available.
           *>
           move h"03" to flgs
           move 0 to tmout

           *> Set CBL_DEBUG_STOP flags to :-
           *> Stop debugging and return the debugger to
           *> a waiting state
           *>
           move h"01" to stop-flags

           *> Run the transaction
           perform run-transaction

             call "CBL_THREAD_SLEEP" using by value 5000 size 4

           *> Run the transaction
           perform run-transaction
           stop run.

       run-transaction section.
           call "CBL_DEBUG_START" using by value flgs
                                                 tmout
                                    by reference identifier
                                       returning st-code
           if st-code not = 0
               display "No waiting debugger"
               goback
           end-if

           call argument

           call "CBL_DEBUG_STOP" using by value stop-flags
                                     returning st-code
           if st-code not = 0
               display "Failed to stop debugger"
           end-if
           .
Parent topic: Starting the Debugger Automatically


Starting the debugger automatically using just-in-time debugging

You can trigger debugging when Eclipse is not running using the just-in-time debugging feature. When this is enabled, an application stops when a run-time error occurs or if the code contains CBL_DEBUGBREAK and CBL_DEBUG_START library routines, and Eclipse starts in the debugging perspective.

The debugger attaches to the failed process and the relevant line of source is highlighted. You can view the contents of data items and memory and step through the code using the standard debugging techniques.

By default, when just-in-time debugging launches Eclipse, only the source file is opened and no associated project. This means that there are no background parse errors or warnings shown, and editing the source is impossible. However, in UNIX environments you can configure Eclipse to open in a particular workspace, so that you can see the file in the context of a project and use background parsing and other editing features.

To enable just-in-time debugging on CBL_DEBUGBREAK or CBL_DEBUG_START

Windows:
  1. Open Eclipse and click Window > Preferences > Micro Focus > COBOL > Debug.
  2. Select Enable JIT debugging.
UNIX:
  1. Use the COBJIT_ECLIPSE environment variable to ensure the Eclipse IDE is launched when the CBL_DEBUGBREAK or CBL_DEBUG_START statement is executed:
    COBJIT_ECLIPSE=true <workspace to open on error>

To enable just-in-time debugging when a run-time error occurs

  1. Perform the same steps as for CBL_DEBUGBREAK or CBL_DEBUG_START calls.
  2. Set the debug_on_error run-time tunable. See the section Run-time Tunables for instructions on how to do this.
Parent topic: Starting the Debugger Automatically
Related concepts
Features Added in Enterprise Developer 2.1
Compiled File Types
Delegates and Events
IBM External Call Interface (ECI)
Getting Started
Related reference
debug_on_error
Related information
Run-time Tunables


Debugging Windows Services

To debug a Windows service you must be logged on to the console of the computer running the service.

You can debug the service either using library routines or using JIT debugging.

Using Library Routines

If you are using an Eclipse project to build the Windows Service:

  1. Start Eclipse as an administrator.
  2. Add a call to CBL_DEBUGBREAK or CBL_DEBUG_START in the application.
  3. Create a COBOL Wait for Application Attachment debug configuration for your project.
  4. Start a COBOL Wait for Application Attachment debug session.
  5. When CBL_DEBUGBREAK or CBL_DEBUG_START is executed, Eclipse starts debugging the application.

    If you use CBL_DEBUG_START you can then use CBL_DEBUG_STOP to detach the debugger from the application, which resumes running without the debugging features.

If you do not have the project that builds the Windows Service, you need the Service's .idy files, and the Service must include calls to CBL_DEBUGBREAK or CBL_DEBUG_START:

  1. Start Eclipse as an administrator.
  2. Create a COBOL Wait for Application Attachment debug configuration.
  3. On the Debug Symbols tab of the configuration, click Add, select File System Directory and then click OK.
  4. Click Browse and navigate to and select the directory on your machine that includes the application’s .idy files, then click OK.
  5. Click Debug in the Debug Configurations dialog box.

    This starts a debugging session and the COBOL Debugger is waiting for an attachment.

  6. Execute your Windows Service.
  7. When CBL_DEBUGBREAK or CBL_DEBUG_START is executed, Eclipse starts debugging the application.

    If you use CBL_DEBUG_START, you can then use CBL_DEBUG_STOP to detach the debugger from the application, which resumes running without the debugging features.

Using JIT Debugging

  1. Enable Just-in-time debugging from Windows > Preferences > Micro Focus > COBOL > Debug.
  2. Add a call to CBL_DEBUGBREAK in the application.

    When the CBL_DEBUGBREAK is executed, Eclipse is launched and starts debugging the application.

Parent topic: Debugging Scenarios


Debugging Using a Core Dump

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.

Core dump debugging is useful when you have a failing application in a production environment, and you don't have the COBOL development system installed. As long as you have access to the application's source files elsewhere, you can produce a core debug file and utilize it.

To accurately debug using a core dump file, in your development environment, you must use the original source and .idy files used to create the executable in question, or failing that, you must ensure that the sources are in the same state (directive settings, optimization, etc..) as they were during the initial build. Also, as this process will most likely result in you moving from a production environment on one machine, to a development environment on another, any supporting files used by the application (shared libraries, shared objects, third-party libraries, etc…) must be installed along the same path in both environments.

If you do not have the required .idy file, you are given the name of the source file or program where the error occurred.

  • Preparing for a core dump
  • To create a core dump
  • To debug a core dump
Parent topic: Debugging Scenarios


Preparing for a core dump

Note: This topic is only applicable to Linux-based platforms.

Security enhancements on Linux-based platforms may prevent a core dump from being generated when you are expecting one. If you are using the core_on_error=1, core_on_error=2, or signal_regime tunables, you need to perform the following steps to override the security, and then run the application from which you require the core dump. (If you are using core_on_error=3, a core dump file will always be created, regardless of this security enhancement; follow the details in To create a core dump instead.)

Note: The following commands must be run with root privileges.
  1. Disable any size limitations that could stop the core dump file from being created in its entirety:
    ulimit -c unlimited
  2. Specify the format and location in which the core dump is to be created - to create the core dump file in the format core.process-id, in the same directory as your application:
    echo "core.%p"> /proc/sys/kernel/core_pattern
    Note: This is only set for the current session; to ensure the format and location persists after a reboot, add the following line to your /etc/sysctl.conf configuration file:
    kernel.core_pattern=core.%p
  3. Disable the AppArmor application (SUSE platforms), or Automatic Bug Reporting Tool (Red Hat platforms) that is preventing the generation of a core dump file:

    SUSE:

    rcapparmor stop

    Red Hat:

    chkconfig abrt off
  4. Ensure that the core dump contains information resulting from processes that were granted permission via setuid and setgid:
    sysctl -w kernel.suid_dumpable=2
    Note: This permission override is only set for the current session; to ensure it persists after a reboot, add the following line to your /etc/sysctl.conf configuration file:
    kernel.suid_dumpable=2
  5. Run the application for which you are expecting a core dump file.

    When the run time system receives an unhandled signal, a core dump file in created in the same directory as the application.

Parent topic: Debugging Using a Core Dump
Related reference
To create a core dump
core_on_error


To create a core dump

Note: (applies to Windows environments only)
  • You cannot enable both Just-In-Time Debugging and Core Dump concurrently.
  • To debug a 64-bit core dump you must first ensure the project is being built for 64-bit, by opening the Project Properties and selecting 64-bit.
  • To create a core dump for an application running under IIS, the application must be run in the same user account as that being used when enabling the core dump feature. For example, a core dump will not be produced for a CGI or ISAPI application running under the default anonymous logon account.
  1. Create a run-time tunables file.
  2. Include in the file an entry for the core_on_error tunable. By default, when a core dump occurs it is saved with the name cblcore, but you can change this by also including the core_filename tunable. For example:
    set core_on_error=3
set core_filename="coredumptest.%p%t_%d"
    core_on_error parameters
    0 | The run-time system never produces a core file on any signal (UNIX), or exception (Windows) 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 (UNIX), or exception (Windows) 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.; for example, a run-time system error COBRT114, and so on.
    Warning: (UNIX platforms only) 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: (UNIX platforms only) 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.
    129 | Same as core_on_error=1, except no message box is displayed after the core file is created.
    130 | Same as core_on_error=2, except no message box is displayed after the core file is created.
    131 | Same as core_on_error=3, except no message box is displayed after the core file is created.
    core_filename parameters
    Important: You can only use this tunable when core_on_error is set to 3.
    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
  3. Add the COBCONFIG_ (Windows) or COBCONFIG (UNIX) environment variable in your Eclipse project, and set it to the location of the tunables file. Do this by opening your project's Properties dialog box, selecting Micro Focus > Run-time Configuration > Environment Variables, and clicking Add.
Parent topic: Debugging Using a Core Dump


To debug a core dump

Note:
  • You cannot enable both Just-In-Time Debugging and Core Dump concurrently.
  • To debug a 64-bit core dump file with a project, first ensure that your source code is built for 64-bit. In the project's properties, click Micro Focus > Build Configuration > COBOL and click 64 bit.
  • (Windows)To create a core dump for an application running under IIS, the application must be run in the same user account as that being used when enabling the core dump feature. For example, a core dump will not be produced for a CGI or ISAPI application running under the default anonymous logon account.
  1. Click Run > Debug Configurations.
  2. Click COBOL Core Dump.
  3. Select the configuration you want or enter a name for a new configuration.
  4. On the General tab, enter the following information:
    COBOL Project
    The project that will be used while debugging.

    You can debug a core dump file without a project. You need to specify the location of the debug symbols file (.idy) on the other tabs of the debug configuration.

    Core Dump File
    Enter the location of where a core dump is stored. If you only specify the directory, and no core dump filename, Eclipse will prompt you for the filename when the debugger starts. The filename is cblcore by default, but you can change this using the run-time tunable core_filename.
    Executables Location
    Identify a working directory. You can set this automatically to whichever directory you chose to store the core dump file.
  5. On the Source tab, ensure that the location of your source files is defined.
  6. On the Debug Symbols tab, specify the location of the debug symbols (.idy) files.
  7. Click Debug. When the core dump file has been loaded, the Debug perspective is displayed, enabling you to see the state of the application at the point the core dump was created. The statement that was being executed is highlighted in an editor and the call stack is displayed in the Debug view. Execution functions such as the step and resume functions are disabled as the application is not actually running.
Parent topic: Debugging Using a Core Dump


Debugging Using a Live Recording

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 debugger 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 your program runs, the recorder captures everything that influences the running of the program, 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 create a live recording
  • To debug a live recording
Parent topic: Debugging Scenarios
Related concepts
COBOL Live Recording
Reverse Debug and Live Recording


To create a live recording

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.

Note: Windows users: to create a live recording file, you must connect to Micro Focus Enterprise Developer UNIX Components running on one of the supported platforms listed above.
  1. In the Eclipse IDE, click Run > Run Configurations.

    The Run Configurations dialog box appears.

  2. In the list of configuration types, double-click COBOL Application.
  3. In the right-hand pane, in the Name field, type a name for your run configuration.
  4. On the General tab, supply the following:
    COBOL Project
    The project that contains the program you want to run.
    Connection Properties
    If your project is located on a Micro Focus Enterprise Developer UNIX Components, specify the connection details for the remote project, and (if applicable) the X Server display details in order to run the program.
    Main Program
    If applicable, ensure that Program is part of project build configuration is checked, and that the name of the build configuration appears in the corresponding field: it should contain your project's output path and main program to be run.
  5. On the Environment tab, define the COB_LIVE_RECORD environment variable:
    1. Click Add.
    2. In the Variable field, type COB_LIVE_RECORD.
    3. In the Value field, type the full path to (optional - default is your Eclipse workspace) and filename prefix for the output file you want the Live Recorder to create when the program runs. For example:
      /home/user/workspace/myrecordings/tictac
      Tip: Optionally, you can also add the COB_LIVE_RECORD_SIZE variable, giving an integer value to represent the amount of memory (in MB) allocated to recording events that will be written to the output file. If this value (or if the variable is not set, the default of 268MB) is exceeded, the buffer is cycled during recording so that the oldest events are removed to make space for the most recent events; therefore, when debugging such a recording file, debugging won't necessarily start at the beginning of the program.
    4. Click OK.
  6. Run the application:
    1. On the Run Configurations dialog box, click Run.
    2. Let the application run until it terminates normally: the live recording file is not created until the application ends.
  7. From a terminal window or file browser, go to the directory specified by the COB_LIVE_RECORD environment variable, and confirm that the output file has been created.

    The output filename takes the following form:

    filePrefix.nnnn.mfr

    Where filePrefix is the filename prefix you specified for the COB_LIVE_RECORD environment variable and nnnn is a generated process ID.

Parent topic: Debugging Using a Live Recording
Related concepts
Reverse Debug and Live Recording
Debugging Using a Live Recording
Related tasks
To debug a live recording


To debug a live recording

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.

Note: Windows users: to debug a live recording file, you must connect to Micro Focus Enterprise Developer UNIX Components running on one of the supported platforms listed above.
  1. Create a live recording. See To create a live recording for details.
    Note: You can only debug a live recording on a machine using the same operating system as the one that it was created on.
  2. In the Eclipse IDE, click Run > Debug Configurations.
  3. Double-click COBOL Live Recording.
  4. In the Name field at the top of the right pane on the Debug Configurations dialog box, type a name for your debug configuration.
  5. On the General tab, supply the following:
    COBOL Project
    The project to use while debugging.
    Live Recording File
    Click Browse for file to locate and select a live recording output file, or click Browse for folder to locate the folder in which you store your recordings (if you select this option, you will be prompted for an output file when the configuration is launched).
    Executables Location
    Do one of the following:
    • If your application executable files are in the same directory as your live recording file, click Live recording file location.
    • If your application executable files are in a different location than your live recording file, click Other location; then either click Browse to select a directory or type the full path into the field.
      Tip: The Enterprise Developer compiler writes the application executable files to the Output Path specified in your project properties.
    Debug Options
    If your application is 64-bit, check Application is 64-bit.
  6. On the Source tab, ensure that the location of the application's source files (COBOL program files and copybooks) is defined; if it is not already listed:
    1. Click Add.
    2. Select File System Directory, and click OK.
    3. Click Browse, navigate to the location of the files, and then click OK.
      Note: The source files must be in the same state that they were in when used to create the application executable you are about to debug.
  7. On the Debug Symbols tab, ensure that the location of your debug symbol (.idy) files is defined; if it is not already listed:
    1. Click Add.
    2. Select Project, and click OK.
    3. Check the box next to the appropriate project name, and click OK.
  8. Click Debug.
  9. If you only selected a folder in the Live Recording File field, select a .mfr file from the folder, and click OK.

    After the live recording file has been loaded, the Debug perspective is displayed with the application at its starting point. Use the forwards and reverse step options to move through the execution of the application. To indicate that you are stepping through a recording (and not a live application), the debug thread that is displayed in the Debug pane, appends in replay mode to the thread title

Parent topic: Debugging Using a Live Recording
Related concepts
Reverse Debug and Live Recording
Debugging Using a Live Recording
Related tasks
To create a live recording


Debugging Using a Remote Machine

Using debug configurations for remote projects

You use a local Enterprise Developer installation to develop remote projects on a remote UNIX machine that has Micro Focus Enterprise Developer UNIX Components installed.

In order to debug a remote project, you use the same types of debug configuration as you would use for local projects. In the configuration, you need to specify the connection properties such as the machine name and the port number.

It is not necessary to start the cobdebugremote (or cobdebugremote64 for a 64-bit process) or identify a port for it to listen on. You just need to select the remote project in the debug configuration.

Performance considerations

When debugging a remote program, the performance of the network, specifically the latency between the local and remote machines, will have an effect on the responsiveness of Eclipse. Whenever Eclipse has to show the new execution position, a number of messages are sent from the remote machine, over the network, to get the required information. The effect of this is that it can take a few seconds after a Step command is issued before Eclipse has updated the screen and is ready for the next command.

You can mitigate this delay by closing any unnecessary debug views. For instance, by closing the Expressions view and the Variables view, the number of messages that are sent is reduced, which allows Eclipse to update quicker.

See the rest of the topics in this section for information on how to debug applications in remote machine scenarios.

  • Remote debug of projects developed locally
  • Projects developed on a remote UNIX machine
Parent topic: Debugging Scenarios
Related information
To create a connection to a remote UNIX host running behind a firewall


Remote debug of projects developed locally

Enterprise Developer enables you to debug local projects while running them on a remote machine, or while your local project interacts with applications running on a remote machine.

The following must be configured:

  • The remote machine can be a Windows or UNIX environment, with either Enterprise Developer or Enterprise Server installed. The two systems must be networked using TCP/IP.
  • The remote machine must have access to the debug symbol (.idy) files in your project, which are normally in the output directory of your project (a location specified in the build configuration).

    To enable access to the debug symbol files for the remote machine:

    • Set up the project subdirectory on the local machine as a network share with the remote machine.
    • Alternatively, you can copy or FTP the .idy files to a directory on the remote machine. You then need to configure the directory paths that are used to search for the application's .idy files.

Remote debugging of local projects is handled by the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process), located in $COBDIR/bin of the remote machine.

Note: If you intend to remotely debug callable shared objects (.so), you must set the COBIDY environment variable to the location of the .idy file before you start cobdebugremote32 or cobdebugremote64.
You must start the process before communication can be established. This process terminates automatically when you terminate the debug session either by disconnecting from or stopping the debugged application. You can use the following options:
no options
Starts the process and opens a random port for remote connections. The port number is displayed in the console.
machine=name
Specify the machine that the process is running on. Only valid with the stop option.
port
port=nnnnn
Specify the port to use to listen for connection requests.
port=nnnnn-yyyyy
Specify the range of ports to use. If port nnnnn is in use, the next port is tried until a free port is found. If no free ports are found in the range, the utility returns an error.
Note: You must enter the same number you set as the port option in the cobdebugremote port field of your debug configuration.
repeat
After the debug session has been completed, start listening for another connection. If no option is specified, the process exits after the debug session has completed.
stop
Causes the process that is listening on the port to exit. Must be used with the port option. This is only valid when the process is waiting for a connection.
Tip: You need to start a cobdebugremote process for every debug session therefore it is recommended to use the repeat option. This ensures the process listens for another connection after the debug session has completed.
Parent topic: Debugging Using a Remote Machine


Projects developed on a remote UNIX machine

You use a COBOL Application debug configuration to debug projects developed on a remote UNIX machine. Before you can debug the remote application, you need to have an X window implementation installed and running, so that the output of a remote application running on a UNIX machine can be viewed on your local machine. You do not need X window for other debug configuration types.

Windows:

Micro Focus ViewNow X is provided as part of Enterprise Developer. See Installing X Windows on Windows in the Installation section. Find the ViewNow X documentation on the Micro Focus SupportLine dropdown menu.

UNIX:
Ensure the local X11 server can receive connections from the remote machine. You can do this using the xhost + command or by enabling SSH port forwarding. Alternatively, enable TCP/IP connections for X11 by setting a value in a configuration file in a manner appropriate to your operating system. For example:
  • Red Hat: run the gdmsetup utility and deselect Deny TCP connections to Xserver in the Security tab (this configures DisallowTCP=false in /etc/gdm/custom.conf)
  • SUSE: set DISPLAYMANAGER_XSERVER_TCP_PORT_6000_OPEN="yes" in /etc/sysconfig/displaymanager

Specify the details about the display that the X11 server tries to contact in the IDE preferences as follows:

  1. Click Window > Preferences > Micro Focus > Debug.
  2. Type the display details in the Default X Server (DISPLAY) field.

    The default Default X Server (DISPLAY) value is clientMachineName:0.0. This configuration applies to both remote COBOL and PL/I projects.

Remote UNIX machines running behind a firewall

If the remote machine is running behind a firewall but is accessible via SSH, you need to use a proxy server to handle traffic to the remote machine. Enterprise Developer supports the SOCKS5 internet protocol. This enables you to route network traffic through SSH to the remote machine. To use SOCKS with a proxy server perform the following steps:

  1. Click Window > Preferences > General > Network Connections.
  2. In the Active Provider list, select Manual.
  3. In the Proxy entries table, click the SOCKS row.
  4. Click Edit.

    This opens the Edit Proxy Entry dialog box for the SOCKS schema.

  5. In the Host field, type the host_name where your proxy server is running.
  6. In the Port field, type the port_number used by your chosen proxy client.

    If your proxy server is configured to request authentication you need to specify the details:

    1. Check Requires Authentication.
    2. Type the username in the User field.
    3. Type the password in the Password field.
  7. Click OK.

If you are going to use the COBOL Application debug configuration you also need to use SSH port forwarding to route X Server display to the local machine. This means you need to specify the remote machine port (rather than the local machine port) when specifying the display in the preferences:

  1. Click Window > Preferences > Micro Focus > Debug.
  2. Type the display details in the Default X Server (DISPLAY) field - for example localhost:10.0.

    The value following localhost comes from /etc/ssh/sshd_config - X11DisplayOffset and is incremented for each additional user.

  3. Click OK.

See To create a connection to a remote UNIX host running behind a firewall for details of how to use SOCKS with PuTTY as the proxy server.

Parent topic: Debugging Using a Remote Machine


Debugging CICS Channels and Containers

As you debug a CICS application in Enterprise Developer, you can view the contents of channels and containers via the CICS Channels view, and edit the contents of writable containers from the Memory view.

You can display the CICS Channels view by clicking Window > Show View > Others > CICS Channels.

  • CICS Channels View
    The CICS Channels view shows an expandable list of channels and the containers they contain, and also provides a view of the data stored in each container.
  • To modify data in a container
Parent topic: Debugging Scenarios


CICS Channels View

The CICS Channels view shows an expandable list of channels and the containers they contain, and also provides a view of the data stored in each container.

You can display the CICS Channels view by clicking Window > Show View > Others > CICS Channels.

Channels and Containers list
An expandable list of channels used up to the point of execution, and the containers they contain. Select a container to view its contents in the box below the list.
Tabs
Eclipse adds a tab to the CICS Channels view for each running debug session.
Channels name filter
Type a character string to filter the list to those in the currently selected container that contain the string in their container name.
Containers name filter
Type a string to filter the list to show just the containers in the currently selected container that contain the string in their container name.
Data view box
Located below the Channels and Containers list, this box shows a view of the data contained in a container. You cannot edit data from this box. See To modify data in a container for more information.
ASCII
Select this to show container data in ASCII.
EBCDIC
Select this to show container data in EBCDIC.
Parent topic: Debugging CICS Channels and Containers


To modify data in a container

Note: This functionality is available only when debugging a CICS COBOL application that uses channels and containers.
  1. From the CICS Channels view, right-click a container that is not marked as read-only; then select Open in Memory View.
  2. Edit the data as required. Changes you make are reflected in the CICS Channels view.
Note: From the New Renderings tab, you can change the rendered encoding of data that appears in the Memory view.
Important: Be sure not to enter data beyond the end of your data structure. Doing so could cause unpredictable results.
Parent topic: Debugging CICS Channels and Containers
Related concepts
CICS Channels View


Debugging Mixed Language Applications

Java class calling a COBOL program

In order to step though a Java class and any COBOL program it calls, you first need to start debugging the COBOL program with a Wait for Application Attachment debug configuration, and then start debugging the calling Java class with a Java Application debug configuration. Note that there are several ways to create debug configurations and start debugging - the following procedure is just one example.

Before you start, make sure both programs are compiled for debugging.

  1. Select the Java project in COBOL Explorer.
  2. Click Run > Debug Configurations and click Java Application.
  3. Click the New button.
  4. On the Main tab, set Main class to the class containing Main.
  5. To make sure the debugger is invoked when the COBOL program is called, do one of the following.
    • Set the variables in the Environment tab:
      • Set COBPATH to the .bin directory of the COBOL project
      • Set COBSW to "+A"
    • Use CBL_DEBUGBREAK or CBL_DEBUG_START statements in the COBOL program
  6. Select the COBOL project.
  7. Click Run > Debug Configurations and click Wait for Application Attachment.
  8. Click Debug. This puts the program in a waiting state; debugging won't start for this program until it is called by the Java class. If you are prompted to switch to the Debug view, click No.
  9. Select the Java project and click Run > Debug as > Java application to start debugging.

Eclipse then opens the Debug perspective, so you can step through the Java code as it executes, and see and change the values of data items. When the class calls the COBOL program, the Debug perspective then switches to the COBOL source so you can step through and track the COBOL code too.

Parent topic: Debugging Scenarios


Debugging Mainframe Applications and Services on Enterprise Server

To debug applications and services you need to run them on an enterprise server that has the Dynamic Debugging option set.

This option enables you to debug services from within your COBOL development environment, while the services are running on a local or remote enterprise server. This requires no changes to your program code.

When you debug a project with Dynamic Debugging enabled, you can specify the items to debug. For example, you can specify that you want to debug instances of a given web service that are started from a particular client machine.

Before you can debug services, you need to prepare. You need to configure the enterprise server, deploy your service and make sure that both the enterprise server and your development environment are set up appropriately.

  • How Debugging on Enterprise Server Works
  • To prepare for debugging on Enterprise Server
  • To debug on Enterprise Server
  • To debug on a remote Enterprise Server
  • Debugging using a temporary enterprise server
  • Error Messages for Web Services
Parent topic: Debugging Scenarios


How Debugging on Enterprise Server Works

When you start a debug session for a project that uses an enterprise server configured for Dynamic Debugging, you can tell the server 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 your debug session. You can then step through the application in the normal way.

Your match criteria can be specific or general. However, we recommend that you are 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) is attached to the instance.

For example:

  1. USERA specifies Web Services started from a particular client IP address
  2. USERB specifies Web Services started from the same client IP address, but also specifies the service name
  3. When a matching web service is started, the enterprise server attaches USERB's debug session to the service.

When you specify the match criteria, you are warned if they are similar to those provided by another user. If you specify identical match criteria to those provided by another user, you receive an error message and the criteria are rejected.

Note: You can view the active dynamic debug sessions and the associated debug criteria on your enterprise server by using the Dyn-Dbg button in ESMAC. You can also use the screen to remove debug criteria that are no longer required.
Parent topic: Debugging Mainframe Applications and Services on Enterprise Server


To prepare for debugging on Enterprise Server

  1. Compile your project for debugging.
  2. Open the Enterprise Server Administration Web page. To do this:
    1. In Server Explorer, right-click the host server.
    2. Select Open Administration Page from the context menu.
  3. Enable dynamic debugging for the enterprise server that you want to use for debugging. To do this:
    1. In the table of servers on the Home page of Enterprise Server Administration, find the row for the server that you want to configure, and click Edit in the left hand column.
    2. In the Server > Properties > General section, select Allow Dynamic Debugging.
    3. Click OK to confirm your changes.
    Important: You must restart the server for the changes to take effect.
  4. If your program is a service (Web Service or EJB), create a client program to submit requests for that service.
  5. Associate the project with the enterprise server:
    1. Ensure that your project is open.
    2. In Server Explorer, right-click the enterprise server with which to associate your project.
    3. Click Associate with project > your project .
Parent topic: Debugging Mainframe Applications and Services on Enterprise Server


To debug on Enterprise Server

  1. Prepare for debugging, see To prepare for debugging on Enterprise Server.
  2. Click Run > Debug Configurations.
  3. Create a new COBOL Enterprise Server configuration.
  4. If you are debugging a Web Service, on the General tab and in the Debugging type section, on the Web Service tab enter the IP address of the client that makes the service request.
    • Alternatively, enter the fully qualified name of the service. This is formed by taking the name of the service and appending a pound or hash character (#) 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 debug is Read, the fully qualified service name is: http://tempuri.org/wmapserv#Read.
    • To prevent the debugger from being suspended for all transactions except breakpoints, optionally check Only stop on breakpoints under Debug Options on the General tab.
  5. Click OK .
  6. Start the Web service or the application you want to debug on the enterprise server region. The way you do this depends on the type of application, for example:
    • For a Web Service, run the client program and enter some input to trigger the service. It is not possible to run the client module from within your debug session. However, if the client program is also part of a different project than the one that you are debugging, you can start another debug session, open the client project and run the client module.
    • For a CICS application, start a TN3270 terminal session and run your transaction.

      If you have Micro Focus Rumba installed, you can run the application in a mainframe session of Rumba Desktop, or in the Rumba Mainframe Display view within the IDE.

  7. Step through the application in the usual manner. When the debugger reaches the exit program statement and no line is highlighted, the service or the application exits. The debugger now waits for the next matching service or application to start.
  8. When you have finished debugging, click Run > Terminate . If specified in your Enterprise Server preferences, when closing the project it will stop and delete the enterprise server used to debug the application.
Parent topic: Debugging Mainframe Applications and Services on Enterprise Server


To debug on a remote Enterprise Server

  1. Before you start your COBOL development system, ensure that the local and remote systems are networked using TCP/IP. See your Configuring CCI Guide. The two systems must be connected using the same CCITCP2 or MFDS process. A simple way to do this is to set the CCITCP2 variable on the local machine running the IDE to point to the remote machine. This environment variable must be set so that the devenv process can pick it up.
    • You can set the variable from a command prompt:
      set
CCITCP2=machine-with-CCI
      where machine-with-CCI can be the machine name or its IP address. Then, you need to execute devenv to start the IDE from the same command prompt.
    • Alternatively, you can set CCITCP2 globally for your machine: open Control Panel, and click System > Advanced system settings > Environment Variables.
  2. If you have a firewall on the remote machine, you need to add some inbound rules. First, ensure that port 86 is opened for TCP and UDP protocols. Second, allow access through the firewall for the following programs: cobremotedaemon and cobdebugengineproxy (cobdebugengineproxy64 for 64-bit environments). These programs reside in the <install-dir>\base\bin directory.
Parent topic: Debugging Mainframe Applications and Services on Enterprise Server


Debugging using a temporary enterprise server

You can debug an application that needs an enterprise server to run even without configuring and associating a server beforehand.

If your project is not associated with any of the existing servers, when you start debugging, the IDE offers to create a temporary server configured for your project type and use that to run the application. The server is deleted when you close the project or the IDE.

To always use a temporary server without a prompt, go to Window > Preferences > Micro Focus > Enterprise Server, and click Always for Automatically create temporary server.

To debug using a temporary enterprise server:

  1. In the IDE, when your project is not associated with any enterprise server, start debugging.

    If you have not configured the IDE to create a temporary server automatically, you receive a message that a temporary server will be created. Otherwise, the IDE creates the temporary server without prompting you to confirm.

  2. Click OK.

    This creates a temporary server which is configured for your project type of project and searches for the project output files in the output directory specified in the project's properties. This also automatically associates the server with your project and starts it.

  3. Debug your application.

    Closing the project or the IDE deletes the temporary server.

Parent topic: Debugging Mainframe Applications and Services on Enterprise Server


Error Messages for Web Services

You may find, when you are debugging a Web service, that the client returns error 0015. This is a time-out, and is caused by the service not returning to the client in the expected time, because you were debugging it. If you find this a problem, you can change the timeout interval by editing the Micro Focus Common Client (MFCC) configuration file, which by default is mf-client.dat, located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 (Windows) or $COBDIR/etc (UNIX) . You can create your own configuration file of any name or location, but you must identify it using the MFC_CONFIG environment variable.

Open the file and insert:

[defaults]
timeout=nn

where nn is the desired timeout period in seconds (at run time the figure is rounded up to a multiple of 5).

Parent topic: Debugging Mainframe Applications and Services 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 Scenarios


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

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:
    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 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
Related tasks
To debug a live recording


Debugging with Character Animator

Note: This topic applies to UNIX environments (remote development) only.

Character Animator was provided as part of previous versions of Micro Focus COBOL development systems as the debugger for you to to use during the various stages of the application development cycle.

We do not recommend the use of Animator in Enterprise Developer because the Eclipse IDE provides an excellent environment in which to debug your applications. In certain circumstances, however, Animator can still provide useful functionality (such as the debugging of deployed applications), so if you are familiar with using Animator you might want to continue to use it in such circumstances.

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


Overview of Character Animator Functions

Note: This topic applies to UNIX environments (remote development) only.

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: Debugging with Character Animator


Working With Character Animator

  • The Character Animator Screen
  • Menus
  • Functions
  • Run-time System Error Messages
Parent topic: Debugging with 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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

This function displays the Breakpoints menu.

Parent topic: Function Descriptions


Cancel All Breakpoints

Note: This topic applies to UNIX environments (remote development) only.

Resets all active breakpoints.

Parent topic: Function Descriptions


Cancel Program Break

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Clears the current input field.

Parent topic: Function Descriptions


Cursor-name Locate

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Displays the Environment menu.

Parent topic: Function Descriptions


Escape

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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.

Parent topic: Function Descriptions


Hex

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Enables you to display the content of a queried data item as it changes during program execution.

Parent topic: Function Descriptions


Monitor-off

Note: This topic applies to UNIX environments (remote development) only.

Switches off the monitor display of a queried data item.

Parent topic: Function Descriptions


Next Reset

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Reorganizes the monitors on your screen to their default positions.

Parent topic: Function Descriptions


Parent Data

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Displays the Perform-level menu.

Parent topic: Function Descriptions


Perform-view

Note: This topic applies to UNIX environments (remote development) only.

Views and changes context to a different level in the CALL/PERFORM stack.

Parent topic: Function Descriptions


Query

Note: This topic applies to UNIX environments (remote development) only.

Displays the Query menu.

Parent topic: Function Descriptions


Query Data-name

Note: This topic applies to UNIX environments (remote development) only.

Displays the Query Data-name menu.

Parent topic: Function Descriptions


Quit-perform

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Refreshes the display of all source text and the monitored variables.

Parent topic: Function Descriptions


Reset-execution

Note: This topic applies to UNIX environments (remote development) only.

Displays the Reset-execution menu.

Parent topic: Function Descriptions


Same Level

Note: This topic applies to UNIX environments (remote development) only.

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)

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Executes the current statement and places the cursor on the next executable statement, which it also highlights.

Parent topic: Function Descriptions


Step Perform

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

Cancels a breakpoint at the current cursor position.

Parent topic: Function Descriptions


Up Table

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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

Note: This topic applies to UNIX environments (remote development) only.

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


Directives for Character Animator

  • Directive Descriptions
  • Using COBANIMOPT
Parent topic: Debugging with 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.
  • PROGBPALLENTRY
    Determines if program breakpoints are triggered only when the program is entered, or are also triggered when execution returns back from a called program.
  • 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: Directives for Character Animator


COBAIF

Specifies whether to load and save Character Animator session information.

Syntax:

Note: This topic applies to UNIX environments (remote development) only.
>>-.----.----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:

Note: This topic applies to UNIX environments (remote development) only.
>>-.---.----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:

Note: This topic applies to UNIX environments (remote development) only.
>>--.----.---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:

Note: This topic applies to UNIX environments (remote development) only.
>>--.----.---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


PROGBPALLENTRY

Determines if program breakpoints are triggered only when the program is entered, or are also triggered when execution returns back from a called program.

Syntax:

Note: This topic applies to UNIX environments (remote development) only.
>>--.----.---PROGBPALLENTRY------------><
    +-NO-+

Parameters:

None

Properties:

Default:
NOPROGBPALLENTRY
Parent topic: Directive Descriptions


RESEQ

Specifies that COBOL line sequence numbers should appear on the Character Animator's source display.

Syntax:

Note: This topic applies to UNIX environments (remote development) only.
>>--.----.---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:

Note: This topic applies to UNIX environments (remote development) only.
>>--.----.---ZEROSEQ------------------><
    +-NO-+

Parameters:

None

Properties:

Default:
NOZEROSEQ

Comments:

NOZEROSEQ suppresses leading zeros.

Parent topic: Directive Descriptions


Using COBANIMOPT

Note: This topic applies to UNIX environments (remote development) only.

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: Directives for Character Animator


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.
Parent topic: Debugging with Character Animator
Related reference
Environment Variables Alpha list
CBL DEBUG START


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 Enterprise Developer, 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
Parent topic: Debugging with 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

  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), as opposed to a CICS or JCL application, 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 JCL | WS | J2EE, depending on the type of application or service you want to debug. | Mandatory | All
    jobname | Specify the name of the job you want to debug. | Optional | JCL only
    stepname | Specify the JCL step that you want to debug. | Optional | JCL only
    jobnumber | Specify the number of a job in the help queue that you want to debug | Optional | JCL only
    program | Specify the name of the JCL program that you want to debug | Optional | JCL only
    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


Code Refactoring

Code refactoring is a process and a set of techniques for improving the internal structure of your code without changing its behavior. Refactoring deals with making the code easier to read, work with, maintain and extend. It can help to improve the code's efficiency and, potentially, resolve some issues.

The refactoring techniques involve applying different cumulative small changes (mini-refactorings) to the code. Individually, each mini-refactoring is small enough to reduce the risk of introducing any errors, but collectively, refactoring can significantly enhance your code.

Enterprise Developer provides support for refactoring of COBOL and PL/I code using the following techniques:

  • Renaming COBOL elements to improve their readability or make their purpose clearer. You can rename variables and identifiers as well as section and paragraph names. You can choose to change all or selected occurrences of a name and the changes will apply to the names in the files from the current workspace
  • Moving selected lines of code into a copybook or a PL/I include file to help with code reuse.
  • Rename Refactoring
  • Rename Refactoring JVM COBOL
  • Extracting COBOL code to a copybook
  • Extracting PL/I code to an include file
Parent topic: Developing Applications in the IDE


Rename Refactoring

Enterprise Developer enables you to rename all or selected occurrences in the workspace of variable, section and paragraph names (in native COBOL), of identifiers (in managed COBOL), or of COBOL types that are referenced in Java code and vice versa.

Preferences for rename refactoring

Eclipse supports renaming directly in the editor which renames all occurrences of the identifier, or renaming with a Rename dialog box which enables you to preview and approve the changes before they are applied.

To specify whether you want to rename with or without the Rename dialog box, click Window > Preferences > Micro Focus > COBOL > Editor and either check or uncheck Rename in editor without dialog (enabled by default).

Renaming identifiers in your code

To rename an identifier:

  1. Right-click the item you want to rename in the editor, and click Refactor > Rename.

    Alternatively, click Refactor > Rename from the main menu or right-click the identifier in the Outline or the Program Outline views and click Refactor > Rename.

    If the IDE is configured for quick rename:

    • The IDE prompts you to enter a new name in the editor.

    • Enter a new name and press Enter to rename all references of the name.

      Optionally, use the commands from the drop-down menu of the rename tooltip to invoke the Rename dialog and preview the suggested changes before they are applied.

    If the IDE is configured to rename with the Rename dialog box:

    1. Specify a new name in the New name field.
    2. Ensure that Update references is checked.
    3. Click Preview to view and approve the changes:

      Ensure the changes are applied as required and click OK.

To revert your changes, click Edit > Undo Rename COBOL Element.

Restrictions

The following restrictions apply to rename refactoring:

  • It is not possible to rename identifiers in a copybook which is referenced using the COBCPY environment variable but is not located in the workspace.
  • It is not possible to rename identifiers in copybooks referenced using a COPY... REPLACING statement.
  • It is not possible to rename data items in JCL or BMS files.
  • It is not possible to rename typedef members.
  • It is not possible to rename identifiers in any resources that are outside the current workspace.
  • It is not possible to rename identifiers defined using the AS phrase.
  • It is not possible to rename a program name or an entry-point.
  • Rename using a COBOL reserved word is not supported. The IDE does not issue a warning if you use a reserved word to rename an identifier and will rename the instances of the identifier. Trying to build your application, however, will fail.

The following restrictions apply to native COBOL only:

  • It is not possible to rename copybooks from the editor. You can rename copybooks from COBOL Explorer. This, however, does not change any of the references to the copybooks in the code.
Parent topic: Code Refactoring


Rename Refactoring JVM COBOL

You can rename a package and optionally any sub packages in a JVM COBOL project. This results in the class's namespace being renamed along with the class's folder structure to match the new package name.

To rename a package in the COBOL Explorer

Note: You need to be in the package presentation view.
  1. Right-click on the package to be renamed, and then click Refactor > Rename.

    This opens the Rename COBOL JVM Package dialog box.

  2. In the New name field, type your new package name.
    Note: By default, the Update references option is checked.
    • If you want to rename subpackages as well, check Rename subpackages.
  3. Click OK.

    This opens the Rename COBOL JVM Package dialog box. At this point, summary information on problems found and the code affected by the rename is displayed.

  4. Click Continue to apply the change.

To rename a package in the COBOL editor

Note: You do not need to be in the package presentation view.
  1. Highlight the namespace component of the class name or place the cursor within the namespace, and then right-click.
  2. Click Refactor > Rename.

    This opens the Rename COBOL JVM Package dialog box.

  3. In the New name field, type your new package name.
    Note: By default, the Update references option is checked.
    • If you want to rename subpackages as well, check Rename subpackages.
  4. Click OK.

    This opens the Rename COBOL JVM Package dialog box. At this point, summary information on problems found and the code affected by the rename is displayed.

  5. Click Continue to apply the change.
Parent topic: Code Refactoring


Extracting PL/I code to an include file

To help reduce duplication across your PL/I application you can extract a block of PL/I code to an include file. To extract the code, perform the following steps:

  1. In the PL/I editor, highlight the lines that you want to extract to an include file.
  2. Right-click in the PL/I editor, and then click Refactor > Extract to Include File. Alternatively, from the main menu, click Refactor > Extract to Include File.

    This opens the Extract to Include File dialog box where Containing project contains the current project.

  3. In the New file name field, type an include file name with an .inc file extension.
  4. Optionally, click Preview to view the changes to be performed. In the Changes to be performed pane, you are presented with a list of the actions to be taken. By default, all actions are checked. You can uncheck actions to obtain the required results. Clicking on the actions displays the result of the actions in the Original Source and Refactored Source panes.
  5. Click OK.

    By default this extracts the highlighted source code to the specified include file and refactors the original source, leaving an %INCLUDE statement referencing the newly-created include file.

Parent topic: Code Refactoring
Parent topic: Using Eclipse for PL/I development


Running COBOL Applications

  • Configuring the Run-Time Behavior
  • To run a COBOL application on your local machine
  • To run an application on a remote machine
Parent topic: Developing Applications in the IDE
Related concepts
Running a PL/I application


Configuring the Run-Time Behavior

You can ensure that your application is always run in a consistent environment by building a run-time configuration into the application. These settings configure the COBOL run-time environment each time your application is started so that it always behaves as you have specified, regardless of settings used by other COBOL applications.

You can configure the application behavior using:

  • Project > Properties > Micro Focus > Run-time Configuration. These settings apply to the project. They are the defaults and are overridden by any run-time settings in the general run-time configuration (described below)
  • Run > Run Configurations. Like build configurations, you can have multiple run configurations and swap between them. These run-time settings override the project settings.
Parent topic: Running COBOL Applications
Related tasks
To run an application on a remote machine
Related information
To run a COBOL application on your local machine


To run a COBOL application on your local machine

Ensure that your project is highlighted in the COBOL Explorer view.

  1. Click Run > Run Configurations.
  2. Expand the appropriate application type and select the configuration you want to use.
  3. Specify the run-time configuration for the application. For example you can specify such as the search order for called programs, environment variables, and input/output settings.
    If you are running a COBOL JVM application
    Select the Classpath tab and check that your preferred runtime system library is selected under the User Entries option. If not, click Advanced > Add Library and select it.
  4. Click Run.
Important: This run-time configuration overrides any run-time settings you have configured for the project in Project > Properties.
Parent topic: Running COBOL Applications
Related concepts
Configuring the Run-Time Behavior
Related tasks
To run an application on a remote machine


To run an application on a remote machine

To run an application you need to connect to your remote machine using, for example, Telnet. You then change to the directory where the program is located and run your program.

If your application is a dynamically loadable file, use the cobrun command from the command prompt, in the form:
cobrun program

You can also open a remote shell from the Eclipse IDE from which to run an application:

  1. Open the Remote Systems perspective.
  2. Expand the remote connection where you want to open a terminal.
  3. Right click Ssh Terminals and select Launch Terminal. You might need to enter a username and password for the remote server. A Terminal view will open.
  4. At the command line in the Terminal view, change directory to where the program is located and run the program, or for dynamically loadable files enter:
    cobrun program
Parent topic: Running COBOL Applications
Related concepts
Configuring the Run-Time Behavior
Related information
To run a COBOL application on your local machine


Using Eclipse for PL/I development

Enterprise Developer offers PL/I developers most of the functionality available for COBOL programming. Refer to the rest of this document for details and instructions on how to use these development features, and the Known Issues and Restrictions topic for a list of features not currently supported for PL/I.

  • PL/I Perspective and Projects
  • The PL/I Editor
  • Creating a PL/I project
  • Creating Remote PL/I Projects
  • Setting PL/I Project, File and Build Configuration Settings
  • Indicating that a PL/I Include File is a Source File
  • Extracting PL/I code to an include file
  • Compiling and building a PL/I project
  • Linking PL/I programs
  • Debugging PL/I projects
  • Running a PL/I application
Parent topic: Developing Applications in the IDE
Related information
Creating COBOL Projects


PL/I Perspective and Projects

The first step in developing PL/I applications in Eclipse is to create a PL/I project. PL/I projects in Eclipse are like other Eclipse projects. A PL/I project is a representation of the source files (with dependencies) and build commands used to create your application or program. You create a project using a wizard and the resulting project is displayed in the PL/I Explorer view, from where you can open your source files.

When you first start Enterprise Developer, you are presented with Eclipse's Welcome page which contains a few shortcut links for the most common type of applications you might be developing. To continue with developing PL/I applications, click Open PL/I Perspective. Perspectives are an Eclipse concept. They present the views, menus and options relevant to your activity. When you load the PL/I perspective, it shows the PL/I Explorer, the Outline and Console views, among others. The perspective is customizable, so you can choose your own views.

The PL/I perspective is associated with developing PL/I applications and can be opened every time you create or open a PL/I project.

If you need to switch to the PL/I perspective from other perspectives, click Window > Perspective > Open Perspective > Other, click PL/I and then click OK.

You can also develop PL/I applications from the default Team Developer perspective, click Window > Perspective > Open Perspective > Other, click Team Developer (default) and then click OK.

Parent topic: Using Eclipse for PL/I development


The PL/I Editor

To work with files in the PL/I editor, simply double-click the PL/I source file in the PL/I Explorer that you want to edit. You can also right-click the file and choose Open.

You can customize the PL/I editor from the preferences pages in Window > Preferences > Micro Focus > PL/I > Editor. You can configure features such as Smart Edit Mode (wrapping code and indentation), margins, syntax coloring.

The PL/I editor contains all features to aid PL/I coding and editing such as:

Block Selection

Lets you select specific blocks of text in your code. Click the Toggle Block Selection Mode ( Toggle Block Selection) button in the toolbar or press Alt+Shift+A to alternately enable and disable block selection.

When in Block Selection mode, the cursor changes to a crosshairs cursor, letting you select a block of text. Click and drag to select a text block.

Breadcrumb Navigation

Context breadcrumbs are enabled by default. You can use the Toggle Context Breadcrumbs button ( Toggle Context Breadcrumbs) on the toolbar to switch the functionality on and off. The breadcrumbs navigation bar displays at the top of each PL/I editor tab, and lets you quickly view and open programs and include files along the trail of files for the current file. You can also use the breadcrumb navigation for quick context switching between include files.

Code Templates

Code templates are preset snippets of code you can place in your programs. Enterprise Developer provides a number of native PL/I and mainframe PL/I code templates that you can use while writing your code. Press Ctrl + space in the editor to access the code templates using the content assist pop-up.

Available templates display at the bottom of the list. Use the scroll bar in the content assist pop-up to find the template you want in the content assist list. Click once on the desired template name to see the code snippet for the template in a pop-up. Double-click the desired template name to place the template code snippet into your code at the current cursor location.

There is a set of templates for PL/I, and an additional template set for code containing EXEC CICS statements.

You can manage your templates in the Templates Preferences page by clicking Window > Preferences > Micro Focus > PL/I > Editor > Templates. You can create new templates, or edit and delete existing templates, as well as import and export templates as .xml files to share with other users.

Content Assist

Content assist supports PL/I language elements when working in the PL/I editor. Content assist provides editing features to help you write syntactically correct code and to look up available elements. Use content assist to complete words, lookup code, get parameter keywords and aid your code development in other ways.

Press Ctrl + space to get content assistance that is in context with what you are typing in your code. For example, if you are typing a PL/I statement and press Ctrl + space, the list of applicable items appears, with the best match for the statement you are typing highlighted in the content assist pop-up. Any related keywords and templates using the highlighted statement also appear in the pop-up list.

Content assist only offers assistance for the variables and methods that are in scope based on the current cursor position. For variables and methods with ambiguous names, the string inserted is disambiguated.

Preference settings for content assist are not supported.

Contextual Help

Dynamic help in the PL/I Editor provides contextual help for PL/I keywords and various language elements in your code. Highlight the desired language element in your code and press F1 or help in the Help viewer for the PL/I statements as you click on them in the code. To open the Help view, click Help > Show Contextual Help. This opens the Help viewer and displays reference information for the highlighted item.

Error Indicator

The Error indicator actively shows any errors and warnings in your code as you type. Lines containing errors or warnings are indicated with a red x at the beginning of the line. You can hover over the error or warning in the line to see a tool tip that displays additional information.

Extracting PL/I code to an include file

You can extract highlighted lines to an include file by right-click in the editor, and clicking Refactor > Extract to Include File. See Extracting PL/I code to an include file for more information.

Find References

Find references lets you discover all the places in your current program where a selected language element is. For example, place the cursor anywhere within a procedure name and choose Find References, or press Ctrl + Shift + G. All occurrences of the selected procedure name in the current program display in the search tab under the program name. Each found instance includes the line number where the instance is located. This appears regardless of whether or not Line Numbering is being used.

Folding

Folding hides sections of your program, such as multi-line comment blocks that start on the fist line or other multi-line comment blocks, external or internal procedures, do-end and begin-end blocks and data structure declarations. You can hover over a collapsed section to display it in expanded form.

You can configure Eclipse to always fold any combination of these block types. To do this, click Window > Preferences > Micro Focus > PL/I > Editor > Folding and check the options that you require.

Go To Definition

Go to definition lets you locate the definitions of variables in the code. Click a variable and press F3 to move to the code that declares the variable. You can also hover over a variable anywhere in code to see a tool tip that shows the procedure in which it is defined and other information including the variable definition and the number of times the variable is referenced in the program.

Go to Matching Block/Bracket

You can use this to locate the bracket or block that matches the one at your current cursor position. In this case, a block is a do-end, begin-end, and select-end block. To move the cursor to the matching block or bracket, right-click in the PL/I editor, and then click Go to Matching Block/Bracket. Alternatively, press Ctrl+Shift+P.

Horizontal Rule

The Horizontal rule runs along the top of the PL/I editor window. It marks the columns with a tick and numbers them into groups of ten. This is helpful when column alignment is required in PL/I programs. Showing or hiding the horizontal rule affects all files open in a PL/I editor tab.

You can configure Eclipse to hide or show the horizontal rule. To do this, click Window > Preferences > Micro Focus > PL/I > Editor and check Show horizontal ruler.

Include Dependency View

Include Dependency view shows a list of the include files referenced from the current program or include file and any nested include files. Click Window > Show View > Include Dependency to see the current program in the PL/I editor display in the Include Dependency tab.

Click the Sort button ( [image]) in the tab to toggle between a physical or alphabetical sequence. Click Hide Program Structure ( [image]) to show the program structure and where the include files fit in it, or only show the include files in the current file.

Line Numbering

Line numbering helps with collaboration and simplifies code navigation, especially in larger programs. Click the Renumber/Unnumber buttons in the toolbar to either insert or remove line numbers from the right margin in the sources. For PL/I, this margin is at column 256. By default, line numbering starts at 00000100 at the first line, and increments by 100 lines. You can specify a different number of lines to increment. To do this, click Window > Preferences > Micro Focus > PL/I > Editor > Line Numbering, and type an integer number of lines.

You can also show the standard Eclipse line numbers in the left margin of any file in the PL/I editor. Right-click anywhere in the left margin and choose Show Line Numbers to show or hide line numbers. Using this command enables the Eclipse standard line numbers for all files open in a PL/I editor.

You can also set the color shown in columns set outside the margins in the Margin color list box.

Margins

By default, the editor automatically sets the PL/I margins based on the project type - at column 1 and 72 for native PL/I programs and at columns 2 and 72 for mainframe subsystem PL/I code. To configure the margins, click Window > Preferences > Micro Focus > PL/I > Editor and either check or uncheck Automatically set margins based on the project settings, or set the margins as needed in the Margin columns field. Change the color of the margin using Margin color.

You can also set the color shown in columns set outside the margins in the Margin color list box. This sets the color of the margin horizontal lines in Eclipse and not of the columns.

Tip: You can also use the -margins compiler option to set the margins for a project, see Compiler Options.

Mark Occurrences

Mark occurrences highlights all the occurrences of the selected variable in the current file. Click the Toggle Mark Occurrences button ( [image]) to turn the feature on or off. When turned on, click within the desired variable name to see where else it is used in the current file.

Outline View

Outline view shows the structure of the program you are editing. This is useful for navigating large programs, for example by clicking on a procedure or a variable declaration to go to it in the code and vice versa - clicking in the code also selects the same block in the Outline view.

The Outline view shows only items from the current editor - if the program is opened in the PL/I editor only items from the current program will be visible and not from its include files. If the program is opened in the Copy View, all items are visible in the editor (the Copy View is a read-only editor) and in the outline.

Double-click items in the Outline view to see how the cursor positions itself on the respective line of code that each one of these outline items refers to and highlights the referenced item in the editor window.

Click the Sort button ( [image]) for the Outline to toggle between a physical or alphabetical sequence.

You can also use the Outline view to manage program debugging execution. Right-click a line to stop on during debugging and click Toggle Breakpoint to set or clear a debug breakpoint at the selected line. To specify a data item you want to watch or stop watching for certain conditions to be met, right-click to select the data item, then click Toggle Watchpoint.

Quick Outline

Quick Outline view lets you see the structure of the current program as a tree view in a pop-up. While working in the PL/I editor, press Ctrl + o or right-click and select Quick Outline to activate the Quick Outline view. You can actively search any string in the program by typing in the entry field at the top of the window. Click any element in the Quick Outline view to move the cursor to the beginning of the line containing the element.

Program Outline View

Program Outline view shows the whole program structure of the current PL/I program, including the procedures, statements, variable declarations, and other elements in an expandable and collapsable tree view. You can also see the elements that are in other files. Click Window > Show View > Program Outline to see the current program in the PL/I editor display in the Program Outline tab.

Click a data declaration in the Program Outline view to open the relevant source or include file, and to navigate to the line containing the data item. Similarly, clicking on a data item in the PL/I editor highlights that item in the Program Outline view at the appropriate place in the program outline.

Right-click to select an element in the Program Outline tab and click References to display a listing of where the selected element is referenced in the program. The reference listings appear in the Search tab.

Like the Outline View, you can also use the Program Outline view to manage program debugging execution. See the section Outline View in this topic for details.

Read-Only Background Coloring

Read-only background coloring displays read-only files with a light-yellow colored background in a PL/I Editor window as a visual cue that you cannot edit the file.

Remote Development Mode

If you are editing PL/I on a remote development platform you can disable statement checking that might generate unwanted diagnostic messages. To do this, click Window > Preferences > Micro Focus > PL/I > Editor, and then check Remote development mode.

Remove Trailing Whitespace

By default, trailing whitespace is not removed when you save a PL/I file. You can specify that you want to remove all trailing whitespace when you save the file. To do this, click Window > Preferences > Micro Focus > PL/I > Editor, and then click Remove trailing whitespace on save.

To remove all trailing whitespace, click Source > Remove Trailing Whitespace. Alternatively, right-click in the PL/I editor, and then click Source > Remove Trailing Whitespace.

Shift-out/Shift-in (SOSI) Byte Editing

You can insert a character in the PL/I editor to indicate a shift out of a single byte input stream into a double byte input stream, then insert another to shift back from a double-byte to a single-byte stream. Press ALT+S, then O to insert the shift-out character to double-byte, and press ALT+S, then I to shift back into single-byte mode after typing the double-byte characters you need. This allows double-byte characters in your PL/I code, particularly Japanese-language characters, as shown in this graphic.

Show/Hide Whitespace Characters

Click the Show Whitespace Characters button ( Show Whitespace Characters) in the toolbar to alternately show and hide whitespace characters in the editor. Whitespace characters include spaces, carriage returns, and end-of-line markers. Showing or hiding whitespace characters affects any PL/I editor window you view. Click the button again to show or hide the characters.

Smart Edit Mode

Smart Edit Mode controls code line wrapping behavior when the end of the code area is reached, or when deleting code, as well as line breaking and margins and indentation when creating new lines or using the Tab key. See the topic Configuring Smart Edit Mode for PL/I for more information on setting Smart Edit features for your PL/I programs.

Smart Caret

Smart caret lets you customize the behavior of the Home, End, and Tab keys. You can configure how the Home, End and Tab keys move the cursor in the code area.

To do this, click Window > Preferences > Micro Focus > PL/I > Editor to set the various smart caret options. See the topic Customizing the Behavior of Home, End, and Tab Keys for more information.

Syntax Error Reporting

The code you type is parsed continuously to identify errors. The errors are underlined with red squiggly lines, and warnings are underlined with yellow squiggly lines. You can hover over an error to see information about the error in an error message tool tip.

Tasks

You can manage tasks by adding the default TODO or FIXME tags in the PL/I code comments. Eclipse visualizes these tags in the Task tab. Any text that follows the TODO or FIXME tags appears in the task description. To view the Task tab, click Window > Show View > Tasks or Windows > Show View > Other, expand General, click Tasks, then click OK. Double-clicking on the line in the Task tab takes you to the highlighted line in the editor.

Both TODO and FIXME tag lines are marked on the left margin of the editor with a clipboard icon ( [image]). Rows in the Task tab that are tagged TODO are high priority tasks and are highlighted with an exclamation point ( [image]).

You can customize the tags from Window > Preferences > Micro Focus > PL/I > Editor > Task Tags. You can add, remove or edit tags, specifying their priority as high, normal or low.

Toggle Comments

Allows you to toggle single or multiple lines between a commented and uncommented state. Pressing Ctrl+/ toggles the highlighted lines between states. Commenting a line applies a leading "/*" and closes the last highlighted line with a "*/", uncommenting removes these markers. See Comments for more information on comments in PL/I.

  • Word wrapping and indentation in Smart Edit Mode
  • Customizing the Behavior of Home, End, and Tab Keys
  • Configuring Which Preprocessor Statements are Ignored by the PL/I Parser
  • Configuring the Ruler in the PL/I Editor
  • Configuring Background Parsing in the PL/I Editor
Parent topic: Using Eclipse for PL/I development


Word wrapping and indentation in Smart Edit Mode

Smart Edit Mode controls the behavior of word wrapping and indentation in the different areas of the PL/I source files.

To enable the Smart Edit Mode:

  1. Click Window > Preferences > Micro Focus > PL/I > Editor.
  2. Ensure Smart edit mode is enabled.
  3. Click OK.

Alternatively, click Toggle Smart Edit Mode, Toggle Smart Edit Mode, in the Eclipse toolbar to turn the mode on or off.

You can change the following configuration options in the Typing preferences dialog box by selecting Window > Preferences > Micro Focus > PL/I > Editor > Typing.

Wrapping
  • Wrap code when source code area end is reached - lines wrap when you reach the end of the source code area.
  • Wrapping moves the text in the right hand area to the new line - any comments in the right-hand area stay in the right-hand area but move to the next line when wrapping in the source code area occurs.
  • Wrap lines when deleting forwards and backwards - when you press Delete after the last non-white space in the area, the line beneath moves up (and where possible wraps in the source code area), and comments in the right-hand area stay with the associated line of code. Similarly, when you press Backspace in column 1, the current line moves up (and where possible wraps in the source code area), and comments in the right-hand area stay with the associated line of code.
Indentation
  • Enter key and smart wrapping adjust the indentation on the new line - pressing Enter moves the code to the next line and to the column where the previous line starts. When this is disabled, pressing Enter moves the code on the next line to the start of the source code area.
  • Tab/Shift-Tab keys adjust the indentation based on the area margins - configures the indentation when you use Tab to move code and it reaches the end of the source code area, and also configures how Shift+Tab moves text in the different areas of the code.
Parent topic: The PL/I Editor
Related concepts
Customizing the Behavior of Home, End, and Tab Keys
Configuring Which Preprocessor Statements are Ignored by the PL/I Parser
Configuring the Ruler in the PL/I Editor
Configuring Background Parsing in the PL/I Editor


Customizing the Behavior of Home, End, and Tab Keys

You can configure how the Home, End and Tab keys move the cursor in the editor as follows:

  1. Click Window > Preferences > Micro Focus > PL/I > Editor.
  2. Ensure Smart caret is checked and check the following options as required:
    • Pressing Tab in the sequence area moves caret to beginning of the source code area - when this is checked, if the cursor is in the sequence area, pressing Tab moves it to the first line of the source code area.
    • Pressing Home/End moves caret to the beginning/end of the area - changes the way the Home and End keys move the cursor in the PL/I editor. Pressing Home repeatedly first moves the cursor immediately before the first non-white space in the current area, then at the beginning of the area, or to the first non-white space in the preceding area. Pressing End repeatedly first moves the cursor immediately after the last non-white space in the current area, and then at the start of the following area.
  3. Click OK.
Parent topic: The PL/I Editor
Related concepts
Word wrapping and indentation in Smart Edit Mode
Configuring Which Preprocessor Statements are Ignored by the PL/I Parser
Configuring the Ruler in the PL/I Editor
Configuring Background Parsing in the PL/I Editor


Configuring Which Preprocessor Statements are Ignored by the PL/I Parser

In cases when mainframe PL/I code is offloaded and this code then gets compiled back on the mainframe, you can prevent specific PL/I macro statements from being parsed by the PL/I parser for code that is currently in the PL/I editor.

  1. Click Window > Preferences > Micro Focus > PL/I > Editor > Ignore Statements. The Ignore Statements page appears, showing the current list of statements to be ignored by the PL/I Background parser. This includes a set list of default statements and any added statements.
  2. Do one of the following:
    • To add a statement to the list of ignored statements: Click Add and enter the name of a valid preprocessor statement in the Add a Statement dialog box. Click OK to add the statement to the list.
    • To delete a statement from the list: Select the statement and click Remove.
    • To edit the name of an existing statement: Select the statement and click Edit, then edit the statement token in the Edit a Statement dialog box.
    • To share a list of ignored statements: Click Export to create an .xml file that can be shared with other users, or click Import to search for and import a file containing another user's list of ignored statements.
    • To use the original default list of statements: Click Restore Defaults.
  3. Click OK to close the Ignore Statements page and save any changes made.
Parent topic: The PL/I Editor
Related concepts
Word wrapping and indentation in Smart Edit Mode
Customizing the Behavior of Home, End, and Tab Keys
Configuring the Ruler in the PL/I Editor
Configuring Background Parsing in the PL/I Editor


Configuring the Ruler in the PL/I Editor

By default, the horizontal ruler is displayed in the editor. You can specify whether to display it or not as follows:

  1. Click Window > Preferences > Micro Focus > PL/I > Editor.
  2. Enable or disable the Show horizontal ruler check box as required.
  3. Click OK.
Parent topic: The PL/I Editor
Related concepts
Word wrapping and indentation in Smart Edit Mode
Customizing the Behavior of Home, End, and Tab Keys
Configuring Which Preprocessor Statements are Ignored by the PL/I Parser
Configuring Background Parsing in the PL/I Editor


Configuring Background Parsing in the PL/I Editor

The code you type is parsed continuously to identify errors. The errors are underlined with red squiggly lines.

Regardless of whether background parsing is enabled, error information is generated during project builds.

CAUTION:
You can turn off background parsing, but many of the IDE features depend on it (for example Outline/Program outline, colorization). If it is switched off they will not work and might cause unexpected problems.

Switching off or delaying background parsing when Eclipse is running

You can turn off background parsing in the Preferences dialog box (select Window > Preferences > Micro Focus > PL/I > Editor and uncheck Background parsing).

Parsing is triggered when there is a pause in editing code; by default this is 500 milliseconds. By keeping Background parsing selected and entering a larger value in the Trigger delay field, you can make sure your code is parsed less frequently, and improve performance when developing projects with large numbers of source files.

Switching off background parsing before you start Eclipse

Use the property disable.cobol.indexing to switch off background parsing when you start Eclipse.

If you start Eclipse from the command line, you do this by using the command:

eclipse.exe -vmargs -Ddisable.cobol.indexing=true

If you start Eclipse from the Start menu or a shortcut, edit the eclipse.ini file and add the line:

-Ddisable.cobol.indexing=true

to the -vmargs section.

Parent topic: The PL/I Editor
Related concepts
Word wrapping and indentation in Smart Edit Mode
Customizing the Behavior of Home, End, and Tab Keys
Configuring Which Preprocessor Statements are Ignored by the PL/I Parser
Configuring the Ruler in the PL/I Editor


Creating a PL/I project

From the Team Developer perspective:

  1. Click File > New > Project, expand the Micro Focus PL/I node and choose either:
    • Mainframe PL/I Project, which enables you to use JCL, BMS, and macro files with your project.
    • PL/I Project, for development of console applications.
    • PL/I Include Project is a local project which only contains PL/I include files to be referenced by other PL/I projects. This provides a central location to store/maintain PL/I include files for use by other projects.

    Click Next. The New PL/I Project dialog box appears.

  2. In the Project Name field, type a descriptive name for the project.
  3. If you have created your own PL/I project templates, you can select one of them from the Select a project template box.
  4. Select the Use default location check box to use the workspace location select when you started Enterprise Developer for Eclipse as the location to store the project. Clear the Use default location check box and click Browse to use the Browse For Folder dialog box to select a different location to store the project.
  5. Click Finish to create the new project.

To add new files to a PL/I Project

From the Team Developer perspective:

  1. To create new files and add them to your project, right-click your project in the Application Explorer view, click New > File and choose your file type.

    When you add a PL/I source file, it is created with a .pli extension, but Enterprise Developer also handles files with a .pl1 extension as PL/I source.

  2. Double-click a file in Application Explorer view to open it for editing.

    The PL/I Editor displays different types of keywords in different colors, which you can change by selecting Window > Preferences, expanding the Micro Focus and PL/I nodes and clicking PL/I Syntax Coloring.

To import existing files into a PL/I project

  1. Click your project in the Application Explorer view.
  2. Click File > Import.
  3. In the Import wizard, expand General, click File System and click Next.
  4. Specify the path to the directory that contains your files in the From directory field.
  5. Select the files you want to import and click Finish.
Parent topic: Using Eclipse for PL/I development
Related information
Creating and importing COBOL projects


Creating Remote PL/I Projects

Restriction: You must have Micro Focus Enterprise Developer UNIX Components installed on the remote machine.
Note: When establishing a connection to a remote machine, you must select the type of file system to use for the connection, e.g. RSE or NFS. For more information see Developing applications on remote machines.

You can create new remote projects using the available templates - Enterprise Developer offers templates for creating remote PL/I and remote mainframe PL/I projects.

You can also use existing PL/I projects stored locally on your machine, and convert them to remote projects. The remote projects are stored, edited, debugged and run on the remote machine. The source projects remain in the original location on your machine.

  • To create a remote PL/I project
  • To create a remote mainframe PL/I project
  • To create a remote PL/I include project
  • To convert a PL/I local project to a PL/I remote project
Parent topic: Using Eclipse for PL/I development


To create a remote PL/I project

Restriction: This functionality requires Micro Focus Enterprise Developer UNIX Components.
  1. While in the Team Developer perspective, click File > New > Other.
  2. Expand Micro Focus PL/I, and then click Remote PL/I Project.
  3. Click Next.
  4. In the New Remote PL/I Project wizard, enter a project name.
  5. Specify whether the project should use the Remote file system (RSE) or the Network file system (SAMBA, NFS, etc...) file system to interact with the remote host.
    • The Remote System Explorer (RSE) is a toolkit in the Eclipse IDE Workbench that enables you to connect and work with a variety of remote systems.
      Restriction: The Classic Data File Tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type.
    • The Network File System (NFS) protocol enables a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.
  6. Click Next.
  7. Select or browse for a project template and click Next.
    Note: By default, two templates are available for you to choose from Micro Focus template [32 bit] or Micro Focus template [64 bit]. Select a template that best suits your requirements.
  8. In the Remote settings section, choose the Connection name from the list. Alternatively, click New Connection and use the New Connection wizard to create a new connection.
  9. In the Remote location field, enter the location of the project on the remote host. You can use the Browse dialog box to browse the remote host's file system.
    Note: For a network file system such as NFS or Samba, the Remote location value should be the UNIX or Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive location\project name can be represented by a remote location of /home/users/my-folder.
  10. Click Finish.

    This creates the project and displays it in the Application Explorer view.

Parent topic: Creating Remote PL/I Projects


To create a remote mainframe PL/I project

Restriction: This functionality requires Micro Focus Enterprise Developer UNIX Components.
  1. While in the Team Developer perspective, click File > New > Other.
  2. Expand Micro Focus PL/I, and then click Remote Mainframe PL/I Project.
  3. Click Next.
  4. In the New Remote Mainframe PL/I Project wizard, enter a project name.
  5. Choose whether to use a Remote file system (RSE) or a Network file system (SAMBA, NFS, etc...) to interact with the remote host.
    • The Remote System Explorer (RSE) is a perspective and toolkit in the Eclipse IDE Workbench that allows you to connect and work with a variety of remote systems.
      Restriction: The following tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type:
      • BMS Painter
      • BMS Compiler
      • All Classic Data File Tools
      • IMS Database editor and segment layout editor
      • Mainframe Assembler compiler
    • The Network File System (SAMBA, NFS) protocol enables a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.
  6. If you have created your own PL/I project templates, you can select one of them from the Select a project template box. Alternatively, check Browse for template and click Browse to navigate to the location of the template and select it; then click Next.
    Note: By default, two templates are available for you to choose from Micro Focus template [32 bit] or Micro Focus template [64 bit]. Select a template that best suits your requirements.
    • If you specify a network file system (Samba or NFS) project:
      1. Check Use default location to populate the Location field with the default workspace path and project name. Alternatively, type the full project path in the Location field or click Browse to select the location.
      2. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
        Note: For network file systems such as NFS or Samba, the Remote Location value should be the UNIX/Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive location\project name should be represented by a remote location of /home/users/my-folder.
    • If you specify a remote file system (RSE) project:
      1. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
  7. Click Finish.

    The project is created and appears in the Application Explorer view.

Parent topic: Creating Remote PL/I Projects


To create a remote PL/I include project

Restriction: This functionality requires Micro Focus Enterprise Developer UNIX Components.

Remote PL/I Include Project is a remote project which only contains PL/I include files to be referenced by other remote PL/I projects. This provides a central location to store/maintain PL/I include files for use by other projects.

  1. Click File > New > Remote PL/I Include Project.
  2. Click Next.
  3. In the New Remote PL/I Include Project wizard, enter a project name.
  4. Specify whether the project should use the Remote file system (RSE) or the Network file system (SAMBA, NFS, etc...) file system to interact with the remote host.
    • The Remote System Explorer (RSE) is a toolkit in the Eclipse IDE Workbench that enables you to connect and work with a variety of remote systems.
      Restriction: The Classic Data File Tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type.
    • The Network File System (NFS) protocol enables a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.
  5. Click Next.
  6. Select or browse for a project template and click Next.
  7. In the Remote settings section, choose the Connection name from the list. Alternatively, click New Connection and use the New Connection wizard to create a new connection.
  8. In the Remote location field, enter the location of the project on the remote host. You can use the Browse dialog box to browse the remote host's file system.
    Note: For a network file system such as NFS or Samba, the Remote location value should be the UNIX or Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive location\project name can be represented by a remote location of /home/users/my-folder.
  9. Click Finish.

    This creates the project and displays it in the Application Explorer view.

Parent topic: Creating Remote PL/I Projects


To convert a PL/I local project to a PL/I remote project

Restriction: This functionality requires Micro Focus Enterprise Developer UNIX Components.
  1. While in the Team Developer perspective, click File > Import.
  2. Expand the Micro Focus folder in the Import dialog box, select Convert Local Micro Focus Projects to Remote Projects , then click Next.

    The Import and Convert Local Micro Focus Projects to Remote dialog box appears.

  3. Click Browse, and select the directory containing the project, then check the project to convert or click Select All if you want to import multiple projects.
    Note: The project being imported should not be in the current workspace.
  4. Choose whether to use a remote file system (RSE) or a network file system (Samba or NFS) to interact with the remote host.
    • The Remote System Explorer (RSE) is a perspective and toolkit in the Eclipse IDE Workbench that allows you to connect and work with a variety of remote systems.
      Restriction: The Classic Data File Tools do not work with files that are part of a remote project created using the Remote System Explorer (RSE) connection type.
    • The Network File System (NFS) protocol allows a client machine to access files over a network connection in a similar manner to how local storage on the client machine is accessed.
  5. Click Next.
    • If you specify a network file system (Samba, NFS) project:
      1. Check the Use default location to populate the Location field with the default workspace path and project name. Alternatively, type the full project path in the Location field or click Browse to select the location.
      2. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
        Note: For network file systems such as NFS or Samba, the Remote Location value should be the UNIX/Linux representation of the path as specified in Location. For example, a location of X:NFS-mounted-drive location\project name should be represented by a remote location of /home/usersmy-folder.
    • If you specify a remote file system (RSE) project:
      1. In the Remote location field, type the path of the project on the remote host. Click Browse to browse the remote host's file system.
  6. Click Finish

    This creates the project and displays it in the Application Explorer view.

Parent topic: Creating Remote PL/I Projects


Setting PL/I Project, File and Build Configuration Settings

You can set properties that apply to the whole project, to individual build configurations or just on individual files.

  • Configuring PL/I project's properties
  • Configuring the Build Configuration of a PL/I Project
  • Setting Properties on PL/I Files
Parent topic: Using Eclipse for PL/I development


Configuring PL/I project's properties

To set project properties that apply to all files in the project, right-click the project in the Application Explorer view and click Properties, then expand the Micro Focus > Project Settings > PL/I Compile Settings node. The following options can be set:

Common options

System
Enables linking to the mainframe system with which the program will operate: either IMS, MVS for programs executing under JCL, or CICS.
Restriction: This option applies to Mainframe PL/I projects only.
Compile for debug
Compile the program for debugging.
Generate listing file
Produce a compiler listing file. The default name of the file containing the listing is xxx.lst, where xxx is the source filename (excluding the pathname) up to, but not including, a last "." (period) in the name. For example, if the source filename is prog.pl1, the default listing is prog.lst. A compiler listing is produced by default whenever -exp, -map, or -xref is specified.
Optimization level
Specifies the level of optimization by the PL/I compiler, where level stands for the level (1 - 3) of optimization. The default setting is -noopt. If a level is not included, the program is optimized at level 3. If -deb is specified, -opt 2 is the maximum level allowed. Note -opt -deb is equivalent to -opt 2 -deb.
Endianness

Select the endianness of the system. The default is "Big endian" (or non-native). Select "Native" for little endian.

EXEC preprocessor options
Specify options for the EXEC preprocessor. Options include PLITEST and NEWNAME(name)
Additional options
Enter any other required compiler directives in this text box.

Logging information

Warnings for filters in structures
Produce warnings for structures containing fillers.
Emit diagnostics

Emit diagnostics for I, W, E, or S level errors.

Print statistics
Prints compiler statistics to the standard output as each compiler phase completes.
Cross reference information

Controls the production of cross reference information

Verbose output
Shows additional build output.

Data types

Use float binary as float decimal

Controls whether or not to use float binary as float decimal.

Use floating point in trigonometry

Controls the uses of floating point for trigonometric functions.

Fixed binary precision

Changes the default precision of fixed binary variables.

Inverse bits
Inverse bits for UNSPEC, INT, and POSINT on big-endian machines.

Formatting and display

Control alignment
Controls alignment of generated code.
Currency symbol
Provides a currency symbol for picture specification. It can take the character, decimal number, or hex constant of the form 0xDD. For example:
  • -currency_symbol £
  • -currency_symbol 163
  • -currency_symbol 0xa3
Specify margins

Specifies the margins (-margins left, right).

Additional NLS support
Provides extended character support. For example, "-names 'string1' ['string2']" where string1 are extralingual characters to add to identifiers, and string2 are optional corresponding uppercase characters. Hex constants of the form 0xDD are accepted in place of the strings. The default is -names.

Initialization

Initialize aggregates
Performs initialization of aggregates (arrays and structures) compatible with 7.x versions of Open PL/I.
Initialize automatic storage
Initializes automatic storage to zero.
Set value of null pointer
Designates a null pointer value n to be returned by the NULL built-in function, where n is a decimal value. If this option is not specified, the value of the NULL built-in function is an address with all bits set to 1.
Storage allocation map
Specifies production of storage allocation maps.

Data checking

More extensive prototype checking
Provides more extensive prototype checking on arguments against parameters in entry declarations (also assumed by default when using -vax).
Subscript range checking
Specify subscript range checking
Undeclared variable declarations
Do not allow implicit compiler declarations for undeclared variables.

External elements

External vars in data section
Causes external variables to be defined in the .data section. You must use this option for programs using external files.
Include file suffix
File extension to use for include files. While the defaults are both .in and .inc, you can only add one extension in this field.
Include handling
Determines how %INCLUDE statements are handled.
Unreferenced external handling in obj files
Include or exclude unreferenced external entries in object files.

Compatibility

Use VAX conventions
Makes the following adaptations for programs originally written with Digital Equipment Corporation's PL/I Compiler for the VAX platform:
  • enables the Fixed Binary(p ? 7) data type as a one-byte signed binary integer.
  • enables Float Binary(24) as equivalent to Float Binary(23).
  • enables Float Binary(53) as equivalent to Float Binary(52).
  • causes the BINARY attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL.
Limit argument descriptors
Tells the compiler to produce argument descriptors for calls only when array bounds or string lengths in the parameter declaration are represented by the asterisk (*) symbol.
When this option is not used, the compiler produces descriptors for array, structure, and string arguments, which can be a problem for very large structures.
Set unaligned at level 1
Causes all structures to be mapped as if the UNALIGNED attribute is specified at the level 1 structure level. This option is for compatibility with versions of DEC VAX PL/I.

Other compiler options

Alternate NOT symbol
Selects alternate NOT symbol.
Alternate OR symbol
Selects alternate OR symbol.

CICS Preprocessor settings

Restriction: These options apply to Mainframe PL/I projects only.

You need to select Enable configuration specific settings to change these settings.

CICS preprocessor options
Specify the options for the CICS External Compiler Module to use.

Macro Preprocessor settings

You need to select Enable configuration specific settings to change these settings.

Emit full listing
When invoking macro preprocessor do not emit %NOLIST before includes.
Infuse include file
Name of include file to infuse as first line of source
No debug information
Specifies that the preprocessor will not generate the normal debug information that it passes to the Compiler. This is useful if you wish to debug using the post-preprocessing PL/I source file rather than the original source file.
Define a macro
Causes value to be used in place of name wherever the identifier name appears.
Undefine a macro
Removes a definition for name, if name was created by a -define option, and leaves the identifier name in the source as name. It does not preclude a %REPLACE statement or %name=expr from changing the value of name.
Specify variant
Supplies a string to be used in place of the VARIANT built-in function.
Process include name
Causes the preprocessor to examine a %INCLUDE file name for the characters @, #, and $, and to replace @ with A, # with N, and $ with D.

SQL Preprocessor settings

You need to select Enable configuration specific settings to change these settings.

DB2 preprocessor options
Specify the DB2 precompiler options for the SQL External Compiler Module to use.
Parent topic: Setting PL/I Project, File and Build Configuration Settings
Related reference
LPIPARAMCOUNT Function
Related information
Compiler Directives
Data Types


Configuring the Build Configuration of a PL/I Project

To set project properties that apply to all files in the project:

  1. Right-click the project in the Application Explorer view, and then click Properties.
  2. Expand the Micro Focus > Build Configurations > PL/I Compile Settings or PL/I Link Settings node, and select any of the properties page.
  3. Check Enable configuration specific settings.
  4. Specify properties as required.
  5. Click Apply and then click OK.

The properties you set on the properties pages for the build configurations only apply when you build your application in the specified build configuration.

Parent topic: Setting PL/I Project, File and Build Configuration Settings


Setting Properties on PL/I Files

Files inherit the properties set on project level. You can override these properties by manually setting properties on file level as follows:

  1. In the Application Explorer view, right-click a file or a selection of files in your project.
  2. Click Properties.
  3. Check Enable file specific settings.
  4. Specify file properties as required and click Apply and then OK.

To set file properties using directives scanning:

Important: This automatically determines the directives that need to be set on individual files. If the project already has a required settings, the scan does not set this on a file.
  1. Select a file, group of files, directory, or a project in the Application Explorer view.
  2. Right-click the selection, and click Determine Directives.

    A window showing the proposed changes opens after the scan.

    The following settings can be set this way:
    CICS Preprocessor settings
    Files that contain EXEC CICS statements have the EXEC CICS option set. The scan sets no other CICS preprocessor options.
    Macro Preprocessor settings
    Enables the Macro preprocessor for files containing any Macro statements.
    SQL Preprocessor settings
    If the files contain any EXEC SQL statements, the EXEC SQL and Preprocessor Type options are set accordingly. The scan sets none of the additional directive's options.
  3. Click OK to accept the changes or Cancel to ignore them.
Parent topic: Setting PL/I Project, File and Build Configuration Settings


Indicating that a PL/I Include File is a Source File

While in the PL/I perspective, PL/I source files (.pli) referenced from other PL/I source files using an %include statement (for example, %include 'programname.pli') are recognized by the IDE as include files and appear in the PL/I Explorer in the PL/I Include Files virtual folder. The IDE does not compile the files in the PL/I Include Files folder and does not support setting Compiler directives on them.

If such .pli files no longer need to be (or should not have been) used as include files and you remove the %include statements, the IDE does not move the files automatically to the PL/I Source Files category and they are still treated as include files. You need to indicate manually that a .pli file shown in the PL/I Include Files folder is a PL/I source file:

  • In the PL/I Explorer, right-click a .pli file that appears in the PL/I Include Files folder and click Transform Include File to Source File.

    This updates the information in the project about this file and moves the file to the PL/I Source Files folder of the project.

Alternatively, you can do one of the following:

  • Use drag and drop in PL/I Explorer to move the file from the PL/I Include Files folder to the PL/I Source Files folder of the project.
  • Copy the file from the PL/I Include Files folder and paste it into the PL/I Source Files folder of the project.
Parent topic: Using Eclipse for PL/I development


Compiling and building a PL/I project

Attention: You must recompile and relink your PL/I applications to use them with this Enterprise Developer release.

By default, Eclipse builds projects automatically whenever a file is saved. To turn off automatic building, select Window > Preferences > General > Workspace and clear the Build automatically check box.

Use build configurations to specify project settings that are passed to the Compiler, including pre- and post-build events, and additional library and resource files.

To configure build configurations, right-click the project in Application Explorer view, select Properties. Then expand the Micro Focus > Build Configurations node.

The built artefacts are selected by clicking in the PL/I Link Settings options of the build configuration and entering a value for Output type. The options are:

Single executable native library
One .dll file for the whole project.
Single executable
One .exe file for the whole project.
Single library
One .lib file for the whole project.
All executable native libraries
A .dll file for each .pli source file in the project.
All executables
An .exe file for each .pli source file in the project.
All libraries
A .lib file for each .pli source file in the project.
Parent topic: Using Eclipse for PL/I development
Related information
Building COBOL applications
Compiler Directives


Linking PL/I programs

Attention: You must recompile and relink your PL/I applications to use them with this Enterprise Developer release.

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.

To configure linking, right-click the project in the PL/I Explorer view and choose Properties, expand the Micro Focus > Build Configurations > PL/I Link Settings node. The following options can be set:

Common options

Output type
Select the type of output files to create:
Single executable native library
One .dll file for the whole project.
Single executable
One .exe file for the whole project.
Single library
One .lib file for the whole project.
All executable native libraries
A .dll file for each .pli source file in the project.
All executables
An .exe file for each .pli source file in the project.
All libraries
A .lib file for each .pli source file in the project.

The default value is "All executable native libraries".

Output filename
Filename to use when creating a single output target type (either single executable or single library).
Additional options
Enter any other required compiler directives in this text box.

Advanced options

Note: Refer to the Microsoft linker documentation for further information on these setttings.
Base address
Sets a base address for the program.
Entry-point symbol
Sets the starting address.
Force file output
Forces a link to complete even with unresolved or symbols defined more than once.
Set heap size
Sets the size of the heap in bytes.
Generate mapfile
Creates a mapfile.
Stack allocations
Sets the size of the stack in bytes.
Verbose output
Output information about the progress of the linking session.

Additional Link Files

Use this dialog box to select other items to be linked to your program.

Parent topic: Using Eclipse for PL/I development
Related information
Linking Native COBOL Code (Windows)
Compiler Directives


Debugging PL/I projects

To debug a local or remote PL/I project you first need to create a debug configuration. This is a set of options and values that determine how a debug session runs and what values it should use.

The following PL/I debug configuration types are available:
  • PL/I Application
  • PL/I Attach to Process - when you want to start debugging a PL/I user program/process that is already running.
  • PL/I Enterprise Server - when you want to debug PL/I applications on Enterprise Server.
  • PL/I Wait for Application Attachment - puts Eclipse in debug wait state until user program signals it's ready to start debugging, usually with a call to PLITEST().
  • To debug a PL/I project
  • PL/I debug configurations
  • Debugging commands and options (PL/I)
  • Views in the debug perspective
  • Using breakpoints
  • Debugging projects developed on a remote UNIX machine
  • Troubleshooting
Parent topic: Using Eclipse for PL/I development
Related information
CodeWatch User's Guide


To debug a PL/I project

  1. Click Run > Debug Configurations. The Debug Configurations dialog box appears.
  2. Select the type of application or scenario such as PL/I Application, PL/I Attach to Application, PL/I Enterprise Server or PL/I Wait for Application Attachment in the left side pane and create a new configuration by clicking on the New launch configuration button. Tabs that contain various debug settings to use for a configuration appear in the right pane of the Debug Configurations dialog box.
  3. Type a descriptive name for the configuration in the Name field.
  4. Enter the required settings for the configuration in the General, Common, Environment, Source, and Debug Symbols tabs. Click Apply after making your configuration settings.
  5. Click Debug (or press Alt+Shift+D then L) to start debugging.

The next time you want to debug the project, you can choose an existing configuration by selecting Run > Debug As.

Parent topic: Debugging PL/I projects


PL/I debug configurations

General tab

The General tab options common for PL/I Application, PL/I Attach to Application and PL/I Wait for Application Attachment are listed and described below:

PL/I Project
The project that will be used while debugging.
Connection Properties
Enter values for these fields if you want to debug your project or the application when it is running on a remote machine.
Remote Host
The name or IP address of the remote machine.
Specify the port on which cobdebugremote process will listen on the remote host
When you are debugging an application on a remote machine, the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) needs to be running on that machine.
If you are developing the application on the remote machine
If you are using Micro Focus Enterprise Developer UNIX Components, the IDE starts the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) automatically on the remote machine when you start debugging. You do not need to select a port as a random one is picked when the process starts, but if you select this option you can assign a specific port in the cobdebugremote port field. If you do specify a port, the process starts automatically on that port.
If you are developing the application on the local machine and debugging remotely
You must first start the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process (or cobdebugremote64 for a 64-bit process) from a command prompt.
The process takes the following options:
no options
Starts the process and opens a random port for remote connections. The port number is displayed in the console.
machine=name
Specify the machine that the process is running on. Only valid with the stop option.
port
port=nnnnn
Specify the port to use to listen for connection requests.
port=nnnnn-yyyyy
Specify the range of ports to use. If port nnnnn is in use, the next port is tried until a free port is found. If no free ports are found in the range, the utility returns an error.
Note: You must enter the same number you set as the port option in the cobdebugremote port field of your debug configuration.
repeat
After the debug session has been completed, start listening for another connection. If no option is specified, the process exits after the debug session has completed.
stop
Causes the process that is listening on the port to exit. Must be used with the port option. This is only valid when the process is waiting for a connection.
If you run the process with no options, you must enter the port number displayed in the console in the cobdebugremote port field.
X Server (DISPLAY)
If you are debugging an application on a remote UNIX machine using Micro Focus Enterprise Developer UNIX Components, enter the identifier for the X server that will display the remote program output on a local Windows machine. The default value is client machine name:0.0.
Before debugging, make sure that the X server is running and that the remote machine xhost configuration has the correct access permissions. You can use the xhost + command to add your host or username to the list of those permitted.
The following settings are only applicable to PL/I Application debug configurations:
Main Program
Select the main executable in your project. If you have already selected this in a build configuration you only need enter the build configuration name, otherwise you can browse to the program's location in your project.
Start Options
Enter the arguments to pass to the program when it starts. You can also indicate the working directory of the application if the project doesn't explicitly specify its location.
Run Options
Check Pause after running the application to prevent the application terminal from automatically closing once it has completed running. This option gives you time to note any terminal output. Press Enter to close the terminal.

The following settings are applicable to PL/I Attach to Application and PL/I Wait for Application Attachment debug configurations:

Debug Options
Use these options to further control the debugging process.
  • To ensure debugging works correctly, you must indicate when the application you are debugging is 64-bit or graphical.
  • For PL/I Wait for Application Attachment you can select the Return to waiting state when debugger disconnects option. this means the debugger will wait until a debuggable program attaches to it again. If you do not select it, debugging terminates when it disconnects from the program.
The following settings are only applicable to PL/I Wait for Application Attachment debug configurations:
Matching Options
Specifies which programs the debugger attaches to when the program starts:
  • Any - the debugger attaches to any process that is enabled for debugging. For instance, using the environment variable COBSW=+A or by a call to CBL_DEBUG_START.
    Note: This option is only available when debugging applications running on Windows.
  • Debug session identifier - specify the identifier of the program the debugger should attach to.
  • Executables stored in directory:
    • On Windows platforms, specify the directory which contains the main executable used to start the process.
    • On UNIX platforms, specify the current directory of the process.

Source tab

The options common to the Source tab in the Debug Configurations dialog box for these configurations are:

Source Lookup Path
Enables you to specify the locations and order in which the debugger looks for source files.

Click Add to add locations:

File System Directory
Click this to specify a specific file system folder to be searched that may exist outside the workspace.
Environment Variable
Click this to select one or more variables that include the folders that must be searched.
PL/I Project
Click this to choose the projects to search. Any folders and dependent projects specified on the Micro Focus > Build Path tab in the projects' properties is also searched.
Project
Click this to enable folders in a specific project to be searched.
Working Set
Click this to add the source lookup path for all the visible projects defined in a working set, see Working Sets.
Workspace
Click this to search all folders within the current workspace.
Workspace Folder
Click this to enable you to specify a specific folder within your workspace as a source lookup path.

Environment tab

This tab is only available for PL/I Application.

Add, modify or remove environment variables using the Add, Edit or Remove buttons.

You can also select to use an environment script or inherit values from the build environment of the associated project.

Common tab

On this tab you can specify some launch configuration settings:

Save As
Lets you select whether to save the launch configuration as a local file or a shared file in a workspace project.
Display in favorites menu
Lets you select the menus where this configuration will appear as a favourite. The options for PL/I Application are Debug and Run. For the other three PL/I debug configuration types there is only one option, Debug.
Encoding
Lets you select the type of encoding.
Launch in background
If this option is selected, the configuration will be launched in the background.

Debug Symbols tab

In this tab you can specify the location in which the debugger looks for debug symbols (.idy) files.

Click Add to add locations:

Environment Variable
Click this to select one or more variables that include the folders that must be searched.
File System Directory
Click this to specify a specific file system folder to be searched that may exist outside the workspace.
Project
Click this to enable folders in a specific project to be searched.
Workspace Folder
Click this to enable you to specify a specific folder within your workspace as a source lookup path.
Parent topic: Debugging PL/I projects


Debugging commands and options (PL/I)

The Eclipse IDE offers a number of debugging features and techniques:

Breakpoint-setting
Run > Toggle Breakpoint or double-click in the left margin.
Data item values
To display a data item's value, you can hover over it, or alternatively right-click it and click Inspect item.

Inspect can also be triggered from a context menu in the editor or by using the Ctrl+Shift+I shortcut.

Debug configurations
Run > Debug Configurations. You can have multiple debug configurations and swap between them. These settings here override the project run-time settings
Main program to debug
Run > Debug. On the General tab, specify the main program file.
Reset execution
Moves the execution point to the cursor position. The shortcut key is Alt+F12, R.
Run to line
You can position your cursor anywhere in your code to instruct the debugger to run from the current execution point to the line on which the cursor is positioned. The feature can save time when debugging as you do not have to use the step functions to step through individual lines of code. You can use Run to line in both the main source code and copybook code. To use, position the cursor in the code and the click Run > Run to line or use the shortcut CTRL+R.
Stop debugging
Run > Terminate. You can also click the red square at the top .
Watchpoint-setting
Run > Toggle Watchpoint or double-click in the left margin.
Keyboard shortcuts - debugging
  • F5 = Step into the next statement at the current line of code and suspend execution. Equivalent of clicking [image].
  • F6 = Step over the next statement at the currently executing line of code without entering it, and suspend execution. The method will be executed normally. Equivalent of clicking [image].
  • F7 = Return from a method or paragraph that has been stepped into, and suspend execution. The remainder of the code inside the method is executed normally. Equivalent of clicking [image].
  • F8 = Resume execution of the program from a suspended line of code. Equivalent of clicking [image].
You can also click the Drop to Frame button [image] to reposition you at the start of the current method.
Querying the value of a data item or the file status of an internal file name
Hold the mouse pointer over a data item or internal file name and the current value or file status displays as a Text Hover. The values of variables and file statuses of internal file names contained on the current execution line and previous line are displayed in Variables View (usually displayed in the top right of the IDE).
Parent topic: Debugging PL/I projects


Views in the debug perspective

When you start debugging, the Debug perspective is displayed, with the views useful for debugging. The default views are listed below; you can display them by clicking Window > Show View.

Variables view
Shows the values of variables and file statuses of internal file names in use on the current or previous line of code. Those which have just changed in the last statement executed are highlighted.
You can configure the contents of this view in Preferences > Micro Focus > Debug, to display values as hexadecimal, for example.

You can change values of the variables in this view. Select a variable from the list, right-click and select Change Value. A dialog box is displayed.

Breakpoints View
Shows the breakpoints you have set, and enables you to set a breakpoint for any program the application calls. You can set actions to take when a breakpoint is hit, by setting the actions in the breakpoint's properties.
You can add breakpoints using the Add an event breakpoint menu ( [image]) in this view. From it you can select the type of breakpoint to add: a program breakpoint, a PL/I condition breakpoint or a PL/I signal breakpoint. When you select Add Program Breakpoint, you are asked to enter the program name. When you select Add a PL/I Condition Breakpoint, a dialog opens that lets you select from a list of conditions to be notified of during the debug session. When you select Add a PL/I Signal Breakpoint, a dialog opens that lets you select from a list of signals to be notified of during the debug session.
Expressions view
Shows the values of data items that you choose to monitor, whether or not they are directly accessed by the current execution statement while debugging.

You can also add an arbitrary expression in the view by clicking Add new expression or [image] in the Expressions view. The added expression can be any string, but to be evaluated it needs to be a valid expression.

Parent topic: Debugging PL/I projects


Using breakpoints

A breakpoint indicates a line of code or program at which you want the execution of an application to pause. When the application is paused, you can view and change the values of data items at that particular step. The Breakpoints Properties view shows details of all bound breakpoints and enables you to configure them.

You set breakpoints by:

  • Double-clicking on the marker bar to the left of the requisite line of executable source code for a breakpoint.
  • Right-clicking on the marker bar and choosing either Toggle Breakpoint from the context menu.
  • You can create a breakpoint for any program in the workspace that your application uses by clicking Run > Add Program Breakpoint, or clicking the [image] icon in the Breakpoint
  • Using the Add an event breakpoint menu ( [image]) on the Breakpoints tab. From it you can select the type of breakpoint to add: a program breakpoint, a PL/I condition breakpoint or a PL/I signal breakpoint. When you select Add Program Breakpoint, you are asked to enter the program name. When you select Add a PL/I Condition Breakpoint, a dialog opens that lets you select from a list of conditions to be notified of during the debug session. When you select Add a PL/I Signal Breakpoint, a dialog opens that lets you select from a list of signals to be notified of during the debug session.

The [image] icon appears in the marker bar when a breakpoint is set. A tick mark is added to these icons when the breakpoint [image] is bound to the program. A program breakpoint is indicated by the [image] icon.

Parent topic: Debugging PL/I projects


Debugging projects developed on a remote UNIX machine

To enable remote debugging using a PL/I Application debug configuration, you need to have an X window implementation installed and running before you start to debug, so that the output of a remote application running on a UNIX machine can be viewed on your local machine. You do not need X window for other debug configuration types.

Windows: Micro Focus ViewNow X is provided as part of Enterprise Developer. See Installing X Windows on Windows in the Installation section. Find the ViewNow X documentation on the Micro Focus SupportLine dropdown menu.

Parent topic: Debugging PL/I projects


Troubleshooting

The following topics provide solutions for issues encountered when using the debugger.

  • Debug session hangs (ES)
  • Debug session hangs
  • Remote debug session hangs
  • CTF tracing
Parent topic: Debugging PL/I projects


Debug session hangs (ES)

This applies to local debug sessions using Enterprise Server.

  1. Click Terminate (Terminate). If this doesn't work, try the next step.
  2. Terminate the cobdebugremote process (or cobdebugremote64) using Task Manager on Windows and the kill command on UNIX.
  3. Go into the ES Region (ESMAC), click Dyn Debug and then click Red X next to your match criteria before starting a new debug session.
Parent topic: Troubleshooting


Debug session hangs

This applies to local debug sessions not using Enterprise Server.

  1. Click Terminate (Terminate). If this doesn't work, try the next step.
  2. Terminate the cobdebugremote process (or cobdebugremote64) using Task Manager on Windows and the kill command on UNIX.
Parent topic: Troubleshooting


Remote debug session hangs

  1. Click Terminate (Terminate). If this doesn't work, try the next step.
  2. Terminate the cobdebugremote process (or cobdebugremote64) using Task Manager on Windows and the kill command on UNIX.
Parent topic: Troubleshooting


CTF tracing

To enable CTF tracing:

  • If using Enterprise Server, set the environment variable MFTRACE_CONFIG in the Configuration Information section of your ES instance, under [ES-Environment].
  • If you are not using Enterprise Server, set the environment variable MFTRACE_CONFIG in a command prompt prior to starting Eclipse. The default location is C:\Users\Public\Micro Focus\Enterprise Developer\eclipse.
  • For non-ES remote projects, set MFTRACE_CONFIG before starting your RDO server.

Example of a debugger issue CTF configuration file:

################################################
# PL/I RTS Tracing
################################################

mftrace.level.mf.rts                              = error
#mftrace.comp.mf.rts#signal             = true

mftrace.level.mf.rts.pli                        = debug
mftrace.comp.mf.rts.pli#all                = true

mftrace.level.MF.DEBUG.ENGINE.PLI = debug
mftrace.comp.MF.DEBUG.ENGINE.PLI#ALL = true
mftrace.comp.MF.DEBUG.ENGINE.PLI#REMOTEALL = true

mftrace.level.MF.DEBUG.ENGINE.NATIVE = INFO
mftrace.comp.MF.DEBUG.ENGINE.NATIVE#ALL = true
Parent topic: Troubleshooting


Running a PL/I application

Before you can run an application, you need to create a run configuration. This is a set of options and values that determine how a session runs and what values it should use.

  1. Click Run > Run Configurations > PL/I Application.
  2. Create a new configuration by clicking on the New Launch Configuration button.
  3. Enter the required settings and click Apply.
  4. Click Run (or press Alt+Shift+X then L) to start the application.

The next time you want to run the project, you can choose an existing configuration by selecting Run > Run As.

Parent topic: Using Eclipse for PL/I development
Related concepts
Running COBOL Applications


Using Enterprise Server from within the IDE

Enterprise Developer provides an integration of Enterprise Server with your IDE of choice - Visual Studio or Eclipse. This means you can use the IDE to administer servers as follows:

  • Create enterprise servers directly from within the IDE - Enterprise Developer provides pre-configured server templates as well as temporary servers if you need to quickly create a server and deploy one or more projects to it.
  • Export server definitions in XML format or as ZIP archives.
  • Import servers using their definition files.
  • Start and stop servers.
  • Associate servers with a Mainframe Subsystem project from Server Explorer.
  • View the server catalog and spool files when debugging or running an application.
  • View the server logs about creating, starting or stopping a server and, for local servers, view the Enterprise Server console log. The information from the log is shown in the Console view.
  • Access the Enterprise Server Administration page - this opens the page within the IDE.
  • Specifying IDE Configuration Options for Enterprise Server
    The Enterprise Server options you specify determine the behavior when using the IDE to debug a mainframe subsystem project.
  • Enterprise Server Templates
    Enterprise Developer provides a number of enterprise server templates, available within the IDE, to enable you to quickly create an enterprise server and associate it with your projects.
  • Using Server Explorer with Enterprise Server
    Server Explorer is an Eclipse view that enables you to connect to servers, as well as view and access their resources.
Parent topic: Developing Applications in the IDE


Specifying IDE Configuration Options for Enterprise Server

The Enterprise Server options you specify determine the behavior when using the IDE to debug a mainframe subsystem project.
  1. Click Window > Preferences.
  2. Expand Micro Focus, then click Enterprise Server.
  3. Check or uncheck the available options, as appropriate:
    Automatically start the associated server
    Start the enterprise server that is associated with your project when debugging starts.
    Automatically stop servers started by Eclipse when closing Eclipse
    Stops any running enterprise servers when you close the IDEs.
    Automatically restart server when project output locations change
    Restarts an enterprise server after reconfiguring the location of built artefacts.
    Automatically create a temporary server
    Creates a temporary enterprise server and associates it with the project if, when debugging starts, the project is not associated with any enterprise server. When you close the project, the server is deleted.
    Automatically enable dynamic debugging
    Enables dynamic debugging for the enterprise server that is associated with your project.

    Dynamic debugging needs to be enabled before you can debug an enterprise server application. If it is not, you must enable it and restart the enterprise server before you can debug. This option is the same as the Allow Dynamic Debugging option available when you edit an enterprise server from within Enterprise Server Administration.

  4. Click OK.
Parent topic: Using Enterprise Server from within the IDE


Enterprise Server Templates

Enterprise Developer provides a number of enterprise server templates, available within the IDE, to enable you to quickly create an enterprise server and associate it with your projects.

The different types of enterprise server templates are available in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates folder, by default. The templates supplied in this folder are the basis for enterprise servers, with the appropriate Mainframe Subsystem Support and CICS, Job Entry Subsystem, or IMS support enabled. For applications that need an enterprise server to run but do not use Mainframe Subsystem Support you need to use the ESTemplate.xml template. You can create additional templates by exporting an active MFDS process repository using the mfds command. See the mfds topic for more information.

Each enterprise server created using one of the templates contains a number of environment variables. When the server is started from the IDE, the environment variables are set to the appropriate project output locations. Using such variables enables you to associate the server with more than one project at the same time, or change associated projects without requiring changes to the server.

The variables enable the enterprise server to locate project output files based on the Output settings for the currently associated project(s); therefore, no changes are required when the enterprise server is associated with another project. Also, if you change the configuration within the currently associated project (for example, from Debug to Release), the new location for the project output is used, without any changes necessary. You can also append project-specific values to theses variables, separating each value with a semi-colon.

The variables are:
IDE_LOADLIB | The location for the Assembler, COBOL and PL/I application files
IDE_MODPATH | The location for MFS and BMS .mod files
IDE_IMSGENPATH | The location for IMS gen output
IDE_IMSDATA | The location for IMS databases
IDE_IMSCONFIG | The location of IMS config output
Note: There is currently no template for a PL/I-configured enterprise server.
Parent topic: Using Enterprise Server from within the IDE


Using Server Explorer with Enterprise Server

Server Explorer is an Eclipse view that enables you to connect to servers, as well as view and access their resources. For example, you can connect to, view and access the following resources:

  • Data Connections
  • Servers
  • Event Logs
  • Services

In your COBOL development system, you can also view and access a Micro Focus server.

From Server Explorer you can:

  • Connect to a Micro Focus server and check which enterprise servers are running
  • Start and stop Micro Focus enterprise servers
  • Create or delete Micro Focus enterprise servers
  • Run and monitor Mainframe Subsystem applications
  • Access the enterprise server administration facilities

If Server Explorer is not displayed, click Window > Show View > Other > Micro Focus > Server Explorer.

  • To access Enterprise Server Administration
  • To export an enterprise server instance
  • To import an enterprise server
  • To associate an enterprise server with a Mainframe Subsystem application
  • To connect to a remote enterprise server
  • To create a new enterprise server
  • To delete an enterprise server
  • To display an enterprise server log inside the IDE
  • To set a run-time environment variable
  • To submit a JCL file
  • To show the JCL catalog
  • To show the JCL spool queues
  • To start, stop, or restart an enterprise server from the IDE
Parent topic: Using Enterprise Server from within the IDE
Related information
Using from within the IDE
Enterprise Server Integration with the IDE


To access Enterprise Server Administration

Enterprise Server Administration is the management console in which you manage enterprise server instances configured on a particular directory server.

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.
  1. In Server Explorer, right-click the host server.
  2. Select Open Administration Page from the context menu.
Parent topic: Using Server Explorer with Enterprise Server
Related tasks
Accessing the ESMAC User Interface
Related information
Accessing the Enterprise Server Administration UI


To export an enterprise server instance

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

You can export the definition of an enterprise server instance from Enterprise Developer into a single XML file or as a set of files packaged as a .zip archive. You can transfer the XML or .zip file to other machines and import the server into other instances of Enterprise Developer.

To export an enterprise server instance:

  1. In Server Explorer, right-click the server you want to export and click Export Server.

    This starts the Export Server dialog box which shows the following details for exporting the server:

    Server name
    The server name as it appears in Server Explorer.
    Work location
    Specify the location where the server definition file will be saved.
    Verbose output
    Check this to view detailed information in the Output window during the server export.
    Export all CICS resources entries
    Check this to export all CICS resource definitions defined in Enterprise Server installed on the machine.

    If this is not checked, only the CICS resource definitions associated with the SIT of the current server will be exported into the server definition file.

    Create zip file
    Check this to export the server definition file as a .zip archive that contains a number of files.

    If this is not checked, the server definition file will be saved in XML format.

  2. Specify the required details and click OK.
Parent topic: Using Server Explorer with Enterprise Server


To import an enterprise server

You can import an enterprise server instance into Enterprise Server from within Enterprise Developer. You need to have the server definition files (either in XML format or packaged as a .zip archive) exported from another instance of Enterprise Developer.

  1. In Server Explorer, right-click localhost under Micro Focus Server and click Import Server.

    This starts the Import Server dialog box in which you can specify the following details:

    Import server definition file
    Specify the server definition file (either in XML format or a .zip archive) which was previously exported from Enterprise Developer.
    Verbose output
    Check this to view detailed information in the Output window during the server import.
  2. Browse to and select a server definition file to import and click OK.

    This imports the server into Enterprise Server. The IDE automatically displays it under localhost in Server Explorer.

Parent topic: Using Server Explorer with Enterprise Server


To associate an enterprise server with a Mainframe Subsystem application

You can associate a particular project with only one enterprise server at a time. One enterprise server can be associated with more than one project.

You can also associate an enterprise server with multiple projects as part of the process of creating a new enterprise server.

  1. Ensure that your project is open.
  2. In Server Explorer, right-click the enterprise server with which to associate your project.
  3. Click Associate with project > your project .
Alternatively:
  1. Select the project in COBOL Explorer.
  2. Change the directory server and server name values in the Properties view. If the Properties view isn't open in the IDE, click Window > Show View > Properties.
Parent topic: Using Server Explorer with Enterprise Server


To connect to a remote enterprise server

In order to connect to a remote enterprise server, you first need to set up a new connection to the appropriate directory server.

  1. Right-click anywhere in the Server Explorer view and select New > Directory Server Connection.
  2. Specify the remote machine in one of the following ways:
    • Click Name and enter the name of the host
    • Click Server Address and enter the IP address of the host in IPv4 format
  3. Specify a port number.
    Note: By default, Server Explorer displays the group of available enterprise servers on your local machine accessible on port 86. Contact the remote machine Administrator to determine the port number of the remote machine.
  4. Click Finish. A list of enterprise servers available on the remote machine is added to Server Explorer.
Parent topic: Using Server Explorer with Enterprise Server


To create a new enterprise server

You can only create enterprise server instanceenterprise server regions on your local machine.

  1. Right-click anywhere in the Server Explorer view and select New > Other > Micro Focus COBOL > Enterprise Server.
  2. Enter a name in the Name field.
  3. Check the 64-bit check box if you need to create a 64-bit server.
  4. Click Browse to the right of the Template field, then navigate to the folder that stores enterprise server template XML files.

    By default, this is the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates folder. The templates supplied in this folder are the basis for enterprise servers, with the appropriate Mainframe Subsystem Support and CICS, Job Entry Subsystem, or IMS support enabled. For applications that need an enterprise server to run but do not use Mainframe Subsystem Support you need to use the ESTemplate.xml template. You can create additional templates by exporting an active MFDS process repository using the mfds command. See the mfds topic for more information.

  5. Select a template and click Open.
  6. In the Associate with pane, select the projects to associate with the server.
  7. Click Finish.

    The new enterprise server is created and associated with the selected projects.

Parent topic: Using Server Explorer with Enterprise Server


To delete an enterprise server

You can only delete servers that are on your local machine.

  1. In Server Explorer, expand localhost under Micro Focus Servers.
  2. Right-click the server you want to delete, and then click Delete.
  3. Click Yes to confirm deletion.
Parent topic: Using Server Explorer with Enterprise Server


To display an enterprise server log inside the IDE

You can view the information from the server logs in the IDE inside the Console view. The following logs are available:

  • General log showing information about creating, starting or stopping of an enterprise server - the log appears in a separate console, Enterprise Server: Local/ServerName within the Console view.
  • Enterprise Server console log for each individual server instance (only available for local servers) - a separate console opens within the Console view for each server instance.

To display the general server log:

  • When you create, start or stop a server, the information from the general log is displayed automatically within the Console view.

To display the Enterprise Server console log for a server instance:

  1. Open the Server Explorer view in the IDE.
  2. Expand the list of servers.
  3. Right-click the enterprise server whose log you would like to see, and click Show Console Log.

    This opens the Console view and loads the output from the console log for the server in it.

    As you are using the server, all diagnostic messages from the log file will continue to appear in the Console view.

As you continue to work on your projects, the Console view continues to display various messages such as details from building your projects. To redisplay the general server log:

  • Click the drop-down arrow of the Display Selected Console button ( [image]) in the Output window, and click Enterprise Server: Local/ServerName .

To redisplay the console log for a server:

  • Click the drop-down arrow of the Display Selected Console button ( [image]) in the Output window, and click Enterprise Server Console Log: Local/ServerName to redisplay the Enterprise Server console log.
Parent topic: Using Server Explorer with Enterprise Server


To set a run-time environment variable

Restriction: This topic applies to Windows environments only.
  1. From the Application Explorer view, right-click a Web service; then select Web Service Properties.
  2. Check Enable Enterprise Server run-time environment.
  3. Click Configure Enterprise Server Run-time Environment.
  4. Expand Run-time Configuration; then click Environment Variables.
  5. Click Add.
  6. In the Variable field, type the name of the variable.
  7. In the Value field, type the value for the variable.
  8. Click OK. This populates the environment variables list and sets the environment variable for Enterprise Server to use at runtime for the selected service only.
  9. Click OK to close the Enterprise Server Run-time Configuration dialog box.
Note: To set a global environment variable in Enterprise Server, see To Set Environment Variables from the User Interface for more information.
Parent topic: Using Server Explorer with Enterprise Server
Parent topic: Manage IMTK Projects


To submit a JCL file

  1. Associate the enterprise server with your project.
  2. Right-click the .jcl file in COBOL Explorer.
  3. Click Submit to Enterprise Server.

    Alternatively, select the file in COBOL Explorer, press Ctrl+Shift+S, then release the keys and press J.

    If the enterprise server is not running, you are prompted to start it.

Parent topic: Using Server Explorer with Enterprise Server
Related concepts
JCL Support Tasks
Related information
To show the JCL catalog
To show the JCL spool queues


To show the JCL catalog

To view catalog, the enterprise server has to be started.

  1. Right-click the enterprise server in Server Explorer.
  2. Click Show catalog. You might have to refresh the server list if this option is not immediately available.
Parent topic: Using Server Explorer with Enterprise Server
Related concepts
JCL Support Tasks
Related information
To submit a JCL file
To show the JCL spool queues


To show the JCL spool queues

To view the spool queues, the enterprise server has to be started.

  1. Right-click the enterprise server in Server Explorer.
  2. Click Show spool. You might have to refresh the server list if this option is not immediately available.
Parent topic: Using Server Explorer with Enterprise Server
Related concepts
JCL Support Tasks
Related information
To submit a JCL file
To show the JCL catalog


To start, stop, or restart an enterprise server from the IDE

  1. In Server Explorer, right-click your enterprise server.
  2. Choose the appropriate option from the context menu.
    A security dialog box might appear. If the server you are starting has no security set, click OK to continue. Otherwise, select Server is secured and enter the credentials.
    Note: If the server is local and unsecured, then the system will use the casstart command to start the enterprise server, thereby using the current user's credentials. Otherwise, the system will use Directory Services (MFDS) to start the server, and use the "SYSTEM" user ID.
    You can choose to store these connection settings to skip this step in the future when starting, stopping, or restarting the server, or submitting a JCL job.

    To clear saved connection settings, right-click your enterprise server in Server Explorer and click Clear credentials.

    You can see the progress of the command in the console if you have enabled Show Local Console for your enterprise server in Enterprise Server Administration.

Parent topic: Using Server Explorer with Enterprise Server


Modern Development Practices

This section of the documentation contains information that is relevant if you are using Enterprise Developer 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 Enterprise Developer with other key components of the process.

  • Using Enterprise Developer in Modern Application Development
  • Using Enterprise Developer with Jenkins
  • Enterprise Developer Build Tools for Windows
  • Using Enterprise Developer with Docker
Parent topic: Micro Focus Enterprise Developer 4.0 for Eclipse


Using Enterprise Developer 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 Enterprise Developer 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
Related information
Introduction to Enterprise Developer Build Tools for Windows
Using Enterprise Developer Build Tools for Windows


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 Enterprise Developer in Modern Application Development
Related tasks
Using Enterprise Developer 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 Enterprise Developer 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
Related reference
Agile Manifesto: Manifesto for Agile Software Development
DevSecOps: What is DevSecOps?
Micro Focus Enterprise DevOps
TechRepublic: Understanding the pros and cons of the Waterfall Model of software development
The Agile Admin: What is DevOps?
Wikipedia: Definition of the waterfall model


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
Related information
Agile Methods
Continuous Integration
Continuous Delivery
Continuous Improvement


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 Enterprise Developer 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
Related reference
Manifesto for Agile Software Development
Related information
Agile Development Workflow
Agile Development and Micro Focus Development Tools
Key Concepts in Modern Application Development


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
Related information
Agile Development and Micro Focus Development Tools
Introduction to 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 Enterprise Developer to produce a deliverable product package, if required.

    When using Enterprise Developer, developers can use the complete array of analysis, intelligence and reporting tools provided by Enterprise Analyzer to quickly gain a full understanding of the applications they are working on. Integration between Rhythm and Enterprise Developer means developers can easily work on code changes and keep Rhythm's status information up to date at the same time.

    For mainframe development, using Enterprise Developer in conjunction with Enterprise Sync (another product from the Micro Focus Enterprise suite) enables you to replicate your mainframe source code to a distributed software configuration management platform, greatly increasing the effectiveness of your parallel application development.

    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.

  • Enterprise Analyzer

    Micro Focus Enterprise Analyzer delivers a wide array of tools and content to enable 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 Enterprise 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.

  • Enterprise Developer

    Micro Focus Enterprise Developer provides an integrated development environment (IDE) that streamlines mainframe COBOL and PL/I development activities. This toolset provides access, flexibility, and extensibility to modern technologies through fast integration and remote development capability.

    The following features of Enterprise Developer make it an invaluable part of the Agile development process:
    • Highly-compatible subsystem support (including CICS, IMS, DB2 and JES) means that you can be confident that the code you write using Enterprise Developer will run as expected on the mainframe.
    • Integration with SCC-compliant source code control systems to enable you to work seamlessly with your source code.
    • Integration into Eclipse 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 Enterprise Developer 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.
    • Wait for attachment enables you to attach the debugger only when a particular piece of code is executed.
    • Integration with Micro Focus Rhythm means that you can navigate and update your sprint backlog without even having to leave Eclipse.
    • 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.
  • Enterprise Sync

    Micro Focus Enterprise Sync integrates with Enterprise Developer to enable faster and more efficient parallel development. Replicating your mainframe source code on a distributed platform lets you take full advantage of the huge range of modern GUI-based tooling that is available to help you to adopt a modern application development process.

    Using Enterprise Sync, changes made to your distributed source control are synchronized automatically with your mainframe software change management system, keeping your mainframe application source code as the primary system of record and ensuring the integrity of your software change and configuration management processes.

  • 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 Enterprise Developer, as well as with third-party issue-tracking, version control and requirements management tools.

Parent topic: Agile Methods
Related reference
Micro Focus: Atlas data sheet
Micro Focus: Atlas online help
Micro Focus: Enterprise Analyzer data sheet
Micro Focus: Enterprise Analyzer online help
Micro Focus: Enterprise Developer data sheet
Micro Focus: Enterprise Sync data sheet
Micro Focus: Enterprise Sync online help
Micro Focus: Rhythm data sheet
Micro Focus: Rhythm online help
Related information
Agile Development Workflow
Introduction to Agile Methods
COBOL Application, COBOL Attach to Process, and COBOL Wait for Application Attachment
Debugging Features and Techniques in Eclipse
Debugging Using a Core Dump
Debugging Using a Live Recording
Debugging Using a Remote Machine
Mainframe Subsystem Support Developer Introduction
The Consolidated Tracing Facility
The Micro Focus Unit Testing Framework


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 Enterprise Developer 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 Enterprise Developer with Jenkins, see Using Enterprise Developer with Jenkins.

Parent topic: Continuous Integration
Related information
Continuous Integration Workflow
Continuous Integration and Micro Focus Development Tools
Key Concepts in Modern Application Development
Using Enterprise Developer with Jenkins


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 Enterprise Developer with Jenkins.

Parent topic: Continuous Integration
Related information
Continuous Integration and Micro Focus Development Tools
Introduction to Continuous Integration
Using Enterprise Developer with Jenkins


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 Enterprise Developer to check out code into their private workspaces. They then make their changes and test them locally using Enterprise Developer's unit testing features.

    This diagram illustrates the use of ChangeMan ZMF as the source code control system but you are not limited to using only that product. Enterprise Developer works with any SCC-compliant source code control system, so you can work seamlessly in Enterprise Developer 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.

    For mainframe development, using Enterprise Developer in conjunction with Enterprise Sync (another product from the Micro Focus Enterprise suite) enables you to replicate your mainframe source code to a distributed software configuration management platform, greatly increasing the effectiveness of your parallel application development.

  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 Enterprise Developer, 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 Enterprise Test 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 Enterprise Developer 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 Enterprise Developer 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:

  • ChangeMan ZMF

    Micro Focus ChangeMan ZMF is a comprehensive, automated change management system for reliably implementing mainframe software changes from development to testing to production, and treats change management as a business issue by giving key stakeholders visibility into the release process. ChangeMan ZMF protects your corporate assets and helps you get more done in less time.

  • Enterprise Analyzer

    Micro Focus Enterprise Analyzer delivers a wide array of tools and content to enable 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 Enterprise 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.

  • Enterprise Developer

    Micro Focus Enterprise Developer provides an integrated development environment (IDE) that streamlines mainframe COBOL and PL/I development activities. This toolset provides access, flexibility, and extensibility to modern technologies through fast integration and remote development capability.

    Enterprise Developer includes the following features that make it a great fit for using in your CI process:

    • Support for Apache Ant 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 Enterprise Developer IDE.
    • Integration into an extensible IDE enables you to use a range of third-party functionality to work with different CI servers.
    • Highly-compatible subsystem support (including CICS, IMS, DB2 and JES) means that you can be confident that the code you write using Enterprise Developer will run as expected on the mainframe.
    • Integration with SCC-compliant source code control systems to enable you to work seamlessly with your source code.
    • Integration into Eclipse 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 Enterprise Developer 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.
    • Wait for attachment enables you to attach the debugger only when a particular piece of code is executed.
    • Integration with Micro Focus Rhythm means that you can navigate and update your sprint backlog without even having to leave Eclipse.
    • 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.
  • Enterprise Sync

    Micro Focus Enterprise Sync integrates with Enterprise Developer to enable faster and more efficient parallel development. Replicating your mainframe source code on a distributed platform lets you take full advantage of the huge range of modern GUI-based tooling that is available to help you to adopt a modern application development process.

    Using Enterprise Sync, changes made to your distributed source control are synchronized automatically with your mainframe software change management system, keeping your mainframe application source code as the primary system of record and ensuring the integrity of your software change and configuration management processes.

  • Enterprise Test Server

    Micro Focus Enterprise Test Server is an IBM mainframe application test environment on Windows. It enables you to confidently test mainframe application change on scalable, low-cost commodity hardware, and expands your test capacity to scale to meet the delivery timelines and quality standards driven by today's business requirements.

    An example of a way in which Enterprise Test Server can simplify your testing is the ability to export and import execution environments. Once you have set up an Enterprise Test 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 Enterprise Test Server environment such as region definitions, locations of data files, and settings of environment variables. After exporting the definition you can then import it to be used during your testing, ensuring that the Enterprise Test Server environment you use in your testing is exactly the same environment as the one you know to be correct.

Parent topic: Continuous Integration
Related reference
Micro Focus: Ant User Guide
Micro Focus: ChangeMan ZMF data sheet
Micro Focus: Enterprise Analyzer data sheet
Micro Focus: Enterprise Analyzer online help
Micro Focus: Enterprise Developer data sheet
Micro Focus: Enterprise Sync data sheet
Micro Focus: Enterprise Sync online help
Micro Focus: Enterprise Test Server data sheet
Micro Focus: Enterprise Test Server online help
Related information
Continuous Integration Workflow
Introduction to Continuous Integration
COBOL Application, COBOL Attach to Process, and COBOL Wait for Application Attachment
Debugging Features and Techniques in Eclipse
Debugging Using a Core Dump
Debugging Using a Live Recording
Debugging Using a Remote Machine
Including Code Analysis in a Continuous Integration Process
Mainframe Subsystem Support Developer Introduction
The Consolidated Tracing Facility
The Micro Focus Unit Testing Framework
To Build a Project Using Apache Ant
To export an enterprise server instance
To import an enterprise server
Using Enterprise Developer with Jenkins
Using Enterprise Developer Build Tools for Windows


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 Enterprise Developer 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
Related reference
Continuous Delivery: What is Continuous Delivery?
Related information
Continuous Delivery Workflow
Continuous Delivery and Micro Focus Development Tools
Key Concepts in Modern Application Development


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 Enterprise Developer with Jenkins.

Parent topic: Continuous Delivery
Related information
Continuous Delivery and Micro Focus Development Tools
Introduction to Continuous Delivery
Continuous Integration Workflow
Using Enterprise Developer with Jenkins


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 Enterprise Developer to check out code into their private workspaces. They then make their changes and test them locally using Enterprise Developer's unit testing features.

    This diagram illustrates the use of ChangeMan ZMF as the source code control system but you are not limited to using only that product. Enterprise Developer works with any SCC-compliant source code control system, so you can work seamlessly in Enterprise Developer 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.

    For mainframe development, using Enterprise Developer in conjunction with Enterprise Sync (another product from the Micro Focus Enterprise suite) enables you to replicate your mainframe source code to a distributed software configuration management platform, greatly increasing the effectiveness of your parallel application development.

  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 Enterprise Developer, 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 Enterprise Test 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 Enterprise Developer 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.

    For mainframe-hosted applications your testing at this stage should include testing your changes on the mainframe in addition to the testing done on your Windows workstations.

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

  • ChangeMan ZMF

    Micro Focus ChangeMan ZMF is a comprehensive, automated change management system for reliably implementing mainframe software changes from development to testing to production, and treats change management as a business issue by giving key stakeholders visibility into the release process. ChangeMan ZMF protects your corporate assets and helps you get more done in less time.

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

  • Enterprise Analyzer

    Micro Focus Enterprise Analyzer delivers a wide array of tools and content to enable 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 Enterprise 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.

  • Enterprise Developer

    Micro Focus Enterprise Developer provides an integrated development environment (IDE) that streamlines mainframe COBOL and PL/I development activities. This toolset provides access, flexibility, and extensibility to modern technologies through fast integration and remote development capability.

    Enterprise Developer includes the following features that make it particularly suitable for using in your continuous delivery process:

    • Support for Apache Ant 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 Enterprise Developer IDE.
    • Integration into an extensible IDE enables you to use a range of third-party functionality to work with different CI servers.
    • Highly-compatible subsystem support (including CICS, IMS, DB2 and JES) means that you can be confident that the code you write using Enterprise Developer will run as expected on the mainframe.
    • Integration with SCC-compliant source code control systems to enable you to work seamlessly with your source code.
    • Integration into Eclipse 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 Enterprise Developer 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.
    • Wait for attachment enables you to attach the debugger only when a particular piece of code is executed.
    • Integration with Micro Focus Rhythm means that you can navigate and update your sprint backlog without even having to leave Eclipse.
    • 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.
  • Enterprise Sync

    Micro Focus Enterprise Sync integrates with Enterprise Developer to enable faster and more efficient parallel development. Replicating your mainframe source code on a distributed platform lets you take full advantage of the huge range of modern GUI-based tooling that is available to help you to adopt a modern application development process.

    Using Enterprise Sync, changes made to your distributed source control are synchronized automatically with your mainframe software change management system, keeping your mainframe application source code as the primary system of record and ensuring the integrity of your software change and configuration management processes.

  • Enterprise Test Server

    Micro Focus Enterprise Test Server is an IBM mainframe application test environment on Windows. It enables you to confidently test mainframe application change on scalable, low-cost commodity hardware, and expands your test capacity to scale to meet the delivery timelines and quality standards driven by today's business requirements.

    An example of a way in which Enterprise Test Server can simplify your testing is the ability to export and import execution environments. Once you have set up an Enterprise Test 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 Enterprise Test Server environment such as region definitions, locations of data files, and settings of environment variables. After exporting the definition you can then import it to be used during your testing, ensuring that the Enterprise Test Server environment you use in your testing is exactly the same environment as the one you know to be correct.

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

Parent topic: Continuous Delivery
Related reference
Micro Focus: Ant User Guide
Micro Focus: ChangeMan ZMF data sheet
Micro Focus: Deployment Automation data sheet
Micro Focus: Enterprise Analyzer data sheet
Micro Focus: Enterprise Analyzer online help
Micro Focus: Enterprise Developer data sheet
Micro Focus: Enterprise Sync data sheet
Micro Focus: Enterprise Sync online help
Micro Focus: Enterprise Test Server data sheet
Micro Focus: Enterprise Test Server online help
Micro Focus: Release Control data sheet
Micro Focus: Silk Central data sheet
Micro Focus: Silk Test data sheet
Related information
Continuous Delivery Workflow
Introduction to Continuous Delivery
COBOL Application, COBOL Attach to Process, and COBOL Wait for Application Attachment
Continuous Integration and Micro Focus Development Tools
Debugging Features and Techniques in Eclipse
Debugging Using a Core Dump
Debugging Using a Live Recording
Debugging Using a Remote Machine
Including Code Analysis in a Continuous Integration Process
Mainframe Subsystem Support Developer Introduction
The Consolidated Tracing Facility
The Micro Focus Unit Testing Framework
To Build a Project Using Apache Ant
To export an enterprise server instance
To import an enterprise server
Using Enterprise Developer with Jenkins
Using Enterprise Developer Build Tools for Windows


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 Enterprise Developer 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 Enterprise Developer in Modern Application Development
Related reference
Agile Manifesto: Principles Behind the Agile Manifesto


Using Enterprise Developer with Jenkins

This section of the documentation contains information that you need to know to in order to use Enterprise Developer 3.0 in conjunction with Jenkins version 2.60.1. It includes information on what software you need to install, how to configure Enterprise Developer and Jenkins to get the most from them working together, and tips and guidance for using Enterprise Developer alongside Jenkins.

General information about using Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer
  • 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
Related information
Introduction to Enterprise Developer Build Tools for Windows
Using Enterprise Developer Build Tools for Windows


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

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 Enterprise Developer 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.
  • Enterprise Developer 3.0 for either Eclipse or Visual Studio - see the product's release notes for any software prerequisites.

    In a scenario where you have a master and a number of agent machines, Enterprise Developer must be installed on each agent machine. You can obtain Enterprise Developer from Micro Focus SupportLine.

  • Apache Ant 1.9.4 - this is required if you are working with COBOL applications created with Enterprise Developer 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 Enterprise Developer with Jenkins
Related reference
Apache Ant web site
Enterprise Developer 3.0 release notes
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 Enterprise Developer 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 Enterprise Developer development process.

  • Configuring Email Reporting
  • Using Sources from Source Control
  • Triggering Builds Automatically
  • Creating Environment Variables
  • Using Agents
Parent topic: Using Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Eclipse, the default source code control system check-out folder, the workspace directory, 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 Enterprise Developer's behavior that you need to configure to enable your Enterprise Developer 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 Enterprise Developer installed. In such configurations, it is useful to have the same Enterprise Developer configuration settings on all agents.

Micro Focus recommends that you install Enterprise Developer 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
  • Making mfant.jar Available to Enable Building
  • Specifying the Location of Linked Folders
Parent topic: Using Enterprise Developer with Jenkins


Setting up the Environment

In most cases, your Jenkins projects execute tasks in a command line environment and not inside the Enterprise Developer 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.

To configure the environment for applications created with Enterprise Developer for Eclipse:

  1. Ensure Enterprise Developer is installed on the machine you are going to use to build, test or analyze the COBOL sources.
  2. In Jenkins, go to the Build section of your project's configuration.
  3. Depending on the platform where your project executes, add either a Windows batch command (Windows) or a shell (UNIX) build step.
  4. Specify the following commands in the step, each one on a new line:
    1. (Windows) Invoke the Enterprise Developer setupenv.bat file to set the required environment variables:
      call "product-install-dir\setupenv.bat"

      (UNIX) Call the cobsetenv script:

      . product-install-dir/bin/cobsetenv

      This sets the following environment variables - COBDIR, PATH, CLASSPATH and LD_LIBRARY_PATH (or LIBPATH on AIX).

    2. Set the JAVA_HOME environment variable:
      • Windows:
        set JAVA_HOME=JDKInstallDir
      • UNIX:
        export JAVA_HOME=java-install-dir
export PATH=$PATH:java-install-dir/bin
    3. Specify the required Ant options:
      set ANT_OPTS=-Xmx1024m
Tip: If your projects execute any tasks on agent machines, you can set JAVA_HOME from the configuration page of the node for that machine.

See the rest of the Enterprise Developer product help for more command line options you can specify.

Tip: Optionally, you can create a file that includes all of the required environment variables and configure your project to use it. To do this, you first need to obtain a list of all environment variables that are set in Enterprise Developer:
  1. From an Enterprise Developer command prompt, execute the following command:
    cblpromp.exe -j

    This displays a list of the environment variables set for Enterprise Developer in the command prompt.

  2. Save the list to a file on your machine such as env.properties.
Tip: Next, configure your project to use the variables specified in this file:
  1. Install the Environment Injector plugin in Jenkins.
  2. In the configuration area of your project, navigate to the Build Environment section.
  3. Check Prepare an environment for the run.
  4. In the Properties File Path section, specify the full path to the env.properties file.
Parent topic: Using Jenkins to Build COBOL Applications
Related concepts
Example - Building COBOL Programs
Example - Integrating Code Analysis
Example - Running MFUnit Tests


Making mfant.jar Available to Enable Building

Eclipse COBOL project files, .cobolBuild, are Ant scripts that use a number of custom Micro Focus tasks defined in the mfant.jar file. Each Eclipse project has its own .cobolBuild file which you need to compile when building the application that they all form.

In order to build such projects with Jenkins, you need to specify the location of the mfant.jar file to Apache Ant using ant's -lib command line option. You need to specify this in the Build section of the Jenkins project's configuration:

  • Windows:
    call ant -lib "%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar" -f .cobolBuild

    UNIX:

    call ant -lib $COBDIR/lib/mfant.jar -f .cobolBuild
Parent topic: Using Jenkins to Build COBOL Applications


Specifying the Location of Linked Folders

If your COBOL applications developed in Enterprise Developer for Eclipse use linked folders, you need to specify their location in the Jenkins project's configuration in order for them to be available at build time.

To specify the location of linked folders:

  1. Establish the linked folders that your project is using. To do this:
    1. Build your application in Enterprise Developer.
    2. Check the console log and note the printLocations locations at the start of the console output.

      These are the locations of the linked folders.

  2. When adding the command for building the .cobolBuild file to the Jenkins project configuration, specify any linked folders using the following syntax:
    -Dlinkedfolder.folderName=folderLocation
Parent topic: Using Jenkins to Build COBOL Applications


Examples

  • Example - Building COBOL Programs
  • Example - Integrating Code Analysis
  • Example - Running MFUnit Tests
Parent topic: Using Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer samples (which is c:\users\Public\Documents\Micro Focus\Enterprise Developer\Samples\COBOL\AirportMFUnitDemo by default).

Example of Building COBOL Programs with an Eclipse Project

Before you create a Jenkins project, ensure that the following software is installed on the machine where you will build the sample:

  • Enterprise Developer for Eclipse
  • Apache Ant

To create a Jenkins project for building the sample:

  1. Create a new freestyle project.
  2. Configure the project to work with COBOL - see Setting up the Environment.
  3. In the Build section of the project's configuration, specify the command that will build your COBOL project:
    cd C:\Users\Public\Documents\Micro Focus\Enterprise Developer\Samples\Eclipse\cobol\AirportDemo
call ant -f .cobolProj
  4. Click Apply and then Save.
  5. Click Build to build the project.

See To Build a Project Using Apache Ant for some useful Ant options you can use to build your projects.

Parent topic: Examples
Related concepts
Example - Integrating Code Analysis
To Build a Project Using Apache Ant
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 Enterprise Developer.

Example with an Eclipse Project

Before you configure Jenkins, you need to do the following:

  • Ensure Enterprise Developer for Eclipse and Apache Ant are installed on the machine on which code analysis will be performed - see Software Requirements. You use Apache Ant to build and analyze COBOL projects.
  • Configure your COBOL projects for code analysis in Enterprise Developer. See Performing Code Analysis when Building a Project in the IDE for more information.

To integrate code analysis in Jenkins:

  1. Create a freestyle project.
  2. Configure the project to work with COBOL - see Setting up the Environment.
  3. In the Build section of the project's configuration, specify the command that will perform code analysis of your COBOL application:
    call ant -f .cobolBuild build.and.analyze -DanalysisFailOnError=true

    Where .cobolBuild is the Eclipse project file of the application you are going to analyze.

For example, the full set of commands for the Jenkins project might look similar to the following:

rem set the COBOL environment:
call "product-install-dir\SetupEnv.bat"
rem locate the mfant.jar file that includes the definitions of the Micro Focus Ant tasks for analyzing code, and build and analyze the application defined by the .cobolBuild project file:
call ant -lib "%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\mfant.jar" -f .cobolBuild build.and.analyze -DanalysisFailOnError=true

Where:

  • product-install-dir is the Enterprise Developer installation directory.
Tip:

  • See Performing Code Analysis from the Command Line for all available code analysis options.

  • You can use various plugins to customize the reports from code analysis. For example, you can install the free Log Parser Plugin to provide better formatting of the reports.
Parent topic: Examples
Related concepts
Example - Building COBOL Programs
Performing Code Analysis from the Command Line
Performing Code Analysis when Building a Project in the IDE
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.

Enterprise Developer for Eclipse must be installed on the machine where you will run the MFUnit tests. You are going to use one of the samples stored in the \COBOL\AirportMFUnitDemo subfolder in the location of the Enterprise Developer samples (%PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples).

  1. Create a Jenkins project.
  2. Configure the project to work with COBOL - see Setting up the Environment.
  3. In the Build section of the project's configuration, enter the following commands to copy the samples files to the workspace:
    • Windows:
      copy "C:\Users\Public\Documents\Micro Focus\Enterprise Developer\Samples\mfunit\*" %WORKSPACE% cd %WORKSPACE%
call examples.bat
    • UNIX:
      cp /opt/microfocus/xxxxxxxx cd $WORKSPACE examples.sh
  4. Build your project.

    After the project build completes, there is a blue icon next to the project on the Jenkins Home page which indicates that the build was successful. This, however, is not correct.

  5. Check the project's console output.

    In the text output you'll see that some tests failed even though the blue indicator in the previous step suggests that everything ran successfully:

    Micro Focus COBOL - mfurun Utility
Unit Testing Framework for Windows/Native/32

Options : verbose=true,process=separate,junit=true,printfile=true
Fixture filename : MFUTASCI.dll
 Preparing test case : MFUTASCI
 Executing test case : MFUTASCI
 Completed test case : MFUTASCI - Failed
 Generating junit xml : TEST-MFUTASCI.xml
 Generating report : MFUTASCI-report.txt

Test Run Summary
 Overall Result            : Failed
 Tests run                 : 1
 Tests passed              : 0
 Tests failed              : 1
 Total execution time      : 3

    Although the tests ran to completion, there were a number of test failures that should have caused this build to fail.

    You now need to enable test reporting.

  6. In the project's configuration page, navigate to the Post-Build actions section.
  7. Click Add post-build action > Publish Junit test result report.
  8. In Test report XMLs, enter *.xml and then save the configuration.
  9. Build the project again.

    Note that this time the icon indicating status has turned yellow. This indicates that the build ran to completion but there were some test failures.

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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer IDE and check whether any errors are reported.
Parent topic: Troubleshooting
Related concepts
Configuring Email Reporting


Enterprise Developer Build Tools for Windows

Enterprise Developer Build Tools for Windows is a separately-installable component of Enterprise Developer that has been designed to be used in environments where you want to work with your COBOL and PL/I projects but you don't want the overheads associated with the Eclipse IDE.

The following sections introduce Enterprise Developer Build Tools for Windows and show you what you need to do to use it and get the best from it.

  • Introduction to Enterprise Developer Build Tools for Windows
  • Prerequisites for Using Enterprise Developer Build Tools for Windows
  • Licensing Considerations
  • Installing Enterprise Developer Build Tools for Windows
  • Restrictions when Using Enterprise Developer Build Tools for Windows
  • Using Enterprise Developer Build Tools for Windows
Parent topic: Modern Development Practices


Introduction to Enterprise Developer Build Tools for Windows

Enterprise Developer Build Tools for Windows is a separately-installable component of Enterprise Developer that has been designed to be used in environments where you want to work with your COBOL and PL/I projects but you don't want the overheads associated with the Eclipse IDE. Examples of such environments are Docker containers and continuous integration (CI) or continuous delivery (CD) systems.

When using Enterprise Developer in a traditional development environment you would access most, if not all, of its functionality through the IDE.

When working with COBOL projects in a containerized environment or a CI system you will want to carry out your tasks by running commands from scripts, batch files or Dockerfiles rather than from the IDE. You still need to be able to build, run, and debug your COBOL projects, but you want to do these things using commands rather than an IDE.

Enterprise Developer Build Tools for Windows includes all of the functionality that is available in Enterprise Developer for building and running COBOL and PL/I projects but it does not include an IDE, giving the following advantages when you use Enterprise Developer Build Tools for Windows rather than Enterprise Developer:

  • A significantly smaller footprint.

    The amount of space required to install Enterprise Developer Build Tools for Windows is much less than the space required for Enterprise Developer because Enterprise Developer Build Tools for Windows doesn't include an IDE (or the support for one) and other components such as online help.

  • A quicker, easier installation process.

    Installing Enterprise Developer Build Tools for Windows is quick and straightforward due to its smaller footprint, fewer prerequisites and dependencies, and lack of installation options when compared to Enterprise Developer.

Note: As its name indicates, Enterprise Developer Build Tools for Windows is only for use on Windows. If you need to work with COBOL projects in a containerized or CI environment on UNIX or Linux you need to use Enterprise Developer UNIX Components rather than Enterprise Developer Build Tools for Windows.
Parent topic: Enterprise Developer Build Tools for Windows
Related information
Installing Enterprise Developer Build Tools for Windows
Using Enterprise Developer in Modern Application Development
Using Enterprise Developer with Jenkins
Using Enterprise Developer with Docker


Prerequisites for Using Enterprise Developer Build Tools for Windows

This topic lists any additional software that you need to be able to use Enterprise Developer Build Tools for Windows.

Apache Ant

Apache Ant version 1.7.1 or later is required if you will be using Enterprise Developer Build Tools for Windows to perform build operations using Eclipse project files. You can download Apache Ant from the Apache Ant project's Binary Distributions page.

Parent topic: Enterprise Developer Build Tools for Windows
Related reference
Apache Ant Project - Binary Distributions Page


Licensing Considerations

Enterprise Developer Build Tools for Windows requires the same license as Enterprise Developer so you need to ensure that you have enough licenses to cover your use of both Enterprise Developer Build Tools for Windows and Enterprise Developer.

For example, if you have purchased six development licenses and install one instance of Enterprise Developer Build Tools for Windows you can install Enterprise Developer (or Enterprise Developer Build Tools for Windows) on a maximum of five other machines.

Parent topic: Enterprise Developer Build Tools for Windows


Installing Enterprise Developer Build Tools for Windows

To install Enterprise Developer Build Tools for Windows:

  1. Read the following sections of this documentation to minimize the chances of encountering issues during or after the installation process:
    • Licensing Considerations
    • Prerequisites for using Enterprise Developer Build Tools for Windows
    • Restrictions when using Enterprise Developer Build Tools for Windows
  2. Run the edbt_40.exe file and follow the wizard instructions to complete the installation.
Note:

edbt_40.exe can take a number of parameters, enabling you to specify a number of different types of installation. Examples are as follows:

  • Silent Installation
    • Format: edbt_40.exe /quiet
    • Summary: Full installation, but the components are installed non-interactively with no user interface, using default options and directories.
  • Modified Silent Installation
    • Format: edbt_40.exe /quiet InstallFolder=d:\otherdirectory
    • Summary: Full installation, but the components are installed non-interactively with no user interface, and Enterprise Developer Build Tools for Windows is installed to d:\otherdirectory.
To see all of the available parameters, execute the following from the command line:
edbt_40.exe /?
Parent topic: Enterprise Developer Build Tools for Windows
Related information
Licensing Considerations
Prerequisites for Using Enterprise Developer Build Tools for Windows
Restrictions when Using Enterprise Developer Build Tools for Windows


Restrictions when Using Enterprise Developer Build Tools for Windows

The following list describes elements of functionality of Enterprise Developer Build Tools for Windows that you should be aware of before installing it:

  • You cannot install Enterprise Developer Build Tools for Windows on the same machine as Enterprise Developer, Visual COBOL, or Visual COBOL Build Tools for Windows.
  • Installing Enterprise Developer Build Tools for Windows does not install any documentation. Instead, full information on how to use Enterprise Developer Build Tools for Windows is included in this documentation for Enterprise Developer. The documentation that describes how to use Enterprise Developer Build Tools for Windows includes links to the sections of documentation for Enterprise Developer that are relevant to Enterprise Developer Build Tools for Windows.
  • To debug a COBOL application that is running in Enterprise Developer Build Tools for Windows you need to use remote debugging. See Debugging using a remote machine for information on using remote debugging with Enterprise Developer Build Tools for Windows.
Parent topic: Enterprise Developer Build Tools for Windows
Related information
Debugging Using a Remote Machine


Using Enterprise Developer Build Tools for Windows

Enterprise Developer Build Tools for Windows enables you to perform all of the compiling, linking, building, and running operations that you can perform from a command prompt in Enterprise Developer.

Enterprise Developer Build Tools for Windows includes exactly the same support for mainframe subsystems that is included in Enterprise Developer. This means that if you have used Enterprise Developer to create applications that make use of features such as CICS, IMS, JCL, Assembler or PL/I, using Enterprise Developer Build Tools for Windows to compile, link, build, and run those applications will have exactly the same effect as if you had used Enterprise Developer.

Because Enterprise Developer Build Tools for Windows does not use the Eclipse IDE you cannot use Eclipse to debug a COBOL application with Enterprise Developer Build Tools for Windows in the way that you would with Enterprise Developer. Instead, Enterprise Developer Build Tools for Windows's lack of an IDE makes it perfectly suited for use in Docker containers, a CI/CD environment, or any other automated build and test system.

To debug a COBOL application in Enterprise Developer Build Tools for Windows you use the remote development functionality offered in Enterprise Developer to attach to and debug the application that is running in Enterprise Developer Build Tools for Windows.

The following sections summarize the different commands you use in Enterprise Developer Build Tools for Windows to carry out these operations, and provide links to other parts of this documentation where you can find detailed information on the commands available in Enterprise Developer Build Tools for Windows.

  • Starting an Enterprise Developer Build Tools for Windows Command Prompt
  • Building Using Enterprise Developer Build Tools for Windows
  • Compiling and Linking Using Enterprise Developer Build Tools for Windows
  • Running Using Enterprise Developer Build Tools for Windows
  • Debugging Using Enterprise Developer Build Tools for Windows
  • Deploying Using Enterprise Developer Build Tools for Windows
Parent topic: Enterprise Developer Build Tools for Windows
Related information
Using Enterprise Developer with Docker
Using Enterprise Developer in Modern Application Development
Using Enterprise Developer with Jenkins


Starting an Enterprise Developer Build Tools for Windows Command Prompt

You start a command prompt for Enterprise Developer Build Tools for Windows in the same way that you start a command prompt for Enterprise Developer.

For more information see To start an Enterprise Developer command prompt and To start an Enterprise Developer command prompt as an administrator.

Parent topic: Using Enterprise Developer Build Tools for Windows
Related information
To start an Enterprise Developer command prompt as an administrator
To start an Enterprise Developer command prompt


Building Using Enterprise Developer Build Tools for Windows

To build a COBOL project you use Apache Ant.

You cannot create COBOL projects using Enterprise Developer Build Tools for Windows, so before you can build a COBOL project with Enterprise Developer Build Tools for Windows you must have created it with Enterprise Developer.

See To Build a Project Using Apache Ant for an overview of using Ant to build COBOL projects, or see the Micro Focus Ant User Manual for full details.

Parent topic: Using Enterprise Developer Build Tools for Windows
Related information
Creating COBOL Projects
To Build a Project Using Apache Ant
Micro Focus Ant User Manual


Compiling and Linking Using Enterprise Developer Build Tools for Windows

Compiling and linking are controlled by the cobol command and cbllink utility respectively, both of which operate in Enterprise Developer Build Tools for Windows in exactly the same way as they do in Enterprise Developer.

See Compiling from the Command Line and Linking from the Command Line for full information on how to use the cobol command and cbllink utility to compile and link your COBOL applications.

If you need to set Compiler directives that in Enterprise Developer you would have set from the IDE you will need to specify those in a alternative way. The different ways in which you can set Compiler directives are described in Setting Directives Outside the IDE.

Parent topic: Using Enterprise Developer Build Tools for Windows
Related information
Compiling from the Command Line (Windows)
Linking from the Command Line (Windows)
Setting Directives Outside the IDE


Running Using Enterprise Developer Build Tools for Windows

To run a COBOL program you simply enter the program's name (if the program has been linked to a system executable program) or use the run command (if it has not). Both of these actions behave in Enterprise Developer Build Tools for Windows in exactly the same way as they do in Enterprise Developer.

See Running an Application from the Command Line for full information on both of these methods of running a COBOL program in Enterprise Developer Build Tools for Windows.

Parent topic: Using Enterprise Developer Build Tools for Windows
Related information
Running an Application from the Command Line


Debugging Using Enterprise Developer Build Tools for Windows

Although you can't directly debug a COBOL application that is running in Enterprise Developer Build Tools for Windows it is a straightforward process to use Enterprise Developer to remotely debug an application that is running on Enterprise Developer Build Tools for Windows.

See Debugging Using a Remote Machine for detailed information on different ways in which you can use remote debugging with Enterprise Developer.

Parent topic: Using Enterprise Developer Build Tools for Windows
Related information
Debugging Using a Remote Machine


Deploying Using Enterprise Developer Build Tools for Windows

When using Enterprise Developer Build Tools for Windows you have the same deployment options available as when you use Enterprise Developer, so you can test the deployment of your applications in a containerized environment or a CI system taking advantages of the benefits of Enterprise Developer Build Tools for Windows.

See Deployment for full information on how to deploy your COBOL applications.

Parent topic: Using Enterprise Developer Build Tools for Windows
Related information
Deployment


Using Enterprise Developer with Docker

This section of the documentation contains information on how you can use Enterprise Developer with Docker to work with your COBOL and PL/I 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 Enterprise Developer that guide you through all the steps involved in creating Docker containers to work with COBOL and PL/I applications.

Note: The Docker information included in this documentation includes information for both Enterprise Developer for Eclipse and Enterprise Developer UNIX Components, although not all information is relevant to both of those products. Where information is relevant to one product but not the other, this is indicated.

Additionally, any references to Enterprise Developer Build Tools for Windows are not relevant to you if you are using Enterprise Developer UNIX Components and you can treat these references as if they were to Enterprise Developer UNIX Components. Any references to Enterprise Developer Build Tools for Windows that are not relevant to users of Enterprise Developer UNIX Components in any context are indicated.

  • Introduction to Docker
  • Benefits of Using Docker
  • Docker Terminology
  • Getting Ready to Use Enterprise Developer with Docker
  • Key Concepts When Using Docker with COBOL Applications
  • Building Images for COBOL Applications
  • Debugging COBOL Applications Running in Containers
  • Debugging PL/I Applications Running in Containers
  • Docker Demonstrations
Parent topic: Modern Development Practices
Related information
Introduction to Enterprise Developer Build Tools for Windows
Using Enterprise Developer Build Tools for Windows


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 Enterprise Developer with Docker
Related reference
Docker: Docker Overview
Docker: Docker Documentation
Related information
Benefits of Using Docker
Docker Terminology
Getting Ready to Use Enterprise Developer 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.

  • Performance

    Although virtual machines are an alternative to containers, the fact that containers do not contain an operating system (whereas virtual machines do) means that containers have much smaller footprints than virtual machines, are faster to create, and quicker to start.

  • Agility

    The portability and performance benefits offered by containers can help you make your development process more agile and responsive. Enhancing your continuous integration and continuous delivery processes to take advantage of containers and technology such as Enterprise Developer Build Tools for Windows makes it easier for you to deliver the right software at the right time. Enterprise Developer Build Tools for Windows is a component of Enterprise Developer which provides all of the functionality of Enterprise Developer to enable you to compile, build, and test COBOL code but without the overhead of an IDE.

    If you are using Enterprise Developer UNIX Components, because Enterprise Developer UNIX Components does not have an IDE you can include it in your containers, resulting in the same benefits that users of Enterprise Developer for Eclipse get by using Enterprise Developer Build Tools for Windows.

  • 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 Enterprise Developer with Docker
Related information
Introduction to Docker
Docker Terminology
Getting Ready to Use Enterprise Developer 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 Enterprise Developer with Docker
Related reference
Docker: Docker Documentation
Related information
Introduction to Docker
Benefits of Using Docker
Getting Ready to Use Enterprise Developer with Docker


Getting Ready to Use Enterprise Developer with Docker

This topic presents information to help you install Docker so that you can use it with Enterprise Developer. Before installing Docker see Docker Known Issues and Restrictions for information that might be relevant to your use of Docker.

For users of Enterprise Developer for Eclipse:

There are two editions of Docker: Community Edition (CE) and Enterprise Edition (EE). Docker Enterprise Edition is supported for use with Enterprise Developer only on Windows Server 2016 so if you are using Windows 10 you must install Docker Community Edition.

Installing Docker on Windows 10

Full information on installing Docker is contained in the Community Edition page on the Docker site.

Note:
  • You must enable Hyper-V in order to use Docker on Windows 10.
  • Once you have installed Docker you need to configure it to use Windows containers (rather than Linux containers, which is the default). To do this, ensure that Docker is running then right-click the Docker icon in your system tray and click Switch to Windows containers.

Installing Docker on Windows Server 2016

To install Docker Enterprise Edition on Windows Server 2016 use the following PowerShell commands:

Install-Module DockerMsftProvider -Force
Install-Package Docker -ProviderName DockerMsftProvider -Force

For users of Enterprise Developer UNIX Components:

There are two editions of Docker: Community Edition (CE) and Enterprise Edition (EE). Docker Enterprise Edition is not supported for use with Enterprise Developer 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 Enterprise Developer with Docker
Related reference
Docker: Docker Community Edition
Microsoft: Install Hyper-V on Windows 10
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 Enterprise Developer with Docker
Related reference
Using Docker with Pipeline
Related information
Building Images for COBOL Applications
Debugging COBOL Applications Running in Containers
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 Enterprise Developer 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
  • Make Use of Enterprise Developer Build Tools for Windows
  • 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
Enterprise Developer Build Tools for Windows
Key Concepts When Using Docker for COBOL Application Deployment
Building a Base Image Containing Enterprise Developer Build Tools for Windows
Building an Image Containing an Application to use with Enterprise Developer Build Tools for Windows
Docker Demonstrations
The CICS Docker Demonstration
The Docker Demonstration for the Enterprise Developer Base Image


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, on Windows, Enterprise Developer is provided as two base images. The smallest of the two is based on the microsoft/dotnet-framework image which does not have any build tools for .NET development but does include all relevant functionality for native COBOL development. The second, larger, image includes the extra build tools provided by the microsoft/dotnet-framework-build image (SDK). This image includes NuGet, .NET Framework profiles and File Tracker.

The images that include build tools all have the suffix -build in the repository name, which enables you to identify them as images ideally suited for building and testing.

Note: If you are using Enterprise Developer UNIX Components, the Enterprise Developer base image, for instance, 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 Enterprise Developer and recommends that you adopt the same sort of conventions.

For users of Enterprise Developer for Eclipse:

For example:

  • As described above, Microsoft provide microsoft/dotnet-framework and microsoft/dotnet-framework-build images and you can base your Enterprise Developer image on either of these images.

    By creating one base image for Enterprise Developer based on microsoft/dotnet-framework and another based on microsoft/dotnet-framework-build you can then switch between using them depending on whether you are working with native or managed COBOL applications.

    You could decide to use the -build version of the base image regardless of whether you need to use the managed COBOL features, but doing so would result in the inclusion of unnecessary files when working with native COBOL applications.

  • When creating the base images for Enterprise Developer you need to create a version that is specific to the bitism of the platform that it will be used on. To achieve this, the Docker demonstrations do the following:
    1. Create a generic base image. This is not specific to a particular bitism and will only be used to create other images that are platform-specific.
    2. Create images that based on the generic base image but are specific to 32-bit and 64-bit platforms.

      The bitisim is indicated in the images' tags. For example, the generic base image microfocus/edbuildtools:win_4.0 could have platform-specific images named microfocus/edbuildtools:win_4.0_x86 and microfocus/edbuildtools:win_4.0_x64.

For users of Enterprise Developer UNIX Components:

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/entdevhub:sles12sp3_4.0_x64 the interactive login image based on this image would be called microfocus/entdevhub:sles12sp3_4.0_x64_login.

Parent topic: Key Concepts When Using Docker for COBOL Application Development


Make Use of Enterprise Developer Build Tools for Windows

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

Enterprise Developer Build Tools for Windows is a component of Enterprise Developer which offers the same compilation, build, and execution functionality as Enterprise Developer but without the overhead of an IDE. Using Enterprise Developer Build Tools for Windows in a container gives you much of the functionality of Enterprise Developer but with a much smaller footprint that is well suited to working in containers.

The Docker demonstration to build the base image for Enterprise Developer uses Enterprise Developer Build Tools for Windows.

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 Enterprise Developer Build Tools for Windows.

    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 Enterprise Developer 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 Enterprise Server.
  2. At this stage you have two options:
    1. Use the Enterprise Developer 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 Enterprise Developer to create the executable files and the files that are required in order to debug the application. You then run your Enterprise Developer Build Tools for Windows 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 Enterprise Developer 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 Enterprise Developer and illustrate how to build a range of images to perform different tasks, from being used as a base image for running Enterprise Developer to debugging a sample CICS 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 Enterprise Developer Build Tools for Windows for a description of how to create a base image that includes Enterprise Developer.
  • Building an Image Containing an Application to use with Enterprise Developer Build Tools for Windows for a description of how to extend the Enterprise Developer base image with applications of your own that you can run and debug using Enterprise Developer.
  • The Docker Demonstration for the Enterprise Developer Base Image for a detailed look at the Docker demonstration files supplied with Enterprise Developer that show how to create a base image for Enterprise Developer Build Tools for Windows.
  • The CICS Docker Demonstration for a detailed look at how the Docker demonstration files supplied with Enterprise Developer extend the Enterprise Developer Build Tools for Windows 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 Enterprise 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 Enterprise 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 Enterprise Developer Build Tools for Windows
Building an Image Containing an Application to use with Enterprise Developer Build Tools for Windows
Docker Demonstrations
The CICS Docker Demonstration
The Docker Demonstration for the Enterprise Developer Base Image


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 Enterprise 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 Enterprise 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/entserver:rhel7_4.0_x64 the image that lets you log in would be called microfocus/entserver:rhel7_4.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.
  • Images that are targeted to 32-bit or 64-bit environments. You can include text such as x86 or x64 in the images' names to indicate whether they are for 32-bit or 64-bit environments respectively. For example, the image microfocus/entserver:win_4.0 could have platform-specific images named microfocus/entserver:win_4.0_x86 and microfocus/entserver:win_4.0_x64 .
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 Enterprise 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 Enterprise Server and illustrate how to build a range of images to perform different tasks, from being used as a base image for running Enterprise Server to debugging a sample CICS 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 Enterprise Developer, 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 Enterprise Developer. These demonstrations include all the files that are needed to create example images for use with Enterprise Developer, 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 Enterprise Developer Build Tools for Windows
  • Building an Image Containing an Application to use with Enterprise Developer Build Tools for Windows
Parent topic: Using Enterprise Developer with Docker
Related information
Debugging COBOL Applications Running in Containers
Key Concepts When Using Docker with COBOL Applications
Docker Demonstrations


Building a Base Image Containing Enterprise Developer Build Tools for Windows

This topic outlines the steps that a Dockerfile must carry out to create a base image for Enterprise Developer Build Tools for Windows.

Once you have built your Enterprise Developer Build Tools for Windows base image you can then build additional images, based on the base image, that include your COBOL applications as well as Enterprise Developer Build Tools for Windows. For more information on creating those additional images see Building an Image Containing an Application to use with Enterprise Developer Build Tools for Windows.

Note: Remember that Enterprise Developer is a development and test environment so not for use in production situations. If you want to run COBOL applications in containers in a production environment you must use containers that contain Enterprise Server.

For users of Enterprise Developer for Eclipse:

Before building a base image for Enterprise Developer Build Tools for Windows you need to ensure that you have available the following:

  • The installable executable file for Enterprise Developer Build Tools for Windows. This is edbt_40.exe and is supplied in the Docker demonstration for the Enterprise Developer Build Tools for Windows base image.
  • The appropriate license (.mflic) file for Enterprise Developer Build Tools for Windows.
  • 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.
Note: If you are using Enterprise Developer UNIX Components you need to ensure that you have available the following:
  • The installable executable for Enterprise Developer. This is setup_entdev_for_docker_4.0_platform and is supplied in the Docker demonstration for the Enterprise Developer base image.
  • The appropriate license (.mflic) for Enterprise Developer.
  • If you will be including Java support in the image, the file server-jre-8u162-linux-x64.tar.gz . This file is supplied in the EntDev folder of the entdev_dockerfiles_4.0_platform.tar file.

For users of Enterprise Developer for Eclipse:

To build a base image that includes Enterprise Developer Build Tools for Windows your Dockerfile needs to perform the following steps:

  1. Specify a base image to work from. This will typically be microsoft/dotnet-framework or microsoft/dotnet-framework-build.

    When creating a base image containing Enterprise Developer Build Tools for Windows you might want to create two different versions of the image - a regular image (which is built from microsoft/dotnet-framework) and a "-build" image (which is built from microsoft/dotnet-framework-build). The microsoft/dotnet-framework-build image includes build-related files that are not included in microsoft/dotnet-framework, so while an image built from microsoft/dotnet-framework will let you run applications, if you want to build applications you should use microsoft/dotnet-framework-build.

    Note: Because microsoft/dotnet-framework-build contains additional files that are not included in microsoft/dotnet-framework, for the sake of keeping container sizes to a minimum you should only use microsoft/dotnet-framework-build when you need the additional build-related features.

    The Docker demonstration that builds the base image containing Enterprise Developer Build Tools for Windows uses this approach, creating both microfocus/edbuildtools:win_4.0 and microfocus/edbuildtools-build:win_4.0.

  2. Define metadata for your image. This will make it easier to establish significant details of the image when you use the docker inspect command.
  3. Define any variables for filenames and folder locations.
    Note: If you will be using this image to run applications under Enterprise Server, you need to set the MFDS_EXTERNAL_ADDR environment variable to specify a resolvable external address string. This is to enable client browsers to resolve the URLs used by ESMAC and other utilities in Enterprise Server Administration.

    The value that you specify for this environment variable is used to replace the internal container address in the URL.

  4. Copy the installable executable file for Enterprise Developer Build Tools for Windows (edbt_40.exe) from your host machine to a temporary folder in the image's filesystem, then run it to install Enterprise Developer Build Tools for Windows.

    When running edbt_40.exe you need to specify the following parameters:

    /q
    to run the installaton silently; that is non-interactively with no user interface, using defaults for any values that are not specified elsewhere on the command line.
    InstallFolder=installation-location
    to specify the name of the folder into which you want to install Enterprise Developer Build Tools for Windows. This a folder that you must have created on the Docker image's filesystem.
    /l log-file-name
    to create a log file of the installation.
    accepteula=yes
    to indicate that you accept the terms of the Micro Focus End User License Agreement (EULA).
  5. Check the log file produced by the installation to ensure that the installation was successful.
  6. Use the MFLicenseAdmin.exe utility to install the license for Enterprise Developer Build Tools for Windows.
  7. Set up the Ant and Java support.
  8. Specify the network ports that the container will listen on at run-time.
  9. Perform any required clean-up. This includes tasks such as resetting variables and deleting temporary folders.
  10. Set the Docker working directory to be the folder into which you installed Enterprise Developer Build Tools for Windows.
Note: Micro Focus recommends that in addition to having a Dockerfile that performs the above steps you have additional Dockerfiles to create platform-specific versions of the Enterprise Developer Build Tools for Windows base image. These additional Dockerfiles will be very simple, using the Enterprise Developer Build Tools for Windows base image as their base then running commands to ensure that the correct (32-bit or 64-bit) environment is set up.

You could also choose to create a base image for Enterprise Developer Build Tools for Windows that doesn't include Java support. If you need to do this you would simply modify the above process to not perform the step related to setting up the Java support.

For users of Enterprise Developer UNIX Components:

To build a base image that includes Enterprise Developer 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 Enterprise Developer Build Tools for Windows to install successfully.
  5. Copy the installable executable file for Enterprise Developer Build Tools for Windows (setup_entdev_for_docker_4.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 Enterprise Developer Build Tools for Windows.
  7. Ensure that the installable executable file for Enterprise Developer Build Tools for Windows has execute permissions, then execute it.

    When running setup_entdev_for_docker_4.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 Enterprise Developer.

    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 Enterprise Developer Build Tools for Windows then remove the license file.
Note: You might also want to create an image that you can log in to and execute shell or Enterprise Developer commands. This option is useful if you are not adding any application files to a base image but want to be able to use Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer Build Tools for Windows. 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 Enterprise Developer Base Image.

Parent topic: Building Images for COBOL Applications
Related information
Enterprise Developer Build Tools for Windows
Building an Image Containing an Application to use with Enterprise Developer Build Tools for Windows
Getting Ready to Use Enterprise Developer with Docker
Running the Docker Demonstration for the Enterprise Developer Base Image
The Docker Demonstration for the Enterprise Developer Base Image


Building an Image Containing an Application to use with Enterprise Developer Build Tools for Windows

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 Enterprise Developer Build Tools for Windows.

Before you follow the steps in this topic you must have built a base image for Enterprise Developer Build Tools for Windows. For information on creating a base image for Enterprise Developer Build Tools for Windows see Building a Base Image Containing Enterprise Developer Build Tools for Windows.

Note: Remember that Enterprise Developer is a development and test environment so not for use in production situations. If you want to run COBOL applications in containers in a production environment you must use containers that contain Enterprise Server.

Before building an image containing an application to use with Enterprise Developer Build Tools for Windows you need to ensure that you have available the following:

  • A base image for Enterprise Developer Build Tools for Windows. If you have not yet built such an image, see Building a Base Image Containing Enterprise Developer Build Tools for Windows for information on how to build one.

To build an image that includes an application to use with Enterprise Developer Build Tools for Windows your Dockerfile needs to perform the following steps:

For users of Enterprise Developer for Eclipse:

  1. Specify a base image to work from. This should be an image containing only Enterprise Developer Build Tools for Windows which was built for 32-bit or 64-bit as required and includes the additional build functionality, typically microfocus/edbuildtools-build:win_4.0_x86or microfocus/edbuildtools-build:win_4.0_x64.

    See Building a Base Image Containing Enterprise Developer Build Tools for Windows for more information.

  2. Define metadata for your image. This will make it easier to establish significant details of the image when you use the docker inspect command.
  3. Define any variables for filenames and folder locations.
    Note: If you will be using this image to run applications under Enterprise Server, you need to set the MFDS_EXTERNAL_ADDR environment variable to specify a resolvable external address string. This is to enable client browsers to resolve the URLs used by ESMAC and other utilities in Enterprise Server Administration.

    The value that you specify for this environment variable is used to replace the internal container address in the URL.

  4. Copy the source files for your application to a folder on the image's filesystem and set the Docker working directory to that folder.
  5. Perform whatever processing you need to do on your application's source file. This would typically be compiling and building but could be anything that you can do with Enterprise Developer Build Tools for Windows.
  6. Copy your built application files to the required folder on the image's filesystem and set the Docker working directory to that folder.
  7. Perform any required clean-up. This includes tasks such as resetting variables and deleting temporary folders.
  8. Specify the name of the executable to run when the image is run.

For users of Enterprise Developer UNIX Components:

  1. Specify a base image to work from. This should be an image containing only Enterprise Developer Build Tools for Windows. See Building a Base Image Containing Enterprise Developer Build Tools for Windows 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 Enterprise Developer commands. This option is useful if you are not adding any application files to a base image but want to be able to use Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer Build Tools for Windows. 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 CICS Docker Demonstration.

Parent topic: Building Images for COBOL Applications
Related information
Building a Base Image Containing Enterprise Developer Build Tools for Windows
Enterprise Developer Build Tools for Windows
The CICS Docker Demonstration
Running the Docker Demonstration for the Enterprise Developer 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. Enterprise Developer UNIX Components does not have any integration with the Eclipse IDE, so much of the functionality described in this section is not available in Enterprise Developer UNIX Components. Where a feature in this section is not available in Enterprise Developer UNIX Components that is indicated in the description of the feature.

To debug a containerized COBOL application you use Enterprise Developer'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 Remote Debugging of Native COBOL Applications 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer.
  2. Run the Enterprise Developer 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 Enterprise Developer with Docker
Related information
Key Concepts When Using Docker with COBOL Applications
Building Images for COBOL Applications
Docker Demonstrations
Debugging Using a Remote Machine
Key Concepts When Using Docker for COBOL Application Development


Building a COBOL Application that is to be Debugged in a Container

Note: This topic does not apply if you are using Enterprise Developer UNIX Components.

The first step in preparing a COBOL application to be debugged in a container is to use Enterprise Developer 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
Related information
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
To import an existing Eclipse project
Building COBOL applications


Running a Container that is to be Debugged

This topic describes how to run an Enterprise Developer Build Tools for Windows 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 Enterprise Developer UNIX Components.

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_4.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_4.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
Building a COBOL Application that is to be Debugged in a Container
Finding the Details of a Container that is to be Debugged
Starting to Debug a COBOL Application in a Container
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 Enterprise Developer UNIX Components.

Once the container to be debugged is running you need to find out some identifying information about it that you can then specify to Enterprise Developer so that you can connect to the container to start debugging it.

You can specify either of the following pieces of information to Enterprise Developer:

  • 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
Related information
Building a COBOL Application that is to be Debugged in a Container
Running a Container that is to be Debugged
Starting to Debug a COBOL Application in a Container


Starting to Debug a COBOL Application in a Container

Note: This topic does not apply if you are using Enterprise Developer UNIX Components.

Once your Enterprise Developer Build Tools for Windows base image is running and you have found out its ID or IP address you are ready to use Enterprise Developer to connect to the container using remote debugging.

Debugging Using a Remote Machine contains information about using Enterprise Developer to remotely debug native COBOL applications in general. You should be familiar with the information presented in Debugging Using a Remote Machine before learning how to use remote debugging to debug a COBOL application running in a Docker container.

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 Enterprise Developer. 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
Related information
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
Debugging Using a Remote Machine


To start debugging a COBOL application that is not yet running in a container

Note: This topic does not apply if you are using Enterprise Developer UNIX Components.
  1. Open the application's project in Enterprise Developer.

    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 concepts
Creating a Debug Configuration
To import an existing Eclipse project
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 Enterprise Developer UNIX Components.
  1. Open the application's project in Enterprise Developer.

    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 concepts
Creating a Debug Configuration
To import an existing Eclipse project
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:
  • This topic only applies if you are using Enterprise Developer UNIX Components.
  • Micro Focus does not recommend the use of Character Animator in Enterprise Developer 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 an Enterprise Developer 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/entdevhub:sles12sp3_4.0_x64 /bin/bash
    Note:
    • On Red Hat Linux the name of the image to run would be microfocus/entdevhub:rhel7_4.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
Debugging with Character Animator
Compiling and Linking from the Command Line (UNIX)


Debugging PL/I Applications Running in Containers

This section of the documentation describes how to debug a PL/I application running in a Docker container.

The process for debugging a PL/I application is the same as for debugging a native COBOL application with the following difference:

  • When debugging a native COBOL application, the debug configurations to use to connect to the COBOL application are:
    • COBOL Application if the COBOL application is not running yet.
    • COBOL Attach to Process if it is.

    When debugging a PL/I application, the corresponding debug configurations to use are PL/I Application and PL/I Attach to Process respectively.

For more information on debugging native COBOL applications, see Debugging COBOL Applications Running in Containers.

Parent topic: Using Enterprise Developer with Docker
Related information
Debugging COBOL Applications Running in Containers
CodeWatch User's Guide
Invoking CodeWatch
mfplx Syntax


Docker Demonstrations

Enterprise Developer 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 Enterprise Developer Base Image
  • The CICS Docker Demonstration
Parent topic: Using Enterprise Developer 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
Debugging COBOL Applications Running in Containers


Supplied Docker Demonstrations

This topic lists the different Docker demonstrations that are supplied with Enterprise Developer, specifies the folder they are contained in, and provides a brief summary of what they do.

For users of Enterprise Developer for Eclipse:

Docker Demonstration | Location | Summary
Base Image | EdBuildTools | Creates a base image for Enterprise Developer Build Tools and two images configured for use with 32-bit or 64-bit applications.
CICS | Examples\CICS | Creates an image containing a sample CICS application that can be run or debugged.
Hello World | Examples\Build_HelloWorld | Creates an image containing a sample (Hello World) application that can be run or debugged.
Hello World (Ant) | Examples\Build_Helloworld_ant | Uses Ant to create 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.
Hello World (PL/I) | Examples\Build_PLI_HelloWorld | Creates an image containing a PL/I-based sample (Hello World) application that can be run or debugged.
MFUnit | Examples\MFUNIT | Compiles the Enterprise Developer MFUnit 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 Enterprise Developer Base Image and The CICS Docker Demonstration.

For users of Enterprise Developer UNIX Components:

Docker Demonstration | Location | Summary
Base Image | EntDev | Creates a base image for Enterprise Developer UNIX ComponentsBuild Tools and two images configured for use with 32-bit or 64-bit applications.
Ant | Examples/Build_demo_ant | Uses Ant to create an image containing a sample (Hello World) application that can be run or debugged.
CICS | Examples/CICS | Creates an image containing a sample CICS 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.
Hello World (PL/I) | Examples/Build_PLI_HelloWorld | Creates an image containing a PL/I-based sample (Hello World) application that can be run or debugged.
JSON | Examples/Build_demo_json | Compiles the Enterprise Developer JSON demo in a container and uses the results to produce a new image with the example.
MFUnit | Examples/Build_demo_mfunit | Compiles the Enterprise Developer MFUnit demo in a container and uses the results to produce a new image with the example.
Multithreading | Examples/Build_demo_mthread | Compiles the Enterprise Developer 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 Enterprise Developer Base Image and The CICS Docker Demonstration.

Parent topic: Docker Demonstrations
Related information
Using the Docker Demonstrations
The Docker Demonstration for the Enterprise Developer Base Image
The CICS Docker Demonstration


Using the Docker Demonstrations

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

For users of Enterprise Developer for Eclipse:

The Docker demonstrations are supplied in the file ed_build_tools_dockerfiles_4.0_windows.zip which is accessible from the same place that you accessed the Enterprise Developer installation file. Unzip ed_build_tools_dockerfiles_4.0_windows.zip 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.bat file to run it. Execute bld.bat with no parameters for a summary of the parameters that you can specify. More information on the parameters you can specify is provided in Running the Docker Demonstration for the Enterprise Developer Base Image and Running the CICS Docker Demonstration.

For users of Enterprise Developer UNIX Components:

The Docker demonstrations are supplied in the file entdev_dockerfiles_4.0_platform.tar which is accessible from the same place that you accessed theEnterprise Developer installation file. Unzip entdev_dockerfiles_4.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 Enterprise Developer Base Image and Running the CICS 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 Enterprise Developer Base Image
The CICS Docker Demonstration
Running the Docker Demonstration for the Enterprise Developer Base Image
Running the CICS Docker Demonstration
Supplied Docker Demonstrations


The Docker Demonstration for the Enterprise Developer Base Image

This section of the documentation introduces the Docker demonstration for the Enterprise Developer 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 Enterprise Developer Base Image
  • Running the Docker Demonstration for the Enterprise Developer Base Image
  • Files in the Docker Demonstration for the Enterprise Developer Base Image
  • Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)
  • Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer UNIX Components)
Parent topic: Docker Demonstrations
Related information
Supplied Docker Demonstrations
Using the Docker Demonstrations
The CICS Docker Demonstration


Introduction to the Docker Demonstration for the Enterprise Developer Base Image

The Docker demonstration for the Enterprise Developer base image contains all the files that you need to build an image containing Enterprise Developer. Once you have built this you can use it as the base image from which you can build images to contain your applications to use with Enterprise Developer.

Parent topic: The Docker Demonstration for the Enterprise Developer Base Image
Related information
Running the Docker Demonstration for the Enterprise Developer Base Image
Files in the Docker Demonstration for the Enterprise Developer Base Image
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer UNIX Components)
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)


Running the Docker Demonstration for the Enterprise Developer Base Image

The Docker demonstration to create the Enterprise Developer base image includes a batch file (bld.bat) to make the process of running the demonstration as easy as possible. This topic lists and describes the parameters that you can specify when running bld.bat.

For users of Enterprise Developer for Eclipse:

Note: When using bld.bat to create a base image for Enterprise Developer you need to ensure that the relevant installation files and licenses are available in the same folder as bld.bat. These are:
  • The installable executable file for Enterprise Developer Build Tools for Windows. This is edbt_40.exe and is supplied in the Docker demonstration for the Enterprise Developer Build Tools for Windows base image.
  • The appropriate license (.mflic) file for Enterprise Developer Build Tools for Windows.
  • 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 batch file to run the Docker demonstration for the Enterprise Developer base image is as follows:

bld.bat { IacceptEULA [verbose] [nojava] [java | oraclejava] [install-location] |
          rmi                                                                   |
          settings }

where the parameters are:

IacceptEULA
Indicates that you accept the Micro Focus End User License Agreement (EULA).

You must specify IacceptEULA to create a base image containing Enterprise Developer.

install-location
Specifies the name of the folder in the image filesystem into which Enterprise Developer will be installed. If specified, this must be the last parameter.
java
Indicates that you want to include Java support in the image, and that the Java support is to be provided by the AdoptOpenJDK OpenJDK. Specifying java results in the latest version of OpenJDK being downloaded and included in the image.
oraclejava
Indicates that you want to include Java support in the image, and that the Java support is to be provided by the Oracle JDK. The file server-jre-8u162-windows-x64.tar.gz must exist in the current directory and you must ensure that you are licensed to use it.
nojava
Indicates that you do not want Java to be installed in the base image. You might want to use this if your system already includes a number of different versions of Java and you don't want to introduce another version unnecessarily.
rmi
Indicates that you want to remove any previously-created Enterprise Developer base images. Specifying rmi results in the execution of a number of docker rmi --force commands to remove all Enterprise Developer 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 Enterprise Developer, 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.

For users of Enterprise Developer UNIX Components:

Note: When using bld.sh to create a base image for Enterprise Developer 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 for Enterprise Developer. This is setup_entdev_for_docker_4.0_platform and is supplied in the Docker demonstration for the Enterprise Developer base image.
  • The appropriate license (.mflic) for Enterprise Developer.
  • If you will be including Java support in the image, the file server-jre-8u162-linux-x64.tar.gz . This file is supplied in the EntDev folder of the entdev_dockerfiles_4.0_platform.tar file.

The command to execute the shell script to run the Docker demonstration for the Enterprise Developer 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 Enterprise Developer.

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

This option is useful if you are not adding any application files to a base image but want to be able to use Enterprise Developer commands from it.

When you specify login the tag of the image created is suffixed with "_login".

logingid=login-gid
Specifies the group ID to use for the user specified by the loginid parameter.
loginid=login-id
Specifies the user ID to use for the login image.
logingname=login-gname
Specifies the group name to use for the user specified by the loginid parameter.
loginname=login-name
Specifies the user name to use for the user specified by the loginid parameter.
nojava
Indicates that you do not want Java to be installed in the base image. You might want to use this parameter if your system already includes a number of different versions of Java and you don't want to introduce another version unnecessarily.
nologin
Indicates that you do not want to create a login image. You would typically want to use this option when creating an image that contains an application rather than just a base image for Enterprise Developer. 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 Enterprise Developer base images. Specifying rmi results in the execution of a number of docker rmi --force commands to remove all Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer Base Image
Related information
Introduction to the Docker Demonstration for the Enterprise Developer Base Image
Files in the Docker Demonstration for the Enterprise Developer Base Image
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer UNIX Components)
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)


Files in the Docker Demonstration for the Enterprise Developer Base Image

For users of Enterprise Developer for Eclipse:

The files contained in the Docker demonstration for the Enterprise Developer base image are as follows:

bld.bat | Batch file to automate the process of building Enterprise Developer images. For full details on the parameters you can specify to bld.bat see Running the Docker Demonstration for the Enterprise Developer Base Image.
bld.env | Configuration file defining various environment variables that are used while building the images. The environment variables define details such as the names of installable files and strings to be used for different parts of the image names.
convsetx.ps1 | PowerShell script file used by Dockerfile.x86 and Dockerfile.x64 to configure the COBOL environment to make it specific to 32-bit or 64-bit applications.
Dockerfile | Dockerfile used to build the base microfocus/edbuildtools:win_4.0 and microfocus/edbuildtools-build:win_4.0 image using OpenJDK from AdoptOpenJDK to provide Java support. For a detailed look at the commands used in this file, see Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image.
Dockerfile.oraclejava | Additional Dockerfile to produce a version of the Enterprise Developer base image that uses the Oracle JDK to provide Java support. Enterprise Developer does not include the files that provide this support, so you must obtain these files yourself and ensure that you are licensed to use them.
Dockerfile.nojava | Additional Dockerfile to produce a base image for Enterprise Developer that does not include Java support. You might want to use this if your system already includes a number of different versions of Java and you don't want to introduce another version unnecessarily.
Dockerfile.x64 | Dockerfile used to build the microfocus/edbuildtools:win_4.0_x64 and microfocus/edbuildtools-build:win_4.0_x64 images based on the microfocus/edbuildtools:win_4.0 and microfocus/edbuildtools-build:win_4.0 images respectively. This is a very simple Dockerfile that uses the convsetx.ps1 PowerShell script file to customize the COBOL environment for use with 64-bit applications.
Dockerfile.x86 | Similar to Dockerfile.x64 but builds the microfocus/edbuildtools:win_4.0_x86 and microfocus/edbuildtools-build:win_4.0_x86 images for use with 32-bit COBOL applications.
edbt_40.exe | The installable executable file for Enterprise Developer Build Tools for Windows.
getAdoptOpenJDK.ps1 | PowerShell script file used by Dockerfile to perform a number of different operations related to AdoptOpenJDK's OpenJDK, including downloading the required files, unzipping the files, and setting the environment to enable Java support.
palic.env | Configuration file used to specify the name of the license (.mflic) file for Enterprise Developer.
prodver.env | Configuration file containing a setting that specifies the version of Enterprise Developer that this Docker demonstration is supplied with.
README*.* | Files for HTML and plain text documents containing instructions on how to build the Enterprise Developer base images.

For users of Enterprise Developer UNIX Components:

The files contained in the Docker demonstration for the Enterprise Developer 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 Enterprise Developer images. For full details on the parameters you can specify to bld.sh see Running the Docker Demonstration for the Enterprise Developer Base Image.
Dockerfile | Dockerfile used to build the Enterprise Developer base image. For a detailed look at the commands used in this file, see Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image.
palic.env | Configuration file used to specify the name of the license (.mflic) file for Enterprise Developer.
prodver.env | Configuration file containing a setting that specifies the version of Enterprise Developer that this Docker demonstration is supplied with.
README*.* | Files for HTML and plain text documents containing instructions on how to build the Enterprise Developer base image.
setup_entdev_for_docker_4.0_platform | The installable executable file for Enterprise Developer Build Tools for Windows. There is also an associated .sum file for this file. You can ignore this file.
Note: The name of the Enterprise Developer base image depends on the platform you are using:
  • On Red Hat Linux the base image is microfocus/entdevhub:rhel7_4.0_x64.
  • On SUSE Linux the base image is microfocus/entdevhub:sles12sp3_4.0_x64.
Parent topic: The Docker Demonstration for the Enterprise Developer Base Image
Related information
Introduction to the Docker Demonstration for the Enterprise Developer Base Image
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer UNIX Components)
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)
Running the Docker Demonstration for the Enterprise Developer Base Image


Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

This topic describes in detail the commands used by the Dockerfiles in the Docker demonstration for the Enterprise Developer base image.

The following Dockerfiles are used:

Dockerfile
The main Dockerfile used to create the image for Enterprise Developer. The image created uses OpenJDK from AdoptOpenJDK to provide Java support. Enterprise Developer does not include the files that provide this support, so you must obtain these files yourself.
Dockerfile.nojava
Additional Dockerfile to produce a base image for Enterprise Developer that does not include Java support. You might want to use this if your system already includes a number of different versions of Java and you don't want to introduce another version unnecessarily.
Dockerfile.oraclejava
Additional Dockerfile to produce a version of the Enterprise Developer base image that uses the Oracle JDK to provide Java support. Enterprise Developer does not include the files that provide this support, so you must obtain these files yourself and ensure that you are licensed to use them.
Dockerfile.x86
Additional Dockerfile to produce a base image for Enterprise Developer for use with 32-bit applications.
Dockerfile.x64
Additional Dockerfile to produce a base image for Enterprise Developer for use with 64-bit applications.
  • The Dockerfile File in the Docker Demonstration for the Enterprise Developer Base Image
  • The Dockerfile.nojava File in the Docker Demonstration for the Enterprise Developer Base Image
  • The Dockerfile.oraclejava File in the Docker Demonstration for the Enterprise Developer Base Image
  • The Dockerfile.x64 File in the Docker Demonstration for the Enterprise Developer Base Image
  • The Dockerfile.x86 File in the Docker Demonstration for the Enterprise Developer Base Image
Parent topic: The Docker Demonstration for the Enterprise Developer Base Image
Related information
Introduction to the Docker Demonstration for the Enterprise Developer Base Image
Running the Docker Demonstration for the Enterprise Developer Base Image
Files in the Docker Demonstration for the Enterprise Developer Base Image
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer UNIX Components)


The Dockerfile File in the Docker Demonstration for the Enterprise Developer Base Image

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

This topic lists and describes the Dockerfile file from the Docker demonstration for the Enterprise Developer 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.

001  # Copyright (C) Micro Focus 2018. All rights reserved.
002
003  ARG BASE_SUFFIX=
004  ARG BASE_TAG=latest
005  FROM microsoft/dotnet-framework${BASE_SUFFIX}:${BASE_TAG}
006
007  # PRODUCT_VERSION is product version associated with this Dockerfile
008  # MFLICFILE is the build-arg for the license filename
009  # ACCEPT_CONTAINER_EULA is the build-arg for the acceptance of the end user license argument
010  # SETUP_EXE is the build-arg name for installer exe to be used
011  # TOOLS_LOC is build-arg name for installation location of the tools
012  # JAVAZIPFILE is the build-arg name for on-disk file that contains the oracle server jre
013  # JAVAHOMEDIR is the build-arg name for location of the java installation
014  ARG PRODUCT_VERSION=4.0.00266
015  ARG MFLICFILE
016  ARG ACCEPT_CONTAINER_EULA=no
017  ARG SETUP_EXE=edbt_40.exe
018  ARG TOOLS_LOC=c:\\EDTools
019  ARG JAVAZIPFILE=
020  ARG TMP_INST_DIR=c:\\ed50tmp
021
022  LABEL vendor="Micro Focus" \
023        com.microfocus.name="Enterprise Developer" \
024        com.microfocus.version="$PRODUCT_VERSION" \
025        com.microfocus.eula.url="https://supportline.microfocus.com/licensing/agreements.aspx" \
026        com.microfocus.is-base-image="true" \
027        com.microfocus.third_parties.java="openjdk"
028
029  # transfer build arguments to environment vars
030  ENV TOOLS_LOC=${TOOLS_LOC} \
031      RMT_DIR="C:\\Program Files (x86)\\Common Files\\SafeNet Sentinel\\Sentinel RMS License Manager\\WinNT"
032
033  # Use cmd.exe, the microsoft/dotnet-framework-build changes this to powershell, so we need to reset
034  SHELL ["cmd", "/S", "/C"]
035
036  # Copy the setup .exe and license to the image
037  COPY ${SETUP_EXE} "${TMP_INST_DIR}\\"
038  COPY ${MFLICFILE} "${TOOLS_LOC}\\"
039
040  # Do the actual installation
041  WORKDIR "${TMP_INST_DIR}"
042  RUN set TMP_INST_DIR=${TMP_INST_DIR} && \
043      set SETUP_EXE=${SETUP_EXE} && \
044      set ACCEPT_CONTAINER_EULA=${ACCEPT_CONTAINER_EULA} && \
045      cd %TMP_INST_DIR% && start "" /wait %SETUP_EXE% /q "InstallFolder=%TOOLS_LOC%" /l log.txt accepteula=%ACCEPT_CONTAINER_EULA%
046
047  # Check log.txt
048  RUN cd %TMP_INST_DIR% && \
049      findstr /ic:"Exit Code: 0x0" log.txt || (echo "Install failed - error messages in log.txt" && findstr /ic:"error" log.txt && findstr /ic:"Exit Code:" log.txt && exit 1)
050
051  # License the image
052  RUN set TOOLS_LOC=${TOOLS_LOC} && \
053      set MFLICFILE=${MFLICFILE} && \
054      cd %TOOLS_LOC% && \
055      "%RMT_DIR%\\MFLicenseAdmin.exe" -install %MFLICFILE%
056
057  # Copy java .tar.gz and setup PATH
058  COPY getAdoptOpenJDK.ps1 /
059  COPY ${JAVAZIPFILE} /
060  RUN cd / && \
061      powershell -command .\getAdoptOpenJDK.ps1 -download $False -unzip $True -CreateSetXBat $true && \
062      call env_setx.bat && \
063      cd / && \
064      del *.zip *.ps1
065
066  # Setup ANT on PATH, ANT_HOME and SYSLIB (for assembler)
067  RUN set TOOLS_LOC=${TOOLS_LOC} && \
068      setx /M PATH "%PATH%;%JAVA_HOME%\bin;%ANT_HOME%\bin" && \
069      setx /M ANT_HOME "%TOOLS_LOC%\ant" && \
070      setx /M SYSLIB "%TOOLS_LOC%\include"
071
072  # Cleaup directory
073  RUN set TMP_INST_DIR=${TMP_INST_DIR} && \
074      cd \ && rmdir /S /Q %TMP_INST_DIR%
075
076  # set the default directory to tools directory
077  WORKDIR "${TOOLS_LOC}"

The commands on the lines in this Dockerfile are as follows:

Lines | Description
003 - 005 | Specifies that the base image to use is the official Docker image for .NET Framework on Windows Server 2016 Server Core.
014 - 020 Define build arguments passed by the docker build command:
  • PRODUCT_VERSION. Indicates the version of Enterprise Developer that this Dockerfile is supplied with.
  • MFLICFILE. Specifies the name of the license file to use for Enterprise Developer.
  • ACCEPT_CONTAINER_EULA. Indicates acceptance of the terms laid out in the license agreement. The default setting of "no" means that you must modify this in order to indicate that you accept the terms of the license agreement.
  • SETUP_EXE. Specifies the name of the Enterprise Developer installation file. The default setting is the name of the file supplied with Enterprise Developer.
  • TOOLS_LOC. Specifies the folder into which Enterprise Developer will be installed.
  • JAVAZIPFILE. Specifies the name of the installation file for OpenJDK from AdoptOpenJDK.
  • TMP_INST_DIR. Specifies a temporary directory to be used while building the image. It is deleted when it is no longer needed.
022 - 027 | Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
030 - 031 Create environment variables to be used in this Dockerfile:
  • TOOLS_LOC is copied from the build argument defined previously.
  • RMT_DIR specifies the location of the COBOL licensing management software. This is installed when you install Enterprise Developer.
034 Specifies that the shell to be used for subsequent instructions is ["cmd", "/S", "/C"].

This is the default for Dockerfiles on Windows but needs to be specified explicitly here because the base image for this Dockerfile is a Microsoft .NET Framework "-build" image, and using that image causes PowerShell to be used as the shell.

037 - 038 | Copies the Enterprise Developer installation file into the temporary folder and the Enterprise Developer license file into the folder where Enterprise Developer is to be installed.
041 | Sets the Docker working directory to be the temporary directory.
042 - 045 | Run the Enterprise Developer installation file specifying parameters to install it silently, into the required directory, creating a log file, and indicating that you have accepted the terms laid out in the license agreement.
048 - 049 | Runs a series of concatenated Windows commands to search the Enterprise Developer installation log file for text indicating that the installation failed. If any such text is found no further processing takes place.
052 - 055 | Run a series of concatenated Windows commands to license Enterprise Developer.
058 - 064 | Copy the OpenJDK .zip file and the getAdoptOpenJDK.ps1 PowerShell script, then run a series of concatenated Windows comments to set up the Java environment and delete any files that are no longer required.
067 - 070 | Enables Ant support in the image by setting the ANT_HOME and PATH environment variables to include the relevant folders.
073 - 074 | Runs a series of concatenated Windows commands to delete the Enterprise Developer installation file and the temporary directory that was used to contain it.
077 | Sets the Docker working directory to be the directory into which Enterprise Developer was installed.
Parent topic: Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)
Related reference
Docker: Best practices for writing Dockerfiles


The Dockerfile.nojava File in the Docker Demonstration for the Enterprise Developer Base Image

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

This topic lists and describes the Dockerfile.nojava file from the Docker demonstration for the Enterprise Developer 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.

001  # Copyright (C) Micro Focus 2018. All rights reserved.
002
003  ARG BASE_SUFFIX=
004  FROM microsoft/dotnet-framework${BASE_SUFFIX}
005
006  # PRODUCT_VERSION is product version associated with this Dockerfile
007  # MFLICFILE is the build-arg for the license filename
008  # ACCEPT_CONTAINER_EULA is the build-arg for the accepting the end user license argument
009  # SETUP_EXE is the build-arg name for installer exe to be used
010  # TOOLS_LOC is build-arg name for installation location of the tools
011  ARG PRODUCT_VERSION=a.b.cc
012  ARG MFLICFILE
013  ARG ACCEPT_CONTAINER_EULA=no
014  ARG SETUP_EXE=edbt_40.exe
015  ARG TOOLS_LOC=c:\\EDTools
016  ARG TMP_INST_DIR=c:\\ed40tmp
017
018  LABEL vendor="Micro Focus" \
019        com.microfocus.name="Enterprise Developer" \
020        com.microfocus.version="$PRODUCT_VERSION" \
021        com.microfocus.eula.url="https://supportline.microfocus.com/licensing/agreements.aspx" \
022        com.microfocus.is-base-image="true" \
023
024  # transfer build arguments to environment vars
025  ENV TOOLS_LOC=${TOOLS_LOC} \
026      RMT_DIR="C:\\Program Files (x86)\\Common Files\\SafeNet Sentinel\\Sentinel RMS License Manager\\WinNT"
027
028  # Use cmd.exe, the microsoft/dotnet-framework-build changes this to powershell, so we need to reset
029  SHELL ["cmd", "/S", "/C"]
030
031  # Copy the setup .exe and license to the image
032  COPY ${SETUP_EXE} "${TMP_INST_DIR}\\"
033  COPY ${MFLICFILE} "${TOOLS_LOC}\\"
034
035  # Do the actual installation
036  RUN set TMP_INST_DIR=${TMP_INST_DIR} && \
037      set SETUP_EXE=${SETUP_EXE} && \
038      set ACCEPT_CONTAINER_EULA=${ACCEPT_CONTAINER_EULA} && \
039      cd %TMP_INST_DIR% && start "" /wait %SETUP_EXE% /q "InstallFolder=%TOOLS_LOC%" /l log.txt accepteula=%ACCEPT_CONTAINER_EULA%
040
041  # Check log.txt
042  RUN cd %TMP_INST_DIR% && \
043      findstr /ic:"Exit Code: 0x0" log.txt || (echo "Install failed - error messages in log.txt" && findstr /ic:"error" log.txt && findstr /ic:"Exit Code:" log.txt && exit 1)
044
045  # License the image
046  RUN set TOOLS_LOC=${TOOLS_LOC} && \
047      set MFLICFILE=${MFLICFILE} && \
048      cd %TOOLS_LOC% && \
049      "%RMT_DIR%\\MFLicenseAdmin.exe" -install %MFLICFILE%
050
051  # Cleaup directory
052  RUN set TMP_INST_DIR=${TMP_INST_DIR} && \
053      cd \ && rmdir /S /Q %TMP_INST_DIR%
054
055  # set the default directory to tools directory
056  WORKDIR "${TOOLS_LOC}"

The commands on the lines in this Dockerfile are as follows:

Lines | Description
003 - 004 | Specifies that the base image to use is the official Docker image for .NET Framework on Windows Server 2016 Server Core.
011 - 016 Define build arguments passed by the docker build command:
  • PRODUCT_VERSION. Indicates the version of Enterprise Developer that this Dockerfile is supplied with.
  • MFLICFILE. Specifies the name of the license file to use for Enterprise Developer.
  • ACCEPT_CONTAINER_EULA. Indicates acceptance of the terms laid out in the license agreement. The default setting of "no" means that you must modify this in order to indicate that you accept the terms of the license agreement.
  • SETUP_EXE. Specifies the name of the Enterprise Developer installation file. The default setting is the name of the file supplied with Enterprise Developer.
  • TOOLS_LOC. Specifies the folder into which Enterprise Developer will be installed.
  • TMP_INST_DIR. Specifies a temporary directory to be used while building the image. It is deleted when it is no longer needed.
Note: Unlike Dockerfile and Dockerfile.oraclejava, Dockerfile.nojava does not need to define any Java-related arguments.
018 - 022 Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
Note: Unlike Dockerfile and Dockerfile.oraclejava, Dockerfile.nojava does not need to include an entry for com.microfocus.third_parties.java.
025 - 026 Create environment variables to be used in this Dockerfile:
  • TOOLS_LOC is copied from the build argument defined previously.
  • RMT_DIR specifies the location of the COBOL licensing management software. This is installed when you install Enterprise Developer.
Note: Unlike Dockerfile and Dockerfile.oraclejava, Dockerfile.nojava does not need to define any Java-related arguments.
029 Specifies that the shell to be used for subsequent instructions is ["cmd", "/S", "/C"].

This is the default for Dockerfiles on Windows but needs to be specified explicitly here because the base image for this Dockerfile is a Microsoft .NET Framework "-build" image, and using that image causes PowerShell to be used as the shell.

032 - 033 | Copies the Enterprise Developer installation file into the temporary folder and the Enterprise Developer license file into the folder where Enterprise Developer is to be installed.
036 - 039 Run a series of concatenated Windows commands to:
  1. Set some environment variables based on the settings of build arguments.
  2. Run the Enterprise Developer installation file specifying parameters to install it silently, into the required directory, creating a log file, and indicating that you have accepted the terms laid out in the license agreement.
042 - 043 | Runs a series of concatenated Windows commands to search the Enterprise Developer installation log file for text indicating that the installation failed. If any such text is found no further processing takes place.
046 - 049 | Runs a series of concatenated Windows commands to license Enterprise Developer.
052 - 053 | Runs a series of concatenated Windows commands to delete the Enterprise Developer installation file and the temporary directory that was used to contain it.
056 | Sets the Docker working directory to be the directory into which Enterprise Developer was installed.
Parent topic: Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)
Related reference
Docker: Best practices for writing Dockerfiles


The Dockerfile.oraclejava File in the Docker Demonstration for the Enterprise Developer Base Image

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

This topic lists and describes the Dockerfile.oraclejava file from the Docker demonstration for the Enterprise Developer 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.

001  # Copyright (C) Micro Focus 2018. All rights reserved.
002
003  ARG BASE_SUFFIX=
004  ARG BASE_TAG=latest
005  FROM microsoft/dotnet-framework${BASE_SUFFIX}:${BASE_TAG}
006
007  # PRODUCT_VERSION is product version associated with this Dockerfile
008  # MFLICFILE is the build-arg for the license filename
009  # ACCEPT_CONTAINER_EULA is the build-arg for the acceptance of the end user license argument
010  # SETUP_EXE is the build-arg name for installer exe to be used
011  # TOOLS_LOC is build-arg name for installation location of the tools
012  # JAVATARFILE is the build-arg name for on-disk file that contains the oracle server jre
013  # JAVAHOMEDIR is the build-arg name for location of the java installation
014  ARG PRODUCT_VERSION=a.b.cc
015  ARG MFLICFILE
016  ARG ACCEPT_CONTAINER_EULA=no
017  ARG SETUP_EXE=edbt_40.exe
018  ARG TOOLS_LOC=c:\\EDTools
019  ARG JAVATARFILE=server-jre-8u162-windows-x64.tar.gz
020  ARG JAVAHOMEDIR=c:\\jdk1.8.0_162
021  ARG TMP_INST_DIR=c:\\ed40tmp
022
023  LABEL vendor="Micro Focus" \
024        com.microfocus.name="Enterprise Developer" \
025        com.microfocus.version="$PRODUCT_VERSION" \
026        com.microfocus.eula.url="https://supportline.microfocus.com/licensing/agreements.aspx" \
027        com.microfocus.is-base-image="true" \
028        com.microfocus.third_parties.java="oraclejava8"
029
030  # transfer build arguments to environment vars
031  ENV TOOLS_LOC=${TOOLS_LOC} \
032      RMT_DIR="C:\\Program Files (x86)\\Common Files\\SafeNet Sentinel\\Sentinel RMS License Manager\\WinNT"
033
034  # Use cmd.exe, the microsoft/dotnet-framework-build changes this to powershell, so we need to reset
035  SHELL ["cmd", "/S", "/C"]
036
037  # Copy the setup .exe and license to the image
038  COPY ${SETUP_EXE} "${TMP_INST_DIR}\\"
039  COPY ${MFLICFILE} "${TOOLS_LOC}\\"
040
041  # Do the actual installation
042  WORKDIR "${TMP_INST_DIR}"
043  RUN set TMP_INST_DIR=${TMP_INST_DIR} && \
044      set SETUP_EXE=${SETUP_EXE} && \
045      set ACCEPT_CONTAINER_EULA=${ACCEPT_CONTAINER_EULA} && \
046      cd %TMP_INST_DIR% && start "" /wait %SETUP_EXE% /q "InstallFolder=%TOOLS_LOC%" /l log.txt accepteula=%ACCEPT_CONTAINER_EULA%
047
048  # Check log.txt
049  RUN cd %TMP_INST_DIR% && \
050      findstr /ic:"Exit Code: 0x0" log.txt || (echo "Install failed - error messages in log.txt" && findstr /ic:"error" log.txt && findstr /ic:"Exit Code:" log.txt && exit 1)
051
052  # License the image
053  RUN set TOOLS_LOC=${TOOLS_LOC} && \
054      set MFLICFILE=${MFLICFILE} && \
055      cd %TOOLS_LOC% && \
056      "%RMT_DIR%\\MFLicenseAdmin.exe" -install %MFLICFILE%
057
058  # Copy java .tar.gz and setup PATH
059  ENV JAVA_HOME=${JAVAHOMEDIR}
060  ADD ${JAVATARFILE} /
061
062  # Setup ANT on PATH and ANT_HOME
063  RUN set TOOLS_LOC=${TOOLS_LOC} && \
064      setx /M PATH "%PATH%;%JAVA_HOME%\bin;%ANT_HOME%\bin" && \
065      setx /M ANT_HOME "%TOOLS_LOC%\ant"
066
067  # Cleaup directory
068  RUN set TMP_INST_DIR=${TMP_INST_DIR} && \
069      cd \ && rmdir /S /Q %TMP_INST_DIR%
070
071  # set the default directory to tools directory
072  WORKDIR "${TOOLS_LOC}"

The commands on the lines in this Dockerfile are as follows:

Lines | Description
003 - 005 | Specifies that the base image to use is the official Docker image for .NET Framework on Windows Server 2016 Server Core.
014 - 021 Define build arguments passed by the docker build command:
  • PRODUCT_VERSION. Indicates the version of Enterprise Developer that this Dockerfile is supplied with.
  • MFLICFILE. Specifies the name of the license file to use for Enterprise Developer.
  • ACCEPT_CONTAINER_EULA. Indicates acceptance of the terms laid out in the license agreement. The default setting of "no" means that you must modify this in order to indicate that you accept the terms of the license agreement.
  • SETUP_EXE. Specifies the name of the Enterprise Developer installation file. The default setting is the name of the file supplied with Enterprise Developer.
  • TOOLS_LOC. Specifies the folder into which Enterprise Developer will be installed.
  • JAVATARFILE. Specifies the name of the .tar file containing the Oracle JDK files that are required to provide Java support by the Oracle JDK. You must provide this file yourself and ensure that you have the required license to use it.
  • JAVAHOMEDIR. Specifies the name of the folder in the image's filesystem into which the files from the JAVATARFILE .tar file will be extracted.
  • TMP_INST_DIR. Specifies a temporary directory to be used while building the image. It is deleted when it is no longer needed.
023 - 028 | Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
031 - 032 Create environment variables to be used in this Dockerfile:
  • TOOLS_LOC is copied from the build argument defined previously.
  • RMT_DIR specifies the location of the COBOL licensing management software. This is installed when you install Enterprise Developer.
035 Specifies that the shell to be used for subsequent instructions is ["cmd", "/S", "/C"].

This is the default for Dockerfiles on Windows but needs to be specified explicitly here because the base image for this Dockerfile is a Microsoft .NET Framework "-build" image, and using that image causes PowerShell to be used as the shell.

038 - 039 | Copies the Enterprise Developer installation file into the temporary folder and the Enterprise Developer license file into the folder where Enterprise Developer is to be installed.
042 | Sets the Docker working directory to be the temporary directory.
043 - 046 | Run the Enterprise Developer installation file specifying parameters to install it silently, into the required directory, creating a log file, and indicating that you have accepted the terms laid out in the license agreement.
049 - 050 | Runs a series of concatenated Windows commands to search the Enterprise Developer installation log file for text indicating that the installation failed. If any such text is found no further processing takes place.
053 - 056 | Run a series of concatenated Windows commands to license Enterprise Developer.
059 - 060 | Enables Java support in the image by untarring the file specified by the JAVATARFILE build argument into the folder specified by the JAVAHOMEDIR build argument, then updating the PATH environment variable to include the bin subfolder of that folder.
063 - 065 | Enables Ant support in the image by setting the ANT_HOME and PATH environment variables to include the relevant folders.
068 - 069 | Runs a series of concatenated Windows commands to delete the Enterprise Developer installation file and the temporary directory that was used to contain it.
072 | Sets the Docker working directory to be the directory into which Enterprise Developer was installed.
Parent topic: Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)
Related reference
Docker: Best practices for writing Dockerfiles


The Dockerfile.x64 File in the Docker Demonstration for the Enterprise Developer Base Image

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

This topic lists and describes the Dockerfile.x64 file from the Docker demonstration for the Enterprise Developer 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.

001  # Copyright (C) Micro Focus 2018. All rights reserved.
002
003  ARG DTAGVER=
004  ARG BASE_SUFFIX=
005  FROM microfocus/edbuildtools${BASE_SUFFIX}:${DTAGVER}
006
007  # copy the powershell script to convert cblpromp -J output to setx command
008  ADD convsetx.ps1 "c:\convsetx.ps1"
009
010  # ensure msbuild is always on the PATH
011  RUN setx /M PATH "%PATH%;C:\\Windows\\Microsoft.NET\\Framework64\\v4.0.30319"
012
013  # convert the output of cblprompt into SETX commands and execute them
014  RUN cd %TOOLS_LOC% && \
015      bin64\cblpromp.exe -J >env.prop && \
016      powershell -file "c:\convsetx.ps1" >envsetx.bat && \
017      envsetx.bat && \
018      del envsetx.bat && \
019      del env.prop && \
020      del "c:\convsetx.ps1"

Lines | Description
003 - 004 | Define build arguments passed by the docker build command.
005 | Specifies that the base image to use is the image built from Dockerfile.
008 | Copies the convsetx.ps1 PowerShell script to the image's filesystem.
011 | Updates the PATH environment variable to enable the use of MSBuild.
014 - 020 | Run a series of concatenated Windows commands to ensure that all environment variables set by the COBOL command prompt are available to applications in this image.
Parent topic: Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)
Related reference
Docker: Best practices for writing Dockerfiles


The Dockerfile.x86 File in the Docker Demonstration for the Enterprise Developer Base Image

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

This topic lists and describes the Dockerfile.x86 file from the Docker demonstration for the Enterprise Developer 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.

001  # Copyright (C) Micro Focus 2018. All rights reserved.
002
003  ARG DTAGVER=
004  ARG BASE_SUFFIX=
005  FROM microfocus/edbuildtools${BASE_SUFFIX}:${DTAGVER}
006
007  # copy the powershell script to convert cblpromp -J output to setx command
008  ADD convsetx.ps1 "c:\convsetx.ps1"
009
010  # ensure msbuild is always on the PATH
011  RUN setx /M PATH "%PATH%;C:\\Windows\\Microsoft.NET\\Framework\\v4.0.30319"
012
013  # convert the output of cblprompt into SETX commands and execute them
014  RUN cd %TOOLS_LOC% && \
015      bin\cblpromp.exe -J >env.prop && \
016      powershell -file "c:\convsetx.ps1" >envsetx.bat && \
017      envsetx.bat && \
018      del envsetx.bat && \
019      del env.prop && \
020      del "c:\convsetx.ps1"

The commands on the lines in this Dockerfile are as follows:

Lines | Description
003 - 004 | Define build arguments passed by the docker build command.
005 | Specifies that the base image to use is the image built from Dockerfile.
008 | Copies the convsetx.ps1 PowerShell script to the image's filesystem.
011 | Updates the PATH environment variable to enable the use of MSBuild.
014 - 020 | Run a series of concatenated Windows commands to ensure that all environment variables set by the COBOL command prompt are available to applications in this image.
Parent topic: Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)
Related reference
Docker: Best practices for writing Dockerfiles


Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer UNIX Components)

Note: This topic only applies if you are using Enterprise Developer UNIX Components.

This topic describes in detail the commands used by the Dockerfile in the Docker demonstration for the Enterprise Developer 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=4.0.00
011  ARG ACCEPTEULA
012  ARG SETUP_EXE=setup_entdev_for_docker_4.0_redhat_x64
013  ARG LOGFILE=EnterpriseDeveloper4.0.log
014  ARG MFLICFILE
015  ARG ESADM_UID=500
016  ARG ESADM_GID=500
017  ARG ESADM_USER=edadm
018  ARG ESADM_SHELL=/bin/bash
019
020  LABEL vendor="Micro Focus" \
021        com.microfocus.name="Enterprise Developer" \
022        com.microfocus.version="$PRODUCT_VERSION" \
023        com.microfocus.eula.url="https://supportline.microfocus.com/licensing/agreements.aspx" \
024        com.microfocus.is-base-image="true"
025
026  ENV MFPRODBASE=/opt/microfocus/EnterpriseDeveloper
027  ENV MFLICBASE=/var/microfocuslicensing
028
029
030  # install ed, pax and glibc-devel.x86_64 as these are a pre-req for the installer
031  # note: disablerepo is used to avoid "HTTPS Error 403 - Forbidden" error
032  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
033
034  # copy the installer from the local machine to the container
035  COPY ${SETUP_EXE} /tmp/
036
037  # Create user esadm
038  RUN groupadd -f -g $ESADM_GID $ESADM_USER && \
039      useradd -u $ESADM_UID -g $ESADM_GID -m -s $ESADM_SHELL $ESADM_USER
040
041  # ensure the setup exe has execute permissions and execute the setup
042  RUN chmod +x ./tmp/${SETUP_EXE} && \
043      (/tmp/${SETUP_EXE} -${ACCEPTEULA} -ESadminID=$ESADM_USER || (echo ${LOGFILE} contains && touch ${LOGFILE} && cat ${LOGFILE} && exit 1)) && \
044      rm -f /tmp/${SETUP_EXE} && \
045      echo "$MFPRODBASE/lib" >>/etc/ld.so.conf && \
046      ldconfig
047
048  # install a license and remove the license file
049  COPY ${MFLICFILE} /tmp/
050  RUN cd /tmp && $MFLICBASE/bin/MFLicenseAdmin -install "${MFLICFILE}" && rm -f "${MFLICFILE}"
051
052  # COPY cobsetenv_login to the bin
053  COPY cobsetenv_login /root/bin/
054  #
055  # clean up for containers that use -network:host
056  #
057  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 - 018 Define build arguments passed by the docker build command:
  • PRODUCT_VERSION.Indicates the version of Enterprise Developer that this Dockerfile is supplied with.
  • SETUP.EXE. Specifies the name of the Enterprise Developer installation file. The default setting is the name of the file supplied with Enterprise Developer.
  • 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 Enterprise Developer into the image.
  • MFLICFILE. Specifies the name of the license file to use for Enterprise Developer.
  • 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.
020 - 024 | Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
026 - 027 Create environment variables to be used in this Dockerfile:
  • MFPRODBASE. Specifies the folder into which Enterprise Developer is installed.
  • MFLICBASE. Specifies the folder where the Micro Focus License Administration tool is installed.
032 | Install software that is required to be able to install Enterprise Developer.
035 | Copy the installation file for Enterprise Developer into a temporary folder.
038 - 039 | Run a series of concatenated commands to add the Enterprise Server admin user and set up the shell to be used by that user.
042 - 046 Run a series of concatenated commands to perform the following actions:
  1. Make the Enterprise Developer installation file executable.
  2. Run the Enterprise Developer 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 Enterprise Developer installation file).
  4. Configure the dynamic linker run-time bindings to include the shared objects supplied with Enterprise Developer.

    Doing this avoids the need to update the LD_LIBRARY_PATH environment variable.

049 - 050 | Copy the license file to a temporary location, use it to license Enterprise Developer, then delete the license file.
053 | Copy the default environment that is to be used when someone logs on as root.
057 | Run a script to reset the temporary file used when applying the license for Enterprise Developer.
Parent topic: The Docker Demonstration for the Enterprise Developer Base Image
Related information
Introduction to the Docker Demonstration for the Enterprise Developer Base Image
Running the Docker Demonstration for the Enterprise Developer Base Image
Files in the Docker Demonstration for the Enterprise Developer Base Image
Dockerfiles in the Docker Demonstration for the Enterprise Developer Base Image (for Enterprise Developer for Eclipse)


The CICS Docker Demonstration

This section of the documentation introduces the CICS 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 CICS Docker Demonstration
  • Running the CICS Docker Demonstration
  • Files in the CICS Docker Demonstration
  • Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer for Eclipse)
  • Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer UNIX Components)
Parent topic: Docker Demonstrations
Related information
Supplied Docker Demonstrations
Using the Docker Demonstrations
The Docker Demonstration for the Enterprise Developer Base Image


Introduction to the CICS Docker Demonstration

The CICS Docker demonstration for Enterprise Developer builds on the Enterprise Developer base image and adds the source files for a sample CICS application to illustrate how you can work with your COBOL applications in Docker containers.

Parent topic: The CICS Docker Demonstration
Related information
Running the CICS Docker Demonstration
Files in the CICS Docker Demonstration
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer for Eclipse)
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer UNIX Components)


Running the CICS Docker Demonstration

For users of Enterprise Developer for Eclipse:

The CICS Docker demonstration includes a batch file (bld.bat) to make the process of running the demonstration as easy as possible. This topic lists and describes the parameters that you can specify when running bld.bat.

The command to execute the batch file to run the CICS Docker demonstration is as follows:

bld.bat { {dn|x64|x86} [debug]  |
         rmi }

where the parameters are:

debug
Indicates that you want to debug the CICS application rather than simply execute it. Specifying debug causes Dockerfile.debug to be run rather than Dockerfile.
dn
Indicates that you want to run the CICS application in a .NET environment. Specifying dn causes Dockerfile.dn to be run rather than Dockerfile.
x64
Indicates that you want to run the CICS application in a 64-bit environment. Specifying x64 causes Dockerfile.x64 to be run rather than Dockerfile.
x86
Indicates that you want to run the CICS application in a 32-bit environment. Specifying x86 causes Dockerfile.x86 to be run rather than Dockerfile.
rmi
Indicates that you want to remove any previously-created CICS Docker demonstration images. Specifying rmi results in the execution of a number of docker rmi --force commands to remove any CICS Docker demonstration images.

For users of Enterprise Developer UNIX Components:

The CICS 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 CICS 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 Enterprise Developer commands.

This option is useful if you are not adding any application files to a base image but want to be able to use Enterprise Developer commands from it.

When you specify login the tag of the image created is suffixed with "_login".

logingid=login-gid
Specifies the group ID to use for the user specified by the loginid parameter.
loginid=login-id
Specifies the user ID to use for the login image.
logingname=login-gname
Specifies the group name to use for the user specified by the loginid parameter.
loginname=login-name
Specifies the user name to use for the user specified by the loginid parameter.
nojava
Indicates that you do not want Java to be installed in the base image. You might want to use this parameter if your system already includes a number of different versions of Java and you don't want to introduce another version unnecessarily.
nologin
Indicates that you do not want to create a login image. You would typically want to use this option when creating an image that contains an application rather than just a base image for Enterprise Developer. 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 CICS Docker demonstration images. Specifying rmi results in the execution of a number of docker rmi --force commands to remove any CICS Docker demonstration 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 Enterprise Developer, 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 CICS Docker Demonstration
Related information
Introduction to the CICS Docker Demonstration
Files in the CICS Docker Demonstration
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer for Eclipse)
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer UNIX Components)


Files in the CICS Docker Demonstration

For users of Enterprise Developer for Eclipse:

The files contained in the CICS Docker demonstration are as follows:

MSS folder | Folder containing source files for the CICS application.
bld.bat | Batch file to automate the process of building CICS Docker demonstration images. For full details on the parameters you can specify to bld.bat see Running the CICS 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.
Dockerfile | Dockerfile used to build the CICS Docker demonstration image. For a detailed look at the commands used in this file, see Dockerfiles in the CICS Docker Demonstration.
MSS32_export.zip | .zip file containing Micro Focus Directory Server (MFDS) resource definitions for the CICS application for use in 32-bit environments.
MSS64_export.zip | .zip file containing MFDS resource definitions for the CICS application for use in 64-bit environments.
README*.* | Files for HTML and plain text documents containing instructions on how to build the CICS Docker demonstration images.
unzip.ps1 | PowerShell script to unzip MSS*_export.zip.
zipbld.ps1 | PowerShell script to recreate MSS.zip to contain the source files for the CICS application.

For users of Enterprise Developer UNIX Components:

The files contained in the CICS Docker demonstration are as follows:

src folder | Folder containing source files for the CICS application.
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 | Batch file to automate the process of building CICS Docker demonstration images. For full details on the parameters you can specify to bld.sh see Running the CICS Docker Demonstration.
bld_package.sh | Shell script to rebuild and package the CICS Docker demonstration application.
Dockerfile | Dockerfile used to build the CICS Docker demonstration image. For a detailed look at the commands used in this file, see Dockerfiles in the CICS Docker Demonstration.
MSS64_export.tar.gz | .tar file containing MFDS resource definitions for the CICS application.
palic.env | Configuration file used to specify the name of the license (.mflic) file for Enterprise Developer.
README*.* | Files for HTML and plain text documents containing instructions on how to build the CICS Docker demonstration images.
sample_setup | Script to start the Micro Focus Directory Server (MFDS), deploy the region definitions, then application and display the console .log file for the region until the container is terminated.
Note: The name of the Enterprise Developer base image depends on the platform you are using:
  • On Red Hat Linux the base image is microfocus/entdevhub:rhel7_4.0_x64.
  • On SUSE Linux the base image is microfocus/entdevhub:sles12sp3_4.0_x64.
Parent topic: The CICS Docker Demonstration
Related information
Introduction to the CICS Docker Demonstration
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer for Eclipse)
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer UNIX Components)
Files in the Docker Demonstration for the Enterprise Developer Base Image
Running the CICS Docker Demonstration


Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer for Eclipse)

Note: This topic only applies if you are using Enterprise Developer for Eclipse.

This topic describes in detail the commands used by the Dockerfile in the CICS 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.

001  # Copyright (C) Micro Focus 2018. 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  ARG EDBTTAG
006  FROM microfocus/edbuildtools:${EDBTTAG}
007
008  LABEL com.microfocus.is-example="true"
009
010  # required arguments
011  ARG EDBTPLATFORM
012
013  # optional arguments
014  ARG APPDIR=c:\\app
015
016  # copy the application to the application directory
017  ENV BASE "${APPDIR}\\MSS"
018  COPY MSS${EDBTPLATFORM}_export.zip "${APPDIR}\\MSS_export.zip"
019  COPY MSS "${APPDIR}\\MSS\\"
020
021  # set the start directory and the initial program name
022  WORKDIR "${APPDIR}"
023
024  RUN set APPDIR=${APPDIR} && \
025      powershell -Command "Expand-Archive MSS_export.zip -Force -DestinationPath %APPDIR%" && \
026      del MSS_export.zip
027
028  WORKDIR "${APPDIR}\\MSS${EDBTPLATFORM}"
029
030  ENV EDBTPLATFORM=${EDBTPLATFORM}
031
032  CMD ["powershell", "-file", "..\\MSS\\DeployAndWait.ps1", "-es_name", "MSS$($env:EDBTPLATFORM))"]
033
034  EXPOSE 86 443 500-55000

The commands on the lines in this Dockerfile are as follows:

Lines | Description
005 - 006 | Specifies the base image to use, which is the Enterprise Developer Build Tools for Windows base image.
008 | Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
011 - 014 Define build arguments passed by the docker build command:
  • EDBTPLATFORM. Either x86 or x64 indicating whether the CICS application will be running in a 32-bit or 64-bit environment respectively.
  • APPDIR. Specifies the folder in the image's filesystem that the CICS application is copied into. c:\app is used if this argument is not specified.
017 - 019 | Copy the .zip files containing the CICS application source files to the relevant folders in the image's filesystem.
022 | Sets the Docker working directory to be the directory containing the CICS application.
024 - 026 | Runs a series of concatenated Windows commands to unzip the CICS application source files to the relevant folders in the image's filesystem then delete the .zip files.
028 | Sets the Docker working directory to be the platform-specific folder into which you unzipped the CICS application source files.
030 | Creates an environment variable to hold a value that indicates whether the CICS application will be running in a 32-bit or 64-bit environment.
032 | Runs a PowerShell script to start the Micro Focus Directory Server (MFDS), deploy the region definitions, then application and display the console .log file for the region until the container is terminated.
034 | Specifies the network ports that the container will listen on at run-time.
Parent topic: The CICS Docker Demonstration
Related reference
Docker: Best practices for writing Dockerfiles
Related information
Introduction to the CICS Docker Demonstration
Running the CICS Docker Demonstration
Files in the CICS Docker Demonstration
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer UNIX Components)


Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer UNIX Components)

Note: This topic only applies if you are using Enterprise Developer UNIX Components.

This topic describes in detail the commands used by the Dockerfile in the CICS 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 2018. 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/entdevhub:rhel7_4.0_x64
006
007  ARG ESADM_USER=edadm
008
009  LABEL com.microfocus.is-base-image="false"
010
011  # Create user app and setup cobsetenv
012  USER root
013
014  RUN useradd -ms /bin/bash app && \
015      usermod -aG $ESADM_USER app && \
016      touch /etc/profile && \
017      touch ~app/.bashrc && \
018      echo ". ~/bin/cobsetenv_login" >>~app/.bashrc && \
019      echo ". ~/bin/cobsetenv_login" >>~app/.bash_login
020
021  COPY sample_setup /home/app/bin/
022  RUN  chown -R app /home/app
023
024  USER app
025  ENV BASE /home/app/MSS
026  ENV CCITCP2_PORT 4790
027  WORKDIR "/home/app"
028  COPY MSS.tar.gz /home/app
029  COPY MSS64_export.tar.gz /home/app
030  RUN tar xvfp MSS.tar.gz && \
031      tar xvfp MSS64_export.tar.gz
032
033  COPY cobsetenv_login /home/app/bin/
034
035  EXPOSE 443 500-55000
036
037  CMD /home/app/bin/sample_setup

The commands on the lines in this Dockerfile are as follows:

Lines | Description
005 Specifies the base image to use, which is the Enterprise Developer base image.

On SUSE Linux the tag specified in the Dockerfile is sles12sp3_4.0_x64.

007 Define build arguments passed by the docker build command:
  • ESADM_USER. Specifies the ID to be used for the Enterprise Server admin user.
009 | Specify the metadata labels for the image that will be created. These labels can be queried using the docker inspect command.
012 | Sets the user to root.
014 - 022 | Run a series of concatenated commands to add the Enterprise Server admin user and set up the shell to be used by that user.
024 | Sets the user name to be used when running the image.
025 - 026 Create environment variables to be used in this Dockerfile:
  • BASE. Specifies the base folder of the CICS application. This is required because this environment variable is used by the resource definitions specified in MSS*_export.zip.
  • CCITCP2_PORT. Specifies the port on which the CCITCP2 registration program operates. See Enterprise Server Communications Environment Variables for more information.
027 | Sets the Docker working directory to be the folder where the CICS application source files are located.
028 - 031 | Copy the .tar files containing the CICS application source files then extract the source files from them.
033 | Copy the default environment that is to be used when someone logs on .
035 | Specifies the network ports that the container will listen on at run-time.
037 | Runs a script to start the Micro Focus Directory Server (MFDS), deploy the region definitions, then application and display the console .log file for the region until the container is terminated.
Parent topic: The CICS Docker Demonstration
Related information
Introduction to the CICS Docker Demonstration
Running the CICS Docker Demonstration
Files in the CICS Docker Demonstration
Dockerfiles in the CICS Docker Demonstration (for Enterprise Developer for Eclipse)


Programming

  • COBOL Programming
  • Compatibility
  • Data Access
  • Using COBOL and Java Together
  • Mainframe Programming
  • Managed COBOL Programming
  • Multi-threaded Programming
  • Performance Programming
  • Problem Determination and Diagnostic Tools
  • The Micro Focus Unit Testing Framework
    The Micro Focus Unit Testing Framework is an xUnit-style testing framework, available from the Enterprise Developer command line or shell prompt, or from the IDE. It supports native COBOL applications, and if you are using the command line version, procedural applications compiled to managed COBOL.
  • Programming Tips
Parent topic: Micro Focus Enterprise Developer 4.0 for Eclipse


COBOL Programming

  • Getting Started with COBOL
  • Calling COBOL Programs
  • Internationalization Support
  • Preparing Applications for Enterprise Server
  • Web Services Support for Native COBOL
    Describes how Enterprise Developer and Enterprise Server support Native COBOL applications as Web services.
  • Interface Mapping Toolkit (IMTK)
    Describes the functionality available in the Interface Mapping Toolkit (IMTK).
  • 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.

    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.

    Though the course uses Visual COBOL to demonstrate the programming concepts, all of the information applies equally to Enterprise Developer.

    This is a standard COBOL programming course. It does not include instructions about how to create applications that use Mainframe Subsystem Support (such as CICS, IMS, JCL and PL/I).

  • 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 Enterprise Developer 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
  • .NET Entry Point Mapping
  • 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


.NET Entry Point Mapping

The Entry Point Mapper is available for .NET COBOL. It supports the mfentmap.dat file and the ENTRYNAMEMAP and MFENTMAP environment variables to locate the file. In addition, the Entry Point Mapper can be configured through the application configuration file.

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.

You can preload entry points by creating a library file that contains any programs with entry points. When you call a library file, the run-time system does not load every program in the library file. Instead, the run-time system registers, for future reference, the existence of all programs and entry points contained in the called library file. Later when one of these programs is called, the run-time system notes that it is contained in the library file and loads it at that point.

Note: Entry points must have names that the system assembler and linker can accept; that is, they must contain only characters that are 0-9, A-Z, a-z, underscore, or hyphen.

Entry points are visible only when an assembly has been loaded. There are two solutions for this:

  • You can preload an assembly by calling the main program id.
  • For a managed application, you can add the assembly name to the interop/preload section of the application configuration file. The following example configuration file, for program a.exe, preloads the managed assembly b.dll:
    <?xml version="1.0" encoding="utf-8" ?>
<configuration>
 <configSections>
    <sectionGroup name="MicroFocus.COBOL.Application">
      <section name="Switches"
     type="System.Configuration.NameValueSectionHandler" />
      <section name="Environment"
     type="System.Configuration.NameValueSectionHandler" />
      <sectionGroup name="Interop">
        <section name="PreLoad"
     type="System.Configuration.NameValueSectionHandler" />
      </sectionGroup>
    </sectionGroup>
    <!--The following code declares a section group for
                            run-time configuration -->
    <sectionGroup name="MicroFocus.COBOL.Runtime">
     <section name="Tunables"
     type="System.Configuration.NameValueSectionHandler" />
     <section name="Switches"
     type="System.Configuration.NameValueSectionHandler" />
    </sectionGroup>
 </configSections>

 <MicroFocus.COBOL.Application>
    <Switches></Switches>
    <Environment></Environment>
    <Interop>
       <PreLoad>
         <add key="b.dll" value="managed" />
       </PreLoad>
    </Interop>
 </MicroFocus.COBOL.Application>
 <runtime>
     <assemblyBinding xmlns="urn:schemas-microsoft-om:asm.v1">
        <probing privatePath="bin"/>
     </assemblyBinding>
 </runtime>
</configuration>
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.

Windows: The called program can be dynamically linked, where a dynamically linked module is a .dll file. The called program can also be dynamically loaded when the program runs, where a dynamically loadable module is a either a .dll file, an .int file or a gnt file.

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.

Windows: Calling Dynamically Loadable Programs

Use either a CALL literal statement, or a CALL data-name statement, to call a dynamically loadable program, and make the dynamic loader run-time support module search for the called program.

If the file is not found, the run-time system tries to load a .dll file from PATH using the specified base-name.

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.dll (Windows) or filename.so (UNIX)
  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 (except .dll files).

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.

Note that, the operating system limits the return value to two bytes, if you use the IF ERRORLEVEL syntax to check the return value.

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

Parameters (Windows)

where the parameters are:

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 any of the following values:
  • 1 = American English
  • 2 = Canadian French
  • 3 = Danish
  • 4 = Dutch
  • 5 = English
  • 6 = Finnish
  • 7 = French
  • 8 = German
  • 9 = Italian
  • 10 = Norwegian
  • 11 = Portuguese
  • 12 = Spanish
  • 13 = Swedish
_ The delimiter for language and territory, if territory is specified.

The following example illustrates how to specify a language of French and use the operating system values for the territory and codepage:

set LANG=7

Parameter (UNIX)

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 command or shell prompt using the following syntax:

Windows:

run msgc /l filename

UNIX:

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:

Windows:

lang\<locale-name>

UNIX:

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 (Windows) or /lang/es_ES (UNIX) 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 Enterprise Developer, 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.

Interface Mapping Toolkit (IMTK)
Starting with a native COBOL program, you can create Web services that use either the SOAP or JSON protocol by mapping a service interface from which to generate Web service components. You can further run these Web services on Enterprise Server and access them via a generated COBOL console client and, depending on the type of Web service, by additional client types. See Interface Mapping Toolkit (IMTK ) for details.
Note: Enterprise Server supports document/literal, RPC/encoded, and REST encoding styles.
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
Related concepts
Interface Mapping Toolkit (IMTK)


Interface Mapping Toolkit (IMTK)

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

The IMTK enables you to create an interface between a legacy COBOL application running on an ESI as a service, such as a Web service or Java service, and a non-COBOL client, such as a Web service client or a JSP client. The interface you create is called a service interface. In your service interface, you can expose as much or as little of the original legacy application functionality as you choose. Because legacy applications often perform a wide variety of functions, the creation of a service interface enables you to limit your end users to access only the functions they need.

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

  • Java Interface
  • Web Service from WSDL
  • Web Service from request-response JSON schemas
  • RESTful Web Service from JSON schema
Attention: To deploy or generate a client for a Java Interface, you must install and configure the Java JDK and a Java application server. See the Application Server JCA support for Enterprise Server section in the Additional Software Requirements on Windows topic.

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

  • Creating and configuring an enterprise server instance to run the legacy application as a service
  • Creating a service interface in an Enterprise Developer project
  • Defining the details of the service interface using the Interface Mapper
  • Deploying the legacy application and service interface to your enterprise server instance
  • Generating one or more clients to access the service running on the enterprise server instance
  • Managing IMTK Projects
    Describes the project features that enable you to create, deploy, and run services.
  • Defining Service Interfaces
    Describes the tools provided in Enterprise Developer that enable you to define service interfaces.
  • Deploying Service Interfaces
    Explains the process of deploying a service interface and its legacy application to run as a service on an enterprise server instance.
  • Clients
    Describes the types of client applications you can generate for service interfaces and the methods you can use to generate them.
  • How to
    Topics that provide step-by-step instructions on how to create, define, manage, and deploy service interfaces using the IMTK.
  • Reference
    Reference information for service interfaces and the Interface Mapper.
Parent topic: COBOL Programming
Related concepts
Additional Software Requirements on Windows
Tutorials: Interface Mapping Toolkit
Web Services Support for Native COBOL


Managing IMTK Projects

Describes the project features that enable you to create, deploy, and run services.

Before you can use the IMTK, you must first create an Eclipse project using the Enterprise Server Application template. Once the project is in place, you can use Eclipse functionality to do the following:

  • Add appropriate files to the project, such as COBOL programs and copybooks for a COBOL Program service interface
  • Create a new service interface
  • Import an existing service interface that was either created using older software such as Net Express, or that is part of a different project
  • Set service interface properties and deployment options
  • Edit existing service interfaces
  • Validate service interfaces
  • Update service interfaces after making changes to a program or copybook
  • Deploy service interfaces to run as services on an enterprise server instance
  • Generate clients to access deployed services
Parent topic: Interface Mapping Toolkit (IMTK)
Related tasks
Manage IMTK Projects


Defining Service Interfaces

Describes the tools provided in Enterprise Developer that enable you to define service interfaces.

The Interface Mapper is the tool that enables you to define your service interfaces. You can define a service interface for a COBOL application from the COBOL source code. The service interfaces you define can cover a broad range – from those that provide access to a subset of the functions performed by your application, to interfaces that do more than your application in its original form. This is done by associating, or "mapping", the fields in your legacy application to the fields you create in the service interface.

The following topics describe the Interface Mapper and the operations you define with it.

  • Interface Mapper
    Describes the components of the Interface Mapper and explains the purpose of each.
  • Operations
    Describes service interface operations created using the Interface Mapper.
Parent topic: Interface Mapping Toolkit (IMTK)
Related tasks
To create a COBOL program-based service interface
Define Service Interfaces


Interface Mapper

Describes the components of the Interface Mapper and explains the purpose of each.
Restriction: This topic applies to Windows environments (local development) only.

The Interface Mapper user interface for COBOL Program service interfaces is split into two parts. The left side shows COBOL LINKAGE section fields, and the right shows interface fields, reusable fields, and COBOL assignments.

Note: To see the Reusable Fields and COBOL Assignments panes, you must turn them on. See To set Interface Mapper preferences.
Linkage Section pane
Shows the selected Linkage Section from the selected COBOL legacy program.
Interface Fields pane
In the Interface Fields pane, you define the details of each field you want to include in your service interface. Each interface field corresponds to a COBOL field shown in the Linkage Section pane. Only the interface fields for the current operation show in this pane.

The most straightforward way to create an interface field from a COBOL field is by dragging a COBOL field from the Linkage Section pane and dropping it onto the Interface Fields pane. This creates a mapping between the COBOL field and the new interface field. From the Interface Fields pane, you can further define the details for that field as it is used by the service interface.

Reusable Fields pane
This pane is primarily for convenience. In it, you create fields you want to use across operations. Then, for each operation in which you want to use one of these fields, drag and drop it from the Reusable Fields pane to the Interface Fields pane. The contents of the Reusable Fields pane does not change from operation to operation in a single service interface.

The Type of interface field created derived from the name of the reusable field. For example, if you create a reusable field named MyReusableField and then drag and drop it into the Interface Fields pane, the value in the Type column for that field is MyResuableField.

COBOL Assignments pane
Shows COBOL assignment you create for the service interface. Use a COBOL assignment to define the path taken by the legacy application for the current operation by providing a unique parameter value. This enables you to perform a different function from each operation even if all operations use the same entry point. The program takes a different path depending on the value of a parameter. Instead of defining an interface field to map to that parameter, place the value here that makes the program take the required path.
Parent topic: Defining Service Interfaces
Related tasks
To edit field properties
To create a reusable field
To assign a value to a COBOL field
To map an interface field
To set Interface Mapper preferences
Define Service Interfaces


Operations

Describes service interface operations created using the Interface Mapper.

Once you have initially created the service interface, you define its functionality by creating a series of operations using the Interface Mapper. Generally, an operation represents an interaction with a single program entry point. In the Interface Mapper, you work with one operation at a time.

A single service interface typically contains multiple operations. For example, if you know that a single entry point leads to an EVALUATE statement choosing between different functions, you could define a separate operation for each one of these functions. Often in such a program, one parameter is a parameter tested by the EVALUATE statement to see which function is specified.

All operations are packaged together into one service, but each operation is independently executable (i.e., only one operation is invoked per service execution).

Parent topic: Defining Service Interfaces
Related tasks
To create a COBOL program-based operation
Define Service Interfaces


Deploying Service Interfaces

Explains the process of deploying a service interface and its legacy application to run as a service on an enterprise server instance.

You can use the Interface Mapping Toolkit (IMTK) feature of Enterprise Developer to create COBOL service interfaces of various types, such as SOAP and JSON Web services and COBOL Enterprise Java Beans (EJBs). Once created, you can also use the IMTK to deploy a service interface to an enterprise server instance where it runs and becomes accessible. The deployment process includes packaging a service interface, and optionally packaging program objects and other files used by it, into a deployment package called a COBOL Archive (CAR) file that is then transmitted to a local or remote enterprise server instance where the service is installed into that instance. This process is known as service interface deployment.

Note: The service interface deployment process deploys both the legacy application and the service interface.
  • Deployment Configuration Requirements
    Describes Web Service property settings and enterprise server instance configuration requirements for successful deployment of the different types of supported COBOL Program service interfaces.
  • Service Interface Deployment Methods
    Describes the methods you can use to deploy a service interface.
  • 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.
  • Deploying Java Service Interfaces
    Describes the additional requirements associated with deployment of a Java-type service interface.
  • Deploying to 64-bit Platforms
    Describes the requirements for deploying service interfaces to a 64-bit platform.
  • Deploying to an Enterprise Server under UNIX
    Describes the process of deploying a service interface to a remote enterprise server instance running on UNIX.
  • Service Interface Deployment Package
    Describes the files generated by Enterprise Developer when you deploy a service interface.
Parent topic: Interface Mapping Toolkit (IMTK)
Related tasks
Deploy Service Interfaces to Enterprise Server


Deployment Configuration Requirements

Describes Web Service property settings and enterprise server instance configuration requirements for successful deployment of the different types of supported COBOL Program service interfaces.

Web Service Properties

Before deploying a COBOL Program service interface, ensure that you have set the Web Service properties appropriate for the type of service interface. Generally, you can accept the default properties; however, you might need to make some adjustments for the following:

All COBOL Program service interfaces
The Endpoint URL port number is 9003 by default and must match the Endpoint Address port number specified for the Web Services and J2EE listener of the associated enterprise server instance. If you change the Endpoint Address, be sure to update the Endpoint URL property to match.

See To set deployment properties for instructions on making changes to Web Service properties.

Enterprise Server Requirements

Enterprise Server provides a default enterprise server instance, ESDEMO, that is configured to run COBOL program-based services. However, if you want to create and configure an enterprise server instance to use specifically for your service, follow the steps outlined in To create a new enterprise server, and use the ESTemplate.xml template.

Web Services and J2EE listener
You need to adjust the Web Services and J2EE listener configuration of your enterprise server instance by providing an Endpoint Address port number that matches the Endpoint URL port number specified in your Web Service properties. The default Endpoint URL port number is 9003. See To set a fixed port in a listener endpoint address for details.
Note: If you decide to use a port other than 9003, be sure to update the Endpoint URL port number in your Web Service properties.

Also, depending on the type of service, you might need to change the supported conversion type for the Web Services and J2EE listener. This setting is on the same page as Endpoint Address. Use the following table as a guide:

Service Type | Conversion Type
SOAP | SOAP and J2EE (legacy)
Java (EJB) | SOAP and J2EE (legacy)
REST | Web Services and J2EE
Other Considerations
Before deploying a service interface, ensure that you have addressed each of these items:
  • Start the enterprise server instance.
  • If your enterprise server instance runs in 64-bit, and you deploy from a Windows 32-bit system, then the service driver program is not compiled and the compiled service driver program is not included in the deployment package. However, the COBOL source for the service driver program is always included in the deployment package. You must recompile the COBOL source for 64-bit; then copy the compiled program to the enterprise server instance. See Compiling Native COBOL Programs for 64-Bit for instructions.
  • If your enterprise server instance is running on a remote UNIX installation of Enterprise Server, you can still deploy to that enterprise server; however, after you deploy, you must then compile the generated driver program for your service on the platform where Enterprise Server is running. See To compile a service driver program on a remote UNIX machine for instructions.
Parent topic: Deploying Service Interfaces
Related concepts
Configuring and Administering Enterprise Server Instances
Service Interface Deployment Package
Deploying to 64-bit Platforms
Related tasks
To compile a service driver program on a remote UNIX machine
To set deployment properties


Service Interface Deployment Methods

The following scenarios cover four possible deployment methods:

Deploy from your Eclipse project
This is the easiest and most straightforward way to deploy. Enterprise Developer provides a service interface Deploy option that automatically generates a deployment package (.car file) and installs it on the enterprise server instance associated with your project. See To generate and deploy a service interface from a project for instructions.
Deploy using the imtkmake command
The imtkmake command enables you to generate a deployment package (.car file) and deploy it to Enterprise Server from the command line. See To deploy a service interface using imtkmake and imtkmake command for details.
Deploy using the mfdepinst command
Use the mfdepinst command to install an existing deployment package to Enterprise Server without generating a new deployment package. This enables you to deploy the same .car to multiple enterprise server instances. See To install a deployment package using mfdepinst and mfdepinst command for details.
Deploy manually
While we recommend that you use one of the first two deployment scenarios, it is possible to perform all the deployment steps manually without a deployment package. You can create all the necessary pieces, copy them manually to the Enterprise Server system, and add package and service objects to the configuration from the Micro Focus Directory Server interface. For more information, see Work with Packages and Work with Services.
Note: EJB service interfaces require, in addition to deploying the service interface to Enterprise Server, that you also deploy the EJB and JSP client to a Java application server. See Deploying Java Service Interfaces and JSP Client for more information.
Parent topic: Deploying Service Interfaces
Related concepts
Deploying Java Service Interfaces
Service Interface Deployment Package
Deploying to 64-bit Platforms
Security Considerations for Service Interface Deployment
Work with Packages
Work with Services
Related tasks
To generate and deploy a service interface from a project
To deploy a service interface using imtkmake
To install a deployment package using mfdepinst
To deploy to a remote enterprise server
To redeploy a service interface
Related reference
imtkmake command
mfdepinst command
Mapping Properties - Deployment Server Tab


Security Considerations for Service Interface Deployment

The ability to deploy a service interface to Enterprise Server poses security risks. An attacker with network access to an enterprise server instance could use service interface deployment to upload and execute arbitrary programs under Enterprise Server, replace an existing service with a malicious implementation, or retrieve information about existing services. To mitigate these risks you can disable or restrict deployment to an enterprise server instance.

Disabling deployment

A deployed service interface running on an enterprise server instance uses a communications listener. This listener 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 Eclipse IDE can supply these credentials when they deploy. With the imtkmake command-line utility, they can be supplied using the username and password parameters. For the web-deploy.html deployment web page, the browser will prompt for credentials if the listener is configured to require them.
  • Certificate Authentication: If the deployment listener is configured to use SSL/TLS, and to require or allow client certificates, the deployment client can send a client certificate to the server. The server can be configured to associate this certificate with a specific user. For the IDE and imtkmake, the client certificate can be configured in mf-client.dat. When deploying with a browser and web-deploy.html, the client certificate will have to be configured using the browser's certificate management interface. Client certificates can be associated with users using the cascertreg utility or by automatic registration (see Deployment listeners).

Recommendations

Micro Focus recommends you consider the following:

  • Do not enable deployment through the Web listener if you are using Enterprise Server for mainframe emulation only, including CICS Web Services.
  • 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: Deploying Service Interfaces
Related concepts
Service Interface Deployment Methods
Related tasks
To generate and deploy a service interface from a project
To deploy a service interface using imtkmake
To install a deployment package using mfdepinst
To deploy to a remote enterprise server
To redeploy a service interface
Related reference
imtkmake command
mfdepinst command
Related information
Deployment Listeners


Deploying Java Service Interfaces

Describes the additional requirements associated with deployment of a Java-type service interface.

When you deploy a Java service interface from Enterprise Developer, the deployment process creates a deployment package (.car) file. This file is installed on Enterprise Server.

The EJB and JSP client are generated simultaneously from Enterprise Developer, and are packaged into a Java .ear file. Because the EJB and JSP client run under a third-party Java application server, you must deploy the generated Java .ear file to the application server.

ED generates a .car file when you deploy the svi to your ESI. When you are ready to put the service interface into a production environment, you must also deploy the EJB and optionally, a JSP client, to the Java application server of your choice.

Once a Java service interface is ready for use in a production environment, you should deploy it to an enterprise server using the .car file generated during the last deployment. You can either use the mfdepinst command to deploy the .car file, or you can deploy it manually.

Depending on the Java application server you are using, additional deployment tasks are likely required. We recommend that you become familiar with these by reviewing the topics contained in the Deploying EJBs and Resource Adapters documentation.

Be mindful of the following as well:

  • If the service has been mapped as an EJB interface, you might need to perform one or both of the following tasks in addition to deploying the .car file:
    • Deploy the EJB to a Java application server
    • Deploy a resource adapter
  • Some Java application servers require that you set some deployment options that tell Enterprise Developer what application server to use and where to find certain files. For more information, see your application server documentation, and the To set deployment properties and To modify the CLASSPATH property for a Java-based service interface topics.
  • For some Java application servers, you might be required to select which application files to deploy, and select one or more deployment locations. See To add or remove application files to deploy for more information.
  • If you generate a client for your Java service, the .car file is deleted from the deployment folder. When setting up your service in a production environment, be sure to deploy this file before generating a client.
Note: To learn about alternative deployment methods, see Service Interface Deployment Methods.
Parent topic: Deploying Service Interfaces
Related concepts
Service Interface Deployment Methods
Deploying EJBs and Resource Adapters
Related tasks
To modify the CLASSPATH property for an EJB service interface
To set deployment properties
To add or remove application files to deploy
To Deploy a Micro Focus Resource Adapter to a Java Application Server
Deploy to Java EE Application Servers
Related reference
mfdepinst command


Deploying to 64-bit Platforms

Describes the requirements for deploying service interfaces to a 64-bit platform.

A service interface is only compiled and included as part of the deployment package when the target enterprise server is running in the same working mode as the development environment. For example, if you deploy from a Windows 32-bit system to a 64-bit enterprise server, then the service driver program is not compiled and the compiled service driver program is not included in the deployment package. However, the COBOL source for the service driver program is always included in the deployment package, allowing for recompilation on the target server platform.

Parent topic: Deploying Service Interfaces
Related concepts
Service Interface Deployment Methods
Deployment Configuration Requirements
Related tasks
To generate and deploy a service interface from a project
Related reference
imtkmake command


Deploying to an Enterprise Server under UNIX

Describes the process of deploying a service interface to a remote enterprise server instance running on UNIX.

If your enterprise server instance is running on a remote UNIX installation of Enterprise Server, you can still deploy a service to it; however, after you deploy, you must then compile the generated driver program for your service on the platform where Enterprise Server is running. For details, see To deploy to a remote enterprise server.

Parent topic: Deploying Service Interfaces
Related tasks
To generate and deploy a service interface from a project
To deploy a service interface using imtkmake
To install a deployment package using mfdepinst
To deploy to a remote enterprise server
To redeploy a service interface
Related reference
The cobol command


Service Interface Deployment Package

Describes the files generated by Enterprise Developer when you deploy a service interface.
A service interface deployment package is generated when you deploy, and is contained in a COBOL Archive (.car) file. This is a standard zip archive that includes the following:
manifest file
An XML document that contains deployment information such as the name of the service and a description of the .car file.
interface definition table
A file that describes the service interface. The file extension is .idt.
specified package files
Other files optionally added to the package.

The name of a deployment package file is myService.car where myService is the name of your service interface. By default, Enterprise Developer generates the .car file in your project's repos\myService.deploy directory.

Parent topic: Deploying Service Interfaces
Related concepts
Service Interface Deployment Methods
Deployment Configuration Requirements
Related tasks
To deploy a service interface using imtkmake
To install a deployment package using mfdepinst
Related reference
imtkmake command
mfdepinst command


Clients

Describes the types of client applications you can generate for service interfaces and the methods you can use to generate them.

You can use a generated client to test a service, or to access a service in production.

  • COBOL Console Client
  • JSP Client
Parent topic: Interface Mapping Toolkit (IMTK)
Related tasks
To generate client applications from a service interface file


COBOL Console Client

With the exception of Java interfaces, all other service types automatically generate a COBOL console application client. As part of client generation, a proxy program is also generated. The proxy provides a standard mechanism for invoking the service, and is intended for use by production clients.

Client folder

After generation, Enterprise Developer adds a client application folder to the project that contains the following components:

myService-app.cbl
The generated client COBOL program.
myService-proxy.cbl
A COBOL program for invoking the service via a production client.
myService-copy.cpy
A copybook used by the both the -app and -proxy programs.

Editing a console client program

To enhance its appearance and usability, you can optionally edit a console client program using the Enterprise Developer COBOL editor, or any text editor.

Running a console client

You can run a console client directly from your project using the Enterprise Developer Debugger. Before doing so, ensure that:

  • The enterprise server instance is started
  • Your service interface is deployed to the enterprise server instance
  • You have defined a COBOL Enterprise Server Debug Configuration that specifies the following:
    • The project that contains your service interface (.svi) file
    • The enterprise server instance configured to run the service
    • That the debugging type that corresponds to the type of service is configured properly
  • The COBOL application is started in the Debugger

Once these things are in place, return to the Team Developer View. Right-click the service interface entry in the project's client folder; then select Debug As > COBOL Application from the context menu.

Parent topic: Clients
Related concepts
Deploying Service Interfaces
Related tasks
To generate client applications from a service interface file
To associate an enterprise server with a project


JSP Client

For an EJB to access a COBOL service running on an enterprise server instance, you must have the EJB and a JSP client running on an application server. You can generate both an EJB and a JSP client from the IMTK simultaneously, and then configure your application server to run them.

Important: During the generation process, the .car file that was created during deployment is deleted. Therefore, when setting up your Java service interface for production, you must deploy the .car file to Enterprise Server before generating a client. See Service Interface Deployment Methods and Service Interface Deployment Package for more information.

The generated EJB and JSP client are packaged into archive files (.jar, .war, and .ear), together with manifest files and deployment descriptors. These files are located in the structure under your project's myService.deploy directory, where myService is the name of your service interface. You can view the contents of and/or extract individual files from these archives using the jar command or a zip utility. The following archive files are created:

EJB Jar Archive
The myService.jar archive contains the EJB classes and additional required files:
ejb-jar.xml | Generic deployment descriptor, defining the EJB
myServiceBean.class | Bean class for the EJB
myServiceHome.class | Home interface for the EJB
myService.class | Remote interface for the EJB
myRecord.class | custom record, if needed by the EJB
manifest.mf | Manifest describing this .jar file
*.xml, such as weblogic-ejb-jar.xml | For some Java application servers (such as WebLogic), a deployment descriptor for deploying the EJB to that application server

The source code for the EJB classes are generated in the directory com\mypackage\myService.

Client War Archive
The myService.war archive contains the JSP class files and other required files:
*.jsp | JSP files. These pass data back and forth between the end user and the servlet.
myServiceJspBean.class | This file contains the getter and setter methods that are used to move information back and forth between the servlet and JSP.
myServiceServlet.class | This file is the servlet. It processes the incoming requests from the JSP, invokes an instance of the stateless EJB, and forwards the response back to the JSP.
myServiceSessionMonitor.class | This is a helper class, which stores the EJB instances for the stateful session bean.
manifest.mf | Manifest describing this .war file
mfejlib.jar | .. custom records
web.xml | Generic deployment descriptor, defining the client servlet and the EJB reference
*.xml, such as weblogic.xml | For some Java application servers (such as WebLogic), a deployment descriptor for deploying the .war file to that application server
Application Ear Archive
The myService.ear archive contains the other two archive files and additional required files. This archive contains everything you need to deploy the EJB to supported third-party application servers, without further changes.
Attention: You must deploy this .ear file to your Java application server.
application.xml | Generic deployment descriptor, defining the .jar and the client .war files
myService.jar | EJB Jar archive file
myService.war | Client War archive file
manifest.mf | Manifest describing this .jar file
mfejlib.jar | Custom records

Editing a JSP client component

To enhance its appearance and usability, you can optionally edit a JSP client. Before attempting to do so, you should first extract the JSP file from the myService.war archive file found in the deployment folder for your project.

Note: If you edit the JSP file, add it back to the .war archive and save a copy of it to another location to ensure it does not get overwritten if you decide to redeploy the service interface.

Running a JSP client

  • The enterprise server instance is started
  • Your service interface is deployed to the enterprise server instance.
  • The generated .ear file is deployed to your Java application server.
  • You have defined a COBOL Enterprise Server Debug Configuration that specifies the following:
    • The project that contains your service interface (.svi) file
    • The enterprise server instance configured to run the service
    • That the debugging type that corresponds to the type of service is configured properly
  • The COBOL application is started in the Debugger
Note: If you are using an unsupported Java application server, you need to create deployment descriptors manually. See your application server documentation for more information. For a list of supported application servers, see the Application Server JCA support for Enterprise Server section in the Additional Software Requirements on Windows topic. See also To Create Deployment Descriptors Manually for further instructions.
  • Application Ear File
  • Client War File
  • EJB Jar File
Parent topic: Clients
Parent topic: Deploying a Java Service Interface and Using Resource Adapters
Related concepts
Deploying Service Interfaces
Additional Software Requirements on Windows
Service Interface Deployment Methods
Related tasks
To generate client applications from a service interface file
To associate an enterprise server with a project
To Create Deployment Descriptors Manually


How to

Topics that provide step-by-step instructions on how to create, define, manage, and deploy service interfaces using the IMTK.
Restriction: This topic applies to Windows environments only.
  • Manage IMTK Projects
    Tasks related to managing IMTK projects within Eclipse.
  • Define Service Interfaces
    Tasks related to using the Interface Mapper.
  • Deploy Service Interfaces to Enterprise Server
    Tasks related to deploying service interfaces to Enterprise Server.
Parent topic: Interface Mapping Toolkit (IMTK)


Manage IMTK Projects

Restriction: This topic applies to Windows environments only.
  • To set a run-time environment variable
  • To create a COBOL program-based service interface
  • To modify the CLASSPATH property for an EJB service interface
  • To update service interfaces with source code changes
  • To set Interface Mapper preferences
  • To validate a service interface
Parent topic: How to
Related concepts
Managing IMTK Projects


To create a COBOL program-based service interface

Restriction: This topic applies to Windows environments only.
  1. In the Team Developer view, right-click a project name; then select New > Interface.
  2. From the context menu, select the type of service interface you want to create: Java interface, SOAP Web Service, or REST Web Service.

    This invokes a Wizard that corresponds to the type of interface or Web service you selected.

  3. Complete the fields on the Wizard; then click Finish.

    For a description of each field and control on the Wizard, see the corresponding Related reference listed below.

The Team Developer view shows a new folder for the Web Service or Java Interface and its associated files.

Parent topic: Manage IMTK Projects
Related concepts
Defining Service Interfaces
Related tasks
To start the Interface Mapper
Related reference
New Java Interface Wizard
New REST Web Service Wizard
New SOAP Web Service Wizard


To modify the CLASSPATH property for an EJB service interface

Restriction: This topic applies to Windows environments only.
  1. In the Team Developer view, right-click a Java interface; then and select Java Properties from the context menu.
  2. On the EJB Generation tab, do one of the following:
    • Type the appropriate paths and filenames into the J2EE Class Path field, each separated by a semicolon (;).
    • Click the Browse button that corresponds to the J2EE Class Path field; then use the Classpath Selection dialog box to select each file you want to include.
Parent topic: Manage IMTK Projects
Related concepts
Deploying Java Service Interfaces


To update service interfaces with source code changes

Restriction: This topic applies to Windows environments only.

After generating a service interface and then subsequently making changes to the COBOL linkage section used to generate it, you should then use the Refresh Resources feature to update the service interface with the changes. We provide two methods:

Refresh resources from the the Team Developer view
  • In the Team Developer view, right-click a project; then select Refresh Resource from the context menu.
Refresh resources from the COBOL editor
  • In the COBOL editor, save your changes; then press F5.
Parent topic: Manage IMTK Projects


To set Interface Mapper preferences

Restriction: This topic applies to Windows environments only.
  1. From the Main Menu, click Window > Preferences.
  2. Expand Micro Focus > Interface Mapper, and click General.
  3. Check one or both of Show Reusable Fields pane and Show COBOL Assignments pane; then click OK.
Parent topic: Manage IMTK Projects
Related concepts
Interface Mapper


To validate a service interface

Restriction: This topic applies to Windows environments only.
  1. From the Team Developer view, right-click the service interface you want to validate, and click Validate. Errors are reported in the Error Log view.
  2. If an error is reported:
    1. Double-click the error to open the Interface Mapper.
    2. Correct the error.
    3. Close the Interface Mapper.
    4. Repeat this process until the Console shows the message "The service mappings are valid."
Parent topic: Manage IMTK Projects


Define Service Interfaces

Restriction: This topic applies to Windows environments only.
  • To assign a value to a COBOL field
  • To create a COBOL program-based operation
  • To create a reusable field
  • To create an interface field
  • To edit field properties
  • To group interface or reusable fields
  • To map an interface field
  • To start the Interface Mapper
Parent topic: How to
Related concepts
Interface Mapper
Defining Service Interfaces
Operations


To assign a value to a COBOL field

Restriction: This topic applies to Windows environments only.
  1. From the Interface Mapper Linkage Section pane, drag a field to the COBOL Assignments pane.
  2. In the Value field, type a literal value to assign to the field specified in the Name field.
Note:
  • If you drag a group field, the COBOL Assignment dialog box opens for each elementary item in turn. You can click Cancel if you do not want to set values for all of them.
  • You can also create a COBOL Assignment field by right-clicking in the COBOL Assignments pane and selecting New Assignment from the context menu.
Related concepts
Interface Mapper
Related reference
COBOL Assignment


To create a COBOL program-based operation

Restriction: This topic applies to Windows environments only.
  1. In COBOL Explorer, right-click the service interface to which you want to add an operation, and click New > Operation.
  2. Define the new operation by specifying:
    • A name for the new operation
    • An entry point, which you select from the list of entry points available in the program
Parent topic: Define Service Interfaces
Related concepts
Operations
Related reference
Operation Properties - General tab
Operation Properties - User Exits tab
Operation Reorder
Operation Properties - HTTP tab


To create a reusable field

Restriction: This topic applies to Windows environments only.
  1. In the Interface Mapper Reusable Fields pane, right-click, then click New Reusable Field from the popup menu.
  2. Complete the fields and click OK.

Alternatively, to create a reusable field from an existing field, drag an existing field from the Linkage Section pane and drop it in the Reusable Fields pane.

Parent topic: Define Service Interfaces
Related concepts
Interface Mapper


To create an interface field

Restriction: This topic applies to Windows environments only.

You can create an interface field using any of these methods:

Drag and Drop
  • From the Interface Mapper, drag a field from the Linkage Section pane and drop it in the Interface Fields pane.
Note:
  • Interface fields created using the Drag and Drop method are automatically mapped to the originating field.
  • The Direction property for an interface field created using the Drag and Drop method is automatically set to Input by default.
Linkage Section context menu
  1. In the Linkage Section pane, right-click the originating field and select New Interface Field from the context menu.
  2. Define field properties as required; then click OK.
Interface Fields context menu
  1. In the Interface Fields pane, right-click and select New Interface Field from the context menu. In this case, a default mapping is not generated for the new interface field. Therefore, be sure to map the new field manually.
  2. Define field properties as required; then click OK.
Main Menu
  1. In the Interface Mapper, click in the Interface Fields pane.
  2. From the main menu, click FIELD > New Interface Field.
  3. Define field properties as required; then click OK.
Note: For a description of each field and control on the Field Properties dialog box, see Field Properties.
Parent topic: Define Service Interfaces
Related reference
Field Properties


To edit field properties

Restriction: This topic applies to Windows environments only.
  1. In the Interface Mapper, right-click a field in the Interface Fields pane and click Properties from the popup menu.
  2. Specify the appropriate properties; then click OK.
Related reference
Field Properties


To group interface or reusable fields

Restriction: This topic applies to Windows environments only.
  1. In the Interface Mapper Interface Fields or Reusable Fields pane, select the fields you want to group. Hold the Shift or Cntl key as you click to select more than one.
  2. Right-click any selected field and click Group from the popup menu.
  3. Type a name for the group into the Name field.
  4. Type the number of times you want the group to occur into the Occurs field.
  5. Click Input or Output to set a direction for the entire group, if applicable.
Note: To ungroup previously grouped fields, right-click the group name and click Ungroup from the popup menu.
Parent topic: Define Service Interfaces
Related concepts
Interface Mapper
Related reference
Group Properties


To map an interface field

Restriction: This topic applies to Windows environments only.
  1. In the Interface Mapper, right-click an interface field on the Interface Fields pane and click Mapping from the popup menu.
  2. From the COBOL fields list, click a field you want to map to your interface field.
  3. Click Add.
  4. Repeat steps 2 and 3 for each additional field you want to map.
  5. Click OK.
Parent topic: Define Service Interfaces
Related concepts
Interface Mapper
Related reference
Mappings


To start the Interface Mapper

Restriction: This topic applies to Windows environments only.
  • In COBOL Explorer, double-click an operation for a service interface.
Note: Immediately after you create a new service interface, the Interface Mapper starts automatically.
Parent topic: Define Service Interfaces
Related tasks
To create a COBOL program-based service interface


Deploy Service Interfaces to Enterprise Server

Restriction: This topic applies to Windows environments only.
  • To add or remove application files to deploy
  • To associate an enterprise server with a project
  • To compile a service driver program on a remote UNIX machine
  • To generate and deploy a service interface from a project
  • To deploy to a remote enterprise server
  • To deploy a service interface using imtkmake
  • To generate client applications from a service interface file
  • To install a deployment package using mfdepinst
  • To redeploy a service interface
  • To set deployment properties
Parent topic: How to
Parent topic: Enterprise Server Task Index
Related concepts
Deploying Service Interfaces


To add or remove application files to deploy

Restriction: This topic applies to Windows environments only.
  1. In the Team Developer view, right-click a Web Service; then select Web Service Properties.
  2. On the Application Files tab, click Legacy application needs deploying.
  3. Add or remove application files as required.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Deploying Java Service Interfaces
Related reference
Mapping Properties - Application Files Tab


To associate an enterprise server with a project

Restriction: This topic applies to Windows environments only.
  1. In Server Explorer, expand Micro Focus Servers to see a list of available enterprise server instances.
  2. Right-click the enterprise server instance with which to associate the project; then click Associate with project > projectName.
Note: Associate with project is a toggle that switches on and off by checking or unchecking the project name.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
COBOL Console Client
JSP Client
Related tasks
To generate and deploy a service interface from a project


To compile a service driver program on a remote UNIX machine

Restriction: This topic applies to Windows environments only.
  1. Log on to the target machine.
  2. Go to the package path folder. If you are using a telnet session originating from your development machine, you can paste the package path from the clipboard.
  3. Compile the service driver source using the cobol command.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Deployment Configuration Requirements
Related reference
The cobol command


To generate and deploy a service interface from a project

Restriction: This topic applies to Windows environments only.
  1. From Eclipse, associate an enterprise server instance with the project containing the service interface you want to deploy.
  2. Start the enterprise server instance.
  3. Ensure that you have set all appropriate properties for service interface deployment.
  4. In COBOL Explorer, right-click your service interface; then select Deploy on the context menu.
Note:
  • Enterprise Server Administration lists your deployed service as a service of the enterprise server running your application. You must delete the service from your enterprise server before you can redeploy it.
  • You can also deploy your service interface to an enterprise server running under UNIX.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Deploying to 64-bit Platforms
Service Interface Deployment Methods
Security Considerations for Service Interface Deployment
Deploying to an Enterprise Server under UNIX
Related reference
imtkmake command
Username/Password
Related information
To associate an enterprise server with a project


To deploy to a remote enterprise server

  1. In the Server Explorer, right-click Micro Focus Servers, and select MFDS Administration from the context menu.
  2. Specify either the Host name or the IP address of the remote server.
  3. In the Port field, type the number of the port you want to use (default is 86); then click OK.
Important: After deploying to a remote UNIX server, you must then compile the service driver program on the target UNIX machine:
  1. Log on to the target machine.
  2. Go to the package path folder. If you are using a telnet session originating from your development machine, you can paste the package path from the clipboard.
  3. Compile the service driver source using the cobol command.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Service Interface Deployment Methods
Security Considerations for Service Interface Deployment
Deploying to an Enterprise Server under UNIX


To deploy a service interface using imtkmake

Restriction: This topic applies to Windows environments only.
  1. Start an Enterprise Developer command prompt.
  2. Change to the directory that contains your service interface (.svi) file.
  3. Enter the following:
    imtkmake -generate -deploy service=service-name type=service-type server=server-name,deployer-name [optional-parameters]
    where:
    service-name | The name of your service interface
    service-type One of:
    • EJB
    • J2SEbean
    • WebService
    • REST
    server-name | The name of the enterprise server to which you want to deploy the service interface
    deployer-name | The name of a deployment service on that enterprise server
    optional-parameters | Optional parameters available with the imtkmake command

See the imtkmake command reference topic for complete information.

Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Service Interface Deployment Methods
Security Considerations for Service Interface Deployment
Service Interface Deployment Package
Deploying to an Enterprise Server under UNIX
Related reference
imtkmake command


To generate client applications from a service interface file

Restriction: This topic applies to Windows environments only.

To generate a console and Java client:

  1. In the Application Explorer view, right-click a Java Interface; then click Generate Client from the context menu.

To generate a console and Web Services client from a service interface:

  1. In the Application Explorer view, right-click a Web Service; then click Generate Client from the context menu.
  2. Depending on how you want to store your generated client, do one of the following to specify the project:
    • Click No project.
    • Click Current project.
    • Click Select a COBOL project; and then type the project name in the Project receiving generated client field, or use the Select button to specify the project.
    • Click Create a new COBOL project; then provide a project name and location using the New COBOL Project dialog box.
  3. Type the path to the output directory into the Output directory field, or use the Browse button to specify a location.
    • For a REST services you can only generate a client from a JSON file:
      1. Check Use JSON.
      2. In the JSON file field, type the path and file name for the JSON file. Alternatively, click Browse and navigate to the JSON file.
      3. In the String size field, type the default string size to use for unbounded strings.
      4. In the Array size field, type the default array size to use for unbounded arrays.
    • For a SOAP service you can only generate a client from a WSDL file:
      1. Check Use WSDL.
      2. In the WSDL file field, type the path and file name for the WSDL file. Alternatively, click Browse and navigate to the WSDL file.
      3. In the String size field, type the default string size to use for unbounded strings.
      4. In the Array size field, type the default array size to use for unbounded arrays.
      Note: The location you can browse to find the WSDL or JSON files is consistent with the project type, that is, a remote project can only browse the remote machine.
  4. Click OK.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Clients
COBOL Console Client
JSP Client
Related reference
imtkmake command


To install a deployment package using mfdepinst

  1. If you don't already have one, generate a COBOL archive (.car) file by either deploying a service interface from an Enterprise Developer project or using the imtkmake command.
  2. Copy the .mfdeploy file, located by default in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\deploy (Windows) or $COBDIR/deploy (UNIX), to the parent directory of the .car file that you want to deploy. For example, if the .car file is in %COBDIR%\deploy\test (Windows) or $COBDIR/deploy/test (UNIX), the .mfdeploy file must be copied to %COBDIR%\deploy (Windows) or $COBDIR/deploy (UNIX).
  3. Open the .mfdeploy file in a text editor, and edit the MFES_SERVER line. By default this is set to ESDEMO. Change it to specify the name of the enterprise server you want to use, as follows:

    MFES_SERVER=myserver

  4. Deploy the .car file using the mfdepinst command. For example, to deploy the services in myService.car, enter the following at a command prompt:
    mfdepinst myService.car

See the mfdepinst command reference topic for complete information.

Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Service Interface Deployment Methods
Security Considerations for Service Interface Deployment
Service Interface Deployment Package
Deploying to an Enterprise Server under UNIX
Related reference
imtkmake command
mfdepinst command


To redeploy a service interface

  1. Start Enterprise Server Administration.
  2. Delete the service from the enterprise server instance.
  3. Deploy the service using the deployment method of your choice.
  4. Confirm that the service has been successfully deployed by refreshing Enterprise Server Administration.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Service Interface Deployment Methods
Security Considerations for Service Interface Deployment
Deploying to an Enterprise Server under UNIX
Related tasks
To Delete a Service with Operations


To set deployment properties

Restriction: This topic applies to Windows environments only.
  1. From the Team Developer view, right-click a service interface; then click Java Properties or Web Service Properties.
  2. Modify property settings on each tab as required. For complete information on each property, see the Mapping Properties reference topics.
  3. Click OK.
Parent topic: Deploy Service Interfaces to Enterprise Server
Related concepts
Deploying Java Service Interfaces
Deployment Configuration Requirements
Related tasks
To set a fixed port in a listener endpoint address
Related reference
Mapping Properties - Deployment Server Tab
Mapping Properties - General Tab
Mapping Properties - EJB Generation Tab
Mapping Properties - Application Files Tab
Mapping Properties - J2SE Generation Tab
Mapping Properties - Mapping Properties Tab
Advanced Settings


Reference

Reference information for service interfaces and the Interface Mapper.
  • imtkmake command
    Enables you to create and deploy a COBOL program-based service interface, and generate a client application to access the service.
  • mfdepinst command
    Installs the service interface contained in deployment package (.car) file to an enterprise server.
  • COBOL to Service Interface Data Type Matches
    Describes which COBOL data types correspond to available Service Interface data types, including Web Services, and .NET and Java Interfaces.
  • User Interface Reference
    Provides help for the fields on each dialog box associated with service interface projects and the Interface Mapper.
Parent topic: Interface Mapping Toolkit (IMTK)


imtkmake command

Enables you to create and deploy a COBOL program-based service interface, and generate a client application to access the service.

Syntax:

imtkmake -defmap          service=service-name
                          src=program-name
                          type=service-type
                         [directives=Compiler-directives]
                         [settings=properties-filename]
                         [transactionAttribute=attribute]
imtkmake -generate        service=service-name
                          type=service-type
                         [appdir=directory-name]
                         [appserver=J2EE-application-server-name]
                         [archivename=arch-name]
                         [basePath=base-path]
                         [bean=bean-name]
                         [classpath=pathname]
                         [ejbInterfaceType={remote|local}]
                         [ejbname=ejb-name]
                         [ejbversion=3]
                         [esruntime=esruntime-filename]
                         [exithandler=program-name]
                         [filename]...
                         [@filelistname]
                         [j2eeVersion={1.4|1.5|5|1.6|6|1.7|7}]
                         [jarname=jar-filename]
                         [javacpath=java-dir]
                         [namespace=service-namespace]
                         [package=package-name]
                         [sepsession={stateless|stateful}]
                         [serverHost=host-name]
                         [serverPort=port-number]
                         [session={stateless|stateful}]
                         [settings=properties-filename]
                         [style={doclit|rpcenc}]
                         [transaction={application|container}]
                         [transactional={yes|no}]
                         [url=ip-address]
                         [version=version]
imtkmake -query
imtkmake -queryAppServerList
imtkmake -queryEJBDefaults
imtkmake -deploy          type=service-type
                         [carname=car-filename]
                         [ejbversion=3]
                         [password=secure-password]
                         [server=server-name,deployer-name]
                         [settings=properties-filename]
                         [username=secure-username]
imtkmake -showlog         deploydir=deployment-directory
imtkmake -genclient       service=service-name
                          type=service-type
                         [appserver=J2EE-application-server-name]
                         [basePath=base-path]
                         [classpath=java-class-path]
                         [clientdir=directory-name]
                         [j2eeVersion={1.4|{1.5|5}|{1.6|6}|{1.7|7}}]
                         [namespace=service-namespace]
                         [serverHost=host-name]
                         [serverPort=port-number]
                         [style={doclit|rpcenc}]
                         [url=ip-address]
                         [version=version]
imtkmake -genclientwsdl   clientwsdl=wsdl-filename
                         [clientdir=directory-name]
                         [defaultstringsize=string-size]
                         [defaultarraysize=array-size]

imtkmake -genclientjson   clientjson=json-filename
                         [clientdir=directory-name]
                         [defaultstringsize=string-size]
                         [defaultarraysize=array-size]

imtkmake -validate
imtkmake -help

Parameters:

-defmap
Create a service interface using default mappings based on the COBOL program specified in the src= parameter.
-generate
Generate deployment files based on the parameters set, and generate a COBOL archive (.car) file containing the generated files for deployment to the enterprise server.
-query
List the enterprise servers available for deployment.
-queryAppServerList
List the available J2EE 1.4 application servers by default. Specify the j2eeversion parameter to see application servers supported for other J2EE versions.
-queryEJBDefaults
Lists all the default EJB generation options.
-deploy
Deploy the .car file created with -generate parameter to the enterprise server. Execute imtkmake with the -deploy parameter from the servicename.deploy directory.
-showlog
Display the contents of the deployment log (deploylog.txt file).
-genclient
Generate a client from the service interface, according to the specified type, such as EJB or Web Services.
-genclientwsdl
Generate a COBOL client from WSDL.
-genclientjson
Generate a COBOL client from JSON Schema.
-validate
Validate the service interface.
-help
Display information about imtkmake functions and parameters.
archivename=arch-name
The full filename of the output archive file, which can be a .jar, .war, or .ear file.
appdir=directory-name
The path to the application files for the application running on the enterprise server.
appserver=J2EE-application-server-name
This is the name and version of the J2EE application server for which an EJB is generated and to which an EJB is deployed. This defines the deployment descriptors that are generated.

This is mandatory when generating EJBs and EJB clients. In other words, mandatory when using the -generate or -genclient functions with type set to EJB. The values must be within quotes since they contain spaces. For example:

  • "JBoss 5.1.0"
  • "WebSphere 7.0"

Note that this parameter must come after the other parameters.

See -queryAppServerList for how to list the available servers.

basePath=base-path
For REST services, the base path used in the URI of the service.
bean=bean-name
For EJB generation, the name of the bean to generate. Defaults to service-name.
carname=car-filename
The path to and name of the .car file to deploy. By default, this file is named servicename.car and is in the servicename.deploy directory. carname= is not required when you generate and deploy on the same command line.
classpath=java-class-path
The full path to the J2EE implementation classes on the J2EE application server, which is different for each J2EE application server and is the path to the following .jar files respectively:
  • JBoss jboss-j2ee.jar and servlet-api.jar
    Note: The names of these files might vary depending on the version of JBoss you are using.
  • Tomcat servlet-api.jar
  • WebSphere j2ee.jar
  • WebLogic weblogic.jar
Note: java-class-path is case sensitive.
clientdir=directory-name
The directory in which to generate the client program. With the -genclientwsdl or -genclientjson function, defaults to the WSDL or JSON Schema file directory; otherwise defaults to the servicename.deploy directory.
clientjson=json-filename
For REST services, the name of the JSON Schema file from which to generate the client program.
clientwsdl=wsdl-filename
The name of the WSDL file from which to generate the client program.
defaultarraysize=array-size
The default array size to use for unbounded arrays.
defaultstringsize=string-size
The default string size to use for unbounded strings.
deploydir=deployment-address
The URL of the deploylog.txt file. This URL is displayed by the -deploy function.
directives=Compiler-directives
The directives required for the program to compile correctly. Use a comma between directives.
ejbInterfaceType={remote|local}
The type of server on which the EJB runs - local or remote.
ejbname=ejb-name
For EJB generation, the name of the EJB to generate. Defaults to service-nameEJB.
ejbversion=3
Enable EJB version 3 support.
esruntime=esruntime-filename
The name of a file containing the run-time configuration settings to be applied when the deployed service is run. The file extension must be .rtc.
exithandler=program-name
For Web Services generation, the name of a user exit program to handle the exit points in the MFRHSOAP request handler.
@filelistname
The name of a file containing a list of additional files that need to be included in a .car file. Each file name must be on a new line.
filename
An additional file that needs to be included in a .car file. You can specify multiple additional files.
j2eeVersion={1.4|{1.5|5}|{1.6|6}|{1.7|7}}
The J2EE version. Paired options inside brackets ({}) are equivalent.
jarname=jar-filename
For EJB generation, the name of the .jar file to create. Defaults to service-name.jar.
javacpath=java-dir
The path to the javac.exe file.
namespace=service-namespace
For Web Services generation, EJB generation and client generation, the service namespace. Web Services generation and client generation defaults to http://tempuri.org/service-name. EJB generation defaults to service-name .
package=package-name
For EJB generation, the name of the package of Java classes to contain the bean. This is case-sensitive. Defaults to com.mypackage.service-name.
password=secure-password
The password to enable a service interface to be deployed to a secure server. This is required only when MFDS is configured to require it.
sepsession={stateless|stateful}
The setting for the associated SEP (Service Execution Process) attribute. SEP attributes are only meaningful when transactional=yes.
server=server-name,deployer-name
The destination of the deployment files. server-name is the enterprise server to which you want to deploy the service, and deployer-name is the name of a deployment service on that enterprise server. If you do not supply this parameter, the function lists the servers available for deployment and prompts you to choose one.
serverHost=host-name
For J2SE Java bean services, the name of the host machine that is running the enterprise server.
serverPort=port-number
For J2SE Java bean services, the port number of the enterprise server listener.
service=service-name
The name of the service for mapping or generation.
session={stateless|stateful}
For EJB generation, the type of EJB to generate. Defaults to stateless.
settings=properties-filename
The name of a file containing the set properties for this service interface.
src=program-name
The program used for creating default mappings.
style={doclit | rpcenc}
The style to use for WSDL generation. The default is doclit.
transaction={application|container}
Specifies whether the service is application-managed or transaction-managed. The default is application.
transactional={yes|no}
For EJB generation, whether or not the EJB service executes in a transactional context. When set to yes, session=stateful by default.
transactionAttribute=attribute
Transaction attribute used for EJB default mapping. Can be one of the following:
  • notSupported
  • mandatory
  • never
  • required
  • requiresNew
type=service-type
The type of mapping to perform or type of client to generate (see defmap, genclient and generate above), where service-type can be one of the following:
  • EJB
  • J2SEbean
  • WebService
  • REST
url=ip-address
For Web Services and client generation, the IP address of the service. This is added to the WSDL document or JSON Schema.
username=secure-username
The username that enables a service interface to be deployed to a secure server. This is required only when MFDS is configured to require it.
version=version
For REST services, the service version used in the URI of the service.

Comments:

  • Execute imtkmake from an Enterprise Developer command prompt in the directory that contains your COBOL program file.
  • This command performs several functions. You must execute the following against the same program in this order:
    • -defmap
    • -generate
    • -query (optional)
    • -deploy
    • -showlog (optional)
    • -genclient and/or -genwsdl (optional)
  • You can combine some functions on the same command line:
    • -defmap and -generate together, to create a service interface with default mappings and generate deployment files to be deployed at a later time.
    • -generate and -deploy together, to generate deployment files for an existing service interface, deploy them to an enterprise server.
    • -defmap, -generate, and -deploy together to perform all three functions.
    Note: When you combine two or more functions on the same command line, you do not need to repeat parameters that are common.
  • You can combine the use of the command line functions with the use of the Service Interfaces feature. For example, you might create the service interface and customize it. You could then use the command line to deploy the service interface.
  • You can create a mapping properties XML file that contains a list of the optional parameters associated with the -generate function, and then specify that file on the command line as a parameter for the -generate function. If you specify any of the same parameters on the command line itself, these override the values set for them in the mapping properties XML file.
  • You can use () as delimiters around parameters rather than = before them, for example, src(book.cbl) instead of src=book.cbl.
  • When you deploy a service interface using imtkmake -deploy, imtkmake uses the first instance of each deployable item found, in this order:
    • MFDS. If the deployment items are in MFDS, any configuration settings in the [destination] section are used. For example:
      [destination]
   server=ESDEMO
   listener=Web Services and J2EE
    • MFDS. If the deployment items are in MFDS, but there aren't any configuration settings, imtkmake uses the enterprise server that owns the service.

Examples:

The following command creates a service interface with default mapping for the program book.cbl:

imtkmake -defmap src=book.cbl service=wmapserv
                 type=webservice

The following command generates a Web service for the wmapserv service interface:

imtkmake -generate service=wmapserv
                   type=webservice
                   exithandler=myhandler
                   namespace=http://corpuri.org/wmapserv

The following command generates an EJB for the JMapServ service interface:

imtkmake -generate service=JMapServ
                   type=ejb
                   bean=JMap
                   classpath=/usr/java131/lib/j2ee.jar
                   ejbname=JMapEJB
                   esruntime=jmapconf.rtc
                   jarname=JMap.jar
                   package=com.corp.jmap
                   session=stateful
                   appserver="WebLogic 10.3.5"

The following command generates a Web service for the wmapserv service interface and deploys it to the enterprise server ESDEMO. The additional data file data-files-path\bookfile.dat (Windows) or data-files-path/bookfile.dat (UNIX) is deployed:

On Windows platforms:

imtkmake -generate service=wmapserv type=webservice
         -deploy server=ESDEMO,Deployer data-files-path\bookfile.dat

On UNIX platforms:

imtkmake -generate service=wmapserv type=webservice
         -deploy server=ESDEMO,Deployer data-files-path/bookfile.dat

The following command deploys a Web service that has already been generated in wmapserv.car to the enterprise server ESDEMO:

imtkmake -deploy carname=wmapserv.car
                 server=ESDEMO,Deployer

This submit is a successful deployment, as indicated by the 202 return code, and the presence of the URL in the response message.

The following command displays the deploylog.txt file from the URL http://10.120.72.229:47704/uploads/cw_diYLq:

imtkmake -showlog deploydir=http://10.120.72.229:47704/uploads/cw_diYLq

The following command creates a COBOL client program for the service wmapserv:

imtkmake -genclient type=webservice
                    service=wmapserv

The following command creates a COBOL client program for the REST service service1 using the base path /servicesApp/ and version 1.0:

imtkmake -genclient service=service1 type=rest
                    url=http://localhost:9003
                    basePath=/servicesApp/
                    version=1.0

The following command creates a COBOL client program for the service wmapserv using the service's WSDL file:

On Windows platforms:

imtkmake -genclientwsdl clientwsdl=wmapserv.wsdl

On UNIX platforms:

imtkmake -genclientwsdl clientwsdl=$PWD/wmapserv.wsdl
                        clientdir=$PWD

The following command creates an EJB service interface with default mapping using the requiresNew transaction attribute:

imtkmake -defmap type=ejb
                 src=calculator.cbl
                 service=service13.xml
                 transactionAttribute=requiresNew

The following command generates the required files for the REST service service1 using the base path /servicesApp/ and version 1.0:

imtkmake -generate type=rest
                   url=http://localhost:9003
                   basePath=/servicesApp/
                   version=1.0
                   service=service1

The following command creates a COBOL client program for the wmapserv service using its JSON Schema file:

imtkmake -genclientjson clientjson=wmapserv.json
Parent topic: Reference
Parent topic: Service Interfaces
Parent topic: Administration and Configuration Commands
Related concepts
Deploying to 64-bit Platforms
Service Interface Deployment Methods
Service Interface Deployment Package
Security Considerations for Service Interface Deployment
Related tasks
To generate and deploy a service interface from a project
To install a deployment package using mfdepinst
To generate client applications from a service interface file
To deploy a service interface using imtkmake
Related reference
mfdepinst command


mfdepinst command

Installs the service interface contained in deployment package (.car) file to an enterprise server.

The mfdepinst command handles the server-side part of the process of deploying a service to enterprise server. The tool installs the files contained in a .car to an enterprise server instance by extracting the deployment package files (.int, .idt, etc.) from the .car file, updating the Directory Service directory for the new services and packages, and if the enterprise server is running, informs it of the new services so they are available for use.

Syntax:

mfdepinst myservice.car

Parameters:

myservice.car
The name of the .car file containing the service to be deployed.

Dependencies:

Before running mfdepinst, copy the .mfdeploy file in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\deploy (Windows) or $COBDIR/deploy (UNIX) to the parent directory of the directory that contains the .car file.

.mfdeploy specifies the location, name, and listener for the enterprise server to which the service interface is deployed. So, for example, if the .car file is in %COBDIR%\myservice\myservice.deploy (Windows) or $COBDIR/myservice/myservice.deploy (UNIX), the .mfdeploy file must be in %COBDIR%\myservice (Windows) or $COBDIR/myservice (UNIX).

Edit .mfdeploy as necessary to specify values other than the default values.

Run mfdepinst from an Enterprise Developer command prompt from the same directory that contains the .car file.

Comments:

mfdepinst extracts files from the .car file and installs them on the enterprise server specified in the .mfdeploy file.

mfdepinst records its progress in the file deploylog.txt in the current directory, overwriting any existing deploylog.txt. After mfdepinst completes, you can examine this file to find out if deployment succeeded.

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.
Parent topic: Reference
Parent topic: Service Interfaces
Parent topic: Administration and Configuration Commands
Related concepts
Service Interface Deployment Methods
Service Interface Deployment Package
Security Considerations for Service Interface Deployment
Deploying Java Service Interfaces
Related tasks
To install a deployment package using mfdepinst
Related reference
imtkmake command


COBOL to Service Interface Data Type Matches

Describes which COBOL data types correspond to available Service Interface data types, including Web Services, and .NET and Java Interfaces.
Table 1. Comp Fields
COBOL Data Item |  |  | Interface Field Default Type
Usage | Digits | Signed | Web Service | Java | .NET
comp fields other than comp-1 and comp-2 | 1-2 | Yes | byte | byte | SByte
 | 1-2 | No | unsignedByte | byte | Byte
 | 3-4 | Yes | short | short | Int16
 | 3-4 | No | unsignedShort | short | UInt16
 | 5-9 | Yes | int | int | Int32
 | 5-9 | No | unsignedInt | int | UInt32
 | 10-18 | Yes | long | long | Int64
 | 10-18 | No | unsignedLong | long | UInt64
 | 19+ |  | integer | BigInteger | Decimal
comp-1 |  |  | float | float | Single
comp-2 |  |  | double | double | Double
Table 2. Display and External Float Fields
COBOL Data Item |  | Interface Field Default Type
Type | Decimal Digits | Web Service | Java | .NET
Display, External Float | 0 | integer | BigInteger | Decimal
 | >0 | decimal | BigDecimal | Decimal
Table 3. Alphanumeric and Alphanumeric Edited Fields
COBOL Data Item | Interface Field Default Type
Type | Web Service | Java | .NET
Alphanumeric, Alphanumeric Edited | string | string | string
Table 4. Pointer and Index Fields
COBOL Data Item | Interface Field Default Type
Type | Web Service | Java | .NET
Pointer, Index | unsignedLong | long | UInt64
Parent topic: Reference
Parent topic: Service Interfaces


User Interface Reference

Provides help for the fields on each dialog box associated with service interface projects and the Interface Mapper.
Restriction: This topic applies to Windows environments only.
  • CICS/COBOL Web Services UI Conrefs
    Conrefs for CICS Web Services UI Reference pages
  • Service Interface Projects
    Dialog boxes associated with Eclipse projects containing service interfaces.
  • Interface Mapper
    Dialog boxes available from within the Interface Mapper.
Parent topic: Reference


Service Interface Projects

Restriction: This topic applies to Windows environments only.
  • Advanced Settings
  • Mapping Properties - General Tab
  • Mapping Properties - Deployment Server Tab
  • Mapping Properties - Application Files Tab
  • Mapping Properties - EJB Generation Tab
  • Mapping Properties - J2SE Generation Tab
  • Mapping Properties - Mapping Properties Tab
  • New Java Interface Wizard
  • New REST Web Service Wizard
  • New SOAP Web Service Wizard
  • Username/Password
Parent topic: User Interface Reference


Advanced Settings

Restriction: This topic applies to Windows environments only.
Namespace
The namespace of the deployed service. This name is pre-pended to the Service name, forming the name by which the service is invoked. If there is no installation standard, leave it unchanged at the default http://tempuri.org/.
URL
The endpoint URL for the service. This must match the address of the listener (Web, or Web Services and J2EE) used by the enterprise server that runs the service. The default is http://localhost:9003.
Style
Document-Literal
Specifies the document-literal binding style for WSDL generation.
RPC-Encoded
Specifies the RPC-Encoded binding style for WSDL generation.
Parent topic: Service Interface Projects
Related tasks
To set deployment properties
Related reference
Mapping Properties - Deployment Server Tab


Mapping Properties - General Tab

Restriction: This topic applies to Windows environments only.
Note: This topic applies to Java service interfaces only.
EJB Generation
Generate an EJB. Selecting this option activates the EJB Generation tab.
Java Bean Generation (Uses J2SE)
Generate a Java Bean. Selecting this option activates the J2SE Generation tab.
Parent topic: Service Interface Projects
Related tasks
To set deployment properties


Mapping Properties - Deployment Server Tab

Restriction: This topic applies to Windows environments only.
Enterprise Server name
The name of the enterprise server on which you want to run your service.
Change
Change to an alternative enterprise server.
Enable Enterprise Server run-time environment
Enable the enterprise server run-time environment. Checking this enables the Configure Enterprise Server Run-time Environment button.
Configure Enterprise Server Run-time Environment
Configure the run-time environment for your enterprise server.
Service name
The name of the COBOL entry point by the service.
Advanced
Invokes the Advanced Settings dialog box where you set the service namespace and service endpoint URL. For more information, see Advanced Settings.
Application managed
Indicates that the service is application managed.
Container managed
Indicates that the service is container managed.
Username/password required for deployment
Specifies that the deployed service requires a user name and/or password. When checked, you are prompted for a user ID and password during the deployment process.
Parent topic: Service Interface Projects
Related concepts
Service Interface Deployment Methods
Related tasks
To set deployment properties
Related reference
Advanced Settings


Mapping Properties - Application Files Tab

Restriction: This topic applies to Windows environments only.
Legacy application already deployed
Indicates that the legacy application used by the service has already been deployed to an enterprise server.
Deployed application path
Type the full path to the deployed legacy application. Available when Legacy application already deployed is selected.
Legacy application needs deploying
Indicates that the legacy application used by the service has not been deployed to an enterprise server.
Application files
A list of files to be deployed with the legacy application. Used when Legacy application needs deploying is selected.
Add Files
Enables you to add application files to deploy.
Remove Files
Enables you to remove previously selected application files.
Parent topic: Service Interface Projects
Related tasks
To add or remove application files to deploy
To set deployment properties


Mapping Properties - EJB Generation Tab

Restriction: This topic applies to Windows environments only.
Note: This topic applies to Java service interfaces only, and is available only when EJB Generation is selected on the General tab.
Application Server
The J2EE version and the application server name to support EJB deployment. This ensures that the appropriate deployment descriptors are generated and included in the relevant archive files (.ear .jar .war).
Interface Type
The type of service interface (Local or Remote), set when it was created.
Bean name
The name of the Java Bean. The default is the service interface name. It is also the root name given to the home and remote interface classes.
Package name
The name of the package of Java classes. It is located in a subdirectory of the same name located under the project directory, which is created when the deployment process generates the EJB.
Session type
The session type for the EJB - Stateful or Stateless.
Transactional
Whether or not the EJB service executes in a transactional context. When set to Yes, the Session type is Stateful by default.
EJB Version 3 (Java compiler 1.5 or later is required)
EJB name
Archive name
File prefix name for Java archive files created during deployment. The default is the service interface name.
Java compiler
The directory containing the Java compiler. Optionally use the Browse button to locate it.
J2EE Class Path
The path to the J2EE implementation classes.
SEP session type
Whether the associated SEP (Service Execution Process) attribute is Stateful or Stateless. SEP attributes are only meaningful when the Transactional property is set to Yes.
Parent topic: Service Interface Projects
Related tasks
To set deployment properties


Mapping Properties - J2SE Generation Tab

Restriction: This topic applies to Windows environments only.
Note: This topic applies to Java service interfaces only, and is available only when Java Bean Generation (Uses J2SE) is selected on the General tab.
Bean name
The name of the Java Bean. The default is the service interface name. It is also the root name given to the home and remote interface classes.
Package name
The name of the package of Java classes. It is located in a subdirectory of the same name located under the project directory, which is created when the deployment process generates the Java Bean.
Session type
The session type for the Java Bean, Stateless or Stateful.
Javac path
The directory containing the Java compiler. Optionally use the Browse button to locate it.
Server host
The name of the machine hosting the enterprise server that runs this service.
Server port
The port number used by ISC listeners configured for the enterprise server that runs this service.
Parent topic: Service Interface Projects
Related tasks
To set deployment properties


Mapping Properties - Mapping Properties Tab

Restriction: This topic applies to Windows environments only.
Note: This topic applies to Web Services only.
Exit point handler program name
The full path to and name of an exit point handler program.
Parent topic: Service Interface Projects
Related tasks
To set deployment properties


New Java Interface Wizard

Restriction: This topic applies to Windows environments only.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Java interface name
Type a name for the new service interface.
Mapping
Default mapping
Let Enterprise Developer create default mappings.
None
Do not have Enterprise Developer create mappings.
Program to map
Type the full path to and filename of a COBOL program. Alternatively, click Browse to find a program.
Parent topic: Service Interface Projects
Related tasks
To create a COBOL program-based service interface


New REST Web Service Wizard

Restriction: This topic applies to Windows environments only.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Web service name
Type a name for the new service interface.
Mapping
Default mapping
Let Enterprise Developer create default mappings.
None
Do not have Enterprise Developer create mappings.
Program to map
Type the full path to and filename of a COBOL program. Alternatively, click Browse to find a program.
Parent topic: Service Interface Projects
Related tasks
To create a COBOL program-based service interface


New SOAP Web Service Wizard

Restriction: This topic applies to Windows environments only.
Restriction: This topic applies only when the Enterprise Server feature is enabled.
Web service name
Type a name for the new service interface.
Mapping
Default mapping
Let Enterprise Developer create default mappings.
None
Do not have Enterprise Developer create mappings.
Program to map
Type the full path to and filename of a COBOL program. Alternatively, click Browse to find a program.
Parent topic: Service Interface Projects
Related tasks
To create a COBOL program-based service interface


Username/Password

Restriction: This topic applies to Windows environments only.
Username
The user ID to pass to the deployment server.
Password
The password to pass to the deployment server.
Parent topic: Service Interface Projects
Related tasks
To generate and deploy a service interface from a project


Interface Mapper

Restriction: This topic applies to Windows environments only.
  • COBOL Assignment
  • Field Properties
  • Group Properties
  • Mappings
  • Operation Properties - General tab
  • Operation Properties - HTTP tab
  • Operation Properties - User Exits tab
  • Operation Reorder
Parent topic: User Interface Reference


COBOL Assignment

Restriction: This topic applies to Windows environments only.
Name
The name of the COBOL field to receive the assigned value.
Value
The value to assign to the selected COBOL field.
Edit
Edit the name of the selected COBOL field.
Parent topic: Interface Mapper
Related tasks
To assign a value to a COBOL field


Field Properties

Restriction: This topic applies to Windows environments only.
Name

The name of the interface or reusable field. If you created this field by drag-and-drop, then the default name is the same as the field you dragged.

Type
The field type. If you created this field by drag-and-drop, the default type is that which most closely matches the type of the dragged field.
Input
This field is received in incoming messages.
Output
This field is sent in outgoing messages.
I/O
This field is both received in incoming messages and sent in outgoing messages.
Occurs
The number of occurrences of this field. If you created this field by drag-and-drop, the default is the number of occurrences of the dragged COBOL field.
Parent topic: Interface Mapper
Related tasks
To edit field properties
To create an interface field


Group Properties

Restriction: This topic applies to Windows environments only.
Name

The name of the group.

Occurs
The number of times this group occurs.
Input
The fields in this group receive incoming messages.
Output
The fields in this group send outgoing messages.
I/O
The fields in this group both receive incoming messages and send outgoing messages.
Parent topic: Interface Mapper
Related tasks
To group interface or reusable fields


Mappings

Restriction: This topic applies to Windows environments only.
Interface Field
The interface field being mapped.
Dimensions
The number of times this field occurs. For fields defined using Occurs.
COBOL fields
A list of available COBOL fields to map.
Add
Creates a mapping between the interface field and the selected COBOL field.
Remove
Removes the mapping between the selected interface field and the COBOL field.
Mappings
Shows the mappings between the interface field and the COBOL field.
Subscripts
Enables you to edit the name of the linkage section item and the associated subscript.
Parent topic: Interface Mapper
Related tasks
To map an interface field


Operation Properties - General tab

Restriction: This topic applies to Windows environments only.
Operation name
The name of the operation.
Entry point
Lists the available entry points for the selected program.
Parent topic: Interface Mapper
Related tasks
To create a COBOL program-based operation


Operation Properties - HTTP tab

Restriction: This topic applies to Windows environments only.
Note: This topic applies to JSON Web Service service interfaces only.
GET
Retrieves (reads) a representation of the resource specified by the URI, returning the representation in JSON.
POST
Creates a new resource using the specified URI. Default.
PUT
Updates an existing resource identified by the URI.
DELETE
Delete the resource identified by the specified URI.
Parent topic: Interface Mapper
Related tasks
To create a COBOL program-based operation


Operation Properties - User Exits tab

Restriction: This topic applies to Windows environments only.
Note: This topic applies to Web Service service interfaces only.

Request group

External data value modification
Enable the user exit point for external data value modification - input parameter (exit point 1).
Internal data value modification
Enable the user exit point for internal data value modification - input parameter (exit point 2).
End request
Enable the user exit point for end of request processing (exit point 4).

Response group

Begin response
Enable the user exit point for start of response processing (exit point 5).
External data value modification
Enable the user exit point for external data value modification - output parameter (exit point 6).
Internal data value modification
Enable the user exit point for internal data value modification - output parameter (exit point 7).
End Response
Enable the user exit point for end of response processing (exit point 8).
Parent topic: Interface Mapper
Related tasks
To create a COBOL program-based operation


Operation Reorder

Restriction: This topic applies to Windows environments only.
Move up
Move the selected operation to an earlier position.
Move down
Move the selected operation to a later position.
Parent topic: Interface Mapper
Related tasks
To create a COBOL program-based operation


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 Assembler Subprograms
  • Interfacing with Windows API Routines
  • 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.
  • 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.

Note that the operating system limits the return value to two bytes if you use the IF ERRORLEVEL syntax to check the return value.

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 Assembler Subprograms
Example of Calling an Assembler Subprogram
Example of Calling a Win32 API Routine
Interfacing with Windows API Routines
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 Assembler Subprograms

We recommend that you write your assembler subprograms to comply with the standard COBOL calling convention (bits 0 and 1 set to 0, the default). The assembler subprogram can consist of multiple code and data segments.

Assembler subprograms must be dynamically linked.

The registers used, assuming the standard call convention, are:

Register | Usage
ESP | holds the return address, followed by parameters which have been pushed in right to left order
EBP, EBX, ESI, EDI | must be preserved by the called program
EAX | holds the return-code for four byte data items
EDX:EAX register pair | holds the return-code for an eight byte structure

For an example, see Example of Calling an Assembler Subprogram.

Parent topic: Mixed Language Programming
Related information
Example of Calling an Assembler Subprogram
Call Conventions for Interfacing with Mixed Languages
Example of Calling a Win32 API Routine
Interfacing with Windows API Routines


Interfacing with Windows API Routines

Restriction: This topic applies to Windows environments (local development) only.

The Win32 API routines can be treated as subprograms that can be called directly from COBOL. The API routines should always be called with the correct call convention.

For an example, see Example of Calling a Win32 API Routine.

Parent topic: Mixed Language Programming
Related information
Interfacing with Assembler Subprograms
Example of Calling an Assembler Subprogram
Call Conventions for Interfacing with Mixed Languages
Example of Calling a Win32 API Routine


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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\include (Windows) or $COBDIR/include (UNIX) 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\include (Windows) or $COBDIR/include (UNIX) 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(). This applies to UNIX environments only.

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\include (Windows) or $COBDIR/include (UNIX), 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) 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
Related information
COBOL


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 Calling an Assembler Subprogram
  • Example of Calling a Win32 API Routine
  • 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 Calling an Assembler Subprogram

An assembler subprogram that obeys the standard COBOL calling convention takes the following form:

The assembler subprogram can consist of multiple code and data segments. You should ensure that the initial code entry point is at the start of the first code segment defined or alternatively that you explicitly define the entry point label after the End directive.

Note:
  • It is essential that each code segment is defined as having a class name of CODE or have a class-name with the suffix CODE. Failure to do so means that the Linker fails to give the segment the access rights which permits it to be executed
  • When linking dynamically, the entry point to the subprogram should be defined in the .def file which you must supply when linking. For the example above the .def file should contain the following lines:
    LIBRARY libname
EXPORTS entry-point-name @1
;---------------------------------------------------------
; Example skeleton assembler subprogram
;---------------------------------------------------------
;---------------------------------------------------------
; Declare local data segment(s)
;---------------------------------------------------------

.386
.MODEL FLAT ;
_DATA   segment dword use32 public 'DATA'
        ...
    data used by subprogram
        ...
_DATA ends

;---------------------------------------------------------
; Declare local code segment(s)
;---------------------------------------------------------

_TEXT   segment dword use32 public 'CODE'

assume cs:flat, ds:flat, ss:flat, es:flat

;---------------------------------------------------------
; Declare public entry point
;---------------------------------------------------------

PUBLIC EXAMPLE

;---------------------------------------------------------
; Declare equates for accessing params(COBOL convention)
;---------------------------------------------------------

param1 equ  ebp+8
param2  equ  ebp+12

EXAMPLE proc  near
    push  ebp              ; preserve ebp
    mov   ebp,esp          ; address params on stack
    push  esi              ; preserve esi, edi
    push  edi

    ...
    program code
    ...

    mov  esi,[param1]      ; access parameter 1
    ...
    mov  esi,[param2]      ; access parameter 2
    ...
    mov  eax,{return-code} ; set up
                           ; return code
    ...

    pop  edi
    pop  esi               ; restored esi,edi
    pop  ebp               ; restored ebp
    ret

EXAMPLE endp

    _TEXT    ends
    end
Parent topic: Examples of Mixed Language Programming
Related information
Interfacing with Assembler Subprograms
Call Conventions for Interfacing with Mixed Languages
Example of Calling a Win32 API Routine
Interfacing with Windows API Routines


Example of Calling a Win32 API Routine

Restriction: The following applies to native COBOL only.

The following program makes use of an API routine to retrieve the current date and time.

 special-names.
     call-convention 74 is winapi.
 working-storage section.
 01 system-time.
     03 system-year     pic 9(4) comp-5.
     03 system-month    pic 9(4) comp-5.
     03 system-day-of-week  pic 9(4) comp-5.
     03 system-day    pic 9(4) comp-5.
     03 system-hour    pic 9(4) comp-5.
     03 system-minute   pic 9(4) comp-5.
     03 system-second   pic 9(4) comp-5.
     03 system-millisecond  pic 9(4) comp-5.

 procedure division.
     call winapi "GetSystemTime" using
                  by reference system-time
     display "Day of week is:  " system-day-of-week
     display "Day of month is:  " system-day
     stop run.
Parent topic: Examples of Mixed Language Programming
Related information
Interfacing with Assembler Subprograms
Example of Calling an Assembler Subprogram
Call Conventions for Interfacing with Mixed Languages
Interfacing with Windows API Routines


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

  • 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
    Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer, 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.

For Windows

The system requirements for Windows include the following:

The XML Extensions hardware and software requirements are the same as Enterprise Developer. Both 32-bit and 64-bit versions are available.

Microsoft's XML parser, MSXML 6.0 or greater, is also required. (A schema processor and an XSLT transformation processor are included in the Microsoft MSXML 6.0 parser.)

Note: The MSXML 6.0 parser may fail to install correctly if the target system does not have either Microsoft Windows Installer or Internet Explorer installed. Both of these products are freely available from Microsoft. To obtain these applications, visit www.microsoft.com/en-gb/download/default.aspx and search for the keywords "Windows Installer 2.0" or "Internet Explorer", as needed.

For UNIX

The system requirements for UNIX include the following:

The XML Extensions hardware and software requirements are the same as Enterprise Developer. Both 32-bit and 64-bit versions are available.

Shared objects libxml2.so, libxslt.so and libexslt.so, which are provided with Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Windows: MSXML 6.0, the Microsoft XML parser, schema processor, and XSLT transformation processor (msxml6.dll, msxml4a.dll, and msxml4r.dll).
  • For UNIX with Enterprise Developer 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 Enterprise Developer products. After Enterprise Developer is successfully installed XML Extensions is ready for use.

For development, a Enterprise Developer system that includes the Enterprise Developer compiler is required.

For deployment, a Enterprise Developer runtime system, such as Enterprise Server, is required.

  • Installing on Windows or UNIX
Parent topic: Installation and introduction


Installing on Windows or UNIX

Simply follow the instructions for installing Enterprise Developer onto your system. XML Extensions is installed as part of Enterprise Developer.

Parent topic: Installing XML Extensions


Introducing XML Extensions

XML Extensions for Enterprise Developer allows Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer employs a model template file to describe the COBOL data structures for export or import operations. Since XML Extensions for Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer compiler.

Compile the program with the following command line:

Windows:

cobol getstarted.cbl xmlgen(ws) noobj;

UNIX:

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:

Windows:

cobol getstarted.cbl xmlgen(ws) noobj; run getstarted

The first parameter of the run command is the name of the COBOL object file.

UNIX:

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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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.
  • Compilation options
  • New XML statement
  • XML statement restrictions
Parent topic: COBOL considerations


Compilation options

To compile for .NET managed code 32-bit add the following compiler directives to your command line, directives file, or in the Additional Directives box in Visual Studio.
ilgen
iltarget(x86)
ilref(MicroFocus.COBOL.XmlExtensions)
ilref(MicroFocus.COBOL.XmlExtensions.Interop)

To compile 64-bit change iltarget(x86) above to iltarget(x64). To compile a called subprogram change ilgen above to ilgen(sub); that will produce a DLL rather than an EXE.

Parent topic: Managed code 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Windows systems, each application is packaged as a self-extracting executable program. For example, the XFORM sample is contained in the file Samples/xform/xform.exe. Running this application will extract its component parts. For the XFORM sample, this will produce the files, xform.cbl and xform.htm.

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

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:

UNIX:
cob programname.cbl -C "{preprocess | p}(prexml)
        [{out | o} (outname)]
        [warn]
                             [outenc (input)]
        [{preprocess | p} (ppname)]
        endp"
Windows:
cobol programname.cbl {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:

UNIX:
cob foo.cbl -C "p(prexml) warn endp"
Windows:
cobol foo.cbl p(prexml) warn o(foo.pp) 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. It is not case sensitive (applies to Windows environments only). 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 (Windows) or cbl2xml (UNIX) 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 Enterprise Developer 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.

Enterprise Developer 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, Enterprise Developer contains a number of features that help make it easier, such as prototyping of library routines. It also provides analysis tooling for Windows environments that helps identify potential issues with your code, before you deploy.

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

In the Eclipse IDE, you set your platform target to 64-bit prior to compilation by choosing 64 bit in Platform Target on the COBOL page of your build configuration options.

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.

On UNIX platforms, you can control the effective working mode (either 32- or 64-bit) of your environment by using the cobmode utility or the COBMODE environment variable: when the effective working mode is 64-bit (which is the default), the generic cob command compiles a 64-bit executable. You can also use the 64-bit specific compilation command (cob64) from either working mode to compile a 64-bit executable. See The cobmode Utility for more information.

Parent topic: 64-bit Native COBOL Programming
Related reference
Compiling from the Command Line (Windows)
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
  • Programs Migrating from the Mainframe
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
Rule-Based Analysis
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


Programs Migrating from the Mainframe

Programs that are being re-hosted from the mainframe to Enterprise Server can be fully migrated to a 64-bit environment; although, those programs that are simply being moved from the mainframe for development and testing purposes should remain 32-bit compatible programs, because the IBM mainframe COBOL only supports 32-bit.

The COBOL and PL/I language syntax is capable of running in a 64-bit environment, but if the programs being migrated include third-party components, for example ADABAS or Easytrieve, you should consult those vendors to see if they are compatible in a 64-bit environment before any migration work is carried out.

As discussed in Programs Using Pointers, a change in pointer size can be problematic if certain assumptions on size are made within the code. Historically, mainframe programmers often took advantage of the relaxed syntax rules for redefining data that COBOL afforded, as it often reduced the amount of code required to be written. Therefore, running the 64 bit readiness rule set from within the IDE or as part of the Enterprise Analyzer product is highly recommended.

You should also set the AMODE directive, which can help you switch between 32- and 64-bit environments for programs performing arithmetic on mainframe-style pointers.

Parent topic: Transitioning Native COBOL Programs to 64-bit


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 COBOL Wait for Application Attachment debug configuration.
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
    • Your Eclipse project must be created as a native COBOL project by choosing File > New > COBOL Project or File > New > Remote COBOL Project and selecting Native as the compilation target.
    • In your project properties, choose Micro Focus > Build Configurations > Link and set Run Time Model to Dynamic.
  • 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 Enterprise Developer, 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 COBOL Wait for Application Attachment debug configuration.

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. Do this by adding it to the Debug Symbols Lookup Path list in your debug configuration.

Debug using COBOL Wait for Application Attachment debug configuration

  1. Start your Web server.
  2. Configure Apache so that the cgi-bin directory points to the Eclipse build output directory.
  3. Ensure the CGI binaries are in a folder on the Web server and execution of CGIs in that folder is enabled.
  4. Start Eclipse.
    • If the CGI is running as a service, you must start Eclipse with administrator's privileges.
    • You can use the httpd executable to run the Apache Web Server from the command line. Since this executable uses your own User ID, it is not necessary to start the IDE with administrator's privileges.
  5. In Eclipse, select a COBOL Wait for Application Attachment debug configuration.
  6. Under Matching Option, select the Executables stored in directory and specify the build Output Path as defined in the project properties.
  7. Start debugging.
  8. Start a Web browser and enter a URL that will invoke the CGI executable.

Debug using CBL_DEBUGBREAK and the Just-In-Time debugger

You can also embed a call to CBL_DEBUGBREAK in your code and use it to debug CGIs.

You should start the IDE as described above but for the COBOL Wait for Application Attachment debug configuration, under Matching Option, select Any.

Debug using CBL_DEBUG_START

You can debug the CGI by embedding a call to CBL_DEBUG_START in your code and specifying the program identifier in the CBL_DEBUG_START statement.

You should start Eclipse as described above but for the COBOL Wait for Application Attachment debug configuration, under Matching Option, select Program Identifier.

This approach enables you to have more than one debug sessions attached to the same process.

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 Enterprise Developer 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
    Enterprise Developer 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 Enterprise Developer 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 wrun32 (Windows) or runcbl (UNIX).

This section describes the ACUCOBOL-GT compatibility features, such as how they are enabled within Enterprise Developer, 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.exe (Windows) or ccbl (UNIX). This executable is located in the bin directory found here: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer. ccbl.exe (Windows) or ccbl (UNIX) 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 Enterprise Developer, 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.exe (Windows) or ccbl (UNIX). This executable is located in the bin directory found here: %ProgramFiles(x86)%\Micro Focus\Enterprise Developer. ccbl.exe (Windows) or ccbl (UNIX) 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 Enterprise Developer, which you enable using the ACUOPT Compiler directive.

General Support Notes

Enterprise Developer 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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.int. 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer.
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 Enterprise Developer. 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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 Enterprise Developer.
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 Enterprise Developer when using ccbl (Windows) or ccbl32 and ccbl64 (UNIX) 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. Enterprise Developer is bit-specific and does not support cross-bit generation.

For UNIX environments

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.

For Windows environments

To produce bit-specific code, use ccbl from either a 32-bit or 64-bit command prompt.

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 Enterprise Developer. In most cases, if your code includes ACUCOBOL-GT features not supported by Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer.
  • Multi-threading Implementation
    The ACUCOBOL-GT multi-threading model differs from the multi-threading model implemented in Enterprise Developer.
  • Screen Descriptions
    Enterprise Developer 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 Enterprise Developer. 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 Enterprise Developer, 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 Enterprise Developer. 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) | There are various JAVA toolkits (for example, Swing) that you can plug into the Eclipse IDE that provide GUI elements. |
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 Enterprise Developer.

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

For example, some configuration settings for handling Vision files can be set in the default File Handler in Enterprise Developer.

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

The ACUCOBOL-GT model contains some additional syntax not supported in Enterprise Developer. Refer to Multi-threaded Programming for details of supported syntax and concepts in Enterprise Developer.

Parent topic: ACUCOBOL-GT Conversion Issues
Related information
Multi-threaded Programming


Screen Descriptions

Enterprise Developer and extend® differ in their support for some of the Screen Description phrases.
In Enterprise Developer, 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 Enterprise Developer 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 Enterprise Developer; for example:
select test-file assign to "-P %TMP% cmd /c dir *.* > %TMP%"
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

Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer.
  • 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 c:\files\rmfiles (Windows) or usr/files/rmfiles (UNIX) to IDXFORMAT 21 and all files with a .DAT extension to IDXFORMAT 17:

Windows:

[FOLDER:C:\\files\\rmfiles]
IDXFORMAT=21

[*.DAT]
IDXFORMAT=17

UNIX:

[FOLDER:usr/files/rmfiles]
IDXFORMAT=21

[*.DAT]
IDXFORMAT=17

If there is a .DAT file in c:\files\rmfiles (Windows) or usr/files/rmfiles (UNIX), 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 Enterprise Developer, there are a number of file limits that affect file handling operations.

The following limits are in addition to the ones imposed in Enterprise Developer; 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.

Windows Platforms:

Each utility is available in a 32-bit and a 64-bit version, located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\binn and \binn64 respectively.

UNIX Platforms:

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

vutil32 (Windows) and mfvutil (UNIX)
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.
vio32 (Windows) and mfvio (UNIX)
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.
logutil32 (Windows) and mflogutil (UNIX)
Enables you to examine and edit an ACUCOBOL-GT transaction log file.
acusort (Windows) and mfvissort (UNIX)
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, using one of the following:
Data File Converter
Use the Micro Focus Data File Converter to convert your Vision files to Micro Focus format.

DFCONV command line utility
(Windows only) Use DFCONV from the command line, specifying Vision as the input format for the file.
Parent topic: ACUCOBOL-GT File Handling
Related reference
Converting Data Files
Using the Data File Converter


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:

Windows:

acurfap://servername:[port]:path\to\file

UNIX:

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 C:\idx\ (Windows) or /home/idx/ (UNIX).

Windows:

...
select acusvridx assign to acurfap://asvr1:3011:c:\idx\idx1.
...

UNIX:

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

Windows:

set COBDATA=%COBDATA%; "acurfap://servername:port:path/to/file"

UNIX:

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 c:\idx\ (Windows) or /home/idx/ (UNIX).

Windows:

set COBDATA=%COBDATA%; "acurfap://asvr2::c:\idx"

UNIX:

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. (UNIX only)

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

Parent topic: ACUCOBOL-GT File Handling
Related concepts
Features Added in Enterprise Developer 2.2
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.
  • Under the optional LISTDIR-FILE-INFORMATION group item, the fields LISTDIR-FILE-CREATION-TIME and LISTDIR-FILE-LAST-ACCESS-TIME only return zeroes.
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 and Windows NT versions 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 and Windows NT

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". Under Windows NT, the prefix will typically be "CMD.EXE /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:

    Windows:

    cobol prog.cbl preprocess"window1" color endp;

    UNIX:

    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


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

Enterprise Developer 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 Enterprise Developer.
  • Retain the use of the selected COBOL on some machine environments while moving to Enterprise Developer 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 Enterprise Developer 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

Enterprise Developer 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 Enterprise Developer.
  • Retain the use of the selected COBOL on some machine environments while moving to Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Eclipse
    As an RM/COBOL user, you can modernize your applications for Enterprise Developer 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 Enterprise Developer 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 Eclipse

As an RM/COBOL user, you can modernize your applications for Enterprise Developer 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 Enterprise Developer using the Eclipse 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 Enterprise Developer 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. Create a Native Enterprise Developer Project
    Create the project in which your RM/COBOL source code will be imported.
  2. Set the DIALECT“RM” Compiler Directive for the Project
    Set the DIALECT"RM" directive at project level, so that it applies to all programs within the project.
  3. Import your RM/COBOL Source Code
    Import one or more of your source files into the project.
  4. Customizing the Reserved Words List
    There are words that may be in your RM/COBOL source code that are reserved in Micro Focus COBOL; their presence will cause syntax errors unless you remove them from the reserved words list.
  5. Add Adis Support to the Project
    Add Adis support to your project to alter the default behavior of the enhanced ACCEPT and DISPLAY statements in Micro Focus COBOL.
  6. Add the RM/COBOL Keyboard Configuration
    Add a keyboard configuration file to the project that sets the typical function key operations when executing ACCEPT statements in an RM/COBOL environment.
  7. Build and Run the Project
    Build the project, and then run the application.
  8. Appendices
Parent topic: Converting RM/COBOL Applications


Create a Native Enterprise Developer Project

Create the project in which your RM/COBOL source code will be imported.
  1. Launch Enterprise Developer. Specify a path for the Eclipse workspace when prompted.

    If this is the first time you start Eclipse, the IDE displays the Eclipse Welcome page. Click Open Team Developer Perspective which is the default perspective in Enterprise Developer.

    If the IDE does not start in the Team Developer perspective, to change to it, click Window > Perspective > Open Perspective > Other, click Team Developer (default), and then click OK.

    Perspectives are an Eclipse concept and they include the views, menus and options relevant to your activity. The Team Developer perspective shows the Application Explorer view, Outline and Console views, among others. The perspective is customizable, so you can choose your own views.

  2. Select File > New > Other .

    The New dialog box is displayed.

  3. Expand Micro Focus COBOL folder, and then click COBOL Project.
  4. Click Next.

    The New COBOL Project dialog box is displayed.

  5. In the Project name field, specify a name for the project.
  6. Click Finish.

    The project is created, and displayed in the Application Explorer view.

Parent topic: Configuring Your Application for Eclipse
Next topic: Set the DIALECT“RM” Compiler Directive for the Project


Set the DIALECT“RM” Compiler Directive for the Project

Set the DIALECT"RM" directive in the project's properties so that it applies to all programs within the project unless you explicitly override it at the program level.
  1. Right-click your project in the COBOL Explorer view and select Properties.

    The Properties for <project-name> dialog box appears.

  2. Select Micro Focus > Project Settings > COBOL.

    The COBOL settings appear in the right-hand pane.

  3. In the Language Dialect field, select RM/COBOL.
  4. Click OK.

    The RM/COBOL dialect is applied to any program within the project, unless that program overrides it by setting the DIALECT directive explicitly within the source code.

Parent topic: Configuring Your Application for Eclipse
Previous topic: Create a Native Enterprise Developer Project
Next topic: Import your RM/COBOL Source Code


Import your RM/COBOL Source Code

Import one or more of your source files into the project.
Note: You may use your own source code, but for this tutorial we are going to use the sample RM/COBOL program listed in Appendix A - RM/COBOL source file.
  1. Open a plain-text editor, copy and paste the sample code in Appendix A - RM/COBOL source file into a new document.
  2. Save the file with a .cbl extension.
  3. Drag the file into Eclipse, and drop it on the project name when the cursor changes to [image] (Windows) or [image] (UNIX).

    The File Operation dialog box appears.

  4. Ensure Copy Files is selected (so that a copy of the original file is created in the project, and not simply a link to the original file inserted), then click OK. A copy of the file is added to the project, and if your environment is set to build automatically, the project is compiled.
Parent topic: Configuring Your Application for Eclipse
Previous topic: Set the DIALECT“RM” Compiler Directive for the Project
Next topic: Customizing the Reserved Words List
Related concepts
Appendix A - RM/COBOL Source File


Customizing the Reserved Words List

There are words that may be in your RM/COBOL source code that are reserved in Micro Focus COBOL; their presence will cause syntax errors unless you remove them from the reserved words list.

Use the directives file, MigrateRM.dir, that is supplied with your Enterprise Developer installation to remove any such words from the list. You can use this file with any RM/COBOL sources you are modernizing.

  1. In your file system, browse to %COBDIR%\etc\rm (Windows) or $COBDIR/etc/rm (UNIX).

    The directory containing MigrateRM.dir appears.

  2. Drag this file into Eclipse, and drop it on the project name when the cursor changes to [image] (Windows) or [image] (UNIX).

    The File Operation dialog box appears.

  3. Ensure Copy Files is selected (so that a copy of the original file is created in the project, and not simply a link to the original file), then click OK.

    A copy of the file is added to the project.

  4. Right-click your project in the Application Explorer view and select Properties.

    The Properties for <project-name> dialog box appears.

  5. Select Micro Focus > Project Settings > COBOL.

    The COBOL settings appear in the right-hand pane.

  6. In the Additional Directives box, type USE(MigrateRM.dir), then click Apply.
  7. Click OK to save the project.

    The directives in the .dir file are applied to your project.

The next task is to add Adis support to the project.
Parent topic: Configuring Your Application for Eclipse
Previous topic: Import your RM/COBOL Source Code
Next topic: Add Adis Support to the Project


Add Adis Support to the Project

Add Adis support to your project to alter the default behavior of the enhanced ACCEPT and DISPLAY statements in Micro Focus COBOL.

Enterprise Developer ships with a version of Adis that contains a configuration intended for modernizing RM/COBOL applications.

  1. In your file system, browse to %COBDIR%\etc\rm (Windows) or $COBDIR/etc/rm (UNIX).

    The directory containing ADISCTRL appears.

  2. Drag this file into Eclipse, and drop it on the project name when the cursor changes to [image] (Windows) or [image] (UNIX).

    The File Operation dialog box appears.

  3. Ensure Copy Files is selected (so that a copy of the original file is created in the project, and not simply a link to the original file), then click OK.

    A copy of the file is added to the project.

  4. To verify that the correct Adis configuration is selected:
    1. Using an Enterprise Developer command prompt, navigate to the project directory (that is, the directory containing ADISCTRL).
    2. Type adiscf, then press Enter.

      The adiscf.exe window appears.

    3. Press F6, then ensure that the RM2VCOB configuration is selected.

      See Appendix B - ADISCTRL settings for RM2VCOB, Appendix C - Adis key mappings for RM2VCOB, and Appendix D - Adis key function mapping for RM2VCOB for a full list of the settings.

    4. Press Esc twice to exit.
      Note: if you are prompted to exit without saving, press N, F4, then Esc twice again.
  5. Right-click your project in the COBOL Explorer view and select Properties.

    The Properties for <project-name> dialog box appears.

  6. In the left-hand pane, select Micro Focus > Build Configurations > Events.

    The Events appear in the right-hand pane.

  7. In the Post-build event command line box, type copy ${basedir}\ADISCTRL ${basedir}\New_Configuration.bin\ADISCTRL (Windows), or cp ${basedir}/ADISCTRL ${basedir}/New_Configuration.bin/ADISCTRL (UNIX), then click Apply.
    Note: If your project builds to another location other than the default New_Configuration.bin directory, you will need to change the above command accordingly.
  8. Click OK.
Parent topic: Configuring Your Application for Eclipse
Previous topic: Customizing the Reserved Words List
Next topic: Add the RM/COBOL Keyboard Configuration
Related concepts
The ADIS configuration utility
Appendix B - ADISCTRL Settings for RM2VCOB
Appendix C - Adis Key Mappings for RM2VCOB
Appendix D - Adis Key Function Mapping for RM2VCOB


Add the RM/COBOL Keyboard Configuration

Add a keyboard configuration file to the project that sets the typical function key operations when executing ACCEPT statements in an RM/COBOL environment.

Enterprise Developer ships with a keyboard configuration intended for modernizing RM/COBOL applications.

Note: On some UNIX platforms, the keyboard configuration file that is supplied may not be compatible with the local termcap file in use. You will be able to tell if this is the case when you run the application, and key-presses are not performing the required actions; in which case, you must use the Keyboard Configuration Utility (keybcf) to correct the supplied version of cobkeymp.
  1. In your file system, browse to %COBDIR%\etc\rm (Windows) or $COBDIR/etc/rm (UNIX).

    The directory containing cobkeymp appears.

  2. Drag this file into Eclipse, and drop it on the project name when the cursor changes to [image] (Windows) or [image] (UNIX).

    The File Operation dialog box appears.

  3. Ensure Copy Files is selected (so that a copy of the original file is created in the project, and not simply a link to the original file), then click OK.

    A copy of the file is added to the project.

  4. Right-click your project in the COBOL Explorer view and select Properties.

    The Properties for <project-name> dialog box appears.

  5. Select Micro Focus > Build Configurations > Events.

    The Events appear in the right-hand pane.

  6. In the Post-build event command line box, on a new line, type copy ${basedir}\cobkeymp ${basedir}\New_Configuration.bin\cobkeymp (Windows), or cp ${basedir}/cobkeymp ${basedir}/New_Configuration.bin/cobkeymp (UNIX), then click Apply.
    Note: If your project builds to another location other than the default New_Configuration.bin directory, you will need to change the above command accordingly.

    If a prompt appears informing you that files already exist in the specified location, click No.

  7. Click OK.
Parent topic: Configuring Your Application for Eclipse
Previous topic: Add Adis Support to the Project
Next topic: Build and Run the Project
Related concepts
Overview of the Keyboard Configuration utility
Keyboard Configuration Utility Keybcf


Build and Run the Project

By default, Eclipse is set to build projects automatically (see Project menu). If there are any problems, check the Problems window: errors for the project show the name of your imported .cbl source file in the Resource column. Double-click an entry to jump to the particular area of the code in error.

To run the application from Eclipse, you need to create a launch configuration.

  1. Right-click your project in the COBOL Explorer view and select Run As > Run Configurations.

    The Run Configurations dialog box appears.

  2. Double-click COBOL Application.

    Default launch configuration details for your project are displayed.

  3. Click Run.

    The following appears:

  4. Press any key to end the application.
This concludes the tutorial in which we have created an Enterprise Developer project, configured it to be highly compatible with RM/COBOL source code, and then run a small RM/COBOL program.
Parent topic: Configuring Your Application for Eclipse
Previous topic: Add the RM/COBOL Keyboard Configuration
Next topic: Appendices


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 Eclipse
Previous topic: Build and Run the Project


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
Related reference
Import your RM/COBOL Source Code


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
Related reference
Add Adis Support to the Project


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
Related reference
Add Adis Support to the Project


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
Related reference
Add Adis Support to the Project


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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer. 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 Enterprise Developer.
  • 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 Enterprise Developer, but Enterprise Developer 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, Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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, Enterprise Developer'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


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 Enterprise Developer, 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
    Enterprise Developer 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 Enterprise Developer, 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
    Enterprise Developer 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 Enterprise Developer, 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
    Enterprise Developer and RM/COBOL differ in the environment variables that they use to locate program and data files.
  • Indexed File Error on Open
    Enterprise Developer 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
    Enterprise Developer and RM/COBOL differ in the way that they allow you to use regular expressions.
  • Linkage Section in Main Program
    Enterprise Developer and RM/COBOL differ in their ability to reference the Linkage Section items in the main program.
  • Nested OCCURS DEPENDING Clauses
    In Enterprise Developer, if you are using nested OCCURS DEPENDING clauses, you must set the ODOSLIDE Compiler directive.
  • Numbering of Segments
    Enterprise Developer and RM/COBOL differ in the number of segments that they permit you to specify.
  • Program Identification and Data Names
    In Enterprise Developer, ensure that the Program-ID name does not share the same name as any data items in the program.
  • REMARKS Paragraph
    In Enterprise Developer, if your program uses the REMARKS paragraph in the Identification Division, you must set the DIALECT"RM" Compiler directive.
  • Reserved Words
    In Enterprise Developer, 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
    Enterprise Developer and RM/COBOL differ in the way that they allow you to reuse existing data structures.
  • Source Code in Columns 73 to 80
    Enterprise Developer ignores any of the code in your source programs which lies within columns 73-80 inclusive.
  • START WHILE LIKE Not Available
    Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer. In Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer, 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

Enterprise Developer 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 Enterprise Developer, set COBPATH to locate program files and COBDATA to locate data files. The RUNPATH environment variable used in RM/COBOL, is not used in Enterprise Developer.

Parent topic: Producing Executable Code
Related information
Environment variables (Windows)


Indexed File Error on Open

Enterprise Developer and RM/COBOL differ in how they handle record length fields and some data fields when you open an RM/COBOL indexed file.

In Enterprise Developer, 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, Enterprise Developer 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

Enterprise Developer and RM/COBOL differ in the way that they allow you to use regular expressions.

RM/COBOL has a LIKE relational-operator. Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer, 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

Enterprise Developer and RM/COBOL differ in the way that they allow you to reuse existing data structures.

In Enterprise Developer, 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 Enterprise Developer.

Parent topic: Producing Executable Code
Related reference
The TYPEDEF Clause
The USAGE Clause


Source Code in Columns 73 to 80

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

Enterprise Developer 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. Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer 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 Enterprise Developer 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
    Enterprise Developer 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
    Enterprise Developer 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 Enterprise Developer, 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, Enterprise Developer 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
    Enterprise Developer 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
    Enterprise Developer 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 Enterprise Developer.
  • Initialization of Working Storage
    Enterprise Developer 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 Enterprise Developer, 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
    Enterprise Developer and RM/COBOL differ in their treatment of the ON SIZE ERROR condition.
  • Open EXTEND of Nonexistent File
    Enterprise Developer 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, Enterprise Developer writes all output intended for a printer to disk.
  • Screen Column Number Specification
    Enterprise Developer and RM/COBOL differ in the number of screen columns you are able to specify.
  • Trailing Blanks in Line Sequential Files
    Enterprise Developer 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
    Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer as "0000123456". However, in RM/COBOL, the value in the ACCEPT field would be held as "1234560000". To allow Enterprise Developer 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. Enterprise Developer 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 Enterprise Developer, 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, Enterprise Developer 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

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

In Enterprise Developer, 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, Enterprise Developer 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, Enterprise Developer 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 Enterprise Developer.

The errors fixed when upgrading to Enterprise Developer 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 Enterprise Developer, 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

Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer, 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 Enterprise Developer create the file and open it for OUTPUT
  • Create the empty file before running your program
  • Specify the OPTIONAL-FILE Compiler directive. This makes Enterprise Developer 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, Enterprise Developer 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

Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer will differ from its position in RM/COBOL.

Parent topic: Running the Code
Related information
COBOL Language Reference


Trailing Blanks in Line Sequential Files

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

Enterprise Developer 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 Enterprise Developer 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, Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer, 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 operandrefers 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 Enterprise Developer, 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 Enterprise Developer, 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 c:\files\rmfiles (Windows) or usr/files/rmfiles (UNIX) to IDXFORMAT 21 and all files with a .DAT extension to IDXFORMAT 17:

Windows:

[FOLDER:C:\\files\\rmfiles]
IDXFORMAT=21

[*.DAT]
IDXFORMAT=17

UNIX:

[FOLDER:usr/files/rmfiles]
IDXFORMAT=21

[*.DAT]
IDXFORMAT=17

If there is a .DAT file in c:\files\rmfiles (Windows) or usr/files/rmfiles (UNIX), 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 Enterprise Developer, there are a number of file limits that affect file handling operations.

The following limits are in addition to the ones imposed in Enterprise Developer; 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.

  1. Click Run > Debug Configurations.
  2. In the COBOL JVM Application section, select the application's main executable.
  3. Select the Environment tab.
  4. Click New.
  5. In the New Environment Variable dialog box, enter the following, then click OK.
    • Name: RMFM_PRETEND_FORCE_CLOSED
    • Value: YES
  6. Click Apply, then click Debug to rebuild and debug your project.
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 44 through Figure 47. The recovery session is started in this example by the following command:

recover1 master.inx dropout1

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

Figure 44: Indexed File Recovery Utility: File Recovery Verification

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

Figure 45: Indexed File Recovery Utility: recover1 Summary

                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 46 shows the information that is displayed while recover1 is rebuilding the node blocks for the prime key.

Figure 46: Indexed File Recovery Utility: recover1 Statistics

                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 47 shows the information that is displayed after recover1 terminates successfully. The two lines regarding truncation are shown only when the T option is specified.

Figure 47: Indexed File Recovery Utility: recover1 Finished Successfully

             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.

In the example shown in Figure 48, 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.

Figure 48: Indexed File Recovery Utility: Entering Key Information

             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 49 shows an example of entering the remainder of the KIB information. Underlined characters have been entered by the user.

Figure 49: Indexed File Recovery Utility: Entering KIB Information

              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

After the key and KIB information has been successfully entered, the recovery process proceeds the same as before, beginning with Figure 44. 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 Enterprise Developer, 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 Enterprise Developer:

  • 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 Eclipse
  • 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 Enterprise Developer
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 Enterprise Developer. 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 Enterprise Developer 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 Enterprise Developer 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.
Modeless operation not supported (Windows platforms)
The utility function (RMP--U-SMD), which initiates modeless operation, has no effect.
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 Enterprise Developer 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 Enterprise Developer.

See the section Converting RM/COBOL Applications for details about converting the application to run under Enterprise Developer.

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc (Windows), or /opt/microfocus/EnterpriseDeveloper/etc (UNIX). 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 Enterprise Developer, 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 Eclipse

The following is an example conversion from RM/COBOL to Enterprise Developer using Eclipse 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 Enterprise Developer:

  • ADISCTRL: The ADIS configuration file for ACCEPT/DISPLAY statements.
  1. Creating an Eclipse Project for the RM/Panels Application
    Create the project in which your RM/Panels source code will be imported.
  2. Set the Dialect“RM” Directive for the Project
    Set the DIALECT"RM" directive at project level, so that it applies to all programs within the project.
  3. Download the Tutorial Files
    The files required for this tutorial are available on the Micro Focus Community web site.
  4. Import the RM/Panels Source Code
    Import the required source files into the project.
  5. 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.
  6. Configure the Supported Copybook Extensions
    Configure Eclipse to recognize the appropriate RM/COBOL file extensions as copybooks in Enterprise Developer.
  7. Configure the Library File for Run Time
    This demo can run on Windows or UNIX. To change it to run from one to the other platform, you must edit a data item to point to the correct run-time system.
  8. Build and Run the Application
    Build (unless it is built automatically) and then run the application.
Parent topic: RM/Panels


Creating an Eclipse Project for the RM/Panels Application

The first task is to create a project.
  1. Launch Enterprise Developer. Specify a path for the Eclipse workspace when prompted.

    If this is the first time you start Eclipse, the IDE displays the Eclipse Welcome page. Click Open Team Developer Perspective which is the default perspective in Enterprise Developer.

    If the IDE does not start in the Team Developer perspective, to change to it, click Window > Perspective > Open Perspective > Other, click Team Developer (default), and then click OK.

    Perspectives are an Eclipse concept and they include the views, menus and options relevant to your activity. The Team Developer perspective shows the Application Explorer view, Outline and Console views, among others. The perspective is customizable, so you can choose your own views.

  2. Select File > New > Other .

    The New dialog box is displayed.

  3. Expand Micro Focus COBOL folder, and then click COBOL Project.
  4. Click Next.

    The New COBOL Project dialog box is displayed.

  5. In the Project name field, type vc_qdemo.
  6. Click Finish.

    The project is created, and displayed in the Application Explorer view.

Parent topic: Conversion Example: Using Eclipse
Next topic: Set the Dialect“RM” Directive for the Project


Set the Dialect“RM” Directive for the Project

Set the DIALECT"RM" directive in the project's properties so that it applies to all programs within the project unless you explicitly override it at the program level.
Note: The qdemo.cbl supplied with the demo files sets the directive explicitly in the source code already, so these steps are not essential; although, they are good practice if you were adding further source files to your project, as you would not have to then explicitly set the directive in the new source files each time.
  1. Right-click your project in the COBOL Explorer view and select Properties.

    The Properties for <project-name> dialog box appears.

  2. Select Micro Focus > Project Settings > COBOL.

    The COBOL settings appear in the right-hand pane.

  3. In the Language Dialect field, select RM/COBOL.
  4. Click OK.

    The RM/COBOL dialect is applied to any program within the project, unless that program overrides it by setting the DIALECT directive explicitly within the source code.

Parent topic: Conversion Example: Using Eclipse
Previous topic: Creating an Eclipse Project for the RM/Panels Application
Next topic: Download the Tutorial Files


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. Point to Micro Focus, then choose Visual COBOL.

    Visual COBOL group

    The Visual COBOL group appears.

  3. Click the Files tab.

    The Visual COBOL - Media Gallery appears.

  4. Click the appropriate Visual COBOL RM/Panels Conversion entry for your platform.
    Note: Click [image] to the right of the Media Gallery title to display the available files as a detailed list; this will enable you to easier locate the required file(s).
  5. Under the Options group on the right side, click Download file.
  6. When prompted, extract the contents of the .zip file to a directory that is not the project directory.
Parent topic: Conversion Example: Using Eclipse
Previous topic: Set the Dialect“RM” Directive for the Project
Next topic: Import the RM/Panels Source Code


Import the RM/Panels Source Code

  1. Ensure that the Navigator pane is selected, then drag the following files (downloaded in the previous step) into Eclipse, and drop them on the project name when the cursor changes to [image] (Windows) or [image] (UNIX).
    • 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

    The File Operation dialog box appears.

  2. Ensure Copy Files is selected (so that a copy of the original file is created in the project, and not simply a link to the original file inserted), then click OK.

    A copy of the files are added to the project, and if your environment is set to build automatically, the project is built. If the project does not build automatically, on the Project menu, select Build Automatically.

  3. Again, ensure that the Navigator pane is selected, then drag the following files into Eclipse, and drop them on the directory that contains the executable that has just been built, when the cursor changes to [image] (Windows) or [image] (UNIX).
    • ADISCTRL
    • qdemo.lib
    Note: The default directory is New_Configuration.bin, unless another directory is specified in the default Run configuration.

    The File Operation dialog box appears.

  4. Ensure Copy Files is selected again, then click OK.

    A copy of the files are added to the project's output directory.

Parent topic: Conversion Example: Using Eclipse
Previous topic: Download the Tutorial Files
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.

Enterprise Developer ships with a version of Adis that contains a configuration intended for applications that include RM/Panels syntax.

  1. Using an Enterprise Developer command or shell prompt, navigate to the project output 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 Eclipse
Previous topic: Import the RM/Panels Source Code
Next topic: Configure the Supported Copybook Extensions


Configure the Supported Copybook Extensions

Configure Eclipse to recognize the appropriate RM/COBOL file extensions as copybooks in Enterprise Developer.
  1. On the Window menu, select Preferences.

    The Preferences dialog box appears.

  2. In the left-hand pane, select General > Appearance > Content Types.

    The Content Types pane appears in the right-hand pane.

  3. Select Text > Micro Focus Project Types > COBOL Copybook. In the bottom pane, a list of file associations for COBOL copybooks appears.
  4. Click Add, then in the Add Content Type Association dialog box, type *.prc and click OK.
  5. Repeat the previous step, entering *.ws this time.
  6. Click OK.

    The Preferences dialog box is closed. Files with the extension .prc or .ws are now recognized as copybooks for all projects in Eclipse.

    Note: If the COPY statements in your source code reference any of these files without specifying the extension, you should also set the COPYEXT"prc,ws" Compiler directive in your project.
Parent topic: Conversion Example: Using Eclipse
Previous topic: Configure Adis Support for RM/Panels
Next topic: Configure the Library File for Run Time


Configure the Library File for Run Time

This demo can run on Windows or UNIX. To change it to run from one to the other platform, you must edit a data item to point to the correct run-time system.

The downloaded library file should already be configured correctly for your platform; if it is not, you must update it and recompile your application.

  1. In COBOL Explorer, select rmpanels.ws.

    The copybook appears in the editor.

    Note: Files with RM/COBOL-specific file extensions (such as .ws and .prc) may only show in a plain text editor; to display them in the COBOL editor, you may have to set the file associations on the Run menu, by selecting Preferences, then General > Editors > File Associations.
  2. Locate the RMP--RUNTIME data item, and update the value accordingly:
    • runpan2.dll (Windows)
    • cobrunpan2 (32-bit UNIX)
    • cobrunpan264 (64-bit UNIX)

  3. Save the copybook.
Parent topic: Conversion Example: Using Eclipse
Previous topic: Configure the Supported Copybook Extensions
Next topic: Build and Run the Application


Build and Run the Application

By default, Eclipse is set to build projects automatically (see Project menu). If there are any problems, check the Problems window: errors for the project show the name of your imported .cbl source file in the Resource column. Double-click an entry to jump to the particular area of the code in error.

To run the application from Eclipse, you need to create a launch configuration.

  1. Right-click your project in the COBOL Explorer view and select Run As > Run Configurations.

    The Run Configurations dialog box appears.

  2. Double-click COBOL Application.

    Default launch configuration details for your project are displayed.

  3. Click Run.

    The following appears:

  4. When you have finished viewing the demonstration, click the Close button in the top right-hand corner.
This concludes the tutorial in which we have created a project in Enterprise Developer, configured it to accept RM/Panels syntax, and then run a small program that demonstrates that.
Parent topic: Conversion Example: Using Eclipse
Previous topic: Configure the Library File for Run Time


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

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

On Windows, Help for the following OO COBOL class libraries is available:

  • Base class library
  • GUI class library
  • OLE class library
  • OLE Automation class library

The Help is available in the file nxrclr.chm, which is installed in the Help folder of your installation. The default location is%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\Help.

To open the help, double-click nxrclr.chm in Windows Explorer.

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
  • File Handling
Parent topic: Programming


Database Access

Enterprise Developer provides several programming options and features to accommodate database access in your COBOL applications.

  • 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.
  • 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 on Windows
Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components


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
  • 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.
SQL Option for DB2
Enterprise Developer also includes a complete relational database product, SQL Option for DB2. This includes access to an XDB database, which is fully compatible with DB2.
HCO for DB2 LUW
In addition to the OpenESQL and COBSQL preprocessors, Enterprise Developer provides the DB2 External Compiler Module preprocessor for developing and deploying mainframe-style DB2 ECM SQL applications.
HCO for SQL Server
HCO for SQL Server (HCOSS) provides tools for migrating DB2 databases and applications to SQL Server 2008 databases and applications. It is a superset of OpenESQL; therefore applications that use HCOSS have access to all OpenESQL functionality.
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
Related concepts
HCO for SQL Server (HCOSS)
SQL Option for DB2


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

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 Enterprise Developer. 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 Enterprise Developer, 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
HCO for DB2 LUW


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.

Note: The OpenESQL JVM Managed Runtime supports JVM host variables in managed code. See the topic JVM Host Variables in Managed Code for more information.
  • 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 the ENTCOBOL dialect.

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 a Sybase database, you can only use host arrays in SELECT and FETCH statements as output variables.
  • If you are using COBSQL with Oracle or Sybase, 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.
    • COBSQL supports the FOR clause with Oracle databases only.

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.

You can code SQL TYPEs directly into your applications or, for OpenESQL applications, use the OpenESQL Assistant to automatically use SQL TYPEs by setting the Type COBOL Variable option for the OpenESQL Assistant to SQL TYPE.

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

Oracle, Sybase and Informix all have different versions of the SQLCA. The Oracle, Sybase and Informix SQLCA's all have a SQLCODE, SQLERRML, SQLERRMC and a SQLWARN. The sizes and the positions of these fields can differ between the precompilers.

For details of the layout of the SQLCA data structure, see the topic The SQLCA Data Structure.

OpenESQL

The SQLCA provided with Enterprise Developer 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 third-party 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX). 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, refer to the relevant Database Error Messages manual.

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. The Oracle SQLDA is not compatible with that used by Sybase, OpenESQL or DB2 and vice versa.

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

For Oracle, Sybase and Informix, the SQLDA is only required if your program uses dynamic SQL. It must be defined as a standard COBOL copybook. You cannot include the SQLDA in your program 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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) 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
HCO for DB2 LUW


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:

In the Enterprise Developer IDE
You can specify an SQL preprocessor and its applicable compiler directive options on the SQL Preprocessor page of your project properties. Do this when your primary method of compilation is building a program or application from the IDE.
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
Setting the XDB 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 dynamic-link libraries (.dll files) (Windows) or callable shared objects (UNIX). 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 - HCO for DB2 LUW
  • 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.
  • COBOL Program Migration Support
    The role of OpenESQL in aiding effective migration of mainframe applications.
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 Enterprise Developer Project
Before compiling from within Enterprise Developer:
  1. Open your project properties and expand Micro Focus > Project Settings > COBOL > SQL Preprocessor.
    Note: You can also set compiler directive options under Micro Focus > Build Configurations > COBOL > SQL Preprocessor. If you do this, the setting applies only when the build configuration is active, and the compiler directive option is not set to something else in the Project Settings or on the program level.
  2. If unchecked, check Enable configuration specific settings and Use SQL Preprocessor.
  3. From the Preprocessor Type drop-down list, select OpenESQL.
  4. Type the name of your database into the Value field of the DB setting.
  5. To specify the type of database access you want, use the grid to set the value of the DBMAN directive to ODBC or JDBC.
  6. Click Apply.
  7. Use the grid to select additional directive options and set appropriate values. Click Apply after each setting.

Alternatively, you can enter the preprocessor specification and options as additional directives:

  1. Open your project properties and expand Micro Focus > Project Settings > COBOL.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. Click in the Additional directives field and type:
    SQL(DBMAN=dbaType [SQLdirOpt])

    Where dbaType is ODBC or JDBC, and SQLdirOpts is one or more additional directive options.

On the Command Line
Use the SQL compiler directive, followed by the DBMAN option to specify the type of database access:

SQL(DBMAN=dbaType) (Windows)

Or:

SQL(DBMAN==dbaType) (UNIX)

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
Setting Compiler Directives for COBOL
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: 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 or PL/I | 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 Enterprise Developer 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 Enterprise Developer 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 Enterprise Developer 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.

Enterprise Developer 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.
  • OpenESQL Configuration Utility for Default SQL Cursor Behavior
Parent topic: OpenESQL
Related concepts
OpenESQL
OpenESQL Configuration Utility for Default SQL Cursor Behavior
OpenESQL


Embedded SQL Cursors in Older Applications

When using a current version of Enterprise Developer with an SQL application that has been:
  • Developed in an earlier Micro Focus COBOL development product or a version of Enterprise Developer earlier than 2.1
  • Migrated to a version of Enterprise Developer 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 Enterprise Developer.

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 Enterprise Developer 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
Related reference
BEHAVIOR
Primitive Directives


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.

Note: The OpenESQL Configuration Utility does not enable you to set the BEHAVIOR directive to either JCL or CICS, both of which are valid settings. If you want to set the BEHAVIOR directive to either of these, be sure to set it in one of the above-referenced places before attempting to compile your application.

You can run this utility, using its user-interface implementation (applies to Windows environments only) or its command-line implementation (esqlconfig command), on each machine where you have installed Enterprise Developer. 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:

  • Optimize for performance and mainframe compatibility
    This is the recommended setting for mainframe migrations and new development.
  • ANSI compliance
    This is the recommended setting for migrating applications that require ANSI compliance, and as a performance optimization for existing users of Micro Focus Net Express and earlier products.
  • No change in default behavior and no optimization
    This setting represents the default behavior in earlier releases of OpenESQL in Micro Focus products.
  • Issue a warning at compile time
    This is the recommended setting for users who would like to be notified when the SQL(BEHAVIOR) directive has not been set outside of the OpenESQL Configuration utility.
  • Issue an error at compile time
    This is the recommended setting for users who require that the SQL(BEHAVIOR) directive be set in program source, project settings, or a COBOL directives file.
Parent topic: OpenESQL Embedded SQL Cursor Behavior and Performance
Related concepts
COBOL Program Migration Support
OpenESQL Embedded SQL Cursor Behavior and Performance
DBMAN Directive Settings
Programming for OpenESQL
Related tasks
To set a default for SQL(BEHAVIOR)
To start the OpenESQL Configuration utility
Related reference
BEHAVIOR
esqlconfig command


Optimize for performance and mainframe compatibility

Sets the SQL(BEHAVIOR) directive to SQL(BEHAVIOR=OPTIMIZED), meaning that data access is read only for everything except data access that is explicitly specified for update.

For database connections to Microsoft SQL Server, multiple active result sets (MARS) are enabled and read only cursors use SQL Server default result sets (otherwise known as firehose cursors). Be sure to use the most recent Microsoft ODBC driver for your version of SQL Server; older versions of the Microsoft ODBC for SQL Server might not provide MARS functionality.

For other databases, such as Oracle or DB2, read only cursors use block fetches of eight rows.

Updatable cursors for all databases use block fetches of eight rows. You can change the block fetch size.

Parent topic: OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
BEHAVIOR


ANSI compliance

Sets the SQL(BEHAVIOR) directive to SQL(BEHAVIOR=ANSI), meaning that data access is updatable for everything except data access that is explicitly specified as read only.

For database connections to Microsoft SQL Server, multiple active result sets (MARS) are enabled and read only cursors use SQL Server default result sets (otherwise known as firehose cursors). Be sure to use the most recent Microsoft ODBC driver for your version of SQL Server; older versions of the Microsoft ODBC for SQL Server might not provide MARS functionality.

For other databases, such as Oracle or DB2, read only cursors use block fetches of eight rows.

Updatable cursors for all databases use block fetches of eight rows. You can change the block fetch size. See the BEHAVIOR topic for more information.

Parent topic: OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
BEHAVIOR


No change in default behavior and no optimization

Sets the SQL(BEHAVIOR) directive to SQL(BEHAVIOR=UNOPTIMIZED), meaning that data access is both scrollable and updatable for everything except data access that is explicitly specified as read only or for update.

With this option, OpenESQL does not perform block fetching, possibly degrading the performance of cursors that are not forward only, read only. Therefore we strongly recommend that you use this option only as an interim measure pending a change to one of the other default options such as Optimize for performance and mainframe compatibility or ANSI compliance.

Parent topic: OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
BEHAVIOR


Issue a warning at compile time

Generates a compile-time warning when the SQL(BEHAVIOR) directive has not been set in your program source code, project settings, or in the COBOL compiler directives file. In addition to generating the warning, the default behavior is set to SQL(BEHAVIOR=OPTIMIZED).

OpenESQL generates the warning when the compiler encounters the first error free EXEC SQL statement in each OpenESQL-based program.

Parent topic: OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
BEHAVIOR


Issue an error at compile time

Generates a compile-time error when the SQL(BEHAVIOR) directive has not been set in your program source code, project settings, or in the COBOL compiler directives file. In this case, all EXEC SQL statements are effectively ignored.

OpenESQL generates the error when the compiler encounters the first error free EXEC SQL statement in each OpenESQL-based program. Once the error is generated, OpenESQL ignores all subsequent EXEC SQL statements in that program.

Parent topic: OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
BEHAVIOR


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. Each OpenESQL preprocessor type requires a different configuration.

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

  • OpenESQL Assistant
  • 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
OpenESQL Configuration Utility for Default SQL Cursor Behavior


OpenESQL Assistant

The OpenESQL Assistant is an interactive tool that makes it easy for you to:

  • Generate SQL and PL/I SQL queries
  • Prototype SQL SELECT, INSERT, UPDATE, and DELETE statements and test them against your database
  • Insert your SQL queries into your COBOL or PL/I code
  • Create and insert auxiliary code into your COBOL or PL/I code
  • Setting OpenESQL Assistant Options
  • Generating Code with MDCLGEN
    Describes the MDCLGEN tool that can be used generate copybooks and include files as an alternative to generating them using the OpenESQL Assistant.
  • Using OpenESQL Assistant
Parent topic: Programming for OpenESQL
Related concepts
Select Type of Query to Create dialog box
To generate and embed auxiliary code
Data Source Properties dialog box
To view data source properties
Tutorials: OpenESQL Assistant
Unicode Support in OpenESQL
Related tasks
To enable PL/I SQL query generation
To set OpenESQL Assistant options
To connect to a data source
To connect to a different data source
To disconnect from a data source
To close a query
To run a query
To start the OpenESQL Assistant
To create a TSQL stored procedure query
To create an SQL query
To embed an SQL query into a program
To specify search criteria (a WHERE clause)
To sort returned data (an ORDER BY clause)
Related reference
OpenESQL Assistant - Main Window
Query tab
Results tab
Details tab
Search Criteria tab
Literal Value dialog box
Sort tab
Auxiliary Code tab


Setting OpenESQL Assistant Options

Before creating SQL queries using OpenESQL Assistant, you can set options that determine the behavior of the OpenESQL Assistant and specify how it generates SQL. See To set OpenESQL Assistant options for details.

Parent topic: OpenESQL Assistant
Related concepts
Select Type of Query to Create dialog box
Related tasks
To set OpenESQL Assistant options
To connect to a data source
To connect to a different data source
To disconnect from a data source
To close a query
To run a query
To start the OpenESQL Assistant
To create a TSQL stored procedure query
To create an SQL query
Related reference
OpenESQL Assistant - Main Window
SQL TYPEs
OpenESQL Assistant - Options


Generating Code with MDCLGEN

Note: This topic applies to Windows environments only.

MDCLGEN is a batch tool alternative to generating copybooks and include files using the OpenESQL Assistant. For the most part, MDCLGEN generates code using the current options set for the OpenESQL Assistant; however, you can override certain default settings via command-line parameters.

For details on using the MDCLGEN tool, see MDCLGEN command-line tool. For more information on OpenESQL Assistant options, see To set OpenESQL Assistant options and OpenESQL Assistant - Options.

Parent topic: OpenESQL Assistant


Using OpenESQL Assistant

Use the OpenESQL Assistant to easily design and build SQL queries and embed those queries into your COBOL or PL/I code. As you make specifications for a query, OpenESQL Assistant generates the necessary code for you. You can also test the queries you create to ensure they are producing the proper results before you embed them into your programs. And, you can use OpenESQL Assistant to generate and embed the auxiliary code necessary to support your queries in COBOL or PL/I.

  • Connecting to a data source
  • Building Queries
  • Testing Your SQL Queries
  • Creating Temporary Files
  • Embedding SQL into a program
  • Auxiliary Code
  • Stored Procedures
Parent topic: OpenESQL Assistant


Connecting to a data source

The OpenESQL Assistant must first connect to a data source before it can generate SQL. All data sources cataloged on your workstation for the database type you have selected as your OpenESQL Assistant Mode option (ODBC or XDB) are listed in the tree view of the OpenESQL Assistant. By default, the connection is made automatically after you select a database from the tree view. After you have connected, all of the table names in the data source show on the tree view. You can only connect to one data source at a time.

Important: You must connect to a 32-bit data source even if the generated application targets a 64-bit platform.
Note:
  • If you have not provided a User name and Password in your OpenESQL Assistant options, you might receive a connect error. In this case, OpenESQL Assistant prompts you for your User ID and Password.
  • PL/I SQL queries are supported using ODBC database connections only.
Parent topic: Using OpenESQL Assistant
Related tasks
To connect to a data source
To connect to a different data source


Building Queries

The process of building a query using OpenESQL includes at least some and potentially all of the following steps:

  • Determine which table you want to query
  • Select the type of query to create
  • Select a column or columns to query
  • Specify search criteria to limit returned data
  • Dictate the order in which data is retrieved and displayed
  • Specify table joins

The following sections provide information about this process.

  • Generating initial query code
  • Selecting Columns
  • Specifying Aggregate Functions for Columns
  • Specifying Search Criteria
  • Specifying the Order in which Data is Retrieved
  • Creating a Table Join
  • Working with Queries
Parent topic: Using OpenESQL Assistant
Related concepts
Select Type of Query to Create dialog box
Related tasks
To set OpenESQL Assistant options
To create a TSQL stored procedure query
To create an SQL query
To embed an SQL query into a program
To specify search criteria (a WHERE clause)
To create an SQL query
To start the OpenESQL Assistant
Related reference
Query tab
Results tab
Details tab
Search Criteria tab
Literal Value dialog box


Generating initial query code

The OpenESQL Assistant generates the initial query code after you have selected a table and a query type.

Selecting tables

You select one table at a time. The selected table appears with a check mark next to it. Once your initial SQL query code has been generated, you can select additional tables.

Note: Some databases use special characters in the names of system tables. For example, Oracle can use system tables whose names contain a dollar sign ($). When the OpenESQL Assistant encounters a special character in the name of system table that would render the generated table name illegal, it automatically encloses the column and table names in quotes.

Selecting a query type

Restriction: You can only generate TSQL stored procedures if you are connected to SQL Server data source.
Once you have selected a table, the Select Type of Query to Create dialog box appears. This dialog box contains a list of query types you can perform on your selection. Depending on the type of query you select, you have some options. You can create the following types of queries including these options:
SELECT (cursor)
Generates a SELECT statement for the selected table using the cursor specified in the Cursor Name field and including a table alias. Here, you have the option to generate the query with a FOR UPDATE clause.
SELECT DISTINCT (cursor)
Generates a SELECT DISTINCT statement for the selected table using the cursor specified in the Cursor Name field. Here, you have the option to generate the query with a FOR UPDATE clause.
SELECT (Singleton)
Generates a SELECT statement for the selected table using the name specified in the SP Name field.
SELECT DISTINCT (Singleton)
Generates a SELECT DISTINCT statement for the selected table using the name specified in the SP Name field.
UPDATE
Generates an UPDATE statement for the selected table. Here, you have the option to generate the query with a WHERE CURRENT OF clause.
INSERT
Generates an INSERT statement for the selected table using the name specified in the SP Name field.
DELETE
Generates a DELETE statement for the selected table. Here, you have the option to generate the query with a WHERE CURRENT OF clause.

Initial query generation

Once you have selected a query type and options, the initial SQL code for the query you have selected is automatically generated and displayed underneath the Query tab. At the same time, a list of all the columns in the table is displayed underneath the table name.

For SELECT queries, a table alias is automatically generated by the OpenESQL Assistant. For example:
SELECT FROM Customer A

The first table selected generates an alias of the letter A. If you select a second table, the OpenESQL Assistant generates an alias of B and so on.

You can use the query as is, or continue to build the query by adding tables, columns, search criteria, and auxiliary code as necessary.

Parent topic: Building Queries
Related tasks
To create an SQL query
To generate an INSERT statement
To generate a DELETE statement
To generate a SELECT (cursor) statement
To generate a SELECT (singleton) statement
To generate an UPDATE statement


Selecting Columns

Once you have generated your initial query code, you can select one or more columns to process in your query. You can add columns to your query by checking the box that appears next to a column name in the tree view. Selected columns appear in the tree view with a check mark next to them. Each column name is prefixed by its alias (for example, A.CustID, A.Company). This enables you to distinguish the columns in one table from those in another.

Note: If the name generated from the column name (including any prefixes and suffixes) is longer than 31 characters or contains characters that are illegal in COBOL, OpenESQL generates a host variable using the column number (for example, COL005) rather than the column name.
Parent topic: Building Queries
Related tasks
To add a column to a query


Specifying Aggregate Functions for Columns

You can specify an aggregate function for any column in a SELECT (cursor) or SELECT DISTINCT (cursor) query. An aggregate function retrieves certain information about the data returned from a column.

OpenESQL returns the following information for each group of returned data:

Aggregate Function | Value for each group of returned data
Sum | Sum of all values returned (numerical columns only)
Avg | Average of all values returned (numerical columns only)
Max | Maximum value returned
Min | Minimum value returned
Count | Number of records returned
Parent topic: Building Queries


Specifying Search Criteria

You can limit which rows are returned by a query by specifying search criteria on the OpenESQL Assistant Search Criteria tab. OpenESQL Assistant generates a WHERE clause based on the criteria you specify.

Parent topic: Building Queries
Related tasks
To specify search criteria (a WHERE clause)
To specify search criteria (a WHERE clause)
Related reference
Search Criteria tab


Specifying the Order in which Data is Retrieved

You can order the rows that are returned by a query by specifying which columns to sort using the OpenESQL Assistant Sort tab. OpenESQL Assistant generates an ORDER BY clause based on the order you specify.

Parent topic: Building Queries
Related tasks
To sort returned data (an ORDER BY clause)


Creating a Table Join

Where tables have at least one column in common, you can create a table join enabling you to retrieve information from more than one table at the same time. The OpenESQL Assistant creates a table join using the first matching column it finds. If OpenESQL does not find any matching columns, it cannot generate the join automatically. In this case, you can specify the join using the Search Criteria feature.

This feature is only available for SELECT queries.

Parent topic: Building Queries


Working with Queries

These topics present some features of OpenESQL Assistant that can help you enhance your ability to create queries.

  • Display Column Details
  • Disconnect from a Data Source
  • Close a Query
  • Remove a Table from a SELECT Query
  • Changing a SELECT (cursor) query to do an Array FETCH
Parent topic: Building Queries


Display Column Details

The Details tab in the OpenESQL Assistant shows detailed information on the columns in a table. The columns on the Details tab describe the columns in the selected table as follows:

  • Column Name

    The column name of each column in the table. Notice that each column name is prefixed by the table alias. For example, a table with the name CustID shows on in the Column Name column as A.CustID. A tick in the box to the left of Column Name indicates that the column is currently selected.

  • Type

    The data type of the column. These are the data types used by the data source to which you are connected. The data type of a column must match the COBOL picture clause of the host variable that is used to pass values for that column to and from the data source.

    OpenESQL Assistant can generate a copybook, tablename.cpy, in the current directory that declares all of the necessary host variables, matching them with COBOL picture clauses generated using column data types. See the topic Auxiliary Code for more details.

  • Precision

    The total number of digits in numerical columns or the length of the column for text columns.

  • Scale

    The number of digits to which the column is rounded, where relevant.

  • Host Variable

    The value of the generated host variable for the column. Generated host variable names take the form:

    :<table-name>-<column-name>
  • Indicator Variable

    The value of the generated indicator variable for the column. Generated indicator variable names take the form:

    :<table-name>-<column-name>-NULL
Parent topic: Working with Queries
Related concepts
Working With OpenESQL Cursors and Result Sets
Auxiliary Code
Related tasks
To display column details
Related reference
Details tab


Disconnect from a Data Source

When you disconnect from a data source, OpenESQL discards the current query. You must disconnect from one data source before you can connect to another.

Parent topic: Working with Queries
Related tasks
To disconnect from a data source


Close a Query

When you close a query, OpenESQL discards the generated code, enabling you to start a new query.

Parent topic: Working with Queries
Related tasks
To close a query


Remove a Table from a SELECT Query

Most queries you create using OpenESQL Assistant access one table only. If you remove that table from the query, OpenESQL closes the query and you lose the code you've generated for it. However, if you have created a SELECT query that contains one or more table joins, you can safely remove a table without closing the query. When you initiate the removal of a table from a SELECT query, you're prompted to confirm your decision. Upon confirmation, OpenESQL removes the generated code that pertains to the table from the query. It also removes any code pertaining to columns that belong to that table.

Parent topic: Working with Queries
Related tasks
To remove a table from a SELECT query


Changing a SELECT (cursor) query to do an Array FETCH

OpenESQL Assistant doesn't directly generate code for array fetches. However, you can modify the SELECT (cursor) code generated by OpenESQL Assistant to handle array fetches.

Parent topic: Working with Queries


Testing Your SQL Queries

You can use OpenESQL Assistant to test the queries you create before committing them to program code. To do this, you simply run a query from the OpenESQL Assistant. The results for all SELECT statements appear automatically on the Results tab. Other query types return the following information in a message box:

  • The name of the query executed
  • The number of rows returned
  • Whether or not the query ran successfully

Occasionally, the query you create will require additional specifications for it to execute correctly. If OpenESQL Assistant cannot execute the code, you are prompted to correct it.

Note: When you run a query in OpenESQL Assistant, any UPDATE, INSERT, and DELETE statements do execute against the database, potentially altering its contents (applies to Windows environments only).
Parent topic: Using OpenESQL Assistant
Related reference
Results tab


Creating Temporary Files

As you complete each query and set of auxiliary code, we recommend that you add the generated code to a temporary file. This temporary file stores the code you have generated and makes it available for copying and pasting individual queries and sets of auxiliary code into a program in your Eclipse project. You can also save the temporary file for later reference, or even create a complete program that you can add directly to your Eclipse project.

Parent topic: Using OpenESQL Assistant
Related tasks
To create a complete program in a temporary file
To create a temporary file
To view a temporary file


Embedding SQL into a program

Once you are happy with the SQL query that you have created, you can insert it into your COBOL or PL/I program by copying it or adding the query to a temporary file Insert query into program, and then pasting the query into your program in the Eclipse Editor.

Parent topic: Using OpenESQL Assistant
Related tasks
To create a complete program in a temporary file
To create a temporary file
To embed an SQL query into a program


Auxiliary Code

The SQL queries you generate with OpenESQL often require additional code outside of the query itself in order to execute properly from your COBOL programs. For example, under DB2 LUW you cannot successfully execute an SQL query that accesses a database until you have inserted a CONNECT statement to connect to the data source. Once you have embedded your query, you can use OpenESQL Assistant to generate and embed this auxiliary code.

  • Generating EXEC SQL Auxiliary Code
  • Embedding Auxiliary Code
Parent topic: Using OpenESQL Assistant
Related concepts
To generate and embed auxiliary code
Display Column Details
Related tasks
To embed an SQL query into a program
Related reference
Auxiliary Code tab


Generating EXEC SQL Auxiliary Code

OpenESQL Assistant can generate the following types of EXEC SQL auxiliary code:

CONNECT Statement
Generates a CONNECT statement based on known information about your current data source connection.
Type 6 CONNECT Statement
Generates a type 6 CONNECT statement, allowing the application to connect to data sources that are not cataloged.
SQLCA Declaration
Generates an INCLUDE statement to include an SQL Communications Area (SQLCA) in your program.
Host Variable Declarations
For each table that you have selected, the OpenESQL Assistant generates a copybook that includes all of the host variable declarations you need. The OpenESQL Assistant can also generate the INCLUDE statement necessary to include the copybook in your program.
OpenESQL Assistant DISCONNECT Statement
Generates a DISCONNECT statement to disconnect from the current data source.
COMMIT Statement
Generates a COMMIT statement to commit changes to a data source issued from a previous SQL statement.
ROLLBACK Statement
Generates a ROLLBACK statement to rollback changes to a data source issued by a previous SQL statement or statements.
Generic SQL or PL/I Program
Generates a skeleton SQL or PL/I program, depending on the setting of the Output language option, that includes the INCLUDE SQLCA, CONNECT and DISCONNECT SQL statements and a default SQL error routine.
Note: When you have set your Output language option to PLI, OpenESQL Assistant generates auxiliary code identical to COBOL SQL auxiliary code with one exception. INCLUDE statements are generated as PL/I %INCLUDE rather than EXEC SQL INCLUDE.
Parent topic: Auxiliary Code
Related tasks
To embed an SQL query into a program


Embedding Auxiliary Code

You embed auxiliary code in the same manner as you embed your SQL queries.

Parent topic: Auxiliary Code
Related tasks
To embed an SQL query into a program


Stored Procedures

This section provides information on generating stored procedures and testing them using OpenESQL Assistant.

Multiple types of SQL statements can exist within a stored procedure. OpenESQL Assistant is not designed to generate stored procedures with multiple types of SQL statements. You need tools, such as the ones provided by Microsoft, to do this.

The intention of OpenESQL Assistant is to allow you to quickly learn how to generate simple SQL stored procedures and the COBOL code required to invoke those stored procedures.

  • Generating a TSQL Stored Procedure Query
  • Testing a TSQL Stored Procedure Query
  • Embedding a TSQL Stored Procedure into a Program
Parent topic: Using OpenESQL Assistant
Related concepts
Select Type of Query to Create dialog box
Related tasks
To set OpenESQL Assistant options
To create a TSQL stored procedure query
To create an SQL query


Generating a TSQL Stored Procedure Query

Microsoft provides tools to create, edit, and test TSQL stored procedures. It is then the task of the programmer to generate the code to invoke these stored procedures from a COBOL client program. The OpenESQL Assistant makes this process easier.

When using Microsoft SQL Server data sources, you have the option to use OpenESQL Assistant to generate the query as a stored procedure. OpenESQL Assistant generates both the SQL statements to create the stored procedure and the client code to invoke it.

OpenESQL Assistant generates two SQL statements that drop the stored procedure and then create it. You typically place these SQL statements in a server program because they only need to be executed once.

OpenESQL Assistant also generates the code that goes into the client program and invokes the stored procedure. Depending on the type of query you select, OpenESQL Assistant might generate a DECLARE CURSOR statement that invokes the stored procedure or it might generate SQL CALL statements only.

Parent topic: Stored Procedures
Related tasks
To create a TSQL stored procedure query


Testing a TSQL Stored Procedure Query

Once you have built the TSQL stored procedure query, you can test it in much the same manner as you test other queries. However, because multiple SQL statements are created by OpenESQL Assistant for a stored procedure, you need to run the query multiple times. Each time you run the query, you execute the next SQL statement.

The first time you run the query, the DROP PROCEDURE statement is executed, and the following message appears:

Cannot drop the procedure 'spname,' because it does not exist...

This message is expected and will change if you execute the DROP PROCEDURE multiple times.

The second time you run the query, the CREATE PROCEDURE statement is executed. A message appears indicating that the statement executed successfully.

To execute a stored procedure CALL statement with search criteria that requires you to provide a literal value, you are prompted to provide that literal value.

When all SQL statements have been executed, OpenESQL shows the results on the Results tab.

You can repeat this process until you are satisfied with the results.

Parent topic: Stored Procedures


Embedding a TSQL Stored Procedure into a Program

This procedure is also similar to that of embedding a standard SQL query into a program.

OpenESQL Assistant generates statements for both client and server programs. You can delete the statements which are not needed. If your program is the client program, the DROP and CREATE PROCEDURE statements are not necessary.

Note: If you test the query as outlined above, you do not need to run either the DROP or CREATE PROCEDURE statements in a program as the TSQL stored procedure has already been created. If the stored procedure has not already been created, then you need to either add an SQL COMMIT statement or add directive SQL(AUTOCOMMIT) to the program that issues the CREATE PROCEDURE. Otherwise the stored procedure is not saved to the data source.
Parent topic: Stored Procedures
Related tasks
To embed an SQL query into a program


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 concepts
Display Column Details
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
Note: If an application uses Static SQL, it returns standard data types. If, however, an application uses Dynamic SQL, it returns the new data types listed above. This applies to Windows environments (local development) only.

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.

OpenESQL Assistant has also been enhanced to support unicode data. See the chapter OpenESQL Assistant for details.

Parent topic: Programming for OpenESQL
Related concepts
OpenESQL Assistant


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.
  • To start the ODBC Data Source Administrator
  • Using OpenESQL with ODBC
    Programming and compiling OpenESQL native SQL applications with ODBC.
  • Using OpenESQL with Web and Application Servers
    Using OpenESQL in environments controlled by Web and Application Servers, such as IIS, MTS, COM+, CICS and Tuxedo.
Parent topic: OpenESQL
Related concepts
Programming for OpenESQL
Related reference
DBMAN


Demonstration Applications

Enterprise Developer provides a number of demonstration applications or programs for OpenESQL ODBC. On Windows platforms, you can access these via the Mainframe and Visual COBOL Samples Browsers. For instructions on how to start either Samples Browser, see To start the Samples Browser.

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.

Mainframe Samples – Windows Environment

All ODBC samples are listed on the Show unmanaged only list in the Mainframe Samples Browser.

The source files are located in subdirectories under %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\SQL\OpenESQL\JCLCallingSP.

Each sample application comes with a Readme file to explain how to use the application.

OESQL - JCL Calling SP Multi-project by Data Name
Walks you through the process of invoking a native COBOL program using JCL, and calling programs and stored procedures in multiple assemblies using data names.
OESQL - JCL Calling SP Multi-project by Literal
Walks you through the process of invoking a native COBOL program using JCL, and calling programs and stored procedures in multiple assemblies using literals.
OESQL - JCL Calling SP Single-project by Data Name
Walks you through the process of invoking a native COBOL program using JCL, and calling programs and stored procedures in a single assembly using data names.
OESQL - JCL Calling SP Single-project by Literal
Walks you through the process of invoking a native COBOL program using JCL, and calling programs and stored procedures in a single assembly using literals.

Visual COBOL Samples – Windows Environment

All ODBC samples are listed on the Show unmanaged only list in the Visual COBOL Samples Browser.

The source files are located in subdirectories under %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Eclipse\COBOL\SQL\openesql.

OESQL - Getting Started
A simple example of using static SQL with OpenESQL, performing a variety of SQL operations. It also demonstrates the use of different styles of CONNECT statement.
OESQL - Behavior
Connects to a data source name LocalServer using the Microsoft SQL Server ODBC driver. To do this, see the Help topic To set up an ODBC data source name.

The program creates and populates a table used by behavior.cbl and behavsub.cbl. After the table is created, we show how the BEHAVIOR directive makes the same ambiguous COBOL cursor declaration read only in behavior.cbl and updateable in behavsub.cbl.

You can verify this by looking at the trace file OpenESQLTrace.processID.log, in the project directory. The log file is generated by the TRACELEVEL directive in behavior.cbl.

OESQL - Catalog
Displays an SQL Data Sources dialog. Enter or select a name and click on OK. A Login dialog is displayed. Enter a login name of "admin", leave the password blank and click on OK. Performs three data dictionary queries and outputs the results.
OESQL - Connect
Prompts for a data source, user name and password. Enter the data source name you created, a user name of "admin" and leave the password blank (just press return). Four tests which perform connects and disconnects using a variety of syntax options are run. The fifth test displays an SQL Data Sources dialog. Select the appropriate name from the Machine Data Source list and click on OK. A Login dialog is displayed. Enter a login name of "admin", leave the password blank and click on OK. The fifth test is run and the program terminates.
OESQL - Dynamic
A simple example of using dynamic SQL with OpenESQL, performing a variety of SQL operations. It is functionally equivalent to the code used by the Getting Started sample.
OESQL - Get Diagnostics
Shows how to use Get Diagnostics EXEC SQL calls to get diagnostic information from the OpenESQL runtime. This demo works with a Microsoft SQL Server but can also work with IBM DB2 LUW and Oracle.
OESQL - LOB Data Types
Shows how to use OpenESQL to insert and select large objects (LOBs), and shows OpenESQL working with LOB columns within a Microsoft SQL Server table. Includes instructions for working with IBM DB2 LUW and Oracle.
OESQL - Select
Connects to the sample database and prompts for a customer code. Enter BLUEL (as the prompt suggests). Two fields from the customer record are displayed and the program prompts for another customer code. Just press the return key this time. The program prompts for a region. Enter CA (as the prompt suggests). The program displays a list of customers in that region and prompts for another region. This time, press the return key to terminate the program.
OESQL - Whenever
Illustrates the use of EXEC SQL WHENEVER syntax to aid with error handling. It also uses the MFSQLMESSAGETEXT variable for retrieving error messages longer than the 70 bytes available within the SQLERRMC field.

UNIX Environment

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
Related tasks
To start the Samples Browser


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.
    Note: When using the SQL Server driver installed automatically by most Windows operating systems, be sure that the driver corresponds to the release of SQL Server you are using. (applies to Windows environments only)
  • 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. On Windows platforms only, you can do this using the ODBC Data Source Administrator. For more information, see To start the ODBC Data Source Administrator.
Parent topic: ODBC
Related tasks
To start the ODBC Data Source Administrator


To start the ODBC Data Source Administrator

Note: This topic applies to Windows environments only.
Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > Data Connections > ODBC Data Source Administrator (32-bit) or ODBC Data Source Administrator (64-bit).
Windows 8.1
  • From the Windows Start screen, click either the ODBC Data Source Administrator (32-bit) or the ODBC Data Source Administrator (64-bit) tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > ODBC Data Source Administrator (32-bit) or ODBC Data Source Administrator (64-bit).
Parent topic: ODBC
Related concepts
ODBC Drivers and Data Source Names
Related tasks
To add a Data Source Name (DSN) for an ODBC driver


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. You can then build SQL statements using the OpenESQL Assistant from the XML data source. Use the PERSIST embedded SQL statement to convert information to XML.

Parent topic: Using OpenESQL with ODBC
Related reference
PERSIST


Using OpenESQL with Web and Application Servers

Restriction: This topic applies to Windows environments (local development) only.

This section describes what you must do to use OpenESQL in environments controlled by Web and Application Servers, such as IIS, MTS, COM+, CICS and Tuxedo.

All servers differ, but the principle described here is common to them all.

  • Thread Safety
  • Connection Management
  • Transactions
  • User Accounts, Schemas and Authentication
  • Transaction Wrapper Sample
Parent topic: ODBC


Thread Safety

Restriction: This topic applies to Windows environments (local development) only.

OpenESQL is thread safe. Normally all threads in an application share SQL resources such as connections and cursors. When running with an application server, however, threads will be scheduled to handle requests from different users. Therefore, you must use the directive:

SQL(THREAD=ISOLATE)

to ensure that each thread's resources are isolated from each other.

Note: OpenESQL has an overhead of 72K for each thread created, and this memory is not released until the application terminates.
Parent topic: Using OpenESQL with Web and Application Servers


Connection Management

Restriction: This topic applies to Windows environments (local development) only.

In most environments, the application server will manage a pool of connections, which means that actual connect and disconnect requests to the database will be rare. When an application runs, it will reuse an existing connection. In most cases, connection pooling will be managed by the ODBC Driver Manager and will be transparent to the application. In other cases, the application server itself will manage the connection pool, and the application must use a "set connection" statement before it does anything else.

Where the application uses OpenESQL connect and disconnect statements, and it is not clear that the application server itself enables ODBC connection pooling, it might be worth experimenting with the SQL(CONNECTIONPOOL=...) directive. However, you are unlikely to need to do this.

Parent topic: Using OpenESQL with Web and Application Servers


Transactions

Restriction: This topic applies to Windows environments (local development) only.

In many cases, the application server provides transaction management. This is determined when your component is placed under the control of the application server.

If the application server is not providing transaction management, it must use OpenESQL COMMIT and ROLLBACK statements to manage transactions.

If, however, the application server is providing transaction management, the following applies:

  • If connection management is not provided by the application server (that is, your application uses CONNECT and DISCONNECT statements), you can use one of the following to handle transactions:
    • Set the TRANSACTION primitive directive of the BEHAVIOR SQL compiler directive option (recommended).
    • Set the AUTOCOMMIT SQL compiler directive option to enable your application to handle transactions using COMMIT and ROLLBACK statements.
    • Use the application server to provide API calls or return codes for you to signal success or failure.

If you are using MTS or COM+, the default transaction isolation level, when the application server is managing transactions, can be serialized. This might cause excessive locking, and reduce concurrency. Your application must be prepared to deal with its transaction being aborted when the application server attempts to resolve a deadlock. To ease these problems, you can use the following statement:

exec sql set transaction isolation read committed end-exec

to set a less stringent isolation level. In this case, the statement must be the first statement to be executed after the CONNECT statement. Note that when SQL(AUTOCOMMIT) is not used, a commit or rollback is required immediately prior to executing a SET TRANSACTION ISOLATION statement.

Parent topic: Using OpenESQL with Web and Application Servers


User Accounts, Schemas and Authentication

Restriction: This topic applies to Windows environments (local development) only.

When running in an application server environment, the user account in which your application executes might be different from the account used for development. ODBC data sources set up as user data sources might, therefore, not be available. You will probably find it more convenient to set up data sources as system data sources on deployment systems. When a file-based data source is used, the database files must be accessible by the account used by the application server. When accessing the database, particularly if integrated security is used (that is, when the DBMS uses the same account number as the operating system), the default schema might be different from that used during development. This might well be what is intended, if different schema names are used for development and deployment. Alternatively, it might mean that tables are no longer visible to the application. It must either use explicit owner qualification, or execute a database-specific statement, which will select the correct schema to be the default.

Parent topic: Using OpenESQL with Web and Application Servers


Transaction Wrapper Sample

Restriction: This topic applies to Windows environments (local development) only.

The following is an example of an transaction wrapper generated by the OCX Wizard modified to include the OpenESQL logic to handle the following scenarios using an MS SQL Server data source:

  • standalone transaction with no MTS/COM+ involved
  • component managed by MTS/COM+ but without MTS/COM+ handling transactions
  • component and transactions handled by MTS/COM+
$set ooctrl(+p) sql(thread=isolate autocommit)
*>-----------------------------------------------------------
*> Class description
*>-----------------------------------------------------------
 class-id. cblsqlwrapper
           inherits from olebase.
 object section.
 class-control.
     cblsqlwrapper is class "cblsqlwrapper"
*> OCWIZARD - start list of classes
     objectcontext is class "objectcontext"
     olebase is class "olebase"
     oleSafeArray is class "olesafea"
     oleVariant is class "olevar"
*> OCWIZARD - end list of classes
*>---USER-CODE. Add any additional class names below.
*>-----------------------------------------------------------
 working-storage section. *> Definition of global data
*>-----------------------------------------------------------

*>-----------------------------------------------------------
 class-object.   *> Definition of class data and methods
*>-----------------------------------------------------------
 object-storage section.

*> OCWIZARD - start standard class methods
*>-----------------------------------------------------------
*> Return details about the class.
*> If you have a type library, theClassId and theInterfaceId
*> here MUST match.
*> theProgId must match the registry entry for this class
*>   (a zero length string implies using the class file name)
*> theClassId must match the CLSID stored in the registry.
*> theVersion is currently ignored (default 1 used).
*>-----------------------------------------------------------
 method-id. queryClassInfo.
 linkage section.
 01 theProgId             pic x(256).
 01 theClassId            pic x(39).
 01 theInterfceId         pic x(39).
 01 theVersion            pic x(4) comp-5.
 01 theDescription        pic x(256).
 01 theThreadModel        pic x(20).
 procedure division using by reference theProgId
                          by reference theClassId
                          by reference theInterfceId
                          by reference theVersion
                          by reference theDescription
                          by reference theThreadModel.
     move z"{3EADD92C-06C5-46F2-A2E0-7EB0794C14DF}"
                                            to theClassId
     move z"{5BF3F966-9932-4835-BFF6-2582CA2592AD}"
                                            to theInterfceId
     move z"Description for class cblsqlwrapper"
                                            to theDescription
     move z"Apartment" to theThreadModel
     exit method.
 end method queryClassInfo.
 .

*>-----------------------------------------------------------
*> Return details about the type library - delete if unused.
*> theLocale is currently ignored (default 0 used).
*> theLibraryName is a null terminated string used for auto
*> registration, and supports the following values:
*>    <no string> - Library is embedded in this binary
*>    <number>    - As above, with this resource number
*>    <Path>      - Library is at this (full path)
*>                        location
*>-----------------------------------------------------------
 method-id. queryLibraryInfo.
 linkage section.
 01 theLibraryName        pic x(512).
 01 theMajorVersion       pic x(4) comp-5.
 01 theMinorVersion       pic x(4) comp-5.
 01 theLibraryId          pic x(39).
 01 theLocale             pic x(4) comp-5.
 procedure division using by reference theLibraryName
                          by reference theMajorVersion
                          by reference theMinorVersion
                          by reference theLibraryId
                          by reference theLocale.
     move 1 to theMajorVersion
     move 0 to theMinorVersion
     move z"{24207F46-7136-4285-A660-4594F5EE7B87}"
                                            to theLibraryId
     exit method.
 end method queryLibraryInfo.

*>-----------------------------------------------------------

*> OCWIZARD - end standard class methods

 end class-object.

*>-----------------------------------------------------------
 object.         *> Definition of instance data and methods
*>-----------------------------------------------------------
 object-storage section.

*> OCWIZARD - start standard instance methods
*> OCWIZARD - end standard instance methods

*>-----------------------------------------------------------
 method-id. "RetrieveString".
 working-storage section.

 01 mfsqlmessagetext pic x(400).
 01 ESQLAction       pic x(100).

 COPY DFHEIBLK.

 COPY SQLCA.
*>...your transaction program name
 01 transactionPgm           PIC X(7) VALUE 'mytran'.

 local-storage Section.
 01 theContext              object reference.
 01 transactionStatusFlag   pic 9.
   88 transactionPassed     value 1.
   88 transactionFailed     value 0.
*>---USER-CODE. Add any local storage items needed below.

 01 ReturnValue             pic x(4) comp-5.
   88 IsNotInTransaction    value 0.

 01 transactionControlFlag  pic 9.
   88 TxnControlledByMTS    value 0.
   88 TxnNotControlledByMTS value 1.

 linkage Section.

*>...Info passed to transaction
 01 transaction-Info.
    05 transaction-Info-RC   pic 9.
    05 transaction-Info-data pic x(100).

*>...Info returned from transaction via
 01 transaction-Info-Returned pic x(100).

 procedure division using by reference transaction-Info
                    returning transaction-Info-Returned.

*>...initialisation code
     perform A-Initialise
     perform B-ConnectToDB
     if TxnNotControlledByMTS
         perform C-SetAutoCommitOff
     end-if

*>...set isolation level to override SQLServer default,
*>...serialize
     perform D-ResetDefaultIsolationLevel

*>...set cursor type to overrde the OpenESQL default,
*>...dynamic+lock
     perform E-ResetDefaultCursorType

*>...call the transaction
     perform F-CallTransaction

*>...finalisation code - issue Commit/Rollback if not
*>...controlled by MTS/COM+
     if TxnNotControlledByMTS
         if transactionPassed
             perform X-Commit
         else
             perform X-Rollback
         end-if
     end-if

     perform Y-Disconnect

*>...Transaction Server - use setAbort if the method fails:
     if theContext not = null
         if transactionPassed
             invoke theContext "setComplete"
         else
             invoke theContext "setAbort"
         end-if
         invoke theContext "finalize" returning theContext
     end-if

     exit method
     .

 A-Initialise.
*>...Transaction Server - get the context we are running in
     invoke objectcontext "GetObjectContext"
            returning theContext

*>...check if this component is enlisted in an MTS transation
     if theContext = null
         set TxnNotControlledByMTS to true
     else
         invoke theContext "IsInTransaction"
                returning ReturnValue
         if IsNotInTransaction
             set TxnNotControlledByMTS to true
         else
            set TxnControlledByMTS    to true
          end-if
     end-if

*>...initialise program variables
     set transactionPassed to true

     INITIALIZE DFHEIBLK
     .

 B-ConnectToDB.
*>...connect to data source

     EXEC SQL
         CONNECT TO 'SQLServer 2000' USER 'SA'
     END-EXEC

     if sqlcode  zero
         move z"connection failed " to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if
     .

 C-SetAutoCommitOff.
     EXEC SQL
         SET AUTOCOMMIT OFF
     END-EXEC
     if sqlcode  zero
         move z"Set Autocommit Off failed " to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if

     perform X-Commit
    .

 D-ResetDefaultIsolationLevel.
*> the default isolation level for SQLServer is "Serialized",
*> so here we reset it to something more appropriate

     EXEC SQL
         SET TRANSACTION ISOLATION READ COMMITTED
     END-EXEC
     if sqlcode  zero
         move z"set transaction isoation failed "
                                            to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if
     .

 E-ResetDefaultCursorType.
*> the default cursor type for OpenESQL is dynamic + lock
*> the most efficient is a "client" or "firehose" cursor -
*> this is a cursor declared as forward + read only - doing
*> this here will set it as a default from now on.  If
*> Forward causes a problem, change the concurrency to fast
*> forward (but note that it will then no longer be a client
*> cursor)

     EXEC SQL
         SET CONCURRENCY READ ONLY
     END-EXEC
     if sqlcode  zero
         move z"Set Concurrency Read Only" to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if

     EXEC SQL
         SET SCROLLOPTION FORWARD
     END-EXEC
     if sqlcode  zero
         move z"Set Concurrancy Read Only" to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if
     .

 F-CallTransaction.
*>...call the program to process the transaction
     move 0               to  transaction-Info-RC
     call tranactionPgm using dfheiblk transaction-Info

*>...check if processing was okay
     if transaction-Info-RC = 0
        set transactionPassed to true
     else
        set transactionFailed to true
     end-if
     .

 X-Commit.
     EXEC SQL
         COMMIT
     END-EXEC
     if sqlcode  zero
         move z"Commit failed " to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if
     .

 X-Rollback.
     EXEC SQL
         ROLLBACK
     END-EXEC
     if sqlcode  zero
         move z"Rollback failed " to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if
     .

 Y-Disconnect.
     EXEC SQL
         DISCONNECT CURRENT
     END-EXEC
     if sqlcode  zero
         move z"Disconnect failed " to ESQLAction
         perform Z-ReportSQLErrorAndExit
     end-if
     .

 Z-ReportSQLErrorAndExit.
     move spaces to transaction-Info-Returned
     string ESQLAction delimited by x"00"
            "SQLSTATE = "
            SQLSTATE
            "  "
            mfsqlmessagetext
            into transaction-Info-Returned
     end-string

     exit method
     .

 exit method.
 end method "RetrieveString".
*>-----------------------------------------------------------

 end object.
 end class cblsqlwrapper.
Parent topic: Using OpenESQL with Web and Application Servers


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
  • Demonstration Application
    A description of the demonstration application provided to illustrate programming techniques and runtime behavior for managed applications using JDBC.
  • 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 Enterprise Developer 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


Demonstration Application

Restriction: This topic applies to Windows environments only.

Enterprise Developer provides one JDBC sample application – Getting Started with JDBC. You can run the sample from the Visual COBOL Samples Browser. See To start the Samples Browser for instructions.

The JDBC sample is listed on the Show managed only list in the Visual COBOL Samples Browser.

The source files are located in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\SamplesEclipse\jvm_cobol by default.

The sample application comes with a Readme file to explain how to use the application.

Before you can use the demonstration application, you need to set up a data source to use by the demonstration.

This demonstration application produces a console log displaying its progress and, possibly, query results. It terminates on receipt of an error after displaying an error message.

OESQL - Getting Started with JDBC
Introduces using OpenESQL with JDBC, and shows how to connect to a database using either Connection Strings or Data Sources. To use Connection Strings you will need to add only your JDBC driver to the build or classpath. To use data sources you will need a JNDI implementation, such as Simple-JNDI, along with configuration files to define the data sources. See the JDBC topic within your product documentation for further information.
Parent topic: JDBC
Related tasks
JDBC
To start the Samples Browser


JDBC Process

We recommend the following process for developing, building, and executing a JVM COBOL application for JDBC:

  1. Assemble your JDBC resources
  2. Create a JVM COBOL project in Enterprise Developer
  3. Set Micro Focus project properties, including SQL Preprocessor and JVM Build Path properties
  4. Assemble application components in your JVM COBOL project
  5. Develop application code
  6. Add appropriate database connection code to your JDBC programs
  7. Build the project
  8. Debug or Run the application in Enterprise Developer
Note: You can also run the application from the command line instead of from the Enterprise Developer project; however, to do so, you must also configure the JVM runtime environment.
Parent topic: JDBC
Related concepts
Configuring the JDBC Run-time Environment
Database Connections
Setting the OpenESQL Preprocessor and Compiler Directive Options
Related tasks
To create a JVM COBOL project for JDBC
To add JDBC resources to the JVM Build Path


JDBC Resources

To build and execute JDBC applications, Enterprise Developer 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 Enterprise Developer project or 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, c:\jdbcrsc (Windows) or /home/jdbcrsc (UNIX).
  2. Create a subdirectory to the root directory in which to store data source files. For example, C:\jdbcrsc\DataSources (Windows) or /home/jdbcrsc/DataSources (UNIX).
User Library
You can reduce the work required to satisfy JDBC resource dependencies by creating an Eclipse user library for your workspace. You define a user library to contain all of the JAR files required for your JVM Build Path. This enables you to point to the user library when building and executing applications, rather than reassembling the JAR components of the JVM Build Path from scratch for each JVM COBOL project. The library import and export features enable you to reuse a single user library across multiple workspaces.

Required Resources

The resources required to build and execute JDBC applications are:

JDBC Drivers
Your Enterprise Developer project must be able to access the JDBC driver provided by your database. 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 Windows or 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 Enterprise Developer projects. 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.
Additional Resources for Microsoft SQL Server

On Windows platforms, if you are not using Windows authentication, no additional resources are required. However, if you are using Kerberos authentication with a driver version of 4.0 or later, then you do not need to enable integrated authentication, but you might need to follow additional configuration steps as described in the driver documentation.

Parent topic: JDBC
Related concepts
Database Connections
JNDI DataSource Objects
Connect Using a JNDI DataSource Object
Related tasks
To create a user library for JDBC resources
To import a user library
To export a user library
To install and configure Simple-JNDI
To create a JVM COBOL project for JDBC
To add JDBC resources to the JVM Build Path
To create a JNDI DataSource object
Related reference
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 JVMGEN compiler directive (Windows) or the -j command flag (UNIX), and JDBC by setting the DBMAN SQL compiler directive option. For example:

cobol myprog.cbl JVMGEN SQL(DBMAN=JDBC); (Windows)

Or:

cob -j myprog.cbl -C "SQL(DBMAN==JDBC)" (UNIX)

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.
  • The OpenESQL Assistant provides an easy method of generating JVM host variables for a table via the DCLGEN option in the tool. See OpenESQL Assistant for more information on how to generate copybooks in this format.

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


COBOL Program Migration Support

You can use OpenESQL as an effective migration tool, particularly when you migrate from the mainframe. OpenESQL provides the BEHAVIOR directive to define the COBOL environment and make migration transparent, yet efficient. You can set BEHAVIOR to any of the following:

OPTIMIZED | Enables OpenESQL to work as it does on the mainframe, and enhances the access speed (default)
ANSI | Enables OpenESQL to work like the ANSI standard, and enhances the access speed
UNOPTIMIZED | Provides backward compatibility with earlier Micro Focus products
MAINFRAME | Synonym for OPTIMIZED, provided for backward compatibility only
CICS Sets all of the following:
  • Enables OpenESQL to work as it does on the mainframe
  • Enhances the access speed
  • Automatically sets the TRANSACTION primitive directive to GLOBAL
JCL Sets all of the following:
  • Enables OpenESQL to work as it does on the mainframe
  • Enhances the access speed
  • Checks for the following statements that are not compatible with JCL applications:
    • CONNECT
    • DISCONNECT
    • SET CONNECT
  • Reports an error for each incompatible statement found
primitivedirective | Optional directives that enable the fine-tuning of BEHAVIOR

With either the OPTIMIZED or ANSI values, OpenESQL determines:

  • The optimal DBMS cursor for ambiguous COBOL cursors, i.e., cursors not defined as explicitly read only or updateable
  • The optimal DBMS cursor selection for both read-only and updateable COBOL cursors
  • The appropriate isolation level and lock concurrency settings

You can change the default behavior of OPTIMIZED to ANSI or UNOPTIMIZED using the OpenESQL Configuration Utility. However, when the BEHAVIOR directive is explicitly set in program code, project settings, or in a compiler directive file, the specified setting overrides the default setting.

You can override a default setting for BEHAVIOR on the program level without changing EXEC SQL statements by setting it explicitly at the start of your program code or on the command line when you compile.

For more information, see the BEHAVIOR topic and the demo application behavior listed in the topic Demonstration Applications.

Parent topic: OpenESQL
Related concepts
OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
BEHAVIOR


COBSQL

You can use COBSQL to access the SQL functions offered by the Oracle, Sybase or Informix 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, Sybase or Informix 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
  • Building COBSQL Applications
  • Building COBSQL Applications with Eclipse
  • Using the CP Preprocessor to Expand Copybooks
  • National Locale Support (NLS)
  • 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 SQL Preprocessor file, build configuration or project property page automatically adds a read-only entry to the top of the preprocessors list in the Additional Preprocessors 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 Enterprise Developer Project Properties
Before compiling from within Enterprise Developer:
Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL > SQL Preprocessor. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the project settings or at the program level.

For Oracle Pro*COBOL, you can set the COBSQL preprocessor and compiler directives from the project's properties:

  1. Expand Micro Focus > Project Settings > COBOL > SQL Preprocessor.
  2. Check Use SQL Preprocessor.
  3. From the Preprocessor Type list, select Oracle Pro*COBOL(COBSQL).
  4. Under Setting choose a directive and specify its value under Value.
  5. Repeat the previous step to add additional directives.
  6. Click Apply, then click OK.
Note: Ensure that no conflicting preprocessor directives are set in Additional Directives.
In your Enterprise Developer 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:

For Oracle Pro*COBOL only, you can set the COBSQL preprocessor and compiler directives from the file properties:

  1. Open your file properties and expand COBOL > SQL Preprocessor.
  2. Check Enable file specific settings.
  3. Check Use SQL Preprocessor.
  4. Under Setting choose a directive and specify its value under Value.
  5. Repeat the previous step to add additional directives.
  6. Click Apply, then click OK.
Note: Ensure that no conflicting preprocessor directives are set in Additional Directives.
On the Command Line
Use this method when compiling from an Enterprise Developer 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
Setting Compiler Directives for COBOL
User Directives File
SOURCEFORMAT


Building COBSQL Applications

Restriction: This topic applies to Windows environments (local development) only.

It is beyond the scope of this document to list the database support modules that are required when shipping on a COBSQL application. It is assumed that the end-user machine already has all the required support modules installed and that it is correctly configured to communicate with the database server.

When linking COBSQL applications, use the import library csqlsupp.lib. This resolves the calls inserted by COBSQL to the COBSQL init and stop run modules. The calls are actually handled by the module csqlsupp.dll which needs to be shipped with the application. This general support module is required for both Oracle and Sybase applications.

Specify the library csqlsupp.lib.

If you split the application into a main exe and a number of sub DLLs, then you only need to link csqlsupp.lib into the modules that you have compiled with the COBSQL directives CSTART or CSTOP.

If you compile all programs with CSTART or CSTOP, then you must link csqlsupp.lib into all the modules. Linking csqlsupp.lib to each module causes each module to be slightly larger than required. Only one version of csqlsupp.dll is loaded when the application runs.

If you compile the main program only with CSTART and CSTOP, then you need to link in the library csqlsupp.lib with the main program only. Any program that you compile with either the CSTART or the CSTOP COBSQL directive, you then need to link csqlsupp.lib with the module for that program.

Parent topic: COBSQL


Building COBSQL Applications with Eclipse

Attention: The following applies to COBSQL applications you develop on a local UNIX machine, or when, from a Windows machine, you develop remote projects on a UNIX machine.

If you are working with a COBSQL/Oracle application, you need to change your project build settings. In your local Eclipse IDE, once you have created a project containing the Pro*COBOL application, you need to update the project properties as follows:

  1. In the Team Developer perspective, select your project in the Application Explorer view.
  2. Click Project > Properties.
  3. In the Properties dialog, expand Micro Focus and click Build Configurations.
  4. Click Link.
  5. Expand Additional Link Directives.
  6. In the text box, type -e program-name.
  7. Click OK.
Parent topic: COBSQL
Related information
Setting Compiler Directives for COBOL


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\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) 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


National Locale Support (NLS)

This applies to Windows environments (local development) only. COBSQL error messages can be displayed in different languages depending on the setting of the LANG environment variable.

Most database clients include some NLS capability but their requirements for the setting of the LANG environment variable differ from those of this COBOL system. We recommend, therefore, that you use the alternative environment variable, COBLANG, which only affects this COBOL system, allowing the LANG environment variable to be used by the database client.

You can set COBLANG to one of the following values:
01 | US English
05 | Great Britain English
20 | Japanese (Shift-JIS)

Any other value triggers the default NLS locale.

Note: COBSQL does not translate any error messages produced by the database precompilers.
Parent topic: COBSQL


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. For PC protocols, try mounting a network drive or sending messages.

  • 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. Set up a Windows project. 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
Related concepts
Specific Troubleshooting Advice


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\PROxx\pcbcfg.cfg (Windows) or $ORACLE_HOME/precomp/admin/pcbcfg.cfg (UNIX) where:

    xx (applies to Windows environments only) | is the Pro*Cobol version (for example, for Oracle 8.0 this is PRO80)
    $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 the bottom of the COBOL listing.
  • Oracle 8 (and later) Directives for COBSQL
  • Migration and Development
  • Oracle 8 and Micro Focus COBOL
Parent topic: Troubleshooting


Oracle 8 (and later) Directives for COBSQL

To use COBSQL with Oracle 8 and later, you should use the following directives:

Directive | Description
CBL2ORA8 C28 (applies to Windows environments only) | This puts calls into the Oracle 8 specific support modules ora8prot and ora8lib. Both of these modules are built into csqlsupp.dll.
COBSQLTYPE CSQLT | EXEC SQL preprocessor. Use the options ORACLE8 and ORA8 to use Pro*COBOL 8.x or later with COBSQL.
Parent topic: Oracle Considerations


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:

Windows:
COBOL -k PROG P(HTMLPP) PREPROCESS(cobsql) CSQLT=ORACLE8
UNIX:
cob -k PROG.pco -C "p(htmlpp) preprocess(cobsql)
             csqlt==oracle8 endp"

whereas this line does not:

Windows:
COBOL -k PROG PREPROCESS(cobsql) CSQLT=ORACLE8 P(HTMLPP)
UNIX:
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:

UNIX:
  • 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
Windows:
  • In the Sybase-supplied copybooks cobpub.cbl and sybhesql.cbl, change all COMP data items to COMP-5.

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 Windows NT client was causing problems and the locales.dat file contained the following setting for Windows NT:

    [NT]
locale = default, us_english, iso_1
locale = enu, us_english, iso_1
locale = fra, french, iso_1
locale = deu, german, iso_1

    then the LANG setting for English would be:

    LANG=enu

    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. This can be set within the environment variable section of a project and enables different projects to connect to different Sybase servers (applies to Windows environments only).
  • 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

Restriction: This topic applies to UNIX environments only.
  • 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

  • OpenESQL Configuration Utility
  • OpenESQL Assistant
  • JDBC
Parent topic: Database Access


OpenESQL Configuration Utility

This topic applies to Windows environments only.

  • To start the OpenESQL Configuration utility
  • To set a default for SQL(BEHAVIOR)
Parent topic: How to


To start the OpenESQL Configuration utility

This topic applies to Windows environments only.

In standalone mode:
Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Configuration > OpenESQL Configuration Utility.
Windows 8.1
  • From the Windows Start screen, click the OpenESQL Configuration Utility tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > OpenESQL Configuration Utility.
From Eclipse:
  • From your Windows desktop, click Run > Tools > Configuration > OpenESQL Configuration Utility.
Parent topic: OpenESQL Configuration Utility
Related concepts
OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
esqlconfig command


To set a default for SQL(BEHAVIOR)

This topic applies to Windows environments only.

  1. Start the OpenESQL Configuration utility.
  2. Select an option.
    Tip: Click Explain next to an option for further details on that option.
  3. Click Save.
Parent topic: OpenESQL Configuration Utility
Related concepts
OpenESQL Configuration Utility for Default SQL Cursor Behavior
Optimize for performance and mainframe compatibility
ANSI compliance
No change in default behavior and no optimization
Issue a warning at compile time
Issue an error at compile time
COBOL Program Migration Support
Related tasks
To start the OpenESQL Configuration utility
Related reference
BEHAVIOR


OpenESQL Assistant

  • To add a column to a query
  • To close a query
  • To close the OpenESQL Assistant
  • To connect to a data source
  • To connect to a different data source
  • To create a complete program in a temporary file
  • To create a table join
  • To create a temporary file
  • To create an SQL query
  • To create a TSQL stored procedure query
  • To disconnect from a data source
  • To display column details
  • To embed an SQL query into a program
  • To enable PL/I SQL query generation
  • To generate a DELETE statement
  • To generate a SELECT (cursor) statement
  • To generate a SELECT (singleton) statement
  • To generate a SELECT DISTINCT (cursor) statement
  • To generate a SELECT DISTINCT (singleton) statement
  • To generate an INSERT statement
  • To generate an UPDATE statement
  • To generate and embed auxiliary code
  • To refresh the list of data sources
  • To remove a table from a SELECT query
  • To run a query
  • To set OpenESQL Assistant options
  • To sort returned data (an ORDER BY clause)
  • To specify search criteria (a WHERE clause)
  • To start the OpenESQL Assistant
  • To view a temporary file
  • To view data source properties
Parent topic: How to


To add a column to a query

  1. In the OpenESQL Assistant, identify a column in the tree view that belongs to a table you have selected for your query.
  2. Check the box next to the column to add it to the query.
Parent topic: OpenESQL Assistant
Related concepts
Selecting Columns
OpenESQL Assistant
Related tasks
To create an SQL query


To close a query

  1. In the OpenESQL Assistant, check the box next to the table name upon which you have built your query.
  2. Click Yes at the prompt.
Note:

If you have specified more than one table in your query, repeat the procedure for each table.

Parent topic: OpenESQL Assistant
Related concepts
Close a Query
OpenESQL Assistant
Setting OpenESQL Assistant Options
OpenESQL Assistant
Related tasks
To create an SQL query
Related reference
OpenESQL Assistant - Main Window


To close the OpenESQL Assistant

  • From the OpenESQL Assistant, click Close Close.
Parent topic: OpenESQL Assistant


To connect to a data source

  1. Start the OpenESQL Assistant.
  2. From the tree view, check the box next to a data source.
Note:

You might be prompted to supply one or more of the following:

  • A user ID
  • A password
  • A database name
Parent topic: OpenESQL Assistant
Related concepts
Connecting to a data source
OpenESQL Assistant
Setting OpenESQL Assistant Options
OpenESQL Assistant
Related tasks
To start the OpenESQL Assistant
To connect to a different data source
Related reference
OpenESQL Assistant - Main Window


To connect to a different data source

  1. On the OpenESQL Assistant, click File > New query. The OpenESQL Assistant discards the current query.
  2. Check the box next to a data source on the tree view.
Parent topic: OpenESQL Assistant
Related concepts
Connecting to a data source
OpenESQL Assistant
Setting OpenESQL Assistant Options
OpenESQL Assistant
Related tasks
To connect to a data source
To view data source properties
Related reference
OpenESQL Assistant - Main Window


To create a complete program in a temporary file

  1. In the OpenESQL Assistant, connect to a data source.
  2. Click the Auxiliary Code tab.
  3. Click Generic SQL or PL/I Program.
  4. Click Add query to temporary file Insert query into program.
  5. Create additional queries and/or auxiliary code as required for the program, and add each one to the temporary file after generating the code.
    Note: OpenESQL Assistant adds generated code to the end of the temporary file each time you click Add query to temporary file Insert query into program.
  6. Edit the temporary file as necessary to ensure that each query and set of auxiliary code appears in its proper location, and that all program code is complete.
  7. Click Save temporary file Insert query into program.
    Note: The default filename is the table name followed by a .cbl or .pli extension depending on the Output language specified in the OpenESQL Options.
  8. Add the saved file to your Eclipse project (optional).
Parent topic: OpenESQL Assistant
Related concepts
Creating Temporary Files
Embedding SQL into a program
Related tasks
To create a temporary file
To view a temporary file


To create a table join

  1. In the OpenESQL Assistant, create a SELECT query.
  2. In the tree view, identify a table that is not part of the current query and that you would like to join to the table that is part of the current query.
  3. Check the box next to the table name.
  4. Review the generated code.
  5. Do one of the following:
    • If the generated code is acceptable, click Yes. OpenESQL Assistant adds the generated code to the query, joining the table. You can now add columns from the joined table to the query.
    • If the generated code is not acceptable, click No. OpenESQL Assistant does not add the generated code to the query; however it does add the table to the query. You should add code for the join from the Search Criteria tab.
    • If OpenESQL Assistant cannot determine how to join the table to the query, it does not generate any code. Instead, either click Yes to add the table to the query or No to omit the table from the query. If you opt to add the table anyway you can specify the join from the Search Criteria tab.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Related tasks
To create an SQL query


To create a temporary file

  1. In the OpenESQL Assistant, create a query.
  2. To copy the query to a temporary file, click Add query to temporary file Insert query into program.
  3. Optionally create additional queries and auxiliary code and add these to the temporary file in the same manner.
    Note: OpenESQL Assistant adds generated code to the end of the temporary file each time you click Add query to temporary file Insert query into program.
  4. Optionally edit the code in the temporary file as needed.
  5. Click Save temporary file Insert query into program.
Parent topic: OpenESQL Assistant
Related concepts
Creating Temporary Files
Embedding SQL into a program
Related tasks
To create a complete program in a temporary file
To view a temporary file


To create an SQL query

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. On the tree view, check the box next to a table name.
  4. On the Select Type of Query to Create dialog box, click a query type from the list.
  5. Check Generate query with FOR UPDATE (SELECT or SELECT DISTINCT queries only) to generate a FOR UPDATE clause in the query. Optional.
  6. Check Generate query with WHERE CURRENT OF (UPDATE or DELETE queries only) to generate a WITH CURRENT OF clause in the query. Optional.
  7. Click OK. The query code appears on the Query tab.
  8. Add tables, columns, search criteria, and auxiliary code to the query as necessary.
Parent topic: OpenESQL Assistant
Related concepts
Select Type of Query to Create dialog box
OpenESQL Assistant
Building Queries
Setting OpenESQL Assistant Options
Stored Procedures
OpenESQL Assistant
Building Queries
Generating initial query code
Related tasks
To add a column to a query
To close a query
To create a table join
To start the OpenESQL Assistant
To remove a table from a SELECT query


To create a TSQL stored procedure query

  1. Start the OpenESQL Assistant.
  2. Select Tools > Options and make sure Type Stored Procedure is set to TSQL.
  3. Connect to a Microsoft SQL Server data source.
  4. Check the box next to a table name.
  5. Click a query type from the list.
  6. Check Generate Query as a TSQL Stored Procedure.
  7. In the SP name field, type a name for the stored procedure. Alternatively, accept the default value.
  8. Click OK.
  9. Continue to build your query.
Parent topic: OpenESQL Assistant
Related concepts
Generating a TSQL Stored Procedure Query
Select Type of Query to Create dialog box
OpenESQL Assistant
Building Queries
Setting OpenESQL Assistant Options
Stored Procedures


To disconnect from a data source

  • In the OpenESQL Assistant, click File > New query, or uncheck the box next to the data source name.
Parent topic: OpenESQL Assistant
Related concepts
Disconnect from a Data Source
OpenESQL Assistant
Setting OpenESQL Assistant Options
Related reference
OpenESQL Assistant - Main Window


To display column details

  1. In the OpenESQL Assistant, create an SQL query.
  2. Click the Details tab.
Parent topic: OpenESQL Assistant
Related concepts
Display Column Details


To embed an SQL query into a program

  1. In the Eclipse IDE, open the project that contains the program into which you want to embed the SQL.
  2. Open the appropriate program in the program editor.
  3. In the OpenESQL Assistant, create an SQL query.
  4. Click Add query to temporary file Insert query into program.
  5. In the program editor, place your cursor at the point in your program where you want the query to appear; then right-click and select Paste.
Parent topic: OpenESQL Assistant
Related concepts
Embedding a TSQL Stored Procedure into a Program
OpenESQL Assistant
Building Queries
OpenESQL Assistant
Setting OpenESQL Assistant Options
Embedding SQL into a program
Auxiliary Code
Embedding Auxiliary Code
Generating EXEC SQL Auxiliary Code
Related reference
Query tab


To enable PL/I SQL query generation

  1. In OpenESQL Assistant, click Tools > Options.
  2. Under the General heading in the right pane, use the drop-down list to change the value of the Output language field from COBOL to PLI; then click OK.
  3. Close the Options dialog box.
Note: When you set the Output language to PLI, this automatically changes the Mode value to ODBC because PLI is only supported in native applications.
Parent topic: OpenESQL Assistant


To generate a DELETE statement

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click DELETE, then click OK.
  5. Further define the query using the Search Criteria feature. Optional.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Generating initial query code
Related tasks
To specify search criteria (a WHERE clause)


To generate a SELECT (cursor) statement

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click SELECT (cursor), then click OK.
  5. Check the box next to each column you want to include in the SELECT statement.
  6. Further define the query using the Search Criteria and Sort features. Optional.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Generating initial query code
Related tasks
To specify search criteria (a WHERE clause)
To sort returned data (an ORDER BY clause)


To generate a SELECT (singleton) statement

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click SELECT (singleton), then click OK.
  5. Check the box next to each column you want to include in the SELECT statement.
  6. Further define the query using the Search Criteria feature. Optional.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Generating initial query code
Related tasks
To specify search criteria (a WHERE clause)
To sort returned data (an ORDER BY clause)


To generate a SELECT DISTINCT (cursor) statement

  1. Start the OpenESQL Assistant.
  2. Connect to the data source.
  3. Check the box next to a table name.
  4. Click SELECT DISTINCT (cursor), then click OK.
  5. Check the box next to each column you want to include in the SELECT statement.
  6. Further define the query using the Search Criteria and Sort features. Optional.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Related tasks
To specify search criteria (a WHERE clause)
To sort returned data (an ORDER BY clause)


To generate a SELECT DISTINCT (singleton) statement

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click SELECT DISTINCT (singleton), then click OK.
  5. Check the box next to each column you want to include in the SELECT statement.
  6. Further define the query using the Search Criteria feature. Optional.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Related tasks
To specify search criteria (a WHERE clause)
To sort returned data (an ORDER BY clause)


To generate an INSERT statement

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click INSERT, then click OK.
  5. Check the box next to each column you want to include in the INSERT statement.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Generating initial query code


To generate an UPDATE statement

  1. Start the OpenESQL Assistant.
  2. Connect to a data source.
  3. Check the box next to a table name.
  4. Click UPDATE, then click OK.
  5. Check the box next to each column you want to include in the UPDATE statement.
  6. Further define the query using the Search Criteria feature. Optional.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Generating initial query code
Related tasks
To specify search criteria (a WHERE clause)


To generate and embed auxiliary code

  1. Open the project that contains the program into which you want to embed the SQL.
  2. Open the appropriate program in the program editor.
  3. Place your cursor at the point in your program where you want the auxiliary code to appear.
  4. In the OpenESQL Assistant, click the Auxiliary Code tab.
  5. Click EXEC SQL.
  6. Click Add query to temporary file .
  7. Click View temporary file Insert query into program.
  8. Copy the code in the temporary file, and paste it into your program.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Auxiliary Code
Related reference
Auxiliary Code tab


To refresh the list of data sources

  • In the OpenESQL Assistant, click Create New Query.
Parent topic: OpenESQL Assistant


To remove a table from a SELECT query

  1. In the OpenESQL Assistant, uncheck the box next to a table name that has been specified in your query.
  2. Click Yes at the prompt.
Note: If you remove the only table specified in a query, this is equivalent to closing the query.
Parent topic: OpenESQL Assistant
Related concepts
Remove a Table from a SELECT Query
OpenESQL Assistant
Related tasks
To create an SQL query


To run a query

  1. In the OpenESQL Assistant, create an SQL query.
  2. Click Run Query Create New Query.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Related reference
OpenESQL Assistant - Main Window


To set OpenESQL Assistant options

  1. From Enterprise Developer, click Windows > Preferences; then expand Micro Focus > Database and click OpenESQL Assistant.
  2. Set the options according to your programming needs.
  3. Click OK.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Select Type of Query to Create dialog box
Building Queries
Stored Procedures
OpenESQL Assistant
Related reference
OpenESQL Assistant - Main Window
OpenESQL Assistant - Options


To sort returned data (an ORDER BY clause)

  1. In the OpenESQL Assistant, click the Sort tab.
  2. In the Columns in SELECT list, click a column you want to sort. This list box displays the column name of every column selected for the query.
  3. Do one of the following:
    • Click Asc to sort the column in ascending order.
    • Click Desc to sort the column in descending order.
  4. If you want to generate the query using a number to represent the column name, check Use integers for column names. The column names are still displayed in the Columns in ORDER BY field, but the integer value of the column is generated for the query.
  5. Insert the sort (ORDER BY clause) into your code by clicking the right-pointing arrow right-pointing arrow.
Note:
  • Code you place into the right-hand pane also appears automatically in the generated query.
  • To remove a sort, click the line of code you want to remove in the right-hand pane, then click the left-pointing arrow right-pointing arrow. This places the sort back into the appropriate fields on the left side of the tab, enabling you to edit it. Moving sorts from the right-hand to the left-hand pane also removes the associated COBOL code from the automatically generated query.
Parent topic: OpenESQL Assistant
Related concepts
Specifying the Order in which Data is Retrieved
OpenESQL Assistant
OpenESQL Assistant
Related tasks
To generate a SELECT (cursor) statement
To generate a SELECT (singleton) statement
To generate a SELECT DISTINCT (cursor) statement
To generate a SELECT DISTINCT (singleton) statement
Related reference
Sort tab


To specify search criteria (a WHERE clause)

  1. In the OpenESQL Assistant, click the Search Criteria tab.
  2. From the Column drop-down list, click a column name.
  3. From the Conditional Operator drop-down list, click a conditional operator.
  4. From the Target Type drop-down list, click a target type.
  5. Do one of the following:
    • If you have selected a target type of Special Register, type a value for your special register into the Target Value field.
    • If you have selected a target type of Column Name, click a column name from the Target Value drop-down list.
    • If you have selected a target type of Literal:
      1. Click Edit.
      2. Type the literal value you want to use.
      3. Click OK.
    • If you have selected a target type of Host Variable, the target value is set for you. Proceed to step 6.
  6. Insert the search criteria (WHERE clause) into your code by clicking the right-pointing arrow right-pointing arrow.
  7. To add a subsequent set of criteria, click either AND or OR and repeat this procedure. Optional.
Note:
  • Code you place into the right-hand pane also appears automatically in the generated query.
  • To remove search criteria, click the line of code you want to remove in the right-hand pane, then click the left-pointing arrow right-pointing arrow. This places the criteria back into the appropriate fields on the left side of the tab, enabling you to edit it. Moving search criteria from the right-hand to the left-hand pane also removes the associated COBOL code from the automatically generated query.
Parent topic: OpenESQL Assistant
Related concepts
Specifying Search Criteria
OpenESQL Assistant
Specifying Search Criteria
Building Queries
OpenESQL Assistant
Related tasks
To generate a DELETE statement
To generate a SELECT (cursor) statement
To generate a SELECT (singleton) statement
To generate a SELECT DISTINCT (cursor) statement
To generate a SELECT DISTINCT (singleton) statement
To generate an UPDATE statement
Related reference
Search Criteria tab
Literal Value dialog box


To start the OpenESQL Assistant

  • In Eclipse, click Run > Tools > Data Tools > OpenESQL Assistant.
Note: If prompted, type your user name and password; then click OK.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
OpenESQL Assistant
Setting OpenESQL Assistant Options
Building Queries
Related tasks
To connect to a data source
To create an SQL query
Related reference
OpenESQL Assistant - Main Window


To view a temporary file

  • In the OpenESQL Assistant, click View temporary file Insert query into program.

    This shows you the contents of the current temporary file.

Parent topic: OpenESQL Assistant
Related concepts
Creating Temporary Files
Related tasks
To create a complete program in a temporary file
To create a temporary file


To view data source properties

  • In the OpenESQL Assistant, check a data source in the tree view.
  • Right-click the data source; then click Data Source Properties on the popup menu.
Parent topic: OpenESQL Assistant
Related concepts
Data Source Properties dialog box
OpenESQL Assistant
Related tasks
To connect to a different data source


JDBC

  • To create a JVM COBOL project for JDBC
  • To install and configure Simple-JNDI
  • To create a JNDI DataSource object
  • To add JDBC resources to the JVM Build Path
  • To create a user library for JDBC resources
  • To import a user library
  • To export a user library
Parent topic: How to


To create a JVM COBOL project for JDBC

  1. From the Eclipse IDE, create a COBOL JVM project.
  2. Right-click your project and select Properties from the context menu.
  3. Expand Micro Focus > SQL Preprocessor.
  4. Check Use SQL Preprocessor.
  5. From the Preprocessor Type drop-down list, select OpenESQL.
  6. Scroll down the Directives list and click the Value field that corresponds to DBMAN.
  7. From the drop-down list, select JDBC.
  8. Click OK.
Note: You can also set the DBMAN compiler directive to JDBC outside of the Eclipse IDE using either of these two methods:
  • Set the directive as a command-line option when you compile from the command line using the following syntax:

    SQL(DBMAN=JDBC) (Windows)

    SQL(DBMAN==JDBC) (UNIX)

  • Embed the directive at the start of a program:

    $SET SQL(DBMAN=JDBC)

Parent topic: JDBC
Related concepts
JDBC Process
JDBC Resources
Related reference
CHECK


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 blackslash (Windows) or or single slash (UNIX) characters in place of single characters. For example:

      Windows: For c:\jdbcrsc, specify c:\\jdbcrsc.

      UNIX: For c:/jdbcrsc, specify c://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
Additional Software Requirements on Windows
Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components
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, c:\jdbcrsc\DataSources\MSSQL.properties (Windows) or c:/jdbcrsc/DataSources/MSSQL.properties (UNIX).

  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


To add JDBC resources to the JVM Build Path

Important: Before performing these steps, ensure that you have reviewed the information in the JDBC Resources topic.
  1. From the Application Explorer view, right-click the project name; then select Properties.
  2. Expand Micro Focus; then click JVM Build Path.
  3. Select the Libraries tab.
  4. Click Add External JARs.
  5. Add the following JAR files:
    JDBC drivers
    Add the driver file or files required for your database. See JDBC Resources for more information.
    JNDI library
    If using Simple-JNDI:
    • Add simple-jndi-version.jar
    • If you have compressed your jndi.properties file into an archive, add the archive file.

    If using the JNDI implementation on your application server, add any appropriate JNDI .jar files.

    This adds the name and path of each selected external JAR file to the JARs and class folders list. A jar-shaped icon, External JAR file, appears next to each external JAR file entry on the list.

    Note: As an alternative, you can add these same JAR files to a user library, and then add the user library to the JVM Build Path. See To create a user library for JDBC resources for more information.
  6. If using Simple-JNDI and you have elected not to compress your jndi.properties file, click Add External Class Path, and add the path to the jndi.properties file.
Parent topic: JDBC
Related concepts
JDBC Process
JDBC Resources
Related tasks
To create a user library for JDBC resources


To create a user library for JDBC resources

  1. From the Application Explorer view, right-click the project name; then select Properties.
  2. Expand Micro Focus; then click JVM Build Path.
  3. Select the Libraries tab.
  4. Click Add Library.
  5. Select User Library; then click Next.
  6. Click User Libraries.
  7. Click New and type in a name for the library. For example, JDBC Resources Library.
  8. Select the Micro Focus template; then click Next.
  9. Click Add External JARs, and add the appropriate JAR files. See To add JDBC resources to the JVM Build Path for details.
  10. When you have finished adding the required files, click OK.
  11. Check the box next to the new library; then click Finish.
Note: You can export and import this user library from one Eclipse workspace to another.
Parent topic: JDBC
Related concepts
JDBC Resources
Related tasks
To add JDBC resources to the JVM Build Path
To import a user library
To export a user library


To import a user library

  1. In Eclipse, open an existing workspace or create a new workspace; then add a new COBOL JVM project.
  2. Right-click the project name and select Properties.
  3. Under Micro Focus, click JVM Build Path; then click the Libraries tab.
  4. Click Add Library.
  5. Select User Library; then click Next.
  6. Click User Libraries.
  7. Click Import.
  8. Click Browse to locate a previously exported library; then click Open. Exported library files have a file extension of .userlibraries.
  9. Check the box next to the library, then click OK.
  10. Click Finish.
Parent topic: JDBC
Related concepts
JDBC Resources
Related tasks
To create a user library for JDBC resources
To export a user library


To export a user library

  1. In Eclipse, open an existing workspace that contains the user library you want to export.
  2. Right-click the project name and select Properties.
  3. Under Micro Focus, click JVM Build Path; then click the Libraries tab.
  4. Select User Library you want to export; then click Edit.
  5. Click User Libraries.
  6. Click Export.
  7. Click Browse to select a directory for the exported library file
  8. Type a name for the exported library; then click OK. Eclipse automatically adds the file extension .userlibraries.
  9. Click OK to clear the confirmation message.
  10. Click OK.
Parent topic: JDBC
Related concepts
JDBC Resources
Related tasks
To create a user library for JDBC resources
To import a user library


Reference

  • OpenESQL
  • 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.
  • MDCLGEN command-line tool
    Describes how to use the MDCLGEN tool for generating copybooks and include files as an alternative to generating them from the OpenESQL Assistant.
  • User Interface Reference
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.

  • ALLOCATE CURSOR
    Defines a cursor and associates it with a result set locator variable.
  • ASSOCIATE LOCATORS
    Gets the result set locator value for each result set returned by a SQL CLR stored procedure.
  • 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 DIAGNOSTICS
    Enables you to get diagnostic information for the last OpenESQL statement executed.
  • 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


ALLOCATE CURSOR

Defines a cursor and associates it with a result set locator variable.
Restriction: This topic applies to Windows environments (local development) only.

Syntax:

>>-EXEC SQL--ALLOCATE cursor_name FOR RESULT SET :rs_locator_variable->
>-----END-EXEC-----<>

Parameters:

cursor_name | A previously declared and opened cursor.
:rs_locator_variable | A result set locator host variable that has been declared in the application program.

Comments:

You can create SQL CLR stored procedures using our Enterprise Developer for Visual Studio product.

Supported for client applications that call SQL CLR stored procedures that return result sets and are compiled with DBMAN=ODBC and DIALECT=MAINFRAME.

Example:

  working-storage section.
       exec sql include sqlca end-exec.
       01  mfsqlmessagetext    pic x(200).
       01  hv-country  pic n(15) national.
       01  CustomerID  pic n(5) national.
       01  Company     pic n(40) national.
       01  City        pic n(15) national.
       01  CustomerID2 pic n(5) national.
       01  Company2    pic n(40) national.
       01  City2       pic n(15) national.
       01  rsl         sql type result-set-locator varying.
       01  rs2         sql type result-set-locator varying.
       01  rs3         sql type result-set-locator varying.
       procedure division.
           exec sql connect to Northwind end-exec

           move N"UK" to hv-country

           *> Test DB2 result set locators
           *> This proc opens 3 cursors. closes 2 and re-opens on
           *> So should return 2 result sets
           exec sql call TestProc1(:hv-country) end-exec

           exec sql
               associate locators (:rsl, :rs2, :rs3)
               with procedure TestProc1
           end-exec

           exec sql
               allocate c1 cursor
               for result set :rsl
           end-exec
           if sqlcode not = 0
               display "Open 1st locator failed"
           end-if

           exec sql
               allocate c2 cursor
               for result set :rs2
           end-exec
           if sqlcode not = 0
               display "Open 2nd locator failed"
           end-if

           exec sql
               allocate c3 cursor
               for result set :rs3
           end-exec
           if sqlcode = 0
               display "FAIL: Open 3rd locator succeeded"
           end-if
Parent topic: Embedded SQL Statements


ASSOCIATE LOCATORS

Gets the result set locator value for each result set returned by a SQL CLR stored procedure.
Restriction: This topic applies to Windows environments (local development) only.

Syntax:

              .-RESULT SET-.
>>-ASSOCIATE--+------------+--+-LOCATORS--+---------------------->
                              '-LOCATOR--'

      .-,-------------------.
      V                     |
>--(----rs-locator-variable-+--)-------------------------------->

>--WITH PROCEDURE--+-procedure-name-+--------------------------><
                   '-hvar-----------'

Parameter:

rs_locator_variable | A result set locator host variable that has been declared in the application program.
procedure-name | The name of a SQL CLR stored procedure.
hvar | A host variable that contains the name of a SQL CLR stored procedure.

Comments:

You can create SQL CLR stored procedures using our Enterprise Developer for Visual Studio product.

Supported for client applications that call SQL CLR stored procedures that return result sets and are compiled with DBMAN=ODBC and DIALECT=MAINFRAME.

Example:

  working-storage section.
       exec sql include sqlca end-exec.
       01  mfsqlmessagetext    pic x(200).
       01  hv-country  pic n(15) national.
       01  CustomerID  pic n(5) national.
       01  Company     pic n(40) national.
       01  City        pic n(15) national.
       01  CustomerID2 pic n(5) national.
       01  Company2    pic n(40) national.
       01  City2       pic n(15) national.
       01  rsl         sql type result-set-locator varying.
       01  rs2         sql type result-set-locator varying.
       01  rs3         sql type result-set-locator varying.
       procedure division.
           exec sql connect to Northwind end-exec

           move N"UK" to hv-country

           *> Test DB2 result set locators
           *> This proc opens 3 cursors. closes 2 and re-opens on
           *> So should return 2 result sets
           exec sql call TestProc1(:hv-country) end-exec

           exec sql
               associate locators (:rsl, :rs2, :rs3)
               with procedure TestProc1
           end-exec

           exec sql
               allocate c1 cursor
               for result set :rsl
           end-exec
           if sqlcode not = 0
               display "Open 1st locator failed"
           end-if

           exec sql
               allocate c2 cursor
               for result set :rs2
           end-exec
           if sqlcode not = 0
               display "Open 2nd locator failed"
           end-if

           exec sql
               allocate c3 cursor
               for result set :rs3
           end-exec
           if sqlcode = 0
               display "FAIL: Open 3rd locator succeeded"
           end-if
Parent topic: Embedded SQL Statements


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

2 HCOSS does not support keyword parameters.

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
DB2 Stored Procedures for PL/I
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. or the HCOSS Manage Connections tool.

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-----+
                        +-DATASET-+      +-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 not compiled with DIALECT=MAINFRAME
  • 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.
  • DATASET enables a cursor that can be used with any BEHAVIOR setting. DATASET is required for applications that use the underlying .NET objects for interoperability with other .NET languages, and is available only for the OpenESQL Managed Runtime.
  • 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 DIAGNOSTICS

Enables you to get diagnostic information for the last OpenESQL statement executed.
Restriction: This topic applies to Windows environments (local development) only.

Syntax:

>>---EXEC SQL---GET-.---------.-DIAGNOSTICS-->
                    +-CURRENT-+

        +-----------,--------------+
        V                          |
>-----.-.- :hvar1 = --.-ROW_COUNT--.->
      |               |            |
      |               +-NUMBER-----+
      |
      |                       +-----------------,------------------+
      |                       V                                    |
      +--CONDITION--condition-.-:hvar2 = --.-DB2_RETURNED_SQLCODE--.->
                                           |                       |
                                           +---RETURNED_SQLCODE----+
                                           |                       |
                                           +---RETURNED_SQLSTATE---+
                                           |                       |
                                           +---MESSAGE_TEXT--------+
                                           |                       |
                                           +---DB2_ROW_NUMER-------+
                                           |                       |
                                           +---ROW_NUMBER----------+
                                           |                       |
                                           +---COLUMN_NUMBER-------+
>---END-EXEC---><

Parameters:

hvar1 | A host variable to receive a statement-level diagnostic information item.
condition | A literal or host variable that specifies the diagnostic record from which diagnostic information is retrieved.
hvar2 | A host variable to receive a statement-level diagnostic information item
ROW_COUNT | The number of rows affected by the previous statement. For INSERT, UPDATE, or DELETE, this is the number of rows inserted, updated, or deleted, respectively. For FETCH, it is the number of rows returned to the application. This must be retrieved into a numeric host variable, usually a 32-bit integer.
NUMBER | The number of diagnostic records available to be queried in subsequent GET DIAGNOSTICS statements. This must be retrieved into a numeric host variable, usually a 32-bit integer.
DB2_RETURNED_SQLCODE | The SQLCODE value associated with the diagnostic record. This must be retrieved into a numeric host variable, usually a 32-bit integer.
RETURNED_SQLCODE | The SQLCODE value associated with the diagnostic record, which is the same as DB@_RETURNED_SQLCODE. This must be retrieved into a numeric host variable, usually a 32-bit integer.
RETURNED_SQLSTATE | The SQLSTATE value associated with the diagnostic record. This must be retrieved into a PIC X(n) host variable, where n can be any size, but is usually 5.
MESSAGE_TEXT | The message text associated with the diagnostic record. This must be retrieved into a PIC X(n) host variable, where n can be any size.
DB2_ROW_NUMBER | The row number associated with the diagnostic record. This is useful with multi-row operations such as insert statements using parameter arrays and block fetches.
ROW_NUMBER | The same as DB2_ROW_NUMBER.
COLUMN_NUMBER | The column or parameter number associated with the diagnostic record. This is useful in determining which host variable(s), string truncation, and other warnings apply to.

Comments:

GET DIAGNOSTICS is supported on Windows platforms only, and for ODBC only.

When an OpenESQL statement is executed, one or more diagnostic records are generated to record diagnostic information about the execution. The SQLCA can return information from only one diagnostic record. You can use GET DIAGNOSTICS to both determine if more than one record was generated, and then to query individual records.

In most cases when a statement executes successfully, only one record is generated. A FETCH statement can potentially generate as many as one record per retrieved column if there are truncation warnings or null values returned with no indicator variable. If a SQL Server stored procedure executes TSQL RAISEERROR statements and COBOL DISPLAY statements in CLR stored procedures, then each of these generates a diagnostic record for the caller.

GET DIAGNOSTICS has no effect on the SQLCA or SQLSTATE, SQLCODE declared by an application.

No diagnostic information is available for execution of GET DIAGNOSTICS statements.

Example:

The following code displays all the diagnostic records generated after a statement has been executed:
       01  condNum             pic s9(8) comp-5.
       01  retSqlCode          pic s9(8) comp-5.
       01  retMessagetext      pic x(120).
       01  retSqlState         pic x(5).

       exec sql get diagnostics :condCount = number end-exec
       perform varying condNum from 1 by 1 until condNum > condCount
           exec sql
               get diagnostics condition :condNum
                   :retSqlState = RETURNED_SQLSTATE,
                   :retSqlCode = DB2_RETURNED_SQLCODE,
                   :retMessageText = MESSAGE_TEXT
           end-exec
           display retSqlCode  ' ' retsqlState ' ' retMessageText
       end-perform
Parent topic: Embedded SQL Statements


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, you must specify the BEHAVIOR directive with the RO_CURSOR=FF primitive directive when compiling SQL Server applications that contain save points.

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
DIALECT=MAINFRAME  SQLCODE = -811 SQLSTATE = 21000 SQLWARN4 = W
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

Note: SQL compiler directives for HCOSS are located under the SQL Compiler Directive Options - HCOSS topic in the HCO for SQL Server (HCOSS) section of this documentation.
  • ACCESS
    Enables deployment of application code and SQL by updating the SQL Server database at compile time.
  • 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.
  • 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.
  • 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 if the application is running under Enterprise Server. 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 the ODBC control panel (Windows) or odbc.ini (UNIX) 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.
  • SPDISPLAY
    Determines where COBOL DISPLAY information can be accessed.
  • 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
DBMAN Directive Settings
Related reference
SQL Compiler Directive Options - HCOSS


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 and Windows platforms 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.

Parent topic: SQL Compiler Directive Options
Related concepts
SQL Code Generation Options
Scope - OpenESQL SQL Compiler Directive Options
Building applications
SQL Code Generation Options
Related reference
QUALIFIER
PASS
DB


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
SQLUTB Utility - Loading and Unloading SQL Tables
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 Enterprise Developer 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 Enterprise Developer.
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
BEHAVIOR
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 (applies to UNIX environments only).
  • 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 | CICS | JCL} [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
CICS Sets all of the following:
  • Enables OpenESQL to work as it does on the mainframe, optimizing ambiguous cursor declarations
  • Enhances the access speed
  • Automatically sets the TRANSACTION directive to GLOBAL
JCL Sets all of the following:
  • Enables OpenESQL to work as it does on the mainframe, optimizing ambiguous cursor declarations
  • Enhances the access speed
  • Checks for the following statements that are not compatible with JCL applications:
    • CONNECT
    • DISCONNECT
    • SET CONNECT
  • Reports an error for each incompatible statement found
  • Automatically sets the TRANSACTION directive to LOCAL
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, JCL | ANSI | CICS
AUTOFETCH | ON | OFF | ON
DEF_CURSOR | RO | UPD | RO
RO_CURSOR | FORWARD or IC_FH | FORWARD or IC_FH | FORWARD or IC_FH
PF_RO_CURSOR | 1 | 1 | 1
IC_FH_ISOLATION | UR | UR | UR
UPD_CURSOR | DYNAMIC | DYNAMIC | DYNAMIC
PF_UPD_CURSOR | 8 | 8 | 8
UPD_CONCURRENCY | LOCK | LOCK | LOCK
ISOLATION | CR | CR | CR
Table 2. Default Behavior Primitive Table for Other DBMSs:
BEHAVIOR = Primitive Default Values | OPTIMIZED, MAINFRAME, JCL | ANSI | CICS
AUTOFETCH | ON | OFF | ON
DEF_CURSOR | RO | UPD | RO
RO_CURSOR | FORWARD | FORWARD | FORWARD
PF_RO_CURSOR | 8 | 8 | 8
UPD_CURSOR | KEYSET | KEYSET | KEYSET
PF_UPD_CURSOR | 8 | 8 | 8
UPD_CONCURRENCY | LOCK | LOCK | LOCK
ISOLATION | CR | 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
OpenESQL Configuration Utility for Default SQL Cursor Behavior
Optimize for performance and mainframe compatibility
ANSI compliance
No change in default behavior and no optimization
Issue a warning at compile time
Issue an error at compile time
COBOL Program Migration Support
Embedded SQL Cursors in Older Applications
Managing Transactions
Scope - OpenESQL SQL Compiler Directive Options
HCO for SQL Server Compiler Directive Options for PL/I
Related tasks
To set a default for SQL(BEHAVIOR)
Related reference
PREFETCH
esqlconfig command
DBMAN Directive Settings
SET CONCURRENCY
SET SCROLLOPTION
DESCRIBEDTCHAR
SAVEPOINT, SAVE TRANSACTION, RELEASE [TO] SAVEPOINT
CLOSE_ON_COMMIT
AUTOCOMMIT


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
Embedded SQL Cursors in Older Applications
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


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 and Windows platforms 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.

Parent topic: SQL Compiler Directive Options
Related concepts
SQL Code Generation Options
Scope - OpenESQL SQL Compiler Directive Options
Building applications
Manage Packages and Plans Tool
Binding Applications
Related reference
DSN command
Bind Script Commands
QUALIFIER


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
HCO for SQL Server Compiler Directive Options for PL/I
Related tasks
To create a JVM COBOL project for JDBC
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
HCO for SQL Server Compiler Directive Options for PL/I
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
HCO for SQL Server Compiler Directive Options for PL/I
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 (applies to UNIX environments only).

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
NOT
Environment Variables (UNIX)


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
ACCESS


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
HCO for SQL Server Compiler Directive Options for PL/I
Related reference
DBMAN Directive Settings
DBMAN Directive Settings - HCOSS
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 Enterprise Developer 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 if the application is running under Enterprise Server. 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
HCO for SQL Server Compiler Directive Options for PL/I


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 (applies to UNIX environments only).

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
CONCAT
Environment Variables (UNIX)


ODBCTRACE

ODBCTRACE=USER enables you to control ODBC tracing via the ODBC control panel (Windows) or odbc.ini (UNIX) 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 on the ODBC control panel (Windows) or in odbc.ini (UNIX).

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 the control panel (Windows) or odbc.ini (UNIX). 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 Enterprise Developer 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
SPDISPLAY
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
ACCESS
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 Windows is either odbcrw32.dll or odbcrw64.dll. 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.

When compiling with the LITLINK compiler directive on Windows platforms only, specify NOPRE to prevent possible link errors. Because NOPRE stops the code generation that loads the OpenESQL module at run time, you must link your application with the appropriate OpenESQL import library, either odbcrw32.lib (located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib) or odbcrw64.lib (located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib64). To do this, add the relevant .lib file to the Link with libs field on the COBOL Link tab of your project properties, or specify it as a cbllink option when linking from the command line. Doing this ensures that the OpenESQL module is loaded at run time.

Parent topic: SQL Compiler Directive Options
Related concepts
Scope - OpenESQL SQL Compiler Directive Options
Related reference
LITLINK
cbllink


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


SPDISPLAY

Determines where COBOL DISPLAY information can be accessed.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]SPDISPLAY

Properties:

Default: NOSPDISPLAY

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - OpenESQL SQL Compiler Directive Options for more information.

Comments:

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.

DISPLAY output from stored procedures goes to SYSOUT for Enterprise Server .NET JCL jobs.

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
HCO for SQL Server Compiler Directive Options for PL/I
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 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 CICS or a Java application server, and its external SQL connection.

Checks for the following statements that are not compatible with CICS or 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.
When BEHAVIOR=JCL, the default behavior includes:
  • Checks for the following statements that are not compatible with JCL applications:
    • CONNECT
    • DISCONNECT
    • SET CONNECT
  • Reports an error for each incompatible statement found.
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.
Restriction: This topic applies to Windows environments only.

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.

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 CICS or Web Services applications.

XAID is mandatory when compiling the DB2 or Oracle SQL RM switch modules for dynamic registration that are also configured to run with User Impersonation.

See RM Switch Module Registration and the UserP=(T|F) section in SQL xa_open string Configuration Options 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 concepts
OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related reference
ANSI92ENTRY
AUTOCOMMIT
BEHAVIOR
CHECKDUPCURSOR
CHECKSINGLETON
DBMAN
ESQLVERSION
NIST
PF_UPD_CURSOR
TARGETDB
UPD_CONCURRENCY
SQL Compiler Directive Options


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 Windows environments with Windows authentication using NTLM:

    type=javax.sql.DataSource
    driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
    url=jdbc:sqlserver://localhost\SQLEXPRESS;database=Northwind;integratedSecurity=true;
    user=
    password=

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
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 Enterprise Developer 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.
  • COBES0211 DBRMLIB name is too long, max 44 characters.
    The value specified for the DBRMLIB HCOSS compiler directive option exceeds the maximum length of 44.
  • COBES0212 Simple name in DBRMLIB name is too long, max 8 characters.
    The value specified for the DBRMLIB HCOSS compiler directive option includes a simple name that exceeds the maximum length of eight.
  • COBES0213 Simple name in DBRMLIB name starts with invalid character.
    The value specified for the DBRMLIB HCOSS compiler directive option includes a simple name that begins with an illegal character.
  • COBES0214 Invalid character in DBRMLIB name.
    The value specified for the DBRMLIB HCOSS compiler directive option includes an illegal character.
  • COBES0215 MEMBER name is too long, max 8 characters.
    The value specified for the MEMBER HCOSS compiler directive option exceeds the maximum length of eight.
  • COBES0216 MEMBER name cannot begin with a numeric digit.
    The value specified for the MEMBER HCOSS compiler directive option begins with a numeric digit, which is not legal.
  • COBES0217 Invalid character in MEMBER name.
    The value specified for the MEMBER HCOSS compiler directive option contains an illegal character.
  • COBES0218 MEMBER directive not valid unless DBRMLIB directive set.
    You have set the MEMBER HCOSS compiler directive but neglected to also set the DBRMLIB HCOSS compiler directive. MEMBER is dependent on DBRMLIB.
  • COBES0219 VERSION directive not valid unless DBRMLIB directive set.
    When compiling an application, you have set the VERSION HCOSS directive without also explicitly setting the DBRMLIB HCOSS directive. The VERSION directive is dependent on the DBRMLIB directive.
  • COBES0220 VERSION is too long, max 64 characters.
    The value specified for the VERSION HCOSS compiler directive has exceeded its maximum allowable length of 64 characters.
  • COBES0221 Invalid character in VERSION.
    The value specified for the VERSION HCOSS compiler directive contains an invalid character.
  • 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 Enterprise Developer Personal Edition. This Edition does not support ODBC.

Resolution:

Either upgrade to Enterprise Developer, 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


COBES0211 DBRMLIB name is too long, max 44 characters.

The value specified for the DBRMLIB HCOSS compiler directive option exceeds the maximum length of 44.

Resolution:

Recompile the application, specifying a DBRMLIB value that conforms to the syntax specifications for Partitioned Dataset Names, including a length of 44 characters or fewer.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0212 Simple name in DBRMLIB name is too long, max 8 characters.

The value specified for the DBRMLIB HCOSS compiler directive option includes a simple name that exceeds the maximum length of eight.

Resolution:

Recompile the application, specifying a DBRMLIB value that conforms to the syntax specifications for Partitioned Dataset Names, including a length of eight characters or fewer for each simple name.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0213 Simple name in DBRMLIB name starts with invalid character.

The value specified for the DBRMLIB HCOSS compiler directive option includes a simple name that begins with an illegal character.

Resolution:

Recompile the application, specifying a DBRMLIB value that conforms to the syntax specifications for Partitioned Dataset Names, including an alphabetic character at the beginning of each simple name.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0214 Invalid character in DBRMLIB name.

The value specified for the DBRMLIB HCOSS compiler directive option includes an illegal character.

Resolution:

Recompile the application, specifying a DBRMLIB value that conforms to the syntax specifications for Partitioned Dataset Names.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0215 MEMBER name is too long, max 8 characters.

The value specified for the MEMBER HCOSS compiler directive option exceeds the maximum length of eight.

Resolution:

If you have not specified the MEMBER compiler directive option, then HCOSS uses the program name by default. In this case, reduce the length of your program name to eight characters or fewer, and recompile the program.

If you have specified the MEMBER compiler directive option, then recompile the program specifying a member name that conforms to the syntax for mainframe Partitioned Data Set names, including eight characters or fewer.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0216 MEMBER name cannot begin with a numeric digit.

The value specified for the MEMBER HCOSS compiler directive option begins with a numeric digit, which is not legal.

Resolution:

If you have not specified the MEMBER compiler directive option, then HCOSS uses the program name by default. In this case, change the name of your program name such that it starts with an alphabetic character, and recompile the program.

If you have specified the MEMBER compiler directive option, then recompile the program specifying a member name that begins with an alphabetic character.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0217 Invalid character in MEMBER name.

The value specified for the MEMBER HCOSS compiler directive option contains an illegal character.

Resolution:

If you have not specified the MEMBER compiler directive option, then HCOSS uses the program name by default. In this case, change the name of your program name such that it conforms to the syntax for mainframe Partitioned Data Set names, and recompile the program.

If you have specified the MEMBER compiler directive option, then recompile the program specifying a member name that conforms to the syntax for mainframe Partitioned Data Set names.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0218 MEMBER directive not valid unless DBRMLIB directive set.

You have set the MEMBER HCOSS compiler directive but neglected to also set the DBRMLIB HCOSS compiler directive. MEMBER is dependent on DBRMLIB.

Resolution:

Recompile the program, specifying both the MEMBER and the DBRMLIB HCOSS compiler directives.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0219 VERSION directive not valid unless DBRMLIB directive set.

When compiling an application, you have set the VERSION HCOSS directive without also explicitly setting the DBRMLIB HCOSS directive. The VERSION directive is dependent on the DBRMLIB directive.

Resolution:

Recompile the application, specifying both the VERSION and the DBRMLIB compiler directives.

Parent topic: OpenESQL Preprocessor Error Messages


COBES0220 VERSION is too long, max 64 characters.

The value specified for the VERSION HCOSS compiler directive has exceeded its maximum allowable length of 64 characters.

Resolution:

Recompile the application, specifying a VERSION value of 64 or fewer letters, digits, or underscore characters (_).

Parent topic: OpenESQL Preprocessor Error Messages


COBES0221 Invalid character in VERSION.

The value specified for the VERSION HCOSS compiler directive contains an invalid character.

Resolution:

Recompile the application, specifying a VERSION value containing only letters, digits, or underscore characters (_)

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.
Restriction: This topic applies to Windows environments only.

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
Parent topic: Run-time Services
Parent topic: DB2 to SQL Server Conversion Reference
Related concepts
Customizing SQLCA Error and Warning Processing


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.

For more information about parameter settings, see the topic OpenESQL Configuration Utility for Default SQL Cursor Behavior.

Parent topic: OpenESQL
Related concepts
OpenESQL Configuration Utility for Default SQL Cursor Behavior
OpenESQL Configuration Utility for Default SQL Cursor Behavior
Related tasks
To start the OpenESQL Configuration utility
Related reference
BEHAVIOR


MDCLGEN command-line tool

Note: This topic applies to Windows environments only.

MDCLGEN is a batch tool alternative to generating copybooks and include files using the OpenESQL Assistant. For the most part, MDCLGEN generates code using the current options set for the OpenESQL Assistant; however, you can override certain default settings via command-line parameters.

Syntax

MDCLGEN mode=ODBC; db=dsn; tbl=table-name; file=cpy-filename;
   [u=user-id;] [p=password;] [typevar={STD | SQL}]; [case={U | L | ASIS};]
   [schema=schema-name;] [sjis={T | F};}

Parameters

Required parameters
The following parameters are required at the command line regardless of the settings in OpenESQL Assistant options.
mode=ODBC
The type of code to generate. MDCLGEN supports ODBC only.
db=dsn
The cataloged data source name.
tbl=table-name
The name of the table from which to generate the copybook.
Note: When running in ODBC mode, table names might be case sensitive; therefore, best practice is to match the case you use for table-name to the case used in the name of the actual table.
file=cpy-filename
The name of the generated copybook.
Optional override parameters
The following parameters are not required at the command line, and default to the settings specified in the OpenESQL Assistant options. However, you can specify one or more of these parameters with MDCLGEN to override default settings:
u=user-id
The user ID needed to log into the specified database. Required only when credentials are required by the database. Equivalent OpenESQL Assistant option is User name.
p=password
The password needed to log into the specified database. Required only when credentials are required by the database. Equivalent OpenESQL Assistant option is Password.
typevar={STD | SQL}
The Type COBOL variables to generate:
STD | Standard Type COBOL Type variables. Default setting.
SQL | Enables the OpenESQL preprocessor to better determine host variable usage
Equivalent OpenESQL Assistant option is Type COBOL variable.
case={U | L | ASIS}
The case to use for characters in generated copybooks:
U | Uppercase
L | Lowercase
ASIS | A combination of upper and lower case as found in the specified table. Default setting.
Equivalent OpenESQL Assistant option is Generate code.
Optional parameters
The following optional parameters have no equivalent in OpenESQL Assistant:
schema=schema-name
The schema name for the specified table. Required only when multiple schemas exist for same table. No default setting.
Note: When running in ODBC mode, schema names might be case sensitive; therefore, best practice is to match the case you use for schema-name to the case used in the name of the actual schema.
sjis={T | F}
When set to T, the copybook is saved as an SJIS file. The default is F.

Example

MDCLGEN command line:
MDCLGEN mode=odbc; db=sample; tbl=EMPLOYEE; file=employee.cpy; typevar=sql;
Generated employee.cpy copybook:
      *> -------------------------------------------
      *> DECLARE TABLE for EMPLOYEE
      *> -------------------------------------------
           EXEC SQL DECLARE EMPLOYEE TABLE
           ( EMPNO                CHAR(6)      NOT NULL
           , FIRSTNME             VARCHAR(12)  NOT NULL
           , MIDINIT              CHAR(1)
           , LASTNAME             VARCHAR(15)  NOT NULL
           , WORKDEPT             CHAR(3)
           , PHONENO              CHAR(4)
           , HIREDATE             DATE
           , JOB                  CHAR(8)
           , EDLEVEL              SMALLINT     NOT NULL
           , SEX                  CHAR(1)
           , BIRTHDATE            DATE
           , SALARY               DECIMAL(9,2)
           , BONUS                DECIMAL(9,2)
           , COMM                 DECIMAL(9,2)
           ) END-EXEC.
      *> -------------------------------------------
      *> COBOL HOST VARIABLES FOR TABLE EMPLOYEE
      *> -------------------------------------------
       01  DCLEMPLOYEE.
           03 EMPLOYEE-EMPNO                  SQL TYPE IS
                                              CHAR(6).
           03 EMPLOYEE-FIRSTNME               SQL TYPE IS
                                              CHAR-VARYING(12).
           03 EMPLOYEE-MIDINIT                SQL TYPE IS
                                              CHAR(1).
           03 EMPLOYEE-LASTNAME               SQL TYPE IS
                                              CHAR-VARYING(15).
           03 EMPLOYEE-WORKDEPT               SQL TYPE IS
                                              CHAR(3).
           03 EMPLOYEE-PHONENO                SQL TYPE IS
                                              CHAR(4).
           03 EMPLOYEE-HIREDATE               SQL TYPE IS DATE.
           03 EMPLOYEE-JOB                    SQL TYPE IS
                                              CHAR(8).
           03 EMPLOYEE-EDLEVEL                PIC S9(04)  COMP-5.
           03 EMPLOYEE-SEX                    SQL TYPE IS
                                              CHAR(1).
           03 EMPLOYEE-BIRTHDATE              SQL TYPE IS DATE.
           03 EMPLOYEE-SALARY                 PIC S9(7)V9(2)  COMP-3.
           03 EMPLOYEE-BONUS                  PIC S9(7)V9(2)  COMP-3.
           03 EMPLOYEE-COMM                   PIC S9(7)V9(2)  COMP-3.
      *> -------------------------------------------
      *> COBOL INDICATOR VARIABLES FOR TABLE EMPLOYEE
      *> -------------------------------------------
       01  DCLEMPLOYEE-NULL.
           03 EMPLOYEE-MIDINIT-NULL           PIC S9(04)  COMP-5.
           03 EMPLOYEE-WORKDEPT-NULL          PIC S9(04)  COMP-5.
           03 EMPLOYEE-PHONENO-NULL           PIC S9(04)  COMP-5.
           03 EMPLOYEE-HIREDATE-NULL          PIC S9(04)  COMP-5.
           03 EMPLOYEE-JOB-NULL               PIC S9(04)  COMP-5.
           03 EMPLOYEE-SEX-NULL               PIC S9(04)  COMP-5.
           03 EMPLOYEE-BIRTHDATE-NULL         PIC S9(04)  COMP-5.
           03 EMPLOYEE-SALARY-NULL            PIC S9(04)  COMP-5.
           03 EMPLOYEE-BONUS-NULL             PIC S9(04)  COMP-5.
           03 EMPLOYEE-COMM-NULL              PIC S9(04)  COMP-5.
Parent topic: OpenESQL


User Interface Reference

Restriction: This topic applies to Windows environments only.
  • OpenESQL Assistant
Parent topic: OpenESQL


OpenESQL Assistant

  • OpenESQL Assistant - Options
  • OpenESQL Assistant - Main Window
  • Select Type of Query to Create dialog box
  • Query tab
  • Results tab
  • Details tab
  • Search Criteria tab
  • Literal Value dialog box
  • Sort tab
  • Auxiliary Code tab
  • Data Source Properties dialog box
Parent topic: User Interface Reference


OpenESQL Assistant - Options

DCLGEN

Use level 49
By default, OpenESQL Assistant generates a host variable as a PIC X(n) field for VARCHAR columns. When data is mapped to the host variable, it is null terminated. However, you can set OpenESQL Assistant to generate the host variable with two level-49 variables; one for the length of the data mapped and one for the actual text data.
Type COBOL Variable
By default, OpenESQL Assistant generates COBOL host variables using COBOL definitions where appropriate. You can set this option to SQL TYPE to enable the SQL precompiler to better determine host variable usage.
Structure name
By default, OpenESQL Assistant generates the structure name for the copybook as DCLtablename. You can also generate the structure name using just the table name or you can supply your own structure name as long as it is a valid COBOL name. OpenESQL Assistant converts all underscores into hyphens. When you set this option to Other, specify your own structure in the User Defined Structure Name field.
User Defined Structure Name
Specify an 01-level COBOL structure name to use when generating the copybook. Required when Structure Name is set to Other.
Host Variable Prefix
By default, OpenESQL Assistant creates host variables using a combination of the column name and a prefix of the table name, converting all underscores to hyphens to create a valid COBOL name. You can also set OpenESQL Assistant to always generate host variables using only the column name (no prefix) or to use an alphabetic character prefix. Host variables generated with alphabetic character prefixes use "A" for the first table selected, "B" for the second table, etc.
Note: If a generated host variable name would result in a name that is either longer than 31 characters in length or that would contain invalid characters, OpenESQL Assistant generates the host variable name as the column number with a prefix of "FLD" regardless of the method specified.
Indicator Variables
By default, OpenESQL Assistant generates indicator variables at the end of a copybook. You can also set OpenESQL Assistant to generate indicator variables after each host variable instead. Your third option is to set OpenESQL Assistant so that no indicator variables are generated.

General

Generate code
By default, OpenESQL Assistant generates SQL queries and copybooks using a combination of upper and lower case. You can also set OpenESQL Assistant to generate in all uppercase or all lowercase.
List items in table name sequence
By default, OpenESQL Assistant lists items in the tree view in the sequence that they are returned from the system catalog. You can also set OpenESQL Assistant to list items in table name sequence instead. When you set OpenESQL Assistant to list items in table name sequence, owner names are not considered.
Mode

Set this option before connecting to a data source.

ODBC
Builds the list of data sources maintained by the ODBC Data Source Administrator (32-bit version).
XDB
Builds the list of data sources maintained by SQL Option for DB2.
Output language
By default, OpenESQL Assistant generates COBOL SQL queries. To generate PL/I SQL queries instead, set this option to PLI.
Prompt on disconnect
By default, OpenESQL Assistant does not prompt you when disconnecting from a data source. If you want to be prompted to save a query you have built before disconnecting, set this option to True. Otherwise, you could lose the query.

Logon

User name
The user name used to connect to your data source. If you choose not to specify a user name, OpenESQL Assistant prompts you when connecting to a data source.
Password
The password associated with the user ID in the User name field.

Query

Qualify table with owner name
By default, OpenESQL Assistant displays all tables in the tree view and builds all queries unqualified. However, if the data source has multiple tables with the same table name, you can set OpenESQL Assistant to show table names in the tree view with their owner names immediately following in parenthesis. Queries performed also return table names qualified with the owner name.
Quote table and column names
By default, OpenESQL Assistant does not enclose column and table names with the quote identifier associated with the data source unless the column or table name contains embedded blanks, a special character such as $, or DBCS characters. You can set OpenESQL Assistant to enclose all table and column names with the appropriate quote identifier by setting this option to True.
Use SQLSTATE
By default, OpenESQL Assistant generates SQL statements using SQLCODE checking. You change this to set OpenESQL Assistant to generate SQL statements using SQLSTATE checking instead.
Generate Interface Code
By default, OpenESQL Assistant generates SQL statements for use by any application. You can also set OpenESQL to generate SQL statements that can be used as a Web service.
Maximum Result Rows
By default, OpenESQL Assistant only returns the first 50 rows when you run a query. This is to prevent queries from returning huge numbers of rows, potentially crashing your machine or overloading your network. However, you can set the maximum number of rows returned to a number of your choice. Set this value to -1 if you want all rows returned. We recommend that you choose the number based on the amount of data you expect to be returned, or based on your testing needs.
Parent topic: OpenESQL Assistant
Related concepts
Setting OpenESQL Assistant Options
Related tasks
To set OpenESQL Assistant options


OpenESQL Assistant - Main Window

Data Source List
A list of all catalogued data sources available for use with OpenESQL Assistant.
Create New Query Create New Query
Create a new SQL query for the data source.
Create New Query Run Query
Run the query shown on the Query tab.
Add query to temporary file Add query to temporary file
Add the query shown on the Query tab to the temporary file, or add the auxiliary code shown on the Auxiliary Code tab to the temporary file.
Insert query into program View temporary file
View and optionally edit the code in the temporary file.
Insert query into program Save temporary file
Save the contents of the temporary file to .
Refresh list of data sources Refresh list of data sources
Reload the list of data sources on the data source list, including updates to any data sources that have been added or deleted since the last time the list was loaded.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Setting OpenESQL Assistant Options
Related tasks
To set OpenESQL Assistant options
To connect to a data source
To connect to a different data source
To disconnect from a data source
To close a query
To run a query
To start the OpenESQL Assistant


Select Type of Query to Create dialog box

Query Type List
A list of all query types available.
Generate query as TSQL stored procedure
Generates a TSQL stored procedure. When unchecked, OpenESQL Assistant does not generate a stored procedure query. Available when the Type Stored Procedure OpenESQL Assistant Option is set to TSQL and you have selected a SQL Server data source.
Generate query with FOR UPDATE
Generates a FOR UPDATE clause as part of a SELECT (cursor) or SELECT DISTINCT (cursor) SQL query.
Generate query with WHERE CURRENT OF
Generates a WHERE CURRENT OF clause as part of an UPDATE or DELETE SQL query.
SP Name
The name of the stored procedure you want to generate. A default name is supplied; however, you can override this by typing in a name of your choice. Applies to stored procedure queries only. Available only when you have selected a SQL Server data source.
Cursor Name
The name of the cursor generated for the query. A default name is supplied; however, you can override this by typing in a name of your choice. Available when the Generate OpenESQL Assistant Option is set to EXEC SQL.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Building Queries
Setting OpenESQL Assistant Options
Stored Procedures
Related tasks
To set OpenESQL Assistant options
To create a TSQL stored procedure query
To create an SQL query


Query tab

Shows the query code generated by OpenESQL Assistant, based on the selections made.

Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Building Queries
Related tasks
To embed an SQL query into a program


Results tab

Column n
Shows the data returned for the column specified in the query.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Building Queries
Testing Your SQL Queries


Details tab

Shows column information for the selected table. A checked box next to a column name indicates that the column is included in the current query.

Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Building Queries
Display Column Details


Search Criteria tab

Column
A list of columns available for this query.
Conditional Operator
A list of operators available for building search criteria.
Target Type
A list of available target types for the search criteria, including Host Variable, Literal, Special Register, and Column Name.
Target Value
A list of values available for the Target Type selected.
Edit
Invokes the Literal Value dialog box, enabling you to supply a literal value required for the search criteria. The value supplied populates the Target Value field. Available when Target Type is set to Literal.
AND
Insert the AND operator into the search criteria.
OR
Insert the OR operator into the search criteria.
Insert Search String Insert Search String
Move the defined search string to the Generated Search Criteria.
Remove Search String Remove Search String
Remove the selected search string from the Generated Search Criteria.
Generated Search Criteria
List of search strings included in the search criteria.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Specifying Search Criteria
Building Queries
Related tasks
To specify search criteria (a WHERE clause)


Literal Value dialog box

Column Name
Shows the name of the column selected for the search string.
Column Type
Shows the data type of the column selected for the search string.
Precision
The maximum number of digits allowed in column data.
Scale
The maximum number of digits allowed to the right of a decimal point in column data.
Column Value
The literal value assigned to the column used in the search string.
Generated Delimiters
Delimiters automatically generated for the literal value specified in the Column Value field.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Building Queries
Related tasks
To specify search criteria (a WHERE clause)


Sort tab

Columns in SELECT
A list of columns available for inclusion in the SELECT statement.
Asc
Sort alphabetically by first letter of the column name in ascending order.
Desc
Sort alphabetically by first letter of the column name in descending order.
Insert Search String Insert Sort String
Move the defined sort string to the Columns in ORDER BY list.
Remove Search String Remove Sort String
Remove the selected sort string from the Columns in ORDER BY list.
Columns in ORDER BY
Sort strings inserted into your query.
Use integers for column names
Generate the integer value of the column instead of the column name.
Note: Column names are displayed on the Columns in ORDER BY list regardless of the setting for Use integers for column names.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Related tasks
To sort returned data (an ORDER BY clause)


Auxiliary Code tab

EXEC SQL
Generate an EXEC SQL statement based on the statement type selected in the Statement Type field.
Statement Type
Lists EXEC SQL statement types available for auxiliary code generation.
Host Variable Array Size
The number that represents the maximum number of rows you want returned for each array FETCH.
Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
Auxiliary Code
To generate and embed auxiliary code


Data Source Properties dialog box

Lists and describes the properties of the selected data source.

Parent topic: OpenESQL Assistant
Related concepts
OpenESQL Assistant
To view data source properties


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

Windows:

{preprocess | p}(cobsql) [[[{cobsqltype|csqlt}=preCompiler] [COBSQLopts] {end-cobsql|end-c|end} [PreCompilerOpts endp]]

UNIX:

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. (applies to UNIX environments only)

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

Windows:

cobol testprog p(cobsql) csqlt=ora makesyn end-c xref=yes mode=ansi endp list()

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

cobol sample.pco anim preprocess(cobsql) cstart cstop csqlt=ora end-c comp5=yes endp;

The COBOL compiler directive specified is anim. The COBSQL directives, initiated by preprocess(cobsql) and terminated by end-c, are cstart cstop and csqlt=ora. The precompiler directive (in this case, Pro*COBOL), terminated by endp, is comp5=yes. The semicolon (;) indicates the end of the command line.

UNIX:

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.

Sybase
Windows:
cobol example1.pco confirm preprocess(cobsql)
   cstop csp cobsqltype=sybase preprocess(cp) sy endp;
UNIX:
cob -a -v -P -k example1.pco -C "p(cobsql) CSQLT==syb endp"
Informix
UNIX:
cob -a -k demo1.eco -C "p(cobsql)
    cobsqltype==informix-new endp"
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 if the application is running under Enterprise Server. 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.
  • SQLBGP
    Enables proper SQL background parsing when Pro*COBOL is not installed on your local machine, and you are using the local machine to access an Eclipse project on a remote machine that does have Pro*COBOL installed.
  • 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)
Related information
Setting Compiler Directives for COBOL
$SET Statements in the Source Code


COBSQLTYPE, CSQLT

Specifies which precompiler to use.

Syntax:

{COBSQLTYPE|CSQLT}={ORACLE|ORACLE8|SYBASE|INFORMIX-NEW}

Properties:

Default: COBSQLTYPE=ORACLE8
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 if the application is running under Enterprise Server. 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


SQLBGP

Enables proper SQL background parsing when Pro*COBOL is not installed on your local machine, and you are using the local machine to access an Eclipse project on a remote machine that does have Pro*COBOL installed.

Syntax:

[NO]SQLBGP

Properties:

Default: NOSQLBGP

Comments:

Use SQLBGP to prevent background parsing from failing when Pro*COBOL is not installed on the local machine and you are using an Eclipse remote project.

SQLBCP is required when COBSQL is set in a directives file only.

SQLBCP is not required when COBSQL is set in your Eclipse project properties, or set in your source code using a $SET statement.

Parent topic: COBSQL Compiler Directive Options


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.

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

  • Tiny Integer
  • Small Integer
  • Integer
  • Big Integer
Parent topic: SQL Data Types


Tiny Integer

A tiny integer (TINYINT) is a 1-byte integer SQL data type.

Host Variable Formats

OpenESQL JVM Managed Runtime
01 tinyint1          PIC S9(2) COMP-5.
01 tinyint2          PIC S9(2) COMP.
01 tinyint3          PIC S9(2) BINARY.
01 tinyint4          PIC X     COMP-5.
01 tinyint5          PIC 9(2)  COMP-X.
01 tinyint6          binary-char.
Parent topic: Integer 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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 shortint10     binary-short.
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.

OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 longint9      binary-long.
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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 bigint5     binary-double.
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.

OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 char-net         string(200).
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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 varchar6           string.
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.
OpenESQL JVM Managed Runtime
OpenESQL JVM Managed Runtime applications have no byte limit. In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 clob3     string.
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.
OpenESQL JVM Managed Runtime
In addition to the definition valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 uni-field2      string.

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.
OpenESQL JVM Managed Runtime
In addition to the definition valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 unichar3               string.

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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 dbclob3     string.

OpenESQL JVM Managed Runtime applications have no byte limit.

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).
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 dbcs-field3      string.

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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 dbcschar3      string.

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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 dbcs3      string.

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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 real2       float-short.
01 float2      float-long.
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
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01  packed05    type java.math.BigDecimal.
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
    • Use JVM Byte 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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for all databases and for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 bin-field5      type java.lang.byte[].
01 bin-field6      type java.lang.byte occurs 200 times.

OpenESQL JVM Managed Runtime applications have no byte limit.

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
    • Use JVM Byte host variables
  • The varbin-field1 format uses the VARBINARY SQL TYPE.
  • The varbin-field2 format uses the LONG-VARBINARY SQL TYPE.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 varbin-field5      type java.lang.byte[].

OpenESQL JVM Managed Runtime applications have no byte limit.

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
    • Use JVM Byte host variables
OpenESQL JVM Managed Runtime
In addition to the definitions valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 blob3     type java.sql.Blob.

OpenESQL JVM Managed Runtime applications have no byte limit.

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 with the exception of OpenESQL JVM Managed Runtime applications that use JVM date and time data types.

  • DATE
  • DATETIMEOFFSET
  • 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 Enterprise Developer 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 Enterprise Developer 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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for all databases and those valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 date5         type java.sql.Date.
Parent topic: Date and Time Data Types
Related reference
DATE SQL Type
DATE-RECORD SQL Type
DATE
DATEDELIM


DATETIMEOFFSET

Data Format

SQL Server 2008 introduced a new SQL date/time data type, DATETIMEOFFSET, which is supported by OpenESQL. The date and time are specified in the following format:
yyyy-mm-dd hh:mm:ss[.f[f[...]]]  {+ | -}hh:mm

Host Variable Formats

OpenESQL
01 datetimeoffset1     PIC X(34).
This data type can also use a DateTimeOffset record layout. For more information, see the topic The SQLDA Data Structure.
Parent topic: Date and Time Data Types
Related reference
The SQLDA Data Structure


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 Enterprise Developer 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 Enterprise Developer 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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for all databases and those valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 time5         type java.sql.Time.
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 Enterprise Developer 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 Enterprise Developer 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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for all databases and those valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 timestamp5         type java.sql.Timestamp.
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.
OpenESQL JVM Managed Runtime
In addition to the definitions valid for all databases and those valid for OpenESQL, the following definition is also valid for the OpenESQL JVM Managed Runtime:
01 timestampoffset4   type System.DateTimeOffset.
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
  • RESULT-SET-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


RESULT-SET-LOCATOR Data Type

Host Variable Format

OpenESQL
01 result-set-locator1 SQL TYPE IS RESULT-SET-LOCATOR VARYING.
  • RESULT-SET-LOCATOR is only valid for OpenESQL applications compiled with HCOSS directives.
  • The result-set-locator1 format uses the RESULT-SET-LOCATOR SQL TYPE.
Parent topic: Locator Data Types
Related reference
RESULT-SET-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
  • RESULT-SET-LOCATOR 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
Setting OpenESQL Assistant Options
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


RESULT-SET-LOCATOR SQL Type

Note: Valid only for OpenESQL applications compiled with HCOSS compiler directives

Syntax

SQL [TYPE] [IS] RESULT-SET-LOCATOR VARYING

Example

01 hv-name SQL TYPE IS RESULT-SET-LOCATOR VARYING.

generates

01 hv-name PIC S9(9) COMP-5.
Parent topic: SQL TYPEs
Related reference
RESULT-SET-LOCATOR Data Type


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-data   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. Microsoft SQL Server limits fractional seconds to three 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. Microsoft SQL Server limits fractional seconds to three 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).

Oracle, Sybase and Informix all have different versions of the SQLCA. The Oracle, Sybase and Informix SQLCAs all have a SQLCODE, SQLERRML, SQLERRMC and a SQLWARN. The sizes and the positions of these fields can differ among the precompilers

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.
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
Related reference
DATETIMEOFFSET


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
  • Classic 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.
  • Data File Structure Command Line Utility
    The Micro Focus Data File Structured Command Line (DFSTRCL) utility is a command line utility that enables you to create record layout (.str) files.
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. You can also edit existing data sets within your Enterprise Server regions.

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.

  • Current Restrictions
  • Accessing Data File Editor
  • Preferences
  • Using the Data File Editor
  • Using the Classic Record Layout Editor
Parent topic: Data File Tools
Related tasks
Tutorial: Data File Editor


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.
  • Structure files are created using the Classic Record Layout Editor or DFSTRCL command line tool. The Classic Record Layout Editor is available with Windows development products, and the DFSTRCL command line tool is available on Windows and UNIX platforms, for development and deployment products. The Classic Record Layout Editor is capable of producing structure files that contain default and conditional layouts, but DFSTRCL is only capable of producing structure files containing default layouts. For both tools, you are required to use an .idy file, which is generated using a development product.
  • Editing files is not supported if your environment contains any form of filename manipulation; for example, the DATAFILE and FILESUFFIX options within an extfh.cfg file, or the setting of the COBDATA environment variable. To work around this restriction on Windows, open Data File Editor from the Windows menu, ensuring no such filename manipulation variables are set at a system level.
  • The only supported UNIX platforms are SUSE, Red Hat, 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 and profile files (.pro files) used in Classic Data File Tools. In this release and beyond, we have reverted back to the conventional .str and .pro files. If you use .dfs structure files, you must use Classic Data File Tools to create equivalent structure and profile 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.
  • A limitation of the Windows clipboard means that when cutting or copying text from the editor, if the selection contains 0x00, any text after this character is truncated when pasted from the clipboard.
  • If you are 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 Command Line or Shell Prompt
  • Launching Data File Editor from the Start Menu
Parent topic: Data File Editor


Launching Data File Editor from a Command Line or Shell Prompt

Use the following syntax to launch Data File Editor from your Enterprise Developer command line or 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
Related information
Launching Data File Editor from the Start Menu


Launching Data File Editor from the Start Menu

On Windows platforms, launch Data File Editor from the Start menu:

  • Click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > Data File Tools.
Parent topic: Accessing Data File Editor
Related information
Launching Data File Editor from a Command Line or Shell Prompt


Preferences

The Preferences section contains the following tabs:

Data File Editor

You can set the following preferences when using the Data File Editor:

Records per page
Set the amount of records you want to display per page. The more records you display per page, the more memory that is required; therefore, reduce the amount of records per page if you receive memory problems. Use the [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 tutorial Tutorial: Configuring SSL Security in the Server explains how to configure an enterprise server to use an SSL connection.

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.
  • 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
Related tasks
Create a Structure File and Record Layouts


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, c:\path\to\file\dat-name.dat (Windows), or /home/path/to/file/dat-name.dat (UNIX).
    • 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 (Windows), or $$FS-server-name/dat-name.dat (UNIX).
  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, c:\path\to\file\dat-name.dat (Windows), or /home/path/to/file/dat-name.dat (UNIX).
    • 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 (Windows), or $$FS-server-name/dat-name.dat (UNIX).
  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
  • Layout and Field Validation
  • Edit a Record Using Hexadecimal Values
  • Delete a record
Parent topic: Using the Data File Editor
Related tasks
Create a Structure File and Record Layouts


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.

Note: This functionality does not support the iFileshare configuration of an enterprise server region.
  • 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
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.
    Note: If the region does not have an external security manager enabled, do not enter any details in these fields.
  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
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
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
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
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
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
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


View File Information

  1. From the Micro Focus Data File Tools window, click File > Open, or click [image] (Open File).

    The Open dialog box appears.

  2. Navigate to the required data file, then click Open.

    The Open Data File dialog box appears.

  3. If you are applying a 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 ositions 7 to 9 within each record, as indicated below

Field condition
This type of condition is only available if you have applied a layout to your data file. A field condition filters the entire contents of the selected field. You can select any non-group field in the layout on which to filter.

For both types of condition, you select a value that you wish to filter and an operator (for example, greater than, contains, or not equal to). There are also supplementary criteria to add to the condition, such as making it case sensitive, or trimming leading or trailing space from the area filtered.

Data File 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, 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, 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, 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, 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, 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


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, 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 Classic Record Layout Editor

Restriction: The Classic Record Layout Editor is only available for development products on Windows platforms. If you only require a default layout, on a UNIX platform or using a deployment product, you can use the DFSTRCL command line utility to produce a structure file; alternatively, if you require a structure file with conditional layouts, you must create it using the Classic Record Layout Editor using a development product, on Windows.

The Record Layout Editor within Classic Data File Tools is the editor that enables you to create structure files (.str files) for use within Data File Editor.

Structure files contain one or more record layouts. When you specify a structure file when opening a data file, you can use the record layouts to view and edit records in a structured way, which makes them easier to view and edit. A structure file is not mandatory; if a structure file is not applied, records are displayed unformatted, as long continuous strings of text.

Record layouts are derived from the Data Division (level-01 fields and below in the File Section and Working Storage Section) of a COBOL program that uses the data file, and are created using the .idy file from the compiled program.

There are two types of record layout that you can create:

Default record layout
You can define one default record layout for each structure file. When you open a data file with the structure file, each record is displayed using the default record layout unless the structure file also contains a conditional record layout and the record in question satisfies the criteria within the conditional record layout.
Conditional record layout
As well as a default record layout, you can create one or more conditional record layouts.
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 the current structure file does not contain a default layout and a record does not satisfy any of the conditional layouts, it is displayed unformatted. If you edit the record so that it satisfies the conditions check of a conditional layout, the record is updated to display using the layout. Conversely, if you edit a record so that it no longer satisfies the conditions check, the record reverts to either using the default layout (if there is one) or is displayed unformatted.

  • Create a Structure File and Record Layouts
Parent topic: Data File Editor


Create a Structure File and Record Layouts

Structure files and the record layouts within them cannot be created or viewed in Data File Editor. You must create the structure file and record layouts using the Classic Data File Tools product; after which, you can apply the resulting .str file to your data files in Data File Editor.
  1. From a Visual COBOL or Enterprise Developer command prompt, type mfdatatools, then press Enter.
  2. On the File menu, click New, then select Record Layout and click OK.

    The Select a file to construct the layouts from dialog box appears.

  3. Navigate to and select the debug information file (.idy file) from a program that uses the data file for which you are creating this structure file, then select Open.

    A Layout window appears, showing the Data Division of the COBOL program.

  4. Create a default layout (optional):
    1. From the left-hand pane, right-click the top-level data item on which to base your layout, then select New Layout.

      The New Record Layout Wizard dialog box appears.

    2. Select Default Layout, then click Next.
    3. Click Finish.

    The default layout is displayed in the right-hand pane.

  5. Create a conditional layout (optional):
    1. From the left-hand pane, right-click the top-level data item on which to base your layout, then select New Layout.

      The New Record Layout Wizard dialog box appears.

    2. Select Conditional Layout, then click Next.
    3. Click Finish.

      The conditional layout is displayed in the right-hand pane.

    4. Expand the layout to locate a field on which to base a condition, then double-click it.

      The Field Properties dialog box appears.

    5. Click [image] and select an operator from the Condition list, then add the appropriate value(s) to the right.
    6. Click OK.
    7. Repeat the last three steps if you need to add more conditions. (All conditions must be met for the layout to be used.)
  6. On the File menu, click Save.

    The Save As dialog box appears.

  7. In the File name field, type a name for the structure file, then click Save.

    The structure file is saved. To use it, you must specify its path and filename when creating or opening a data file.

Parent topic: Using the Classic Record Layout Editor
Related concepts
Creating Data Files
Editing Data Files


File Conversion Utilities

File Conversion Utility | Use to...
DFCONV | Convert downloaded data files to the required format on the PC
VRECGEN | Modify mainframe files into the format required for download from the mainframe to the PC
VRECGEN2 | Modify files uploaded from the PC into the format required on the mainframe
  • DFCONV Batch File Conversion
  • VRECGEN
  • VRECGEN2
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
  • Act as a called program 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.
  • A GUI version of the Data File Converter is also available as part of the Micro Focus Data Tools. To access these, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > Classic Data File Tools .
  • Operation
  • Using the Data File Converter
  • Data File Converter Error Messages
Parent topic: File Conversion Utilities
Related information
VRECGEN
VRECGEN2


Operation

The following sections describe the two Data File Converter operations:

  • The command line batch interface
  • The call batch interface
  • Command Line Batch Interface
  • The DFCONV call 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 (ERRORLEVEL) 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
The DFCONV call batch interface
Defining File Conversion with a Profile File


The DFCONV call batch interface

Calling the Data File Converter from a COBOL program

If a profile for a conversion exists, you can invoke the Data File Converter to do the conversion using the following interface:

call dfconv using dfconv-params

where:

 01 dfconv-params   PIC X(n).
dfconv-params can be up to 1024 characters and contains the following parameters. These must be separated by spaces in the call, and file names that include spaces should be put in straight quotation marks. File names can be up to 255 characters in length.
profile-filename
The name of the profile file containing the details of the data file conversion.
-d
Optional. Stops information about the call being displayed in the console.
input-filename
The name of the input file. Optional, but must have a value if you want to specify output-filename.
output-filename
Optional. The name of the output file. You must also specify a value for input-filename.

If you specify file names in the parameter fields as well as in the profile file, those in the parameter fields take precedence.

On return from the Data File Converter, RETURN-CODE is set to non-zero if an error occurred, and the error number is returned in the first two characters of dfconv-params.

Using the entry point DFCONVXL

Previous versions of the Data File Converter only supported file names of 65 characters, so an entry point DFCONVXL was included to support filenames of up to 255 characters. The entry point DFCONVXL is still provided and uses the same dfconv-params parameters described above.

Calling the Data File Converter from a non-COBOL program

The Data File Converter can be called from a non-COBOL program using an entry point DFCONVC, provided within the Data File Converter .dll. The dfconv-params parameters are space terminated as for the COBOL call but the parameter list is NULL terminated.

Parent topic: Operation
Related information
Command Line Batch Interface


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
Parent topic: Data File Converter
Related tasks
To convert a data 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


VRECGEN

VRECGEN is a mainframe utility. Use VRECGEN to create a copy of a variable-length mainframe file. That copy embeds record length information in the data records for download from the mainframe to the PC. Micro Focus provides the source code for the VRECGEN utility (vrecgen.cbl). However, you may need to modify the source code before use, to specify options not catered for by the supplied version vrecgen.cbl.

The file created by VRECGEN has a two-byte record length field preceding each of the variable length data records. The record length field contains a value which is the two-byte record length field plus the length of the variable length data record. This is necessary because most file transfer software (for example, IBM SEND/RECEIVE) works with logical records and strips off the "Record Descriptor Word" which contains the length for each record. Without this information, it is impossible to separate the records to rebuild the data set on the PC.

The file created by VRECGEN is in a special download format. You should use the standard Transfer utility to transfer this file to the PC in binary format. The file can then be processed through the Data File Converter.

Note:

The source code to VRECGEN (vrecgen.cbl) is provided by Micro Focus primarily as a model, rather than as a final utility that meets the needs of all sites without modification. You should edit your version of vrecgen.cbl so that it contains the specific values that meet your application or site requirements. A typical reason for editing vrecgen.cbl is to increase the maximum record length to be more than 32,000 bytes.

  • Installing VRECGEN
  • Running VRECGEN
Parent topic: File Conversion Utilities
Related information
DFCONV Batch File Conversion
VRECGEN2


Installing VRECGEN

If you plan to download variable-length test files, you must first upload and compile the VRECGEN program in your mainframe environment. This program is provided as a sample COBOL program for converting mainframe variable-length format files.

Note: Each site should review the provided source code and determine maximum and minimum lengths for its variable-length files. These values (plus 4 for the MVS "Record Descriptor Word") should be used in the OCCURS DEPENDING ON clause of the record descriptions in the sample FDs.

To install VRECGEN:

  1. The source code file for VRECGEN is copied onto the PC as part of the installation procedure; the file name is vrecgen.cbl and it copies to %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src and $COBDIR/copylib in the installation of your COBOL development system.
  2. After you install your COBOL development system, upload the file vrecgen.cbl to the mainframe, specifying conversion from ANSI to EBCDIC. Verify that the file is in fixed file, 80-byte card image format.
  3. Compile VRECGEN on your mainframe using your COBOL Compiler. When compiling this program, specify the following options. Some are compiler options, some run-time system options, and some are link-edit options. Use only those applicable to your specific environment and compiler:
    • NOSSRANGE or NOSUBRNGCK (no subscript range checking)
    • DATA(24)
    • NOOPT
    • AMODE=24,RMODE=24
Note: If you use VS COBOL II, Release 3 or above, and receive a file status of 39, recompile VRECGEN using the CMPR2 compile option.
Parent topic: VRECGEN
Related information
Running VRECGEN


Running VRECGEN

You need to supply the appropriate JCL information before running the VRECGEN on the mainframe. Enter the following JCL skeleton pointing to the correct STEPLIB, input data set and output data set:

//MYJOB   JOB (ACCOUNTING INFORMATION)
//STP1    EXEC PGM=VRECGEN
//STEPLIB DD DSN=STEPLIB,DISP=SHR
//SYSOUT  DD SYSOUT=*
//INPDD   DD DSN=INPUT.OS.DATA.SET,DISP=SHR
//OUTDD   DD DSN=OUTPUT.OS.DATA.SET,
//        DISP=(NEW,CATLG,DELETE),
//        DCB=(RECFM=VB,LRECL=LLL,BLKSIZE=BBB),
//        SPACE=(TRK,(X,Y),RLSE),
//        UNIT=SYSDA
Note:
  • When you fill in the LLL (LRECL) and BBB (BLKSIZE) values for the output file, refer to the values specified in the FD for OUTDD in your version of VRECGEN. The default LRECL and BLKSIZE from the program is 32700, but must be changed so that the JCL, FD in VRECGEN, and file-label on the input file are consistent.
  • The resulting output files are in the special download format, ready to be transferred to the PC using the standard transfer facility. Be sure, when you do the download, to specify a binary transfer and to not use the carriage control characters, CR (carriage return) and LF (line feed).
Parent topic: VRECGEN
Related information
Installing VRECGEN


VRECGEN2

VRECGEN2 is a mainframe utility that converts files in Micro Focus variable-length record format to mainframe format. Thus it enables you to upload these files and use them on the mainframe.

  • Installing VRECGEN2
  • Running VRECGEN2
Parent topic: File Conversion Utilities
Related information
DFCONV Batch File Conversion
VRECGEN


Installing VRECGEN2

If you plan to convert files in Micro Focus variable-length record format to mainframe format, you must first upload and compile the VRECGEN2 program in your mainframe environment:

  1. The source code file for VRECGEN2 is copied onto the PC as part of the installation procedure. The file name is vrecgen2.cbl and it is copied to %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src. and $COBDIR/copylib in the installation of your COBOL development system.
  2. After you install your COBOL development system, upload the file vrecgen2.cbl to the mainframe, in the same way as for VRECGEN, using CRLF and ANSI as parameters
Parent topic: VRECGEN2
Related information
Running VRECGEN2


Running VRECGEN2

The following steps show you how to upload a variable length data file whose records are between 100 and 400 bytes long:

  1. Convert your variable-length PC file to VRECGEN2 input format using the Data File Converter. Specify the minimum and maximum record lengths as 100 and 400 respectively. Note that because the Data File Converter prepends two bytes containing the record length, the actual minimum and maximum lengths are 102 and 402 respectively. If the file is in ANSI format, you should also convert it to EBCDIC format at the same time.
  2. On the mainframe, allocate a data file to receive the file from the PC. Use the following parameters:
    • FORMAT = VB
    • RECLEN = 406
    • BLKLEN = 410
  3. Upload the file. Don't set CRLF insertion. If you converted to EBCDIC at step 1, don't specify ANSI.
  4. Change the source of vrecgen2.cbl on your mainframe so that the FD for the output file matches the format of the required mainframe data file
  5. Compile and link vrecgen2.cbl
  6. Run VRECGEN2. The JCL is the same as for VRECGEN, except for the following changes:
    • The program-name should be VRECGEN2
    • The output file definition should be consistent with the output FD in VRECGEN2
    • Specify:
      • RECFM=FB
      • LRECL=404
      • BLKSIZE=408

A valid variable length file should result as the output. The following shows the format of a VRECGEN2 format file, using a record length of 100 bytes as an example:

Bytes | Contents
1-4 | Record Descriptor Word.
5-6 | Record length.
7-106 | Record data. The record is padded with null bytes if it is shorter than the maximum record size.
Note: The VRECGEN and VRECGEN2 file formats are incompatible in that VRECGEN format is used to download files from the mainframe and VRECGEN2 format is used to upload Micro Focus format files to the mainframe.
Parent topic: VRECGEN2
Related information
Installing VRECGEN2


Data File Structure Command Line Utility

The Classic Data File Tools utility enables you to create record and segment layout files using COBOL and Open PL/I debug information files. The Classic Data File Tools provides a GUI that simplifies the process of creating records. The Data File Structure Command Line (DFSTRCL) utility complements the Classic Data File Tools utility and enables you to create record layout (.str) files from .idy files directly from the command line.

  • DFSTRCL Prerequisites and Restrictions
    This details the prerequisites, operating environment and limitations of the DFSTRCL utility.
  • DFSTRCL Inputs
    This details how to create the .idy files used as input to the DFSTRCL utility.
  • DFSTRCL Command Line Syntax
    This details the DFSTRCL command syntax used to create a record layout (.str) file from COBOL debug information (.idy) file.
Parent topic: Data File Tools


DFSTRCL Prerequisites and Restrictions

The DFSTRCL utility is installed as part of Enterprise Developer.

The DFSTRCL utility has the following restrictions:

  • The utility is not available within Enterprise Test Server, Enterprise Server or Enterprise Server environments.
  • The utility does not accept PL/I information files.
  • The utility does not support the creation of segment layout files for IMS database segments.
  • The utility can process up to a maximum of 100 .idy files in its parameters file.
Parent topic: Data File Structure Command Line Utility


DFSTRCL Inputs

The DFSTRCL utility takes the debug information (.idy) file as an input, so before running the utility you need to create an .idy file.

To produce and .idy file for a COBOL program you must compile it:

  1. From an Enterprise Developer command prompt, change to the directory that contains the COBOL program you want to generate an information file for.
  2. Execute the following from the command prompt:
    cobol filename.cbl anim;

    This generates an information file called filename.idy.

An .idy file is also produced if you compile the file in the IDE as part of a project.

Once you have created an .idy file, you can run the DFSTRCL utility to generate a record layout .str file based on the Data Division information in the .idy file.

Parent topic: Data File Structure Command Line Utility


DFSTRCL Command Line Syntax

You must run this command from a Enterprise Developer command prompt, available from Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt.

You can run the DFSTRCL utility to process a single debug information (.idy) file. Alternatively, you can configure DFSTRCL to perform batch processing using a parameters file passed at the command line using the /r parameter. You can use a parameters file that contains a maximum of 100 .idy files.

Syntax:

dfstrcl idy_file.idy {/a|/d record_name} [/o str_file] [/r param_file.ext] [/?]

Parameters:

idy_name.idy
The name of the COBOL debug information (.idy) file. Optionaly, you can provide it prefixed with a relative or absolute file path.
/a
The first 01-level group in the .idy file is used for the default layout. If you use this option, you do not need to specify /d record_name.
/d record_name
The default record layout name to be used from the debug information file.
/o str_file
Optional, the name for the output record layout (.str) file . The default is the basename of the .idy file with a .str extension.
Note: If the output filename does not include a .str extension it will be appended to the filename specified.
/r param_file.ext
Optional, the parameters filename. The parameters file can contain .idy file names to process and optional /d and /o parameters. Using a parameters file enables you to process multiple .idy files.
Note: The parameters file may contain up to a maximum of 100 debug information (.idy) files.
/? or no parameters
Displays command line help.
  • DFSTRCL Examples
Parent topic: Data File Structure Command Line Utility


DFSTRCL Examples

Below are several examples of how DFSTRCL can be used:

  • Example 1
    Demonstrates how to create a record layout (.str) file from a COBOL debug information (.idy) file.
  • Example 2
    Demonstrates how to create a record layout (.str) file with a specified location and name and using a specified record structure.
  • Example 3
    Demonstrates how to batch process multiple information (.idy) files by reading the parameters from a text file.
Parent topic: DFSTRCL Command Line Syntax


Example 1

To run the DFSTRCL utility with an information (.idy) file as a parameter and residential_address as the default record layout, use:

dfstrcl "C:\test layout\customer_address.idy" /d residential_address

Where, DFSTRCL uses the residential_address record layout and outputs a filename allocated by default, in this case customer_address.str.

Parent topic: DFSTRCL Examples


Example 2

To specify a particular record structure as the default if the .idy if it contains multiple record structures:

dfstrcl "C:\test layout\staff.idy" /d clerical_record /o "C:\test data\clerical_staff.str"

This specifies clerical_record as the default record layout where the information file contains multiple record layout structures. The /o parameter specifies a new location and filename for the record layout (.str) file.

Parent topic: DFSTRCL Examples


Example 3

To specify the command line parameters in a text file rather than on the command line:

dfstrcl /r "C:\output definition\output_definition.txt"

The output_definition.txt file contains the following parameters:

information_file_a.idy /d record_one /o "C:\output_one_location\output_one.str
information_file_b.idy /d record_two /o "C:\output_two_location\output_two.str
information_file_c.idy /d record_three /o "C:\output_three_location\output_three.str

This example processes three separate information (.idy) files, each file uses a specific record name, creating three output layout (.str) files.

Parent topic: DFSTRCL Examples


Classic Data File Tools

Data File Converter
You can convert between file organizations and formats. You can convert between EBCDIC and ANSI and, in doing so, convert floating-point formats. You can change the record length.
Record Layout Editor
You can create and maintain the record layouts that enable you to edit and convert formatted data. You can define one default record layout and one or more conditional record layouts. You can also use record layouts to specify which data items to convert when converting between ANSI and EBCDIC.
Data File Editor
You can create data files of various types. Then, use the Data File Editor window to create and delete records and to view, edit and print data. Search tools are provided also.

See Known Errors and Restrictions for issues with the Classic Data File Tools utility.

Attention: We also provide data tools for IMS that enable you to create and maintain segment layouts, and edit and maintain IMS databases. See the Segment Layout Editor and IMS Database Editor topics in the IMS Support section of this documentation.
  • Configuring Classic Data File Tools
  • Data File Converter
    The Data File Converter is a graphical interface for converting data files on your PC.
  • Record Layout Editor
    Describes the Record Layout Editor, which is used to format data file records such that you can edit the records using the Data File Editor.
  • Data File Editor
    The Data File Editor enables you to create and edit data files on your PC.
  • How to
  • Reference
Parent topic: Data Files
Related concepts
Classic Data File Tools
IMS Database Editor
IMS Segment Layout Editor


Configuring Classic Data File Tools

Before using the Classic Data File Tools, we suggest that you configure them to perform best for you. We provide configuration options for the toolset in general, and also several options for the Data File Editor and the IMS Database Editor. See To set Classic Data File Tools options and Data Tools Options dialog box for specific information.

Parent topic: Classic Data File Tools
Related tasks
To set Classic Data File Tools options
Related reference
Data Tools Options dialog box


Data File Converter

You can use the Data File Converter to convert data files between file organizations and formats as follows:

Restructure data
Converting files from one format to another enables you to restructure data. For example, you can convert a data file from sequential organization to indexed or you can add extra secondary indices.
Convert between EBCDIC and ANSI
The Data File Converter provides an easy method for data conversion between EBCDIC and ANSI, thereby removing the need to recreate data already produced or to write special conversion programs. You can also convert internal floating-point formats between S/370 format and IEEE format.
Change record lengths
For non-variable length records, you can specify a new record length. For variable length records, you can change the minimum length and maximum length.
Convert mainframe files downloaded to your PC
You can convert from:
  • Files that have been downloaded to a PC from a mainframe
  • Variable length VRECGEN format to PC data file format
  • PC data file format to VRECGEN2 format for transfer to the mainframe
  • Mainframe fixed length report format to PC print format
  • PC print format to mainframe fixed length report format
  • Convert a blocked variable length file to a sequential file
  • Input File Specifications
  • Output File Specifications
  • Character Set Conversion
Parent topic: Classic Data File Tools
Related concepts
Record Layout Editor
Related tasks
To convert a data file
Related reference
Data File Convert dialog box
Key Information dialog box


Input File Specifications

For each input file, the Data File Converter needs to identify its type and record length. Generally, this information is obtained automatically from either the header in the input file or from a loaded profile (.pro) file. However, some data files do not contain a header, so if you have not created a profile to load the information, you need to specify the file organization and record length manually. We support all of the following file organizations:

  • ANSI Mainframe Report
  • Line Sequential
  • Machine Mainframe Report
  • PC Print
  • Relative - fixed length
  • Sequential - fixed length
  • VRECGEN
  • Blocked VRec
CAUTION:
The Data File Converter supports IDX formats 8 and 12; however they must be unstriped files only. Using the Data File Converter on a stripe of a striped file could cause data corruption.
Parent topic: Data File Converter
Related concepts
Data File Profiles
Opening a Data File
Related tasks
To convert a data file
To define or change file details
To apply a record layout to a file conversion
Related reference
Data File Convert dialog box


Character Set Conversion

When converting between EBCDIC and ANSI, you can do a one-to-one record conversion, or you can optionally specify a record layout to control which record fields to convert. See Record Layout Editor for more information on creating and applying a record layout.

Parent topic: Data File Converter
Related concepts
Record Layout Editor
Related tasks
To convert a data file


Record Layout Editor

The Record Layout Editor enables you to create record layout files. When applied to a data file, a record layout file enables you to:

  • Convert existing data files to use different formats, organizations, and character sets
  • View and edit records at the field level

A record layout file is essentially a template of the Data Division data structures in a COBOL program that are used to send and receive data to and from a data file. When you apply a record layout file to a data file in the Data File Editor, it lays out the data as it is used by the COBOL program, thus enabling you to edit the data within the structures defined in the program. When you apply a record layout file to a data file in the Data File Converter, it converts the records in the data file to conform to the Data Division structures defined in the record layout file and controls which fields in a record are converted.

  • Input
  • Record Layout Types
  • Record Layout Names
  • Output
Parent topic: Classic Data File Tools
Related concepts
Data File Editor
Data File Converter
Creating and Editing Data
Adding Records
Creating and Using a Record Layout File
Related tasks
To start the Record Layout Editor
To create a new record layout file
Related reference
Record Layout Editor window


Input

The Record Layout Editor uses the Data Division of a COBOL program as input for creating a record layout. You can create one or more layouts from each Data Division.

To enable the Record Layout Editor to read the Data Division of a COBOL program, you must first compile the program to produce a debug information (.idy) file that can be read by the Record Layout Editor. The record layouts that you create from the .idy file describe the name, length, and picture of the fields in a data record.

Parent topic: Record Layout Editor
Related tasks
To create a debug information (.idy) file for layout file input
To start the Record Layout Editor


Record Layout Types

From each COBOL Data Division, you can create two types of record layouts: a default record layout, and optionally one or more conditional record layouts depending on your needs. If you do not define any conditional record layouts, all records in the data file adopt the default record layout.

Default record layout
You can define one default record layout for each data file. When applied, a default record layout formats records that do not otherwise meet the conditions specified by a conditional record layout defined in the same record layout file.
Conditional record layout
As well as a default record layout, you can create one or more conditional record layouts. When you create a conditional record layout, you define one or more conditions to apply to one or more fields. When you apply a conditional record layout to a data record, the data that is loaded into the Data File Editor must satisfy all the tests defined for that layout. When viewing a data record that meets the conditions set by the applied record layout, this enables you to narrow the scope of fields that appear in the Data File Editor to those that satisfy the conditions.

When you modify data in a record, the Data File Editor works out automatically which record layout to use for the modified record.

Parent topic: Record Layout Editor
Related tasks
To create a new record layout file
Related reference
New Record Layout wizard


Record Layout Names

A record layout name is constructed from the Data Division data item from which it is created.

Default record layout name
A default record layout name consists of the selected data item name appended with "DEFAULT". For example, if you select a Data Division data item named CUSTOMER-REC as your default record layout, the record layout name is CUSTOMER-REC-DEFAULT.
Conditional record layout names
The name of the first conditional layout created for a data item is always the same as the data item name. Subsequent layouts created for the same data item are appended with a generated number starting with "001" and incremented with each subsequent layout. For example, EM-POSITION, EM-POSITION-001, EM-POSITION-002, and so on.
Parent topic: Record Layout Editor
Related tasks
To create a new record layout file
Related reference
New Record Layout wizard


Output

The default output file name for any new record layout file is Layout.str, and can be saved in a directory of your choice. However, if you follow these conventions, the Data File Editor automatically applies the appropriate record layout file to a data file when you open it for editing:
  • Save the record layout file in the same directory as the data file
  • Name it using the same file prefix as the data file
  • Use the .str file extension
Parent topic: Record Layout Editor
Related tasks
To create a new record layout file


Data File Editor

The Data File Editor enables you to tailor input data files for use in program testing, and view output data files to verify the program is operating correctly. You can edit and view data as records formatted against your program specification, with minimal set-up work.

Using the Data File Editor, you can:

  • View and edit records and fields in a data file
  • Create new data files
  • Look at data using either the ANSI or EBCDIC character sets
  • Search through a data file for a string
  • Create records
  • Delete records
  • Print data
Important: To view and edit a data file that contains formatted data, you must first create a record layout file to apply to the data file. You do this using the Record Layout Editor. The remaining topics in this section assume that formatted data files have a record layout associated with them. See Record Layout Editor for details.
  • Configuring the Data File Editor
  • Creating Data Files
  • Opening a Data File
  • Navigating Data Files
  • Searching a Data File
  • Creating and Editing Data
  • Printing from a Data File
Parent topic: Classic Data File Tools
Related concepts
Record Layout Editor
Creating and Using a Record Layout File
Related tasks
To start Classic Data File Tools
Related reference
Data File Editor window


Configuring the Data File Editor

Data File Editor configuration is done from the Data File Editor tab of the Data Tools Options dialog box.

Warning Prompts

By default, the Data File Editor prompts you for confirmation each time you attempt to:

  • Edit a record
  • Delete a record
  • Open an indexed file
  • Open a relative file
  • Edit data in a sequential file

You can turn these prompts off by unchecking Update warning and Delete warning. Any changes made during an editing session take effect the next time you open a data file. You can also prevent a prompt from appearing again in a current session by checking its Do not show this message again box.

Data File Backup

The Back up file before editing check box controls whether the Data File Editor makes a backup of each data file that you open. By default, the editor creates a backup automatically. You can use the backup to restore the file to the state it was in before you made your edits.

Backup files are kept in the same folder as the data file. Your data file is copied to filename.dbk. If the data file is indexed using a separate index file, the index is copied to filename.ibk.

Restriction: A backup is not taken if you open a Vision file (IDXFORMAT 17).

Open as Read Only

The Open read only check box controls whether you can open data files in read-only mode or edit mode. By default, this option is unchecked, meaning that you can edit data in the file. When checked, you can other processes can read the file, but you cannot change any of its contents.

Note: Regardless of the Open read only setting, you cannot edit a file that has the Windows read-only attribute.

Typing Mode

The Always overtype in unformatted view checkbox controls whether to use Insert or Overtype mode in the left pane of the Data File Editor window. By default, the mode is Overtype. This reduces the possibility of shifting your data fields. You can switch this off during an editing session by pressing Insert. In this case, you are prompted to confirm the switch.

This setting has no effect in the right pane, where you always edit numeric fields in overtype mode and alphanumeric fields in insert mode.

Parent topic: Data File Editor
Related concepts
Editing Data
Related tasks
To set Classic Data File Tools options
Related reference
Data Tools Options dialog box


Creating Data Files

You can use the Data File Editor to create and edit data files of various types, and define keys for indexed files.

  • Data File Types
  • Data File Profiles
  • Key Definitions for Indexed Files
Parent topic: Data File Editor
Related tasks
To create a data file


Data File Types

You can create or specify many types of data files:

Micro Focus Format
The Micro Focus format supports four file organizations:
  • Indexed Sequential
  • Line Sequential
  • Relative
  • Sequential
IDXFORMAT(4)
Standard IDX format 4 files.
IDXFORMAT(8) or IDXFORMAT(12)
The Data File Editor supports IDX format 8 and format 12 indexed files that are larger than 2GB on operating systems that can deal with files of that size; however, support is limited to 2.1 billion records per data file, and is available for unstriped files only.
CAUTION:
Using the Data File Editor on a stripe of a striped file could cause data corruption.

When you specify a data file that uses the IDXFORMAT(8) or IDXFORMAT(12) formats, you must set the FILEMAXSIZE parameter in the File Handler configuration file, extfh.cfg, to FILEMAXSIZE=8 to enable locking, to accommodate the necessary 25 bytes of virtual memory needed per sequential record, and to accommodate both the data and the index of an IDXFORMAT(8) or IDXFORMAT(12) file. For more information about the extfh.cfg file, see File Handler Configuration.

Note: Data File Editor locking behavior prevents other programs from accessing a data file that is open for editing in Data File Editor. If the data file is locked, Data File Editor prompts to try and open the file read only. This does not apply when Open read only configuration option is checked.
Parent topic: Creating Data Files
Related concepts
File Handler Configuration
Related tasks
To create a data file
To set Classic Data File Tools options


Data File Profiles

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.

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 Data File Editor prompts you to create a profile file. When you edit the same data file again, Data File Editor automatically loads the header information contained in the profile file created for that data file. 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.

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.

Parent topic: Creating Data Files
Related concepts
Input File Specifications
Opening a Data File
Related tasks
To open a data file


Key Definitions for Indexed Files

When you create an indexed file, you also define its keys. For each indexed file:

  • Define at least one key
  • Define at least one component for each key
  • For each component, specify a component length. This must be less than 1,016 bytes or the maximum record length, whichever is the smaller.
  • For each component, specify a component offset, which must be less than 63,488 bytes or the minimum record length, whichever is the smaller.

In addition, you can optionally:

  • Specify that a key is non-unique, that is, duplicate key values are allowed.
  • Specify one or more additional keys, adding them before or after the current key. The first key in the list of keys in the Key Information dialog box is always the primary key.
  • Specify one or more additional components, adding them before or after the current component.
  • Delete a key or a component.
  • Apply key compression.
  • Define a particular key as a sparse key; that is, an index entry is not written for any record containing only the sparse character in the key.
Parent topic: Creating Data Files
Related tasks
To open a data file
Related reference
Key Information dialog box


Opening a Data File

To open a data file, Classic Data File Tools must be able to identify the file type and the record type and lengths. For non-indexed files, this information can be read from a profile file, or supplied as prompted. For variable-length sequential or relative files, and for indexed files, this information is read from the file header. See Data File Profiles for more information

Note:
  • You cannot open a data file if you have the Back up file before editing configuration option checked, but do not have sufficient space for the backup file.
  • To avoid modifying data accidentally, you can open a file as read only.
  • Loading and Saving Data Files
  • Determining File Organization
  • Determining Record Lengths
  • Applying Record Layouts
Parent topic: Data File Editor
Related concepts
Input File Specifications
Data File Profiles
Related tasks
To open a data file
Related reference
Data Tools Options dialog box


Loading and Saving Data Files

Sequential Files
As with most files, when you open a sequential file, the Data File Editor loads the file into memory. All changes to the file are stored in memory while you work on it. The file is written to disk when you save or close the file.
Indexed and Relative Files
Because these files can be quite large, the Data File Editor does not load indexed or relative files into memory when opened. Each time you move your cursor off of a modified record, the Data File Editor updates the record on disk. If you have Update warning configuration option checked, you are prompted to confirm the changes.
Parent topic: Opening a Data File
Related tasks
To open a data file
Related reference
Data Tools Options dialog box


Determining File Organization

When opening a sequential file that does not have an associated profile file, you must supply the file organization and record length. To determine the file organization, look at the Data Division of the COBOL program that uses the data file, and under the Input-Output section, look at the SELECT statement. Use the following table to determine the file organization:

SELECT statement contains | File Organization
ORGANIZATION IS SEQUENTIAL | Line sequential
ORGANIZATION IS LINE SEQUENTIAL | Line sequential
LINE SEQUENTIAL | Line sequential
SEQUENTIAL | Line sequential
ORGANIZATION IS RECORD SEQUENTIAL | Fixed-length sequential
RECORD SEQUENTIAL | Fixed-length sequential
ORGANIZATION IS RELATIVE | Fixed-length relative
RELATIVE | Fixed-length relative
Parent topic: Opening a Data File
Related tasks
To open a data file
Related reference
File Formats and Organizations


Determining Record Lengths

To find the record length, look at the record layout described by the FD entry in the File Section of the COBOL program that uses the data file. The record length is the sum of all the lengths of all the elementary data items which make up the FD group item.

Each character position occupies one byte for PIC X and PIC 9 items. To find out how to calculate the length of computational fields (COMP-1, COMP-2, COMP-3, COMP-4, COMP-5 and COMP-X) see Selection of Character Representation and Radix.

Parent topic: Opening a Data File
Related concepts
Selection of Character Representation and Radix
Related tasks
To open a data file


Applying Record Layouts

When the Data File Editor loads a data file, it looks in the current directory for a record layout file with the same prefix, and if found, automatically loads that record layout file and applies it to the data file. To apply a record layout file to a data file that is already open or whose name does not match that of the record layout file, you must load it explicitly.

Parent topic: Opening a Data File
Related tasks
To apply record layouts to a data file


Navigating Data Files

For all types of data files, you can jump directly to a particular position in a file by clicking on the position. The position is defined by a line number and a column number, both of which start at zero, and are displayed in the Data File status bar at the bottom of the Classic Data File Tools main window. If the current record has a record layout, you can also jump directly to a field.

Sequential Files

You can move through the file sequentially, as you would if you read the file sequentially using a COBOL program.

Relative Files

You can alter your position in a file by inserting, repeating, or deleting a record. Before inserting or repeating a record, you must specify an unused relative record number.

Indexed Files

You can alter your position in a file by:

  • Adding a record
  • Altering a key
  • Finding on key
  • Changing the current key of reference

When you alter your position in a relative or indexed file in one of these ways, the line number in the Data File status bar is reset to zero. This is because line numbers in these types of files can only be determined with respect to some given position.

The line number then changes as you move through the file:

  • If you then move backward in the file, the line number decreases by one for each record moved and appears as a negative number.
  • If you move forward in the file, the line number increases by one for each record moved.

To maintain consistency with the line number, the column number also starts from zero.

Parent topic: Data File Editor
Related concepts
Adding Records
Related tasks
To insert records
To view information
To select an alternate key
To search within a data file


Searching a Data File

You can use the search option to look for a particular string in a data file. You can search forwards or backwards through the data file.

Additionally, you can search your file for a particular string and replace it with another specified string. If you enter a replace string that is shorter than the search string, the Data File Editor fills the empty bytes with padding characters. Replace strings longer than the search string are truncated. This is a way of preserving the consistency of field positions within the record.

For indexed files only, you can search on the current key of reference.

Note: When you are searching on a numeric key with COMPUTATIONAL usage, you must specify the hexadecimal value. Data File Editor does not format data specified in the Find on Key dialog box, even where a record layout file exists. This is because a key can be split across several fields which might each have different formatting.
Parent topic: Data File Editor
Related tasks
To search within a data file
Related reference
Data File Find And Replace dialog box
Find on Current Key dialog box
Goto dialog box
Locate Field dialog box


Creating and Editing Data

You use the Data File Editor in the same manner whether you start with a newly created data file or an existing data file.

If you have a record layout file loaded, you can create a new record based on one of the record layout types, or you can specify padding bytes to fill the records. If you have created conditional record layouts and you choose your new record to be one of these, the condition field is set appropriately. For more information about record layouts, see Record Layout Editor.

  • Editing Data
  • Cutting, Copying, and Pasting Data
  • Adding Records
  • Deleting Records
  • Changing the Key in an Indexed File
  • Initializing Data Records and Fields
Parent topic: Data File Editor
Related concepts
Record Layout Editor
Related tasks
To create a data file
To define record keys for an indexed data file
To configure edit warnings


Editing Data

You can use the Data File Editor to edit both unformatted and formatted data, and indexed or non-indexed data.

Note: If a field or record contains invalid data, it represents the invalid data as asterisks (*). If you select such a field or record, the Data File Editor prompts you for an opportunity to initialize it.

Unformatted Data

When you insert or delete data in the unformatted view, you can potentially create a shift in all of your data thereby causing file corruption. To avoid this, we suggest that you check the Always overtype in unformatted view configuration option. For more information, see Configuring the Data File Editor.

Tip: If you have applied a record layout file, you can see the edits made in the unformatted view applied to the formatted view. To do this, click View > Data File Editor > Refresh Formatted Pane.

Formatted Data

In the formatted view, the editing rules depend on whether you are editing alphanumeric or numeric data.

Numeric data
You always edit numeric fields in overtype mode regardless of configuration settings. Numeric fields can accept numeric data only. When you delete numeric data, each digit is set to zero.
Alphanumeric data
You always edit alphanumeric fields in insert mode regardless of configuration settings; however, you can only insert new characters into an alphanumeric field if the field has space for them. For example, if a PIC X(4) field already has four characters in the field, you must delete these and replace them with the new data. When you delete alphanumeric characters without replacing them, the Data File Editor adds spaces to the right edge of the field.

Indexed Data

When editing an indexed file, exercise caution when making changes to key values:

  • Do not change a key in one record to the same value as another unless duplicate key values are allowed. You should not have duplicate primary keys in a file.
  • If you edit a record area containing a key, be careful not to change the logical position of the record in the file.
Parent topic: Creating and Editing Data
Related concepts
Configuring the Data File Editor
Related tasks
To select an alternate key
To initialize a record
To initialize a field
To insert records
To undo a record edit
To append an ESDS record
To change a record length
To delete records
Related reference
IMS Database Editor window


Cutting, Copying, and Pasting Data

You can cut, copy and paste data in your data files. You can also paste data from the clipboard. Data File Editor can store information on the clipboard in two formats:

Binary
This supports the full character set available within the record data.
Text
This replaces nulls with spaces, enabling paste operations in tools that accept text-format blocks.

You can cut, copy, and paste information from one of the following views. The method used depends on the view you are using:

Record view
You can click on complete records to select them for a cut, copy or paste operation, then right-click to display a popup menu from which you can click on the appropriate operation.
Record Hexadecimal view and Field Hexadecimal view
You can select characters for a cut, copy or paste operation, then right-click to display a popup menu from which you can click on the appropriate operation.
Field view
When a field is open for editing, you can select characters for a cut, copy or paste operation, then right-click to display a popup menu from which you can click on the appropriate operation. If the field is a COMP item, you can only select complete fields as the binary characters representing the field are copied to the clipboard.

When pasting a record into an indexed file, you must provide unique record keys. When pasting a record into a relative file, you must provide a unique relative record number.

Parent topic: Creating and Editing Data
Related tasks
To cut, copy, and paste data


Adding Records

The methods for adding records are different for sequential, indexed, and relative files because sequential files do not have keys, and relative and indexed files have different types of keys. Also, special considerations apply to VSAM ES files.

Sequential Files

You can insert a new record either before or after the currently selected record.

You can also create new records by:

  • Copying an existing record once.
  • Copying an existing record many times. This technique is known as multiple repeat. It is a fast way to set up test data in a sequential file.

Indexed Files

You can add a new record to an indexed file by either creating a new record or copying an existing record. The line number displayed in the Data File status bar is reset to zero. For more information, see Navigating Data Files.

When you add an indexed file record, you must specify all unique keys for the new record. The prime key should always be a unique key. In some cases, a file might also have one or more unique alternate keys.

If you are inserting records with record layouts loaded, any key information that you specify during the insert process takes precedence over conditional data associated with the selected record layout. For more information about record layouts, see Record Layout Editor.

Relative Files

You can add a new record to a relative file by either creating a new record or copying an existing record.

When you add a new record, you must provide a relative record number so that Data File Editor can position the new record in the file. The line number displayed in the Data File status bar is reset to zero. For more information, see Navigating Data Files.

If you have not loaded any record layouts, Data File Editor uses the appropriate padding byte and sets the record to:

  • The minimum record length for variable-length files
  • The maximum record length for fixed-length files

VSAM ES Files

You can only create a new record in a VSAM ES file (often known as an ESDS file) by appending an empty record to the end of the file. If the file has alternate indexes, you must also supply any unique key values.

The new record is always positioned physically at the end of the file. If the file has alternate indexes, the empty record appears in the editing window in the position in the file dictated by the key of reference. For more information, see Navigating Data Files.

Once the record has been appended, you specify the field values in an editing session.

Parent topic: Creating and Editing Data
Related concepts
Record Layout Editor
Navigating Data Files
Related tasks
To insert records
To append an ESDS record
To cut, copy, and paste data


Deleting Records

You can delete single or multiple records from any type of data file except for VSAM ES files.

A multiple delete continues to run even if insufficient records are available. The delete continues until the end of the file when a message box displays the number of records deleted.

Note: To help avoid accidental deletion, check the Delete warning configuration option.
Parent topic: Creating and Editing Data
Related tasks
To delete records
Related reference
Data Tools Options dialog box


Changing the Key in an Indexed File

By default, the Data File Editor displays records in an indexed file in primary key order. If the file has alternate keys, you can change the display order by selecting a different key of reference. To select an alternate key for viewing an indexed file, use the Data File Toolbar which shows the currently selected key and character set.

Parent topic: Creating and Editing Data
Related tasks
To select an alternate key
To define record keys for an indexed data file
Related reference
Key Information dialog box


Initializing Data Records and Fields

You can initialize a single field or all the fields in a record. You might want to do this for testing purposes, or to reset a field or record that contains invalid data. Initialization replaces the data in the field or record, changing:

  • Alphanumeric fields to all spaces
  • Numeric fields to all zeros

Initialization does not affect conditions applied to fields by conditional record layouts, nor does it affect indexed record keys.

Parent topic: Creating and Editing Data
Related tasks
To initialize a record
To initialize a field


Printing from a Data File

You can print or preview both unformatted data (left pane) or formatted data (right pane) from the Data File Editor.

Unformatted Data

You can print or preview data records from the left pane. You can print one record, all records, selected records, part of a record, and various other combinations. You can also specify several print options that dictate the information that appears on the preview or printout, including:

  • A header
  • A footer
  • Page numbers
  • A ruler showing byte positions
  • Record numbers
  • Hexadecimal values

When you display a print preview, the Data File status bar shows the page number. You can change the magnification of the display.

CAUTION:
If the size in bytes of the print preview exceeds the available memory, an error occurs; however, no such limitation exists when printing files.

Formatted Data

When you have a record layout associated with a data file, you can print or preview formatted data from the right pane with the same options as those for printing unformatted data, but with the following restrictions:

  • You can only preview or print at the field level if the applied record layout file contains a layout for the record containing the field. For more information, see Record Layout Editor .
  • If, during the printing or previewing process, the Data File Editor determines that a record does not match any of the available layouts or contains an invalid OCCURS DEPENDING ON RANGE statement, the output includes an error message.
  • You cannot print the following:
    • Rulers
    • Record numbers
    • Hexadecimal data
    • Part of a record
Parent topic: Data File Editor
Related concepts
Record Layout Editor
Related tasks
To print from a data file
To preview a data file
Related reference
Print and Preview dialog boxes


How to

  • To start Classic Data File Tools
  • To set Classic Data File Tools options
  • Data File Converter
  • Record Layout Editor
  • Data File Editor
Parent topic: Classic Data File Tools


To start Classic Data File Tools

Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > Classic Data File Tools.
Windows 8.1
  • From the Windows Start screen, click the Classic Data File Tools tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > Classic Data File Tools.
From the Eclipse main menu
  • From the main menu, click Run > Tools > Data Tools > Classic Data File Tools.
From an Eclipse IMS project
  • In the project, right-click a DBD file; then select Open With > IMS Database Editor from the context menu.
Parent topic: How to
Related concepts
Data File Editor
Related tasks
To start the Record Layout Editor
To start the Segment Layout Editor
Related reference
Data File Editor window


To set Classic Data File Tools options

  1. In Classic Data File Tools, click Options > Data File Tools.
  2. Click the tab or tabs required to configure the tool or tools that you use regularly.
  3. Set your required options; then click OK.
Notes:
  • The General tab sets universal options for all data file tools.
  • For a description of each field and control on the Data Tools Options dialog box, see Data Tools Options dialog box.
Parent topic: How to
Parent topic: IMS Database Editor
Related concepts
Configuring Classic Data File Tools
Configuring the Data File Editor
Configuring the IMS Database Editor
Related reference
Data Tools Options dialog box


Data File Converter

  • To convert a data file
  • To define or change file details
  • To define record keys for an indexed data file
  • To apply a record layout to a file conversion
Parent topic: How to


To convert a data file

  1. In Classic Data File Tools, click Tools > Convert.
  2. Type the full path to and filename of the data file you want to convert into the Filename field within the Input file group, or click its corresponding Browse button and use the Open dialog box to select a file to convert.
    Important: If the data file contains a header, or if is has an associated profile, the Data File Converter detects the format and organization of the specified data file. However, if the data file neither contains a header nor has an associated profile, you must supply the information manually. See To define or change file details for instructions.
  3. If the character set used in the data file is not ANSI (default), select EBCDIC from the Character set drop-down list in the Input file group.
  4. To make changes to or provide additional details about the input file, such as the file organization and minimum/maximum record length specifications, click File Details. Optional. See To define or change file details for more information.
  5. If your input file uses record keys, click View keys to view the keys defined in the file. Optional.
  6. If you want to convert the character set from ANSI to EBCDIC or EBCDIC to ANSI, check Convert character set. This changes the value of the Character set field in the New file group, and activates the Records contain non-text data items check box.
  7. If you record contains non-text (numeric) data items, check Records contain non-text data items. This activates the Select layout for conversion button, enabling you to apply a record layout file. For more instructions, see To apply a record layout to a file conversion.
  8. In the Filename field within the New file group, type an output file name or click the corresponding Browse button and use the Open dialog box to select a file.
  9. From the Format drop-down list, select a format for the output file.
  10. From the Organization drop-down list, select an organization for the output file.
  11. If your output file organization is indexed, click Define Keys to define the index specifications. See Key Information dialog box for more information.
  12. If you want your output file to contain fixed-length records, specify the record length in the Maximum length field.
  13. If you want your output file to contain variable-length records, check Variable length records; then provide a Minimum length and a Maximum length.
  14. If you want the data records in your output file to be compressed, check Compress data records.
  15. To save the settings specified on the Data File Convert dialog box, click Save profile and specify a file name and location for the profile file. Optional.
  16. Click Convert.
  17. Click OK on the message saying the data file conversion is complete.
  18. Click Cancel.
Note: Alternatively, if you have saved previous specifications as a profile, click Load profile to load the specifications automatically.
Parent topic: Data File Converter
Related concepts
Data File Converter
Input File Specifications
Output File Specifications
Character Set Conversion
Related tasks
To define or change file details
To apply a record layout to a file conversion
Related reference
Data File Convert dialog box
Key Information dialog box


To define or change file details

  1. Do one of the following:
    • If the File Details dialog box has opened automatically from the Data File Converter, continue to step 2.
    • From the Data File Converter, select a line sequential, fixed-length sequential, or fixed-length relative data input file; then click File Details.
  2. From the File organization drop-down list, select the file organization of the data input file.
  3. Do one of the following:
    • For fixed-length file organizations, type the record length into the Maximum length field.
    • For variable-length file organizations, type the minimum record length into the Minimum length field, and the maximum record length into the Maximum length field.
  4. Click OK. This returns you to the Data File Convert dialog box to continue with the conversion.
Parent topic: Data File Converter
Related concepts
Input File Specifications
Related tasks
To convert a data file
Related reference
File Details dialog box


To define record keys for an indexed data file

  1. From either the Data File Convert or the Create file dialog box, click Define Keys.
  2. On the Key Information dialog box, click Insert Key. This creates a Prime Record Key.
  3. Click Prime Record Key on the tree view.
  4. Define the key using the fields and controls in the Key Compression and Key Options groups. For information on each field and control, see Key Information dialog box.
  5. To define a key component, select the component from the tree view; then complete the fields in the Key Component group. For information on each field, see Key Information dialog box.
  6. To insert an alternate key, click Prime Record Key on the tree view; then click Insert Key Before or Insert Key After.
  7. To insert an additional key component, select a component on the tree view; then click Insert Component Before or Insert Component After.
  8. If you have inserted an alternate key and/or an additional component, define each as you did for the Primary Record Key and its component(s).
  9. To delete a key or a component, select it on the tree view; then click Delete Item.
  10. To save your changes and close the Key Information dialog box, click OK.
Parent topic: Data File Converter
Parent topic: Data File Editor
Related concepts
Creating and Editing Data
Changing the Key in an Indexed File
Related tasks
To select an alternate key
Related reference
Key Information dialog box


To apply a record layout to a file conversion

  1. Create a record layout file that contains the record layout you want to apply. See To create a new record layout file for instructions.
  2. In the Data File Converter, check Convert character set and Records contain non-text data items.
  3. Click Select layout for conversion.
  4. In the Filename field, type the full path to and filename of the record layout file that contains the record layout you want to apply, or click Browse and use the Open dialog box to select a file.
    Note: Record layout files have a .str file extension.
  5. If your data contains floating-point data items that you want to convert, check Convert floating point data items; then select a conversion specification from the drop-down list.
  6. Click OK.
Parent topic: Data File Converter
Related concepts
Input File Specifications
Related tasks
To convert a data file
To create a new record layout file
Related reference
Select Layout for Conversion dialog box


Record Layout Editor

  • To create a debug information (.idy) file for layout file input
  • To start the Record Layout Editor
  • To create a new record layout file
  • To load program information
  • To define record layouts
  • To define or edit a condition for a conditional layout
  • To edit an existing record layout file
  • To view layout information in the Layout Editor window
Parent topic: How to


To create a debug information (.idy) file for layout file input

  1. In Eclipse, open an Enterprise Developer project that contains the COBOL program(s) on which you want to base a record layout file.
  2. On the project's COBOL properties page, check Compile for debugging; then save the project. By default, Enterprise Developer automatically builds the project, and automatically generates an .idy file for each program in the project.
Note: Enterprise Developer writes .idy files to the output directory specified in your project properties.
Parent topic: Record Layout Editor
Parent topic: IMS Segment Layout Editor
Related concepts
Input
IMS Segment Layout Editor
Input
Related tasks
To start the Record Layout Editor
To create a new record layout file
To load program information
To start the Segment Layout Editor
To create a new segment layout file
To load program information


To start the Record Layout Editor

To start the Record Layout Editor from your Enterprise Developer project:

  1. In Eclipse, open the project that contains your COBOL program.
  2. In the Project Explorer, expand the COBOL Programs folder to show the COBOL programs in the project.
  3. Right-click the COBOL program that contains the Data Division on which you want to base your new record layout file; then select Create Record Layout File from the context menu.
    Note: In Application Explorer view, ensure that you have built your project before trying to start the record layout editor.

To start the Record Layout Editor in Classic Data File Tools:

  1. In Classic Data File Tools, click File > New > Record Layout; then click OK.
  2. Navigate to the folder that contains the .idy file created from your COBOL program.
  3. Select the .idy file; then click Open.
Parent topic: Record Layout Editor
Related concepts
Record Layout Editor
Input
Related tasks
To create a debug information (.idy) file for layout file input
To create a new record layout file
To load program information
To start Classic Data File Tools
Related reference
Record Layout Editor window


To create a new record layout file

  1. Create a debug information file for the program containing the data division you want to use for the new record layout file. See To create a debug information (.idy) file for layout file input for instructions.
  2. Start the Record Layout Editor. See To start the Record Layout Editor for instructions.
  3. To define one or more record layouts, see To define record layouts.
  4. Click File > Save to save the new record layout file.
  5. Click File > Close to close the Record Layout Editor.
Parent topic: Record Layout Editor
Related concepts
Record Layout Editor
Record Layout Types
Record Layout Names
Output
Related tasks
To create a debug information (.idy) file for layout file input
To start the Record Layout Editor
To define record layouts
To apply a record layout to a file conversion
Related reference
Record Layout Editor window
New Record Layout wizard


To load program information

  1. Generate an .idy debug information file for the COBOL program that contains the Data Division you want to load. See To create a debug information (.idy) file for layout file input for instructions.
  2. Start the Record Layout Editor. See To start the Record Layout Editor for instructions.
  3. Right-click inside the Record Layout Editor window; then select Load Program Information from the context menu.
  4. Locate the .idy file that contains the Data Division from which you want to extract layouts.
  5. Click Open.

    The Record Layout Editor loads the Data Division of the selected COBOL file into the left pane of the Record Layout Editor window.

Parent topic: Record Layout Editor
Related tasks
To create a debug information (.idy) file for layout file input
To start the Record Layout Editor


To define record layouts

  1. In the Record Layout Editor with a Data Division loaded, expand the structure tree in the left pane; then and select a data item for which you want to create a record layout.
  2. Right-click the data item; then select New Layout from the context menu. This starts the New Record Layout wizard.
  3. Select either Default Layout or Conditional Layout; then click Next.
  4. Click Finish.
  5. Create additional layouts as required.
Note:
  • To delete a record layout, right-click it in the right pane of the Record Layout Editor; then click Delete.
  • Each record layout file may define one default record layout.
  • For each conditional layout, you must define one or more conditions.
Parent topic: Record Layout Editor
Related tasks
To create a new record layout file


To define or edit a condition for a conditional layout

  1. In the right pane of the Layout Editor, expand a conditional segment layout until you can see the field that you want to use as the test field.
  2. Right-click the test field; then select Properties from the context menu.
  3. From the IF drop-down list, select the type of test you want to define.
  4. In the box to the right of the IF field, type in a value. If you are using a test that requires two values, type a second value into the box to the right of AND.
  5. If you want to use this layout with the Data File Converter, optionally check Convert to convert the character set. When checked, the Layout Editor adds a check mark * to the conditional field icon.
  6. Click OK.

    The Layout Editor window adds an * to the conditional field icon.

Parent topic: Record Layout Editor
Parent topic: IMS Segment Layout Editor
Related concepts
Data File Converter
Related tasks
To edit an existing segment layout file
Related reference
Field Properties dialog box


To edit an existing record layout file

  1. In Classic Data Tools, click File > Open.
  2. From the Files of type list, select Record Layout Files (*.str).
  3. Locate the file in its folder; then click Open.
    The Record Layout Editor shows only the record layouts already defined in the current record layout file. From here, you can:
    • Define new conditions
    • Edit existing conditions
    • Create additional layouts
      Note: To create additional layouts, you must first load a Data Division.
  4. When you have finished, click File > Save .
Parent topic: Record Layout Editor


To view layout information in the Layout Editor window

To switch the Header Information and COBOL Header bars on and off
Right-click in the right pane of the Layout Editor window; then select Header Information from the context menu.
To view the properties set up for a conditional field
Hover over the * icon that corresponds to the field.
To view all the conditions defined for a conditional layout
Hover over the folder icon * that corresponds to the layout.
To view the state of a layout
Select the layout; then hover over the * icon in the Header Information Bar.
Parent topic: Record Layout Editor
Parent topic: IMS Segment Layout Editor
Related reference
Record Layout Editor window
IMS Segment Layout Editor Window


Data File Editor

  • To configure edit warnings
  • To create a data file
  • To define record keys for an indexed data file
  • To open a data file
  • To apply record layouts to a data file
  • To associate a record layout file with a data file
  • To view information
  • To select an alternate key
  • To search within a data file
  • To initialize a record
  • To initialize a field
  • To insert records
  • To cut, copy, and paste data
  • To undo a record edit
  • To append an ESDS record
  • To change a record length
  • To delete records
  • To print from a data file
  • To preview a data file
Parent topic: How to


To configure edit warnings

To turn edit warnings on or off as the default
  1. In Classic Data File Tools, click Options > DataTools.
  2. To configure warnings for the Data File Editor, click the Data File Editor tab.
  3. To turn on the Delete and/or Update warning messages, check the appropriate box(es).
  4. To turn off the Delete and/or Update warning messages, uncheck the appropriate box(es).
  5. Click OK.
Important: Changes take effect the next time you open a data file. Therefore, new settings do not take effect for any currently open files.
To turn off edit warnings for the current editing session
  • When an edit warning prompt appears, check the Switch warning off box before responding to the prompt.
Parent topic: Data File Editor
Related concepts
Creating and Editing Data
Creating and Editing Data
Related reference
IMS Database Editor window
Data Tools Options dialog box


To create a data file

  1. In Classic Data File Tools, click File > New.
  2. Select Data File; then click OK.
  3. In the Filename field, type the full path to and filename of the new file, or click Browse and use the Save As dialog box to select a directory and specify a filename.
  4. Complete the remaining fields and controls as required. For a description of each field and control, see Create file dialog box.
  5. Click Create.
    Note: If you have specified a line sequential, or a fixed-length sequential or relative file, you are prompted to save the file header details you have just entered. If you click Yes, the file details are saved in a profile file in the same directory as the data file, using the same file prefix as the data file, plus a .pro extension. The profile enables you to open a line sequential, or a fixed-length sequential or relative file, without having to specify its details. In other data file organizations, the Data File Editor loads the data file details from its file header.
  6. Add, copy, insert, delete, and edit records as required. See Creating and Editing Data for details.
  7. Click File > Save.
Parent topic: Data File Editor
Related concepts
Creating Data Files
Data File Types
Creating and Editing Data
Related reference
Create file dialog box


To open a data file

  1. In Classic Data File Tools, click File > Open.
  2. Use the Open dialog box to select and open a data file.
  3. If the data file does not have a file header, and it has no associated profile file, complete the fields on the Data File Editor dialog box; then click OK. See Opening a Data File for more information.
Note: Fixed- or variable-length indexed, and variable-length sequential or relative files contain file information headers.
Parent topic: Data File Editor
Related concepts
Data File Profiles
Opening a Data File
Loading and Saving Data Files
Key Definitions for Indexed Files
Determining File Organization
Determining Record Lengths
Related tasks
To associate a record layout file with a data file


To apply record layouts to a data file

  1. From the Data File Editor, click File > Data File Editor > Load Record Layouts.
  2. Use the Open dialog box to locate and open a .str record layout file.
Parent topic: Data File Editor
Related concepts
Applying Record Layouts
Related tasks
To associate a record layout file with a data file


To associate a record layout file with a data file

  1. Open a data file in the Data File Editor. See To open a data file for instructions.
  2. Load the record layout file that contains the layouts you want to use with the data file. See To apply record layouts to a data file for instructions.
  3. Select File > Data File Editor > Associate Record Layouts and use the Open dialog box to locate and select a record layout to associate.
Note: When you subsequently open this project and data file, the associated record layout loads automatically.
Parent topic: Data File Editor
Related tasks
To open a data file
To apply record layouts to a data file


To view information

  • From the Data File Editor, click View > Data File Editor; then select one of the following options from the context menu:
    File Information
    To view details about the current data file.
    Synchronize Views
    To see the same part of the data file in both formatted and unformatted panes.
    Refresh Formatted Pane
    To refresh the formatted pane after editing data in the unformatted pane.
    Show Hex
    To display hexadecimal values at the bottom of the Data File Editor.
Parent topic: Data File Editor
Related concepts
Navigating Data Files


To select an alternate key

Alternate record keys are available only for indexed data files. You can created Indexed files using the Data File Editor or the Data File Converter where you can also define alternate keys. See To define record keys for an indexed data file for instructions.

From the Data File Editor window, click the Prime Key drop-down list and select an alternate key.
Parent topic: Data File Editor
Related concepts
Navigating Data Files
Editing Data
Changing the Key in an Indexed File
Related tasks
To define record keys for an indexed data file
Related reference
Key Information dialog box


To search within a data file

  • From the Data File Editor, click Search > Data File Editor; then select one of the following options from the context menu:
    Data File Find and Replace
    To perform searches and replace strings in the current data file. See Data File Find And Replace dialog box for details.
    Find on Current Key
    To find a record in an indexed file using its record key.
    Goto Record
    To go to a particular record in a file by specifying a column number and line number.
    Locate Field
    To locate a field by providing the field name.
Parent topic: Data File Editor
Related concepts
Navigating Data Files
Searching a Data File
Related reference
Data File Find And Replace dialog box
Find on Current Key dialog box
Goto dialog box
Locate Field dialog box


To initialize a record

  1. In the unformatted view of the Data File Editor, select a record to initialize.
  2. Click Edit > Data File Editor > Initialize Record.
Note: If you have applied a record layout file, you can also initialize an entire record by clicking anywhere in the formatted view and selecting Edit > Data File Editor > Initialize Record.
Note: If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
Parent topic: Data File Editor
Related concepts
Editing Data
Initializing Data Records and Fields
Related tasks
To configure edit warnings


To initialize a field

  1. In the formatted view in the Data File Editor, click on a field you want to initialize.
  2. Click Edit > Data File Editor > Initialize Field.
Parent topic: Data File Editor
Related concepts
Editing Data
Initializing Data Records and Fields


To insert records

  1. In the Data File Editor unformatted view, select a record.
  2. Click Edit > Data File Editor; then, depending on your file type, select one of the following options:
    Insert Record Before
    Inserts a record immediately before the selected record. Sequential and line sequential files only.
    Insert Record After
    Inserts a record immediately after the selected record. Sequential and line sequential files only.
    Insert Indexed Record
    Inserts a record with a unique prime key. If you have applied record layouts, you can select a record layout to use to initialize the new record. Indexed files only.
    Insert Relative Record
    Inserts a record using user-specified and previously unused relative record number.
    Repeat Record
    Inserts a new record, duplicating the information in the selected record. For indexed and relative files, you must provide a unique prime key or a relative record number respectively.
    Multi Repeat Records
    Inserts the same record multiple times. You specify the number of times to repeat the record. Sequential and line sequential files only.
Parent topic: Data File Editor
Related concepts
Navigating Data Files
Editing Data
Adding Records


To cut, copy, and paste data

  1. Select the data you want to cut or copy.
  2. Right-click; then select Cut or Copy from the context menu.
  3. Do one of the following:
    • Place your cursor in the position within the data where you want to add the data on the clipboard.
    • Select the data you want to replace with the data on the clipboard.
  4. Right-click; then select Paste from the context menu.
Note: When pasting, if you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
Parent topic: Data File Editor
Parent topic: IMS Database Editor
Related concepts
Cutting, Copying, and Pasting Data
Adding Records
Related tasks
To configure edit warnings


To undo a record edit

  • In the Data File Editor, before clicking away from the record or field you have just edited, click Edit > Data File Editor > Undo Record Edit.
Note: This action undoes just the last key stroke. To undo multiple key strokes, repeat the action as many times as necessary to back out your changes. As an alternative to Edit > Data File Editor > Undo Record Edit, you can press Ctrl+Z.
Parent topic: Data File Editor
Related concepts
Editing Data


To append an ESDS record

  1. In the Data File Editor unformatted view of an ESDS file, position your cursor after the last record in the file.
  2. Click Edit > Data File Editor > Append ESDS Record.
  3. If you have applied record layouts, select a record layout to format the new record; then click OK.
Parent topic: Data File Editor
Related concepts
Editing Data
Adding Records


To change a record length

Note: This topic applies to variable-length data files only.
  1. In the Data File Editor unformatted view, select a record.
  2. Click Edit > Data File Editor > Set Record Length.
  3. In the New record length field, type a number that represents a valid value; then click OK.
Note: If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
Parent topic: Data File Editor
Related concepts
Editing Data
Related tasks
To configure edit warnings


To delete records

  1. In the Data File Editor unformatted view, select a record.
  2. Click Edit , depending on your file type, > Data File Editor; then select one of the following options:
    Delete Record
    Deletes the selected record.
    Multi Delete Record
    Deletes the number of records you specify, starting with the selected record.
Note: If you have the Delete warning option checked, click Yes to enable deletion. See To configure edit warnings for more information.
Parent topic: Data File Editor
Related concepts
Editing Data
Deleting Records
Related tasks
To configure edit warnings
Related reference
Data Tools Options dialog box


To print from a data file

  1. From the Data File Editor window, click File > Print.
  2. Configure the print output using the fields and controls on the Print dialog box. For a description of each field and control, see Print and Preview dialog boxes.
  3. Click Print.
  4. Use the default Print dialog box to make any necessary printer setup specifications; then click OK.
Parent topic: Data File Editor
Related concepts
Printing from a Data File
Related reference
Print and Preview dialog boxes


To preview a data file

  1. From the Data File Editor window, click File > Print Preview.
  2. Configure the preview page using the fields and controls on the Preview dialog box. For a description of each field and control, see Print and Preview dialog boxes.
  3. Click Preview.
  4. Use the button bar to page through the preview and zoom in and out. Optional.
  5. To print the file, click Print; then follow the steps provided in To print from a data file starting with step 2.
  6. Click Close.
Parent topic: Data File Editor
Related concepts
Printing from a Data File
Related reference
Print and Preview dialog boxes


Reference

  • File Formats and Organizations
  • The Classic Data File Tools Command Line Utility
  • User Interface Reference
Parent topic: Classic Data File Tools


File Formats and Organizations

The following are supported file formats and organizations available for Classic Data File Tools, including define key requirements, and minimum record length requirements for each variable record format.

Format | Organization | Record length | Define keys? | Specify min length?
Micro Focus | Sequential | Fixed or Variable | No | Yes if record format is variable.
Micro Focus | Line sequential | Variable | No | No
Micro Focus | Indexed | Fixed or Variable | Yes | Yes if record length is variable. The minimum length must exceed the largest offset plus key length combination defined for this file.
Micro Focus | Relative | Fixed or Variable | No | Yes if record length is variable.
IDXFORMAT(4) | n/a | Fixed or Variable | Yes | Yes if record length is variable. The minimum length must exceed the largest offset plus key length combination defined for this file.
IDXFORMAT(8) | n/a | Fixed or Variable | Yes | Yes if record length is variable. The minimum length must exceed the largest offset plus key length combination defined for this file.
IDXFORMAT(12) | n/a | Fixed or Variable | Yes | Yes if record length is variable. The minimum length must exceed the largest offset plus key length combination defined for this file.
Parent topic: Reference
Related concepts
Determining File Organization
Related reference
Create file dialog box


The Classic Data File Tools Command Line Utility

The Classic Data File Tools Command Line Utility enables you to invoke the Classic Data File Tools UI, ready to perform certain specific tasks. You can open data files, specifying certain file attributes (depending on the file organization), create record layout files, or you can perform specific tasks relating to an IMS database.

  • Using the Data File Editor Command Line Utility
  • Using the IMS Database Editor Command Line Utility
  • Command Line Examples
Parent topic: Reference


Using the Data File Editor Command Line Utility

From an Enterprise Developer command prompt, you can invoke the Data File Editor using the following syntax:

mfdatatools [file-type] [file-name] [/org org-type] [/reclen record-length] [/charset char-set]
file-type
Can be one of
/data
Use this type if you are opening an existing data file. You must specify this if you are also supplying any of the additional data file attributes (organization, record length and character set). This option may be omitted if you are not supplying additional data file attributes.
/create_str
Use this type to create a new record layout file (.str file).
file-name
The (path name and) file name of the file to open or create. If you are opening a data file or record layout file, you must specify a valid .dat or .str file. If you are creating a record layout file, you must specify the (path name and) file name of a valid debug information file (.idy file).
/org org-type
The organization of the data file being opened. org-type can be one of:
option | description
seq | sequential
lseq | line sequential
rel | relative
Note: For data file types that contain a file header (for example, indexed), you do not need to specify this parameter.
If you specify this parameter, you must also specify the /data file-type.
/reclen record-length
The record length. (This is the maximum record length if the organization is relative.)
Note: For data file types that contain a file header (for example, indexed), you do not need to specify this parameter.
If you specify this parameter, you must also specify the /data file-type.
/charset char-set
The character set of the data within the file. char-set can be either ansi or ebcdic.
Note: For data file types that contain a file header (for example, indexed), you do not need to specify this parameter.
If you specify this parameter, you must also specify the /data file-type.

Comments:

If you run mfdatatools without any additional parameters, Classic Data File Tools starts without any opened files.

Parent topic: The Classic Data File Tools Command Line Utility
Related information
Using the IMS Database Editor Command Line Utility
Command Line Examples


Using the IMS Database Editor Command Line Utility

From an Enterprise Developer command prompt, you can invoke the IMS Database Editor using the following syntax:

mfdatatools [file-type] [file-name] [/imslib imsgenpath] [/imsdat imsdatabasepath] [/acblib path]
file-type
Can be one of:
/create_slf
Use this type to create a segment layout file (.slf). If you specify this option, you must also specify the /imslib option.
/dbd dbdname
Use this type to open a database from a DBD file. If you specify this option, you must also specify the /imslib and /imsdat options.
/psb psbname
Use this type to open a database from a PSB file. If you specify this option, you must specify the file name without the file extension, also you must specify the /imslib and /imsdat options.
file-name
The (path name) and file name of the debug information file (.idy) file. Specify this option only when creating a segment layout file (option /create_slf).
/imslib imsgenpath
The location of DBDGEN2.DAT, DBDGEN2F.DAT and PSBGEN3.DAT files. This is the equivalent of setting the ES_IMSDAT environment variable; if this variable is already set, you do not need to specify this parameter.
/imsdat imsdatabasepath
The location of the IMS DB files. This is the equivalent of setting the ES_IMSLIB environment variable; if this variable is already set, you do not need to specify this parameter.
/acblib path
The location of IMS ACB files. This is the equivalent of setting the ES_ACBLIB environment variable; if this variable is already set, you do not need to specify this parameter.
If this parameter is omitted, the path name specified for /imslib is used.

Comments:

If you run mfdatatools without any additional parameters, the IMS Database Editor UI is displayed without any file opened.

Parent topic: The Classic Data File Tools Command Line Utility
Related information
Using the Data File Editor Command Line Utility
Command Line Examples


Command Line Examples

Use the following commands from an Enterprise Developer command prompt to perform specific operations relating to Classic Data File Tools.

Data File Editor

The following example opens a data file:

mfdatatools c:\dats\dfdaccount.dat

The following example opens a sequential data file, using a maximum record length of 350 characters, and using the EBCDIC character set:

mfdatatools /data c:\dats\dfdstaff.dat /org seq /reclen 350 /charset ebcdic

The following example opens a record layout file:

mfdatatools c:\dats\dfdstaff.str

The following example opens the Layout editor, enabling you to create a new record layout file from the debug information file specified:

mfdatatools /create_str c:\projects\dft\dfdstaff.idy

IMS DB Editor

The following example opens a segment layout file:

mfdatatools c:\projects\dft\demo03dd.slf

The following example opens the IMS DB Editor, enabling you to create a segment layout file from the debug information file specified:

mfdatatools /create_slf c:\projects\dft\demo001t.idy /imslib c:\ims\

The following example opens a database in the IMS DB Editor, using the DBD file specified:

mfdatatools /dbd demo03dd /imslib c:\ims\ /imsdat c:\ims\ /acblib c:\ims\

The following example opens a database in the IMS DB Editor, using the PSB file specified:

mfdatatools /psb demo001t 3 /imslib c:\ims\ /imsdat c:\ims\ /acblib c:\ims\
Parent topic: The Classic Data File Tools Command Line Utility
Related information
Using the Data File Editor Command Line Utility
Using the IMS Database Editor Command Line Utility


User Interface Reference

  • Data Tools Options dialog box
  • Data File Converter
  • Record Layout Editor
  • Data File Editor
Parent topic: Reference


Data Tools Options dialog box

General tab
Character set
Select a default the character set for data files
EBCDIC padding byte
Specify a character to use as the EBCDIC padding byte. The hexadecimal equivalent is shown directly below.
ANSI padding byte
Specify a character to use as the ANSI padding byte. The hexadecimal equivalent is shown directly below.
Data File Editor tab
Back up file before editing
Check this to ensure that files are automatically backed up on opening
Open read only
Check this to open files as read only
Always overtype in unformatted view
Check this to specify overtype editing for unformatted view
Update warning
Check this to see a warning message before you update a file
Delete warning
Check this to see a warning message before you delete a record
Show please note message
Check to show low-priority messages
Offsets (from 0)
Select to count offsets from the 0-byte position
Position (from 1)
Select to count offsets from the 1st byte position
IMS DB Editor tab
Update warning
Check this to turn on update warnings during editing sessions.
Delete warning
Check this to turn on delete warnings during editing sessions.
Number of segments per browser page
Specify the number of segments to show on each Segment Browser page.
Parent topic: User Interface Reference
Related concepts
Configuring Classic Data File Tools
Configuring the Data File Editor
Deleting Records
Related tasks
To set Classic Data File Tools options
To delete records
To configure edit warnings


Data File Converter

  • Data File Convert dialog box
  • File Details dialog box
  • Key Information dialog box
  • Select Layout for Conversion dialog box
Parent topic: User Interface Reference


Data File Convert dialog box

Input file group
Filename
Type the full path to and filename of the input file to convert, or click Browse to use the Open dialog box to select a file.
Format
Shows the format of the input file
Character set
Select the character set of the input file
File details
Define details for the specified input file
Organization
Shows the organization of the input file
View keys
View the keys for the specified input file, if indexed
Character set conversion group
Convert character set
Convert the character set used in the input file from ANSI to EBCDIC or from EBCDIC to ANSI for the output file, depending on the value of the Character set field; activates the Records contain non-text data items check box
Select layout for conversion
Specify the record layout file to apply to records in the input file
Records contain non-text data items
Check when records contain numeric data items; activates the Select layout for conversion button that enables you to apply a record layout when necessary
New file group
Filename
Type the full path to and filename of the output file, or click Browse to use the Open dialog box to select a file.
Format
Lists available formats for the output file
Character set
Shows the output file character set; changes when Convert character set is checked
Organization
Lists available organizations for the output file
Define keys
Specify the details of keys required for an output file of an indexed organization
Variable length records
Check to specify that the output file has variable length records; unckeck to specify that the output file has fixed length records
Minimum length
Specify the minimum record length for variable length records in the output file
Maximum length
Specify the maximum record length in the output file
Compress data records
Check to compress data records in the output file
Load profile
Load specifications from an existing profile
Save profile
Save specifications to a profile
Convert
Create an output file from the input file using the specifications on this dialog box
Parent topic: Data File Converter
Related concepts
Data File Converter
Input File Specifications
Related tasks
To convert a data file


File Details dialog box

File organization
Select the file organization to be used to open the file
Minimum length
Specify the minimum record length for variable length records in file
Maximum length
Specify the maximum record length in the file
Parent topic: Data File Converter
Related tasks
To define or change file details


Key Information dialog box

Key Information tree
Shows the key information for the input file
Key compression group
Leading characters
Shows whether identical leading characters in the selected key are compressed
Trailing spaces
Shows whether trailing spaces in the selected key are compressed
Duplicates
Shows whether duplicate key values for the selected key are compressed
Key options group
Duplicate keys allowed?
Shows whether duplicate values are allowed for the selected key
Sparse Key?
Shows whether the selected key is a sparse key
Sparse character
Active when Sparse Key? is checked, and shows the character that indicates a sparse key value in either ANSI or EBCDIC depending on the selection from the drop-down list.
Key Component group
Key Offset
Specify the number of offset bytes for the key selected on the Key Information tree.
Key Length
Specify the length for the key selected on the Key Information tree.
Manipulate Keys and Components group
Insert Key Before
Insert a new key before the key selected on the Key Information tree.
Insert Key After
Insert a new key after the key selected on the Key Information tree.
Insert Component Before
Insert a new component before the component selected on the Key Information tree.
Insert Component After
Insert a new component after the component selected on the Key Information tree.
Delete Item
Delete the key or component selected on the Key Information tree.
Parent topic: Data File Converter
Parent topic: Data File Editor
Related concepts
Data File Converter
Key Definitions for Indexed Files
Changing the Key in an Indexed File
Related tasks
To convert a data file
To select an alternate key
To define record keys for an indexed data file
Related reference
Create file dialog box


Select Layout for Conversion dialog box

Filename
Type the full path to and filename of a record layout filename to use for output file records, or click Browse to use the Open dialog box to select a file.
Convert floating point data items
Check to select a conversion type for floating point data items
Parent topic: Data File Converter
Related tasks
To apply a record layout to a file conversion


Record Layout Editor

  • Record Layout Editor window
  • New Record Layout wizard
  • Field Properties dialog box
Parent topic: User Interface Reference
Related concepts
Character Set Conversion
Printing from a Data File


Record Layout Editor window

Data Structures View
Structures from filename
Shows the name of the COBOL file that contains the Data Division structures shown in the lower part of the pane.
Tree view
Shows the loaded Data Division structures.
Layout view
Header Information Bar
Provides information about the status of the layout file and is made up of the following items:
Indicates that no layouts have been defined for the item selected in the left pane.
Indicates that the selected layout is usable.

Indicates that the selected conditional layout requires a defined condition.
No Layouts
No layouts are defined.
Layouts n
Indicates the number of layouts defined.
No Conditions
No conditions are defined.
Conditions n
Indicates the number of conditions defined for the selected layout.
ANSI
Indicates that the layout was created from a COBOL file that uses the ANSI character set.
EBCDIC
Indicates that the layout was created from a COBOL file that uses the EBCDIC character set.
Layout Indicators
Default layout.
Conditional layout.
Field with no defined condition and without conversion.
Field with a defined condition but no conversion.
Field with conversion but no defined condition.
Field with a defined condition and with conversion.
Parent topic: Record Layout Editor
Related concepts
Record Layout Editor
Related tasks
To start the Record Layout Editor
To create a new record layout file
To view layout information in the Layout Editor window


New Record Layout wizard

Default Layout
Create a default layout for the selected record.
Conditional Layout
Create a conditional layout for the selected record.
Parent topic: Record Layout Editor
Related concepts
Record Layout Types
Record Layout Names
Related tasks
To create a new record layout file


Field Properties dialog box

Name
The name of the selected field.
Range
Shows the position and length of the field within the layout. The first character is the position of the first byte of the field counting from one and the second digit is the length of the field.
Character set
Shows the character set of the field.
Convert
When this record layout is applied, convert the character set of the record.
Condition group
Build the condition you want to apply to this layout. Hex values show below the dotted line in each condition box.
Parent topic: Record Layout Editor


Data File Editor

  • Data File Editor window
  • File Information dialog box
  • Create file dialog box
  • Key Information dialog box
  • Data File Editor dialog box
  • Print and Preview dialog boxes
  • Data File Find And Replace dialog box
  • Find on Current Key dialog box
  • Goto dialog box
  • Locate Field dialog box
  • Set record length dialog box
Parent topic: User Interface Reference


Data File Editor window

ANSI / EBCDIC
Use the drop-down list to select a character set for the data file.
Prime Key
Use the drop-down list to select a different key of reference for an indexed file.
IEEE / IBM 390
Use the drop-down list to select the floating-point data format contained within the records, either IEEE or IBM 390 floating point for COMP-1 and COMP-2 fields.
Note: You cannot edit a floating-point field from the Layout view.
Invokes the File Information dialog box.
Data view
Lists the contents of each record in the data file. Key areas in an indexed file are shown in red. If a record layout file has been applied, select a record in this pane to edit its fields in the right pane.
Hexadecimal view
Located at the bottom of the window, this shows selected data in hexadecimal. Key areas in an indexed file are shown in red.
Note: In the Data File Editor, this is visible only when View > Data File Editor > Show Hex is checked.
Layout view

Layout view
This pane shows on the right, and only when a layout file has been applied.
Layout status bar
Displays the name of the layout applied, and its status. Use the up and down arrows on the far right to scroll through the list in the left pane.
Indicates that the selected layout is usable.

Indicates that the layout is in error.
Message
Describes the layout status, including error messages.
Field indicators
Field with no defined condition and without conversion.
Field with a defined condition but no conversion.
Field with conversion but no defined condition.
Field with a defined condition and with conversion.
Field contains invalid data.
Field Name
Shows the name of the COBOL field that corresponds to the selected data item.
Format
Shows the COBOL picture clause defined for each field.
Value
Shows the value assigned to the field from the selected record. This field is editable.
Parent topic: Data File Editor
Related concepts
Data File Editor
Related tasks
To start Classic Data File Tools


File Information dialog box

PC File tab
Shows information about the current data file.
Keys tab
Shows key and component information for indexed files. click a key or component in the left pane to see its information in the right pane.
General tab
Shows information associated with the current data file.
Record Layouts tab
Shows information for the record layouts defined in the current data file's associated record layout file. Select a layout name in the top pane to see its defined conditions, if any, in the bottom pane.
Parent topic: Data File Editor


Create file dialog box

Filename
The full path to and filename of the new data file.
Character set
Select a character set to use in the file.
Format
Select a format from the drop-down list. For a description of each available format, see File Formats and Organizations.
Organization
Select a record organization from the drop-down list. For a description of each available file organization, see File Formats and Organizations.
Define Keys
For indexed files, click this to specify key information. See Key Information dialog box for details.
Variable length records
Check this to specify that the data file has variable length records.
Minimum length
For data files with variable-length records, specify the minimum record length allowed.
Maximum length
Specify the maximum record length allowed.
Data compress records
Save and store the file using data compression.
Parent topic: Data File Editor
Related tasks
To create a data file
Related reference
File Formats and Organizations
Key Information dialog box


Data File Editor dialog box

File organization
Select the file organization to be used to open the file
Minimum length
Specify the minimum record length for variable length records in file
Maximum length
Specify the maximum record length in the file
Parent topic: Data File Editor


Print and Preview dialog boxes

Print is based on
Lists the available views for printing or previewing your data.
Header (text)
Check to print a header for your data. In the corresponding field, specify the header text that you want to see on your printout or preview.
Footer (text)
Check to print a footer for your data. In the corresponding field, specify the footer text that you want to see on your printout or preview.
Page numbers
Check to show page numbers on your printout or preview.
Ruler
Check to show a ruler on your printout or preview.
Record numbers
Check to show record numbers on your printout or preview.
Hexadecimal values
Check to include hexadecimal values on your printout or preview.
Current record
Print or preview only the current record.
All records
Print or preview all records in the file.
Selected records
Print or preview a range of files specified by the values entered into the corresponding From and To fields.
From
Specify the number of the first record in the range of fields to print or preview.
To
Specify the number of the last record in the range of fields to print or preview.
Whole record
For each record selected, print or preview the entire record.
Part of record
For each record selected, print or preview the part of the record specified by the values entered into the corresponding From and To fields.
From
Specify the number of the first character in the record to print or preview.
To
Specify the number of the last record in the range of fields to print or preview.
Print
Print the selected data (Print dialog box only).
Preview
Preview the selected data (Preview dialog box only).
Parent topic: Data File Editor
Related concepts
Printing from a Data File
Related tasks
To print from a data file
To preview a data file


Data File Find And Replace dialog box

Find
Type search string.
Replace
Check to replace found text with the text typed into the corresponding field.
Fwd
Search forward from the current position.
Back
Search backward from the current position.
Replace fwd
Replace the next instance found forward from the current position.
Replace back
Replace the next instance found backward from the current position.
Replace all
Replace all instances.
Match case
Check this to specify that the search is case sensitive.
Hex
Check this to search for hexadecimal instances of the text specified in the Find field.
Within offsets
Check this to search between the offsets specified in the corresponding Left and Right fields.
Parent topic: Data File Editor
Related concepts
Searching a Data File
Related tasks
To search within a data file


Find on Current Key dialog box

Find
Type the key to search for.
Condition
Select a condition from the drop-down list.
Parent topic: Data File Editor
Related concepts
Searching a Data File
Related tasks
To search within a data file


Goto dialog box

Column
Type the number of the column you want to go to.
Line
Type the line number that you want to go to.
Parent topic: Data File Editor
Related concepts
Searching a Data File
Related tasks
To search within a data file


Locate Field dialog box

Entry field
You have three options:
  • Specify the field name in full and click OK.
  • Specify part of the field name and click Suggest.
  • From the drop-down list, select a field you found previously.
Suggest
Display a list of fields with names that start with the partial field name you specified in the entry field. To locate one of these fields, click on the field.
Parent topic: Data File Editor
Related concepts
Searching a Data File
Related tasks
To search within a data file


Set record length dialog box

Valid values are
Shows the range of valid values.
Current record length is
The length of the current record.
Current layout length is
If record layouts have been applied, the length of the layout applied to the record.
New record length
Type a number that represents a valid value.
Parent topic: Data File Editor


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
IMS Database Automatic Backward Recovery
Automatic Backward Recovery Process
Recovery Utility
Invoking Backward Recovery from JCL
Rebuild Utility


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 (UNIX) or TMP or TEMP (Windows) to point to the directory where you would like to keep temporary files.
Parent topic: Rebuild
Related information
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Command Line

The format of the Rebuild command line is:

rebuild in-file [,out-file] [options]

Both in-file and out-file must include the filename extension. The filename of out-file must not be the same as in-file. You can use environment variables in place of in-file or out-file to implement filename mapping.

The options specified on the command line define the operation to be carried out by Rebuild.

  • Option Files
  • Redirection of Information
Parent topic: Rebuild
Related information
Overview
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Option Files

On the Rebuild command line, an at character (@) followed by a filename indicates that the named file contains Rebuild command line options.

If you use a file to supply Rebuild command line options, the file must be an ASCII text file.

Within the Rebuild options file:

  • Options should be separated by spaces.
  • Line ends are treated as spaces.
  • Any text between an asterisk (*) and the line end is treated as a comment.

In the following example:

rebuild infile.dat, outfile.dat @conv.par

conv.par is an ASCII text file containing Rebuild options.

Parent topic: Command Line
Related information
Redirection of Information


Redirection of Information

All information displayed by the Rebuild utility can be redirected to a text file using standard operating system redirection:

Use: | To:
> | Create a new file
>> | Extend an existing file

For example:

rebuild oldms001.dat,ms001.dat -k:1+20<N> -i >> rebuild.prt

redirects the output from Rebuild to the existing file rebuild.prt.

Note: When you are redirecting output, do not use the -v option.
Parent topic: Command Line
Related information
Option Files


Rebuild Options

The processing performed by Rebuild is defined by the option(s) specified on the command line.

On UNIX systems, Rebuild options must be preceded by a hyphen (-) character rather than a slash (/) character.

The following options are available:

-c | Specifies file compression
-d | Reconstructs an index from the data area of an indexed file
-e | Reports illegal duplicate keys and continues processing. If more than 1000 illegal duplicate keys are found, the rebuild aborts, because it considers the file attributes being used conflict with the data in the file to an extent that any results could be meaningless.
-f | Validates indexed files
-i | Displays information about the files being processed
-k | Defines the key structure for an indexed file
-m | Reserved for future use
-n | Displays information about a file (no other processing is performed)
-o | Specifies the organization of the input and output files
-p | Rebuilds IDXFORMAT "8" file in place
-q | Quickly rebuilds index files using the index side file (IDXFORMAT"12")
-r | Defines the record structure of the input and output files
-s | Specifies the format of the input file
-t | Specifies the format of the output file
-u | Attempts to recover a file for which the last update operation was not completed
-v | Displays a record count which is incremented as the file is processed
-y | Forces Rebuild to ignore file size discrepancies
-x | Specifies the order in which data is written when reorganizing an indexed file
-z | Instructs Rebuild to use a Fileshare server for file access
--q | Suppresses display of the Rebuild banner
--v | Displays the version number of Rebuild

Options can be placed in any order on the command line, except that options beginning with a double hyphen (--) must be placed before options beginning with a single hyphen (-). Options are free-format; spaces are required between options.

A colon (:) is required before parameters of the -f or -v options. For other options, a colon before parameters is optional. Do not insert spaces between the parameters of options.

Parent topic: Rebuild
Related information
Overview
Command Line
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Reorganizing Indexed Files

The format of the command line for reorganizing a file is:

rebuild in-file,out-file
[-c] [-d] [-i] [-k] [-n] [-p] [-s] [-v] [-x]

As indexed files are updated by adding, deleting and altering records, the index and data structures become disjointed, making processing less efficient. In addition, space left by deleted records is not always reused, making the file bigger than it needs to be.

After a large number of changes have been made, it is worth reorganizing an indexed file to rebuild the data and indices in an ordered sequential fashion and to reclaim any free space. This will ensure optimum performance and data integrity.

There are other reasons why you may want to reorganize a file. For example, if a file is processed sequentially, the access time to process the file increases over time, as the records start to become out of sequence due to updates. In this situation, you can reduce access time by reorganizing the file.

A third reason is to rebuild a duplicate key chain. A duplicate key has a duplicate occurrence value appended to it to make it unique. When a new duplicate key is added, the occurrence value of the last added key is incremented by one and used for the newly added key. If keys are deleted, no change is made to the occurrence values of the remaining keys. Therefore, you can reach the maximum number of duplicate values, even if some of those keys have already been deleted. In these circumstances it is a good idea to reorganize the file. For more information on duplicate keys, see the topic Duplicate Keysin the section File Organizations.

For example:

rebuild infile.dat,outfile.dat

causes Rebuild to read the data file (infile.dat) using the index file (infile.idx) and then create the output file (outfile.dat). The deleted records in infile.dat are not written to the output file.

Note: You cannot use the same filename for the input file and the output file.
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild
Rebuild Examples


Rebuilding a Corrupt Indexed File

The format of the command line for rebuilding an index is:

rebuild in-file[,out-file]
[-c] [-d] [-e] [-i] [-k] [-n] [-p] [-s] [-v]

The out-file parameter is optional, but recommended, because if you do not specify it, and the Rebuild operation fails, you will lose your original file.

There are a number of reasons why an indexed file becomes corrupt, for example:

  • A close operation on an indexed file fails.
  • A power surge occurs while the indexed file is open.
  • The machine is rebooted or powered off while an indexed file is open.

When a COBOL program attempts to open a corrupt indexed file, the run-time system detects that the file is corrupt and returns an extended file status code.

Rebuild can recover corrupt indexed files for you:

  • If the data portion of the file is intact and only the index portion is corrupt, then Rebuild can generate a new index (.idx) file from the data file with no loss of data.
  • If the data portion of the file is corrupt then Rebuild can rebuild a complete new indexed file, both data and index portions, but there will be loss of data as Rebuild discards any corrupt data records that it encounters.
    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}
rebuild $$server-name/in-file [$$server-name/out-file] {/l|/n}

On UNIX systems, replace the server-name prefix $$ with \$\$.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Callable Rebuild
Rebuild Examples


Callable Rebuild

You can call Rebuild from your COBOL program as follows:

call "callrb" using commands status

where:

Parameter: | Meaning:
commands | A PIC X(600) item containing the Rebuild command line. This item must be 600 bytes in length because Rebuild scans the command line backwards from offset 599.
status | A PIC XX COMP-X item containing the returned file status. This item shows the result of the call to Rebuild.

When called from within a program, Rebuild does not display any of its usual messages.

If an error occurs or the rebuild is unsuccessful, RETURN-CODE contains a non-zero value and status contains the returned file status. You should always check RETURN-CODE and status after a call to Rebuild.

The possible values of RETURN-CODE are shown below.

Value | Description
0 | Rebuild executed successfully
1 | An error occurred on the input file such as file not found or invalid file format - check status parameter
2 | An error occurred on the output file - check status parameter
3 | Error in sort
4 | File is corrupt
5 | Attempt to do a /k:a:exists
6 | Attempt to do a /k:r:onprime
7 | Attempt to do a /k:r:dontexist
8 | Too many duplicates on out
9 | The parameter list contained an error such as an invalid option or an invalid combination of options
10 | Rebuild has run out of memory

If an error occurs, execute Rebuild from the command line on the same file with a set of identical options. The screen output should give a more precise indication as to the cause of the error.

Note: If you are using the -f option (validate an indexed file), then any non-zero RETURN-CODE indicates that the file is corrupt. Again, execute Rebuild from the command line on the same file with a set of identical options to obtain more precise information.

The following example shows Rebuild being called from within a COBOL program.

 01 parameters   pic x(600).
 01 status       pic xx comp-x.
   ...
     move "infile.dat,outfile.dat -s:lii -c:d1" to parameters
     call "callrb" using parameters,status
     end-call
Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Rebuild Examples


Rebuild Examples

The section provides examples of using Rebuild.

rebuild infile.dat,outfile.dat -i

Reorganizes the file. The data is written in the order of the prime record key, and processing information displayed when the reorganization is complete.

rebuild infile.dat,outfile.dat -x:3

Reorganizes the file. The data is written in the order of the third alternate key.

rebuild infile.dat

Rebuilds the indexed file (assuming that the index (.idx) file is still present, and the key information held therein is not corrupt).

With C-ISAM and Level 2 files that do not have index files, use the -r and -s options to specify the record information and file format.

rebuild infile.dat,outfile.dat -s:c-isam -c:d1 -t:mf

Converts a C-ISAM format index file into the format used by this system and compresses the data part of the file.

rebuild infile.dat,outfile.dat --o:rel,ind -k:1+2:3+10d
-c:i7 -r:f10

Generates an index, with key compression, for a fixed-length relative file.

rebuild infile.dat,outfile.dat -s:lii -t:lii

Reorganizes a LEVEL II V2.5 COBOL format file and retains the LII structure on the output file. It is possible to combine -s and -t with other formats in a similar manner.

set data=/tmp.dat rebuild data -i

Reorganizes and displays information about the file /tmp.dat.

Parent topic: Rebuild
Related information
Overview
Command Line
Rebuild Options
Reorganizing Indexed Files
Rebuilding a Corrupt Indexed File
Converting a File
Validating an Indexed File
Rebuild through Fileshare
Callable Rebuild


File Handling

  • File Handling Examples
  • File Handling Guide
  • File Systems
  • Fileshare Guide
Parent topic: Data Access


File Handling Examples

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


Btrieve

  • Example Xfh2btr Configuration File
  • Example Btrieve Trace Output
  • Example Btrieve Trace Option Settings
  • Example of Btrieve Record Lengths
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
Sequential Files


Example Xfh2btr Configuration File

[X2B-DEFAULTS]
output:accelerated
i-o-shareable:accelerated
i-o-exclusive:accelerated
btrpage:2048
btrmaxrec:2000
[test1.dat]
output:exclusive
i-o-shareable:normal
btrpage:4096

The above is an example Xfh2btr configuration file which specifies the following:

  • The default open mode for files opened OUTPUT is accelerated.
  • The default open mode for files opened I/O which are shareable is accelerated.
  • The default open mode for files opened I/O which are exclusive is accelerated.
  • The default page size to use when creating files is 2048 bytes.
  • The default maximum record length is 2000 bytes.
  • For the file test1.dat, OPEN OUTPUT operations open the file exclusively.
  • For the file test1.dat, OPEN I/O operations which are shareable use the normal open mode.
  • For the file test1.dat, the page size to use when creating the file is 4096 bytes.
Parent topic: Btrieve
Related information
Example Btrieve Trace Output
Example Btrieve Trace Option Settings
Example of Btrieve Record Lengths


Example Btrieve Trace Output

Below is an example of the output produced when the trace option is used:

                                             Line
Input FA01 ifile1.tmp                          1
Output Btrieve Error=+0000 COBOL Error=0/0     2
Input FAF3 ifile1.tmp                          3
Output Btrieve Error=+0000 COBOL Error=0/0     4
Input FAF3 ifile1.tmp                          5
Output Btrieve Error=+0000 COBOL Error=0/0     6
Input FADC All Files                           7
Output Btrieve Error=+0000 COBOL Error=0/0     8
Input FA80 ifile1.tmp                          9
Output Btrieve Error=+0000 COBOL Error=0/0    10
Input FA02 ifile1.tmp                         11
Output Btrieve Error=+0000 COBOL Error=0/0    12
Input FAF5 ifile1.tmp                         13
Output Btrieve Error=+0000 COBOL Error=0/0    14
Input FAF5 ifile1.tmp                         15
Output Btrieve Error=+0000 COBOL Error=0/0    16
Input FAF5 ifile1.tmp                         17
Output Btrieve Error=+0009 COBOL Error=1/0    18
Input FA80 ifile1.tmp                         19
Output Btrieve Error=+0000 COBOL Error=0/0    20
Input FA01 test.dat                           21
Output Btrieve Error=+0029 COBOL Error=9/078  22
Input FA00 ifile1.tmp                         23
Output Btrieve Error=+0000 COBOL Error=0/0    24
Input FAF3 ifile1.tmp                         25
Output Btrieve Error=+0000 COBOL Error=4/8    26
Input FA80 ifile1.tmp                         27
Output Btrieve Error=+0000 COBOL Error=0/0    28

Line 1 shows an example input line: the operation code and the name of the file on which the operation is being performed.

Line 2 shows an example output line: the Btrieve error status and the error being returned to the COBOL application.

Line 7 shows an example of an operation (in this case, COMMIT) being performed on all open files.

Line 22 shows the error status 29 being returned from the Btrieve run-time system and that this is returned to the COBOL application as a 9/078 status. For details of the Btrieve error status 29, see the relevant Btrieve documentation.

Line 26 shows an error that is generated within the Xfh2btr module. An attempt is being made to write to a file which is opened for INPUT.

Parent topic: Btrieve
Related information
Example Xfh2btr Configuration File
Example Btrieve Trace Option Settings
Example of Btrieve Record Lengths


Example Btrieve Trace Option Settings

The following entries in the Xfh2btr configuration file:

[X2B-DEFAULTS]
trace-file:x2btrace.dat
trace:

specify that tracing is on for every file and that the trace information is written to the file x2btrace.dat.

The following entries in the Xfh2btr configuration file:

[X2B-DEFAULTS]
trace-file:
[test1.dat]
trace:

specify that tracing is on for the file test1.dat and that the trace information is written to the file xfh2btr.lst (the default trace filename).

Parent topic: Btrieve
Related information
Example Xfh2btr Configuration File
Example Btrieve Trace Output
Example of Btrieve Record Lengths


Example of Btrieve Record Lengths

The following examples use a page size of 1024 bytes:

  • A fixed length record index file with a record length of 1018 bytes creates a fixed length record Btrieve file with a fixed record length of 1018 bytes.

    All the keys must be in the first 1018 bytes of the record.

  • A fixed length record index file with a record length of 1019 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

    All the keys must be in the first 1014 bytes of the record.

  • A fixed length record index file with a record length of 1010 bytes and one key which allows duplicates creates a fixed length record Btrieve file with a fixed record length of 1010 bytes.

    All of the keys must be in the first 1010 bytes of the record.

  • A fixed length record index file with a record length of 1011 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes.

    All of the keys must be in the first 1006 bytes of the record.

  • A fixed length record relative file with a record length of 1014 bytes creates a fixed length record Btrieve file with a fixed record length of 1018 bytes.

    The additional four bytes is due to the auto-increment key that is added automatically to the front of each record.

    If you are using the opcode 06 action-code for the Callable File Handler call interface, the record length returned is 1014 bytes.

  • A fixed length relative file with a record length of 1015 bytes creates a variable length Btrieve file with a fixed record length of 1014 bytes. This is because you are limited to a maximum of 1014 bytes.

    This length includes the additional four bytes automatically added to the front of each record, due to the auto-increment key.

    If you are using the opcode 06 action-code for the Callable File Handler call interface, the record length returned is 1010 bytes.

  • A variable length record index file with a minimum record length of 1014 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

    All of the keys must be in the first 1014 bytes of the record.

  • A variable length record index file with a minimum record length of 1015 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

    All of the keys must be in the first 1014 bytes of the record.

  • A variable length record index file with a minimum record length of 1006 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes.

    All of the keys must be in the first 1006 bytes of the record.

  • A variable length record index file with a minimum record length of 1007 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes.

    All of the keys must be in the first 1006 bytes of the record.

  • A variable length record relative file with a minimum record length of 1010 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

    The additional four bytes is due to the auto-increment key that is added automatically to the front of each record.

    If you are using the opcode 06 action-code for the Callable File Handler call interface, the record length returned is 1010 bytes.

  • A variable length record relative file with a minimum record length of 1011 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes.

    The additional four bytes is due to the auto-increment key that is added automatically to the front of each record.

    If you are using the opcode 06 action-code for the Callable File Handler call interface, the record length returned is 1010 bytes.

Parent topic: Btrieve
Related information
Example Xfh2btr Configuration File
Example Btrieve Trace Output
Example Btrieve Trace Option Settings


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
Btrieve
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
Btrieve
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
Btrieve
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
Btrieve
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 SET (Windows) or export (UNIX) command to relate envvar to the physical filename you want to use:

Windows:
set envvar=c:\test.dat
UNIX:
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


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

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 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 recovering a corrupt indexed file

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

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

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

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

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
Btrieve
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
Btrieve
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
    Enterprise Developer 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
    Enterprise Developer provides MFSORT, a command line sort and merge utility, and MFJSORT, an emulator for DFSORT and SYNCSORT.
  • Btrieve
    Btrieve is the file handling system from Pervasive Software Inc.
  • 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
Btrieve
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
Btrieve
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 comprises the carriage return (x"0D") and the line feed (x"0A") characters (Windows) or is the line feed (x"0A") character (UNIX), 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"0D0A" (Windows) or x"0A" (UNIX) - record present

x"0D00" (Windows) or x"00" (UNIX) - 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
  • External File Mapper (Mfextmap)
Parent topic: File Handling Guide
Related information
Introduction
File Organizations
File Status
Sharing Files
File Handler Configuration
File Handler and Sort APIs
Sort Utilities
Btrieve
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 255 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
External File Mapper (Mfextmap)


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
External File Mapper (Mfextmap)


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 Windows example, opening stockfile causes the file warehs.buy in the current directory on the b: drive to be opened:

 select stockfile
     assign to "b:warehs.buy".

In the following UNIX example, opening stockfile causes the file warehs.buy in the current directory to be opened:

 select stockfile
     assign to "warehs.buy".

In this Windows example, a WRITE statement causes data to be output to prn:, the first parallel printer:

 select printfile
     assign to "prn:".

In this Windows example, opening input-file opens the file prog in the directory data (relative to the current directory):

 select input-file
     assign to "data\prog".
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.

If the filename of the physical file that you are creating contains spaces, you should surround the filename with quotes - see Example 2 below (applies to Windows environments only).

Example 1

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.

Example 2

The followingWindows example shows how to use quotes to create the file spacey filename.dat, where the filename contains spaces:

 select f1
      assign to dynamic f1-name.
...
working-storage section.
01 f1     pic x(30).
...
move """spacey  filename.dat""" to f1-name
....
open output f1.
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

Windows:
 device\library-name.lbr\filename.ext
UNIX:
 /library-name.lbr/filename.ext

Example

Windows:
c:\appdir\applib.lbr\app.dat
UNIX:
/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
External File Mapper (Mfextmap)
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.

In this topic, the term "environment variable" should be read as including the Micro Focus extended environment variables which are enabled via use of the External File Mapper (see the section External File Mapper (Mfextmap) later in this chapter).

Before you run the program, you should give any environment variables you are using an appropriate value using the operating system SET (Windows) or export (UNIX) command, for example:

set dir=d2

or

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 (\) (Windows) or (/) (UNIX), 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:

Windows:
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
UNIX:
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 File Mapper (Mfextmap)
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.

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

Windows:
set test=c:\apdir;d:\aplbr\aplbr.lbr;d:\aplbr\aplbr1.lbr
the filename $test\app.dat would be resolved to d:\aplbr\aplbr.lbr\app.dat if c:\apdir\app.dat did not exist.
UNIX:
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

Windows:
set appath=d:\apdir\progs1.lbr;d:\appdir\progs2.lbr
UNIX:
set appath=/apdir/progs1.lbr;/appdir/progs2.lbr

you can use the format

Windows:
call "$appath\prog"
UNIX:
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
External File Mapper (Mfextmap)


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
External File Mapper (Mfextmap)


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


External File Mapper (Mfextmap)

You can assign filenames externally using the External File Mapper (Mfextmap). This provides a flexible method of mapping the assigned filename used in your COBOL program to a physical filename, by enabling filename mapping to be resolved in a text file (the mapper file). Filename mappings can be altered subsequently, simply by editing the file.

select filename
   assign to external assigned-name

where the parameters are:

filename
The logical (internal) filename used by your program.
assigned-name
An entry in the mapper file.

Using the External File Mapper, rather than resolving filename assignments via operating system environment variables, reduces the amount of memory required for environment space.

  • Mapper File Structure
  • Mapper File Location
  • Activating the External File Mapper
  • Disabling The External File Mapper
Parent topic: Filenames
Related information
Filename Conventions
Assigning Filenames
Library Names in Paths
Filename Mapping
Assigning Device Names
Setting Up Pipes


Mapper File Structure

Before you can use the External File Mapper, you must create an ordinary text file (use a text editor such as Notepad to do this) and call that text file mfextmap.dat.

Each line in this file contains a filename assignment and takes the following form:

assigned-name physical-name

where the parameters are:

assigned-name
The assigned filename used in your program.
physical-name
The actual name of the physical file, including the pathname.

In this file:

  • Only one assignment is allowed per line
  • At least one space must separate the assigned and physical filenames
  • There can be any number of spaces preceding the assigned filename and following the physical filename
  • Filenames that include embedded spaces must be enclosed in double-quotes: for example, myfile "my file name"
  • Where you need to specify a file handler option for a filename that includes embedded spaces, it must be included within the double-quotes enclosing the name: for example, myfile "my file name(printer)"

You can alter the contents of the mapper file during the execution of your program. The mapping information in the current version of the mapper file is always used.

Parent topic: External File Mapper (Mfextmap)
Related information
Mapper File Location
Activating the External File Mapper
Disabling The External File Mapper


Mapper File Location

If you create a mapper file, it must be called mfextmap.dat and it must be located in one of the following places:

  • In the current directory (the directory in which your program is running)
  • In a directory on the COBOL system path (pointed to by the environment variable COBDIR)
  • In a directory on the path pointed to by the environment variable MFEXTMAP

Both MFEXTMAP and COBDIR can have multiple paths defined.

If MFEXTMAP is set but the mapper file does not exist in the directory or directories to which it points, the system tries to resolve the filename by searching for an environment variable with the same name as the assigned filename used in the program.

If MFEXTMAP is not set, the system searches for the mapper file in the current directory and then along the COBDIR path. If the mapper file is not found, the system tries to resolve the filename by searching for an environment variable with the same name as the assigned filename used in the program.

Parent topic: External File Mapper (Mfextmap)
Related information
Mapper File Structure
Activating the External File Mapper
Disabling The External File Mapper


Activating the External File Mapper

To use the External File Mapper, you must:

  • Link your program with the shared run-time system
  • Create a valid mapper file

Then, to activate the External File Mapper you must set the run-time system tunable environment_mapper to TRUE. You do this by adding the following line:

set environment_mapper=TRUE

to a configuration file pointed to by the COBCONFIG_ environment variable.

For more information on run-time tunables, see the topic Run-time Tunables.

Parent topic: External File Mapper (Mfextmap)
Related reference
Run-time Tunables
Related information
Mapper File Structure
Mapper File Location
Disabling The External File Mapper


Disabling The External File Mapper

By disabling the External File Mapper you will increase the speed of your system as no disk accesses are required to search for the current version of the mapper file.

To disable the External File Mapper set the run-time system tunable environment_mapper to FALSE.

Parent topic: External File Mapper (Mfextmap)
Related information
Mapper File Structure
Mapper File Location
Activating the External File Mapper


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

Windows:
set EXTFH=c:\mydir\test.cfg
sets the filename to c:\mydir\test.cfg.
UNIX:
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:

Windows:

  1. The file specified by the EXTFH variable.
  2. The file extfh.cfg in the current directory.
  3. The file %COBDIR%\etc\extfh.cfg.

UNIX:

  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
Btrieve
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 reference
Tutorial: Using the Callable 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 Enterprise Developer | FCD3
64-bit Enterprise Developer | FCD3
Managed COBOL support within Enterprise Developer | 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:

Windows:
set DYNREDIR=mod1!ep1[:mod2!ep2[:mod3!ep3]]
UNIX:
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 (UNIX) or .dll file (Windows)
  • userfh2
  • userfh3 in the module3shared library (UNIX) or .dll file (Windows)

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.
  • Custom file handlers are not supported in the .NET environment.
  • 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
  • DFSORT and ICETOOL Emulation
  • SYNCSORT Emulation
  • 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
Btrieve
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. Invoke it using the SORT statement, or use the CALL statement to invoke the SORT API directly.
MFSORT utility | A utility that you can invoke from the command line, which enables you to sort and merge data files.
MFJSORT utility | An emulator of IBM’s DFSORT and ICETOOL utilities and SYNCSORT, which supports many of their major functions .
Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
Related reference
The SORT Statement
Sort Module
Related information
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


DFSORT and ICETOOL Emulation

Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.

Every reasonable effort has been made to ensure the accuracy of information relating to the emulation of IBM's DFSORT and ICETOOL at the time of publication; however, we cannot guarantee complete accuracy as these tools continue to be developed.

The MFSORT and MFJSORT utilities support the DFSORT EXEC PARM and program control statements that are detailed below. In addition, MFJSORT also supports the operators of the ICETOOL mainframe utility that are detailed below:

  • DFSORT EXEC PARM Options Emulation
  • DFSORT Program Control Emulation
  • ICETOOL Emulation
Parent topic: Sort Utilities
Related concepts
SYNCSORT Emulation
MFJSENGINE
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


DFSORT EXEC PARM Options Emulation

The MFSORT and MFJSORT utilities emulate the following PARM parameters of the EXEC statement:

  • PARM
Parent topic: DFSORT and ICETOOL Emulation


PARM

The following PARM parameters of the EXEC statement are supported.

>--,PARM=--.-CENTWIN=.-s-.---.--------<<
           |         +-f-+   |
           |                 |
           +-SIZE-.-n------+-+
           |      +-nK-----+ |
           |      +-nM-----+ |
           |      +-MAX----+ |
           |      +-MAX-m--+ |
           |      +-MAX-mK-+ |
           |      +-MAX-mM-+ |
           |                 |
           +-SKIPREC=z-------+
           |                 |
           +-STOPAFT=n-------+
           |                 |
           +-VLSHRT----------+
           |                 |
           +-Y2PAST=.-s-.----+
           |         +-f-+   |
           |                 |
           +-SIGN-EBCDIC-----+
Note:
  • VLSHRT is ON by default.
  • SIGN-EBCDIC is an MFJSORT extension; see Sort/Merge Operations (MFJSORT) for more information.

In this COBOL system, the following parameter fields are only parsed and ignored:

Parameter | Fields
ABEND | NOABEND |
ARESALL | (n | nK | nM)
AVGRLEN | n
BSAM |
CINV | NOCINV |
COBEXIT | (COB1 | COB2)
DSPSIZE | (MAX | n)
DYNALLOC | [ =( d | n | d, n | OFF)]
EFS | (name | NONE)
EQUALS | NOEQUALS |
E15 | =COB
E35 | =COB
FILSZ | (x | Ex | Ux)
HIRPMAX | (OPTIMAL | N | p%)
LIST | NOLIST |
LISTX | NOLISTX |
LOCALE | (name | CURRENT | NONE)
MSGDDN | ddname
MSGPRT | (ALL | CRITICAL | NONE)
ODMAXBF | (n | nK | nM)
OUTREL | NOOUTREL |
OVFLO | (RC0 | RC4 | RC16)
PAD | (RC0 | RC4 | RC16)
RC16 | (ABE)
RESALL | (n | nK | nM)
RESERVE | (n | nK | nM)
RESET | NORESET |
SDB | (LARGE | YES | INPUT | NO)
SOLRF | NOSOLRF |
SPANINC | (RC0 | RC4 | RC16)
SZERO | NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
VERIFY | NOVERIFY |
VLLONG | NOVLLONG |
VLSCMP | NOVLSCMP |
NOVLSHRT |
VSAMEMT | NOVSAMEMT |
VSAMIO | NOVSAMIO |
WRKREL | NOWRKREL |
WRKSEC | NOWRKSEC |
ZDPRINT | NZDPRINT |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT EXEC PARM Options Emulation
Related reference
Sort/Merge Operations (MFJSORT)


DFSORT Program Control Emulation

The MFSORT and MFJSORT utilities emulate the following program control statements:

  • ALTSEQ
  • DEBUG
  • END
  • INCLUDE
  • INREC
  • MERGE
  • MODS
  • OMIT
  • OPTION
  • OUTFIL
  • OUTREC
  • RECORD
  • SORT
  • SUM
Parent topic: DFSORT and ICETOOL Emulation


ALTSEQ

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                  +--,---+
                  V      |
>--ALTSEQ--CODE=-(.-fftt-.)------<<
Parent topic: DFSORT Program Control Emulation


DEBUG

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

          +------,-------+
          V              |
>--DEBUG--.--.---------.-.-----<<
             +-ABEND---+
             +-NOABEND-+
             +-ABSTP---+

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT Program Control Emulation


END

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--END--<<
Parent topic: DFSORT Program Control Emulation


INCLUDE

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--INCLUDE--COND=-(logical-expression)-.----------.----------<<
                                       +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


INREC

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                      +--------,-------+
                      V                |
>---INREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                        +-c:-+ |                                           |
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-p,m,date-format,DATEDIFF,p,m,date-format--+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-p,m,date-format,DATEDIFF,p,m,date-format--+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

DATEDIFF limitations:

The valid length(m) and format(Y2x) combinations for each type of date field that can be used with DATEDIFF:

  • m,Y2X
  • 5,Y2T
  • 6,Y2T
  • 5,Y2W
  • 6,Y2W
  • 3,Y2U
  • 4,Y2V
  • 3,Y2X
  • 4,Y2Y

The maximum number of DATEDIFF operands permitted is 300.

Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


MERGE

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--MERGE--FIELDS=-(logical-expression)--FORMAT=f-----<<
Note: The maximum size of a merge field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | (FILSZ=x | size=y]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


MODS

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

         +----------------,-------------------+
         V                                    |
>--MODS--.-.-E15-.=-(-n,m.----------------.-)-.-+-.-------------.----<<
           +-E35-+       +-,-.---.-.----.-+       +-HILEVEL=YES-+
                             +-s-+ +-,e-+

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
MODS | (E18=n, m, [s] [e])+[HILEVEL=YES] (E39=n, m, [s] [e])+[HILEVEL=YES]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT Program Control Emulation


OMIT

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--OMIT--COND=--(logical-expression)-.----------.----------<<
                                     +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


OPTION

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

           +---------,-------------+
           V                       |
>--OPTION--.--.-CENTWIN---------.--.----------<<
              |                 |
              +-COPY------------+
              |                 |
              +-EFS=.-name-.----+
              |     +-NONE-+    |
              |                 |
              +-.-EQUALS---.----+
              | +-NOEQUALS-+    |
              |                 |
              +-OVFLO=.-RC0--.--+
              |       +-RC4--+  |
              |       +-RC16-+  |
                 |                 |
              +--SKIPREC=z------+
              |                 |
              +--STOPAFT=n------+
              |                 |
              +--Y2PAST=.-s-.---+
              |         +-f-+   |
              |                 |
              +-.-ZDPRINT--.----+
              | +-NZDPRINT-+    |
              |                 |
              +-VLSHRT----------+
Note: VLSHRT is ON by default.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
ARESALL | (n | nK | nM)
ARESINV | (n | nK | nM)
AVGRLEN | n
CHALT |
NOCHALT |
CHECK |
NOCHECK |
CINV |
NOCINV |
CKPT |
COBEXIT | (COB1 | COB2)
DSA | n
DSPSIZE | MAX
DYNALLOC | [=(d | n | d,n | OFF)]
EXITCK | (STRONG | WEAK)
FILSZ | (x | Ex | Ux)
SIZE | (y | Ey | Uy)
HIRPMAX | (OPTIMAL | n | P%)
LIST |
NOLIST |
LISTX |
NOLISTX |
LOCALE | (name | CURRENT | NONE)
MAINSIZE | (n | nK | nM | MAX)
MOSIZE | (MAX | n | p%)
MSGDDN | ddname
MSGPRT | (ALL | NONE | CRITICAL)
PRINT |
NOBLKSET |
NOOUTREL |
NOOUTSEC |
NULLOUT | (RC0 | RC4 | RC16)
ODMAXBF | (n | nK | nM)
PAD | (RC0 | RC4 | RC16)
RESALL | (n | nK | nM)
RESET |
NORESET |
RESINV | (n | nK | nM)
SDB | (LARGE | YES | INPUT | NO)
SMF | (SHORT | FULL | NO)
SOLRF |
NOSOLRF |
SORTDD | cccc
SORTIN | ddname
SORTOUT | ddname
SPANINC | (RC0 | RC4 | RC16)
SZERO |
NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
USEWKDD |
VERIFY |
NOVERIFY |
VLLONG |
NOVLLONG |
VLSCMP |
NOVLSCMP |
NOVLSHRT |
VSAMEMT |
NVSAMEMT |
VSAMIO |
NOVSAMIO |
WRKREL |
NOWRKREL |
WRKSEC |
NOWRKSEC |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: DFSORT Program Control Emulation


OUTFIL

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

           +----------------------------,-----------------------------------+
           |                                                                |
           |             +---,----+                                         |
           V             V        |                                         |
>--OUTFIL--.--.--FNAMES=-.-ddname-.---------------------------------------.-.----------<<
              |                                                           |
              |         +---,-----+                                       |
              |         V         |                                       |
              +--FILES=-.-.-d---.-.---------------------------------------+
              |           +-dd--+                                         |
              |           +-OUT-+                                         |
              |                                                           |
              +--STARTREC=-n----------------------------------------------+
              |                                                           |
              +-ENDREC=-n-------------------------------------------------+
              |                                                           |
              |           +------,---------+                              |
              |           V                |                              |
              +--OUTREC=-(.-item-statement-.)-.----------.-.------------.-+
              |                               +-,VTOF----+ +-VFILL=byte-+ |
              |                               +-,CONVERT-+                |
              |            +-------,--------+                             |
              |            V                |                             |
              +--OVERLAY=-(.-item-statement-.)----------------------------+
              |                                                           |
              |                                                           |
              |                                                           |
              +-.-INCLUDE=-.-(-logical-expression-)-.---.-----------------+
              | |          +-ALL--------------------+   |                 |
              | |          +-NONE-------------------+   |                 |
              | |                                       |                 |
              | |                                       |                 |
              + +-OMIT=-.-(logical-expression-)-.-------+                 |
              |         +-ALL-------------------+                         |
              |         +-NONE------------------+                         |
              |                                                           |
              +--SAVE-----------------------------------------------------+
              |                                                           |
              +--FTOV-----------------------------------------------------+
              |                                                           |
              +--VLTRIM=byte----------------------------------------------+
              |                                                           |
              +--SPLIT----------------------------------------------------+
              |                                                           |
              +--NULLOFL=-.-RC0--.----------------------------------------+
              |           +-RC4--+                                        |
              |           +-RC16-+                                        |
              |                                                           |
              +--LINES=n--------------------------------------------------+
              |                                                           |
              |           +--------,--------+                             |
              |           V                 |                             |
              +--HEADERn=-.-(-header-item-)-.-----------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--TRAILERn=-.-(-trailer-item-)-.---------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--SECTIONS=-.-(-section-item-)-.---------------------------|
              |                                                           |
              +--NODETAIL-------------------------------------------------|
              |                                                           |
              +--REMOVECC-------------------------------------------------|
              |                                                           |
              +--CONVERT--------------------------------------------------+
Note: The maximum number of OUTFILs is 2048.

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                        +-c:-+ |                                           |
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-p,m,date-format,DATEDIFF,p,m,date-format--+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

The following options for the header item are supported:

              +-------------,--------------------+
              V                                  |
>--HEADERn=--(.--.----.-.-r------------------.-)-.--<<
                 +-c:-+ +-.-DATE----------.--+
                        | +-&DATE---------+  |
                        | +-DATE=(abcd)---+  |
                        | +-&DATE=(abcd)--+  |
                        | +-DATENS=(abc)--+  |
                        | +-&DATENS=(abc)-+  |
                        |                    |
                        +-.-TIME--.----------+
                        | +-&TIME-+          |
                        |                    |
                        +-.-PAGE--.----------+
                          +-&PAGE-+

The following options for a trailer item are supported:

               +-------------,----------------------------------+
               V                                                |
>--TRAILERn=--(.--.----.-.-r--------------------------------.-)-.--<<
                  +-c:-+ +-.-DATE----------.----------------+
                         | +-&DATE---------+                |
                         | +-DATE=(abcd)---+                |
                         | +-&DATE=(abcd)--+                |
                         | +-DATENS=(abc)--+                |
                         | +-&DATENS=(abc)-+                |
                         |                                  |
                         +-.-TIME--.------------------------+
                         | +-&TIME-+                        |
                         |                                  |
                         +-.-PAGE--.------------------------+
                         | +-&PAGE-+                        |
                         |                                  |
                         +-.-COUNT-------.------------------|
                         | +-COUNT=edit--+                  |
                         |                                  |
                         +-.-SUBCOUNT-----------.-----------|
                         | +-SUBCOUNT15---------+           |
                         | +-SUBCOUNT=(.-edit-.)+           |
                         |             +-to---+             |
                         |                                  |
                         +-.-TOTAL-.=-(p,m,f.------.)-------+
                         | +-TOT---+        +-,to--+        |
                         |                                  |
                         +-MIN=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-MAX=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-AVG=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +--.-SUB------.=-(p,m,f.-------.)--+
                         |  +-SUBTOT---+        +-,edit-+   |
                         |  +-SUBTOTAL-+        +-,to---+   |
                         |                                  |
                         +--SUBMIN=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         |                                  |
                         +--SUBMAX=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         |                                  |
                         +--SUBAVG=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         +----------------------------------+
Note: See the Limitations section for the COUNT and SUBCOUNT values, and the TOTAL, MIN, MAX, and AVG fields.

The following options for a sections item are supported:

              +------------------------------,--------------------------+
              |     +------------------------,------------------------+ |
              V     V                                                 | |
>--SECTIONS=-(.-p,m-.--.--------------------------------------------.-.-.)----<<
                       +-SKIP=.-P--.--------------------------------+
                       |      +-L--+                                |
                       |      +-nL-+                                |
                       |          +-----,-------+                   |
                       |          V             |                   |
                       +-HEADER3=(.-header-item-.)--.------------.--+
                       |                            +-,-PAGEHEAD-+  |
                       |           +-----,-------+                  |
                       |           V             |                  |
                       +-TRAILER3=(.-header-item-.)-----------------+

Limitations:

  • The maximum length of COUNT and SUBCOUNT values is 9 digits.
  • The maximum length of the TOTAL fields:
    TOTAL field formats | MFJSORT | DFSORT
    Length (m) | Digits (d) | Length (m) | Digits (d)
    ZD | 1-15 | *Maximum 18 | 1-15 | 15
    ZD | 16-31 | 16-31 | 31
    PD | 1-8 | 1-8 | 15
    PD | 9-16 | 9-16 | 31
    BI | 1-4 | 1-4 | 10
    BI | 5-8 | 5-8 | 20
    FI | 1-4 | 1-4 | 10
    FI | 5-8 | 5-8 | 20
    FL | 4 or 8 | 4 or 8 | 20
    CSF, FS | 1-15 | 1-15 | 15
    CSF, FS | 16-32 | 16-32 | 31

    * MFJSORT will display the total to the same amount of digits as specified in the length.

  • The TO parameter for TOTAL, MIN, MAX, and AVG is only applicable for TRAILER3.

DATEDIFF limitations:

The valid length(m) and format(Y2x) combinations for each type of date field that can be used with DATEDIFF:

  • m,Y2X
  • 5,Y2T
  • 6,Y2T
  • 5,Y2W
  • 6,Y2W
  • 3,Y2U
  • 4,Y2V
  • 3,Y2X
  • 4,Y2Y

The maximum number of DATEDIFF operands permitted is 300.

Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


OUTREC

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                      +--------,-------+
                      V                |
>--OUTREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                        +-c:-+ |                                           |
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-p,m,date-format,DATEDIFF,p,m,date-format--+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-p,m,date-format,DATEDIFF,p,m,date-format--+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

DATEDIFF limitations:

The valid length(m) and format(Y2x) combinations for each type of date field that can be used with DATEDIFF:

  • m,Y2X
  • 5,Y2T
  • 6,Y2T
  • 5,Y2W
  • 6,Y2W
  • 3,Y2U
  • 4,Y2V
  • 3,Y2X
  • 4,Y2Y

The maximum number of DATEDIFF operands permitted is 300.

Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


RECORD

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

>--RECORD--.-TYPE=-.-F-.--------------------.----<<
           |       +-V-+                    |
           +-.--------.--LENGTH=(L1,...,L3)-+
           | +-TYPE=F-+                     |
           +-.--------.--LENGTH=(L1,...,L7)-+
             +-TYPE=V-+
Parent topic: DFSORT Program Control Emulation


SORT

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                    +---,---+                   +---------,------------+
                    V       |                   V                      |
>--SORT--FIELDS=-.-(.-p,m,f-.)----------------.-.--.-.-EQUALS---.---.--.----<<
                 |                            |    + +-NOEQUALS-+   |
                 |  +--,--------+             |    |                |
                 |  V           |             |    +-SKIPREC=z------+
                 +-(.-p,m,.---.-.)-,-FORMAT=f-+    +-STOPAFT=n------+
                 |        +-f-+               |    +-Y2PAST=-.-s-.--+
                 +-COPY-----------------------+    |         +-f-+  |
                                                   +-CENTWIN=-.-s-.-+
                                                              +-f-+
Note: The maximum size of a sort field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | CKPT DYNALLOC [=(d | n | d, n | OFF)] FILSZ = (x | Ex | Ux) SIZE = (y | Ey | Uy)

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


SUM

The following parameters of this DFSORT control statement are supported in MFSORT and MFJSORT:

                   +---,---+
                   V       |
>--SUM--FIELDS=-.-(.-p,m,f-.)----------------.----<<
                |                            |
                |  +--,--------+             |
                |  V           |             |
                +-(.-p,m,.---.-.)-,-FORMAT=f-+
                |        +-f-+               |
                +-NONE-----------------------+
Restriction: The maximum number of SUM fields is 600 and the maximum SUM field length is 18.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: DFSORT Program Control Emulation
Related reference
Field Types


ICETOOL Emulation

The MFJSORT utility supports the following ICETOOL operators.

Note: Not each operator is fully supported. There is no support for parameters which are not listed.
  • COPY
  • COUNT
  • DISPLAY
  • OCCUR
  • RANGE
  • SELECT
  • SPLICE
  • SORT
  • STATS
  • UNIQUE
Parent topic: DFSORT and ICETOOL Emulation


COPY

The following parameters of this ICETOOL operator are supported in MFJSORT:

                              +---,---+
                              V       |
>--COPY--FROM(indd)-.-.--TO-(-.-outdd-.-)-----------.-.----<<
                    | +-USING(xxxx)-----------------+ |
                    | |                             | |
                    | |      +----,--+              | |
                    | |      V       |              | |
                    | +-TO-(-.-outdd-.-)-USING(xxx)-+ |
                    |                                 |
                    +-.-------------.-----------------+
                    | +-VSAMTYPE(x)-+                 |
                    |                                 |
                    +-.--------.----------------------+
                      +-SERIAL-+

Limits and Restrictions:

Parameter | Restriction
outdd | Maximum outdd count is 10
LOCALE(name), LOCALE(CURRENT), and LOCALE(NONE) | These parameters are parsed but ignored.
Parent topic: ICETOOL Emulation


COUNT

The following parameters of this ICETOOL operator are supported in MFJSORT:

>-COUNT--FROM(indd)-.--.-------------.--.------<<
                    |  +-USING(xxxx)-+  |
                    |                   |
                    +-.-------------.---+
                    | +-VSAMTYPE(x)-+   |
                    |                   |
                    +-.------.----------+
                    | +-RC4--+          |
                    | +-RC12-+          |
                    |                   |
                    +-.-------------.---+
                      +-EMPTY-------+
                      +-NOTEMPTY----+
                      +-HIGHER(x)---+
                      +-LOWER(y)----+
                      +-EQUAL(v)----+
                      +-NOTEQUAL(w)-+

Limits and Restrictions:

Parameter | Restriction
LOCALE(name), LOCALE(CURRENT), and LOCALE(NONE) | These parameters are parsed but ignored.
Parent topic: ICETOOL Emulation


DISPLAY

The following parameters of this ICETOOL operator are supported in MFJSORT:

                          +-----------,--------------+
                          V                          |
>--DISPLAY--FROM(indd)--.-.-.--ON(p,m,f)-----------.-.-.----<<
                        |   +--ON(p,m,f,formatting-+   |
                        |   +--ON(p,m,HEX)---------+   |
                        |   +--ON(VLEN)------------+   |
                        |   +--ON(NUM)-------------+   |
                        |                              |
                        +-LIST(listdd)-----------------+
                        |                              |
                        | +------,--------------+      |
                        | V                     |      |
                        +-.-.-----------------.-.------+
                        |   +-TITLE('string')-+        |
                        |                              |
                        +-.------.---------------------+
                        | +-PAGE-+                     |
                        |                              |
                        +-.------------.---------------+
                        | +-DATE-------+               |
                        | +-DATE(abcd)-+               |
                        |                              |
                        +-.-----------.----------------+
                        | +-TIME------+                |
                        | +-TIME(abc)-+                |
                        |                              |
                        +-.-------.--------------------+
                        | +-BLANK-+                    |
                        | +-PLUS--+                    |
                        |                              |
                        | +----------,-----------+     |
                        | V                      |     |
                        +-.-.------------------.-.-----+
                        |   +-HEADER('string')-+       |
                        |   +-HEADER(NONE)-----+       |
                        |   +-NOHEADER---------+       |
                        |                              |
                        +-.----------.-----------------+
                        | +-LINES(n)-+                 |
                        |                              |
                        +-.-----------------.----------+
                        | +-TOTAL('string')-+          |
                        |                              |
                        +-.-------------------.--------+
                        | +-MINIMUM('string')-+        |
                        |                              |
                        +-.-------------------.--------+
                        | +-MAXIMUM('string')-+        |
                        |                              |
                        +-.-------------------.--------+
                        | +-AVERAGE('string')-+        |
                        |                              |
                        +-.----------.-----------------+
                        | +-LIMIT(n)-+                 |
                        |                              |
                        +-.-------------.--------------+
                        | +-VSAMTYPE(x)-+              |
                        |                              |
                        +-.----------.-----------------+
                        | +-WIDTH(n)-+                 |
                        |                              |
                        +-.--------------.-------------+
                        | +-BREAK(p.m.f)-+             |
                        |                              |
                        +-.-----------------.----------+
                        | +-BTITLE('string')+          |
                        |                              |
                        +-.-----------------.----------+
                        | +-BTOTAL('string')+          |
                        |                              |
                        +-.-------.--------------------+
                          +-UZERO-+

Limits and Restrictions:

Parameter | Restriction
ON | Maximum ON count of 20
HEADER('string') | Maximum string size of 50
LINES(n) | Range of n = 9-1000
WIDTH(n) | Range of n = 121-2048
TITLE('string') | Maximum TITLE('string') count is 3
Parent topic: ICETOOL Emulation


OCCUR

The following parameters of this ICETOOL operator are supported in MFJSORT:

                             +-----------,--------------+
                             V                          |
>--.-OCCUR--.--FROM(indd)--.-.-.-ON(p,m,f)------------.-.-.-----<<
   +-OCCURS-+              |   +-ON(p,m,f,formatting)-+   |
                           |   +-ON(p,m,HEX)----------+   |
                           |   +-ON(VLEN)-------------+   |
                           |   +-ON(VALCNT)-----------+   |
                           |                              |
                           +---LIST(listdd)---------------+
                           |                              |
                           | +-------,-------------+      |
                           | V                     |      |
                           +-.-.-----------------.-.------+
                           |   +-TITLE('string')-+        |
                           |                              |
                           +-.------.---------------------+
                           | +-PAGE-+                     |
                           |                              |
                           +-.------------.---------------+
                           | +-DATE-------+               |
                           | +-DATE(abcd)-+               |
                           |                              |
                           +-.-----------.----------------+
                           | +-TIME------+                |
                           | +-TIME(abc)-+                |
                           |                              |
                           +-.-------.--------------------+
                           | +-BLANK-+                    |
                           | +-PLUS--+                    |
                           |                              |
                           | +----------,-----------+     |
                           | V                      |     |
                           +-.-.------------------.-.-----+
                           |   +-HEADER('string')-+       |
                           |   +-HEADER(NONE)-----+       |
                           |   +-NOHEADER---------+       |
                           |                              |
                           +-.----------.-----------------+
                           | +-LINES(n)-+                 |
                           |                              |
                           +-.-------------.--------------+
                           | +-VSAMTYPE(x)-+              |
                           |                              |
                           +-.----------.-----------------+
                           | +-WIDTH(n)-+                 |
                           |                              |
                           +-.-------.--------------------+
                           | +-UZERO-+                    |
                           |                              |
                           +-.-----------.----------------+
                             +-ALLDUPS---+
                             +-NODUPS----+
                             +-HIGHER(x)-+
                             +-LOWER(y)--+
                             +-EQUAL(v)--+

Limits and Restrictions

Parameter | Restriction
ON | Maximum ON count of 20
HEADER('string') | Maximum string size of 50
LINES(n) | Range of n = 9-1000
WIDTH(n) | Range of n = 121-2048
TITLE('string') | Maximum TITLE('string') count is 3

The ALLDUPS/NODUPS/HIGHER(x)/LOWER(y)/EQUAL(v) parameter must be the last parameter specified.

Parent topic: ICETOOL Emulation


RANGE

The following parameters of this ICETOOL operator are supported in MFJSORT:

>--RANGE--FROM(indd)--.-.--ON(p,m,f)--.--------.----<<
                      | +--ON(VLEN)---+        |
                      |                        |
                      +-.-HIGHER(x)----------.-+
                      | +-LOWER(y)-----------+ |
                      | +-HIGHER(x)-LOWER(y)-+ |
                      | +-EQUAL(v)-----------+ |
                      | +-NOTEQUAL(w)--------+ |
                      |                        |
                      +-.---------------.------+
                        +--VSAMTYPE(x)--+

Limits and Restrictions:

Parameter | Restriction
ON | Only one ON is allowed
Parent topic: ICETOOL Emulation


SELECT

The following parameters of this ICETOOL operator are supported in MFJSORT:

>--SELECT--FROM(indd)--.-.--TO(outdd)-----------------.-.---------<<
                       | +--DISCARD(savedd)-----------+ |
                       | +--TO(outdd)-DISCARD(savedd)-+ |
                       |                                |
                       |   +---,-------+                |
                       |   V           |                |
                       +-.-.-ON(p,m,f)-.-.--------------+
                       | +-ON(VLEN)------+              |
                       |                                |
                       +-.-ALLDUPS---.------------------+
                       | +-NODUPS----+                  |
                       | +-HIGHER(x)-+                  |
                       | +-LOWER(y)--+                  |
                       | +-EQUAL(v)--+                  |
                       | +--FIRST----+                  |
                       | +--LAST-----+                  |
                       |                                |
                       +-.-------------.----------------+
                       | +-VSAMTYPE(x)-+                |
                       |                                |
                       +-.---------.--------------------+
                       | +--UZERO--+                    |
                       |                                |
                       +-.-------------.----------------+
                         +-USING(xxxx)-+

Limits and Restrictions:

Parameter | Restriction
ON | Maximum ON count of 20
ON and ALLDUPS|NODUPS|HIGHER|LOWER|EQUAL|FIRST|LAST | Mandatory keywords
Parent topic: ICETOOL Emulation


SPLICE

The following parameters of this ICETOOL operator are supported in MFJSORT:

                              +-----------+ +-----------+
                              v           | v           |
>-SPLICE-FROM(indd)-TO(outdd)-.-ON(p,m,f)-.-.-WITH(p,m)-.-.-----------------.-<<
                                                          |                 |
                                                          +-.----------.----+
                                                          | +-WITHALL--+    |
                                                          | +-WITHANY--+    |
                                                          | +-WITHEACH-+    |
                                                          |                 |
                                                          +-.------------.--+
                                                          | +-KEEPNODUPS-+  |
                                                          |                 |
                                                          +-.----------.----+
                                                          | +-KEEPBASE-+    |
                                                          |                 |
                                                          +-.-------------.-|
                                                          | +-USING(xxxx)-+ |
                                                          |                 |
                                                          +-.-------------.-+
                                                          | +-VSAMTYPE(x)-+ |
                                                          |                 |
                                                          +-.-------.-------+
                                                          | +-UZERO-+       |
                                                          |                 |
                                                          +-.----------.----+
                                                            +-VLENMAX--+
                                                            +-VLENOVLY-+

Limits and Restrictions

Parameter | Restriction
ON | ON count must be between 1 and 20
WITH | WITH count must be between 1 and 50
Parent topic: ICETOOL Emulation


SORT

The following parameters of this ICETOOL operator are supported in MFJSORT:

>--SORT--FROM(indd)--USING(xxxx)--.-.------------------.-.-----<<
                                  | |                  | |
                                  | |      +--,----+   | |
                                  | |      V       |   | |
                                  | +--TO(-.-outdd-.-)-+ |
                                  |                      |
                                  +-VSAMTYPE(x)----------+
                                  |                      |
                                  +-.--------.-----------+
                                    +-SERIAL-+

Limits and Restrictions:

Parameter | Restriction
outdd | Maximum outdd count is 10
LOCALE(name), LOCALE(CURRENT), and LOCALE(NONE) | These parameters are parsed but ignored.
Parent topic: ICETOOL Emulation


STATS

The following parameters of this ICETOOL operator are supported in MFJSORT:

                          +----,------+
                          V           |
>--STATS--FROM(indd)--.-.-.-ON(p,m,f)-.-.-.-----<<
                      | +-ON(VLEN)------+ |
                      |                   |
                      +-.-------------.---+
                        +-VSAMTYPE(x)-+
Parent topic: ICETOOL Emulation


UNIQUE

The following parameters of this ICETOOL operator are supported in MFJSORT:

                           +----,------+
                           V           |
>--UNIQUE--FROM(indd)--.-.-.-ON(p,m,f)-.-.-.-----<<
                       | +-ON(VLEN)------+ |
                       |                   |
                       +-.-------------.---+
                       | +-VSAMTYPE(x)-+   |
                       |                   |
                       +-.-------.---------+
                         +-UZERO-+
Parent topic: ICETOOL Emulation


SYNCSORT Emulation

Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.
Every reasonable effort has been made to ensure the accuracy of information relating to the emulation of SYNCSORT at the time of publication; however, we cannot guarantee complete accuracy as this tool continues to be developed.

The MFSORT and MFJSORT utilities support the following emulation:

  • SYNCSORT EXEC PARM Options Emulation
  • SYNCSORT Program Control Emulation
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
MFJSENGINE
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Error Messages


SYNCSORT EXEC PARM Options Emulation

The MFSORT and MFJSORT utilities emulate the following PARM parameters of the EXEC statement:

  • PARM
Parent topic: SYNCSORT Emulation


PARM

The following PARM parameters of the EXEC statement are supported.

>--,PARM=--.-CENTWIN=.-s-.---.--------<<
           |         +-f-+   |
           |                 |
           +-SIZE-.-n------+-+
           |      +-nK-----+ |
           |      +-nM-----+ |
           |      +-MAX----+ |
           |      +-MAX-m--+ |
           |      +-MAX-mK-+ |
           |      +-MAX-mM-+ |
           |                 |
           +-SKIPREC=z-------+
           |                 |
           +-STOPAFT=n-------+
           |                 |
           +-VLSHRT----------+
           |                 |
           +-Y2PAST=.-s-.----+
           |         +-f-+   |
           |                 |
           +-SIGN-EBCDIC-----+
Note:
  • VLSHRT is ON by default.
  • SIGN-EBCDIC is an MFJSORT extension; see Sort/Merge Operations (MFJSORT) for more information.

In this COBOL system, the following parameter fields are only parsed and ignored:

Parameter | Fields
ABEND | NOABEND |
ARESALL | (n | nK | nM)
AVGRLEN | n
BSAM |
CINV | NOCINV |
COBEXIT | (COB1 | COB2)
DSPSIZE | (MAX | n)
DYNALLOC | [ =( d | n | d, n | OFF)]
EFS | (name | NONE)
ELAP |
EQUALS | NOEQUALS |
E15 | =COB
E35 | =COB
FILSZ | (x | Ex | Ux)
HIRPMAX | (OPTIMAL | N)
LIST | NOLIST |
LISTX | NOLISTX |
LOCALE | (name | CURRENT | NONE)
MSGDDN | ddname
MSGPRT | (ALL | CRITICAL | NONE)
ODMAXBF | (n | nK | nM)
OUTREL | NOOUTREL |
OVFLO | (RC0 | RC4 | RC16)
PAD | (RC0 | RC4 | RC16)
RC16 | (ABE)
RESALL | (n | nK | nM)
RESERVE | (n | nK | nM)
RESET | NORESET |
SDB | (LARGE | YES | INPUT | NO)
SOLRF | NOSOLRF |
SPANINC | (RC0 | RC4 | RC16)
SZERO | NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
VERIFY | NOVERIFY |
VLLONG | NOVLLONG |
VLSCMP | NOVLSCMP |
NOVLSHRT |
VSAMEMT | NOVSAMEMT |
VSAMIO | NOVSAMIO |
VSCORE | value
VSCORET | value
WRKREL | NOWRKREL |
WRKSEC | NOWRKSEC |
ZDPRINT | NZDPRINT |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT EXEC PARM Options Emulation
Related reference
Sort/Merge Operations (MFJSORT)


SYNCSORT Program Control Emulation

The MFSORT and MFJSORT utilities emulate the following program control statements:

  • ALTSEQ
  • DEBUG
  • END
  • INCLUDE
  • INREC
  • MERGE
  • MODS
  • OMIT
  • OPTION
  • OUTFIL
  • OUTREC
  • RECORD
  • SORT
  • SUM
Parent topic: SYNCSORT Emulation


ALTSEQ

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                  +--,---+
                  V      |
>--ALTSEQ--CODE=-(.-fftt-.)------<<
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


DEBUG

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
          +------,-------+
          V              |
>--DEBUG--.--.---------.-.-----<<
             +-ABEND---+
             +-NOABEND-+
             +-ABSTP---+

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
DEBUG | BSAM CFW NOCFW CTRx=n EFSDPAFT=(n)+ EFSDPBFR=(n)+ EQUCOUNT ESTAE NOESTAE NOASSIST

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


END

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--END--<<
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


INCLUDE

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--INCLUDE--COND=-(logical-expression)-.----------.----------<<
                                       +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE
Related reference
Field Types


INREC

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                      +--------,-------+
                      V                |
>---INREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--.---------.--<<
                        +-c:-+ |                                           |      +-convert-+
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE
Related reference
Field Types


MERGE

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--MERGE--FIELDS=-(logical-expression)--FORMAT=f-----<<
Note: The maximum size of a merge field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | (FILSZ=x | size=y]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE
Related reference
Field Types


MODS

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
         +----------------,-------------------+
         V                                    |
>--MODS--.-.-E15-.=-(-n,m.----------------.-)-.-+-.-------------.----<<
           +-E18-+       +-,-.---.-.----.-+       +-HILEVEL=YES-+
           +-E35-+           +-s-+ +-,e-+

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
MODS | (E18=n, m, [s] [e])+[HILEVEL=YES] (E39=n, m, [s] [e])+[HILEVEL=YES]

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


OMIT

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--OMIT--COND=--(logical-expression)-.----------.----------<<
                                     +-FORMAT=f-+

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

Limitations:

The maximum field length when comparing two fields that have the same format and the same length:

Format | MFJSORT | DFSORT and SYNCSORT
All | 256 | 256
CH (only when EBCDIC) | 128 | n/a

The maximum field length when comparing two fields that have the same format and differing lengths.

Format | MFJSORT | DFSORT and SYNCSORT
CH | 128 | 256
TS, CST | 19 | 256
ZD, OT, CTO, OL, CLO, LS, CSL | 18 | 256
FS, CSF | 18 | 32
PD | 10 | 255
PD0 | 8 | 8
BI, FI | 8 | 256
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE
Related reference
Field Types


OPTION

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
           +---------,-------------+
           V                       |
>--OPTION--.--.-CENTWIN---------.--.----------<<
              |                 |
              +-COPY------------+
              |                 |
              +-EFS=.-name-.----+
              |     +-NONE-+    |
              |                 |
              +-.-EQUALS---.----+
              | +-NOEQUALS-+    |
              |                 |
              +-OVFLO=.-RC0--.--+
              |       +-RC4--+  |
              |       +-RC16-+  |
                 |                 |
              +--SKIPREC=z------+
              |                 |
              +--STOPAFT=n------+
              |                 |
              +--Y2PAST=.-s-.---+
              |         +-f-+   |
              |                 |
              +-.-ZDPRINT--.----+
              | +-NZDPRINT-+    |
              |                 |
              +-VLSHRT----------+
Note: VLSHRT is ON by default.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
ARESALL | (n | nK | nM)
ARESINV | (n | nK | nM)
AVGRLEN | n
CHALT |
NOCHALT |
CHECK |
NOCHECK |
CINV |
NOCINV |
CKPT |
COBEXIT | (COB1 | COB2)
DSA | n
DSPSIZE | MAX
DYNALLOC | [=(d | n | d,n | OFF)]
EXITCK | (STRONG | WEAK)
FILSZ | (x | Ex | Ux)
SIZE | (y | Ey | Uy)
HIRPMAX | (OPTIMAL | n | P%)
LIST |
NOLIST |
LISTX |
NOLISTX |
LOCALE | (name | CURRENT | NONE)
MAINSIZE | (n | nK | nM | MAX)
MOSIZE | (MAX | n | p%)
MSGDDN | ddname
MSGPRT | (ALL | NONE | CRITICAL)
PRINT |
NOBLKSET |
NOOUTREL |
NOOUTSEC |
NULLOUT | (RC0 | RC4 | RC16)
ODMAXBF | (n | nK | nM)
PAD | (RC0 | RC4 | RC16)
RESALL | (n | nK | nM)
RESET |
NORESET |
RESINV | (n | nK | nM)
SDB | (LARGE | YES | INPUT | NO)
SMF | (SHORT | FULL | NO)
SOLRF |
NOSOLRF |
SORTDD | cccc
SORTIN | ddname
SORTOUT | ddname
SPANINC | (RC0 | RC4 | RC16)
SZERO |
NOSZERO |
TRUNC | (RC0 | RC4 | RC16)
USEWKDD |
VERIFY |
NOVERIFY |
VLLONG |
NOVLLONG |
VLSCMP |
NOVLSCMP |
NOVLSHRT |
VSAMEMT |
NVSAMEMT |
VSAMIO |
NOVSAMIO |
WRKREL |
NOWRKREL |
WRKSEC |
NOWRKSEC |

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


OUTFIL

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
           +----------------------------,-----------------------------------+
           |                                                                |
           |             +---,----+                                         |
           V             V        |                                         |
>--OUTFIL--.--.--FNAMES=-.-ddname-.---------------------------------------.-.----------<<
              |                                                           |
              |         +---,-----+                                       |
              |         V         |                                       |
              +--FILES=-.-.-d---.-.---------------------------------------+
              |           +-dd--+                                         |
              |           +-OUT-+                                         |
              |                                                           |
              +--STARTREC=-n----------------------------------------------+
              |                                                           |
              +-ENDREC=-n-------------------------------------------------+
              |                                                           |
              |           +------,---------+                              |
              |           V                |                              |
              +--OUTREC=-(.-item-statement-.)-.----------.-.------------.-+
              |                               +-,VTOF----+ +-VFILL=byte-+ |
              |                               +-,CONVERT-+                |
              |            +-------,--------+                             |
              |            V                |                             |
              +--OVERLAY=-(.-item-statement-.)----------------------------+
              |                                                           |
              |                                                           |
              |                                                           |
              +-.-INCLUDE=-.-(-logical-expression-)-.---.-----------------+
              | |          +-ALL--------------------+   |                 |
              | |          +-NONE-------------------+   |                 |
              | |                                       |                 |
              | |                                       |                 |
              + +-OMIT=-.-(logical-expression-)-.-------+                 |
              |         +-ALL-------------------+                         |
              |         +-NONE------------------+                         |
              |                                                           |
              +--SAVE-----------------------------------------------------+
              |                                                           |
              +--FTOV-----------------------------------------------------+
              |                                                           |
              +--VLTRIM=byte----------------------------------------------+
              |                                                           |
              +--SPLIT----------------------------------------------------+
              |                                                           |
              +--NULLOFL=-.-RC0--.----------------------------------------+
              |           +-RC4--+                                        |
              |           +-RC16-+                                        |
              |                                                           |
              +--LINES=n--------------------------------------------------+
              |                                                           |
              |           +--------,--------+                             |
              |           V                 |                             |
              +--HEADERn=-.-(-header-item-)-.-----------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--TRAILERn=-.-(-trailer-item-)-.---------------------------+
              |                                                           |
              |            +-------,----------+                           |
              |            V                  |                           |
              +--SECTIONS=-.-(-section-item-)-.---------------------------|
              |                                                           |
              +--NODETAIL-------------------------------------------------|
              |                                                           |
              +--REMOVECC-------------------------------------------------|
              |                                                           |
              +--CONVERT--------------------------------------------------+
Note: The maximum number of OUTFILs is 2048.

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--.---------.--<<
                        +-c:-+ |                                           |      +-convert-+
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.

The following options for the logical-expression field are supported:

>--relational-condition1--.----------------------------------------.---<<
                          | +-------------------.---------------+  |
                          | V                                   |  |
                          +-.-,-.-AND-.--,relational-condition2-.--.
                                +-OR--+

The following options for the relational-expression field are supported:

>--.-(p1,m1.---------.,binary-operator,-.-p2,m2,format-.)----------------.-->
   |       +-,format-+                  +-constant-----+                 |
   |                                                                     |
   +-(p1,m1,.-----.-.-EQ-.-,-.-constant-.-)------------------------------+
   |        +-SS,-+ +-NE-+   +-NUM------+                                |
   |                                                                     |
   +-(p1,m1,format,-.-EQ-.-,-NUM)----------------------------------------|
   |                +-NE-+                                               |
   |                                                                     |
   +-(p1,m1,-.----.-,-bit-operator,-mask)--------------------------------|
   |         +-BI-+                                                      |
   |                                                                     |
   +-(p1,m1,-.-------------.-,-binary-operator,-.-p2,m2,-.------------.)-+
             +-date-format-+                    |        +date-format-+
                                                +-constant------------+

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.

The following options for the header item are supported:

              +-------------,--------------------+
              V                                  |
>--HEADERn=--(.--.----.-.-r------------------.-)-.--<<
                 +-c:-+ +-.-DATE----------.--+
                        | +-&DATE---------+  |
                        | +-DATE=(abcd)---+  |
                        | +-&DATE=(abcd)--+  |
                        | +-DATENS=(abc)--+  |
                        | +-&DATENS=(abc)-+  |
                        |                    |
                        +-.-TIME--.----------+
                        | +-&TIME-+          |
                        |                    |
                        +-.-PAGE--.----------+
                          +-&PAGE-+

The following options for a trailer item are supported:

               +-------------,----------------------------------+
               V                                                |
>--TRAILERn=--(.--.----.-.-r--------------------------------.-)-.--<<
                  +-c:-+ +-.-DATE----------.----------------+
                         | +-&DATE---------+                |
                         | +-DATE=(abcd)---+                |
                         | +-&DATE=(abcd)--+                |
                         | +-DATENS=(abc)--+                |
                         | +-&DATENS=(abc)-+                |
                         |                                  |
                         +-.-TIME--.------------------------+
                         | +-&TIME-+                        |
                         |                                  |
                         +-.-PAGE--.------------------------+
                         | +-&PAGE-+                        |
                         |                                  |
                         +-.-COUNT-------.------------------|
                         | +-COUNT=edit--+                  |
                         |                                  |
                         +-.-SUBCOUNT-----------.-----------|
                         | +-SUBCOUNT15---------+           |
                         | +-SUBCOUNT=(.-edit-.)+           |
                         |             +-to---+             |
                         |                                  |
                         +-.-TOTAL-.=-(p,m,f.------.)-------+
                         | +-TOT---+        +-,to--+        |
                         |                                  |
                         +-MIN=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-MAX=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +-AVG=(p,m,f.------.)--------------+
                         |           +-,to--+               |
                         |                                  |
                         +--.-SUB------.=-(p,m,f.-------.)--+
                         |  +-SUBTOT---+        +-,edit-+   |
                         |  +-SUBTOTAL-+        +-,to---+   |
                         |                                  |
                         +--SUBMIN=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         |                                  |
                         +--SUBMAX=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         |                                  |
                         +--SUBAVG=-(p,m,f.-------.)--------+
                         |                +-,edit-+         |
                         |                +-,to---+         |
                         +----------------------------------+
Note: See the Limitations section for the COUNT and SUBCOUNT values, and the TOTAL, MIN, MAX, and AVG fields.

The following options for a sections item are supported:

              +------------------------------,--------------------------+
              |     +------------------------,------------------------+ |
              V     V                                                 | |
>--SECTIONS=-(.-p,m-.--.--------------------------------------------.-.-.)----<<
                       +-SKIP=.-P--.--------------------------------+
                       |      +-L--+                                |
                       |      +-nL-+                                |
                       |          +-----,-------+                   |
                       |          V             |                   |
                       +-HEADER3=(.-header-item-.)--.------------.--+
                       |                            +-,-PAGEHEAD-+  |
                       |           +-----,-------+                  |
                       |           V             |                  |
                       +-TRAILER3=(.-header-item-.)-----------------+

Limitations:

  • The maximum length of COUNT and SUBCOUNT values is 9 digits.
  • The maximum length of the TOTAL fields:
    TOTAL field formats | MFJSORT | SYNCSORT
    Length (m) | Digits (d) | Length (m) | Digits (d)
    ZD | 1-15 | *Maximum 18. | 1-15 | 15
    ZD | 16-31 | 16-31 | 31
    PD | 1-8 | 1-8 | 15
    PD | 9-16 | 9-16 | 31
    BI | 1-4 | 1-4 | 10
    BI | 5-8 | 5-8 | 20
    FI | 1-4 | 1-4 | 10
    FI | 5-8 | 5-8 | 20
    FL | 4 or 8 | 4 or 8 | 20
    CSF, FS | 1-15 | 1-15 | 15
    CSF, FS | 16-32 | 16-32 | 31

    * MFJSORT will display the total to the same amount of digits as specified in the length.

  • The TO parameter for TOTAL, MIN, MAX, and AVG is only applicable for TRAILER3.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE
Related reference
Field Types


OUTREC

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                      +--------,-------+
                      V                |
>--OUTREC--.-FIELDS=-(.-item-statement-.)----.---<<
           |                                 |
           |          +--------,----------+  |
           |          V                   |  |
           +-OVERLAY=(.-overlay-statement-.)-+

The following options for the item-statement field are supported:

                     +-------------,-----------------------------------------+
                     V                                                       |
>--item-statement=--(.--.----.-.-s-----------------------------------------.-.-)--.---------.--<<
                        +-c:-+ |                                           |      +-convert-+
                               +-p-----------------------------------------+
                               |                                           |
                               +-p,m.----.---------------------------------+
                               |    +-,a-+                                 |
                               |                                           |
                               +-p,m,format.-,edit-.-----------------------+
                               |           +-,to---+                       |
                               |                                           |
                               +-p,HEX-------------------------------------+
                               |                                           |
                               +-p,m,HEX-----------------------------------+
                               |                                           |
                               +-p,m,TRAN=LTOU-----------------------------+
                               |                                           |
                               +-p,m,TRAN=UTOL-----------------------------+
                               |                                           |
                               +-p,m,TRAN=ALTSEQ---------------------------+
                               |                                           |
                               +-p,m,Y2x(c)--------------------------------+
                               |                                           |
                               +-p,m,Y2xP----------------------------------+
                               |                                           |
                               +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                               |                                           |
                               +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following options for the overlay-statement field are supported:

                +-------------,-----------------------------------------+
                V                                                       |
>--OVERLAY--=--(.--.----.-.-s-----------------------------------------.-.-)--<<
                   +-c:-+ |                                           |
                          +-p,m---------------------------------------+
                          |                                           |
                          +-p,m.----.---------------------------------+
                          |    +-,a-+                                 |
                          |                                           |
                          +-p,m,format.-,edit-.-----------------------+
                          |           +-,to---+                       |
                          |                                           |
                          +-p,m,HEX-----------------------------------+
                          |                                           |
                          +-p,m,TRAN=LTOU-----------------------------+
                          |                                           |
                          +-p,m,TRAN=UTOL-----------------------------+
                          |                                           |
                          +-p,m,TRAN=ALTSEQ---------------------------+
                          |                                           |
                          +-p,m,Y2x(c)--------------------------------+
                          |                                           |
                          +-p,m,Y2xP----------------------------------+
                          |                                           |
                          +-p,m,CHANGE=(v,(find-set)+,[NOMATCH=(set)]-+
                          |                                           |
                          +-seqnum------------------------------------+
Note: For options p,m,Y2x(c), the (c) is only parsed and ignored in this COBOL system

The following field values are supported, where applicable:

Field | Values
a (alignment) | D (doubleword aligned), F (fullword aligned), H (halfword aligned).
s (separation) | ADD, DATE, &DATE, DATE=(abcd), &DATE=(abcd), DATE1, &DATE1, DATE1P, &DATE1P, DATE2, &DATE2, DATE2P &DATE2P, DATE3, &DATE3, DATE3P, &DATE3P, DATEn, &DATEn, DATEn+r, &DATEn+r, DATEn-r, &DATEn-r, DATEn(c), &DATEn(c), DATEn(c)+r, &DATEn(c)+r, DATEn(c)-r, &DATEn(c)-r, DATEnP, DATEnP+r, &DATEnP+r, DATEnP-r, &DATEnP-r, DATENS, &DATENS, DATENS=(abc), &DATENS=(abc), DIVIDE, LITERALS, MULTIPLY, SEPERATOR CHARS, SEQNUM, SUBTRACT.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


RECORD

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
>--RECORD--.-TYPE=-.-F-.--------------------.----<<
           |       +-V-+                    |
           +-.--------.--LENGTH=(L1,...,L3)-+
           | +-TYPE=F-+                     |
           +-.--------.--LENGTH=(L1,...,L7)-+
             +-TYPE=V-+
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE


SORT

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                    +---,---+                   +---------,------------+
                    V       |                   V                      |
>--SORT--FIELDS=-.-(.-p,m,f-.)----------------.-.--.-.-EQUALS---.---.--.----<<
                 |                            |    + +-NOEQUALS-+   |
                 |  +--,--------+             |    |                |
                 |  V           |             |    +-SKIPREC=z------+
                 +-(.-p,m,.---.-.)-,-FORMAT=f-+    +-STOPAFT=n------+
                 |        +-f-+               |    +-Y2PAST=-.-s-.--+
                 +-COPY-----------------------+    |         +-f-+  |
                                                   +-CENTWIN=-.-s-.-+
                                                              +-f-+
Note: The maximum size of a sort field is 256 characters.

In this COBOL system, the following parameter fields for this control statement are only parsed and ignored:

Parameter | Fields
FIELDS | CKPT DYNALLOC [=(d | n | d, n | OFF)] FILSZ = (x | Ex | Ux) SIZE = (y | Ey | Uy)

Use the following table as a guide to help you understand the options that are ignored:

Symbol | Meaning
(...) | Options within these brackets are required.
[...] | Options with these brackets are optional.
+ | This symbol follows a set of required or optional brackets to indicate that more than one option can be specified, delimited by a comma.
| | This symbol delimits options enclosed in required or optional brackets, to indicate a choice from these options.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE
Related reference
Field Types


SUM

The following parameters of this SYNCSORT control statement are supported in MFSORT and MFJSORT. To enable this support, set the MFJSENGINE environment variable.

Note: SYNCSORT emulation allows you to omit the equals sign (=) between a keyword and its bracketed parameters; for example, OUTREC(05:5,10).
                   +---,---+
                   V       |
>--SUM--FIELDS=-.-(.-p,m,f-.)----------------.----<<
                |                            |
                |  +--,--------+             |
                |  V           |             |
                +-(.-p,m,.---.-.)-,-FORMAT=f-+
                |        +-f-+               |
                +-NONE-----------------------+
Restriction: The maximum number of SUM fields is 600 and the maximum SUM field length is 18.

If required, use the SORTXSUM DD statement to write records that were deleted during a SUM process to a dataset. This occurs at the time of the SUM processing, and so will not undergo OUTREC, E35 or OUTFIL processing, which all occur after SUM processing.

The following field formats are supported, where applicable:

Field | Supported formats
Binary-operator | EQ, GE, GT, LE, LT, NE.
Bit-operator | ALL, BM, BNM, BNO, BNZ, BO, BZ, NONE, NOTALL, NOTNONE, NOTSOME, SOME.
Date-format | Y2B, Y2C, Y2D, Y2P, Y2S, Y2T, Y2U, Y2V, Y2W, Y2X, Y2Y, Y2Z, Y2TP, Y2UP, Y2VP, Y2WP, Y2XP, Y2YP.
Format | AQ, BI, CH, CLO, CSF, CSL, CST, CTO, FI, FL, FS, LS, OL, OT, PD, PD0, SB, SS, TS, ZD.
Parent topic: SYNCSORT Program Control Emulation
Related concepts
MFJSENGINE
Related reference
Field Types


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.

Windows: When specifying instructions on the command line, the maximum length of the mfsort command is 1024 characters. Characters after this limit are ignored, and if this truncation causes an invalid or incomplete command, an error is produced.

UNIX: 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 concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
Related information
Introduction
Creating a Statistics Report
Example Commands
Error Messages
Instructions


Instructions

The following is a list of valid mfsort instructions:

Instruction | Meaning
* | The rest of the line is treated as a comment. This is useful if you are supplying instructions via a text file as you can add comments to the file which explain the purpose of each instruction.
CHAR-EBCDIC | EBCDIC data. CHAR-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SIGN-EBCDIC | Numeric DISPLAY items with included signs are interpreted according to the EBCDIC convention. SIGN-EBCDIC is not required when CHAR-EBCDIC is specified; it is required for data that is otherwise ASCII, such as when the program which created the data was compiled with the SIGN"EBCDIC" Compiler directive. SIGN-EBCDIC must precede all SORT, MERGE, USE or GIVE instructions.
SORT-EBCDIC | Record-sequential ASCII files are sorted in EBCDIC order. Important: SORT-EBCDIC cannot sort files that have keys containing non-printable characters.
SORT/MERGE | These instructions specify either a sort or a merge option and must be followed by a FIELDS instruction specifying the field(s) to be used. The FIELDS instruction may optionally be followed by a RECORD instruction specifying the record size and format of the work file. SORT and MERGE are mutually exclusive.
FIELDS (instructions) | The fields on which the file is to be sorted or merged. See the section Fields Instruction.
RECORD definition | Record size and format. A RECORD instruction can be used to specify these details for the work file, input file(s) and output file(s). See the section RECORD Instruction.
USE input-file | Each USE instruction specifies an input file. You must specify all USE instructions before any GIVE instructions. See the section Defining Input and Output Files.
GIVE output-file | Each GIVE instruction specifies an output file. See the section Defining Input and Output Files.
INCLUDE/OMIT | Specifies conditions in which records will be included or omitted from the sort process. For details, see the IBM documentation to be found on the IBM Knowledge Center. INCLUDE and OMIT are mutually exclusive.
INREC | Reformats records before the SORT/MERGE process.
OUTREC | Reformats records following the SORT/MERGE process.
MODS | Specifies external procedures (user exits) that are executed, each time a record is released to or returned from the SORT/MERGE process. This implementation supports the E15 and E35 user exits.
SUM | Specifies that records with the same key value are returned as a single record. Optionally, a field may be specified to accumulate totals for all records with equal keys. The SUM operation can be done for the following control field types:
OUTFIL | This is used to specify complex editing and reporting to one or more output files. Each output file should be specified using a GIVE command. Otherwise, OUTFIL works as described in the IBM documentation, found on the IBM Knowledge Center.
OPTION | This can be used to specify various options. One of these options is COPY which results in records being copied, rather than sorted, to the output file.
  • FIELDS Instruction
  • Defining Input and Output Files
Parent topic: Invoking Mfsort
Related information
Invoking Mfsort
Fields Instruction
RECORD Instruction
Defining Input and Output Files


FIELDS Instruction

A SORT or MERGE instruction must be followed by a FIELDS instruction which specifies the fields on which the input file is to be sorted or merged.

A fields instruction takes the following form:

fields({start,length,type,order},...)

where the parameters are:

Parameter | Description
start | The starting position of the field in the record, counting in bytes from 1
length | The length of the field (bytes)
type | The type of data in the field. See the section Field Types .
order | The ordering of output, which can be either of: A - ascending D - descending

You can specify up to 100 fields by repeating the parameter set (start, length, type and order). Use commas to separate the parameters and the parameter sets.

  • Field Types
Parent topic: Instructions


Field Types

The following is a list of some of the available field types:

Field Type | Definition
AQ | Character with alternate collating sequence.
BI | COMP
C5 | COMP-5
C6 | COMP-6
CH | PIC X DISPLAY
CX | COMP-X
FL | Floating point, signed.
FS/CSF | Signed numeric, with optional leading floating sign.
LI/OL/CLO | PIC S9 LEADING INCLUDED
LS/CSL | PIC S9 LEADING SEPARATE
NU | PIC 9 DISPLAY
PD | PIC S9 COMP-3
PD0 | Packed decimal with first semi-byte and sign semi-byte ignored.
SB/FI | PIC S9 COMP
S5 | S9 COMP-5
SS | Substring. Used in conditions only.
TS/CST | PIC S9 TRAILING SEPARATE
TI/ZD/OT/CTO | PIC S9 TRAILING INCLUDED
Y2B | Two-digit, one-byte binary year data.
Y2C/Y2Z | Two-digit, two-byte year data, with optional trailing included sign. PIC 99 or PIC S99.
Y2D | Two-digit, one-byte packed decimal year data. PIC 99 COMP-6.
Y2P | Two-digit, two-byte packed decimal year data. PIC 99 COMP-3.
Y2S | Two-digit, two-byte character year data with special indicators. Binary zeros, blanks and binary ones are treated as special cases.
Y2T | Full date format, yyx...
Y2U | Full date format, yyx..., COMP-3.
Y2V | Full date format, yyx..., COMP-3. Ignores first semi-byte.
Y2W | Full date format, x...yy.
Y2X | Full date format, x...yy, COMP-3.
Y2Y | Full date format, x...yy, COMP-3. Ignores first semi-byte.

You can find other field types defined in the IBM documentation at SORT Control Statement.

Suppose that golf.dat is a relative file defined in a COBOL program as follows:

 file-control.
     select members-file
         assign to "d:\netexpress\base\workarea\golf.dat" (Windows) or
             assign to "/home/user/workarea/golf.dat" (UNIX)
         organization is relative
         access mode is random
         relative key is relative-key.
 data division.
 file section.
 fd members-file
     record contains 28 characters.
 01 members-record.
     03 members-number pic 9(6).
     03 members-lname pic x(10).
     03 members-fname pic x(10).
     03 members-handicap pic 9(2).

You can then use the following mfsort command to sort the file golf.dat on the field containing the membership number in ascending order:

mfsort sort fields(1,6,nu,a)
   use golf.dat record f,28 org rl
   give members.dat

The sorted version of the file is written to the file members.dat.

Parent topic: FIELDS Instruction


Defining Input and Output Files

You need to give instructions to define both the input and output files:

File Instructions
Input
USE input-file [record definition]
   [org organization] [key structure]
Output
GIVE output-file [record definition]
   [org organization] [key structure]
Note:
  • For input files that are either variable length or indexed files, you do not need to specify RECORD, ORG or KEY commands as the file characteristics can be deduced from the file itself.
  • If you omit any of the above instructions, the last specified values are used. Therefore, you need only specify values for the first file if the input and output files are all of the same type and format.
  • If the first file is variable length or indexed, you do not need to specify any of the values.
  • If you specify more than one input file, you cannot specify the same file as the output file unless it is the first input file specified.
  • You can use embedded library names and environment variables when you specify input and output files, in the same way as you can when you specify them in ASSIGN clauses; for more information see the sections Library Names in Paths and Filename Mapping in the chapter Filenames.
  • You can redirect the output file generated by MFSORT to another filename as follows:
    • If you do not use the SYSOUT environment variable, it is written to a file named SYSOUT.
    • If you do specify the SYSOUT environment variable, you specify the filename to be written to.
  • RECORD Instruction
  • ORG Instruction
  • KEY Instruction
Parent topic: Instructions


RECORD Instruction

You use the RECORD instruction to specify the format and length of records in the:

  • Sort work file
  • Input and output files when the instruction follows the associated USE or GIVE instruction

The RECORD instruction takes the following form:

RECORD format,rec-len,max-len

where the parameters are:

Parameter | Description
format | The record format, one of: F - fixed-length records of length rec-len V - variable-length records with a minimum length of rec-len and a maximum length of max-len
rec-len | If format is set to F, the record length If format is set to V, the minimum record length
max-len | If format is set to V, the maximum record length

If you do not specify a RECORD instruction for the sort workfile, the format defaults to fixed record format, with the record size equal to the largest record specified in the USE or GIVE instructions.

You do not need to specify a RECORD instruction for input files that are either variable length or indexed files as the file characteristics can be deduced from the file itself.

You must use a RECORD instruction if the record size is greater than 256.

If you do not specify a max-len for a line sequential input file, mfsort assumes 256. If you exceed this, the output file will have the input records split into several records.

Parent topic: Defining Input and Output Files


ORG Instruction

The ORG instruction specifies the file organization, and can be one of:

ORG Instruction | File Organization
IX | indexed
RL | relative
SQ | sequential (default value)
LS | line sequential

You do not need to specify an ORG instruction for input files that are either variable length or indexed files as the file characteristics can be deduced from the file itself.

Parent topic: Defining Input and Output Files


KEY Instruction

The KEY instruction specifies the key structure for an indexed file. It is used when an output file is indexed and its key structure is not the same as that of the indexed input file.

The format of the KEY instruction is:

KEY ({start,length,ixkey},...)

where the parameters are:

start
The starting position of the key in a record, counting in bytes from 1
length
The number of bytes in the key
ixkey
One of:
P
Primary key (this must always be defined first)
A
Alternate key
AD
Alternate key with duplicates
C
Component of the last-specified primary or alternate key

You can repeat the KEY instruction as often as required to describe the entire key structure. Use commas to separate the parameters and parameter sets (start, length, ixkey).

You must define the keys in order of importance with the primary key first, followed by all its components if it is split, then the first alternate key and all of its components and so on.

The following example defines three keys:

KEY (4,5,p,10,5,c,20,2,ad,40,2,a,46,10,c)

where:

4,5,p,10,5,c | represents the first primary key which is split. Its first component starts at character position 4 with a length of 5 bytes and its second component starts at character position 10 with a length of 5 bytes.
20,2,ad | represents the second (alternate) key which can have duplicates and starts at character position 20 with a length of 2 bytes
40,2,a,46,10,c | represents the third key. This is a split alternate key, with the first component starting at character position 40 with a length of 2 bytes and the second component starting at character position 46 with a length of 10 bytes.
Parent topic: Defining Input and Output Files


Creating a Statistics Report

There are two ways in which you can produce a statistics report for a SORT operation:

  • If you are not running under mainframe emulation, you can create a statistical report by using the MFJSTATS environment variable. For more information, see the section MFJSTATS in the appendix Environment Variables in your User's Guide.
    Note: Setting the environment variable MFJSTATS to ON creates a report containing statistics for the SORT that is displayed to SYSOUT (applies to Windows environments only). If a report file already exists for a previous SORT, the new statistics are appended to the end of the previous one. The syntax is MFJSTATS=ON.
  • If you are running under mainframe emulation, add the following to your JCL to create a spool output, in ASCII format, for the SORT operation:
    //MFJSTATS DD SYSOUT=*
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
Related information
Introduction
Invoking Mfsort
Example Commands
Error Messages


Example Commands

This section gives some examples of mfsort commands and jobstreams.

You may find it helpful to refer to the Examples of DFSORT Job Streams section of your DFSORT Application Programming Guide.

  • Sorting Using More Than One File
  • Single File Sort Using INCLUDE and a Sub-string Comparison
  • Single File Sort Using Environment Variables
  • Transforming Records Using OUTREC
  • Sort Using OUTFIL for Complex Reporting
Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Error Messages


Sorting Using More Than One File

Imagine four indexed files (north.dat, south.dat, east.dat and west.dat) which contain for the north, south, east and west of the country the scores achieved by members of a national organisation in a national competition. The COBOL syntax used to define north.dat is shown below:

 file-control.
     select idxfile assign to "north.dat"
         organization is indexed
         record key is member-id.
 data division.
 file section.
 fd idxfile
     record contains 39 characters.
 01 idxfile-record.
     03 member-id  pic 9(6).
     03 surname    pic x(15).
     03 first-name pic x(15).
     03 score      pic 9(3).

Each of the other files has been created in the same way and the results of the competition have been entered in the files. The following examples use these files.

  • Character Sort in Ascending Order
  • Numeric Sort in Descending Order
  • Omitting Records
Parent topic: Example Commands


Character Sort in Ascending Order

The following mfsort commands takes all of the records from each of the four files, sorts them on the member's surname in ascending order and outputs the result to the relative file members.dat:

mfsort sort fields(7,15,ch,a)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give members.dat org rl
Parent topic: Sorting Using More Than One File


Numeric Sort in Descending Order

The following mfsort command takes each of the four files, sorts them on the member's score (highest score first) and outputs the result to the relative file scores.dat:

mfsort sort fields(37,3,nu,d)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give scores.dat org rl
Parent topic: Sorting Using More Than One File


Omitting Records

The following mfsort command takes each of the four files, sorts them on the membership number (which is the primary key) and outputs the result to the indexed file national.dat. All records for which the score field is less than 20 are omitted:

mfsort sort fields(1,6,nu,a)
   use north.dat
   use south.dat
   use east.dat
   use west.dat
   give national.dat
   omit cond (37,3,nu,lt,20)
Parent topic: Sorting Using More Than One File


Single File Sort Using INCLUDE and a Sub-string Comparison

The following mfsort command takes a line sequential file, sortin.dat and sorts its records on a character field starting at position 11 with a length of 4 bytes. The results are output to the file sortout.dat which will include only records for which the sub-string, starting at position 15 of length 3 bytes, is equal to any three consecutive characters in the string 'J69,L92,J82'.

mfsort sort fields=(11,4,ch,a)
   use sortin.dat org ls record (f 80)
   give sortout.dat
   include cond=(15,3,ss,eq,c'J69,L92,J82')
Parent topic: Example Commands


Single File Sort Using Environment Variables

The following mfsort command takes a text file, unsorted.txt and a file a.1, sorts its records in ascending order, and outputs the result to the file sorted.txt.

set $infile=unsorted.txt
set $outfile=sorted.txt

mfsort take a.1

where unsorted. txt contains:

BBBBBBBBBBBBBBBBBBBB
CCCCCCCCCCCCCCCCCCCC
AAAAAAAAAAAAAAAAAAAA

and a.1 contains:

use $infile org LS
sort
give $outfile
Parent topic: Example Commands


Transforming Records Using OUTREC

The following mfsort command transforms records containing a field of format cyymmdd to the format yyymmdd.

Sort C'cyymmdd'
     SORT FIELDS=(1,7,BI,A)        * sort C'cyymmdd'
     use mfs110a.in org ls record (f 40)
    * Transform C'cyymmdd' to C'yyyymmdd'
     OUTFIL OUTREC=(1,1,CHANGE=(2, * change C'c' as follows:
                      C'0',C'19',  *   C'0' to C'19'
                      C'1',C'20',  *   C'1' to C'20'
                      C'2',C'21'), *   C'2' to C'21'
                      NOMATCH=(C'99')
                    2,6)           * copy C'yymmdd'

     give sortout.dat
Parent topic: Example Commands


Sort Using OUTFIL for Complex Reporting

The following is an example of how to use the OUTFIL command to produce a complex report, in this case a Profit and Loss report for one of four divisions. The input file, mfs121a.dat is sorted on the first two fields and only records from the western region are output. The SECTIONS instruction produces a page throw when the field starting in position 3, length 10 bytes changes. The following shows:

  • The input data
  • The mfsort command
  • The resultant output
  • Input Data
  • Mfsort Command
  • Output
Parent topic: Example Commands


Input Data

  Chips        San Martin     0088902203 West
  Chips        Oakland        0023412432 West
  Chips        San Jose       0123213335 West
  Ice Cream    Marin          0054234123 West
  Chips        Gilroy         0055484342 West
  Ice Cream    Napa           0085734283 West
  Pretzels     San Jose       0123488534 West
  Ice Cream    San Francisco  0092231245 West
  Chips        San Francisco  000324343q West
  Chips        San Jose       0123213335 South
  Ice Cream    San Martin     0100346730 West
  Pretzels     Marin          0534332344 West
  Chips        Gilroy         0055484342 South
  Chips        Morgan Hill    0098732232 West
  Pretzels     Morgan Hill    0084384340 West
  Ice Cream    San Jose       000002345u West
  Pretzels     Napa           0531234856 West
  Chips        Oakland        0023412432 South
  Pretzels     San Martin     000023438r West
  Chips        Los Angeles    000223401t West
  Ice Cream    Marin          0054234123 South
  Pretzels     San Francisco  0541230005 West
  Ice Cream    Napa           0085734283 South
  Pretzels     San Jose       0123488534 South
  Ice Cream    San Francisco  0092231245 South
  Chips        San Francisco  000324343q South
  Ice Cream    San Martin     0100346730 South
  Pretzels     Marin          0534332344 South
  Chips        Morgan Hill    0098732232 South
  Pretzels     Morgan Hill    0084384340 South
  Ice Cream    San Jose       000002345u South
  Pretzels     Napa           0531234856 South
  Pretzels     San Martin     000023438r South
  Chips        Los Angeles    0002234014 South
  Pretzels     San Francisco  0541230005 South
Parent topic: Sort Using OUTFIL for Complex Reporting
Related information
Mfsort Command
Output


Mfsort Command

SORT FIELDS=(3,10,A,16,13,A),FORMAT=CH

  use mfs121a.dat  org ls record (f 80)
  OUTFIL
   INCLUDE=(42,6,CH,EQ,C'West'),
   HEADER1=(5/,18:'    Western Region',3/,
               18:'Profit and Loss Report',3/,
               18:'     for  ',&DATE,3/,
               18:'      Page',&PAGE),
   OUTREC=(6:16,13,24:31,10,ZD,M5,LENGTH=20,75:X),
   SECTIONS=(3,10,SKIP=P,
    HEADER3=(2:'Division:  ',3,10,5X,'Page:',&PAGE,2/,
             6:'Branch Office',24:'       Profit/(Loss)',/,
             6:'-------------',24:'--------------------'),
    TRAILER3=(6:'=============',24:'====================',/,
             6:'Total',24:TOTAL=(31,10,ZD,M5,LENGTH=20),/,
             6:'Lowest',24:MIN=(31,10,ZD,M5,LENGTH=20),/,
             6:'Highest',24:MAX=(31,10,ZD,M5,LENGTH=20),/,
             6:'Average',24:AVG=(31,10,ZD,M5,LENGTH=20),/,
             3/,2:'Average for all Branch Offices so far:',
                X,SUBAVG=(31,10,ZD,M5))),
    TRAILER1=(8:'Page ',&PAGE,5X,'Date:  ',&DATE,5/,
            8:'Total Number of Branch Offices Reporting:  ',
              COUNT,2/,
            8:'Summary of Profit/(Loss) for all',
              ' Western Division Branch Offices',2/,
            12:'Total:',
                22:TOTAL=(31,10,ZD,M5,LENGTH=20),/,
            12:'Lowest:',
                22:MIN=(31,10,ZD,M5,LENGTH=20),/,
            12:'Highest:',
                22:MAX=(31,10,ZD,M5,LENGTH=20),/,
            12:'Average:',
                22:AVG=(31,10,ZD,M5,LENGTH=20))
      give outfil1.dat
Parent topic: Sort Using OUTFIL for Complex Reporting
Related reference
Input Data
Related information
Output


Output

                     Western Region

                 Profit and Loss Report

                      for  11/05/95

                       Page     1
************************************************************
  Division:  Chips          Page:     2

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Gilroy                     554,843.42
     Los Angeles                (22,340.14)
     Morgan Hill                987,322.32
     Oakland                    234,124.32
     San Francisco              (32,434.31)
     San Jose                 1,232,133.35
     San Martin                 889,022.03
     =============     ====================
     Total                    3,842,670.99
     Lowest                     (32,434.31)
     Highest                  1,232,133.35
     Average                    548,952.99

 Average for all Branch Offices so far:     548,952.99
************************************************************
  Division:  Ice Cream      Page:     3

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Marin                      542,341.23
     Napa                       857,342.83
     San Francisco              922,312.45
     San Jose                      (234.55)
     San Martin               1,003,467.30
     =============     ====================
     Total                    3,325,229.26
     Lowest                        (234.55)
     Highest                  1,003,467.30
     Average                    665,045.85

 Average for all Branch Offices so far:     597,325.02
************************************************************
  Division:  Pretzels       Page:     4

     Branch Office            Profit/(Loss)
     -------------     --------------------
     Marin                    5,343,323.44
     Morgan Hill                843,843.40
     Napa                     5,312,348.56
     San Francisco            5,412,300.05
     San Jose                 1,234,885.34
     San Martin                  (2,343.82)
     =============     ====================
     Total                   18,144,356.97
     Lowest                      (2,343.82)
     Highest                  5,412,300.05
     Average                  3,024,059.49

 Average for all Branch Offices so far:   1,406,236.51
************************************************************
        Page      5     Date:  11/05/95

       Total Number of Branch Offices Reporting:        18

       Summary of Profit/(Loss) for all Western Division
          Branch Offices

           Total:          25,312,257.22
           Lowest:            (32,434.31)
           Highest:         5,412,300.05
           Average:         1,406,236.51
Parent topic: Sort Using OUTFIL for Complex Reporting
Related reference
Input Data
Related information
Mfsort Command


Workfile

During a sort or merge operation, mfsort uses a temporary workfile. This workfile is paged to disk in the current directory or, if it is set, in the directory specified by the TMP or TEMP (Windows) or TMPDIR (UNIX) environment variable. If not set, the current working directory is used.

Mfsort copies all the records from each of the input files to the temporary workfile, truncated or padded as appropriate. The workfile is then sorted or merged according to its key description. After being sorted or merged in the workfile, the records are copied to each of the output files and truncated or padded as appropriate.

During this operation:

  • If you do not need any of the records to be truncated, you must ensure that the record length of the workfile is sufficient for the longest record to be sorted
  • If your input files are of variable length and the sort workfile is not, all concept of variable-length is lost
  • If your input file is fixed length and the workfile is variable length, the record length of the record in the workfile is either the fixed length of the input file or the maximum record length of the workfile, whichever is the smaller


Error Messages

A full list of mfsort error messages is given in the topic Mfsort Error Messages.

Parent topic: Sort Utilities
Related concepts
DFSORT and ICETOOL Emulation
SYNCSORT Emulation
Related information
Introduction
Invoking Mfsort
Creating a Statistics Report
Example Commands
Mfsort Error Messages


Btrieve

Btrieve is the file handling system from Pervasive Software Inc.
Note: This module is only supported for native COBOL, in a Windows environment.

For full details on Btrieve, consult the Btrieve manuals supplied by Pervasive Software. To process Btrieve files in Enterprise Developer, use the Xfh2btr call conversion module.

The Btrieve run-time system is not supplied with this COBOL development system. It is assumed that you already have a copy of the Btrieve run-time system or a Btrieve Developer's Kit. You are not allowed to distribute the Btrieve run-time system to any third party unless you have entered into a License Agreement with Pervasive Software. Contact Pervasive Software for more information.

  • Xfh2btr Call Conversion Module
  • Calling Xfh2btr
  • Btrieve Environment Variables
  • Xfh2btr Configuration File
  • Xfh2btr Differences
  • Calling Btrieve in Non-ANSI Mode
  • Btrieve 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
Sort Utilities
Data and Key Compression
Tracing File Operations


Xfh2btr Call Conversion Module

The Xfh2btr call conversion module enables you to use the Micro Focus File Handler API to access Btrieve files from this COBOL system.

Btrieve does not normally conform to ANSI standards but, by default, the Xfh2btr call conversion module makes the necessary calls to the Btrieve run-time system to force it to emulate ANSI behavior. You can, however, choose to operate in non-ANSI mode.

Xfh2btr is compatible with versions of Btrieve 6.1x and above.

It is supplied as part of this COBOL system and also as a linkable module, xfh2btr.obj, which can be linked with any application that needs to perform I/O on Btrieve files.

When the call conversion module needs to call the Btrieve run-time system to perform I/O, it calls the module _BTRV. The function of this module is to format the call and pass it to the Btrieve Microkernel Interface (wbtrv32.dll for Windows). Note that you can call the module _BTRV directly from your COBOL program using the same parameters as those used in Btrieve API calls (see your Btrieve Programmer's Reference Manual).

Parent topic: Btrieve
Related information
Calling Xfh2btr
Btrieve Environment Variables
Xfh2btr Configuration File
Xfh2btr Differences
Calling Btrieve in Non-ANSI Mode
Btrieve Error Messages


Calling Xfh2btr

There are three ways of calling the Xfh2btr call conversion module:

  • Use the CALLFH Compiler directive
  • Use the FILETYPE Compiler directive
  • Use external filename assignment

Note that some file operations and formats are not supported by Btrieve; for example, WRITE AFTER and line sequential files. In these cases, if you try and direct file I/O to the converter, you will get an error returned to your program.

  • CALLFH Compiler Directive
  • FILETYPE Compiler Directive
Parent topic: Btrieve
Related information
Xfh2btr Call Conversion Module
Btrieve Environment Variables
Xfh2btr Configuration File
Xfh2btr Differences
Calling Btrieve in Non-ANSI Mode
Btrieve Error Messages


CALLFH Compiler Directive

The CALLFH Compiler directive specifies the file handler used by your program to perform all COBOL I/O operations. By default, if no file handler is specified, the Micro Focus File Handler is used.

If you use the CALLFH Compiler directive to specify the Xfh2btr call conversion module, your program passes all I/O to the Xfh2btr call conversion module so that COBOL I/O operations are converted to Btrieve I/O operations.

You can include CALLFH at the top of your source program as an initial $SET statement as follows:

$set callfh"xfh2btr"
Parent topic: Calling Xfh2btr
Related information
FILETYPE Compiler Directive


FILETYPE Compiler Directive

The FILETYPE Compiler directive specifies the format of files created by your program.

You can put the FILETYPE Compiler directive at the top of your program as an initial $SET statement as follows:

$set filetype"n"

where n, in this case, can be either 5 or 6.

FILETYPE"5" is used when it is important for file operations to conform to ANSI standards. Btrieve does not normally conform to ANSI standards and this mode of operation requires a number of calls to the Btrieve run-time system to force it to emulate ANSI behavior.

FILETYPE"6" is used when speed is important. In this mode of operation, each Micro Focus File Handler operation is mapped to the nearest Btrieve run-time call. No attempt is made to conform to ANSI standards.

You can mix different types of file in your program by putting the FILETYPE Compiler directive around individual SELECT statements, for example:

$set filetype"0"
select testfile-1 assign to "test-1.dat"
   organization indexed
   record key prime-key
   access sequential.
$set filetype"5"
select testfile-2 assign to "test-2.dat"
   organization relative
   access sequential.

In the above example, all I/O on test-1.dat is handled by the Micro Focus File Handler while all I/O on test-2.dat is handled by the Xfh2btr call conversion module.

Note: Note:

To specify the format to use when creating an indexed file, you can include the IDXFORMAT parameter under that file's settings in your File Handler configuration file. Set IDXFORMAT to either 5 or 6 to indicate Btrieve with or without ANSI conformance respectively. For more information, see the chapter File Handler Configuration.

Parent topic: Calling Xfh2btr
Related information
CALLFH Compiler Directive
File Handler Configuration


Btrieve Environment Variables

There are two environment variables that you can set to change the way in which the Xfh2btr call conversion module operates: BTRPAGE and BTRMAXREC.

  • BTRPAGE Environment Variable
  • BTRMAXREC Environment Variable
Parent topic: Btrieve
Related information
Xfh2btr Call Conversion Module
Calling Xfh2btr
Xfh2btr Configuration File
Xfh2btr Differences
Calling Btrieve in Non-ANSI Mode
Btrieve Error Messages


BTRPAGE Environment Variable

The BTRPAGE environment variable specifies the page size that is used when Btrieve files are created. You can set it using the following command:

set BTRPAGE=nnn

where nnn is a byte value in the range 512 to 4096 inclusive, in multiples of 512 bytes. The value must be greater than the record size.

If you do not set BTRPAGE, or you specify a wrong value, the page size defaults to 1024 bytes.

Note: Notes:

  • The page size affects the number of keys you can define in the file and where the keys can occur in the record
  • The Btrieve Record Manager must be loaded with the correct page size
  • You can specify the value of BTRPAGE on a per-file basis using the xfh2btr configuration file
Parent topic: Btrieve Environment Variables
Related information
BTRMAXREC Environment Variable


BTRMAXREC Environment Variable

The BTRMAXREC environment variable specifies the maximum record size.

You can set BTRMAXREC using the following command:

set BTRMAXREC=nnnn

where nnnn is a byte value specifying the maximum record length.

You should set BTRMAXREC to the record size of the largest record to be accessed.

If you do not set BTRMAXREC, the default value of 32 Kilobytes is used.

You can specify the value of BTRMAXREC on a per-file basis using the xfh2btr configuration file.

Parent topic: Btrieve Environment Variables
Related information
BTRPAGE Environment Variable


Xfh2btr Configuration File

Note: Note:

If you need to use the Xfh2btr configuration file you must link your program with mfini.obj.

The Xfh2btr configuration file enables you to specify the page size, maximum record length and Btrieve open mode for all files or for an individual file.

You can specify the name of the configuration file via the XFH2BTR environment variable. If this environment variable is not set, the default configuration filename of xfh2btr.cfg is used. The configuration file is searched for first in the current directory and then along the path specified by the COBDIR environment variable.

The tag [X2B-DEFAULTS] is used to specify default values for page size, maximum record length and Btrieve open mode while a tag containing a filename (for example [test.dat]) is used to specify values for a particular file.

  • Page size
  • Maximum record length
  • Btrieve open mode

Attribute names can be separated from attribute values by a space or a colon (:) character.

Note: Note:

If a configuration file exists, the settings of the Btrieve environment variables BTRPAGE and BTRMAXREC are ignored.

You can also turn on the Xfh2btr trace option and specify the name of the trace file via the Xfh2btr configuration file.

  • Page Size
  • Maximum Record Size
  • Btrieve File Open Mode
  • Example Xfh2btr Configuration File
  • Trace Option
Parent topic: Btrieve
Related information
Xfh2btr Call Conversion Module
Calling Xfh2btr
Btrieve Environment Variables
Xfh2btr Differences
Calling Btrieve in Non-ANSI Mode
Btrieve Error Messages


Page Size

You can specify the page size to use when creating a Btrieve file by setting an attribute in the Xfh2btr configuration file as follows:

BTRPAGE:nnn

where nnn is a byte value in the range 512 to 4096 inclusive, in multiples of 512 bytes.

If you do not set BTRPAGE, or you specify a wrong value, the page size defaults to 1024 bytes.

Parent topic: Xfh2btr Configuration File
Related information
Maximum Record Size
Btrieve File Open Mode
Example Xfh2btr Configuration File
Trace Option


Maximum Record Size

You can specify the maximum record size for a Btrieve file by setting an attribute in the Xfh2btr configuration file as follows:

BTRMAXREC:nnnn

where nnnn is a byte value. You should set BTRMAXREC to the record size of the largest record to be accessed. If you do not set BTRMAXREC, the default value of 32 Kilobytes is used.

Parent topic: Xfh2btr Configuration File
Related information
Page Size
Btrieve File Open Mode
Example Xfh2btr Configuration File
Trace Option


Btrieve File Open Mode

You can use the Xfh2btr configuration file to specify the Btrieve open mode used to open a file:

INPUT-EXCLUSIVE:open-mode
INPUT-SHAREABLE:open-mode
OUTPUT:open-mode
EXTEND-EXCLUSIVE:open-mode
EXTEND-SHAREABLE:open-mode
I-O-EXCLUSIVE:open-mode
I-O-SHAREABLE:open-mode

The possible values of open-mode are: normal, accelerated, read-only, verify, exclusive. For further details on these open modes, consult your Btrieve documentation.

Parent topic: Xfh2btr Configuration File
Related information
Page Size
Maximum Record Size
Example Xfh2btr Configuration File
Trace Option


Example Xfh2btr Configuration File

[X2B-DEFAULTS]
output:accelerated
i-o-shareable:accelerated
i-o-exclusive:accelerated
btrpage:2048
btrmaxrec:2000
[test1.dat]
output:exclusive
i-o-shareable:normal
btrpage:4096

The above is an example Xfh2btr configuration file which specifies the following:

  1. The default open mode for files opened OUTPUT is accelerated
  2. The default open mode for files opened I/O which are shareable is accelerated
  3. The default open mode for files opened I/O which are exclusive is accelerated
  4. The default page size to use when creating files is 2048 bytes
  5. The default maximum record length is 2000 bytes
  6. For the file test1.dat, OPEN OUTPUT operations open the file exclusively
  7. For the file test1.dat, OPEN I/O operations which are shareable use the normal open mode
  8. For the file test1.dat, the page size to use when creating the file is 4096 bytes
Parent topic: Xfh2btr Configuration File
Related information
Page Size
Maximum Record Size
Btrieve File Open Mode
Trace Option


Trace Option

If the Xfh2btr trace option is set, every operation performed by the Xfh2btr call conversion module and every error code returned by the Btrieve Record Manager are either displayed on the screen or recorded in a trace file.

If an error is returned by the Btrieve Record Manager, the Xfh2btr call conversion module maps the Btrieve error to a COBOL file status code which it returns to your program. The COBOL file status code to which a Btrieve error has been mapped is also displayed in the trace file.

If a Btrieve error is not shown on the trace but a COBOL file status is returned, the error has been generated in the Xfh2btr call conversion module. For example, trying to write to a file opened for input would generate such an error.

There are two attributes that effect the trace option: TRACE-FILE and TRACE.

TRACE-FILE:filename

This specifies that the trace information is to be directed to the specified file and not to the screen. If no filename is specified, the default filename, xfh2btr.lst, is used. The trace-file attribute can only be specified under the [X2B-DEFAULTS] tag. If a number of client applications are writing trace information to the same trace file, the order in which the information appears in the file is undetermined.

Note: Note:

Specifying a trace filename does not turn on the TRACE facility.

TRACE

The TRACE attribute switches tracing on. It can be specified under the [X2B-DEFAULTS] tag (in which case operations on all files are traced) or under a filename tag (in which case only operations on that file are traced).

  • Example Trace Option Settings
  • Example Trace Output
Parent topic: Xfh2btr Configuration File
Related information
Page Size
Maximum Record Size
Btrieve File Open Mode
Example Xfh2btr Configuration File


Example Trace Option Settings

The following entries in the Xfh2btr configuration file:

[X2B-DEFAULTS]
trace-file:x2btrace.dat
trace:

specify that tracing is on for every file and that the trace information is written to the file x2btrace.dat.

The following entries in the Xfh2btr configuration file:

[X2B-DEFAULTS]
trace-file:
[test1.dat]
trace:

specify that tracing is on for the file test1.dat and that the trace information is written to the file xfh2btr.lst (the default trace filename).

Parent topic: Trace Option
Related information
Example Trace Output


Example Trace Output

Below is an example of the output produced when the trace option is used:

                                                Line
Input FA01 ifile1.tmp                            1
Output Btrieve Error=+0000 COBOL Error=0/0       2
Input FAF3 ifile1.tmp                            3
Output Btrieve Error=+0000 COBOL Error=0/0       4
Input FAF3 ifile1.tmp                            5
Output Btrieve Error=+0000 COBOL Error=0/0       6
Input FADC All Files                             7
Output Btrieve Error=+0000 COBOL Error=0/0       8
Input FA80 ifile1.tmp                            9
Output Btrieve Error=+0000 COBOL Error=0/0      10
Input FA02 ifile1.tmp                           11
Output Btrieve Error=+0000 COBOL Error=0/0      12
Input FAF5 ifile1.tmp                           13
Output Btrieve Error=+0000 COBOL Error=0/0      14
Input FAF5 ifile1.tmp                           15
Output Btrieve Error=+0000 COBOL Error=0/0      16
Input FAF5 ifile1.tmp                           17
Output Btrieve Error=+0009 COBOL Error=1/0      18
Input FA80 ifile1.tmp                           19
Output Btrieve Error=+0000 COBOL Error=0/0      20
Input FA01 test.dat                             21
Output Btrieve Error=+0029 COBOL Error=9/078    22
Input FA00 ifile1.tmp                           23
Output Btrieve Error=+0000 COBOL Error=0/0      24
Input FAF3 ifile1.tmp                           25
Output Btrieve Error=+0000 COBOL Error=4/8      26
Input FA80 ifile1.tmp                           27
Output Btrieve Error=+0000 COBOL Error=0/0      28

Line 1 shows an example input line: the operation code and the name of the file on which the operation is being performed.

Line 2 shows an example output line: the Btrieve error status and the error being returned to the COBOL application.

Line 7 shows an example of an operation (in this case, COMMIT) being performed on all open files.

Line 22 shows the error status 29 being returned from the Btrieve run-time system and that this is returned to the COBOL application as a 9/078 status. For details of the Btrieve error status 29, see the relevant Btrieve documentation.

Line 26 shows an error that is generated in the Xfh2btr module. An attempt is being made to write to a file which is opened for INPUT.

Parent topic: Trace Option
Related information
Example Trace Option Settings


Xfh2btr Differences

The majority of COBOL file operations performed by the Micro Focus File Handler operate in exactly the same way when performed by Xfh2btr on Btrieve files. However, due to underlying differences between the two systems, there are instances where behavior differs. These include:

  • Keys
  • Locked record detection
  • OPEN OUTPUT operation
  • Record lengths
  • Current Record Pointer (CRP)
  • Transaction processing
  • WRITELOCK
Note: Note:

You should especially note the positioning of the current record pointer (CRP) when performing sequential read operations after having written, rewritten or deleted records in a file.

  • Keys
  • Locked Record Detection
  • OPEN OUTPUT Operation
  • Record Lengths
  • Current Record Pointer (CRP)
  • Transaction Processing
  • WRITELOCK Compiler Directive
Parent topic: Btrieve
Related information
Xfh2btr Call Conversion Module
Calling Xfh2btr
Btrieve Environment Variables
Xfh2btr Configuration File
Calling Btrieve in Non-ANSI Mode
Btrieve Error Messages


Keys

With keys, the differences are:

  • Using Btrieve v5.x or earlier, the total number of key components per file (a normal key has one component, a split key has more than one) cannot exceed 24. So, you can have one key of 24 components, 24 keys of one component or any combination of these.
  • Using Btrieve v6.x or later, the maximum number of key components depends on the page size of the file. The page size of a file can be specified via the Btrieve environment variable, BTRPAGE or via the Xfh2btr configuration file. For files with a page size of 4096 bytes, the maximum number of key components is 119. See your Btrieve documentation for more details.
  • The Xfh2btr module does not verify the number of key components in the file; if your version of Btrieve does not support the required number of key components then any error returned from the Btrieve run-time system is reported to your application program
  • The total length of any key in a Btrieve file cannot exceed 255 bytes
  • All keys in a Btrieve file must be completely contained in the fixed part of a variable length file
  • Using Btrieve, you cannot perform a START operation with a part-key; you must use the whole key
Parent topic: Xfh2btr Differences
Related information
Locked Record Detection
OPEN OUTPUT Operation
Record Lengths
Current Record Pointer (CRP)
Transaction Processing
WRITELOCK Compiler Directive


Locked Record Detection

When this COBOL system reads a record that is locked by another user, the record data is returned to the program together with a COBOL file status of 9/068 ("Record locked").

With Btrieve, if a record is locked, the data is not returned and so reading a locked record requires multiple calls to the Btrieve run-time system, making default record reading slower.

You can improve the speed of read operations by:

  • Opening the file with an exclusive lock

    When you do this, calls to the Btrieve run-time system to detect record locks are not required because the file is locked exclusively and so individual records do not need to be checked

  • Using the NODETECTLOCK Compiler directive

    If this directive is set no calls are made to the Btrieve run-time system to see if the record is locked by another user

  • Accessing the file from a transaction

    When you access a Btrieve file from a transaction, a temporary exclusive lock is obtained on the file and so calls to the Btrieve run-time system to detect record locks are not required

Parent topic: Xfh2btr Differences
Related information
Keys
OPEN OUTPUT Operation
Record Lengths
Current Record Pointer (CRP)
Transaction Processing
WRITELOCK Compiler Directive


OPEN OUTPUT Operation

The COBOL OPEN OUTPUT operation creates a file and opens it with an exclusive lock. This is performed in a single operating system call. With Btrieve, this operation requires two calls to the Btrieve run-time system, the first to create the file and the second to open the file with an exclusive lock. Because a small time lapse exists between these two calls, it is possible for a second user to access the file between the time that the file is created and the time that it is opened. If this happens, the second user finds the file empty and an attempt to read the file results in an "at end" error. The user performing the OPEN OUTPUT receives a "file locked" error because the exclusive OPEN call fails.

Parent topic: Xfh2btr Differences
Related information
Keys
Locked Record Detection
Record Lengths
Current Record Pointer (CRP)
Transaction Processing
WRITELOCK Compiler Directive


Record Lengths

In a Btrieve file, variable length records consist of two parts: a fixed length part and a variable length part. Fixed length records consist of only the fixed length part.

For variable length records, the fixed length part of the record is usually determined by the minimum record length defined in your COBOL program. However, depending on the number of keys which allow duplicates and the page size used, Btrieve may impose restrictions on the maximum length of the fixed part of the record. The formula for determining the maximum length of the fixed part of a record is given below:

p - 6 - ( 8 * k ) [- 4 for variable length records] [- 4 for relative files]

where the parameters are:

p
The page size of the file.
k
The number of keys that allow duplicates.
Note:
  • If you try to create a Btrieve file with fixed length records and specify a record length that is greater than the maximum size allowed for the fixed part of the Btrieve record, the file is created as a variable length Btrieve file with the fixed part set to the maximum size allowed
  • If you try and create a Btrieve file with variable length records and specify a minimum record length that is greater than the maximum size allowed for the fixed part, the file is created with the fixed part set to the maximum size allowed
  • Btrieve requires that all the keys are defined in the fixed part of a Btrieve record
  • Relative files are created as Btrieve keyed files with a four-byte auto-increment key at the front of each record. This processing of the key is transparent to the user program. However, the physical Btrieve file has a fixed record length four bytes larger than that calculated using the above formula.
  • Example of Btrieve Record Lengths
Parent topic: Xfh2btr Differences
Related information
Keys
Locked Record Detection
OPEN OUTPUT Operation
Current Record Pointer (CRP)
Transaction Processing
WRITELOCK Compiler Directive


Example of Btrieve Record Lengths

The following examples use a page size of 1024 bytes:

  • A fixed length record index file with a record length of 1018 bytes creates a fixed length record Btrieve file with a fixed record length of 1018 bytes

    All the keys must be in the first 1018 bytes of the record

  • A fixed length record index file with a record length of 1019 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes

    All the keys must be in the first 1014 bytes of the record

  • A fixed length record index file with a record length of 1010 bytes and one key which allows duplicates creates a fixed length record Btrieve file with a fixed record length of 1010 bytes

    All of the keys must be in the first 1010 bytes of the record

  • A fixed length record index file with a record length of 1011 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes

    All of the keys must be in the first 1006 bytes of the record

  • A fixed length record relative file with a record length of 1014 bytes creates a fixed length record Btrieve file with a fixed record length of 1018 bytes

    The additional four bytes is due to the auto-increment key that is added automatically to the front of each record. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1014 bytes.

  • A fixed length relative file with a record length of 1015 bytes creates a variable length Btrieve file with a fixed record length of 1014 bytes. This is because you are limited to a maximum of 1014 bytes.

    This length includes the additional four bytes automatically added to the front of each record, due to the auto-increment key. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1010 bytes.

  • A variable length record index file with a minimum record length of 1014 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes

    All of the keys must be in the first 1014 bytes of the record

  • A variable length record index file with a minimum record length of 1015 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes

    All of the keys must be in the first 1014 bytes of the record

  • A variable length record index file with a minimum record length of 1006 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes

    All of the keys must be in the first 1006 bytes of the record

  • A variable length record index file with a minimum record length of 1007 bytes and one key which allows duplicates creates a variable length record Btrieve file with a fixed record length of 1006 bytes

    All of the keys must be in the first 1006 bytes of the record

  • A variable length record relative file with a minimum record length of 1010 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes

    The additional four bytes is due to the auto-increment key that is added automatically to the front of each record. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1010 bytes.

  • A variable length record relative file with a minimum record length of 1011 bytes creates a variable length record Btrieve file with a fixed record length of 1014 bytes

    The additional four bytes is due to the auto-increment key that is added automatically to the front of each record. If you are using the opcode 06 action-code for the Micro Focus File Handler call interface, the record length returned is 1010 bytes.

Parent topic: Record Lengths


Current Record Pointer (CRP)

With this COBOL system, the Current Record Pointer (CRP) is only affected when START, READ (sequential or random) and OPEN operations are performed on the file.

With the Btrieve run-time system, however, the CRP is affected by WRITE, REWRITE and DELETE operations. This means that, following these operations, the CRP in a Btrieve file has to be restored to its original position so that sequential READ statements are not affected.

In a shared environment, the re-positioning of the CRP can fail if the record to be re-positioned on has been deleted by another user. If this happens, any attempt to perform a sequential READ returns an error.

In the following sections, re-positioning of the CRP is performed after the operation has completed and not at the time of the next sequential READ statement. This reduces the possibility of the record being deleted and increases the possibility of successfully re-positioning the CRP.

Note: Note:

The non-ANSI conforming mode of operation does not try to re-position the CRP and can, therefore, be significantly faster.

  • Sequential READ Operations After WRITE Operations
  • Sequential READ Operations After DELETE Operations
  • Sequential READ Operations After REWRITE Operations
Parent topic: Xfh2btr Differences
Related information
Keys
Locked Record Detection
OPEN OUTPUT Operation
Record Lengths
Transaction Processing
WRITELOCK Compiler Directive


Sequential READ Operations After WRITE Operations

For shared files opened I/O that are not in transactions where the ANSI conforming mode of operation is being used, the file is actually opened twice. The first open of the file is used to read records from the file. The second open of the file is used to write records to the file. Therefore, it is not possible for the reading position to be affected by normal WRITE operations. However, if you use the WRITELOCK directive, the inserted record has to be read back with a lock and this changes the CRP in the file.

Re-positioning the Btrieve file position indicator after a WRITE operation can only fail if WRITELOCK directives are used and the file is shareable. If the re-positioning after the WRITE operation fails, an error is returned when the sequential READ is attempted.

Parent topic: Current Record Pointer (CRP)
Related information
Sequential READ Operations After DELETE Operations
Sequential READ Operations After REWRITE Operations


Sequential READ Operations After DELETE Operations

For files opened I/O with random or dynamic access, the Btrieve file position indicator has to be moved to the position of the record to be deleted. After performing the DELETE operation, the file position indicator is restored to its original position, although this could fail if the record to re-position on has been deleted.

This problem does not occur for files with sequential access because the file position indicator is already on the record to be deleted and so re-positioning is not necessary.

Note: Note:

It is not possible to perform a sequence of sequential READ and DELETE statements when the key of reference is on a key which allows duplicates. This is because it is not possible to re-position the CRP after the DELETE operation.

Parent topic: Current Record Pointer (CRP)
Related information
Sequential READ Operations After WRITE Operations
Sequential READ Operations After REWRITE Operations


Sequential READ Operations After REWRITE Operations

For files opened I/O with random or dynamic access, the Btrieve file position indicator is moved to the position of the record to be changed. After performing the REWRITE operation, the file position indicator is restored to its original position, although this could fail if the record to re-position on has been deleted.

This problem does not occur for files with sequential access because the file position indicator is already on the record to be rewritten and so re-positioning is not necessary.

Parent topic: Current Record Pointer (CRP)
Related information
Sequential READ Operations After WRITE Operations
Sequential READ Operations After DELETE Operations


Transaction Processing

In this COBOL system, transaction processing is only available if you are using Fileshare but Btrieve users do not require Fileshare to implement transaction processing.

When you update records in a file in a transaction with Fileshare, the individual records in the file are locked to prevent another user from reading the record. This is because there is the possibility of a ROLLBACK operation being performed when a record has been removed from the file. However, when you access a Btrieve file via Xfh2btr from a transaction, the whole file is given a temporary exclusive file lock which prevents other users from accessing the file at the same time. In Btrieve v6.x and later, concurrent transactions are used, so files can be shared in a transaction.

A Btrieve transaction starts whenever a REWRITE, WRITE or DELETE operation is performed for a file that has no transaction in progress and has been opened with ROLLBACK. At this point, Btrieve obtains an exclusive lock on the file and this file lock remains until the transaction finishes, except when concurrent transactions are in use (Btrieve v6.x and later).

Note: Notes:
  • For Btrieve v6.x or above, concurrent Btrieve transactions are used. Btrieve then performs locking at the page level. (See the Btrieve documentation for details.)
  • A transaction finishes when a COMMIT or ROLLBACK operation is performed. The transaction restarts when I/O is performed again on a file which is opened with ROLLBACK.

The CLOSE operation does not re-start transactions because Btrieve CLOSE operations can only be performed when transactions are not active.

File-locked errors are returned by Xfh2btr at the time files are opened, as this is the only time that this COBOL system returns a file-locked error. Btrieve can return a file-locked error on accessing a file in a transaction, although this is converted to a record-locked error by Xfh2btr which is a status that could legitimately be returned by this COBOL system when accessing files in transactions.

Parent topic: Xfh2btr Differences
Related information
Keys
Locked Record Detection
OPEN OUTPUT Operation
Record Lengths
Current Record Pointer (CRP)
WRITELOCK Compiler Directive


WRITELOCK Compiler Directive

With this COBOL system you can use the WRITELOCK Compiler directive to write a record to a file and obtain a lock on the record written. Locks are also obtained on records that are re-written to the file.

With Btrieve the record is first written or re-written to the file and then read back to obtain a lock on the record. This requires a number of calls to the Btrieve run-time system with small time lapses between the calls. It is possible, therefore, for a second user to access the record and obtain a lock on the written record before it can be read back with a lock by the first user.

Parent topic: Xfh2btr Differences
Related information
Keys
Locked Record Detection
OPEN OUTPUT Operation
Record Lengths
Current Record Pointer (CRP)
Transaction Processing


Calling Btrieve in Non-ANSI Mode

Btrieve does not normally conform to ANSI standards but, by default, the Xfh2btr call conversion module makes the necessary calls to the Btrieve run-time system to force it to emulate ANSI behavior. You can, however, choose to operate in non-ANSI mode by setting the FILETYPE Compiler directive to FILETYPE"6".

In this mode of operation, each Micro Focus File Handler operation is mapped to the nearest Btrieve run-time call and no attempt is made to conform to ANSI standards:

  • Any run-time system switches you set in this COBOL system are ignored by the Xfh2btr call conversion module
  • The operation proceeds as if you had specified the NODETECTLOCK Compiler directive
  • No attempt is made to re-position the current record pointer (CRP) after deleting, re-writing or writing records in the file
  • Each COBOL I/O call is mapped to its nearest corresponding Btrieve run-time system call as follows:
    COBOL I/O Call | Btrieve Run-time System Call
    OPEN | Open
    CLOSE | Close
    WRITE | Insert
    READ | Get
    START | Get
    DELETE | Get/Delete
    REWRITE | Get/Delete
    UNLOCK | Unlock
    ROLLBACK | Abort transaction
    COMMIT | End transaction
Parent topic: Btrieve
Related information
Xfh2btr Call Conversion Module
Calling Xfh2btr
Btrieve Environment Variables
Xfh2btr Configuration File
Xfh2btr Differences
Btrieve Error Messages


Btrieve Error Messages

For a full list of Btrieve error messages, see the online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click Btrieve, errors.)

If an error is returned by the Btrieve Record Manager, the Xfh2btr call conversion module maps the Btrieve error to a COBOL file status code which it returns to your program. Again, these mappings are shown in the online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click Btrieve, status codes.)

Parent topic: Btrieve
Related information
Xfh2btr Call Conversion Module
Calling Xfh2btr
Btrieve Environment Variables
Xfh2btr Configuration File
Xfh2btr Differences
Calling Btrieve in Non-ANSI Mode


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
Btrieve
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 and CBLDC101

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

The compression routine CBLDC101 behaves in exactly the same way as CBLDC001.

The difference between CBLDC001 and CBLDC101 is that CBLDC101 can handle strings of up to 256 kilobytes (KB) in length, whereas CBLDC001 can only handle strings of up to 65535 bytes.

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 and CBLDC103

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 CBLDC103 routine behaves in the same way as routine CBLDC003.

The difference between CBLDC003 and CBLDC103 is that CBLDC103 can handle strings of up to 256 kilobytes (KB) in length, whereas CBLDC003 can only handle strings of up to 65535 bytes.

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 for routines CBLDC001 and CBLDC003 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.

and for routines CBLDC101 and CBLDC103 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 256 megabytes.
input_buffer_size | A four-byte (int in C, PIC XXXX 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 four-byte (int in C, PIC XXXX 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
  • Trace Player
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
Btrieve
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
  • Replay a sequence of file handling operations, using Trace Player
Parent topic: Tracing File Operations
Related information
Configuring Tracing and Logging
Dynamic Tracing
Trace Player


Configuring Tracing and Logging

You use the File Handler configuration parameters TRACE, TRACEFILEEXTEND, TRACEFILENAME, LOG, and LOGFILENAME to control tracing and logging activities:

  • Set TRACE=ON to turn tracing on
  • Set TRACEFILEEXTEND=ON to indicate that you want trace information to be written to the end of the current trace file, if the trace file already exists
  • Set TRACEFILENAME=filename if you want the trace file to have a name other than the default, which is xfhtrace.xfh
  • Set LOG=ON to indicate that you want any unusual file-related situations, such as corrupted files, or automatic file recovery, to be recorded in a log file for later examination
  • Set LOGFILENAME=filename if you want the log file to have a name other than the default, which is xfhlog

You can set TRACE and LOG either globally or for individual files, but you can only set TRACEFILEEXTEND, TRACEFILENAME, and LOGFILENAME globally.

Here is an example configuration file:

Windows:
[XFH-DEFAULT]
TRACE=OFF
TRACEFILENAME=c:\trace\mftracefile.xfh
TRACEFILEEXTEND=ON
LOG=ON
LOGFILENAME=mflogfile.log

[datafile1.dat]
TRACE=ON

[datafile2.dat]
LOG=OFF
UNIX:
[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
Trace Player


Dynamic Tracing

You can turn tracing on and off from within a COBOL program either by setting the appropriate flags in the FCD or by using library routines. You might want to do this to focus on file handling problems in a subset of an application's operations. When you set FCD flags you do it for a particular file. When you use the library routines, the trace settings affect all the file operations executed by the program from that point on.

When you do dynamic tracing, you use two flags together. This is because file operations such as READs and WRITEs can be traced only if the OPEN operation was traced. If you execute a program with tracing turned off, open a file, then switch dynamic tracing on, the tracing mechanism won't be able to trace any subsequent operations. The best way to proceed is to switch dynamic tracing on for OPENs and CLOSEs at the beginning of the program, then switch tracing for all operations on and off as required. However, the tracing of OPEN and CLOSE operations on its own can also be useful.

  • Using the FCD to Control Tracing
  • Using Library Routines to Control Tracing
Parent topic: Tracing File Operations
Related information
Introduction
Configuring Tracing and Logging
Trace Player


Using the FCD to Control Tracing

To use the FCD flags you must have access to the FCD; see the topic Accessing the FCD in the section File Handler and Sort APIs.

File tracing is controlled by two flag bit settings within the FCD:

  • Bit 1 of fcd-flags-1 controls whether all file operations are traced.
  • Bit 3 of fcd-fs-flags controls whether OPEN and CLOSE operations only are traced.

Change these bit settings as required to control tracing for individual files.

Parent topic: Dynamic Tracing
Related 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


Trace Player

You can use the Trace Player to read and optionally replay the tracing information created when you have file operation tracing configured on. Tracing information is stored for one or more processes, with each process identified as a separate session. An operation trace consists of the I/O number (a number starting from 1 giving the position of the operation in the sequence of operations), the session ID, the opcode, file status resulting from the call and the name of the file. Additional information can optionally be displayed.

There are various ways to use the Trace Player:

  • View all the operations that were traced.
  • Replay all the operations across all sessions in I/O number order. All the files must be available in their original states.
  • Replay all the operations in one session in I/O number order.
  • Run a script to replay each session in session order. All the files must be available in their original states. The absolute order of operations across sessions might not be the same as when they were originally recorded.
  • Run the Trace Player from the Command Line
  • Examples
Parent topic: Tracing File Operations
Related information
Introduction
Configuring Tracing and Logging
Dynamic Tracing


Run the Trace Player from the Command Line

The format of the command line is:

cobfhrepro2/cobfhrepro3 [options]

Use cobfhrepro2 when you are using the FCD2 data structure and cobfhrepro3 when you are using FCD3.

The options specified on the command line define the operation to be carried out by the Trace Player. The following options are available:

num
Replays all the operations in one session, where num is the session ID. If num = 0, all the operations in all the sessions are replayed.
/a
Displays arguments; use in conjunction with /d
/d
Displays the trace information for each operation in I/O number order
/eop-num
Ends the replay at the I/O number op-num
/f
Displays the files needed for a replay
/nfilename
Trace a specific file
/pop-num
Pauses the replay at the I/O number op-num; press Enter to continue
/t
Displays only operations that fail and final status

If you run the Trace Player with no options, it creates the script that plays back each session in session order and informs you of the script's name. You must do this before every invocation of the script.

Parent topic: Trace Player
Related information
Examples


Examples

Here are some examples of typical output.

Example /d output

 I/O     Sess  Op  Opcode   Act   Exp   Filename                       O
Number    Id  Code Desc     Stat  Stat                                 K
-------- ---- ---- -------- ----- ----- ------------------------------ -
00000001 0001 FA02 Open      \    0\0   .\CATALOG.DAT
00000002 0001 FAF6 Read Ran  \    0\0   .\CATALOG.DAT
00000003 0001 FA02 Open      \    0\0   .\CATALOG.DAT

Example /d /a output

 I/O     Sess  Op  Opcode   Act   Exp   Filename                       O
Number    Id  Code Desc     Stat  Stat                                 K
-------- ---- ---- -------- ----- ----- ------------------------------ -
00000001 0001 FA02 Open      \    0\0   .\CATALOG.DAT
  fcd-version. 00   organisation 02   access-mode. 88   open.mode... 80
  opt2........ 20   shr2........ 08   shr......... 84   opt......... 20
  osp......... 80   file-format. 08   flags1...... 03   misc........ 10

RBA =000000000000  Rec Len = 010476
Session-id = 000000000000  FS-file-id =  000000000000

00000002 0001 FAF6 Read Ran  \    0\0   .\CATALOG.DAT
  fcd-version. 00   organisation 02   access-mode. 88   open.mode... 02
  opt2........ 20   shr2........ 08   shr......... 84   opt......... 20
  osp......... 80   file-format. 08   flags1...... 03   misc........ 10

RBA =000000000000  Rec Len = 010476
Session-id = 000000000000  FS-file-id =  000000000000

00000003 0001 FA02 Open      \    0\0   D:\Catalogs\TempOLFiles\Catalo
  fcd-version. 00   organisation 02   access-mode. 88   open.mode... 80
  opt2........ 20   shr2........ 08   shr......... 84   opt......... 20
  osp......... 80   file-format. 08   flags1...... 03   misc........ 10

RBA =000000000000  Rec Len = 010476
Session-id = 000000000000  FS-file-id =  000000000000

Example replay output

 I/O     Sess  Op  Opcode   Act   Exp   Filename                       O
Number    Id  Code Desc     Stat  Stat                                 K
-------- ---- ---- -------- ----- ----- ------------------------------ -
00000001 0001 FA02 Open     0\0   0\0   .\CATALOG.DAT -
00000002 0001 FAF6 Read Ran 0\0   0\0   .\CATALOG.DAT -
00000003 0001 FA02 Open     0\0   0\0   .\CATALOG.DAT -

Act Stat is the actual status returned when the Trace Player is run. Exp Stat is the status returned when the trace was recorded. In theory these two should be the same but in practice, they can be different. Act Stat is blank when you do a display because there is no actual status.

Parent topic: Trace Player
Related information
Run the Trace Player from the Command Line


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 Millennium
  • Windows 2000 (FAT)
  • Windows XP (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 NT (NTFS)
  • Windows 2000 (NTFS)
  • Windows XP (NTFS)
  • UNIX large file system
  • Linux
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. For Fileshare clients and servers on Windows platforms, you can also use the Named Shared Memory protocol (CCISM). Use the CCI.INI configuration file on the Fileshare client to specify which protocol to use for which Fileshare server.

  • To specify the Named Shared Memory protocol (CCISM) as the default protocol:
    /cm ccism
  • To specify that the Named Shared Memory protocol is used when communicating with a specific Fileshare Server, use the /cm and /s options together:
    /cm ccism /s server1
    The Fileshare Client uses CCISM for communicating with the Fileshare Server named server1, whilst using the default protocol (CCITCP) for other servers.

If you are using the TCP/IP protocol, you do not need to specify it in a CCI.INI configuration file.

Note: The CCI.INI file that ships with Enterprise Server contains detailed comments that explain the various CCI.INI options that you can use to alter the basic configuration. Most of these are rarely required.
Parent topic: Fileshare Client
Parent topic: Configuring CCI Communications for Fileshare
Related concepts
Fileshare Client Configuration Options
About CCISMEM
Configuring Your Fileshare Client
Related information
Specifying the Fileshare Server
Configuring Your Fileshare Client
Using the File Handling Redirector Module
FHREDIR Return Codes
About Fileshare Communications
Using CCITCP
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Configuring Your Fileshare Client

The Fileshare Client configuration file is an ordinary text file that you can create using any text editor. By default, it is called fhredir.cfg. The Fileshare Client searches for this file in the current working directory of your application and then along the path specified by the COBDIR environment variable, if one has been set up. Alternatively, you can specify the location of the Fileshare Client configuration file using the FHREDIR environment variable, for example:

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
Using CCISMEM
Specifying the Communications Protocol
About CCISMEM
Related information
Specifying the Fileshare Server
Specifying the Communications Protocol
Using the File Handling Redirector Module
FHREDIR Return Codes
Using CCITCP


Fileshare Client Configuration Options

This section describes the available Fileshare Client configuration options. These options can appear as many times as necessary within a Fileshare Client configuration file, and in any order, but only one option can be specified per line.

Note:
  • The Fileshare Client configuration file can contain a maximum of 16 unique Fileshare Server names
  • Filenames appearing in the configuration file are case-sensitive unless defined by the /r option (DYNCONFIG), in which case they are not case sensitive when run in Windows
  • The filename in the configuration file must appear exactly as it will appear to FHRedir on the first OPEN request passed by your program
  • The Fileshare Server name is folded to uppercase. Note that it may be necessary to use the name in uppercase in some configuration files to ensure name matching works as expected.
  • 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
Using CCISMEM
Specifying the Communications Protocol
About CCISMEM
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, 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
  • About CCISMEM
  • Using CCISMEM
  • Logging Fileshare Messages: CCI Trace
  • Using Multiple Protocols with Test Programs
  • Configuring the CCI Timeout
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Database Integrity
Security
Advanced Operation
Error Handling
Fileshare Server Messages


About Fileshare Communications

A Fileshare Server communicates with a Fileshare Client using the Common Communications Interface (CCI). A Windows Fileshare Server can use several communication protocols concurrently, enabling it to communicate with a number of Fileshare Clients that do not all use the same protocol.

When you invoke a Fileshare Server, you need to specify the communications protocols it supports, using the /cm option in the Fileshare configuration file. Valid values for /cm are:

Windows platforms:

  • TCP/IP

    Setting: ccitcp

  • CCISMEM

    Setting: ccism

UNIX platforms:

  • TCP/IP

    Setting: ccitcp

Parent topic: Configuring CCI Communications for Fileshare
Related information
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using CCITCP

Fileshare defaults to the TCP/IP (CCITCP) protocol. When using CCITCP, you can use either CCITCP Direct or the following process:

  • Both the Fileshare Client and the Fileshare Server must have access to a registration process. Depending upon the product that has been installed there are two versions of the registration server called ccitcp2 or mfds the Micro Focus Directory Server.
  • The registration process helps the Fileshare Client to locate the Fileshare Server.
  • The registration process can be running on any machine that the Fileshare Client and Fileshare Server can contact. It does not have to be running on the same machine as either Fileshare Server or Fileshare Client.
  • You must set the environment variable CCITCP2 to the host name of the machine where the ccitcp2 process is running.

    If you do not set the environment variable, CCITCP assumes that ccitcp2 is running on the local machine. The Fileshare Client and the Fileshare Server must register with the same ccitcp2 process in order to communicate with each other.

    For example, consider the situation where the Fileshare Server and the Fileshare Client are running on different machines and the ccitcp2 process is running on the same machine as the Fileshare Server. The environment variable CCITCP2 does not have to be set on the machine running the Fileshare Server. However, it must be set (on the machine running the Fileshare Client) to the TCP/IP host name of the machine where the Fileshare Server (and the ccitcp2 process) is running.

  • By default both ccitcp2 and mfds will start on TCP (mfds only) and UDP port 86. Both registration processes may be started on different ports. If this has been done then you must set the environment variable CCITCP2_PORT to the decimal number of the port that is being used for the registration process.

    For example, consider the situation where mfds has been started with CCITCP2_PORT set to 2023, or using the -p 2023 option. You must set CCITCP2_PORT to 2023 on both the Fileshare Client and the Fileshare Server.

Many configuration options exist for CCITCP, details of these can be found in the comments within the CCI.INI configuration file.

Parent topic: Configuring CCI Communications for Fileshare
Related concepts
Fileshare Client Configuration Options
Configuring Your Fileshare Client
Related information
About Fileshare Communications
Specifying the Communications Protocol
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout
Configuring CCI


About CCISMEM

CCISMEM (ccism) uses a Named Shared Memory communications method to transfer date between two processes on the same Windows system. Both the client and the server application must reside on the same Windows system.

These shared memory transfers are typically about as fast as its possible to transfer data buffers between processes. Individual data transfers that fit within the shared memory segment are typically several context switches faster than using TCP/IP in loopback mode to move the same data. As buffer sizes grow the difference becomes less noticeable, but is still present. By default, shared memory segments are 8K in size, but this is easily configurable using the cci.ini configuration file options.

When using Fileshare with the CCISM protocol, ensure the server is started using the /sc switch. This switch starts Fileshare in synchronous communications mode, which gives the best performance.

To also use clients located on other systems, you must configure Fileshare Server to use CCITCP as well as CCISM. To do this, in cci.ini, set the following configuration options:

-cm ccitcp -cm ccism

Using two protocols within a single Fileshare Server prevents Fileshare Server being used in synchronous mode; this is the only functionality that is lost with this type of configuration.

From a client perspective, the default CCITCP functionality doesn't require much FHREDIR.CFG configuration. When using CCISMEM you will need to use the following client options:

/cm ccism
Note: When using CCISMEM, the /MA parameter should not normally be used as it has a different meaning in the context of Named Shared Memory. The /MA option is equivalent to using the mem_files_location option in the cci.ini configuration file.
Parent topic: Configuring CCI Communications for Fileshare
Related concepts
Specifying the Communications Protocol
Fileshare Client Configuration Options
Configuring Your Fileshare Client
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using CCISMEM

Fileshare defaults to using the TCP/IP (CCITCP) protocol. If you are running both the Fileshare server and the Fileshare client on the same Windows system you can use an alternative connection protocol that utilises shared memory: CCISM.

Shared Memory transfers are usually faster than using TCP/IP between two processes.

To configure a Fileshare server to use the CCISM protocol, use the following option:

fs -cm ccism

To give the best performance, we also recommend that you start the Fileshare server with the /sc option (synchronous communications mode).

You can combined multiple communications methods for the Fileshare server, as follows:

fs -cm ccism –cm ccitcp

Unfortunately, you cannot run multiple protocols on a Fileshare server that is running in synchronous mode.

To configure a Fileshare client to use CCISMEM, you must use the following line in your FHREDIR.CFG configuration file:

/CM ccism
Note: When using CCISMEM, the /MA parameter in FHREDIR.CFG has no effect.

Many configuration options exist for CCISMEM, details of these can be found in the comments within the CCI.INI configuration file.

Parent topic: Configuring CCI Communications for Fileshare
Related concepts
Fileshare Client Configuration Options
Configuring Your Fileshare Client
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Logging Fileshare Messages: CCI Trace

CCI Trace enables all the messages sent by CCI to be logged to a file. This can help in tracking down and debugging problems related to communications.

CCI Trace is enabled through the Consolidated Tracing Facility (CTF); additionally, to trace CCI activity through the Fileshare Server, add the following to the Fileshare Server configuration file:

/tr cci

To prevent unauthorized access to the CCI Trace information, you are prompted for the supervisor password when you invoke a Fileshare Server with CCI Trace enabled. If the password is accepted, CCI Trace is enabled and a second prompt asks if CCI Trace should be activated immediately or not.

Note:
  • The supervisor password is that specified for the user-ID FSVIEW in the password file, so you must specify the appropriate password file when you start the Fileshare Server.
  • CCI Trace can be toggled on and off using the F3 key.
  • The CCI trace options are specified via the CCITRACE environment variable.
Parent topic: Configuring CCI Communications for Fileshare
Related reference
To Enable CTF Tracing
Enabling CCI Tracing
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Using Multiple Protocols with Test Programs
Configuring the CCI Timeout


Using Multiple Protocols with Test Programs

Switching between CCITCP protocol and CCISMEM protocol can affect test program timings.

Access to the driver levels usually results in the context switching out of the sending process quite soon after the send attempt has begun. Typically the peer process uses the CPU before the context switches back to the original process.

As a result, with CCITCP, more processing time is required at the driver level than with CCISMEM which has no driver application to call. When CCITCP moves to the drivers to execute the extra data moves, the context is switched out the parent process. On the other hand, using CCISMEM with the same send operation, no context switch occurs. The CCI caller manages when to switch to its peers.

When the configuration is set to async mode (the default) File Share polls CCI to determine if data is present to read. As a result, much more time in CPU processing is spent at the user level, waiting for the next buffer to process. The application and File Share do not context switch to the conversation peer until the end of a full time-slice. That is, the CPU cannot process the next chunk of data and to respond to the original sender until the end of a full time-slice.

This can often cause quite dramatic effects on heavily loaded single CPU systems, or dual/quad core systems, when using test application created with polling loops that have scrolling screen displays.

Highlighting windows and de-selecting them alters the time spent in clients and servers because it changes their system priorities and hence the amount of time that is spent polling around not yielding to let partner processes do their work.

In these cases the fastest route is always to not high-light either client or server, then they both get the same amount of CPU with the smallest time slice. Its a case of the processes running with too much CPU not too little.

The fastest design is of course to not loop at all, then you'll be in the right place to receive the in-bound data when it arrives, and to respond quickly without wasting any CPU cycles in redundant polling.

File share can be configured to avoid the polling loop.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Configuring the CCI Timeout


Configuring the CCI Timeout

By default, CCI waits 120 seconds for a network request to complete before it times it out and returns an error. If a network request has not completed in a period much shorter than this, it can usually be assumed that it is unnecessary to wait any longer. For example, if a Fileshare Server with the correct server-name is not active when a Fileshare Client attempts its first open, the application appears to hang for 120 seconds before a 9/124 status is returned because the server cannot be contacted. See the section Communications Errors in the chapter Error Handling for more details.

You can configure the Fileshare Client to use a shorter timeout period by using the /ct option in the client configuration file, fhredir.cfg. The timeout period is specified in 1/10th seconds.

For example:

/ct 300

This instructs the Fileshare Client to specify that CCI waits for 30 seconds for network requests to complete. After this time it returns a 9/124 status to the application program.

Parent topic: Configuring CCI Communications for Fileshare
Related information
About Fileshare Communications
Specifying the Communications Protocol
Using CCITCP
About CCISMEM
Using CCISMEM
Logging Fileshare Messages: CCI Trace
Using Multiple Protocols with Test Programs


Database Integrity

This chapter describes all of those Fileshare features which enable you to safeguard the integrity of your database:
  • Transaction Processing
    Transaction processing enables you to group a set of data file updates together into one logical unit of work, known as a transaction.
  • Recovery Logging
    Logging the actions performed within Fileshare helps you to recover data in the event of a system failure.
  • Fileshare Recovery
    The Fileshare Recovery Utility enables you to recover updates to data files after a system failure.
  • Database Sequence Numbering
    Database sequence numbering provides a method of linking groups of data files so that they and their corresponding log file can be kept in step.
  • Database Backup and Recovery
    To alleviate data loss and optimize recovery time, ensure you back up your Fileshare database regularly.
  • Database Reference File Maintenance
    The database reference file contains references to data files and the actions that Fileshare Server performs on them.
  • Best Practices for Backup and Recovery
    Use these best practices to optimize the backup and recovery processes within Fileshare.
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Security
Advanced Operation
Error Handling
Fileshare Server Messages


Transaction Processing

Transaction processing enables you to group a set of data file updates together into one logical unit of work, known as a transaction.

The changes you make as part of a transaction can be:

  • Permanently reflected in the data files by committing the work
  • Removed from the data files by rolling back the work. When a transaction is rolled back, the Fileshare Server returns the data files to the state they were in before the transaction started.

A transaction can include multiple updates to multiple data files on multiple Fileshare Servers.

A transaction starts when your program performs the first update operation (WRITE, REWRITE or DELETE) on a file which has the WITH ROLLBACK clause defined in its SELECT statement after:

  • The file is opened
  • A COMMIT or ROLLBACK statement is executed

A transaction terminates when:

  • A COMMIT verb is executed
  • A ROLLBACK verb is executed
  • The transaction is timed out. See the section Automatic Record Lock Timeout for further information.
Notes:

  • The COMMIT and ROLLBACK verbs release all the record locks held by a program on every data file. This does not depend on whether or not you specified the WITH ROLLBACK clause for a particular file.
  • The time taken to process a COMMIT or ROLLBACK operation is directly proportional to the number of updates performed in that transaction.
  • If you try to CLOSE a file that is participating in an active transaction, a 9/100 error status is returned and the file remains open. A COMMIT or ROLLBACK needs to be issued before the CLOSE can be executed.
  • When you use the WITH ROLLBACK clause, multiple record locking is implicitly defined on the file.

Before using transaction processing you are strongly advised to do the following to ensure the highest level of integrity for your data:

  • Include any file on which transaction processing is to be performed in the database reference file of the Fileshare Server that services the I/O requests for that file. See the section Database Reference File Maintenance for further information.
  • Specify a rollforward recovery log file in the database reference file. See the section Rollforward Recovery Logging for further information.

Record locks are implicitly obtained on every record that is updated in a transaction. If a transaction is temporarily suspended, for example, if your program requests input and the user is not responding, record locks can remain in the file for a considerable length of time. If another Fileshare Client tries to access the locked records, and a specified length of time has passed, the Fileshare Server aborts (rolls back) the transaction. When this happens, the transaction is said to be timed out by the Fileshare Server. See the section Automatic Record Lock Timeout for further information.

Note:

By keeping the number of updates performed in a transaction to a minimum, the number of record locks obtained is also kept to a minimum. This reduces the number of record locking conflicts between Fileshare Clients sharing the data, and increases the speed of any subsequent COMMIT or ROLLBACK operations.

  • Automatic Record Lock Timeout
  • Transaction Processing - Fileshare Client
  • Transaction Processing - Fileshare Server
Parent topic: Database Integrity
Related information
Recovery Logging
Fileshare Recovery
Database Sequence Numbering
Database Backup and Recovery
Database Reference File Maintenance
Best Practices for Backup and Recovery
Automatic Record Lock Timeout
Database Reference File Maintenance
Rollforward Recovery Logging


Automatic Record Lock Timeout

In a multi-user environment where files are being shared, programs use record locks to control concurrent access to individual records. In addition, Fileshare automatically obtains a record lock on any record that it updates within a transaction. The larger the number of record locks being held, however, the less concurrent access to data is possible. It is beneficial, therefore, for any one program to keep the number of record locks that it holds at any one time to a minimum.

If a Fileshare Client obtains a lock on a record (either explicitly or because it updated the record within a transaction) and a second Fileshare Client tries to read the locked record, the Fileshare Server checks to see how long it is since the Fileshare Client holding the record lock last contacted the Fileshare Server. If this period is:

  • Greater than the timeout period, the Fileshare Server:
    • Automatically rolls back any pending transaction being carried out by the first Fileshare Client
    • Releases all the record locks held by the first Fileshare Client
    • Returns error 9/068 "record locked" to the Client trying to read the record. Retrying the operation succeeds in gaining access to the record because the lock has now been released.
  • Less than the timeout period, the Fileshare Server returns error 9/068 "record locked" to the Fileshare Client trying to read the record

The default timeout period is 60 seconds. You can change this value using the /t option in the Fileshare Server configuration file. Specifying a value of zero disables the automatic record lock timeout such that record locks are only released under application program control.

A program that is timed out receives error 9/125 on its next I/O operation. You should treat this as a warning message and repeat the operation on which the error was returned. The Fileshare Server rolls back any active transaction and releases all the record locks held by the program that timed out.

Parent topic: Transaction Processing
Related information
Transaction Processing - Fileshare Client
Transaction Processing - Fileshare Server


Transaction Processing - Fileshare Client

For each data file on which you want transaction processing active, use the WITH ROLLBACK clause when you define the data file using the SELECT statement in your COBOL program.

For example:

select test-file assign to "test.dat"
   organization indexed
   record key prime-key
   lock mode manual with rollback
   ...

This sample code specifies that transaction processing is active on the file test.dat.

In your program, use the COMMIT verb to make the updates in a transaction permanent. Use the ROLLBACK verb to remove the updates in a transaction from the data files.

The COMMIT and ROLLBACK verbs work on all data files involved in a transaction. This means that you cannot check the status of the COMMIT or ROLLBACK operation using the file status of any one data file. Instead, you must call the File Handling Redirector module to check the status of the COMMIT or ROLLBACK. The entry point to call in the the File Handling Redirector module module is fs_status. The format of the call is:

call "fs_status" returning t-status
end-call

where t-status is defined as:

01 t-status  pic x(2) comp-x.

A non-zero value returned in t-status indicates that the COMMIT or ROLLBACK operation failed.

For example:

1   SELECT test-file ASSIGN TO "test.dat"
2      LOCK MODE MANUAL WITH ROLLBACK
3   ...
4   OPEN I-O test-file
5   ...
6   move 1 to prime-key
7   WRITE test-file-record
8   ...
9   COMMIT
10   call "fs_status"
11      returning t-status
12   end-call
13   if t-status < > 0
14      display "Warning - Commit operation failed"
15   end-if
16   move 2 to prime-key
17   WRITE test-file-record
18   ...
19   ROLLBACK
20   call "fs_status"
21      returning t-status
22   end-call
23   if t-status < > 0
24      display "Warning - Rollback operation failed"
25   end-if
26   WRITE test-file-record
27   ...

where:

Lines 1 - 2:
SELECT test-file ASSIGN TO "test.dat"
   LOCK MODE MANUAL WITH ROLLBACK

Specifies transaction processing for this data file.

Line 7:
WRITE test-file-record

Starts a new transaction.

Line 9:
COMMIT

Makes the updates to test-file permanent and terminates the transaction.

Lines 10 - 15:
call "fs_status"
   returning t-status
end-call
if t-status < > 0
   display "Warning - Commit operation failed"
end-if

Checks the status of the COMMIT operation.

Line 17:
WRITE test-file-record

Starts a new transaction.

Line 19:
ROLLBACK

Removes the updates made to test-file and terminates the transaction.

Lines 20 - 25:
call "fs_status"
   returning t-status
end-call
if t-status < > 0
   display "Warning - Rollback operation failed"
end-if

Checks the status of the ROLLBACK operation.

Line 26:
WRITE test-file-record

Starts a new transaction.

You do not need to change the configuration of the Fileshare Client to enable transaction processing.

Parent topic: Transaction Processing
Related information
Automatic Record Lock Timeout
Transaction Processing - Fileshare Server


Transaction Processing - Fileshare Server

Normally, you do not need to change the configuration of the Fileshare Server to enable transaction processing. However, if you are using IDXFORMAT 17 and 21 files, transaction processing is not supported by default; you must configure it on a file-by-file basis using the Virtual File Handler option (/ap) when specifying the file in your database reference file. For example, when you access the following file through Fileshare, it is additionally re-directed to the ACUFH file handler, where transactional support can be provided:
Fs /d dbase.ref /f acufile1.dat /ap ACUFH

If you recover a data file using the Rollforward Recovery Utility, any outstanding transactions at the end of the recovery process are implicitly rolled back. See the section Rollforward Recovery Utility for further information.

Parent topic: Transaction Processing
Related information
Automatic Record Lock Timeout
Transaction Processing - Fileshare Client
Rollforward Recovery Utility


Recovery Logging

Logging the actions performed within Fileshare helps you to recover data in the event of a system failure.

A system failure can result in loss of data in either of the following circumstances:

  • The Fileshare Server's cache or operating system's cache is not written to disk
  • The system failed while updating a file. In this case, the integrity of the files cannot be guaranteed

Recovery logging is the method used by Fileshare to store all the updates made to your data files in one or more log files. If your system fails, resulting in loss of data, the log file(s) are used by a recovery utility to re-apply the updates to the data files. When the recovery is complete, the files contain the data they contained at the time of the system failure (with any outstanding transactions rolled back).

There are two versions of recover logging that you can use. A basic version of logging, which is enabled as default, provides a Rollforward Recovery Utility. An advanced version of logging, which you must enable, provides Rollforward and Rollback Recovery. The advanced logging version also has other benefits that the basic version does not, such as compatibility with a user exit procedure and with hot backups.

You can only use one version of logging at any one time.

You do not need to make any changes to the Fileshare Client in order to use recovery logging.

  • Basic Recovery Logging
  • Advanced Recovery Logging
Parent topic: Database Integrity
Related information
Transaction Processing
Fileshare Recovery
Database Sequence Numbering
Database Backup and Recovery
Database Reference File Maintenance
Best Practices for Backup and Recovery
Fileshare Recovery


Basic Recovery Logging

To log updates to one or more files you need to create a database reference file containing the name of the file(s) for which updates are to be logged, and the name of the log file. See Database Reference File Maintenance for details on creating database reference files.

You do not need to include an extension when you specify the log file name as this is generated automatically by the Fileshare Server. If you do specify an extension, the following message is displayed:

FS180-W The log filename specified has an extension. The name of the
log file has been changed to "filename".

During the logging process the Fileshare Server creates one or more recovery log files. The first recovery log file is called a starter log file, and subsequent log files are called continuation log files. The Fileshare Server creates a continuation log file whenever the current log file is backed up.

The current recovery log file always has an extension beginning with the character "L". A recovery log file that has been backed up has an extension beginning with the character "B". Following either of these letters is a two digit number indicating the recovery log file number, starting at 01. These automatically generated extensions indicate the order in which the log files were written, and hence the order in which they should be applied if a rollforward recovery is performed. For example, suppose you specify a log file called recover. When the Fileshare Server starts up it creates a log file called recover.L01 and logs updates in this file. If the recovery log file is backed up, the Fileshare Server renames the current log file recover.B01 and creates a new one called recover.L02. If the Fileshare Server is shut down, there would be two recovery log files: recover.B01 is called the starter log file and recover.L02 is a continuation log file. There is only ever one starter log file, but there can be any number of continuation log files.

When performing a recovery operation, the Basic Rollforward Recovery Utility processes the starter log file first and then the continuation log files in the order in which they were created.

Updates to data files that are referenced in the database reference file are logged unless you explicitly turn logging off:

  • To add a data file entry to the database reference file, use the /f option of the Database Reference File Maintenance Utility
  • To turn logging off for a particular data file, use the /o l (omit logging) option when you add the filename entry to the database reference file

Because of the caching used by some operating systems, not all of the information written to the log file is physically written to disk. The Fileshare Server periodically calls the operating system to force the log file updates to be written. By default, the log file is flushed after every 100 records are written to it. You can configure this interval using the /lc (log count) option when you add the log file name to the database reference file. If you specify a log count of zero, the Fileshare Server does not make any calls to the operating system to flush the updates to disk. Instead, the operating system controls the flushing of the log file to disk.

The log file updates are also flushed to disk after every COMMIT operation.

If a transaction was pending at the time of a system failure, the Basic Rollforward Recovery Utility implicitly rolls back the transaction when the files are recovered.

Parent topic: Recovery Logging
Related concepts
Advanced Recovery Logging
Related information
Automatic Database Backup and Rollforward Recovery
Database Reference File Maintenance
Database Sequence Numbering


Advanced Recovery Logging

When advanced recovery logging is enabled, you have more control over how you back up and recover your data files.

There are two types of recovery available when you have enabled advanced recovery logging:

Rollback recovery
A fast recovery method suited to application failures. In the event of system failures, you can only use this if you have enabled additional logging features, which do have an effect on day-to-day Fileshare performance.
Rollforward recovery
A recovery method suitable for all types of failure, and does not require the additional flushing features.

Advanced recovery logging can be configured to use only the rollback method, or to use both methods.

With advanced recovery logging enabled, you can have more control over recovery by using a user exit procedure (fsexitproc.cbl), and you are able to view the log file in a user-readable format.

Advanced logging also enables you to take more regular backups, using the hot backups option, which doesn't require you to shut down Fileshare.

The Database sequence numbering, and automatic backup and recovery options are not available when advanced logging is enabled.

  • Enabling Advanced Recovery Logging
  • Fileshare Exit Procedure - fsexitproc.cbl
  • Viewing the Log Files
Parent topic: Recovery Logging
Related information
Basic Recovery Logging


Enabling Advanced Recovery Logging

Advanced recovery logging can be enabled either for rollback recovery only, or for rollback and rollforward recovery, by entering one of the following commands on the Fileshare server:

To enable logging for rollback recovery only:

FS /d dbase.ref /ltf logtrans.dat

To enable logging for both types of recovery:

FS /d dbase.ref /ltf logtrans.dat /ltt f
where:
Syntax | Explanation
/d dbase.ref | Specifies the database reference file
/ltf logtrans.dat | Specifies the log file for advanced logging
/ltt f | Specifies logging compatible with rollforward recovery, as well as rollback recovery

If you want to use rollback recovery for system failures, you need to enable extra logging, which has an impact on performance. You must have enabled the write through (/lw) and flush on commit (/fc) options when Fileshare was started, either on the command line, or by setting them in the fs.cfg file. You do not need to enable these settings if you plan to use only rollforward recovery.

Parent topic: Advanced Recovery Logging
Related information
Advanced Rollback Recovery
Advanced Rollforward Recovery


Fileshare Exit Procedure - fsexitproc.cbl

When you have advanced recovery logging enabled, you can use the exit procedure fsexitproc.cbl to programmatically control logging, recovery and backup behavior.

The exit procedure is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or /opt/microfocus/EnterpriseDeveloper/cpylib (UNIX).

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:

Windows:

fs /d dbase.ref /backup	c:\backdir

UNIX:

fs /d dbase.ref /backup	/backdir

adds an entry to the database reference file called dbase.ref which specifies the backup directory as c:\backdir on Windows or /backdiron UNIX. A full path can be specified for the backup directory, otherwise paths which are not fully qualified are taken to be relative to the current directory of the Fileshare Server.

Setting a backup directory in this way causes the Fileshare Server to copy all the data files specified in the database reference file to the directory c:\backdir on Windows or /backdiron UNIX, 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

Windows:

fs /d dbase.ref /l logfile
fs /d dbase.ref /backup c:\backdir
fs /d dbase.ref /f c:\accounts\customer.dat
fs /d dbase.ref /f c:\finance\history.dat

UNIX:

fs /d dbase.ref /l logfile
fs /d dbase.ref /backup /backdir
fs /d dbase.ref /f /accounts/customer.txt
fs /d dbase.ref /f /finance/history.txt

These commands perform the following:

  • Create a database reference file called dbase.ref
  • Specify the recovery log file as logfile so that the first log file that the Fileshare Server creates is called logfile.L01
  • Specify that any updates to the files c:\accounts\customer.dat and c:\finance\history.dat on Windows or /accounts/customer.txt and /finance/history.txt on UNIX, are logged
  • Specify c:\backdir on Windows or /backdiron UNIX, as the backup directory

On startup, the Fileshare Server automatically backs up these data files in the directory c:\backdir on Windows or /backdiron UNIX. If the log file is backed-up while the Fileshare Server is active, backup files are also placed in this directory. If the Rollforward Recovery Utility is invoked, the backup files in c:\backdir on Windows or /backdiron UNIX are restored to their original directories and any updates recorded in the log file(s) are re-applied.

Parent topic: Database Backup and Recovery
Related information
Basic Recovery Logging
Fileshare Manager
Best Practices Basic Logging


Hot Backups

Hot backups enable you to take a backup of your database files and start a new log file without the need to shutdown and restart the Fileshare Server.
Note: Hot backups are only available if you have advanced logging enabled.

You can run a hot backup if the Fileshare server resides on an operating system that supports a snapshot process; for example, DiskShadow, which is shipped with modern Windows platforms.

To run a hot backup, you need to:
  • Enable advanced logging for rollforward recovery
  • Be able to run commands in supervisor mode in FSVIEW.
  • Configure the exit procedure (fsexitproc.cbl) to call the snapshot utility

When a hot backup is initiated, Fileshare suspends the start of new transactions, putting these into a hold state until all outstanding requests are processed. When they are complete, control is handed to fsexitproc.cbl, where you can code a command line invocation to your snapshot utility, to back up your data files.

When the snapshot is complete, normal transaction processing resumes.

Note: During the period where the outstanding transactions have been finalized and new transactions are resumed, the server does not communicate with its clients. If this duration is longer than a client CCI-Timeout setting, the client will disconnect from the server; therefore, you may need to increase the setting in a Fileshare Client configuration file to ensure that it does not disconnect while the hot backup is running.

  • Running a Hot Backup
Parent topic: Database Backup and Recovery
Related information
Fileshare Exit Procedure - fsexitproc.cbl
Best Practices for Backup and Recovery
Fileshare Client Configuration Options
Configuring the CCI Timeout


Running a Hot Backup

Note: Hot backups are only available if you have advanced logging enabled.
  1. At the command prompt, type FSVIEW.

    The FSVIEW Administration Utility is started.

  2. To log on to supervisor mode, type admin logon <username> <password>, where <username> and <password> are your Fileshare logon credentials.
  3. To log on to the server, type server set <server-name>, where <server-name> is the name of the Fileshare server.
  4. Type backup init.

    Fileshare now only processes file operations for in-flight transactions. While these transactions are being processed, you can enter backup cancel at the FSVIEW prompt to cancel the backup.

  5. When all sessions have been processed, control is passed to the 78-transactions-newlog clause in fsexitproc.cbl.

    when 78-transactions-newlog
    *> Fileshare is ready to create a new log.
     *> used when roll forward logging is enabled.
     *> default it to start new log
     *> set action to determine what occurs..
     *> don't start new log     value h"0000".
     *> start new log           value h"0001".
continue
    At this point, the log file is finalized, the data files are flushed to disk, and if the default action is set, a new log file is created.
    Note: Any new requests are cycled until the backup has completed; ensure Fileshare clients do not time out during this period by setting CCI TIMEOUT to a sufficient period of time; see Best Practices for Advanced Logging for more details.
  6. When the files are ready, control then moves to the 78-transactions-suspended clause in fsexitproc.cbl.
    Note: fsexitproc.cbl contains an example of how the backup can be taken using the Diskshadow utility (see below) and a script file example. Update this clause to run your preferred utility.
    when 78-transactions-suspended
   call "CBL_EXEC_RUN_UNIT"
      using "diskshadow.exe /s script.dsh "
                       by value  52
                       by reference runit-run-id
                       by value     runit-stack-sz
                                    runit-flags
                returning return-code
   continue
    The accompanying script file example
    *> Example script.dsh for use with diskshadow.exe (Windows)
#DiskShadow script file
set context persistent nowriters
set metadata c:\diskshadowdata\example.cab
set verbose on
begin backup
add volume d: alias SystemVolumeShadow

create
unexpose p:
expose %SystemVolumeShadow% p:
end backup
*> #End of script

    When the snapshot has been taken, Fileshare resumes normal transaction processing.

  7. You should now copy the data files from the snapshot to a safe location.
Parent topic: Hot Backups


Database Reference File Maintenance

The database reference file contains references to data files and the actions that Fileshare Server performs on them.

This section explains how to create and update a database reference file in order to make use of the features described earlier in this chapter.

You should only create or change a database reference file using the Database Reference File Maintenance Utility. This is because the file contains information that is stored in a special format.

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:

Windows:

To use your own fsseclog module, create and link it into cobfssecurity.dll and place it on the search path, PATH. Fileshare will notify you that it has loaded the user security modules.

UNIX:

To use your own fsseclog module, create and link it into a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or 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:

Windows:

You can create your own fssecopn module, link it into the cobfssecurity.dll and place it on the search path, PATH. Fileshare will notify you that it has loaded the user security modules.

UNIX:

You can create your own fssecopn module, link it into a cobfssecurity shared object and place it on the search path, LD_LIBRARY_PATH (or 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 Enterprise Developer prior to version 3.0. Upgraded password files can support long usernames and passwords up to 100 characters in length.

    Note: Micro Focus recommend that you take a backup of your password file before you upgrade.

Examples

fs /pf pass.dat /u pkel /pw fishwife

This example invokes password file maintenance, creates or updates a password file called pass.dat and adds a user-ID of pkel and password of fishwife.

fs /pf pass.dat /clp

This example upgrades a password file that was created using Enterprise Developer prior to version 3.0. The upgraded password file now supports long usernames and passwords.

Parent topic: Security
Related 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
  • Running Fileshare as a Windows Service
  • Performance Considerations
  • Large File Support with Fileshare
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Error Handling
Fileshare Server Messages


Running Fileshare as a Background Process

Note: This process is applicable to Fileshare Servers on UNIX only.

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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare
Password File Maintenance


The NFILES Setting

Note: This setting is applicable to Fileshare Servers on UNIX only.

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
Running Fileshare as a Windows Service
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare


Filename Mapping

Filename mapping enables I/O requests made against one data file to be mapped to a different data file when your program is executed. For example, you can use filename mapping to enable applications that use DOS file naming conventions to access data files under the control of a Fileshare Server running on an operating system that uses different file naming conventions, such as UNIX or NetWare.

You do not need to change the configuration of the Fileshare Client to use filename mapping.

  • Fileshare Server
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare


Fileshare Server

To enable filename mapping, use the /af (alternate filename) option with the /f option in the database reference file.

The /fs (filename string) option used in conjunction with the /af option enables you to substitute characters at the start of a filename. This is particularly useful for mapping pathnames.

For example:

fs /d dbase.ref /f old.dat /af new.dat
fs /d dbase.ref /fs c: /af e:

adds entries to the database reference file dbase.ref which specify that:

  • All requests to the data file old.dat are redirected to the data file new.dat
  • All accesses to data files starting with c: are directed to drive e:

If the Fileshare Server finds an entry specifying an alternate filename, any character string substitution specified by a /fs option is applied to the new filename.

After processing any string substitution specified by an /fs option, the Fileshare Server does not search the database reference file for any matching /f option using the new filename.

Fileshare processes all filenames as relative to the Fileshare Server's current directory if you have not given a fully qualified filename after the /f option or a fully qualified filename is not passed from the Fileshare Client.

All filenames and paths are forced to upper case by Fileshare Servers not running on the UNIX operating system and are expanded to include the full path to ensure matching. Filenames specified with the /af option are not modified.

Example 1:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat

This example adds entries to the database reference file dbase.ref that specify that file accesses to the file file1.dat are mapped to the alternate filename file2.dat.

Example 2:

fs /d dbase.ref /f file1.dat /af c:\data\file2.dat
fs /d dbase.ref /fs c: /af e:

This example adds entries to the database reference file dbase.ref that specify that all requests made to the data file file1.dat are redirected to the alternate filename and, in addition, the alternate filename is changed, using string substitution, to be on drive e:.

Parent topic: Filename Mapping


Data and Key Compression

You can configure the Fileshare Server so that data files are created using data or key compression.

You do not need to change the Fileshare Client configuration in order to use data or key compression on a data file.

  • Data and Key Compression - Fileshare Server
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare


Data and Key Compression - Fileshare Server

To enable data or key compression for a data file, use the /k option in the database reference file. In conjunction with the /k option, use the d option to specify data compression and the i option to specify key compression.

Values that you specify after the d and i options are the same values that you would specify using the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Data and key compression specifications in the database reference file are effective only if the Fileshare Server creates the data files. They do not affect existing data files. For existing files, the data and key compression information is retrieved from the data file header. Any settings in your program or the database reference file are ignored.

Example:

fs /d dbase.ref /f file1.dat /k d001
fs /d dbase.ref /f file2.dat /k d001i7

This example tells the Fileshare Server to create the file file1.dat with data compression and the file file2.dat with both data and key compression.

Parent topic: Data and Key Compression


Virtual File Handler Interface

The Fileshare Server can pass I/O requests to a program specified by you, rather than by the Micro Focus File Handler, as long as the program that you specify conforms to the call interface used by the File Handler.

Note: If you are using Fileshare, IDXFORMATs 17 and 21 do not provide transaction processing capabilities by default. You must configure it on a file-by-file basis using the Virtual File Handler option (/ap) when specifying the file in your database reference file. For example, when you access the following file through Fileshare, it is additionally re-directed to the ACUFH file handler, where transactional support can be provided:
Fs /d dbase.ref /f acufile1.dat /ap ACUFH

You do not need to change the configuration of the Fileshare Client to use the Virtual File Handler Interface.

  • Fileshare Server
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare


Fileshare Server

To specify a virtual file handler, use the /ap (application program) option with the /f option in the database reference file to specify the program to which I/O requests for a particular data file are passed by the Fileshare Server.

Example:

fs /d dbase.ref /f user1.dat /ap myprog

This adds entries to the database reference file, dbase.ref which specify that the Fileshare Server should pass all I/O requests for the data file user1.dat to the program myprog.

Windows:

On Windows, your program should be compiled to intermediate or generated code, or to a dynamic link library, and must be callable from the Fileshare process.

UNIX:

On UNIX, your program should be compiled to intermediate or generated code, or to a callable shared object, and must be callable from the Fileshare process.

You also need to use the fcd3 copybook instead of the standard fcd layout.

Parent topic: Virtual File Handler Interface


Monitoring Fileshare

When the Fileshare Server is active, you can toggle the trace option on and off using the F2 key. If the trace option is on, the Fileshare Server displays the file access requests on the console as they happen. Each line of trace provides:

  • Input:
    • The user-ID assigned, in the order that the Fileshare Clients logged onto the Fileshare Server
    • The operation code, indicating the I/O operation requested (see the online help on the Micro Focus File Handler for further information about operation codes)
    • The name of the file being accessed
  • Output:
    • The status returned to the Fileshare Client, indicating the result of the operation
Note:

The trace option can degrade performance. You should only use it as a diagnostic aid in problem investigation.

You can activate the trace option when the Fileshare Server is started using the "/tr f" option. This causes the trace to be written to the file fsscreen.lst, as well as being displayed on the screen. Note, however, that this severely impacts the Fileshare Server performance if tracing is switched on. If, however, tracing is switched off, only information messages are written to the screen and to the file. This is a useful method of keeping a permanent record of Fileshare messages on disk.

If you are using Fileshare in single user mode (see the section Single User Mode), the trace display, together with all other output normally displayed on the Fileshare Server console screen, is written to the file fsscreen.lst in the Fileshare Server's current directory .

Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare
Single User Mode


Fileshare Manager

You can use the Fileshare Manager (fsmgr) to automate some of Fileshare's supervisor mode functions by writing a COBOL program to call it. The Fileshare Manager can be called to instruct a Fileshare server to:

  • Perform an automatic backup of its recovery log file
  • Close all of its currently open data files. Any client application accessing these files is returned a file status, indicating that the file is no longer open. This is particularly useful in the event of a system crash or power failure, either of which could cause a Fileshare client program to terminate without disconnecting properly from Fileshare. If this happens, and data files are left open on the Fileshare server, it can prevent automatic disk backups from running and possibly prevent other clients from accessing the files.
  • Log off any clients currently connected to it, close any open files and roll back any incomplete transactions belonging to these clients.Any subsequent access attempts by these client applications result in an error status (9/125).
  • Close down completely. Any open files are closed and any incomplete transactions rolled back
  • Close down completely and then re-start. If a backup directory has been specified in the database reference file, Fileshare copies all the files named in the database reference file to the backup directory, deletes the recovery log file(s) and re-starts with a new recovery log file.
Note: Any Fileshare Clients connected to the Fileshare Server when this instruction is issued will be logged off and any files which they had open will be closed.

The Fileshare Manager program (fsmgr) is called from a COBOL program as follows:

Syntax:

call "fsmgr" using parameter-block

Parameters:

parameter-block
A group item defined as:
function-code
pic xx comp-x.
error-status
pic xx comp-x.
fileshare-name
pic x(16).
supervisor-passwd
pic x(20).
reserved
pic x(24).

On Entry:

function-code
The Fileshare Manager program function required:
1
Backup recovery log file
2
Close all open data files
3
Log off all connected clients
4
Shut down Fileshare
5
Shut down and re-start Fileshare
fileshare-name
The name of the Fileshare server (this is the name that was used when Fileshare was started)
supervisor-passwd
The supervisor password. See the section Supervisor Mode in the chapter Security for more information
reserved
Reserved for future use. Must contain binary zeros.

On Exit:

error-status
Reflects the success, or failure, of the call. Possible values of error-status are shown below.
Value | Description
0 | Function completed successfully
1 Communications error. A Fileshare server of the name specified in fileshare-name could not be contacted on the network using the specified communications protocol. This error is also returned if a network failure occurs during the execution of the function but after the initial connection was made.

Check that fileshare-name is specified correctly and that the Fileshare Handling Redirection module (FHRedir) is configured to use the correct communications protocol.

2 File error during initial connection.

To connect to Fileshare, the Fileshare Manager opens a file called fsmgr.ctl. This file should not already exist and the Fileshare Manager does not actually create it. If it does exist, this status is returned if there is a subsequent error in closing the file.

3 Invalid password specified in supervisor-password.

Ensure that Fileshare is running with a password file and that the contents of supervisor-password match the supervisor password entry in the password file. Note that Fileshare passwords are case sensitive.

See Supervisor Mode in the chapter Security for more information.

4 | Invalid value specified in function-code - must be within the range one to five
5 No Fileshare log file.

You have attempted to backup the log file on a Fileshare server that is running without a recovery log file.

6 Function 2 or 3 could not complete.

While attempting to log off all Fileshare's clients (function 3), it is possible for other clients to log on before the logging off operation completes. For example, the Fileshare Manager has to send a "logoff client n" request four times if there are four clients logged on. If, however, a new client logs on before all four original clients have been logged off, the Fileshare Manager retries the "logoff client n" request in order to log off the new client. It retries 10 times and if new clients are still logging on, it returns error 6. A similar situation can occur during processing of a function 2 (close all data files) if new files are continuously being opened at the same time.

10 | Other error
Parent topic: Advanced Operation
Related information
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare
Supervisor Mode


Fileshare Manager Configuration

Fileshare Manager, like other Fileshare Client applications, accesses a Fileshare server via the Fileshare Handling Redirection module (FHRedir) and so needs to be configured to use the correct communications protocol. See the section Client Configuration in the chapter Configuration for more information.

Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare
Client Configuration


Byte-stream I/O Calls

Fileshare supports some of the byte-stream I/O routines that are available with this COBOL system. Most of the routines use the same parameters and have the same effect as the corresponding COBOL system call, but access remote files via Fileshare. The only change needed to your program is to call the routine starting with FS_ instead of CBL_. The only routine that does not have exactly the same call interface as its corresponding CBL_ routine is FS_LOCATE_FILE.

Fileshare supports the following byte-stream I/O routines:

  • FS_CHECK_FILE_EXIST
  • FS_CLOSE_FILE
  • FS_CREATE_FILE
  • FS_COPY_FILE
  • FS_DELETE_FILE
  • FS_JOIN_FILENAME (see below)
  • FS_LOCATE_FILE (see below)
  • FS_OPEN_FILE
  • FS_READ_FILE
  • FS_RENAME_FILE
  • FS_SPLIT_FILENAME (see below)
  • FS_WRITE_FILE

You can use these routines to access files on remote Fileshare servers, as well as local files. Configure the Fileshare Client in the normal manner to define which files are local and which are remote.

Note:

  • The FS_COPY_FILE routine only works on the Fileshare server and cannot be used to copy the file locally or to another Fileshare server. Currently you would have to code your own FS_OPEN_FILE and FS_READ_FILE/CBL_WRITE_FILE loop to copy the contents of the file locally.
  • Do not use byte-stream I/O and COBOL I/O on the same file
  • If you want to share files between multiple Fileshare Clients you must access the files using normal COBOL I/O verbs
  • FS_LOCATE_FILE
  • FS_SPLIT_FILENAME and FS_JOIN_FILENAME
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
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
Running Fileshare as a Windows Service
Performance Considerations
Large File Support with Fileshare


FS_LOCATE_FILE

The functionality provided by FS_LOCATE_FILE is the same as CBL_LOCATE_FILE except:

  • You cannot use FS_LOCATE_FILE to search for files in libraries on remote Fileshare Servers
  • You can use CBL_LOCATE_FILE to search for files along each path specified in an environment variable. You can then use the returned actual-file-spec as the filename when opening the file.

    If you have specified a $$server-name prefix in user-file-spec, actual-file-spec must contain the same $$server-name prefix for an OPEN using actual-file-spec to be re-directed automatically. By default, Fileshare only returns the filename in actual-file-spec to your program. To return the $$server-name in actual-file-spec, set the most significant bit of user-mode before making the call to FS_LOCATE_FILE.

  • When a remote file is found, using an environment variable containing many paths, FS_LOCATE_FILE returns actual-file-spec including the full path where the file is located

When a call to FS_LOCATE_FILE is directed to a custom file handler by configurable DYNREDIR, the customer file handler is called with op-code FAF8 plus fcd(3:1) and uses the value 5 to specifiy it as an FS_LOCATE_FILE call.

On Entry Fields

On entry, the following fields are set:

fcd-name-ptr | Pointer to the user file
fcd-open-mode | User mode
fcd-optional | Path flag
fcd-name-length | Length of filename

On entry, the length of the fcd-name-length field is the same as the length of the filename pointed to by the field fcd-name-ptr.

On exit, you need to set the following fields:

fcd-record-ptr | Pointer to the actual file spec
fcd-access-mode | Exist flag
fcd-file-status | File status
Parent topic: Byte-stream I/O Calls
Related information
FS_SPLIT_FILENAME and FS_JOIN_FILENAME


FS_SPLIT_FILENAME and FS_JOIN_FILENAME

The functionality provided by FS_SPLIT_FILENAME and FS_JOIN_FILENAME is the same as that provided by the corresponding CBL_routines. In addition, using FS_SPLIT_FILENAME and FS_JOIN_FILENAME you can process filenames that specify Fileshare Server names using the $$server-name prefix at the front of the filename. When processing such filenames, the $$server-name prefix characters are included as part of the pathname parameter.

If you have included the callable sort, and receive error 173 after switching to release build, you need to include fhrsub.obj in your project.

Parent topic: Byte-stream I/O Calls
Related information
FS_LOCATE_FILE


Running Fileshare as a Windows Service

Restriction: This topic applies to Windows environments (local development) only.

You can use the Fileshare Server so that it runs as a Windows service, using the following commands:

fsservice -i [service-name [configuration-options] ]
fsservice -u [service-name]
fsservice -v [service-name]

Where:

-i
Install the service.
-v
Display the status of the service.
-u
Uninstall the service.
service-name
A unique name for the service. The service is called "Micro Focus Fileshare Service:name", where :name is included only if a name is specified. service-name is optional unless you specify configuration-options, in which case it is mandatory.
configuration-options
Options used to start the Fileshare service. See Fileshare Server Configuration .

To start the Fileshare service as a background process and to stop it:

  1. Make sure the License Manager service is started.
  2. Click Control Panel > Services.
  3. Select Micro Focus Fileshare Service[: service-name] from the list of displayed services.
  4. Click Start or Stop as appropriate.

    You can also choose to start the service automatically whenever Windows starts.

Notes:
  • When you stop the service from the Services window, as above, Fileshare closes down as normal. Any connected Fileshare clients are logged off and their data files closed (with any incomplete transactions rolled back).
  • When you shut down Windows, Fileshare is similarly shut down.
  • If you choose it to start the service automatically and you have logging switched on for any data files, we recommend that you specify a Fileshare backup directory in your database reference file.

For example, the following command installs a service called "Micro Focus Fileshare Service: My Service", which will execute in the c:\mydir directory and use a Fileshare server name of myserver:

fsservice -i "My Service" /wd c:\mydir /s myserver
  • Fileshare Server Configuration
Parent topic: Advanced Operation
Related reference
Fileshare Manager
Related information
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


Fileshare Server Configuration

Windows:

When the Fileshare Server service starts, it is configured according to the Fileshare Server configuration file. By default, the service takes its configuration from %windir%\system32\fs.cfg, where %windir% is for example c:\winnt\system32. You can edit this file or create your own here or elsewhere.

The /cf option enables you to specify a configuration file containing the configuration options. For example, the following command installs a service called "Micro Focus Fileshare Service: My Service", which takes its configuration from the file c:\mydir\myfs.cfg:

    fsservice -i "My Service" c:\mydir\myfs.cfg

To use a different working directory, specify this using the /wd option as the first entry in your configuration file. On start-up, Fileshare changes to your specified working directory and accesses any files that are not fully qualified as being relative to this working directory. For example, the following command installs a service called "Micro Focus Fileshare Service: My Service", which will execute in the c:\mydir directory:

    fsservice -i "My Service" /wd c:\mydir /cf c:\mydir\myfs.cfg

Because Fileshare runs as a background process, any messages it generates are written to the file fsscreen.lst in the current working directory. Check the contents of this file to diagnose any problems.

Example:

The following is an example of a Fileshare Server configuration file:

    /wd d:\fsdir
    /s server1
    /d dbase.ref

where:

  • /wd d:\fsdir specifies the directory fsdir on the drive d: as the Fileshare Server's current directory. Any data files without fully qualified pathnames are searched for relative to this directory.
  • /s server1 specifies that the Fileshare Server is to register its name on the network as server1
  • /d dbase.ref specifies that Fileshare is to use the database reference file dbase.ref. Because this name is not fully qualified it is searched for in Fileshare's current directory, that is, d:\fsdir.

For details on the configuration options, see the section Server Configuration in the chapter Configuration.

Parent topic: Running Fileshare as a Windows Service


Performance Considerations

Although Fileshare reduces the number of requests made across the network for COBOL I/O, some types of data file access benefit more than others. The following areas affect Fileshare's ability to improve the speed of accessing remote data:

  • Synchronous communications

    Where possible, you should use Fileshare in synchronous communications mode (/sc). This has been shown to improve performance significantly when using the CCISM protocol. We recommend that asynchronous mode (that is, Fileshare without the /sc setting) should be considered as being for development purposes only; production installations should always use synchronous mode, if possible.

    Note: Synchronous mode is only possible if all clients are using the same protocol to communicate with the Fileshare server.
  • File organization

    A single request to an indexed data file can involve many accesses to the physical data file itself such as reading the header and updating the integrity marker. Complex key structures also increase the number of accesses needed to update the index structure in the file. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network. The simpler data file organizations (relative and sequential files) involve a smaller processing overhead.

    Any speed improvements using Fileshare are therefore more apparent when processing indexed data files.

  • I/O request

    The number of accesses to a data file needed to process a WRITE, DELETE or REWRITE operation is generally larger than the number needed to process a READ or START operation. Using the normal COBOL file handling system, each of these accesses generates a request that is sent across the network. Using Fileshare, only one request is sent across the network.

    Any speed improvements using Fileshare are therefore more apparent when performing WRITE, DELETE or REWRITE operations.

  • Concurrent use of data files

    If your program opens a data file exclusively, the normal COBOL file handling system uses caching. This means that it does not have to check to see if the file has been updated on every I/O operation. The number of requests sent across the network, therefore, is significantly less if the data file is opened exclusively.

    Fileshare provides a greater improvement in performance, therefore, when a large number of users require concurrent access to data files than when files are opened exclusively. This is because access and caching are controlled by the Fileshare Server and so the additional requests needed when accessing a shared data file via the normal COBOL file handling system are not needed.

    Any speed improvements are therefore very specific to individual applications and become more pronounced as more Fileshare Clients concurrently access the same data files.

  • 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
Running Fileshare as a Windows Service
Large File Support with Fileshare


Fileshare Performance on UNIX

Fileshare improves performance when remote COBOL applications are concurrently accessing shared data files across a network but it cannot improve performance when the COBOL data resides on the same machine as the application. In this configuration, there is actually a performance overhead when using Fileshare instead of the standard Callable File Handler.

Although UNIX machines can be used as remote data servers, it is not uncommon for the application itself to run on the machine where the data resides. For example, multiple users may log in, across a network, to a machine where they run applications which share the same data. In such a configuration, you encounter the performance overhead of using Fileshare, making performance slower than when using the standard Callable File Handler.

Parent topic: Performance Considerations


Large File Support with Fileshare

Fileshare, by default, supports files that can be up to 32 Terabytes in size.

An alternative technology, file striping, was introduced in previous releases as an interim solution to overcome limitations on the maximum allowed file size some operating systems permit. It enables you to specify that a single data file is to be stored in multiple physical files (or stripes) on disk.

Because of the complications involved with configuring striping together with Fileshare (these issues are discussed below), we recommend that you keep your large files non-striped and instead, configure the file handler to use its standard large file support.

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
Running Fileshare as a Windows Service
Performance Considerations


Error Handling

This chapter details:
  • Fileshare-specific causes of run-time status codes returned by the COBOL system
  • Communications errors generated by CCI
  • Transaction processing errors
  • Fileshare Extended Status Codes
  • Communications Errors
  • Transaction Processing Errors
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Fileshare Server Messages
Fileshare Server Messages


Fileshare Extended Status Codes

Status Code | Meaning
9/037 Access is denied. In addition to the normal situations where this error occurs, Fileshare generates this error when:
  • An invalid user-ID and/or password is passed to a Fileshare Server and Fileshare Password Security is active
  • A Fileshare Client attempts to access a particular data file and access is denied

See the chapter Security for more information.

9/100 | A CLOSE operation is tried on a data file that is participating in an active transaction. See the section Transaction Processing in the chapter Database Integrity for more information.
9/124 | A communications error occurred between the Fileshare Client and the Fileshare Server. You can call fs_status to determine the cause of the error. For details of this call see the section Communications Errors.
9/125 Caused by one of these conditions:
  • A transaction or record lock timed out. (See the section Automatic Record Lock Timeout in the chapter Database Integrity.)
  • The Fileshare Client has been forced to log off from the Fileshare Server
  • If you are using the Micro Focus File Handler interface, an invalid Fileshare session ID was passed on the call to the File Handling Redirector module. Check that the six bytes of the FCD from offset 79 have not been changed.
  • A previous access to this open file returned a 9/124 status, so further operations cannot be made
9/126 | The record size used on the I/O operation is too large to be handled by the Fileshare Server. See the description of the /m option in the section Server Configuration in the chapter Configuration.
9/173 | When using the virtual file interface, the program-name specified in the database reference file is not found. See the section Virtual File Handler Interface in the chapter Advanced Operation.
Parent topic: Error Handling
Related information
Communications Errors
Transaction Processing Errors
Security
Transaction Processing
Communications Errors
Automatic Record Lock Timeout
Server Configuration
Virtual File Handler Interface


Communications Errors

Error status 9/124 on an I/O operation indicates that a communications error has occurred between the Fileshare Client and the Fileshare Server.

The most common time for error 9/124 to occur is on the very first I/O request that your program makes. It is then that the Fileshare Client tries to contact the Fileshare Server. If the Fileshare Client is unable to do this, it returns error 9/124. If you receive this error, examine the configuration of Fileshare and check that:

  • The Fileshare Server is started and operational
  • You have specified the correct Fileshare Server name. The name that you specify must exactly match the name specified when the Fileshare Server was started.
  • The Fileshare Client and Fileshare Server are configured to use the same CCI communications protocol
  • You have a working network connection between the Fileshare Client and the Fileshare Server and the correct network driver and software is loaded

Once you have made a successful connection and the Fileshare Server is servicing the request from the Fileshare Client, the request is visible if trace is active at the Fileshare Server. See the section Monitoring Fileshare in the chapter Advanced Operation for more information. Any further communications errors are returned to the program using the error code 9/124. This is a fatal error and the Fileshare Client drops the connection to the Server. To determine the cause of the error, call the entry point fs_status in the the File Handling Redirector module. The format of the call is:

call "fs_status" returning cci-status

where the parameter is defined as:

01 cci-status   pic x(2) comp-x.

On return, cci-status contains the CCI error code returned to the File Handling Redirector module from the CCI module. For details of CCI error codes, please refer to your book, Configuring CCI.

You can make an additional call after error 9/124 to obtain an extended error message. This message is in the form of a text string that indicates a CCI-specific error as well as some additional information. The format of the call is:

call "fs_commserr" using by reference buffer
                         by value maxlen
                         by reference actual-len

where the parameters are defined as:

01 buffer       pic x(n).
01 maxlen       pic x(4) comp-5 value length of buffer.
01 actual-len   pic x(4) comp-5.

On return, buffer contains the extended error message and actual-len contains the length of this message. The additional information in the returned message includes:

  • The date and time that the last error 9/124 was returned
  • Last return code from the CCI module (a 4-digit number)
  • Message code (for the File Handling Redirector module's internal use, a 2-digit number)
  • The CCI error message text

In addition, the File Handling Redirector module automatically logs communications errors in a local file called fhneterr.log. Each entry in the log file has the same format as the buffer returned from the fs_commserr call.

If you do not have a call to fs_commserr in your application, you can check this file for more detailed information following a 9/124 error.

This log file is not deleted by the Fileshare Client. You can, however, delete it if its contents are of no interest.

Parent topic: Error Handling
Related information
Fileshare Extended Status Codes
Transaction Processing Errors
Monitoring Fileshare
Configuring CCI


Transaction Processing Errors

The COMMIT and ROLLBACK operations work across many data files. You cannot check the file status of any one data file to see if the COMMIT or ROLLBACK operation was successful. Instead, call the entry point fs_status to determine the status of the COMMIT or ROLLBACK operation.

The format of the call is:

call "fs_status" returning t-status

where the parameter is defined as:

01 t-status   pic x(2) comp-x.

A non-zero status indicates that the COMMIT or ROLLBACK operation failed. Fileshare cannot provide definitive information on transaction processing errors because of the complexity of multiple file transactions across networks.

Parent topic: Error Handling
Related information
Fileshare Extended Status Codes
Communications Errors


Fileshare Server Messages

These are of varying levels of severity:

  • Severe

    Severe level messages indicate that a problem has occurred that has prevented the Fileshare Server carrying out the requested operation. The cause of the error should be rectified and then the operation tried again.

  • Warning

    Warning level messages indicate that a situation was encountered that the Fileshare Server was not expecting, but was able to continue.

  • Informational

    Informational level messages provide information about the operations that the Fileshare Server is performing.

The format of each message is as follows:

FSnnn-x text

where:

Parameter | Description
FS | Fileshare Server message
nnn | Message number
x | Indicates the severity of the message ("S", "W" or "I")
text | Text of the message

For more information on the messages, see the links below.

  • Messages from FS001-S to FS050-W
  • Messages from FS051-W to FS099-W
  • Messages from FS101-I to FS149-I
  • Messages from FS151-I to FS200-W
  • Messages from FS201 to FS300
  • Messages from FS301 - FS400
Parent topic: Fileshare Guide
Related information
Introduction
Standard Operation
Configuring CCI Communications for Fileshare
Database Integrity
Security
Advanced Operation
Error Handling


Messages from FS001-S to FS050-W

  • FS001-S The parameter "text " is not recognized as a valid parameter.
    This error status is displayed when the Fileshare Server parses the specified parameters and finds one which it does not recognize.
  • FS004-S The parameter "text " specifies a time-out value that is invalid.
    The /t parameter has been specified in a configuration file, but the characters following do not conform to a valid specification of a time-out value.
  • FS005-S The parameter "text " is too long or invalid.
    The parameter indicated could not be processed correctly. This can be for one of the following reasons:
  • FS006-S The parameter "text " has already been specified.
    A duplicate parameter has been specified and duplicates are not permitted for this parameter.
  • FS007-S Invalid parameter combination.
    Fileshare has processed the specified parameters and is unable to process the information given.
  • FS008-S Communications Initialization Failure.
    An error has occurred when the Fileshare Server initialized CCI or the Fileshare Server was unable to perform the CCI call because the required operating system and/or Micro Focus communication support modules are not available. This error can also indicate a problem with the network setup on the machine (for example, the required drivers have not been loaded).
  • FS009-S The required communications module cannot be found.
    The Fileshare Server tried to load the CCI module required for the protocol specified, but was unable to do so. This implies that the CCI module (or required support modules) cannot be found or they cannot be loaded.
  • FS011-W Communications send failure.
    The Fileshare Server encountered a communications error when it tried to return the result of an I-O operation to a Fileshare Client. This can imply that there is a problem with the network or that the Fileshare Client process terminated abnormally.
  • FS012-W Communications disconnect failure.
    The Fileshare Server tried to drop the connection with the Fileshare Client, but the communications system returned an error. The Fileshare Server tries to disconnect from Fileshare Clients when:
  • FS013-W Communications receive error.
    An unexpected error occurred while receiving information from the communications system. This error implies a problem with the network software or hardware because a message has been received but could not be processed correctly.
  • FS014-W Communications data length not as expected.
    The information sent from the Fileshare Client to the Fileshare Server includes a check on the amount of information that is being sent. This error occurs when the amount of data received by the Fileshare Server is not the same as the amount sent by the Fileshare Client.
  • FS015-W Request from unknown user - request rejected.
    The information received by the Fileshare Server is not recognized as being from a Fileshare Client that is currently logged onto this Fileshare Server.
  • FS016-S The parameter "text " is invalid.
    The parameter has been recognized as a valid parameter, but the option specified for that parameter is not valid. For example, the /o (omit) parameter has been specified, but the option is not t (transaction processing), l (rollforward recovery logging) or s (sequence number checking).
  • FS017-S Unable to open the file : filename.
    The Fileshare Server is unable to create the file specified.
  • FS018-S Log file corrupt - unrecognizable record in file.
    Each record written to the recovery log file has a marker informing the Rollforward Recovery Utility of the type of data contained in the record.
  • FS019-S Log file corrupt - can't read header.
    Each record written to the recovery log file has a marker indicating the type of data contained in the record. This error indicates that the required header record at the beginning of the log file was not found. This implies that the log file has become corrupt, which can happen, for example, if the system crashed while records were being written to the recovery log file.
  • FS020-S The log file does not match the database sequence numbers - recovery aborted.
    Each index file (not C-ISAM) and all variable length record files have (by default) a sequence number stored in the header of the file. A corresponding sequence number is stored in the log file. Checks are made between the sequence numbers in the file headers and the log file to help ensure that the recovery process proceeds successfully.
  • FS021-S There is no log filename specified in the database reference file.
    You have tried to erase a log file entry from the database reference file but there is no log filename specified in the database reference file. The operation therefore cannot be completed successfully.
  • FS022-S The log filename given cannot be found in the database reference file.
    You have failed to erase a log file entry from the database reference file because the log filename specified is not the same as the log filename in the database reference file.
  • FS024-S Failed to open log file : filename.
    The Fileshare Server encountered an error while trying to open or create the rollforward recovery log file. Common causes of this error are:
  • FS025-S Write failure to the log file, Fileshare Server is closing down.
    The Fileshare Server encountered an error while writing a record to the recovery log file. Because the integrity of the log file cannot be guaranteed, the Fileshare Server shuts down so that the updates performed up to the point of failure are not lost.
  • FS026-W Failed to close the log file.
    The Fileshare Server encountered an error while closing the current log file.
  • FS027-S A second log file parameter has been found.
    While processing the database reference file, a second log file parameter was found. There should only ever be one log file specified in the database reference file and this error indicates that the database reference file is corrupt or has been changed without using the Database Reference File Maintenance Utility.
  • FS028-W The log file shows the last session was not shut down successfully.
    When the Fileshare Server shuts down successfully, the last record written to the recovery log file is a special record that marks the end of the recovery log file. This message indicates that the Fileshare Server could not find the special, last record when it opened the log file, suggesting that the log file was not closed in a controlled manner, probably due to a system crash. The log file could have been opened either to append to or read from in order to perform a rollforward recovery.
  • FS029-S The log filename is already specified in the database reference file.
    You have tried to add the name of the recovery log file to the database reference file. However a log filename already exists in the database reference file. A database reference file can only contain one log filename.
  • FS030-S Insufficient disk space to continue logging to log file.
    The amount of space remaining on the disk where the log file is being written has less than 200K bytes of free space remaining. This is not adequate to ensure that the recovery log file can continue to be successfully written.
  • FS031-I Record lock time-out failure on user : user.
    A record lock time-out has occurred on the user indicated. This is due to the user holding a lock on a record for a period of time longer than the record lock time-out period, when another user is trying to access that locked record.
  • FS034-S A filename or log file parameter must be specified.
    The Database Reference File Maintenance Utility has been invoked using the /d option, however a valid parameter for the utility has not been given
  • FS035-S A database reference file must be specified.
    The Database Reference File Maintenance Utility has been invoked, however the name of the database reference file to use has not been specified using the /d parameter. For example, the parameter /f (filename), /l (log filename), /fs (file string) or /backup (backup directory) has been used to invoke the Database Reference File Maintenance Utility but a /d option has not been specified to supply the name of the database reference file.
  • FS037-I The file filename does not have a file header record. Sequence checking is switched off for this file.
    The Fileshare Server has determined that the file indicated does not have a Micro Focus format file header. It is not possible to have sequence numbering on files that do not contain file headers. However, the configuration of the database reference file specifies that sequence number checking should be applied to this file.
  • FS038-S A matching sequence number not found in filename.
    This error message is displayed when the sequence number in the header of the named file does not match the sequence number in the rollforward recovery log file. See the section Database Sequence Numbering in the chapter Database Integrity for full details of database sequence numbering works.
  • FS039-S Improperly closed file - filename.
    The Fileshare Server has found that the file indicated has been marked as corrupt because it was not closed correctly. This implies that the file was not closed in a controlled manner and that the Fileshare Server last accessing the file terminated abnormally.
  • FS040-S Unable to read the file header record in the file filename.
    The Fileshare Server was able to open the file specified, but was not able to read the file header. The file header consists of the first 128 bytes of the file.
  • FS041-S Unable to update the sequence number in the file filename.
    The Fileshare Server was unable to update the sequence number in the header of the file specified. The sequence number in the header of this file cannot be relied on and hence messages relating to incorrect sequence numbers can be ignored. However, careful checks should be made to ensure that the correct version of the file are in place when starting the Fileshare Server or performing a rollforward recovery.
  • FS042-S Unable to open the database reference file: filename.
    The Fileshare Server was unable to open the database reference file indicated
  • FS043-S The database reference file contains an invalid entry.
    The Fileshare Server has found data in the database reference file which is not as expected. This implies that the database reference file has been changed without using the Database Reference File Maintenance Utility or that the database reference file is corrupt in some way.
  • FS044-S Error reading the database reference file.
    An error was encountered when reading the database reference file. The file was successfully opened by the Fileshare Server. This message implies that the file is corrupt or that a disk I/O error occurred. Alternatively, if the database reference file is on a remote drive, a network error could have occurred.
  • FS045-W Duplicate filename specified in the database reference file.
    A duplicate filename was found when the Fileshare Server processed the database reference file. This message implies that the database reference file has been modified, but not using the Database Reference File Maintenance Utility. A given filename should appear only once in the database reference file.
  • FS050-W A log file is not specified in the database reference file.
    The Fileshare Server processed the database reference file but could not find a rollforward recovery log filename. The database reference file should have a recovery log file specified in order that recovery logging can be performed.
Parent topic: Fileshare Server Messages
Related information
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201 to FS300
Messages from FS301 - FS400


FS001-S The parameter "text " is not recognized as a valid parameter.

The operation did not complete.

Resolution:

Change the indicated parameter and retry the operation.

The valid parameters are given in the sections:

  • Server Configuration in the chapter Configuration
  • Database Reference File Maintenance and Rollforward Recovery Utility in the chapter Database Integrity
  • Password File Maintenance in the chapter Security
Parent topic: Messages from FS001-S to FS050-W
Related information
Server Configuration
Database Reference File Maintenance
Rollforward Recovery Utility
Password File Maintenance


FS004-S The parameter "text " specifies a time-out value that is invalid.

The time-out value is specified in seconds and must be in the range 0 through 99999.

See the section Automatic Record Lock Timeout in the chapter Database Integrity for more information.

Resolution:

Retry the operation using a time-out value in the correct range.

Parent topic: Messages from FS001-S to FS050-W
Related information
Automatic Record Lock Timeout


FS005-S The parameter "text " is too long or invalid.

  • The parameter specified is too long. For example a password has been specified which is more than 20 characters in length.
  • The parameter expects a value, but none has been given. For example, the /t parameter has been specified but no time-out value has been given.

Resolution:

Retry the operation using a correct value for the parameter indicated.

Parent topic: Messages from FS001-S to FS050-W


FS006-S The parameter "text " has already been specified.

Resolution:

Retry the operation ensuring that only one occurrence of the parameter exists.

Parent topic: Messages from FS001-S to FS050-W


FS007-S Invalid parameter combination.

This can be for the following reasons:

  • Not enough parameters have been specified in order for the operation to be processed. For example, you have tried to start the Fileshare Server without giving a server name.
  • The parameters specified do not indicate a valid operation that can be carried out. For example, the combination /s and /r is invalid as the first implies that the Fileshare Server is to start with the server name indicated, whereas the second parameter indicates that a Rollforward Recovery is to be performed.

Resolution:

Ensure that the parameters specified are correct and retry the operation.

Parent topic: Messages from FS001-S to FS050-W


FS008-S Communications Initialization Failure.

Resolution:

Ensure that the required CCI module(s) required for the protocol you are using is/are available. Use the CCI demo program supplied with the product to ensure that the CCI module required can be loaded and initialized.

Ensure that the network software on the machine is installed, configured and operational.

Parent topic: Messages from FS001-S to FS050-W


FS009-S The required communications module cannot be found.

Resolution:

Ensure that the CCI (and required network modules) are installed correctly on the machine.

Try out the CCI demo program supplied with the product with the same CCI protocols before trying the start the Fileshare Server again.

Parent topic: Messages from FS001-S to FS050-W


FS011-W Communications send failure.

See the message FS148-I for more information.

Resolution:

No user action is possible. However, if the error persists, this could indicate that there is a possible problem with the network or that the network has a high volume of traffic.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS148-I


FS012-W Communications disconnect failure.

  • It receives a request from an unknown Fileshare Client
  • The CCI protocol indicated that the Fileshare Client application terminated abnormally

Resolution:

If the error persists, there could be a problem with the network that is being used. Also, ensure that users are closing down Fileshare Client applications correctly and not turning the workstation machines off or using utilities to terminate the Fileshare applications abnormally (for example kill on UNIX).

Parent topic: Messages from FS001-S to FS050-W


FS013-W Communications receive error.

See the message FS148-I for more information about the cause of the error.

Resolution:

No direct action by the user is possible. However, if the error persists, there could be a problem with the network that is being used or there could be a high volume of network traffic.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS148-I


FS014-W Communications data length not as expected.

This error should not occur in normal circumstances. If found, it implies that there is a problem with the communications system or that the requester service has not been started when using the NETBIOS protocol.

The Fileshare Server has ignored the data sent from the Fileshare Client.

See also the messages FS151-I and FS082-S for additional information.

Resolution:

If using the NETBIOS protocol, ensure that it is installed correctly, configured and operational.

It is highly likely that the Fileshare Client appears to have stopped because the Fileshare Server has not sent back any reply. Depending on the CCI protocol being used, a time-out occurs in approximately two minutes and a 9/124 status is returned to the application program.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS151-I
FS082-S


FS015-W Request from unknown user - request rejected.

The Fileshare Server has ignored the information that it has received and has returned a 9/125 error status to the Fileshare Client that sent the request.

With some CCI protocols, the session associated with this request is disconnected. See the message FS238-I for additional information.

Resolution:

No action is required.

Parent topic: Messages from FS001-S to FS050-W
Related information
FS238-I


FS016-S The parameter "text " is invalid.

Resolution:

Change the parameter specified to a valid option.

Parent topic: Messages from FS001-S to FS050-W


FS017-S Unable to open the file : filename.

The file may be open already or marked as read-only.

Resolution:

Ensure that the path and filename are valid and that the Fileshare Server has read and write access to the directory.

Parent topic: Messages from FS001-S to FS050-W


FS018-S Log file corrupt - unrecognizable record in file.

This error indicates that the marker in the record header is not recognized which implies that the log file has become corrupted in some way.

This error can occur if the last record of the recovery log file was not written successfully because of a system crash. The Recovery Utility will have processed all of the records up to the point of failure.

Resolution:

Ensure that the correct log file is available to the Fileshare Rollforward Recovery Utility.

Parent topic: Messages from FS001-S to FS050-W


FS019-S Log file corrupt - can't read header.

Resolution:

Ensure that the correct log file is available to the Fileshare Rollforward Recovery Utility. If the correct log file is in place, then the file is corrupt and cannot be used in a rollforward recovery process.

Parent topic: Messages from FS001-S to FS050-W


FS020-S The log file does not match the database sequence numbers - recovery aborted.

This error indicates one of the following:

  • The sequence number in the file headers is greater than that in the log file. This indicates that updates have been applied to the files, without the updates being logged in the log file. Because the log file does not contain all of the updates, it is not possible to perform a rollforward recovery. This also indicates that the rollforward recovery is trying to use the wrong versions of the files.
  • The first sequence number in the recovery log file is larger than the sequence number in the file headers. This indicates that updates have been written to the log file but they have not been applied to the data files. It is not possible to apply the updates from the recovery log file because the versions of the data files and the recovery log file do not match.

Resolution:

Ensure that the correct versions of the data and rollforward recovery log file are being used.

See the section Database Sequence Numbering in the chapter Database Integrity for more information.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Sequence Numbering


FS021-S There is no log filename specified in the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS001-S to FS050-W


FS022-S The log filename given cannot be found in the database reference file.

Resolution:

Specify the correct name of the log file when trying to erase the entry from the database reference file.

Parent topic: Messages from FS001-S to FS050-W


FS024-S Failed to open log file : filename.

  • The Fileshare Server does not have read/write access to the log file and/or the directory where the log file resides.
  • The filename specified for the log file is invalid. The filename may not be a valid filename for the operating system on which the Fileshare Server resides or the path specified in the log filename specifies a drive/directory that does not exist.
  • The log file is in use by another process, preventing the Fileshare Server from obtaining exclusive access to the log file.
  • The operating system or the COBOL run-time system is unable to allocate a file handle to the log file.
Parent topic: Messages from FS001-S to FS050-W


FS025-S Write failure to the log file, Fileshare Server is closing down.

The cause of the failure should be investigated. Possible causes include the disk is full, a disk error or, if logging to a remote drive, a network error occurred.

Resolution:

We advise you to have the recovery log file local to where the Fileshare Server is running so that the chances of network errors occurring while writing to the log file are reduced. Also, the Fileshare Server cannot force the operating system to flush records to disk if the log file is not on the local machine.

Parent topic: Messages from FS001-S to FS050-W


FS026-W Failed to close the log file.

Possible causes are that the disk is full or, if logging to a remote drive, a network error occurred.

We advise you to have the recovery log file local to where the Fileshare Server is running so that the chances of network errors occurring while writing to the log file are reduced.

The cause of the failure should be investigated.

Resolution:

It should be possible to use this recovery log file in a rollforward recovery operation as the Fileshare Server has written all of the required information to the file.

Parent topic: Messages from FS001-S to FS050-W


FS027-S A second log file parameter has been found.

Resolution:

Ensure that the correct database reference file is used and that only one recovery log filename is specified in the database reference file.

Only use the Database Reference File Maintenance Utility to change the contents of the database reference file. In this situation however, it may be possible to remove the duplicate entry using a normal text editor. Alternatively the current database reference file can be discarded and a new one created using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS001-S to FS050-W


FS028-W The log file shows the last session was not shut down successfully.

If the Fileshare Server is starting up, the log file is backed up and a new log file created. If you have specified a backup directory in the database reference file, the Rollforward Recovery Utility is invoked automatically.

If a rollforward recovery is being performed, recovery proceeds up to the last full record in the recovery log file (any incomplete transactions are rolled back).

Resolution:

No action is required

Parent topic: Messages from FS001-S to FS050-W


FS029-S The log filename is already specified in the database reference file.

Resolution:

Remove the current log filename from the database reference file using the Database Reference File Maintenance Utility and then add the name of the new log file using the same utility.

Parent topic: Messages from FS001-S to FS050-W


FS030-S Insufficient disk space to continue logging to log file.

The Fileshare Server will close the current recovery log file and wait for it to be backed up before continuing.

Resolution:

Manually back up the current log file and then delete the file. This releases disk space and enables the Fileshare Server to continue logging with a new logfile.

Parent topic: Messages from FS001-S to FS050-W


FS031-I Record lock time-out failure on user : user.

This record lock time-out has caused any transactions that this user has outstanding to be automatically rolled back and all record locks held by this user have been released. See the section Automatic Record Lock Timeout in the chapter Database Integrity for more information.

You can specify the record lock time-out period using the /t option when you configure the Fileshare Server.

On the next I/O operation, a status of 9/125 will be returned to the Fileshare Client application that held the lock.

Resolution:

No action is required, however the time-out period can be changed or disabled if required.

Parent topic: Messages from FS001-S to FS050-W
Related information
Automatic Record Lock Timeout


FS034-S A filename or log file parameter must be specified.

Resolution:

Ensure that when invoking the Database Reference File Maintenance Utility, the option /f (filename), /l (log filename), /fs (file string) or /backup (log file backup directory) is used to specify which action should be taken

Parent topic: Messages from FS001-S to FS050-W


FS035-S A database reference file must be specified.

Resolution:

Include the /d option when invoking the Database Reference File Maintenance Utility to provide the name of the database reference file to use

Parent topic: Messages from FS001-S to FS050-W


FS037-I The file filename does not have a file header record. Sequence checking is switched off for this file.

The Fileshare Server will not apply sequence number checking to this file.

Resolution:

The programs accessing the files should be changed so that they define the files as variable length record files.

It is not possible to have sequence number checking on line sequential files.

If sequence number checking is required, the file must contain a file header. Fixed length indexed, sequential and relative files should be converted to variable length record format.

Alternatively, if sequence number checking is not required for this file, this message can be avoided by explicitly turning sequence number checking off using the /o s option in this file's entry in the database reference file. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Reference File Maintenance


FS038-S A matching sequence number not found in filename.

The named file is listed in the database reference file and sequence number checking is active for the file. This message indicates that an incorrect version of the file is being used. The Fileshare Server does not start until this problem is rectified.

Resolution:

Ensure that the correct version of the file is available to the Fileshare Server and that if sequence numbering is used, all updates performed to the file are done via the Fileshare system. See the section Database Sequence Numbering in the chapter Database Integrity for more information.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Sequence Numbering


FS039-S Improperly closed file - filename.

Resolution:

The file is corrupt and a backup should be put in place and recovery performed using the Rollforward Recovery Utility. See the section Rollforward Recovery Utility in the chapter Database Integrity for details. If you have specified a backup directory in the database reference file, the recovery will be performed automatically.

If updates to the file have not been logged then the file should be rebuilt using the REBUILD utility.

Parent topic: Messages from FS001-S to FS050-W
Related information
Rollforward Recovery Utility


FS040-S Unable to read the file header record in the file filename.

Resolution:

If sequence number checking is not required for this file then this feature should be omitted for this file using the /o s option in the database reference file.

All files that can have sequence number checking are at least 128 bytes in length as this is the size of a file header (which is required for sequence number checking to be performed).

Parent topic: Messages from FS001-S to FS050-W


FS041-S Unable to update the sequence number in the file filename.

Resolution:

This error is very rare and implies a disk I/O error (or a network error if the file is not on the local Fileshare Server machine).

Parent topic: Messages from FS001-S to FS050-W


FS042-S Unable to open the database reference file: filename.

Resolution:

Ensure that the path and filename are correct and that the Fileshare Server has full read and write access to the file specified.

Also ensure that the Fileshare Server can gain exclusive access to the database reference file and that another process does not have the file open.

Parent topic: Messages from FS001-S to FS050-W


FS043-S The database reference file contains an invalid entry.

Resolution:

Ensure that only the Database Reference File Maintenance Utility is used to change the contents of the database reference file.

Alternatively, discard the current database reference file and re-create the contents of the file using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS001-S to FS050-W


FS044-S Error reading the database reference file.

Resolution:

Try the operation again. If the problem persists, the database reference file is probably corrupt - the current file should be discarded and a new database reference file created using the Database Reference File Maintenance Utility

Parent topic: Messages from FS001-S to FS050-W


FS045-W Duplicate filename specified in the database reference file.

Resolution:

Recreate the database reference file ensuring that each filename appears in the file only once.

Parent topic: Messages from FS001-S to FS050-W


FS050-W A log file is not specified in the database reference file.

Resolution:

If rollforward recovery logging is required, add an entry to the database reference file specifying a rollforward recovery log filename. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Parent topic: Messages from FS001-S to FS050-W
Related information
Database Reference File Maintenance


Messages from FS051-W to FS099-W

  • FS051-W Failure to allocate a larger buffer, the I-O request failed.
    When using compression on the communication buffers, this message indicates that there was not enough memory available to the Fileshare Server to enable it to decompress the buffer. The I/O request has failed and the Fileshare Client was returned a 9/105 (out of memory) error.
  • FS052-S Failure to allocate required memory. The Fileshare Server is closing down.
    You see this message when the Fileshare Server is initializing and cannot allocate enough memory for the required internal tables
  • FS055-S The parameter "text " specifies a configuration file that does not exist.
    The Fileshare Server is unable to locate or open the configuration file indicated
  • FS056-S The parameter "text " specifies a data compression value that is not within the range 0-255.
    You have tried to add an entry to the database reference file. This entry specifies a value for the data compression outside of the permitted limits. The data compression option must specify a value within the range 0 through 255. To use the routine CBLDC001 as the compression method on records in the file, specify a compression value of 1.
  • FS057-S The parameter "text " specifies a key compression value that is not within the range 0-7.
    You have tried to add an entry to the database reference file which specifies a value for the key compression outside of the permitted limits.
  • FS058-S Failure to allocate memory for the decompression of the log file.
    The Rollforward Recovery Utility has been invoked but is unable to allocate the required memory so that it can process the recovery log file. This error is displayed during the initialization of the recovery process and indicates a shortage of available memory.
  • FS059-S Failure to allocate the memory required for processing the database reference file.
    When reading in a database reference file (either when the Fileshare Server or the Rollforward Recovery Utility is starting) this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the database reference file
  • FS062-S Failure creating the password file filename.
    The Fileshare Server was unable to create the password file indicated
  • FS063-S Failure opening the password file filename.
    The Fileshare Server was unable to open the password file indicated
  • FS064-S Failure reading the password file filename.
    The Fileshare Server encountered an error reading the information from the password file. This implies that an I/O error occurred, the password file has become corrupted in some way or that a network error occurred if the password file is located on a remote machine.
  • FS065-S The password file is not of a recognized format.
    The first record in the password file is a special record which indicates to the Fileshare Server that the file is a password file. This record also contains information regarding the version of the password file being used.
  • FS066-S The specified user name already exists in the password file.
    You see this message when using the Password File Maintenance Utility and you have tried to add a user name to the password file when the user name already exists in the password file
  • FS068-I The password file is now empty and has been deleted.
    You see this message when you have used /e (erase) option with the Password File Maintenance Utility to remove the last entry from the password file. As the password file is now empty, it has been deleted. If a new password file is required it is created automatically when you add an entry using the Password File Maintenance Utility.
  • FS069-S The specified entry could not be found in the password file.
    This message indicates that you have used /e (erase) option with the Password File Maintenance Utility to remove an entry, but the entry specified does not exist in the password file.
  • FS070-S Failure writing to the password file.
    The Password Maintenance Utility encountered an error when it tried to write information to the password file. This implies that an I/O error occurred (possibly a full disk) or a network error was encountered (if the password file is on a remote machine). The integrity of the password file cannot be guaranteed.
  • FS071-W Unable to load the module FHXSCOMP to decompress the data area.
    This message indicates that the Fileshare Server has received a compressed communications buffer. However, it is unable to load the decompression module FHXSCOMP in order to perform the necessary decompression. There may not be enough memory to load the module or the module may not be found.
  • FS072-S The parameter "text " contains a wild card which is not allowed with this parameter.
    A parameter containing a wild card symbol was specified when invoking the Database Reference File Maintenance Utility but the parameter does not support wild cards.
  • FS073-S Failure to allocate memory to process the password file.
    When reading in a password file (when either the Fileshare Server or the Password File Maintenance Utility is starting), this message indicates that the Fileshare Server was not able to allocate the required memory to be able to process all of the information in the password file.
  • FS074-S The Fileshare Server (NLM) failed to log on to NetWare with the login id specified.
    NLM: This message is only applicable to the Fileshare NLM.
  • FS075-W Unable to load the module FSSECLOG - LOGON has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS076-W Unable to load the module FSSECOPN - OPEN has been denied.
    This message indicates that the Fileshare Server failed to call the module FSSECLOG because:
  • FS077-S A Fileshare Server of the same name has already been defined - the Fileshare Server is closing down.
    When the Fileshare Server starts up, it registers its name on the network so that Fileshare Clients can connect to it. This message indicates that the Fileshare Server is trying to register with a name that is already in use by another Fileshare Server on the network.
  • FS078-S No password file has been specified for the use of background mode.
  • FS079-S A supervisor password entry must exist for the use of background mode.
  • FS080-S No password file has been specified for the use of the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a supervisor-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMgr. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS081-S A supervisor password must be specified in the password file for the synchronous communications mode.
    You have tried to start the Fileshare Server using synchronous communications (as opposed to asynchronous communications which is the default). To enable the use of synchronous communications, you must specify a password file which contains a user-ID of FSVIEW. This enables the Fileshare Server to be closed down remotely using FSVIEW or FSMGR. This is necessary because in this communications mode, the Fileshare Server only checks for keyboard input very occasionally.
  • FS082-S The Netbios communications protocol is not responding. Ensure the requester software is loaded and functional.
    You have tried to start the Fileshare Server using the Netbios protocol (CCINETB) but the required network software is not loaded or is not operational. The Fileshare Server is trying to use the NETBIOS software but is receiving invalid data.
  • FS083-S Incompatible CCIIPX.NLM version.
    The Fileshare NLM Server has detected that the version of cciipx.nlm being used is not a compatible version. You are probably trying to use an old version of the CCIIPX NLM with this version of the Fileshare NLM.
  • FS084-I Fileshare Server is starting.
    This message indicates that the Fileshare Server is in the process of initializing. The configuration, database reference and password files (if specified) are being processed and the communications software is being loaded and initialized.
  • FS085-I Fileshare Server is active.
    This message indicates that the Fileshare Server has completed its initialization processing and is now ready to accept incoming requests from Fileshare Clients. At this stage all of the configuration, database reference and password files have been processed and the communications software has been successfully initialized and is operational.
  • FS086-I Fileshare Server is closing down.
    This message indicates that the Fileshare Server has started the process of closing down and will shortly terminate. This can be invoked by the following:
  • FS087-I Fileshare Server has closed down.
    This message indicates that the Fileshare Server has completed all of its termination processing. All communications have stopped, all files closed, all transactions rolled back and any rollforward recovery log file shut. The Fileshare Server can now be restarted when necessary.
  • FS089-I Database Reference File Maintenance Utility.
    The Database Reference File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file. The Database Reference File Maintenance Utility will try to process the remaining parameters specified as options to this utility.
  • FS090-I Database Reference File installation completed successfully.
    The Database Reference File Maintenance Utility has been invoked successfully and the required change made to the database reference file has been made.
  • FS091-I Rollforward Recovery Utility
    The Rollforward Recovery Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS092-I Rollforward Recovery has completed.
    The recovery process is now complete: the files contain the updates recorded in the log file when the Fileshare Server was in use.
  • FS094-I Password File Maintenance Utility.
    The Password File Maintenance Utility has been invoked using the parameters specified on the command line or in the Fileshare Server configuration file.
  • FS096-I Password File installation has completed.
    The Password File Maintenance Utility has successfully updated the password file using the options specified when the Password File Maintenance Utility was invoked.
  • FS097-I Are you sure that you wish to close down the Fileshare Server ? (Y/N)
    You have used the Esc key sequence to close down the Fileshare Server. This message is an additional prompt to avoid closing down the Fileshare Server in error.
  • FS099-W File I/O status was not as expected. Returned status: status Expected status: status Action code: text File: filename.
    This error occurs when a file is being recovered using the Rollforward Recovery Utility. When the log file is written during the normal operation of the Fileshare Server, a record is made in the log file of the status of each I/O operation performed. At the time of recovery, the status returned during the recovery process is compared with that stored in the recovery log file.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS101-I to FS149-I
Messages from FS151-I to FS200-W
Messages from FS201 to FS300
Messages from FS301 - FS400


FS051-W Failure to allocate a larger buffer, the I-O request failed.

Resolution:

Free some memory on the machine where the Fileshare Server is running so that it is able to increase the size of its decompression buffers.

Alternatively, reconfigure the Fileshare System so that compression on the communications buffers is not used.

Parent topic: Messages from FS051-W to FS099-W


FS052-S Failure to allocate required memory. The Fileshare Server is closing down.

Resolution:

Free some memory on the machine where the Fileshare Server is running so that more memory is available to the Fileshare Server.

Parent topic: Messages from FS051-W to FS099-W


FS055-S The parameter "text " specifies a configuration file that does not exist.

Resolution:

Ensure that the path and filename are correct and that the Fileshare Server has read access to the file. Also ensure that no other process currently has the file open as the Fileshare Server requires exclusive access to the configuration file.

Parent topic: Messages from FS051-W to FS099-W


FS056-S The parameter "text " specifies a data compression value that is not within the range 0-255.

The specification of compression of records only takes effect when the file is created. Specifying data compression on a file that already exists and contains uncompressed records has no effect.

Resolution:

Specify a data compression value of 0 through 255

See the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /k parameter and valid options.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS057-S The parameter "text " specifies a key compression value that is not within the range 0-7.

The key compression option must specify a value within the range 0 through 7.

Specifying key compression only has an effect at the time that the file is created. Specifying key compression on a file that already exists, but does not have key compression, has no effect.

Resolution:

Specify a key compression value of 0 through 7.

See the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /k parameter and valid options.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS058-S Failure to allocate memory for the decompression of the log file.

Resolution:

Increase the amount of available memory by reducing the number of processes and/or applications running on the same machine where you are running the Rollforward Recovery. Then try to run the Rollforward Recovery Utility again.

Parent topic: Messages from FS051-W to FS099-W


FS059-S Failure to allocate the memory required for processing the database reference file.

Resolution:

Try to make more memory available to the Fileshare Server by reducing the number of processes or applications that are running on the same machine. If this is not possible, reduce the amount of information that is contained in the database reference file.

Parent topic: Messages from FS051-W to FS099-W


FS062-S Failure creating the password file filename.

Resolution:

Ensure that the path and filename are valid and that the specified file is not already open by another process. The Fileshare Server requires read and write permission to the password file and tries to create the file with exclusive access.

Parent topic: Messages from FS051-W to FS099-W


FS063-S Failure opening the password file filename.

Resolution:

Ensure that the path and filename are valid and that the specified file is not already open by another process. The Fileshare Server requires read and write permission to the password file and tries to open the file with exclusive access.

Parent topic: Messages from FS051-W to FS099-W


FS064-S Failure reading the password file filename.

Resolution:

Retry the operation. If the message persists, the password file may be corrupt and should be discarded. A new password file should then be created using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS065-S The password file is not of a recognized format.

This message indicates that the Fileshare Server has not recognized this record in the file as being that identifying a password file. Alternatively the password file has become corrupt.

Resolution:

Check that the path and filename of the password file specified are correct.

If they are correct then the current password file should be discarded and a new one created using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS066-S The specified user name already exists in the password file.

Resolution:

To update a user entry that already exists in the password file, first erase the entry and then add the new entry to the file. See the section Password File Maintenance in the chapter Security for more details.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS068-I The password file is now empty and has been deleted.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS069-S The specified entry could not be found in the password file.

Resolution:

Ensure that the user name and password are correct (that is, exactly those which were specified for the entry to be erased when the entry was first added to the password file). If the user-ID or password are no longer known, you must create a new password file using the Password File Maintenance Utility.

Parent topic: Messages from FS051-W to FS099-W


FS070-S Failure writing to the password file.

Resolution:

Restore the password file from a backup and try to add the new entry again. If no backup is available, discard the current password file and create a new one using the Password File Maintenance Utility.

Ensure that there is enough disk space available on the drive where the password file resides.

Parent topic: Messages from FS051-W to FS099-W


FS071-W Unable to load the module FHXSCOMP to decompress the data area.

Alternatively there may be an insufficient number of file handles available to enable the operating system or run-time system to load the module.

The request received from the Fileshare Client has been discarded.

Resolution:

Ensure that the system module FHXSCOMP is available on your system. Also ensure that there is enough memory available for the module to be loaded and file handles are available to enable the run-time or operating system to load the file.

Parent topic: Messages from FS051-W to FS099-W


FS072-S The parameter "text " contains a wild card which is not allowed with this parameter.

Wild cards are only permitted on database entries defining an alternate program.

See the /ap option in the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Resolution:

Do not specify a wild card symbol for this parameter.

A full path or filename should be given.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS073-S Failure to allocate memory to process the password file.

Resolution:

Try to make more memory available to the Fileshare Server by reducing the number of processes or applications that are running on the same machine. Alternatively, reduce the amount of information that is contained in the password file.

Parent topic: Messages from FS051-W to FS099-W


FS074-S The Fileshare Server (NLM) failed to log on to NetWare with the login id specified.

You see this message when using the /nu option to force the Fileshare Server to log onto NetWare with the specified user-ID. However, the Fileshare NLM Server encountered an error when trying to connect with the user-ID specified. This implies that there is no user account with the user-ID set up on the NetWare server or that you entered an incorrect password when prompted to do so.

Resolution:

Check that the user-ID is correct and that a user account for that ID is defined on the NetWare operating system. Also check that the correct password for this user-ID was entered when prompted.

Parent topic: Messages from FS051-W to FS099-W


FS075-W Unable to load the module FSSECLOG - LOGON has been denied.

  • FSSECLOG is not available
  • There is insufficient memory available to load FSSECLOG
  • There may be an insufficient number of file handles available to enable the operating system or run-timesystem to load FSSECLOG

FSSECLOG is required to validate logon requests to the Fileshare Server by Fileshare Clients. Because one possible cause of this error is that the FSSECLOG module has been removed on purpose, the Fileshare Server does not permit the logon to proceed in this situation.

The Fileshare Client application program has received a 9/037 error status.

Resolution:

Ensure that the module FSSECLOG is available to the Fileshare Server (this can be the FSSECLOG module supplied with the Fileshare system or a user-written one). If the module is available, try making more memory available by reducing the number of other processes or applications running on the machine and ensure that there are enough free file handles available to enable the module to be loaded.

See the chapter Security for more information about the FSSECLOG module.

Parent topic: Messages from FS051-W to FS099-W
Related information
Security


FS076-W Unable to load the module FSSECOPN - OPEN has been denied.

  • FSSECOPN is not available
  • There is insufficient memory available to load FSSECOPN
  • There may be an insufficient number of file handles available to enable the operating system or run-timesystem to load FSSECOPN

FSSECOPN is required to validate open requests to the Fileshare Server by Fileshare Clients. Because one possible cause of this error is that the FSSECOPN module has been removed on purpose, the Fileshare Server does not permit the open to proceed in this situation.

The Fileshare Client application program has received a 9/037 error status.

Resolution:

Ensure that the module FSSECOPN is available to the Fileshare Server (this can be the FSSECOPN module supplied with the Fileshare system or a user-written one). If the module is available, try making more memory available by reducing the number of other processes or applications running on the machine and ensure that there are enough free file handles available to enable the module to be loaded.

See the chapter Security for more information about the FSSECOPN module.

Parent topic: Messages from FS051-W to FS099-W
Related information
Security


FS077-S A Fileshare Server of the same name has already been defined - the Fileshare Server is closing down.

Alternatively, this message can indicate that a Fileshare Server that was using this name terminated abnormally and did not de-register its name from the network.

Resolution:

Ensure that the Fileshare Server name is unique for this server. This is the name that the Fileshare Server is configured to register on the network. If a Fileshare Server that was using this name terminated abnormally, it may be necessary to re-initialize the network software on the machine where that Fileshare Server was running to ensure that its name is no longer registered (what action is required in this situation depends on the communications protocol that is being used).

Parent topic: Messages from FS051-W to FS099-W


FS078-S No password file has been specified for the use of background mode.

UNIX:

This message is applicable to Fileshare Servers on UNIX only.

It is possible to configure the Fileshare Server to run as a daemon process on UNIX so that information is neither accepted from the keyboard nor displayed on the screen. When configuring the Fileshare Server to run in this mode, a password file must be used which should contain a FSVIEW (supervisor) user-ID and password. This enables the Fileshare Server to be closed down remotely using FSView, FSMgr or COBFSCLOSE.

This message indicates that you have tried to run the Fileshare Server in background mode but you have not specified a password file.

Resolution:

Create a password file using the Password File Maintenance Utility containing a user-ID of FSVIEW and a password. Then specify this password file (using the -pf option) in the Fileshare Server configuration file.

See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS079-S A supervisor password entry must exist for the use of background mode.

UNIX:

This message is applicable to Fileshare Servers on UNIX only.

It is possible to configure the Fileshare Server to run as a daemon process in the background on UNIX where no information is accepted from the keyboard nor displayed on the screen. When configuring the Fileshare Server to run in this mode, a password file must be used which should contain an FSVIEW (supervisor) user-ID and password. This enables the Fileshare Server to be closed down remotely using FSMgr, FSView or COBFSCLOSE.

This message indicates that you have tried to run the Fileshare Server in background mode but the password file that you specified does not contain an FSVIEW (supervisor) user-ID or password.

Resolution:

Add a user-ID of FSVIEW and password to the password file specified using the Password File Maintenance Utility.

See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS080-S No password file has been specified for the use of the synchronous communications mode.

Resolution:

When starting the Fileshare Server, use the /pf option in the Fileshare Server configuration file to specify the name of a password file containing a user-ID of FSVIEW. See the sections Password System and Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password System
Password File Maintenance


FS081-S A supervisor password must be specified in the password file for the synchronous communications mode.

This message indicates that a password file has been specified, however, there is no (supervisor) user-ID of FSVIEW in the password file.

Resolution:

Add a user-ID of FSVIEW and a password to the password file using the Password File Maintenance Utility and try the operation again. See the section Password File Maintenance in the chapter Security for more information.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS082-S The Netbios communications protocol is not responding. Ensure the requester software is loaded and functional.

Resolution:

Ensure that the NETBIOS software has been loaded, is functioning and is configured correctly on the machine where you are trying to start the Fileshare Server. Try to start the Fileshare Server again. Alternatively, use another communications protocol.

See the message FS014 for further information.

Parent topic: Messages from FS051-W to FS099-W
Related information
FS014


FS083-S Incompatible CCIIPX.NLM version.

Resolution:

Ensure that the version of cciipx.nlm supplied with the Fileshare Server NLM is the one on the system and that this version is loaded in preference to any earlier version (meaning that this version is on the search path before any older version of the CCIIPX NLM)

Parent topic: Messages from FS051-W to FS099-W


FS084-I Fileshare Server is starting.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS085-I Fileshare Server is active.

Fileshare Client applications can now be started and communicate with this Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS086-I Fileshare Server is closing down.

  • The Fileshare Server encountered an error when starting up, for example an error was found in a configuration, database reference or password file. Alternatively the communications support could not be started.
  • The user has requested to shut down the Fileshare Server (either by the Esc key sequence or a remote request from FSView or FSMgr)
  • The Fileshare Server has encountered an unrecoverable error during its operation. For example, the remaining disk space where the rollforward recovery log file resides is below the acceptable limits for logging to continue.
  • The Fileshare Server process was terminated by an event external to the Fileshare Server(for example a kill command on UNIX)

The Fileshare Server is closing all outstanding connections with Fileshare Clients, rolling back any outstanding transactions, closing all open files and shutting down the communication support.

Depending on the communications protocol that is in use, the Fileshare Client applications may appear to suspend if they are still trying to send requests to this Fileshare Server.

Resolution:

No action is required

Parent topic: Messages from FS051-W to FS099-W


FS087-I Fileshare Server has closed down.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS089-I Database Reference File Maintenance Utility.

If the Database Reference File Maintenance Utility should not have been invoked, check the command line to ensure that neither the /d option nor any other valid Database Reference File Maintenance option has been specified. See the section Database Reference File Maintenance in the chapter Database Integrity for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Database Reference File Maintenance


FS090-I Database Reference File installation completed successfully.

The database reference file specified now contains the change required.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS091-I Rollforward Recovery Utility

If the Rollforward Recovery Utility should not have been invoked, check the command line to ensure that neither the /r option nor any other valid Rollforward Recovery Utility option has been specified. See the section Rollforward Recovery Utility in the chapter Database Integrity for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Rollforward Recovery Utility


FS092-I Rollforward Recovery has completed.

If the updates have been applied successfully, you should back up the recovered files and use a new log file when you restart the Fileshare Server. This ensures that the new recovery log file is in step with the current data files.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS094-I Password File Maintenance Utility.

If the Password File Maintenance Utility should not have been invoked, check the command line to ensure that the /pf option has been used correctly and that no other option specific to the Password File Maintenance Utility has been used. See the section Password File Maintenance in the chapter Security for more details.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W
Related information
Password File Maintenance


FS096-I Password File installation has completed.

Resolution:

No action is required.

Parent topic: Messages from FS051-W to FS099-W


FS097-I Are you sure that you wish to close down the Fileshare Server ? (Y/N)

The Fileshare Server does not accept input from Fileshare Clients whilst waiting for the response to this prompt. Consequently, you should respond quickly to this prompt.

Resolution:

Responding Y to this prompt causes the Fileshare Server to start its termination processing. If there are any files open or users logged onto this Fileshare Server, an additional prompt and confirmation are displayed. When the Fileshare Server shuts down, it rolls back all outstanding transactions, closes all open files, logs off all users and closes down the communication support modules.

If you give any reponse other than Y, the Fileshare Server continues operating as normal.

Parent topic: Messages from FS051-W to FS099-W


FS099-W File I/O status was not as expected. Returned status: status Expected status: status Action code: text File: filename.

This message indicates that the status returned during the recovery process was not the same as that when the operation was performed during the normal Fileshare Server processing when the log file was written.

The Returned status is the status that the Rollforward Recovery Utility encountered when trying to apply the updates from the recovery log file to the data files.

The Expected Status is the status that was returned when this operation was originally performed by the Fileshare Server (and when the log file was being written).

The Action code is the operation code that is being performed.

The name of the file is included in the message.

This error indicates one of the following:

  • The files to which the recovery log file is being applied are not the ones that were in use at the time that the Fileshare Server was started and the log file was created
  • The recovery log file or the files being rolled forward are corrupt
  • A situation has arisen which did not occur when the rollforward recovery file was created during normal Fileshare Server operation

Resolution:

Note the expected and returned error codes and take appropriate action. Also ensure that the correct version of the data files are in place and try to re-run the rollforward recovery.

Parent topic: Messages from FS051-W to FS099-W


Messages from FS101-I to FS149-I

  • FS101-I text -- parameter has been accepted.
    The indicated parameter (and value if required) has been accepted by the Fileshare Server
  • FS103-I The log filename has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a recovery log filename to the database reference file and the operation has completed successfully. The database reference file now contains the name of the recovery log file specified.
  • FS104-I The log file cannot be found, creating a new recovery log file.
    The Fileshare Server on starting up has processed the database reference file and determined the name of the rollforward recovery log file to use. The recovery log file does not exist and so the Fileshare Server has created a new one.
  • FS105-W The disk free space for the log file is below acceptable limits.
    The Fileshare Server has detected that the amount of disk space remaining on the drive where the recovery log file is being written is below a certain level.
  • FS106-I filename - added to database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully added the filename indicated to the database reference file.
  • FS107-I filename - removed from the database reference file.
    This message indicates that the Database Reference File Maintenance Utility has successfully removed the filename indicated from the database reference file.
  • FS108-I Processing the files specified in the database reference file.
    This message indicates that the Fileshare Server has opened the database reference file and is now scanning through it, processing each filename listed. The type of processing that it performs depends on the utility being used:
  • FS109-W The file filename does not exist.
    You see this message when the filenames listed in the database reference file are being processed and indicates that the file indicated cannot be located physically on disk.
  • FS110-I filename - OK.
    The Fileshare system has successfully processed the entry indicated in the database reference file and the file has been physically located on disk.
  • FS111-W Files are still open. Continue to close down the Fileshare Server (Y/N) ?
    You have selected to close down the Fileshare Server using the Esc key sequence. This message indicates that Fileshare Clients are still connected to this Fileshare Server with files open, or at least one Fileshare Client application program has terminated abnormally leaving one or more files open. You are asked to confirm that you do want to shut down the Fileshare Server even though there are files open.
  • FS114-W Waiting for the old log file to be removed.
    The drive where the rollforward recovery log file is being written has become full and the Fileshare Server is no longer able to continue writing to the rollforward recovery log file. The Fileshare Server is waiting for the old log file to be backed up and then deleted so that it can continue writing to the directory where the log file resides.
  • FS118-I The database sequence number matches the sequence number in the log file, no recovery is needed.
    For files formats with file headers (all index files and variable length record relative and sequential files), the Fileshare Server stores a sequence number in the header. This sequence number is also placed in the recovery log file. The sequence numbers can be checked by the Fileshare Server in certain situations to ensure that the correct files are in use.
  • FS122-I Communications too busy on CCI SEND - retrying.
    The Fileshare Server tried to send a reply back to the Fileshare Client performing an I/O request. CCI returned a Too Busy error (error 10) to the Fileshare Server.
  • FS123-I Communications too busy on CCI RECEIVE - retrying.
    The Fileshare Server tried to receive information from the network but CCI returned a Too Busy error (error 10) to the Fileshare Server
  • FS124-I Checking the validity of the log file, please wait.
    You see this message when the Rollforward Recovery Utility has been invoked and it has not found a valid record as the last record in the recovery log file. The Rollforward Recovery Utility scans through the log file to find the last sequence number that was in use to validate the integrity of the recovery log file.
  • FS125-I Recovery possible to last valid recovery log file record.
    You see this message when the Rollforward Recovery Utility has been invoked. This message indicates that the recovery log file has been validated up to the point of the last complete record in the recovery log file. It is therefore possible to apply the updates stored in the recovery log file up to this point.
  • FS126-I Performing recovery, please wait.
    The Rollforward Recovery Utility has been invoked and has initialized successfully, processed the database reference file, checked the sequence numbers in the file listed in the database reference file and validated the recovery log file.
  • FS127-S Invalid name mapping command.
    You see this message when the Fileshare Server or Rollforward Recovery Utility is processing the command line or entries in the database reference file. An /fs (file string replacement) option has been specified without a corresponding /af option specifying the new string value. The /fs option must be used in conjunction with the /af option.
  • FS128-W Fileshare Server closedown invoked by Stop Run processing.
    This message indicates that the Fileshare Server has entered its termination routine not under the control of an administrator (that is, the Esc key sequence or FSView or FSMgr are not being used to shut down the Fileshare Server).
  • FS129-I The Fileshare Server is still active.
    The response to the prompt as to whether the Fileshare Server should be closed down (see messages FS097 and FS111) indicated that the Fileshare Server should not be shut down.
  • FS130-I Reading database reference file, please wait.
    The Fileshare Server, Database File Maintenance Utility or the Rollforward Recovery Utility is reading the information stored in the database reference file. The utility will try to open the database reference file and process the information held in it.
  • FS131-W Invalid communications mode - parameter ignored.
    You see this message when the Fileshare Server is processing a /cm (communications) option. The value specified for this parameter is not valid and the parameter has been ignored. See the chapters Communications and Configuration for details of valid communications modes.
  • FS132-I The Fileshare Server is running with the following communication protocol(s):
    This message gives a list of the communication protocols that the Fileshare Server is using, after it has performed all of its initialization processing.
  • FS133-I Processing the password file, please wait.
    You see this message displayed by the Fileshare Server when it is starting or by the Password File Maintenance Utility when the password file is being updated.
  • FS134-I The password file cannot be found - creating a new password file.
    The Password File Maintenance Utility displays this message when it cannot locate the password file specified with the /pf option.
  • FS135-I Fileshare Server security is active.
    Fileshare Server security is active and all Fileshare Client applications that try to access this Fileshare Server should supply a valid user-ID and password that are in the password file. If you do not provide a valid user-ID or password, access will be denied and a 9/037 error returned to the application.
  • FS136-I Fileshare Server security is not active.
    A password file has been specified, however the only user-ID specified in the file is the FSVIEW (supervisor) id. Because this is the only ID, Fileshare Server security is not active and Fileshare Client applications that try to access the Fileshare Server do not have to supply a valid user-ID or password.
  • FS138-W The log file has been backed up and a new one has been created.
    You see this message when the Fileshare Server is starting up and a recovery log file already exists. The Fileshare Server has determined that it is unable to append to the recovery log file because the last record in the log file indicates that it was not shut in a controlled manner.
  • FS139-I A matching date and time entry has been found in the log file.
    The Rollforward Recovery Utility displays this message when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and has applied the updates up to the date and time specified. This message implies that there were additional records stored in the recovery log file which were not processed as they were written after the time specified.
  • FS140-I No matching date and time entry has been found in the log file.
    You see this message displayed by the Rollforward Recovery Utility when the /dt option has been used to recover updates to a certain point in time. The Rollforward Recovery Utility has performed the recovery using the recovery log file and reached the end of the log file before a record could be found that was written at the date and time specified. This implies that the date and time specified when performing the recovery is later than the date and time that the last record was written to the recovery log file. All the updates stored in the recovery log file have been applied to the data files.
  • FS142-W The Operating System does not permit the log file to be flushed to disk.
    You see this message when the Fileshare Server is using a recovery log file to store updates made to files. At certain points during its operation the Fileshare Server makes a call to the operating system to force it to flush the contents of the recovery log file to disk. This ensures that any data that has been written to the recovery log file is physically stored on disk and can be read in again after a system failure. The Fileshare Server performs this flush operation after every COMMIT operation is performed and at regular intervals (the default being after every 100 records have been written to the recovery log file, which can be changed using a /lc entry in the database reference file).
  • FS143-W The Operating System does not allow free disk space information to be obtained.
    When writing a recovery log file, it is important that there is enough disk space available. Consequently, the Fileshare Server makes periodic checks to see whether sufficient disk space remains.
  • FS144-W More than one communications protocol has been specified - synchronous communications mode not active.
    You have tried to start the Fileshare Server using the synchronous communications mode (as opposed to the asynchronous communications mode which is the default) using the /sc option.
  • FS145-W Fileshare Client disconnected, cannot contact user: text.
    The CCI has returned an error to the Fileshare Server indicating that a Fileshare Client has been disconnected. This message indicates that there may be a problem with the network or that the Fileshare Client application program is no longer functioning.
  • FS146-W Unexpected action code, action-code - discarded.
    You see this message when performing a rollforward recovery. The Rollforward Recovery Utility has read a record from the recovery log file which contains information not relating to any file currently being recovered. The information in the record cannot be processed and the Rollforward Recovery Utility has moved onto the next record in the recovery log file.
  • FS147-I A duplicate network message was received and discarded.
    This message only occurs when you are using the CCIIPX protocol and indicates that you are using an old version of the CCIIPX modules. The buffer sent between the Fileshare Client and Fileshare Server for each I/O request contains additional information which enables the Fileshare Server to check on the validity of the request. This message indicates that the Fileshare Server has received (in error) a duplicate of the previous buffer received from the communications system. This duplicate buffer has been discarded as it is not a valid I/O request.
  • FS148-I CCI return-code (function func) = code.
    You see this message when the Fileshare Server receives an unexpected error status from a CCI module. It is normally displayed in conjunction with a Fileshare Server message indicating the circumstances in which the error occurred.
  • FS149-I CCI SEND not complete, status will be checked later.
    A request sent back to a client application from the Fileshare Server has not completed within the expected time period. This message indicates that the Fileshare Server will continue processing requests from other client applications normally and will check the status of this request at a later time.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS151-I to FS200-W
Messages from FS201 to FS300
Messages from FS301 - FS400


FS101-I text -- parameter has been accepted.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS103-I The log filename has been added to the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS104-I The log file cannot be found, creating a new recovery log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS105-W The disk free space for the log file is below acceptable limits.

The amount of disk space remaining is calculated as a percentage of the total size of the disk where the log file is being written. The default is for this warning to be displayed when less than 5 percent of the total disk space remains free. This percentage can be changed using the /p option when entering the log filename into the database reference file using the Database Reference File Maintenance Utility.

Note:

If disk space is not cleared, the drive where the recovery log file is located will become so full as to make rollforward recovery logging impossible.

Resolution:

Clear disk space on the drive where the recovery log file is being written so that the Fileshare Server can continue logging the updates being performed.

Alternatively, if the amount of free disk space is becoming very low, the Fileshare Server should be shut down and the recovery log file backed up and deleted before starting the Fileshare Server again.

Parent topic: Messages from FS101-I to FS149-I


FS106-I filename - added to database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS107-I filename - removed from the database reference file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS108-I Processing the files specified in the database reference file.

  • The Database Reference File Maintenance Utility searches through the list of files to check the integrity of each one and also determine the current sequence numbers that are in use (if any)
  • The Fileshare Server scans the names in the database reference file in order to determine the processing to be done on each file
  • The Rollforward Recovery Utility searches through the list of files to check the integrity of each file and the sequence number in the header of each one

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS109-W The file filename does not exist.

Resolution:

If the file should exist, ensure that the filename and the path specified are correct and that the Fileshare Server is able to open the file with read-write access. Also ensure that the file is not open by another process as the Fileshare system requires exclusive access to the file.

If the file should not exist (for example, it is expected that it will be created by an application program), then this warning can be ignored.

Parent topic: Messages from FS101-I to FS149-I


FS110-I filename - OK.

Resolution:

No action is required as this message is informational.

Parent topic: Messages from FS101-I to FS149-I


FS111-W Files are still open. Continue to close down the Fileshare Server (Y/N) ?

Resolution:

At the prompt enter Y or N depending on whether the Fileshare Server is to be closed down or not.

Parent topic: Messages from FS101-I to FS149-I


FS114-W Waiting for the old log file to be removed.

Resolution:

The current log file should be backed up. The log file should then be moved so that the Fileshare Server can continue writing to the directory. If a rollforward recovery is necessary, the log files should be provided in the order that they were created to the Rollforward Recovery Utility. The Rollforward Recovery Utility will prompt for the continuation log files as they are required, if they cannot be located automatically.

Parent topic: Messages from FS101-I to FS149-I


FS118-I The database sequence number matches the sequence number in the log file, no recovery is needed.

You see this message when the Rollforward Recovery Utility has been invoked to perform a rollforward recovery. The Rollforward Recovery Utility has read the sequence numbers from the header of the files and also the last one that was written to the recovery log file. The sequence number in the headers and in the log file are the same indicating that the last updates written to the recovery log file have been applied to the files. It is therefore not necessary to perform a rollforward recovery as there are no updates in the recovery log file that have not already been applied to the files.

It is not necessary to perform the rollforward recovery.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS122-I Communications too busy on CCI SEND - retrying.

The Fileshare Server will retry the operation until the CCI protocol has been able to complete the operation.

This message could indicate that the network or network software is reaching a limit or is very busy.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS123-I Communications too busy on CCI RECEIVE - retrying.

The Fileshare Server will retry the request until valid data is returned from CCI

This message could indicate that the network or network software is reaching a limit or is very busy

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS124-I Checking the validity of the log file, please wait.

The fact that the log file does not contain a valid last record indicates that the recovery log file was not closed in a controlled manner and that the Fileshare Server which was writing to the recovery log file terminated abnormally.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more information.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS125-I Recovery possible to last valid recovery log file record.

The Rollforward Recovery Utility will apply the updates up to the point of the last valid record stored in the recovery log file.

See the sections Rollforward Recovery Logging and Rollforward Recovery Utility in the chapter Database Integrity for more information.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging
Rollforward Recovery Utility


FS126-I Performing recovery, please wait.

The Rollforward Recovery Utility will now start the recovery process. The time required to perform the recovery depends on the number of updates that are logged in the recovery log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS127-S Invalid name mapping command.

See the section Filename Mapping in the chapter Advanced Operation and the section Database Reference File Maintenance in the chapter Database Integrity for more information on the /fs option.

Resolution:

If the option has been specified on the command line, include the /af option to specify the name of the replacement string value and retry the operation.

If the option is specified in a database reference file, this error indicates that the database reference file has become corrupt or has been changed without using the Database Reference File Maintenance Utility.

In this situation, it may be possible to remove the invalid entry using a normal text editor. If this is unsuccessful, discard the current database reference file and create a new one using the Database Reference File Maintenance Utility.

Parent topic: Messages from FS101-I to FS149-I
Related information
Filename Mapping
Database Reference File Maintenance


FS128-W Fileshare Server closedown invoked by Stop Run processing.

This message should not be displayed under normal circumstances. Possible causes for this error are:

  • Closing the Fileshare Session on Windows or a kill command on UNIX. Such methods of closing the Fileshare Server should not be used as it can lead to files being corrupted and the recovery log file not being written to disk correctly.
  • The Fileshare Server has encountered an internal processing error which has caused the closedown code in the run-time system to be invoked. In this situation you should contact our technical support department to try and ascertain the cause of this error.

The Fileshare Server terminates by closing all files, rolling back any outstanding transactions, clearing all communication links with Fileshare Clients and closing the recovery log file (if in use).

Resolution:

You should try to ascertain why the Fileshare Server closed in this manner.

Parent topic: Messages from FS101-I to FS149-I


FS129-I The Fileshare Server is still active.

This message indicates that the Fileshare Server is continuing to function as normal.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
FS097
FS111


FS130-I Reading database reference file, please wait.

The amount of time required to process the database reference file depends on the amount of information contained in the file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS131-W Invalid communications mode - parameter ignored.

Resolution:

Ensure that the value specified for the communications parameter is valid.

If you do not wish to specify a communications protocol you should not use the /cm option. The Fileshare Server uses the default communications protocol for the operating system on which it is running.

Parent topic: Messages from FS101-I to FS149-I
Related information
Communications


FS132-I The Fileshare Server is running with the following communication protocol(s):

The Fileshare Client application programs can use any of the protocols listed to contact this Fileshare Server.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS133-I Processing the password file, please wait.

The password file has been successfully located and opened and is now being processed.

The time required for this operation depends on the amount of information that is stored in the password file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS134-I The password file cannot be found - creating a new password file.

The Password File Maintenance Utility will therefore try to create a new password file of the name specified.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS135-I Fileshare Server security is active.

See the chapter Security for more details about the Fileshare Server security features and how to use them.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Security


FS136-I Fileshare Server security is not active.

Logons are validated by the Fileshare Server by calling the FSSECLOG module.

See the chapter Security for more details about the Fileshare Server security features and how to use them.

See the section Password File Maintenance in the chapter Security for more information about supervisor passwords.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
Security
Password File Maintenance


FS138-W The log file has been backed up and a new one has been created.

This implies that the Fileshare Server which was previously writing to this log file terminated abnormally.

Because the Fileshare Server is unable to append to the existing log file, it has been renamed and a new recovery log file has been created. This new recovery log file will be used.

Note:

This message implies that the correct sequence of regularly backing up data files and deleting recovery log files is not being performed as the Fileshare Server is being started when a recovery log file already exists.

See the section Rollforward Recovery Logging in the chapter Database Integrity for more details.

Resolution:

No action is required

Parent topic: Messages from FS101-I to FS149-I
Related information
Rollforward Recovery Logging


FS139-I A matching date and time entry has been found in the log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS140-I No matching date and time entry has been found in the log file.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I


FS142-W The Operating System does not permit the log file to be flushed to disk.

This message indicates that an error was returned from the operating system when it tried to flush the recovery log file to disk. This implies that the operating system does not enable application programs to force I/O buffers to be flushed to disk. Consequently, the Fileshare Server is unable to force the operating system to write the contents of the recovery log file to disk and in the event of a system failure, it is possible that not all of the contents of the recovery log file will be available when the recovery process is performed.

Resolution:

See the section Database Reference File Maintenance in the chapter Database Integrity and Rollforward Recovery for more details.

Parent topic: Messages from FS101-I to FS149-I
Related information
Database Reference File Maintenance


FS143-W The Operating System does not allow free disk space information to be obtained.

This message indicates that the call to the operating system to determine how much disk space is available has returned an error. This implies that the operating system does not enable applications to determine how much disk space is available.

Resolution:

It is the system administrator's responsibility to ensure that sufficient disk space is available, as the Fileshare Server is unable to determine the amount of free space available on the drive. If the Fileshare Server is unable to write a recovery log file because there is insufficient disk space, the Fileshare Server automatically closes down.

Parent topic: Messages from FS101-I to FS149-I


FS144-W More than one communications protocol has been specified - synchronous communications mode not active.

With this mode of communication it is only possible to start the Fileshare Server with one communications protocol.

This message indicates that the Fileshare Server is configured to use more than one communications protocol and so the synchronous communications option has been ignored.

The Fileshare Server has started, but it is not using the synchronous communications mode.

Resolution:

If the synchronous communications mode is required, make sure that the Fileshare Server is configured to use only one communications protocol.

Parent topic: Messages from FS101-I to FS149-I


FS145-W Fileshare Client disconnected, cannot contact user: text.

You see the user number and user name, if one was supplied at the time that this user logged onto the Fileshare Server.

The Fileshare Server has closed all files that this user had open and rolled back any outstanding transactions pending for this user.

The Fileshare Client application, if still active, will be returned a 9/124 error on its next I/O operation.

Resolution:

Check that the Fileshare Client application is still running. Also check for any adverse network conditions that could have forced the connection to have been dropped.

Parent topic: Messages from FS101-I to FS149-I


FS146-W Unexpected action code, action-code - discarded.

This message can indicate that the recovery log file has become corrupted in some way or that the recovery file contains invalid information.

Resolution:

As the rollforward recovery log file contains an invalid record, it is possible that not all of the record updates have been recovered from the file. After the recovery has completed the data in the files should be checked. If the problem recurs contact our technical support department.

Parent topic: Messages from FS101-I to FS149-I


FS147-I A duplicate network message was received and discarded.

Resolution:

Ensure that the latest CCIIPX modules are installed on the Fileshare Client and Fileshare Server machines.

Parent topic: Messages from FS101-I to FS149-I


FS148-I CCI return-code (function func) = code.

The message consists of a function code which indicates which CCI verb was being used at the time of the error and the return-code received from the CCI module.

The Fileshare Server calls CCI to determine details of the error that has occurred. This information is also displayed on the screen.

Resolution:

No action is required. However, the above information should indicate the cause of an error or unexpected occurrence during the Fileshare Server operation. This information should be used with any additional information contained in other messages to determine the cause of any errors.

When contacting our technical support department the above information is important and must be included with any problem report.

Parent topic: Messages from FS101-I to FS149-I


FS149-I CCI SEND not complete, status will be checked later.

Message FS228 is displayed when it is determined that the request eventually either completed or failed.

If you see this message frequently, it may be due to large record sizes taking longer to process than expected on slower network connections.

Resolution:

No action is required.

Parent topic: Messages from FS101-I to FS149-I
Related information
FS228


Messages from FS151-I to FS200-W

  • FS151-I CCI message size received = text. Indicated send message size = text
    You see this message in conjunction with message FS014.
  • FS153-I The Fileshare Server name has been reregistered on the network.
    The Fileshare Server tried to register its name on the network so that Fileshare Clients can contact it. An error status was returned indicating that the Fileshare Server name was already registered on the network by a Fileshare Server which terminated abnormally. As this name is not being used by an active Fileshare Server, the name has been reregistered on the network by the Fileshare Server being started.
  • FS154-I Please enter the FSVIEW supervisor password to enable the use of CCI Trace.
    The Fileshare Server is being started and is configured to use the CCI Trace option. This option can only be used by a supervisor because it can cause a large amount of disk space to be used for storing the CCI Trace file. When starting the Fileshare Server a password file should be specified that contains a user-ID of FSVIEW.
  • FS155-I Password accepted - CCI Trace is enabled. Do you want CCI Trace active immediately? (Y/N)
    You see this message displayed after the supervisor has entered the supervisor password to enable the use of CCI Trace. The Fileshare Server has confirmed that the password entered is correct and it is now possible to use CCI Trace.
  • FS156-W Incorrect password - CCI Trace is disabled.
    You see this message after the FSVIEW supervisor has entered the supervisor password to enable the use of CCI Trace.
  • FS158-I CCI Trace activated.
    This message indicates that the Fileshare Server has enabled the CCI Trace option and all requests made to CCI are being logged in the CCI Trace file.
  • FS159-I CCI Trace switched off.
    This message indicates that the Fileshare Server has turned off the CCI Trace option and all requests made to CCI are no longer being logged in the CCI Trace file. You see this message when the CCI Trace is either:
  • FS160-I Fileshare trace activated.
    You see this message displayed by the Fileshare Server when the trace option has been activated using the F2 key. All requests received by the Fileshare Server will be shown, with the operation code being requested, the name of the user performing the request and some additional information depending on the operation being performed. The result of the operation (including the file status) that is returned to the Fileshare Client is also shown.
  • FS161-I Fileshare trace switched off.
    You see this message displayed by the Fileshare Server when the trace option has been toggled off using the F2 key. The Fileshare Server no longer displays requests received or information about the data being returned to the Fileshare Clients. The Fileshare Server also is no longer writing to the trace file fsscreen.lst if the trace file option was specified when the Fileshare Server was started.
  • FS163-I Input useropcode [filename-1] [ filename-2].
    You see this message when the Fileshare Server trace option is activated and a request has been received by the Fileshare Server. The information displayed is as follows:
  • FS170-I Input- Logon.
    You see this message when the Fileshare Server trace option is activated and a logon request has been received by the Fileshare Server. The Fileshare Server will process the logon request and the result of the request will also be displayed. A logon request is always the first operation performed by a new Fileshare Client connecting to this Fileshare Server.
  • FS171-I Input- Logoff user.
    You see this message when the Fileshare Server trace option is activated and a log off request has been received by the Fileshare Server. If the Fileshare Client supplied a user name when it logged onto this Fileshare Server, the user name is displayed here if Fileshare Security is active. If no user name was supplied, then the user number is displayed.
  • FS172-I Input- Find File userfilename.
    You see this message when the trace option is activated and a Find File request has been received by the Fileshare Server from a Fileshare Client when a program tries to open a file. The Fileshare Server that should process the file has not been explicitly defined and more than one default Fileshare Server is configured.
  • FS173-I Output- userstatus.
    You see this message when the Fileshare Server trace option is activated and a request has been processed by the Fileshare Server and the result sent back to the Fileshare Client
  • FS176-W There is no backup directory specified in the database reference file.
    You tried to erase a backup directory entry from the database reference file but the database reference file does not contain a backup directory entry
  • FS177-S The backup directory specified cannot be found in the database reference file.
    You tried unsuccessfully to erase a backup directory-name from the database reference file. This is because the backup directory-name specified is not the same as the backup directory-name in the database reference file.
  • FS178-I The backup directory has been added to the database reference file.
    The Database Reference File Maintenance Utility has been invoked to add a backup directory-name to the database reference file and the operation has completed successfully. The database reference file now contains the name of the backup directory specified.
  • FS179-S A backup directory is already specified in the database reference file.
    You tried to add the name of the backup directory to the database reference file. However such an entry already exists in the database reference file which can only contain one recovery log file backup directory-name.
  • FS180-W The log filename specified has an extension. The name of the log file has been changed to "filename".
    The Database Reference File Maintenance Utility has been invoked to add the name of the recovery log file to the database reference file. The name of the log file specified contained an extension and this has been removed. The extension is removed to enable the Fileshare Server to automatically backup the recovery log file when necessary. The name of the log file added to the database reference file is shown.
  • FS182-W Output- Access Denied
    You see this message when the Fileshare Server trace option is activated and a logon request was received by the Fileshare Server from the Fileshare Client. This logon request has been denied, either because:
  • FS188-W Fileshare Server database reference file installation completed with errors.
    The Database Reference File Maintenance Utility has been used to update the contents of the database reference file. However, an error was found when parsing the command line passed to the utility or when processing the information stored in the database reference file.
  • FS189-W The backup directory does not exist.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS190-W The backup directory specifies the name of an existing file.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS191-W An error occurred accessing the backup directory.
    The Database Reference File Maintenance Utility has been invoked to add the name of a backup directory to the database reference file.
  • FS192-S More than one log file exists in the log file directory.
    You see this message when the Fileshare Server is starting up. The Fileshare Server has searched the directory where the recovery log file is to be written and has determined that more than one recovery log file exists in the directory. The Fileshare Server is unable to determine which of these recovery log files is a valid one and hence which one it can append data to.
  • FS193-S Unable to open the log file.
    The Fileshare Server has determined that a recovery log file exists in the directory where the recovery log file is specified but an error was returned when the Fileshare Server tried to open it.
  • FS194-I The log file "filename-1" has been backed up successfully to "filename-2".
    This message indicates that the Fileshare Server has successfully backed up the recovery log file. The backup operation was performed either as a request from FSVIEW or FSMGR or because the current recovery log file cannot be appended to and has been automatically backed up when the Fileshare Server has started. filename-1 is the name of the log file that has been backed up. filename-2 is the name of the file that the log file has been backed up to.
  • FS195-I The Fileshare Server is using the log file "filename".
    The Fileshare Server has successfully opened (and created if necessary) the recovery log file indicated and is writing recovery records to this log file.
  • FS196-W Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS197-S Unable to create the log file "filename".
    The Fileshare Server tried to create the recovery log file indicated, but was unable to do so.
  • FS198-W The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS199-S The attempt to backup the log file failed because the backup file "filename" already exists.
    The Fileshare Server was unable to backup the recovery log file to the directory and name specified because a file of that name already exists.
  • FS200-W The attempt to backup the log file to "filename" failed.
    The Fileshare Server tried to copy the recovery log file to the directory and name specified but encountered an error when doing so. Possible causes are that the directory is full or that a disk I/O error occurred during the copying process.
Parent topic: Fileshare Server Messages
Related information
Messages from FS001-S to FS050-W
Messages from FS051-W to FS099-W
Messages from FS101-I to FS149-I
Messages from FS201 to FS300
Messages from FS301 - FS400


FS151-I CCI message size received = text. Indicated send message size = text

The information sent from the Fileshare Client to the Fileshare Server includes a check on the amount of information that is being sent. This error states that the amount of data received by the Fileshare Server is not the same as the amount sent by the Fileshare Client.

This message shows the amount of data that has been received by the Fileshare Server and also the amount of data that was sent by the Fileshare Client.

The Fileshare Server has ignored the data sent from the Fileshare Client.

Resolution:

If using the NETBIOS protocol, ensure that it is installed correctly, configured and operational.

It is highly likely that the Fileshare Client appears to have stopped because the Fileshare Server has not sent any reply back. Depending on the CCI protocol being used, a time-out occurs in approximately two minutes and a 9/124 status is returned to the application program.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS014-W


FS153-I The Fileshare Server name has been reregistered on the network.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS154-I Please enter the FSVIEW supervisor password to enable the use of CCI Trace.

See the section Password File Maintenance in the chapter Security for more information.

See also the messages FS155 and FS156.

Resolution:

At this prompt enter the supervisor password that corresponds to the entry in the password file for the user-ID of FSVIEW

Parent topic: Messages from FS151-I to FS200-W
Related information
Password File Maintenance
FS155
FS156


FS155-I Password accepted - CCI Trace is enabled. Do you want CCI Trace active immediately? (Y/N)

This prompt is to determine if the Fileshare Server is to trace communication requests immediately and include all of the CCI initialization requests made by the Fileshare Server.

Resolution:

Responding Y enables the Fileshare Server to start using CCI Trace immediately and causes all CCI initialization requests to be traced to the CCI Trace file. The CCI Trace remains operational until toggled off using the F3 key.

Entering any other response apart from Y does not enable CCI trace immediately. However, CCI trace can be toggled on at a later time using the F3 key.

See also the messages FS154 and FS156.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS154
FS156


FS156-W Incorrect password - CCI Trace is disabled.

The Fileshare Server has determined that the password entered is incorrect and has consequently disabled the use of the CCI Trace feature.

Resolution:

If CCI Trace is required then the Fileshare Server should be brought down using the Esc key sequence. Ensure that when starting the Fileshare Server the /pf option is used to specify a password file that contains a password for the user-ID FSVIEW. When prompted to enter the supervisor password the password for the FSVIEW user-ID should be entered.

If CCI Trace is not required then no action is required as the Fileshare Server has started and the CCI Trace feature is not enabled. However, to prevent this message in future, the Fileshare Server should be reconfigured not to use CCI Trace.

Parent topic: Messages from FS151-I to FS200-W


FS158-I CCI Trace activated.

You see this message when either CCI Trace is made active on start-up, or is toggled on using the F3 key while the Fileshare Server is operational.

Note:

The CCI Trace file can become very large. If no disk space remains to enable the CCI Trace file to be written, no errors are reported and the tracing of CCI requests is suspended.

Resolution:

No action is required

Parent topic: Messages from FS151-I to FS200-W


FS159-I CCI Trace switched off.

  • Not made active immediately on the Fileshare Server starting up (see the message FS155)

    or

  • Toggled off using the F3 key while the Fileshare Server is operational

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS155


FS160-I Fileshare trace activated.

If the trace to a file option was specified when the Fileshare Server was started then the information displayed on the screen is also written to a file called fsscreen.lst.

The trace option can be toggled off using the F2 key.

See also message FS161.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS161


FS161-I Fileshare trace switched off.

The trace option can be toggled on using the F2 key.

See also message FS160.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W
Related information
FS160


FS163-I Input useropcode [filename-1] [ filename-2].

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server then the user name is displayed here if Fileshare Security is active. If no user name was supplied, the user number is displayed. The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2, etc.
opcode | This is an indication of the type of action requested by the Fileshare Client. Most normal operations appear as an action-code. If a byte stream operation is being performed, the name of the operation is displayed. For COMMIT operations, an indication is given if the COMMIT is part of a prepare, confirm or abort stage of the transaction processing (if the transaction spans more than one Fileshare Server).
filename-1 | If the operation being performed is specific to a file then the name of the file is displayed here
filename-2 | If the operation being performed is specific to a file and requests to the file are being mapped to a different file using the alternate filename mapping option, the actual name of the file being processed is displayed here

The information displayed will also be written to a file called fsscreen.lst if the trace file option was specified when the Fileshare Server was started.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS170-I Input- Logon.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS171-I Input- Logoff user.

The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.

A logoff request is the last operation performed by a Fileshare Client when the Fileshare Client application program terminates.

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS172-I Input- Find File userfilename.

The Fileshare Client is in the process of polling each default Fileshare Server to determine if that Fileshare Server should process requests for this file.

The information displayed is as follows:

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server, the user name is displayed here if Fileshare Server security is active. If no user name was supplied, then the user number is displayed. The user number is generated when the Fileshare Client logs on to this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.
filename | The name of the file that the Fileshare Client is trying to open

Resolution:

No action is required.

Parent topic: Messages from FS151-I to FS200-W


FS173-I Output- userstatus.

The information displayed is as follows:

user | If the Fileshare Client supplied a user name when it logged onto this Fileshare Server then the user name is displayed here. If no user name was supplied, the user number is displayed. The user number is generated when the Fileshare Client logs onto this Fileshare Server. The first Fileshare Client has user-ID 1, the second user-ID 2.
status | The error status generated from the result of the requested operation. For normal file I/O operations this is the same format as standard file I/O statuses. Note that this status may not be the status that is returned to the application program. The Fileshare Client uses the status displayed here to do any status conversion necessary (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
  • Deploying a Java Service Interface and Using Resource Adapters
  • 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

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

For more information, see Tutorial: Interface Mapping Toolkit.

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.

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 Enterprise 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.
Debug experience | There are different debuggers for Java and COBOL in Eclipse. | It is possible to step between Java and COBOL in Eclipse. | There are different debuggers for Java and COBOL in Eclipse. It is not possible to debug both languages at the same time. You can debug Java independently of COBOL and COBOL independently of Java.
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, Enterprise Developer 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
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.

For Windows environments

Before you start writing COBOL and Java programs which interact, you need to set up the following environment variables for the COBOL and Java run-time systems:

  • PATH

    The jvm.dll file must be available. Do not move jvm.dll to a different location, because it has dependencies on other files shipped as part of the Java run-time system. The location of this file depends on which version of the JDK you are using. To ensure the file is available, add it to the system PATH. For example:

    set path=jdk-install-directory\bin\subdirectory;%path%

    Where subdirectory might be client, classic, hotspot or server.

    If you generate EJBs or Java beans using the Interface Mapping Toolkit, the Java Compiler must be available. To do this, put the bin directory of JDK on the PATH. For example:
    set path=jdk-install-directory\bin;%path%
  • CLASSPATH

    If you have Java programs that call COBOL, you need to provide access to the Java classes that interface to the COBOL run-time system. To do this, ensure that mfcobol.jar is specified by the CLASSPATH environment variable. For example:

    set classpath=install-directory\base\bin\mfcobol.jar;%classpath%;.;

    Alternatively, you can set the classpath when you run a Java program, using the -classpath switch. For example:

    java -classpath ".;install-directory\base\bin\mfcobol.jar;%classpath%" MyClass
    If you generate EJBs or Java beans using the Interface Mapping Toolkit, the tools.jar of the JDK must be on the CLASSPATH. For example:
    set classpath=jdk-install-directory\lib\tools.jar;%classpath%;.;
  • Shared library path

    The operating system's shared library path must include the directory containing libjava. This is often found in a subdirectory of Java's jre/lib directory, although the name of this directory is specific to each platform. On some platforms, you might need to specify more than one directory for this, for example, an additional directory containing the Java native threading support.

For UNIX environments

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.

All platforms

If you are developing Java or JVM projects in Eclipse, you do not have to set the Java installation directory using the JAVA_HOME variable. Follow these steps to identify the JRE or JDK using the Properties dialog boxes:
  1. Select your project in the Navigator pane.
  2. On the Project menu, click Properties.

    The Properties for <project-name> dialog box appears.

  3. Select one of the following:
    • For a COBOL JVM project, click Micro Focus > JVM Build Path.
    • For a Java project, click Java Build Path.
  4. Click the Libraries tab.
  5. Select JRE System Library and click Edit.
  6. Select Alternate JRE, click Installed JREs, then select an installed JRE or JDK and click OK.
    Note: Click Add and use the Add JRE wizard to add a JRE or JDK that is not listed.
  7. Click Finish, then click OK.
Parent topic: Considerations
Related reference
Using the Java/COBOL Application Launcher from the Command Line


Java/COBOL Application Launcher

Restriction: This topic only applies to local and remote development on Linux and UNIX platforms.

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
  • Using the Java/COBOL Application Launcher from the Eclipse IDE
Parent topic: Considerations


Using the Java/COBOL Application Launcher from the Command Line

Restriction: This topic applies to UNIX environments (remote development) only.

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
  • In Eclipse, you set up a launch configuration and you specify cobjrun as the executable to run and specify that the multi-threaded run-time system is used
  • 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: Java/COBOL Application Launcher
Related concepts
Setting Up the Environment for Java and COBOL


Using the Java/COBOL Application Launcher from the Eclipse IDE

Restriction: This topic only applies to local and remote development on Linux and UNIX platforms.
  1. In the JDK bin directory, create a symbolic link to the cobjrun executable in the bin directory in the product installation directory. To do this, execute the following from the command line:
    ln -s $COBDIR/bin/cobjrun /usr/java/<jdk version>/bin/cobjrun

    Create symbolic links in a similar way for each JDK that you plan to use.

  2. Configure your Java project to use the RuntimeSystem class which is in the mfcobol.jar in $COBDIR/lib. To do this:
    1. Launch Eclipse and open your Java project.
    2. Select the project and click Project > Properties.
    3. Select Java Build Path.
    4. Click the Libraries tab.
    5. Click Add External JARs and select the mfcobol.jar in $COBDIR/lib.

      Click OK.

  3. Before running the Java program, in Eclipse, you need to change the launch configuration so that it uses cobjrun which loads the COBOL libraries for Java. To do this:
    1. Launch Eclipse and open your Java project.
    2. Click Run > Run Configurations.
    3. Select the Java Application configuration in use.
    4. Click the JRE tab and then click Alternate JRE.
    5. Select the JRE that you want to use.
    6. In the java executable section, click Alternate and then type cobjrun.
    7. In the Java launch configuration, set the COBMODE environment variable as follows:
      1. Click the Environment tab for the configuration in use.
      2. Click New and add the environment variable COBMODE with value:
        32
        if you are calling 32-bit COBOL applications
        64
        if you are calling 64-bit COBOL applications

    This ensures the Enterprise Server will be loaded before Java needs it.

  4. Additionally, when calling 64-bit COBOL applications, you need to add the 64-bit JDK libraries at the start of LD_LIBRARY_PATH as follows:
    1. Click the Environment tab for the configuration in use.
    2. Add the LD_LIBRARY_PATH variable with value:
      /usr/java/<jdk
version>/jre/lib/amd64/server/:${env_var:LD_LIBRARY_PATH}
    3. Ensure Append environment to native environment is checked.
  5. Click Apply.
  6. Click OK.
Parent topic: Java/COBOL Application Launcher


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:

UNIX:
ooctrl"+p-f"
Windows:
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.

In Eclipse, ensure that the multi-threaded run-time system is selected in your build configuration. Similarly, to debug or run the application within Eclipse, ensure that your launch configuration specifies that the multi-threaded run-time system is used.

Parent topic: Considerations


Deploying a Java Service Interface and Using Resource Adapters

You can expose procedural COBOL as EJBs or Java beans by using the Service Interfaces feature to map an interface onto your COBOL program.

The COBOL service interface then needs to be deployed as a service to an enterprise server. The COBOL service comprises the mapping information and the original COBOL. You can deploy the service interface automatically by deploying from your Eclipse project, or you can do it manually in one of the following ways:

  • You deploy the EJB to a Java Enterprise Edition (Java EE) application server and also deploy a resource adapter to handle the connection between the Java EE application server and the enterprise server.
  • You run the Java bean in a Java 2 Standard Edition (J2SE) environment. The bean accesses the enterprise server directly, without a resource adapter. This avoids using a Java EE application server, but you lose the management and transaction support that it provides.
  • You ignore the EJB or Java bean generated and write your own Java, which uses an unmanaged connection to call the resource adapter and send the request to an enterprise server.

At run time, your client application makes Java requests and invokes the generated EJB or Java bean. The EJB uses the resource adapter to pass the requests to an enterprise server, which in turn runs the exposed COBOL. The Java bean pass the requests to the enterprise server directly.

The mapping information is used at run time to pass data to and from the exposed COBOL. The enterprise server returns the response to the EJB through the resource adapter or directly to the Java bean. The EJB or bean passes the response on to the client.

Note: The JNDI name for the resource adapter, the resource adapter's reference name (also called its coded name) is CCIMFCobol_v1.0, which is the name of the connection factory. The JNDI name that you specify is eisMFCobol_v1.0. You must use the names stated here.
  • JSP Client
  • Deployment Descriptors that Are Generated
  • Manifest Files
  • CustomRecord and Other Java Support
  • Calling the Generated EJB or Java Bean
  • Using Java Beans under J2SE
  • Overview of Using an Unmanaged Connection under J2SE
Parent topic: Using COBOL and Java Together


Application Ear File

When you generate a client for an EJB, the EJB and the client are packaged together into an enterprise archive file myService.ear file together with the following files:

application.xml | Generic deployment descriptor, defining the .jar and the client .war files
myService.jar | EJB archive file
myService.war | Client archive file
manifest.mf | Manifest describing this .jar file
mfejlib.jar | Custom records
Parent topic: JSP Client


Client War File

When you generate a client for an EJB , it is packaged into a Web archive file myService.war file together with the following files:

*.jsp | JSP files. These pass data back and forth between the end user and the servlet.
myServiceJspBean.class | This file contains the getter and setter methods that are used to move information back and forth between the servlet and JSP.
myServiceServlet.class | This file is the servlet. It processes the incoming requests from the JSP, invokes an instance of the stateless EJB, and forwards the response back to the JSP.
myServiceSessionMonitor.class | This is a helper class, which stores the EJB instances for the stateful session bean.
manifest.mf | Manifest describing this .war file
mfejlib.jar | .. custom records
web.xml | Generic deployment descriptor, defining the client servlet and the EJB reference
*.xml, such as weblogic.xml | For some Java application servers (such as WebLogic), a deployment descriptor for deploying the .war file to that application server
Parent topic: JSP Client


EJB Jar File

When you generate an EJB, it is packaged into a Java archive file (myService.jar) together with the following files:
ejb-jar.xml | Generic deployment descriptor, defining the EJB
myServiceBean.class | Bean class for the EJB
myServiceHome.class | Home interface for the EJB
myService.class | Remote interface for the EJB
myRecord.class | custom record, if needed by the EJB
manifest.mf | Manifest describing this .jar file
*.xml, such as weblogic-ejb-jar.xml | For some Java application servers (such as WebLogic), a deployment descriptor for deploying the EJB to that application server

The source code for the EJB classes are generated in the directory com\mypackage\myService (Windows) or com/mypackage/myService (UNIX).

Parent topic: JSP Client


Deployment Descriptors that Are Generated

Deployment descriptors are xml files containing deployment information, such as the settings you specify in the Interface Mapping Toolkit. Java application servers require deployment descriptors for the archive files (.jar, .war and .ear) to be deployed. At run time, the Java application server reads the descriptors and acts accordingly. Deployment descriptors are not required for the generated Java beans.

When you generate an EJB or client, the following generic deployment descriptors are created and packaged into the relevant archive files:

  • application.xml, which defines and is packaged in the enterprise archive file (.ear)
  • ejb-jar.xml, which defines and is packaged in the EJB Java archive file (.jar) to be deployed.
  • web.xml, which defines and is packaged in the Web archive file (.war) to be deployed.

Some Java application servers require additional deployment descriptors in the archive files. These descriptors are generated automatically for the supported application servers.

If your application server requires additional deployment descriptors and these are not generated, you need to create them manually and add them to the archive files.

Parent topic: Deploying a Java Service Interface and Using Resource Adapters


Manifest Files

When you generate an EJB, a manifest file manifest.mf is included in each archive file that is generated. The manifest file specifies the information needed by the files in the archive. For example:

  • The manifest for myService.jar defines the classpath for mfejblib.jar, which provides the Micro Focus support for the CustomRecord and RuntimeProperties interfaces.
  • The manifest for myService.war defines the classpath for mfejblib.jar and for myService.jar.

Notice that the manifest file mandates that mfejblib.jar is in the root of the deployed archive file by specifying the classpath as follows:

Class-path: mfejblib.jar

You must ensure that the mfejblib.jar is in that location. Alternatively, if you require mfejblib.jar to be elsewhere, you can change the classpath accordingly.

Parent topic: Deploying a Java Service Interface and Using Resource Adapters


CustomRecord and Other Java Support

If your EJB or Java bean uses custom records you need to make sure that support for them is available. Custom records are created if you map COBOL group items onto Java data types. You map group items in the Interface Mapper whenever you set up Reusable Mappings for group items and you then make those group items into complex interface fields.

For Java beans, support for the CustomRecord and the RuntimeProperties interfaces is provided in mfj2se.jar, which is supplied in the ...\base\bin directory of your installation (Windows) or $COBDIR/lib (UNIX). This support must be available at run time, and you can ensure this by putting mfj2se.jar on the classpath. For example, you could run your application, with the command:.

java –classpath class-directory\/mfj2se.jar myProgram.class

For EJBs, support for the CustomRecord and the RuntimeProperties interfaces is provided in mfejblib.jar. This support is automatically included in the application .ear file when you generate a client for the EJB. When the Deploy tool creates the EJB, it adds a manifest file manifest.mf to the .jar file, and in that manifest file it sets the classpath to mfejblib.jar.

If you create a client manually, you need to add the mfejblib.jar to your .ear file, manually. There are two versions of the file: one for J2EE 1.3 and one for J2EE 1.4, and these are available in the base\bin\j2ee13 and base\bin\j2ee14 (Windows) or $COBDIR/lib/j2ee13 and $COBDIR/lib/j2ee14 (UNIX) directories. By default, the mfejblib.jar file belongs in the root of the .ear file, because the classpath to mfejblib.jar is set to the root in the manifest.mf file of the EJB's .jar file.

You can view this manifest file by extracting it from the EJB's archive file, myservice.jar, which is in myproject \Repos\.deploymyservice (Windows) or myproject /Repos/myservice.deploy (UNIX). Notice that the classpath is set as follows:

Class-path: mfejblib.jar

If you require mfejblib.jar to be elsewhere, you need to change the classpath in manifest.mf in the EJB's jar file accordingly.

Parent topic: Deploying a Java Service Interface and Using Resource Adapters


Calling the Generated EJB or Java Bean

You need to write some Java client software to call the generated EJB or Java bean and to pass it the parameters required for the COBOL service. This client software might be a JSP or a servlet or some other module.

The EJB or Java bean interface is defined in the Interface Mapping Toolkit. Typically, you find out the interface by importing the EJB or Java bean into a Java development tool and investigating the interface there. One point to note is with regard to output parameters. If the mapped interface passes multiple output parameters (rather than using a group item and its corresponding custom record), the output parameters are returned through a container object in the EJB or Java bean interface. You can see this in your Java development tool.

At run time, the Java client software calls the EJB or Java bean. The EJB passes the request to the resource adapter, which communicates with the enterprise server to execute the COBOL service. The Java bean communicates with the enterprise server directly.

Parent topic: Deploying a Java Service Interface and Using Resource Adapters


Using Java Beans under J2SE

You can bypass the Java application server and the resource adapter, by generating a Java bean that accesses the COBOL enterprise server directly. Although this avoids the overhead of administering a Java EE application server, you lose its advantages such as transaction support.

The Java bean generated is stateless. One class is generated for the bean and other classes are generated for any data classes representing the records that are mapped.

The Java bean runs in a J2SE environment with the libraries from the Java application server. The Java bean accesses the COBOL enterprise server directly, in an out-of-process manner. The J2SE and enterprise server run in two separate processes and they communicate through sockets.

You need to write your client software to call the Java bean.

Support for the Java bean is supplied in mfj2se.jar, which is available in the base\bin (Windows) or $COBDIR/lib (UNIX) directory.

To trace the behavior of the Java bean, use the –Dmfdebug=true switch. For example run the program myBean as follows:

java –Dmfdebug=true myBean
Parent topic: Deploying a Java Service Interface and Using Resource Adapters


Overview of Using an Unmanaged Connection under J2SE

  • Using an Unmanaged Connection under J2SE
    You can bypass the Java application server by writing your own code to call the resource adapter and send the request to an enterprise server.
  • Writing a Simple CCI Program
    The sample code in this section demonstrates Java code requesting a COBOL service.
Parent topic: Deploying a Java Service Interface and Using Resource Adapters


Using an Unmanaged Connection under J2SE

In this case, the connection is unmanaged. Your code runs in a J2SE environment with the libraries from the Java application server. Although this avoids the overhead of administering a Java application server, you lose its advantages such as transaction support.

To deploy an unmanaged connection, all you need to do is to update your classpath to include the classes that provide support for the Micro Focus resource adapters. These classes are packaged in mfcobolpure.jar and mfconnector.jar. There are two versions of these files: one for J2EE 1.3 and one for J2EE 1.4, and these are available in the base\bin\j2ee13 and base\bin\j2ee14 (Windows) or $COBDIR/lib/j2ee13 and $COBDIR/lib/j2ee14 (UNIX) directories.

The code you write needs to use CCI. The CCI defines an API for resource adapters connecting to Enterprise Information Servers (EISs), such as Enterprise Server. Micro Focus also supplies some extension classes specific to using the Micro Focus resource adapters.

In summary the code:

  1. Imports the Java and Micro Focus classes
  2. Gets a connection
  3. Gets an interaction
  4. Sets the InteractionSpecs for the interaction
  5. Executes the interaction
  6. Gets the results
  7. Closes the connection

The CCI classes and some of their methods include:

  • Managed ConnectionFactory - createConnectionFactory()
  • ConnectionFactory - get Connection(), getRecordFactory()
  • Connection -
          createInteraction(),
          getResultSetInfo(),
          close()
  • Interaction - getConnection(), execute(), getWarnings()
  • Record - getRecordName(), clone()
  • InteractionSpec - SYNC-SEND, SYNC_RECEIVE and so on

The Micro Focus extensions are supplied in the com.microfocus.cobol.connector.cci package and are documented in the J2EE 1.3 Connector Class Library Reference and J2EE 1.4 Connector Class Library Reference. The com.microfocus.cobol.connector.cci package provides classes such as:

  • CobolConnectionFactory - getConnection(), getRecordFactory()
  • CobolInteraction - execute(), getWarnings()
  • CobolInteractionSpec - getInteractionVerb(), setArgument()
  • CustomRecord -
          getRecordName(),
          clone(),
          hashCode()
  • IndexedRecord -
          lastIndexOf(),
          contains(),
          lastElement()
Parent topic: Overview of Using an Unmanaged Connection under J2SE


Writing a Simple CCI Program

The Java code uses CCI code to interact with a resource adapter which passes the request to the COBOL service. It demonstrates the use of a CCI custom record to represent a COBOL group item. In this sample, the Add service is mapped from the Calculate COBOL program through the entry point ADD using the reusable record Calculator.

  • Sample Program to Connect to a Resource Adapter
  • Sample Service
  • Sample Initialize Method
  • Sample Custom Record
  • Sample Calculator COBOL Program
Parent topic: Overview of Using an Unmanaged Connection under J2SE


Sample Program to Connect to a Resource Adapter

You need to map the COBOL program onto a Java interface using the Interface Mapper. You drag the Calculator parameter into the Reusable Mappings pane and then drag it up into the Interface Fields pane for the Add operation. You can do the same for the subtract, divide and multiply operations. You need to map the interface this way, in this example, because the sample unmanaged class is demonstrating the use of a CCI custom record.

The sample program uses classes from these Java packages:

javax.resource.cci | A collection of CCI interfaces defined in the J2EE Connector Architecture specification
com.microfocus.cobol.connector.spi | Classes specific to the Micro Focus resource adapters that implement the Service Provider Interface (SPI) interfaces
com.microfocus.cobol.connector.cci | Classes specific to the Micro Focus resource adapters that implement the CCI interfaces

To use the classes from these packages, we recommend that you import them into your code. For example, use statements such as:

import com.microfocus.cobol.connector.spi.*;
import com.microfocus.cobol.connector.cci.*;
import javax.resource.cci.*;
Parent topic: Writing a Simple CCI Program


Sample Service

Here is code for the sample service followed by an explanation of the significant lines of code.

1      try {
2       // Get a Connection Factory instance
3       mcf = new CobolNoTxManagedConnectionFactory();
4       // set the appropriate fields.
5       mcf.setServerHost("localhost");
6       mcf.setServerPort("9003");

7       // Get a connection Factory (without using JNDI)
8       cxf = (javax.resource.cci.ConnectionFactory)
               mcf.createConnectionFactory();

9       // Get a Cobol Connection Handle
10      connection = cxf.getConnection();
11      initialize(connection, cxf, true);

12      // Set up an interaction
13      interaction = connection.createInteraction();

14      // create a new interaction spec
15      CobolInteractionSpec iSpec =
             new CobolInteractionSpec();
16      iSpec.setFunctionName("myservice.add");

17      javax.resource.cci.RecordFactory rf =
             cxf.getRecordFactory();
18      Calculator calc = new Calculator();
19      calc.setArg1(new java.math.BigDecimal(10));
20      calc.setArg2(new java.math.BigDecimal(20));
21      iSpec.setArgument(0, com.microfocus.cobol.
             RuntimeProperties.BY_REFERENCE);

22      interaction.execute(iSpec, calc, calc);
23      System.out.println(
             "Input - Arg 1 was" + calc.getArg1());
24      System.out.println(
             "Input - Arg 2 was" + calc.getArg2());
25      System.out.println(
             "Result was" + calc.getResult());
26      System.out.println(
             "Memory was" + calc.getStorage());

28      interaction.close();
29      connection.close();
30      } catch( javax.resource.ResourceException re)
        {
31        re.printStackTrace();
32        Exception le = re.getLinkedException();
33      }

Lines 3-6:

mcf = new CobolNoTxManagedConnectionFactory();

Instantiate the above ConnectionFactory class. The class then configures the following attributes of the unmanaged connection between the Java code and the resource adapter:

  • mcf.setServerHost("localhost");

    This is the name of the machine where the resource adapter is located.

  • mcf.setServerPort("9003");

    This is the port where the enterprise server listens for resource adapter communication.

Line 8:

cxf = (javax.resource.cci.ConnectionFactory)
           mcf.createConnectionFactory();

Instantiate the javax.resource.cci.ConnectionFactory object, by using the CobolNoTxManagedConnectionFactory that you created in line 1.

Line 10:

connection = cxf.getConnection();

Instantiate the javax.resource.cci.Connection class. Invoke the getConnection method on your Connection Factory object to obtain an instance of Connection, configured as stated by the configuration of your CobolNoTxManagedConnectionFactory. This connection handle maps to a ManagedConnection at any time.

Line 11:

initialize(connection, cxf, true);

Initialize the connection. This is a necessary step. The true parameter denotes the state of the COBOL program on the enterprise server. If the program requires the same initial state each time, then set the boolean (parameter three) to true. Otherwise if you want to preserve the state between service calls then set the value to false.

Line 13:

interaction = connection.createInteraction();

Instantiate the javax.resource.cci.Interaction object, by invoking createInteraction() on your Connection object. The Connection object is responsible for the creation of the Interaction object, which will execute interactions with the enterprise server.

Line 15:

CobolInteractionSpec iSpec =
    new CobolInteractionSpec();

Instantiate and configure the specific object for the kind of interaction that is required. In this case, use the com.microfocus.cobol.connector.cci.CobolInteractionSpec class. This class builds the request and method of passing the parameters. The class is used to hold the function name and the direction (In, Out or I/O) of each of the arguments in an indexed record or the direction argument if it is a custom record.

Line 16:

iSpec.setFunctionName("myservice.add");

Set the name of the program to be run on the enterprise server, through the setFunctionName method.

Lines 18-21:

Calculator calc = new Calculator();
calc.setArg1(new java.math.BigDecimal(10));
calc.setArg2(new java.math.BigDecimal(20));
iSpec.setArgument(0,
      com.microfocus.cobol.
      RuntimeProperties.BY_REFERENCE);

Create a new object of custom record class. If only a custom record is being sent as an argument, the steps above are sufficient. The custom record is generated automatically when you generate the EJB. The source files generated for the custom record are available in myproject\repos\myService.deploy\packageName (Windows) or myproject/repos/myService.deploy/packageName (UNIX).

If more than one custom record or a mixture of custom records and basic Java types need to be passed as an argument, you need to use an indexed record. For example, if an integer and a custom record need to be passed as an argument, use the following code:

    javax.resource.cci.RecordFactory rf =
          cxf.getRecordFactory();
    javax.resource.cci.IndexedRecord iRec =
          rf.createIndexedRecord("IndexedIn");
    javax.resource.cci.IndexedRecord oRec =
          rf.createIndexedRecord("IndexedOut");
    iRec.add(new Integer(5));
    iRec.add(calc);
    iSpec.setArgument(0,
          com.microfocus.cobol.
          RuntimeProperties.BY_REFERENCE);

This sets the direction of the argument. The arguments are numbered from 0 and this is the first value passed to setArgument. The valid values for direction are:

    com.microfocus.cobol.RuntimeProperties.BY_REFERENCE
    com.microfocus.cobol.RuntimeProperties.BY_VALUE
    com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY

Line 22:

interaction.execute(iSpec, calc, calc);

Execute the Interaction. The execute() method invoked on the Interaction object causes the request to be flowed to the enterprise server.

Lines 28-29:

interaction.close();

Finally, close the Interaction and the Connection. The close() method on the Connection object is the final flow, and closes the underlying connection to the resource adapter. It must be executed after the close() method on the Interaction.

Parent topic: Writing a Simple CCI Program


Sample Initialize Method

The code for the initialize method is as follows:

private void initialize(
                 javax.resource.cci.Connection con,
                 javax.resource.cci.ConnectionFactory cf,
                 boolean isInitial) {
      try {
      javax.resource.cci.Interaction ix =
           con.createInteraction();
      com.microfocus.cobol.connector.cci.CobolInteractionSpec
           iSpec = new
           com.microfocus.cobol.connector.cci.CobolInteractionSpec();
      iSpec.setFunctionName("initialize");
      javax.resource.cci.RecordFactory rf =
           cf.getRecordFactory();
      javax.resource.cci.IndexedRecord irec =
           rf.createIndexedRecord("beanArgs");
      irec.add(new Boolean(isInitial));
      javax.resource.cci.Record orec =
           ix.execute(iSpec, irec);
      ix.close();
   } catch(javax.resource.ResourceException ex) {
      throw new javax.ejb.EJBException(
           "initialize threw ResourceException: ", ex);
   }
}
Parent topic: Writing a Simple CCI Program


Sample Custom Record

The above example uses the group record Calculator in the COBOL service, myservice.add. In the resource adapter CCI, this group record is expressed as a custom record. The following code is the custom record class, Calculator.java, corresponding to the group record:

/*******************************************************
This is a file generated by Micro Focus Net Express 4.0
This file represents the Custom Class for Calculator
*******************************************************/

public class Calculator extends
      com.microfocus.cobol.connector.cci.CustomRecord {

   private java.math.BigDecimal arg1 =
           java.math.BigDecimal.valueOf(0);
   private java.math.BigDecimal arg2 =
           java.math.BigDecimal.valueOf(0);
   private java.math.BigDecimal result =
           java.math.BigDecimal.valueOf(0);
   private java.math.BigDecimal storage =
           java.math.BigDecimal.valueOf(0);
   public Calculator() {
   }
   public java.math.BigDecimal getArg1() {
       return arg1;
   }
   public void setArg1(java.math.BigDecimal ___p) {
       arg1 = ___p ;
   }
   public java.math.BigDecimal getArg2() {
       return arg2;
   }
   public void setArg2(java.math.BigDecimal ___p) {
       arg2 = ___p ;
   }
   public java.math.BigDecimal getResult() {
       return result;
   }
   public void setResult(java.math.BigDecimal ___p) {
       result = ___p ;
   }
   public java.math.BigDecimal getStorage() {
       return storage;
   }
   public void setStorage(java.math.BigDecimal ___p) {
       storage = ___p ;
   }
   public Object[] getParameters() {
       Object[] objs = new Object[4];
       objs[0] = arg1;
       objs[1] = arg2;
       objs[2] = result;
       objs[3] = storage;
       return objs;
   }
   public void setParameters(Object[] objs) {
       arg1 = (java.math.BigDecimal)objs[0];
       arg2 = (java.math.BigDecimal)objs[1];
       result = (java.math.BigDecimal)objs[2];
       storage = (java.math.BigDecimal)objs[3];
   }
}
Parent topic: Writing a Simple CCI Program


Sample Calculator COBOL Program

The calculator COBOL program used in the sample service is:

          identification division.
       program-id. calculate.

       environment division.

       data division.
       working-storage section.
       01 calmemory      pic s9(9) comp-5 value 0.

       linkage section.
       01 calculator.
          05 arg1        pic s9(19)v9(19) comp-3.
          05 arg2        pic s9(19)v9(19) comp-3.
          05 result      pic s9(19)v9(19) comp-3.
          05 storage     pic s9(19)v9(19) comp-3.

       procedure division.
       exit program.

       entry "add" using calculator.
         move arg1 to result
         add  arg2 to result
         add  result to calmemory
         move calmemory to storage
         exit program.

       entry "subtract" using calculator.
         move arg1 to result
         subtract arg2 from result
         add  result to calmemory
         move calmemory to storage
         exit program.

      entry "multiply" using calculator.
         move arg1 to result
         multiply arg2 by result
         add  result to calmemory
         move calmemory to storage
         exit program.

      entry "divide" using calculator.
         move arg1 to result
         divide arg2 into result
         add  result to calmemory
         move calmemory to storage
         exit program.
Parent topic: Writing a Simple CCI Program


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
Using Java and COBOL Together
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) (Windows) or "2" (UNIX) directive.

    REENTRANT(2) (Windows) or "2" (UNIX) 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) (Windows) or "2" (UNIX) 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) (Windows) or "2" (UNIX) 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 help\mfcobol.docs.zip (Windows) or docs/mfcobol.docs.zip (UNIX) 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 help\mfcobol.docs.zip (Windows) or docs/mfcobol.docs.zip (UNIX) 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:
    Windows:
    $set ooctrl(+p-f)
    UNIX:
    $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 help\mfcobol.docs.zip (Windows) or docs/mfcobol.docs.zip (UNIX) 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 help\mfcobol.docs.zip (Windows) or docs/mfcobol.docs.zip (UNIX) 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 (Windows) or -d $TARGETDIR -classpath "$CLASSPATH":$TARGETDIR $FILENAME (UNIX). The "%CLASSPATH";%TARGETDIR (Windows) or "$CLASSPATH":$TARGETDIR (UNIX) 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.
  • We recommend that you add the -g Java build directive in debug mode (to generate debugging information), but replace it with the -O directive in release mode (to create optimized code). This applies to Windows environments (local development) only. You can set these directives by clicking on the Project menu. Then select the Compile tab for each .java file and add this directive to the list.
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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) 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 help\mfcobol.docs.zip (Windows) or docs/mfcobol.docs.zip (UNIX) 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
  • Example of Java Calling JVM COBOL
  • JVM COBOL Calling Java
  • Example of 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

In the IDE

In order to call JVM COBOL from Java, you need to add the JVM COBOL project to the build path of the Java project and to import any COBOL classes you want to use into your Java sources.

This is an outline of the steps to enable calling JVM COBOL from Java:

  1. In your Eclipse workspace, create a JVM COBOL project for your COBOL program.
  2. In your Eclipse workspace, create a Java project for the calling Java program.
  3. In the Java project, add the JVM COBOL project to the project's Java build path.
  4. Add mfcobol.jar and the JVM COBOL Runtime, mfcobolrts.jar to the project's classpath.

    This ensures proper interoperation of Java code with COBOL types which are not directly mapped to JVM types such as COBOL group items or COBOL numeric types which are longer than four bytes.

  5. 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.*
    Note: We recommend that you use the RunUnit class for multi-user environments. See com.microfocus.cobol.runtimeservices for more information.

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


Example of Java Calling JVM COBOL

The following example shows how to create a Java project and enable it to access a JVM COBOL program compiled to JVM byte code.

  1. In your Eclipse workspace, create a JVM COBOL project for the COBOL program:
    1. Click File > New > COBOL JVM Project.
    2. Type CobolProject as the project name.
    3. Click Finish.
  2. Add a COBOL class to the JVM COBOL project:
    1. Click File > New > COBOL JVM Class.
    2. Specify com.microfocus.test in the Package field.
    3. Specify CobolCalculator as the class name.
    4. Click Finish.

      This adds the class to your project and opens it in the editor.

  3. Add the following code snippet to the newly generated class:
           class-id com.microfocus.test.CobolCalculator public.

       working-storage section.

       method-id add.
       local-storage section.
       procedure division using by value firstNumber as binary-long,
                                by value secondNumber as binary-long,
                                returning result as binary-long.

           add firstNumber to secondNumber giving result
           goback.

       end method.

       end class.
  4. In your Eclipse workspace, create a Java project for the calling Java program:
    1. Click File > New > Project > Java > Java Project.
    2. Click Next.
    3. Specify JavaProject as the project name
    4. Click Finish.
    5. Click No in the Open Associated Perspective dialog box.
  5. Add a class to the Java project:
    1. Click File > New > Other > Java > Class.
    2. Click Next.
    3. Specify com.microfocus.javademo in the Package field.
    4. Specify JavaCalculatorClient as the class name.
    5. Click Finish.

      This adds the class to your Java project and opens it in the editor.

  6. Paste the following code in the Java class:
    package com.microfocus.javademo;

public class JavaCalculatorClient {

/**
* @param args
*/
    public static void main(String[] args) {

    CobolCalculator cobolCalculator = new CobolCalculator();
    System.out.println(cobolCalculator.add(10, 5));

    }
}

    Note that the Java code here uses the CobolCalculator class defined in the JVM COBOL project. However, because the interoperation between the Java and the JVM COBOL projects has not been enabled yet, the COBOL class is not recognized and the code above generates errors.

  7. To enable Java to access JVM COBOL, add the JVM COBOL project to the Java build path of the Java project as follows:
    1. Select your Java project and click Project > Properties.
    2. Click Java Build Path in the left-hand pane.
    3. Click the Projects tab.
    4. Click Add.
    5. Select your COBOL JVM project from the list and click OK twice.
  8. Add mfcobol.jar and the JVM COBOL Runtime, mfcobolrts.jar, to the project's classpath:
    1. Select the Java project and click Project > Properties.
    2. Select Java Build Path.
    3. Click the Libraries tab.
    4. Click Add External JARs and select mfcobol.jar and mfcobolrts.jar in <installdir>\bin (Windows) or $COBDIR/lib (Linux).
    5. Click Open and then OK.
  9. Add an import statement in the Java source file to import the COBOL class:
    1. Open the Java class, JavaCalculatorClient.java, in the editor.
    2. Insert the following code at the top of the file:
      import com.microfocus.test.CobolCalculator;
      Tip: This is the same as using the Eclipse Quick Fix feature in the editor:
      • Right-click the unresolved class, CobolCalculator, in the editor.
      • Select Quick Fix. This opens Content Assist which offers you several options to resolve the problem.
      • Double-click Import 'CobolCalculator' (com.microfocus.test) in the list. This adds an import statement in the code for the COBOL class.
    3. Build the project. Note that there are no build errors this time.
  10. Run your Java program.
    1. Click Run > Run As > Java Application.
    2. The IDE displays the result in the Console window.
Parent topic: JVM COBOL Interoperating with Java


JVM COBOL Calling Java

In the IDE

In order to call Java from JVM COBOL you need to add the Java project to the build path of the JVM COBOL project. There is no special syntax for calling the Java types from your JVM COBOL code. The Java types appear in the Content Assist for the JVM COBOL project alongside the other available types.

The following outlines the steps to enable calling Java from JVM COBOL:

  1. In your Eclipse workspace, create a Java project that contains the Java program which you wish to call from JVM COBOL.
  2. In your Eclipse workspace, create a JVM COBOL project for the calling JVM COBOL program.
  3. Add the Java project to the JVM build path of the JVM COBOL project (Project > Properties > Micro Focus > JVM Build Path > Projects).
  4. In the JVM COBOL code, declare variables of the types defined in your Java project.

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


Example of JVM COBOL Calling Java

The following example shows how to create a Java project and enable it to access a JVM COBOL program compiled to JVM byte code.

  1. In your Eclipse workspace, create a Java project for the Java program:
    1. Click File > New > Project > Java > Java Project.
    2. Click Next.
    3. Specify JavaProject as the project name
    4. Click Finish.
    5. Click No in the Open Associated Perspective dialog box.
  2. Add a class to the Java project:
    1. Click File > New > Other > Java > Class.
    2. Click Next.
    3. Specify com.microfocus.test in the Package field.
    4. Specify JavaCalculator as the class name.
    5. Click Finish.

      This adds the class to your Java project and opens it in the editor.

  3. Paste the following code in the Java class:
    package com.microfocus.test;

public class JavaCalculator {

    public int add(int first, int second) {
        return first + second;
    }
}
  4. In your Eclipse workspace, create a JVM COBOL project for the calling COBOL program:
    1. Click File > New > COBOL JVM Project.
    2. Type CobolProject as the project name.
    3. Click Finish.
  5. Add a new COBOL program to the JVM COBOL project:
    1. Click File > New > COBOL Program.
    2. Specify CobolCalculatorClient as the file name.
    3. Click Finish.

      This adds the COBOL program to your project and opens it in the editor.

  6. Add the following code snippet to the newly generated class:
           program-id. CobolCalculatorClient as "CobolCalculatorClient".

       data division.
       working-storage section.

       01 calculator type com.microfocus.test.JavaCalculator.
       01 result pic 99.

       procedure division.

           set calculator to new com.microfocus.test.JavaCalculator()
           set result to calculator::add(10, 5)
           display result

           goback.

       end program CobolCalculatorClient.

    Note that the COBOL code defines a variable of the type JavaCalculator which is defined in the com.microfocus.test package. However, because the interoperation between the Java and the JVM COBOL projects has not been enabled yet, the Java class is not recognized and the code above generates errors.

  7. To enable JVM COBOL to access Java, add the Java project to the build path of the JVM COBOL project as follows:
    1. Select your JVM COBOL project in the Application Explorer view.
    2. Click Project > Properties.
    3. Click Micro Focus > JVM Build Path in the left-hand pane.
    4. Click the Projects tab.
    5. Click Add.
    6. Select your Java project from the list and click OK twice.
    7. Build the project. Note that there are no build errors this time.
  8. Run your COBOL program.
    1. Open the COBOL program, CobolCalculatorClient, in the editor.
    2. Click Run > Run As > COBOL JVM Application.
    3. The IDE displays the result in the Console window.
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


Mainframe Programming

  • Mainframe Subsystem Support Developer Introduction
    Contains Mainframe Subsystem Support information for developers.
  • AppMaster Builder
  • Assembler Support
  • CICS Support
    This chapter describes the technical aspects of developing CICS applications.
  • HCO for DB2 LUW
    Explains the functionality associated with the DB2 External Compiler Module (ECM) preprocessor, and provides information for developing and deploying DB2 ECM SQL applications.
  • HCO for SQL Server (HCOSS)
  • IMS Support
  • JCL Support
    This chapter describes the support for JCL provided within Enterprise Developer.
  • Mainframe Emulation
  • PL/I Programming
  • SQL Option for DB2
Parent topic: Programming


Mainframe Subsystem Support Developer Introduction

This book explains how to use MSS to develop CICS , IMS and JCL applications that run under Enterprise Server.
  • What is Mainframe Subsystem Support?
  • About CICS applications
  • About IMS applications
  • About JCL applications
  • Configuring Enterprise Server to Run the Application
  • CICS Intersystem Communication
  • Terminal Emulation
Parent topic: Mainframe Programming


What is Mainframe Subsystem Support?

Mainframe Subsystem Support (MSS) enables you to maintain and run CICS, IMS and JCL applications. These applications have been migrated from the mainframe and now run under Enterprise Server on Windows or UNIX.

You use Enterprise Developer for maintaining your CICS, IMS and JCL applications. If you are working with CICS, you can edit and compile BMS maps, and also compile the CICS programs, using the Micro Focus CICS preprocessor, which translates the CICS commands into native code. If you are working with IMS, you can edit and generate your DBDs, MFSs and PSBs, and compile your IMS programs. If you are working with JCL, you can edit and create JCL, and build projects containing the programs that the JCL references. When the application is ready to run, you then deploy it to Enterprise Server.

You use Enterprise Server for running your CICS, IMS and JCL applications, for testing and for production use. Enterprise Server also provides facilities for monitoring and controlling your applications and for other tasks such as maintaining CICS resource definitions and viewing the system catalog and spool queues.

  • Migrating the Application
Parent topic: Mainframe Subsystem Support Developer Introduction


Migrating the Application

System integrators are typically responsible for migrating the CICS, IMS and JCL applications from the mainframe. They download the applications to the Windows or UNIX environment, and leave you with a working application, running under Enterprise Server.

In some cases the system integrators might use Micro Focus migration tools including Enterprise Developer to migrate your CICS or IMS applications. They replace one mainframe-only language or technology at a time, and make sure that the application works correctly before continuing. For example, if your application includes Assembler and PL/I modules, they might replace the Assembler modules with COBOL modules. They would then recompile and test the application thoroughly before moving on to replace the PL/I modules.

When the system integrators have got the application up and running under Enterprise Server, they hand over to you to maintain and develop the applications in Enterprise Developer, and to run the applications under Enterprise Server.

This book assumes that your application has been migrated from the mainframe, and that it runs successfully under Enterprise Server.

Parent topic: What is Mainframe Subsystem Support?


About CICS applications

When the CICS application has been migrated from the mainframe to the PC, you maintain and develop the application as follows:

  1. Create a project comprising all the parts of the application, such as the COBOL source and BMS mapsets. This also involves specifying the appropriate project and build properties.
  2. Edit BMS mapsets used by your client program, as required. You can do this using the BMS Painter supplied with this product.

    If your client program uses a graphical or Web interface, use the External Call Interface (ECI) to communicate with the CICS application.

  3. Compile the CICS COBOL programs and BMS mapsets.
  4. Configure an enterprise server to run the CICS application. This involves, among other things, adding a listener for CICS requests and setting up search paths to locate your application files, the CICS resource definitions and so on.
  5. Run the application in Enterprise Server and check that it is working correctly. Use the facilities for monitoring CICS applications within Enterprise Server, as necessary.
  6. Debug the application in your COBOL development system IDE.
  7. To publish the application to UNIX:
    1. Copy the source files to your UNIX machine.
    2. Compile the programs using the Cob utility.
    3. Test and debug the application using our Server Express product.
  • Micro Focus BMS Painter
  • Invoking CICS Programs Externally
  • CICS Application Programming Interface (API)
  • File and Database Support
  • CICS ECM Preprocessor
Parent topic: Mainframe Subsystem Support Developer Introduction
Related information
Developing CICS Applications


Micro Focus BMS Painter

If your application uses Basic Mapping Support (BMS) mapsets, which provide the user interface, you might need to update these. The Micro Focus BMS Painter enables you to do this.

The painter provides a screen painting facility that enables fields, labels, and attributes to be defined and positioned as they would be for a 3270 display device. It provides fast BMS screen definition and manipulation with powerful features like block moves and copies through simple use of a keyboard or mouse. It supports most standard BMS macro operands plus long data names and allows the construction of repeated groups of fields in a manner similar to the IBM Screen Definition Facility (SDF II).

BMS macro output is fully portable to mainframe CICS. Mapset painting and generation are supported for 3270 models 2 through 5.

  • Overview of the BMS Painter
    The BMS Painter is a powerful, flexible tool for designing maps and generating the BMS macros necessary for creating displayable mapset objects. The painter can also generate the corresponding copybooks needed for using these maps from your program, and compile them into executable modules.
  • Starting the BMS Painter Utility
    If you are using a mainframe subsystem application project, you can start the BMS Painter from the IDE.
  • Configuring the BMS Painter
    You can configure the BMS Painter using the settings available from the Options menu.
  • Build Settings for the BMS Painter
    You specify BMS build settings for the BMS Painter in the properties of the BMS file within Enterprise Developer.
  • Working with Maps
    Use the BMS Painter to configure the contents of your map, such as creating fields, then grouping them together or creating an array of a particular field.
  • Defining Field, Map and Mapset Properties
    You define the properties of fields, maps and mapsets using the Field Properties, Map Properties and Mapset Properties dialog boxes.
  • Working with Previously Created Maps
    You can open and work on a mapset that has been downloaded to your PC from the mainframe but as yet does not belong to a project.
  • Generating Output from the BMS Painter
    Use the BMS Painter to generate a number of different output types
  • BMS Compiler
    Compiles BMS mapsets from the command line.
  • BMS Painter Technical Details
    The following section assumes that you are familiar with BMS fields, maps, and mapsets, and with the DFHMDF, DFHMDI, and DFHMSD macros.
  • BMS Directives
    There are a number of Compiler directives that are applicable to BMS files, and, depending on the directive, can be set in one of two ways.
  • BMS Painter Keyboard Shortcuts
    There are several keyboard shortcuts that you can use to navigate around the map view of the BMS Painter window.
  • BMS Painter Compile Messages
    Error messages that may be produced during the compilation of a BMS file are prefixed BMSCH.
  • BMS Painter Generate Messages
    Error messages that may be produced during the generate phase of a BMS file are prefixed BMSCM.
Parent topic: About CICS applications
Parent topic: Mainframe Reference


Invoking CICS Programs Externally

The client program for your CICS application need not run in a CICS region, and need not use BMS. You can invoke your CICS programs externally via a graphical or Web user interface that is written in Java, Cobol, C, or runs under Microsoft .NET or uses Dialog System. You achieve this using the External Call Interface (ECI) and (External Presentation Interface (EPI), which allow non-CICS programs to interact with CICS programs and transactions.

Enterprise Server supports standard ECI and EPI calls to Mainframe Subsystem enterprise server instances. ECI allows non-CICS programs running outside the server to invoke COMMAREA-based CICS programs within a region. EPI allows non-CICS programs to initiate 3270-based CICS transactions and send/receive associated data. Both ECI and EPI facilitate the opening up of access to legacy business logic.

Which Middleware?

Micro Focus provides two methods of communicating with CICS applications running under Enterprise Server. These are: IBM CICS Transaction Gateway (CTG), and Micro Focus ECI. You need to determine which of these two methods best suits your requirements.

IBM CICS Transaction Gateway
IBM's CICS Transaction Gateway (CTG) is a full function connector, allowing a wide range of application platforms to connect to CICS. If you require all the features provided by CTG, then you may wish to choose this product. However, consider these factors:
  • You require an IBM CTG license
  • You need to install and configure CTG on each client machine, unless you link the CTG module into your client program

For more information, refer to the IBM publication CICS Transaction Gateway for Multiplatforms.

Micro Focus ECI
Micro Focus provides a no-cost ECI emulator as part of Enterprise Server. Being an integral part of the product, you do not need to install or configure any additional software. This emulator has a simpler feature set, and supports the following:
  • COBOL ECI LUW and ELUW
  • COBOL ECI client with ES region on the same local machine and shared memory link between client and server
  • COBOL ECI client with ES region on a local or remote machine and TCP/IP link between client and server
  • Java ECI LUW and ELUW with SSL
  • Java ECI client with ES Server on a local or remote machine and TCP/IP link between client and server
  • Additionally, Java ECI clients can invoke CICS programs passing data either in a Commarea or in a Channel and its associated Containers.
  • Non transactional Java Connector Architecture based resource adapter. Java ECI clients run in Java AS. Support for Websphere 8.5 and JBoss 7.1
The following restrictions apply to this implementation:
  • No managed COBOL
  • No SSL for COBOL ECI clients
  • No support for External Presentation Interface (EPI)
  • No support for External Security Interface (ESI)
  • No workload management
  • IBM CICS Transaction Gateway
    An overview of the programming interfaces provided by IBM's CICS Transaction Gateway to enable external access to CICS applications running under Enterprise Server.
  • Micro Focus External Call Interface
    An overview of the programming interface provided by Micro Focus to enable external access to CICS applications running under Enterprise Server.
Parent topic: About CICS applications


IBM CICS Transaction Gateway

Client programs using the CTG APIs can run on the same machine as the Enterprise Server region, or on different physical hardware. In either case, requests are submitted to the target region through the communication layer via the Web Services and J2EE listener.

Programming for IBM CICS Transaction Gateway

You use the CTG APIs (ECI, EPI and ESI) in your client program to communicate with the CICS application running under Enterprise Server. The calls from your client program are passed through the IBM CICS Transaction Gateway to Enterprise Server.

CICS client-side support
The API entry points such as CICSEXTERNALCALL are exposed by modules which are supplied as a dynamic load library on Windows and a callable shared object on UNIX and Linux platforms. Please consult the IBM CICS Transaction Gateway documentation for platform-specific information.

Client programs can add a CALL statement to the dll exposing the required ECI/EPI API, include an INITCALL directive (COBOL), or link the client module to the appropriate .lib file.

Note: To call programs with Java, use the Java API provided by IBM.
Configuration

You need to configure CTG to refer to a named Enterprise Server and a nominated port - this is most commonly done via the IBM CICS Transaction Gateway Configuration Tool. ECI and EPI calls via CTG require the creation of a CTG listener, which can be accomplished via the Listeners tab of the relevant Enterprise Server Administration screen, ensuring that the Endpoint Address corresponds to the specified CTG port, and CICS Transaction Gateway is selected as the supported conversation type.

Restrictions
IBM provides Java classes to create channels and containers in an ECI client, and pass these channels and containers to a CICS application. The mechanism for this feature is provided by the IBM proprietary transport IP interconnectivity (IPIC), which is not supported by Enterprise Server.
Parent topic: Invoking CICS Programs Externally


Micro Focus External Call Interface

ECI client programs can run on the same machine as the Enterprise Server, or on different physical hardware. Requests are submitted to the target region through the communication layer. If you wish to access a remote server, your programs connect via the Web Services and J2EE listener. The following diagram shows the path of the request from the client to a remote server over TCP/IP:

Alternatively, you may wish to access a local server via shared memory. The following diagram shows the path of the request from the client to a local server:

Programming for Micro Focus External Call Interface

You can use ECI calls in your client program to communicate directly with a CICS application running under Enterprise Server, and bypass the need for any third-party software at all.

Client-side support

ECI entry points such as CICSEXTERNALCALL are exposed by the casbnccl module which is supplied as a dynamic load library on Windows and a callable shared object on UNIX and Linux platforms.

Client programs should call this module either by coding a CALL statement, or by using an INITCALL(casbnccl) compilation directive. Currently, there is no facility to link the casbnccl module into a client application.

Java client support
Micro Focus also provides an ECI API for Java clients. Using this API, you can invoke CICS programs running on Enterprise Server, and do it without the help of CTG. You can invoke CICS programs using either extended mode (transactional) or non-extended mode (non-transactional).
Note: The Java client ECI API supports only synchronous calls to Enterprise Server.

To use the API, you typically set up the connection with host, port, connection type and trace flags. After populating the CommArea object and the CCLParams object with an appropriate CICS program name, user ID, and password, the API sends the request to the enterprise server and gets a ECIResponse object back from the server. In case of an exception, the enterprise server returns either a CICSException or an AbendException.

An explanation of how you change your Java code to work with Micro Focus ECI calls is in Micro Focus ECI Java API.

Configuration

To configure an Enterprise Server region to use the ECI, set the ES_LEGACY_ECI environment variable to Y. For example, ES_LEGACY_ECI=Y.

If the amount of data to be returned from the CICS programs that you will be running will be approximately more than twice the size of the input data, set the ES_ECI_MAX_RESP environment variable to the maximum expected response size (in bytes). For example, ES_ECI_MAX_RESP=70000.

Locating a Server
The simplest method of communicating with a server in a COBOL program is via a Micro Focus ECI extension. This feature is enabled with these environment variables:
ES_REGION An eight character region/server ID.
Example:
ES_REGION=myserver
Implies use of shared memory to a local server.
ES_ECI_SOCKET An eight character region/server ID and web services listener port separated by a colon (<server>:<port>).
Example:
ES_ECI_SOCKET=myserver:9001

Implies use of TCP/IP to a local or remote server.

The two environment variables are mutually exclusive. However, if you do use both, ES_ECI_SOCKET takes precedence over ES_REGION.

If you omit to use either of these environment variables, then the mode of operation is the same as that for IBM CTG. In this instance, the server to which the request is directed is identified through the ECI-SYSTEM-NAME variable in the ECI parameter block, and takes a null- or space-padded value, which must match a server definition in the MFDS repository.

The location of this repository can be specified either by editing the mf-client.dat file, or by setting the environment variable ES_ECI_CCITCP2 which takes the value: <host>:<mfds-port>, for example:
ES_ECI_CCITCP2=localhost:86
The mf-client.dat file can be found in the \bin and \bin64 directory of your Micro Focus COBOL product installation on Windows, and in /etc on UNIX and Linux.
Parent topic: Invoking CICS Programs Externally


CICS Application Programming Interface (API)

A large subset of the command-level API of IBM CICS is supported and provides the expected behavior for programs written using this syntax. Most syntax that is not functionally supported is recognized so that programs using these commands and operands will compile without change. Much of the CICS system programming interface is also supported; some CICS APIs in MSS return fixed, default values, rather than values that the mainframe might return.

Parent topic: About CICS applications


File and Database Support

Data access is supported for data in emulated VSAM files, IMS databases, and relational database systems.

VSAM file emulation is supported for ESDS and RRDS files and KSDS data sets, which can also be shared with non-CICS (batch) applications. Fileshare provides data integrity for VSAM emulation for application data files, temporary storage and transient data queues. Alternate indexes are supported for application data files. Emulated VSAM files use standard Micro Focus file formats.

Support is provided to the XA-compliant SQL databases from Oracle and IBM DB2/UDB.

Parent topic: About CICS applications


CICS ECM Preprocessor

The CICS command syntax is recognized by the CICS External Compiler Module (ECM) preprocessor, which runs as part of the program compilation step. The preprocessor scans the program source for EXEC CICS commands and replaces them with native statements for the language in which the program is written.

We provide two methods of invoking the CICS ECM:
  • On the COBOL tab in your project properties, check EXEC CICS (preferred method).
  • Set the CICSECM compiler directive when compiling on the command line, or in your program.
Parent topic: About CICS applications


About IMS applications

When the IMS application has been migrated from the mainframe to the PC, you maintain and develop the application as follows:

  1. Create a project comprising all the parts of the application, such as the COBOL source DBD, MFS and PSB files. This also involves specifying the appropriate project and build properties.
  2. Compile the IMS COBOL programs and generate the DBD, MFS and PSB files.
  3. Configure an enterprise server to run the IMS application. This involves, among other things, setting up search paths to locate your application files, and specifying the message processing regions in which your application will run.
  4. Run the application in Enterprise Server and check that it is working correctly. Use the facilities for monitoring IMS applications within Enterprise Server, as necessary.
  5. Debug the application in your COBOL development system IDE.
Parent topic: Mainframe Subsystem Support Developer Introduction
Related information
Developing IMS Applications


About JCL applications

When the JCL application has been migrated from the mainframe to the PC, you maintain and develop the application as follows:

  1. Create a project comprising all the parts of the application, such as the COBOL source JCL files. This also involves specifying the appropriate project and build properties.
  2. Compile the COBOL programs.
  3. Configure an enterprise server to run the JCL application. This involves, among other things, setting up search paths to locate your application files, the system catalog and so on.
  4. Run the application in Enterprise Server and check that it is working correctly. Use the facilities for monitoring JCL applications within Enterprise Server, as necessary.
  5. Debug the application using Enterprise Developer.

File and database support is the same as for CICS applications.

Parent topic: Mainframe Subsystem Support Developer Introduction
Related information
JCL Support


Configuring Enterprise Server to Run the Application

When the CICS, IMS or JCL application has been compiled, you run it under Enterprise Server. If you have CICS, IMS or JCL applications already running under an enterprise server, you might be able to use that enterprise server. Alternatively, if you want to run the application on your own machine under your own enterprise server, you need to configure an enterprise server for running CICS, IMS or JCL applications.

The Enterprise Server Administration console and Enterprise Server Monitoring and Control (ESMAC), provide facilities to do this. Among other tasks, you need to:

  • Update the resource definitions for the application, as necessary. The resources include system initialization tables (SITs), startup lists, transactions, programs and so on (CICS and JCL only).
  • Set up search paths to locate the programs, data files and other resources that your application uses.
  • Adjust the data conversion templates as necessary (CICS only).
  • Add an enterprise server listener to listen for CICS requests (CICS only).
  • CICS, IMS and JCL Resources
  • Data Conversion
Parent topic: Mainframe Subsystem Support Developer Introduction
Related information
Administering CICS-enabled Enterprise Servers
Administering JCL-enabled Enterprise Servers
Administering IMS-enabled Enterprise Servers


CICS, IMS and JCL Resources

The resources that your CICS application uses need to be defined, so that you have a CICS environment in which you can run and debug your applications. The resource definitions are set up as part of the migration of your application from the mainframe. They are stored in a Resource Definition file called dfhdrdat.

JCL and IMS and applications also use CICS-style resource definitions, defined in the dfhdrdat file.

The resource definitions include:

  • A system initialization table (SIT)

    The SIT defines the initialization parameters to use when the enterprise server that runs your application is started. You might need to change some of these parameters for your project.

    A SIT is required for CICS, IMS and JCL applications.

  • A startup list

    The startup list contains the list of the groups of resources to be used. Enterprise Server loads all the groups in the startup list. The base startup list dfhlist contains recommended system groups that you should include in all your user-defined startup lists.

    A startup list is required for CICS, IMS and JCL applications.

  • Resource groups

    Resource groups are sets of resource definitions that define the programs and files that are used by the enterprise server running your application. If you create any resource groups you need to add them to the startup list, or you can add them at execution time in Enterprise Server with the CINS supplied transaction.

    Resource groups for CICS include:

    • Program Control Table (PCT) - this defines the transactions that your application uses
    • File Control Table (FCT) - this defines information about the files that your application uses, such as the file type (KSDS, ESDS, RRDS) and minimum and maximum record length
    • Processing Program Table (PPT) - this defines the programs that are invoked by transactions or other programs.

    The only resource group you need for JCL is a JES resource group. This contains definitions of special service execution processes which start when the enterprise server is started, and which run JCL jobs and handle the sending of job output to a printer.

    IMS applications also need to use the JES resource group, as it contains definitions of the message processing regions (MPRs) which start when the enterprise server is started.
Parent topic: Configuring Enterprise Server to Run the Application


Data Conversion

CICS applications on the mainframe run with an EBCDIC character set. PCs use an ANSI character set, while on UNIX the character set in use is ASCII. When CICS applications are migrated from the mainframe, the majority of them are converted to use ANSI or ASCII, and they run under Enterprise Server using ANSI or ASCII. However, there are some cases where an application needs to continue to use EBCDIC on the server, while the client program uses ANSI or ASCII. In these cases, you need to set up data conversion macros to ensure the data is converted.

For details see the section Data Conversion in the chapter Legacy Extension with MSS in your MSS Configuration and Administration Guide.

Parent topic: Configuring Enterprise Server to Run the Application


CICS Intersystem Communication

CICS applications can operate over networks in client/server, cooperative, and distributed processing modes.

The supported CICS intersystem communication facilities include:

  • Transaction routing
  • Function shipping
  • Distributed program linking (DPL)
  • Distributed transaction processing (DTP)
  • IBM CICS Transaction Gateway® (CTG). Enterprise Server provides a CTG listener and can process CTG requests, where the requests conform to the IBM ECI (External Call Interface) or EPI (External Presentation Interface) . The client program contains ECI or EPI calls, which send requests through the CTG to Enterprise Server.
  • IBM Universal Client®. This is effectively the same as the CTG.

For more information about using these facilities, see the chapter Legacy Extension with MSS in your Mainframe Subsystem Support Configuration and Administration Guide.

Parent topic: Mainframe Subsystem Support Developer Introduction


Terminal Emulation

The user interface to CICS and IMS applications from the PC is often through 3270 terminal emulators. The 3270 terminal emulators enable the CICS and IMS applications to display input and output screens on the PC using 3270 data streams and to receive input from the PC. It is intended for programs that use BMS or build 3270 data streams. Emulation is provided for 3270 models 2 through 5.

We recommend that you use a Telnet 3270 (TN3270) client such as Micro Focus RUMBA. The keyboard mapping and support for character level attributes is a property of the third-party TN3270 client you choose.

When you start a 3270 terminal emulator, it is separate from the enterprise server that runs the CICS or IMS application. Terminals do not need to be predefined. This means terminal emulation characteristics can be specified at terminal startup.

Enterprise Server needs to have a listener for requests from 3270 terminal emulators. You add this as part of configuring the enterprise server that will run your CICS or IMS application.

  • Running Applications in a TN3270 Mainframe Display
    Enterprise Developer enables you to use a mainframe display control integrated within the IDE, or launch a mainframe session of an external emulator from within the IDE when running or debugging Mainframe Subsystem applications that require an emulator that supports TN3270 to run.
Parent topic: Mainframe Subsystem Support Developer Introduction


Running Applications in a TN3270 Mainframe Display

Enterprise Developer enables you to use a mainframe display control integrated within the IDE, or launch a mainframe session of an external emulator from within the IDE when running or debugging Mainframe Subsystem applications that require an emulator that supports TN3270 to run.

Enterprise Developer supports the following TN3270 mainframe displays:

Rumba Mainframe Display view
A Rumba Mainframe Display view embedded in the IDE.

This option is only available if you have installed and licensed Micro Focus Rumba 8.3 or later (Rumba 9.5 is included with the Enterprise Developer setup file).

Rumba Desktop
You can use a mainframe session of Rumba Desktop to run or debug the applications you develop in Enterprise Developer.
Other
Alternatively, if you have an emulator other than Rumba that has a mainframe display, you can use that to run your Mainframe Subsystem applications.
Note:
  • The functionality described in this section is only available for native Mainframe Subsystem Projects.
  • For more information, see the Micro Focus Rumba product Help.
  • Choosing a TN3270 Mainframe Display
    You can specify in the IDE which mainframe display to use by default.
  • Embedded Rumba Mainframe Display View
    The embedded Rumba Mainframe Display view is a Rumba TN3270 emulator fully integrated within the IDE. This option is only available if you have installed and licensed Micro Focus Rumba 8.3 or later.
  • Running Applications in a TN3270 Mainframe Display
  • Debugging using a TN3270 Mainframe Display
    Debugging of Mainframe Subsystem applications differs depending on the TN3270 display options you have specified in the IDE.
Parent topic: Terminal Emulation
Related concepts
Debug MFDEMO
Run MFDEMO


Choosing a TN3270 Mainframe Display

You can specify in the IDE which mainframe display to use by default.
  1. In the IDE, click Window > Preferences.
  2. Expand Micro Focus > Enterprise Server, and click TN3270.
  3. Ensure that Enable display is checked.

    If you leave this unchecked, you can still execute your application but no display is available when you run or debug the application.

  4. Click one of the options to specify the integrated TN3270 display to use:
    • Rumba (Embedded) - click this to use the embedded Rumba display when you run or debug your application. By default, the session connects automatically.

      This options is only available if you have installed Rumba 8.3 or 9.0.

    • Rumba (Desktop) - click this to use Rumba Desktop to run or debug applications. The IDE launches Rumba Desktop if it not already running, and starts the application in a mainframe session. The session connects automatically.
    • External - click this to use a TN3270 mainframe emulator other than Rumba.
  5. Click OK.
Parent topic: Running Applications in a TN3270 Mainframe Display


Embedded Rumba Mainframe Display View

The embedded Rumba Mainframe Display view is a Rumba TN3270 emulator fully integrated within the IDE. This option is only available if you have installed and licensed Micro Focus Rumba 8.3 or later.

The Rumba Mainframe Display view is a TN3270 Mainframe Rumba emulator embedded in the IDE. To detach and leave the view floating, right-click the toolbar of the view, and click Detached. The IDE preserves the last state, size, and position of the window between debug sessions.

The Embedded Rumba Mainframe Display view includes:

  • A toolbar with the following buttons:
    • New Rumba Mainframe Display New Rumba Mainframe Display - enables you to specify connection details and connect the display to an enterprise server.
    • Show Terminal Show Terminal - enables you to view the active connections and choose to display one of them.
    • Connect and Disconnect Disconnect - use this to connect or disconnect the display to the server in the current connection.
    • Disconnect and Close Close - disconnects the display from the server and closes the current connection.
    • Disconnect and Close All Close All - disconnects the server from the current connection and also closes all connections.
    • Properties Properties - opens the TN3270 Connection Properties dialog box with the properties of the curent connection. If the display is temporary disconnected, it enables you to reconnect.
    • Help Help - opens the Help for the embedded mainframe display.
  • Emulation screen - the main area of the view
  • Status bar - includes the following indicators:
    • Terminal name - shows the name of the current connection.
    • Status field - displays general Rumba software status information.
    • Cursor coordinates - displays the row and column position of the cursor.
    • Connection properties - displays the server and the port that the display is currently connected to.

Follow the links below for details on how to use the embedded Rumba Mainframe Display view.

  • Connecting to the host
  • Disconnecting from the host
Parent topic: Running Applications in a TN3270 Mainframe Display


Connecting to the host

To establish a connection to an enterprise server:

  1. Click the New Rumba Mainframe Display button, New Rumba Mainframe Display, on the toolbar of the Rumba Mainframe Display view. This starts the TN3270 Connection Properties dialog box.

  2. Type the name or IP address of the enterprise server and the TN3270 port number.
  3. Optionally, type a name for the connection in the Terminal name field. If you do not specify a terminal name, the server connection is listed as ServerName:PortNumber - for example, localhost:5000.
  4. Click Connect.

If the emulator is temporarily disconnected from the server, you can reconnect as follows:

  5. Click the Connect button Connect on the toolbar of the Rumba Mainframe Display view.
  6. Or, alternatively, click the Properties button Properties on the toolbar, specify connection details if necessary, and click Connect.
Parent topic: Embedded Rumba Mainframe Display View
Related tasks
Disconnecting from the host


Disconnecting from the host

To disconnect the Rumba Mainframe Display view from the host (this does not close the connection):

  1. Click the Disconnect button Disconnect on the toolbar of the Rumba Mainframe Display view.

To close the active connection:

  2. Click the Disconnect and Close button Close on the toolbar.

To close all connections in the mainframe display:

  3. Click the Disconnect and Close All button Close All on the toolbar.
Parent topic: Embedded Rumba Mainframe Display View
Related tasks
Connecting to the host


Running Applications in a TN3270 Mainframe Display

To run Mainframe Subsystem applications in a TN3270 mainframe display:

  1. Build your Mainframe Subsystem Application project.
  2. Ensure that your project is associated with an enterprise server and that the server is running.
  3. Launch the TN3270 Mainframe Display and connect it to the server.
  4. Use the TN3270 Mainframe Display to execute the application.
  • Launching the Display When Running Applications
  • Connecting the Display to an Enterprise Server When Running Applications
Parent topic: Running Applications in a TN3270 Mainframe Display


Launching the Display When Running Applications

To start the Rumba Mainframe Display view:

  • From COBOL Explorer - right-click your project, and click Enterprise Server > Show TN3270 Display.
  • From Server Explorer - right-click the enterprise server associated with your project, and click Show TN3270 Display.
  • From the IDE menus:
    1. In the IDE, click Window > Show View > Other.
    2. Select Rumba Mainframe Display under Micro Focus, and click OK.
    3. Connect the display to the enterprise server on which your application is running.
To start Rumba Desktop or a third-party TN3270 emulator:
  1. Start the emulator manually outside of the IDE.
  2. Connect the emulator to the enterprise server on which your application is running.
Parent topic: Running Applications in a TN3270 Mainframe Display
Related information
Connecting the Display to an Enterprise Server When Running Applications


Connecting the Display to an Enterprise Server When Running Applications

By default, when launched, the Rumba Mainframe Display view connects automatically to the enterprise server associated with your project.

You need to connect Rumba Desktop or any third-party emulator manually to the enterprise server associated with your project.

When using the embedded Rumba Mainframe Display view, you can have more than one active connections at the same time, but the display is only showing one of them. To switch to a different connection:

  1. Click the Show Terminal button, [image]:

  2. Click the name of the server to which you want to connect.

    This connects the display to the respective server and loads the application in it.

    Closing the Rumba Mainframe Display view does not disconnect the active sessions.

Parent topic: Running Applications in a TN3270 Mainframe Display
Related information
Launching the Display When Running Applications


Debugging using a TN3270 Mainframe Display

Debugging of Mainframe Subsystem applications differs depending on the TN3270 display options you have specified in the IDE.
  • Launching the TN3270 Mainframe Display When Debugging Applications
  • Connecting the Display to an Enterprise Server when Debugging Applications
  • Debugging Using the Embedded Rumba Mainframe Display View
    Depending on the TN3270 debugging settings you have set and on the last state of the mainframe display, the display either launches automatically when debugging starts, or you need to launch it manually.
  • Debugging using Rumba Desktop
  • Debugging using Other TN3270 Emulators
Parent topic: Running Applications in a TN3270 Mainframe Display


Launching the TN3270 Mainframe Display When Debugging Applications

Before you can start the TN3270 mainframe display specified in the IDE options, ensure that your project is associated with an enterprise server and that the server is running.

When you start debugging, the IDE automatically launches the TN3270 Mainframe Display specified in the IDE preferences and connects it to the enterprise server on which your application is running.

If the TN3270 Mainframe display of choice is closed, you can open it in one of the following ways:

  1. In the Debug perspective, right-click the application thread in the Debug view.
  2. Click Show Rumba Terminal.

Alternatively, you can show the Rumba Mainframe Display view as follows:

  1. Click Window > Show View > Other.
  2. Select Rumba Mainframe Display under Micro Focus, and click OK.

    The view automatically connects to the enterprise server on which the application you are debugging runs.

Parent topic: Debugging using a TN3270 Mainframe Display
Related information
Connecting the Display to an Enterprise Server when Debugging Applications
Debugging Using the Embedded Rumba Mainframe Display View
Debugging using Rumba Desktop
Debugging using Other TN3270 Emulators


Connecting the Display to an Enterprise Server when Debugging Applications

By default, when launched, the TN3270 mainframe display automatically connects to the enterprise server associated with your application.

When using the embedded Mainframe Rumba Display view, you can have more than one active connections at the same time, but the display is only showing one of them. To connect to a different enterprise server from the ones to which you have already been connected:

  1. Click the Show Terminal button [image], and click the server to which you want to connect.

    This connects the display to the respective server and loads the application in it.

Parent topic: Debugging using a TN3270 Mainframe Display
Related information
Launching the TN3270 Mainframe Display When Debugging Applications
Debugging Using the Embedded Rumba Mainframe Display View
Debugging using Rumba Desktop
Debugging using Other TN3270 Emulators


Debugging Using the Embedded Rumba Mainframe Display View

Depending on the TN3270 debugging settings you have set and on the last state of the mainframe display, the display either launches automatically when debugging starts, or you need to launch it manually.

The IDE preserves the last state, size, and position of the embedded Rumba Mainframe Display view:

  • If the embedded Rumba Mainframe Display view is open when debugging ends, it opens automatically next time you start debugging.
  • If you close the embedded Rumba Mainframe Display view, the session is still connected until debugging ends.
Parent topic: Debugging using a TN3270 Mainframe Display
Related information
Launching the TN3270 Mainframe Display When Debugging Applications
Connecting the Display to an Enterprise Server when Debugging Applications
Debugging using Rumba Desktop
Debugging using Other TN3270 Emulators


Debugging using Rumba Desktop

If Rumba Desktop is your TN3270 emulator of choice the IDE launches it, if Rumba Desktop is not already running, and connects to the enterprise server where your application is running. Stopping debugging closes Rumba Desktop.

If Rumba Desktop is already running, when you start debugging, it opens a new tab and connects to the enterprise server where your application is running. In this case, stopping debugging does not close Rumba Desktop.

Note: For more information, see the Rumba product Help.
Parent topic: Debugging using a TN3270 Mainframe Display
Related information
Launching the TN3270 Mainframe Display When Debugging Applications
Connecting the Display to an Enterprise Server when Debugging Applications
Debugging Using the Embedded Rumba Mainframe Display View
Debugging using Other TN3270 Emulators


Debugging using Other TN3270 Emulators

The IDE uses the Eclipse debugger to debug applications that run in an external emulator. The IDE automatically launches the emulator when debugging starts. Stopping debugging closes the emulator.

Parent topic: Debugging using a TN3270 Mainframe Display
Related information
Launching the TN3270 Mainframe Display When Debugging Applications
Connecting the Display to an Enterprise Server when Debugging Applications
Debugging Using the Embedded Rumba Mainframe Display View
Debugging using Rumba Desktop


AppMaster Builder

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Introducing AppMaster Builder
    AppMaster Builder is a full-function application generator that automates the development and redevelopment of the applications that support your business. With AppMaster Builder you can build simple or complex applications without manual coding.
  • Developing Applications in the AppMaster Builder Perspective
    Describes the tools AppMaster Builder provides for developing applications, and how to use those tools to develop your applications in the Eclipse AppMaster Builder Perspective.
  • Developing Applications in the Team Developer Perspective (Technology Preview)
    Describes the use of AppMaster Builder in the Eclipse Team Developer perspective, which includes mainframe access using the AMB Endevor Interface.
  • AMB Endevor Interface (Technology Preview)
    Describes the AMB Endevor Interface feature, which provides AppMaster Builder project element integration with mainframe Endevor elements.
  • Generating Code
    Explains the processes of generating AMB objects, such as screens, programs, and full applications from both the Enterprise Developer IDE in Eclipse and from the command line.
  • Administration
    Describes the AppMaster Builder features designed for AMB administrators.
  • How to
  • Reference
Parent topic: Mainframe Programming


Introducing AppMaster Builder

AppMaster Builder is a full-function application generator that automates the development and redevelopment of the applications that support your business. With AppMaster Builder you can build simple or complex applications without manual coding.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Scenario for Using AppMaster Builder
  • The AppMaster Builder Tool Set
  • AppMaster Builder User Areas
  • AppMaster Builder Preferences
  • AppMaster Builder in Eclipse IDE vs. AppMaster Builder in Mainframe Express IDE
    Shows the Eclipse IDE equivalents to Mainframe Express IDE features.
Parent topic: AppMaster Builder


Scenario for Using AppMaster Builder

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AppMaster Builder lets you work in whatever sequence you choose. For example, you can define the user interface before you think about the program logic. Or you can first define the global data that all programs must use. Whether you decide to work top down, bottom up, or middle out, AppMaster AMB lets you proceed from the step you just completed to the one you want to do next. And, if you are maintaining or redeveloping existing applications, AppMaster Builder lets you focus on only those components that must change.

Build Applications from High-level Specifications

It's often best to begin by defining your application's runtime or target environment. When you select an environment, AMB handles the necessary implementation details when it generates the application. AMB supports the following targets:

Databases
  • SQL (HCO (DB2))
  • IMS
  • VSAM
User Interfaces
  • Batch
  • CICS
  • DLG
  • IMS
  • ISPF

Target One or More Databases

If your application must access more than one kind of database, AMB can generate code to accommodate this. You can also perform prototype testing on multi-target applications.

Prototype Look and Feel

You can next prototype the look and feel of an application so that end users can review it early in the design process. As you create the user interface, you and your end users run the interface - without leaving AppMaster AMB - to ensure that the application user interface meets end user expectations. You can enter data into data entry fields to ensure that they capture all of the required information. Because it is so easy to create, run, and change these prototypes, you can work closely with end users to refine this aspect of an application before you move on to design the underlying details.

Specify Application Logic

AppMaster Builder also simplifies the task of defining an application's processing logic. You can generate online applications from high-level designs using the default logic that AMB produces, or you can tailor the logic to your particular requirements. For example, you can tailor the way that AMB processes database calls, error routines, or other program actions.

You create batch applications using whatever combination of AMB specifications, COBOL syntax, or user-defined logic modules that you prefer. You can combine online and batch programs as you like within a single application.

Automatically Generate Application Code

When you generate an application, the result is consistent, high-quality code, ready to be compiled on the mainframe, or on the PC. You can also generate AMB code directly to an Enterprise Developer project where it is automatically compiled into run-time modules.

Debug Applications

Once you generate an application, you can debug it from either the COBOL or the S-COBOL level, depending on your preferences.

Parent topic: Introducing AppMaster Builder


The AppMaster Builder Tool Set

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The basic AppMaster Builder tool set is:

AppMaster Builder Perspective
This Eclipse perspective provides access to:
Project Explorer
Add and create projects and project objects, which are the components of a working application such as programs, screens or report mock-ups, and data structures, and define the relationships from one object to another. Other tools in the AppMaster Builder tool set are available from here.
Database View Explorer
Add, edit, load, and build IMS, SQL, and VSAM database views.
Team Developer Perspective (Technology Preview)
Provides access to the same functionality as the Project Explorer in the AppMaster Builder perspective plus access to the AMB Endevor Interface.
Screen Painter
Paint character-based screens to access from your application programs.
Online Express
Define logic for your programs by assigning predefined actions to your screen components, mapping data between your screens and databases, defining and qualifying database calls, and adding your own program actions to support specialized requirements.
Program Painter
The Program Painter is a specialized editor in which you can create batch programs, online programs, user rules, and program stubs, using COBOL, S-COBOL, and high-level AMB constructs such as database calls, user interface calls, and Report Writer constructs.
Report Painter
A specialized editor that enables you to create report mock-ups.
Data Structure Editor
Define data structures that you can reuse in your applications.
Customizer/Micro Focus Generator (MFG)
The Customizer enables you to define User Rules that are generated into COBOL code using the Micro Focus Generator (MFG) preprocessor.
Report Generators
Produces a variety of application reports to help you understand how the application works.
Analysis Option
Analyze your code for better understanding of how each project object interrelates with others.
AMB Endevor Interface (Technology Preview)
Enables you to share and synchronize resources between an AMB project and mainframe Endevor datasets.
Parent topic: Introducing AppMaster Builder
Related concepts
Data Structure Editor
Online Express
Program Painter
Screen Painter
Data View Manager
Application Reports
Analysis Option


AppMaster Builder User Areas

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMB requires each user to have his or her own area in which to store generated files. An individual user area consists of a directory named for the user, and a series of subdirectories for the generated files. The existence of a user area defines a user to AMB in that the name of an individual's user area directory is used by AMB as a user ID.

On installation, AMB defines a default parent user area directory, %PUBLIC%\Documents\Micro Focus\Enterprise Developer\AMBWorkArea. You can create alternative parent user area directories if you prefer not to use the default. Individual user area directories are always subdirectories of a defined parent user area directory.

For example, if your parent user area directory is the default, and you have three users - Joe, Bob, and Mary - the user area directory structure would look like this:
%PUBLIC%\Documents\Micro Focus\Enterprise Developer\AMBWorkArea\Joe
                                                               \Bob
                                                               \Mary

For each installation of AMB, you set the user area in the AppMaster Builder preferences. AMB then generates source files to the user area specified, and uses the name of the individual user area directory (AMB user ID) to identify the jobs on the job queue that are owned by that user.

You can create, delete, or clean an individual user area. When you delete an individual user area, AMB removes the entire individual user area directory structure, effectively deleting the user ID as well. If you want to remove all of the generated files in an individual user area without deleting the user ID, use the Clean option instead.

Parent topic: Introducing AppMaster Builder
Related tasks
To create a user area
To delete a user area
To clean a user area
Related reference
User Area Directories


AppMaster Builder Preferences

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The information stored as AppMaster Builder preferences is used as you develop and generate all AMB applications. You set these preferences on a global level, meaning they apply to all applications in the current AMB project. The AppMaster Builder preferences include:

AppMaster Builder
Set your current project and user area directories, enable a workgroup, and optionally specify an Enterprise Developer project in which to compile generated code.
Customization
Select a method for loading and expanding applications, set tooltip options, and set Job Queue options.
Editors
Set options for the Data Structure, Program, and Report Painters.
Environment
Optionally set a database directory and alternate directories for file storage.
International
Set preferences that apply to the language used in your code.
Logging
Enable or disable run-time logging.
Output
Set options for generated code.
Parent topic: Introducing AppMaster Builder
Related tasks
To set AppMaster Builder preferences


AppMaster Builder in Eclipse IDE vs. AppMaster Builder in Mainframe Express IDE

Shows the Eclipse IDE equivalents to Mainframe Express IDE features.
Restriction: This topic applies to Windows environments only.

Application View

The following table shows AppMaster Builder in Mainframe Express IDE features available from the Application View, and their corresponding equivalents and locations in Eclipse.
Important: All actions described in the AppMaster Builder in Enterprise Developer for Eclipse columns assume that the AppMaster Builder perspective is open and active in the Eclipse IDE. To open the AppMaster Builder perspective:
  1. Start Enterprise Developer for Eclipse.
  2. From the Enterprise Developer for Eclipse IDE, click Window > Perspective > Open Perspective > Other.
  3. Select AppMaster Builder; then click OK.
Functionality | AppMaster Builder in Mainframe Express | AppMaster Builder in Enterprise Developer for Eclipse
Project Control |  |
Create New Project | From the Application View, click Admin > Project Data Set > New Project. | From the Eclipse menu, click Admin > Project > Create.
Delete Project | Right-click a project on the Application View tree and select Delete from the context menu. | Click Admin > Project > Delete.
Start Online Express | Double-click an Online Express program on the Application View tree. | Double-click an Online Express program on the Project Explorer.
Set User Preferences | From the Application View, click Options > User Preferences. | From the AppMaster Builder perspective, click AMB preferences page AppMaster Builder preferences page.
Start the Screen Painter | Double-click a screen on the Application View tree. | Double-click a screen on the Project Explorer.
Create a User Area | From the Application View, click Options > User Preferences, Project tab. | From the Eclipse menu, click User > User Area > Create.
Delete a User Area |  | From the Eclipse menu, click User > User Area > Delete.
Clean a User Area |  | From the Eclipse menu, click User > User Area > Clean.
Add an Object | Right-click an Application View tree entry and select Add from the context menu. | Right-click aProject Explorer entry and select Add > objectType from the context menu.
Rename an Object | Right-click an Application View tree entry and select Rename from the context menu. | Right-click a Project Explorer entry and select Rename from the context menu.
Remove an Object | Right-click an Application View tree entry and select Remove from the context menu. | Right-click a Project Explorer entry and select Remove from the context menu.
Start the Program Painter | Select the program on the Application View tree and click Actions > Program Painter. | Double-click a Program Painter program on the Project Explorer.
Start the Analysis Browser | Right-click an Application View tree entry and select Analysis Option > Analysis Browser from the context menu. | To analyze a project, right-click the project on the Project Explorer, and select Analysis Option > Analysis Option for Project. To analyze an application, right-click the application on the Project Explorer, and select Analysis Option > Analysis Option for Application.
Set object parameters | From the Application View, click the object for which you want to set parameters; then select parameters using the field at the top of the desktop. | Right-click an object on the Project Explorer and select Properties from the context menu.
Copy and Add a File | From the Application View, click File > Copy + Add . | Right-click an object on the Project Explorer and select Copy + Add from the context menu.
Start the Object Finder | From the Application View, click File > Object Finder. | Not supported
Find an object in an application | From the Application View, click File > Find Object in Applications. | Not supported
Start APSSRC | From the Application View, click File > APSSRC. | Not supported
Select Multiple Map Mapsets | From the Application View, click Actions > Multiple Map Mapset. | In the Project Explorer, right-click either the project name or a blank area; then select Generate Multiple Map Mapset from the context menu.
Generating |  |
Generate from the Command Line | From the Application View, click Actions > Command Line Generation. | Not supported from the IDE
View Job Queue Listings | From the Application View or the Database View, click Options > Job Queue Listings. | From the AppMaster Builder perspective, click Job Queue Job Queue.
Start AppMaster Builder Server | Starts automatically when you start AppMaster Builder. | Starts automatically when you open the AppMaster Builder perspective. To toggle it on and off from the AppMaster Builder perspective, click Start AppMaster Builder Server Start AppMaster Builder Server or Stop AppMaster Builder Server Stop AppMaster Builder Server.
Generate an application | Right-click an application on the Application View tree, and select Generate > Generate Application. | Right-click an application on the Project Explorer and select Generate Application from the context menu.
Generate all programs | Right-click an application on the Application View tree, and select Generate > Generate All Programs. | All Program Painter programs: Right-click an application on the Project Explorer and select Generate All Programs from the context menu. All Online Express programs: Right-click an application on the Project Explorer and select Generate All Online Express from the context menu.
Generate all screens | Right-click an application on the Application View tree, and select Generate > Generate All Screens. | Right-click an application on the Project Explorer and select Generate All Screens from the context menu.
Generate an Online Express program into an APSPROG member | Select an Online Express program on the Application View tree; then click Actions > Generate Express. | Right-click an Online Express program on the Project Explorer and select Generate Online Express from the context menu.
Generate a data structure | Right-click a data structure on the Application View tree, and select Generate. | Right-click a data structure on the Project Explorer and select Generate Data Structure from the context menu.
Generate one screen | Right-click a screen on the Application View tree, and select Generate. | Right-click a screen on the Project Explorer and select Generate Screen from the context menu.
Editing |  |
Edit Data Structures | Double-click a data structure on the Application View tree. | Double-click a data structure on the Project Explorer.
Edit User Rules | Double-click a user rule on the Application View tree. | Double-click a user rule on the Project Explorer.
Undo new edits | From the Application View, click Edit > Undo New. | Not supported
Redo new edits | From the Application View, click Edit > Redo New. | Not supported
Create Application Edits | From the Application View, click Admin > Application Edit List. | Not supported
Reporting |  |
Generate an Online Express report | Right-click an Online Express program from the Application View and select Report from the context menu. | Right-click an Online Express program on the Project Explorer and select Online Express Report from the context menu.
Generate a Program report | Right-click an Online Express program from the Application View and select Report from the context menu. | Right-click a program on the Project Explorer and select Report from the context menu.
Importing |  |
Import BMS | From the Application View, click Interfaces > Import BMS. | Not supported
Import MFS | From the Application View, click Interfaces > Import MFS. | Not supported
Additional Features |  |
Control Source Code | From the Application View, access the Source Control menu. | Not supported
Manage Workgroup Libraries | From the Application View, click Admin > Manage Workgroup Libraries. | Edit the workgroup definition file using a text editor.
Migrate from APS to AppMaster Builder | From the Application View, click Admin > APS to AMB Migration . | Not supported
Change Admin password | From the Application View, click Admin > Change Admin Password. | From the Eclipse menu, click Admin > Change Admin Password.
Migrate Data Elements | From the Application View, click Admin > Data Element Migration . | Not supported
Start DDI File Utilities | From the Application View, click Admin > DDI File Utilities > Unlock, Restore, Backup, Reorganize. | From the Eclipse menu, click Admin > DDI File Utilities > Unlock, Restore, Backup, Reorganize.
Administer user variables | From the Application View, click Admin > User Variables. | Not supported
Add/Delete/Modify User Menu items | From the Application View, click Admin > User Menu. | Not supported

Database View

The Database View in Enterprise Developer for Eclipse is functionally similar to the Database View available in AppMaster Builder for Mainframe Express. The following table lists exceptions:
Functionality | AppMaster Builder in Mainframe Express | AppMaster Builder in Enterprise Developer for Eclipse
Start Database View | From the AppMaster Builder Desktop, click the Database View tab. | Click the Database View Explorer tab.
Create a database view | In the Database View Manager, click File > New. | In the Database View Explorer, right-click a Database View Files entry and choose Add.
Create new database source files | In the Database View Manager, click File > Load/Build. | In the Database View Explorer, right-click a Source file type node (under IMS Source Files, VSAM Source files, SQL Source files) and choose Add.
Load source files for a database view | In the Database View Manager, click a database view on the list, then click File > Open.Select the source and file, click Load, then click OK. Delete. | In the Database View Explorer, right-click a database view and choose Edit Database View. Select the appropriate radio button and the source to load and choose Load.
Load a workgroup into a database view | From the Application View, click Options > User Preferences. Select Workgroup in the Preferences dialog box. Select a workgroup, then click OK. | From the AppMaster Builder perspective, click AMB preferences page AppMaster Builder preferences page. Specify a workgroup in the Workgroup name field and click OK.
Delete a database target file | In the Database View Manager, double-click the database view that contains the source file you want to delete. Select the file and click Delete. | In the Database View Explorer, right click a target you want to delete and choose Delete.
To delete a source member | In the Database View folder, double-click any database view name. Select the source member you want to delete and click Delete. | In the Database View Explorer, right-click a database view source and select Delete.
Edit a database source file | In the Database View Manager, click File > Load/Build. Click the type of source you want to modify, then click Edit. | In the Database View Explorer, either double-click the database source name and edit the source as necessary, or for a SQL schema, double-click the name in the Database View Explorer and use the SQL Schema dialog box to select or remove SQL table definitions.

Data Element View

The Data Element View is not supported in Enterprise Developer.

Parent topic: Introducing AppMaster Builder
Related information
Mainframe Express Functionality That Works Differently in Enterprise Developer for Eclipse


Developing Applications in the AppMaster Builder Perspective

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: You can also use AppMaster Builder in the Team Developer Perspective; however, some features are not available. See Developing Applications in the Team Developer Perspective for details (technology preview).
  • AppMaster Builder Projects
    Explains the structure of AppMaster Builder projects in Eclipse, and the AMB project objects.
  • Workgroups
    Introduces you to AppMaster Builder Workgroups and explains their use.
  • Screen Painter
    Describes the Screen Painter and its use in creating CICS, IMS or DLG applications.
  • Online Express
    Introduces you to Online Express and explains how to use it to define program processing logic.
  • Program Painter
    Describes the Program Painter, which is a tool you can use to create batch or online programs, stubs, and User Rules.
  • Customizer/Micro Focus Generator (MFG)
    Describes the preprocessor that processes AppMaster Builder Rule and User Rule definitions.
  • Data View Manager
    Explains the use of the Data View Manager to import your database source.
  • Data Structure Editor
    Describes the use of the Data Strcuture Editor to create reusable data structures.
  • Report Painter
    Describes Report Painter concepts, including information on using report mock-ups, and information on coding online and batch programs using the Program Painter.
  • Application Reports
    Describes the default and custom reports AppMaster Builder can generate about your applications.
  • Analysis Option
    Explains what Analysis Option provides and how to use it.
Parent topic: AppMaster Builder
Related concepts
Developing Applications in the Team Developer Perspective (Technology Preview)


AppMaster Builder Projects

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You use the AppMaster Builder Project Explorer to create and manage your AMB projects, which are made up of a collection of objects. These objects can define an application of whatever size scope you require from a single-order status database inquiry to an entire order inventory system.

  • Object Types
  • Project Explorer Tree View
  • Object Properties
Parent topic: Developing Applications in the AppMaster Builder Perspective


Object Types

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

An AMB project can contain one or more of each of the following types of objects:

Applications
An application object serves as a container for all of the objects associated with the application.
Programs
A program object contains one program, either created in Online Express or in the Program Painter.
Screens
A screen object contains one screen, created in the Screen Painter.
Database views
A Data View defines the records in your database that are available to the program or programs in your application.
Data structures
A data structure is usually a global object that contains structures written in the Data Editor Structure format.
User rules
A user rule object defines a rule coded using MFG structures, COBOL, S-COBOL, or a combination of the three.
Program stubs
A program stub is defined as part of an application but is not a full program. You can call a stub from another program, and it is available to all programs in the application of which it is a part. Stubs do not get generated as programs.
Parent topic: AppMaster Builder Projects
Related tasks
To add an existing object to an application
To remove or delete an object
To set program properties
To set application properties
To set screen, data structure, and user rule properties
To rename an object


Project Explorer Tree View

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Use the tree view in the AppMaster Builder perspective Project Explorer tab to view an inventory of AMB projects and objects, and to navigate from there to the other AMB tools where you develop each object. As you complete individual programs, screens, or the application as a whole, you return to the Project Explorer to generate them into executable COBOL source or to generate reports on the progress of your work.

Tree View Organization

AMB project objects are organized hierarchically on the Project Explorer tree view as follows:
AppMaster Builder Perspective Object Hierarchy

For example, the following shows a typical Project Explorer tree view:
Tree View

Filtering

You can limit the types and names of program objects that show on the Project Explorer using the Filter Programs feature. When using Workgroups, you can also set a filter to show only local programs that match specific type and/or name. See To filter programs for more information.

Parent topic: AppMaster Builder Projects
Related tasks
To create an application
To add an existing object to an application
To remove or delete an object
To copy an object


Object Properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can specify properties for an entire application, or for most individual objects. Some of these properties augment your AppMaster Builder properties, and some override them.

Application Properties
Here you set options specific to the application, such as the user interface and database it uses.

You can also optionally specify or create an Enterprise Developer COBOL project, other than the COBOL project specified in AppMaster Builder preferences, in which to compile generated AMB code.

For information on each property setting, see the Application - Resource and AppMaster Builder reference topics.

Program Properties
Here you set the type of program, and program coding and output options specific to the program. See the Program - Resource reference topic for information on each setting.
Screen Properties
Specify the type of screen - Input, Output, or InputOutput.
Data Structure Properties
Specifiy a program location for the data structure - Linkage, Commarea, or Working-Storage.
User Rule Properties
Specify a program location in which to insert the user rule. You can choose from several pre-defined locations.
Parent topic: AppMaster Builder Projects
Related tasks
To set AppMaster Builder preferences
Related reference
Application - Resource
AppMaster Builder
Program - Resource
Screen - General
User Rule - General
Data Structure - General


Workgroups

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The AppMaster Builder Workgroup feature enables you to use AMB objects located outside of your current AMB project subdirectories, including objects located in AMB project subdirectories associated with a project other than the current project, and objects located in mainframe PDSs. You create and modify objects in the current project for the purpose of building programs and applications. When you associate a workgroup with the current project, AppMaster Builder gives you access to the objects located in the directories and PDSs defined in the workgroup. You can view the objects from AMB and use them when you generate programs, screens, databases, and applications. You cannot edit or modify workgroup objects located outside of your current project subdirectories.

Workgroups enable you to:

  • Keep mainframe files on the mainframe and still use them to build AMB applications.
  • Use a single application object in multiple projects without having to maintain it in multiple locations.
  • Group and access objects and source code according to development stages. For example, one workgroup might point to a set of production files and another to a set of test files.

A workgroup consists of a workgroup library file that contains a list of one or more of the following:

  • AMB project subdirectories for the current project (local)
  • AMB project subdirectories located on a local area network
  • Mainframe PDSs, including but not limited to APS projects
  • A combination of the above items
  • Data view sources

Workgroups function in a similar manner to path specifications. The current project subdirectories are searched first, followed by the project subdirectories and mainframe PDSs specified in the workgroup in the order that they are listed in the workgroup library file. Objects that are stored in the directories and PDSs specified in the workgroup are all available to AMB. When searching a workgroup for a specific object, AMB uses the first matching object it finds. If a workgroup consists of a combination of local and LAN project subdirectories and mainframe PDSs, all local and LAN directories are searched before the PDSs are searched. A workgroup can contain up to nine AMB project locations for PC/LAN locations, and nine mainframe project locations.

  • Specifying a Workgroup
  • Using Workgroup Objects
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
Managing Workgroups
Related tasks
To create a workgroup
To modify a workgroup
Related reference
Workgroup dialog box


Specifying a Workgroup

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Your AppMaster Builder administrator creates and maintains workgroups. All workgroups are available to all AMB users. Each user can specify one workgroup at a time. The Workgroup dialog box, available through the AppMaster Builder page of your AppMaster Builder preferences shows you all folders and project directories or PDSs available in a workgroup.

The Workgroup path field shows the full path to the directory containing workgroup library files as defined by your AMB administrator.

The Workgroup name list shows the names of the workgroup libraries contained in that directory.

The Folders list shows you all of the project subdirectories defined in the selected workgroup library. Only the subdirectories with defined workgroup locations appear on this list.

The Locations list shows which paths and/or PDSs are available for the project subdirectory selected on the Project Folders list. The order in which the entries appear on the Locations list dictates the search order.

Parent topic: Workgroups
Related tasks
To specify a workgroup


Using Workgroup Objects

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To access a workgroup object, you must add it to the Project Explorer. When you add an object, AppMaster Builder searches the workgroup for a matching object to link to. If it does not find the object in your workgroup, it creates a new object in the current project.

if you double-click an object in the Project Explorer and AppMaster Builder doesn't find it in the local project subdirectories or in any of the workgroup-specified directories or PDSs, it creates a new object.

When you view a workgroup object from one of the AppMaster Builder painters or the editor, AMB makes a copy of the object to load into the painter or editor. Both the Screen Painter and Online Express warn you when you are viewing a workgroup object that you cannot save changes should you make any. In the editor, you view workgroup objects in browse mode, meaning you cannot edit the files.

When you view a workgroup object in an AppMaster Builder painter, the location of the object appears in the title bar. You can expect that the location reported is the first instance of the object found by AMB based on the sequential order of the folders or PDSs listed in the workgroup library you specify in your AppMaster Builder preferences.

Note:
  • For the AMB workgroup feature to properly access your mainframe, you must have the command-line interface for the Mainframe Access feature configured and running properly on your PC. For more information, see Configuration.
  • If your object file is located in a mainframe PDS, the location reported on the title bar is a temporary location on your PC. AMB temporarily downloads mainframe workgroup files for viewing.
Parent topic: Workgroups
Related concepts
Configuration
Related tasks
To set AppMaster Builder preferences


Screen Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Screen Painter enables you to paint character-based screens that are intuitive and easy to use. You first paint the fields, and then specify field names, field attribute and edit criteria, and generation parameters. The AMB Generators retrieve this screen information from your project to produce native screen source code. Using the Screen Painter, you can:

  • Define screen attributes
  • Design a screen
  • Paint fields
  • Test screen behavior
  • Create an application model to prototype screens
  • Set generation options
  • Defining Screen Attributes
  • Designing a Screen
  • Painting Fields
  • Defining Field Edits
  • Testing Screen Behavior
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
The AppMaster Builder Tool Set


Defining Screen Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Screen Generator takes your designs from the Screen Painter and generates native map definitions. You can tailor your screen for your environment by selecting options that:

  • Print expanded assembler rules.
  • Retain field names as assembler labels.
  • Unprotect I/O fields for prototyping.
  • Modify I/O field attributes at run time.
  • Create a system message field.
  • Change how text fields display at run time.
  • Tailor your screen for the CICS, IMS DC, or Dialog target environment.
  • CICS
  • IMS
  • DLG
Parent topic: Screen Painter
Related tasks
To define screen attributes


CICS

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

For the CICS environment, you can select options that:

  • Generate an assembler END statement
  • Define a unique transaction ID
  • Specify a mapset name
  • Indicate the starting line of the map on the physical screen
Parent topic: Defining Screen Attributes


IMS

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

For the IMS environment, you can select options that:

  • Generate an assembler END statement
  • Specify standard device characters for different terminals and printers
  • Provide a field for cursor feedback
  • Generate MFS code for logical page requests
  • Define MFS system literals
  • Rearrange the order of input message fields (MID/MOD)
  • Assign trancodes, IMS commands, or logical paging commands to PF keys
  • Construct MFS trancodes
Parent topic: Defining Screen Attributes


DLG

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

For the Dialog environment, you can select options that:

  • Generate native definition statements to override ISPF defaults.
  • Provide tutorial help panels.
  • Control PF key processing.
Parent topic: Defining Screen Attributes


Designing a Screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Screen Painter provides editing and design options to help you paint the screen. For example, you can specify where the Command field automatically appears on your screen, and can determine whether your text appears in upper case, lower case, or both. You can display a screen grid to help you align fields as you place them on the screen.

You can center fields within a designated workspace, left or right justify them, or top or bottom justify them. For example, you can left justify a row of entry fields and then center align the corresponding text to the entry field.

Use selections from the Options menu to help you design the screen.

Parent topic: Screen Painter
Related tasks
To define screen attributes
To paint a screen


Painting Fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

A character screen consists of fields and blocks of fields that you paint on a blank screen. You can paint two types of fields:

  • Input/Output (I/O) fields - These enable end users to view, add, update, and delete information. I/O fields can have as many characters as can fit on one row of the screen.
  • Text fields - These display text, such as prompts for I/O fields, column headings, screen headings, section headings, and explanatory text.

Use the following guidelines as you paint your screens:

  • Maximum 500 fields per screen.
  • Turn on sticky mode to paint several fields at one time.
  • Include repeated record blocks to accept or display multiple occurrences of one or more records, repeating a block of one or more source rows as many times as necessary. A repeated record block generates a table in Working-Storage.
  • Column 1 in the generated screen definition is reserved for attribute bytes.
  • When you create a static text field on a dialog screen:
    • Paint the field as it should appear at run time.
    • Include the appropriate number of ampersands (&). The Screen Generator generates two ampersands for every one you paint. Once the screen is online, DLG deletes the extra ampersands.
    • Leave as many spaces at the right of the row as there are ampersands in the row.
  • Field Attributes
  • Defining Data Representation
  • Arranging Fields
  • Duplicating Fields
  • Painting Program Fields
Parent topic: Screen Painter
Related tasks
To paint a screen
To use sticky mode
To create repeated record blocks
To move repeated record blocks
To change repeated record blocks
To delete repeated record blocks
To delete a field in a repeated record block
To modify attributes for a field in a record block


Field Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can assign field attributes, such as field protection, brightness, cursor positioning, and color, to both I/O and text fields. The Screen Painter supports full and extended 3270 attribute capabilities, including:

  • Color
  • Underline, blinking, and reverse video features
  • Cursor positioning when the screen appears to the end user
  • Bright and dark intensity
  • Numeric keyboard locking
  • Field protection
  • Assignment of an initial value
  • Light pen sensitivity

AMB assigns default attribute values to each field. You can quickly override the default values by entering or selecting the values you want.

  • Rules for Defining Field Attributes
  • CICS Data Transmission
Parent topic: Painting Fields
Related tasks
To define screen attributes
To define field attributes


Rules for Defining Field Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Follow these rules when defining field attributes:

  • When assigning names to screen fields:
    • If you give a screen field the same name as its corresponding database field, Online Express automatically maps the relationship for you, prefixing the field name with the screen name; otherwise you must map the screen field to the database in your program.
    • If the same field appears on several screens, give it the same name on each screen.
  • When you use field edits with an update program under IMS, always set the Modified Data Tag to On; otherwise, results are unpredictable. Under CICS, if you set the tag to Off, you must set some variables in the CTRL file; otherwise, results are unpredictable. See Control (CNTL) Files for more information.
  • Turning the numeric keyboard locking attribute on does not ensure only numeric data is entered because it is terminal dependent. To ensure that the end user enters only numbers, specify so in Field Edits.
  • The Modify Extended Attributes attribute works in conjunction with the EXATTR MODIFBLE parameter on the Screen Generation Parameters window. If you set that parameter to F(alse), AppMaster Builder ignores the Modify attribute. If you set the parameter to T(rue), AMB searches your screen to find which fields have the Modify attribute on.
  • If you change Initial Cursor positioning by setting a new field to Yes, you must change the previous "yes" field to No.
  • Be default, Online Express positions the cursor on the function field for the non-repeated block data. To override the default with the field you select here, blank out the Position Cursor on Field field with spaces on the Online Express Program Definition window.
  • The Ruled Line drop-down list enables you to control the placement of lines around a field. You can either select Left, Right, Under, and Over from the drop-down list, or you can specify a hex value that represents one or more lines. The following table shows you the equivalent of each hex value:
    Hex Value | Under | Right | Over | Left | Equivalent to...
    00 | spaces
    01 | X | U
    02 | X | R
    03 | X | X
    04 | X | O
    05 | X | X
    06 | X | X
    07 | X | X | X
    08 | X | R
    09 | X | X
    0A | X | X
    0B | X | X | X
    0C | X | X
    0D | X | X | X
    0E | X | X | X
    0F | X | X | X | X | B
Parent topic: Field Attributes
Related tasks
To define field attributes
Related reference
Control (CNTL) Files


CICS Data Transmission

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Under normal CICS screen processing, the MDT (Modified Data Tag) field attribute must be turned on for each field when you use Field Edits with an updateable program. This causes the end user workstation or terminal to always send all field data, modified or not, to the program.

Transmission of data is more efficient if MDT is turned off, but then only the data modified by the end user is returned to the program, and the unmodified data is lost, which can be undesirable.

During processing, AMB returns the modified data to the program, and retains the unmodified data in temporary storage, returning it to the program after the modified data is returned.

A rule in APCICSIN named $TP-MDTOFF-BUILD-QUEUENAME builds the temporary storage queue name used to store the screen records. You can change this rule to build a name that conforms to your site standards.

Also contained in APCICSIN are the following error processing rules that execute when there is an error in reading, writing, or deleting your screen records in temporary storage.

$TP-MDTOFF-READQ-TS-ERROR
$TP-MDTOFF-WRITEQ-TS-ERROR
$TP-MDTOFF-DELETEQ-TS-ERROR

As shipped, these rules generate a CICS-SEND-TEXT call to display appropriate error messages, and a TERM to terminate the program. You can change these rules to conform to your shop standards.

Parent topic: Field Attributes
Related tasks
To define field attributes
To turn off the MDT tag


Defining Data Representation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Field edits let you define the display and storage characteristics for I/O fields. Field edits can validate input data and format that data for storage and output. You can assign characteristics, such as an internal picture, output picture, edit mask, or date and time format. Or, you can test for specific values or a range of values.

The internal data representation specifies storage characteristics for data in a field. Input and output data representations let you specify the type of data that users can enter or that a field can display. For example, an input data representation for a field may permit a user to enter numbers from 1 to 1,000; an output data representation may require that data display a dollar sign, decimal point, and two places following the decimal point.

You can also code your own edit routines and apply them to multiple screens across any number of application systems. Field edits ensure that entries match specified definitions. Some fields, however, require specialized testing. For example, if a field has alternate formats, no single field edit can confirm the validity of all possible entries. In such a case, you can write an application edit that verifies all legal entries. Or, you can select a predefined edit from a centralized application edit listing.

You can instruct the screen to bypass all input edits on the screen, or bypass input edits for a single row occurrence in a repeated record block. You do so by defining bypass conditions for one field per screen; if any of those conditions occur, AMB bypasses input field edits for the entire screen. If the field is in a repeated record block, AMB bypasses edits for all fields in that row occurrence only.

Parent topic: Painting Fields
Related concepts
Defining Field Edits
Related tasks
To define field attributes


Arranging Fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Simple techniques let you quickly resize, align, reposition, and space fields at any time. For example, you can left justify a row of entry fields, left justify its corresponding text, and then vertically align the text to the center of the entry field.

Parent topic: Painting Fields
Related tasks
To align screen fields
To select multiple fields
To delete screen fields


Duplicating Fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can copy and paste fields from one screen to another or on a single screen, and you can duplicate fields on a single screen.

When you copy a field, the following attributes are copied to the resulting field:

  • name
  • length
  • position
  • initial value

When you paste a field, the Screen Painter places the field one row down and two columns over from its original position. You can reposition the field by dragging it to another location on the screen.

You can duplicate one or more fields on a single screen. The duplication process preserves the size, attributes, and field edits for each field selected. Be sure to rename duplicated fields to avoid having more than one field with the same name. You can reposition any field by dragging it to another location on the screen.

Parent topic: Painting Fields
Related tasks
To duplicate screen fields


Painting Program Fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

If you want the end user to execute program functions by entering a function code on the screen, paint function code fields on your screen. You can then program these fields using Online Express. If your screen displays both single and multiple occurrences of data, you might need two function fields as follows:

  • A primary function field for updating the single occurrence record
  • A row function field, if you must update the repeated record block rows

For your program to execute database functions, your screen may need fields for savekey storage. Generally, you paint savekey storage fields in Online Express.

Parent topic: Painting Fields
Related tasks
To paint a screen
To define a Savekey


Defining Field Edits

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The screen fields you paint in the Screen Painter can be:

  • Character
  • Numeric
  • Date or time

Depending on the type of field you create, you assign field edits that define the data representations. AppMaster Builder supports the following field edits:

  • Internal field edit values - Specify the COBOL picture characteristics for storing data the end user enters. These include:
    • Alphabetic, character, or numeric data type
    • Internal length
    • Binary or packed format
    • Sign specification
    • Right justification
  • Input field edit values - Specify format and data requirements that the end user must adhere to when entering data into the field. These include:
    • Required data
    • Input mask
    • Julian, Gregorian, system, or user-defined date type
    • User-defined or system time type
    • Minimum/maximum input requirements
    • Testing for blank spaces or special characters
    • Testing for numeric data
    • Testing for specific values
    • Zero-fill when blank
  • Output field edit values - Specify the format requirements for displaying the data. These include:
    • Output mask
    • Output picture
    • Julian, Gregorian, system, or user-defined date type
    • User-defined or system time type
    • Right justification
    • Commas
    • Zero suppression
    • Floating, leading, and trailing symbols
  • Values or conversion values - Ensure only certain values are entered. You can test for:
    • A specific value or range of values for input data
    • Conversion values for input and output data representation to define how data is stored and converted for output
  • Application edit routines - Specify additional edits or tests for input or output data. Edit routines can be paragraphs, subprograms, or Customizer rules that you create. Or, you can select a predefined application edit routine from a centralized listing of edit routines maintained by your AppMaster Builder Administrator.
  • Edit Masks
  • Error Processing Messages
  • Values and Conversions
  • Fields and Flags for Edit Routines
Parent topic: Screen Painter
Related concepts
Defining Data Representation
Related tasks
To define field edits
To delete field edits


Edit Masks

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMB verifies an edit mask depending on whether the field has optional characters in an edit mask, as follows:

Optional Mask Chars | Verification
No | Left to right scan
Yes, on the left | Left to right scan
Yes, on the right | Right to left scan

To reverse commas and decimal points in the output picture of numeric fields, such as ZZ.ZZZ.ZZ9,99, modify the CNTL(APSPROJ) file in one of the following ways, and then compile the screen and program:

  • Code the following assignment statements in the APSPROJ control file, where membername is the USERMACS member name that contains the $TP-SPECIAL-NAMES rule definition. AMB includes the member for you. The $TP-SPECIAL-NAMES rule generates the DECIMAL-POINT-IS-COMMA statement:
    % &FE-DECIMAL-POINT-IS-COMMA = "YES"
% &FE-TP-SPECIAL-NAMES-MACMBR = "TPSPEC"|"membername"
  • Then, copy TPSPEC from &SSMAPS..CNTL to &SSMDSN..USERMACS. Modify the $TP-SPECIAL-NAMES rule as desired to generate statements in the SPECIAL-NAMES paragraph.
  • Code the following statement in the APSPROJ control file. The DC target epilogue rule generates the DECIMAL-POINT-IS-COMMA statement.
    % &FE-DECIMAL-POINT-IS-COMMA = "YES"
Parent topic: Defining Field Edits
Related reference
Control (CNTL) Files
APSPROJ


Error Processing Messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Code default error messages to display when the end user enters invalid data or neglects to enter data that is required. You can code these messages for each field, or globally for all fields. A field-specific message overrides a global message.

When users fail to enter data correctly, you can display an error message that explains the problem. You can define two error messages, one for when the end user enters invalid data, and one for when the end user neglects to enter data that is required.

These can be global messages that display for all fields and controls, or specific messages that display for individual controls and fields. Messages defined for a specific control or field override the global messages. You can also define conditions for bypassing input edits under certain conditions.

Parent topic: Defining Field Edits
Related tasks
To define a field-specific error message
To define a global error message


Values and Conversions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can set your field edits to check information entered into your screen by an end user to ensure that only certain values are entered or accepted. This includes testing for a specific value or range of values, or testing for conversion values for the input and output data representation. This enables you to define how data is stored and converted for output.

  • Specifying Values
  • Specifying Conversions
Parent topic: Defining Field Edits


Specifying Values

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

value
lowvalue TO|THRU
          highvalue
lowvalue UP
highvalue DOWN

General Rules:

  1. Separate each entry with a comma
  2. Do not code commas in an entry
  3. Ensure that the value length meets the restrictions of the International Picture Format
  4. Use negative values only if the internal data representation is signed
  5. Use decimals only if the internal data representation includes a decimal

Example:

1000 to 30000, 50 down
NORTH, SOUTH, EAST, WEST
25.5 to 35.5, 45.5 to 55.5, 100
-10 to 25, 50.5 up
Parent topic: Values and Conversions


Specifying Conversions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

(input1,
          input2, ..., inputN,
          I=internalval,
          O=outputval)

General Rules:

Follow these rules when you specify conversions:

  1. Separate each entry with a comma
  2. Code the internal storage conversion format in internalvalue
  3. Code the output display in outputvalue
  4. Ensure that the internalvalue and outputvalue are valid input data

Example:

The entry:

(ja, jan, i=1, o=January)

Means the end user can enter ja or jan. AMB converts and stores the ja or jan as 1. AMB displays the output as:

January
Parent topic: Values and Conversions


Fields and Flags for Edit Routines

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can pass a screen field or error flag as an argument to an error routine by prefixing the name of the field or flag with the screen name and a hyphen.

You can interrogate the following AMB-generated flags and data fields to determine input data errors.

APS-EDITS-PASSED | Flag that AMB sets to T(rue) if there are no input errors and F(alse) if there are
APS-EDIT-ERRORS-CTR | Data field containing the number of screen fields in error
screenname-fieldname-FLAG | Flag that AMB sets to T(rue) if an error occurs and F(alse) if not

You can use the following AMB-generated fields to code your application edit routines. The column Before / After indicates whether the routine executes before or after the name and format. The field edits determine which field to reference.

Input/ Output | Before/After | Field Name | Description
Input | After | Screenname-fieldname. | Internal picture was updated by any previous field edits.
Input | Before | Screenname-fieldname-INPT. | Data field containing any invalid data entered by the end user. Edits have not been performed; data is in screen input format. Field length is field length painted on the screen; definition is PIC X.
Output | After | Screenname-fieldname-EDIT. | Data was moved to -EDIT by previous output edits. Data may contain special symbols. Default length is field length painted on the screen; definition is PIC X.
Output | Before | Screenname-fieldname. | Data was not processed by previous output edits and is still in the internal format. Data in this field moves to the -EDIT field when an output format is specified. Default length is field length painted on the screen; definition is PIC X.
Either | Either | (APS-ROW-SUB) | This data field contains the row number being processed for fields in a repeated block, or in a list box or combination box.
Either | Either | APS-EDIT-MESSAGE | Data field that lets you display an error message in addition to any you defined in the field edits for the field. Move a literal or data name containing the text into this field.
Either | Either | Screenname-fieldname-LEN | For CICS only. Contains the length of the field; definition is PIC X.
Either | Either | Screenname-fieldname-ATTR | For CICS only. Contains the attribute values assigned to the field; definition is PIC X.

AppMaster Builder processes input data from the screenname-fieldname-INPT field. After the data passes the input edits, the data moves to screenname-fieldname and takes on the characteristics of the internal picture. For output, the data moves to the screenname-fieldname-EDIT field and takes on the characteristics of the output format specifications.

Application edit routines execute for a field whether the data passes or fails field edits, unless you set various switches in the APFEIN control file. To indicate an error in an application edit routine, move T to screenname-fieldname-FLAG. This tells AMB to execute error processing; you can display an additional error message from the APS-EDIT-MESSAGE field.

Note: Do not code database calls in application edit routines.
Parent topic: Defining Field Edits
Related reference
Control (CNTL) Files
APFEIN


Testing Screen Behavior

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Once you paint a screen, you can test it to verify that it satisfies end user requirements. With the Test option, you can test the behavior of the screen and its fields. If you identify a problem or an incorrect action, you can deactivate the test and fix the problem immediately.

You can view the behavior of your screen at any time in the design process by entering mock data into the entry fields or practicing cursor movement by tabbing through your screen.

Parent topic: Screen Painter
Related tasks
To test screens and fields


Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You complete your character-based application by defining its program processing logic using Online Express, a menu-driven painter with a graphical user interface. Online Express references the information that you have specified in the AppMaster Builder painters, and prompts you to define the processing logic for those specifications. You do the following to complete your application.

  • Select the events for executing actions

    You can choose whether the end user executes actions by entering a value in a function field or pressing a function key. In addition, Online Express provides locations in your generated program - known as screen events - where you can execute actions during program execution. For example, you can perform a custom routine each time a program is invoked, or before displaying data on the screen.

  • Select predefined program actions, or write custom actions

    Online Express provides predefined actions - including database read and write actions, and teleprocessing actions - that you can assign to your program. In addition, you can write and execute custom actions to supplement or override the predefined actions.

  • Map screen fields to your database

    Online Express automatically displays all screen fields that you defined on your program screen so that you can map them to the appropriate fields or columns in your database.

  • Define database access

    For each Query, Update, Add, and Delete action that you select, you must define one or more database calls that specify which record or records to read, and which database actions to perform on them - such as Obtain, Modify, Store, and Erase. Online Express predefines these database actions for you; you simply select the ones you need.

  • Customize the database calls

    You can modify and supplement the default processing logic of database calls as follows:

    • Add your own source code at events
    • Override the default error processing of database calls
    • Define savekey storage. You define savekey storage area(s) to store record key values during program execution if your program must do any of the following
    • Update records with the Update, Add, and Delete actions.
    • Obtain records sequentially with the Next action
    • Display repeated record blocks that the end user can scroll with the Forward and Backward actions.
    • Re-read repeated record blocks so that the end user can update and delete them with the Modify and Erase actions.
  • Define Commarea storage

    You use a program Commarea to store any data that your program passes between programs.

Before you access Online Express, be sure you have:

  • Listed the components of your application in the Project Explorer.
  • Painted your program screen in the Screen Painter.
  • Created your database definition in the Data View Manager.
  • Events
  • Actions
  • Field Mapping
  • Database Access
  • Writing Custom Logic
  • Commarea and Savekey Storage
  • Control Points
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
The AppMaster Builder Tool Set
Related tasks
To start Online Express


Events

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Online Express provides events at which to execute actions. Some events occur when the end user does things such as placing the cursor in an entry field. Other events occur at specific locations in the program. For any event, you can assign predefined actions, write and execute custom actions, or both. Writing custom actions at events occurring in the program lets you supplement or override the default program logic that Online Express generates. These events let you add logic at such program locations as:

  • Upon program invocation
  • Before sending the screen
  • Before evaluating field actions
  • Before and after moving records between the database and the screen
  • Before transferring to another program
  • Before terminating the program
  • Other locations, depending on which actions you define for your program

In addition, you can add processing logic at events that occur before and after database calls.

Because the design and functionality of many programs differ, you will often see a different subset of events from program to program. To view the events in your program, you display the events for your fields or controls in the Action/Event Editor. In addition, you can look in your generated program source to see where the events occur; Online Express generates comments in your program to identify them.

Parent topic: Online Express
Related tasks
To assign actions to screen events


Actions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can customize your actions by providing your own code to execute at an event, or you can choose from one of several reserved actions provided by AppMaster Builder.

Predefined Actions

Online Express provides predefined actions you can customize to execute specific code or a reserved action. You specify what code is executed by providing each with an argument. The available actions are:

Call
Calls a subroutine or, for a CICS application, performs a CICS LINK. Provide a program name as its argument.
Global Code
Executes code that is available for any program of an application. It can consist of any procedural source code and paragraphs that the code performs. Entering code into a Global Code action automatically makes it available to other program within the application.
Local Code
Executes code that you write specifically for the current program. It can consist of any procedural source code, paragraphs that the code performs, and Data Division source code for the code.
User Rule
Executes the logic in a user rule. Provide the name of a user rule as its argument.
Perform
Executes a PERFORM statement. Provide a paragraph name as its argument.
Reserved
Executes one of several reserved actions you can specify as its argument. See the section Reserved Actions below.
XCTL
Transfers execution to another program and terminates the current program. Provide a program name for its argument.
MSG-SW
IMS only. Schedules a new program; optionally you can pass a character screen record or other data record to the program. Provide a transaction ID, program name, or data name for its argument.
SEND
Transmits an input/output screen. Provide a screen name with its appropriate arguments as its argument.
Alias

Reserved Actions

Online Express provides predefined action logic that you can assign to your program. These actions include database read and write actions, and teleprocessing actions. You simply select the ones that you need; Online Express generates default processing logic. For many of these, you supply an argument that enables you to customize the

The Reserved action enables you to specify one of several reserved actions that execute predefined logic. The reserved actions are:

Add
Stores records in your database.
Clear
Moves low-values to all entry fields and clears all controls. There is one exception: for non-CICS applications, Clear moves spaces or low-values, depending on which option you select on the Express Generation Options window - either Clear Screen with Spaces or Clear Screen with Low Values.
Delete
Erases records in your database.
Next
Retrieves the next sequential record and displays its data; not applicable to SQL.
Query
Obtains one or more records and displays them on the screen.
Refresh
Re-reads the database when the end user executes any database write function on one or more repeated record block rows, and re-displays the record block to reflect the database updates.
Term
Terminates the program.
Update
Modifies records in your database.
Forward
Pages forward through a repeated record block in a character application.
Backward
Pages backward through a repeated record block in a character screen.

All of these actions can be specified in Online Express as an argument for the Reserved database action.

Parent topic: Online Express
Related tasks
To assign actions to screen events


Field Mapping

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In Online Express, you can map your screen fields to database or Working-Storage fields. You can define these mappings as:

One-way
Input only or output only; moving information from a screen field to a Working-Storage or database field or a database or Working-Storage field to a screen field.
Two-way
Input/output; moving information between a Working-Storage or database field and a screen field. This is the default.

You can define these mappings manually, or, if your screen fields and their corresponding database or Working-Storage fields have identical names, you can set Online Express to automatically map the fields. If a database field exists in multiple database records, you can qualify that field to indicate which record it belongs to.

Using the Field Mapping feature in Online Express, you can also create Working-Storage fields or specify existing Working-Storage fields to which you can map your screen fields. When specifying an existing field that exists in multiple database records, you must qualify that field to indicate which record it belongs to.

Parent topic: Online Express
Related tasks
To map screen fields in Online Express
To create Working-Storage fields in Online Express


Database Access

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

While Online Express let you completely define database calls without having to code them, you can also extend and customize those calls to suit your needs with any of the following techniques:

  • Execute a predefined call at an Online Express-provided event
  • Execute a customized call at an event or anywhere else that you can perform a paragraph
  • Define nested loop calls
  • Execute multiple database actions with one control action.
  • Override status codes and error messages
  • Call 01 assigns the Obtain database action and selects Default for the Program Function field on the Attributes window.
  • Call 02 assigns the Store database action and selects Query for the Program Function field so that Query also executes this Store call.

You could then customize the Store call with user-defined logic.

  • Define the Call
  • Execute DB Calls at Events
  • Coding Nested Loops
  • Executing Multiple Database Actions
  • Qualifying VSAM Multiple-Field Keys
  • Overriding Error Processing
Parent topic: Online Express


Define the Call

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

When you create a database call, the first thing you need to do is define the call as a query, join, union, or subselect clause, which further defines qualify a query, join, or union call but is defined as a separate call. You can also define a Path call to access parent and child records.

Query
  • A non-loop query can Obtain, Modify, Erase, and/or Store information
  • A loop query can Obtain and Loop on information
Join
These can Obtain and Loop on information. You can also specify a correlation name prefix for each table.
Union
These can Obtain and Loop on information. First, define the first Select clause for the first table. You define the subsequent Select clause(s) after you fully define the first one.
Subselect
When you define a Subselect call, you choose the action based on the type of call you are further defining.
Path
To define this type of call, you first specify Position only, or specify Position and Loop. Then, for child records, select one or more: Obtain, Modify, Erase, Store. For example, to position on the parent record and loop on its child, specify the Position and Loop actions for parent record, and the Obtain action for the child. You can also specify the Modify, Erase, and Store actions for the child record if you want the user to be able to perform those actions against it.
Parent topic: Database Access
Related tasks
To customize database calls in Online Express
To define a VSAM call in Online Express
To define an SQL call in Online Express
To define an explicit Join specification


Execute DB Calls at Events

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Typically, you define calls that execute at an event. You can also define calls that execute anywhere that you can perform a paragraph.

For example, you might want to store in a log record the error messages that end users receive when querying a customer order record. To do this, you would follow this procedure:

  1. First, you define a call that stores the log record.
  2. Then, on the Attributes dialog box for the call, you select the *User value for the Program Function field. The default name of the paragraph to which Online Express writes the user call is in the Paragraph Name field on the Attributes dialog box. You can override the default name.
  3. Next, you would execute the paragraph at the Post-Screen-Read event on the Action/Event Editor for your Screen control name.
  4. Then, you would write and execute custom code at the After Access event on the DB Call Tailoring Editor to move the error messages to the log record.

The following figure shows what the completed call might look like on the Database Access Summary window.

Figure 1. Executing a DB Call as a Paragraph
Executing a DB Call as a Paragraph

When performing a User call from an input edit, first perform the default AMB-generated paragraph, PX-INIT-PARAGRAPH, which initializes several AMB input edit flags. These flags include:

OK-TO-PROCEED
APS-EDIT-MESSAGE
APS-EDIT-ERROR-FLG
APS-EDITS-PASSED
APS-EDIT-CTR
APS-EDIT-ALL-OK
Parent topic: Database Access
Related tasks
To customize database calls in Online Express
To define a VSAM call in Online Express
To define an SQL call in Online Express
To define an explicit Join specification


Coding Nested Loops

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You use nested loops to obtain multiple occurrences of multiple records. Loops that are not nested obtain multiple occurrences of a single record. You can map any loop records to repeated record blocks on your screen, or you can loop on records to calculate field totals and display just the calculation results.

When you define two loop calls in a program, the first loop is an outer loop, and the second loop is an inner (nested) loop. The nested loop executes repeatedly each time that the outer loop executes, and obtains all records that satisfy the outer loop record key. For example, you might want to loop on all order records of a particular customer, and loop on all detail records of all the order records.

You also might want to loop on a record to obtain a certain record occurrence that you loop on again, and display just the second loop records. For example, if your program must display all items to be included in the next shipment to a certain customer, you first loop on all outstanding orders for the customer to determine which order ships next. You then loop on that order to obtain all its detail records.

To indicate that the inner loop is nested within the outer loop, Online Express assigns a default nesting level value of 1 to it on the Attributes dialog box. The outer loop nesting level is 0, indicating that it is not nested.

When you define more than two loops, each loop is nested within the previous loop. That is, the second loop is nested within the first, and the third loop is nested within the second. The default nesting level of the third loop is 2. You can define as many nested loops in your program as you need.

  • Nested Loop Example
  • Overriding Nesting Levels
Parent topic: Database Access


Nested Loop Example

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In the sample IMS database program in the figure below, a nested loop obtains all detail records of each order record that is obtained by the previous program loop. In addition, the call following the nested loop obtains the part master record for each detail record. Fields from all three records display on the program screen, as shown below.

Figure 1. Nesting Database Calls
Nesting Database Calls

The sample programs in the above figure execute as follows:

Call 01 | Obtains the customer record. It is qualified on the customer record key, which is the customer number.
Call 02 | The outer loop. It loops on the order record, which is qualified on the order record key, the customer number.
Call 03 | The nested loop. It positions the database pointer on the currently-obtained first order record record and loops on the detail record.
Call 04 | An obtain call, nested within the second loop. It obtains the part master record associated with the detail record that was obtained by call 03.
Call 03 and Call 04 | Execute repeatedly until no more detail and part master records are found for the first order record.
Call 02 | Executes again, obtaining the second order record.
Call 03 and Call 04 | Execute repeatedly until no more detail and part master records are found for the second order record.
Call 02 and Call 04 | Execute repeatedly until no more order, detail, or part master records are found for the customer number specified in the customer record call, Call 01.
Parent topic: Coding Nested Loops


Overriding Nesting Levels

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Depending on what you want your program to do, you might need to override the nesting levels of loops to nest them under different loops, or to execute them independently of other loops. By default, Online Express assigns default nesting levels to each loop in the Nesting Level field on the Attributes dialog box. For example, if you define three loops in your program, their default Nesting Level field values are:

Loop | Nesting Level | Description
1 | 0 | Loop is not nested
2 | 1 | Loop is nested within loop 1
3 | 2 | Loop is nested within loop 2

You can decrease but not increase the default nesting level of any loop simply by changing the Nesting Level field value. For example, if you want the second loop to execute independently of the first loop, you change its nesting level from 1 to 0. Or, if you want the third loop to be nested within the first loop rather than the second, you change its nesting level from 2 to 1. Online Express ensures that your nesting levels do not skip a level. For example, you cannot specify a level 0 loop followed by a level 2 loop.

When you override nesting levels, you specify the outermost loop - a level 0 loop - whose records you plan to map to your screen.

In the figure below, the program must display all items to be included in the next shipment to a certain customer. The first loop reads all outstanding orders for the customer and executes a user-defined routine to determine which order ships next. The second loop obtains all detail records of the order found by the first loop, and maps them to a repeated record block.

Note that, if the program shown here uses the default nesting level of the second loop, it would not execute as required. The program would loop on and obtain all customer order records and their detail records. In addition, Online Express would assume that records of the first loop will map to the screen.

Figure 1. Overriding Nesting Levels
Overriding Nesting Levels

The next figure illustrates how to make the program execute as required.

  • On the Attributes window, the nesting level of calls 02 and 03 are changed from 1 to 0 to make them not nested within the first loop.
  • The RB field of the first loop has been deactivated. This means that the loop does not display on the screen. To deactivate the RB field, double-click it to display the Attributes dialog box, then uncheck Scrollable Rec.
  • The RB field value of the second loop is selected. This means that the loop does display on the screen.
Figure 2. Executing Nested Calls
Executing Nested Calls
Parent topic: Coding Nested Loops


Executing Multiple Database Actions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can define a control action to execute more than one database action. For example, you can define the Query action to execute the Store action as well as the Obtain action.

Suppose you want the Query control action to execute two calls - one that obtains records in a particular table, and another that simply stores those same records in another table. The following figure illustrates this.

Figure 1. Multiple Database Actions
Multiple Database Actions
Parent topic: Database Access


Qualifying VSAM Multiple-Field Keys

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To qualify a VSAM group-level key field, you write custom logic that moves the key elementary field values to a group-level qualification value field that you define. You then qualify the key with the qualification value field. You write and execute the custom logic at the Before DB Access event.

For example, suppose that a key has the following elementary fields.

01  SALES-KEY.
    05  REGION-CODE    PIC X(2).
    05  YEAR-CODE      PIC X(2).

You write the following logic at the Before DB Access event, on the DB Call Tailoring window. The logic defines a group-level Working-Storage field and moves the values of the two elementary fields to it.

MOVE SCREEN-REGION-CODE TO REGION-CODE
        MOVE SCREEN-YEAR-CODE TO YEAR-CODE
 WS01   NEW-SALES-KEY.
        05  REGION-CODE    PIC X(2).
        05  YEAR-CODE      PIC X(2).

Then, on the Qualification window, you qualify the key field, SALES-KEY, with the qualification value field, NEW-SALES-KEY.

Parent topic: Database Access
Related tasks
To qualify VSAM multiple-key fields in Online Express


Overriding Error Processing

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can customize database call processing by overriding the status codes of Online Express status flags and the text of default error messages. You do both on the DB Call Tailoring Editor dialog box.

Online Express provides the following status flags:

Status Flag | Default Status Code
OK-ON-REC | Normal
END-ON-REC | Normal
NTF-ON-REC (Not found) | Error
DUP-ON-REC | Error
VIO-ON-REC (Violation) | Error

When Online Express returns the Error status flag, the program aborts and performs the ERROR-SEND-AND-QUIT paragraph.

To override the default Error flag processing, you can change a status flag code from Error to Exception, and then write your own error routines at any of the database events on the DB Call Tailoring Editor.

Online Express also generates error messages that show which type of call failed and which record caused the failure. You can override the default messages with either a text message or a rule that contains a text message.

Parent topic: Database Access
Related tasks
To customize database calls in Online Express


Writing Custom Logic

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Without leaving Online Express, you can write custom logic to supplement or override the default logic that Online Express generates. You can provide custom logic for events that occur before or after an action or database call, and when actions and calls execute normally or abnormally.

There are two types of events for which you can write your own logic:

  • Predefined actions, such as sending a screen.
  • Database calls, such as Obtain and Store. For example, you might want to tailor the Obtain action by adding a data validation routine that executes whenever the Obtain action executes. Or, you might want to override the default error message text.

You can execute any of the following types of custom logic at any event.

  • Local program code - Event logic specifically for the current program.
  • Global program code - Custom logic that you use throughout your application.
  • Paragraph - A Procedure Division paragraph along with Data Division source that executes in the current program.
  • User-defined rule - Any code that you write using the AMB Customizer, a high-level tool for writing and processing rules.
  • Customizing Database Calls
  • Types of Custom Code
Parent topic: Online Express


Customizing Database Calls

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can execute custom logic at any of several Express-provided events that occur during database call processing:

Event | Occurrence
Before DB Access | Before a non-loop database call executes
Before Loop | Before a loop database call executes
Normal Status | After processing records, and before moving them to the window or screen
Normal-X Status | For looped records only. After Normal Status executes, and before moving records to the window or screen
Error Status | After the database call returns an Error status flag
Exception Status | After the database call returns an Exception status flag
After DB Access | After a non-loop database call executes
After Loop | After a loop database call executes

The Normal Status and Normal-X Status events enable you to add custom logic before looped records map to your screen. Use these events when you want to map only some of the records that a loop obtains. In your custom code, write conditional logic to determine which records to map. Online Express provides a flag, OK-TO-PROCEED, that you set to True to map and process the record, or False to bypass mapping and processing. You can ignore the flag if you do not use this event; the flag is set to True by default.

The following example illustrates both events. Suppose that you must map the records that show annual sales of $100,000 or more in the Northwest region, and calculate and map the grand total of those records.

  • First, you define a loop call and qualify it to obtain the records of $100,000 or more.
  • Then, you tailor the loop call with two paragraphs.
    • The first paragraph (at the Normal-X Status event) checks the records obtained by the loop and process records of the Northwest region only.
    • The second paragraph (at the Normal Status event) calculates the grand total of those records, and maps the total to the screen.

Using the Normal Status Events - Generated Code

DB-PROCESS REC SALES-RECORD
... WHERE ANNUAL-SALES-TOTAL > 99999
    PERFORM CHECK-BEFORE-MAPPING-PARA
    IF OK-TO-PROCEED
        ADD 1 TO CTR
        PERFORM RECORD-STOREKEY-PARA
        PERFORM CALC-AND-MAP-PARA
        MOVE REC-TO-SCREEN-LB1
     .
     .
     .
CHECK-BEFORE-MAPPING-PARA
    TRUE OK-TO-PROCEED
    IF SALES-REGION NOT = NORTHWEST
        FALSE OK-TO-PROCEED

CALC-AND-MAP-PARA
    calculation and mapping routine for grand total

In the example code:

  • The CHECK-BEFORE-MAPPING-PARA paragraph executes at the Normal Status event. Express generates the paragraph PERFORM statement.
  • The CALC-AND-MAP-PARA paragraph executes at the Normal-X Status event. Express generates the paragraph PERFORM statement.
  • Online Express generates all code subordinate to the DB-PROCESS call.
Parent topic: Writing Custom Logic


Types of Custom Code

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Online Express enables you to write custom code as local code, global code, user rules, and paragraphs.

Observe the following coding rules.

  • A paragraph can consist of a main paragraph, other paragraphs that the main paragraph performs, and Data Division source code for the paragraphs.
  • For each paragraph, enter PARA in columns 4 through 7, and the paragraph name in column 12 on the same line. On the following lines, enter COBOL S-COBOL statements. Do not use any other AMB keywords in paragraphs.
  • To pass arguments to the paragraph, code them next to the paragraph name without parentheses. For example:
    paragraphname arg1 arg2 arg3 .
  • After coding all paragraphs, use Data Division keywords to define data items that the paragraphs reference.
  • Local Program Code
  • Global Program Code
  • Paragraphs
  • User-Defined Rules
Parent topic: Writing Custom Logic


Local Program Code

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You write and execute local code specifically in one program. It can consist of a main paragraph, other paragraphs that the main paragraph performs, and Data Division source code for the paragraphs. You write local code in the Program Painter. When you generate your program, AMB inserts the code in the program and generates a PERFORM statement to perform it.

Observe the following coding rules.

  • On the first line, enter COBOL S-COBOL statements starting in column 12 and continue onto as many lines as you need. Do not enter the PARA keyword or a paragraph name; AMB generates a paragraph name for the code and displays it in the Program Painter. In the code, you can perform additional paragraphs that you write elsewhere in the code. See S-COBOL Structures for more information.
  • To define a paragraph that the code performs, enter the PARA keyword in the KYWD column (columns 8-11) and the paragraph name starting in column 12 on the same line. On the following lines, enter your paragraph statements.
  • After all paragraphs, define any Data Division source for the paragraphs, such as data items that the code references. To do so, use AMB Data Division keywords. See Program Painter Keywords for more information.

For example:

        statement
            .
            .
            .
        PERFORM paragraphname [(arguments)]
 PARA   paragraphname [(+|-arguments)]
        statement
            .
            .
            .
 WS
 01     groupleveldataitem
        05  elementarydataitem
            .
            .
            .
Parent topic: Types of Custom Code
Related tasks
To qualify VSAM multiple-key fields in Online Express
To specify an isolation level
Related reference
Program Painter Keywords
S-COBOL Structures


Global Program Code

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You write code that can you use throughout your application. Global code can consist of a main paragraph and other paragraphs that the main paragraph performs. You write global code in the Program Painter.

Observe the following coding rules.

  • On the first line, enter any COBOL or S-COBOL procedural source code or write one or more paragraphs.
  • To define a paragraph, type the PARA keyword in columns 4 through 7 and the paragraph name in column 12 on the same line. On the following lines, enter paragraph statements starting in column 12. Do not use any other AMB keywords in the paragraph. In the paragraph, you can perform additional paragraphs that you write in the global code.
  • To define an additional paragraph that the main paragraph performs, enter the PARA keyword columns 4 through 7 and the paragraph name starting in column 12 on the same line. On the following lines, enter your paragraph statements.

For example:

PERFORM paragraphname
 PARA   paragraphname
        statement
            .
            .
            .
        PERFORM subparagraphname [(arguments)]
 PARA   subparagraphname [(+|-arguments)]
        statement
            .
            .
            .
Parent topic: Types of Custom Code
Related tasks
To qualify VSAM multiple-key fields in Online Express
To specify an isolation level


Paragraphs

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can write a Procedure Division paragraph along with Data Division source that executes in one program. The paragraph can perform other paragraphs that you write with the main paragraph. This differs from local code in that you associate the paragraph with the Perform action, and that AMB stores these paragraphs in the MISC-USER-PARAGRAPHS file.

Parent topic: Types of Custom Code


User-Defined Rules

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

A user rule is any code that you write using the AMB Customizer, a high-level tool for writing and processing rules. You include rule library members in your application on the Project Explorer.

Parent topic: Types of Custom Code
Related tasks
To create a User Rule
To update a User Rule
To qualify VSAM multiple-key fields in Online Express
To specify an isolation level


Commarea and Savekey Storage

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can define storage for a Commarea, and define separate Savekey storage, or store Savekey information in your Commarea.

  • Commarea Storage
  • Savekey Storage
  • Global Commarea Size
Parent topic: Online Express


Commarea Storage

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Commarea is an area of your program generated by Online Express that stores data you pass between programs.

Online Express automatically creates a Commarea; you simply specify the size of the largest record that your program can send or receive in the Extra Commarea Bytes field on the Express Generation Options window. To access this window, from the File menu, select Express Generation Options.

When you generate your program, the following code is generated to create a storage area in Commarea.

    SYM2    $PX-CA-COMPUTE-LEN( savekeybytes, sharedbytes)
    CA05    FILLER
            $PX-CA-SETUP

Where:

  • Savekeybytes is the number of storage bytes that Online Express calculates for storing record keys when:
    • Obtaining records sequentially with the Next action
    • Re-reading repeated record block records so that the end user can update and delete them with the Modify and Erase actions.

    Online Express calculates the number of savekeybytes as the key length of each window record that can be updated, plus a one-byte flag per key. For scrollable SQL records, Online Express calculates savekeybytes as the length of each Order By column, plus a one-byte flag per key.

  • Sharedbytes is the number of bytes that you specify for storing data that you pass between programs using the Call, XCTL, XCTL NOTERM, or MSG-SW actions. You can specify any number of bytes. Express stores the sharedbytes in the Commarea data structure PX-USER-COMMAREA.

Alternatively, you can define a Commarea data structure object in your application's Globals folder using the Data Structure Editor. See CA, CA05, and CADS for more information.

Parent topic: Commarea and Savekey Storage
Related reference
CA, CA05, and CADS


Savekey Storage

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Savekeys are places where key values of a record are stored for updating to reread the same record, or for sequentially browsing a database where the savekey is a placeholder.

You define savekey storage area(s) to store record key values during program execution, if your program:

  • Updates records with the Update and Delete program actions.
  • Browses records sequentially with the Next program action.
  • Displays repeated record blocks that the end user can scroll with the Forward and Backward actions.

Online Express calculates the amount of savekey space needed for you.

  • For each record updated, Online Express adds the record primary key size to the savekey size. If that record is in a repeated record block, Online Express multiplies that amount by the number of rows in the block.
  • If a record is scrollable, Online Express adds the record size and key to the savekey size. For SQL, Online Express adds the size of all columns in the ORDER BY clause. If backward scrolling is permitted, Online Express multiplies this value by 2.

You can store a savekey in one of two ways.

  • Specify its storage in the Commarea.
  • Paint and define it on your application screen, in the Screen Painter.
  • Store on your Screen
  • Suppressing Savekey Generation
Parent topic: Commarea and Savekey Storage
Related tasks
To define Savekey storage


Store on your Screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

If your screen displays only one occurrence of data at a time, and the data is updateable, you paint one savekey field. However, if your screen displays a scrollable or updateable repeated record block, as well as a single occurrence of data, you paint either:

  • Two savekey fields - one for the repeated block data and one for the single occurrence data.
  • One savekey field for both.
Parent topic: Savekey Storage
Related tasks
To define a Savekey
To paint a Savekey field


Suppressing Savekey Generation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You might want to suppress the generation of the savekey storage area and savekey logic for a call if the call:

  • Updates or delete records that do not have a unique index
  • Performs blind update or delete function

For example, to update and delete a record, you would write two separate calls - one to obtain and modify the record and one to obtain and delete the record. You would select the following values for each call:

Call | Function | Action
01 | Update | Obtain Modify
02 | Delete | Obtain Erase
Parent topic: Savekey Storage


Global Commarea Size

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

If you want to use your Commarea to store savekey information, you need to ensure that it can accommodate both the program key and the largest amount of data that the program can receive from another program. You can define a global Commarea size that all programs of the application use as their Commarea size.

  1. Check the Express Savekey Data dialog box of each program to determine the largest savekey requirement.
  2. Check the number of bytes of the largest record that your program can receive.
  3. Add the two largest record sizes of each to determine the largest required record size.
  4. In a control file or in a user-defined rule, assign the result to the AppMaster Builder variable &TP-USER-LEN. Online Express uses the value of this variable to assign the size of the savekey storage in Commarea. The format of &TP-USER-LEN is:
    &TP-USER-LEN = savekeybytes + sharedbytes

    Where:

    • Savekeybytes is the value of the savekey required bytes from the For All Savekeys field on the Savekey Data dialog box.
    • Sharedbytes is the value of the Extra Commarea Bytes field on the Express Generation Options dialog box.
Parent topic: Commarea and Savekey Storage


Control Points

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMB control points enable you to write and execute custom processing logic to supplement or override the default logic that Online Express generates. Execute this logic at any of the AMB-provided locations in your program, known as program control points.

The following table shows you the name of each control point and where you can find it in a program:

Control Point | Location in Program
After-Receive-Para | After entering a program, regardless of invocation mode.
Post-Screen-Read | After a screen-invoked program receives its screen.
Transid-Invoked-Para | After a transid-invoked program is invoked.
Program-Invoked-Para | When AMB displays the screen of a program invoked by the XCTL or MSG-SW function.
Pre-Term | Before AMB terminates the program.
After-Enter-Check | After the end user presses the processing key (the Enter key is the default), and before the PRE-FUNCTION-TEST paragraph executes.
Pre-Function-Test | Before AMB evaluates all functions except the Terminate, or Exit, function.
Pre-Branch | Before each MSG-SW, XCTL, or Call function executes.
Ed-Error-Pre-Send | Before AMB send a screen whose field edits have failed.
General-Pre-Send | After AMB checks all functions, and before the TP-SEND call executes, when invocation mode is screen-invoked.
Before-Send-Para | Before AMB sends the screen, regardless of invocation mode.
Pre-Screen-To-Rec | Before AMB performs the MOVE-SCREEN-TO-REC paragraph.
Post-Screen-To-Rec | After AMB performs the MOVE-SCREEN-TO-REC paragraph, and the Update or Add function executes.
Pre-Rec-To-Screen | Before AMB performs the MOVE-REC-TO-SCREEN paragraph.
Post-Rec-To-Screen | After AMB performs the MOVE-REC-TO-SCREEN paragraph, and after the Query function executes.
Pre-RB1-Row-To-Rec | Before the Add or Update function executes for a repeated record block row, and before screen fields move to database fields. AMB uses the subscript CTR to reference repeated block rows.
Post-RB1-Row-To-Rec | Before the Add or Update function executes for a repeated record block row, and after screen fields move to database fields. AMB uses the subscript CTR to reference repeated block rows.
Pre-Rec-To-RB1-Row | After the Query or Forward function executes for a repeated record block row, and before database fields move to screen fields. AMB uses the subscript CTR to reference repeated block rows.
Post-Rec-To-RB1-Row | After the Query or Forward function executes for a repeated record block row, and after database fields move to screen fields. AMB uses the subscipt CTR to reference repeated block rows.
Error-Send-And-Quit | When a program terminates abnormally, such as when a database call fails when the Database Call Tailoring screen's Abort On Error parameter is set to Y.
Misc-User-Paragraphs | A location where you can write and store any number of paragraphs to perform at any control point in the program. Code all your paragraphs in one file in this location.
Before DB Access | Before a non-loop database call executes
Before Loop | Before a loop database call executes
Normal Status (Before Record is Processed) | Before Online Express maps looped records to the screen
Normal Status | After Online Express maps any records to the screen
Exception Status | After the database call returns a status flag with the Exception status code
Error Status | After the database call returns a status flag with the Error status code
After DB Access | After a non-loop database call executes
After Loop | After a loop database call executes

The following flowcharts illustrate the locations of all control points in AMB-generated programs.

Standard Control Points

Function Code and PF Key Processing

Function Code and PF Key Processing (continued)

Evaluate Row Actions

The flowchart below illustrates the location of the database call control points in generated programs.

Non-Loop Call and Loop Call

You can set AppMaster Builder to automatically generate comments in your programs that indicate the location of control points in the code.

Parent topic: Online Express


Program Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Program Painter offers you an alternative to Online Express. Unlike the menu-driven method of Online Express, the Program Painter method is text-driven, enabling you to enter your specifications on a blank window using a text editor. The Program Painter provides a shorthand method for creating online COBOL programs for your applications.

Your application can consist entirely of online programs, or you can mix online programs with batch programs in the same application. In addition, the programs of a single application can access different database targets. For example, your online programs can access SQL databases and VSAM files, while your batch programs access VSAM files and IMS databases.

In combination with standard COBOL, you can also use the following types of source code:

AppMaster Builder Structured COBOL (S-COBOL) source code
S-COBOL is an optional set of COBOL-like procedural structures that are simpler and more powerful than COBOL structures. You can write S-COBOL statements in conjunction with, or instead of, COBOL statements.
AMB database and data communication calls
These calls provide almost all the functionality offered by your target environment calls, but are easier to write. The short, simple formats of the AMB calls shield you from much tedious coding - you simply enter the call name and any keywords and arguments that you need. AMB generates your specifications as complete calls, written in the syntax native to your DB environments.

In addition, you can include externally-defined source code in your programs that further streamlines the process of developing applications. To do this, enter AMB keywords to specify the location in the program where the source code belongs. Applications created in the Program Painter can use any of the following types of external source code.

External Code | Project Subdirectory | Description
Global code | APSPROG | You create global code using the Program Painter; AMB stores each global code module in a separate file that all programs of your application can share.
COBOL copyfiles | COPYLIB | These copybooks can contain data structures or other source code.
Data structures | APSDATA | Data structures that you create in the Data Structure Editor.
User-defined rules | USERMACS | User-defined Customizer rules

Before you get started on coding your programs, be sure you have done the following:

  • Set your AppMaster Builder preferences
  • Created your application and program in the Project Explorer
  • Assigned the appropriate application and program properties
  • For online programs - Created your application screens
  • Program Templates
  • Coding Programs
  • Coding Options
  • Sample Online Program
  • Sample Batch Program
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
The AppMaster Builder Tool Set
Related tasks
To start the Program Painter
To set AppMaster Builder preferences
Related reference
S-COBOL Structures
Program Painter Keywords


Program Templates

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This section discusses the program templates you can use for online and batch programs. Templates define several pieces of your program, based on the objects you have defined for your application in the Project Explorer, your AppMaster Builder preferences, and the application and program properties you have set.

  • Program Template for Online Applications
  • Program Template for Batch Applications
Parent topic: Program Painter
Related tasks
To set AppMaster Builder preferences


Program Template for Online Applications

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

By entering a single AMB keyword, NTRY, you can generate a program template, or shell, that fully defines all parts of your online program except for the procedural code that you supply.

Default Template Definitions

The online template defines the following:

  • The Identification Division
  • The Environment Division
  • The Data Division, including the following Working-Storage and Linkage Section structures:
    • Your database record or file definitions
    • Your IMS PCB mask for IMS programs
    • An AMB data structure for passing data between programs, known as a Commarea, which appears in either Working-Storage or the Linkage Section, depending on your user interface target
    • Function key definitions, based on your specified user interface target
    • Flags required by AMB
  • Portions of the Procedure Division, including:
    • A housekeeping routine to initialize Working-Storage fields, flags, and counters
    • Program invocation logic to initialize your program
    • Logic to send the program screen

By default, the NTRY keyword tailors the generated program template depending on the DC target you use. The template tests the field TP-INVOCATION-MODE to determine the mode that invoked it (ie. via a transaction ID, another program, or a screen). Once the mode has been determined, the program performs one of the following paragraphs.

APS-TRANSID-INVOKED-PARA
Displays the first input screen associated with the program in the Application Painter or the screen coded with NTRY. This paragraph is performed if a transaction ID has been entered and no screen information or data is passed to the program; not applicable for IPSF Dialog programs.
APS-PROGRAM-INVOKED-PARA
Displays the first input screen associated with the program in the Application Painter or the screen coded with NTRY. This paragraph is performed if the program is called from another program and data is available in the Commarea; not applicable for IMS/DC programs.
APS-SCREEN-INVOKED-PARA
Performed if the program is screen-invoked. The program checks field edits to see if input paragraphs must be performed before it starts. This paragraph also performs APS-USER-CODE-PARA, which contains the statement(s) you coded with the NTRY keyword.

Customizing the Program Template

You can customize the template generated by the NTRY keyword by substituting your own logic in place of any generated invocation paragraph, or even substituting your own logic for the entire Procedure Division. You can also add your own logic at entry and exit points in the template using predefined paragraph names that are invoked automatically.

To substitute template logic, you can do either or both of the following:

  • Substitute your own paragraph logic in place of the logic supplied with any of the default invocation paragraphs: APS-PROGRAM-INVOKED-PARA, APS-TRANSID-INVOKED-PARA, and APS-SCREEN-INVOKED-PARA

    You must use these paragraph names, replacing the logic only. For example, you might want to modify APS-PROGRAM-INVOKED-PARA to move information from the Commarea to the screen before it is displayed, or you might want to modify the APS-TRANSID-INVOKED-PARA to perform more initialization.

  • Substitute the entire Procedure Division portion of the generated template with your own logic. To do so:
    • Add the OPT PROG statement on a line above NTRY.
    • Add your custom Procedure Division code beneath NTRY.

    When using OPT PROG, any invocation paragraphs that you have overridden are not automatically performed from the generated Procedure Division. Therefore, if you specify OPT PROG and also substitute your own logic for one or more invocation paragraphs, you must also include the code that performs those paragraphs. Other, non-Procedure Division portions of the template are still generated, however.

To add logic at entry or exit points in your program, supply either or both of the following two paragraphs, which are automatically invoked from the mainline code if they exist in the program:

APS-AFTER–RECEIVE-PARA
Performed immediately after the program receives control from a screen and all field edits have been performed, regardless of the invocation mode. You can use this paragraph, for example, to check security.
APS-BEFORE-SEND-PARA
Performed before a send of the default screen if control was not transferred by a previously executed program. It is performed regardless of the specified invocation mode. You can use this paragraph, for example, to blank out a password field.
Parent topic: Program Templates
Related reference
Program Painter Keywords


Program Template for Batch Applications

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Batch program template defines the following:

  • Identification Division
  • Data Division, Working-Storage Section
    • Database record definitions
    • IMS database PCB mask for IMS programs
    • Flags required by AMB
  • Procedure Division - Routines to initialize AMB Working-Storage flags
Parent topic: Program Templates


Coding Programs

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

While the templates do provide a solid foundation for your programs, your programs are likely to require additional functionality that is not provided by the code generated by the program templates.

As you code a program, you specify the COBOL program locations where the code belongs, such as the Working-Storage Section or Procedure Division, by entering AMB keywords in columns 4 through 7.

You can enter your source code and associated keywords in any sequence; when you generate the program, AMB arranges the source into the proper COBOL program sequence. For example, you can define Working-Storage fields in the Procedure Division instead of Working-Storage.

Online Programs

You can add to or modify the template as needed. To do this, enter additional AMB keywords with your source code to specify the program location where the source belongs. For example, you can:

  • Add Working-Storage or Linkage Section data elements and flags for your procedural routines
  • Redefine the AMB Commarea data structure to accommodate the data that you pass between programs
  • Add to or modify the default program invocation logic to suit your program requirements
  • Add calls to user-defined Customizer rules, and set any variable values required by the rules

Batch Programs

There are a few items you need to code into your program that are not provided by the batch program template. Use Program Painter keywords, COBOL, S-COBOL, database calls, and user-defined Customizer rules to code:

  • Data Division, File Section
  • Data elements and flags for your procedural routines
  • Procedural source code

Program Stub

A program stub is just part of a program. Usually, it consists of a paragraph or paragraphs, and is written in COBOL or S-COBOL. A stub can also contain user-defined Customizer rules. You can call a program stub from other programs, but you cannot compile and run it on its own. You add a program stub to an application in the Project Explorer, which makes the stub available to all other programs in the application that contains it. You code program stubs in the Program Painter.

APSSRC

If you choose, you can also code a program directly using S-COBOL, that is, without coding the logic into the Program Painter. To do this, create a source member in your APSSRC directory, and code S-COBOL statements directly into it. Effectively, an APSSRC member contains the same code as would a GENSRC member if you coded the same logic into the Program Painter.

Customizer Rules

In your program, you can enter any Customizer rule calls or statements that your program requires. For example, if on the Project Explorer you include user-defined rules in a Globals folder, call the rules you need, and assign values to any variables that the rules require. Use the following keywords to place Customizer source in the appropriate program location.

Keyword | Program Location
SYM1 | At the beginning of the program, before rule libraries that you include at the beginning of the program
SYM2 | After rule libraries that you include at the beginning of the program
SYEN | In the Environment Division, after the Special-Names paragraph
SYDD | At the beginning of the Data Division
SYFD | In the File Section, after rules that you include at the beginning of the File Section
SYWS | In the Working-Storage Section, after rules and data structures that you include in Working-Storage
SYLT | In the Linkage Section, after rules and data structures that you include at the beginning of Linkage
SYLK | In the Linkage Section, after source code that you include with the SYLT keyword
SYBT | At the end of the program

Example

   SYM1
   /*      RULE VARIABLE TO APPEAR AT BEGINNING OF PROGRAM,BEFORE
   /*      RULE LIBRARY THAT I INCLUDE AT BEGINNING OF PROGRAM.
           % &MY-SYMBOL = 1234

   SYM2
   /*      RULE VARIABLE TO APPEAR AFTER RULE LIBRARY THAT I
   /*      INCLUDE AT BEGINNING OF PROGRAM.
           % &MY-STRING-SYMB = "THIS IS A STRING"

   SYWS
   /*      RULE VARIABLE TO APPEAR AFTER RULE LIBRARY THAT I
   /*      AT INCLUDE BEGINNING OF WORKING-STORAGE.
           % &MY-WS-SYMBOL = 1234
Parent topic: Program Painter
Related concepts
Defining Customizer User Rules
Creating Report Programs
Related tasks
To code Identification Division comments in the Program Painter
To code an Environment Division Special-Names statement
To code Working-Storage structures
To define data structures in COBOL format
To define data structures in Data Editor format
To include a copyfile
To include a global or local data structure
To define a DB2 table declaration and cursor declarations
To code Linkage Section structures
To define or redefine the Commarea
To begin the Procedure Division for online programs
To code the Procedure Division
To code Procedure Division comments
To define the Input-Output Section
To create a User Rule
To update a User Rule
Related reference
Program Painter Keywords
S-COBOL Structures
SY*


Coding Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AppMaster Builder provides several coding options. In the course of development, you can code in:

  • Native COBOL - any legal COBOL language structure
  • COBOL XML statements - XML PARSE and XML GENERATE
  • S-COBOL - procedural structures that extend the power of native COBOL, yet simplify and shorten the amount of code you must write
  • Keywords - In the Program Painter, use these to represent COBOL structures
Parent topic: Program Painter
Related reference
COBOL Language Reference
The XML PARSE Statement
The XML GENERATE Statement
S-COBOL Structures
Program Painter Keywords


Sample Online Program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Program Painter source:

   NTRY    PSINQY
   /*      BEGIN PROCEDURE DIVISION SOURCE CODE
           IF PF12
              SEND PSMENU
           ELSE-IF PF1
              PSUPDT-EMPLOYEE-NO = PSINQY-EMPLOYEE-NO
              PSUPDT-FUNCTION = '1'
              SEND PSUPDT
           ELSE
              SEND PSINQY
           PERFORM SAMPLE-S-COBOL-PARA
           PERFORM SAMPLE-COBOL-PARA

   PARA    SAMPLE-COBOL-PARA.
           source
   PARA    SAMPLE-S-COBOL-PARA
           source
   STUB    MY-STUB

Generated AMB source:

003700 $TP-ENTRY ("PSINQY", "")
003710     IF TP-TRANSID-INVOKED
003720         PERFORM APS-TRANSID-INV-PARA
003730     ELSE-IF TP-PROGRAM-INVOKED
003740         PERFORM APS-PROGRAM-INV-PARA
003750     ELSE-IF TP-SCREEN-INVOKED
003760         PERFORM APS-SCREEN-INV-PARA
003770     $TP-SEND ( "PSINQY", "")
003780
003790 APS-TRANSID-INV-PARA.
003800     % IF &TP-USER-LEN > 0
003810         MOVE LOW-VALUES TO TP-USERAREA
003820     $SC-CLEAR ( "PSINQY")
003830     EJECT
003840 APS-PROGRAM-INV-PARA.
003850     $SC-CLEAR ( "PSINQY")
003860     EJECT
003870 APS-SCREEN-INV-PARA.
003880     PERFORM APS-USER-CODE-PARA
003890     EJECT
003900 APS-USER-CODE-PARA.
003910 /*  BEGIN PROCEDURE DIVISION SOURCE CODE
003920 IF PF12
003930     $TP-SEND PSMENU
003940 ELSE-IF PF1
003950     PSUPDT-EMPLOYEE-NO = PSINQY-EMPLOYEE-NO
003960     PSUPDT-FUNCTION = '1'
003970     $TP-SEND PSUPDT
003980 ELSE
003990     $TP-SEND PSINQY
004000 PERFORM SAMPLE-COBOL-PARA
004010 PERFORM SAMPLE-S-COBOL-PARA
004020 PERFORM MY-STUB
004030
004040 SAMPLE-COBOL-PARA.
004050     source
004060 SAMPLE S-COBOL-PARA
004070     source
004080 MY-STUB
004090     source
Note: To override the APS-TRANSID-INV-PARA, APS-PROGRAM-INV-PARA, or APS-SCREEN-INV-PARA paragraph, you must also perform it; AMB does not automatically perform it.
Parent topic: Program Painter


Sample Batch Program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Program Painter source:

   IO      INPUT-CUSTFILE
           ASSIGN TO GARYDD
           ORGANIZATION IS LINE SEQUENTIAL
   IO      OUTPUT-FILE
           ASSIGN TO GARYOUT
           ORGANIZATION IS LINE SEQUENTIAL
   FD      INPUT-CUSTFILE
           RECORD CONTAINS 80 CHARACTERS.
   01      INPUT-REC.
           05  INP-ACTION-CODE     PIC X(1).
           05  INP-CUSTOMER-NO     PIC X(6).
           05  INP-CUSTOMER-NAME   PIC X(20).
           05  INP-CUSTOMER-ADDR   PIC X(20).
           05  INP-CUSTOMER-CITY   PIC X(20).
           05  INP-CUSTOMER-ZIP    PIC X(9).
           05  FILLER              PIC X(4).
   FD      OUTPUT-CUSTFILE
           RECORD CONTAINS 80 CHARACTERS.
   01      OUTPUT-REC.
           05  OUTPUT-STATUS           PIC X(2).
           05  OUTPUT-CUSTOMER-NO      PIC X(6).
           05  OUTPUT-CUSTOMER-NAME    PIC X(20).
           05  OUTPUT-CUSTOMER-ADDR    PIC X(20).
           05  OUTPUT-CUSTOMER-CITY    PIC X(20).
           05  OUTPUT-CUSTOMER-ZIP     PIC X(9).
           05  OUTPUT-FILLER           PIC X(3).

   PROC
           OPEN INPUT INPUT-CUSTFILE
           ...  OUTPUT OUTPUT-FILE
           REPEAT
               READ INPUT-CUSTFILE
               WS-CUST-NO = INP-CUSTOMER-NO
           UNTIL AT END ON INPUT-CUSTFILE
               EVALUATE INP-ACTION-CODE
               WHEN 'Q'
                   PERFORM QUERY-LOGIC
               WHEN 'U'
                   PERFORM UPDATE-LOGIC
               WHEN 'D'
                   PERFORM DELETE-LOGIC
           CLOSE INPUT-CUSTFILE
           ...   OUTPUT-FILE

   PARA    QUERY-LOGIC
           DB-OBTAIN REC CUSTOMER-REC
           ... WHERE CM_CUSTOMER_NO = #WS-CUST-NO
           IF OK-ON-REC
               OUTPUT-STATUS      = 'SQ'
               PERFORM MOVE-COPYLIB-TO-OUTPUT
               PERFORM WRITE-MSGOUT
           ELSE
               OUTPUT-STATUS      = 'UQ'
               PERFORM MOVE-INPUT-TO-OUTPUT
               PERFORM WRITE-MSGOUT

   PARA    UPDATE-LOGIC
           PERFORM MOVE-INPUT-TO-COPYLIB
           DB-MODIFY REC CUSTOMER-REC
           ... WHERE CM_CUSTOMER_NO = #WS-CUST-NO
           IF OK-ON-REC
               OUTPUT-STATUS      = 'SM'
               PERFORM MOVE-COPYLIB-TO-OUTPUT
               PERFORM WRITE-MSGOUT
           ELSE
               OUTPUT-STATUS      = 'UM'
               PERFORM MOVE-COPYLIB-TO-OUTPUT
               PERFORM WRITE-MSGOUT

   PARA    DELETE-LOGIC
           DB-ERASE REC CUSTOMER-REC
           ... WHERE CM_CUSTOMER_NO = #WS-CUST-NO
           IF OK-ON-REC
               OUTPUT-STATUS      = 'SE'
               PERFORM MOVE-INPUT-TO-OUTPUT
               PERFORM WRITE-MSGOUT
           ELSE
               OUTPUT-STATUS      = 'UE'
               PERFORM MOVE-INPUT-TO-OUTPUT
               PERFORM WRITE-MSGOUT

   PARA    ADD-LOGIC
           PERFORM MOVE-INPUT-TO-COPYLIB
           DB-STORE REC CUSTOMER-REC
           ... WHERE CM_CUSTOMER_NO = #WS-CUST-NO
           IF OK-ON-REC
               OUTPUT-STATUS      = 'SS'
               PERFORM MOVE-INPUT-TO-OUTPUT
               PERFORM WRITE-MSGOUT
           ELSE
               OUTPUT-STATUS      = 'BS'
               PERFORM MOVE-INPUT-TO-OUTPUT
               PERFORM WRITE-MSGOUT

   PARA    MOVE-INPUT-TO-OUTPUT
           OUTPUT-STATUS                  = OUTPUT-STATUS
           OUTPUT-CUSTOMER-NO             = INP-CUSTOMER-NO
           OUTPUT-CUSTOMER-NAME           = INP-CUSTOMER-NAME
           OUTPUT-CUSTOMER-ADDR           = INP-CUSTOMER-ADDR
           OUTPUT-CUSTOMER-CITY           = INP-CUSTOMER-CITY
           OUTPUT-CUSTOMER-ZIP            = INP-CUSTOMER-ZIP

   PARA    MOVE-COPYLIB-TO-OUTPUT
           OUTPUT-CUSTOMER-NO             = CM-CUSTOMER-NO
           OUTPUT-CUSTOMER-NAME           = CM-CUSTOMER-NAME
           OUTPUT-CUSTOMER-ADDR           = CM-CUSTOMER-ADDR
           OUTPUT-CUSTOMER-CITY           = CM-CUSTOMER-CITY
           OUTPUT-CUSTOMER-ZIP            = CM-CUSTOMER-ZIP

   PARA    MOVE-INPUT-TO-COPYLIB
           CM-CUSTOMER-NO                 = INP-CUSTOMER-NO
           CM-CUSTOMER-NAME               = INP-CUSTOMER-NAME
           CM-CUSTOMER-ADDR               = INP-CUSTOMER-ADDR
           CM-CUSTOMER-CITY               = INP-CUSTOMER-CITY
           CM-CUSTOMER-ZIP                = INP-CUSTOMER-ZIP

   PARA    WRITE-MSGOUT
           WRITE OUTPUT-REC
   WS
   01      THEFLDS.
           05  WS-CUST-NO              PIC X(6).

Generated AMB source:

 %   &AP-GEN-VER = 2200
 %   &AP-PGM-ID = "SAMPLPGM"
 %   &AP-MAIN-PROGRAM- = "NO"
 %   &AP-GEN-DC-TARGET = "MVS"
 %   &AP-GEN-DB-TARGET = "VSAM"
 %   &AP-GEN-USER-HELP = "NO"
 %   &AP-PROC-DIV-KYWD-SEEN = 1
 %   &AP-FILE-CONTROL-SEEN = 1
 %   &AP-SUBSCHEMA = "SAMPLSUB"
 %   &AP-APPLICATION-ID = "JOHND"
 %   &AP-GEN-DATE = "930407"
 %   &AP-GEN-TIME = "07244461"

 %*  --- SUBSCHEMA / PSB FROM APPLICATION DEFINITION ---
 $DB-SUBSCHEMA("SAMPLSUB")

 IDENTIFICATION DIVISION.
 PROGRAM-ID.                       SAMPLPGM.
 AUTHOR.                           JOHND.
 DATE-WRITTEN.                     93/04/07.
 DATE-COMPILED.                    &COMPILETIME.

 ENVIRONMENT DIVISION.

 CONFIGURATION SECTION.
 SOURCE-COMPUTER.                  &SYSTEM.
 OBJECT-COMPUTER.                  &SYSTEM.

 INPUT-OUTPUT SECTION.
 FILE-CONTROL.
     SELECT INPUT-CUSTFILE
     ASSIGN GARYDD
     ORGANIZATION IS LINE SEQUENTIAL.
     SELECT OUTPUT-FILE
     ASSIGN GARYOUT
     ORGANIZATION IS LINE SEQUENTIAL.

 DATA DIVISION.

 FILE SECTION.

 FD  INPUT-CUSTFILE
     RECORD CONTAINS 80 CHARACTERS.
 01  INPUT-REC.
     05  INP-ACTION-CODE     PIC X(1).
     05  INP-CUSTOMER-NO     PIC X(6).
     05  INP-CUSTOMER-NAME   PIC X(20).
     05  INP-CUSTOMER-ADDR   PIC X(20).
     05  INP-CUSTOMER-CITY   PIC X(20).
     05  INP-CUSTOMER-ZIP    PIC X(9).
     05  FILLER              PIC X(4).
 FD  OUTPUT-FILE
     RECORD CONTAINS 80 CHARACTERS.
 01  OUTPUT-REC
     05  OUTPUT-STATUS           PIC X(2).
     05  OUTPUT-CUSTOMER-NO      PIC X(6).
     05  OUTPUT-CUSTOMER-NAME    PIC X(20).
     05  OUTPUT-CUSTOMER-ADDR    PIC X(20).
     05  OUTPUT-CUSTOMER-CITY    PIC X(20).
     05  OUTPUT-CUSTOMER-ZIP     PIC X(9).
     05  OUTPUT-FILLER           PIC X(3).

 WORKING-STORAGE SECTION.
 $TP-WS-MARKER

 01  THEFLDS.
     05  WS-CUST-NO              PIC X(6).

 01  TEXT-MSG                    PIC X(30)
             VALUE &SQ+PLEASE ENTER NEXT TRANSID&SQ.

 PROCEDURE DIVISION.

     OPEN INPUT INPUT-CUSTFILE
     ...  OUTPUT OUTPUT-FILE
     REPEAT
         READ INPUT-CUSTFILE
         WS-CUST-NO = INP-CUSTOMER-NO
     UNTIL AT END ON INPUT-CUSTFILE
         EVALUATE INP-ACTION-CODE
         WHEN 'Q'
             PERFORM QUERY-LOGIC
         WHEN 'U'
             PERFORM UPDATE-LOGIC
         WHEN 'D'
             PERFORM DELETE-LOGIC
     CLOSE INPUT-CUSTFILE
     ...   OUTPUT-FILE

 QUERY-LOGIC
     $DB-OBTAIN ( "REC CUSTOMER-REC WHERE CM_CUSTOMER_NO = ",
     %... "#WS-CUST-NO" )
     IF OK-ON-REC
         OUTPUT-STATUS      = 'SQ'
         PERFORM MOVE-COPYLIB-TO-OUTPUT
         PERFORM WRITE-MSGOUT
     ELSE
         OUTPUT-STATUS      = 'UQ'
         PERFORM MOVE-INPUT-TO-OUTPUT
         PERFORM WRITE-MSGOUT

 UPDATE-LOGIC
     PERFORM MOVE-INPUT-TO-COPYLIB
     $DB-MODIFY ( "REC CUSTOMER-REC WHERE CM_CUSTOMER_NO = ",
     %... "#WS-CUST-NO" )
     IF OK-ON-REC
         OUTPUT-STATUS      = 'SM'
         PERFORM MOVE-COPYLIB-TO-OUTPUT
         PERFORM WRITE-MSGOUT
     ELSE
         OUTPUT-STATUS      = 'UM'
         PERFORM MOVE-COPYLIB-TO-OUTPUT
         PERFORM WRITE-MSGOUT

  DELETE-LOGIC
     $DB-ERASE ( "REC CUSTOMER-REC WHERE CM_CUSTOMER_NO = ",
     %... "#WS-CUST-NO" )
     IF OK-ON-REC
         OUTPUT-STATUS      = 'SE'
         PERFORM MOVE-INPUT-TO-OUTPUT
         PERFORM WRITE-MSGOUT
     ELSE
         OUTPUT-STATUS      = 'UE'
         PERFORM MOVE-INPUT-TO-OUTPUT
         PERFORM WRITE-MSGOUT

 ADD-LOGIC
     PERFORM MOVE-INPUT-TO-COPYLIB
     $DB-STORE ( "REC CUSTOMER-REC WHERE CM_CUSTOMER_NO = ",
     %... "#WS-CUST-NO" )
     IF OK-ON-REC
         OUTPUT-STATUS      = 'SS'
         PERFORM MOVE-INPUT-TO-OUTPUT
         PERFORM WRITE-MSGOUT
     ELSE
         OUTPUT-STATUS      = 'BS'
         PERFORM MOVE-INPUT-TO-OUTPUT
         PERFORM WRITE-MSGOUT

 MOVE-INPUT-TO-OUTPUT
     OUTPUT-STATUS                  = OUTPUT-STATUS
     OUTPUT-CUSTOMER-NO             = INP-CUSTOMER-NO
     OUTPUT-CUSTOMER-NAME           = INP-CUSTOMER-NAME
     OUTPUT-CUSTOMER-ADDR           = INP-CUSTOMER-ADDR
     OUTPUT-CUSTOMER-CITY           = INP-CUSTOMER-CITY
     OUTPUT-CUSTOMER-ZIP            = INP-CUSTOMER-ZIP

 MOVE-COPYLIB-TO-OUTPUT
     OUTPUT-CUSTOMER-NO             = CM-CUSTOMER-NO
     OUTPUT-CUSTOMER-NAME           = CM-CUSTOMER-NAME
     OUTPUT-CUSTOMER-ADDR           = CM-CUSTOMER-ADDR
     OUTPUT-CUSTOMER-CITY           = CM-CUSTOMER-CITY
     OUTPUT-CUSTOMER-ZIP            = CM-CUSTOMER-ZIP

 MOVE-INPUT-TO-COPYLIB
     CM-CUSTOMER-NO                 = INP-CUSTOMER-NO
     CM-CUSTOMER-NAME               = INP-CUSTOMER-NAME
     CM-CUSTOMER-ADDR               = INP-CUSTOMER-ADDR
     CM-CUSTOMER-CITY               = INP-CUSTOMER-CITY
     CM-CUSTOMER-ZIP                = INP-CUSTOMER-ZIP

 WRITE-MSGOUT
     WRITE OUTPUT-REC
Parent topic: Program Painter


Customizer/Micro Focus Generator (MFG)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The AppMaster Builder Customizer enables you to write User Rules to modify and supplement the default AppMaster Builder Rule definitions.

The Micro Focus Generator (MFG) is a code generator engine that processes AppMaster Builder Rules and Customizer User Rules. The MFG also processes a specific set of structures you can use to code User Rules. MFG structures are similar to COBOL, but offer more functionality with less code.

  • Defining Customizer User Rules
  • Calling AMB and Customizer User Rules
  • MFG/FMP Compatibility
  • MFG Subsystems
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related reference
S-COBOL Structures
AMB Generator Rule Library (APSMACS)
Project Files and Directories
Example - MFG Structures


Defining Customizer User Rules

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Once defined, you can use and reuse any Customizer User Rule in any AMB program or application. A Customer User Rule can be a rule unto itself, or it can modify an AppMaster Builder Rule definition. Customizer User Rules are saved to your USERMACS project subdirectory, and AMB Rules reside in the %ProgramFiles(x86)%\Micro Focus\Enterprise Server\etc\APSMACS directory by default.

Follow these guidelines to create Customizer User Rules:

  • Code the User Rule using Micro Focus Generator (MFG) structures, traditional COBOL, S-COBOL, or any combination of the three
  • Begin with a % DEFINE MFG statement, which assigns a name to the rule and can include any number of formal argument variables. A formal argument variable receives values, called actual arguments, from the rule calls that invoke the rule.
  • End each rule with a % END MFG statement, starting in the same column as the % DEFINE statement.
  • Any statement that does not begin with % or $ is interpreted as a text line.

When you generate your programs, the MFG automatically generates COBOL from your Customizer User Rules; no extra generation steps are required.

List rules in the application definition

To include a rule in your application, you specify its rule library name in the application definition in the AMB Project Explorer. Additionally, you specify in the Location area the program location where you want to include it. Alternatively, you can code a % INCLUDE statement in the program at the desired location.

Parent topic: Customizer/Micro Focus Generator (MFG)
Related concepts
Coding Programs
Related tasks
To code Identification Division comments in the Program Painter
To code an Environment Division Special-Names statement
To code Working-Storage structures
To define data structures in COBOL format
To define data structures in Data Editor format
To include a copyfile
To include a global or local data structure
To define a DB2 table declaration and cursor declarations
To code Linkage Section structures
To define or redefine the Commarea
To begin the Procedure Division for online programs
To code the Procedure Division
To code Procedure Division comments
To define the Input-Output Section
To create a User Rule
To update a User Rule
Related reference
Example - Invoking Rules
Example - % IF Structure
Example - Looping
Example - MFG Structures
Example - Program Location Statements
Example - Rule Compilation Report
S-COBOL Structures


Calling AMB and Customizer User Rules

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To call a rule from a program, you assign a rule call to an Online Express control event, or, if writing programs in the Program Painter, you write the rule call. In each call, you pass values to variables in the rules according to your program requirements. For example, you could write a rule that performs a loop and builds a table, based on the size, data name, and PIC clause values that you pass to it.

Use one of the following methods, depending on which AMB tool you use to define your program.

AMB Component | Invocation Method
Online Express | Write a rule call using the various code options available in Online Express, such as Local Code or Miscellaneous User Code. Or, you can assign an existing rule call as the action for a control event or control point, using the Action/Event Editor or DB Call Tailoring window. In the call, you can pass values to rule variables.
Program Painter | Write a rule call at the desired program location. In the call, you can pass values to rule variables.
Parent topic: Customizer/Micro Focus Generator (MFG)


MFG/FMP Compatibility

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Micro Focus Generator provides greater processing speed and a 98% level of compatibility with its predecessor, the FMP generator. The 98% compatibility level, while difficult to quantify, is intended to indicate that nearly all statements continue to execute exactly as before. There are some exceptions:

  • Enhancements have been made to add more flexibility in coding
  • Some statements behave differently
  • Some statements do not execute in the new version

This topic describes such changes to the language, while the built-in structures are documented in the Help topic MFG Structures.

Language Enhancements

Enhancements to the language include the following:

  • The MFG generator is more forgiving of minor user indentation errors than the FMP generator, and provides more predictable control over output formatting. If you had coded the following and generated using the FMP generator:
               % IF &A = 1
               % &B = 2
               % &C = 3
              % &D = 4
           % END

    Then an "indentation decreased" error would have occurred on the line, % &D = 4.

    With the MFG generator, as long as the indentation does not terminate the scope of the % IF by starting in a column equal to or less than the starting column of the % IF statement, then the code above is accepted and executed. The following variation will process with the effect shown:

               % IF &A = 1
               ABD
               % &C = 3
              % &D = 4
              DEF
           % END

    The output is:

                   ABD
              DEF
  • The subcripts of a DECLARE table can be passed as actual arguments to a rule.
  • There is no restriction on the length of symbol names.
  • There is no limit on the number of subscripts a DECLARE table can have.
  • % LOOKUP can increment up to 20 subscripts (previous limit was 3) in performing its search.
  • % LOOKUP can accomodate expressions in the FROM clause. Previously only constants or a single variable were allowed.
  • In DECLARE tables a REDEFINED table can now be REDEFINED, as COBOL programmers would expect.
  • The LANG=TEXT parameter now enables the generator to read columns 1-32K instead of 1-80.
  • There are new % SET statements, built-in functions, and variables.

Compatibility Issues

The following are FMP/MFG compatibility issues. With the MFG:

  • The general nature of a statement must be easily recognized by the processor before any evaluation expressions are evaluated. That is, the basic structure of a statement cannot change, depending on the result of an evaluation expression.

    The most common use of evaluation expressions is to construct variable names; this use is usually not affected.

    Evaluation expressions that are affected and do not work with the MFG generator include those that introduce self-modifying logic, which is generally considered a bad practice anyway. In practically all cases, there is a more natural way to recode an expression that is much more readable and often will execute faster.

    Another type of evaluation expression that is not supported under MFG are those that have unmatched quotes. You can replace these expressions with equivalents that do not use unmatched quotes. For example:

    Replace this evaluation statement... | With...
    % <&SQ&A&B>" | % <&SQ&A&B&SQ>
    % <%&CQ AT &HH+:&MN> PM" | % <%&CQ AT &HH+:&MN PM&CQ>
  • All statements are examined whether they are executed or not. Source code that did not execute under FMP, and thus did not generate errors, might generate errors when executed under MFG. For example, in the following code, a parsing error occurs due to an unnecessary quote after SSMCLASS:
            $ISPEXEC( "VGET (SSMBPLAN",
        % ...           "SSMJOB",
        % ...           "SSMCLASS") PROFILE" )

    Taking the extra quote out fixes the problem.

  • Arguments of a rule call or built-in function must be enclosed in parentheses and separated by commas, as follows:
            $ruleName [ ( argument1 [, argument2...] ) ]
        &functionName [ ( argument1 [, argument2...] ) ]
  • The following % SET statements, although recognized, do nothing except issue a warning message:
    % SET CONTROL
% SET DELIMITERS-OPTIONAL
% SET DELIMITERS-REQUIRED
% SET CONVERT-LOWER-CASE
% SET PRESERVE-LOWER-CASE
% SET AUXILIARY-INPUT
% SET COUNT
% SET NOCOUNT
% SET STRICT-STRING-LIMIT
% SET NO-STRICT-STRING-LIMIT
% SET CONTROL-CARDS
  • The following % SET statements are recognized but do nothing:
    % SET EVAL-BRACKETS
% SET EVAL-BRACKETS-AUX
% SET LEFT-MARGIN
% SET RIGHT-MARGIN
% SET WRITE-CONTROL-LIMIT
  • The following built in functions are not supported:
    &APS-TARGET
&APS-CICS-DISPATCH
&APS-INPUT.

    To define values you need, code assignment statements

  • Do not continue non-MFG source code using the MFG syntax for continuation (% ...). For example, the following statement is invalid:
            MOVE &FLD1
        % ...  TO &FLD2

    Instead, code S-COBOL continuation as follows:

            MOVE &FLD1
        ...  TO &FLD2
  • Statements containing a verb that is evaluated at execution time are not supported. Some of them will compile cleanly to generate UNDET (undetermined) op codes which will cause warning messages to be output at execution time; others will generate syntax errors. For example:
            % <&VARIABLE>
        % <&VARIABLE>
             statementblock
        % <&VARIABLE>
             statementblock
        % ELSE
             statementblock
        % <$RULE>"QUOTED EXPRESSION"
  • Any statement that does not begin with a % or $ is treated as a text line. In the following examples, the second statement does not invoke the rule.

    Example:

            % &A = "$MY-MAC"
        <&A>(&ABC)

    To fix this, code:

            % &A = "MY-MAC"
        $<&A>(&ABC)

    Example:

            % WHILE &DEFINED (&APS-EPILOGUE)
            % SET EPILOGUE
            <&DEFVAL>

    To fix this, code:

            % WHILE &DEFINED (&APS-EPILOGUE)
            % SET EPILOGUE
            $<&SUBSTR(&DEFVAL,2)>

    In this example, the second statement is not recognized as the value of &REMARKS, but is treated as a text line. All statements indented under it are parsed successively, possibly resulting in compile errors.

            % &REMARKS = "% IF 0"
        <&REMARKS>
            THIS IS A COMMENT LINE.

    To fix this, code the following, which causes the parser to generate an undetermined type 2 node and handle the "IF 0" evaluation correctly at run-time:

            % &REMARKS = "IF 0"
        % <&REMARKS>
            THIS IS A COMMENT LINE.
  • The following syntax results in a compiler syntax error. The problem is that the nature of the statement as an assignment is hidden within the evaluation expression, and cannot be identified until execution time.
    % &<%&ARG = &QT&ARG3&DOS-SYS+-&ARG2+-&DEV+-S-&ARG1&QT>

    To fix this, code:

    % &<%&ARG> = <%&QT&ARG3&DOS-SYS+-&ARG2+-&DEV+-S-&ARG1&QT>
  • Grouping all the textual comments under a % SUBMEMBER statement (which never gets included by any rule) is not supported. To get around this, change the % SUBMEMBER statement to % IF 0, and indent all the textual comments under it to the right.
  • Floating point assignments and arithmetic is not supported in any version of the generator. FMP issued an error message; MFG does not. The net result is the same in any version - only the integer part of the value is accepted. For example, the following assignment statement produces the value 12:
            % &A  =  12.34
  • Expressions that are concatenations of evaluations and text do not support embedded non-alphanumeric characters, such as the colon ( : ) in the following example:
            % &A =  <&SQ>:<%&ST-NAME><%&COBOL-LINE><&SQ>

    To fix this, code:

            % &A =  <&SQ><%:&ST-NAME><%&COBOL-LINE><&SQ>

    Or:

            % &A =  <%&SQ:&ST-NAME&COBOL-LINE&SQ>

    Or:

            % &COLON = ":"
        % &A =  <&SQ><%&COLON><%&ST-NAME><%&COBOL-LINE><&SQ>
  • If an ELSE statement is followed by an IF statement (as opposed to an ELSE-IF statement), then there should be a line break and indentation after the ELSE and before the IF. For example:
            % ELSE IF &A = "ABC" OR &B = "DEF"

    To fix this, code:

            % ELSE
        % IF &A = "ABC" OR &B = "DEF"
  • The following statement will not compile due to the embedded less than character ( < ) which is assumed to be the start of an evaluation:
            &16+88  PF24 VALUE &SQ+<&SQ.

    To fix this, code:

            % &LEVAL = "<"
        &16+88  PF24 VALUE &SQ+&LEVAL+&SQ.

    Or:

            &16+88  PF24 VALUE "<".
  • There are approximately 30 additional built-in functions with natural-sounding names, such as &STRING. However, there is a possibility that the names of these additional functions conflict with variable names in existing code used previously with the FMP. If you encounter different behavior when running a rule, scan the code for names which conflict with the names of the MFG built-ins.

Unsupported Syntax

The following are samples of syntax encountered in actual production rules which were presumably never executed because they are not compilable with the FMP generator, and are not supported in MFG.

Example:

$DBDC-GEN-MSG( "9080", "NOGEN", &EDIT-NAME) "01-99")

To fix this, change the right parenthesis following &EDIT-NAME to a comma. This appears to be a typographical error.

Example:

$GASCR+-SELECT = XXXXA-CONFIRM                      01

This is an invalid syntax for a rule call and appears to be a typographical error.

Example:

% IF &T-CODE NOT DEFINED

To fix this, code:

% IF NOT &DEFINED(&T-CODE)
Parent topic: Customizer/Micro Focus Generator (MFG)
Related reference
Customizer/Micro Focus Generator (MFG)
MFG Structures
&APS-BLANK-STATUS


MFG Subsystems

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Micro Focus Generator (MFG) is composed of several subsystems that work together. In addition to being logical groups of modules, the IG is implemented as a set of DLLs, generally one per subsystem or group. For development purposes, the source files are organized along the same lines, with all the source components in one subdirectory.

The groups can be organized into larger logical units as follows.

  • Main programs and high-level control of processing
    • IG - Invokes the main MFG entry point in the FMPDRVR DLL.
    • FMPDRVR - Contains the mainline logic, exception handling, initial bootstrap program, and the main entry point for the MFG (as a DLL).
    • PARM - Handles command line and control file input.
    • IGDRVR - Contains the MFG exception handling routines for unexpected error conditions that are first detected by the operating system or C run-time library. The messages typically indicate a catastrophic failure. Except where noted, the severity of these errors is FATAL, and the MFG terminates with all output buffers flushed.
  • Compiler "front end"
    • PARSE - Performs the parsing, intermediate representation generation, and optimization phases.
    • LEX - The scanner (or lexical analysis) pass of the MFG compiler.
    • IP - A set of low-level service routines for parsing.
  • Execution engine
    • VM - Executes the intermediate representation.
    • BUILTIN - An extension to the Virtual Machine (VM) that implements the built-in macros and variables.
    • INFRA - A set of infrastructure routines that provide VM services .
  • Processing of generated output: OUTPUT - Structures and writes the generated output
  • Writing compiled macros in a form for later use: STORE - Writes out the intermediate form of compiled macros to a DLL or Assembly language source form.
  • Sets of service routines
    • FMPIO - A set of low-level I/O service routines.
    • FMPMSGS - Contains the externalized message text that is used for error messages and command line help.
    • GLOBAL - A set of data and MFG service routines that are used by other groups.
    • SRVCS - Provides access to system-dependent services, such as DLL loading and memory management.
Note: Each MFG subsystem has a corresponding series of error messages called IG messages. You can find them in your online Help under AppMaster Builder > Reference > Error Messages > IG - Micro Focus Generator messages.
Parent topic: Customizer/Micro Focus Generator (MFG)


Data View Manager

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

A database view is a definition that tells AppMaster Builder what database records it can use. Use the Data View Manager to import any of the following database source into an AppMaster Builder database view:

  • IMS
  • VSAM
  • SQL DDL

Each database view you create can reference sources for one or more database environments. For example, if your application accesses information in both VSAM files and SQL databases, you can create one database view that contains the record information for both.

  • Data Source Files
  • Loading Data Sources
  • Coding DDI Sources
  • Coding SQL DDL Sources
  • Coding SQL Schema Sources
  • Customizing Data Views
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
The AppMaster Builder Tool Set


Data Source Files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You define data view records by loading source files into the data view. Then you build the data view based on the sources you've loaded. Some source file types, such as IMS PSBs and SQL DDL contain native code. Other sources, such as IMS DDI and VSAM, are created specifically for AppMaster Builder and require you to code a series of DDI statements. For more information on coding DDI statements, see Coding DDI Sources.

AppMaster Builder looks for data source files in the following directories, all subdirectories of your project:

Source Type | Directory
IMS PSB | PSBSRC
IMS DBD | DBDSRC
IMS DDI | DDISRC
VSAM | DDISRC
SQL DDL | SQLDDL
Parent topic: Data View Manager
Related concepts
Coding DDI Sources


Loading Data Sources

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can load and build IMS source, VSAM source, and SQL DDL source either from the AppMaster Builder IDE or from the command line at an Enterprise Developer command prompt.

  • Loading IMS
  • Loading VSAM
  • Loading SQL
Parent topic: Data View Manager


Loading IMS

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can load IMS directly into a data view.

Before you begin, be sure that:

  • Native PSB source is in your project PSBSRC directory
  • Native DBD source is in your project DBDSRC directory
  • DDI source you have written is in the DDISRC directory
    Note: The name of each DDI source file you create must match the name of its corresponding DBD source file.

Loading IMS from the IDE

You can load IMS directly into AppMaster Builder via your PSB source. All DBD source referenced by the PSB source is loaded automatically with the PSB source. You can also provide additional information for the data view by creating a DDISRC file containing DDI statements that identify IMS segments and their corresponding COBOL copybook record descriptions. This is also loaded automatically. For details on coding DDI statements for IMS, see Coding DDI Sources.

Loading IMS into a COBOL project

You can specify a COBOL project into which AppMaster Builder simultaneously loads IMS sources when you load them into your data view. AppMaster Builder automatically loads IMS sources into your COBOL Project when you have the Compile in COBOL Project check box selected in the AppMaster Builder Preferences page. Click the Preferences button on the AppMaster Builder Explorer toolbar to access the preferences. You can load sources into the COBOL project as well. See Compiling in a COBOL project for more information.

Parent topic: Loading Data Sources
Related concepts
Coding DDI Sources
Compiling in a COBOL project
Related tasks
To load and build IMS into a database view
To set AppMaster Builder preferences


Loading VSAM

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To load VSAM into a data view, you must first create a DDISRC file that contains specific DDI statements to define your VSAM files and records. Save these DDISRC files to the DDISRC directory of your project. For details on coding DDI statements for VSAM, see Coding DDI Sources.

Loading VSAM from the IDE

You can load the DDI source you have created directly into AppMaster Builder and then build it using the Eclipse IDE.

Parent topic: Loading Data Sources
Related concepts
Coding DDI Sources
Related tasks
To load and build VSAM into a database view
To set AppMaster Builder preferences


Loading SQL

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You have several options for loading SQL source into a data view. You can either load native SQL DDL or create SQL schemas from your SQL DDL source. It is highly recommend that you create SQL schemas rather than loading native SQL DDL. The advantage to creating a schema over loading native SQL DDL is that the schema, which is primarily a list of tables, is easier to maintain. A single SQL schema can reference tables from several SQL DDL files. Therefore, if a table changes you only need to edit it in one place, then rebuild the schemas that include it.

As an alternative, you can also load SQL DDL source from the command line.

Before loading your SQL, set the properties that describe the SQL you are loading. For example, you might be loading SQL that is for HCO (DB2) or SQL that is specifically for Micro Focus's SQL Option for DB2. You can also specify whether or not to allow mixed case in your SQL tables, and whether or not you want AppMaster Builder to automatically generate a REDEFINES statement for any copybook field whose corresponding SQL field is a DATE, TIME, or TIMESTAMP. This lets you specify a particular date and/or time format, such as U.S. or European.

Loading SQL DDL Source

Before you begin, be sure that the SQL DDL source is in your project SQLDDL directory. If your SQL DDL source file contains a CREATE SUBSCHEMA statement, all tables you want in the data view must be in that file. For information on coding SQL DDL source, see Coding SQL DDL Sources.

Note: It is recommended that you load SQL using SQL schemas as a better alternative to directly loading SQL DDL source.

Loading a SQL Schema

To take make the best use of this feature, create a series of SQL DDL files that each contain one table, along with any associated indexes or views on that table, and no CREATE SUBSCHEMA statement. You can include each table in as many SQL schemas as you like.

Parent topic: Loading Data Sources
Related concepts
Coding SQL DDL Sources
Related tasks
To set properties for a specific database view
To load and build SQL DDL source into a database view
To load and build a SQL schema into a database view


Coding DDI Sources

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To build VSAM into a data view, you must code a series of DDI statements to define your records. You can also supply your IMS with additional information on COBOL records by coding DDI statements.

The purpose of VSAM DDI source is to supply your VSAM files, record indexes, and COBOL record descriptions to a data view. See DDI statements - VSAM for complete information on coding VSAM DDI source.

The purpose of a DDI source for an IMS data view is to establish a correlation between the IMS you load and build into a data view and the COBOL records in the corresponding copybook. See DDI statements - IMS DB for complete information on coding IMS DDI source.

Parent topic: Data View Manager
Related concepts
Data Source Files
Loading IMS
Loading VSAM
Related tasks
To edit database source files
To create new database source files
Related reference
DDI statements - IMS DB
DDI statements - VSAM


Coding SQL DDL Sources

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You load native SQL DDL into AppMaster Builder data views. Follow instructions in your SQL documentation for coding these statements. These restrictions pertain to coding SQL DDL sources:

  • Do not use TIMESTAMP as a column name. AppMaster Builder recognizes TIMESTAMP as a data type.
  • If you have the Micro Focus Generator (MFG) turned off, table names cannot exceed 18 characters.
  • If you have the MFG turned on, table names cannot exceed 128 characters.
  • Column names cannot exceed 30 characters.
  • Tables that use reserved COBOL data names for column names are loaded into AppMaster Builder with -cpy appended to the column name.
Parent topic: Data View Manager
Related concepts
Loading SQL
Related tasks
To edit database source files
To create new database source files


Coding SQL Schema Sources

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

While AppMaster Builder provides an interface for you to use to build SQL schemas, you can also code them into your SQL DDL source as an alternative. See CREATE SUBSCHEMA for complete information on coding SQL schema files.

Parent topic: Data View Manager
Related tasks
To edit database source files
To create new database source files
Related reference
CREATE SUBSCHEMA


Customizing Data Views

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can customize the way SQL data views are used in the generation of your COBOL. For example, you can provide alternate names for copybooks, dictate the names of tables, and override variables. See D2 Statements for complete information.

Parent topic: Data View Manager
Related reference
D2 Statements


Data Structure Editor

The Data Structure Editor enables you to code data structure project objects.

Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
The AppMaster Builder Tool Set


Report Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

TheAppMaster Builder Report Painter enables you to produce a report by designing the physical appearance of the report, rather than the detailed procedures necessary to produce that report. Instead of writing COBOL statements that determine the relationship of output lines, recognize page overflow, construct headers and footers, recognize logical data groups, format output lines, map data to output fields, and perform data calculations, AMB sets up the routines needed to produce the report in the requested format. All you do is paint a visual representation of the report and specify which items control the report logic.

  • Paint Report Layouts
  • Creating Report Programs
  • Sample Programs
Parent topic: Developing Applications in the AppMaster Builder Perspective


Paint Report Layouts

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

First, you paint the report layouts, called mock-ups, in the Report Painter, which provides a free-form definition facility. You can define the mock-up by typing literals and output fields to visually represent the report output. You can specify both floating numeric and alphanumeric output edit masks directly within the report mock-up. AMB automatically stores the report mock-ups, making them available as report templates or for use in multiple programs.

Before you can paint report mock-ups, you must first create your application definition and name your report(s) in the Project Explorer.

  • Painting Report Mock-Ups
  • Report Mock-Up Rules
  • Sample Report Mock-Up
Parent topic: Report Painter
Related concepts
AppMaster Builder Projects
Related tasks
To start the Report Painter


Painting Report Mock-Ups

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You define the mock-up by typing literals and output fields to visually represent the report output. The report mock-up determines the columns where literals and data items print. Your report program code determines the lines where they print.

Parent topic: Paint Report Layouts
Related tasks
To paint a report mock-up


Report Mock-Up Rules

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. The first character of the report mock-up name must be alphabetic, @, or #; the remaining characters can be alphabetic, numeric, @, $, or #.
  2. Reports can be a maximum of 200 lines and 247 columns.
  3. Paint lines as they appear within their report group.
  4. Include any blank lines that appear between the first and last lines of a report group in the mock-up.
  5. To minimize programming, include blank lines preceding or following a report group in the mock-up.
  6. Paint the line or lines that compose a DETAIL group only once.
  7. Each field that composes a line must be shown with a COBOL picture for variable data or with the literal for fixed data.
  8. Within the layout of a line, position each field in the desired printing position with exact spacing between fields.
  9. Show a floating-point item in the mock-up with a COBOL picture in floating-point form. The same picture must be repeated in a PIC phrase in the corresponding SOURCE, SUM, or VALUE statement.
  10. In your program, the data field PIC strings on the mock-up must match the detail line data item descriptions in your Report Section. Report Writer matches the mock-up fields to the program field descriptions from left to right, from top to bottom.
Parent topic: Paint Report Layouts


Sample Report Mock-Up

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following is a sample report mock-up for Wonderful Widgets, Inc.:

***************************TOP OF DATA********************
                 WONDERFUL WIDGETS INCORPORATED

                          STOCK REPORT

                           XXXXXX XXX

                   MID-ATLANTIC
                   STOCK REPORT
                    XXXXXX XXX
LOCATION       LAST COUNT   QUANTITY   QUANTITY   QUANTITY
                  DATE      IN STOCK    ISSUED    RECEIVED
XXXXXXXXXXXX    99/99/99     ZZZ,ZZ9     ZZ,ZZ9    ZZZ,ZZ9

                           ---------  ---------  ---------
TOTAL BY LOCATION:         Z,ZZZ,ZZ9   Z,ZZZ,ZZ9  Z,ZZZ,ZZ9
TOTAL NUMBER OF SALES BY LOCATION:       ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS IN STOCK:      Z,ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS ISSUED:        Z,ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS RECEIVED:      Z,ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS SOLD:          Z,ZZZ,ZZ9

                                                  PAGE ZZZ9

          *****  END OF REPORT  *****
Parent topic: Paint Report Layouts


Creating Report Programs

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This section outlines the steps you must take to code Working-Storage entries and program logic for your reports.

Before you code reports into your programs, see Coding Programs.

  • Define Report Logic
  • Report Mapping Rules
  • Structure Summary
Parent topic: Report Painter
Related concepts
Coding Programs
Related tasks
To start the Program Painter


Define Report Logic

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

After you create a mock-up, you define the report logic in the Program Painter using AMB Report Writer structures. Report Writer structures let you automatically perform paging, calculate field values, test and execute control breaks, generate multiple reports, and generate all logic necessary to map fields between reports and databases or files. You can include multiple reports in a single program. Follow this process:

  1. Name the input and output files

    First, using the Program Painter IO and FD keywords, name the input data file, the output report file, and the report itself.

  2. Add a Report Section

    Then, with the Program Painter RED, MOCK, and 01 keywords, you add a Report Section naming the report and defining the format of each report named. There are two types of format entries.

    • Those that describe the physical aspects of the report format, such as the maximum number of lines per page, where report lines appear on the page, and which data items are controls.
    • Those that describe the function, format, and characteristics of each report line.
  3. Determine your report groups

    AMB categorizes the report lines into report groups, which are groups of report lines that make up the headings, body, and footings of the report. Report groups are:

    • Report Heading - Header lines that print once at the beginning of a report. Optionally, it can appear on a page by itself.
    • Page Heading - Header lines that print at the top of each page.
    • Control Heading - Header lines that print each time a control break occurs.
    • Detail - Detail lines that are the body of the report. Detail lines are not required for summary reports.
    • Control Footing - Line(s) of totals that print at the end of each detail group, immediately following the detail lines.
    • Page Footing - Footer lines that print at the bottom of each page.
    • Report Footing - Footer lines that print once at the end of a report.

    The following table shows a sample mock-up with the various report group types.

    Report Heading

    WONDERFUL WIDGETS INCORPORATED
STOCK REPORT
XXXXXX XXX

    Page Heading

    MID-ATLANTIC
STOCK REPORT
XXXXXX XXX

    Control Heading

    LOCATION LAST COUNT QUANTITY QUANTITY QUANTITY
DATE IN STOCK ISSUED RECEIVED

    Detail Line

    XXXXXXXXXXXX 99/99/99 ZZZ,ZZ9 ZZ,ZZ9 ZZZ,ZZ9
--------- --------- ---------

    Control Footing

    TOTAL BY LOCATION: Z,ZZZ,ZZ9 Z,ZZZ,ZZ9 Z,ZZZ,ZZ9

    Control Footing Final

    TOTAL NUMBER OF SALES BY LOCATION: ZZZ,ZZ9
TOTAL WONDERFUL WIDGETS IN STOCK: Z,ZZZ,ZZ9
TOTAL WONDERFUL WIDGETS ISSUED: Z,ZZZ,ZZ9
TOTAL WONDERFUL WIDGETS RECEIVED: Z,ZZZ,ZZ9
TOTAL WONDERFUL WIDGETS SOLD: Z,ZZZ,ZZ9

    Page Footing

    PAGE ZZZ9

    Report Footing

    ***** END OF REPORT *****
  4. Further define detail lines

    Entries for the detail lines that make up the body of the report describe the characteristics of the data items, such as the format, its placement in relation to the other data items, and any control factors. You use the following statements to define the line contents.

    • SOURCE statement - Use this statement to map a data item to the report output field, using the current value of this data item each time the field prints.
    • REFERENCE statement - Use this statement to identify a non-printing data item for summing in a control footing.
    • SUM statement - Use this statement to total the values in the named fields. When a SUM statement executes, AMB automatically:
      • Creates a Working-Storage SUM accumulator field for each data item.
      • Increments the SUM accumulator.
      • Prints the accumulated values at control break time.
      • Resets the SUM accumulator to zero after printing.
    • VALUE statement - Use this statement to designate a literal value to print for the field each time the line prints.
  5. Set control breaks

    You use controls to specify how to arrange the data your report displays. For example: you might want to display detail lines arranged by sales territories within cities or states or both. You can have up to 28 control breaks. AMB processes controls from the most inclusive down to the least inclusive, that is from major to minor. When a data item designated as a control changes value, such as a monthly change in a date field, a control break occurs, and AMB:

    • Prints the detail line that caused the break.
    • Prints control headings for any lower-level data items, followed by the heading for the data item that caused the control break.
    • Prints control totals for the current and lower-level data items.
    • Clears all associated counters and accumulators.
  6. Produce the report in the Procedure Division

    In the Procedure Division, you open your input and output files, execute and print the report, and close the files, using the following Report Writer statements:

    • INITIATE statement - perform functions in the Report Writer analogous to the OPEN statement for individual files. The figure below illustrates INITIATE processing.
      Figure 1. INITIATE Logic Processing
      INITIATE Logic Processing
    • GENERATE statement - produces the body of the report, and executes and prints the entire report. When this statement executes, AMB:
      • Prints specified headings and footings.
      • Increments and resets counters and accumulators as necessary.
      • Obtains source information.
      • Produces sum information.
      • Moves values to the data item(s) in the report group entries.
      • Tests controls.
      • Prints detail lines.
      • Pages the report.
      • Prints the all lines required when a control break occurs.

        The next two figures illustrate GENERATE processing.

        Figure 2. GENERATE Logic Processing 1
        GENERATE Logic Processing 1
        Figure 3. GENERATE Logic Processing 2
        GENERATE Logic Processing 2
    • Optional USE BEFORE REPORTING statement - specifies additional processing for a heading or footing report group, such as a calculation or a line edit, prior to printing.
    • TERMINATE statement - completes the processing of a report. It is analogous to the CLOSE statement for individual files. The following figure illustrates TERMINATE processing.
      Figure 4. TERMINATE Logic Processing
      TERMINATE Logic Processing
  7. Use special counters

    AMB provides two counters that you can use in any Procedure Division statement.

    • LINE-COUNTER - Reference LINE-COUNTER to determine when to print a PAGE HEADING or a PAGE FOOTING report group. The maximum value of the LINE-COUNTER is based on the number of lines per page specified in the PAGE LIMIT(S) clause.
    • PAGE-COUNTER - Reference PAGE-COUNTER in a SOURCE statement to print the page number.
  • Code Working-Storage
  • Code Report Logic
  • Multiple SUM or SOURCE Statements
Parent topic: Creating Report Programs
Related tasks
To start the Report Painter
To paint a report mock-up
To code input-output statements for reports
To code control breaks in reports
To code a report page description
To specify a report mock-up
To identify report groups
To map report lines
To map report fields
To define non-printing detail items
To sum data items in a report


Code Working-Storage

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The process of adding Working-Storage entries is as follows:

  1. Identify the report
  2. Determine control breaks
  3. Describe the printed page
  4. Identify the mock-up
  5. Identify each report group
  6. Map report lines
  7. Map report fields - indicate which data items supply values to output fields
  8. Define non-printing detail items - specify non-printing detail items that you want Report Writer to sum and total for control breaks, such as an employee count or the number of sales in a given location
  9. Sum the data items - specify the data items you want to sum
Parent topic: Define Report Logic
Related tasks
To code Working-Storage entries for reports
To identify a report in Working-Storage


Code Report Logic

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Code the Procedure Division logic under the NTRY (or PROC) keyword to produce and generate the report.

In AMB with all versions of COBOL except OS/VS COBOL, you can use the automatic page and date features by coding ACCEPT statements in your Procedure Division Code, as follows:

ACCEPT WS-fieldname FROM DATE
ACCEPT WS-fieldname FROM PAGE

For example:

   NTRY
           OPEN INPUT INPUT-FILE
           ...OUTPUT REPORT-OUTPUT-FILE
           ACCEPT WS-DATE-HOLD FROM DATE
           MOVE WS-DATE-YY-X TO WS-DATE-YY
           MOVE WS-DATE-MM-X TO WS-DATE-MM
           MOVE WS-DATE-DD-X TO WS-DATE-DD
           INITIATE STOCK-REPORT
           REPEAT
               READ INPUT-FILE INTO WS-PART-STOCK-REC
           UNTIL AT END ON INPUT-FILE
               GENERATE DETAIL-LINE
           TERMINATE STOCK-REPORT
           CLOSE INPUT-FILE
           ... REPORT-OUTPUT-FILE
Parent topic: Define Report Logic
Related tasks
To code report logic
To specify multiple reports


Multiple SUM or SOURCE Statements

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Instead of coding individual statements to source or sum sequential suffixed data items or array elements, AMB provides an iterative expression feature that lets you code only one SOURCE or SUM statement, which generates multiple statements. This construct replaces coding repetitive series when incrementing a data item or subscript.

  • Suffixed Data Elements
  • Array Items
Parent topic: Define Report Logic


Suffixed Data Elements

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The iterative expression syntax for numerically suffixed data elements is:

dataitem-#startnumber[/endnumber[/increment]]

Where the parameters are:

# | The pound sign (#) indicates the starting number of an iteration.
startnumber | Starting number of the iteration. Leading zeros in startnumber are generated in the SUM or SOURCE statements.
/ | The first slash separating numeric descriptors of an iteration translates to THRU, the second slash to BY.
endnumber | Top limit of the increment range, or bottom limit if the increment is negative.
increment | The increment is the number by which the iteration is incremented; default is 1.

For example:

SOURCE MONTH-#1/6 BLANK WHEN ZERO

Generates an iteration of six SOURCE statements, suffixed numerically, 1 through 6, for example, MONTH-1 through MONTH-6. If you specify only one number, the iteration assumes the starting number to be 1. For example, SOURCE MONTH-#6 is equivalent to SOURCE MONTH-#1/6.

Without the iterative expression, you would code the previous statement, SOURCE MONTH-#1/6 BLANK WHEN ZERO, as follows:

SOURCE MONTH-1 BLANK WHEN ZERO
SOURCE MONTH-2 BLANK WHEN ZERO
SOURCE MONTH-3 BLANK WHEN ZERO
SOURCE MONTH-4 BLANK WHEN ZERO
SOURCE MONTH-5 BLANK WHEN ZERO
SOURCE MONTH-6 BLANK WHEN ZERO

For example, the following four SUM statements:

SUM MONTH-9-DATA
SUM MONTH-10-DATA
SUM MONTH-11-DATA
SUM MONTH-12-DATA

Can instead be coded as:

SUM MONTH-#9/12-DATA

This next example increments an iteration of SOURCE statements by 2 instead of the default 1.

SOURCE ELEMENT-#6/12/2

Which generates:

SOURCE ELEMENT-6
SOURCE ELEMENT-8
SOURCE ELEMENT-10
SOURCE ELEMENT-12

The PIC clause for each SUM or SOURCE statement generated by the iterative expression is taken from the mock-up. AMB matches the mock-up and detail line data item descriptions as the increment statements generate.

Parent topic: Multiple SUM or SOURCE Statements


Array Items

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The iterative expression syntax for a complex array is the following:

1-dimensional array:

arrayitem
          (#startnum[/endnum1[/increment1]]
          1st subscript range

2-dimensional array:

arrayitem
          (#startnum[/endnum1[/increment1]],
          1st subscript range
#startnum[/endnum2[/increment2]]
          2nd subscript range

3-dimensional array:

arrayitem
          (#startnum1[/endnum1[/increment1]],
          1st subscript range
#startnum2[/endnum2[/increment2]],
          2nd subscript range
#startnum3[/endnum3[/increment3]])
          3rd subscript range

The following rules apply:

  • Parentheses indicate an array.
  • Use up to three # symbols to indicate three dimensions of an array.
  • Separate the subscript ranges with commas.
  • All of the symbols used for generating suffixed data items, above, apply to each array range.
  • Each dimension is described by a separate Data Division entry with an OCCURS clause.

The following SOURCE statements reference a 2 by 3 array:

SOURCE ARRAY-ITEM (1, 1)
SOURCE ARRAY-ITEM (1, 2)
SOURCE ARRAY-ITEM (1, 3)
SOURCE ARRAY-ITEM (2, 1)
SOURCE ARRAY-ITEM (2, 2)
SOURCE ARRAY-ITEM (2, 3)

Can, instead, be coded as:

SOURCE ARRAY-ITEM (#2, #3)

The following iterative expression:

SOURCE ARRAY-ITEM (#3, #2)

Replaces the following code:

SOURCE ARRAY-ITEM (1, 1)
SOURCE ARRAY-ITEM (1, 2)
SOURCE ARRAY-ITEM (2, 1)
SOURCE ARRAY-ITEM (2, 2)
SOURCE ARRAY-ITEM (3, 1)
SOURCE ARRAY-ITEM (3, 2)

The following statement produces SUM statements for each element of a three dimensional array of 3 by 2 by 3:

SUM TABLE ELEMENT (#3, #2, #3)

The following iterative expressions are examples of ranges within a one dimensional array:

SUM EXT-SALES-DOLLARS (#1/3)        PIC Z,ZZ9
     SUM QTR-1-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#4/6)   PIC Z,ZZ9
     SUM QTR-2-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#7/9)   PIC Z,ZZ9
     SUM QTR-3-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#10/12) PIC Z,ZZ9
     SUM QTR-4-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM YR-SALES-DOLLARS           PIC $$$$,$$$
Parent topic: Multiple SUM or SOURCE Statements


Report Mapping Rules

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The sequence in which mock-up fields are matched with the data item descriptions is the same as a page of text is read, from left to right across each line of the mock-up starting with the top line and continuing to the bottom.

AppMaster Builder matches the report mock-up fields to the data item description entries in your program according to the following rules:

  • The following are considered literals:
    • The COBOL picture character A.
    • Any one or more consecutive non-space, non-picture characters.
    • Any single COBOL picture character, that is preceded and followed by a space. Exception to this rule: 9 and X.
    • A string of hyphens because of its frequent use for underlining.
  • A single COBOL picture character, such as -, X, Z, or 9, that is embedded in a string of non-blank, non-picture characters is considered part of a literal. For example, the following are literals:

    and the following are pictures beside literals:

  • AMB generates a VALUE statement for each literal in the mockup, and does not match the literal with the data item descriptions in the program.
  • Any legal COBOL picture longer than one character is considered a COBOL picture, except for the letter S and the hyphen (-), and matches it to the next data item description in the program.
  • AMB considers any consecutive PIC characters in the mock-up as one PIC character string, unless the string is matched with PIC clauses in multiple, consecutive SOURCE statements.
  • AMB assigns each PIC character string as the PIC for the next sequential data item description, unless the next description contains a PIC clause.
  • When a data item description contains a PIC clause, AMB compares it with an equal number of characters in the mock-up, starting with the next sequential, unassigned character in the mock-up.
  • When comparing a data item description entry with a PIC clause to an equal number of characters in the mock-up and a non-match occurs, AMB continues the comparison by moving one position to the right until it finds a match. AMB considers the non-matched characters from this process to be a literal, and generates a VALUE entry that precedes the data item description with the PIC clause that initiated the comparison.
  • When a PIC clause in a data item description does not match any series of mock-up characters from the start of a comparison to the end of the mock-up, AMB terminates processing and generates an error message.
  • If a data item contains a PIC clause in a SOURCE or SUM statement, it indicates that the next matching COBOL picture in the mock-up is the COBOL picture for the statement. AMB compares it with an equal number of the next unassigned characters. If no match occurs, the comparison moves one position to the right until a match is found. If no match is found, an error message is printed. For example:

    Report mock-up:

    Report program:

    Report Writer matches DATA-1 and DATA-2 directly to the mock-up. It then matches the PIC clause in the SOURCE statement for DATA-3 to the first two X characters under FIELD-3, and the two remaining X characters to DATA-4. If you omit the PIC clause on the DATA-3 SOURCE statement, an error occurs. If you omit the DATA-4 SOURCE statement, AMB considers the XX a literal, because there are no source statements remaining.

Parent topic: Creating Report Programs
Related tasks
To map report fields
To map report lines


Structure Summary

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

For this task...

Use this structure...

Coding the Input/Output Section

01 or IO keyword

Coding Working-Storage structures

WS keyword

Identifying the report

RED keyword

Describing the report page for printing

CONTROL PAGE LIMIT

Identifying the report mock-up

MOCK keyword

Indicating the report groups

  • 01 keyword
  • TYPE clause

Mapping report lines

  • 01 keyword
  • MOCKUP statement

Mapping report fields

  • 01 keyword
  • REFERENCE statement
  • SOURCE statement
  • SUM statement
  • VALUE clause

Coding Procedure Division logic

  • GENERATE statement
  • INITIATE statement
  • NTRY keyword
  • TERMINATE statement

Coding declarative procedures to modify default processing before printing headings or footings

  • DPAR keyword
  • USE BEFORE REPORTING clause

Using COBOL picture characters as literals in the mock-up

VALUE clause

Overriding the standard COBOL WRITE statement

WRITE ROUTINE clause

Highlighting or underscoring report lines

OVERPRINT statement

Parent topic: Creating Report Programs
Related reference
Report Writer Structures
Program Painter Keywords


Sample Programs

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The sample programs shown here include examples of using Report Writer structures and iterative expressions.

  • Report Writer Structures - Sample Program
  • Iterative Expressions - Sample Program
Parent topic: Report Painter


Report Writer Structures - Sample Program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This program includes a report mock-up, complete program, generated source code, and the final printed report derived from the program.

Report Mock-up

                 WONDERFUL WIDGETS INCORPORATED

                          STOCK REPORT

                           XXXXXX XXX

                          MID-ATLANTIC
                          STOCK REPORT
                           XXXXXX XXX

LOCATION          LAST COUNT     QUANTITY IN    QUANTITY    QUANTITY
                    DATE          STOCK         ISSUED     RECEIVED

XXXXXXXXXXXX    99/99/99         ZZZ,ZZ9      ZZZ,ZZ9     ZZZ,ZZ9

                               ---------     ---------  ---------
TOTAL BY LOCATION:             Z,ZZZ,ZZ9     Z,ZZZ,ZZ9  Z,ZZZ,ZZ9

TOTAL NUMBER OF SALES BY LOCATION:       ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS IN STOCK:      Z,ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS ISSUED:        Z,ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS RECEIVED:      Z,ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS SOLD:          Z,ZZZ,ZZ9

                                                         PAGE ZZZ9
                             *****  END OF REPORT  *****

Program Painter Source

 IO  INPUT-FILE ASSIGN [TO] DYNAMIC FILEIN
 IO  REPORT-OUTPUT-FILE ASSIGN "REPTOUT".
 FD  INPUT-FILE
     LABEL RECORDS ARE STANDARD
     BLOCK CONTAINS 0 CHARACTERS.
 01  PART-STOCK-REC              PIC X(80).
FD  REPORT-OUTPUT-FILE
     LABEL RECORDS ARE STANDARD
     REPORT IS STOCK-REPORT.
WS  WS-PART-STOCK-REC.
     05  WS-LOCATION-CODE
         ... PIC X(12)  VALUE SPACES.
     05  WS-LAST-COUNT-DATE.
         10  WS-LAST-COUNT-MONTH PIC 99    VALUE 0.
         10  WS-LAST-COUNT-DAY   PIC 99    VALUE 0.
         10  WS-LAST-COUNT-YEAR  PIC 99    VALUE 0.
     05  WS-QTY-IN-STOCK         PIC 9(6)  VALUE 0.
     05  WS-QTY-ISSUED           PIC 9(6)  VALUE 0.
     05  WS-QTY-RECEIVED         PIC 9(6)  VALUE 0.
     05  WS-NO-OF-SALES          PIC 9(4)  VALUE 0.
     05  FILLER
         ...PIC X(40) VALUE SPACES.
 WS  WS-DATE.
     05  WS-DATE-MM              PIC 9(2).
     05  WS-DATE-DD              PIC 9(2).
     05  WS-DATE-YY              PIC 9(2).
 WS  WS-DATE-HOLD.
     05  WS-DATE-YY-X            PIC 9(2).
     05  WS-DATE-MM-X            PIC 9(2).
     05  WS-DATE-DD-X            PIC 9(2).

 RED STOCK-REPORT
     CONTROLS ARE FINAL WS-LOCATION-CODE
     PAGE LIMIT IS 50
     FIRST DETAIL 10
     LAST DETAIL 40
     FOOTING 47.
 MOCK STCKRPT
 01  TYPE IS REPORT HEADING NEXT GROUP
         NEXT PAGE
     MOCKUP LINES 1 THRU 6
     SOURCE WS-DATE

 01  TYPE IS PAGE HEADING.
     MOCKUP LINES 7 THRU 9
     SOURCE WS-DATE

 01  TYPE IS CONTROL HEADING WS-LOCATION-CODE.
     MOCKUP LINES 10 THRU 13

 01  DETAIL-LINE TYPE IS DETAIL.
     MOCKUP LINE 14
     SOURCE WS-LOCATION-CODE      GROUP INDICATE
     SOURCE WS-LAST-COUNT-MONTH  PIC 99
     SOURCE WS-LAST-COUNT-DAY    PIC 99
     SOURCE WS-LAST-COUNT-YEAR   PIC 99
     SOURCE WS-QTY-IN-STOCK
     SOURCE WS-QTY-ISSUED
     SOURCE WS-QTY-RECEIVED
     REFERENCE WS-NO-OF-SALES    PIC ZZZ9

 01  TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
     MOCKUP LINES 15 THRU 21
     SUM WS-QTY-IN-STOCK
     SUM WS-QTY-ISSUED
     SUM WS-QTY-RECEIVED
     SUM WS-NO-OF-SALES

 01  TYPE IS CONTROL FOOTING FINAL.
     MOCKUP LINES 22 THRU 30
     SUM WS-QTY-IN-STOCK
     SUM WS-QTY-ISSUED
     SUM WS-QTY-RECEIVED
     SUM WS-NO-OF-SALES

 01  TYPE IS PAGE FOOTING.
     MOCKUP LINE 31
     SOURCE PAGE-COUNTER

 01  TYPE IS REPORT FOOTING LINE PLUS 2.
     MOCKUP LINES 32 THRU 33

 NTRY
     OPEN INPUT INPUT-FILE
     ...OUTPUT REPORT-OUTPUT-FILE
     ACCEPT WS-DATE-HOLD FROM DATE
     MOVE WS-DATE-YY-X TO WS-DATE-YY
     MOVE WS-DATE-MM-X TO WS-DATE-MM
     MOVE WS-DATE-DD-X TO WS-DATE-DD
     INITIATE STOCK-REPORT
     REPEAT
         READ INPUT-FILE INTO WS-PART-STOCK-REC
     UNTIL AT END ON INPUT-FILE
         GENERATE DETAIL-LINE
     TERMINATE STOCK-REPORT
     CLOSE INPUT-FILE
     ... REPORT-OUTPUT-FILE

Generated Source

 %   &AP-GEN-VER = 3000
 %   &AP-PGM-D = "STOCK1"
 %   &AP-GEN-DC-TARGET = "PC"
 %   &AP-TP-ENTRY-KYWD-SEEN = 1
 %   &AP-FILE-CONTROL-SEEN = 1
 IDENTIFICATION DIVISION.
 PROGRAM-ID.                      STOCK1.
 AUTHOR.                          AP-SYSTEM GENERATED.
 DATE-WRITTEN.                    140125.
 DATE-COMPILED.                   &COMPILETIME.
 ENVIRONMENT DIVISION.
 CONFIGURATION SECTION.
 SOURCE-COMPUTER.                 &SYSTEM.
 OBJECT-COMPUTER.                 &SYSTEM.
 INPUT-OUTPUT SECTION.
 FILE-CONTROL.
     INPUT-FILE ASSIGN [TO] DYNAMIC FILEIN.
     REPORT-OUTPUT-FILE ASSIGN "REPTOUT".
 DATA DIVISION.
 FILE SECTION.
 FD  INPUT-FILE
     LABEL RECORDS ARE STANDARD
     BLOCK CONTAINS O CHARACTERS.
 01  PART-STOCK-REC             PIC X(80).
 FD  REPORT-OUTPUT-FILE
     LABEL RECORDS ARE STANDARD
     REPORT IS STOCK-REPORT.

 WORKING-STORAGE SECTION.
 01  WS-PART-STOCK-REC.
     05  WS-LOCATION-CODE        PIC X(12) VALUE SPACES.
     05  WS-LAST-COUNT-DATE.
         10  WS-LAST-COUNT-MONTH PIC 99    VALUE O.
         10  WS-LAST-COUNT-DAY   PIC 99    VALUE O.
         10  WS-LAST-COUNT-YEAR  PIC 99    VALUE O.
     05  WS-QTY-IN-STOCK         PIC 9(6)  VALUE O.
     05  WS-QTY-ISSUED           PIC 9(6)  VALUE O.
     05  WS-QTY-RECEIVED         PIC 9(6)  VALUE O.
     05  WS-NO-OF-SALES          PIC 9(4)  VALUE O.
     05  FILLER                  PIC X(40) VALUE SPACES.
 01  WS-DATE.
     05  WS-DATE-MM              PIC 9(2).
     05  WS-DATE-DD              PIC 9(2).
     05  WS-DATE-YY              PIC 9(2).
 01  WS-DATE-HOLD.
     05  WS-DATE-YY-X            PIC 9(2).
     05  WS-DATE-MM-X            PIC 9(2).
     05  WS-DATE-DD-X            PIC 9(2).

 REPORT SECTION.
 RED STOCK-REPORT
     CONTROLS ARE FINAL, WS-LOCATION-CODE
     PAGE LIMIT IS 50
     FIRST DETAIL 10
     LAST DETAIL 40
     FOOTING 47.

01  TYPE IS REPORT HEADING NEXT GROUP NEXT PAGE.
MOCKUP LINES 1 THRU 6
SOURCE WS-DATE

01  TYPE IS PAGE HEADING.
MOCKUP LINES 7 THRU 9
SOURCE WS-DATE

01  TYPE IS CONTROL HEADING WS-LOCATION-CODE.
MOCKUP LINES 10 THRU 13

01  DETAIL-LINE TYPE IS DETAIL.
MOCKUP LINE 14
SOURCE WS-LOCATION-CODE       GROUP INDICATE
SOURCE WS-LAST-COUNT-MONTH    PIC 99
SOURCE WS-LAST-COUNT-DAY      PIC 99
SOURCE WS-LAST-COUNT-YEAR     PIC 99
SOURCE WS-QTY-IN-STOCK
SOURCE WS-QTY-ISSUED
SOURCE WS-QTY-RECEIVED
REFERENCE WS-NO-OF-SALES      PIC zzz9

01  TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
MOCKUP LINES 15 THRU 21
SUM WS-QTY-IN-STOCK
SUM WS-QTY-ISSUED
SUM WS-QTY-RECEIVED
SUM WS-NO-OF-SALES

01  TYPE IS CONTROL FOOTING FINAL.
MOCKUP LINES 22 THRU 30
SUM WS-QTY-IN-STOCK
SUM WS-QTY-ISSUED
SUM WS-QTY-RECEIVED
SUM WS-NO-OF-SALES

01  TYPE IS PAGE FOOTING.
MOCKUP LINE 31
SOURCE PAGE-COUNTER

01  TYPE IS REPORT FOOTING.
MOCKUP LINES 32 THRU 33

$TP-ENTRY
    OPEN INPUT INPUT-FILE
    ...OUTPUT REPORT-OUTPUT-FILE
    ACCEPT WS-DATE-HOLD FROM DATE
    MOVE WS-DATE-YY-X TO WS-DATE-YY
    MOVE WS-DATE-MM-X TO WS-DATE-MM
    MOVE WS-DATE-DD-X TO WS-DATE-DD
    INITIATE STOCK-REPORT
    REPEAT
        READ INPUT-FILE INTO WS-PART-STOCK-REC
    UNTIL AT END ON INPUT-FILE
        GENERATE DETAIL-LINE
    TERMINATE STOCK-REPORT
    CLOSE INPUT-FILE
    ... REPORT-OUTPUT-FILE

Printed Report

                 WONDERFUL WIDGETS INCORPORATED
                          STOCK REPORT
                           01/25/14
                          MID-ATLANTIC
                          STOCK REPORT
                           01/25/14

LOCATION       LAST COUNT     QUANTITY IN    QUANTITY    QUANTITY
                  DATE          STOCK         ISSUED     RECEIVED

ALEXANDRIA      05/01/90             111          222         333
                06/01/90             111          222         333
                07/01/90             111          222         333
                08/01/90             111          222         333
                09/01/90             111          222         333
                10/01/90             111          222         333
                11/01/90             111          222         333
                               _________    _________   _________
TOTAL BY LOCATION:                   777        1,554       2,331

TOTAL NUMBER OF SALES BY LOCATION:     3,108

               LAST COUNT     QUANTITY IN    QUANTITY    QUANTITY
LOCATION          DATE          STOCK         ISSUED     RECEIVED

BALTIMORE       06/01/90              11           22          33
                08/01/90              11           22          33
                09/01/90              11           22          33
                10/01/90              11           22          33
                11/01/90              11           22          33
                               _________    _________   _________
TOTAL BY LOCATION:                    55          110         165

TOTAL NUMBER OF SALES BY LOCATION:       220

                                                            PAGE    1

                          MID-ATLANTIC
                          STOCK REPORT
                           01/25/14

               LAST COUNT     QUANTITY IN    QUANTITY    QUANTITY
LOCATION          DATE          STOCK         ISSUED     RECEIVED

ROCKVILLE       05/01/90              11           22          33
                06/01/90              11           22          33
                07/01/90              11           22          33
                08/01/90              11           22          33
                09/01/90              11           22          33
                10/01/90              11           22          33
                11/01/90              11           22          33
                               _________    _________   _________
TOTAL BY LOCATION:                    77          154         231

TOTAL NUMBER OF SALES BY LOCATION:       308

               LAST COUNT     QUANTITY IN    QUANTITY    QUANTITY
LOCATION          DATE          STOCK         ISSUED     RECEIVED

WASHINGTON      06/01/90         111,111      222,222     333,333
                07/01/90         111,111      222,222     333,333
                08/01/90         111,111      222,222     333,333
                09/01/90         111,111      222,222     333,333
                10/01/90         111,111      222,222     333,333
                11/01/90         111,111      222,222     333,333
                               _________    _________   _________
TOTAL BY LOCATION:               666,666    1,333,332   1,999,998

TOTAL NUMBER OF SALES BY LOCATION:    26,664

                                                            PAGE    2

                          MID-ATLANTIC
                          STOCK REPORT
                           01/25/14

TOTAL WONDERFUL WIDGETS IN STOCK:        667,575
TOTAL WONDERFUL WIDGETS ISSUED:        1,335,150
TOTAL WONDERFUL WIDGETS RECEIVED:      2,002,725
TOTAL WONDERFUL WIDGETS SOLD:             30,300

                                                            PAGE    3
                             *****  END OF REPORT  *****
Parent topic: Sample Programs


Iterative Expressions - Sample Program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This next program illustrates Report Writer structures and the use of iterative expressions.

Report Mock-up

=============================================================================================================================
                                                         EGAS,INC.

                                          XXXX YEAR-END PRODUCT SALES SUMMARY

                           ******************************************************************

                                                                                PAGEZZZZ9
                                                  REGION:  XXXXXXXXX
                                             XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

              ----- 1-ST QUARTER -----  ----- 2-ND QUARTER -----  ----- 3-RD QUARTER ----- ----- 4-TH QUARTER -----
PRODUCT        JAN   FEB   MAR  TOTAL   APR   MAY   JUN  TOTAL    JUL   AUG   SEP  TOTAL    OCT   NOV   DEC  TOTAL   TOTAL
------------- ----- ----- ----- ------ ----- ----- ----- ------  ----- ----- ----- ------  ----- ----- ----- ------  --------
SALES OFFICE:  XXXXXXXXXXXXXXX
MANAGER:  XXXXXXXXXXXXXXXXXXXX

XXXXXXXXXXXX Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  $$$$,$$$

TOTAL FOR:    ----- ----- ----- ------ ----- ----- ----- ------  ----- ----- ----- ------  ----- ----- ----- ------  --------
XXXXXXXXXXXX  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9 Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  $$$$,$$$

TOTAL FOR:    ----- ----- ----- ------ ----- ----- ----- ------  ----- ----- ----- ------  ----- ----- ----- ------  --------
XXXXXXXXX     Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9 Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  $$$$,$$$
              ----- ----- ----- ------ ----- ----- ----- ------  ----- ----- ----- ------  ----- ----- ----- ------  --------
TOTAL         Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9 Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  Z,ZZ9 Z,ZZ9 Z,ZZ9 ZZ,ZZ9  $$$$,$$$

                            ******************************************************************

                                               EGAS! ANOTHER BANNER YEAR!
=================================================================================================================================

Program Painter Source

REM  READS DATA.EXTRACT AND GENERATES A SUMMARY
     REPORT BY REGION, OFFICE AND PRODUCT.
/*   *****************************************************
IO   EXTRACT-FILE                ASSIGN TO UT-S-EXTRACT
IO   SALES-SUMMARY-FILE          ASSIGN TO UT-S-SUMMREPT
IO   DEFINITION-FILE             ASSIGN TO UT-S-DEFS
/*   *****************************************************

/*   IO EXTRACT-FILE                ASSIGN "EXTRACT"
/*   IO SALES-SUMMARY-FILE          ASSIGN "SUMMREPT"
/*   IO DEFINITION-FILE             ASSIGN "DEFS"

FD   EXTRACT-FILE
     LABEL RECORDS ARE STANDARD
     RECORDING MODE IS F
     RECORD CONTAINS 90 CHARACTERS
     BLOCK CONTAINS 0 RECORDS.

01   EXTRACT-FILE-RECORD
     02  EXT-REGION              PIC X(9).
     02  EXT-OFFICE              PIC X(15).
     02  EXT-PRODUCT             PIC X(18).
     02  EXT-SALES-DOLLARS       PIC 9(4) OCCURS 12.

FD   SALES-SUMMARY-FILE
     LABEL RECORDS ARE STANDARD
     RECORDING MODE IS F
     RECORD CONTAINS 133 CHARACTERS
     BLOCK CONTAINS 0 RECORDS
     REPORT IS YEAR-END-SALES-SUMMARY.

FD   DEFINITION-FILE
     LABEL RECORDS ARE STANDARD
     RECORDING MODE IS F
     RECORD CONTAINS 38 CHARACTERS
     BLOCK CONTAINS 0 RECORDS.

01   DEFINITION-RECORD.
     02  DEFINITION-TYPE         PIC X(3).
     02  DEFINITION-REGION       PIC X(29).
     02  FILLER                  PIC X(6).

01   DEFINITION-RECORD-2.
     02  FILLER                  PIC X(3).
     02  DEFINITION-OFFICE       PIC X(35).

WS01 JJ                          PIC S9(4) COMP SYNC VALUE ZERO.
WS01 II                          PIC S9(4) COMP SYNC VALUE ZERO.
WS01 FIRST-FLG                   PIC X(1) VALUE 'T'.

WS01 REGION-DEFINITIONS.
     02  REGION-TABLE OCCURS 4 TIMES INDEXED BY REGION-IDX.
         03  REGION-NAME         PIC X(9).
         03  REGION-MANAGER      PIC X(20).

WS01 REGION                      PIC X(9).
WS01 REGION-MGR.
     02  REG-MGR OCCURS 20 TIMES
                                 INDEXED BY REG-MGR-IDX
                                 PIC X(1).

WS01 REG-MGR-MAX                 PIC S9(4) COMP SYNC VALUE +20.
WS01 REGION-MGR-FIELD.
     02  REGION-MGR-X OCCURS 30 TIMES INDEXED BY MGR-IDX
                                 PIC X(1).
WS01 REGION-MGR-FLD REDEFINES REGION-MGR-FIELD
                                 PIC X(30).
WS01 REGION-MGR-MAX              PIC S9(4) COMP SYNC VALUE +30.
WS01 MANAGER-WORD                PIC X(10) VALUE 'MANAGER:  '.
WS01 MANAGER-BY-CHAR REDEFINES MANAGER-WORD.
     02  MANAGER-LETTER OCCURS 10 TIMES
                                 INDEXED BY LETTER-IDX
                                 PIC X(1).
WS01 MANAGER-WORD-SIZE           PIC S9(4) COMP SYNC VALUE +10.

WS01 OFFICE-DEFINITIONS.
     02  OFFICE-TABLE OCCURS 14 TIMES INDEXED BY OFFICE-IDX.
         03  OFFICE-NAME         PIC X(15).
         03  OFFICE-MANAGER      PIC X(20).
WS01 OFFICE                      PIC X(15).
WS01 OFFICE-MGR                  PIC X(20).

WS01 QTR-1-SALES-DOLLARS         PIC 9(5) VALUE ZERO.
WS01 QTR-2-SALES-DOLLARS         PIC 9(5) VALUE ZERO.
WS01 QTR-3-SALES-DOLLARS         PIC 9(5) VALUE ZERO.
WS01 QTR-4-SALES-DOLLARS         PIC 9(5) VALUE ZERO.

WS01 YR-SALES-DOLLARS            PIC 9(6) VALUE ZERO.
WS01 CURRENT-DATE-X.
     02  CURRENT-YEAR            PIC 9(2).
     02  FILLER                  PIC X(4).
WS01 REPORT-YEAR.
     02  FILLER                  PIC 9(2) VALUE 20.
     02  REPORT-YEAR-X           PIC 9(2).

RED  YEAR-END-SALES-SUMMARY
     CONTROLS ARE FINAL REGION REGION-MGR-FLD OFFICE
     PAGE LIMIT IS 58 LINES
     FIRST DETAIL 9
     HEADING 1
     FOOTING 58.

MOCK SUMMARY

01   RH-YEAR-END-SALES-SUMMARY   TYPE IS REPORT HEADING
                                 NEXT GROUP IS NEXT PAGE.
     MOCKUP LINES 1 THRU 4
     LINE 25
     SOURCE REPORT-YEAR          PIC X(4).

01   PH-YEAR-END-SALES-SUMMARY   TYPE IS PAGE HEADING.
     MOCKUP LINES 10 THRU 17
     SOURCE PAGE-COUNTER         PIC ZZZZ9.
     SOURCE REGION               PIC X(9).
     SOURCE REGION-MGR-FLD       PIC X(30).

01   CH-REGION                   TYPE IS CONTROL HEADING
                                 REGION
                                 NEXT GROUP IS NEXT PAGE.

01   CH-OFFICE                  TYPE IS CONTROL HEADING
                                OFFICE.
     MOCKUP LINES 18 THRU 20
     SOURCE OFFICE              PIC X(15).
     SOURCE OFFICE-MGR          PIC X(20).

01   DE-YEAR-END-SALES-SUMMARY  TYPE IS DETAIL.
     MOCKUP LINE 21
     SOURCE EXT-PRODUCT                PIC X(8).
     SOURCE EXT-SALES-DOLLARS (#1/3)   PIC Z,ZZ9
     SOURCE QTR-1-SALES-DOLLARS        PIC ZZ,ZZ9
     SOURCE EXT-SALES-DOLLARS (#4/6)   PIC Z,ZZ9
     SOURCE QTR-2-SALES-DOLLARS        PIC ZZ,ZZ9
     SOURCE EXT-SALES-DOLLARS (#7/9)   PIC Z,ZZ9
     SOURCE QTR-3-SALES-DOLLARS        PIC ZZ,ZZ9
     SOURCE EXT-SALES-DOLLARS (#10/12) PIC Z,ZZ9
     SOURCE QTR-4-SALES-DOLLARS        PIC ZZ,ZZ9
     SOURCE YR-SALES-DOLLARS           PIC $$$$,$$$

01   PF-YEAR-END-SALES-SUMMARY  TYPE IS PAGE FOOTING
                                NEXT GROUP IS NEXT PAGE.
     MOCKUP LINE 32

01   RF-YEAR-END-SALES-SUMMARY  TYPE IS REPORT FOOTING.
     MOCKUP LINE 38
     LINE IS 25

01   CF-FINAL                   TYPE IS CONTROL FOOTING
                                FINAL.
     MOCKUP LINES 29 THRU 31
     SUM EXT-SALES-DOLLARS (#1/3)   PIC Z,ZZ9
     SUM QTR-1-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#4/6)   PIC Z,ZZ9
     SUM QTR-2-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#7/9)   PIC Z,ZZ9
     SUM QTR-3-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#10/12) PIC Z,ZZ9
     SUM QTR-4-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM YR-SALES-DOLLARS           PIC $$$$,$$$

01   CF-REGION                  TYPE IS CONTROL FOOTING
                                REGION.
     MOCKUP LINES 26 THRU 28
     SOURCE REGION                  PIC X(9)
     SUM EXT-SALES-DOLLARS (#1/3)   PIC Z,ZZ9
     SUM QTR-1-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#4/6)   PIC Z,ZZ9
     SUM QTR-2-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#7/9)   PIC Z,ZZ9
     SUM QTR-3-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#10/12) PIC Z,ZZ9
     SUM QTR-4-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM YR-SALES-DOLLARS           PIC $$$$,$$$

01   CF-OFFICE                   TYPE IS CONTROL FOOTING
                                 OFFICE.
     MOCKUP LINES 23 THRU 25
     SOURCE OFFICE                  PIC X(15)
     SUM EXT-SALES-DOLLARS (#1/3)   PIC Z,ZZ9
     SUM QTR-1-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#4/6)   PIC Z,ZZ9
     SUM QTR-2-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#7/9)   PIC Z,ZZ9
     SUM QTR-3-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM EXT-SALES-DOLLARS (#10/12) PIC Z,ZZ9
     SUM QTR-4-SALES-DOLLARS        PIC ZZ,ZZ9
     SUM YR-SALES-DOLLARS           PIC $$$$,$$$

DPAR SUPPRESS CH-REGION SECTION
     USE BEFORE REPORTING CH-REGION
DPAR SUPPRESS CH-REGION-PARA
     IF FIRST-FLG = TRUE
         SUPPRESS PRINTING

PROC
     ACCEPT CURRENT-DATE-X FROM DATE
     MOVE CURRENT-YEAR TO REPORT-YEAR-X
     PERFORM LOAD-DEFINITIONS
     OPEN INPUT EXTRACT-FILE
     OPEN OUTPUT SALES-SUMMARY-FILE
     INITIATE YEAR-END-SALES-SUMMARY
     MOVE ZERO TO PAGE-COUNTER
     REPEAT
         READ EXTRACT-FILE
     UNTIL AT END ON EXTRACT-FILE
         IF EXT-OFFICE NOT = OFFICE
             PERFORM LOCATE-MANAGERS
         ADD EXT-SALES-DOLLARS (1) TO QTR-1-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (2) TO QTR-1-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (3) TO QTR-1-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (4) TO QTR-2-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (5) TO QTR-2-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (6) TO QTR-2-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (7) TO QTR-3-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (8) TO QTR-3-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (9) TO QTR-3-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (10) TO QTR-4-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (11) TO QTR-4-SALES-DOLLARS
         ADD EXT-SALES-DOLLARS (12) TO QTR-4-SALES-DOLLARS
         REPEAT VARYING II FROM 1 BY 1
         UNTIL II > 12
             ADD EXT-SALES-DOLLARS (II) TO YR-SALES-DOLLARS
         GENERATE DE-YEAR-END-SALES-SUMMARY
         MOVE FALSE TO FIRST-FLG
         MOVE ZEROES TO QTR-1-SALES-DOLLARS
         ... QTR-2-SALES-DOLLARS QTR-3-SALES-DOLLARS
         ... QTR-4-SALES-DOLLARS YR-SALES-DOLLARS
     TERMINATE YEAR-END-SALES-SUMMARY
     CLOSE EXTRACT-FILE SALES-SUMMARY-FILE

PARA LOAD-DEFINITIONS.
     SET REGION-IDX TO 1
     SET REGION-IDX DOWN BY 1
     SET OFFICE-IDX TO 1
     SET OFFICE-IDX DOWN BY 1
     OPEN INPUT DEFINITION-FILE
     REPEAT
         READ DEFINITION-FILE
     UNTIL AT END ON DEFINITION-FILE
         IF DEFINITION-TYPE = 'REG'
             SET REGION-IDX UP BY 1
             MOVE DEFINITION-REGION TO REGION-TABLE (REGION-IDX)
         ELSE-IF DEFINITION-TYPE = 'OFF'
             SET OFFICE-IDX UP BY 1
             MOVE DEFINITION-OFFICE TO OFFICE-TABLE (OFFICE-IDX)
     CLOSE DEFINITION-FILE

PARA LOCATE-MANAGERS.
     SET REGION-IDX TO 1
     SEARCH REGION-TABLE
     WHEN EXT-REGION = REGION-NAME (REGION-IDX)
         MOVE REGION-MANAGER (REGION-IDX) TO REGION-MGR
     MOVE SPACES TO REGION-MGR-FLD
     SET REG-MGR-IDX TO REG-MGR-MAX
     WHILE REG-MGR (REG-MGR-IDX) = SPACE
     ... AND REG-MGR-IDX > ZERO
         SET REG-MGR-IDX DOWN BY 1
     SET JJ TO REG-MGR-IDX
     COMPUTE II =
     ... (REGION-MGR-MAX - MANAGER-WORD-SIZE - JJ) / 2
     ADD 1 TO II
     IF II <= ZERO
         MOVE 1 TO II
     SET REG-MGR-IDX TO 1
     SET LETTER-IDX TO 1
     REPEAT VARYING MGR-IDX FROM II BY 1
     UNTIL MGR-IDX > REGION-MGR-MAX
         IF LETTER-IDX <= MANAGER-WORD-SIZE
             MOVE MANAGER-LETTER (LETTER-IDX)
             ... TO REGION-MGR-X (MGR-IDX)
             SET LETTER-IDX UP BY 1
         ELSE-IF REG-MGR-IDX <= REG-MGR-MAX
             MOVE REG-MGR (REG-MGR-IDX)
             ... TO REGION-MGR-X (MGR-IDX)
             SET REG-MGR-IDX UP BY 1
         ELSE
             SET MGR-IDX TO REGION-MGR-MAX
             DISPLAY 'MANAGER INDEXES OUT OF RANGE: '
             ... EXTRACT-FILE-RECORD
     SET OFFICE-IDX TO 1
     SEARCH OFFICE-TABLE
     WHEN EXT-OFFICE = OFFICE-NAME (OFFICE-IDX)
         MOVE OFFICE-MANAGER (OFFICE-IDX) TO OFFICE-MGR
     MOVE EXT-REGION TO REGION
     MOVE EXT-OFFICE TO OFFICE

Generated Source

%   &AP-GEN-VER = 1719
%   &AP-PGM-ID = "SUMMARY"
%   &AP-GEN-DC-TARGET = "MVS"
%   &AP-GEN-DB-TARGET = "VSAM"
%   &AP-PROC-DIV-KYWD-SEEN = 1
%   &AP-FILE-CONTROL-SEEN = 1
%   &AP-SUBSCHEMA = ""
%   &AP-APPLICATION-ID = "GLGAP"
%   &AP-GEN-DATE = "861204"
%   &AP-GEN-TIME = "17142491"
IDENTIFICATION DIVISION.
PROGRAM-ID.                     SUMMARY.
AUTHOR.                         AP-SYSTEM GENERATED.
DATE-WRITTEN.                   861204.
DATE-COMPILED.                  &COMPILETIME.
*
*REMARKS.
*    READS DATA.EXTRACT AND GENERATES A SUMMARY
*    REPORT BY REGION, OFFICE AND PRODUCT.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.                &SYSTEM.
OBJECT-COMPUTER.                &SYSTEM.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
IO EXTRACT-FILE                ASSIGN "EXTRACT"
IO SALES-SUMMARY-FILE          ASSIGN "SUMMREPT"
IO DEFINITION-FILE             ASSIGN "DEFS"
DATA DIVISION.
FILE SECTION.
FD  EXTRACT-FILE
    LABEL RECORDS ARE STANDARD
    RECORDING MODE IS F
    RECORD CONTAINS 90 CHARACTERS
    BLOCK CONTAINS 0 RECORDS.
01  EXTRACT-FILE-RECORD
    02  EXT-REGION              PIC X(9).
    02  EXT-OFFICE              PIC X(15).
    02  EXT-PRODUCT             PIC X(18).
    02  EXT-SALES-DOLLARS       PIC 9(4) OCCURS 12.
FD  SALES-SUMMARY-FILE
    LABEL RECORDS ARE STANDARD
    RECORDING MODE IS F
    RECORD CONTAINS 133 CHARACTERS
    BLOCK CONTAINS 0 RECORDS
    REPORT IS YEAR-END-SALES-SUMMARY.
FD  DEFINITION-FILE
    LABEL RECORDS ARE STANDARD
    RECORDING MODE IS F
    RECORD CONTAINS 38 CHARACTERS
    BLOCK CONTAINS 0 RECORDS.
01  DEFINITION-RECORD.
    02  DEFINITION-TYPE         PIC X(3).
    02  DEFINITION-REGION       PIC X(29).
    02  FILLER                  PIC X(6).
01  DEFINITION-RECORD-2.
    02  FILLER                  PIC X(3).
    02  DEFINITION-OFFICE       PIC X(35).

WORKING-STORAGE SECTION.
$TP-WS-MARKER
01  JJ                          PIC S9(4) COMP SYNC VALUE ZERO.
01  II                          PIC S9(4) COMP SYNC VALUE ZERO.
01  FIRST-FLG                   PIC X(1) VALUE 'T'.
01  REGION-DEFINITIONS.
    02  REGION-TABLE OCCURS 4 TIMES INDEXED BY REGION-IDX.
        03  REGION-NAME         PIC X(9).
        03  REGION-MANAGER      PIC X(20).
01  REGION                      PIC X(9).
01  REGION-MGR.
    02  REG-MGR OCCURS 20 TIMES
                                INDEXED BY REG-MGR-IDX
                                PIC X(1).
01  REG-MGR-MAX                 PIC S9(4) COMP SYNC VALUE +20.
01  REGION-MGR-FIELD.
    02  REGION-MGR-X OCCURS 30 TIMES INDEXED BY MGR-IDX
                                PIC X(1).
01  REGION-MGR-FLD REDEFINES REGION-MGR-FIELD
                                PIC X(30).
01  REGION-MGR-MAX              PIC S9(4) COMP SYNC VALUE +30.
01  MANAGER-WORD                PIC X(10) VALUE 'MANAGER:  '.
01  MANAGER-BY-CHAR REDEFINES MANAGER-WORD.
    02  MANAGER-LETTER OCCURS 10 TIMES
                                INDEXED BY LETTER-IDX
                                PIC X(1).
1  MANAGER-WORD-SIZE            PIC S9(4) COMP SYNC VALUE +10.
01  OFFICE-DEFINITIONS.
    02  OFFICE-TABLE OCCURS 14 TIMES INDEXED BY OFFICE-IDX.
        03  OFFICE-NAME         PIC X(15).
        03  OFFICE-MANAGER      PIC X(20).
01  OFFICE                      PIC X(15).
01  OFFICE-MGR                  PIC X(20).

01  QTR-1-SALES-DOLLARS         PIC 9(5) VALUE ZERO.
01  QTR-2-SALES-DOLLARS         PIC 9(5) VALUE ZERO.
01  QTR-3-SALES-DOLLARS         PIC 9(5) VALUE ZERO.
01  QTR-4-SALES-DOLLARS         PIC 9(5) VALUE ZERO.
01  YR-SALES-DOLLARS            PIC 9(6) VALUE ZERO.
01  CURRENT-DATE-X.
    02  CURRENT-YEAR            PIC 9(2).
    02  FILLER                  PIC X(4).
01  REPORT-YEAR.
    02  FILLER                  PIC 9(2) VALUE 20.
    02  REPORT-YEAR-X           PIC 9(2).
REPORT SECTION.
RED YEAR-END-SALES-SUMMARY
    CONTROLS ARE FINAL REGION REGION-MGR-FLD OFFICE
    PAGE LIMIT IS 58 LINES
    FIRST DETAIL 9
    HEADING 1
    FOOTING 58.
01  RH-YEAR-END-SALES-SUMMARY   TYPE IS REPORT HEADING
                                NEXT GROUP IS NEXT PAGE.
MOCKUP LINES 1 THRU 4
LINE 25
SOURCE REPORT-YEAR          PIC X(4).
01  PH-YEAR-END-SALES-SUMMARY   TYPE IS PAGE HEADING.
MOCKUP LINES 10 THRU 17
SOURCE PAGE-COUNTER         PIC ZZZZ9.
SOURCE REGION               PIC X(9).
SOURCE REGION-MGR-FLD       PIC X(30).
01  CH-REGION               TYPE IS CONTROL HEADING
                            REGION
                            NEXT GROUP IS NEXT PAGE.
01  CH-OFFICE               TYPE IS CONTROL HEADING
                            OFFICE.
MOCKUP LINES 18 THRU 20
SOURCE OFFICE               PIC X(15).
SOURCE OFFICE-MGR           PIC X(20).
01  DE-YEAR-END-SALES-SUMMARY  TYPE IS DETAIL.
MOCKUP LINE 21
SOURCE EXT-PRODUCT                 PIC X(8).
SOURCE EXT-SALES-DOLLARS (#1/3)    PIC Z,ZZ9
SOURCE QTR-1-SALES-DOLLARS         PIC ZZ,ZZ9
SOURCE EXT-SALES-DOLLARS (#4/6)    PIC Z,ZZ9
SOURCE QTR-2-SALES-DOLLARS         PIC ZZ,ZZ9
SOURCE EXT-SALES-DOLLARS (#7/9)    PIC Z,ZZ9
SOURCE QTR-3-SALES-DOLLARS         PIC ZZ,ZZ9
SOURCE EXT-SALES-DOLLARS (#10/12)  PIC Z,ZZ9
SOURCE QTR-4-SALES-DOLLARS         PIC ZZ,ZZ9
SOURCE YR-SALES-DOLLARS            PIC $$$$,$$$
01  PF-YEAR-END-SALES-SUMMARY  TYPE IS PAGE FOOTING
                               NEXT GROUP IS NEXT PAGE.
MOCKUP LINE 32
01  RF-YEAR-END-SALES-SUMMARY  TYPE IS REPORT FOOTING.
MOCKUP LINE 38
LINE IS 25
01  CF-FINAL                   TYPE IS CONTROL FOOTING
                               FINAL.
MOCKUP LINES 29 THRU 31
SUM EXT-SALES-DOLLARS (#1/3)       PIC Z,ZZ9
SUM QTR-1-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#4/6)       PIC Z,ZZ9
SUM QTR-2-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#7/9)       PIC Z,ZZ9
SUM QTR-3-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#10/12)     PIC Z,ZZ9
SUM QTR-4-SALES-DOLLARS            PIC ZZ,ZZ9
SUM YR-SALES-DOLLARS               PIC $$$$,$$$
01  CF-REGION                  TYPE IS CONTROL FOOTING
                               REGION.
MOCKUP LINES 26 THRU 28
SOURCE REGION                      PIC X(9)
SUM EXT-SALES-DOLLARS (#1/3)       PIC Z,ZZ9
SUM QTR-1-SALES-DOLLARS            PIC ZZ,ZZ9

SUM EXT-SALES-DOLLARS (#4/6)       PIC Z,ZZ9
SUM QTR-2-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#7/9)       PIC Z,ZZ9
SUM QTR-3-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#10/12)     PIC Z,ZZ9
SUM QTR-4-SALES-DOLLARS            PIC ZZ,ZZ9
SUM YR-SALES-DOLLARS               PIC $$$$,$$$
01  CF-OFFICE                  TYPE IS CONTROL FOOTING
                               OFFICE.
MOCKUP LINES 23 THRU 25
SOURCE OFFICE                      PIC X(15)
SUM EXT-SALES-DOLLARS (#1/3)       PIC Z,ZZ9
SUM QTR-1-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#4/6)       PIC Z,ZZ9
SUM QTR-2-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#7/9)       PIC Z,ZZ9
SUM QTR-3-SALES-DOLLARS            PIC ZZ,ZZ9
SUM EXT-SALES-DOLLARS (#10/12)     PIC Z,ZZ9
SUM QTR-4-SALES-DOLLARS            PIC ZZ,ZZ9
SUM YR-SALES-DOLLARS               PIC $$$$,$$$

PROCEDURE DIVISION.
DECLARATIVES.
SUPPRESS CH-REGION SECTION.
    USE BEFORE REPORTING CH-REGION
SUPPRESS CH-REGION-PARA.
    IF FIRST-FLG = TRUE
        SUPPRESS PRINTING
END DECLARATIVES.
    ACCEPT CURRENT-DATE-X FROM DATE
    MOVE CURRENT-YEAR TO REPORT-YEAR-X
    PERFORM LOAD-DEFINITIONS
    OPEN INPUT EXTRACT-FILE
    OPEN OUTPUT SALES-SUMMARY-FILE
    INITIATE YEAR-END-SALES-SUMMARY
    MOVE ZERO TO PAGE-COUNTER
    REPEAT
        READ EXTRACT-FILE
    UNTIL AT END ON EXTRACT-FILE
        IF EXT-OFFICE NOT = OFFICE
            PERFORM LOCATE-MANAGERS
        ADD EXT-SALES-DOLLARS (1) TO QTR-1-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (2) TO QTR-1-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (3) TO QTR-1-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (4) TO QTR-2-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (5) TO QTR-2-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (6) TO QTR-2-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (7) TO QTR-3-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (8) TO QTR-3-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (9) TO QTR-3-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (10) TO QTR-4-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (11) TO QTR-4-SALES-DOLLARS
        ADD EXT-SALES-DOLLARS (12) TO QTR-4-SALES-DOLLARS
        REPEAT VARYING II FROM 1 BY 1
        UNTIL II > 12
            ADD EXT-SALES-DOLLARS (II) TO YR-SALES-DOLLARS
        GENERATE DE-YEAR-END-SALES-SUMMARY
        MOVE FALSE TO FIRST-FLG
        MOVE ZEROES TO QTR-1-SALES-DOLLARS
        ... QTR-2-SALES-DOLLARS QTR-3-SALES-DOLLARS
        ... QTR-4-SALES-DOLLARS YR-SALES-DOLLARS
    TERMINATE YEAR-END-SALES-SUMMARY
    CLOSE EXTRACT-FILE SALES-SUMMARY-FILE

LOAD-DEFINITIONS.
    SET REGION-IDX TO 1
    SET REGION-IDX DOWN BY 1
    SET OFFICE-IDX TO 1
    SET OFFICE-IDX DOWN BY 1
    OPEN INPUT DEFINITION-FILE
    REPEAT
        READ DEFINITION-FILE
    UNTIL AT END ON DEFINITION-FILE
       IF DEFINITION-TYPE = 'REG'
            SET REGION-IDX UP BY 1
            MOVE DEFINITION-REGION TO REGION-TABLE (REGION-IDX)

        ELSE-IF DEFINITION-TYPE = 'OFF'
            SET OFFICE-IDX UP BY 1
            MOVE DEFINITION-OFFICE TO OFFICE-TABLE (OFFICE-IDX)
    CLOSE DEFINITION-FILE

LOCATE-MANAGERS.
    SET REGION-IDX TO 1
    SEARCH REGION-TABLE
    WHEN EXT-REGION = REGION-NAME (REGION-IDX)
        MOVE REGION-MANAGER (REGION-IDX) TO REGION-MGR
    MOVE SPACES TO REGION-MGR-FLD
    SET REG-MGR-IDX TO REG-MGR-MAX
    WHILE REG-MGR (REG-MGR-IDX) = SPACE
    ... AND REG-MGR-IDX > ZERO
        SET REG-MGR-IDX DOWN BY 1
    SET JJ TO REG-MGR-IDX
    COMPUTE II =
    ... (REGION-MGR-MAX - MANAGER-WORD-SIZE - JJ) / 2
    ADD 1 TO II
    IF II <= ZERO
        MOVE 1 TO II
    SET REG-MGR-IDX TO 1
    SET LETTER-IDX TO 1
    REPEAT VARYING MGR-IDX FROM II BY 1
    UNTIL MGR-IDX > REGION-MGR-MAX
        IF LETTER-IDX <= MANAGER-WORD-SIZE
            MOVE MANAGER-LETTER (LETTER-IDX)
            ... TO REGION-MGR-X (MGR-IDX)
            SET LETTER-IDX UP BY 1
        ELSE-IF REG-MGR-IDX <= REG-MGR-MAX
            MOVE REG-MGR (REG-MGR-IDX)
            ... TO REGION-MGR-X (MGR-IDX)
            SET REG-MGR-IDX UP BY 1
        ELSE
            SET MGR-IDX TO REGION-MGR-MAX
            DISPLAY 'MANAGER INDEXES OUT OF RANGE: '
            ... EXTRACT-FILE-RECORD
    SET OFFICE-IDX TO 1
    SEARCH OFFICE-TABLE
    WHEN EXT-OFFICE = OFFICE-NAME (OFFICE-IDX)
        MOVE OFFICE-MANAGER (OFFICE-IDX) TO OFFICE-MGR
    MOVE EXT-REGION TO REGION
    MOVE EXT-OFFICE TO OFFICE
Parent topic: Sample Programs


Application Reports

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In addition to any custom reports you mock up using the Report Painter, AppMaster Builder provides a set of reports that help you understand your application and its various components. You can use these reports as you develop an application to determine the status of your work and the tasks left to complete. Some reports help you to troubleshoot problems in an application that you are developing, or to determine the effect of a proposed change. Others help you to verify the results of your work. Once you have fully implemented an application, use the AppMaster Builder reports to document it so that developers who later maintain or enhance the application can easily understand it.

Note: Ensure that the current AMB project contains the application objects you want to report on.

You can produce reports on an entire application, on selected components, or on selected members of components, as follows:

Application Definition Report
Lists and describes all components of an application.
Component List Report
Catalogs and totals the components for each type.
DDIFILE Report
Describes the contents of the IMS or VSAM file that contains information about your database, formatted to AppMaster Builder specifications.
Field-Screen Cross Reference Report
lists application screens, along with their entry or text fields.
Macro Cross Reference Report
Lists macros and the programs that use them.
Customized Mock-up Report
Llists and displays report mock-ups as painted in the Report Painter. This report displays the report exactly as painted in the Report Painter, with or without line numbers.
Program DB-DC Report
Lists the screens and the subschemas or PSBs used by a program.
Program Definition Report
Provides a printout of programs created in AppMaster Builder. This report produces a listing of the program code you create in the Program Painter.
  • Application Definition Report
  • Screen HardcopyField Attribute Report
  • Component List Report
  • Field/Screen Cross Reference Report
  • Macro/Program Cross Reference Report
  • Program DB/DC Report
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
The AppMaster Builder Tool Set


Application Definition Report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This report displays each component of an application in a separate report section. This report is actually a collection of the following reports for the application.

  • Data Structure Definition
  • Program Definition
  • Report Definition
  • Screen Hardcopy/Field Attribute
  • Program DB/DC
Parent topic: Application Reports
Related tasks
To run an application report
To run the DDIFILE report


Screen HardcopyField Attribute Report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This report produces a mock-up for your screen, as it was painted. Optionally, additional sections describe the attributes and field edits.

  • The Field Attributes section lists the attribute values for each screen field in the order it appears on the screen. The report indicates default values with periods (...). The Occ(urrence) column shows the number of field occurrences within a repeated record block.
  • The Field Edits section lists the field edits applied to the screen fields.
Parent topic: Application Reports
Related tasks
To run an application report


Component List Report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Component List Report catalogs all of the entities created for an application within a specific Project and Group.

The report lists entities by type in six columns, one each for applications, programs, screens, report mock-ups, data structures, and scenarios. Within each column, the report lists entities in alphabetical order. The bottom of the report totals the number of entities listed for each type. You can produce a report listing application entities of one or more types.

This report does not provide information about subschemas or about the contents of each listed entity.

Parent topic: Application Reports
Related tasks
To run the Component List report


Field/Screen Cross Reference Report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Field/Screen Cross Reference Report lists all the screens containing I/O fields, along with the attribute values for the field in each screen. The fields appear alphabetically on the report. For each field, the report lists the field attributes assigned in the Screen Painter, and the number of field occurrences within a repeated block. The reports denotes default values with periods (..). The end of the report shows the total number of fields cross-referenced, the associated screens reported, and the actual number of stored screens. The report documents this aspect of your application to support future maintenance and enhancement efforts.

Parent topic: Application Reports
Related tasks
To run the Field/Screen Cross Reference report


Macro/Program Cross Reference Report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Macro/Program Cross Reference Report lists the rules used in one or more applications, along with all of the programs that invoke the rules, and the rule libraries that the programs reside in. Use the report to find all the programs and applications that use a given rule.

The cross-referenced rules appear alphabetically within an application on the report. If you report on all applications, the applications display alphabetically in the report. Specific rule libraries are listed as follows

  • Rule libraries specified in the Project Explorer display in the rulelib indicator column.
  • Global rule libraries display ***ALL*** in the type indicator column.
  • Global custom code and batch programs display ***STUB*** in the type indicator column.

After each application, summary statistics provide the

  • Total number of rules and libraries reported
  • Number of programs with rule calls
  • Number of common rule libraries
  • Total number of programs in that application
Parent topic: Application Reports
Related tasks
To run the Macro Cross Reference report


Program DB/DC Report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Program DB/DC Report documents the screens and data definitions used by a program. The report has three sections:

  • Tables/Views or Records - database table, view, or record names showing hierarchical relationships, if applicable.
  • Record IO Areas - database record descriptions, including host variable descriptions, if applicable. Records are listed alphabetically by record name.
  • Screen IO Areas - COBOL screen field descriptions for up to 20 screens, arranged alphabetically.
Parent topic: Application Reports
Related tasks
To run the Program DB/DC report


Analysis Option

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AppMaster Builder Analysis Option gives a tree view of the relationships of the components in an application or group of applications. All the components are listed at the top level. You can expand any component to see what components it accesses and what components it's accessed by. You can also see which components contain macro definitions.

To use Analysis Option, you must have the objects of your application (such as the screens, data and logic) defined in the AppMaster Builder Project Explorer.

You generate the analysis in stages, by generating the application first followed by the analysis. You can then display the analysis and browse the relationships as required.

When you are browsing the analysis you can show and hide components by setting browser options. You can also double-click to invoke the relevant editor or browser at the relevant place.

  • Generating the Analysis
  • Browsing the Analysis
  • Analysis Browser Features and Options
  • Handling Changes
Parent topic: Developing Applications in the AppMaster Builder Perspective
Related concepts
The AppMaster Builder Tool Set


Generating the Analysis

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Important: To ensure that you generate a complete analysis for an application, you must be sure that each object in the application generates without errors. Before generating an analysis, we recommend that you generate an application, including all of its objects, and then consult the Job Queue to see that each object has built correctly. The Job Queue shows a list of generated application objects on the left and the text of the job log on the right. Correct all errors before continuing.

You generate the analysis in stages as follows:

Stage 1: Generate application and program manifests
Before generating the application, you need to enable the creation of program manifests by checking Generate program manifest on the Output preferences page. Then, when you generate the application, AMB generates both the COBOL code and the program manifests.

One program manifest is created for each program, and each manifest contains a list of all the components in the program. The manifests are recreated every time you regenerate the application.

The program manifests are stored in the APXPROG project subdirectory. Generally, you don't need to access the manifests.

Stage 2: Generate a rule definition file
The rule definition file lists where each User Rule is located in the application's programs. When you generate this file, you can specify which directories to search for User Rule files, or you can search the default directories, such as APSMACS and CNTL (both located by default under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc (Windows) or $COBDIR/etc (UNIX)). The rule definition file is an XML file, macrodef.xml and is stored in your project's root directory. The Analysis Browser uses the rule definition file when displaying an analysis.
Stage 3: Generate the analysis
You can generate an analysis for the whole project or for just one application, as follows:
Project analysis
This creates an XML file containing an analysis of each application and program in your project, and is created using the information from the program manifest files together with information on the application files. The project analysis file has the same name as your project and is stored in your project's root directory.
Appication analysis
This creates an XML file containing an analysis of a single application, and is created using the information from the program manifest files. The application analysis file has the same name as your application and is stored in the APXAPPL project subdirectory.

The Analysis Browser uses the analysis XML file when displaying an analysis. The file might also be of use to you in other ways. For example, if you want to copy files from AppMaster Builder, the analysis file gives you a complete inventory of the application.

Parent topic: Analysis Option
Related tasks
To generate a rule definition file for an analysis
To generate a project analysis
To use the Job Queue
To generate an application analysis
Related reference
Output


Browsing the Analysis

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Analysis Option shows a tree view of the relationships of the components in an application or group of applications. All the components are listed at the top level. You can expand any component to see what components it accesses and what components it's accessed by, as well as what user rule definitions it contains. See the following figures for an example.

Figure 1. Analysis Option Browser
Analysis Option Browser

This first figure shows the analysis of the supplied demonstration project bldrappl. Notice the following:

  • The Title bar shows the name of the application bldrappl.
  • At the top level, there are folders for each type of component, such as Programs and APSMACS through to Rule Definitions and External Calls.
  • The Programs folder lists the two programs in the application: bldrcadd and bldrcmnu.
  • The Programs\BLDRCADD and Programs\BLDRCMNU folders each have two subfolders: Accesses and Accessed By. The next figure shows the analysis with the BLDRCADD\Accesses folder expanded.
  • The APSMACS folder lists all the apsmacs components used in the application, starting with apcicstp.
Figure 2. Expanded Analysis
Expanded Analysis

This figure shows the same analysis with the BLDRCADD\Accesses folder expanded. Notice that:

  • The bldrcadd program accesses the data view apsadd, the apsmacs component apxmacs, the screen bldrca and so on.
  • The Location column shows the path to bldrcadd and shows the line on which bldrcadd accesses each component. For example, bldrcadd accesses the user rule tp-perform on lines 11, 29, 36, 40 and so on.

    You can double-click a component to open bldrcadd in your default editor.

In addition to the Accesses and Accessed By folders, there is a third folder, Contains. The Contains folder is displayed for copybooks and user rules (apsmacs, usermacs, cntl and user cntl), if relevant. The Contains folder lists any user rule definitions that the component of interest contains.

Most folders are associated with physical files. However the folders for Rule Definitions and External Calls are associated with logical definitions.

Parent topic: Analysis Option
Related tasks
To generate an application analysis
To generate a project analysis
Related reference
Analysis Browser


Analysis Browser Features and Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Analysis Browser has the following features. You can:

  • Double-click a file reference and go directly to that line in the relevant editor or painter.
  • Sort the display in alphabetical order (or the reverse) by column. Click the column heading to do this and click it again to reverse the order.
  • Search for items by entering text, and wildcards if you want, in the entry field at the top of the browser window. You click Find Items Find Items at the top right of the window to start the search.
  • Show only items you are interested in by setting the browser options. Click Options Options at the top right of the window to do this.

    For example, you could display just programs, copybooks and screens. Alternatively, you could display only direct references at the top level, instead of both indirect and direct references. Showing only direct references can make the analysis easier to interpret.

The options you choose and the layout for the browser are used the next time you invoke the Analysis Browser.

Parent topic: Analysis Option
Related tasks
To set options for the analysis browser
Related reference
Analysis Browser Options


Handling Changes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can view an existing analysis at any stage during the development cycle. The following might be useful when making changes to an application:

  • When you generate the analysis, if some programs in the applications are not compiled or are not available, you are informed. If you choose to continue, the Analysis Browser highlights where information is missing.
  • When you open the Analysis Browser, it checks for changed files and marks the changed items with an X.
  • If some components have changed, you can regenerate just those components without regenerating the whole application. You then need to regenerate the analysis for the whole application.
Parent topic: Analysis Option
Related reference
Analysis Browser


Developing Applications in the Team Developer Perspective (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

The process of developing applications using AMB in the Team Developer Perspective is very much the same as when using the AppMaster Builder perspective, but with the following differences:

AppMaster Builder Perspective | Team Developer Perspective
Provides the traditional Application View and Database View via the Project Explorer and Database View Explorer tabs respectively. | Provides the traditional Application View via the Application Explorer tab, but does not provide access to the traditional Database View.
Does not provide access to Endevor mainframe datasets. | Provides full access to Endevor mainframe datasets via the AMB Endevor Interface. See AMB Endevor Interface for details. (Technology Preview)
Supports drag and drop within the Project Explorer. | Does not support drag and drop.
Supports Find in Application(s) from the Project Explorer. | Does not support Find in Application(s).
Provides tooltips in the Project Explorer. | Does not provide tooltips.
Provides toolbar icons for quick access to the following:
  • Start/Stop AppMaster Builder Server
  • AppMaster Builder Console view
  • Job Queue view
  • AppMaster Builder preferences page
No toolbar icons are provided; however, all functions are available via context or main menu options.

You are not limited to using one perspective at a time. You can load your AppMaster Builder project into both the AppMaster Builder and the Team Developer perspectives simultaneously and toggle between the two from Eclipse. Updates made in either perspective are reflected in the other.

The AMB in the Team Developer Perspective feature is delivered as part of an Application Workflow Manager (AWM) attachment. Before you can use it, you must install the AMB Attachment on your local machine. See Workflow Manager AMB Attachment for details.

Parent topic: AppMaster Builder
Related concepts
Developing Applications in the AppMaster Builder Perspective
AMB Endevor Interface (Technology Preview)
Prerequisite (Technology Preview)
Workflow Manager AMB Attachment (Technology Preview)
Related tasks
AMB Endevor Interface (Technology Preview)


AMB Endevor Interface (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

The AMB Endevor Interface enables you to share and synchronize resources between an AMB project and mainframe Endevor datasets.

The AMB Endevor Interface is delivered as an Application Workflow Manager (AWM) attachment. Before you can use it, you must install the Endevor Attachment on your mainframe, and the AMB Attachment on your local machine. In addition, you must establish a mainframe connection in Eclipse. See Workflow Manager Endevor Attachment, Workflow Manager AMB Attachment, and Defining a client connection to z/Server for details.

Parent topic: AppMaster Builder
Related concepts
Developing Applications in the Team Developer Perspective (Technology Preview)
Prerequisite (Technology Preview)
Workflow Manager Endevor Attachment
Workflow Manager AMB Attachment (Technology Preview)


Generating Code

Explains the processes of generating AMB objects, such as screens, programs, and full applications from both the Enterprise Developer IDE in Eclipse and from the command line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Generating Objects

You can generate source code for a single object listed on the Program Explorer. Each object generates code as specified by your AppMaster Builder preferences and/or object properties.

Generating Applications

When you generate an application, the AppMaster Builder Generator and Precompiler translate your AppMaster Builder specifications into a complete, executable structured COBOL application.

The generation options you assign regulate how AppMaster Builder generates an application. Options are available for controlling both the Generator and Precompiler, as well as target-specific options.

When AppMaster Builder generates an application, it:

  • Ensures that each component of the application exists.
  • Rearranges program specifications into proper COBOL program organization.
  • Includes externally-defined information that the program references, such as copyfiles and user-defined rules, at the appropriate COBOL program locations.
  • Processes all database and user interface calls and user-defined rules, translating all source to COBOL source.
  • Generates screen symbols for the precompiler and screen source for the data communications user interface.
  • Translates all AppMaster Builder Report Writer source to COBOL source.
  • Writes a temporary error message file and merges it with the COBOL compiler error message file. The combined error message file presents messages sorted by program line number with both types of messages appearing where appropriate.

Generated Source Code Locations

By default, generated source code is saved in the testlib subdirectory of your User Area as specified in your AppMaster Builder preferences. However, you can redirect source code output by checking the Save COBOL, Save GENSRC, or Save MFS / BMS output options. These options redirect source code output to a subdirectory of your Project path. For a list of these subdirectories and their contents, see AMB Libraries and Directories.

Customizations via APRPROG

Program properties are stored in an APRPROG member, which is required for successful generation. If no APRPROG member is found during generation, generation fails unless you have set the Use default APRPROG if none found in the AppMaster Builder Output preferences. When set, this option enables successful generation by creating a temporary program property file. By default, all property values in the temporary file are set to system defaults.

Important: The only exception is the Online Express/Program Painter flag. This flag is dynamically set during generation, depending on the existence of an APSEXPS member with the same program name.

However, when no APRPROG member is found during generation and the Use default APRPROG if none found option is turned on, you can override default property values by providing your own set of properties and values in an aprprog.tmpl file. When present, the values set in the template file are used in the generated temporary APRPROG member.

Create an aprprog.tmpl file in any editor; then copy it to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\template\amb\properties directory.

For more information, see To set AppMaster Builder preferences and Output.

You can generate objects and applications from the Enterprise Developer IDE in Eclipse, or from the command line.

  • Generating from the IDE
  • Generating from the Command Line
  • Using the Batch Server
  • Job Queue Log Management
  • Compiling in a COBOL project
Parent topic: AppMaster Builder
Related tasks
To set AppMaster Builder preferences
Related reference
Libraries and Directories
AppMaster Builder
Output


Generating from the IDE

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Options are available for controlling both the Generator and Precompiler, as well as target-specific options. After setting your output options, you generate the entire application from the Enterprise Developer IDE in Eclipse with one action; however, you can also generate specific objects of an application, including:

  • A specific program
  • A specific screen
  • All programs in the application
  • All screens in the application
  • Programs coded manually using S-COBOL (APSSRC)
  • Programs generated from S-COBOL (GENSRC)
Note: You must generate the screens of a program before you can successfully generate the program.
Parent topic: Generating Code
Related tasks
To generate a single program or screen
To generate an application, all programs, or all screens
To generate multiple-map mapsets for CICS applications


Generating from the Command Line

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can generate applications from the command line as an alternative to generating from the Enterprise Developer IDE in Eclipse. To enable this feature, you must create a configuration XML file for each object or application you want to generate. An application's configuration XML file contains all the information necessary to generate the screens, multiple-map mapsets, and programs of the application.

Note: The command-line generation feature does not support the generation of COBOL copybooks (COPYLIB files) from data structure (APSDATA) files and data definition interface (DDI) symbols files. You must generate these files from the IDE.

Configuration XML File

You must create a configuration XML file manually using a specific structure and XML elements as described in the Configuration XML File reference topics. See also To create a configuration XML file.

The configuration XML file you generate for an application is stored in the cmdgnxml project subdirectory, and is named as follows:

ap_applicationname.xml

Once you have created the configuration XML file, you can generate it from the command line.

cmdgen Command

Use the cmdgen command to generate a full application or one or more application objects. For complete information, see To generate from the command line and the cmdgen command reference topic.

Parent topic: Generating Code
Related tasks
To create a configuration XML file
To generate from the command line
Related reference
Configuration XML File
cmdgen command


Using the Batch Server

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Batch Server processes most of the activities executed within AppMaster Builder, such as code generation and compilation. AMB submits each process to the Batch Server, which then performs the appropriate tasks and reports the results to both the Logger and the Job Queue listing.

The Batch Server handles processes in the order they are submitted. The first job listed is the one currently being processed by the server; additional jobs listed are queued and processed in order.

The Batch Server window displays job information.

  • The Select column lets you delete jobs before they run.
  • The Submission ID column indicates the name of the file in the user JOBQUEUE directory being processed. Batch Server deletes this file after processing.
  • The User ID column names the person who submitted the job.
  • The Type field indicates what the submitted job is, such as a Program, Screen, or Report.
  • The Entity field names the Program, Screen, Report, etc., that the Server is processing.
  • The Date/Time column shows when the Batch Server received the job.
Parent topic: Generating Code


Job Queue Log Management

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The left pane of the Job Queue lists each file in the JOBQUEUE folder, showing in columns the same information contained in the filename. From the left pane, you can:

  • Select a job to view the contents of the log file in the right pane
  • Sort the jobs by any component of the job name
  • Resize the columns
  • Reorder the columns
Note: If you have customized the Job Queue to delete job logs after a specified number of days, the Job Queue shows only the job logs for jobs run within the specified number of days.
Parent topic: Generating Code
Related tasks
To use the Job Queue
To set AppMaster Builder preferences


Compiling in a COBOL project

If you have set your preferences to compile generated code in a COBOL project, AppMaster Builder automatically copies generated source members to the specified COBOL project where it is added to the COBOL project and compiled by Enterprise Developer.

Generated source members are added to the appropriate COBOL project folders such as COBOL Programs, Copybooks, BMS mapsets, etc.

If you have set your AMB Output preferences to generate S-COBOL, the generated S-COBOL source members appear in the COBOL project in a folder named S-COBOL.

Parent topic: Generating Code
Related concepts
Loading IMS
Related tasks
To set AppMaster Builder preferences
Related reference
Output
AppMaster Builder


Administration

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Some features in AppMaster Builder require the oversight of an administrator.

Access to two of these features is available from the Admin menu in AppMaster Builder:

Project
As an AMB Administrator, it is your responsibility to create and delete projects. AMB provides one default project on installation. The default location is \mfuser\project\group. This is the default project path for each user. Users can specify an alternative project in their AppMaster Builder preferences, but the alternative project must have been previously created by the AMB administrator.
DDI File Utilities
DDI files are source code files that contain statements defining the records that are built into a data view. You can unlock, backup, restore, and reorganize DDI files:
Unlock
Removes any Create or Update locks placed in an entity, and deletes incomplete entitles created during DDI loading.
Backup
Copies the DDIFILE to an OS sequential data set.
Restore
Copies the backup data set to the DDIFILE.
Reorganize
Convert the binary portion of the PC DDIFILE-KEY to the same binary storage format used on the mainframe. If you have DBDs, PSBs or VSAM sources that are large or need to be loaded frequently, it may be necessary to run this utility (i.e., especially if you get DDI-1024 errors).

In addition, AMB administrators are responsible for:

Creating and Maintaining Workgroup Libraries
Create and maintain the workgroup library files that each contain a list of workgroup LAN and/or mainframe library locations.
Implementation of Distributed Generation Server
Install and configure DGS mainframe components and third-party software required to synchronize your generated AppMaster Builder and APS for z/OS code.
Copying Properties to and from Programs and Applications
Use the APPLCPY and PROGCPY utilities to copy the properties of an application or a program and apply them to anther application or program.
  • Managing Workgroups
  • Distributed Generation Server
  • Copy Properties Utilities
Parent topic: AppMaster Builder
Related tasks
To create a new project
To delete a project
To maintain DDI files
To set AppMaster Builder preferences


Managing Workgroups

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

As an administrator, you can create an unlimited number of workgroups for your AMB users. Each workgroup can specify up to nine local or LAN directories, or mainframe PDSs, for each AMB library type. When a user requests a workgroup object from AppMaster Builder, these directories and PDSs are searched in the order they are listed in the workgroup.

You can order the directories and PDSs in a workgroup as you see fit with one exception. If a workgroup consists of a combination of local or LAN folders and mainframe PDSs, the mainframe PDSs must be placed after the local and LAN folders in the list.

Workgroups are available to all AMB users regardless of their primary project, provided they are running AppMaster Builder from the same location.

Note: For the AMB workgroup feature to properly access your mainframe, you must have the command-line interface for the Mainframe Access feature configured and running properly on your PC. For more information, see Configuration.
Parent topic: Administration
Related concepts
Configuration
Workgroups
Related tasks
To create a workgroup
To modify a workgroup
Related reference
Workgroup dialog box


Distributed Generation Server

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The AppMaster Builder Distributed Generation Server feature enables you to generate APS for z/OS code using AppMaster Builder on a local PC or LAN without having to download your APS source members and import them into an AppMaster Builder project. You can generate programs for CICS, IMS, ISPF, and MVS data communication targets, and screens for CICS and IMS data communication targets.

The DGS is designed to receive and send messages to and from your mainframe via a middleware interface. These messages provide information such as file names and locations, output requirements, and other preference settings. DGS generation is achieved using the following process:

  1. On the mainframe side, a message to AppMaster Builder is initiated in the JCL that runs an APS generation job by executing the DGS AMBCOMP program. The job pauses at that point, awaiting a return message.
  2. On the PC side, the message is received by the DGS, which downloads required APS source members and then generates them according to the details in the message. When generation is complete, the DGS initiates a return message to the mainframe and uploads the appropriate generated files.
  3. When the return message is received on the mainframe, depending on the message returned, the APS generation job either continues from the point after the execution of the AMBCOMP program, or stops running.

For detailed information describing the role of the AMBCOMP program and the middleware interface, see AMBCOMP Program and The WebSphere MQ DGS Interface.

To see example JCL that executes AMBCOMP, see JCL Example.

  • AMBCOMP Program
  • The WebSphere MQ DGS Interface
  • Software Requirements
  • Installing DGS Components
  • Installing WebSphere MQ
  • Setting DGS Options
Parent topic: Administration


AMBCOMP Program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To initiate Distributed Generation Server from the mainframe, you execute the AMBCOMP program from the JCL that is running your APS job. You can replace all of the standard APS generation steps with a single AMBCOMP step. The AMBCOMP program processes a set of SYSIN cards that specify the following:

  • AMB generation parameters
  • Cataloged PDS names containing input source files needed by the AMB generators
  • Cataloged PDS and member names of input CNTL files neede by the AMB generators
  • Cataloged PDS name where generated components and the AMB generation logfile are sent upon completion of the generation process

The AMBCOMP program passes this information to the Distributed Generation Server as an XML document. The Distributed Generation Server writes the document to an XML file in the apsftwrk subdirectory of the user area specified on the Distributed Generation Server workstation.

Note: If you start Distributed Generation Server with the Error Reporting Level set to Debug and Keep User Area Files checked, DGS keeps the XML file; it is not deleted and can be useful when tracking problems.

The DGS then parses this XML file and creates two files in the jobqueue subdirectory of the user area specified on the Distributed Generation Server workstation:

  • The first file has an extension of .lst and contains generation parameters and locations of input and output files
  • The second file has an extension of .sub and drives the AMB generators
Note: If you start Distributed Generation Server with the Error Reporting Level set to Debug and Keep Submission Files checked, DGS keeps these files; they are not deleted and can be useful when tracking problems.

After the AMB generation process completes, APSCOMP writes the AMB generation log file to the jobqueue subdirectory. This file does not have a file extension. It contains messages and return codes from each of the AMB generators.

After all of the appropriate AMB generators have finished, DGS uploads a number of files to mainframe-cataloged PDSs. These files include all generated components (e.g., COBOL programs, screen symbols, BMS, MFS, etc.) and the AMB generation log file.

Jobs steps following the AMBCOMP step, (e.g., DB2 translator, CICS translator, COBOL compiler, etc.) might execute, depending on the value of this return code.

Parent topic: Distributed Generation Server
Related concepts
Distributed Generation Server
Related reference
JCL Example


The WebSphere MQ DGS Interface

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This section provides an overview of WebSphere MQ technology, and how it interfaces with Distributed Generation Server. The definitions presented assume that WebSphere MQ distributed queuing is used and it is assumed that the proper sender and receiver channel pair definitions exist between each Distributed Generation Server machine and the mainframe:

Figure 1. WebSphere MQ to Mainframe Configuration
WebSphere MQ to Mainframe Configuration

Each Mainframe to DGS connection has a pair of local and remote queue definitions. Figure 1 is an example of this. On the mainframe, there is a remote queue definition, AMBCOMP.DS.Q, that refers to a local queue definition on the Distributed Generation Server. The local queue should be defined SHARE DEFSOPT(SHARED). On the Distributed Generation Server machine, there is a remote queue definition, AMBCOMP.MF.Q, that refers to a local queue definition on the mainframe. This local queue should also be defined SHARE DEFSOPT(SHARED).

The layer that interfaces with WebSphere MQ is called the Middleware Interface (MWI). The MWI puts messages into the queue and gets messages from the queue. Messages are sent from AMBCOMP to the Distributed Generation Server via the MWI.

The Distributed Generation Server MWI waits to receive a message. In this example, it monitors AMBCOMP.DS.Q. When a message is received, it processes the generation request. When the generation request is complete, a message is placed into the reply queue (AMBCOMP.MF.Q) and then the Distributed Generation Server gets the next message from the queue. If there are no messages available, the Distributed Generation Server waits.

On the mainframe, messages are retrieved from AMBCOMP.MF.Q by correlation ID, thus ensuring that response messages are delivered to the AMBCOMP process that initiated the generation request.

For information on specifying WebSphere MQ objects to the Distributed Generation Server Mainframe and PC environments, see Installing WebSphere MQ.

Parent topic: Distributed Generation Server
Related concepts
Installing WebSphere MQ
Distributed Generation Server


Software Requirements

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In addition to Micro Focus software products, Distributed Generation Server also requires third-party middleware interface software components on both the mainframe and the PC/LAN to facilitate communication between APS for z/OS on the mainframe and AppMaster Builder on the PC/LAN. Because the purpose of the Distributed Generation Server is to generate code from source members created on the mainframe using APS for z/OS, we assume that you have both the software and one or more APS projects in place on your mainframe. See your APS documentation for complete information.

The full inventory of software you need to support the installation and execution of the Distributed Generation Server consists of:

Mainframe
  • APS for z/OS
  • Distributed Generation Server mainframe components, provided with the AppMaster Builder AddPack (see PC/LAN below)
  • IBM WebSphere MQ mainframe components (middleware interface software)
PC/LAN
  • Micro Focus Enterprise Developer for Eclipse, version 2.2 Update 1 or later
  • AppMaster Builder AddPack
  • IBM WebSphere MQ PC/LAN components

The following third-party software has been tested with DGS:

  • IBM z/OS 1.2 through 2.1
  • IBM WebSphere MQ 5.3
Parent topic: Distributed Generation Server


Installing DGS Components

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Distributed Generation Server requires that certain components be installed both on the PC and on the mainframe.

Distributed Generation Server PC Installation

The PC components of Distributed Generation Server are automatically installed with the AppMaster Builder AddPack.

Distributed Generation Server Mainframe Installation

The DGS mainframe components are provided by the AMB AddPack; however, you must install them onto your mainframe.

The Distributed Generation Server mainframe installation files are located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\mainframe directory, and include:

File | Description
CNTL.bin | A binary image containing AMB CNTL files
ISPPLIB.bin | A binary image containing ISPF panels
ISPPLIBH.bin | A binary image containing ISPF Help panels
ISPSLIB.bin | A binary image containing ISPF file tailoring skeletons
LOADLIB2.bin | A binary image containing executable files
instjcl.txt | A text file containing installation JCL

If you are upgrading from a previous version of Distributed Generation Server, you need to replace the old Distributed Generation Server files on the mainframe with the new files supplied with this version.

See To install or update DGS mainframe files for installation instructions.

Parent topic: Distributed Generation Server
Related tasks
To install or update DGS mainframe files


Installing WebSphere MQ

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

WebSphere MQ Mainframe Installation

For installation and customization instructions, see your IBM WebSphere MQ for z/OS Program Directory and IBM WebSphere MQ for z/OS System Management Guide.

After installing WebSphere MQ, define WebSphere MQ objects as described in The WebSphere MQ DGS Interface.

WebSphere MQ PC Installation

For installation and customization instructions, see your IBM WebSphere MQ documentation.

Parent topic: Distributed Generation Server
Related concepts
The WebSphere MQ DGS Interface


Setting DGS Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Before starting DGS, you can set options that enable you to dictate how AMB handles log files, user exits, diagnostic files, and performance monitoring.

Logfiles
DGS provides several options for the generation of logfiles. You can set a maximum length for a logfile and set DGS to copy full logfiles to a backup filename and location. Each time a logfile becomes full, it is copied off and logging continues in a new logfile. This feature enables you to save all of your log information without creating very large and cumbersome logfiles, and can be especially useful if your system has a file size limit.

You can also set up a user exit to execute when a logfile becomes full.

User Exits
In addition to the user exit you can specify to execute when a logfile becomes full, you can also specify a user exit to execute when you start DGS and a user exit to execute when you stop DGS. You can either have your user exits execute in the background, or you can specify that they execute and show in a window. You can also set a timeout interval to specify how much time DGS should wait before executing a user exit.
Diagnostics
DGS creates several diagnostic files you can view to help you in debugging, and stores registry values as well. By default, diagnostic files and values are deleted when you regenerate your application. However, you can set DGS to save diagnostics so you can have them for future reference and to compare current generation diagnostics with previous diagnostics. DGS creates the following types of diagnostic files:
  • Job Submission - .sub and .lst files stored in the JOBQUEUE directory
  • Project Shadow Group - files downloaded from the mainframe into the current User Area
  • User Area

DGS stores Registry Work Group values as well.

Performance Monitoring

The Performance Monitoring feature of DGS enables you to capture statistics for every task that executes during application or program generation. This information can help you to adjust your system for optimal performance. For example, one of the statistics captured by DGS performance monitoring is the amount of time it takes to execute a particular task. If a great deal of time is being spent on searching for files in the PDS order specified in your Work Group, you can adjust the PDS search order to enable DGS to find files more quickly.

Performance statistics for each job are saved in the APSFTWRK directory of your user test area in a file named performance.log. This file is overwritten each time you kick off a generation. However, you can also set your DGS options to back up the existing performance.log file before it is overwritten. DGS copies the existing performance.log file to a directory you specify, renaming the file using a convention that shows the type of object generated, the name of the object, the date it was generated, and the time it was generated as follows:
objType_objName_ddmmmyyyy_hhmmss.txt
For example, if you kicked off the generation of a screen named MASTX at noon on the 25th of December, 2020, the backup performance log filename would be:
SCREEN_MASTX_25DEC2020_120000.txt
MQ Options
You can set DGS MQ options to enable automatic reconnection to WebSphere MQ in the event that the connection between DGS and WebSphere MQ is interrupted during processing.

By default, when DGS loses its connection to WebSphere MQ, AppMaster Builder writes an error to the Logger window, disconnects the DGS from the MQ interface, and switches the Server to an AppMaster Builder Batch Server. When WebSphere MQ is once again available, you must manually restart DGS.

DGS MQ options enable you to set parameters that specify how many times the DGS should attempt to reconnect, and how much time it should wait between attempts. If a reconnection is made within the specified parameters, the DGS continues processing where it left off. If no reconnection is made, AppMaster Builder switches the Server from DGS to AppMaster Builder Batch Server. In this case, when WebSphere MQ is once again available, you must manually restart the DGS.

Parent topic: Distributed Generation Server


Copy Properties Utilities

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The PROGCOPY and APPLCOPY utilities enable you to copy the properties from one program or application and apply them to another.

PROGCOPY
AMB provides this utility to enable you to copy program properties from one program to one or more other programs without having to set the properties for each program manually. This can be particularly useful when you migrate applications from the mainframe or from earlier versions of AppMaster Builder.
APPLCOPY
The APPLCOPY utility is similar to the PROGCOPY utility in that it enables you to propagate the application properties from one application to one or more other applications without having to set them manually.
Parent topic: Administration
Related tasks
To copy program properties
To copy application properties


How to

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Administration
  • AMB Endevor Interface (Technology Preview)
  • Analysis Option
  • Application Reports
  • Code Generation
  • Database Views
  • Online Express
  • Preferences and Properties
  • Program Painter
  • Projects
  • Report Painter
  • Screen Painter
  • User Areas
Parent topic: AppMaster Builder


Administration

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To change the administration password
  • To copy program properties
  • To copy application properties
  • To create a new project
  • To create a workgroup
  • To delete a project
  • To maintain DDI files
  • To modify a workgroup
  • To install or update DGS mainframe files
  • To configure DGS mainframe execution
  • To set DGS PC options
  • To start Distributed Generation Server
Parent topic: How to


To change the administration password

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder perspective from either tab, click Admin > Change Admin Password.
  2. Complete the fields.
  3. Click OK. The new password takes effect.
Parent topic: Administration


To copy program properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the Project Explorer, identify a program that contains the properties you want to copy to one or more other programs. Or, alternatively, select a program and set its properties to reflect those you want to copy to one or more other programs. The program you select is your source program.
  2. At a command prompt, change to your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.
  3. If you want to update programs that reside in more than one application, using a text editor, create a text file that contains a list of the names of those applications. (optional)
  4. At the command prompt, enter the following:
    progcopy sourceprogram {-a applicationname | -f inputfile} [project]

    Parameters:

    sourceprogram | The name of the program you want to copy from.
    applicationname | The name of the application that contains the programs you want to update with properties from the source program.
    inputfile | The name of the text file that contains a list of applications whose programs you want to update. Optionally created in step 3. If the text file you created resides in a directory other than %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin, include the full path to the file as well.
    project | The full path to an alternate project in which the application or applications specified are found. If you do not specify a project, AMB defaults to the project specified in your AppMaster Builder preferences.
    Note:
    • The source program and all applications specified must be part of the same project.
    • All programs in each application specified are updated.
Parent topic: Administration
Related concepts
Copy Properties Utilities
Related tasks
To set AppMaster Builder preferences


To copy application properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the Project Explorer, identify an application that contains the properties you want to copy to one or more other applications. Or, alternatively, select an application and set its properties to reflect those you want to copy to one or more other applications. The application you select is your source application.
  2. At a command prompt, change to your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.
  3. If you want to update more than one application, using a text editor, create a text file that contains a list of the names of those applications. (optional)
  4. At the command prompt, enter the following:
    applcopy sourceapp {-a applicationname | -f inputfile} [project]

    Parameters:

    sourceapp | The name of the application you want to copy from.
    applicationname | The name of the application you want to update with properties from the source application.
    inputfile | The name of the text file that contains a list of applications. Optionally created in step 3. If the text file you created resides in a directory other than %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin, include the full path to the file as well.
    project | The full path to an alternate project in which the application or applications specified are found. If you do not specify a project, AMB defaults to the project specified in your AppMaster Builder preferences.
    Note: The source application and all applications specified must be part of the same project.
Parent topic: Administration
Related concepts
Copy Properties Utilities
Related tasks
To set AppMaster Builder preferences


To create a new project

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. With the AppMaster Builder perspective active, click Admin > Project > Create.
  2. In the Administrator Password field, type the password; then click OK.
  3. In the Qualifier field, type the full path to a directory you want to designate as the parent directory for your project.
  4. In the Project field, type the name of a subdirectory to the path you specified in the Qualifier field to serve as a parent to the various groups you want to use, or that is already a parent directory for existing groups.
  5. In the Group field, type the name of a subdirectory to the directory specified in the Project field.
  6. Click Create. If the path and directories you have specified do not exist, AMB creates them for you.
Note: You can also use the Browse button to select a project if the path and directories already exist.
Parent topic: Administration
Related concepts
Administration


To create a workgroup

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Using a text editor, create a file in a workgroup folder location. This can be any folder you designate, and is the folder users select to specify a workgroup for a project. Give the file a name of your choice, but specify no file extension.
  2. At the top of the file, starting in column 1, type the name of an AMB library type. AMB library type names are the same names used for project subdirectories, plus APSMACS and CNTL.
  3. On the line directly beneath the AMB library type name, type the full path to a directory that contains the type of objects specified by the library type. The directory can be a local, LAN, or PDS location.
  4. On the next line, type the full path to another directory that contains the type of objects specified by the library type. (optional)
  5. Continue adding directories in the same manner until you have listed all locations you want to include in the workgroup for the library type.
    Important: If you want to include both PC (local and LAN) and mainframe locations for a single library type, list all PC locations first, followed by the mainframe locations. You can specify up to nine PC locations and nine mainframe locations for each library type.
  6. Add additional library types and locations as necessary, placing the next library type designation on the line directly below the last location specified for the previous library type.
    Note: When you have a COBOL Project directory specified in your AppMaster Builder Preferences, you can include the $COBOLPROJECT$ variable as a location for the COPYLIB library type. $COBOLPROJECT$ resolves to the defined COBOL Project directory. You can further qualify $COBOLPROJECT$ by adding one or more subdirectories separated by a forward slash (/). For example, $COBOLPROJECT$/copylib.
  7. When you have added all of the library types and locations you require, save the file and exit the text editor.

Example workgroup file:

APSPROG
Z:\OtherProjects\projects\lan01\project\group\APSPROG
Z:\OtherProjects\projects\lan02\project\group\APSPROG
Z:\OtherProjects\projects\lan03\project\group\APSPROG
Z:\OtherProjects\projects\lan04\project\group\APSPROG
Z:\OtherProjects\projects\lan05\project\group\APSPROG
Z:\OtherProjects\projects\lan06\project\group\APSPROG
Z:\OtherProjects\projects\lan07\project\group\APSPROG
Z:\OtherProjects\projects\lan08\project\group\APSPROG
Z:\OtherProjects\projects\lan09\project\group\APSPROG
APSDATA
Z:\MoreProjects\project\group1\APSDATA
Z:\MoreProjects\project\group2\APSDATA
Z:\MoreProjects\project\group3\APSDATA
Z:\MoreProjects\project\group4\APSDATA
Z:\MoreProjects\project\group5\APSDATA
MFI01.AMBQMF06.APSDATA
MFI01.AMBQMF07.APSDATA
MFI01.AMBQMF08.APSDATA
MFI01.AMBQMF09.APSDATA
COBIMS
MFI01.AMBQMF01.COBIMS
MFI01.AMBQMF02.COBIMS
MFI01.AMBQMF03.COBIMS
MFI01.AMBQMF04.COBIMS
MFI01.AMBQMF05.COBIMS
MFI01.AMBQMF06.COBIMS
MFI01.AMBQMF07.COBIMS
MFI01.AMBQMF08.COBIMS
MFI01.AMBQMF09.COBIMS
COPYLIB
$COBOLPROJECT$/copylib
Parent topic: Administration
Related concepts
Workgroups
Managing Workgroups
Related tasks
To modify a workgroup
To specify a workgroup
Related reference
Workgroup dialog box


To delete a project

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the Project Explorer, click Admin > Project Data Set > Delete Project. If the Administration dialog box appears, type your password and click OK.
  2. In the Qualifier field, type the full path to the parent directory of your project area.
  3. In the Project field, type the name of the subdirectory of the path you specified in the Qualifier field that serves as a parent to group you want to delete.
  4. In the Group field, type the name of a subdirectory to the directory specified in the Project field that you want to delete.
  5. Click Delete.
Note: You can also use the Browse button to select a project to delete.
Parent topic: Administration
Related concepts
Administration


To maintain DDI files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder desktop in any View, click Admin > DDI File Utilities. If the Administration dialog box appears, enter your password and click OK.
  2. Click any of the following from the fly-out menu:
    • Unlock to unlock the DDI file, by removing any Create or Update locks placed in an entity. Unlock also deletes incomplete entitles created during DDI loading.
    • Backup to copy the DDIFILE, via a DOS COPY, to an OS sequential data set.
    • Restore to copy the backup data set to the DDIFILE.
    • Reorganize to convert the binary portion of the PC DDIFILE-KEY to the same binary storage format used on the mainframe. If you have DBDs, PSBs or VSAM sources that are large or need to be loaded frequently, it may be necessary to run this utility (i.e., especially if you begin to get DDI-1024 errors).
  3. AppMaster Builder immediately executes the process.
Note: The Reorganize utility is for DDI files used on the PC only; it is not applicable for the z/OS DDIFILE. A copy of your unconverted DDIFILE is created and saved under the name DDIUNCNV in case execution errors occur during the Reorganization process.
Parent topic: Administration
Related concepts
Administration


To modify a workgroup

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Using a text editor, open an existing workgroup file.
  2. Using the instructions in the topic To create a workgroup, edit the file to reflect changes, deletions, and additions to AMB library types and locations.
Parent topic: Administration
Related concepts
Workgroups
Managing Workgroups
Related tasks
To create a workgroup


To install or update DGS mainframe files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Pre-allocate the following TSO/mainframe datasets, substituting a high-level dataset name qualifier appropriate to your own site for your.name. Use the same qualifier for both datasets. These datasets are used to store the files that you upload from the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\mainframe directory.
    your.name.CNTL.X
A sequential fixed block file
organization  PS
record format FB
record length 80
block size    6160

your.name.ISPPLIB.X
A sequential fixed block file
organization  PS
record format FB
record length 80
block size    6160

your.name.ISPPLIBH.X
A sequential fixed block file
organization  PS
record format FB
record length 80
block size    6160

your.name.ISPSLIB.X
A sequential fixed block file
organization  PS
record format FB
record length 80
block size    6160

your.name.LOADLIB2.X
A sequential fixed block file
organization  PS
record format FB
record length 80
block size    3120
  2. Transfer the binary files to the TSO/mainframe datasets you just created. Transfer to the mainframe using binary mode (no ASCII to EBCDIC conversion). Although this example shows the appropriate ftp commands, you can also transfer the files using IND$FILE or any other file transfer tool that you have:
    put CNTL.bin        'your.name.CNTL.X'
put IPSPPLIB.bin    'your.name.ISPPLIB.X'
put IPSPPLIBH.bin   'your.name.ISPPLIBH.X'
put ISPSLIB.bin     'your.name.ISPSLIB.X'
put LOADLOIB2.bin   'your.name.LOADLIB2.X'
  3. Transfer the instjcl.txt fileto any suitable PDS, substituting the name of the PDS for your.pds. Transfer this file to the mainframe in ASCII mode. Although this example shows the appropriate ftp commands, you can also transfer the files using IND$FILE or any other file transfer tool that you have:
    put instjcl.txt 'your.pds(INSTJCL)'
  4. Customize the installation JCL by editing the INSTJCL member:
    //jobname JOB (9999,9999),'DEFINE ',
//   MSGCLASS=X,CLASS=A,NOTIFY=&SYSUID,
//   MSGLEVEL=(1,1)
//*******************************************************
//DGSINST PROC PREFIX=
//DELETE  EXEC PGM=IEFBR14
//DEL1 DD DSN=&PREFIX..CNTL,DISP=(MOD,DELETE),
//        SPACE=(TRK,(1))
//DEL2 DD DSN=&PREFIX..ISPPLIB,DISP=(MOD,DELETE),
//        SPACE=(TRK,(1))
//DEL3 DD DSN=&PREFIX..ISPSLIB,DISP=(MOD,DELETE),
//        SPACE=(TRK,(1))
//DEL4 DD DSN=&PREFIX..ISPPLIBH,DISP=(MOD,DELETE),
//        SPACE=(TRK,(1))
//DEL5 DD DSN=&PREFIX..LOADLIB,DISP=(MOD,DELETE),
//        SPACE=(TRK,(1))
//STEP20  EXEC PGM=IEFBR14
//CREATE1 DD DSN=&PREFIX..CNTL,SPACE=(CYL,(5,2,80)),
//        DCB=(LRECL=80,RECFM=FB,BLKSIZE=22480),
//        UNIT=SYSDA,DISP=(NEW,CATLG)
//CREATE2 DD DSN=&PREFIX..ISPPLIB,SPACE=(CYL,(5,2,80)),
//        DCB=(LRECL=80,RECFM=FB,BLKSIZE=22480),
//        UNIT=SYSDA,DISP=(NEW,CATLG)
//CREATE3 DD DSN=&PREFIX..ISPPLIBH,SPACE=(CYL,(5,2,80)),
//        DCB=(LRECL=80,RECFM=FB,BLKSIZE=22480),
//        UNIT=SYSDA,DISP=(NEW,CATLG)
//CREATE4 DD DSN=&PREFIX..ISPSLIB,SPACE=(CYL,(5,2,80)),
//        DCB=(LRECL=80,RECFM=FB,BLKSIZE=22480),
//        UNIT=SYSDA,DISP=(NEW,CATLG)
//CREATE5 DD DSN=&PREFIX..LOADLIB,SPACE=(CYL,(5,2,80)),
//        DCB=(LRECL=0,RECFM=U,BLKSIZE=22528),
//        UNIT=SYSDA,DISP=(NEW,CATLG)
//RECEIVE1 EXEC PGM=IKJEFT01,REGION=1024K
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//INFILE   DD DSN=&PREFIX..CNTL.X,DISP=SHR
//SYSTSIN DD DUMMY
//RECEIVE2 EXEC PGM=IKJEFT01,REGION=1024K
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//INFILE   DD DSN=&PREFIX..ISPPLIB.X,DISP=SHR
//SYSTSIN DD DUMMY
//RECEIVE3 EXEC PGM=IKJEFT01,REGION=1024K
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//INFILE   DD DSN=&PREFIX..ISPPLIBH.X,DISP=SHR
//SYSTSIN DD DUMMY
//RECEIVE4 EXEC PGM=IKJEFT01,REGION=1024K
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//INFILE   DD DSN=&PREFIX..ISPSLIB.X,DISP=SHR
//SYSTSIN DD DUMMY
//RECEIVE5 EXEC PGM=IKJEFT01,REGION=1024K
//SYSUDUMP DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//INFILE   DD DSN=&PREFIX..LOADLIB2.X,DISP=SHR
//SYSTSIN DD DUMMY
//  PEND
//DGSINST EXEC DGSINST,
//       PREFIX='your.name'
//RECEIVE1.SYSTSIN DD *
  RECEIVE INDDNAME(INFILE)
     DSN('your.name.CNTL')
/*
//RECEIVE2.SYSTSIN DD *
  RECEIVE INDDNAME(INFILE)
     DSN('your.name.ISPPLIB')
/*
//RECEIVE3.SYSTSIN DD *
  RECEIVE INDDNAME(INFILE)
     DSN('your.name.ISPPLIBH')
/*
//RECEIVE4.SYSTSIN DD *
  RECEIVE INDDNAME(INFILE)
     DSN('your.name.ISPSLIB')
/*
//RECEIVE5.SYSTSIN DD *
  RECEIVE INDDNAME(INFILE)
     DSN('your.name.LOADLIB2')
/*
    • Tailor the job card as needed
    • Set the PREFIX variable to the high level qualifier that you used for the CNTL.X, ISPPLIB.X, ISPPLIBH.X, ISPSLIB.X and LOADLIB2.X datasets
    • Change the dataset in the RECEIVE DSN parameter to:
      • your.name.CNTL
      • your.name.ISPPLIB
      • your.name.ISPPLIBH
      • your.name.ISPSLIB
      • your.name.LOADLIB2

      where your.name is the high level qualifier specified in the PREFIX variable.

  5. Submit INSTJCL to:
    • Allocate five libraries:
      • your.name.CNTL
      • your.name.ISPPLIB
      • your.name.ISPPLIBH
      • your.name.ISPSLIB
      • your.name.LOADLIB2
    • Populate the libraries with the data extracted from:
      • your.name.CNTL.X
      • your.name.ISPPLIB.X
      • your.name.ISPPLIBH.X
      • your.name.ISPSLIB.X
      • your.name.LOADLIB2.X
  6. Edit APS CLIST/Logon Procedures:
    • In the appropriate APS logon procedure or CLIST, enter your.name.ISPPLIB and your.name.ISPPLIBH as the first two files associated with the ISPPLIB DD name
    • In the appropriate APS logon procedure or CLIST enter your.name.ISPSPLIB as the first file associated with the ISPSLIB DD name
  7. Copy the following APSCNTL files to your mainframe APS installation area CNTL PDS:
    • your.name.ISPSLIB.CNTL.APSHEX
    • your.name.ISPSLIB.CNTL.APSHXMFG
Parent topic: Administration
Related concepts
Installing DGS Components


To configure DGS mainframe execution

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Install the Distributed Generation Server mainframe components.
  2. Install and configure WebSphere MQ on your mainframe.
  3. Start APS using the modified logon procedure/CLIST. For information on logon procedures and using CLISTs, see the chapter Installing APS for z/OS on the Mainframe in your APS for z/OS Installation Guide.
  4. From the APS main menu, select option 4 to go to the APS Utilities Menu.
  5. From the APS Utilities Menu, select option 5 to go to Distributed Generation Server.
  6. From the DGS Main Menu, select the MQS option to go to the DGS WebSphere MQ Options menu.
  7. Set options as required for your environment. See the Distributed Generation Server - Mainframe user interface reference topics for a description of each screen option and its field options.
  8. Press F3 to return to the DGS Main Menu.
Parent topic: Administration


To set DGS PC options

  1. From the AppMaster Builder Server IDE, click Options > Distributed Generation Server Options.
    Note: If the AppMaster Builder Server is not started, click Start Batch Server from the AppMaster Builder perspective.
  2. To set log file and user exit options, click the Project tab and set them as appropriate. For information on a specific field or control, see Distributed Generation Options - Logfile/User Exit tab .
  3. To specify diagnostic files, click the Diagnostics tab and check the boxes that correspond to the diagnostic file types you want to keep. For information on a specific diagnostic file type, see Distributed Generation Options - Diagnostics tab .
  4. To turn performance monitoring on, click the Performance Monitoring tab and check Performance Monitoring. Then set your monitoring options as appropriate. For information on a specific checkbox or field, see Distributed Generation Options - Performance Monitoring tab .
  5. To set options for WebSphere MQ, click the MQ Options tab and check Enable MQ Retry option. Then set your MQ retry options as appropriate. For information on a specific field, see Distributed Generation Options - MQ Options tab .
  6. Click OK to save your options and return to the AppMaster Builder Batch Server IDE.
Parent topic: Administration
Related reference
Distributed Generation Options – Logfile/User Exit tab
Distributed Generation Options – Diagnostics tab
Distributed Generation Options – Performance Monitoring tab
Distributed Generation Options – MQ Options tab


To start Distributed Generation Server

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Start Mainframe Access and log onto the mainframe. See Starting Mainframe Access for more information.
  2. If not already started, start the AppMaster Builder Batch Server.
  3. From the AppMaster Builder Batch Server IDE, click Options > Start Distributed Generation Server. The Start Distributed Generation Server Interface dialog box appears.
  4. Complete the fields and controls on this dialog box according to your configuration. For information on an individual field or control, see Start Distributed Generation Server Interface.
  5. Click Start.
  6. Verify that the Distributed Generation Server is running by clicking the Server Logger tab to see a listing of the settings you specified for the HTTP Interface.
Parent topic: Administration
Related reference
Start Distributed Generation Server Interface


AMB Endevor Interface (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
Attention: Tasks listed in this section must be performed from the Application Explorer view in the Team Developer perspective.
  • To add a single AMB element to Endevor (Technology Preview)
  • To add all AMB project elements to Endevor (Technology Preview)
  • To add all AMB folder elements to Endevor (Technology Preview)
  • To add multiple selected AMB elements to Endevor (Technology Preview)
  • To retrieve a single AMB element from Endevor (Technology Preview)
  • To retrieve all AMB project elements from Endevor (Technology Preview)
  • To retrieve all AMB folder elements from Endevor (Technology Preview)
  • To retrieve multiple selected AMB elements from Endevor (Technology Preview)
Parent topic: How to
Related concepts
Developing Applications in the Team Developer Perspective (Technology Preview)


To add a single AMB element to Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

Add directly from an AMB project:

  1. From the Application Explorer view, right-click an AMB project element; then select Add to Endevor from AMB Project from the context menu.
  2. Provide all required information on the Add to Endevor from AMB Project dialog box; then click OK.

Add from the Table Results tab:

  1. From the Application Explorer view, right-click an AMB project or folder; then select Show elements for Endevor Add from the context menu.

    This opens the Table Results tab showing a list of all elements associated with the project or folder selection.

  2. On the Table Results tab, right-click the element you want to add; then click Add element to Endevor.
  3. Provide all required information on the Add to Endevor from AMB Project dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


To add all AMB project elements to Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
  1. From the Application Explorer view, right-click an AMB project name; then select Add to Endevor from AMB Project from the context menu.
  2. Provide all required information on the Mass Add from Local Project dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


To add all AMB folder elements to Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
  1. From the Application Explorer view, right-click an AMB project folder such as a program or global folder; then select Add to Endevor from AMB Project from the context menu.
  2. Provide all required information on the Mass Add from Local Project dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


To add multiple selected AMB elements to Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
  1. From the Application Explorer view, right-click an AMB project or folder; then select Show elements for Endevor Add from the context menu.

    This opens the Table Results tab showing a list of all elements associated with the project or folder selection.

  2. On the Table Results tab, select the elements you want to add to Endevor.
  3. Right-click in the Table Results tab; then click Add elements to Endevor.
  4. Provide all required information on the Mass Add from Local Project dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


To retrieve a single AMB element from Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

Retrieve directly from an AMB project:

  1. From the Application Explorer view, right-click an AMB project element; then select Retrieve from Endevor to AMB Project from the context menu.
  2. Provide all required information on the Retrieve from Endevor to AMB Project dialog box; then click OK.

Retrieve from the Table Results tab:

  1. From the Application Explorer view, right-click an AMB project or folder; then select Show elements for Endevor Retrieve from the context menu.

    This opens the Table Results tab showing a list of all elements associated with the project or folder selection.

  2. On the Table Results tab, right-click the element you want to add; then click Retrieve element from Endevor.
  3. Provide all required information on the Retrieve from Endevor to AMB Project dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


To retrieve all AMB project elements from Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
  1. From the Application Explorer view, right-click an AMB project name; then select Retrieve from Endevor to AMB Project from the context menu.
  2. Provide all required information on the Mass Retrieve from Endevor dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


To retrieve all AMB folder elements from Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
  1. From the Application Explorer view, right-click an AMB project folder such as a program or global folder; then select Retrieve from Endevor to AMB Project from the context menu.
  2. Provide all required information on the Mass Retrieve from Endevor dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


To retrieve multiple selected AMB elements from Endevor (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
  1. From the Application Explorer view, right-click an AMB project or folder; then select Show elements for Endevor Retrieve from the context menu.

    This opens the Table Results tab showing a list of all elements associated with the project or folder selection.

  2. On the Table Results tab, select the elements you want to retrieve from Endevor.
  3. Right-click in the Table Results tab; then click Retrieve elements from Endevor.
  4. Provide all required information on the Mass Retrieve from Endevor dialog box; then click OK.
Parent topic: AMB Endevor Interface (Technology Preview)


Analysis Option

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To generate a project analysis
  • To generate an application analysis
  • To generate a rule definition file for an analysis
  • To set options for the analysis browser
Parent topic: How to


To generate a project analysis

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, generate a project, including its program manifests.
    Note: To ensure that AMB generates the program manifests, check Generate program manifest on the Output preferences page before generating the project.
  2. If you want the analysis to include User Rules, generate a rule definition file.
  3. From the Project Explorer, right-click the project; then select Analysis Option > Generate Project Analysis.
    Note: If you get a message saying that the file macrodef.xml does not exist, this means that you haven't generated a rule definition file. If you do not want the analysis to include User Rules, you can clear the message and continue. Otherwise, generate the rule definition file and then regenerate the project analysis.
Parent topic: Analysis Option
Related concepts
Generating the Analysis
Browsing the Analysis
Related tasks
To generate a rule definition file for an analysis
To set AppMaster Builder preferences
To generate an application, all programs, or all screens
Related reference
Output


To generate an application analysis

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, generate an application and its program manifests.
    Note: To ensure that AMB generates the program manifests, check Generate program manifest on the Output preferences page before generating the application.
  2. If you want the analysis to include User Rules, generate a rule definition file.
  3. From the Project Explorer, right-click an application object; then select Analysis Option > Generate Application Analysis.
    Note: If you get a message saying that the file macrodef.xml does not exist, this means that you haven't generated a rule definition file. If you do not want the analysis to include User Rules, you can clear the message and continue. Otherwise, generate the rule definition file and then regenerate the application analysis.
Parent topic: Analysis Option
Related concepts
Generating the Analysis
Browsing the Analysis
Related tasks
To generate a rule definition file for an analysis
To set AppMaster Builder preferences
To generate an application, all programs, or all screens
To set options for the analysis browser
Related reference
Output


To generate a rule definition file for an analysis

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
If you want the rule definition file to include User Rules that are stored in directories other than the default User Rule directories, which are APSMACS and CNTL (both located by default under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin) and the CNTL and USERMACS project subdirectories, add the non-default directories to the list of searched directories before generating the rule definition file:
  1. From the AppMaster Builder Project Explorer, right-click a project; then select Analysis Option > Rule Directory Selection.
  2. Click Add and specify a directory you want to search.
  3. In the same way, add or delete other directories as required.
  4. Click OK.

To generate the rule definition file:

  1. From the AppMaster Builder Project Explorer, right-click a project; then select Analysis Option > Generate Rule Definition File.
Parent topic: Analysis Option
Related concepts
Generating the Analysis
Related tasks
To generate an application analysis
To generate a project analysis


To set options for the analysis browser

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, generate the application analysis.
  2. Click Find Component at the top right of the browser window.
  3. Select the options you want. Among other things, you can show only direct references at the top level, which can make the analysis easier to interpret. Alternatively you can show both direct and indirect references at the top level.
  4. Click OK.
Parent topic: Analysis Option
Related concepts
Analysis Browser Features and Options
Related tasks
To generate an application analysis
Related reference
Analysis Browser
Analysis Browser Options


Application Reports

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To run an application report
  • To run the Component List report
  • To run the DDIFILE report
  • To run the Field/Screen Cross Reference report
  • To run the Macro Cross Reference report
  • To run the Program DB/DC report
  • To view an application report
Parent topic: How to


To run an application report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: This topic provides instructions for running the Application Definition, Data Structure Definition, Customized Mock-up, Program Definition, and Screen Hardcopy/Field Attribute reports.
  • From the AppMaster Builder Project Explorer, right-click on an application object you want to report on; then select Report from the context menu.
Parent topic: Application Reports
Related concepts
Application Definition Report
Screen HardcopyField Attribute Report
Related tasks
To view an application report


To run the Component List report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click the Project entry; then select Report > Component List Report.
  2. From the Entity Type drop-down list, click an entity type for which you want a report, or click All for all entities.
  3. Click OK to generate the report.
Parent topic: Application Reports
Related concepts
Component List Report
Related tasks
To view an application report


To run the DDIFILE report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, without selecting a component, right-click; then select Report > DDIFILE Report.
  2. Click OK to generate the report.
Parent topic: Application Reports
Related concepts
Application Definition Report
Related tasks
To view an application report


To run the Field/Screen Cross Reference report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, without selecting a component, right-click; then select Report > Field/Screen Cross Reference Report.
  2. To select a specific field, type its name in the Equal field.
  3. To select a range of fields, select the subset you need by entering a Greater than value, a Less than value, or both. Use alphabetic characters to indicate the range; full field names are not necessary. For example, to list fields with names beginning with letters K through Z, type K into the Greater than field.
  4. Click OK to generate the report.
Parent topic: Application Reports
Related concepts
Field/Screen Cross Reference Report


To run the Macro Cross Reference report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, without selecting a component, right-click; then select Report > Macro Cross Reference Report.
  2. On the Application list, click the application for which you want to generate this report.
  3. Click OK to generate the report.
Parent topic: Application Reports
Related concepts
Macro/Program Cross Reference Report
Related tasks
To view an application report


To run the Program DB/DC report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, without selecting a component, right-click; then select Report > Program DB/DC Report.
  2. From the Program list, click the program you want to report on.
  3. From the Schema list, click the schema you want to report on.
  4. From the Screen list, click a screen you want to report on.
  5. Click OK to generate the report.
Note: AMB automatically includes this report for all programs in an application when you run the Application Definition report.
Parent topic: Application Reports
Related concepts
Program DB/DC Report
Related tasks
To view an application report


To view an application report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder perspective, click Job Queue Listings Job Queue Listings.
  2. In the left pane, click a report. The report shows in the right pane.
Note: You can edit the report by double-clicking it. This brings the report up in the Eclipse editor.
Parent topic: Application Reports
Related tasks
To run an application report
To run the DDIFILE report
To run the Component List report
To run the Macro Cross Reference report
To run the Program DB/DC report


Code Generation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To create a configuration XML file
  • To delete jobs from the Batch Server
  • To generate an application, all programs, or all screens
  • To generate from the command line
  • To generate multiple-map mapsets for CICS applications
  • To generate a single program or screen
  • To start the AppMaster Builder console
  • To start and stop the Batch Server
  • To use the Job Queue
  • To view generated code
Parent topic: How to


To create a configuration XML file

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Using any text editor, create a file named ap_applicationname.xml in the cmdgnxml subdirectory of your AMB user area.
  2. Insert an XML header on the first line of the file.
  3. Code the <cmdgen> parent element.
  4. Using the Configuration XML File reference topics to guide you, complete the required code.
  5. Save the file and exit the text editor.
Parent topic: Code Generation
Related concepts
Generating from the Command Line
Related tasks
To generate from the command line
Related reference
Configuration XML File
cmdgen command


To delete jobs from the Batch Server

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the Batch Server, click the Select column field next to the job or jobs you want to delete.
  2. Click File > Delete and click Yes to confirm.
Note: You cannot delete the first job, because the Batch Server is processing it.
Parent topic: Code Generation


To generate an application, all programs, or all screens

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • From the AppMaster Builder Project Explorer, right-click the application; then click Generate > Generate Application, Generate All Programs, or Generate All Screens, depending on what you want to generate.
Note: Check the Job Queue to view generation results.
Parent topic: Code Generation
Related concepts
Generating from the IDE
Related tasks
To generate an application analysis
To generate a project analysis
To use the Job Queue


To generate from the command line

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Create a configuration XML file containing the information required for the application or object(s) you want to generate.
  2. At an Enterprise Developer command prompt, execute the cmdgen command using appropriate parameters to generate the object(s) or application required.
Parent topic: Code Generation
Related concepts
Generating from the Command Line
Related tasks
To create a configuration XML file
Related reference
Configuration XML File
cmdgen command


To generate multiple-map mapsets for CICS applications

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click a project; then select Generate Multiple Map Mapset.
  2. If the location in the Screen location field (default APPSSCRN project subdirectory) is not the location of the maps you want to include, select an alternative location from the drop-down list. (optional)
    Note: If you have assigned a workgroup in your AppMaster Builder preferences, all APSSCRN workgroup locations are available on the drop-down list.
  3. In the Mapset name field, type a name for the multiple-map mapset you want to generate.
  4. On the Available maps column, select from two to 20 maps to include.
  5. Click Select available maps to move the selected maps to the Selected maps column.
  6. Click Generate to generate the mapset.
  7. Repeat steps 2 through 6 for each multiple map mapset you want to generate.
  8. Click Close.
Note: To remove one or more maps from the Selected maps column, select the maps in the Selected maps column; then click Remove selected map(s).
Parent topic: Code Generation
Related concepts
Generating from the IDE
Related tasks
To set AppMaster Builder preferences


To generate a single program or screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • From the AppMaster Builder Project Explorer, right-click the program or screen you want to generate; then click Generate.
Parent topic: Code Generation
Related concepts
Generating from the IDE


To start the AppMaster Builder console

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: The AppMaster Builder console automatically starts when you start a generation process.
From the AppMaster Builder perspective:
  • Click the AppMaster Builder console icon AppMaster Builder console.
From the Team Developer perspective (technology preview) or the AppMaster Builder perspective:
  1. In Eclipse, click the Console tab.
  2. On the icon bar, click the down arrow associated with Display Selected Console Display Selected Console.
  3. Click AppMaster Builder.
Parent topic: Code Generation


To start and stop the Batch Server

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: The AppMaster Builder Batch Server automatically starts when you start Eclipse.
To start Batch Server from the command line:
  1. At a command prompt on the server system, change to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc (Windows) or $COBDIR/etc (UNIX) directory.
  2. Enter batserv.
From the AppMaster Builder perspective:
  • To toggle the batch server between Start and Stop, click the AppMaster Builder Server icon AppMaster Builder Server.
From the Team Developer perspective (technology preview):
  • Right-click the AppMasterBuilder local system; then select either Start Batch Server or Stop Batch Server from the context menu.
Note: For more information on the Batch Server, see The Batch Server.
Parent topic: Code Generation


To use the Job Queue

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Do one of the following to start the Job Queue view:
    • From the AppMaster Builder perspective, click the Job Queue icon Job Queue Listings.
    • From the Team Developer perspective (technology preview) or the AppMaster Builder perspective:
      1. Click Window > Show View > Other.
      2. On the Show View dialog box, expand AppMaster Builder.
      3. Select Job Queue; then click Open.
  2. Do one or more of the following:
    • To view the contents of a job log file, click the job Name in the left pane. The log file appears in the right pane.
    • To view a log file in the default text editor, double-click a job name.
    • To sort the jobs by a component of the job name, click the column heading that corresponds to the component you want to sort on.
    • To resize the columns, place your cursor between column headings and drag to the left or the right.
    • To refresh the list of jobs, click Refresh job queue listing Refresh job queue listing.
    • To print a single job log, right-click it in the left pane; then select Print.
    • To print multiple job logs, select them in the left pane; then click Print selected job(s) Print selected jobs.
    • To delete a single job log, right-click it in the left pane; then select Delete.
    • To delete multiple job logs, select them in the left pane; then click Delete selected job(s) Delete selected jobs.
    • To delete a all job logs, click anywhere in the left pane; then Delete all jobs Delete all jobs.
    • To change the job queue directory, type a new directory into the Job queue directory field, use the drop-down list to select a new directory, or click Browse to navigate to and select a directory.
    • To switch to the AppMaster Builder perspective, click AppMaster Builder AppMaster Builder perspective.
Tip:
  • You can assign colors to correspond to different output results and to different log file entries by customizing the Job Queue. See To set AppMaster Builder preferences and Customization - Job Queue tab for more information.
  • For an explanation of each field on the Job Queue perspective, see Job Queue.
Parent topic: Code Generation
Related concepts
Generating the Analysis
Job Queue Log Management
Related tasks
To set AppMaster Builder preferences
To generate an application, all programs, or all screens


To view generated code

  1. In Eclipse, open the AppMaster Builder perspective.
  2. Click Explore > User Area.
  3. Double-click testlib.
  4. Open any generated file using a text editor of your choice.
Note: If you have set your AppMaster Builder preferences to compile in a COBOL project, you can also view generated code from the COBOL Explorer.
Parent topic: Code Generation
Related tasks
To set AppMaster Builder preferences
Related reference
User Area Directories


Database Views

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: Tasks listed in this section can be performed when using the AppMaster Builder perspective only unless otherwise noted.
  • To create a new database view
  • To create new database source files
  • To delete a database target record from a database view
  • To delete a database view
  • To delete a source member from the input source directory
  • To edit database source files
  • To import OS400 physical file definitions
  • To load and build IMS into a database view
  • To load and build VSAM into a database view
  • To load and build SQL DDL source into a database view
  • To load and build a SQL schema into a database view
  • To edit a SQL Schema file
  • To maintain DDI files
  • To reference logical relationships
  • To set properties for a specific database view
Parent topic: How to


To create a new database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Database View Explorer of the AppMaster Builder perspective, right-click the Database View Files entry and select Add. The New Source dialog box appears. The current Source folder appears in the Source folder list. A default name for the new database view appears in the Name field.
  2. Type a meaningful name for the new database view in the Name field. Use these guidelines to help you choose an appropriate name:
    • IMS - Give the database view the same name as the PSB source file that contains the DBD names you want to load into the database view.
    • VSAM - Give the database view the same name as the name specified in the DDI SUB statement of the DDISRC file you want to load into this database view.
    • SQL DDL - If the SQL DDL source you intend to load and build into this database view contains a CREATE SUBSCHEMA statement, the name of the database view must be the same name as is specified in the CREATE SUBSCHEMA statement. If your SQL DDL does not contain a CREATE SUBSCHEMA statement, you can name the database view anything you choose.
    • SQL SUBSCHEMA - Choose a name that describes the collection of tables you want to reference in this database view. AppMaster Builder uses the name you assign here to generate a CREATE SUBSCHEMA statement for this database view.
  3. Click OK. The new database view appears in the Database View Explorer's list of database view files for the project.

Once you create a database view, you can create and edit it's data sources, and load those sources into the database file. You can also set properties for the database view. See To create new database source files and To set properties for a specific database view for more information.

Note:

You can also set properties for this database view from the Properties tab on the Data Views dialog box. Be sure to set the properties before you load the database view, and click Save/Build to save the settings for future sessions.

Default database view names are based on the folder where the database view is to be stored and a sequential number, which is incremented by one if the sequential number is saved to the database view name. For example, if adding two files and using the default names DSYM00 and DSYM01, the default name for the next database view in that location is DSYM02. If you change that database view name, the next database view also defaults to DSYM02.

Data view names can be a maximum eight characters.

Parent topic: Database Views
Related tasks
To create new database source files
To set properties for a specific database view


To create new database source files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Database View Explorer of the AppMaster Builder perspective, right-click the desired Source file type node (IMS Source Files, VSAM Source files, SQL Source files) and choose Add. The New Source dialog box appears. The current Source folder appears in the Source folder list. A default name for the new database view appears in the Name field.
  2. Type a meaningful name for the new source file in the Name field.
  3. Click OK. The new source file is added to the list of sources under the appropriate source file type node in the Database View Explorer.
  4. Find the new source file in the list and double-click the file.
  • If the new source file is a SQL schema file, The SQL Schema dialog box appears. Use this dialog box to associate SQL table definitions with a SQL schema file. Select or remove table definitions from the SQL schema as needed and click OK to save the changes. See the topic To edit a SQL Schema file for specific instructions.
  • For all other types of source files, double-click the file in the Database View Explorer to edit its contents in its own Editor window in the Eclipse IDE. Code the source in the Editor window as needed, then choose File > Save to save any changes before closing the Editor window.
Note:
  • See Coding DDI Sources for information on coding DDI statements for IMS and VSAM.
  • You can optionally create new sources outside of the AppMaster Builder environment. Save all new sources in their appropriate project directories.
  • Be sure to load and build your new source into a database view so that it becomes available to AppMaster Builder.
Parent topic: Database Views
Related concepts
Coding DDI Sources
Coding SQL DDL Sources
Coding SQL Schema Sources
Related tasks
To create a new database view
To edit a SQL Schema file
To edit database source files


To delete a database target record from a database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

If a desired database view contains multiple database target types (VSAM , SQL or IMS), you can delete one of the targets.

  1. In the Database View Explorer of the AppMaster Builder perspective, right-click on the target record you want to delete and choose Delete. A message box appears asking to confirm the deletion.
  2. Click OK to delete the target. The Database View automatically rebuilds after deleting a target.
Parent topic: Database Views


To delete a database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Database View Explorer of the AppMaster Builder perspective, right-click the database view you want to delete and click Delete. A message box asks you to confirm the deletion.
  2. Click Yes to confirm.
Parent topic: Database Views


To delete a source member from the input source directory

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Database View Explorer, right-click any database view source and select Delete. A message box appears asking you to confirm the deletion.
  2. Click Yes.
Parent topic: Database Views


To edit database source files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • On the Database View Explorer tab, do one of the following:
    • For IMS source, VSAM source, and SQL DDL, double-click the database source name in the Database View Explorer. Edit the source as necessary in the Editor window, then save and close the editor.
    • For a SQL schema, double-click the name in the Database View Explorer and use the SQL Schema dialog box to select or remove SQL table definitions, or edit the Copylib field as necessary and click OK to save any changes.
Note:
  • You can optionally edit sources directly from their project directories using the editor of your choice.
  • Each time you make a change to a source file that has already been built into a database view, you must reload the source and rebuild the database view to properly update it.
  • See To create new database source files and To edit a SQL Schema file for more information on how to edit database source files.
Parent topic: Database Views
Related concepts
Coding DDI Sources
Coding SQL DDL Sources
Coding SQL Schema Sources
Related tasks
To create new database source files


To import OS400 physical file definitions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the OS400 environment, type ddsextr on the command line and press PF4 to execute the DDS Extract utility. The DDSEXTR screen appears. Execute the utility once for each file you want to import.
  2. Complete the fields on the DDSEXTR window. Press F1 for help on an individual field.
  3. Transfer the extracted file to the PC into the project\OS4FILE directory.
Note:
  • Be sure that the name of the file you transfer is the same as the data view name with no extension.
  • Be sure the database targets assigned to the application reflect the OS4 target.
Parent topic: Database Views


To load and build IMS into a database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Copy your PSB sources to the PSBSRC directory of your project.
  2. Copy the DBD sources referenced in your PSB source to the DBDSRC directory of your project.
  3. Ensure that any IMS DDI source files you want to include in the database view are in the DDISRC directory of your project.
  4. In the Database View Explorer of the AppMaster Builder perspective, right-click to select the desired database view and choose Edit Database View. The Load Source for Database View dialog box appears with the Sources tab selected.
  5. Select the PSB Source radio button.
  6. From the list of sources, select the file that contains your PSB code and click Load. A message box indicates if the source has been loaded in to the database file. Click OK to clear the message box.
    Tip: AppMaster Builder automatically loads your PSB source, all of the DBD source referenced in your PSB source, and each DDI source member that has a filename that matches a DBD name referenced in your PSB.

    If you have also set your options and properties to automatically load IMS source into a COBOL project, your IMS source compiles into the specified COBOL project at this time.

  7. Click Save/Build. A message box appears when the database view has finished building.
  8. Click OK to return to the AppMaster Builder Desktop. Review the information in the Console to ensure that your IMS has loaded successfully.
Note:
  • If a database view with the same name as your PSB source member already exists, your IMS is built into that existing database view. Otherwise, AppMaster Builder creates a new database view with the same name as your PSB source member.
  • You can also load VSAM source into this database view if the SUB name specified in the VSAM matches the name of the PSB source file.
  • You can load a SQL schema into this same database view if the name of the subschema matches the name of the PSB source file.
  • You can load any SQL DDL source file into this database view if the source file does not contain a CREATE SUBSCHEMA statement.
  • For more information on coding DDI statements for IMS, see the DDI Statements - IMS DB.
Parent topic: Database Views
Related concepts
Loading IMS


To load and build VSAM into a database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Save all VSAM source files you create to the DDISRC directory of your project/view.
  2. In the Database View Explorer of the AppMaster Builder perspective, right-click to select the desired database view and choose Edit Database View. The Load Source for Database View dialog box appears with the Sources tab selected.
  3. Select the VSAM Source radio button.
  4. From the list of sources, select the file you want to load and build into this database view and click Load. A message box indicates when the source has been loaded in to the database file. Click OK to clear the message box.
  5. Repeat the previous step for any other VSAM files you want to load into the database view.
  6. Click Save/Build. A message box appears when the database view has finished building.
  7. Click OK to return to the AppMaster Builder Desktop. Review the information in the Logger window to ensure that your VSAM loaded successfully.
Note:
  • If a database view with the same name as your SUB name already exists, your VSAM is built into that existing database view. Otherwise, AppMaster Builder creates a new database view for your VSAM of the same name as its SUB name.
  • You can also load PSB sources into this same database view if the name of the PSB source file matches the SUB name found in your VSAM file.
  • You can load a SQL schema into this same database view if the name of the subschema matches the SUB name found in your VSAM file.
  • You can load any SQL DDL source file into this database view if the source file does not contain a CREATE SUBSCHEMA statement.
  • For more information on coding DDI statements for VSAM, see the topic DDI Statements - VSAM.
Parent topic: Database Views
Related concepts
Loading VSAM


To load and build SQL DDL source into a database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Copy your SQL DDL sources containing native SQL CREATE TABLE statements to the SQLDDL directory of your project.
  2. In the Database View Explorer of the AppMaster Builder perspective, right-click to select the desired database view and choose Edit Database View. The Load Source for Database View dialog box appears with the Sources tab selected.
  3. Select the SQL DDL Source radio button.
  4. Select a source location on the Source Folder list. This can be a source folder or mainframe location.
  5. From the list of sources, select a file you want to load and build into this database view and click Load. The file can be SQL DDL file, mainframe file, or workgroup file. A message box indicates if the source has been loaded in to the database file. Click OK to clear the message box.
  6. Click Save/Build. A message box appears when the database view has finished building.
  7. Click OK to return to the AppMaster Builder Desktop. Review the information in the Logger window to ensure that your SQL DDL loaded successfully.
Note:
  • You can change the default SQL target information for this session on the Properties tab for the Load/Build Data Views dialog box. The properties revert back to the default settings when you close the Load/Build Data Views dialog box.
  • A message box alerts you if the Subschema name in the CREATE statement does not match the database view name. If this happens, click OK to clear the message, then adjust the subschema name in the CREATE statement before reloading the source file.
  • You can load any SQL DDL source file into this database view if the source file does not contain a CREATE SUBSCHEMA statement. However, it is recommended to load SQL tables using a SQL schema instead of loading them directly from the SQL DDL.
Parent topic: Database Views
Related concepts
Loading SQL


To load and build a SQL schema into a database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Copy the SQL DDL sources that contain the tables you want to reference in your SQL schema to the SQLDDL directory of your project or group.
  2. In the Database View Explorer of the AppMaster Builder perspective, right-click to select the desired database view and choose Edit Database View. The Load Source for Database View dialog box appears with the Sources tab selected.
  3. Select the SQL Schema Source radio button.
  4. From the list of source members, select the SQL schema you want to load and build into this database view and click Load. A message box indicates when the source has been loaded in to the database file. Click OK to clear the message box.
  5. Click Save/Build. A message box appears when the database view has finished building.
  6. Click OK to return to the AppMaster Builder Desktop. Review the information in the Logger window to ensure that your SQL schema loaded successfully.
Note:
  • If a database view with the same name as your SQL SCHEMA already exists, your schema is built into that existing database view.
  • You can change the default SQL target information for this session on the Properties tab for the Load/Build Data Views dialog box. The properties revert back to the default settings when you close the Load/Build Data Views dialog box.
  • You can also load VSAM source into this database view if the SUB name specified in the VSAM matches the name of the database view.
  • You can load IMS into this same database view if the name of the PSB source matches the name of the database view.
Parent topic: Database Views
Related concepts
Loading SQL
Related tasks
To edit a SQL Schema file


To edit a SQL Schema file

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Do one of the following:
    • To modify an existing schema, right-click its name in the tree view list and select Edit.
    • To create a new schema, select Add and then specify a name for your new schema in the Name field, then click OK. Then double-click or select Edit. The SQL Schema dialog box appears, which lets you edit the new schema file. The locations for the SQL table definitions and the schemas display in the SQL Table location and Schema location fields.
  2. Click a table name listed on the SQL Table Definitions list, and choose the >>> button. This moves the table name to the Table Definitions in Schema File list. You can select more than one table at a time by holding down the Shift or Ctrl key as you click the table name.

    To provide a copybook name for a table, click the table name on the Table Definitions in Schema File list, then type the copybook filename into the Copylib field.

    Note: The table names listed on the Create SQL Schema dialog box are all of the tables defined in the SQL DDL files you have stored in the SQLDDL folder of your project or group.
  3. Repeat the previous step for each table for which you want to provide a copybook name.
    Tip: If you do not specify a copybook name for a table, AppMaster Builder generates a name for that table's copybook and for the record names contained in the copybook.
  4. When you have selected all of the table names you want to include in the schema and assigned copybook names as necessary, click OK.
Note: Use the <<< button to remove a table definition from a schema file.
Parent topic: Database Views
Related tasks
To load and build a SQL schema into a database view
To create new database source files


To maintain DDI files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder desktop in any View, click Admin > DDI File Utilities.
  2. Click any of the following from the context menu:
    • Unlock to unlock the DDI file, by removing any Create or Update locks placed in an entity. Unlock also deletes incomplete entitles created during DDI loading.
    • Backup to copy the DDIFILE, via a DOS COPY, to an OS sequential data set.
    • Restore to copy the backup data set, via a DOS COPY, to the DDIFILE.
    • Reorganize to convert the binary portion of the PC DDIFILE-KEY to the same binary storage format used on the mainframe. If you have DBDs, PSBs or VSAM sources that are large or need to be imported frequently, it may be necessary to run this utility (i.e., especially if you begin to get DDI-1024 errors).
  3. AppMaster Builder immediately executes the process.
Note: The Reorganize utility is for DDI files used on the PC only; it is not applicable for the z/OS DDIFILE. A copy of your unconverted DDIFILE is created and saved under the name DDIUNCNV in case execution errors occur during the Reorganization process.
Parent topic: Database Views


To reference logical relationships

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Code a DDI DBD statement.
  2. Code a DDI REC statement. Do not include information for segments in a logical DBD if the logical segment has a single physical source segment or the same IMS name as its physical source segment.
Note: The IMS Generator does not validate IMS logical Insert/Delete/Replace rules.
Parent topic: Database Views


To set properties for a specific database view

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Data View Manager of the AppMaster Builder perspective, right-click the Database View for which you want to set properties and select Edit Database View.... The Load Source for Database View dialog box appears.
  2. Click the Properties tab.
  3. Do one of the following:
    • To load IMS source into this database view, check Load DDISRC with IMS PSB override, then select the appropriate DDI source location in the DDISRC Location list.
    • To load SQL into this database view, set the SQL target from the Target list. Then select check boxes as needed to allow mixed case in your SQL table definitions, or generate a REDEFINES statement for any copybook field with a corresponding DATE, TIME, or TIMESTAMP SQL field. For Double-byte character sets used in DBCS PICTURE clauses, select the symbol to be used from the list (G, N, or N with NATIONAL USAGE).
  4. Click Save/Build. A message box appears indicating when the database view has finished building. Click OK.
Note:
  • If no records are in the database view, clicking Save/Build displays a message indicating no records have been loaded.
  • You can optionally choose to load a specific IMS DDISRC member when you load PSB source by checking Load DDISRC with IMS PSB override, then selecting the appropriate DDI source location in the DDISRC Location list.
  • For SQL, defaults apply if the user does not set any properties.
Parent topic: Database Views
Related concepts
Loading SQL
Related tasks
To create a new database view


Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To activate or deactivate Online Express comments
  • To assign actions to function fields
  • To assign actions to PF keys
  • To assign actions to screen events
  • To create Working-Storage fields in Online Express
  • To customize database calls in Online Express
  • To customize predefined actions in Online Express
  • To define a Savekey
  • To define a VSAM call in Online Express
  • To define an explicit Join specification
  • To define an IMS call in Online Express
  • To define an SQL call in Online Express
  • To define Savekey storage
  • To finalize a Union call in Online Express
  • To map screen fields in Online Express
  • To qualify VSAM multiple-key fields in Online Express
  • To specify an isolation level
  • To start Online Express
Parent topic: How to


To activate or deactivate Online Express comments

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Express Generation Options.
  2. Check or uncheck Control Point Comments.
Parent topic: Online Express


To assign actions to function fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Action/Event. The Action/Event Browser appears.
  2. On the Control list, click Function Field to assign an action to the primary function field, or Row Function Field to assign an action to a row function. The Action/Event Browser appears.
  3. In the Event field, type the value that you want the end user to enter into the function field to execute the action. Maximum characters 8.
  4. From the Action drop-down list, click the action you want to perform at the event.
  5. In the Argument field, type the appropriate argument for the event or click an argument from the drop-down list. See Actions for a list of actions and appropriate arguments.
  6. If your argument requires that you write new or modify existing code:
    • For Global Code, User Rule, or Perform, click Action/Event > Edit Misc User Code and type the code into your editor.
    • For Local Code, click Edit Code and type the code into your editor.
  7. Save the code and exit the editor.
Note: For information on coding Global Code, User Rules, Performs, or Local Code, see Types of Custom Code.
Parent topic: Online Express
Related concepts
Types of Custom Code
Actions
Related reference
Action/Event Browser
Action/Event Editor


To assign actions to PF keys

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Action/Event. The Action/Event Browser appears.
  2. On the Control list, click KEYS.
  3. On the Control Name list, double-click PF1 - PF12, PF13 - PF24, or Special Keys for the PA keys and the Clear key. The Action/Event Editor appears, showing the keys in the Event field.
  4. Click the event you want to assign actions to.
  5. From the Action drop-down list, click the action you want to perform at the event.
  6. In the Argument field, type the appropriate argument for the event or click an argument from the drop-down list. See Actions for a list of actions and appropriate arguments.
  7. In the Argument field, type the appropriate argument for the event or click an argument from the drop-down list. See Actions for a list of actions and appropriate arguments.
  8. If your argument requires that you write new or modify existing code:
    • For Global Code, User Rule, or Perform, click Action/Event > Edit Misc User Code and type the code into your editor.
    • For Local Code, click Edit Code and type the code into your editor.
  9. Save the code and exit the editor.
Note:
  • The Enter key on the keyboard is the default function processing key. It causes your program to test the action value that the end user enters, and executes the action. To override the Enter key as the default action processing key, on the Special Key window, click the overriding key name in the Processing Key field. The processing key causes your program to test the action value that the end user has entered, and then execute the action.
  • For information on coding Global Code, User Rules, Performs, or Local Code, see Types of Custom Code.
Parent topic: Online Express
Related concepts
Types of Custom Code
Actions
Related reference
Action/Event Browser
Action/Event Editor


To assign actions to screen events

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Action/Event. The Action/Event Browser appears.
  2. On the Control list, click Screens.
  3. On the Control Name list, double-click the screen name for which you want to assign actions. The Action/Event Editor appears.
  4. Click the event you want to assign actions to.
  5. From the Action drop-down list, click the action you want to perform at the event.
  6. In the Argument field, type the appropriate argument for the event or click an argument from the drop-down list. See Actions for a list of actions and appropriate arguments.
  7. If your argument requires that you write new or modify existing code:
    • For Global Code, User Rule, or Perform, click Action/Event > Edit Misc User Code and type the code into your editor.
    • For Local Code, click Edit Code and type the code into your editor.
  8. Save the code and exit the editor.
Note: For information on coding Global Code, User Rules, Performs, or Local Code, see Types of Custom Code.
Parent topic: Online Express
Related concepts
Events
Actions
Types of Custom Code
Related reference
Action/Event Browser
Action/Event Editor


To create Working-Storage fields in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From Online Express, click File > Field Mapping. The Field Mapping dialog box appears.
  2. Click Field Mapping > Add User Variable. The Create Working Storage dialog box appears.
  3. In the Name field, type the name of the Working-Storage field you want to create.
  4. If you want to qualify the field, type the name of the record to which the Working-Storage field belongs in the OF Qualification field.
  5. Click OK.
Note: These Working-Storage fields must be coded into your program as local code or global code in Online Express, or as part of a Program Painter program.
Parent topic: Online Express
Related concepts
Field Mapping
Related reference
Field Mapping
Create Working Storage Field


To customize database calls in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Database Access. The Database Access Summary window appears.
  2. Click the call you want to customize, and click Database Access > Call Tailoring. The Database Call Tailoring Browser appears.
  3. In the Database Action column, double-click a database action. The DB Call Tailoring Editor appears.
  4. Click the event you want to customize.
  5. From the Action drop-down list, click the action you want to perform.
  6. In the Argument field, type the appropriate argument for the event.
  7. Do one of the following:
    • For Global Code, User Rule, or Perform, click Action/Event > Edit Misc User Code and type the code into your editor.
    • For Local Code, click Edit Code and type the code into your editor.
  8. Save the code and exit the editor.
  9. If you want to override the default Error flag processing:
    1. In the Status Matrix group using the drop-down list provided for each flag, change a default status flag from Normal or Error to Exception.
    2. Follow steps 4 through 8 of this procedure for the Exeption Status event and code your own error routine.
    3. If you want to prevent the Error flag from aborting the program, uncheck Abort On Error.
  10. If you want to override the Online Express-generated error messages that show which type of call failed and which record caused the failure:
    1. In the Error Message field, either type a text message or a rule name.
    2. From the Error Message Type drop-down list, click either Text or Rule, depending on what you typed in the Error Message field.
  11. Click Apply to save your call customizations.
Note: Be sure when you specify Global Code or a User Rule that the code or the rule appears as an object on the Project Explorer in your Globals folder.
Parent topic: Online Express
Related concepts
Execute DB Calls at Events
Define the Call
Overriding Error Processing
Types of Custom Code
Actions
Related reference
Action/Event Browser
Action/Event Editor
Database Access Summary
Database Call Tailoring Browser
Database Call Tailoring Editor


To customize predefined actions in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Online Express Action/Event Browser, click a control type from the Control Type list, and double-click a name on the Control Name list. The Action/Event Editor appears.
  2. Click the event you want to customize.
  3. From the Action drop-down menu for the event you want to customize, click the action you want to perform.
  4. From the Action drop-down list, click the action you want to perform at the event.
  5. In the Argument field, type the appropriate argument for the event or click an argument from the drop-down list. See Actions for a list of actions and appropriate arguments.
  6. If your argument requires that you write new or modify existing code:
    • For Global Code, User Rule, or Perform, click Action/Event > Edit Misc User Code and type the code into your editor.
    • For Local Code, click Edit Code and type the code into your editor.
  7. Save the code and exit the editor.
Note: For information on Global Code, User Rules, Performs, or Local Code, see Types of Custom Code.
Parent topic: Online Express
Related concepts
Types of Custom Code
Actions
Related tasks
To create a User Rule
To update a User Rule
Related reference
Action/Event Browser
Action/Event Editor


To define a Savekey

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Use the Screen Painter to paint a Savekey field.
  2. In Online Express, click File > Savekey Specification. The Savekey Data dialog box appears.
  3. Specify which screen fields to use for storing savekey data as follows:

    If your screen displays...

    Select a screen field from...

    Only a single occurrence of data with the Update, Delete, or Next action

    Non Repeated Savekey

    Only a repeated record block with the Update, Delete, Forward, or Backward action

    Repeated Savekey

    Both of the above

    Either Non Repeated Savekey and Repeated Savekey or For All Savekeys

  4. Click OK.
Parent topic: Online Express
Related concepts
Painting Program Fields
Store on your Screen
Related tasks
To paint a Savekey field
Related reference
Savekey Data


To define a VSAM call in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Database Access. The Database Access Summary window appears.
  2. Click Edit > Create. The Attributes dialog box appears.
  3. From the Database Type drop-down list, click VSAM.
  4. If you want to change the call from a Query (default) to something else, click the Program Function drop-down list and click the program function you want to execute with the call.
  5. Click OK. The Record Selection dialog box appears, identifying all records defined in your database.
    Note: AppMaster Builder modifies your table names to tablename-REC, where tablename is the first eight characters of the original name.
  6. Check the boxes that identify the actions you want to perform on your data.
  7. Do one of the following:
    • If you want to qualify one or more fields, click Next. The Add/Delete Fields for Qualification dialog box appears.
      1. Check the fields you want to qualify.
      2. Click Next. The Qualification dialog box appears.
      3. Set the qualification parameters as you see fit.
      4. Click Finish.
    • If you do not want to qualify any fields, click Finish.
Parent topic: Online Express
Related concepts
Execute DB Calls at Events
Define the Call
Related tasks
To qualify VSAM multiple-key fields in Online Express
Related reference
Database Access Summary
Attributes
Add/Delete Fields for Qualification
Qualification
Record Selection


To define an explicit Join specification

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Follow the steps in the topic To define an SQL call in Online Express, and define a Join call.
  2. Click Database Access > Explicit Join Specification. The Explicit SQL Join Specification dialog box appears.
  3. Select a 1st Join Table from its drop-down list and a 2nd Join Table from its drop-down list.
  4. From the Join Type drop-down list, click the type of Join you want to create:
    Inner
    Combines each row of the 1st Join Table with every row of the 2nd Join Table keeping only the rows where the join condition is true.
    Left Outer
    Includes the rows from the 1st Join Table that were missing from the inner join.
    Right Outer
    Includes the rows from the 2nd Join Table that were missing from the inner join.
    Full Outer
    Includes rows from both tables that were missing from the inner join.
  5. To specify a join condition, click On Clause. The On Clause dialog box appears.
  6. Set up the ON clause using the drop-down lists available on this dialog box; then click Apply.
Parent topic: Online Express
Related concepts
Execute DB Calls at Events
Define the Call
Related tasks
To define an SQL call in Online Express
Related reference
Explicit Join Specification
On Clause


To define an IMS call in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Database Access. The Database Access Summary window appears.
  2. Click Edit > Create. The Attributes dialog box appears.
  3. From the Database Type drop-down list, click IMS.
  4. If you want to change the call from a Query (default) to something else, click the Program Function drop-down list and click the program function you want to execute with the call.
  5. Click OK. The Record Selection dialog box appears, identifying all records defined in your database.
    Note: AppMaster Builder modifies your record names to recordname-REC, where recordname is the first eight characters of the original name. Plus symbols (+) that prefix record names indicate parent/child relationships.
  6. Check the boxes that identify the actions you want to perform on your data.
  7. Do one of the following:
    • If you want to qualify one or more fields, click Next. The Add/Delete Fields for Qualification dialog box appears.
      1. Check the fields you want to qualify.
      2. Click Next. The Qualification dialog box appears.
      3. Set the qualification parameters as you see fit.
      4. Click Finish.
    • If you do not want to qualify any fields, click Finish.
Note: When you want to add a child record for a particular parent, perform two separate steps. First, obtain the correct positioning for the child record by obtaining the parent. Additionally, specify *ADD for the obtain action to indicate that this is a preliminary step for inserting a record. Second, store the child record. Do not try to obtain the parent record and store the child record in one database access.
Parent topic: Online Express
Related reference
Database Access Summary
Attributes
Add/Delete Fields for Qualification
Qualification
Record Selection


To define an SQL call in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Database Access. The Database Access Summary window appears.
  2. Click Edit > Create. The Attributes dialog box appears.
  3. From the Database Type drop-down list, click SQL for DB2 Option.
  4. If you want to change the call from a Query (default) to something else, click the Program Function drop-down list and click the program function you want to execute with the call. Program Functions are as follows:
    • Query - executes Obtain
    • Update - executes Modify
    • Add - executes Store
    • Delete - executes Erase
  5. If you want to specify a Subselect or Union query, click Details On and click the appropriate query type from the Query Type drop-down list. Query is the default.
  6. Click OK. The Record Selection dialog box appears, identifying all of the tables defined in your data view.
    Note: AppMaster Builder modifies your table names to tablename-REC, where tablename is the first eight characters of the original name.
  7. Check the boxes that identify the actions you want to perform on your data.
  8. Do one of the following:
    • If you have specified a Loop action and want to specify the order in which your loop calls group table rows for display:
      1. Click Next. The Add/Delete Fields for Order By dialog box appears.
      2. Check the fields you want to loop on.
      3. Click Next. The Order By dialog box appears.
      4. Specify the order in which your loop call groups table rows for display. This dialog box shows your table index column as the column on which to order your data. If your database definition contains multiple indexes, Online Express displays only the first index listed. If your call includes the Modify or Erase actions, the index must be unique.
      5. In the Loop Max field, type the maximum number of rows that the loop Obtains.
      6. In the Optimize For field, specify the number of rows stored in the buffer before sending data back to the program.
      7. Click Finish.
    • If you have not specified a Loop action and you want to select or delete table columns:
      1. Click Next. The Add/Delete Fields for Field Selection dialog box appears.
      2. Check the box that corresponds to each Field Name you want to select.
      3. Click Next. The Field Selection dialog box appears.
      4. From the Function drop-down list for each column, click the function you want to associate with each column.
      5. If you want to qualify one or more fields, click Next and check the boxes that correspond to the fields you want to qualify.
      6. Click Finish.
    • If you do not want to order your looping fields, select or delete table columns, or qualify fields, click Finish.
Note: If you specify a Union query type, see the Help topic To finalize a Union call in Online Express for information on completing the call.
Parent topic: Online Express
Related concepts
Execute DB Calls at Events
Define the Call
Related tasks
To define an explicit Join specification
To finalize a Union call in Online Express
Related reference
Database Access Summary
Attributes
Add/Delete Fields for Qualification
Qualification
Record Selection


To define Savekey storage

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, click File > Savekey Specification. The Savekey Data window appears, showing the number of bytes required for savekey storage.
  2. Do one of the following:
    • To store savekey data in the program Commarea:
      1. Check Use Commarea to Store Savekey.
      2. In the field to the right of the For All Savekeys field, type a size for the field. The default is 00009.
      3. Click OK. Online Express allocates a savekey storage area in Commarea, using the size specified next to the field, For All Savekeys.
    • To store savekey data in screen fields, specify which screen field or fields to use for storing savekey data as follows:
      • For a single occurrence of data only (for the Update, Delete, or Next actions), from the Non Repeated Savekey drop-down list, click a field in which to store savekey information.
      • For a repeated record block only (for the Update, Delete, Forward, or Backward actions), from the Repeated Row Savekey drop-down list, click a repeated record block.
      • For both a single occurrence of data in a repeated record block, from the For All Savekeys, click a field.

      In the field to the right of the drop-down list for the field you selected, type a size for the field.

Note:
  • Before you begin this procedure, be sure all actions and database calls are already defined.
  • Savekey fields on your screen should have Type=Protected and Length=number of bytes specified in the For All Savekeys field.
Parent topic: Online Express
Related concepts
Savekey Storage
Related reference
Savekey Data


To finalize a Union call in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Complete the steps in the Help topic To define an SQL call in Online Express, specifying a Union query type. You can also define a Join call within a Union call.
  2. To define the next SELECT clause, on the Database Access Summary window, click Database Access > Continue Union and repeat the steps in the topic To define an SQL call in Online Express.
  3. Repeat step 2 for each SELECT clause.
  4. To ensure that all columns match, click Database Access > Union Cross-Ref The Union Reference window appears, showing the column type and length attributes of each SELECT clause.
  5. Be sure that the corresponding columns of each statement are identical in type and length. Click Validate to compare the column type and length attributes for mismatches. Messages identifying the mismatches appear.
  6. Correct any column mismatches by modifying your column or record selections on the Field Selection or Record Selection dialog boxes.
  7. Click OK.
Note:
  • Ensure that the statement with the largest number of columns is the first statement in the list, because Online Express returns all column data to the host variables of the first SELECT clause. All other statements can be arranged in any order.
  • If the last column(s) in the first statement has no corresponding column(s) in the other statements, Online Express automatically pads the omitted column(s) with an appropriate value—either a blank character, a zero, DATE, TIME, or TIMESTAMP. For example, Online Express pads the third column of statement 2:
    Stmt 1 | Column 1 | Column 2 | Column 3
    Stmt 2 | Column 1 | Column 2
    Stmt 3 | Column 1 | Column 2 | Column 3
  • If any column in the first statement except the last one has no corresponding column in the remaining statements, pad the omitted column(s) on the Field Selection window. This rule applies, for example, to the second column of statement 2:
    Stmt 1 | Column 1 | Column 2 | Column 3
    Stmt 2 | Column 1 | Column 3
    Stmt 3 | Column 1 | Column 2 | Column 3
  • To pad any column, insert a line on the Field Selection window and enter an asterisk (*) into it. To do so, position your cursor on the desired row, click Edit > Create, and type an asterisk as the column name. Online Express pads the column with an appropriate value.
Parent topic: Online Express
Related tasks
To define an SQL call in Online Express
Related reference
Database Access Summary
Union Reference
Field Selection
Record Selection


To map screen fields in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From Online Express, click File > Field Mapping. The Field Mapping dialog box appears.
  2. To set the mapping direction, click Field Mappings > Mapping Direction and click One-way or Two-way. The default is Two-way.
  3. To create a mapping:
    1. Place the mouse pointer over a screen field on the Control list or a database or Working-Storage field on the Field list.
    2. Click and drag the mouse pointer from the field you selected in step a to the field you want to map to on the other list.
    3. Release the mouse to complete the mapping. A one-sided or double-sided arrow, depending on the mapping direction you selected, appears to represent the mapping.
Note:
  • When you have the mapping direction set to one-way, Online Express creates an output from the field where the mapping originates and an input to the field where the mapping terminates.
  • When you have the mapping direction set to two-way, Online Express creates an input/output for each field.
  • You can also modify or delete Working-Storage fields, and do a variety of other tasks from the Field Mapping dialog box.
Parent topic: Online Express
Related concepts
Field Mapping
Related reference
Field Mapping


To qualify VSAM multiple-key fields in Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In Online Express, define a VSAM call as outlined in the topic To define a VSAM call in Online Express, but do not qualify the call. Be sure you have an Obtain database action defined in the call.
  2. Return to the Database Access Summary window.
  3. On the Database Access Summary window, click the call, then click Database Access > Call Tailoring. The Database Call Tailoring Browser window appears.
  4. On the Database Actions list, double-click Obtain. The Database Call Tailoring Editor appears.
  5. In the Action field next to the Before DB Access event, click Local Code from the drop-down list, and click Edit Code. The Program Painter appears.
  6. Write local code to move elementary field values to group-level fields. Online Express automatically executes the local code at this event, before the call executes. For information on writing local code, see Local Program Code.
  7. Save the code when complete, and exit the Program Painter.
  8. Click Database Access > Qualification. The Qualification window appears.
  9. To qualify the key field, click = from the Operator drop-down list, and type the group-level qualification value field in the Value field.
Note: As an alternative to steps 5 and 6, at the Before DB Access event you can execute global code or invoke a User Rule. See Global Program Code and User-Defined Rules for more information.
Parent topic: Online Express
Related concepts
Qualifying VSAM Multiple-Field Keys
Related tasks
To specify an isolation level
To define a VSAM call in Online Express
Related reference
Database Access Summary
Database Call Tailoring Browser
Database Call Tailoring Editor
Related information
Local Program Code
Global Program Code
User-Defined Rules


To specify an isolation level

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the Database Access Summary window, click the call for which you want to define an isolation level.
  2. Click Database Access > Record Selection. The Record Selection dialog box appears.
  3. From the Isolation Level drop-down list, click one of the following:
    • CS - with cursor stability
    • RS - with read stability
    • RR - with repeatable read capability
    • UR - with an uncommited read capability
  4. Click Apply.
Parent topic: Online Express
Related tasks
To qualify VSAM multiple-key fields in Online Express
Related reference
Record Selection
Database Access Summary
Related information
Local Program Code
Global Program Code
User-Defined Rules


To start Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • From the AppMaster Builder Project Explorer, double-click an Online Express Program entry.
Note: The Online Express program icon, Online Express Icon, appears on the Project Explorer next to each Online Express program.
Parent topic: Online Express
Related concepts
Online Express


Preferences and Properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To set AppMaster Builder preferences
  • To set application properties
  • To set program properties
  • To set screen, data structure, and user rule properties
Parent topic: How to


To set AppMaster Builder preferences

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Do one of the following:
    • From the AppMaster Builder perspective, click the AppMaster Builder Preferences page icon [image].
    • From the Team Developer perspective (technology preview) or the AppMaster Builder perspective, click Window > Preferences; then expand Micro Focus and select AppMaster Builder.
  2. Set preferences as required on the AppMaster Builder page; then click Apply.
  3. On the tree view, expand AppMaster Builder.
  4. Click any of the items listed under AppMaster Builder to see its preferences page. You might need to expand some of these items to see all available pages.
  5. After setting the preferences for a specific page, click Apply before moving on to another page. For a description of each field and control on these pages, click the appropriate Related reference topic below.
  6. When you have finished setting your preferences, click OK.
Parent topic: Preferences and Properties
Related concepts
Scenario for Using AppMaster Builder
AppMaster Builder User Areas
Related reference
AppMaster Builder
Environment
Customization
Tooltip - Text
Job Queue
Editors - Program Painter - Colorization
International
Output
Workgroup dialog box


To set application properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click an application object; then click Properties.
  2. Set the properties as required on the Resource page; then click OK.
Note: For information on specific fields and controls, see Application - Resource.
Parent topic: Preferences and Properties
Related concepts
Object Types
Related tasks
To create an application
To create a Program Painter program
Related reference
Application - Resource


To set program properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder Project Explorer, right-click a program object; then click Properties.
  2. Set the properties as required on the Resource page; then click OK.
Note: For information on specific fields and controls, see Program - Reource.
Parent topic: Preferences and Properties
Related concepts
Object Types
Related reference
Program - Resource


To set screen, data structure, and user rule properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder Project Explorer, right-click a screen, data structure, user rule, or report object; then click Properties.
  2. Set the properties as required; then click OK.
Note:
  • Property settings vary depending on the selected object. For information on specific fields and controls, see Screen - General, Data Structure - General, and User Rule - General.
  • From the Project Explorer, you can view Report and Data View object properties in the same manner, but you cannot change any settings.
Parent topic: Preferences and Properties
Related concepts
Object Types
Related reference
Screen - General
Data Structure - General
User Rule - General


Program Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To begin the Procedure Division for batch programs
  • To begin the Procedure Division for online programs
  • To code an Environment Division Special-Names statement
  • To code Identification Division comments in the Program Painter
  • To code Linkage Section structures
  • To code Procedure Division comments
  • To code the Procedure Division
  • To code Working-Storage structures
  • To create a User Rule
  • To customize the Program Painter
  • To define a DB2 table declaration and cursor declarations
  • To define a Declaratives section
  • To define data structures in COBOL format
  • To define data structures in Data Editor format
  • To define or redefine the Commarea
  • To define the Input-Output Section
  • To include a copyfile
  • To include a global or local data structure
  • To specify a report mock-up
  • To specify multiple reports
  • To start the Program Painter
  • To update a User Rule
Parent topic: How to


To begin the Procedure Division for batch programs

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Depending on the type of batch program you are coding, in the Program Painter, type NTRY or PROC in columns 4 through 7 as follows:

    Program Type

    Keyword

    Calling or non-calling

    NTRY or PROC. Both keywords generate a PROCEDURE DIVISION statement.

    Called

    PROC with optional USING clause. PROC generates a PROCEDURE DIVISION USING statement; the program receives data items from a calling program CALL statement.

  2. Type its arguments, such as the linkage record, in column 12. For example:
       PROC    USING LINKAGE-RECORD
    Generated AMB Source:
    PROCEDURE DIVISION USING LINKAGE-RECORD.
Parent topic: Program Painter
Related reference
NTRY
PROC


To begin the Procedure Division for online programs

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Type NTRY keyword in columns 4 through 7
  2. Type its arguments, such as the program screen, in column 12. NTRY generates logic to initialize your program when invoked, and to send the screen to the monitor. For example:
       NTRY    PSINQY
    Generated AMB Source:
    003700 $TP-ENTRY ("PSINQY", "")
003710     IF TP-TRANSID-INVOKED
003720         PERFORM APS-TRANSID-INV-PARA
003730     ELSE-IF TP-PROGRAM-INVOKED
003740         PERFORM APS-PROGRAM-INV-PARA
003750     ELSE-IF TP-SCREEN-INVOKED
003760         PERFORM APS-SCREEN-INV-PARA
003770     $TP-SEND ( "PSINQY", "")
003780
003790 APS-TRANSID-INV-PARA.
003800     % IF &TP-USER-LEN > 0
003810         MOVE LOW-VALUES TO TP-USERAREA
003820     $SC-CLEAR ( "PSINQY")
003830     EJECT
003840 APS-PROGRAM-INV-PARA.
003850     $SC-CLEAR ( "PSINQY")
003860     EJECT
003870 APS-SCREEN-INV-PARA.
003880     PERFORM APS-USER-CODE-PARA
003890     EJECT
003900 APS-USER-CODE-PARA.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
NTRY


To code an Environment Division Special-Names statement

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, type the SPNM keyword in columns 4 through 7.
  2. Type the statement starting in column 12, on the same line.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
SPNM


To code Identification Division comments in the Program Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Depending on the version of COBOL you are using, in the Program Painter, do one of the following:
    • If you are using OS/VS COBOL, type REM in columns 4 through 6
    • If you are using any other version of COBOL, type /* in columns 4 and 5
  2. Type your comments text starting in column 12, on the same line.
  3. Continue on as many lines as you need.

For example:

When coding for OS/VS COBOL:

   REM      comment text
            continues onto the next line.

When coding for all other versions of COBOL:

   /*       comment text
            continues onto the next line.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
/* (Comments)
REM


To code Linkage Section structures

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, mark the beginning of your Linkage Section entries by typing the LK keyword in columns 4 and 5.
  2. Skip a line and type your Linkage Section structures in the same manner that you type in your Working-Storage structures, beginning in column 12.
Note: To include a copybook in the Linkage Section, substitute the SYWS keyword with the SYLK keyword.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
LK


To code Procedure Division comments

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Use the following format to code comments into the Procedure Division:

   /*      comment text
           source code /* comment text
Note: You can also enter comments at the end of a line of source code.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
/* (Comments)


To code the Procedure Division

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Type your Procedure Division source code beginning on the line after the NTRY keyword. Procedure Division source code can include the following:
    • COBOL or S-COBOL statements, paragraphs, or global code
    • AMB database and data communication calls
    • Customizer rule calls and other statements
  2. To code a paragraph, type PARA in columns 4 through 7, the paragraph name in column 12 on the same line, and associated paragraph statements on the following lines.
  3. To include a program stub in the program, type STUB in columns 4 through 7 and the stub name in column 12 on the same line.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
NTRY
PARA
STUB


To code Working-Storage structures

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, mark the beginning of your Working-Storage entries by typing WS in columns 4 and 5.
  2. Skip a line to begin entering your Working-Storage structures, such as data structures, copyfile specifications, and DB2 table and cursor declarations.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
WS


To create a User Rule

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click either the Globals folder to create a global User Rule, or a program to create a local User Rule.
  2. In the Name field, type a name for the User Rule.
  3. From the Location drop-down list, select a program location where you want the User Rule to be inserted.
  4. Click OK. This returns you to the Project Explorer.
  5. From the Project Explorer, double-click the new User Rule entry.
  6. In the Program Painter, type the code for the User Rule. You can use COBOL or S-COBOL.
  7. Save your code and exit the editor. AppMaster Builder saves the User Rule in the USERMACS project subdirectory.
Note: You can also create a User Rule in Online Express.
Parent topic: Program Painter
Parent topic: Projects
Related concepts
User-Defined Rules
Coding Programs
Defining Customizer User Rules
Related tasks
To customize predefined actions in Online Express
Related reference
Program Painter Keywords
S-COBOL Structures
SY*


To customize the Program Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
From the Editors page
On the Editors preferences page, you can set background and foreground colorization options for all of the AMB painters, and turn on basic color mode. You can also change the cursor style to a cross-hair cursor, and set a color and size for it.
  1. From the AppMaster Builder perspective, click AppMaster Builder preferences page [image].
  2. In the left pane, click Editors.
  3. Set options as desired; then click OK.

    For complete details on each field and control on this page, see the Editors user interface reference topic.

    Note: If you prefer to view code using a single background and a single foreground color, set these colors using the controls in the Basic color mode group. When specified, basic color mode overrides colorization settings specified on the Editors - Program Painter - Colorization page.
From the Editors - Program Painter page
On the Editors - Program Painter preferences page, you can set options that dictate how code is entered into the painter.
  1. From the AppMaster Builder perspective, click AppMaster Builder preferences page [image].
  2. In the left pane, expand Editors; then click Program Painter.
  3. Set options as desired; then click OK.

    For complete details on each field and control on this page, see the Editors - Program Painter user interface reference topic.

From the Editors - Program Painter - Colorization page
On the Editors - Program Painter - Colorization page, you set colorization options for specific code structures.
Note: If you prefer to override the color scheme defined here and instead edit code using a single background and a single foreground color, set these colors on the Editors preferences page using the controls in the Basic color mode group.
  1. From the AppMaster Builder perspective, click AppMaster Builder preferences page [image].
  2. In the left pane, expand Editors > Program Painter; then click Colorization.
  3. Check Enable colorization.
  4. To change the color for a structure:
    1. Select a structure on the Appearance color options list.
    2. Double-click the Color field.
    3. Select a color; then click OK.
  5. To define a custom color:
    1. On the Color dialog box, click Define Custom Colors.
    2. To define a color, either use the cross hairs and slider, or type a value into each field.
    3. Click Add to Custom Colors.
  6. When all colors are set as desired, click OK.

    For complete details on each field and control on this page and its associated dialog boxes, see the Editors - Program Painter - Colorization and Color dialog box user interface reference topics.

From the Editors - Program Painter - Content Assistant page
On the Editors - Program Painter - Content Assistant preferences page, you can set options to enable the content assistant and customize how it works.
  1. From the AppMaster Builder perspective, click AppMaster Builder preferences page [image].
  2. In the left pane, expand Editors > Program Painter; then click Content Assistant.
  3. Set options as desired; then click OK.

    For complete details on each field and control on this page, see the Editors - Program Painter - Content Assistant user interface reference topic.

From within the Program Painter
While you are running the Program Painter, you can toggle the cross-hair cursor on and off, and customize its size and color.
  1. To toggle the cross-hair cursor on or off, press Alt + + (on the numeric keypad) or Alt + +/= (on the character keyboard).
  2. While toggled on, use the following short-cut key combinations to change the size and/or color of your cross-hair cursor:
    Alt + 1 through Alt + 9 | Sets the line thickness from 1 to 9 pixels.
    Alt + 0 (zero) | Changes the color of the cursor. Each time you press this combination, the color changes and continues to change with entered each key-stroke combination until all defined colors have been displayed; then the sequence begins again.
Parent topic: Program Painter
Related reference
Editors
Editors - Program Painter
Editors - Program Painter - Colorization
Editors - Program Painter - Content Assistant
Color dialog box


To define a DB2 table declaration and cursor declarations

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Type SQL in columns 4 through 6.
  2. Type the declaration(s) starting in column 12. For example:
       SQL     DECLARE DSN8.TDEPT TABLE
           ... (DEPTNO CHAR(3) NOT NULL,
           ... DEPTNAME CHAR(36) NOT NULL,
           ... MGRNO CHAR(3) NOT NULL,
           ... ADMRDEPT CHAR(3) NOT NULL)
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
SQL


To define a Declaratives section

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To define a Declaratives Section, choose one of the following methods:

  • Type DPAR in columns 4 through 7. Do not enter the DECLARATIVES header; AMB generates it. AMB also generates the END DECLARATIVES statement at the appearance of another keyword in columns 4 through 7; be sure that a keyword appears at the end of your Declaratives Section. For example:
       DPAR    section-1-name SECTION declarative-sentence
   DPAR    para-1-name
           /* para-1-name source code
           .
           .
           .
   DPAR    section-2-name SECTION declarative-sentence
   DPAR    para-2-name
           /* para-2-name source code
           .
           .
           .
    Generated AMB source:
     DECLARATIVES.
 section-1-name SECTION. declarative-sentence
 para-1-name.
 /* para-1-name source code
      .
      .
 section-2-name SECTION. declarative-sentence
 para-2-name.
 /* para-2-name source code
      .
      .
 END DECLARATIVES.
  • To specify Declaratives Section statements only, not sections or paragraphs, type DECL in columns 4 through 7. For example:
       DECL    declarative-statement
           declarative-statement
    Generated AMB source:
     DECLARATIVES.
 declarative-statement
 declarative-statement
 END DECLARATIVES.
Parent topic: Program Painter
Related reference
DECL
DPAR


To define data structures in COBOL format

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, type 01 in columns 4 and 5.
  2. Type your 01-level data item starting in column 12.
  3. To define elementary data items, skip a line and type them starting in column 12, as shown below. We recommend that you indent each new level of elementary data items four columns. For example:
       01      WS-STRUCT-IN-COBOL-FORMAT.
           05  MY-WS-FIELD-1                   PIC X(8).
           05  MY-WS-FIELD-2.
               10  MY-WS-FIELD-3               PIC X(8).
               10  MY-WS-FIELD-4               PIC X(3).
    Generated AMB source:
          01  WS-STRUCT-IN-COBOL-FORMAT.
          05  MY-WS-FIELD-1                   PIC X(8).
          05  MY-WS-FIELD-2.
              10  MY-WS-FIELD-3               PIC X(8).
              10  MY-WS-FIELD-4               PIC X(3).
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
01


To define data structures in Data Editor format

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, type REC in columns 4 through 6.
  2. Type your 01-level data item starting in column 12.
  3. To define elementary data items, skip a line and type them starting in column 16, as shown below. Do not enter the data item level numbers, such as 01 or 05; AMB generates them based on how you indent the items. We recommend that you indent each new level of elementary data items four columns. For example:
       REC      WS-STRUCT-IN-DSPAINTER-FORMAT.
              MY-WS-FIELD-1                   X8
              MY-WS-FIELD-2
                  MY-WS-FIELD-3               X8
                  MY-WS-FIELD-3               X3
    Generated AMB source:
           01  WS-STRUCT-IN-DSPAINTER-FORMAT.
           05  MY-WS-FIELD-1                   PIC X(8).
           05  MY-WS-FIELD-2.
               10  MY-WS-FIELD-3               PIC X(8).
               10  MY-WS-FIELD-4               PIC X(3).
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
REC


To define or redefine the Commarea

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Accept or override the default length (80 bytes) of the Commarea field and optionally redefine it into multiple fields. For main programs, do this in Working-Storage; for sub programs, do this in the Linkage Section.

  • To assign a length to TP-USERAREA, type the variable value assignment statement, &TP-USER-LEN, in column 12, and the keyword SYM1 in the columns 4 through 7. SYM1 places the variable at the top of your program. For example:
       SYM1    &TP-USER-LEN = 49
    Generated AMB source:
    01  TP-COMMAREA.
         .
         .
    05  TP-USERAREA            PIC X(49).
  • To redefine TP-USERAREA, type a redefinition data structure directly into the program, or put it into a data structure object and include it in the program. Use any of the following keyword/source code combinations:
    • CA05 - Define a COBOL redefinition data structure in the program. For example:
         SYM1    &TP-USER-LEN = 49
    .
    .
   CA05    CA-REDEF.
           10  CA-EMPLOYEE-NAME     PIC X(20).
           10  CA-EMPLOYEE-TITLE    PIC X(20).
           10  CA-EMPLOYEE-SSN      PIC X(09).
      Generated AMB source:
       01  TP-COMMAREA.
          .
          .
          .
 01  CA-REDEF REDEFINES TP-COMMAREA.
     05  FILLER                        PIC X(40).
     05  TP-USERAREA                   PIC X(49).
     05  CA-REDEF      REDEFINES TP-USERAREA.
         10  CA-EMPLOYEE-NAME         PIC X(20).
         10  CA-EMPLOYEE-TITLE        PIC X(20).
         10  CA-EMPLOYEE-SSN          PIC X(09).
    • CADS - Define a redefinition data structure object and include it in the program with the CADS keyword. For example:
         CADS    PGM-USERAREA

      The generated AMB source is identical to the source generated by the CA05 keyword in the example above.

    • CA - Using the Data Structure Editor format, define a redefinition data structure in the Program Painter. For example:
         SYM1    &TP-USER-LEN = 49
    .
    .
    .
   CA      PGM-USERAREA
               10  CA-EMPLOYEE-NAME     X20
               10  CA-EMPLOYEE-TITLE    X20
               10  CA-EMPLOYEE-SSN      X09

      The generated AMB source is identical to the source generated by the CA05 keyword in the example above.

      Generated AMB source:
       01  TP-COMMAREA.
          .
          .
          .
 01  FILLER REDEFINES TP-COMMAREA.
     05  TP-USERAREA                  PIC X(49).
     05  PGM-USERAREA    REDEFINES TP-USERAREA.
         10  CA-EMPLOYEE-NAME         PIC X(20).
         10  CA-EMPLOYEE-TITLE        PIC X(20).
         10  CA-EMPLOYEE-SSN          PIC X(09).
      Using the CA keyword:
         SYM1    &TP-USER-LEN = 49
    .
    .
    .
   CA      PGM-USERAREA
               10  CA-EMPLOYEE-NAME     X20
               10  CA-EMPLOYEE-TITLE    X20
               10  CA-EMPLOYEE-SSN      X09

      The generated AMB source is identical to the source generated by the CA05 keyword in the example above.

      Using the CADS keyword:
         CADS    PGM-USERAREA
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
CA, CA05, and CADS


To define the Input-Output Section

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, for each input and output file, type IO in columns 4 and 5.
  2. Type paragraph clauses starting in column 12. Do not code the word SELECT in the SELECT clause; AMB generates it for you.
  3. Continue on as many lines as you need. AMB generates the Input-Output Section and File-Control headers. For example:
       IO      INPUT-CUSTFILE
           ASSIGN TO EXTERNAL GARYDD
           ORGANIZATION IS LINE SEQUENTIAL
   IO      OUTPUT-FILE
           ASSIGN TO EXTERNAL GARYOUT
           ORGANIZATION IS LINE SEQUENTIAL
    Generated AMB Source:
     INPUT-OUTPUT SECTION.
 FILE-CONTROL.
     SELECT INPUT-CUSTFILE
     ASSIGN TO EXTERNAL GARYDD
     ORGANIZATION IS LINE SEQUENTIAL.
     SELECT OUTPUT-FILE
     ASSIGN TO EXTERNAL GARYOUT
     ORGANIZATION IS LINE SEQUENTIAL.
  4. Define the file description of your first (or only) input file in the File Section, by typing FD in columns 4 and 5, and a COBOL file description starting in column 12. For example:
       FD      INPUT-CUSTFILE
           RECORD CONTAINS 80 CHARACTERS.
  5. Next, define the input file record description using one of the following formats:
    • COBOL format - Type 01 columns 4 and 5), and the 01-level data item starting in column 12. To define elementary data items, skip a line and enter them starting in column 12, as shown below. We recommend that you indent each new level of elementary data items four columns. For example:
         01      INPUT-REC.
           05  INP-ACTION-CODE     PIC X(1).
           05  INP-CUSTOMER-NO     PIC X(6).
           05  INP-CUSTOMER-NAME   PIC X(20).
           05  INP-CUSTOMER-ADDR   PIC X(20).
           05  INP-CUSTOMER-CITY   PIC X(20).
           05  INP-CUSTOMER-ZIP    PIC X(9).
           05  FILLER              PIC X(4).
    • Data Structure Editor format -Type REC in columns 4 through 6, and the 01-level data item starting in column 12. To define elementary data items, skip a line and enter them starting in column 16, as shown below. Do not enter the data item level numbers, such as 01 or 05; AMB generates them based on how you indent the items. We recommend that you indent each new level of elementary data items four columns. For example:
         REC     INPUT-REC
               INP-ACTION-CODE     X1
               INP-CUSTOMER-NO     X6
               INP-CUSTOMER-NAME   X20
               INP-CUSTOMER-ADDR   X20
               INP-CUSTOMER-CITY   X20
               INP-CUSTOMER-ZIP    X9
               FILLER              X4
      Generated AMB source:
       01  INPUT-REC.
     05  INP-ACTION-CODE     PIC X(1).
     05  INP-CUSTOMER-NO     PIC X(6).
     05  INP-CUSTOMER-NAME   PIC X(20).
     05  INP-CUSTOMER-ADDR   PIC X(20).
     05  INP-CUSTOMER-CITY   PIC X(20).
     05  INP-CUSTOMER-ZIP    PIC X(9).
     05  FILLER              PIC X(4).
    • Include a data structure - If you created the record description in a data structure object, include the data structure in your program. Type DS in columns 4 and 5, and the data structure file name in column 12. For example:
         DS      INREC
  6. Define additional input files in the File Section in the same manner that you defined the first one.
  7. Define the file description of your first (or only) output file in the File Section. Type FD in columns 4 and 5, and a COBOL file description starting in column 12. For example:
       FD      OUTPUT-FILE
           RECORD CONTAINS 80 CHARACTERS.
  8. Define the output file record descriptions as in steps 5 and 6. For example, the following is sample generated AMB souce code:
    01      OUTPUT-REC.
         05  OUTPUT-STATUS           PIC X(2).
         05  OUTPUT-CUSTOMER-NO      PIC X(6).
         05  OUTPUT-CUSTOMER-NAME    PIC X(20).
         05  OUTPUT-CUSTOMER-ADDR    PIC X(20).
         05  OUTPUT-CUSTOMER-CITY    PIC X(20).
         05  OUTPUT-CUSTOMER-ZIP     PIC X(9).
         05  OUTPUT-FILLER           PIC X(3).
  9. To define a sort file description in the File Section, type SD in columns 4 and 5, and the file description starting in column 12. For example:
       SD      SORT-FILE
           RECORD CONTAINS 80 CHARACTERS
           DATA RECORD IS SORT-RECORD.
  10. Define the sort file record description as in steps 5 and 6. For example, the following is sample generated AMB souce code:
    01      SORT-RECORD.
         05  SORT-CUSTOMER-NAME      PIC X(8).
         05  FILLER                  PIC X(72).
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
IO
01
REC
FD
DS
SD


To include a copyfile

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Choose one of the following methods:

  • If you use an OS/VS COBOL compiler, and your copyfile does not contain an indexed table, do one of the following:
    • Type 01 in columns 4 and 5, and a COBOL COPY statement in column 12. For example:
         01       COPY MY-COPYBOOK
    • Copy the copyfile into a Working-Storage field, as follows:
         01       WS-COPYBOOK-FLD COPY MY-COPYBOOK
  • If you use any other COBOL compiler, or if your copyfile contains an indexed table:
    1. Type SYWS columns 4 through 7.
    2. Type % INCLUDE in column 12. For example:
         SYWS     % INCLUDE COPYLIB (MY-COPYBOOK)
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
01


To include a global or local data structure

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Type DS in columns 4 and 5.
  2. Type the data structure name in column 12. For example:
       DS      DATARECS
Note: The data structure name you specify must be either a child to the program that includes it or in the Globals folder for your application.
Parent topic: Program Painter
Related concepts
Coding Programs
Defining Customizer User Rules
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
DS


To specify a report mock-up

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, type MOCK in columns 4 through 7.
  2. Type the mock-up name starting in column 12 of the same line, as follows:
   MOCK    reportmockupname

Where reportmockupname is a mock-up you created from the AppMaster Builder Project Explorer and painted in the Report Painter.

For example:

   MOCK    STOCKRPT
Parent topic: Program Painter
Parent topic: Report Painter
Related concepts
Define Report Logic
Related reference
MOCK


To specify multiple reports

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, specify multiple reports using the REPORTS ARE clause in the FD statement.
  2. For each report specified, follow the steps presented in To code Working-Storage entries for reports and To code report logic.
Parent topic: Program Painter
Parent topic: Report Painter
Related concepts
Code Report Logic
Related tasks
To code Working-Storage entries for reports
To code report logic
Related reference
FD


To start the Program Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • From the AppMaster Builder Project Explorer, double-click a Program Painter Program, Batch, or Stub object.
Parent topic: Program Painter
Related concepts
Program Painter
Creating Report Programs


To update a User Rule

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To change the location where the User Rule is inserted:

  1. From the AppMaster Builder Project Explorer, right-click a User Rule object; then click Properties.
  2. From the Location drop-down list, select a new program location where you want the User Rule to be inserted.
  3. Click OK. This returns you to the Project Explorer.

To edit User Rule code:

  1. From the Project Explorer, double-click a User Rule object.
  2. In the Program Painter, update the code as required. You can use COBOL or S-COBOL.
  3. Save your code and exit the Program Painter.
Note: You can also update User Rule code in Online Express.
Parent topic: Program Painter
Parent topic: Projects
Related concepts
User-Defined Rules
Coding Programs
Defining Customizer User Rules
Related tasks
To customize predefined actions in Online Express
Related reference
Program Painter Keywords
S-COBOL Structures
SY*
Program - Resource


Projects

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To add an existing object to an application
  • To change projects
  • To copy an object
  • To create a data structure
  • To create a Program Painter program
  • To create a program stub
  • To create a User Rule
  • To create an AMB project
  • To create an application
  • To create an Online Express program
  • To filter programs
  • To remove or delete an object
  • To rename an object
  • To reorder objects under a parent program
  • To set debug options for an application
  • To sort programs in the Project Explorer
  • To specify a workgroup
  • To update a data structure
  • To update a User Rule
  • To view project files
Parent topic: How to


To add an existing object to an application

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click an object listed on the application or program/GLOBALS level; then click Add > objectName.
    Where objectName can be any of the following, depending on its parent object:
    • Program
    • Online Express
    • Batch
    • Stub
    • Data Structure
    • Data View
    • User Rule
    • Screen
    • Report
    Note: The Source folder field shows the default folder for the object type you have selected, and the existing objects for that type show on the list.
  2. To populate the Name field, select an existing object from the list.
  3. Complete any other fields and controls as required; then click OK.
Note: When you are performing any kind of update action, such as adding a screen or program, and another user has modified the same application during your session, AMB displays a warning and refreshes the view. You might need to perform the same procedure again so AMB can properly save the object to the project.
Parent topic: Projects
Related concepts
Object Types
Project Explorer Tree View


To change projects

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder perspective, click AppMaster Builder Preferences page [image].
  2. Do one of the following to change the information in the Project path field:
    • Select an alternative project path from the drop-down list.
    • Click Browse to select an alternative project.
    • Type the full path to the project directory.
  3. Click OK.
Note: If the project you select does not contain all of the information AMB attempts to load, a warning message appears. In this case, current values are retained with exception that the database directory changes to the selected project.
Parent topic: Projects
Related concepts
AppMaster Builder Preferences
Related tasks
To create an AMB project


To copy an object

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: You cannot copy an object of one type to a new object of another type. The object types must match.
  1. From the AppMaster Builder Project Explorer, right-click an object; then select Copy + Add from the context menu.

    When the Copy + Add Object dialog box appears, the object you selected on the Project Explorer populates the New Name field, and is selected automatically on the list below the field.

  2. Type a name for the new object into the New Name field.
  3. Click OK to copy and add the object.
  4. Optionally select another object from the list; then repeat steps 2 and 3 to add another object.
  5. When you are done adding objects, click Exit.
Note: You can filter the list of objects using the Filter field, and set the Copy + Add Object dialog box to automatically load changed filters. See the Copy + Add Object user interface reference topic for details.
Parent topic: Projects
Related concepts
Project Explorer Tree View
Related reference
Copy + Add Object


To create a data structure

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click either the Globals folder to create a global data structure, or a program to create a local data structure.
  2. In the Name field, type a name for the data structure.
  3. From the Location drop-down list, select a program location where you want the data structure to be inserted.
  4. Click OK. This returns you to the Project Explorer.
  5. From the Project Explorer, double-click the new data structure object.
  6. In the editor, type the code for the data structure. You can use COBOL or S-COBOL.
  7. Save your code and exit the editor. AppMaster Builder saves the data structure in the APSDATA project subdirectory.
Parent topic: Projects


To create a Program Painter program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder Project Explorer, right-click an application object; then click Add > Program Painter program.
  2. In the Name field, type a name for the program.
  3. Click OK. This returns you to the Project Explorer.
  4. To set program properties, right-click the new program object on the Project Explorer; then click Properties.
    Note: If you cannot see the new program on the Project Explorer, expand the parent application.
  5. Set the properties as required; then click OK. For information on the fields and controls on the Properties page, see Program - Resource.
  6. To write program code, double-click the new program object on the Project Explorer. This starts the Program Painter.
  7. When you have completed the code, save it and exit the Program Painter.
Note: Your AppMaster Builder preferences and Application properties can affect program generation. Be sure to review these before generating the program or the application.
Parent topic: Projects
Related tasks
To create an AMB project
To set AppMaster Builder preferences
To set application properties
Related reference
Program - Resource
Application - Resource
AppMaster Builder


To create a program stub

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click an application entry.
  2. In the Name field, type a name for the program stub.
  3. Click OK. This returns you to the Project Explorer.
  4. From the Project Explorer, double-click the new program stub entry.
  5. In the Program Painter, type the code for the stub. Follow the rules outlined in the Program Stub section of the Coding Programs topic.
  6. Save your code and exit the Program Painter. AppMaster Builder saves the stub in the APSPROG project subdirectory.
Parent topic: Projects


To create an AMB project

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. With the AppMaster Builder perspective active, click Admin > Project > Create.
  2. Type the administrator password; then click OK.
  3. In the Qualifier field, type the full path to a directory to serve as a parent to contain AppMaster Builder projects.
  4. In the Project field, replace the default text with the name of the project.
  5. In the Group field, replace the default text with the name of a development group.
  6. Click Create. A message appears in the dialog header indicating that the project was created.
  7. Click Exit.
Note:
  • To ensure that your project is configured to your preferences, be sure to set AppMaster Builder preferences.
  • When you create a new project, it does not appear on the Project Explorer immediately if you have another project open at the time. In that case, to see the new project, follow the instructions in To change projects.
Parent topic: Projects
Related tasks
To create an application
To change projects
To set AppMaster Builder preferences
To view project files
To create a Program Painter program


To create an application

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder Project Explorer, right-click the project name; then click Add > Application.
  2. In the Name field, type a name for the application.
  3. Click OK. This returns you to the Project Explorer.
    Note: If you cannot see the application on the Project Explorer, expand the project.
Important: To ensure that your application is configured properly, be sure to set AppMaster Builder preferences, and Application properties.
Parent topic: Projects
Related concepts
Project Explorer Tree View
Related tasks
To create an AMB project
To set AppMaster Builder preferences
To set application properties


To create an Online Express program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. On the AppMaster Builder Project Explorer, right-click an application object; then click Add > Online Express program.
  2. In the Name field, type a name for the program.
  3. Click OK. This returns you to the Project Explorer.
    Note: If you cannot see the program on the Project Explorer, expand the application.
Parent topic: Projects


To filter programs

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click a project name; then click Filter Programs on the context menu.
  2. Do one of the following:
    • If you are not using workgroups, or if you are using workgroups and want the filter to include both local and workgroup locations, proceed to the next step.
    • If you are using workgroups and want the filter to show local programs only, click Local Files Only; then proceed to the next step.
  3. Click the program type you want to show on the tree view.
  4. To limit the filtered programs to those that start with specific characters, type those characters into the field that appears. Optional.
    Note: The default setting is *, meaning all programs of the type selected.
  5. Close the dialog box.

    The filters specified are reflected on the updated tree view.

Parent topic: Projects


To remove or delete an object

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To remove an object From the AppMaster Builder Project Explorer, but keep the project file for later use:

  1. From the AppMaster Builder Project Explorer, right-click the object.
  2. Click Remove.
    Note: You cannot remove an application or a project.

To delete an object from the Project Explorer and also delete the object's project file:

  1. From the AppMaster Builder Project Explorer, right-click the object.
  2. Click Delete.
Parent topic: Projects
Related concepts
Object Types
Project Explorer Tree View


To rename an object

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click an object; then click Rename.
  2. In the New Name field, type a new name for the object; then click Rename.
Note: You cannot rename a Data View, a Data Structure, or the Global folder.
Parent topic: Projects
Related concepts
Object Types


To reorder objects under a parent program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: Drag and drop functionality is not available from the Team Developer perspective
  1. On the Customization - General tab of your AppMaster Builder Preferences, check Enable drag drop.
  2. In the Project Explorer, drag and drop objects under a single program to reorder them.
Parent topic: Projects
Related tasks
Customization
To set AppMaster Builder preferences


To set debug options for an application

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder perspective from either tab, click Options / Debug.
  2. Select one of the following:
    • COBOL to trace execution and debug source code at the COBOL code level.
    • AMB to trace execution and debug source code at the AMB code level.
Parent topic: Projects


To sort programs in the Project Explorer

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, right-click a project; then select Sort programs from the context menu. This sorts the programs in the project by alphabetical order.
Parent topic: Projects


To specify a workgroup

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder perspective, click AppMaster Builder Preferences page [image].
  2. From the list of preferences pages, select AppMaster Builder.
  3. In the Workgroup name field, do one of the following:
    • Type the full path and workgroup name of the workgroup library file you want to use and click OK.
    • Click Select and use the Workgroup dialog box to select the workgroup path and name of the library file you want to use. The library types (Folders field) and locations display for a specified workgroup file when selecting the workgroup using the Workgroup dialog box. Click OK to return to the AppMaster Builder Preferences page.
  4. Click OK to save any changes.
Parent topic: Projects
Related concepts
Specifying a Workgroup
Related tasks
To create a workgroup
Related reference
Workgroup dialog box
AppMaster Builder


To update a data structure

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

To change the location where the data structure is inserted:

  1. From the AppMaster Builder Project Explorer, right-click a data structure object; then click Properties.
  2. From the Location drop-down list, select a new program location where you want the data structure to be inserted.
  3. Click OK. This returns you to the Project Explorer.

To edit data structure code:

  1. From the Project Explorer, double-click a data structure object.
  2. In the editor, update the code as required. You can use COBOL or S-COBOL.
  3. Save your code and exit the editor.
Parent topic: Projects


To view project files

  1. In Eclipse, open the AppMaster Builder perspective.
  2. Click Explore > Project.
  3. Double-click any directory to see a list of files in that directory.
Note: You can view the contents of some project files using a text editor; however, we do not recommend that you edit these files directly. To make changes to project files, use the appropriate AMB editor or painter.
Parent topic: Projects
Related tasks
To create an AMB project
To set AppMaster Builder preferences
Related reference
Project Files and Directories


Report Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To code a report page description
  • To code control breaks in reports
  • To code input-output statements for reports
  • To code report logic
  • To code Working-Storage entries for reports
  • To customize the Report Painter
  • To define non-printing detail items
  • To identify a report in Working-Storage
  • To identify report groups
  • To map report fields
  • To map report lines
  • To paint a report mock-up
  • To specify a report mock-up
  • To specify multiple reports
  • To start the Report Painter
  • To sum data items in a report
Parent topic: How to


To code a report page description

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, type RED in columns 4 through 6.
  2. Type the report name starting in column 12 of the same line.
  3. Code the number of printable lines on each page using the PAGE LIMIT Report Writer structure.
  4. Code the line number where you want the first control heading line or detail line of the report body to print on each page using the FIRST DETAIL parameter. Remember to leave space at the top of the page for any report heading and page heading lines when calculating the first detail line number.
  5. Code the line number where you want the last detail line of the report body to print on each page using the LAST DETAIL parameter. Remember to leave space at the bottom of the page for any control break lines, page footing lines, and report footing lines when calculating the last detail line number.
  6. Code the line number where you want the last control footing line to print for each page using the FOOTING parameter. Remember to leave space at the bottom of the page for any page footing and report footing lines when calculating the last control footing number.

Use the following syntax:

   RED     reportname
           [CONTROL [IS] | CONTROLS [ARE] [FINAL]
               dataname1 ... [datanameN]]
           [PAGE [LIMIT IS | LIMITS ARE] number [LINE|LINES]
               [FIRST DETAIL firstlinenumber]
               [LAST DETAIL lastlinenumber]
               [FOOTING footinglinenumber]].

For example:

   RED     STOCK-REPORT
           CONTROLS ARE FINAL WS-LOCATION-CODE
           PAGE LIMIT IS 50
           FIRST DETAIL 10
           LAST DETAIL 40
           FOOTING 47.
Parent topic: Report Painter
Related concepts
Define Report Logic
Related reference
RED
PAGE LIMIT


To code control breaks in reports

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, identify the data items you want to test for a control break. The order in which you code the data items creates the control hierarchy, where FINAL is the highest control, the first data item is the major control, and the last data item is the minor (lowest) control.
  2. Type RED in columns 4 through 6.
  3. Type the report name starting in column 12 of the same line.
  4. Continue coding, using the following as your guide:
       RED     reportname
           [CONTROL [IS] | CONTROLS [ARE] [FINAL]
               dataname1 ... [datanameN]]

For example:

   RED     STOCK-REPORT
           CONTROLS ARE FINAL WS-LOCATION-CODE
Parent topic: Report Painter
Related concepts
Define Report Logic
Related reference
RED


To code input-output statements for reports

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Report Painter, specify the FILE-CONTROL SELECT information with the Program Painter IO keyword, using dataname, "literal" or EXTERNAL externalfilename|ddname as follows:
       IO      filename ASSIGN [TO] dataname
                                "literal"
                                EXTERNAL externalfilename|ddname
           ORGANIZATION IS RECORD SEQUENTIAL
                           LINE
  2. Code the program input file description, using the FD keyword and the following format:
       FD      inputfilename
           LABEL RECORDS clause
           BLOCK CONTAINS clause
           [Other applicable COBOL FD clauses]
   01      inputrecordname              PIC clause.

    For example:

  3. Determine the output record size. The default size is 133, the standard mock-up size of 132 plus 1 byte for the carriage control character. To define a different report record size, calculate the size as follows.

    Record Size =

    Report mock-up size (maximum 247 characters)

    + 1 byte for carriage control

    + 2 bytes for the CODE clause, if used

  4. Code the program output file description, using the FD keyword and the following format. To accept the default record size, omit the RECORD CONTAINS clause.
       FD      outputfilename
           LABEL RECORDS clause
           [RECORD CONTAINS clause]
           [Other applicable COBOL FD clauses]
           REPORT IS|ARE reportname1 [... reportname15]
   01      outputrecordname              PIC clause.

    For example:

Parent topic: Report Painter
Related concepts
Define Report Logic
Related reference
IO
FD


To code report logic

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, initialize all report counters and set up control heading and footing items with the INITIATE statement.
  2. Process the detail lines with a GENERATE statement. If the report has multiple detail lines, code multiple GENERATE statements.
  3. End report processing with the TERMINATE statement.

Use the following structure:

   NTRY
                .
                .
           OPEN INPUT filename1
           ... OUTPUT filename2
                .
                .
           INITIATE reportname
                .
                .
           IF ...
               GENERATE detlineidentifier
                .
                .
           TERMINATE reportname
                .
                .
           CLOSE filename1 filename2
Parent topic: Report Painter
Related concepts
Code Report Logic
Related tasks
To specify multiple reports
Related reference
NTRY
INITIATE
GENERATE
TERMINATE


To code Working-Storage entries for reports

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, locate the output record description.
  2. Add Working-Storage entries needed for your report after the output record description in any of the following places:
    • Before the I/O description at the beginning of the program.
    • After the output record description.
    • After an 01 TYPE statements, and after your Procedure Division code.

For example:

WS    WS-DATE.
       05  WS-DATE-MM              PIC 9(2).
       05  WS-DATE-DD              PIC 9(2).
       05  WS-DATE-YY              PIC 9(2).
 WS    WS-DATE-HOLD.
       05  WS-DATE-YY-X            PIC 9(2).
       05  WS-DATE-MM-X            PIC 9(2).
       05  WS-DATE-DD-X            PIC 9(2).
Parent topic: Report Painter
Related concepts
Code Working-Storage
Related tasks
To specify multiple reports
Related reference
WS


To customize the Report Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
From the Editors page
On the Editors preferences page, you can set background and foreground colorization options for all of the AMB painters, and turn on basic color mode. You can also change the cursor style to a cross-hair cursor, and set a color and size for it.
  1. From the AppMaster Builder perspective, click AppMaster Builder preferences page [image].
  2. In the left pane, click Editors.
  3. Set options as desired; then click OK.

    For complete details on each field and control on this page, see the Editors user interface reference topic.

    Note: If you prefer to view code using a single background and a single foreground color, set these colors using the controls in the Basic color mode group. When specified, basic color mode overrides colorization settings specified on the Editors - Report Painter - Colorization page.
From the Editors - Report Painter - Colorization page
On the Editors - Report Painter - Colorization page, you set colorization options for specific code structures.
Note: If you prefer to override the color scheme defined here and instead edit code using a single background and a single foreground color, set these colors on the Editors preferences page using the controls in the Basic color mode group.
  1. From the AppMaster Builder perspective, click AppMaster Builder preferences page [image].
  2. In the left pane, expand Editors > Report Painter; then click Colorization.
  3. Check Enable colorization.
  4. To change the color for a structure:
    1. Select a structure on the Appearance color options list.
    2. Double-click the Color field.
    3. Select a color; then click OK.
  5. To define a custom color:
    1. On the Color dialog box, click Define Custom Colors.
    2. To define a color, either use the cross hairs and slider, or type a value into each field.
    3. Click Add to Custom Colors.
  6. When all colors are set as desired, click OK.

    For complete details on each field and control on this page and its associated dialog boxes, see the Editors - Report Painter - Colorization and Color dialog box user interface reference topics.

From within the Report Painter
While you are running the Report Painter, you can toggle the cross-hair cursor on and off, and customize its size and color.
  1. To toggle the cross-hair cursor on or off, press Alt + + (on the numeric keypad) or Alt + +/= (on the character keyboard).
  2. While toggled on, use the following short-cut key combinations to change the size and/or color of your cross-hair cursor:
    Alt + 1 through Alt + 9 | Sets the line thickness from 1 to 9 pixels.
    Alt + 0 (zero) | Changes the color of the cursor. Each time you press this combination, the color changes and continues to change with entered each key-stroke combination until all defined colors have been displayed; then the sequence begins again.
Parent topic: Report Painter
Related reference
Editors
Editors - Report Painter - Colorization
Color dialog box


To define non-printing detail items

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • At the end of an 01 TYPE statement, type REFERENCE in column 12, and provide a data name and PIC clause as well. Use the following syntax as your guide:
    REFERENCE [IS] dataname PIC picclause

For example:

   01      PART-DETAIL TYPE IS DETAIL
               NEXT GROUP PLUS 1
           MOCKUP LINE 13
           SOURCE WS-LOCATION-CODE    GROUP INDICATE
           SOURCE WS-LAST-COUNT-MONTH
           SOURCE WS-LAST-COUNT-DAY
           SOURCE WS-LAST-COUNT-YEAR
           SOURCE WS-QTY-IN-STOCK
           SOURCE WS-QTY-ISSUED
           SOURCE WS-QTY-RECEIVED
           REFERENCE WS-NO-OF-SALES   PIC 9999
Note:
  • A REFERENCE field value never displays when the detail line prints.
  • If you code a corresponding SUM statement (see the next step), AMB adds the field value to an internal sum accumulator.
Parent topic: Report Painter
Related concepts
Define Report Logic
Related reference
REFERENCE


To identify a report in Working-Storage

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, type RED in columns 4 through 6.
  2. Type the report name starting in column 12 of the same line, as follows:
       RED     reportname

For example:

   RED     STOCK-REPORT
Parent topic: Report Painter
Related concepts
Code Working-Storage
Related reference
RED


To identify report groups

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, for each report group you want to identify, type 01 in columns 4 and 5.
  2. Starting in column 12 of the same line, type TYPE and continue coding as follows:
       01      [identifier] TYPE IS REPORT FOOTING
                           CONTROL HEADING [FINAL]|controlname
                           CONTROL FOOTING [FINAL]|controlname
                           DETAIL

                             number
           [LINE [NUMBER IS] PLUS number
                             NEXT PAGE       ]

                             number
           [NEXT GROUP [IS] PLUS number
                             NEXT PAGE       ]
Note:
  • For each 01 TYPE statement:
    • You must assign an identifying data name for the DETAIL report group, the report body. Identifiers for the other report groups are optional. You use these identifying data names in the Procedure Division to refer to the various report groups.
    • The TYPE statements for CONTROL HEADING and CONTROL FOOTING report groups must indicate the name of control break field that causes the control break. This control data name must correspond to a data item specified in the CONTROLS option of the RED statement.
  • Optionally for each report group, designate the line number where the first line of the report group prints, using the LINE parameter.
  • Optionally for each report group, designate the line number where the first line of the next report group prints, using the NEXT GROUP parameter.
  • Report Writer treats each report group specified in the TYPE clause as a unit and always prints the entire group on one page. It never begins the group on one page and completes it on another.

For example:

   MOCK    STOCKRPT
   01      TYPE IS REPORT HEADING
             NEXT GROUP IS NEXT PAGE
   01      TYPE IS PAGE HEADING
             NEXT GROUP PLUS 3
   01      TYPE IS CONTROL HEADING WS-LOCATION-CODE
             NEXT GROUP PLUS 1
   01      PART-DETAIL TYPE IS DETAIL
             NEXT GROUP PLUS 1
   01      TYPE IS CONTROL FOOTING WS-LOCATION-CODE
   01      TYPE IS CONTROL FOOTING FINAL
   01      TYPE IS PAGE FOOTING
   01      TYPE IS REPORT FOOTING
             LINE PLUS 2
Parent topic: Report Painter
Related concepts
Define Report Logic
Related reference
01
TYPE


To map report fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
For the applicable report groups, indicate which data items supply values to output fields by typing SOURCE on line 12 of your program. Use the following syntax and guidelines:
           SOURCE [IS] dataname [PIC picclause]
               [BLANK [WHEN] ZERO]
               [JUSTIFIED|JUST [RIGHT]
               [CHANGE INDICATE|GROUP INDICATE]

Follow these rules when coding:

  • Map the data items within the report group from left to right, top to bottom, as they will appear on the printed report.
  • Include picture clauses if multiple fields are strung together on the mock-up. A PIC clause indicates the next matching COBOL picture in the mock-up is the COBOL picture for this data item.
  • Optionally print spaces when the value of the field is zero by specifying the BLANK WHEN ZERO parameter.
  • Optionally justify the field value with the JUSTIFIED RIGHT parameter.
  • Optionally print the value of the field only when it changes value with the CHANGE INDICATE parameter.
  • Optionally print the value of the field only on the first occurrence of the report group after a control break or a page advance with the GROUP INDICATE parameter.

For example:

   01      TYPE IS REPORT HEADING
               NEXT GROUP IS NEXT PAGE
           MOCKUP LINES 1 THRU 5
           SOURCE IS WS-DATE
   01      TYPE IS PAGE HEADING
               NEXT GROUP PLUS 3
           MOCKUP LINES 6 THRU 8
           SOURCE IS WS-DATE
   01      PART-DETAIL TYPE IS DETAIL
               NEXT GROUP PLUS 1
           MOCKUP LINE 13
           SOURCE WS-LOCATION-CODE    GROUP INDICATE
           SOURCE WS-LAST-COUNT-MONTH
           SOURCE WS-LAST-COUNT-DAY
           SOURCE WS-LAST-COUNT-YEAR
           SOURCE WS-QTY-IN-STOCK
           SOURCE WS-QTY-ISSUED
           SOURCE WS-QTY-RECEIVED
   01      TYPE IS PAGE FOOTING
               LINE PLUS 2
           MOCKUP LINE 24
           SOURCE IS PAGE-COUNTER
Note: For more information, seeReport Mapping Rules.
Parent topic: Report Painter
Related concepts
Define Report Logic
Report Mapping Rules
Related reference
SOURCE


To map report lines

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
In the Program Painter, follow each TYPE clause you coded for each group with a MOCKUP LINES clause, starting in column 12 on the next line down, as follows:
           MOCKUP LINE[S] linenumber1 [THRU linenumberN]

For example, the following code:

   MOCK    STOCKRPT
   01      TYPE IS REPORT HEADING
               NEXT GROUP IS NEXT PAGE
           MOCKUP LINES 1 THRU 5
   01      TYPE IS PAGE HEADING
               NEXT GROUP PLUS 2
           MOCKUP LINES 6 THRU 8
   01      TYPE IS CONTROL HEADING WS-LOCATION-CODE
           MOCKUP LINES 10 THRU 12
   01      PART-DETAIL TYPE IS DETAIL
               NEXT GROUP PLUS 1
           MOCKUP LINE 13
   01      TYPE IS CONTROL FOOTING WS-LOCATION-CODE
           MOCKUP LINES 14 THRU 19
   01      TYPE IS CONTROL FOOTING FINAL
           MOCKUP LINES 20 THRU 24
   01      TYPE IS PAGE FOOTING
               LINE PLUS 2
           MOCKUP LINE 25
   01      TYPE IS REPORT FOOTING
               LINE PLUS 2
           MOCKUP LINE 27

Corresponds to the following mock-up.:

*************************TOP OF DATA**********************
                 WONDERFUL WIDGETS INCORPORATED
                         MID-ATLANTIC
                          STOCK REPORT
                           XXXXXX XXX

                         MID-ATLANTIC
                         STOCK REPORT
                         XXXXXX XXX

LOCATION       LAST COUNT   QUANTITY   QUANTITY   QUANTITY
                  DATE      IN STOCK    ISSUED    RECEIVED

XXXXXXXXXXXX    99/99/99     ZZZ,ZZ9     ZZ,ZZ9    ZZZ,ZZ9

                           ---------  ---------  ---------
TOTAL BY LOCATION:         Z,ZZZ,ZZ9   Z,ZZZ,ZZ9  Z,ZZZ,ZZ9

TOTAL NUMBER OF SALES BY LOCATION:       ZZZ,ZZ9

TOTAL WONDERFUL WIDGETS IN STOCK:      Z,ZZZ,ZZ9
TOTAL WONDERFUL WIDGETS ISSUED:        Z,ZZZ,ZZ9
TOTAL WONDERFUL WIDGETS RECEIVED:      Z,ZZZ,ZZ9
TOTAL WONDERFUL WIDGETS SOLD:          Z,ZZZ,ZZ9

                             PAGE ZZZ9

                    *****  END OF REPORT  *****
Note: For more information, see Report Mapping Rules.
Parent topic: Report Painter
Related concepts
Define Report Logic
Report Mapping Rules
Related reference
TYPE
MOCKUP LINES


To paint a report mock-up

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Report Painter, type the literals and output fields in columns 1 through 247, as follows:
    • To create a literal field, type the literal characters.
    • To create an output field, type a PIC character string, for example Z,ZZZ,ZZ9 or XXXXX. You can use the following COBOL output edit masks directly within the report mock-up:
      • Floating numeric formats, including * $ + - S 9 Z
      • Alphanumeric masks
  2. To save your mock-up, click File > Save. AMB stores report mock-ups in your AMB project APSREPT directory.
Parent topic: Report Painter
Related concepts
Painting Report Mock-Ups
Define Report Logic


To start the Report Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • From the AppMaster Builder Project Explorer, double-click a report entry.
Note: The Report Painter uses the same text editor as the Program Painter. However, when you edit a report in this editor, the profile is set to APSREPT, which specifies the proper parameters for entering report mock-up items.
Parent topic: Report Painter
Related concepts
Paint Report Layouts
Define Report Logic


To sum data items in a report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Program Painter, identify the SOURCE or REFERENCE statements in the CONTROL FOOTING report groups that you want to sum.
  2. Use the following syntax as your guide:
       SUM     dataname [dataname] ...
           [UPON detlineidentifier [detlineidentifier] ...]
           [RESET [FINAL] controlname]
           [DATA-NAME fieldname]
           [PICTURE picclause]
  3. Use the following guidelines as you code:
    • Sum the data items within the report group from left to right, top to bottom, as they will appear on the printed report.
    • If the report has more than one detail line, use the UPON parameter to name the line where the summing takes place.
    • To override the AMB default of resetting SUM accumulators to zero after each control break, use the RESET parameter to do a running total and specify which control break should reset the accumulator.
    • To automatically move the value in the Report Writer field accumulator to a field you can reference in the Procedure Division, for example, to test the field or do further calculations, create the field by naming it in the DATA-NAME fieldname parameter.
    • Include a picture clause for SUM statements if multiple fields are strung together on the mock-up. A PIC clause indicates the next matching COBOL picture in the mock-up is the COBOL picture for this data item.

For example:

   MOCK    STOCKRPT
   01      TYPE IS REPORT HEADING
               NEXT GROUP IS NEXT PAGE
           MOCKUP LINES 1 THRU 5
           SOURCE WS-DATE

   01      TYPE IS PAGE HEADING
               NEXT GROUP PLUS 3
           MOCKUP LINES 6 THRU 8
           SOURCE WS-DATE

   01      TYPE IS CONTROL HEADING WS-LOCATION-CODE
           MOCKUP LINES 10 THRU 12

   01      PART-DETAIL TYPE IS DETAIL
               NEXT GROUP PLUS 1
           MOCKUP LINE 13
           SOURCE WS-LOCATION-CODE    GROUP INDICATE
           SOURCE WS-LAST-COUNT-MONTH
           SOURCE WS-LAST-COUNT-DAY
           SOURCE WS-LAST-COUNT-YEAR
           SOURCE WS-QTY-IN-STOCK
           SOURCE WS-QTY-ISSUED
           SOURCE WS-QTY-RECEIVED
           REFERENCE WS-NO-OF-SALES   PIC 9999

   01      TYPE IS CONTROL FOOTING WS-LOCATION-CODE
           MOCKUP LINES 14 THRU 18
           MOCKUP LINES 19 THRU 22
           SUM WS-QTY-IN-STOCK
           SUM WS-QTY-ISSUED
           SUM WS-QTY-RECEIVED
           SUM WS-NO-OF-SALES

   01      TYPE IS CONTROL FOOTING FINAL
           MOCKUP LINES 19 THRU 22
           SUM WS-QTY-IN-STOCK
           SUM WS-QTY-ISSUED
           SUM WS-QTY-RECEIVED
           SUM WS-NO-OF-SALES

   01      TYPE IS PAGE FOOTING
               LINE PLUS 2
           MOCKUP LINE 24
           SOURCE IS PAGE-COUNTER

   01      TYPE IS REPORT FOOTING
               LINE PLUS 3
           MOCKUP LINE 26
Note:
  • Use SUM for CONTROL FOOTING report groups only.
  • AMB creates an internal SUM accumulator field for each data item specified. The name of this field is dataname-nnnn, where nnnn is a 4-digit number. Each time the detail line containing the data item prints, AMB adds its value to the accumulator. AMB clears the accumulators either after each control break (the default) or after a control break you specify with the RESET option.
Parent topic: Report Painter
Related concepts
Define Report Logic
Related reference
SOURCE
REFERENCE
SUM


Screen Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To align screen fields
  • To define field attributes
  • To define screen attributes
  • To bypass field edits
  • To change repeated record blocks
  • To create repeated record blocks
  • To create system message fields
  • To define a global error message
  • To define field edits
  • To delete a field in a repeated record block
  • To define a field-specific error message
  • To delete field edits
  • To delete repeated record blocks
  • To delete screen fields
  • To duplicate screen fields
  • To modify attributes for a field in a record block
  • To move repeated record blocks
  • To paint a Savekey field
  • To paint a screen
  • To select multiple fields
  • To start the Screen Painter
  • To test screens and fields
  • To turn off the MDT tag
  • To use sticky mode
Parent topic: How to


To align screen fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, select a group of fields; the primary field becomes the basis for the alignment, that is, what the other fields align against.
  2. Click Arrange > Alignment.
  3. Select a horizontal and vertical alignment using the radio buttons provided. The sample fields in the alignment diagram simulate the result.
  4. Click OK.
Note: To align other fields with the same alignment you used in your previous alignment, select the fields and click Arrange > Align (horizvalue, verticalvalue). The Screen Painter aligns the fields according to the horizontal and vertical values displayed.
Parent topic: Screen Painter
Related concepts
Arranging Fields
Related tasks
To select multiple fields
To paint a screen
Related reference
Alignment


To define field attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, double-click a painted field. The Field Attributes dialog box appears.
  2. Specify the desired attributes.
  3. Click the check mark icon to accept your choices.
Note:
  • To cancel the selections, click the X icon.
  • To reset the attributes back to what they were when you accessed this window, click Extras > Reset Attribute.
Parent topic: Screen Painter
Related concepts
Field Attributes
Rules for Defining Field Attributes
CICS Data Transmission
Defining Data Representation
Related tasks
To paint a screen
Related reference
Field and Text Attributes


To define screen attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, double-click on any empty portion of the painted screen. The Screen Parameters dialog box appears showing default values.
  2. Change the values on this dialog box as necessary and/or do one or more of the following:
    • To assign generation options for your DC target, on the menu bar, click CICS, DLG, or IMS.
    • To assign IMS commands or values to the MFS PF key fields, on the menu bar, click IMS. The IMS Generation Parameters dialog box appears. On the menu bar, click PFkeys.
    • To change the MID/MOD order in which the I/O fields from your screen appear in the generated Working-Storage, on the menu bar click IMS. The IMS Generation Parameters dialog box appears. On the menu bar, click Reorder.
    • To construct trancodes by concatenating screen fields, literals, and PF keys, on the menu bar click IMS. The IMS Generation Parameters dialog box appears. On the menu bar, click Trancode.
    • To assign Assembler parameters, on the menu bar click IMS. The IMS Generation Parameters dialog box appears. On the menu bar, click Assembler.
    • To assign a default error message for the screen to display when the end user enters invalid data, on the menu bar click Edits.
    • To assign system message parameters, on the menu bar, click SYSMSG.
    • To define conditions for bypassing input edits for the screen, click Edits on the menu bar. The Field Edit Message and Attributes dialog box appears. On the menu bar, click Bypass.
Parent topic: Screen Painter
Related concepts
Defining Screen Attributes
Designing a Screen
Field Attributes
Related tasks
To paint a screen
Related reference
Screen Parameters
IMS Generation Parameters
Field Edit Messages and Attributes
SYSMSG Parameters
Field Edit Bypass Criteria
Assembler Generation Parameters
MFS Function Keys
IMS Trancode Construction


To bypass field edits

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, double-click on any empty portion of the painted screen. The Screen Parameters dialog box appears.
  2. On the menu bar, click Edits. The Field Edit Messages and Attributes dialog box appears.
  3. On menu bar, click Bypass. The Field Edit Bypass Criteria dialog box appears.
  4. Enter values into the fields, as appropriate.
  5. Click OK on each dialog box to return to the Screen Painter.
Parent topic: Screen Painter
Related reference
Screen Parameters
Field Edit Messages and Attributes
Field Edit Bypass Criteria


To change repeated record blocks

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, double-click anywhere on a repeated block (red fields). The Repeat Block Attributes dialog box appears.
  2. Change one or more values; then click OK.
Parent topic: Screen Painter
Related concepts
Painting Fields
Related reference
Repeat Block Attributes


To create repeated record blocks

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, on the row you want to repeat, click any field. If you want to repeat several rows, click a field on the top row.
  2. On the menu bar, click Repeat Block Repeat Block Tool. The Repeat Block Attributes dialog box appears.
  3. Enter the number of rows to repeat, and the number of times to repeat the row(s).
  4. Click Apply to create the block. The repeated fields appear red on your screen.
Parent topic: Screen Painter
Related concepts
Painting Fields
Related tasks
To paint a screen
Related reference
Repeat Block Attributes


To create system message fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, do one of the following:
    • If you want to paint your own field for system messages, paint a field, then double-click on an empty part of your painted screen.
    • If you want AppMaster Builder to generate the system message field automatically, without first painting a field for system messages, double-click on an empty part of your painted screen.

    The Screen Parameters dialog box appears.

  2. On the menu bar, click SYSMSG. The SYSMSG Parameters dialog box appears.
  3. Do one of the following:
    • To use the field you painted as a system message field, click your field name on the Name drop-down list.
    • To have AppMaster Builder generate the field for you, click *Yes or *SYSMSG on the Name drop-down list.
  4. ClickOK to return to your painted screen.
Parent topic: Screen Painter
Related tasks
To paint a screen
Related reference
SYSMSG Parameters
Screen Parameters


To define a global error message

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, double-click on any empty portion of the painted screen. The Screen Parameters dialog box appears.
  2. On the menu bar, click Edits. The Field Edit Messages and Attributes dialog box appears.
  3. Enter values into the fields, as appropriate.
  4. Click OK on each dialog box until you return to your painted screen.
Parent topic: Screen Painter
Related reference
Error Processing Messages
Screen Parameters
Field Edit Messages and Attributes


To define field edits

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, click on a field, then click Edit > Field Edits. The Field Edit Data Type dialog box appears.
  2. On the Local Data Class list, click the type of field edits you want to assign to the field.
  3. On the Local Data Type box, click on the format you want. The Field Edit summary dialog box appears with the default internal storage requirements appropriate to the format chosen.
  4. Click the appropriate buttons to perform the functions listed below. When the applicable dialog box appears, select or enter values as appropriate.
    • Internal - Define storage requirements for the field
    • Input - Define a format the end user must adhere to when entering data into the field, specify an error message, or code your own application edit routine
    • Output - Define the format for displaying the data in the field or code your own application edit routine
    • Values - Specify a range of valid values, a specific valid value, or conversion values for the field
Parent topic: Screen Painter
Related concepts
Defining Field Edits
Related reference
Screen Parameters
Field Edit Messages and Attributes


To delete a field in a repeated record block

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, click the field you want to delete from the original row (non-red) of the repeated block.
  2. Press the Delete key, and click Yes to confirm.
Parent topic: Screen Painter
Related concepts
Painting Fields


To define a field-specific error message

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, click on a field, then click Edit > Field Edits. The Field Edit Data Type dialog box appears.
  2. Complete the fields on the Field Edit Data Type dialog box, if necessary, and click OK.
  3. From the Field Edits dialog box, click Input.
  4. On the Input Representation dialog box, click Message. The Default Error Message dialog box appears.
  5. Code messages of up to 75 characters. This message overrides any global default messages you entered for your painted screen.
Parent topic: Screen Painter
Related reference
Error Processing Messages
Field Edits
Field Edit Data Type
Input Representation


To delete field edits

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, click on a field, then click Edit > Field Edits. The Field Edit Data Type dialog box appears.
  2. Click Delete, then click OK to confirm. All field edits for the field are deleted.
Note: To delete a specific edit only, for example, field justification, go to the appropriate window and modify your selection.
Parent topic: Screen Painter
Related concepts
Defining Field Edits
Related reference
Field Edits


To delete repeated record blocks

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, double-click anywhere on the repeated block (red fields). The Repeat Row Blocks dialog box appears.
  2. Click Delete.
Parent topic: Screen Painter
Related concepts
Painting Fields
Related reference
Repeat Block Attributes


To delete screen fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, select one or more fields.
  2. Press the Delete key, and click Yes to confirm.
Parent topic: Screen Painter
Related concepts
Arranging Fields


To duplicate screen fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, select one or more fields on your screen.
  2. Click Edit > Duplicate. The Screen Painter duplicates the size, attributes, and field edits for each field selected.
  3. To reposition the duplicated field or group, drag it to the desired location.
  4. Rename the duplicated fields.
Parent topic: Screen Painter
Related concepts
Duplicating Fields
Related tasks
To select multiple fields


To modify attributes for a field in a record block

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. Double-click on the field you want to mofidy from the original row (non-red) of the repeated block. The Field Attributes dialog box appears.
  2. Change the values as desired.
Parent topic: Screen Painter
Related concepts
Painting Fields
Related reference
Field and Text Attributes


To move repeated record blocks

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, right-click anywhere on the original (non-red) repeated block row.
  2. Drag it to a new location. All associated fields automatically follow.
Parent topic: Screen Painter
Related concepts
Painting Fields


To paint a Savekey field

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, paint entry field on your screen, giving it the following attributes:

    Attribute

    Setting

    Intensity

    Dark

    Type

    Protected

  2. Save the screen and exit the Screen Painter.
  3. Start Online Express for the program that corresponds to the screen in which you painted the field, and follow the steps in the To define a Savekey.
  4. In Online Express, define all control actions and database calls for the program.
  5. Click File > Savekey Specification. The Savekey Data window appears.
  6. To inform Online Express that you painted a savekey field on your screen, specify which fields to use for storing savekey data as follows:

    If your screen displays...

    Select a screen field from...

    Only a single occurrence of data with the Update, Delete, or Next action

    Non Repeated Savekey

    Only a repeated record block with the Update, Delete, Forward, or Backward action

    Repeated Savekey

    Both of the above

    Either Non Repeated Savekey and Repeated Savekey

    Or For All Savekeys

  7. Click OK.
Parent topic: Screen Painter
Related concepts
Store on your Screen
Related tasks
To define a Savekey
Related reference
Savekey Data


To paint a screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. From the AppMaster Builder Project Explorer, double-click a screen name to access the Screen Painter.
  2. To paint each field, click Entryfield Entry Field Tool or Static Text Static Text Tool.
  3. Position the mouse where you want to place the field on your window. Click once to drop the field.
  4. Specify the field length by dragging the field to the size desired. Make sure the tracking option is turned on so you can watch the size increase or decrease.
  5. Do one or more of the following:
    • To specify attributes, double click on the field. The Field Attributes dialog box appears. Change the attribute defaults as appropriate.
    • To specify field edits for entry fields, click the painted field and click Edit > Field Edits.
    • To paint a system message field, see the Help topic To create system message fields.
    • To assign screen and generation attributes, double-click anywhere on the screen. The Screen Parameters dialog box appears. Specify desired parameters; specify environment-specific parameters from the menu bar.
Tip:
  • For more information on painting fields, see Painting Fields.
  • To quickly paint several fields of the same type, use Sticky Mode.
  • To easily align fields, use the Alignment option.
  • Use the repeated block function to paint rows (blocks), of fields.
  • Test your screen functionality with the Test option.
Parent topic: Screen Painter
Related concepts
Designing a Screen
Painting Fields
Painting Program Fields
Related tasks
To use sticky mode
To align screen fields
To test screens and fields
To create repeated record blocks
To create system message fields
To define field attributes
To define screen attributes
Related reference
Field and Text Attributes
Field Edits


To select multiple fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter using the Selection tool Selection Tool, click the first field you want to select.
  2. Press and hold the Shift key
  3. Click on each additional field you want to select.
  4. Release the Shift key.
Note: The first field you select is the Key field. The Screen Painter uses the Key field as a reference point when performing certain tasks such as aligning screen fields.
Parent topic: Screen Painter
Related concepts
Arranging Fields
Related tasks
To align screen fields
To duplicate screen fields


To start the Screen Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • From the AppMaster Builder Project Explorer, Find the screen you want to edit on the application tree and double-click it.
Parent topic: Screen Painter


To test screens and fields

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, click the Test Tool Test Tool to turn on testing mode.
  2. To turn off the testing mode, click the Selection Tool Selection Tool in the toolbar.
Note:
  • The Test option tests the behavior of an individual screen, but cannot test the flow of functions between screens.
  • If, when testing a large screen, the toolbar disappears, press Alt+F6 to bring the toolbar back into focus.
Parent topic: Screen Painter
Related concepts
Testing Screen Behavior
Related tasks
To paint a screen


To turn off the MDT tag

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. In the Screen Painter, double-click an updateable I/O field from which you want to send modified and unmodified data. The Field Attributes dialog box appears.
  2. Uncheck MDT.
  3. Click the check mark in the upper left-hand area of the dialog box to confirm the change.
  4. Exit the Field Attributes dialog box.
  5. Repeat steps 1 and 4 for each applicable field.
  6. Edit the APCICSIN control file and set the &CIC-MDTOFF-PROCESSING flag to yes.
Parent topic: Screen Painter
Related concepts
CICS Data Transmission
Related reference
Field and Text Attributes
APCICSIN


To use sticky mode

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. To turn on sticky mode, in the Screen Painter, click Tools > Sticky Mode.
  2. Click either Static Text Static Text Tool or Entryfield Entry Field Tool. Size and position the field on your window.
  3. For each subsequent field, position the mouse where you want the field on the window and click the mouse button to drop the field.
  4. To turn sticky mode off, click Tools > Sticky Mode.
Parent topic: Screen Painter
Related concepts
Painting Fields
Related tasks
To paint a screen


User Areas

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: All tasks listed in this section can be performed using the AppMaster Builder perspective or the Team Developer perspective (technology preview) unless otherwise noted.
  • To create a user area
  • To delete a user area
  • To clean a user area
Parent topic: How to


To create a user area

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. With the AppMaster Builder perspective active, click User > User Area > Create.
  2. In the User name field, type your name, or a name you want to use as your AMB user ID. This user name is your AMB user ID.
  3. Click Create.

    AMB creates a new directory of the same name as your provided AMB user ID. This new directory is a subdirectory to the AMB user area parent directory shown in the User area directory field.

  4. Click Exit to close the Create User Area dialog box.
Parent topic: User Areas
Related concepts
AppMaster Builder User Areas
Related reference
Create User Area
User Area Directories


To delete a user area

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Warning: This action deletes the entire individual user area directory structure, effectively deleting the user ID from AMB. If you want to remove generated files from a user area without deleting the user ID, use the Clean option instead.
  1. With the AppMaster Builder perspective active, click User > User Area > Delete.
  2. On the Existing user IDs list, click the user ID for the user area you want to delete.
  3. Click Delete.
  4. Click Yes on the prompt.
  5. Click Exit.
Parent topic: User Areas
Related concepts
AppMaster Builder User Areas
Related reference
Delete User Area
User Area Directories


To clean a user area

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. With the AppMaster Builder perspective active, click User > User Area > Clean.
  2. Click Yes.
Note: AMB determines which user area to clean based on the User area directory defined in AppMaster Builder preferences.
Parent topic: User Areas
Related concepts
AppMaster Builder User Areas
Related reference
User Area Directories


Reference

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • cmdgen command
    Generates AMB applications, programs, and screens.
  • Configuration XML File
    Describes the coding requirements for the configuration XML file.
  • Control (CNTL) Files
    Lists the control files that enable you to customize your AMB projects and development environment.
  • Customizer/Micro Focus Generator (MFG)
    Describes AMB Customizer rule components and the MFG structures you can use with them.
  • Data Communication Calls
    AMB Data Communication calls are predefined, easy-to-use statements that let you focus on what needs to be accomplished, rather than the mechanics of the target environment. To address environment-specific requirements, you can extend these calls with arguments; no native coding is required. These calls facilitate both generic processing and specialized requests.
  • Data Structures
    Lists the shorthand data structures valid in the Data Structure Editor.
  • Database Access Statements
    Lists the AMB-specific statements you can use to access a database.
  • Database Calls
    AMB Database (DB) calls are predefined, easy-to-use statements with common syntax that allows transparent access to a variety of databases. The AMB DB calls let you focus on what needs to be accomplished, rather than the mechanics of the target environment. To address environment-specific requirements, you can extend these calls with arguments; no native coding is required. These calls facilitate both generic processing and specialized requests.
  • Date Field Formats
    Describes valid input and output formats for all date fields.
  • Distributed Generation Server
    Provides reference information for the AMBCOMP program, JCL, and output files and directories.
  • AppMaster Builder Error Messages
    Provides information for each error message produced by the various AppMaster Builder (AMB) painters, utilities, and generators.
  • Fields, Flags, and Exit Points
    AppMaster Builder supplies you with several data fields and flags you can use to test values, to determine the validity of user-entered data, and to test for error conditions. AMB also supplies exit points you can use to customize methods.
  • IMS Calls
    AMB supports IMS calls for Character applications generating for an IMS DB target. Also supported are IMS DC fast path data communication calls for single-platform character-based applications, and system service calls for IMS DC.
  • Libraries and Directories
    Lists the AMB directory structure and the members of each AppMaster Builder directory library.
  • Program Painter Keywords
    Lists each keyword used in the Program Painter and provides a description for each.
  • Programming and Size Limitations
    Provides information about AMB-specific programming size limitations.
  • Report Writer Structures
    Use Report Writer structures to code report logic in batch programs and applications after you paint your report mock-up in the Report Painter. Report Writer structures enable you to:
  • Reserved Words
    Lists the reserved AMB-specific words that apply to coding programs.
  • Run-time Module - A1MVCL
    Describes the A1MVCL run-time module that ensures programs that contain alternate I/O areas execute properly.
  • S-COBOL Structures
    An AppMaster Builder program can be coded in AMB Structured COBOL (S-COBOL) language structures, either in combination with or instead of COBOL statements. S-COBOL structures are procedural, and extend the power of native COBOL, yet simplify and shorten the amount of code you must write.
  • Time Field Formats
    Describes valid input and output formats for all date fields.
  • User Interface Reference
    Describes each component of the various user interfaces that make up AppMaster Builder, on the field and control level.
Parent topic: AppMaster Builder


cmdgen command

Generates AMB applications, programs, and screens.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

cmdgen /f [path\]configXMLfilename [/c] [/h | /?] [/m mapsetname[;...]]
 [/p programname[;...]] [/q] [/s screenname[;...]] [/{parameter=value}]

Parameters:

path | The full path to your configuration XML file. You can omit the path when you execute cmdgen from the cmdgnxml directory of your user test area.
configXMLfilename | The name of the configuration XML file containing the application(s) you want to generate.
/c | Specifies continuous mode, meaning that generation continues regardless of returned errors.
/h or /? | Displays help for cmdgen syntax.
/m mapsetname[;...]] | Specifies one or more mapsets contained in the configuration XML file that you want to generate with this command. This enables you to choose a subset of mapsets rather than generating all of them. Separate multiple mapset names with a semicolon (;).
/p programname[;...]] | Specifies one or more programs contained in the configuration XML file that you want to generate with this command. This enables you to choose a subset of programs rather than generating all of them. Separate multiple program names with a semicolon (;).
/q | Specifies quiet mode, meaning that the console screen does not display output.
/s screenname[;...] | Specifies one or more screens contained in the configuration XML file that you want to generate with this command. This enables you to choose a subset of screens rather than generating all of them. Separate multiple screen names with a semicolon (;).
/{parameter=value} | Specifies a parameter and a value to override the value specified for that parameter in the configuration XML file or, if the parameter is not defined in the configuration XML file, to specify a parameter and a value in addition to those defined in the configuration XML file.

Examples:

Example 1
Generates all programs and screens defined in a configuration XML file created for the myapp application:
cmdgen /f ap_myapp.xml
Example 2
Generates only the myprog program and the myscreen screen, both defined in the configuration file generated for the myapp application:
cmdgen /f ap_myapp.xml /p myprog /s myscreen
Example 3
Generates just the programs screens specified, all of which are defined in the configuration file:
cmdgen /f ap_myapp.xml /p myprog1;myprog2 /s myscreen1;myscreen2
Example 4
Generates an entire application, overriding the value defined in the configuration XML file for the WORKGROUP parameter with an alternate value:
cmdgen /f ap_myapp.xml /[WORKGROUP=QAGROUP1]
Parent topic: Reference
Related concepts
Generating from the Command Line
Related tasks
To create a configuration XML file
To generate from the command line


Configuration XML File

  • XML Header
  • Configuration XML File Elements
  • Examples
Parent topic: Reference
Related concepts
Generating from the Command Line
Related tasks
To create a configuration XML file
To generate from the command line


XML Header

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This code is required at the beginning of each configuration XML file to identify the file as XML format.

Syntax:

<?xml version="1.0" encoding="utf-8" ?>
Parent topic: Configuration XML File


Configuration XML File Elements

  • application Element
    This specifies the name of an application you want to generate.
  • applications Element
    This element is a container for all of the definitions necessary to generate an application using this configuration XML file.
  • cmdgen Element
    This element specifies the appropriate XML namespace and serves as a container for all definitions in the configuration XML file. cmdgen is the root element of the configuration XML file.
  • dd Element
    This specifies the locations of the input files used by the various AppMaster Builder generators, and the storage locations for output files such as generated COBOL, BMS, MFS and generation log files.
  • dds Element
    This element is a container for all of the data definitions necessary to generate an application.
  • globals Element
    This element is reserved for future use and is not currently required.
  • multiple-map-mapset Element
    This defines multiple-map mapsets for BMS only.
  • multiple-map-mapset-screen Element
    This identifies a particular screen contained in a multiple-map mapset.
  • multiple-map-mapsets Element
    This element serves as a container for mapset definitions in a BMS multiple-map mapset. Because this information is not available in either the application definition file (APSAPPL) or individual screen files (APSSCRN) you must code this element into the configuration XML file manually.
  • parm Element
    This element specifies information that is not found in the application properties file (APRAPPL) or program properties file (APRPROG), and are typically the settings found in your AppMaster Builder preferences.
  • parms Element
    This element is a container for all of the parameter definitions necessary to generate an application.
  • program Element
    This defines each program in your application. Screens are associated with their respective programs.
  • programs Element
    This element is a container for all of the dd definitions necessary to generate an application.
  • screen Element
    This element defines each screen in a single program.
  • screens Element
    This element serves as a container for screen definitions associated with a single program.
Parent topic: Configuration XML File


application Element

This specifies the name of an application you want to generate.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<application name="applname"></application>

Parameter:

applname Name of an application

Attributes:

parent | applications
occurrences | one
children
  • parms
  • dds
  • globals
  • programs
  • multiple-map-mapsets
Parent topic: Configuration XML File Elements


applications Element

This element is a container for all of the definitions necessary to generate an application using this configuration XML file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<applications></applications>

Attributes:

parent | cmdgen
occurrences | one
child | application
Parent topic: Configuration XML File Elements


cmdgen Element

This element specifies the appropriate XML namespace and serves as a container for all definitions in the configuration XML file. cmdgen is the root element of the configuration XML file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<cmdgen xmlns="http://xml.microfocus.com/schema/amb/v1.0/cmdgen.xsd">

Attributes:

parent | none
occurrences | one
child | applications
Parent topic: Configuration XML File Elements


dd Element

This specifies the locations of the input files used by the various AppMaster Builder generators, and the storage locations for output files such as generated COBOL, BMS, MFS and generation log files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<dd dd="ddname" file="location" />

Parameters:

ddname The name of an AppMaster Builder library. Valid values are:

For more information on AppMaster Builder libraries, see the topic AMB Libraries and Directories.
  • APRAPPL
  • APRPROG
  • APSAPPL
  • APSCNTL
  • APSDATA
  • APSDE
  • APSEXPS
  • APSMACS
  • APSPROG
  • APSREPT
  • APSSCFE
  • APSSCRN
  • APSSRC
  • CNTL
  • COBCICS
  • COBIMS
  • COBMVS
  • COPYLIB
  • DBDSRC
  • DDISRC
  • DDISYMB
  • FMPOUT
  • GAPSPROG
  • GCOBOL
  • GENBMS
  • GENMFS
  • GENSRC
  • GLOGFILE
  • GSCR
  • GSCRSYMB
  • PSBSRC
  • SCRCOPY
  • SCRSYMB
  • SQLDDL
  • USERCNTL
  • USERMACS
location | The full path to the library specified in ddname.
parent | application
occurrences | one or more
children | none

Attributes:

parent | application
occurrences | one or more
children | none
Parent topic: Configuration XML File Elements


dds Element

This element is a container for all of the data definitions necessary to generate an application.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<dds></dds>

Attributes:

parent | application
occurrences | one
child | dd
Parent topic: Configuration XML File Elements


globals Element

This element is reserved for future use and is not currently required.
Parent topic: Configuration XML File Elements


multiple-map-mapset Element

This defines multiple-map mapsets for BMS only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<multiple-map-mapset mapset-name="mapsetname"></multiple-map-mapset>

Parameters:

mapsetname The name of the multiple-map mapset

Attributes:

parent | multiple-map-mapsets
occurrences | one to many
child | multiple-map-mapset-screen
Parent topic: Configuration XML File Elements


multiple-map-mapset-screen Element

This identifies a particular screen contained in a multiple-map mapset.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<multiple-map-mapset-screen screen-name="screenname" />

Parameters:

screenname The name of a screen defined in the multiple-map mapset specified

Attributes:

parent | multiple-map-mapset
occurrences | two to 20
children | none
Parent topic: Configuration XML File Elements


multiple-map-mapsets Element

This element serves as a container for mapset definitions in a BMS multiple-map mapset. Because this information is not available in either the application definition file (APSAPPL) or individual screen files (APSSCRN) you must code this element into the configuration XML file manually.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<multiple-map-mapsets></multiple-map-mapsets>

Attributes:

parent | application
occurrences | none or one
child | multiple-map-mapset
Parent topic: Configuration XML File Elements


parm Element

This element specifies information that is not found in the application properties file (APRAPPL) or program properties file (APRPROG), and are typically the settings found in your AppMaster Builder preferences.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<parm parmname="parmvalue" />

Parameters:

parmname | parmvalue
A2APPL | Name of the application
A2MDB | Database (DB) target
A2MDC | User Interface (UI) target
APLSTG | YES | NO
parmname | parmvalue
A2APPL | Name of the application
A2MDB | Database (DB) target
A2MDC | User Interface (UI) target
APLSTG | YES | NO
APSDEBUG | YES | NO
parmname | parmvalue
A2APPL | Name of the application
A2MDB | Database (DB) target
A2MDC | User Interface (UI) target
APLSTG | YES | NO
APSDEBUG | YES | NO
APXCURR | Currency sign
APXLANG | Language
CARDIN | Name of the CARDIN file. This is usually APSDBDC.
PROGSRC | YES | NO
parmname | parmvalue
A2APPL | Name of the application
A2MDB | Database (DB) target
A2MDC | User Interface (UI) target
APLSTG | YES | NO
APSDEBUG | YES | NO
APXCURR | Currency sign
APXLANG | Language
CARDIN | Name of the CARDIN file. This is usually APSDBDC.
PROGSRC | YES | NO
SSMCBL2G | YES | NO
parmname | parmvalue
A2APPL | Name of the application
A2MDB | Database (DB) target
A2MDC | User Interface (UI) target
APLSTG | YES | NO
APSDEBUG | YES | NO
APXCURR | Currency sign
APXLANG | Language
CARDIN | Name of the CARDIN file. This is usually APSDBDC.
PROGSRC | YES | NO
SSMCBL2G | YES | NO
SSMSQL | DB2 | blank
YES | List the generated code in the job listing
NO | Do not list the generated code in the job listing
YES | Generate code for debugging
NO | Do not generate code for debugging
YES | Create program manifest
NO | Do not create program manifest
YES | Generate non-OS/VS COBOL
NO | Generate OS/VS COBOL
DB2 | Program accesses DB2 data
blank | Program does not access DB2 data
APSDEBUG | YES | NO
APXCURR | Currency sign
APXLANG | Language
CARDIN | Name of the CARDIN file. This is usually APSDBDC.
PROGSRC | YES | NO
SSMCBL2G | YES | NO
SSMSQL | DB2 | blank
WORKGROUP | AppMaster Builder workgroup name. Optional.
APSPARM | Name of the APSPARM member. This is usually APSPARM.
ZISPFIO | Name of the ZISPFIO member. This is usually ZISPFIO. Use this when you are generting ISPF screens.
parent | parms
occurrences | one or more
children | none
APXCURR | Currency sign
APXLANG | Language
CARDIN | Name of the CARDIN file. This is usually APSDBDC.
PROGSRC | YES | NO
SSMCBL2G | YES | NO
SSMSQL | DB2 | blank
WORKGROUP | AppMaster Builder workgroup name. Optional.
APSPARM | Name of the APSPARM member. This is usually APSPARM.
ZISPFIO | Name of the ZISPFIO member. This is usually ZISPFIO. Use this when you are generting ISPF screens.
parent | parms
occurrences | one or more
children | none
SSMCBL2G | YES | NO
SSMSQL | DB2 | blank
WORKGROUP | AppMaster Builder workgroup name. Optional.
APSPARM | Name of the APSPARM member. This is usually APSPARM.
ZISPFIO | Name of the ZISPFIO member. This is usually ZISPFIO. Use this when you are generting ISPF screens.
parent | parms
occurrences | one or more
children | none
SSMSQL | DB2 | blank
WORKGROUP | AppMaster Builder workgroup name. Optional.
APSPARM | Name of the APSPARM member. This is usually APSPARM.
ZISPFIO | Name of the ZISPFIO member. This is usually ZISPFIO. Use this when you are generting ISPF screens.
parent | parms
occurrences | one or more
children | none
WORKGROUP | AppMaster Builder workgroup name. Optional.
APSPARM | Name of the APSPARM member. This is usually APSPARM.
ZISPFIO | Name of the ZISPFIO member. This is usually ZISPFIO. Use this when you are generting ISPF screens.
parent | parms
occurrences | one or more
children | none

Attributes:

parent | parms
occurrences | one or more
children | none
Parent topic: Configuration XML File Elements
Related tasks
To set AppMaster Builder preferences


parms Element

This element is a container for all of the parameter definitions necessary to generate an application.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<parms></parms>

Attributes:

parent | application
occurrences | one
child | parm
Parent topic: Configuration XML File Elements


program Element

This defines each program in your application. Screens are associated with their respective programs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<program name="progname" type="{APSEXPS|APSPROG}" subtype="{BATCH|STUB|NONE}"
 gentype="{APSEXPS|APSEXPSF|APSPROG}"></program>

Parameters:

progname | Name of a program
type="APSEXPS" | Online Express program
type="APSPROG" | Program Painter program
BATCH | Batch program
STUB | Program stub
NONE | Online Express program
gentype="APSEXPS" | For Online Express programs, creates a Program Painter (APSPROG) file but does not generate COBOL
gentype="APSEXPSF" | For Online Express programs, creates a Program Painter (APSPROG) file and also generates COBOL
gentype="APSPROG" | For Program Painter applications, this option generates COBOL

Attributes:

parent | programs
occurrences | one or more
child | screens
Parent topic: Configuration XML File Elements


programs Element

This element is a container for all of the dd definitions necessary to generate an application.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<programs></programs>

Attributes:

parent | application
occurrences | one
child | program
Parent topic: Configuration XML File Elements


screen Element

This element defines each screen in a single program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<screen name="screenname" mapset="mapsetname" />

Parameters:

screenname | Name of the screen
mapsetname | For BMS only , the name of the mapset

Attributes:

parent | screens
occurrences | one to many
child | none
Parent topic: Configuration XML File Elements


screens Element

This element serves as a container for screen definitions associated with a single program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

<screens></screens>

Attributes:

parent | program
occurrences | none or one
child | screen
Parent topic: Configuration XML File Elements


Examples

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Configuration XML File (no WORKGROUP parm specified)

<?xml version="1.0" encoding="utf-8" ?>
<cmdgen xmlns="http://xml.microfocus.com/schema/amb/v1.0/cmdgen.xsd">
  <applications>
    <application name="APPL1">
      <parms>
        <parm A2APPL="APPL1" />
        <parm A2MDB="SQL" />
        <parm A2MDC="CICS" />
        <parm APLSTG="NO" />
        <parm APSDEBUG="NO" />
        <parm APXCURR="$" />
        <parm APXDECM="PERIOD" />
        <parm APXLANG="ENGLISH" />
        <parm CARDIN="APSDBDC" />
        <parm PROGSRC="NO" />
        <parm SSMCBL2G="YES" />
        <parm SSMSQL="DB2" />
        <parm APSPARM="APSPARM" />
        <parm ZISPFIO="ZISPFIO" />
      </parms>
      <dds>
        <dd dd="APRAPPL"  file="C:\AMB\PROJ\GRP\APRAPPL" />
        <dd dd="APRPROG"  file="C:\AMB\PROJ\GRP\APRPROG" />
        <dd dd="APSAPPL"  file="C:\AMB\PROJ\GRP\APSAPPL" />
        <dd dd="APSCNTL"  file="%ProgramFiles(x86)%\etc\CNTL" />
        <dd dd="APSDATA"  file="C:\AMB\PROJ\GRP\APSDATA" />
        <dd dd="APSDE"    file="C:\AMB\PROJ\GRP\APSDE" />
        <dd dd="APSEXPS"  file="C:\AMB\PROJ\GRP\APSEXPS" />
        <dd dd="APSMACS"  file="%ProgramFiles(x86)%\etc\APSMACS" />
        <dd dd="APSPROG"  file="C:\AMB\PROJ\GRP\APSPROG" />
        <dd dd="APSREPT"  file="C:\AMB\PROJ\GRP\APSREPT" />
        <dd dd="APSSCFE"  file="C:\AMB\PROJ\GRP\APSSCFE" />
        <dd dd="APSSCRN"  file="C:\AMB\PROJ\GRP\APSSCRN" />
        <dd dd="APSSRC"   file="C:\AMB\PROJ\GRP\APSSRC" />
        <dd dd="CNTL"     file="%ProgramFiles(x86)%\etc\CNTL" />
        <dd dd="COBCICS"  file="C:\AMB\PROJ\GRP\COBCICS" />
        <dd dd="COBIMS"   file="C:\AMB\PROJ\GRP\COBIMS" />
        <dd dd="COBMVS"   file="C:\AMB\PROJ\GRP\COBMVS" />
        <dd dd="COPYLIB"  file="C:\AMB\PROJ\GRP\COPYLIB" />
        <dd dd="DBDSRC"   file="C:\AMB\PROJ\GRP\DBDSRC" />
        <dd dd="DDISRC"   file="C:\AMB\PROJ\GRP\DDISRC" />
        <dd dd="DDISYMB"  file="C:\AMB\PROJ\GRP\DDISYMB" />
        <dd dd="FMPOUT"   file="C:\AMB\PROJ\GRP\FMPOUT" />
        <dd dd="GAPSPROG" file="C:\work\gapsprog" />
        <dd dd="GCOBOL"   file="C:\work\gcobol" />
        <dd dd="GENBMS"   file="C:\AMB\PROJ\GRP\GENBMS" />
        <dd dd="GENMFS"   file="C:\AMB\PROJ\GRP\GENMFS" />
        <dd dd="GENSRC"   file="C:\AMB\PROJ\GRP\GENSRC" />
        <dd dd="GLOGFILE" file="C:\work\glogfile" />
        <dd dd="GSCR"     file="C:\work\gscr" />
        <dd dd="GSCRSYMB" file="C:\work\gscrsymb" />
        <dd dd="PSBSRC"   file="C:\AMB\PROJ\GRP\PSBSRC" />
        <dd dd="SCRCOPY"  file="C:\AMB\PROJ\GRP\SCRCOPY" />
        <dd dd="SCRSYMB"  file="C:\AMB\PROJ\GRP\SCRSYMB" />
        <dd dd="SQLDDL"   file="C:\AMB\PROJ\GRP\SQLDDL" />
        <dd dd="USERCNTL" file="C:\AMB\PROJ\GRP\CNTL" />
        <dd dd="USERMACS" file="C:\AMB\PROJ\GRP\USERMACS" />
      </dds>
      <globals>
      </globals>
      <programs>
        <program name="PROG1" type="APSEXPS" subtype="NONE" gentype="APSPROG" >
          <screens>
            <screen name="SCRN1" mapset="SCRN1$" />
          </screens>
        </program>
        <program name="PROG2" type="APSEXPS" subtype="NONE" gentype="APSPROG" >
          <screens>
            <screen name="SCRN2" mapset="SCRN2$" />
          </screens>
        </program>
      </programs>
      <multiple-map-mapsets>
      </multiple-map-mapsets>
    </application>
  </applications>
</cmdgen>

Configuration XML File with WORKGROUP parm specified

<?xml version="1.0" encoding="utf-8" ?>
<cmdgen xmlns="http://xml.microfocus.com/schema/amb/v1.0/cmdgen.xsd">
  <applications>
    <application name="APPL1">
      <parms>
        <parm A2APPL="APPL1" />
        <parm A2MDB="SQL" />
        <parm A2MDC="CICS" />
        <parm APLSTG="NO" />
        <parm APSDEBUG="NO" />
        <parm APXCURR="$" />
        <parm APXDECM="PERIOD" />
        <parm APXLANG="ENGLISH" />
        <parm CARDIN="APSDBDC" />
        <parm PROGSRC="NO" />
        <parm SSMCBL2G="YES" />
        <parm SSMSQL="DB2" />
        <parm WORKGROUP="WORKGROUP1" />
        <parm APSPARM="APSPARM" />
        <parm ZISPFIO="ZISPFIO" />
      </parms>
      <dds>
        <dd dd="GAPSPROG" file="C:\work\gapsprog" />
        <dd dd="GCOBOL"   file="C:\work\gcobol" />
        <dd dd="GLOGFILE" file="C:\work\glogfile" />
        <dd dd="GSCR"     file="C:\work\gscr" />
        <dd dd="GSCRSYMB" file="C:\work\gscrsymb" />
        <dd dd="GWORKGRP" file="C:\WORKGROUPS" />
      </dds>
      <globals>
      </globals>
      <programs>
        <program name="PROG1 type="APSEXPS" subtype="NONE" gentype="APSPROG" >
          <screens>
            <screen name="SCRN1" mapset="SCRN1$" />
          </screens>
        </program>
        <program name="PROG2" type="APSEXPS" subtype="NONE" gentype="APSPROG" >
          <screens>
            <screen name="SCRN2" mapset="SCRN2$" />
          </screens>
        </program>
        <program name="STUB1" type="APSPROG" subtype="STUB" gentype="NONE" >
        </program>
      </programs>
      <multiple-map-mapsets>
          <multiple-map-mapset mapset-name="MULT1$">
            <multiple-map-mapset-screens>
              <multiple-map-mapset-screen screen-name="SCRN3" />
              <multiple-map-mapset-screen screen-name="SCRN4" />
            </multiple-map-mapset-screens>
          </multiple-map-mapset>
      </multiple-map-mapsets>
    </application>
  </applications>
</cmdgen>
Parent topic: Configuration XML File


Control (CNTL) Files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following is a list of the control files AMB supplies. You can edit AMB Control (CNTL) files to customize your projects to your development environment. The Help topics on this list provide the variables you can specify with each CNTL file and what affect changes in variables or their values have on your projects. CNTL files are located by default in your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cntl folder.

  • APCICSIN
    Controls CICS options.
  • APDB2IN
    Controls SQL calls.
  • APDLGIN
    Controls DLG.
  • APFEIN
    Controls field edits
  • APHLPIN
    Controls User Help
  • APIMSIN
    Controls IMS DB calls.
  • APSDBDC
    Controls database and user interface calls.
  • APSPROJ
    Controls the output picture of numeric fields.
  • APVSAMIN
    Controls VSAM batch and online.
Parent topic: Reference
Related concepts
Rules for Defining Field Attributes
Related reference
Edit Masks
Fields and Flags for Edit Routines
REDEFINES


APCICSIN

Controls CICS options.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

File Contents:

Edit APCICSIN to control the following CICS options:

  • DLIUIB name
  • Prologue generation
  • Inline error checking (for example, CICS IGNORE globally or NOHANDLE on a call-by-call basis)
  • Data name suffixes generated for field length and attribute data names
  • DFHAID and AMB-EIBRCODE copybook inclusion
  • EJECTs
  • CICS comments
  • CICS call overrides
  • RESP/RESP2 options
Parent topic: Control (CNTL) Files
Related tasks
To turn off the MDT tag
Related reference
APDB2IN
APDLGIN
APIMSIN
APSDBDC
APSPROJ
APVSAMIN


APDB2IN

Controls SQL calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

File Contents:

Edit APDB2IN to control the following for SQL calls:

  • Comment generation; the default generates comments
  • EJECTs
  • Size of SQL calls accepted (default is 200 tokens, for example, items separated by spaces)
  • Generation of the IBM DCLGEN convention, DCLtablename, for host 01-level qualifiers
  • Automatic error processing, controlled by the variable &D2-AUTO-ERROR-HANDliNG (default is ON)
  • Customization of automatic error processing, including:
    • Modifying the AMB error processing paragraph &D2-ERROR-PARA, which resides in the rule $DB2-ERROR-SETUP
    • Modifying which status codes should be considered error conditions, in the rule $DB2-CHECK-RETURNS-AUX, and changing the status of a referential integrity constraint from an abnormal condition to an invalid key
  • The DB-PROCESS call loop limit flag, &DB2-LOOP-liMIT (default is 100); you can change the limit number or disable the check for the limit.
  • COMMIT generation for the DB-MODIFY, DB-STORE, DB-ERASE, and DB-CLOSE calls.
  • DB2 customization exits, which are program locations where you can write your own rules to customize AMB SQL calls.
  • Generated data names. You can:
    • Override the use of the IND-cursorname structure when generating indicator variables
    • Use an 01-level name instead of copylib-REC for DB2 record host-variable qualification
    • Modify generated data names used by $DB2-EPILOGUE, which is invoked after all DB2 calls have been processed
    • Use a table alias name instead of the table name
  • Comment generation for the AMB $DB2- calls, which are used by the SQL calls.
  • SQL Get Diagnostics generation and customization, including:
    • User Exit for adding user logic to handle multiple conditions.
    • Customization of which diagnostics information is returned.
    • Automatic generation of GET DIAGNOSTICS calls after each SQL statement if &D2-AUTO-GET-DIAGNOSTICS is set to YES (default is NO).
    • Macro $DB2-GET-DIAGNOSTICS, which you can customize. Invoke it after any SQL call to get SQL diagnostics information for that call. Indent user logic under $DB2-GET-DIAGNOSTICS for multiple-row condition information that is returned in a loop.
Parent topic: Control (CNTL) Files
Related reference
APCICSIN
APDLGIN
APIMSIN
APSDBDC
APSPROJ
APVSAMIN


APDLGIN

Controls DLG.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

File Contents:

Edit APDLGIN to control the following DLG information:

  • DYNAM or NODYNAM calls
  • VDELETE variables upon TP-TERM
  • TP-LINK and TP-XCTL generation of COBOL CALLs or ISPEXEC SELECTs
  • Automatic open/close for VSAM files (enable/disable)
  • DB2 COMMIT generation for DLG TP-LINK, TP-XCTL, and TP-TERM calls
  • Prologue generation
  • EJECTs
Parent topic: Control (CNTL) Files
Related reference
APCICSIN
APDB2IN
APIMSIN
APSDBDC
APSPROJ
APVSAMIN


APFEIN

Controls field edits
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: APSPROJ controls the output picture of numeric fields

File Contents:

Edit APFEIN to control the following field edit information:

  • Setting the maximum number of input and output edited fields per paragraph. The default is ten input fields and ten output fields. To change the defaults, set the &FE-INP-PARA-BREAK and &FE-OUT-PARA-BREAK variables as desired.
  • Preventing execution of a user-defined input application edit when the field does not pass assigned field edits. The default is No, which continues execution. To prevent execution, set the variable &FE-BYPASS-INPUT-APPL-EDIT to yes.
  • Preventing execution of subsequent input and output field edits if a field fails a user-defined input application edit. The default is No, which continues execution. To prevent execution, set the variables &FE-BYPASS-EDITS-IF-APPL-FAIL and &FE-BYPASS-OUTPUT-EDITS to yes.
  • Using the USA format or European format that reverses the comma and decimal point. The default is the USA format. To use the European format, set the &FE-DECIMAL-IS-COMMA variable to yes.
  • Supporting DBCS (Double Byte Character Set) characters. The default for the &FE-DBCS-ENABLE variable is yes.
  • Allowing spaces within numbers. The default for the $FE-EMB-SPACE-IN-NUMERIC is no.
  • Interpreting the century for output date formats. The default for the &FE-FIRST-YEAR-OF-CENTURY is 50. This means that AMB interprets any date with a YY (year) value of 51 through 99 as being in the 20th century, that is, year 1951 through 1999, and any YY value of 00 through 50 as being in the 21st century, that is, year 2000 through 2050.
  • CICS only. Resetting attribute bytes to the painted values if the field passes all assigned input edits. The default for the &FE-RESET-CICS-ATTRS variable is YES.
  • CICS only. Resetting field attribute bytes before or after input edits. The default for the &FE-RESET-CICS-ATTRS-AT-TOP variable is NO, which means after input edits.
Parent topic: Control (CNTL) Files
Related reference
Fields and Flags for Edit Routines


APHLPIN

Controls User Help
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

File Contents:

Edit APHLPIN to control the following information:

  • Program and screen names (if naming conflicts exists)
  • Internal and external storage database targets
  • Subschema access used by the help database
  • Database name and attributes
  • Database field names--COBOL or native
  • Attribute restoration
  • Screen data storage options
  • Data field length
  • Global screen message field name
  • Field help indicator string
  • Date format
  • PF key designations
  • COBOL help invocation conditions
  • Builder-generated User Help comment suppression
Parent topic: Control (CNTL) Files


APIMSIN

Controls IMS DB calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

File Contents:

Edit APIMSIN to control the following information in IMS DB calls:

  • Prologue generation.
  • EJECTs.
  • Color, Blink, Reverse Video, Underscore switches.
  • System Service Calls (IM-STAT, IM-LOG, IM-ROLL, IM-ROLB).
  • GSAM RSA calls.
  • DB-PROCESS call loop limit flag, &VS-IMS-LOOP-MAX (default 100); you can change the limit number or disable the check for the limit.
  • Generation of calls to the A1MVCL run-time module. The value of the Customizer control variable &CODE-A1MVCL-INLINE controls whether the Customizer generates calls to the A1MVCL run-time module to move blocks of data to a target location from a source location or generates inline COBOL MOVE statements instead.
    Value | Generates
    Not defined | Calls to A1MVCL
    NO | Calls to A1MVCL (default)
    YES | Inline COBOL MOVE statements
    Note: You can specify a value for &CODE-A1MVCL-INLINE in this CNTL file or define &CODE-A1MVCL-INLINE and its value within a program. If you define &CODE-A1MVCL-INLINE and its value within a program, the value specified in the program overrides the value specified in APIMSIN.
Parent topic: Control (CNTL) Files
Related reference
APCICSIN
APDB2IN
APDLGIN
APSDBDC
APSPROJ
APVSAMIN
Run-time Module - A1MVCL


APSDBDC

Controls database and user interface calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Warning: Changing APSDBDC values affects the entire installation. To override values only for a specific Project, set the variables in the CNTL file APSPROJ.

File Contents:

Edit the following APSDBDC variables to control database and user interface calls:

Parameter | Description
% SET NOBLANK | Suppress blank lines from appearing in the output. Override with % SET BLANK.
% SET EVAL- BRACKETS "<>" Define the characters used as evaluation brackets.
Warning: Overriding this parameter is not recommended because it will affect the Customizer rules.
% &MACRO- COMMENTS = 1 | Allows COBOL comments to appear in generated source. Override with 0.
% &TP-MACRO- COMMENTS = 1 | Allows COBOL comments to appear in generated source. Override with 0.
% SET LOOP- LIMIT 500 Limit all loops in APSMACS and USERMACS to 500 executions. Maximum override number is 999999.

Loop limit flags for DB-PROCESS loops are in the target-specific AMB CNTL files.

An error trace mechanism that identifies the line of source that caused the error, the active % INCLUDE statement(s), the rule(s) currently invoked and not yet ended, and the number of loops completed at the time of error (if applicable). The severity codes of errors traced are F (Fatal), E (Error), W (Warning), and I (Information) messages. To eliminate Information message traces, append a space and the argument NOINFO to the trace statement. To turn off the trace in selected portions of a program, code % SET NOTRACE.% SET TRACE ERROR

% &IM-HOLD- DEFAULT = "NOHOLD" | Prevent AMB-generated IMS DB-OBTAIN calls from HOLDing a record for update except when HOLD is specified in the DB-OBTAIN call. Override with "procopt", which does HOLD a record automatically, assuming the subschema or PSB specifies that the program can update the record.
% &VS- PROTOTYPE- MODE = "NO" | "Yes" specifies that a VSAM program is a prototype, enabling you to code DB calls without accessing a VSAM file. All subschema validation at program generation is still performed. NO means prototype mode is inactive.
% &IM- SUPPRESS-DB- CALL = "NO" | Deactivate the prototype mode for an IMS program. "Yes" specifies that an IMS program is a prototype, enabling you to code DB calls without accessing a data base. All subschema validation at program generation is still performed.
% &IM-USE- DFS0AER = 0 | Disable the AMB-supplied IMS database error routine rules from calling the IMS-supplied error display module, DFS0AER. In this case, all database errors are resolved using only the AMB-supplied status flags. To enable use of DSF0AER and the AMB-supplied flags, set to 1. If your installation does not use DFS0AER, leave this flag set to 0. See also Fields, Flags, and Exit Points.
% &GEN-DB- REC-01-NAMES = 0 IMS DB parameter. If your top-level copylib records begin with the level number 01 positioned in column 8, use the flag default of 0. If they don't, override with 1.
Note: Ensure that no 01 level copylibs exists. Otherwise, when flag set to 1, duplicate 01 level names will exist causing a COBOL error.
% &IM- SUPPRESS- COPYLIB = 0 | Override with 1 to suppress a copylib described in your DDI statements. &IM is for IMS; &VS is for VSAM.
% &VS- SUPPRESS- COPYLIB = 0 | Override with 1 to suppress a copylib described in your DDI statements. &IM is for IMS; &VS is for VSAM.
% &COPY- SECTION = "WORKING- STORAGE" | Specify that copylib members are placed in Working-Storage.
% &TP-RETRY = 1 | Set the parameter RETRY as the default parameter for the NTRY call. Override with 0 to set the default to NORETRY. You can also override on a program-by-program basis by coding RETRY or NORETRY in the NTRY call. See NTRY for more information.
% &IM-USE- ASSEMBLER- BLOCKING = 1 Use a supplied Assembler routine to move data between record I/O areas and IMS concatenated segment I/O areas in AMB-generated programs. This method is recommended because it's more efficient and doesn't require redefining the record I/O areas.
Note: Because this module is linked during generation of COBOL code, setting this variable to 1 might interfere with transportability of the generated code.

Overriding with 0 causes AMB-generated programs to block and unblock IMS concatenated I/O areas using a byte-level loop in the generated code. Setting to 0 also causes AMB to automatically redefine all record I/O areas as an array of bytes. Setting to 0 is incompatible with copyfile members containing a COBOL OCCURS DEPENDING ON clause or multiple record declarations in a single member.

% &IM-EXEC- DLI = 0

CICS parameter. Generate CALL 'CBLTDLI' syntax. Override with 1 to generate EXEC DL/I syntax.

Parent topic: Control (CNTL) Files
Related reference
APCICSIN
APDB2IN
APDLGIN
APIMSIN
APSPROJ
APVSAMIN
Fields, Flags, and Exit Points
NTRY


APSPROJ

Controls the output picture of numeric fields.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

File Contents:

Edit APSPROJ to reverse commas and decimal points in the output picture of numeric fields (such as ZZ.ZZZ.ZZ9,99).

Note: After editing APSPROJ, compile the screen and program.
  • Code the following assignment statements in APSPROJ, where membername is the USERMACS member name that contains the $TP-SPECIAL-NAMES rule definition. AMB includes the member for you. The $TP-SPECIAL-NAMES rule generates the DECIMAL-POINT-IS-COMMA statement.
    % &FE-DECIMAL-POINT-IS-COMMA = "YES"

    % &FE-TP-SPECIAL-NAMES-MACMBR =
"TPSPEC"|"membername"

    Then, copy TPSPEC from &SSMAPS..CNTL to &SSMDSN..USERMACS. Modify the $TP-SPECIAL-NAMES rule as desired to generate statements in the SPECIAL-NAMES paragraph.

  • Code the following statement in APSPROJ. The DC target epilogue rule generates the DECIMAL-POINT-IS-COMMA statement.
    % &FE-DECIMAL-POINT-IS-COMMA = "YES"
Parent topic: Control (CNTL) Files
Related reference
APCICSIN
APDB2IN
APDLGIN
APIMSIN
APSDBDC
APVSAMIN
Edit Masks


APVSAMIN

Controls VSAM batch and online.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

File Contents:

Edit APVSAMIN to control VSAM batch and online:

  • Functions for both CICS/VSAM and batch
    • Abnormal error processing (enable/disable automatic AMB routine)
    • Non-referenced record descriptions (include/exclude)
    • Record inclusion
    • A flag to use if your copylib records don't begin with the 01-level number
  • CICS/VSAM-specific functions
    • Abnormal error processing (exclude certain CICS Exceptional Conditions and ISI-Errors from being abnormal conditions)
    • DB-PROCESS call loop limit flag, &VS-CICS-LOOP-MAX (default 100); you can change the limit number or disable the check for the limit.
    • ENDBR/UNLOCK
    • Customization exits, which are program locations where you can write your own rules to customize AMB VSAM and native VSAM calls
    • Data name generation
    • Comment generation
  • Batch-specific functions
    • Abnormal error processing (exclude certain batch conditions from being abnormal conditions)
    • DB-PROCESS call loop limit flag, &VS-MVS-LOOP-MAX (default 999,999); you can change the limit number or disable the limit check.
    • Termination method (STOP RUN or call your own abend program)
    • Customization exits, which are program locations where you can write your own rules to customize VSAM calls
    • Data name generation
    • Comment generation
  • Generation of calls to the A1MVCL run-time module. The value of the Customizer control variable &CODE-A1MVCL-INLINE controls whether the Customizer generates calls to the A1MVCL run-time module to move blocks of data to a target location from a source location or generates inline COBOL MOVE statements instead.
    Value of &CODE-A1MVCL-INLINE | Generates
    Not defined | Calls to A1MVCL
    NO | Calls to A1MVCL (default)
    YES | Inline COBOL MOVE statements
    Note: You can specify a value for &CODE-A1MVCL-INLINE in this CNTL file or define &CODE-A1MVCL-INLINE and its value within a program. If you define &CODE-A1MVCL-INLINE and its value within a program, the value specified in the program overrides the value specified in APVSAMIN.
Parent topic: Control (CNTL) Files
Related reference
APCICSIN
APDB2IN
APDLGIN
APIMSIN
APSDBDC
APSPROJ
Run-time Module - A1MVCL


Customizer/Micro Focus Generator (MFG)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Customizer Symbols
  • Customizer Statements
  • Customizer Rule Examples
  • MFG command
  • MFG Structures
Parent topic: Reference


Customizer Symbols

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Customizer uses the following reserved symbols:

Symbol | Description
% | When % is the first character on a line, it identifies the entire line as a Customizer statement .
& | &variable is a variable. Generally, you code variables in rules and assign values to them in your programs. In addition, you can both define and assign values to variables in your programs. You can use variables in a Customizer statement or embed them in a line of COBOL or S-COBOL.
$ | $rulename is a rule call or, when used with % DEFINE, it is a rule definition statement . Generally, you code rule definitions in your USERMACS files, and rule calls in your programs. You can use a rule call in a Customizer statement or embed one in a line of COBOL or S-COBOL.
+ | &variable+suffix appends a literal suffix to a variable. &columnnumber+source designates the column where the facility processor places source code in the output.
Parent topic: Customizer/Micro Focus Generator (MFG)


Customizer Statements

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Continuation of Customizer Statements

After coding a Customizer symbol, continue Customizer statements on additional lines.

Statement | Continuation Method
Rule call | Break the line after any comma in the argument list and skip to the next line. For AMB programs, code an ellipsis and at least one space (... ); for all other programs, code a percent symbol, an optional space, an ellipsis and at least one space (% ... ).
Rule definition | Break the line after any comma in the argument list; skip to the next line and code a percent symbol, an optional space, an ellipsis, and at least one space (% ... ).
Literal string in a variable assignment statement | For mainframe platforms. Code a hyphen anywhere in the string, skip to the next line and code a percent symbol, space, ellipsis, and at least one space (% ... ). For PC platforms. Break the line anywhere in the string, skip to the next line and code a percent symbol, space, ellipsis, and at least one space (% ... ). Mainframe rules are also acceptable.
All other statements | For mainframe platforms. Break the line after a blank space by coding a hyphen; skip to the next line and code a percent symbol, space, ellipsis, and at least one space (% ... ). For PC platforms. Break the line anywhere in the statement, skip to the next line and code a percent symbol, space, ellipsis, and at least one space (% ... ). Mainframe rules are also acceptable.

Examples

Continue a rule definition
% DEFINE $SAMPLE-RULE( &ARG1, &ARG2, &ARG3,
% ... &ARG4)
Continue a rule call in a AMB program
$TABLE-MAKER( 3, 4, 'ENTRY', 'ITEM',
... 'X(4) VALUE SPACES')
Continue a rule call in a non-AMB program
$TABLE-MAKER( 3, 4, 'ENTRY', 'ITEM',
% ... 'X(4) VALUE SPACES')
Continue a literal string variable value
% &VARIABLE = 'THIS WORKS-
% ... FINE'
% &VARIABLE = 'THIS WORKS FI-
% ... NE TOO'
Continue other statements
% REPEAT VARYING &IM-TARG FROM -
% ... 1 TO 20
% IF &APS-IDENT < 8 -
% ... OR &APS-INDENT > 11
Parent topic: Customizer/Micro Focus Generator (MFG)


Customizer Rule Examples

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following are examples of Customizer Rules:

  • Example - Invoking Rules
    The following example shows two sample user rules - $CONSTRUCT-FD and $DAYDEF - and how a program invokes and uses them. To illustrate how AMB processes rules, we show the program at the following two stages of generation.
  • Example - % IF Structure
    The % IF structure builds a program that tests records for any specific character and replaces some occurrences of it with any other specific character, depending on the character mode, for example, whether the character appears as a leading or trailing character, or anywhere. The variables that control the record length and what you search and replace, appear at the top of the program. Thus, you can reuse this rule for different purposes simply by changing the values of a few variables.
  • Example - Looping
    This program calls two user rules that create a data structure with loops. A loop that incorporates built-in functions returns a value to text.
  • Example - MFG Structures
    This examples shows a Customizer rule written with several MFG structures.
  • Example - Program Location Statements
    This example illustrates program location statements and in-line rules. In addition to showing rules, program input, and Customizer output, this example goes a step further and shows the program after AMB precompiler processing.
  • Example - Rule Compilation Report
    The appearance of OPEN_CODE in the report refers to the outermost level of code within a file of rules, such as code outside of any % DEFINEs or % SUBMEMBERs.
Parent topic: Customizer/Micro Focus Generator (MFG)


Example - Invoking Rules

The following example shows two sample user rules - $CONSTRUCT-FD and $DAYDEF - and how a program invokes and uses them. To illustrate how AMB processes rules, we show the program at the following two stages of generation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Before AMB inserts the rule source in the program. The program at this stage is stored in the GENSRC directory or data set in your Project and Group.
  • After AMB inserts the rule source in the executable COBOL program.

The rules are defined in a USERMACS file. The $CONSTRUCT-FD rule writes FD statements. The program calls the rule and passes arguments--the FD file names--to the FD file name variable in the rule. The $DAYDEF rule builds a Working-Storage symbol table. The program repeatedly calls the rule and passes arguments--literal strings and their lengths--to the string and length variables in the rule.

User-defined rules:

% DEFINE $CONSTRUCT-FD( &FILE-NAME)
    FD  &FILE-NAME
        BLOCK CONTAINS 0 RECORDS
        LABEL RECORDS ARE STANDARD.
% END

% DEFINE $DAYDEF( &DAY, &LEN)
    % &DAYCTR = &DAYCTR + 1
    02  FILLER.
      03  FILLER          PIC S9(2) COMP SYNC VALUE +&LEN.
      03  FILLER          PIC X(9) VALUE &QT&DAY&QT.
% END

Program before rule source:

 % &REC-LEN = 121                                     315.
 % &DAYCTR = 0                                        316.
 % &QT = "'"                                          317.
                                                      318.
 IDENTIFICATION DIVISION.                             319.
 PROGRAM-ID.                     EXAMPLE3.            320.
*SPECIAL CONSIDERATIONS.                              321.
*    SAMPLE PROGRAM: CALLS TO RULES THAT WRITE        322.
*    AN FD STATEMENT AND BUILD A TABLE.               323.
                                                      324.
 ENVIRONMENT DIVISION.                                325.
 INPUT-OUTPUT SECTION.                                326.
 FILE-CONTROL.                                        327.
 SELECT INPUT-FILE           ASSIGN "INPUT".          328.
 SELECT OUTPUT-FILE          ASSIGN "OUTPUT".         329.
                                                      330.
 DATA DIVISION.                                       331.
 FILE SECTION.                                        332.
                                                      333.
 $CONSTRUCT-FD( 'INPUT-FILE')                         334.
 01  INPUT-RECORD                PIC X(&REC-LEN).     335.
                                                      336.
 $CONSTRUCT-FD( 'OUTPUT-FILE')                        337.
 01  OUTPUT-RECORD               PIC X(&REC-LEN).     338.
 WORKING-STORAGE SECTION.                             340.
                                                      341.
 01  DAY-TABLE.                                       342.
   $DAYDEF( 'SUNDAY', 6)                              343.
   $DAYDEF( 'MONDAY', 6)                              344.
   $DAYDEF( 'TUESDAY', 7)                             345.
   $DAYDEF( 'WEDNESDAY', 9)                           346.
   $DAYDEF( 'THURSDAY', 8)                            347.
   $DAYDEF( 'FRIDAY', 6)                              348.
   $DAYDEF( 'SATURDAY', 8)                            349
 01  DAY-TABLE-REDEF   REDEFINES DAY-TABLE            350.
   02  DAY-ENTRY   OCCURS &DAYCTR.                    351.
     03  DAY-LEN   PIC S9(2) COMP SYNC.               352.
     03  DAY-BOL   PIC X(9).                          353.

Program after rule source:

030200                                                315
030800                                                316.
031100                                                317.
031800                                                318.
031900 IDENTIFICATION DIVISION.                       319.
032000 PROGRAM-ID.                     EXAMPLE3.      320.
032100*SPECIAL CONSIDERATIONS.
321.
032200*    SAMPLE PROGRAM: CALLS TO RULES THAT WRITE  322.
032300*    AN FD STATEMENT AND BUILD A TABLE          323.
032400                                                324.
032500 ENVIRONMENT DIVISION.                          325.
032600 INPUT-OUTPUT SECTION.                          326.
032700 FILE-CONTROL.                                  327.
032800 SELECT INPUT-FILE      ASSIGN "INPUT".         328.
032900 SELECT OUTPUT-FILE     ASSIGN "OUTPUT".        329.
033000                                                330.
033100 DATA DIVISION.                                 331.
033200 FILE SECTION.                                  332.
033300                                                333.
033400 FD  INPUT-FILE                                 334.
033402     BLOCK CONTAINS 0 RECORDS                   334.
033404     LABEL RECORDS ARE STANDARD.                334.
033500 01  INPUT-RECORD                PIC X(121).    335.
033600                                                336.
033700 FD  OUTPUT-FILE                                337.
033702     BLOCK CONTAINS 0 RECORDS                   337.
033704     LABEL RECORDS ARE STANDARD.                337.
033800 01  OUTPUT-RECORD               PIC X(121).    338.
033900                                                339.
034000 WORKING-STORAGE SECTION.                       340.
034100                                                341.
034200 01  DAY-TABLE.                                 342.
034300   02  FILLER.                                  343.
034302     03  FILLER   PIC S9(2) COMP SYNC VALUE +6. 343.
034304     03  FILLER   PIC X(9)  VALUE 'SUNDAY'.     343.
034400   02  FILLER.                                  344.
034402     03  FILLER   PIC S9(2) COMP SYNC VALUE +6. 344.
034404     03  FILLER   PIC X(9)  VALUE 'MONDAY'.     344.
034500   02  FILLER.                                  345.
034502     03  FILLER   PIC S9(2) COMP SYNC VALUE +7. 345.
034504     03  FILLER   PIC X(9)  VALUE 'TUESDAY'.    345.
034600   02  FILLER.                                  346.
034602     03  FILLER   PIC S9(2) COMP SYNC VALUE +9. 346.
034604     03  FILLER   PIC X(9)   VALUE 'WEDNESDAY'. 346.
034700   02  FILLER.                                  347.
034702     03  FILLER   PIC S9(2) COMP SYNC VALUE +8. 347.
034704     03  FILLER   PIC X(9)  VALUE 'THURSDAY'.   347.
034800   02  FILLER.                                  348.
034802     03  FILLER   PIC S9(2) COMP SYNC VALUE +6. 348.
034804     03  FILLER   PIC X(9)  VALUE 'FRIDAY'.     348.
034900   02  FILLER.                                  349.
034902     03  FILLER   PIC S9(2) COMP SYNC VALUE +8. 349.
034904     03  FILLER   PIC X(9)VALUE 'SATURDAY'.     349.
035000 01  DAY-TABLE-REDEF   REDEFINES DAY-TABLE.     349.
035100   02  DAY-ENTRY  OCCURS 7.                     351.
035200     03  DAY-LEN  PIC S9(2) COMP SYNC.          352.
035300     03  DAY-BOL  PIC X(9).                     353.
Parent topic: Customizer Rule Examples


Example - % IF Structure

The % IF structure builds a program that tests records for any specific character and replaces some occurrences of it with any other specific character, depending on the character mode, for example, whether the character appears as a leading or trailing character, or anywhere. The variables that control the record length and what you search and replace, appear at the top of the program. Thus, you can reuse this rule for different purposes simply by changing the values of a few variables.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Input source:

 % &MODE = 'TRAILING'                                      201.
 % &REC-LEN =121                                           202.
 % &TEST-CHR = 'SPACE'                                     203.
 % &REPLACE-CHR = 'ZERO'                                   204.
 IDENTIFICATION DIVISION.                                  205.
 PROGRAM-ID.                     EXAMPLE2.                 206.
*SPECIAL CONSIDERATIONS.                                   207.
* SAMPLE PROGRAM TO READ RECS WHOSE LENGTH IS DETERMINED   208.
* AT COMPILE-TIME & REPLACE SOME OCCURRENCES OF TEST-CHR   209.
* BY THE REPLACE-CHR (BOTH TO BE SET AT COMPILE-TIME).     210.
* REPLACEMENT MODE USED (LEADING, TRAILING, OR ALL)        211.
* IS SET AT COMPILE-TIME.                                  212.
                                                           213.
 ENVIRONMENT DIVISION.                                     214.
 INPUT-OUTPUT SECTION.                                     215.
 FILE-CONTROL.                                             216.
 SELECT INPUT-FILE           ASSIGN "INPUT".               217.
 SELECT OUTPUT-FILE          ASSIGN "OUTPUT".              218.
                                                           219.
 DATA DIVISION.                                            220.
 FILE SECTION.                                             221.
                                                           222.
 FD  INPUT-FILE                                            223.
     BLOCK CONTAINS 0 RECORDS                              224.
     LABEL RECORDS ARE STANDARD.                           225.
 01  INPUT-RECORD                PIC X(&REC-LEN).          226.
                                                           227.
 FD  OUTPUT-FILE                                           228.
     BLOCK CONTAINS 0 RECORDS                              229.
     LABEL RECORDS ARE STANDARD.                           230.
 01  OUTPUT-RECORD               PIC X(&REC-LEN).          231.
                                                           232.
 WORKING-STORAGE SECTION.                                  233.
                                                           234.
 01  WS-RECORD.                                            235.
   02  WS-CHR                   PIC X OCCURS &REC-LEN.     236.
                                                           237.
 01  II                          PIC S9(4) COMP-5.         238.
                                                           239.
 PROCEDURE DIVISION.                                       240.
                                                           241.
 OPEN INPUT INPUT-FILE                                     242.
 OPEN OUTPUT OUTPUT-FILE                                   243.
                                                           244.
 REPEAT                                                    245.
     READ INPUT-FILE INTO WS-RECORD                        246.
 UNTIL AT END ON INPUT-FILE                                247.
     % IF &MODE = 'LEADING'                                248.
         REPEAT VARYING II FROM 1 BY 1                     249.
         UNTIL II > &REC-LEN                               250.
         ... OR WS-CHR (II) NOT = &TEST-CHR                251.
             WS-CHR (II) = &REPLACE-CHAR                   252.
     % ELSE-IF &MODE = 'TRAILING'                          253.
         REPEAT VARYING II FROM &REC-LEN BY -1             254.
         UNTIL II < 1                                      255.
         ... OR WS-CHR (II) NOT = &TEST-CHR                256.
             WS-CHR (II) = &REPLACE-CHAR                   257.
     % ELSE-IF &MODE = 'ALL'                               258.
         REPEAT VARYING II FROM 1 BY 1                     259.
         UNTIL II > &REC-LEN                               260.
             IF WS-CHR (II) = &TEST-CHR                    261.
                 WS-CHR (II) = &REPLACE-CHAR               262.
     % ELSE                                                263.
         DISPLAY "PARAMETER ERROR IMPROPER MODE:" &MODE    264.
                                                           265.
     WRITE OUTPUT-RECORD FROM WS-RECORD                    266.
                                                           267.
 CLOSE INPUT-FILE OUTPUT-FILE                              268.

Output source:

020500 IDENTIFICATION DIVISION.                            205.
020600 PROGRAM-ID.                     EXAMPLE2.           206.
020700*SPECIAL CONSIDERATIONS.                             207.
020800* PROGRAM TO READ RECS WHOSE LENGTH IS DETERMINED AT 208.
020900* COMPILE-TIME & REPLACE SOME OCCURRENCES OF TEST-CHR209.
021000* BY REPLACE-CHR (BOTH TO BE SET AT COMPILE-TIME).   210.
021100* REPLACEMENT MODE USED (LEADING, TRAILING OR ALL)   211.
021200* IS SET AT COMPILE-TIME.                            212.
021300                                                     213.
021400 ENVIRONMENT DIVISION.                               214.
021500 INPUT-OUTPUT SECTION.                               215.
021600 FILE-CONTROL.                                       216.
021700 SELECT INPUT-FILE           ASSIGN "INPUT".         217.
021800 SELECT OUTPUT-FILE          ASSIGN "OUTPUT".        218.
021900                                                     219.
022000 DATA DIVISION.                                      220.
022100 FILE SECTION.                                       221.
022200                                                     222.
022300 FD  INPUT-FILE                                      223.
022400     BLOCK CONTAINS 0 RECORDS                        224.
022500     LABEL RECORDS ARE STANDARD.                     225.
022600 01  INPUT-RECORD                PIC X(121).         226.
022700                                                     227.
022800 FD  OUTPUT-FILE                                     228.
022900     BLOCK CONTAINS 0 RECORDS                        229.
023000     LABEL RECORDS ARE STANDARD.                     230.
023100 01  OUTPUT-RECORD               PIC X(121).         231.
023200                                                     232.
023300 WORKING-STORAGE SECTION.                            233.
023400                                                     234.
023500 01  WS-RECORD.                                      235.
023600   02  WS-CHR                    PIC X OCCURS 121.   236.
023700                                                     237.
023800 01  II                          PIC S9(4) COMP-5.   238.
023900                                                     239.
024000 PROCEDURE DIVISION.                                 240.
024100                                                     241.
024200     OPEN INPUT INPUT-FILE                           242.
024300     OPEN OUTPUT OUTPUT-FILE                         243.
024400                                                     244.
024500     REPEAT                                          245.
024600         READ INPUT-FILE INTO WS-RECORD              246.
024700     UNTIL AT END ON INPUT-FILE                      247.
025400         REPEAT VARYING II FROM 121 BY -1            254.
025500         UNTIL II < 1                                255.
025600         ... OR WS-CHR (II) NOT = SPACE              256.
025700             WS-CHR (II) = ZERO                      257.
026600         WRITE OUTPUT-RECORD FROM WS-RECORD          266.
026700                                                     267.
026800     CLOSE INPUT-FILE OUTPUT-FILE                    268.

Discussion:

Lines 201 - 204:

  • Input - Variables are assigned values and are used in the Procedure Division to replace any trailing space with a zero.

Lines 245-247 and 266-268:

  • Input - The S-COBOL REPEAT verb establishes a loop that can be tested at the middle or end. The statement blocks subordinate to REPEAT and UNTIL form the loop and are executed repeatedly until the condition specified by the UNTIL statement is true, for example, until the end of file. At end of file, processing continues at line 268 After line 268, S-COBOL generates a STOP RUN.
  • Output - These lines are copied into the output source because they contain no Customizer syntax.

Lines 253-257:

  • Input - This statement block is executed because &MODE was assigned the value 'TRAILING' at the top of the program. REPEAT VARYING ... UNTIL ... is an extension of the S-COBOL REPEAT verb. It establishes a test and executes its subordinate statement block repeatedly until the test is true.
  • Output - Line 253 does not appear in the output because it is a Customizer statement. The other lines do appear. The variables &REC-LEN, &TEST-CHR, and &REPLACE-CHR are resolved with their values 121, SPACE, and ZERO. The loop starts at the 121st character, is decrements by 1; it executes line 257 until a trailing character appears that is not a space, or until all 121 characters are tested.

Lines 263-265:

  • Input - If &MODE is neither LEADING, TRAILING, or ALL, control falls to this % ELSE statement and displays an error message.
  • Output - Note that input line 265 is blank. It does not appear in the output because it is considered part of the statement block subordinate to % ELSE. Remember that a statement block ends with the first non-blank character at the same or less indentation than the controlling conditional statement. To get the blank line to appear in the output, end the conditional structure by inserting a line beneath line 264 and coding % END at the same indentation as % ELSE; then, leave the next line blank.
Parent topic: Customizer Rule Examples


Example - Looping

This program calls two user rules that create a data structure with loops. A loop that incorporates built-in functions returns a value to text.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

User rules:

%* HERE ARE TWO RULES: $ITEM-MAKER AND $TABLE-MAKER        601.
                                                           602.
 % DEFINE $ITEM-MAKER( &MM, &DATANAME, &TAIL)              603.
     % &II = 1                                             604.
     % WHILE &II <= &MM                                    605.
         02  &DATANAME+-&II      &40+PIC &TAIL.            606.
         % &II = &II + 1                                   607.
 % END                                                     608.
                                                           609.
 % DEFINE $TABLE-MAKER( &MM, &NN, &TNAME, &INAME, &TAIL)   610.
     % &II = 1                                             611.
     % WHILE &II <= &MM                                    612.
         02  &TNAME+-&II.                                  613.
         % &JJ = 1                                         614.
         % UNTIL &JJ > &NN                                 615.
             % BEGIN                                       616.
               03  &INAME+-&II+-&JJ &40+PIC &TAIL.         617.
             % &JJ = &JJ + 1                               618.
         % &II = &II + 1                                   619.
 % END                                                     620.
                                                           621.

Lines 603-608:

The rule $ITEM-MAKER has three formal arguments; the rule call on line 634 supplies the values. % WHILE starts a loop that executes repeatedly while the value of &II is <= to the value of &MM. The loop generates the 02 TEST-ITEM data elements (see line 634 under Program output).

Note the two uses of the plus symbol in line 606. Used in &DATANAME+-&II, the plus concatenates the two variables, resulting in TEST-ITEM-1 for the first data item. On the next line, &II increments by one during each loop, resulting in TEST-ITEM-2 for the second data item, etc. The second use for the plus symbol places the value of PIC &TAIL in column 40 of the output for each TEST-ITEM.

Lines 610-620:

The rule $TABLE-MAKER has five formal arguments whose values are supplied by the rule call in the program on line 635.

% WHILE starts an outer loop that repeatedly executes lines 613-619 while the &II <= &MM. The outer loop generates the 02 data elements ENTRY-1, ENTRY-2, and ENTRY-3.

& UNTIL starts a nested, inner loop. Its subordinate statement block (lines 616-618) executes repeatedly until &JJ > &NN. The inner loop generates the 03 data elements for the outer loop 02s.

% BEGIN places the 03 data items in the output shifted left four spaces in the inner loop, so that they are indented two spaces from the 02 data items. Without % BEGIN, they would have the same indentation as the 02s. The whole outer and inner loop structure shifts as a unit, thus all lines retain their relative positioning.

Line 618 increments the inner loop variable &JJ. Line 619 increments the outer loop variable &II; to be part of the outer loop, it must be indented from the outer loop but not from the inner loop. The loops generate the multiple lines; output from both loops appear in lines 634-635.

Program input:

 % SET BLANK                                               622.
 IDENTIFICATION DIVISION.                                  623.
 PROGRAM-ID.                     EXAMPLE6.                 624.
*SPECIAL CONSIDERATIONS.                                   625.
*    DEMONSTRATE LOOPING.                                  626.
                                                           627.
       ---------------------------------------             628.
       ---------------------------------------             629.
                                                           630.
 WORKING-STORAGE SECTION.                                  631.
                                                           632.
 01  TEST-RECORD.                                          633.
   $ITEM-MAKER( 12,'TEST-ITEM','S9(9) COMP SYNC VALUE -1') 634.
   $TABLE-MAKER( 3, 4,'ENTRY','ITEM' 'X(4) VALUE SPACES')  635.
 % &STR = 'MISSISSIPPI'                                    637.
 % &SUB = 'IS'                                             638.
 % &II = 0                                                 639.
 % REPEAT                                                  640.
     % &JJ = &INDEX( &STR, &SUB)                           641.
 % UNTIL &JJ = 0                                           642.
     % &II = &II + 1                                       643.
     % &JJ = &JJ + &LENGTH( &SUB)                          644.
     % &STR = &SUBSTR( &STR, &JJ)                          645.
 THE NUMBER OF 'IS' IN 'MISSISSIPPI' IS &II.               646.
                                                           647.

Line 622:

% SET BLANK makes all blank lines that follow appear in the output.

Lines 637-646:

The % REPEAT and % UNTIL structures use the built-in functions &INDEX, &LENGTH, and &SUBSTR to find the number of occurrences of the substring IS in the literal string MISSISSIPPI. Lines 641-645 execute repeatedly until &JJ = 0.

Program output:

062300 IDENTIFICATION DIVISION.                             623.
062400 PROGRAM-ID.                     EXAMPLE6.            624.
062500*SPECIAL CONSIDERATIONS.                              625.
062600*    DEMONSTRATE LOOPING.                             626.
062700                                                      627.
062800     -----------------------------------              628.
062900     -----------------------------------              629.
063000                                                      630.
063100 WORKING-STORAGE SECTION.                             631.
063200                                                      632.
063300 01  TEST-RECORD.                                     633.
063400   02  TEST-ITEM-1      PIC S9(9) COMP SYNC VALUE -1. 634.
063402   02  TEST-ITEM-2      PIC S9(9) COMP SYNC VALUE -1. 623.
063404   02  TEST-ITEM-3      PIC S9(9) COMP SYNC VALUE -1. 634.
063406   02  TEST-ITEM-4      PIC S9(9) COMP SYNC VALUE -1. 634.
063408   02  TEST-ITEM-5      PIC S9(9) COMP SYNC VALUE -1. 634.
063410   02  TEST-ITEM-6      PIC S9(9) COMP SYNC VALUE -1. 634.
063412   02  TEST-ITEM-7      PIC S9(9) COMP SYNC VALUE -1. 634.
063414   02  TEST-ITEM-8      PIC S9(9) COMP SYNC VALUE -1. 634.
063416   02  TEST-ITEM-9      PIC S9(9) COMP SYNC VALUE -1. 634.
063418   02  TEST-ITEM-10     PIC S9(9) COMP SYNC VALUE -1. 634.
063420   02  TEST-ITEM-11     PIC S9(9) COMP SYNC VALUE -1. 634.
063422   02  TEST-ITEM-12     PIC S9(9) COMP SYNC VALUE -1. 634.
063500   02  ENTRY-1.                                       635.
063502     03  ITEM-1-1       PIC X(4) VALUE SPACES.        635.
063504     03  ITEM-1-2       PIC X(4) VALUE SPACES.        635.
063506     03  ITEM-1-3         PIC X(4) VALUE SPACES.      635.
063508     03  ITEM-1-4         PIC X(4) VALUE SPACES.      635.
063510   02  ENTRY-2.                                       635.
063512     03  ITEM-2-1         PIC X(4) VALUE SPACES.      635.
063514     03  ITEM-2-2         PIC X(4) VALUE SPACES.      635.
063516     03  ITEM-2-3         PIC X(4) VALUE SPACES.      635.
063518     03  ITEM-2-4         PIC X(4) VALUE SPACES.      635.
063520   02  ENTRY-3.                                       635.
063522     03  ITEM-3-1         PIC X(4) VALUE SPACES.      635.
063524     03  ITEM-3-2         PIC X(4) VALUE SPACES.      635.
063526     03  ITEM-3-3         PIC X(4) VALUE SPACES.      635.
063528     03  ITEM-3-4         PIC X(4) VALUE SPACES.      635.
063600                                                      636.
064600 THE NUMBER OF 'IS' IN 'MISSISSIPPI' IS 2.            646.
064700                                                      647.
Parent topic: Customizer Rule Examples


Example - MFG Structures

This examples shows a Customizer rule written with several MFG structures.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

User rule:

 %* HERE IS THE RULE $DAYDEF                                501.
                                                            502.
 % DEFINE $DAYDEF( &DAY)                                    506.
     % &PREFIX = &SUBSTR( &DAY, 1, 24)                      507.
     % &CHR = &SUBSTR( &PREFIX, 24)                         508.
     % IF &CHR = '-'                                        509.
         % &PREFIX = &SUBSTR( &PREFIX, 1, 23)               510.
     % &SUFFIX = '-ENTRY'                                   511.
     % &DAYCTR = &DAYCTR + 1                                512.
     02  &PREFIX&SUFFIX.                                    513.
       03  FILLER &40+PIC S9(2) COMP SYNC VALUE +&LENGTH( &DAY).
       % IF &LENGTH( &DAY) <= 16                            515.
         03  FILLER &40+PIC X(30) VALUE &QT&DAY&QT.         516.
       % ELSE                                               517.
         03  FILLER &40+PIC X(30) VALUE                     518.
                    &40+&QT&DAY&QT.                         519.
 % END                                                      520.
                                                            521.

All Lines:

The $DAYDEF rule uses the structures &SUBSTR and &LENGTH to build a data structure for a table. For each table entry, $DAYDE builds an 02-level data name and provides the values for the two 03-level entries VALUE clauses that follow it. The 02-level data name construct is &PREFIX&SUFFIX.

The value of &PREFIX is supplied by the formal argument &DAY, which receives its value from a rule call to $DAYDEF. For example, the first rule call in the program gives the value SUNDAY to &DAY. The structure &SUBSTR checks this value and allows acceptance of up to 24 characters; values longer than 24 characters are truncated. On the next line, &SUBSTR checks to see whether the 24th character (if there is one) is a hyphen. If it is a hyphen, it uses only 23 characters; this prevents a double hyphen, which would be undesirable; for example, you don't want a hyphen from the name followed by the hyphen of the suffix -ENTRY. SUNDAY is only 6 characters long, so the entire value is accepted for &PREFIX. Thus, the value of &PREFIX&SUFFIX for the first call is SUNDAY-ENTRY.

Now, $DAYDEF provides the VALUE clause values for the two 03-level data elements of SUNDAY-ENTRY. In the first 03 element, VALUE +&LENGTH( &DAY) becomes VALUE +6 because the value of &DAY, which is SUNDAY, is 6 characters long. The plus symbol is recognized as the COBOL plus symbol because there is a space before it. In contrast, the plus symbol in &40+PIC is recognized as a Customizer column indicator, which in this case means to put the PIC clause in column 41.

Line 515 checks to see whether the &DAY values fit on one line; for example, if they are 16 characters maximum. If it fits, its format is like line 516; remember that the line shifts under the % IF statement during processing. If it cannot fit, its format is the 2-line format on lines 518-519.

The value of &SUFFIX for each rule call is the literal string -ENTRY.

Program input:

 % &DAYCTR = 0                                              522.
 % &QT = "'"                                                523.
                                                            524.
 % SET BLANK                                                525.
 IDENTIFICATION DIVISION.                                   526.
 PROGRAM-ID.              EXAMPLE&INDEX( 'ABCDEFG', 'EF').  527.
 DATE-COMPILED.              &COMPILETIME.                  528.
*SPECIAL CONSIDERATIONS.                                    529.
*    A PIECE OF A SAMPLE PROGRAM TO DEMONSTRATE SOME        530.
*    OF THE SOURCE CODE GENERATOR STRUCTURES.               531.
                                                            532.
     --                                                     533.
     --                                                     534.
                                                            535.
 WORKING-STORAGE SECTION.                                   536.
                                                            537.
 01  DAY-TABLE.                                             538.
   $DAYDEF( 'SUNDAY')                                       539.
   $DAYDEF( 'MONDAY')                                       540.
   $DAYDEF( 'TUESDAY')                                      541.
   $DAYDEF( 'WEDNESDAY')                                    542.
   $DAYDEF( 'THURSDAY')                                     543.
   $DAYDEF( 'FRIDAY')                                       544.
   $DAYDEF( 'A-LARGE-SYMBOL-TO-CHECK-DAYDEF')               545.
 01  DAY-TABLE-REDEF             REDEFINES DAY-TABLE.       546.
   02  DAY-ENTRY                 OCCURS &DAYCTR.            547.
     03  DAY-LEN                 PIC S9(2) COMP SYNC.       548.
     03  DAY-BOL                 PIC X(30).                 549.
                                                            550.
 PROCEDURE DIVISION.                                        551.
                                                            552.
     --                                                     553.
     --                                                     554.

Lines 527-528:

&INDEX returns a number identifying the character position of the first occurrence of EF within ABCDEFG. The number is 5; thus, EXAMPLE&INDEX 'ABCDEFG', 'EF') becomes EXAMPLE5.

&COMPILETIME returns the current date and time each time the program compiles.

Lines 539-545:

These are seven rule calls to $DAYDEF, each providing a value for the &DAY argument in $DAYDEF.

Line 547:

The OCCURS clause value is initialized to 0 at the top of the program, and is used in $DAYDEF.

Program output:

052300 IDENTIFICATION DIVISION.                            526.
052400 PROGRAM-ID.                 EXAMPLE5.               527.
052500 DATE-COMPILED.              22 OCT 79 14.24.00.     528.
052600*SPECIAL CONSIDERATIONS.                             529.
052700*    A PIECE OF A SAMPLE PROG TO DEMONSTRATE SOME OF 530.
052800*    THE SOURCE CODE GENERATOR STRUCTURES.           531.
052900                                                     532.
053000     --                                              533.
053100     --                                              534.
053200                                                     535.
053300 WORKING-STORAGE SECTION.                            536.
053400                                                     537.
053500 01  DAY-TABLE.                                      538.
053600   02  SUNDAY-ENTRY.                                 539.
053602     03  FILLER        PIC S9(2) COMP SYNC VALUE +6  539.
053604     03  FILLER        PIC X(30) VALUE 'SUNDAY'.     539.
053700   02  MONDAY-ENTRY.                                 540.
053702     03  FILLER        PIC S9(2) COMP SYNC VALUE +6. 540.
053704     03  FILLER        PIC X(30) VALUE 'MONDAY'.     540.
053800   02  TUESDAY-ENTRY.                                541.
053802     03  FILLER        PIC S9(2) COMP SYNC VALUE +7. 541.
053804     03  FILLER        PIC X(30) VALUE 'TUESDAY'.    541.
053900   02  WEDNESDAY-ENTRY                               542.
053902     03  FILLER        PIC S9(2) COMP SYNC VALUE +9. 542.
053904     03  FILLER        PIC X(30) VALUE 'WEDNESDAY'.  542.
054000   02  THURSDAY-ENTRY.                               543.
054002     03  FILLER        PIC S9(2) COMP SYNC VALUE +8. 543.
054004     03  FILLER        PIC X(30) VALUE 'THURSDAY'.   543.
054100   02  FRIDAY-ENTRY.                                 544.
054102     03  FILLER        PIC S9(2) COMP SYNC VALUE +6. 544.
054104     03  FILLER        PIC X(30) VALUE 'FRIDAY'.     544.
054200   02  A-LARGE-SYMBOL-TO-CHECK-ENTRY.                545.
054202     03  FILLER        PIC S9(2) COMP SYNC VALUE +30.545.
054204     03  FILLER        PIC X(30) VALUE               545.
054206                    'A-LARGE-SYMBOL-TO-CHECK-DAYDEF'.545.
054300 01  DAY-TABLE-REDEF      REDEFINES DAY-TABLE.       546.
054400   02  DAY-ENTRY          OCCURS 7.                  547.
054500     03  DAY-LEN          PIC S9(2) COMP SYNC.       548.
054600     03  DAY-BOL          PIC X(30).                 549.
054700                                                     550.
054800 PROCEDURE DIVISION.                                 551.
054900                                                     552.
055000     --                                              553.
055100     --                                              554.
Parent topic: Customizer Rule Examples


Example - Program Location Statements

This example illustrates program location statements and in-line rules. In addition to showing rules, program input, and Customizer output, this example goes a step further and shows the program after AMB precompiler processing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

User rules:

 1.            % DEFINE $IN-LINE( &ARG)
 2.                COUNTER = &ARG
 3.                % &IN-LINE = &ARG
 4.            % END
 5.            % DEFINE $MY-EPILOGUE
 6.               % * MARK COLUMN 7 MARGIN
 7.                % SET LINKAGE
 8.                01  MY-EPILOGUE-CHR        &40+PIC X.
 9.                % SET PROCEDURE
10.                    COUNTER = 100
11.                % SET EPILOGUE $SECOND-EPILOGUE
12.            % DEFINE $SECOND-EPILOGUE
13.               % BEGIN
14.                    COUNTER = 101
15.            % SET EPILOGUE $MY-EPILOGUE

Lines 1-14:

Three rules are defined-- $IN-LINE, $MY-EPILOGUE, and $SECOND-EPILOGUE.

Line 15:

% SET EPILOGUE $MY-EPILOGUE automatically invokes $MY-EPILOGUE at the very end of the program (after line 63).

Program input:

16.            % SET EVAL-BRACKETS "<>"
17.            IDENTIFICATION DIVISION.
18.            PROGRAM-ID.
19.                                          EXAMPLE9.
20.            ENVIRONMENT DIVISION.
21.            INPUT-OUTPUT SECTION.
22.            FILE-CONTROL.
23.                SELECT YOUR-FILE      ASSIGN UT-S-YOURFILE.
24.            DATA DIVISION.
25.            FILE SECTION.
26.            FD  YOUR-FILE.
27.            01  YOUR-RECORD                 PIC X(80).
28.            WORKING-STORAGE SECTION.
29.            01  COUNTER                     PIC S9(4) COMP.
30.            01  WS-1                        PIC X.
31.            % SET END-WORKING-STORAGE
32.           * PLACE FOR STUFF THAT MUST BE AT END OF WS FOR
33.           * CERTAIN NON-BUILDER PRE-PROCESSORS.
34.            PROCEDURE DIVISION.
35.                COUNTER = 1
36.                $IN-LINE( 2)
37.                TEST-NO-DELIMITERS = <$IN-LINE( 3)>
38.                ADD <$IN-LINE( 4)> <$IN-LINE( 5)> TO COUNTER
39.            % SET LINKAGE
40.            01  LINKAGE-STUFF              PIC X.
41.            % SET PROCEDURE
42.            % SET DELIMITERS-OPTIONAL
43.                $IN-LINE( TEST-NO-DELIMITERS)
44.                $IN-LINE( 6)
45.            % SET DATA
46.           * PLACING DATA IN DATA DIVISION
47.            % SET PROCEDURE
48.            % SET FILE
49.            FD  MY-FILE.
50.            01  MY-RECORD                  PIC X(80).
51.            % SET PROCEDURE
52.            % SET FILE-CONTROL
53.                SELECT MY-FILE         ASSIGN UT-S-MYFILE.
54.            % SET PROCEDURE
55.                OPEN INPUT MY-FILE YOUR-FILE
56.                CLOSE MY-FILE YOUR-FILE
57.            % SET WORKING-STORAGE
58.            01  TEST-NO-DELIMITERS          PIC 9(&IN-LINE).
59.            % SET PROCEDURE
60.            /* THIS IS AN S-COBOL COMMENT LINE.
61.            % SET AUXILIARY-OUTPUT
62.            THIS IS AUXILIARY FILE DATA
               /*************************************
63.            % SET NORMAL-OUTPUT

Line 31:

This is a marker for the code on line 58 that is relocated to WORKING-STORAGE; it goes immediately above this marker.

Line 36:

$IN-LINE is invoked, passing the actual argument 2 to the rule formal argument &ARG. The result appears in output line 6306 (COUNTER = 2).

Line 37:

First, the contents of the evaluation brackets are evaluated. The brackets contain a call to the $IN-LINE rule, passing the argument 3 to the rule argument &ARG. This calls the rule; the result appears in output line 6308 (COUNTER = 3).

Next, the contents of the brackets are resolved, giving TEST-NO-DELIMITERS a value. The value comes from a variable within $IN-LINE, which must have same name as the rule it belongs to, and its value is the same as the argument passed to the rule, for example, 3. Thus, <$IN-LINE( 3)> is replaced by 3, and TEST-NO-DELIMITERS = 3 is output to line 6310.

Line 38:

If we add 45 to COUNTER instead of 4 and 5, the space between the first and second appearance of the in-line rule would be omitted.

Lines 39-41:

Line 39 generates the LINKAGE SECTION statement and relocates line 40 to the Linkage Section; see output lines 5328-5330). Line 41 ends the effect of % SET LINKAGE.

Line 42:

This omits delimiters around string arguments, as on line 43.

Lines 45-47:

Line 45 relocates line 46 to immediately after the DATA DIVISION statement (see output line 5304).

Lines 48-51:

Line 48 relocates lines 49-50 to the end of the File Section (see output lines 5312-5314).

Lines 52-54:

Line 52 relocates line 53 to the end of FILE-CONTROL.

Lines 57-59:

Line 57 relocates line 58 to the end of WORKING-STORAGE.

Lines 61-63:

Line 61 outputs line 62 to an external auxiliary file named RULE.

Output source:

001700 IDENTIFICATION DIVISION.                              17.
001800 PROGRAM-ID.                                           18.
001900                               EXAMPLE9.               19.
002000 ENVIRONMENT DIVISION.                                 20.
002100 INPUT-OUTPUT SECTION.                                 21.
002200 FILE-CONTROL.                                         22.
002300     SELECT YOUR-FILE          ASSIGN UT-S-YOURFILE.   23.
005300     SELECT MY-FILE            ASSIGN UT-S-MYFILE.     53.
005302 DATA DIVISION.                                        24.
005304* PLACING DATA IN DATA DIVISION                        46.
005306 FILE SECTION.                                         25.
005308 FD  YOUR-FILE.                                        26.
005310 01  YOUR-RECORD                 PIC X(80).            27.
005312 FD  MY-FILE.                                          49.
005314 01  MY-RECORD                   PIC X(80).            50.
005316 WORKING-STORAGE SECTION.                              28.
005318 01  COUNTER                     PIC S9(4) COMP.       29.
005320 01  WS-1                        PIC X.                30.
005322 01  TEST-NO-DELIMITERS          PIC 9(6).
005324*    PLACE FOR STUFF THAT MUST BE AT END OF WS FOR
005326*    CERTAIN NON-BUILDER PRE-PROCESSORS                33.
005328 LINKAGE SECTION.
005330 01  LINKAGE-STUFF               PIC X.                40.
006300 01  MY-EPILOGUE-CHR             PIC X.
006302 PROCEDURE DIVISION.                                   34.
006304     COUNTER = 1                                       35.
006306     COUNTER = 2
006308     COUNTER = 3
006310     TEST-NO-DELIMITERS = 3
006312     COUNTER = 4
006314     COUNTER = 5
006316     COUNTER = COUNTER + 4 5
006318     COUNTER = TEST-NO-DELIMITERS
006320     COUNTER = 6
006322     OPEN INPUT MY-FILE YOUR-FILE                      55.
006324     CLOSE MY-FILE YOUR-FILE                            56.
006326*/*  THIS IS AN S-COBOL COMMENT LINE.                  60.
006328     COUNTER = 100                                       11.
006330     COUNTER = 101                                       15.

Lines 6312-6316:

If we add 45 to COUNTER instead of 4 and 5, the space between the first and second appearance of the in-line rule would be omitted.

Line 6328:

Line 15 of the rule source (% SET EPILOGUE $MY-EPILOGUE) put $MY-EPILOGUE in the storage area called EPILOGUE. All rules in EPILOGUE are invoked at the end of the program and after Customizer processing, starting with the last rule put into EPILOGUE. Because $MY-EPILOGUE is the only rule in EPILOGUE, it is invoked. The result is line 6328 in the output.

During $MY-EPILOGUE processing, % SET LINKAGE relocates line 9 to the end of the Linkage Section (line 6300), and puts COUNTER = 100 at the end of the Procedure Division (line 6328). Line 15 is an EPILOGUE statement nested within a $MY-EPILOGUE; it puts $SECOND-EPILOGUE into the EPILOGUE area. This completes $MY-EPILOGUE processing.

Now, $SECOND-EPILOGUE, the last rule existing in EPILOGUE, is invoked.

After precompiler processing:

After Customizer processes the above program, the precompiler processes it. The result is shown below. Note the additional lines (5324 through 5340 and 6236 through 6242) that the precompile process generates.

001700 IDENTIFICATION DIVISION.                              17.
001800 PROGRAM-ID.                                           18.
001900                                 EXAMPLE9.             19.
002000 ENVIRONMENT DIVISION.                                 20.
002100 INPUT-OUTPUT SECTION.                                 21.
002200 FILE-CONTROL.                                         22.
002300     SELECT YOUR-FILE          ASSIGN UT-S-YOURFILE.   23.
005300     SELECT MY-FILE           ASSIGN UT-S-MYFILE.     53.
005302 DATA DIVISION.                                        24.
005304* PLACING DATA IN DATA DIVISION                        46.
005306 FILE SECTION.                                         25.
005308 FD  YOUR-FILE.                                        26.
005310 01  YOUR-RECORD               PIC X(80).              27.
005312 FD  MY-FILE.                                          49.
005314 01  MY-RECORD                 PIC X(80).              50.
005316 WORKING-STORAGE SECTION.                              28.
005318 77  COUNTER                   PIC S9(4) COMP.         29.
005320 01  WS-1                      PIC X.                  30.
005322 01  TEST-NO-DELIMITERS        PIC 9(6).
005322
005324 01  GENERATED--FLAGS.
005326     05  TRUE                    PIC X VALUE 'T'.
005328         88  ALWAYS              VALUE 'T'.
005330         88  NEVER               VALUE 'F'.
005332     05  FALSE                   PIC X VALUE 'F'.
005334     05  YOUR-FILE--END          PIC X.
005336     05  YOUR-FILE--INV          PIC X.
005338     05  MY-FILE--END            PIC X.
005340     05  MY-FILE--INV            PIC X.
005342
005344*    PLACE FOR STUFF THAT MUST BE AT END OF WS FOR    32.
005346*    CERTAIN NON-BUILDER PRE-PROCESSORS.              33.
005348 LINKAGE SECTION.
005350 01  LINKAGE-STUFF               PIC X.                40.
006200 01  MY-EPILOGUE-CHR             PIC X.
006202 PROCEDURE DIVISION.                                   34.
006204 MAIN--SECTION SECTION.                                35.
006206 MAIN--SECTION--PARA.                                  35.
006208     COUNTER = 1.                                      35.
006210     COUNTER = 2.
006212     COUNTER = 3.
006214     TEST-NO-DELIMITERS = 3.
006216     COUNTER = 4.
006218     COUNTER = 5.
006220     COUNTER = COUNTER + 4 5
006222     COUNTER = TEST-NO-DELIMITERS.
006224     COUNTER = 6.
006226     OPEN INPUT MY-FILE YOUR-FILE.                     55.
006228     CLOSE MY-FILE YOUR-FILE.                          56.
006230*    THIS IN AN S-COBOL COMMENT LINE                   60.
006232     COUNTER = 100.                                    11.
006234     COUNTER = 101.                                    15.
006236 MAIN--SECTION--EXIT.                                  15.
006238     EXIT PROGRAM.                                     15.
006240 MAIN--SECTION--EXIT.                                  15.
006242 STOP RUN.                                             15.
Parent topic: Customizer Rule Examples


Example - Rule Compilation Report

The appearance of OPEN_CODE in the report refers to the outermost level of code within a file of rules, such as code outside of any % DEFINEs or % SUBMEMBERs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
--- COMPILATION REPORT: VARIABLES BY RULE ---

FILE: E:\IG\USERMACS\defmacs

OPEN_CODE
  GLOBAL SYMBOLS
    $A
    $AK
    $ATTR
    $COMPLETE
    $D
    $DATA-TYPE
    $DIALOG
    $DOMAIN
    $DOMAIN-VALUE
    $E
    $EDITORS
    $ENT-MAPPING-HINTS
    $ENT-TYPE
    $ENTITY
    $IBMATTR
    $IBMENT
    $IBMMODEL
    $IBMREL
    $ISASUPER
    $LDM-ENT
    $LISTATTR
    $LOGICAL-DATA-MODEL
    $M
    $MODEL
    $PK
    $R
    $REL-DEPENDS-ON
    $REL-IS-ORDERED
    $REL-MAPPING-HINTS
    $REL-TYPE
    $RELATION
    $RELATION-AUX
    $RESOLVE-DATATYPE-INFO
    $SECS
    $SELMDL
    $T
    $TOOL
    $TOOLVIEW
    $USAGE
    $W
    &IS-ENT
    &IS-REL
    &MODELTYPE-ATOM
    &MODELTYPE-NAME
    &OBJID
$MODEL
  FORMAL ARGUMENTS
    &DESC
    &NAME
  GLOBAL SYMBOLS
    &DEFINED
    &IXMODL
    &MODL-DAT-COUNT
    &MODL-DESC-NAME
    &MODL-DOM-COUNT
    &MODL-ENT-COUNT
    &MODL-ID
    &MODL-REL-COUNT
    &MODLL-NAME
    &MODLNAME
    &OBJID
$ENT-TYPE
  FORMAL ARGUMENTS
    &ENTT-DESC
    &ENTT-NAME
  GLOBAL SYMBOLS
    &ETT-DESC-NAME
    &ETT-INSTANCE-COUNT
    &ETTNAME
$REL-TYPE
  FORMAL ARGUMENTS
    &FWD-NAME
    &INV-NAME
  GLOBAL SYMBOLS
    &IXRTT
    &RTT-FWD-NAME
    &RTT-INSTANCE-COUNT
    &RTT-INV-NAME
.
.
.
-------------------------------------------------------

--- COMPILATION REPORT: VARIABLE-RULE CROSS REFERENCE ---
FILE: E:\IG\USERMACS\defmacs

$A                               OPEN_CODE
$AK                              OPEN_CODE
$ATTR                            OPEN_CODE
$COL-NAME                        $RESOLVE-DATATYPE-INFO
$COMPLETE                        OPEN_CODE
$D                               OPEN_CODE
$DATA-TYPE                       OPEN_CODE
$DIALOG                          OPEN_CODE
$DOMAIN                          OPEN_CODE
$DOMAIN-VALUE                    OPEN_CODE $ENTITY
$E                               OPEN_CODE
$EDITORS                         OPEN_CODE
$ENT-MAPPING-HINTS               OPEN_CODE
$ENT-TYPE                        OPEN_CODE
$ENTITY                          OPEN_CODE
$IBMATTR                         OPEN_CODE
$IBMENT                          OPEN_CODE
$IBMMODEL                        OPEN_CODE
$IBMREL                          OPEN_CODE
$ISASUPER                        OPEN_CODE
$LDM-ENT                         OPEN_CODE
$LISTATTR                        OPEN_CODE
$LOGICAL-DATA-MODEL              OPEN_CODE
$M                               OPEN_CODE
$MODEL                           OPEN_CODE
$PK                              OPEN_CODE
$R                               OPEN_CODE
$REL-DEPENDS-ON                  OPEN_CODE
$REL-IS-ORDERED                  OPEN_CODE
$REL-MAPPING-HINTS               OPEN_CODE
$REL-TYPE                        OPEN_CODE
$RELATION                        OPEN_CODE
$RELATION-AUX                    OPEN_CODE $RELATION
$RESOLVE-DATATYPE-INFO           OPEN_CODE
$SECS                            OPEN_CODE
$SELMDL                          OPEN_CODE
$T                               OPEN_CODE
$TOOL                            OPEN_CODE
$TOOLVIEW                        OPEN_CODE
$USAGE                           OPEN_CODE
$W                               OPEN_CODE
&A                             F $USAGE
&A                               $A
&ABSTRACT                      F $ISASUPER
&ALL-OBJ                       F $TOOLVIEW
&AT1                           F $PK $AK $LISTATTR
&AT2                           F $PK $AK $LISTATTR
&AT3                           F $PK $AK $LISTATTR
&AT4                           F $PK $AK $LISTATTR
&AT5                           F $PK
&AT6                           F $PK
&AT7                           F $PK
&AT8                           F $PK
&ATTR                          F $ATTR
&AUDIT-ATTRS                   F $REL-MAPPING-HINTS
&B                             F $USAGE
&C                             F $USAGE
&C1                            F $USAGE
&C10                           F $USAGE
&C11                           F $USAGE
&C12                           F $USAGE
&C13                           F $USAGE
&C14                           F $USAGE
&C15                           F $USAGE
&C16                           F $USAGE
&C17                           F $USAGE
&C2                            F $USAGE
&C3                            F $USAGE
&C4                            F $USAGE
&C5                            F $USAGE
&C6                            F $USAGE
&C7                            F $USAGE
&C8                            F $USAGE
&C9                            F $USAGE
&CHECK-RESERVED-WORDS            $W
&COL-NAME                        $RESOLVE-DATATYPE-INFO
&COLMNAME                      F $DATA-TYPE $ATTR
&CONTROLID                     F $ATTR
&CQ                              $ENTITY $AK $LISTATTR $LDM-ENT
&CRUD                          F $TOOLVIEW
&CRUD                            $USAGE
&D                               $D
&DATATYPE                      F $DATA-TYPE $ATTR
&DEFID                         F $DIALOG
&DEFINED                         $MODEL $DOMAIN $DOMAIN-VALUE $DATA-
                                 TYPE $ENTITY
                                 $ENT-MAPPING-HINTS $EDITORS $ISASUPER
                                 $RELATION
                                 $RELATION-AUX $REL-MAPPING-HINTS
                                 $REL-DEPENDS-ON $ATTR $DIALOG $PK $AK $LISTATTR
                                 $IBMENT $IBMREL $IBMATTR $RESOLVE-
                                 DATATYPE-INFO
                                 $COMPLETE $LOGICAL-DATA-MODEL $LDM-
                                 ENT $W $TOOL
                                 $TOOLVIEW $USAGE
&DEFVALUE                      F $DOMAIN $DATA-TYPE $ATTR
&DEFVALUE-FLAG                 F $DOMAIN-VALUE
&DESC                          F $MODEL $ENTITY $LOGICAL-DATA-MODEL
                                 $TOOL
                                 $TOOLVIEW
&DIALOGID                      F $ENTITY $RELATION $RELATION-AUX
$DIALOG
&DM-ID                           $DOMAIN
&DM-MODEL                        $DOMAIN
&DM-NAME                         $DOMAIN $DOMAIN-VALUE $DATA-TYPE
                                 $ENTITY $ATTR
&DM-NUM-ATOMS                    $DOMAIN $DOMAIN-VALUE
&DM-REF-COUNT                    $DOMAIN $DATA-TYPE $ATTR
&DM-TYPE                         $DOMAIN
&DMX-MAX                         $DOMAIN
&DMX-MIN                         $DOMAIN
&DMY-DEFVALUE                    $DOMAIN $DOMAIN-VALUE $DATA-TYPE
&DOMAIN                        F $ATTR
&DOMN                          F $DATA-TYPE
&DST-DEL-RULE                  F $REL-MAPPING-HINTS
&DST-PREFIX                    F $REL-MAPPING-HINTS
&DTL                             $RESOLVE-DATATYPE-INFO
&DTL-DT-IXDM                     $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DTL-DT-LEN                      $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DTL-DT-MODEL                    $DATA-TYPE
&DTL-DT-NAME                     $DATA-TYPE $ATTR $RESOLVE-DATATYPE-
                                 INFO
&DTL-DT-REF-COUNT                $DATA-TYPE $ATTR $RESOLVE-DATATYPE-
                                 INFO
&DTL-DT-SCALE                    $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DTL-DT-TYPE                     $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DTLX                            $RESOLVE-DATATYPE-INFO
&DTLX-COL-LEN                    $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DTLX-COL-NAME                   $DATA-TYPE $ATTR $RESOLVE-DATATYPE-
                                 INFO
&DTLX-COL-TYPE                   $RESOLVE-DATATYPE-INFO
&DTLY-DEFVALUE                   $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DTLY-PARENT                     $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DTLY-PARENT-IXDT                $DATA-TYPE $RESOLVE-DATATYPE-INFO
&DV-ID                           $DOMAIN-VALUE
&DV-MEAN                         $DOMAIN-VALUE
&DV-VALUE                        $DOMAIN-VALUE
&E                               $E
&E1                            F $RELATION $RELATION-AUX
&E1-MAX                        F $RELATION $RELATION-AUX
Parent topic: Customizer Rule Examples


MFG command

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Describes the execution of the Micro Focus Generator from the command line.

Important: When you generate a program, AppMaster Builder automatically invokes the MFG, constructing a control file and executing the MFG command. However, you can optionally invoke the MFG using the MFG command at a command prompt. Do this only when you:
  • Run the generator outside of AMB.
  • Modify the AMB file tailoring skeleton to change how AMB invokes the generator.

The MFG command:

  • Executes the Micro Focus Source Code Generator rule source
  • Compiles rule source in a .DLL
  • Runs an MFG Rule Compilation Report

Syntax:

 MFG <inputfile> [<outputfile>]
 ... /RunRule=EXEC|COMPile
[... /CARDin=drive:\path\filename]
[... /CHARacterS,[(LINE|Rule|VARiable|VariableTERM|
 ...     LeftEVAL|RightEVAL|EVALs)]]
[... /[NO]CompilationDATA]
[... /[NO]CompilationRePorT]
[... /DataDefinition,[(Name=name)]
 ...     [(DynamicLinkLibrary=drive:\path\DLLfilename)]
 ...     [(eXtension=value)]
 ...     [(File)[(FileBufferSize=MIN|MAX|<value>)]
 ...     [(FileBufferType=Full|Line|None)]
 ...     [(LANGuage=CoBol|CoBoL2|CoBoLII|SCoBol|TeXT)]]
 ...     [(Path=drive:\path\filename)
 ...     [(FileBufferSize=MIN|MAX|<value>)]
 ...     [(FileBufferType=Full|Line|None)]
 ...     [(LANGuage=CoBol|CoBoL2|CoBoLII|SCoBol|TeXT)]]
 ...     [(SearchMode)[(FirstFound|Latest)]]]
[... /[NO]ERRorOPTion,[suboption]]
[... /Help|? [(optionname)]]
[... /LANGuage,(CoBoL|CoBoL2|CoBoLII|SCoBol|TeXT)]
[... /LeftMARgin=colmunnumber]
[... /RightMARgin=colmunnumber]
[... /LOGfile=drive:\path\logfilename]
[... /macro=drive:\path\MACROfilename]
[... /mainIN=drive:\path\MAININfilename]
[... /MCS=screengenerationname]
[... /MDB=databasetarget]
[... /MDB=datacommunicationtarget]
[... /[NO]NewBuiltinWarning]
[... /PARMin=drive:\path\controlfilename]
[... /postsOUT=drive:\path\outputfilename]
[... /PREServe,[(ALL|CoMmeNTs|LINEnumbers|LinePrefix|
 ...    LineSuffix]
[... /ProjectGroup=drive:\project\group]
[... /PSB=PSBname]
[... /RePorT=drive:\path\reportfilename]
[... /RunMode,[(EXECute|COMPile|UNParse)]]
[... /SearchMode,[(FirstFound|Latest)]
[... /TarGeTCOMPiler,[(ASseMbly|BASic|CoBoL|CoBoL2|FORTran|
 ...     JCL|PAScal|PLI|SCoBol|TeXT)]]
[... /[NO]TRACE,[(ALL|[NO]AST|[NO]EVALMESSages|[NO]LASTstmts|
 ...     [NO]UNParse|[NO]VARiableS)]]
[... /[NO]VERbose,[(ALL|HeLP|[NO]INCL[udemessages]|
 ...     [NO]ProGraMDLLmessages)]]

Syntax Rules:

  1. Enclose any option value with an embedded blank, hyphen, or slash in quotes.
  2. Prefix options with a forward slash (/) or a hyphen (-).
  3. Option syntax is flexible. You can omit parentheses and equal signs if the meaning is clear. For example, for options with sub-options, the following are all equivalent:
    • /TRACE=(AST,VARS)
    • /TRACE=(AST) /TRACE=(VARS)
    • /TRACE=AST /TRACE=VARS
    • /TRACEAST /TRACEVARS
    You can form and use shortened keywords. To form a shorter keyword, use either the capitalized letters, the first several capital letters, or the first several letters (caps or not) that uniquely identify the option. For example, for /RunMode=COMPile/n, you could use any of the following:
    • /RunMode=COMPile /RunMode=COMP
    • /RM=COMPile /RM=COMP
    • /RMCOMP /RunMo=COMP
    • /RUNM=COMP /RUNM=COM

    You could not use /RUN=COMP, because there are other RunMode options that start with /RUN.

Parameters:

Inputfile
For generating a file containing rule source that is the main input to the generator (MAININ).

For compiling a file containing rule source to be compiled.

Outputfile
For generating a file to receive the generator output (POSTSOUT). Default file is POSTSOUT in the current directory.

For compiling a DLL file to receive the compiled input file.

/RunRule=EXEC|COMPILE
For generating. the default is EXEC.

For compiling, the default is COMPILE.

Comments:

  • You can establish MFG command options using two environment variables.
    • IG_DEFAULTS, which is processed before the command line, thus establishing default values
    • IG_OVERRIDES, which is processed after the options on the command line, thus overriding any previous values
  • To establish these variables, use the operating system SET command. For example, SET IG_DEFAULTS /MDB=DB2.
  • Alternatively, you can establish options in a control file:
    • Place the options in a control file and identify the control file by prefixing it with the "at" sign ( @ ). For example: Alternatively, you can establish options in a control file. Place the options in a control file and identify the control file by prefixing it with the "at" sign ( @ ). For example:
      MFG @mygen.ctl
MFG infile outfile.out @mygen.ctl
MFG infile @mygen.ctl /RM=COMPILE @moreopts.ctl
    • When the same logical file (DD) or option is specified more than once, the last specification is used, regardless of whether it came from environment variables, the command line, or an option file.
    • When the same logical file (DD) or option is specified more than once, the last specification is used, regardless of whether it came from environment variables, the command line, or an option file.

Examples:

Read a file called MAININ and write a file named POSTSOUT, both in the current directory.

MFG

Read myrule.fmp and send the generated output to a file named POSTSOUT.

MFG myrule.fmp

Read myrule and send the generated output to gened.out.

MFG myrule gened.out

Read myrule.fmp and send the compiled output to myrule.dll. The RunRule option is appropriately set to COMP.

MFG myrule.fmp myrule.dll /RM=COMP

There are other ways to specify the MAININ and POSTSOUT input and output files. See the Examples section of /mainIN and /postsOUT for more information.

  • CARDin
    Specify the file path and name for the CARDIN INCLUDE member, which is the optional rule source file that the MFG processes before it reads the MAININ INCLUDE file.
  • CHARacterS
    Specify a special character to ensure certain source items are processed rather than simply "passed through" to the output. Default special characters designate the following.
  • CompilationDATA
    Produce an intermediate report data file of variable-rule cross references that later produce a comprehensive compilation report. For more information, see Example - Rule Compilation Report.
  • CompilationRePorT
    Produce a compilation report that cross-references variable symbols and rule names to the rules where they are defined and referenced. This report is created when rule source is read and compiled--not executed. Thus, variable names constructed during rule execution using evaluation expressions are not listed..
  • DataDefinition
    Define a data definition for physical data access. You can define a single file, a directory containing many files, or a concatenation of several directories.
  • ERRorOPTion
    Control how error messages display.
  • Help
    Print general information or information about a particular option.
  • LANGuage
    Specify the language attribute of an input or output file that do not have the language specified.
  • LeftMARgin
    Specify the leftmost column of a source line. The LeftMARgin value is used for lexical scanning and unparsing.
  • LOGfile
    Specify the path and name for the file containing both a detailed event log and the debug output.
  • macro
    Specify the file path and name for the MACRO output auxiliary file.
  • mainIN
    Specify the file path and name for the MAININ file, which is read and processed after CARDIN. This option is an alternative to specifying:
  • MCS
    Set the value to the screen generation name; this becomes the value of the &APS-MCS built-in function in the control file, which, in turn, is passed to the MFG.
  • MDB
    Set the value Multiple Database (MDB) generation target; this becomes the value of the built-in &APS-MDB function in the control file, which, in turn, is passed to the IG. In your rule program logic, examine this variable to tailor the output to the generated application database.
  • MDC Option
    Set the value Multiple Data Communications (MDC) generation target; this becomes the value of the &APS-MDC built-in function, which holds the data communications target value. This function in the control file is passed to the MFG. In your rule program logic, examine this variable to tailor the output to the generated screen.
  • NewBuiltinWarning
    Generate a compile time warning when the MFG encounters a Customizer function not supported by the mainframe platform.
  • NOoption
    An alternative way to disable the following options.
  • PARMin
    Name the parameter input file (also called a control file) containing the MFG options you specified. Specifying /PARM=C:\MYFILE.CTL is equivalent to specifying @C:\MYFILE.CTL on the command line. The parameter file can contain parameters formatted the same way they would appear on the command line, but can be placed one per line in the file.
  • postsOUT
    Specify the file path and name for the output generated from the IG.POSTSOUT. This option is an alternative to specifying:
  • PREServe
    Preserve aspects of the original source code when you compile, such as line numbers. The option facilitates debugging.
  • ProjectGroup
    Specify the project and group path to the file that qualifies rule source INCLUDEs.
  • PSB
    Specify the IMS Program Specification Block (PSB) Name. This name is passed to the built-in &APS-PSB-NAME variable, which returns the PSB name.
  • RePorT
    Specify the file path and name of the file to which the IG writes a high-level summary of the run.
  • RightMARgin
    Specify the rightmost column of a source line. The RightMARgin value is used for lexical scanning and unparsing.
  • RunMode
    Execution mode.
  • SearchMode
    Specify the default search mode when looking for a file or member in a DD that is a concatenation of paths. This option applies to all DDs that do not explicitly specify a SearchMode option.
  • TarGeTCOMPiler
    Specify the compiler or processor language. Normally, the language is available to rule programs via the built-in variable &APS-COMPILER. However, you can modify the program for a different processor by testing the &APS-COMPILER variable and using this option.
  • TRACE
    Specify how to execute the TRACE rule for debugging.
  • VERbose
    Specify amount of online help detail to display.
Parent topic: Customizer/Micro Focus Generator (MFG)


CARDin

Specify the file path and name for the CARDIN INCLUDE member, which is the optional rule source file that the MFG processes before it reads the MAININ INCLUDE file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/CARDin=drive:\path\filename
Parent topic: MFG command


CHARacterS

Specify a special character to ensure certain source items are processed rather than simply "passed through" to the output. Default special characters designate the following.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • %--Start of a rule line
  • $--Start of a rule name
  • &--Start of a rule variable name
  • +--End of a rule variable name
  • <--Left evaluation bracket
  • >--Right evaluation bracket

Syntax:

/CHARacterS,[(LINE|Rule|VARiable|VariableTERM|
... LeftEVAL|RightEVAL|EVALs)]

Parameters:

LINE | The rule line start character (default is %) signals a statement line which contains a command to the Generator.
Rule | The rule start character (default is $) signals the beginning of a rule name. A rule is a package of statements.
VARiable | The variable name start character (default is &) signals the beginning of a generator variable name. Variables are assigned values that are substituted where the variable name appears.
VariableTERM | The variable name termination character (default is +) signals the end of a generator variable name. The termination character is useful where a variable name is followed by characters that could be part of a variable name.
LeftEVAL | The left evaluation bracket (default is <) signals the left boundary of a statement fragment whose content is determined at execution.
RightEVAL | The right evaluation bracket (default is >) signals the left boundary of the statement fragment whose content is determined at execution.
EVALs | Alternative to specifying LeftEVAL and RightEVAL. The pair of characters to serve as the left and right evaluation brackets (default is < >).
Parent topic: MFG command


CompilationDATA

Produce an intermediate report data file of variable-rule cross references that later produce a comprehensive compilation report. For more information, see Example - Rule Compilation Report.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/CompilationDATA
Parent topic: MFG command


CompilationRePorT

Produce a compilation report that cross-references variable symbols and rule names to the rules where they are defined and referenced. This report is created when rule source is read and compiled--not executed. Thus, variable names constructed during rule execution using evaluation expressions are not listed..
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/[NO]CompilationRePorT
Parent topic: MFG command


DataDefinition

Define a data definition for physical data access. You can define a single file, a directory containing many files, or a concatenation of several directories.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/DataDefinition,[(Name=name)]
... [(DynamicLinkLibrary=drive:\path\DLLfilename)]
... [(eXtension=value)]

... [(File)[(FileBufferSize=MIN|MAX|<value>)]
... [(FileBufferType=Full|Line|None)]
... [(LANGuage=CoBol|CoBoL2|CoBoLII|SCoBol|TeXT)]]

... [(Path=drive:\path\filename)
... [(FileBufferSize=MIN|MAX|<value>)]
... [(FileBufferType=Full|Line|None)]
... [(LANGuage=CoBol|CoBoL2|CoBoLII|SCoBol|TeXT)]]

... [(SearchMode)[(FirstFound|Latest)]]

Parameters:

Name=name This suboption is positional. Specify the name by which the file, directory or concatenation of directories is referenced by the rule statements. For example, the following statement reads and processes a file of rule source.
% INCLUDE ddname [(member)]
[submember]

For another example, the % INCLUDE MYDIR (MYMACS) statement expects a DataDefinition that associates the logical DataDefinition name to physical files as follows.

/DD(NAME=MYDIR <file spec>) or /DD(MYDIR <file spec>)

DynamicLinkLibrary Specifies the file is a Dynamic Link Library (DLL). This keyword names a .DLL that contains compiled rules to be included for generation. For example, the % INCLUDE COMPLMAC statement expects a DataDefinition that associates the logical DataDefinition name to the physical file AFILE.DLL containing compiled rules.

/DD(COMPLMAC DLL=C:\RULEDIR\AFILE.DLL)

eXtension Supplies an extension for a file. This is helpful where the extensions for a type of file are not obvious from the type. For example, rule source files could be given extensions such as .FMP or .IGL. Where the extension is determined (e.g., DLL type files always has and extension of .DLL), this option is not needed. This option is also useful in shops that want files to have file extensions, even though the % INCLUDE statement can not specify a file extension. For example:

% INCLUDE SRCMACS (MYMEMBR) would refer to file MYMEMBR.IGL in the C:\RULEDIR directory: /DD(SRCMACS EXT=IGL,PATH=C:\RULEDIR)

File | Indicate that the object in the DataDefinition is a file, instead of a directory and path.
FileBufferSize | Specify the file buffer size, for example, FBS=4096. Specify MIN or MAX for the generator to use the smallest or largest reasonable size, as set by developers.
FileBufferType | Specify the default buffering type for files that do not have one specified.
LANGuage | Same as the LANGuage option.
Path | Indicate that the DataDefinition object is a directory that contains the rule source files included in the generation process. For example, the % INCLUDE SRCMACS (MYMEMBR) statement expects a DataDefinition associating the logical DataDefinition name to the physical compiled rule file MYMEMBR. /DD(SRCMACS PATH=C:\RULEDIR), where MYMEMBR is in the C:\RULEDIR directory.
SearchMode | Same as the SearchMode option.
Parent topic: MFG command
Related reference
LANGuage
SearchMode


ERRorOPTion

Control how error messages display.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/[NO]ERRorOPTion,[suboption]

Parameters:

Suboption can be:

ALL | Display all messages.
[NO]UNDETerminedForms | Display (default), or do not display, a message when a compiled rule AST node for an undetermined form (UNDETx) executes.
[NO]UNIMPLementedSETs | Display (default), or do not display, a message when a % SET statement, that is obsolete or not implemented, executes.
[NO]EVALSTartLine | Display (default), or do not display, a warning message when a non-rule line begins with a left evaluation bracket. A warning is useful here because the line is interpreted as text, that is, a non-rule line).
Parent topic: MFG command


Help

Print general information or information about a particular option.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/[NO]Help|? [(optionname)]

Comments:

To Display... | Enter...
List of options | MFG /?
Help on a single option and its suboptions | MFG /?<optionname> or MFG /<optionname> For example, MFG /?DD or MFG /??DD
Additional help on a single option and all its suboptions | MFG /?<optionname> or MFG /VERbose /<optionname>. For example, MFG /???DD or MFG /VERbose /??DD
List of options and all their suboptions | MFG /??
List of options and suboptions with additional information | MFG /??? or MFG /VERbose /??
Parent topic: MFG command


LANGuage

Specify the language attribute of an input or output file that do not have the language specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

For an input file, the language attribute determines the

  • Left and right margins of lines being processed.
  • Rules for distinguishing generator statements from target language statements.

For an output file, the language attribute determines the

  • Left and right margins.
  • Breaking and wrapping of lines, for example, continuation characters.
  • Structure of the output file, for example, the organization of sections.

Syntax:

/LANGuage,(CoBoL|CoBoL2|CoBoLII|SCoBol|TeXT)
Parent topic: MFG command


LeftMARgin

Specify the leftmost column of a source line. The LeftMARgin value is used for lexical scanning and unparsing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/LeftMARgin=colmunnumber

Comments:

The default left margin value is set by the Language precompiler parameter, as follows.

Parameter Value | Left Margin
SCB | Column 8
COBOL | Column 1
JCL | Column 1
Text | Column 1
Parent topic: MFG command


LOGfile

Specify the path and name for the file containing both a detailed event log and the debug output.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/LOGfile=drive:\path\logfilename
Parent topic: MFG command


macro

Specify the file path and name for the MACRO output auxiliary file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/macro=drive:\path\MACROfilename
Parent topic: MFG command


mainIN

Specify the file path and name for the MAININ file, which is read and processed after CARDIN. This option is an alternative to specifying:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • MFG (inputfile) on the command line.
  • /DD (MAIN filename)--use this, however, when you want to use other /DD suboptions

Syntax:

/mainIN=drive:\path\MAININfilename
Parent topic: MFG command


MCS

Set the value to the screen generation name; this becomes the value of the &APS-MCS built-in function in the control file, which, in turn, is passed to the MFG.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/MCS=screengenerationname
Parent topic: MFG command


MDB

Set the value Multiple Database (MDB) generation target; this becomes the value of the built-in &APS-MDB function in the control file, which, in turn, is passed to the IG. In your rule program logic, examine this variable to tailor the output to the generated application database.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/MDB=databasetarget

Comments:

  • The default target is VSAM.
  • Enclose any targets that have hyphens as part of their name in quotes. For example, /MDB=SQL and /MDB="SQL-SVR".
Parent topic: MFG command


MDC Option

Set the value Multiple Data Communications (MDC) generation target; this becomes the value of the &APS-MDC built-in function, which holds the data communications target value. This function in the control file is passed to the MFG. In your rule program logic, examine this variable to tailor the output to the generated screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/MDB=datacommunicationtarget

Comments:

  • The default target is ISPF.
  • Enclose any targets that have hyphens as part of their name in quotes.
Parent topic: MFG command


NewBuiltinWarning

Generate a compile time warning when the MFG encounters a Customizer function not supported by the mainframe platform.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/NewBuiltinWarning
Parent topic: MFG command


NOoption

An alternative way to disable the following options.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • /CompilationData
  • /CompilationRePorT
  • /ErrorOption
  • /Help
  • /NewBuiltinWarning
  • /PREServe
  • /TRACE
  • /VERbose

Syntax:

/NOoptionname

Example:

To turn execution tracing off, the following are equivalent.

/TRACE=NO or /NOTRACE
Parent topic: MFG command


PARMin

Name the parameter input file (also called a control file) containing the MFG options you specified. Specifying /PARM=C:\MYFILE.CTL is equivalent to specifying @C:\MYFILE.CTL on the command line. The parameter file can contain parameters formatted the same way they would appear on the command line, but can be placed one per line in the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/PARMin|@=drive:\path\controlfilename

Examples:

Coding the following on the command line:

MFG /MAININ=MYFILE.FMP /POSTSOUT=MYFILE.OUT

Is equivalent to either of the following:

MFG /PARM=MYFILE.CTL
MFG @MYFILE.CTL

Where, MYFILE.CTL contains the lines:

/MAININ=MYFILE.FMP
/POSTSOUT=MYFILE.OUT
Parent topic: MFG command


postsOUT

Specify the file path and name for the output generated from the IG.POSTSOUT. This option is an alternative to specifying:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • MFG (inputfile) POSTSOUToutputfile on the command line.
  • /DD (POSTSOUT filename)--use this, however, when you want to use other /DD suboptions

Syntax:

/postsOUT=drive:\path\outputfilename
Parent topic: MFG command


PREServe

Preserve aspects of the original source code when you compile, such as line numbers. The option facilitates debugging.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/[NO]PREServe,[(ALL|CoMmeNTs|LINEnumbers|LinePrefix|LineSuffix)]

Parameters:

ALL | Preserve all comments, line numbers, source line prefixes and suffixes.
CoMmeNTs | Preserve comment lines (lines beginning with %*). By default, the MFG discards these lines; comment lines do not appear in unparsed source. This suboption permits a compiled form to be unparsed back into the source form with comment lines preserved.
LINEnumbers | Preserve all line numbers. If preserved, source line numbers can speed the process of editing a rule source using and editor that can position at a specified line. Line numbers may appear in error messages to help identify lines in error.
LinePrefix | Preserve the source line prefix, that is, those columns before the left margin. For example, in COBOL, the source line prefix is the sequence number in columns 1-6.
LineSuffix | Preserve the source line suffix, that is, those columns after the right margin. For example, in COBOL, the source line suffix is the identification numbers in columns 73-80. Use this suboption to identify the exact line that appears in an error message.

Comments:

Using this option increases the size of the compiled source.

Parent topic: MFG command


ProjectGroup

Specify the project and group path to the file that qualifies rule source INCLUDEs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/ProjectGroup=drive:\project\group

Comments:

  • The default is the current directory.
  • Use this option for the file that contains % INCLUDEs that only reference undefined DDNames.
Parent topic: MFG command


PSB

Specify the IMS Program Specification Block (PSB) Name. This name is passed to the built-in &APS-PSB-NAME variable, which returns the PSB name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/PSB=PSBname
Parent topic: MFG command


RePorT

Specify the file path and name of the file to which the IG writes a high-level summary of the run.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/RePorT=drive:\path\reportfilename
Parent topic: MFG command


RightMARgin

Specify the rightmost column of a source line. The RightMARgin value is used for lexical scanning and unparsing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/RightMARgin=colmunnumber

Comments:

The default right margin value is set by the Language precompiler parameter, as follows.

Parameter Value | Left Margin
SCB | Column 72
COBOL | Column 72
JCL | Column 72
Text | Column 80
Parent topic: MFG command


RunMode

Execution mode.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/RunMode,[(EXECute|COMPile|UNParse)]

Parameters:

EXECute | Default. Input and process a rule source file.
COMPile | Compile a rule source file to a DLL.
UNParse | Load a DLL of compiled rules and reconstitute the source to a file.
Parent topic: MFG command


SearchMode

Specify the default search mode when looking for a file or member in a DD that is a concatenation of paths. This option applies to all DDs that do not explicitly specify a SearchMode option.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/SearchMode,[(FirstFound|Latest)]

Parameters:

FirstFound | Default. Stop the search with the first matching file or member found in the DD path concatenation. Use this option for best performance, and to to control the search order of files, such as rule INCLUDE members.
Latest | Search across all paths in the DD for the file or member with the latest modification time and date. Use this option to find the most recent version of a file. For example, you could use this option when the source and compiled (DLL) form of a rule member are in the same directory, and you want the latest version, regardless of form. For best performance, avoid using this option. Each path in the DD concatenation is searched, even if the desired member exists in the first path.
Parent topic: MFG command


TarGeTCOMPiler

Specify the compiler or processor language. Normally, the language is available to rule programs via the built-in variable &APS-COMPILER. However, you can modify the program for a different processor by testing the &APS-COMPILER variable and using this option.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/TarGeTCOMPiler,[(ASseMbly|BASic|CoBoL|CoBoL2|FORTran|JCL|
... PAScal|PLI|SCoBol|TeXT)]
Parent topic: MFG command


TRACE

Specify how to execute the TRACE rule for debugging.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/[NO]TRACE,[(ALL|[NO]AST|[NO]EVALMESSages|[NO]LASTstmts|
... [NO]UNParse|[NO]VARiableS)]

Parameters:

ALL | Display all lines.
AST or NOAST | Display, or do not display, each executed AST node.
EVALMESSages or NOEVALMESSages | Display, or do not display, evaluation expression results.
LASTstmts or NOLASTstmts | Capture, or do not capture, the full trace for the last 50 statements executed.
UNParse or NOUNParse | Display, or do not display, the source code for each statement executed.
VARiableS or NOVARiableS | Display, or do not display, the variable values that are referenced or modified by each statement executed.
Parent topic: MFG command


VERbose

Specify amount of online help detail to display.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

/[NO]VERbose,[(ALL|HeLP|[NO]INCL[udemessages]|
... [NO]ProGraMDLLmessages)]

Parameters:

ALL | Display all information.
HeLP | Detailed descriptions of command line parameters.
INCLudemessages or NOINCLudemessages | Default. Send, or do not send, % INCLUDEd rule member information to the log. Can use NOINCL with NOPGMDLL.
ProGraMDLLmessages or NOProGraMDLLmessages | Default. Default. Send, or do not send, information about the executable DLLs which comprise the generator to the log. Can use NOPGMDLL with NOINCL.
Parent topic: MFG command


MFG Structures

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following Micro Focus Generator (MFG) structures can be used to create Customizer rules in AMB programs.

Note: Pay attention to the "Syntax" section for each structure. When a structure has no arguments, do not code %structure ().
  • % * (comments)
    Document MFG code with comments.
  • % BEGIN
    Use in conditional or looping statement blocks to control the number of columns that AMB or APS moves the blocks during processing. The number of columns that you indent % BEGIN in a conditional or looping construct is the same number of columns that AMB moves the subordinate block to the left. Default processing moves the block to the starting column of the controlling conditional or looping construct.
  • % DECLARE
    Define a % DECLARE table made of variable assignments that can be referenced either directly (after assigning values to its subscripts), or by searching with the % LOOKUP structure.
  • % DEFINE
    Specify the rule name and formal arguments in a USERMACS file, or AMB program.
  • % ESCAPE
    Stop processing the rule and continue processing at the line immediately following the rule call.
  • % IF/ELSE-IF/ELSE
    Evaluate a condition.
  • % INCLUDE
    Open, read, and process a user-defined rule, copybook, or other file in a AMB program.
  • % LOOKUP
    Reference a % DECLARE table.
  • % REPEAT
    Establish a loop and test a condition.
  • % SET BLANK or NOBLANK
    Print all blank lines that appear in the input, or suppress blank lines from printing.
  • % SET COMMUNICATION
    Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the Communication Section.
  • % SET DATA
    Move all source code appearing between this statement and the next % SET statement from the Procedure Division to immediately after the Data Division header.
  • % SET EPILOGUE
    Call a rule after all other Customizer processing finishes. Although you can specify only one rule call per EPILOGUE statement, you can write multiple statements.
  • % SET ERROR FATAL WARNING INFO
    Send a message to the final message report of the compile, as follows.
  • % SET FILE
    Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the File Section. AMB generates the File Section header, unless it is in the input source or if the rule is an EPILOGUE rule.
  • % SET FILE-CONTROL
    Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the File-Control paragraph. AMB generates the Input-Output Section and File-Control headers, unless they are in the input source or if the rule is an EPILOGUE rule.
  • % SET LAST-STATUS
    Reset the value of the &APS-LAST-STATUS built-in function to 0. Use this rule to monitor the success or failure of one or more statements. The global status remains unchanged.
  • % SET LINKAGE
    Move all source code appearing between this statement and the next % SET statement to the end of the Linkage Section. AMB generates the Linkage Section header, unless it is in the input source or if the rule is invoked by % SET EPILOGUE. Use % SET LINKAGE in the Procedure Division.
  • % SET LOCATION structure
    Establish a location in a single output file where the MFG should place subsequent output lines. %SET-LOCATION can establish a new section in an output file, as well as reposition subsequent output lines at the end of a previously established section.
  • % SET LOOP-LIMIT
    Override the loop counter default (500) in the AMB CNTL file APSDBDC. The internal default set by the MFG is 999999. % SET LOOP-LIMIT is often used to locate the cause of infinite loops.
  • % SET NORMAL-OUTPUT
    Restore the output file to the file designated by /POSTSOUT= or the /DD for POSTSOUT.
  • % SET OUTPUT-FILE
    Establish a new output file to receive MFG output, or redirect MFG output to a previously established output file.
  • % SET PROCEDURE
    Mark the end of the preceding % SET statement that moves source to other locations in the program, such as % SET WORKING-STORAGE and % SET DATA DIVISION, and return to the location of the statement, not to the beginning or end of the Procedure Division.
  • % SET RETAIN-LINE-SUFFIX
    Specify that generator statements use their own source line suffixes (beyond the right margin) on output, instead of the inherited value from a higher level, for the current and lower execution levels. An indentation level is changed by either a % INCLUDEstatement or a rule invocation.
  • % SET RETAIN-LINE-SUFFIX-LEVELS
    Specify the number of levels of execution, including the current level and below, that use their own source line suffixes (beyond the right margin) on output, instead of the inherited value from a higher level. This identifies the source lines, enabling AMB to refer to errors.
  • % SET SECTION
    Establish an area in the output file where the MFG can append output lines. % SET SECTION acts similar to % SET LOCATION by establishing a new section in the current output file for output lines. However, % SET SECTION does not receive output in the section named in the statement.
  • % SET SPECIAL-NAMES
    Use in the Procedure Division to move all source code appearing between this statement and the next % SET statement to the end of the Special-Names paragraph. AMB generates the Special-Names header unless it is in the input source or if the rule is an EPILOGUE.
  • % SET TRACE
    Trace the generation execution of selected segments of rule source code, and produce a detailed execution log. You can turn tracing features on and off in different sections of rule logic. This ability to selectively debug reduces the volume of debug output. % SET TRACE traces all variables; you can use % SET WATCH to trace individual variables.
  • % SET TRACEBACK
    Limit the rule call trace function.
  • % SET WATCH
    Trace selected variables. Whereas % SET WATCH traces individual variables, % SET TRACE traces all variables.
  • % SET WORKING-STORAGE
    Use in the Procedure Division to move source code appearing between this statement and the next % SET statement to the end of the Working-Storage Section, immediately above the % SET END-WORKING-STORAGE statement, if coded.
  • % SET WRITE-CONTROL
    Equivalent to % SET TRACE, except that the INFO and NOINFO options are invalid. Output is written to the log, not to the generated output (POSTSOUT).
  • % UNTIL/WHILE
    Establish a loop and test a condition to execute a subordinate statement block either until or while a single or compound condition is satisfied.
  • &columnnumber+source
    Specify the output column number at which to place the associated statement source code.
  • &variable+suffix
    Append a literal suffix to a variable data name. You precede the suffix with a plus symbol (+). During processing, the plus symbol disappears--it is not replaced with a space--and the suffix appends onto the resolved variable value.
  • &ABS
    Holds the absolute value of a numeric argument. Character strings are acceptable as arguments if they can be converted to numeric type.
  • &APS-BLANK-STATUS
    Determine whether the generator ignores blank lines or passes them through to the output.
  • &APS-ELAPSED-SECONDS
    Holds the number of seconds elapsed since the start of the job. &APS-TASK-MILLISECONDS returns the number of milliseconds elapsed since the start of a job. Use these rules to examine sections of source code for performance improvement.
  • &APS-EPILOGUE
    Holds the rule name that the last % SET EPILOGUE put into the EPILOGUE queue.
  • &APS-FULL
    Holds a PIC string containing a 4-byte mainframe full-word or PC double word binary picture specification.
  • &APS-HALF
    Holds a binary PIC string containing a 2-byte mainframe half-word or PC word binary picture specification.
  • &APS-INDENT
    Holds the indentation level of the current rule. It returns the column position of the $ of the invoking rule; otherwise, it returns the column position of the left margin (usually column 7 when LANG=COBOL).
  • &APS-LAST-STATUS
    Holds the generation status since the last % SET LAST-STATUS statement executed. Use this rule to determine the success or failure of a statement sequence. For the global status of the generator process, use &APS-STATUS.
  • &APS-LOOP-LIMIT
    Holds the current value of the internal loop counter, LOOP-LIMIT.
  • &APS-MCS
    Holds the screen or window generation name from the MFG control file that is passed to the MFG.
  • &APS-MDB
    Holds the Multiple Database (MDB) generation target you specified.
  • &APS-MDC
    Holds the Multiple Data Communications (MDC) target, which is the data communication generation target value specified in your application.
  • &APS-OUTPUT-FILE
    Contains the name of the output file where the output lines are. Use % SET OUTPUT-FILE to name the output file receiving output lines.
  • &APS-OUTPUT-LOCATION
    Contains the name of the output file where the output lines are. Use % SET OUTPUT-FILE to name the output file receiving output lines.
  • &APS-PROGRAM-ID
    Holds the PROGRAM-ID name from the Identification Division.
  • &APS-PSB-NAME
    Holds the data view--PSB or subschema--specified for your program.
  • &APS-STATUS
    Holds the global status of the generator process. This value is identical to the return code that the generator returns. The value increases monotonically throughout processing as the generator encounters progressively more serious errors.
  • &APS-TASK-MILLISECONDS
    Holds the number of milliseconds the generator used since the job start. Use this rule to examine sections of source code for performance improvement. To return the number of seconds elapsed, use &APS-ELAPSED-SECONDS.
  • &AS-HEX
    Holds the contents of a variable--a hexadecimal character text string that represents the input argument. This rule accepts both numeric and text type arguments.
  • &CAT
    Equivalent to &STRING.
  • &COMPILETIME
    Holds the compile date and time in dd mmm yy hh.mm.ss format.
  • &CONCAT
    Equivalent to &STRING.
  • &DEFINED
    Determines if a specific rule or variable has a defined value and returns a true value (1) if defined, and a false value (0) if not defined.
  • &DEFVAL
    Holds the string or number value of the last &DEFINED variable in &variablename.
  • &ENCODING
    Determines whether the argument contains single-byte or double-byte characters and returns either SBCS or DBCS. &ENCODING tests each byte to determine whether the byte is within a numeric range; the range is determined by your country code. The generator returns SBCS for country codes--such as US--that do not include double byte characters.
  • &ENTRY
    Create a new built-in function by establishing a symbolic name and associating it with an entry point in a DLL. This is used with the MFG API that allows the MFG to call functions with a predefined signature that reside in a DLL.
  • &HEX-AS-NUMBER
    Convert a text string containing hexadecimal characters to an unsigned numeric value.
  • &HEX-AS-SIGNED
    Convert a text string containing hexadecimal characters to a signed 1-, 2-, or 4-byte value.
  • &HEX-AS-STRING
    Return a string containing the characters represented by the hex character sequence, thus eliminating unprintable characters in the source code.
  • &HEX-AS-UNSIGNED
    Equivalent to &HEX-AS-NUMBER.
  • &IG-DEBUG-TYPE
    Returns a string indicating whether the generator was built as an internal debug or production version. For example, if you run IG version 1.0 GA production build, then &IG-DEBUG-TYPE returns the string "PRODUCTION".
  • &IG-MAJOR-VER
    Holds a string indicating the major version number of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
  • &IG-MINOR-VER
    Holds a string indicating the minor version number of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
  • &IG-RELEASE
    Holds a string indicating the release level of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
  • &IG-TYPE
    Contains the environment the generator was built for. This function provides data to document a run, such as a comment in the generated output.
  • &IG-VER
    Contains the entire version and release level of the generator. This function provides data to document a run, such as a comment in the generated output.
  • &INDEX
    Search a string, from left to right, for the first occurrence of a character-string. Then, return a number identifying the character position.
  • &IS-ALPHA
    Examines an argument and returns 1 if the argument contains alphabetic characters only; otherwise returns 0.
  • &IS-ALPHANUMERIC
    Examines an argument and returns 1 if the argument contains alphabetic and numeric characters only: A-Z, a-z or 0-9; otherwise, returns 0.
  • &IS-DECIMAL
    Determines whether the variable contains the following valid numeric characters, and if so, returns 1; otherwise, returns 0.
  • &IS-DIGITS
    Examines an argument and returns 1 if the argument contains valid numeric digits only: 0123456789; otherwise, returns 0.
  • &IS-HEX
    Examines an argument and returns 1 if the argument contains valid hexadecimal characters: 0-9, A-F, or a-f; otherwise, returns 0.
  • &IS-LOWER
    Examines an argument and returns 1 if the variable value contains lower case characters only; otherwise, returns 0.
  • &IS-NUMERIC
    Examines an argument and returns 1 if the argument contains valid numeric characters, as follows; otherwise, returns 0.
  • &IS-PRINTABLE
    Examines an argument and returns 1 if the argument contains printable characters only: characters with hexadecimal representation 20 hex through 7E hex. Otherwise, it returns 0.
  • &IS-UPPER
    Examines an argument and returns 1 if the variable value contains upper case characters only; otherwise, returns 0.
  • &LENGTH
    Examines an argument string and returns a number specifying its length.
  • &LOW-CASE
    Equivalent to &LOWER.
  • &LOWER
    Returns a copy of a string with all upper case characters converted to lower case. Other characters remain unchanged.
  • &MAX
    Finds and holds the highest number in a set of signed numeric arguments.
  • &MIN
    Finds and holds the lowest signed value in a set of signed numeric arguments.
  • &MOD
    Determines whether a number is divisible by another by returning the numeric remainder from dividing the first argument by the second.
  • &NUM
    Construct a numeric typed value from the concatenation of the arguments. Use this function, instead of evaluation brackets, to increase the level of semantic expression in the program, that is, indicate that a string is being constructed.
  • &NUMERIC
    Determines whether a variable is represented internally in numeric form and returns 1 if numeric or 0 if non-numeric.
  • &OPSYS-MAJOR|MINOR-VER
    These functions contain the major and minor version numbers of the operating system executing the MFG.
  • &OPSYS-TYPE
    Contains the name of the executing operating system, e.g., "NT". Use this function to include a different rule file depending on where the MFG is generating.
  • &PARSE
    Parses a Customizer text string. &PARSE facilitates the following tasks.
  • &RANDOM
    Holds a pseudo-random number in the range.
  • &SEED
    Provides an initial value for the &RANDOM function. This function provides statistical control (reproducibility) over programs using &RANDOM.
  • &STRING
    Concatenates text strings, variable values, or expressions, and returns the result. Use &STRING instead of evaluation brackets to increase the level of semantic expression in the program, in the sense of indicating a string is being constructed.
  • &STRLWR
    Equivalent to &LOWER.
  • &STRUPR
    Equivalent to &UPPER.
  • &SUBST
    Holds the original string with only the first occurrence of the match string replaced by the substitute string. If the match string does not occur in the original string, &SUBST returns a copy of the original string. The original arguments remain unchanged.
  • &SUBST-ALL
    Holds the original string along with all occurrences of the match string replaced by the substitute string. If the match string does not occur in the original string, &SUBST returns a copy of the original string. The original arguments remain unchanged.
  • &SUBSTR
    Extract a substring from a string, starting with startcolumn and continuing for length .
  • &TO-LOWER
    Equivalent to &LOWER.
  • &TO-UPPER
    Equivalent to &UPPER.
  • &UP-CASE
    Equivalent to &UPPER.
  • &UPPER
    Return a copy of the original string with all lower case characters in the variable converted to upper case. Other characters remain unchanged. Use &IS-UPPER or &IS-LOWER to test if the string is upper or lower case.
Parent topic: Customizer/Micro Focus Generator (MFG)


% * (comments)

Document MFG code with comments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

%* comment text

Comments:

  • A comment can start in any column, but must appear on a line by itself.
  • Indent comments at the same or lesser indentation as the source code above it so that you do not interrupt the proper COBOL indentation of your rule.

Example:

% DEFINE $SAMPLE-RULE( arg1, arg2)
    %* comment text
    %* more comment text
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% BEGIN

Use in conditional or looping statement blocks to control the number of columns that AMB or APS moves the blocks during processing. The number of columns that you indent % BEGIN in a conditional or looping construct is the same number of columns that AMB moves the subordinate block to the left. Default processing moves the block to the starting column of the controlling conditional or looping construct.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

For example, if % BEGIN is indented four columns from an IF statement, all lines subordinate to % BEGIN move four columns to the left during processing. Any text at the same or lesser indentation than % BEGIN stops the effect of % BEGIN, and default processing resumes.

Syntax:

% BEGIN

Comments:

Do not use the Customizer function &columnnumber+source with % BEGIN.

Example:

Default processing shifts the block to the starting column of the IF statement--column 8.

Input:

Column   8...12..16
         % IF &TYPE = 'NEW'
                 05  PART-CLASS.
                     10  PART-NUMBER PIC X(5).
             01  INV-ITEM.

Output:

Column   8...12..16
         05  PART-CLASS.
             10  PART-NUMBER PIC X(5).
         01  INV-ITEM.

Override default processing with % BEGIN to shift the IF statement block to column 12.

Input:

Column   8...12..16
         % IF &TYPE = 'NEW'
             % BEGIN
                 05  PART-CLASS.
                     10  PART-NUMBER PIC X(5).
             01  INV-ITEM.

Output:

Column   8...12..16
             05  PART-CLASS.
                 10  PART-NUMBER PIC X(5).
         01  INV-ITEM.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&columnnumber+source


% DECLARE

Define a % DECLARE table made of variable assignments that can be referenced either directly (after assigning values to its subscripts), or by searching with the % LOOKUP structure.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 % DECLARE
&fieldname(&subscript1)[...(&subscriptN)]
   [% &declarepart1      [Xn|Nn|REDEFINES]
                .
                .
                .
    % &declarepartN       [Xn|Nn|REDEFINES]]
[% END]

Parameters:

&declarepart Subscript-part of &fieldname. Indentation indicates subordination. Note the following.
  • Do not use an &declarepart as a &subscript.
  • If an alphanumeric or numeric picture clause (Xn or Nn) assigns a fixed length to a &declarepart, and &fieldname has more than one &declarepart, each &declarepart needs a picture clause.
  • The maximum &declareparts sum in one DECLARE structure level is 78 bytes
  • The maximum number of &declareparts per table is 1000.
&fieldname | Name-assignment statement with zero or more subscripts and up to 78 &declareparts in each structure level.
&subscript | Set members of single- or multi-dimensional arrays. Values are numbers or strings (maximum 12 characters). For numeric values, the counter starts at 1 and increments until the end of the numeric value. There is no limit on the number of &subscripts.

Comments:

  • Assign at least one &declarepart of each &fieldname a value in order to reference other &declareparts for the same &fieldname.
  • Values of &declareparts can be changed by conventional AMB variable assignment statements.
  • &Declareparts can be accessed in the same manner as any other variable except when accessed by the following functions: &INDEX, &LENGTH, &NUMERIC, &PARSE, &SUBSTR.
  • &Declareparts can be redefined with REDEFINES or REDEF. REDEFINES indicates that it shares the same DECLARE storage as the &declarepart immediately preceding it at the same level of indentation.
  • You can REDEFINE a REDEFINED table.
  • &Subscripts can be passed as actual arguments to a rule.
  • The maximum number of % DECLARE tables per program is 200.

Examples:

Although &subscript &KEY has already been set to several values, the most common value is 1. The current values of &FILE and &KEY determine &FILE-KEY-NAME, whereas &FILE-KEY-NAME always references key 1, regardless of the &KEY value.

% DECLARE &(&FILE)-KEY-(&KEY)-A
    % &FILE-KEY-NAME        X30
    % &FILE-KEY-TYPE        X
    % &FILE-KEY-LEN         N4
% DECLARE &(&FILE)-KEY-1-A
    % &FILE-KEY-1-NAME      X30
    % &FILE-KEY-1-TYPE      X
    % &FILE-KEY-1-LEN       N4
           .
           .
           .

Access fixed-length strings of screen field attribute records that are stored in the SCRSYMB file.

% DECLARE &(&SCX-SCR)-XFLD-(&SCX-FLD)
    % &SCP-FLD-NAME                   X16
    % &SCP-REP-CNT                    N3
    % &SCP-REP-COL                    N3
    % &SCP-FLD-SHORT                  X8
    % &SCP-FLD-FI
        % &SCP-FLD-LEN                N3
        % &SCP-FLD-ROW                N3
        % &SCP-FLD-COL                N3
        % &SCP-FLD-ATTRS
            % &SCP-FLD-PROT           X
            % &SCP-FLD-INTENS-FLG     X
            % &SCP-FLD-MDT-FLG        X
            % &SCP-FLD-NUM-FLG        X
        % &SCP-FLD-EXT-ATTRS
            % &SCP-FLD-RVID-FLG       X
            % &SCP-FLD-BLINK-FLG      X
            % &SCP-FLD-UNDER-FLG      X
            % &SCP-FLD-COLOR          X2
            % &SCP-FLD-DET-FLG        X
    % &SCP-FLD-EDIT-FLG               N
    % &SCP-FLD-IM-MOD                 X

The above % DECLARE statement accommodates these fixed-length record strings stored in SCRSYMB.

% &DMOL-XFLD-1 = "PART-NBR   0 08  8  6 19UNTFFFF  F1F"
% &DMOL-XFLD-2 = "SHORT-DESC 0 0  13  8 19PNTFFFF  F0F"
% &DMOL-XFLD-3 = "LOCATION   5 3  12 12  5PNTFFFF  F0F"
           .
           .
           .

Directly reference a DECLARE table.

% DECLARE &VS-(&VSX-FILE)-KEY-(&VSX-KEY)-B
    % &VSP-FILE-KEY-VOL                X8
    % &VSP-FILE-KEY-SPACE              X20
    % &VSP-FILE-KEY-CICZ               X20
           .
           .
           .
% &VSX-FILE = "FILE3"
% &VSX-KEY = 2
           .
           .
           .
% &VOL = &VSP-FILE-KEY-VOL

Reference a DECLARE table with % LOOKUP.

% DECLARE &IMS-PCB-(&PCBX)-SEG-(&SEGX)
    % &IMS-PCB-SEG-NAME                 X30
    % &IMS-PCB-SEG-IMSNAME              X8
    % &IMS-PCB-SEG-PROCOPTS
        % &IMS-PCB-SEG-PROCOPT-GET      N
        % &IMS-PCB-SEG-PROCOPT-ISRT     N
        % &IMS-PCB-SEG-PROCOPT-REPL     N
        % &IMS-PCB-SEG-PROCOPT-DLET     N
    % &IMS-PCB-SEG-LEN                  N6
           .
           .
           .
% LOOKUP &IMS-PCB-SEG-NAME = &THE-SEG-NAME-YOU-WANT FROM 1 1
           .
           .
           .
% ELSE
           .
           .
           .

Reference a loaded table by coding a table of value assignments; use % DECLARE to name the table and define &subs for the table name.

% DECLARE &OPERATOR-(&OPR)
    % &OPERATOR            X2
    % &OPERATOR-SYMBOL     X
% &OPERATOR-1 = "EQ="
% &OPERATOR-2 = "LT<"
% &OPERATOR-3 = "GT>"
% &OPERATOR-4 = "MI-"
% &OPERATOR-5 = "PL+"
% &OPERATOR-6 = "TIX"
% &OPERATOR-7 = "DI/"

Load a table of value assignments by varying the &subs of a % DECLARE.

% DECLARE &VS-OPT-(&VSX-OPT)
    % &VS-FILE-OPT
% REPEAT VARYING &VSX-OPT FROM 1
% WHILE &DEFINED(&SCR-OPTS-<&VSX-OPT>)
    % &VS-FILE-OPT = &DEFVAL
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% LOOKUP


% DEFINE

Specify the rule name and formal arguments in a USERMACS file, or AMB program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 % DEFINE $rulename [(&formalarg1[, &formalarg2,
 % ... &formalarg3, ..., &formalarg1000])]
           statementblock
[% END]

Parameters:

&formalarg Formal argument list. Formal arguments receive their values from actual arguments in a rule call. Separate arguments with a comma and optionally one or more spaces. Enclose the argument list in parentheses.

Example:

Define a rule with three formal arguments whose values are supplied by a call that invokes the rule.

% DEFINE $ITEM-MAKER( &MM, &DATANAME, &TAIL)
            .
            .
            .
% END

Rule call

$ITEM-MAKER( 12, 'TEST-ITEM', 'S9(9) COMP SYNC VALUE -1')
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% ESCAPE

Stop processing the rule and continue processing at the line immediately following the rule call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% ESCAPE
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% IF/ELSE-IF/ELSE

Evaluate a condition.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 % IF condition1
    statementblock
 % ELSE-IF condition2
    statementblock
 % ELSE-IF conditionN
    statementblock
 % ELSE
    statementblock
[% END]

Parameters:

condition Can be a
  • Number
  • Literal enclosed in apostrophes or quotation marks
  • Variable
  • Relational operator, which can be =, NOT =, <, >, NOT <, NOT >, <=, >=
  • Value, which can be a number, a literal enclosed in apostrophes or quotation marks, or a variable

Numbers, literals, and variables must be followed by a space and a relational operator; followed by a space and a value. To specify multiple conditions, use the Boolean operators AND or OR with no parentheses.

Comments:

  • Indent each level of subordinate source code a consistent number of columns; we recommend four columns.
  • During processing, the Customizer moves statement blocks to the starting columns of their controlling % IF, % ELSE-IF, and % ELSE statements.
  • The limit of % ELSE-IFs for a single % IF is 199.
  • This structure executes identically to the S-COBOL IF/ELSE-IF/ELSE structure.
  • If an ELSE statement is followed by an IF statement (that is, ELSE ... IF instead of ELSE-IF), code the IF on the next line, and indent it. See the "Examples" below.

Examples:

Test a variable for a numeric condition.

% IF &LEN = 80
% IF &APS-INDENT < 8

Test a variable for a true condition, represented by the value 1.

% &EMPLOYEE-TYPE-A = 0
% &EMPLOYEE-TYPE-B = 1
% IF &EMPLOYEE-TYPE-B
    statementblock

Test a variable for multiple conditions.

% IF &APS-INDENT < 8 OR &APS-INDENT > 11

Code an ELSE ... IF rather than ELSE-IF.

% ELSE
    % IF &A = "ABC" OR &B = "DEF"

Nest conditional statements.

% IF condition1
   statementblock1
    % IF condition2
        % IF condition3
           statementblock2
        % ELSE-IF condition4
        % ELSE-IF condition5
           statementblock3
        % ELSE
           statementblock4
    % ELSE
       statementblock5
        % IF condition6
            % IF condition7
           statementblock6
   statementblock7
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
IF/ELSE-IF/ELSE


% INCLUDE

Open, read, and process a user-defined rule, copybook, or other file in a AMB program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% INCLUDE directory(filename)

Comments:

  • Use % INCLUDE to include copybooks when either of the following conditions are true.
    • You use a COBOL compiler other than OS/VS COBOL
    • Your copybook contains an indexed table
  • Use a COBOL COPY statement to including copybooks, when both of the following conditions are true.
    • You use an OS/VS COBOL compiler
    • Your copybook does not contain an indexed table
  • You can code % INCLUDE in a file that is INCLUDEd; you can have up to ten levels of nested INCLUDEs.
  • Always use a SY* keyword, such as SYM1, with an % INCLUDE to specify where to put the included file in the program.

Examples:

Include a rule at the top of the program.

   SYM1   % INCLUDE USERMACS(MY-RULE)

Include a rule at the bottom of the program.

   SYBT   % INCLUDE USERMACS(MY-RULE)

Include a copybook in Working-Storage.

   SYWS   % INCLUDE COPYLIB(MY-COPYBOOK)

Include a copybook in Linkage.

   SYLK   % INCLUDE COPYLIB(MY-COPYBOOK)
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
SY*


% LOOKUP

Reference a % DECLARE table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 % LOOKUP &declarepart oper searchval [FROM value [valueN
...]]
     statementblock
[% ELSE-IF condition
     statementblock
          .
          .
          .
[% ELSE
     statementblock
[% END]

Parameters:

&declarepart | Name of variable assignment in % DECLARE table.
condition | Condition can be a number or variable, followed by a space and a relational operator, followed by a space and a value. To specify multiple conditions, use the Boolean operators AND or OR with no parentheses. Relational operator can be =, NOT =, <, >, NOT <, NOT >, <=, >=. Value can be a number, a literal enclosed in apostrophes or quotation marks, or a variable.
oper | Valid operators =, NOT =, <, >, NOT <, NOT >, <=, >=.
searchval | Customizer term.
value | Starting value(s) of the low-order &subscript of the &fieldname associated with the &declarepart. Can be a constant, variable, or expression.

Comments:

  • % LOOKUP can increment up to 20 subscripts.
  • If FROM is not coded, the low-order &subscript in % DECLARE is the starting value that increments by 1 until the condition is satisfied or an undefined instance is found.
  • If the next-to-low-order DECLARE &subscript does not exist or is a string, then only the low-order &subscript enumerates by 1.

Examples:

Reference a % DECLARE table.

% DECLARE &IMS-PCB-(&PCBX)-SEG-(&SEGX)
    % &IMS-PCB-SEG-NAME                 X30
    % &IMS-PCB-SEG-IMSNAME              X8
    % &IMS-PCB-SEG-PROCOPTS
        % &IMS-PCB-SEG-PROCOPT-GET      N
        % &IMS-PCB-SEG-PROCOPT-ISRT     N
        % &IMS-PCB-SEG-PROCOPT-REPL     N
        % &IMS-PCB-SEG-PROCOPT-DLET     N
    % &IMS-PCB-SEG-LEN                  N6
                 .
                 .
% LOOKUP &IMS-PCB-SEG-NAME = &THE-SEG-NAME-YOU-WANT FROM 1 1
    do this if found
                 .
                 .
% ELSE
    do this if found
                 .
                 .
                 .

Address &declareparts of other % DECLARE structures that use some or all of the same &subscripts without an additional % LOOKUP. Strip blanks from &ALIAS before the % LOOKUP by parsing it with the function &PARSE.

% DECLARE &VS-(&VSX-FILE)-KEY-(&VSX-KEY)-B
    % &VSP-FILE-KEY-VOL           X8
    % &VSP-FILE-KEY-SPACE         X20
    % &VSP-FILE-KEY-CICZ          X20
% DECLARE &VS-(&VSX-FILE)-KEY-(&VSX-KEY)-ALIAS-(&VSX-ALIAS)
    % &VSP-FILE-KEY-ALIAS         X30
                 .
                 .
                 .
&ALIAS = &PARSE(&ALIAS)
                 .
                 .
                 .
% LOOKUP &VSP-FILE-KEY-ALIAS = &ALIAS FROM 1 1 1
    % &VOL = &VSP-FILE-KEY-VOL
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% DECLARE


% REPEAT

Establish a loop and test a condition.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

Format 1:

 % REPEAT
     statementblock
 % UNTIL|WHILE condition
    [statementblock]
[% END]

Format 2:

 % REPEAT VARYING|R-V &variable
 % ... [FROM &variable|literal|arithmeticexpr]
 % ... [BY &variable|literal|arithmeticexpr]
           statementblock
 % ... UNTIL|WHILE condition
           [statementblock]
[% END]

Format 3:

 % REPEAT VARYING|R-V &variable
 % ... [FROM &variable|literal|arithmeticexpr]
 % ... [BY &variable|literal|arithmeticexpr]
 % ... THRU|TO &variable|literal|arithmeticexpr
[% ... OR THRU|TO &variable|literal|arithmeticexpr]
[% ... OR THRU|TO &variable|literal|arithmeticexpr]
[% ... OR THRU|TO &variable|literal|arithmeticexpr]
           statementblock
[% END]

Parameters:

condition | Can be a number or variable, followed by a space and a relational operator, followed by a space and a value. To specify multiple conditions, use the Boolean operators AND or OR with no parentheses. Relational operator can be =, NOT =, <, >, NOT <, NOT >, <=, >=. Value can be a number, a literal enclosed in apostrophes or quotation marks, or a variable.
statementblock | Can contain any Customizer, COBOL, or S-COBOL statements.
variable | Customizer variable with a valid COBOL name.

Processing:

During processing:

  • Customizer moves % REPEAT statement blocks to the starting columns of their controlling % REPEAT statements.
  • The statement block subordinate to the % REPEAT, and any statement block subordinate to the % UNTIL or % WHILE, establish the loop. The loop executes until or while the condition is satisfied.
  • In formats 1 and 2, if the % UNTIL or % WHILE does not have a subordinate statement block, AMB tests the condition and does the following:
    • If the % UNTIL condition is false or the % WHILE condition is true, the loop executes the % REPEAT statement block until the condition is true or while the condition is false, respectively.
    • If the % UNTIL condition is true or the % WHILE condition is false, the loop ends, and processing resumes at the next line that has the same or less indentation as the % UNTIL or % WHILE.
  • In formats 1 and 2, if the % UNTIL does have a subordinate statement block, AMB tests the condition and does the following:
    • If the % UNTIL condition is false or the % WHILE condition is true, the loop executes the % UNTIL or % WHILE statement block and the % REPEAT statement block until the condition is true or while the condition is false, respectively.
    • If the % UNTIL condition is true or the % WHILE condition is false, the loop ends without executing the % UNTIL or % WHILE statement block, and processing resumes at the next line that has the same or less indentation as the % UNTIL or % WHILE.
  • In format 3, with the TO option, the loop executes to--but not including--its specified variable, literal, or arithmetic expression.

Comments:

  • AMB evaluates any evaluation bracket source in an % UNTIL or % WHILE statementblock at each iteration of the loop; AMB evaluates bracketed source in a % REPEAT or % REPEAT VARYING call just once.
  • If FROM is not coded, the default is the current value of the % REPEAT &variable.
  • If BY is not coded, the default is BY 1.
  • AMB provides an internal loop counter, LOOP-LIMIT, which defaults to 500. To override the default, change the value of % SET LOOP-LIMIT in the AMB CNTL file APSDBDC. You can override the default with a number as high as 999999. Because some AMB libraries reset LOOP-LIMIT to 200, you might need to reset the limit after an % INCLUDE statement.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% INCLUDE


% SET BLANK or NOBLANK

Print all blank lines that appear in the input, or suppress blank lines from printing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET BLANK
% SET NOBLANK

Aliases:

% Set Blank       % set blank
% Set Noblank     % set noblank

Comments:

  • % SET BLANK is the default.
  • Use &APS-BLANK-STATUS in your program to determine the current setting.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET COMMUNICATION

Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the Communication Section.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET COMMUNICATION [SECTION]
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET DATA

Move all source code appearing between this statement and the next % SET statement from the Procedure Division to immediately after the Data Division header.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET DATA [DIVISION]
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET EPILOGUE

Call a rule after all other Customizer processing finishes. Although you can specify only one rule call per EPILOGUE statement, you can write multiple statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMB stores all EPILOGUE rule calls in an EPILOGUE queue, and invokes them in "last in, first called" order. Assuming that you code the EPILOGUE statement in the Procedure Division, AMB places the invoked rules at the end of the Procedure Division. You can override the "last in, first called" rule by following the last % SET EPILOGUE statement with an empty % SET EPILOGUE statement-- AMB gets the rule name value from &APS-EPILOGUE.

Syntax:

% SET EPILOGUE [$rulename]

Aliases:

% Set Epilogue [$rulename]  % set epilogue [$rulename]

Comments:

The results of calling AMB rules in an EPILOGUE rule can be unpredictable. We recommend that you call only user-defined rules from an EPILOGUE rule.

Example:

Store three rule calls in the EPILOGUE queue, but invoke just $RULE-1.

% SET EPILOGUE $RULE-1
% SET EPILOGUE $RULE-2
% SET EPILOGUE $RULE-3
    %* Current value of &APS-EPILOGUE is $RULE-3.
         .
% SET EPILOGUE
    %* $RULE-3 (the current value of &APS-EPILOGUE) is
    %* eliminated from the EPILOGUE queue;
    %* the new current value of &APS-EPILOGUE is $RULE-2.
         .
% SET EPILOGUE
    %* $RULE-2 (the current value of &APS-EPILOGUE) is
    %* eliminated from the EPILOGUE queue;
    %* the new current value of &APS-EPILOGUE is $RULE-1.
    %* $RULE-1 (the current value of &APS-EPILOGUE) is
    %* invoked.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-EPILOGUE


% SET ERROR FATAL WARNING INFO

Send a message to the final message report of the compile, as follows.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Statement | Effect
% SET FATAL | Sets MFG return code to 16 and terminates execution..
% SET ERROR | Sets MFG return code to 8.
% SET WARNING | Sets MFG return code to 4.
% SET INFO | No effect on return code.

Syntax:

% SET ERROR message text
% SET FATAL message text
% SET INFO message text
% SET WARNING message text

Aliases:

% Set Error message text       % set error message text
% Set Fatal message text       % set fatal message text
% Set Info message text        % set info message text
% Set Warning message text     % set warning message text

Comments:

Variables appearing in the message text are handled in a fashion different from how they are handled in all other types of statements. No substitution is performed on variable in these statements except when the variables are enclosed in evaluation brackets.

Examples:

Send an informational message to the final message report.

Input:

&A = "ABC"
% SET INFO INVALID DOMAIN TYPE FOR &A = <&A>

Output:

INFO: INVALID DOMAIN TYPE FOR &A = ABC

Send a fatal message and then terminate the MFG.

Input:

&FCN = "PRINT"
% SET FATAL INVALID FUNCTION <&FCN> SPECIFIED

Output:

FATAL: INVALID FUNCTION PRINT SPECIFIED
Parent topic: MFG Structures
Related reference
% SET TRACEBACK
Customizer/Micro Focus Generator (MFG)


% SET FILE

Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the File Section. AMB generates the File Section header, unless it is in the input source or if the rule is an EPILOGUE rule.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET FILE [SECTION]
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET FILE-CONTROL

Move all source code appearing between this statement and the next % SET statement from the Procedure Division to the end of the File-Control paragraph. AMB generates the Input-Output Section and File-Control headers, unless they are in the input source or if the rule is an EPILOGUE rule.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET FILE-CONTROL
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET LAST-STATUS

Reset the value of the &APS-LAST-STATUS built-in function to 0. Use this rule to monitor the success or failure of one or more statements. The global status remains unchanged.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET LAST-STATUS

Aliases:

% set last-status     % Set Last-Status
% set laststatus      % Set LastStatus
% SET LASTSTATUS
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-LAST-STATUS


% SET LINKAGE

Move all source code appearing between this statement and the next % SET statement to the end of the Linkage Section. AMB generates the Linkage Section header, unless it is in the input source or if the rule is invoked by % SET EPILOGUE. Use % SET LINKAGE in the Procedure Division.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET LINKAGE [SECTION]
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET EPILOGUE


% SET LOCATION structure

Establish a location in a single output file where the MFG should place subsequent output lines. %SET-LOCATION can establish a new section in an output file, as well as reposition subsequent output lines at the end of a previously established section.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET LOCATION locationname

Parameters:

locationname Name of location. Locations are set on a per-file basis. The same location can appear in many output files.

Comments:

Use &APS-OUTPUT-LOCATION to determine the current output location.

Example:

Establish and save the current output location so that it can be reset at the end of a macro.

%* SAVE THE NAME OF THE CURRENT LOCATION
% &SAVE-LOCATION = &APS-OUTPUT-LOCATION
% SET LOCATION MYSECTION
      .
      .
      .
%* RESTORE WHERE WE WERE OUTPUTTING LINES TO PREVIOUSLY
% SET LOCATION &SAVE-LOCATION
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-OUTPUT-LOCATION


% SET LOOP-LIMIT

Override the loop counter default (500) in the AMB CNTL file APSDBDC. The internal default set by the MFG is 999999. % SET LOOP-LIMIT is often used to locate the cause of infinite loops.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET LOOP-LIMIT number

Aliases:

% set loop-limit number     % Set Loop-Limit number
% set loop limit number     % Set LoopLimit number
% SET LOOPLIMIT number

Comments:

  • Number can be as high as 2,147,483,647.
  • Because some AMB libraries reset LOOP-LIMIT to 200, you might need to reset the limit after an % INCLUDE statement .

Example:

Set the loop limit to 320000.

% SET LOOP-LIMIT 320000
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% INCLUDE


% SET NORMAL-OUTPUT

Restore the output file to the file designated by /POSTSOUT= or the /DD for POSTSOUT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET NORMAL-OUTPUT

Comments:

  • Use &APS OUTPUT-FILE to determine the current output file.
  • To establish a new output file, use % SET OUTPUT-FILE.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET TRACEBACK
% SET OUTPUT-FILE


% SET OUTPUT-FILE

Establish a new output file to receive MFG output, or redirect MFG output to a previously established output file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET OUTPUT-FILE ddname (filename)

Parameters:

ddname | Name defined on a /DD command line parameter.
filename | Root name (no path or extension) of the file to receive generated output lines.

Comment:

To reset the output to go to POSTSOUT, use % SET NORMAL-OUTPUT.

Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET NORMAL-OUTPUT


% SET PROCEDURE

Mark the end of the preceding % SET statement that moves source to other locations in the program, such as % SET WORKING-STORAGE and % SET DATA DIVISION, and return to the location of the statement, not to the beginning or end of the Procedure Division.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET PROCEDURE
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET DATA
% SET WORKING-STORAGE


% SET RETAIN-LINE-SUFFIX

Specify that generator statements use their own source line suffixes (beyond the right margin) on output, instead of the inherited value from a higher level, for the current and lower execution levels. An indentation level is changed by either a % INCLUDEstatement or a rule invocation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET RETAIN-LINE-SUFFIX

Aliases:

% set retain-line-suffix   % Set Retain-Line-Suffix
% set retain line suffix   % Set RetainLineSuffix
% SET RETAINLINESUFFIX

Comment:

To deactivate this statement, code % SET NO-RETAIN-LINE-SUFFIX.

Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% INCLUDE
Defining Customizer User Rules


% SET RETAIN-LINE-SUFFIX-LEVELS

Specify the number of levels of execution, including the current level and below, that use their own source line suffixes (beyond the right margin) on output, instead of the inherited value from a higher level. This identifies the source lines, enabling AMB to refer to errors.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

SET RETAIN-LINE-SUFFIX-LEVELS numberoflevels
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET SECTION

Establish an area in the output file where the MFG can append output lines. % SET SECTION acts similar to % SET LOCATION by establishing a new section in the current output file for output lines. However, % SET SECTION does not receive output in the section named in the statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET SECTION sectionname

Comments:

To determine the current output location, use &APS-OUTPUT-LOCATION.

Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET LOCATION structure
&APS-OUTPUT-LOCATION


% SET SPECIAL-NAMES

Use in the Procedure Division to move all source code appearing between this statement and the next % SET statement to the end of the Special-Names paragraph. AMB generates the Special-Names header unless it is in the input source or if the rule is an EPILOGUE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET SPECIAL-NAMES
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET TRACE

Trace the generation execution of selected segments of rule source code, and produce a detailed execution log. You can turn tracing features on and off in different sections of rule logic. This ability to selectively debug reduces the volume of debug output. % SET TRACE traces all variables; you can use % SET WATCH to trace individual variables.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET TRACE [option, option, ...]

Parameters:

[NO]UNP Aliases: UNPARSE, SRC, SOURCE, NOUNPARSE, NOSRC, NOSOURCE | Trace, or do not trace, each following statement. % SET TRACE UNPARSE writes each statement to the log as it executes. The statement is actually reconstituted (or UNPARSED) from the internal compiled AST form.
[NO]VARIABLES Alias: VARS, NOVARS | Write, or do not write, variable values, that the generator either accesses or updates, to the log.
[NO]EVALMESSAGES Aliases: EVALMESS, EVAL, NOEVALMESS, NOEVAL | Write, or do not write, the result of evaluation expressions to the log.
[NO]LASTSTMTS|ALL|NONE Alias: LAST, NOLAST, ON, OFF | Turns off, or turn off, the continuous trace recording of the results from UNPARSE, EVALMESS and VARS trace. % SET TRACE LAST is very useful when you encounter an infinite loop or an severe error. It records the last 50 statements and variable values executed and writes them to the log when the MFG terminates from an exception, from the user pressing Ctrl+Break, or from a % SET FATAL.
ALL|NONE | Activates, or deactivate, all trace options.
INFO | Trace back the % SET ERROR, FATAL, WARNING, INFO messages. This function is for upward compatibility. We recommend that you use % SET TRACEBACK INFO instead.
NOINFO Aliases: Noinfo, noinfo | Trace back the % SET ERROR, FATAL, WARNING, INFO messages. This function is for upward compatibility. We recommend that you use % SET TRACEBACK INFO instead.

Comments:

  • To deactivate % SET TRACE, code % SET NOTRACE.
  • To trace the generation execution of an entire rule instead of just selected segments, enter /TRACE on the command line.
  • We recommend that you use % SET TRACE and % SET WATCH only as debugging aids, not in production applications, because they impose a considerable overhead on execution efficiency.
  • In previous versions, % SET TRACE limited the rule call traceback function that accompanied the % SET INFO and % SET message statements.% SET TRACEBACK now performs that function, although you can still use % SET TRACE to do it.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET WATCH
% SET ERROR FATAL WARNING INFO
% SET TRACEBACK


% SET TRACEBACK

Limit the rule call trace function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET TRACEBACK INFO| NOINFO

Aliases:

% Set Traceback Info|Noinfo
% set traceback info|noinfo

Parameters:

INFO | Trace the % SET ERROR, FATAL, WARNING, INFO messages.
NOINFO | Trace the % SET ERROR, FATAL, WARNING messages only.

Comment:

To deactivate this statement, code % SET NOTRACEBACK.

Parent topic: MFG Structures
Related reference
% SET ERROR FATAL WARNING INFO
Customizer/Micro Focus Generator (MFG)


% SET WATCH

Trace selected variables. Whereas % SET WATCH traces individual variables, % SET TRACE traces all variables.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET WATCH [variable variable ...]|[NONE]

Aliases:

% Set Watch [variable variable ...]|[None]
% set watch [variable variable ...]|[none]

Parameters:

variable | One or more variable names to display in the log; separate each variable with a space. A variable must be defined before it can be watched.
OFF | Turn off % SET WATCH. You can also deactivate the trace by coding % SET NOWATCH.

Comments:

  • To trace the generation execution of an entire rule instead of just selected segments, enter /TRACE on the command line.
  • We recommend that you use % SET TRACE and % SET WATCH only as debugging aids, not in production applications, because they impose considerable overhead on execution efficiency.

Examples:

% SET WATCH &ABC &DEF
% SET WATCH NONE
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET TRACE


% SET WORKING-STORAGE

Use in the Procedure Division to move source code appearing between this statement and the next % SET statement to the end of the Working-Storage Section, immediately above the % SET END-WORKING-STORAGE statement, if coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET WORKING-STORAGE
         .
         .
         .
[% SET END-WORKING-STORAGE]
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


% SET WRITE-CONTROL

Equivalent to % SET TRACE, except that the INFO and NOINFO options are invalid. Output is written to the log, not to the generated output (POSTSOUT).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

% SET WRITE-CONTROL [option, option, ...]

Aliases:

% Set Write-Control [option, option, ...]
% set write-control [option, option, ...]

Comments:

To deactivate this statement, code % SET NOWRITE-CONTROL.

Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET TRACE


% UNTIL/WHILE

Establish a loop and test a condition to execute a subordinate statement block either until or while a single or compound condition is satisfied.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 % UNTIL|WHILE condition

                statementblock
                [% END]

Parameters:

condition Valid values are a
  • Constant numeric term.
  • Relational operator =, NOT =, <, >, NOT <, NOT >, <=, >=.
  • Variable that has a numeric true/false value

AND or OR may connect multiple logical terms. Do not use parentheses.

Comments:

  • During processing, the Customizer moves % UNTIL and % WHILE statement blocks to the starting columns of their controlling % UNTIL and % WHILE statements.
  • The % UNTIL statement block executes until the condition is true. Conversely, the % WHILE statement block executes while the condition is false.
  • When the % UNTIL condition is true or the % WHILE condition is false, the loop ends without executing the % UNTIL or % WHILE statement block, and processing resumes at the next line that has the same or less indentation as the % UNTIL or % WHILE.
  • AMB provides an internal loop counter, LOOP-LIMIT, which defaults to 500. To override the default, change the value of % SET LOOP-LIMIT in the AMB CNTL file APSDBDC. You can override the default with a number as high as 999999. Because some AMB libraries reset LOOP-LIMIT to 200, you might need to reset the limit after an % INCLUDE statement.
  • AMB evaluates any evaluation bracket source in an % UNTIL and % WHILE statement block at each iteration of the loop; AMB evaluates bracketed source in a % REPEAT and % REPEAT VARYING statement block just once.
  • Use % UNTIL or % WHILE with a % REPEAT loop to add a conditional test to the % REPEAT loop.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% INCLUDE
% REPEAT


&columnnumber+source

Specify the output column number at which to place the associated statement source code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&columnnumber+source

Example:

Place the literal value PIC and the value of &TAIL in output column 40.

02  &DATANAME+-&II      &40+PIC &TAIL.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&variable+suffix

Append a literal suffix to a variable data name. You precede the suffix with a plus symbol (+). During processing, the plus symbol disappears--it is not replaced with a space--and the suffix appends onto the resolved variable value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&variable+suffix

Example:

Append the suffix -ROUTINE to the variable &SCOPE and specify that they are two separate parts, not one variable called &SCOPE-ROUTINE.

Input:

% &SCOPE = 'CALC'
PERFORM &SCOPE+-ROUTINE

Output:

PERFORM CALC-ROUTINE
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&ABS

Holds the absolute value of a numeric argument. Character strings are acceptable as arguments if they can be converted to numeric type.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&ABS (number)

Aliases:

&abs (number)     &Abs (number)

Comments:

  • &ABS returns:

    arg if arg > 0

    0 if arg = 0

    -arg if arg < 0

  • The argument range is 2,147,483,648 to 2,147,483,647.

Example:

&ABS (0)  = 0
&ABS (123)  = 123
&ABS (-123)  = 123
&ABS ("-123")  = 123
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&APS-BLANK-STATUS

Determine whether the generator ignores blank lines or passes them through to the output.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-BLANK-STATUS

Alias:

&aps-blank-status     &Aps-Blank-Status
&APSBLANKSTATUS       &apsblankstatus
&ApsBlankStatus

Comments:

  • To have a rule to convert the handling of blank lines back to the way it was when the rule was invoked, capture the blank/noblank status when entering the rule. See the example below.
  • To print or suppress blank lines, use % SET BLANK or %SET NOBLANK.

Example:

When entering the rule, capture the value:

% &SAVE-BLANK-STATUS = &APS-BLANK-STATUS

When leaving the rule,

% IF &SAVE-BLANK-STATUS = "BLANK"
    % SET BLANK
% ELSE-IF &SAVE-BLANK-STATUS = "NOBLANK"
    % SET NOBLANK

Sample generated values:

&APS-BLANK-STATUS = "BLANK" (following a % SET BLANK)

&APS-BLANK-STATUS = "NOBLANK" (following a % SET NOBLANK)

Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% REPEAT


&APS-ELAPSED-SECONDS

Holds the number of seconds elapsed since the start of the job. &APS-TASK-MILLISECONDS returns the number of milliseconds elapsed since the start of a job. Use these rules to examine sections of source code for performance improvement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-ELAPSED-SECONDS

Alias:

&aps-elapsed-seconds      &Aps-Elapsed-Seconds
&apselapsedseconds        &ApsElapsedSeconds
&APSELAPSEDSECONDS

Example:

&APS-ELAPSED-SECONDS = 6
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-TASK-MILLISECONDS


&APS-EPILOGUE

Holds the rule name that the last % SET EPILOGUE put into the EPILOGUE queue.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-EPILOGUE

Aliases:

&aps-epilogue     &Aps-Epilogue
&apsepilogue      &ApsEpilogue
&APSEPILOGUE

Example:

Store three rule calls in the EPILOGUE queue, but invoke just $RULE-1.

% SET EPILOGUE $RULE-1
% SET EPILOGUE $RULE-2
% SET EPILOGUE $RULE-3
    %* Current value of &APS-EPILOGUE is $RULE-3.
         .
% SET EPILOGUE
    %* $RULE-3 (the current value of &APS-EPILOGUE) is
    %* eliminated from the EPILOGUE queue;
    %* the new current value of &APS-EPILOGUE is $RULE-2.
         .
% SET EPILOGUE
    %* $RULE-2 (the current value of &APS-EPILOGUE) is
    %* eliminated from the EPILOGUE queue;
    %* the new current value of &APS-EPILOGUE is $RULE-1.
    %* $RULE-1 (the current value of &APS-EPILOGUE) is
    %* invoked.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET EPILOGUE


&APS-FULL

Holds a PIC string containing a 4-byte mainframe full-word or PC double word binary picture specification.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-FULL

Aliases:

&aps-full     &Aps-Full
&ApsFull      &apsfull
&APSFULL

Comments:

  • &APS-FULL returns PIC S9(9) COMP.
  • To return a half-word binary PIC, use &APS-HALF.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-HALF


&APS-HALF

Holds a binary PIC string containing a 2-byte mainframe half-word or PC word binary picture specification.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-HALF

Aliases:

&aps-half      &Aps-Half
&ApsHalf       &apshalf
&APSHALF

Comments:

  • &APS-HALF returns PIC S9(4) COMP.
  • To return a full-word binary PIC, use &APS-FULL.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-FULL


&APS-INDENT

Holds the indentation level of the current rule. It returns the column position of the $ of the invoking rule; otherwise, it returns the column position of the left margin (usually column 7 when LANG=COBOL).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-INDENT

Aliases:

&aps-indent     &Aps-Indent
&apsindent      &ApsIndent
&APSINDENT

Example:

Enforce the position of certain rules.

% DEFINE $TP-ENTRY
    % IF &APS-INDENT < 8 OR &APS-INDENT > 11
        % SET ERROR $TP-ENTRY MUST BE INVOKED IN
AREA A
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&APS-LAST-STATUS

Holds the generation status since the last % SET LAST-STATUS statement executed. Use this rule to determine the success or failure of a statement sequence. For the global status of the generator process, use &APS-STATUS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-LAST-STATUS

Aliases:

&aps-last-status     &Aps-Last-Status
&apslaststatus       &ApsLastStatus
&APSLASTSTATUS

Comments:

To reset the &APS-LAST-STATUS built-in function to zero, use % SET-LAST-STATUS.

Example:

Sample generated values:

&APS-LAST-STATUS  = 0
&APS-LAST-STATUS  = 8
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET LAST-STATUS
&APS-STATUS


&APS-LOOP-LIMIT

Holds the current value of the internal loop counter, LOOP-LIMIT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-LOOP-LIMIT

Alias:

&aps-loop-limit     &Aps-Loop-Limit
&apslooplimit       &ApsLoopLimit
&APSLOOPLIMIT

Comment:

To override the internal loop counter default value, use % SET LOOP-LIMIT.

Example:

&APS-LOOP-LIMIT   = 999999
&APS-LOOP-LIMIT   = 23456
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET LOOP-LIMIT


&APS-MCS

Holds the screen or window generation name from the MFG control file that is passed to the MFG.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-MCS

Alias:

&aps-mcs     &Aps-Mcs
&apsmcs      &ApsMcs
&APSMCS

Example:

If your application screen or window name is ABC, the MFG generates:

&APS-MCS = "ABC"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&APS-MDB

Holds the Multiple Database (MDB) generation target you specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-MDB

Alias:

&aps-mdb      &Aps-Mdb
&apsmdb       &ApsMdb
&APSMDB

Example:

If your application specifies DB2 as the database target, the MFG generates:

&APS-MDB = "DB2"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&APS-MDC

Holds the Multiple Data Communications (MDC) target, which is the data communication generation target value specified in your application.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-MDC

Alias:

&aps-mdc     &Aps-Mdc
&apsmdc      &ApsMdc
&APSMDC

Example:

If your application target is CICS, the MFG generates:

&APS-MDC = "CICS"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&APS-OUTPUT-FILE

Contains the name of the output file where the output lines are. Use % SET OUTPUT-FILE to name the output file receiving output lines.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-OUTPUT-FILE

Alias:

&aps-output-file     &Aps-Output-File
&apsoutputfile       &ApsOutputFile
&APSOUTPUTFILE

Example:

Save the current output file to be reset later, for example, at the end of a macro.

%* SAVE THE NAME OF THE CURRENT FILE
% &SAVE-FILE = &APS-OUTPUT-FILE
% SET OUTPUT-FILE MYDD (MYFILE)
    .
    .
    .
%* RESTORE OUTPUTTING LINES TO PREVIOUS FILE
%* NOTE THAT EVALUATION BRACKETS ARE REQUIRED IN
%* SET STATEMENTS
% SET OUTPUT-FILE MYDD <%(&SAVE-FILE)>
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
% SET OUTPUT-FILE


&APS-OUTPUT-LOCATION

Contains the name of the output file where the output lines are. Use % SET OUTPUT-FILE to name the output file receiving output lines.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-OUTPUT-LOCATION

Alias:

&aps-output-location     &Aps-Output-Location
&apsoutputlocation       &ApsOutputLocation
&APSOUTPUTLOCATION

Example:

Save the current output location to be reset later, for example, at the end of a macro.

%* SAVE THE NAME OF THE CURRENT LOCATION
% &SAVE-LOCATION = &APS-OUTPUT-LOCATION
% SET LOCATION MYSECTION
    .
    .
    .
%* RESTORE OUTPUTTING LINES TO PREVIOUS LOCATION
% SET LOCATION &SAVE-LOCATION
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-OUTPUT-FILE


&APS-PROGRAM-ID

Holds the PROGRAM-ID name from the Identification Division.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-PROGRAM-ID

Aliases:

&aps-program-id     &Aps-Program-Id
&apsprogramid       &ApsProgramid
&APSPROGRAMID

Comment:

This function is initialized to the base name of the MAININ file, as specified on the command line. For LANG=SCOBOL only, the program name from the PROGRAM-ID statement is used.

Example:

Move the program ID name to PROGRAM-NAME.

MOVE &SQ&APS-PROGRAM-ID&SQ   TO PROGRAM-NAME
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&APS-PSB-NAME

Holds the data view--PSB or subschema--specified for your program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-PSB-NAME

Aliases:

&aps-psb-name     &Aps-Psb-Name
&apspsbname       &ApsPsbName
&APSPSBNAME

Comments:

Set this with the /PSB=psbname command line command, or assign it a value; otherwise it is ignored.

Example:

Move the program PSB name to PSBNAME.

MOVE &SQ+&APS-PSB-NAME&SQ         TO PSBNAME
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&APS-STATUS

Holds the global status of the generator process. This value is identical to the return code that the generator returns. The value increases monotonically throughout processing as the generator encounters progressively more serious errors.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-STATUS

Aliases:

&aps-status     &Aps-Status
&apsstatus      &ApsStatus
&APSSTATUS

Comments:

Unlike &APS-LAST-STATUS, you cannot reset or decrease the value of &APS-STATUS.

Examples:

When a program starts, MFG generates:

&APS-STATUS  = 0

After a % SET ERROR, MFG generates:

&APS-STATUS  = 8
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-LAST-STATUS
% SET ERROR FATAL WARNING INFO


&APS-TASK-MILLISECONDS

Holds the number of milliseconds the generator used since the job start. Use this rule to examine sections of source code for performance improvement. To return the number of seconds elapsed, use &APS-ELAPSED-SECONDS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&APS-TASK-MILLISECONDS

Alias:

&aps-task-milliseconds     &Aps-Task-Milliseconds
&apstaskmilliseconds       &ApsTaskMilliseconds
&APSTASKMILLISECONDS

Example:

&APS-TASK-MILLISECONDS = 19836
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&APS-ELAPSED-SECONDS


&AS-HEX

Holds the contents of a variable--a hexadecimal character text string that represents the input argument. This rule accepts both numeric and text type arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Use this rule for debugging programs. To test if a value is hexadecimal, use &IS-HEX; to convert the hexadecimal value, use the &HEX rules.

Syntax:

&AS-HEX (&variablename)

Alias:

&as-hex (&variablename)     &As-Hex (&variablename)
&ashex (&variablename)      &AsHex (&variablename)
&ASHEX (&variablename)

Example:

&AS-HEX (1)           = "1"
&AS-HEX (2)           = "2"
&AS-HEX (-1)          = "FFFFFFFF"
&AS-HEX (1024)        = "400"
&AS-HEX ("1")         = "31"
&AS-HEX ("ABCDEFG")   = "41424344454647"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&CAT

Equivalent to &STRING.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&STRING


&COMPILETIME

Holds the compile date and time in dd mmm yy hh.mm.ss format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&COMPILETIME

Aliases:

&compiletime     &Compiletime

Example:

Assign the value of &COMPILETIME to the variable &TODAY.

DATE-COMPILED.                  &COMPILETIME.
% &TODAY = &COMPILETIME

Sample generated value:

&COMPILETIME = "09 SEP 94 14.06.46"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&CONCAT

Equivalent to &STRING.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&STRING


&DEFINED

Determines if a specific rule or variable has a defined value and returns a true value (1) if defined, and a false value (0) if not defined.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&DEFINED( $rulename|&variablename)

Aliases:

&defined( $rulename|&variablename)
&Defined( $rulename|&variablename)

Comments:

Variable names used as formal parameters to rules can become undefined. All other variable types, such as global symbols, remain defined until the program terminates.

Examples:

If &FILE-2 and &FILE-3 have defined values, add them to the CLOSE statement.

CLOSE &FILE-1
% IF &DEFINED( &FILE-2)
    ... &FILE-2
% IF &DEFINED( &FILE-3)
    ... &FILE-3

Save two symbol lookups every time a loop is performed. You can replace this code

% REPEAT VARYING &SC-I FROM 1
% WHILE &DEFINED( &<&SCR>-FLD-<&SC-I>)
    % &VAR = &<&SCR>-FLD-<&SC-I>
% END

With this code.

% REPEAT VARYING &SC-I FROM 1
% WHILE &DEFINED( &<&SCR>-FLD-<&SC-I>)
    % &VAR= &DEFVAL
% END
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&DEFVAL


&DEFVAL

Holds the string or number value of the last &DEFINED variable in &variablename.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&DEFVAL

Aliases:

&defval      &Defval

Comments:

&DEFVAL is an abbreviation that executes faster than the equivalent, more explicit code.

Example:

You can replace the following code:

% REPEAT VARYING &SC-I FROM 1
% WHILE &DEFINED( &<&SCR>-FLD-<&SC-I>)
    % &VAR = &<&SCR>-FLD-<&SC-I>
% END

With this code.

% REPEAT VARYING &SC-I FROM 1
% WHILE &DEFINED( &<&SCR>-FLD-<&SC-I>)
    % &VAR = &DEFVAL
% END
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&DEFINED


&ENCODING

Determines whether the argument contains single-byte or double-byte characters and returns either SBCS or DBCS. &ENCODING tests each byte to determine whether the byte is within a numeric range; the range is determined by your country code. The generator returns SBCS for country codes--such as US--that do not include double byte characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Use this rule for debugging programs. To test if a value is hexadecimal, use &IS-HEX; to convert the hexadecimal value, use the &HEX rules.

Syntax:

&ENCODING (&variablename)

Alias:

&encoding (&variablename)
&Encoding (&variablename)

Example:

The following assume the US country code.

&ENCODING ("ABCD")  = "SBCS"
&ENCODING (&HEX-AS-STRING ("4142"))  = "SBCS"
&ENCODING (&HEX-AS-STRING ("8142"))  = "SBCS"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&HEX-AS-NUMBER
&HEX-AS-SIGNED
&HEX-AS-STRING
&HEX-AS-UNSIGNED
&IS-HEX


&ENTRY

Create a new built-in function by establishing a symbolic name and associating it with an entry point in a DLL. This is used with the MFG API that allows the MFG to call functions with a predefined signature that reside in a DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&ENTRY (DLLname, entrypointname)

Alias:

&entry     &Entry

Parameters:

DLLname | DLL name, which is a string value, such as F:\MYDLLS\MYFUNCS.DLL.
entrypointname | Name of an entry point exported by the DLL.

Example:

The following statement

% &READDB = &ENTRY ("F:\ODBC\ODBCFCNS.DLL", "PerformSelect")

Defines a new function name, &READDB, which can be called like any other built-in function.

% &RC = &READDB ("CUSTDB", "SELECT * FROM CUSTOMER")
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&HEX-AS-NUMBER

Convert a text string containing hexadecimal characters to an unsigned numeric value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&HEX-AS-NUMBER
  (&variablename)

Aliases:

&hex-as-number (&variablename) &Hex-As-Number(&variablename)
&hexasnumber (&variablename)   &HexAsNumber (&variablename)
&HEXASNUMBER (&variablename)

&HEX-AS-UNSIGNED (&variablename)&hex-as-unsigned (&variablename)
&Hex-As-Unsigned (&variablename)&HEXASUNSIGNED (&variablename)
&hexasunsigned (&variablename) &HexAsUnsigned (&variablename)

Comments:

  • The generator converts hex strings to their unsigned equivalent. Exception A sequence of eight hex characters can be converted to a signed number because the generator deals with signed fullwords. Because the numeric type is always signed, the generator converts hex values greater than 7FFFFFFF to the signed value (a negative value) and issues a warning message.
  • The string being converted should:
    • Contain hexadecimal values.
    • Not be empty.
    • Have string symbol type of text.

Example:

&HEX-AS-NUMBER ("00")  = 0
&HEX-AS-NUMBER ("01")  = 1
&HEX-AS-NUMBER ("0A")  = 10
&HEX-AS-NUMBER ("0F")  = 15
&HEX-AS-NUMBER ("10")  = 16
&HEX-AS-NUMBER ("13")  = 19
&HEX-AS-NUMBER ("6F")  = 111
&HEX-AS-NUMBER ("7F")  = 127
&HEX-AS-NUMBER ("FF")  = 255
&HEX-AS-NUMBER ("F")   = 15
&HEX-AS-NUMBER ("1000")  = 4096
&HEX-AS-NUMBER ("4142")  = 16962
&HEX-AS-NUMBER ("6FFF")  = 28671
&HEX-AS-NUMBER ("7000")  = 28672
&HEX-AS-NUMBER ("7FFF")  = 32767
&HEX-AS-NUMBER ("FFFF")  = 65535
&HEX-AS-NUMBER ("FFFFF")  = 1048575
&HEX-AS-NUMBER ("100000")    = 1048576
&HEX-AS-NUMBER ("10000000")  = 268435456
&HEX-AS-NUMBER ("7FFFFFFF")  = 2147483647
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&HEX-AS-SIGNED

Convert a text string containing hexadecimal characters to a signed 1-, 2-, or 4-byte value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&HEX-AS-SIGNED (&variablename[, &targetlength])

Aliases:

&hex-as-signed (&variablename[, &targetlength])
&Hex-As-Signed (&variablename[, &targetlength])
&HEXASSIGNED (&variablename[, &targetlength])
&hexassigned (&variablename[, &targetlength])
&HexAsSigned (&variablename[, &targetlength])

Comments:

When converting hex to an equivalent binary string, &targetlength determines which bit is interpreted as a sign bit. For example,

&HEX-AS-SIGNED ("7F", 1) = 127
&HEX-AS-SIGNED ("80", 1) = -128

For hex 80 (binary 10000000), the eighth bit from the right (counting the rightmost bit as 1) is the sign bit, but

&HEX-AS-SIGNED ("7F", 2) = 127
&HEX-AS-SIGNED ("80", 2) = 256

For hex 80 (binary 0000000010000000), the 16th bit from the right is the sign bit.

Example:

&HEX-AS-SIGNED ("00")  = 0
&HEX-AS-SIGNED ("01")  = 1
&HEX-AS-SIGNED ("0A")  = 10
&HEX-AS-SIGNED ("0F")  = 15
&HEX-AS-SIGNED ("10")  = 16
&HEX-AS-SIGNED ("13")  = 19
&HEX-AS-SIGNED ("6F")  = 111
&HEX-AS-SIGNED ("7F")  = 127
&HEX-AS-SIGNED ("80")  = 128
&HEX-AS-SIGNED ("FF")  = 255
&HEX-AS-SIGNED ("F")   = 15
&HEX-AS-SIGNED ("00", 1) = 0
&HEX-AS-SIGNED ("01", 1) = 1
&HEX-AS-SIGNED ("0A", 1) = 10
&HEX-AS-SIGNED ("0F", 1) = 15
&HEX-AS-SIGNED ("10", 1) = 16
&HEX-AS-SIGNED ("13", 1) = 19
&HEX-AS-SIGNED ("6F", 1) = 111
&HEX-AS-SIGNED ("7F", 1) = 127
&HEX-AS-SIGNED ("80", 1) = -128
&HEX-AS-SIGNED ("FF", 1) = -1
&HEX-AS-SIGNED ("FF", "1") = 255
&HEX-AS-SIGNED ("FF", 3) = 255
&HEX-AS-SIGNED ("1000")  = 4096
&HEX-AS-SIGNED ("4142")  = 16962
&HEX-AS-SIGNED ("6FFF")  = 28671
&HEX-AS-SIGNED ("7000")  = 28672
&HEX-AS-SIGNED ("7FFF")  = 32767
&HEX-AS-SIGNED ("8000")  = 32768
&HEX-AS-SIGNED ("FFFF")  = 65535
&HEX-AS-SIGNED ("1000", 2) = 4096
&HEX-AS-SIGNED ("4142", 2) = 16962
&HEX-AS-SIGNED ("6FFF", 2) = 28671
&HEX-AS-SIGNED ("7000", 2) = 28672
&HEX-AS-SIGNED ("7FFF", 2) = 32767
&HEX-AS-SIGNED ("8000", 2) = -32768
&HEX-AS-SIGNED ("FFFF", 2) = -1
&HEX-AS-SIGNED ("100000")    = 1048576
&HEX-AS-SIGNED ("10000000")  = 268435456
&HEX-AS-SIGNED ("7FFFFFFF")  = 2147483647
&HEX-AS-SIGNED ("80000000")  = -2147483648
&HEX-AS-SIGNED ("FFFFFFFF")  = -1
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&HEX-AS-STRING

Return a string containing the characters represented by the hex character sequence, thus eliminating unprintable characters in the source code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&HEX-AS-STRING (&variablename)

Aliases:

&hex-as-string (&variablename) &Hex-As-String (&variablename)
&hexasstring (&variablename) &HexAsString (&variablename)
&HEXASSTRING (&variablename)

Comments:

The string being converted should:

  • Contain hexadecimal values.
  • Have an even number of digits.
  • Not be empty.
  • Have a string symbol type of text.

Example:

&HEX-AS-STRING ("00") = (unprintable result)

&HEX-AS-STRING ("01") = (unprintable result)

&HEX-AS-STRING ("10") = (unprintable result)

&HEX-AS-STRING ("13") = (unprintable result)

&HEX-AS-STRING ("FF") = (unprintable result)

&HEX-AS-STRING ("30414243") = "0ABC"

&HEX-AS-STRING ("1000") = (unprintable result)

&HEX-AS-STRING ("100000") = (unprintable result)

&HEX-AS-STRING ("10000000") = (unprintable result)

&HEX-AS-STRING ("7FFFFFFF") = (unprintable result)

&HEX-AS-STRING ("FFFFFFFF") = (unprintable result)

Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&HEX-AS-UNSIGNED

Equivalent to &HEX-AS-NUMBER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&HEX-AS-NUMBER


&IG-DEBUG-TYPE

Returns a string indicating whether the generator was built as an internal debug or production version. For example, if you run IG version 1.0 GA production build, then &IG-DEBUG-TYPE returns the string "PRODUCTION".
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Note: This function is mainly for Micro Focus internal use. Customers receive only the production build.

Syntax:

&IG-DEBUG-TYPE
&IgDebugType
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IG-MAJOR-VER

Holds a string indicating the major version number of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Compare ranges of versions with relational comparison operators.
  • Document a run, such as a comment in the generated output.
  • Test a rules program that depends on the features in a specific MFG version.

Syntax:

&IG-MAJOR-VER

Aliases:

&ig-major-ver     &Ig-Major-Ver
&igmajorver       &IgMajorVer
&IGMAJORVER

Comment:

Because generators prior to Version 1.2 do not support this function, you may find this function more useful in the future.

Examples:

For code that depends on the major version of the generator, you can code:

% IF &IG-MAJOR-VER = "2"
    %* Logic that takes advantage of release 2
    %* features only% ELSE
    %* Logic for generating with any other version
% END

When executing IG Version 1.2, MFG generates:

&IG-MAJOR-VER = "1"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&NUM


&IG-MINOR-VER

Holds a string indicating the minor version number of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Compare ranges of versions with relational comparison operators.
  • Document a run, such as a comment in the generated output.
  • Test a rules program that depends on the features in a specific MFG version.

Syntax:

&IG-MINOR-VER

Aliases:

&ig-minor-ver     &Ig-Minor-Ver
&igminorver       &IgMinorVer
&IGMINORVER

Comment:

Because generators prior to Version 1.2 do not support this function, you may find this function more useful in the future.

Examples:

For code that depends on both the major and minor version of the generator, you can code

% IF &IG-MAJOR-VER = "1"
    % IF &IG-MINOR-VER = "2"
        %* Logic for using Version 1.2
    % ELSE-IF &OPSYS-MINOR-VER = "1"
        %* Logic for using Version 1.1
    % END
% END

When executing IG Version 1.2, MFG generates:

&IG-MINOR-VER = "2"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&NUM


&IG-RELEASE

Holds a string indicating the release level of the generator. Use &NUM to convert the returned string to a number you can use, for example, to:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Compare ranges of versions with relational comparison operators.
  • Document a run, such as a comment in the generated output.
  • Test a rules program that depends on the features in a specific MFG version.

Syntax:

&IG-RELEASE

Aliases:

&ig-release     &Ig-Release
&igrelease      &IgRelease
&IGRELEASE

Comments:

  • Although other strings are possible, the usual values are: "FT" for field-test, "ESP" for early support program, and "GA" for general availability
  • Because generators prior to Version 1.2 do not support this function, you may find this function more useful in the future.

Example:

When executing IG Version 1.2 GA, MFG generates:

&IG-RELEASE = "GA"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&NUM


&IG-TYPE

Contains the environment the generator was built for. This function provides data to document a run, such as a comment in the generated output.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IG-TYPE

Aliases:

&ig-type      &Ig-Type
&igtype       &IgType
&IGTYPE

Example:

When executing an MFG version built to run under Windows NT, MFG generates:

&IG-TYPE = "NT"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IG-VER

Contains the entire version and release level of the generator. This function provides data to document a run, such as a comment in the generated output.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IG-VER

Aliases:

&ig-ver     &Ig-Ver
&igver      &IgVer
&IGVER

Comment:

Because generators prior to Version 1.2 do not support this function, you may find this function more useful in the future.

Example:

When executing IG Version 1.2 GA, MFG generates:

&IG-VER = "INTERSOLV Generator (IG) Version 1.2 GA"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&INDEX

Search a string, from left to right, for the first occurrence of a character-string. Then, return a number identifying the character position.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&INDEX( `wholestring', `characterstring')

Aliases:

&index( `wholestring', `characterstring')
&Index( `wholestring', `characterstring')

Comments:

  • Delimiting quotes are not included in the character position.
  • &INDEX returns 0 when there is no character string.

Example:

Search for the first occurrence of the character string IS. The value 3 is returned because IS first occurs in the third position.

&INDEX( 'THIS IS AN EXAMPLE', 'IS')
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IS-ALPHA

Examines an argument and returns 1 if the argument contains alphabetic characters only; otherwise returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IS-ALPHA (&variablename)

Aliases:

&is-alpha (&variablename)     &Is-Alpha (&variablename)
&isalpha (&variablename)      &IsAlpha (&variablename)
&ISALPHA (&variablename)

Comments:

  • If &variablename is numeric, &IS-ALPHA returns 0.
  • The original argument remains unchanged.
  • National characters such as #&$ are not considered alphabetic.

Examples:

&IS-ALPHA ("123")         = 0
&IS-ALPHA ("+123")        = 0
&IS-ALPHA ("-123")        = 0
&IS-ALPHA ("ABC")         = 1
&IS-ALPHA ("abc")         = 1
&IS-ALPHA ("abc%")        = 0
&IS-ALPHA ("")            = 0
&IS-ALPHA (1)             = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IS-ALPHANUMERIC

Examines an argument and returns 1 if the argument contains alphabetic and numeric characters only: A-Z, a-z or 0-9; otherwise, returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IS-ALPHANUMERIC (&variablename)

Aliases:

&is-alphanumeric (&variablename)
&Is-Alphanumeric (&variablename)
&ISALPHANUMERIC (&variablename)
&isalphanumeric (&variablename)
&IsAlphanumeric (&variablename)

Comments:

  • If &variablename is numeric, and has a non-negative value, it is considered to be alphanumeric. However, a negative number--because of its minus sign--is not considered to be alphanumeric.
  • National characters, such as # & $, are not considered alphabetic.
  • The original argument remains unchanged.

Examples:

&IS-ALPHANUMERIC ("123")  = 1
&IS-ALPHANUMERIC ("+123") = 0
&IS-ALPHANUMERIC ("-123") = 0
&IS-ALPHANUMERIC ("ABC")  = 1
&IS-ALPHANUMERIC ("abc")  = 1
&IS-ALPHANUMERIC ("abc%") = 0
&IS-ALPHANUMERIC ("")     = 0
&IS-ALPHANUMERIC (1)      = 1
&IS-ALPHANUMERIC (-1)     = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IS-DECIMAL

Determines whether the variable contains the following valid numeric characters, and if so, returns 1; otherwise, returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Optional + or - in the first position
  • Digits 0-9 in any position
  • Decimal point in any position

Syntax:

&IS-DECIMAL (&variablename)

Aliases:

&is-decimal (&variablename)      &Is-Decimal (&variablename)
&isdecimal (&variablename)       &IsDecimal (&variablename)
&ISDECIMAL (&variablename)

Comments:

  • Arguments with decimals are not storable as numeric types.
  • A single decimal point is permitted.
  • MFG accepts both text and numeric type arguments.

Examples:

&IS-DECIMAL ("123")       = 1
&IS-DECIMAL ("+123")      = 1
&IS-DECIMAL ("-123")      = 1
&IS-DECIMAL ("123-")      = 0
&IS-DECIMAL ("123.")      = 1
&IS-DECIMAL (123)         = 1
&IS-DECIMAL (0)           = 1
&IS-DECIMAL (-123)        = 1
&IS-DECIMAL (".0123")     = 1
&IS-DECIMAL ("1.23")      = 1
&IS-DECIMAL ("1.2.3")     = 0
&IS-DECIMAL ("123A")      = 0
&IS-DECIMAL ("")          = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IS-DIGITS

Examines an argument and returns 1 if the argument contains valid numeric digits only: 0123456789; otherwise, returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IS-DIGITS (&variablename)

Aliases:

&is-digits (&variablename)     &Is-Digits (&variablename)
&&isdigits (&variablename)     &IsDigits (&variablename)
ISDIGITS (&variablename)

Comments:

  • Signs and decimal points are not considered digits.
  • A negative numeric type argument value--because of the minus sign--is not considered to be all digits.
  • The original argument remains unchanged.

Examples:

&IS-DIGITS ("123")        = 1
&IS-DIGITS ("+123")       = 0
&IS-DIGITS ("-123")       = 0
&IS-DIGITS ("123-")       = 0
&IS-DIGITS ("123.")       = 0
&IS-DIGITS (123)          = 1
&IS-DIGITS (-123)         = 0
&IS-DIGITS ("123A")       = 0
&IS-DIGITS ("")           = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&IS-DECIMAL
&NUMERIC


&IS-HEX

Examines an argument and returns 1 if the argument contains valid hexadecimal characters: 0-9, A-F, or a-f; otherwise, returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IS-HEX (&variablename)

Aliases:

&is-hex (&variablename)     &Is-Hex (&variablename)
&ishex (&variablename)      &IsHex (&variablename)
&ISHEX (&variablename)

Comment:

If &variablename is a numeric type argument, MFG converts it into a text string. A negative number--because it has a minus sign--is not considered a hex string.

Examples:

&IS-HEX ("01234567890")   = 1
&IS-HEX ("ABCDEF")        = 1
&IS-HEX ("abcdef")        = 1
&IS-HEX ("+ABC")          = 0
&IS-HEX ("-123")          = 0
&IS-HEX ("A ")            = 0
&IS-HEX ("Af")            = 1
&IS-HEX ("AG")            = 0
&IS-HEX ("")              = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IS-LOWER

Examines an argument and returns 1 if the variable value contains lower case characters only; otherwise, returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IS-LOWER (&variablename)

Aliases:

&is-lower (&variablename)     &Is-Lower (&variablename)
&islower (&variablename)      &IsLower (&variablename)
&ISLOWER (&variablename)

Comment:

If &variablename is a numeric type, &IS-LOWER returns 0.

Examples:

&IS-LOWER ("ABC")         = 0
&IS-LOWER ("abc")         = 1
&IS-LOWER ("abc%")        = 0
&IS-LOWER ("AbCd")        = 0
&IS-LOWER ("123A")        = 0
&IS-LOWER ("")            = 0
&IS-LOWER (123)           = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IS-NUMERIC

Examines an argument and returns 1 if the argument contains valid numeric characters, as follows; otherwise, returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Optional + or - in the first position
  • Digits 0-9 in any position

Syntax:

&IS-NUMERIC (&variablename)

Aliases:

&is-numeric (&variablename) &Is-Numeric (&variablename)
&isnumeric (&variablename)  &IsNumeric (&variablename)
&ISNUMERIC (&variablename)

Comments:

  • A return value 1 lets you store the argument as a numeric type.
  • Note that the &NUMERIC function tests only whether the argument is of numeric type (internal storage format).

Examples:

&IS-NUMERIC ("123")       = 1
&IS-NUMERIC ("+123")      = 1
&IS-NUMERIC ("-123")      = 1
&IS-NUMERIC ("123-")      = 0
&IS-NUMERIC ("123.")      = 0
&IS-NUMERIC (123)         = 1
&IS-NUMERIC (0)           = 1
&IS-NUMERIC (-123)        = 1
&IS-NUMERIC ("123A")      = 0
&IS-NUMERIC ("")          = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&NUMERIC


&IS-PRINTABLE

Examines an argument and returns 1 if the argument contains printable characters only: characters with hexadecimal representation 20 hex through 7E hex. Otherwise, it returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IS-PRINTABLE (&variablename)

Aliases:

&-printable (&variablename)&Is-Printable (&variablename)
&isprintable (&variablename) &IsPrintable (&variablename)
&ISPRINTABLE (&variablename)

Comment:

If &variablename is a numeric type, MFG converts it to a text string. For example, 123 becomes "123".

Examples:

&IS-PRINTABLE ("ABC")   =  0  (the string contains a tab)
&IS-PRINTABLE ("ABC ")    = 1
&IS-PRINTABLE ("ABC")     = 1
&IS-PRINTABLE ("abc")     = 1
&IS-PRINTABLE ("abc%")    = 1
&IS-PRINTABLE ("AbCd")    = 1
&IS-PRINTABLE ("123A")    = 1
&IS-PRINTABLE (123)       = 1
&IS-PRINTABLE ("")        = 0
&IS-PRINTABLE (&HEX-AS-STRING("1F")) = 0
&IS-PRINTABLE (&HEX-AS-STRING("20")) = 1
&IS-PRINTABLE (&HEX-AS-STRING("7E")) = 1
&IS-PRINTABLE (&HEX-AS-STRING("7F")) = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&IS-UPPER

Examines an argument and returns 1 if the variable value contains upper case characters only; otherwise, returns 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&IS-UPPER (&variablename)

Aliases:

&is-upper (&variablename)   &Is-Upper (&variablename)
&isupper (&variablename)    &IsUpper (&variablename)
&ISUPPER (&variablename)

Comments:

  • If &variablename is a numeric type, &IS-UPPER returns 0.
  • The original argument remains unchanged.

Examples:

&IS-UPPER ("ABC")         = 1
&IS-UPPER ("abc")         = 0
&IS-UPPER ("abc%")        = 0
&IS-UPPER ("AbCd")        = 0
&IS-UPPER ("123A")        = 0
&IS-UPPER ("")            = 0
&IS-UPPER (123)           = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&LENGTH

Examines an argument string and returns a number specifying its length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&LENGTH( string)

Aliases:

&length( string)
&Length( string)

Comments:

Leading and trailing blanks are included as part of a string; delimiting quotation marks are not.

Example:

The value 10 is returned for this example.

&LENGTH( `FOUNDATION')
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&LOW-CASE

Equivalent to &LOWER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&LOWER


&LOWER

Returns a copy of a string with all upper case characters converted to lower case. Other characters remain unchanged.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&LOWER (string)

Aliases:

&lower (string)        &Lower (string)
&TO-LOWER (string)     &to-lower (string)
&TOLOWER (string)      &To-Lower (string)
&tolower (string)      &ToLower (string)&STRLWR (string) &strlwr (string)
&Strlwr (string)&LOW-CASE (string) &low-case (string)
&Low-Case (string)     &lowcase (string)
&LOWCASE (string)      &LowCase (string)

Examples:

&LOWER ("ABC")  = "abc"
&LOWER ("Ab1%") = "ab1%"
&LOWER ("abc")  = "abc"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&LOW-CASE


&MAX

Finds and holds the highest number in a set of signed numeric arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&MAX (number, number, ...)

Aliases:

&max (number, number, ...)
&Max (number, number, ...)

Comments:

  • Character strings are acceptable arguments if they can be converted to numeric types.
  • There is no limit on the number of arguments.

Examples:

&MAX (-25, 1)  = 1
&MAX (25, 1)  = 25
&MAX (25, 1, 101)  = 101
&MAX (25, 1, "101")  = 101
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&MIN

Finds and holds the lowest signed value in a set of signed numeric arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&MIN (number, number, ...)

Aliases:

&min (number, number, ...)
&Min (number, number, ...)

Comments:

  • Character strings are acceptable arguments if they can be converted to numeric types.
  • There is no limit on the number of arguments.

Examples:

&MIN (-25, 1)  = -25
&MIN (25, 1)  = 1
&MIN (25, 1, 101)  = 1
&MIN (25, 1, "101")  = 1
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&MOD

Determines whether a number is divisible by another by returning the numeric remainder from dividing the first argument by the second.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&MOD (dividend, divisor)

Aliases:

&mod (dividend, divisor)     &Mod (dividend, divisor)
&&modulo (dividend, divisor) &Modulo (dividend, divisor)
MODULO (dividend, divisor)

Examples:

&MOD (25, 6)  = 1
&MOD (-25, 6)  = -1
&MOD (25, -6)  = 1
&MOD (-25, -6)  = -1
&MOD (25, 7)  = 4
&MOD (25, 1)  = 0
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&NUM

Construct a numeric typed value from the concatenation of the arguments. Use this function, instead of evaluation brackets, to increase the level of semantic expression in the program, that is, indicate that a string is being constructed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&NUM (number, number, ...)

Aliases:

&num (number, number, ...)    &Num (number, number, ...)
&number (number, number, ...) &Number (number, number, ...)
&NUMBER (number, number, ...)

Examples:

&NUM (25, 1, "101")  = 251101
&NUM ("-", 25, 1, "101")  = -251101
&NUM ("+", 25, 1, "101")  = 251101
&NUM ("+", 25, &I, "101") = 257101
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&NUMERIC

Determines whether a variable is represented internally in numeric form and returns 1 if numeric or 0 if non-numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&NUMERIC( &variablename)

Aliases:

&numeric( &variablename)     &Numeric( &variablename)

Comments:

Note that &NUMERIC ("123") returns 0 (false), because the argument is a string. To test whether a string contains a numerics, use &IS-NUMERIC or &IS-DIGITS.

Example:

Set &II to true and test for its numeric value.

% &II = 1
% IF &NUMERIC( &II)
    /* YOU WILL GET THIS TEXT
    .
    .
    .
% END
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&IS-DIGITS
&IS-NUMERIC


&OPSYS-MAJOR|MINOR-VER

These functions contain the major and minor version numbers of the operating system executing the MFG.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&OPSYS-MAJOR-VER
&OPSYS-MINOR-VER

Aliases:

&opsys-major-ver     &Opsys-Major-Ver
&OPSYSMAJORVER
&opsysmajorver       &OpsysMajorVer&opsys-minor-ver &Opsys-Minor-Ver
&opsysminorver       &OpsysMinorVer
&OPSYSMINORVER

Examples:

For code that depends on the version of the operating system platform where the generator runs, you could code the following.

% IF &OPSYS-MAJOR-VER = "5"
    % IF &OPSYS-MINOR-VER = "1"
        %* Logic for generating under Version 5.1
    % ELSE-IF &OPSYS-MINOR-VER = "5"
        %* Logic for generating under Version 5.5
    % END
% END

When executing under Windows NT version 3.5, MFG generates:

&OPSYS-MINOR-VER = "5"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&OPSYS-TYPE

Contains the name of the executing operating system, e.g., "NT". Use this function to include a different rule file depending on where the MFG is generating.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&OPSYS-TYPE

Aliases:

&opsys-type     &Opsys-Type
&opsystype      &OpsysType
&OPSYSTYPE

Comment:

This function returns "NT" for Windows NT.

Examples:

For code that depends on the platform on which the generator runs, you could code the following.

% IF &OPSYS-TYPE = "NT"
    %* Logic for generating under Windows NT
% ELSE-IF &OPSYS-TYPE = "WIN32S"
    %* Logic for generating under Win32s
% END
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&PARSE

Parses a Customizer text string. &PARSE facilitates the following tasks.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Parsing rule arguments or parameter strings that have embedded punctuation, operators, or keywords. You can split the string into two strings--the part preceding and the part following the first occurrence of the operator string. Then, you can skip past embedded single- or double-quoted strings when looking for the first occurrence of the operator string.
  • Eliminating the trailing and leading spaces from both of the new strings, making them easier to read.
  • Parsing long parameter strings by loops. You can reload the string that follows the operator string into the original string variable.

Syntax:

&PARSE( &string[value])

Aliases:

&parse( &string[value])     &Parse( &string[value])

Parameters:

&String Variable with a string value.
Value Can be:
  • A literal text string.
  • A variable with a string value.
  • A number (the number turns into a string).

Comments:

  • Value is matched against the string value of &string. The part of the &string value following the match is stored back in &string, with leading and trailing spaces eliminated. Then, the part of the &string value preceding the match returns as the value of the parsing function, with leading and trailing spaces eliminated.
  • When matching the second string inside the first string, the match does not begin within a string that is embedded (quoted) within the first string.
  • When using &PARSE with only one argument, the argument must be a variable with a string value. The string in the argument is assigned the null string and the original string is returned as the value of the parsing function with leading and trailing spaces trimmed.

Examples:

If &STR is assigned by the statement % &STR = " X, PARM = `A, B', Y", then

This statement... | Is equivalent to...
% PART = &PARSE( &STR, ",") | % &STR = "PARM = `A, B', Y" % &PART = "X"

If &PARSE is used again on &STR:

This statement... | Is equivalent to...
% &PART = &PARSE( &STR, ",") | % &STR = "Y" % &PART = "PARM = `A, B'"

Note that the comma embedded in `A, B' is ignored.

If &PARSE is used again on &STR:

This statement... | Is equivalent to...
% &PART = &PARSE( &STR, ",") | % &STR = "" % &PART = "Y"

And finally, if &PARSE is used again on &STR:

This statement... | Is equivalent to...
% &PART = &PARSE( &STR, ",") | % &STR = "" % &PART = ""

In other words, after processing, you get the following result.

% &PART = &PARSE( &STR, ",")

Where

  • &PART contains what was in the value of &STR up to but not including the first comma (with leading and trailing spaces trimmed).
  • &STR contains what was in the value of &STR, after and not including the first comma (with leading and trailing spaces trimmed).

IF &STR is assigned by the statement % &STR = " ABC ":

This statement... | Is equivalent to...
% &PART = &PARSE( &STR) | % &STR = "" % &PART = "ABC"

Because the argument is restored before the &PARSE value is passed, &PARSE eliminates spaces and returns the string to the original variable.

If % &STR = " ABC ":

This statement... | Is equivalent to...
% &STR = &PARSE( &STR) | % &STR = "ABC"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&RANDOM

Holds a pseudo-random number in the range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&RANDOM

Aliases:

&random     &Random
&rand       &Rand
&RAND

Comment:

To set an initial value for the randomizer, use &SEED.

Examples:

Input:

% &A = &RANDOM

Output:

% &A = 16838
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&SEED


&SEED

Provides an initial value for the &RANDOM function. This function provides statistical control (reproducibility) over programs using &RANDOM.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&SEED (initialvalue)

Aliases:

&seed (initialvalue)
&Seed (initialvalue)

Comment:

Character strings are acceptable for initialvalue, if they can be converted to numeric types.

Example:

&SEED (1234)
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&RANDOM


&STRING

Concatenates text strings, variable values, or expressions, and returns the result. Use &STRING instead of evaluation brackets to increase the level of semantic expression in the program, in the sense of indicating a string is being constructed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&STRING (expression, expression, ...)

Aliases:

&string (expression, expression, ...)
&String (expression, expression, ...)&CONCAT (expression, expression, ...)
&concat (expression, expression, ...)
&Concat (expression, expression, ...)&CAT (expression, expression, ...)
&cat (expression, expression, ...)
&Cat (expression, expression, ...)

Comments:

If any of the arguments are stored as a numeric type, MFG converts those arguments to a temporary text form before performing the matching process.

Examples:

Use &STRING instead of evaluation expressions to form concatenations.

  • Instead of <%&SQ&VAR1&VAR2&SQ>, where &SQ is a quote, code &STRING (&VAR1, &VAR2).
  • Instead of <%&CQ&VAR1+TEXT&VAR2&CQ>, where &CQ is an apostrophe, code &STRING (&VAR1, "TEXT", &VAR2).

Sample generated values.

&CONCAT ("ABC")  = "ABC"
&CONCAT ("")  = ""
&CONCAT ("ABC", "DEF")  = "ABCDEF"
&CONCAT ("ABC", 123)  = "ABC123"
&CAT ("ABC", "DEF")  = "ABCDEF"
&CAT ("ABC", "DEF", &I)  = "ABCDEFHIJ"  (where &I = "HIJ")
&STRING ("ABC")  = "ABC"
&STRING ("ABC", "DEF")  = ABCDEF
&STRING ("ABC", 123)  = ABC123
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&STRLWR

Equivalent to &LOWER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&LOWER


&STRUPR

Equivalent to &UPPER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&UPPER


&SUBST

Holds the original string with only the first occurrence of the match string replaced by the substitute string. If the match string does not occur in the original string, &SUBST returns a copy of the original string. The original arguments remain unchanged.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&SUBST ('originalstring', 'matchstring', 'substitutestring')

Aliases:

&subst ('originalstring', 'matchstring', 'substitutestring')
&Subst ('originalstring', 'matchstring', 'substitutestring')
&SUBSTITUTE ('originalstring', 'matchstring', 'substitutestring')
&substitute ('originalstring', 'matchstring', 'substitutestring')
&Substitute ('originalstring', 'matchstring', 'substitutestring')

Comments:

If any of the arguments are stored as a numeric type, MFG converts them to a temporary text form before performing the matching process.

Examples:

&SUBST ("ABCDEFABCDEF", "ABC", "xyz") = "xyzDEFABCDEF"
&SUBST ("ABCDEFABC", "ABC", "uvwxyz") = "uvwxyzDEFABCDEF"
&SUBST ("ABCDEFABCDEF", "ABC", "xyz") = "xyzDEFABC"
&SUBST ("ABCDEFABCDEF", "ABC", "")    = "DEFABCDEF"
&SUBST ("ABCDEFABCDEF", "", "xyz")    = "ABCDEFABCDEF"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&SUBST-ALL

Holds the original string along with all occurrences of the match string replaced by the substitute string. If the match string does not occur in the original string, &SUBST returns a copy of the original string. The original arguments remain unchanged.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&SUBST-ALL ('originalstring', 'matchstring', 'substitutestring')

Aliases:

&subst-all ('originalstring', 'matchstring', 'substitutestring')
&Subst-All ('originalstring', 'matchstring', 'substitutestring')
&SUBSTALL ('originalstring', 'matchstring', 'substitutestring')
&substall ('originalstring', 'matchstring', 'substitutestring')
&SubstAll ('originalstring', 'matchstring', 'substitutestring')
&SUBSTITUTE-ALL ('origstring', 'matchstring', 'substitutestring')
&substitute-all ('origstring', 'matchstring', 'substitutestring')
&Substitute-All ('origstring', 'matchstring', 'substitutestring')
&SUBSTITUTEALL ('origstring', 'matchstring', 'substitutestring')
&substituteall ('origstring', 'matchstring', 'substitutestring')
&SubstituteAll ('origstring', 'matchstring', 'substitutestring')

Comments:

If any of the arguments are stored as a numeric type, MFG converts them to a temporary text form before performing the matching process.

Examples:

&SUBST-ALL ("ABCDEFABCDEF", "ABC", "xyz") = "xyzDEFxyzDEF"
&SUBST-ALL ("ABCDEFABC", "ABC", "uvwxyz") =
% ... "uvwxyzDEFuvwxyzDEF"
&SUBST-ALL ("ABCDEFABCDEF", "ABC", "xyz") = "xyzDEFxyz"
&SUBST-ALL ("ABCDEFABCDEF", "ABC", "")    = "DEFDEF"
&SUBST-ALL ("ABCDEFABCDEF", "", "XYZ")    = "ABCDEFABCDEF"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&SUBSTR

Extract a substring from a string, starting with startcolumn and continuing for length .
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&SUBSTR( string, startcolumn[, length])

Aliases:

&substr( string, startcolumn[, length])
&Substr( string, startcolumn[, length])

Parameters:

String | Can be an alphanumeric literal string delimited with quotation marks, a number, or a variable with a string value.
Startcolumn and length | Can be a number or variable; if length is omitted, the substring includes all characters from startcolumn onward.

Comments:

  • If startcolumn is greater than length, or if length is 0, the result is an empty string.
  • If startcolumn plus length is greater than length, the result begins with string start character and ends with its last character; the substring is not padded with blanks.

Examples:

Extract a substring from the string value of &PREFIX, starting with column 1 and continuing for 23 characters.

% &PREFIX = &SUBSTR( &PREFIX, 1, 23)

Extract substring values from the values of &RANDOM and &STUFF, and assign the result to MY-LANGUAGE. Note that &QT defines the delimiter character as the apostrophe; the quotation marks delimiting the string values are not considered part of the string and are stripped from the output.

Input:

% &QT = "'"
% &RANDOM = &SUBSTR( "MEANINGLESS", 1, 4)
% &STUFF = &SUBSTR( "EXAMPLE", 3, 5)
MY-LANGUAGE = &QT&RANDOM&STUFF&QT

Output:

MY-LANGUAGE = 'MEANAMPLE'

When the string argument is a number, AMB converts the number to a string and strips leading zeros as follows.

Coding | Yields
&SUBSTR( 012, 1, 2) | 12
&SUBSTR( -12, 1, 2) | -1
&SUBSTR( -012, 1, 2) | -1
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)


&TO-LOWER

Equivalent to &LOWER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&LOWER


&TO-UPPER

Equivalent to &UPPER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&UPPER


&UP-CASE

Equivalent to &UPPER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&UPPER


&UPPER

Return a copy of the original string with all lower case characters in the variable converted to upper case. Other characters remain unchanged. Use &IS-UPPER or &IS-LOWER to test if the string is upper or lower case.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

&UPPER (string)

Aliases:

&upper (string)        &Upper (string)
&TO-UPPER (string)     &to-upper (string)
&To-Upper (string)     &ToUpper (string)
&TOUPPER (string)      &toupper (string)&strupr (string) &Strupr (string)
&STRUPR (string)&UP-CASE (string) &up-case (string)
&Up-Case (string)     &UPCASE (string)
&upcase (string)      &UpCase (string)

Comments:

If the argument is stored as a numeric type, &UPPER returns a text string form of the number.

Examples:

&UPPER ("ABC")  = "ABC"
&UPPER ("Ab1%") = "AB1%"
&UPPER ("abc")  = "ABC"
Parent topic: MFG Structures
Related reference
Customizer/Micro Focus Generator (MFG)
&IS-LOWER
&IS-UPPER


Data Communication Calls

AMB Data Communication calls are predefined, easy-to-use statements that let you focus on what needs to be accomplished, rather than the mechanics of the target environment. To address environment-specific requirements, you can extend these calls with arguments; no native coding is required. These calls facilitate both generic processing and specialized requests.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG (Dialog)
  • IMS DC
  • DLG Compatibility with IMS DC, CICS
    The following calls improve communication between DLG and other DC targets.
  • Program Control Blocks, IO
    AMB generates an IO PCB to define a program control block.
  • Program Specification Blocks (PSBs)
    When you assign a PSB to a program by naming the PSB in the Project Explorer, CICS schedules only one PSB at a time. NTRY schedules the PSB. This PSB is active until the program:
  • ATTR
    Modify the screen I/O field attributes at run time.
  • CIC-ADDRESS
    Use with the TP-LINKAGE call to access CICS storage areas.
  • CIC-ASSIGN
    Obtain values outside the program and assign them to a Working-Storage data area in the current program.
  • CIC-CANCEL
    Cancel a previously issued CIC-DELAY or CIC-START.
  • CIC-DELAY
    Suspend task processing for a prescribed time interval.
  • CIC-DELETEQ-TD
    Delete all transient data associated with a predefined transient data queue.
  • CIC-FREEMAIN
    Release storage previously acquired by a CIC-GETMAIN.
  • CIC-GETMAIN
    Obtain and initialize main storage.
  • CIC-LOAD
    Load specified programs, tables, or maps from a library to main storage.
  • CIC-READQ-TD
    Read transient data from a predefined data queue.
  • CIC-READQ-TS
    Retrieve data from a temporary storage queue in main or auxiliary storage.
  • CIC-RELEASE
    Delete program, table, or map, previously loaded with a CIC-LOAD call, from main storage.
  • CIC-SCHEDULE-PSB
    Schedule the PSB in the program, if not currently scheduled. AMB automatically generates this call when you specify a PSB in the Project Explorer.
  • CIC-SEND-TEXT
    Format output data without mapping and transmit to a terminal or line printer.
  • CIC-SERVICE-RELOAD
    Establish addressability to a data area in the Linkage Section following an address change in the BLL cell.
  • CIC-START
    Start a task on a local or remote system at a specified time.
  • CIC-TERM-PSB
    Terminate the currently scheduled PSB. You normally use this call before transferring to another program.
  • CIC-WRITEQ-TD
    Write transient data to a predefined data queue.
  • CIC-WRITEQ-TS
    Write or rewrite temporary data records to a temporary storage queue.
  • CLEAR
    Move spaces to all fields in a specified screen.
  • CLEAR-ATTRS
    Reset all screen field attributes to their original painted values.
  • DLG-ISPEXEC
    Invoke ISPF services that use CALL ISPEXEC format.
  • DLG-ISREDIT
    Invoke ISREDIT services.
  • DLG-SETMSG
    Display a message on the next panel; define message text and attributes.
  • DLG-VCOPY
    Copy data from a Dialog variable to a COBOL program variable and generate the Working-Storage entry for the COBOL variable, if the COBOL level is specified.
  • DLG-VDEFINE
    Establish a link between a Dialog function pool variable and a COBOL program variable.
  • DLG-VDELETE
    Remove the Dialog variables, previously defined by VDEFINE, from the function pool.
  • DLG-VREPLACE
    Move data from a COBOL program variable to an ISPF function pool variable.
  • DLG-VRESET
    Reset all program function pool variables and delete the links between COBOL variables and Dialog variables within the function pool.
  • LINK
    Transfer control and optionally send Commarea data from a CICS program at one logical level to a CICS AMB or non-AMB application subprogram; or, transfer control to an IMS or DLG subprogram.
  • MSG-SW
    Send data or a message to the specified program trancode or subprogram.
  • RESET-PFKEY
    Simulate screen invocation.
  • SCRNLIST
    Enable your program to use multiple screens and generate
  • SEND
    Display screen data for end user response.
  • TERM
    Terminate programs and transaction operations. Under DLG, performs internal program cleanup, terminate the program via GOBACK statement, and return control to the calling program.
  • TP-BACKOUT
    ABEND the program. In IMS programs, this call invokes the IMS dynamic backout feature, canceling all database updates and messages sent since running the program or since receipt of the most recent input message.
  • TP-COMMAREA
    TP-COMMAREA generates a Working-Storage record for passing data between programs or coordinates the placement of the AMB-generated Commarea structure with a user-provided redefinition of that structure.
  • TP-LINKAGE
    Handle addressability of Linkage Section data records in a called program.
  • TP-NULL
    Move LOW-VALUES to all fields in a specified screen record. This call does not alter the field attributes.
  • TP-PERFORM
    Perform a paragraph, with or without passing arguments.
  • XCTL
    XCTL either transfers control from a program at one logical level to a AMB or non-AMB application program at the same level, and passes the Commarea, or it operates identically to LINK.
Parent topic: Reference


DLG Compatibility with IMS DC, CICS

The following calls improve communication between DLG and other DC targets.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
NTRY | You can list explicit data areas; this allows flexibility in passing data areas between programs.
TP-COMMAREA | Not required to pass data areas between programs, but is supported for upward compatibility.
SEND | Provided for upward compatibility; does not invoke a program. Use LINK to invoke a program that displays a screen.
TP-LINKAGE | Provided for upward compatibility. This call is necessary for CICS to order the LINKAGE section properly, but DLG lets you locate user records in LINKAGE without coding TP-LINKAGE.

The PFKEY option allows PF key processing similar to AMB CICS and IMS with the Program-Controlled option when converting a AMB CICS or IMS application to DLG.

Parent topic: Data Communication Calls
Related reference
NTRY
TP-COMMAREA
TP-LINKAGE
SEND


Program Control Blocks, IO

AMB generates an IO PCB to define a program control block.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

  • IMS
  • IMS/SQL mixed target

Linkage Section:

The IO PCB AMB generates has the following format in the Linkage Section:

LINKAGE SECTION.
01  IO-PCB.
    05  IO-PCB-LTERM        PIC X(8).
    05  FILLER              PIC X(2).
    05  IO-PCB-STATUS       PIC X(2).
    05  IO-PCB-INPUT-PREF.
        10  IO-PCB-DATE     PIC S9(7) COMP-3.
        10  IO-PCB-TIME     PIC S9(7) COMP-3.
        10  IO-PCB-MSG-SEQ  PIC S9(7) COMP.
    05  IO-PCB-MOD-NAME     PIC X(8).
    05  IO-PCB-USER-ID      PIC X(8).

Comments:

  • In a AMB IMS/SQL program, code a PSB with the same name as your DB2 subschema. The PSB must specify an IO PCB (by setting CMPAT=YES in the PSBGEN). If your program uses MSG-SW, the PSB must also specify an alternate IO PCB.
  • A program requires IO PCBs to obtain an input message and return a reply to the originating terminal.
  • To send a message to a logical terminal instead of to the originating terminal, code the MSG-SW call and specify an alternate IO PCB that you define with MODIFY=YES in the program specification block (PSB). MSG-SW cannot include the EXPRESS keyword when it references this alternate IO PCB.
Parent topic: Data Communication Calls


Program Specification Blocks (PSBs)

When you assign a PSB to a program by naming the PSB in the Project Explorer, CICS schedules only one PSB at a time. NTRY schedules the PSB. This PSB is active until the program:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Encounters a SEND or TERM
  • Initiates a CIC-TERM-PSB and continues processing

Targets:

  • CICS
  • IMS DB

General Rules:

  1. To ensure that your PSB remains active when you link or transfer to another program, pass the associated PCBs in the LINK or XCTL call, as shown below:
    LINK programname [errorpara]
... [DLIUIB pcbname [pcbname ...]]
... [userparm [userparm]...]
XCTL programname [errorpara]
... [DLIUIB pcbname [pcbname ...]]
  2. The invoking program must pass the PCBs in the order that they are coded in the Linkage Section of the invoked program.
  3. When a program invokes a LINK to a subprogram, and passes a scheduled PSB, it expects the PSB to remain scheduled when control returns from the subprogram. To return without terminating the PSB, use TERM because it does not terminate a PSB passed from a higher-level program. To terminate a PSB, use the CIC-TERM-PSB call.

Example:

Pass part of a scheduled PSB and two Linkage Section data areas:

LINK PROGRMB * DLIUIB
... ORDERDB-PCB
... ITEMDB-PCB
... USER-LINK-1
... USER-LINK-2

The PSB remains scheduled at the start of the next program.

Parent topic: Data Communication Calls
Related reference
CIC-TERM-PSB
SEND
TERM


ATTR

Modify the screen I/O field attributes at run time.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax:

[TP-]ATTR screenname

... attribute1[+attribute2...]
... fieldname[(subscript)][+fieldname[(subscript)]
...]

General Rules:

  1. When redefining a screen, use the original name.
  2. Code only as many fieldnames as can fit on a single line. To code more field names, code another ATTR.
  3. For character-based applications, to modify color or highlighting, turn on the Extattr Modifiable parameter in the Screen Painter.
  4. You can code attributes that are not supported, such as when prototyping, without causing an error. They are ignored at generation/execution time.
  5. If fieldname is part of a repeated block, it must be subscripted and the subscript included with the field name as passed to ATTR.

Parameters:

attribute | Specify one or more attributes.
 | BRT | Bright character images
 | NORM | Normal character images
 | DARK | Suppress character display
 | MDTON | Enable modified data tags (CICS only)
 | MDTOFF | Disable modified data tags (CICS only)
 | NUM[LOCK] | Enable numeric locking
 | NOLOCK| NUMOFF | Disable numeric locking
 | POS[ITION] | Position the cursor at the first field in the string
 | PROT | Specify write-protection
 | ASKIP | Specify write-protection
 | UNPROT| NOPROT | Cancel write-protection
 | DET | Enable light pen detection
 | Specify one of the following colors:
 | DEFCOL | Default color
 | BLUE|BL |
 | NEUTRAL|NU |
 | PINK|PK |
 | GREEN|GN |
 | RED|RD |
 | TURQ|TQ | Turquoise
 | YELLOW|YL |
 | Specify one of the following character highlights:
 | BLINK | Blinking cursor
 | NOBLINK | Nonblinking cursor
 | RVID | Reverse video
 | NORVID | Normal video
 | UNDER | Underlining
 | NOUNDER | No underlining
 | NODET|DETOFF | Disable light pen detection
fieldname [(subscript)] | Screen field name(s). Code only the field name, not its screen name prefix; code the field subscript if applicable.
screenname | Screen name; value must be literal (maximum 8 characters).

Examples:

Position the cursor to the SS-NUM field.
ATTR SCRA POS SS-NUM
Change the intensity of the EMPL-NAME field.
ATTR SCRA BRT EMPL-NAME
Apply multiple attributes to multiple fields.
ATTR SCRA PROT+BRT SS-NUM+EMPL-NAME
Specify the field SOC-SEC-NUM as part of a repeated block.
ATTR SCRA BRT+POS SOC-SEC-NUM(LINE-CTR)
Parent topic: Data Communication Calls


CIC-ADDRESS

Use with the TP-LINKAGE call to access CICS storage areas.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-ADDRESS option(linkdataname)
[option(linkdataname) ...]

Parameters:

option | CWA | Common Work Area
 | TCTUA | Terminal Control Table User Area
 | TWA | Transaction Work Area
 | CSA | Common Storage Area
 | EIB | Execute Interface Block
linkdataname | 01-level Linkage Section data area identical to the linkdataname in the associated TP-LINKAGE call.

Example:

Pass information to the application program. The current program Linkage Section data area (LK-CWA) is set to the CWA address for access.
 SYLK   TP-LINKAGE LK-CWA
 LK01   LK-CWA              PIC X(200).
 NTRY   CIC-ADDRESS CWA(LK-CWA)
Parent topic: Data Communication Calls
Related reference
TP-LINKAGE


CIC-ASSIGN

Obtain values outside the program and assign them to a Working-Storage data area in the current program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-ASSIGN CICSoption(dataarea)
[CICSoption(dataarea)....]

... [ERROR(errorpara)]

Parameters:

CICSoption | Valid CICS option. See your CICS reference manual for more information.
(dataarea) | COBOL data name containing the result of the call.
(errorpara) | User-defined error routine to perform when an abnormal condition occurs.

Example:

Obtain a value outside the application program and assign it to a user-defined area.
CIC-ASSIGN APPLID(WS-APPLID)
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-CANCEL

Cancel a previously issued CIC-DELAY or CIC-START.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-CANCEL [REQID(name)]
... [TRANSID(name)]
... [SYSID(name)]
... [ERROR(errorpara)]

Parameters:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
REQIDname) | Unique call name; can be a literal or COBOL data name (maximum 8 characters).
SYSIDname) | Remote system name; can be a literal or a COBOL data name (maximum 4 characters).
TRANSID (name) | Transaction code identifying the program where control returns; can be a literal (maximum 4 characters) or COBOL data name (minimum 5 characters).

Example:

Cancel an activity invoked by a CIC-START.
CIC-CANCEL TRANSID('TRAN') ERROR(ERROR-PARA)
Parent topic: Data Communication Calls
Related reference
CIC-DELAY
CIC-START


CIC-DELAY

Suspend task processing for a prescribed time interval.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-DELAY [REQID(name)]
... [INTERVAL(hhmmss)|TIME(hhmmss)]
... [ERROR(errorpara)]

Parameters:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
INTERVAL (hhmmss) | Time interval between issuing and executing a call. Hhmmss can be replaced by zero, a decimal constant, or a COBOL data name defined as PIC S9(07) COMP-3.
REQID(name) | Unique call name; can be a literal or COBOL data name (maximum 8 characters).
TIME(hhmmss) | Expiration time for the DELAY function. Hhmmss can be replaced by a decimal constant or a COBOL data name defined as PIC S9(07) COMP-3.

Examples:

Suspend task processing for a 5-minute interval; let another task cancel this activity (UNIQCOM command).
CIC-DELAY INTERVAL(500) ERROR(ERROR-PARA)
REQID('UNIQCOM')
Suspend task processing until 1:30 a.m.
CIC-DELAY TIME(013000) ERROR(ERROR-PARA)
REQID('UNIQCOM')
Parent topic: Data Communication Calls


CIC-DELETEQ-TD

Delete all transient data associated with a predefined transient data queue.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-DELETEQ-TD QUEUE(name)
... [SYSID(name)]
... [ERROR(errorpara)]

Parameters:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
QUEUE(name) | Queue name; can be a literal (maximum 8 characters), or COBOL data name (maximum 30 characters) defined as X(4).
SYSID(name) | Remote system name; can be a literal or a COBOL data name (maximum 4 characters).

Examples:

Delete all the intrapartition transient data stored in storage queue `TDAQ'.
CIC-DELETEQ-TD QUEUE('TDAQ') ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-FREEMAIN

Release storage previously acquired by a CIC-GETMAIN.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-FREEMAIN DATA(linkdataname)

Parameter:

linkdataname

01-level Linkage Section data area identical to the linkdataname in the associated TP-LINKAGE call.

Example:

Release the main storage of LK-STORAGE-AREA.
CIC-FREEMAIN DATA(LK-STORAGE-AREA)
Parent topic: Data Communication Calls
Related reference
TP-LINKAGE
CIC-GETMAIN


CIC-GETMAIN

Obtain and initialize main storage.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-GETMAIN SET(linkdataname)
... LENGTH(value)|FLENGTH(value)
... [INITIMG(value)]
... [ERROR(errorpara)]

Parameter:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
INITIMG (value) | Initialize storage area. Value is 1 byte; can be a literal or COBOL data name.
FLENGTH (value) | Specify length as a full word value.
LENGTH (value) | Maximum length of data; can be a literal (LINK or XCTL only) or COBOL data name defined as S9(04)COMP. Can also be a partial length (XCTL only).
SET(link-dataname) | 01-level Linkage Section data area identical to the linkdataname in the associated TP-LINKAGE call.

Example:

Obtain an area of main storage of the length specified in the Working-Storage data area (WS-LENGTH). Specify initialization value (WS-BLANK) for the acquired main storage.
CIC-GETMAIN SET(STORAGE-AREA)
... LENGTH(WS-LENGTH)
... INITIMG(WS-BLANK)
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-LOAD

Load specified programs, tables, or maps from a library to main storage.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-LOAD PROGRAM(name) [SET(linkdataname)]
... [LENGTH(dataarea)]|[FLENGTH(dataarea)]
... [ENTRY(pointref)]
... [HOLD] [ERROR(errorpara)]

Parameter:

ENTRY (pointref) | BLL cell containing program address after the LOAD operation.
ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
FLENGTH (value) | Specify length as a full word value.
HOLD | Hold loaded module in main storage until a CIC-RELEASE call executes.
LENGTH (value) | Maximum length of data; can be a literal (LINK or XCTL only) or COBOL data name defined as S9(04)COMP. Can also be a partial length (XCTL only).
PROGRAM (name) | Name of module to load into main storage; can be a literal or COBOL data name (maximum 8 characters).
SET(link dataname) | 01-level Linkage Section data area identical to the linkdataname in the associated TP-LINKAGE call.

Example:

Load table TAXTAB into main storage; perform user-defined error routine ERROR-PARA when an error occurs; store the address at which the module was loaded in Linkage Section data area TAX-TABLE-AREA; and store the length of the loaded module in Working-Storage data area TAX-LEN.
CIC-LOAD PROGRAM('TAXTAB')
... SET(TAX-TABLE-AREA) LENGTH(TAX-LEN)
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-READQ-TD

Read transient data from a predefined data queue.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-READQ-TD QUEUE(name)
... INTO(dataarea)|SET(linkdataname)
... [LENGTH(dataarea)] [SYSID(name)]
... [ERROR(errorpara)]

Parameter:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
INTO (dataarea) | Name of data area where AMB places transient or temporary data.
LENGTH (value) | Maximum length of data; can be a literal (LINK or XCTL only) or COBOL data name defined as S9(04)COMP. Can also be a partial length (XCTL only).
QUEUE(name) | Queue name; can be a literal (maximum 8 characters), or COBOL data name (maximum 30 characters) defined as X(4).
SET(link-dataname) | 01-level Linkage Section data area identical to the linkdataname in the associated TP-LINKAGE call.
SYSID(name) | Remote system name; can be a literal or a COBOL data name (maximum 4 characters).

Example:

Read a record from a transient data queue `TDAQ' into data area WS-TD-REC.
CIC-READQ-TD QUEUE('TDAQ') INTO(WS-TD-REC)
... LENGTH(WS-TD-LEN)
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-READQ-TS

Retrieve data from a temporary storage queue in main or auxiliary storage.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-READQ-TS QUEUE(name)
... INTO(dataarea)|SET(linkdataname)
... LENGTH(dataarea) NUMITEMS(dataarea)
... [ITEM(value)|NEXT]
... [SYSID(name)]
... [ERROR(errorpara)]

Parameter:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
INTO (dataarea) | Name of data area where AMB places transient or temporary data.
ITEM (value) | Relative record number in the queue; can be a literal or COBOL data name defined as S9(04)COMP. Required with REWRITE.
LENGTH (value) | Maximum length of data; can be a literal (LINK or XCTL only) or COBOL data name defined as S9(04)COMP. Can also be a partial length (XCTL only).
NEXT | Read next sequential logical record.
NUMITEMS (dataarea) | Number of items in the queue.
QUEUE(name) | Queue name; can be a literal (maximum 8 characters), or COBOL data name (maximum 30 characters) defined as X(4).
SET(linkdataname) | 01-level Linkage Section data area identical to the linkdataname in the associated TP-LINKAGE call.
SYSID(name) | Remote system name; can be a literal or a COBOL data name (maximum 4 characters).

Example:

Read the next (or only) record from temporary storage queue `TSAQ' into data area WS-TD-RECORD.
CIC-READQ-TS QUEUE('TSAQ')
... INTO(WS-TD-RECORD) LENGTH(WS-TD-RECLEN)
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-RELEASE

Delete program, table, or map, previously loaded with a CIC-LOAD call, from main storage.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-RELEASE PROGRAM(name)
... [ERROR(errorpara)]

Parameter:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs
PROGRAM (name) | Main storage module to be deleted; can be a literal or COBOL data name (maximum 8 characters)

Example:

Delete program PROG5.
CIC-RELEASE PROGRAM('PROG5')
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-SCHEDULE-PSB

Schedule the PSB in the program, if not currently scheduled. AMB automatically generates this call when you specify a PSB in the Project Explorer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICSand IMS DB

Syntax:

CIC-SCHEDULE-PSB
Parent topic: Data Communication Calls


CIC-SEND-TEXT

Format output data without mapping and transmit to a terminal or line printer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-SEND-TEXT FROM(dataarea)
... LENGTH(value) [CICSoptions]
... [ERROR(errorpara)]

General Rule:

  1. Use CIC-SEND-TEXT prior to a TERM from a main program in order to clear the screen and unlock the keyboard.

Parameters:

CICSoptions | Valid CICS, see your CICS reference manual for more information.
ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
FROM (dataarea) | Data area to be acted on.
LENGTH (value) | Maximum length of data; can be a literal (LINK or XCTL only) or COBOL data name defined as S9(04)COMP; can also be a partial length (XCTL only).

Example:

CIC-SEND-TEXT outputs data block TEXT-STRING, to be formatted without being mapped.
CIC-SEND-TEXT FROM(TEXT-STRING)
... LENGTH(100) ERASE FREEKB
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls
Related reference
TERM


CIC-SERVICE-RELOAD

Establish addressability to a data area in the Linkage Section following an address change in the BLL cell.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-SERVICE-RELOAD linkdataname

General Rule:

  1. SERVICE-RELOAD is an OS/VS COBOL statement; do not use with COBOL II, because the compiler treats this call as a CONTINUE statement.

Parameter:

linkdata-name

01-level Linkage Section data area identical to the linkdataname in the associated TP-LINKAGE call.

Example:

Establish addressability to Linkage area LINK-AREA-1 after an address change.
MOVE PASSED-ADDRESS TO LINK-AREA-1-PNTR
CIC-SERVICE-RELOAD LINK-AREA-1
Parent topic: Data Communication Calls
Related reference
TP-LINKAGE


CIC-START

Start a task on a local or remote system at a specified time.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-START TRANSID(name)
... [INTERVAL(hhmmss)|TIME(hhmmss)] [CICSoptions]
... [ERROR(errorpara)]

General Rule:

  1. SERVICE-RELOAD is an OS/VS COBOL statement; do not use with COBOL II, because the compiler treats this call as a CONTINUE statement.

Parameters:

CICSoptions | Valid CICS option. See your CICS reference manual for more information.
ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
INTERVAL (hhmmss) | Time interval between issuing and executing the call. Hhmmss can be replaced by zero, a decimal constant, or a COBOL data name defined as PIC S9(07) COMP-3.
TIME (hhmmss) | Expiration time for the START function. Hhmmss can be replaced by a decimal constant or a COBOL data name defined as PIC S9(07) COMP-3.
TRANSID (name) | Transaction code identifying the program where control returns; can be a literal (maximum 4 characters) or COBOL data name (minimum 5 characters).

Example:

Start a specific task (not associated with a terminal) in one hour.
CIC-START TRANSID('TRNL') INTERVAL(10000)
... ERROR(ERROR-PARA)
Initiate task TRN2 associated with terminal STA3; begin the task at 5:30 P.M.
CIC-START TRANSID('TRN2') TIME(173000)
... TERMID('STA3') ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-TERM-PSB

Terminate the currently scheduled PSB. You normally use this call before transferring to another program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-TERM-PSB
Parent topic: Data Communication Calls


CIC-WRITEQ-TD

Write transient data to a predefined data queue.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-WRITEQ-TD QUEUE(name) FROM(dataarea)
... [LENGTH(value)] [SYSID(name)]
... [ERROR(errorpara)]

Parameters:

ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
FROM (dataarea) | Data area to be acted on.
LENGTH (value) | Maximum length of data; can be a literal (LINK or XCTL only) or COBOL data name defined as S9(04)COMP. Can also be a partial length (XCTL only). Required with SYSID.
QUEUE(name) | Queue name; can be a literal (maximum 8 characters), or COBOL data name (maximum 30 characters) defined as X(4).
SYSID(name) | Remote system name; can be a literal or a COBOL data name (maximum 4 characters).

Example:

Write data to predefined transient data queue 'TRDQ'.
CIC-WRITEQ-TD QUEUE('TRDQ') FROM(WS-MESSAGE)
... LENGTH(WS-TD-LEN)
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CIC-WRITEQ-TS

Write or rewrite temporary data records to a temporary storage queue.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

CICS

Syntax:

CIC-WRITEQ-TS QUEUE(name) FROM(dataarea)
... LENGTH(value) [SYSID(name)]
... [ITEM(dataarea) [REWRITE] [CICSoptions]
... [NOSUSPEND]
... [ERROR(errorpara)]

Parameters:

CICSoptions | Valid CICS option. See your CICS reference manual for more information.
ERROR (errorpara) | User-defined error routine to perform when an abnormal condition occurs.
FROM (dataarea) | Data area to be acted on.
ITEM(value) | Relative record number in the queue; can be a literal or COBOL data name defined as S9(04)COMP. Required with REWRITE.
LENGTH (value) | Maximum length of data; can be a literal (LINK or XCTL only) or COBOL data name defined as S9(04)COMP. Can also be a partial length (XCTL only).
NOSUSPEND | Return to the program without waiting for resources to become available.
QUEUE(name) | Queue name; can be a literal (maximum 8 characters), or COBOL data name (maximum 30 characters) defined as X(4).
REWRITE | Overwrite existing record in queue with data contained in data area.
SYSID(name) | Remote system name; can be a literal or a COBOL data name (maximum 4 characters).

Example:

Write a record to a temporary storage queue in auxiliary storage, where the queue name is in QUEUE-NAME.
CIC-WRITE-TS QUEUE(QUEUE-NAME)
... FROM(WS-TS-RECORD)
... LENGTH(WS-TS-LENGTH)
... ITEM(WS-TS-ITEM-NO)
... ERROR(ERROR-PARA)
Parent topic: Data Communication Calls


CLEAR

Move spaces to all fields in a specified screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax:

[TP-|SC-]CLEAR screenname

General Rule:

  1. This call does not alter the field attributes.

Example:

Move spaces to all fields on screen SCRA.
CLEAR SCRA
Parent topic: Data Communication Calls


CLEAR-ATTRS

Reset all screen field attributes to their original painted values.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax:

[TP-]CLEAR-ATTRS screenname

General Rule:

  1. The screen field contents do not change.

Example:

Reset all field attributes to their original values for screen SCRA.
CLEAR-ATTRS SCRA
Parent topic: Data Communication Calls


DLG-ISPEXEC

Invoke ISPF services that use CALL ISPEXEC format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

DLG

Syntax:

DLG-ISPEXEC commandproceduresyntax

General Rule:

  1. Data field DLG-ISPEXEC-RC contains the return code after the call execution.

Parameter:

commandproceduresyntax

Syntax for call executed in Command Procedure (CLIST) format.

Example:

Use the CONTROL service to disable the user's split screen capability.
DLG-ISPEXEC CONTROL SPLIT DISABLE
IF  DLG-ISPEXEC-RC = 8
    /* SPLIT SCREEN ALREADY DISABLED
    TRUE  SPLIT-SCREEN-DISABLED
ELSE-IF DLG-ISPEXEC-RC = 0
    /* SPLIT SCREEN DISABLED
    TRUE  SPLIT-SCREEN-DISABLED
Define an application message library to search before the default message library.
DLG-ISPEXEC LIBDEF ISPMLIB DATASET
ID('ABC.DEF.ISPMLIB')
IF  DLG-ISPEXEC-RC = 0
    /* OK
ELSE
    DISPLAY '??? LIBDEF ISPMLIB ERROR, RC = ' DLG-
ISPEXEC-RC
Invoke a command procedure to allocate application files.
DLG-ISPEXEC SELECT CMD(%ALOCFILE ALLOC)
IF  DLG-ISPEXEC-RC = 0
    /* OK
ELSE
    DISPLAY '??? ALOCFILE ERROR, RC = ' DLG-
ISPEXEC-RC
Parent topic: Data Communication Calls


DLG-ISREDIT

Invoke ISREDIT services.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

DLG

Syntax:

DLG-ISREDIT commandproceduresyntax

General Rule:

  1. Data field DLG-ISREDIT-RC contains the return code after call execution.

Parameter:

commandproceduresyntax

Syntax for call executed in Command Procedure (CLIST) format

Example:

Determine if the member is new or existing. DLG-VDEFINE links ISPF variable &LASTLINE to COBOL variable LASTLINE.
DLG-VDEFINE LASTLINE &APS-FULL
DLG-ISREDIT (LASTLINE) = LINENUM .ZLAST
IF  LASTLINE = 0
    /* NEW MEMBER
    TRUE  NEW-MEMBER
Parent topic: Data Communication Calls


DLG-SETMSG

Display a message on the next panel; define message text and attributes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

DLG

Syntax: for Format 1

SETMSG definition

DLG-SETMSG
... [SHORT 'shortmessagetext']
... [LONG 'longmessagetext']
... [ALARM 'YES'|'NO'] [HELP 'helppanelname']

Syntax: for Format 2

SETMSG definition for execution by Format 3

DLG-SETMSG erroridentifier

... [SHORT 'shortmessagetext']
... [LONG 'longmessagetext']
... [ALARM 'YES'|'NO']
... [HELP 'helppanelname']

Syntax: for Format 3

SETMSG execution

DLG-SETMSG [erroridentifier|messageID]

General Rules:

  1. If you use Format 2, include at least one of the parameters.
  2. Data field DLG-SETMSG-RC checks the return code after call execution.

Parameters:

ALARM | Sound alarm when screen displays.
error-identifier | Unique name referencing predefined message text and attributes.
HELP 'help panelname' | Help panel that displays via PF1.
messageID | ISPF MSGID for SETMSG service.
LONG 'long messagetext' | Display text in long message field when the end user presses PF1 for the first time. Messagetext must fit on the same line as LONG.
SHORT 'short messagetext' | Display text in short message field. Messages longer than 24 characters can cause truncation errors. Messagetext must fit on the same line as SHORT.

Example:

Define a message for an invalid option condition. INVALID-OPT (error identifier) identifies the message information to display when DLG-SETMSG is invoked in the execution format.
DLG-SETMSG INVALID-OPT
... SHORT 'INVALID OPTION'
... LONG  'ENTER ONE OF THE LISTED OPTIONS'
... ALARM 'YES'
Then, display the invalid option message.
IF  SCRA-OPTION = 'value'
    /* VALID CONDITION
ELSE
    DLG-SETMSG INVALID-OPT
Parent topic: Data Communication Calls


DLG-VCOPY

Copy data from a Dialog variable to a COBOL program variable and generate the Working-Storage entry for the COBOL variable, if the COBOL level is specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

DLG

Syntax:

DLG-VCOPY [COBOLlevel] COBOLvariable

... [[FROM] dialogvariable]
... [PIC COBOLpicture]|LEN value
... [GENONLY]

Syntax Rules:

  1. Code FROM dialogvariable on the same line as COBOLvariable.
  2. Coding COBOLlevel generates COBOLvariable in Working-Storage; otherwise, define the COBOL variable in Working-Storage.
  3. Data field DLG-VCOPY-RC contains the return code after call execution.

Parameters:

COBOLlevel | COBOLvariable level number.
COBOLvariable | COBOL data name the call processes.
FROM dialog variable | DLG variable where data comes from; default is COBOLvariable, truncated to eight characters.
GENONLY | Define COBOLvariable data item in Working-Storage only.
LEN value | COBOLvariable length; can be numeric integer, COBOL variable, or arithmetic expression.
PIC COBOLpicture | COBOLvariable picture; default is alphanumeric.

Example:

Copy data from a system variable into a screen field. The call does not generate the COBOL variable because the COBOL level number is not coded.
DLG-VCOPY SCRA-ZUSER FROM ZUSER LEN 8
Copy data from a system variable into a Working-Storage variable. Coding the COBOL level number generates the COBOL variable.
DLG-VCOPY 01 WS-LONG-ERROR-MESSAGE PIC X(78) FROM
ZERRLM
Parent topic: Data Communication Calls


DLG-VDEFINE

Establish a link between a Dialog function pool variable and a COBOL program variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

DLG

Syntax:

DLG-VDEFINE [COBOLlevel] COBOLvariable

... [[AS] dialogvariable]
... [PIC COBOLpicture]|LEN value
... [GENONLY]

Syntax Rules:

  1. Code AS dialogvariable on the same line as COBOLvariable.
  2. NTRY automatically links any panel variables to screen field names.
  3. Coding COBOLlevel generates COBOLvariable in Working-Storage; otherwise, define the COBOL variable in Working-Storage.
  4. Data field DLG-VDEFINE-RC checks the return code after call execution.

Parameters:

AS dialog variable | DLG variable where data links from; default is COBOLvariable, truncated to eight characters.
COBOLlevel | COBOLvariable level number.
COBOLvariable | COBOL data name the call processes.
GENONLY | Define the COBOLvariable data item in Working-Storage only.
LEN value | COBOLvariable length; can be numeric integer, COBOL variable, or arithmetic expression.
PIC COBOLpicture | COBOLvariable picture; default is alphanumeric.

Example:

Establish a link between function pool variable COMDATA and COBOL variable WS-COMM-DATA. Coding the COBOL level number generates the COBOL data name.
DLG-VDEFINE 01 WS-COMM-DATA PIC X(150) AS COMDATA
Parent topic: Data Communication Calls


DLG-VDELETE

Remove the Dialog variables, previously defined by VDEFINE, from the function pool.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

DLG

Syntax:

DLG-VDELETE dialogvariable|*

Syntax Rules:

  1. Coding an asterisk deletes the variables according to the value of the control variable &DLG-AUTO-VARIABLE-VDELETE.
  2. Data field DLG-VDELETE-RC contains the return code after call execution.

Parameters:

dialog-variable | Delete a specific DLG variable.
* (asterisk) | Delete all variables.

Example:

Remove the link between function pool variable COMDATA and COBOL variable WS-COMM-DATA.
DLG-VDEFINE 01 WS-COMM-DATA LEN(150)
... AS COMDATA
DLG-VDELETE COMDATA
Parent topic: Data Communication Calls


DLG-VREPLACE

Move data from a COBOL program variable to an ISPF function pool variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

DLG

Syntax:

DLG-VREPLACE [COBOLlevel] COBOLvariable

... [[INTO] dialogvariable]
... [PIC COBOLpicture]|LEN value
... [GENONLY]

Syntax Rules:

  1. Code INTO dialogvariable on the same line as COBOLvariable.
  2. Coding COBOLlevel generates COBOLvariable in Working-Storage; otherwise, define the COBOL variable in Working-Storage.

Parameters:

COBOLlevel | COBOLvariable level number.
COBOL-variable | COBOL data name the call processes.
GENONLY | Define COBOLvariable data item in Working-Storage only.
INTO dialog variable | ISPF function pool variable data replaces; default is COBOLvariable, truncated to eight characters.
LEN value | COBOLvariable length; can be numeric integer, COBOL variable, or arithmetic expression.
PIC COBOLpicture | COBOLvariable picture; default is alphanumeric.

Example:

Move a new value to the function pool variable ZPF01 and invoke ISPF help services with PF01.
DLG-VREPLACE 01 WS-PF01-HELP PIC X(04) VALUE 'HELP'
INTO ZPF01
Parent topic: Data Communication Calls


DLG-VRESET

Reset all program function pool variables and delete the links between COBOL variables and Dialog variables within the function pool.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

DLG

Syntax:

DLG-VRESET

General Rules:

  1. Data field DLG-VRESET-RC contains the return code after call execution.
Parent topic: Data Communication Calls


LINK

Transfer control and optionally send Commarea data from a CICS program at one logical level to a CICS AMB or non-AMB application subprogram; or, transfer control to an IMS or DLG subprogram.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

DLG

CICS

Syntax: for Format 1

Link to a AMB program

[TP-]LINK programname [errorpara]
... [DLIUIB pcbname [pcbname] ...]
... [userparm [userparm]...]
... [COMMAREA(dataarea) LENGTH(value)]|[NOCA]

Syntax: for Format 2

Linking to a non-AMB program

[TP-]LINK programname(NONAPS)[errorpara]
... [COMMAREA(dataarea)
... LENGTH(value)]|[NOCA]

General Rules:

  1. When linking to a AMB program, TP-COMMAREA passes by default. Alternately, you may pass another data area, or pass neither. Ensure that the Commarea in the "linked-to" program is the same length as the TP-COMMAREA or alternate data area you pass.
  2. When linking to a non-AMB program, TP-USERAREA passes by default. Alternately, you pass another data area, or pass neither. Ensure that the Commarea in the non-AMB program is the same length as the TP-USERAREA or alternate data area you pass. (TP-USERAREA gets its value from &TP-USER-LEN.)

    Additionally, code the following before your NTRY statement.

    % &TP-PROGRAM-INVOCATION = "NONAPS"
  3. Coding TERM in the subprogram returns control to the program that issued the link call.

Parameters:

program-name | Program name; can be a literal, variable, or combination, where the literal is moved to the variable (indicated by a slash (/) as the first character) by rule logic.
errorpara | User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
DLIUIB pcbname | DLI User Interface Block and the Program Control Block for the next program.
userparm | Pass linkage data area(s). Code with TP-LINKAGE, which names the 01-level user-defined area in the Linkage Section.
COMMAREA (dataarea) | Pass data area to a program instead of TP-COMMAREA.
LENGTH (value) | Maximum length of data; can be a literal or COBOL data name; define as S9(04)COMP.
(NONAPS) | Program is not a AMB program.
NOCA | Do not pass COMMAREA.

Examples:

Link to PGM001. No PSB is active and no arguments pass.
LINK PGM001
Link to the program stored in WS-PROGNAME. No PSB is active and no arguments pass.
LINK /WS-PROGNAME
Move the value PGM003 to WS-PROGNAME and link to that program.
LINK PGM003/WS-PROGNAME
Link to PGM004; execute an error routine for an abnormal condition. There is no active PSB and no arguments pass.
LINK PGM004 ERROR-PARA
Link to PGM005. Schedule a PSB and use a PCB named ABC-PCB for the linked-to program. Omit the positional parameter errorpara .
LINK PGM005 * DLIUIB ABC-PCB
Link to PGM006 and pass a Linkage data area SCR6-RECORD so that PGM006 can move data directly to screen fields.
LINK PGM006 * SCR6-RECORD
Link to PROG001, a non-AMB program, passing TP-USERAREA only.
LINK PROG001(NONAPS)
Link to PROG002, a non-AMB program, passing the data area WS-COMMAREA.
LINK PROG002(NONAPS) * COMMAREA(WS-COMMAREA)
... LENGTH(100)
Link to PROG003, a non-AMB program, without passing a COMMAREA.
LINK PROG003(NONAPS) * NOCA

IMS DC

Syntax:

[TP-]LINK subprogram

... [errorpara]
... [argument1 ... argument36]

Parameters:

subprogram | AMB-painted subprogram that links the calling program.
errorpara | User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
argument | Pass record area(s), such as a PCB. TP-COMMAREA, TP-USERAREA, or *NOSPA, may be an argument for conversational programs.

Example:

The following examples show the CALL statements generated in the program after linking to subprograms.

Coding. . . Yields. . .
LINK SUBPGM * ARG1 ARG2 ARG3

CALL 'SUBPGM' USING TP-COMMAREA
ARG1 ARG2 ARG3

LINK SUBPGM * *NOSPA ARG1 ARG2
ARG3

CALL 'SUBPGM' USING ARG1 ARG2
ARG3

LINK SUBPGM * ARG1 ARG2
TP-COMMAREA ARG3

CALL 'SUBPGM' USING ARG1 ARG2
TP-COMMAREA ARG3

DLG

Syntax: for Format 1

CALL format

[TP-]LINK programname [errorpara]
... [userparm [userparm]...]
... [COMMAREA]

Syntax: for Format 2

SELECT format

[TP-]LINK programname

... [errorpara]
... [options]

General Rules:

  1. Including a TERM call in the invoked program returns control to the program issuing the LINK.
  2. Code userparms in the same order as those in the LINKAGE SECTION and the NTRY statement in the linked to program.
  3. To receive TP-COMMAREA as a passed data area from a called program, code the following before the NTRY keyword.
            % &DLG-COMMAREA-IN-LINKAGE = 'YES'
  4. LINK generates a COBOL CALL or ISPEXEC SELECT, depending on the PROGRAM CONTROL TRANSFER option.
  5. The &APSPRE..CNTL member APDLGIN assigns the default value for the PROGRAM CONTROL TRANSFER option. The variable &DLG-PROGRAM-TRANSFER-OPTION can have the values CALL (default) or SELECT.
  6. The PROGRAM CONTROL TRANSFER option affects the availability of function pool variables between programs. Using CALL makes the current function variable pool available to the linked-to program; using SELECT does not.
  7. To override the PROGRAM CONTROL TRANSFER option
    • At the installation level, change the value in &APSPRE..CNTL(APDLGIN).
    • At the project group level, code the assignment statement in &DSNPRE..CNTL(APSPROJ).
    • At the application level, code the assignment statement in a &DSNPRE..USERMACS member and include it for all application programs.
    • At the program level, code the assignment statement at the top of the program.
  8. The PROGRAM CONTROL TRANSFER option lets you invoke the LIBDEF service to define application-level libraries via the SELECT value.
  9. The called program must issue a TERM to stop executing, terminate the screen, and return to the calling program.
  10. The program that is called via TP-LINK should not issue a XCTL to another program.

Parameters:

program-name | Program name; can be a literal, variable, or combination, where the literal is moved to the variable (indicated by a slash (/) as the first character) by rule logic.
errorpara | User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
userparm | Pass linkage data area(s). Code with TP-LINKAGE, which names the 01-level user-defined area in the Linkage Section.
COMMAREA | Pass the TP-COMMAREA, if the invoking program is the main program. Pass DLG-LINKAGE-COMMAREA, if the invoking program is a called program, that is, one where &DLG-COMMAREA-IN-LINKAGE = 'YES'.
options | DLG Management services SELECT PGM options.

Examples:

Invoke PGM001 as a new program function. The SELECT service option NEWPOOL creates a new shared variable pool. The SELECT option is in effect.
LINK PGM001 * NEWPOOL
Invoke PGM001 as a new program function. The SELECT service option PARM passes data to PGM001 via LINKAGE SECTION. To pass variable data, VDEFINE a dialog variable. The SELECT option is in effect.
DLG-VDEFINE 01  WS-EMPL-NBR  PIC X(05) AS EMPNBR
MOVE EMPL-NBR TO WS-EMPL-NBR
LINK PGM001 * PARM('&EMPNBR')
DLG-VDELETE EMPNBR
Link to the program in WS-PROGNAME. The CALL option is in effect.
MOVE 'PGM001' TO WS-PROGRAM
LINK /WS-PROGNAME
Link to PGM006 and pass Linkage data area SCR6-RECORD so that PGM006 can move data directly to screen fields. The CALL option is in effect.
LINK PGM006 * SCR6-RECORD
Parent topic: Data Communication Calls


MSG-SW

Send data or a message to the specified program trancode or subprogram.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

IMS DC

Syntax:

[TP-]MSG-SW trancode|programname|dataname
[errorpara]
... [screenname|recordname]
... [keyword[+keyword]...]

Syntax Rules:

  1. Allow the program to send invalid or empty screen values by specifying NORETRY with the NTRY keyword; use generated flags to test whether input data is valid.
  2. Use the PURG and NOPURG keywords to control how AMB sends messages. When issuing multiple inserts to the same destination before reaching a SYNC point, IMS sends the messages as one multi-segmented message. If you send the message via an Express PCB, AMB issues a PURG after the insert and sends it as one single-segmented message.
  3. Omitting screenname or recordname sends a message with a transaction code to the new program.
  4. When coding RECORD and recordname in conversational programs, and recordname differs from your application trancode, code:
    SYM1    % &recordname-TRANCODE = "trancode"

General Rules:

  1. Making both the sending and receiving program conversational passes data in the Commarea (SPA) to the new program (see TP-COMMAREA).
  2. MSG-SW lets a program send a message to itself. You might use this feature to break a long process into several small pieces.
  3. Remember to define an alternate IO PCB in the program specification block (PSB) and specify MODIFY=YES. See Program Control Blocks in online help for more information.

Parameters:

dataname | Name of data element
errorpara | User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
keyword | Valid keywords are:
 | NOALTRESP | Default. Use an IO PCB, not an alternate response IO PCB to send a response to the terminal.
 | ALTRESP | Use an alternate response IO PCB to send a response to the terminal.
 | NOCONT | Default. Control returns to top of the Procedure Division of the sending program.
 | CONT | Control returns to the instruction following call execution, that is, the next statement after the MSG-SW.
 | CONTCOND | TP-CONTCOND determines if control passes to the next instruction or returns to the top of the program.
 | NOEXPRESS | Default. Do not send a message for abnormal program termination.
 | EXPRESS | Send a message at program termination.
 | NOENDCONV | Default. Do not blank out the TRANCODE in the SPA.
 | ENDCONV | Blank out the TRANCODE in the SPA.
 | SCREEN | Default. Input is a AMB-painted screen. Multisegment screens are not supported.
 | RECORD | Input is recordname. See also Considerations below.
 | NOPURG | Send all messages to the same destination as one multi-segmented message. Default with NOEXPRESS argument.
 | PURG | After inserting the message, send it as one single-segmented message. Default with EXPRESS keyword.
record-name | User-defined I/O area in Working-Storage. See also Considerations below.
screen-name | Screen name; must be literal (maximum 8 characters).
trancode| program-name | Literal name of destination program or transaction code identifying receiving program; can be a literal (maximum 8 characters) or a COBOL data name (minimum 9 characters).

Examples:

Send messages to another program; perform error routine when error occurs.
MSG-SW trancode PROCESS-ERRORS
Send messages and pass a screen record. Note that the asterisk (*) replaces the positional parameter errorpara.
MSG-SW trancode * SCRA
Send messages and pass a COBOL record.
MSG-SW trancode * WS-CUSTOMER RECORD
Parent topic: Data Communication Calls
Related reference
TP-COMMAREA
Program Control Blocks, IO


RESET-PFKEY

Simulate screen invocation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax:

[TP-]RESET-PFKEY keyvalue

General Rule:

  1. When you set your DLG generation parameters in the Screen Painter:
    • Select Program Controlled for the program to control PF key processing. AMB saves the end user original PF key values and replaces them with literals not recognized by Dialog, so that you can control the PF key usage. When the program terminates, the original PF key values are restored.
    • Select ISPF Command Table for Dialog to control PF key processing. This is the default.

Parameters:

keyvalue

See the following table for valid values

Value Supported Targets

PF0

  • CICS
  • IMS

PF00

  • CICS
  • IMS

PF01 thru PF24

  • CICS
  • IMS
  • DLG

ENTER

  • CICS
  • IMS
  • DLG

ENTER-KEY

  • CICS
  • IMS
  • DLG

PA1

CICS

PA2

CICS

PA3

CICS

CLEAR-KEY

CICS

CLEAR

CICS

NO-KEY

IMS

NONE

IMS

PEN

CICS

TRIG

CICS

OPID

CICS

MSRE

CICS

STRF

CICS

Example:

Simulate pressing the ENTER key.
/* Move Commarea key to key field
MOVE CA-PASSED-KEY TO SCRN-KEY-FLD
/* Move Q to FUNCTION field
MOVE 'Q' TO SCRN-FUNCTION-FLD
/* Simulate pressing of ENTER key
/* with RESET-PFKEY call
RESET-PFKEY ENTER
/* Perform processing logic
TP-PERFORM APS-USER-CODE-PARA
Parent topic: Data Communication Calls


SCRNLIST

Enable your program to use multiple screens and generate
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Procedural code to receive each specified screen
  • Screen records in the Working-Storage or Linkage Sections

AMB generates SCRNLIST when you specify multiple I/O screens for a program in the Project Explorer.

Targets:

  • CICS
  • DLG
  • IMS DC

CICS

Syntax:
[TP-]SCRNLIST screenname1 [... screenname12]
... [MAPSET(mapsetname)]
... [LINKAGE]
... [REDEFINE|NOREDEF]
General Rule:
  1. You can generate multiple-map mapsets from the Actions menu in the Project Explorer on the AppMaster Builder desktop.
  2. See All Formats for additional rules.
Parameters:

screenname

The name of a screen.

MAPSETmapsetname)

Mapset containing the screen(s) received by the program; must be a literal (maximum 7 characters).

LINKAGE

Generate every screen record in the Linkage Section instead of in Working-Storage.

REDEFINE

Default. Screen records redefine each other.

NOREDEF

Screen records do not redefine each other. Ignored when coded with LINKAGE.

Examples:
Generate screen records SCRA and SCRB, that redefine each other, in Working-Storage. Both screens are in mapset SCRASET.
SCRNLIST SCRA SCRB MAPSET(SCRASET)
Generate a screen record in the Linkage Section for screen SCRA.
SCRNLIST SCRA MAPSET(SCRASET) LINKAGE
Generate screen records that do not redefine each other.
SCRNLIST SCRA SCRB NOREDEF

DLG

Syntax: for Format 1
[TP-]SCRNLIST screenname1[(LK)] [...
screenname40[(LK)]]
Syntax: for Format 2
[TP-]SCRNLIST screenname1[ ... screenname40]
... [LINKAGE]
General Rules:
  1. See All Formats for rules.
Parameters:

screenname

The name of a screen.

LINKAGE

Generate every screen record in the Linkage Section instead of in Working-Storage.

Examples:
Generate screen records SCRA and SCRB in Working-Storage
SCRNLIST SCRA SCRB
Generate screen record SCRA in Working-Storage, and screen record SCRB in the Linkage Section
SCRNLIST SCRA SCRB(LK)

IMS DC

Syntax: for Format 1
[TP-]SCRNLIST screenname1 [...screenname40]
Syntax: for Format 2
[TP-]SCRNLIST screenname1 [... screenname40]
General Rules:
  1. Label each screen in the Screen Painter. A labeled screen contains eight extra bytes (appended to the MID) that contain the screen name. NTRY logic determines which screen named in SCRNLIST was received, moves the data to the appropriate screen record description in Working-Storage, and performs any specified field editing.
  2. Screens separated with a slash (/) instead of a space redefine each other in Working-Storage, limiting the size of Working-Storage.
  3. A maximum of 30 screens can be listed in the Project Explorer (and thus appear in the automatically-generated TP-SCRNLIST).
  4. You can write rules to customize SCRNLIST processing for some or all screens in the screen list, using a AMB-supplied predefined rule name. AMB executes the rules at locations immediately before and after the following AMB-generated paragraphs.
    AMB Paragraph Paragraph Function

    APS-CHK-SCRN-RECEIVED-PARA

    Checks which screen was received

    APS-screenname-RECEIVED-PARA

    Receives the screen

    APS-SCRNLIST-EDIT-PARA

    Determines which screen has field edits

    APS-screenname-INP-EDIT-PARA

    Processes screen field edits

    Define the rules using these predefined rule name formats:

    $TP-PRE-CHK-SCRN-RECEIVED$TP-POST-CHK-SCRN-RECEIVED
$TP-PRE-screenname-RECEIVED
$TP-POST-screenname-RECEIVED
$TP-PRE-SCRNLIST-EDIT
$TP-POST-SCRNLIST-EDIT
$TP-PRE-screenname-INP-EDIT
$TP-POST-screenname-INP-EDIT
  5. See All Formats for additional rules.
Parameters:

screenname

The name of a screen.

Example:
Code logic that receives either SCREENA, SCREENB, or SCREENC, and always sends SCREENC as the output screen
IF TP-SCREENA-RECEIVED
    SCREENC-FIELD-1 = SCREENA-FIELD-X
    SCREENC-FIELD-2 = SCREENA-FIELD-Y
    SCREENC-FIELD-3 = SCREENA-FIELD-Z
          .
          .
IF TP-SCREENB-RECEIVED
    SCREENC-FIELD-1 = SCREENB-FIELD-XX
    SCREENC-FIELD-2 = SCREENB-FIELD-YY
    SCREENC-FIELD-3 = SCREENB-FIELD-ZZ
Code logic where, during a single execution, the program can receive either SCREENA or SCREENB. Let SCREENA and SCREENB redefine each other; keep SCREENC separate (not involved in the redefinition in the SCRNLIST call) in order to prevent any improper overlaying (and thus destruction) of data fields.
SCRNLIST SCREENA/SCREENB SCREENC

All Formats

General Rules:
  1. Code the SCRNLIST call to override the AMB-generated TP-SCRNLIST.
  2. Code SCRNLIST only once, before NTRY, and do not code a screen name with NTRY.
  3. AMB generates 88-level flags indicating the received screen:
    TP-SCRN-RECEIVED               PIC X(08)
    88  TP-screenname-RECEIVED VALUE 'screenname'.
Parent topic: Data Communication Calls


SEND

Display screen data for end user response.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

CICS

SEND generates a CICS SEND MAP command to send screen data to a terminal for user response, as well as a CICS RETURN command to return control to CICS.

Syntax:
[TP-]SEND screen[(mapsetname)] errorpara|*
... [TRANSID(name)]
... [NORETURN] [NOERASE]
... [CICSoption [CICSoption] ...]
Parameters:

mapsetname

Mapset containing the screen(s) the program receives; must be a literal (maximum 7 characters). When not specified, generates a default mapset name as per NTRY.

errorpara|*

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

TRANSID (name)

Transaction code identifying the program where control returns; can be a literal (maximum 4 characters) or COBOL data name (minimum 5 characters).

NORETURN

Suppress the default generation of CICS RETURN (after a generated CICS SEND MAP call).

NOERASE

Suppress the default generation of ERASE.

Examples:

Send screen map SCRA.

Program Painter source:

SEND SCRA

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    CURSOR
    ERASE
    FREEKB END-EXEC.
EXEC CICS RETURN
    TRANSID( 'SCRA')
    COMMAREA(TP-COMMAREA)
    LENGTH(169) END-EXEC.
GO TO APS-USER-MAIN-PARA--EXIT.

Generate a CICS SEND MAP for map SCRA in mapset SCRASET; return to CICS with transaction code WXYZ. Override the default TRANSID specified in the Screen Painter.

Program Painter source:

SEND SCRA(SCRASET) * TRANSID('WXYZ')

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    CURSOR
    ERASE
    FREEKB END-EXEC.
EXEC CICS RETURN
    TRANSID( 'WXYZ')
    COMMAREA(TP-COMMAREA)
    LENGTH(169) END-EXEC.
GO TO APS-USER-MAIN-PARA--EXIT.

Generate a CICS SEND MAP for map SCRA.

Program Painter source:

SEND SCRA * NORETURN

Generated source:

EXEC CICS SEND MAP( 'SCRA')
    FROM(AA00-RECORD)
    MAPSET( 'SCRASET')
    END-EXEC.

DLG

Display screen data for end user response.

Syntax:
[TP-]SEND screen errorpara|*
... [CONTINUE|NOCONTINUE]
General Rules:
  1. With NOCONTINUE, enter your return code checking routine under TP-SCREEN-INVOKED logic. With CONTINUE, enter your return code checking routine under SEND.

  2. The following AMB-provided structure checks the return code after a SEND.
    APS-TP-SEND-RC           PIC 9(08).
    88  OK-ON-SEND       VALUE 0.
    88  NTF-ON-SEND      VALUE 4.
    88  END-ON-SEND      VALUE 8.
    88  AB-ON-SEND       VALUE 12 16 20
Parameters:

errorpara|*

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

CONTINUE

Execute the next instruction after the call.

NOCONTINUE

Default. Return control to the top of the program.

Examples:
Display screen SCRA. Determine whether END or RETURN was entered on the screen.
NTRY  SCRA
      IF TP-PROGRAM-INVOKED
          PERFORM  INITIALIZE-SCREEN-FIELDS
      ELSE-IF TP-SCREEN-INVOKED
          IF  END-ON-SEND
          ... OR SCRA-FUNCTION = 'E'
              /* USER ENTERED END OR RETURN
              TERM
          ELSE-IF OK-ON-SEND
              PERFORM  PROCESS-SCREEN-DATA
          ELSE
              SCRA-SYSMSG = 'INVALID OPTION'
      SEND SCRA * NOCONTINUE
Display screen SCRA. Determine whether END or RETURN was entered on the screen. Perform return code checking immediately following the SEND.
REPEAT
    SEND SCRA * CONTINUE
UNTIL APS-TP-SEND-RC > 0
    PERFORM  PROCESS-SCREEN-DATA
TERM

IMS DC

Send screen messages, in screen or record layout form, to terminals or printers.

Syntax:
 [TP-]SEND screenname|recordname errorpara|*
 ... [lterm]
 ... [keyword[+keyword] ...]
Syntax Rules:
  1. For recordname, move the MOD name to IM-SCREEN-RECORD-MODNAME (a AMB-generated field) prior to SEND. Multisegment screens are not supported.
  2. When coding RECORD and recordname in conversational programs, code the following statement if recordname differs from your application trancode.
    SYM1    % &recordname-TRANCODE = "trancode"
General Rules:
  1. Use the PURG and NOPURG keywords to control how AMB sends messages. When issuing multiple inserts to the same destination before reaching a SYNC point, IMS sends the messages as one multi-segmented message. If you send the message via an Express PCB, AMB issues a PURG after the insert and sends it as one single-segmented message.
  2. When sending screens with edited fields, the value of the field variable (the COBOL name assigned during screen painting) moves to a field defined with a display format. The edited fields must contain valid values on output or the screen returns for correction.
  3. To allow end users to send invalid or empty screen values, specify NORETRY with the NTRY keyword and use the generated flags to test for input data validity.
  4. SEND logically terminates a program when executed; however, the program actually runs as a loop that processes multiple input messages.
  5. To retain control in the program after sending a screen, code the CONT keyword. You can then send more than one screen or message from a program while processing a single transaction, or send multiple pages of output to the same destination.
  6. When coding a conversational program in Online Express, AMB checks your alternate IO PCB for the following parameters:
    EXPRESS=YESMODIFY=YESALTRESP=YES

    If any parameters are missing, a message warns you that, if an error occurs after successful database updates, AMB does not send a message to the originating terminal--the program simply terminates and performs a rollback of the updates.

  7. In a single program execution, the terminal operator can page forward and backward with MFS logical paging commands. To do this:
    • Ensure that all pages are for the same screen format.
    • Ensure that all generated AMB screens contain a single DPAGE.
    • Specify operator logical paging on the Screen Generation Parameters window in the Screen Painter.
    • Specify that the trancode comes either from a screen field or from PF keys. If PF keys provide all or part of the trancode, define the PF key values on the MFS Function Key window.
Parameters:

screenname

Screen name; must be literal (maximum 8 characters).

recordname

User-defined I/O area in Working-Storage.

errorpara|*

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

lterm

Logical terminal or printer where program sends message; can be a literal (maximum 8 characters) or COBOL data name (maximum 9 characters). Default is device that sends an input message to the program.

keyword

Valid keywords are:

NOALTRESP

Default. Use an IO PCB, not an alternate response IO PCB to send a response to the terminal.

ALTRESP

Use an alternate response IO PCB to send a response to the terminal.

NOCONT

Default. Control returns to top of the Procedure Division of the sending program.

CONT

Control returns to the instruction following call execution, that is, the next statement after the MSG-SW.

CONTCOND

TP-CONTCOND determines if control passes to the next instruction or returns to the top of the program.

NOEXPRESS

Default. Do not send a message for abnormal program termination.

EXPRESS

Send a message at program termination.

NOENDCONV

Default. Do not blank out the TRANCODE in the SPA.

ENDCONV

Blank out the TRANCODE in the SPA.

SCREEN

Default. Input is a AMB-painted screen. Multisegment screens are not supported.

RECORD

Input is recordname. See also Considerations below.

NOPURG

Send all messages to the same destination as one multi-segmented message. Default with NOEXPRESS keyword.

PURG

After inserting the message, send it as one single-segmented message. Default with EXPRESS keyword.

Examples:
Send the single screen defined as output for the program.
SEND
In a program with multiple output screens, qualify the screens to send.
SEND SCRA
Send a screen using the EXPRESS PCB.
SEND SCRA * * EXPRESS
Send a screen using an alternate PCB and return to the next instruction following the call.
SEND SCRA * * CONT+ALTRESP
Parent topic: Data Communication Calls


TERM

Terminate programs and transaction operations. Under DLG, performs internal program cleanup, terminate the program via GOBACK statement, and return control to the calling program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax:

[TP-]TERM

General Rules: for CICS

  1. AMB generates a CICS RETURN without a TRANSID or COMMAREA. Program control returns to either the next higher-level linked program or to CICS.
  2. Code TERM in a linked-to program that returns to the calling program and ensures that TP-COMMAREA data is passed back. When returning to a calling program, TP-COMMAREA moves to DFHCOMMAREA.
  3. Call does not terminate an active PSB that is passed via LINK.

General Rules: for IMS DC

  1. Use TERM after sending output messages (SEND or MSG-SW) with CONTINUE. Do not use TERM prior to sending at least one response; this causes a user terminal in response mode to remain locked, awaiting a response.

Example:

Terminate a program when SCRA-FUNCTION = 'E' or PF3 is pressed.
IF  SCRA-FUNCTION = 'E' OR PF3
    TERM
Parent topic: Data Communication Calls


TP-BACKOUT

ABEND the program. In IMS programs, this call invokes the IMS dynamic backout feature, canceling all database updates and messages sent since running the program or since receipt of the most recent input message.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • IMS DC

CICS

Syntax:
TP-BACKOUT [ABORT[(name)]|NOABORT]
Parameters:

ABORT(name)

Invoke CICS ABEND to terminate task. Name specifies a formatted dump of main storage; can be literal or COBOL data name (maximum 4 characters).

NOABORT

Nonfunctional--allowed for compatibility with IMS.

Examples:
The following three examples execute identically. Each terminates a task abnormally by invoking a CICS ABEND code.
TP-BACKOUT
TP-BACKOUT ABORT
TP-BACKOUT NOABORT
Specify a recovery option and code name to identify a main storage dump related to the task.
TP-BACKOUT ABORT('PGM1')

IMS DC

Syntax:
TP-BACKOUT [ABORT|NOABORT] [CONT|NOCONT]
General Rules:
  1. Use ABORT if the detected error prevents other messages from processing successfully.
  2. Use NOABORT if the detected error is specific to the processing message.
  3. To send a message and use TP-BACKOUT, use the EXPRESS keyword with either SEND or MSG-SW.
  4. Coding NOABORT calls an IMS ROLB with the current input message discarded; ABORT calls an IMS ROLL.
  5. The IMS option of issuing a ROLB with an IOAREA to reread the current input message is not supported by TP-BACKOUT. For further information on ROLL and ROLB, see the appropriate IMS manuals.
Parameters:

ABORT

Cancel program and do not reschedule.

NOABORT

Default. Return next input message for processing.

CONT

Default. Set the TP-GOBACK flag to FALSE.

NOCONT

Set the TP-GOBACK flag to TRUE.

Examples:
The following three examples execute identically. Each terminates a task abnormally by invoking a CICS ABEND code.
TP-BACKOUT
TP-BACKOUT ABORT
TP-BACKOUT NOABORT
Specify a recovery option and code name to identify a main storage dump related to the task.
TP-BACKOUT ABORT('PGM1')
Parent topic: Data Communication Calls


TP-COMMAREA

TP-COMMAREA generates a Working-Storage record for passing data between programs or coordinates the placement of the AMB-generated Commarea structure with a user-provided redefinition of that structure.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

CICS

TP-COMMAREA generates a Working-Storage record for passing data between programs. This record contains AMB information as well as user data.

There is no need to code a TP-COMMAREA call; AMB generates it. The value of &TP-USER-LEN--the default is 80--determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the AMB default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields.

The following calls pass a Commarea:

SEND | Send a screen to the terminal and terminate the program. CICS saves the data stored in the TP-COMMAREA and makes it available to the next program when AMB returns the screen to CICS.
LINK | Link to a subprogram, passing it the TP-COMMAREA address. Define COMMAREA identically in each program.
XCTL | Transfer control to another program, passing a copy of TP-COMMAREA. Define TP-COMMAREA identically in both programs.

You can redefine TP-USERAREA to fit program requirements.

  • Code the redefinition in the Data Structure Editor. You must also specify the Commarea redefinition in Application View--code its name in the Data Str field and specify its type as CA (Commarea).
  • Code the redefinition in the Program Painter. Three keywords are available to redefine TP-USERAREA: CA, where you code the redefinition in Data Structure Editor syntax; CA05 and CA, where you code it in COBOL syntax.

Optionally, you can code the redefinition in a copybook or rule that you include.

Examples:
Redefine TP-USERAREA in the Program Painter.
 SYM1   % * SET THE LENGTH OF TP-USERAREA TO
        % * 21 BYTES
        % &TP-USER-LEN = 21
 CA     AACA-USERAREA
            CA-DATE                X8
            CA-TIME                X8
            CA-CUST-NUMBER         X5
 SYM1   % * SET THE LENGTH OF TP-USERAREA TO
        % * 21 BYTES
        % &TP-USER-LEN = 21
 CA05   AACA-USERAREA
        10  CA-DATE                X8
        10  CA-TIME                X8
        10  CA-CUST-NUMBER         X5
Redefine TP-USERAREA in the Data Structure Editor.
AACA-USERAREA
    CA-DATE                X8
    CA-TIME                X8
    CA-CUST-NUMBER         X5
Each of the above examples generates:
01  TP-COMMAREA
          .
          .
          .
01  FILLER REDEFINES TP-COMMAREA.
    05  FILLER                PIC X(40).
    05  TP-USERAREA           PIC X(21).
    05  AACA-USERAREA   REDEFINES TP-USERAREA.
        10  CA-DATE           PIC X(08).
        10  CA-TIME           PIC X(08).
        10  CA-CUST-NUMBER    PIC X(05).

DLG

TP-COMMAREA generates a Working-Storage record for passing data between programs. This record contains AMB information and user data.

There is no need to code a TP-COMMAREA call; AMB generates it. The value of &TP-USER-LEN--the default is zero-- determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the AMB default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields. You must define the Commarea in Working-Storage.

To redefine TP-USERAREA as a group-level data structure, the length must be the same as the value specified for &TP-USER-LEN. A CA01 keyword generates an 05-level REDEFINES TP-USERAREA statement.

To generate a single-field Commarea in Working-Storage called TP-USERAREA, assign a value to the AMB variable &TP-USER-LEN. Code the following on one line.

 SYM1    % &TP-USER-LEN = number
  • SYM1 indicates &TP-USER-LEN is an Customizer variable and places the variable at the top of the program.
  • &TP-USER-LEN = number specifies the size of TP-USERAREA; it should be large enough to store all fields of data on the screen that the program receives. The default for number is zero.

To receive TP-COMMAREA as a passed data area from a calling program, code this assignment statement before NTRY.

        % &DLG-COMMAREA-IN-LINKAGE = "YES"

The results are:

  • AMB generates the following in the Linkage Section
    01  DLG-LINKAGE-COMMAREA  PIC X(&TP-USER-LEN).
  • AMB generates the Procedure Division statement with
    ... USING DLG-LINKAGE-COMMAREA
  • Generated logic maps the data between TP-COMMAREA and DLG-LINKAGE-COMMAREA at the following points
    • Upon program invocation, from DLG-LINKAGE-COMMAREA to TP-COMMAREA
    • Before execution of LINK or XCTL, from TP-COMMAREA to DLG-LINKAGE-COMMAREA
    • After execution of LINK or XCTL, from DLG-LINKAGE-COMMAREA to TP-COMMAREA
    • Before program termination, from TP-COMMAREA to DLG-LINKAGE-COMMAREA
Example:
Redefine TP-USERAREA.

Program Painter source:

 SYM1   % &TP-USER-LEN = 49
 CA05   PGM-USERAREA
            10  CA-EMPLOYEE-NAME    PIC X(20).
            10  CA-EMPLOYEE-TITLE   PIC X(20).
            10  CA-EMPLOYEE-SSN     PIC X(09).

Generated source:

01 TP-COMMAREA.
   05  TP-USERAREA              PIC (X49).
   05  PGM-USERAREA REDEFINES TP-USERAREA.
       10  CA-EMPLOYEE-NAME     PIC X(20).
       10  CA-EMPLOYEE-TITLE    PIC X(20).
       10  CA-EMPLOYEE-SSN      PIC X(09).

IMS DC

TP-COMMAREA coordinates the placement of the AMB-generated Commarea structure with a user-provided redefinition of that structure. Use it only with conversational IMS programs - nonconversational IMS programs do not use a Commarea.

In IMS, the Commarea is called a SPA (Scratch Pad Area). Its reserved prefix includes an IMS LLZZ field, the input trancode, and the AMB invocation mode flag.

There is no need to code a TP-COMMAREA call; AMB generates it. The value of &TP-USER-LEN--the default is 0--determines the size of TP-USERAREA, the user portion of TP-COMMAREA. You can accept the AMB default of a single Commarea field, TP-USERAREA, or redefine TP-USERAREA as multiple Commarea fields. You must define the Commarea in Working-Storage.

To redefine TP-USERAREA as a group-level data structure, the length must be the same as the value specified for &TP-USER-LEN. A CA01 keyword generates an 05-level REDEFINES TP-USERAREA statement.

To generate a single-field Commarea in Working-Storage called TP-USERAREA, assign a value to the AMB variable &TP-USER-LEN. Code the following on one line.

SYM1   % &TP-USER-LEN = number
  • SYM1 indicates &TP-USER-LEN is an Customizer variable and places the variable at the top of the program.
  • &TP-USER-LEN = number specifies the size of TP-USERAREA; it should be large enough to store all fields of data on the screen that the program receives. Caution An undefined &TP-USER-LEN defaults to zero; when prototyping, the default is 2048.
Examples:
Program Painter source:
 SYM1   % &TP-USER-LEN = 100
 CA05   MY-REDEF
        10 CA-FLD-A            PIC X(10).
        10 CA-FLD-B            PIC S9(4) COMP.
        10 CA-FLD-C            PIC X(20).
Generated source:
% &TP-USER-LEN = 100
IDENTIFICATION DIVISION
          .
          .
WORKING-STORAGE SECTION.
$TP-WS-MARKER
$TP-COMMAREA
    05  MY-REDEF REDEFINES TP-USERAREA.
        10 CA-FLD-A            PIC X(10).
        10 CA-FLD-B            PIC S9(4) COMP.
        10 CA-FLD-C            PIC X(20).
Parent topic: Data Communication Calls


TP-LINKAGE

Handle addressability of Linkage Section data records in a called program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax:

TP-LINKAGE linkdataname[/
copybookname|rulefilename]
... [linkdataname[/copybookname|rulefilename] ...]

General Rules

  1. Code call on the first line of the Linkage Section.
  2. List data items in the order that they appear in the Linkage Section, copybook, or rule file.
  3. Make sure that each linkdataname you specify is defined in the Linkage Section. Choose one of the following methods:
    • Define them yourself.
    • Include (using TP-LINKAGE) a copybook or rule file that contains the linkdatanames.
  4. TP-LINKAGE generates a % INCLUDE to include the copybook or macro. If you want TP-LINKAGE to generate a COBOL COPY statement, instead of a % INCLUDE statement, code &TP-COPY-LINKAGE = 1 prior to the TP-LINKAGE call.
  5. In Online Express, list the records in the order they pass from the calling program.

General Rules: for CICS

  1. Use TP-LINKAGE with calls that use the SET option.

  2. Coding TP-LINKAGE with the SYLT keyword ensures that the AMB-generated DFHCOMMAREA is the first record in the Linkage Section. This prevents the CICS translator from generating an additional one.
  3. One BLL cell is generated per 4,096 bytes. Linkage records longer than 4,096 bytes require additional BLL cells to establish addressability to the entire record.
  4. To generate additional BLL cells, code dummy records after the record that is greater than 4,096 bytes. A dummy record name must be prefixed with DUMMY and its copybook name must be DUMMY.
  5. BLL cells are not used with COBOL/2.

General Rules: for DLG

  1. AMB provides this call for compatibility with CICS and IMS--it is not required to handle addressability of Linkage Section records.
  2. Make the linkdataname a PARM area and the only area defined in the Linkage Section, if the PROGRAM CONTROL TRANSFER option is SELECT.

General Rules: for IMS DC

  1. Code the call on the first line of the Linkage Section, and with either NTRY or PROC to generate parameters for the PROCEDURE DIVISION USING statement.
  2. Do not define PCBs with TP-LINKAGE; the subschema defines them.

Examples:

Define records LINK-REC-1 and LINK-REC-2. Include definitions from USERMACS rule members LINKR1 and LINKR2.
TP-LINKAGE LINK-REC-1/LINKR1 LINK-REC-2/LINKR2
Define records LINK-REC-1 and LINK-REC-2 and copy their definitions from COPYLIB members LINKR1 and LINKR2.
% &TP-COPY-LINKAGE = 1
TP-LINKAGE LINK-REC-1/LINKR1 LINK-REC-2/LINKR2
Define records LINK-REC-1 and LINK-REC-2, coded in the Linkage Section.
TP-LINKAGE LINK-REC-1 LINK-REC-2
Define records LINK-REC-1 and LINK-REC-2. LINK-REC-1 has been coded in the Linkage Section; LINK-REC-2 is copied from COPYLIB member LINKR2.
% &TP-COPY-LINKAGE = 1
TP-LINKAGE LINK-REC-1 LINK-REC-2/LINKR2
LINK-REC-1       PIC X(100).

CICS

Linkage record containing 10,000 bytes.
 SYLK   TP-LINKAGE LINK-REC
        ... DUMMY-LINK-REC-BLL1/DUMMY
        ... DUMMY-LINK-REC-BLL2/DUMMY
 LK01   LINK-REC.
        05  LINK-REC-1-4096       PIC X(4096).
        05  LINK-REC-2-8192       PIC X(4096).
        05  LINK-REC-3-10000      PIC X(1808).
 OPT    PROG
 NTRY
        CIC-GETMAIN
        ... SET(LINK-REC)
        ... LENGTH(10000)
        /* PROGRAM HAS ADDRESSABILITY TO
        /* THE FIRST 4,096 BYTES.
        ADD 4096 LINK-REC--P
        ... GIVING DUMMY-LINK-REC-BLL1--P
        ... GIVING DUMMY-LINK-REC-BLL2--P
        /* PROGRAM HAS ADDRESSABILITY TO
        /* ALL 10,000 BYTES.

DLG

Define a PARM area for use by TP-LINK and TP-ENTRY. The PROGRAM CONTROL TRANSFER option has been set to SELECT. PGM-PARM-DATA is coded inline. Note You can place the PGM-PARM-DATA area in Linkage without the use of TP-LINKAGE.
 SYLK   TP-LINKAGE PGM-PARM-DATA
 LK01   PGM-PARM-DATA.
            05  PGM-PARM-DATA-LEN   PIC S9(04) COMP.
            05  PGM-PARM-EMPNBR     PIC X(05).
            05  FILLER              PIC X(95).
Parent topic: Data Communication Calls


TP-NULL

Move LOW-VALUES to all fields in a specified screen record. This call does not alter the field attributes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax:

TP-|SC-NULL screenname

Parameters:

screenname

Screen name; value must be literal.

Example:

Move LOW-VALUES to all fields on screen SCRA.
TP-NULL SCRA
Parent topic: Data Communication Calls


TP-PERFORM

Perform a paragraph, with or without passing arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG
  • IMS DC

Syntax: for Format 1

Perform a paragraph

TP-PERFORM paragraphname

Syntax: for Format 2

Perform a paragraph and pass arguments

TP-PERFORM paragraphname actualargument1[[,]
... actualargument2[,] ... actualargument8]
          .
paragraphname ([+|-]formalargument1[[,]
... [+|-]formalargument2[,] ... [+|-
]formalargument8])

General Rules:

  1. When continuing a list of arguments onto one or more other lines, do not break an argument.
  2. The number of actual arguments must equal the number of formal argument names and be in the same order.

Parameters:

+|- | A plus (+) or minus (-) sign preceding a formalargument passes values between actual arguments and formal arguments, as follows.
 | With a plus sign (+), PERFORM passes the actualargument value to formalargument after the paragraph executes. The program does not return the formalargument value to actualargument.
 | With a minus sign (-), PERFORM passes the formalargument value to the actualargument after the paragraph executes.
 | If there is no prefix, the PERFORM passes the actualargument to its corresponding formalargument. After the paragraph executes, PERFORM passes the formalargument back to its corresponding actualargument.
actual-argument | Values you send or receive from a formalargument in the paragraph; can be literals, identifiers, arithmetic expressions, or index names.
formal-argument | Values you receive from or send to an actualargument in the PERFORM statement.
paragraph-name | Name of paragraph to perform.
Parent topic: Data Communication Calls


XCTL

XCTL either transfers control from a program at one logical level to a AMB or non-AMB application program at the same level, and passes the Commarea, or it operates identically to LINK.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • DLG

CICS

Transfer control from a program at one logical level to a AMB or non-AMB application program at the same level, and pass the Commarea.

Syntax: for Format 1

Transferring to a AMB program

[TP-]XCTL programname [errorpara]
... [LENGTH(value)]
... [DLIUIB pcbname [pcbname ...]]
... [userparm [userparm] ...]
Syntax: for Format 1

Transferring to a non-AMB program

[TP-]XCTL programname(NONAPS) [errorpara]
... [LENGTH(value)]
General Rules:
  1. When transferring control to a AMB program, XCTL transfers control to the program specified in the call and passes the TP-COMMAREA. Ensure that the Commarea in the transferred-to program is the same length as the TP-COMMAREA you pass.
  2. When transferring to a non-AMB program, XCTL transfers control to the specified program and passes the TP-USERAREA. Ensure that the Commarea in the transferred-to program is the same length as the TP-USERAREA you pass. (TP-USERAREA gets its value from &TP-USER-LEN.) Additionally, code the following before your NTRY statement.
    % &TP-PROGRAM-INVOCATION = "NONAPS"
Parameters:

DLIUIB pcbname

DLI interface block and the Program Control Block required by the next program.

errorpara

User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.

LENGTH (value)

Maximum length of data; can be a literal or COBOL data name defined as S9(04)COMP. Can also be a partial length.

(NONAPS)

The program is not a AMB program.

NOTERM

Do not terminate the screen display for the calling program, that is, display screens for both the called and the calling program.

programname

Program name; can be a literal, variable, or combination. If you precede a variable name with a slash (/), AMB moves the literal to it. There is no active PSB and no passing of arguments.

Examples:
Transfer control to PGM001. There is no active PSB and no passing of arguments.
XCTL PGM001
Transfer control to the program whose name is stored in WS-PROGNAME. There is no active PSB and no passing of arguments.
XCTL /WS-PROGNAME
Move the value PGM003 to WS-PROGNAME and transfer control to that program. There is no active PSB and no passing of arguments.
XCTL PGM003/WS-PROGNAME
Transfer control to PGM004; execute an error routine for an abnormal condition. There is no active PSB and no passing of arguments.
XCTL PGM004 ERR-PARA
Transfer control to PGM005. A PSB is scheduled and the transferred-to program uses PCB ABC-PCB.
XCTL PGM005 * DLIUIB ABC-PCB
Transfer control to a non-AMB program, PROG001.
XCTL PROG001(NONAPS)

DLG

XCTL, which calls a subprogram at the next lower level, operates identically to LINK. XCTL invokes LINK, providing no additional functionality and does not pass the COMMAREA; XCTL is provided for upward compatibility.

Parent topic: Data Communication Calls


Data Structures

Lists the shorthand data structures valid in the Data Structure Editor.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Code reusable data structures for programs and copy files, using a shorthand format in the Data Structure Editor. Or, code these data structures specifically for your program in the Program Painter. The shorthand format substitutes indentation for level numbers and allows shorthand picture formats. The AMB generators insert level numbers for indentation levels, expand the shorthand formats to full COBOL formats, and insert the necessary punctuation. Alternatively, you can code data structures in the standard COBOL format.

  • 66 ...RENAMES
    Code 66-level RENAMES clauses in your data structures.
  • 88
    Code 88-level clauses in your data structures.
  • OCCURS
    Code OCCURS clauses in your data structures.
  • REDEFINES
    REDEFINES enables you to code clauses in your data structures that redefine elements.
  • VALUE
    VALUE enables you to code VALUE clauses into your data structures.
  • Edit Mask Characters
  • Picture Formats
    Code data structures in the Data Structure Editor format, which is a shorthand syntax.
Parent topic: Reference


66 ...RENAMES

Code 66-level RENAMES clauses in your data structures.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

66 anytext

Syntax Rule:

  1. A 66-level variable needs the same or deeper indentation than the data name it refers to.

Parameters:

anytext

Valid COBOL syntax for 66-levels.

Example 1: Data Structure Editor format

000001   WORK-RECORD
000002      WORK-RECORD-GRP1
000003          WORK-FIELD-1   XX
000004          WORK-FIELD-2   XXX
000005          WORK-FIELD-3   PIC X(04)
000006      WORK-RECORD-GRP2
000007          WORK-FIELD-4   PIC X(02)
000008          WORK-FIELD-5   PIC X(06)
000009      WORK-RECORD-GRP3
000010          WORK-FIELD-6   PIC X(08)
000011          WORK-FIELD-7   PIC X(02)
000012   66  RECORD-1-REN RENAMES WORK-FIELD-1
000013   ... THRU WORK-FIELD-6

Example 2: Generated COBOL code

01  WORK-RECORD.
    05  WORK-RECORD-GRP1.
        10  WORK-FIELD-1        PIC XX.
        10  WORK-FIELD-2        PIC XXX.
        10  WORK-FIELD-3        PIC X(04).
    05  WORK-RECORD-GRP2.
        10  WORK-FIELD-4        PIC X(02).
        10  WORK-FIELD-5        PIC X(06).
    05  WORK-RECORD-GRP3.
        10  WORK-FIELD-6        PIC X(08).
        10  WORK-FIELD-7        PIC X(02).
    66  RECORD-1-REN RENAMES WORK-FIELD-1
                            THRU WORK-FIELD-6.
Parent topic: Data Structures
Related reference
88
OCCURS
REDEFINES
VALUE
Edit Mask Characters
Picture Formats


88

Code 88-level clauses in your data structures.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

88   dataname VALUE 'value1' [THRU 'value2']
...                'value3' [THRU 'value4']
...                'value5' [THRU 'value6']
                .
                .
...                'valueN' [THRU 'valueN']

Syntax Rules:

  1. An 88-level variable needs the same or deeper indentation as the data name it refers to.
  2. You can code the VALUE clause either:
    • On the same line as dataname if it fits entirely on that line
    • On its own line and continue it on subsequent lines with the continuation symbol

Parameter:

value

88-level value; do not enclose numeric values in single quotation marks.

Example 1: Data Structure Editor format

-LINE- ------- Data Structure Editor --------
000001      WRK1-FIELD-1 X5
000002        88 OPEN-VAL
000003        ... V 'OPEN' 'BEGIN'
000004        ...  'START'
000005        88 OPEN-FLAG
000006        ... VALUE 'ON'
000007        ... 'YES'

Example 2: Generated COBOL code

01  WRK1-FIELD-1          PIC X(5).
    88  OPEN-VAL          VALUE 'OPEN' 'BEGIN'
                          'START'.
    88  OPEN-FLAG         VALUE 'ON'
                          'YES'.

Example 3: Data Structure Editor format

-LINE- ------- Data Structure Editor --------
000009      WRK1-FIELD-2 X(04)
000010        88 SUB-LVL1
000011        ... V 'ABCD' 'EFGH'
000012        ... 'FFFF' THRU 'MMMM'
000013        ... 'PPPP' THRU 'ZZZZ'
000014        88 SUB-LVL2
000015        ... V LOW-VALUES

Example 4: Generated COBOL code

01  WRK1-FIELD-2           PIC X(04).
    88  SUB-LVL1           VALUE 'ABCD' 'EFGH'
                           'FFFF' THRU 'MMMM'
                           'PPPP' THRU 'ZZZZ'.
    88  SUB-LVL2           VALUE LOW-VALUES.

Example 5: Data Structure Editor format

-LINE- ------- Data Structure Editor --------
000016      WRK1-FIELD-3 H
000017        88 SUB-LVL3
000018        ... V -1000 +1000
000019        ... -900 THRU -700
000020        ... +500 THRU +800

Example 6: Generated COBOL code

01  WRK1-FIELD-3           PIC S9(4) COMP.
    88 SUB-LVL3            VALUE -1000 +1000
                                 -900 THRU -700
                                 +500 THRU +800.
Parent topic: Data Structures
Related reference
66 ...RENAMES
OCCURS
REDEFINES
VALUE
Edit Mask Characters
Picture Formats


OCCURS

Code OCCURS clauses in your data structures.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

dataname(OCCURSclause) [TIMES]
[... DO|ODO dataname]
[... IX|IB|IXB|IXBY dataname]
[... ASCENDING KEY IS dataname]
[... DESCENDING KEY IS dataname]
 ... PICformat

Shorthand syntax for the dimensions of a table in an OCCURS clause:

Parent topic: Data Structures
Related reference
66 ...RENAMES
88
REDEFINES
VALUE
Edit Mask Characters
Picture Formats


REDEFINES

REDEFINES enables you to code clauses in your data structures that redefine elements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

dataname REDEF[INES]|R PICformat

Syntax Rules:

  1. When identifing controls in the Control Files clause, dataname must be an elementary data name.
  2. In the following example, B cannot be used as a control variable because it is a group data item. To make B into an elementary data item, use the REDEFINES clause.
    WS01  A                         PIC X(2).
WS01  B.
      02  B-1                   PIC 9(4).
      02  B-2                   PIC 9(4).
WS01  B-REDEF  REDEFINES B      PIC X(8).
      .
      .
      .
RED TEST-REPORT
    CONTROLS ARE A B-REDEF

Parameters:

PICformat

PICTURE format for data name being redefined

Example 1: Data Structure Editor format

-LINE- ------- Data Structure Editor --------
000001        WRK1-FIELD-8
000002            WRK1-FIELD-9    X4
000003            WRK1-FIELD-10   X(30)
000004        WRK1-FIELD-11       R X34

Example 2: Generated COBOL code

01  WRK1-FIELD-8.
    05  WRK1-FIELD-9            PIC X(4).
    05  WRK1-FIELD-10       PIC X(30).
01  WRK1-FIELD-11   REDEFINES WRK1-FIELD-8  PIC
X(34).
Parent topic: Data Structures
Related reference
66 ...RENAMES
88
OCCURS
VALUE
Edit Mask Characters
Picture Formats
Control (CNTL) Files


VALUE

VALUE enables you to code VALUE clauses into your data structures.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

dataname PICformat
[...] [VALUE|V] 'valueclause'

Syntax Rules:

  1. Valueclause can be as long as you need, continuing on subsequent lines with the continuation symbol.
  2. You can code valueclause on the same line as dataname, if it fits entirely on that line.
  3. Do not enclose numeric values in single quotation marks.

Example 1: Data Structure Editor format

-LINE- ----- Data Structure Editor ----------
000001  WRK1-FIELD-7 X(120)
000002  ... VALUE 'A LONG LITERAL MAY BE
000003  ...  CONTINUED ON ONE OR
000004  ...  MORE LINES'
000005  WRK1-FIELD-8 X(80)
000006  ... V 'A VALUE CLAUSE THAT SPANS
000007  ...  TWO OR MORE LINES MUST BEGIN
000008  ...  ON ITS OWN LINE'

Example 2: Generated COBOL code

 01  WRK1-FIELD-7    VALUE 'A LONG LITERAL MAY BE CONT
   'INUED ON ONE OR MORE LINES'
                           PIC X(120).
 01  WRK1-FIELD-8    VALUE 'A VALUE CLAUSE THAT SPANS
   'TWO OR MORE LINES MUST BEGIN ON ITS OWN LINE'
                                       PIC X(80).

Example 3: Data Structure Editor format

-LINE- ------- Data Structure Editor ---------
000001  WRK1-FIELD-5 x(18) V'18 CHARACTERS LONG'
000002  WRK1-FIELD-6 x(13)
000003  ... V'13 CHARS LONG'

Example 4: Generated COBOL code

01  WRK1-FIELD-5 PIC X(18)
                 VALUE '18 CHARACTERS LONG'.
01  WRK1-FIELD-6 VALUE '13 CHARS LONG'
                 PIC X(13).a
Parent topic: Data Structures
Related reference
66 ...RENAMES
88
OCCURS
REDEFINES
Edit Mask Characters
Picture Formats


Edit Mask Characters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Code the following COBOL edit mask characters in your data structures:

  • A
  • P
  • Z
  • +
  • -
  • *
  • B
  • $
  • 0

The following table shows an example of each:

AMB Code

Generated Code

A(12)000B
PIC A(12)000B.

PPP999

PIC PPP999.

ZZZ9.99

PIC ZZZ9.99

+999.99

PIC +999.99.

****.**

PIC ****.**.

S999PPP

PIC S999PPP.
Parent topic: Data Structures
Related reference
66 ...RENAMES
88
OCCURS
REDEFINES
VALUE
Picture Formats


Picture Formats

Code data structures in the Data Structure Editor format, which is a shorthand syntax.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Format

Generated COBOL

9

PIC 9.

99

PIC 99

999

PIC 999

9999

PIC 9999

9(n)

PIC 9(n)

9n

PIC 9(n)

9&variable

PIC 9(&variable)

A

PIC A.

AA

PIC AA.

AAA

PIC AAA.

A(n)

PIC A(n).

An

PIC A(n).

A&variable

PIC A(&variable).

C

PIC S9 COMP.

C(n)

PIC S9(n) COMP.

Cn

PIC S9(n) COMP.

C-3

PIC S9 COMP-3.

Cn-3

PIC S9(n) COMP-3.

C&variable

PIC S9(&variable) COMP.

C&variable+-3

PIC S9(&variable) COMP-3.

F|FULL

PIC S9(9) COMP.

H|HALF

PIC S9(4) COMP.

I|INDEX

INDEX.  (For [USAGE IS] INDEX)

N

PIC 9.

N(n)

PIC 9(n).

Nn

PIC 9(n).

N&variable

PIC 9(&variable).

P|POINTER

POINTER.

(For COBOL/2 only:  [USAGE IS] POINTER.)

R|REDEF|
REDEFINES

REDEFINES dataname.

S

PIC S9.

S(n)

PIC S9(n).

Sn

PIC S9(n).

S&variable

PIC S9(&variable).

SYNC

SYNCHRONIZED

V(n)

PIC V9(n).

Vn

PIC V9(n).

V&variable

PIC V9(&variable).

Vvalueclause

VALUE valueclause.

X

PIC X.

XX

PIC XX.

XXX

PIC XXX.

XXXX

PIC XXXX.

Xn

PIC X(n).

X(n)

PIC X(n).

X&variable

PIC X(&variable).

...

Continuation of a format

General Rules:

  1. Application generation treats most format specifications beginning with COBOL edit mask characters as a valid COBOL formats, and passes them directly to the generated program. However, AMB translates an A, followed by a numeral, as follows.

    A8  generates  PIC A(8).

    2.

  2. Enter only the level 66, 77, or 88 numbers; do not enter other level numbers, such as 01, 05.

    3.

  3. Enter one data element name per line only. A data element name can be a valid COBOL name of 1 - 30 characters, or expression introduced by one of the Customizer default symbols.

    4.

  4. You do not need to code the word PICTURE in a picture clause. A PICTURE clause format can be a valid COBOL format or a AMB Data Structure Editor shorthand picture format.

    5.

  5. If you do code the PICTURE or PIC, use only valid COBOL syntax within the PIC clause - do not use the AMB shorthand picture format.

    6.

  6. You can continue the data structure on multiple lines wherever a space occurs, for example:

    WORK1-FIELD1      X(13)
... V'13 CHARS LONG'
WORK1-FIELD2      X(120)
... VALUE 'A LONG LITERAL MAY
...  BE CONTINUED ON ONE OR
...  MORE LINES'

    7.

  7. AMB treats the Data Structure Editor formats 99, A9,N9,S9, and V9 as valid COBOL formats and passes them directly to the generated program (as PIC 99, PIC A9, and so on). If, however, you want the generated COBOL to be PIC 9(9), PIC V(9), and PIC A(9), use the Data Structure Editor formats 9(9), V(9), and A(9).

    8.

  8. If a format includes an Customizer variable followed by additional format syntax, use a plus sign (+) to separate the Customizer variable from the additional syntax. During processing, AMB eliminates the plus sign and concatenates the suffix onto the syntax. For example:

    9&variable+V5 generates PIC 9(&variable)V9(5).

    9.

  9. Distinguish Vvalueclause from V as an implied decimal point.

    • For Vvalueclause, precede the V with a space and immediately follow it with the
                  valueclause.

      •

    • For V as an implied decimal point, use no space before or after the V. For example:

      N8V4 generates PIC 9(8) V9(4).
N8 V4 generates PIC 9(8) VALUE 4.

      •

    10.

  10. Never code comments within Data Structure Editor constructs.

    11.

Example:

The following illustrates using indentation to create level numbers:

Data Structure Editor code

000001        PROG-SPECIFIC-WORKING-DATA
000002          PGWS-FIELD1
000003              PGWS-FIELD2
000004                  PGWS-FIELD3
000005                      PGWS-FIELD4
000006                          PGWS-FIELD5
000007                              PGWS-FIELD6
000008                                  PGWS-FIELD7 X13

000009                                  ... V'ABCDEFGHIJKL'
000010                  PGWS-FIELD8
000011                      PGWS-FIELD9
000012                          PGWS-FIELD10  N13

Generated COBOL code

01  PROG-SPECIFIC-WORKING-DATA.
    05  PGWS-FIELD1.
        10  PGWS-FIELD2.
            15  PGWS-FIELD3.
                20  PGWS-FIELD4.
                    25  PGWS-FIELD5.
                        30  PGWS-FIELD6.
                            35  PGWS-FIELD7
                                PIC X(13)
                                VALUE 'ABCDEFGHIJKL'.
            15  PGWS-FIELD8.
                20  PGWS-FIELD9.
                    25  PGWS-FIELD10
                                PIC 9(13).

Parent topic: Data Structures

Related reference

66 ...RENAMES

88

OCCURS

REDEFINES

VALUE

Edit Mask Characters


Database Access Statements

Lists the AMB-specific statements you can use to access a database.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Database access statements let you configure how AMB accesses your database. Code the statements in the AMB file or files specified for each Help topic listed below.

  • CREATE SUBSCHEMA
  • DDI Statements
  • D2 Statements
  • CREATE SUBSCHEMA
  • DDI Statements
  • D2 Statements
  • SQL Functions
  • SQL Column Functions
  • SQL Scalar Functions
  • SQL Expressions
  • Example - Mixed Target
Parent topic: Reference


CREATE SUBSCHEMA

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Use the CREATE SUBSCHEMA statement to:

  • Provide a copybook name (other than the default) for a particular data view contained in the SQLDDL file.
  • Add a column or table prefix or suffix to enable reuse of a single table or column in multiple places in your working storage.
  • Specify a mixed SQL target.

Insert the CREATE SUBSCHEMA statement as the first entry in your SQLDDL file.

Syntax: for Format 1:

Use this format to provide a copybook name for a data view.

CREATE SUBSCHEMA subschemaname [(table/viewname1
[copylib 'copybookmembername'],[table/viewname2
[copylib 'copybookmembername'], ... );

Syntax: for Format 2:

Use this format to specify a column or table prefix or suffix.

CREATE SUBSCHEMA subschemaname [(table/viewname1
[TABLEPREFIX|TABLESUFFIX|COLUMNPREFIX|COLUMNSUFFIX
'string'],[table/viewname2
[TABLEPREFIX|TABLESUFFIX|COLUMNPREFIX|COLUMNSUFFIX
'string'], ... );

Syntax: for Format 3:

Use this format to specify tables and views of different targets.

CREATE SUBSCHEMA subschemaname (tablename1 TARGET
sqltarget, tablename2 TARGET sqltarget ...)

Parameters:

subschemaname | Must be identical to your SQLDDL file name.
table | The table name that contains the view you want to reference with a copybook name.
viewnameN | The name of the view you want to reference.
copybook | Overrides the default names generated for each table copybook named.
copybookmember-name | The copybook name you want to use to reference the view.
TABLEPREFIX|TABLESUFFIX|COLUMNPREFIX|COLUMNSUFFIX | Specify which prefix or suffix you want to provide, table or column.
string | The text string you want to use as the prefix or suffix.
tablenameN | The table for which you want to specify an alternate SQL target.
sqltarget | Specify an SQL target for the table.

Example:

CREATE SUBSCHEMA Latims (tsinvnt.tmobchctl copylib 'bchctl',
tsinvnt.tmsaccref copylib 'accref', tsinvnt.tmsagnref copylib
'agnref', tsinvnt.tmsasnmst copylib 'asnmst',
tsinvnt.tmsassref copylib 'assref', tsinvnt.tmsbdgzref copylib
'bdgref', tsinvnt.tmscltref copylib 'cltref',
tsinvnt.tmscltrul copylib 'cltrul', tsinvnt.tmscrsref copylib
'crsref', tsinvnt.tmsctlatv copylib 'ctlatv',
tsinvnt.tmsdspref copylib 'dspref');
Parent topic: Database Access Statements
Related concepts
Coding SQL Schema Sources
Related reference
Building Database Views


DDI Statements

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

DDI statements consist of the literal value *DDI, followed by a statement type and it's applicable arguments. The statement type identifies database or file records, fields, or indexes. You write these *DDI statements to a file in your DDISRC project subdirectory. Begin each statement in column 7 and code:

Column | Value
7-10 | *DDI
11 | Blank
12-14 | Statement type
15 | Blank
16-18 | Keyword parameter

The following topics each contain a list of DDI statement types:

  • IMS DB
  • VSAM
  • DDI statements - IMS DB
  • DDI statements - VSAM
Parent topic: Database Access Statements
Related reference
DDI statements - IMS DB
DDI statements - VSAM


DDI statements - IMS DB

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following three types of DDI statements specify your Program Specification Blocks (PSBs), Data Base Definitions (DBDs), and their COBOL record descriptions.

Description and Syntax:
Statement Type | Description and Syntax
*DDI DBD | *DDI DBD specifies the DBD statement in the database.
 *DDI DBD NAME=dbdname
*DDI REC | Specifies the SEGM statement/copybook
*DDI REC NAME=copybookrec|[new-COBOL-recordname],
*DDI     SEG=segname, [COPY=membername|[new-copybookname]],
*DDI     [GEN01=Y|N]
*DDI FLD | Specifies the FIELD and XDFLD statement/copybook field
*DDI FLD NAME=copybookfldname,
IMSNAME=fldname,*DDI     [PIC=copybookpic]
Parameters:
DDI Statement | Argument | Value | Len | Req | Default
*DDI DBD | NAME | dbname | 8 | yes | none
*DDI REC | NAME | copybookrec | 30 | yes | DBD value of SEGM NAME=
SEG | DBD value of SEG NAME= | 8 | yes | none
COPY | Membername | 8 | no | SEG NAME
GEN01 | Y or N | 1 | no | Y
*DDI FLD | NAME | copybookfieldname | 30 | yes | DBD value of FIELD NAME= or DBD value of XDFLD NAME=
IMSNAME | DBD value of FIELD NAME= or DBD value of XDFLD NAME= | 8 | yes | none
PIC | copybookpic | 24 | no | x(n), where n = the value of the BYTES keyword in the DBD
Comments:
  • Code your IMS DDI source file as follows:
    • Code a DDI DBD statement to correspond to the DBD statement in the database.
    • Code DDI REC statements for each segment you want to import that corresponds to the SEGM statement in the database and its copybook record. Specify the name of the copybook record that corresponds to the DBD segment identified on the DDI DBD statement using the NAME parameter. The name of the copybook member that contains the segment copybook record should be the same as the segment name. If it is not, specify the copybook member name with the COPY parameter.
    • Code a DDI FLD statement to correspond to the copybook record field. You must code a DDI FLD statement for each field statement in the DBD.
    • If the XDFLD has multiple SRCH fields, include SRCH fields. Code a DDI FLD statement. When there are multiple SRCH fields, AppMaster Builder defaults the name value to the XDFLD value. Code a dummy COBOL name that is different than any copybook field name of the SRCH fields in the NAME parameter to override the default. Alternatively, specify the DBD value of XDFLD using the IMSNAME parameter. Use the dummy name you specified on the DDI FLD statement in database commands to qualify on a secondary index composed of multiple SRCH fields.
    • If the XDFLD has one SRCH field, code DDI DBD and DDI REC statements only. It is not necessary to code a DDI FLD statement for the XDFLD because the Micro Focus Generator refers to the SRCH field definition.
  • To indicate the level number of the top level copybook records, set the &GEN-DB-REC-01 NAMES flag in the AMB CNTL file, APSDBDC as follows:
    • If the top level copybook records begin with 01, set the flag to 0 (default).
    • If the top level copybook record does not begin with 01, set the flag to 1 and assign a unique 01-level name using the NAME parameter.
    • Alternatively, use the GEN01 parameter on the DDI DBD statement to override the value of this flag. Specify GEN01=n to indicate that the top level copybook record level number begins with an 01 level number or specify GEN01=y to indicate that the top level numbers do not begin with 01.
  • When you load and build IMS DDI source into a data view, AppMaster Builder converts the following special characters in data names:
    Special Character Converts to
    $ X
    # Y
    @ Z
  • If the database contains secondary indexes, you can search on a secondary index field without having to generate DDISYMB for the index database.
  • If you write a database command against a PCB that uses a secondary index, use the proper COBOL name for the index field to be qualified upon. The Micro Focus Generator recognizes a secondary index by the presence of the PROCSEQ or INDICES parameters, and generates segment search arguments (SSA) naming the IMS XDFLD.
  • To access the index database itself, define the index DBD in DBD source, and include PCBs for it in PSBs you load and build into the data view.
  • If a PSB contains multiple PCBs for the database, use the VIEW or PCB parameter when you code the database rule to ensure that the correct PCB is used for the generated call.
  • To reference logical relationships in your data view, code a DDI DBD statement and a DDI REC statement. In the DDI REC statement, do not include information for segments in a logical DBD if the logical segment has a single physical source segment or the same IMS name as its physical source segment. The IMS Generator does not validate IMS logical Insert/Delete/Replace rules.
Example: DBD and Copybook DDI Statements

DBD statements:

DBD    NAME=DBD1,ACCESS=(HDAM,VSAM), ...
SEGM   NAME=S1,BYTES=100,PTR=T, ...
FIELD  NAME=S1FLD,START=1,BYTES=3,TYPE=N, ...
SEGM   NAME=S2,BYTES=80, ...
FIELD  NAME=S2FLD,START=1,BYTES=30,TYPE=C, ...

copybook record (S1):

01  SALES-REC.
    05  REGION-FLD          PIC 9(03).

          .

copybook record (S2):

01  CUST-REC.
    05  LOCATION-FLD        PIC X(30).
          .

DDI Statements:

*DDI DBD NAME=DBD1
*DDI REC NAME=SALES-REC,SEG=S1,COPY=S1,
*DDI     GEN01=Y
*DDI FLD NAME=REGION-FLD,IMSNAME=S1FLD,PIC=9(03)
*DDI REC NAME=CUST-REC,SEG=S2,COPY=S2,
*DDI     GEN01=Y
*DDI FLD NAME=LOCATION-FLD,IMSNAME=S2FLD,PIC=X(30)
Parent topic: DDI Statements
Related concepts
Coding DDI Sources
Related reference
Building Database Views


DDI statements - VSAM

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following four types of DDI statements specify your VSAM files, record indexes, and COBOL record descriptions.

Description and Syntax:
Statement Type | Description andSyntax
*DDI VSM | Specifies the VSAM file external ddname. Identifies VSAM file attributes.
*DDI VSM DDN=extddn, TYPE=K|E|R,
VSPREFIX=fileprefix,
         [CYL|TRK|REC(size)],
CISZ(cntlintrvalsize),
         VOL(volname), CAT=catname,
[idcamskeywrds]
*DDI REC | Specifies the copybook record name with the longest MAXLEN. Each copybook record must have a *DDI REC statement.
*DDI REC NAME=recname,
SHORT=shrtrecname, COPY=mbrname,
         SOURCE=P|C|, MAXLEN=maxreclen,
         AVGLEN=avgreclen
*DDI IDX | Required for keyed files. Specifies the keyed field name and copybook file name. Must immediately follow the *DDI REC statement. Write overlapping record keys as ordinary DDI IDX statements. AMB generates IDCAMS KEYS keywords according to the OFFSET and KEYLEN keywords on the DDI IDX statement.
*DDI IDX NAME=cpylibreckeyfldname,
[ALIAS=redefinefld],
         TYPE=P|U|D, KEYLEN=keyfldlen,
OFFSET=position,
         DDN=indxddname,
PIC=number,[idcamskeywrds]
*DDI SUB Specifies the copybook record name(s) used by AMB programs, record processing, batch options, and VSAM file external ddname. Defines a data view for the VSAM file.
Note: To define a data view with multiple VSAM files, assign DDI SUB statement parameters for each VSAM file.
*DDI SUB NAME=subschemaname,
RECORD=recname,
         PROCOPT=A|G|I|D|R,
[ACCESS=opt], [BLOCK=0],
         [LABEL=STANDARD],
[ASSIGN=extddname
Parameters:
DDI Statement | Argument | Value | Len | Req | Default
*DDI VSM | DDN | File external ddname | 8 | yes | none
TYPE | K(eyed)E(ntry)R(elative) | 1 | yes | K
VSPREFIX | File prefix | NA | yes | none
CYL,TRK or REC | Choose one | NA | yes | none
CISZ | ControlInterval Size | NA | yes | 4096
VOL | Volume name | NA | yes | none
CAT | Catalog name | NA | yes | none
Other IDCAMS keywords | IDCAMS syntax | NA | no | none
*DDI REC | NAME | Recname | 30 | yes | none
SHORT | Shrtrecname | 8 | yes
COPY | Membername | 8 | yes
SOURCE | Method used to put copybook members in program. P=via an %INCLUDE statement; C=via COBOL COPY command | 1 | yes | none
MAXLEN | Maximum record length | NA | yes | none
AVGLEN | Average record length | NA | yes | MAXLEN
*DDI IDX | NAME | copybook record key field name | 30 | yes | none
ALIAS | File that uses multiple copybook records. The name of the field that redefines NAME | 30 | no | none
TYPE | Index type--P(rimary) first index must be P; U(nique);D(uplicate) | 1 | yes | none
KEYLEN | Length of key field | 4 | yes | none
OFFSET | Offset position of the field relative to the beginning of the record. The first position is 0 | 4 | yes | none
DDN | Ddname of the index | 24 | yes | Primary=ddname
PIC | Ddname of the index | 24 | yes | alphanumeric
IDCAMS overrides | IDCAMS syntax | NA | no | none
*DDI SUB | NAME | Unique data view name | 8 | yes | none
RECORD | Value of the first (or only) DDI REC statement NAME keyword | 30 | yes | none
PROCOPT | Process control optionsA(ll)G(et)I(nsert)D(elete)R(eplace) | 1 | no | A
ACCESS or ACC | Batch access options | NA | no | dynamic for KSDS files; sequential for ESDS/RRDS
BLOCK | 0 | NA | no | 0
LABEL | STANDARD | NA | no | STANDARD
ASSIGN or AS | VSAM file external ddname | 8 | no | value of DDN parm in the DDI VSM statement
Comments:
  • Code a DDI VSM statement to correspond to the VSAM file external ddname. This statement identifies VSAM file attributes.
  • Code a DDI REC statement for each copybook record to correspond to the copybook record name and copybook filename with the longest MAXLEN.
  • If the top-level copybook records do not begin with 01, set the global flags &VS-GEN-01-USING-RECNAMES and GEN-DB-REC-01-NAMES in AMB CNTL files APVSAMIN and APSDBDC respectively to yes.
  • If the VSAM file is keyed, write a DDI IDX statement for each index that corresponds to keyed copybook field name and copybook file name. All DDI IDX statements must immediately follow the DDI REC statement. Write overlapping record keys as ordinary DDI IDX statements. AMB generates IDCAMS KEYS keyword according to the OFFSET and KEYLEN keywords on the DDI IDX statement
  • Code a DDI SUB statement to correspond to the copybook record name(s) and VSAM file external ddname. This statement defines a data view for the VSAM file.
  • To define a data view with multiple VSAM files, assign a RECORD keyword to each VSAM file you want to include.
  • For mixed target data views, the names of the SQL and VSAM or IMS data views must be identical. That is, the CREATE SUBSCHEMA name or SQLDDL\filename must be identical to either the VSAM DDI statement value DDI SUB=subschemaname or the IMS DDI statement value DDI DBD=dbdname.
Example: DDI for Fixed-length keyed sequential (KSDS) File
*DDI VSM DDN=EMPLOYEE
*DDI       TYPE=K,VSPREFIX=VQAC6550.APS17X,
*DDI       TRK(100 10),CISZ(8192),VOL(SAGE03),
*DDI       REPLICATE,FSPC(15 15),SHR(1 3),NOIMBED
*DDI REC NAME=EMPLOYEE-RECORD,SHORT=EMPL,
*DDI       COPY=EMPLOYEE,SOURCE=P,
*DDI       MAXLEN=56
*DDI IDX NAME=EMPL-EMP-NUM,TYPE=P,KEYLEN=6,OFFSET=0,
*DDI       DDN=EMPLOYEE,TRK(5 5),VOL(SAGE03)
*DDI IDX NAME=EMPL-SOURCE-CODE,TYPE=D,
*DDI       KEYLEN=6,OFFSET=30,DDN=EMPLOYE1,
*DDI       TRK(3 3),VOL(SAGE03),NOIMBED
*DDI IDX NAME=EMPL-SALARY,TYPE=D,
*DDI       KEYLEN=4,OFFSET=36,DDN=EMPLOYEZ,
*DDI       PIC=9(7)COMP-3,TRK(3 3),VOL(SAGE03)
*DDI SUB NAME=SAMPPGM,RECORD=EMPLOYEE-RECORD,PROCOPT=A,
*DDI       LABEL=STANDARD,BLOCK=200,ASSIGN=EMPLOYEE
Example: Copybook for a Variable-length KSDS file (with one index accessing multiple records)
% * CICS RECORDS ARE REDEFINED FOR WORKING-STORAGE.
% * Z/OS RECORDS NOT REDEFINED;ARE PLACED DIRECTLY UNDER FD.
% IF &APS-MDC = "CICS-TP"
    &VSSUF = "  REDEFINES ORDER-RECORD"
% ELSE
    &VSSUF = ""
01  ORDER-RECORD.
    05  ORDER-KEY                   PIC X(05).
    05  ORDER-RECORD-TYPE           PIC X(01).
    05  ORDER-CUST-NUMBER           PIC X(07).
    05  ORDER-PART-NUMBER           PIC X(07).
    05  ORDER-QUANTITY-ORDERED      PIC 9(05).
    05  ORDER-QUANTITY-TYPE         PIC X(10).
    05  ORDER-ORDER-AMOUNT          PIC 9(05)V99.
    05  ORDER-ORDER-STATUS          PIC X(04).
01  ORDER-PART-RECORD &VSSUF.
    05  FILLER                      PIC X(06).
    05  PART-NAME                   PIC X(05).
    05  PART-DESCRIPTION            PIC X(25).
    05  PART-SUPPLIER-NBR           PIC X(07).
    05  PART-SUPPLIER-NAME          PIC X(25).
01  ORDER-DELV-RECORD &VSSUF.
    05  FILLER                      PIC X(06).
    05  DELV-CONTACT-NAME           PIC X(30).
    05  DELV-CONTACT-PHONE          PIC X(12).
    05  DELV-ADDRESS                PIC X(35).
    05  DELV-SPECIAL-INSTRUCTIONS   PIC X(50).
Example: DDI for Variable-Length KSDS Files
*DDI VSM DDN=ORDER
*DDI REC NAME=ORDER-RECORD,SHORT=ORDER,COPY=ORDER,SOURCE=P,
*DDI     MAXLEN=133,AVGLEN=46
*DDI IDX NAME=ORDER-KEY,TYPE=P,KEYLEN=5,OFFSET=0,DDN=ORDER
*DDI REC NAME=ORDER-PART-RECORD,SHORT=PART,MAXLEN=68
*DDI REC NAME=ORDER-DELV-RECORD,SHORT=DELV,MAXLEN=133
*DDI SUB NAME=ORDERSS,
*DDI     RECORD=ORDER-RECORD,PROCOPT=A,
*DDI     LABEL=STANDARD,BLOCK=0,ASSIGN=ORDER
Example: DDI Statements for Generating DDISYMB
*DDI VSM DDN=PERSON
*DDI     TYPE=K,VSPREFIX=VAPS6550,
*DDI     CISZ(4096),VOL(PDVL02),TRK(5 5)
*DDI REC NAME=PERSONNEL-RECORD,SHORT=PERSONEL,
*DDI     COPY=PERSONEL,SOURCE=P,MAXLEN=80,PREFIX=PER
*DDI IDX NAME=SSA,ALIAS=SSA-X,TYPE=P,KEYLEN=9,
*DDI     OFFSET=0,DDN=PERSON,
*DDI     TRK(5,5),VOL(PDVL02)
*DDI IDX NAME=LAST-NAME,TYPE=D,KEYLEN=15,
*DDI     OFFSET=9,DDN=PERSON1,
*DDI     TRK(5,5),REUSE,VOL(PDVL02)
*DDI IDX NAME=TITLE,TYPE=D,KEYLEN=15,
*DDI     OFFSET=24,DDN=PERSON2,
*DDI     TRK(5,5),REUSE,VOL(PDVL02)
*DDI SUB NAME=SAMPLE,RECORD=PERSONNEL-RECORD,
*DDI     PROCOPT=A
Example: DDI for Data Views Containing Multiple VSAM Files
*DDI VSM DDN=DMOPART
*DDI     TYPE=K,VSPREFIX=CTSAPS.DEMO,TRK(10 10),VOL(WIN004),
*DDI     CISZ(4096)
*DDI REC NAME=PART-MASTER-REC,SHORT=DMOPART,COPY=DMOPART
*DDI     SOURCE=P,MAXLEN=80
*DDI IDX NAME=PM-PART-NO,TYPE=P,KEYLEN=8,OFFSET=0,
         DDN=DMOPART,TRK(1,1)
*DDI VSM DDN=DMOSTCK
*DDI     TYPE=K,VSPREFIX=CTSAPS.DEMO,TRK(10 10),VOL(WIN004),
*DDI     CISZ(4096)
*DDI REC NAME=PART-STOCK-REC,SHORT=DMOSTCK,COPY=DMOSTCK
*DDI     SOURCE=P,MAXLEN=80
*DDI IDX NAME=PS-STOCK-KEY,TYPE=P,KEYLEN=20,OFFSET=0,
*DDI     DDN=DMOSTCK,TRK(1,1)
*DDI IDX NAME=PS-PART-NO,TYPE=D,KEYLEN=8,OFFSET=0,
*DDI     DDN=DMOSTCKX,TRK(1,1)
*DDI SUB NAME=DMVMNU,RECORD=PART-MASTER-REC,PROCOPT=G,
*DDI     ACC=DYNAMIC,AS=DMOPART
*DDI SUB NAME=DMVINQ,RECORD=PART-MASTER-REC,PROCOPT=A,
*DDI     ACC=DYNAMIC,AS=DMOPART
*DDI SUB NAME=DMVUPD,RECORD=PART-MASTER-REC,PROCOPT=A,
*DDI     ACC=DYNAMIC,AS=DMOPART
*DDI SUB NAME=DMVLST,RECORD=PART-STOCK-REC,PROCOPT=A,
*DDI     ACC=DYNAMIC,AS=DMOSTCK

*DDI      RECORD=PART-MASTER-REC,PROCOPT=A,ACC=DYNAMIC,
*DDI      AS=DMOPART
Parent topic: DDI Statements
Related concepts
Coding DDI Sources
Related reference
Building Database Views


D2 Statements

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

For SQL targets, you can use special D2 (data view) flags to suppress or modify DCLGEN copybook generation. After you generate your data view, insert these D2 statements into the generated DDISYMB file.

Syntax: for Flag 1, suppress inclusion of the AMB-generated DCLGEN copybook
&D2-INCLUDED-COPYLIB-copybookname = "YES"|"NO"
Syntax: for Flag 2, specify user override of AMB indicator structure generation
&D2-INCLUDED-IV-copybookname = "YES"|"NO"
Syntax: for Flag 3, specify indicator variable prefix override, overriding the AMB default prefix IND
&D2-copybookname-IV-PREFIX = "prefixvalue"
Syntax: for Flag 4, specify indicator structure, group-level, override name
&D2-copybookname-IV-01-NAME =
"indicatorvariablename"
Syntax: for Flag 5, specify host structure, group-level override name
&D2-copybookname-HOST-01-NAME = "01levelname"
Syntax: for Flag 6, generate a value for &D2-copybookname-HOST-01-NAME
&D2-GLOBAL-DCLGEN-NAME = "YES"|"NO"
Syntax: for Flag 7, override use and generation of the default IND-cursorname structure
&D2-USE-CURSOR-IND = "YES"|"NO"
General Rules: for Flag 1
  1. Include your own DB2 host variable copybook.
  2. Suppress inclusion of the corresponding AMB-generated DCLGEN copybook named by copybookname.
General Rules: for Flag 2
  1. Include your own indicator variable structure in the copybook or DB2 DDI symbols for that table.
  2. Suppress generation of the AMB host indicator variable structure for the table named by copybookname.
  3. You can override the host indicator variable structure generated by AMB with one of your own, but you still must conform to the format above. The AMB-generated host indicator variable structure has the format:
    01  IND-copybookname-REC
    05 IND-colname1
    05 IND-colname2

    You can specify one prefix for each host indicator variable structure. The prefix you create must be supplied to AMB via the variable &D2-copybookname-IV-prefix.

  4. You can override the 01-level name of the host indicator variable structure. If the 01-level name you choose is not in the AMB format shown above, supply it to AMB via the variable &D2-copybookname-IV-01-name. These two user flags are described below.
General Rules: for Flag 3
  1. Code it to substitute a value for the default prefix, IND, on all indicator variables for a table.
  2. Include this flag to supply your own indicator variable structure and if the variable names have a prefix other than IND.
  3. The prefix you enter can include up to 11 characters.
  4. Follow the naming convention of prefix-columname for indicator variable names, where prefix is either IND or a value you specify in the prefix override. For example, for a table represented by a copybook named TAB2, the entry:
    % &D2-TAB2-IV-PREFIX = "TAB2-IV"
    Yields the following indicator variable structure:
    01  TAB2-IV-TAB2-REC.
    05  TAB2-IV-colname1
    05  TAB2-IV-colname2
    05  TAB2-IV-colname3
          .
          .
          .
    05  TAB2-IV-colnameN
  5. If you do not supply this variable, the AMB uses the structure generated for each cursor:
    cursorname-IND-variable
    for cursor processing.
General Rules: for Flag 4
  1. Code it to create your own 01-level name for the indicator variable structure. Indicatorvariablename replaces the AMB-generated 01-level name. The default for the 01-level name is prefixcolumnamerec.
  2. Include this flag to supply an override indicator variable structure when the 01-level name does not conform to the AMB naming convention.
  3. The maximum length of indicatorvariablename is 30 characters.
  4. Indicator variable names must follow the naming convention of prefix-columname, in which prefix is either IND or a value you specify in &D2-copybookname-IV-PREFIX. For example, a table represented by a copybook named TAB2, the entry:
    % &D2-TAB2-IV-01-NAME = "TAB2-IND-VAR"

    yields the following indicator variable structure.

    01  TAB2-IND-VAR.
    05  IND-colname1
    05  IND-colname2
    05  IND-colname3
          .
          .
          .
    05  IND-colnameN
  5. If you do not supply this variable, the AMB uses the structure generated for each cursor:
    cursorname-IND-variable
    for cursor processing.
General Rules: for Flag 5
  1. Code this to change the default host structure after the DCLGEN process creates it. 01levelname replaces the AMB-generated 01-level name, copybooknamerec. AMB uses your host 01-level name when it qualifies host variables during SQL generation.
General Rules: for Flag 6
  1. Use this flag, rather than Flag 5, to generate a name for all your tables. In the AMB CNTL file APDB2IN, set the flag &D2-GLOBAL-DCLGEN-NAME to yes. AMB generates a value for &D2-copybookname-HOST-01-NAME, using the IBM DCLGEN convention of DCLtablename. Defining this flag in APDB2IN overrides manually-coded definitions in all applications.
General Rules: for Flag 7
  1. Use this flag to override the default indicator variable structure, IND-cursorname with the structure IND-tablerec. AMB generates the default indicator variable structure:
    01   TABLE-REC.
     05  COL1                PIC X(4).
     05  COL2                PIC X(8).
01   IND-TABLE-REC.
     05  IND-COL1            PIC S9(4) COMP.
01   IND-CURSOR1.
     05  IND-COL1            PIC S9(4) COMP.
          .
          .
          .
     DB-FETCH CURSOR CURSOR1
     IF OK-ON-REC
         IF IND-COL1 OF IND-CURSOR1 = +0
             MAP-COL1 = COL1 in TABLE-REC
  2. When you code YES for this flag, AMB generates the default indicator variable structure, as follows:
    01   TABLE-REC.
     05  COL1       PIC X(4).
     05  COL2       PIC X(8).
01   IND-TABLE-REC.
     05  IND-COL1   PIC S9(4) COMP.
01   IND-CURSOR1.
     05  IND-COL1   PIC S9(4) COMP.
          .
          .
          .
     DB-FETCH CURSOR CURSOR1
     IF OK-ON-REC
         IF IND-COL1 OF IND-CURSOR1 = +0
             MAP-COL1 = COL1 in TABLE-REC
  3. When you code NO for this flag to override the indicator variable structure, the IND-cursor1 field is not created. AMB generates this indicator variable structure:
    01   TABLE-REC.
     05  COL1       PIC X(4).
     05  COL2       PIC X(8).
01   IND-TABLE-REC.
     05  IND-COL1   PIC S9(4) COMP.
  4. Using the host indicator variable structure can simplify your code because the one indicator variable structure can be used repeatedly. In nested processes, however, the host indicator variables are overwritten by each successive nesting level.
Examples:
Substitute the prefix TAB2-IV for the default prefix IND for all indicator variables in a table represented by copybookname and for the 01-level name.
% &D2-copybookname-IV-PREFIX = "TAB2-IV"
Substitute a different 01-level name in the indicator variable structure generated by AMB.
% &D2-copybookname-IV-01-NAME = "USER-IND-VAR-
NAME"
Sample source code:
% &D2-D2MASTER-HOST-01-NAME = "XYZ-D2MASTER-STRUCT"
****************************************************
*  COBOL DECLARATION FOR TABLE D2MASTER
*  01-LEVEL NAME POST-PROCESSED
****************************************************
01  XYZ-D2MASTER-STRUCT.
  10  PM-PART-NO                      PIC X(8).
  10  PM-NEW-PART-NO                  PIC X(8).
  10  PM-OLD-PART-NO                  PIC X(8).
  10  PM-PART-SHORT-DESC              PIC X(13).
  10  PM-UNITS                        PIC 9(5).
  10  PM-UNIT-BASE-PRICE              PIC 9(5).
  10  PM-DIMENSIONS                   PIC X(8).
  10  PM-COLOR                        PIC X(8).
Generated SQL code using &D2-D2MASTER-HOST-01-NAME:
   EXEC SQL SELECT ...
   INTO XYZ-D2MASTER-STRUCT.PM-PART-NO,
        XYZ-D2MASTER-STRUCT.PM-NEW-PART-NO,
          .
          .
          .
        XYZ-D2MASTER-STRUCT.PM-COLOR,
   FROM ...
   WHERE ...
   END-EXEC
Generated SQL code without using &D2-D2MASTER-HOST-01-NAME:
   EXEC SQL SELECT ...
   INTO D2TAB-REC.PM-PART-NO,
        D2TAB-REC.PM-NEW-PART-NO,
          .
          .
          .
        D2TAB-REC.PM-COLOR,
   FROM ...
   WHERE ...
   END-EXEC
Parent topic: Database Access Statements
Related concepts
Customizing Data Views
Related reference
Building Database Views


SQL Functions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Code SQL built-in and scalar functions as keywords for the database access calls DB-DECLARE, DB-OBTAIN, and DB-PROCESS.

Target:

SQL

Syntax: for DB-DECLARE

DB-DECLARE cursorname [correlname1.]copylibname-REC
... function1[(](expression)[,expression[,Y][)]]
... function2[(](expression)[,expression[,Y][)]]
          .
          .
          .
... functionN[(](expression)[,expression[,Y][)]]
... WHERE ...

Syntax: for DB-OBTAIN

DB-OBTAIN REC [correlname1.]copylibname-REC
... function1[(](expression)[,expression[,Y][)]]
... function2[(](expression)[,expression[,Y][)]]
          .
          .
          .
... functionN[(](expression)[,expression[,Y][)]]
... WHERE ...

Syntax: for DB-PROCESS

DB-PROCESS REC [correlname1.]copylibname-REC
... [DB-PROCESS-ID name]
... function1[(](expression)[,expression[,Y][)]]
... function2[(](expression)[,expression[,Y][)]]
          .
          .
          .
... functionN[(](expression)[,expression[,Y][)]]
... WHERE ...

General Rules:

  1. If you code a column function, every column in the call must use column functions, unless you code GROUP BY.
  2. You can code functions in a WHERE clause. For example:
    DB-OBTAIN
.. REC PARTDESC-REC
.. WHERE
.. MAX (PD_LONG_DESC) = 3
  3. You can mix scalar functions with individual column selections in a call.
  4. If you apply a function against a single column, the result is returned to the host variable. To override the result, specify a result field in the call and either:
    • Create a field in Working-Storage with the same data type as its corresponding columns or expression result. For scalar functions, the data type is determined by the function used and its associated rules.
    • Enter Y after the result field in the column function to let AMB create the field.
  5. If you apply a function against multiple columns, a literal, or an expression for which there is no host-variable, declare a result field in Working-Storage. The result field name can be as large as 26 characters; use COBOL naming conventions.
  6. If the function can return a null value, it requires an associated indicator variable as follows:
    • When AMB creates the result field, it creates a null indicator variable with the name based in the result field, such as resultfield-IND.
    • If you create the indicator variable in Working-Storage, use the same naming convention so that AMB can correctly name each indicator variable in the resulting SQL.
    • Limit resultfield to 26 characters to allow room for -IND. Define resultfield-IND as PIC S9(4) COMP.; for SQL for DB2, PIC S9(4) COMP-5.
  7. If you do not specify a result field with the COUNT function, the AMB-created field APS-COUNT-ROWS returns the COUNT result.

Example: Select the minimum unit base price and count the number of colors it finds for a given part number; create the result fields and appropriate indicator variables in Working-Storage.

DB-DECLARE D2MAST-CURSOR D2TAB-REC
... MIN((PM_UNIT_BASE_PRICE),WS-PM-UNIT-BASE-PRICE,Y)
... COUNT((DISTINCT PM_COLOR),WS-PM-COLOR,Y)
... WHERE PM_PART_NO = :WS-PART-NO

Example: SQL code with MIN and MAX functions

DB-OBTAIN REC D2TAB-REC
... MAX((PM_UNIT_BASE_PRICE),WS-MAX-PRICE,Y)
... MIN((PM_UNIT_BASE_PRICE * PM_UNITS),WS-MIN-RESULT,Y)
... WHERE PM_PART_SHORT_DESC = 'WIDGET'

Generated code:

EXEC SQL SELECT
    MAX(PM_UNIT_BASE_PRICE)
    MIN(PM_UNIT_BASE_PRICE * PM_UNITS)
    into :WS-MAX-PRICE, :WS-MAX-PRICE-IND
    :WS-MIN-RESULT :WS-MIN-RESULT-IND
    FROM AUTHID.D2MASTER
    WHERE PM_PART_SHORT_DESC = 'WIDGET'
END-EXEC.

Example: SQL code with SUM and AVG functions

DB-OBTAIN REC D2TAB-REC
... SUM(PM_UNITS)
... AVG((PM_UNITS),WS-AVG-UNITS,Y)
... WHERE PM_PART_NO = '23432'

Generated code:

EXEC SQL select
    SUM(PM_UNITS)
    AVG(PM_UNITS)
    INTO :D2TAB-REC.PM-UNITS :IND-D2TAB-REC.IND-PM-UNITS,
    :WS-AVG-UNITS :WS-AVG-UNITS-IND
    FROM AUTHID.D2MASTER
    WHERE PM_PART_NO = '23432'
END-EXEC.

Example: SQL code with COUNT function

DB-OBTAIN REC D2MASTER-REC
... MAX((PM-UNITS),WS-MAX-PM-UNITS)
... COUNT((*),WS-PM-COUNT-FLD)
... AVG((PM-UNIT-BASE-PRICE),WS-AVG-PRICE)
... WHERE PM-PART-SHORT-DESC='WIDGET'
... AND PM-COLOR='RED'

Generated code:

EXEC SQL select
    MAX(PM-UNITS)
    MIN(PM-UNIT-BASE-PRICE)
    COUNT(*)
    AVG(PM-UNIT-BASE-PRICE)
    INTO WS-MAX-PM-UNITS WS-MAX-PM-UNITS-IND,
    WS-PM-COUNT-FLD,
    WS-AVG-PRICE WS-AVG-PRICE-IND
    FROM AUTHID.D2MASTER
    WHERE PM-PART-SHORT-DESC='WIDGET'
    AND PM-COLOR='RED'
END-EXEC.

Example: SQL code with DATE, TIME, and AVG scalar functions

DB-OBTAIN REC D2INVEN-REC
... IN_PART_NO
... DATE(IN_DATE_LAST_UPDTE)
... TIME((IN_TIME_LAST_UPDTE),WS-TIME-RETURN,Y)
... CHAR((IN_DATE_LAST_ORDER,ISO),WS-CHAR-RETURN)
... IN_QTY_ONHAND
... WHERE IN_PART_NO = '23432'

Generated code:

EXEC SQL SELECT
    IN_PART_NO
    DATE(IN_DATE_LAST_UPDTE)
    TIME(IN_TIME_LAST_UPDTE)
    CHAR(IN_DATE_LAST_ORDER,ISO)
    IN_QTY_ONHAND
    INTO :D2INVEN-REC.IN-PART-NO,
    :D2INVEN-REC.IN-DATE-LAST-UPDTE
    :IND-D2INVEN-REC.IN-DATE-LAST-UPDTE,
    :WS-TIME-RETURN :WS-TIME-RETURN-IND,
    :WS-CHAR-RETURN :WS-CHAR-RETURN-IND,
    :D2INVEN-REC.IN-QTY-ONHAND
    :IND-D2INVEN-REC.IN-QTY-ONHAND
    FROM AUTHID.D2INVTRY
    WHERE IN_PART_NO = '23432'
END-EXEC.
Note: In this last example, the field IN_DATE_LAST_UPDTE is of type DATE. Because the result field WS-TIME-RETURN is followed by Y and the TIME function can return a null value, AMB creates both a result field with a picture appropriate for a TIME data type and a WS-TIME-RETURN-IND indicator in Working-Storage. Because the result field WS-CHAR-RETURN is not followed by Y and the CHAR function can return a null value, you must create both the result field and the WS-CHAR-RETURN-IND indicator variable in Working-Storage.
Parent topic: Database Access Statements
Related reference
SQL Column Functions
SQL Scalar Functions
SQL Expressions


SQL Column Functions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following list includes the SQL Column functions supported in Online Express and for Customizer User Rules:

  • MAX
  • MIN
  • AVG
  • SUM
  • COUNT
  • STDDEV (Customizer Rules only)
  • VARIANCE, VAR (Customizer Rules only)
Parent topic: Database Access Statements
Related reference
SQL Scalar Functions
SQL Functions
Customizer/Micro Focus Generator (MFG)


SQL Scalar Functions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following table lists the SQL Scalar functions supported in AppMaster Builder's Online Express and Customizer rules:

  • ABS, ABSVAL
  • ACOS
  • ASIN
  • ATAN
  • ATANH
  • CEILING, CEIL
  • CHAR
  • COALESCE (Customizer rules only)
  • COS
  • COSH
  • DATE
  • DAY
  • DAYOFMONTH
  • DAYOFWEEK
  • DAYOFWEEK_ISO (Customizer rules only)
  • DAYOFYEAR
  • DAYS
  • DECIMAL
  • DEGREES
  • DIGITS
  • EXP
  • FLOAT
  • FLOOR
  • HEX
  • HOUR
  • INTEGER
  • JULIAN_DAY
  • LEFT
  • LENGTH
  • LOWER, LCASE
  • LOG, LN
  • LOG10
  • LTRIM
  • MICROSECOND
  • MIDNIGHT_SECONDS
  • MINUTE
  • MOD
  • MONTH
  • POWER
  • QUARTER
  • RAND
  • RADIANS
  • REAL
  • RIGHT
  • ROUND
  • RTRIM
  • SECOND
  • SIGN
  • SIN
  • SINH
  • SMALLINT (Customizer rules only)
  • SQRT
  • SUBSTR
  • SUBSTRING
  • TAN
  • TANH
  • TIME
  • TIMESTAMP
  • TRUNC
  • UPPER, UCASE
  • VALUE
  • VARGRAPHIC
  • WEEK
  • WEEK_ISO (Customizer rules only)
  • YEAR
Parent topic: Database Access Statements
Related reference
SQL Column Functions
SQL Functions
Customizer/Micro Focus Generator (MFG)


SQL Expressions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

SQL supports expressions for the DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls.

Target:

SQL

Sample Expressions:

Expression | Return INTO Host | Null Indicator
INTEGER (DOB) - INTEGER(PERF - 1) (WS-RET-INT) | WS-RET-INT | IND-DOB
CURRENT DATE - 1 DAY (WS-CURRDATE) | WS-CURRDATE | --------
RATE + (DED / 2.0) | RATE | IND-RATE
YTD + RATE + DED / 2 | YTD | IND-YTD
PERF / 2 | PERF | IND-PERF
INTEGER(YTD - DED) * INTEGER(RATE) (WS-INT-FLD) | WS-INT-FLD | INT-YTD
HIREDTE + YEAR(CURRENT DATE) YEARS | HIREDTE | IND-HIREDTE
SUM(YTD) / 2 | YTD | IND-YTD
AVG(DED - 1) / 5 (WS-AVG-DED) | WS-AVG-DED | IND-DED
SUM(RATE) + SUM(DED) (WS-RATE-DED) | WS-RATE-DED | IND-RATE

General Rule:

  1. If an INTO variable is not specified, the result returns to the host variable for the first column.

Example:

DB-OBTAIN REC TABLE1
... RATE + (DED / 2.0)
... PERF / 2
... INTEGER(DOB) - INTEGER(PERF - 1) (WS-RET-INT)
... WHERE PERF > 100
DB-OBTAIN REC RECORD1-RED
... RATE + YEAR_TO_DATE              (WS-CALC-RATE)
... MONTH(HIREDATE) - DAY(HIREDATE)  (WS-DATE-RETURN
... AVG(RATE - 1) / 4                (WS-AVG-RATE)
... YEAR((CURRENT DATE - HIREDTE),WS-CALC-DATE,Y)
... CHAR((HIREDTE - 28 DAYS,USA),WS-DATE-AREA,Y)
... WHERE RATE > 7
Parent topic: Database Access Statements
Related reference
SQL Functions


Example - Mixed Target

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

In this example, you create a mixed target database view by loading both VSAM source and SQL DDL source into the same database view.

Note: When creating your own data views, you can optionally load your SQL tables using an SQL schema instead of loading SQL DDL source directly.

From the AppMaster Builder Data View Manager, create a new VSAM source member named MIXEDSUB.

Enter the following code into your default editor. Start each *DDI statement in column 7. The line numbers shown here are for the purposes of annotating the code only so each line can be explained below. Do not put them into your code:

0010   *DDI VSM DDN=SAMPVSM1
0020   *DDI     TYPE=K,VSPREFIX=USER.CLASSX,TRK(10 10)
0030   *DDI     VOL(30E119),CSIZ(4096)
0040   *DDI REC NAME=SAMPLE-RECORD1,SHORT=SAMPVSM1
0050   *DDI     COPY=SAMPVSM1,SOURCE=P,MAXLEN=250
0060   *DDI IDX NAME=ISE-PRIMARY-KEY,TYPE=P,KEYLEN=40,
0070   *DDI     OFFSET=0,DDN=SAMPVSM1,TRK(1,1)
0080   *DDI IDX NAME=ISE-ALTERNATE1-KEY,TYPE=U,KEYLEN=45,
0090   *DDI     OFFSET=40,DDN=SAMPALT1,TRK(1,1)
0100   *DDI VSM DDN=SAMPVSM2
0110   *DDI     TYPE=K,VSPREFIX=USER.CLASSX,TRK(10 10)
0120   *DDI     VOL(30E119),CISZ(4096)
0130   *DDI REC NAME=SAMPLE-RECORD2,SHORT=SAMPVSM2
0140   *DDI     COPY=SAMPVSM2,SOURCE=P,MAXLEN=2500
0150   *DDI IDX NAME=MB-CCMS-600-COMPY-KEY,TYPE=P,KEYLEN=7,
0160   *DDI     OFFSET=0,DDN=SAMPVSM2,TRK(1,1)
0170   *DDI SUB NAME=MIXEDSUB
0180   *DDI       RECORD=SAMPLE-RECORD1,PROCOPT=A,
0190   *DDI       ACC=DYNAMIC
0200   *DDI AS=SAMPVSM1
0210   *DDI       RECORD=SAMPLE-RECORD2,PROCOPT=A
0220   *DDI       ACC=DYNAMIC
0230   *DDI AS=SAMPVSM2

Lines 0010 - 0030:

       *DDI VSM DDN=SAMPVSM1
       *DDI     TYPE=K,VSPREFIX=USER.CLASSX,TRK(10 10)
       *DDI     VOL(30E119),CSIZ(4096)

Use the VSM keyword to provide a DD name for a VSAM record.

Lines 0040 - 0050:

       *DDI REC NAME=SAMPLE-RECORD1,SHORT=SAMPVSM1
       *DDI     COPY=SAMPVSM1,SOURCE=P,MAXLEN=250

Use the REC keyword to define the VSAM record.

Lines 0060:

       *DDI IDX NAME=ISE-PRIMARY-KEY,TYPE=P,KEYLEN=40,
       *DDI     OFFSET=0,DDN=SAMPVSM1,TRK(1,1)
       *DDI IDX NAME=ISE-ALTERNATE1-KEY,TYPE=U,KEYLEN=45,
       *DDI     OFFSET=40,DDN=SAMPALT1,TRK(1,1)

Use the IDX keyword to define primary and alternate indexes.

Lines 0100 - 0160:

       *DDI VSM DDN=SAMPVSM2
       *DDI     TYPE=K,VSPREFIX=USER.CLASSX,TRK(10 10)
       *DDI     VOL(30E119),CISZ(4096)
       *DDI REC NAME=SAMPLE-RECORD2,SHORT=SAMPVSM2
       *DDI     COPY=SAMPVSM2,SOURCE=P,MAXLEN=2500
       *DDI IDX NAME=MB-CCMS-600-COMPY-KEY,TYPE=P,KEYLEN=7,
       *DDI     OFFSET=0,DDN=SAMPVSM2,TRK(1,1)

This code defines a second VSAM record.

Lines 0170 - 0230:

       *DDI SUB NAME=MIXEDSUB
       *DDI       RECORD=SAMPLE-RECORD1,PROCOPT=A,
       *DDI       ACC=DYNAMIC
       *DDI AS=SAMPVSM1
       *DDI       RECORD=SAMPLE-RECORD2,PROCOPT=A
       *DDI       ACC=DYNAMIC
       *DDI AS=SAMPVSM2

Use the SUB statement to specify the name of the database view that will contain the two identified records. In this case, the name of the database view is MIXEDSUB, and it identifies SAMPLE-RECORD1 and SAMPLE-RECORD2. The name specified for the SUB statement must match the name of the database view.

Save the code in your editor and then load the MIXEDSUB VSAM source file and build the MIXEDSUB database view.

You should see your new database view, MIXEDSUB appear in the AppMaster Builder Data View Manager tree structure.

When creating a mixed target database view that contains SQL records, the subschema name (specified in the CREATE SUBSCHEMA statement of your SQL DDL file) and the filename of your SQL DDL file must also match the name of the database view. This is the same name as is specified in the SUB statement of your VSAM DDISRC file.

Next, open the MIXEDSUB database view and create a new SQL DDL source member named MIXEDSUB.

Enter the following native SQL into your editor to define your tables. It does not matter what column you start in. Again, the line numbers are for annotation purposes only. Do not put them into your code:

0010 CREATE SUBSCHEMA MIXEDSUB
0020 (TB_CEDCO_BRK     COPYLIB 'TBXCEDCO',
0030 TB_GROUP_CODES    COPYLIB 'TBXGROUP',
0040 TB_INSTMT_DETLS   COPYLIB 'TBXINSTM');
0050
0060
0070 CREATE TABLE TB_CEDCO_BRK
0080    ( CEDCO_CODE         CHAR        (006)       NOT NULL,
0090      CEDCO_NAME         CHAR        (030)       NOT NULL WITH DEFAULT,
0100      ADDRESS_1          CHAR        (030)       NOT NULL WITH DEFAULT,
0110     ADDRESS_2          CHAR        (030)       NOT NULL WITH DEFAULT,
0120      ADDRESS_3          CHAR        (030)       NOT NULL WITH DEFAULT,
0130      ADDRESS_4          CHAR        (030)       NOT NULL WITH DEFAULT,
0140      GROUP_CODE         CHAR        (003)       NOT NULL WITH DEFAULT,
0150      UK_AUTHORITY       CHAR        (001)       NOT NULL WITH DEFAULT,
0160      SOLVENCY_IND       CHAR        (002)       NOT NULL WITH DEFAULT,
0170      SOLVENCY_UPD_DATE  DATE                   ,
0180      BRK_TERRITORY_CODE CHAR        (003)       NOT NULL WITH DEFAULT,
0190      UPDATE_DATE        DATE                    NOT NULL,
0200      UPDATE_TIME        TIME                    NOT NULL,
0210      TIME_STAMP         TIMESTAMP               NOT NULL WITH DEFAULT,
0220      PRIMARY KEY
0230        ( CEDCO_CODE
0240        )
0250    )
0260 IN UAPDB001.TSDE01;
0270
0280 CREATE TABLE TB_GROUP_CODES
0290    ( GROUP_CODE         CHAR        (003)       NOT NULL,
0300      GROUP_NAME         CHAR        (030)       NOT NULL WITH DEFAULT,
0310      UPDATE_DATE        DATE                    NOT NULL,
0320      UPDATE_TIME        TIME                    NOT NULL,
0330      TIME_STAMP         TIMESTAMP               NOT NULL WITH DEFAULT,
0340      PRIMARY KEY
0350        ( GROUP_CODE
0360        )
0370    )
0380 IN UAPDB001.TSSG01;
0390
0400 CREATE TABLE TB_INSTMT_DETLS
0410    ( COMPANY_CODE       CHAR        (002)       NOT NULL,
0420      CONTRACT_NUMBER    CHAR        (010)       NOT NULL,
0430      UW_YEAR            CHAR        (002)       NOT NULL,
0440      INSTAL_OCC_NO      SMALLINT                NOT NULL,
0450      PREMIUM_DUE_MTH    CHAR        (002)       NOT NULL WITH DEFAULT,
0460      PREMIUM_DUE_YEAR   CHAR        (002)       NOT NULL WITH DEFAULT,
0470      PREMIUM_DUE_PCT    DECIMAL (007,004)       NOT NULL WITH DEFAULT,
0480      TIME_STAMP         TIMESTAMP               NOT NULL WITH DEFAULT,
0490      PRIMARY KEY
0500        ( COMPANY_CODE,
0510          CONTRACT_NUMBER,
0520          UW_YEAR,
0530          INSTAL_OCC_NO
0540        )
0550    )
0560 IN UAPDB001.TSMA04;

Lines 0010 - 0040:

     CREATE SUBSCHEMA MIXEDSUB
     (TB_CEDCO_BRK     COPYLIB 'TBXCEDCO',
     TB_GROUP_CODES    COPYLIB 'TBXGROUP',
     TB_INSTMT_DETLS   COPYLIB 'TBXINSTM');

The CREATE SUBSCHEMA statement identifies the subschema name and defines the copybooks it uses.

Lines 0070 - 0560:

0070 CREATE TABLE TB_CEDCO_BRK
0080    ( CEDCO_CODE         CHAR        (006)       NOT NULL,
0090      CEDCO_NAME         CHAR        (030)       NOT NULL WITH DEFAULT,
0100      ADDRESS_1          CHAR        (030)       NOT NULL WITH DEFAULT,
0110     ADDRESS_2          CHAR        (030)       NOT NULL WITH DEFAULT,
0120      ADDRESS_3          CHAR        (030)       NOT NULL WITH DEFAULT,
0130      ADDRESS_4          CHAR        (030)       NOT NULL WITH DEFAULT,
0140      GROUP_CODE         CHAR        (003)       NOT NULL WITH DEFAULT,
0150      UK_AUTHORITY       CHAR        (001)       NOT NULL WITH DEFAULT,
0160      SOLVENCY_IND       CHAR        (002)       NOT NULL WITH DEFAULT,
0170      SOLVENCY_UPD_DATE  DATE                   ,
0180      BRK_TERRITORY_CODE CHAR        (003)       NOT NULL WITH DEFAULT,
0190      UPDATE_DATE        DATE                    NOT NULL,
0200      UPDATE_TIME        TIME                    NOT NULL,
0210      TIME_STAMP         TIMESTAMP               NOT NULL WITH DEFAULT,
0220      PRIMARY KEY
0230        ( CEDCO_CODE
0240        )
0250    )
0260 IN UAPDB001.TSDE01;
0270
0280 CREATE TABLE TB_GROUP_CODES
0290    ( GROUP_CODE         CHAR        (003)       NOT NULL,
0300      GROUP_NAME         CHAR        (030)       NOT NULL WITH DEFAULT,
0310      UPDATE_DATE        DATE                    NOT NULL,
0320      UPDATE_TIME        TIME                    NOT NULL,
0330      TIME_STAMP         TIMESTAMP               NOT NULL WITH DEFAULT,
0340      PRIMARY KEY
0350        ( GROUP_CODE
0360        )
0370    )
0380 IN UAPDB001.TSSG01;
0390
0400 CREATE TABLE TB_INSTMT_DETLS
0410    ( COMPANY_CODE       CHAR        (002)       NOT NULL,
0420      CONTRACT_NUMBER    CHAR        (010)       NOT NULL,
0430      UW_YEAR            CHAR        (002)       NOT NULL,
0440      INSTAL_OCC_NO      SMALLINT                NOT NULL,
0450      PREMIUM_DUE_MTH    CHAR        (002)       NOT NULL WITH DEFAULT,
0460      PREMIUM_DUE_YEAR   CHAR        (002)       NOT NULL WITH DEFAULT,
0470      PREMIUM_DUE_PCT    DECIMAL (007,004)       NOT NULL WITH DEFAULT,
0480      TIME_STAMP         TIMESTAMP               NOT NULL WITH DEFAULT,
0490      PRIMARY KEY
0500        ( COMPANY_CODE,
0510          CONTRACT_NUMBER,
0520          UW_YEAR,
0530          INSTAL_OCC_NO
0540        )
0550    )
0560 IN UAPDB001.TSMA04;

Save the code in your editor, then load your new MIXEDSUB source file into the MIXEDSUB database view and build it again.

From the AppMaster Builder Data View Manager, expand MIXEDSUB to see the VSAM and SQL members contained in the one database view.

Parent topic: Database Access Statements


Database Calls

AMB Database (DB) calls are predefined, easy-to-use statements with common syntax that allows transparent access to a variety of databases. The AMB DB calls let you focus on what needs to be accomplished, rather than the mechanics of the target environment. To address environment-specific requirements, you can extend these calls with arguments; no native coding is required. These calls facilitate both generic processing and specialized requests.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMB supports the following database calls and targets.

Database Call

Description

Targets

DB-CLOSE

Close a file or cursor set.

  • SQL
  • VSAM Batch

DB-COMMIT

Perform the COMMIT function.

  • IMS
  • SQL

DB-DECLARE

Declare a cursor set.

SQL

DB-ERASE

Delete a row or record.

  • IMS
  • SQL
  • VSAM Batch
  • VSAM Online

DB-FETCH

Obtain a row from a cursor set.

SQL

DB-FREE

Release file resources.

VSAM Online

DB-MODIFY

Update a row or record.

  • IMS
  • SQL
  • VSAM Batch
  • VSAM Online

DB-OBTAIN

Read a table or record.

  • IMS
  • SQL
  • VSAM Batch
  • VSAM Online

DB-OPEN

Open a cursor set or file.

  • SQL
  • VSAM Batch

DB-PROCESS

Read a table or file and loop on it.

  • IMS
  • SQL
  • VSAM Batch
  • VSAM Online

DB-ROLLBACK

Perform the ROLLBACK function.

  • IMS
  • SQL

DB-STORE

Add a record to the database or file.

  • IMS
  • SQL
  • VSAM Batch
  • VSAM Online

DB-SUBSCHEMA

Include a data view in your program.

  • IMS
  • SQL
Note: AMB Logical View DB calls can consist of a call name, keywords, and arguments. Observe the General Rules when you code a DB call.

General Rules:

  1. Code the call using COBOL indentation. Improperly indented calls may cause errors.
  2. Argument values can be:
    • Variables
    • 1- to 7-digit numbers
    • Literal strings delimited by single or double quotation marks
  3. An alternate value can be a literal, column name, or host-variable.
  4. A host-variable is any COBOL data item referenced in your AMB SQL code; can a be data item generated automatically by AMB to match a DB2 column name.
  5. An alternate host-variable is one you instruct AMB to use instead of the automatically generated one for a column.
  6. Precede host-variables and alternate host-variables with a colon. AMB generates a # symbol for the colon.
  7. Separate each call component with a space, unless indicated otherwise in the syntax.
  8. Never code comments within database calls.
  9. Continue a call on as many as 101 subsequent lines by coding an ellipsis followed by a space (... ). Break a call for continuation at any blank space, but do not break a parameter.
  • DB-CLOSE
    Close files, cursor sets, batch files, and data view areas.
  • DB-COMMIT
    Perform database COMMIT functions.
  • DB-DECLARE
    Designate a set of rows as a logical group, that is, a cursor set. The call declares:
  • DB-ERASE
    The purpose of DB-ERASE varies depending on the target.
  • DB-FETCH
    DB-FETCH sequentially retrieves rows from the cursor set defined by DB-DECLARE. When you define a cursor set with DB-DECLARE, SQL places the selected rows in a results table, or cursor set. DB-FETCH retrieves these rows. Each DB-FETCH returns the next row of the cursor set until the end of the results table is reached.
  • DB-FREE
    DB-FREE releases file resources and:
  • DB-MODIFY
    Modify a record.
  • DB-OBTAIN
    The purpose of DB-OBTAIN varies depending on the target.
  • DB-OPEN
    Open a record, cursor set, or file.
  • DB-PROCESS
    Combine record retrieval and looping functions into one call. DB-PROCESS provides a built-in loop structure to process records and rows. The loop structure can include blocks of user-supplied logic and AMB-generated control fields. User logic executes once for each successful iteration of DB-PROCESS, and can include:
  • DB-ROLLBACK
    Perform ROLLBACK functions.
  • DB-STORE
    The purpose of this call varies depending on the target.
  • DB-SUBSCHEMA
    Include the imported program subschema in your program. AMB does this for you when you specify your subschema in the Project Explorer after importing the subschema.
  • GSAM Calls
    Access GSAM databases.
  • GROUP BY HAVING
    Apply column functions to data elements that are collected into groups and define a hierarchy for these groups.
  • IMS command codes
  • Joining Tables
    Join rows or columns from more than one table in the same call using the DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls.
  • NULL Indicator Field
    Use a null indicator variable to indicate whether the associated host variable has been assigned a null value.
  • Special Registers
    Use selected SQL calls to reference and test special registers as column values. Special Registers include:
  • Subselect Clause
    Create subselect clause by embedding a complete DB-OBTAIN call within a WHERE clause.
  • UNION
    Unite a DB-DECLARE or DB-PROCESS call with one or more DB-OBTAIN calls via the UNION keyword, which collects similar columns from two or more tables into one new table. The DB-OBTAIN calls in a union can select rows from one or many tables; the union results in a single table containing the rows selected by each call.
Parent topic: Reference
Related reference
&CONCAT
Control (CNTL) Files
D2 Statements
DDI Statements
Fields, Flags, and Exit Points
Programming and Size Limitations
System Service Calls


DB-CLOSE

Close files, cursor sets, batch files, and data view areas.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • SQL
  • VSAM Batch

SQL

Close SQL cursor sets.

Syntax:
DB-CLOSE CUR[SOR] cursorname
General Rule:
  1. In SQL, a cursor set can be opened, processed, and closed multiple times in the same program; you must code DB-CLOSE before you invoke another DB-OPEN.
Parameters:

CUR[SOR] cursorname

Specify cursor. Cursorname must be previously named by DB-DECLARE or DB-PROCESS-ID.

VSAM Batch

Close VSAM batch files.

Syntax for Format 1:
DB-CLOSE FILE filename1 [ ... filenameN]
Syntax for Format 2:
DB-CLOSE FILE ALL
General Rule:
  1. DB-CLOSE is required for single-platform applications.
Parameters:

FILE filename

File(s) to process.

ALL

Specify all files and ready all areas defined in the subschema.

Parent topic: Database Calls


DB-COMMIT

Perform database COMMIT functions.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • IMS DB
  • SQL

IMS DB

Syntax:
DB-COMMIT
General Rules:
  1. We recommend using the DB-COMMIT and DB-ROLLBACK calls instead of $IM-CHKP and $IM-ROLB.

SQL

Syntax:
DB-COMMIT [HOLD]
Parameters:
HOLD

Do not release resources; do not close open cursors; preserve prepared SQL statements; release locks on specific rows acquired during the transaction.

Parent topic: Database Calls


DB-DECLARE

Designate a set of rows as a logical group, that is, a cursor set. The call declares:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • All rows and columns in a table
  • All columns, from specific rows, in a table
  • Specific columns in a table
  • Specific columns, from specific rows, in a table

Note the following when coding DB-DECLARE:

  • Declare a cursor before coding a DB-OPEN or DB-FETCH call.
  • Because a declared cursor name is referenced by all subsequent calls for that cursor, code UPDATE to specify which columns can be modified; otherwise columns cannot be modified in subsequent cursor processing.
  • When specifying columns for sorting, identify them either by name or position in the selection list; do not mix references.

Target:

SQL

Syntax: for Format 1

Unqualified, select all columns.

DB-DECLARE cursorname copylibname-REC
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [UPDATE|ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Syntax: for Format 2

Qualified, select all columns.

DB-DECLARE cursorname copylibname-REC
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
... [UPDATE|ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Syntax: for Format 3

Select specific columns.

DB-DECLARE cursorname copylibname-REC
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... column1 [(altvalue)] [... columnN [(altvalue)]]
... [WHERE column operator [[:]altvalue]|column
... [AND|OR correlname.]column operator
... [[:]altvalue]|column]
        .
        .
        .
... [AND|OR correlname.]column operator
... [[:]altvalue]|column]]
... [UPDATE|ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Syntax: for Format 4

Implicit Join selecting columns from two or more tables.

DB-DECLARE cursorname correlname.copylibname-REC
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [correlname.copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
        .
        .
        .
... [WHERE correlname.column oper
... [:]altvalue|correlname.column
... [AND|OR correlname.column oper
... [:]altval|correlname.column]
        .
        .
        .
... [AND|OR correlname.column oper
... [:]altvalue|correlname.col]]
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Syntax: for Format 5

Specify a UNION.

DB-DECLARE cursorname copylibname-REC
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
        .
        .
        .
... [AND|OR column operator [[:]altvalue|]column]]
... UNION [ALL]
DB-OBTAIN REC copylibname-REC
        .
        .
        .
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Syntax: for Format 6

Specify a Join using a join-operator.

DB-DECLARE cursorname correlname1.copylibname-REC
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [column1 [... columnN]]|[NONE]
           .
           .
           .
... [[INNER JOIN|RIGHT OUTER JOIN|LEFT OUTER JOIN|FULL OUTER JOIN]
... ON joincondition REC]
... correlnameN.copylibname-REC
... [column1 [... columnN]]|[NONE]
           .
           .
           .
... [WHERE correlname.column1 oper
... [:]value|correlname.column2
... [AND|OR correlname.column3 oper
... [:]value|correlname.column4
           .
           .
           .
... AND|OR correlname.columnN operator
... [:]value|correlnameN]]
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC]]]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING]

General Rules:

  1. Declare a cursor before coding a DB-OPEN or DB-FETCH call.
  2. Because a declared cursor name is referenced by all subsequent calls for that cursor, code UPDATE to specify which columns can be modified; otherwise columns cannot be modified in subsequent cursor processing.
  3. When specifying columns for sorting, identify them either by name or position in the selection list; do not mix references.
  4. When you code WITH HOLD, a commit operation commits all the changes in the current unit of work, but releases only locks that are not required to maintain the cursor. Afterwards, you must code an initial DB-FETCH before you can execute a positioned update or delete. After the initial DB-FETCH, the cursor is positioned on the row following the one it was positioned on before the commit operation.
  5. The WITH HOLD clause is ignored in CICS and IMS DC.
  6. When using ROWSET operations, set up host-variable array structures to receive multiple values for each column.

Parameters:

cursorname | Cursor name (maximum 12 characters) must be unique, and cannot be the same as the subschema copylib names.
copylibname-REC | Copybook library name of source data.
DISTINCT | Eliminate all but one row from each set of duplicate rows. Duplicate rows have identical selected columns from the results table. You can use one or more DISTINCT keywords on selects.
FETCH ONLY | Specify that the table is read-only and therefore the cursor cannot be referred to in positioned UPDATE and DELETE statements. Do not code in a call that contains an UPDATE clause.
READ ONLY | Equivalent to FETCH ONLY.
QUERYNO number | Specifies the number to be used for this SQL statement in EXPLAIN output and trace records.
WITH HOLD | Prevent the closing of a cursor as a consequence of a commit operation.
OPTIMIZE number | Specify estimated maximum number of rows that call will retrieve. If the call retrieves no more than number rows, performance could be improved. Specifying this keyword does not prevent all rows from being retrieved.
INNER JOIN ON joincondition | Combines each row of the left table with every row of the right table keeping only the rows where the join-condition is true. If no join operator is specified, INNER is implicit
RIGHT OUTER JOIN ON joincondition | Includes the rows from the right table that were missing from the inner join.
LEFT OUTER JOIN ON joincondition | Includes the rows from the left table that were missing from the inner join.
FULL OUTER JOIN ON joincondition | Includes rows from both tables that were missing from the inner join.
UPDATE | Modify columns during cursor processing. In cursor processing, you cannot modify a column unless you code UPDATE first. Do not code UPDATE with UNION, DISTINCT, GROUP BY, or if call specifies a join or selects column functions.
ORDER [ASC|DESC] [column1 ...columnN] | Sort the results table in ascending (default) or descending order, based on the values in the columns specified. Specify the column either by name or by relative position in the column selection list. Specify at least one column. Do not code with UPDATE.
WHERE column operator [:]altvalue | Column is the column on which to qualify the selection. Operator can be =, ^=, >, <, >=, <=, native SQL predicates (such as LIKE and BETWEEN). See also the information on Alternate values and Host variables in the General Rules section of the Help topic Database Calls. Column names cannot exceed 18 characters.
AND|OR column operator column|[:]altvalue | Altvalue can be a literal or data name. See also the information on Alternate values and Host variables in the General Rules section of the Help topic Database Calls.
UNION | See UNION.
FETCH FIRST numberofrows | Limits the number of rows that can be fetched.
WITH | Specifies the isolation level at which the statement is executed.
 | CS | Cursor stability
 | RS | Read stability
 | RR | Repeatable read
 | UR | Uncommited read - can only be specified if the result table is read-only.
SENSITIVE SCROLL CURSOR | Cursor is scrollable. Changes made to the base table after the result table is materialized are visible to the cursor.
 | DYNAMIC | The result table of the cursor when it is opened is dynamic, meaning the size of the result table and the order of rows might change when rows are inserted or deleted. This is the default.
 | STATIC | The size of the result table and the order of the rows do not change after the cursor is opened.
INSENSITIVE SCROLL CURSOR | Cursor is scrollable. Changes made to the base table after the result table is materialized are not visible to the cursor.
WITH ROWSET POSITIONING | Retrieve multiple rows of data from the result table as a rowset into host-variable arrays.

Examples:

Declare cursor set D2MAST-CURSOR; define to include all rows and columns in D2MASTER table; allow updating for PM_COLOR and PM_NEW_PART_NO columns.
DB-DECLARE D2MAST-CURSOR D2TAB-REC
... UPDATE PM_COLOR PM_NEW_PART_NO
Declare cursor set consisting of entire rows selected by evaluating two columns; if duplicate rows, select only one row where PM_PART_SHORT_DESC equals Working-Storage variable WS_PART_SHORT_DESC and PM_UNIT_BASE_PRICE is greater than 10 and less than 50.
DB-DECLARE D2MAST-CURSOR D2TAB-REC
... DISTINCT
... WHERE PM_PART_SHORT_DESC =
... :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE BETWEEN 10 AND 50
Declare cursor and define its set to include two columns; select only rows that meet selection criteria; for column PM_PART_NO, move data to default destination; for column PM_COLOR, move data to alternate host-variable WS-COLOR.
DB-DECLARE D2MAST-CURSOR D2TAB-REC
... PM_PART_NO
... PM_COLOR (WS-COLOR)
... WHERE PM_PART_SHORT_DESC =
... :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE BETWEEN 10 AND 50
Declare cursor and define its set to include two columns; select only one row that meets selection criteria. Sort columns by position within selection list; sort cursor first by PM_COLOR (second column in selection list), then within PM_COLOR by PM_PART_NO (first column).
DB-DECLARE D2MAST-CURSOR D2TAB-REC
... DISTINCT
... PM_PART_NO PM_COLOR
... WHERE PM_PART_SHORT_DESC =
... :WS-PART-SHORT-DESC
... ORDER 2, 1

Declare a cursor set to include three columns drawn from two separate select statements, UNIONed together. Select two columns from D2TAB-REC and one column from D2INVEN-REC in the first UNION. Base selection criteria on PM_PART_NO matching IN_PART_NO, with PM_COLOR equal to the Working-Storage field WS-COLOR and IN-COLOR equal to 'BLUE'.

Select three columns from D2TAB-REC in the second UNION. Base selection criteria on PM_COLOR not equal to 'BLUE' and PM_UNITS less than 50. Sort the result table (consisting of rows returned from both select statements) by PM_PART_NO within PM_COLOR.
DB-DECLARE JOIN-CUR A.D2TAB-REC
... DISTINCT
... PM_PART_NO PM_COLOR
... B.D2INVEN_REC IN_QTY_ONHAND
... WHERE A.PM_PART_NO = B.IN_PART_NO
... AND A.PM_COLOR = :WS-COLOR
... AND B.IN_COLOR = 'BLUE'
... UNION
DB-OBTAIN REC D2TAB-REC
... PM_PART_NO PM_COLOR PM_UNITS
... WHERE PM_COLOR ^= 'BLUE'
... AND PM_UNITS < 50
... ORDER 1 ASC, 2 ASC
This example shows use of a sensitive cursor:
DB-DECLARE ORDERSCROLL
... ACCTMAST-REC
... SENSITIVE DYNAMIC SCROLL CURSOR
... WHERE ACCOUNT_NUMBER > 1000
... UPDATE CUSTOMER_NUMBER

DB-OPEN CURSOR ORDERSCROLL

DB-FETCH CURSOR ORDERSCROLL
... SENSITIVE RELATIVE +3

DB-CLOSE CURSOR ORDERSCROLL
This example shows ROWSET positioning:
DB-DECLARE C1
... A.ACCTMAST-REC
... WITH ROWSET POSITIONING

DB-OPEN CURSOR C1

DB-FETCH CURSOR C1
... NEXT ROWSET
... FOR 9 ROWS
... INTO ACCTMAST-REC

DB-CLOSE CURSOR C1
Parent topic: Database Calls
Related reference
UNION
Database Calls


DB-ERASE

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • IMS DB
  • SQL
  • VSAM Batch
  • VSAM Online

IMS DB

DB-ERASE deletes a record and all its dependent segments.

Syntax: for Format 1
DB-ERASE REC segment [FROM dataarea]
... [VIEW pcbname|PCB pcbname]
Syntax: for Format 2, records obtained by path calls
DB-ERASE REC|REF segment1 [FROM dataarea]
... [VIEW pcbname|PCB pcbname]
... REC|REF segment2 [FROM dataarea]
... [VIEW pcbname|PCB pcbname]
        .
        .
        .
... REC segmentN [FROM dataarea]
... [VIEW pcbname|PCB pcbname]
Syntax Rules: for Formats 1 and 2
  1. DB-ERASE assumes record retrieval from the default I/O area. If this is not true, you must code FROM dataarea.
  2. When a record is obtained from a PCB other than the default PCB, such as by DB-OBTAIN with VIEW or PCB, you must code VIEW pcbname.
Syntax Rules: for Format 2
  1. Use REF only when DB-ERASE is preceeded by a DB-OBTAIN path call, meaning more than one record was obtained by the call and placed into the I/O area.
  2. Use REF with DB-ERASE to specify higher-level segments that you do not want to delete.
General Rules: for Formats 1 and 2
  1. Specify every segment down to the first segment being deleted for records obtained by path calls. That is, every record named in a DB-OBTAIN preceding a DB-ERASE must also be named in the DB-ERASE.
General Rules: for Format 2
  1. If a preceding DB-OBTAIN specifies the REF parameter, meaning that the record is referenced but not placed into the I/O area, DB-ERASE ignores the record.
Parameters:

REC|REF segment

Specify that the segment name (maximum 8 characters) is in a Working-Storage variable for the program to delete.

FROM dataarea

Alternate I/O area where program deletesa record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO.

PCB|VIEW pcbname

Specify PCB used when PSB contains multiple PCBs for the same database.

Examples:
Format 1
Delete only RECORD-B and RECORD-C. First, issue a DB-OBTAIN call.
 DB-OBTAIN REC RECORD-A WHERE KEY-A = VALUE-A
 ... REC RECORD-B WHERE KEY-B = VALUE-B
 ... REC RECORD-C WHERE KEY-C = VALUE-C HOLD
Then, name all segments accessed by the prior path call DB-OBTAIN. Because the children of a deleted segment are also deleted, there is no need to code beyond the highest level segment being deleted (RECORD-B).
DB-ERASE REF RECORD-A
... REC RECORD-B REC RECORD-C
Format 2
The following examples assume that the following DB-OBTAIN path call precedes the DB-ERASE:
$DB-OBTAIN ("REC SEG1, REC SEG2, REC SEG3")

To delete the entire path:

$DB-ERASE ("REC SEG1")
Note: Dependent segments are automatically deleted.

To delete SEG2 and its dependents:

$DB-ERASE ("REF SEG1, REC SEG2")

To delete just SEG3:

$DB-ERASE (REF SEG1, REF SEG2, REC SEG3")

The following example assumes that the following DB-OBTAIN call precedes the DB-ERASE. This DB-OBTAIN is not a path call and places only SEG3 into the I/O area; therefore, DB-ERASE ignores SEG1 and SEG2:

$DB-OBTAIN ("REF SEG1, REF SEG2, REC SEG3")

To delete SEG3:

$DB-ERASE ("REC SEG3")

The following examples assume that the following DB-OBTAIN path call precedes the DB-ERASE. This DB-OBTAIN places only SEG2 and SEG3 into the I/O area; therefore, DB-ERASE ignores SEG1:

$DB-OBTAIN ("REF SEG1, REC SEG2, REC SEG3")

To delete only SEG3:

$DB-ERASE ("REF SEG2, REC SEG3")

To delete SEG2 and SEG3, which is a dependent of SEG2:

$DB-ERASE ("REC SEG2")

SQL

DB-ERASE deletes:
  • All rows in a table
  • Specific row in a table
  • Cursor set rows
Syntax: for Format 1
DB-ERASE REC copylibname-REC
... [WHERE column operator [:]altvalue
... [AND|OR column operator [:]altvalue
        .
        .
        .
... AND|OR column operator [:]altvalue]]
... [QUERYNO number]
... [WITH [CS|RS|RR]]
Syntax: for Format 2
DB-ERASE REC copylibname-REC
... [WHERE CURRENT [OF] cursorname]
... [QUERYNO number]
... [WITH [CS|RS|RR]]
Parameters:

AND|OR column operator [:]altvalue

Altvalue can be a literal or data name.

REC copylib-REC

Specify the 01-level name of the COBOL row layout in the DCLGEN or copybook information. Cannot be the same as any cursor names or DB-PROCESS-ID names.

WHERE CURRENT [OF] cursorname

Valid for cursor processing only. Act upon the row retrieved from cursor.

QUERYNO number

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records.

WITH

Specifies the isolation level at which the statement is executed.

CS

Cursor stability

RS

Read stability

RR

Repeatable read

Example:
Delete any row in table D2MASTER where PM_PART_NO equals 123 or 567.
DB-ERASE REC D2TAB-REC
... WHERE PM_PART_NO = '123' OR PM_PART_NO = '567'

VSAM Batch

DB-ERASE deletes a record:
  • Specified by key qualification via DB-OBTAIN (key qualified)
  • Retrieved by DB-OBTAIN or DB-PROCESS (unqualified)
Syntax: for Format 1, key-qualified
DB-ERASE REC recordname
 ... WHERE primarykey = value
 ... [SUB value] [OF|IN dataarea]
Syntax: for Format 2, unqualified
DB-ERASE REC recordname
Parameters:

WHERE primarykey = value

Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or an integer.

OF|IN dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field.

Example:

Delete a record where ORDR-NUMBER equals the value in the Working-Storage variable CUST-ORDR-NUMBER.

DB-ERASE REC ORDR-RECORD
 ... WHERE ORDR-NUMBER = CUST-ORDR-NUMBER

Read a CUST-RECORD for deletion.

DB-OBTAIN REC CUST-RECORD
... WHERE CUST-KEY = SCREEN-CUST-KEY
IF OK-ON-REC
    DB-ERASE REC CUST-RECORD

VSAM Online

DB-ERASE deletes a record:
  • Specified by key qualification via DB-OBTAIN (key qualified).
  • Retrieved by DB-OBTAIN or DB-PROCESS (unqualified).
Syntax: for Format 1, key-qualified
DB-ERASE REC recordname
... WHERE primarykeyname = value
... [SUB[SCRIPT] value] [OF|IN dataarea]
... [KEYLENGTH|KLEN value]
... [SYSID systemname] [DDN ddname]
Syntax: for Format 2, unqualified
DB-ERASE REC recordname
Parameters:

WHERE pri-marykey = value

Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or, under VSAM Batch or Online, an integer.

OF|IN dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field.

KEYLENGTH| KLEN value

Specify number or characters in key length; full or partial length is valid. Value can be a number or a data name defined as PIC S9(4) COMP. AMB generates the CICS GENERIC option for a partial key length.

SYSID systemname

Process records stored on remote systems. Name a file residing in a remote data set. Systemname can be a 4-character literal region name or a Working-Storage field containing a 4-character region name.

DDN ddname

File data description name; supply a value to the name option of CICS DATASET option. Ddname can be a literal or data name defined as PIC X(8).

Examples:

Delete a group of ORDR-RECORD records; use partial key length. For successful deletes, store the number of actual records in the AMB data field APS-VSAM-NUMREC.

DB-ERASE REC ORDR-RECORD
... WHERE ORDR-NUMBER = SCREEN-PARTIAL-ORDR-NUMBER KLEN 6
IF  OK-ON-REC
    SCREEN-MSG = 'ORDER RECORDS DELETED, NUMBER ORDERS = '
    SCREEN-NBR-RECS = APS-VSAM-NUMREC

Hold a CUST-RECORD for deletion.

DB-OBTAIN REC CUST-RECORD
... WHERE CUST-KEY = SCREEN-CUST-KEY HOLD
IF OK-ON-REC
    DB-ERASE REC CUST-RECORD
Parent topic: Database Calls


DB-FETCH

DB-FETCH sequentially retrieves rows from the cursor set defined by DB-DECLARE. When you define a cursor set with DB-DECLARE, SQL places the selected rows in a results table, or cursor set. DB-FETCH retrieves these rows. Each DB-FETCH returns the next row of the cursor set until the end of the results table is reached.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

SQL

Syntax:

DB-FETCH CUR[SOR] cursorname
... [SENSITIVE|INSENSITIVE]
... [ABSOLUTE number|RELATIVE number|CURRENT|FIRST|LAST|NEXT|PREVIOUS|PRIOR]
... [NEXT ROWSET | FIRST ROWSET  | PRIOR ROWSET |
... CURRENT ROWSET | LAST ROWSET |
... ROWSET STARTING AT {ABSOLUTE number | RELATIVE number}]
... [FOR number ROWS]
... [INTO dataname]

General Rules:

  1. The row returned by the current iteration of DB-FETCH is the current row.
  2. You can code DB-FETCH within an S-COBOL loop to retrieve multiple rows from a cursor set.
  3. To FETCH into individual columns, specify those alternate host variables in DB-DECLARE.
  4. When using ROWSET operations, set up host-variable array structures to receive multiple values for each column.
  5. AMB creates default array structures for records that specify multiple-row fetches or entire-row, multiple-row inserts. The array size is the maximum row number value found specified in the FOR number ROWS clause for that table. For example:
    01   recordname-ARR.
     05  CobolHostVar1-ARR     picture occurs row-number times.
     05  IND-CobolHostVar1-ARR picture occurs row-number times.
     05  CobolHostVar2-ARR     picture occurs row-number times.
     05  IND-CobolHostVar2-ARR picture occurs row-number times.
     …..
     05  CobolHostVarn-ARR     picture occurs row-number times.
     05  IND-CobolHostVarn-ARR picture occurs row-number times.

Parameters:

CUR[SOR] cursorname

Specify cursor. Cursorname must be previously named by DB-DECLARE or DB-PROCESS-ID.

  • ABSOLUTE number
  • RELATIVE number
  • CURRENT
  • FIRST
  • LAST
  • NEXT
  • PREVIOUS
  • PRIOR

Cursor positioning keywords. NEXT is the default.

INTO dataname

Move host variable structure into the alternate data structure data name. Data moves after the actual SQL call via a MOVE statement. Generated code isIF OK-ON-RECMOVE hostname TO dataname

SENSITIVE

Reflects changes made outside of this cursor.

INSENSITIVE

Returns rows from the result table as is.

  • NEXT ROWSET
  • FIRST ROWSET
  • PRIOR ROWSET
  • CURRENT ROWSET
  • LAST ROWSET
  • ROWSET STARTING AT
  • ABSOLUTE number
  • RELATIVE number

Rowset positioning keywords. NEXT ROWSET is the default.

FOR number ROWS

Controls how many rows are returned on each FETCH.

Example:

Retrieve columns and rows in cursor set D2MAST-CURSOR; place information into WS-D2MAST-RECORD in Working-Storage.
DB-FETCH CURSOR D2MAST-CURSOR
... INTO WS-D2MAST-RECORD
Parent topic: Database Calls


DB-FREE

DB-FREE releases file resources and:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Ends a sequential DB-OBTAIN browse.
  • Unlocks a held record (a record held by a DB-OBTAIN HOLD) when DB-OBTAIN is not followed by DB-MODIFY or DB-ERASE.

Target:

VSAM Online

Syntax:

DB-FREE REC recordname|ALL
... [VIEW keyname]
... [ENDBR] [UNLOCK] [REQID number]
... [SYSID systemname] [DDN ddname]

Syntax Rules:

  1. UNLOCK and ENDBR are default keywords. De-activate either one by:
    • Coding only ENDBR makes UNLOCK inactive
    • Coding only UNLOCK makes ENDBR inactive
  2. When ALL is coded and UNLOCK and ENDBR are active, a single DB-FREE call (located in a central paragraph) works for the entire program.

Parameters:

ALL | Process all subschema records. When coded with SYSID, all files must reside on the same region.
DDN ddname | Specify file ddname; can be a literal or data name defined as PIC X(8). Supply a value to the name option of CICS DATASET.
ENDBR | End active browse; generate CICS ENDBR command.
REC recordname | COBOL record to process.
REQID number | Unique browse identifier for performing a simultaneous browse on the same key; is a single integer (0 - 9). Assign &VS-ENDBR-CONTROL = "USER" in the AMB CNTL file APVSAMIN.
SYSID systemname | Remote system name (maximum 4 characters); can be a literal region name or a Working-Storage field.
UNLOCK | Unlock file; generate CICS UNLOCK command.
VIEW keyname | Specify primary or alternate key.

Examples:

Release a record held by a direct DB-OBTAIN; deactivate ENDBR.
DB-OBTAIN REC ORDR-RECORD
... WHERE ORDR-NUMBER = SCREEN-ORDR-NUMBER
... HOLD
DB-FREE REC ORDR-RECORD
... UNLOCK
Terminate a sequential DB-OBTAIN; specify the key used; deactivate UNLOCK.
DB-OBTAIN REC CUST-RECORD
... VIEW CUST-NUMBER
DB-FREE REC CUST-RECORD
... VIEW CUST-NUMBER
... ENDBR
Parent topic: Database Calls


DB-MODIFY

Modify a record.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • IMS DB
  • SQL
  • VSAM Batch
  • VSAM Online

IMS DB

Syntax:
DB-MODIFY
... REC|REF recordname1 [FROM dataarea]
... [VIEW|PCB pcbname]
        .
        .
        .
... REC|REF recordnameN [FROM dataarea]
... [VIEW|PCB pcbname]
Syntax Rules:
  1. Use REF only when DB-MODIFY is preceeded by a DB-OBTAIN path call, meaning more than one record was obtained by the call and placed into the I/O area.
  2. Use REF with DB-MODIFY to specify higher-level segments that you do not want to modify.
General Rules:
  1. The record must be retrieved and held by a DB-OBTAIN or DB-PROCESS call before it can be modified.
  2. To modify records obtained by a path call DB-OBTAIN, specify every segment obtained in the path. To specify that a segment is not modified, code REF.
  3. If a preceding DB-OBTAIN specifies the REF parameter, meaning that the record is referenced but not placed into the I/O area, DB-MODIFY ignores the record.
  4. Use the CCODE keyword to include additional IMS command codes. See the topic IMS command codes for a list of valid CCODEs.
Parameters:

REC recordname

IMS segment to process.

REF recordname

Specify an IMS segment to reference. The program uses the referenced segment for navigating the database.

FROM dataarea

Alternate I/O area where program deletes, modifies, or adds a record. Code FROM when a record is obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO.

PCB pcbname

Specify the PCB used when the PSB contains multiple PCBs for the same database. Code PCB when a record is obtained from the default PCB.

VIEW pcbname

Specify the PCB used when the PSB contains multiple PCBs for the same database. Code VIEW when a record is not obtained from the default PCB.

Examples:
Modify only RECORD-C.
DB-OBTAIN REC RECORD-A WHERE KEY-A = VALUE-A
... REC RECORD-B WHERE KEY-B = VALUE-B
... REC RECORD-C WHERE KEY-C = VALUE-C HOLD
DB-MODIFY REF RECORD-A
... REF RECORD-B
... REC RECORD-C

The following examples assume that the following DB-OBTAIN path call precedes the DB-MODIFY.

$DB-OBTAIN ("REC SEG1, REC SEG2, REC SEG3")

To modify all records retrieved in the path:

$DB-MODIFY ("REC SEG1, REC SEG2, REC SEG3")

To modify just SEG2:

$DB-MODIFY ("REF SEG1, REC SEG2")

To modify just SEG3:

$DB-MODIFY ("REF SEG1, REF SEG2, REC SEG3")

The following example assumes that the following DB-OBTAIN call precedes the DB-MODIFY. This DB-OBTAIN is not a path call and places only SEG3 into the I/O area; therefore, DB-MODIFY ignores SEG1 and SEG2:

$DB-OBTAIN ("REF SEG1, REF SEG2, REC SEG3")

To modify SEG3 only:

$DB-MODIFY ("REC SEG3")

The following examples assume that the following DB-OBTAIN path call precedes the DB-MODIFY. This DB-OBTAIN places only SEG2 and SEG3 into the I/O area; therefore, DB-MODIFY ignores SEG1:

$DB-OBTAIN ("REF SEG1, REC SEG2, REC SEG3")

To modify SEG3 only:

$DB-MODIFY ("REF SEG2, REC SEG3")

To modify SEG2 only:

$DB-MODIFY ("REC SEG2")

SQL

DB-MODIFY updates row contents in a table or cursor set as follows:

  • All rows in a table
  • Specific rows in a table
  • Specific columns in a table
  • Specific columns of a specific row
  • Cursor set rows
Syntax:
DB-MODIFY REC copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [FROM dataname]
... [WHERE column1 operator [:]altvalue
        .
        .
        .
... AND|OR columnN operator [:]altvalue]
... [END[WHERE]]]
... [WHERE CURRENT [OF] cursorname]
... [QUERYNO number]
... [WITH [CS|RS|RR]]
Parameters:

REC copylib-REC

Specify the 01-level name of the COBOL row layout in the DCLGEN or copybook information. Cannot be the same as any cursor names or DB-PROCESS-ID names.

column1 [(altvalue)]

Altvalue can be a literal, column name, host variable, or one of the following expressions:

  • NEXT VALUE FOR sequencename
  • PREVIOUS VALUE FOR sequencename

If you name an alternate host variable for a specific column, do not code FROM, which names an entire alternate host structure.

See also the information on Host variables in the General Rules section of the Help topic Database Calls.

FROM dataname

Move alternate data structure to the host variable structure name. Data moves prior to the actual SQL call via MOVE statement.

WHERE column operator

Not valid for cursor processing. Column is the column on which to qualify the selection. Operator can be =, ^=, >, <, >=, <=, native SQL predicates (such as LIKE and BETWEEN).

[:]altvalue

Alternate value; when used with WHERE, AND , or OR, it can be a literal or a column name.

END[WHERE]

Terminate a WHERE clause. Required if you code WHERE before FROM.

WHERE CURRENT [OF] cursorname

Valid for cursor processing only. Act upon the row retrieved from cursorname.

QUERYNO number

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records.

WITH

Specifies the isolation level at which the statement is executed.

CS

Cursor stability

RS

Read stability

RR

Repeatable read

Example:
Update specific columns of specific rows using selection criteria and alternate data from different areas for each column.
DB-MODIFY REC D2TAB-REC
... PM_UNIT_BASE_PRICE (25.99)
... PM_UNITS (:WS-UNITS)
... WHERE PM_PART_SHORT_DESC = 'WIDGET'
... AND PM_COLOR = 'RED'
... AND PM_UNIT_BASE_PRICE < 50

VSAM Batch

Syntax:
DB-MODIFY REC recordname [FROM dataarea]
General Rule:
  1. Before modifying a record, retrieve it with a DB-OBTAIN or DB-PROCESS call.
Parameters:

REC recordname

COBOL record to process.

FROM dataarea

Alternate I/O area where program deletes, modifies, or adds a record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO

Example:

Hold CUST-RECORD for modification; specify an alternate storage area to contain the data that updates the record.

DB-OBTAIN REC CUST-RECORD
... WHERE CUST-NUMBER = SCREEN-CUST-NUMBER
IF  OK-ON-REC
    DB-MODIFY REC CUST-RECORD
    ... FROM CUST-RECORD-UPDATE-AREA

VSAM Online

Syntax:
DB-MODIFY REC recordname [FROM dataarea]
... [SYSID systemname] [DDN ddname]
General Rule:
  1. Before modifying a record, retrieve it with a DB-OBTAIN or DB-PROCESS call.
Parameters:

DDN ddname

Specify file ddname; can be a literal or data name defined as PIC X(8). Supply a value to the name option of CICS DATASET.

FROM dataarea

Alternate I/O area where program deletes, modifies, or adds a record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO

REC recordname

COBOL record or IMS segment to process.

SYSID systemname

Remote system name (maximum 4 characters); can be a literal region name or a Working-Storage field.

Example:
Hold CUST-RECORD for modification; specify an alternate storage area to contain the data that updates the record.
DB-OBTAIN REC CUST-RECORD
... WHERE CUST-NUMBER = SCREEN-CUST-NUMBER
... HOLD
IF  OK-ON-REC
    DB-MODIFY REC CUST-RECORD
    ... FROM CUST-RECORD-UPDATE-AREA
Parent topic: Database Calls
Related reference
IMS command codes
Database Calls


DB-OBTAIN

The purpose of DB-OBTAIN varies depending on the target.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • IMS DB
  • SQL
  • VSAM Batch
  • VSAM Online

IMS DB

DB-OBTAIN performs:
  • Qualified and unqualified record retrievals
  • Retrieval of records qualified on multiple fields (Boolean qualification)
  • Retrieval of records qualified on secondary indices composed of more than one field
  • Compound calls
  • Path calls
  • Hold segments for modification or deletion
  • Current positioning
  • Reset positioning
  • First/last qualification
  • Naming of an alternate I/O area that a record is read into or stored from
  • Retrieval of segments using concatenated key qualification
Syntax: for Format 1

Unqualified.

DB-OBTAIN REC recordname [HOLD] [RESET]
Syntax: for Format 2

Qualified.

DB-OBTAIN REC recordname
... WHERE fieldname1 operator value
... [AND|OR fieldname2 operator value [FIRST|LAST]
... [INTO dataarea]
        .
        .
... [AND|OR fieldnameN operator value] [FIRST|LAST]
... [INTO dataarea] [HOLD]]] [RESET]
Syntax: for Format 3

Qualified on secondary index values.

DB-OBTAIN REC recordname
... WHERE fieldname operator (value1 [ ... valueN])
... [INTO dataarea]
... [FIRST|LAST] [HOLD] [RESET]
Syntax: for Format 4

Qualified compound retrieval.

DB-OBTAIN REF segmentname1 WHERE fieldname1 operator value
... REC|REF segmentname2 WHERE fieldname2 operator value
        .
        .
        .
... [REC segmentnameN WHERE fieldnameN operator value
... [FIRST|LAST] [HOLD]]
... [RESET]
Syntax: for Format 5

Retrieve next segment.

DB-OBTAIN NEXT[REC] INTO dataarea
...VIEW|PCB pcbname [HOLD] [RESET]
Syntax: for Format 6

Retrieve segment specified in program at run time.

MOVE 'segmentname' TO segmentname
DB-OBTAIN IMSREC segmentname FROM dataarea
... VIEW pcbname|PCB pcbname
Syntax: for Format 7

Retrieve dependent of current record.

DB-OBTAIN REF recordname1 CURRENT
... REC recordname2 [WHERE fieldname operator value]
Syntax: for Format 8

Retrieve segment from PSB with multiple PCBs.

DB-OBTAIN REC recordname
... [WHERE fieldname operator value]
... VIEW|PCB pcbname
Syntax: for Format 9

Retrieve qualified or subscripted field.

DB-OBTAIN REC recordname
... WHERE keyname operator fieldname
... OF dataarea|SUB (number)
Syntax: for Format 10

Retrieve dependent record via concatenated key.

DB-OBTAIN REC recordname
... CKEYED dataname
Syntax Rules: for Format 2
  1. Fieldname1 can be a primary key, secondary key, segment sequence field, or segment search field. If it is a secondary key made up of more than one field, the data name supplied as value must be a concatenation of all fields composing the index.
Syntax Rules: for Format 3
  1. The number of values listed within parentheses must equal the number of source fields making up the index, and be listed in the same order. Values can be qualified or subscripted.
Syntax Rules: for Format 4
  1. Ensure that all segments lie along a single imaginary path that runs from the root down to the dependent segment, and are in the same logical database.
  2. Specify segments in hierarchical order.
  3. With a compound DB-OBTAIN, code REC for the lowest level segment.
Syntax Rules: for Format 5
  1. Do not use with IMS call codes.
  2. NEXTREC generates IMS retrieval call without segment search arguments (SSAs).
  3. Do not use field qualifications with NEXTREC and IMSREC.
Syntax Rules: for Format 6
  1. Code only one segment per call. Move the correct IMS segment name into Working-Storage before issuing the call.
  2. Do not use field qualifications with NEXTREC and IMSREC.
Syntax Rules: for Format 7
  1. Code CURRENT only with REF.
  2. Code CURRENT for the first level specified.
  3. Do not qualify a CURRENT segment in any other way; you can qualify segments below as usual.
General Rules:
  1. Use the CCODE keyword to include additional IMS command codes. See the topic IMS command codes for a list of valid CCODEs.
Parameters:

[:](altvalue)

See the information on Alternate values and Host variables in the General Rules section of the Help topic Database Calls.

REC recordname

COBOL record or IMS segment to process.

HOLD

Hold a record for modification or deletion. Code only once, at end of call.

RESET

Reset database or file positioning to the beginning. Code only once, at end of call.

WHERE fieldname operator value

Operator can be =, ^=, >, <, >=, <=, native SQL predicates (such as LIKE and BETWEEN).

FIRST

Establish positioning at the first occurrence of the specified segment; generate IMS code F.

LAST

Establish positioning at the last occurrence of the specified segment; generate IMS code L.

INTO dataarea

Specify I/O area where the program reads a record.

REF recordname

Specify a COBOL record to reference. Under IMS, the program uses the referenced segment for navigating the database.

RECsegmentname

VIEW|PCB pcbname

Specify the PCB used when the PSB contains multiple PCBs for the same database. Must be last keyword in call.

IMSREC segmentname

Specify that the segment name (maximum 8 characters) is in a Working-Storage variable for the program to read, modify, add, or delete.

CKEYED dataname

Single data area containing concatenated key information.

Examples:

Do a compound DB-OBTAIN to obtain SEGMENT-C.

DB-OBTAIN REF SEGMENT-A WHERE KEY-A = VALUE-A
... REF SEGMENT-B WHERE KEY-B = VALUE-B
... REC SEGMENT-C WHERE KEY-C = VALUE-C HOLD

Do a path call to retrieve three segments. Use REC at each level to indicate that each record is retrieved.

DB-OBTAIN REC SEGMENT-A WHERE KEY-A = VALUE-A
... REC SEGMENT-B WHERE KEY-B = VALUE-B
... REC SEGMENT-C HOLD

Do a path call to retrieve specific records (SEGMENT-A, SEGMENT-C) at certain levels. Specify that SEGMENT-B is used for qualification only and is not retrieved.

DB-OBTAIN REC SEGMENT-A WHERE KEY-A = VALUE-A
... REF SEGMENT-B WHERE KEY-B = VALUE-B
... REC SEGMENT-C HOLD

Using position, qualify database access. First, retrieve RECORD-A. Then, retrieve RECORD-B; restrict the retrieval of RECORD-B to children of the previously retrieved RECORD-A.

DB-OBTAIN REC RECORD-A WHERE FIELD-1 = VALUE-1
DB-OBTAIN REF RECORD-A CURRENT
... REC RECORD-B WHERE FIELD-2 = VALUE-2

Retrieve the last occurrence of RECORD-B under a specific RECORD-A.

DB-OBTAIN REF RECORD-A WHERE FIELD-1 = VALUE-1
... REC RECORD-B LAST

Reference the next occurrence of RECORD-A; retrieve the first occurrence of RECORD-B under RECORD-A and read it into DATAAREA-B. Also, retrieve the first occurrence of RECORD-C under RECORD-B and read it into DATAAREA-C.

DB-OBTAIN REF RECORD-A
... REC RECORD-B INTO DATAAREA-B
... REC RECORD-C INTO DATAAREA-C

Retrieve RECORD-A based on the value of the data name FIELD-X, which is found in DATAAREA-Z.

DB-OBTAIN REC RECORD-A
... WHERE KEY-A = FIELD-X OF DATAAREA-Z

Assume FIELD-X is an array as shown. First, retrieve RECORD-A based on the value of the seventh occurrence of FIELD-X. Then, obtain a dependent record by specifying its concatenated key.

01  FIELD-X OCCURS 10 TIMES PIC X(10).
        .
        .
DB-OBTAIN REC RECORD-A
... WHERE KEY-A = FIELD-X SUB(7)
        .
        .
DB-OBTAIN REC RECORD-C
... CKEYED WS-FIELD

SQL

DB-OBTAIN:
  • Selects an entire row qualified on one column
  • Selects an entire row qualified on multiple columns
  • Selects specific columns from a row
  • Names an alternate data name into which the host-variable structure is moved
  • Joins columns from more than one table
  • Specifies a union
Syntax: for Format 1

Qualified; select all columns.

DB-OBTAIN REC copylibname-REC
... WHERE column operator [:]altvalue|column
... [AND|OR column operator [:]altvalue|column]
        .
        .
        .
... [AND|OR column operator [:]altvalue|column]
... [INTO dataname]
... [FETCH FIRST 1]
... [QUERYNO number]
... [WITH [CS|RS|RR|UR]]
Syntax: for Format 2

Unqualified; select all columns.

DB-OBTAIN REC copylibname-REC
... [INTO dataname]
... [FETCH FIRST 1]
... [QUERYNO number]
... [WITH [CS|RS|RR|UR]]
Syntax: for Format 3

Implicit Join retrieving all columns from two tables.

DB-OBTAIN REC correlname1.copylibname-REC
... REC correlnameN.copylibname-REC
... [WHERE correlname.column oper
... [:]altvalue|correlname.column
... [AND|OR correlname.column oper
... [:]altval|correlname.column]
        .
        .
        .
... [AND|OR correlname.column oper
... [:]altvalue|correlname.col]]
... [FETCH FIRST 1]
... [QUERYNO number]
... [WITH [CS|RS|RR|UR]]
Syntax: for Format 4

Select specific columns.

DB-OBTAIN REC copylibname-REC
... [DISTINCT]
... column1 [(altvalue)] [AS name] [... columnN
... [(altvalue)]]
... [WHERE [correlname.]column operator
... [:]altvalue|column]
... [FETCH FIRST 1]
... [QUERYNO number]
... [WITH [CS|RS|RR|UR]]
Syntax: for Format 5

Specify an explicit Join.

DB-OBTAIN REC correlname1.copylibname-REC
... [DISTINCT]
... [column1 [... columnN]]|[NONE]
           .
           .
           .
... [[INNER JOIN|RIGHT OUTER JOIN|LEFT OUTER JOIN|FULL OUTER JOIN]
... ON joincondition]
... REC correlnameN.copylibname-REC
... [column1 [AS name] [... columnN]]|[NONE]
... [WHERE correlname.column1 oper
... [:]value|correlname.column2
... [AND|OR correlname.column3 oper
... [:]value|correlname.column4
           .
           .
           .
... AND|OR correlname.columnN op
... [:]value|correlname.columnN]]
... [FETCH FIRST 1]
... [QUERYNO number]
... [WITH [CS|RS|RR|UR]]
Parameters:

REC copylibname-REC

Specify the 01-level name of the COBOL row layout in the DCLGEN or copybook information. Copybook library name of source data. Cannot be the same as any cursor names or DB-PROCESS-ID names.

WHERE column operator

Column is the column on which to qualify the selection.

Operator can be =, ^=, >, <, >=, <=, native SQL predicates (such as LIKE and BETWEEN).

altvalue

Altvalue can be a literal or data name.

See also the information on Alternate values in the General Rules section of the Help topic Database Calls.

FETCH FIRST 1

Limits the number of rows that can be fetched. Only use on DB-OBTAIN if the query can result in more than a single row. “Fetch First 1” indicates that only one row should be retrieved.

INTO dataname

Move host variable structure into the alternate data structure dataname. Can code before or after WHERE.

Data moves after the actual SQL call via a MOVE statement. Generated code isIF OK-ON-RECMOVE hostname TO dataname

correlname.

Correlation name (maximum 18 characters); end with a period. Required if columnname is in a select list or if the WHERE clause appears in multiple joined tables.

WITH

Specifies the isolation level at which the statement is executed.

CS

Cursor stability

RS

Read stability

RR

Repeatable read

UR

Uncommited read - can only be specified if the result table is read-only.

DISTINCT

Eliminate all but one row from each set of duplicate rows. Duplicate rows have identical selected columns from the results table. You can use one or more DISTINCT keywords on selects.

column1 [(altvalue)]

Column1 can be a column name or one of the following expressions:

  • NEXT VALUE FOR sequencename
  • PREVIOUS VALUE FOR sequencename

INNER JOIN ON joincondition

Combines each row of the left table with every row of the right table keeping only the rows where the join-condition is true. If no join operator is specified, INNER is implicit

RIGHT OUTER JOIN ON joincondition

Includes the rows from the right table that were missing from the inner join.

LEFT OUTER JOIN ON joincondition

Includes the rows from the left table that were missing from the inner join.

FULL OUTER JOIN ON joincondition

Includes rows from both tables that were missing from the inner join.

Examples:

Select the rows where PM_PART_NO equals 123; move the data to an alternate area, WS-D2MAST-RECORD in Working-Storage.

DB-OBTAIN REC D2TAB-REC
... WHERE PM_PART_NO = '123'
... INTO WS-D2MAST-RECORD

Select only one row (if duplicates exist) based on multiple selection criteria.

DB-OBTAIN REC D2TAB-REC
... DISTINCT
... WHERE PM_PART_SHORT_DESC = 'WIDGET'
... AND PM_COLOR = 'RED'

Select only columns PM_PART_NO and PM_COLOR, from rows of table D2MASTER based on multiple selection criteria; eliminate duplicate rows. For column PM_PART_NO, move the data to the default destination, the COBOL host-variable of the same name; for column PM_COLOR, name an alternate destination, Working-Storage field WS-COLOR.

DB-OBTAIN REC D2TAB-REC
... DISTINCT
... PM_PART_NO PM_COLOR (WS-COLOR)
... WHERE PM_PART_SHORT_DESC = 'WIDGET'
... AND PM_COLOR = 'RED'

This example shows a DB-OBTAIN that uses SQL functions UPPER, LEFT, ROUND, CEILING, SIGN, COS, LOG, and DAYOFYEAR. It also shows usage of a FULL OUTER JOIN and WITH CLAUSE.

DB-OBTAIN
... REC A.EMSAVING-REC
...     ACCOUNT_NUMBER (ACCOUNT-NUMBER)
...     UPPER((CUSTOMER_NAME),CUSTOMER-NAME)
...     LEFT((ADDRESS_1,10),WS-ADDRESS1)
...     ADDRESS_2 (ADDRESS-2)
...     CITY (CITY)
...     STATE (STATE)
...     ZIP_CODE (ZIP-CODE)
...     ROUND((CURRENT_BALANCE,1),CURRENT-BALANCE)
... FULL OUTER JOIN
... ON
... A.ACCOUNT_NUMBER = B.ACCOUNT_NUMBER
... REC B.EMSTOCK-REC
...    ENDING_BALANCE (ENDING-BALANCE)
...    CEILING((BEGIN_BALANCE),BEGIN-BALANCE)
...    SIGN((CHANGE),CHANGE)
...    CURRENT_BALANCE (CURRENT-BALANCE)
...    STOCK_NAME (STOCK-NAME)
...    STOCK_SYMBOL (STOCK-SYMBOL)
...    GAINS_CODE (GAINS-CODE)
...    COS((SHARES),WS-FLOAT2)
...    LOG((DIVIDENDS),WS-FLOAT1)
...    MARKET_VALUE (MARKET-VALUE)
...    DATE_PURCHASED (DATE-PURCHASED)
...    DAYOFYEAR((DATE_SOLD),WS-INTEGER)
...    STOCK_TYPE (STOCK-TYPE)
... WHERE
... A.STATE = 'NY'
... WITH UR

This example shows a DB-OBTAIN using the AS clause, FETCH FIRST clause, and the SQL Function LEFT:

DB-OBTAIN
... REC CUSTMAST-REC
...    CUSTOMER_NAME
...    LEFT((ADDRESS_1,10),WS-ADDRESS,'Y') AS ADDRESSX
...    CITY
...    STATE
... WHERE
... CUSTOMER_NUMBER > #MASTX-CUSTNO
... FETCH FIRST 1

VSAM Batch

DB-OBTAIN:
  • Reads records from a file.
  • Provides a starting point in a file that meets specified key criteria in the call.
  • Reads calls sequentially, in ascending key order (sequential DB-OBTAIN).
  • Reads a record based upon specified key criteria (direct DB-OBTAIN).
  • Positions a file for a sequential DB-OBTAIN, based upon key criteria (positional DB-OBTAIN).
Syntax: for Format 1

Sequential.

DB-OBTAIN REC recordname
... [VIEW keyname] [INTO dataarea] [RESET]
Syntax: for Format 2

Direct.

DB-OBTAIN REC recordname
... WHERE keyname operator value [SUB value]
... [OF dataarea] [INTO dataarea]
Syntax: for Format 3

Positional.

DB-OBTAIN REF recordname
... WHERE keyname operator value [SUB[SCRIPT] value]
... [OF dataarea]
General Rule:
  1. AMB locates a variable length record description directly under the associated FD and places the fixed length record descriptions in Working-Storage.
Parameters:

REC recordname

COBOL record to process.

VIEW keyname

Specify key primary or alternate key.

INTO dataarea

Specify I/O area where the program reads a record.

RESET

Reset database or file positioning to the beginning. Code only once, at end of call. Code with PREV or KLEN, to reset file position to end.

Alternate reset method: prior to retrieving under VSAM Batch, set RESET-OBTAIN flag to TRUE

WHERE keyname operator value

Operator can be =, EQ, >=, GTEQ. Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or an integer.

OF dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field. Optionally code IN instead of OF.

REF recordname

Specify a COBOL record to reference. Under IMS, the program uses the referenced segment for navigating the database.

QUERYNO number

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records.

Examples:

Read records sequentially by the CUST-NUMBER key.

DB-OBTAIN REC CUST-RECORD VIEW CUST-NUMBER

Read records sequentially; store record in an alternate storage area.

DB-OBTAIN REC CUST-RECORD
... INTO CUST-RECORD-SAVE-AREA

Read records by CUST-NUMBER key; identify the subscripted SCREEN-CUST-NUMBER that is used as the key search value. After successful execution, establish file position so that a sequential DB-OBTAIN can read the next record.

DB-OBTAIN REC CUST-RECORD
... WHERE CUST-NUMBER = SCREEN-CUST-NUMBER
... SUB (ROW-CTR)

Verify the existence of a CUST-NUMBER and (if successful) provide a starting point in the file for a sequential DB-OBTAIN to execute.

DB-OBTAIN REF CUST-RECORD
... WHERE CUST-NUMBER = SCREEN-CUST-NUMBER
IF  OK-ON-REC
    DB-OBTAIN REC CUST-RECORD
    ... VIEW CUST-NUMBER

VSAM Online

DB-OBTAIN:
  • Reads records from a file.
  • Provides a starting point in a file that meets specified key criteria in the call.
  • Reads calls sequentially, in ascending key order (sequential DB-OBTAIN).
  • Reads a record based upon specified key criteria (direct DB-OBTAIN).
  • Positions a file for a sequential DB-OBTAIN, based upon key criteria (positional DB-OBTAIN).
Syntax: for Format 1

Sequential.

DB-OBTAIN REC recordname
... [VIEW keyname] [INTO dataarea]
... [HOLD] [PREV[IOUS]]
... [REQID number] [RESET]
... [SYSID systemname] [DDN ddname]
Syntax: for Format 2

Direct.

DB-OBTAIN REC recordname
... WHERE keyname operator value [SUB value]
... [OF dataarea] [INTO dataarea]
... [KLEN|KEYLENGTH value]
... [HOLD] [REQID number]
... [SYSID systemname] [DDN ddname]
Syntax: for Format 3

Positional.

DB-OBTAIN REF recordname
... WHERE keyname operator value [SUB value] [OF dataarea]
... [KLEN value] [RESETBR] [REQID number]
... [SYSID systemname] [DDN ddname]
General Rule:
  1. Always follow a DB-OBTAIN HOLD with a DB-MODIFY or DB-ERASE.
Parameters:

REC recordname

COBOL record to process.

VIEW keyname

Specify key primary or alternate key.

INTO dataarea

Specify I/O area where the program reads a record.

HOLD

Hold a record for modification or deletion. Code only once, at end of call. Do not code with PREV or KLEN.

PREV[IOUS]

Perform a reverse sequential browse starting at the last record in file. Do not code with HOLD or KLEN.

REQID number

Unique browse identifier for performing a simultaneous browse on the same key; is a single integer (0 - 9). Assign &VS-ENDBR-CONTROL = "USER" in the AMB CNTL file APVSAMIN.

RESET

Reset database or file positioning to the beginning. Code only once, at end of call. Code with PREV or KLEN, to reset file position to end.

Alternate reset method: prior to retrieving under VSAM Online, set RESET-OBTAIN flag to TRUE

SYSID systemname

Remote system name (maximum 4 characters); can be a literal region name or a Working-Storage field.

DDN ddname

Specify file ddname; can be a literal or data name defined as PIC X(8). Supply a value to the name option of CICS DATASET.

WHERE keyname operator value

Operator can be =, EQ, >=, GTEQ. Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or an integer.

OF dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field. Optionally code IN instead of OF.

KLEN|KEYLENGTH value

Specify number or characters in key length; full or partial length is valid. Value can be a number or a data name defined as PIC S9(4) COMP. AMB generates the CICS GENERIC option for a partial key length. Do not use with HOLD.

REF recordname

Specify a COBOL record to reference. Under IMS, the program uses the referenced segment for navigating the database.

RESETBR

Reset active browse on key name; generate CICS RESETBR.

Examples:

Read records sequentially by the CUST-NUMBER key.

DB-OBTAIN REC CUST-RECORD VIEW CUST-NUMBER

Sequentially read records into an alternate storage area and hold a record for updating. The VSAM Generator ends the sequential read and rereads the file via the primary key for updating. The sequential read is then resumed on the next execution of the DB-OBTAIN call.

DB-OBTAIN REC CUST-RECORD
... INTO CUST-RECORD-SAVE-AREA
... HOLD
      .
      .
      .
DB-MODIFY REC CUST-REC

Read records by CUST-NUMBER key. Identify the subscripted SCREEN-CUST-NUMBER that is used as the key search value. Establish file position for a sequential DB-OBTAIN.

DB-OBTAIN REC CUST-RECORD
... WHERE CUST-NUMBER = SCREEN-CUST-NUMBER SUB
(ROW-CTR)

Read by ORDR-NUMBER; hold the record for updating. Note that if ORDR-NUMBER was an alternate key, the file would be reread via the primary key for updating.

DB-OBTAIN REC ORDR-RECORD
... WHERE ORDR-NUMBER = CUST-ORDR-NUMBER HOLD

Verify the existence of CUST-RECORD with the value specified in CUST-NUMBER and (if successful) provide a starting point in the file for a sequential DB-OBTAIN.

DB-OBTAIN REF CUST-RECORD
... WHERE CUST-NAME = SCREEN-CUST-NAME
IF  OK-ON-REC
    DB-OBTAIN REC CUST-RECORD... VIEW CUST-NAME
Parent topic: Database Calls
Related reference
IMS command codes
Database Calls


DB-OPEN

Open a record, cursor set, or file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • SQL
  • VSAM Batch

SQL

Syntax:
DB-OPEN CUR[SOR] cursorname
General Rule:
  1. A cursor set can be opened, processed, and closed multiple times in the same program. A DB-OPEN issued for an open cursor set causes an error; first code a DB-CLOSE.
Parameters:

CUR[SOR] cursorname

Specify cursor. Cursorname must be previously named by DB-DECLARE or DB-PROCESS-ID.

Example:
Open cursor set D2MAST-CURSOR, previously defined in DB-DECLARE.
DB-OPEN CURSOR D2MAST-CURSOR

VSAM Batch

Syntax: for Format 1
DB-OPEN FILE filename [... filename]
... MODE option
Syntax: for Format 2
DB-OPEN FILE ALL
... MODE option
General Rule:
  1. DB-OPEN is required for single-platform applications.
Parameters:

FILE filename

File(s) to process.

MODE option

File processing mode: INPUT, OUTPUT, I-O, EXTEND

All

Specify all files defined in the data view.

Example:
Open the AORDER and ASUPLIR files for I-O processing.
DB-OPEN FILE AORDER ASUPLIR MODE I-O
Parent topic: Database Calls


DB-PROCESS

Combine record retrieval and looping functions into one call. DB-PROCESS provides a built-in loop structure to process records and rows. The loop structure can include blocks of user-supplied logic and AMB-generated control fields. User logic executes once for each successful iteration of DB-PROCESS, and can include:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Any AMB DB call, except DB-OPEN, DB-DECLARE, or DB-CLOSE
  • Record and row processing code, for example, MOVE DATA TO SCREEN

AMB generates the following fields, enabling you to logically terminate the loop structure.

APS-END-PROCESS | S-COBOL flag initialized FALSE. To end the process loop, set flag to TRUE.
name-END-PROCESS | AMB generates this flag, where name is the PROCESS-ID name. Use this flag when using DB-PROCESS-ID clauses for nested loops.
name-PROCESS-CTR | AMB generates this counter, where name is the PROCESS-ID name. Use this counter when using DB-PROCESS-ID clauses for nested loops.
APS-PROCESS-CTR | AMB increments this counter at each process loop execution. This counter controls looping, serves as a subscript when moving data into a table or screen fields, and counts processed records

The specific purposes of this call vary depending on the target.

Targets:

  • IMS DB
  • SQL
  • VSAM Batch
  • VSAM Online

IMS DB

DB-PROCESS processes:
  • Records that satisfy the key qualification (key qualified)
  • Records sequentially (unqualified)
Syntax: for Format 1

Key-qualified.

DB-PROCESS REC recordname
... [WHERE keyname operator value [SUB[SCRIPT] value]
... [OF|IN dataarea]]
... [DB-PROCESS-ID name] [INTO dataarea] [HOLD] [RESET]
... [VIEW|PCB pcbname]
  Controlled logic block
Syntax: for Format 2

Unqualified.

DB-PROCESS REC recordname
... [DB-PROCESS-ID name] [INTO dataarea]
... [HOLD] [RESET]
... [VIEW|PCB pcbname]
  Controlled logic block
General Rules:
  1. Processing begins at a previously established position in the database or, if RESET coded, at the beginning of the database.
  2. Use the CCODE keyword to include additional IMS command codes. See the topic IMS command codes for a list of valid CCODEs.
Parameters:

REC recordname

IMS segment to process.

WHERE keyname operator value

Operator can be =, EQ, >, GT, <, LT, >=, GE, <=, LE, <>, NE, ^=. Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or, under VSAM Batch or Online, an integer.

OF|IN dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field.

DB-PROCESS-ID name

Generate an end-process flag named name-END-PROCESS, and a counter named name-PROCESS-CTR.

Name (maximum 12 characters) must be unique, and cannot be the same as the subschema copylib names.

INTO dataarea

Specify I/O area where the program reads a record.

HOLD

Hold a record for modification or deletion. Code only once, at end of call. Do not code with PREV or KLEN.

RESET

Reset database or file positioning to the beginning. Code only once per call, at end.

Alternate reset method: prior to retrieving under VSAM Batch or Online, set RESET-OBTAIN flag to TRUE; under IMS DB, set RESET-POSITION flag to TRUE.

VIEW|PCB pcbname

Synonymous with VIEW. Specify the PCB used when the PSB contains multiple PCBs for the same database.

Example:

Process CUST-RECORD; execute logic upon each successful read. Note that CUST-PROCESS-CTR serves as a subscript for the screen fields.

DB-PROCESS REC CUST-RECORD
... WHERE CUST-KEY >= SCREEN-KEY
... DB-PROCESS-ID CUST
        IF  CUST-PROCESS-CTR > SCREEN-MAX
            TRUE CUST-END-PROCESS
        ELSE
            SCREEN-CUST    (CUST-PROCESS-CTR) = CUST-NAME
            SCREEN-PHONE   (CUST-PROCESS-CTR) = CUST-PHONE
            SCREEN-ADDRESS (CUST-PROCESS-CTR) = CUST-ADDRESS
IF NTF-ON-REC
    SCREEN-MSG = 'CUSTOMER NOT FOUND'
ELSE-IF END-ON-REC
    SCREEN-MSG = 'END OF CUSTOMER RECORDS'

Sample loop syntax:

/* Begin process loop
DB-PROCESS REC recordname
... WHERE keyname operator value keywords
... [DB-PROCESS-ID name]
    IF  APS-PROCESS-CTR|name-PROCESS-CTR > value
    /* End process loop
        TRUE APS-END-PROCESS|name-END-PROCESS
    ELSE
        /* User-written record processing logic
IF ...
/*Logic executed after process loop termination
/*    Includes file status checking

SQL

DB-PROCESS simplifies cursor row processing by:
  • Declaring a cursor
  • Opening a cursor for processing
  • Defining a loop flag and a loop counter
  • Providing logic for retrieving rows from the results table
  • Executing user-written row processing code
  • Processing closing the cursor set file at the end of processing
  • Processing entire rows throughout a cursor set
  • Processing specific columns throughout a cursor set
  • Processing specific columns and rows throughout a cursor set
  • Processing columns from more than one table, such as a join)
Syntax: for Format 1

Unqualified - select all columns.

DB-PROCESS REC copylibname-REC
... [DB-PROCESS-ID name]
... [DB-LOOP-MAX=number]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING FOR number ROWS]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [UPDATE|ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]
... [INTO dataname]
  Controlled logic block
Syntax: for Format 2

Qualified - select all columns.

DB-PROCESS REC copylibname-REC
... [DB-PROCESS-ID name]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING FOR number ROWS]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... WHERE column operator [[:]]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
          .
          .
          .
... [AND|OR column operator [[:]altvalue]|column]
... [DB-LOOP-MAX=number]
... [UPDATE|ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]
... [INTO dataname]
  Controlled logic block
Syntax: for Format 3

Select specific columns.

DB-PROCESS REC copylibname-REC
... [DB-PROCESS-ID name]
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING FOR number ROWS]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... column1 [(altvalue)] [AS name] [... columnN [(altvalue)]]
... WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
          .
          .
          .
... [AND|OR column operator [[:]altvalue]|column]
... [DB-LOOP-MAX=number]
... [UPDATE|ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]
  Controlled logic block
Syntax: for Format 4

Join columns from two or more tables:

DB-PROCESS REC correlname.copylibname-REC
... [DB-PROCESS-ID name]
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [WITH [CS|RS|RR|UR]]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING FOR number ROWS]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [column1 [(altvalue)][AS name][... columnN [(altvalue)]]]
... REC correlname.copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
          .
          .
          .
... [WHERE correlname.column oper
... [[:]altval]|correlname.column
... [AND|OR correlname.column oper
... [[:]altval]|correlname.col]
          .
          .
          .
... [AND|OR correlname.column oper
... [[:]altval]|correlname.col]
... [DB-LOOP-MAX=number]
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]
  Controlled logic block
Syntax: for Format 5

Specify a UNION.

DB-PROCESS REC copylibname-REC
... [DB-PROCESS-ID name]
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING FOR number ROWS]
... [WITH [CS|RS|RR|UR]]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [column1 [(altvalue)] [AS name] [... columnN [(altvalue)]]]
... [WHERE column operator [[:]altvalue]|column
... [AND|OR column operator [[:]altvalue]|column]
          .
          .
          .
... [AND|OR column operator [[:]altvalue]|column]]
... [DB-LOOP-MAX=number]
... UNION [ALL]
DB-OBTAIN REC copylibname-REC
          .
          .
          .
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]
  Controlled logic block
Syntax: for Format 6

Specify a Join using a join operator.

DB-PROCESS REC correlname1.copylibname-REC
... [DB-PROCESS-ID name]
... [DISTINCT]
... [FETCH ONLY|READ ONLY]
... [FETCH FIRST numberofrows]
... [SENSITIVE [DYNAMIC | STATIC] SCROLL CURSOR|INSENSITIVE SCROLL CURSOR]
... [WITH ROWSET POSITIONING FOR number ROWS]
... [WITH [CS|RS|RR|UR]]
... [QUERYNO number]
... [WITH HOLD]
... [OPTIMIZE number]
... [column1 [AS name] [... columnN]]|[NONE]
           .
           .
           .
... [[INNER JOIN|RIGHT OUTER JOIN|LEFT OUTER JOIN|FULL OUTER JOIN]
... ON joincondition]
... REC correlnameN.copylibname-REC
... [column1 [AS name] [... columnN]]|[NONE]
... [WHERE correlname.column1 oper
... [:]value|correlname.column2
... [AND|OR correlname.column3 oper
... [:]value|correlname.column4
           .
           .
           .
... AND|OR correlname.columnN op
... [:]value|correlname.columnN]]
... [DB-LOOP-MAX=number]
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]
  Controlled logic block
General Rules:
  1. DB-PROCESS generates and performs the DB-DECLARE, DB-OPEN, DB-FETCH, and DB-CLOSE calls within loop structure.
  2. AMB declares the cursor at the first DB-PROCESS. All subsequent calls within the loop reference the cursor. The cursor is named
    • By you, if you code DB-PROCESS-ID.
    • By AMB, which generates a copylib name and a numeric suffix, beginning with one and increasing by one with each subsequent DB-PROCESS for the same DCLGEN or copybook member.
  3. When you code WITH HOLD, a commit operation commits all the changes in the current unit of work, but releases only locks that are not required to maintain the cursor. Afterwards, you must code an initial DB-FETCH before you can execute a positioned update or delete. After the initial DB-FETCH, the cursor is positioned on the row following the one it was positioned on before the commit operation.
  4. When using ROWSET operations or multiple row operations on inserts, set up host-variable array structures to receive multiple values for each column.
  5. AMB creates default array structures for records that specify multiple-row fetches or entire-row, multiple-row inserts. The array size is the maximum row number value found specified in the FOR number ROWS clause for that table. For example:
    01   recordname-ARR.
     05  CobolHostVar1-ARR     picture occurs row-number times.
     05  IND-CobolHostVar1-ARR picture occurs row-number times.
     05  CobolHostVar2-ARR     picture occurs row-number times.
     05  IND-CobolHostVar2-ARR picture occurs row-number times.
     …..
     05  CobolHostVarn-ARR     picture occurs row-number times.
     05  IND-CobolHostVarn-ARR picture occurs row-number times.
Parameters:

REC copylibname-REC

Specify the 01-level name of the COBOL row layout in the DCLGEN or copybook information. Copybook library name of source data. Cannot be the same as any cursor names or DB-PROCESS-ID names.

DB-PROCESS-ID name

Generate a cursor named name (for SQL targets), an end-process flag named name-END-PROCESS, and a counter named name-PROCESS-CTR.

DB-LOOP-MAX=number

Maximum number loops allowed. Overrides loop flags for current structure only; you can define a different limit for each DB-PROCESS.

FETCH ONLY

Specify that the table is read-only and therefore the cursor cannot be referred to in positioned UPDATE and DELETE statements. Do not code in a call that contains an UPDATE clause.

Data moves after the actual SQL call via a MOVE statement. Generated code isIF OK-ON-RECMOVE hostname TO dataname

READ ONLY

Equivalent to FETCH ONLY.

FETCH FIRST numberofrows

Limits the number of rows that can be fetched.

WITH

Specifies the isolation level at which the statement is executed.

CS

Cursor stability

RS

Read stability

RR

Repeatable read

UR

Uncommited read - can only be specified if the result table is read-only.

SENSITIVE SCROLL CURSOR

Cursor is scrollable. Changes made to the base table after the result table is materialized are visible to the cursor.

DYNAMIC

The result table of the cursor when it is opened is dynamic, meaning the size of the result table and the order of rows might change when rows are inserted or deleted. This is the default.

STATIC

The size of the result table and the order of the rows do not change after the cursor is opened.

INSENSITIVE SCROLL CURSOR

Cursor is scrollable. Changes made to the base table after the result table is materialized are not visible to the cursor.

WITH ROWSET POSITIONING

Retrieve multiple rows of data from the result table as a rowset into host-variable arrays.

FOR number ROWS

Controls how many rows are returned.

Note: DB-PROCESS defaults to NEXT ROWSET in the generated FETCH logic.

WITH HOLD

Prevent the closing of a cursor as a consequence of a commit operation.

QUERYNO number

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records.

OPTIMIZE number

Specify estimated maximum number of rows that call will retrieve. If the call retrieves no more than number rows, performance could be improved. Specifying this argument does not prevent all rows from being retrieved.

INNER JOIN ON joincondition

Combines each row of the left table with every row of the right table keeping only the rows where the join-condition is true. If no join operator is specified, INNER is implicit

RIGHT OUTER JOIN ON joincondition

Includes the rows from the right table that were missing from the inner join.

LEFT OUTER JOIN ON joincondition

Includes the rows from the left table that were missing from the inner join.

FULL OUTER JOIN ON joincondition

Includes rows from both tables that were missing from the inner join.

UPDATE column1columnN

Modify columns during cursor processing. In cursor processing, you cannot modify a column unless you specify UPDATE first. Do not code UPDATE with ORDER, UNION, DISTINCT, GROUP BY, or if the call specifies a join or selects column functions. Column names cannot exceed 18 characters.

ORDER [ASC|DESC] [column11 columnN]

Sort the results table in ascending (default) or descending order, based on the values in the columns specified. Specify the column either by name or by relative position in the column selection list. Specify at least one column. Do not code with UPDATE. Column names cannot exceed 18 characters.

INTO dataname

Move host variable structure into the alternate data structure dataname. Can code before or after WHERE.

Data moves after the actual SQL call via a MOVE statement. Generated code isIF OK-ON-RECMOVE hostname TO dataname

WHERE column operator [:]altvalue|column

Column is the column on which to qualify the selection. Operator can be =, ^=, >, <, >=, <=, native SQL predicates (such as LIKE and BETWEEN). See also the information on Alternate values and Host variables in the General Rules section of the Help topic Database Calls.

AND|OR column operator [:]altvalue|column

Altvalue can be a literal or data name. See also the information on Alternate values and Host variables in the General Rules section of the Help topic Database Calls.

DISTINCT

Eliminate all but one row from each set of duplicate rows. Duplicate rows have identical selected columns from the results table. You can use one or more DISTINCT keywords on selects.

correlname.

Correlation name (maximum 18 characters); end with a period. Required if columnname is in a select list or if the WHERE clause appears in multiple joined tables.

UNION

See UNION.

Examples:

Declare, name, and open a cursor; retrieve all rows and columns; process only one row from duplicate rows; close the cursor; move data into an alternate area.

DB-PROCESS REC D2TAB-REC
... DB-PROCESS-ID D2MAST-ID
... DISTINCT
... INTO WS-D2MAST-RECORD

Eliminate duplicate rows from the cursor set (rows with matching data in columns PM_PART_NO, PM_COLOR, IN_PART_NO, and IN_COLOR are considered duplicates). Sort cursor set in ascending order by D2MASTER columns PM_PART_NO and PM_COLOR.

DB-PROCESS REC A.D2TAB-REC
... DB-PROCESS-ID D2MAST-ID
... DISTINCT
... PM_PART_NO PM_COLOR
... REC B.D2INVEN-REC
... IN_PART_NO IN_COLOR
... WHERE A.PM_PART_NO = B.IN_PART_NO
... AND A.PM_PART_SHORT_DESC =
... :WS-PART-SHORT-DESC
... AND B.IN_QTY_ONHAND > 100
... DB-LOOP-MAX=999
... ORDER A.PM_PART_NO ASC
... A.PM_COLOR ASC

Join a table to itself. Retrieve records where the IN_QTY_ONHAND column is greater than 100 and retrieve records whose IN_DATA_LAST_ORDER column matches these records.

DB-PROCESS REC A.D2INVEN-REC
... DB-PROCESS-ID D2MAST-ID
... IN_PART_NO
....IN_QTY_ONHAND
... IN_DATE_LAST_ORDER
... REC B.D2INVEN-REC
... IN_PART_NO       (:WS-PART-NO)
... IN_QTY_ONHAND    (:WS-QTY-ONHAND)
... WHERE A.IN_DATA_LAST_ORDER = B.IN_DATE_LAST_ORDER
... AND A.IN_QTY_ONHAND > 100

Use a LEFT OUTER JOIN.

DB-PROCESS
... REC A.ACCTMAST-REC
... LEFT OUTER JOIN
... ON A.ACCOUNT_NUMBER = B.ACCOUNT_NUMBER
... REC B.EMSTOCK-REC
... WHERE DIVIDENDS IS NOT NULL
... DB-PROCESS-ID PX24

Use multiple INNER JOINs:

DB-PROCESS
... REC A.EMSTOCK-REC
...     A.ACCOUNT_NUMBER   (WS-ACCOUNT-NUMBER-1)
...     A.CUSTOMER_NAME
... INNER JOIN
... ON A.ACCOUNT_NUMBER = C.ACCOUNT_NUMBER
... REC B.EMSAVING-REC
...     B.DEPOSITS   (WS-DEPOSITS)
... INNER JOIN
... ON C.ACCOUNT_NUMBER = A.ACCOUNT_NUMBER
... REC C.ACCTMAST-REC
...     C.ACCOUNT_TYPE (WS-ACCOUNT-TYPE)
...     C.CITY
... WHERE C.CITY IS NOT NULL
... DB-PROCESS-ID CSR2

Use both a LEFT OUTER JOIN and a FULL OUTER JOIN.

DB-PROCESS
... REC A.EMSTOCK-REC
...       A.ACCOUNT_NUMBER   (WS-ACCOUNT-NUMBER-1)
...       A.CUSTOMER_NAME
... LEFT OUTER JOIN
... ON A.ACCOUNT_NUMBER = C.ACCOUNT_NUMBER
... REC B.EMSAVING-REC
...       B.DEPOSITS   (WS-DEPOSITS)
... FULL OUTER JOIN
... ON C.ACCOUNT_NUMBER = A.ACCOUNT_NUMBER
... REC C.ACCTMAST-REC
...     C.ACCOUNT_TYPE (WS-ACCOUNT-TYPE)
...     C.CITY
... REC A.EMSTOCK-REC
...       A.ENDING_BALANCE
... WHERE C.CITY IS NOT NULL
... DB-PROCESS-ID CSR7

This example shows a DB-PROCESS with both a LEFT OUTER join and a RIGHT OUTER join, usage of the AS clause, and usage of SQL Functions ABS, and ROUND:

DB-PROCESS
... REC A.ACCTMAST-REC
...     ACCOUNT_NUMBER
... LEFT OUTER JOIN
... ON A.ACCOUNT_NUMBER = B.ACCOUNT_NUMBER
... REC B.EMSTOCK-REC
...     DIVIDENDS
...     ABS((BEGIN_BALANCE),WS-ABS,'N') AS ABSX
...     ROUND((CHANGE, 1),WS-CHANGE-ROUNDED,'N') AS ROUNDX
... RIGHT OUTER JOIN
... ON A.ACCOUNT_NUMBER = C.ACCOUNT_NUMBER
... AND A.ACCOUNT_NUMBER = '11111'
... REC C.EMSAVING-REC
...     ABS((DEPOSITS),WS-DEPOSITS,'N') AS DEPOSITX
...     WITHDRAWALS
... WHERE DEPOSITS IS NOT NULL
... ORDER BY ABSX, ROUNDX
... DB-PROCESS-ID PX03

This example shows a DB-PROCESS using the FOR READ ONLY, FETCH FIRST, WITH, and QUERYNO clauses, INSENSITIVE SCROLL CURSOR, and SQL functions LOWER and RIGHT:

DB-PROCESS
... REC A.ACCTMAST-REC
...     CUSTOMER_NUMBER
...     LOWER(CUSTOMER_NAME)
...     ACCOUNT_NUMBER
...     ACCOUNT_TYPE
...     ADDRESS_1
...     ADDRESS_2
...     RIGHT((CITY,5),WS-CITY-SHORT,'Y')
...     STATE
...     ZIP_CODE
... WHERE (
... CUSTOMER_NUMBER = #MASTX-CUSTNO
... ) AND
... ((A.CUSTOMER_NUMBER = #PX-FWDX-ACCTMASTER-0001 AND
... A.ACCOUNT_NUMBER > #PX-FWDX-ACCTMASTER-0002 )
... OR
... (A.CUSTOMER_NUMBER > #PX-FWDX-ACCTMASTER-0001 ))
... ORDER
... 01
... 03
... DB-PROCESS-ID PX01
... READ ONLY
... INSENSITIVE SCROLL CURSOR
... WITH CS
... QUERYNO 2
... FETCH FIRST 40

Sample loop syntax:

/* Begin process loop
DB-PROCESS REC recordname
    /* Custom row processing code
    IF APS-PROCESS-CTR|name-PROCESS-CTR > value
    /* End process loop
        TRUE APS-END-PROCESS|name-END-PROCESS
    ELSE
        /* Custom record processing logic
        /*     Can include file status
/* Logic executed after process loop termination
/*     Can include file status checking

This example shows use of a sensitive dynamic scroll cursor:

DB-PROCESS
...  REC A.ACCTMAST-REC
...  CUSTOMER_NUMBER
...  CUSTOMER_NAME
...  ACCOUNT_NUMBER
...  ACCOUNT_TYPE
...  WHERE
...  ACCOUNT_NUMBER = '111111'
...  DB-PROCESS-ID THS-CSR1
...  SENSITIVE DYNAMIC SCROLL CURSOR

This example shows ROWSET positioning:

DB-PROCESS
...  REC A.ACCTMAST-REC
...  CUSTOMER_NUMBER
...  CUSTOMER_NAME
...  ACCOUNT_NUMBER
...  ACCOUNT_TYPE
...  WHERE
...  ACCOUNT_NUMBER = '111111'
...  DB-PROCESS-ID THS-CSR3
...  SENSITIVE SCROLL CURSOR WITH ROWSET POSITIONING
...  FOR 9 ROWS

This example shows a multiple row insert:

DB-STORE
... REC ACCTMAST-REC
... CUSTOMER_NUMBER (:CUSTOMER-NUMBER-ARR)
... CUSTOMER_NAME (:CUSTOMER-NAME-ARR)
... ACCOUNT_NUMBER (:ACCOUNT-NUMBER-ARR)
... ACCOUNT_TYPE (DEFAULT)
... FOR 5 ROWS
... NOT ATOMIC

This example shows storing multiple rows:

DB-STORE REC D2MASTER-REC FOR 10 ROWS

VSAM Batch

DB-PROCESS processes records:
  • Sequentially, beginning at the position established by the key qualification (key qualified)
  • Sequentially, beginning at the beginning, end, or a previously defined position in the file (unqualified)
Syntax: for Format 1

Qualified.

DB-PROCESS REC recordname WHERE keyname operator value
... [DB-PROCESS-ID name] [SUB value]
... [OF dataarea] [INTO dataarea]
  Controlled logic block
Syntax: for Format 2

Unqualified.

DB-PROCESS REC recordname [VIEW keyname]
... [DB-PROCESS-ID name] [INTO dataarea] [RESET]
  Controlled logic block
General Rules:
  1. The ENDFILE condition can be determined outside of the process loop, even after DB-PROCESS ends the sequential browse.
  2. You must precede a DB-PROCESS call with a DB-OPEN call, and code a subsequent DB-CLOSE call. AMB does not support automatic file opening and closing.
  3. AMB locates a variable length record description directly under the associated FD and places the fixed length record descriptions in Working-Storage.

    See also the section All Formats - Stand-alone Applications below.

Parameters:

REC recordname

COBOL record to process.

WHERE keyname operator value

Operator can be =, EQ, >=, GTEQ. Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

DB-PROCESS-ID name

Generate a cursor named name (for SQL targets), an end-process flag named name-END-PROCESS, and a counter named name-PROCESS-CTR.

Name (maximum 12 characters) must be unique, and cannot be the same as the subschema copylib names.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or, an integer.

OF dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field. Optionally code IN instead of OF.

INTO dataarea

Specify I/O area where the program reads a record.

VIEW keyname

Specify primary or alternate key.

RESET

Reset database or file positioning to the beginning. Code only once per call, at end.

Alternate reset method: prior to retrieving, set RESET-OBTAIN flag to TRUE.

Example:

Process CUST-RECORD; execute logic upon each successful read. Note that CUST-PROCESS-CTR serves as a subscript for the screen fields.

DB-PROCESS REC CUST-RECORD
... WHERE CUST-KEY >= SCREEN-KEY
... DB-PROCESS-ID CUST
        IF  CUST-PROCESS-CTR > SCREEN-MAX
            TRUE CUST-END-PROCESS
        ELSE
            SCREEN-CUST    (CUST-PROCESS-CTR) = CUST-NAME
            SCREEN-PHONE   (CUST-PROCESS-CTR) = CUST-PHONE
            SCREEN-ADDRESS (CUST-PROCESS-CTR) = CUST-ADDRESS
IF NTF-ON-REC
    SCREEN-MSG = 'CUSTOMER NOT FOUND'
ELSE-IF END-ON-REC
    SCREEN-MSG = 'END OF CUSTOMER RECORDS'

Sample loop syntax

/* Begin process loop
DB-PROCESS REC recordname
... WHERE keyname operator value keywords
... [DB-PROCESS-ID name]
    IF  APS-PROCESS-CTR|name-PROCESS-CTR > value
    /* End process loop
        TRUE APS-END-PROCESS|name-END-PROCESS
    ELSE
        /* User-written record processing logic
IF ...
/*Logic executed after process loop termination
/*    Includes file status checking

VSAM Online

DB-PROCESS processes records:
  • Sequentially, beginning at the position established by the key qualification (key qualified)
  • Sequentially, beginning at the beginning, end, or a previously defined position in the file (unqualified)
Syntax: for Format 1

Key qualified.

DB-PROCESS REC recordname WHERE keyname operator value
... [DB-PROCESS-ID name] [SUB value]
... [OF dataarea] [INTO dataarea]
... [KLEN value] [HOLD] [PREV]
... [REQID number] [SYSID systemname]
... [DDN ddname]
  Controlled logic block
Syntax: for Format 2

Unqualified.

DB-PROCESS REC recordname
... [DB-PROCESS-ID name] [INTO dataarea]
... [HOLD] [PREV] [RESET]
... [REQID number] [SYSID systemname]
... [VIEW keyname] [DDN ddname]
  Controlled logic block
General Rules:
  1. Because DB-PROCESS terminates the active browse when the process loop is terminated, it is not necessary to end the browse with the DB-FREE call.
  2. DB-PROCESS unlocks a locked record when the process loop terminates. Unlocking a record via a DB-FREE UNLOCK is unnecessary.
  3. The ENDFILE condition can be determined outside of the process loop, even after DB-PROCESS ends the sequential browse.

    See also All Formats.

Parameters:

REC recordname

COBOL record to process.

WHERE keyname operator value

Operator can be =, EQ, >=, GTEQ. Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

DB-PROCESS-ID name

Generate a cursor named name (for SQL targets), an end-process flag named name-END-PROCESS, and a counter named name-PROCESS-CTR.

Name (maximum 12 characters) must be unique, and cannot be the same as the subschema copylib names.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or an integer.

OF dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field. Optionally code IN instead of OF.

INTO dataarea

Specify I/O area where the program reads a record.

KLEN|KEYLENGTH value

Specify number or characters in key length; full or partial length is valid. Value can be a number or a data name defined as PIC S9(4) COMP. AMB generates the CICS GENERIC option for a partial key length. Do not use with HOLD.

HOLD

Hold a record for modification or deletion. Code only once, at end of call. Do not code with PREV or KLEN.

PREV[IOUS]

Perform a reverse sequential browse starting at the last record in file. Do not code with HOLD or KLEN.

REQID number

Unique browse identifier for performing a simultaneous browse on the same key; is a single integer (0 - 9). Assign &VS-ENDBR-CONTROL = "USER" in the AMB CNTL file APVSAMIN.

SYSID systemname

Remote system name (maximum 4 characters); can be a literal region name or a Working-Storage field.

DDN ddname

Specify file ddname; can be a literal or data name defined as PIC X(8). Supply a value to the name option of CICS DATASET.

VIEW keyname

Specify key primary or alternate key.

Examples:

Process CUST-RECORD; execute logic upon each successful read. Note that CUST-PROCESS-CTR serves as a subscript for the screen fields.

DB-PROCESS REC CUST-RECORD
... WHERE CUST-KEY >= SCREEN-KEY
... DB-PROCESS-ID CUST
        IF  CUST-PROCESS-CTR > SCREEN-MAX
            TRUE CUST-END-PROCESS
        ELSE
            SCREEN-CUST    (CUST-PROCESS-CTR) = CUST-NAME
            SCREEN-PHONE   (CUST-PROCESS-CTR) = CUST-PHONE
            SCREEN-ADDRESS (CUST-PROCESS-CTR) = CUST-ADDRESS
IF NTF-ON-REC
    SCREEN-MSG = 'CUSTOMER NOT FOUND'
ELSE-IF END-ON-REC
    SCREEN-MSG = 'END OF CUSTOMER RECORDS'

Sample loop syntax:

/* Begin process loop
DB-PROCESS REC recordname
... WHERE keyname operator value keywords
... [DB-PROCESS-ID name]
    IF  APS-PROCESS-CTR|name-PROCESS-CTR > value
    /* End process loop
        TRUE APS-END-PROCESS|name-END-PROCESS
    ELSE
        /* User-written record processing logic
IF ...
/*Logic executed after process loop termination
/*    Includes file status checking

Sample loop syntax:

/* Begin process loop
DB-PROCESS REC recordname
    /* Custom row processing code
    IF APS-PROCESS-CTR|name-PROCESS-CTR > value
    /* End process loop
        TRUE APS-END-PROCESS|name-END-PROCESS
    ELSE
        /* Custom record processing logic
        /*     Can include file status checking
/* Logic executed after process loop termination
/*     Can include file status checking

All Formats - Stand-alone Applications

The following rules apply to all formats for DB-PROCESS used in stand-alone applications:
  1. Under SQL, code file status checking inside a DB-PROCESS loop; under IMS DB, and VSAM Batch or Online, code file status checking outside the process loop.
  2. You can nest DB-PROCESS calls if you supply each call with a unique DB-PROCESS-ID clause, thus providing controlled exits for each.
  3. DB-PROCESS continues looping until the program reaches a TRUE APS-END-PROCESS or TRUE name-END-PROCESS, an invalid or end of file condition, the limit defined by a AMB internal counter.
  4. AMB defines a loop limit as follows:
    • If you do not code DB-PROCESS-ID, the loop limit is 500, set by the AMB counter &APS-DB-PROCESS-GLOBAL-LIMIT. This counter resides in the APSMACS file APSBASE.
    • If you do code DB-PROCESS-ID, adhere to the following loop limit and counter for each target
      Target Limit AMB Counter

      IMS DB

      100

      &VS-IMS-LOOP-MAX

      SQL

      100

      &DB2-LOOP-MAX

      VSAM Batch

      999,99
9

      &VS-MVS-LOOP-MAX

      VSAM Online

      100

      &VS-CICS-LOOP-
MAX
  5. You can change the value of LOOP-MAX in the APSMACS file; this affects all generated applications. Or, change the LOOP-MAX limit at the program level by redefining it at the top of your program with the SYM1 or SYM2 keyword. For example:
    SYM1    % &prefix-LOOP-MAX = 200
Parent topic: Database Calls
Related reference
UNION
IMS command codes


DB-ROLLBACK

Perform ROLLBACK functions.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • IMS DB
  • SQL

IMS DB

Perform ROLLBACK functions.

Syntax
DB-ROLLBACK
General Rule:
  1. We recommend using the DB-COMMIT and DB-ROLLBACK calls instead of $IM-CHKP and $IM-ROLB.

SQL

Perform ROLLBACK functions.

Syntax
DB-ROLLBACK
General Rules:
  1. Use DB-ROLLBACK in conjunction with a DB-BEGIN-TRAN call, which marks the beginning of the transaction. SQL statements enclosed within DB-BEGIN-TRAN and DB-ROLLBACK calls define the transaction.
  2. AMB generates logic to BEGIN-TRAN and COMMIT or ROLLBACK a set of database updates as a logical unit of work, that is, a transaction. AMB executes a BEGIN-TRAN before a DB-STORE, DB-MODIFY, or DB-ERASE, if one is not coded.

    The following variables in APSCNTL control this runtime logic.

    % &PM-DB2-AUTO-COMMIT-SEND = "YES"
% &PM-DB2-AUTO-COMMIT-XCTL = "YES"
% &PM-DB2-AUTO-COMMIT-LINK = "YES"
% &PM-DB2-AUTO-COMMIT-TERM = "YES"

    To disable the automatic COMMIT before any of these points, set the appropriate variable to NO; to disable the automatic BEGIN-TRAN, set all the variables to NO.

Parent topic: Database Calls


DB-STORE

The purpose of this call varies depending on the target.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • IMS DB
  • SQL
  • VSAM Batch
  • VSAM Online

IMS DB

DB-STORE enables you to:
  • Specify either a single record level or multiple records along a path, like DB-OBTAIN.
  • Store a dependent segment--one that references one or more parent level segments to specify the exact record placement. This is a compound DB-STORE.
Syntax:
DB-STORE [REC|REF recordname1] [FROM dataarea]
... [VIEW|PCB pcbname]
... [WHERE fieldname operator value]
... [REC|REF recordname2] [FROM dataarea]
... [VIEW|PCB pcbname]
... [WHERE fieldname operator value]
... [SUB number] [OF|IN dataarea]
        .
        .
        .
... REC recordnameN [FROM dataarea]
... [VIEW pcbname|PCB pcbname]
... [WHERE fieldname operator value]
... [SUB number] [OF dataarea]
General Rules:
  1. When a record is not obtained from the default I/O area, such as by DB-OBTAIN INTO, code FROM dataarea.
  2. When a record is not obtained from the default PCB, such as by DB-OBTAIN VIEW|PCB, code VIEW|PCB pcbname.
  3. When you store a new root, DB-STORE places the record according to its key field value. If a STORE for a dependent record provides qualification at each parent level, this qualification specifies the position of the new record. Otherwise, prior database positioning determines record placement. Thus, a DB-STORE for a dependent record should either
    • Specify qualification at each parent level, or
    • Ensure that the preceding database call executed for the database PCB accesses the desired parent.
  4. Use the CCODE keyword to include additional IMS command codes. See the topic IMS command codes for a list of valid CCODEs.
Parameters:

REC|REF recordname

IMS segment to process.

FROM dataarea

Alternate I/O area where program deletes, modifies, or adds a record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO.

VIEW|PCB pcbname

Synonymous with VIEW. Specify the PCB used when the PSB contains multiple PCBs for the same database.

WHERE keyname operator value

Operator can be =, EQ, >, GT, <, LT, >=, GE, <=, LE, <>, NE, ^=. Value can be literal, data name, or an asterisk (*). An asterisk indicates the segment record description contains the key value.

SUB[SCRIPT] (value)

Move the subscripted field value to a specified field. Value can be a data name, literal, or, under VSAM Batch or Online, an integer.

OF|IN dataarea

Qualify the I/O area moving to the value field, when more than one structure in the Data Division contains the field.

Examples:

Add an occurrence of RECORD-A to the database.

DB-STORE REC RECORD-A

Add one occurrence of RECORD-A and one of its dependents, RECORD-B.

DB-STORE REC RECORD-A REC RECORD-B

Add one occurrence of RECORD-B, a dependent of a specific RECORD-A.

DB-STORE REF RECORD-A WHERE FIELD-1 = VALUE-1
... REC RECORD-B

Alternately, add RECORD-B by coding DB-STORE after DB-OBTAIN.

DB-OBTAIN REF RECORD-A WHERE KEY-A = VALUE-A
DB-STORE RECORD-B

SQL

DB-STORE enables you to add entire rows or selected columns.

Syntax: for Format 1
DB-STORE REC copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [FOR number ROWS] [NOT ATOMIC]
... [FROM dataname]
... [QUERYNO number]
... [WITH [CS|RS|RR]]
Syntax: for Format 2
DB-STORE REC copylibname-REC
... [column1 [(altvalue)] [... columnN [(altvalue)]]]
... [DB-OBTAIN REC copylibname-REC
... column1 [... columnN]
... [FOR number ROWS] [NOT ATOMIC]
... WHERE column1 operator [:]altvalue
... [AND|OR column2 operator [:]altvalue]]
        .
        .
... [AND|OR columnN operator [:]altvalue] ]
... [QUERYNO number]
... [WITH [CS|RS|RR]
Parameters:

REC copylibname-REC

Specify the 01-level name of the COBOL row layout in the DCLGEN or copybook information. Copybook library name of source data. Cannot be the same as any cursor names or DB-PROCESS-ID names.

column1 [(altvalue)]

Altvalue can be a literal, column name, host-variable, or one of the following expressions:

  • GENERATE_UNIQUE()
  • NEXT VALUE FOR sequencename
  • PREVIOUS VALUE FOR sequencename

See also the information on Host variables in the General Rules section of the Help topic Database Calls.

FROM dataname

Move alternate data structure to the host variable structure name. Data moves prior to the actual SQL call via MOVE statement.

FOR number ROWS

Controls how many rows are returned.

NOT ATOMIC

Rows should not be inserted as an atomic operation.

Note: Do not code ATOMIC, which is the default and should not be coded.

WHERE column operator

Column is the column on which to qualify the selection. Operator can be =, ^=, >, <, >=, <=, native SQL predicates (such as LIKE and BETWEEN).

[:]altvalue

Altvalue can be a literal or a data name.

QUERYNO number

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records.

WITH

Specifies the isolation level at which the statement is executed.

CS

Cursor stability

RS

Read stability

RR

Repeatable read

Examples:

Insert specific columns into D2MASTER; for PM_PART_NO, store information from the default COBOL host variable; for other columns, name alternate sources of information.

DB-STORE REC D2TAB-REC
... PM_PART_NO PM_NEW_PART_NO ('23432')
... PM_COLOR (:WS-NEW-COLOR)

Insert columns IN_PART_NO and IN_UNIT_BASE_PRICE from D2MASTER into table D2INVEN; select only rows from D2MASTER where PM_PART_NO does not equal PM_NEW_PART_NO.

 DB-STORE REC D2INVEN-REC
 ... IN_PART_NO IN_UNIT_BASE_PRICE
 ... DB_OBTAIN REC D2MASTER-REC
 ... PM_PART_NO PM_UNIT_BASE_PRICE
 ... WHERE PM_PART_NO not= PM_NEW_PART_NO

Use SQL insert with expressions and with the DEFAULT keyword.

DB-STORE
... REC EMSAVING-REC
... ACCOUNT_NUMBER ('100')
... CUSTOMER_NAME ('MILLER')
... ADDRESS_1 ('101 FIRST STREET')
... ACCOUNT_TYPE (DEFAULT)
... CITY ('JEFFERSON')
... STATE ('NY')
... ZIP_CODE ('19801')
... PREVIOUS_BALANCE (1000 + 22)
... DEPOSITS (1000 / 21.6)
... WITHDRAWALS (1000 / 22.5)
... INTEREST_PAID (1000 - 22)
... CURRENT_BALANCE (WS-CUR-BALANCE * 22)

VSAM Batch

Syntax:
DB-STORE REC recordname [FROM dataarea]
Parameters:

REC|REF recordname

COBOL record to process.

FROM dataarea

Alternate I/O area where program deletes, modifies, or adds a record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO.

Example:

Write ORDR-RECORD to the file; check file status.

DB-STORE REC ORDR-RECORD
IF OK-ON-REC
    SCREEN-MSG = 'ORDER ADDED TO FILE'
ELSE-IF IVD-ON-REC
    SCREEN-MSG = 'ORDER ALREADY EXISTS'

VSAM Online

Syntax:
DB-STORE REC recordname [FROM dataarea]
... [SYSID systemname] [DDN ddname]
Parameters:

REC recordname

COBOL record to process.

FROM dataarea

Alternate I/O area where program deletes, modifies, or adds a record. Required for a record obtained from an I/O area other than the default I/O area, such as by DB-OBTAIN INTO.

SYSID systemname

Remote system name (maximum 4 characters); can be a literal region name or a Working-Storage field.

DDN ddname

Specify file ddname; can be a literal or data name defined as PIC X(8). Supply a value to the name option of CICS DATASET.

Example:

Write ORDR-RECORD to the file; check file status.

DB-STORE REC ORDR-RECORD
IF OK-ON-REC
    SCREEN-MSG = 'ORDER ADDED TO FILE'
ELSE-IF IVD-ON-REC
    SCREEN-MSG = 'ORDER ALREADY EXISTS'
Parent topic: Database Calls
Related reference
IMS command codes
Database Calls


DB-SUBSCHEMA

Include the imported program subschema in your program. AMB does this for you when you specify your subschema in the Project Explorer after importing the subschema.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • IMS DB
  • SQL
  • VSAM Batch
  • VSAM Online

Syntax:

DB-SUBSCHEMA subschemaname

General Rules:

  1. Specify a subschema for a AMB program in either of the following ways.
    • Recommended way Code the subschema name in the Project Explorer.
    • Code a DB-SUBSCHEMA call before the NTRY keyword.
Parent topic: Database Calls


GSAM Calls

Access GSAM databases.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

IM-CLSE view
IM-OPEN view
IM-OPEN-INP view
IM-OPEN-OUT view
IM-OPEN-OUTA view
IM-OPEN-OUTM view
IM-GN PCBname [ssa1 [...ssa15]]
IM-GU PCBname ssa1 [...ssa15]
IM-ISRT PCBname [ssa1 [...ssa15]]

Parameters:

pcbname | Data view; can be up to 20 characters. Default is IO-PCB.
ssa | SSA (record search) arguments that trigger COBOL MOVEs to or from the generated I/O area IM-IO-AREA. Default is IM-IO-AREA with a length of 32,000 bytes; set IM-IO-AREA-LEN in your program or DDISYMB member to override the length.
 | Specify only one SSA per hierarchical level along a path. These arguments generate 8-byte records in Working-Storage to hold the corresponding values.
view | Data view. Must correspond to a GSAM PCB.

Examples:

The following code
$IM-OPEN ("PARDBINP")
$IM-OPEN-INP ("PARDBINP")
$IM-GN ("PARDBINP")
Generates in the Procedure Division
CALL 'CBLTDLI' USING
... IM-OPEN PARDBINP-PCB
MOVE PARDBINP-STATUS TO IM-STATUS
MOVE 'INP' TO IM-IO-AREA
CALL 'CBLTDLI' USING
... IM-OPEN PARDBINP-PCB IM-IO-AREA
MOVE PARDBINP-STATUS TO IM-STATUS
CALL 'CBLTDLI' USING
... IM-GN PARDBINP-PCB GSAM-IN-IO-AREA
MOVE PARDBINP-STATUS TO IM-STATUS
Parent topic: Database Calls


GROUP BY HAVING

Apply column functions to data elements that are collected into groups and define a hierarchy for these groups.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Use the HAVING clause, which acts as a WHERE clause, with GROUP BY to identify or evaluate the groups you want to include. A HAVING clause:

  • Names a grouping column or column function with its search conditions or qualifications
  • Can link qualifications
  • Can test the number of rows found for a group

Target:

SQL

Comments:

  • Code GROUP BY with DB-DECLARE and DB-PROCESS only.
  • Use column names or expressions.
  • Each column name in the SELECT list must be in the GROUP BY statement, and vice versa.
  • Use the ORDER BY keyword with GROUP BY to sort rows.
  • Separate each item in the GROUP BY and ORDER BY clauses with a space; commas are optional.
  • The HAVING clause should directly follow the GROUP BY statement.
  • To link qualifications, use the Boolean operators AND and OR in the HAVING clause
  • To test the number of rows found for a group, code the HAVING clause with COUNT--COUNT(*)operator value

Examples:

This statement:
DB-PROCESS REC EMPLOYEE-REC
... DB-PROCESS-ID D2EMP
... EMP-DEPT
... MAX(EMP-SALARY)
... WHERE EMP-NAME NOT NULL
... GROUP BY EMP-DEPT
... ORDER BY EMP-DEPT
Yields this result:
EMP-DEPT    EMP-SALARY
--------    ----------
FIN001      66700.000
FIN201      45250.000
MKT001      72300.000
PAY001      68800.000
PAY002      43500.000
SYS001      75000.000
This statement first groups rows by EMP-DEPT number, then within department by EMP-SEX, and then calculates maximum rates and salaries for each group.
DB-PROCESS REC EMPLOYEE-REC
... DB-PROCESS-ID D2EMP
... EMP-DEPT
... EMP-SEX
... MAX(EMP-RATE)
... MAX(EMP-SALARY)
... WHERE EMP-NAME NOT NULL
... GROUP BY EMP-DEPT,EMP-SEX
... HAVING COUNT(*) > 2
... AND MIN(EMP-RATE) > 3
... ORDER BY EMP-DEPT,EMP-SEX
Resulting in:
EMP-DEPT    EMP-SEX     EMP-RATE    EMP-SALARY
---------    -------    ---------   ----------
FIN001      F           32.067      66700.000
FIN001      M           31.105      64700.000
FIN201      F           19.711      41000.000
FIN201      M           21.754      45250.000
PAY001      F           33.076      68800.000
PAY001      M           31.884      66320.000
SYS001      F           32.692      68000.000
SYS001      M           36.058      75000.000
This statement uses an expression rather than a column name:
DB-PROCESS
... REC EMSAVING-REC DB-PROCESS-ID ID-DETAIL
... RIGHT((ADDRESS_1,12),WS-ADDRESS1) AS ADDRESS-RIGHT1
... PREVIOUS_BALANCE + INTEREST_PAID
... SUM(INTEREST_PAID)
... WHERE STATE = 'MD'
... GROUP BY
... RIGHT(ADDRESS_1,12)
... PREVIOUS_BALANCE + INTEREST_PAID
... SUM(INTEREST_PAID)
... ORDER BY
... PREVIOUS_BALANCE + INTEREST_PAID
... ADDRESS_1
Which produces this generated code:
EXEC SQL DECLARE ID_DETAIL CURSOR
  FOR SELECT
  RIGHT(  ADDRESS_1,12)
      AS ADDRESS-RIGHT1,
  PREVIOUS_BALANCE + INTEREST_PAID,
  SUM( INTEREST_PAID)
  FROM
  MFIFAT.EMSAVINGS
  WHERE
  STATE = 'MD'
  GROUP BY
  RIGHT(ADDRESS_1,12),
  PREVIOUS_BALANCE
  +
  INTEREST_PAID,
  SUM(INTEREST_PAID)
  ORDER BY
  PREVIOUS_BALANCE
  +
  INTEREST_PAID,
  ADDRESS_1
END-EXEC
perform OPEN CURSOR paragraph,
FETCH CURSOR paragraph, and CLOSE CURSOR paragraph
Parent topic: Database Calls


IMS command codes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Use the CCODE keyword to include additional IMS command codes in DB-OBTAIN, DB-MODIFY, DB-PROCESS, and DB-STORE. Most IMS command codes are generated by the call keywords; any command code you specify with the CCODE keyword is added to these.

Note: Use CCODE carefully, because the command codes you specify with it are not validated by the IMS DB Generator.
Valid IMS CCODEs are:
P | Establish parentage at this level.
Q | Enqueue the segment.
U | Maintain current position at this level.
- | Null command code.
AMB generates the following IMS CCODEs; do not code them yourself.
D | Put segment in I/O area (generated by REC).
F | Locate first occurrence (generated by FIRST).
L | Locate last occurrence (generated by LAST).
N | Do not replace segment (generated by REF).
V | Maintain current position at this level (generated by CURRENT).

For more information, refer to the applicable IMS manuals.

Parent topic: Database Calls
Related reference
DB-OBTAIN


Joining Tables

Join rows or columns from more than one table in the same call using the DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

SQL

Syntax for Format 1

With DB-DECLARE

DB-DECLARE cursorname correlname1.copylibname-REC
... [DISTINCT]
... [column1 [... columnN]]|[NONE]
           .
... correlnameN.copylibname-REC
... [column1 [... columnN]]|[NONE]
           .
... [WHERE correlname.column1 op [:]value|correlname.column2
... [AND|OR correlname.column3 op [:]value|correlname.column4
           .
... AND|OR correlname.columnN operator [:]value|correlnameN]]
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC]]]

Syntax for Format 2

With DB-OBTAIN

DB-OBTAIN REC correlname1.copylibname-REC
... [DISTINCT]
... [column1 [... columnN]]|[NONE]
           .
... REC correlnameN.copylibname-REC
... [column1 [... columnN]]|[NONE]
... [WHERE correlname.column1 op [:]value|correlname.column2
... [AND|OR correlname.column3 op [:]value|correlname.column4
           .
... AND|OR correlname.columnN op [:]val|correlname.columnN]]

Syntax for Format 3

With DB-PROCESS

DB-PROCESS REC correlname1.copylibname-REC
... [DB-PROCESS-ID name]
... [DISTINCT]
... [column1 [... columnN]]|[NONE]
           .
... REC correlnameN.copylibname-REC
... [column1 [... columnN]]|[NONE]
... [WHERE correlname.column1 op [:]value|correlname.column2
... [AND|OR correlname.column3 op [:]value|correlname.column4
           .
... AND|OR correlname.columnN op [:]val|correlname.columnN]]
... [DB-LOOP-MAX=number]
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]
        Controlled logic block

General Rules:

  1. Including a correlation name with each column is optional when joining tables. Correlation names help insulate your code against changes in table structures, and emphasize the exact columns you are accessing. A call requires a correlation name if the column name in a select list or WHERE clause appears in more than one of the joined tables.
  2. Use the NONE keyword when you want to qualify on the table, that is, you reference the table with a WHERE clause, but do not want to select columns.
  3. Join your tables together before coding WHERE. You can join any number of tables. You can also join a table to itself.
  4. The WHERE clause refers to any column prefaced with the correlation name assigned to its table. Be sure to enter the correct correlation name–the SQL Generator cannot check it for you.

Example:

Select specific columns from tables D2MASTER and D2INVTRY; add qualifications to the WHERE clause. Note that every column in the WHERE clause is preceded by a correlation name.
DB-OBTAIN REC A.D2TAB-REC
... PM_PART_NO PM_UNITS PM_COLOR
... REC B.D2INVEN-REC
... IN_PART_NO IN_QTY_ONHAND
... IN_DATE_LAST_ORDER
... WHERE A.PM_PART_NO = B.IN_PART_NO
... AND A.PM_COLOR = 'RED'
... AND B.IN_COLOR = 'RED'

Declare the cursor D2JOIN-CUR and include columns from tables D2MASTER and D2INVTRY. Use a WHERE clause to select rows where:

  • Columns PM_PART_NO and IN_PART_NO from each table match
  • Column IN_QTY_ONHAND from table D2INVTRY is greater than 100
Eliminate duplicate rows from the cursor set (rows with matching data in every selected column are considered duplicates). Sort the cursor set in ascending order by PM_PART_NO from table D2MASTER, then in descending order by IN_QTY_ONHAND from table D2INVTRY.
DB-DECLARE D2JOIN-CUR A.D2TAB-REC
... DISTINCT
... PM_PART_NO PM_COLOR
... B.D2INVEN-REC
... IN_PART_NO IN_QTY_ONHAND
... WHERE A.PM_PART_NO = B.IN_PART_NO
... AND B.IN_QTY_ONHAND > 100
... ORDER A.PM_PART_NO B.IN_QTY_ONHAND DESC

Process the cursor D2MAST-ID. The cursor set includes columns from tables D2MASTER and D2INVTRY. Use a WHERE clause to include rows in the cursor set where:

  • Columns PM_PART_NO and IN_PART_NO from each table match
  • Column PM_PART_SHORT_DESC from table D2MASTER equals the Working-Storage variable :WS-PART-SHORT-DESC
  • IN_QTY_ONHAND from table D2INVTRY is greater than 100
Eliminate duplicate rows from the cursor set (rows with matching data in columns PM_PART_NO, PM_COLOR, IN_PART_NO, and IN_COLOR are considered duplicates). Sort cursor set in ascending order by D2MASTER columns PM_PART_NO and PM_COLOR.
DB-PROCESS REC A.D2TAB-REC
... DB-PROCESS-ID D2MAST-ID
... DISTINCT
... PM_PART_NO PM_COLOR
... REC B.D2INVEN-REC
... IN_PART_NO IN_COLOR
... WHERE A.PM_PART_NO = B.IN_PART_NO
... AND A.PM_PART_SHORT_DESC =
... :WS-PART-SHORT-DESC
... AND B.IN_QTY_ONHAND > 100
... DB-LOOP-MAX=999
... ORDER A.PM_PART_NO ASC
... A.PM_COLOR ASC
Join a table to itself. Retrieve records where the IN_QTY_ONHAND column is greater than 100 and retrieve records whose IN_DATA_LAST_ORDER column matches these records.
DB-PROCESS REC A.D2INVEN-REC
... DB-PROCESS-ID D2MAST-ID
... IN_PART_NO
....IN_QTY_ONHAND
... IN_DATE_LAST_ORDER
... REC B.D2INVEN-REC
... IN_PART_NO       (:WS-PART-NO)
... IN_QTY_ONHAND    (:WS-QTY-ONHAND)
... WHERE A.IN_DATA_LAST_ORDER = B.IN_DATE_LAST_ORDER
... AND A.IN_QTY_ONHAND > 100
Parent topic: Database Calls
Related reference
Database Access Statements


NULL Indicator Field

Use a null indicator variable to indicate whether the associated host variable has been assigned a null value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

SQL

Syntax:

SQL generates a null indicator variable in Working-Storage, defined as:

01  IND-cursorname|IND-recordname
    05  IND-column

General Rules:

  1. When using indicator variables, prefix them with the 01 level name, because AMB can generate duplicate names with different 01 levels.
  2. When column contains an underscore, it changes to a hyphen at program generation.
  3. Normally, the IND-cursorname structure references a cursor set. To override this structure when generating indicator variables, set the &D2-USE-CURSOR-IND flag to NO in the AMB CNTL member APDB2IN. This generates the indicator variables with the IND-recordname structure.
Parent topic: Database Calls


Special Registers

Use selected SQL calls to reference and test special registers as column values. Special Registers include:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • CURRENT DATE
  • CURRENT TIME
  • CURRENT TIMESTAMP
  • CURRENT TIMEZONE

Use special registers in DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls to:

  • Store and display the special register values.
  • Evaluate special register values in WHERE clauses for conditional processing.

Target:

SQL

Comment:

Do not use SQL function names, such as HOUR, TIMESTAMP, as column names.

Examples:

Store the value of CURRENT-DATE in a Working-Storage field.

DB-OBTAIN REC D2TAB-REC
... PM_PART_NO
... PM_COLOR (WS-COLOR)
... CURRENT DATE (WS-CURR-DATE)
... WHERE PM_PART_SHORT_DESC = 'WIDGET'
... AND PM_COLOR = 'RED'

Select rows by comparing column SHIP_DATE with the special register CURRENT DATE.

DB-PROCESS REC D2INVEN-REC
... DB-PROCESS-ID D2INV-ID
... IN_PART_NO
... IN_PART_SHORT_DESC
... IN_QTY_ONHAND
... WHERE SHIP_DATE = CURRENT DATE
Parent topic: Database Calls


Subselect Clause

Create subselect clause by embedding a complete DB-OBTAIN call within a WHERE clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

SQL

Syntax:

Embed a DB-OBTAIN call by enclosing it in parentheses. The syntax for the embedded DB-OBTAIN is the same as that for a standard DB-OBTAIN.

General Rules:

  1. Create subselect code in a DB-DECLARE, DB-OBTAIN, DB-PROCESS, or DB-STORE call.
  2. All standard SQL requirements for a subselect clause apply to the embedded DB-OBTAIN.
  3. The number and type of columns coded must match the DB-OBTAIN column sequence; both calls must specify columns from different tables.
  4. When you code a DB-STORE call, make sure that you:
    • Make the number of selected columns for DB-STORE match the number of columns in the result table for the subselect.
    • Do not code the same copylibname-REC in both the DB-STORE and subselect calls.
    • Do not code DB STORE FROM dataname.
    • Do not code alternate values for any columns in DB-STORE.
    • Do not enclose the subselect statement in parentheses, as you do for other DB calls.

Example:

DB-OBTAIN REC A.D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE
... WHERE EXISTS
... (DB-OBTAIN REC D2INVEN-REC
... WHERE IN_PART_NO = A.PM_PART_NO)
DB-DECLARE D2MAST-CURSOR D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_COLOR
... WHERE PM_PART_NO IN
... (DB-OBTAIN
... REC D2INVEN-REC IN_PART_NO
... WHERE IN_QTY_ONHAND > 100)
... AND PM_UNIT_BASE_PRICE BETWEEN 50 and 100
DB-PROCESS REC D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_COLOR
... WHERE PM_UNITS <
... (DB-OBTAIN REC D2TAB-REC
... AVG(PM_UNITS))
DB-STORE REC D2INVEN-REC
... IN_PART_NO IN_QTY_ONHAND
... DB-OBTAIN REC D2TAB-REC
... PM_PART_NO PM_PART_SHORT_DESC
... WHERE PM_UNITS > '99'
Parent topic: Database Calls


UNION

Unite a DB-DECLARE or DB-PROCESS call with one or more DB-OBTAIN calls via the UNION keyword, which collects similar columns from two or more tables into one new table. The DB-OBTAIN calls in a union can select rows from one or many tables; the union results in a single table containing the rows selected by each call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

SQL

Syntax: for DB-DECLARE

DB-DECLARE cursorname [correlname1.]copylibname-REC
          .
          .
... UNION [ALL]
DB-OBTAIN REC copylibname-REC
          .
          .
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

Syntax: for DB-PROCESS

DB-PROCESS REC [correlname1.]copylibname-REC
          .
          .
... UNION [ALL]
DB-OBTAIN REC copylibname-REC
          .
          .
... [ORDER
... column1 [ASC|DESC] [...columnN [ASC|DESC]]]

General Rules:

  1. To create a union of tables, code all keywords and parameters for each DB-DECLARE, DB-OBTAIN, and DB-PROCESS call just as you do for a single call.
  2. When coding a UNION, the columns selected in the DB-PROCESS or DB-DECLARE statements in the UNION determine the host variables the FETCH uses. Specify return-fields only in the DB-DECLARE or DB-PROCESS statements of the UNION. See the last example below.
  3. Because a UNION places all rows in a single table, code INTO only in the last DB-OBTAIN call. However, if a DB-OBTAIN call joins tables, do not code INTO, which puts the results from only one table's host-area into the alternate area. A joined table has only part of its contents placed into the alternate area named by INTO.
  4. The column selection list for DB-DECLARE, DB-PROCESS, and each DB-OBTAIN must adhere to standard SQL rules for UNION.
  5. To identify the source call that produces each row in a UNION, include numeric and character literals in your column specifications for each call. Each row then includes a column that identifies the specific DB-DECLARE, DB-OBTAIN, or DB-PROCESS call that retrieved it.
  6. Although you can code a literal for a column in any SQL call, its primary use is for UNIONs.
  7. UNION ALL includes all rows selected from the source tables in the new table. To eliminate duplicate rows from the new table, do not code ALL.
  8. SQL statements adhere to all other SQL requirements for tables created through a union.
  9. UNION combines tables with the same number of columns. The rows of each table must contain column sequences that match in data type and length.
  10. To sort rows in a table, code the ORDER clause, as follows:
    • Code ORDER only once, as the final statement in the last DB-OBTAIN call. The ORDER clause applies to the result table produced by UNION.
    • Specify sort columns by their position in the selection list (for example, 1 or 2), rather than by name.

Parameters:

See the applicable database call for parameter descriptions.

Examples:

Unite DB-DECLARE with one DB-OBTAIN; eliminate duplicate rows; sort the combined table in ascending order by PM_PART_NO, then in descending order by PM_UNIT_BASE_PRICE and PM_UNITS. Note that the column literals STMT1 and STMT2 identify which call retrieves each row.

DB-DECLARE D2MAST-CURSOR D2TAB-REC
... DISTINCT
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS 'STMT1'
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE BETWEEN 50 AND 150
... UNION
DB-OBTAIN REC D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS 'STMT2'
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE > 300
... AND PM_UNITS > 1000
... ORDER 1,2 DESC, 3 DESC

Unite DB-PROCESS with one DB-OBTAIN call. Sort the combined table in ascending order by PM_PART_NO, then in descending order by PM_UNIT_BASE_PRICE and PM_UNITS.

DB-PROCESS REC D2TAB-REC
... DB-PROCESS-ID D2UNION-ID
... DISTINCT
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE > 50
... AND PM_UNIT_BASE_PRICE < 150
... DB-LOOP-MAX=500
... UNION
DB-OBTAIN REC D2TAB-REC
... PM_PART_NO PM_UNIT_BASE_PRICE PM_UNITS
... WHERE PM_PART_SHORT_DESC = :WS-PART-SHORT-DESC
... AND PM_UNIT_BASE_PRICE > 300
... AND PM_UNITS > 1000
... ORDER 1,2

Because return-fields are not specified for JOB_NAME and PROC_NAME, the host variables of those same names are used. In the case of the literal P, no host variable exists so a return-field must be specified. Specify return-fields only in the DB-DECLARE or DB-PROCESS statements.

DB-PROCESS
... REC A.HTJCLD-REC
... DB-PROCESS-ID SHARED-ID
... JOB_NAME
... PROC_NAME
... REC B.HTJOBR-REC
... 'P'  (WS-HOLD-ACTION)
... WHERE B.RESOURCE = :WS-RESOURCE AND
... B.JOB_NAME = :WS-JOB-NAME
... UNION ALL
DB-OBTAIN REC A.HTJCLD-REC
... DISTINCT JOB_NAME
... PROC_NAME
... REC B.HTJSTEP-REC
... 'A'
... WHERE B.JOB_NAME = :WS-JOB-NAME
... ORDER 01 03 02

Retrieve different columns from two tables. Unite DB-PROCESS with one DB-OBTAIN call and sort the combined table in ascending order by UNIT_CODE, STD_MAT_INV_ACCT, and PART_NUMBER.

In the DB-PROCESS call, select five columns from table 1. However, in the DB-OBTAIN statement, select only two columns from table 2. To maintain the same number of columns for each select, enter literals as place holder values that correspond in data type to table 1. To use different columns in the DB-PROCESS call (or in a DB-DECLARE call), be sure that each corresponding column from the DB-PROCESS call (or DB-DECLARE call) and each DB-OBTAIN call match in data type.

DB-PROCESS REC MANAGE01-REC
... UNIT_CODE STD_MAT_INV_ACCT
... PART_NUMBER      (WS-PART-NUMBER)
... UNIT_OF_MEASURE  (WS-UNIT-OF-MEASURE)
... FREIGHT_CODE     (WS-FREIGHT-CODE)
... WHERE NOT DATA_TYPE = `F'
... UNION
DB-OBTAIN REC-MANAGE02-REC
... UNIT_CODE STD_MAT_INV_ACCT
... 999999           (WS-PART-NUMBER)
... `uc'             (WS-UNIT-OF-MEASURE)
... `'               (WS-FREIGHT-CODE)
... WHERE DATA_TYPE = `F'
... ORDER 1 2 3
Parent topic: Database Calls


Date Field Formats

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Valid mask characters
Valid mask characters are Y (year), M (month), D (day), and special characters.
Default input and output format
MM.DD.YY The field length determines if the special characters are assigned. For example, if you select the MM/DD/YY format, and the field length is 8, then AMB assigns MM/DD/YY to the field; if the field length is 6, AMB assigns MMDDYY to the field.
Restrictions
Y
  • 2 or 4 characters
  • 2 Ys indicate a numeric year, such as 14
  • 4 Ys indicate a numeric century and year, such as 2014
M
  • 2, 3, or 9 characters
  • 2 Ms indicate a numeric month, such as 12
  • 3 Ms indicate a short character month, such as DEC
  • 9 Ms indicate a long character month, such as DECEMBER
D
  • 3 characters if you do not define Month, otherwise it must be 2 characters
  • 2 Ds indicate a numeric Gregorian day, such as 30
  • 3 Ds indicate a numeric Julian day, such as 360

Month, day, and year must be in the same order in both the input and output formats. For example:

Storage Format | YYYYMMDD
Input Format | MMDDYY
Output Format | MMMMMMMMM DD, YYYY
Parent topic: Reference
Related reference
Input Representation


Distributed Generation Server

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • AMBCOMP Step Return Codes
  • AMBCOMP SYSIN Cards
  • JCL SYSIN Parameters
  • JCL Example
  • Output Files and Directories
Parent topic: Reference


AMBCOMP Step Return Codes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

After completing the generation process, DGS passes a return code to the AMBCOMP program. Just before terminating, AMBCOMP moves the value of the return code to the RETURN-CODE register. You can test this return code in the remaining job steps of your JCL. A text message, explaining the return code, is also written to held output.

The following table lists the possible return codes and a description of each.

Return Code | Description
4000
  • Incomplete parameters passed to AMBCOMP
  • Duplicate parameters passed to AMBCOMP
  • Required parameters not passed to AMBCOMP
  • Invalid parameters passed to AMBCOMP
3000 | MQ problems
2000 – 2999 | Distributed Generation Server problems
0 – 12 | AMB generation return codes
Parent topic: Distributed Generation Server


AMBCOMP SYSIN Cards

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

DGS provides AMBCOMP SYSIN cards. See the table AMBCOMP Input CNTL file DD parameters in AMBCOMP Input CNTL File DD Descriptions for a list of AMBCOMP SYSIN parameters you can use with the DGS.

  • AMBCOMP SYSIN Parameter Cards
  • AMBCOMP Input DD cards
  • AMBCOMP Input CNTL File DD Descriptions
  • AMBCOMP Output DD Descriptions
Parent topic: Distributed Generation Server


AMBCOMP SYSIN Parameter Cards

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMBCOMP SYSIN parameter cards specify generation options. These generation options are passed down to the Distributed Generation Server and alter the behavior of the AMB generators.

Format:

PARM parameter value

Example:

PARM CODEPAGE 1140
Parent topic: AMBCOMP SYSIN Cards


AMBCOMP Input DD cards

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMBCOMP input DD cards specify mainframe-cataloged PDS names where the generators can search for input source files.

Format:

DD ddname PDSname

Example:

DD APSMACS MFI01.AMB.APSMACS
  • You can specify up to 39 DD statements per library name if concatenation is required
  • You can continue any single DD statement over a maximum of three lines by putting “-“ in columns 1 and 2 of a continuation line
  • Generators search DD names in the order they appear in the DD input cards
  • You do not need to group like DD names. For example, you could specify an APSPROG DD followed by a COPYLIB DD followed by another APSPROG DD.
Parent topic: AMBCOMP SYSIN Cards


AMBCOMP Input CNTL File DD Descriptions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMBCOMP input CNTL DD cards specify the PDS and member name of three special CNTL files required by the AMB generators.

Format:

DD ddname PDSname(membername)

Example:

DD CARDIN MFI01.AMB.APSCNTL(APSDBDC)

Specify no more than one occurrence of each AMB CNTL file.

The following table lists AMBCOMP SYSIN input CNTL file DD parameters you can specify.

Table 1. AMBCOMP Input CNTL file DD parameters
Parameter | Description
APSPARM | PDS and member name of APSPARM CNTL file
CARDIN | PDS and member name of APSDBDC CNTL file
ZISPFIO | PDS and member name of ZISPFIO CNTL file
Parent topic: AMBCOMP SYSIN Cards


AMBCOMP Output DD Descriptions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMBCOMP output DD cards specify cataloged PDS name where generated components (COBOL programs, BMS, MFS, etc.) and the location of the AMB generation log file.

Format:

DD ddname PDSname

Example:

DD GLOGFILE  MFI01.AMB.GENLOG
  • Specify one occurrence for each applicable DD name
  • Because these are output files, there is no concatenation
  • For program generations, the member name of the AMB generation log file in the PDS specified for GLOGFILE is the program name
  • For screen generations, excluding CICS multiple-map mapsets, the member name of the AMB generation log file in the PDS specified for GLOGFILE is the screen name
  • For CICS multiple-map mapset generations, the member name of the AMB generation log file in the PDS specified for GLOGFILE is the mapset name.

The following table lists AMBCOMP SYSIN input DD parameters you can specify.

Parameter | Description
GAPSPROG | Mainframe PDS where AMB generation log file is uploaded
GCOBOL | Mainframe PDS where generated COBOL program is uploaded
GLOGFILE | Mainframe PDS where AMB generation log file is uploaded
GSCR | Mainframe PDS where generated BMS, MFS or ISPF panel is uploaded
GSCRSYMB | Mainframe PDS where generated screen symbol(s) are uploaded
GWORKGRP | Workstation location where AMB workgroup definition resides
Parent topic: AMBCOMP SYSIN Cards


JCL SYSIN Parameters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following table lists JCL SYSIN parameters you can use with the DGS. To see an example of these in the JCL, see JCL Example.

Table 1. JCL SYSIN Parameters
APPLICATION | Application name containing the screen or program being generated
APSDEBUG | Specifies the generation of S-COBOL debug code; valid values are YES and NO
CODEPAGE | Country Code Page (Default is 1140, USA code)
CURRENCY | Currency symbol used for picture clauses
DB | For program generation: gives data base target (DLI, IMS, VSAM)
DC | Data communication target. For program generation, valid targets are CICS, IMS, ISPF, and MVS. For screen generation, valid targets are CICS and IMS.
DEBUG INPUT | Writes images of AMBCOMP SYSIN lines to held output, excluding comment lines unless DEBUG SHOWCOMMENTS is specified
DEBUG POSTCALL | Writes debug information to held output before the generation request is sent to the DGS
DEBUG PRECALL | Writes debug information to held output upon completion of the generation process
DEBUG SHOWCOMMENTS | Writes images of AMBCOMP SYSIN comments lines to held output
DEBUG XML-ATOM | Writes individual XML atoms to held output
DEBUG XML-FILE | Writes the XML file passed to the DGS to held output
DECIMAL | Character used to represent the decimal point
ENDEVOR | Enables Endevor support
FOOTPRINT | Writes Endevor Footprint information to the program manifest file
GENTYPE | Indicates generation type: APSPROG or APSSCRN (APSSRC, APSEXPS and APSEXPSF not implemented yet)
LANGUAGE | Language being used
LOGFILE SYSOUT | Write the AMB generation logfile to SYSOUT
MAPSET | For CICS screen generation only, specifies the BMS mapset name
MAXJOBQCOL n | Specifies the maximum record length allowed per record in the uploaded AMB generation logfile; valid values are 80 to 132 inclusive
MQDISTRIBUTEDQUEUENAME | Workstation MQ name
MQMANAGERNAME | Name of the MQ Manager for your configuration
MQWAITINTERVAL | Timeout period for an MQ message in 1000ths of a second
NODEFDD | Looks for APSMACS and APSCNTL locations specified in SYSIN DD cards only
OSVSGEN | For program generation: value is NO to enable non-OS/VS code generation (same as COBOL-II = “YES"); otherwise the value is YES
PROGRAM | For program generation: the program name
PGMNAME | For PROGRAM-ID generation: generates PROGRAM-ID values inside quotes; valid value is LONGMIXED
PROGRAMMANIFEST YES | For program generation: create a manifest file as part of the generation process
SCANCOBOLCOPYBOOKS | Specifies whether or not to suppress the scanning of COBOL copybook files and writing that information to the program manifest. Valid values are YES (default) to scan and NO to suppress scanning.
SCANDDISRC | Specifies whether or not to suppress the scanning of DDISYMB files and writing that information to the program manifest. Valid values are YES (default) to scan and NO to suppress scanning.
SCREEN | For screen generation: the screen name; this parameter can occur multiple times for a CICS target
SQL | For program generation: the value is DB2 if the program accesses SQL tables
WORKGROUP | If non-blank, the workgroup name
Parent topic: Distributed Generation Server
Related concepts
JCL Example


JCL Example

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following is an example of JCL that generates a CICS program using the Distributed Generation Server on the Mainframe.

//MFIUSRA JOB (99999999),
//             'AMBCICG    AMBCICG',
//             CLASS=A,
//             MSGCLASS=X,
//             MSGLEVEL=(2,0)
/*NOTIFY MFIUSR
//* ***
//* START ISPSLIB(AMBJOB  ) - $Revision: 1.3 $
//* ***
//* ***
//* END   ISPSLIB(AMBJOB  ) - $Revision: 1.3 $
//* ***
//* ***
//* START ISPSLIB(AMBALLOC) - $REVISION:   1.11  $
//* ***
//**********************************************************************
//* STEP: AMBALLOC
//**********************************************************************
//AMBALLOC EXEC  PGM=IEFBR14,REGION=1024K
//SYSPRINT DD SYSOUT=*
//GCOBOL   DD DISP=(,CATLG,DELETE),
//    DSN=MFIUSR.Y040624.H5161267.COBOL,
//    UNIT=,VOL=SER=,SPACE=(3120,(12,60,20)),
//    DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120)
//GLOGFILE DD DISP=(,CATLG,DELETE),
//    DSN=MFIUSR.Y040624.H5161267.LOG,
//    UNIT=,VOL=SER=,SPACE=(13200,(12,60,20)),
//    DCB=(RECFM=FB,LRECL=132,BLKSIZE=13200)
//* ***
//* END   ISPSLIB(AMBALLOC) - $REVISION:   1.11  $
//* ***
//MFIUSRA JOB (99999999),
//             'AMBCICG    AMBCICG',
//             CLASS=A,
//             MSGCLASS=X,
//             MSGLEVEL=(2,0)
/*NOTIFY MFIUSR
//* ***
//* START ISPSLIB(AMBJOB  ) - $Revision: 1.3 $
//* ***
//* ***
//* END   ISPSLIB(AMBJOB  ) - $Revision: 1.3 $
//* ***
//* ***
//* START ISPSLIB(AMBCICP ) - $Revision: 1.3 $
//* ***
//APS2CICS  PROC
//AMBCOMP  EXEC  PGM=AMBCOMP,REGION=1024K,
//    COND=(4,LT)
//STEPLIB   DD  DISP=SHR,DSN=MFIDJM.DGSBUILD.LOADLIB2
//          DD  DISP=SHR,DSN=CSQ531.SCSQLOAD
//          DD  DISP=SHR,DSN=CEE.SCEERUN
//GLOGFILE  DD  DISP=SHR,DSN=MFIUSR.Y040624.H5161267.LOG(MASTX)
//OLOGFILE  DD  SYSOUT=*,DCB=(RECFM=FB,LRECL=132,BLKSIZE=13200)
//SYSPRINT DD SYSOUT=*
//**********************************************************************
//* STEP: SAVECOB
//**********************************************************************
//SAVECOB  EXEC PGM=IDCAMS,COND=(4,LT)
//INDD     DD DISP=SHR,
//    DSN=MFIUSR.Y040624.H5161267.COBOL(MASTX)
//OUTDD    DD DISP=SHR,
//    DSN=MFIDJM.MFEEDEMO.COBCICS(MASTX)
//SYSPRINT DD SYSOUT=*
//* ***
//* START ISPSLIB(AMBDB2  ) - $Revision: 1.3 $
//* ***
//**********************************************************************
//* STEP: DB2XLAT
//**********************************************************************
//DB2XLAT  EXEC PGM=DSNHPC,REGION=4096K,
//    COND=(4,LT),
//    PARM=('HOST(COB2),SOURCE,APOST')
//STEPLIB   DD  DISP=SHR,DSN=DSN710.SDSNEXIT
//          DD  DISP=SHR,DSN=DSN710.SDSNLOAD
//DBRMLIB   DD  DISP=(NEW,PASS),DSN=&&DBRMLIB(MASTX),
//    DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160,DSORG=PO),
//    UNIT=SYSDA,SPACE=(6160,(30,30,1),RLSE)
//SYSLIB    DD  DISP=SHR,DSN=DSN710.SRCLIB.DATA
//          DD  DISP=SHR,DSN=MFIDJM.MFEEDEMO.COPYLIB
//SYSTERM   DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//SYSUT1    DD  SPACE=(800,(500,500)),UNIT=SYSDA
//SYSUT2    DD  SPACE=(800,(500,500)),UNIT=SYSDA
//SYSIN     DD  DISP=SHR,
//    DSN=MFIUSR.Y040624.H5161267.COBOL(MASTX)
//SYSCIN    DD  DISP=(NEW,PASS),DSN=&&DB2OUT,
//    DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160),
//    UNIT=SYSDA,SPACE=(6160,(30,30),RLSE)
//* ***
//* END   ISPSLIB(AMBDB2  ) - $Revision: 1.3 $
//* ***
//* ***
//* START ISPSLIB(AMBCICS ) - $REVISION:   1.11  $
//* ***
//**********************************************************************
//* STEP: CICSXLAT
//**********************************************************************
//CICSXLAT EXEC PGM=DFHECP1$,REGION=2048K,
//    COND=(4,LT),
//    PARM=(COBOL2,NOSOURCE)
//STEPLIB   DD  DISP=SHR,DSN=CICS41.SDFHLOAD
//SYSPRINT  DD  SYSOUT=*
//SYSIN     DD  DISP=(OLD,DELETE,DELETE),
//    DSN=&&DB2OUT
//* ***
//SYSPUNCH  DD  DISP=(NEW,PASS,DELETE),DSN=&&CICSOUT,
//    DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160),
//    UNIT=SYSDA,SPACE=(6160,(200,200),RLSE)
//* ***
//* END   ISPSLIB(AMBDB2  ) - $REVISION:   1.11  $
//* ***
//* ***
//* START ISPSLIB(AMBCOBOL) - $Revision: 1.3 $
//* ***
//**********************************************************************
//* STEP: COBOL
//**********************************************************************
//COBOL    EXEC PGM=IGYCRCTL,REGION=768K,
//    COND=(4,LT),
//    PARM=(TERM,LIB,NUM,NOADV,
//          NOSEQ,
//         NOMAP,'DATA(24)',RENT,NOTRUNC,
//         NODYNAM,
//         APOST)
//STEPLIB   DD  DISP=SHR,DSN=IGY.V1R2M0.SIGYCOMP
//SYSTERM   DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//SYSIN     DD DISP=(OLD,DELETE,DELETE),
//      DSN=&&CICSOUT
//SYSLIB    DD  DISP=SHR,DSN=MFIDJM.MFEEDEMO.COPYLIB
//          DD  DISP=SHR,DSN=CICS41.SDFHCOB
//SYSUT1    DD  SPACE=(1024,(400,200)),UNIT=SYSDA
//SYSUT2    DD  SPACE=(1024,(400,200)),UNIT=SYSDA
//SYSUT3    DD  SPACE=(1024,(400,200)),UNIT=SYSDA
//SYSUT4    DD  SPACE=(1024,(400,200)),UNIT=SYSDA
//SYSUT5    DD  SPACE=(1024,(400,200)),UNIT=SYSDA
//SYSUT6    DD  SPACE=(1024,(400,200)),UNIT=SYSDA
//SYSUT7    DD  SPACE=(1024,(400,200)),UNIT=SYSDA
//SYSLIN    DD  DISP=(NEW,PASS,DELETE),DSN=&&OBJECT,
//    DCB=(LRECL=80,BLKSIZE=3200,RECFM=FB),
//    UNIT=SYSDA,SPACE=(3200,(30,30))
//* ***
//* END   ISPSLIB(AMBCOBOL) - $Revision: 1.3 $
//* ***
//* ***
//* START ISPSLIB(AMBLINK ) - $Revision: 1.3 $
//* ***
//**********************************************************************
//* STEP: LINK
//**********************************************************************
//LINK     EXEC PGM=IEWL,REGION=512K,
//    PARM=(LIST,
//          RENT,
//          MAP),
//    COND=(4,LT)
//SYSPRINT  DD  SYSOUT=*
//SYSUT1    DD  UNIT=SYSDA,SPACE=(TRK,(30,30))
//SYSLMOD   DD  DISP=SHR,DSN=MFIDJM.MFEEDEMO.LOADCICS
//SYSLIB    DD  DISP=SHR,DSN=CICS41.SDFHLOAD,
//    DCB=BLKSIZE=23476
//          DD  DISP=SHR,DSN=DSN710.SDSNEXIT
//          DD  DISP=SHR,DSN=DSN710.SDSNLOAD
//          DD  DISP=SHR,DSN=CEE.SCEECICS
//          DD  DISP=SHR,DSN=CEE.SCEELKED
//          DD  DISP=SHR,DSN=MFIDJM.MFEEDEMO.LOADCICS
//          DD  DISP=SHR,DSN=APS.APS50GA.LOADLIB2
//SYSLIN    DD  DISP=SHR,DSN=APS.APS50GA.CNTL(DFHEILIC),
//    DCB=BLKSIZE=3200
//          DD  DISP=(OLD,DELETE,DELETE),DSN=&&OBJECT
//          DD  DISP=SHR,DSN=APS.APS50GA.CNTL(DSNCLI)
//          DD  DDNAME=LINKID
//* ***
//* END   ISPSLIB(AMBLINK ) - $Revision: 1.3 $
//* ***
//* ***
//* START ISPSLIB(AMBDB2X ) - $Revision: 1.3 $
//* ***
//**********************************************************************
//* STEP: SAVEDBRM
//**********************************************************************
//SAVEDBRM EXEC PGM=IDCAMS,COND=(4,LT)
//INDD     DD DISP=(OLD,DELETE),
//    DSN=&&DBRMLIB(MASTX)
//OUTDD    DD DISP=SHR,
//    DSN=MFIDJM.MFEEDEMO.DBRMLIB(MASTX)
//SYSPRINT DD SYSOUT=*
//* ***
//* END   ISPSLIB(AMBDB2X ) - $Revision: 1.3 $
//* ***
//    PEND
//**********************************************************************
//* STEP: APS2CICS PROC
//**********************************************************************
//MASTX  EXEC APS2CICS
//* ***
//* END   ISPSLIB(AMBCICP ) - $Revision: 1.3 $
//* ***
//* ***
//* START ISPSLIB(AMBCICSY) - $REVISION:   1.11  $
//* ***
//AMBCOMP.SYSIN DD *
PARM LOGFILE        SYSOUT
PARM ENDEVOR
PARM FOOTPRINT
PARM MQMANAGERNAME  CSQ3
PARM MQMAINFRAMEQUEUENAME WILLH.AMBCOMP.MF.Q
PARM MQDISTRIBUTEDQUEUENAME WILLH.AMBCOMP.DS.Q
PARM MQWAITINTERVAL 1000000
PARM CODEPAGE       1140
PARM DECIMAL        PERIOD
PARM CURRENCY       $
PARM LANGUAGE       ENGLISH
PARM PROGRAMMANIFEST   YES
PARM WORKGROUP DEV
PARM GENTYPE APSPROG
PARM APPLICATION    BANKDEMO
PARM APSDEBUG YES
PARM PROGRAM MASTX
PARM PGMNAME LONGMIXED
PARM DB  VSAM
PARM SQL DB2
PARM DC  CICS
PARM OSVSGEN NO
*THIS IS A COMMENT
DD GCOBOL  MFIUSR.Y040624.H5161267.COBOL
DD GPROGSRC "C:\MFUSER\LONG PROJECT\LONG GROUP\DEVELOPMENT\WORK AREA\USER\TEMPX\
-- APXPROG"
DD GLOGFILE MFIUSR.Y040624.H5161267.LOG
DD GWORKGRP "C:\TMP\FILE\LOCATION\WITH LONG\SPACE NAME"
/*
//SAVECOB.SYSIN    DD *
 REPRO INFILE(INDD) -
       OUTFILE(OUTDD)
/*
//LINK.LINKID       DD *
  IDENTIFY MASTX('MFIDJM.MFEEDEMO.MFIUSR.04.175.15:16')
  NAME MASTX(R)
/*
//SAVEDBRM.SYSIN    DD *
 REPRO INFILE(INDD) -
       OUTFILE(OUTDD)
/*
//* ***
//* END   ISPSLIB(AMBCICSY) - $REVISION:   1.11  $
//* ***
//* ***
//* END   ISPSLIB(AMBCICG ) - $REVISION:   1.11  $
//* ***
Parent topic: Distributed Generation Server
Related concepts
AMBCOMP Program
Distributed Generation Server
JCL SYSIN Parameters


Output Files and Directories

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

When you run DGS, it creates output files and directories depending upon your generation target.

All generation targets:

  • GLOGFILE - Mainframe file where job output is written.
  • GWORKGRP - Workstation location where AMB workgroup resides.

Screen generation:

  • GSCRSYMB - Mainframe file where generated screen symbols are written.
  • GSCR - Mainframe file where generated BMS, MFS, and ISPF panels are written.

Program generation:

  • GPROGSRC - Workstation location where the generated Program Manifest is copied after program generation.
  • GCOBOL - Mainframe file where generated COBOL output is written.
  • GAPSPROG - Dataset where the APSPROG generated from APSEXPS is written. This applies when your program type is APSEXPS or APSEXPSF.
Parent topic: Distributed Generation Server


AppMaster Builder Error Messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • IG- Micro Focus Generator Messages
  • ADB- database messages
  • AFE- field edit messages
  • APX- Online Express messages
  • BTC- batch call messages
  • CB2- COBOL messages
  • CIC- CICS messages
  • DB2- SQL messages
  • DCL- IMS rule messages
  • DDI- database definition messages
  • DEF- internal AMB messages
  • DNA- internal AMB module messages
  • DOC- Painter messages
  • FMP- AMB Generator errors
  • IMS- IMS messages
  • INT- initialization module messages
  • MDC- TP data communication messages
  • PRM- AMB parameter messages
  • PST- message report messages
  • PTR- Painter system messages
  • RWT- Report Writer messages
  • SCB- S-COBOL Messages
  • VSM- VSAM Messages
Parent topic: Reference
Related information
Enterprise


IG- Micro Focus Generator Messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • 15nnn - IG-IGDRVR
  • 16nnn - IG-PARSE
  • 17nnn - IG-PARM
  • 19nnn - IG-INFRA
  • 20nnn - IG-GLOBAL
  • 21nnn - IG-STORE
  • 22nnn - IG-SRVCS
  • 23nnn - IG-VM
  • 24nnn - IG-BUILTIN
  • 26nnn - IG-LEX
  • 15 - IG-IGDRVR
  • 16 - IG-PARSE
  • 17 - IG-PARM
  • 19 - IG-INFRA
  • 20 - IG-GLOBAL
  • 21 - IG-STORE
  • 22 - IG-SRVCS
  • 23 - IG-VM
  • 24 - IG-BUILTIN
  • 26 - IG-LEX
Parent topic: AppMaster Builder Error Messages


15 - IG-IGDRVR

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 15002 INTEGER OVERFLOW EXCEPTION
    An integer overflow was detected. Message is severity ERROR; IG processing continues.
  • 15202 MEMORY ACCESS VIOLATION EXCEPTION
    A memory access violation was detected.
  • 15203 CTRL+BREAK or CTRL+C EXCEPTION
    The user pressed Ctrl+Break or Ctrl+C.
  • 15204 INTEGER DIVIDE BY ZERO EXCEPTION
    A division by zero was detected.
  • 15210 EXCEPTION DATATYPE MISALIGNMENT EXCEPTION
    A thread tried to read data that is misaligned on a 2-, 4-, or 8-byte boundary.
  • 15211 EXCEPTION ARRAY BOUNDS EXCEEDED EXCEPTION
    Array bounds were exceeded.
  • 15212 EXCEPTION FLOATING POINT DENORMAL OPERAND EXCEPTION
    Floating point operation is too small.
  • 15213 EXCEPTION FLT DIVIDE BY ZERO EXCEPTION
    Floating point divide by zero.
  • 15214 EXCEPTION FLT INVALID OPERATION EXCEPTION
    Floating point invalid operation exception.
  • 15216 EXCEPTION FLT STACK CHECK EXCEPTION
    The stack overflowed or underflowed due to a floating point operation.
  • 15217 EXCEPTION FLT UNDERFLOW EXCEPTION
    Exponent of floating point operation underflow (too small).
  • 15218 EXCEPTION PRIV INSTRUCTION EXCEPTION
    Attempt to execute a privileged instruction.
  • 15219 EXCEPTION IN PAGE ERROR EXCEPTION
    In page error.
  • 15220 EXCEPTION ILLEGAL INSTRUCTION EXCEPTION
    Illegal instruction.
  • 15221 EXCEPTION STACK OVERFLOW EXCEPTION
    Stack overflow.
Parent topic: IG- Micro Focus Generator Messages


15002 INTEGER OVERFLOW EXCEPTION

An integer overflow was detected. Message is severity ERROR; IG processing continues.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15202 MEMORY ACCESS VIOLATION EXCEPTION

A memory access violation was detected.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15203 CTRL+BREAK or CTRL+C EXCEPTION

The user pressed Ctrl+Break or Ctrl+C.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15204 INTEGER DIVIDE BY ZERO EXCEPTION

A division by zero was detected.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15210 EXCEPTION DATATYPE MISALIGNMENT EXCEPTION

A thread tried to read data that is misaligned on a 2-, 4-, or 8-byte boundary.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15211 EXCEPTION ARRAY BOUNDS EXCEEDED EXCEPTION

Array bounds were exceeded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15212 EXCEPTION FLOATING POINT DENORMAL OPERAND EXCEPTION

Floating point operation is too small.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15213 EXCEPTION FLT DIVIDE BY ZERO EXCEPTION

Floating point divide by zero.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15214 EXCEPTION FLT INVALID OPERATION EXCEPTION

Floating point invalid operation exception.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15216 EXCEPTION FLT STACK CHECK EXCEPTION

The stack overflowed or underflowed due to a floating point operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15217 EXCEPTION FLT UNDERFLOW EXCEPTION

Exponent of floating point operation underflow (too small).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15218 EXCEPTION PRIV INSTRUCTION EXCEPTION

Attempt to execute a privileged instruction.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15219 EXCEPTION IN PAGE ERROR EXCEPTION

In page error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15220 EXCEPTION ILLEGAL INSTRUCTION EXCEPTION

Illegal instruction.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


15221 EXCEPTION STACK OVERFLOW EXCEPTION

Stack overflow.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 15 - IG-IGDRVR


16 - IG-PARSE

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 16100 ERR SYNTAX ERROR
    The parser detected an invalid construct while parsing the statement.
  • 16101 ERR SYNTAX ERROR NEWLINE
    The parser reached an unexpected end of line. Missing delimiters such as a parenthesis or comma can cause this error.
  • 16201 ERR INVALID SYN ERROR TYPE
    The general syntax error routine within the AST generator was passed an error, which it does not recognize. This is an internal error in the GenErrorNodes function of module fmpgen.c.
  • 16202 ERR INVALID TYPE FOR DECL VAR
    Invalid data type for a DECLARE part (i.e., variable). Valid types are 'X' for string and 'N' for Numeric. Line linenumber in source file is invalid.
  • 16203 ERR INVALID ARITH OP
    Invalid arithmetic operator operatorname . Valid arithmetic operators are +, -, *, and /. Line linenumber in source file is string.
  • 16204 ERR MAX OPCODES EXCEEDED
    The opcodeCntIndex maximum reached. This is an internal error in module fmpgen.c.
  • 16205 ERR INVALID RELATIONAL OP
    Invalid relational operator operatorname . Valid relational operators are =, >, <, >=, <=, and any of these prefixed by a 'NOT'. Line linenumber in source file is string.
  • 16208 ERR INVALID SET
    The keyword following % SET is invalid. Line linenumber in source file is invalid.
  • 16209 ERR INVALID EVAL BRACKET
    Invalid value specified for SET EVAL-BRACKETS. Valid syntax is % SET EVAL-BRACKETS 'XY' where X and Y are single symbols such as < and >. Line linenumber in source file is string.
  • 16210 ERR INVALID EVAL BRACKET AUX
    Invalid value specified for SET EVAL-BRACKETS-AUX. Valid syntax is % SET EVAL-BRACKETS-AUX 'XY' where X and Y are single symbols such as < and >. Line linenumber in source file is string.
  • 16211 ERR EVAL BRACKETS NOT SET
    No value was specified for SET EVAL-BRACKETS. Line linenumber in source file is string.
  • 16212 ERR EVAL BRACKETS AUX NOT SET
    No value was specified for SET EVAL-BRACKETS-AUX. Line linenumber in source file is string.
  • 16213 ERR INVALID LEFT MARGIN
    Unsupported SET LEFT-MARGIN syntax. Only numeric values can be specified. Line linenumber in source file is string.
  • 16214 ERR INVALID RIGHT MARGIN
    Unsupported SET RIGHT-MARGIN syntax. Only numeric values can be specified. Line linenumber in source file is string.
  • 16215 ERR INVALID SET MSG
    string is an invalid msg set name on line linenumber.
  • 16216 ERR DUPLICATE FORMAL ARG
    Same formal argument 'argument' defined in macro more than once. Line linenumber in source file is string.
  • 16217 ERR UNABLE ALLOC PCODE
    Unable to allocate a node for the Abstract Syntax Tree.
  • 16218 ERR INVALID ASSIGN OP
    Invalid assignment operator operatorname . Valid assignment operators are =, <<, <+, <-, <*, and </. Line linenumber in source file is string.
  • 16219 ERR UNSUPPORTED SET
    Unsupported SET statement. Line linenumber in source file is invalid.
  • 16220 ERR FOOLMAC NOT SPECIFIED
    FMP Object Oriented Language (FOOL) generation support macro has not been specified. Defaulting to the name '$FOOLMAC'. Use the /FoolMacro=$macroname option to specify this name. Line linenumber in source file is string.
  • 16221 ERR NEW BUILTIN WARNING
    The source code references an undefined IG built-in string function.
  • 16300 ERR STMT STACK NOT EMPTY
  • 16301 ERR HEAD STACK NOT EMPTY
  • 16302 ERR TAIL STACK NOT EMPTY
  • 16303 ERR EXPR STACK NOT EMPTY
  • 16304 ERR ARG STACK NOT EMPTY
    Internal warning in FMPGNSTK. One of the following stacks is not empty.
  • 16305 ERR STACK UNDERFLOW
    string stack underflow.
  • 16306 ERR IP TREE INIT FAILED
    IPTree initialize failed to set up the tree in PushIpTreeStacks.
  • 16400 ERR INVALID SYMBOL TYPE
    Invalid variable symbol type string. Valid values are 0 thru 5. This is an internal error in module fmpsymtb.c or fmpgen.c.
  • 16401 ERR TOO MANY SOURCE SYMBOLS
    There are too many % symbol names defined in the INCLUDEd file source code. Try breaking the source code into two or more INCLUDEd files.
  • 16500 ERR INDIR TAB MAX EXCEEDED
    Maximum number of indentation levels exceeded when print an AST. Maximum number of levels is string in module fmpprint.c.
  • 16600 ERR OPENING REPORT DATA FILE OUTPUT
    Cannot open report data file filename. That file is output for the report data extraction step.
  • 16601 ERR OPENING REPORT DATA FILE INPUT
    Cannot open report data file filename. That file is input to the report generator.
  • 16602 ERR OPENING REPORT PRINT FILE
    Cannot open report data file filename. That file is the report printout file.
  • 16603 ERR EMPTY REPORT DATA FILE
    Empty report data file filename. That file is input to the report generator.
  • 16604 ERR NOT ENOUGH MEMORY FOR REPORT
    Insufficient memory in PrintCompileRunRpt routine.
  • 16605 ERR IND TAB MAX REACHED
    Maximum number of indentation levels exceeded in compilation report. Maximum number of levels is string in module comprpt.c.
  • 16700 ERR SYNTAX ERRORS FOUND
    Compile resulted in string syntax errors.
Parent topic: IG- Micro Focus Generator Messages


16100 ERR SYNTAX ERROR

The parser detected an invalid construct while parsing the statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16101 ERR SYNTAX ERROR NEWLINE

The parser reached an unexpected end of line. Missing delimiters such as a parenthesis or comma can cause this error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16201 ERR INVALID SYN ERROR TYPE

The general syntax error routine within the AST generator was passed an error, which it does not recognize. This is an internal error in the GenErrorNodes function of module fmpgen.c.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16202 ERR INVALID TYPE FOR DECL VAR

Invalid data type for a DECLARE part (i.e., variable). Valid types are 'X' for string and 'N' for Numeric. Line linenumber in source file is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16203 ERR INVALID ARITH OP

Invalid arithmetic operator operatorname . Valid arithmetic operators are +, -, *, and /. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16204 ERR MAX OPCODES EXCEEDED

The opcodeCntIndex maximum reached. This is an internal error in module fmpgen.c.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16205 ERR INVALID RELATIONAL OP

Invalid relational operator operatorname . Valid relational operators are =, >, <, >=, <=, and any of these prefixed by a 'NOT'. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16208 ERR INVALID SET

The keyword following % SET is invalid. Line linenumber in source file is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16209 ERR INVALID EVAL BRACKET

Invalid value specified for SET EVAL-BRACKETS. Valid syntax is % SET EVAL-BRACKETS 'XY' where X and Y are single symbols such as < and >. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16210 ERR INVALID EVAL BRACKET AUX

Invalid value specified for SET EVAL-BRACKETS-AUX. Valid syntax is % SET EVAL-BRACKETS-AUX 'XY' where X and Y are single symbols such as < and >. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16211 ERR EVAL BRACKETS NOT SET

No value was specified for SET EVAL-BRACKETS. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16212 ERR EVAL BRACKETS AUX NOT SET

No value was specified for SET EVAL-BRACKETS-AUX. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16213 ERR INVALID LEFT MARGIN

Unsupported SET LEFT-MARGIN syntax. Only numeric values can be specified. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16214 ERR INVALID RIGHT MARGIN

Unsupported SET RIGHT-MARGIN syntax. Only numeric values can be specified. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16215 ERR INVALID SET MSG

string is an invalid msg set name on line linenumber.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16216 ERR DUPLICATE FORMAL ARG

Same formal argument 'argument' defined in macro more than once. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16217 ERR UNABLE ALLOC PCODE

Unable to allocate a node for the Abstract Syntax Tree.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16218 ERR INVALID ASSIGN OP

Invalid assignment operator operatorname . Valid assignment operators are =, <<, <+, <-, <*, and </. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16219 ERR UNSUPPORTED SET

Unsupported SET statement. Line linenumber in source file is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16220 ERR FOOLMAC NOT SPECIFIED

FMP Object Oriented Language (FOOL) generation support macro has not been specified. Defaulting to the name '$FOOLMAC'. Use the /FoolMacro=$macroname option to specify this name. Line linenumber in source file is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16221 ERR NEW BUILTIN WARNING

The source code references an undefined IG built-in string function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16300 ERR STMT STACK NOT EMPTY

Parent topic: 16 - IG-PARSE


16301 ERR HEAD STACK NOT EMPTY

Parent topic: 16 - IG-PARSE


16302 ERR TAIL STACK NOT EMPTY

Parent topic: 16 - IG-PARSE


16303 ERR EXPR STACK NOT EMPTY

Parent topic: 16 - IG-PARSE


16304 ERR ARG STACK NOT EMPTY

Internal warning in FMPGNSTK. One of the following stacks is not empty.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Statement Stack
  • Head Stack
  • Tail Stack
  • Expression Stack
  • Argument Stack
Parent topic: 16 - IG-PARSE


16305 ERR STACK UNDERFLOW

string stack underflow.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16306 ERR IP TREE INIT FAILED

IPTree initialize failed to set up the tree in PushIpTreeStacks.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16400 ERR INVALID SYMBOL TYPE

Invalid variable symbol type string. Valid values are 0 thru 5. This is an internal error in module fmpsymtb.c or fmpgen.c.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16401 ERR TOO MANY SOURCE SYMBOLS

There are too many % symbol names defined in the INCLUDEd file source code. Try breaking the source code into two or more INCLUDEd files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16500 ERR INDIR TAB MAX EXCEEDED

Maximum number of indentation levels exceeded when print an AST. Maximum number of levels is string in module fmpprint.c.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16600 ERR OPENING REPORT DATA FILE OUTPUT

Cannot open report data file filename. That file is output for the report data extraction step.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16601 ERR OPENING REPORT DATA FILE INPUT

Cannot open report data file filename. That file is input to the report generator.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16602 ERR OPENING REPORT PRINT FILE

Cannot open report data file filename. That file is the report printout file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16603 ERR EMPTY REPORT DATA FILE

Empty report data file filename. That file is input to the report generator.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16604 ERR NOT ENOUGH MEMORY FOR REPORT

Insufficient memory in PrintCompileRunRpt routine.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16605 ERR IND TAB MAX REACHED

Maximum number of indentation levels exceeded in compilation report. Maximum number of levels is string in module comprpt.c.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


16700 ERR SYNTAX ERRORS FOUND

Compile resulted in string syntax errors.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 16 - IG-PARSE


17 - IG-PARM

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 17000 ERR INVALID PARM OPTION
    An invalid parameter option was specified in either a command line parameter or a control file. For a list of valid parameters, enter /? on the command line. The invalid option is string.
  • 17001 ERR DUPLICATE PARM OPTION
    A duplicate parameter option was specified within module parm.c. This is an internal error. The duplicate option is string.
Parent topic: IG- Micro Focus Generator Messages


17000 ERR INVALID PARM OPTION

An invalid parameter option was specified in either a command line parameter or a control file. For a list of valid parameters, enter /? on the command line. The invalid option is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 17 - IG-PARM


17001 ERR DUPLICATE PARM OPTION

A duplicate parameter option was specified within module parm.c. This is an internal error. The duplicate option is string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 17 - IG-PARM


19 - IG-INFRA

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 19000 SYMBOL NAME INVALID
  • 19000 SYMCLASS INVALID
  • 19000 SYMTYPE INVALID
    Invalid symbol type string found in the symbol descriptor at address string. This is an internal error.
  • 19100 SYMTABCLASS INVALID
    Invalid symbol name or table class found. This is an internal error.
  • 19102 SYMBOL CHAIN CORRUPTION
    Memory is corrupted. The symbol chain was broken. This is an internal error.
  • 19200 SYMPART ALREADY EXISTS
    Attempted to declare the string string as a PART of a declarative structure. The PART is ignored and not declared.
  • 19201 SYMPART INVALID REDEF
    Redefined a non-existent PART string or the length is too large.
  • 19202 SYMPART INVALID REDEF LENGTH
    Attempted to redefine a PART string of string bytes long to a smaller PART string of string bytes long.
  • 19203 INVALID DECLARE TYPE
    The string string with a string value cannot be accessed as a declarative structure.
  • 19204 INCOMPATIBLE SYMBOL TYPE
    Attempted to assign a PART symbol with a type string to a symbol with a type string. Type mismatch assignment.
  • 19300 FARG OVERRIDING DECLARE PART
  • 19301 FARG OVERRIDING GLOBAL SUBS
    Formal argument argumentname is overriding a a DECLARE part or a global subscript. This is a warning message.
  • 19400 INVALID DIRECTORY
  • 19401 INVALID FILE
    Searching for string, found an invalid file 'filename' or directory 'dirname'.
  • 19500 INVALID SYMBOL ASSIGNMENT
    Attempted to assign a string symbol string to a string string.
  • 19501 INVALID SYMBOL VALUE
    Attempted to access a string symbol string with a string value as a string value.
  • 19600 UNABLE ALLOCATE INDTAB
    When allocating an indirection table for number, symbol names failed because there are too many symbols in the source file.
Parent topic: IG- Micro Focus Generator Messages


19000 SYMBOL NAME INVALID

Parent topic: 19 - IG-INFRA


19000 SYMCLASS INVALID

Parent topic: 19 - IG-INFRA


19000 SYMTYPE INVALID

Invalid symbol type string found in the symbol descriptor at address string. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19100 SYMTABCLASS INVALID

Invalid symbol name or table class found. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19102 SYMBOL CHAIN CORRUPTION

Memory is corrupted. The symbol chain was broken. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19200 SYMPART ALREADY EXISTS

Attempted to declare the string string as a PART of a declarative structure. The PART is ignored and not declared.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19201 SYMPART INVALID REDEF

Redefined a non-existent PART string or the length is too large.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19202 SYMPART INVALID REDEF LENGTH

Attempted to redefine a PART string of string bytes long to a smaller PART string of string bytes long.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19203 INVALID DECLARE TYPE

The string string with a string value cannot be accessed as a declarative structure.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19204 INCOMPATIBLE SYMBOL TYPE

Attempted to assign a PART symbol with a type string to a symbol with a type string. Type mismatch assignment.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19300 FARG OVERRIDING DECLARE PART

Parent topic: 19 - IG-INFRA


19301 FARG OVERRIDING GLOBAL SUBS

Formal argument argumentname is overriding a a DECLARE part or a global subscript. This is a warning message.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19400 INVALID DIRECTORY

Parent topic: 19 - IG-INFRA


19401 INVALID FILE

Searching for string, found an invalid file 'filename' or directory 'dirname'.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19500 INVALID SYMBOL ASSIGNMENT

Attempted to assign a string symbol string to a string string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19501 INVALID SYMBOL VALUE

Attempted to access a string symbol string with a string value as a string value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 19 - IG-INFRA


19600 UNABLE ALLOCATE INDTAB

When allocating an indirection table for number, symbol names failed because there are too many symbols in the source file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Break the file into two or more files with fewer symbols each.

Parent topic: 19 - IG-INFRA


20 - IG-GLOBAL

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 20001 ERR MSG MODULE UNAVAIL
  • 20002 ERR MSG RES UNAVAIL
  • 20003 ERR MSG RES SIZE UNAVAIL
  • 20004 ERR INVALID FMP SUBSYSTEM
  • 20005 ERR OPENING RPT FILE
  • 20006 ERR WRITING RPT FILE
  • 20007 ERR CLOSING RPT FILE
    Error closing the FMP Report output file that provides execution status information.
  • 20008 ERR OPENING LOG FILE
  • 20009 ERR WRITING LOG FILE
  • 20010 ERR CLOSING LOG FILE
    Error occurred while writing the FMP Log (.LOG) output file that captures processing event and debugging output details.
Parent topic: IG- Micro Focus Generator Messages


20001 ERR MSG MODULE UNAVAIL

Parent topic: 20 - IG-GLOBAL


20002 ERR MSG RES UNAVAIL

Parent topic: 20 - IG-GLOBAL


20003 ERR MSG RES SIZE UNAVAIL

Parent topic: 20 - IG-GLOBAL


20004 ERR INVALID FMP SUBSYSTEM

Parent topic: 20 - IG-GLOBAL


20005 ERR OPENING RPT FILE

Parent topic: 20 - IG-GLOBAL


20006 ERR WRITING RPT FILE

Parent topic: 20 - IG-GLOBAL


20007 ERR CLOSING RPT FILE

Error closing the FMP Report output file that provides execution status information.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 20 - IG-GLOBAL


20008 ERR OPENING LOG FILE

Parent topic: 20 - IG-GLOBAL


20009 ERR WRITING LOG FILE

Parent topic: 20 - IG-GLOBAL


20010 ERR CLOSING LOG FILE

Error occurred while writing the FMP Log (.LOG) output file that captures processing event and debugging output details.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 20 - IG-GLOBAL


21 - IG-STORE

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 21004 INVALID MEM MODEL
    Memory model specified for creating DLL of compiled macros is neither 16-bit segmented or 32-bit linear model.
  • 21005 ERR OPENING ASM FILE
    Error opening .ASM output file to receive the assembler source form of compiled macros.
  • 21006 ERR WRITING ASM FILE
    Error occurred while writing the .ASM output file to receive the assembler source form of compiled macros.
  • 21007 ERR OPENING DLL FILE
    Error opening .DLL output file to directly receive the DLL form of compiled macros.
  • 21008 ERR WRITING DLL FILE
    Error writing the .DLL output file that directly receives the .DLL form of compiled macros.
  • 21009 ERR OPENING DEF FILE
    Error opening .DEF output file to receive the the module definition for creating the DLL form of compiled macros.
  • 21010 ERR WRITING DEF FILE
    Error occurred while writing the .DEF output file to receive the the module definition for creating the DLL form of compiled macros.
  • 21012 ERR OPENING OUTPUT FILE
  • 21013 ERR CLOSING OUTPUT FILE
    Error opening or closing an output file that writes out compiled macros.
  • 21014 BAD INCLUDE MEMBER NAME
    Invalid INCLUDE member name provided to the macro compilation process.
  • 21015 ERR INIT OF IRLOCMGR
    Error occurred during the initialization of the Internal Representation Location Manager.
  • 21016 MEMBER NAME TOO LONG
    Supplied INCLUDE member name is too long.
  • 21017 SAN MBR NAME TOO LONG
    Sanitized (refined) INCLUDE member name is too long.
  • 21018 TOO MANY DATA SEG PARTS
    The allowed number of data parts/segments used to write the compiled form of a macro has been exceeded. This is an FMP internal error.
  • 21019 INVALID DATA SEG PART IX
    An internal index into the data parts/segments used to write the compiled form of a macro is out of bounds. This is an FMP internal error.
  • 21020 INVALID OPCODE
    An operation was encountered that is not known to the compiled macro write routines. This is an FMP internal error.
  • 21021 NO MORE FIXUP SORT SLOTS
    When sorting fixups by page, location address, and reference address for constructing a DLL for a compiled macro, FMP ran out of slots in the sort table. This is an FMP internal error.
  • 21022 LOCATION NOT DEFINED
    A compiled macro is a complex data structure with many pointer references to locations (addresses of structures). A reference has been encountered to a location that has never been defined. This is an FMP internal error.
  • 21023 INVALID ASM SYMBOL TYPE
    When writing out a compiled macro, symbolic names are assigned to each data structure that comprises the compiled macro. A structure of unknown type has been encountered. This is an FMP internal error.
  • 21024 DUPLICATE SYMBOL DEFN
    When writing out a compiled macro, symbolic names are assigned to each data structure that comprises the compiled macro. A location of a structure has been defined twice. This is an FMP internal error.
  • 21025 DLL ENTRYTABLE EXCEEDED
  • 21026 DLL FIXUPPAGETABLE EXCEEDED
  • 21026 DLL OBJECTPAGETABLE EXCEEDED
  • 21027 DLL FIXUPRECORDTABLE EXCEEDED
  • 21029 DLL NONRESNAMES EXCEEDED
    When writing out a compiled macro as a .DLL, the size of the area allocated for the one of the following tables was exceeded. This is an FMP internal error.
  • 21100 NO ALLOC LOCMGR HASH TAB
    Could not allocate memory for the IR Location Manager hash table. This is a memory allocation error.
  • 21101 NOT ALL LOC NODES FREED
    Upon terminating, the IR Location Manager, not all allocated Location Nodes were freed to the free chain. This is an FMP internal error.
  • 21102 UNABLE ALLOC LOC NODE
    Unable to allocate memory for an IR Location Node. Location Nodes keep track of addresses in the Intermediate Representation that can be referenced and relocated. This is an FMP internal error.
  • 21103 NULL LOC NODE ADDR
    Encountered an address of an IR Location Node that is NULL. This is an FMP internal error.
  • 21200 UNABLE ALLOC REF NODE
    Unable to allocate memory for an IR Reference Node. Reference Nodes keep track of references Locations in the in the Intermediate Representation. This is an FMP internal error.
  • 21201 UNABLE CREATE REF NODE
    A call to createRefNode was unable to return an IR Reference Node in which to store a reference to an IR Location. This is an FMP internal error.
  • 21202 NOT ALL REF NODES FREED
    Upon terminating the IR Reference Manager, not all allocated Reference Nodes were freed to the free chain. This is an FMP internal error.
  • 21203 NULL REF NODE ADDR
    Encountered an address of an IR Reference Node that is NULL. This is an FMP internal error.
  • 21300 INVALID DEF QUEUE TYPE
    An invalid type of deferred queue was presented to a routine in the Deferred Queue Manager. The Deferred Queue Manager provides queues to defer writing structures out as compiled macros; there is a queue for each structure type. This is an FMP internal error.
  • 21301 NO ROOM IN DEF QUEUE
    A Deferred Queue Manager queue is full. The Deferred Queue Manager provides queues to defer writing structures out as compiled macros; there is a queue for each structure type. This is an FMP internal error.
  • 21400 UNABLE ALLOC DLL WORK
    Unable to allocate the work areas for directly writing out a .DLL of compiled macros.
  • 21401 WRONG DATA SEG TYPE16
    An a 16-bit data segment was requested for an inappropriate memory model for writing compiled macros to a DLL. 16-bit segments are only for creating a 16-bit segmented memory model DLL. This is an FMP internal error.
  • 21402 WRONG DATA PART TYPE32
    A 32-bit data part was requested for an inappropriate memory model for writing compiled macros to a DLL. 32-bit data parts are only for creating a 32-bit linear (flat) memory model DLL. For incremental allocation reasons, the single 32-bit logical data object is physically created in incrementally allocated data parts. This is an FMP internal error.
  • 21403 UNABLE ALLOC DLL AREA
    Unable to allocate memory for a work area in which to construct the DLL for the non-data portion of a compiled macro. This is a memory allocation error.
  • 21404 UNABLE ALLOC DLL DATA AREA
    Unable to allocate memory for a work area in which to construct the data part of a DLL for a compiled macro. This is a memory allocation error.
  • 21405 UNABLE ALLOC DLL FIXUP REC AREA
    Unable to allocate memory for a work area in which to construct the fixup record area for a LX DLL for a compiled macro. This is a memory allocation error.
  • 21406 DLL EXCEEDED MAX FIXUPRECORDAREAS
    Exceeded the maximum number of fixup record work areas that can be allocated. Work areas are for constructing the fixup record area for an LX DLL for a compiled macro. The limit is set by an internal constant. Try breaking the macro source file into several smaller files.
  • 21407 BAD BACKPATCH ALIGN
    When backpatching forward references while directly writing out compiled macros to a DLL, a reference to another location in the DLL was not on the correct alignment boundary. Pointers are usually aligned. This is a potential problem. This is an FMP internal warning.
Parent topic: IG- Micro Focus Generator Messages


21004 INVALID MEM MODEL

Memory model specified for creating DLL of compiled macros is neither 16-bit segmented or 32-bit linear model.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21005 ERR OPENING ASM FILE

Error opening .ASM output file to receive the assembler source form of compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21006 ERR WRITING ASM FILE

Error occurred while writing the .ASM output file to receive the assembler source form of compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21007 ERR OPENING DLL FILE

Error opening .DLL output file to directly receive the DLL form of compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21008 ERR WRITING DLL FILE

Error writing the .DLL output file that directly receives the .DLL form of compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21009 ERR OPENING DEF FILE

Error opening .DEF output file to receive the the module definition for creating the DLL form of compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21010 ERR WRITING DEF FILE

Error occurred while writing the .DEF output file to receive the the module definition for creating the DLL form of compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21012 ERR OPENING OUTPUT FILE

Parent topic: 21 - IG-STORE


21013 ERR CLOSING OUTPUT FILE

Error opening or closing an output file that writes out compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21014 BAD INCLUDE MEMBER NAME

Invalid INCLUDE member name provided to the macro compilation process.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21015 ERR INIT OF IRLOCMGR

Error occurred during the initialization of the Internal Representation Location Manager.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21016 MEMBER NAME TOO LONG

Supplied INCLUDE member name is too long.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21017 SAN MBR NAME TOO LONG

Sanitized (refined) INCLUDE member name is too long.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21018 TOO MANY DATA SEG PARTS

The allowed number of data parts/segments used to write the compiled form of a macro has been exceeded. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21019 INVALID DATA SEG PART IX

An internal index into the data parts/segments used to write the compiled form of a macro is out of bounds. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21020 INVALID OPCODE

An operation was encountered that is not known to the compiled macro write routines. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21021 NO MORE FIXUP SORT SLOTS

When sorting fixups by page, location address, and reference address for constructing a DLL for a compiled macro, FMP ran out of slots in the sort table. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21022 LOCATION NOT DEFINED

A compiled macro is a complex data structure with many pointer references to locations (addresses of structures). A reference has been encountered to a location that has never been defined. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21023 INVALID ASM SYMBOL TYPE

When writing out a compiled macro, symbolic names are assigned to each data structure that comprises the compiled macro. A structure of unknown type has been encountered. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21024 DUPLICATE SYMBOL DEFN

When writing out a compiled macro, symbolic names are assigned to each data structure that comprises the compiled macro. A location of a structure has been defined twice. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21025 DLL ENTRYTABLE EXCEEDED

Parent topic: 21 - IG-STORE


21026 DLL FIXUPPAGETABLE EXCEEDED

Parent topic: 21 - IG-STORE


21026 DLL OBJECTPAGETABLE EXCEEDED

Parent topic: 21 - IG-STORE


21027 DLL FIXUPRECORDTABLE EXCEEDED

Parent topic: 21 - IG-STORE


21029 DLL NONRESNAMES EXCEEDED

When writing out a compiled macro as a .DLL, the size of the area allocated for the one of the following tables was exceeded. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Entry Table--A likely cause is too many entry points.
  • Object Page Table
  • Fixup Page Table
  • Fixup Record Table
  • Non Resident Names Table
Parent topic: 21 - IG-STORE


21100 NO ALLOC LOCMGR HASH TAB

Could not allocate memory for the IR Location Manager hash table. This is a memory allocation error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21101 NOT ALL LOC NODES FREED

Upon terminating, the IR Location Manager, not all allocated Location Nodes were freed to the free chain. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21102 UNABLE ALLOC LOC NODE

Unable to allocate memory for an IR Location Node. Location Nodes keep track of addresses in the Intermediate Representation that can be referenced and relocated. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21103 NULL LOC NODE ADDR

Encountered an address of an IR Location Node that is NULL. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21200 UNABLE ALLOC REF NODE

Unable to allocate memory for an IR Reference Node. Reference Nodes keep track of references Locations in the in the Intermediate Representation. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21201 UNABLE CREATE REF NODE

A call to createRefNode was unable to return an IR Reference Node in which to store a reference to an IR Location. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21202 NOT ALL REF NODES FREED

Upon terminating the IR Reference Manager, not all allocated Reference Nodes were freed to the free chain. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21203 NULL REF NODE ADDR

Encountered an address of an IR Reference Node that is NULL. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21300 INVALID DEF QUEUE TYPE

An invalid type of deferred queue was presented to a routine in the Deferred Queue Manager. The Deferred Queue Manager provides queues to defer writing structures out as compiled macros; there is a queue for each structure type. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21301 NO ROOM IN DEF QUEUE

A Deferred Queue Manager queue is full. The Deferred Queue Manager provides queues to defer writing structures out as compiled macros; there is a queue for each structure type. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21400 UNABLE ALLOC DLL WORK

Unable to allocate the work areas for directly writing out a .DLL of compiled macros.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21401 WRONG DATA SEG TYPE16

An a 16-bit data segment was requested for an inappropriate memory model for writing compiled macros to a DLL. 16-bit segments are only for creating a 16-bit segmented memory model DLL. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21402 WRONG DATA PART TYPE32

A 32-bit data part was requested for an inappropriate memory model for writing compiled macros to a DLL. 32-bit data parts are only for creating a 32-bit linear (flat) memory model DLL. For incremental allocation reasons, the single 32-bit logical data object is physically created in incrementally allocated data parts. This is an FMP internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21403 UNABLE ALLOC DLL AREA

Unable to allocate memory for a work area in which to construct the DLL for the non-data portion of a compiled macro. This is a memory allocation error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21404 UNABLE ALLOC DLL DATA AREA

Unable to allocate memory for a work area in which to construct the data part of a DLL for a compiled macro. This is a memory allocation error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21405 UNABLE ALLOC DLL FIXUP REC AREA

Unable to allocate memory for a work area in which to construct the fixup record area for a LX DLL for a compiled macro. This is a memory allocation error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21406 DLL EXCEEDED MAX FIXUPRECORDAREAS

Exceeded the maximum number of fixup record work areas that can be allocated. Work areas are for constructing the fixup record area for an LX DLL for a compiled macro. The limit is set by an internal constant. Try breaking the macro source file into several smaller files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


21407 BAD BACKPATCH ALIGN

When backpatching forward references while directly writing out compiled macros to a DLL, a reference to another location in the DLL was not on the correct alignment boundary. Pointers are usually aligned. This is a potential problem. This is an FMP internal warning.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 21 - IG-STORE


22 - IG-SRVCS

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 22000 INVALID DLL NAME
    The name of the DLL to be loaded is invalid, that is, either null or too long.
  • 22001 ERROR LOADING MODULE
    An error occurred while attempting to load a DLL into memory or to locate a previously loaded DLL.
  • 22002 ERROR QUERY PROC ADDR
    An error occurred while attempting to determine the entry point address of a callable procedure within a module, such as an EXE or a DLL.
  • 22003 ERROR QUERY PROC TYPE
    An error occurred while attempting to determine the entry point type, such as 16 bit or 32-bit calling conventions, of a callable procedure within a module, such as an EXE or a DLL.
  • 22004 ERROR QUERY MOD HANDLE
    An error occurred while attempting to obtain the module handle of a DLL.
  • 22005 ERROR QUERY MOD NAME
    An error occurred while attempting to obtain the module name of a DLL, given its module handle.
  • 22006 ERROR FREEING MODULE
    An error occurred while attempting to free a DLL from memory.
  • 22010 ERR FILE NOT FOUND
    DLL not found in the current directory or libpath if name is unqualified, or in specific directory if name has a path and .DLL extension.
  • 22011 ERR TOO MANY OPEN FILES
    There are not enough file handles.
  • 22012 ERR ACCESS DENIED
    Access denied.
  • 22013 ERR NOT ENOUGH MEMORY
    Not enough memory.
  • 22014 ERR BAD FORMAT
    Bad format. (May not be a DLL.)
  • 22015 ERR NOT DOS DISK
    Unknown media type.
  • 22016 ERR INVALID NAME
    Invalid file system name.
  • 22017 ERR INVALID MODULETYPE
    Invalid module type, such as an EXE that should be a DLL.
  • 22020 ERR INVALID EXE SIGNATURE
    Invalid .DLL signature (e.g., may be a DOS program).
  • 22021 ERR EXE MARKED INVALID
    DLL was marked invalid by the linker.
  • 22022 ERR ITERATED DATA EXCEEDS 64K
    Iterated data in DLL exceeds 64K.
  • 22023 ERR INVALID MINALLOCSIZE
    DLL was built with the wrong MINALLOC size.
  • 22030 ERR INVALID HANDLE
    Invalid module handle. The module handle does not refer to a loaded DLL or EXE module.
  • 22031 ERR INTERRUPT
    Interrupted system call.
  • 22032 ERR PROC NOT FOUND
    Procedure not found in DLL.
  • 22033 ERR ENTRY IS CALLGATE
    Entry point can be accessed via a callgate only.
  • 22034 ERR INVALID PROC NAME
    Name of entry point/procedure is not exported from DLL.
  • 22035 ERR INVALID ORDINAL
    Invalid ordinal of entry point in DLL.
  • 22036 ERR INVALID ACCESS
    Invalid access code.
  • 22037 ERR BAD NAME LENGTH
    Invalid length supplied for buffer area to receive module name.
  • 22050 ERROR WRITING COMPMAC
    An error occurred while attempting to write out a compiled macro as a DLL. Error occurred in routine string. Macro member name = macroname. Output path for compiled macro = pathname. Return code from store = .
  • 22051 ERROR INVALID PROCTYPE
    An error occurred while loading a DLL into memory. The procType (i.e., 16-bit or 32-bit) of a requested entry point within the module was invalid. The routine executing at the time is routinename. The module (i.e., DLL) is modulename. The procedure (i.e., entry point) is entrypointname. The procType of the DLL is /*------ fileio ------*/
  • 22060 FILE NAME TOO LONG
    File name is too long to be a valid file name.
  • 22061 NULL FILE NAME
    A pointer to a file name is NULL.
  • 22062 ERR OPENING FILE
  • 22063 ERR CLOSING FILE
    Error occurred while opening or closing a file.
  • 22080 UNABLE ALLOC MEM
    Unable to allocate memory via direct request to the operating system. Usually due to an invalid request.
  • 22081 NOT ENOUGH MEMORY
    Unable to allocate memory via direct request to the operating system because there is no more memory available. This is a memory allocation error.
  • 22082 UNABLE FREE MEM
    Unable to free memory via direct request to the operating system. Usually due to an invalid request.
  • 22083 MEM ACCESS DENIED
    Unable to free memory via direct request to the operating system because access to the memory was denied. Usually due to an invalid request.
  • 22084 INVALID FREE ADDRESS
    Unable to free memory via direct request to the operating system because the address supplied was not an address that could be freed. Usually due to an invalid request.
  • 22201 ERR ALLOC MEMPAGE FAILED
    No memory is available for a memory page. This is an internal error.
  • 22202 ERR ALLOC MEMORY FAILED
    No memory is available. This is an internal error.
  • 22203 ERR UNABLE TO FREE MEMPAGE
    Memory page is currently active. Unable to free. This is an internal error.
  • 22204 ERR MEMPAGE LIMIT REACHED
    Limit of allocated memory page is reached %u., parm.memPageLimit. This is an internal error.
  • 22205 ERR MEMPAGEINDEX CORRUPTION
  • 22206 ERR MEMINDEX CORRUPTION
    Memory is corrupted. Invalid memory index found. This is an internal error.
  • 22207 ERR MEMCLASS CORRUPTION
    Memory has been corrupted. Invalid memory class found. This is an internal error.
  • 22208 ERR MEMCLASS INVALID
    Memory is corrupted. Memory allocation is requested by class. An invalid memory class has either been requested to be allocated or a block with an invalid memory class has been found. This is an internal error.
  • 22209 ERR MEMPAGE CORRUPTION
    Memory has been corrupted. Memory page pointers are mismatched. This is an internal error.
  • 22210 ERR MEMPAGE NOT INITIALIZED
    Memory page was not initialized. This is an internal error.
  • 22211 ERR MEMPAGE IS ACTIVED
    Memory page is currently active. The memory page was not freed. This is an internal error.
  • 22212 ERR MEMLIST CORRUPTION
    Memory is corrupted. Memory list within the page is corrupted. This is an internal error.
  • 22213 ERR FREEING MEM TWICE
    Attempted to free a block of memory at address addressname with memory class classname twice. This is an internal error. A dump of the block follows this message.
  • 22300 ERR UNABLE QUERY DBCS ENV
    Error getting the country-dependent DBCS environment vector that indicates the range of values for the lead byte of a double byte character. Return code from DosQueryDBCSEnv = returncode.
  • 22301 ERR NLS OPEN FAILED
    Could not open COUNTRY.SYS file.
  • 22302 ERR NLS NO CTRY CODE
    Country code not found. Check to ensure the correct COUNTRY.SYS file is installed on your system.
  • 22303 ERR NLS TABLE TRUNCATED
    The table doesn't contain all the possible lead character ranges because the the program area was not large enough to hold all the ranges. This is an internal error.
  • 22304 ERR NLS TYPE NOT FOUND
    Selected NLS type of information was not found in the COUNTRY.SYS file. This is either an internal error or there is a problem with the COUNTRY.SYS file.
  • 22305 ERR CODE PAGE NOT FOUND
    The code page was not found. Check to ensure the correct COUNTRY.SYS file is installed on your system.
Parent topic: IG- Micro Focus Generator Messages


22000 INVALID DLL NAME

The name of the DLL to be loaded is invalid, that is, either null or too long.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22001 ERROR LOADING MODULE

An error occurred while attempting to load a DLL into memory or to locate a previously loaded DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22002 ERROR QUERY PROC ADDR

An error occurred while attempting to determine the entry point address of a callable procedure within a module, such as an EXE or a DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22003 ERROR QUERY PROC TYPE

An error occurred while attempting to determine the entry point type, such as 16 bit or 32-bit calling conventions, of a callable procedure within a module, such as an EXE or a DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22004 ERROR QUERY MOD HANDLE

An error occurred while attempting to obtain the module handle of a DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22005 ERROR QUERY MOD NAME

An error occurred while attempting to obtain the module name of a DLL, given its module handle.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22006 ERROR FREEING MODULE

An error occurred while attempting to free a DLL from memory.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22010 ERR FILE NOT FOUND

DLL not found in the current directory or libpath if name is unqualified, or in specific directory if name has a path and .DLL extension.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22011 ERR TOO MANY OPEN FILES

There are not enough file handles.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22012 ERR ACCESS DENIED

Access denied.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22013 ERR NOT ENOUGH MEMORY

Not enough memory.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22014 ERR BAD FORMAT

Bad format. (May not be a DLL.)
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22015 ERR NOT DOS DISK

Unknown media type.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22016 ERR INVALID NAME

Invalid file system name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22017 ERR INVALID MODULETYPE

Invalid module type, such as an EXE that should be a DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22020 ERR INVALID EXE SIGNATURE

Invalid .DLL signature (e.g., may be a DOS program).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22021 ERR EXE MARKED INVALID

DLL was marked invalid by the linker.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22022 ERR ITERATED DATA EXCEEDS 64K

Iterated data in DLL exceeds 64K.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22023 ERR INVALID MINALLOCSIZE

DLL was built with the wrong MINALLOC size.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22030 ERR INVALID HANDLE

Invalid module handle. The module handle does not refer to a loaded DLL or EXE module.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22031 ERR INTERRUPT

Interrupted system call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22032 ERR PROC NOT FOUND

Procedure not found in DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22033 ERR ENTRY IS CALLGATE

Entry point can be accessed via a callgate only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22034 ERR INVALID PROC NAME

Name of entry point/procedure is not exported from DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22035 ERR INVALID ORDINAL

Invalid ordinal of entry point in DLL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22036 ERR INVALID ACCESS

Invalid access code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22037 ERR BAD NAME LENGTH

Invalid length supplied for buffer area to receive module name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22050 ERROR WRITING COMPMAC

An error occurred while attempting to write out a compiled macro as a DLL. Error occurred in routine string. Macro member name = macroname. Output path for compiled macro = pathname. Return code from store = .
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22051 ERROR INVALID PROCTYPE

An error occurred while loading a DLL into memory. The procType (i.e., 16-bit or 32-bit) of a requested entry point within the module was invalid. The routine executing at the time is routinename. The module (i.e., DLL) is modulename. The procedure (i.e., entry point) is entrypointname. The procType of the DLL is /*------ fileio ------*/
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22060 FILE NAME TOO LONG

File name is too long to be a valid file name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22061 NULL FILE NAME

A pointer to a file name is NULL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22062 ERR OPENING FILE

Parent topic: 22 - IG-SRVCS


22063 ERR CLOSING FILE

Error occurred while opening or closing a file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22080 UNABLE ALLOC MEM

Unable to allocate memory via direct request to the operating system. Usually due to an invalid request.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22081 NOT ENOUGH MEMORY

Unable to allocate memory via direct request to the operating system because there is no more memory available. This is a memory allocation error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22082 UNABLE FREE MEM

Unable to free memory via direct request to the operating system. Usually due to an invalid request.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22083 MEM ACCESS DENIED

Unable to free memory via direct request to the operating system because access to the memory was denied. Usually due to an invalid request.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22084 INVALID FREE ADDRESS

Unable to free memory via direct request to the operating system because the address supplied was not an address that could be freed. Usually due to an invalid request.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22201 ERR ALLOC MEMPAGE FAILED

No memory is available for a memory page. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22202 ERR ALLOC MEMORY FAILED

No memory is available. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22203 ERR UNABLE TO FREE MEMPAGE

Memory page is currently active. Unable to free. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22204 ERR MEMPAGE LIMIT REACHED

Limit of allocated memory page is reached %u., parm.memPageLimit. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22205 ERR MEMPAGEINDEX CORRUPTION

Parent topic: 22 - IG-SRVCS


22206 ERR MEMINDEX CORRUPTION

Memory is corrupted. Invalid memory index found. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22207 ERR MEMCLASS CORRUPTION

Memory has been corrupted. Invalid memory class found. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22208 ERR MEMCLASS INVALID

Memory is corrupted. Memory allocation is requested by class. An invalid memory class has either been requested to be allocated or a block with an invalid memory class has been found. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22209 ERR MEMPAGE CORRUPTION

Memory has been corrupted. Memory page pointers are mismatched. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22210 ERR MEMPAGE NOT INITIALIZED

Memory page was not initialized. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22211 ERR MEMPAGE IS ACTIVED

Memory page is currently active. The memory page was not freed. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22212 ERR MEMLIST CORRUPTION

Memory is corrupted. Memory list within the page is corrupted. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22213 ERR FREEING MEM TWICE

Attempted to free a block of memory at address addressname with memory class classname twice. This is an internal error. A dump of the block follows this message.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22300 ERR UNABLE QUERY DBCS ENV

Error getting the country-dependent DBCS environment vector that indicates the range of values for the lead byte of a double byte character. Return code from DosQueryDBCSEnv = returncode.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22301 ERR NLS OPEN FAILED

Could not open COUNTRY.SYS file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22302 ERR NLS NO CTRY CODE

Country code not found. Check to ensure the correct COUNTRY.SYS file is installed on your system.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22303 ERR NLS TABLE TRUNCATED

The table doesn't contain all the possible lead character ranges because the the program area was not large enough to hold all the ranges. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22304 ERR NLS TYPE NOT FOUND

Selected NLS type of information was not found in the COUNTRY.SYS file. This is either an internal error or there is a problem with the COUNTRY.SYS file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


22305 ERR CODE PAGE NOT FOUND

The code page was not found. Check to ensure the correct COUNTRY.SYS file is installed on your system.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 22 - IG-SRVCS


23 - IG-VM

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 23000 ERR UNDEFINED VARIABLE
    Undefined variable.
  • 23001 ERR SET KEYWORD NOT IMPL
    % SET function not implemented in this release.
  • 23002 ERR LOOP LIMIT REACHED
    Loop Limit reached. The Loop Limit is a counter established by the programmer to limit the number of executions of each loop construct, for example % R-V or % WHILE. The statement % SET LOOP-LIMIT sets the loop limit value. Use the Loop Limit as a debugging aid to help find infinite loops.
  • 23010 ERR EXCEEDED SUBSCRIPTS
    Subscript limit exceeded for LOOKUP.
  • 23020 ERR SUBMEMBER NOT SUPP
    Conditional 'SUBMEMBER' statement not supported--that is, SUBMEMBER statements under an IF, ELSE-IF, or ELSE. SUBMEMBER statements that delimit the start of a new and separate includable submember are the only valid SUBMEMBER statements. The remaining code in the macro is skipped.
  • 23020 ERR TOO MANY ARGS
    Too many arguments in macro call.
  • 23022 ERR UNDEF SET KEYWORD
    Undefined % SET keyword. The keyword following the word 'SET' is not recognized as one of the valid keywords.
  • 23030 ERR INP FILE NOT FOUND
    Input file not found.
  • 23031 ERR NO FILE NAME
    No input file specified. At least one of the two input files, MAININ and CARDIN, must be specified to supply input to drive the macro processing.
  • 23032 ERR WHILE LOADING DLL
    The expected macro control block was not found in the .DLL file of compiled macros when the .DLL was loaded. This is an internal error.
  • 23033 ERR DLL NOT FOUND
    INCLUDEd .DLL of compiled macros was not found.
  • 23034 ERR BAD INCLUDE MEMBER NAME
    Invalid INCLUDE member name provided to the INCLUDE process.
  • 23035 ERR NO FILE LVL SYM FOR INCL
    Attempted to read a source file was attempted to be read but could not establish an internal symbol for the INCLUDE file. Ensure that the DD name and member name (if any) are composed of characters that form a valid generator symbol name. Special and national characters are not valid.
  • 23036 ERR NO OPEN CODE FOR INCL
    Attempted to read a source file but there was either no 'open code' in the member--the open code is code that is not within a submember or macro define--or there was no code for the submember (if specified).
  • 23037 ERR BAD INCL SYM NAME BUILD
  • 23038 ERR BAD CODE SYM NAME BUILD
    Could not construct a valid internal symbolic name for the INCLUDE file or for the code with an INCLUDE file. Ensure that the DD name, member name (if any) and submember name (if any) are composed of characters that could form a valid generator symbol name. Special and national characters are not valid.
  • 23040 ERR INV REPEAT WHILE
  • 23041 ERR INV REPEAT UNTIL
    Invalid % REPEAT WHILE or UNTIL statement. Missing both blocks. See % REPEAT.
  • 23042 ERR WRONG FILE TYPE
    Attempted to read a file but it was of the wrong type. Only source text files and DLLs of compiled macros can be included using % INCLUDE.
  • 23043 ERR CARDIN NOT FOUND
    The optional CARDIN input file was not found. (Information message only).
  • 23050 ERR UNDEFINED FORMAL ARG
  • 23051 ERR UNDEF VAR IN FARGINIT
    Undefined formal argument or variable in formal argument initialization expression.
  • 23052 ERR UNDEF VAR AT EXEC TIME
    Undefined variable. The variable name is constructed at macro execution time.
  • 23053 ERR FUNC ASSIGNED VALUE
    A built-in function cannot be assigned a value. Function name = .
  • 23054 ERR MACRO OVERIDDEN
    The macroname macro is overridden because it was previously defined.
  • 23055 ERR UNAUTHORIZE DEFINE
    Unauthorized definition of macro macroname. Please contact your administrator for more information.
  • 23060 ERR INV NON NUMERIC TEXT
    In Convtype: Invalid non-numeric text found.
  • 23061 ERR EXEC UNDET FORM
    Op code string represents a source construct form that cannot be determined by the parser. To suppress this message, use the /ERROPT=(NOUNDETF) parameter.
  • 23070 ERR INCOMPAT REL EXPR
    Incompatible expression types are being compared by a relational operator. For example, strings cannot be compared with numbers. Hint: If an operand has no type, it may be an uninitialized formal argument or the name of a built-in function.
  • 23080 ERR SET FATAL
    SET FATAL statement encountered. Processing is terminated as requested.
  • 23090 ERR OP ARG NOT POPCODE
  • 23091 ERR OP ARG NOT PSYMDESC
  • 23092 ERR OP ARG NOT PMCB
  • 23093 ERR OP ARG NOT PTXTOBJ
    The opcode points to an invalid type. Expecting pointer to OPCODE, SYMDESC, MCB, or TXTOBJ. This in an internal error.
  • 23100 ERR DIVIDE BY ZERO
    Attempt to divide by zero. The actual division is bypassed and the result is assigned a large number of the mathematically appropriate sign.
  • 23110 ERR SET STMT NOT IMPL
    SET string is not supported in this release. The statement has no effect. The SET statement is either obsolete or could not be implemented. To suppress this message, use the /ERROPT=(NOUNIMPLSET) parameter.
  • 23120 ERR MISSING DLL CALL PARAM
    The DLL name, the function name, or both are missing for the DLL function call.
  • 23121 ERR TOO MANY DLL ARGS
    Too many arguments are specified in the DLL function call. Only the first number arguments are accepted.
Parent topic: IG- Micro Focus Generator Messages


23000 ERR UNDEFINED VARIABLE

Undefined variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23001 ERR SET KEYWORD NOT IMPL

% SET function not implemented in this release.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23002 ERR LOOP LIMIT REACHED

Loop Limit reached. The Loop Limit is a counter established by the programmer to limit the number of executions of each loop construct, for example % R-V or % WHILE. The statement % SET LOOP-LIMIT sets the loop limit value. Use the Loop Limit as a debugging aid to help find infinite loops.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23010 ERR EXCEEDED SUBSCRIPTS

Subscript limit exceeded for LOOKUP.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23020 ERR SUBMEMBER NOT SUPP

Conditional 'SUBMEMBER' statement not supported--that is, SUBMEMBER statements under an IF, ELSE-IF, or ELSE. SUBMEMBER statements that delimit the start of a new and separate includable submember are the only valid SUBMEMBER statements. The remaining code in the macro is skipped.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23020 ERR TOO MANY ARGS

Too many arguments in macro call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23022 ERR UNDEF SET KEYWORD

Undefined % SET keyword. The keyword following the word 'SET' is not recognized as one of the valid keywords.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23030 ERR INP FILE NOT FOUND

Input file not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23031 ERR NO FILE NAME

No input file specified. At least one of the two input files, MAININ and CARDIN, must be specified to supply input to drive the macro processing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23032 ERR WHILE LOADING DLL

The expected macro control block was not found in the .DLL file of compiled macros when the .DLL was loaded. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23033 ERR DLL NOT FOUND

INCLUDEd .DLL of compiled macros was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23034 ERR BAD INCLUDE MEMBER NAME

Invalid INCLUDE member name provided to the INCLUDE process.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23035 ERR NO FILE LVL SYM FOR INCL

Attempted to read a source file was attempted to be read but could not establish an internal symbol for the INCLUDE file. Ensure that the DD name and member name (if any) are composed of characters that form a valid generator symbol name. Special and national characters are not valid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23036 ERR NO OPEN CODE FOR INCL

Attempted to read a source file but there was either no 'open code' in the member--the open code is code that is not within a submember or macro define--or there was no code for the submember (if specified).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23037 ERR BAD INCL SYM NAME BUILD

Parent topic: 23 - IG-VM


23038 ERR BAD CODE SYM NAME BUILD

Could not construct a valid internal symbolic name for the INCLUDE file or for the code with an INCLUDE file. Ensure that the DD name, member name (if any) and submember name (if any) are composed of characters that could form a valid generator symbol name. Special and national characters are not valid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23040 ERR INV REPEAT WHILE

Parent topic: 23 - IG-VM


23041 ERR INV REPEAT UNTIL

Invalid % REPEAT WHILE or UNTIL statement. Missing both blocks. See % REPEAT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23042 ERR WRONG FILE TYPE

Attempted to read a file but it was of the wrong type. Only source text files and DLLs of compiled macros can be included using % INCLUDE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23043 ERR CARDIN NOT FOUND

The optional CARDIN input file was not found. (Information message only).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23050 ERR UNDEFINED FORMAL ARG

Parent topic: 23 - IG-VM


23051 ERR UNDEF VAR IN FARGINIT

Undefined formal argument or variable in formal argument initialization expression.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23052 ERR UNDEF VAR AT EXEC TIME

Undefined variable. The variable name is constructed at macro execution time.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23053 ERR FUNC ASSIGNED VALUE

A built-in function cannot be assigned a value. Function name = .
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23054 ERR MACRO OVERIDDEN

The macroname macro is overridden because it was previously defined.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23055 ERR UNAUTHORIZE DEFINE

Unauthorized definition of macro macroname. Please contact your administrator for more information.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23060 ERR INV NON NUMERIC TEXT

In Convtype: Invalid non-numeric text found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23061 ERR EXEC UNDET FORM

Op code string represents a source construct form that cannot be determined by the parser. To suppress this message, use the /ERROPT=(NOUNDETF) parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23070 ERR INCOMPAT REL EXPR

Incompatible expression types are being compared by a relational operator. For example, strings cannot be compared with numbers. Hint: If an operand has no type, it may be an uninitialized formal argument or the name of a built-in function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23080 ERR SET FATAL

SET FATAL statement encountered. Processing is terminated as requested.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23090 ERR OP ARG NOT POPCODE

Parent topic: 23 - IG-VM


23091 ERR OP ARG NOT PSYMDESC

Parent topic: 23 - IG-VM


23092 ERR OP ARG NOT PMCB

Parent topic: 23 - IG-VM


23093 ERR OP ARG NOT PTXTOBJ

The opcode points to an invalid type. Expecting pointer to OPCODE, SYMDESC, MCB, or TXTOBJ. This in an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23100 ERR DIVIDE BY ZERO

Attempt to divide by zero. The actual division is bypassed and the result is assigned a large number of the mathematically appropriate sign.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23110 ERR SET STMT NOT IMPL

SET string is not supported in this release. The statement has no effect. The SET statement is either obsolete or could not be implemented. To suppress this message, use the /ERROPT=(NOUNIMPLSET) parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23120 ERR MISSING DLL CALL PARAM

The DLL name, the function name, or both are missing for the DLL function call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


23121 ERR TOO MANY DLL ARGS

Too many arguments are specified in the DLL function call. Only the first number arguments are accepted.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 23 - IG-VM


24 - IG-BUILTIN

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 24000 ERR PARSE TOO MANY ARGS
    &PARSE function processes the first two arguments only.
  • 24001 ERR PARSE NEEDS AN ARG
    &PARSE function needs at least one argument.
  • 24002 ERR SUBSTR TOO MANY ARGS
    &SUBSTR function processes the first three arguments only.
  • 24003 ERR SUBSTR NEEDS TWO ARGS
    &SUBSTR function needs at least two arguments.
  • 24004 ERR DEFINED TOO MANY ARGS
    &DEFINED function processes the first argument only.
  • 24005 ERR DEFINED NEEDS AN ARG
    &DEFINED function needs an argument.
  • 24006 ERR LENGTH TOO MANY ARGS
    &LENGTH function processes the first argument only.
  • 24007 ERR LENGTH NEEDS AN ARG
    &LENGTH function needs an argument.
  • 24008 ERR NUMERIC TOO MANY ARGS
    &NUMERIC function processes the first argument only.
  • 24009 ERR NUMERIC ARG NOT FOUND
  • 24010 ERR NUMERIC NEEDS AN ARG
    &NUMERIC function needs an argument.
  • 24011 ERR INDEX TOO MANY ARGS
    &INDEX function processes the first two arguments only.
  • 24012 ERR INDEX NEEDS TWO ARGS
    &INDEX function needs two arguments.
  • 24013 ERR BUILTIN TOO MANY ARGS
    The built-in function processes the first argument only.
  • 24014 ERR BUILTIN ARG NOT FOUND
    A specified built-in function argument was not obtained. This can occur when an undefined variable was coded as an argument.
  • 24015 ERR BUILTIN NEEDS AN ARG
  • 24016 ERR BUILTIN NEEDS 2 ARGS
  • 24017 ERR BUILTIN NEEDS 3 ARGS
    The built-in function requires more arguments than you supplied.
  • 24018 ERR HEXSTR NOT EVEN DIGITS
    &HEX-AS-STRING expects an even number of hexadecimal digits, since it takes two hex digits to map into a single character.
  • 24019 ERR HEXSTR NEEDS STRING
    &HEX-AS-STRING expects the argument to be of string type.
  • 24020 ERR HEXSIGNED BAD TGT SIZE
    The optional second parameter of &HEX-AS-SIGNED, if supplied, must have the value 1, 2, or 4, specifying whether the sign bit is the leftmost bit of a 8, 16, or 32 bit field.
  • 24021 ERR HEXSIGNED TGT NOT NUM
    The optional second parameter of &HEX-AS-SIGNED, if supplied, must be numeric.
  • 24022 ERR HEXSIGNED STR TOO LONG
    The required first parameter of &HEX-AS-SIGNED, has too many digits to fit in the target size. The target size of 4 bytes means the string cannot have more than 8 hex digits. A 2 byte target means no more than 4 hex digits and a 1 byte target means no more than 2 hex digits.
  • 24023 ERR HEXAS STRING EMPTY
    &HEX-AS-STRING expects a non-empty string.
  • 24024 ERR HEXAS NOT STRING
    The required first parameter of &HEX-AS-SIGNED, must be of type string.
  • 24025 ERR HEXAS STRING NOT HEX
    The required first parameter of &HEX-AS-SIGNED, must contain hexadecimal characters only.
  • 24026 ERR HEXUNSIGNED STR TOO LONG
    The required first parameter of &HEX-AS-UNSIGNED or &HEX-AS-NUMBER, is has too many digits to fit in the target size. A target size of 4 bytes means the string cannot have more than 8 hex digits.
  • 24027 ERR HEXUNSIGNED TOO BIG
    The number represented by the hex string argument of &HEX-AS-UNSIGNED or &HEX-AS-NUMBER is too large to fit in a 31 bit integer. Numbers in FMP are stored as signed 31 bit numbers and there is no 32 bit unsigned integer data type. The number is converted to the equivalent signed value, which is a negative value.
  • 24028 ERR ARG SHOULD BE NUMERIC
  • 24029 ERR ARG SHOULD BE TEXT
    The built-in function requires an argument of numeric type or text/string type.
Parent topic: IG- Micro Focus Generator Messages


24000 ERR PARSE TOO MANY ARGS

&PARSE function processes the first two arguments only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24001 ERR PARSE NEEDS AN ARG

&PARSE function needs at least one argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24002 ERR SUBSTR TOO MANY ARGS

&SUBSTR function processes the first three arguments only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24003 ERR SUBSTR NEEDS TWO ARGS

&SUBSTR function needs at least two arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24004 ERR DEFINED TOO MANY ARGS

&DEFINED function processes the first argument only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24005 ERR DEFINED NEEDS AN ARG

&DEFINED function needs an argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24006 ERR LENGTH TOO MANY ARGS

&LENGTH function processes the first argument only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24007 ERR LENGTH NEEDS AN ARG

&LENGTH function needs an argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24008 ERR NUMERIC TOO MANY ARGS

&NUMERIC function processes the first argument only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24009 ERR NUMERIC ARG NOT FOUND

Parent topic: 24 - IG-BUILTIN


24010 ERR NUMERIC NEEDS AN ARG

&NUMERIC function needs an argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24011 ERR INDEX TOO MANY ARGS

&INDEX function processes the first two arguments only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24012 ERR INDEX NEEDS TWO ARGS

&INDEX function needs two arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24013 ERR BUILTIN TOO MANY ARGS

The built-in function processes the first argument only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24014 ERR BUILTIN ARG NOT FOUND

A specified built-in function argument was not obtained. This can occur when an undefined variable was coded as an argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24015 ERR BUILTIN NEEDS AN ARG

Parent topic: 24 - IG-BUILTIN


24016 ERR BUILTIN NEEDS 2 ARGS

Parent topic: 24 - IG-BUILTIN


24017 ERR BUILTIN NEEDS 3 ARGS

The built-in function requires more arguments than you supplied.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24018 ERR HEXSTR NOT EVEN DIGITS

&HEX-AS-STRING expects an even number of hexadecimal digits, since it takes two hex digits to map into a single character.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24019 ERR HEXSTR NEEDS STRING

&HEX-AS-STRING expects the argument to be of string type.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24020 ERR HEXSIGNED BAD TGT SIZE

The optional second parameter of &HEX-AS-SIGNED, if supplied, must have the value 1, 2, or 4, specifying whether the sign bit is the leftmost bit of a 8, 16, or 32 bit field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24021 ERR HEXSIGNED TGT NOT NUM

The optional second parameter of &HEX-AS-SIGNED, if supplied, must be numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24022 ERR HEXSIGNED STR TOO LONG

The required first parameter of &HEX-AS-SIGNED, has too many digits to fit in the target size. The target size of 4 bytes means the string cannot have more than 8 hex digits. A 2 byte target means no more than 4 hex digits and a 1 byte target means no more than 2 hex digits.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24023 ERR HEXAS STRING EMPTY

&HEX-AS-STRING expects a non-empty string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24024 ERR HEXAS NOT STRING

The required first parameter of &HEX-AS-SIGNED, must be of type string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24025 ERR HEXAS STRING NOT HEX

The required first parameter of &HEX-AS-SIGNED, must contain hexadecimal characters only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24026 ERR HEXUNSIGNED STR TOO LONG

The required first parameter of &HEX-AS-UNSIGNED or &HEX-AS-NUMBER, is has too many digits to fit in the target size. A target size of 4 bytes means the string cannot have more than 8 hex digits.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24027 ERR HEXUNSIGNED TOO BIG

The number represented by the hex string argument of &HEX-AS-UNSIGNED or &HEX-AS-NUMBER is too large to fit in a 31 bit integer. Numbers in FMP are stored as signed 31 bit numbers and there is no 32 bit unsigned integer data type. The number is converted to the equivalent signed value, which is a negative value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


24028 ERR ARG SHOULD BE NUMERIC

Parent topic: 24 - IG-BUILTIN


24029 ERR ARG SHOULD BE TEXT

The built-in function requires an argument of numeric type or text/string type.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 24 - IG-BUILTIN


26 - IG-LEX

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about :

  • 26000 MSG LINE ASSUMED OUTPUT TEXT
    IG determines the overall structure of a line by examining the source before any evaluation bracket processing occurs. This precludes lines that begin with an evaluation bracket expression that resolves to a generator line (e.g., starts with a %%). The following line (line linenumber from source file filename) is assumed to resolve to a text line to be output. Suppress this message with the ERROPT=(NOEVALSTARTLINE) command line parameter.
  • 26001 ERR EXCEED INDENT STACK MAX
    The maximum number of levels of indentation has been exceeded. The maximum number is string. Indentation stack array max reached (in module fmpline.c). Line causing the error is linenumber. This is an internal error.
  • 26002 ERR INDENT STACK UNDERFLOW
    The indentation has been popped more often than pushed. Check your indentation in the source file. Indent stack array underflow (in module fmpline.c). Line causing the error is linenumber. This is an internal error.
  • 26100 ERR SOURCE FILE NOT FOUND
    The % INCLUDEd source file sourcefilename could not be found.
  • 26101 ERR READING SOURCE FILE
    An error occurred reading the % INCLUDEd source file sourcefilename.
Parent topic: IG- Micro Focus Generator Messages


26000 MSG LINE ASSUMED OUTPUT TEXT

IG determines the overall structure of a line by examining the source before any evaluation bracket processing occurs. This precludes lines that begin with an evaluation bracket expression that resolves to a generator line (e.g., starts with a %%). The following line (line linenumber from source file filename) is assumed to resolve to a text line to be output. Suppress this message with the ERROPT=(NOEVALSTARTLINE) command line parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 26 - IG-LEX


26001 ERR EXCEED INDENT STACK MAX

The maximum number of levels of indentation has been exceeded. The maximum number is string. Indentation stack array max reached (in module fmpline.c). Line causing the error is linenumber. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 26 - IG-LEX


26002 ERR INDENT STACK UNDERFLOW

The indentation has been popped more often than pushed. Check your indentation in the source file. Indent stack array underflow (in module fmpline.c). Line causing the error is linenumber. This is an internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 26 - IG-LEX


26100 ERR SOURCE FILE NOT FOUND

The % INCLUDEd source file sourcefilename could not be found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 26 - IG-LEX


26101 ERR READING SOURCE FILE

An error occurred reading the % INCLUDEd source file sourcefilename.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: 26 - IG-LEX


ADB- database messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • ADB-5800-00-F V-ISAM is the only valid DB target for Micro Focus COBOL
    AMB found a DB target other than V-ISAM in the data view for a Micro Focus COBOL program.
  • ADB-5810-00-F VSAM is the only valid DB target for Micro Focus PC-CICS
    AMB found a DB target other than VSAM in the data view for a PC-CICS program.
  • ADB-5820-00-W DLI is only a valid DB target for Micro Focus IMSVS86
    Use DLI only for Micro Focus IMSVS86.
  • ADB-9000-00-E AMB DB error record name unknown to AMB subschema record name
    The record name coded on the database call is either invalid or not defined in the data view.
  • ADB-9010-00-E AMB DB error No arguments passed to DB command
    AMB found a database call coded without keywords.
  • ADB-9020-00-E AMB DB error Cursor was not declared cursor name
    You did not declare the cursor with a correct DB-DECLARE call, or the cursor name is invalid.
  • ADB-9040-00-E AMB DB error DB-FREE command is invalid for IMS and DB2
    You coded a DB-FREE call for an IMS or DB2 database.
  • ADB-9050-00-E AMB DB error First DB command keyword is invalid
    AMB did not recognize the first keyword coded on the database call.
  • ADB-9096-00-E AMB DB error DB-PROCESS-ID has no name
    You did not follow the DB-PROCESS-ID keyword with a unique process ID name.
  • ADB-9097-00-E DB-PROCESS-ID name longer than 18 characters
    The DB-PROCESS-ID name cannot be longer than 18 characters.
  • ADB-9098-00-E Duplicate DB-PROCESS-ID name
    The DB-PROCESS-ID name must be unique.
  • ADB-9099-00-W DB-PROCESS-ID omitted in more than one DB-PROCESS command
    You coded more than one DB-PROCESS call without specifying a DB-PROCESS-ID name. Nested DB-PROCESS calls can yield unpredictable results.
  • ADB-9100-00-F AMB VSAM Version II must be used when mixing VSAM with DB2 or IDMS
    You set &VS-COMMAND-VERSION to I, indicating AMB VSAM VERSION I. You can only mix VERSION I with IMS DB.
Parent topic: AppMaster Builder Error Messages


ADB-5800-00-F V-ISAM is the only valid DB target for Micro Focus COBOL

AMB found a DB target other than V-ISAM in the data view for a Micro Focus COBOL program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: ADB- database messages


ADB-5810-00-F VSAM is the only valid DB target for Micro Focus PC-CICS

AMB found a DB target other than VSAM in the data view for a PC-CICS program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: ADB- database messages


ADB-5820-00-W DLI is only a valid DB target for Micro Focus IMSVS86

Use DLI only for Micro Focus IMSVS86.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: ADB- database messages


ADB-9000-00-E AMB DB error record name unknown to AMB subschema record name

The record name coded on the database call is either invalid or not defined in the data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: ADB- database messages


ADB-9010-00-E AMB DB error No arguments passed to DB command

AMB found a database call coded without keywords.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the database call with the proper keywords.

Parent topic: ADB- database messages


ADB-9020-00-E AMB DB error Cursor was not declared cursor name

You did not declare the cursor with a correct DB-DECLARE call, or the cursor name is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Name the cursor correctly in a DB-DECLARE call.

Parent topic: ADB- database messages


ADB-9040-00-E AMB DB error DB-FREE command is invalid for IMS and DB2

You coded a DB-FREE call for an IMS or DB2 database.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the DB-FREE call for CICS/VSAM only.

Parent topic: ADB- database messages


ADB-9050-00-E AMB DB error First DB command keyword is invalid

AMB did not recognize the first keyword coded on the database call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for misspelling or check the database call in Help for valid keywords.

Parent topic: ADB- database messages


ADB-9096-00-E AMB DB error DB-PROCESS-ID has no name

You did not follow the DB-PROCESS-ID keyword with a unique process ID name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add the DB-PROCESS-ID name to the DB-PROCESS call.

Parent topic: ADB- database messages


ADB-9097-00-E DB-PROCESS-ID name longer than 18 characters

The DB-PROCESS-ID name cannot be longer than 18 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: ADB- database messages


ADB-9098-00-E Duplicate DB-PROCESS-ID name

The DB-PROCESS-ID name must be unique.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add the DB-PROCESS-ID name to the DB-PROCESS call.

Parent topic: ADB- database messages


ADB-9099-00-W DB-PROCESS-ID omitted in more than one DB-PROCESS command

You coded more than one DB-PROCESS call without specifying a DB-PROCESS-ID name. Nested DB-PROCESS calls can yield unpredictable results.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use the DB-PROCESS-ID keyword when nesting DB-PROCESS calls.

Parent topic: ADB- database messages


ADB-9100-00-F AMB VSAM Version II must be used when mixing VSAM with DB2 or IDMS

You set &VS-COMMAND-VERSION to I, indicating AMB VSAM VERSION I. You can only mix VERSION I with IMS DB.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use AMB VSAM VERSION II. Set &VS-COMMAND-VERSION to II.

Parent topic: ADB- database messages


AFE- field edit messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • AFE-1000-00-E AMB edits error - application edit call undefined
    You did not specify the application edit call for your application.
  • AFE-1010-01-E Bypass edit keys CLEAR PA1 PA2 Invalid for DC target IMS
    The IMS environment does not use these keys.
Parent topic: AppMaster Builder Error Messages


AFE-1000-00-E AMB edits error - application edit call undefined

You did not specify the application edit call for your application.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling of the call name and make sure that the call exists.

Parent topic: AFE- field edit messages


AFE-1010-01-E Bypass edit keys CLEAR PA1 PA2 Invalid for DC target IMS

The IMS environment does not use these keys.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: AFE- field edit messages


APX- Online Express messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • APX-1020-01-W Program does not contain appropriate modifiable express PCB for error response Error after DB update will result in ROLB and no response to terminal user possible
    Caused when the following conditions are all met:
  • APX-1030-01-E Input screen uses PFKEYS for TRAN PX specs Assume PFKEYS available Correct conflict
    On an IMS input screen, the PF keys were defined to provide all or part of the IMS trancode. The program cannot test PF keys after its screen is received. If the Express program definition associates program functions with PF keys, the program will not function as intended. This message does not necessarily mean that such a conflict exists, but is a warning that PF keys will not be available for testing during program execution.
  • APX-1040-00-E TP-USER-LEN too small for SAVEKEY and additional COMMAREA
    This message is generated from the $PX-CA-COMPUTE-LEN call if a Commarea length was defined via symbol &TP-USER-LEN, and the length specified is less than the sum of SAVEKEY length assigned to Commarea plus additional Commarea bytes, as defined on the Work Area Definition window.
Parent topic: AppMaster Builder Error Messages


APX-1020-01-W Program does not contain appropriate modifiable express PCB for error response Error after DB update will result in ROLB and no response to terminal user possible

Caused when the following conditions are all met:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. The program performs database updates
  2. The DC target is IMS
  3. The PSB does not provide an EXPRESS PCB that may be used for responding to the originating LTERM.

If error occurs after successful updates, AMB sends the screen and error message via an EXPRESS PCB and terminates the program with a ROLB call. If an appropriate EXPRESS PCB is not available, the program terminates without responding.

Resolution:

Add an EXPRESS PCB and recompile program, or accept that in some error situations, no response to the terminal is possible. If the program performs only one update in a single execution, ignore this message.

Note: In conversational programs, be sure your alternate IO PCB contains the parameters EXPRESS=YES, MODIFY=YES, and ALTRESP=YES.
Parent topic: APX- Online Express messages


APX-1030-01-E Input screen uses PFKEYS for TRAN PX specs Assume PFKEYS available Correct conflict

On an IMS input screen, the PF keys were defined to provide all or part of the IMS trancode. The program cannot test PF keys after its screen is received. If the Express program definition associates program functions with PF keys, the program will not function as intended. This message does not necessarily mean that such a conflict exists, but is a warning that PF keys will not be available for testing during program execution.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify that program functions were not associated with PF keys. If they have, disassociate them.

Parent topic: APX- Online Express messages


APX-1040-00-E TP-USER-LEN too small for SAVEKEY and additional COMMAREA

This message is generated from the $PX-CA-COMPUTE-LEN call if a Commarea length was defined via symbol &TP-USER-LEN, and the length specified is less than the sum of SAVEKEY length assigned to Commarea plus additional Commarea bytes, as defined on the Work Area Definition window.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Increase Commarea length defined by &TP-USER-LEN. Or, decrease Commarea requirements defined to Online Express by not using Commarea for SAVEKEY or by reducing the specification for additional Commarea bytes.

Parent topic: APX- Online Express messages


BTC- batch call messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • BTC-1000-00-W TP command invoked in MVS batch program
    A non-IMS batch program invoked a TP call. This may also cause the warning that AMB set the TP-GOBACK flag to false.
  • BTC-2020-00-E Unknown keyword
    The parameter coded with TP-BACKOUT is invalid.
  • BTC-8010-00-F APBTCTP included twice in your program
Parent topic: AppMaster Builder Error Messages


BTC-1000-00-W TP command invoked in MVS batch program

A non-IMS batch program invoked a TP call. This may also cause the warning that AMB set the TP-GOBACK flag to false.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Invoke TP calls only in programs with $TP-ENTRY coded.

Parent topic: BTC- batch call messages


BTC-2020-00-E Unknown keyword

The parameter coded with TP-BACKOUT is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The only valid keywords for this call are ABORT or NOABORT.

Parent topic: BTC- batch call messages


BTC-8010-00-F APBTCTP included twice in your program

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra INCLUDE.

Parent topic: BTC- batch call messages


CB2- COBOL messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • CB2-1000-00-W Too many arguments in paragraph
    You specified too many arguments after a paragraph. The size of the buffer that stores these arguments depends on the memory available at execution time.
  • CB2-1001-00-F Error obtaining arguments
    This error occurs when parsing the call argument under the DOS prompt.
  • CB2-1002-00-E Opening
    Cannot open the file.
  • CB2-1003-00-E First pass failed unable to continue
    This error occurs while parsing the program in the first pass.
  • CB2-1010-00-W Found unexpected division on line
    AMB found a division at the wrong place in the program.
  • CB2-1100-00-E Searching for paragraph header
    Found a paragraph header specified in COBOL region B.
  • CB2-1201-00-E Block stack underflow
    AMB found an extra end of block statement.
  • CB2-1202-00-E File identifier stack underflow
    Internal error.
  • CB2-1203-00-E Repeat stack underflow
    Internal error.
  • CB2-1204-00-E Statement stack underflow
    Internal error.
  • CB2-1300-00-E Unable to translate index initialization in REPEAT VARYING
    This error occurs when you use an index on a FROM clause in a REPEAT VARYING statement with a complex expression.
  • CB2-1301-00-E Cannot find beginning of statement
    AMB could not recognize the beginning of the statement.
  • CB2-1302-00-E Invalid literal continuation on line linenumber
    Invalid continuation syntax.
  • CB2-1303-00-E Unable to translate INDEX INCREMENT-DECREMENT on line
    Syntax for INDEX INCREMENT/DECREMENT is incorrect or too complex. AMB expects a plus or minus sign for the INDEX INCREMENT or DECREMENT statement.
  • CB2-1304-00-E COPY statement does not end with a period on line linenumber
    The COPY statement found on the referenced line number is missing a period (.) at the end.
  • CB2-1308-00-E Improper S-Cobol continuation on line linenumber
    AMB found a partial ellipses (i.e., only two dots) at the beginning of a line.
  • CB2-1400-00-W Ambiguous UNTIL after PERFORM on line
    AMB found an UNTIL verb at the beginning of a statement following a complete PERFORM statement.
  • CB2-1401-00-W Ambiguous indent on line column
    AMB found a verb at the beginning of a statement indented under a following statement that could have an exception clause such as ADD, COMPUTE, etc.
  • CB2-1402-00-W Ambiguous outdent on line column
    AMB found a verb at the beginning of a statement that could end the indentation of the previous statement.
  • CB2-1403-00-W Ambiguous ELSE after statement on line column
    An ELSE was found after a nested IF statement that belongs to the outer IF statement with the same indentation.
  • CB2-1500-00-E EVALUATE or SEARCH was terminated when encountered on line
    A WHEN statement found after an EVALUATE statement was previously terminated either by indentation or an END-EVALUATE statement.
  • CB2-1999-00-E Found unexpected on line
    Grammatical or syntax error found.
  • CB2-2000-00-F Token buffer capacity of exceeded
    Internal error. Tokens including white spaces cannot exceed 4094 bytes.
  • CB2-2001-00-E Encountered EOF before last character
    AMB found an end of file marker before collecting all characters for a token, for example, an alpha-numeric literal.
  • CB2-2002-00-E Installing entry point
    Internal error.
  • CB2-2003-00-S Found unhandled state caused by internal error
    Internal error.
Parent topic: AppMaster Builder Error Messages


CB2-1000-00-W Too many arguments in paragraph

You specified too many arguments after a paragraph. The size of the buffer that stores these arguments depends on the memory available at execution time.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for the available memory or missing right parenthesis.

Parent topic: CB2- COBOL messages


CB2-1001-00-F Error obtaining arguments

This error occurs when parsing the call argument under the DOS prompt.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for the invalid parameter. If the call line is too long, use the control file instead.

Parent topic: CB2- COBOL messages


CB2-1002-00-E Opening

Cannot open the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for the attributes and the existence of the file.

Parent topic: CB2- COBOL messages


CB2-1003-00-E First pass failed unable to continue

This error occurs while parsing the program in the first pass.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check spelling of Division, syntax of TRUE and FALSE statements and the format of paragraph header with arguments list.

Parent topic: CB2- COBOL messages


CB2-1010-00-W Found unexpected division on line

AMB found a division at the wrong place in the program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for the order of all COBOL divisions coded.

Parent topic: CB2- COBOL messages


CB2-1100-00-E Searching for paragraph header

Found a paragraph header specified in COBOL region B.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for invalid placement of the period.

Parent topic: CB2- COBOL messages


CB2-1201-00-E Block stack underflow

AMB found an extra end of block statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for the extra end of block statement such as END-IF, END-PERFORM, ...

Parent topic: CB2- COBOL messages


CB2-1202-00-E File identifier stack underflow

Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: CB2- COBOL messages


CB2-1203-00-E Repeat stack underflow

Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: CB2- COBOL messages


CB2-1204-00-E Statement stack underflow

Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: CB2- COBOL messages


CB2-1300-00-E Unable to translate index initialization in REPEAT VARYING

This error occurs when you use an index on a FROM clause in a REPEAT VARYING statement with a complex expression.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Break up the complex expression to multiple SET index UP/DOWN statements.

Parent topic: CB2- COBOL messages


CB2-1301-00-E Cannot find beginning of statement

AMB could not recognize the beginning of the statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CB2- COBOL messages


CB2-1302-00-E Invalid literal continuation on line linenumber

Invalid continuation syntax.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CB2- COBOL messages


CB2-1303-00-E Unable to translate INDEX INCREMENT-DECREMENT on line

Syntax for INDEX INCREMENT/DECREMENT is incorrect or too complex. AMB expects a plus or minus sign for the INDEX INCREMENT or DECREMENT statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CB2- COBOL messages


CB2-1304-00-E COPY statement does not end with a period on line linenumber

The COPY statement found on the referenced line number is missing a period (.) at the end.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add a period (.) to the end of the COPY statement on the referenced line.

Parent topic: CB2- COBOL messages


CB2-1308-00-E Improper S-Cobol continuation on line linenumber

AMB found a partial ellipses (i.e., only two dots) at the beginning of a line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add a dot at the beginning of the affected line to complete the ellipses (three dots total).

Parent topic: CB2- COBOL messages


CB2-1400-00-W Ambiguous UNTIL after PERFORM on line

AMB found an UNTIL verb at the beginning of a statement following a complete PERFORM statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Move the UNTIL to the end of the previous line or use ellipses '...' to continue the PERFORM statement.

Parent topic: CB2- COBOL messages


CB2-1401-00-W Ambiguous indent on line column

AMB found a verb at the beginning of a statement indented under a following statement that could have an exception clause such as ADD, COMPUTE, etc.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If you indented the statement for the exception clause, no action is required. Otherwise, change the indentation to line up with the previous statement.

Parent topic: CB2- COBOL messages


CB2-1402-00-W Ambiguous outdent on line column

AMB found a verb at the beginning of a statement that could end the indentation of the previous statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If the statement should end the exception clause, no action required. Otherwise fix the indentation to line up with the previous statement.

Parent topic: CB2- COBOL messages


CB2-1403-00-W Ambiguous ELSE after statement on line column

An ELSE was found after a nested IF statement that belongs to the outer IF statement with the same indentation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If the indentation is correct, no action is required. Otherwise change the indentation to line up with the correct IF statement or code an END-IF statement.

Parent topic: CB2- COBOL messages


CB2-1500-00-E EVALUATE or SEARCH was terminated when encountered on line

A WHEN statement found after an EVALUATE statement was previously terminated either by indentation or an END-EVALUATE statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Move the WHEN statement and statement block before the END-EVALUATE statement or fix the indentation to line up under the EVALUATE statement.

Parent topic: CB2- COBOL messages


CB2-1999-00-E Found unexpected on line

Grammatical or syntax error found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check your AMB and COBOL syntax.

Parent topic: CB2- COBOL messages


CB2-2000-00-F Token buffer capacity of exceeded

Internal error. Tokens including white spaces cannot exceed 4094 bytes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: CB2- COBOL messages


CB2-2001-00-E Encountered EOF before last character

AMB found an end of file marker before collecting all characters for a token, for example, an alpha-numeric literal.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for a missing quote at the end of the program or an end of file marker in a string.

Parent topic: CB2- COBOL messages


CB2-2002-00-E Installing entry point

Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: CB2- COBOL messages


CB2-2003-00-S Found unhandled state caused by internal error

Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: CB2- COBOL messages


CIC- CICS messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • CIC-1010-00-E 1070-00-E Required screen name(s) not supplied
    Enter the screen(s) name as the first argument in the call.
  • CIC-1020-00-E CIC-1100-00-E CIC-1170-00-E Option Parameter is not allowed
    This option does not expect any parameters.
  • CIC-1030-00-E Option Required parameter was not supplied
    Option specified without its required parameter.
  • CIC-1040-00-E Option Option is unknown by this command
    Option misspelled or unknown by call.
  • CIC-1050-00-E CIC-1060-00-E Required program name not supplied
  • CIC-1070-00-E 1010-00-E At least one screen must be specified
    Enter the screen(s) name as the first argument in the call.
  • CIC-1100-00-E CIC-1020-00-E CIC-1170-00-E Option Parameter is not allowed
    This option does not expect any parameters.
  • CIC-1110-00-E CIC-1120-00-E Required options were not supplied
    Options required by call missing.
  • CIC-1140-00-E CIC-1150-00-E CIC-1180-00-E Option optionname Option is unknown by this command
    Option misspelled or unknown by call.
  • CIC-1160-00-E Option optionname Invalid parameter for this option
    Parameter syntax is incorrect.
  • CIC-1170-00-E CIC-1020-00-E CIC-1100-00-E Option Parameter is not allowed
    This option does not expect any parameters.
  • CIC-1180-00-E CIC-1140-00-E CIC-1150-00-E Option optionname Option is unknown by this command
    Option misspelled or unknown by call.
  • CIC-1200-00-E Screen screenname field fieldname
    Required subscript missing for field. An attributed field within a repeated block is missing a subscript.
  • CIC-1210-00-E Screen field Subscript invalid on non-repeating field
    An attributed field coded with a subscript is not part of a repeated block.
  • CIC-1220-00-E Screen screenname field fieldname
    Field is not defined or invalid for this screen.
  • CIC-1230-00-E Screen combination of attributes Invalid combination of attributes
  • CIC-1240-00-E Screen Attribute not recognized
    Check the spelling of the attribute.
  • CIC-1250-00-E Screen Required field name(s) not supplied
    Code one or more field names.
  • CIC-1260-00-E Screen Required field attribute(s) not supplied
    Specify one or more attributes.
  • CIC-1270-00-E Required paragraph name not supplied
    Specify a paragraph name with this call.
  • CIC-1280-00-E Screen Extended attributes are not allowed
    You coded an extended attribute for a screen that allows only common attributes.
  • CIC-1290-00-E Program Program name must be 8 characters or less
    Change the program name to eight characters or fewer.
  • CIC-1300-00-E Data name Data name must be 30 characters or less
    This is a COBOL limitation.
  • CIC-1310-00-E LENGTH option is missing
    LENGTH option required when the COMMAREA option specified.
  • CIC-1320-00-E Option option LENGTH parameter is missing
    You coded the LENGTH option without its required parameter.
  • CIC-1330-00-E COMMAREA option is missing
    COMMAREA option is required when LENGTH option specified.
  • CIC-1340-00-E Option option COMMAREA parameter is missing
    You coded the COMMAREA option without its required parameter.
  • CIC-1350-00-E Option option COMMAREA option is invalid in call
    COMMAREA is valid only when linking to non-AMB programs.
  • CIC-1360-00-E Option option LENGTH option is invalid in call
    LENGTH option is valid only when linking to non-AMB programs.
  • CIC-1370-00-E OPTION option NOCA option is invalid in call
    NOCA option is valid only when linking to non-AMB programs.
  • CIC-2010-00-E TP-ADDR-MAX must be increased to accommodate data areas being passed
    TP-ADDR table is not large enough to hold the addresses of all the linkage areas specified.
  • CIC-2020-00-E CIC-SERVICE-RELOAD may not be used in non-OS-VS COBOL programs
    The non-OS/VS COBOL compiler does not allow service reloads.
  • CIC-3010-00-E Record name Record name must be defined to AMB
    You must specify linkage records in the TP-LINKAGE or SCRNLIST calls.
  • CIC-4010-00-I TP-USER-LEN TP-USER-LEN set to default value
    AMB found &TP-USER-LEN undefined; value set to default.
  • CIC-4020-00-I Record name copybook was not specified Record assumed coded inline
    You did not provide a COPY/INCLUDE member name. AMB assumes record coded is inline following this call.
  • CIC-4030-00-I CIC-LINKAGE macro no longer supported
    AMB no longer supports the CIC-LINKAGE call.
  • CIC-4050-00-I TP-ADDR-MAX &ampTP-ADDR-MAX set to default value
    &TP-ADDR-MAX is undefined. AMB sets the value to default.
  • CIC-5010-00-W Option Option is not supported by Micro Focus PC-CICS
    This is a valid CICS option but the Micro Focus PC-CICS product does not currently support it.
  • CIC-5020-00-E Command Command is not supported by Micro Focus PC-CICS
    This is a valid CICS call but it is not currently supported by the Micro Focus PC-CICS
  • CIC-5800-00-F AMB module APMFCSTP has been included twice
  • CIC-8020-00-F AMB module APCICSTP has been included twice
  • CIC-8020-00-F AMB module APCICSTP has been included twice
    Remove the extra INCLUDE in your program.
Parent topic: AppMaster Builder Error Messages


CIC-1010-00-E 1070-00-E Required screen name(s) not supplied

Enter the screen(s) name as the first argument in the call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1020-00-E CIC-1100-00-E CIC-1170-00-E Option Parameter is not allowed

This option does not expect any parameters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Remove parameter from option.

Parent topic: CIC- CICS messages


CIC-1030-00-E Option Required parameter was not supplied

Option specified without its required parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Enter required parameter with option.

Parent topic: CIC- CICS messages


CIC-1040-00-E Option Option is unknown by this command

Option misspelled or unknown by call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Verify the spelling or validity of entered option.

Parent topic: CIC- CICS messages


CIC-1050-00-E CIC-1060-00-E Required program name not supplied

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Enter the program name as the first argument in the call.

Parent topic: CIC- CICS messages


CIC-1070-00-E 1010-00-E At least one screen must be specified

Enter the screen(s) name as the first argument in the call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1100-00-E CIC-1020-00-E CIC-1170-00-E Option Parameter is not allowed

This option does not expect any parameters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Remove parameter from option.

Parent topic: CIC- CICS messages


CIC-1110-00-E CIC-1120-00-E Required options were not supplied

Options required by call missing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1140-00-E CIC-1150-00-E CIC-1180-00-E Option optionname Option is unknown by this command

Option misspelled or unknown by call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1160-00-E Option optionname Invalid parameter for this option

Parameter syntax is incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: CIC- CICS messages


CIC-1170-00-E CIC-1020-00-E CIC-1100-00-E Option Parameter is not allowed

This option does not expect any parameters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Remove parameter from option.

Parent topic: CIC- CICS messages


CIC-1180-00-E CIC-1140-00-E CIC-1150-00-E Option optionname Option is unknown by this command

Option misspelled or unknown by call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1200-00-E Screen screenname field fieldname

Required subscript missing for field. An attributed field within a repeated block is missing a subscript.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1210-00-E Screen field Subscript invalid on non-repeating field

An attributed field coded with a subscript is not part of a repeated block.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the subscript.

Parent topic: CIC- CICS messages


CIC-1220-00-E Screen screenname field fieldname

Field is not defined or invalid for this screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check spelling.

Parent topic: CIC- CICS messages


CIC-1230-00-E Screen combination of attributes Invalid combination of attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify and remove conflicting attributes.

Parent topic: CIC- CICS messages


CIC-1240-00-E Screen Attribute not recognized

Check the spelling of the attribute.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: CIC- CICS messages


CIC-1250-00-E Screen Required field name(s) not supplied

Code one or more field names.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: CIC- CICS messages


CIC-1260-00-E Screen Required field attribute(s) not supplied

Specify one or more attributes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: CIC- CICS messages


CIC-1270-00-E Required paragraph name not supplied

Specify a paragraph name with this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1280-00-E Screen Extended attributes are not allowed

You coded an extended attribute for a screen that allows only common attributes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1290-00-E Program Program name must be 8 characters or less

Change the program name to eight characters or fewer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1300-00-E Data name Data name must be 30 characters or less

This is a COBOL limitation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1310-00-E LENGTH option is missing

LENGTH option required when the COMMAREA option specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1320-00-E Option option LENGTH parameter is missing

You coded the LENGTH option without its required parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1330-00-E COMMAREA option is missing

COMMAREA option is required when LENGTH option specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1340-00-E Option option COMMAREA parameter is missing

You coded the COMMAREA option without its required parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1350-00-E Option option COMMAREA option is invalid in call

COMMAREA is valid only when linking to non-AMB programs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1360-00-E Option option LENGTH option is invalid in call

LENGTH option is valid only when linking to non-AMB programs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-1370-00-E OPTION option NOCA option is invalid in call

NOCA option is valid only when linking to non-AMB programs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-2010-00-E TP-ADDR-MAX must be increased to accommodate data areas being passed

TP-ADDR table is not large enough to hold the addresses of all the linkage areas specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Increase value assigned to &RTP-ADDR-MAX.

Parent topic: CIC- CICS messages


CIC-2020-00-E CIC-SERVICE-RELOAD may not be used in non-OS-VS COBOL programs

The non-OS/VS COBOL compiler does not allow service reloads.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


CIC-3010-00-E Record name Record name must be defined to AMB

You must specify linkage records in the TP-LINKAGE or SCRNLIST calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Enter the record name as an argument to TP-LINKAGE.

Parent topic: CIC- CICS messages


CIC-4010-00-I TP-USER-LEN TP-USER-LEN set to default value

AMB found &TP-USER-LEN undefined; value set to default.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The default is 80 but you may override this value.

Parent topic: CIC- CICS messages


CIC-4020-00-I Record name copybook was not specified Record assumed coded inline

You did not provide a COPY/INCLUDE member name. AMB assumes record coded is inline following this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: CIC- CICS messages


CIC-4030-00-I CIC-LINKAGE macro no longer supported

AMB no longer supports the CIC-LINKAGE call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The TP-LINKAGE call replaces the CIC-LINKAGE call.

Parent topic: CIC- CICS messages


CIC-4050-00-I TP-ADDR-MAX &ampTP-ADDR-MAX set to default value

&TP-ADDR-MAX is undefined. AMB sets the value to default.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The default value is 20 but you may override this value.

Parent topic: CIC- CICS messages


CIC-5010-00-W Option Option is not supported by Micro Focus PC-CICS

This is a valid CICS option but the Micro Focus PC-CICS product does not currently support it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No action is necessary, or, you can remove the option.

Parent topic: CIC- CICS messages


CIC-5020-00-E Command Command is not supported by Micro Focus PC-CICS

This is a valid CICS call but it is not currently supported by the Micro Focus PC-CICS
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the call.

Parent topic: CIC- CICS messages


CIC-5800-00-F AMB module APMFCSTP has been included twice

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra INCLUDE in your program.

Parent topic: CIC- CICS messages


CIC-8020-00-F AMB module APCICSTP has been included twice

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra INCLUDE in your program.

Parent topic: CIC- CICS messages


CIC-8020-00-F AMB module APCICSTP has been included twice

Remove the extra INCLUDE in your program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: CIC- CICS messages


DB2- SQL messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • DB2-1001-00-E Not a valid column name
    The named column does not belong to the table.
  • DB2-1002-00-W Cursor not declared
  • DB2-1003-00-E Not WHERE or NOWHERE or NULL keyword
    Invalid call keyword.
  • DB2-1004-00-W This statement will modify an entire table
    DB-MODIFY call updates the entire table.
  • DB2-1005-00-E No record name defined
    You did not specify the record name in the call.
  • DB2-1006-00-E COLUMN not inserted and declared not null
    The specified column name is not inserted but declared not null.
  • DB2-1007-00-E WHERE not allowed on STORE
    AMB does not allow the WHERE keyword in a DB-STORE call.
  • DB2-1008-00-W This statement will erase an entire table
    AMB will delete all rows in the table.
  • DB2-1009-00-W Cursor not declared
    You did not declare the cursor name.
  • DB2-1010-00-E No column names allowed on ERASE
    It is Invalid to delete a column.
  • DB2-1011-00-W OBTAIN needs a WHERE clause or it can retrieve multiple rows
    The coded call may retrieve multiple rows.
  • DB2-1012-00-E CANNOT OBTAIN WHERE CURRENT NEED CURSOR AND FETCH
    Keyword WHERE CURRENT invalid in DB-OBTAIN call.
  • DB2-1013-00-E Declare cursor more than once
    The named cursor already used.
  • DB2-1014-00-E Command cannot have WHERE CURRENT OF
    Do not use WHERE CURRENT OF with this call.
  • DB2-1015-00-E No cursor name defined
    Code cursor name for this call.
  • DB2-1016-00-E Keyword not allowed as record name
    Keyword is already used as record name. Code a record name instead of a keyword in the call.
  • DB2-1017-00-E UPDATE specified but no column name follows keyword
    Enter column name after keyword UPDATE or remove empty UPDATE from the call.
  • DB2-1018-00-E Parameter not WHERE or NULL or NOWHERE or UPDATE or ORDER
    Invalid parameter.
  • DB2-1019-00-E Invalid column name after UPDATE
    The named column in UPDATE clause does not belong to the table.
  • DB2-1020-00-F Name not found in DDISYMB
    The specified record name not found in DDISYMB.
  • DB2-1021-00-E WHERE search condition not found
    Enter a search condition in the WHERE clause, or remove the empty WHERE.
  • DB2-1022-00-E FROM not allowed with
    Do not use the FROM keyword with this call.
  • DB2-1023-00-E INTO not allowed with
    Do not use the INTO keyword with this call.
  • DB2-1024-00-E DB-PROCESS-ID is valid only with the DB-PROCESS call
  • DB2-1025-00-E ORDER specified but no column name follows keyword
  • DB2-1026-00-E Invalid column name after ORDER
    AMB could not find the named column in ORDER clause in the result table.
  • DB2-1027-00-E Cannot have UPDATE and ORDER in same cursor declaration
    Code UPDATE or ORDER in a single cursor declaration.
  • DB2-1028-00-I Column name specified in the UPDATE clause will be updated
    AMB will update the named column in UPDATE clause.
  • DB2-1029-00-E INTO or FROM keyword has no structure name
    Code the structure name after FROM or INTO.
  • DB2-1030-00-E DB-PROCESS-ID keyword has no ID name following it
  • DB2-1031-00-E Found more than once in command
    Remove the extra keyword.
  • DB2-1032-00-E END or ENDWHERE specified and had no WHERE clause
  • DB2-1033-00-E Keyword only valid for DB-PROCESS and DB-DECLARE
  • DB2-1034-00-E WHERE clause found after END or ENDWHERE
    Check for a valid WHERE clause.
  • DB2-1035-00-E NOWHERE clause specified and there is a WHERE clause
    Cannot use NOWHERE or WHERE in the same call.
  • DB2-1036-00-E NOWHERE clause specified and there is an END or ENDWHERE
    END or ENDWHERE are invalid for NOWHERE.
  • DB2-1037-00-E When WHERE clause is present UPDATE or ORDER must follow after
    Found WHERE after UPDATE or ORDER.
  • DB2-1038-00-E Cannot have CURRENT keyword with a NOWHERE clause
    CURRENT is invalid in a NOWHERE clause.
  • DB2-1039-00-E Found CURRENT keyword before finding WHERE clause
    CURRENT valid only with WHERE (WHERE CURRENT OF).
  • DB2-1040-00-E Invalid use of WHERESQL with CURRENT
    You used WHERESQL CURRENT OF instead of WHERE CURRENT OF.
  • DB2-1042-00-E CURSOR longer than 12 characters
    The named cursor is longer than the maximum length of 12 characters.
  • DB2-1043-00-E -ID name longer than 10 characters
  • DB2-1045-00-E Individual cols and builtin functions should not be mixed
    Do not select individual columns in a query if also using a built-in function.
  • DB2-1046-00-E Syntax invalid for SELECT DISTINCT
    You either used the keyword DISTINCT more than once in a subselect, or it you did not place it directly before the column select list.
  • DB2-1047-00-E Not a valid built-in function
    You coded a built-in function other than MAX, MIN, AVG, SUM or COUNT.
  • DB2-1048-00-E DISTINCT modifier required for COUNT
    Syntax for the built-in function COUNT requires the keyword DISTINCT.
  • DB2-1049-00-E Invalid function argument -
    The argument given in a function is not a valid data type for that function.
  • DB2-1050-00-E Cannot return result -
    AMB cannot determine the result field for a function.
  • DB2-1051-00-E Cannot create function result -
    Something other than Y or N specified for the CREATE RESULT field indicator.
  • DB2-1052-00-E Invalid use of DB-LOOP-MAX keyword
    DB-LOOP-MAX is valid for DB-PROCESS calls only. You included DB-LOOP-MAX included in a call other than a DB-PROCESS.
  • DB2-1053-00-E Invalid use of UNION keyword
    The following conditions can cause this message:
  • DB2-1054-00-E UNION select list incompatible
    The select lists of each query in a UNION are not the same length.
  • DB2-1055-00-E Data type of column in function cannot be found - regen subschema
    To process SQL functions, AMB SQL needs data type information for each column. The current data view does not contain data type information for all columns.
  • DB2-1056-00-E Indicator structure not found for CURSOR
    A fatal error occurred as a DB-MODIFY call processed either the cursor or the indicator structure for the cursor.
  • DB2-1057-00-E Indicator structure not found for TABLE
    A fatal error occurred in processing the indicator structure for the named table.
  • DB2-1058-00-E INSERT table cannot be the same as SUBSELECT table
    You named the table or view into which data is being inserted by a DB-STORE as the source from where a subselect is drawing that data. The object of an insert cannot be the same as the object of the subselect.
  • DB2-1059-00-E Columns in SUBSELECT result table do not match insert column list
    Select lists for insert and subselect are not the same length.
  • DB2-1060-00-E GROUP BY specified but no column name follows keyword
    No column name given after the GROUP keyword.
  • DB2-1061-00-E Invalid column name after GROUP
    AMB could not find a column named in the GROUP BY clause in the SELECT list.
  • DB2-1062-00-E Different location names seen in UNION
    You cannot execute a UNION of tables from two or more different locations. Refer only to tables in the same location.
  • DB2-1063-00-E Different location names seen in Join
    You cannot Join tables from two or more different locations. Refer only to tables in the same location.
  • DB2-1064-00-E Cannot INSERT DELETE or UPDATE from remote location if using CICS or IMS
    When accessing remote tables or views via the CICS or IMS/VS attachment facility, you cannot use INSERT, DELETE, or UPDATE statements.
  • DB2-1065-00-E DISTINCT invalid or used more than once in a statement
    Either the DISTINCT keyword is invalid as used, or it appears more than once in a statement.
  • DB2-1066-00-E COMMIT-ROLLBACK not supported in non-ISPF environment
    You attempted to use the DB-COMMIT call in a CICS or IMS program.
  • DB2-1067-00-E COMMIT with HOLD parameter not supported unless using SQL-400
    When coding a DB-COMMIT, do not code the HOLD parameter unless the SQL target is SQL/400.
  • DB2-1068-00-E Invalid parameter specified for command
  • DB2-1069-00-E WITH HOLD expected Found An unexpected keyword found following WITH
  • DB2-1070-00-E Number of row expected
    An unexpected keyword was found following OPTIMIZE.
  • DB2-1071-00-I FETCH ONLY assumed
    An unexpected keyword was found following FETCH. The only valid keyword to immediately follow FETCH is ONLY. .
  • DB2-1072-00-E In EXPR arithmetic operator applied to CHAR
    When evaluating the arithmetic expression indicated, a column with a CHARACTER data type encountered.
  • DB2-1073-00-E Mixed data types - creation of result field not supported
    While evaluating a function in which you specified Y to allow AMB to create the result field, AMB encountered columns with more than one data type. AMB cannot correctly create a result field for the function under these circumstances.
  • DB2-1074-00-E Command supported for SQLSVR only
    The database call is supported for SQL SERVER (SQLSVR) only.
  • DB2-1075-00-E Keyword supported for SQLSVR only
    The keyword is only supported for SQL SERVER (SQLSVR).
  • DB2-1076-00-E UPDATE keyword is invalid for SQLSVR
    In a DB-PROCESS or DB-DECLARE, the UPDATE keyword is invalid if your SQL target is SQL SERVER.
  • DB2-1077-00-E Cannot have BROWSE and HOLDLOCK in same cursor declaration
    The HOLDLOCK keyword restricts a shared lock on a specific table by holding it until completion of a transaction. The HOLDLOCK and BROWSE keywords are mutually exclusive.
  • DB2-1078-00-E AUTO keyword is only valid for DC targets PM and WIN
    Current DC currentdc. AMB only allows the AUTO keyword for DB-CONNECT under PM and WIN.
  • DB2-1079-00-E DB2-AUTO-COMMIT disabled for SQLSVR
    AMB does not support the DB2-AUTO-COMMIT option, which automatically generates a commit after a DB-MODIFY, DB-STORE, DB-ERASE or DB-CLOSE, for SQL SERVER targets.
  • DB2-1080-00-I DB-COMMIT used without DB-BEGIN-TRAN
    AMB found a DB-COMMIT that is not preceded by a DB-BEGIN-TRAN.
  • DB2-1081-00-E DB-BEGIN-TRAN used without DB-COMMIT
  • DB2-1082-00-E Keyword supported for ORACLE only
    This keyword is only supported for ORACLE.
  • DB2-1083-00-E Command - cannot have AT-DBNAME clause
    The AT-DBNAME clause is only valid for DB-PROCESS, DB-DECLARE, DB-STORE, DB-OBTAIN, DB-ERASE, and DB-MODIFY database calls.
  • DB2-1084-00-E Command supported for ORACLE only
    This database call is supported for ORACLE only.
  • DB2-1086-00-E Expression not valid for command
    AMB SQL supports expressions for DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls. Expressions in all other AMB SQL calls are invalid.
Parent topic: AppMaster Builder Error Messages


DB2-1001-00-E Not a valid column name

The named column does not belong to the table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the spelling or check for column name in the table.

Parent topic: DB2- SQL messages


DB2-1002-00-W Cursor not declared

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the cursor name to make sure it is declared.

Parent topic: DB2- SQL messages


DB2-1003-00-E Not WHERE or NOWHERE or NULL keyword

Invalid call keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Use WHERE, NOWHERE, or WHERE as keyword.

Parent topic: DB2- SQL messages


DB2-1004-00-W This statement will modify an entire table

DB-MODIFY call updates the entire table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

You must specify column name(s) or AMB updates the entire table.

Parent topic: DB2- SQL messages


DB2-1005-00-E No record name defined

You did not specify the record name in the call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the record name.

Parent topic: DB2- SQL messages


DB2-1006-00-E COLUMN not inserted and declared not null

The specified column name is not inserted but declared not null.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Specify the column name in the call (the column cannot contain null value).

Parent topic: DB2- SQL messages


DB2-1007-00-E WHERE not allowed on STORE

AMB does not allow the WHERE keyword in a DB-STORE call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1008-00-W This statement will erase an entire table

AMB will delete all rows in the table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: DB2- SQL messages


DB2-1009-00-W Cursor not declared

You did not declare the cursor name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the cursor name to make sure it is declared.

Parent topic: DB2- SQL messages


DB2-1010-00-E No column names allowed on ERASE

It is Invalid to delete a column.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the named column from the call.

Parent topic: DB2- SQL messages


DB2-1011-00-W OBTAIN needs a WHERE clause or it can retrieve multiple rows

The coded call may retrieve multiple rows.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Be sure you want multiple row retrieval.

Parent topic: DB2- SQL messages


DB2-1012-00-E CANNOT OBTAIN WHERE CURRENT NEED CURSOR AND FETCH

Keyword WHERE CURRENT invalid in DB-OBTAIN call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

DB-DECLARE and DB-FETCH the cursor if cursor desired.

Parent topic: DB2- SQL messages


DB2-1013-00-E Declare cursor more than once

The named cursor already used.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Specify different cursor name.

Parent topic: DB2- SQL messages


DB2-1014-00-E Command cannot have WHERE CURRENT OF

Do not use WHERE CURRENT OF with this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1015-00-E No cursor name defined

Code cursor name for this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1016-00-E Keyword not allowed as record name

Keyword is already used as record name. Code a record name instead of a keyword in the call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1017-00-E UPDATE specified but no column name follows keyword

Enter column name after keyword UPDATE or remove empty UPDATE from the call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1018-00-E Parameter not WHERE or NULL or NOWHERE or UPDATE or ORDER

Invalid parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Correct the specified parameter (should be WHERE, NOWHERE, UPDATE, ORDER or omitted).

Parent topic: DB2- SQL messages


DB2-1019-00-E Invalid column name after UPDATE

The named column in UPDATE clause does not belong to the table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the spelling or check for column name in the table.

Parent topic: DB2- SQL messages


DB2-1020-00-F Name not found in DDISYMB

The specified record name not found in DDISYMB.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling of record name.

Parent topic: DB2- SQL messages


DB2-1021-00-E WHERE search condition not found

Enter a search condition in the WHERE clause, or remove the empty WHERE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1022-00-E FROM not allowed with

Do not use the FROM keyword with this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1023-00-E INTO not allowed with

Do not use the INTO keyword with this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1024-00-E DB-PROCESS-ID is valid only with the DB-PROCESS call

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1025-00-E ORDER specified but no column name follows keyword

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Enter column name after keyword ORDER, or remove the empty ORDER.

Parent topic: DB2- SQL messages


DB2-1026-00-E Invalid column name after ORDER

AMB could not find the named column in ORDER clause in the result table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Correct the spelling or check for column name in the result table. Be sure you select the column before you code it in an ORDER clause.

Parent topic: DB2- SQL messages


DB2-1027-00-E Cannot have UPDATE and ORDER in same cursor declaration

Code UPDATE or ORDER in a single cursor declaration.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1028-00-I Column name specified in the UPDATE clause will be updated

AMB will update the named column in UPDATE clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: DB2- SQL messages


DB2-1029-00-E INTO or FROM keyword has no structure name

Code the structure name after FROM or INTO.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1030-00-E DB-PROCESS-ID keyword has no ID name following it

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1031-00-E Found more than once in command

Remove the extra keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1032-00-E END or ENDWHERE specified and had no WHERE clause

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for a valid WHERE clause, or remove END or ENDWHERE from the code.

Parent topic: DB2- SQL messages


DB2-1033-00-E Keyword only valid for DB-PROCESS and DB-DECLARE

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1034-00-E WHERE clause found after END or ENDWHERE

Check for a valid WHERE clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1035-00-E NOWHERE clause specified and there is a WHERE clause

Cannot use NOWHERE or WHERE in the same call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1036-00-E NOWHERE clause specified and there is an END or ENDWHERE

END or ENDWHERE are invalid for NOWHERE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1037-00-E When WHERE clause is present UPDATE or ORDER must follow after

Found WHERE after UPDATE or ORDER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Code UPDATE or ORDER after WHERE clause.

Parent topic: DB2- SQL messages


DB2-1038-00-E Cannot have CURRENT keyword with a NOWHERE clause

CURRENT is invalid in a NOWHERE clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1039-00-E Found CURRENT keyword before finding WHERE clause

CURRENT valid only with WHERE (WHERE CURRENT OF).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1040-00-E Invalid use of WHERESQL with CURRENT

You used WHERESQL CURRENT OF instead of WHERE CURRENT OF.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DB2- SQL messages


DB2-1042-00-E CURSOR longer than 12 characters

The named cursor is longer than the maximum length of 12 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1043-00-E -ID name longer than 10 characters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Make sure the name is 10 characters or less.

Parent topic: DB2- SQL messages


DB2-1045-00-E Individual cols and builtin functions should not be mixed

Do not select individual columns in a query if also using a built-in function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Create a select list that either names individual columns or lists columns with built-in functions applied to them; do not include both in one select list.

Parent topic: DB2- SQL messages


DB2-1046-00-E Syntax invalid for SELECT DISTINCT

You either used the keyword DISTINCT more than once in a subselect, or it you did not place it directly before the column select list.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Do not use DISTINCT more than once in a subselect. In addition, DISTINCT must precede the column select list.

Parent topic: DB2- SQL messages


DB2-1047-00-E Not a valid built-in function

You coded a built-in function other than MAX, MIN, AVG, SUM or COUNT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1048-00-E DISTINCT modifier required for COUNT

Syntax for the built-in function COUNT requires the keyword DISTINCT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1049-00-E Invalid function argument -

The argument given in a function is not a valid data type for that function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the function arguments to ensure they are the proper data type.

Parent topic: DB2- SQL messages


DB2-1050-00-E Cannot return result -

AMB cannot determine the result field for a function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

You may have used a complex expression as a function argument; if so, you must create the result field in Working-Storage yourself. Also, check the number of parentheses coded with the function.

Parent topic: DB2- SQL messages


DB2-1051-00-E Cannot create function result -

Something other than Y or N specified for the CREATE RESULT field indicator.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the syntax for coding SQL built-in functions.

Parent topic: DB2- SQL messages


DB2-1052-00-E Invalid use of DB-LOOP-MAX keyword

DB-LOOP-MAX is valid for DB-PROCESS calls only. You included DB-LOOP-MAX included in a call other than a DB-PROCESS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1053-00-E Invalid use of UNION keyword

The following conditions can cause this message:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  1. ORDER keyword coded before the end of a UNION
  2. UNION coded in a DB-PROCESS structure
  3. More than one DB-DECLARE coded in a UNION

Check for the above conditions. See UNION syntax, examples and other coding guidelines.

Parent topic: DB2- SQL messages


DB2-1054-00-E UNION select list incompatible

The select lists of each query in a UNION are not the same length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Each query should return the same number of columns, with a corresponding sequence of column length and type. See UNION syntax, examples and other coding guidelines.

Parent topic: DB2- SQL messages


DB2-1055-00-E Data type of column in function cannot be found - regen subschema

To process SQL functions, AMB SQL needs data type information for each column. The current data view does not contain data type information for all columns.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

REGEN your data view to pick up this information.

Parent topic: DB2- SQL messages


DB2-1056-00-E Indicator structure not found for CURSOR

A fatal error occurred as a DB-MODIFY call processed either the cursor or the indicator structure for the cursor.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the cursor name to ensure that the first 8 characters uniquely identify it, and it contains no more than 12 characters altogether. If you have overridden generation or inclusion of indicator structures by AMB, make sure you included your own indicator structures for the named cursor. Contact your AMB Administrator for assistance.

Parent topic: DB2- SQL messages


DB2-1057-00-E Indicator structure not found for TABLE

A fatal error occurred in processing the indicator structure for the named table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If you have overridden generation or inclusion of indicator structures by AMB, make sure you have included your own indicator structures for the named cursor or table. Contact your AMB Administrator for assistance.

Parent topic: DB2- SQL messages


DB2-1058-00-E INSERT table cannot be the same as SUBSELECT table

You named the table or view into which data is being inserted by a DB-STORE as the source from where a subselect is drawing that data. The object of an insert cannot be the same as the object of the subselect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the object of the subselect or re-evaluate the need for a subselect.

Parent topic: DB2- SQL messages


DB2-1059-00-E Columns in SUBSELECT result table do not match insert column list

Select lists for insert and subselect are not the same length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The number of columns in the result table of the subselect must equal the number of names in the insert column select list.

Parent topic: DB2- SQL messages


DB2-1060-00-E GROUP BY specified but no column name follows keyword

No column name given after the GROUP keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check GROUP BY syntax. Specify the appropriate column that is, the column you want to use as a grouping column.

Note: AMB applies column functions (MAX, MIN, SUM, AVG, or COUNT) to any column in the SELECT list that you did not specify as a grouping column.
Parent topic: DB2- SQL messages


DB2-1061-00-E Invalid column name after GROUP

AMB could not find a column named in the GROUP BY clause in the SELECT list.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check to ensure every column named in the GROUP BY clause is also named in the SELECT list.

Parent topic: DB2- SQL messages


DB2-1062-00-E Different location names seen in UNION

You cannot execute a UNION of tables from two or more different locations. Refer only to tables in the same location.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1063-00-E Different location names seen in Join

You cannot Join tables from two or more different locations. Refer only to tables in the same location.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1064-00-E Cannot INSERT DELETE or UPDATE from remote location if using CICS or IMS

When accessing remote tables or views via the CICS or IMS/VS attachment facility, you cannot use INSERT, DELETE, or UPDATE statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If you use CICS or IMS, use INSERT, DELETE, and UPDATE statements on local tables only.

Parent topic: DB2- SQL messages


DB2-1065-00-E DISTINCT invalid or used more than once in a statement

Either the DISTINCT keyword is invalid as used, or it appears more than once in a statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax for valid usage of the DISTINCT clause and remove any duplicate DISTINCT clauses. For example, a program may have a DISTINCT clause in one area, as well as a select statement such as COUNT (DISTINCT columnname).

Parent topic: DB2- SQL messages


DB2-1066-00-E COMMIT-ROLLBACK not supported in non-ISPF environment

You attempted to use the DB-COMMIT call in a CICS or IMS program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Valid DC targets for DB-COMMIT and DB-ROLLBACK are BATCH and DLG.

Parent topic: DB2- SQL messages


DB2-1067-00-E COMMIT with HOLD parameter not supported unless using SQL-400

When coding a DB-COMMIT, do not code the HOLD parameter unless the SQL target is SQL/400.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1068-00-E Invalid parameter specified for command

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Re-check your syntax for the call named. Remove any invalid parameters.

Parent topic: DB2- SQL messages


DB2-1069-00-E WITH HOLD expected Found An unexpected keyword found following WITH

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Re-check your syntax for the call named. Remove any invalid parameters.

Parent topic: DB2- SQL messages


DB2-1070-00-E Number of row expected

An unexpected keyword was found following OPTIMIZE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. The OPTIMIZE keyword should immediately follow a number indicating the estimated maximum number of rows that the call will retrieve.

Parent topic: DB2- SQL messages


DB2-1071-00-I FETCH ONLY assumed

An unexpected keyword was found following FETCH. The only valid keyword to immediately follow FETCH is ONLY. .
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax

Parent topic: DB2- SQL messages


DB2-1072-00-E In EXPR arithmetic operator applied to CHAR

When evaluating the arithmetic expression indicated, a column with a CHARACTER data type encountered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

You cannot apply arithmetic operations against columns defined as CHARACTER data types. Correct the expression.

Parent topic: DB2- SQL messages


DB2-1073-00-E Mixed data types - creation of result field not supported

While evaluating a function in which you specified Y to allow AMB to create the result field, AMB encountered columns with more than one data type. AMB cannot correctly create a result field for the function under these circumstances.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the create result field parameter from Y to N and create the result field yourself. Otherwise, modify the function arguments so that they are the same data type.

Parent topic: DB2- SQL messages


DB2-1074-00-E Command supported for SQLSVR only

The database call is supported for SQL SERVER (SQLSVR) only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1075-00-E Keyword supported for SQLSVR only

The keyword is only supported for SQL SERVER (SQLSVR).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1076-00-E UPDATE keyword is invalid for SQLSVR

In a DB-PROCESS or DB-DECLARE, the UPDATE keyword is invalid if your SQL target is SQL SERVER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

To modify columns during cursor processing, use the BROWSE keyword instead of UPDATE.

Parent topic: DB2- SQL messages


DB2-1077-00-E Cannot have BROWSE and HOLDLOCK in same cursor declaration

The HOLDLOCK keyword restricts a shared lock on a specific table by holding it until completion of a transaction. The HOLDLOCK and BROWSE keywords are mutually exclusive.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax. Code only HOLDLOCK or BROWSE in a single cursor declaration.

Parent topic: DB2- SQL messages


DB2-1078-00-E AUTO keyword is only valid for DC targets PM and WIN

Current DC currentdc. AMB only allows the AUTO keyword for DB-CONNECT under PM and WIN.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1079-00-E DB2-AUTO-COMMIT disabled for SQLSVR

AMB does not support the DB2-AUTO-COMMIT option, which automatically generates a commit after a DB-MODIFY, DB-STORE, DB-ERASE or DB-CLOSE, for SQL SERVER targets.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Set &NDB2-AUTO-COMMIT to NO.

Parent topic: DB2- SQL messages


DB2-1080-00-I DB-COMMIT used without DB-BEGIN-TRAN

AMB found a DB-COMMIT that is not preceded by a DB-BEGIN-TRAN.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: DB2- SQL messages


DB2-1081-00-E DB-BEGIN-TRAN used without DB-COMMIT

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

End DB-BEGIN-TRAN by coding a DB-COMMIT to end the transaction.

Parent topic: DB2- SQL messages


DB2-1082-00-E Keyword supported for ORACLE only

This keyword is only supported for ORACLE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1083-00-E Command - cannot have AT-DBNAME clause

The AT-DBNAME clause is only valid for DB-PROCESS, DB-DECLARE, DB-STORE, DB-OBTAIN, DB-ERASE, and DB-MODIFY database calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1084-00-E Command supported for ORACLE only

This database call is supported for ORACLE only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DB2-1086-00-E Expression not valid for command

AMB SQL supports expressions for DB-DECLARE, DB-OBTAIN, and DB-PROCESS calls. Expressions in all other AMB SQL calls are invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DB2- SQL messages


DCL- IMS rule messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • DCL-0900-00-F PSB or subschema invoked more than once
    You coded the IM-PSB or DB-SUBSCHEMA call more than once, or coded both.
  • DCL-0910-00-F Regenerate DDI symbols using 17Q or greater
    Regenerate the DDI symbols with the current release of the DDI utility.
  • DCL-1010-00-E No parms passed
    AMB invoked a database call but you did not pass any parameters.
  • DCL-1030-00-E REC or REF expected as second parm in
    If specifying record type as the first parameter (i.e., GSAM, VSAM, or DLI), then REC or REF must be the second parameter.
  • DCL-1040-00-E MODE keyword expected
    For a DB-OPEN, specify the MODE keyword followed by the appropriate access mode.
  • DCL-1050-00-E NEXT valid only for DB-OBTAIN
    The keyword NEXT or NEXTREC pertains only to retrievals. It generates an unqualified retrieval call. It is therefore valid only for a DB-OBTAIN.
  • DCL-1060-00-E INTO expected as second parm
    When you use the NEXT or NEXTREC keyword, the following parameter must be INTO followed by a data area.
  • DCL-1070-00-E Record name expected no more parms
    The COBOL record name must follow the keywords REF, REFERENCE, REC, or RECORD in call.
  • DCL-1080-00-E CKEYED valid only for first record
    A concatenated key value is valid only for the first record specified in the retrieval call.
  • DCL-1090-00-E CKEYED specified more than once
    You can specify the CKEYED or CONCAT-KEYED only once per call.
  • DCL-1100-00-E Concatenated key value expected no more parms
    Follow the keyword CKEYED or CONCAT-KEYED with a literal or data field containing the concatenated key value in call.
  • DCL-1110-00-E Qualification not allowed for
    You cannot qualify this call with a field qualification or with the keyword CURRENT.
  • DCL-1120-00-E CURRENT only valid for first record
    The keyword CURRENT is valid only if it follows the first record in call.
  • DCL-1130-00-E CURRENT only valid for referenced record
    CURRENT is valid only for a record that you precede with the keyword REFERENCE or REF.
  • DCL-1140-00-E CURRENT specified more than once
    You can specify the keyword CURRENT only once per call.
  • DCL-1150-00-E FROM or INTO specified more than once in
    You can specify the keywords FROM or INTO only once per record retrieved.
  • DCL-1160-00-E Data name expected no more parms
    AMB expects a data area following the preceding keyword.
  • DCL-1170-00-E FROM or INTO expected followed by data area
    When you use the keyword IMSREC, a data area must follow the keyword FROM or INTO.
  • DCL-1180-00-E WHERE keyword found expected REC or REF or boolean operator
    You can only specify WHERE once per record qualification call.
  • DCL-1190-00-E Field qualification invalid when using keyword IMSREC
    The keyword IMSREC and a field qualification are mutually exclusive. Remove either the field qualification or the keyword IMSREC.
  • DCL-1200-00-E Field qualification invalid with CURRENT
    The keyword CURRENT and a field qualification are mutually exclusive.
  • DCL-1210-00-E Field qualification invalid with CKEYED
    The keyword CKEYED or CONCAT-KEYED and a field qualification are mutually exclusive.
  • DCL-1220-00-E Field name expected no more parms
    Complete the qualification by specifying a COBOL field name followed by a relational operator and then followed by a data area.
  • DCL-1230-00-E Relational operator expected no more parms
    Complete the qualification by specifying a relational operator followed by a data area.
  • DCL-1240-00-E Relational operator expected
    The symbol or character abbreviation for the relational operator is incorrect.
  • DCL-1250-00-E Field value expected no more parms
    AMB expects a value field or literal to complete the qualification.
  • DCL-1260-00-E Subscript expected no more parms
  • DCL-1270-00-E Right paren expected following key qualification no more parms
    You coded a left parenthesis to indicate that the following key qualification contains more than one field but you did not terminate the qualification with a right parenthesis.
  • DCL-1280-00-E FIRST or LAST invalid with CURRENT
    The keywords CURRENT and FIRST or LAST are mutually exclusive.
  • DCL-1290-00-E FIRST or LAST specified more than once for record
    Remove the extra keyword.
  • DCL-1300-00-E CCODE found more than once for record
    Remove the extra CCODE or COMMAND-CODE keyword.
  • DCL-1310-00-E Command code expected no more parms
    You must follow the keyword CCODE or COMMAND-CODE with one or more call codes.
  • DCL-1320-00-E FROM or INTO specified more than once for record
    Remove the extra keyword.
  • DCL-1330-00-E NEXT or IMSREC invalid when specifying more than one record per call
    You cannot specify the keywords NEXT, NEXTREC, or IMSREC in a multi-level call.
  • DCL-1340-00-E VIEW specified more than once
    You can specify the keyword VIEW only once per call.
  • DCL-1350-00-E View name expected no more parms
    You must follow the keyword VIEW with a view name.
  • DCL-1360-00-E RESET specified more than once
    You can specify the keyword RESET only once per call.
  • DCL-1370-00-E HOLD-NOHOLD specified more than once
    You can specify the HOLD or NOHOLD only once per call.
  • DCL-1380-00-E PREV specified more than once
    You can specify the keyword PREV or PREVIOUS only once per call.
  • DCL-1390-00-E expected no more parms
    You must follow the keyword KLEN or KEYLENGTH with the key length.
  • DCL-1400-00-E Unrecognized or misplaced parm
    The parameter is invalid or it is in the wrong place in the call.
  • DCL-1410-00-E VIEW keyword followed by is required for this
    If you specify the keyword NEXT, NEXTREC, or IMSREC, then follow the keyword VIEW with a view name.
  • DCL-1420-00-E At least one record must be acted upon by specifying keyword REC
    If the call is DB-MODIFY or DB-STORE, at least one of the records specified must be acted upon by prefacing it with the keyword REC or RECORD.
  • DCL-1430-00-E CKEYED invalid for DB-MODIFY
    The keyword CKEYED or CONCAT-KEYED is invalid for DB-MODIFY.
  • DCL-1440-00-E Added record may not be qualified by concatenated key
    You cannot qualify the record you want to add with a concatenated key value. Remove the keyword CKEYED.
  • DCL-1450-00-E Dependent record under record to be added may not be referenced
    You cannot precede a record under a record you want to add with the keyword REF or REFERENCE. You must precede it with the keyword REC or RECORD.
  • DCL-1460-00-E
    Field qualification invalid for added record. You cannot qualify a record you want to add with a field qualification.
  • DCL-1470-00-E Dependent record under record to be deleted may not be referenced
    For a DB-ERASE, you must precede any record which is a child of a record you want to delete with the keyword REC.
  • DCL-1480-00-E Lowest level record must be preceded by keyword REC
    For a DB-ERASE, you must precede the lowest level record specified with the keyword REC or RECORD.
  • DCL-1490-00-E Command codes invalid for DB-ERASE
    You cannot specify call codes for DB-ERASE.
  • DCL-1500-00-E CKEYED invalid for DB-ERASE
    CKEYED or CONCAT-KEYED is invalid for DB-ERASE.
  • DCL-1510-00-E Expected keyword relational or boolean operator
  • DCL-1520-00-E FIRST keyword not recognized
  • DCL-1530-00-E Record name missing
  • DCL-1540-00-E Record name not defined to subschema record name ()
    AMB did not find the record name on the call in the data view symbols.
  • DCL-2000-00-E DCL-2005-00-E Do not use subscripted fields with EXEC DLI commands
    The SUBSCRIPT, OF, and IN keywords are invalid in EXEC DLI calls.
  • DCL-2007-00-E Do not use multiple field values with EXEC DLI commands
    Remove multiple field values for key qualification. AMB permits only one value.
  • DCL-2010-00-E LOCK keyword invalid for REFERENCED records
    You cannot LOCK a record that you REFerence.
  • DCL-2020-00-E LOCK keyword specified more than once
  • DCL-2030-00-E Record length expected no more parms
    You specified the LENGTH keyword but did not follow it with a record length.
  • DCL-2040-00-E Offset value expected No more parms
    You specified the OFFSET keyword but did not follow it with a record offset.
  • DCL-2050-00-E Keyword RECLENGTH must be specified
    AMB requires the RECLENGTH keyword, followed by the record length, for this call.
  • DCL-2060-00-E RESET invalid with CURRENT for EXEC DLI
    The keyword RESET is invalid when used with the keyword CURRENT.
  • DCL-2070-00-E RESET invalid with FIRST for EXEC DLI
    The keyword RESET is invalid when used with the keyword FIRST.
  • DCL-2080-00-E GN call issued for this command
    RESET-POSITION flag assumed to be FALSE. AMB generated a GET NEXT call for this call.
Parent topic: AppMaster Builder Error Messages


DCL-0900-00-F PSB or subschema invoked more than once

You coded the IM-PSB or DB-SUBSCHEMA call more than once, or coded both.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The two calls are synonymous. Invoke only one.

Parent topic: DCL- IMS rule messages


DCL-0910-00-F Regenerate DDI symbols using 17Q or greater

Regenerate the DDI symbols with the current release of the DDI utility.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Regenerate the symbols using the appropriate software. Contact your AMB Administrator for assistance.

Parent topic: DCL- IMS rule messages


DCL-1010-00-E No parms passed

AMB invoked a database call but you did not pass any parameters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Specify the appropriate parameters with the call.

Parent topic: DCL- IMS rule messages


DCL-1030-00-E REC or REF expected as second parm in

If specifying record type as the first parameter (i.e., GSAM, VSAM, or DLI), then REC or REF must be the second parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1040-00-E MODE keyword expected

For a DB-OPEN, specify the MODE keyword followed by the appropriate access mode.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1050-00-E NEXT valid only for DB-OBTAIN

The keyword NEXT or NEXTREC pertains only to retrievals. It generates an unqualified retrieval call. It is therefore valid only for a DB-OBTAIN.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1060-00-E INTO expected as second parm

When you use the NEXT or NEXTREC keyword, the following parameter must be INTO followed by a data area.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1070-00-E Record name expected no more parms

The COBOL record name must follow the keywords REF, REFERENCE, REC, or RECORD in call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1080-00-E CKEYED valid only for first record

A concatenated key value is valid only for the first record specified in the retrieval call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the keyword CKEYED specified for any record other than the first one.

Parent topic: DCL- IMS rule messages


DCL-1090-00-E CKEYED specified more than once

You can specify the CKEYED or CONCAT-KEYED only once per call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1100-00-E Concatenated key value expected no more parms

Follow the keyword CKEYED or CONCAT-KEYED with a literal or data field containing the concatenated key value in call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1110-00-E Qualification not allowed for

You cannot qualify this call with a field qualification or with the keyword CURRENT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1120-00-E CURRENT only valid for first record

The keyword CURRENT is valid only if it follows the first record in call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1130-00-E CURRENT only valid for referenced record

CURRENT is valid only for a record that you precede with the keyword REFERENCE or REF.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1140-00-E CURRENT specified more than once

You can specify the keyword CURRENT only once per call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1150-00-E FROM or INTO specified more than once in

You can specify the keywords FROM or INTO only once per record retrieved.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1160-00-E Data name expected no more parms

AMB expects a data area following the preceding keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

You coded the keyword FROM, INTO, OF, or IN as the very last parameter. Correct the call by specifying a data area to follow the keyword.

Parent topic: DCL- IMS rule messages


DCL-1170-00-E FROM or INTO expected followed by data area

When you use the keyword IMSREC, a data area must follow the keyword FROM or INTO.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1180-00-E WHERE keyword found expected REC or REF or boolean operator

You can only specify WHERE once per record qualification call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1190-00-E Field qualification invalid when using keyword IMSREC

The keyword IMSREC and a field qualification are mutually exclusive. Remove either the field qualification or the keyword IMSREC.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1200-00-E Field qualification invalid with CURRENT

The keyword CURRENT and a field qualification are mutually exclusive.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove either the field qualification or the keyword CURRENT.

Parent topic: DCL- IMS rule messages


DCL-1210-00-E Field qualification invalid with CKEYED

The keyword CKEYED or CONCAT-KEYED and a field qualification are mutually exclusive.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove either the field qualification or the keyword CKEYED.

Parent topic: DCL- IMS rule messages


DCL-1220-00-E Field name expected no more parms

Complete the qualification by specifying a COBOL field name followed by a relational operator and then followed by a data area.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1230-00-E Relational operator expected no more parms

Complete the qualification by specifying a relational operator followed by a data area.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1240-00-E Relational operator expected

The symbol or character abbreviation for the relational operator is incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by specifying the proper relational operator.

Parent topic: DCL- IMS rule messages


DCL-1250-00-E Field value expected no more parms

AMB expects a value field or literal to complete the qualification.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by specifying a literal or data field containing the value for the field qualification after the relational operator.

Parent topic: DCL- IMS rule messages


DCL-1260-00-E Subscript expected no more parms

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by specifying a subscript after the keyword SUB or SUBSCRIPT.

Parent topic: DCL- IMS rule messages


DCL-1270-00-E Right paren expected following key qualification no more parms

You coded a left parenthesis to indicate that the following key qualification contains more than one field but you did not terminate the qualification with a right parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1280-00-E FIRST or LAST invalid with CURRENT

The keywords CURRENT and FIRST or LAST are mutually exclusive.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by removing either the keyword FIRST, LAST, or CURRENT.

Parent topic: DCL- IMS rule messages


DCL-1290-00-E FIRST or LAST specified more than once for record

Remove the extra keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1300-00-E CCODE found more than once for record

Remove the extra CCODE or COMMAND-CODE keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1310-00-E Command code expected no more parms

You must follow the keyword CCODE or COMMAND-CODE with one or more call codes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1320-00-E FROM or INTO specified more than once for record

Remove the extra keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1330-00-E NEXT or IMSREC invalid when specifying more than one record per call

You cannot specify the keywords NEXT, NEXTREC, or IMSREC in a multi-level call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by specifying only one record level when using the keyword NEXT or IMSREC.

Parent topic: DCL- IMS rule messages


DCL-1340-00-E VIEW specified more than once

You can specify the keyword VIEW only once per call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1350-00-E View name expected no more parms

You must follow the keyword VIEW with a view name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1360-00-E RESET specified more than once

You can specify the keyword RESET only once per call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1370-00-E HOLD-NOHOLD specified more than once

You can specify the HOLD or NOHOLD only once per call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1380-00-E PREV specified more than once

You can specify the keyword PREV or PREVIOUS only once per call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1390-00-E expected no more parms

You must follow the keyword KLEN or KEYLENGTH with the key length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1400-00-E Unrecognized or misplaced parm

The parameter is invalid or it is in the wrong place in the call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling and/or placement of the parameter syntax.

Parent topic: DCL- IMS rule messages


DCL-1410-00-E VIEW keyword followed by is required for this

If you specify the keyword NEXT, NEXTREC, or IMSREC, then follow the keyword VIEW with a view name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1420-00-E At least one record must be acted upon by specifying keyword REC

If the call is DB-MODIFY or DB-STORE, at least one of the records specified must be acted upon by prefacing it with the keyword REC or RECORD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1430-00-E CKEYED invalid for DB-MODIFY

The keyword CKEYED or CONCAT-KEYED is invalid for DB-MODIFY.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1440-00-E Added record may not be qualified by concatenated key

You cannot qualify the record you want to add with a concatenated key value. Remove the keyword CKEYED.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-1450-00-E Dependent record under record to be added may not be referenced

You cannot precede a record under a record you want to add with the keyword REF or REFERENCE. You must precede it with the keyword REC or RECORD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure that you preface each record you want to insert with the keyword REC in the call.

Parent topic: DCL- IMS rule messages


DCL-1460-00-E

Field qualification invalid for added record. You cannot qualify a record you want to add with a field qualification.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove either the field qualification or the record you want to insert.

Parent topic: DCL- IMS rule messages


DCL-1470-00-E Dependent record under record to be deleted may not be referenced

For a DB-ERASE, you must precede any record which is a child of a record you want to delete with the keyword REC.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by specifying the keyword REC for all records under the first record you want to delete.

Parent topic: DCL- IMS rule messages


DCL-1480-00-E Lowest level record must be preceded by keyword REC

For a DB-ERASE, you must precede the lowest level record specified with the keyword REC or RECORD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by specifying the keyword REC before the lowest level record in the call.

Parent topic: DCL- IMS rule messages


DCL-1490-00-E Command codes invalid for DB-ERASE

You cannot specify call codes for DB-ERASE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by removing the keyword CCODE.

Parent topic: DCL- IMS rule messages


DCL-1500-00-E CKEYED invalid for DB-ERASE

CKEYED or CONCAT-KEYED is invalid for DB-ERASE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-1510-00-E Expected keyword relational or boolean operator

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling or placement of the parameter in question.

Parent topic: DCL- IMS rule messages


DCL-1520-00-E FIRST keyword not recognized

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling of the keyword.

Parent topic: DCL- IMS rule messages


DCL-1530-00-E Record name missing

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling of the keyword and syntax.

Parent topic: DCL- IMS rule messages


DCL-1540-00-E Record name not defined to subschema record name ()

AMB did not find the record name on the call in the data view symbols.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-2000-00-E DCL-2005-00-E Do not use subscripted fields with EXEC DLI commands

The SUBSCRIPT, OF, and IN keywords are invalid in EXEC DLI calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-2007-00-E Do not use multiple field values with EXEC DLI commands

Remove multiple field values for key qualification. AMB permits only one value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-2010-00-E LOCK keyword invalid for REFERENCED records

You cannot LOCK a record that you REFerence.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-2020-00-E LOCK keyword specified more than once

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra keyword.

Parent topic: DCL- IMS rule messages


DCL-2030-00-E Record length expected no more parms

You specified the LENGTH keyword but did not follow it with a record length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-2040-00-E Offset value expected No more parms

You specified the OFFSET keyword but did not follow it with a record offset.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-2050-00-E Keyword RECLENGTH must be specified

AMB requires the RECLENGTH keyword, followed by the record length, for this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DCL- IMS rule messages


DCL-2060-00-E RESET invalid with CURRENT for EXEC DLI

The keyword RESET is invalid when used with the keyword CURRENT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-2070-00-E RESET invalid with FIRST for EXEC DLI

The keyword RESET is invalid when used with the keyword FIRST.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DCL-2080-00-E GN call issued for this command

RESET-POSITION flag assumed to be FALSE. AMB generated a GET NEXT call for this call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DCL- IMS rule messages


DDI- database definition messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • DDI-1000-00-F DDI-1007-00-F DDI-1020-00-F UNTIL error PT-PACK too long
    Fatal error, processing stopped. When unpacking data from the DDI file, a pointer calculated was out of range.
  • DDI-1001-00-F DDI-1008-00-F DDI-1021-00-F UNTIL error PT-TEXT too long
    Fatal error, processing stopped. When unpacking data from the DDI file, text calculated was out of range.
  • DDI-1002-00-F Error in DELETE
    Fatal error, processing stopped. When deleting an entity from the DDI file, a file error occurred.
  • DDI-1003-00-F Empty DDIFILE
    Fatal error, processing stopped. AMB attempted to search the DDI file and found it empty.
  • DDI-1004-00-F DDI-1022-00-F SAVE-CANCEL file access
    Fatal error, processing stopped. A SAVE or CANCEL on the DDI file failed.
  • DDI-1005-00-F DDI-1023-00-F CREATE-UPDATE file access
    Fatal error, processing stopped. A CREATE or UPDATE on the DDI file failed.
  • DDI-1006-00-F DDI-1024-00-F Record READ access
    Fatal error, processing stopped. A READ on the DDI file failed.
  • DDI-1007-00-F DDI-1000-00-F DDI-1020-00-F UNTIL error PT-PACK too long
    Fatal error, processing stopped. When unpacking data from the DDI file, a pointer calculated was out of range.
  • DDI-1008-00-F DDI-1001-00-F DDI-1021-00-F UNTIL error PT-TEXT too long
    Fatal error, processing stopped. When unpacking data from the DDI file, text calculated was out of range.
  • DDI-1009-00-F Unclear entity found reload into DDIFILE
    An error occurred when reading the DDI file.
  • DDI-1010-00-F Parameter name too long
    On the parameter NAME= the name that followed (a PSB or DBD name) was greater than 8 characters.
  • DDI-1011-00-F Invalid parameter found
    AMB found an invalid parameter. Valid parameters are:
  • DDI-1012-00-F Too many PSB names
    You specified more than 1000 PSB names on the PSB= parameter.
  • DDI-1013-00-F PSB and subschema not found
    AMB did not find the named PSB and/or data view source in the appropriate directory.
  • DDI-1014-00-F Segment not found
    AMB did not find the segment named in the PSB in either the DBD or the DDI statements source.
  • DDI-1015-00-F Segment parent not found
    AMB did not find the segment parent specified on the PSB in the DBD.
  • DDI-1016-00-F UNTIL2 program error
    Software error.
  • DDI-1017-00-F DDG program error
    Software error.
  • DDI-1018-00-F Record not found
    AMB did not find the named record in the DDI file.
  • DDI-1019-00-F Record is locked
    The named record is locked on the DDI file.
  • DDI-1020-00-F DDI-1007-00-F DDI-1000-00-F UNTIL error PT-PACK too long
    Fatal error, processing stopped. When unpacking data from the DDI file, a pointer calculated was out of range.
  • DDI-1021-00-F DDI-1008-00-F DDI-1001-00-F UNTIL error PT-TEXT too long
    Fatal error, processing stopped. When unpacking data from the DDI file, text calculated was out of range.
  • DDI-1022-00-F DDI-1004-00-F SAVE-CANCEL file access
    Fatal error, processing stopped. A SAVE or CANCEL on the DDI file failed.
  • DDI-1023-00-F DDI-1005-00-F CREATE-UPDATE file access
    Fatal error, processing stopped. A CREATE or UPDATE on the DDI file failed.
  • DDI-1024-00-F DDI-1006-00-F Record READ access
    Fatal error, processing stopped. A READ on the DDI file failed.
  • DDI-1025-00-F CREATE file access
    Fatal error, processing stopped. A CREATE on the DDI file failed.
  • DDI-1026-00-F SAVE-CREATE file access
    Fatal error, processing stopped. A CREATE or UPDATE on the DDI file failed. Contact your AMB Administrator.
  • DDI-1027-00-F DELETE file access
    Fatal error, processing stopped. A DELETE on the DDI file failed. Contact your AMB Administrator.
  • DDI-1028-00-F Illegal version fld
    While processing DDI statements for a DBD, AMB found a version field that is not-numeric.
  • DDI-1029-00-F Version fld too large
    While processing DDI statements for a DBD, AMB found a version field that is greater than 255.
  • DDI-1030-00-F Illegal MOD fld
    While processing DDI statements for a DBD, AMB found a MOD field that is not numeric.
  • DDI-1031-00-F MOD fld too large
    While processing DDI statements for a DBD, AMB found a MOD field is greater than 255.
  • DDI-1032-00-F Did not find DBDNAME or PSBNAME parameter
    While processing a PSB, AMB did not find the DBDNAME= or PSBNAME= parameter.
  • DDI-1033-00-F DBDNAME not found
    While processing a PSB, AMB found the DBDNAME= parameter with a nonexistent name for the DBD.
  • DDI-1034-00-F DBD table limit exceeded max is 10
    While processing a PSB, AMB detected more than 10 DBD references.
  • DDI-1035-00-F PSBNAME not found
    While processing a PSB, the PSBNAME= parameter had no name associated with it.
  • DDI-1036-00-F PSB table limit exceeded max is 10
    While processing a PSB, AMB detected more than 10 PSB references.
  • DDI-1037-00-F Unexpected EOF on DBD-PSB file
    AMB found a continuation character at the end of a PSB or DBD. AMB did not find a DBDGEN, FINISH, or END for a DBD; AMB did not find a PSBGEN or END for a PSB.
  • DDI-1038-00-F DBD name 8 characters
    AMB found a DBD name longer than 8 characters.
  • DDI-1039-00-F Parm not DEBUG or IGNORE invalid
    You passed an invalid keyword as a parameter to DDIDDG.
  • DDI-1041-00-F Right paren missing on parm
    You did not close a parameter with a right parenthesis.
  • DDI-1042-00-F No right paren found on parm
    Parameter is missing a right parenthesis.
  • DDI-2000-00-E Card must begin with xmlDDI
    AMB found something other than *DDI starting in column 7 of the DDI source.
  • DDI-2001-00-E Invalid card type
    DDI statements for VSAM processing must have a valid type starting in column 12. Valid types are:
  • DDI-2002-00-E DDNAME required for ALT indices
    AMB requires A DDN= followed by a name up to 8 characters for alternate indices. This name is the VSAM ddname of the file where AMB defines the alternate index.
  • DDI-2003-00-E DDN for primary IDX VSM DDN
    If you supply a ddname for a primary index, it must be the same name as the ddname of the file. If you do not supply a ddname, it defaults to the VSAM ddname.
  • DDI-2004-00-E Short name required for record
    You must supply a short record name, maximum 8 characters, on all REC statements.
  • DDI-2005-00-E COPY parameter only allowed on the first REC
    When defining a file with multiple records, only the first REC statement can have a COPY=. This copybook member should contain a definition for all records in the file.
  • DDI-2006-00-E MAXLEN required for record
    All REC statements require a maximum record length.
  • DDI-2007-00-E Record name missing
    AMB did not find a NAME= parameter on a REC statement. AMB requires a COBOL record name up to 30 characters. The name of the first record is also the long file name for the file.
  • DDI-2008-00-E File DDN missing
    AMB did not find a DDN= parameter on a VSM statement. AMB requires a ddname for the file; it can be up to 8 characters.
  • DDI-2009-00-E Member name missing
    AMB did not find a COPY= parameter followed by an 8 character name on a REC statement. This copybook member gives the record description.
  • DDI-2010-00-E Invalid copy source type
    AMB found a SOURCE= parameter with a value other than P (PDS member) or C (COBOL copybook member).
  • DDI-2011-00-E Invalid file record type
    AMB found a VSM statement with an invalid TYPE=. Valid record types are:
  • DDI-2012-00-E MAX record length missing
    All REC statements require MAXLEN= parameter.
  • DDI-2013-00-E AVG length greater than maximum
    On a variable length file, the average length of the record is larger than the maximum length. AVGLEN= should be less than or equal to MAXLEN=.
  • DDI-2014-00-E INDEX data missing for keyed file
    You must code at least one IDX statement for a keyed VSAM file. The IDX statement must follow the first REC statement for the file.
  • DDI-2015-00-E Subschema name missing
    AMB found a SUB statement without NAME=. This is the name of the VSAM data view and may be up to 8 characters.
  • DDI-2016-00-E Subschema records missing
    AMB found a SUB statement without REC=. This name should be the COBOL record name of the first record in the VSAM file and can be up to 30 characters.
  • DDI-2017-00-E REC card has invalid keyword
    AMB found a REC statement with an invalid keyword. Valid keywords are:
  • DDI-2018-00-E SUB card has invalid keyword
    AMB found a SUB statement with an invalid keyword. Valid keywords are:
  • DDI-2019-00-E Invalid file processing option
    AMB found a SUB statement with a PROCOPT= followed by an invalid processing option. Valid options are:
  • DDI-2020-00-E No PSBNAME or DBDNAME found
    AMB did not find any PSB names or DBD names on the parameter.
  • DDI-2021-00-E Improper format in the DBD parameter
    AMB found an error specifying a second argument on the DBD= parameter. Either a right parenthesis is missing or you supplied a non-numeric character.
  • DDI-2023-00-E PROCSEQ OR INDICIES NOT IN DBD
    When processing the PSB, AMB did not find a PROCSEQ or indices in the DBD.
  • DDI-2024-00-E Segment not found for XDFLD
    When processing the DBD, AMB did not find the specified segment for the XDFLD in the DDI file.
  • DDI-2025-00-E Record not found
    AMB did not find the named VSAM record on the DDI file.
  • DDI-2026-00-E Unrecognized parameter
    AMB found an invalid statement in the DBD, DDI statements, or PSB source.
  • DDI-2027-00-E Illegal syntax in DDI card
    AMB found a DDI statement with an illegal keyword. Valid keywords are:
  • DDI-2028-00-E Found card not starting with xmlDDI
    AMB found a statement in the DDI source that did not start with *DDI.
  • DDI-2029-00-E Missing DBD name or access
    When processing a DBD, AMB did not find the NAME= or ACCESS= parameter.
  • DDI-2030-00-E Illegal dataset
    You defined a label field in a data set statement without operands; but the access method specified in the DBD statement does not allow labeling without operands. Access must be HDAM or HIDAM.
  • DDI-2031-00-E No matching dataset label
    You did not previously define the label specified on the current data set with operands.
  • DDI-2032-00-E No preceding segment for field
    When processing a DBD, AMB found a FLD statement without a segment before it.
  • DDI-2033-00-E No preceding segment for LCHILD
    When processing a DBD, AMB found an LCHILD statement without a segment before it.
  • DDI-2034-00-E No preceding segment for XDFLD
    When processing a DBD, AMB found an XDFLD statement without a segment before it.
  • DDI-2035-00-E Missing PSB name
    The PSB name is missing from the parameter supplied to generate the step.
  • DDI-2036-00-E Missing or illegal PCB type
    While processing a PCB, AMB found the TYPE = parameter missing or invalid.
  • DDI-2037-00-E No previous PCB for SENSEG
    While processing a PSB, AMB found a SENSEG parameter without a prior PCB statement.
  • DDI-2038-00-E No previous SENSEG for SENFLD
    While processing a PSB, AMB found a SENFLD statement without a prior SENSEG statement.
  • DDI-2039-00-E Invalid keyword found on DBD ATTACH card
    While processing a DBD, AMB found a DBD DDI statement with something other than name or version.
  • DDI-2040-00-E Continuation expected found end of file
    AMB found a comma at the end of a DDI statement and the next READ found the end of file.
  • DDI-2041-00-E Expected continuation not found
    When processing the DDI statements, AMB found a statement with a comma at the end and you did not continue the statement on the next line.
  • DDI-2042-00-E Attempt to update failed
    Another job locked the DBD specified on the control card for update.
  • DDI-2043-00-E DBD not found
    While reading the DDI file, AMB did not find the named DBD.
  • DDI-2044-00-E PSB not found
    While reading the DDI file, AMB did not find the named PSB.
  • DDI-2045-00-E REC has no DBD before IT
    When processing the DDI statements for the DBD, AMB found a REC statement without a DBD statement before it. See Coding IMS DDI Statements.
  • DDI-2046-00-E Illegal keyword found on REC attach card
    AMB found an invalid keyword in the DDI source. Valid keywords are:
  • DDI-2047-00-E SEGMENT NOT FOUND
    When processing the DDI statements for a DBD, the SEG= parameter named a segment not found in the DBD.
  • DDI-2048-00-E Fld has no REC before it
    When processing the DDI statements, AMB found a FLD statement without a REC statement before it.
  • DDI-2049-00-E Fld IMSNAME not found under segment
    The IMSNAME keyword in the DDISRC must reference a DBDSRC NAME keyword defined in the segment being processed.
  • DDI-2050-00-E Illegal continuation
    A nonblank character must be in column 72 for continuation, or continue the next line in column 16.
  • DDI-2051-00-E Illegal keyword found on fld attach card
    While processing the DDI statements, AMB found a FLD statement with an invalid parameter. Valid FLD parameters are:
  • DDI-2052-00-E xmlDDI FLD card has no IMSNAME
    While processing DDI statements for PCB-level DDI overrides, AMB encountered a FLD statement without a IMSNAME= keyword or with spaces following IMSNAME=. See Coding IMS DDI Statements.
  • DDI-2053-00-E A PCB card was not entered for all PCBs
    While processing DDI statements for PCB-level overrides, you did not enter enough PCB statements to match all the TP and DB PCBs in the PSB. See Coding IMS DDI Statements.
  • DDI-2054-00-E REC card has no PCB card before it
    While processing DDI statements for PCB-level DDI overrides, AMB encountered a REC statement out of order. A REC statement must have a PCB statement preceding it. The proper statement sequence for PCB-level DDI statements is:
  • DDI-2055-00-E PCB card has no PSB card before it
    While processing DDI statements for a PCB-level override, AMB encountered a PCB statement out of order. A PCB statement must have a REC statement following it. The proper sequence for PCB-level DDI statements is:
  • DDI-2056-00-E Invalid keyword found on PSB attach card
    When processing a PSB statement for DDI overrides, AMB encountered a keyword other than NAME=. NAME= is the only valid keyword.
  • DDI-2057-00-E IDX only allowed for KSDS
    In a VSAM file definition, AMB found an IDX statement for an ESDS or relative record file.
  • DDI-3000-00-N PSB and-or subschema not DLI or VSAM
    While executing one step in the PSBGEN utility, AMB noticed the named PSB or data view is neither a DL/I nor VSAM type.
  • DDI-4000-00-I Duplicate 01 name
    While processing a DBD, AMB found a duplicate COBOL name on the DDI statements.
  • DDI-4001-00-I Defaulted to 8 char IMSNAME
    While processing a DBD, AMB did not find a DDI statement specifying a COBOL name for the field.
  • DDI-4002-00-I DDI-4003-00-I Name in excess of 30 characters right most truncated
    When processing *DDI statements, AMB found a NAME= followed by a name greater than 30 characters in length. AMB truncates the name, on the right, to a length of 30.
  • DDI-4004-00-I Foreign DBD referenced PCB processed
    PCB processed a referenced a DBD for an IGNORE option.
  • DDI-5000-00-D CREATE was unsuccessful for
    CREATE was unsuccessful for the entity named for reasons stated in prior error messages.
  • DDI-5001-00-D File boundary violation file may be full
    On a cancel of a CREATE, a boundary violation occurred on the DDI file, probably due to lack of space.
  • DDI-5002-00-D Update was unsuccessful for
    An UPDATE was unsuccessful for the entity named for reasons stated in prior error messages.
  • DDI-5003-00-D FILE BOUNDARY VIOLATION FILE MAY BE FULL
    On a cancel of an UPDATE, a boundary violation occurred on the DDI file, probably due to lack of space.
  • DDI-5004-00-D File boundary violation file may be full
    On a CREATE, a boundary violation occurred on the DDI file probably due to lack of space.
  • DDI-5005-00-D File boundary violation file may be full
    On an UPDATE, a boundary violation occurred on the DDI file, probably due to lack of space.
  • DDI-5006-00-D Symbol generation for unsuccessful Check error file
    Symbol generation for the named PSB or data view was unsuccessful for reasons stated in prior error messages.
  • DDI-5007-00-D Sym gen for successful see warnings
    Symbol generation for the PSB or data view named was successful but AMB issued warning messages in prior messages.
  • DDI-5008-00-D DDI info for was not added
    When processing the DDI statements, AMB did not add information to the DDI file for reasons stated in prior error messages.
  • DDI-5009-00-D File boundary violation STATUS file may be full
    When attempting to add or update records on the DDI file, a VSAM error occurred.
  • DDI-5010-00-D Create unsuccessful for
    The CREATE of an entity on the DDI file was unsuccessful for reasons mentioned in prior error messages.
  • DDI-5011-00-D Update unsuccessful for
    The update of an entity on the DDI file was unsuccessful for reasons mentioned in prior error messages.
  • DDI-5012-00-D Invalid parameters found check error file
    AMB found an invalid parameter for reasons mentioned in prior error messages.
Parent topic: AppMaster Builder Error Messages


DDI-1000-00-F DDI-1007-00-F DDI-1020-00-F UNTIL error PT-PACK too long

Fatal error, processing stopped. When unpacking data from the DDI file, a pointer calculated was out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1001-00-F DDI-1008-00-F DDI-1021-00-F UNTIL error PT-TEXT too long

Fatal error, processing stopped. When unpacking data from the DDI file, text calculated was out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1002-00-F Error in DELETE

Fatal error, processing stopped. When deleting an entity from the DDI file, a file error occurred.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1003-00-F Empty DDIFILE

Fatal error, processing stopped. AMB attempted to search the DDI file and found it empty.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check to be sure you are pointing to the correct DDI file. See Data View Manager for more information.

Parent topic: DDI- database definition messages


DDI-1004-00-F DDI-1022-00-F SAVE-CANCEL file access

Fatal error, processing stopped. A SAVE or CANCEL on the DDI file failed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1005-00-F DDI-1023-00-F CREATE-UPDATE file access

Fatal error, processing stopped. A CREATE or UPDATE on the DDI file failed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1006-00-F DDI-1024-00-F Record READ access

Fatal error, processing stopped. A READ on the DDI file failed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1007-00-F DDI-1000-00-F DDI-1020-00-F UNTIL error PT-PACK too long

Fatal error, processing stopped. When unpacking data from the DDI file, a pointer calculated was out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1008-00-F DDI-1001-00-F DDI-1021-00-F UNTIL error PT-TEXT too long

Fatal error, processing stopped. When unpacking data from the DDI file, text calculated was out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1009-00-F Unclear entity found reload into DDIFILE

An error occurred when reading the DDI file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Reload the entity into the file.

Parent topic: DDI- database definition messages


DDI-1010-00-F Parameter name too long

On the parameter NAME= the name that followed (a PSB or DBD name) was greater than 8 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1011-00-F Invalid parameter found

AMB found an invalid parameter. Valid parameters are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • $#& NOPHYS
  • CICS NAME=
  • NOPDS PSB=
  • DEBUG DBD=
  • PLI

Resolution:

Correct the error and resubmit.

Parent topic: DDI- database definition messages


DDI-1012-00-F Too many PSB names

You specified more than 1000 PSB names on the PSB= parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1013-00-F PSB and subschema not found

AMB did not find the named PSB and/or data view source in the appropriate directory.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1014-00-F Segment not found

AMB did not find the segment named in the PSB in either the DBD or the DDI statements source.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1015-00-F Segment parent not found

AMB did not find the segment parent specified on the PSB in the DBD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-1016-00-F UNTIL2 program error

Software error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1017-00-F DDG program error

Software error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1018-00-F Record not found

AMB did not find the named record in the DDI file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Reloading into the DDI file may be necessary.

Parent topic: DDI- database definition messages


DDI-1019-00-F Record is locked

The named record is locked on the DDI file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Run the DDI unlock utility and resubmit.

Parent topic: DDI- database definition messages


DDI-1020-00-F DDI-1007-00-F DDI-1000-00-F UNTIL error PT-PACK too long

Fatal error, processing stopped. When unpacking data from the DDI file, a pointer calculated was out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1021-00-F DDI-1008-00-F DDI-1001-00-F UNTIL error PT-TEXT too long

Fatal error, processing stopped. When unpacking data from the DDI file, text calculated was out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1022-00-F DDI-1004-00-F SAVE-CANCEL file access

Fatal error, processing stopped. A SAVE or CANCEL on the DDI file failed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1023-00-F DDI-1005-00-F CREATE-UPDATE file access

Fatal error, processing stopped. A CREATE or UPDATE on the DDI file failed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1024-00-F DDI-1006-00-F Record READ access

Fatal error, processing stopped. A READ on the DDI file failed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DDI- database definition messages


DDI-1025-00-F CREATE file access

Fatal error, processing stopped. A CREATE on the DDI file failed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure there is enough space for the entity on the DDI file and resubmit the job.

Parent topic: DDI- database definition messages


DDI-1026-00-F SAVE-CREATE file access

Fatal error, processing stopped. A CREATE or UPDATE on the DDI file failed. Contact your AMB Administrator.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1027-00-F DELETE file access

Fatal error, processing stopped. A DELETE on the DDI file failed. Contact your AMB Administrator.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1028-00-F Illegal version fld

While processing DDI statements for a DBD, AMB found a version field that is not-numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-1029-00-F Version fld too large

While processing DDI statements for a DBD, AMB found a version field that is greater than 255.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-1030-00-F Illegal MOD fld

While processing DDI statements for a DBD, AMB found a MOD field that is not numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-1031-00-F MOD fld too large

While processing DDI statements for a DBD, AMB found a MOD field is greater than 255.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-1032-00-F Did not find DBDNAME or PSBNAME parameter

While processing a PSB, AMB did not find the DBDNAME= or PSBNAME= parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-1033-00-F DBDNAME not found

While processing a PSB, AMB found the DBDNAME= parameter with a nonexistent name for the DBD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-1034-00-F DBD table limit exceeded max is 10

While processing a PSB, AMB detected more than 10 DBD references.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1035-00-F PSBNAME not found

While processing a PSB, the PSBNAME= parameter had no name associated with it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1036-00-F PSB table limit exceeded max is 10

While processing a PSB, AMB detected more than 10 PSB references.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1037-00-F Unexpected EOF on DBD-PSB file

AMB found a continuation character at the end of a PSB or DBD. AMB did not find a DBDGEN, FINISH, or END for a DBD; AMB did not find a PSBGEN or END for a PSB.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-1038-00-F DBD name 8 characters

AMB found a DBD name longer than 8 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1039-00-F Parm not DEBUG or IGNORE invalid

You passed an invalid keyword as a parameter to DDIDDG.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-1041-00-F Right paren missing on parm

You did not close a parameter with a right parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-1042-00-F No right paren found on parm

Parameter is missing a right parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2000-00-E Card must begin with xmlDDI

AMB found something other than *DDI starting in column 7 of the DDI source.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2001-00-E Invalid card type

DDI statements for VSAM processing must have a valid type starting in column 12. Valid types are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • VSM
  • REC
  • IDX
  • SUB

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2002-00-E DDNAME required for ALT indices

AMB requires A DDN= followed by a name up to 8 characters for alternate indices. This name is the VSAM ddname of the file where AMB defines the alternate index.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2003-00-E DDN for primary IDX VSM DDN

If you supply a ddname for a primary index, it must be the same name as the ddname of the file. If you do not supply a ddname, it defaults to the VSAM ddname.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2004-00-E Short name required for record

You must supply a short record name, maximum 8 characters, on all REC statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2005-00-E COPY parameter only allowed on the first REC

When defining a file with multiple records, only the first REC statement can have a COPY=. This copybook member should contain a definition for all records in the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2006-00-E MAXLEN required for record

All REC statements require a maximum record length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2007-00-E Record name missing

AMB did not find a NAME= parameter on a REC statement. AMB requires a COBOL record name up to 30 characters. The name of the first record is also the long file name for the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements or Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2008-00-E File DDN missing

AMB did not find a DDN= parameter on a VSM statement. AMB requires a ddname for the file; it can be up to 8 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2009-00-E Member name missing

AMB did not find a COPY= parameter followed by an 8 character name on a REC statement. This copybook member gives the record description.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2010-00-E Invalid copy source type

AMB found a SOURCE= parameter with a value other than P (PDS member) or C (COBOL copybook member).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2011-00-E Invalid file record type

AMB found a VSM statement with an invalid TYPE=. Valid record types are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • K(eyed) file
  • E(ntry) sequenced
  • R(elative) record

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2012-00-E MAX record length missing

All REC statements require MAXLEN= parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2013-00-E AVG length greater than maximum

On a variable length file, the average length of the record is larger than the maximum length. AVGLEN= should be less than or equal to MAXLEN=.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2014-00-E INDEX data missing for keyed file

You must code at least one IDX statement for a keyed VSAM file. The IDX statement must follow the first REC statement for the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2015-00-E Subschema name missing

AMB found a SUB statement without NAME=. This is the name of the VSAM data view and may be up to 8 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2016-00-E Subschema records missing

AMB found a SUB statement without REC=. This name should be the COBOL record name of the first record in the VSAM file and can be up to 30 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2017-00-E REC card has invalid keyword

AMB found a REC statement with an invalid keyword. Valid keywords are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • NAME=
  • MAXLEN=
  • SHORT=
  • AVGLEN=
  • COPY=
  • PREFIX=
  • SOURCE=

Resolution:

See Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2018-00-E SUB card has invalid keyword

AMB found a SUB statement with an invalid keyword. Valid keywords are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • ACCESS= or ACC=
  • ASSIGN= or AS=
  • BLOCK= or BLK=
  • LABEL= or LAB=
  • PROCOPT=
  • RECORD=

Resolution:

See Coding IMS DDI Statements or Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2019-00-E Invalid file processing option

AMB found a SUB statement with a PROCOPT= followed by an invalid processing option. Valid options are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • A(ll) options allowed (default)
  • G(et) allowed (read)
  • I(nsert) allowed
  • D(elete) allowed
  • R(eplace) allowed

Resolution:

See Coding IMS DDI Statements or Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-2020-00-E No PSBNAME or DBDNAME found

AMB did not find any PSB names or DBD names on the parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2021-00-E Improper format in the DBD parameter

AMB found an error specifying a second argument on the DBD= parameter. Either a right parenthesis is missing or you supplied a non-numeric character.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2023-00-E PROCSEQ OR INDICIES NOT IN DBD

When processing the PSB, AMB did not find a PROCSEQ or indices in the DBD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2024-00-E Segment not found for XDFLD

When processing the DBD, AMB did not find the specified segment for the XDFLD in the DDI file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2025-00-E Record not found

AMB did not find the named VSAM record on the DDI file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2026-00-E Unrecognized parameter

AMB found an invalid statement in the DBD, DDI statements, or PSB source.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check DDI syntax.

Parent topic: DDI- database definition messages


DDI-2027-00-E Illegal syntax in DDI card

AMB found a DDI statement with an illegal keyword. Valid keywords are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • DBD
  • REC
  • PSB
  • FLD

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2028-00-E Found card not starting with xmlDDI

AMB found a statement in the DDI source that did not start with *DDI.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2029-00-E Missing DBD name or access

When processing a DBD, AMB did not find the NAME= or ACCESS= parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2030-00-E Illegal dataset

You defined a label field in a data set statement without operands; but the access method specified in the DBD statement does not allow labeling without operands. Access must be HDAM or HIDAM.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2031-00-E No matching dataset label

You did not previously define the label specified on the current data set with operands.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2032-00-E No preceding segment for field

When processing a DBD, AMB found a FLD statement without a segment before it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2033-00-E No preceding segment for LCHILD

When processing a DBD, AMB found an LCHILD statement without a segment before it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2034-00-E No preceding segment for XDFLD

When processing a DBD, AMB found an XDFLD statement without a segment before it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2035-00-E Missing PSB name

The PSB name is missing from the parameter supplied to generate the step.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2036-00-E Missing or illegal PCB type

While processing a PCB, AMB found the TYPE = parameter missing or invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2037-00-E No previous PCB for SENSEG

While processing a PSB, AMB found a SENSEG parameter without a prior PCB statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2038-00-E No previous SENSEG for SENFLD

While processing a PSB, AMB found a SENFLD statement without a prior SENSEG statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2039-00-E Invalid keyword found on DBD ATTACH card

While processing a DBD, AMB found a DBD DDI statement with something other than name or version.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2040-00-E Continuation expected found end of file

AMB found a comma at the end of a DDI statement and the next READ found the end of file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2041-00-E Expected continuation not found

When processing the DDI statements, AMB found a statement with a comma at the end and you did not continue the statement on the next line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2042-00-E Attempt to update failed

Another job locked the DBD specified on the control card for update.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2043-00-E DBD not found

While reading the DDI file, AMB did not find the named DBD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure the DBD name on the DBD and DDI statements are the same. Check to see that the DBD named on the PSB is correct and check to see if you loaded the DBD in the DDI file. See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages
Related reference
Coding DDI Sources


DDI-2044-00-E PSB not found

While reading the DDI file, AMB did not find the named PSB.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure that you loaded the PSB into the DDI file. See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2045-00-E REC has no DBD before IT

When processing the DDI statements for the DBD, AMB found a REC statement without a DBD statement before it. See Coding IMS DDI Statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2046-00-E Illegal keyword found on REC attach card

AMB found an invalid keyword in the DDI source. Valid keywords are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • NAME
  • COPY
  • SEG
Parent topic: DDI- database definition messages


DDI-2047-00-E SEGMENT NOT FOUND

When processing the DDI statements for a DBD, the SEG= parameter named a segment not found in the DBD.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2048-00-E Fld has no REC before it

When processing the DDI statements, AMB found a FLD statement without a REC statement before it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2049-00-E Fld IMSNAME not found under segment

The IMSNAME keyword in the DDISRC must reference a DBDSRC NAME keyword defined in the segment being processed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-2050-00-E Illegal continuation

A nonblank character must be in column 72 for continuation, or continue the next line in column 16.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2051-00-E Illegal keyword found on fld attach card

While processing the DDI statements, AMB found a FLD statement with an invalid parameter. Valid FLD parameters are:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • NAME=
  • IMSNAME=
  • PIC=

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2052-00-E xmlDDI FLD card has no IMSNAME

While processing DDI statements for PCB-level DDI overrides, AMB encountered a FLD statement without a IMSNAME= keyword or with spaces following IMSNAME=. See Coding IMS DDI Statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2053-00-E A PCB card was not entered for all PCBs

While processing DDI statements for PCB-level overrides, you did not enter enough PCB statements to match all the TP and DB PCBs in the PSB. See Coding IMS DDI Statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-2054-00-E REC card has no PCB card before it

While processing DDI statements for PCB-level DDI overrides, AMB encountered a REC statement out of order. A REC statement must have a PCB statement preceding it. The proper statement sequence for PCB-level DDI statements is:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • *DDI PSB
  • *DDI PCB
  • *DDI REC
  • *DDI FLD

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2055-00-E PCB card has no PSB card before it

While processing DDI statements for a PCB-level override, AMB encountered a PCB statement out of order. A PCB statement must have a REC statement following it. The proper sequence for PCB-level DDI statements is:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

*DDI PSB

Resolution:

*DDI PCB

Resolution:

*DDI REC

Resolution:

*DDI FLD

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2056-00-E Invalid keyword found on PSB attach card

When processing a PSB statement for DDI overrides, AMB encountered a keyword other than NAME=. NAME= is the only valid keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements.

Parent topic: DDI- database definition messages


DDI-2057-00-E IDX only allowed for KSDS

In a VSAM file definition, AMB found an IDX statement for an ESDS or relative record file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-3000-00-N PSB and-or subschema not DLI or VSAM

While executing one step in the PSBGEN utility, AMB noticed the named PSB or data view is neither a DL/I nor VSAM type.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary. AMB continues processing.

Parent topic: DDI- database definition messages


DDI-4000-00-I Duplicate 01 name

While processing a DBD, AMB found a duplicate COBOL name on the DDI statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-4001-00-I Defaulted to 8 char IMSNAME

While processing a DBD, AMB did not find a DDI statement specifying a COBOL name for the field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: DDI- database definition messages


DDI-4002-00-I DDI-4003-00-I Name in excess of 30 characters right most truncated

When processing *DDI statements, AMB found a NAME= followed by a name greater than 30 characters in length. AMB truncates the name, on the right, to a length of 30.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See Coding IMS DDI Statements or Coding VSAM DDI Statements.

Parent topic: DDI- database definition messages


DDI-4004-00-I Foreign DBD referenced PCB processed

PCB processed a referenced a DBD for an IGNORE option.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: DDI- database definition messages


DDI-5000-00-D CREATE was unsuccessful for

CREATE was unsuccessful for the entity named for reasons stated in prior error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check error messages.

Parent topic: DDI- database definition messages


DDI-5001-00-D File boundary violation file may be full

On a cancel of a CREATE, a boundary violation occurred on the DDI file, probably due to lack of space.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Run the DDI unlock utility and increase the space on the DDI file.

Parent topic: DDI- database definition messages


DDI-5002-00-D Update was unsuccessful for

An UPDATE was unsuccessful for the entity named for reasons stated in prior error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check error messages.

Parent topic: DDI- database definition messages


DDI-5003-00-D FILE BOUNDARY VIOLATION FILE MAY BE FULL

On a cancel of an UPDATE, a boundary violation occurred on the DDI file, probably due to lack of space.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Run the DDI unlock utility and increase the space on the DDI file.

Parent topic: DDI- database definition messages


DDI-5004-00-D File boundary violation file may be full

On a CREATE, a boundary violation occurred on the DDI file probably due to lack of space.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Run the DDI unlock utility and increase the space on the DDI file.

Parent topic: DDI- database definition messages


DDI-5005-00-D File boundary violation file may be full

On an UPDATE, a boundary violation occurred on the DDI file, probably due to lack of space.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Run the DDI unlock utility and increase the space on the DDI file.

Parent topic: DDI- database definition messages


DDI-5006-00-D Symbol generation for unsuccessful Check error file

Symbol generation for the named PSB or data view was unsuccessful for reasons stated in prior error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: DDI- database definition messages


DDI-5007-00-D Sym gen for successful see warnings

Symbol generation for the PSB or data view named was successful but AMB issued warning messages in prior messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: DDI- database definition messages


DDI-5008-00-D DDI info for was not added

When processing the DDI statements, AMB did not add information to the DDI file for reasons stated in prior error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DDI-5009-00-D File boundary violation STATUS file may be full

When attempting to add or update records on the DDI file, a VSAM error occurred.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure there is enough space for the file. Run the DDI unlock utility and resubmit the job.

Parent topic: DDI- database definition messages


DDI-5010-00-D Create unsuccessful for

The CREATE of an entity on the DDI file was unsuccessful for reasons mentioned in prior error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check error messages.

Parent topic: DDI- database definition messages


DDI-5011-00-D Update unsuccessful for

The update of an entity on the DDI file was unsuccessful for reasons mentioned in prior error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check error messages.

Parent topic: DDI- database definition messages


DDI-5012-00-D Invalid parameters found check error file

AMB found an invalid parameter for reasons mentioned in prior error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DDI- database definition messages


DEF- internal AMB messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • DEF-9000-00-F DOS-LPTR and DOS-DSK not defined
    You did not define the DOS assignment default for the printer and disk.
  • DEF-9002-00-F Unknown system
    You did not define FMP variable, &SYSTEM for this compile or FMP did not recognize the system selected.
Parent topic: AppMaster Builder Error Messages


DEF-9000-00-F DOS-LPTR and DOS-DSK not defined

You did not define the DOS assignment default for the printer and disk.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Define the FMP variable &DOS-LPTR and &DOS-DSK (usually defined in SSTPARM).

Parent topic: DEF- internal AMB messages


DEF-9002-00-F Unknown system

You did not define FMP variable, &SYSTEM for this compile or FMP did not recognize the system selected.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Define FMP variable &SYSTEM to equal a recognized system.

Parent topic: DEF- internal AMB messages


DNA- internal AMB module messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • DNA-1000-00-E Requested DDNAME not found
    AMB could not locate data set name specified on the DD statement of the JCL.
  • DNA-1001-00-F I-O error in PDS directory
    A fatal I/O error occurred during Lookup routine processing for a member of the PDS.
  • DNA-1002-00-E Requested member not found
    AMB could not find the member requested via INCLUDE. Member was not in specified PDS or you misspelled the member name on the FMP % INCLUDE.
  • DNA-1003-00-F I-O error on CLOSE
    During CLOSE call processing, AMB detected a fatal I/O error. AMB issued the CLOSE call for an inactive channel. Probable internal logic error in AMB compiler.
  • DNA-1004-00-E BLK not LRECL mult
    During processing of DCB information, AMB determined the block size not to be a multiple of the record length.
  • DNA-1005-00-F I-O error FMT1 DSCB
    The error occurred during execution of an OPEN call instruction for a data set on a direct access device, for one of the following reasons:
  • DNA-1006-00-E VOL mount prob rerun
    No unit is available for mounting the specified volume. The volume already on the allocated unit is either permanently resident or reserved. It could not be unmounted in order to mount the required volume, or the volume cannot be unmounted because another DCB is open on that device.
  • DNA-1010-00-E Invalid concatenation
    You issued an open call instruction for a partitioned data set that you concatenated with a data set that does not reside on a direct access storage device (DASD). You can concatenate partitioned data sets only with data sets having like attributes.
  • DNA-1011-00-E Unknown - see SYSMSG
    During I/O processing, AMB detected an error but the I/O program that reads FMP % INCLUDE files was unable to analyze the error.
  • DNA-1012-00-E Program error - contact your AMB rep
    This error message indicates an internal error within AMB compiler (portion that reads % INCLUDE files). During I/O processing, AMB issued an OPEN or READ call for a channel that did not have a prior LOOKUP or CLOSE call. The channel number passed from SSTCTIM to SSTDDNA is less than 1 or greater than the maximum number of channels. You passed an invalid call code from SSTCTIM to SSTDDNA.
  • DNA-1013-00-E No storage for buffer allocation
    You issued a GETMAIN and AMB could not allocate storage. There is an inadequate region size for the program being compiled.
Parent topic: AppMaster Builder Error Messages


DNA-1000-00-E Requested DDNAME not found

AMB could not locate data set name specified on the DD statement of the JCL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all of your INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries.

Parent topic: DNA- internal AMB module messages


DNA-1001-00-F I-O error in PDS directory

A fatal I/O error occurred during Lookup routine processing for a member of the PDS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries. Check the PDS manually by attempting to browse the member (ISPF=1) or examine the member list (ISPF=3.1). If PDS looks correct, try job again. If error persists, contact your AMB Administrator.

Parent topic: DNA- internal AMB module messages


DNA-1002-00-E Requested member not found

AMB could not find the member requested via INCLUDE. Member was not in specified PDS or you misspelled the member name on the FMP % INCLUDE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all of your INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries.

Parent topic: DNA- internal AMB module messages


DNA-1003-00-F I-O error on CLOSE

During CLOSE call processing, AMB detected a fatal I/O error. AMB issued the CLOSE call for an inactive channel. Probable internal logic error in AMB compiler.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DNA- internal AMB module messages


DNA-1004-00-E BLK not LRECL mult

During processing of DCB information, AMB determined the block size not to be a multiple of the record length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check DD statements in call libraries for correct DCB, LRECL and BLKSIZE values. Possibly correct block size in the DCB.

Parent topic: DNA- internal AMB module messages


DNA-1005-00-F I-O error FMT1 DSCB

The error occurred during execution of an OPEN call instruction for a data set on a direct access device, for one of the following reasons:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • An I/O error occurred reading the FORMAT1 DSCB, or
  • AMB could not find the FORMAT1 DSCB for the data set in any of the following places:
    1. The first volume specified by the DD statement
    2. The volume indexed by the volume sequence number
    3. The catalog

Resolution:

If you cannot find the FORMAT1 DSCB for the data set, ensure that the DSNAME and volume parameters are correct.

Inspect all of your INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries.

Parent topic: DNA- internal AMB module messages


DNA-1006-00-E VOL mount prob rerun

No unit is available for mounting the specified volume. The volume already on the allocated unit is either permanently resident or reserved. It could not be unmounted in order to mount the required volume, or the volume cannot be unmounted because another DCB is open on that device.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all of your INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries. Try rerunning the job. If the problem occurs again, contact the operator to check if there is a problem with the mounted device.

Parent topic: DNA- internal AMB module messages


DNA-1010-00-E Invalid concatenation

You issued an open call instruction for a partitioned data set that you concatenated with a data set that does not reside on a direct access storage device (DASD). You can concatenate partitioned data sets only with data sets having like attributes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all of your INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries for compatibility of DCB information.

Parent topic: DNA- internal AMB module messages


DNA-1011-00-E Unknown - see SYSMSG

During I/O processing, AMB detected an error but the I/O program that reads FMP % INCLUDE files was unable to analyze the error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all of your INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries. See your IBM System Messages and Codes manual for information on the error.

Parent topic: DNA- internal AMB module messages


DNA-1012-00-E Program error - contact your AMB rep

This error message indicates an internal error within AMB compiler (portion that reads % INCLUDE files). During I/O processing, AMB issued an OPEN or READ call for a channel that did not have a prior LOOKUP or CLOSE call. The channel number passed from SSTCTIM to SSTDDNA is less than 1 or greater than the maximum number of channels. You passed an invalid call code from SSTCTIM to SSTDDNA.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries. Contact your AMB Administrator.

Parent topic: DNA- internal AMB module messages


DNA-1013-00-E No storage for buffer allocation

You issued a GETMAIN and AMB could not allocate storage. There is an inadequate region size for the program being compiled.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all of your INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Also check DD statements for call libraries. Increase region size for this particular compile.

Note: MVS users should note that the region size on the job card overrides the region size on individual step cards.
Parent topic: DNA- internal AMB module messages


DOC- Painter messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • DOC-0000-00-I Copyright year MICRO FOCUS &ampsq&ampAPS-rel &amppgm-id &ampcompiletime&ampsq
    Internal AMB copyright marker for AMB load modules.
  • DOC-1000-00-W Selected entity not painted
  • DOC-1001-00-W Entity does not exist or is a bad entity
  • DOC-5000-00-E Selected entity does not exist
  • DOC-5001-00-E Empty SDFILE No screens were found in the SD file
  • DOC-5002-00-E Selection criteria not met
    Entity within the entered selection criteria was not found.
  • DOC-5003-00-E Only 3 selections allowed
    More than three selection criteria were found. Internal error.
  • DOC-7000-00-F No execution parameters found
    Parameters for program execution are missing.
  • DOC-7001-00-F Illegal entity name
    The entity name is less than four characters or greater than eight.
  • DOC-7002-00-F Illegal entity type
    The entity type should be PG, SC, DS, SS, ML, or RP.
  • DOC-7003-00-F Illegal parameter
    Unknown parameter found. Internal error.
  • DOC-7004-00-F Equal sign missing in parms
  • DOC-7005-00-F Illegal date selection
    Date entered is not correctly formatted.
  • DOC-7006-00-F Unknown selection
    Selection made is unknown.
  • DOC-9000-00-F Duplicate sort entry found in table -
    A duplicate Sort entry was found in the specified table.
  • DOC-9050-00-F Table overflow - -2 Max nbr of members in PDS exceeded Table size is 2000
    Internal error.
Parent topic: AppMaster Builder Error Messages


DOC-0000-00-I Copyright year MICRO FOCUS &ampsq&ampAPS-rel &amppgm-id &ampcompiletime&ampsq

Internal AMB copyright marker for AMB load modules.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: DOC- Painter messages


DOC-1000-00-W Selected entity not painted

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for spelling error, or create the entity.

Parent topic: DOC- Painter messages


DOC-1001-00-W Entity does not exist or is a bad entity

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for spelling error.

Parent topic: DOC- Painter messages


DOC-5000-00-E Selected entity does not exist

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for spelling error or create entity.

Parent topic: DOC- Painter messages


DOC-5001-00-E Empty SDFILE No screens were found in the SD file

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for correct project and group entry.

Parent topic: DOC- Painter messages


DOC-5002-00-E Selection criteria not met

Entity within the entered selection criteria was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DOC- Painter messages


DOC-5003-00-E Only 3 selections allowed

More than three selection criteria were found. Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DOC- Painter messages


DOC-7000-00-F No execution parameters found

Parameters for program execution are missing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DOC- Painter messages


DOC-7001-00-F Illegal entity name

The entity name is less than four characters or greater than eight.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DOC- Painter messages


DOC-7002-00-F Illegal entity type

The entity type should be PG, SC, DS, SS, ML, or RP.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DOC- Painter messages


DOC-7003-00-F Illegal parameter

Unknown parameter found. Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DOC- Painter messages


DOC-7004-00-F Equal sign missing in parms

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check PROC statement or contact your AMB Administrator.

Parent topic: DOC- Painter messages


DOC-7005-00-F Illegal date selection

Date entered is not correctly formatted.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DOC- Painter messages


DOC-7006-00-F Unknown selection

Selection made is unknown.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: DOC- Painter messages


DOC-9000-00-F Duplicate sort entry found in table -

A duplicate Sort entry was found in the specified table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DOC- Painter messages


DOC-9050-00-F Table overflow - -2 Max nbr of members in PDS exceeded Table size is 2000

Internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: DOC- Painter messages


FMP- AMB Generator errors

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • FMP-1000-00-F FMP-1000-40-F No more core
    The amount of core given in the EXEC statement is exceeded, or no more core was available on the system when a GETMAIN was issued. Possibly, an FMP loop limit was previously raised and the loop is causing the program to use additional core.
  • FMP-1003-00-F Main source missing
    Program specified on the DD statement as the source for a compile was not found.
  • FMP-1004-00-F Too many active INCLUDEs
    Maximum number of % INCLUDEs in one program (8) exceeded. Active % INCLUDEs refer to the number of ddnames.
  • FMP-1005-00-F Submember not found
    On a % INCLUDE statement, the named submember was not found.
  • FMP-1006-01-F Invalid EVAL-BRACKETS
    Evaluation brackets are invalid or were not set properly. Evaluation brackets cannot be a numeric, alpha, quote, apostrophe, left or right parenthesis; we recommend using the less-than and greater-than characters <>.
  • FMP-1006-02-F Invalid EVAL-BRACKETS-AUX
    Auxiliary evaluation brackets are invalid or were not set properly. Evaluation brackets cannot be a numeric, alpha, quote, apostrophe, left or right parenthesis.
  • FMP-1007-00-F No in-line macros in FMP REPEAT loop test
    During processing of an FMP REPEAT loop test, an in-line call was found.
  • FMP-1008-00-F No in-line macros in FMP ELSE-IF
    During processing of an FMP ELSE-IF test, an in-line call was found.
  • FMP-1009-01-F SYM table full
    During FMP processing the internal symbol table exceeded allocated size.
  • FMP-1010-00-F No more line buffers
    Line buffer for FMP was exceeded. FMP program requires more line buffers.
  • FMP-1011-00-F Too many DECLARE &ampMSG-PART
    The maximum number of DECLAREs allowed for one program (200) was exceeded.
  • FMP-1012-00-F Loop limit reached
    The maximum number of FMP loops (initiated by % REPEAT, % UNTIL, % WHILE) performed during processing is equal to the setting of the loop limit counter % SET LOOP-LIMIT (default = 200) or &D2-TOKEN-MAX.
  • FMP-1013-00-F Missing Data Division statement
    Data Division header either not found, not in the correct place (columns 8-11), or misspelled.
  • FMP-1014-00-F Missing Environment Division stmt
    Environment Division header either not found, not in the correct place (columns 8-11), or misspelled.
  • FMP-1015-00-F Missing ID Division statement
    Identification Division header not found, in wrong place, or misspelled.
  • FMP-1016-00-F Missing Procedure Division statement
    Procedure Division header not found, in wrong place, or misspelled.
  • FMP-1017-00-F Submember must be in library file
    The submember named in a % INCLUDE statement does not exist.
  • FMP-1018-00-F Unprivileged FMP use
    Program has attempted to enter the module for processing FMP.
  • FMP-1019-00-F Unterminated report or map mock-up
    Execution halts. Report or map mock-up opening delimiters were read, but no closing delimiters are found.
  • FMP-1020-00-F Requested member not found
    The member included by a % INCLUDE was not found. Member was not in specified PDS or member name was misspelled on FMP % INCLUDE.
  • FMP-1022-00-E Requested DDNAME not found
    Data set name specified on the DD statement could not be located.
  • FMP-1023-00-E No storage for buffer allocation
    A GETMAIN was issued and storage could not be allocated. There is an inadequate region size for the program being compiled.
  • FMP-1024-00-F I-O error in PDS directory
    A fatal I/O error occurred when processing a LOOKUP routine for a PDS member.
  • FMP-1025-00-E Program error - contact your AMB rep
    An internal error within the AMB compiler (portion that reads % INCLUDE files) occurred. During I/O processing an OPEN or READ call was issued for a channel that did not have a prior LOOKUP or CLOSE call. The channel number passed from SSTCTIM to SSTDDNA is less than 1 or greater than the maximum number of channels. An invalid call code was passed from SSTCTIM to SSTDDNA.
  • FMP-1026-00-F I-O error on CLOSE
    CLOSE call was issued for an inactive channel. Probable internal logic error in AMB compiler.
  • FMP-1027-00-E BLK not LRECL mult
    When processing DCB information, the block size was not a multiple of the record length.
  • FMP-1028-00-F I-O error FMT1 DSCB
    The error occurred executing an OPEN call instruction for a data set on a direct access device. An I/O error occurred reading the FORMAT1 DSCB. Or, the FORMAT1 DSCB for the data set could not be found either on the first volume specified by the DD statement, the volume indexed by the volume sequence number, or in the catalog.
  • FMP-1029-00-E VOL mount prob rerun
    No unit is available for mounting the specified volume. The volume already on the allocated unit is either permanently resident or reserved. It could not be unmounted in order to mount the required volume, or the volume cannot be unmounted because another DCB is open on that device.
  • FMP-1030-00-E INVALID CONCATENATION
    An open call instruction was issued for a partitioned data set concatenated with a data set that does not reside on a direct access storage device (DASD). Partitioned data sets can be concatenated only with data sets having like attributes.
  • FMP-1031-00-E Unknown - see SYSMSG
    During I/O processing an error was detected but the I/O program that reads FMP % INCLUDE files could not analyze the error.
  • FMP-1201-00-F INCLUDE name illegal
    The member name in an % INCLUDE statement is not a valid file name.
  • FMP-1202-00-F SET AUXILIARY-INPUT not implemented
    Auxiliary input is not supported in this implementation.
  • FMP-1203-00-E Cannot split line correctly
    An attempt was made to expand an S-COBOL line that could not be continued correctly on a second line.
  • FMP-1204-00-W Line broken into two lines
    A generated output line was continued on a second line.
  • FMP-1206-00-W SPLITTING COBOL IDENTIFIER
    A COBOL data name is continued on a second line.
  • FMP-2000-00-E Not fix len string
    A DECLARE part was given a picture and length but the symbol it represents is not a fixed length.
  • FMP-2004-00-E Incompat DCLR stms
    The DECLARE variable is incompatible with another DECLARE statement.
  • FMP-2005-00-E Invalid DCLR value
    DECLARE variable was not numeric, a string, or another DECLARE variable.
  • FMP-2006-00-E DCLR part undef
    During DECLARE USE, a DECLARE part was found with no defined value.
  • FMP-2007-00-E Invalid DCLR sub
    This message occurs when attempting to use a variable as a subscript which was already defined to FMP as a nonsubscript. Possibly a Declare part was used as a Declare subscript.
  • FMP-2008-00-E Part not unique
    All parts of DECLARE variables must have unique names.
  • FMP-2009-00-E Value not string
    During DECLARE processing, a test was made for a string but the element was numeric.
  • FMP-2010-00-E Compound built-in function
    This is caused by using a built-in function as an argument within another built-in function. This is allowed only when:
  • FMP-2011-00-E DCLR part required
    % LOOKUP can only reference DECLARE parts.
  • FMP-2012-01-E Indentation error decreased
    The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the block must then use the same indentation increment established by the first indented statement, until a new block begins. For further processing, the line indentation is decreased to the level of the current indentation.
  • FMP-2012-02-E Invalid indentation
    The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the block must then use the same indentation increment established by the first indented statement, until a new block begins.
  • FMP-2013-00-E Unallowed code at end of FMP line
    The code following an ELSE statement is not allowed.
  • FMP-2014-00-E Operator expected in line
    An arithmetic or logical operator was expected in the flagged line.
  • FMP-2015-00-E Non-numeric destination in arith operation
    When evaluating an arithmetic expression, an FMP variable was determined to be non-numeric.
  • FMP-2016-00-E Division by 0 not allowed
    When evaluating a division statement, an attempt to divide by zero was detected.
  • FMP-2017-00-F Invalid indent in loop
    The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the loop must use the same indentation increment established by the first indented statement, until the loop ends.
  • FMP-2018-00-E REPEAT is an improper FMP loop termination
    REPEAT was coded instead of a WHILE or UNTIL clause with a test in an FMP loop.
  • FMP-2019-00-E Missing REPEAT VARYING variable
    The FMP variable being varied in an FMP loop is missing.
  • FMP-2020-00-E Left parenthesis expected
    A call name or a built-in function is followed by something other than a left parenthesis.
  • FMP-2021-00-E Parameter list overflow for macro
    Too many arguments (maximum is 40) were coded for a call.
  • FMP-2022-00-E Too many invoking parameters
    Too many arguments were coded when calling a call defined with nn number of arguments.
  • FMP-2023-00-E Argument not FMP variable
    The argument was not prefixed by an ampersand (&), or a string constant was not enclosed by quotes.
  • FMP-2024-00-E Undefined ARG
    Either a user call was coded with arguments, or a call was not defined with arguments.
  • FMP-2025-00-E Argument not a string
    Invalid arguments were coded on the invoking call statement. The call expects a string argument.
  • FMP-2026-00-E Not FMP string variable
    An FMP string variable was not used in a built-in call that required one.
  • FMP-2027-00-E Right paren expected
    An argument list was not followed by a right parenthesis.
  • FMP-2030-00-E SET coded in improper location
    A % SET WORKING STORAGE, FILE, FILE-CONTROL, LINKAGE, DATA, or SPECIAL-NAMES was encountered somewhere other than the Procedure Division or procedural code.
  • FMP-2031-00-E SET END WORKING STORAGE in wrong location
    The statement was found outside of the Working-Storage section.
  • FMP-2032-00-E Width must be at least &amp
    Statement testing for the left and right margins either begins before column 7 or goes beyond column 72.
  • FMP-2033-00-E Improper coding of EPILOGUE macro
    The epilogue call is invalid.
  • FMP-2034-00-E Invalid SET statement
    Invalid syntax or spelling error.
  • FMP-2035-00-E Improper location
    Possibly there is a % SET statement syntax error, invalid location, or indentation error.
  • FMP-2036-00-E Linkage Section header not in proper order
    Linkage Section header is coded after the Communication Section.
  • FMP-2037-00-E Macro name must start with $
    A call name must be prefixed by a dollar sign $.
  • FMP-2038-00-E Variable must start with &amp
    FMP variables must start with an ampersand (&).
  • FMP-2039-00-E DECLARE items invalid as formal arguments
    A DECLARE item cannot be used as a formal (dummy) argument for an FMP call.
  • FMP-2040-00-E Default value not number or string
    Evaluation of a DEFINE statement detected use of something other than a number or string as a default call argument.
  • FMP-2041-00-E Invalid indent in def
    The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the block must use the same indentation increment established by the first indented statement, until a new block begins.
  • FMP-2042-00-E Unrecognized control cards parameter
    % SET CONTROL-CARDS was not followed by LEADING, TRAILING, or END.
  • FMP-2043-00-E String expected
    During internal processing of an FMP statement, a string was expected and not found.
  • FMP-2044-00-E Cannot shift line
    When processing a statement using eval-brackets, the statement expanded beyond column 72.
  • FMP-2045-00-E FMP-2054-00-E Right evaluation bracket expected
    A right evaluation bracket is expected and not found.
  • FMP-2050-00-E Compound logic illegal
    Use of compound logic (AND and OR used together) in an FMP conditional or loop statement is illegal.
  • FMP-2052-00-E Non-numeric elem used in arith expression
    When evaluating an arithmetic expression (statement containing a + - * /) a non-numeric field was found.
  • FMP-2053-00-E Invalid element
    Element, evaluated during a user call or in an FMP expression, was not a numeric, a string, or an ampersand.
  • FMP-2054-00-E FMP-2045-00-E Right evaluation bracket expected
    A right evaluation bracket is expected and not found.
  • FMP-2055-00-E Unmatched right evaluation bracket
    During evaluation scanning, a right evaluation bracket was paired with a left evaluation bracket.
  • FMP-2056-00-E Infinite evaluation loop
    When processing an evaluation statement, the internal counter exceeded 100.
  • FMP-2057-00-E Auxiliary input not active
    This error occurs when the request is not available to the user, or when the parameters are not set properly.
  • FMP-2058-00-E Improper date argument
    The date format passed to AMB was incorrect.
  • FMP-2059-00-E &ampAPS-HALF not defined
    Variable &APS-HALF was not defined properly.
  • FMP-2060-00-E Non-numeric variable
    When evaluating an internal date/time routine, something other than a numerically defined FMP variable was found.
  • FMP-2061-00-E Comma expected
    When evaluating FMP statement, a comma was expected but not found.
  • FMP-2062-00-E &ampAPS-FULL not defined
    Variable &APS-FULL was not defined properly.
  • FMP-2063-00-E Non-numeric arg
    A non-numeric argument was supplied to a built-in function that requires a numeric argument.
  • FMP-2064-00-E Right paren or comma expected
    Evaluation of a statement terminated incorrectly. Either a right parenthesis was omitted, or a comma was not used as a delimiter between fields.
  • FMP-2065-00-E First argument not text string variable
    The first argument of the PARSE built-in function is not an FMP string (text) variable.
  • FMP-2067-00-E DECLARE variable not parsable
    The &PARSE function cannot be used on DECLARE parts.
  • FMP-2068-00-E Improper argument
    An argument used with a built-in function is not a numeric, a string, or an ampersand.
  • FMP-2069-00-E Not macro or FMP variable name
    When evaluating a statement starting with $ or &, the call or variable in question could not be found.
  • FMP-2070-00-E Not an FMP variable or number
    When evaluating an element, the element was not defined as a variable or a numeric.
  • FMP-2071-00-E Numeric expected When evaluating an element FMP expected a numeric
    Correct element to be numeric.
  • FMP-2072-00-E String too long truncated
    Evaluation of a string in quotes is too long.
  • FMP-2073-00-E Non-numeric sequence number
    Numbering of generated code can not be handled because a non-numeric is in columns 1 through 6.
  • FMP-2074-00-E Non-numeric WYLBUR
    Wylbur sequence numbering was requested via parameter and the numbering could not be done for the generated code.
  • FMP-2075-01-E SEQUENCE NUMBER TOO LARGE
    Sequence numbering exceeds limit for numbering. Limit is 999,999.
  • FMP-2075-02-E NON-NUMERIC SEQUENCE NUMBER
    Numbering of generated code can not be handled because a non-numeric is in columns 1 through 6.
  • FMP-2076-00-E Non-numeric identifier in column 73-80
    Non-numeric characters are found in columns 73-80.
  • FMP-2077-00-E Statement not allowed in column 7
    Only comment or continuation characters are allowed in column 7. A shift right was attempted but the statement went to column 72 and the shift could not be accomplished.
  • FMP-2078-00-E DECLARE variable must start with &amp
    When evaluating a DECLARE variable, the FMP special character for identifying variables (&) was not found.
  • FMP-2079-00-E DECLARE subscript must start with &amp
    When evaluating a DECLARE subscript, the FMP special character for identifying DECLARE subscripts (&) was not found.
  • FMP-2080-00-E expected during DECLARE processing
    You mistyped or left out % before DECLARE parts.
  • FMP-2081-00-E DECLARE part above not a group
    A DECLARE part can reference several elementary level DECLARE parts. To do this, the group DECLARE part cannot have a picture and the subordinate DECLARE parts must be indented under the group level DECLARE part.
  • FMP-2083-00-E DECLARE part must start with &amp
    When evaluating a DECLARE part variable, the FMP special character for identifying variables (&) was not found.
  • FMP-2084-00-E Improper declare var type
    A DECLARE part can be defined as numeric or string only.
  • FMP-2085-00-E DECLARE string over 78 bytes
    The value of a DECLARE part cannot exceed 78 characters.
  • FMP-2086-00-E Part value not numeric
    During DECLARE processing, a numeric variable was given a nonnumeric value.
  • FMP-2087-00-E LOOKUP requires variable
    % LOOKUP must reference a defined DECLARE part variable.
  • FMP-2088-00-E Invalid LOOKUP relation
    Relational operator in the % LOOKUP is incorrect.
  • FMP-2089-00-E DECLARE part and value incompatible
    In an arithmetic expression, a numeric DECLARE part was given a non-numeric value.
  • FMP-2090-00-E THRU-TO value should be numeric
    In a REPEAT VARYING loop, the THRU/TO values were not numeric.
  • FMP-2091-00-E Starting value should be numeric
    In a REPEAT VARYING loop, the FROM value was not numeric.
  • FMP-2092-00-E No subscripts found
    The field was defined as an OCCURS, but the subscript was omitted when the field was referenced in code.
  • FMP-2093-00-E Only one subscript found
    An element was defined in a two dimensional table. When the element was used, only one subscript applied.
  • FMP-2094-00-E Low-order subscript must be numeric
    If the FROM clause in a LOOKUP is omitted, the low-order subscript must contain a numeric value.
  • FMP-2095-00-E FMP cont ( ) expected but not found
    The FMP call arguments begun on a previous line were not closed with a right parenthesis. Therefore, continuation of the arguments was expected on the next line, but the % ... expected to signal the continuation was not found.
  • FMP-2096-00-E The word DIVISION expected assumed
    Division header does not show the word DIVISION. Processing resumes as if present.
  • FMP-2097-00-E ELSE does not match IF
    % ELSE was encountered at a level of indentation for which no % IF was previously encountered.
  • FMP-2098-00-E ELSE-IF does not match IF
    % ELSE-IF was encountered at a level of indentation for which no % IF was previously encountered.
  • FMP-2100-00-E Unallowed code follows REPEAT
    % REPEAT is followed by something other than VARYING on the same line.
  • FMP-2101-00-E Invalid evaluation expression
    Expression within evaluation brackets is not correct.
  • FMP-2102-00-E Invalid argument following macro call
    Argument following FMP user call is not an FMP variable, a numeric literal, or an alphanumeric string (enclosed in quotes).
  • FMP-2103-00-E Left paren needed after DEFINE
    A % DEFINE $DATANAME is followed by code not beginning with a left parenthesis.
  • FMP-2104-00-E Map section already seen
    A second Map section header was encountered.
  • FMP-2105-00-E Missing PROGRAM-ID statement
    Make sure the PROGRAM-ID statement follows the ID division header and begins in margin A (columns 8-11).
  • FMP-2106-00-E Modified line too wide
    After resolution of evaluation brackets, the remaining line of COBOL extends past column 72.
  • FMP-2107-00-E Relation condition not valid
    The relation condition following an FMP conditional verb (% IF, % ELSE-IF, % WHILE, % UNTIL) is not valid.
  • FMP-2108-00-E Report Section already seen
    Use only one Report Section header, even if there are multiple reports in the program.
  • FMP-2109-00-E The word SECTION not found or missing period
    The word SECTION is missing from a Section Header line or period is missing.
  • FMP-2110-00-E Too many digits in number
    Integer to be processed by FMP exceeds 999,999.
  • FMP-2111-00-E Undefined DEF
    Call is called that was not defined.
  • FMP-2112-00-E Undefined symbol &amp
    Symbolic variable was encountered for which no value is assigned. This variable can reside within a line of the source program, or as the value of another symbolic variable.
  • FMP-2113-00-E Undefined word after
    Word encountered following a % is not an FMP keyword or a symbolic variable name.
  • FMP-2114-00-E Unmatched quote
    String was opened with a single or double and was not closed on the same line with the same delimiter.
  • FMP-2115-00-E &amp followed by space improper FMP stm
    An FMP statement begins with an ampersand (followed by a space) instead of a percent.
  • FMP-2205-00-E Macro definition not allowed
    An unauthorized use of AMB Customizer was attempted.
  • FMP-2207-00-E LOOKUP &ampFLDNAME is a part
    The &FLDNAME in a LOOKUP operation has the same name as a &PART.
  • FMP-2208-00-E LOOKUP &ampFLDNAME is a predefined name
    A &FLDNAME in a LOOKUP operation has cannot have the same name as a predefined name.
  • FMP-2209-00-E UNTIL expected in loop repetition
    EVAL BRACKET reevaluation action failed to generate the expect % UNTIL or % WHILE for % REPEAT or % R-V processing.
  • FMP-2210-00-E WHILE expected in loop repetition
    EVAL BRACKET reevaluation action failed to generate the expect % UNTIL or % WHILE for % REPEAT or % R-V processing.
  • FMP-2219-00-E &ampDEFVAL value undefined
    &DEFVAL is undefined because a &DEFINED test has either not yet occurred or has tested false.
  • FMP-2220-00-E &ampFLDNAME for &ampPART has no &ampSUBs in LOOKUP
    Attempted a LOOKUP against a &PART belonging to a &FLDNAME that has no &SUBs.
  • FMP-2221-00-E &ampFLDNAME is &ampPART
    &FLDNAME cannot have the same name as a &PART.
  • FMP-2222-00-E &ampFLDNAME text is not valid
    A &FLDNAME name is invalid.
  • FMP-2223-00-E &ampFLDNAME value illegal
    The content of a % DECLARE subscript resolved &FLDNAME to the name of an already defined &FLDNAME, call name, or FDEFINE name.
  • FMP-2224-00-E &ampFLDNAME value is numeric
    An attempt was made to reference an &PART defined under an &FLDNAME that was set to numeric.
  • FMP-2225-00-E &ampFLDNAME value is predefined name
    An &FLDNAME was resolved to a predefined name.
  • FMP-2226-00-E &ampINDEX requires two arguments
    The two required arguments for &INDEX were not coded.
  • FMP-2227-00-E &ampLENGTH requires one argument
    The required argument for &LENGTH was not coded.
  • FMP-2228-00-E &ampNUMERIC requires one argument
    The required argument for &NUMERIC was not coded.
  • FMP-2229-00-E &ampPARSE argument is predefined &ampVARIABLE
    An argument to the &PARSE predefined function cannot be a predefined function.
  • FMP-2233-00-E &ampSUB is predefined function
    An &SUB cannot have the same name as a predefined function.
  • FMP-2234-00-E &ampSUB undefined
    A reference was made to an undefined &SUB for a % DECLARE
  • FMP-2235-00-E &ampSUBSTR position parameter is not 0
    The value for the position parameter in a &SUBSTR operation was either coded as 0, or evaluated to 0.
  • FMP-2236-00-E &ampSUBSTR requires either 2 or 3 arguments
    An &SUBSTR operation is missing the minimum number of arguments.
  • FMP-2237-00-E &amp is a predefined name in R-V
    A predefined variable name was used in a % R-V operation.
  • FMP-2238-00-E &ampVARIABLE is a text &ampPART in R-V
    An attempt was made to use a text part in a numeric % R-V operation.
  • FMP-2239-00-E &ampVARIABLE value is text in REPEAT VARYING
    A text variable was used in a % R-V operation.
  • FMP-2240-00-E Argument required for &ampDEFINED
    A variable name was not specified in an &DEFINED test.
  • FMP-2241-00-E Arguments required for &ampPARSE
    No arguments were specified in an &PARSE operation.
  • FMP-2242-00-E Arguments required for built-in function
    Built-in function requires argument(s).
  • FMP-2243-00-E BY expression is text in REPEAT VARYING
    The BY increment variable is a text variable.
  • FMP-2244-00-E Cant store &ampPART in numeric &ampFLDNAME
    A value was assigned to an &PART belonging to an &FLDNAME set to a numeric value.
  • FMP-2245-00-E Cannot break line correctly
    Cannot continue an S-COBOL data name.
  • FMP-2247-00-E DECLARE part must start with &amp
    DECLARE PART name does not have a leading &.
  • FMP-2248-00-E Expression expected at end of line
    The call processor syntax expects an expression at the end of the line, probably following an OR operator.
  • FMP-2249-00-E Expression expected
    The call processor syntax expects an expression somewhere in the line.
  • FMP-2250-00-E FLDNAME is PART or SUB
    A FLDNAME was defined with the same name as a previously defined &PART or &SUB
  • FMP-2251-00-E FROM expression is TEXT REPEAT VARYING
    A FROM expression evaluated to TEXT.
  • FMP-2252-00-E FROM value does not fit &ampPART
    FROM numeric value in % R-V does not fit in &PART.
  • FMP-2253-00-E Illegal REDEFINES in &ampPART
    A DECLARE item was not redefined at the same level of indentation.
  • FMP-2254-00-E Indent of changed by EVAL BRKTS
    An EVAL BRACKET action inserted a space in the beginning of the line, causing an indentation error.
  • FMP-2255-00-E Invalid &ampFLDNAME in DECLARE
    &FLDNAME is coded with illegal syntax.
  • FMP-2256-00-E Invalid loop limit
    LOOP LIMIT cannot be greater than 32,767.
  • FMP-2257-00-E Invalid PICTURE
    DECLARE PART picture is invalid.
  • FMP-2259-00-W Invalid text after macro call
    Unrecognizable text trails the closing right parenthesis of a call invocation.
  • FMP-2260-00-E Invalid WRITE-CONTROL limit
    WRITE-CONTROL LIMIT cannot be greater than 32,767.
  • FMP-2261-00-E Left operand must be numeric
    In an arithmetic assignment, the left operand is not numeric.
  • FMP-2262-00-E Macro name may not be $ alone
    A call name was not prefixed with a $.
  • FMP-2263-00-E Member not found
    The requested member in an INCLUDE was not found.
  • FMP-2264-00-E Missing member name in INCLUDE
    The member name was omitted in a % INCLUDE statement
  • FMP-2265-00-E Mockup line truncated
    A mockup line expansion caused truncation.
  • FMP-2266-00-E More than one BY clause in R-V
    More than one BY clause was coded in a % R-V operation.
  • FMP-2267-00-E More than one FROM clause in R-V
    More than one FROM clause was coded in a % R-V operation.
  • FMP-2268-00-E More than one TO-THRU clause in R-V
    More than one TO/THRU clause was coded in a % R-V operation.
  • FMP-2269-00-E NEXT-TO-LAST &ampSUB not defined
    Two low order subs were specified in a % LOOKUP call and only one low order sub was coded.
  • FMP-2270-00-E No DDNAME in INCLUDE
    DDNAME missing from % INCLUDE statement
  • FMP-2271-00-E Non-numeric source in arith operation
    Right-side variable in an operator assignment is text, instead of numeric.
  • FMP-2272-00-E Numeric compared with text in LOOKUP
    A numeric variable was compared with a text variable in % LOOKUP processing.
  • FMP-2275-00-E Positive integer expected
    A % SET statement requires a positive integer.
  • FMP-2277-00-E Quotes or &amp required on identifier
    Element following AND or OR is invalid.
  • FMP-2278-00-E Quotes required in macro argument
    A non-null call argument was not delimited by quotes.
  • FMP-2280-00-E REPEAT value out of &ampPART RANGE
    A value in a % REPEAT or % R-V operation is too big for the numeric &PART.
  • FMP-2281-00-E REPEAT value out of range
    The expression evaluation caused the new repeat value to be out of range.
  • FMP-2282-00-E Result out of range
    An expression evaluation produced a number either less than -9999999 or greater than +9999999.
  • FMP-2288-00-E Right parenthesis expected after arguments
    A right parenthesis must end the argument list in a built-in function.
  • FMP-2290-00-E Right parenthesis expected after symbol name
    A right parenthesis must follow the variable argument in the built-in function.
  • FMP-2292-00-E Right parenthesis expected in INCLUDE
    A right parenthesis must follow the member name in INCLUDE.
  • FMP-2293-00-E Right parenthesis expected
    A right parenthesis is missing in an expression evaluation.
  • FMP-2296-00-E Source file not found
    The requested main input file was not found in the main input directory.
  • FMP-2297-00-E Symbol is predefined or part for inline $macro
    The AMB call variable (SYMBOL) for an inline call cannot be a predefined variable or &PART.
  • FMP-2298-00-E Symbol not assigned in inline $macro
    The AMB call variable (SYMBOL) for an inline call must be defined before invoking the inline call that uses it.
  • FMP-2299-00-E Text compared with numeric in LOOKUP
    A text variable was compared with a numeric variable in % LOOKUP processing.
  • FMP-2301-00-E THRU expression is 9999999
    The expression evaluation put the new THRU value out of range.
  • FMP-2302-00-E TO-THRU expression is text REPEAT VARYING
    A TO/THRU expression must resolve to a numeric value in a % R-V operation.
  • FMP-2303-00-E TO-THRU value does not fit &ampPART
    TO/THRU numeric value in % R-V was incremented and now will not fit in &PART.
  • FMP-2304-00-E Unrecognized text at end of INCLUDE
    Unrecognizable text trails the closing right parenthesis of a % INCLUDE.
  • FMP-2305-00-E Unrecognized text at end of line
    Unrecognizable text trails an otherwise syntactically correct line.
  • FMP-2315-00-E Unrecognized text follows DECLARE ITEM
    Unrecognizable text trails a % DECLARE ITEM.
  • FMP-2316-00-E Unterminated report or map mockup
    The designated 4 terminating characters are missing on the mock-up.
  • FMP-2317-00-E Macro name must start with $
    All call names must start with $.
  • FMP-3000-00-W Location set to Procedure Div for EPILOGUE
    During epilogue processing, the location for the output source was not set to Procedure Division.
  • FMP-3001-00-W Incompatible expression types
    Two expressions being compared using <, >, NOT < or NOT > are incompatible types (that is, a numeric variable being compared to a string).
  • FMP-3002-00-W AMB overflow truncated
    During code evaluation, the line was found to be almost entirely quotes.
  • FMP-3003-00-W Redefining part is longer group lengthened
    During DECLARE processing, a REDEFINES is longer than the element redefining it.
  • FMP-3004-00-W Redefined part is longer
    A redefined element is longer than the element being redefined.
  • FMP-3005-00-W Leading sign-digit(s) truncated
    During DECLARE processing, the leading character of a numeric was truncated.
  • FMP-3006-00-W Statement shifted to right
    A character was found in column 7 but the statement did not exceed column 72 so the line was shifted to the right. COBOL expects statements to start in column 8. Column 7 is for COBOL continuation and comment characters.
  • FMP-3007-00-W Changing built-in symbol
    An FMP reserved word was used as an FMP variable.
  • FMP-3008-00-W Macro already defined redefine ignored
    A AMB call defined in the compressed APSMAC library was redefined by the user. The compressed call is ignored.
  • FMP-3321-00-E Invalid character
    Garbage or control character on the line.
  • FMP-3322-00-W Non-numeric character in numeric &ampPART
    A text value was stored in a numeric part.
  • FMP-3323-00-F Text stack overflow
    Recursive expressions with an infinite nesting depth have caused text stack overflow.
  • FMP-3324-00-W Unknown TRACE operand
    An illegal trace operand was coded.
  • FMP-3325-00-W Changing BUILTIN symbol
    A predefined symbol is being changed in an assignment operation.
  • FMP-4000-00-I Fatal compile-time error processing ended
    Processing ended due to a previous fatal FMP error. An error code APS-XXX-9999-99-F was previously encountered.
  • FMP-9002-00-F Source stack overflow
    Number of source levels in stack exceeded maximum of 139. Too many nested sources (that is, invocations of calls or % INCLUDES). AMB internal error.
  • FMP-9003-00-F Source stack underflow
    Internal AMB error.
  • FMP-9004-00-F Indent stack full
    Number of indent statements in stack exceeded maximum of 50. AMB internal error.
  • FMP-9005-00-F Indent stack underflow
    Internal AMB error. Can be caused by a nonblank character incorrectly placed or generated when expanded into column 72. Another cause is a statement that should be continued is not continued. For example:
  • FMP-9006-00-F Internal fatal error
    Internal AMB error. During a call to the SSTTBL module for FMP table creation and LOOKUP routines, incorrect parameters were passed.
  • FMP-9007-00-E Storage exceeded
    Internal AMB error. During a call to the SSTTBL module for FMP table creation and LOOKUP routines, storage exceeded.
Parent topic: AppMaster Builder Error Messages


FMP-1000-00-F FMP-1000-40-F No more core

The amount of core given in the EXEC statement is exceeded, or no more core was available on the system when a GETMAIN was issued. Possibly, an FMP loop limit was previously raised and the loop is causing the program to use additional core.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify that there is not an unreasonable loop limit override (the default is 200); if not, increase the core on the EXEC step.

Parent topic: FMP- AMB Generator errors


FMP-1003-00-F Main source missing

Program specified on the DD statement as the source for a compile was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for misspelling.

Parent topic: FMP- AMB Generator errors


FMP-1004-00-F Too many active INCLUDEs

Maximum number of % INCLUDEs in one program (8) exceeded. Active % INCLUDEs refer to the number of ddnames.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Combine/decrease the number of INCLUDEs for program by concatenating INCLUDEs or combining defined libraries.

Parent topic: FMP- AMB Generator errors


FMP-1005-00-F Submember not found

On a % INCLUDE statement, the named submember was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for misspelled submember or incorrect sequence.

Parent topic: FMP- AMB Generator errors


FMP-1006-01-F Invalid EVAL-BRACKETS

Evaluation brackets are invalid or were not set properly. Evaluation brackets cannot be a numeric, alpha, quote, apostrophe, left or right parenthesis; we recommend using the less-than and greater-than characters <>.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check to see if % SET EVAL-BRACKETS statement is correct. Proper syntax is % SET EVAL-BRACKETS 'leftright' where the recommended value of leftright is the less-than and greater-than characters <>. Also, check to see if the evaluation-brackets flagged in the statement are the same as those specified by the SET statement.

Parent topic: FMP- AMB Generator errors


FMP-1006-02-F Invalid EVAL-BRACKETS-AUX

Auxiliary evaluation brackets are invalid or were not set properly. Evaluation brackets cannot be a numeric, alpha, quote, apostrophe, left or right parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check to see if % SET EVAL-BRACKETS-AUX statement is correct. Proper syntax is % SET EVAL-BRACKETS-AUX 'leftright' where leftright is the value of the auxiliary evaluation brackets. Also, check to see if the evaluation-brackets flagged in the statement are the same as those specified by the SET statement.

Note: % SET-EVAL-BRACKETS must also be defined.
Parent topic: FMP- AMB Generator errors


FMP-1007-00-F No in-line macros in FMP REPEAT loop test

During processing of an FMP REPEAT loop test, an in-line call was found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

In-line calls are invalid.

Parent topic: FMP- AMB Generator errors


FMP-1008-00-F No in-line macros in FMP ELSE-IF

During processing of an FMP ELSE-IF test, an in-line call was found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

In-line calls are invalid.

Parent topic: FMP- AMB Generator errors


FMP-1009-01-F SYM table full

During FMP processing the internal symbol table exceeded allocated size.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check all loops that define FMP symbols.

Parent topic: FMP- AMB Generator errors


FMP-1010-00-F No more line buffers

Line buffer for FMP was exceeded. FMP program requires more line buffers.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Increase region size on JOB and EXEC statements.

Parent topic: FMP- AMB Generator errors


FMP-1011-00-F Too many DECLARE &ampMSG-PART

The maximum number of DECLAREs allowed for one program (200) was exceeded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-1012-00-F Loop limit reached

The maximum number of FMP loops (initiated by % REPEAT, % UNTIL, % WHILE) performed during processing is equal to the setting of the loop limit counter % SET LOOP-LIMIT (default = 200) or &D2-TOKEN-MAX.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the loops and determine whether an error exists. To increase the loop limit, increase the value of % SET LOOP-LIMIT nnnn either in CNTL\APSDBDC or at the beginning of the program (which overrides the value in APSDBDC).

Parent topic: FMP- AMB Generator errors


FMP-1013-00-F Missing Data Division statement

Data Division header either not found, not in the correct place (columns 8-11), or misspelled.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-1014-00-F Missing Environment Division stmt

Environment Division header either not found, not in the correct place (columns 8-11), or misspelled.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-1015-00-F Missing ID Division statement

Identification Division header not found, in wrong place, or misspelled.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for correct spelling. Incorporate the Identification Division as the first line of the parent program that does not begin with % and correct its placement (columns 8-11).

Parent topic: FMP- AMB Generator errors


FMP-1016-00-F Missing Procedure Division statement

Procedure Division header not found, in wrong place, or misspelled.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for correct spelling and placement (columns 8-11). Certain errors in a report or map mock-up can cause the remainder of the program to be read as part of the mock-up; thus, the Procedure Division header may be correct but unrecognized.

Parent topic: FMP- AMB Generator errors


FMP-1017-00-F Submember must be in library file

The submember named in a % INCLUDE statement does not exist.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-1018-00-F Unprivileged FMP use

Program has attempted to enter the module for processing FMP.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Process program without call processor or obtain a new privilege card from Micro Focus SupportLine

Parent topic: FMP- AMB Generator errors


FMP-1019-00-F Unterminated report or map mock-up

Execution halts. Report or map mock-up opening delimiters were read, but no closing delimiters are found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Insert closing delimiters in program at appropriate place in report section or map section. If program has a split report mock-up, make sure each half is opened and closed with the delimiters. A split report mock-up requires opening and closing delimiters for each half (two pairs).

Parent topic: FMP- AMB Generator errors


FMP-1020-00-F Requested member not found

The member included by a % INCLUDE was not found. Member was not in specified PDS or member name was misspelled on FMP % INCLUDE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct program name or include source. If % INCLUDE DDISYMB <membername> was coded, ensure the DDI was built and the member name is spelled correctly. If % INCLUDE SCRSYMB was coded, verify that the screen is generated.

Parent topic: FMP- AMB Generator errors


FMP-1022-00-E Requested DDNAME not found

Data set name specified on the DD statement could not be located.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications, and verify that the referenced file members exist. Check DD statements for call libraries.

Parent topic: FMP- AMB Generator errors


FMP-1023-00-E No storage for buffer allocation

A GETMAIN was issued and storage could not be allocated. There is an inadequate region size for the program being compiled.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications, and verify that the referenced file members exist. Check DD statements for call libraries. Increase region size for this particular compile.

Parent topic: FMP- AMB Generator errors


FMP-1024-00-F I-O error in PDS directory

A fatal I/O error occurred when processing a LOOKUP routine for a PDS member.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications, and verify that the referenced file members exist. Check DD statements for call libraries. Check the PDS manually by browsing the member (ISPF=1) or the member list (ISPF=3.1). If PDS looks correct, try job again. If error persists, contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-1025-00-E Program error - contact your AMB rep

An internal error within the AMB compiler (portion that reads % INCLUDE files) occurred. During I/O processing an OPEN or READ call was issued for a channel that did not have a prior LOOKUP or CLOSE call. The channel number passed from SSTCTIM to SSTDDNA is less than 1 or greater than the maximum number of channels. An invalid call code was passed from SSTCTIM to SSTDDNA.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications, and verify that the referenced file members exist. Check DD statements for call libraries. Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-1026-00-F I-O error on CLOSE

CLOSE call was issued for an inactive channel. Probable internal logic error in AMB compiler.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-1027-00-E BLK not LRECL mult

When processing DCB information, the block size was not a multiple of the record length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check DD statements in call libraries for correct DCB, LRECL and BLKSIZE values. Possibly correct the block size in the DCB of the JCL.

Parent topic: FMP- AMB Generator errors


FMP-1028-00-F I-O error FMT1 DSCB

The error occurred executing an OPEN call instruction for a data set on a direct access device. An I/O error occurred reading the FORMAT1 DSCB. Or, the FORMAT1 DSCB for the data set could not be found either on the first volume specified by the DD statement, the volume indexed by the volume sequence number, or in the catalog.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications, and verify that the referenced file members exist. Also check DD statements for call libraries. If the FORMAT1 DSCB for the data set cannot be found, make sure that the DSNAME and volume parameters are correct.

Parent topic: FMP- AMB Generator errors


FMP-1029-00-E VOL mount prob rerun

No unit is available for mounting the specified volume. The volume already on the allocated unit is either permanently resident or reserved. It could not be unmounted in order to mount the required volume, or the volume cannot be unmounted because another DCB is open on that device.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications and verify that the referenced file members exist. Check DD statements for call libraries. Try rerunning the job. If the problem occurs again contact the operator to check if there is a problem with the mounted device.

Parent topic: FMP- AMB Generator errors


FMP-1030-00-E INVALID CONCATENATION

An open call instruction was issued for a partitioned data set concatenated with a data set that does not reside on a direct access storage device (DASD). Partitioned data sets can be concatenated only with data sets having like attributes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications, and verify that the referenced file members exist. Check DD statements of call libraries for DCB compatibility.

Parent topic: FMP- AMB Generator errors


FMP-1031-00-E Unknown - see SYSMSG

During I/O processing an error was detected but the I/O program that reads FMP % INCLUDE files could not analyze the error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Inspect all INCLUDE statements for correct syntax and file specifications, and verify that the referenced file members exist. C DD statements for call libraries. See IBM system messages and codes manual for information on the error and take appropriate action for system message.

Parent topic: FMP- AMB Generator errors


FMP-1201-00-F INCLUDE name illegal

The member name in an % INCLUDE statement is not a valid file name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure the file name is valid to the operating system. Check for misspelling.

Parent topic: FMP- AMB Generator errors


FMP-1202-00-F SET AUXILIARY-INPUT not implemented

Auxiliary input is not supported in this implementation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove % SET AUXILIARY-INPUT from the source.

Parent topic: FMP- AMB Generator errors


FMP-1203-00-E Cannot split line correctly

An attempt was made to expand an S-COBOL line that could not be continued correctly on a second line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Structure the original input line so that the line can be correctly split. See Coding Rules for S-COBOL.

Parent topic: FMP- AMB Generator errors


FMP-1204-00-W Line broken into two lines

A generated output line was continued on a second line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: FMP- AMB Generator errors


FMP-1206-00-W SPLITTING COBOL IDENTIFIER

A COBOL data name is continued on a second line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: FMP- AMB Generator errors


FMP-2000-00-E Not fix len string

A DECLARE part was given a picture and length but the symbol it represents is not a fixed length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Define the DECLARE part to correctly represent the symbol.

Parent topic: FMP- AMB Generator errors


FMP-2004-00-E Incompat DCLR stms

The DECLARE variable is incompatible with another DECLARE statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2005-00-E Invalid DCLR value

DECLARE variable was not numeric, a string, or another DECLARE variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2006-00-E DCLR part undef

During DECLARE USE, a DECLARE part was found with no defined value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2007-00-E Invalid DCLR sub

This message occurs when attempting to use a variable as a subscript which was already defined to FMP as a nonsubscript. Possibly a Declare part was used as a Declare subscript.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the DELCARE statement.

Parent topic: FMP- AMB Generator errors


FMP-2008-00-E Part not unique

All parts of DECLARE variables must have unique names.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2009-00-E Value not string

During DECLARE processing, a test was made for a string but the element was numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2010-00-E Compound built-in function

This is caused by using a built-in function as an argument within another built-in function. This is allowed only when:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • The nested function is enclosed by assigned-quotes (for example, &QT) within evaluation brackets
  • The left bracket is followed by a %.
Parent topic: FMP- AMB Generator errors


FMP-2011-00-E DCLR part required

% LOOKUP can only reference DECLARE parts.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2012-01-E Indentation error decreased

The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the block must then use the same indentation increment established by the first indented statement, until a new block begins. For further processing, the line indentation is decreased to the level of the current indentation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Align the indentation and recompile.

Parent topic: FMP- AMB Generator errors


FMP-2012-02-E Invalid indentation

The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the block must then use the same indentation increment established by the first indented statement, until a new block begins.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Align the indentation and recompile if necessary.

Parent topic: FMP- AMB Generator errors


FMP-2013-00-E Unallowed code at end of FMP line

The code following an ELSE statement is not allowed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct line so that IF follows ELSE on line, or ELSE stands alone on line.

Parent topic: FMP- AMB Generator errors


FMP-2014-00-E Operator expected in line

An arithmetic or logical operator was expected in the flagged line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2015-00-E Non-numeric destination in arith operation

When evaluating an arithmetic expression, an FMP variable was determined to be non-numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2016-00-E Division by 0 not allowed

When evaluating a division statement, an attempt to divide by zero was detected.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check division statement for divisor of zero, or check the data field, used as the divisor, for a zero value.

Parent topic: FMP- AMB Generator errors


FMP-2017-00-F Invalid indent in loop

The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the loop must use the same indentation increment established by the first indented statement, until the loop ends.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Align the indentation and recompile if necessary.

Parent topic: FMP- AMB Generator errors


FMP-2018-00-E REPEAT is an improper FMP loop termination

REPEAT was coded instead of a WHILE or UNTIL clause with a test in an FMP loop.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct loop termination by replacing REPEAT with WHILE or UNTIL and a test.

Parent topic: FMP- AMB Generator errors


FMP-2019-00-E Missing REPEAT VARYING variable

The FMP variable being varied in an FMP loop is missing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add the FMP variable to the coded loop or check to see if variable name is prefixed with an ampersand.

Parent topic: FMP- AMB Generator errors


FMP-2020-00-E Left parenthesis expected

A call name or a built-in function is followed by something other than a left parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2021-00-E Parameter list overflow for macro

Too many arguments (maximum is 40) were coded for a call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2022-00-E Too many invoking parameters

Too many arguments were coded when calling a call defined with nn number of arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify that the calling call does not use a number of arguments exceeding the amount defined for the call.

Parent topic: FMP- AMB Generator errors


FMP-2023-00-E Argument not FMP variable

The argument was not prefixed by an ampersand (&), or a string constant was not enclosed by quotes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Prefix the variable with an ampersand or delimit the string with quotes.

Parent topic: FMP- AMB Generator errors


FMP-2024-00-E Undefined ARG

Either a user call was coded with arguments, or a call was not defined with arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2025-00-E Argument not a string

Invalid arguments were coded on the invoking call statement. The call expects a string argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2026-00-E Not FMP string variable

An FMP string variable was not used in a built-in call that required one.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2027-00-E Right paren expected

An argument list was not followed by a right parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2030-00-E SET coded in improper location

A % SET WORKING STORAGE, FILE, FILE-CONTROL, LINKAGE, DATA, or SPECIAL-NAMES was encountered somewhere other than the Procedure Division or procedural code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2031-00-E SET END WORKING STORAGE in wrong location

The statement was found outside of the Working-Storage section.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2032-00-E Width must be at least &amp

Statement testing for the left and right margins either begins before column 7 or goes beyond column 72.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2033-00-E Improper coding of EPILOGUE macro

The epilogue call is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

% SET EPILOGUE must either be on a line by itself, removing the most current epilogue from the stack without being invoked. Or, follow % SET EPILOGUE with $MACRONAME on the same line, adding $MACRONAME to the stack of calls invoked at the end of FMP processing.

Parent topic: FMP- AMB Generator errors


FMP-2034-00-E Invalid SET statement

Invalid syntax or spelling error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2035-00-E Improper location

Possibly there is a % SET statement syntax error, invalid location, or indentation error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify syntax and use of the % SET PROCEDURE DIVISION. Check indentation.

Parent topic: FMP- AMB Generator errors


FMP-2036-00-E Linkage Section header not in proper order

Linkage Section header is coded after the Communication Section.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2037-00-E Macro name must start with $

A call name must be prefixed by a dollar sign $.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2038-00-E Variable must start with &amp

FMP variables must start with an ampersand (&).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2039-00-E DECLARE items invalid as formal arguments

A DECLARE item cannot be used as a formal (dummy) argument for an FMP call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2040-00-E Default value not number or string

Evaluation of a DEFINE statement detected use of something other than a number or string as a default call argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2041-00-E Invalid indent in def

The indentation increment for a given block of code is established by the number of indented spaces of the first line of indented code within the block. All indentation within the block must use the same indentation increment established by the first indented statement, until a new block begins.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Align the indentation and recompile if necessary.

Parent topic: FMP- AMB Generator errors


FMP-2042-00-E Unrecognized control cards parameter

% SET CONTROL-CARDS was not followed by LEADING, TRAILING, or END.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2043-00-E String expected

During internal processing of an FMP statement, a string was expected and not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the % SET EVAL-BRACKETS statement, or possibly the DECLARE statement.

Parent topic: FMP- AMB Generator errors


FMP-2044-00-E Cannot shift line

When processing a statement using eval-brackets, the statement expanded beyond column 72.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Move statement using the eval-brackets so expansion is not beyond column 72. If unable to shift statement, code a PERFORM and place the evaluation statement in the performed paragraph.

Parent topic: FMP- AMB Generator errors


FMP-2045-00-E FMP-2054-00-E Right evaluation bracket expected

A right evaluation bracket is expected and not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2050-00-E Compound logic illegal

Use of compound logic (AND and OR used together) in an FMP conditional or loop statement is illegal.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2052-00-E Non-numeric elem used in arith expression

When evaluating an arithmetic expression (statement containing a + - * /) a non-numeric field was found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2053-00-E Invalid element

Element, evaluated during a user call or in an FMP expression, was not a numeric, a string, or an ampersand.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct user call or FMP expression. Check all characters including any arguments, if used.

Parent topic: FMP- AMB Generator errors


FMP-2054-00-E FMP-2045-00-E Right evaluation bracket expected

A right evaluation bracket is expected and not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2055-00-E Unmatched right evaluation bracket

During evaluation scanning, a right evaluation bracket was paired with a left evaluation bracket.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code left evaluation bracket or remove extra right bracket.

Parent topic: FMP- AMB Generator errors


FMP-2056-00-E Infinite evaluation loop

When processing an evaluation statement, the internal counter exceeded 100.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2057-00-E Auxiliary input not active

This error occurs when the request is not available to the user, or when the parameters are not set properly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-2058-00-E Improper date argument

The date format passed to AMB was incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2059-00-E &ampAPS-HALF not defined

Variable &APS-HALF was not defined properly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax and correct. If the user is not overriding variable, contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-2060-00-E Non-numeric variable

When evaluating an internal date/time routine, something other than a numerically defined FMP variable was found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct data fields being passed. All FMP variables are preceded by an ampersand. Make them numeric values.

Parent topic: FMP- AMB Generator errors


FMP-2061-00-E Comma expected

When evaluating FMP statement, a comma was expected but not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2062-00-E &ampAPS-FULL not defined

Variable &APS-FULL was not defined properly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax and correct. If the user is not overriding variable, contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-2063-00-E Non-numeric arg

A non-numeric argument was supplied to a built-in function that requires a numeric argument.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2064-00-E Right paren or comma expected

Evaluation of a statement terminated incorrectly. Either a right parenthesis was omitted, or a comma was not used as a delimiter between fields.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct statement. Do not pass column 72.

Parent topic: FMP- AMB Generator errors


FMP-2065-00-E First argument not text string variable

The first argument of the PARSE built-in function is not an FMP string (text) variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2067-00-E DECLARE variable not parsable

The &PARSE function cannot be used on DECLARE parts.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2068-00-E Improper argument

An argument used with a built-in function is not a numeric, a string, or an ampersand.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2069-00-E Not macro or FMP variable name

When evaluating a statement starting with $ or &, the call or variable in question could not be found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Define call or variable.

Parent topic: FMP- AMB Generator errors


FMP-2070-00-E Not an FMP variable or number

When evaluating an element, the element was not defined as a variable or a numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2071-00-E Numeric expected When evaluating an element FMP expected a numeric

Correct element to be numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2072-00-E String too long truncated

Evaluation of a string in quotes is too long.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2073-00-E Non-numeric sequence number

Numbering of generated code can not be handled because a non-numeric is in columns 1 through 6.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the non-numeric from columns 1 - 6. Blanks are not allowed in columns 1 - 6.

Parent topic: FMP- AMB Generator errors


FMP-2074-00-E Non-numeric WYLBUR

Wylbur sequence numbering was requested via parameter and the numbering could not be done for the generated code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove non-numerics from columns 73 - 80.

Parent topic: FMP- AMB Generator errors


FMP-2075-01-E SEQUENCE NUMBER TOO LARGE

Sequence numbering exceeds limit for numbering. Limit is 999,999.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change sequence parameter to record or left justified style.

Parent topic: FMP- AMB Generator errors


FMP-2075-02-E NON-NUMERIC SEQUENCE NUMBER

Numbering of generated code can not be handled because a non-numeric is in columns 1 through 6.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove non-numeric characters from columns 1 - 6. Blanks are not allowed in columns 1 - 6.

Parent topic: FMP- AMB Generator errors


FMP-2076-00-E Non-numeric identifier in column 73-80

Non-numeric characters are found in columns 73-80.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove them.

Parent topic: FMP- AMB Generator errors


FMP-2077-00-E Statement not allowed in column 7

Only comment or continuation characters are allowed in column 7. A shift right was attempted but the statement went to column 72 and the shift could not be accomplished.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct statement to start in column 8. Continue statement, if necessary.

Parent topic: FMP- AMB Generator errors


FMP-2078-00-E DECLARE variable must start with &amp

When evaluating a DECLARE variable, the FMP special character for identifying variables (&) was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2079-00-E DECLARE subscript must start with &amp

When evaluating a DECLARE subscript, the FMP special character for identifying DECLARE subscripts (&) was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2080-00-E expected during DECLARE processing

You mistyped or left out % before DECLARE parts.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2081-00-E DECLARE part above not a group

A DECLARE part can reference several elementary level DECLARE parts. To do this, the group DECLARE part cannot have a picture and the subordinate DECLARE parts must be indented under the group level DECLARE part.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correctly define DECLARE parts if using as a group item, or correct indentation of elementary items.

Parent topic: FMP- AMB Generator errors


FMP-2083-00-E DECLARE part must start with &amp

When evaluating a DECLARE part variable, the FMP special character for identifying variables (&) was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2084-00-E Improper declare var type

A DECLARE part can be defined as numeric or string only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2085-00-E DECLARE string over 78 bytes

The value of a DECLARE part cannot exceed 78 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2086-00-E Part value not numeric

During DECLARE processing, a numeric variable was given a nonnumeric value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct value or define DECLARE part to be type X.

Parent topic: FMP- AMB Generator errors


FMP-2087-00-E LOOKUP requires variable

% LOOKUP must reference a defined DECLARE part variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2088-00-E Invalid LOOKUP relation

Relational operator in the % LOOKUP is incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Valid relational operators are =, NOT =, <=, <, >, >=, NOT < or NOT >.

Parent topic: FMP- AMB Generator errors


FMP-2089-00-E DECLARE part and value incompatible

In an arithmetic expression, a numeric DECLARE part was given a non-numeric value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2090-00-E THRU-TO value should be numeric

In a REPEAT VARYING loop, the THRU/TO values were not numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2091-00-E Starting value should be numeric

In a REPEAT VARYING loop, the FROM value was not numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2092-00-E No subscripts found

The field was defined as an OCCURS, but the subscript was omitted when the field was referenced in code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2093-00-E Only one subscript found

An element was defined in a two dimensional table. When the element was used, only one subscript applied.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2094-00-E Low-order subscript must be numeric

If the FROM clause in a LOOKUP is omitted, the low-order subscript must contain a numeric value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2095-00-E FMP cont ( ) expected but not found

The FMP call arguments begun on a previous line were not closed with a right parenthesis. Therefore, continuation of the arguments was expected on the next line, but the % ... expected to signal the continuation was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Either close parenthesis on user call line or signal continuation to a second line with a comma at the end of the call line and % ... at the beginning of the continuation line.

Parent topic: FMP- AMB Generator errors


FMP-2096-00-E The word DIVISION expected assumed

Division header does not show the word DIVISION. Processing resumes as if present.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Insert word DIVISION on indicated Division Header line.

Parent topic: FMP- AMB Generator errors


FMP-2097-00-E ELSE does not match IF

% ELSE was encountered at a level of indentation for which no % IF was previously encountered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Either the % IF or the % ELSE must be brought in line with the other. The two statements must begin in the same column.

Parent topic: FMP- AMB Generator errors


FMP-2098-00-E ELSE-IF does not match IF

% ELSE-IF was encountered at a level of indentation for which no % IF was previously encountered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Either the % IF or the % ELSE-IF must be brought in line with the other; the two statements must begin in the same column.

Parent topic: FMP- AMB Generator errors


FMP-2100-00-E Unallowed code follows REPEAT

% REPEAT is followed by something other than VARYING on the same line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the code so that % REPEAT stands alone on line, or is followed by VARYING.

Parent topic: FMP- AMB Generator errors


FMP-2101-00-E Invalid evaluation expression

Expression within evaluation brackets is not correct.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2102-00-E Invalid argument following macro call

Argument following FMP user call is not an FMP variable, a numeric literal, or an alphanumeric string (enclosed in quotes).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check code and correct call arguments.

Parent topic: FMP- AMB Generator errors


FMP-2103-00-E Left paren needed after DEFINE

A % DEFINE $DATANAME is followed by code not beginning with a left parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Determine whether arguments are intended to follow the % DEFINE, and if so, enclose them in parentheses. Note that no code other than arguments can be included on a % DEFINE $DATANAME line.

Parent topic: FMP- AMB Generator errors


FMP-2104-00-E Map section already seen

A second Map section header was encountered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use only one Map section header in your program.

Parent topic: FMP- AMB Generator errors


FMP-2105-00-E Missing PROGRAM-ID statement

Make sure the PROGRAM-ID statement follows the ID division header and begins in margin A (columns 8-11).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2106-00-E Modified line too wide

After resolution of evaluation brackets, the remaining line of COBOL extends past column 72.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Determine if the code can be placed on two lines. FMP lines cannot be continued.

Parent topic: FMP- AMB Generator errors


FMP-2107-00-E Relation condition not valid

The relation condition following an FMP conditional verb (% IF, % ELSE-IF, % WHILE, % UNTIL) is not valid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2108-00-E Report Section already seen

Use only one Report Section header, even if there are multiple reports in the program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2109-00-E The word SECTION not found or missing period

The word SECTION is missing from a Section Header line or period is missing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2110-00-E Too many digits in number

Integer to be processed by FMP exceeds 999,999.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2111-00-E Undefined DEF

Call is called that was not defined.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for input of call definition beginning at % DEFINE $MACRO-NAME. It may appear in a call library or in the program itself. Libraries must be designated as input to the program generator.

Parent topic: FMP- AMB Generator errors


FMP-2112-00-E Undefined symbol &amp

Symbolic variable was encountered for which no value is assigned. This variable can reside within a line of the source program, or as the value of another symbolic variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Assign a value to the designated variable or correct spelling of an already assigned symbolic variable.

Parent topic: FMP- AMB Generator errors


FMP-2113-00-E Undefined word after

Word encountered following a % is not an FMP keyword or a symbolic variable name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2114-00-E Unmatched quote

String was opened with a single or double and was not closed on the same line with the same delimiter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check code for presence of closing delimiter. Make sure it is same character as opening one.

Parent topic: FMP- AMB Generator errors


FMP-2115-00-E &amp followed by space improper FMP stm

An FMP statement begins with an ampersand (followed by a space) instead of a percent.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2205-00-E Macro definition not allowed

An unauthorized use of AMB Customizer was attempted.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB administrator.

Parent topic: FMP- AMB Generator errors


FMP-2207-00-E LOOKUP &ampFLDNAME is a part

The &FLDNAME in a LOOKUP operation has the same name as a &PART.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2208-00-E LOOKUP &ampFLDNAME is a predefined name

A &FLDNAME in a LOOKUP operation has cannot have the same name as a predefined name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2209-00-E UNTIL expected in loop repetition

EVAL BRACKET reevaluation action failed to generate the expect % UNTIL or % WHILE for % REPEAT or % R-V processing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2210-00-E WHILE expected in loop repetition

EVAL BRACKET reevaluation action failed to generate the expect % UNTIL or % WHILE for % REPEAT or % R-V processing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2219-00-E &ampDEFVAL value undefined

&DEFVAL is undefined because a &DEFINED test has either not yet occurred or has tested false.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Recode logic so that &DEFVAL is only referenced when at least one &DEFINED test is known to have tested true.

Parent topic: FMP- AMB Generator errors


FMP-2220-00-E &ampFLDNAME for &ampPART has no &ampSUBs in LOOKUP

Attempted a LOOKUP against a &PART belonging to a &FLDNAME that has no &SUBs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the DECLARE &FLDNAME definition to include at least one &SUB.

Parent topic: FMP- AMB Generator errors


FMP-2221-00-E &ampFLDNAME is &ampPART

&FLDNAME cannot have the same name as a &PART.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2222-00-E &ampFLDNAME text is not valid

A &FLDNAME name is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2223-00-E &ampFLDNAME value illegal

The content of a % DECLARE subscript resolved &FLDNAME to the name of an already defined &FLDNAME, call name, or FDEFINE name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the statement or process that populates the subscripts (SUBs) of the &FLDNAME.

Parent topic: FMP- AMB Generator errors


FMP-2224-00-E &ampFLDNAME value is numeric

An attempt was made to reference an &PART defined under an &FLDNAME that was set to numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Set &FLDNAME to an appropriate text value.

Parent topic: FMP- AMB Generator errors


FMP-2225-00-E &ampFLDNAME value is predefined name

An &FLDNAME was resolved to a predefined name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the statement or process that populates the subscripts (SUBs) of the &FLDNAME.

Parent topic: FMP- AMB Generator errors


FMP-2226-00-E &ampINDEX requires two arguments

The two required arguments for &INDEX were not coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2227-00-E &ampLENGTH requires one argument

The required argument for &LENGTH was not coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2228-00-E &ampNUMERIC requires one argument

The required argument for &NUMERIC was not coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2229-00-E &ampPARSE argument is predefined &ampVARIABLE

An argument to the &PARSE predefined function cannot be a predefined function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2233-00-E &ampSUB is predefined function

An &SUB cannot have the same name as a predefined function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2234-00-E &ampSUB undefined

A reference was made to an undefined &SUB for a % DECLARE
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Define the &SUB for the DECLARE

Parent topic: FMP- AMB Generator errors


FMP-2235-00-E &ampSUBSTR position parameter is not 0

The value for the position parameter in a &SUBSTR operation was either coded as 0, or evaluated to 0.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Make the position parameter a positive number.

Parent topic: FMP- AMB Generator errors


FMP-2236-00-E &ampSUBSTR requires either 2 or 3 arguments

An &SUBSTR operation is missing the minimum number of arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2237-00-E &amp is a predefined name in R-V

A predefined variable name was used in a % R-V operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2238-00-E &ampVARIABLE is a text &ampPART in R-V

An attempt was made to use a text part in a numeric % R-V operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the &PART to numeric.

Parent topic: FMP- AMB Generator errors


FMP-2239-00-E &ampVARIABLE value is text in REPEAT VARYING

A text variable was used in a % R-V operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the offending variable to numeric.

Parent topic: FMP- AMB Generator errors


FMP-2240-00-E Argument required for &ampDEFINED

A variable name was not specified in an &DEFINED test.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2241-00-E Arguments required for &ampPARSE

No arguments were specified in an &PARSE operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2242-00-E Arguments required for built-in function

Built-in function requires argument(s).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2243-00-E BY expression is text in REPEAT VARYING

The BY increment variable is a text variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change it to numeric.

Parent topic: FMP- AMB Generator errors


FMP-2244-00-E Cant store &ampPART in numeric &ampFLDNAME

A value was assigned to an &PART belonging to an &FLDNAME set to a numeric value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Assign the &FLDNAME a text value.

Parent topic: FMP- AMB Generator errors


FMP-2245-00-E Cannot break line correctly

Cannot continue an S-COBOL data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Break the input line into two smaller lines.

Parent topic: FMP- AMB Generator errors


FMP-2247-00-E DECLARE part must start with &amp

DECLARE PART name does not have a leading &.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Prefix PART name with leading &.

Parent topic: FMP- AMB Generator errors


FMP-2248-00-E Expression expected at end of line

The call processor syntax expects an expression at the end of the line, probably following an OR operator.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure the expression is present on the line and legally coded.

Parent topic: FMP- AMB Generator errors


FMP-2249-00-E Expression expected

The call processor syntax expects an expression somewhere in the line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the line for the missing expression.

Parent topic: FMP- AMB Generator errors


FMP-2250-00-E FLDNAME is PART or SUB

A FLDNAME was defined with the same name as a previously defined &PART or &SUB
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2251-00-E FROM expression is TEXT REPEAT VARYING

A FROM expression evaluated to TEXT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the variable or expression to a numeric value.

Parent topic: FMP- AMB Generator errors


FMP-2252-00-E FROM value does not fit &ampPART

FROM numeric value in % R-V does not fit in &PART.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Increase the size of the &PART.

Parent topic: FMP- AMB Generator errors


FMP-2253-00-E Illegal REDEFINES in &ampPART

A DECLARE item was not redefined at the same level of indentation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2254-00-E Indent of changed by EVAL BRKTS

An EVAL BRACKET action inserted a space in the beginning of the line, causing an indentation error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2255-00-E Invalid &ampFLDNAME in DECLARE

&FLDNAME is coded with illegal syntax.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2256-00-E Invalid loop limit

LOOP LIMIT cannot be greater than 32,767.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2257-00-E Invalid PICTURE

DECLARE PART picture is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change PART picture to Xn or Nn format.

Parent topic: FMP- AMB Generator errors


FMP-2259-00-W Invalid text after macro call

Unrecognizable text trails the closing right parenthesis of a call invocation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the line and delete the trailing garbage.

Parent topic: FMP- AMB Generator errors


FMP-2260-00-E Invalid WRITE-CONTROL limit

WRITE-CONTROL LIMIT cannot be greater than 32,767.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2261-00-E Left operand must be numeric

In an arithmetic assignment, the left operand is not numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2262-00-E Macro name may not be $ alone

A call name was not prefixed with a $.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2263-00-E Member not found

The requested member in an INCLUDE was not found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Place the missing member in the appropriate directory.

Parent topic: FMP- AMB Generator errors


FMP-2264-00-E Missing member name in INCLUDE

The member name was omitted in a % INCLUDE statement
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2265-00-E Mockup line truncated

A mockup line expansion caused truncation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Redesign the report mockup line so that it can handle the maximum length of any expanded AMB call processor action on that line.

Parent topic: FMP- AMB Generator errors


FMP-2266-00-E More than one BY clause in R-V

More than one BY clause was coded in a % R-V operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2267-00-E More than one FROM clause in R-V

More than one FROM clause was coded in a % R-V operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2268-00-E More than one TO-THRU clause in R-V

More than one TO/THRU clause was coded in a % R-V operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2269-00-E NEXT-TO-LAST &ampSUB not defined

Two low order subs were specified in a % LOOKUP call and only one low order sub was coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add an extra low order SUB to &FLDNAME, or remove one from the LOOKUP call.

Parent topic: FMP- AMB Generator errors


FMP-2270-00-E No DDNAME in INCLUDE

DDNAME missing from % INCLUDE statement
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Recode the statement as % INCLUDE DDNAME(member)

Parent topic: FMP- AMB Generator errors


FMP-2271-00-E Non-numeric source in arith operation

Right-side variable in an operator assignment is text, instead of numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2272-00-E Numeric compared with text in LOOKUP

A numeric variable was compared with a text variable in % LOOKUP processing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change one of the variables to text or numeric.

Parent topic: FMP- AMB Generator errors


FMP-2275-00-E Positive integer expected

A % SET statement requires a positive integer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the integer value to positive.

Parent topic: FMP- AMB Generator errors


FMP-2277-00-E Quotes or &amp required on identifier

Element following AND or OR is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2278-00-E Quotes required in macro argument

A non-null call argument was not delimited by quotes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2280-00-E REPEAT value out of &ampPART RANGE

A value in a % REPEAT or % R-V operation is too big for the numeric &PART.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Increase the size of the numeric &PART.

Parent topic: FMP- AMB Generator errors


FMP-2281-00-E REPEAT value out of range

The expression evaluation caused the new repeat value to be out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the expression so that the range value is not less than -9999999 and not greater than +9999999.

Parent topic: FMP- AMB Generator errors


FMP-2282-00-E Result out of range

An expression evaluation produced a number either less than -9999999 or greater than +9999999.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the expression so that the range value is not less than -9999999 and not greater than +9999999.

Parent topic: FMP- AMB Generator errors


FMP-2288-00-E Right parenthesis expected after arguments

A right parenthesis must end the argument list in a built-in function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2290-00-E Right parenthesis expected after symbol name

A right parenthesis must follow the variable argument in the built-in function.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2292-00-E Right parenthesis expected in INCLUDE

A right parenthesis must follow the member name in INCLUDE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2293-00-E Right parenthesis expected

A right parenthesis is missing in an expression evaluation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2296-00-E Source file not found

The requested main input file was not found in the main input directory.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2297-00-E Symbol is predefined or part for inline $macro

The AMB call variable (SYMBOL) for an inline call cannot be a predefined variable or &PART.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the call variable to a regular AMB call variable.

Parent topic: FMP- AMB Generator errors


FMP-2298-00-E Symbol not assigned in inline $macro

The AMB call variable (SYMBOL) for an inline call must be defined before invoking the inline call that uses it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2299-00-E Text compared with numeric in LOOKUP

A text variable was compared with a numeric variable in % LOOKUP processing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change one of the variables being compared to a text or numeric.

Parent topic: FMP- AMB Generator errors


FMP-2301-00-E THRU expression is 9999999

The expression evaluation put the new THRU value out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the expression so that the THRU will not resolve to greater than 9,999,999.

Parent topic: FMP- AMB Generator errors


FMP-2302-00-E TO-THRU expression is text REPEAT VARYING

A TO/THRU expression must resolve to a numeric value in a % R-V operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2303-00-E TO-THRU value does not fit &ampPART

TO/THRU numeric value in % R-V was incremented and now will not fit in &PART.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Increase the size of the &PART.

Parent topic: FMP- AMB Generator errors


FMP-2304-00-E Unrecognized text at end of INCLUDE

Unrecognizable text trails the closing right parenthesis of a % INCLUDE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the line and delete the trailing garbage.

Parent topic: FMP- AMB Generator errors


FMP-2305-00-E Unrecognized text at end of line

Unrecognizable text trails an otherwise syntactically correct line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the line and delete the trailing garbage.

Parent topic: FMP- AMB Generator errors


FMP-2315-00-E Unrecognized text follows DECLARE ITEM

Unrecognizable text trails a % DECLARE ITEM.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the line and delete the trailing garbage.

Parent topic: FMP- AMB Generator errors


FMP-2316-00-E Unterminated report or map mockup

The designated 4 terminating characters are missing on the mock-up.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-2317-00-E Macro name must start with $

All call names must start with $.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-3000-00-W Location set to Procedure Div for EPILOGUE

During epilogue processing, the location for the output source was not set to Procedure Division.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary. AMB sets location to Procedure Division automatically.

Parent topic: FMP- AMB Generator errors


FMP-3001-00-W Incompatible expression types

Two expressions being compared using <, >, NOT < or NOT > are incompatible types (that is, a numeric variable being compared to a string).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify code to prevent unexpected results.

Parent topic: FMP- AMB Generator errors


FMP-3002-00-W AMB overflow truncated

During code evaluation, the line was found to be almost entirely quotes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify code to prevent unexpected results.

Parent topic: FMP- AMB Generator errors


FMP-3003-00-W Redefining part is longer group lengthened

During DECLARE processing, a REDEFINES is longer than the element redefining it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: FMP- AMB Generator errors


FMP-3004-00-W Redefined part is longer

A redefined element is longer than the element being redefined.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: FMP- AMB Generator errors


FMP-3005-00-W Leading sign-digit(s) truncated

During DECLARE processing, the leading character of a numeric was truncated.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: FMP- AMB Generator errors


FMP-3006-00-W Statement shifted to right

A character was found in column 7 but the statement did not exceed column 72 so the line was shifted to the right. COBOL expects statements to start in column 8. Column 7 is for COBOL continuation and comment characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: FMP- AMB Generator errors


FMP-3007-00-W Changing built-in symbol

An FMP reserved word was used as an FMP variable.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use a different name. AMB libraries use the built-in functions and will not compile if any function name is assigned as a variable.

Parent topic: FMP- AMB Generator errors


FMP-3008-00-W Macro already defined redefine ignored

A AMB call defined in the compressed APSMAC library was redefined by the user. The compressed call is ignored.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure you have not included APSMAC in your program twice. If you have redefined an individual AMB call, you may want to copy the entire call member to a separate file and include this file in your ISPF.INI ahead of the compressed APSMLBR library in the DDLBR(APSMACS) concatenation to suppress the warning message.

Parent topic: FMP- AMB Generator errors


FMP-3321-00-E Invalid character

Garbage or control character on the line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the line, in hex mode if necessary, for the offending character.

Parent topic: FMP- AMB Generator errors


FMP-3322-00-W Non-numeric character in numeric &ampPART

A text value was stored in a numeric part.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the value to make certain this is the desired result.

Parent topic: FMP- AMB Generator errors


FMP-3323-00-F Text stack overflow

Recursive expressions with an infinite nesting depth have caused text stack overflow.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the nesting depth of the recursive expression.

Parent topic: FMP- AMB Generator errors


FMP-3324-00-W Unknown TRACE operand

An illegal trace operand was coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the trace operand to INFO or NOINFO.

Parent topic: FMP- AMB Generator errors


FMP-3325-00-W Changing BUILTIN symbol

A predefined symbol is being changed in an assignment operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check to make sure that this is the desired result.

Parent topic: FMP- AMB Generator errors


FMP-4000-00-I Fatal compile-time error processing ended

Processing ended due to a previous fatal FMP error. An error code APS-XXX-9999-99-F was previously encountered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: FMP- AMB Generator errors


FMP-9002-00-F Source stack overflow

Number of source levels in stack exceeded maximum of 139. Too many nested sources (that is, invocations of calls or % INCLUDES). AMB internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check for possibility of recursive call invocation (invoking a call from within itself, however many levels deep). Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-9003-00-F Source stack underflow

Internal AMB error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-9004-00-F Indent stack full

Number of indent statements in stack exceeded maximum of 50. AMB internal error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Break code up into performed paragraphs. If problem is not resolved, contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-9005-00-F Indent stack underflow

Internal AMB error. Can be caused by a nonblank character incorrectly placed or generated when expanded into column 72. Another cause is a statement that should be continued is not continued. For example:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • % &A1 = 'A.......AAA- <The '-' is in column 72
  • % &B1 = 'B.......BBB'

Resolution:

Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-9006-00-F Internal fatal error

Internal AMB error. During a call to the SSTTBL module for FMP table creation and LOOKUP routines, incorrect parameters were passed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


FMP-9007-00-E Storage exceeded

Internal AMB error. During a call to the SSTTBL module for FMP table creation and LOOKUP routines, storage exceeded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: FMP- AMB Generator errors


IMS- IMS messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • IMS-1020-00-E (TP) Subscript missing for SCR FLD
    An attributed field within a repeated block is missing the subscript for that field.
  • IMS-1030-00-E (TP) SCR FLD is not a repeated field
    You coded a subscript with an attributed field that is not part of a repeated block. Remove the subscript.
  • IMS-1040-00-E (TP) FLD is not a valid field for SCR
    The coded field name is invalid for the named screen.
  • IMS-1050-00-E (TP) Required screen name not supplied
    You did not supply the screen name when:
  • IMS-1060-00-E (TP) Required attribute not supplied
    When setting attributes (ATTR), you did not supply the attribute.
  • IMS-1070-00-E (TP) Required field name not supplied
    When setting attributes (ATTR), you did not supply any field name(s).
  • IMS-2010-00-E (TP) Combination of attributes not recognized in attribute table
    The attribute table in APIMSTP does not contain the combination of the values given.
  • IMS-2011-00-E PREV invalid for IMS
    The keyword PREV or PREVIOUS is invalid when accessing an IMS database.
  • IMS-2030-00-W (TP) Attributes not valid
  • IMS-2031-00-E Invalid command for GSAM
    AMB does not allow this call for GSAM records.
  • IMS-2040-00-E Multi level call invalid for GSAM
    You can specify a single record only when accessing a GSAM database.
  • IMS-2041-00-W Extended attribute has no effect on screen in PCIMS
    The extend attribute xxxxxxxx is color, blink, reverse video, or underscore, depending on what you coded in the ATTR call.
  • IMS-2043-00-W Fields defined
    More than 400 fields in one screen not supported in PCIMS. You coded more than 400 fields for one screen, exceeding the limit for PCIMS.
  • IMS-2050-00-E GSAM record can be qualified only on one field
    You can qualify the record on one key only when accessing a GSAM database.
  • IMS-2060-00-E GSAM record must be qualified on GSAM-KEY
    You must use the field GSAM-KEY when qualifying on a GSAM record .
  • IMS-2070-00-E For record no PCB with procopt G or I
    To retrieve a GSAM record, the PCB needs a procopt of G; to insert a GSAM record, the PCB needs a procopt of I.
  • IMS-2080-00-I View has defaulted to
    You did not specify a view name in the call, so the View has defaulted.
  • IMS-2090-00-E Procopt violation get required for record
    You coded a DB-OBTAIN for a record and the PCB does not allow retrievals.
  • IMS-2100-00-E Procopt violation insert required for record
    You coded a DB-STORE for a record and the PCB does not allow inserts.
  • IMS-2110-00-E Procopt violation replace required for record
    You coded a DB-MODIFY for a record and the PCB does not allow updates.
  • IMS-2120-00-E Procopt violation delete required for record
    You coded a DB-ERASE for a record and the PCB does not allow deletes.
  • IMS-2130-00-E Procopt violation path required for record
    You requested a record in a path call, and the procopt does not allow path calls.
  • IMS-2140-00-W For record record is key sensitive no data retrieved
    For a DB-OBTAIN, AMB referenced the lowest level record; data was not retrieved.
  • IMS-2150-00-E For record lowest level record may not be referenced unless key sensitive
    For a DB-OBTAIN, AMB may not reference the lowest level record unless it is key sensitive.
  • IMS-2160-00-W For key qualifications specified do not match actual number of parts comprising key
    The key contains more than one field, but the number of qualifications specified in the call for this key is less than the actual number of parts.
  • IMS-2170-00-E For key too many qualifications specified for key
    The key contains more than one field, and the number of qualifications specified in the call for this key exceeds the actual number of parts.
  • IMS-2180-00-E For record more than five command codes generated
    The number of call codes generated exceeds the limit of five.
  • IMS-2190-00-E Assembler blocking routine must be used when not using default IO area
    You must use the assembler blocking and unblocking routine when acting on more than one record in a call and specifying an IO area different from the default.
  • IMS-2200-00-E For record logical concatenated record invalid in path call when logical child is variable length
    You cannot specify the record in a path call because the logical child portion is a variable length.
  • IMS-2210-00-W Data base call not generated Flag set to suppress data base call
    The FMP flag, &IM-SUPPRESS-DB-CALL, is set to suppress the database call. No response is necessary.
  • IMS-3010-00-E For record for key key invalid for record
    The key specified in the call is invalid for the record.
  • IMS-3020-00-E For record invalid record name
    AMB does not recognize the specified record name as a valid COBOL record name.
  • IMS-3030-00-E For record PCB not found Invalid record name use COBOL record name
    You did not give a PCB name the call, and AMB cannot use the default because the record name is incorrect.
  • IMS-3040-00-E For view invalid view name
    The PCB name specified in the call is incorrect. Check the spelling of the named View (PCB).
  • IMS-3050-00-E For view for record invalid record name
    Use COBOL record name. The record name specified in the call is incorrect.
  • IMS-3060-00-E For record for parent parent invalid for this record
    The records specified in the call are not in the proper hierarchical order.
  • IMS-4010-00-E Function not now supported by PCIMS
    Do not code the system service calls IM-STAT, IM-ROLL, IM-ROLB, and IM-LOG, if the target is PCIMS.
  • IMS-4020-00-W GSAM call generated without RSA PCIMS does not support RSA
    Do not code a record search argument on the GSAM calls IM-GU, IM-GN, or IM-ISRT, if the target is PCIMS.
  • IMS-5010-00-E (TP) Program argument required
    AMB invoked the MSG-SW call and detected that the first parameter is missing or contains nulls.
  • IMS-5020-00-E (TP) No alt PCB for
    AMB invoked $TP-CHNG-TO-DEST and found no alternate PCB was defined.
  • IMS-5030-00-E (TP) No appropriate IO-PCB
    A SEND or MSG-SW call required an alternate IO PCB with specific characteristics and the present program PSB cannot provide the appropriate PCB.
  • IMS-5040-00-F (TP) SUBSCHEMA or PSB macro not invoked
    You did not invoke IM-PSB or DB-SUBSCHEMA.
  • IMS-5800-00-F (TP) DB2 is not a valid DB target for Micro Focus IMSVS86
    The Data Definition symbols contain DB2 references.
  • IMS-6020-00-W (TP) Use TP-SEND with ENDCONV
    You invoked a $TP-SEND-LAST call. AMB replaced this call with SEND.
  • IMS-6030-00-W (TP) Use $TP-SEND
    You invoked a $TP-SEND-LAST call. AMB replaced this call with SEND.
  • IMS-6040-00-E (TP) Unknown keyword
    The named keyword is invalid.
  • IMS-7010-00-E (TP) Screen must have value not null or spaces
    AMB invoked SEND and the first parameter is missing or contains nulls.
  • IMS-7020-00-W (TP) Use $TP-MSG-SW instead of $TP-XCTL
    You invoked XCTL. AMB replaced this call with MSG-SW.
  • IMS-7030-00-E (TP) First parm to TP-SCRNLIST must name a screen
    The SCRNLIST call found a keyword as the first parameter. Keyword parameters must follow one or more screen names.
  • IMS-7040-00-E (TP) Screen must be labeled
    SCRNLIST supplied the name of a screen without the LABELED option, where the input message contains the screen name as the final 8 bytes. AMB requires this so that logic generated by SCRNLIST can determine which screen it received at run time.
  • IMS-7050-00-E (TP) RECORD keyword invalid when using TP-SCRNLIST
    The SCRNLIST call detected the RECORD keyword. RECORD is not a valid parameter for SCRNLIST.
  • IMS-7060-00-E ALT LTERM required for destination-printer
    When using SEND and you defined the output device in the Screen Painter to a printer, ensure that you include an alternate PCB TYPE=TP definition in the PSB source.
  • IMS-8010-00-F (TP) Include APMDCSC before APIMSTP
    You included the call library member APIMSTP before the member APMDCSC.
  • IMS-8020-00-F APIMSTP included twice - remove extra INCLUDE
    You included the call library member, APIMSTP, twice.
  • IMS-8030-00-E $TP-LINKAGE invoked twice - remove extra INCLUDE
    AMB invoked the call TP-LINKAGE more than once.
  • IMS-8040-00-E (TP) $TP-LINKAGE must be invoked before $TP-ENTRY
    AMB invoked the call TP-LINKAGE after $TP-ENTRY.
  • IMS-8050-00-F $TP-ENTRY must be invoked for IMS program
    You compiled a program with the MDC set to IMS/DC but AMB did not encounter TP-ENTRY.
  • IMS-8060-00-F $TP-SCRNLIST must be invoked before TP-ENTRY
    AMB encountered $TP-ENTRY, followed by SCRNLIST.
  • IMS-8070-00-F TP-SCRNLIST invoked more than once
    Only one invocation of SCRNLIST is valid.
  • IMS-8080-00-E xmlNOSPA keyword used twice
    Only one SPA keyword allowed per SCRNLIST call.
  • IMS-9010-00-F Missing include SCRSYMB for SCR
    The screen symbols for the named screen are missing.
  • IMS-9020-01-F IMS-9020-02-F PROGRAM-INVOKED para for non-conversational IMS program
    A nonconversational IMS/DC program contains the paragraph APS-PROGRAM-INV-PARA. In a program using design mode, AMB performs this paragraph when the program is TP-PROGRAM-INVOKED. Usually, you set TP-PROGRAM-INVOKED to TRUE for a conversational program only. The presence of APS-PROGRAM-INV-PARA in a nonconversational program is a conflict, and may not function as intended.
Parent topic: AppMaster Builder Error Messages


IMS-1020-00-E (TP) Subscript missing for SCR FLD

An attributed field within a repeated block is missing the subscript for that field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-1030-00-E (TP) SCR FLD is not a repeated field

You coded a subscript with an attributed field that is not part of a repeated block. Remove the subscript.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-1040-00-E (TP) FLD is not a valid field for SCR

The coded field name is invalid for the named screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-1050-00-E (TP) Required screen name not supplied

You did not supply the screen name when:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Setting attributes (ATTR)
  • Clearing attributes (CLEAR-ATTRS)
  • Clearing the screen with either spaces (CLEAR) or null values (TP-NULL)
Parent topic: IMS- IMS messages


IMS-1060-00-E (TP) Required attribute not supplied

When setting attributes (ATTR), you did not supply the attribute.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Supply theattributes you want to set.

Parent topic: IMS- IMS messages


IMS-1070-00-E (TP) Required field name not supplied

When setting attributes (ATTR), you did not supply any field name(s).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-2010-00-E (TP) Combination of attributes not recognized in attribute table

The attribute table in APIMSTP does not contain the combination of the values given.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator. Attribute table needs updating.

Parent topic: IMS- IMS messages


IMS-2011-00-E PREV invalid for IMS

The keyword PREV or PREVIOUS is invalid when accessing an IMS database.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: IMS- IMS messages


IMS-2030-00-W (TP) Attributes not valid

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling of the attribute. Check syntax.

Parent topic: IMS- IMS messages


IMS-2031-00-E Invalid command for GSAM

AMB does not allow this call for GSAM records.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The call is either a DB-MODIFY or DB-ERASE, both of which are invalid for GSAM. Remove the call.

Parent topic: IMS- IMS messages


IMS-2040-00-E Multi level call invalid for GSAM

You can specify a single record only when accessing a GSAM database.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by specifying only one record for processing.

Parent topic: IMS- IMS messages


IMS-2041-00-W Extended attribute has no effect on screen in PCIMS

The extend attribute xxxxxxxx is color, blink, reverse video, or underscore, depending on what you coded in the ATTR call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If you use extended attributes, be aware that they have no effect in PCIMS.

Parent topic: IMS- IMS messages


IMS-2043-00-W Fields defined

More than 400 fields in one screen not supported in PCIMS. You coded more than 400 fields for one screen, exceeding the limit for PCIMS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-2050-00-E GSAM record can be qualified only on one field

You can qualify the record on one key only when accessing a GSAM database.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Specify only one field qualification.

Parent topic: IMS- IMS messages


IMS-2060-00-E GSAM record must be qualified on GSAM-KEY

You must use the field GSAM-KEY when qualifying on a GSAM record .
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Specify GSAM-KEY as the key.

Parent topic: IMS- IMS messages


IMS-2070-00-E For record no PCB with procopt G or I

To retrieve a GSAM record, the PCB needs a procopt of G; to insert a GSAM record, the PCB needs a procopt of I.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consult with the Database Administrator to determine appropriate processing options for the record in question.

Parent topic: IMS- IMS messages


IMS-2080-00-I View has defaulted to

You did not specify a view name in the call, so the View has defaulted.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If you do not explicitly specify PCB (or VIEW) in the call, then the default PCB is the first one in the PSB that permits access to the first record named in the call. No response is necessary. See also Coding IMS DDI Statements.

Parent topic: IMS- IMS messages


IMS-2090-00-E Procopt violation get required for record

You coded a DB-OBTAIN for a record and the PCB does not allow retrievals.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consult with your Database Administrator to determine appropriate processing options for the record in question.

Parent topic: IMS- IMS messages


IMS-2100-00-E Procopt violation insert required for record

You coded a DB-STORE for a record and the PCB does not allow inserts.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consult with your Database Administrator to determine appropriate processing options for the record in question.

Parent topic: IMS- IMS messages


IMS-2110-00-E Procopt violation replace required for record

You coded a DB-MODIFY for a record and the PCB does not allow updates.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consult with your Database Administrator to determine appropriate processing options for the record in question.

Parent topic: IMS- IMS messages


IMS-2120-00-E Procopt violation delete required for record

You coded a DB-ERASE for a record and the PCB does not allow deletes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consult with your Database Administrator to determine appropriate processing options for the record in question.

Parent topic: IMS- IMS messages


IMS-2130-00-E Procopt violation path required for record

You requested a record in a path call, and the procopt does not allow path calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consult with your Database Administrator to determine appropriate processing options for the record in question.

Parent topic: IMS- IMS messages


IMS-2140-00-W For record record is key sensitive no data retrieved

For a DB-OBTAIN, AMB referenced the lowest level record; data was not retrieved.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The record named is key sensitive so AMB does not retrieve data in the IO area; however, you can determine whether or not the record exists in the database by checking the status flags, as done normally.

No response is necessary.

Parent topic: IMS- IMS messages


IMS-2150-00-E For record lowest level record may not be referenced unless key sensitive

For a DB-OBTAIN, AMB may not reference the lowest level record unless it is key sensitive.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the call by preceding the lowest level record specified in the call by the keyword, REC.

Parent topic: IMS- IMS messages


IMS-2160-00-W For key qualifications specified do not match actual number of parts comprising key

The key contains more than one field, but the number of qualifications specified in the call for this key is less than the actual number of parts.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The key is a secondary index comprised of more than one field. You specified a number of fields to move to the SSA that is less than the actual number of fields comprising the key. No response is necessary.

Parent topic: IMS- IMS messages


IMS-2170-00-E For key too many qualifications specified for key

The key contains more than one field, and the number of qualifications specified in the call for this key exceeds the actual number of parts.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The key is a secondary index comprised of more than one field. You specified a number of fields to move to the SSA that is more than the actual number of fields comprising the key. Specify the correct number of fields to be moved to the SSA.

Parent topic: IMS- IMS messages


IMS-2180-00-E For record more than five command codes generated

The number of call codes generated exceeds the limit of five.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

You probably caused more than five call codes to generate by coding the keyword CCODE followed by a list of call codes. If you need more than five call codes, call the AMB Administrator; otherwise, remove unnecessary call codes.

Parent topic: IMS- IMS messages


IMS-2190-00-E Assembler blocking routine must be used when not using default IO area

You must use the assembler blocking and unblocking routine when acting on more than one record in a call and specifying an IO area different from the default.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Set an FMP symbol to specify that you are using the assembly. Consult the AMB Administrator for the proper way to do this.

Parent topic: IMS- IMS messages


IMS-2200-00-E For record logical concatenated record invalid in path call when logical child is variable length

You cannot specify the record in a path call because the logical child portion is a variable length.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the named record from the path call.

Parent topic: IMS- IMS messages


IMS-2210-00-W Data base call not generated Flag set to suppress data base call

The FMP flag, &IM-SUPPRESS-DB-CALL, is set to suppress the database call. No response is necessary.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-3010-00-E For record for key key invalid for record

The key specified in the call is invalid for the record.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: IMS- IMS messages


IMS-3020-00-E For record invalid record name

AMB does not recognize the specified record name as a valid COBOL record name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

In a data view where there are DLI and VSAM records, AMB cannot determine the type of record. Check the spelling of the named record.

Parent topic: IMS- IMS messages


IMS-3030-00-E For record PCB not found Invalid record name use COBOL record name

You did not give a PCB name the call, and AMB cannot use the default because the record name is incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-3040-00-E For view invalid view name

The PCB name specified in the call is incorrect. Check the spelling of the named View (PCB).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-3050-00-E For view for record invalid record name

Use COBOL record name. The record name specified in the call is incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-3060-00-E For record for parent parent invalid for this record

The records specified in the call are not in the proper hierarchical order.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-4010-00-E Function not now supported by PCIMS

Do not code the system service calls IM-STAT, IM-ROLL, IM-ROLB, and IM-LOG, if the target is PCIMS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-4020-00-W GSAM call generated without RSA PCIMS does not support RSA

Do not code a record search argument on the GSAM calls IM-GU, IM-GN, or IM-ISRT, if the target is PCIMS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-5010-00-E (TP) Program argument required

AMB invoked the MSG-SW call and detected that the first parameter is missing or contains nulls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the program name or transaction ID as the first parameter in the call.

Parent topic: IMS- IMS messages


IMS-5020-00-E (TP) No alt PCB for

AMB invoked $TP-CHNG-TO-DEST and found no alternate PCB was defined.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the PSB to define an alternate PCB. See Coding IMS DDI Statements. It may be necessary to contact your AMB Administrator.

Parent topic: IMS- IMS messages


IMS-5030-00-E (TP) No appropriate IO-PCB

A SEND or MSG-SW call required an alternate IO PCB with specific characteristics and the present program PSB cannot provide the appropriate PCB.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

You must match the three independent criteria specified in (or allowed to default in) the call in a single IO PCB so AMB can choose it for the call. The criteria to select an IO PCB is:

  • If you specify an LTERM or TRANCODE in the call, either hard code LTERM/TRANCODE or define the PCB as modifiable. If you provide the trancode as a COBOL data name instead of a literal constant (recognized by an LTERM/TRANCODE greater than 8 characters), you can use a modifiable PCB only.
  • For a call that specifies EXPRESS, AMB requires an EXPRESS PCB (EXPRESS=YES on PCB statement in PSB source). If the call specifies NOEXPRESS (default), then AMB requires a non-express PCB.
    Note: For MSG-SW to reference an alternate IO PCB, define that PCB with EXPRESS=NO and MODIFY=YES.
  • For a call that specifies ALTRESP, AMB requires an ALTRESP PCB (ALTRESP=YES on PCB statement in PSB source). If the call specifies NOALTRESP, then AMB requires a nonaltresp PCB.

Review the call to determine the PCB requirements. Either modify the PSB to provide a PCB with appropriate options (and redefine the modified PSB to AMB DDI) or modify the call so that its PCB requirements meet an IO PCB that is available within the PSB. See Coding IMS DDI Statements.

Parent topic: IMS- IMS messages


IMS-5040-00-F (TP) SUBSCHEMA or PSB macro not invoked

You did not invoke IM-PSB or DB-SUBSCHEMA.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

All IMS programs must invoke either IM-PSB or DB-SUBSCHEMA as the first call in the program.

Parent topic: IMS- IMS messages


IMS-5800-00-F (TP) DB2 is not a valid DB target for Micro Focus IMSVS86

The Data Definition symbols contain DB2 references.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Micro Focus IMSVS86 does not support DB2. Remove references to DB2.

Parent topic: IMS- IMS messages


IMS-6020-00-W (TP) Use TP-SEND with ENDCONV

You invoked a $TP-SEND-LAST call. AMB replaced this call with SEND.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use SEND instead of $TP-SEND-LAST. Code the keyword ENDCONV because you used a SPA.

Parent topic: IMS- IMS messages


IMS-6030-00-W (TP) Use $TP-SEND

You invoked a $TP-SEND-LAST call. AMB replaced this call with SEND.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-6040-00-E (TP) Unknown keyword

The named keyword is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-7010-00-E (TP) Screen must have value not null or spaces

AMB invoked SEND and the first parameter is missing or contains nulls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the screen name as the first parameter in the call.

Parent topic: IMS- IMS messages


IMS-7020-00-W (TP) Use $TP-MSG-SW instead of $TP-XCTL

You invoked XCTL. AMB replaced this call with MSG-SW.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-7030-00-E (TP) First parm to TP-SCRNLIST must name a screen

The SCRNLIST call found a keyword as the first parameter. Keyword parameters must follow one or more screen names.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-7040-00-E (TP) Screen must be labeled

SCRNLIST supplied the name of a screen without the LABELED option, where the input message contains the screen name as the final 8 bytes. AMB requires this so that logic generated by SCRNLIST can determine which screen it received at run time.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify that you provided the correct screen names to the SCRNLIST call. If necessary, specify the LABELED option and regenerate the screens that do not specify this option.

Parent topic: IMS- IMS messages


IMS-7050-00-E (TP) RECORD keyword invalid when using TP-SCRNLIST

The SCRNLIST call detected the RECORD keyword. RECORD is not a valid parameter for SCRNLIST.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-7060-00-E ALT LTERM required for destination-printer

When using SEND and you defined the output device in the Screen Painter to a printer, ensure that you include an alternate PCB TYPE=TP definition in the PSB source.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Define an alternate PCB TYPE=TP in the PSB source. See Coding IMS DDI Statements.

Parent topic: IMS- IMS messages


IMS-8010-00-F (TP) Include APMDCSC before APIMSTP

You included the call library member APIMSTP before the member APMDCSC.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: IMS- IMS messages


IMS-8020-00-F APIMSTP included twice - remove extra INCLUDE

You included the call library member, APIMSTP, twice.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: IMS- IMS messages


IMS-8030-00-E $TP-LINKAGE invoked twice - remove extra INCLUDE

AMB invoked the call TP-LINKAGE more than once.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-8040-00-E (TP) $TP-LINKAGE must be invoked before $TP-ENTRY

AMB invoked the call TP-LINKAGE after $TP-ENTRY.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code TP-LINKAGE before coding NTRY.

Parent topic: IMS- IMS messages


IMS-8050-00-F $TP-ENTRY must be invoked for IMS program

You compiled a program with the MDC set to IMS/DC but AMB did not encounter TP-ENTRY.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct input and resubmit; either change the program to batch or use the ENTRY keyword.

Parent topic: IMS- IMS messages


IMS-8060-00-F $TP-SCRNLIST must be invoked before TP-ENTRY

AMB encountered $TP-ENTRY, followed by SCRNLIST.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change the order of the calls so that SCRNLIST appears first.

Parent topic: IMS- IMS messages


IMS-8070-00-F TP-SCRNLIST invoked more than once

Only one invocation of SCRNLIST is valid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-8080-00-E xmlNOSPA keyword used twice

Only one SPA keyword allowed per SCRNLIST call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: IMS- IMS messages


IMS-9010-00-F Missing include SCRSYMB for SCR

The screen symbols for the named screen are missing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: IMS- IMS messages


IMS-9020-01-F IMS-9020-02-F PROGRAM-INVOKED para for non-conversational IMS program

A nonconversational IMS/DC program contains the paragraph APS-PROGRAM-INV-PARA. In a program using design mode, AMB performs this paragraph when the program is TP-PROGRAM-INVOKED. Usually, you set TP-PROGRAM-INVOKED to TRUE for a conversational program only. The presence of APS-PROGRAM-INV-PARA in a nonconversational program is a conflict, and may not function as intended.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

To keep the paragraph, explicitly perform it from user-written logic, or define the program as conversational by specifying &TP-USER-LEN 0. Otherwise, remove the paragraph.

Parent topic: IMS- IMS messages


INT- initialization module messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • INT-5001-00-F Not enough core for FMP tables RETURN-CODE
    The program requires more core for the FMP step than requested on the EXEC step of the AMB precompile. If the cause is an incorrectly coded FMP loop, AMB increases the FMP loop limit.
Parent topic: AppMaster Builder Error Messages


INT-5001-00-F Not enough core for FMP tables RETURN-CODE

The program requires more core for the FMP step than requested on the EXEC step of the AMB precompile. If the cause is an incorrectly coded FMP loop, AMB increases the FMP loop limit.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Increase the amount of core on the EXEC step, or decrease the loop limit and correct the FMP loop code.

Parent topic: INT- initialization module messages


MDC- TP data communication messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • MDC-1010-00-E $TP-ENTRY missing
    You did not invoke the $TP-ENTRY call.
  • MDC-1020-00-E Subscript missing for SCR
    An attributed field, within a repeated block, is missing the subscript for that field.
  • MDC-1030-00-E SCR FLD is not a repeated field
    You coded an attributed field with a subscript, and that field is not part of a repeated block.
  • MDC-1040-00-E FLD is not a valid field for SCR
    The field name is not a valid field for the named screen.
  • MDC-1050-00-E Required screen name not supplied
    You coded the call without a screen name.
  • MDC-2010-00-E No room for sign
    A numeric field, specified for editing, does not have room for the sign.
  • MDC-2020-00-E NO ROOM FOR SIGN-DEC POINT
    A numeric field, specified for editing, does not have room for both the sign and the decimal point.
  • MDC-2030-00-E Macro named as edit for FLD contained in screen was not defined
    During screen generation, the field editing calls found a field that you specified for a user edit call. However, you did not define that user call.
  • MDC-4010-00-E Too many one character TSO fields
    There can be a maximum of 25 one character fields on a TSO screen.
  • MDC-4035-00-E Combination of attributes not recognized in attribute table
    AMB cannot find the combination of attributes in the attribute table.
  • MDC-8010-00-F APMDCSC included twice - remove extra INCLUDE
    You included the member APMDCSC more than once.
  • MDC-9010-00-F unknown MDC parm
    The DC target is unknown.
  • MDC-9020-00-F improper &ampTP(SC)-SSF-LIB
    The screen symbol library is invalid.
Parent topic: AppMaster Builder Error Messages


MDC-1010-00-E $TP-ENTRY missing

You did not invoke the $TP-ENTRY call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Invoke $TP-ENTRY after Working-Storage section. Use it in lieu of Procedure Division.

Parent topic: MDC- TP data communication messages


MDC-1020-00-E Subscript missing for SCR

An attributed field, within a repeated block, is missing the subscript for that field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MDC- TP data communication messages


MDC-1030-00-E SCR FLD is not a repeated field

You coded an attributed field with a subscript, and that field is not part of a repeated block.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MDC- TP data communication messages


MDC-1040-00-E FLD is not a valid field for SCR

The field name is not a valid field for the named screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MDC- TP data communication messages


MDC-1050-00-E Required screen name not supplied

You coded the call without a screen name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MDC- TP data communication messages


MDC-2010-00-E No room for sign

A numeric field, specified for editing, does not have room for the sign.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Make the field large enough to hold the sign.

Parent topic: MDC- TP data communication messages


MDC-2020-00-E NO ROOM FOR SIGN-DEC POINT

A numeric field, specified for editing, does not have room for both the sign and the decimal point.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Make the field large enough to hold the sign and a decimal point.

Parent topic: MDC- TP data communication messages


MDC-2030-00-E Macro named as edit for FLD contained in screen was not defined

During screen generation, the field editing calls found a field that you specified for a user edit call. However, you did not define that user call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify that the call name is correct and that you included a definition of the call for the compile.

Parent topic: MDC- TP data communication messages


MDC-4010-00-E Too many one character TSO fields

There can be a maximum of 25 one character fields on a TSO screen.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MDC- TP data communication messages


MDC-4035-00-E Combination of attributes not recognized in attribute table

AMB cannot find the combination of attributes in the attribute table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: MDC- TP data communication messages


MDC-8010-00-F APMDCSC included twice - remove extra INCLUDE

You included the member APMDCSC more than once.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: MDC- TP data communication messages


MDC-9010-00-F unknown MDC parm

The DC target is unknown.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator. The FMP symbol, &APS-MDC, is invalid.

Parent topic: MDC- TP data communication messages


MDC-9020-00-F improper &ampTP(SC)-SSF-LIB

The screen symbol library is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: MDC- TP data communication messages


PRM- AMB parameter messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • PRM-2001-00-E Unknown language name
    You entered an invalid language parameter.
  • PRM-2002-00-E Unknown target name
    You entered an invalid target parameter.
  • PRM-2003-00-E Improper XLATE value
    You entered an invalid XLATE value.
  • PRM-2004-00-E Improper debug value
    The debug parameter used and you coded a misspelled or invalid parameter.
  • PRM-2005-00-E Improper SEQ value
    You entered an invalid SEQ value.
  • PRM-2006-00-E Unprivileged parameter use
    You entered an unauthorized parameter.
  • PRM-2007-00-E 4 characters required
    You coded a misspelled or invalid parameter value for the FMP-CHARS parameter, which requires a minimum of four (4) characters. The 4 default characters are % $ & + .
  • PRM-2008-00-E Unknown parameter keyword
    You specified an invalid parameter.
  • PRM-2009-00-E Equal sign missing
    The equal sign before the specified parameter value is missing.
  • PRM-5001-00-F Parameters inconsistent with S-FORTRAN
    You cannot use the XLATE parameter values with an S-FORTRAN target.
Parent topic: AppMaster Builder Error Messages


PRM-2001-00-E Unknown language name

You entered an invalid language parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PRM-2002-00-E Unknown target name

You entered an invalid target parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PRM-2003-00-E Improper XLATE value

You entered an invalid XLATE value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PRM-2004-00-E Improper debug value

The debug parameter used and you coded a misspelled or invalid parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator if you need the DEBUG option.

Parent topic: PRM- AMB parameter messages


PRM-2005-00-E Improper SEQ value

You entered an invalid SEQ value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PRM-2006-00-E Unprivileged parameter use

You entered an unauthorized parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove parameter or see your AMB Administrator.

Parent topic: PRM- AMB parameter messages


PRM-2007-00-E 4 characters required

You coded a misspelled or invalid parameter value for the FMP-CHARS parameter, which requires a minimum of four (4) characters. The 4 default characters are % $ & + .
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PRM-2008-00-E Unknown parameter keyword

You specified an invalid parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PRM-2009-00-E Equal sign missing

The equal sign before the specified parameter value is missing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PRM-5001-00-F Parameters inconsistent with S-FORTRAN

You cannot use the XLATE parameter values with an S-FORTRAN target.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PRM- AMB parameter messages


PST- message report messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • PST-1000-00-F COBOL compiler message overflow
    AMB reached the maximum of 300 error messages.
  • PST-1001-00-F Message table full truncated
    AMB reached the maximum of 462 error messages.
  • PST-4000-00-I SEQ-PAIR overflow compile COBOL separately
    The internal tracking of the sequence numbering exceeded the maximum of 900. This error can result from the NUM option turned off for the COBOL compile.
  • PST-4001-00-I AMB error message problem - is NUM option on
    During internal error message tracking, the error message and source line are not in order. The NUM option is not on in the COBOL compile.
Parent topic: AppMaster Builder Error Messages


PST-1000-00-F COBOL compiler message overflow

AMB reached the maximum of 300 error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PST- message report messages


PST-1001-00-F Message table full truncated

AMB reached the maximum of 462 error messages.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PST- message report messages


PST-4000-00-I SEQ-PAIR overflow compile COBOL separately

The internal tracking of the sequence numbering exceeded the maximum of 900. This error can result from the NUM option turned off for the COBOL compile.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Recompile program using NUM option if not already turned on. Otherwise, compile program in stages with AMB compile first and then the COBOL compile.

Parent topic: PST- message report messages


PST-4001-00-I AMB error message problem - is NUM option on

During internal error message tracking, the error message and source line are not in order. The NUM option is not on in the COBOL compile.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Recompile using the NUM option.

Parent topic: PST- message report messages


PTR- Painter system messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • PTR -5410-00-E COPY only allowed with 01 TYPE keyword
    Use the COPY verb only with an 01 keyword for data structures.
  • PTR -5415-00-E Multiple PROC keywords are invalid
  • PTR -5424-00-E Line can only start with $ &amp - or alpha character
    Line must start with valid alpha COBOL character or Customizer symbol ($ % & or /).
  • PTR -5425-00-E No room for a closing period on this line
    Line in program is too long for period to be added during conversion.
  • PTR -5428-00-E ENTER verb must be followed by COBOL or S-COBOL only
    A statement beginning with ENTER has a word other than COBOL or S-COBOL after it.
  • PTR-0000-00-I Copyright year MICRO FOCUS &ampsq&ampAPS-rel &amppgm-id &ampcompiletime&ampsq
  • PTR-0201-00-I EXP-0201-00-I Data structure change successful
    This message occurs when using the K line call, and all changes or line additions are correct when passed back to the Program Painter.
  • PTR-0204-00-I Convert not successful
    An error was encountered in the code. Correct error before continuing.
  • PTR-0400-00-I Only keyword needed is REC - keyword changed
    If keywords such as WS or CA are entered, the Data Structure Editor no longer requires them and converts them to REC.
  • PTR-0800-00-I Info-literal may not be contained within QUOTES-APOSTS
    The TRANCODE literal field was entered with quotes. The quotes were removed because they are not valid.
  • PTR-0801-00-I INFO-FILL character of NULL assumed for PFKEY
    The TRANCODE Fill field was changed to N since TRANCODE is a PF key and not a literal.
  • PTR-1801-00-W xmlPFKEY specified as trancode but not defined PFKEY trancode ignored
    *PFkey was supplied in the trancode construction dialog box, but no values were assigned the MFS function keys.
  • PTR-1805-00-W Warning - Field name SYSMSG conflicts with SYSMSG parm value
    "SYSMSG" was used as the name for an IO field, and "YES" or "SYSMSG" was specified in the SYSMSG field.
  • PTR-1806-00-W Warning - SYSMSG over AMB text repeated block or I-O field
    SYSMSG or YES was specified in the SYSMSG field, but the default line for building the SYSMSG field already contains a field on it.
  • PTR-1807-00-W Warning - Oper logical paging requested without trancode field
    Operator logical paging was set to YES, but an optional trancode field name or trancode construction was not specified. See Assigning Screen Attributes.
  • PTR-1809-00-W Warning - TC constructed but xmlTC not specified for trancode fld
    Field names or default literals were supplied for trancode construction screen, but trancode construction was not activated.
  • PTR-1810-00-W Warning - PFKEYS defined but xmlPF not specified for trancode fld
    PFkey values were supplied for the MFS function keys, but the function keys weren't activated as the trancode.
  • PTR-5401-00-E Format on group level is not allowed
    Format is entered next to a group level. This is illegal in COBOL.
  • PTR-5422-00-E No match for quote or apostrophe
    Arguments have incorrect syntax. Ensure that each quote or apostrophe is paired.
  • PTR-5432-00-E PARA keyword must be followed by a paragraph name or section name in column 8 on the same line as the PARA keyword
  • PTR-5433-00-E Literal exceeds 120 characters
    Continuation of a literal exceeds 120 characters. The literal is too long.
  • PTR-5435-00-E Above keyword must be followed by the entity name to be accessed
    The required entity name missing after the keyword.
  • PTR-5436-00-E The above keyword is invalid
  • PTR-5800-00-E Error-literal contains illegal characters - line
    The literal contains quotes. Remove the quotes from the literal.
  • PTR-5802-00-E Error - xmlPFKEY may only be specified once per trancode
    The transaction code cannot be built using repeated names.
  • PTR-5803-00-E Error - fld name may not be used twice in trancode - line
    Cannot construct trancode using a field more than once.
  • PTR-5809-00-E Error - row specified for SYSMSG not numeric or out of range
    The line number specified for SYSMSG is less than 1 or greater than screen depth.
  • PTR-5810-00-E Error - invalid characters contained in field
    A character was found that was not alphabetic, numeric, or '#', '$', or '@'.
  • PTR-5811-00-E Error - DIF-DOF-MID-MOD names must be unique
    The input and output maps can't be distinguished from each other.
  • PTR-5812-00-E Error - segment exit not numeric or out of range
    The MID segment exit number or vector is not numeric or is out of range.
  • PTR-5813-00-E Error - both nbr and vector are required for segment exits
    The MID segment exit number and vector are not compatible.
  • PTR-5814-00-E Error - value specified for MOD fill character is invalid
    Fill character can only be null. Enter 'NULL' in field.
  • PTR-5815-00-E Error - intensity may only be BRIGHT or NORMAL for text
  • PTR-5816-00-E Error - invalid value specified for COLOR
    Abbreviation entered for color selection is invalid.
  • PTR-5818-00-E Error - numeric range specified is invalid
    Either the ranges specified exceed the screen size, or the first range exceeds the second range. See numeric range.
  • PTR-5819-00-E Error - length specified for SYSMSG not numeric or out of range
    The length specified for SYSMSG not numeric, or it exceeds the screen width.
  • PTR-7400-00-E Invalid keyword in indicated line
    Keyword entered is not recognized by the Painter system.
  • PTR-7401-00-E 77 level must start in margin A
    A 77-level data item must start in column 8.
  • PTR-7402-00-E Data name must start with alpha or &amp
    Data names must begin with an alphabetic character, & or < .
  • PTR-7403-00-E Level will be too high -- highest level is 49
    A level higher than 49 will be generated.
  • PTR-7404-00-E Invalid syntax after data name
    Syntax violates COBOL or Data Structure call syntax.
  • PTR-7406-00-E Only data name can follow 88 or 66 levels
    A valid data name must follow an 88 or 66 . . . RENAMES level number.
  • PTR-7407-00-E Data name for structure must be on line 1
    All data structures must have a valid keyword and data name on line 1.
  • PTR-7408-00-E Alphabetic format AAAAAAANA(N) A(&ampSYM)
    If an A is the first character in the format field, then the code must be in one of the valid formats.
  • PTR-7409-00-E Invalid computational (C) form at spec
    C is invalid as used. Use a valid format.
  • PTR-7412-00-E Numeric format NN2N3N$ NKN(K)N&ampSYM
    If an N is the first character in the format field, then the code must be in one of the valid formats.
  • PTR-7413-00-ERedefines format is R RED REDEF REDEFINES
    Invalid format for REDEFINES was entered.
  • PTR-7414-00-E Signed numeric format S SN S&ampSYM
    Signed symbol is invalid format as used.
  • PTR-7415-00-E Alphanumeric format XXXXXXXKX(K)X(&ampSYM)
    Alphanumeric symbol is invalid format as used.
  • PTR-7416-00-E Numeric format 99293949K9(K)9&ampSYM
    Numeric format is invalid format as used.
  • PTR-7417-00-E To indicate PICTURE must use PIC
    If the P is the first character in the format field, then the PICTURE clause is expected.
  • PTR-7418-00-E OCCURS specification not allowed in format
    OCCURS symbol is not entered in the data name field.
  • PTR-7422-00-E Invalid character follows space in format
    Only V or R can continue a format.
  • PTR-7423-00-E Value can be first format only on 88 levels
    Only an 88 level value can be assigned first in a format.
  • PTR-7424-00-E Invalid data format Recheck format specification
    This is an invalid data structure.
  • PTR-7425-00-E Cannot specify format for a group level item
    A PICture clause on a group level is illegal.
  • PTR-7428-00-E No format spec allowed on 66 level RENAMES
    Invalid format on 66-level data item.
  • PTR-7429-00-E V (VALUE) is only valid format for 88 levels
    Invalid 88-level data items format.
  • PTR-7430-00-E Selected entity is being edited by another
  • PTR-7431-00-E No spaces allowed in FMP variable name
    The variable name has space(s) embedded in it.
  • PTR-7432-00-E Comments start in data name field - no keyword
    Comment line was specified in the keyword field.
  • PTR-7480-00-E Valid formats beginning with I are I or INDEXED
  • PTR-7481-00-E Valid formats beginning with R are R or REDEFINES
  • PTR-7483-00-E PICTURE clause incomplete--no data field type specified
    An empty PIC clause was entered. Enter a valid PICture clause.
  • PTR-7484-00-E OCCURS clause is described with invalid occurrence of table
    An invalid statement following the OCCURS clause was entered.
  • PTR-7485-00-E REDEFINES clause must precede OCCURS clause
    The OCCURS specification must be entered before the REDEFINES clause.
  • PTR-7490-00-E EGCS value too long
    The EGCS literal exceeds 54 characters, the limit for EGCS literals.
Parent topic: AppMaster Builder Error Messages


PTR -5410-00-E COPY only allowed with 01 TYPE keyword

Use the COPY verb only with an 01 keyword for data structures.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR -5415-00-E Multiple PROC keywords are invalid

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove extra keywords.

Parent topic: PTR- Painter system messages


PTR -5424-00-E Line can only start with $ &amp - or alpha character

Line must start with valid alpha COBOL character or Customizer symbol ($ % & or /).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR -5425-00-E No room for a closing period on this line

Line in program is too long for period to be added during conversion.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR -5428-00-E ENTER verb must be followed by COBOL or S-COBOL only

A statement beginning with ENTER has a word other than COBOL or S-COBOL after it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-0000-00-I Copyright year MICRO FOCUS &ampsq&ampAPS-rel &amppgm-id &ampcompiletime&ampsq

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: PTR- Painter system messages


PTR-0201-00-I EXP-0201-00-I Data structure change successful

This message occurs when using the K line call, and all changes or line additions are correct when passed back to the Program Painter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: PTR- Painter system messages


PTR-0204-00-I Convert not successful

An error was encountered in the code. Correct error before continuing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-0400-00-I Only keyword needed is REC - keyword changed

If keywords such as WS or CA are entered, the Data Structure Editor no longer requires them and converts them to REC.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-0800-00-I Info-literal may not be contained within QUOTES-APOSTS

The TRANCODE literal field was entered with quotes. The quotes were removed because they are not valid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-0801-00-I INFO-FILL character of NULL assumed for PFKEY

The TRANCODE Fill field was changed to N since TRANCODE is a PF key and not a literal.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-1801-00-W xmlPFKEY specified as trancode but not defined PFKEY trancode ignored

*PFkey was supplied in the trancode construction dialog box, but no values were assigned the MFS function keys.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Supply a transaction code value on the MFS function keys definition dialog box, or do not specify *PFKEYS as the transaction code.

Parent topic: PTR- Painter system messages


PTR-1805-00-W Warning - Field name SYSMSG conflicts with SYSMSG parm value

"SYSMSG" was used as the name for an IO field, and "YES" or "SYSMSG" was specified in the SYSMSG field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Either change the name of the IO field and supply that name for SYSMSG, or delete the IO field and allow the SYSMSG parameter to build the IO field upon screen generation. See Creating System Message Fields.

Parent topic: PTR- Painter system messages


PTR-1806-00-W Warning - SYSMSG over AMB text repeated block or I-O field

SYSMSG or YES was specified in the SYSMSG field, but the default line for building the SYSMSG field already contains a field on it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the field from the last line of the screen. See also Creating System Message Fields.

Parent topic: PTR- Painter system messages


PTR-1807-00-W Warning - Oper logical paging requested without trancode field

Operator logical paging was set to YES, but an optional trancode field name or trancode construction was not specified. See Assigning Screen Attributes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-1809-00-W Warning - TC constructed but xmlTC not specified for trancode fld

Field names or default literals were supplied for trancode construction screen, but trancode construction was not activated.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Specify *TC as the optional trancode field. See Assigning Screen Attributes.

Parent topic: PTR- Painter system messages


PTR-1810-00-W Warning - PFKEYS defined but xmlPF not specified for trancode fld

PFkey values were supplied for the MFS function keys, but the function keys weren't activated as the trancode.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Specify *PF as the optional trancode field name. See Assigning Screen Attributes.

Parent topic: PTR- Painter system messages


PTR-5401-00-E Format on group level is not allowed

Format is entered next to a group level. This is illegal in COBOL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5422-00-E No match for quote or apostrophe

Arguments have incorrect syntax. Ensure that each quote or apostrophe is paired.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5432-00-E PARA keyword must be followed by a paragraph name or section name in column 8 on the same line as the PARA keyword

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5433-00-E Literal exceeds 120 characters

Continuation of a literal exceeds 120 characters. The literal is too long.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5435-00-E Above keyword must be followed by the entity name to be accessed

The required entity name missing after the keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5436-00-E The above keyword is invalid

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the spelling.

Parent topic: PTR- Painter system messages


PTR-5800-00-E Error-literal contains illegal characters - line

The literal contains quotes. Remove the quotes from the literal.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5802-00-E Error - xmlPFKEY may only be specified once per trancode

The transaction code cannot be built using repeated names.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove extra occurrences of PFKEY. See also Assigning Screen Attributes.

Parent topic: PTR- Painter system messages


PTR-5803-00-E Error - fld name may not be used twice in trancode - line

Cannot construct trancode using a field more than once.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra occurrences of the field name. See also Assigning Screen Attributes.

Parent topic: PTR- Painter system messages


PTR-5809-00-E Error - row specified for SYSMSG not numeric or out of range

The line number specified for SYSMSG is less than 1 or greater than screen depth.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5810-00-E Error - invalid characters contained in field

A character was found that was not alphabetic, numeric, or '#', '$', or '@'.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5811-00-E Error - DIF-DOF-MID-MOD names must be unique

The input and output maps can't be distinguished from each other.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Rename one of the maps.

Parent topic: PTR- Painter system messages


PTR-5812-00-E Error - segment exit not numeric or out of range

The MID segment exit number or vector is not numeric or is out of range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5813-00-E Error - both nbr and vector are required for segment exits

The MID segment exit number and vector are not compatible.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Enter a numeric value for both number and vector. See also Assigning Screen Attributes.

Parent topic: PTR- Painter system messages


PTR-5814-00-E Error - value specified for MOD fill character is invalid

Fill character can only be null. Enter 'NULL' in field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5815-00-E Error - intensity may only be BRIGHT or NORMAL for text

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change intensity attribute to bright or normal for text fields.

Parent topic: PTR- Painter system messages


PTR-5816-00-E Error - invalid value specified for COLOR

Abbreviation entered for color selection is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5818-00-E Error - numeric range specified is invalid

Either the ranges specified exceed the screen size, or the first range exceeds the second range. See numeric range.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-5819-00-E Error - length specified for SYSMSG not numeric or out of range

The length specified for SYSMSG not numeric, or it exceeds the screen width.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7400-00-E Invalid keyword in indicated line

Keyword entered is not recognized by the Painter system.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7401-00-E 77 level must start in margin A

A 77-level data item must start in column 8.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7402-00-E Data name must start with alpha or &amp

Data names must begin with an alphabetic character, & or < .
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7403-00-E Level will be too high -- highest level is 49

A level higher than 49 will be generated.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Either change the startup level, or reduce the number of indentations.

Parent topic: PTR- Painter system messages


PTR-7404-00-E Invalid syntax after data name

Syntax violates COBOL or Data Structure call syntax.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7406-00-E Only data name can follow 88 or 66 levels

A valid data name must follow an 88 or 66 . . . RENAMES level number.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7407-00-E Data name for structure must be on line 1

All data structures must have a valid keyword and data name on line 1.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7408-00-E Alphabetic format AAAAAAANA(N) A(&ampSYM)

If an A is the first character in the format field, then the code must be in one of the valid formats.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7409-00-E Invalid computational (C) form at spec

C is invalid as used. Use a valid format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7412-00-E Numeric format NN2N3N$ NKN(K)N&ampSYM

If an N is the first character in the format field, then the code must be in one of the valid formats.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7413-00-ERedefines format is R RED REDEF REDEFINES

Invalid format for REDEFINES was entered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7414-00-E Signed numeric format S SN S&ampSYM

Signed symbol is invalid format as used.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7415-00-E Alphanumeric format XXXXXXXKX(K)X(&ampSYM)

Alphanumeric symbol is invalid format as used.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7416-00-E Numeric format 99293949K9(K)9&ampSYM

Numeric format is invalid format as used.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7417-00-E To indicate PICTURE must use PIC

If the P is the first character in the format field, then the PICTURE clause is expected.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7418-00-E OCCURS specification not allowed in format

OCCURS symbol is not entered in the data name field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7422-00-E Invalid character follows space in format

Only V or R can continue a format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7423-00-E Value can be first format only on 88 levels

Only an 88 level value can be assigned first in a format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7424-00-E Invalid data format Recheck format specification

This is an invalid data structure.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7425-00-E Cannot specify format for a group level item

A PICture clause on a group level is illegal.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7428-00-E No format spec allowed on 66 level RENAMES

Invalid format on 66-level data item.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7429-00-E V (VALUE) is only valid format for 88 levels

Invalid 88-level data items format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7430-00-E Selected entity is being edited by another

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Try again later.

Parent topic: PTR- Painter system messages


PTR-7431-00-E No spaces allowed in FMP variable name

The variable name has space(s) embedded in it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7432-00-E Comments start in data name field - no keyword

Comment line was specified in the keyword field.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Begin comment line with % *, /* , or * in the data name field.

Parent topic: PTR- Painter system messages


PTR-7480-00-E Valid formats beginning with I are I or INDEXED

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See valid formats.

Parent topic: PTR- Painter system messages


PTR-7481-00-E Valid formats beginning with R are R or REDEFINES

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See valid formats.

Parent topic: PTR- Painter system messages


PTR-7483-00-E PICTURE clause incomplete--no data field type specified

An empty PIC clause was entered. Enter a valid PICture clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7484-00-E OCCURS clause is described with invalid occurrence of table

An invalid statement following the OCCURS clause was entered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7485-00-E REDEFINES clause must precede OCCURS clause

The OCCURS specification must be entered before the REDEFINES clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


PTR-7490-00-E EGCS value too long

The EGCS literal exceeds 54 characters, the limit for EGCS literals.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: PTR- Painter system messages


RWT- Report Writer messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • RWT-1002-00-F SOURCE-SUM-VALUE buffer overflow
    You exceeded the limit (300) of SOURCE, SUM, and VALUE entries in one source program.
  • RWT-1003-00-F Mock-up buffer overflow
    You exceeded the limit of 200 lines in the left half of the mock-up.
  • RWT-1004-00-F Report limit reached for FD
    The number of reports specified within a Report clause exceeds 15.
  • RWT-1005-00-F Invalid keyword or period missing in RED hdr
    AMB detected a clause beginning with a keyword other than CONTROL, CODE, PAGE, FIRST, LAST, HEADING, FOOTING, or WRITE in the Report Description statement or the required period at the end of the Report description statement is missing.
  • RWT-1006-00-F CONTROL ITEM MAXIMUM EXCEEDED
    You exceeded the maximum number of control items (28) allowed for the report.
  • RWT-1007-01-F RWT-1007-02-F Report data name missing
    You did not follow a TERMINATE or INITIATE statement with a data name.
  • RWT-1008-00-F Invalid INITIATE statement
    You followed an INITIATE statement with an invalid report name.
  • RWT-1009-00-F GENERATE data name missing
    You did not follow a GENERATE statement with a data name.
  • RWT-1010-00-F Improper GENERATE statement
    You followed a GENERATE statement with an invalid report name or data name.
  • RWT-1011-00-F Invalid TERMINATE statement
    You followed a TERMINATE statement with an invalid report name.
  • RWT-1012-00-F Declaratives statement missing
    AMB did not find a Declaratives statement before encountering an END statement.
  • RWT-1013-00-F END statement missing for declaratives
    AMB did not find an END Declaratives statement for the Declaratives section.
  • RWT-1016-00-F PIC not given for detail item
    AMB encountered a detail item without an associated PICture clause.
  • RWT-1017-00-F Detail symbol storage failure call AMB rep
    A problem occurred storing the detail items. Execution halts.
  • RWT-1019-00-F PIC not given for identifier item
    AMB encountered an identifier item without an associated PICture clause.
  • RWT-1021-00-F Report desc keyword missing or in wrong col
    The RED keyword is missing or coded in the wrong column.
  • RWT-1024-00-F Control variable required with CH-CF clause
    A valid data name must follow the CH (Control Heading) or CF (Control Footing) clauses.
  • RWT-1027-00-F Only numeric literals permitted for detail
    You can use numeric literals only with detail.
  • RWT-1029-00-F Illegal literal
    The number of characters where a literal should be is equal to zero. Therefore, it is invalid.
  • RWT-1030-00-F -PAGE- MUST BE FIRST ENTRY FOR GROUP
    Use PAGE once for a group; it must precede all other parameters.
  • RWT-1032-00-F Num enclosed by - permitted in detail only
    /INTEGER/ indicates a relative number of lines to advance before presenting the first line of the group if used with detail.
  • RWT-1034-00-F G-C INDICATE permitted for detail only
    You can only use the GROUP INDICATE and CHANGE INDICATE clauses with detail lines.
  • RWT-1035-00-F No identifier given for G-C INDICATE
    GROUP and CHANGE INDICATE both require an identifier.
  • RWT-1036-00-F PIC permitted for detail only
    AMB allows PICture clauses for detail items only.
  • RWT-1037-00-F No identifier given for PIC
    Identifier is missing before the specified PICture clause.
  • RWT-1038-00-F No identifier given for subscript-index
    AMB encountered a subscript or index not prefixed with an identifier. AMB halts execution.
  • RWT-1039-00-F Iterative subscript permitted in detail only
    Use iterative subscripts for detail lines only.
  • RWT-1040-00-F Only 3 levels of sub-index permitted
    AMB allows only 3 levels of subscripts or indices are permitted.
  • RWT-1042-00-F Illegal subscript-index
    The subscript or index as coded is incorrect.
  • RWT-1045-00-F Incorrect sequence of parameters in detail
    The parameters used in the detail group were syntactically incorrect.
  • RWT-1046-00-F At least 1 ID must be given in detail
    There must be at least one identifier in each detail line.
  • RWT-1047-00-F Numeric 4 digits
    The integer specified for a PAGE LIMIT, FIRST DETAIL, LAST DETAIL, HEADING, or FOOTING or clause is greater than 4 digits.
  • RWT-1048-00-F Expecting numeric found nonnumeric
    AMB expected an integer in the PAGE LIMIT, HEADING, DETAIL or FOOTING clauses and did not find it.
  • RWT-1049-00-F Numeric must be greater than 0
    AMB encountered a negative number where only a positive number is allowed.
  • RWT-1050-00-F PH-ATOM storage problem CALL AMB REP
    AMB encountered a problem in PAGE HEADING storage. Execution stops.
  • RWT-1051-00-F Detail group must be given
    A Detail group must follow a DETAIL clause.
  • RWT-1052-00-F Duplicate report group
    When processing multiple reports, AMB found a duplicate Report group.
  • RWT-1053-00-F CH-CF control var not found in CTRL clause
    You must use a control variable with a control heading and control footing in a CONTROL clause.
  • RWT-1054-00-F MOCK-UP must immediately follow RED entry
    AMB found something other than a mock-up delimiter following the Report Description statement.
  • RWT-1055-00-F Mock-up not found
    AMB did not find a mock-up for a Report Description entry.
  • RWT-1057-00-F Data name missing on TYPE IS CH-CF
    You did not specify a control identifier (data name) on a TYPE clause for a Control Heading (CH) or Control Footing (CF) group.
  • RWT-1058-00-F Anim-debug overflow
    You exceeded the buffer limit (25) for consecutive debugger lines. A block of comments with more than 25 lines is probably the cause.
  • RWT-2001-00-E RWT-2001-02-E Mock-up and MOCKUP statement incompatible
    AMB found a mock-up statement when using group mock-ups. Use MOCKUP statements only with report mock-ups.
  • RWT-2002-00-E MOCKUP statement must be first
    AMB encountered a mock-up statement out of sequence in a Group Description entry.
  • RWT-2003-00-E LINE statement must be after MOCKUP
    AMB encountered a LINE statement out of sequence in a group description entry.
  • RWT-2004-00-E Invalid line number
    Characters following a LINE NUMBER statement are not numeric.
  • RWT-2005-00-E Invalid SOURCE SUM or VALUE statement
    You did not code an item description entry (SOURCE, SUM, or VALUE statement) correctly.
  • RWT-2008-00-E Unmatched SUM-SOURCE-VALUE clause
    You coded a SUM, SOURCE, or VALUE clause for which there is no matching picture in the mock-up. Possibly, you did not delete a SOURCE clause that you no longer reference in the mock-up. Or possibly, MOCKUP line statements do not accurately match the lines specified for each group in the mock-up.
  • RWT-2009-00-E PIC missing for REFERENCE
    A REFERENCE statement contains no PICture clause.
  • RWT-2010-00-E Too many lines in right half of mock-up
    The right half of the mock-up has more lines than the left.
  • RWT-2011-00-E Mock-up continuation missing
    AMB did not find the right half of the report mock-up following the left half.
  • RWT-2012-00-E Right half mock-up overflow
    You exceeded the limit of 200 lines in the right half of the mock-up.
  • RWT-2013-00-E Improper beginning mock-up reference
    A MOCKUP statement specifies a line number outside the range of the report mock-up as its beginning line, or AMB found a MOCKUP statement for a group mock-up.
  • RWT-2014-00-E Improper ending mock-up reference
    A MOCKUP statement using the INTEGER-1 through INTEGER-2 format, specifies a line number outside the range of the report mock-up as its ending line (INTEGER-2).
  • RWT-2015-00-E Obsolete syntax temporarily excepted
    You specified a data name following a left parenthesis in a SOURCE clause.
  • RWT-2016-00-E Remove left paren (obsolete syntax)
    You specified a data name following a left parenthesis in a SOURCE clause without a closing right parenthesis.
  • RWT-2017-00-E PICTURE missing
    You did not follow the keyword designating a PICture or IS in a SUM/SOURCE/VALUE statement with a COBOL picture character.
  • RWT-2018-00-E Improper PICTURE no closing parens
    In a PICture clause of a SUM/SOURCE/VALUE or REFERENCE clause, AMB encountered an opening parenthesis following a valid PICture character with no closing parenthesis.
  • RWT-2019-00-E Invalid character for PICTURE clause
    In a PICture clause of a SUM/SOURCE/VALUE or REFERENCE clause, AMB encountered a character other than X 9 Z $ , 0 . + - C R D * V E ( ).
  • RWT-2020-00-E Missing quoted OVERPRINT text
    AMB encountered an OVERPRINT statement without a character string enclosed in quotes.
  • RWT-2021-00-E Improper file name
    You followed a File Description entry (FD) by blanks or an invalid file name.
  • RWT-2022-00-E RWT-2023-00-E Improper BLOCK CONTAINS clause
    Invalid BLOCK CONTAINS format. You coded the clause with something other than characters or records or you did not specify an unsigned integer. If you coded the optional INTEGER-1 to INTEGER-2 format, INTEGER-2 is not an unsigned integer.
  • RWT-2024-00-E RWT-2025-01-E RWT-2025-02-E RWT-2026-00-E Improper RECORD CONTAINS clause
    Invalid RECORD CONTAINS format. You coded the clause with something other than characters or records or you did not specify an unsigned integer. If you coded the optional INTEGER-1 to INTEGER-2 format, INTEGER-2 is not an unsigned integer.
  • RWT-2027-01-E RWT-2027-02-E Improper LABEL RECORDS clause
    Invalid LABEL RECORDS format.
  • RWT-2028-00-E Improper FILE-ID clause
    Invalid FILE ID format.
  • RWT-2029-00-E Improper FILE REPORTS clause
    Invalid REPORT clause format.
  • RWT-2030-00-E Improper DATA RECORDS clause
    Invalid DATA RECORDS format.
  • RWT-2031-00-E IMPROPER RD NAME
    You followed a Report Description entry (RED) with blanks or an invalid name.
  • RWT-2032-00-E Improper RED statement
    You followed a CODE clause with an invalid mnemonic name or with blanks.
  • RWT-2033-00-E RWT-2033-02-E Improper CONTROL clause
    You coded a CONTROL clause in an invalid format.
  • RWT-2034-00-E Improper PAGE LIMIT clause
    Invalid PAGE LIMIT format, or the clause specifies 0 as the last line where you can print anything.
  • RWT-2035-00-E Improper HEADING clause
    Invalid HEADING format, or the clause specifies 0 as the first line number of the heading print group.
  • RWT-2036-00-E Improper FIRST DETAIL clause
    Invalid FIRST DETAIL format, or the clause specifies 0 as the first line number of the body group.
  • RWT-2037-00-E RWT-2037-02-E Improper LAST DETAIL clause
    Invalid LAST DETAIL format, or the clause specifies 0 as the last line number of the last nonfooting body group.
  • RWT-2038-00-E Improper FOOTING clause
    Invalid FOOTING format. The clause specifies 0 as the last line number of the last Control Footing Report group.
  • RWT-2039-00-E Improper TYPE clause
    A TYPE clause specifies an invalid option.
  • RWT-2040-00 Improper LINE clause
    Invalid LINE format, or INTEGER-1 is not a positive integer for the LINE NUMBER IS INTEGER-1 format, or INTEGER-2 is not a positive integer for the LINE NUMBER plus INTEGER-2 format.
  • RWT-2041-00-E Improper NEXT GROUP clause
    Invalid NEXT GROUP format, or INTEGER-1 is not a positive integer for the NEXT GROUP IS INTEGER-1 format, or INTEGER-2 is not a positive integer for the NEXT GROUP IS PLUS INTEGER-2 format.
  • RWT-2042-00-E Improper USAGE clause Invalid USAGE format
    You specified a USAGE other than DISPLAY.
  • RWT-2043-00-E Improper RESET clause
    Invalid RESET option format with the SUM clause.
  • RWT-2044-00-E Improper JUSTIFIED clause
    Invalid JUSTIFIED format. You followed JUSTIFIED (or JUST) with something other than RIGHT, or you coded it with a clause other than SOURCE, or you coded for a data item that is numeric.
  • RWT-2045-00-E Improper BLANK WHEN ZERO clause
    Invalid BLANK WHEN ZERO format.
  • RWT-2046-00-E Improper CHANGE INDICATE clause
    Invalid CHANGE INDICATE format.
  • RWT-2047-00-E Improper GROUP INDICATE clause
    Invalid GROUP INDICATE format.
  • RWT-2048-00-E Improper COLUMN clause
    Invalid COLUMN format. You did not specify a positive integer.
  • RWT-2049-00-E Improper VALUE clause
    Invalid value label for a SOURCE format. You did not specify an integer, keyword, or quoted string.
  • RWT-2050-00-E Improper SUM clause
    The SUM clause does not specify a valid data name.
  • RWT-2051-00-E Improper SOURCE clause
    The SOURCE clause does not specify a valid data name.
  • RWT-2052-00-E Improper UPON clause
    Invalid UPON option format for the SUM clause.
  • RWT-2053-00-E Improper PICTURE text
    The PICture phrase has an invalid character string.
  • RWT-2054-00-E Improper DECLARATIVES statement
    Invalid USE BEFORE REPORTING sentence format.
  • RWT-2055-00-E Improper INITIATE statement
    You followed an INITIATE statement with a report name for which there was no Report Description entry.
  • RWT-2056-00-E Improper TERMINATE statement
    You followed a TERMINATE statement with a report name for which there was no Report Description entry.
  • RWT-2057-00-E Duplicate reports found in report structure
    You specified a report name more than once for a Report Description entry.
  • RWT-2058-00-E Invalid subscript or index entry
    AMB encountered a subscript or index that surpassed the allowable number of subscript or index levels.
  • RWT-2059-01-E RWT-2059-02-E RWT-2059-03-E RWT-2059-04-E PICTURE missing for
    The PICture clause is missing for the data name specified.
  • RWT-2060-00-E COLUMN clause missing
    A COLUMN clause is not present where one is necessary.
  • RWT-2061-00-E Invalid USE BEFORE REPORTING clause
    A USE BEFORE REPORTING sentence specifies a data name that is neither a Heading nor Footing Report group.
  • RWT-2062-00-E Number of detail groups max exceeded
    You exceeded the maximum number of detail groups (99).
  • RWT-2063-00-E TYPE clause does not match CONTROL clause
    The type coded in the TYPE clause is not consistent with that in the CONTROL clause.
  • RWT-2064-00-E SOURCE clause missing
    A SOURCE clause is not present where one is necessary.
  • RWT-2065-00-E SUM clause missing
    A SUM clause is not present where one is necessary.
  • RWT-2066-00-E Invalid continuation
    AMB encountered a hyphen (-) in column 7, or AMB encountered an ellipsis (...) as the opening word or symbol of a statement.
  • RWT-2067-00-E Invalid character in col 7
    Column 7 contains a character other than an asterisk (*) or a hyphen (-).
  • RWT-2068-00-E Name may not end with a hyphen
    AMB encountered a hyphen (-) at the end of the data name.
  • RWT-2069-00-E Name longer than 30 characters
    The data name contains more than 30 characters.
  • RWT-2070-00-E Integer longer than 30 characters
    The integer contains more than 30 characters.
  • RWT-2071-00-E Number longer than 30 characters
    The number contains more than 30 characters.
  • RWT-2072-00-E PICTURE longer than 30 char
    The PICture clause contains more than 30 characters.
  • RWT-2073-00-E Edited PICTURE illegal as SOURCE
    AMB encountered a PICture clause for a SOURCE statement that has edit characters in it.
  • RWT-2074-00-E Illegal PICTURE clause
    AMB encountered PICture statement that contained a character other than X Z , . 9 A B 0 * + - $ E ( ).
  • RWT-2075-00-E Level number must be followed by space
    AMB encountered a level number (01, 05, etc.) that you did not follow with a space.
  • RWT-2076-00-E No line number provided for report footing
    You did not specify a line number on the FOOTING clause.
  • RWT-2077-00-E Group line table overflow
    You exceeded the maximum storage capability of group line items (1625) resulting in table overflow.
  • RWT-2078-00-E SOURCE item table overflow
    You exceeded the maximum storage capability of 30 SOURCE items resulting in table overflow.
  • RWT-2079-00-E CONTROL FOOTING space limitation
    There is not enough room to print the Control Footing where specified.
  • RWT-2080-00-E Invalid computed footing line
    The FOOTING line is less than or equal to zero.
  • RWT-2081-00-E PAGE LIMIT parameters not in ascending order
    The integers given on the HEADING, DETAIL, or FOOTING clause exceed the PAGE LIMIT clause. The integers must be in ascending order and not greater than the PAGE LIMIT.
  • RWT-2083-00-E Invalid PAGE LIMIT 58 assumed
    The PAGE LIMIT given was not an integer. AMB moved the number, 58, to the page limit temporarily for further processing.
  • RWT-2084-00-E Invalid PAGE LIMIT clause
    The PAGE LIMIT clause contains a character other than an integer as the page limit.
  • RWT-2088-00-E RWT-2089-00-E invalid HEADING clause value calculated
    The value following the HEADING clause is not an integer so AMB calculated the value.
  • RWT-2091-00-E Unrecognized group type
    AMB encountered a group TYPE other than REPORT HEADING or REPORT FOOTING. Possibly you followed REPORT with something other than HEADING or FOOTING.
  • RWT-2092-00-E CONTROL clause not followed by data name
    CONTROL IS/ARE is not followed by a data name.
  • RWT-2093-00-E FIRST DETAIL not numeric
    Something other than a valid line number follows the FIRST DETAIL clause.
  • RWT-2094-00-E FIRST is a COBOL reserved word
    FIRST is reserved for the FIRST DETAIL clause.
  • RWT-2095-00-E LAST DETAIL not numeric
    Something other than a valid line number follows the LAST DETAIL clause.
  • RWT-2096-00-E LAST is a COBOL reserved word
    LAST is reserved for the LAST DETAIL clause.
  • RWT-2098-00-E -PAGE- invalid for group
    The PAGE keyword is invalid for PAGE HEADING because it always begins a new page. It is invalid for PAGE FOOTING because it cannot begin a new page, and it is invalid for DETAIL because AMB only allows one type of detail.
  • RWT-2099-00-E SUPPRESS invalid on grp other than PH-CH-CF
    AMB does not allow SUPPRESS on groups except for PH (Page Heading), CH (Control Heading), or CF (Control Footing).
  • RWT-2100-00-E Unrecognized phrase after GROUP-CHANGE
    A word other than INDICATE follows a GROUP or CHANGE clause.
  • RWT-2101-00-E PICTURE not matched by SOURCE
    The PICture clause given for a particular SOURCE item does not match the item.
  • RWT-2102-00-E Invalid PICTURE
    Invalid PICture clause format.
  • RWT-2103-00-E Unknown integer
    AMB encountered an integer without a correct parameter prefixing it.
  • RWT-2104-00-E Quote assumed
    If AMB encounters column 72 after a string (or alphanumeric literal) opens, AMB places a quote in column 72.
  • RWT-2105-00-E Data name valid on TYPE IS CH or CF only
    You specified a control identifier (data name) on a TYPE clause for a group other than Control Heading (CH) or Control Footing (CF).
  • RWT-2106-00-E MOCKUP stm expected
    You did not follow a TYPE clause for a report mock-up by a MOCKUP statement.
  • RWT-2110-00-E WRITE ROUTINE clause invalid for NORWT
    The optional report description clause, WRITE ROUTINE, is only available when the RWT parameter is ON.
  • RWT-2111-00-E Improper WRITE ROUTINE syntax
    Invalid WRITE ROUTINE clause format.
  • RWT-2112-00-E Only 1 CH-CF allowed per CONTROL item
    AMB found more than one control heading or control footing for this control item.
  • RWT-3002-01-W 02-W 01 LEVEL DELETED - NEW ONE GENERATED
    AMB replaces the 01 level you coded with a AMB generated 01 level.
  • RWT-3003-00-W Next group suppressed must be in USE stm
    When you specify MOVE 1 TO PRINT-SWITCH, the Heading or Footing Report group you want to suppress should be in a USE BEFORE REPORTING sentence.
  • RWT-3005-00-W Line area occupied
    You computed a heading to go in an area that is already occupied by something else.
  • RWT-3008-00-W RH-HEADING clauses do not agree
    The report heading and the given REPORT HEADING clause are not the same.
  • RWT-3009-00-W PH-HEADING clauses do not agree
    The page heading and the given PAGE HEADING clause are not the same.
  • RWT-3010-00-W PH line-computed PH line do not agree
    The line number given in the PAGE HEADING clause and the computed line number for the Page Heading line are not the same.
  • RWT-3011-00-W FIRST DETAIL-computed first DE do not agree
    The line number given in the FIRST DETAIL clause and the computed line number for the first detail line are not the same.
  • RWT-3012-00-W RF line/computed RF line do not agree.
    The line number given in the REPORT FOOTING clause and the computed line number for the report footing line are not the same.
  • RWT-3013-00-W Line-computed PF line do not agree
    The line number given in the PAGE FOOTING clause and the computed line number for the page footing line are not the same.
  • RWT-3014-00-W FOOTING/computed footing do not agree.
    The line number given in the FOOTING clause and the computed line number for the footing line are not the same.
  • RWT-3015-00-W LAST DETAIL-computed last DE do not agree
    The line number given in the LAST DETAIL clause and the computed line number for the Last Detail line are not the same.
  • RWT-3016-00-W Invalid PAGE NUM clause top right assumed
    The PAGE NUMBER clause is incorrect. AMB default places page numbers at the top right of page.
  • RWT-3017-00-W Illegal subscript continuation
    You must code all subscripts on one line. AMB attempted a continuation.
  • RWT-3019-00-W Period should end sentence preceding FD-SD
    You left a period off of the sentence preceding an FD or SD statement.
  • RWT-3022-00-W NEXT GROUP improper
    You used a NEXT GROUP clause on a page heading, page footing, or report footing. This is not proper syntax for these groups.
  • RWT-3023-00-W No RED for
    In the REPORT clause of an FD, you specified a report-name that you did not define via a RED statement.
  • RWT-3024-00-W No FD for reportname
    You cannot match a report defined via a RED section header with any report record description. The report neither uses the WRITE ROUTINE clause nor gets associated with an FD by a REPORT IS clause.
  • RWT-9001-00-F Structure block storage space full
  • RWT-9002-00-E Group block storage space full
  • RWT-9003-00-F Symbol table full
    The internal table used by AMB is full. AMB halts execution.
  • RWT-9004-00-F Internal symbol data segments full
  • RWT-9005-00-F Atom buffer full
    The internal buffer used by AMB is full. AMB halts execution.
  • RWT-9006-00-F Internal hash table full
  • RWT-9007-00-E Expecting record AMB thru WS reached EOF
    Internal processing of the source code expected to find Working-Storage information and could not find it.
  • RWT-9008-00-E EXPECTING RECORD AMB LNKCMM REACHED EOF
    Internal processing of the source code expected to find Linkage/Communication section and did not find it.
  • RWT-9009-00-F Identifier symbol storage failure
  • RWT-9011-00-F Internal structure block overflow
  • RWT-9012-00-F Maximum of 100 reports exceeded
    You can have a maximum limit of 100 reports per program when you use AMB Report Writer.
Parent topic: AppMaster Builder Error Messages


RWT-1002-00-F SOURCE-SUM-VALUE buffer overflow

You exceeded the limit (300) of SOURCE, SUM, and VALUE entries in one source program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

To reduce the number of SOURCE, SUM, and VALUE entries in the program, compile some report descriptions separately.

Parent topic: RWT- Report Writer messages


RWT-1003-00-F Mock-up buffer overflow

You exceeded the limit of 200 lines in the left half of the mock-up.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Instead of incorporating blank lines in the mock-up, you can use the LINE statement to position the report.

Parent topic: RWT- Report Writer messages


RWT-1004-00-F Report limit reached for FD

The number of reports specified within a Report clause exceeds 15.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add additional FDs if necessary. Contact your AMB Administrator if you need more assistance.

Parent topic: RWT- Report Writer messages


RWT-1005-00-F Invalid keyword or period missing in RED hdr

AMB detected a clause beginning with a keyword other than CONTROL, CODE, PAGE, FIRST, LAST, HEADING, FOOTING, or WRITE in the Report Description statement or the required period at the end of the Report description statement is missing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Verify spelling of keywords and/or insert the required period.

Parent topic: RWT- Report Writer messages


RWT-1006-00-F CONTROL ITEM MAXIMUM EXCEEDED

You exceeded the maximum number of control items (28) allowed for the report.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Decrease the number of controls.

Parent topic: RWT- Report Writer messages


RWT-1007-01-F RWT-1007-02-F Report data name missing

You did not follow a TERMINATE or INITIATE statement with a data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1008-00-F Invalid INITIATE statement

You followed an INITIATE statement with an invalid report name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1009-00-F GENERATE data name missing

You did not follow a GENERATE statement with a data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1010-00-F Improper GENERATE statement

You followed a GENERATE statement with an invalid report name or data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If the report name is correct, look for an illegal or missing 01 TYPE clause or MOCK-UP statement.

Parent topic: RWT- Report Writer messages


RWT-1011-00-F Invalid TERMINATE statement

You followed a TERMINATE statement with an invalid report name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1012-00-F Declaratives statement missing

AMB did not find a Declaratives statement before encountering an END statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1013-00-F END statement missing for declaratives

AMB did not find an END Declaratives statement for the Declaratives section.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1016-00-F PIC not given for detail item

AMB encountered a detail item without an associated PICture clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1017-00-F Detail symbol storage failure call AMB rep

A problem occurred storing the detail items. Execution halts.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-1019-00-F PIC not given for identifier item

AMB encountered an identifier item without an associated PICture clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1021-00-F Report desc keyword missing or in wrong col

The RED keyword is missing or coded in the wrong column.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1024-00-F Control variable required with CH-CF clause

A valid data name must follow the CH (Control Heading) or CF (Control Footing) clauses.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1027-00-F Only numeric literals permitted for detail

You can use numeric literals only with detail.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1029-00-F Illegal literal

The number of characters where a literal should be is equal to zero. Therefore, it is invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1030-00-F -PAGE- MUST BE FIRST ENTRY FOR GROUP

Use PAGE once for a group; it must precede all other parameters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1032-00-F Num enclosed by - permitted in detail only

/INTEGER/ indicates a relative number of lines to advance before presenting the first line of the group if used with detail.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code /INTEGER/ in a detail group only. See also Iterative Expression.

Parent topic: RWT- Report Writer messages


RWT-1034-00-F G-C INDICATE permitted for detail only

You can only use the GROUP INDICATE and CHANGE INDICATE clauses with detail lines.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1035-00-F No identifier given for G-C INDICATE

GROUP and CHANGE INDICATE both require an identifier.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1036-00-F PIC permitted for detail only

AMB allows PICture clauses for detail items only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1037-00-F No identifier given for PIC

Identifier is missing before the specified PICture clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1038-00-F No identifier given for subscript-index

AMB encountered a subscript or index not prefixed with an identifier. AMB halts execution.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1039-00-F Iterative subscript permitted in detail only

Use iterative subscripts for detail lines only.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1040-00-F Only 3 levels of sub-index permitted

AMB allows only 3 levels of subscripts or indices are permitted.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1042-00-F Illegal subscript-index

The subscript or index as coded is incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1045-00-F Incorrect sequence of parameters in detail

The parameters used in the detail group were syntactically incorrect.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1046-00-F At least 1 ID must be given in detail

There must be at least one identifier in each detail line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1047-00-F Numeric 4 digits

The integer specified for a PAGE LIMIT, FIRST DETAIL, LAST DETAIL, HEADING, or FOOTING or clause is greater than 4 digits.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1048-00-F Expecting numeric found nonnumeric

AMB expected an integer in the PAGE LIMIT, HEADING, DETAIL or FOOTING clauses and did not find it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1049-00-F Numeric must be greater than 0

AMB encountered a negative number where only a positive number is allowed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1050-00-F PH-ATOM storage problem CALL AMB REP

AMB encountered a problem in PAGE HEADING storage. Execution stops.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-1051-00-F Detail group must be given

A Detail group must follow a DETAIL clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1052-00-F Duplicate report group

When processing multiple reports, AMB found a duplicate Report group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1053-00-F CH-CF control var not found in CTRL clause

You must use a control variable with a control heading and control footing in a CONTROL clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1054-00-F MOCK-UP must immediately follow RED entry

AMB found something other than a mock-up delimiter following the Report Description statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the code. Possibly you coded two periods coded in the Report Description statement. AMB allows only one.

Parent topic: RWT- Report Writer messages


RWT-1055-00-F Mock-up not found

AMB did not find a mock-up for a Report Description entry.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1057-00-F Data name missing on TYPE IS CH-CF

You did not specify a control identifier (data name) on a TYPE clause for a Control Heading (CH) or Control Footing (CF) group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-1058-00-F Anim-debug overflow

You exceeded the buffer limit (25) for consecutive debugger lines. A block of comments with more than 25 lines is probably the cause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Reduce the number of consecutive comment lines, or set the Debug option to None in the Project Explorer.

Parent topic: RWT- Report Writer messages


RWT-2001-00-E RWT-2001-02-E Mock-up and MOCKUP statement incompatible

AMB found a mock-up statement when using group mock-ups. Use MOCKUP statements only with report mock-ups.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2002-00-E MOCKUP statement must be first

AMB encountered a mock-up statement out of sequence in a Group Description entry.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code a MOCKUP statement after the 01 TYPE statement.

Parent topic: RWT- Report Writer messages


RWT-2003-00-E LINE statement must be after MOCKUP

AMB encountered a LINE statement out of sequence in a group description entry.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code a LINE statement after the MOCKUP statement; or, if there is no MOCKUP statement (because you used a group mock-up), after the 01 TYPE statement.

Parent topic: RWT- Report Writer messages


RWT-2004-00-E Invalid line number

Characters following a LINE NUMBER statement are not numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2005-00-E Invalid SOURCE SUM or VALUE statement

You did not code an item description entry (SOURCE, SUM, or VALUE statement) correctly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2008-00-E Unmatched SUM-SOURCE-VALUE clause

You coded a SUM, SOURCE, or VALUE clause for which there is no matching picture in the mock-up. Possibly, you did not delete a SOURCE clause that you no longer reference in the mock-up. Or possibly, MOCKUP line statements do not accurately match the lines specified for each group in the mock-up.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2009-00-E PIC missing for REFERENCE

A REFERENCE statement contains no PICture clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2010-00-E Too many lines in right half of mock-up

The right half of the mock-up has more lines than the left.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the code so that right and left halves of the mock-up match. A possible cause is a delimiter (a non-blank character, non-alphabetic and non-numeric) in Column 7, continuing for 4 or more consecutive bytes.

Parent topic: RWT- Report Writer messages


RWT-2011-00-E Mock-up continuation missing

AMB did not find the right half of the report mock-up following the left half.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2012-00-E Right half mock-up overflow

You exceeded the limit of 200 lines in the right half of the mock-up.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2013-00-E Improper beginning mock-up reference

A MOCKUP statement specifies a line number outside the range of the report mock-up as its beginning line, or AMB found a MOCKUP statement for a group mock-up.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2014-00-E Improper ending mock-up reference

A MOCKUP statement using the INTEGER-1 through INTEGER-2 format, specifies a line number outside the range of the report mock-up as its ending line (INTEGER-2).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Make the line number greater than 0 or check the report mock-up for actual line number.

Parent topic: RWT- Report Writer messages


RWT-2015-00-E Obsolete syntax temporarily excepted

You specified a data name following a left parenthesis in a SOURCE clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the parenthesis.

Parent topic: RWT- Report Writer messages


RWT-2016-00-E Remove left paren (obsolete syntax)

You specified a data name following a left parenthesis in a SOURCE clause without a closing right parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the left parenthesis or add right parenthesis.

Parent topic: RWT- Report Writer messages


RWT-2017-00-E PICTURE missing

You did not follow the keyword designating a PICture or IS in a SUM/SOURCE/VALUE statement with a COBOL picture character.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the PICture clause or supply a correct picture following the keyword. Note that AMB does not require a PICture clause, but having one helps catch incompatibilities between the mock-up and the SUM/SOURCE/VALUE statements early in the debugging process (at compile time, rather than execution time).

Parent topic: RWT- Report Writer messages


RWT-2018-00-E Improper PICTURE no closing parens

In a PICture clause of a SUM/SOURCE/VALUE or REFERENCE clause, AMB encountered an opening parenthesis following a valid PICture character with no closing parenthesis.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2019-00-E Invalid character for PICTURE clause

In a PICture clause of a SUM/SOURCE/VALUE or REFERENCE clause, AMB encountered a character other than X 9 Z $ , 0 . + - C R D * V E ( ).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2020-00-E Missing quoted OVERPRINT text

AMB encountered an OVERPRINT statement without a character string enclosed in quotes.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2021-00-E Improper file name

You followed a File Description entry (FD) by blanks or an invalid file name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2022-00-E RWT-2023-00-E Improper BLOCK CONTAINS clause

Invalid BLOCK CONTAINS format. You coded the clause with something other than characters or records or you did not specify an unsigned integer. If you coded the optional INTEGER-1 to INTEGER-2 format, INTEGER-2 is not an unsigned integer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2024-00-E RWT-2025-01-E RWT-2025-02-E RWT-2026-00-E Improper RECORD CONTAINS clause

Invalid RECORD CONTAINS format. You coded the clause with something other than characters or records or you did not specify an unsigned integer. If you coded the optional INTEGER-1 to INTEGER-2 format, INTEGER-2 is not an unsigned integer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2027-01-E RWT-2027-02-E Improper LABEL RECORDS clause

Invalid LABEL RECORDS format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2028-00-E Improper FILE-ID clause

Invalid FILE ID format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2029-00-E Improper FILE REPORTS clause

Invalid REPORT clause format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2030-00-E Improper DATA RECORDS clause

Invalid DATA RECORDS format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2031-00-E IMPROPER RD NAME

You followed a Report Description entry (RED) with blanks or an invalid name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2032-00-E Improper RED statement

You followed a CODE clause with an invalid mnemonic name or with blanks.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2033-00-E RWT-2033-02-E Improper CONTROL clause

You coded a CONTROL clause in an invalid format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2034-00-E Improper PAGE LIMIT clause

Invalid PAGE LIMIT format, or the clause specifies 0 as the last line where you can print anything.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2035-00-E Improper HEADING clause

Invalid HEADING format, or the clause specifies 0 as the first line number of the heading print group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2036-00-E Improper FIRST DETAIL clause

Invalid FIRST DETAIL format, or the clause specifies 0 as the first line number of the body group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2037-00-E RWT-2037-02-E Improper LAST DETAIL clause

Invalid LAST DETAIL format, or the clause specifies 0 as the last line number of the last nonfooting body group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2038-00-E Improper FOOTING clause

Invalid FOOTING format. The clause specifies 0 as the last line number of the last Control Footing Report group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2039-00-E Improper TYPE clause

A TYPE clause specifies an invalid option.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2040-00 Improper LINE clause

Invalid LINE format, or INTEGER-1 is not a positive integer for the LINE NUMBER IS INTEGER-1 format, or INTEGER-2 is not a positive integer for the LINE NUMBER plus INTEGER-2 format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2041-00-E Improper NEXT GROUP clause

Invalid NEXT GROUP format, or INTEGER-1 is not a positive integer for the NEXT GROUP IS INTEGER-1 format, or INTEGER-2 is not a positive integer for the NEXT GROUP IS PLUS INTEGER-2 format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2042-00-E Improper USAGE clause Invalid USAGE format

You specified a USAGE other than DISPLAY.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2043-00-E Improper RESET clause

Invalid RESET option format with the SUM clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2044-00-E Improper JUSTIFIED clause

Invalid JUSTIFIED format. You followed JUSTIFIED (or JUST) with something other than RIGHT, or you coded it with a clause other than SOURCE, or you coded for a data item that is numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2045-00-E Improper BLANK WHEN ZERO clause

Invalid BLANK WHEN ZERO format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2046-00-E Improper CHANGE INDICATE clause

Invalid CHANGE INDICATE format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2047-00-E Improper GROUP INDICATE clause

Invalid GROUP INDICATE format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2048-00-E Improper COLUMN clause

Invalid COLUMN format. You did not specify a positive integer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2049-00-E Improper VALUE clause

Invalid value label for a SOURCE format. You did not specify an integer, keyword, or quoted string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2050-00-E Improper SUM clause

The SUM clause does not specify a valid data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2051-00-E Improper SOURCE clause

The SOURCE clause does not specify a valid data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2052-00-E Improper UPON clause

Invalid UPON option format for the SUM clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2053-00-E Improper PICTURE text

The PICture phrase has an invalid character string.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2054-00-E Improper DECLARATIVES statement

Invalid USE BEFORE REPORTING sentence format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2055-00-E Improper INITIATE statement

You followed an INITIATE statement with a report name for which there was no Report Description entry.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2056-00-E Improper TERMINATE statement

You followed a TERMINATE statement with a report name for which there was no Report Description entry.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2057-00-E Duplicate reports found in report structure

You specified a report name more than once for a Report Description entry.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2058-00-E Invalid subscript or index entry

AMB encountered a subscript or index that surpassed the allowable number of subscript or index levels.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2059-01-E RWT-2059-02-E RWT-2059-03-E RWT-2059-04-E PICTURE missing for

The PICture clause is missing for the data name specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2060-00-E COLUMN clause missing

A COLUMN clause is not present where one is necessary.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2061-00-E Invalid USE BEFORE REPORTING clause

A USE BEFORE REPORTING sentence specifies a data name that is neither a Heading nor Footing Report group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2062-00-E Number of detail groups max exceeded

You exceeded the maximum number of detail groups (99).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2063-00-E TYPE clause does not match CONTROL clause

The type coded in the TYPE clause is not consistent with that in the CONTROL clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Fix the incorrect type. If the TYPE clause appears correct, the number of CONTROL clauses may have exceeded the maximum (28) for the report. Reduce the number of CONTROL clauses.

Parent topic: RWT- Report Writer messages


RWT-2064-00-E SOURCE clause missing

A SOURCE clause is not present where one is necessary.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2065-00-E SUM clause missing

A SUM clause is not present where one is necessary.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2066-00-E Invalid continuation

AMB encountered a hyphen (-) in column 7, or AMB encountered an ellipsis (...) as the opening word or symbol of a statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Replace the hyphen in column 7 with a properly placed continuation ellipsis. If an ellipsis is present, check for correct alignment with preceding code. There should not be a blank line between original line of code and continuation line containing the ellipsis.

Parent topic: RWT- Report Writer messages


RWT-2067-00-E Invalid character in col 7

Column 7 contains a character other than an asterisk (*) or a hyphen (-).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the character from column 7. You can reinsert it in column 7 at the COBOL level if you require it for COBOL compilation.

Parent topic: RWT- Report Writer messages


RWT-2068-00-E Name may not end with a hyphen

AMB encountered a hyphen (-) at the end of the data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2069-00-E Name longer than 30 characters

The data name contains more than 30 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2070-00-E Integer longer than 30 characters

The integer contains more than 30 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2071-00-E Number longer than 30 characters

The number contains more than 30 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2072-00-E PICTURE longer than 30 char

The PICture clause contains more than 30 characters.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2073-00-E Edited PICTURE illegal as SOURCE

AMB encountered a PICture clause for a SOURCE statement that has edit characters in it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2074-00-E Illegal PICTURE clause

AMB encountered PICture statement that contained a character other than X Z , . 9 A B 0 * + - $ E ( ).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2075-00-E Level number must be followed by space

AMB encountered a level number (01, 05, etc.) that you did not follow with a space.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2076-00-E No line number provided for report footing

You did not specify a line number on the FOOTING clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2077-00-E Group line table overflow

You exceeded the maximum storage capability of group line items (1625) resulting in table overflow.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2078-00-E SOURCE item table overflow

You exceeded the maximum storage capability of 30 SOURCE items resulting in table overflow.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2079-00-E CONTROL FOOTING space limitation

There is not enough room to print the Control Footing where specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2080-00-E Invalid computed footing line

The FOOTING line is less than or equal to zero.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax for HEADING, DETAIL, and PAGE clauses.

Parent topic: RWT- Report Writer messages


RWT-2081-00-E PAGE LIMIT parameters not in ascending order

The integers given on the HEADING, DETAIL, or FOOTING clause exceed the PAGE LIMIT clause. The integers must be in ascending order and not greater than the PAGE LIMIT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2083-00-E Invalid PAGE LIMIT 58 assumed

The PAGE LIMIT given was not an integer. AMB moved the number, 58, to the page limit temporarily for further processing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2084-00-E Invalid PAGE LIMIT clause

The PAGE LIMIT clause contains a character other than an integer as the page limit.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2088-00-E RWT-2089-00-E invalid HEADING clause value calculated

The value following the HEADING clause is not an integer so AMB calculated the value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2091-00-E Unrecognized group type

AMB encountered a group TYPE other than REPORT HEADING or REPORT FOOTING. Possibly you followed REPORT with something other than HEADING or FOOTING.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2092-00-E CONTROL clause not followed by data name

CONTROL IS/ARE is not followed by a data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2093-00-E FIRST DETAIL not numeric

Something other than a valid line number follows the FIRST DETAIL clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2094-00-E FIRST is a COBOL reserved word

FIRST is reserved for the FIRST DETAIL clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2095-00-E LAST DETAIL not numeric

Something other than a valid line number follows the LAST DETAIL clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2096-00-E LAST is a COBOL reserved word

LAST is reserved for the LAST DETAIL clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2098-00-E -PAGE- invalid for group

The PAGE keyword is invalid for PAGE HEADING because it always begins a new page. It is invalid for PAGE FOOTING because it cannot begin a new page, and it is invalid for DETAIL because AMB only allows one type of detail.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2099-00-E SUPPRESS invalid on grp other than PH-CH-CF

AMB does not allow SUPPRESS on groups except for PH (Page Heading), CH (Control Heading), or CF (Control Footing).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2100-00-E Unrecognized phrase after GROUP-CHANGE

A word other than INDICATE follows a GROUP or CHANGE clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2101-00-E PICTURE not matched by SOURCE

The PICture clause given for a particular SOURCE item does not match the item.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2102-00-E Invalid PICTURE

Invalid PICture clause format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2103-00-E Unknown integer

AMB encountered an integer without a correct parameter prefixing it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2104-00-E Quote assumed

If AMB encounters column 72 after a string (or alphanumeric literal) opens, AMB places a quote in column 72.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2105-00-E Data name valid on TYPE IS CH or CF only

You specified a control identifier (data name) on a TYPE clause for a group other than Control Heading (CH) or Control Footing (CF).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2106-00-E MOCKUP stm expected

You did not follow a TYPE clause for a report mock-up by a MOCKUP statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2110-00-E WRITE ROUTINE clause invalid for NORWT

The optional report description clause, WRITE ROUTINE, is only available when the RWT parameter is ON.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2111-00-E Improper WRITE ROUTINE syntax

Invalid WRITE ROUTINE clause format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-2112-00-E Only 1 CH-CF allowed per CONTROL item

AMB found more than one control heading or control footing for this control item.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3002-01-W 02-W 01 LEVEL DELETED - NEW ONE GENERATED

AMB replaces the 01 level you coded with a AMB generated 01 level.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: RWT- Report Writer messages


RWT-3003-00-W Next group suppressed must be in USE stm

When you specify MOVE 1 TO PRINT-SWITCH, the Heading or Footing Report group you want to suppress should be in a USE BEFORE REPORTING sentence.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Ensure you use a USE BEFORE REPORTING sentence for the group you want to suppress.

Parent topic: RWT- Report Writer messages


RWT-3005-00-W Line area occupied

You computed a heading to go in an area that is already occupied by something else.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3008-00-W RH-HEADING clauses do not agree

The report heading and the given REPORT HEADING clause are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3009-00-W PH-HEADING clauses do not agree

The page heading and the given PAGE HEADING clause are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3010-00-W PH line-computed PH line do not agree

The line number given in the PAGE HEADING clause and the computed line number for the Page Heading line are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3011-00-W FIRST DETAIL-computed first DE do not agree

The line number given in the FIRST DETAIL clause and the computed line number for the first detail line are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3012-00-W RF line/computed RF line do not agree.

The line number given in the REPORT FOOTING clause and the computed line number for the report footing line are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3013-00-W Line-computed PF line do not agree

The line number given in the PAGE FOOTING clause and the computed line number for the page footing line are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3014-00-W FOOTING/computed footing do not agree.

The line number given in the FOOTING clause and the computed line number for the footing line are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3015-00-W LAST DETAIL-computed last DE do not agree

The line number given in the LAST DETAIL clause and the computed line number for the Last Detail line are not the same.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3016-00-W Invalid PAGE NUM clause top right assumed

The PAGE NUMBER clause is incorrect. AMB default places page numbers at the top right of page.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3017-00-W Illegal subscript continuation

You must code all subscripts on one line. AMB attempted a continuation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3019-00-W Period should end sentence preceding FD-SD

You left a period off of the sentence preceding an FD or SD statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3022-00-W NEXT GROUP improper

You used a NEXT GROUP clause on a page heading, page footing, or report footing. This is not proper syntax for these groups.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary in most cases, but unexpected results may occur.

Parent topic: RWT- Report Writer messages


RWT-3023-00-W No RED for

In the REPORT clause of an FD, you specified a report-name that you did not define via a RED statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: RWT- Report Writer messages


RWT-3024-00-W No FD for reportname

You cannot match a report defined via a RED section header with any report record description. The report neither uses the WRITE ROUTINE clause nor gets associated with an FD by a REPORT IS clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Associate the report to an FD with the REPORT IS clause, or specify developer control of the report via the WRITE ROUTINE clause in the RED section header.

Parent topic: RWT- Report Writer messages


RWT-9001-00-F Structure block storage space full

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9002-00-E Group block storage space full

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9003-00-F Symbol table full

The internal table used by AMB is full. AMB halts execution.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

It may be necessary to process the program in two parts and recombine the output for the COBOL compile. Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9004-00-F Internal symbol data segments full

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9005-00-F Atom buffer full

The internal buffer used by AMB is full. AMB halts execution.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

It may be necessary to break one long paragraph into two paragraphs.

Parent topic: RWT- Report Writer messages


RWT-9006-00-F Internal hash table full

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9007-00-E Expecting record AMB thru WS reached EOF

Internal processing of the source code expected to find Working-Storage information and could not find it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Rerun. If you receive the same results, contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9008-00-E EXPECTING RECORD AMB LNKCMM REACHED EOF

Internal processing of the source code expected to find Linkage/Communication section and did not find it.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Rerun. If you receive the same results, contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9009-00-F Identifier symbol storage failure

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9011-00-F Internal structure block overflow

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: RWT- Report Writer messages


RWT-9012-00-F Maximum of 100 reports exceeded

You can have a maximum limit of 100 reports per program when you use AMB Report Writer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator if you require more than 100 reports in the program.

Parent topic: RWT- Report Writer messages


SCB- S-COBOL Messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • SCB-1001-00-F Unprivileged S-COBOL use
    You cannot process S-COBOL in this program. Program has attempted to enter the module for processing S-COBOL.
  • SCB-1002-00-F Improper loc for Procedure Division stm
    A Procedure Division statement was encountered after Procedure Division processing has begun. Execution stops.
  • SCB-1003-00-F Improper loc for Declaratives stm
    A Declaratives Header was encountered in an incorrect location within the Procedure Division. Execution stops.
  • SCB-1004-00-F Improper loc for END DECLARATIVES stm
    The word END was encountered as the first COBOL word in a statement in the Procedure Division and no corresponding Declaratives Header was previously encountered. This END is presumed to be a part of End Declaratives statement. Execution stops.
  • SCB-1005-00-F Paragraph argument table overflow limit 400 arguments
  • SCB-1006-00-F Stm overflow
    Number of statements in the paragraph exceeds the internal table of 600 (after processing, each resulting S-COBOL line is counted as a statement).
  • SCB-1007-00-F RWT errors prevent Declaratives translation
    RWT errors have occurred in a program that uses Declaratives, preventing the translation of Declaratives into a generated paragraph.
  • SCB-2001-00-E Missing file name
    An internal file name is missing from the SELECT statement.
  • SCB-2002-00-E Continuation improper
    Continuation is not allowed in Section or Division header. A continuation ellipses was coded in a Section or Division header.
  • SCB-2003-00-E Procedure name not unique
    A section header was encountered that does not provide a unique procedure name.
  • SCB-2004-00-E Paragraph name is a reserved word
  • SCB-2005-00-E Para not unique
    The paragraph name encountered was previously used in the program.
  • SCB-2006-00-E Error in paragraph name
    A character other than a left parenthesis or a period was encountered following a COBOL word that begins in AREA-A of the Procedure Division.
  • SCB-2007-00-E Improper paragraph argument
    The dummy arguments following a paragraph name are not proper data items.
  • SCB-2008-00-E Improper para-arg subscript
    The subscript of a paragraph argument is neither a data item nor a number.
  • SCB-2009-00-E Increment of subscript or index not numeric
    The increment (following + or -) of a subscript or an index is not numeric.
  • SCB-2010-00-E No name after INDEXED-BY clause
    An INDEXED-BY clause appears to be followed by a keyword.
  • SCB-2011-00-E Missing index name
    Missing index name for index used in a SET statement, or missing an INDEXED-BY name.
  • SCB-2012-00-E Para-name must follow ENTER in area-A
    ENTER COBOL/ENTER SCOBOL in area-A was followed by a paragraph of code that did not start with a paragraph name. When the ENTER COBOL statement starts in AREA-A, the current S-COBOL paragraph is closed to further processing/code generation.
  • SCB-2013-00-E USE statement missing
    A USE statement does not follow the Declaratives header and the subsequent section header.
  • SCB-2014-00-E Keyword cannot follow TRUE-FALSE verb
    The word following TRUE or FALSE is a keyword instead of a data name.
  • SCB-2015-00-E Only subscripted data names allowed
    A subscript or an index was encountered following a data name in a statement with TRUE or FALSE.
  • SCB-2016-00-E Portability violation
    GOBACK, ENTRY, or EXHIBIT was coded. These are extensions of ANSI COBOL and are not offered by all compilers.
  • SCB-2017-00-E Keyword found instead of verb
    A verb is expected in the structure, but another keyword was found.
  • SCB-2018-00-E ELSE must stand alone on line
    The only code that can follow an ELSE statement on the same line is a comment beginning with /* . A missing hyphen in an ELSE-IF construction also causes this message.
  • SCB-2019-00-E REPEAT statement syntax incorrect
  • SCB-2020-00-E USERNAME incompatible with CICS
  • SCB-2021-00-E USE verb outside of DECLARATIVES
    The USE verb was encountered outside the Declaratives portion of the Procedure Division.
  • SCB-2022-00-E ENTRY verb must follow paragraph name
    ENTRY was not positioned immediately after a paragraph or section header.
  • SCB-2023-00-E EXIT PROGRAM not allowed in DECLARATIVES
    EXIT PROGRAM logic should be in the main part of the Procedure Division.
  • SCB-2024-00-E PROGRAM must be added to EXIT statement
    An EXIT statement assumes EXIT PROGRAM is intended. EXIT alone is invalid in S-COBOL.
  • SCB-2025-00-E Improper indentation decreased
    All the indentation within one statement block must be the same. If one statement in a statement block begins one column or more earlier or later, this message results. For further processing, the line indentation decreases to the level of current indentation.
  • SCB-2026-00-E ELSE-ELSE-IF does not match cond above
    An ELSE or ELSE-IF statement was coded at a level of indentation that does not match a preceding condition statement.
  • SCB-2027-00-E No matching SEARCH or EVALUATE with WHEN stm
    SEARCH or EVALUATE
  • SCB-2028-00-E No indented stm block for last conditional
    The last conditional of an IF, ELSE-IF, ELSE statement is not followed by an indented statement block.
  • SCB-2029-00-E Missing WHILE-UNTIL after REPEAT stm
    REPEAT was coded without an accompanying WHILE or UNTIL statement at the same level of indentation
  • SCB-2030-00-E No WHEN clause with EVALUATE stm
  • SCB-2031-00-E Conditional stm not implemented
    The coded conditional statement is not defined or is spelled incorrectly.
  • SCB-2032-00-E Plus or minus expected
    A plus or minus sign is expected for index increment or decrement in format SOURCE IS (SRC-1 +/- SRC-2).
  • SCB-2033-00-E SCB-2033-02-E Syntax-error in REPEAT or EVALUATE stm
    REPEAT or EVALUATE
  • SCB-2034-00-E Too many varying clauses with REPEAT stm
    More than the maximum of 20 VARYING clauses are used with one REPEAT statement.
  • SCB-2035-00-E Index data item incompatible with VARYING
    An index data item cannot be a conditional variable in a VARYING clause.
  • SCB-2036-00-E BY clause required with REPEAT LINKING
  • SCB-2037-00-E Action statement is undefined
    The specified action statement is not in use because it is not defined or was misspelled.
  • SCB-2038-00-E Not a file name
    In the flagged line, or the line immediately preceding it, something other than a file name was referenced.
  • SCB-2039-00-E Record name must be qualified
    The record name is not unique and requires qualification.
  • SCB-2040-00-E Too many conditions for WHEN expression
  • SCB-2041-00-W Incomplete WHEN statement
  • SCB-2042-00-E Para undefined
    The paragraph being performed is not defined in the program.
  • SCB-2043-00-E Proc undefined
    The procedure named in the preceding PERFORM statement does not exist.
  • SCB-2044-00-E Procedure with ENTRY may not be performed
    A paragraph with an ENTRY statement is performed by another paragraph that is executed with the subprogram.
  • SCB-2045-00-E No arguments for para in PERFORM stm
    Arguments were passed in a PERFORM statement to a paragraph with no arguments.
  • SCB-2046-00-E Not enough arguments for PERFORM stm
    The number of PERFORM statement actual arguments does not agree with the dummy argument list following the corresponding paragraph name.
  • SCB-2047-00-E Too many arguments for PERFORM stm
    The number of PERFORM statement actual arguments does not agree with the dummy argument list following the corresponding paragraph name.
  • SCB-2048-00-E Arguments needed for PERFORM stm
    The number of PERFORM statement actual arguments does not agree with the dummy argument list following the corresponding paragraph name.
  • SCB-2049-00-E Improper statement termination
    During S-COBOL scanning of statement line, the statement appears terminate on a non-numeric, non-alpha character.
  • SCB-2050-00-E Data name qualification is incorrect
    The item being qualified is not a variable, or OF/IN is used incorrectly.
  • SCB-2051-00-E Syntax error in argument sequence
    During scanning for argument fields a syntax error was detected.
  • SCB-2052-00-E Argument return impossible
    A literal or arithmetic expression must correspond to an argument preceded by a plus sign (+). You cannot copy back into a literal or arithmetic expression.
  • SCB-2053-00-E Improper use of concatenation operator
    A concatenation operator, &&, tried to continue a line that does not end with a non-numeric literal. Use && only when concatenating a non-numeric literal onto a continued line.
  • SCB-2054-00-E WHILE-UNTIL invalid for REPEAT with THRU-TO
  • SCB-2055-00-E THRU or TO missing
    THRU or TO is missing in the DOWN TO/THRU clause in the REPEAT statement.
  • SCB-3001-00-W Unknown verb COBOL action word assumed
    The word flagged is not recognized by the AMB processor. It passes through, as is, to the generated COBOL output.
  • SCB-3002-00-W ON SIZE ERROR required assumed
    An indented statement or an ELSE-IF/ELSE statement followed an arithmetic statement. This is valid only with an ON SIZE ERROR clause.
  • SCB-3003-00-W No scope found for ON SIZE ERROR
    The ON SIZE ERROR clause has no indented code to execute when a size error is encountered.
  • SCB-3005-00-W Replace THRU with TO clause
    Use TO when executing the loop to, but not including, the stop point.
  • SCB-3006-00-W SCB-3007-00-W Negative found DOWN THRU assumed
    Negative found; DOWN TO assumed
  • SCB-3008-00-W SCB-3009-00-W Flag not set to FALSE in program
    Flag not set to TRUE in program. The flag name following a TRUE or FALSE statement is not used with a corresponding FALSE or TRUE statement elsewhere in the program.
  • SCB-3010-00-W AT END clause incompatible with file type
    An AT END clause was encountered on an Input/Output statement (READ, WRITE, or REWRITE) for a direct file or an indexed file that is accessed randomly.
  • SCB-3011-00-W Trailing quote missing - added
    The trailing quote on a literal was omitted.
  • SCB-3012-00-W Extraneous ELSE-ELSE-IF follows ELSE
    An ELSE or ELSE-IF is indented directly beneath an ELSE.
  • SCB-9002-00-F Parse stack overflow call AMB rep
    Internal stack overflow. Execution stops.
  • SCB-9003-01-F SCB-9003-02-F Product error (A) call AMB rep
    Internal check on S-COBOL processing. Make sure the ellipsis has three dots.
  • SCB-9004-00-F Compiler error (L) call AMB rep
    Internal check on S-COBOL processing of paragraph arguments.
  • SCB-9005-00-F Record look-ahead overflow call AMB rep
    S-COBOL internal look-ahead routine exceeds the internal limits set for records held in a buffer area.
  • SCB-9006-00-F Look-ahead problem call AMB rep
    Trouble with an internal S-COBOL routine that holds records in a buffer.
  • SCB-9007-00-F Symbol table full
    The maximum limit of 1801 entries is exceeded.
Parent topic: AppMaster Builder Error Messages


SCB-1001-00-F Unprivileged S-COBOL use

You cannot process S-COBOL in this program. Program has attempted to enter the module for processing S-COBOL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: SCB- S-COBOL Messages


SCB-1002-00-F Improper loc for Procedure Division stm

A Procedure Division statement was encountered after Procedure Division processing has begun. Execution stops.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-1003-00-F Improper loc for Declaratives stm

A Declaratives Header was encountered in an incorrect location within the Procedure Division. Execution stops.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

A Declaratives Header immediately follows the Procedure Division statement. Use only one.

Parent topic: SCB- S-COBOL Messages


SCB-1004-00-F Improper loc for END DECLARATIVES stm

The word END was encountered as the first COBOL word in a statement in the Procedure Division and no corresponding Declaratives Header was previously encountered. This END is presumed to be a part of End Declaratives statement. Execution stops.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-1005-00-F Paragraph argument table overflow limit 400 arguments

Parent topic: SCB- S-COBOL Messages


SCB-1006-00-F Stm overflow

Number of statements in the paragraph exceeds the internal table of 600 (after processing, each resulting S-COBOL line is counted as a statement).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Break the paragraph into multiple paragraphs with consecutive PERFORM statements for each.

Parent topic: SCB- S-COBOL Messages


SCB-1007-00-F RWT errors prevent Declaratives translation

RWT errors have occurred in a program that uses Declaratives, preventing the translation of Declaratives into a generated paragraph.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2001-00-E Missing file name

An internal file name is missing from the SELECT statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2002-00-E Continuation improper

Continuation is not allowed in Section or Division header. A continuation ellipses was coded in a Section or Division header.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2003-00-E Procedure name not unique

A section header was encountered that does not provide a unique procedure name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2004-00-E Paragraph name is a reserved word

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See also reserved word.

Parent topic: SCB- S-COBOL Messages


SCB-2005-00-E Para not unique

The paragraph name encountered was previously used in the program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2006-00-E Error in paragraph name

A character other than a left parenthesis or a period was encountered following a COBOL word that begins in AREA-A of the Procedure Division.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the line for extraneous characters and for an invalid paragraph name.

Parent topic: SCB- S-COBOL Messages


SCB-2007-00-E Improper paragraph argument

The dummy arguments following a paragraph name are not proper data items.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2008-00-E Improper para-arg subscript

The subscript of a paragraph argument is neither a data item nor a number.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2009-00-E Increment of subscript or index not numeric

The increment (following + or -) of a subscript or an index is not numeric.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2010-00-E No name after INDEXED-BY clause

An INDEXED-BY clause appears to be followed by a keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Enter a legitimate data name after the INDEXED-BY clause.

Parent topic: SCB- S-COBOL Messages


SCB-2011-00-E Missing index name

Missing index name for index used in a SET statement, or missing an INDEXED-BY name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2012-00-E Para-name must follow ENTER in area-A

ENTER COBOL/ENTER SCOBOL in area-A was followed by a paragraph of code that did not start with a paragraph name. When the ENTER COBOL statement starts in AREA-A, the current S-COBOL paragraph is closed to further processing/code generation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add a paragraph name before the paragraph of code.

Parent topic: SCB- S-COBOL Messages


SCB-2013-00-E USE statement missing

A USE statement does not follow the Declaratives header and the subsequent section header.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code a USE BEFORE REPORTING sentence following the section header in the Declaratives section.

Parent topic: SCB- S-COBOL Messages


SCB-2014-00-E Keyword cannot follow TRUE-FALSE verb

The word following TRUE or FALSE is a keyword instead of a data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2015-00-E Only subscripted data names allowed

A subscript or an index was encountered following a data name in a statement with TRUE or FALSE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use a MOVE statement to set a subscripted or indexed data name to TRUE or FALSE.

Parent topic: SCB- S-COBOL Messages


SCB-2016-00-E Portability violation

GOBACK, ENTRY, or EXHIBIT was coded. These are extensions of ANSI COBOL and are not offered by all compilers.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change code or remove portability parameter.

Parent topic: SCB- S-COBOL Messages


SCB-2017-00-E Keyword found instead of verb

A verb is expected in the structure, but another keyword was found.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2018-00-E ELSE must stand alone on line

The only code that can follow an ELSE statement on the same line is a comment beginning with /* . A missing hyphen in an ELSE-IF construction also causes this message.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Put ELSE on a separate line and indent the statement block beneath.

Parent topic: SCB- S-COBOL Messages


SCB-2019-00-E REPEAT statement syntax incorrect

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See also REPEAT statement.

Parent topic: SCB- S-COBOL Messages


SCB-2020-00-E USERNAME incompatible with CICS

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See also USERNAME.

Parent topic: SCB- S-COBOL Messages


SCB-2021-00-E USE verb outside of DECLARATIVES

The USE verb was encountered outside the Declaratives portion of the Procedure Division.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2022-00-E ENTRY verb must follow paragraph name

ENTRY was not positioned immediately after a paragraph or section header.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2023-00-E EXIT PROGRAM not allowed in DECLARATIVES

EXIT PROGRAM logic should be in the main part of the Procedure Division.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2024-00-E PROGRAM must be added to EXIT statement

An EXIT statement assumes EXIT PROGRAM is intended. EXIT alone is invalid in S-COBOL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2025-00-E Improper indentation decreased

All the indentation within one statement block must be the same. If one statement in a statement block begins one column or more earlier or later, this message results. For further processing, the line indentation decreases to the level of current indentation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Align the indentation and recompile. Truncation can occur when a line of less indentation follows one of more indentation within a statement block.

Parent topic: SCB- S-COBOL Messages


SCB-2026-00-E ELSE-ELSE-IF does not match cond above

An ELSE or ELSE-IF statement was coded at a level of indentation that does not match a preceding condition statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the code to determine if code is missing, indentation is incorrect, or the ELSE/ELSE-IF conditional is removable.

Parent topic: SCB- S-COBOL Messages


SCB-2027-00-E No matching SEARCH or EVALUATE with WHEN stm

SEARCH or EVALUATE
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2028-00-E No indented stm block for last conditional

The last conditional of an IF, ELSE-IF, ELSE statement is not followed by an indented statement block.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check the code to determine whether code is missing, indentation is needed, or the conditional is removable.

Parent topic: SCB- S-COBOL Messages


SCB-2029-00-E Missing WHILE-UNTIL after REPEAT stm

REPEAT was coded without an accompanying WHILE or UNTIL statement at the same level of indentation
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

This does not apply to REPEAT VARYING.

Parent topic: SCB- S-COBOL Messages


SCB-2030-00-E No WHEN clause with EVALUATE stm

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See EVALUATE.

Parent topic: SCB- S-COBOL Messages


SCB-2031-00-E Conditional stm not implemented

The coded conditional statement is not defined or is spelled incorrectly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2032-00-E Plus or minus expected

A plus or minus sign is expected for index increment or decrement in format SOURCE IS (SRC-1 +/- SRC-2).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2033-00-E SCB-2033-02-E Syntax-error in REPEAT or EVALUATE stm

REPEAT or EVALUATE
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2034-00-E Too many varying clauses with REPEAT stm

More than the maximum of 20 VARYING clauses are used with one REPEAT statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2035-00-E Index data item incompatible with VARYING

An index data item cannot be a conditional variable in a VARYING clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2036-00-E BY clause required with REPEAT LINKING

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See REPEAT LINKING.

Parent topic: SCB- S-COBOL Messages


SCB-2037-00-E Action statement is undefined

The specified action statement is not in use because it is not defined or was misspelled.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2038-00-E Not a file name

In the flagged line, or the line immediately preceding it, something other than a file name was referenced.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the code if the program runs on a system that supports only a file name.

Parent topic: SCB- S-COBOL Messages


SCB-2039-00-E Record name must be qualified

The record name is not unique and requires qualification.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Add OF or IN clause after the record name followed by a higher-level qualifier.

Parent topic: SCB- S-COBOL Messages


SCB-2040-00-E Too many conditions for WHEN expression

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See also WHEN.

Parent topic: SCB- S-COBOL Messages


SCB-2041-00-W Incomplete WHEN statement

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See also WHEN.

Parent topic: SCB- S-COBOL Messages


SCB-2042-00-E Para undefined

The paragraph being performed is not defined in the program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Define paragraph being performed or check the spelling of the paragraph name.

Parent topic: SCB- S-COBOL Messages


SCB-2043-00-E Proc undefined

The procedure named in the preceding PERFORM statement does not exist.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the procedure name in the PERFORM statement or create a paragraph and assign the procedure name to it. Presumably the paragraph will be developed later.

Note: If this error does not point to a specific error line, ensure that any user-supplied screen field edit routines are coded within the program itself (or if Online Express, at the MISC-USER-PARA control point).
Parent topic: SCB- S-COBOL Messages


SCB-2044-00-E Procedure with ENTRY may not be performed

A paragraph with an ENTRY statement is performed by another paragraph that is executed with the subprogram.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

This is illegal.

Parent topic: SCB- S-COBOL Messages


SCB-2045-00-E No arguments for para in PERFORM stm

Arguments were passed in a PERFORM statement to a paragraph with no arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Either remove the arguments, or you can add a list of dummy arguments to the corresponding paragraph name.

Note: If this error does not point to a specific error line, ensure that any user-supplied screen field edit routines are coded within the program itself (or if Online Express, at the MISC-USER-PARA control point).
Parent topic: SCB- S-COBOL Messages


SCB-2046-00-E Not enough arguments for PERFORM stm

The number of PERFORM statement actual arguments does not agree with the dummy argument list following the corresponding paragraph name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2047-00-E Too many arguments for PERFORM stm

The number of PERFORM statement actual arguments does not agree with the dummy argument list following the corresponding paragraph name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2048-00-E Arguments needed for PERFORM stm

The number of PERFORM statement actual arguments does not agree with the dummy argument list following the corresponding paragraph name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2049-00-E Improper statement termination

During S-COBOL scanning of statement line, the statement appears terminate on a non-numeric, non-alpha character.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check statement for a proper termination by a complete line, or for a proper continuation break.

Parent topic: SCB- S-COBOL Messages


SCB-2050-00-E Data name qualification is incorrect

The item being qualified is not a variable, or OF/IN is used incorrectly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2051-00-E Syntax error in argument sequence

During scanning for argument fields a syntax error was detected.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check flagged statement for properly coded arguments and syntax usage.

Parent topic: SCB- S-COBOL Messages


SCB-2052-00-E Argument return impossible

A literal or arithmetic expression must correspond to an argument preceded by a plus sign (+). You cannot copy back into a literal or arithmetic expression.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Precede the argument with a + sign if the argument receives a literal or arithmetic expression. Or, move the literal or arithmetic expression to a data name and use the data name as the PERFORM parameter.

Parent topic: SCB- S-COBOL Messages


SCB-2053-00-E Improper use of concatenation operator

A concatenation operator, &&, tried to continue a line that does not end with a non-numeric literal. Use && only when concatenating a non-numeric literal onto a continued line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-2054-00-E WHILE-UNTIL invalid for REPEAT with THRU-TO

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See also REPEAT.

Parent topic: SCB- S-COBOL Messages


SCB-2055-00-E THRU or TO missing

THRU or TO is missing in the DOWN TO/THRU clause in the REPEAT statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-3001-00-W Unknown verb COBOL action word assumed

The word flagged is not recognized by the AMB processor. It passes through, as is, to the generated COBOL output.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Examine the code for:

  • Spelling error.
  • Failure to provide an ellipsis (... ) on a continuation line when the word is not be a verb.
  • A verb that represents an extension of ANSI COBOL by a specific compiler (some IBM extensions are not so flagged).
  • Commands for a precompiler for COBOL software support in database management or data communication. For example, CICS has a special verb for use in S-COBOL; AMB does not recognize EXEC CICS or END-EXEC. Disregard this warning if the COBOL output is correct.
Parent topic: SCB- S-COBOL Messages


SCB-3002-00-W ON SIZE ERROR required assumed

An indented statement or an ELSE-IF/ELSE statement followed an arithmetic statement. This is valid only with an ON SIZE ERROR clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If inserting the ON SIZE ERROR clause into the code will generate the correct output, you can correct this at your convenience. Examine the code closely to determine whether any other correction is required.

Parent topic: SCB- S-COBOL Messages


SCB-3003-00-W No scope found for ON SIZE ERROR

The ON SIZE ERROR clause has no indented code to execute when a size error is encountered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-3005-00-W Replace THRU with TO clause

Use TO when executing the loop to, but not including, the stop point.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-3006-00-W SCB-3007-00-W Negative found DOWN THRU assumed

Negative found; DOWN TO assumed
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

The DOWN TO/THRU clause was omitted in a REPEAT statement where the literal or identifier following the BY clause is a negative number. The loop should be executed through the stop point.

No response is necessary if the DOWN clause is correct. Otherwise, correct the code.

Parent topic: SCB- S-COBOL Messages


SCB-3008-00-W SCB-3009-00-W Flag not set to FALSE in program

Flag not set to TRUE in program. The flag name following a TRUE or FALSE statement is not used with a corresponding FALSE or TRUE statement elsewhere in the program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Determine if this is correct.

Parent topic: SCB- S-COBOL Messages


SCB-3010-00-W AT END clause incompatible with file type

An AT END clause was encountered on an Input/Output statement (READ, WRITE, or REWRITE) for a direct file or an indexed file that is accessed randomly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Determine if the file access is correct, or if AT END should be removed.

Parent topic: SCB- S-COBOL Messages


SCB-3011-00-W Trailing quote missing - added

The trailing quote on a literal was omitted.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-3012-00-W Extraneous ELSE-ELSE-IF follows ELSE

An ELSE or ELSE-IF is indented directly beneath an ELSE.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


SCB-9002-00-F Parse stack overflow call AMB rep

Internal stack overflow. Execution stops.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

A nested IF structure may have exceeded the maximum of 14 indentation levels. If so, reduce the number of levels with PERFORM statements or some other code modification. Otherwise, contact your AMB Administrator.

Parent topic: SCB- S-COBOL Messages


SCB-9003-01-F SCB-9003-02-F Product error (A) call AMB rep

Internal check on S-COBOL processing. Make sure the ellipsis has three dots.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: SCB- S-COBOL Messages


SCB-9004-00-F Compiler error (L) call AMB rep

Internal check on S-COBOL processing of paragraph arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

If an error message pertaining to invalid REPEAT usage precedes this message, check for invalid REPEAT VARYING ...m THRU usage. Otherwise, contact your AMB Administrator.

Parent topic: SCB- S-COBOL Messages


SCB-9005-00-F Record look-ahead overflow call AMB rep

S-COBOL internal look-ahead routine exceeds the internal limits set for records held in a buffer area.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

This error can occur when one statement is continued on more than 16 subsequent lines. This limit applies to:

  • MOVE operands (i.e., <<, <+, <-, etc.)
  • REPEAT VARYING statements
  • I-O statements
  • EVALUATE with WHEN OTHER statements
  • PERFORMs with arguments
  • CICS Handle statements
  • Comment statements

Resolution:

Contact your AMB Administrator if more assistance is needed.

Parent topic: SCB- S-COBOL Messages


SCB-9006-00-F Look-ahead problem call AMB rep

Trouble with an internal S-COBOL routine that holds records in a buffer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Contact your AMB Administrator.

Parent topic: SCB- S-COBOL Messages


SCB-9007-00-F Symbol table full

The maximum limit of 1801 entries is exceeded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: SCB- S-COBOL Messages


VSM- VSAM Messages

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Select the number of the message you require details about:

  • VSM-1010-00-E Error in arguments
    An error occurred in VS-VALIDATE-OBTAIN. This error usually occurs in combination with another error that gives details on the argument in error.
  • VSM-1020-00-E Error - file(s) was not given cannot be defaulted
    An error occurred in VS-VALIDATE-FILE. You did not specify the file name for the OPEN or CLOSE call.
  • VSM-1030-00-E Error - record was not given cannot be defaulted
    An error occurred in VS-VALIDATE-REC. You did not specify the record name.
  • VSM-1040-00-E Error - record unknown An error occurred in VS-VALIDATE-REC
    You specified an invalid record name.
  • VSM-1050-00-E For record key not defined
    An error occurred in VS-VALIDATE-KEY. You specified an invalid key name.
  • VSM-1060-00-E Error - record was not given cannot be defaulted
    An error occurred in DDI-FIND-REC. You did not specify the record name.
  • VSM-1070-00-E Error - record not found cannot be defaulted
    An error occurred in DDI-FIND-REC. You specified an invalid record name.
  • VSM-1080-00-E MODE not specified in OPEN
    An error occurred in VS-OPEN. You did not specify the file mode.
  • VSM-1090-00-E File not specified in open
    An error occurred in VS-OPEN. You did not specify the file. The VS-VALIDATE-FILE call should trap the error.
  • VSM-1100-00-E File not specified in close
    An error occurred in VS-CLOSE. You did not specify the file. The VS-VALIDATE-FILE call should trap the error.
  • VSM-1500-00-E AMB VSAM error - first keyword for DB command is missing
    You coded the database call without specifying the required keywords.
  • VSM-1520-00-E AMB VSAM error - first keyword for DB-ERASE DB-STORE DB-MODIFY and DB-PROCESS must be REC
  • VSM-1530-00-E AMB VSAM error - unknown keyword at parm number keyword
    You coded the database call using an invalid keyword.
  • VSM-1540-00-E AMB VSAM error - record name is missing
    You coded the database call without specifying a record name.
  • VSM-1550-00-E VSM-1560-00-E AMB VSAM error - MODE keyword missing
    You coded the DB-OPEN call without the MODE option.
  • VSM-1570-00-E AMB VSAM error - INTO keyword missing
    You coded the DB-OBTAIN or DB-PROCESS call with the INTO keyword, but did not specify the alternate storage area name.
  • VSM-1580-00-E AMB VSAM error - FROM keyword missing
    You coded the DB-STORE or DB-MODIFY call with the FROM keyword, but did not specify the alternate storage area.
  • VSM-1590-00-E AMB VSAM error - SUB keyword missing
    You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the SUB keyword, but did not specify the subscript.
  • VSM-1600-00-E AMB VSAM error - OF keyword missing
    You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the OF keyword, but did not specify the qualification data name.
  • VSM-1610-00-E AMB VSAM ERROR - KLEN is missing expected as parm number
    You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the KLEN keyword, but did not specify the actual key length as a number or data name.
  • VSM-1620-00-E AMB VSAM error - key name is missing expected as parm number
    You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the WHERE keyword, but did not specify the record key name.
  • VSM-1630-00-E AMB VSAM error - operator is missing expected as parm number
    You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the WHERE keyword, but did not specify the operator.
  • VSM-1640-00-E AMB VSAM error - key source is missing expected as parm number
    You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE with WHERE, but did not specify the key source (value that updates the key).
  • VSM-1650-00-E AMB VSAM error - REQID is missing expected as parm number
    You coded the he DB-OBTAIN, DB-PROCESS, or DB-FREE with REQID, but the did not specify the identifier.
  • VSM-1660-00-E AMB VSAM error - DDN data area is missing expected as parm number
    The DB call was coded using the DDN keyword, but the DDN data-area was not specified.
  • VSM-1670-00-E AMB VSAM error - file keyword missing
    The DB-OPEN or DB-CLOSE call did not specify FILE as the first keyword.
  • VSM-1680-00-E AMB VSAM error - SYSID name missing expected as parm number
    The DB call was coded with the SYSID keyword, but the SYSID name was not specified.
  • VSM-2010-00-E PREVIOUS keyword allowed for CICS only
    The PREVIOUS or PREV keyword is an option allowed only when the DC target is CICS.
  • VSM-2020-00-E KEYLENGTH allowed for CICS only
    The KEYLENGTH or KLEN keyword is an option allowed only when the DC target is CICS.
  • VSM-2030-00-E Multi level call invalid for VSAM
    Only a single record can be specified in a call accessing VSAM files.
  • VSM-2040-00-E VSAM record can be qualified only on one field
    The record can be qualified only on one key if accessing VSAM files.
  • VSM-2050-00-E REF keyword invalid for VSAM
    The keyword REF or REFERENCE is invalid for VSAM files.
  • VSM-2060-00-E CKEYED invalid for VSAM
    The keyword CKEYED or CONCAT-KEYED is invalid for VSAM files.
  • VSM-2070-00-E CURRENT invalid for VSAM
    The keyword CURRENT is invalid for VSAM files.
  • VSM-2080-00-E CCODE invalid for VSAM
    The keyword CCODE or COMMAND-CODE is invalid for VSAM files.
  • VSM-2090-00-E FIRST or LAST invalid for VSAM
    The keywords FIRST or LAST are invalid for VSAM files.
  • VSM-2100-00-E HOLD invalid for read PREVIOUS
    The keyword HOLD is invalid when specifying the keyword PREV or PREVIOUS.
  • VSM-2110-00-E RESET invalid for read PREVIOUS
    The keyword RESET is invalid when specifying the keyword PREV or PREVIOUS.
  • VSM-2120-00-I RESET ignored for qualified read
    The keyword RESET or RESET-POSITION has no meaning for a qualified retrieval and is ignored.
  • VSM-2130-00-I VIEW ignored for qualified read
    The keyword VIEW is ignored for a qualified retrieval.
  • VSM-2140-00-I PREV ignored for qualified read
    The keyword PREV or PREVIOUS has no meaning for a qualified retrieval and is ignored.
  • VSM-2150-00-E Access must be specified as DYNAMIC
    File access must be DYNAMIC for keyed reads when the relational operator is not =.
  • VSM-2210-00-E Error - value for VS-HOLD-DEFAULT is invalid value
    An error occurred in VSMDBMAC. The value for &VS-HOLD-DEFAULT is invalid. Valid values are HOLD, NOHOLD, and PROCOPT.
  • VSM-2220-00-E Error for file access sequential for keyed VSAM read
    An error occurred in MVS VS-OBTAIN-BY-KEY. The data view specifies sequential access, but a keyed READ call was entered.
  • VSM-2230-00-E Qualified retrieval not allowed for entry sequenced data set (ESDS) or OS sequential file
    An error occurred in MVS VS-OBTAIN-BY-KEY. The data view specifies ESDS record type, but a keyed READ call was coded.
  • VSM-2240-00-E Error for file READ NEXT invalid for random file
    An error occurred in MVS VS-OBTAIN-NEXT. The data view has specified random access and a sequential READ call was coded.
  • VSM-2250-00-E Error for file qualified retrieval not allowed for entry sequenced data set (ESDS) or OS sequential file
    An error occurred in MVS VS-OBTAIN-NEXT. The data view has specified sequential or ESDS file type while the developer has coded a key parameter.
  • VSM-2260-00-E Cannot OBTAIN-PREV in MVS program
    An error occurred in VS-OBTAIN-PREV. READ PREVIOUS is not allowed for batch programs.
  • VSM-2270-00-E Entry sequenced data set or OS sequential file cannot be deleted
    An error occurred in VS-ERASE. ESDS and OS sequential files cannot be deleted.
  • VSM-2280-00-E Key length too great defined length used
    An error occurred in VS-VALIDATE-KLEN. The key length parameter is greater than the key length specified in the data view. The key length specified in the data view is used.
  • VSM-2290-00-E Operator should be EQUAL
    An error occurred in VS-VALIDATE-OPERATOR. A OBTAIN-PREV or PREVIOUS parameter was coded with an operator other than EQUAL.
  • VSM-2300-00-E Operator should be EQUAL or GTEQ
    An error occurred in VS-VALIDATE-OPERATOR. An operator other than EQUAL or GTEQ was coded in a CICS program.
  • VSM-2310-00-E Operator not valid operator
    An invalid operator was found in VS-VALIDATE-OPERATOR.
  • VSM-2330-00-E File used but not opened
    An error occurred in VS-EPILOGUE-MACRO. You coded a VSAM database call without coding an OPEN for the file.
  • VSM-2340-00-E File opened but not closed
    An error occurred in VS-EPILOGUE-MACRO. You coded an OPEN call without coding a CLOSE for the file.
  • VSM-2350-00-E File closed but not opened
    An error occurred in VS-EPILOGUE-MACRO. You coded a CLOSE call without coding an OPEN for the file.
  • VSM-2360-00-E PROCOPT violation file
    An error occurred in VS-VALIDATE-PROCOPT. This message occurs when &VS-PROCOPT-WARNING = 2. You coded a VSAM call that is not allowed according to the file processing option in the data view.
  • VSM-2370-00-E Linkage not allowed in CICS program use TP-LINKAGE commands
    An error occurred in DB-PD-STACKED-EPILOGUE. The &COPY-SECTION variable was set to linkage for a CICS program. &COPY-SECTION should be set to WORKING-STORAGE for CICS programs.
  • VSM-2380-00-E File unknown
    This message occurred in VS-VALIDATE-FILE. You coded the OPEN/CLOSE call, but specified a file that is unknown to the data view.
  • VSM-2390-00-E VSM-2600-00-E Entry sequenced data sets (ESDS) must use EQUAL operator
    This message occurred in VS-VALIDATE-OPERATOR. You used an operator other than EQUAL for an ESDS file type.
  • VSM-2450-00-E AMB VSAM ERROR - &ampVS-HOLD-DEFAULT SHOULD BE PROCOPT HOLD OR NOHOLD VALUE value
    The CARDIN variable &VS-HOLD-DEFAULT was assigned a value other than HOLD, NOHOLD, or PROCOPT.
  • VSM-2460-00-E AMB VSAM error - INTO keyword for DB retrieval commands only
    The INTO keyword was used on a non-retrieval DB call.
  • VSM-2466-00-E AMB VSAM error - INTO keyword invalid with REF keyword
    The INTO keyword was used on a DB-OBTAIN with the REF keyword. The REF keyword indicates file positioning only - not record retrieval.
  • VSM-2470-00-E AMB VSAM error - FROM keyword for DB-STORE and DB-MODIFY only
    The FROM keyword was used on a retrieval call.
  • VSM-2480-00-E AMB VSAM error - DB-ERASE with key qualification invalid with sequential access mode
    The WHERE key qualification for DB-ERASE is invalid when SEQUENTIAL access is specified.
  • VSM-2481-00-E AMB VSAM error - SUB and OF keywords used for key qualification only
    Use the SUB and OF keywords only with calls specifying the WHERE key qualification to subscript or qualify the data being moved to the record key.
  • VSM-2500-00-E AMB VSAM error - PROCOPT violation file name command in violation procopts for file
    The Data view PROCOPT (processing option) for the named file does not include the processing option for the DB call.
  • VSM-2510-00-E AMB VSAM error - HOLD keyword is invalid when used with duplicate key
    The HOLD keyword is invalid when used on a sequential DB-OBTAIN or DB-PROCESS call where the VIEW keyname specifies an alternate key with duplicates allowed.
  • VSM-2520-00-E AMB VSAM error - HOLD keyword is invalid when used with keyword
    The HOLD keyword is invalid when used with the named keyword.
  • VSM-2530-00-E AMB VSAM error - record name is not defined to subschema
    The record name was not found in the program Data view.
  • VSM-2550-00-E AMB VSAM error - key name invalid key
    The record key name was not found in the program Data view.
  • VSM-2600-00-E AMB VSAM error - entry sequenced data sets (ESDS) must use EQUAL operator
    The operator used was invalid.
  • VSM-2610-00-E AMB VSAM error - invalid operator
    The operator used was invalid.
  • VSM-2650-00-E AMB VSAM error - keyword invalid when using qualified OBTAIN
    The named keyword is invalid for a DB-OBTAIN specifying the WHERE key qualification.
  • VSM-2660-00-E AMB VSAM error - PREV keyword is invalid for MVS/VSAM - used in CICS/VSAM only
    The PREV keyword is invalid for MVS processing. The READPREV function is not a native MVS VSAM operation.
  • VSM-2670-00-E AMB VSAM error - REF keyword must use key qualification
    The DB-OBTAIN used with the REF keyword must also specify the WHERE key qualification clause.
  • VSM-2680-00-E AMB VSAM error - qualified DB-ERASE not valid with keyword
  • VSM-2690-00-E AMB VSAM error - qualified DB-ERASE must use primary key
    The key named on the DB-ERASE with key qualification was not the record primary key.
  • VSM-2700-00-E AMB VSAM error - qualified DB-ERASE must use EQUAL operator
  • VSM-2710-00-E AMB VSAM error - DB-FREE cannot be used with keyword
  • VSM-2720-00-E AMB VSAM ERROR - key qualification invalid for command
    The WHERE key qualification is invalid for the named call.
  • VSM-2730-00-E AMB VSAM error - DB-FREE keyword ALL cannot be used with keyword
    The named keyword is invalid when the ALL keyword is used.
  • VSM-2740-00-E AMB VSAM error - keyword can only be used with REF keyword
    The named keyword is valid only for a DB-OBTAIN call specifying REF.
  • VSM-2750-00-E AMB VSAM error - KEYWORD can only be used with DB-FREE
  • VSM-2760-00-E AMB VSAM error - file used but not opened
    The named file was specified by database calls, but was not opened with a DB-OPEN call.
  • VSM-2770-00-E AMB VSAM error - file opened but not closed
    The named file was opened with a DB-OPEN but was not closed with a DB-CLOSE call.
  • VSM-2780-00-E AMB VSAM error - file closed but not opened
    The named file was closed with a DB-CLOSE but was not opened with a DB-OPEN call.
  • VSM-2790-00-E AMB VSAM error - filename not found in subschema at parm number filename
    The named file was not found in the program Data view.
  • VSM-2800-00-E AMB VSAM error - invalid mode specification mode
    The DB-OPEN MODE option was invalid.
  • VSM-2830-00-E AMB VSAM error - REQID keyword is invalid with the APS option of &ampVS-ENDBR-CONTROL Must use USER option
    The REQID keyword (indicating a simultaneous browse operation) is valid only when the control variable &VS-ENDBR-CONTROL is set to USER.
  • VSM-2840-00-E AMB VSAM error - SYSID keyword was seen on previous commands but was not specified for DB-FREE
    The SYSID keyword specified a remote data set on a previous call but was not coded for the DB-FREE call.
  • VSM-2850-00-E AMB VSAM error - when reqid keyword is used with the PERFORM option of &ampVS-ENDBR-UNLOCK-LOGIC all applicable commands must have the REQID keyword
    The REQID was used previously in the program but was not specified for this call. The control variable &VS-ENDBR-UNLOCK-CONTROL is set to PERFORM (versus INLINE).
  • VSM-2860-00-E AMB VSAM error - KLEN keyword is invalid when used with PREV keyword
    The KLEN keyword cannot be used with the PREV keyword. The native CICS STARTBR must not specify a partial key length prior to the CICS READPREV.
  • VSM-2870-00-E AMB VSAM error - KLEN keyword is invalid when used with ESDS or RRDS files
  • VSM-2880-00-E AMB VSAM error - DB-ERASE cannot be used for ESDS files
  • VSM-2890-00-E AMB VSAM error - REQID value must be a numeric single digit between 0 and 9 REQID
  • VSM-2900-00-E AMB VSAM error - &ampVS-ENDBR-CONTROL option must have APS value to use ALL keyword
    The control variable &VS-ENDBR-CONTROL must be set to AMB to use the DB-FREE keyword ALL.
  • VSM-2910-00-E AMB VSAM error - &ampCIC-APS-EIBRCODE variable must be set to YES when using VSAM Command Version II
    AMB VSAM VERSION II must have the AMB CICS EIBRCODE structure included.
  • VSM-2920-00-E AMB VSAM error - control OF ENDBR and UNLOCK functions must be in USER mode to use the DDN keyword
    The DDN keyword is valid only when the control variables &VS-ENDBR-CONTROL and &VS-UNLOCK-CONTROL are set to USER.
  • VSM-3010-00-E For record no primary key defined
    An error occurred in VS-VALIDATE-KEY. You used the default (primary key) but the data view does not have a primary key defined.
  • VSM-3020-00-E Error in validate key
    An error occurred in VS-VALIDATE-KEY. You used the default (primary key) but the data view does not have a primary key defined.
  • VSM-4010-00-I HOLD option with single string may produce excessive code
    This message occurred in VS-OBTAIN-NEXT. The developer has coded the OBTAIN-NEXT/DB-OBTAIN with the hold parameter. This informational item means that an ENDBROWSE and READ for update will be generated.
  • VSM-4020-00-I RESET keyword is ignored for entry sequenced data set (ESDS) and OS sequential files
    This message occurred in MVS VS-OBTAIN-NEXT. You coded the OBTAIN-NEXT/DB-OBTAIN with the RESET parameter. The RESET parameter is ignored.
  • VSM-4040-00-I PROCOPT violation file
    This message occurred in VS-VALIDATE-PROCOPT, where &VS-PROCOPT-WARNING = 1. You coded a VSAM call that is not allowed according to the file processing option in the data view.
  • VSM-4050-00-W PROCOPT VIOLATION FILE file
    This message occurred in VS-VALIDATE-PROCOPT and when &VS-PROCOPT-WARNING = 0. You coded a VSAM call that is not allowed according to the file processing option in the data view.
  • VSM-4510-00-I AMB VSAM information - keyword keyword ignored for MVS/VSAM
    The named keyword is ignored for AMB MVS/VSAM, because it has no function in the MVS VSAM environment.
  • VSM-4530-00-I AMB VSAM information - KEYLENGTH specified larger than defined length - using length defined to subschema
    The number specified for the KLEN keyword is greater than the length defined to the program Data View. The Data View-defined length is used.
  • VSM-4540-00-I AMB VSAM information - DB-FREE ignored for MVS-VSAM
    The DB-FREE call performs CICS-specific functions only and is ignored for the AMB MVS VSAM program.
  • VSM-4550-00-I AMB VSAM information - file is variable length field Must be updated with record length prior to DB-STORE and DB-MODIFY
  • VSM-4560-00-I AMB VSAM information - record(s) in subschema not referenced by DB commands have been excluded from program storage
    Record descriptions for files not used in a database call are not included into the program storage.
  • VSM-4570-00-I AMB VSAM warning - DB-OPEN and DB-CLOSE ignored for CICS VSAM programs
    DB-OPEN and DB-CLOSE calls found in a CICS program are ignored.
  • VSM-5010-00-E Record name VSAM type record only VSAM type records are supported for Micro Focus V-ISAM
    Micro Focus V-ISAM supports only KSDS type records.
  • VSM-5020-00-E VSM-5030-00-E Option is not supported by Micro Focus V-ISAM
    This option is not supported by Micro Focus and is ignored.
  • VSM-5040-00-W Record name type record Only fixed length records are supported for Micro Focus PC-CICS
    Micro Focus PC-CICS with V-ISAM does not support variable length records.
  • VSM-5060-00-E Command is not supported by Micro Focus PC-CICS
  • VSM-6065-00-E Option is not supported by Micro Focus PC-CICS
  • VSM-8010-00-F VSMDBMAC included twice - remove the extra INCLUDE
  • VSM-8020-00-F VSMPHYS included twice-remove the extra INCLUDE
  • VSM-8200-00-F AMB VSAM fatal - APVSMDB included twice
  • VSM-8210-00-F AMB VSAM fatal - APVSMCIC included twice
  • VSM-8220-00-F AMB VSAM fatal - APVSMMVS included twice
  • VSM-8230-00-F AMB VSAM command version invalid
    The CARDIN variable &VS-COMMAND-VERSION was assigned an invalid value.
Parent topic: AppMaster Builder Error Messages


VSM-1010-00-E Error in arguments

An error occurred in VS-VALIDATE-OBTAIN. This error usually occurs in combination with another error that gives details on the argument in error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1020-00-E Error - file(s) was not given cannot be defaulted

An error occurred in VS-VALIDATE-FILE. You did not specify the file name for the OPEN or CLOSE call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1030-00-E Error - record was not given cannot be defaulted

An error occurred in VS-VALIDATE-REC. You did not specify the record name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1040-00-E Error - record unknown An error occurred in VS-VALIDATE-REC

You specified an invalid record name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1050-00-E For record key not defined

An error occurred in VS-VALIDATE-KEY. You specified an invalid key name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1060-00-E Error - record was not given cannot be defaulted

An error occurred in DDI-FIND-REC. You did not specify the record name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1070-00-E Error - record not found cannot be defaulted

An error occurred in DDI-FIND-REC. You specified an invalid record name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1080-00-E MODE not specified in OPEN

An error occurred in VS-OPEN. You did not specify the file mode.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1090-00-E File not specified in open

An error occurred in VS-OPEN. You did not specify the file. The VS-VALIDATE-FILE call should trap the error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1100-00-E File not specified in close

An error occurred in VS-CLOSE. You did not specify the file. The VS-VALIDATE-FILE call should trap the error.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1500-00-E AMB VSAM error - first keyword for DB command is missing

You coded the database call without specifying the required keywords.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1520-00-E AMB VSAM error - first keyword for DB-ERASE DB-STORE DB-MODIFY and DB-PROCESS must be REC

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1530-00-E AMB VSAM error - unknown keyword at parm number keyword

You coded the database call using an invalid keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1540-00-E AMB VSAM error - record name is missing

You coded the database call without specifying a record name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1550-00-E VSM-1560-00-E AMB VSAM error - MODE keyword missing

You coded the DB-OPEN call without the MODE option.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1570-00-E AMB VSAM error - INTO keyword missing

You coded the DB-OBTAIN or DB-PROCESS call with the INTO keyword, but did not specify the alternate storage area name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1580-00-E AMB VSAM error - FROM keyword missing

You coded the DB-STORE or DB-MODIFY call with the FROM keyword, but did not specify the alternate storage area.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1590-00-E AMB VSAM error - SUB keyword missing

You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the SUB keyword, but did not specify the subscript.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1600-00-E AMB VSAM error - OF keyword missing

You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the OF keyword, but did not specify the qualification data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1610-00-E AMB VSAM ERROR - KLEN is missing expected as parm number

You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the KLEN keyword, but did not specify the actual key length as a number or data name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1620-00-E AMB VSAM error - key name is missing expected as parm number

You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the WHERE keyword, but did not specify the record key name.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1630-00-E AMB VSAM error - operator is missing expected as parm number

You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE call using the WHERE keyword, but did not specify the operator.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1640-00-E AMB VSAM error - key source is missing expected as parm number

You coded the DB-OBTAIN, DB-PROCESS, or DB-ERASE with WHERE, but did not specify the key source (value that updates the key).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1650-00-E AMB VSAM error - REQID is missing expected as parm number

You coded the he DB-OBTAIN, DB-PROCESS, or DB-FREE with REQID, but the did not specify the identifier.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1660-00-E AMB VSAM error - DDN data area is missing expected as parm number

The DB call was coded using the DDN keyword, but the DDN data-area was not specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1670-00-E AMB VSAM error - file keyword missing

The DB-OPEN or DB-CLOSE call did not specify FILE as the first keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-1680-00-E AMB VSAM error - SYSID name missing expected as parm number

The DB call was coded with the SYSID keyword, but the SYSID name was not specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2010-00-E PREVIOUS keyword allowed for CICS only

The PREVIOUS or PREV keyword is an option allowed only when the DC target is CICS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2020-00-E KEYLENGTH allowed for CICS only

The KEYLENGTH or KLEN keyword is an option allowed only when the DC target is CICS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2030-00-E Multi level call invalid for VSAM

Only a single record can be specified in a call accessing VSAM files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2040-00-E VSAM record can be qualified only on one field

The record can be qualified only on one key if accessing VSAM files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2050-00-E REF keyword invalid for VSAM

The keyword REF or REFERENCE is invalid for VSAM files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2060-00-E CKEYED invalid for VSAM

The keyword CKEYED or CONCAT-KEYED is invalid for VSAM files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2070-00-E CURRENT invalid for VSAM

The keyword CURRENT is invalid for VSAM files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2080-00-E CCODE invalid for VSAM

The keyword CCODE or COMMAND-CODE is invalid for VSAM files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2090-00-E FIRST or LAST invalid for VSAM

The keywords FIRST or LAST are invalid for VSAM files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2100-00-E HOLD invalid for read PREVIOUS

The keyword HOLD is invalid when specifying the keyword PREV or PREVIOUS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2110-00-E RESET invalid for read PREVIOUS

The keyword RESET is invalid when specifying the keyword PREV or PREVIOUS.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2120-00-I RESET ignored for qualified read

The keyword RESET or RESET-POSITION has no meaning for a qualified retrieval and is ignored.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2130-00-I VIEW ignored for qualified read

The keyword VIEW is ignored for a qualified retrieval.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2140-00-I PREV ignored for qualified read

The keyword PREV or PREVIOUS has no meaning for a qualified retrieval and is ignored.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2150-00-E Access must be specified as DYNAMIC

File access must be DYNAMIC for keyed reads when the relational operator is not =.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2210-00-E Error - value for VS-HOLD-DEFAULT is invalid value

An error occurred in VSMDBMAC. The value for &VS-HOLD-DEFAULT is invalid. Valid values are HOLD, NOHOLD, and PROCOPT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2220-00-E Error for file access sequential for keyed VSAM read

An error occurred in MVS VS-OBTAIN-BY-KEY. The data view specifies sequential access, but a keyed READ call was entered.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2230-00-E Qualified retrieval not allowed for entry sequenced data set (ESDS) or OS sequential file

An error occurred in MVS VS-OBTAIN-BY-KEY. The data view specifies ESDS record type, but a keyed READ call was coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2240-00-E Error for file READ NEXT invalid for random file

An error occurred in MVS VS-OBTAIN-NEXT. The data view has specified random access and a sequential READ call was coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2250-00-E Error for file qualified retrieval not allowed for entry sequenced data set (ESDS) or OS sequential file

An error occurred in MVS VS-OBTAIN-NEXT. The data view has specified sequential or ESDS file type while the developer has coded a key parameter.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2260-00-E Cannot OBTAIN-PREV in MVS program

An error occurred in VS-OBTAIN-PREV. READ PREVIOUS is not allowed for batch programs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2270-00-E Entry sequenced data set or OS sequential file cannot be deleted

An error occurred in VS-ERASE. ESDS and OS sequential files cannot be deleted.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2280-00-E Key length too great defined length used

An error occurred in VS-VALIDATE-KLEN. The key length parameter is greater than the key length specified in the data view. The key length specified in the data view is used.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2290-00-E Operator should be EQUAL

An error occurred in VS-VALIDATE-OPERATOR. A OBTAIN-PREV or PREVIOUS parameter was coded with an operator other than EQUAL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2300-00-E Operator should be EQUAL or GTEQ

An error occurred in VS-VALIDATE-OPERATOR. An operator other than EQUAL or GTEQ was coded in a CICS program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2310-00-E Operator not valid operator

An invalid operator was found in VS-VALIDATE-OPERATOR.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2330-00-E File used but not opened

An error occurred in VS-EPILOGUE-MACRO. You coded a VSAM database call without coding an OPEN for the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2340-00-E File opened but not closed

An error occurred in VS-EPILOGUE-MACRO. You coded an OPEN call without coding a CLOSE for the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2350-00-E File closed but not opened

An error occurred in VS-EPILOGUE-MACRO. You coded a CLOSE call without coding an OPEN for the file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2360-00-E PROCOPT violation file

An error occurred in VS-VALIDATE-PROCOPT. This message occurs when &VS-PROCOPT-WARNING = 2. You coded a VSAM call that is not allowed according to the file processing option in the data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check data view *DDI card procopt option. See Coding VSAM DDI Statements.

Parent topic: VSM- VSAM Messages


VSM-2370-00-E Linkage not allowed in CICS program use TP-LINKAGE commands

An error occurred in DB-PD-STACKED-EPILOGUE. The &COPY-SECTION variable was set to linkage for a CICS program. &COPY-SECTION should be set to WORKING-STORAGE for CICS programs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2380-00-E File unknown

This message occurred in VS-VALIDATE-FILE. You coded the OPEN/CLOSE call, but specified a file that is unknown to the data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check data view. The file name should correspond to batch data view option AS or DDN.

Parent topic: VSM- VSAM Messages


VSM-2390-00-E VSM-2600-00-E Entry sequenced data sets (ESDS) must use EQUAL operator

This message occurred in VS-VALIDATE-OPERATOR. You used an operator other than EQUAL for an ESDS file type.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2450-00-E AMB VSAM ERROR - &ampVS-HOLD-DEFAULT SHOULD BE PROCOPT HOLD OR NOHOLD VALUE value

The CARDIN variable &VS-HOLD-DEFAULT was assigned a value other than HOLD, NOHOLD, or PROCOPT.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Assign appropriate value to &VS-HOLD-DEFAULT in CNTL(APSDBDC).

Parent topic: VSM- VSAM Messages


VSM-2460-00-E AMB VSAM error - INTO keyword for DB retrieval commands only

The INTO keyword was used on a non-retrieval DB call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use the FROM keyword to specify an alternate storage area for DB-STORE and DB-MODIFY.

Parent topic: VSM- VSAM Messages


VSM-2466-00-E AMB VSAM error - INTO keyword invalid with REF keyword

The INTO keyword was used on a DB-OBTAIN with the REF keyword. The REF keyword indicates file positioning only - not record retrieval.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2470-00-E AMB VSAM error - FROM keyword for DB-STORE and DB-MODIFY only

The FROM keyword was used on a retrieval call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use the INTO keyword to specify an alternate storage area for DB-STORE and DB-MODIFY.

Parent topic: VSM- VSAM Messages


VSM-2480-00-E AMB VSAM error - DB-ERASE with key qualification invalid with sequential access mode

The WHERE key qualification for DB-ERASE is invalid when SEQUENTIAL access is specified.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Retrieve the record prior to deletion. Use DB-ERASE without the key qualification.

Parent topic: VSM- VSAM Messages


VSM-2481-00-E AMB VSAM error - SUB and OF keywords used for key qualification only

Use the SUB and OF keywords only with calls specifying the WHERE key qualification to subscript or qualify the data being moved to the record key.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2500-00-E AMB VSAM error - PROCOPT violation file name command in violation procopts for file

The Data view PROCOPT (processing option) for the named file does not include the processing option for the DB call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change DDI SUB PROCOPT card if necessary.

Parent topic: VSM- VSAM Messages


VSM-2510-00-E AMB VSAM error - HOLD keyword is invalid when used with duplicate key

The HOLD keyword is invalid when used on a sequential DB-OBTAIN or DB-PROCESS call where the VIEW keyname specifies an alternate key with duplicates allowed.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consider program logic that retains record position among duplicates while record updating occurs.

Parent topic: VSM- VSAM Messages


VSM-2520-00-E AMB VSAM error - HOLD keyword is invalid when used with keyword

The HOLD keyword is invalid when used with the named keyword.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Consider separating the steps required to accomplish the function.

Parent topic: VSM- VSAM Messages


VSM-2530-00-E AMB VSAM error - record name is not defined to subschema

The record name was not found in the program Data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2550-00-E AMB VSAM error - key name invalid key

The record key name was not found in the program Data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2600-00-E AMB VSAM error - entry sequenced data sets (ESDS) must use EQUAL operator

The operator used was invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use the EQUAL or GTEQ operator for CICS. Use the EQUAL, GTEQ or > operator for MVS.

Parent topic: VSM- VSAM Messages


VSM-2610-00-E AMB VSAM error - invalid operator

The operator used was invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use the EQUAL or GTEQ operator for CICS. Use the EQUAL, GTEQ or > operator for MVS.

Parent topic: VSM- VSAM Messages


VSM-2650-00-E AMB VSAM error - keyword invalid when using qualified OBTAIN

The named keyword is invalid for a DB-OBTAIN specifying the WHERE key qualification.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2660-00-E AMB VSAM error - PREV keyword is invalid for MVS/VSAM - used in CICS/VSAM only

The PREV keyword is invalid for MVS processing. The READPREV function is not a native MVS VSAM operation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use an alternate programming method.

Parent topic: VSM- VSAM Messages


VSM-2670-00-E AMB VSAM error - REF keyword must use key qualification

The DB-OBTAIN used with the REF keyword must also specify the WHERE key qualification clause.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the WHERE key qualification to specify the key search criteria for the MVS START or CICS STARTBR call.

Parent topic: VSM- VSAM Messages


VSM-2680-00-E AMB VSAM error - qualified DB-ERASE not valid with keyword

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2690-00-E AMB VSAM error - qualified DB-ERASE must use primary key

The key named on the DB-ERASE with key qualification was not the record primary key.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use the primary record key or consider an alternate programming method.

Parent topic: VSM- VSAM Messages


VSM-2700-00-E AMB VSAM error - qualified DB-ERASE must use EQUAL operator

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2710-00-E AMB VSAM error - DB-FREE cannot be used with keyword

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See DB-FREE.

Parent topic: VSM- VSAM Messages


VSM-2720-00-E AMB VSAM ERROR - key qualification invalid for command

The WHERE key qualification is invalid for the named call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2730-00-E AMB VSAM error - DB-FREE keyword ALL cannot be used with keyword

The named keyword is invalid when the ALL keyword is used.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code a separate DB-FREE call for the file requiring the named keyword.

Parent topic: VSM- VSAM Messages


VSM-2740-00-E AMB VSAM error - keyword can only be used with REF keyword

The named keyword is valid only for a DB-OBTAIN call specifying REF.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2750-00-E AMB VSAM error - KEYWORD can only be used with DB-FREE

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

See DB-FREE.

Parent topic: VSM- VSAM Messages


VSM-2760-00-E AMB VSAM error - file used but not opened

The named file was specified by database calls, but was not opened with a DB-OPEN call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2770-00-E AMB VSAM error - file opened but not closed

The named file was opened with a DB-OPEN but was not closed with a DB-CLOSE call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2780-00-E AMB VSAM error - file closed but not opened

The named file was closed with a DB-CLOSE but was not opened with a DB-OPEN call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2790-00-E AMB VSAM error - filename not found in subschema at parm number filename

The named file was not found in the program Data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2800-00-E AMB VSAM error - invalid mode specification mode

The DB-OPEN MODE option was invalid.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2830-00-E AMB VSAM error - REQID keyword is invalid with the APS option of &ampVS-ENDBR-CONTROL Must use USER option

The REQID keyword (indicating a simultaneous browse operation) is valid only when the control variable &VS-ENDBR-CONTROL is set to USER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

You can change &VS-ENDBR-CONTROL in the control file APSCNTL(APVSAMIN).

Parent topic: VSM- VSAM Messages


VSM-2840-00-E AMB VSAM error - SYSID keyword was seen on previous commands but was not specified for DB-FREE

The SYSID keyword specified a remote data set on a previous call but was not coded for the DB-FREE call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the SYSID keyword to avoid execution errors.

Parent topic: VSM- VSAM Messages


VSM-2850-00-E AMB VSAM error - when reqid keyword is used with the PERFORM option of &ampVS-ENDBR-UNLOCK-LOGIC all applicable commands must have the REQID keyword

The REQID was used previously in the program but was not specified for this call. The control variable &VS-ENDBR-UNLOCK-CONTROL is set to PERFORM (versus INLINE).
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Code the REQID keyword on all applicable calls or change the value of &VS-ENDBR-UNLOCK-LOGIC to INLINE in APSCNTL(APVSAMIN).

Parent topic: VSM- VSAM Messages


VSM-2860-00-E AMB VSAM error - KLEN keyword is invalid when used with PREV keyword

The KLEN keyword cannot be used with the PREV keyword. The native CICS STARTBR must not specify a partial key length prior to the CICS READPREV.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-2870-00-E AMB VSAM error - KLEN keyword is invalid when used with ESDS or RRDS files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2880-00-E AMB VSAM error - DB-ERASE cannot be used for ESDS files

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2890-00-E AMB VSAM error - REQID value must be a numeric single digit between 0 and 9 REQID

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Check syntax.

Parent topic: VSM- VSAM Messages


VSM-2900-00-E AMB VSAM error - &ampVS-ENDBR-CONTROL option must have APS value to use ALL keyword

The control variable &VS-ENDBR-CONTROL must be set to AMB to use the DB-FREE keyword ALL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use separate DB-FREE calls for each file, or change the value of &VS-ENDBR-CONTROL to AMB in APSCNTL(APVSAMIN).

Parent topic: VSM- VSAM Messages


VSM-2910-00-E AMB VSAM error - &ampCIC-APS-EIBRCODE variable must be set to YES when using VSAM Command Version II

AMB VSAM VERSION II must have the AMB CICS EIBRCODE structure included.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Set &CIC-APS-EIBRCODE to YES in APSCNTL(APCICSIN).

Parent topic: VSM- VSAM Messages


VSM-2920-00-E AMB VSAM error - control OF ENDBR and UNLOCK functions must be in USER mode to use the DDN keyword

The DDN keyword is valid only when the control variables &VS-ENDBR-CONTROL and &VS-UNLOCK-CONTROL are set to USER.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Set &VS-ENDBR-CONTROL and &VS-UNLOCK-CONTROL to the USER in APSCNTL(APVSAMIN).

Parent topic: VSM- VSAM Messages


VSM-3010-00-E For record no primary key defined

An error occurred in VS-VALIDATE-KEY. You used the default (primary key) but the data view does not have a primary key defined.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-3020-00-E Error in validate key

An error occurred in VS-VALIDATE-KEY. You used the default (primary key) but the data view does not have a primary key defined.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-4010-00-I HOLD option with single string may produce excessive code

This message occurred in VS-OBTAIN-NEXT. The developer has coded the OBTAIN-NEXT/DB-OBTAIN with the hold parameter. This informational item means that an ENDBROWSE and READ for update will be generated.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: VSM- VSAM Messages


VSM-4020-00-I RESET keyword is ignored for entry sequenced data set (ESDS) and OS sequential files

This message occurred in MVS VS-OBTAIN-NEXT. You coded the OBTAIN-NEXT/DB-OBTAIN with the RESET parameter. The RESET parameter is ignored.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-4040-00-I PROCOPT violation file

This message occurred in VS-VALIDATE-PROCOPT, where &VS-PROCOPT-WARNING = 1. You coded a VSAM call that is not allowed according to the file processing option in the data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: VSM- VSAM Messages


VSM-4050-00-W PROCOPT VIOLATION FILE file

This message occurred in VS-VALIDATE-PROCOPT and when &VS-PROCOPT-WARNING = 0. You coded a VSAM call that is not allowed according to the file processing option in the data view.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: VSM- VSAM Messages


VSM-4510-00-I AMB VSAM information - keyword keyword ignored for MVS/VSAM

The named keyword is ignored for AMB MVS/VSAM, because it has no function in the MVS VSAM environment.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: VSM- VSAM Messages


VSM-4530-00-I AMB VSAM information - KEYLENGTH specified larger than defined length - using length defined to subschema

The number specified for the KLEN keyword is greater than the length defined to the program Data View. The Data View-defined length is used.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Correct the key length specification, if necessary.

Parent topic: VSM- VSAM Messages


VSM-4540-00-I AMB VSAM information - DB-FREE ignored for MVS-VSAM

The DB-FREE call performs CICS-specific functions only and is ignored for the AMB MVS VSAM program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

No response is necessary.

Parent topic: VSM- VSAM Messages


VSM-4550-00-I AMB VSAM information - file is variable length field Must be updated with record length prior to DB-STORE and DB-MODIFY

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

For variable length files, update the named field with the calculated record length prior to executing DB-STORE and DB-MODIFY calls.

Parent topic: VSM- VSAM Messages


VSM-4560-00-I AMB VSAM information - record(s) in subschema not referenced by DB commands have been excluded from program storage

Record descriptions for files not used in a database call are not included into the program storage.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

In APSCNTL(APVSAMIN), you can modify the variable &VS-EXCLUDE-FILES to include all record descriptions, whether they are referenced or not.

Parent topic: VSM- VSAM Messages


VSM-4570-00-I AMB VSAM warning - DB-OPEN and DB-CLOSE ignored for CICS VSAM programs

DB-OPEN and DB-CLOSE calls found in a CICS program are ignored.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

These calls should not appear in a CICS program.

Parent topic: VSM- VSAM Messages


VSM-5010-00-E Record name VSAM type record only VSAM type records are supported for Micro Focus V-ISAM

Micro Focus V-ISAM supports only KSDS type records.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Use KSDS fixed length records.

Parent topic: VSM- VSAM Messages


VSM-5020-00-E VSM-5030-00-E Option is not supported by Micro Focus V-ISAM

This option is not supported by Micro Focus and is ignored.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Parent topic: VSM- VSAM Messages


VSM-5040-00-W Record name type record Only fixed length records are supported for Micro Focus PC-CICS

Micro Focus PC-CICS with V-ISAM does not support variable length records.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Change records to a fixed length.

Parent topic: VSM- VSAM Messages


VSM-5060-00-E Command is not supported by Micro Focus PC-CICS

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove this call.

Parent topic: VSM- VSAM Messages


VSM-6065-00-E Option is not supported by Micro Focus PC-CICS

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove this option.

Parent topic: VSM- VSAM Messages


VSM-8010-00-F VSMDBMAC included twice - remove the extra INCLUDE

Parent topic: VSM- VSAM Messages


VSM-8020-00-F VSMPHYS included twice-remove the extra INCLUDE

Parent topic: VSM- VSAM Messages


VSM-8200-00-F AMB VSAM fatal - APVSMDB included twice

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra INCLUDE.

Parent topic: VSM- VSAM Messages


VSM-8210-00-F AMB VSAM fatal - APVSMCIC included twice

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra INCLUDE.

Parent topic: VSM- VSAM Messages


VSM-8220-00-F AMB VSAM fatal - APVSMMVS included twice

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Remove the extra INCLUDE.

Parent topic: VSM- VSAM Messages


VSM-8230-00-F AMB VSAM command version invalid

The CARDIN variable &VS-COMMAND-VERSION was assigned an invalid value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Resolution:

Assign the proper value to &VS-COMMAND-VERSION in CNTL(APSDBDC).

Parent topic: VSM- VSAM Messages


Fields, Flags, and Exit Points

AppMaster Builder supplies you with several data fields and flags you can use to test values, to determine the validity of user-entered data, and to test for error conditions. AMB also supplies exit points you can use to customize methods.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Fields and Flags, Field Edit
    You can interrogate the following AMB-generated flags and data fields to determine input data errors when you code your application edit routines. Instructions for coding application edit routines are in online Help.
  • Fields and Flags, Invocation Modes
    Fields and flags are provided to enable you to invoke programs. These vary depending on the target.
  • Fields and Flags, VSAM Batch
    Use AMB-defined data fields and S-COBOL flags in your program.
  • Fields and Flags, VSAM Online
    Use AMB-defined data fields and S-COBOL flags in your program.
  • Flags Screen Redefinition
    During screen generation, AMB generates record definitions describing the data layout and format of a screen. You can redefine the entire generated screen record, selected tables in the screen, or selected fields in the screen by setting a flag to enable redefinition and creating user rules to generate the redefinition code.
  • Exit Points SQL
    At various program locations, you can write your own rules to customize methods. In your program, you write a rule using one of the AMB-supplied predefined rule names, and AMB automatically invokes it at its proper location. You can write rules that are automatically invoked at the beginning and end of the processing using either of these predefined rule name formats.
  • Exit Points VSAM
    At various program locations, you can write your own rules to customize methods. In your program, you write a rule using one of the AMB-supplied predefined rule names, and AMB automatically invokes it at its proper location. You can write rules that are automatically invoked at the beginning and end of the processing using either of these predefined rule name formats.
Parent topic: Reference
Related reference
APSDBDC


Fields and Flags, Field Edit

You can interrogate the following AMB-generated flags and data fields to determine input data errors when you code your application edit routines. Instructions for coding application edit routines are in online Help.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Fields:

These are the AMB-generated fields. The option Execute Before/After Edits determines which field to reference.

Representation | Execute Option | Field Name and Format
Representation | Execute Option | Field Name and Format
Input | After AMB edits | Screenname-fieldname. Internal picture was updated by any previous field edits.
Input | Before AMB edits | Screenname-fieldname-INPT. Data field containing any invalid data entered by the end user. Edits have not been performed; data is in screen input format. Field length is field length painted on the screen; definition is PIC X.
Output | After AMB Edits | Screenname-fieldname-EDIT. Data was moved to -EDIT by previous output edits. Data may contain special symbols. Default length is field length painted on the screen; definition is PIC X.
Output | Before AMB Edits | Screenname-fieldname. Data was not processed by previous output edits and is still in the internal format. Data in this field moves to the -EDIT field when an output format is specified. Default length is field length painted on the screen; definition is PIC X.
Input or Output | Before or After AMB Edits | (APS-ROW-SUB). This data field contains the row number being processed for fields in a repeated block, or in a list box or combination box.
Input or Output | Before or After AMB Edits | APS-EDIT-MESSAGE. Data field that lets you display an error message in addition to any you defined in the field edits for the field. Move a literal or data name containing the text into this field.
Input or Output | Before or After AMB Edits | Screenname-fieldname-LEN. For CICS only. Contains the length of the field; definition is PIC X.
Input or Output | Before or After AMB Edits | Screenname-fieldname-ATTR. For CICS only. Contains the attribute values assigned to the field; definition is PIC X.

Flags:

These are the AMB-generated flags:

Flag | Description
APS-EDITS-PASSED | Flag that AMB sets to T(rue) if there are no input errors and F(alse) if there are
APS-EDIT-ERRORS-CTR | Data field containing the number of screen fields in error
screenname-fieldname-FLAG | Flag that AMB sets to T(rue) if an error occurs and F(alse) if not

General Rules:

  1. AMB processes input data from the screenname-fieldname-INPT field. After the data passes the input edits, the data moves to screenname-fieldname and takes on the characteristics of the internal picture. For output, the data moves to the screenname-fieldname-EDIT field and takes on the characteristics of the output format specifications.
  2. Application edit routines execute for a field whether the data passes or fails field edits, unless you set various switches in the APFEIN control file . To indicate an error in an application edit routine, move T to screenname-fieldname-FLAG. This tells AMB to execute error processing; you can display an additional error message from the APS-EDIT-MESSAGE field.
  3. Do not code database calls in application edit routines.

Examples:

The following is sample generated code for a screen record with input and output edits.
01  EMPLOYEE-RECORD.
    05 EMPLOYEE-SALARY-GRP.
       10 EMPLOYEE-SALARY-INPT.
          15  FILLER             PIC X(03).
          15  EMPLOYEE-SALARY    PIC S9(O5)V99.
       10 EMPLOYEE-SALARY-OUTP REDEFINES
                          EMPLOYEE-SALARY-INPT.
          15  EMPLOYEE-SALARY-EDITPIC $$$,$$9.99.

The following example shows the generated code when you code an application edit routine as a subprogram. The routine:

  • Validates the customer number entered in the CUSTOMER-NO field.
  • Is invoked during field edit input logic execution.
  • Executes After AMB Edits.
  • Passes the following arguments: *CUSTOMER-NO, *CUST-NO-FLAG, APS-EDIT-MESSAGE
The edit routine uses the CUSTVER subprogram. The subprogram accepts the arguments into the Linkage Section.
CALL 'CUSTVER' USING
... SCRN-CUSTOMER-NO,
... SCRN-CUST-NO-FLAG,
... APS-EDIT-MESSAGE
Parent topic: Fields, Flags, and Exit Points


Fields and Flags, Invocation Modes

Fields and flags are provided to enable you to invoke programs. These vary depending on the target.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

  • CICS
  • IMS DC
  • DLG

CICS

To determine how to invoke a CICS program, CICS provides the following 88-level flags to indicate the mode of program invocation.

TP-INVOCATION-MODE                 PIC X(01).
    88  TP-TRANSID-INVOKED         VALUE 'T'.
    88  TP-PROGRAM-INVOKED         VALUE 'P'.
    88  TP-SCREEN-INVOKED          VALUE 'S'.
    88  TP-LINK-INVOKED            VALUE 'L'.
TP-TRANSID-INVOKED | A transaction code entered on a blank screen invokes the program.
TP-PROGRAM-INVOKED | An XCTL call from another program invokes the program.
TP-SCREEN-INVOKED | The SEND call sends the screen and a PF key or ENTER key invokes the program.
TP-LINK-INVOKED | A LINK call from another program invokes the program.

IMS DC

To determine how to invoke an IMS DC program, AMB provides the following 88-level program support variable flags.

TP-INVOCATION-MODE                 PIC X(01).
    88  TP-TRANSID-INVOKED         VALUE 'T'.
    88  TP-PROGRAM-INVOKED         VALUE 'P'.
    88  TP-SCREEN-INVOKED          VALUE 'S'.
    88  TP-LINK-INVOKED            VALUE 'L'.
TP-TRANSID-INVOKED | Provided for upward compatibility; has no function.
TP-PROGRAM-INVOKED | A LINK call from another program invokes the program.
TP-SCREEN-INVOKED | The SEND call sends the screen and a PF key or ENTER key invokes the program.
TP-LINK-INVOKED | Provided for upward compatibility; has no function.

AMB tests for a TRUE value to determine which invocation paragraph to perform.

DLG

To determine how to invoke an DLG program, AMB provides the following 88-level flags.

TP-INVOCATION-MODE                 PIC X(01).
    88  TP-TRANSID-INVOKED         VALUE 'T'.
    88  TP-PROGRAM-INVOKED         VALUE 'P'.
    88  TP-SCREEN-INVOKED          VALUE 'S'.
    88  TP-LINK-INVOKED            VALUE 'L'.
TP-TRANSID-INVOKED | Provided for upward compatibility; has no function.
TP-PROGRAM-INVOKED | A LINK call from another program invokes the program.
TP-SCREEN-INVOKED | The SEND call sends the screen and a PF key or ENTER key invokes the program.
TP-LINK-INVOKED | Provided for upward compatibility; has no function.
Parent topic: Fields, Flags, and Exit Points


Fields and Flags, VSAM Batch

Use AMB-defined data fields and S-COBOL flags in your program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Field or Flag Name | Associated Calls | Description
APS-END- PROCESS | DB-PROCESS | Flag that terminates a DB-PROCESS loop. Example: TRUE RESET-OBTAIN
ddname-RRN | DB-OBTAINDB-PROCESSDB-ERASE DB STORE | Field that controls relative record number (RRN) of a retrieved or stored RRDS file record; generates value for the RELATIVE KEY clause of the SELECT statement. Ddname is the external file name specified in the subschema. Generated field definition isddname-RRN PIC 9(09)
RESET-OBTAIN | DB-OBTAIN DB-PROCESS | Flag that resets browse to beginning of file. Example: TRUE RESET-OBTAIN

RRDS and ESDS support:

  • In RRDS processing, VSAM generates ddname-RRN, deriving the RRN (relative record number) of the current retrieved record. This allows access to a specific RRN. The field value is the RRN of each retrieved or stored record, and is updated after every successful READNEXT operation.
  • Assign a RRN value to ddname-RRN prior to a DB-STORE, if the SELECT statement ACCESS clause is either RANDOM or DYNAMIC.
  • An ESDS file is opened in I/O mode.
Parent topic: Fields, Flags, and Exit Points


Fields and Flags, VSAM Online

Use AMB-defined data fields and S-COBOL flags in your program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Field or Flag Name | Associated Calls | Description
APS- shortrecname-VAR | DB-OBTAIN DB-STORE DB-MODIFY DB-PROCESS DB-ERASE | Field that contains actual record length after a successful record retrieval (direct or sequential for DB-OBTAIN and DB-PROCESS. See Skip Sequence Processing below. Shortrecname comes from the subschema definition; it is the REC card SHORT keyword.
APS-END-PROCESS | DB-PROCESS | Flag that terminates DB-PROCESS loop. Example: TRUE RESET-OBTAIN
APS-VSAM-NUMREC | DB-ERASE | Field that contains number of records deleted after key-qualified ERASE with partial key length specified.
ddname-APS- KEYnumber | DB-OBTAIN DB-PROCESS | Field that contains AMB-generated key name for use in skip-sequential processing. See also Skip Sequence Processing below. Ddname is the subschema file. Example: ORDER-APS-KEY1
ddname-RBA | DB-OBTAIN DB-PROCESSDB-STORE | Field that contains relative byte address (RBA) of a retrieved, stored ESDS file record. See also ESDS Support and Skip Sequence Processing below. Ddname is the subschema file. Generated field definition isDdname-RBA PIC S9(08) COMP
ddname-RRN | DB-OBTAIN DB-PROCESSDB-STORE | Field that contains relative record number (RRN) of a retrieved or stored RRDS file record. See also RRDS Support and Skip Sequence Processing below. Generated field definition isDdname-RBA PIC S9(08) COMP
RESET-OBTAIN | DB-OBTAIN DB-PROCESS | Flag that resets browse to beginning of file. When used with PREV, resets to end of file. Example: TRUE RESET-OBTAIN

ESDS support:

  • Ddname-RBA provides access to a specific relative byte address (RBA). The current retrieved or written (stored) record determines the RBA; every successful READNEXT, READPREV, and WRITE operation updates the RBA.
  • DB-ERASE cannot delete a record from an ESDS file.
  • The operator must be EQUAL or = for a direct or positional DB-OBTAIN and for a qualified DB-PROCESS.
  • Assign ddname-RBA an RBA value prior to a DB-STORE or direct (key-specified) call.
  • If a key qualification specifies a non-existent RBA, the ILLOGIC condition occurs (the DB status flag AB-ON-REC). The AMB-supplied abnormal condition processing may need to be customized to access this condition.

RRDS support:

  • Ddname-RRN provides access to a specific relative record number (RRN). The current retrieved determines the RRN; every successful READNEXT and READPREV operation updates the RRN.
  • Assign ddname-RRN a RRN value prior to a DB-STORE or direct (key-specified) call.

Skip sequence processing:

Skip-sequential processing moves new key search criteria to a AMB-generated key while an active sequential DB-OBTAIN or DB-PROCESS browse is in progress. The following indicates the AMB-generated keys by target.

File Type | Record Key
KSDS | ddname-APS-KEYnumber
 | Number indicates the key number, as follows 1 = Prime record key
 | The remaining numbers correspond to the order of the DDI IDX subschema cards for that record 2 = First alternate index, 3 = Second alternate index, . . .
 | The Micro Focus FCT facility supports only one alternate index.
ESDS | ddname-RBA PIC S9(08) COMP.
RRDS | ddname-RRN PIC S9(08) COMP.

Variable length files

  • VSAM provides the APS-shortrecname-VAR field, which contains length information for variable length files, for each record definition in the subschema.
  • APS-shortrecname-VAR must be updated with the calculated record length prior to all DB-STORE and DB-MODIFY calls. For example, the following updates APS-CUST-VAR with the actual length of CUST-RECORD prior to the DB-STORE.
    APS-CUST-VAR = WS-FIXED-PORTION +
... (CUST-NBR-ORDERS * WS-OCCURS-LENGTH)
DB-STORE REC CUST-RECORD
Parent topic: Fields, Flags, and Exit Points


Flags Screen Redefinition

During screen generation, AMB generates record definitions describing the data layout and format of a screen. You can redefine the entire generated screen record, selected tables in the screen, or selected fields in the screen by setting a flag to enable redefinition and creating user rules to generate the redefinition code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Rule name suffixes:

AMB provides rule name suffixes that the flags recognize and invoke automatically. These rule name suffixes reside in the AMB CNTL file GENSYMB2. To enable a flag, set it to 1.

&SCRGEN-RDF-REC | Use for redefining an entire screen record description. The flag invokes the $screenname-RECORD-RDF rule, which you write.
&SCRGEN-RDF-TAB | Use for redefining a screen table. The flag invokes the $screenname-TABLE-n-RDF rule, which you write.
&SCRGEN-RDF-FLD | Use for redefining a screen field. The flag invokes the $screenname-fieldname-RDF rule, which you write.

User rules:

Using the USERMACS rule library, you can create a rule to redefine your screen record description. Use the following rule naming conventions:

Redefinition | Rule Name
Table in a record description | $screenname-TABLE-n-RDF Where n is the table position in sequence with other tables on the screen, counting from top to bottom on the screen.
Field in a record description | $screenname-fieldname-RDF
Entire record description | $screenname-RECORD-RDF

General Rules:

  1. When using the TP-ATTR call in a rule, use the original screen name, not the new (redefined) name.
  2. When redefining a screen, include the attribute bytes as part of the redefinition.

Examples:

Redefine field PARTNO on screen INVENT. Note that all field names within the screen are prefixed with the screen name.
% DEFINE $INVENT-PARTNO-RDF
    &12+05 INVENT-PARTNO-Z99 &36+REDEFINES INVENT-PARTNO
                            &40+PIC Z99.
Redefine a table definition for a repeat block field named PART-NO-ROW on screen INVENT. The variable &INVENT-TABLE-1-MAX contains the number of occurrences for the repeated row block. The rule $SC-REP-FIELD-HEADER-0 generates the native attribute fields depending on the DC target. The field INVENT-PART-NO-ROW-EDITED contains the picture that is used to edit the data for output display.
% DEFINE $INVENT-TABLE-1-RDF
    &12+05  FILLER  &46+REDEFINES INVENT-TABLE-1.
        &16+10  FILLER  &46+OCCURS &INVENT-TABLE-1-MAX.
            $SC-REP-FIELD-HEADER-0("PART-NO-ROW")
            &20+15  INVENT-PART-NO-ROW-EDITED  &46+PIC ZZZ9.
% END
Parent topic: Fields, Flags, and Exit Points


Exit Points SQL

At various program locations, you can write your own rules to customize methods. In your program, you write a rule using one of the AMB-supplied predefined rule names, and AMB automatically invokes it at its proper location. You can write rules that are automatically invoked at the beginning and end of the processing using either of these predefined rule name formats.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

SQL

Formats:

DB-ERASE
$D2-DB-ERASE-BEGIN-EXIT
$D2-DB-ERASE-END-EXIT
DB-MODIFY
$D2-DB-MODIFY-BEGIN-EXIT
$D2-DB-MODIFY-END-EXIT
DB-OBTAIN
$D2-DB-OBTAIN-BEGIN-EXIT
$D2-DB-OBTAIN-END-EXIT
DB-PROCESS
$D2-DB-PROCESS-BEGIN-EXIT
$D2-DB-PROCESS-END-EXIT
DB-STORE
$D2-DB-STORE-BEGIN-EXIT
$D2-DB-STORE-END-EXIT
Parent topic: Fields, Flags, and Exit Points


Exit Points VSAM

At various program locations, you can write your own rules to customize methods. In your program, you write a rule using one of the AMB-supplied predefined rule names, and AMB automatically invokes it at its proper location. You can write rules that are automatically invoked at the beginning and end of the processing using either of these predefined rule name formats.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

  • VSAM Batch
  • VSAM Online

Formats:

DB-ERASE
$VS-DB-ERASE-BEGIN-EXIT
$VS-DB-ERASE-END-EXIT
DB-MODIFY
$VS-DB-MODIFY-BEGIN-EXIT
$VS-DB-Modify-END-EXIT
DB-OBTAIN
$VS-DB-OBTAIN-BEGIN-EXIT
$VS-DB-OBTAIN-END-EXIT
DB-PROCESS
$VS-DB-PROCESS-BEGIN-EXIT
$VS-DB-PROCESS-END-EXIT
DB-STORE
$VS-DB-STORE-BEGIN-EXIT
$VS-DB-STORE-END-EXIT
Parent topic: Fields, Flags, and Exit Points


IMS Calls

AMB supports IMS calls for Character applications generating for an IMS DB target. Also supported are IMS DC fast path data communication calls for single-platform character-based applications, and system service calls for IMS DC.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • System Service Calls
    IMS system service calls:
  • $IM-FLD
    Access Main Storage Data Bases (only) at the field level, and query the field contents and subsequently change the field value.
  • $IM-FSA
    Build your own field search argument (FSA) to use with the IM-FLD call.
  • $IM-POS
    Access Data Entry Data Bases (DEDBs) only. Retrieve the location of a specific sequential dependent segment or the last inserted sequential dependent segment, or determine the amount of unused space within each DEDB area.
  • Fast Path Data Communication Calls
    Perform Fast Path data communication calls.
Parent topic: Reference


System Service Calls

IMS system service calls:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Ensure successful recovery from error conditions
  • Monitor and control database services
  • Define regular checkpoints from which you can request a service for the database and check for error conditions
  • Perform error recovery from the last successful checkpoint status check

Target:

IMS DB

Syntax:

IM-CHKP pcbname checkpointID
... [length1 dataarea1 [... length7 dataarea7

IM-XRST pcbname
... [length1 area1 [... length7 area7]]
... [checkpointID maxiolength]
IM-CHKP-OSVS pcbname checkpointID
IM-DEQ pcbname deqcharacter
IM-GSCD pcbname
IM-LOG pcbname logcode loglength message
IM-ROLB pcbname [msgarea]
IM-ROLL
IM-STAT-DBAS-FULL pcbname
IM-STAT-DBAS-UNFORMATED pcbname
IM-STAT-DBAS-SUMMARY pcbname
IM-STAT-VBAS-FULL pcbname
IM-STAT-VBAS-UNFORMATED pcbname
IM-STAT-VBAS-SUMMARY pcbname

General Rules

  1. System service calls generate Working-Storage areas as arguments.
  2. We recommend using the DB-COMMIT and DB-ROLLBACK calls instead of $IM-CHKP and $IM-ROLB.

General Rules: for Checkpoint/restart functions

  1. These calls neither redefine the IMS facilities nor change the considerations for their use. Consult your appropriate IMS reference manuals for information.
  2. Checkpoint and restart are normally not applicable to online programs. This is because the database updates associated with processing an online message represent a single work unit, which executes for only a brief period of time.
  3. Batch and BMP programs may require this facility based on the expected duration of execution, number of database updates, and the potential for conflict with other concurrent processes.
  4. Checkpoint calls establish both an IMS commit point and a place where the program can be restarted. There are two types of checkpoints
    • Symbolic checkpoints can specify up to seven data areas in the program to checkpoint. The program restarts from the last checkpoint call issued, before the abend or from a specific checkpoint named in the restart call IM-XRST. AMB restores checkpoint areas to the condition they were when the program abended.
    • Basic checkpoints do not restart the program; you must provide your own logic. No data areas can be restored.
  5. Use IM-CHKP for both symbolic and basic checkpoint processing.
  6. Use IM-XRST for symbolic checkpoint and restart processing.
  7. IM-XRST is the first IMS call executed by the program. Next, the program should interrogate the IM-XRST-AREA field (generated by this rule). If the field is not equal to spaces, perform restart processing.
  8. A checkpoint cancels all database positioning. After a checkpoint or restart, the program must reestablish the database positioning with fully qualified DB-OBTAIN calls.
  9. In batch programs, the program needs the compatibility option available in its PSB (CMPAT=YES).
  10. Symbolic checkpoints do not support OS/VS files; basic checkpoints do not support OS/VS or GSAM files.

Parameters:

checkpoint | An 8-character COBOL data name or a literal that specifies the ID for this checkpoint
dataarea | Name of the data area designated in Working-Storage
deqchara | A COBOL data name or single character literal string
length | Length of data area as defined in Working-Storage
logcode | A COBOL data name or literal character string containing a code that must be greater than or equal to X'A0' and less than or equal to X'E0'
loglength | Length of record, excluding the 5-byte header
maxiolength | Length of the largest program I/O area; can be variable or literal; default is the longest path call I/O area, or 0 if no path call exists
message | A COBOL data name or literal string
msgarea | Name of area in program where IMS returns the message segment being processed
pcbname | Data view; can be up to 20 characters; default is IO-PCB

Examples:

The following code is from a AMB batch program using a symbolic checkpoint restart:
WS     CHKPT-WORKAREAS
            CHKPT-ID
                FILLERX4 V'CID1'
                CHKPT-ID-CTR    9(4) V 0
            CHKPT-LIMIT  S9(5) V 0 COMP-3
                88 CHKPT-LIMIT-REACHED    V+50
 WS     CHECKPOINT-AREA-1
            PREV-PART-NO X8  V LOW-VALUES
 NTRY
        IM-XRST IO 8 CHECKPOINT-AREA-1
        IF NOT IM-OK
            PERFORM ERROR-PARA
 /*     IF IM-XRST-AREA IS NOT BLANK,
 /*         PROGRAM IS BEING RESTARTED
        IF IM-XRST-AREA NOT = SPACES
            MOVE IM-XRST-CHECKPOINT TO CHKPT-ID
            TRUE RESTART
        ELSE
 /*         PERFORM FIRST CHECK POINT
            PERFORM SYMB-CHKPT-RTN
        REPEAT
            PERFORM READ-DB
        UNTIL END-ON-REC
            PERFORM PROCESS-DB-REC
 /*         INCREMENT COUNTER FOR EACH RECORD READ
            CHKPT-LIMIT = CHKPT-LIMIT + 1
            IF CHKPT-LIMIT-REACHED
                PERFORM SYMB-CHKPT-RTN
 PARA   SYMB-CHKPT-RTN
 /*     INCREMENT CHKPT-ID CNTR
        CHKPT-ID-CTR = CHKPT-ID-CTR + 1
        IM-CHKP IO CHKPT-ID
        ... 8 CHECKPOINT-AREA-1
        IF NOT IM-OK
            PERFORM ERROR-PARA
        CHKPT-LIMIT = 0
The following code:
$IM-CHKP ("IO", "'MYCHKP'", 25, "AREA-1",
% ... 37, "AREA-2")
$IM-CHKP ("IO", "MY-BASIC-CHKP-NAME")
$IM-XRST ("IO", 25, "AREA-1")
Generates in Working-Storage:
01  IM-CBLTDLI-ARGUMENTS.
    05  IM-CHKP             PIC X(4) VALUE 'CHKP'.
    05  IM-DEQ              PIC X(4) VALUE 'DEQ '.
    05  IM-LOG              PIC X(4) VALUE 'LOG '.
    05  IM-STAT             PIC X(4) VALUE 'STAT'.
    05  IM-XRST             PIC X(4) VALUE 'XRST'.
    05  OSVSCHKP            PIC X(8) VALUE'OSVSCHKP'.
    05  IM-CALL-FUNCTION    PIC X(4).
    05  IM-IO-AREA-LEN      PIC S9(9) COMP VALUE +0.
    05  IM-IO-MAXAREA-LEN   PIC S9(9) COMP VALUE +0.
    05  IM-LEN-25           PIC S9(9) COMP VALUE +25.
    05  IM-LEN-37           PIC S9(9) COMP VALUE +37.
01  IM-LOG-AREA.
    05  IM-LOG-LEN          PIC S9(4) COMP.
    05  FILLER              PIC S9(4) COMP VALUE +0.
    05  IM-LOG-CODE         PIC X.
    05  IM-LOG-RECORD       PIC X(55).
01  IM-DEQ-CHR   PIC X.
01  IM-XRST-AREA.
    05  IM-XRST-CHECKPOINT  PIC X(8).
    05  FILLER              PIC X(4) VALUE SPACES.
01  IM-CHECKPOINT-ID        PIC X(8).
01  IM-STAT-FUNCTION.
    05  FILLER              PIC X(4).
    05  IM-STAT-FORMAT      PIC X.
    05  FILLER              PIC X(4).
01  IM-STATISTICS  PIC X(120).
Generates in the Procedure Division:
MOVE 'MYCHKP' TO IM-CHECKPOINT-ID
IF IM-IO-MAXAREA-LEN < IM-IO-AREA-LEN
    MOVE IM-IO-AREA-LEN
... TO IM-IO-MAXAREA-LEN
CALL 'CBLTDLI' USING
... IM-CHKP IO-PCB
... IM-IO-MAXAREA-LEN
... IM-CHECKPOINT-ID
... IM-LEN-25 AREA-1
... IM-LEN-37 AREA-2
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE MY-BASIC-CHKP-NAME
... TO IM-CHECKPOINT-ID
CALL 'CBLTDLI' USING
... IM-CHKP IO-PCB
... IM-CHECKPOINT-ID
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE 'MYOSVSCP'
... TO IM-CHECKPOINT-ID
CALL 'CBLTDLI' USING
... IM-CHKP IO-PCB
... IM-CHECKPOINT-ID
... IM-OSVSCHKP
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE 'A' TO IM-DEQ-CHR
CALL 'CBLTDLI' USING
... IM-DEQ IO-PCB
...IM-DEQ-CHR
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
COMPUTE IM-LOG-LEN = 38 + 5
MOVE LOG-CODE-1 TO IM-LOG-CODE
MOVE LOG-MESSAGE-1
... TO IM-LOG-RECORD
CALL 'CBLTDLI' USING
... IM-LOG IO-PCB
... IO-LOG-AREA
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
COMPUTE IM-LOG-LEN = 55 + 5
MOVE LOG-CODE-2 TO IM-LOG-CODE
MOVE LOG-MESSAGE-2
... TO IM-LOG-RECORD
CALL 'CBLTDLI' USING
... IM-LOG IO-PCB
... IO-LOG-AREA
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
MOVE 'VBAS'
... TO IM-STAT-FUNCTION /* CLR TAIL
MOVE 'S' TO IM-STAT-FORMAT
CALL 'CBLTDLI' USING
... IM-STAT BE1PARTS-PCB
... IM-STATISTICS
... IM-STAT-FUNCTION
MOVE BE1PARTS-PCB-STATUS
... TO IM-STATUS
MOVE BE1PARTS-PCB
... TO IM-DB-PCB
MOVE SPACES
... TO IM-XRST-AREA
IF IM-IO-AREA-LEN > IM-IO-MAXAREA-LEN
    MOVE IM-IO-AREA-LEN
... TO IM-IO-MAXAREA-LEN
CALL 'CBLTDLI' USING
... IM-XRST IO-PCB
... IM-IO-AREA-LEN
... IM-XRST-AREA
... IM-LEN-25 AREA-1
MOVE IO-PCB-STATUS
... TO IM-STATUS
...    TP-STATUS
Parent topic: IMS Calls


$IM-FLD

Access Main Storage Data Bases (only) at the field level, and query the field contents and subsequently change the field value.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

IMS DC

Syntax:

$IM-FLD MSDBview fsaname [rootssa]

Parameters:

fsaname | COBOL dataname for the generated field search argument.
MSDBview | Main Storage Data Base PCB
rootssa | Root segment search argument; if not specified, AMB retrieves the first segment in the MSDB.

Comment:

Refer to your IMS documentation for more information on $IM-FLD.

Parent topic: IMS Calls


$IM-FSA

Build your own field search argument (FSA) to use with the IM-FLD call.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

IMS DB

Syntax:

$IM-FSA fsaname segment
... [field1[/picture/] operator operand1
... [field2[/picture/] operator operand2]
                .
                .
 ... [field10[/picture/[ operator operand10]

Parameters:

field | Segment field name; can be 8-character IMS field name or the corresponding COBOL record name.
fsaname | COBOL data name for the generated FSA; references the FSA in $IM-FLD.
operand | Value to test against field in a field verify, or actual field value in a field change.
operator | Valid operators for a field verify are: E Verify that field and operand are equal. G Verify that field is greater than operand. H Verify that field is greater than or equal to operand. L Verify that field is less than operand. M Verify that field is less than or equal to operand. N Verify that field is not equal to operand.
 | Valid operators for a field change are: + Add operand from field. - Subtract operand from field. = Set field to value of operand
picture | COBOL picture; if not specified, AMB calculates picture from field length and field type.
segment | The segment referenced by the FSA; can be eight-character IMS segment name or the corresponding COBOL field name.

Comments:

Refer to your IMS documentation for more information on $IM-FSA.

Parent topic: IMS Calls


$IM-POS

Access Data Entry Data Bases (DEDBs) only. Retrieve the location of a specific sequential dependent segment or the last inserted sequential dependent segment, or determine the amount of unused space within each DEDB area.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

IMS DB

Syntax:

$IM-POS DEDBview [SSA]

Parameters:

DEDBview | Data Entry Data Base PCB
SSA | Segment Search Argument, which triggers COBOL MOVEs to or from the generated I/O area IM-IO-AREA; default is IM-IO-AREA with a length of 32,000 bytes. To override the length, set IM-IO-AREA-LEN in your program or DDISYMB member.
 | Specify only one SSA per hierarchical level along a path. These arguments generate 8-byte records in Working Storage to hold the corresponding values.

Comments:

  • After an IM-POS call successfully executes, information returns in the field IM-POS-IO-AREA, which is defined 01 IM-POS-IO-AREA.
        05  IM-POS-LENGTH                 PIC S9(04) COMP.
    05  IM-POS-DATA-AREA-PONAME  OCCURS 240.
        10  IM-POS-AREA-DDNAME        PIC X(08).
        10  IM-POS-INFO
            15  IM-POS-CYCLS-COUNT    PIC S9(8) COMP.
            15  IM-POS-VSAM-RBA       PIC S9(8) COMP.
        10  IM-POS-UNUSED-SEQDEP-CIS  PIC S9(8) COMP.
        10  IM-POS-UNUSED-INDEP-CIS   PIC S9(8) COMP.
  • Refer to your IMS documentation for more information on $IM-POS.
Parent topic: IMS Calls


Fast Path Data Communication Calls

Perform Fast Path data communication calls.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

IMS DC for single-platform applications

Syntax:

$IM-CHNG altview [destination]
$IM-CMD [PCBname] [msgarea]
$IM-GCMD [PCBname] [msgarea]
$IM-GN PCBname SSA1 [... SSA15]
$IM-GU PCBname SSA1 [... SSA15]
$IM-ISRT [PCBname]altview] SSA1 [... SSA15]
$IM-PURG [PCBname] [msgarea] [mod]

Parameters:

altview | Alternate view or IO PCB name.
destina-tion | Terminal destination; can be data name or literal in an 8-byte field.
msgarea | Area where IMS returns the message segment being processed; AMB treats this area as the first segment of a new message.
mod | Data name or literal in an 8-byte field naming the message output description.
pcbname | Data view (maximum 20 characters); default is IO-PCB.
SSA | Segment Search Argument, which triggers COBOL MOVEs to or from the generated I/O area IM-IO-AREA; default is IM-IO-AREA with a length of 32,000 bytes. To override the length, set IM-IO-AREA-LEN in your program or the DDISYMB member.
 | Specify only one SSA per hierarchical level along a path. These arguments generate 8-byte records in Working-Storage to hold the corresponding values.

Examples:

The following code:
$IM-CHNG ("ALT-IO", "YOUR-TERMINAL-NAME")
Generates in Working-Storage:
01  IM-DESTINATION-NAME    PIC X(8).
Generates in the Procedure Division:
MOVE YOUR-TERMINAL-NAME
... TO IM-DESTINATION-NAME
CALL 'CBLTDLI' USING
... IM-CHNG ALT-IO-PCB
... IM-DESTINATION-NAME
MOVE ALT-IO-STATUS
... TO IM-STATUS
The following code:
$IM-CHNG ("AOT-IO", "'YOURTERM'")
Generates in Working-Storage
01  IM-DESTINATION-NAME    PIC X(8).
Generates in the Procedure Division
 MOVE 'YOURTERM'
 ... TO IM-DESTINATION-NAME
 CALL 'CBLTDLI' USING
 ... IM-CHNG ALT-IO-PCB
 ... IM-DESTINATION-NAME
 MOVE ALT-IO-STATUS
 ... TO IM-STATUS
Parent topic: IMS Calls


Libraries and Directories

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AppMaster Builder provides several directories to house files of interest to AMB users.

  • AMB Generator Rule Library (APSMACS)
  • User Area Directories
  • Project Files and Directories
Parent topic: Reference
Related concepts
Generating Code


AMB Generator Rule Library (APSMACS)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The APSMACS rule library is contained in a subdirectory to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc (Windows) or $COBDIR/etc (UNIX) directory.

Rule Name | Usage
A1UXAP01 | Application View User Exit
APAUTOED | Automatic Edits
APBTCHTP | Batch Generator
APCICSTP | CICS Generator
APDB2DB | SQL Generator
APDLGMAC APDLGTP | DLG Generator
APFEDCLR APFEMACS | Field Edits
APHLPMAC | Online Help
APIMSDB | IMS DB Generator
APIMSTP | IMS/TM Generator
APMSGADB | Database Generator Errors
APMSGAPX | Online Express Messages
APMSGBTC | Batch Generator Messages
APMSGCIC | CICS Messages
APMSGDB2 | SQL Generator Messages
APMSGDCL | IMS Database Messages
APMSGDLG | DLG Messages
APMSGIMS | IMS Generator Messages
APMSGISP | ISPF Generator Messages
APMSGMDC | TP Messages (CICS, IMS, ISPF)
APMSGVSM | VSAM Generator Messages
APSBASE | AMB Base
APSCRGEN | Screen Generator
APSDBCMD | Database Generator
APSUBSCH | Subschema Processor
APVSMCIC | VSAM Generator (CICS only)
APVSMDB | VSAM Generator (all platforms)
APVSMMVS | VSAM Generator (batch)
APXMACS APXPRESS | Online Express Generator
DCLMACS | IMS DB and VSAM Generator
DDIAMS | VSAM IDCAMS Generator (mainframe only)
DXPG02 | PG02 (Program Painter) Report Generator
IMSDBMAC IMSPHYS | IMS DB Generator
PROGXML | XML Generator
PXMSGS | Online Express Messages
SCRDCLR | Screen Generator
SQLBUILD | SQL Migration Generator
SSMXPG02 | PG02 (Program Painter) Report Generator
VSMDBMAC | VSAM Generator
VSMPHYS | VSAM Generator (all platforms)
Note: You can copy and customize any member of this library to suit your programming needs.
Parent topic: Libraries and Directories


User Area Directories

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following user area directories are subdirectories of your specified User Area, which by default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\AMBWorkArea\user-id.

Directory | Description
APSFTWRK | Contains all job control work files
APSWRK | ISPF Editor work area
JOBQUEUE | Area for batch execution results
PDSPXWRK | Editor work area
TESTLIB | Contains generated COBOL programs, MFS, BMS, and PSB files
Parent topic: Libraries and Directories
Related concepts
AppMaster Builder User Areas
Related tasks
To view generated code
To create a user area
To delete a user area
To clean a user area


Project Files and Directories

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Project files and directories are subdirectories of your AppMaster Builder project directory.

Directory | Description
APRAPPL | Required by Project Explorer
APRINV | Required by the Documentation Facility, to enable generation of reports MD01, EN01, and GS01
APRPROG | Required by Program Painter
APSAPPL | Required by Project Explorer
APSDATA | Required by Data Structure Editor
APSEXPS | Required by Online Express
APSPROG | Required by Program Painter
APSREPT | Required by Report Painter
  • APSSCFE
  • APSSCRN
Required by Screen Painter
APSSRC | Source coded outside the AMB painters is stored in APSSRC. Because the source must be coded in strict AMB S-COBOL syntax, it must therefore be processed by the AMB Precompiler.
APXAPPL | Contains XML files used by the AMB Analysis Option
APXPROG | Contains program inventory files
CNTL | User control statements.
  • COBCICS
  • COBDLG
  • COBIMS
  • COBMVS
Resolved COBOL output from AMB precompiler.
COPYLIB | Standard COBOL copybooks
DBDSRC | DBD source data
DDIFILE | Current copy of DDIFILE
DDISRC | DDI source data
DDISYMB | Symbol output from data base definitions and creation
FMPOUT | Required by AMB generators
  • GENBMS
  • BENDLG
  • GENFMS
Panel output from AMB generators.
GENSRC | Generated S-COBOL code
PSBSRC | PSB source data
  • SCRCOPY
  • SCRSYMB
Required by AMB Screen Painter
  • SQLDDL
  • SQLGEN
Required for SQL DDL Importer
SQLSCHEM
USERMACS | Rules created by AMB users
Parent topic: Libraries and Directories
Related tasks
To view project files
Related reference
Control (CNTL) Files


Program Painter Keywords

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Purpose:

Program Painter keywords designate program Divisions and Sections. The keyword you choose determines the location of your program code within the generated program.

Program Painter keywords also designate blocks of code within which all other categories of AMB structures are coded. Following any keyword, you can enter

  • Program code, including COBOL and S-COBOL structures; database and data communication calls
  • Data structures
  • Report Writer structures
  • User-defined rules

Code keywords in the Program Painter for batch, report, or complex online programs, or Online Express.

Program Painter keywords:

The following lists the keywords and their logical placement in a program.

Location | Keyword
Beginning of program | SYM1 | Define rule variables.
 | SYM2 | Call user-defined rules after any rule libraries named in Project Explorer.
IDENTIFICATION DIVISION | REM | Create COBOL comments in the Considerations Section. Not valid for COBOL II.
ENVIRONMENT DIVISION | SPNM | Create Special-Names paragraph
 | SYEN | Call user-defined rules in Special-Names paragraph.
Input/Output Section | SYIO | Call user-defined rules after any rule libraries.
 | IO | Code SELECT statement.
DATA DIVISION | SYDD | Call user-defined rules at the beginning of the Data Division.
File Section | SYFD | Call user-defined rules after any rule libraries included.
 | FD SD | Code File Description or Sort Description statement.
Record description | 01 | Code record description in COBOL format.
 | DS | Specify name of data structure defined in Data Structure Editor containing record description.
 | REC | Specify name of data structure defined in Data Structure Editor containing record description. Structure must be coded in Data Structure Editor format (see Data Structures).
Working-Storage Section | SYWS | Call user-defined rules after any rule libraries and data structures named in Project Explorer.
 | WS | Designate Working-Storage section.
Data definitions | 01 | Code data structure in COBOL format.
 | DS | Specify name of data structure defined in Data Structure Editor containing data definition.
 | REC | Specify name of data structure defined in Data Structure Editor containing data definition. Structure must be coded in Data Structure Editor format (see Data Structures).
 | ++ | Character-based applications only. Specify PANVALET member name containing data definition.
 | SQL | Designate DB2 table or cursor.
Linkage Section | SYLT | Call user-defined rules after any rule libraries and data structures named in the Project Explorer and preceding any SYLK code.
 | SYLK | Call user-defined rules after any rule libraries and data structures named in the Project Explorer.
 | LK | Designate Linkage Section.
Data definitions | 01 | Code data structure in COBOL format.
 | DS | Specify name of data structure defined in Data Structure Editor containing data definition.
 | REC | Specify name of data structure defined in Data Structure Editor containing data definition. Structure must be coded in Data Structure Editor format (see Data Structures).
 | ++ | Character-based applications only. Specify PANVALET member name containing data definition.
 | SQL | Designate DB2 table or cursor.
Report Section | SYRP | Call user-defined rules after any rule libraries.
 | RED | Create a Report Section and specify the report name.
 | MOCK | Identify the report mock-up.
 | 01 | Specify the type of report line, such as header, footer, detail.
PROCEDURE DIVISION | NTRY PROC | Designate the Procedure Division; generate program skeleton and program invocation logic.
 | OPT | Suppress generation of program invocation logic.
 | PARA | Designate S-COBOL or COBOL paragraph.
 | STUB | Name the global code to be inserted.
Declaratives Section | DECL | Create a Declarative Section without paragraphs; code declarative statements.
 | DPAR | Create a Declarative Section paragraph; code declarative paragraph statements.
Bottom of program | SYBT | Call user-defined rules.
Anywhere in the program | /* | Code comments. The /* keyword does not end the action of the current keyword; the next keyword ends the current one.
 | FRFM | Pass associated COBOL or S-COBOL statements through the generator without translation and move the statements four columns to the left.

Coding Conventions:

  • Code keywords in the Program Painter for batch, report, or complex online programs, or in Online Express.
    Note: A keyword is active until the appearance of another keyword, except for the comment keyword.
  • You can code keywords in any sequence. Remember, keywords designate blocks of logically related statement blocks and the action of one keyword is terminated by the appearance of the next keyword. The AMB generators use these keywords to arrange the program according to COBOL program requirements.

Pass-Through Keyword:

The SQL keyword enables you to code and pass through native SQL calls, without translation, to the precompile process.

Examples:

The following examples include all AMB keywords that you can enter in the Program Painter when creating online or batch programs. They illustrate:

  • The program locations where each keyword places the source code after you generate the program through AMB to produce an executable COBOL program.
  • The program locations at which AMB places externally-defined components associated with your program, such as user-defined rules and data structures that you list on the Project Explorer.

Online programs:

*SYM1 keyword places Customizer code here
*user rules from Appl View where Location=Top of program
*SYM2 keyword places Customizer code here
 IDENTIFICATION DIVISION.
          .
          .
          .
*/* keyword places comments here
 REMARKS.  REM keyword places comments here (COBOL)
 ENVIRONMENT DIVISION.
          .
          .
          .
 SPECIAL-NAMES.  SPNM keyword places code here
*SYEN keyword places Customizer code here
 DATA DIVISION.
*SYDD keyword places Customizer code here
 WORKING-STORAGE SECTION.
*user rules from Appl View where Location=Top of W-S
*data structures from from Appl View where Location=Top of W-S
*user rules from Appl View where Location=Working-Storage
*SYWS keyword places Customizer code here
*WS  keyword, followed by any of the following six
*    keywords that you enter on the next line
*01   keyword
*REC  keyword
*DS   keyword
*SQL  keyword
*FRFM keyword
*user rules from Appl View where Location=Bottom of W-S
*CA, CA05, CADS keywords place code here in CICS, IMS,
*    DLG parent pgms
 LINKAGE SECTION.
*user rules from Appl View where Location=Top of Linkage
*data structures from Appl View where Location=Linkage Section
*user rules from Appl View where Location=Linkage Section
*SYLT keyword places Customizer code here
*SYLK keyword places Customizer code here
*LK  keyword, followed by any of the following six
*    keywords that you enter on the next line
*01   keyword
*DS   keyword
*REC  keyword
*SQL  keyword
*FRFM keyword
*CA, CA05, CADS keywords place code here in DLG child programs
*user rules from Appl View where Location=Bottom of Linkage
 PROCEDURE DIVISON.  NTRY|PROC keyword generates this stmt
*OPT keyword places code here
          .
          .
          .
*PARA keyword places code here
          .
          .
          .
*STUB keyword places code here
          .
          .
          .
*user rules from Appl View where Location=Bottom of program
*SYBT keyword places Customizer code here
*End of program.

Batch programs:

*SYM1 keyword places Customizer code here
*user rules from Appl View where Location=Top of program
*SYM2 keyword places Customizer code here
 IDENTIFICATION DIVISION.
          .
          .
          .
*/* keyword places comments here (COBOL II)
 REMARKS.  REM keyword places comments here (COBOL)
 ENVIRONMENT DIVISION.
          .
          .
          .
 SPECIAL-NAMES.  SPNM keyword places code here
*SYEN keyword places Customizer code here
 INPUT-OUTPUT SECTION.
*user rules from Appl View where Location=Top of I/O Section
*SYIO keyword places Customizer code here
 FILE-CONTROL.
*IO   keyword places code here
          .
          .
          .
 DATA DIVISION.
*SYDD keyword places Customizer code here
 FILE SECTION.
*user rules from Appl View where Location=Top of File Section
*FD keyword places code here
*SD keyword places code here
 WORKING-STORAGE SECTION.
*user rules from Appl View where Location=Top of W-S
*data structures from from Appl View where Location=Top of W-S
*user rules from Appl View where Location=Working-Storage
*SYWS keyword places Customizer code here
*WS  keyword, followed by any of the following six
*    keywords that you enter on the next line
*01   keyword
*REC  keyword
*DS   keyword
*SQL  keyword
*FRFM keyword
*user rules from Appl View where Location=Bottom of W-S
 LINKAGE SECTION.
*user rules from Appl View where Location=Top of Linkage
*data structures from Appl View where Location=Linkage Section
*user rules from Appl View where Location=Linkage Section
*SYLT keyword places Customizer code here
*SYLK keyword places Customizer code here
*LK  keyword, followed by any of the following six
*    keywords that you enter on the next line
*01   keyword
*DS   keyword
*REC  keyword
*SQL  keyword
*FRFM keyword
*user rules from Appl View where Location=Bottom of Linkage
 PROCEDURE DIVISON.       /*NTRY keyword generates this stmt
 PROCEDURE DIVISON USING. /*PROC keyword generates this stmt
 DECLARATIVES.          /* DECL keyword generates this stmt
 DECLARATIVES SECTION.  /* DPAR generates this stmt
*DPAR keyword places code here
 END DECLARATIVES.
*OPT keyword places code here
          .
          .
          .
*PARA keyword places code here
          .
          .
          .
*STUB keyword places code here
          .
          .
          .
*user rules from Appl View where Location=Bottom of program
*SYBT keyword places Customizer code here
*End of program.
  • Program Painter Keywords - All Applications
    The following comments and examples apply to all Program Painter Keywords.
  • /* (Comments)
    Enter comments in your program. To code comments in the Identification Division, see REM.
  • ++
    Generate a PANVALET ++INCLUDE statement.
  • &&
    Continue a Customizer argument on another line.
  • 01
    Use the 01 keyword to:
  • CA, CA05, and CADS
    Redefine the the Commarea to pass data between programs. See TP-COMMAREA.
  • DECL
    Create Declaratives Section statements only--not sections or paragraphs.
  • DPAR
    Create a Declaratives Section paragraph or section--not declarative statements.
  • DS
    In your program, include a data structure created in the Data Structure Editor and in that format.
  • FD
    Define the file descriptions for input and output files, including report files.
  • FRFM
    Pass COBOL or S-COBOL statements to the AMB generator without translation, in a freeform manner, and insert the statements in the program section where they are coded.
  • IO
    Generate the Input-Output Section File-Control paragraph.
  • LK
    Create or include data structures in the Linkage Section.
  • MOCK
    Specify the report mock-up name in your report program.
  • NTRY
    Generate a program template that fully defines all parts of your program except for the procedural code that you supply.
  • OPT
    Suppress the mainline program section generated by the NTRY or PROC keyword, in order to supply your own screen and program invocation logic. Use OPT only in online programs with screens.
  • PARA
    Indicate a paragraph in your program code. A paragraph is a Procedure Division routine that you write and perform specifically for one program. Use paragraphs to perform the following, depending on which AMB tool you use
  • PROC
    Generate the batch program template, including a PROCEDURE DIVISION USING clause that enables a called program to receive data from the calling program.
  • REC
    Define a data structure in the Data Structure Editor format.
  • RED
    Name and begin the statement block that defines the report; identify the report name, control fields, and report page characteristics.
  • REM
    Create Identification Division Remarks text.
  • SD
    Include a sort file description.
  • SPNM
    Create a Special-Names paragraph in the generated program.
  • SQL
    Designate a DB2 table or cursor declaration in the Working-Storage or Linkage Section. Additionally, code native SQL statements and pass them through, without translation, to the precompile process.
  • STUB
    Include in a program a custom source code module that you named in the Project Explorer.
  • SY*
    Specify in a AMB program the location where the generator places source code.
  • WS
    Define or include data structures in the Working-Storage Section.
Parent topic: Reference
Related concepts
Local Program Code
Program Painter
Program Template for Online Applications
Coding Programs
Structure Summary
Related tasks
To code Identification Division comments in the Program Painter
To code an Environment Division Special-Names statement
To code Working-Storage structures
To define data structures in COBOL format
To define data structures in Data Editor format
To include a copyfile
To include a global or local data structure
To define a DB2 table declaration and cursor declarations
To code Linkage Section structures
To define or redefine the Commarea
To begin the Procedure Division for online programs
To code the Procedure Division
To code Procedure Division comments
To define the Input-Output Section
To create a User Rule
To update a User Rule
Related reference
Coding Options
Data Structures


Program Painter Keywords - All Applications

The following comments and examples apply to all Program Painter Keywords.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Comments:

Code an NTRY, PROC, or OPT statement for each program.

  • To generate a batch program template with a PROCEDURE DIVISION USING statement, code PROC .
  • The generated $TP-ENTRY generates a program template to send the appropriate window depending on the program invocation mode. To suppress the window and program invocation logic from your program template, code OPT PROG .

Examples:

Generate code to receive screen SCRA when the program is screen-invoked. Specify that the program can receive a screen that contains invalid data. Omit the error paragraph.

 NTRY   SCRA * NORETRY

Receive multiple screens and include an error routine. Note that when you use SCRNLIST, you do not specify any screens in the NTRY statement.

 SYM1   SCRNLIST C1ORDR C2ORDR C3ORDR
 NTRY   * PROCESS-ERRORS
Parent topic: Program Painter Keywords
Related reference
OPT
PROC


/* (Comments)

Enter comments in your program. To code comments in the Identification Division, see REM.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1, code anywhere in your program

 /*     commentline

Syntax: for Format 2, code in the Procedure Division only

        /*commentline

Syntax: for Format 3, code in the Procedure Division only

program-code /*comment

Syntax: for Format 4, code in Customizer rules

%* comment

Syntax: for Format 5, code in the Data Structure Editor only

* comment
/* comment
%* comment

Comments:

  • Comment lines do not affect the function of a program or data structure. In the Program Painter, the last keyword entered before your comment line(s) is still in effect.
  • You cannot code comments within database calls, user interface calls, or Data Structure Editor constructs.
  • Do not use evaluation brackets in Formats 2, 3, and 4.
  • Begin each comment line with /* or %*.
  • In the Procedure Division, you can code /* anywhere in the column 12 - 72 area.
  • A Customizer comment (Format 4) can start in any column, as long as it is on a line by itself and is indented (we recommend four spaces) underneath the Customizer statement.

Examples:

In the Program Painter:

002000         /* S-COBOL COMMENT LINE
002010  /*     COBOL COMMENT LINE
002020  PARA   MAIN-PARA   /* S-COBOL COMMENT

In the Data Structure Editor:

-LINE- -------- Data Structure Editor -------
000001         /* WORK FIELD 1 RECORD
000002         WRK1-FIELD-1    X(5)
000003             88 OPEN-VAL   V'OPEN'
000004             88 CLOSED-VAL V'CLOSE'

Generated COBOL code:

000001  */* WORK FIELD 1 RECORD
000002   01  WRK1-FIELD-1    PIC X(5).
000003       88  OPEN-VAL    VALUE 'OPEN'.
000004       88  CLOSED-VAL  VALUE 'CLOSE'.
Parent topic: Program Painter Keywords
Related tasks
To code Identification Division comments in the Program Painter
To code Procedure Division comments
Related reference
REM


++

Generate a PANVALET ++INCLUDE statement.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 ++     PANVALETmembername

Comments:

The preceding section keyword determines the placement of a data structure in the generated program. Associated section keywords are

FD | File Section (see FD)
SD | Sort File Description (see SD)
LK | Linkage Section (see LK )
WS | Working-Storage Section (see WS)

Examples:

 WS
 REC    WS-INPUT-REC
          WS-IN-PART-NO       N8
          WS-IN-DESC          X50
          WS-IN-BASE-PRICE    N6V2
 01     WS-OUT-REC.
 DS05   WSOUTREC
 ++     PANWSREC
Parent topic: Program Painter Keywords
Related reference
FD
SD
LK
WS


&&

Continue a Customizer argument on another line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

macroname argumentpart1
...&& argumentpart2

Comment:

You can continue a Customizer argument on as many lines as necessary.

Example:

Program Painter code:

   SYM1     % DEFINE $USER-MACRO(&ARG1, &ARG2, &ARG3, &ARG4)
                 DISPLAY <&SQ><%&ARG1><&SQ>

               USER-MACRO  A_LONG_ARGUMENT_THAT_NEEDS_TO_BE_CONTINUED_ON
               ... && THE_NEXT_
               ... && LINE

Generated code:

   DISPLAY  'A_LONG_ARGUMENT_THAT_NEEDS_TO_BE_CONTINUED_ON_THE_NE
   -    'XT_LINE'
Parent topic: Program Painter Keywords
Related reference
Customizer/Micro Focus Generator (MFG)


01

Use the 01 keyword to:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Define the input and output files in a batch program File Section.
  • Define a data structure in Working-Storage or Linkage Section.
  • Copy a data structure into the Working-Storage or Linkage Section.
  • Define AppMaster Builder Report Writer statements for headings, footers, or detail lines.

Syntax: for Format 1, define input or output files

 IO     filename ASSIGN [TO] ...
        ORGANIZATION IS ...
 01     input|outputrecordname         PIC clause

Syntax: for Format 2, define a data structure

 01     COBOLdatastructure
        [05  COBOLdatastructure]

Syntax: for Format 3, copy a data structure

 01     COBOLcopystatement

Syntax: for Format 4, define Report Writer line types

 01    [dataname] TYPE [IS] reportgroup
       [NEXT GROUP [IS] number|PLUS number|NEXT PAGE][.]
       [LINE [NUMBER IS] number|PLUS number|NEXT PAGE]
       MOCKUP|M LINE|LINES linenumber1 [THRU linenumberN]
       [O[VERPRINT] WHEN "characterstring" AT COLUMN column]
       [S[OURCE] [IS] dataname [options]]
       [V[ALUE] [IS] literal]
       [R[EFERENCE [IS] dataname PIC[TURE] [IS] picclause
           [options]]
        [SUM|+ [IS] dataname [dataname] ...
            [UPON detailgroup [detailgroup] ...]
            [RESET [ON] [FINAL] dataname]
            [options]]

Comments:

  • You must provide all necessary COBOL punctuation.
  • The following COPY statement formats are available for OS/VS COBOL. They are not supported by other versions of COBOL, where the LANGLVL compiler option is set to 1.
     01     COPY copybookname
 01     dataname COPY copybookname
 01     dataname
            COPY copybookname
 01     dataname COPY copybookname
            REPLACING fieldname1 BY fieldname2

    To write subordinate elementary data elements, include the level numbers in columns 12 - 72.

  • If you are using a non-OS/VS version of COBOL, or your copybook contains an indexed table, enter the SWYS or SYLK keyword in the KYWD column and the % INCLUDE statement, rather than a COBOL COPY statement. % INCLUDE inserts the copybook into the program before precompilation, so the AppMaster Builder Precompiler can interpret the index. The preceding section keyword determines the placement of a data structure in the generated program. Associated section keywords are:
    FD | File Section (seeFD )
    SD | Sort File Description (see SD)
    LK | Linkage Section (see LK)
    WS | Working-Storage Section (see WS)
Parent topic: Program Painter Keywords
Related tasks
To define data structures in COBOL format
To define the Input-Output Section
To include a copyfile
To identify report groups
Related reference
FD
SD
LK
WS
% INCLUDE
SY*


CA, CA05, and CADS

Redefine the the Commarea to pass data between programs. See TP-COMMAREA.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

 CA     datastructure

Syntax: for Format 2

 CA05   COBOLdatastructure

Syntax: for Format 3

 CADS   datastructurename

Comments:

  • All formats generate an 05-level REDEFINES TP-USERAREA for the TP-USERAREA data structure and all other data elements at the same indentation level.
  • When using Formats 1 and 3, code the data structure in the Data Structure Editor format; when using Format 2, code in COBOL format.
  • A CA keyword is invalid in a batch program.
  • &TP-USER-LEN controls the size of TP-USERAREA. Change the size of this area by coding % &TP-USER-LEN=nnn, with a length greater than zero. Code this variable with the SYM1 or SYM2 keyword.

Examples:

 IO     INPUT-FILE ASSIGN TO UT-S-INPUT
 IO     OUTPUT-FILE ASSIGN TO UT-S-OUTPUT
 FD     INPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 01     INPUT-REC        PIC X(80).
 DS01   INPUTREC
 FD     OUTPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 REC    OUTPUT-REC       X80
 01     OUTPUT-REC-R REDEFINES OUTPUT-REC.
        ...COPY OUTREC.
 CA     CA-INPUT-REC
          CA-IN-PART-NO       N8
          CA-IN-DESC          X50
          CA-IN-BASE-PRICE    N6V2
 CADS   CAOUTREC
Parent topic: Program Painter Keywords
Related concepts
Commarea Storage
Related tasks
To define or redefine the Commarea
Related reference
TP-COMMAREA


DECL

Create Declaratives Section statements only--not sections or paragraphs.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

See also DPAR and USE BEFORE REPORTING for creating Declarative Section statements, paragraphs, and sections.

Targets:

  • CICS programs without screens
  • IMS DC programs without screens
  • DLG batch programs

;

Syntax:

 DECL   declarativestatements

Comments:

  • Do not code the DECLARATIVES SECTION header or the END DECLARATIVES statement. AMB generates these for you.
  • We recommend that you code declaratives at the end of your program, because AMB generates the END DECLARATIVES statement when either:
    • It encounters another keyword in the KYWD column.
    • The Declaratives Section is at the end of the program.

Examples:

 DECL   declarative statement
        declarative statement

Generated AMB source

DECLARATIVES.
declarativestatement declarativestatement
END DECLARATIVES
Parent topic: Program Painter Keywords
Related tasks
To define a Declaratives section
Related reference
DPAR
USE BEFORE REPORTING


DPAR

Create a Declaratives Section paragraph or section--not declarative statements.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

See also DECL and USE BEFORE REPORTING for creating Declarative Section statements, paragraphs, and sections.

Targets:

  • DLG programs
  • CICS batch programs and reports
  • IMS DC batch programs and reports

Syntax:

 DPAR   sectionname SECTION
        USE declarativesentence
[DPAR   paragraphname
            paragraphstatements ]

Parameters:

sectionname | Specify Section paragraph.
USE declarative sentence | AMB supports the USE clause with the exception of USE AFTER DEBUGGING, which is not supported.

Comments:

  • Micro Focus recommends that you code declaratives at the end of your program, because AMB generates the END DECLARATIVES statement when either:
    • It encounters another keyword in the KYWD column.
    • The Declaratives Section is at the end of the program.
  • Do not code the DECLARATIVE SECTION header and the END DECLARATIVES statements. AMB generates these for you.

Examples:

Program Painter code

 DPAR    DUMMY-FOOTER SECTION
         USE BEFORE REPORTING FOOTER-DUMMY
 DPAR    DUMMY-FOOTER-PARA
         MOVE TOTAL-DIFF TO TIME-TOTAL
         SUPPRESS PRINTING
 DPAR    TOTAL-FOOT-SECTION SECTION
         USE BEFORE REPORTING TOTAL-FOOT
         TOTAL-FOOT-PARA
         TIME-AVERAGE = TIME-TOTAL / AVERAGE-CNT
         CALL-PERCENTAGE = (HALF-HOUR-CALLS / AVERAGE-CNT)
         ... * 100
         MOVE HALF-HOUR-CALLS TO HOLD-CALLS
         ADD HOLD-CALLS TO HALF-HOUR-CNT
         MOVE ZERO TO HALF-HOUR-CALLS
 DPAR    CONTROL-FOOTING-FINAL SECTION
         USE BEFORE REPORTING CNTL-FT-GP
 DPAR    CONTROL-FOOTING-FINAL-PARA
         IF SYSIN-TRACKER NOT = 'CTSALL'
             SUPPRESS PRINTING
         ELSE
             FINAL-PERCENTAGE = (HALF-HOUR-CNT / FINAL-PROB-
CNT * 100)

Generated code

 DECLARATIVES.
 DUMMY-FOOTER SECTION.
     USE BEFORE REPORTING FOOTER-DUMMY
 DUMMY-FOOTER-PARA.
     MOVE TOTAL-DIFF TO TIME-TOTAL
     SUPPRESS PRINTING
 TOTAL-FOOT-SECTION SECTION.
     USE BEFORE REPORTING TOTAL-FOOT
     $TOTAL-FOOT-PARA
     TIME-AVERAGE = TIME-TOTAL / AVERAGE-CNT
     CALL-PERCENTAGE = (HALF-HOUR-CALLS / AVERAGE-CNT)
     ... * 100
     MOVE HALF-HOUR-CALLS TO HOLD-CALLS
     ADD HOLD-CALLS TO HALF-HOUR-CNT
     MOVE ZERO TO HALF-HOUR-CALLS
 CONTROL-FOOTING-FINAL SECTION.
     USE BEFORE REPORTING CNTL-FT-GP
CONTROL-FOOTING-FINAL-PARA.
     IF SYSIN-TRACKER NOT = 'CTSALL'
         SUPPRESS PRINTING
     ELSE
         FINAL-PERCENTAGE = (HALF-HOUR-CNT / FINAL-PROB-CNT * 100)
 END DECLARATIVES.
Parent topic: Program Painter Keywords
Related tasks
To define a Declaratives section
Related reference
DECL
USE BEFORE REPORTING


DS

In your program, include a data structure created in the Data Structure Editor and in that format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 DS[nn]  datastructurename

Comments:

  • Nn is the beginning level number for the data structure entity. This is useful when concatenating multiple data structure entities in the same program. Nn overrides the default 01-level created with the REC keyword in the Data Structure Editor.
  • The preceding section keyword determines the placement of a data structure in the generated program. Associated section keywords are
    FD | File Section (see FD)
    SD | Sort File Description (see SD)
    LK | Linkage Section (see LK)
    WS | Working-Storage Section (see WS)
Parent topic: Program Painter Keywords
Related tasks
To define the Input-Output Section
To include a global or local data structure
Related reference
FD
SD
LK
WS


FD

Define the file descriptions for input and output files, including report files.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

 FD     inputfilename|outputfilename
        [Applicable COBOL FD clauses]

Syntax: for Format 2

 FD     filename
        [Applicable COBOL FD clauses]
        REPORT IS|REPORTS ARE reportname1 [... reportname15]

Comments:

  • Use one FD keyword per file description.
  • In Format 1, follow each file description with the file record description, using the 01, DS, or REC keywords.
  • In Format 2
    • Reportnames may be in any order.
    • Each Reportname must have a corresponding RED statement. Reportnames in both statements must be identical.
    • The RED statement for each report replaces the file record description entry required for Format 1.
    • The default size for a report record is 133. To define a different report record size in your FD statement, calculate the size as follows, and code it in a RECORD CONTAINS clause.

      Record Size = Report mock-up size (maximum 247 characters) + 1 byte for carriage control + 2 bytes for the CODE clause, if used.

    • If you define the report record in the WRITE ROUTINE clause, the default size is either 248 or 250. See WRITE ROUTINE.
    • AMB generates the file description 01-level identifier(s) for each report output file(s); you need not code them.
    • If reportname exceeds 20 characters, Report Writer creates an abbreviated record name, as follows: The first character of each hyphenated word in the data name (except the last word), a hyphen, the last word, a hyphen, and RECORD. For example,
      Input REALLY-LONG-REPORT-NAME
Output RLR-NAME-RECORD

Example:

 FD     INPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS.
 01     PART-STOCK-REC             PIC X(80).
 FD     REPORT-OUTPUT-FILE
        LABEL RECORDS ARE STANDARD
        REPORT IS STOCK-REPORT.
Parent topic: Program Painter Keywords
Related tasks
To define the Input-Output Section
To code input-output statements for reports
To specify multiple reports
Related reference
WRITE ROUTINE


FRFM

Pass COBOL or S-COBOL statements to the AMB generator without translation, in a freeform manner, and insert the statements in the program section where they are coded.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

For Working-Storage and Linkage Sections only

 FRFM   COBOLstatements|S-COBOLstatements

Syntax: for Format 2S

For Working-Storage and Linkage Sections only

        ENTER COBOL|ENTER S-COBOL
        COBOLstatements|S-COBOLstatements

Comments:

  • The next keyword (except the comment keyword, /*) terminates the FRFM function.
  • In Format 1, all COBOL and S-COBOL statements shift four spaces to the left during generation.
  • In Format 2, omit the FRFM keyword; all COBOL statements remain in Column 12 during generation.
  • Do not use the ENTER COBOL and ENTER S-COBOL statements within REPEAT or IF/ELSE-IF/ELSE structures.

Examples:

Code 77-level data structures and put the data elements in column 8.

 FRFM   77 FIELD-A         PIC S99 COMP-3.
        77 FIELD-B         PIC S99 COMP-3.
        77 FIELD-C         PIC S99 COMP-3.

Code 77-levels with Customizer symbols

 SYWS   &08+77  FIELD-A     PIC S99 COMP-3.
        &08+77  FIELD-B     PIC S99 COMP-3.
        &08+77  FIELD-C     PIC S99 COMP-3.
Parent topic: Program Painter Keywords


IO

Generate the Input-Output Section File-Control paragraph.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Compatibility:

Batch environments

Syntax: for Format 1

 IO     filename ASSIGN [TO] COBOLdataname
                              "literal"
                              EXTERNAL externalfile
        ORGANIZATION IS RECORD SEQUENTIAL
                        LINE

Syntax: for Format 2

 IO    filename ASSIGN [TO] DYNAMIC ddname
       ORGANIZATION IS RECORD SEQUENTIAL

Comments:

  • Do not code the SELECT verb in your syntax.
  • Do not use ellipses to continue a FILE-CONTROL clause on subsequent lines. Any keyword except /* (the comment keyword) designates the end of the continuation.
  • Code an IO keyword for each file.
  • AMB generates both the program INPUT-OUTPUT section header and the FILE-CONTROL header.
  • Format 1 supports COBOL, as follows
    • Dataname can be a drive, path identifier, or both.
    • EXTERNAL identifies externalfile to the external environment for further mapping to an external file-storage environment name.
    • Externalfile specifies the environment variable. The SET command defines the environment variable; the Runtime system uses it to locate externalfile in the environment.
    • "Literal" is a standard PC file specification.
    • ORGANIZATION is RECORD SEQUENTIAL, a fixed length record (default).
Parent topic: Program Painter Keywords
Related tasks
To define the Input-Output Section
To code input-output statements for reports


LK

Create or include data structures in the Linkage Section.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 LK
 kywd   associated data structure

Parameters:

kywd Associated data structure keywords are 01, DS, REC, SQL.

Examples:

Code Working-Storage and Linkage data structures using section keywords.

 IO     INPUT-FILE ASSIGN TO UT-S-INPUT
 FD     INPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 01     INPUT-REC         PIC X(80).
 WS
 REC    WS-INPUT-REC.
            WS-IN-PART-NO       N8
            WS-IN-DESC          X50
            WS-IN-BASE-PRICE    N6V2
 LK
 REC    LK-INPUT-REC
            LK-IN-PART-NO       N8
            LK-IN-DESC          X50
            LK-IN-BASE-PRICE    N6V2
 01     LK-OUT-REC.
 DS05   LK-OUT-REC
Parent topic: Program Painter Keywords
Related tasks
To code Linkage Section structures
Related reference
DS
01
REC
SQL


MOCK

Specify the report mock-up name in your report program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Compatibility:

Batch environments

Syntax:

 MOCK  mockupname

Comments:

Mockupname is the name entered in the Reports field associated with your program in the Project Explorer and painted in the Report Painter.

Examples:

 RED   STOCK-REPORT
       CONTROLS ARE FINAL WS-LOCATION-CODE
       PAGE LIMIT IS 50
       FIRST DETAIL 10
       LAST DETAIL 40
       FOOTING 47.
 MOCK  STCKPRT
 01    TYPE IS REPORT HEADING NEXT GROUP
           NEXT PAGE LINE 20.
       MOCKUP LINES 1 THRU 6
       SOURCE WS-DATE
Parent topic: Program Painter Keywords
Related tasks
To specify a report mock-up


NTRY

Generate a program template that fully defines all parts of your program except for the procedural code that you supply.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

NTRY generates a program template that defines:

  • The Identification Division, based on your Output preferences
  • The Environment Division, based on your Output preferences
  • The Data Division, including the following Working-Storage and Linkage Section structures:
    • Your database record or file definitions, based on your imported subschema
    • Your window and screen field data structures, based on your Screen Painter specifications
    • CICS EIBRCODEand DFHCOMMAREA structures
    • Your IMS PCB mask, including I/O and database PCBs, based on your data view
    • A data structure for passing data among programs, known as a Commarea; the Commarea appears in either Working-Storage or the Linkage Section, depending on your DC or UI target
    • PF key definitions, based on your specified DC or UI target
    • Flags required by AMB
  • Portions of the Procedure Division, including:
    • A housekeeping routine to initialize Working-Storage fields, flags, and counters
    • Program invocation logic to initialize your program when it is invoked by a transaction ID, a window, or another program, based on your specified DC or UI target
    • Logic to send the program screen to the end user monitor

Targets:

  • CICS
  • DLG

CICS

In CICS programs, NTRY also generates code to:

  • Obtain addressability to Linkage Section areas passed from other programs via addresses in the program Commarea.
  • Receive correct map if transaction is screen-invoked.
Syntax:
NTRY|ENTR screenname(mapsetname)]
... [errorpara]
... [RETRY|NORETRY]
Parameters:
screenname | Screen name; value must be literal (maximum 8 characters).
mapsetname | Mapset containing the screen(s) the program receives; must be a literal (maximum 7 characters). See also Remarks for CICS below.
errorpara | User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
RETRY | Default. Accept only valid data in screen fields with assigned edits; otherwise, return screen to the terminal user for correction.
NORETRY | Accept invalid data in screen fields with assigned edits.
Comments:
  • Normally, if received data fails to pass editing, AMB returns the screen, highlighting errors and displaying error messages in the SYSMSG field. Application logic executes after the received data passes editing.

    It is possible, however, to accept screens with data that does not pass editing. When NORETRY is coded, the application logic executes regardless. A set of runtime flags allow application logic to determine the success or failure of editing

    APS-EDITS-PASSED | 88-level flag set to true when data for all edited fields is valid. Code IF APS-EDITS-PASSED to test whether the edit is OK.
    screenname-fieldname-FLAG | Indicator flag set to spaces when data for a specified field valid. Code IF screenname-fieldname-FLAG = SPACES to test whether the data is valid.
    screenname-fieldname-INPT | AMB-generated data field; contains data exactly as entered if the field failed to pass editing.
    APS-MSG-IO-ERROR | Applies to IMS DC only. 88-level flag set to true when a program sends a user-defined I/O error message. Code IF APS-MSG-IO-ERROR to test if message sent.
    APS-MSG-EDIT-ERROR | 88-level flag set to true when a program sends a user-defined edit error message. Code IF APS-MSG-EDIT-ERROR to test whether if message sent.
  • When mapsetname is not specified, AMB looks for it in the Screen Generation Parameters window information; otherwise, AMB generates a default mapset name, based upon the length of the screen name.
    Screen Name Length | Generated Mapset Name
    4 characters | screennameSET
    5 characters | screenname$
    6 characters | screenname$
    7 characters | Last character of screenname changes to $
    8 characters | Truncates eighth character of screenname; seventh character changes to $
  • You can write rules, using the following names, to customize NTRY processing.
    User Rule Name | Where Included
    TP-ENTRY-EXIT-1 | Bottom of APS-HOUSEKEEPING-PARA
    TP-ENTRY-EXIT-2 | After APS-HOUSEKEEPING-PARA
  • For more information, see Comments in the Help topic Program-Painter Keywords - All Applications.
Examples:

Generate code to receive screen CUSTORDR in mapset CUSTOR$ for a screen-invoked program. Perform MAP-ERROR-PARA when an exceptional condition occurs on the RECEIVE MAP.

 NTRY   CUSTODR(CUSTOR$) MAP-ERROR-PARA

See also Examples in Program-Painter Keywords - All Applications.

DLG

In DLG programs, NTRY also generates code to display screens.

Syntax:
NTRY|ENTR screenname
... [errorpara]
... [RETRY|NORETRY]
... [CANCEL|RETURN]
... [dataareas]
Parameters:
screenname | Screen name; value must be literal (maximum 8 characters).
errorpara | User-defined error routine to perform when an abnormal condition occurs. Errorpara is positional; if omitted, code an asterisk (*) in its place.
RETRY | Default. Accept only valid data in screen fields with assigned edits; otherwise, return screen to the terminal user for correction.
NORETRY | Accept invalid data in screen fields with assigned edits.
CANCEL | Default. Generate CONTROL ERRORS CANCEL (return control to ISPF when dialog error of return code 12 or higher).
RETURN | Generate CONTROL ERRORS RETURN to return control to program when dialog error occurs. See also Remarks below.
dataareas Generate the PROCEDURE DIVISION USING statement. List user-defined data areas only, not records defined by TP-COMMAREA, TP-LINKAGE, and SCRNLIST, which automatically generate other data areas. AMB generates data areas in the following order.
  • Data areas listed with NTRY.
  • TP-COMMAREA record (see TP-COMMAREA).
  • TP-LINKAGE records (see TP-LINKAGE).
  • SCRNLIST screen records (see SCRNLIST).
Comments:
  • Normally if received data fails to pass editing, AMB returns the screen, highlighting errors and displaying error messages in the SYSMSG field. Application logic executes after the received data passes editing.

    It is possible, however, to accept screens with data that does not pass editing. When NORETRY is coded, the application logic executes regardless. A set of runtime flags allow application logic to determine the success or failure of editing.

    APS-EDITS-PASSED | 88-level flag set to true when data for all edited fields is valid. Code IF APS-EDITS-PASSED to test whether the edit is OK.
    screenname-fieldname-FLAG | Indicator flag set to spaces when data for a specified field valid. Code IF screenname-fieldname-FLAG = SPACES to test whether the data is valid.
    screenname-fieldname-INPT | AMB-generated data field; contains data exactly as entered if the field failed to pass editing.
    APS-MSG-EDIT-ERROR | 88-level flag set to true when a program sends a user-defined edit error message. Code IF APS-MSG-EDIT-ERROR to test whether if message sent.
  • Code logic in errorpara to process all ISPEXEC display service return codes with a value of 12 or higher.
  • Provide errorpara to handle dialog errors when coding RETURN.
  • For more information, see Comments in the Help topic Program Painter Keywords - All Applications.
Examples:

Generate code to display screen SCRA. Perform PROCESS-ISPF-ERRORS when return codes from services are greater than 12. Generate CONTROL ERRORS RETURN code so the program can control all error processing.

 NTRY   SCRA  PROCESS-ISPF-ERRORS  RETURN

See also the Examples in Program Painter Keywords - All Applications.

Parent topic: Program Painter Keywords
Related tasks
To begin the Procedure Division for batch programs
To begin the Procedure Division for online programs
To code the Procedure Division
To code report logic
Related reference
Program Painter Keywords - All Applications
TP-COMMAREA
TP-LINKAGE
SCRNLIST
APSDBDC
Output


OPT

Suppress the mainline program section generated by the NTRY or PROC keyword, in order to supply your own screen and program invocation logic. Use OPT only in online programs with screens.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

Programs created in Program Painter

Syntax:

 NTRY|PROC
 OPT    PROG

Comments:

  • You can use PROGRAM, PROGRAMMER, PCONV, or PCONVERT in place of PROG in columns 12 - 72.
  • Code an NTRY, PROC, or OPT statement for each program.
    • To generate a batch program template with a PROCEDURE DIVISION USING statement, code PROC.
    • To generate a program template that fully defines all parts of your program except for the procedural code that you supply, code NTRY.
Parent topic: Program Painter Keywords
Related reference
PROC
NTRY


PARA

Indicate a paragraph in your program code. A paragraph is a Procedure Division routine that you write and perform specifically for one program. Use paragraphs to perform the following, depending on which AMB tool you use
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Use paragraphs in . . . | To perform . . .
Online Express | Custom actions for events
Program Painter | Custom routines in the Procedure Division

Syntax: for Format 1

 PARA   paragraphname [SECTION.]
        paragraphcode

Syntax: for Format 2

             .
             .
        PERFORM paragraphname [(arguments)]
             .
             .
 PARA   paragraphname [(+|-arguments)]
        statement
             .
             .
             .
        PERFORM subparagraphname [(arguments)]
 PARA   subparagraphname [(+|-arguments)]
        statement
             .
             .
             .
 WS
 01     group-level-data-item
        05  elementary-data-item
             .
             .
             .

Comments:

  • Use Format 1 with SECTION to code a SORT procedure.
  • The keyword PARA, followed by a paragraph name with an optional list of arguments, denotes a paragraph. Within a paragraph, indentation determines the exact positioning of its logic statements, or statement blocks.
  • A paragraph ends with the next appearance of any Procedure Division keyword, except the comment keyword (/*); there is no need to code an END-paragraphname.
  • Code at least one PERFORM statement before any PARA keywords in your program. Generally, you code a PERFORM statement that performs your main logic paragraph.

Paragraph Rules

Rules for coding paragraphs in Client and Online Express.

  • A paragraph can consist of a main paragraph, other paragraphs that the main paragraph performs, and Data Division source code for the paragraphs.
  • For each paragraph, enter the PARA keyword in the KYWD column and the paragraph name in column 12 on the same line. On the following lines, enter COBOL, COBOL II, or S-COBOL paragraph statements. Do not use any other AMB keywords in paragraphs.
  • After all paragraphs, use AMB Data Division keywords to define data items that the paragraphs reference.

Rules for coding paragraphs in the Program Painter.

  • A paragraph can perform other paragraphs.
  • For each paragraph, enter the PARA keyword in the KYWD column and the paragraph name in column 12 on the same line. On the following lines, enter COBOL, COBOL II, or S-COBOL paragraph statements. Do not use any other AMB keywords in paragraphs.
  • Anywhere in the program, use AMB Data Division keywords to define any data items that the paragraphs reference.
Parent topic: Program Painter Keywords
Related tasks
To code the Procedure Division


PROC

Generate the batch program template, including a PROCEDURE DIVISION USING clause that enables a called program to receive data from the calling program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

Non-IMS batch programs

Syntax:

 PROC   [variablename1 variablename2 ... variablenameN]

Comments:

  • Use PROC instead of NTRY in non-IMS batch programs called by other programs. Use NTRY for IMS programs.
  • Code Linkage Section data structures for the variables that the called program receives.
  • Code an NTRY, PROC, or OPT statement for each program.
    • The generated $TP-ENTRY generates a program template to send the appropriate window depending on the program invocation mode. To suppress the window and program invocation logic from your program template, code OPT PROG.
    • To generate a program template that fully defines all parts of your program except for the procedural code that you supply, code NTRY.

Examples:

Program Painter code:

 PROC   REC-2 REC-2 REC-3

Generated COBOL code:

PROCEDURE DIVISION USING REC-2 REC-2 REC-3
Parent topic: Program Painter Keywords
Related tasks
To begin the Procedure Division for batch programs
Related reference
OPT
NTRY


REC

Define a data structure in the Data Structure Editor format.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 REC    datastructure

Parameters:

datastructure Valid Data Structure Editor construct.

Comments:

  • Each REC keyword generates an 01-level data structure. AMB transfers the REC entity to the Working-Storage Section.
  • The preceding section keyword determines the placement of a data structure in the generated program. Associated section keywords are:
    FD | File Section (see FD)
    SD | Sort File Description (see SD)
    LK | Linkage Section (see LK)
    WS | Working-Storage Section (see WS)
  • Code a COBOL COPY with REC, as follows
     REC    dataname
            COPY copybookname
            ... REPLACING field1 BY field2
Parent topic: Program Painter Keywords
Related tasks
To define data structures in Data Editor format
To define the Input-Output Section
Related reference
FD
SD
LK
WS


RED

Name and begin the statement block that defines the report; identify the report name, control fields, and report page characteristics.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

Batch environments

Syntax:

 RED    reportname
       [CODE literal]
       [CONTROL [IS] [FINAL] dataname |
        CONTROLS [ARE] [FINAL] dataname1 ... datanameN ]
       [WRITE ROUTINE [IS] paragraphname]
       [PAGE LIMIT[S] IS|ARE number LINE[S]
           [FIRST DETAIL linenumber]
           [LAST DETAIL linenumber]
           [FOOTING linenumber]] [.]

Parameters:

reportname Report name of the REPORT clause in the File Section

Comments:

  • If reportname exceeds 20 characters, Report Writer creates an abbreviated record name, consisting of: the first character of each hyphenated word of the report name, except the last word; a hyphen; the last word; a hyphen; and the word RECORD. For example,
    • Input REALLY-LONG-REPORT-NAME
    • Output RLR-NAME-RECORD
  • Each report requires a RED statement. Reportnames in both the RED and FD statements must be identical.
  • Code RED clauses in any sequence.

Examples:

 RED   YEAR-END-SALES-SUMMARY
       CONTROLS ARE FINAL
          REGION REGION-MGR-FLD OFFICE
       PAGE LIMIT IS 58 LINES
       FIRST DETAIL 9
       HEADING 1
       FOOTING 58.
Parent topic: Program Painter Keywords
Related tasks
To code a report page description
To code control breaks in reports
To identify a report in Working-Storage


REM

Create Identification Division Remarks text.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Target:

Supported for OS/VS COBOL only, in all targets.

Syntax:

 REM    commentline1
             .
             .
             .
        commentlineN
Parent topic: Program Painter Keywords
Related tasks
To code Identification Division comments in the Program Painter


SD

Include a sort file description.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 SD     sortfilename
        [Applicable COBOL SD clauses]

Comments:

  • Use one SD keyword per sort file description.
  • Follow each file description with the file record description, using the 01, DS, or REC keywords.

Examples:

 IO     INPUT-FILE ASSIGN TO UT-S-INPUT
 IO     OUTPUT-FILE ASSIGN TO UT-S-OUTPUT
 SPNM   C01 IS TOP-OF-PAGE
 FD     INPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 01     INPUT-RECORD            PIC X(80)
               .
               .
 FD     OUTPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 01     OUTPUT-RECORD            PIC X(80)
               .
               .
 SD     SORT-FILE
        RECORD CONTAINS 80 CHARACTERS
        DATA RECORD IS SORT-RECORD
 01     SORT-RECORD            PIC X(80)
               .
               .
Parent topic: Program Painter Keywords
Related tasks
To define the Input-Output Section


SPNM

Create a Special-Names paragraph in the generated program.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 SPNM   statement1
            .
            .
            .
 SPNM   statement1

Examples:

 SPNM   C01 IS TOP-OF-PAGE
Parent topic: Program Painter Keywords
Related tasks
To code an Environment Division Special-Names statement


SQL

Designate a DB2 table or cursor declaration in the Working-Storage or Linkage Section. Additionally, code native SQL statements and pass them through, without translation, to the precompile process.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

Working-Storage and Linkage Sections

 SQL    SQLdatastructurestatement
                .
                .
                .

Syntax: for Format 2

Procedure Division

        SQL nativecall
                .
                .
                .

Comments:

  • Use one SQL keyword for each SQL call. AMB generates EXEC SQL and END-EXEC statements before the first and last statements, respectively.
  • In the Data Division, the SQL keyword designates a DB2 table or one or more cursor declarations in the Working-Storage or Linkage Section. Use one SQL keyword for each SQL call. AMB generates EXEC SQL and END-EXEC statements before the first and last statements, respectively.
  • In the Procedure Division, start every SQL Procedure Division statement with the SQL verb, coded in columns 12 through 72. Begin subsequent lines of the statement with continuation ellipses. All statements pass to the precompiler without translation. SQL statements can be coded anywhere after the PARA, PROC, or NTRY keywords.

Examples:

Program Painter code

 SQL
        DECLARE DSN8.TDEPT TABLE
        ... (DEPTNO CHAR(3) NOT NULL,
        ... DEPTNAME CHAR(36) NOT NULL,
        ... MGRNO CHAR(3) NOT NULL,
        ... ADMRDEPT CHAR(3) NOT NULL)
 REC    WS-DEPARTMENT
           DEPARTMENT-NUM       X3
           DEPARTMENT-NAME      X36
           DEPARTMENT-MGR-NO    X3
           DEPARTMENT-ADMIN     X3
 NTRY
        SQL
            ... SELECT DEPTNO, DEPTNAME,
            ... MGRNO, ADMRDEPT
            ... INTO :DEPARTMENT-NUM,
            ... :DEPARTMENT-NAME,
            ... :DEPARTMENT-MGR-NO,
            ... :DEPARTMENT-ADMIN
            ... FROM DSN8.TDEPT
            ... WHERE DEPTNO > 0
        IF SQLCODE > +0
            PERFORM ERROR-DISPLAY

Generated code

%   &AP-GEN-VER = 1719
%   &AP-PGM-ID = "TSTSQL"
%   &AP-GEN-DC-TARGET = "ISPF"
%   &AP-TP-ENTRY-KYWD-SEEN = 1
%   &AP-SUBSCHEMA = ""
%   &AP-APPLICATION-ID = "TSTSQL"
%   &AP-GEN-DATE = "861219"
%   &AP-GEN-TIME = "16063323"
IDENTIFICATION DIVISION.
PROGRAM-ID.                     TSTSQL.
AUTHOR.                         AP-SYSTEM GENERATED.
DATE-WRITTEN.                   861219.
DATE-COMPILED.                  &COMPILETIME.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER.                &SYSTEM.
OBJECT-COMPUTER.                &SYSTEM.
DATA DIVISION.
WORKING-STORAGE SECTION.
 $TP-WS-MARKER
    EXEC SQL INCLUDE SQLCA
    END-EXEC.
    EXEC SQL
    DECLARE DSN8.TDEPT TABLE
        (DEPTNO CHAR(3) NOT NULL,
        DEPTNAME CHAR(35) NOT NULL,
        MGRNO CHAR(3) NOT NULL,
        ADMRDEPT CHAR(3) NOT NULL)
    END-EXEC.
 01  WS-DEPARTMENT.
     05  DEPARTMENT-NUM          PIC X(3).
     05  DEPARTMENT-NAME         PIC X(36).
     05  DEPARTMENT-MGR-NO       PIC X(3).
     05  DEPARTMENT-ADMIN        PIC X(3).
 $TP-COMMAREA
 $TP-ENTRY ("", "")
     SQL
         ... SELECT DEPTNO, DEPTNAME,
         ... MGRNO, ADMRDEPT
         ... INTO :DEPARTMENT-NUM,
         ... :DEPARTMENT-NAME,
         ... :DEPARTMENT-MGR-NO,
         ... :DEPARTMENT-ADMIN
         ... FROM DSN8.TDEPT
         ... WHERE DEPTNO > 0
     IF SQLCODE > +0
         PERFORM ERROR-DISPLAY
Parent topic: Program Painter Keywords
Related tasks
To define a DB2 table declaration and cursor declarations


STUB

Include in a program a custom source code module that you named in the Project Explorer.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 STUB   name

Comments:

When generated, the source appears in column 8.

Examples:

 NTRY   MSCR
      .
      .
      .
 STUB   STUBPGM
Parent topic: Program Painter Keywords
Related tasks
To code the Procedure Division


SY*

Specify in a AMB program the location where the generator places source code.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Compatibility:

PC and mainframe operating systems

Syntax:

 SYBT   source
 SYEN   source
 SYDD   source
 SYFD   source
 SYIO   source
 SYLT   source
 SYLK   source
 SYM1   source
 SYM2   source
 SYRP   source
 SYWS   source

Locations in Generated Code:

Location | Keyword | Explanation
Top of program | SYM1 | At the beginning of the program, before rule libraries that you include at the beginning of the program
 | SYM2 | After rule libraries that you include at the beginning of the program
Environment Division | SYEN | In the Environment Division, after the Special-Names paragraph
 | SYIO | In the Input-Output Section, after rule libraries that you include at the beginning of the Input-Output Section
Data Division | SYDD | At the beginning of the Data Division
 | SYFD | In the File Section, after rule libraries that you include at the beginning of the File Section
 | SYWS | In the Working-Storage Section, after rule libraries and data structures that you include in Working-Storage
 | SYLT | In the Linkage Section, after rule libraries and data structures that you include at the beginning of Linkage
 | SYLK | In the Linkage Section, after source code that you include with the SYLT keyword
 | SYRP | In the Report Section, after any rule libraries that you include at the beginning of the Report Section
Procedure Division | SYBT | At the end of the program
  • The effect of a SY* keyword ends with the appearance of another keyword in the KYWD column.
  • The generation process shifts the source to start in column 8.

Examples:

Include a rule at the top of the program.

 SYM1   % INCLUDE USERMACS(MY-RULE)

Place a variable assignment statement at the top of the program.

 SYM1    &TP-USER-LEN = 49

Include a copybook in Working-Storage.

 SYWS   % INCLUDE COPYLIB(MY-COPYBOOK)

Include a copybook in Linkage.

 SYLK   % INCLUDE COPYLIB(MY-COPYBOOK)
Parent topic: Program Painter Keywords
Related concepts
Coding Programs
Related tasks
To code Identification Division comments in the Program Painter
To code an Environment Division Special-Names statement
To code Working-Storage structures
To define data structures in COBOL format
To define data structures in Data Editor format
To include a copyfile
To include a global or local data structure
To define a DB2 table declaration and cursor declarations
To code Linkage Section structures
To define or redefine the Commarea
To begin the Procedure Division for online programs
To code the Procedure Division
To code Procedure Division comments
To define the Input-Output Section
To create a User Rule
To update a User Rule


WS

Define or include data structures in the Working-Storage Section.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 WS
 kywd   associated data structure

Parameters:

kwyd Associated data structure keywords are 01, DS, REC, or ++.

Examples:

Use Section keywords to code Working-Storage data structures.

 IO     INPUT-FILE ASSIGN TO UT-S-INPUT
 IO     OUTPUT-FILE ASSIGN TO UT-S-OUTPUT
 SPNM   C01 IS TOP-OF-PAGE
 FD     INPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 01     INPUT-REC         PIC X(80).
 DS01   INPUT-REC
 FD     OUTPUT-FILE
        LABEL RECORDS ARE STANDARD
        BLOCK CONTAINS 0 RECORDS
 REC    OUTPUT-REC       X80
 01     OUTPUT-REC-R REDEFINES OUTPUT-REC.
        ... COPY OUTREC.
 WS
 REC     WS-INPUT-REC
            WS-IN-PART-NO       N8
            WS-IN-DESC          X50
            WS-IN-BASE-PRICE    N6V2
 01     WS-OUT-REC
 DS05   WSOUTREC
Parent topic: Program Painter Keywords
Related tasks
To code Working-Storage structures
To code Working-Storage entries for reports
Related reference
01
REC
++


Programming and Size Limitations

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

AMB enforces the following size and programming limitations.

Component | Item | Maximum
COBOL | Characters in paragraph name | 24
Report Writer | Report mock-up lines in copyfile | 200
 | Report mock-up lines in Report Painter | 200
 | Number of reports for FD | 15
 | Number SOURCE/SUM/ VALUE statements per program | 300
S-COBOL | Paragraph | 600
 | Characters in paragraph name | 24
 | Indentation levels per nested IF structure | 14
 | Paragraph arguments per program | 400
 | EVALUATE statement conditional fields | 255
 | EVALUATE statement WHEN conditions | 102
 | Symbol table entries (such as, paragraph names, file names, record names, verbs, section names, keywords, arguments, indexes, flags) | 1801
SQL | Cursor/DB-PROCESS-ID names used in DB-DECLARE, DB-OPEN, DB-FETCH, DB-CLOSE and DB-PROCESS | 12
 | Correlation Names (also known as “Alias” field in Online Express) in SQL DB macros | 17
 | Correlation names in Online Express | 4
 | Table names when MFG is on | 128, no embedded spaces
 | Table names when MFG is off | 18, no embedded spaces
 | Column names | 30, no embedded spaces
 | Copyfile names | 8
 | Record names | 12
 | Result field names for functions and their indicator variables | 26
Parent topic: Reference


Report Writer Structures

Use Report Writer structures to code report logic in batch programs and applications after you paint your report mock-up in the Report Painter. Report Writer structures enable you to:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Automatically page the report
  • Define headers and footers
  • Calculate field values
  • Test and execute control and page breaks
  • Generate multiple reports
  • Generate all logic necessary to map fields between reports and databases or files

Code these Report Writer structures in the Program Painter for report programs.

IO FD | Name the input and output files.
RED | Add a Report Section to your program.
CODE | Specify a 2-character literal that identifies each print line with a specific report.
CONTROL | Identify data items that cause control breaks.
WRITE ROUTINE | Override a standard COBOL WRITE statement and execute your own routine.
PAGE LIMIT | Define the report format, such as the number of lines per page and where report lines appear on the page.
MOCK | Identify the report mock-up.
01 TYPE | Describe function, format, and characteristics of each report line.
MOCKUP LINES | Map the report mock-up lines to the lines on the printed report.
OVERPRINT | Highlight or underscore the lines identified in the MOCKUP LINES clause.
SOURCE | Map the report mock-up fields to the output fields on the printed report.
VALUE | Designate a literal value to print for the field each time the line prints.
REFERENCE | Identify a non-printing data field for summing in a control break.
SUM | Establish a sum accumulator for a corresponding SOURCE or REFERENCE data field, and print the total in a control break.
INITIATE | Open report files and initialize page, line, and sum counters and accumulators.
GENERATE | Generate and print all the report lines.
USE BEFORE REPORTING | Specify additional processing for a report group prior to printing.
TERMINATE | End report processing and close all files.

Rules:

The sequence in which mock-up fields are matched with the data item descriptions is the same as a page of text is read–from left to right across each line of the mock-up starting with the top line and continuing to the bottom. AMB matches the report mock-up fields to the data item description entries in your program according to the following rules:

  1. The following are considered literals:
    • The COBOL picture character A.
    • Any one or more consecutive non-space, non-picture characters.
    • Any single COBOL picture character, that is preceded and followed by a space. Exception to this rule: 9 and X.
    • A string of hyphens because of its frequent use for underlining.
    • AMB considers a single COBOL picture character, such as -, X, Z, or 9, that is embedded in a string of non-blank, non-picture characters as part of a literal. For example, the following are literals
      1979
WXYZ
EXTRA
WIZARD
  2. The following are considered pictures beside literals:
    #99 | Literal is #, PIC is 99
    l999 | Literal is l, PIC is 999
    Section-999 | Literal is SECTION, PIC is -999
  3. AMB considers any legal COBOL picture longer than one character to be a COBOL picture, except for the letter S and the hyphen (-), and matches it to the next data item description in the program.
  4. AMB generates a VALUE statement for each literal in the mockup, and does not match the literal with the data item descriptions in the program.
  5. AMB considers any consecutive PIC characters in the mock-up as one PIC character string, unless the string is matched with PIC clauses in multiple, consecutive SOURCE statements.
  6. AMB assigns each PIC character string as the PIC for the next sequential data item description, unless the next description contains a PIC clause.
  7. When a data item description contains a PIC clause, AMB compares it with an equal number of characters in the mock-up, starting with the next sequential, unassigned character in the mock-up.
  8. When comparing a data item description entry with a PIC clause to an equal number of characters in the mock-up and a non-match occurs, AMB continues the comparison by moving one position to the right until it finds a match. AMB considers the non-matched characters from this process to be a literal, and generates a VALUE entry that precedes the data item description with the PIC clause that initiated the comparison.
  9. When a PIC clause in a data item description does not match any series of mock-up characters from the start of a comparison to the end of the mock-up, AMB terminates processing and generates an error message.

Coding Conventions

Code Report Writer structures in the Program Painter, associating the structures with keywords, as shown in this sample skeletal Report Writer program:

Example: Sample Skeletal Report Writer Program

IO     Input/Output statements
              .
 FD     Input FD clause
 01     Input record description
 FD     Output FD clause
 01     Output record description
 RED    reportfilename
        CODE clause
        CONTROL clause
        WRITE ROUTINE clause
        PAGE LIMIT nn LINE
            FIRST DETAIL linenumber
            LAST DETAIL linenumber
            FOOTING linenumber.
 MOCK mockupreportname
 01   TYPE IS REPORT HEADING /*for report header
      MOCKUP LINES clause
      OVERPRINT clause
      SOURCE clause|VALUE clause
 01   TYPE PAGE HEADING        /*for page header
      MOCKUP LINES clause
      SOURCE clause|VALUE clause
 01   TYPE CONTROL HEADING  /*for control header
      MOCKUP LINES clause
      SOURCE clause or VALUE clause
 01   TYPE DETAIL             /*for detail lines
      MOCKUP LINES clause
      SOURCE clause|VALUE clause
      REFERENCE clause
 01   TYPE CONTROL FOOTING   /*for control break
      MOCKUP clause
      SOURCE clause|VALUE clause
      SUM clause
 NTRY
          .
          .
          .
      INITIATE statement
          .
          .
      GENERATE statement
          .
          .
      TERMINATE statement
          .
          .
          .
  • Iterative Expressions
    An Iterative Expression is a report writer contruct you use to express arrays or a series of numerically-suffixed data items as one SOURCE or SUM statement. This construct replaces coding repetitive series' when incrementing a data item or subscript.
  • CODE
    Specify a two-character literal placed at the beginning of each report line. It is useful when writing multiple reports to one file.
  • CONTROL
    Identify control data items (Report Writer controls), which are tested for a change each time a detail line is printed. Create a control hierarchy for the report control headings and footings (control breaks). This clause is part of the RED (see RED) keyword statement block.
  • GENERATE
    Produce either a detail report or a summary report; test controls; generate control breaks; print totals, detail lines, headings, and footings; clear counters and accumulators; and, paginate the report.
  • INITIATE
    Initialize all report counters and accumulators; set up control heading and control footing items.
  • MOCKUP LINES
    In your report program, specify the line numbers in the report mock-up that correspond to the detail lines, headers, and footers.
  • OVERPRINT
    Print one line on top of the other without advancing the line printer. Use this feature to create bold text or to underscore text.
  • PAGE LIMIT
    Define the page length and the vertical subdivisions of a printed page.
  • REFERENCE
    Establish summing capability for a non-printing detail item and sum the item in a control footing.
  • SOURCE
    Map Data Division items to output fields. Batch environments.
  • SUM
    Sum data items, and generate an internal SUM accumulator for a SOURCE or REFERENCE data field to be used in a control footing group.
  • SUPPRESS PRINTING
    Inhibit printing a report group named in a USE BEFORE REPORTING clause. This structure suppresses the following report group functions:
  • TERMINATE
    End report processing. The TERMINATE statement also:
  • TYPE
    Identify a report group, such as a header line, detail line, or footer line.
  • USE BEFORE REPORTING
    Code statements that execute before HEADING or FOOTING report groups print. You name the report group in the Report Section of the Data Division. You can specify special processing requirements, including calculations in addition to those specified in the SUM clause, and edits to a report line.
  • VALUE
    Designate, as literals, any values that can be interpreted as PIC characters, such as embedded Xs and 9s to a mock-up text field. AMB considers two or more consecutive COBOL PIC characters a COBOL PIC clause and all other strings as literals, with the following exceptions
  • WRITE ROUTINE
    Override the COBOL WRITE statement and execute your own routine.
Parent topic: Reference
Related concepts
Structure Summary
Related reference
Reserved Words


Iterative Expressions

An Iterative Expression is a report writer contruct you use to express arrays or a series of numerically-suffixed data items as one SOURCE or SUM statement. This construct replaces coding repetitive series' when incrementing a data item or subscript.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Targets:

VSAM Batch and all other batch environments

Syntax for Format 1

Numerically suffixed data items

item-#num[/limit[/increment]]

Syntax for Format 2

1-dimensional array

arrayitem (#num[/limit1[/increment1]]) One subscript range

Syntax for Format 3

2-dimensional array

arrayitem (#num[/limit1[/increment1]], First subscript range
          #num2[/limit2[/increment2]]) Second subscript range

Syntax for Format 4

3-dimensional array

arrayitem (#num[/limit1[/increment1]], First subscript range
          #num2[/limit2[/increment2]], Second subscript range
          #num3[/limit3[/increment3]]) Third subscript range

General Rules:

  1. The first slash separating numeric descriptors of an iteration translates to THRU, the second slash to BY.
  2. Leading zeros in the starting number are generated in the SUM or SOURCE statements.

Parameters:

number | Starting number
limit | Top limit of the increment range, or bottom limit if the increment is negative
increment | Integer increment value for intermediate data items

Example:

The following iterative expression:

SOURCE ARRAY-ITEM (#3, #2)

Replaces the following code:

SOURCE ARRAY-ITEM (1, 1)
SOURCE ARRAY-ITEM (1, 2)
SOURCE ARRAY-ITEM (2, 1)
SOURCE ARRAY-ITEM (2, 2)
SOURCE ARRAY-ITEM (3, 1)
SOURCE ARRAY-ITEM (3, 2)
Parent topic: Report Writer Structures
Related reference
CODE
CONTROL
GENERATE
INITIATE
MOCKUP LINES
OVERPRINT
PAGE LIMIT
REFERENCE
SOURCE
SUM
SUPPRESS PRINTING
TERMINATE
TYPE
USE BEFORE REPORTING
VALUE
WRITE ROUTINE


CODE

Specify a two-character literal placed at the beginning of each report line. It is useful when writing multiple reports to one file.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

CODE literal

Parameters:

literal A two-character, non-numeric name inserted as the first two bytes of each report record or print line

Comments:

  • The two bytes identifying a literal are included in the logical record size, not in the print line description.
  • If your report has a File Description (FD) in the REPORT IS clause, include a RECORD CONTAINS clause that allows for the two extra bytes the CODE clause needs; the default value of 133 for RECORD CONTAINS does not.

    If your report does not have a File Description, the AMB default record length of 250 includes the extra two bytes the CODE clause needs.

  • If you specify CODE for one report, specify it for all reports in the file.

Examples:

See Sample Programs.

Parent topic: Report Writer Structures
Related concepts
Sample Programs


CONTROL

Identify control data items (Report Writer controls), which are tested for a change each time a detail line is printed. Create a control hierarchy for the report control headings and footings (control breaks). This clause is part of the RED (see RED) keyword statement block.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

CONTROL [IS] [FINAL] dataname

Syntax: for Format 2

CONTROLS [ARE] [FINAL] dataname1 ... datanameN

Parameters:

dataname | Data item that causes a control break when it changes.
FINAL | Inclusive report control group not associated with a control dataname. It represents the highest level of control.

Comments:

  • Datanames can be qualified, but cannot be subscripted or indexed, or have a subordinate data item with a variable size defined in an OCCURS clause. Each dataname must be a different data item.
  • List the datanames from the highest to lowest level. An implicit FINAL is the highest control. The first dataname is the major control; the last dataname is the minor (lowest) control.
  • When identifing controls in the CONTROL clause, dataname must be an elementary data name. In the following example, B cannot be used as a control variable because it is a group data item. To make B into an elementary data item, use the REDEFINES clause.
    WS01  A                         PIC X(2).
WS01  B.
      02  B-1                   PIC 9(4).
      02  B-2                   PIC 9(4).
WS01  B-REDEF  REDEFINES B      PIC X(8).
      .
      .
      .
RED TEST-REPORT
    CONTROLS ARE A B-REDEF
  • You can omit the CONTROL clause when the only control is FINAL.
  • The first time a GENERATE builds a report, all control values are saved. The next GENERATE tests Report Writer controls for changes every time a detail line is printed, by comparing the contents with the contents saved from the last GENERATE of the same report.
    • If the control is numeric, the relation test compares two numeric operands.
    • If the control is an index, the test compares two index data items.
    • If it is neither numeric nor an index, it compares two non-numeric operands.
  • A change in dataname (a control) causes a control break that
    • Prints control footings for lower level datanames, followed by the control footing for the dataname causing the control break
    • Clears counters associated with the datanames
    • Prints control headings for the dataname and lower level datanames
    • Prints the detail line causing the break

Examples:

See Sample Programs.

Parent topic: Report Writer Structures
Related concepts
Sample Programs
Related reference
RED


GENERATE

Produce either a detail report or a summary report; test controls; generate control breaks; print totals, detail lines, headings, and footings; clear counters and accumulators; and, paginate the report.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

GENERATE dataname|reportname

Parameters:

dataname | Produce a detail report. Specify dataname in the TYPE clause as DETAIL.
reportname | Produce a summary report that contains no detail lines. Use reportname only if the referenced report group description contains a CONTROL clause, at least one REPORT HEADING, REPORT FOOTING, CONTROL HEADING, CONTROL FOOTING, or DETAIL group, and no more than one DETAIL report group

Comments:

  • On first GENERATE clause execution, AMB saves the control values. During other GENERATE executions, AMB tests these control values to determine control breaks until it detects one. When a control break occurs, AMB saves the new set of control values.
  • During report printing, AMB processes PAGE HEADING and PAGE FOOTING report groups for each page.
  • When the first GENERATE clause of a report executes, AMB processes, in order, the report groups defined in the report description-- REPORT HEADING, PAGE HEADING, and CONTROL HEADINGs, (from major to minor order).
  • When GENERATE dataname executes, AMB processes the designated report group. When GENERATE reportname executes, AMB performs certain steps to process a DETAIL report group.
  • When a GENERATE clause other than the first one executes, AMB locates control breaks. The rules for determining the equality of control data items are the same as for relation conditions. If a control break occurs
    • CONTROL FOOTING, USE procedures and CONTROL FOOTING, SOURCE statements are able to access the control data item values.
    • AMB processes the CONTROL FOOTING report groups in minor to major order. AMB does not process the CONTROL FOOTING report groups of a higher level than where the control break occurs.
    • AMB processes the CONTROL HEADING report groups in major to minor order. AMB does not process the CONTROL HEADING report groups of a higher level than where the control break occurs.
  • GENERATE processing can only occur after INITIATE processing and before TERMINATE processing, for the report.
Parent topic: Report Writer Structures
Related tasks
To code report logic


INITIATE

Initialize all report counters and accumulators; set up control heading and control footing items.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

INITIATE reportname1 [,reportname2] ...

Comments:

  • Define each report name in a RED statement.
  • Initialization does not open the report file. Code a COBOL OPEN OUTPUT statement before the INITIATE to do so.
  • You must TERMINATE reportname1 before executing an INITIATE for reportname2.
Parent topic: Report Writer Structures
Related tasks
To code report logic


MOCKUP LINES

In your report program, specify the line numbers in the report mock-up that correspond to the detail lines, headers, and footers.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

MOCKUP|M LINE|LINES linenumber1 [THRU linenumberN]

Comments:

  • Refer to all extra lines in a report mock-up with a MOCKUP statement.
  • The maximum number of report mock-up lines is 200.

Examples:

Specify that lines 1 through 8 in the report mock-up contain the heading text.

 01    TYPE IS REPORT HEADING LINE 20 NEXT GROUP
           NEXT PAGE.
       MOCKUP LINES 1 THRU 8
Parent topic: Report Writer Structures
Related tasks
To map report lines


OVERPRINT

Print one line on top of the other without advancing the line printer. Use this feature to create bold text or to underscore text.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

OVERPRINT|O WHEN 'characterstring' AT COLUMN integer

Parameters:

characterstring | Line or text to be overprinted; must be identical to characterstring in mock-up; delimit with single or double quotation marks.
integer | Starting column number of characterstring on the mock-up.

Comments:

In the mock-up, the two lines of text that print on one line of the page must be consecutive. On the first line enter a text string. On the second line enter the text that prints over the first line, and to the right of this text enter a unique characterstring to identify the line. When the report prints, blanks replace characterstring in the mock-up.

Examples:

Underscore text within a page heading. Below are lines 7 and 8 of a mock-up. The identifying character string, NO ADVANCING, begins in column 70 of the second line.

XXXXXXX
_______
NO ADVANCING

The OVERPRINT clause

 01    TYPE IS PAGE HEADING.
       MOCKUP LINES 7 THRU 9
       OVERPRINT WHEN 'NO ADVANCING' AT COLUMN 70

The printed result

XXXXXXX

Print text within the report heading of a mock-up twice, to appear as bold type. The identifying character string begins in column 70.

WIDGETS
WIDGETS
DITTO

The OVERPRINT statement

 01    TYPE IS REPORT HEADING LINE 20 NEXT GROUP NEXT PAGE.
       MOCKUP LINES 1 THRU 6
       OVERPRINT WHEN 'DITTO' AT COLUMN 70

The printed result

WIDGETS
Parent topic: Report Writer Structures


PAGE LIMIT

Define the page length and the vertical subdivisions of a printed page.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

PAGE LIMIT IS|ARE number [LINE|LINES]
    [FIRST DETAIL linenumber]
    [LAST DETAIL linenumber]
    [FOOTING linenumber] [.]

Parameters:

number LINE|LINES | Number of lines on each report page. Number cannot exceed 3 digits and must be greater than or equal to the FOOTING linenumber.
FIRST DETAIL linenumber | First detail line. Print control break heading and report body detail lines beginning on linenumber. Print REPORT and PAGE HEADING groups before linenumber.
LAST DETAIL linenumber | Line number of the last report body detail line. Print CONTROL FOOTING, PAGE FOOTING, and REPORT FOOTING lines after this number. Linenumber must be greater than FIRST DETAIL linenumber.
FOOTING linenumber | Last line number of the last control footing report group. Print PAGE FOOTING and REPORT FOOTING lines after this number Linenumber must be greater than or equal to LAST DETAIL linenumber.

Comments:

  • Code PAGE LIMIT before FIRST DETAIL, LAST DETAIL, or FOOTING.
  • Code FIRST DETAIL, LAST DETAIL, and FOOTING in any order.
  • Each report group should fit on one page; Report Writer never splits a report group across page boundaries.
  • Coding PAGE LIMIT assumes default values.
  • Omitting FIRST DETAIL assigns the heading line value to linenumber.
  • Omitting either LAST DETAIL or FOOTING assigns the PAGE number value to them.
  • Coding FOOTING without LAST DETAIL assigns the FOOTING linenumber to LAST DETAIL linenumber.
  • Coding LAST DETAIL without FOOTING assigns the LAST DETAIL linenumber to FOOTING linenumber.
  • Omitting PAGE LIMIT generates a single-page report of indefinite length without page and line counter registers.
  • AppMaster Builder automatically makes number LINES the maximum for the LINE-COUNTER field, which you can reference at any time. To map LINE-COUNTER (or PAGE-COUNTER) when there is more than one report in a program, code LINE-COUNTER of reportname.

Examples:

 RED   STOCK-REPORT
       CONTROLS ARE FINAL WS-LOCATION-CODE
       PAGE LIMIT IS 50
       FIRST DETAIL 10
       LAST DETAIL 40
       FOOTING 47.
Parent topic: Report Writer Structures
Related tasks
To code a report page description


REFERENCE

Establish summing capability for a non-printing detail item and sum the item in a control footing.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

R[EFERENCE] [IS] dataname PIC[TURE] [IS] picclause
    [DATA-NAME [IS] fieldname]

Parameters:

dataname | Data item being referenced
DATA-NAME fieldname | Name a sum accumulator established by a SUM or REFERENCE clause. Do not define fieldname in Working-Storage. At generation, AMB inserts fieldname after the level number in the report group. DATA-NAME moves the value of the internal SUM accumulator to fieldname.
 | Code DATA-NAME when a SUM UPON clause references a DETAIL report group, when the program references a sum accumulator, or when a sum accumulator requires a data name for qualification.
PIC picclause | Specify the format of dataname. If dataname is a report mock-up field instead of a Working-Storage field, the next matching COBOL picture in the report mock-up is the picclause for dataname.

Comments:

  • When you code a REFERENCE statement, the PIC clause must match the PIC clause in the record description. For example:
    01    COST-DETAIL TYPE DETAIL
       MOCKUP LINE 9
       SOURCE WS-DEPT
       SOURCE WS-EMPLOYEE
       SOURCE WS-CITY
       REFERENCE EMP-CTR   PIC 999
 01    TYPE CONTROL FOOTING
       MOCKUP LINE 9
       SOURCE WS-DEPT
       SUM EMP-CTR
 WS01  EMP-CTR     PIC 999   VALUE 1.
  • If one of the PIC clauses were PIC 9(3), Report Writer would not find a match.
  • In a REFERENCE statement, the data item referenced must be defined in Working-Storage with a VALUE clause. The value in the VALUE clause tells Report Writer the increment to add to the internal accumulator each time the detail line prints. In the previous example, AMB adds 1 to the internal accumulator whenever the detail line prints.
  • The generated program does not describe the referenced field, dataname, on the report mock-up detail line, nor display it on the printed detail line.

Example:

                  LAST COUNT    QUANTITY       QUANTITY     QUANTITY
LOCATION          DATE          IN STOCK       ISSUED       RECEIVED
XXXXXXXXXXXX    99/99/99         ZZZ,ZZ9       ZZZ,ZZ9       ZZZ,ZZ9
                                 -------       -------      --------
TOTAL BY LOCATION:             Z,ZZZ,ZZ9     Z,ZZZ,ZZ9     Z,ZZZ,ZZ9

TOTAL NUMBER OF SALES BY LOCATION: ZZZ,ZZ9
 01    DETAIL-LINE TYPE IS DETAIL.
       MOCKUP LINE 16
       SOURCE WS-LOCATION-CODE     GROUP INDICATE
       SOURCE WS-LAST-COUNT-MONTH    PIC 99
       SOURCE WS-LAST-COUNT-DAY      PIC 99
       SOURCE WS-LAST-COUNT-YEAR     PIC 99
       SOURCE WS-QTY-IN-STOCK
       SOURCE WS-QTY-ISSUED
       SOURCE WS-QTY-RECEIVED
       REFERENCE WS-NO-OF-SALES      PIC 9999
 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE
       MOCKUP LINES 17 THRU 20
       SUM WS-NO-OF-SALES            PIC ZZZ9
Parent topic: Report Writer Structures
Related tasks
To define non-printing detail items
To sum data items in a report


SOURCE

Map Data Division items to output fields. Batch environments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

SOURCE [IS] dataname [iterativeexpression] [PIC
picclause]
    [BLANK [WHEN] ZERO]
    [CHANGE INDICATE|GROUP INDICATE]
    [JUSTIFIED|JUST [RIGHT]
    [DATA-NAME [IS] fieldname]

Parameters:

BLANK WHEN ZERO | Print spaces when SOURCE dataname is zero. COBOL usage rules apply.
CHANGE INDICATE | Print value of SOURCE dataname whenever it changes. See also Considerations below..
DATA-NAME fieldname | Name a sum accumulator established by a SUM or REFERENCE clause. Do not define fieldname in Working-Storage. At generation, AMB inserts fieldname after the level number in the generated report group. DATA-NAME moves the value of the internal SUM accumulator to fieldname. Code the DATA-NAME clause when a SUM UPON clause references DETAIL report group, when the program references a sum accumulator, or when a sum accumulator requires a data name for qualification.
dataname | Data item being referenced; can be report mock-up field or a Working-Storage field.
GROUP INDICATE | Identify an item, such as a header, that prints on the first occurrence of its report group after a control break or a page advance. You can use GROUP INDICATE when a DETAIL type defines a printable item; specify GROUP INDICATE for elementary items. If the RED keyword does not contain a PAGE or a CONTROL clause, a GROUP INDICATE item prints the first time its DETAIL line prints after INITIATE processing.
iterative expression | Generate multiple SOURCE statements for suffixed data items or elements of an array.
JUSTIFIED RIGHT | Right justify the field value. COBOL usage rules apply.
PIC picclause | Specify the format of dataname. If dataname is a report mock-up field instead of a Working-Storage field, the next matching COBOL picture in the report mock-up is the picclause for dataname.

Comments:

  • SOURCE immediately follows the MOCKUP or OVERPRINT clause.
  • SOURCE designates that the item is described in the program Data Division, is the special Report Writer register LINE-COUNTER or PAGE-COUNTER, or is the internal sum accumulator established by Report Writer.
  • In CONTROL FOOTING, PAGE HEADING, PAGE FOOTING, and REPORT FOOTING report groups, SOURCE cannot reference controls or data items referencing controls.
  • To map PAGE-COUNTER (or LINE-COUNTER) when there is more than one report in a program, code PAGE-COUNTER OF reportname.
  • In a DETAIL type entry, use CHANGE INDICATE instead of GROUP INDICATE to suppress printing the item after a page break.

Examples:

 01    DETAIL-LINE TYPE IS DETAIL.
       MOCKUP LINE 16
       SOURCE WS-LOCATION-CODE    GROUP INDICATE
       SOURCE WS-LAST-COUNT-MONTH PIC 99
       SOURCE WS-LAST-COUNT-DAY   PIC 99
       SOURCE WS-LAST-COUNT-YEAR  PIC 99
       SOURCE WS-QTY-IN-STOCK     JUSTIFIED RIGHT
       SOURCE WS-QTY-ISSUED       JUSTIFIED RIGHT
       SOURCE WS-QTY-RECEIVED     JUSTIFIED RIGHT
       REFERENCE WS-NO-OF-SALES   PIC 9999
Parent topic: Report Writer Structures
Related tasks
To map report fields
To sum data items in a report


SUM

Sum data items, and generate an internal SUM accumulator for a SOURCE or REFERENCE data field to be used in a control footing group.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

SUM|+ [IS] dataname [iterativeexpression|dataname] ...
    [UPON detlineidentifier [detlineidentifier] ...]
    [RESET [ON] [FINAL] controlname]
    [DATA-NAME [IS] fieldname]
    [PICTURE|PIC [IS] picclause]

Parameters:

dataname | Data item to reference; can be report mock-up field or a Working-Storage field. Define as a numeric data item.
DATA-NAME fieldname | Name a sum accumulator established by a SUM or REFERENCE clause. Do not define fieldname in Working-Storage. At generation, AMB inserts fieldname after the level number in the generated report group. DATA-NAME moves the value of the internal SUM accumulator to fieldname. Code DATA-NAME when a SUM UPON clause references DETAIL report group, when the program references a sum accumulator, or when a sum accumulator requires a data name for qualification.
iterative expression | Generate multiple SUM statements for numerically suffixed data items or elements of an array.
PIC picclause | Specify the format of dataname. If dataname is a report mock-up field instead of a Working-Storage field, the next matching COBOL picture in the report mock-up is the picclause for dataname. Picclause determines the size of the internal SUM accumulator.
RESET controlname | Set the SUM accumulator to zero after a control break on controlname. If RESET is not coded, the internal SUM accumulator resets to zero after each control break.
UPON detline- identifier | Sum on the printing of a specific detail line, when there is more than one detail line. Detlineidentifier is the name of DETAIL report group.

Comments:

  • To set up a SUM accumulator, identify the data field with a SOURCE or REFERENCE on the detail line, and sum it with a SUM clause on the control footing line. AMB adds the value of dataname1 to its internal sum accumulator each time the dataname1 data item prints for a detail group.
  • SUM is valid for a CONTROL FOOTING report group only. It follows MOCKUP or OVERPRINT clause.
  • The internal SUM accumulator value prints with the CONTROL FOOTING group and then clears.
  • If the description for a printable data item contains a SUM clause, the internal SUM accumulator serves as a data item, that is, Report Writer moves the internal accumulator value to the data item for printing.
  • AMB sums data field values into internal SUM accumulators during GENERATE and TERMINATE processing.

Examples:

Each time DEBIT-LINE generates, add SOURCE amount to the DEBIT-LINE and CREDIT-LINE amount accumulators.

 01    DEBIT-LINE TYPE IS DETAIL.
       MOCKUP LINE 1
       SOURCE AMOUNT               PIC 9(5)
 01    CREDIT-LINE TYPE IS DETAIL.
       MOCKUP LINE 2
       SOURCE AMOUNT               PIC 9(5)
 01    TYPE IS CONTROL FOOTING WS-PRODUCT-CODE.
       MOCKUP LINE 3
       SUM AMOUNT UPON DEBIT-LINE  PIC 9(6)
       SUM AMOUNT UPON CREDIT-LINE PIC 9(6)

Print CONTROL FOOTING and RESET the SUM accumulator to zero after the final control break.

 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
       MOCKUP LINE 15 THRU 21
       SUM WS-QTY-IN-STOCK RESET ON FINAL

RESET the WS-LOCAL-SALES field to continue accumulating a sum until the WS-REGION-SALES control break occurs.

 RED   SALES REPORT
       CONTROLS ARE FINAL WS-REGION-SALES
          WS-LOCAL-SALES
 01     TYPE IS CONTROL FOOTING WS-LOCAL-SALES.
       MOCKUP LINE 5
       SUM WS-LOCAL-SALES RESET ON
           WS-REGION-SALES

Move the value of the NO-OF-SALES accumulator to the TOT-SALES field.

 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
       MOCKUP LINE 12
       SUM NO-OF-SALES DATA-NAME TOT-SALES

Print all values for WS-QTY-IN-STOCK on the detail line in the report and the total of those values in the control footing of the report. Print the total only for WS-NO-OF-SALES in the control footing. When the detail line is prints, add the REFERENCE field value to the SUM accumulator.

 01    DETAIL-LINE TYPE IS DETAIL.
       MOCKUP LINE 16
       SOURCE WS-QTY-IN-STOCK     PIC ZZZ,ZZ9
       REFERENCE WS-NO-OF-SALES   PIC 9999
 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE.
       MOCKUP LINES 17 THRU 23
       SUM WS-QTY-IN-STOCK        PIC Z,ZZZ,ZZ9
       SUM WS-NO-OF-SALES         PIC ZZZ9
Parent topic: Report Writer Structures
Related tasks
To sum data items in a report


SUPPRESS PRINTING

Inhibit printing a report group named in a USE BEFORE REPORTING clause. This structure suppresses the following report group functions:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Line printing
  • LINE NUMBER and NEXT GROUP processing
  • LINE-COUNTER adjusting

Syntax:

SUPPRESS PRINTING

Comments:

  • Use SUPPRESS only with USE BEFORE REPORTING.
  • AMB generates the COBOL statement MOVE 1 TO PRINT-SWITCH. When this statement is processed the warning message, NEXT GROUP WILL BE SUPPRESSED, displays.

Example:

 NTRY  OPEN INPUT OUTPUT
       PERFORM MAIN-PARA
 DPAR  SUPPRESS-CH-REGION SECTION
           USE BEFORE REPORTING CH-REGION
 DPAR  SUPPRESS-CH-REGION-PARA
           IF FIRST-FLG = TRUE
               SUPPRESS PRINTING
Parent topic: Report Writer Structures


TERMINATE

End report processing. The TERMINATE statement also:
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Adds all SUM operands and saves their values
  • Saves current values of all CONTROL items
  • Produces all CONTROL FOOTING report groups beginning with the minor CONTROL FOOTING and ending with FINAL
  • Produces PAGE FOOTING and PAGE HEADING report groups if a page break occurred
  • Produces REPORT FOOTING report group
  • Resets all CONTROL items to their values when TERMINATE was executed

Syntax:

TERMINATE reportname1 [,reportname2] ...

Parameters:

reportname Identify the report. Define reportname in a RED statement in the Report Section of the Data Division.

Comments:

  • If GENERATE processing was not executed for a report between its INITIATE and TERMINATE, TERMINATE does not produce any report groups or perform any related processing. If INITIATE processing does not execute, TERMINATE does not execute.
  • TERMINATE does not close the report file; to do so, code a COBOL CLOSE statement. TERMINATE every report in which you coded INITIATE before you code a CLOSE.
Parent topic: Report Writer Structures
Related tasks
To code report logic


TYPE

Identify a report group, such as a header line, detail line, or footer line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1, page header

TYPE [IS] PAGE HEADING|PH
    [LINE [NUMBER IS] number     ]  [.]
                      PLUS number

Syntax: for Format 2, page footer

TYPE [IS] PAGE FOOTING|PF
    [LINE [NUMBER IS] number]
    [NEXT GROUP [IS] number     ]  [.]
                     PLUS number

Syntax: for Format 3, report header

TYPE [IS] REPORT HEADING|RH
    [LINE [NUMBER IS] number     ]
                      PLUS number
                     number
    [NEXT GROUP [IS] PLUS number]  [.]
                     NEXT PAGE

Syntax: for Format 4, report footer

TYPE [IS] REPORT FOOTING|RF
                      number
    [LINE [NUMBER IS] PLUS number]  [.]
                      NEXT PAGE

Syntax: for Format 5, control headers and footers

TYPE [IS] CONTROL HEADING|CH [FINAL]
controldataname
          CONTROL FOOTING|CF
                      number
    [LINE [NUMBER IS] PLUS number]
                      NEXT PAGE
                     number
    [NEXT GROUP [IS] PLUS number]  [.]
                     NEXT PAGE

Syntax: for Format 6, detail lines

detaildataname TYPE [IS] DE[TAIL]
                      number
    [LINE [NUMBER IS] PLUS number]
                      NEXT PAGE
                     number
    [NEXT GROUP [IS] PLUS number]  [.]
                     NEXT PAGE

Parameters:

CONTROL FOOTING|CF | Print group totals immediately following the detail lines each time a control group ends, that is, when a control break occurs.
CONTROL HEADING|CH | Print heading line(s) before each detail group, that is, when a control break occurs.
controldataname | Designate control data name. Unless FINAL, code controldataname in the corresponding RED keyword CONTROL clause.
DETAIL|DE | Specify the body group, that is, lines containing data items of a report. See also Comments below.
detaildataname | Name of detail line.
FINAL | Specify the highest, most inclusive, control group. Implicit; does not have to be coded in order to be used in a CONTROL FOOTING.
LINE number | Designate the line number where the current header, footer, or detail line prints. Number (maximum 3 digits) must be within the defined page limits. Specify the RED keyword PAGE LIMIT clause.
LINE NEXT PAGE | Print the current header, footer, or detail line on a new page.
LINE PLUS number | Designate the line where the current header, footer, or detail line prints, and optionally insert blank lines. Number (maximum 3 digits) must be within the defined page limits. PLUS increments the line number by number, causing blank lines. A simpler way to print blank lines, however, is to include them in your mock-up.
NEXT GROUP number | Designate the line number where the next TYPE entity prints (for example, a detail line, header, or footer). Number (maximum 3 digits) must be within the defined page limits. Specify the RED keyword PAGE LIMIT clause. See also Comments below.
NEXT GROUP PLUS number | Designate the line where the next TYPE entity prints, and optionally insert blank lines (for example, a detail line, header, or footer). Number (maximum three digits) must be within the defined page limits. PLUS increments the line number number, causing blank lines. A simpler way to print blank lines, however, is to include them in your mock-up. See also Comments below.
NEXT GROUP NEXT PAGE | Print the next TYPE entity on a new page (for example, a detail line, header, or footer). Do not code NEXT PAGE with PAGE FOOTING.
PAGE HEADING|PH | First line(s) on each page. AMB processes PAGE HEADING as the first report group on each page, unless a REPORT HEADING, that is not on a page by itself, precedes it. AMB ignores PAGE HEADING on a page that contains only a REPORT HEADING or REPORT FOOTING. See also Comments below.
PAGE FOOTING|PF | Last line(s) on each page. AMB processes PAGE FOOTING as the last report group on each page of a report, unless a REPORT FOOTING, that is not on a page by itself, follows it. AMB ignores PAGE FOOTING on a page that contains only a REPORT HEADING or REPORT FOOTING. See also Comments below.
REPORT FOOTING|RF | Last line(s) of the report. The TERMINATE statement processes REPORT FOOTING as the last report group.
REPORT HEADING|RH | First line(s) of the report. It is the first report group and processes once per report.

Comments:

  • Enter at least one TYPE statement per report.
  • Code a TYPE statement for each report group in the report, that is, each type of report line.
  • Code at least one detail line for each report, including a summary report. Without a detail line, SUM accumulators are not summed.
  • AMB ignores NEXT GROUP with CONTROL FOOTING, unless CONTROL FOOTING is at the highest level for a control break.
  • Code LINE NUMBER and NEXT GROUP clauses on separate lines.
  • Specify the PAGE HEADING and PAGE FOOTING report groups only if the RED statement has a PAGE LIMIT clause. Specify the CONTROL HEADING or CONTROL FOOTING in the RED CONTROL clause. FINAL is implicit.

Examples:

01     TYPE IS REPORT HEADING
           NEXT GROUP IS NEXT PAGE.
01     TYPE IS PAGE HEADING.
       SOURCE IS PAGE-COUNTER        PIC ZZZ9
01     PART-DETAIL TYPE IS DETAIL.
       MOCKUP LINES 5 THRU 6
       SOURCE IS PM-PART-NO          PIC XXXXXXXX
       SOURCE IS PD-LONG-DESC        PIC X(50)
       SOURCE IS PM-UNIT-BASE-PRICE  PIC $$$,$$9.99
01     TYPE IS CONTROL FOOTING.
       MOCKUP LINES 7
 SUM PM-UNIT-BASE-PRICE PIC $$$$,$$9.99

Print a report heading on line 20.

 01    TYPE IS REPORT HEADING LINE 20.

Insert blank lines in the report by incrementing the line number by two before printing the footer.

 01    TYPE IS REPORT FOOTING LINE PLUS 2.

Print two blank lines between groups. Indentation causes continuation when coding NEXT GROUP PLUS 2.

 01    TYPE IS CONTROL FOOTING WS-LOCATION-CODE
          NEXT GROUP PLUS 2.

Increment the page counter after printing a line.

 01   TYPE IS REPORT HEADING
          NEXT GROUP NEXT PAGE.
Parent topic: Report Writer Structures
Related tasks
To identify report groups
To map report lines


USE BEFORE REPORTING

Code statements that execute before HEADING or FOOTING report groups print. You name the report group in the Report Section of the Data Division. You can specify special processing requirements, including calculations in addition to those specified in the SUM clause, and edits to a report line.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

See also the DECL and DPAR keywords for creating Declarative Section statements, paragraphs, and sections.

Syntax:

USE BEFORE REPORTING identifier

Parameter:

identifier Designate a HEADING or FOOTING report group. Identifier cannot appear in more than one USE BEFORE REPORTING.

Comments:

  • Remember to name the report group in the Report Section of the Data Division.
  • A USE statement follows a section header in a declaratives section and ends with a period and space. The section can consist of paragraphs that define procedures.
  • A USE BEFORE REPORTING statement cannot alter the value of any control data item.
  • The INITIATE, GENERATE, or TERMINATE clauses cannot appear in a paragraph within a USE BEFORE REPORTING.
  • Report Writer ensures that the designated statements execute just before the specified report group.
  • Declarative statements cannot reference non-declarative statements; conversely, non-declarative statements cannot reference a statement name appearing in the declarative portion. The COBOL PERFORM statement is the only exception of a non-declarative that refers to a declarative statement.

Example:

 NTRY  OPEN INPUT
       OPEN OUTPUT
       PERFORM MAIN-PARA
 DPAR  SUPPRESS-CH-REGION SECTION
       USE BEFORE REPORTING CH-REGION
 DPAR  SUPPRESS-CH-REGION-PARA
          IF FIRST-FLG = TRUE
             SUPPRESS PRINTING
Parent topic: Report Writer Structures
Related reference
DECL
DPAR


VALUE

Designate, as literals, any values that can be interpreted as PIC characters, such as embedded Xs and 9s to a mock-up text field. AMB considers two or more consecutive COBOL PIC characters a COBOL PIC clause and all other strings as literals, with the following exceptions
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • The letter A is a literal character
  • A single hyphen is a COBOL picture character; a string of hyphens is a literal.
  • A 9 or an X bounded by spaces is a COBOL PIC; any other character surrounded by spaces is a literal.
  • Lower case letters are literals, not I/O fields.

To distinguish literals from PIC strings, such as the literal EXXON, which would be interpreted as the literal E, followed by the PIC string XX, and the literal ON, paint the word as a data field in the report mock-up and use the VALUE clause when coding the detail line data item description in your program.

Syntax:

VALUE "characterstring" [PIC picclause]
    [DATA-NAME [IS] fieldname]

Parameters:

"characterstring" Designate a literal as follows:
  • First, enter the text field on the mock-up as a data field (that is, a series of Xs).
  • Then, code VALUE "characterstring", where characterstring is the literal value of the text field.
DATA-NAME fieldname Name a sum accumulator established by a SUM or REFERENCE clause. Do not define fieldname in Working-Storage. At generation, AMB inserts fieldname after the level number in the generated report group. DATA-NAME moves the value of the internal SUM accumulator to fieldname.

Code DATA-NAME when a SUM UPON clause references DETAIL report group, when the program references a sum accumulator, or when a sum accumulator requires a data name for qualification.

PIC picclause Specify the format of characterstring.

Examples:

Create the report heading QUARTERLY REPORT FOR EXXON.

====
QUARTERLY REPORT FOR XXXXX
====
 01    TYPE IS PAGE HEADING.
       MOCKUP LINE 1
       VALUE 'EXXON' PIC X(5)
Parent topic: Report Writer Structures


WRITE ROUTINE

Override the COBOL WRITE statement and execute your own routine.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

WRITE ROUTINE [IS] paragraphname

Parameters:

Paragraph-name Name of WRITE ROUTINE paragraph

Comments:

  • If you code WRITE ROUTINE, you can define your report record as a group-level record in the File Section and reference it in your WRITE ROUTINE paragraph.
  • AMB generates a single-field 01-level report record when you code REPORT IS in the FD statement. You can replace REPORT IS with a definition of a group-level record--that is, an 01-level record with elementary data items. AMB generates a 248-byte 01-level report record in Working-Storage, for the largest possible report; it generates a 250-byte record if the RED keyword CODE clause is coded.
  • If FDs are not included in your program, as when accessing GSAM files, you can still create a WRITE routine by defining an 01-level user file record. Report Writer uses this record to generate an 01-level report file record in Working-Storage that stores the report records.

Examples:

FD    INPUT-FILE
       LABEL RECORDS ARE STANDARD
       BLOCK CONTAINS 0 RECORDS.
 01    PART-STOCK-REC                 PIC X(80).
 FD    REPORT-OUTPUT-FILE
       LABEL RECORDS ARE STANDARD
 01    USER-REPORT-RECORD.
       03  USER-REPORT-APS-PART       PIC X(248).
       03  USER-REPORT-USER-PART      PIC X(7).
          .
          .
 RED   STOCK-REPORT
          .
          .
       WRITE ROUTINE IS USER-DEFINED-PARA
          .
          .
 NTRY
          .
          .
 PARA  USER-DEFINED-PARA
          .
          .
       MOVE STOCK REPORT RECORD TO
       ...USER-REPORT-APS-PART
Parent topic: Report Writer Structures


Reserved Words

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The following words are reserved for AMB use:

  • %
  • --
  • $
  • +
  • ++
  • $
  • 01
  • $APS-
  • $CIC-
  • $DB-
  • $DDI-
  • $DLG-
  • $IM-
  • $IMS-
  • $MACRO-
  • $MDB-
  • $MDC-
  • $SC-
  • $SCP-
  • $SCR-
  • $TP-
  • $VS-
  • $VSAM-
  • &
  • &&
  • &COMPILETIME
  • &DEFINE[D]
  • &DEFVAL
  • &INDEX
  • &LENGTH
  • &NUMERIC
  • &PARSE
  • &SUBSTR
  • *EOF*
  • /*
  • <
  • <*
  • <+
  • </
  • <<
  • =
  • @
  • ACCEPT
  • ACCESS
  • ADD
  • ALL
  • ALTERNATE
  • APPLY
  • APSMACS
  • APSSRC
  • ARE
  • ASSIGN
  • ATTR
  • AUXOUT
  • BASIS
  • BEFORE
  • BIND
  • BLANK
  • BLOCK
  • BYTES
  • CA
  • CALL
  • CANCEL
  • CARDIN
  • CBL
  • CF
  • CH
  • CHANGE
  • CHARACTERS
  • CICS
  • CLEAR
  • CLOSE
  • COBIIMES
  • COBMESS
  • CODE
  • CODE-SET
  • COLUMN
  • COMMIT
  • COMP
  • COMPUTATIONAL
  • COMPUTE
  • CONNECT
  • CONTAINS
  • CONTINUE
  • CONTROL[S]
  • COPY
  • COPYLIB
  • CPERFORM
  • DATA
  • DATA-NAME
  • DB-CLOSE
  • DB-ERASE
  • DB-IF
  • DB-MODIFY
  • DB-OBTAIN
  • DB-OPEN
  • DB-ROLLBACK
  • DB-STORE
  • DC
  • DDISYMB
  • DE
  • DEBUG
  • DECL
  • DECLARATIVES
  • DELETE
  • DEPENDING
  • DESTINATION
  • DETAIL
  • DISCONNECT
  • DISPLAY
  • DIVIDE
  • DIVISION
  • DPAR
  • DS
  • EDIT-FLAGS
  • EJECT
  • ELSE
  • ELSE-IF
  • END
  • END-OBTAIN
  • ENTER
  • ENTRY
  • ERASE
  • ERROR
  • ESCAPE
  • EVALUATE
  • EXAMINE
  • EXEC
  • EXHIBIT
  • EXIT
  • FALSE
  • FD
  • FILE
  • FILE-ID
  • FILE-LIMITS
  • FILLER
  • FIND
  • FINISH
  • FIRST
  • FOOTING
  • FRFM
  • GENERATE
  • GET
  • GO
  • GOBACK
  • GROUP
  • HEADING
  • HIGH-VALUE
  • HIGH-VALUES
  • IDM-
  • IF
  • IN
  • INDEX[ED]
  • INDICATE
  • INITIATE
  • INPUT
  • INPUT-OUTPUT
  • INSERT
  • INSPECT
  • IO
  • IS
  • JUST
  • JUSTIFIED
  • KEEP
  • LABEL
  • LAST
  • LEADING
  • LIB1[IN]
  • LIB2[IN]
  • LIB3[IN]
  • LIMIT
  • LIMITS
  • LINE-COUNTER
  • LINE[S]
  • LINK
  • LINKAGE
  • LK
  • LOW-VALUE[S]
  • MACRO
  • MAININ
  • MERGE
  • MOCK
  • MOCKUP
  • MOD-NAME
  • MODE
  • MODIFY
  • MOVE
  • MSG-SW
  • MULTIPLY
  • NARROW
  • NEXT
  • NOMINAL
  • NOT
  • NOTE
  • NTRY
  • NUMBER
  • OBTAIN
  • OBTAIN-BY-KEY
  • OBTAIN-BY-SEARCH
  • OBTAIN-NEXT
  • OBTAIN-PREV
  • OBTAIN-REL
  • OBTAIN-REL-BY-KEY
  • OCCURS
  • OF
  • OMITTED
  • ON
  • OPEN
  • OPT
  • ORGANIZATION
  • OUTPUT
  • OVERPRINT
  • PAGE
  • PAGE-COUNTER
  • PARA
  • PASS
  • PASSWORD
  • PERFORM
  • PF
  • PFKEY-VALUE
  • PH
  • PIC
  • PICTURE
  • PLUS
  • POSTSOUT
  • PRIVIN
  • PROC
  • PROCEDURE
  • PROCESSING
  • QUOTE[S]
  • RD
  • RDREAD
  • READ
  • READY
  • REC
  • RECEIVE
  • RECORD[S]
  • RECORDING
  • RED
  • REDEFINES
  • REFERENCE
  • RELEASE
  • REM
  • RENAMES
  • REPEAT
  • REPORT[S]
  • REPORTING
  • RERUN
  • RESERVE
  • RESET
  • RETURN
  • REWRITE
  • RF
  • RIGHT
  • ROLLBACK
  • SAME
  • SC-CLEAR
  • SCELIB
  • SCRNLIST
  • SCRSYMB
  • SD
  • SEARCH
  • SECTION
  • SEEK
  • SELECT
  • SEND
  • SERVICE
  • SET
  • SIGN
  • SKIP1
  • SKIP2
  • SKIP3
  • SORT
  • SOURCE
  • SPACE[S]
  • SPNM
  • SQL
  • STANDARD
  • START
  • STOP
  • STOP
  • STORE
  • STRING
  • STUB
  • SUBTRACT
  • SUM
  • SUPPRESS
  • SUPRA
  • SYBT
  • SYDD
  • SYEN
  • SYFD
  • SYIO
  • SYLK
  • SYM1
  • SYM2
  • SYMBOLIC
  • SYNC
  • SYNCHRONIZED
  • SYRP
  • SYSDBOUT
  • SYSIN
  • SYSMSG
  • SYSOUT
  • SYWS
  • TERM
  • TERMINATE
  • TEXT
  • TIMES
  • TRACE
  • TRAILING
  • TRANCODE-AREA
  • TRANSFORM
  • TRUE
  • TYPE
  • UNSTRING
  • UNTIL
  • UPDATE
  • UPON
  • USAGE
  • USE
  • USERMACS
  • USERNAME
  • VALUE[S]
  • WHEN
  • WHILE
  • WITH
  • WORK1
  • WORK2
  • WORK3
  • WORK4
  • WORK5
  • WORK6
  • WORK7
  • WORK8
  • WORK9
  • WORKING-STORAGE
  • WRITE
  • WS
  • XCTL
Parent topic: Reference


Run-time Module - A1MVCL

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Programs that use IMS path calls or that read VSAM records into alternate I/O areas require the presence of the A1MVCL run-time module to execute properly. These programs use A1MVCL to move blocks of data to a target location from a source location. Values passed from a program to A1MVCL include:

  • Address of the target area.
  • Offset within the target area.
  • Number of bytes to be overlayed in the target area.
  • Address of the source area.
  • Starting offset within the source area.
  • Number of bytes to move from the source area to the target area.
  • Padding character to use if the number of source bytes is less than the number of bytes to be overlayed in the target area. The default padding character is low-values.

To make the A1MVCL run-time module available to an executing program, copy the following files from your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory to the Enterprise Developer project directory that contains your generated and compiled program.

  • A1MVCL.DLL
  • A1MVCL.LIB

These files must be present in the project directory before you run the program.

Parent topic: Reference
Related reference
APIMSIN
APVSAMIN


S-COBOL Structures

An AppMaster Builder program can be coded in AMB Structured COBOL (S-COBOL) language structures, either in combination with or instead of COBOL statements. S-COBOL structures are procedural, and extend the power of native COBOL, yet simplify and shorten the amount of code you must write.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

You can write a complete AMB program in S-COBOL. There are no differences between S-COBOL and batch COBOL in the Identification, Environment, and Data Divisions. The major differences exist in the Procedure Division.

Reserved Words:

S-COBOL reserved words are the same as ANSI COBOL, plus the following. For a complete list of all AMB reserved words and symbols, see the Help topic Reserved Words.

  • ALWAYS
  • ELSE-IF
  • ESCAPE
  • EVALUATE
  • FALSE
  • FALSX
  • NEVER
  • REPEAT
  • SAGE-TRACE-FLAG
  • TRUE
  • TRUX
  • UNTIL
  • USERNAME (IMS only)
  • WHILE

S-COBOL Structures:

  • You code the S-COBOL structures in paragraphs and statement blocks. A paragraph is denoted by the keyword PARA and a paragraph name, followed by clauses or a statement block. Within a paragraph, indentation determines the exact positioning of statements. A paragraph ends with the next appearance of any Procedure Division keyword.
  • Indentation determines how the statements execute. For example, when you indent a statement under a conditional statement, the indentation tells AMB that this statement is subordinate to the condition.
  • AMB reads an S-COBOL program from top to bottom. The first paragraph performs all other paragraphs. Within paragraphs and statement blocks, statements execute sequentially until conditional statements, PERFORMs, or CALLs modify the sequence of operations. Indentation controls the logical sequence in which lines of source code execute.
  • Code S-COBOL structures in the Program Painter for batch, report, or complex online programs, or in the Program Painter for a simple program.

List of Structures:

The following are the S-COBOL structures.

Verbs
ENTRY

Establish entry point for subprogram.

ESCAPE

Exit from the current paragraph.

EVALUATE

Evaluate conditions; program a decision table.

EXIT PROGRAM

End the execution sequence.

PERFORM

Execute a particular paragraph or section, with or without arguments.

REPEAT

Establish a loop for testing.

SEARCH

Establish looping or conditionals for each WHEN.

STOP RUN

Return control to the operating system.

TRUE/FALSE

Establish true and false flags; test the flags.

UNTIL/WHILE

Form a loop with a test.

USERNAME

Title a procedure generated by the Precompiler.

Conditionals
AT END/INVALID KEY

Test for end-of-file or invalid key condition.

EVALUATE

Evaluate one or more conditions; program a decision table.

IF/ELSE-IF/ELSE

Evaluate one or more conditions.

SEARCH

Establish looping or conditionals for each WHEN condition.

TRUE/FALSE

Establish true and false flags; test the flags.

Error Handling
AT END/INVALID KEY

Test for end-of-file or invalid key condition.

TRUE, FALSE, ALWAYS, NEVER

Use these AMB-supplied flags for testing.

TRUE/FALSE

Establish true and false flags; test the flags.

Flags
TRUE, FALSE, ALWAYS, NEVER

Use these AMB-supplied flags for testing.

Looping
REPEAT

Establish a loop for testing.

UNTIL/WHILE

Form a loop with a test.

Transferring Program Control
ENTRY

Establish entry point for subprogram.

ESCAPE

Exit from the current paragraph.

EXIT PROGRAM

End the execution sequence.

STOP RUN

Return control to the operating system.

General Rules:

  1. When coding paragraph names, at least one character within the first 24 characters must be unique for each paragraph in the program.
  2. Code only one verb per source code line.
  3. Do not code punctuation in the Procedure Division. It is unnecessary and therefore disregarded.
  4. Code punctuation within the Identification, Environment, and Data Divisions that conforms to COBOL rules.
  5. Code structures with consistent indentation. The level of indentation can vary with each new statement block; however, it cannot vary within a statement block of code. We recommend using four additional spaces for each new level of indentation.
  6. Do not code the following structures.
    • PERFORM ... THRU statement
    • GO TO statement
    • SORT|MERGE THRU ... sectionname with INPUT PROCEDURE or OUTPUT PROCEDURE
    • NEXT SENTENCE
  7. Avoid using the double-hyphen (--). The S-COBOL translator frequently creates procedures and flags required for generating ANSI COBOL that are unnecessary and sometimes invalid in S-COBOL. Generated names for these procedures or flags always contain a double-hyphen to avoid conflict with programmed names. Under IMS, the USERNAME parameter can change double hyphens to single hyphens at S-COBOL processing time.
  8. Continue a structure on subsequent lines by coding an ellipsis followed by a space (... ).
  9. Continue a non-numeric literal by splitting the literal and concatenating the parts, which AMB then treats as separate literals. Concatenate non-numeric literals by separating them with an ellipsis, space, two ampersands, and space (... && ), for example,
               REGISTER = " THIS IS A VERY,"
           ... && "VERY LONG LITERAL"
  10. Enclose literals with quotation marks. S-COBOL allows both single and double quotation marks within the same program.
  11. Use any of the following relational operators to make comparisons.
    Type of Comparison Relational Operator

    Greater than

    IS GREATER THAN
IS >

    Not greater than

    IS NOT GREATER
THAN
IS NOT >
IS <=

    Less than

    IS LESS THAN
IS <

    Not less than

    IS NOT LESS THAN
IS NOT <
IS >=

    Equal to

    IS EQUAL TO
IS =

    Not equal to

    IS NOT EQUAL TO
IS NOT =

    Greater than or equal to

    >=

    Less than or equal to

    <=
  12. Create compound conditions by using ANDs or ORs.
  13. Optionally, use a simplified syntax:
    Abbreviated Syntax S-COBOL/COBOL Equivalent
    A = B

    MOVE B TO A

    A B = C

    MOVE C TO A B

    A = B + C

    COMPUTE A = B + C

    B = B + C

    COMPUTE B = B + C

    A = B - C

    COMPUTE A = B - C

    A = B * C

    COMPUTE A = B * C

    A = B / C

    COMPUTE A = B / C

    A = B + (C * D)

    COMPUTE A = B + (C * D)

    A <+ B

    COMPUTE A = A + B

    A </ B

    COMPUTE A = A / B

    A << B

    MOVE B TO A

    A <* B

    COMPUTE A = A * B
  14. Use the above simplified syntax with any of these verbs: ADD, COMPUTE, DIVIDE, MOVE, MULTIPLY, SUBTRACT

Example:

The following example demonstrates control logic without interrupting the flow or readability of the program with a GO TO. Program control is handled entirely by S-COBOL indentation.
001030  PARA   PAYROLL-CALCULATION  /*PARAGRAPH NAME
001040         IF EMPLOYEE-TYPE = 'HRLY'
001050             IF HOURS-WORKED > 40
001060                 HOURS-BASE = HOURS-WORKED * 2
001070                 HOURS-BASE = HOURS-BASE - 40
001080             ELSE
001090                 HOURS-BASE = HOURS-WORKED
001100                 GROSS-PAY = HOURS-BASE * HOURS-RATE
001110         ELSE
001120             GROSS-PAY = EMPLOYEE-SALARY

Because IF conditions generally require an alternative action, you generally code an ELSE-IF or ELSE statement at the same level of indentation as the IF.

Line: 1040

001040         IF EMPLOYEE-TYPE = 'HRLY'

If EMPLOYEE-TYPE is not equal to HRLY, control passes to the corresponding ELSE statement on line 1110. On the other hand, if EMPLOYEE-TYPE is equal to HRLY, lines 1050-1100 execute.

Lines: 1050 - 1120

001050             IF HOURS-WORKED > 40
001060                 HOURS-BASE = HOURS-WORKED * 2
001070                 HOURS-BASE = HOURS-BASE - 40
001080             ELSE
001090                 HOURS-BASE = HOURS-WORKED
001100                 GROSS-PAY = HOURS-BASE * HOURS-RATE

If EMPLOYEE-TYPE is equal to HRLY, lines 1050-1100 execute. In this case, if HOURS-WORKED is not greater than 40, control passes to the ELSE statement at the same indentation (line 1080). Thus, lines 1060-1070 execute only for hourly employees who have worked over 40 hours, while line 1090 executes for hourly employees who have worked 40 hours or less.

Line:

001110         ELSE
001120             GROSS-PAY = EMPLOYEE-SALARY

Executes for employees who are not hourly.

  • AT END/INVALID KEY
    Test the END-OF-FILE or AT END condition for files accessed sequentially, and test the INVALID KEY condition for files accessed randomly.
  • ENTRY
    Establish an entry point in a COBOL subprogram.
  • ESCAPE
    Exit from the current paragraph.
  • EVALUATE
    Perform logic by cases, such as a decision table.
  • EXIT PROGRAM
    End the execution sequence of a program or subprogram and return control to the invoking source.
  • IF/ELSE-IF/ELSE
    Evaluate a condition.
  • PERFORM
    Depart from the normal program execution sequence to execute a particular paragraph or section and then return control to the statement immediately following the PERFORM statement. Optionally, send or receive arguments.
  • REPEAT
    Establish a loop for testing; use with WHILE or UNTIL statement to test the loop at the middle or at the end. This construction eliminates the need for GO TO statements and the multiple tests that are required to form similar loops in COBOL.
  • SEARCH
    Use in the same manner as the COBOL SEARCH verb, including conditionals and looping for each WHEN condition.
  • STOP RUN
    Return control to the operating system.
  • TRUE/FALSE
    Establish flags, set them to true and false, and then test them.
  • TRUE, FALSE, ALWAYS, NEVER
    TRUE, FALSE, ALWAYS, NEVER are data names whose meanings are reserved and automatically provided by S-COBOL.
  • UNTIL/WHILE
    Form a loop with a test at the beginning that allows a subordinate statement block to execute repeatedly, either until or while a single or compound condition is satisfied. The UNTIL statement block executes until the condition is true. The WHILE statement block executes while the condition is true.
  • USERNAME
    Direct either the current AMB paragraph name or one you designate to name a procedure generated by the AMB Precompiler, so that your program follows the conventions, requirements or preferences of a given application or installation.
Parent topic: Reference
Related concepts
Local Program Code
Program Painter
Coding Programs
Related tasks
To code Identification Division comments in the Program Painter
To code an Environment Division Special-Names statement
To code Working-Storage structures
To define data structures in COBOL format
To define data structures in Data Editor format
To include a copyfile
To include a global or local data structure
To define a DB2 table declaration and cursor declarations
To code Linkage Section structures
To define or redefine the Commarea
To begin the Procedure Division for online programs
To code the Procedure Division
To code Procedure Division comments
To define the Input-Output Section
To create a User Rule
To update a User Rule
Related reference
Coding Options
Reserved Words


AT END/INVALID KEY

Test the END-OF-FILE or AT END condition for files accessed sequentially, and test the INVALID KEY condition for files accessed randomly.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

conditionalverb [AT] END ON filename
    statementblock

Syntax: for Format 2

conditionalverb INVALID [KEY] ON filename
    statementblock

Syntax Rules:

  1. S-COBOL defines 05 filename--END PIC X and 05 filename--INV PIC X as flags for the AT END and INVALID KEY conditions for each file.
  2. END ON filename and INVALID ON filename are 88-level file status condition names that S-COBOL provides with the AT END and INVALID KEY flags. You can use these as a condition in any conditional statement.
  3. Flag are set when the file is accessed by a READ, WRITE, etc., statement and before the AT END ON/INVALID KEY ON condition is valid.

Example:

PARA   MAIN-LOGIC
            OPEN INPUT MASTER-FILE
            REPEAT
                READ MASTER-FILE INTO MASTER-REC
                ... INVALID KEY
                    MASTER-REC = HIGH-VALUES
                ELSE-IF MASTER-TYPE = 'A'
                    PERFORM PROCESS-TYPE-A
                ELSE-IF MASTER-TYPE = 'C'
                    PERFORM PROCESS-TYPE-C
                ELSE
                    PERFORM PROCESS-OTHER-TYPES
            UNTIL INVALID KEY ON MASTER-FILE
            CLOSE MASTER-FILE
        STOP RUN
Parent topic: S-COBOL Structures


ENTRY

Establish an entry point in a COBOL subprogram.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

 ENTRY literal
         .
         .
         .
[USING identifier1, ..., identifierN]

General Rules:

  1. S-COBOL considers the paragraph where the program enters the subprogram as a main-logic paragraph.
  2. Code ENTRY immediately after a paragraph name.
  3. Code ENTRY only in a paragraph that is not performed by any other paragraph within the subprogram. At the end of this paragraph, control returns to the calling program, so that you do not need to code EXIT PROGRAM.
  4. If the program reaches an EXIT PROGRAM before the end of the paragraph, control returns to the calling program.
Parent topic: S-COBOL Structures


ESCAPE

Exit from the current paragraph.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

ESCAPE

General Rules:

  1. Processing resumes with the first statement after the statement performing the paragraph, except if ESCAPE occurs in the first or main logic paragraph of:
    • The main program--control returns to the operating system by generating an EXIT PROGRAM statement.
    • A called program--control passes to the first statement after the CALL statement in the calling program. The called program generates an EXIT PROGRAM statement.

Example:

If the condition in line 2220 is true, pass control back to line 2050.
           .
           .
002030  CHECK-DATA
002040       PERFORM STEP-1
002050       ADD 1 TO COUNTER
           .
           .
002210  STEP-1
002220       IF X = 1
002230            ESCAPE
002240       ADD 1 TO FIELD-A
Parent topic: S-COBOL Structures


EVALUATE

Perform logic by cases, such as a decision table.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

Standard evaluation procedure

EVALUATE identifier
WHEN valuexpression1
    statementblock
[          .
           .
           .
WHEN valuexpressionN
    statementblockN    ]
[WHEN OTHER
    statementblock     ]

Syntax: for Format 2

Decision table.

EVALUATE identifier1[, ..., identifierN]
WHEN valuexpression1[, ..., valuexpressionN]
    statementblock
[          .
           .
           .
WHEN valuexpressionN+1[, ..., valuexpressionN+N]
    statementblock     ]
[WHEN OTHER
    statementblock     ]

General Rules:

  1. For run time efficiency, AMB generates the GO TO ... DEPENDING ON translation with Format 1, if the code meets the following criteria.
    • Each WHEN valuexpression is a numeric literal.
    • The literals increase in value from left to right, top to bottom.
    • The largest (last) literal in the statement is less than four times as big as the number of WHEN clauses, not counting WHEN OTHER.
  2. If the above criteria are met and the evaluated field is not defined as numeric, a COBOL error occurs.
  3. Only the first WHEN condition met is executed.
  4. If a WHEN condition is true and it does not include an optional statement block, program control passes to the next statement with the same or less indentation as the word EVALUATE.
  5. To prevent logic from falling through if no WHEN conditions are met, code WHEN OTHER.
  6. EVALUATE does not evaluate 88-levels, as the COBOL II EVALUATE statement does.
  7. If a COBOL II EVALUATE statement is also valid S-COBOL EVALUATE syntax, AMB processes it as S-COBOL statement.
  8. You can evaluate a maximum of 255 conditions/fields. You can code a maximum of 102 WHEN conditions.
  9. You can use EVALUATE to code the NEXT SENTENCE concept of passing program control out of a particular construct to the next executable statement.

Parameters:

identifier | Any COBOL identifier
value-xpression | In Format 1, a data name or a group of COBOL literals, identifiers, and arithmetic expressions forming expression1, expression2, . . ..
 | In Format 2, one of the following ANY, or expression1 [THRU expression2]... OR expression3[THRU expression4]... [OR expression5 [THRU expression6]] Symbols such as =, <, and > are not valid.

Example:

Create a mailing list that includes new subscribers (less than 1 year) and preferred subscribers (more than 5 years) broken down by region.
EVALUATE MONTHS, REGION
WHEN 1 THRU 11, 'EAST'
    WRITE NEW-EAST-REC
WHEN 1 THRU 11, 'WEST'
    WRITE NEW-WEST-REC
WHEN 61 THRU 9999, 'EAST'
    WRITE PREFERRED-EAST-REC
WHEN 61 THRU 9999, 'WEST'
    WRITE PREFERRED-WEST-REC
Parent topic: S-COBOL Structures


EXIT PROGRAM

End the execution sequence of a program or subprogram and return control to the invoking source.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

EXIT PROGRAM

General Rules:

  1. EXIT PROGRAM can appear anywhere in an S-COBOL paragraph.
  2. In a called program, EXIT PROGRAM passes control to the first statement after the CALL statement in the calling program.
  3. An EXIT PROGRAM terminates all AMB programs, unless you include a STOP RUN or GOBACK (IBM COBOL extension).
  4. AMB generates an EXIT PROGRAM at the end of the first paragraph of any called program so that you do not need to code it.
Parent topic: S-COBOL Structures


IF/ELSE-IF/ELSE

Evaluate a condition.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

 IF condition1
    statementblock
[ELSE-IF|ELSE IF condition1
    statementblock
              .
              .
              .
 ELSE-IF|ELSE IF conditionN
    statementblock ]
[ELSE
    statementblock ]

Syntax: for Format 2

COBOLimperativestatement
... COBOLconditionalclause
    statementblock
ELSE-IF|ELSE IF condition1
    statementblock
[             .
              .
              .
ELSE-IF|ELSE IF conditionN
    statementblock ]
[ELSE
    statementblock ]

General Rules:

  1. When IF condition1 is true, its statement block executes. Control then passes to the next statement at the same or less indented level as the IF statement (other than related ELSE-IF or ELSE statements which, by definition, are at the same level as their IF).
  2. When IF condition1 is false, S-COBOL looks for ELSE-IF statements at the same level. If such ELSE-IF statements are present, the conditions are evaluated one after the other. If one of the conditions is true, its statement block executes. Control then passes to the next statement at the same or less indentation as the IF statement (other than related ELSE-IF or ELSE statements).
  3. If no ELSE-IF statements are present, or if the IF condition and the ELSE-IF conditions are all false, control passes to the statement block subordinate to the ELSE statement; if no ELSE statement is present, control passes to the next statement at the same or less indentation as the IF and ELSE-IF statements.
  4. If an ELSE-IF statement has no subordinate statement block and the condition is true, control passes to the next statement at the same or less indentation level as the ELSE-IF statement.
  5. You can nest up to fourteen IF levels.
  6. The last IF, ELSE-IF, or ELSE coded in a related series requires a subordinate statement block.
  7. With Format 2, you can form conditional constructions similar to IF, ELSE-IF, ELSE by combining a COBOL imperative verb and its conditional clauses with ELSE-IF and ELSE statements. Verbs that permit this construction are:
    ADD, RETURN, CALL, REWRITE, COMPUTE, START,
DELETE, STRING, DIVIDE, SUBTRACT, MULTIPLY,
UNSTRING, READ, WRITE.
  8. You can use the IF construct to code the NEXT SENTENCE concept of passing program control out of a particular construct to the next executable statement. See "Example".
  9. AT END and INVALID KEY conditional clauses can be combined with ELSE-IF and ELSE statements.

Example:

If line 2020 is false, pass control back to line 1020, the first statement after the PERFORM statement, because there is no ELSE-IF or ELSE coding associated with this IF, and the first character at the same or less indentation as this IF is a new paragraph name, which denotes the end of the preceding PERFORMed paragraph. If the line 2020 condition is true, execute its subordinate statement block (lines 2030 through 2170) and return control to line 1020.

After line 2030 is executed, test line 2040. If the condition in line 2040 is true, execute lines 2050 through 2071; pass control to line 2170. If line 2040 is false, test line 2080, etc. If lines 2040, 2080, and 2120 are false, execute the ELSE statement block (line 2160) and pass control to line 2170.
001010         PERFORM EMPLOYEE-BENEFIT-DEDUCTION
 001020             MOVE ...
                      .
                      .
 002010  PARA   EMPLOYEE-BENEFIT-DEDUCTION
 002020         IF EMPL-COVERAGE NOT = SPACES
 002030             PERFORM CALC-BASIC-BEN
 002040             IF EMPL-COVERAGE-TYPE = 'EXTRA'
 002050                 PERFORM CALC-EXTRA-BEN
 002060                 PERFORM CALC-DENTAL-BEN
 002070                 BEN-FIELD = XTRA-BEN +
 002071                 ... DENTAL-BEN
 002080             ELSE-IF EMPL-COVERAGE-TYPE =
 002081             ... 'FAMILY'
 002090                 PERFORM CALC-FAMILY-BEN
 002100                 PERFORM CALC-DENTAL-BEN
 002110                 BEN-FIELD = FAMILY-BEN +
 002111                 ... DENTAL-BEN
 002120             ELSE-IF EMPL-COVERAGE-TYPE =
 002121             ... 'DENTAL'
 002130                 PERFORM CALC-DENTAL-BEN
 002140                 BEN-FIELD = BASIC-BEN +
 002141                 ... DENTAL-BEN
 002150             ELSE
 002160                 BEN-FIELD = BASIC-BEN
 002170             EMPL-DED-FIELD =
 002171             ... BEN-FIELD * .5 / 12
 002180
 002190     PARA  CALC-BASIC-BEN
Nest conditional statements.
IF condition1
    statementblock1
    IF condition2
        IF condition3
    statementblock2
        ELSE-IF condition4
        ELSE-IF condition5
    statementblock3
        ELSE
    statementblock4
    ELSE
    statementblock5
        IF condition6
            IF condition7
    statementblock6

    statementblock7
Make the MULTIPLY function conditional by ON SIZE ERROR.
            WS-NET-PAY = EMP-HOURS *
            ... EMP-HOURLY-RATE
            ... ON SIZE ERROR
                PERFORM PRINT-ERROR-MESSAGE
                DISPLAY SSNO WS-NET-PAY
                WS-NET-PAY  WS-DEDUC = 0
            ELSE-IF EMP-HOURLY-RATE = MIN-WAGE
                PERFORM CALC-DEDUC-MIN
            ELSE-IF EMP-HOURLY-RATE < 5.00
                PERFORM CALC-DEDUC-1
            ELSE-IF EMP-HOURLY-RATE >= 5.00
                PERFORM CALC-DEDUC-2
                IF EMP-HOURLY-RATE > 20.00
                    DISPLAY SSNO
                    ... EMP-HOURLY-RATE
            ELSE
                DISPLAY SSNO  EMP-HOURLY-RATE
                PERFORM PRINT-ERROR-MESSAGE
            NET-PAY = WS-NET-PAY - WS-DEDUC
Using a NEXT SENTENCE construction, the following S-COBOL code:
 PARA   CALC-BENEFIT
            BEN-FIELD = ZERO
            IF PERM-PART-TIME
                PERFORM GROUP-A-CALC
                IF HRS-WORKED > 25
                    BEN-FIELD =
                    ... BEN-FIELD * 1.25
            ELSE-IF PART-TIME
            ELSE-IF FULL-TIME
                PERFORM GROUP-B-CALC
            EMPL-REC-BEN-FIELD =
            ... BEN-FIELD
Replaces the following COBOL code:
CALC-BENEFIT.
    MOVE ZERO TO BEN-FIELD.
    IF PERM-PART-TIME
        PERFORM GROUP-A-CALC
        IF HRS-WORKED > 25
            MULTIPLY BEN-FIELD BY 1.25
        ELSE
            NEXT SENTENCE
    ELSE
        IF PART-TIME
            NEXT SENTENCE
        ELSE
            IF FULL-TIME
                PERFORM GROUP-B-CALC
            ELSE
                NEXT SENTENCE.
    MOVE BEN-FIELD TO EMPL-REC-BEN-FIELD.
Parent topic: S-COBOL Structures


PERFORM

Depart from the normal program execution sequence to execute a particular paragraph or section and then return control to the statement immediately following the PERFORM statement. Optionally, send or receive arguments.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

Perform a paragraph.

PERFORM paragraphname

Syntax: for Format 2

Perform a paragraph and pass arguments.

PERFORM paragraphname (actualargument1[[,]
... actualargument2[,] ... actualargumentN])
                      .
                      .
                      .
PARA  paragraphname ([+|-]formalargument1[[,]
      ... [+|-]formalargument2[,] ... [+|-]formalargumentN])

General Rules:

  1. When continuing a list of arguments onto one or more other lines, do not break an argument.
  2. The number of actual arguments must equal the number of formal argument names and be in the same order.

Parameters:

+|- | A plus (+) or minus (-) sign preceding a formalargument passes values between actual arguments and formal arguments, as follows:
 | With a plus sign (+), PERFORM passes the actualargument value to formalargument after the paragraph executes. The program does not return the formalargument value to actualargument.
 | With a minus sign (-), PERFORM passes the formalargument value to the actualargument after the paragraph executes.
 | If there is no plus or minus sign, the PERFORM passes the actualargument to its corresponding formalargument. After the paragraph executes, PERFORM passes the formalargument back to its corresponding actualargument.
actualargu-ment | Values you send to or receive from a formalargument in the paragraph; can be literals, identifiers, arithmetic expressions, variables, or index names.
formal-argument | Values you receive from or send to an actualargument in the PERFORM statement.
paragraph-name | Name of paragraph to perform.

Example:

PERFORM PARA-1( 'ABC', ABC-FLD, RESULT)
          .
          .
          .
PARA-1( +ARG1, +ARG2, -'Y')
Generates:
    MOVE 'ABC' TO ARG-1
    MOVE ABC-FLD TO ARG2
    PERFORM PARA-1 THRU .......
    MOVE 'Y' TO RESULT
Perform GET-SALARY (line 5010); pass the literal 20 to HOURS-WORKED and the value of HOURLY-RATE to PAY-RATE before calculating TOT-PAY (line 5020). After the GET-SALARY paragraph executes, pass the value of PAY-RATE to HOURLY-RATE and the value of TOT-PAY to WEEKLY-PAY.
000100  NTRY
   .
   .
   .
003010            IF CLASS = 'HALF-TIME'
003020                PERFORM GET-SALARY( 20,
003021                ... HOURLY-RATE, WEEKLY-PAY)
003030            ELSE
003040                PERFORM GET-SALARY( 40,
003041                ... HOURLY-RATE, WEEKLY-PAY)
003050            WEEKLY-PAY = WEEKLY-PAY * TAX
003060            COMPUTE MEDICAL-DEDUC =
003061            ... HOURLY-RATE * 1.50
   .
   .
   .
005010  PARA   GET-SALARY( +HOURS-WORKED,
005011        ... PAY-RATE,-TOT-PAY)
005020            TOT-PAY = HOURS-WORKED * PAY-RATE
   .
Parent topic: S-COBOL Structures


REPEAT

Establish a loop for testing; use with WHILE or UNTIL statement to test the loop at the middle or at the end. This construction eliminates the need for GO TO statements and the multiple tests that are required to form similar loops in COBOL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

REPEAT
    statementblock
UNTIL|WHILE condition
 [  statementblock    ]

Syntax: for Format 2

REPEAT VARYING|LINKING indexname|identifier1
... [FROM indexexpression]|[arithmeticexpression]
... [BY literal]|[identifier2]
    statementblock
UNTIL|WHILE condition
 [  statementblock    ]

Syntax: for Format 3

REPEAT VARYING indexname|identifier1
... [FROM indexexpression][arithmeticexpression1]
... [BY literal]|[identifier2]
... [DOWN] TO|THRU arithmeticexpression2
 [  statementblock    ]

Syntax: for Format 4

REPEAT LINKING indexname|identifier1
... [FROM indexexpression][arithmeticexpression1]
... BY identifier2
... [DOWN] TO arithmeticexpression2
 [  statementblock    ]

Syntax: for Format 5

REPEAT VARYING|LINKING clause1
                      .
                      .
                      .
[... VARYING|LINKING clauseN]
 [  statementblock    ]
UNTIL|WHILE condition
 [  statementblock    ]

General Rules:

  1. The statement block subordinate to the REPEAT, and any statement block subordinate to the WHILE or UNTIL, forms the loop and executes under control of the conditions specified with WHILE or UNTIL.
  2. If the WHILE or UNTIL does not have a subordinate statement block, the condition is tested at the end of the loop. Control returns to the beginning of the REPEAT statement block until the WHILE condition is false or the UNTIL condition is true. The next statement executed is the first one with the same or less indentation than the REPEAT/WHILE or REPEAT/UNTIL.
  3. If the WHILE or UNTIL has a subordinate statement block, it establishes a loop which contains a test in the middle. When the WHILE condition is FALSE or the UNTIL condition is true, control passes out of the loop to the next statement with the same or less indentation than the REPEAT, without executing its statement block.
  4. In the following format, AMB tests the condition after the REPEAT statementblock1 executes.
    REPEAT
    statementblock
    UNTIL condition

    statementblock3
  5. Be careful using this format for reading records--it can read the last record twice.
  6. In the following format, AMB tests the condition after the REPEAT statementblock1 executes, but before the UNTIL statementblock2 executes. When the UNTIL condition is true, the UNTIL statemenblock2 does not execute.
    REPEAT
    statementblock
    UNTIL condition
    statementblock statementblock3
  7. Coding an extraneous WHILE or UNTIL causes an endless loop, if the looping condition is satisfied by the REPEAT VARYING/LINKING preceding it.
  8. DOWN is generally used if literal or identifier2 is negative at execution, and used if positive. The loop executes until:
    UNTIL indexname identifier1 <
arithmeticexpression2
  9. With the TO option, the loop executes to, but not including, the stop-point. With the THRU option, the loop executes through and including the stop-point.
  10. If FROM is not coded, the default is the value of indexname or identifier1 at the time of execution.
  11. If BY is not coded, the default is BY 1 (or -1, if DOWN TO/THRU is coded).
  12. AMB initializes the index or identifier is immediately before the REPEAT loop begins and increments it each time the loop repeats, immediately before the statement block repeats.
  13. For the identifier to be treated as an index, the indexed data element structure must be present in the program during AMB precompilation, otherwise subscript processing is assumed.
  14. To copy data containing an indexed structure, use the % INCLUDE statement.

Parameters:

arithmetic-expression | A legal arithmetic relation-condition
indexexpression | Format can be literalidentifier +|- literalindexname
identifier2 | Names a table entry, such as a data name with an OCCURS clause

Example:

Read header records from a file, move the relevant data to a table, and then print the table.
002010  NTRY
002020         LINE-SUB = 1
002030         PRINT-TABLE = SPACES
002040         OPEN INPUT INPUT-FILE
002050         ... OUTPUT PRINT-FILE
002060
002070         /* BEGIN FIRST LOOP
002080         REPEAT
002090             READ INPUT-FILE
002100         UNTIL AT END ON INPUT-FILE
002110             IF REC-TYPE = 'HDR'
002120                 WORK-FIELD = INPUT-DATA
002130                 IF WORK-FIELD NOT = SPACES
002140                     COLUMN-SUB = 0
002150                     /* BEGIN SECOND LOOP
002160                     REPEAT
002170                         COLUMN-SUB = COLUMN-SUB + 1
002180                         PRINT-COL (LINE-SUB, COLUMN-SUB) =
002190                         ... WORK-FIELD-CHAR (COLUMN-SUB)
002200                     UNTIL COLUMN-SUB = COLUMN-SUB-LIMIT
002210                     ... OR WORK-FIELD-CHAR (COLUMN-SUB) =
002211                     ... '/'
002220                     /* END OF SECOND LOOP
002230                     LINE-SUB = LINE-SUB + 1
002240         /* END OF FIRST LOOP
002250
002260         PERFORM WRITE-PRINT-TABLE
002270         CLOSE INPUT-FILE PRINT-FILE
002280
002290  PARA   WRITE-PRINT-TABLE
002300             LINE-SUB = 1
002310             WHILE PRINT-LINE (LINE-SUB) NOT = SPACES
002320             ... AND LINE-SUB NOT > LINE-SUB-LIMIT
002330                 WRITE PRINT-REC FROM PRINT-LINE (LINE-SUB)
002340                 LINE-SUB = LINE-SUB + 1
Perform the same function as the second loop in the preceding example, but use VARYING to set and increment COLUMN-SUB.
    IF WORK-FIELD NOT = SPACES
        REPEAT VARYING COLUMN-SUB FROM 1 BY 1
            PRINT-COL (LINE-SUB, COLUMN-SUB) =
            ... WORK-FIELD-CHAR (COLUMN-SUB)
        UNTIL COLUMN-SUB = COLUMN-SUB-LIMIT
        ... OR WORK-FIELD-CHAR (COLUMN-SUB) = '/'
        LINE-SUB = LINE-SUB + 1
Use REPEAT ... VARYING to move data items in diagonal sequence (upper right to lower left) from a two-dimensional table to a one-dimensional table. Terminate the loop when after DOWN THRU.
    REPEAT VARYING ROW-SUB FROM 1 BY 1
    ... VARYING COLUMN-SUB FROM 5 DOWN THRU 1
        X-FIELD (ROW-SUB) =
        ... TABLE-ELEMENT (ROW-SUB, COLUMN-SUB)
Use II as the pointer, MY-CHAIN for the initial setting, BLOCK-LINK for the linking element in the table, and ZERO to establish when to stop.
             .
 01     BLOCK-STRUCTURE.
        02  BLOCK    OCCURS 250 TIMES.
            03 BLOCK-LINK  PIC S9(9) COMP SYNC.
            03 BLOCK-DATA  PIC X(20).
             .
 NTRY
        REPEAT LINKING II FROM MY-CHAIN
       ... BY BLOCK-LINK TO ZERO
           PERFORM PASS-DATA( BLOCK-DATA (II))
             .
 PARA  PASS-DATA(+PASS-DATA-BLOCK)
             .
Generated COBOL code:
    MOVE MY-CHAIN TO II.
    GO TO G--002.
G--001.
    MOVE BLOCK-LINK (II) TO II.
G--002.
    IF II NOT = ZERO
         MOVE BLOCK-DATA (II) TO PASS-DATA-BLOCK
         PERFORM PASS-DATA THRU PASS-DATA--XIT
         GO TO G--001.

AMB uses SET in the generated code if the subscript is an index; otherwise, AMB uses MOVE as shown above.

Parent topic: S-COBOL Structures


SEARCH

Use in the same manner as the COBOL SEARCH verb, including conditionals and looping for each WHEN condition.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

SEARCH identifier1 VARYING indexname|identifier2
... [[AT] END]
    statementblock
[WHEN searchcondition1
    statementblock  ]
         .
         .
[WHEN searchconditionN
    statementblock  ]

Syntax: for Format 2

SEARCH ALL identifier [[AT] END]
    statementblock
WHEN searchcondition
    statementblock

Example:

Use SEARCH to achieve the NEXT SENTENCE concept. If the condition in lines 1040-1050 is true, pass control to line 1110.
001010  PARA   SEARCH-TABLE
001020             SEARCH STOCK-ELEMENT AT END
001030                 PERFORM END-ROUTINE
001040             WHEN QUAN-ON-HAND (STOCK-INDEX) NOT <
001050             ... QUAN-NEEDED (STOCK-INDEX)
001060             WHEN QUAN-ON-HAND (STOCK-INDEX) = ZERO
001070                 PERFORM NO-STOCK-ROUTINE
001080             WHEN QUAN-ON-HAND (STOCK-INDEX) <
001090             ... QUAN-NEEDED (STOCK-INDEX)
001100                 PERFORM DETERMINE-IF-ORDER-ROUTINE
001110             WORK-QUAN = QUAN-ON-HAND (STOCK-INDEX)
Parent topic: S-COBOL Structures


STOP RUN

Return control to the operating system.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

STOP RUN

General Rules:

  1. STOP RUN can appear anywhere in an S-COBOL program.
  2. AMB generates a STOP RUN at the end of the first paragraph of an S-COBOL program and at the end of the first paragraph of a called program that compiles independently of the main program.
Parent topic: S-COBOL Structures


TRUE/FALSE

Establish flags, set them to true and false, and then test them.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

TRUE|FALSE dataname1 [dataname2 [... datanameN]]

General Rules:

  1. For each dataname coded, S-COBOL provides an 02-level conditional variable and an associated 88-level condition name entry in an 01 GENERATED-FLAGS area of Working-Storage. AMB adds a --FLG suffix to dataname to create the 02-level entry, and dataname itself becomes the 88-level entry. AMB always assigns VALUE 'T' to the 88-level condition name, never VALUE 'F'. For example

    The following code in the Procedure Division

          .
      .
TRUE THERE-ARE-NO-ERRORS
FALSE WITHIN-RANGE
      .
       .
       .

    Generates

    WORKING-STORAGE SECTION.
       .
       .
02  THERE-ARE-NO-ERRORS--FLG    PIC X.
    88  THERE-ARE-NO-ERRORS    VALUE 'T'.
02  WITHIN-RANGE--FLG    PIC X.
    88  WITHIN-RANGE    VALUE 'T'.
  2. If, for debugging purposes, you want to display a generated flag, add the --FLG suffix to dataname in the DISPLAY statement. For example, TRUE THERE-ARE-NO-ERRORS generates MOVE TRUE TO THERE-ARE-NO-ERRORS--FLG.
  3. If only true statements, such as TRUE WITHIN-RANGE, or only false statements, such as FALSE WITHIN-RANGE, are coded for dataname, a warning message indicates a logic error.
  4. S-COBOL minimizes the code required to test the flags established and set by the TRUE/FALSE verbs.
    • Code WHILE THERE-ARE-NO-RECORDS instead of WHILE THERE-ARE-NO-RECORDS--FLG = TRUE.
    • Code IF NOT WITHIN-RANGE instead of IF WITHIN-RANGE--FLG = FALSE.

Example:

Set two undefined flags, THERE-ARE-NO-ERRORS and WITHIN-RANGE to TRUE (line 3030). Define these flags in Working-Storage (88-level condition name flags), because this is the first TRUE or FALSE statement for either flag in this program. If the condition in line 3060 is true, set the THERE-ARE-NO-ERRORS flag to FALSE. If either condition in line 3110 is true, set the WITHIN-RANGE flag to FALSE. As long as the value of the THERE-ARE-NO-ERRORS flag is TRUE, perform the loop. Inside the loop test the other flag, WITHIN-RANGE. If the value is TRUE, execute the subordinate statement block.
.
003030         TRUE THERE-ARE-NO-ERRORS
003031         ... WITHIN-RANGE
   .
003060         IF CODE-IN NOT NUMERIC
003070             FALSE THERE-ARE-NO-ERRORS
   .
003110         IF COUNT > 372 OR COUNT < 50
003120             FALSE WITHIN-RANGE
   .
003150         WHILE THERE-ARE-NO-ERRORS
003160             IF WITHIN-RANGE
Parent topic: S-COBOL Structures


TRUE, FALSE, ALWAYS, NEVER

TRUE, FALSE, ALWAYS, NEVER are data names whose meanings are reserved and automatically provided by S-COBOL.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

Automatically generated in Working-Storage

01  GENERATED-FLAGS.
    02  TRUX        PIC X  VALUE 'T'.
        88  ALWAYS         VALUE 'T'.
        88  NEVER          VALUE 'F'.
    02 FALSX        PIC X  VALUE 'F'.

Comments:

Because TRUE and FALSE are reserved words on some systems, S-COBOL changes every occurrence of TRUE and FALSE to TRUX and FALSX, and generates the flags accordingly.

Parent topic: S-COBOL Structures


UNTIL/WHILE

Form a loop with a test at the beginning that allows a subordinate statement block to execute repeatedly, either until or while a single or compound condition is satisfied. The UNTIL statement block executes until the condition is true. The WHILE statement block executes while the condition is true.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax: for Format 1

REPEAT
        .
        .
UNTIL|WHILE condition1 [AND|OR condition2
... [... AND|OR conditionN]]
    statementblock

Syntax: for Format 2

REPEAT
    statementblock1
UNTIL condition
      statementblock2

Syntax: for Format 2

REPEAT
    statementblock1
UNTIL condition
      statementblock2

statementblock3

General Rules:

  1. Use these statements with REPEAT to test a condition at the middle or end of a loop.
  2. In the Format 2, AMB tests the condition after the REPEAT statementblock1 executes. Be careful using this format for reading records--it can read the last record twice.
  3. In the Format 3, AMB tests the condition after the REPEAT statementblock1 executes, but before the UNTIL statementblock2 executes. When the UNTIL condition is true, the UNTIL statemenblock2 does not execute.

Examples:

Find the first X in a string of characters.
PARA   FIND-X
            A-SUB = 1
            UNTIL A-SUB > 100
            ... OR CHAR (A-SUB) = "X"
                A-SUB = A-SUB + 1
            IF A-SUB <= 100
                CHARACTER-COUNT = A-SUB
            ELSE
               .
               .
               .
Use WHILE to achieve the same results.
        WHILE A-SUB <= 100
        ... AND CHAR (A-SUB) NOT = 'X'
Parent topic: S-COBOL Structures


USERNAME

Direct either the current AMB paragraph name or one you designate to name a procedure generated by the AMB Precompiler, so that your program follows the conventions, requirements or preferences of a given application or installation.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Syntax:

USERNAME paragraphname

General Rules:

  1. To activate any USERNAME statement, select the USERNAME option at compile time from the AMB Precompiler Options window; otherwise, the paragraph name for a generated procedure is G--nnn, where G means generated and nnn begins with 001 and increases by one for each generated paragraph name in top-down order.
  2. When USERNAME is selected, AMB creates paragraph names as follows:
    • AMB generates single dashes instead of double dashes.
    • AMB uses the current paragraph name, unless USERNAME is coded in a paragraph. Then it uses that paragraph name until the end of the paragraph.
  3. USERNAME paragraph applies only to names assigned for procedures generated as the direct result of code within the paragraph where USERNAME appears. When more than one USERNAME is coded in a paragraph, AMB assigns the first user-designated paragraph name until it is overrided by a second name in the AMB processing sequence.
  4. USERNAME does not appear in the generated code.
  5. Be careful to avoid any naming conflicts that can arise with USERNAME.
Parent topic: S-COBOL Structures


Time Field Formats

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Valid mask characters are HH (hour), MM (minute), SS (second), *s, and special characters. Seconds are optional.

Append your format with asterisks to indicate the AM and PM indicators that you specify, using a one-to-one correspondence. For example, if your indicators are A.M. and P.M., append **** to your format; if they are AM and PM, append ** to your format.

Hours, minutes, and seconds must be in the same order in both the input and output formats. For example:

Input Format | HHMMSS
Output Format | HH.MM.SS**
Parent topic: Reference
Related reference
Input Representation


User Interface Reference

Describes each component of the various user interfaces that make up AppMaster Builder, on the field and control level.
Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Analysis Option
  • AppMaster Builder Preferences
  • AppMaster Builder Perspective
  • Data View Manager
  • Distributed Generation Server - Mainframe
  • Distributed Generation Server - PC
  • Job Queue
  • Project Object Properties
  • Online Express
  • Screen Painter
  • User Areas
Parent topic: Reference


Analysis Option

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Analysis Browser
  • Analysis Browser Options
Parent topic: User Interface Reference


Analysis Browser

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Click this to find the component that appears in the field at the top of the Browser.
Analysis Browser Options
Click this to set Analysis Browser Options
Parent topic: Analysis Option
Related concepts
Browsing the Analysis
Handling Changes
Related tasks
To set options for the analysis browser


Analysis Browser Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Item name filter
Type an application component for which you want to set Analysis Browser options.
Show an item’s direct references only
Check this to show an application component’s direct references only. This is the default.
Show only items that are out-of-date
Check this to show only application components that have been changed but not generated. The default is unchecked.
Item types
Check all appropriate boxes to indicate what components you want to see listed in the Analysis Browser.
Parent topic: Analysis Option
Related concepts
Analysis Browser Features and Options
Related tasks
To set options for the analysis browser


AppMaster Builder Preferences

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • AppMaster Builder
  • Color dialog box
  • Customization
  • Database View
  • Editors
  • Editors - Program Painter
  • Editors - Program Painter - Colorization
  • Editors - Program Painter - Content Assistant
  • Editors - Report Painter - Colorization
  • Environment
  • International
  • Job Queue
  • Logging
  • Tooltip - Report
  • Tooltip - Screen
  • Tooltip - Text
  • Output
  • Workgroup dialog box
Parent topic: User Interface Reference


AppMaster Builder

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Project path
The full path to the current AMB project.
User area
Shows the path to the user area for the current user. The default is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\AMBWorkArea\username.
Workgroup name
Shows the name of a workgroup library file that contains the locations AMB uses when searching for project objects. You can set or change the workgroup library file from the Workgroup preferences page.
Select
Click this to invoke the Workgroup preferences page and populate the Workgroup name field.
Compile in COBOL Project
Check this to automatically copy generated code to the specified Enterprise Developer COBOL project and automatically compile the code in the COBOL project. Use the drop-down list to select a project.
New
Create an Enterprise Developer COBOL project in which to copy and compile generated AMB code.
Parent topic: AppMaster Builder Preferences
Related concepts
Object Properties
Generating Code
Compiling in a COBOL project
Related tasks
To set AppMaster Builder preferences
To create a Program Painter program
To specify a workgroup


Color dialog box

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Basic colors
Shows all colors defined by AppMaster Builder. Click a color block to select it.
Custom colors
Shows all defined custom colors. Click a color block to select it.
Define Custom Colors
Click this to define a new custom color.
Custom color pallet
Shows an array of colors. Move the cross hairs over the colors to find a new color.
Slider bar
Shows varying degrees of color saturation. Slide the arrow up and down to find a new color saturation.
Color|Solid box
Shows the new custom color.
Hue field
Shows a number corresponding to the hue of the color shown in the Color|Solid box. Optionally type a number into the field to change the hue.
Sat field
Shows a number corresponding to the saturation of the color shown in the Color|Solid box. Optionally type a number into the field to change the saturation.
Lum field
Shows a number corresponding to the luminescence of the color shown in the Color|Solid box. Optionally type a number into the field to change the luminescence.
Add to Custom Colors
Click this to add the color shown in the Color|Solid box to Custom colors.
Parent topic: AppMaster Builder Preferences
Related tasks
To customize the Program Painter
To set AppMaster Builder preferences
To customize the Report Painter
Related reference
Editors - Program Painter - Colorization


Customization

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Load current application only
Check this to load your current application only, but with all its objects. If AMB cannot find the last active application, it displays a message and loads all applications and their components.

To load all applications and their objects, uncheck both this and Expand selected application.

Note: With this option checked, you cannot add a new application.
Expand selected application
Check this to delay loading the actual application objects until you expand the application. AMB automatically refreshes the application with updated components if another user has modified a component.

To load all applications and their objects, uncheck both this and Load current application only.

Expand all items in the application
Check this to automatically expand and show all objects in an application when initially loaded into the AppMaster Builder perspective.
Enable drag drop
Check this to enable you to reorder objects under a parent program in the Program Explorer.
Load and update program attributes
Check this to automatically load and update all program attributes, including those for programs in workgroups located on the mainframe. Uncheck to improve loading speed.
Also delete generated screen symbols
Check this to enable the deletion of generated screen symbols from the Project Explorer.
AppMaster Builder Console
Check this to clear the AppMaster Builder console in Eclipse before each generation process begins.
Micro Focus Console
Check this to clear all Micro Focus consoles in Eclipse before each generation process begins.
Parent topic: AppMaster Builder Preferences
Related tasks
To set AppMaster Builder preferences
To reorder objects under a parent program


Database View

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Automatically build Database View after each load
Check this to instruct AppMaster Builder to build symbols when loading from the Database View Manager.
Use File Tailoring for Dataview generation
Check this to instruct AppMaster Builder to apply File Tailoring when generating a database view.
Parent topic: AppMaster Builder Preferences


Editors

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Alternate Editor
The full path to and executable file name of a third-party editor to use instead of the default AppMaster Builder editor.
Note: Preferences specified for Program Painter and Report Painter do not apply to third-party editors.
Background color
The default background color used for the Program Painter and the Report Painter.
Default foreground
The foreground color used with color preferences set for each AppMaster Builder editor.
Read-Only mode
Background color
The background color used in each AppMaster Builder editor when viewing code in read-only mode, which applies to mainframe files and protected files.
Basic Color mode group
Use basic foreground color
Check to set one background and foreground color combination.
Important: When checked, this setting overrides the colors set in Background color and Default foreground on this page. It also overrides colors set on the Program Painter and Report Painter Colorization preferences pages.
Basic colors
Double-click one of the six color combinations to set the Background color and Foreground color fields. Available when Use basic foreground color is checked.
Note: The Basic colors label reflects the color combination selected.
Background color
The basic background color set in the editor. Populate this field by double-clicking one of the color combinations under Basic colors. Applies when Use basic foreground color is checked.
Foreground color
The basic foreground color set in the editor. Populate this field by double-clicking one of the color combinations under Basic colors. Applies when Use basic foreground color is checked.
Cursor style group
Use cross hair cursor
Check this to use a cross-hair cursor in the Program and Report Painters.
Color
Sets the color used for the cross-hair cursor. Click to invoke the Color dialog box for color selection. Available when Use cross hair cursor is checked.
Size
The line thickness of the cross-hair cursor, from 1 to 15 pixels.
Note: You can toggle a cross-hair cursor on and off, and change the cursor color and thickness on the fly using keystroke combinations. See To customize the Program Painter and To customize the Report Painter for details.
Parent topic: AppMaster Builder Preferences
Related tasks
To customize the Program Painter
To customize the Report Painter


Editors - Program Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Keyword columns
Shows the column numbers for the columns into which you type Program Painter keywords.
Statement columns
Shows the column numbers for the columns into which you type Program Painter.
Remove data in columns 73-80 when loading the program
Removes the data during the program load process.
Tab width
The number of columns that the cursor advances when you press the Tab key.
Force capitals
Automatically converts lower case characters to upper case as you type them into the Program Painter.
Smart edit mode
Turns on smart edit mode, which enables further customization of keywords and carets as you enter code.
Keyword auto completion
Automatically finishes typing a keyword into the keyword area as soon as the keyword is recognized. Available only when Smart edit mode is checked.
Smart caret
Check the box next to the description of each caret behavior that you want to turn on in the Program Painter. Each behavior is associated with one or more a keyboard keys as described.
Parent topic: AppMaster Builder Preferences
Related tasks
To customize the Program Painter


Editors - Program Painter - Colorization

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Enable colorization
When checked, the colorization options set on this page display in the Painter.
Appearance color options
A list of structures to select and then assign to a color using the colored block.
colored block
Shows the color assigned to the structure selected on the Appearance color options list. Click the colored block to invoke the Color dialog box where you can change the color.
Example structure code
Located directly below the colored block, shows an example of the structure selected on the Appearance color options in the color that appears in the colored block.
Preview
Shows example code with each structure in the color assigned to it.
Parent topic: AppMaster Builder Preferences
Related tasks
To set AppMaster Builder preferences
To customize the Program Painter
Related reference
Color dialog box


Editors - Program Painter - Content Assistant

Enable content assistant
When checked, the content assistant invokes a list from which to select an item after you start typing code that is recognized as part of a COBOL verb or statement. For example, typing DB invokes a list of verbs that start with DB, such as DB-OPEN, DB-OBTAIN, etc.
Enable auto activation
When checked, the Content Assistant automatically displays a popup list containing suggested code, such as keywords, as you type characters into the Program Painter. Optionally double-click a list item to replace your typing with the suggested code.
Auto activation delay (ms)
The number of milliseconds AMB waits before automatically activating the Content Assistant. Available only when Enable auto activation is checked.
Parent topic: AppMaster Builder Preferences
Related tasks
To customize the Program Painter


Editors - Report Painter - Colorization

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Enable colorization
When checked, the colorization options set on this page display in the Painter.
Appearance color options
A list of structures to select and then assign to a color using the colored block.
colored block
Shows the color assigned to the structure selected on the Appearance color options list. Click the colored block to invoke the Color dialog box where you can change the color.
Example structure code
Located directly below the colored block, shows an example of the structure selected on the Appearance color options in the color that appears in the colored block.
Preview
Shows example code with each structure in the color assigned to it.
Parent topic: AppMaster Builder Preferences
Related tasks
To customize the Report Painter


Environment

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Database Directory
Type the path of the project and group DDIFILE directory. Do not specify the name DDIFILE. Defaults to the project and group path specified. If your application does not access a database, you can optionally leave this field blank.
User Variable Directory
The path to the directory that stores user variables. By default, this is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\AMBWorkArea\Project\Group\CNTL.
Alternate SQL Copylib directory
Type the path to a directory, other than the COPYLIB project subdirectory, where you want to store the copybooks associated with the tables in your SQL schemas. Do this when you want to use static versions of these copybooks rather than the copybooks generated by AppMaster Builder when you build SQL schema data views. The generated copybooks are overwritten each time you build a SQL schema data view. Optional.
Alternate File Tailoring Directory(s)
Type the paths to locations where AMB should search for File Tailoring members before searching the default path. You can enter up to three fully qualified paths, separated by a semi-colon (;).

For example, C:\TMP;D\MYSLIB;C:\APSUSERS\TESTLIB, tells AMB to first look in C:\TMP, then in D:\MYSLIB, etc., for any file tailoring members. AMB uses the first file tailoring member it encounters. For use with Distributed Generation Server only. Optional.

Important: Ensure that file tailoring files in alternate paths are correct in their syntax structure.
Parent topic: AppMaster Builder Preferences
Related tasks
To set AppMaster Builder preferences


International

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Decimal Point
Select the period or the comma as the symbol for the decimal point in this application. The default is the period.
Currency Sign
Type the symbol this application uses for currency. The default is the dollar sign ($).
Language
Type the language you want to use when you generate the application. The default is English.
DBCS
Check this when your application requires Double-Byte Character Support.
Parent topic: AppMaster Builder Preferences
Related tasks
To set AppMaster Builder preferences


Job Queue

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Job Queue automatic refresh
Check this to automatically refresh each listing in the job queue each time you open the job queue.
Use one Editor per job output
Check this to view output for all jobs in a single instance of the editor. When unchecked, each job output is invoked in its own instance of the editor.
Double click to open job output
Check this to open a job output on a double instead of a single click, which is the default.
Delete jobs older than x days
Select a number that represents the number of days you want to keep job listings before they are automatically deleted. A value of 0 (zero) indicates that jobs are never automatically deleted.
Appearance color options group
drop-down list
A list of Job Queue structures to select and then assign to a color using the colored block.
colored block
Shows the color assigned to the structure selected on the drop-down list. Click the colored block to invoke the Color dialog box where you can change the color.
example structure code
Located to the right of the colored block, shows a code example of the structure selected on the drop-down list in the color showing in the colored block.
Preview
Shows example job queue output with each structure in the color assigned to it.
Parent topic: AppMaster Builder Preferences
Related tasks
To set AppMaster Builder preferences


Logging

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Enable run-time logging
Check this to turn on logging at run time.
Parent topic: AppMaster Builder Preferences


Tooltip - Report

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Report
The name of the report output file. The default is empty.txt.
Background
Shows report background color. Click to change the color.
Text
Shows report text color. Click to change the color.
Field
Shows report text field background color. Click to change the color.
Parent topic: AppMaster Builder Preferences


Tooltip - Screen

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Screen
Select a screen to show the color scheme for tool tips.
Note: The screen is used here for convenience to represent tool tip colors and does not represent the colors used to render screens in AMB.
Background
Shows screen background color. Click to change the color.
Text
Shows text color. Click to change the color.
Field
Shows text field background color. Click to change the color.
Parent topic: AppMaster Builder Preferences


Tooltip - Text

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Foreground
Shows text color. Click to change the color.
Background
Shows text background color. Click to change the color.
sample text
Shows text rendered in the selected foreground and background colors.
Parent topic: AppMaster Builder Preferences
Related tasks
To set AppMaster Builder preferences


Output

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Save COBOL
Check this to save generated COBOL program source. AMB saves the source in the directory appropriate for your User Interface or data communications target.

If you do not check this option, Builder puts the generated COBOL into your TESTLIB area.

Save GENSRC
Check this to save generated source code in the GENSRC directory. Otherwise, AMB saves the generated source in APSEXPS and APSPROG.
Save MFS/BMS
Check this to save the generated MFS or BMS source code in GENPCMFS or GENPCBMS, respectively. Valid for an IMS or CICS program.
Keep temporary files
Check this to retain the temporary files created during program and screen generation. Temporary files are located in the APSFTWRK directory, and contain information you can use to diagnose generation errors. The default is unchecked.
Generate non-OS/VS COBOL
Check this to generate non-OS/VS COBOL source code.
List generated COBOL
Check this to produce a listing of the generated code in a report format.
Generate program manifest
Check this to generate a program manifest for use with the AppMaster Builder Analysis Option.
Generate for S-COBOL debugging
Check this to generate S-COBOL code.
Use default APRPROG if none found
Check this to create a temporary APRPROG file during program generation in the case where no APRPROG file is found.
Show verbose log messages
Check this to see detailed generation messages in the Logger window. When unchecked, the Logger window shows only generation summary messages. The default is unchecked.
Enable Consolidated Tracing Facility
Check this to capture trace information detailing input and output processes and procedural flow. The log file created, ambctf.log, is written to the APSFTWRK folder. Default is unchecked.
Parent topic: AppMaster Builder Preferences
Related concepts
Generating the Analysis
Generating Code
Related tasks
To generate a project analysis
To generate an application analysis
To set AppMaster Builder preferences


Workgroup dialog box

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Workgroup path
Shows the folder that contains workgroup library files.
Workgroup name
Select workgroup library file that contains project folders and workgroup locations to populate the Project folders and Locations lists.
Folders
Lists the default AMB project subdirectories represented in the workgroup library specified in the Workgroup names field.
Locations
Shows all workgroup locations associated with the project subdirectory selected on the Project folders list.
Parent topic: AppMaster Builder Preferences
Related concepts
Workgroups
Managing Workgroups
Related tasks
To create a workgroup
To set AppMaster Builder preferences
To specify a workgroup


AppMaster Builder Perspective

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • AppMaster Builder Perspective
  • Copy + Add Object
  • Generate Multiple-map Mapset
  • Rename Application
  • Rule Directory Selection
Parent topic: User Interface Reference


AppMaster Builder Perspective

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Project Explorer
A hierarchical representation of the current project as objects on a tree view. Click, double-click, or right-click each tree object to perform an action.
Database Explorer
A hierarchical representation of the data views available in the current project.
Stop Batch Server Stop Batch Server
Exit the Batch Server, which starts automatically when you start AppMaster Builder.
Start Batch Server Start Batch Server
Start the Batch Server.
AppMaster Builder Console View AMB Console View
Switch to the AppMaster Builder console.
Job Queue Listings Job Queue
Switch to the Job Queue.
AppMaster Builder Preferences AMB Preferences
Open AppMaster Builder preferences pages.
Parent topic: AppMaster Builder Perspective


Copy + Add Object

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
New Name
Type a name for the new object.
list
Lists the objects available to copy from.
Autoload the list when the filter changes
Check this to automatically load new filter specifications when changed in the Filter field.
Filter
Type filter specifications to filter the list of available objects, or click a filter tile to automatically populate the field.
Load
When Autoload the list when the filter changes is unchecked, click this to apply filter specifications to the list of objects.
filter tiles
Click one of these to apply its contents as the filter.
Parent topic: AppMaster Builder Perspective
Related tasks
To copy an object


Generate Multiple-map Mapset

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Screen location
Shows path to your APSSCRN project subdirectory. If you have assigned a workgroup in your AppMaster Builder preferences, all APSSCRN workgroup locations are available on the drop-down list.
Mapset name
Type the name for the new multiple-map mapset.
Available maps
A list of all maps available in the Screen location.
Selected maps
A list of all maps selected for the multiple-map mapset.
Select available maps Select available maps
Click this to move selected maps from the Available maps column to the Selected maps column.
Remove selected maps Remove selected map(s)
Click this to move selected maps from the Selected mapscolumn back to the Available maps column.
Generate
Click this to generate the multiple-map mapset.
Parent topic: AppMaster Builder Perspective


Rename Application

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Source folder
Shows path to your APSAPPL project subdirectory.
Old name
Shows the current name of the application.
New name
Type a new name for the application.
Rename
Click this to assign the new name to the application.
Parent topic: AppMaster Builder Perspective


Rule Directory Selection

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Default Rule Directories
Lists the default directories that contain AppMaster Builder Rules and Customizer User Rules.
Additional Rule Directories
Lists the directories added in addition to the default rule directories.
Add
Click this to add an additional rule directory using a directory browser.
Delete
Click this to delete directories selected on the Additional Rule Directories list.
Parent topic: AppMaster Builder Perspective


Data View Manager

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Data View Manager
  • Database View / Load/Build Database Views - Properties tab
  • Database View / Load/Build Database Views - Sources tab
Parent topic: User Interface Reference


Data View Manager

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

Data View Manager displays data views in a tree structure. These are the data views that you create for your application from the PSBSRC, DBDSRC, SQLDDL, and DDISRC directories, into which you can import:

  • IMS DBD and PSB statements
  • SQL DDL statements
  • VSAM file definitions
  • SQL Schemas

The field at the top of Data View Manager is automatically populated with the database view you select on the tree structure.

Database View
Click a database view or record you want to build or delete.
Build
Click this to build the database view selected.
Delete
Click this to delete the database view or record selected.
Parent topic: Data View Manager


Database View / Load/Build Database Views - Properties tab

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
SQL Target
Specify the SQL target for the database source you want to load.
Allow Mixed Case
Check this to allow mixed case in your SQL table definitions.
Generate Redefines
Check this to automatically generate a REDEFINES statement for any copybook field whose corresponding SQL field is a DATE, TIME, or TIMESTAMP.
Parent topic: Data View Manager


Database View / Load/Build Database Views - Sources tab

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Source Name
Type the name of a source file you want to create, edit, delete, or load. Optionally, click a source file on the list below to populate this field.
Type
Select the database source type you want to see on the list.
New
Click this to create a new source file.
Edit
Click this to edit the selected source file.
Delete
Click this to delete the selected source file.
Load
Click this to load a selected source file into your data view.
Build List
Click this to build the data views for the sources you have loaded.
Save/Build
Click this to build or update the data view for the source you have loaded.
Source Location
Select a location for your data view source. This drop-down list shows only your project directory unless you have specified a workgroup.
Parent topic: Data View Manager


Distributed Generation Server - Mainframe

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • DGS WebSphere MQ Options
  • DGS Software Locations
  • DGS File Locations
  • DGS Generation Options
  • DGS Save Options
  • DGS Screen Generation
  • DGS Program Generation
  • DGS Application XML
  • DGS Workgroup Options
  • DGS JCL Options
Parent topic: User Interface Reference


DGS WebSphere MQ Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Queue Manager Name
Specify the MQ Manager name for your configuration
Mainframe Queue Name
Specify the mainframe MQ name
Workstation Queue Name
Specify the workstation MQ name
Wait Interval
Specify the timeout period for a MQ message
Code Page
Specify the country code page (Default is 1140, USA code)
Parent topic: Distributed Generation Server - Mainframe


DGS Software Locations

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
APS Project
The current APS project
APS Group
The current APS group
APSMACS
The ddS containing APSMACS members
APSCNTL
The dd's containing APSCNTL members
AMBCOMP LoadLib
Location of uploaded LOADLIB2 modules (see above)
WebSphere MQ loadlib
Location of the WebSphere MQ run-time load modules
COBOL Runtime
COBOL compiler run-time
Parent topic: Distributed Generation Server - Mainframe


DGS File Locations

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Delete temporary files at job completion
YES
Deletes temporary files
No
Retains temporary files
Disk Volume
Disk volume for data sets that are created
Disk Unit
Disk unit for data sets that are created
Program Manifest
Workstation Location for receiving Program Manifests
Parent topic: Distributed Generation Server - Mainframe


DGS Generation Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Decimal
Specify decimal type
Currency
Specify currency sign (e.g. $)
Language
Specify country language (e.g. ENGLISH)
Parent topic: Distributed Generation Server - Mainframe


DGS Save Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Save BMS/MFS
Specify Yes to copy temporary file to the appropriate ddS in the current APS project
Save COBOL
Specify Yes to copy temporary file to the appropriate ddS in the current APS project
Save Object
Specify Yes to copy temporary file to the appropriate ddS in the current APS project
Write AMB logfile to SYSOUT
Specify Yes to have the AMB job listing written to SYSOUT
Max record length of logfile
Valid values are 80 to 132 inclusive. The value specified represents the maximum record length allowed per record in the uploaded AMB generation logfile. DGS splits records exceeding the value specified at the next character encountered after the specified length has been reached.
Parent topic: Distributed Generation Server - Mainframe


DGS Screen Generation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Application
Specify application name containing the screen(s) to generate.
Mapset name
Specify BMS Mapset name. (Required for CICS DC)
DC
Specify DC target from list
Screen
Specify a screen name. If DC is CICS and multiple screens are listed, then a multiple map mapset will be generated.
Parent topic: Distributed Generation Server - Mainframe


DGS Program Generation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Program Type
APSPROG
Generate an Online Express or Program Painter program
APSSRC
Generate a program coded in APSSRC (not implemented)
APSEXPS
Generate an APSPROG file from an Online Express program
APSEXPSF
Creates an APSPROG file from an APSEXPS file and then generates the COBOL program
Application
Specify application name containing the program to generate
Program name
Specify name of program to generate
DC
Specify DC target from list
DB
Specify DB target from list
SQL
Specify YES if your program accesses DB2
Batch
YES
The program is a batch program
NO
The program is not a batch program
Generate non-OS/VS code
YES
Generates non-OS/VS COBOL code
NO
Generates OS/VS COBOL code
Generate Program Manifest
YES
Generates a Program Manifest, saving it to the location specified on the File Locations screen.
NO
Does not generate a Program Manifest
PGMNAME (LONGMIXED)
YES
Generates PROGRAM-ID values inside quotes
NO
Generates PROGRAM-ID values without quotes
Generate for S-COBOL Debugging
YES
Generates S-COBOL debug code
NO
Does not generate S-COBOL debug code
Cadture DGS Statistics
YES
Sets the Performance Monitoring feature to ON
NO
Sets the Performance Monitoring feature to OFF
Note: This setting overrides Performance Monitoring options set from the AppMaster Builder Server Distributed Generations Server options dialog box. See Performance Monitoring.
Online Express Validation
YES
Automatically validates Online Express applications before generation
NO
Does not validate Online Express applications
Parent topic: Distributed Generation Server - Mainframe


DGS Application XML

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Application Name
For the named application, create XML that provides a generation inventory of used sources.
Parent topic: Distributed Generation Server - Mainframe


DGS Workgroup Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
AMB Workgroup Name
Specify an AppMaster Builder Workgroup name. See Specifying Workgroups for more information.
Note: When AppMaster Builder Workgroups are specified, the DD values passed from the mainframe to the Distributed Generation Server are ignored. Workgroup settings take precedence over passed DD values.
AMB Workgroup Location
Specify the workstation location where the Workgroup resides.
Parent topic: Distributed Generation Server - Mainframe


DGS JCL Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Preview JCL
Specify YES to view JCL prior to Job submission
ISPSLIB comments
Specify YES to include comments showing skeletal source members
JCL comments
Specify YES to include comments before each job step
Parent topic: Distributed Generation Server - Mainframe


Distributed Generation Server - PC

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Distributed Generation Options – Diagnostics tab
  • Distributed Generation Options – Logfile/User Exit tab
  • Distributed Generation Options – MQ Options tab
  • Distributed Generation Options – Performance Monitoring tab
  • Start Distributed Generation Server Interface
Parent topic: User Interface Reference


Distributed Generation Options – Diagnostics tab

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Keep Job Submission Files
Check this to ensure that the .sub and .lst files created for each generation submission in the current User Area's JOBQUEUE folder are not deleted.
Keep Project Shadow Group Files
Check this to ensure that the files downloaded from the mainframe into the current User Area are not deleted.
Keep User Area Files
Check this to ensure that the files in the current User Area folder are not deleted.
Keep Registry Work Group Values
Check this to ensure that the WorkGroup values used in the last generation are retained.
Parent topic: Distributed Generation Server - PC
Related tasks
To set DGS PC options


Distributed Generation Options – Logfile/User Exit tab

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Limit Logfile Size
Check this to limit the size of the logfile generated by DGS.
Log size
Type a file size in bytes that represents the maximum number of bytes you want to have written to the logfile.
Backup Logfile
Check this to save full logfiles to another name and location. Type the full path to and filename of the backup file you want to use, or click Browse to navigate to and select an appropriate file. If you do not specify a filename, DGS uses the following default filenaming convention:

DGSLOGnnnnnnnn.txt

Where nnnnnnnn is a DGS-generated number.

Log Full User Exit
Type the full path to and filename of a batch file or executable file that you want to run when the logfile becomes full, or click Browse to navigate to and select an appropriate file.
Show User Exit Window
Check this to call a window to show the execution of your user exit.
User Exit Timeout Interval
Type a number, in seconds, that represents the amount of time you want DGS to wait before executing a user exit.
DGS Start User Exit
Type the full path to and filename of a batch file or executable file that you want to run when you start DGS, or click Browse to navigate to and select an appropriate file.
DGS Stop User Exit
Type the full path to and filename of a batch file or executable file that you want to run when you stop DGS, or click Browse to navigate to and select an appropriate file.
Parent topic: Distributed Generation Server - PC
Related tasks
To set DGS PC options


Distributed Generation Options – MQ Options tab

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Enable MQ Retry option
Check this to enable DGS to attempt to reconnect to WebSphere MQ in the event that it becomes unavailable while DGS is processing a job. The default is unchecked. When checked, the Retry Interval and Number of retry attempts fields are enabled.
Retry Interval
Type the number of seconds you want DGS to wait between reconnection attempts to WebSphere MQ. If blank, the default interval is 30 seconds. To override the wait interval, manually restart DGS.
Number of retry attempts

Type a number that represents the number of times you want DGS to attempt to reconnect to WebSphere MQ before abandoning reconnection attempts.

If the number of retry attempts is achieved without successful reconnection, the Distributed Generation Server changes automatically to an AppMaster Builder Batch Server.

If this field is blank, no reconnection attempts are made.

If you specify 0 (zero), reconnection attempts continue indefinitely at the specified interval until reconnection is accomplished or you manually shut down the DGS.

Parent topic: Distributed Generation Server - PC
Related tasks
To set DGS PC options


Distributed Generation Options – Performance Monitoring tab

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Performance Monitoring
Check this to turn on the performance monitoring feature.
Backup Logs
Check this to create backup logs containing performance monitoring information. Type the full path to the directory where you want to store your backup performance logfiles, or click Browse to navigate to and select an appropriate directory.
Parent topic: Distributed Generation Server - PC
Related tasks
To set DGS PC options


Start Distributed Generation Server Interface

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Queue Manager Name
Type the MQ Manager name for your configuration.
Mainframe Queue Name
Type the mainframe MQ name.
Workstation Queue Name
Type the workstation MQ name.
Mainframe Put Message Expiry
Type a number, in 10ths of a second, that represents how long the MQ message to be sent to the mainframe should sit in the queue before being deleted.
Error Reporting Level
Select a level of error reporting:
Production | Minimal Server Logger output
Normal | Standard Server Logger output
High | Informational Logger output
Debug | Large Volume output for tracing possible errors during processes
WebSphere MQ Middleware Support
Click Server if you have IBM WebSphere MQ installed locally on the Distributed Generation Server machine. Click Client if you have WebSphere MQ Client installed locally on the Distributed Generation Server and the owning Queue Manager installed on a remote system. The default is Server.
Start
Click this to start the Distributed Generation Server Interface.
Parent topic: Distributed Generation Server - PC
Related tasks
To start Distributed Generation Server


Job Queue

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Type
Shows the type of the generated object: Screen, Program, Report, or Database.
Name
Shows the name of the generated object.
RC
Shows the return code from the generator.
Date
Shows the date and time the job ran.
User
The AMB user ID for the user who submitted the job.
Refresh job queue listing Refresh job queue listing
Refresh the list of jobs.
Print selected job(s) Print selected jobs
Refresh the list of jobs.
Delete selected job(s) Delete selected jobs
Refresh the list of jobs.
Delete all jobs Delete all jobs
Refresh the list of jobs.
AppMaster Builder AppMaster Builder perspective
Switch to the AppMaster Builder perspective.
Parent topic: User Interface Reference


Project Object Properties

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Application - Resource
  • Data Structure - General
  • Program - Resource
  • Screen - General
  • User Rule - General
Parent topic: User Interface Reference


Application - Resource

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Author
Type an author identification. This ID is used, for example, in the IDENTIFICATION DIVISION of your program to designate the author of the program.
Description
Type a short description of the application.
User Interface
Select the user interface target.
MOD Size
Select one of the following:
MOD2
24 x 80 lines
MOD3
32 x 80 lines
MOD4
43 x 80 lines
MOD5
27 x 132 lines
Databases
Check one or more databases to use with the application.
Floating point
Check this to link floating point data items with the Micro Focus system object library. For example, COMP-1, COMP-2, or SQL Server floating data type.
Indexed files
Check this to link indexed files with the Micro Focus runtime system. Valid for an application accessing VSAM or IMS database targets only.
Parent topic: Project Object Properties
Related concepts
Object Properties
Related tasks
To set application properties
To create a Program Painter program


Data Structure - General

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Location
Select program location for the data structure: Linkage, Working-Storage (default), or Commarea.
Parent topic: Project Object Properties
Related concepts
Object Properties
Related tasks
To set screen, data structure, and user rule properties


Program - Resource

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Program type
Change the program type. Defaults to the program type set on the Project Explorer, indicated by the program entry icon letter - B for Batch, S for Stub, P for Program Painter, and O for Online Express.
Apos/Quot
Select either the apostrophe (default) or quotation mark character to delimit non-numeric literals in your input source.
Language
Select one of the following:
SCB
Process S-COBOL in columns 8-72. To force a character into column 7, use the symbol &07 in the code. (default)
COBOL
Processs COBOL source in columns 1-72.
JCL
Process JCL in columns 1-72. Useful for text-processing JCL and for controlling columns 1-6 of S-COBOL.
Text
Process source in columns 1-80 and considers all columns to be text. Does not generate sequence numbers.
Translate
Select one of the following:
FMP
Stop after AMB processes Customizer AppMaster Builder and User Rules.
RED
Stop after translating report mock-ups into Report Writer source.
RWT
Stop after translating the Report Section into COBOL Working-Storage and S-COBOL.
SCB
Stop after generating S-COBOL into COBOL.
Columns
Select one of the following:
Sequence
Generates sequence numbers in columns 1-6 for blank, new, or out-of-sequence lines of source code.
Spaces
Generates spaces in columns 1-6; do not select this option when you choose Text as your Language selection.
Cardin
Type the name of the directory for the APSDBDC member. The default is APSDBDC.
Scan Report Writer Mockup
Check this to scan lines in report mock-ups and process the characters % & and + as Micro Focus Generator (MFG) symbols.
Generate Message in Eval Brackets
Check this to generate messages that list evaluation bracket resolutions. When checked, this option usually generates a lengthy list of messages.
User Named Paragraphs
Check this to have AMB generate paragraph names with a prefix that matches the originating S-COBOL paragraph name. One S-COBOL paragraph might expand to several when processed by the Micro Focus Generator. When this option is unchecked, AMB generates paragraph names using the prefix "G--."

Also when checked, this option sets S-COBOL generated data names to use one dash instead of two. When unchecked S-COBOL generated data names have two dashes.

Report Writer
Check this to generate COBOL code from Report Writer statements for non-OS/VS COBOL. When unchecked, AMB passes Report Writer statements directly to the COBOL compiler.
Subroutine
Check this to generate the source code as a subroutine program. When unchecked, AMB generates it as a primary program.
Print Source Program
Check this to print the main input source program after the message report.
Generate Comments
Check this to generate replaced source statements as comments in the COBOL source.
Activate S-COBOL Trace
Check this to activate the SAGE-TRACE-FLAG debugging facility.
Generate nested IF Structures
Check this to generate nested IF statements in the COBOL source.
Parent topic: Project Object Properties
Related concepts
Object Properties
Related tasks
To set program properties
To update a User Rule
To create a Program Painter program


Screen - General

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Screen type
Select the screen type: Input, Output, or InputOutput (default).
Parent topic: Project Object Properties
Related concepts
Object Properties
Related tasks
To set screen, data structure, and user rule properties


User Rule - General

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Location
Select program location in which to insert the user rule. The default is Top of Program.
Parent topic: Project Object Properties
Related concepts
Object Properties
Related tasks
To set screen, data structure, and user rule properties


Online Express

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Action/Event Browser
  • Action/Event Editor
  • Add/Delete Fields for Qualification
  • Attributes
  • Column Information
  • Create Working Storage Field
  • Database Access Summary
  • Database Call Tailoring Browser
  • Database Call Tailoring Editor
  • Explicit Join Specification
  • Express Generation Options
  • Express Savekey Data
  • Field Mapping
  • Field Selection
  • On Clause
  • Qualification
  • Qualification SQL
  • Record Selection
  • Savekey Data
  • Union Reference
Parent topic: User Interface Reference


Action/Event Browser

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Control Type
Click an entry on the list to see control names and completed actions and events for the selected type.
Control Name
Double-click an entry on the list to define actions and events for the selected control.
Control
Lists controls for which actions and events are defined.
Event
Shows the defined event that corresponds to the selected control.
Action
Shows the defined action that corresponds to the selected control.
Argument
Show an argument that corresponds to the selected control, if applicable.
Parent topic: Online Express


Action/Event Editor

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Event
Shows the defined event.
Action
Select a pre-defined action for the event.
Call
Click this to call a subroutine or, for a CICS application, perform a CICS LINK. Then, type the program name into the Argument field.
Global Code
Click this to specify Procedure Division source that you can execute in any program of an application. Global code can consist of any procedural source code and paragraphs that the code performs. Then, type the name of the global code component into the Argument field.
Local Code
Click this to specify Procedure Division and Data Division source that you write and execute specifically in one program. Local code can consist of any procedural source code, paragraphs that the code performs, and Data Division source code for the code.

To write local code, click Edit Code.

User Rule
Click this to specify an existing Customizer user rule. Then, type the name of the rule into the Argument field.
Argument
Select the name of the User Rule, Paragraph, or Global Code to associate with this call.
Perform
Click this to perform a paragraph, which in this case is Procedure Division or Data Division source that you write and execute specifically for one program. Then, the paragraph name into the Argument field.
Reserved
Add
Click this to store records in your database.
Clear
Click this to move low-values to all entry fields; clears all controls.

Exception: For non-CICS applications, Clear moves spaces or low-values, depending on which option you select on the Express Generation Options dialog box - either Clear Screen with Spaces or Clear Screen with Low Values.

Delete
Click this to erase records in your database.
Next
Click this to retrieve the next sequential record and displays its data; does not apply to SQL.
Query
Click this to obtain one or more records and display them on the screen.
Term
Click this to terminate the program.
Update
Click this to modify records in your database.
Forward
Click this to page forward through a repeated record block in an application.
Backward
Click this to page backward through a repeated record block in a screen.
Refresh
Click this to reread the database when the user executes any database write function on one or more repeated record block rows, and redisplays the record block to reflect the database updates.
XCTL
Click this to transfer execution to another program and terminate the current program.
MSG SW
IMS target only. Click this to schedule a new program; optionally you can pass a screen record or other data record to the program. Then, type the trancode|programname|dataname into the Argument field.
SEND
Click this to transmit an input/output screen. Then, type screenname [arg1 arg2 ... argN] into the Argument field.
Apply
Click this to save the current assignments.
Reset
Click this to cancel the assignments just made.
Edit Code
Click this to write customized code for an event. This option is valid when you select the Perform, Global Code, or Local Code actions and enter the name, as required, in the Argument field.
Dup Pfkeys
Click this to duplicate the actions defined for either PF keys 1 throught 12 or PF keys 13 - 24, depending on which you are viewing at the time.
Function Field
Select the type of field, OPTION or MESSAGE.
Parent topic: Online Express


Add/Delete Fields for Qualification

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Select None
Click this to uncheck all check boxes that appear next to the Record Name.
Select All
Click this to check all check boxes that appear next to the Record Name.
Parent topic: Online Express
Related tasks
To define a VSAM call in Online Express
To define an IMS call in Online Express
To define an SQL call in Online Express


Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Database Type
This output-only field reflects your database type.
Program Function
Select database action/control action associations for the call. from one of the following:
Paragraph Name
Shows the default name of the user database call paragraph if you set the Program Function to *User. Type a new name if you want to override the default name. If you override the default paragraph name, you must write a paragraph of that name to replace the default paragraph.
Nesting Level
Specify the nesting level of a loop call.
Scrollable Rec
placeLoop calls only. Check this if you plan to map the records of the outermost loop–a level 0 loop–to a repeated record block. The default is the first loop. Override to specify any loop.
Details On
Click this to see additional attributes.
Query Type
Specify whether the call is a:
Query
Default for all targets. For SQL, select Query to define a call that consists of one Select clause. To define an SQL Join call, select Query and define multiple query calls.
Subselect
For SQL only. Select this to define a Subselect clause. You define a Subselect separately from a Query, placeUnion, or Join call, and then include the Subselect in your call when you qualify it.
placeUnion
For SQL only. Select to define a Union call.
Union All
Check this to include duplicate records in an SQL Union result.
Literal
Type a prefix to identify SQL Union statements.
Parent topic: Online Express
Related tasks
To define a VSAM call in Online Express
To define an IMS call in Online Express
To define an SQL call in Online Express


Column Information

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Previous
Click this to see a synopsis of the previous column.
Next
Click this to see a synopsis of the next column.
Parent topic: Online Express


Create Working Storage Field

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Name
Type the name of a new Working-Storage field you want to map to a screen field.
Of Qualification
Type the name of this permits the end user to specify a qualification for his Working-Storage field to make it unique.
Parent topic: Online Express
Related tasks
To create Working-Storage fields in Online Express


Database Access Summary

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Call No
Shows the call number, which is automatically assigned.
Query Type
Shows the type of call defined, such as a query, subselect, or union.
Actions
Shows the actions assigned to the call as follows:
O | Obtain
L | Loop
M | Modify
E | Erase
S | Store
P | Position
Record Name
Shows the record(s) that the call accesses.
Qualifier
Shows the qualification if the call is qualified as key qualified or boolean. If the call is not qualified, this column is blank.
Program Function
Shows the action/control action associations for the call.
RB
When checked, this column indicates that the call displays data in a repeated record block on the program screen.
Tailor
When checked, this column indicates that the call was customized in the DB Call Tailoring Editor.
Parent topic: Online Express
Related tasks
To customize database calls in Online Express
To qualify VSAM multiple-key fields in Online Express
To define a VSAM call in Online Express
To define an IMS call in Online Express
To define an SQL call in Online Express
To finalize a Union call in Online Express
To specify an isolation level


Database Call Tailoring Browser

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Database Actions
Double-click an action on the list to tailor the call.
Database Action
Lists the names of tailored database calls.
Event
Lists the events that correspond to the tailored database calls.
Action
Lists the action that corresponds to each event.
Argument
Lists any arguments required for specific actions.
Parent topic: Online Express
Related tasks
To customize database calls in Online Express
To qualify VSAM multiple-key fields in Online Express


Database Call Tailoring Editor

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Events
Lists the available events for this database call. Click an event to tailor it in your database call.
Action
Lists actions that correspond to the events listed in the Events column. Select an action for each event you want to tailor.
Argument
Type the name of a User Rule, Paragraph, or Global Code required to complete the corresponding action.
OK
Select CityNormal, Error, or Exception to set the placeStateOK-ON-REC status flag. The default is placeCityNormal.
End
Select placeCityNormal, Error, or Exception to set the END-ON-REC status flag. The default is placeCityNormal.
Not Found
Select placeCityNormal, Error, or Exception to set the NTF-ON-REC status flag. The default is Error.
Duplicate
Select placeCityNormal, Error, or Exception to set the DUP-ON-REC status flag. The default is Error.
VIO
Select placeCityNormal, Error, or Exception to set the VIO-ON-REC status flag. The default is Error. VIO stands for violate.
Error Message
Type a new message to override the default messages using text or specifying a user rule that contains a text message. Be sure to set the Error Message Type to match the type of message you specify here.
Error Message Type
Select Text if you entered text in the Error Message field; select Macro if you entered a user rule.
Abort on Error
Check this to specify that when the program encounters an error flag, it aborts. Uncheck this option to prevent the Error flag from aborting the program.
Apply
Click this to save the current assignments.
Reset
Click this to cancel the assignments made.
Edit Code
Click this to write customized code for an event. This is valid when you select the Perform, Global Code, or Local Code actions and type the name, as required, in the Argument field.
Parent topic: Online Express
Related tasks
To customize database calls in Online Express
To qualify VSAM multiple-key fields in Online Express


Explicit Join Specification

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Join Table
Select a table to serve as the first table in the Join.
Join Type
Select the type of join you want to create, as follows:
Inner
Combines each row of the 1st Join Table with every row of the 2nd Join Table keeping only the rows where the join condition is true.
Left Outer
Includes the rows from the 1st Join Table that were missing from the inner join.
Right Outer
Includes the rows from the 2nd Join Table that were missing from the inner join.
Full Outer
Includes rows from both tables that were missing from the inner join.
2nd Join Table
Select a table to serve as the second table in the Join.
Undo Explicit Join
Click this to undo the join specified on this dialog box.
On Clause
Click this to define an ON clause for the Join.
Parent topic: Online Express
Related tasks
To define an explicit Join specification


Express Generation Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Generate Control Point Comments
Check this to generate comments in programs identifying control events.
Generate Database calls
Check this to generate your database access specifications into database calls. When testing the program teleprocessing functions without accessing a database, uncheck this option to suppress the generation of database calls.
Error-Send-and-Quit Para defined by user
Check this to prevent Online Express from generating the Error-Send-and-Quit paragraph in a stub, copybook, or in miscellaneous code. When checked, you must code this paragraph yourself. The default is unchecked.
Generate InterScreen Moves
Check this to move all fields on the primary screen to like-named fields on the screen specified by a user-coded SEND macro. The default is unchecked.
Redisplay Record
Check this to display the last record of a repeated record block when scrolling.
Improve Sql Looping
Click this to generate two DB-PROCESS calls instead of one to improve runtime performance. Otherwise, only one DB-PROCESS executes both the initial retrieval and the paging forward function.
Clear Screen with Spaces
Click this to clear all I/O screen fields with spaces. This is the default for non-CICS applications.
Clear Screen with LowValues
Click this to clear all I/O screen fields with low values. This is the default for CICS applications.
System Message Field
Select a message field name.
Cursor on Field
Select the screen field on which you want the cursor to initially appear.
Extra Commarea Bytes
Type the size of the largest record that the program can send or receive.
Parent topic: Online Express


Express Savekey Data

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Use Commarea to Store Savekey
Check this to store savekey data in the program Commarea instead of storing it in a screen field.
Non-Repeated Savekey
Select a field from this list when your screen has a single occurrence of data only, with the Update, Delete, or Next action. The field to the right contains the size that the savekey screen field must be to store the database key.
Repeated Row Savekey
Select a field from this list when your screen has a repeated record block only, with the Update, Delete, Forward, or Backward action. The field to the right contains the size that the savekey screen field must be to store the database key.
For All Savekeys
Select a field from this list when your screen has both:
  • A single occurrence of data, with the Update, Delete, or Next action
  • A repeated record block, with the Update, Delete, Forward, or Backward action
The field to the right contains the size that the savekey screen field must be to store the database key.
Note: Each savekey field on your screen should have the Type attribute set to Protected and the Length attribute set to the sum of the bytes allocated for non-repeated and repeated row savekeys.
Parent topic: Online Express


Field Mapping

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Control Selection
Click a control category on the list to view the applicable controls on the Control list
Record
Click a record on the list to view its associated fields on the Field list.
Type
Shows the database type for the associated record.
Control
Click a control on the list and drag the mouse to a field on the Field list to create a mapping. Double-click a control to view the mapping direction for the control.
Mappings
Shows an arrow for each mapping to indicate what fields and controls are mapped, and whether the mapping is one-way or two-way. An arrow with one head indicates a one-way mapping. A two-headed arrow indicates a two-way mapping.
Field
Click a field on the list and drag the mouse to a field on the Control list to create a mapping. Double-click a field to qualify it
Field Mapping Order
Shows the mapping direction (one-way or two-way) from the database field through the control to the database record.
Parent topic: Online Express
Related tasks
To create Working-Storage fields in Online Express
To map screen fields in Online Express


Field Selection

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Function
Lists the functions associated with the columns you selected for the call. Click a function to change its assignment to another column function or, if the call is a Loop call, an SQL scalar function.
Column
Lists all the columns you selected for the call.
Host Variable
Lists COBOL host variable field names. If another host variable is available for a specified column, you can select it from the drop-down list.
Index
Check this to indicate that the field is an index field.
Distinct
Check this to indicate that the field is distinct.
Add/Del Fields
Click this to exclude any columns from or add columns to the call.
Parent topic: Online Express
Related tasks
To finalize a Union call in Online Express


On Clause

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
(
Select one left paren or a set or parentheses to group your call qualification components. Be sure to select the appropriate right parentheses in the ) column to complete your group.
Fn()
Select a function on which to qualify the call.
Column
Shows the relevant column for the call.
Operator
Select an arithmetic operator to create an equation between the column in the Column field and the value in the Value/Subselect field.
Value/Subselect
Select a field from the list, type a literal value, or select SUBSELECT to set the value for the qualification.
Boolean
Select AND, OR, or nothing as your boolean operator.
Apply
Click this to save the current assignments.
Reset
Click this to cancel the assignments made.
Add/Del Fields
Click this to add or delete fields from your database call.
)
Select one right paren or a set of parentheses to group your call qualification components with the appropriate left parentheses selected.
Parent topic: Online Express
Related tasks
To define an explicit Join specification


Qualification

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Record
Shows the record name.
Field
Shows the field name.
Operator
Select an arithmetic operator to create an equation between the field in the Field field and the value in the Value field.
Value
Type a value for the field in the Field field.
Type
Shows the field type.
Length
Type the length of the record.
Boolean
Select AND, OR, or nothing as your boolean operator.
Add/Del Fields
Click this to add or delete fields from your database call.
Parent topic: Online Express
Related tasks
To define a VSAM call in Online Express
To define an IMS call in Online Express
To define an SQL call in Online Express


Qualification SQL

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
(
Select one left paren or a set or parentheses to group your call qualification components. Be sure to select the appropriate right parentheses in the ) column to complete your group.
Function
Select a function on which to qualify the call.
Column
Shows the relevant column for the call.
Operator
Select an arithmetic operator to create an equation between the column in the Column field and the value in the Value/Subselect field.
Value/Subselect
Select a field from the list, type a literal value, or select SUBSELECT to set the value for the qualification.
Boolean
Select AND, OR, or nothing as your boolean operator.
Apply
Click this to save the current assignments.
Reset
Click this to cancel the assignments made.
Add/Del Fields
Click this to add or delete fields from your database call.
)
Select one right paren or a set of parentheses to group your call qualification components with the appropriate left parentheses selected.
Parent topic: Online Express


Record Selection

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Important: The Record Selection dialog box is dynamic. The fields and controls that appear on it depend on the database call you are defining. The following list represents all possible fields or controls you might encounter:
Database Type
This dialog box shows the attributes for all of the screen fields.
Query Type
Specify whether the call is a:
Query
Default for all targets. For SQL, select Query to define a call that consists of one Select clause. To define an SQL Join call, select Query and define multiple query calls.
Subselect
For SQL only. Select this to define a Subselect clause. You define a Subselect separately from a Query, Union, or Join call, and then include the Subselect in your call when you qualify it.
Union
For SQL only. Select to define a Union call.
Record
Lists the records available in the program for which you can define database calls. Click a record to define a database call for it.
Obtain
Check this to Obtain information for the corresponding record.
Loop
Check this to Loop on information for the corresponding record.
Modify
Check this to Modify information in the corresponding record.
Erase
Check this to Erase information in the corresponding record.
Store
Check this to Store information in the corresponding record.
Alias
Type a short-hand name (alias) for the table.
Position
Check this to ???
Self-Join
Check this to create a self join for the database call.
Isolation Level
Select an isolation level, which determines how data is locked and isolated from other processes while the data is being accessed, from the following:
CS | with cursor stability
RS | with read stability
RR | with repeatable read capability
UR | with an uncommitted read capability

This field is optional.

Parent topic: Online Express
Related tasks
To define a VSAM call in Online Express
To define an IMS call in Online Express
To define an SQL call in Online Express
To finalize a Union call in Online Express
To specify an isolation level


Savekey Data

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
User Commarea to Store Savekey
Check this to store savekey data in the program Commarea instead of storing it in a screen field.
Non-Repeated Savekey
Select a field from this list when your screen has a single occurrence of data only, with the Update, Delete, or Next action. The field to the right contains the size that the savekey screen field must be to store the database key.
Repeated Row Savekey
Select a field from this list when your screen has a repeated record block only, with the Update, Delete, Forward, or Backward action. The field to the right contains the size that the savekey screen field must be to store the database key.
For All Savekeys
Select a field from this list when your screen has both:
  • A single occurrence of data, with the Update, Delete, or Next action
  • A repeated record block, with the Update, Delete, Forward, or Backward action

The field to the right contains the size that the savekey screen field must be to store the database key.

Note: Each savekey field on your screen should have the Type attribute set to Protected and the Length attribute set to the sum of the bytes allocated for non-repeated and repeated row savekeys.
Parent topic: Online Express
Related tasks
To define a Savekey
To define Savekey storage
To paint a Savekey field


Union Reference

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Field Name
The first occurrence shows the first field in each listed placeUnion. The second occurrence shows the second field in each listed placeUnion.
Field type
The first occurrence shows the field type of the first field in each listed placeUnion. The second occurrence shows the field type of the second field in each listed placeUnion.
Len / Leng
The first occurrence (Len) shows the length of the first field in each listed placeUnion. The second occurrence (Leng) shows the length of the second field in each listed placeUnion.
Validate
Click this to validate the Union calls listed.
New Value
Type a new value for the user variable.
Union Validation Messages
Shows the messages produced by the validation process.
Parent topic: Online Express
Related tasks
To finalize a Union call in Online Express


Screen Painter

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
  • Alignment
  • Assembler Generation Parameters
  • CICS Generation Parameters
  • DLG Generation Options
  • Field and Text Attributes
  • Field Edit Bypass Criteria
  • Field Edit Data Type
  • Field Edit Messages and Attributes
  • Field Edits
  • IMS Generation Parameters
  • IMS Trancode Construction
  • Input Messages and Attributes
  • Input Representation
  • Internal Representation
  • MFS Function Keys
  • Output Representation
  • Repeat Block Attributes
  • Screen Parameters
  • SYSMSG Parameters
  • Values and Conversions
Parent topic: User Interface Reference


Alignment

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Top
Click this to align all selected fields with the selected field closest to the top of the screen.
Center
Click this to align all selected fields vertically on the center of the screen.
Bottom
Click this to align all selected fields with the selected field closest to the bottom of the screen.
None
Click this to specify no vertical alignment.
Left
Click this to align all selected fields with the selected field closest to the left side of the screen.
Center
Click this to align all selected fields horizontally on the center of the screen.
Right
Click this to align all selected fields with the selected field closest to the right side of the screen.
None
Click this to specify no horizontal alignment.
Parent topic: Screen Painter
Related tasks
To align screen fields


Assembler Generation Parameters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
No Assembler END
Check this to prevent AMB from generating an assembler END statement.
Print Expanded Assembler Rules
Check this to print expanded assembler rules.
Retain Datanames
Check this to retain painted field names as assembler labels. Under BMS or MFS, duplicate or invalid names can occur due to the maximum number of characters that BMS and MFS allow.
Parent topic: Screen Painter
Related tasks
To define screen attributes


CICS Generation Parameters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Assembler
Click this to set Assembler generation options.
Transaction ID
Type an associated transaction ID; default is the first four characters of the screen name. If more than one screen begins with the same four characters, you need to define a unique transaction ID.
Mapset Name
Type a mapset name if you want to override the AMB-generated mapset name; maximum seven characters. To generate a multiple-map mapset that includes some or all screens, assign the same mapset name to the applicable screens in the application. The default mapset name reflects the number of characters in the screen name, as follows:

4-char name - screennameSET

5-, 6-char name - screenname$

7-char name - screenname$, where $ replaces the seventh character

Starting Line
Type the line of the map on the physical screen where you want generation to start; default is 001; value cannot exceed the screen depth.
Parent topic: Screen Painter


DLG Generation Options

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Help Panel Name
Type the name of the panel to display, if the user requests help. This option generates the .HELP = panelname statement.
Program Controlled
Click this if you want the program to control PF key processing. AMB saves the user's original PF key values and replaces them with literals not recognized by Dialog so that you can control the PF key usage. When the program terminates, the original PF key values are restored.
ISPF Command Table
Click this to control PF key processing using the ISPF Command Table. This is the default.
Command Field
Select the screen field to be the panel command field that allows users to enter DLG commands and prevent truncation errors when they use PF keys. The default field is the first unprotected I/O field on the screen.

This option generates the native )BODY CMD(variable) statement.

Short Message
Select a screen field name for the panel short message field. The program moves the literal message to the screen via this field.

This option generates the native )BODY SMSG(variable) statement.

Long Message
Select a screen field name for the panel long message field. The program moves the literal message to the screen via this field.

This option generates the native )BODY LMSG(variable) statement.

Parent topic: Screen Painter


Field and Text Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Name
Type the I/O field name; maximum 16 characters. Text fields do not have names because programs do not reference them. If you give a screen field the same name as its corresponding database field, Online Express automatically maps the relationship for you, prefixing the field name with the screen name; otherwise you must type the database field names into your program.
Text
Type the text you want to appear in the field.
Initial Value
Type a value to display in the field when the field first appears; the maximum is the length of the field 27 characters, whichever is less.
Row and Column
Shows the row and column where the field is located on the screen.
Length
Shows the length of the field.
Protected
Check this to prevent users from entering information into an output only field.
Intensity
Select an intensity level. placeCityNormal is the default.
MDT on
Check this to set the Modified Data Tag. The default is to always send the screen field data to the program when the user presses Enter.

Uncheck this to send the screen field data only when the end user modifies the data. In this case, the unmodified data is lost because the MDT value changes to ON when the user modifies a field.

Numeric
Check this to activate the numeric keyboard shift lock function when the cursor moves into the field. This restricts the user from entering non-numeric data into the field.
Detectable
Check this if the field is light pen detectable.
Cursor
Check this to indicate that the cursor should be positioned on the field when the screen is sent. Not supported in IMS.
Mod
Check this to enable the end user to modify the field.
Color
Select the initial color of a field on a full color terminal.
Highlight
Select Blink to create a flashing field.

Select Underline to create an underlined field.

Select Rvideo to create a dark field with light letters.

Format
Select the character format for a field on DBCS terminals. Selecting None (default) implies the field is EBCDIC only.
Ruled Line
Select the line placement around a field on DBCS terminals.

None - do not place any lines around the field.

L - place a line to the left side of the field.

R - place a line to the right side of the field.

O - place a line over the field.

U - place a line under the field.

B - place a line surrounding the field.

00-0F - place a combination of lines around the field.

Parent topic: Screen Painter
Related tasks
To define field attributes
To modify attributes for a field in a record block
To paint a screen
To turn off the MDT tag


Field Edit Bypass Criteria

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Name
Select screen field to bypass. Fields in a repeated block are valid.
Bypass Values
Type the value(s) that let end users bypass input edits in the Override 1 and Override 2 fields. Valid COBOL reserved words are SPACES, LOW-VALUES, and HIGH-VALUES.
Comma Separated Values
Type additional value(s) that enable users to bypass input edits. Separate each value with a comma. Valid COBOL reserved words are SPACES, LOW-VALUES, and HIGH-VALUES.
Bypass Keys
Check the PF keys the user can press to bypass the input edits.
Parent topic: Screen Painter
Related tasks
To define screen attributes
To bypass field edits


Field Edit Data Type

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Local Data Class
Select the appropriate data class as follows:
Character
Alphanumeric format.
Numeric
Numeric format.
Date - Predefined Edits
Gregorian, Julian, or system date storage format and a predefined list of input/output formats.
Data User-Defined Edits
Storage, input, and output date formats that you define.
Time - User-Defined Edits
Storage, input, and output time formats that you define.
Local Data Type
Select the appropriate data type format.
Parent topic: Screen Painter
Related tasks
To define a field-specific error message


Field Edit Messages and Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Error
Type the text that you want to appear when data entered by the user on the screen does not pass field edit requirements.
Required
Type the text that you want to appear when the user neglects to enter data for any field where data is required.
Attributes
Type the field attributes for fields that fail input edits, using the syntax attribute+attribute+... . Default attributes are POS+BRT, meaning bright intensity with the cursor positioned on the field in error.
Message Display Field
Select the field you want to display the global message.
Parent topic: Screen Painter
Related tasks
To define screen attributes
To bypass field edits
To define a global error message
To define field edits


Field Edits

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Internal
Click this to define storage requirements for the field.
Input
Click this to define a format the user must adhere to when entering data into the field, or specify an error message, or code your own application edit routine.
Output
Click this to define the format for displaying the data in the field or code your own application edit routine.
Values
Click this to specify valid values, ranges of values, or conversion values.
Delete
Click this to delete the field edit.
Parent topic: Screen Painter
Related tasks
To define a field-specific error message
To delete field edits
To paint a screen


IMS Generation Parameters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
PFkeys
Click this to set parameters for MFS function keys.
Trancode
Click this to specify IMS trancode construction.
Reorder
Click this to reorder MFS MIDs and MODs.
Assembler
Click this to set Assembler generation options.
MID Name
Type a new MID name if you want to override the AMB-generated name. The default MID name reflects the number of characters in the screen name, as follows:

4-char name - screennameMI

5-, 6-, 7-char name - screennameI

8-char name - screennameI, where I replaces the 8th character

MID Number
Type a number to generate the EXIT parameter on the MID segment statement using your number as the exit routine number. Valid values are 0 through 127.
MID Vector
Type a number to generate the EXIT parameter on the MID segment statement using your number as the exit vector number. Valid values are 0 through 255.
MID Default Values
Check this to treat initial values as the default values for fields in the MFS-generated MID.
MOD Name
Type a new MOD name if you want to override the AMB-generated name. The default MOD name reflects the number of characters in the screen name, as follows:

4-char name - screennameMO

5-, 6-, 7-char name - screennameO

8-char name - screennameO, where O replaces the 8th character

MOD Fill Char
Click one of the following options to generate fill characters in the MOD segment statement:

None - Use spaces for the fill character (default).

Null - Do not use fill characters. This causes the field to be truncated. Programs that specify a Null fill character must handle variable-length fields.

PT - Use the program tab character for the fill character.

Character - Specify the use of a specific character as the fill character. Also type the character value in the field to its right.

Trancode Field Name
Select the field name to hold the transaction code or operator logical paging command. Alternatively, select *PF and assign the PF key value on the MFS Function Keys dialog box, or *TC and construct a transaction code on the Trancode Construction dialog box.
Trancode Literal
Type a literal value as the transaction code. The default is the screen name.
Lines per Page
Type the number of lines to print on a page if the Device Type is a printer.
Device Type
Type the standard device characters for different model terminals and printers. Defaults are IBM-recommended device characters. See your IBM MFS or IMS installation manual for further details.
DSCA
Type a new value for the Default System Control Area if you want to override it. The default value is X'00A0'.
DIF-DOF Name
Type a new value if you want to override the AMB-generated name. The default DIF-DOF name reflects the number of characters in the screen name, as follows:

4-char name - screennameDF

5-, 6- char name - screenname$

7-, 8-char name - screenname, truncated to six characters

Operator Logical Paging
Check this to request operator logical paging.
Cursor Feedback
Check this to define a field in the MID as the cursor feedback field. This field provides cursor information for input processing. To hold the information, Builder appends two half-word binary fields to the screen records screen-CURSOR-ROW and screen-CURSOR-COL. Cursor feedback fields do not affect output cursor positioning.
LABELED Screen
Check this to append the screen name to the input message.
Parent topic: Screen Painter
Related tasks
To define screen attributes


IMS Trancode Construction

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Field Name
Default Literal
Null Filler
Field Name
Select the field name, or select *PF if you specify PF key values on the MFS Function Keys dialog box. If you select a field, AMB ignores all field attributes, including an initial value. Enter the initial value in the Default Literal field.
Default Literal
Type the initial literal value for corresponding the field. If you supply a literal on the same line as a field name or *PFKEY, AMB transmits the literal in the MID when no value is entered for the field or when the PF key is not invoked.
Null Filler
Check this if the MID fill character for the associated field name or *PFKEY is null. The default is space.
Parent topic: Screen Painter
Related tasks
To define screen attributes


Input Messages and Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Error
Type the text that you want to appear when data entered by the user on the screen does not pass field edit requirements.
Required
Type the text that you want to appear when the user neglects to enter data for any field where data is required.
Attributes
Type the field attributes for fields that fail input edits, using the syntax attribute+attribute+... . Default attributes are POS+BRT, meaning bright intensity with the cursor positioned on the field in error.
Parent topic: Screen Painter


Input Representation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Input Representation dialog box is dynamic. The fields and controls that appear on it depend on the data type you select for the field you are defining. The following list represents all possible fields or controls you might encounter:

AM Indicator
Type the AM time indicator, such as a.m. or am.
Application Edits
Click this to create your own edit routine to process data.
Decimal
Select a character to represent a decimal, such as a period (.).
Decimal Digits
Type the smallest number of digits required to follow the decimal point into the Min field and the largest number allowed into the Max field; the Max field defaults to largest number that fits. This option does not imply that data is required.
Embedded Spaces
Check this to accept characters separated by spaces. Leading and trailing blank spaces are unaffected by this option.
Ensure Computational
Check this to enable users to enter numeric data only.
Input Format
Type a format for a date or a time, depending on what type of field you are defining.
Input Length
Type the length of shortest valid entry into the Min field; default is zero. Type length of longest valid entry in the Max field; default is zero. These specifications do not imply that data is required.
Input Required
Check this to indicate that input is required for the field.
Input Mask
Double-click each input specification on the list to add its corresponding code to the Input Mask field. The Input Mask field can contain multiple codes. Required mask characters do not require data entry; they require that data entered be of that specific type. For example, the A mask character requires an alphabetic character in that position if any data is entered.
Justification
Select the alignment of the data in the field. The default is Left justification.
Left Input Digits
Type the smallest number of digits required before the decimal point into the Min field and the largest number allowed into the Max field; the Max field defaults to the largest number that fits. This option does not imply that data is required.
Message
Click this to display specify error messages and attributes that display if the field or control fails input edits.
PM Indicator
Type the PM time indicator, such as p.m. or pm.
Punctuation
Specify whether field requires, allows, or disallows the end user to enter punctuation characters such as commas, colons, and dashes. Default is Allowed. The generated code does not use punctuation.
Refresh System Date on Input
Click this to always insert the system date during input editing, regardless of the field contents.
Refresh System Time on Input
Select to always insert the system time during input editing, regardless of the field contents.
Strip Characters
Check this to remove special characters when converting the data to the storage format. A special character is any character other than input mask characters.
Use Characteristics
Click this to specify one or more of the format specifications that follow.
Use input mask
Click this to create an input mask.
Use System Date on Input
Check this to insert the system date during input editing only if the field is blank.
Use System Time on Input
Check this to insert the system time during input editing only if the field is blank.
Zero When Blank
Check this to move zero to the internal picture if no data is entered.
Parent topic: Screen Painter
Related tasks
To define a field-specific error message
Related reference
Date Field Formats
Time Field Formats


Internal Representation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Internal Representation dialog box is dynamic. The fields and controls that appear on it depend on the data type you select for the field you are defining. The following list represents all possible fields or controls you might encounter:

AM Indicator
Type the AM time indicator, such as a.m. or am.
Character Mode
Select single-byte, double-byte, or mixed.
Character Set
Choose ASCII or EBCDIC.
Data Subtype
Select the type of storage format:
JULIAN | Store data as YYDDD and generate PIC X(5) or PIC 9(5) COMP 3, depending on the Physical Data Type selected above.
GREGOR | Store data as YYMMDD and generate PIC X(6) or PIC 9(6) COMP 3, depending on the physical data type specified for the field.
Data Use
Select Packed Decimal, Binary, or ZONDEC Display.
Initialize with System Date
Check this to initialize the field with the current system date.
Justification
Select the alignment of the data in the field. The default is Left justification.
Number of Digits
Total | Type the sum of digits stored before and after the decimal point.
Right of Decimal | Type the number of digits that follow the decimal point.
PM Indicator
Type the PM time indicator, such as p.m. or pm.
Separate Sign
Check this to count the letter "S" in the COBOL Picture clause when determining the actual size of the item. When unchecked the letter "S" in the COBOL Picture clause is NOT counted when determining the size of the item.

This option is only valid for Numeric data items that have an Internal Data Use of "ZONEDEC Display" and have Trailing or Leading as the Sign field value.

Sign
Select a sign symbol.
Storage Format
Type the internal storage format mask. Special characters are allowed only if the field is not numeric. This format length must equal the internal picture length.

If the field is a Time field, valid characters are HH (hour), MM (minute), SS (second), *s, and special characters. Seconds are optional. For example: HH:MM**

Storage Length
Character fields | Type the physical space required to store the data; maximum 16777216 bytes. Default is the length specified for the control item.
Numerical fields | Shows the physical space required to store the data; AMB calculates this value for you.
Parent topic: Screen Painter


MFS Function Keys

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Pfkey Global Default
Click Null or Space to set the global PF key default.
Associated Data
Assign trancodes, operator logical paging, other IMS commands, and nulls or spaces to the MFS PF key fields in the Associated Data field. For example:
PFkey 1  =+1
PFkey 2  =-1
PFkey 3  /for frmt1mo
PFkey 4  /for frmt2mo
PFkey 5  /for frmt3mo
PFkey 6  tran1
PFkey 7  tran2
PFkey 8  tran3
PFkey 9  /exit
PFkey 10 /end
Parent topic: Screen Painter
Related tasks
To define screen attributes


Output Representation

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.

The Output Representation dialog box is dynamic. The fields and controls that appear on it depend on the data type you select for the field you are defining. The following list represents all possible fields or controls you might encounter:

AM Indicator
Type the AM time indicator, such as a.m. or am.
Application Edits
Click this to create your own edit routine to process data.
Decimal
Select a character to represent a decimal, such as a period (.).
Justification
Select the alignment of the data in the field. The default is Left justification.
Max Length
Type the maximum length for a character field.
Output Format
Type a format for a date or a time, depending on what type of field you are defining.
Output Mask
Double-click each input specification on the list to add its corresponding code to the Input Mask field. The Input Mask field can contain multiple codes. Required mask characters do not require data entry; they require that data entered be of that specific type. For example, the A mask character requires an alphabetic character in that position if any data is entered.
Refresh System Date on Output
Click this to always insert the system date during output editing, regardless of the field contents.
Refresh System Time on Output
Select to always insert the system time during output editing, regardless of the field contents.
Thousand
Specify a comma, period, or no character to separate millions, thousands, and hundreds. The default is Comma.
PM Indicator
Type the PM time indicator, such as p.m. or pm.
Punctuation
Specify whether field requires, allows, or disallows the end user to enter punctuation characters such as commas, colons, and dashes. Default is Allowed. The generated code does not use punctuation.
Sign
Select a sign symbol.
Use Characteristics
Click this to specify one or more of the format specifications that follow.
Use Output Mask
Click this to create an input mask.
Use System Date on Output
Check this to insert the system date during output editing only if the field is blank.
Use System Time on Output
Check this to insert the system time during output editing only if the field is blank.
Parent topic: Screen Painter


Repeat Block Attributes

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Starting Row
Shows the row number that the block starts on. AMB automatically displays the lowest row number of the fields you selected.
Number of Rows
Type the number of source rows you want in the repeated block. Each row in a repeated record block encompasses the entire width of the screen.
Number of Occurrences
Type the total number of times the block of source rows should occur. For example, a record block that contains two source rows and has five occurrences produces ten lines on the screen. You can create a record block covering as many consecutive blank lines as are available on the screen.
Parent topic: Screen Painter
Related tasks
To change repeated record blocks
To create repeated record blocks
To delete repeated record blocks


Screen Parameters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
CICS
Click this to set CICS generation parameters.
IMS
Click this to set IMS generation parameters.
DLG
Click this to set DLG generation parameters.
EDITS
Click this to set field edit messages and attributes.
SYSMSG
Click this to set SYSMSG parameters.
Title
Type a descriptive screen title. The default is the screen name.
Intensity
Select an intensity for all static text fields. Normal (default) maintains the painted intensity attribute of each field.
Color
Select a color for all static text fields. None (default) maintains the painted color attribute of each field.
Highlite
Select the type of highlighting for static text fields. None (default) maintains the painted highlight attribute of each field.
Allow Dynamic Extended Attribute Changes
Check this to allow modification of extended attributes at run time. AMB generates EXTATTR=YES and extra attribute bytes in DSECT.
Allow Dynamic Extended Attribute Changes
KANJI only. Check this to modify Format and Ruled Line attributes for static text fields at run time.
Gen Panel KANA
KANJI only. Check this to generate the KANA keyword in the ISPF panel body header statement to display Japanese Katakana.
Box Unprotected Fields
KANJI only. Check this to enclose unprotected I/O fields in lines.
Parent topic: Screen Painter
Related tasks
To define screen attributes
To bypass field edits
To create system message fields
To define a global error message
To define field edits


SYSMSG Parameters

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Name
Select an existing field to be the system message field, or select:

*No - Do not display system messages.

*Yes or *SYSMSG - Display messages on last line of the screen if space is available. If the last line is not available, AMB paints a default field in which message appears in the generated screen; this field does not appear on the painted screen.

Row
Type the row number of the system message field. This option is valid only when you set Name to *Yes.
Column
Type the starting column number of the system message field. This option is valid only when you set Name to *Yes. The field length of the system message field can be from 40 to 70 characters, or up to 131 characters for MOD5 screens.
Parent topic: Screen Painter
Related tasks
To define screen attributes
To create system message fields


Values and Conversions

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
Enter Values or Conversions
Assign values as follows:
  • value
  • lowvalue TO|THRU highvalue
  • lowvalue UP
  • highvalue DOWN

Assign conversion values as follows:

(input1, input2, ..., inputN,I=internalvalue,O=outputvalue)

You can assign values or conversions, but not both.

Verify Conversion Values
Check this to specify that the listed conversions are the only valid input values.
Parent topic: Screen Painter


User Areas

  • Create User Area
  • Delete User Area
Parent topic: User Interface Reference


Create User Area

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
User area directory
The parent user area directory. AMB stores your generated code in a series of subdirectories. The default is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\AMBWorkArea.
User name field
Your AMB user ID. AMB uses this user ID:
  • As the name of a subdirectory to the User area directory, where it stores your generated code in a series of subdirectories to this user ID subdirectory.
  • To identify your jobs in the Job Queue.
User name list
Lists existing user names.
Parent topic: User Areas
Related tasks
To create a user area


Delete User Area

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
User ID
The user ID that corresponds to the user area to be deleted.
Existing user IDs
Lists all existing AMB user IDs.
Parent topic: User Areas
Related tasks
To delete a user area


Assembler Support

Enterprise Developer Assembler support allows you to import assembler programs into your project, and to use the trace and debug functionality to debug these programs.

Note: The current version of the product is aimed at the early adopter. Our Assembler support does not allow you to include assembler program components in your run-time applications. Once you have an assembler component working, you need to re-write it in COBOL in order to include it in a deployed application.
  • Assembler Support Overview
  • Configuring Assembler Project File Locations
  • Compiling and Linking Assembler Modules
  • Debugging Assembler Applications
    Describes the debugging functionality available for Assembler and Assembler/COBOL applications.
  • Configuring Runtime Memory Requirements
  • Configuring a Program's Memory Requirements
  • File Handling
  • Using the Generalized Trace Facility
Parent topic: Mainframe Programming


Assembler Support Overview

Assembler support enables you to include Assembler modules in your projects. As with COBOL programs, you can:
  • Edit Assembler source code
  • Compile and link your Assembler source code including copybooks and macros provided with Enterprise Developer, or ones you have written yourself.
  • Create new Assembler modules
  • Trace and debug your Assembler modules.
Note:
  • Assembler support does not allow you to include Assembler program components in your run-time applications. Once you have an assembler component working, you need to rewrite it in COBOL to include it in a deployed application.
  • The Assembler Compiler and Linker are not supported on UNIX and Linux platforms.
  • Enterprise Developer supports remote projects that include Assembler code (for example, you can convert local projects to remote ones). You can add files to such projects and edit them and project settings, but compiling, linking and debugging are not supported.
  • About Developing Assembler Applications
  • About Creating, Editing and Navigating Source Code
  • Configuring the Environment
Parent topic: Assembler Support


About Developing Assembler Applications

Assembler programs usually have file extensions of .MLC or .ASM and can be included into any Enterprise Developer project.

Assembler modules with EXEC CICS statements in them are usually identified with the file extension .CAP. When these modules are added to your project you can assemble and link them into either data tables with the extension .MOD, or as executable modules with the extension .390.

Note:
  • Only assembler modules are linked to form executable modules.
  • Cobol modules cannot be linked with 390 assembler modules. Even though assembler modules have the .OBJ file extension these modules are not compatible with any Microsoft linker, and can only be linked with the Micro Focus assembler linker.

    As a result while assembler modules can be linked to make assembler to assembler calls static or dynamic, all Assembler to COBOL or COBOL to assembler calls must be dynamic.

Parent topic: Assembler Support Overview


About Creating, Editing and Navigating Source Code

You create and edit the source code for the Assembler modules in your project in the same way as the source code for your COBOL modules.

Some of the IDE's facilities for navigating source code are available for Assembler source code; these are:

  • Find and replace text
  • Find in files
Note: For source code downloaded from a mainframe, you might want to consider removing the sequence numbers in positions 73 through 80 of each record. The source files for Assembler support are line-sequential, variable-length files. If you omit the sequence numbers, you can also omit the trailing blanks at the end of each instruction. This can result in a significant saving of disk space on a PC.

The presence of these sequence numbers does not cause errors at assembly time.

Parent topic: Assembler Support Overview


Configuring the Environment

Using the IDE

You can configure the environment by specifying environment variables from within the IDE - using the project's properties or though properties inherited from the project dependencies.

Using the MF370CTL.CFG configuration file

The MF370CTL.CFG file holds environment variable configurations for:

  • Project file locations
  • Default memory size
  • Run Time Virtual Memory settings
  • Fileshare pathnames
  • Controlling the Generalized Trace Facility (GTF)
  • Configuring the default SQA memory size

By default, this configuration file is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin installation directory, but you can create a copy in your working directory. When you compile or run applications, the values set in the version of the file in your project's working directory override the values set in the original file in the default directory.

In your working directory, you can create a copy of the configuration file that contains project-specific settings to override the default values.

Note: It is not recommended to use the MF370CTL.CFG file if you are using the IDE to develop Assembler applications. However, if you need to use MF370CTL.CFG, the environment variables specified in it will be overridden by the settings explicitly set using the project properties or that apply through the project's dependencies.

Order in which the Assembler Compiler searches for environment variables

The Assembler Compiler searches for environment variables in the following locations in the specified order:

  1. Any variables set in the IDE using the project's properties or at the command line. The environment variables set in this way override any other values specified in other places.
  2. Any variables that are set for the environment in which the Assembler Compiler is executed.
  3. Checks the working directory for a copy of the MF370CTL.CFG file.
  4. Checks the values in the MF370CTL.CFG file in the Enterprise Developer install-dir\bin folder.
Note: You can only set the SYSLIB environment variable from within the IDE (in the project's properties click Micro Focus > Build Path and specify Assembler Macro Paths on the Dependency Paths). It is not possible to changing the value of SYSLIB from the MF370CTL.CFG file.
Parent topic: Assembler Support Overview
Related concepts
Setting Addressing Mode and Residency Mode
Configuring a Program's Memory Requirements
Introduction to File Handling
Turning GTF on and Specifying Options
Configuring the Default SQA Memory Size


Configuring Assembler Project File Locations

You can use sub-directories in your project to hold the Assembler modules and input and output file types. For these files, all assembler input and output locations are controlled by setting specific environment variables.

To set sub-directory locations, you can use the MF370CTL.CFG configuration file, or you can configure environment variables from the user interface or the command prompt, or you can use a combination of both.

Note: Environment variables set from within the IDE or from the command prompt override any environment variables set in the MF370CTL.CFG file.

For example, you can use the command line or a command file to temporarily override the project file locations set using the configuration file.

  • Using the IDE to Set Locations
  • Using the Configuration File to Set Locations
  • Using a Command File to Configure Locations
  • Component Location Environment Variables
Parent topic: Assembler Support
Related concepts
Component Location Environment Variables
Using a Command File to Configure Locations
Example: Using a Command File to Set Locations


Using the IDE to Set Locations

You can configure the location of the project output files from the project properties:

  1. In COBOL Explorer, right-click your project and click Properties.
  2. Expand Micro Focus > Build Path > COBOL.
  3. Specify the location of the output files in the Output Path field.
Note: Environment variables set from the user interface or in the environment override any environment variables set in the MF370CTL.CFG file.
Parent topic: Configuring Assembler Project File Locations


Using the Configuration File to Set Locations

You can use the MF370CTL.CFG configuration file to set the varable=value pairs that the assembler uses. You can use a MF370CTL.CFG file to maintain a project's variables in one place.

By default, this configuration file is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.

It can be helpful to copy the assembler configuration and control file, MF370CTL.CFG, into your working directory and edit the environment variables in the file to customize where input and output files should be located in your project.

Note: Environment variables set from the user interface or in the environment override any environment variables set in the MF370CTL.CFG file.
  • Example: Using MF370CTL.CFG to Set Locations
Parent topic: Configuring Assembler Project File Locations


Example: Using MF370CTL.CFG to Set Locations

The following example illustrates how to use a MF370CTL.CFG file to configure project file locations.

Consider the following project directory structure:
  • Project directory: c:\bugs\envtest
  • Source code directory: c:\bugs\envtest\source
  • Listing file directory: c:\bugs\envtest\listing
  • Object and executable file directory: c:\bugs\envtest\debug

Setting the following environment variables configures this structure:

  • SYSLIN=.\DEBUG
  • SYSLIST=.\LISTING
  • SYSLMOD=.\DEBUG

If run from the current directory command line the command:

RUN MF370CHK SOURCE\BR14 NOANIM LIST;

results in BR14.OBJ and BR14.390 placed in \debug, while the listing file BR14.PRN is placed in \listing.

To use a MF370CTL.CFG file to make these settings, you would configure the file as follows:

*------------------------------------------------------------
* The following environment variables take a single directory:
* SYSIN - Macro input .MLC files
SYSIN=.
*
* SYSLIST  - Assemble and Link listing files .MAT .PRN .LST
SYSLIST=.\listing
* SYSWORK  - Assemble, Link and Animator/370 work files .BAL .IDF/.IDX
SYSWORK=.
* SYSPUNCH - Assemble output .PCH files for PUNCH statements
SYSPUNCH=.
* SYSMPC   - Assemble input precompiled macros .MPC
SYSMPC=.
* SYSLIN   - Link input .LIN files and Assemble output .OBJ files
SYSLIN=.\debug
* SYSLMOD  - Link output load-member .390 files
SYSLMOD=.\debug
Parent topic: Using the Configuration File to Set Locations


Using a Command File to Configure Locations

You can configure project locations using a command file to set the necessary environment variables:

For example, you could create a command file to hold temporary locations. Before a compile, you could then run this command file to override the locations set in the configuration file.

  • Example: Using a Command File to Set Locations
Parent topic: Configuring Assembler Project File Locations
Related concepts
Component Location Environment Variables
Configuring Assembler Project File Locations
Example: Using a Command File to Set Locations


Example: Using a Command File to Set Locations

The following command file configures the following project file locations:

  • The assembler reads all assembler source code files from the \mlclib directory.
  • The assembler looks for all macro and copyfiles from directory \maclib and \copylib
  • Linker input files, .LIN, are taken from \linlib
  • Output files such as .BAL files are written to \worklib
  • Object files are written to \loadlib
  • Listings are written to \listing
rem *--------------------------------------------------------------------------
rem * Tell the assembler where to find all input files:
rem *
rem * MLC's from SYSIN
rem * MAC's and CPY's from SYSLIB
rem * LIN files from SYSLIN
rem * OBJ files are both input (by the linker) and output (by the assembler)
rem *     so OBJ file locations are set by SYSLIN
rem *
set SYSIN=.\mlclib
set SYSLIB=.\maclib;.\copylib
set SYSLIN=.\linlib
rem *--------------------------------------------------------------------------
rem * Tell the assembler where to write all output files.
rem *
rem * BAL/IDF/IDX files are output to SYSWORK if specified
rem * LISTING files go to SYSLIST
rem * 390 files go to SYSLMOD
rem *
set SYSWORK=.\WORKLIB
set SYSLIST=.\LISTING
set SYSLMOD=.\loadlib
rem *
rem *  Now try an assembly and a link
rem *  Note the use of the BAL assembler option to get the
rem *  assembler to produce a TEST.BAL file.  The .BAL file
rem *  should go into the SYSWORK= directory
rem *
run mm370asm test.mlc bal noanim
run mf370lnk test noanim
rem *
Parent topic: Using a Command File to Configure Locations
Related concepts
Component Location Environment Variables
Configuring Assembler Project File Locations
Using a Command File to Configure Locations


Component Location Environment Variables

Set the following environment variables to a directory path or paths to define locations. For variables that can hold multiple paths, use a semi colon (;) to separate each entry.

OBJ370
The paths for Link input .OBJ files. SYSLIN must also be set.

You can specify multiple paths, each separated by a semi colon.

STEPLIB
The paths for Loader input load-members .390 files (must contain SYSLMOD) .

You can specify multiple paths, each separated by a semi colon.

SYSIN
The path for macro input .MLC files.

You can specify a single path only.

SYSLIST
The path for Assemble and Link listing files: .MAT, .PRN, and .LST.

You can specify a single path only.

SYSWORK
The path for Assemble, Link and Animator/370 work files .BAL .IDF/.IDX.

You can specify a single path only.

SYSPUNCH
The path for Assemble output .PCH files for PUNCH statements.

You can specify a single path only.

SYSMPC
The path for Assemble input precompiled macros: .MPC.

You can specify a single path only.

SYSLIB
The paths for Assemble input macro and copy files .MAC .CPY.

You can specify multiple paths, each separated by a semi colon.

SYSLIN
The path for Link input .LIN files and Assemble output .OBJ files.

You can specify a single path only.

SYSLMOD
The path for Link output load-member .390 files.

You can specify a single path only.

Parent topic: Configuring Assembler Project File Locations
Related concepts
Configuring Assembler Project File Locations
Using a Command File to Configure Locations
Example: Using a Command File to Set Locations


Compiling and Linking Assembler Modules

This chapter provides detailed information about compiling and linking Assembler modules.

Important: Only assembler modules can be linked together. Unlike on the mainframe, COBOL and Assembler modules cannot be linked together.
  • About Compiling and Linking Assembler Modules
  • Setting Compiler Directives
  • Compiling Assembler Copybooks and Macros Containing EXEC CICS Statements
  • Linking Modules
  • Entry Point Mapping
Parent topic: Assembler Support


About Compiling and Linking Assembler Modules

In Enterprise Developer, compiling and linking is a one-stage process that takes place when your project is built - by default, Eclipse is configured to build projects automatically. You control the process by specifying build settings for Assembler. You can do this either for the whole project, for individual build configurations or for the individual source file.

If you are compiling a single Assembler module that does not use CICS, and you want to debug the module, you should not need to change any of the default build settings.

If your project contains an Assembler executable that is created by linking several Assembler object modules into one single executable, then you may need to alter the build settings for linking.

If any of the Assembler modules in your project use 24-bit addressing rather than the default 31-bit addressing, you may need to alter project settings and build settings that affect the type of memory and addressing used at execution time. It is critical that any COBOL parameter passed to an AMODE(24) Assembler module resides below the 16 megabyte addressing line so it can be accessed by the Assembler module. This is typically done by compiling the COBOL module with the AMODE(24) or DATA(24) Compiler options.

Parent topic: Compiling and Linking Assembler Modules
Related concepts
Setting Compiler Directives
Compiling Assembler Copybooks and Macros Containing EXEC CICS Statements
Linking Modules
Entry Point Mapping


Setting Compiler Directives

You can use directives to control the way the Assembler Compiler behaves. For normal operation you need no more than a few directives. Most of the time, you use the default values.

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

You set Assembler compiler directives from the command line. You can set directives to:

  • Create debug information. The Compiler stores the debug information in files filename.idf and filename.idx, where filename is the name of your program.
  • Create optimized code. An optimized code compilation fully resolves references to addresses in macro code. If the compilation of your program involves the execution of many macros, you can reduce the total compilation time by specifying this directive.
  • Mark the code as serially reusable. This prevents reloading of the module each time it is called.
  • Generate a listing file with optional cross-reference listing.
  • Link the module automatically; see the topic Linking Modules for more information.
  • Mark the code as re-entrant. This has the same effect as marking code as serially reusable.
  • Resolve external calls at link time; see the section Linking Modules for more information.
  • Set addressing mode and residency mode.
  • Specify what type of load module is to be produced, an executable code file or a data table.
  • Specify whether the module includes EXEC CICS commands, which require preprocessing. If an Assembler copybook includes EXEC CICS commands you must perform some additional steps, as described in the topic Compiling Assembler Copybooks and Macros Containing EXEC CICS Statements.
  • Use macros that have been partly pre-compiled, rather than recompiling them from the source file. If a macro source file has changed since the date of pre-compilation, it is recompiled anyway. If you have changed a copybook that is included in a macro file, you should always recompile the macro file from the source file.
  • Create Assembler Analysis Tool files. These are files that assist in the analysis of Assembler programs.
  • Provide a value for $SYSPARM, which is a variable that can be used within an Assembler module to determine which parts of the code to assemble.
Parent topic: Compiling and Linking Assembler Modules
Related concepts
About Compiling and Linking Assembler Modules
Compiling Assembler Copybooks and Macros Containing EXEC CICS Statements
Linking Modules
Entry Point Mapping


Compiling Assembler Copybooks and Macros Containing EXEC CICS Statements

Compiling an Assembler copybook or macro that contains EXEC CICS statements results in error ASMCM0060S ("Undefined operation code") if the file extension .MLC is used instead of .CAP.

This is because with these extensions, the EXEC CICS statements are not pre-processed before the copybook or macro is compiled, and the Assembler Compiler tries to interpret the EXEC statement as a macro. This results in the ASMCM0060S error mentioned above.

If Assembler modules with EXEC CICS in them are given the file extension .CAP, then the assembler runs the Assembler CICS preprocessor on them before assembling, and no errors result.

You can also set Enterprise Developer to run the Assembler CICS preprocessor on an assembler file with the .MLC extension. To do this, perform the following additional steps:

  1. Right-click the program in COBOL Explorer, and then click Properties.
  2. Click Assembler Compiler > CICS Preprocessor and specify the following build settings on the page:
    1. Check Enable file specific settings.
    2. Check Use CICS preprocessor.
    3. Ensure Insert standard prolog macros (PROLOG) and Insert standard epilog macro (EPILOG) are set to True, if needed for your Assembler module. For example, if your module has already coded an EXEC CICS compatible prolog then there is no need for the Assembler CICS preprocessor to insert one.
    4. Click OK.

      If you have not changed the Eclipse defaults, the IDE now performs a build and compiles the program with your changes.

  3. Compile the module - By default, Eclipse compiles the entire project when it detects changes in any of the sources. If you have disabled the default behavior (by clicking Project and disabling Build Automatically), to compile an individual program, right-click the file in COBOL Explorer and click Compile. .

    This creates loadlib\<program name>.bal (the preprocessor output with macros expanded) and loadlib\<program name>.pac (the preprocessor output without macros expanded).

  4. Copy loadlib\<program name>.pac to copylib\program name.cpy as appropriate.

You can now compile without errors.

Note: We recommend you create a separate Enterprise Developer project to handle Assembler copyboooks and macros that contain EXEC CICS statements as this enables you to keep your other projects separate from those that require special processing.
Parent topic: Compiling and Linking Assembler Modules
Related concepts
About Compiling and Linking Assembler Modules
Setting Compiler Directives
Linking Modules
Entry Point Mapping


Linking Modules

When you build a project containing one or more Assembler modules, the Assembler Compiler first creates an object code file (.obj) for each module. Next, you can either have the Assembler compiler automatically link the object code file into an executable load module (.390) or you can run a separate linker process that combines several object modules into a single linked load module. The link process uses its own link file (.lin) containing link commands. The Assembler automatically searches for external references in CALL commands in the object code files and includes additional object code files as necessary to resolve the external references.

Linking modules when you build the project is known as static linking. You can also link modules dynamically at execution time, when external references in LINK or LOAD commands are resolved.

  • Program Structures and Static Linking
  • Dynamic Linking
  • Mixing Static and Dynamic Linking
  • Assembler Modules that call COBOL Modules
  • Link File INCLUDE Commands
  • Other Link File Commands
Parent topic: Compiling and Linking Assembler Modules
Related concepts
About Compiling and Linking Assembler Modules
Setting Compiler Directives
Compiling Assembler Copybooks and Macros Containing EXEC CICS Statements
Entry Point Mapping


Program Structures and Static Linking

You can statically link one or more Assembler modules in several types of executable program structure, using build settings and an optional link file. Your executable program can consist of :

  • A single Assembler module which is either executed stand-alone or is dynamically called from another Assembler program or a COBOL program.
  • Several Assembler modules, one of which is the main module that calls the other modules. The main module calls the called modules using their external names (that is, there is only one entry point in each called program).
  • Several Assembler modules, one of which is the main module that calls the other modules. The main module calls the other modules using entry points other than the modules' external names.
  • Single Assembler Module
  • Multiple Assembler Modules with Calls Using External Names
  • Multiple Assembler Modules with Calls Using Entry Points
Parent topic: Linking Modules


Single Assembler Module

To link a single stand-alone Assembler module:

  1. Right-click the program in COBOL Explorer, and click Properties.
  2. Expand Assembler Compiler, and click Auto-link Settings.
  3. Check Enable file specific settings.
  4. Ensure that the Automatically link module setting in the file properties is checked, and then click OK.
Parent topic: Program Structures and Static Linking


Multiple Assembler Modules with Calls Using External Names

To link multiple Assembler modules where all the calls reference the external names of the called modules, you need to ensure that the Automatically link module and Resolve external calls at link time (CALL) settings are enabled for the main module (the calling module) and disabled for the called modules.

Note: When linking modules for the first time you may want to set Resolve external calls at link time (CALL) to false to prevent the linker from automatically generating stub modules for them. Then you can see any missing assembler or COBOL reference that are required for this module.

You can find both of these settings in your file properties on the Assembler Compiler > Auto-link Settings page and in Micro Focus > Project Settings > Assembler Compiler > Auto-link Settings in your project properties.

Since all the calls reference the modules' external names, the Assembler Compiler finds and locates all the called modules in your Assembler source libraries, and builds the main and called modules into one .390 file. Once this .390 load module is brought into memory by the COBOL run-time loader, all public entry points in the .390 module are callable by any other COBOL or Assembler module.

Parent topic: Program Structures and Static Linking


Multiple Assembler Modules with Calls Using Entry Points

To link multiple Assembler modules where the calls reference entry points in the called programs rather than their external names, you need to:

  1. Ensure that Automatically link module is unchecked for all the modules in the project.

    You can find this setting on the Assembler Compiler > Auto-link Settings page in the file properties.

  2. Ensure that Resolve external calls at link time (CALL) is enabled.

    You can find this setting in your project properties and on the Micro Focus > Project Settings > Assembler Compiler > Auto-link Settings page.

  3. Create a link file (.lin) that lists all of the object files to be included with the main module in the executable file. This link file must have the same name as the main module. For example if the main module has the name mymain.mlc, the link file must have the name mymain.lin.

If you compile individual modules, you must select the .lin file for compilation too. If you build or rebuild the whole project, the .lin file is compiled with the other source files but will always be linked after any assembly to ensure that only the latest .OBJ files are linked. In either case, the Assembler Linker looks in the .lin file to find which object files need to be included in the executable .390 or .MOD file.

Parent topic: Program Structures and Static Linking


Dynamic Linking

If you want to link modules dynamically at run-time, you have two choices:

  • You can code your calling module to check whether the called module is already available. This way you retain the option to link modules statically sometimes. Each calling module that calls another module first tests the external reference address, and then if it is zero, issues a LOAD for the module, saving the address in the external reference field, then a BALR to go to the called module. With this method you must also specify the Linker directive NCAL when you build the executable program.

    To do this, disable Resolve external calls at link time (CALL) in your project properties and on the Micro Focus > Project Settings > Assembler Compiler > Auto-link Settings tab.

    With NCAL set, the linker issues warnings that external references were not resolved and stores zero in each field holding the address of an external reference.

  • You can code your calling module to link dynamically always. You simply issue a LOAD for the module you want to link to, then a BALR to branch to it. With this method it makes no difference whether you specify the NCAL Linker directive or not.

We recommend that you also mark each module in this environment as reentrant and serially reusable, so that modules are not deleted and reloaded for each call.

To mark a module as reentrant:

  • In your project properties and on the Micro Focus > Project Settings > Assembler Compiler tab, set Mark module as reentrant (RENT) to true.

To mark a module as serially reusable:

  • In your project properties and on the Micro Focus > Project Settings > Assembler Compiler > Auto-link Settings tab, set Mark load module as serially reusable (REUS) to true.

If you want to use static linking on a module that is normally dynamically linked, and its END statement names a default entry point for the module, you may need to provide an ENTRY command in the linker input file, .LIN, to override the default entry point. This is because the Linker, emulating the mainframe binder tool, sets the entry point for the entire executable program to the entry point named on the END statement of the final included module.

Parent topic: Linking Modules


Mixing Static and Dynamic Linking

If you want to link some modules statically and others dynamically, you need to:

  • Specify the Linker directive CALL when you build the executable program. To do this:
    • Set Resolve external calls at link time (CALL) to true in your project properties and on the Micro Focus > Project Settings > Assembler Compiler > Auto-link Settings tab.

    With CALL set, the linker attempts to resolve all external references.

  • Ensure that for each module that you want to call dynamically, you include an INCLUDE command in the link file with the operand TYPE=COBOL or TYPE=ASM. When the Linker processes the INCLUDE command, it does not actually include the module, but instead generates and includes a small Assembler module to dynamically call that entry point. When the CALL is executed at run time, the Assembler module asks the cobol run time to load the module and transfer control to it.

If there are any entry points defined in the statically linked modules that match entry points in the dynamically linked modules, you must also use the Linker directive NOEXPORT, to prevent the linker from making any of the entries in the executable program available to calling programs after it is loaded into memory. By default any ENTRY or CSECT or START symbol in all Assembler modules are normally loaded into the cobol run time system’s entry point table so NOEXPORT will prevent this behaviour. Also use an ALIAS link file commands for the statically linked modules, including the main executable program. This technique gives you precise control over the type of linking you use for each module.

Parent topic: Linking Modules


Assembler Modules that call COBOL Modules

You must use dynamic linking if your Assembler module calls a COBOL module. By definition, all calls from assembler to cobol and vice versa are dynamic because Assembler .OBJ files and COBOL .OBJ files cannot be linked together. There are two methods of dynamically linking to COBOL modules:

  • You can issue a CALL macro call in your Assembler program. With this method you also need to put an INCLUDE command in a link file for the assembler module giving the name of the cobol module that you want to link to. When the Linker processes the INCLUDE command, it does not actually include the COBOL module, but instead generates and includes a small Assembler module. When the CALL is executed at run time, the Assembler module loads and links to the COBOL module entry point specified.
  • You can issue a LOAD macro call in your Assembler program. Again, the LOAD macro does not load the COBOL module directly, but instead creates and loads an Assembler module the address of which is returned by the LOAD. You then issue a BALR instruction specifying this address. The small Assembler stub module then performs a dynamic CALL to the COBOL module desired.
    Note: Note that if you use this option you must use standard Assembler to COBOL linking which means the high bit in the last parameter address being passed is set so that the COBOL program being called can determine the correct number of parameters being passed.

    Whenever a COBOL program calls an Assembler module this linkage is also automatically done and the assembler module will be entered with register 1 pointing at the list of addresses, one address per parameter passed, and the last parameter will have its high bit set to indicate the end of the parameter list.

Parent topic: Linking Modules


Link File INCLUDE Commands

You need an INCLUDE command in your link file for each module that you want to be linked with the main module to produce one .390 file.

Here is an example of a link file. Assume that assemA is the main Assembler module that calls assemB, assemC and cobolD (with two parameters). The link file assemA.lin contains the following three records:

INCLUDE SYSLIB(assemB)

INCLUDE SYSLIB(assemC)

INCLUDE SYSLIB(cobolD),TYPE=CBL,PARMS=2

The TYPE parameter specifies the language of the called module and is optional; it defaults to ASM (for Assembler) if the main module is Assembler. The PARMS parameter specifies the number of parameters to be passed to the called program; you only need to specify it if TYPE=CBL (for COBOL) . There are options that allow you to call a COBOL IMS program and to call a program with a variable number of parameters.

Parent topic: Linking Modules


Other Link File Commands

Link files can also contain the following commands:

  • NAME. Use this command to specify a name for the executable file other than the name of the source. For example, the name of the source file might be myprog.mlc, but you may want the executable to have the name program1.390
  • ENTRY. Use this command if the executable file you are building may be called by another program, and you want all such calls to enter the program at a particular entry point, rather than the beginning of the program.
  • ALIAS. Use this command to create an alias for the executable file that you are building. The alias is created in the entry point mapping file mfentmap.dat.
  • CHANGE. Use this command to change the names of external symbols in the object module named in the next INCLUDE command
Parent topic: Linking Modules


Entry Point Mapping

If one module calls another using the LOAD statement and the call is to an entry point within the module rather than to the external name of the module, you need to specify the relationship between the entry point and the module. You can do this by either:

  • Specifying the AUTOALIAS Linker directive; this directs the Linker to generate automatic entries in the mfentmap.dat file for all entry points.
  • Editing the entry point mapping file mfentmap.dat.
Parent topic: Compiling and Linking Assembler Modules
Related concepts
About Compiling and Linking Assembler Modules
Setting Compiler Directives
Compiling Assembler Copybooks and Macros Containing EXEC CICS Statements
Linking Modules


Debugging Assembler Applications

You can debug Assembler and Assembler/COBOL applications using the Assembler Debugger. This debugger appears in a separate window, outside of the IDE.

  • Compiling Assembler Programs for Debugging
    Describes how to compile Assembler for debugging.
  • Configuring an Enterprise Server Region for Debugging
    Describes the requirements for an enterprise server region used to debug an Assembler application.
  • Starting the Assembler Debugger
    Describes the methods available for starting the Assembler Debugger from the command line, from JCL, and from the IDE for standalone programs, Assembler applications, and mixed Assembler and COBOL applications.
  • How to...
Parent topic: Assembler Support


Compiling Assembler Programs for Debugging

Before you can debug an Assembler program, you must compile it for debugging either in the IDE or from the command line. The compiler generates an Assembler .390 file.

Compiling from the IDE
Before you compile your Assembler module from the IDE, be sure that the Create debug information (ANIM) property is set on the Assembler Compiler page in your project or program properties. This is the default. The resulting filename.390 file is placed in the build output directory for the project.
Compiling from the Command Line
From a 32-bit Enterprise Developer command prompt, change to the directory that contains your Assembler module; then enter the following command:
run mm370asm filename ANIM [otherDirectives];
where filename is the name of your Assembler module, and otherDirectives can be any additional Assembler compiler directive options as required. The resulting filename.390 file is placed in the current directory.

Note that, if you are compiling for debugging from the command line and later rebuild the application from within the IDE, the debugging information produced from compiling from the command line is deleted if the IDE is not configured to produce it as well.

Parent topic: Debugging Assembler Applications


Configuring an Enterprise Server Region for Debugging

To debug any application containing one or more Assembler modules, with the exception of an application consisting of a standalone Assembler program, you must have an enterprise server available to run the application.

You configure an enterprise server to run an Assembler or an Assembler/COBOL application in much the same way as you would for any COBOL application. Depending on the type of application, be sure to include the path to your Assembler programs on the appropriate path specifications as follows:
  • JCL - JES Program Path
  • CICS - Transaction Path
  • CICS - File Path
  • IMS - TM Application Path

The ES_SERVER_CONSOLE=YES variable must be specified in the enterprise server configuration for the server that will be used to debug Assembler modules.

Non-CICS applications that contain both Assembler and COBOL require that you turn on (check) Allow Dynamic Debugging in the enterprise server configuration.

CICS applications require that you also set the environment ES_MFASM_SUPPORT=YES variable in the Configuration Information field in the enterprise server configuration:
[ES-Environment]
ES_MFASM_SUPPORT=YES
ES_SERVER_CONSOLE=YES
Parent topic: Debugging Assembler Applications


Starting the Assembler Debugger

The method required to start the Assembler Debugger varies depending on how the program or programs are invoked, and the components that make up your application.

Important: All methods require that you first compile your application for debugging. All methods except the Standalone Assembler Program method require that you configure an enterprise server to run the application before debugging the application.
Standalone Assembler Program
To debug a single Assembler program from the command line:
  1. From a 32-bit Enterprise Developer command prompt, change to the directory that contains your Assembler executable file.
  2. Enter the following:
    run filename.390
    where filename.390 is the name of your Assembler executable file.

The Assembler Debugger starts in a command window.

Assembler Program Started from JCL
To debug an assembler program that is invoked via JCL, do all of the following from the same 32-bit Enterprise Developer command prompt:
Alternatively, if you are using the command line, to debug an assembler program that is invoked via JCL, do all of the following from the same 32-bit Enterprise Developer command prompt:
  1. Set the following environment variable:
    es_server_console=y
    Note: Failure to set this environment variable before starting the enterprise server results in an RTS197 error when the Assembler application is executed.
  2. Start the enterprise server from within the IDE or from the same Enterprise Developer command prompt using the following command:
    casstart /rServerName
  3. In the IDE, submit the JCL that invokes the Assembler program.

The Assembler Debugger starts in a command window when the JCL executes the Assembler program.

CICS or IMS Assembler Application
To debug a CICS or IMS application that is comprised entirely of assembler programs:
  1. From a 32-bit Enterprise Developer command prompt, set the following environment variable:
    es_server_console=y
    Note: Failure to set this environment variable before starting the enterprise server results in an RTS197 error when the Assembler application is executed.
  2. Start the server from within the IDE or from a 32-bit Enterprise Developer command prompt:
    casstart /rServerName
  3. From the same 32-bit Enterprise Developer command prompt, start a server execution process:
    start cassi /rServerName /a
  4. Run the application using a TN3270 terminal emulator.

    If you have installed Micro Focus Rumba as part of the Enterprise Developer installation, you can use the Rumba TN3270 Mainframe Display integrated with the IDE or the standalone Rumba Desktop.

    The Assembler Debugger starts in a command window.

COBOL and Assembler in a Non-CICS Application
To debug a non-CICS application comprised of both COBOL and Assembler programs:
  1. In Enterprise Developer, associate your enterprise server with the project.
  2. From a 32-bit Enterprise Developer command prompt, set the following environment variable:
    es_server_console=y
    Note: Failure to set this environment variable before starting the enterprise server results in an RTS197 error when the Assembler application is executed.
  3. From the same 32-bit Enterprise Developer command prompt, start the server:
    casstart /rServerName
  4. From the IDE, start debugging the application.
  5. Run the application in a 3270 terminal emulator such as Rumba.

The COBOL programs are debugged in the IDE, and the Assembler programs are debugged in the Assembler Debugger, which appears in a separate window.

COBOL and Assembler in a CICS Application

When you have an application that consists of both COBOL and Assembler programs, the COBOL programs are debugged in Enterprise Developer, and the Assembler programs are debugged in the Assembler Debugger, which appears in a separate window.

To debug a CICS application comprised of both COBOL and Assembler programs:

  1. In the IDE, open the project that contains the application you want to debug.
  2. From a 32-bit Enterprise Developer command prompt, set the following environment variable:
    es_server_console=y
    Note: Failure to set this environment variable before starting the enterprise server results in an RTS197 error when the Assembler application is executed.
  3. From the same 32-bit Enterprise Developer command prompt, start the server:
    casstart /rServerName
  4. From the same 32-bit Enterprise Developer command prompt, start a server execution process:
    start cassi /rServerName /a
  5. Run the application in a 3270 terminal emulator such as Rumba.
Parent topic: Debugging Assembler Applications


How to...

  • To change a floating-point register value
  • To change a general-purpose register value
  • To change colors on Assembler debugger
  • To clear breakpoints
  • To examine an instruction
  • To execute a sequence of instructions
  • To execute the rest of the module or program
  • To find parts of the code
  • To find the next executable instruction
  • To get help while debugging
  • To jump instructions
  • To monitor module exits
  • To navigate your Assembler source code
  • To perform hexadecimal and decimal additions
  • To recall the last message
  • To set address breakpoints
  • To set branch breakpoints
  • To set opcode breakpoints
  • To set register breakpoints
  • To specify a hexadecimal value
  • To step through code
  • To stop debugging
  • To view debugging status information
  • To view floating-point registers
  • To view new dumps
  • To view previous dumps
  • To toggle zSeries and OS390 general-purpose registers
Parent topic: Debugging Assembler Applications


To change a floating-point register value

  1. From the Assembler debug window, press R (Reg) for a window to appear, containing four choices.
  2. Press 2, for Floating Point Register Modify.
  3. Enter the number of the register you want to modify. Floating-point registers are numbered 0, 2, 4 and 6.
  4. Enter the new value.
Parent topic: How to...
Related tasks
To change a general-purpose register value
To view floating-point registers
To toggle zSeries and OS390 general-purpose registers


To change a general-purpose register value

  1. From the Assembler debug window, press R (Reg) for a window to appear, containing four choices.
  2. Press 1, for General Register Modify.
  3. Enter the number of the register you want to modify. Registers are numbered 0 to F, where A to F represent 10 to 15.
  4. Enter the new hexadecimal value.
Parent topic: How to...
Related tasks
To change a floating-point register value
To view floating-point registers
To toggle zSeries and OS390 general-purpose registers
To specify a hexadecimal value


To change colors on Assembler debugger

  1. From the Assembler debug window, press C (Color) to display the Color menu.
  2. Select the part of the screen you want to change by pressing:
    T | Trace panel
    L | List panel
    R | Register panel
    K | Menu keys
    M | Menu text
  3. Select which part of the color to change by pressing:
    B | Background. The background of the selected area cycles through eight colors as you press B repeatedly
    F | Foreground. The foreground (that is, the text) of the selected area cycles through 8 colors as you press F repeatedly.
    I | Intensity. The color of the selected area toggles between bright and dim as you press I repeatedly.
  4. Press S (Save) to save these new settings or Esc to exit without saving.
Parent topic: How to...
Related tasks
To navigate your Assembler source code


To clear breakpoints

  • From the Assembler debug window, press U (Unset).
Parent topic: How to...
Related tasks
To set address breakpoints
To set branch breakpoints
To set opcode breakpoints
To set register breakpoints
To monitor module exits


To examine an instruction

  1. From the Assembler debug window, press P (Probe) for a window with detailed information about the current instruction.
  2. Press P again to see two dumps, one for each operand.
  3. Press P again to remove the window.
Parent topic: How to...
Related tasks
To execute a sequence of instructions
To find the next executable instruction
To jump instructions
To step through code


To execute a sequence of instructions

  1. From the Assembler debug window, scroll down the list of instructions until line 18 shows the instruction where you want the debugger to stop.
  2. Press T (syncTrace) to execute the instructions between the current instruction and the instruction on line 18.
Parent topic: How to...
Related tasks
To examine an instruction
To find the next executable instruction
To jump instructions
To step through code


To execute the rest of the module or program

  • From the Assembler debug window, press one of the following:
    G | (Go) to execute the rest of the module. The debugger scrolls though the instructions on the trace panel (and the listing panel, if syncMode is ON).
    Z | (Zoom) to execute the rest of this module, plus any other modules loaded or called, including this one if entered again. If an abend occurs or a breakpoint is reached, the Assembler debug window reappears in step mode with all the panels updated.
    N | (Next) to execute the rest of this module. If this module is re-entered or another module is called or loaded, or an abend occurs or a breakpoint is reached, the Assembler debug window reappears in step mode with all the panels updated.
    Q | (Quiet) to return to normal execution. The debug window only reappears if an abend occurs.
Parent topic: How to...


To find parts of the code

  1. From the Assembler debug window, press F (Find) for a Window to appear, containing four choices:
    • To find a label, press 1; then enter the label
    • To find a value, press 2; then enter the value
    • To find the first occurrence of a particular Assembler statement, press 3; then enter the statement
    • To find an address, press 4; then enter the address
Parent topic: How to...
Related tasks
To find the next executable instruction


To find the next executable instruction

  • From the Assembler debug window, press L (SyncList) so that the line that is about to be executed is shown on line 18 of the screen, just above the register values.
Parent topic: How to...
Related tasks
To examine an instruction
To execute a sequence of instructions
To jump instructions
To step through code
To find parts of the code


To get help while debugging

  1. Click the Assembler debug window
  2. Press F1 to bring up a window with three choices:
    • Press 1 to see a list of Assembler instructions in opcode sequence. You can scroll through this list by pressing Page Up and Page Down. You can also press S and enter an opcode to see detailed information on that opcode
    • Press 2 to see some introductory information about the Assembler debug window
    • Press 3 to see the Help menu
  3. Press Escape to exit from Help
Parent topic: How to...


To jump instructions

  1. From the Assembler debug window, press J (Jump).
  2. Enter the address of the instruction to jump to, and execute.
Parent topic: How to...
Related tasks
To examine an instruction
To execute a sequence of instructions
To find the next executable instruction
To step through code


To monitor module exits

  1. From the Assembler debug window, press E (Exit); then:.
    • Specify Y against Halt on DETACH to have execution halt just before control passes back to a COBOL calling program.
    • Specify Y against Halt on ? BRANCH to have execution halt and a message displayed if the Assembler module attempts to branch outside its address space.
  2. If you only change the first option or you make no changes, press Enter or Esc to close the Exits window.
Parent topic: How to...
Related tasks
To clear breakpoints
To set address breakpoints
To set branch breakpoints
To set opcode breakpoints
To set register breakpoints


To navigate your Assembler source code

  1. Click the Assembler debug window.
  2. Press + or - to move up and down through the source code.
  3. Press Page Up or Page Down to move up or down through the source code one page at a time.
Parent topic: How to...
Related tasks
To change colors on Assembler debugger
To step through code
To stop debugging


To perform hexadecimal and decimal additions

  1. From the Assembler debug window, press H (Hex/add).
  2. In the calculator window:
    • Press Enter to cycle around the three lines in which you can enter the numbers to be added and the menu line.
    • Enter H or D to switch between working in hexadecimal and working in decimal.
    • Enter C to clear the current addition.
    • Enter K to keep the current addition and return to the main debug window.
  3. Press Esc to close the calculator window.
Parent topic: How to...
Related tasks
To specify a hexadecimal value


To recall the last message

  1. From the Assembler debug window, hold down the Shift and press ?.
Note: Messages appear on line 1 of the Assembler debug window.
Parent topic: How to...
Related tasks
To view debugging status information


To set address breakpoints

  1. From the Assembler debug window, press B (Breakpoint) for a window to appear, containing four choices.
  2. Press 1.
  3. Specify up to four relative addresses in hexadecimal.
  4. Press Enter.
Parent topic: How to...
Related tasks
To clear breakpoints
To set branch breakpoints
To set opcode breakpoints
To set register breakpoints
To monitor module exits
To specify a hexadecimal value
To view debugging status information


To set branch breakpoints

  1. From the Assembler debug window, press B (Breakpoint) for a window to appear, containing four choices.
  2. Press 3
  3. Enter Y or N for each type of branch on which you can set a breakpoint:
    • BCr halts execution on all successful Branch-on-Condition and Branch-on-Condition-Register instructions
    • BALR/BR14 halts execution on the following instructions:
        BALR  14,15
  BASR  14,15
  BAL   14,label
  BAS   14,label
  BR    14
    • BCTr halts execution on all successful Branch-on-Count instructions when the count register reaches zero
    • BALr/BASr halts execution on all Branch-on-Link and Branch-on-Save instructions
  4. Press Enter.
Parent topic: How to...
Related tasks
To clear breakpoints
To set address breakpoints
To set opcode breakpoints
To set register breakpoints
To monitor module exits


To set opcode breakpoints

  1. From the Assembler debug window, press B (Breakpoint) for a window to appear, containing four choices.
  2. Press 2
  3. Specify up to two opcodes.
  4. Press Enter.
Note: If you set a breakpoint on opcode 'SVC', you can zoom to each supervisor call in turn to check your macros.
Parent topic: How to...
Related tasks
To clear breakpoints
To set address breakpoints
To set branch breakpoints
To set register breakpoints
To monitor module exits


To set register breakpoints

  1. From the Assembler debug window, press B (Breakpoint) for a window to appear, containing four choices.
  2. Press 4.
  3. Enter a register number (0 through 15).
  4. Enter a relation condition (EQ = equal, NE = not equal, GT = greater than, GE = greater than or equal, LT = less than, LE= less than or equal, AC = any condition, ** to unset).
  5. Enter a hexadecimal value.
  6. Repeat steps 4 through 6 until you have set all the register breakpoints you need.
  7. Press Esc to remove the register breakpoints window.
Parent topic: How to...
Related tasks
To clear breakpoints
To set address breakpoints
To set branch breakpoints
To set opcode breakpoints
To monitor module exits


To specify a hexadecimal value

These are four alternative ways of specifying the hexadecimal value h"0000025C" assuming that Register 3 contains this value, Register 4 contains h"00000200" and the module was loaded at address h"00000200".

  • Enter 25C, followed by a space. (You do not need to type all the leading zeros.)
  • Enter R3, followed by a space
  • Enter R4+5C, followed by a space
  • Enter L+5C, followed by a space
Note: The fourth method, which uses Load Notation, allows you to specify an absolute address by giving a displacement from the address where the module was loaded. You can specify the load address of the module using L on its own.
Parent topic: How to...
Related tasks
To change a general-purpose register value
To perform hexadecimal and decimal additions
To set address breakpoints


To step through code

  • From the Assembler debug window, press S (Step) to execute the current instruction.
Parent topic: How to...
Related tasks
To examine an instruction
To execute a sequence of instructions
To find the next executable instruction
To jump instructions
To navigate your Assembler source code


To stop debugging

  1. From the Assembler debug window, press Esc while the Assembler is debugging.
  2. Press one of the following:
    • 1 to ignore the cancel request.
    • 2 to cancel just the execution of this module.
    • 3 to cancel the entire job.
  3. Click Stop Debugging on the Debug menu.
Note: You can also cancel the whole job just by clicking Stop Debugging on the Debug menu.
Parent topic: How to...
Related tasks
To navigate your Assembler source code


To view debugging status information

  1. From the Assembler debug window, press I (Information).
  2. Press Esc to close the status information window.
Note: The information shown includes the program status word (PSW) which shows the current instruction being executed; the high-order bit indicates whether the program is executing in 31-bit mode (bit on) or 24-bit mode (bit off).

With the status information window open, Press - or Page Down to view a list of currently loaded programs with their entry addresses. This information may help you when you are setting address breakpoints.

Parent topic: How to...
Related tasks
To recall the last message
To set address breakpoints


To view floating-point registers

  1. From the Assembler debug window, press R (Reg) for a window to appear, containing four choices.
  2. Press 3, for Floating Point Display.
Note: The floating-point registers are displayed on line 21. Repeating this task hides the floating-point registers.

If the OS/390 general-purpose registers are being displayed, you see the four OS/390 floating-point registers. If the zSeries general-purpose registers are being displayed, you see the sixteen zSeries floating-point registers.

The floating-point registers are always displayed in IBM double-precision IBM hexadecimal format regardless of the actual precision or the actual type of format (IBM or IEEE).

Parent topic: How to...
Related tasks
To change a floating-point register value
To change a general-purpose register value
To toggle zSeries and OS390 general-purpose registers


To view new dumps

  1. From the Assembler debug window, ress D (Dump) to show the Dump menu.
  2. Press 1 for the first dump.
  3. Type the address you require and press Enter.
  4. Repeat steps 3 and 4 to view a second dump, entering 2 at step 3.
  5. At this point you can:
    • Switch between dump windows by pressing 1 or 2.
    • Modify memory by pressing M, entering the location of the first byte you want to modify, then entering the new value in hexadecimal.
    • See the dump previously requested, by pressing P.
    • Change the starting point of the selected dump, by pressing A then entering a new address in hexadecimal.
    • See the text equivalents of the hexadecimal values by entering T.
    • Scroll up and down the selected dump by pressing + or -.
  6. Press Esc twice to remove the dump windows.
Parent topic: How to...


To view previous dumps

  1. From the Assembler debug window, press O (Odump) to recall the dumps you last viewed.
  2. Press Esc twice to remove the dump windows.
Parent topic: How to...


To toggle zSeries and OS390 general-purpose registers

  1. From the Assembler debug window, press R (Reg) for a window to appear, containing four choices.
  2. Press 4. If the OS/390 32-bit general-purpose registers were being displayed, they are replaced by the zSeries 64-bit general purpose registers, and vice versa.
Parent topic: How to...
Related tasks
To change a floating-point register value
To change a general-purpose register value
To view floating-point registers


Configuring Runtime Memory Requirements

The topics in this section describe how to configure memory requirements.

  • About Memory Requirements
  • Setting Addressing Mode and Residency Mode
  • Configuring the Default SQA Memory Size
  • Reserving Memory for Execution
  • Run Time Memory Environment Variables
Parent topic: Assembler Support
Parent topic: Assembler Support


About Memory Requirements

On the mainframe, an area of memory can be located either below the line or above the line. The term 'the line' means the point at which the address of an area of memory requires four bytes to hold it. Three-byte addresses can point to memory up to 16Mb. Any area of memory starting at a higher point than this requires a four-byte address. Four-byte addresses are actually 31-bit addresses, since bit 0 is used for other purposes. A 31-bit address can point to memory up to 2Gb.

The memory requirements of an Assembler program are indicated by its AMODE (or addressing mode) and RMODE (or residency mode). AMODE governs the type of addresses the program uses, while RMODE indicates where the program must be located when it is loaded for execution.

There are two AMODE values:

  • AMODE(24) indicates 24-bit (three-byte) addressing - memory below the line
  • AMODE(31) indicates 31-bit addressing - memory above and below the line.

You can set AMODE to 24 or 31 for Assembler, since we emulate both types of addressing by mapping mainframe-style above and below the line addresses to real 32-bit PC memory addresses. An AMODE (24) program can only access memory below the line, while an AMODE(31) program can access memory both below and above the line.

There are two RMODE values:

  • RMODE(24) indicates that the program must be loaded into memory below the line.
  • RMODE(31) indicates that the program can be loaded either below or above the line.
Parent topic: Configuring Runtime Memory Requirements
Related concepts
Program Only Uses Memory Above the Line
Program Only Uses Memory Below the Line


Setting Addressing Mode and Residency Mode

The memory requirements of an Assembler program are indicated by its AMODE and RMODE:

  • AMODE (or addressing mode) governs the type of addresses the program uses.
  • RMODE (or residency mode) indicates where the program must be located when it is loaded for execution.
We support two AMODE values:
  • AMODE(24) - Tells the assembler runtime to set the addressing mode bit in the Processor Status Word (PSW) to 0 when the module is called from a COBOL program. This sets the initial addressing mode to 24-bit.
  • AMODE(31) - Tells the assembler runtime to set the addressing mode bit in the PSW to 1 when the module is called from a COBOL program. This sets the initial addressing mode to 31-bit.
Note:
  • When an assembler program loads and branches into another assembler module, Assembler ignores the AMODE setting of the called module and preserves the current setting of the address mode bit in the PSW.
  • You can use the DATA(24) COBOL compiler directive to ensure that the addresses assigned in the Working-Storage Section of the COBOL module are below the 16 MB threshold, irrespective of any AMODE setting.
Parent topic: Configuring Runtime Memory Requirements
Related concepts
Configuring the Environment
Configuring a Program's Memory Requirements
Introduction to File Handling
Turning GTF on and Specifying Options
Configuring the Default SQA Memory Size


Configuring the Default SQA Memory Size

You can use the MF370CTL.CFG file set the default SQA memory. You can also set the default memory above and below the line through the user interface.

Note: The settings in the user interface override any settings in the MF370CTL.CFG file.
For example, the following entry sets the SQA memory size to 3 Mb:
VM370=3000   ; set SQA size to 3Meg
Parent topic: Configuring Runtime Memory Requirements
Related concepts
Configuring the Environment
Setting Addressing Mode and Residency Mode
Configuring a Program's Memory Requirements
Introduction to File Handling
Turning GTF on and Specifying Options


Reserving Memory for Execution

When the Assembler run-time system is initialized, it allocates an area of memory called the system queue area to the executable program. You can specify how much of this memory is below the line and how much is above the line.

The main executable program and any other executables that it loads are loaded into memory below or above the line depending on the program's RMODE settings. When a program issues requests for extra memory using the macros GETMAIN or STORAGE OBTAIN, it can specify whether the memory needs to come from the below-the-line allocation or the above-the-line allocation, depending on its addressing needs.

In general the assembler run time allocates memory addresses bottom up from absolute address 0, while the COBOL run time allocates memory addresses top down, either from the 2 gigabyte line down, or the 16 megabyte line down.

  • Setting the Run Time Virtual Memory Environment
  • Example: Runtime Virtual Memory Configuration
Parent topic: Configuring Runtime Memory Requirements


Setting the Run Time Virtual Memory Environment

Run time virtual memory is controlled by environment variables set in the MF370CTL.CFG file

This file is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.

These control the amount of virtual memory which the 370 assembler emulator uses when the first assembler module is called:

Parent topic: Reserving Memory for Execution


Example: Runtime Virtual Memory Configuration

The following is a typical MF370CTL.CFG virtual memory configuration file located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory:
*--------------------------------------------------------------------------
* RUN TIME VARIABLES
MFPM=ON                   ; mainframe pointer manager is on by default
SVC370=MFI                ; set engine to MFI-mode
MEMSIZE=00000000,7FFFFFFF ; set valid address range
VM370=3000                ; set SQA size to 3Meg
AMODE370=31               ; run in 31-bit mode
Parent topic: Reserving Memory for Execution


Run Time Memory Environment Variables

The following environment variables control the run time virtual memory

MFMP
This must be set to ON for assembler to execute.
Example:

MFMP=ON

SVC370
This switch is related to backward compatibility. It must always be set to MFI.
Example:

SVC370=MFI

MEMSIZE=<LOW>,<HIGH>
Maximum 370 linear address that assembler modules can address. A value of 0,7FFFFFFF addresses the bottom 2 gigabytes of 370 virtual memory
Example:

MEMSIZE=0,7FFFFFFF

VM370
Amount of memory, starting at absolute address 0, to be allocated for the use of 370 assembler modules to be loaded into. Default is 3 meg below the 16 meg address line.
Example:

VM370=3000

AMODE370
Tells the assembler emulator which addressing mode to initially start in when the first assembler module is called.
Example:

AMODE370=31

Parent topic: Configuring Runtime Memory Requirements


Configuring a Program's Memory Requirements

Configuring access to the type of memory you require involves several steps. You must:

  1. Specify how much memory the program needs below the line and above the line, using the Max. memory below 16Mb line and Max. memory above 16Mb line fields. You can find these settings in the MF370CTL.CFG (assembler control and configuration file) which is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory. The default values are:
    * RUN TIME VARIABLES
MFPM=ON                   ; mainframe pointer manager is on by
                          ;  default
SVC370=MFI                ; set engine to MFI-mode
MEMSIZE=00000000,7FFFFFFF ; set valid address range

* THE FOLLOWING RUN TIME VARIABLES ARE OVERRIDDEN BY
* THE SETTINGS IN
* THE IDE PROJECT, PROJECT OPTIONS PULLDOWN.
VM370=3000                ; set SQA size to 3Meg
AMODE370=31               ; run in 31-bit mode
    The most likely value you will need to change will be the VM370= value, which allocates the default size of assembler memory to allocate when the first assembler module is called in a COBOL run unit.
  2. Specify the addressing mode for each Assembler program that does not need a separate link file to control the production of an executable code file, including any programs that the main program calls, using the Addressing mode field, set on the Link page of the Property Pages for the program.
  3. Ensure that all your GETMAIN or STORAGE OBTAIN macro calls indicate which type of memory is required.

The following sections cover most possibilities.

  • Program Only Uses Memory Below the Line
  • Program Only Uses Memory Above the Line
  • Program Uses Memory Below and Above the Line
  • Setting Residency Mode
  • Using Subpools
Parent topic: Assembler Support
Related concepts
Configuring the Environment
Setting Addressing Mode and Residency Mode
Introduction to File Handling
Turning GTF on and Specifying Options
Configuring the Default SQA Memory Size


Program Only Uses Memory Below the Line

If your program only needs to address memory below the line, you should:

  1. Set Max. memory below 16Mb line to the maximum amount of memory below the line that your program requires. The default is 3Mb and the maximum is 16Mb.
  2. Set Addressing mode to AMODE(24) for the main program and for each program that the main program loads.
  3. Omit the LOC parameter from all GETMAIN or STORAGE OBTAIN macros issued by your program.
Parent topic: Configuring a Program's Memory Requirements
Related concepts
About Memory Requirements


Program Only Uses Memory Above the Line

If your program needs to address memory above the line, you should:

  1. Set Max. memory above 16Mb line to the maximum amount of memory above the line that your program requires. The default is 3Mb and the maximum is 2Gb.
  2. Set Addressing mode to AMODE(31) for the main program and for each program that the main program loads.
  3. Set LOC=ANY in all GETMAIN and STORAGE OBTAIN macros issued by your program.
Parent topic: Configuring a Program's Memory Requirements
Related concepts
About Memory Requirements


Program Uses Memory Below and Above the Line

If your program needs to address both types of memory, that is, you have a mix of some modules that use memory below the line and others that use memory above the line, you should:

  1. Set Max. memory below 16Mb line to the maximum amount of memory below the line that your program requires. The default is 3Mb and the maximum is 16Mb.
  2. Set Max. memory above 16Mb line to the maximum amount of memory above the line that your program requires. The default is 3Mb and the maximum is 2Gb.
  3. Set Addressing mode to AMODE (24) for each program to be loaded that uses memory below the line.
  4. Set Addressing mode to AMODE (31) for each program to be loaded that uses memory above the line.
  5. To allocate memory below the line, omit the LOC parameter from all GETMAIN and STORAGE OBTAIN macros that the module issues.
  6. To allocate memory above the line, set LOC=ANY in all GETMAIN and STORAGE OBTAIN macros that the module issues.
  7. Use the Assembler instructions BASSM or BSM to transfer control between programs that use different addressing modes.
Note:
  • If a program that uses 31-bit addressing needs to manipulate 24-bit addresses, you must include code to clear the unused byte of the address before any instruction that sets a register to a new address. These instructions include LA, BAL, BALR, EDMK and TRT.
  • You can only set LOC=ANY on the RU and RC formats of the GETMAIN macro. The R format of GETMAIN is restricted to memory below the line.
Parent topic: Configuring a Program's Memory Requirements


Setting Residency Mode

You specify the residency mode of a program and of any programs that the main program calls using the Residency mode field. Residency mode appears in two places:

Specify the residency mode for each Assembler program that does not need a separate link file to control the production of an executable code file, including any programs that the main program calls, using the Residency mode field, set on the Link page of the Property Pages for the program.

The valid combinations of AMODE and RMODE are:

  • AMODE(24) and RMODE(24)
  • AMODE(31) and RMODE(31)
  • AMODE(31) and RMODE(24): use this combination where the Assembler program contains 24-bit address constants but needs to be executed in 31-bit addressing mode so that it can handle 31-bit addresses passed as parameters by calling COBOL programs.
Note: If you set AMODE to 31 and RMODE to 31, but the Assembler module contains 24-bit addresses, the Linker overrides your RMODE setting and loads the module below the line, and displays a warning message.
Parent topic: Configuring a Program's Memory Requirements


Using Subpools

You can use subpools to help manage your memory requirements in just the same way as you do on the mainframe. A subpool is a logical grouping of memory allocations that can be de-allocated with a single FREEMAIN or STORAGE RELEASE macro statement. Subpools are available for memory both above and below the line.

You create a subpool simply by including the SP parameter in a GETMAIN or STORAGE OBTAIN macro statement. Valid subpool numbers are 0 through to 127, 131 and 132. If you omit the SP parameter from your GETMAIN and STORAGE OBTAIN macro statements, all memory is allocated in subpool 0, unless you specify the NONCAN Linker directive, in which case all memory is allocated in subpool 132.

Parent topic: Configuring a Program's Memory Requirements


File Handling

This section describes the file handling facilities supplied with Assembler support.

  • Introduction to File Handling
  • Using QSAM for File Handling
  • Using BSAM for File Handling
  • Using VSAM for File Handling
Parent topic: Assembler Support


Introduction to File Handling

Assembler support provides file handling facilities for a subset of data set organizations. The following table shows the data set organizations and access methods that you can use in your Assembler programs:

Data Set Organization | Record Formats | Access Methods
PS (member of GDG) | Fixed, variable, line sequential | QSAM, BSAM
PS | Fixed, variable, line sequential | QSAM, BSAM
PSU | Fixed, variable, line sequential | QSAM, BSAM
ES (Entry sequence) | Fixed, variable | VSAM
KS (Key sequence) | Fixed, variable | VSAM
RR (Relative record) | Fixed, variable | VSAM

Assembler support includes performing all file handling by calling the COBOL file handler; this ensures 100% compatibility. Your Assembler programs can access any file created by a COBOL program, as long as its data set organization is one of those shown in the table. Equally, COBOL programs can access files created by Assembler programs.

In your Assembler program you define your files and perform input/ouput operations on them using the same macros that you use on the mainframe. We ignore some control block parameters and applies others differently, but in general the level of compatibility between control blocks on the PC and control blocks on the mainframe is very high. The input/output request macros expand differently from the mainframe. All fields in request macros that accept register notation in a mainframe environment also accept register notation in our Assembler support.

If you are working with mainframe-style files you should map PC filenames to mainframe-style names using the catalog.

You can access data files held on Fileshare servers. We recommend that you specify full Fileshare pathnames in the catalog for any files that you want to access through Fileshare. Alternatively you can specify Fileshare pathnames in your Assembler file handling macros; if you want to use this method, you need to use the Fileshare File Handler, FHREDIR, rather than the standard COBOL File Handler. To do this, set the following parameter in the Assembler support configuration file, mf370ctl.cfg, located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory:

MF370EFH=FHREDIR

Parent topic: File Handling
Related concepts
Configuring the Environment
Setting Addressing Mode and Residency Mode
Configuring a Program's Memory Requirements
Turning GTF on and Specifying Options
Configuring the Default SQA Memory Size


Using QSAM for File Handling

Our Assembler support includes QSAM-style processing of files with the data set organizations PS and PSU. You define your file with the DCB macro and process it with the OPEN, CLOSE, GET and PUT request macros. QSAM file handling is identified in the DCB by the MACRF options of G, P, or G,P for GET, PUT or GET/PUT. The two-byte COBOL ANSI 85 file status code is available after every file operation at byte 6 in the data control block (DCB).

Your files can have fixed, variable or Micro Focus line sequential record formats. The length of the last record read or written is always available in the LRECL field of the DCB.

In the case of variable-length records, each record is prefixed by a four-byte mainframe-compatible record descriptor word (RDW)

To use Micro Focus line sequential file organization, specify RECFM=T in the DCB. All records are variable length and, whether read or written, must end with ANSI carriage-return and line-feed characters (x"0D0A").

Some of the sample programs provided with our Assembler support illustrate the use of QSAM-style file handling. All of these files are located by default in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\Assembler\Classic\QSAM directory:

Program | Summary
pgasm04.mlc | Uses the input/ouput macro statements to copy a line sequential file. The input file is mf370get.dat; the new output file is mf370put.dat. The program displays the records on the screen as it copies them.
qsamex4.mlc | Reads an ANSI text file (line sequential format ) and writes the records to an EBCDIC PS file of 80-character fixed length records. This sample program is very useful for converting ASCII text files into 80-byte EBCDIC card-images to be read by other Assembler programs.
Parent topic: File Handling


Using BSAM for File Handling

Our Assembler support includes BSAM-style processing of files with the data set organizations PS and PSU. You define your file with the DCB macro and process it with the OPEN, CLOSE, READ and WRITE request macros. BSAM file handling is identified in the DCB by the MACRF options of R, W, or R,W for READ, WRITE or READ/WRITE. The two-byte COBOL ANSI 85 file status code is available after every file operation at byte 6 in the data control block (DCB).

The BSAM READ and WRITE operations act on a block of records at a time; your Assembler program is responsible for any processing required to deblock and block individual records. However, PC operating systems do not currently support blocked record files; all PC files must consist of individual logical records. There are two solutions to this incompatibility between the mainframe and PC. In both cases you need to convert the file to an unblocked format on the mainframe, using either a specially-written program or a third-party utility. The two solutions are as follows:

  • If the file is to be accessed only by an Assembler program, your conversion program should write out each block as a record. Then when the Assembler program on the PC issues a READ, although the COBOL file handler returns a single record, the Assembler program can continue to treat it as a block.
  • If the file is to be accessed by both an Assembler program and a COBOL program, your conversion program should write out each record individually. Then on the PC your COBOL program can access the file one record at a time, while the Assembler program can access it one block at a time, with each block holding one record. You can only use this approach if your Assembler program is able to handle blocks containing variable numbers of records.

Your blocked files can have fixed, variable or Micro Focus line sequential record formats. Fixed length records are held in fixed length blocks, while variable length records are held in variable length blocks. Line sequential records are held in variable length blocks, one record per block.

In the case of variable-length blocks, each block is prefixed by a four-byte mainframe-compatible block descriptor word. Each record is normally prefixed by its own record descriptor word, but processing this is the responsibility of your Assembler program.

To use Micro Focus line sequential file organization, specify RECFM=T in the DCB. The single record in each block must end with ANSI carriage-return and line-feed characters (x"0D0A").

Parent topic: File Handling


Using VSAM for File Handling

Our Assembler support includes VSAM-style processing of files with the data set organizations ES, KS and RR, providing sequential, indexed and random access. You define your file with the ACB, EXLST and RPL control block macros and process it with the OPEN, CLOSE, GET, PUT, POINT and ERASE request macros. You can also manipulate the ACB, EXLST and RPL control blocks at execution time using the SHOWCB, MODCB, TESTCB and GENCB macros. The two-byte COBOL ANSI 85 file status code is available after every file operation at byte 6 in the access method control block (ACB).

Your files can have fixed or variable record formats. The length of the last record read or written is always available in the RECLEN field of the request parameter list.

You can use one alternate index to access a VSAM KS files. You specify alternate index access with the AIX option of the MACRF parameter of the ACB macro.

We do not support the following mainframe VSAM options: reverse sequential processing, relative byte addressing, control interval access, asynchronous input/output and multiple file positions.

Some of the sample programs provided with our Assembler support illustrate the use of VSAM-style file handling. All of these files are located by default in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\Assembler\Classic\VSAM directory:

Program | Summary
vsamex1.mlc | Reads a variable-length KS file sequentially by key and displays each record on the screen.
vsamex3.mlc | Reads a variable-length KS file directly by key, adding new records and optionally updating retrieved records.
vsamex5.mlc | Reads a fixed-length RR file, erases any existing records then performs a sequence of tests to demonstrate that records can be written and read sequentially and at random.
vsamex19.mlc | Reads a variable-length KS file using an alternate index. The alternate key values are verified after each read and a success or fail message is written to the screen depending on the sequence of records returned.
Parent topic: File Handling


Using the Generalized Trace Facility

The chapter describes how you use the Generalized Trace Facility to obtain an execution trace of an Assembler program.

  • Generalized Trace Facility Introduction
  • Turning GTF on and Specifying Options
  • The Trace File
  • Types of Trace
  • Program Interruption Information
Parent topic: Assembler Support


Generalized Trace Facility Introduction

The Assembler Generalized Trace Facility (GTF) is a debugging tool designed to help speed up the process of isolating the location and cause of a problem in an Assembler program. You use the GTF tool to create a trace file showing the operations performed by the program. You do not have to compile the program for debugging. You can request different levels of detail. For example, you might run a trace requesting program level information and then run a further trace on a specific section by specifying the level of detail and the start and end points for the trace.

Parent topic: Using the Generalized Trace Facility


Turning GTF on and Specifying Options

To turn on the Generalized Trace Facility, set the environment variable GTFFILE to the absolute path and file name of the trace file. You set this environment variable in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\MF370ctl.cfg configuration file.

You can specify the following GTF options after the GTFFILE environment variable:

GTFIMIN
The instruction count at which to start the trace (default 00000000)
GTFIMAX
The instruction count at which to end the trace (default FFFFFFFF)
GTFAMIN
The instruction address at which to start the trace (default 00000000)
GTFAMAX
The instruction address at which to end the trace (default FFFFFFFF)
GTFOPT
The level of detail. You can set this environment variable to one or more of the following three-character codes separated by commas to indicate the level of detail you want: INS Trace each instruction

BAL Trace each BALR, BASR, and BASSM instruction

SVC Trace each SVC instruction

PGM Trace each LOAD, DELETE, and LINK

FOC Trace each file OPEN and CLOSE operation

FIO Trace each file input and output operation, as well as each OPEN and CLOSE

MEM Trace GETMAIN, FREEMAIN, and STORAGE

ALL All of the above trace options

REG Trace the 16 general-purpose registers at each trace event

The default value is BAL, PGM, FOC

The size of a trace file depends on the options that you specify. It can be very large. For this reason we recommend that you always begin by running a trace with the default options to find out the optimum starting point for a detailed trace. When you run a detailed trace, using options such as FIO, INS or ALL, specify the start and end points using the GTFIMIN and GTFIMAX or the GTFAMIN and GTFAMAX options.

You can also specify the REG option with any other option if you want the contents of the 16 general-purpose registers at each trace point. This increases the size of the trace file by a factor of 3 and makes it a little more difficult to read, so only use this option if you really need it. The contents of the registers are shown as they were just before the trace operation; hence the REG option is most useful with the following options:

  • INS, because this traces every instruction
  • MEM and PGM, because with these options the trace is performed at the end of the instructions affected such as LOAD and GETMAIN

Regardless of the trace options you have specified, whenever a program interruption occurs, the trace file contains extra lines for the instruction causing the interruption. These lines show the program status word (PSW), which contains the interruption code in the low-order byte of the first word, and the registers.

Parent topic: Using the Generalized Trace Facility
Related concepts
Configuring the Environment
Setting Addressing Mode and Residency Mode
Configuring a Program's Memory Requirements
Introduction to File Handling
Configuring the Default SQA Memory Size


The Trace File

You can view or print the GTF trace file using any ASCII-compatible editor or word processor. The file begins with the GTF options used to generate the file and the date and time the trace started. The last line of the file shows the date and time the trace ended. If this line is not present, the trace is probably incomplete because it was not closed properly. This can happen if you are running an interactive debugging session using the Assembler debugger with the Generalized Trace Facility turned on, and an unrecoverable error occurs. To ensure that the GTF trace file is complete, you must allow the debugging session to end without being forced: press S(tep) or G(o) to record the program exception on the trace file and then stop the debugging session.

In between the information at the beginning of the file and the last line are individual trace records. Each of these includes the following items of information:

  • Instruction count. This is a hexadecimal counter showing the total number of instructions executed up to the trace point. This count is very useful when you want to work out where to start a detailed trace at a point deep into a complex application where the same code may be executed many times before the point of failure. You use the option GTFIMIN to set the starting instruction count for a trace.
  • Instruction address. This is the linear address of the next instruction at the current trace point. This address provides an alternative way of specifying where you want a detailed trace to start. You use the option GTFAMIN to set the starting instruction address for a trace.
  • Instruction operation. This field indicates the machine instruction or run-time operation being performed at the trace point. Additional information may follow depending on the type of trace line: INS The hexadecimal machine instruction, which can be 2, 4, or 6 bytes in length
PGM
The program name and entry for LOAD, DELETE, or LINK
FOC and FIO
The DCB, ACB, or DTF control block address
MEM
Length and address of memory allocated or deallocated
Parent topic: Using the Generalized Trace Facility


Types of Trace

This section describes various types of trace you can obtain.

  • Default Trace
  • Detailed Trace
  • File Input/Output Trace
  • Memory Allocation Trace
Parent topic: Using the Generalized Trace Facility


Default Trace

Use the default trace option GTFOPT=PGM,BAL,FOC, which traces LOAD, DELETE, LINK, BALR, BASR, OPEN, and CLOSE operations, to get an overview of what an application is doing and to identify possible starting and ending points for more detailed traces if required.

Here is the trace file for a default trace of an IMS COBOL and Assembler application:

GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG
GTF option GTFOPT  =BAL,FOC,PGM
GTF option GTFIMIN =00000000
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=08495898
INS-CTR  INS-ADDR INS-OP
00000043 81000188 BALR     05EF
00000044 81005998 BALR     05F0
00000047 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00000051 810001E6 LOAD     NAME=LDDECTBL ENTRY=810059D8
000006DA 8100033A BALR     05EF
00000704 81005998 BALR     05F0
00000707 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00000762 81000E10 LOAD     NAME=CG#CTL   ENTRY=80012CF0
00000988 810059B0 BALR     05F0
0000098B 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001051 8100033A BALR     05EF
0000107B 81005998 BALR     05F0
0000107E 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
000012F7 810059B0 BALR     05F0
000012FA 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001360 8100033A BALR     05EF
0000139C 81005998 BALR     05F0
0000139F 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00001618 810059B0 BALR     05F0
0000161B 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001CDC 8100033A BALR     05EF
00001D06 81005998 BALR     05F0
00001D09 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00001F82 810059B0 BALR     05F0
00001F85 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001F92 810003EA DELETE   NAME=LDDECTBL ENTRY=00000000
00001FED 81007628 BALR     05EF
00001FEE 8100CE38 BALR     05F0
00001FF1 8100CE42 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00001FFB 81007686 LOAD     NAME=LDDECTBL ENTRY=80011228
00002684 810077DA BALR     05EF
000026AE 8100CE38 BALR     05F0
000026B1 8100CE42 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000270C 810082B0 LOAD     NAME=CG#CTL   ENTRY=8100CE78
00002932 8100CE50 BALR     05F0
00002935 8100CE5A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00002FFB 810077DA BALR     05EF
.........................................
.........................................
0000B04A 81022160 BALR     05F0
0000B04D 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000B0AA 8101CAEA BALR     05EF
0000B0EF 81022148 BALR     05F0
0000B0F2 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000B114 81022160 BALR     05F0
0000B117 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000B174 8101CAEA BALR     05EF
0000B1B0 81022148 BALR     05F0
0000B1B3 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000B4A4 81022160 BALR     05F0
0000B4A7 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000B501 8101CAEA BALR     05EF
0000B519 81022160 BALR     05F0
0000B51C 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000BBE2 8101CAEA BALR     05EF
0000BC0C 81022148 BALR     05F0
0000BC0F 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000BE8D 81022160 BALR     05F0
0000BE90 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000BEED 8101CAEA BALR     05EF
0000BF32 81022148 BALR     05F0
0000BF35 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000BF51 81022160 BALR     05F0
0000BF54 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000BFB1 8101CAEA BALR     05EF
0000BFED 81022148 BALR     05F0
0000BFF0 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000C2E1 81022160 BALR     05F0
0000C2E4 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000C33E 8101CAEA BALR     05EF
0000C356 81022160 BALR     05F0
0000C359 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000C3BF 8101CAEA BALR     05EF
0000C3FB 81022148 BALR     05F0
0000C3FE 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000C67C 81022160 BALR     05F0
0000C67F 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000CD40 8101CAEA BALR     05EF
0000CD6A 81022148 BALR     05F0
0000CD6D 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000CFEB 81022160 BALR     05F0
0000CFEE 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000CFFB 8101CB9A DELETE   NAME=LDDECTBL ENTRY=00000000
GTF trace file DATE=000114 TIME=08514748
Parent topic: Types of Trace


Detailed Trace

Use the GTFOPT=ALL option to obtain a detailed trace.

Here is a detailed trace of the last section of code starting with BALR at instruction count CFEB in the default trace example in section Default Trace. Options GTFOPT=ALL and GTFIMIN=0000CFEB were used to obtain this trace:

GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG
GTF option GTFOPT  =ALL
GTF option GTFIMIN =0000CFEB
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=09370586
INS-CTR  INS-ADDR INS-OP
0000CFEB 81022160 BALR     05F0
0000CFEC 81022162 ICM      BF08F00D
0000CFED 81022166 LA       41F0F00E
0000CFEE 8102216A SVC      0A27
0000CFEE 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000CFEF 8102216C BCR      07FE
0000CFF0 8101DBFA L        58D0D004
0000CFF1 8101DBFE L        58E0D00C
0000CFF2 8101DC02 BCR      07FE
0000CFF3 8101CAEC L        58E0B092
0000CFF4 8101CAF0 BCR      07FE
0000CFF5 8101C864 BAS      4DE0B3B4
0000CFF6 8101CB7A ST       50E0B092
0000CFF7 8101CB7E CLC      D501300AB484
0000CFF8 8101CB84 BC       4770B40C
0000CFF9 8101CB88 L        5860B446
0000CFFA 8101CB8C BAL      4500B3D2
0000CFFB 8101CB98 SVC      0A09
0000CFFB 8101CB9A DELETE   NAME=LDDECTBL ENTRY=00000000
0000CFFC 8101CB9A LTR      12FF
0000CFFD 8101CB9C BC       4770B412
0000CFFE 8101CBA0 L        5810B4B6
0000CFFF 8101CBA4 L        5890B4BE
0000D000 8101CBA8 L        5860B442
0000D001 8101CBAC LR       1809
0000D002 8101CBAE LH       48F0B3EE
0000D003 8101CBB2 BC       47000003
0000D004 8101CBB6 SVC      0A78
0000D004 8101CBB8 FREEMAIN  LOC=  00010EC8 LEN=  00000359
0000D005 8101CBB8 LTR      12FF
0000D006 8101CBBA BC       4770B412
0000D007 8101CBBE L        5810B4D6
0000D008 8101CBC2 LH       48F0B4D2
0000D009 8101CBC6 LA       4120B49A
0000D00A 8101CBCA LH       4830B482
0000D00B 8101CBCE SR       1B55
0000D00C 8101CBD0 MVCL     0E24
0000D00D 8101CBD2 L        58E0B092
0000D00E 8101CBD6 BCR      07FE
0000D00F 8101C868 L        58D0B04E
0000D010 8101C86C ST       50FD0010
0000D011 8101C870 LM       98ECD00C
0000D012 8101C874 BCR      07FE
0000D013 80000860 SVC      0A00
GTF trace file DATE=000114 TIME=09375776
Parent topic: Types of Trace


File Input/Output Trace

Use the option GTFOPT=FIO to trace all file input and output operations including OPEN, CLOSE, GET, PUT, POINT, READ, WRITE etc. Alternatively, use the option GTFOPT=FOC, which traces file open and close operations only, to identify the location within an application where an OPEN or CLOSE is failing.

Here is the GTF trace file for a file input/output trace of the Assembler demo program pgasm04.mlc:

GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG
GTF option GTFOPT  =FIO
GTF option GTFIMIN =00000000
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=09504509
INS-CTR  INS-ADDR INS-OP
0000002B 80017572 OPENL    CB=000172C0
00000070 80017572 OPENL    CB=00017320
000000A1 80017AD0 GET      CB=000172C0
000000C6 80017AD0 PUT      CB=00017320
000000F3 80017AD0 GET      CB=000172C0
00000118 80017AD0 PUT      CB=00017320
00000145 80017AD0 GET      CB=000172C0
0000016A 80017AD0 PUT      CB=00017320
00000197 80017AD0 GET      CB=000172C0
000001BC 80017AD0 PUT      CB=00017320
000001E9 80017AD0 GET      CB=000172C0
0000020E 80017AD0 PUT      CB=00017320
0000023B 80017AD0 GET      CB=000172C0
00000260 80017AD0 PUT      CB=00017320
0000028D 80017AD0 GET      CB=000172C0
000002B2 80017AD0 PUT      CB=00017320
000002DF 80017AD0 GET      CB=000172C0
00000304 80017AD0 PUT      CB=00017320
00000331 80017AD0 GET      CB=000172C0
00000356 80017AD0 PUT      CB=00017320
00000383 80017AD0 GET      CB=000172C0
000003A8 80017AD0 PUT      CB=00017320
000003D5 80017AD0 GET      CB=000172C0
000003FA 80017AD0 PUT      CB=00017320
00000427 80017AD0 GET      CB=000172C0
0000044C 80017AD0 PUT      CB=00017320
00000479 80017AD0 GET      CB=000172C0
0000049E 80017AD0 PUT      CB=00017320
000004CB 80017AD0 GET      CB=000172C0
000004F0 80017AD0 PUT      CB=00017320
0000051D 80017AD0 GET      CB=000172C0
00000542 80017AD0 PUT      CB=00017320
0000056F 80017AD0 GET      CB=000172C0
000005A2 80017E8A CLOSEL   CB=000172C0
000005DE 80017E8A CLOSEL   CB=00017320
GTF trace file DATE=000114 TIME=09504618
Parent topic: Types of Trace


Memory Allocation Trace

Use the option GTFOPT=MEM to focus on the allocation and deallocation of memory in an Assembler application. The information shown includes the address and length of memory allocated above and below the 16 megabyte line.

Here is the GTF trace file for a memory allocation trace of the Assembler demo program testvml.mlc:

GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG
GTF option GTFOPT  =INS,MEM
GTF option GTFIMIN =00000000
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=10044120
INS-CTR  INS-ADDR INS-OP
00000001 81007E78 BALR     05C0
00000002 81007E7A LR       18BE
00000003 81007E7C BAL      4510C03A
00000004 81007EB4 SVC      0A23
00000005 81007EB6 PACK     F232C158C173
00000006 81007EBC PACK     F232C15CC176
00000007 81007EC2 PACK     F272C166C179
00000008 81007EC8 CVB      4F20C166
00000009 81007ECC MH       4C20C17E
0000000A 81007ED0 MH       4C20C17E
0000000B 81007ED4 CP       F930C158C181
0000000C 81007EDA BC       4780C0CA
0000000D 81007EDE BAL      4510C08C
0000000E 81007F06 SVC      0A23
0000000F 81007F08 LR       1802
00000010 81007F0A ICM      BF08C097
00000011 81007F0E BC       47000000
00000012 81007F12 SR       1B11
00000013 81007F14 BCTR     0610
00000014 81007F16 SVC      0A0A
00000014 81007F18 GETMAIN   LOC=  00010010 LEN=  00100000
00000015 81007F18 BAL      4510C0BE
00000016 81007F38 SVC      0A23
00000017 81007F3A SP       FB30C158C180
00000018 81007F40 BC       4720C08E
00000019 81007F08 LR       1802
0000001A 81007F0A ICM      BF08C097
0000001B 81007F0E BC       47000000
0000001C 81007F12 SR       1B11
0000001D 81007F14 BCTR     0610
0000001E 81007F16 SVC      0A0A
0000001E 81007F18 GETMAIN   LOC=  00110020 LEN=  00100000
0000001F 81007F18 BAL      4510C0BE
00000020 81007F38 SVC      0A23
00000021 81007F3A SP       FB30C158C180
00000022 81007F40 BC       4720C08E
00000023 81007F44 CP       F930C15CC181
00000024 81007F4A BC       4780C136
00000025 81007F4E BAL      4510C0FC
00000026 81007F76 SVC      0A23
00000027 81007F78 LR       1802
00000028 81007F7A LH       48F0C106
00000029 81007F7E BC       47000022
0000002A 81007F82 SVC      0A78
0000002A 81007F84 GETMAIN   LOC=  01008010 LEN=  00100000
0000002B 81007F84 BAL      4510C12A
0000002C 81007FA4 SVC      0A23
0000002D 81007FA6 SP       FB30C15CC180
0000002E 81007FAC BC       4720C0FE
0000002F 81007F78 LR       1802
00000030 81007F7A LH       48F0C106
00000031 81007F7E BC       47000022
00000032 81007F82 SVC      0A78
00000032 81007F84 GETMAIN   LOC=  01108020 LEN=  00100000
00000033 81007F84 BAL      4510C12A
00000034 81007FA4 SVC      0A23
00000035 81007FA6 SP       FB30C15CC180
00000036 81007FAC BC       4720C0FE
00000037 81007FB0 BAL      4510C154
00000038 81007FCE SVC      0A23
00000039 81007FD0 BCR      07FB
0000003A 80000860 SVC      0A00
GTF trace file DATE=000114 TIME=10044864
Program Interruption Information
Here is the trace file for a program that attempts to add 1 to a packed decimal field containing spaces. The PSW contains interrupt code 7 corresponding to the MVS abend 0C7 that would occur on the mainframe.

GTF option GTFFILE =GTF.LOG
GTF option GTFOPT  =ALL
GTF option GTFIMIN =00000000
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=10565281
INS-CTR  INS-ADDR INS-OP
00000001 81007FE8 BALR     05C0
00000002 81007FEA LA       41100002
00000003 81007FEE AP       FA10C00CC00E
 R0-R7 00000000 00000002 00000000 00000000 00000000 00000000 00000000 00000000
 R9-RF 00000000 00000000 00000000 00000000 81007FEA 00002870 00000860 01007FE8
00000003 81007FF4 PGMCHK   PSW=0000000781007FF4
GTF trace file DATE=000114 TIME=10565286
Parent topic: Types of Trace


Program Interruption Information

Here is the trace file for a program that attempts to add 1 to a packed decimal field containing spaces. The PSW contains interrupt code 7 corresponding to the MVS abend 0C7 that would occur on the mainframe.

GTF option GTFFILE =GTF.LOG
GTF option GTFOPT  =ALL
GTF option GTFIMIN =00000000
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=10565281
INS-CTR  INS-ADDR INS-OP
00000001 81007FE8 BALR     05C0
00000002 81007FEA LA       41100002
00000003 81007FEE AP       FA10C00CC00E
 R0-R7 00000000 00000002 00000000 00000000 00000000 00000000 00000000 00000000
 R9-RF 00000000 00000000 00000000 00000000 81007FEA 00002870 00000860 01007FE8
00000003 81007FF4 PGMCHK   PSW=0000000781007FF4
GTF trace file DATE=000114 TIME=10565286
Parent topic: Using the Generalized Trace Facility


CICS Support

  • Mainframe-style Pointers
  • Forcing a Program to be Reloaded
  • Accessing Large VSAM Files
  • Abend Codes in CICS Transactions
  • Using the SET Option of the BMS-related SEND Functions
  • Developing Exit Programs
    This chapter explains how to write exit programs for use with MSS.
  • CICS Web Services
Parent topic: Mainframe Programming


Mainframe-style Pointers

This COBOL system enables the contents of pointer items to be stored in a format that is compatible with that used on an IBM mainframe. You can redefine both USAGE POINTER and CICS BLL cell data items as USAGE PIC S9(9) COMP and can perform full arithmetic on such items. You control the use of mainframe-style pointers with the AMODE compiler directive; there is a choice between 24-bit pointers, 31-bit pointers or NO AMODE, depending on the dialect in use; programs compiled with NO AMODE use PC-style pointers and are known as non-AMODE compiled programs.

  • AMODE and Non-AMODE Compiled Programs
Parent topic: CICS Support
Related reference
AMODE Compiler Directive


AMODE and Non-AMODE Compiled Programs

You can run transactions that use both AMODE and non-AMODE compiled programs within the same region. However, within each discrete transaction all programs must be either AMODE-compiled or non-AMODE compiled. You should be especially aware of this when using supplied system transactions such as the mirror transaction (CVMI or CPMI) for inbound system communications or facilities such as the autoinstall exits, as these are non-AMODE compiled and could cause problems if you try to execute them with AMODE-compiled programs.

If you are using distributed program linking, you can get round this problem by setting a value for communications area override. We recommend that you set communications area override at the individual program level in the PPT definition. To do this, set a value in Commarea on the CICS PPT page of ESMAC. If you are not sure what value to set it to, set it to the maximum, 32,767 bytes.

Parent topic: Mainframe-style Pointers


Forcing a Program to be Reloaded

By default, when a transaction program is canceled, it remains in memory. This behavior improves performance because the program does not need to be reloaded if it is called a subsequent time. However, it also means that you can't load a updated version of the program without closing down the enterprise server and starting it up again. If you are actively working on one or more programs that run in your enterprise server, and you want to ensure that the latest version is loaded every time, you can force programs to be reloaded each time they are called by checking Force program PHASEIN under the SIT properties . Alternatively, you can force an individual program to be reloaded by using the Phasein function of the transaction CPMT.

Parent topic: CICS Support


Accessing Large VSAM Files

You might find that VSAM files larger than 1GB (gigabyte) cannot be accessed. This is because the default record locking mechanism uses the top two bits of the file address for locking and compression bits, thus reducing the address space for the maximum offset from 4GB to 1GB for a shared idxformat 3 or 4 file. If you encounter this problem, you should change the record locking mechanism for the file. To do this:

  1. If the large VSAM files are set to OPEN (which means that the files are opened when the CICS region is started), verify that Fileshare Support on the SIT is enabled.
  2. Create a file handler configuration file that sets LOCKTYPE to 2 for the files causing the problem. With this setting, the file handling mechanism creates a separate file for storing record locks, with the same basename as the file and a .lck extension.
  3. Set the EXTFH environment variable to point to the file. The default file name is extfh.cfg.

The file handler configuration file lists defaults for all files under the tag [XFH-DEFAULT], and settings for individual files under a tag consisting of the filename. For example, the following configuration file sets BASENAME=ON (which means that you do not need to supply pathnames for files) and sets the lock type to 2 for the file myfile:

[XFH-DEFAULT]
BASENAME=ON
[MYFILE]
LOCKTYPE=2
Parent topic: CICS Support


Abend Codes in CICS Transactions

Unhandled transaction program abends are reported through the TXKC0001E system message. Generally these abends are caused by a standard CICS error condition. The abend codes (and descriptions) in these cases are the same as the abend codes issued for those conditions in the mainframe environment.

In addition to these errors, the emulator can encounter conditions that do not match a standard CICS error condition but where the transaction cannot proceed successfully and so must be abended. These abend codes are:

  • ASSA
  • EXIF
  • FUNC
  • IRST
  • LANG
  • MATP
  • MBLL
  • MCOM
  • MUSR
  • RECU
Parent topic: CICS Support
Related information
IBM CICS/ESA Messages and Codes


ASSA

Your development system issues the ASSA abend code if it encounters either of the following:

  • an invalid resource name
  • a lack of storage

when it is dynamically creating a resource entry (for example, a PPT entry).

Use the diagnostic tools and log files to determine the cause of the error.

Parent topic: Abend Codes in CICS Transactions


EXIF

Your development system issues the EXIF abend code if your program calls the CICS API with parameters that do not conform to the specifications. The most likely cause is that the transaction program was compiled from a translated source file that has been modified incorrectly.

Parent topic: Abend Codes in CICS Transactions


FUNC

The FUNC abend code is issued when an unsupported CICS API function is requested. It is caused by the execution of an EXEC CICS command that was identified by the preprocessor as unsupported and the /CICSECM(FUNCTION=ABEND) preprocessor directive (abend at execution) was specified.

Parent topic: Abend Codes in CICS Transactions


IRST

The IRST abend code is issued when the program control functions for saving and restoring Working Storage have encountered an illogical condition; generally a system error.

Parent topic: Abend Codes in CICS Transactions


LANG

The LANG abend code is issued when different dialects of COBOL are mixed in a run unit, for example, a program written in VS COBOL II calls a program written in OS/VS COBOL.

Parent topic: Abend Codes in CICS Transactions


MATP

The MATP abend code is issued when there is insufficient memory for the API Emulation server to allocate the control block needed for the target program of a LINK, XCTL, or VS COBOL II CALL.

Parent topic: Abend Codes in CICS Transactions


MBLL

The MBLL abend code is issued when there is insufficient memory for the API Emulation server to allocate the BLL Cell List area for an OS/VS COBOL transaction program.

Parent topic: Abend Codes in CICS Transactions


MCOM

The MCOM abend code is issued when there is insufficient memory for the API Emulation server to allocate a COMMAREA to be passed to a user transaction program invoked through XCTL.

Parent topic: Abend Codes in CICS Transactions


MUSR

The MUSR abend code is issued when there is insufficient memory for the API Emulation server to allocate the file or terminal buffer for data to be returned to the user transaction program.

Parent topic: Abend Codes in CICS Transactions


RECU

The RECU abend code is issued when an attempt is made to CALL (using DFHEIBLK) a user transaction program that is already active in the current CICS LINK level.

Parent topic: Abend Codes in CICS Transactions


Using the SET Option of the BMS-related SEND Functions

To be able to support the SET option of the BMS-related SEND functions, your development system returns a fake TIOA address in the low-order three bytes of each entry in the Page List. To make use of a fake TIOA address, you need to convert it to a real (usable) TIOA address using DFHMFSET.

You need to modify every program that uses the SET option of the following BMS functions:

  • SEND CONTROL
  • SEND MAP
  • SEND PAGE
  • SEND TEXT

You also need to modify every program that uses the addresses in the resulting Page List.

  • Converting a Fake TIOA Address to a Real TIOA Address
  • Restrictions on Using DFHMFSET
  • Examples
Parent topic: CICS Support


Converting a Fake TIOA Address to a Real TIOA Address

Enter the following on the command line:

call "DFHMFSET" using page-list-entry
                      address-field

where:

  • page-list-entry is a four byte area, containing the value of one entry from the Page List (returned in the area addressed by the address returned for the SET option on a BMS SEND command). It might be the actual entry or some other area. Its value must be one of the current valid values in the list. The end of the list is marked by a mainframe NULL pointer data item (x'FF000000').
  • address-field is a four byte area.
    • For OS/VS COBOL it should be defined and used as a BLL Cell value, that is S9(8) COMP.
    • For VS COBOL II it should be defined and used as a POINTER data item.
Note: The end of the list is always signalled by an entry with high-values in the high-order byte and low-values in the low-order three bytes. On the mainframe, this corresponds to the defined value used for NULL pointer data items, but not to a NULL pointer value in the Micro Focus COBOL environment. The test for the end of the list should always be done by explicitly testing for high-values in the high-order byte of an entry.
Parent topic: Using the SET Option of the BMS-related SEND Functions


Restrictions on Using DFHMFSET

The following restrictions on using DFHMFSET apply:

  • The DFHMFSET entry point should only be called in programs preprocessed by the CICS preprocessor.
  • The conversion of any fake TIOA addresses in the Page List must be done before the Page List is reused. Subsequent BMS SEND commands specifying the SET option will only reuse the Page List if the first "logical message" has been completed (by SEND PAGE, PURGE MESSAGE, or SYNCPOINT).
  • In OS/VS COBOL only, a SERVICE RELOAD must be done for the associated 01-level if the actual BLL cell is used as the second parameter on the call to DFHMFSET. This is necessary to let the compiler know that it must re-establish the base address for that 01-level using the (possibly) changed value in the BLL cell.
  • The Page List returned cannot exceed 127 entries (plus one for the "end-of-list" entry).
Parent topic: Using the SET Option of the BMS-related SEND Functions


Examples

The OS/VS COBOL and VS COBOL II examples each provide the same function. They show a simple case of the use of the DFHMFSET entry point with the Page List that is returned for the SET option on BMS SEND commands.

They each do a SEND MAP command using the SET option that returns the address of a Page List containing the address of the datastream in the first entry. Note that the second entry of the Page List contains the end-of-list marker. The examples convert the Page List entry to a "real" TIOA address for the built datastream, establish the addressability for the datastream, and actually send it to the terminal using a SEND TEXT MAPPED command.

Note that the PIC X(9999) for PAGE-DSC-AREA and the value of 5 in the OCCURS clause for PAGE-LIST-ENTRY are not in themselves significant; they are just the values used in this example.

  • OS/VS COBOL Example
  • VS COBOL II Example
Parent topic: Using the SET Option of the BMS-related SEND Functions


OS/VS COBOL Example

WORKING-STORAGE SECTION.
        .
        .
     05  PAGE-LIST-ADDRESS       PIC S9(8)   COMP.
     05  PAGE-DATA-ADDRESS       PIC S9(8)   COMP.
        .
        .
 LINKAGE SECTION.
        .
        .
 01  BLL-CELL-LIST.
     05  FILLER                  PIC S9(8)   COMP.
     05  PAGE-LIST-BLL-CELL      PIC S9(8)   COMP.
     05  PAGE-DATA-BLL-CELL      PIC S9(8)   COMP.
*
 01  PAGE-LIST.
     05  PAGE-LIST-ENTRY              OCCURS 5 TIMES.
         10  PAGE-TERMINAL-TYPE  PIC X.
         10  PAGE-DSC-ADDRESS    PIC XXX.
 01  PAGE-DATA-AREA.
     05  PAGE-TIOA-PREFIX.
         10  FILLER              PIC X(8).
         10  PAGE-LENGTH         PIC 9(4)    COMP.
         10  FILLER              PIC X(2).
     05  PAGE-DSC-AREA           PIC X(9999).
        .
        .
 PROCEDURE DIVISION.
        .
     EXEC CICS SEND    MAP    ('MAPNAME')
                       MAPSET ('MSETNAM')
                       SET    (PAGE-LIST-BLL)
     END-EXEC.
        .
        .
     CALL 'DFHMFSET' USING PAGE-LIST-ENTRY (1)
                           PAGE-DATA-ADDRESS.
     MOVE PAGE-DATA-ADDRESS TO PAGE-DATA-BLL-CELL.
        .
        .
     EXEC CICS SEND TEXT MAPPED
                       FROM    (PAGE-DSC-AREA)
                       LENGTH  (PAGE-LENGTH)
     END-EXEC.
        .
Parent topic: Examples


VS COBOL II Example

        .
        .
 WORKING-STORAGE SECTION.
        .
        .
     05  PAGE-LIST-ADDR          POINTER.
     05  PAGE-DATA-POINTER       POINTER.
        .
        .
 LINKAGE SECTION.
        .
        .
 01  PAGE-LIST.
     05  PAGE-LIST-ENTRY              OCCURS 5 TIMES.
         10  PAGE-TERMINAL-TYPE  PIC X.
         10  PAGE-DSC-ADDRESS    PIC XXX.
 01  PAGE-DATA-AREA.
     05  PAGE-TIOA-PREFIX.
         10  FILLER              PIC X(8).
         10  PAGE-LENGTH         PIC 9(4)    COMP.
         10  FILLER              PIC X(2).
     05  PAGE-DSC-AREA           PIC X(9999).
        .
        .
 PROCEDURE DIVISION.
        .
        .
     EXEC CICS SEND    MAP     ('MAPNAME')
                       MAPSET  ('MSETNAM')
                       SET     (PAGE-LIST-ADDR)
     END-EXEC.
        .
        .
     CALL 'DFHMFSET' USING PAGE-LIST-ENTRY (1)
                           PAGE-DATA-POINTER.
     SET ADDRESS OF PAGE-DATA-AREA TO PAGE-DATA-POINTER.
        .
        .
     EXEC CICS SEND TEXT MAPPED
                       FROM    (PAGE-DSC-AREA)
                       LENGTH  (PAGE-LENGTH)
     END-EXEC.
        .
Parent topic: Examples


Developing Exit Programs

  • Introduction to Developing Exit Points
  • Global and Task-related Exit Programs
  • Security Exit Programs
Parent topic: CICS Support


Introduction to Developing Exit Points

A user exit is a point in MSS itself at which control can be transferred to a user-written program and at which MSS can resume control after it has finished. The following types of user exit program are supported:

  • Global exit programs. A global user exit is a point in the code that is unrelated to any particular CICS task; for example before control is transferred to an application program. The following types of global user exits are supported:
    • XZCATT
    • XZCIN
    • XZCOUT
    • XEIIN
    • XEIOUT
    • XWBOPEN
    • XWBSNDO
    • XWBAUTH
  • Task-related exit programs. A task-related user exit is a point in the code that handles task-related functions such as rollbacks and commits.
  • Security exit programs. A security exit program is an exit program written to emulate the behavior of the QUERY SECURITY CICS command.

You must write separate global and task-related user exits. You must write all user exit programs in non-mainframe COBOL. They must not use EXEC CICS commands, and they must use native addressing for pointers.

Note: All COBOL CICS programs that call user exits must be compiled with the NOAMODE compiler directive.
Parent topic: Developing Exit Programs
Related concepts
CICS Web Interface Support
Global and Task-related Exit Programs


Global and Task-related Exit Programs

You must enable each user exit that an application program needs before it is called, and you can disable it when the application program has finished with it, though you do not have to; user exits are always disabled by default when CICS starts up. You use the CICS command ENABLE PROGRAM to enable a user exit program, and the CICS command DISABLE PROGRAM to disable a user exit program. If you try to enable an invalid exit an EIBRCODE of X'804000' is returned. If you try to enable an exit that is valid but not implemented, an EIBRCODE of X'804010' is returned. The EXTRACT EXIT command is also provided; you use this to gain access to the work area of a user exit program. For details of the level of support provided for these commands see the topic System Programmers Commands.

You must define each user exit program as a program (in the PLT) and the definition must be available on the running system.

For information about global user exits and task-related user exits see the IBM manual CICS/ESA 3.3 Customization Guide. This manual contains a list of valid user exit points.

You need to include the following two copybooks in your user exit program, whether it is for a global user exit or a task-related user exit:

  • dfhcbuxi.cpy:
            78 78-uxi-TRUE                          value  1.
        78 78-uxi-XZCATT                        value  2.
        78 78-uxi-XZCIN                         value  3.
        78 78-uxi-XZCOUT                        value  4.
        78 78-uxi-XEIIN                         value  5.
        78 78-uxi-XEIOUT                        value  6.
        78 78-uxi-XFCFSHRO                      value  7.
        78 78-uxi-XWBOPEN                       value  8.
        78 78-uxi-XWBSNDO                       value  9.
        78 78-uxi-XWBAUTH                       value  10.
610668  78 78-uxi-XFAINTU                       value  11.

       78  78-exi-rc-UERCBYP                    value 4.

      ***--------------------------------------------------------------*
      *** Base parameters                                              *
      ***--------------------------------------------------------------*

        01 uxi-user-exit-interface.
           02 uxi-operational-flags-ptr         pointer.
           02 uxi-scheduling-flags-ptr          pointer.
           02 uxi-global-area-ptr               pointer.
           02 uxi-global-area-length            pic x(4) comp-5.
           02 uxi-local-area-ptr                pointer.
           02 uxi-local-area-length             pic x(4) comp-5.
           02 uxi-dfheiblk-ptr                  pointer.
           02 uxi-unit-of-recovery-ptr          pointer.

      ***--------------------------------------------------------------*
      ***  Exit specific parameters                                    *
      ***--------------------------------------------------------------*

           02 uxi-exit-specific-ptrs.         *> XZCAT In/Ot XEin/ot FSHRO  XWB????
            03 uxi-resource-ptr      pointer. *> TCTTE TCTTE Arg lst Buffer
            03 uxi-resource-data-ptr pointer. *> TIOA  TIOA  UserID  UserID
            03 uxi-res-data-len-ptr  pointer. *>  *     *
            03 uxi-aux-1-ptr         pointer. *> 62TPN       program F-Name ParmList
            03 uxi-aux-1-length-ptr  pointer. *>  *                  *
            03 uxi-aux-2-ptr         pointer. *> Tran        Sys EIB Keys
            03 uxi-aux-2-length-ptr  pointer. *>
            03 uxi-aux-3-ptr         pointer. *> TEUA  TEUA
            03 uxi-aux-3-length-ptr  pointer. *>  *     *
            03 uxi-aux-4-ptr         pointer. *> ComA  ComA
            03 uxi-aux-4-length-ptr  pointer. *>  *     *
            03                       pointer. *>
610668     02  redefines uxi-exit-specific-ptrs.   *> XFAINTU
610668         03  uxi-xfaintu-uepfareq-ptr        *> UEPFAREQ
610668                                 pointer.
610668         03  uxi-xfaintu-uepfatut-ptr        *> UEPFATUT
610668                                 pointer.
610668         03  uxi-xfaintu-uepfanam-ptr        *> UEPFANAM
610668                                 pointer.
610668         03  uxi-xfaintu-uepfatyp-ptr        *> UEPFATYP
610668                                 pointer.
610668         03  uxi-xfaintu-uepfauaa-ptr        *> UEPFAUAA
610668                                 pointer.
610668         03  uxi-xfaintu-uepfaual-ptr        *> UEPFAUAL
610668                                 pointer.
610668         03  uxi-xfaintu-uepfatk-ptr         *> UEPFATK
610668                                 pointer.
610668         03  uxi-xfaintu-uepfamch-ptr        *> UEPFAMCH
610668                                 pointer.
610668         03  uxi-xfaintu-uepfareg-ptr        *> UEPFAREG
610668                                 pointer.
sc-f74         03                      pointer.
sc-f74         03                      pointer.
sc-f74         03                      pointer.
      ***--------------------------------------------------------------*
      ***  System parameters                                           *
      ***--------------------------------------------------------------*

           02 uxi-PCA-ptr                       pointer.
           02 uxi-CSA-ptr                       pointer.
           02 uxi-DCA-ptr                       pointer.
           02 uxi-local-trace-table-ptr         pointer.
      *----------------------------------------------------------------*
      * dfhcbuxi.cpy end
      *----------------------------------------------------------------*
  • dfhcbuxc.cpy:
            01 lk-uxc-operation.
           03 lk-uxc-exit-id                   pic x comp-x.
              88 lk-uxc-TRUE-88                value 78-uxi-TRUE.
              88 lk-uxc-XZCATT-88              value 78-uxi-XZCATT.
              88 lk-uxc-XZCIN-88               value 78-uxi-XZCIN.
              88 lk-uxc-XZCOUT-88              value 78-uxi-XZCOUT.
              88 lk-uxc-XEIIN-88               value 78-uxi-XEIIN.
              88 lk-uxc-XEIOUT-88              value 78-uxi-XEIOUT.
              88 lk-uxc-XFCFSHRO-88            value 78-uxi-XFCFSHRO.
           03 lk-uxc-schedule                  pic x.
              88 lk-uxc-generic-88             value x'80'.
              88 lk-uxc-TRUE-on-start-88       value x'80'.
              88 lk-uxc-TRUE-on-sync-88        value x'40'.
              88 lk-uxc-TRUE-on-prep-88        value x'20'.
              88 lk-uxc-TRUE-on-tr-wrap-88     value x'01'.
           03 lk-uxc-modifier                  pic x    comp-x.
              88 lk-uxc-user-syncpoint-88      value 0.
              88 lk-uxc-task-syncpoint-88      value 1.
              88 lk-uxc-task-start-88          value 2.
Y97157        88 lk-uxc-re-initialization-88   value 253.
              88 lk-uxc-initialization-88      value 254.
Y97157        88 lk-uxc-initialization-88m     value 253 254.
              88 lk-uxc-shutdown-88            value 255.
           03 lk-uxc-action                    pic x    comp-x.
              88 lk-uxc-syncpoint-commit-88    value 0.
              88 lk-uxc-syncpoint-rollback-88  value 1.
              88 lk-uxc-syncpoint-prepare-88   value 2.
           03 lk-uxc-return-code               pic x(4) comp-5.
a82573        88 ws-uex-max-rc-uercbyp-88         value 4.
        01 lk-uxc-schedule-parm.
           03 lk-uxc-schedule-byte             pic x.
           03 lk-uxc-schedule-byte-bin redefines lk-uxc-schedule-byte
                                               pic x comp-x.
           78 78-lk-uxc-TRUE-on-start          value h'80'.
           78 78-lk-uxc-TRUE-on-sync           value h'40'.
           78 78-lk-uxc-TRUE-on-prep           value h'20'.
           78 78-lk-uxc-TRUE-on-tr-wrap        value h'01'.
      *----------------------------------------------------------------*
      * dfhcbuxc.cpy end
      *----------------------------------------------------------------*
Note:
  • The user exit parameters are passed to your exit program in structure uxi-user-exit-interface, defined in the copybook dfhcbuxi.cpy. Two fields in this structure, uxi-operational-flags-ptr and uxi-scheduling-flags-ptr, point respectively to two further structures, lk-uxc-operation and lk-uxz-schedule-param, in the other copybook, dfhcbuxc.cpy.
  • A CICS application can call a task-related user exit directly, for example, to obtain the address of the task area. Normally, the CICS application would call a task-related user exit program with the DFHRMCAL macro. As this macro is not supported, the application must call the user exit program directly, and must include the copy books dfhcbuxi.cpy and dfhcbuxc.cpy. If a user exit program can be called by an application program, you need to use a mechanism by which the exit program can decide whether it was called by an application program or by MSS. The sample exit program included below shows one approach: the application sets an unused bit in lk-uxc-schedule, which the user exit program tests for.

Here is a skeleton example of a task-related user exit program:

       id division.
       program-id. SAMPTRUE.
       environment division.
       configuration section.
       input-output section.
       data division.
       file section.
       working-storage section.
       linkage section .
       copy 'dfhcbuxi.cpy'.
       copy 'dfhcbuxc.cpy'.
       01 lk-global-area.
           03 lk-ga-byte pic x occurs 0 to 32767
               depending on uxi-global-area-length.
       01 lk-local-area.
           03 lk-la-byte pic x occurs 0 to 32767
               depending on uxi-local-area-length.

       procedure division using
                           uxi-user-exit-interface.
       module-entry-point.
           move 0                      to return-code
           set address of lk-uxc-operation
               to uxi-operational-flags-ptr
           set address of lk-uxc-schedule-parm
               to uxi-scheduling-flags-ptr
           move 0                      to lk-uxc-return-code
           *> -- Are we being called by an application?
           *> -- (User application sets unused value in lk-uxc-schedule.)
           if lk-uxc-schedule = x'00'
               perform called-by-application
               goback
           end-if
           evaluate true
           when lk-uxc-initialization-88
               perform initialization
           when lk-uxc-shutdown-88
               goback
           when lk-uxc-task-start-88
               perform task-start-process
           when lk-uxc-task-syncpoint-88
               evaluate true
               when lk-uxc-syncpoint-prepare-88
                   perform syncpoint-prepare
               when lk-uxc-syncpoint-commit-88
                   perform syncpoint-commit
               when lk-uxc-syncpoint-rollback-88
                   perform syncpoint-rollback
               end-evaluate
           when lk-uxc-user-syncpoint-88
               set address of lk-global-area
                   to uxi-global-area-ptr
               set address of lk-local-area
                   to uxi-local-area-ptr
               evaluate true
               when lk-uxc-syncpoint-prepare-88
                   continue
               when lk-uxc-syncpoint-commit-88
                   perform syncpoint-commit
               when lk-uxc-syncpoint-rollback-88
                   perform syncpoint-rollback
               end-evaluate
           end-evaluate
           goback
           .
       called-by-application section.
           *> -- Add any code here that you wish to execute when
           *> -- called by an application program.
           exit
           .
       initialization section.
      $if 78-break-on-error defined
           call 'CBL_DEBUGBREAK'
      $end
           perform set-schedule-bits
           exit
           .
       task-start-process section.
           *> -- Insert code here that you wish to perform at
           *> -- start of task.
           perform set-schedule-bits
           exit
           .
       end-task-process section.
           *> -- Insert code here that you wish to perform at
           *> -- end of task.
           exit
           .
       syncpoint-prepare section.
           *> -- Insert code here that you wish to perform at
           *> -- syncpoint prepare.
           exit
           .
       syncpoint-commit section.
           *> -- Insert code here that you wish to perform at
           *> -- syncpoint commit.
           exit
           .
       syncpoint-rollback section.
           *> -- Insert code here that you wish to perform at
           *> -- syncpoint rollback.
           exit
           .
       set-schedule-bits section.
           initialize lk-uxc-schedule-byte
           *> -- Register start of task interest
           compute lk-uxc-schedule-byte-bin =
               lk-uxc-schedule-byte-bin B-OR 78-lk-uxc-TRUE-on-start
           *> -- Register syncpoint interest
           compute lk-uxc-schedule-byte-bin =
               lk-uxc-schedule-byte-bin B-OR 78-lk-uxc-TRUE-on-sync
           *> -- Register prepare interest
           compute lk-uxc-schedule-byte-bin =
               lk-uxc-schedule-byte-bin B-OR 78-lk-uxc-TRUE-on-prep
           exit
           .
Parent topic: Developing Exit Programs
Related concepts
CICS Web Interface Support
Introduction to Developing Exit Points
Related information
CICS/ESA 3.3 Customization Guide


Security Exit Programs

MSS emulates the behavior of the QUERY SECURITY CICS command by calling a user exit program. On the mainframe the QUERY SECURITY command interrogates an external security manager (ESM) such as IBM's RACF and returns information to the application about the level of access that a particular end-user is allowed to have to a particular resource. The user exit program must return the same information.

A default user exit program is supplied, and as supplied, this program returns NOT for all types of access. In other words, if your CICS application issues the QUERY SECURITY command, the result is always that access is denied. If you want any other behavior, you must alter the supplied exit program.

  • Interface
  • Error Conditions
Parent topic: Developing Exit Programs


Interface

The user exit program must be called dfhuesm. We provide a sample program and a copy book that defines the parameters passed between MSS and the exit program. We also provide a compiled dynamic link library (.dll) for Windows systems, and a shared object (.so) file for UNIX systems for both 32- and 64-bit platforms. These files are located in:

File | Location
dfhuesm.cbl | %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits (Windows) or $COBDIR$COBDIR\cpylib (UNIX)
dfhcbesm.cpy | %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX)
dfhuesm.dll (Windows) | %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64
dfhuesm.so (UNIX) | $COBDIR/lib
dfhuesm64.so (UNIX) | $COBDIR/lib

When the QUERY SECURITY command is issued, the input parameters are set using the information supplied by your application. The parameters are as follows:

Field | Value
esm-version-no | Indicates the version of the parameter blocks. Micro Focus will increment this value if it issues an updated interface.
esm-user-id | The ID for the current user. If the user has not signed on, this field contains binary zeroes.
esm-opid | The operator ID associated with the user as defined in the sign-on table. If the user has not signed on, this field contains binary zeroes.
esm-opclass | The operator class associated with the user. This field contains character zeroes, unless the user has not signed on, in which case it contains binary zeroes.
esm-arg-01-flag | Unused.
esm-arg-02-flag | A value of 1 indicates that the application has used the RESTYPE keyword; the field esm-restype contains a valid resource type.
esm-arg-03-flag | A value of 1 indicates that the application has used the RESID keyword. This is mandatory, so this field is always set to 1. See the field esm-resid.
esm-arg-04-flag | A value of 1 indicates that the application has used the RESIDLENGTH keyword. See the field esm-residlength.
esm-arg-05-flag | A value of 1 indicates that the application has used the READ keyword. See the field esm-read.
esm-arg-06-flag | A value of 1 indicates that the application has used the UPDATE keyword. See the field esm-update.
esm-arg-07-flag | A value of 1 indicates that the application has used the RESCLASS keyword; the field esm-resclass contains a resource class.
esm-arg-08-flag | A value of 1 indicates that the application has used the ALTER keyword. See the field esm-alter.
esm-arg-09-flag | A value of 1 indicates that the application has used the CONTROL keyword. See the field esm-control.
esm-arg-10-flag | A value of 1 indicates that the application has used the LOGMESSAGE or the LOG keyword. See the field esm-logmessage.
esm-arg-11-flag | Unused.
esm-arg-12-flag | Unused.
esm-arg-13-flag | Unused.
esm-arg-14-flag | Unused.
esm-arg-15-flag | Unused.
esm-arg-16-flag | Unused.
esm-restype If specified, this field contains one of the following values:
  • DB2ENTRY
  • FILE
  • JOURNALNAME
  • JOURNALNUM
  • PROGRAM
  • PSB
  • SPCOMMAND
  • TDQUEUE
  • TRANSACTION
  • TRANSATTACH
  • TSQUEUE
esm-resclass | If specified, this field contains the name of a resource class.
esm-residlength | If specified, this field contains the number of significant characters in the field esm-resid.
esm-resid | This field contains the ID of a resource, the user's access to which the application needs to query. It may either be a CICS resource ID of up to 12 characters or a user-defined resource ID of up to 240 characters.
esm-logmessage | If specified, this field notifies the user exit program as to whether security violations are to be logged or not. On the mainframe, this field is used to tell CICS to log security violations. It is provided for compatibility with the mainframe; however, security violations are not logged.

The user exit program sets the output parameters, which are as follows:

Field | Value
esm-eibresp | This field contains either zero to indicate that the QUERY SECURITY call is valid, or a non-zero value to indicate otherwise. This value is returned to the application program in the EIBRESP field. It is the responsibility of the user exit program to ensure that a correct value is placed here. It should be necessary to return only the NOTFND or QIDERR condition, but you are not restricted in doing so.
esm-eibresp2 | If your exit program returns a non-zero value in the field esm-eibresp, it must return a non-zero value in this field. The only values that your exit program needs to return are 1, 3, 5 or 8 for the NOTFND condition, or 1 for the QIDERR condition. This value is returned to the application in the EIBRESP2 field.
esm-eibrcode | If your exit returns a non-zero value in the field esm-eibresp, then it must place a hexadecimal value in this field. This value is returned to the application program in the EIBRCODE field.
esm-alter | If the application has requested the ALTER status for the named resource (field esm-arg-08-flag set), then the exit program must return a CVDA value of either ALTERABLE or NOTALTERABLE in this field.
esm-control | If the application has requested the CONTROL status for the named resource (field esm-arg-09-flag set), then the exit program must return a CVDA value of either CTRLABLE or NOTCTRLABLE in this field.
esm-read | If the application has requested the READ status for the named resource (field esm-arg-05-flag set), then the exit program must return a CVDA value of either READABLE or NOTREADABLE in this field.
esm-update | If the application has requested the UPDATE status for the named resource (field esm-arg-06-flag set), then the exit program must return a CVDA value of either UPDATABLE or NOTUPDATABLE in this field.
Note: All character fields in the input parameter block are encoded in ANSI, even though they may have originated from an EBCDIC program. If you need the data in EBCDIC, then you will have to convert the data.
Parent topic: Security Exit Programs
Related information
National Locale Support
Internationalization Support


Error Conditions

When a QUERY SECURITY command is encountered the command is validated and may return one of a number of error conditions. If the command passes validation, the input fields are set up and control is passed to the user exit program. The user exit program may then itself perform some validation and reject the requests.

The following table shows the error conditions that can be returned:

Error Condition (EIBRESP field) | Further information (EIBRESP2 field)
INVREQ | 7 | LOGMESSAGE does not contain either LOG or NOLOG
 | 9 | RESID is invalid or filled with blanks
 | 10 | The external security manager (ESM) is inactive or not present. This means that the user exit program is missing.
LENGERR | 6 | The RESIDLENGTH value is not valid, that is, it is not in the range 1 through 246
NOTFND | 2 | The RESTYPE value is not valid

The following table shows the error conditions that you are most likely to need to check for in your exit program.

Error Condition (EIBRESP field) | Further information (EIBRESP2 field)
NOTFND | 1 | The RESID value is not valid
 | 3 | The RESID value for RESTYPE (SPCOMMAND) not valid.
 | 5 | The RESCLASS is not defined to the external security manager (ESM).
 | 8 | The resource is not protected. This is only returned when QUERY SECURITY is used with the RESCLASS option (and never occurs with RESTYPE).
QIDERR | 1 | An indirect queue name associated with the given RESID is not found

If any of these error codes are returned to an application program that does not provide error handling, the application abends.

Parent topic: Security Exit Programs


CICS Web Services

Enterprise Developer COBOL CICS Web Services (CWS) support enables you to create CICS COMMAREA- and Channel-based Web services, and generate CWS client applications.

Under Enterprise Server, a COBOL CICS application can act as a service requester and/or a service provider. CICS under Enterprise Server supports:

  • HTTP and Websphere MQ as transport protocols
  • SOAP 1.1, 1.2, and JSON messages

Enterprise Developer provides support for developing requester and provider COBOL CICS applications. The following command utilities are provided to generate various Web service binding files (WSBIND) for WSDL and JSON, and also optionally for JSON when using "linkable interface" mode, JSON binding files (JSBIND) generated inside a bundle directory. Binding files map between WSDL or JSON schema and COBOL programming language data structures, and are required at runtime:

ws2ls
WSDL to language structure
ls2ws
Language structure to WSDL
js2ls
JSON schema to language structure WSBIND file, or
ls2js
Language structure to JSON schema

For more information on each of these commands, see the appropriate reference topic listed below.

You can run any of these utilities from your Enterprise Developer project using the CICS Web Services wizard, or from an Enterprise Developer command prompt.

Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.
  • Demonstration Applications
    A list of available demonstration applications provided to illustrate programming techniques and runtime behavior for CICS Web services, along with a description of each of these applications.
  • Configuration Requirements for CICS Web Services
    Describes required third-party software and its configuration, Eclipse project configuration, and enterprise server region configuration requirements for successful creation and execution of CICS Web services.
  • CCSID Conversion Tables
    Describes the requirements for installing CCSID conversion tables, updating an enterprise server region that uses them, and facilitating conversion from EBCDIC to ASCII. Also explains support for double-byte character sets (DBCS).
  • CICS Web Service Types and Methods
    Describes the types of CICS Web services supported by Enterprise Developer and the methods you can use to generate them.
  • CWS Security
    Describes security options available for CICS Web services.
  • New CICS Web Service Wizard
    Describes the New CICS Web Service Wizard feature available in Enterprise Developer to generate CICS Web services.
  • Troubleshooting
    Provides a checklist to assist in troubleshooting problems encountered when running a CICS Web service.
  • How to
  • Reference
Parent topic: CICS Support
Related tasks
To start an Enterprise Developer command prompt
Related reference
ls2ws command
ws2ls command
ls2js command
js2ls command


Demonstration Applications

Enterprise Developer provides a number of demonstration applications for CICS Web services. On Windows platforms, you can access these via the Mainframe Samples Browser. For instructions on how to start the Mainframe Samples Browser, see To start the Samples Browser. Source files for these demonstration applications are located under the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Eclipse\Mainframe\CICS\Classic\CWS (Windows) or $COBDIR/demo/cics/cws (UNIX) directory.

Windows

The Mainframe Samples that are shipped with the product include several detailed walkthroughs from development through Enterprise Server configuration and deployment, to execution of CICS Web Services.

Samples for Provider (developing bottom-up and top-down) and Requester mode (top-down) are supplied for both SOAP and JSON.

UNIX

Demonstrations that are shipped with the product include several detailed walkthroughs from development through Enterprise Server configuration and deployment, to execution of CICS Web Services.

Samples for Provider (developing bottom-up and top-down) and Requester mode (top-down) are supplied for both SOAP and JSON.

Parent topic: CICS Web Services


Configuration Requirements for CICS Web Services

To successfully create and execute a CICS Web service using Enterprise Developer and Enterprise Server, ensure that you have:

  • Installed the IBM-37, IBM-437, and 002501B5 CCSID tables
  • Created and configured an Enterprise Developer project to support CICS Web services
  • Created and configured an enterprise server region on which to run the Web service

CCSID Tables

The CICS Web services feature requires that you install the appropriate IBM CCSID tables, and then configure your enterprise server region to reference them. For instructions, see To install CCSID tables.

Enterprise Developer Projects for CWS

Use these guidelines to create and configure an Enterprise Developer project for CWS:

  • Create the project using the Mainframe Subsystem Application template.
  • Set the following project properties on the COBOL tab:
    • COBOL dialect: Micro Focus
    • Character set: ASCII
    • Mainframe group: Check EXEC CICS
Note: This topic addresses settings specific to CICS Web services development for execution on an enterprise server region. The development environment for CICS Web services running on alternative runtime platforms might require alternative settings.

Enterprise Server Regions for CWS

Use these guidelines to create and configure an enterprise server region on which to run a CICS Web service:

  • Create the enterprise server region using the provided CICSTemplate.xml template.
  • In Enterprise Server Monitor and Control (ESMAC), add the following provided resources to your startup list, which is DEMOSTRT by default:
    • DFHWEB
    • DFHPIPE
  • Update the System Initialization Table (SIT), which is DEMOSIT by default, to specify a CCSID code set identifier of 37 in the Local CCSID field. For details, see To specify a CCSID table in the CICS SIT.
  • If your CICS application running on Enterprise Server uses the ASCII character set, you must configure your region to convert from EBCDIC to ASCII. For details, see To convert an EBCDIC CCSID to ASCII.
Parent topic: CICS Web Services
Related tasks
To create a CICS Web Service provider using the bottom-up method, WSDL
To create CICS Web service requester from WSDL using the top-down method
To create a CICS Web service requester and provider from WSDL using the top-down method
To create a CICS Web Service provider from WSDL using the top-down method
To create a CICS Web Service provider using the bottom-up method, JSON
To create a CICS Web Service provider from JSON using the top-down method
To create a CICS Web Service requester using the bottom-up method, JSON
To create CICS Web service requester from JSON using the top-down method
Related reference
New CICS Web Service Wizard Start page
New CICS Web Service (Bottom Up) pages 1 and 2
New CICS Web Service Requester page
New CICS Web Service Requester and Provider page
CICS Web Service Provider (Bottom-Up, Request-Response)
CICS Web Service Provider (Top-Down, Request-Response)
CICS Web Service Requestor (Bottom-Up, Linkable Interface)
CICS Web Service Requestor (Top-Down, Linkable Interface)


CCSID Conversion Tables

To use the CICS Web Services (CWS) feature requires the following:

  • Installing the IBM-37, IBM-437, and 002501B5 CCSID conversion tables
  • Updating the SIT to identify the conversion table to use
  • Creating and installing a replacement program file to facilitate conversion from EBCDIC to ASCII

Acquiring the IBM CCSID Conversion Tables

The IBM CCSID conversion tables are available from cdctables.zip, and must be installed to Enterprise Developer before you can use them. The cdctables.zip file contains a set of .zip files - intro.zip and several Packagen.zip files. Intro.zip contains three .txt files that provide details about the conversion tables.

readme.txt
Detailed information on the tables themselves, including the various types of tables, how they are created, how to use them, and conventions and terminology.
tabindex.txt
An exhaustive list of each table including a description, filename, and package specification for each.
HINTS.TXT
Hints to help you locate the tables you need.

See To install CCSID tables for detailed installation instructions.

Updating the SIT

Once you have installed the required CCSID tables, you must provide the EBCDIC local CCSID to the CICS SIT associated with your enterprise server region.

See To specify a CCSID table in the CICS SIT for details.

Note: If you create your enterprise server region from Enterprise Developer using the CICSWebServices.xml template, the default EBCDIC local CCSID is set by default.

Converting from EBCDIC to ASCII

If your CICS application running on Enterprise Server is in ASCII, you must provide a replacement MFCCSIDMAP module that identifies the ASCII CCSID that corresponds to the EBCDIC local CCSID specified in the SIT. At startup, your enterprise server region calls MFCCSIDMAP to identify the ASCII CCSID. A return code of zero (0) indicates that the call is successful.

See To specify the corresponding ASCII CCSID for an EBCDIC CCSID for details.

Using IANA Registered Names

If you want to specify a CCSID using an Internet Assigned Numbers Authority (IANA) registered name, use the CICS GET CONTAINER and PUT CONTAINER statements.

Important: Only a subset of IBM CCSIDs have an IANA-equivalent registered name. See character-sets.xml and Mappings of CCSIDs to encoding names for serialized XML output data for details.
Parent topic: CICS Web Services
Related concepts
Additional Software Requirements on Windows
Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components
Troubleshooting
Configuration Requirements for CICS Web Services
Related tasks
To create a CICS Web Service provider using the bottom-up method, WSDL
To create a CICS Web Service provider from WSDL using the top-down method
To create CICS Web service requester from WSDL using the top-down method
To create a CICS Web service requester and provider from WSDL using the top-down method
To set preferences for CICS Web Services
To create a CICS Web Service provider using the bottom-up method, JSON
To create a CICS Web Service provider from JSON using the top-down method
To create a CICS Web Service requester using the bottom-up method, JSON
To create CICS Web service requester from JSON using the top-down method
To install CCSID tables
To specify a CCSID table in the CICS SIT
To specify the corresponding ASCII CCSID for an EBCDIC CCSID
Related reference
New CICS Web Service Wizard Start page
New CICS Web Service (Bottom Up) pages 1 and 2
New CICS Web Service Provider page
New CICS Web Service Requester page
New CICS Web Service Requester and Provider page
CICS Web Services
CICS Web Service Provider (Bottom-Up, Request-Response)
CICS Web Service Provider (Top-Down, Request-Response)
CICS Web Service Requestor (Bottom-Up, Linkable Interface)
CICS Web Service Requestor (Top-Down, Linkable Interface)
ls2js command
js2ls command
ls2ws command
ws2ls command
CICS SIT Details
Create a New CICS SIT


CICS Web Service Types and Methods

Using Enterprise Developer, you can generate the following types of CICS Web services:

Provider
A provider CICS Web service is made available over the Web to a requester, which can be another Web service, a JSON request, or a SOAP request. The requester makes one or more requests to the provider, which then provides the requested data back to the requester.
Using Enterprise Developer, you can create a provider CICS Web service using either the top-down or the bottom-up method.
Top-down method
To use the top-down method, you start with a WSDL file, request and response JSON files, or a RESTful JSON file. These files describe an existing CICS COBOL application. From the WSDL file, request and response JSON files, or RESTful JSON file, you generate a CICS provider skeleton program containing a set of COBOL language structures to process requests, and a WSBIND file that maps the input and output of the provider program to the input and output of the described Web service.
Bottom-up method
To use the bottom-up method, you start with an existing CICS COBOL application, and expose its functionality as a Web service suitable for access across the Web. Minimally, the CICS COBOL application must consist of a main program (.cbl) file, and two copybook (.cpy) files - one containing input data structures, and one containing output data structures.

From the original application, Enterprise Developer generates WSDL or JSON that describes the application, and a WSBIND file that maps the input and output of the application to the Web service.

If you want to make your provider Web service available to multiple clients via the Web, you can distribute the generated WSDL file or JSON files from which requester clients can be generated. Organizations that distribute WSDL and JSON files for this purpose are called Web service provider agents.

Requester
All CICS Web service requesters are created using the top-down method. You start with a WSDL file or a set of request and response JSON files such as are supplied by a Web service provider agent, that describe the underlying CICS application. From the WSDL or JSON, Enterprise Developer generates a CICS client application to launch the Web service requester, and to receive returned data. In addition, Enterprise Developer generates a WSBIND file or a set of request and response JSBIND files. A bind file maps the input and output of the application to the Web service.
Parent topic: CICS Web Services


CWS Security

CICS Web services does not provide its own security; however, you can implement some measure of security using one or more of the following options:

TCPIPSERVICE
You can configure the TCPIPSERVICE with transport security (TLS/SSL). To use it effectively, a client might be required to perform authentication via a certificate, via HTTP Basic Authentication, or both. See SSL Support for CICS Web Interface Servers for details.
Authorization header
A CICS Web Service requester can send an Authorization header using the technique described for the IBM SupportPac CA8J in their SupportPac CA8J: Generate Basic Authentication headers for a CICS HTTP client document. Generally, this includes these three steps:
  1. Specify a transport handler program in the pipeline configuration file for the requester.
  2. Code the transport handler program to call the HTTPAUTH program, providing the required user name and password.
    Note: HTTPAUTH encodes the credentials in Base64.
  3. Using the encoded data returned from HTTPAUTH, append the transport handler program with an Authorization header to the SOAPAction header container.
Parent topic: CICS Web Services
Related concepts
SSL Support for CICS Web Interface Servers


New CICS Web Service Wizard

The New CICS Web Service Wizard enables you to create bottom-up provider Web services, and top-down provider and requester Web services. Before using the wizard, be sure you have assembled all of the required input components. See CICS Web Service Components for details.

Parent topic: CICS Web Services
Related tasks
To create a CICS Web Service provider using the bottom-up method, WSDL
To create a CICS Web Service provider from WSDL using the top-down method
To create CICS Web service requester from WSDL using the top-down method
To create a CICS Web service requester and provider from WSDL using the top-down method
Related reference
ls2ws command
ws2ls command


Troubleshooting

If you encounter any problems with your CICS Web Service application, use the following checklist to assist in determining a resolution. This list presents the most common problems:

General
Are CICS WEBSERVICES disabled?
If the following message appears in the console log:
CASSI0017W ES support for CICS WEBSERVICES is disabled. CCSID tables not found

Check your CCSID installation and configuration, and make corrections as required. See CCSID Conversion Tables for more information.

Note: When CICS WEBSERVICES are disabled, the PIPELINE and WEBSERVICE resources do not show in ESMAC.
Resources
Are all defined resources running on your enterprise server region?
If you have not installed a resource after adding or creating it, or have not reset the region since doing so, your new resources might not be running. Try resetting the region by stopping and restarting it.
Are the DFHWEB and DFHPIPE resource groups installed correctly?
If not, install these two groups to your enterprise server region using ESMAC. See To add a resource group to a startup list for details.
Provider mode: Did the PIPELINE resource install correctly?
Check to be sure that the PIPELINE configuration file is in the specified location. If it is, check the file to be sure it is a well-formed provider-mode (not requester-mode) configuration file.

Verify that the appropriate WEBSERVICEs and URIMAPs were automatically installed by the PIPELINE installation process, which installs one WEBSERVICE and one URIMAP for each WSBIND file found in the WSDIR directory specified by the PIPELINE definition.

Provider mode: Is the TCPIPSERVICE installed and the port open?
When using HTTP as your transport, check to ensure that the TCPIPSERVICE is installed and the port is open.
Requester mode: Did the PIPELINE resource install correctly?
Check to be sure that the PIPELINE configuration file is in the specified location. If it is, check the file to be sure it is a well-formed requester-mode (not provider-mode) configuration file.

Verify that the appropriate WEBSERVICEs were automatically installed by the PIPELINE installation process, which installs one WEBSERVICE for each WSBIND file found in the WSDIR directory specified by the PIPELINE definition.

Request handling
Is the request target accurate?
Check to be sure that the target of the request correctly identifies the host, port, and path, and that the appropriate case is used when applicable.
Is the request body accurate?
Verify that the SOAP or JSON code in the request is free of errors.
Mappings
Is the data in the WSBIND file mapped correctly?
Generate a log file for the generation of the WSBIND file using the appropriate CWS command-line utility – ws2ls, ls2ws, ws2js, or js2ws – with the logfile parameter (see the matching command Reference topic listed below for details). This file can be very useful when trying to diagnose problems that occur due to inaccurate data mapping between SOAP or JSON and COBOL.
Debugging
Is the data in the input structure(s) correct?
Verify that the input structure(s) contain the correct data.
Is the data in the output structure(s) correct?
Verify that the output structure(s) contain the correct data.
Is the container data correct?
Verify that all data in a container and sent to an application and all data retrieved from a container by the application is correct.
Diagnostics
CPIO transaction
The TD QUEUE CPIO collects a great deal of information and contains all CICS Web services error messages. The contents can be particularly useful, especially in diagnosing PIPELINE installation problems, including the failure to dynamically generate WEBSERVICEs and URIMAPs. You can retrieve the contents of the queue using the CPIO transaction, which generates an output file to the Enterprise Server work area.
Note: If you are unsure of the location of your work area, see the Enterprise Server System Directory topic for more information.
Application handler trace
To generate an application handler trace, access the active WEBSERVICE in ESMAC and check Trace Application Handler. Resubmit the request, and then check for an output file in the work area. The output file contains the following:
  • The names of the CICS resources being used
  • The SOAP or JSON message received by or sent from CICS
  • Parsing output for the received SOAP or JSON message
  • Key pieces of information from the WSBIND header
  • Output for the processing of the WSBIND from SOAP or JSON to COBOL
  • Output for the processing of the WSBIND from COBOL to SOAP orJSON
  • The response message built and sent back to or received by the requester
Note: If you are unsure of the location of your work area, see the Enterprise Server System Directory topic for more information.
CTF trace
In some cases, you might find that CTF trace is useful in addition to other diagnostics. See CTF Trace for more information.
SupportLine
If you are unable to diagnose a problem using the information in this topic, be sure to collect the following diagnostic information before calling SupportLine:
  • console.log file
  • Aux trace captured while the offending request ran, with at least the following flags:
    • kcp
    • api
    • cws
  • CAS dumps, ideally one taken before the request and another taken afterwards
  • Application Handler trace
  • Contents of the CPIO TD QUEUE
  • Log file for the generation of the WSBIND file

For more information on preparing to call SupportLine, see Information We Need.

Parent topic: CICS Web Services
Related concepts
CTF Trace
Information We Need
Enterprise Server System Directory
Related tasks
To add a resource group to a startup list
Related reference
ls2js command
js2ls command
ls2ws command
ws2ls command
CASSI0017W ES support for CICS WEBSERVICES is disabled. CCSID tables Source CCSID to Target CCSID not found


How to

  • To install CCSID tables
  • To specify a CCSID table in the CICS SIT
  • To specify the corresponding ASCII CCSID for an EBCDIC CCSID
  • To set preferences for CICS Web Services
  • To create a CICS Web Service provider using the bottom-up method, WSDL
  • To create a CICS Web Service provider from WSDL using the top-down method
  • To create CICS Web service requester from WSDL using the top-down method
  • To create a CICS Web service requester and provider from WSDL using the top-down method
  • To create a CICS Web Service provider using the bottom-up method, JSON
  • To create a CICS Web Service provider from JSON using the top-down method
  • To create a CICS Web Service requester using the bottom-up method, JSON
  • To create CICS Web service requester from JSON using the top-down method
Parent topic: CICS Web Services


To install CCSID tables

Note: To complete this task, you must have administrator privileges for the Enterprise Developer installation directory.
  1. In a Web browser, download the IBM CCSID tables (in cdctables.zip) from cdctables.zip to your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ccsid (Windows) or $COBDIR/etc/ccsid (UNIX) subdirectory.
  2. Use the tabindex.txt file located in the cdctables.zip file to identify the package number and filename for each CCSID table you need to install.
    Note: The CCSID value used in the SIT must be an EBCDIC one. As Enterprise Server operates in ASCII mode, you need to pick the corresponding ASCII CCSID as well. See To convert an EBCDIC CCSID to ASCII about how to configure this.
    • To use the CICS Web services feature with the default CCSID of 37 configured in the SIT, you install the IBM-37, IBM-437, and 002501B5 tables as a minimum:
      • IBM-37 is the conversion table to convert from CCSID 37 to UTF-8.
      • IBM-437 is the conversion table to convert from CCSID 437 (the corresponding default ASCII CCSID) to UTF-8.
      • 002501B5 is the conversion table to convert from CCSID 37 to CCSID 437.
    • If the CCSID value in the SIT is changed to a different EBCDIC CCSID (CCSID EBC1), you need to configure the corresponding ASCII CCSID (ASC1) as mentioned above. You need the following tables:
      • IBM-EBC1, IBM-ASC1 and the table to convert from EBC1 to ASC1 (the folder name would be denoted using the HEX values of EBC1 and ASC1).
  3. For each table you want to install, as a subdirectory to the ccsid directory, create a directory of the same name as the CCSID table filename as specified in the tabindex.txt file.
  4. For each CCSID that you want to install, open its corresponding Packagen.zip file (as specified in tabindex.txt) and extract the files from the appropriate CCSID .zip file to the corresponding directory you created in step 3.

    For example, to install a CCSID table to convert Spanish to USA English, create a subdirectory under ccsid named 011C01B5. Then extract the contents of package4.zip\011C01B5.zip (Windows) or package4.zip/011C01B5 (UNIX) to the 011C01B5 subdirectory.

    Note: You also need to create subdirectories and extract the IBM-284 and IBM-437 tables which are both contained in package1.zip.
  5. If your application uses another CCSID 'E1' in addition to the configured default ones, you might also need to download the following tables to convert from:
    • 'E1' to 437 (or the default ASCII CCSID)
    • 'E1' to 37 (or the default EBCDIC CCCSID)
    • 'E1' to UTF-8
Parent topic: How to
Related concepts
CCSID Conversion Tables
Related tasks
To specify the corresponding ASCII CCSID for an EBCDIC CCSID
To specify a CCSID table in the CICS SIT


To specify a CCSID table in the CICS SIT

Note: If you created your enterprise server region from Enterprise Developer using the CICSWebServices.xml template, the default EBCDIC local CCSID is set by default.
  1. From the Enterprise Server Administration Home page, start ESMAC for your enterprise server region.
  2. In the Resources group, click SIT.
  3. Click the Details button that corresponds to the SIT specified for the enterprise server region.
  4. In the Local CCSID field, type the decimal CCSID code set identifier.
    Note: If you do not know the code set identifier, see ccsid_registered.html.
  5. Click Apply.
Parent topic: How to
Related concepts
CCSID Conversion Tables


To specify the corresponding ASCII CCSID for an EBCDIC CCSID

Note: To complete this task, you must have administrator privileges to the Enterprise Developer installation directory.
  1. Install both the EBCDIC and ASCII CCSIDs. See To install CCSID tables for details.
  2. Specify the EBCDIC CCSID in the SIT. See To specify a CCSID table in the CICS SIT for details.
  3. Code a COBOL module named MFCCSIDMAP, inserting the following code:
           linkage section.
       01 lk-ccsid                     pic x(4) comp-5.

       procedure division using by reference lk-ccsid.
           if lk-ccsid = EBCDIC-CCSID
               move ASCII-CCSID to lk-ccsid
           end-if
           goback.

    Where EBCDIC-CCSID is the CSSID specified in the SIT and ASCII-CCSID is the corresponding ASCII CCSID.

  4. Compile MFCCSIDMAP to a dynamic link library (.dll) (Windows) or shared library (.so) (UNIX) file, using the charset(ASCII) and dialect(MF) directives.
  5. Make a backup copy of the existing MFCCSIDMAP.dll (Windows) or MFCCSIDMAP.so (UNIX) files located by default in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 (Windows) or $COBDIR/bin (UNIX).
  6. Copy your new MFCCSIDMAP compiled program files to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin and \bin64 directories respectively (Windows) or $COBDIR/bin (UNIX) directory, overwriting the existing files.
Parent topic: How to
Related concepts
Compiling from the Command Line (Windows)
Compiling and Linking from the Command Line (UNIX)
CCSID Conversion Tables
Related tasks
To install CCSID tables
To specify a CCSID table in the CICS SIT


To set preferences for CICS Web Services

  1. Click Windows > Preferences > Micro Focus > Service Interfaces > CICS Web Services.
  2. Change preferences as required. For a description of each field, see the CICS Web Services reference topic.
  3. Click OK.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Related reference
CICS Web Services


To create a CICS Web Service provider using the bottom-up method, WSDL

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click XML message processing.
  5. From the drop-down list, select CICS Web Service (Bottom-Up); then click Next.
  6. Complete the fields on this page and the next using the New CICS Web Service (Bottom Up) pages 1 and 2 reference topics as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
New CICS Web Service Wizard
Related reference
New CICS Web Service Wizard Start page
New CICS Web Service (Bottom Up) pages 1 and 2


To create a CICS Web Service provider from WSDL using the top-down method

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click XML message processing.
  5. From the drop-down list, select CICS Web Service Provider (Top-Down); then click Next.
  6. Complete the fields on this page using the New CICS Web Service Provider page reference topic as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
New CICS Web Service Wizard
Configuration Requirements for CICS Web Services
Related reference
New CICS Web Service Wizard Start page
New CICS Web Service Provider page


To create CICS Web service requester from WSDL using the top-down method

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click XML message processing.
  5. From the drop-down list, select CICS Web Service Requester (Top-Down); then click Next.
  6. Complete the fields on this page using the New CICS Web Service Requester page reference topic as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
New CICS Web Service Wizard
Related reference
New CICS Web Service Wizard Start page
New CICS Web Service Requester page


To create a CICS Web service requester and provider from WSDL using the top-down method

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click XML message processing.
  5. From the drop-down list, select CICS Web Service Requester and Provider (Top-Down); then click Next.
  6. Complete the fields on this page using the New CICS Web Service Requester and Provider page reference topic as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
New CICS Web Service Wizard
Related reference
New CICS Web Service Wizard Start page
New CICS Web Service Requester and Provider page


To create a CICS Web Service provider using the bottom-up method, JSON

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click JSON message processing.
  5. From the drop-down list, select CICS Web Service Provider(Bottom-Up, Request-Response); then click Next.
  6. Complete the fields on this and any subsequent Wizard pages using the CICS Web Service Provider (Bottom-Up, Request-Response) reference topic as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related reference
CICS Web Service Provider (Bottom-Up, Request-Response)


To create a CICS Web Service provider from JSON using the top-down method

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click JSON message processing.
  5. From the drop-down list, select CICS Web Service Provider (Top-Down, Request-Response); then click Next.
  6. Complete the fields on this page and any subsequent Wizard pages using the CICS Web Service Provider (Top-Down, Request-Response) reference topic as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related reference
CICS Web Service Provider (Top-Down, Request-Response)


To create a CICS Web Service requester using the bottom-up method, JSON

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click XML message processing.
  5. From the drop-down list, select CICS Web Service Requester (Bottom-Up, Linkable Interface); then click Next.
  6. Complete the fields on this page and any subsequent Wizard pages using the CICS Web Service Requester (Bottom-Up, Linkable Interface) reference topic as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related reference
CICS Web Service Requestor (Bottom-Up, Linkable Interface)


To create CICS Web service requester from JSON using the top-down method

  1. From the Application Explorer, right-click the project name; then select New > Other.
  2. Expand Micro Focus Service Interface.
  3. Select CICS Web Service; then click Next.

    This invokes the New CICS Web Service Wizard dialog box.

  4. Click XML message processing.
  5. From the drop-down list, select CICS Web Service Requester (Top-Down, Linkable Interface); then click Next.
  6. Complete the fields on this page and any subsequent Wizard pages using the CICS Web Service Requester (Top-Down, Linkable Interface) reference topic as your guide; then click Finish.
Parent topic: How to
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related reference
CICS Web Service Requestor (Top-Down, Linkable Interface)


Reference

  • Command line reference
  • CWS Resources
    Describes the ESMAC resources you need to define in each enterprise server region that runs a CICS Web service.
  • CWS API Calls
    Describes the CICS API calls that are supported for CICS Web services.
  • CWS SPI Calls
    Lists the CICS SPI calls that are supported for CICS Web services.
  • User Interface reference
Parent topic: CICS Web Services


Command line reference

  • js2ls command
    Generate a CICS application as a Web service provider or requester, starting with one or more JSON schemas.
  • ls2js command
    Exposes a CICS application program as a Web service by generating one or more JavaScript Object Notation (JSON) schema files and a Web service bind (WSBIND) file.
  • ls2ws command
    Exposes a CICS application program as a Web service by generating a Web service description (WSDL) file and a Web service bind (WSBIND) file.
  • ws2ls command
    Expose a CICS application as a Web service provider or construct a Web service requester. Generates COBOL data structures, a skeleton COBOL program, and a Web service bind (WSBIND) file from a Web service description file (WSDL).
Parent topic: Reference


js2ls command

Generate a CICS application as a Web service provider or requester, starting with one or more JSON schemas.
Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.

Syntax:

js2ls {json-schema=json-filename|
       json-schema-request=request-filename
       json-schema-response=response-filename|
       json-schema-restful=rest-filename}
       pgmname=program-name
       pgmint={channel|commarea}
       wsbind=bind-file
      [bundle=folder-name]
      [char-whitespace={collapse|replace|preserve}]
      [contid=container-name]
      [ccsid=ccsid]
      [data-trunction={enabled|disabled}]
      [default-char-maxlength=max-length]
      [http-methods={GET|POST|PUT|DELETE|HEAD}[,...]]
      [inline-maxoccurs-limit=max-occurs]
      [jsontransfrm=transform-filename]
      [logfile=logfile]
      [pdsmem=pds-prefix]
      [reqmem=request-prefix]
      [respmem=response-prefix]
      [synconreturn={yes|no}]
      [uri=address]
js2ls -help

Parameters:

json-schema=json-filename
The fully qualified name of the JSON schema file. linkable interfaces only.
json-schema-request=request-filename
The fully qualified name of the JSON schema file that contains the input data area. Must be used with json-schema-response=response-filename. For Request-Response services only.
json-schema-response=response-filename
The fully qualified name of the JSON schema file that contains the output data area. Must be used with json-schema-request=request-filename. For Request-Response services only.
json-schema-restful=rest-filename
The fully qualified name of the JSON schema file. For RESTful services only.
pgmint={channel|commarea}
Note: For generating a Web service provider.
channel
Create a service provider that passes data to the target application program via a channel container.
commarea
Create a service provider that passes data to the target application program via a commarea.
pgmname=program-name
The fully qualified file name to use for the generated skeleton CICS program. Depending on other supplied parameters, this skeleton program is generated either to invoke a Web service (requester), or to be exposed as a Web service (provider).
wsbind=bind-file
The fully qualified name of the Web service bind file.
bundle=folder-name
The path to and name of the bundle directory and archive file (.zip or .jar).
ccsid=ccsid
The CCSID used at runtime to encode character data into the application data structure.
contid=container-name
For generating a Web service provider, the name of the container that holds the top-level data structure used to represent a SOAP message. When not specified, this defaults to DFHWS-DATA.
data-truncation={enabled|disabled}
enabled
Variable-length data is tolerated in a fixed-length field structure.
disabled
Variable-length data is not tolerated in a fixed-length field structure.
default-char-maxlength=max-length
The default string size to use for unbounded strings when none is specified in the JSON schema.
http-methods={GET|POST|PUT|DELETE|HEAD}[,...]
For RESTful services only, specify one or more methods that are accepted by the RESTful service. Separate multiple methods with a comma (,).
inline-maxoccurs-limit=max-occurs
The maximum size an array can be before it is replaced with a container-based mapping in the generated service or client. Valid values are from 1 to 32767 inclusive.
Note: For complete information about how Enterprise Developer generates COBOL variable-length array structures for CICS Web services from WSDL and JSON, see Handling Variable Arrays in WSDL and JSON - CICS COBOL.
jsontransfrm=transform-filename
The name to use for the JSONTRANSFRM bundle resource in CICS; also the name of the generated JSBIND file. linkable interfaces only.
logfile=logfile
The fully qualified name of a logfile to contain output information generated by the js2ls command. When not specified, no logfile is generated.
pdsmem=pds-prefix
The prefix to use for the copybook containing the generated data structure. For linkable and RESTful services only.
reqmem=request-prefix
A one- to six-character prefix used in naming the request copybook file generated for a Web service. The generated copybook file contains the Web service request data structures.
respmem=response-prefix
A one- to six-character prefix used in naming the response copybook file generated for a Web service. The generated copybook file contains the Web service response data structures.
synconreturn={yes|no}
yes
The remote service can issue a sync point.
no
The remote service cannot issue a sync point.
uri=address
For Web service providers, specifies the relative URI used by a client to access the Web service. For Web service requesters, specifies an absolute URI used in the EXEC CICS INVOKE SERVICE call within the generated skeleton program.
-help
Displays information about ws2ls parameters.
Parent topic: Command line reference
Parent topic: CICS Web Services
Related concepts
CICS Web Services
CCSID Conversion Tables
Related reference
CICS Web Service Provider (Top-Down, Request-Response)
CICS Web Service Provider (Top-down, RESTful)
CICS Web Service Requestor (Top-Down, Linkable Interface)


ls2js command

Exposes a CICS application program as a Web service by generating one or more JavaScript Object Notation (JSON) schema files and a Web service bind (WSBIND) file.
Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.

Syntax:

ls2js {json-schema=json-filename|
       json-schema-request=request-filename
       json-schema-response=response-filename}
       pgmint={channel|commarea}
       pgmname=program-name
       reqmem=request-copy-file
       uri=address
       wsbind=bind-file
      [bundle=folder-name]
      [ccsid=ccsid]
      [contid=container-name]
      [data-truncation={enabled|disabled}]
      [datetime={unused|packed15}]
      [logfile=logfile]
      [operation-name=operation-name]
      [pdsmem=pds-prefix]
      [respmem=response-copy-file]
      [jsontransfrm=transform-filename]
      [synconreturn={yes|no}]
ls2js -help

Parameters:

json-schema=json-filename
The fully qualified name of the JSON schema file. linkable interfaces only.
json-schema-request=request-filename
The fully qualified name of the JSON schema file that contains the input data area. Must be used with json-schema-response=response-filename. For Request-Response services only.
json-schema-response=response-filename
The fully qualified name of the JSON schema file that contains the output data area. Must be used with json-schema-request=request-filename. For Request-Response services only.
pgmint={channel|commarea}
channel
Pass data via a channel container.
commarea
Pass data via a commarea.
pgmname=program-name
The name of the target application program to expose as a Web service.
reqmem=request-copy-file
The fully qualified name of the copybook file containing the high-level language structure for the Web service request.
uri=address
The relative or absolute URI to be used by a client to access the Web service.
wsbind=bind-file
The fully qualified name of the Web service bind file.
bundle=folder-name
The path to and name of the bundle directory and archive file (.zip or .jar). Linkable interface only.
ccsid=ccsid
The CCSID used at runtime to encode character data into the application data structure.
contid=container-name
The name of the container that holds the top-level data structure used to represent a JSON message. When not specified, this defaults to DFHWS-DATA.
data-truncation={enabled|disabled}
enabled
Variable-length data is tolerated in a fixed-length field structure.
disabled
Variable-length data is not tolerated in a fixed-length field structure.
logfile=logfile
The fully qualified name of a logfile to contain output information generated by the ls2js command. When not specified, no logfile is generated.
pdsmem=pds-prefix
For linkable interface only, the prefix to use for the copybook containing the generated data structure.
respmem=response-copy-file
The fully qualified name of the copybook file containing the high-level language structure for the Web service response.
synconreturn={yes|no}
yes
The remote service can issue a sync point.
no
The remote service cannot issue a sync point.
-help
Displays information about ls2js parameters.
Parent topic: Command line reference
Parent topic: CICS Web Services
Related concepts
CICS Web Services
CCSID Conversion Tables
Related reference
CICS Web Service Provider (Bottom-Up, Request-Response)
CICS Web Service Requestor (Bottom-Up, Linkable Interface)


ls2ws command

Exposes a CICS application program as a Web service by generating a Web service description (WSDL) file and a Web service bind (WSBIND) file.
Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.

Syntax:

ls2ws pgmint={channel|commarea}
      pgmname=program-name
      reqmem=request-copy-file
      uri=address
      wsbind=bind-file
      wsdl=wsdl-file
     [ccsid=ccsid]
     [contid=container-name]
     [data-truncation={enabled|disabled}]
     [datetime={unused|packed15}]
     [logfile=logfile]
     [operation-name=operation-name]
     [respmem=response-copy-file]
     [synconreturn={yes|no}]
     [wsdl-namespace=wsdl-namespace]
ls2ws -help

Parameters:

pgmint={channel|commarea}
channel
Pass data via a channel container.
commarea
Pass data via a commarea.
pgmname=program-name
The name of the target application program to expose as a Web service.
reqmem=request-copy-file
The fully qualified name of the copybook file containing the high-level language structure for the Web service request.
uri=address
The relative or absolute URI to be used by a client to access the Web service.
wsbind=bind-file
The fully qualified name of the Web service bind file.
wsdl=wsdl-file
The fully qualified name of the WSDL file to contain the Web service description.
ccsid=ccsid
The CCSID used at runtime to encode character data into the application data structure.
contid=container-name
The name of the container that holds the top-level data structure used to represent a SOAP message. When not specified, this defaults to DFHWS-DATA.
data-truncation={enabled|disabled}
enabled
Variable-length data is tolerated in a fixed-length field structure.
disabled
Variable-length data is not tolerated in a fixed-length field structure.
datetime={unused|packed15}
unused
Packed decimal fields of length 15 (8 bytes) in the data structure are not used.
packed15
Packed decimal fields of length 15 (8 bytes) in the data structure are treated as CICS ABSTIME fields and mapped as timestamps.
logfile=logfile
The fully qualified name of a logfile to contain output information generated by the ls2ws command. When not specified, no logfile is generated.
operation-name=operation-name
The operation name used in the generated WSDL file. When not specified, this defaults to the value of program-name plus the literal value Operation.
respmem=response-copy-file
The fully qualified name of the copybook file containing the high-level language structure for the Web service response.
wsdl-namespace=wsdl-namespace
The CICS namespace used in the generated WSDL file. When not specified, this defaults to http://www.pgmname.comwhere pgmname is the value passed to the pgmname parameter.
synconreturn={yes|no}
yes
The remote service can issue a sync point.
no
The remote service cannot issue a sync point.
-help
Displays information about ls2ws parameters.

Examples:

Example 1
The following command uses the incpy.cpy request copybook and the outcpy.cpy response copybook to communicate with the comml1 CICS program, and generates the mywsdl.wsdl WSDL file and the mywsbind.wsbind Web service bind file:
ls2ws pgmname=comml1
      pgmint=channel
      reqmem=incpy.cpy
      respmem=outcpy.cpy
      wsdl=mywsdl.wsdl
      wsbind=mywsbind.wsbind
      uri=/mysvc/operation
Example 2
The following command uses the set1.cpy request copybook to communicate with the set1 CICS program, and generates the set1.wsdl WSDL file and the set1.wsbind Web service bind file that each contain a newly defined operation named newOperation:
ls2ws pgmname=set1
      pgmint=commarea
      reqmem=set1.cpy
      wsdl=set1.wsdl
      wsbind=set1.wsbind
      uri=/mysvc/operation
      operation-name=newOperation
Parent topic: Command line reference
Parent topic: CICS Web Services
Related concepts
CICS Web Services
New CICS Web Service Wizard
CCSID Conversion Tables
Related reference
New CICS Web Service (Bottom Up) pages 1 and 2


ws2ls command

Expose a CICS application as a Web service provider or construct a Web service requester. Generates COBOL data structures, a skeleton COBOL program, and a Web service bind (WSBIND) file from a Web service description file (WSDL).
Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.

Syntax:

ws2ls pgmname=program-name
      wsdl=wsdl-file
      wsbind=bind-file
     [ccsid=ccsid]
     [contid=container-name]
     [default-char-maxlength=max-length]
     [inline-maxoccurs-limit=max-occurs]
     [logfile=logfile]
     [operations=op-name-1[,op-name-n[,...]]]
     [pgmint={channel|commarea}]
     [reqmem=request-prefix]
     [respmem=response-prefix]
     [synconreturn={yes|no}]
     [uri=address]
ws2ls -help

Parameters:

pgmname=program-name
The fully qualified file name to use for the generated skeleton CICS program. Depending on other supplied parameters, this skeleton program is generated either to invoke a Web service (requester), or to be exposed as a Web service (provider).
wsdl=wsdl-file
The fully qualified name of the WSDL file that contains the Web service description.
wsbind=bind-file
The fully qualified name of the Web service bind file.
ccsid=ccsid
The CCSID used at runtime to encode character data into the application data structure.
contid=container-name
The name of the container that holds the top-level data structure used to represent a SOAP message. When not specified, this defaults to DFHWS-DATA. Used only when generating a Web service provider.
default-char-maxlength=max-length
The default string size to use for unbounded strings when none is specified in the WSDL file.
inline-maxoccurs-limit=max-occurs
The maximum size an array can be before it is replaced with a container-based mapping in the generated service or client. Valid values are from 1 through 32767 inclusive.
Note: For complete information about how Enterprise Developer generates COBOL variable-length array structures for CICS Web services from WSDL and JSON, see Handling Variable Arrays in WSDL and JSON - CICS COBOL.
logfile=logfile
The fully qualified name of a logfile to contain output information generated by the ws2ls command. When not specified, no logfile is generated.
operations=op-name-1[,op-name-n[,...]]
Specifies a subset of valid WSDL operations to use in generating the WSBIND file; requester mode only.
pgmint={channel|commarea}
channel
Create a service provider that passes data to the target application program via a channel container.
Note: Do not specify the pgmint parameter when constructing a Web service requestor.
commarea
Create a service provider that passes data to the target application program via a commarea.
Note: Do not specify the pgmint parameter when constructing a Web service requestor.
reqmem=request-prefix
Specifies a one- to six-character prefix used in naming copybook files generated for requester Web services. A unique two-digit number is appended to this prefix to produce uniquely named copybook files. Each generated copybook file contains the request data structures for one operation defined in the given WSDL file.
respmem=response-prefix
Specifies a one- to six-character prefix used in naming copybook files generated for provider Web services. A unique two-digit number is appended to this prefix to produce the copybook file name. The generated copybook file contains the Web service response data structures.
synconreturn={yes|no}
yes
The remote service can issue a sync point.
no
The remote service cannot issue a sync point.
uri=address
For Web service providers, specifies the relative URI used by a client to access the Web service. For Web service requesters, specifies an absolute URI used in the EXEC CICS INVOKE SERVICE call within the generated skeleton program. When a URI is not supplied for a requestor Web service, the EXEC CICS INVOKE SERVICE call uses the service end point address found in the WSDL file.
-help
Displays information about ws2ls parameters.

Examples:

Example 1
The following command uses the mywsdl.wsdl WSDL file to create the program.cbl skeleton COBOL program and the mywsbind.wsbind Web service bind file:
ws2ls wsdl=mywsdl.wsdl
      pgmname=program.cbl
      wsbind=mywsbind.wsbind
      pgmint=channel
      reqmem=REQ
      respmem=RESP
Example 2
The following command uses the mywsdl.wsdl WSDL file and the /mysvc/operation URI to create the mywsbind.wsbind Web service bind file, appropriate request and response copybook files, and the program.cbl skeleton COBOL program, which uses a Commarea interface to receive requests and return responses:
ws2ls wsdl=mywsdl.wsdl
        pgmname=program.cbl
        wsbind=mywsbind.wsbind
        reqmem=REQ
        respmem=RESP
        uri=/mysvc/operation
        pgmint=commarea
Parent topic: Command line reference
Parent topic: CICS Web Services
Related concepts
CICS Web Services
New CICS Web Service Wizard
CCSID Conversion Tables
Related reference
New CICS Web Service Provider page
New CICS Web Service Requester page
New CICS Web Service Requester and Provider page


CWS Resources

Describes the ESMAC resources you need to define in each enterprise server region that runs a CICS Web service.
Note: For complete information on each resource, see the Resources section under Enterprise Server Monitor and Control in this documentation.
PIPELINE
Add a PIPELINE resource for CICS provider and requester applications for SOAP, and CICS provider applications for JSON. A PIPELINE defines information about the handler programs that are invoked during the processing of request and response messages. This information is provided by the XML file you specify as the PIPELINE's CONFIGFILE attribute. A single PIPELINE is often used by multiple services.

For both provider and requester applications, the PIPELINE installation processes generates and installs a WEBSERVICE resource for each WSBIND file found in the location specified by the WSDIR attribute. For provider-only applications, the installation process also dynamically generates a URIMAP resource that identifies which PIPELINE to use.

Note: CICS requester applications for JSON use the linkable interface instead of the PIPELINE resource.
WEBSERVICE
A WEBSERVICE defines:
  • The set of handler programs that operate on the request and response messages via the PIPELINE.
  • The WSBIND file used to transform messages between SOAP/JSON and COBOL.
  • A Web service description (as in a WSDL file). This is ignored at run time because run-time validation against the Web service description is not supported.

You can create a WEBSERVICE resource from scratch; however, this is often unnecessary as WEBSERVICE resources are dynamically generated and installed by the PIPELINE installation process when the WSBIND file for the service is in the directory specified by the PIPELINE's WSDIR attribute.

Note: CICS requester applications for JSON use the linkable interface instead of the WEBSERVICE resource.
URIMAP
In the context of a CICS Web service, you should set the URIMAP USAGE value to PIPELINE. This associates incoming messages with a PIPELINE and a WEBSERVICE.
BUNDLE
The BUNDLE resource applies only to CICS requester applications that use the JSON linkable interface (JSONTRANSFRM bundle), which includes a JSBINE file that provides information required by JSON requester applications at runtime to map between application data and JSON messages.
Note: BUNDLE can also be used for XSDBIND files that have been generated on the mainframe for use on CICS TRANSFORM commands. Enterprise Developer does not generate XSDBIND files.
Parent topic: Reference
Related reference
Resources


CWS API Calls

Describes the CICS API calls that are supported for CICS Web services.
Note: For complete information on each API call, see the CICS API Calls section of this documentation.
INVOKE SERVICE
Used by a CICS application to invoke a Web service. The SCOPE and SCOPELEN attributes are ignored.
SOAPFAULT CREATE
Creates a SOAP fault. The NATLANG attribute is ignored.
SOAPFAULT ADD
Adds information to an existing SOAPFAULT. The NATLANG, SUBCODESTR and SUBCODELEN attributes are ignored.
SOAPFAULT DELETE
Deletes an existing SOAPFAULT.
Parent topic: Reference
Related reference
CICS API Calls


CWS SPI Calls

Note: For complete information on each SPI call, see the CICS SPI Calls section of this documentation.
  • DISCARD PIPELINE
  • DISCARD TCPIPSERVICE
  • DISCARD URIMAP
  • DISCARD WEBSERVICE
  • INQUIRE PIPELINE
  • INQUIRE TCPIPSERVICE
  • INQUIRE URIMAP
  • INQUIRE WEBSERVICE
  • SET BUNDLE
  • SET PIPELINE
  • SET URIMAP
  • SET WEBSERVICE
Parent topic: Reference
Related reference
CICS SPI Calls


User Interface reference

  • CICS Web Services
  • New CICS Web Service Wizard Start page
  • New CICS Web Service (Bottom Up) pages 1 and 2
  • New CICS Web Service Provider page
  • New CICS Web Service Requester page
  • New CICS Web Service Requester and Provider page
  • CICS Web Service Provider (Bottom-Up, Request-Response)
  • CICS Web Service Provider (Top-Down, Request-Response)
  • CICS Web Service Provider (Top-down, RESTful)
  • CICS Web Service Requestor (Bottom-Up, Linkable Interface)
  • CICS Web Service Requestor (Top-Down, Linkable Interface)
Parent topic: Reference


CICS Web Services

Default String Length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default Array Size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Related tasks
To set preferences for CICS Web Services


New CICS Web Service Wizard Start page

XML message processing
Lists the types of CICS Web services you can create using this wizard and WSDL.
JSON message processing
Lists the types of CICS Web services you can create using this wizard and JSON.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create a CICS Web Service provider using the bottom-up method, WSDL
To create a CICS Web Service provider from WSDL using the top-down method
To create CICS Web service requester from WSDL using the top-down method
To create a CICS Web service requester and provider from WSDL using the top-down method


New CICS Web Service (Bottom Up) pages 1 and 2

Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
Program location
The location of the program from which to create the Web service. Click Browse to select a location.
Program name
The name of the program from which to create the Web service.
Service location
The endpoint URL used to invoke the Web service, consisting of the server, port, and a URI used to identify the Web service in Enterprise Server.
Program interface
Lists the types of interfaces you can select for this Web service: COMMAREA or CHANNEL.
Container name
Shows the name of the container associated with the selected interface. The default name for the COMMAREA interface is DFHWS-DATA, which cannot be changed. For a CHANNEL interface, this field is enabled so you can type in the name of the container.
Operation name
The name of the operation defined in the service interface. The default is program-nameOperation.
Request structure
The path or virtual path to and name of a program or copybook that contains the data structures required to request data. Click Browse to select a file.
Response structure
The path or virtual path to and name of a program or copybook that contains the data structures required to send data. Click Browse to select a file.
Additional parameters
Any additional parameters. See the ls2lws reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create a CICS Web Service provider using the bottom-up method, WSDL
Related reference
ls2ws command


New CICS Web Service Provider page

Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
Service definition
The WSDL file used to create the Web service. Click Browse to select a file.
Program name
The name of the generated Web service program.
Service location
The endpoint URL used to invoke the Web service, consisting of the server, port, and a URI used to identify the Web service in Enterprise Server.
Request file prefix
A file prefix for the generated copybook containing the request data structure.
Response file prefix
A file prefix for the generated copybook containing the response data structure.
Program interface
Lists the types of interfaces you can select for this Web service: COMMAREA or CHANNEL.
Container name
Shows the name of the container associated with the selected interface. The default name for the COMMAREA interface is DFHWS-DATA, which cannot be changed. For a CHANNEL interface, this field is enabled so you can type in the name of the container.
Default string length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default array size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Additional parameters
Any additional parameters. See the ws2ls reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Related tasks
To create a CICS Web Service provider from WSDL using the top-down method
Related reference
ws2ls command


New CICS Web Service Requester page

Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
Service definition
The WSDL file used to create the Web service. Click Browse to select a file.
Program name
The name of the generated Web service program.
Request file prefix
A file prefix for the generated copybook containing the request data structure.
Response file prefix
A file prefix for the generated copybook containing the response data structure.
Default string length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default array size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Additional parameters
Any additional parameters. See the ws2ls reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create CICS Web service requester from WSDL using the top-down method
Related reference
ws2ls command


New CICS Web Service Requester and Provider page

Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
Service definition
The WSDL file used to create the Web service. Click Browse to select a file.
Requester program name
The name of the generated Web service requester program.
Provider program name
The name of the generated Web service provider program.
Service location
The endpoint URL used to invoke the Web service, consisting of the server, port, and a URI used to identify the Web service in Enterprise Server.
Request file prefix
A file prefix for the generated copybook containing the request data structure.
Response file prefix
A file prefix for the generated copybook containing the response data structure.
Program interface
Lists the types of interfaces you can select for this Web service: COMMAREA or CHANNEL.
Container name
Shows the name of the container associated with the selected interface. The default name for the COMMAREA interface is DFHWS-DATA, which cannot be changed. For a CHANNEL interface, this field is enabled so you can type in the name of the container.
Default string length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default array size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Additional parameters
Any additional parameters. See the ws2ls reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create a CICS Web service requester and provider from WSDL using the top-down method
Related reference
ws2ls command


CICS Web Service Provider (Bottom-Up, Request-Response)

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.
Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.
Page 1, New CICS JSON Web Service
Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
Program location
The location of the program from which to create the Web service. Click Browse to select a location.
Program name
The name of the program from which to create the Web service.
Service location
The endpoint URL used to invoke the Web service, consisting of the server, port, and a URI used to identify the Web service in Enterprise Server.
Program interface
Lists the types of interfaces you can select for this Web service: COMMAREA or CHANNEL.
Container name
Shows the name of the container associated with the selected interface. The default name for the COMMAREA interface is DFHWS-DATA, which cannot be changed. For a CHANNEL interface, this field is enabled so you can type in the name of the container.
Page 2, Interface Mapping and Output Artifacts
Request structure
The path or virtual path to and name of a program or copybook that contains the data structures required to request data. Click Browse to select a file.
Response structure
The path or virtual path to and name of a program or copybook that contains the data structures required to send data. Click Browse to select a file.
JSON request
The name of a request JSON schema file that defines input data structure. Click Browse to select a folder and/or schema file.
JSON response
The name of a response JSON schema file that defines output data structure. Click Browse to select a folder and/or schema file.
WSBIND file
The fully qualified name of the Web service bind file. Click Browse to select a folder and/or WSBIND file.
Additional parameters
Any additional parameters. See the ls2js reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create a CICS Web Service provider using the bottom-up method, JSON
Related reference
ls2js command


CICS Web Service Provider (Top-Down, Request-Response)

Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.
Page 1, New CICS JSON Web Service
Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
JSON request
The fully qualified name of the JSON schema file that contains the input data area. Click Browse to select a schema file.
JSON response
The fully qualified name of the JSON schema file that contains the output data area. Click Browse to select a schema file.
Service location
The endpoint URL used to invoke the Web service, consisting of the server, port, and a URI used to identify the Web service in Enterprise Server.
Program interface
Lists the types of interfaces you can select for this Web service: COMMAREA or CHANNEL.
Container name
Shows the name of the container associated with the selected interface. The default name for the COMMAREA interface is DFHWS-DATA, which cannot be changed. For a CHANNEL interface, this field is enabled so you can type in the name of the container.
Page 2, Additional Parameters and Output Artifacts
Program name
The name of the program from which to create the Web service.
Request file prefix
A file prefix for the generated copybook containing the request data structure.
Response file prefix
A file prefix for the generated copybook containing the response data structure.
WSBIND file
The fully qualified name of the Web service bind file. Click Browse to select a folder and/or WSBIND file.
Default string length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default array size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Additional parameters
Any additional parameters. See the js2ls reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create a CICS Web Service provider from JSON using the top-down method
Related reference
js2ls command


CICS Web Service Provider (Top-down, RESTful)

Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.
Page 1
Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
JSON schema
The fully qualified name of the JSON schema file. Click Browse to select a schema file.
Service location
The endpoint URL used to invoke the Web service, consisting of the server, port, and a URI used to identify the Web service in Enterprise Server.
HTTP methods
For RESTful services only, specify one or more methods that are accepted by the RESTful service. Separate multiple methods with a comma (,).
Program interface
Lists the types of interfaces you can select for this Web service: COMMAREA or CHANNEL.
Container name
Shows the name of the container associated with the selected interface. The default name for the COMMAREA interface is DFHWS-DATA, which cannot be changed. For a CHANNEL interface, this field is enabled so you can type in the name of the container.
Page 2, Additional Parameters and Output Artifacts
Program name
The name of the program from which to create the Web service.
Copy file prefix
The prefix to use for the copybook containing the generated data structure.
WSBIND file
The fully qualified name of the Web service bind file. Click Browse to select a WSBIND file.
Default string length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default array size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Additional parameters
Any additional parameters. See the js2ls reference topic for a list of parameters.
Parent topic: User Interface reference
Related reference
js2ls command


CICS Web Service Requestor (Bottom-Up, Linkable Interface)

Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.
Page 1, New CICS JSON Web Service
Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
Service name
The name of the generated service interface file.
Page 2, New CICS JSON Web Service
Request structure
The path or virtual path to and name of a program or copybook that contains the data structures required to request data. Click Browse to select a file.
Bundle
The path to and name of the bundle directory and archive file (.zip or .jar). Click Browse to select an archive file.
JSON transform
The name to use for the JSONTRANSFRM bundle resource in CICS; also the name of the generated JSBIND file.
JSON schema
The fully qualified name of the JSON schema file that contains the input data area. Click Browse to select a schema file.
Additional parameters
Any additional parameters. See the ls2js reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create a CICS Web Service requester using the bottom-up method, JSON
Related reference
ls2js command


CICS Web Service Requestor (Top-Down, Linkable Interface)

Important: Before attempting to run a CICS Web Service on Enterprise Server, review the information in the Configuration Requirements for CICS Web Services topic.
Page 1
Project
Shows the name of the project in which the CICS Web service is created. The default is the current project. Click Browse to specify a different project.
Service name
The name of the generated service interface file.
Page 2, Request
JSON schema
The fully qualified name of the JSON schema file that contains the input data area. Click Browse to select a schema file.
Request file prefix
A one- to six-character prefix used in naming the request copybook file generated for a Web service. The generated copybook file contains the Web service request data structures.
Bundle
The path to and name of the bundle directory and archive file (.zip or .jar). Click Browse to select an archive file.
JSON transform
The name to use for the JSONTRANSFRM bundle resource in CICS; also the name of the generated JSBIND file.
Default string length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default array size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Additional parameters
Any additional parameters. See the js2ls reference topic for a list of parameters.
Page 3, Response
JSON schema
The fully qualified name of the JSON schema file that contains the output data area. Click Browse to select a schema file.
Response file prefix
A one- to six-character prefix used in naming the response copybook file generated for a Web service. The generated copybook file contains the Web service response data structures.
Bundle
The path to and name of the bundle directory and archive file (.zip or .jar). Click Browse to select an archive file.
JSON transform
The name to use for the JSONTRANSFRM bundle resource in CICS; also the name of the generated JSBIND file.
Default string length
The maximum number of characters that can be processed in a COMMAREA or CHANNEL string.
Default array size
The maximum number of times a single array can be processed by a COMMAREA or CHANNEL string.
Additional parameters
Any additional parameters. See the js2ls reference topic for a list of parameters.
Parent topic: User Interface reference
Related concepts
CCSID Conversion Tables
Configuration Requirements for CICS Web Services
Related tasks
To create CICS Web service requester from JSON using the top-down method
Related reference
js2ls command


HCO for DB2 LUW

Explains the functionality associated with the DB2 External Compiler Module (ECM) preprocessor, and provides information for developing and deploying DB2 ECM SQL applications.
  • Demonstration Applications
    A list of available demonstration applications provided to illustrate programming techniques and runtime behavior for applications using HCO for DB2 LUW and 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
  • Host Compatibility Option (HCO)
  • How to
  • Reference
Parent topic: Mainframe Programming
Related concepts
Database Access Preprocessors
Compiling SQL Applications


Demonstration Applications

Enterprise Developer provides a number of demonstration applications or programs for HCO for DB2 LUW and the DB2 ECM. On Windows platforms, you can access these via the Mainframe and Visual COBOL Samples Browsers. For instructions on how to start either Samples Browser, see To start the Samples Browser.

HCO for DB2 LUW – Windows Environment

All HCO for DB2 LUW samples are listed on the Show unmanaged only list in the Mainframe Samples Browser.

The source files are located in subdirectories under %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\SQL\HCO for DB2 LUW.

Each sample application comes with a Readme file to explain how to use the application.

HCO for DB2 LUW - Getting Started
Demonstrates the functionality of Host Compatibility Option, including: Database creation; DDL processing; Import; Export; DCLGEN; Using Static SQL statements; Using Dynamic SQL statements.
HCO for DB2 LUW - BindAll
Demonstrates how to write bind (.bnd) files to a different directory using DB2(BINDDIR) directive, and then run the HCO BINDALL command using a post build event to bind all of the generated .bnd files.

HCO for DB2 LUW – UNIX Environment

One HCO for DB2 LUW demonstration application, hcodemo, is supplied. This application consists of several scripts and COBOL programs that demonstrate the functionality of the Host Compatibility Option.

The source files for this demonstration are located in $COBDIR/demo/hco The hcodemo.txt file in the same location explains how to use the application.

DB2 ECM – Windows Environment

All DB2 ECM samples are listed on the Show managed only list in the Visual COBOL Samples Browser.

The source files are located in subdirectories under %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Eclipse\COBOL\sql\db2ecm.

Each sample application comes with a Readme file to explain how to use the application.

The following applications are provided:

DB2 ECM - Connect
Shows the syntax variants for connecting to and disconnecting from a DB2 database using Type 1 CONNECTs that IBM DB2 LUW supports.
DB2 ECM - Db2storedproc
Shows how to create and call a COBOL stored procedure using IBM DB2 LUW.
DB2 ECM - Dynamic
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.
DB2 ECM - LOB Data Types
Illustrates the use of LOB LOCATOR and VALUES functions to retrieve LOB data from DB2 LUW.
DB2 ECM - Select
A simple example of using both singleton SELECT and cursor-based FETCH statements with IBM DB2 LUW.
DB2 ECM - Whenever
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.

DB2 ECM – UNIX Environment

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: HCO for DB2 LUW
Related tasks
To start the Samples Browser


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
  • User Defined Functions
  • Extensions to Embedded SQL Support
  • Compiling
  • Error Codes
  • Building Applications
  • Binding
  • Linking
Parent topic: HCO for DB2 LUW


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


User Defined Functions

Restriction: This topic applies to Windows environments (local development) only.

A program containing a reference to a User Defined Function (UDF) causes a separate module to be invoked; it contains user-supplied code which returns an appropriate value or values. The UDF code itself does not contain any SQL.

Running a program containing embedded SQL statements causes DB2 to be invoked and this in turn may invoke the UDF module. The declaration of the UDF should specify the language this module is written in. DB2 currently allows this to be C only, although on some platforms it is possible to write the module in COBOL. The following section demonstrates by use of example how this may be achieved. More complete descriptions of User Defined Functions and parameter descriptions are provided in the DB2 documentation.

User Defined Functions written in COBOL are not currently supported on UNIX.

Note: In a client/server configuration, the UDF module is invoked on the server and these restrictions apply to the server only - any client can access UDFs if the server is suitable.

The entry points in the UDF should be defined using C calling conventions. The following sample code segments show the use and definition of a simple UDF to calculate an exponent:

Program 1 declares the function to DB2. This program must be compiled and executed before program 2 can be compiled.

exec sql
   create function mfexp(integer, integer)
      returns integer
      fenced
      external name 'db2v2fun!mfexp'
      not variant
      no sql
      parameter style db2sql
      language cobol
      no external action
end-exec

Note the LANGUAGE COBOL clause. This is provided by Micro Focus COBOL as an extension to the DB2 syntax. It is equivalent to LANGUAGE C and, regardless of which is used, the called module should conform to the C calling convention. The EXTERNAL NAME clause specifies, in this case, that the called module is called db2v2fun.dll and the entry point within this is mfexp.

Program 2 uses the UDF:

     move 2 to hv-integer
     move 3 to hv-integer-2
     exec sql
         values (mfexp(:hv-integer, :hv-integer-2))
          into :hv-integer-3
     end-exec

Program 3 is a pure COBOL program containing the UDF itself.

$set case
 special-names.
     call-convention 0 is cc.
 linkage section.
 01  a pic s9(9) comp-5.
 01  b pic s9(9) comp-5.
 01  c pic s9(9) comp-5.
 01  an pic s9(4) comp-5.
 01  bn pic s9(4) comp-5.
 01  cn pic s9(4) comp-5.
 01  udf-sqlstate pic x(6).
 01  udf-fname pic x(28).
 01  udf-fspecname pic x(19).
 01  udf-msgtext pic x(71).
 procedure division cc.
    goback
    .
 entry "mfexp" cc
     using a b c an bn cn
           udf-sqlstate
           udf-fname
           udf-fspecname
           udf-msgtext.
     if an not = 0 or bn not = 0
         move -1 to cn
     else
         compute c = a ** b
         move 0 to cn
     end-if
     goback
     .

This module should be compiled to create a dynamically loadable executable (dll) and placed somewhere where the operating system can locate it (on the PATH).

Note: Entry-point names are case sensitive on all systems. Care should be exercised in matching case names, and the CASE Compiler directive should be specified (as per the $SET statement in the example program above).
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 and PL/I External Routines
    Describes support for nested COBOL programs and PL/I external routines, 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 and PL/I External Routines

The DB2 ECM supports nested COBOL programs and PL/I external routines, 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


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 on Windows using either the DB2START or NET START DB2 command depending on whether the database is local or remote. Start DB2 on UNIX using db2start.
  • If using DB2 LUW as a remote database server, start security services.
  • Specify a valid database in the project settings on the SQL page (Windows) or database name by setting the DB2(DB=databaseName) compiler directive (UNIX)

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.
  • DB2 ECM Preprocessor
    Describes the DB2 ECM preprocessor and how to set the COBOL compiler to use it.
  • 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.
  • Connecting to a DB2 Database
    Describes the methods you can use to connect to a DB2 database.
  • DB2 Compiler Directive
Parent topic: DB2 External Compiler Module
Related concepts
Invoking the DB2 ECM
Linking
Related reference
COBDB0006 Required DB software token could not be found.


DB2 ECM Preprocessor

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

Parent topic: Compiling


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 your Enterprise Developer Project
  1. Open your project properties and expand Micro Focus > Project Settings > COBOL > SQL Preprocessor.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL > SQL Preprocessor. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. Check Enable configuration specific settings and Use SQL Preprocessor.
  3. From the Preprocessor Type drop-down list, select HCO for DB2 LUW.
  4. Type the name of your database into the Value field of the DB setting.
    Note: If you leave the value for DB blank, the compiler uses the database specified by the value of the DB2DBDFT environment variable.
  5. Click Apply.

Alternatively, you can enter the preprocessor specification and options as additional directives:

  1. Open your project properties and expand Micro Focus > Project Settings > COBOL.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. Click in the Additional directives field and type:
    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.
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])] (Windows)

Or:

DB2[(DB==dbName [DB2dirOpts])] (UNIX)

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
Setting Compiler Directives for COBOL
User Directives File


Connecting to a DB2 Database

To compile a DB2 LUW program, you must first connect to a database. The database itself is specified by the DB2 ECM directive, DB. User credentials are also provided to the compiler by the DB2 ECM preprocessor. The login credentials used to connect to the database can vary depending on whether the database is local or remote, what DB2 compiler directive options have been specified, and what environment variables have been set.

The DB2 ECM checks for login credentials in one or more places and in a particular sequence, and attempts to connect using the credentials provided in each place until the connection succeeds.

PASS compiler directive option
Important: This is the preferred and recommended method on all platforms.

When you specify login credentials using PASS, they take precedence over credentials supplied by any other means. If the connection succeeds using the credentials provided, then compilation proceeds. PASS is required to connect to a remote DB2 database. If the connection fails using the credentials provided by PASS, the DB2 ECM next looks for the SQLPASS.TXT environment variable.

See PASS for details.

SQLPASS.TXT environment variable
Attention: This method is deprecated, and provided for backward compatibility only.

This applies to Windows environments (local development) only.

This option is used only when no credentials have been supplied using the PASS compiler directive option, or if the credentials supplied by PASS fail to enable the connection. If the connection succeeds, then compilation proceeds.

If the SQLPASS.TXT environment variable is not set, or if the connection fails using the credentials provided, the DB2 ECM next looks at the operating system credentials.

See SQLPASS.TXT environment variable for details.

Operating System credentials

Windows:

If you have not specified login credentials using the PASS compiler directive option, nor have you set the SQLPASS.TXT environment variable, or if either or both of those approaches yield unusable credentials, the DB2 ECM attempts to make the connection using your current Operating System credentials. This compilation attempt can succeed only if you are using a local database. If you are using a remote database, please consider using the PASS directive, which consistently works across all platforms.

If the connection fails using your Operating System credentials, the DB2 ECM prompts you for login credentials.

UNIX:

If you have not specified login credentials using the PASS compiler directive option, or if this approach yields unusable credentials, the DB2 ECM attempts to make the connection using your current Operating System credentials. This compilation attempt can succeed only if you are using a local database.

If you are using a remote database, or if the connection to a local database fails using your Operating System credentials, use the PASS compiler directive option. Be sure to provide usable credential specifications.

MFDAEMON prompt

This applies to Windows environments (local development) only.

If the DB2 ECM fails to connect to the database after exhausting all other methods of obtaining login credentials, or has failed in all previous attempts to connect to the database, it prompts you for credentials by invoking the SQL Logon dialog box:

The Micro Focus SQL Dialog Box
Note: The credentials supplied here are stored in the memory of your local machine and remain there until you reboot, or until you remove the information from memory by issuing the MFDAEMON CLOSE command at an Enterprise Developer command prompt.
Parent topic: Compiling
Related reference
PASS
SQLPASS.TXT environment variable (deprecated)


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

Restriction: This topic applies to UNIX environments (remote development) only.

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
  • Building DB2 Applications with Eclipse
Parent topic: DB2 External Compiler Module


Stand-alone DB2 Applications

Restriction: This topic applies to UNIX environments (remote development) only.

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

Restriction: This topic applies to UNIX environments (remote development) only.

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


Building DB2 Applications with Eclipse

Restriction: This topic applies to UNIX environments (remote development) only.

When you work with DB2 ECM applications, you need to build them with the NOLITLINK directive.

Your project might be using copybooks that are stored outside of your project directory - for example, copybooks as provided by IBM. In this case, before building your project, you need to ensure that the Eclipse project can locate the copybooks within the project directory as this is where it searches for them.

One way to do this is to create a symbolic link pointing to your project directory in the IBM DB2 installation directory. To create a symbolic link, you need to execute the following from the command line:

ln -s <db2_install_dir>/include/cobol_mf /home/myuser/myproject

Where:

  • <db2_install_dir> is the DB2 install directory. For example: /opt/IBM/db2/V9.5;
  • /home/myuser/myproject is the project directory on the server machine.
Parent topic: Building Applications
Related information
Setting Compiler Directives for COBOL


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 or in your project properties. For details, see the BIND DB2 compiler directive option topic and the Setting BIND and BINDDIR in your project section below.

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 or in your project properties. For details, see the BINDDIR DB2 compiler directive option topic and the Setting BIND and BINDDIR in your project section below.

Setting BIND and BINDDIR in your project
If you want to use BIND or BINDDIR when compiling from your Enterprise Developer, set one or both of these directives in your project properties on the SQL Preprocessor page. On the Setting grid, you can enter a specific directory for one or both. Alternatively, to set either to your defined build output directory, use the drop-down list associated with the directive to change its setting to <Enabled>. This instructs the IDE to automatically substitute the build directory when it generates the directive.
Note: When you clean a project, Enterprise Developer deletes all files in the build directory, including .bnd files.
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


Linking

Restriction: This topic applies to Windows environments (local development) only.

To link an application:

  1. Click Project > Properties for your current project.
  2. Click the COBOL Link tab.
  3. In the Link with libs field, type db2api.lib; then click OK.
    Note: The 64-bit version of DB2 LUW automatically installs both a 64- and 32-bit version of db2api.lib. If you have installed the 64-bit version of DB2 LUW but want to use the 32-bit version of db2api.lib instead of the 64-bit version, type the full path to and filename of the 32-bit version of db2api.lib into the Link with libs field before you click OK.
Parent topic: DB2 External Compiler Module
Related concepts
Compiling


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: HCO for DB2 LUW


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:

    Windows:

    Do one of the following

    • Add your installation's executable (bin) directory to the PATH statement
    • Copy the following DLLs to the directory from which you execute the stored procedure. You need to do this for DB2 to be able to execute a COBOL stored procedure:
      • cblrtsm.dll
      • cblviom.dll
      • mffh.dll
      • mfhcolib.dll
      • mfsqlsmf.dll

    In addition, see the IBM documentation for Building Micro Focus COBOL Routines on Windows.

    UNIX:

    See the IBM documentation for Building Micro Focus COBOL Routines 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 DLL (Windows) or module (UNIX) 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
Writing and Preparing Stored Procedures
Working with Stored Procedures


Executing the SQL Statement CALL

Use the CALL statement to execute each series of SQL statements in your application.

Example 1

Restriction: This topic applies to Windows environments (local development) only.

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

Restriction: This topic applies to Windows environments (local development) only.

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

Restriction: This topic applies to Windows environments (local development) only.

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

Restriction: This topic applies to Windows environments (local development) only.

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

Restriction: This topic applies to Windows environments (local development) only.

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

Restriction: This topic applies to Windows environments (local development) only.

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

Note: This topic applies to Windows environments (local development) only.

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.

Additionally, Micro Focus stored procedures must be built as a dynamic link library (DLL) when running under Windows DB2 LUW servers. The following embedded SQL statements are not allowed in Micro Focus stored procedures on any platform:
  • CONNECT
  • DISCONNECT
  • SET CONNECTION
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Defining Stored Procedures under DB2 LUW

A stored procedure is unusable until it is defined. Use the CREATE PROCEDURE command to do this. You can either use the DB2 command prompt or place the command in a program and compile and run it. If you use the DB2 command prompt, you first connect to the DB2 LUW Server where the stored procedure will be executed.

For example:

C:> db2 connect to sample

You can type in the command at the DB2 command prompt making sure you include continuation characters and command delimiters, or you can place the CREATE PROCEDURE in an ANSI text file. For example, if we placed the previous command in text file creproc.sql, the command that you would enter would be:

Windows:

C:> db2 -td; -vf creproc.sql

UNIX:

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 (UNIX only) 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:

On Windows platforms:

  1. Add the program you want to use as a stored procedure to an Enterprise Developer project.
  2. Set the project properties as follows:
    • If your program does not contain a $SET DB2(DB) statement, set this directive on the SQL Preprocessor page by selecting the HCO for DB2 LUW option for the Preprocessor Type field.
    • If you have 64-bit DB2 LUW installed, but you are building a 32-bit application, you need to update your project properties to specify the fully qualified path and filename of the 32-bit version of the db2api.lib file, which is a part of your DB2 installation. To do this, open the project properties, expand Micro Focus > Build Configuration > Link, click Additional Link Files, and add the path and filename to the Additional items to be linked field..
  3. Build the project.
  4. At a command prompt or using Windows Explorer, copy the generated .dll file from its output location (the default is projectpath\bin\x86\Debug) to the SQLLIB\FUNCTION subdirectory of your DB2 installation directory.
Note: If your program contains stored procedure CALL statements, you must specify the CALL_RESOLUTION DB2 directive to avoid an SQL0204 error.

On UNIX platforms:

  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.

On all platforms:

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


Host Compatibility Option (HCO)

Host Compatibility Option (HCO) is a set of tools that enable EBCDIC programs to work with DB2 LUW. Use these tools to offload DB2 for z/OS development and testing from a mainframe to a Windows or UNIX platform that uses IBM's DB2 LUW. You can then take these DB2 applications and use them with other Enterprise Developer features such as those in our IMS and CICS support. In addition, HCO can be used to re-host applications where the target run-time environment has changed. For example, you can use mainframe SQL syntax but replace character front ends with graphical interfaces.

Note: For information on configuring your system to use HCO, see Additional Software Requirements on Windows or Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components.
  • Creating a DB2 LUW Database for HCO
    Describes the requirements for creating a DB2 LUW database to use with COBOL applications written using a mainframe COBOL dialect.
  • HCO Tools
  • Product Specifications
  • Compiling and Run Time
  • Sample Programs
Parent topic: HCO for DB2 LUW
Related concepts
Additional Software Requirements on Windows
Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components


Creating a DB2 LUW Database for HCO

COBOL applications written using a mainframe COBOL dialect require that any DB2 LUW database accessed by such an application use an EBCDIC collating sequence. The HCO Create Database Tool enables you to create a compatible DB2 LUW database on a Windows or UNIX platform for access from a COBOL application coded using a mainframe COBOL dialect.

Note: The HCO Create Database tool provides seamless integration with mainframe COBOL-dialect applications that use SBCS (single-byte character sets) only, regardless of the platform. To create a database to be accessed from an application that uses DBCS (double-byte character sets), see the IBM documentation that covers database creation and appropriate EBCDIC collating sequences.

The Create Database Tool is available from the HCO for DB2 LUW user interface (Windows only) , or using the mfhco create (Windows) or cobmfhco create (UNIX) . See the mfhco and cobmfhco create commands and To create a database topics for additional details.

Set MFCODESET to a country code

Before using the Create Database tool to create a database, set the MFCODESET environment variable to an appropriate country code value listed on the Supported Country Codes topic. A correct setting of MFCODESET ensures that the database EBCDIC collating sequence matches the CHARSET EBCDIC behavior of your application. The correct code for a given country could vary depending on your platform and whether or the database requires Euro (€) character translation enablement.

Windows platforms
Create DB2 LUW databases on Windows platforms using code page 1252 for both Euro and non-Euro character translations. To determine the country code, use the first table listed on the Supported Country Codes topic.
UNIX platforms
On UNIX platforms, create databases requiring Euro character translation enablement using code page 923, and databases that do not require Euro character translation enablement using code page 819. To determine the country code, use the second table listed on the Supported Country Codes topic.
Important: IBM does not always support the creation of a UNIX database from a Windows environment when using code page 923. In light of this, we recommend that you create UNIX DB2 LUW databases that do require Euro enablement, on a UNIX machine using the UNIX cobmfhco create command-line tool.

Determine the code page

You can determine which code page was used to create an existing database by connecting to the database, starting a DB2 command prompt, and issuing a get db config command. See the IBM GET DATABASE CONFIGURATION command documentation for details.

The following is an example of get db config output showing a Database code page of 1252:

C:\Program Files\IBM\SQLLIB\BIN>db2 get db config
       Database Configuration for Database
 Database configuration release level                    = 0x1400
 Database release level                                  = 0x1400

 Database territory                                      = En_US
 Database code page                                      = 1252
 Database code set                                       = 1252
 Database country/region code                            = 1
 Database collating sequence                             = UNIQUE
 Alternate collating sequence              (ALT_COLLATE) =
 Number compatibility                                    = OFF
 Varchar2 compatibility                                  = OFF
Parent topic: Host Compatibility Option (HCO)
Related concepts
Create Database Tool
Supported Country Codes
Related tasks
To create a database
Related reference
mfhco and cobmfhco create commands
Input, output and display environment variables


HCO Tools

Included in Host Compatibility Option are tools to:

  • Create databases with EBCDIC collating sequences
  • Process SQL DDL statements so that DB2 table definitions stored on the mainframe can be downloaded to the PC and used to create tables without having to be modified
  • Generate copybooks for tables (DCLGEN)
  • Export data in a variety of formats
  • Import data in a variety of formats
  • Bind or rebind packages

These tools are available from the HCO for DB2 LUW user interface (applies to Windows environments only), and the command line. See To start HCO tools and Command Line reference for details.

Before you start, be sure you have installed the prerequisite software. For more information, see Additional Software Requirements on Windows or Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components (UNIX).

Note: You can use IBM's DB2 Control Center and/or the DB2 Setup tool to perform other HCO functions such as cataloging databases and servers, executing SQL, and generating aliases.
  • Create Database Tool
  • DDL Processor
  • DCLGEN Tool
  • Export Data Tool
  • Import Data Tool
  • BindAll Packages Tool
Parent topic: Host Compatibility Option (HCO)
Related concepts
BindAll Packages Tool
Create Database Tool
DDL Processor
DCLGEN Tool
Export Data Tool
Import Data Tool
Related tasks
To start HCO tools
Related reference
Command Line Reference


Create Database Tool

Databases created on Windows and UNIX platforms store data in ANSI. To use these databases with EBCDIC-enabled subsystems such as IMS and CICS, you must have a database created with an alternative collating sequence.

You can run the Create Database tool from the HCO for DB2 LUW user interface (Windows only) , or using the mfhco create (Windows) or cobmfhco create (UNIX) command.

Note: If you were to use any of the IBM tools to create the database, all data would be returned to your application in ANSI collating sequence. IBM does provide some examples of how to create databases with alternative collating sequences, but the EBCDIC to ANSI translation that IBM uses might be different from the translation used by Enterprise Developer. Therefore, we strongly recommend that you use the Create Database tool to create the database.
Parent topic: HCO Tools
Related concepts
Creating a DB2 LUW Database for HCO
HCO Tools
Related tasks
To create a database
Related reference
mfhco and cobmfhco create commands
Create Database tab
Related information
Log tab


DDL Processor

The DDL Processor processes SQL DDL statements using one of the following methods:
  • Transforming DB2 for z/OS syntax DDL statements to DB2 LUW format
  • Processing the DDL statements unchanged

You can run the DDL Processor from the HCO for DB2 LUW user interface (Windows only) , or using the mfhco ddl (Windows) or cobmfhco ddl (UNIX) command.

Downloading Source DDL

DDL source files on the mainframe should be downloaded and converted to standard ANSI text files. The maximum input length per record accepted by the DDL processor is 80 bytes.

Note: If non-blank characters exist in columns 73 through 80, you must change maximum column to process to be 72 or they are treated as part of the DDL source statement. See mfhco and cobmfhco ddl commands for more details.

Downloading Data to Load Tables

There are two tools in Host Compatibility Option to help you load test data exported from tables located on the mainframe:

  • The Export Data tool
  • The Import Data tool

Using the DDL Processor to Load Data

You can also use the DDL processor to load or update data into tables by placing one or more of the following DML statements in the same file as DDL statements:

  • INSERT
  • UPDATE
  • DELETE
  • COMMIT

This is a convenient way to load test data into tables.

Statements cannot contain any host variables and you cannot use quotes ( " ) around literals. You must use apostrophes ( ' ). You should also issue a COMMIT before you try to insert data into a table if it was created within the same unit of work. For example:

-- Create Available Product table
 CREATE TABLE MF.PRODUCT
  (PROD_ID  CHAR(04)    NOT NULL
  ,PROD_DESC  CHAR(40)    NOT NULL WITH DEFAULT
  ,VERSION  CHAR(6)    NOT NULL WITH DEFAULT
  ,PRIMARY KEY (PROD_ID) )
  IN DSB8G210.CISC0001
 ;
 COMMIT
 ;

 -- Sample data for Product table

 INSERT INTO MF.PRODUCT (PROD_ID ,PROD_DESC ,VERSION )
 VALUES ('SR02' ,'Host Compatibility Option ' ,'2.0.01' )
Parent topic: HCO Tools
Related concepts
DB2 LUW Syntax DDL
Product Specifications
Import Data Tool
Export Data Tool
HCO Tools
Related tasks
To process SQL DDL statements
Related reference
mfhco and cobmfhco ddl commands
DDL Tool tab
Related information
Log tab


DCLGEN Tool

Host Compatibility Option provides a tool to generate DDL for existing SQL tables or copybooks for tables in COBOL, PL/I or C syntax.

You can run the DCLGEN tool from the HCO for DB2 LUW user interface (Windows only) , or using the mfhco dclgen (Windows) or cobmfhco dclgen (UNIX) command.

Use Case Scenarios

Scenario 1
This example creates the file ITEMS.CPY from table DEMO.ITEMS in database DB2DEMO and prefixes all COBOL field names with the table name.

The DECLARE TABLE part of copybook file would look something like this:

************************************************************
*  MFHCODCL OPTIONS:
*  DATABASE : DB2DEMO
*  SCHEMA : DEMO
*  PREFIX : TABLE NAME
************************************************************
  EXEC SQL DECLARE DEMO.ITEMS TABLE
  ( ORD_NO    INTEGER   NOT NULL
  ,ITEM_NO    SMALLINT  NOT NULL
  ,PROD_ID    CHAR(4)
  ,QTY_ORDERED   SMALLINT  NOT NULL WITH DEFAULT
  ,QTY_SHIPPED   SMALLINT  NOT NULL WITH DEFAULT
  ,AMT_EACH    DECIMAL(7, 2) NOT NULL WITH DEFAULT
  ,DATE_ENTERED   TIMESTAMP  NOT NULL WITH DEFAULT
  ,DATE_SHIPPED   DATE
  ,ITEM_NOTES   VARCHAR(560)
  ) END-EXEC.

The COBOL DECLARATION part of copybook file would look something like this:

************************************************************
* COBOL DECLARATION FOR TABLE DEMO.ITEMS
************************************************************
 01 DCLITEMS.
  10 ITEMS-ORD-NO           PIC S9(09) COMP.
  10 ITEMS-ITEM-NO          PIC S9(04) COMP.
  10 ITEMS-PROD-ID          PIC X(4).
  10 ITEMS-QTY-ORDERED      PIC S9(04) COMP.
  10 ITEMS-QTY-SHIPPED      PIC S9(04) COMP.
  10 ITEMS-AMT-EACH         PIC S9(05)v9(02) COMP-3.
  10 ITEMS-DATE-ENTERED     PIC X(26).
  10 ITEMS-DATE-SHIPPED     PIC X(10).
  10 ITEMS-ITEM-NOTES.
   49 ITEMS-ITEM-NOTES-LEN  PIC S9(04) COMP.
   49 ITEMS-ITEM-NOTES-TEXT PIC X(560).
************************************************************
* COBOL INDICATOR VARIABLES FOR TABLE
************************************************************
 01 DCLITEMS-NULL.
  10 ITEMS-PROD-ID-NULL      PIC S9(04) COMP.
  10 ITEMS-DATE-SHIPPED-NULL PIC S9(04) COMP.
  10 ITEMS-ITEM-NOTES-NULL   PIC S9(04)COMP.
************************************************************
* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9
************************************************************
Scenario 2
In this example, change the prefix to a user value of "HV" instead of using the table name as prefix and generate indicator values with a suffix of IND.

The COBOL DECLARATION part of copybook file would look something like this:

************************************************************
* COBOL DECLARATION FOR TABLE DEMO.ITEMS
************************************************************
 01 DCLITEMS.
  10 HV-ORD-NO           PIC S9(09) COMP.
  10 HV-ITEM-NO          PIC S9(04) COMP.
  10 HV-PROD-ID          PIC X(4).
  10 HV-QTY-ORDERED      PIC S9(04) COMP.
  10 HV-QTY-SHIPPED      PIC S9(04) COMP.
  10 HV-AMT-EACH         PIC S9(05)v9(02) COMP-3.
  10 HV-DATE-ENTERED     PIC X(26).
  10 HV-DATE-SHIPPED     PIC X(10).
  10 HV-ITEM-NOTES.
   49 HV-ITEM-NOTES-LEN  PIC S9(04) COMP.
   49 HV-ITEM-NOTES-TEXT PIC X(560).
************************************************************
* COBOL INDICATOR VARIABLES FOR TABLE
************************************************************
 01 DCLITEMS-IND.
  10 HV-PROD-ID-IND      PIC S9(04) COMP.
  10 HV-DATE-SHIPPED-IND PIC S9(04) COMP.
  10 HV-ITEM-NOTES-IND   PIC S9(04) COMP.
************************************************************
* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9
************************************************************
Scenario 3
In this example, change the prefix to a user value of "FIELD" and generate numbered fields instead of column names. Use configuration default instead of specifying CBL for language.

The COBOL DECLARATION part of copybook file would look something like this:

************************************************************
* COBOL DECLARATION FOR TABLE DEMO.ITEMS
************************************************************
 01 DCLITEMS.
  10 FIELD-001       PIC S9(09) COMP.
  10 FIELD-002       PIC S9(04) COMP.
  10 FIELD-003       PIC X(4).
  10 FIELD-004       PIC S9(04) COMP.
  10 FIELD-005       PIC S9(04) COMP.
  10 FIELD-006       PIC S9(05)v9(02) COMP-3.
  10 FIELD-007       PIC X(26).
  10 FIELD-008       PIC X(10).
  10 FIELD-009.
   49 FIELD-009-LEN  PIC S9(04) COMP.
   49 FIELD-009-TEXT PIC X(560).
************************************************************
* COBOL INDICATOR VARIABLES FOR TABLE
************************************************************
 01 DCLITEMS-NULL.
  10 FIELD-003-NULL PIC S9(04) COMP.
  10 FIELD-008-NULL PIC S9(04) COMP.
  10 FIELD-009-NULL PIC S9(04) COMP.
************************************************************
* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9
************************************************************
Scenario 4
In this example, create the file ITEMS.PLI from table DEMO.ITEMS in database DB2DEMO and prefix all field names with the table name. Language is PL/I.

The DECLARE TABLE part of copybook file would look something like this:

/*-------------------------------------------------------*/
/*  MFHCODCL OPTIONS:                                    */
/*   DATABASE : DB2DEMO                                  */
/*   SCHEMA : DEMO                                       */
/*   PREFIX : TABLE NAME                                 */
/*-------------------------------------------------------*/
 EXEC SQL DECLARE DEMO.ITEMS TABLE
 ( ORD_NO    INTEGER   NOT NULL,
  ITEM_NO    SMALLINT  NOT NULL,
  PROD_ID    CHAR(4),
  QTY_ORDERED   SMALLINT  NOT NULL WITH DEFAULT,
  QTY_SHIPPED   SMALLINT  NOT NULL WITH DEFAULT,
  AMT_EACH    DECIMAL(7, 2) NOT NULL WITH DEFAULT,
  DATE_ENTERED   TIMESTAMP  NOT NULL WITH DEFAULT,
  DATE_SHIPPED DATE,  ITEM_NOTES   VARCHAR(560)
 );

The PL/I DECLARATION part of copybook file would look something like this:

/*-------------------------------------------------------*/
/*  PL/I DECLARATION FOR TABLE DEMO.ITEMS                */
/*-------------------------------------------------------*/
DECLARE
1 DCLITEMS,
 5 ITEMS_ORD_NO     BIN FIXED(31),
 5 ITEMS_ITEM_NO    BIN FIXED(15),
 5 ITEMS_PROD_ID     CHAR(4),
 5 ITEMS_QTY_ORDERED    BIN FIXED(15),
 5 ITEMS_QTY_SHIPPED    BIN FIXED(15),
 5 ITEMS_AMT_EACH     DEC FIXED(5,2),
 5 ITEMS_DATE_ENTERED    CHAR(26),
 5 ITEMS_DATE_SHIPPED    CHAR(10),
 5 ITEMS_ITEM_NOTES    CHAR(560) VAR;
/*-------------------------------------------------------*/
/*  PL/I INDICATOR VARIABLES FOR TABLE                   */
/*-------------------------------------------------------*/
DECLARE 1 DCLITEMS_NULL,
 5 ITEMS_PROD_ID_NULL    BIN FIXED(15),
 5 ITEMS_DATE_SHIPPED_NULL   BIN FIXED(15),
 5 ITEMS_ITEM_NOTES_NULL   BIN FIXED(15);
/*-------------------------------------------------------*/
/*  THE NO. OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9*/
/*-------------------------------------------------------*/
Scenario 5
This example creates the file ITEMS.C from table DEMO.ITEMS in database DB2DEMO and prefixes all field names with the table name. Language is C.

The copybook file would look something like this:

/*-------------------------------------------------------*/
/*  MFHCODCL OPTIONS:                                    */
/*   DATABASE : DB2DEMO                                  */
/*   SCHEMA : DEMO                                       */
/*   PREFIX : TABLE NAME                                 */
/*  C HOST VARIABLES FOR TABLE DEMO.ITEMS                */
/*-------------------------------------------------------*/
EXEC SQL BEGIN DECLARE SECTION;
struct dclitems
{
 long   items_ord_no;
 short   items_item_no;
 char   items_prod_id[4];
 short   items_qty_ordered;
 short   items_qty_shipped;
 double  items_amt_each;
 char   items_date_entered[26];
 char   items_date_shipped[10];
 struct {
    short len
    char data[560];
   }  items_item_notes;
/*-------------------------------------------------------*/
/*   C INDICATOR VARIABLES FOR TABLE                     */
/*-------------------------------------------------------*/
 short   items_prod_id_null;
 short   items_date_shipped_null;
 short   items_item_notes_null;
 };
EXEC SQL END DECLARE SECTION;
/*-------------------------------------------------------*/
/*  THE NO. OF COLUMNS DESCRIBED BY THIS DECLARATION IS 9*/
/*-------------------------------------------------------*/
Scenario 6
In this scenario, generate the EMP_PHOTO table without a DECLARE TABLE section, generate all numeric variables as COMP-5 rather than COMP, and generate LOB variables as LOB SQL TYPEs rather than generating them as the default of LOB-LOCATOR.

The DECLARE TABLE part of copybook file would look something like this:

/*----------------------------------------------------------*/
/* MFHCODCL OPTIONS:                                        */
/*     DATABASE : SAMPLE                                    */
/*     SCHEMA   : TESTER                                    */
/*     PREFIX   : TABLE NAME                                */
/*----------------------------------------------------------*/
/* COBOL DECLARATION FOR TABLE                              */
/*----------------------------------------------------------*/
 01  DCLEMP-PHOTO.
     10 EMP-PHOTO-EMPNO                  PIC X(6).
     10 EMP-PHOTO-PHOTO-FORMAT.
        49 EMP-PHOTO-PHOTO-FORMAT-LEN    PIC S9(04)  COMP-5.
        49 EMP-PHOTO-PHOTO-FORMAT-TEXT   PIC X(10).
     10 EMP-PHOTO-PICTURE                SQL TYPE IS
                                         BLOB(100K).
/*----------------------------------------------------------*/
/* COBOL INDICATOR VARIABLES FOR TABLE                      */
/*----------------------------------------------------------*/
 01  DCLEMP-PHOTO-NULL.
     10 EMP-PHOTO-PICTURE-NULL           PIC S9(04)  COMP-5.
/*----------------------------------------------------------*/
/* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 3 */
/*----------------------------------------------------------*/
Parent topic: HCO Tools
Related concepts
HCO Tools
Related tasks
To create a DCLGEN
Related reference
mfhco and cobmfhco dclgen commands
DCLGEN tab
Copybook tab


Export Data Tool

Once you have created SQL tables, you need data to test your applications. You may also need to distribute data to other Windows or UNIX machines or to send data back to the mainframe. IBM and other vendors provide products to do this. However, if you have not installed one of these products, moving data around can be a problem.

Host Compatibility Option supplies you with an Export Data tool that you can combine with DB2 Connect, IBM's DRDA gateway, giving you a relatively inexpensive way of moving data between mainframe databases and Windows and UNIX machines.

You can run the Export Data tool from the HCO for DB2 LUW user interface (Windows only) , or using the mfhco export (Windows) or cobmfhco export (UNIX) command.

The Export Data tool has the following limitations:

  • All columns and rows in a table are exported. There is no ability in this tool to limit the data or rows exported.
  • Export formats WSF (Lotus worksheet) and IXF (mainframe) are not supported
  • IXF and DEL files are exported using IBM's EXPORT application programming interface. Some options of the API are not supported. See IBM's DB2 LUW Command Reference for list of all available options.
  • DSNTIAUL is exported using a SELECT statement, so large tables may take a while to process
  • LOB data types are not supported in DSNTIAUL format
  • LOB data types are generated as part of file in IXF and DEL formats. See IBM's DB2 LUW Command Reference for other limitations.

If you need to restrict rows and/or columns exported, you can use the IBM command line processor, DB2, or the IBM Control Center to export data. See IBM's DB2 LUW Command Reference for more details on how to use the IBM Control Center.

Parent topic: HCO Tools
Related concepts
DDL Processor
HCO Tools
Related tasks
To export data
Related reference
mfhco and cobmfhco export commands
Export tab
Related information
Log tab


Import Data Tool

The Import Data tool is designed for programmers who need sample data for testing. This tool is not intended to be used to load large quantities of data. If you want to load large quantities of data, you should contact IBM or other third-party vendors who provide a number of products that can handle this better than Host Compatibility Option. You should take care in using this tool to ensure that the database does not become unusable. You should back up your data regularly to provide a means of recovering from loss of data.

You can run the Import Data tool from the HCO for DB2 LUW user interface (Windows only) , or using the mfhco import (Windows) or cobmfhco import (UNIX) command.

The Import Data tool has the following limitations:

  • Data for all columns in a table must be in import file. There is no ability in this tool to limit the column data being inserted.
  • Import formats WSF (Lotus worksheet) and IXF (mainframe) are not supported.
  • IXF and DEL files are imported using IBM's IMPORT application programming interface. Some options of the API are not supported. See IBM's DB2 LUW Command Reference for list of all available options.
  • DSNTIAUL files are converted to ANSI delimited format and then use the DEL IMPORT API.
  • LOB data types are not supported in DSNTIAUL format.
  • LOB data types generated as part of file in IXF and DEL formats. See IBM's DB2 LUW Command Reference for other limitations.
  • An LOB must be 32K or smaller, and the information contained in it must be in the same file as other data being imported.
Parent topic: HCO Tools
Related concepts
DDL Processor
HCO Tools
Related tasks
To import data
Related reference
mfhco and cobmfhco import commands
Import tab
Related information
Log tab


BindAll Packages Tool

Bind or rebind all packages (.bnd files) found in the current directory using the bind options specified.

You can run the BindAll Packages tool using the mfhco dclgen (Windows) or cobmfhco dclgen (UNIX) command.

The BindAll Packages tool can bind using only these options:

  • Collection ID
  • Qualifier
  • Datetime
  • Isolation level
  • Row blocking
  • SqlWarn

To bind or rebind with any other options, use the IBM BIND command. See your IBM documentation for details.

Parent topic: HCO Tools
Related concepts
HCO Tools
Related reference
mfhco and cobmfhco bindall commands


Product Specifications

DB2 LUW is basically compatible with DB2 for z/OS, with some exceptions in DML syntax and functions supported and certain DDL statements that are hardware/operating system specific. Host Compatibility Option tries to address some of the main areas of incompatibility where possible by converting DB2 for z/OS SQL statements to supported DB2 LUW syntax.

Additional compatibility is possible when using DB2 for z/OS database servers via the DB2 Connect product.

For more information on the differences in syntax supported by the various versions of DB2, see IBM's SQL Reference for Cross-Platform Development.

  • HCO Functions
  • DDL DB2 for z/OS Syntax Supported
  • DB2 LUW Syntax DDL
  • Features Supported by DB2 LUW
  • Features Not Supported by DB2 LUW
Parent topic: Host Compatibility Option (HCO)
Related concepts
DDL Processor
DDL Processing


HCO Functions

Host Compatibility Option provides the following functions:

  • Support of programs checked with CHARSET(EBCDIC)
  • Support of DB2 for z/OS syntax DDL statements in programs and via a batch utility
  • SQLCODE map function to translate SQLCODEs automatically from DB2 LUW value to a new, designated value
  • A utility to do DCLGENs to produce INCLUDE COBOL copybooks of tables
  • A DSNTIAR subroutine to translate SQLCODEs into expanded SQL error messages
  • Quotes can be used as literals within SQL statements
  • Dashes can be used within cursor definitions
  • Support of the syntax
    SET host-variable = SPECIAL REGISTER
  • Support of DECLARE TABLE statements
  • Support of host variables with data structures (COBOL level numbers 01 through 48)
  • Ability to use COMP data items for integer and small integer instead of the INTEL COMP-5 format
  • Removal of the need to identify all host variables in Working-Storage via BEGIN DECLARE SECTION and END DECLARE SECTION statements
  • Configurable CONCAT character ( | )
  • Support of the NOT OPERATOR (¬) within queries
  • Insertion of missing colon in fields when the SQL statement parameter must be a host variable
  • Support of NOFOR compile option which allows updateable cursors to be defined without using the FOR UPDATE clause
  • Support for alternate special register names, CURRENT_DATE, CURRENT_TIME, and CURRENT_TIMESTAMP
  • Support for the DECLARE hostVariableName FOR BIT DATA statement
Parent topic: Product Specifications


DDL DB2 for z/OS Syntax Supported

As stated previously, the Host Compatibility Option pre-processor and DDL processor are designed to handle DDL statements that use DB2 for z/OS syntax. Functions can be processed in one of the following ways:

  • With no changes
  • Changed to comments as their syntax is not supported under DB2 LUW
  • With only slight modifications to remove unsupported options

Sometimes it is better to perform the function manually.

  • Functions Processed Unchanged
  • Functions Changed to Comments
  • Functions That May Be Modified
Parent topic: Product Specifications


Functions Processed Unchanged

The following is a list of functions that are not modified or changed since they are supported by DB2 LUW V7.2 or later:

  • COMMENT
  • CREATE ALIAS
  • CREATE VIEW
  • CREATE SYNONYM
  • GRANT
  • REVOKE
  • DROP TABLE
  • DROP INDEX
  • DROP VIEW
  • DROP ALIAS
  • DROP SYNONYM
  • SET
Parent topic: DDL DB2 for z/OS Syntax Supported


Functions Changed to Comments

DB2 LUW does not use STOGROUP when creating databases and tables. Therefore, this syntax is changed to comments. Some syntax such as TABLESPACE is supported by DB2 LUW but the usage is machine specific depending on the type of DB2 server being used so this syntax is also removed. Other functions, such as DROP DATABASE can be done using other DDL Processor options.

The following is a list of functions that are changed to comments:

  • ALTER TABLESPACE
  • ALTER INDEX
  • ALTER STOGROUP
  • CREATE DATABASE
  • CREATE STOGROUP
  • CREATE TABLESPACE
  • DROP DATABASE
  • DROP STOGROUP
  • DROP TABLESPACE
  • EXPLAIN
Parent topic: DDL DB2 for z/OS Syntax Supported


Functions That May Be Modified

Host Compatibility Option auto-senses which SQL engine it is running with. In addition, certain options such as FIELDPROC are not supported under DB2 LUW. Consequently, all columns defined with this option must be modified. The following is a list of functions that are supported and modifications are made to statements as needed to run under DB2 LUW:

  • ALTER TABLE
  • CREATE TABLE
  • CREATE INDEX

For example, the ALTER TABLE statement has the following syntax and options:

ALTER TABLE table-name
    ADD column-name data-type FIELDPROC
    (program-name or constant)
    ADD column-name data-type NOT NULL WITH DEFAULT VALIDPROC
      program or NULL
    AUDIT NONE or CHANGES or ALL
    PRIMARY KEY ( column-name )
    FOREIGN KEY constraint-name ( column-name )
    REFERENCES table-name ON DELETE
    RESTRICT or CASCADE or SET NULL
    DROP PRIMARY KEY
    DROP FOREIGN KEY constraint-name

The options FIELDPROC, VALIDPROC and AUDIT are not supported by DB2 LUW and would be removed from the statement. The rest of the statement is supported unchanged.

Similarly, the CREATE INDEX statement has the following syntax and options:

CREATE unique INDEX index-name
ON table-name
    ( column-name ASC or DESC )
    USING VCAT catalog-name
    USING STOGROUP stogroup-name
    PRIQTY integer SECQTY integer
    ERASE no or yes
    FREEPAGE integer
    PCTFREE integer
    CLUSTER ( PART integer VALUES (constant )
    or using-block or free-block )
    SUBPAGES 1 or 2 or 4 or 8 or 16
    BUFFERPOOL BP0 or BP1 or BP2
    CLOSE yes or no
    DSETPASS password

The options USING VCAT, USING STOGROUP, FREEPAGE, PCTFREE, CLUSTER, SUBPAGES, BUFFERPOOL, CLOSE and DSETPASS are not supported under DB2 LUW and therefore will be removed from the command that is passed to DB2 LUW.

In the CREATE TABLE statement, the syntax and options are as follows:

CREATE TABLE table-name
     ( column-definition data-type FIELDPROC
    program-name or constants
    , column-definition data-type NOT NULL
    , column-definition data-type NOT NULL WITH DEFAULT
    , PRIMARY KEY (column-name)
    , FOREIGN KEY constraint-name ( column-name )
         REFERENCES table-name
         ON DELETE RESTRICT or CASCADE or SET NULL
    LIKE table-name or view-name )
    IN DATABASE database-name
    IN database-name.tablespace-name
    EDITPROC program-name
    VALIDPROC program-name
    AUDIT NONE or CHANGES or ALL

The options FIELDPROC, LIKE, IN DATABASE, EDITPROC and VALIDPROC are not supported by DB2 LUW.

Parent topic: DDL DB2 for z/OS Syntax Supported


DB2 LUW Syntax DDL

HCO can also process DDL statements in DB2 LUW syntax without modifying the statements.

Parent topic: Product Specifications
Related concepts
DDL Processor


Features Supported by DB2 LUW

DB2 LUW supports a number of DB2 for z/OS functions, scalars and special registers.

  • Column Functions and Scalars
  • Special Registers
Parent topic: Product Specifications


Column Functions and Scalars

DB2 LUW supports Date and Time arithmetic and the following Scalar and Column functions:

  • AVG
  • COUNT
  • MAX
  • MIN
  • SUM
  • CHAR
  • DATE
  • DAY
  • DAYS
  • DECIMAL
  • FLOAT
  • INTEGER
  • HOUR
  • LENGTH
  • MICROSECOND
  • MINUTE
  • SECOND
  • SUBSTR
  • TIME
  • TIMESTAMP
  • YEAR
  • CONCAT or the concatenation operator (||)
  • VALUE
  • DIGITS
  • HEX
Parent topic: Features Supported by DB2 LUW


Special Registers

DB2 LUW supports the following special registers:

  • USER
  • CURRENT DATE
  • CURRENT DEGREE
  • CURRENT EXPLAIN MODE
  • CURRENT EXPLAIN SNAPSHOT
  • CURRENT FUNCTION PATH
  • CURRENT NODE
  • CURRENT PATH
  • CURRENT QUERY OPTIMIZATION
  • CURRENT SERVER
  • CURRENT TIME
  • CURRENT TIMESTAMP
  • CURRENT TIMEZONE
  • CURRENT SQLID

See your DB2 LUW SQL Reference for details on any additional special registers that may be supported.

Parent topic: Features Supported by DB2 LUW


Features Not Supported by DB2 LUW

DB2 LUW is not completely DML-compatible with DB2 for z/OS.

  • Special Registers
  • Other Functions
Parent topic: Product Specifications


Special Registers

DB2 LUW does not support the following special registers:

  • CURRENT LC_TYPE
  • CURRENT OPTIMIZATION HINT
  • CURRENT PRECISION
  • CURRENT PACKAGESET
  • CURRENT RULES

You can set the current packageset but IBM has not implemented this as a special register.

Parent topic: Features Not Supported by DB2 LUW


Other Functions

DB2 LUW does not support the following statements:

  • ALLOCATE CURSOR
  • CREATE AUXILIARY TABLE
  • DECLARE
  • DESCRIBE CURSOR
  • DESCRIBE PROCEDURE
  • HOLD LOCATOR
  • LABEL ON
  • SET SPECIAL REGISTER where the register is not supported by DB2 LUW

Some SQL syntax especially dealing with stored procedures is supported by DB2 LUW via other languages such as C++ or JAVA but has not been implemented using COBOL.

Parent topic: Features Not Supported by DB2 LUW


Compiling and Run Time

  • Compiling DB2 Programs with HCO
  • Run-time Services
Parent topic: Host Compatibility Option (HCO)


Compiling DB2 Programs with HCO

The DB2 External Compiler Module allows programs checked with CHARSET(EBCDIC) directive to access SQL tables using DB2 LUW. The DB2 ECM generates code to convert all character data (columns defined as CHAR or VARCHAR) from EBCDIC to ANSI before storing it in DB2 LUW tables and conversely converts it from ANSI to EBCDIC on all retrievals from DB2 LUW tables.

This means that other products such as Microsoft Excel can still be used to access data stored in the tables.

Note: If your application contains character columns defined as FOR BIT DATA, and the data stored in the columns is not ANSI, you must define the host variable with the DECLARE hostVariableName FOR BIT DATA statement. Otherwise, the results are unpredictable.
  • DDL Processing
  • Invoking the DB2 ECM
  • Error Messages When Compiling Program
Parent topic: Compiling and Run Time


DDL Processing

The DB2 ECM has the ability to handle DB2 syntax DDL statements within programs. DDL statements are converted automatically to DB2 LUW syntax.

Parent topic: Compiling DB2 Programs with HCO
Related concepts
Product Specifications


Invoking the DB2 ECM

When you compile your programs, the DB2 ECM must be invoked to add the additional code needed to do the ANSI to EBCDIC translations as well as translate the EXEC SQL statements into database API calls.

Parent topic: Compiling DB2 Programs with HCO
Related concepts
Compiling
Related reference
DB2 Compiler Directive Options


Error Messages When Compiling Program

There are two significant differences when using DB2 LUW versus mainframe DB2. The first is that you have to connect to the database before you can compile a program. With mainframe DB2 you can pre-compile a program without DB2 being active. The second major difference is that all columns and tables referenced in the program must be created in the database before a program can be compiled whereas with mainframe DB2 they don't have to be. In both cases, the mainframe DB2 pre-compiler uses the DECLARE TABLE information in an SQL INCLUDE copybook to determine valid syntax as opposed to DB2 LUW which uses DB2 system catalog information to validate statements. In either case, a SQL Error could result using DB2 DB2 LUW is basically compatible with DB2 for z/OS, with some exceptions in DML syntax and functions supported and certain DDL statements that are hardware/operating system specific. Host Compatibility Option tries to address some of the main areas of incompatibility where possible by converting DB2 for z/OS SQL statements to supported DB2 LUW syntax. .

In addition, if invalid SQL syntax is encountered while compiling your program, a SQL error is also generated for each statement in error. The text that is associated with the SQL error is displayed using the following format:

DB0100e SQLnnnnnn error-text

Where DB indicates error resulted from DB2 ECM (the error number is always 0100); e is the error severity, and SQLnnnnnn is the SQL error code (nnnnnn may vary between 2 and 6 characters).

Parent topic: Compiling DB2 Programs with HCO


Run-time Services

In addition to the tools described in earlier topics, Host Compatibility Option provides other tools that are only invoked when you run or debug your SQL program. Such run-time tools include the following:

  • MFHCOCDS - A routine to re-map SQLCODEs from one value to another
  • DSNTIAR and DSNTIAC- Routines to return text messages for a SQLCODE
  • MFHCOEBC - A routine that converts character data between ANSI and EBCDIC and

All of these tools are stored in the file mfhcolib.dll. You do not need to copy this file to any other location if you are running under this COBOL development system.

  • MFHCOCDS Tool
  • DSNTIAR and DSNTIAC
    Converts SQL return codes to character-string messages.
  • MFHCOEBC
Parent topic: Compiling and Run Time


MFHCOCDS Tool

DB2 LUW generally returns the same SQLCODE as DB2 for common errors such as no more rows in table or duplicate index entry. MFHCOCDS is a mapping facility provided to support the translation of DB2 LUW SQLCODE's to their DB2 equivalent for special situations where the mappings are not the same. To enable this facility, create a line sequential text file named mfhcocds.sql in the same directory where your compiled application resides. In the mfhcocds.sql file, identify the DB2 LUW SQL code to be replaced and its equivalent DB2 SQL code to be returned to the application program. Use the following format:

DB2LUWcode DB2SQLcode

For example, if you want to change the SQLCODE -30080 (communication error) to -902 (system error), place the following line of text in the file:

-30080 -902
  • Dynamic Bind Utility
Parent topic: Run-time Services


Dynamic Bind Utility

The Dynamic Bind Utility enables you to bind dynamically programs that get -805 or -818 SQL errors.

A good example of how you can take advantage of this utility is if your organization has a number of common SQL routines that they share but they use these routines against multiple databases. Someone within the organization, usually the DBA, would have to bind these common modules against each database for them to be used. Another option would be to compile each of these routines against each database. If someone changed one of the common routines, the bind/compile process would have to be repeated for each database!

Host Compatibility Option offers a third option. When you compile an SQL routine, Host Compatibility Option passes additional information to the MFHCOCDS routine when an SQL error occurs. If a -805 or -818 error occurs, Host Compatibility Option tries to find the bind file associated with the routine in error and then bind the package against the database to which the program is currently connected. A message is then displayed reporting whether the bind was successful. The original SQL error is returned to your program so that you need to restart the program or, if you are animating the program, re-execute the SQL statement that originally failed.

To implement this feature, you need to:

  • Re-compile all common SQL routines with the DB2 directive BIND

The BIND directive creates a bind file for each common routine. When the -805 or -818 SQL error occurs, Host Compatibility Option looks for the bind file using the following search sequence:

  1. Current folder
  2. Folder specified by the HCOBND environment variable

To take advantage of the dynamic bind utility, set the HCO_AUTOREBIND environment variable as follows:

Windows:
SET HCO_AUTOREBIND=ON
UNIX:
HCO_AUTOREBIND=ON
export HCO_AUTOREBIND

You can still use the HCO BIND tool to quickly re-bind all applications.

Parent topic: MFHCOCDS Tool


MFHCOEBC

This routine converts each character column accessed by your program from ANSI to EBCDIC.

Host Compatibility Option automatically detects whether your environment supports DBCS data. If so, it examines all character strings for SISO characters.

Parent topic: Run-time Services


Sample Programs

Enterprise Developer provides a number of demonstration applications for Host Compatibility Option. On Windows platforms, you can access these via the Mainframe Samples Browser. For instructions on how to start the Mainframe Samples Browser, see To start the Samples Browser. The functionality represented includes:

  • Database creation
  • DDL processing
  • Import
  • Export
  • DCLGEN
  • Using Static SQL statements
  • Using Dynamic SQL statements

You can find the HCO demonstration application source code in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\SQL\HCO for DB2 LUW (Windows) or $COBDIR/demo/sql/hco (UNIX) directory.

Parent topic: Host Compatibility Option (HCO)
Related tasks
To start the Samples Browser


How to

  • To start HCO tools
  • To create a database
  • To process SQL DDL statements
  • To create a DCLGEN
  • To import data
  • To export data
  • To set HCO for DB2 LUW options
Parent topic: HCO for DB2 LUW


To start HCO tools

This topic applies to Windows environments only.

Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > HCO for DB2 LUW
Windows 8.1
  • From the Windows Start screen, click the HCO for DB2 LUW tile
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > HCO for DB2 LUW
Parent topic: How to
Related concepts
HCO Tools


To create a database

  1. From the HCO for DB2 LUW interface, click Create Database.
  2. On the Create Database tab, complete the fields. See the Create Database tab topic for a description of each field.
  3. Click Run tool.
  4. Optionally, click the Log tab to view results.
Parent topic: How to
Related concepts
Create Database Tool
Creating a DB2 LUW Database for HCO
Related tasks
To start HCO tools
Related reference
mfhco and cobmfhco create commands
Create Database tab
Related information
Log tab


To process SQL DDL statements

  1. From the HCO for DB2 LUW interface, click DDL Processor.
  2. On the DDL Tool tab, complete the fields. See the DDL Tool tab topic for a description of each field.
  3. Click Run tool.
  4. Optionally, click the Log tab to view results.
Parent topic: How to
Related concepts
DDL Processor
Related tasks
To start HCO tools
Related reference
mfhco and cobmfhco ddl commands
DDL Tool tab
Related information
Log tab


To create a DCLGEN

  1. From the HCO for DB2 LUW interface, click DCLGEN.
  2. On the DCLGEN tab, use the Table/Schema grid to select the tables and schemas you want to include in the generated copybook.
  3. Complete the remaining fields. See the DCLGEN tab topic for a description of each field.
  4. If not already connected to the specified database, click Connect.
  5. Click Run tool.
  6. Click the Copybook tab to see the generated copybook source.
Parent topic: How to
Related concepts
DCLGEN Tool
Related tasks
To start HCO tools
Related reference
mfhco and cobmfhco dclgen commands
DCLGEN tab
Copybook tab


To import data

  1. From the HCO for DB2 LUW interface, click Import Data.
  2. On the Import tab, use the Table/Schema grid to select the tables and schemas you want to import.
  3. Complete the remaining fields. See the Import tab topic for a description of each field.
  4. If not already connected to the specified database, click Connect.
  5. Click Run tool.
  6. Optionally, click the Log tab to view results.
Parent topic: How to
Related concepts
Import Data Tool
Related tasks
To start HCO tools
Related reference
mfhco and cobmfhco import commands
Import tab
Related information
Log tab


To export data

  1. From the HCO for DB2 LUW interface, click Export Data.
  2. On the Export tab, use the Table/Schema grid to select the tables and schemas you want to export.
  3. Complete the remaining fields. See the Export tab topic for a description of each field.
  4. If not already connected to the specified database, click Connect.
  5. Click Run tool.
  6. Optionally, click the Log tab to view results.
Parent topic: How to
Related concepts
Export Data Tool
Related tasks
To start HCO tools
Related reference
mfhco and cobmfhco export commands
Export tab
Related information
Log tab


To set HCO for DB2 LUW options

  1. From the HCO for DB2 LUW interface, click Options.
  2. Using the grid, modify options as required. See the HCO for DB2 LUW Options topic for a description of each.
  3. Click Update to save changes.
Parent topic: How to
Related tasks
To start HCO tools
Related reference
HCO for DB2 LUW Options


Reference

  • DB2 Compiler Directive Options
  • DB2 Environment Variables
  • DB2 ECM Error Messages
  • HCO Tools
Parent topic: HCO for DB2 LUW


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 Enterprise Developer.
  • 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 if the application is running under Enterprise Server. 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: Reference
Related concepts
DB2 Compiler Directive
Invoking the DB2 ECM
Error Codes
Setting the DB2 ECM Preprocessor and Compiler Directive Options
Related information
Setting Compiler Directives for COBOL
$SET Statements in the Source Code


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


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.

Examples:

Windows:
db2(bind=d:\mybinds\test.bnd)
UNIX:
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 Enterprise Developer.

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 if the application is running under Enterprise Server. 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 and PL/I External Routines.

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


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 and PL/I External Routines.

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


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


PASS

Supplies login credentials required to connect to a DB2 database.

Syntax:

PASS={password | userid.password}
NOPASS

Parameters:

password
Enterprise Developer accepts a maximum of 18 characters for the password; however, the length cannot exceed the maximum set by DB2 or the operating system.
userid
Enterprise Developer 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 concepts
Connecting to a DB2 Database
Related reference
DB
SQLPASS.TXT environment variable (deprecated)


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.

When compiling with the LITLINK compiler directive on Windows platforms only, specify NOPRE to prevent possible link errors. Because NOPRE stops the code generation that loads the associated DB2 modules at run time, you must link your application with the appropriate MFHCO import library, mfhcolib.lib (32-bit version located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib; 64-bit version located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib64). To do this, add the relevant .lib file to the Link with libs field on the COBOL Link tab of your project properties, or specify it as a cbllink option when linking from the command line. Doing this ensures that the DB2 modules are loaded at run time.

Parent topic: DB2 Compiler Directive Options
Related reference
LITLINK
cbllink


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 and PL/I External Routines.

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


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.

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.
  • SQLPASS.TXT environment variable (deprecated)
    Supplies login credentials for a DB2 database connection.
Parent topic: Reference


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.
Windows:
SET HCOBND=path
UNIX:
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.

Examples:

Windows:
SET HCOBND=d:\mydir\binds
UNIX:
SET HCOBND=/mydir/binds
export HCOBND
Parent topic: DB2 Environment Variables
Related concepts
Binding
Related reference
BIND
BINDDIR


SQLPASS.TXT environment variable (deprecated)

Supplies login credentials for a DB2 database connection.
Restriction: This topic applies to Windows environments (local development) only.

Syntax:

Note: SQLPASS.TXT is deprecated, and provided for backward compatibility only. We recommend using the PASS compiler directive option to supply login credentials.
SET SQLPASS.TXT=[path]credfile

Parameters:

path
The full path to the directory that contains a text file containing the appropriate login credentials.
credfile
The name of a text file containing login credentials in the format userid.password. For example:
MyId.MyPassword
Note: If the database login is case sensitive, be sure to supply the appropriate case for both the user ID and password.

Example:

SET SQLPASS.TXT=D:\BATCH.TXT
Parent topic: DB2 Environment Variables
Related concepts
Connecting to a DB2 Database
Related reference
PASS


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: Reference
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 JVMGEN 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 Enterprise Developer. 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
Creating Debug Files
Host Variables


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 (applies to UNIX environments only).
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 (applies to UNIX environments only).
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 Enterprise Developer to ensure that the appropriate version of DB2 Connect is installed.

Parent topic: COBDB0002 - COBDB0013
Related concepts
Connecting to a DB2 Database


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
Connecting to a DB2 Database


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 dialog box in your Build Configurations:
    • Set the ESQL Preprocessor to HCO for DB2 LUW
    • 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 JVMGEN 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
Related reference
JVMGEN


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
DCLGEN Tool


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
Creating Debug Files
Host Variables


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
Related reference
DCLGEN Tool


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
Creating Debug Files
Host Variables


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.
  • COBDB0902 An internal error occurred.
    An unexpected error occurred in the preprocessor. This applies to PL/I only.
  • 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


COBDB0902 An internal error occurred.

An unexpected error occurred in the preprocessor. This applies to PL/I only.

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
Connecting to a DB2 Database


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


HCO Tools

  • Command Line Reference
  • User Interface reference
Parent topic: Reference


Command Line Reference

  • mfhco and cobmfhco create commands
  • mfhco and cobmfhco ddl commands
  • mfhco and cobmfhco dclgen commands
  • mfhco and cobmfhco import commands
  • mfhco and cobmfhco export commands
  • mfhco and cobmfhco bindall commands
Parent topic: HCO Tools
Related concepts
HCO Tools


mfhco and cobmfhco create commands

Important: Before executing the mfhco or cobmfhco create command, be sure that the MFCODESET environment variable is set to the appropriate country code. See Creating a DB2 LUW Database for HCO for details.

Syntax

Windows:

mfhco create db=databasename [coll=collsequence] [log=logfilename]
   [drv=driveletter] [id=logon-id] [pass=password] [srvr=nodename] [lctn={L | R}]

UNIX:

cobmfhco create db=databasename [coll=collsequence] [log=logfilename]
   [id=logon-id] [pass=password] [srvr={nodename | db2instancename}] [lctn={L | R}]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equals sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

databasename | Specifies the name of the new database.
collsequence | If specified, must be the default value MFD. This ensures that the environment variable MFCODESET is used.
logfilename | The name of the log file in which to capture output information. The default value is createdb.log.
driveletter (applies to Windows environments only) | The drive letter to create local database on.
logon-id | The logon ID required to connect to the server where the database is to reside.
password | The password required to connect to the server where the database is to reside.
nodename | For databases on a remote server, the cataloged DB2 node name for that server.
db2instancename(applies to UNIX environments only) | For databases on a local server, the default DB2 instance name specified by the DB2INSTANCE environment variable.
L | Indicates that the database location is a local server. Default.
R | Indicates that the database location is a remote server.

Examples

The following Windows command:
mfhco create db=test drv=e
creates a database named test on drive e using the default Enterprise Developer EBCDIC collating sequence.
The following UNIX command:
cobmfhco create db=test srvr=db2inst1
creates a database named test using the default Enterprise Developer EBCDIC collating sequence in the DB2 instance db2inst1.
Parent topic: Command Line Reference
Related concepts
Create Database Tool
Creating a DB2 LUW Database for HCO
Related tasks
To create a database


mfhco and cobmfhco ddl commands

Syntax

Windows:

mfhco ddl db=databasename file=file [log=logfile]
    [max=colno] [mod=modify] [saveddl=savefile]

UNIX:

cobmfhco ddl db=databasename file=file [log=logfile]
    [max=colno] [mod=modify]
       [id=logon pass=password saveddl=savefile]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

ddl | Specifies use of the DDL Processor. This parameter is positional.
databasename | Name of the database that you want to process DDL statements against.
file | The name of the file that contains DDL statements.
logfile | The name of log file to write processing details to. If this parameter is not specified, a logfile is created in the current directory(UNIX) or with a default logfile name using the project name (Windows). If you specify this parameter but specify no value for it (blank), this turns logging off.
colno | Column number to process DDL statements to. Must be a number less than or equal to 80.
modify | Set this parameter to "Y" if you want DDL statements converted to DB2 LUW format. Set this parameter to "N" if you want to process DDL statements unchanged. If you select this option, you must set the DDL delimiter value in the configuration file.
logon | The logon ID for the database server. (UNIX only)
pass | The password for the database server. (UNIX only)
saveddl | Save the converted DDL to a file instead of writing it to the database.
savefile | The name of a file in which to save the converted DDL. In this case, the database is not updated.

Examples

Windows:

mfhco ddl db=db2demo file=hcosetup.sql log=ddlproc.log

UNIX:

cobmfhco ddl db=db2demo file=hcosetup.sql log=ddlproc.log
Parent topic: Command Line Reference
Related concepts
DDL Processor
Related tasks
To process SQL DDL statements


mfhco and cobmfhco dclgen commands

Syntax

Windows:

mfhco dclgen db=databasename lang=language tbl=schemaname.tablename
  file=copybookname [pre={USER | TBL | NO}] [user=username] [fld={COL | NUM}]
     null=nullindname [typeint={COMP | COMP5}] [typelob={LOCATOR | LOB | FILE}]
        [declare={Y | N }] [str=structurename]

UNIX:

cobmfhco dclgen db=databasename lang=language tbl=schemaname.tablename
  file=copybookname [pre={USER | TBL | NO}] [user=username] [fld={COL | NUM}]
     null=nullindname [typeint={COMP | COMP5}] [typelob={LOCATOR | LOB | FILE}]
        [declare={Y | N }] [str=structurename]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

databasename | Name of the target database.
language | Language to generate. cbl is the default; can also specify c or pli.
schemaname | Schema name for the generated copybook.
tablename | Table name for the generated copybook.
filename | Name of the copybook file to generate.
TBL | Specifies that the copybook prefix is the same as the table name. Default.
USER | Specifies that the prefix is supplied by the user.
NO | Specifies that there is no prefix.
username | A text string composed of valid COBOL characters, used as a prefix for each host variable in the copybook.
COL | Specifies the column name. Default.
NUM | Specifies the column number.
nullindname | Specifies the null indicator name suffix. Default is NULL.
COMP | Specifies generation of numeric fields as COMP variables. Default.
COMP5 | Specifies generation of numeric fields as COMP-5 variables.
LOCATOR | Specifies generation of LOB variables as SQL TYPE LOB-LOCATOR. Default.
LOB | Specifies generation of LOB variables as SQL TYPE LOB(size).
FILE | Specifies generation of LOB variables as SQL TYPE LOB-FILE.
declare | Y - Generate DECLARE TABLE as part of the copybook. Default. N - Do not generate DECLARE TABLE as part of the copybook.
structurename | Specifies the name of the copybook structure.

Examples

Windows:

mfhco dclgen db=db2demo lang=cbl tbl=demo.items file=item.cpy

UNIX:

cobmfhco dclgen db=db2demo lang=cbl tbl=demo.items file=item.cpy
Parent topic: Command Line Reference
Related concepts
DCLGEN Tool
Related tasks
To create a DCLGEN


mfhco and cobmfhco import commands

Syntax

Windows:

mfhco import db=databasename tbl=tablename file=filename [fmt=format]
    [log=logfile] [chardel=chardelimiter] [coldel=coldelimiter]
        [date=dateformat] [plus=sign] [savedel=delfilename]
            [commit=rowcount]

UNIX:

cobmfhco import db=databasename tbl=tablename file=filename [fmt=format]
    [log=logfile] [chardel=chardelimiter] [coldel=coldelimiter]
        [date=dateformat] [plus=sign] [savedel=delfilename]
            [id=logon pass=password] [commit=rowcount]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

import | Invokes the Import Data command-line processor. This parameter is positional.
databasename | Name of the database to import to.
tablename | Name of table to be imported. You can specify both the schema and the table name, separated with a period.
filename | Filename to import data from.
format | Format to import data. Valid values are IXF, DEL, and DSNTIAUL. You can use DSN for DSNTIAUL.
logfile | File to write processing messages to. If this parameter is not specified, a logfile is created in the current directory. In Windows environments, the default logfile name is based on the project name. .
chardelimiter | Delimiter used to enclose character data when import format is DEL specified. Default is double quotes (").
coldelimiter | Delimiter used to indicate the end of column data when import format DEL is specified. Default is comma (,).
dateformat | Format to import date fields in if importing data in DSNTIAUL or DEL format. Default is the format for your country. Valid values for DSNTIAUL are ISO, USA, EUR, and JIS. ISO is only valid option for DEL format.
sign | Generate positive numeric data with plus signs when importing data in DEL format. Valid values are "Y" for yes to generate plus signs or "N" to not generate plus signs. Default is "Y".
savedel | Save DSNTIAUL as an ASCII-delimited file that can be used to import large amounts of data via a third-party tool.
delfilename | Filename of the ASCII-delimited file.
rowcount | The number of rows per commit.
logon | The logon ID for the database server. (UNIX only)
pass | The password for the database server. (UNIX only)

Comments

The Import Data tool can also be run as a batch function.

Examples

Windows:

mfhco import db=db2demo fmt=dsn tbl=demo.product file=product.dsn chardel=' log=import.log commit=1000

UNIX:

cobmfhco import db=db2demo fmt=dsn tbl=demo.product file=product.dsn chardel=' log=import.log
Parent topic: Command Line Reference
Related concepts
Import Data Tool
Related tasks
To import data


mfhco and cobmfhco export commands

Syntax

Windows:

mfhco export db=databasename tbl=table file=filename
    [fmt=format] [log=logfile] [chardel=chardelimiter] [coldel=coldelimiter]
       [date=dateformat] [plus=sign]

UNIX:

cobmfhco export db=databasename tbl=table file=filename
    [fmt=format] [log=logfile] [chardel=chardelimiter] [coldel=coldelimiter]
       [date=dateformat] [plus=sign]

Syntax Rules

  1. At least one space must occur before each parameter in the command.
  2. There must be an equal sign (=) between parameters and their values.
  3. If you omit parameters that have a default value, Host Compatibility Option uses the default value.

Parameters

export | Parameter to invoke Export Data command line processor. Parameter is positional.
databasename | Name of the database to connect to.
table | Name of table to be exported. Can include both schema and table name.
filename | Filename to export data to.
format | Format in which to export data. Valid values are IXF, DEL, and DSNTIAUL. You can use DSN for DSNTIAUL.
logfile | File to write processing messages to. If this parameter is not specified, a logfile is created in the current directory(UNIX) or with a default logfile name using the project name (Windows).
chardelimiter | Delimiter used to enclose character data when export format DEL specified. Default is double quotes (").
coldelimiter | Delimiter used to indicate the end of column data when export format DEL is specified. Default is comma (,).
dateformat | Format to export date fields in if exporting data in DSNTIAUL or DEL format. Default is format for your country. Valid values for DSNTIAUL are ISO, USA, EUR and JIS. ISO is the only valid option for DEL format.
sign | Generate positive numeric data with plus signs when exporting data in DEL format. Valid values are "Y" for yes to generate plus signs or "N" to not generate plus signs. Default is "Y".

Comments

You can also run the Export Data tool as a batch function.

Examples

Windows:

mfhco export db=db2demo fmt=ixf file=product.ixf tbl=demo.product log=export.log

UNIX:

cobmfhco export db=db2demo fmt=ixf file=product.ixf tbl=demo.product log=export.log
Parent topic: Command Line Reference
Related concepts
Export Data Tool
Related tasks
To export data


mfhco and cobmfhco bindall commands

Syntax

Windows:

mfhco bindall db=databasename [qualifier=schema] [collection=collection-id]
    [datetime=format] [isolation=isolation-level] [blocking=row-blocking]
       [sqlwarn=compile-option] [id=logon-id] [pass=password]

UNIX:

cobmfhco bindall db=databasename [qualifier=schema] [collection=collection-id]
    [datetime=format] [isolation=isolation-level] [blocking=row-blocking]
       [sqlwarn=compile-option] [id=logon-id] [pass=password]

Parameters

bindall | Parameter to invoke BindAll command line processor. Parameter is positional.
databasename | Name of the database to connect to.
schema | Name of the schema to use for table qualification.
collection-id | A 128-byte collection identifier for the package.
format One of the following datetime formats to return when executing the application:
  • USA
  • ISO
  • JIS
  • EUR
  • LOC
  • DEF
isolation-level Determines how far a program bound to this package can be isolated from the effect of other executing programs. Valid values are:
  • CS
  • RR
  • RS
  • UR
row-blocking The type of row blocking for cursors. Valid values are:
  • UNAMBIG
  • ALL
  • NO

The blocking of row data that contains references to LOB column data types is also supported in partitioned database environments.

compile-option Indicates whether warnings are returned from the compilation of dynamic SQL statements via PREPARE or EXECUTE IMMEDIATE, or from describe processing via PREPARE...INTO or DESCRIBE. Valid values are:
  • YES
  • NO
logon-id | Logon ID required to connect to the server where the database resides.
password | Password required to connect to the server where the database resides.

Comments

You must execute the BindAll Packages tool either from a command prompt in the directory that contains your .bnd files, or from your project as a post-build event. For more information on build events, see Setting Project-Wide Build Properties and Compiler Directives.

The BindAll Packages tool generates a log file, bindall.txt, that summarizes the results for all packages bound. Individual results are written to programName.txt.

Log files are written to the current directory.

Examples

Windows:

mfhco bindall db=db2demo qualifier=DEMO datetime=usa isolation=cs sqlwarn=no

UNIX:

cobmfhco bindall db=db2demo qualifier=DEMO datetime=usa isolation=cs sqlwarn=no
Parent topic: Command Line Reference
Related concepts
BindAll Packages Tool
Setting Project-Wide Build Properties and Compiler Directives


User Interface reference

  • Create Database tab
  • DDL Tool tab
  • DCLGEN tab
  • Copybook tab
  • Import tab
  • Export tab
  • Log tab
  • HCO for DB2 LUW Options
Parent topic: HCO Tools


Create Database tab

Database
The name of the database you are creating.
Log File
The full path to and name of the logfile to capture output information. The default path is the current directory, and the default name is createdb.log.
Login ID
The logon ID required to connect to the server where the database is to reside.
Password
The password required to connect to the server where the database is to reside.
DB2 Remote Server
For databases on a remote server, the cataloged DB2 node name for that server.
Parent topic: User Interface reference
Related concepts
Create Database Tool
Related tasks
To create a database


DDL Tool tab

Database
Lists all available databases.
DDL File
The name of the file that contains DDL statements.
Log File
File to write processing messages to. If not specified, a logfile is created in the current directory. In Windows environments, the default logfile name is based on the project name. .
Save DDL
The full path to and name of a file in which to save the converted DDL instead of writing it to the database.
Parent topic: User Interface reference
Related concepts
DDL Processor
Related tasks
To process SQL DDL statements


DCLGEN tab

Database
Name of the database to connect to.
Table/Schema Grid
Lists the tables and schemas that can be included in the generated copybook.
File
Name of the generated copybook file.
Connect
Connect to the specified database.
Parent topic: User Interface reference
Related concepts
DCLGEN Tool
Related tasks
To create a DCLGEN


Copybook tab

Shows generated copybook code.

Parent topic: User Interface reference
Related concepts
DCLGEN Tool
Related tasks
To create a DCLGEN


Import tab

Database
Name of the database to import to.
Table/Schema Grid
List of tables and schemas to be imported.
Import from
The name of an exported file that contains the data to import.
Log File
File to write processing messages to. If not specified, a logfile is created in the current directory. In Windows environments, the default logfile name is based on the project name. .
Save DEL File
The name of a file in which to save DSNTIAUL as an ASCII-delimited file that can be used to import large amounts of data via a third-party tool.
Connect
Connect to the specified database.
Parent topic: User Interface reference
Related concepts
Import Data Tool
Related tasks
To import data


Export tab

Database
Name of the database to connect to.
Table/Schema Grid
List of tables and schemas that can be exported.
Export to
The name of a file to export data to.
Log File
File to write processing messages to. If not specified, a logfile is created in the current directory. In Windows environments, the default logfile name is based on the project name. .
Connect
Connect to the specified database.
Parent topic: User Interface reference
Related concepts
Export Data Tool
Related tasks
To export data


Log tab

Shows log information generated during the execution of the tool.

Parent topic: User Interface reference
Related concepts
Create Database Tool
DDL Processor
Export Data Tool
Import Data Tool
Related tasks
To create a database
To process SQL DDL statements
To export data
To import data


HCO for DB2 LUW Options

Options grid
Lists the options and enables you to modify them. For information on each option, see the context help at the bottom of the grid.
Update
Saves changed options.
Parent topic: User Interface reference
Related tasks
To set HCO for DB2 LUW options


HCO for SQL Server (HCOSS)

Restriction: This topic applies to Windows environments only.

HCO for SQL Server (HCOSS) provides tools for migrating DB2 databases and applications to SQL Server databases and applications. It is a superset of OpenESQL; therefore applications that use HCOSS have access to all OpenESQL functionality.

For third-party software requirements, see the Database Access - HCO for SQL Server (HCOSS) section in Additional Software Requirements on Windows.

  • Demonstration Applications
    A list of available demonstration applications provided to illustrate programming techniques and runtime behavior for application migrations using HCO for SQL Server.
  • HCOSS Toolset
  • Before Using HCO for SQL Server
    Describes the SQL Server database adjustments that are required each time you upgrade your version of Enterprise Developer.
  • Using HCOSS with Windows User Account Control (UAC)
  • HCOSS Datetime Data Type Handling
    Describes how HCOSS enables you to keep your mainframe DB2 datetime data type formats intact, including DATE, TIME, and TIMESTAMP formats in PIC X character host variables, while accessing corresponding SQL Server date, time, and datetime2 columns, rather than using SQL Server default formats for these data types. Also describes how to ensure that SQL Server character columns can also store data with mainframe DB2 formats intact.
  • Scope - HCOSS SQL Compiler Directive Options
  • Managing Connections
  • Migrating Databases
  • Migrating Applications
  • Deploying Native Applications
  • Managing Log Files
  • Customizing HCOSS
  • How to
  • Reference
Parent topic: Mainframe Programming
Related concepts
Database Access Features
Additional Software Requirements on Windows
Before Using HCO for SQL Server


Demonstration Applications

Restriction: This topic applies to Windows environments only.

Enterprise Developer provides a number of demonstration applications for HCOSS. You can access these via the Mainframe Samples Browser. For instructions on how to start the Mainframe Samples Browser, see To start the Samples Browser.

The demonstration files are located in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Eclipse\Mainframe\SQL\hcoss directory.

Each sample application comes with a Readme file to explain how to use the application.

The HCOSS demonstration applications all produce a console log displaying their progress. They all terminate on receipt of an error, after displaying an error message.

HCOSS - Array Insert
Demonstrates how array inserts work with SQL Server when using mainframe DB2 syntax.
HCOSS - Function Emulation
Demonstrates how to add math functions to SQL Server that emulate standard math functions in DB2.
HCOSS - Labeled Durations
Demonstrates how HCOSS manages DB2 date formats and labeled duration calculations. SQL Server does not support labeled calculations directly. HCOSS handles the conversion to T-SQL to emulate DB2 labelled duration syntax.
HCOSS - TwoPackageSet
Demonstrates how to use HCOSS to switch package sets and alternate fetching data using a single cursor name. It also demonstrates how, with HCOSS, you can bind the application using HCOSS Manage Packages and Plans tool.
Parent topic: HCO for SQL Server (HCOSS)
Related tasks
To start the Samples Browser


HCOSS Toolset

Restriction: This topic applies to Windows environments only.

The HCOSS toolset includes:

Manage Connections Tool
Enables you to connect to both your mainframe's DB2 database and a SQL Server database running locally or remotely on a local area network.
Database Migration Tools
Extract Schema
Downloads the DB2 database schema objects and creates an XML schema file representing the schema structure.
Assess Data Migration
Produces an editable report of the information in your extracted schema.
Define Lists
Reads the XML schema file created using the Extract Schema tool and enables you to create a list of database objects to transfer to the SQL Server database.
Generate DDL
Reads both the XML schema file and the list of selected database objects and translates the information into a SQL Server DDL script.
Transfer Data
Builds and executes an SSIS package to move each specified database object to your SQL Server database.
Compare Data
Verifies the validity of newly imported data by comparing it with the original data.
Application Migration Tools
Assess Application Migration
Analyzes the EXEC SQL statements in your DB2 program and copybook code and flags statements that could potentially cause problems when migrating to SQL Server in different migration scenarios, with and without using HCOSS.
Manage Packages and Plans
Create and edit scripts that enable you to bind DBRM members, packages, and plans to your COBOL programs, and to free packages and plans.
Application Database support
HCOSS also provides SQL Server functions and meta-data tables to support mainframe emulation in a SQL Server database. For more information, see Application Database Support.
Customization Tools
Customize Type Mappings
View or change the default type mappings for your SQL database.
Customize SQL Name Mappings
View or change default SQL name mappings, or define additional SQL name mappings.
Customize SQLCode Mappings
View or change the default OpenESQL SQLCodes and their DB2 SQLCode and DB2 SQLState equivalents that are stored in your SQL database.
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
Manage Connections Tool
Migrating Databases
Migrating Applications
Why You Should Use the Assess Application Migration Tool
Application Database Support
Related tasks
To start HCO for SQL Server
To set HCOSS options
Related reference
Options


Before Using HCO for SQL Server

Describes the SQL Server database adjustments that are required each time you upgrade your version of Enterprise Developer.
Restriction: This topic applies to Windows environments only.

HCOSS mimics z/OS functions and other z/OS functionality by storing SQL Server stored procedures and tables in your SQL Server database(s).

To successfully use HCOSS, it is important that you update this information stored in your database(s) each time you upgrade your version of Enterprise Developer, including new releases, updates, or hotfixes. Doing so ensures that HCOSS always executes optimally.

We provide three HCOSS scripts you can use to update your SQL Server database(s) after each upgrade. By default, all are located in your %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory:

InstallSYSIBM.sql
Creates metadata tables.
InstallBindProcs.sql
Creates SQL Server stored procedures required for binding and managing temporary table metadata.
InstallDigitsFunction.sql
Creates SQL Server stored procedures required to support DB2 z/OS functions.
To execute these scripts against any SQL Server database, you must have the following permissions to the database:
  • CREATE SCHEMA
  • CREATE PROCEDURE
  • EXECUTE PROCEDURE in the SYSIBM schema

We suggest that you choose from the following methods of script execution:

SQL Server Management Studio
Execute all three HCOSS scripts against each SQL Server database.
SQL Server sqlcmd utility
This option enables you to automate the process, running the three scripts consecutively. Use the following syntax at a command prompt:
sqlcmd -S myServer\instanceName -i "scriptDir\HCOSSscript.sql"

Where:

myServer | Name of a SQL Server database
instanceName | SQL Server instance name
scriptDir | Full path to the directory that contains the scripts
HCOSSscript | Name of an HCOSS script
DSN Bind Utility
While the DSN Bind utility does just what the other two options also do, you might find it easier to use as an alternative to executing the scripts yourself. We recommend this procedure:
  1. Start an Enterprise Developer command prompt.
  2. Do one of the following:
    • If using Windows authentication, enter:
      DSN SYSTEM(connectionName)
    • If using SQL Server authentication:
      DSN SYSTEM(connectionName) ASUSER(LoginID.Password)

    Where connectionName is the name of a connection created with the HCOSS Manage Connections tool, and LoginID and Password are a SQL Server login ID and password respectively.

    DSN automatically executes the required scripts and updates the database. The command window shows its execution process.

  3. When a DSN command prompt appears, enter END.
Note: You must have the same SQL Server permissions when using the DSN Bind utility as are required to execute the scripts using one of the other methods.
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
HCO for SQL Server (HCOSS)
DSN Bind Utility


Using HCOSS with Windows User Account Control (UAC)

Restriction: This topic applies to Windows environments only.
Restriction: This topic applies to the Windows Vista and 7 operating systems and later. It does not apply to the Windows XP operating system.

When you have enabled the Windows User Account Control (UAC) feature, HCOSS exhibits different behavior depending on whether or not you are logged in as a standard user or an administrator, whether or not you are a member of the Windows Administrators group, and how you start the HCOSS user interface.

Standard user and administrator modes

You can run HCOSS as a standard user or as an administrator. When you run as an administrator, all HCOSS features are available to you. However, when you run HCOSS as a standard user, some features are limited. We recommend that you run HCOSS as an administrator when possible.

HCOSS UAC behavior

When using UAC, HCOSS runs in either standard user or administrator mode, depending on these three factors:
  • The Windows group to which you belong - standard user or administrator
  • How you start HCOSS - from the Start menu or from within the IDE
  • The settings for HCOSS UAC Behavior options

To run HCOSS in standard user mode

The following scenarios show how to run HCOSS in standard user mode, limiting access to some features. In each scenario, the statement in each first-level bullet point must be true. Assume all HCOSS UAC Behavior options are set to their defaults:
Scenario 1
  • You are logged into Windows as a standard user
  • You are not part of the Administrator group
  • You start HCOSS as a standard user using either of the following methods:
    • From within the IDE by selecting Run > Tools > Data Tools > HCO for SQL Server
    • From the Start menu
Scenario 2
  • You are logged into Windows as a standard user
  • You are also part of the Windows Administrator group
  • You start HCOSS using either of the following methods:
    • From within the IDE by selecting Run > Tools > Data Tools > HCO for SQL Server
    • From the Start menu, answering No to any subsequent prompts.
Scenario 3
  • You are logged into Windows as an administrator
  • You start HCOSS from the Start menu, answering No to any subsequent prompts

To run HCOSS in administrator mode

The following scenarios show how to run HCOSS in administrator mode, providing full access to all features. In each scenario, the statement in each first-level bullet point must be true:
Scenario 1
  • You are logged into Windows as a standard user
  • You are a member of the Windows Administrator group
  • You start HCOSS using either of the following methods:
    • From the Start menu, answering Yes to any subsequent prompts
    • From the Start menu but right-clicking HCO for SQL Server and selecting Run as administrator
Scenario 2
  • You are logged into Windows as an administrator
  • You start HCOSS using any of the following methods:
    • From within the IDE by selecting Run > Tools > Data Tools > HCO for SQL Server
    • From the Start menu
    • From the Start menu by right-clicking HCO for SQL Server and selecting Run as administrator

HCOSS UAC prompts

By default, HCOSS could prompt you at startup depending on the settings of the HCOSS UAC Behavior options. You might encounter one or both of the following prompts:
Relaunch HOCSS as Administrator
This prompt appears by default when:
  • You are a member of the Administrator group
  • You launch HCOSS from the Start menu without selecting Run as administrator

If you respond Yes to this prompt, HCOSS relaunches in administrator mode, and Windows displays the User Account Control dialog box. Respond to this prompt as appropriate.

If you respond No to this prompt, HCOSS resumes launching in standard user mode.

If you check Stop asking me, HCOSS changes the default setting of the Prompt to automatically run as Administrator option from True to False.

Running as non-administrator information
When you are running HCOSS in standard user mode and you are not a member of the Administrators group, this dialog box appears to notify you that some features are limited in standard user mode.

If you check Do not tell me again, HCOSS changes the default setting of the Warn non-Administrator users of limited functionality option from True to False.

Note: You can change the default HCOSS behavior with regard to launching HCOSS with UAC and UAC prompts by setting the options manually. For information on setting HCOSS UAC Behavior options, see Options.
Parent topic: HCO for SQL Server (HCOSS)
Related tasks
To start HCO for SQL Server
To set HCOSS options
Related reference
Options


HCOSS Datetime Data Type Handling

Restriction: This topic applies to Windows environments only.

While most mainframe DB2 applications use the default format for DB2 DATE, TIME, and TIMESTAMP PIC X character host variables, some do not. Mainframe DB2 applications support alternative formats as well as the defaults. Similarly, most SQL Server applications use the default date, time, and datetime2 formats for PIC X character host variables. Unfortunately, default DB2 data type formats do not match the default SQL Server data type formats. To ensure that your mainframe DB2 DATE, TIME, and TIMESTAMP formatting is properly converted and recognized by your SQL Server application, use HCOSS to customize the conversion.

For example, the default Data Type formats for character host variables are:

Mainframe Data Type | Mainframe DB2 format | SQL Server Data Type | SQL Server format
DATE | yyyy-mm-dd | date | yyyy-mm-dd
TIME | hh.mm.ss | time | hh:mm:ss
TIMESTAMP | yyyy-mm-dd-hh.mm.ss.ffffff | datetime2 | yyyy-mm-dd hh:mm:ss.ffffffff

The character host variable default formats for the DATE data type for mainframe DB2 and the date data type for SQL Server match; therefore, SQL Server recognizes the DB2 format and no conversion is required. However, the default data type formats for TIME/time and TIMESTAMP/datetime2 do not match. Therefore, if your application uses default DB2 TIME and/or TIMESTAMP formats for your character host variables, and you want to use these for your SQL Server time and datetime2 data types respectively, use HCOSS to convert the mainframe DB2 formats such that they are recognized by SQL Server.

Input Host Variables - DETECTDATE

In cases where the DB2 application being converted uses an input host variable format that is not supported by SQL Server by default, use the DETECTDATE HCOSS compiler directive option to convert the DB2 format to a SQL Server-compatible format. DETECTDATE instructs HCOSS to examine the contents of SQL Server character input host variables, looking for data that matches the mainframe format specified for DATE, TIME and TIMESTAMP data.

DATE and TIME Data Types

With respect to DATE and TIME data types processed using only the DETECTDATE directive to address date and time conversion, HCOSS examines the contents of SQL Server character input host variables and identifies fields that match based on the default DATE and TIME DB2 mainframe formats (yyyy-mm-dd and hh.mm.ss respectively).

If you specify the DATE and/or TIME HCOSS directives in addition to DETECTDATE, HCOSS examines the contents of SQL Server character input host variables and identifies fields that match the date and time formats specified by the DATE and TIME directives.

TIMESTAMP Data Types
With respect to the TIMESTAMP data type, DETECTDATE instructs HCOSS to examine input host variables, looking for matches with any of the following DB2 TIMESTAMP formats:
  • 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

When it finds a match, HCOSS translates the data in the input host variable into a format SQL Server understands.

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 DB2 application uses DATE, TIME, and TIMESTAMP values in PIC X input host variables, but I only use those values in date, time or datetime2 columns in SQL Server. | CLIENT
My DB2 application uses DATE, TIME, and TIMESTAMP values in PIC X input host variables, but I only use those values in character columns in SQL Server. 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 HCOSS SQL compiler directive options.
I only use SQLTYPE host variables with date, time and datetime2 columns in SQL Server, and never use PIC X host variables with date, time or datetime2 columns. | Not required.1
My DB2 application uses DATE, TIME, and TIMESTAMP values in PIC X input host variables, and I use those values both in character columns and in date, time and datetime2 columns in SQL Server, and my character columns might use data in formats that could be confused with the formats for DATE, TIME, or TIMESTAMP values. | SERVER
My application uses DB2 mainframe DATE and/or TIME formats that match the default SQL Server formats, and I use those values in both character columns and/or date columns in SQL Server. | Not required. Do not use DETECTDATE, DATE, or TIME HCOSS SQL compiler directive options.
1Optionally, you can use alternative datetime HCOSS SQL compiler directive options.
Note: For complete information on all DETECTDATE options, see the DETECTDATE HCOSS SQL compiler directive option topic.

Output Host Variables

Simply by enabling HCOSS using the DIALECT=MAINFRAME directive, by default HCOSS returns SQL Server datetime and datetime2 data types in the mainframe default format as shown below:

Mainframe Data Type | SQL Server Data Type | Mainframe Default Format
DATE | date | yyyy-mm-dd
TIME | time | hh.mm.ss
TIMESTAMP | datetime2 | yyyy-mm-dd-hh.mm.ss.ffffff
DATE and TIME Directives
You can also specify the optional DATE and TIME HCOSS directives, which enable you to specify alternative output host variable formats for SQL Server date and time columns, including USA, EUR or JIS.
Note: If you omit the DETECTDATE directive, the DATE and TIME directives affect output format only.
DATE, TIME, and DETECTDATE Directives
If you specify the DATE and/or TIME directives in addition to the DETECTDATE directive, the specified DATE and TIME formats dictate the format of both input and output host variables.

Datetime Literals in SQL Statements

HCOSS also provides support for literals inside of SQL statements. To enable this functionality, code any of the following SQL comments into your DB2 mainframe application, positioned before a literal declaration. These comments tell HCOSS whether the literal value is used with a DATE, TIME, TIMESTAMP or CHAR column in your DB2 database:

  • /*#CHAR*/
  • /*#DATE*/
  • /*#TIME*/
  • /*#TIMESTAMP*/

In particular, the CHAR literal specification can be very helpful when you do not want HCOSS to translate the literal.

Parent topic: HCO for SQL Server (HCOSS)
Related reference
DETECTDATE
DIALECT
DATE
TIME


Scope - HCOSS SQL Compiler Directive Options

Restriction: This topic applies to Windows environments only.
Important: 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 Using XA-compliant Resources (XARs) for more information.

For a list of process-based OpenESQL directives, see Scope - OpenESQL SQL Compiler Directive Options.

Each HCOSS SQL compiler directive option is used either at compile time, run time, or both. The behavior at run time is described as Source file, meaning that when a source file specifies the directive, the value set in the source file is used.

For additional information on the scope of each HCOSS SQL compiler directive option, see its corresponding Reference topic.

Parent topic: HCO for SQL Server (HCOSS)
Related concepts
Using XA-compliant Resources (XARs)
Related reference
SQL Compiler Directive Options - HCOSS


Managing Connections

Restriction: This topic applies to Windows environments only.

To successfully migrate DB2 databases and applications to SQL Server, you must establish a connection to both databases. You can do this using the Manage Connections tool, or a combination of other connection utilities.

For ODBC connectivity, we recommend that you always use the most recent supported version of the ODBC driver available when creating new connections. We also recommend that you upgrade existing connections to use the most recent driver when possible. HCOSS detects the ODBC driver version at startup, when creating, editing, and repairing SQL Server system or user connection types, and provides the option to upgrade where appropriate. For information on supported ODBC drivers, see the Database Access - HCO for SQL Server (HCOSS) section in the Additional Software Requirements on Windows topic.

  • Manage Connections Tool
  • Connection Types
Parent topic: HCO for SQL Server (HCOSS)


Manage Connections Tool

Restriction: This topic applies to Windows environments only.

The Manage Connections tool enables you to make the SQL Server and DB2 connections needed to run your applications.

It includes the following key functionality:

  • Maintains a catalog of DSN connections, including the provider used to access the connection and the connection parameters used by the provider.
  • Sets both 32-bit and 64-bit connections on 64-bit operating systems using one set of connection parameters.
  • Creates export XML files you can use to import connections into the Manage Connections tool.
  • Provides the option to upgrade the ODBC driver where appropriate.
Note: The Manage Connections tool is not compatible with DB2 ODBC connections.
Parent topic: Managing Connections
Related concepts
HCOSS Toolset
Application Migration Process
Connection Types
Offline Extract Schema Solution
Related tasks
To create a DB2 connection
To create a system or user SQL Server connection
To import a connection
To export a connection
To repair a connection
Related reference
Manage Connections Tool Log Files
Manage Connections Tool Error Messages
DB2 Connection tab
SQL Server Connection tab
Export tab
Import tab
Connection List tab


Connection Types

Restriction: This topic applies to Windows environments only.

HCOSS provides the System and User connection types. For each, connection information is tracked and stored in a series of files.

System Connection Type

The Manage Connections tool tracks and stores connection information in the following files:
%PROGRAMDATA%\Micro Focus\HCOSS\Connections\ConnectionTracking.hcocon
A work file containing tracking information.
%WINDOWS%\Microsoft.NET\Framework\v2.0.50727\CONFIG\machine.config
A configuration file that stores 32-bit framework 2.0, 3.0, and 3.5 (CLR 2) system connection strings.
%WINDOWS%\Microsoft.NET\Framework\v4.0.30319\Config\machine.config
A configuration file that stores 32-bit framework 4.0 (CLR 4) system connection strings.
%WINDOWS%\Microsoft.NET\Framework64\v2.0.50727\CONFIG\machine.config
A configuration file that stores 64-bit framework 2.0, 3.0, and 3.5 (CLR 2) system connection strings.
%WINDOWS%\Microsoft.NET\Framework64\v4.0.30319\Config\machine.config
A configuration file that stores 64-bit framework 4.0 (CLR 4) system connection strings.

User Connection Type

The Manage Connections tool tracks and stores connection information in the following files:
%LOCALAPPDATA%\Micro Focus\HCOSS\Connections\UserConnectionTracking.hcocon
A work file containing tracking information.
%LOCALAPPDATA%\Micro Focus\UserConnections32_v2.config
A configuration file that stores 32-bit framework 2.0, 3.0, and 3.5 (CLR 2) user connection strings.
%LOCALAPPDATA%\Micro Focus\UserConnections32_v4.config
A configuration file that stores 32-bit framework 4.0 (CLR 4) user connection strings.
%LOCALAPPDATA%\Micro Focus\UserConnections64_v2.config
A configuration file that stores 64-bit framework 2.0, 3.0, and 3.5 (CLR 2) user connection strings.
%LOCALAPPDATA%\Micro Focus\UserConnections64_v4.config
A configuration file that stores 64-bit framework 4.0 (CLR 4) user connection strings.
Parent topic: Managing Connections
Related concepts
Manage Connections Tool
Related tasks
To create a DB2 connection
To create a system or user SQL Server connection
To import a connection
To export a connection
To repair a connection
Related reference
Manage Connections Tool Log Files
Manage Connections Tool Error Messages


Migrating Databases

Restriction: This topic applies to Windows environments only.

HCO for SQL Server (HCOSS) provides tools and methods for migrating DB2 databases from the mainframe to SQL Server databases on a Local Area Network.

Note: For information about prerequisite third-party software and supported DB2 versions, see the HCO for SQL Server (HCOSS) section in the topic Database Access Support with Native COBOL.
  • DB2 Database Migration Process
  • DB2 Temporary Table Migration
  • Extract Schema Tool
  • Assess Data Migration Tool
  • Define Lists Tool
  • Generate DDL Tool
  • Transfer Data Tool
  • Compare Data Tool
  • Mainframe Batch Database Tools
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
HCOSS Toolset


DB2 Database Migration Process

Restriction: This topic applies to Windows environments only.

Use the HCOSS standard tool set to migrate the DB2 databases from your mainframe to SQL Server databases that run on Windows.

The basic process is as follows:

  1. Install all prerequisite third-party software. For details, see Additional Software Requirements on Windows.
  2. Gather the information required to connect to mainframe DB2 using the Microsoft OLE DB provider Data Access Tool, which includes:
    • Mainframe logon credentials
    • Network address and port for your DB2 location
    • OLE DB provider parameters including initial catalog and collection
    Note: Your mainframe DBA must set mainframe permissions such that the Microsoft OLE DB provider can create packages in a mainframe collection. Users who connect to the mainframe when using HCOSS must have access to this collection.
  3. Run the Data Access Tool that comes with the OLE DB provider, and use it to:
    • Create the mainframe packages required by the provider
    • Create a new data source to connect to the mainframe
    • Test the connection
    • Create the packages used by the provider
    • Run the sample query
  4. Create a destination SQL Server database using Microsoft SQL Server SQL Server Management Studio.
  5. Create a connection to your SQL Server database using the Manage Connections tool.
  6. Extract the DB2 schemas from your mainframe DB2 database to a local or shared directory using the Extract Schema tool.
  7. Optionally assess the data migration by viewing and editing the information in the schema extract file created by the Extract Schema tool.
  8. Define a list of extracted DB2 schema objects that you want to migrate to the SQL Server database using the Define Lists tool.
  9. Create an SQL script to create the DB2 schema objects in the new SQL Server database using the Generate DDL tool.
  10. Populate the SQL Server database with the selected schema objects from the DB2 database using the Transfer Data tool.
  11. Verify the results of the transferred data using the Compare Data tool.
Parent topic: Migrating Databases
Related concepts
Extract Schema Tool
Define Lists Tool
Generate DDL Tool
Transfer Data Tool
Compare Data Tool
Deploying Native Applications
Related reference
Required DB2 Catalog Tables


DB2 Temporary Table Migration

Restriction: This topic applies to Windows environments only.

HCOSS supports the DECLARE GLOBAL TEMPORARY TABLE statement. When executed, HCOSS creates a SQL Server temporary table. HCOSS only supports use of the SESSION qualifier for global temporary tables, HCOSS does not support use of regular tables in the SESSION schema.

HCOSS does not support the direct migration of temporary tables created using the CREATE statement. However, you can accommodate this type of temporary table by converting the CREATE statement to a DECLARE statement, and adding it to the start of any program that references the table created by the converted CREATE statement. Use the following guidelines when adding a DECLARE statement to a program:
  • You must convert the application to use the SESSION schema as a qualifier for access to global temporary tables that were CREATEd on the mainframe
  • You can DECLARE a table multiple times; executing a DECLARE statement for a global temporary table that already exists has no effect
Once the DECLARE statements have been added to appropriate programs, HCOSS converts the tables as follows:
  • When DECLARE GLOBAL TEMPORARY TABLE is executed, HCOSS creates a temporary table.
  • Because SQL Server temporary table names always start with #, HCOSS generates a temporary table name using the original table name used in the mainframe code, plus a prepended # sign. For example, if the original table name is EMP, the SQL Server temporary table is named #EMP.
Parent topic: Migrating Databases


Extract Schema Tool

Restriction: This topic applies to Windows environments only.

The HCOSS tools used to prepare for a migration rely on a data file known as a schema extract file. This file contains metadata extracted from the DB2 system catalog for database schemas you want to migrate. As the first step in preparing for a DB2 database to SQL Server database migration, use the Extract Schema tool to create this file. You can run the tool either from the HCOSS user interface, or from the command line using the MFExtractSchemaInfo command.

HCOSS uses the generated schema extract file in the next step of the database migration process - defining lists of specific tables and views to migrate.

  • Schema Extraction Process
  • Offline Extract Schema Solution
  • Modifying Exporting and Importing Schema Extract Files
  • Extract Schema Security
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Deploying Native Applications
Related tasks
To extract DB2 schema objects
To modify a schema extract file
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files
Extract Schema Tool Error Messages
Required DB2 Catalog Tables
Schema Extract tab
Create New Schema Extract
Results tab


Schema Extraction Process

Restriction: This topic applies to Windows environments only.

The Extract Schema tool retrieves information about various z/OS DB2 SQL objects, and then stores this information in an XML file for further processing with HCOSS.

The standard schema extraction method is to first connect to your z/OS DB2 database, and then retrieve the required information directly from the z/OS DB2 catalog.

You can optionally use the offline schema extract solution. With this approach, you first migrate the z/OS DB2 catalog information to SQL Server, and then use the Extract Schema tool connected to SQL Server. This eliminates the need to connect to z/OS DB2 directly. For details on this approach, see Offline Extract Schema Solution.

The Extract Schema tool extracts data for selected schemas from the following DB2 catalog tables in the SYSIBM schema:
Object Type DB2 System Catalog Tables

tables, aliases, synonyms, columns, sequences

  • SYSTABLES
  • SYSCOLUMNS
  • SYSSEQUENCES
  • SYSSYNONYMS

indexes

  • SYSINDEXES
  • SYSKEYS

routines, parameters

  • SYSROUTINES
  • SYSPARMS

constraints (relational, check, key)

  • SYSCHECKS
  • SYSCHECKDEP
  • SYSCHECKS2
  • SYSCONSTDEP
  • SYSTABCONST
  • SYSKEYCOLUSE
  • SYSRELS
  • SYSFOREIGNKEYS
  • SYSSEQUENCESDEP

views

  • SYSVIEWS
  • SYSVIEWDEP
Note: The user ID and password combination you use to connect to your mainframe must grant you READ access to your DB2 system catalog tables. For a complete list of required tables, see the topic Required DB2 Catalog Tables.

The Extract Schema tool does the following to create the schema extract file:

  • Connects to a DB2 database directly, or connects to a SQL Server database that contains z/OS DB2 catalog information migrated using the method outlined in Offline Extract Schema Solution.
  • Requests a list of available schemas
  • Populates the tool with the list of available schemas
  • Enables selection of specific schemas for migration
  • Enables selection of an estimated or actual table row count for each table in the schema
  • Generates an XML file containing a representation of the objects in the selected schemas, including:
    • Dependent objects such as dependent tables or views and tables referenced by a foreign key in a different table
    • Parameter values necessary to create the same schema objects in SQL Server 2008
  • Reports results
Parent topic: Extract Schema Tool


Offline Extract Schema Solution

Restriction: This topic applies to Windows environments only.

The HCOSS Extract Schema tool, when used as an online tool, requires a direct connection to DB2 for z/OS. In some production environments, this direct access can have a negative effect on the speed of regular business transactions on production databases, or can sometimes upset database security policy. To get around this, we provide a solution for schema extraction that can be done off line.

You can use Mainframe Batch Database Tools (MBDT) along with z/OS DB2 DSNUTILB UNLOAD to eliminate the need for direct access to the z/OS DB2 catalog. With this approach, the contents of the DB2 tables are unloaded from the mainframe using methods that either minimize or have no effect on z/OS DB2 processing. Once DB2 catalog tables are unloaded, you can use MBDT to load this information into SQL Server. This enables the Extract Schema tool to access the catalog via SQL Server.

This offline Extract Schema approach expands the existing HCOSS Toolset by altering only the Extract Schema step in the process of HCOSS database migration. All other steps, from Assess Data Migration to Compare Data, remain unchanged.

Like the online Extract Schema tool, the HCOSS Offline Extract Schema tool supports multiple versions of DB2 for z/OS, starting with Version 9.

Note: z/OS DB2 9 is no longer supported by IBM.

Unlike the online Extract Schema tool, which is one-step process, the offline tool requires that you perform multiple steps:

  1. Unload DB2 catalog tables from mainframe DB2 using z/OS DB2 DSNUTILB UNLOAD
  2. Import and catalog the unloaded data sets in Enterprise Server
  3. Create the DB2 catalog tables in SQL Server
  4. Load the data sets to SQL Server catalog tables using MBDT DSNUTILB LOAD
  5. Create foreign key references for the SQL Server catalog tables
  6. Run the Extract Schema tool with a SQL Server ADO.NET DSN

The following sections provide details for each step:

Important: All files referenced here as provided by Micro Focus are located by default in your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\hcoss directory.
Step 1: Unload catalog tables from z/OS DB2
Use the DB2 for z/OS batch utility, DSNUTILB UNLOAD, to unload the DB2 catalog tables for consumption by the MBDT DSNUTILB LOAD tool.

The SYSIBM schema contains 17 DB2 catalog tables that must be unloaded. To expedite this, Micro Focus provides the UNLOAD.parm file that contains all recommended UNLOAD cards. While some of the UNLOAD cards in UNLOAD.parm select an entire table, some of them select only a subset of the columns of a particular table. For example:

UNLOAD EBCDIC CCSID(00037,00037,00000)
DATA FROM TABLE SYSIBM.SYSPARMS
( SCHEMA,
  NAME,
  PARMNAME,
  ROWTYPE,
  ORDINAL,
  TYPENAME,
  LENGTH,
  SCALE,
  SUBTYPE,
  CCSID,
  ENCODING_SCHEME)

The purpose of selecting a subset of columns for some tables is to reduce the amount of data to unload, yet still provide enough information for the HCOSS Extract Schema tool to work successfully.

Important: When unloading, be sure to save the generated LOAD cards. These LOAD cards are used in Step 4.
Note: If you are using z/OS DB2 version 9, you must use the documented UNLOAD card provided for SYSIBM.SYSVIEWS in UNLOAD.parm rather than the one provided for z/OS DB2 version 10 or later.
Step 2: Copy the unloaded DB2 data and catalog it in Enterprise Server
Using Micro Focus Mainframe Access MFDAS IMPORT command-line tool, copy the unloaded DB2 data to your local Windows machine, and then catalog the data in an enterprise server region.
Preparing to copy and unload
Before you can run MFDAS IMPORT, you must create an enterprise server region that is enabled for both Mainframe Subsystem Support and Job Entry Subsystem (JES).

MFDAS IMPORT enables you to both copy and catalog all in one step, but you must run the tool separately for each extracted table. Therefore, you might consider creating a single batch file containing an MFDAS IMPORT command for each table.

Executing MFDAS IMPORT
You must run MFDAS IMPORT from an Enterprise Developer command prompt as an administrator. The method you use to do this varies depending on your operating system. See To start an Enterprise Developer command prompt as an administrator for details.

At your Enterprise Developer command prompt, run MFDAS IMPORT using the following syntax:

MFDAS IMPORT datFilePath\datFileName.dat
FROM QSAM mainframeDataSet /CATLOC=ESWorkArea\ESRegionName\catalog.dat

Where the variables are:

datFilePath
The path to a local directory on Windows where you want to store the file containing extracted unloaded data set data.
datFileName
The name of a data file to contain the extracted data.
mainframeDataSet
The name of the unloaded data set on the mainframe.
ESWorkArea
Your Enterprise Server WORKAREA folder, which by default is %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA.
ESRegionName
The name of your MSS- and JES-enabled enterprise server region.

For example, to copy and catalog the data set for SYSVIEWS, the command line might look like this:

MFDAS IMPORT C:\work\DB2CATALOG\SYSVIEWS.DAT FROM QSAM MFIXCH.UTILBTS.ULSYSVWS
/CATLOC=%USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREAEXSCHEMA\catalog.dat
Step 3: Create the DB2 catalog tables in SQL Server
To expedite the creation of DB2 catalog tables in SQL Server, Micro Focus provides the CREATECATALOG.sql script file. This file contains the SQL Server CREATE TABLE statements required to migrate the IBM catalog tables to SQL Server.

We recommended that you execute CREATECATALOG.sql from SQL Server Management Studio. Before execution, be sure that the SYSIBM schema exists in the SQL Server database.

Step 4: Load the data sets into SQL Server catalog tables
The MBDT DSNUTILB LOAD tool loads the imported and cataloged Enterprise Server data sets into SQL Server tables. Use the LOAD cards generated by z/OS DB2 DSNUTILB UNLOAD in Step 2 with some minor changes as follows:
  • Replace the RESUME YES with the REPLACE YES option
  • Specify the EBCDIC option explicitly to override the MBDT default of ASCII.

The following is a JCL example of MBDT DSNUTILB LOAD into a table in SQL Server:

//LDSYSPRM JOB
//DSNUPROC EXEC PGM=TSTUTILB,PARM='HCOD,SH      '
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//STPRIN01 DD   SYSOUT=*
//*COLSDISC DD   SYSOUT=*
//* DISCARDDN CHKSDISC DISCARDS 0
//IDIOFF   DD   DUMMY
//*
//SYSUT1   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSUT1
//SORTOUT  DD   DISP=MOD,DSN=SH.DSNUTILB.SYSOUT
//SYSMAP   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSMAP
//SYSERR   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSERR
//SYSREC   DD   DISP=SHR,DSN=MFIXCH.UTILBTS.ULSYSPRM
//SYSIN    DD   *
LOAD DATA INDDN SYSREC LOG NO  REPLACE YES
 EBCDIC  CCSID(00037,00037,65534)
 INTO TABLE
 "SYSIBM".
 "SYSPARMS"
 WHEN(00001:00002) = X'0146'
 NUMRECS                 1274
 ( "SCHEMA"
  POSITION(  00003:00132) VARCHAR
 , "NAME"
  POSITION(  00133:00262) VARCHAR
 , "PARMNAME"
  POSITION(  00263:00392) VARCHAR
 , "ROWTYPE"
  POSITION(  00393:00393) CHAR(001)
 , "ORDINAL"
  POSITION(  00394:00395) SMALLINT
 , "TYPENAME"
  POSITION(  00396:00525) VARCHAR
 , "LENGTH"
  POSITION(  00526:00529) INTEGER
 , "SCALE"
  POSITION(  00530:00531) SMALLINT
 , "SUBTYPE"
  POSITION(  00532:00532) CHAR(001)
 , "CCSID"
  POSITION(  00533:00536) INTEGER
 , "ENCODING_SCHEME"
  POSITION(  00537:00537) CHAR(001)
 )
/*
//
//*
Step 5: Create Foreign Keys for SQL Server catalog tables
To expedite the process of creating foreign keys for SQL Server catalog tables, Micro Focus provides the CREATECATALOGFK.txt file. This file contains SQL Server ALTER TABLE statements that enable foreign keys to be used properly with SQL Server. We recommended that you execute CREATECATALOGFK.txt from SQL Server Management Studio.
Step 6: Run the HCOSS Extract Schema tool against SQL Server
Create an ADO.NET connection to SQL Server using the HCOSS Manage Connections tool. Then, run the HCOSS Extract Schema tool:
From the command line:
Use the MFExtractSchemaInfo command with the DB2 argument set to your ADO.NET connection name. Set all other arguments the same as you would when running against DB2 for z/OS. For example:
MFExtractSchemaInfo DB2=HCODEMO; OUT=SCH81010; SCHEMA=DSN81010; TYPELOG=FILE

For complete information on running the Extract Schema tool from the command line, see MFExtractSchemaInfo command.

From the Extract Schema tool UI:
Follow the instructions in the topic To extract DB2 schema objects with the following exception:
  • In step 2, instead of providing a DB2 connection, click SQL Server DSN.

    This turns off the Table Row Count and Both Estimate and Actual options. If the actual table row count is required, use the UI version of the Assess Data Migration tool.

Note: Neither an ADO.NET connection to DB2 for z/OS nor a Microsoft OLE DB2 Provider for DB2 are required.
Parent topic: Extract Schema Tool
Related concepts
Manage Connections Tool
Mainframe Batch Database Tools (MBDT)
Related tasks
To extract DB2 schema objects
Related reference
MFExtractSchemaInfo command
MFDAS


Modifying Exporting and Importing Schema Extract Files

Restriction: This topic applies to Windows environments only.

Once you have created a schema extract file, you can use the Schema Extract tool to modify it, export it, and/or import it. The export and import features enable you to share schema extract files with multiple users, and to assist Micro Focus SupportLine in troubleshooting migration issues.

Parent topic: Extract Schema Tool


Extract Schema Security

Restriction: This topic applies to Windows environments only.

We offer two methods of implementing security with regard to catalog and mainframe access during the Extract Schema process:

Catalog Security
When catalog security is a concern, consider creating an additional schema containing views of SYSIBM DB2 catalog tables. This enables the user of the Extract Schema tool to extract from the new schema, and therefore does not require query access to the catalog tables themselves. If catalog security is not a concern, then anyone who runs the Extract Schema tool requires query access to the required DB2 catalog tables in the SYSIBM schema.
Mainframe Security
If your aim is to limit mainframe access to a single individual or system, you can use the Export and Import features of the Schema Extract tool to provide additional staff access to schema extract files without granting access to the mainframe.
Parent topic: Extract Schema Tool


Assess Data Migration Tool

Restriction: This topic applies to Windows environments only.

The Assess Data Migration tool enables you to examine extracted DB2 schemas to estimate the table sizes, and to identify the tables you want to migrate to your SQL Server database using HCOSS.

The Assess Data Migration Tool provides the following functionality:

  • Reads the content of an extracted schema file created using the Extract Schema tool.
  • Shows the contents of the extracted schema, including the following information for each table represented in the schema:
    • Creator
    • Name
    • Row count
    • Count type
    • Maximum row size
    • Data volume
    • Transfer option
    • Date of last update
  • Provides two count type options for each table:
    • Actual - Determined by running a query against the DB2 table on the mainframe. Depending on the table size, this could be time consuming; however, the results are reliably accurate.
    • Estimated - Based on the statistics collected by the DB2 RUNSTATS utility. While this is the most time-efficient method for determining table size, it is not always accurate because the statistics can be out of date.
    The default setting is based on the Table Row Count option you selected when extracting the schema.
  • Provides two data migration transfer options for each table represented in the extracted schema:
    • HCOSS - to migrate all data in the table
    • OTHER - to bypass migration of the data in the table
  • Updates the schema extract file with your changes.
  • Provides a report of error messages encountered when updating the schema extract file.
  • Enables you to save the extracted schema information as a flat text file or in CSV format compatible with spreadsheet software.
Parent topic: Migrating Databases
Related tasks
To assess data migration
Related reference
Data Assessment Tasks tab
Create New Data Assessment Task dialog box
Results tab
Schema Extract tab


Define Lists Tool

Restriction: This topic applies to Windows environments only.

Use the Define Lists tool to select specific tables and views with which to generate a list of objects to transfer to your SQL Server database. The Generate DDL tool uses this list to create SQL Server objects. You can run the tool either from the HCOSS user interface, or from the command line using the MFObjectList command.

The Define Lists tool includes the following functionality:
  • Reads the XML file generated by the Extract Schema tool
  • Provides a list of available objects
  • Enables selection of specific objects to transfer
  • Saves the transfer information to a file, enabling future editing of the list
    Note: You cannot change the source schema for an existing transfer list unless it is empty.

HCOSS uses the saved transfer information in the next step of the database migration process - generating DDL tasks to move the data.

Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To define an object transfer list
Related reference
MFObjectList command
Define Lists Tool Log Files
Define Lists Tool Error Messages
Transfer Lists tab
Create New List dialog box


Generate DDL Tool

Restriction: This topic applies to Windows environments only.

Use the Generate DDL tool to create the DDL script used to migrate your DB2 schema objects to your SQL Server database. Each script you create is one DDL task. As with the other HCOSS tools, you name your DDL tasks and store them in a local or shared location.

You can run the Generate DDL tool either from the HCOSS user interface, or from the command line using the MFDDLConverter command.

To run the Generate DDL tool, you must have:
  • A schema extract file containing schema objects, created using the Extract Schema tool.
  • An object transfer list created using the Define Lists tool.
  • A connection to your production SQL Server database against which to execute your DDL scripts. Optional if you're using the tool only for the purpose of exporting a DDL script.
  • A connection to a test SQL Server database (optional).
The Generate DDL tool includes the following functionality:
  • Reads the schema extract file, filtered by the object transfer list that specifies the objects you want to migrate
  • Translates the database structure found in the extracted schema and transfer list, including schemas, tables, views, indexes, constraints, and relational information, into a SQL Server 2008 DDL script
  • Creates DDL script commands that drop and create objects, or restore missing objects in the SQL Server database
  • Maps DB2 data types to SQL Server 2008 data types
  • Creates tables using data type mappings defined in the Customize Type Mappings tool
  • Enables you to customize DDL at the object level
  • Enables you to edit schema mappings
  • Tests DDL task specifications against a test SQL Server data source
  • Executes generated DDL against your production SQL Server
  • Enables you to export the generated DDL as an SQL script
  • Reports results of DDL test runs and executions

HCOSS uses DDL tasks in the next step of the database migration process - transferring the data to the SQL database.

Note: HCOSS does not support XML indexes. Therefore, no XML indexes existing in the DB2 database are created in the DDL. Likewise, any column that is part of an index and is mapped to the SQL Server XML data type is not created. This is true even if the originating DB2 index and column are of XML type but are mapped to the XML data type.
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


Transfer Data Tool

Restriction: This topic applies to Windows environments only.

Use the Transfer Data tool to build and execute an SSIS package for each table you want to migrate from the DB2 database to the SQL Server database. Each transfer you define is one Transfer Data task. You can run the Transfer Data tool either from the HCOSS user interface, or from the command line using the MFDataTransferCtlr command.

As with the other HCOSS tools, you name your data transfer tasks and store them in a local or a shared location.

To run the Transfer Data tool, you must have:
  • A connection to your DB2 database
  • An associated DDL task
  • A connection to your SQL Server database
The Transfer Data tool includes the following functionality:
  • Reads the DDL task you created with the Generate DDL tool
  • Builds one SSIS package for each table specified in the associated DDL task
  • Executes SSIS packages to transfer data for all tables defined in the associated DDL task
  • Enables you to customize your Transfer Data tasks from the DB2 database to the SQL Server database by providing specifications for handling logs, errors, triggers, constraints, and source table row counts, and including WHERE and/or ORDER BY clauses in SELECT statements.
    Note: Ensure that the required schema objects are in place in the destination SQL Server database before executing a data transfer task.
  • Enables you to export SSIS packages
  • Reports results

The Transfer Data tool automatically names and saves each SSIS package it builds, and stores them in the same local or shared location as the transfer data tasks. SSIS package files use the following naming convention:

tableName_RunTimePackage.dtsx.

  • SSIS Packages
  • Data Type Support
  • Data Transform Types
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To transfer data
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files
Transfer Data Tool Error Messages
Transfer Data Tasks tab
Create New Transfer Data Task dialog box
Customize Transfer Data tab
Results tab


SSIS Packages

Restriction: This topic applies to Windows environments only.

HCOSS transfers data from DB2 databases to SQL Server 2008 databases by building one SQL Server Integration Services (SSIS) package for each of the database tables selected for transfer, and then executing these packages.

An SSIS package is a collection of SQL script commands. When you execute an SSIS package, the SSIS engine runs each script in sequence. We chose SSIS packages as the mechanism to transfer data because they are a flexible and efficient deployment option. You can schedule, script, customize, extend, and integrate SSIS packages using SQL Server and Eclipse tools. SSIS packages can also be reused by the Execute Package Utility of SQL Server Integration Services, and it can be loaded into the SQL Server Business Intelligence Development Studio for debugging purposes.

For more information about SSIS packages, see the documentation for the Microsoft SQL Server Development Center, available on the Microsoft Web site.

Parent topic: Transfer Data Tool


Data Type Support

Restriction: This topic applies to Windows environments only.

While most of the data types in DB2 are supported by the tool, there are a few exceptions.

Lack of support may be due to a delay between a new type being added to DB2 and support for the new type being added to provider APIs, or because SQL Server does not have a suitable type to map the new DB2 type to. For instance, DECFLOAT (16 byte float) and XML are among the new data types added to DB2 for z/OS v9.1. Because there is no corresponding 16 byte float data type in SQL Server 2008, both the Microsoft and IBM OLE DB Providers output it as 8 byte float, suffering from potential loss of precision.

The BLOB data type is not supported by the current version (2.0) of Microsoft OLE DB Provider for DB2. Check with Microsoft to see when this data type will be supported. For the XML data type, neither Microsoft OLE DB Provider for DB2 supports it nor does IBM OLE DB Provider, in their current versions. The IBM DB2 .NET Data Provider is a promising alternative to the OLE DB Providers for DB2, as it supports the XML data type. It will be incorporated in the tool in the future. However, its current version (v9.5.3) wrongly outputs DECFLOAT(p) as Numeric(p,0) with 0 scale, where p stands for the precision.

For SQL Server 2008, the SQL Server OLE DB/Native Client supports all the incoming data types.

Parent topic: Transfer Data Tool


Data Transform Types

Restriction: This topic applies to Windows environments only.

There are two types of data transforms that may occur in the data transfer process. The first type is explicit from the point view of an SSIS package, the conversion between Unicode characters and non-Unicode characters. This conversion is automatically handled by the tool, which adds an SSIS Data Transform component to the package.

The second type is implicit, the conversion between subtypes of the same data type, such as conversion between DataTime and DataTime2, conversion between REAL and FLOAT. This type of conversion is handled internally by the SQL Server Database engine and there is no need to add a Data Transform component to the package.

Parent topic: Transfer Data Tool


Compare Data Tool

Restriction: This topic applies to Windows environments only.

Use the Compare Data tool after transferring data to verify and compare the newly imported data with the original data. As with the other HCOSS tools, you create and name compare data tasks and store them in a local or shared location. You can run the Compare Data tool either from the HCOSS user interface, or from the command line using the MFTestConversion command.

To run the Compare Data tool, you must have:
  • A connection to your DB2 database
  • An associated DDL task
  • A connection to your SQL Server database
The Compare Data tool includes the following functionality:
  • Reads the data from the DB2 database source connection and the SQL Server database destination connection
  • Compares the data found in each
  • Shows the results for each row of data that was transferred from the source connection to the destination connection
Parent topic: Migrating Databases
Related concepts
DB2 Database Migration Process
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Log Files
Compare Data Tool Error Messages
Compare Data Tasks tab
Create New Compare Data Task dialog box
Customize Compare Data tab
Results tab


Mainframe Batch Database Tools

Enterprise Developer provides a series of batch tools to assist you in migrating mainframe databases. See Mainframe Batch Database Tools (MBDT) for complete information.

Parent topic: Migrating Databases
Related concepts
Mainframe Batch Database Tools (MBDT)


Migrating Applications

Restriction: This topic applies to Windows environments only.

HCO for SQL Server (HCOSS) provides tools and methods for migrating mainframe-based DB2 applications to Windows-based SQL Server applications.

  • Assess Application Migration Tool
  • Application Migration Process
  • DB2 to SQL Server Conversion
  • Application Database Support
  • Binding Applications
  • Manage Packages and Plans Tool
  • DSN Bind Utility
  • Managing DBRMs
  • Running Applications
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
HCOSS Toolset
Why You Should Use the Assess Application Migration Tool


Assess Application Migration Tool

Restriction: This topic applies to Windows environments only.

The Assess Application Migration tool provides you with a blueprint for how prepare your source code for successful migration to SQL Server by reporting the errors you might encounter when DB2 EXEC SQL statements are executed on SQL Server. This is done by providing detailed information for several conversion scenarios. Before migrating your applications to SQL Server, we strongly recommend that you analyze your application's migration potential using this tool.

  • Why You Should Use the Assess Application Migration Tool
  • Migration Scenarios
  • Supported Source Code
  • Processing Requirements
Parent topic: Migrating Applications
Related tasks
To assess application migration
To export assessment results
Related reference
Assessment Tasks tab
Create New Assessment Task dialog box
Results tab
Source Code tab
SQL Conversion tab


Why You Should Use the Assess Application Migration Tool

Restriction: This topic applies to Windows environments only.
When considering application migration from mainframe DB2 to SQL Server, you need answers to these important questions:
  • How fast can I get my application migrated, up, and running on SQL Server?
  • How do I figure out how heavily my application relies on mainframe technology?
  • How can I eventually eliminate all reliance on mainframe technology such that my application uses SQL Server exclusively?
The Assess Application Migration tool helps you to analyze your COBOL and PL/I code with these questions in mind, and provides valuable information that guides you in determining the best migration option for your application. Using HCOSS, you have several options. You can:
Migrate your code as-is to SQL Server
Use this option if your goal is to get up and running as quickly as possible with SQL Server, without a dependency on mainframe compatibility or behavior. This is a great option if you have few statements to remediate, and you want to eliminate mainframe behavior dependency immediately.
Migrate converted DB2 statements to SQL Server statements
Use this option if you want to identify all SQL DB2 statements that require conversion to SQL Server statements to ensure 100% SQL Server compatibility after migration, and manually convert that code before migration. Contact Micro Focus SupportLine for more information on this approach.
Migrate your original code using HCOSS without the BIND option
Use this option if your goal is to get up and running as quickly as possible with SQL Server, but you do not want to BIND your application. This approach requires that you remediate SQL package and plan statements.
Migrate your original code using full HOCSS functionality
Use this option if your goal is to get up and running as quickly as possible with SQL Server. This option exploits all HCOSS functionality and ensures that your application runs with mainframe compatibility.
We also recommend that you use the Assess Application Migration tool Data Analysis feature to analyze your schema extract files and identify structures that are not supported by SQL Server, or that could require manual modification before HCOSS can accurately transfer the data to SQL Server. Data analysis includes the identification of:
  • SQL data types
  • SQL Stored Procedures written in an unsupported application language
  • SQL Sequences
  • Defined Global Tables
  • SQL ALIAS objects
  • SQL SYNONYMS
Parent topic: Assess Application Migration Tool
Related concepts
HCOSS Toolset
Migrating Applications
Application Migration Process
Migration Scenarios
Related tasks
To analyze schema extract data
Related reference
Data Analysis tab


Migration Scenarios

Restriction: This topic applies to Windows environments only.
The Assess Application Migration tool runs a multi-phase process to determine the migration potential of each SQL statement contained in your original IBM z/OS mainframe DB2 SQL. The tool considers and reports on the following four scenarios for each source file containing DB2 EXEC SQL code:
  • As is - use existing DB2 SQL code as is.
  • Code convert - convert the DB2 SQL code to T-SQL code.
  • HCOSS no BIND - convert the DB2 SQL code using SQL(DIALECT) only.
  • HCOSS with BIND - convert the DB2 SQL code using both SQL(DIALECT) and SQL(DBRMLIB). For more information, see the Manage Packages and Plans Tool and DSN BIND utility topics.
For each scenario, the tool reports the total number of DB2 SQL statements that fall into these categories:
  • OK - statements that can be likely migrated to SQL Server without alteration
  • Must fix - statements that are not compatible with SQL Server and require a manual code change
  • In doubt - statements for which HCOSS cannot determine migration potential
Parent topic: Assess Application Migration Tool
Related concepts
Manage Packages and Plans Tool
DSN Bind Utility
Why You Should Use the Assess Application Migration Tool
Related tasks
To assess application migration
Related reference
DSN command


Supported Source Code

The Assess Application Migration tool supports COBOL and PL/I program and copybooks, and PL/I source code files to determine their migration potential. This includes files with the following file extensions:
  • .cob
  • .cbl
  • .cpy
  • .sqb
  • .pli
  • .pl1
  • .inc
  • .plinc
Parent topic: Assess Application Migration Tool


Processing Requirements

Before processing source files, the Assess Application Migration tool requires that you provide the following information:
  • A SQL Server connection name
  • A COBOL or PL/I source code and copybook root directory to examine
  • The COBOL or PL/I source code and copybook files to include
  • A default qualifier (optional)
  • The level of error reporting
Parent topic: Assess Application Migration Tool


Application Migration Process

Restriction: This topic applies to Windows environments only.

Host Compatibility Option for SQL Server (HCOSS) and OpenESQL provides features and tools that assist in migration of mainframe applications that use DB2 to applications that run on Windows and use SQL Server. HCOSS also includes tools that enable you to migrate DB2 databases.

Note: All DB2 application components must reside either on your machine or on your local area network before beginning the migration to SQL Server.

You can use a combination of the following tools and features to achieve successful COBOL application migration, which includes building and binding an application:

HCOSS Assess Application Migration tool
Used to determine the best method of migration you can use to automatically convert your DB2 SQL code to SQL Server.
HCOSS Manage Connections tool
Used to create a connection to the SQL Server database.
HCOSS Manage Packages and Plans tool
Used to bind DBRM members into packages and plans, and to bind packages into plans. It also generates and saves BIND commands to bind script (.hcodsn) files you can execute using the DSN Bind utility.
DSN Bind utility
A free-standing Windows command-line utility used to achieve mainframe-like binding using a subset of the functionality of the mainframe DSN utility. This option is available if you do not create bind scripts that bind the application during the build process
HCOSS-specific OpenESQL SQL compiler directive options
Provide SQL syntax compatibility between DB2 and SQL and also provide binding functionality.

While you can choose from other methods of application migration using HCOSS, the basic and recommended process of COBOL and PL/I application migration includes:

  1. Using the HCOSS Manage Connections tool, connect to your SQL Server database.
  2. In Eclipse, create a project based on the COBOL Native Console Application template.
  3. Using the Assess Application Migration tool, determine the SQL conversion method that best fits your COBOL or PL/I source code.
  4. Take appropriate steps to convert your source code, based on your selected conversion method. This could include manually fixing your existing code based on the findings reported in the Assess Application Migration tool, or using HCOSS with or without the BIND option to convert the code based on the HCOSS DB2 to SQL Server Conversion mappings.
  5. Add mainframe or converted COBOL or PL/I source code to the project.
  6. Add appropriate SQL OpenESQL compiler directive options in the project properties.
  7. Also in the project properties, add a post-build event that runs the DSN command and binds the application to the SQL Server database.
  8. Build the application, automatically binding the application to the database.
  9. Run the application.
Parent topic: Migrating Applications
Related concepts
Building Applications
Running Applications
Binding Applications
Manage Connections Tool
Why You Should Use the Assess Application Migration Tool
Related tasks
To assess application migration
To bind as a post-build event


DB2 to SQL Server Conversion

Restriction: This topic applies to Windows environments only.

You can set HCOSS to automatically convert DB2 statements to SQL Server statements. The conversion details are determined by a set of rules and defaults, some of which are customizable.

HCOSS DB2 to SQL Server conversion is triggered by setting the DIALECT compiler directive option to either MAINFRAME or MIXED. HCOSS converts all DB2 statements automatically, and converts DB2-compatible SQL Server statements as specified using statement prefixes.

The following topics provide important information on key features of HCOSS that enable you to optimize DB2 to SQL Server conversion:

  • HCOSS Conversion Rules
    Outlines the rules HCOSS uses to convert DB2 statements to SQL Server statements.
  • SQL Code Generation Options
    An overview of the SQL code generation options available with HCOSS.
  • SQL Statement Prefixes for DIALECT Directive
    Describes the statement prefixes you can use to adjust DB2 to SQL Server conversion specifications on the statement level when compiling with the DIALECT directive.
  • Application Progression from DB2 to SQL Server
    Provides a scenario for progressing an application from a DB2 mainframe application to a SQL Server application over time.
  • Building Applications
Parent topic: Migrating Applications
Related reference
Default Data Type Mappings
Default SQLCODE Mappings
Default Function Mappings
Default Special Register Mappings
DIALECT
Date and Time Data Types


HCOSS Conversion Rules

Restriction: This topic applies to Windows environments only.

The following apply to HCOSS DB2 to SQL Server conversion:

  • Converts DB2 functions and special registers to SQL Server functions and special registers according to a set of the defaults that best match one to the other. Customizable.
  • Converts DB2 data types to SQL Server data types according to a set of defaults that best match one to the other. Customizable.
  • Converts DB2 SQLCODE values to equivalent SQL Server SQLCODE values. Customizable.
  • Optimization of DB2 SQL statements is allowed and done by adding SQL Server query hints, such as OPTION(RECOMPILE), to select, insert, update, and delete statements.
  • Concatenation of SQL Server SQL TYPE BINARY and SQL TYPE VARBINARY data according to DB2 rules is done via the CONCAT_BINARY function and operator.
  • Applications that concatenate z/OS DB2 BINARY or VARBINARY values to use CONCAT_BINARY must be manually converted when migrating to SQL Server.
  • CONCAT_BINARY is converted to the HCOSS-supplied dbo.CONCAT_BINARY call.
  • For SQL Server 2012 SP2 and later, DECLARE GLOBAL TEMPORARY statements support:
    • SQL(CHECK), at compile time
    • Both AS and LIKE clauses, in addition to column definition specifications

To learn more about changing HCOSS default settings for DB2 functions and special registers, data types, SQLCODE values and SQL identifiers, see Customizing HCOSS. To review HCOSS default settings and additional support information for these items, see DB2 to SQL Server Conversion Reference.

Parent topic: DB2 to SQL Server Conversion
Related concepts
Customizing HCOSS
Related reference
DB2 to SQL Server Conversion Reference


SQL Code Generation Options

Restriction: This topic applies to Windows environments only.

Before you begin compiling, testing, and executing your HCOSS code, consider what you want HCOSS to do for you.

To convert the mainframe SQL in my programs such that it works with SQL Server
Set the DIALECT SQL compiler directive option to MAINFRAME to convert all SQL, or MIXED to convert selected EXEC SQL statements in the code. To fully enable compile-time checking of converted SQL statements using SQL Server, set the DB, PASS and QUALIFIER directives along with DIALECT=MAINFRAME or DIALECT=MIXED. For additional information, see the DIALECT Statement Prefixes and the Application Progression from DB2 to SQL Server topics.
To mimic mainframe-style binding with my application
Specify the DBRMLIB SQL compiler directive option. If required to fully emulate your mainframe setup, you can also specify the MEMBER and VERSION directives. For additional information, see the Building Applications topic.
Note: Packages and plans are stored as SQL Server stored procedures.
To manage the application using SQL Server stored procedures
For HCOSS to manage your application using SQL Server stored procedures for your applicable SQL statements, but not manage them via packages or plans, specify either the ACCESS or BIND SQL compiler directive option.
Only to embed SQL into the generated code
To have HCOSS simply embed SQL into the generated code, no compiler directive options are required. This is the default behavior.

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.
DBRMLIB1 Enables generation of DBRMs containing the static SQL statements from COBOL programs, mimicking mainframe-style binding.
  • Mainframe deployment compatibility, meaning you can bind using existing JCL.
  • You can bind a DBRM multiple times using different parameters each time, such as different default qualifiers.
  • You can apply security separately to procedures and data so that application users can only access and update data via the application.
  • You can use the Manage Packages and Plans tool to manage DBRM binding and freeing.
  • Enables HCOSS to maintain mainframe-compatible metadata in the database for bound packages and plans.
  • DBAs can review SQL after binding by browsing stored procedures without having to access source code.
DIALECT2 Converts DB2 SQL statements that are not compatible with SQL Server into equivalent T-SQL statements in most cases.
  • You do not need to convert DB2 statements to T-SQL.
  • You can change the default schema when a program is bound, or in some cases, change the default schema at compile time using the QUALIFIER SQL compiler directive option.
1 For additional information, see also the Building Applications topic.

2 For additional information, see also the DIALECT Statement Prefixes and the Building Applications topics.

Parent topic: DB2 to SQL Server Conversion
Related concepts
SQL Statement Prefixes for DIALECT Directive
Application Progression from DB2 to SQL Server
Building Applications
Related reference
BIND
DBRMLIB
DIALECT


SQL Statement Prefixes for DIALECT Directive

Restriction: This topic applies to Windows environments only.

DIALECT statement prefixes enable you to specify DB2 to SQL Server conversion details for individual EXEC SQL statements, including SQL Server statements that conform to DB2 syntax. In this way, you can apply certain overrides and conversion routines to DB2-compatible SQL Server statements, such as qualification of unqualified tables and views, on an as-needed basis.

Over time, your migrated applications can evolve to use syntax that is specific to SQL Server rather than DB2. When compiling an application using the DIALECT=MAINFRAME compiler directive option, by default HCOSS assumes all statements are DB2 statements and converts them to SQL Server statements using the specifications provided by defined HCOSS data type mappings, SQL name mappings, and SQLCODE mappings. HCOSS also applies qualifiers for unqualified tables and views based on the use of the SQL(QUALIFIER) compiler directive option or the QUALIFIER parameter on a BIND PACKAGE or BIND PLAN command. Also by default, HCOSS applies no conversions to existing SQL Server statements, submitting them directly to the SQL Server database.

When compiling with DIALECT=MIXED, the conversions described above are only performed for statements that have a prefix of [MAINFRAME], and HCOSS assumes that by default all statements are SQL Server statements.

The choice between DIALECT=MAINFRAME and DIALECT=MIXED depends on whether the majority of statements should be processed as DB2 or SQL Server statements.

Syntax:

A statement prefix is coded directly into an EXEC SQL statement as follows:
EXEC SQL [statementPrefix]... SQLStatement END-EXEC

Parameters:

statementPrefix
[NOPLAN]
The SQLStatement is not written to a DBRM even if SQL(DBRMLIB) is specified, but instead treats the statement as dynamic SQL at runtime. When used with other prefixes, [NOPLAN] must be specified first.
[MAINFRAME]
The SQLStatement is converted and qualified by HCOSS.
[NODIALECT]
The SQLStatement is neither converted nor qualified by HCOSS.
SQLStatement
Any DB2 statement, or DB2-compatible SQL Server statement.

Dependencies:

Statement prefixes must be used in conjunction with the DIALECT compiler directive option.

Examples:

All of the following examples assume that DIALECT is set to either MAINFRAME or MIXED, and all SQLStatements are DB2 compatible.

Example 1

The QUALIFIER compiler directive option is not set, and there is no specified QUALIFIER parameter.

EXEC SQL [NOPLAN] SQLStatement END-EXEC

The SQLStatement is converted but not qualified by HCOSS; it is not written to a DBRM, not written to a bind script file even when the BIND compiler directive option is set, and not used to create a stored procedure at compile time even when ACCESS compiler directive option is set.

Example 2

The QUALIFIER compiler directive option is set.

EXEC SQL [MAINFRAME] SQLStatement END-EXEC

The SQLStatement is converted and qualified by HCOSS.

Example 3

The QUALIFIER compiler directive option is set.

EXEC SQL [NOPLAN][MAINFRAME] SQLStatement END-EXEC

The SQLStatement is converted and qualified by HCOSS but is not written to a DBRM.

Example 4

The QUALIFIER compiler directive option is set.

EXEC SQL [NODIALECT] SQLStatement END-EXEC

The SQLStatement is neither converted nor qualified by HCOSS.

Example 5

The BIND or DBRMLIB compiler directive is set, along with the QUALIFIER compiler directive.

EXEC SQL [NOPLAN][NODIALECT] SQLStatement END-EXEC

The SQLStatement is neither converted nor qualified by HCOSS and is not written to a bind file or DBRM.

Parent topic: DB2 to SQL Server Conversion
Related concepts
Application Progression from DB2 to SQL Server
SQL Code Generation Options
Related reference
DIALECT
QUALIFIER


Application Progression from DB2 to SQL Server

Restriction: This topic applies to Windows environments only.
As your application progresses from being a mainframe DB2 application to being a SQL Server application with no residual dependencies on mainframe characteristics, the combination of DIALECT settings and statement prefixes required when compiling and binding change, depending on the stage of the progression, to ensure optimal DB2 to SQL Server conversion results. The following scenario suggests each stage of application progression along with the combination of DIALECT and statement prefix settings recommended for each stage:
Stage 1 - All statements are DB2 compatible
Recommended settings:
DIALECT Setting | Statement Prefix
MAINFRAME | None
The preprocessor attempts to process all statements as DB2 statements and issues a DB2 compatibility warning on each statement that HCOSS does not recognize as a valid DB2 statement, but that is otherwise compatible with SQL Server. Only statements that compile without DB2 compatibility warnings are qualified by the QUALIFIER compiler directive or BIND parameter.
Stage 2 - Some statements are SQL Server specific; most are mainframe compatible
Recommended settings:
DIALECT Setting | Statement Prefix
MAINFRAME | [NODIALECT] on statements you want to flag as SQL Server compatible

The [NODIALECT] prefix suppresses the DB2 compatibility warning on statements that are only compatible with SQL Server. Since. due to the DIALECT=MAINFRAME setting, these statements are not qualified by the QUALIFIER compiler directive option or the BIND QUALIFIER parameter, ensure that the statements are either explicitly qualified in the source code or that the default schema for the connection points SQL Server to the correct schema.

Stage 3 - Most statements are SQL Server compatible
Recommended settings:
DIALECT Setting | Statement Prefix
MIXED | [MAINFRAME] on statements that fail with SQL(CHECK) and that are not ready for conversion to SQL Server

You may remove [NODIALECT] prefixes at this stage if you want, but it is not required.

Stage 4 - First class SQL Server Application
Recommended settings:
DIALECT Setting | Statement Prefix
NONE | None

Remove all [MAINFRAME] and [NODIALECT] statement prefixes specified for previous stages. These prefixes cause compilation errors when DIALECT is set to NONE. However, you can specify the [NOPLAN] prefix on statements of your choice.

Parent topic: DB2 to SQL Server Conversion
Related concepts
SQL Code Generation Options
Related reference
DIALECT
QUALIFIER
SQL Statement Prefixes for DIALECT Directive


Building Applications

Restriction: This topic applies to Windows environments only.

Because your migrated application originated in a mainframe environment, the run-time application expects to find all of the appropriate SQL statements in packages and/or plans that reference database request modules (DBRMs). DBRMs contain the SQL statements extracted from the application source code during compilation.

To mimic this mainframe behavior, HCOSS provides a set of SQL compiler directive options that enable you to extract the EXEC SQL statements in your application source code into DBRMs as you compile the application. In a post-compilation step, you then bind the DBRMs to the application so that they can be accessed at run time.

The following sample use case scenarios show typical SQL compiler directives you might set for HCOSS applications:

Type of Program | Scenario | SQL Compiler Directive Options
COBOL | Create DBRMs, and bind like the mainframe | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER, DB=databaseName, [PASS=userid.password, ]BEHAVIOR=OPTIMIZED, DIALECT=MAINFRAME, DBRMLIB)1
COBOL | Create DBRMs, bind like the mainframe, but do not connect to the database during compilation | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER,BEHAVIOR=OPTIMIZED, DIALECT=MAINFRAME, DBRMLIB, NOCHECK)1
COBOL | Do not create DBRMs, and do not create SQL Server stored procedures | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER, DB=databaseName, [PASS=userid.password, ] BEHAVIOR=OPTIMIZED, DIALECT=MAINFRAME)1
COBOL | Do not create DBRMs, do not create SQL Server stored procedures, and do not connect to the database during compilation | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER, BEHAVIOR=OPTIMIZED, DIALECT=MAINFRAME, NOCHECK)1
PL/I | Create DBRMs, and bind like the mainframe | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER, DB=databaseName, [PASS=userid.password, ] BEHAVIOR=OPTIMIZED, DIALECT=MAINFRAME, DBRMLIB)1
PL/I | Create DBRMs, bind like the mainframe, but do not connect to the database during compilation | SQL(DBMAN=ODBC, TARGETDB=MSSQLSERVER, DB=databaseName, [PASS=userid.password, ] BEHAVIOR=OPTIMIZED, DIALECT=MAINFRAME, DBRMLIB, NOCHECK)1
1 DIALECT=MAINFRAME automatically sets CHECK, CHECKDUPCURSOR, CHECKSINGLETON, DETECTDATE, DATE=ISO, TIME=ISO

In the IDE, you compile applications by building the projects that contain them. When you build an HCOSS application, you must first set appropriate SQL compiler directive options, and in most cases, establish a connection to your SQL Server database.

In addition to the standard SQL compiler directive options, HCOSS includes these specific options to handle application binding and SQL compatibility between DB2 and SQL Server:
  • ACCESS
  • BIND
  • DATE
  • DBRMLIB (required)
  • DIALECT (required)
  • MEMBER
  • QUALIFIER
  • TIME
  • VERSION
At a minimum, edit your project's SQL properties to set the following compiler directive options for the OpenESQL ESQL preprocessor to ensure that the build process generates the appropriate DBRMs and converts DB2 SQL into SQL Server SQL where necessary.
  • DBMAN - set this to ODBC.
  • TARGETDB - set this to a value of MSSQLSERVER.
  • DB - set this value to your SQL Server data source connection name
  • PASS - if your data source connection requires that you provide a user ID and password to connect, provide a user ID and password as follows:

    userID.password

  • DBRMLIB
  • DIALECT - set this to a value of MAINFRAME.
  • DETECTDATE
  • INIT

Before compiling, unless you have specified the SQL(NOCHECK) directive, you must be connected to the database specified by the DB directive via an ODBC connection.

Note: To set the SQL(NOCHECK) directive, you must add it such that it lists after the SQL(DBRMLIB) directive.
Parent topic: DB2 to SQL Server Conversion
Related concepts
Binding Applications
Application Migration Process
SQL Code Generation Options
Related reference
DATE
DBRMLIB
DIALECT
MEMBER
QUALIFIER
TIME
VERSION
Build error messages


Application Database Support

Restriction: This topic applies to Windows environments only.

HCOSS database migration tools transfer customer data from mainframe DB2 databases to SQL Server databases.

HCOSS also provides SQL Server functions and metadata tables that enable SQL Server databases to emulate DB2 mainframe behavior and facilities. This additional SQL Server support consists of:

  • Scalar SQL functions that emulate mainframe DB2 SQL; required when you use DIALECT=MAINFRAME
  • Metadata tables and SQL functions that emulate mainframe DB2 packages and plans; required when you use the DBRMLIB directive and the DSN BIND utility

You can add HCOSS DB2 emulation support to a new or an existing SQL Database using either of these methods, depending on whether or not you use the DBRMLIB HCOSS SQL compiler directive option:

When using DBRMLIB
All additional SQL Server support is added to your database at BIND time. If your HCOSS installation has been updated by a new release of Enterprise Developer, or by a Hot Fix installation, new versions or additional functions are updated automatically at the first BIND after the new installation. For more information, see Binding Applications
When not using DBRMLIB
Run the following scripts manually from SQL Server Management Studio. We recommend that you run all three scripts on a new database even if you do not plan to use the DBRMLIB support. The user running these scripts must have read, update, and create permissions to the SYSIBM and dbo schemas in the database.

By default, these scripts are installed in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory:

  • InstallDigitsFunction.sql - adds DB2 SQL emulation functions
  • InstallSYSIBM.sql - installs HCOSS metadata tables
  • InstallBindProcs.sql - installs the functions required to maintain HCOSS metadata tables
Note: After you have run these scripts once, subsequent release or HotFix installations require that you run just the InstallDigitsFunction.sql script unless the readme that accompanies the new installation specifies otherwise.
Parent topic: Migrating Applications
Related concepts
HCOSS Toolset
Binding Applications
DSN Bind Utility
Related reference
DBRMLIB
DIALECT


Binding Applications

Restriction: This topic applies to Windows environments only.

Once you have built your application such that it generates the necessary DBRMs, you must bind the DBRMs to your application by directly binding the DBRMs, or by binding the DBRMs into packages and/or plans that can be accessed by your run-time application.

You have several options for binding applications:
  • Use the Manage Packages and Plans tool to generate bind script files (.hcodsn files) containing BIND script commands that you can execute immediately to achieve application binding, or that you can save for later execution.
  • Use the Manage Packages and Plans tool to create and save bind script files to execute using the DSN Bind utility at a command prompt or as a post-build event.
  • Manually code bind script files to execute using the DSN Bind utility at a command prompt or as a post-build event.
    Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.
  • Bind from JCL by coding DSN commands directly into the JCL.

Whether you bind your applications via the Manage Packages and Plans tool or directly with the DSN Bind utility, the results are the same. This is because the Manage Packages and Plans tool actually runs the DSN Bind utility for you when you execute a script command.

We recommend that you bind your applications by creating collections and packages from DBRM members and then binding those packages to one or more plans. This method offers a significant advantage over binding DBRM members directly into a plan. For example, if you need to change the SQL in a single source member, and that source member is bound into a package that has been bound into a plan, you only need to rebind the changed member to its package. However, if the changed member is bound directly into a plan, you must rebind the entire plan to include the change.

Parent topic: Migrating Applications
Related concepts
Manage Packages and Plans Tool
DSN Bind Utility
Local DBRMs
Managing DBRMs
Shared DBRMs and multi-user environments
Building Applications
Running Applications
Application Migration Process
Freeing Packages and Plans
Application Database Support
Related tasks
To create a bind script file
To open an existing bind script file
To create a new package
To create a new plan
To edit an existing BIND command
To execute one or all bind script lines
To free one or more packages
To free one plan or all plans
To bind from the command line
To bind as a post-build event
To manually code a bind script file
Related reference
BIND
Assessment Tasks tab
DSN command
Bind Script Commands


Manage Packages and Plans Tool

Restriction: This topic applies to Windows environments only.

Use the Manage Packages and Plans tool to create and edit bind script files that contain BIND commands. You can execute these scripts from the Manage Packages and Plans tool, or save them to execute later with the tool or using the DSN Bind utility. The tool also enables you to free (clean out) old or unused packages and plans from your SQL Server database.

With regard to binding applications, the Manage Packages and Plans tool provides the following functionality:
  • Generates BIND commands according to specifications you provide.
    Note: You can also bind applications on your deployment server as well as your development server; however, to do this you must have appropriate permissions on the deployment server machine.
  • Saves the commands in bind script files (.hcodsn files) to any location you specify so that you can open, edit, and execute the commands again at any time.
  • Reports BIND command errors.
  • Executes one, some, or all of the BIND commands in your script file to either generate stored procedures that populate the SYSIBM schema or remove stored procedures that already exist in your SQL Server database.
With regard to freeing packages and plans, the Manage Packages and Plans tool provides the following functionality:
  • Free packages, removing associated system table data and associated stored procedure(s) from your SQL Server database
  • Free plans, removing associated system table data and associated stored procedure(s) from your SQL Server database, and removing package associations to the plan
  • Package Specifications
  • Plan Specifications
  • Freeing Packages and Plans
Parent topic: Migrating Applications
Related concepts
Manage Packages and Plans Tool
DSN Bind Utility
Binding Applications
Freeing Packages and Plans
Migration Scenarios
Related tasks
To create a bind script file
To open an existing bind script file
To create a new package
To create a new plan
To edit an existing BIND command
To execute one or all bind script lines
To free one or more packages
To free one plan or all plans
Related reference
BIND
Assessment Tasks tab
Bind Scripts tab
Bind Packages tab
Bind Plans tab
Free Packages tab
Free Plans tab


Package Specifications

Restriction: This topic applies to Windows environments only.
You must provide the following specifications to the Manage Packages and Plans tool to enable it to generate a valid BIND PACKAGE script command:
Collection name
You can specify any name you choose, and add one or more packages to that collection. HCOSS creates the collection the first time you execute a package that you specify to be stored in the collection.
Library name
The name of a library containing extracted DBRMs.
  • DBRM libraries are located under localHCOSSFiles\DBRMDataSets, where localHCOSSFiles represents the value of the Local HCOSS Directory HCOSS option.
  • When you compile your application using the SQL(DBRMLIB) directive without specifying a DBRM name, HCOSS puts all DBRMs into a default library directory named DBRMLIB.
  • If, when you compile, you specify a value for the DBRMLIB directive, the library directory name is the same as the value you specify.
  • The Manage Packages and Plans tool provides you with a list of the available libraries from which to select.
  • Each library contains one DBRM for each source code member.
  • Each DBRM contains the extracted EXEC SQL statements from a single source member.
Member name
The name of the DBRM from which you want to create the package. This is the program ID of the source code member from which the DBRM was extracted. If there is more than one DBRM in the specified library, you can select from a list of available members.
Default qualifier
The name of a schema to use as the default qualifier for this package. (Optional)
Action
The action you want to take with regard to this package and the collection. If this package doesn't already exist in the collection, you can click Add to add it. If it does exist in the collection, you can click Replace to replace the current package version with an updated DBRM member, or you can replace a specific version by specifying the version identifier for the package that you want to replace and clicking Replace Version. HCOSS generates a new version for the package when you generate the DBRM.
Parent topic: Manage Packages and Plans Tool
Related tasks
To create a new package
To edit an existing BIND command
Related reference
Bind Packages tab


Plan Specifications

Restriction: This topic applies to Windows environments only.
You must provide some or all of the following specifications to the Manage Packages and Plans tool to enable it to generate each BIND PLAN script command:
  • Plan name - You can specify any name you choose. HCOSS creates the plan the first time you bind it.
  • Default qualifier (optional) - the name of a schema to use as the default qualifier for this plan. HCOSS applies plan qualifiers to DBRM members specified in the plan; however, packages included in the plan use the qualifier specified for the package when it was executed, ignoring any specified plan qualifier.
  • Action - the action you want to take with regard to this plan. If the plan doesn't already exist, you can add it. If it does exist, you can replace it with modified specifications you provide.
  • Collections that contain packages you want to include in the plan.
  • Packages you want to include.
  • DBRM members you want to include in the plan.
  • DBRM libraries in which you want to search for specified DBRM members.
Parent topic: Manage Packages and Plans Tool
Related tasks
To create a new plan
To edit an existing BIND command
Related reference
Bind Plans tab


Freeing Packages and Plans

Restriction: This topic applies to Windows environments only.

Over time, as a result of binding multiple DBRMs into multiple packages and plans, you might accumulate more data records and stored procedures in your SQL Server database than you need to run your application. In this case, you can use the Manage Packages and Plans tool to free (clean out) the packages and plans that you no longer need.

When you free a package, the Manage Packages and Plans tool removes associated system table data about the package and the stored procedure(s) associated with the package. You can remove all versions or a specific version of each package. You cannot restore a package that you have freed. Instead, you must bind the package again.

When you free a plan, the Manage Packages and Plans tool removes associated system table data about the plan and the stored procedure(s) associated with the plan. This includes removing all associations with packages bound into the plan. However, the packages themselves remain intact. Remember that a single package can be accessed individually and/or from any plan into which is has been bound. Therefore, even when you free a plan, its packages remain usable in those other contexts. If you want to also free the packages associated with a plan, you must free them separately.

You cannot restore a plan that you have freed. Instead, you must bind the plan again.

Parent topic: Manage Packages and Plans Tool
Related concepts
Binding Applications
Manage Packages and Plans Tool
Related tasks
To free one or more packages
To free one plan or all plans


DSN Bind Utility

Restriction: This topic applies to Windows environments only.
Important: Starting with Enterprise Developer 2.2 Update 1 and continuing with each subsequent release, run the DSN Bind utility against all of your existing SQL Server databases. This ensures that all mainframe artifacts stored in the database are updated appropriately with each software release.

Using the DSN Bind utility, you can bind your database to your SQL Server application from the command line or as a post-build event.

The DSN Bind utility requires that you have an active connection to your SQL Server database, and that you provide a bind script file (.hcodsn file) containing the DSN commands you want to execute. You can create the bind script file using the Manage Packages and Plans tool, or create it manually in a text editor.
Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.

A post-build event is a process executed automatically, immediately following the building of an application in the IDE.

The DSN Bind utility executes in two sequential phases each time you run it - the Schema Update execution phase followed by the Bind Script execution phase.

Schema Update Execution

In this phase of execution, DSN checks the SQL Server database to which you are connected to ensure that the tables and stored procedures it requires are present in the database, and that the table and function definitions are consistent with the version of HCOSS in use. If the checks return successfully, DSN moves on to the Bind Script Execution phase. However, if the checks fail, DSN performs a schema update before moving on.

DSN database checks fail, triggering a schema update, only when either of the following is true:
  • You run DSN against a new SQL Server database
  • You run DSN for the first time after installing an HCOSS upgrade
  • DSN determines that necessary tables and/or stored procedures are missing from the database
To perform a schema update, DSN executes the following SQL scripts against your SQL Server database:
  • InstallSYSIBM.sql - creates metadata tables that DSN uses to manage bound DBRMs.
  • InstallBindProcs.sql - creates stored procedures that DSN uses to manage these tables.
  • InstallDigitsFunction.sql - creates the following functions to emulate DB2 functions not provided by SQL Server:
    • DATEINTERVAL
    • DIGITS
    • JULIANDAY
    • LASTDAY
    • LPAD
    • MIDNIGHT_SECONDS
    • NEXTDAY
    • RPAD
    • STRIP
    • TIMEINTERVAL
    • TRANSLATE
    • TRUNCATE

These SQL scripts reside in your %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory.

To ensure successful completion of the schema update process, connect to your SQL Server database using login credentials that include the following permissions:
  • CREATE SCHEMA
  • CREATE TABLE
  • DROP TABLE
  • CREATE INDEX
  • DROP INDEX
  • CREATE PROCEDURE in the SYSIBM schema
  • DROP and CREATE FUNCTION in the dbo schema
Important: This set of required permissions provides broader access to the SQL Server database than is necessary for the checking and binding done by DSN on a regular basis, that is, when database checks do not trigger the schema update process. If you routinely bind your applications by executing DSN from the command line or as a post-build event, and you prefer to restrict permissions for day-to-day use, you can avoid possible errors and prevent DSN from triggering an automatic schema update by completing the process manually immediately after creating a new SQL Server database and after each HCOSS upgrade. To perform a manual schema update, connect to your SQL Server database using login credentials that grant the required permissions, and then run the SQL scripts manually.

Permissions required to run database checking are the same as those required for bind script execution.

Bind Script Execution

In the Bind Script Execution phase, DSN:
  • Generates stored procedures that bind packages and plans, maintaining them as metadata in the following SQL Server database tables:
    SYSIBM.SYSDBRM
SYSIBM.SYSPACKAGE
SYSIBM.SYSPACKLIST
SYSIBM.SYSPLAN
  • For each DBRM package specified in a BIND PACKAGE command, generates a separate stored procedure for each static SQL statement, saving them to your SQL Server database using the following naming convention:

    PKG:collectionName.memberName consistencyToken$statementNumber

    Where consistencyToken is a DSN-generated string that provides a unique name for the stored procedure, and statementNumber is a DSN-generated number starting at 0. For example:

    PKG:COLLECTION1.MEMBERAEEEcKIKy$0

  • For each plan specified in a BIND PLAN command, generates stored procedures for specified packages/members, saving them to your SQL Server database using a similar naming convention:

    PLN:planNameconsistencyToken$statementNumber

    For example:

    PLN:MYPLAN1.MEMBERAFFFdLJLz$0

To ensure successful completion of the Bind Script Execution phase, connect to your SQL Server database using login credentials that include the following permissions:
  • CREATE SCHEMA
  • CREATE PROCEDURE
  • EXECUTE PROCEDURE in the SYSIBM schema
Parent topic: Migrating Applications
Related concepts
Manage Packages and Plans Tool
Binding Applications
Local DBRMs
Managing DBRMs
Shared DBRMs and multi-user environments
Migration Scenarios
Before Using HCO for SQL Server
Application Database Support
Related tasks
To bind from the command line
To bind as a post-build event
To manually code a bind script file
Related reference
Assessment Tasks tab
DSN command
Bind Script Commands


Managing DBRMs

Restriction: This topic applies to Windows environments only.

HCOSS manages DBRMs in DBRM libraries local to each user, and also in a shared DBRM library available to all HCOSS users. HCOSS ensures that each program and application is bound using DBRMs from the appropriate library.

  • Local DBRMs
    Explains how HCOSS manages local DBRMs.
  • Shared DBRMs and multi-user environments
    Explains how HCOSS ensures that the appropriate version of each DBRM is found and used when binding an application that is routinely accessed and maintained by more than one HCOSS user.
Parent topic: Migrating Applications
Related concepts
Shared DBRMs and multi-user environments
Binding Applications
DSN Bind Utility
Related reference
Options
PROMOTE
DBRMLIB


Local DBRMs

Restriction: This topic applies to Windows environments only.
When compiling an HCOSS program or application with the DBRMLIB compiler directive option, DBRMs are generated and stored in one of two places:
  • The DBRMDataSets\DBRMLIB subdirectory of the directory specified in your Local HCOSS Directory HCOSS option (default).
  • A subdirectory of the DBRMDataSets directory, specified as argument to the DBRMLIB compiler directive option. When specified, this value overrides the default directory.

For users who are working on a single program or application, compiling and binding is done on the local level using DBRMs available in the local DBRM libraries.

Note: When binding a program or application for which there are no local DBRMs, HCOSS uses DBRMs found in the shared DBRM library. See Shared DBRMs and Multi-User Environments for more information.
Parent topic: Managing DBRMs
Related concepts
Shared DBRMs and multi-user environments
Binding Applications
DSN Bind Utility
Related reference
PROMOTE
DBRMLIB


Shared DBRMs and multi-user environments

Restriction: This topic applies to Windows environments only.

HCOSS maintains a DBRM library that is located in the DBRMDataSets subdirectory of the directory specified in your Shared HCOSS Directory HCOSS option. This shared DBRM library provides a single location for all production DBRMs, regardless of which user generated them. This shared DBRM library is essential for binding large applications maintained in Enterprise Developer and accessed by multiple users.

Individual HCOSS users populate the shared DBRM library when compiling HCOSS programs and applications using both the DBRMLIB and the PROMOTE compiler directive options. DBRMLIB specifies the generation of DBRMs, and PROMOTE specifies that the generated DBRMS are stored in the shared HCOSS DBRM library, and that older versions of the same DBRMS in the user's local DBRM library are deleted. In this way, HCOSS retains only the promoted copy of each DBRM.

Important: In a multi-user environment, it is vital that each HCOSS user has the same physical location specified in his or her Shared HCOSS Directory HCOSS option.

Use Case Scenario

The following scenario illustrates how the shared DBRM library is maintained and accessed for an Eclipse project containing a single HCOSS application comprised of multiple programs maintained by several different HCOSS developers.

Developer A
  1. Opens the Eclipse project and edits one program within the project, Program A.
  2. Compiles Program A using the DBRMLIB option.

    This generates DBRMs in Developer A's local HCOSS DBRM library.

  3. Binds the DBRMs to Program A for testing.

    HCOSS looks for each DBRM in Developer A's local HCOSS library first, and if not found, then looks in the shared HCOSS library.

  4. Tests Program A.
  5. Recompiles Program A using both the DBRMLIB and the PROMOTE options.

    HCOSS generates DBRMs in the shared HCOSS library and deletes the older versions of the same DBRMs from Developer A's local HCOSS library.

Developer B
  1. Compiles the application that contains Program A, but without specifying DBRMLIB.

    All programs are compiled, but no DBRMs are generated.

  2. Binds the application.

    HCOSS binds using the DBRMs found in the shared DBRM library, including those for Program A, previously promoted by Developer A using the PROMOTE compiler directive.

Parent topic: Managing DBRMs
Related concepts
Shared DBRMs and multi-user environments
Binding Applications
DSN Bind Utility
Local DBRMs
Managing DBRMs
Related reference
Options
PROMOTE
DBRMLIB


Running Applications

Restriction: This topic applies to Windows environments only.

Your run-time applications require access to the DBRMs containing your SQL Server information. Therefore, you must specify the package collection or plan to which you have bound the DBRMs needed for a particular application.

Note: Because plan selection is specific to a connection, HCOSS maintains separate settings of CURRENT PACKAGE PATH, CURRENT PACKAGESET and APPLICATION PLAN for each connection used by an application.
  • CICS Applications - DBRM Specification
  • JCL Applications - DBRM Specification
Parent topic: Migrating Applications
Related concepts
Binding Applications
Application Migration Process


CICS Applications - DBRM Specification

Restriction: This topic applies to Windows environments only.

CICS applications migrated using HCOSS and running under Enterprise Server require that you specify a package collection, list of package collections, or a plan in which your application's DBRMs are bound. You can do this one of two ways:

  • Enterprise Server environment variables

    Depending on how you have bound your DBRMs, set one the following environment variables in the Configuration Information field on the Enterprise Server Administration Server > Properties > General tab for the enterprise server running the application:

    • ES_DB_APPLICATION_PLAN
    • ES_DB_PACKAGESET
    • ES_DB_PACKAGE_PATH

    These variables set the APPLICATION PLAN, CURRENT PACKAGESET or CURRENT PACKAGE PATH special registers. By setting one of these variables, you create a global setting for a CICS region.

  • In application source code

    Add one of the following statements to your source code:

    • SET APPLICATION PLAN
    • SET CURRENT PACKAGESET
    • SET CURRENT PACKAGE PATH

    Use SET APPLICATION PLAN or SET CURRENT PACKAGESET to explicitly set the plan name or collection name containing your DBRMs. Use SET CURRENT PACKAGE PATH to specify a list of collections from which to select.

    Note: This method is less desirable because it requires changes to application code.
Parent topic: Running Applications


JCL Applications - DBRM Specification

Restriction: This topic applies to Windows environments only.
JCL run-time applications migrated with HCOSS require that you specify the plan or package collection(s) to which its DBRMs are bound. This is accomplished using one of three methods:
  • Explicitly on the JCL RUN command
    JCL passes the PLAN parameter value from the JCL RUN command to OpenESQL, which then uses this value to set the plan used by the application. For example:
    RUN PROG(progName) PLAN(planName)
  • Automatically by default
    If you do not specify a PLAN parameter in the JCL RUN command, JCL defaults to using the program name as the plan name. For example:
    RUN PROG(progName)
  • In application source code

    This method overrides the automatic default method. It also enables you to specify package collection(s) instead of a plan. Add one of the following statements to your source code:

    • SET APPLICATION PLAN - Explicitly set the plan name
    • SET CURRENT PACKAGESET - Explicitly set the collection name
    • SET CURRENT PACKAGE PATH - Specify a path containing collections from which to select
Parent topic: Running Applications


Deploying Native Applications

The software components required for successful HCOSS application deployment depend on your deployment scenario. For details, see Additional Software Requirements on Windows.

Deploy an Application Compiled Without DBRMLIB

To deploy an Enterprise Developer HCOSS application that was not compiled using the DBRMLIB directive, meaning that you did not bind the DBRM files for your application, complete the steps presented in the topic Deploying Native COBOL Applications. The steps presented there are necessary to successfully deploy your application to the deployment machine.

Development Machine
  • Build and test the HCOSS application with a development SQL Server machine.
Deployment Machine
  • Follow the steps defined in Deploying Native COBOL Applications, moving your HCOSS application as specified
  • Create a connection to the deployment SQL Server machine
  • Test the HCOSS application with the deployment SQL Server machine

Deploy an Application Compiled With DBRMLIB

To bind an Enterprise Developer HCOSS application using the DBRMLIB directive and deploy it to a deployment machine, you have two choices:

Bind the application from your development machine
Development Machine
  • Build and test the HCOSS application with a development SQL Server machine
  • Create a connection to the deployment SQL Server machine
  • Bind the HCOSS application to the deployment SQL Server machine using the connection you created
Deployment Machine

  • Follow the steps defined in Deploying Native COBOL Applications, moving your HCOSS application as specified

  • Create a connection to the deployment SQL Server machine
  • Test the HCOSS application with the deployment SQL Server machine
Bind the application from your deployment machine
Development Machine
  • Build and test the HCOSS application with a development SQL Server machine.
Deployment Machine
  1. Follow the steps defined in Deploying Native COBOL Applications.
  2. Be sure that all prerequisite software is installed on the machine. See Additional Software Requirements on Windows for details.
  3. Copy your HCOSS application from the development machine to the appropriate directory structure on the deployment machine.
    Important: You must create some or all of the required directory structure manually.

    Specifically, copy database request modules (DBRMs), that is, the DBRMName.hcodbrm files, from the development machine to the equivalent directory on the deployment machine. The location of your DBRM files varies on your development machine depending on your HCOSS options, and the specified DBRMLIB directive. The location on your development machine is:

    localHCOSSFiles\DBRMDataSets\DBRMLIBName

    Where localHCOSSFiles represents the value of the Local HCOSS Directory HCOSS option, and DBRMLIBName represents the value of the DBRMLIB directive.

    Note: If no value is provided for the DBRMLIB directive, the default value is DBRMLIB. SQL(DBRMLIB) is the equivalent of SQL(DBRMLIB=DBRMLIB).

    On the deployment machine, you must put the DBRM files into a subdirectory of the default directory: %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets. The subdirectory name must match the DBRMLIB name.

    For example, assuming the following:

    Development machine Windows user ID | devuser
    Deployment machine Windows user ID | exeuser
    DBRMLIB directive | SQL(DBRMLIB=REX.PROJECT.DEMO)
    Value of Local HCOSS Directory HCOSS option on both machines | Default setting, %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets

    You then copy the generated DBRM files using the following directory specifications:

    Development Machine | Deployment Machine
    c:\Users\devuser\AppData\Local\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets\REX.PROJECT.DEMO | c:\Users\exeuser\AppData\Local\Micro Focus\Enterprise Developer\hcoss\DBRMDataSets\REX.PROJECT.DEMO
  4. Start HCO for SQL Server in standalone mode. If you need instructions, see To start HCO for SQL Server.
  5. Using the Manage Connections tool, create a connection to the deployment SQL Server machine. For more information, see the Manage Connections Tool topic.
    Important: Be sure that the login credentials you use grant you the permissions necessary to successfully perform the tasks outlined in both the Schema Update Execution and Bind Script Execution sections of the DSN Bind Utility topic.
  6. Using the Manage Packages and Plans tool, bind the DBRM to your deployment SQL Server machine by creating and executing a BIND PACKAGE script command. For complete details, see the Manage Packages and Plans topic.
  7. Test your HCOSS application on the deployment SQL Server machine.
    Note: When running from the command line, if your Enterprise Developer installation directory contains spaces, do not enclose the directory specification in quotes when you add it to the PATH environment variable.

Deploy an Application with Customized SQL Error Codes

Copy the mfhcocds.txt file on your development machine, located in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer directory by default, to the same directory on your deployment machine.

Deploy an Application with Customized SQL Name Mappings

Copy the DialectMappings.hcomap file on your development machine, located in the %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss directory by default, to the same directory on your deployment machine.

Parent topic: HCO for SQL Server (HCOSS)
Related concepts
DB2 Database Migration Process
Deploying Native Applications
Customize SQLCode Mappings Tool
Additional Software Requirements on Windows
Extract Schema Tool
Related tasks
To start HCO for SQL Server
Related reference
DSN command


Managing Log Files

Restriction: This topic applies to Windows environments only.
Each of the following HCOSS tools generate one or more log files as you use the tool, storing them in folders as specified in your HCOSS options:
  • Manage Connections
  • Extract Schema
  • Define Lists
  • Generate DDL
  • Transfer Data
  • Compare Data
  • Manage Packages and Plans

Within the IDE, we provide a Log File tab for each of these tools where you can view the contents of the log files generated, and delete the log files of your choice. You can also configure your HCOSS options to automatically delete log files older than a given number of days.

Parent topic: HCO for SQL Server (HCOSS)
Related reference
Log Files tab


Customizing HCOSS

Restriction: This topic applies to Windows environments only.

You can customize HCOSS by setting options, changing default conversion specifications, setting certain SQL compiler directive options, and calling the DSNTIAR or DSNTIAC facility from your programs.

  • Customizing Data Type Mappings
  • Customizing Functions and Special Registers
  • Customize SQLCode Mappings Tool
  • Customizing SQLCA Error and Warning Processing
  • Customizing SQL Identifiers
Parent topic: HCO for SQL Server (HCOSS)
Related concepts
HCOSS Conversion Rules


Customizing Data Type Mappings

Restriction: This topic applies to Windows environments only.

HCOSS converts DB2 data types to SQL Server data types automatically, using a set of defaults to map each DB2 data type to a corresponding SQL Server data type.

If you want to convert any of your DB2 database data types to SQL Server database data types using settings other than the defaults mapped by HCOSS, you can customize them.

From the HCOSS Customize Type Mappings tool, you can customize the following for each DB2 data type mapping:
  • Encoding
    • ASCII
    • EBCDIC
    • UNICODE
  • Data Storage Option
    • For bit data
    • Mixed data
    • None
    • SBCS data
  • SQL Server Data Type - any available

You can also add data type mappings using the Customize Type Mappings tool.

Parent topic: Customizing HCOSS
Related tasks
To customize data type mappings
Related reference
Default Data Type Mappings
Data Mappings tab


Customizing Functions and Special Registers

Restriction: This topic applies to Windows environments only.

HCOSS converts DB2 functions and special registers to SQL Server functions or special registers automatically, using a set of defaults to map each DB2 function or special register to a corresponding SQL Server function or special register.

If you want to convert any of your DB2 database functions or special registers to SQL Server database functions or special registers using settings other than the defaults mapped by HCOSS, you can customize them.

From the HCOSS Customize SQL Name Mappings tool, you can customize the following for each DB2 function or special register:
  • The SQL Server equivalent
  • Whether SQL Server handles it as a function or a special register

Also from the Custom SQL Name Mappings tool, you can add DB2 functions and special registers defined in your DB2 database that are not represented in your SQL Server database.

Important: If you want to add a mapping for a DB2 function or special register that exists in your DB2 database but that is not represented in your SQL Server database, you must first create the SQL Server object in your SQL Server database. All objects must be present in the SQL Server database before you can create the mapping, and before you bind your application.
  • Function Customization Process
  • Function Customization Example
Parent topic: Customizing HCOSS
Related tasks
To customize SQL name mappings
Related reference
Default Function Mappings
Default Special Register Mappings
SQL Name tab


Function Customization Process

Restriction: This topic applies to Windows environments only.

DB2 comes with some built-in functions that are not represented in SQL Server. If your application uses any of these built-in functions, you must define an equivalent SQL Server function for each in your SQL Server database, and map each DB2 function to its corresponding user-defined SQL Server function using HCOSS. Do these things before binding the application.

SQL Server requires that all calls to user-defined functions are qualified with the schema name of the function. You can use HCOSS to map unqualified function names to qualified function names.

The process for customizing SQL Server to emulate a non-represented DB2 function is as follows:

  1. In your SQL Server database, define a function to serve as an equivalent of the DB2 built-in function.
  2. Qualify the new function, specifying its SQL Server schema. This is necessary because SQL Server requires that all calls to user-defined functions be qualified with the schema name.
  3. In HCOSS, map the DB2 built-in function to the newly created SQL Server function.
  4. When you build the application, set the HCOSS DIALECT directive to MAINFRAME. This tells HCOSS to consult the mapping entries to find qualified SQL Server functions based on the equivalent, original DB2 function definition.
Parent topic: Customizing Functions and Special Registers


Function Customization Example

Restriction: This topic applies to Windows environments only.

In this example, we use the scenario that our migrated DB2 database uses a built-in function for math, atanh, that our SQL Server database does not support. We use Microsoft SQL Server Management Studio to create the function in the default dbo schema of our SQL Server database, and we use HCOSS to map the DB2 function to the newly created SQL Server user-defined function.

  1. In SQL Server Management Studio, create a user-defined function in your SQL Server database to serve as an equivalent for the DB2 atanh function by executing the following Transact-SQL.
    create function atanh (@in float) returns float
begin
    return log((1 + @in) / (1 - @in)) / 2
end
go
  2. Qualify the function in SQL Server Management Studio using the dbo schema by executing the following:
    declare @x float = 0.75
select dbo.atanh(@x)
  3. Map the newly defined dbo.atanh SQL Server function to the DB2 atanh.
    1. From the HCOSS interface, click Customize SQL Name Mappings and add the following to the blank row at the bottom of the page:
      • In DB2 Function/Special Register column type atanh.
      • In SQL Server Equivalent column type dbo.atanh.
      • Check the Is Function checkbox.
    2. Click Save.
  4. Set the DIALECT directive to MAINFRAME and build the application.
       $set sql(targetdb=mssqlserver db=HCODemo dialect=mainframe, init)
       identification division.
       program-id. Program1.

       environment division.
       configuration section.

       data division.
       working-storage section.

       exec sql include sqlca end-exec.

       01  mfsqlmessagetext    pic x(200).

       01  x           comp-2.

       01  atanh       comp-2.
       01  digits      comp-2

       procedure division.

           move 0.25 to x
           exec sql
               select atanh(:x)
                into :atanh
           end-exec

           display atanh

           goback.
Parent topic: Customizing Functions and Special Registers


Customize SQLCode Mappings Tool

Restriction: This topic applies to Windows environments only.

HCOSS stores OpenESQL SQLCodes and their DB2 SQLCode and DB2 SQLState equivalents. This information, called SQLCode mappings, is stored both in your SQL Server database and in a flat text file named mfhcocds.txt. You can use the Customize SQLCode Mappings tool to manage the information in the mfhcocds.txt file and the SQL Server database.

The Customize SQLCode Mappings tool provides the following functionality:
  • By default, loads the SQLCode mappings found in mfhcocds.txt.
  • Enables you to make changes to existing mappings and add new mappings.
  • Each time you save changes, creates a backup file containing mapping information, using the following naming convention:

    mfhcocds_backup_dateTime.txt

  • Restores previous mappings by reloading a backup file.
  • Deploys mapping changes to your SQL Server database.
  • Extracts SQLCode mappings stored in the SQL Server database to a backup file.

HCOSS stores the mfhcocds.txt file and its backup files in your %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer directory.

You can also use any text editor to make changes to SQLCode mappings stored in the mfhcocds.txt file. The mappings are stored in a comma-delimited format with each line listing an OpenESQL SQLCode value followed by its DB2 SQLCode value equivalent followed by the SQLState value returned for the OpenESQL SQLCode value. For example, here is a listing of the default mfhcocds.txt contents:

* OESQL SQLCODE, DB2 SQLCODE, DB2 SQLSTATE DELIMITED BY COMMAS
-2601,-803,23505
-19519,-501,24501
-19516,-502,24502
-2714,-601,42710
-207,-204,42704
-208,-204,42704
Parent topic: Customizing HCOSS
Related concepts
Deploying Native Applications
Related tasks
To customize SQLCode mappings
Related reference
Deploy/Extract tab
SQLCode Mappings tab


Customizing SQLCA Error and Warning Processing

Restriction: This topic applies to Windows environments only.

HCOSS provides DSNTIAR and DSNTIAC facilities you can call from your program that emulate those available on the mainframe. These HCOSS facilities enable you convert your SQL run-time return codes into character string messages.

Parent topic: Customizing HCOSS
Related reference
DSNTIAR and DSNTIAC


Customizing SQL Identifiers

Restriction: This topic applies to Windows environments only.

HCOSS maps many DB2 identifiers to their SQL equivalents to resolve differences and enable smooth migration. For example, by default, HCOSS maps z/OS DB2 identifiers TRAN and APPLICATION to "TRAN" and "APPLICATION" respectively in SQL Server. This mapping is defined as such because while TRAN and APPLICATION are perfectly valid z/OS DB2 identifiers, they are reserved words in SQL Server. Therefore, to prevent these DB2 identifiers from failing to execute in SQL Server, they are mapped to SQL Server surrounded by double quotes.

In addition to using the default mappings, you can also define customized SQL identifier mappings in HCOSS using the SQL Name Mappings Tool. For more information, see Default Function Mappings, Default Special Register Mappings, and To customize SQL name mappings.

Parent topic: Customizing HCOSS
Related tasks
To customize SQL name mappings
Related reference
Default Function Mappings
Default Special Register Mappings


How to

Restriction: This topic applies to Windows environments only.
  • To start HCO for SQL Server
  • Manage Connections Tasks
  • Migrate Databases Tasks
  • Assess Application Migration
  • Manage Packages and Plans Tasks
  • Bind Applications
  • Customize HCOSS
Parent topic: HCO for SQL Server (HCOSS)


To start HCO for SQL Server

Restriction: This topic applies to Windows environments only.
In standalone mode:
Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > HCO for SQL Server.
Windows 8.1
  • From the Windows Start screen, click the HCO for SQL Server tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > HCO for SQL Server.
From Eclipse
  • From your Windows desktop, click Run > Tools > Data Tools > HCO for SQL Server.
Important: If you are using Windows UAC, you might be prompted to run HCOSS as an administrator when you start HCOSS in standalone mode. See Using HCOSS with Windows User Account Control (UAC) for more information.
Note: If HCOSS finds a more recent version of SQL Native Client or a more recent version of the ODBC Driver for SQL Server available on your machine, it prompts you with the option to upgrade your existing system and user connections to use the updated driver. You can turn this functionality off by unchecking Enable Checking for New ODBC Drivers on the Connection List tab or by checking Stop asking me on the prompt dialog box.
Parent topic: How to
Related concepts
HCOSS Toolset
Using HCOSS with Windows User Account Control (UAC)
Related tasks
To set HCOSS options
Related reference
Options


Manage Connections Tasks

  • To create a DB2 connection
  • To create a system or user SQL Server connection
  • To edit an existing connection
  • To import a connection
  • To export a connection
  • To repair a connection
Parent topic: How to


To create a DB2 connection

Restriction: This topic applies to Windows environments only.
  1. From the HCO for SQL Server interface, click Manage Connections.
  2. On the Connections List tab, select a Connection Type (System or User) for this DB2 connection.
  3. Click New DB2 Connection.
  4. Complete all fields on the form.
  5. Click Test.
  6. When the connection tests successfully, click OK to clear the message; then click Save.

    The new connection appears on the Connections List located on the Connections List tab.

Parent topic: Manage Connections Tasks
Related concepts
Manage Connections Tool
Connection Types
Related reference
Manage Connections Tool Log Files
Manage Connections Tool Error Messages
DB2 Connection tab
Connection List tab
Required DB2 Catalog Tables


To create a system or user SQL Server connection

Restriction: This topic applies to Windows environments only.
  1. Be sure you have added your SQL Server database to Microsoft SQL Server Management Studio.
  2. From the HCO for SQL Server interface, click Manage Connections.
  3. On the Connection List tab, select a Connection Type - System or User - for this SQL Server connection.
  4. From the Connection List tab, click New SQL Server Connection.
  5. Specify appropriate Connection Properties.
  6. Specify appropriate Data Link Properties as follows:
    1. Specify a SQL Server Instance by selecting from the drop-down list, or by typing the name of your SQL Server instance into the field. If you type in the name of your SQL Server instance rather than selecting it from the drop-down list, you must also click Confirm Server.
    2. If you want to use a database other than the default database, check Use a database other than the default database: dbname, and then select an alternative database from the Database drop-down list.
  7. Click Test.
  8. When the connection tests successfully, click OK to clear the message.
  9. Click Save.

    The new connection appears on the Connections List located on the Connections List tab.

Parent topic: Manage Connections Tasks
Related concepts
Manage Connections Tool
Connection Types
Related reference
Manage Connections Tool Log Files
Manage Connections Tool Error Messages
Connection Types
SQL Server Connection tab
Connection List tab


To edit an existing connection

Restriction: This topic applies to Windows environments only.
  1. From the HCO for SQL Server interface, click Manage Connections.
  2. On the Connection List tab, select a connection from the connection list; then click Edit.
  3. Modify the Connection Properties and Data Link Properties as appropriate.
  4. Click Test.
  5. When the connection tests successfully, click OK to clear the message.
  6. Click Save.
Note: When editing a SQL Server connection of the System or User connection type, if HCOSS finds a more recent version of SQL Native Client available on your machine, it prompts you with the option to upgrade the connection to use the updated driver. You can turn this functionality off by unchecking Enable Checking for New ODBC Drivers on the Connection List tab or by checking Stop asking me on the prompt dialog box.
Parent topic: Manage Connections Tasks


To import a connection

Restriction: This topic applies to Windows environments only.
  1. From the HCO for SQL Server interface, click Manage Connections.
  2. On the Import tab, type the full path to and filename of an XML (.xml) file containing the exported connection(s) that you want to import, or click the browse button to select a file.
  3. Click Read Available Connections to populate the list.
  4. Select one or more connections to import. Use Ctrl+Click to select multiple connections.
  5. Click Import.
    Note:
    • If one or more of the selected connections uses a provider other than the SQL Native Client, or if you do not have the appropriate database provider installed, the Import button is disabled and you cannot import the connection.
    • When importing an OleDb Data Provider connection, whenever possible, HCOSS uses the same driver version that was in use when the connection was exported. For example, if the exported connection used SQL Server Native Client 10.0, and that version is installed and available for the import, HCOSS uses it. If the version specified is not installed or is not available, HCOSS uses the latest version available for that driver.
    • HCOSS cannot import a connection that has the same name as an existing connection. In this case, HCOSS notifies you that the connection already exists, and does not perform the import of that connection.
  6. When the import is complete, click OK to clear the message. You should see the imported connections on the Connection List found on the Connection List tab.
Parent topic: Manage Connections Tasks
Related concepts
Manage Connections Tool
Connection Types
Related reference
Manage Connections Tool Log Files
Manage Connections Tool Error Messages
Import tab


To export a connection

Restriction: This topic applies to Windows environments only.
  1. From the HCO for SQL Server interface, click Manage Connections.
  2. From the connection list on the Export tab, select one or more connections you want to export.
  3. In the Export to File field, type the full path to and filename of a file to which you want to export the connection(s), or click the browse button to select or specify a file.
    Note:
    • The default file extension for exported connections is .xml.
    • If you don't specify a path, HCO for SQL Server puts the file into the bin directory of your installation.
    • If you specify an existing file, HCO for SQL Server prompts you to confirm the overwriting of that file.
  4. Click Export.
Parent topic: Manage Connections Tasks
Related concepts
Manage Connections Tool
Connection Types
Related reference
Manage Connections Tool Log Files
Manage Connections Tool Error Messages
Export tab


To repair a connection

Restriction: This topic applies to Windows environments only.
  1. From the HCO for SQL Server interface, click Manage Connections.
  2. From the Connection List tab, select a Connection Type (System or User) to populate the Connection List grid with connections defined for that type.
  3. From the Connection List grid, select a connection that shows a status of Needs Repair.
  4. Click Repair.
Note: When repairing SQL Server connection of the System or User connection type, HCOSS attempts to use the ODBC driver specified when the connection was created, such as SQL Server Native Client 10.0. If the specified driver version is not available, HCOSS uses the latest available version.
Parent topic: Manage Connections Tasks
Related concepts
Manage Connections Tool
Connection Types
Related reference
Manage Connections Tool Log Files
Manage Connections Tool Error Messages


Migrate Databases Tasks

  • To extract DB2 schema objects
  • To modify a schema extract file
  • To export and import DB2 schemas
  • To assess data migration
  • To export data assessment results
  • To define an object transfer list
  • To generate and execute DDL
  • To customize generated DDL
  • To customize schema mappings in DDL
  • To transfer data
  • To customize a transfer data task
  • To compare transferred data
  • To run customized data comparisons
Parent topic: How to


To extract DB2 schema objects

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Extract Schema tool, click the Schema Extract tab.
  2. Do one of the following:
    • If using a direct connection to z/OS DB2:
      1. In the Connection group, select DB2 DSN.
      2. From the Connection drop-down list, select the DB2 connection you created using the Manage Connections tool that points to the DB2 database containing the schema objects that you want to extract.
    • If using the offline schema extract solution:
      1. In the Connection group, select SQL Server DSN.
      2. From the Connection drop-down list, select the SQL Server connection you created using the Manage Connections tool that points to the SQL Server database containing the schema objects that you want to extract.
        Note: For detailed information about using the offline extract schema solution, see Offline Extract Schema Solution.
  3. If prompted, provide your user ID and password.
  4. Click New.
  5. In the Schema Extract Name field, type a name for the generated schema extract file.
  6. In the Metadata/Catalog Schema Name field, type the name of a schema containing alternative views of the SYSIBM table. Optional.
    Note: This feature enables users to access the information in SYSIBM tables without having access to the SYSIBM catalog. In this case, you must create the alternative schema before running the Extract Schema tool.
  7. Click OK.
  8. On the Schema Extract tab, choose one of the following:
    Local | To save the generated schema extract file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated schema extract file to the directory specified by the Shared HCOSS Directory HCOSS option.
  9. On the Select schema(s) to extract list, check the box that corresponds to each schema you want to extract.
  10. In the Table Row Count group, select one of the following:
    • Estimated using schema statistics - to record the estimated table row count based on the schema statistics stored in SYSIBM.SYSTABLES. Use this option to improve performance.
    • Both Estimated using schema statistics and Actual using SELECT BIG_COUNT(*) - to record both the estimated table row count and the actual row count as retrieved using a SELECT BIG-COUNT(*) query. Use this option to provide accuracy.
      Note: This option is not available when using the offline extract schema solution.
  11. Click Extract.
  12. On the Results tab, verify that the schema extract file has been generated properly.
    Note: If you get a -551 SQL error extracting a table, no schema is extracted. To correct this, have your DB2 DBA grant you READ access to the table that generated the error; then rerun the Extract Schema tool.
  13. On the Schema Extract tab, click Save to save the settings.
Parent topic: Migrate Databases Tasks
Related concepts
Extract Schema Tool
Offline Extract Schema Solution
Related tasks
To export and import DB2 schemas
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files
Extract Schema Tool Error Messages
Required DB2 Catalog Tables
Schema Extract tab
Create New Schema Extract
Results tab


To modify a schema extract file

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Extract Schema tool, click the Schema Extract tab.
  2. Select an existing schema extract file from the Schema Extract Name drop-down list.
  3. Using the fields and controls on the Schema Extract tab change the settings as required.
    Note: If you change the properties from Local to Shared, or vice versa, you have the following options:
    • Move the existing extract file to the new location
    • Copy the existing extract file to the new location
    • Neither move nor copy the existing extract file
  4. Click Extract.
  5. On the Results tab, verify that the schema extract file has been generated properly.
    Note: If you get a -551 SQL error extracting a table, no schema is extracted. To correct this, have your DB2 DBA grant you READ access to the table that generated the error; then rerun the Extract Schema tool.
  6. On the Schema Extract tab, click Save to save the new settings.
Parent topic: Migrate Databases Tasks
Related concepts
Extract Schema Tool
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files
Extract Schema Tool Error Messages
Required DB2 Catalog Tables
Schema Extract tab
Results tab


To export and import DB2 schemas

Restriction: This topic applies to Windows environments only.

To export a schema:

  1. From the Schema Extract tab, create a schema extract file or open an existing schema extract file from the Schema Extract Name drop-down list.
  2. Click Export.
  3. Select a location and provide a file name for the exported schema file. Do not include a file extension.
  4. Ensure that the Save as type field is set to Micro Focus HCOSS Schema Extract Files(*.hcodbs); then click Save.
  5. If a schema extract file with the same name exists in the same location, you are prompted to confirm that you want to overwrite it.

To import a schema:

  1. From the Schema Extract tab, click Import.
  2. Browse to and select an exported schema file. These files have a .hcodbs file extension.
  3. Click Open.
Parent topic: Migrate Databases Tasks
Related tasks
To extract DB2 schema objects


To assess data migration

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Assess Data Migration tool, click the Data Assessment Tasks tab.
  2. From the DB2 Connection drop-down list, select the DB2 connection that contains the extracted schema you want to assess.
  3. Do one of the following:
    • To define a new Data Assessment task:
      1. Click New.
      2. In the Name field, type a name for the data assessment task.
      3. From the Schema Extract drop-down list, select an existing schema extract file.
      4. Click OK.
    • To edit an existing data assessment task, select either the Local or Shared radio button; then select a task from the Available Assessments drop-down list.
  4. Choose one of the following to apply to the Available Assessments drop-down list:
    Local | To save the generated data assessment task to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated data assessment task to the directory specified by the Shared HCOSS Directory HCOSS option.
  5. Choose one of the following to apply to the Associated Schema Extract drop-down list:
    Local | To show local extracted schemas on the Associated Schema Extract drop-down list.
    Shared | To show shared extracted schemas on the Associated Schema Extract drop-down list.
  6. From the Associated Schema Extract drop-down list, select an extracted schema created using the Extract Schema tool.

    This populates the Table List with information in the selected schema extract.

  7. Click Save to save the data assessment task so that it is available for future editing.

    At this point, you can browse the information in the schema extract file, and you can optionally make changes. If you want to make changes to the file, continue with step 8.

  8. From the DB2 Connection drop-down list, select the DB2 database connection you want to use when updating the schema extract file.
  9. To change the information in the extracted schema, optionally choose one of the following actions for each table on the grid:
    • Change the Count-Type. The default type listed for each column depends on which Table Row Count option you chose when you extracted the schema.
    • Change the Transfer Option from HCOSS to OTHER for tables containing data that you do not want to migrate.
  10. To update the schema extract file with changes on the Table List grid, click Update Row Count. Any error messages are shown in the Update Results window on the Results tab.
  11. Click Save Options to save the changes you've made in the Table List grid.
Parent topic: Migrate Databases Tasks
Related concepts
Assess Data Migration Tool
Related reference
Data Assessment Tasks tab
Create New Data Assessment Task dialog box
Results tab
Schema Extract tab


To export data assessment results

Restriction: This topic applies to Windows environments only.

To export data assessment results as a CSV file:

  1. Perform the analysis.
  2. Click Export Details (csv).
  3. In the File Name field supply a filename and specify a location. If you specify a file name that doesn't exist, it is created. If you specify a file name that already exists, you will be prompted to confirm that you want to overwrite the existing file.

To export data assessment results as a text file:

  1. Perform the analysis.
  2. Click Export Report (txt).
  3. In the File Name field supply a filename and specify a location. If you specify a file name that doesn't exist, it is created. If you specify a file name that already exists, you will be prompted to confirm that you want to overwrite the existing file.
Parent topic: Migrate Databases Tasks


To define an object transfer list

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Define Lists tool, click the Transfer Lists tab.
  2. Do one of the following:
    • To define a new transfer list:
      1. Click New.
      2. In the Name field, type a name for the transfer list file.
      3. Click OK.
    • To edit an existing transfer list, select an existing list from the Available Transfer Lists drop-down list.
  3. Choose one of the following to apply to the Available Transfer Lists drop-down list:
    Local | To save the generated transfer list file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated transfer list file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated Schema Extract drop-down list:
    Local | To show local extracted schemas on the Associated Schema Extact drop-down list.
    Shared | To show shared extracted schemas on the Associated Schema Extact drop-down list.
  5. From the Associated Schema Extract drop-down list, select a schema extract file created using the Extract Schema tool.

    The objects available from the Schema Extract file appear on the Available Objects list.

  6. To filter the list of available objects, use the fields in the Object Filtering and Selection group. Optional.
  7. Do one or more of the following to select objects to transfer:
    • To transfer one or more objects on the Available Objects list, select each object you want to transfer using a combination of mouse clicks and the Ctrl or Shift keys; then click Add.
    • To transfer all of the objects on the Available Objects list, click Add All.
    Note: Objects dependent on selected objects are added automatically.
  8. To remove objects from the Selected Objects list, do one of the following:
    • To remove one or more of the objects on the Selected Objects list, select each object you want to remove using a combination of mouse clicks and the Ctrl or Shift keys; then click Remove.
    • To remove all of the objects on the Selected Objects list, click Remove All.
    Optional.
  9. Click Save.
Parent topic: Migrate Databases Tasks
Related concepts
Define Lists Tool
Related reference
MFObjectList command
Define Lists Tool Log Files
Define Lists Tool Error Messages
Transfer Lists tab
Create New List dialog box


To generate and execute DDL

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Generate DDL tool, click the DDL Tasks tab.
  2. Do one of the following:
    • To define a new DDL task:
      1. Click New.
      2. In the Name field, type a name for the DDL task file.
      3. Click OK.
    • To edit an existing DDL task, select an existing task from the Available Tasks drop-down list.
  3. Choose one of the following to apply to the Available Tasks drop-down list:
    Local | To save the generated DDL task file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated DDL task file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated Transfer List drop-down list:
    Local | To show local transfer lists on the Associated Transfer List drop-down list.
    Shared | To show shared transfer lists on the Associated Transfer List drop-down list.
  5. From the Associated Transfer Lists drop-down list, select a transfer list file created using the Define Lists tool.
  6. To define the DDL behavior, select either Drop and create objects or Restore missing objects.
  7. From the Connection for Execute drop-down list, select a SQL Server connection previously defined using the Manage Connections tool.
  8. Optionally, do one or more of the following:
    • To customize your generated DDL, click Customize. See To customize generated DDL for more information.
    • To change the default schema mappings, click Schema Mappings. See To customize schema mappings in DLL for more information.
    • To populate coded character set identifiers (CCSIDs), thus preserving the mainframe text sort order, check Preserve mainframe text sort order. If left unchecked, the sort order is the default SQL Server order specified for the database.
    • To check the DDL task specifications against a test SQL Server data source, specify a SQL Server data source in the Connection for Check drop-down list; then click Check. Results are displayed on the Results tab.
    • To save the SQL generated for the DDL as an SQL script, click Export SQL Script.
  9. Click Save to save the DDL task.
  10. Click Execute.
  11. Click the Results tab to review the execution results.
Parent topic: Migrate Databases Tasks
Related concepts
Generate DDL Tool
Related tasks
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


To customize generated DDL

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Generate DDL tool, either create a new DDL task or open an available DDL task.
  2. Click the Customize DDL tab.
  3. On the Objects grid, click a schema object you want to customize.
  4. In the Customized DDL window, edit the DDL code to reflect the changes you desire.
  5. Click Save All to save your changes.
    Note: The code shown in the Generated DDL window is the DDL code that HCOSS generates by default. However, once you make and save changes to the code in the Customized DDL window, HCOSS generates your customized code instead of the default code.
  6. Repeat steps 3 through 5 for each schema object you want to customize.
Parent topic: Migrate Databases Tasks
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


To customize schema mappings in DDL

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Generate DDL tool, either create a new DDL task or open an available DDL task.
  2. Click the Schema Mappings tab.
  3. In the SQL Server Schema Name column, double-click the entry you want to change.
  4. Edit the mapping to reflect the appropriate SQL Server schema name.
    Note: The changes you make are automatically saved when you click outside of the SQL Server Schema Name column.
Parent topic: Migrate Databases Tasks
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files
Generate DDL Tool Error Messages
DDL Tasks tab
Create New DDL Task dialog box
Customize DDL tab
Schema Mappings tab
Results tab


To transfer data

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Transfer Data tool, click the Transfer Data Tasks tab.
  2. Do one of the following:
    • To define a new transfer data task:
      1. Click New.
      2. In the Name field, type a name for the transfer data task file.
      3. Click OK.
    • To edit an existing transfer data task, select an existing task from the Available Tasks drop-down list.
  3. Choose one of the following to apply to the Available Tasks drop-down list:
    Local | To save the transfer data task file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the transfer data task file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated DDL Task drop-down list:
    Local | To show local DDL tasks on the Associated DDL Task drop-down list.
    Shared | To show shared DDL tasks on the Associated DDL Task drop-down list.
  5. From the Associated DDL Task drop-down list, select a DDL task file created using the Generate DDL tool.
  6. From the Source Connection drop-down list, select a DB2 connection previously defined using the Manage Connections tool.
  7. From the Destination Connection drop-down list, select a SQL Server connection previously defined using the Manage Connections tool.
  8. To customize your transfer data task, click Customize. See To customize a transfer data task for more information. Optional.
  9. Click Save to save the transfer data task.
  10. To export the transfer data task as one or more SSIS packages, click Export as SSIS Packages. Optional.
  11. Click Transfer.
    Warning: While the transfer is running, do not to switch to another HCOSS tool. This action could produce an undesirable result. If you must switch to another tool, click Cancel and wait for the transfer process to stop before switching.
  12. On the Results tab, verify that the data transfer has completed properly.
Parent topic: Migrate Databases Tasks
Related concepts
Transfer Data Tool
Related tasks
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files
Transfer Data Tool Error Messages
Transfer Data Tasks tab
Create New Transfer Data Task dialog box
Customize Transfer Data tab
Results tab


To customize a transfer data task

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Transfer Data tool, either create a new transfer data task or open an available transfer data task.
  2. Click the Customize Transfer Data tab.
  3. Do one or more of the following to customize the task. All are optional:
    • Edit the Seq, Schema name, Name, or Buffer rows column for any entry on the Tables grid.
      Note:
      • Be careful that any new values you enter into column fields are valid within the context of the transfer task. Invalid values can cause Build Query failures.
      • Edits made directly to the Query column are not saved.
    • Change or set the controls in the Transfer Task Options group to affect all schemas and tables.
    • Build a WHERE or an ORDER BY into a SELECT statement:
      1. On the Tables grid, double-click the first column on the left-hand side of the grid for the object you want to customize.
      2. Use the fields and controls in the WHERE/ORDER BY in SELECT group to construct the clause.
      3. Click Update to add the WHERE or ORDER BY to the query statement.
    • Select a method for handling source row data from the Source Row Data Count group.
      Note:
      • The default setting for Source Row Data Count when you have not specified a WHERE clause is Estimate using schema statistics. If you have specified a WHERE clause, the default is Acutal using COUNT_BIG(*).
      • You can override the default by specifically selecting an option from the group with one exception. If the default setting is Acutal using COUNT_BIG(*), you cannot override it by setting it to Estimate using schema statistics.
  4. Click Save All to save all customizations.
  5. Optionally, click Transfer to immediately transfer the data.
    Note: You can also transfer the data from the Transfer Data Tasks tab.
Parent topic: Migrate Databases Tasks
Related concepts
Transfer Data Tool
Related tasks
To transfer data
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files
Transfer Data Tool Error Messages
Transfer Data Tasks tab
Create New Transfer Data Task dialog box
Customize Transfer Data tab
Results tab


To compare transferred data

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Compare Data tool, click the Compare Data Tasks tab.
  2. Do one of the following:
    • To define a new compare data task:
      1. Click New.
      2. In the Name field, type a name for the compare data task file.
      3. Click OK.
    • To edit an existing compare data task, select an existing task from the Available Tasks drop-down list.
  3. Choose one of the following to apply to the Available Tasks drop-down list:
    Local | To save the compare data task file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the compare data task file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Choose one of the following to apply to the Associated DDL Task drop-down list:
    Local | To show local DDL tasks on the Associated DDL Task drop-down list.
    Shared | To show shared DDL tasks on the Associated DDL Task drop-down list.
  5. From the Associated DDL Task drop-down list, select a DDL task file created using the Generate DDL tool.
  6. From the Source Connection drop-down list, select a DB2 connection previously defined using the Manage Connections tool.
  7. From the Destination Connection drop-down list, select a SQL Server connection previously defined using the Manage Connections tool.
  8. To customize your compare data task, click Customize. See To run customized data comparisons for more information. Optional.
  9. Click Save to save the compare data task.
  10. Click Compare.
  11. On the Results tab, verify that the results of the comparison.
Parent topic: Migrate Databases Tasks
Related concepts
Compare Data Tool
Related tasks
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Log Files
Compare Data Tool Error Messages
Compare Data Tasks tab
Create New Compare Data Task dialog box
Customize Compare Data tab
Results tab


To run customized data comparisons

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Compare Data tool, either create a new compare data task or open an available compare data task.
  2. Click the Customize Compare Data tab.
  3. On the Source Schemas and Tables tree view, expand the tree and check a table you want to customize. This populates the Customized Query Pair window with the query associated with the checked table.
  4. Do one or more of the following:
    • Edit the query code in the Customized Query Pair window; then click Compare. Results are shown on the Results tab.
    • Build a WHERE or an ORDER BY clause into the SELECT statement:
      1. Use the fields and controls in the WHERE/ORDER BY in SELECT group to construct the clause. When you click > or <, HCOSS updates the code in the Customized Query Pair window.
      2. Click Compare. Results are shown on the Results tab.
      3. On the Customize Compare Data tab, click Save All to save the changes.
    Note: HCOSS does not save manual changes made to code in the Customized Query Pair window.
Parent topic: Migrate Databases Tasks
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
Related reference
MFTestConversion command
Compare Data Tool Log Files
Compare Data Tool Error Messages
Compare Data Tasks tab
Create New Compare Data Task dialog box
Customize Compare Data tab
Results tab


Assess Application Migration

  • To analyze schema extract data
  • To assess application migration
  • To export assessment results
Parent topic: How to


To analyze schema extract data

Restriction: This topic applies to Windows environments only.
  1. Use the Extract Schema tool to create one or more schema extract files.
  2. Start the HCOSS Assess Application Migration tool, and click the Data Analysis tab.
  3. Choose one of the following to apply to the Select Schema Extract File drop-down list:
    Local | To save the generated data analysis file to the directory specified by the Local HCOSS Directory HCOSS option.
    Shared | To save the generated data analysis file to the directory specified by the Shared HCOSS Directory HCOSS option.
  4. Select a schema extract file from the drop-down list.
  5. Click Analyze Schema Extract.

    Output appears in the output window on the lower part of the page.

  6. Repeat steps 4 and 5 to analyze additional schema. Output for each subsequent schema analysis is appended to the bottom of the output window. (Optional)
  7. To save the output to a file, click Save to File. (Optional)
  8. To close the current schema extract file and clear the output window, click Close Schema Extract. (Optional)
Parent topic: Assess Application Migration
Related concepts
Why You Should Use the Assess Application Migration Tool
Related reference
Data Analysis tab


To assess application migration

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Assess Application Migration tool, click the Assessment Tasks tab.
  2. Do one of the following:
    • To define a new assessment task:
      1. Click New.
      2. In the Name field, type a name for the assessment task file.
      3. Click the browse button and navigate to the directory containing your COBOL source files, or the parent directory to one or more subdirectories containing your COBOL source files.
      4. Click OK.
    • To edit an existing assessment task, select an existing task from the Available Assessments drop-down list.
  3. From the SQL Server Connection drop-down list, select an existing SQL Server connection to use in the assessment.
  4. If you have a schema you want to use as the default qualifier for this assessment, type its name into the Qualifier (default schema) field. Optional.
  5. If you want HCOSS to report errors related to schema specification, uncheck Ignore Schema Errors. Optional.
    Note: Do not uncheck this checkbox if you have not created your SQL Server database.
  6. In the Summary grid's Check for SQL column, uncheck any files that you do not want to include in the assessment. If you want to select all of the files, right-click in the column, and then click Select All from the popup menu.
    Note:
    • To view the source for any file listed on the Summary grid, double-click the file name in the File Path column. This opens the Source Code tab. Use the Next EXEC SQL and Previous EXEC SQL buttons to move from one SQL statement to another.
    • The code that appears on the Source Code tab is the original source file if you have not processed the assessment. If you have, the code that appears is the converted code.
  7. Click Save to save the assessment task.
  8. Click Process Files.
  9. On the Results tab, review the assessment results.
  10. To see a comparison of the original source code along with converted source code, double-click a file listed on the Error Details grid, and view the code in the SQL Conversion tab.
Parent topic: Assess Application Migration
Related concepts
Assess Application Migration Tool
Application Migration Process
Migration Scenarios
Related reference
Assessment Tasks tab
Create New Assessment Task dialog box
Results tab
SQL Conversion tab
Source Code tab


To export assessment results

Restriction: This topic applies to Windows environments only.

To export application migration assessment results as a CSV file:

  1. Perform the analysis.
  2. Click Export Details (csv).
  3. In the File Name field supply a filename and specify a location. If you specify a file name that doesn't exist, it is created. If you specify a file name that already exists, you will be prompted to confirm that you want to overwrite the existing file.

To export application migration assessment results as a text file:

  1. Perform the analysis.
  2. Click Export Report (txt).
  3. In the File Name field supply a filename and specify a location. If you specify a file name that doesn't exist, it is created. If you specify a file name that already exists, you will be prompted to confirm that you want to overwrite the existing file.
Parent topic: Assess Application Migration
Related concepts
Assess Application Migration Tool
Related reference
Assessment Tasks tab
Create New Assessment Task dialog box
Results tab


Manage Packages and Plans Tasks

  • To create a bind script file
  • To open an existing bind script file
  • To create a new package
  • To create a new plan
  • To edit an existing BIND command
  • To execute one or all bind script lines
  • To free one or more packages
  • To free one plan or all plans
Parent topic: How to


To create a bind script file

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Manage Packages and Plans tool, click the Bind Scripts tab.
  2. If you have a script file open, click New to clear the page.
  3. Specify a SQL Server Connection.
  4. Add one or more bind script entries by creating one or more Packages or Plans.
  5. Click Save As to name and save the file to a location of your choosing. All bind script files are in XML format and have the file extension .hcodsn.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Related reference
Bind Scripts tab


To open an existing bind script file

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Manage Packages and Plans tool, click the Bind Scripts tab.
  2. Click Open to locate and select an existing bind script file. Bind script files have the file extension .hcodsn.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Related reference
Bind Scripts tab


To create a new package

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Manage Packages and Plans tool, either create or open a bind script file.
  2. Click New Package.
  3. In the Collection Name field, type a name for the collection in which to store the package.
  4. Select an action. If you select Replace Version, type the version you want to replace into the corresponding field.
  5. From the Library Name drop-down list, select the library that contains the source member from which you want to create the package. The default is DBRMLIB.
  6. From the Member Name drop-down list, select the member you want to action.
  7. If you have a qualifier you would like to specify, type it into the Default Qualifier field.
  8. Click Execute. This generates a script command and places it onto the list of Bind Script Entries on the Bind Scripts tab.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Package Specifications
Related reference
Bind Packages tab


To create a new plan

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Manage Packages and Plans tool, either create or open a bind script file.
  2. Click New Plan.
  3. In the Plan Name field, type a name for the plan.
  4. Select an action.
  5. Do one of the following:
    • To bind packages into the plan, select Packages mode. In this case, all versions of each package are available to the plan.
    • To bind DBRM members directly to the plan, select DBRM Members mode. In this case, HCOSS expects to find these members in the default DBRM library.
    • To bind one or more DBRM libraries to the plan, including all of the members in those libraries, select DBRM Libraries mode. In this case, HCOSS searches the libraries for DBRM members in the order in which the libraries appear on the Selected Libraries list. HCOSS uses the first instance of a specified member that it finds.
  6. If you have a qualifier you would like to specify, type it into the Default Qualifier field.
    Note: HCOSS applies plan qualifiers to DBRM members specified in the plan; however, packages included in the plan use the qualifier specified for the package when it was executed, ignoring any specified plan qualifier.
  7. Depending on the mode you have selected, use the other lists and fields on this page to add packages or DBRM members to the plan, or to remove them from the plan. You can use the Search field above each list to narrow the scope of the list. Use the % character as a wild card.
  8. Click either Add to Script to add the generated script command to the list of Bind Script Entries on the Bind Scripts tab, or click Execute to add the generated script and also execute the script commands thereby updating the SQL Server database.
    Note: If you do not execute the command at this time, you can execute it from the Bind Scripts tab to update the SQL Server database. You must eventually execute the command for the bind to take place.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Plan Specifications
Related reference
Bind Plans tab


To edit an existing BIND command

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Manage Packages and Plans tool, open a bind script file.
  2. Select a command on the Bind Script Entries list.
  3. Click Edit.
  4. Make any desired changes to the specification. For BIND PLAN commands, the available lists and fields on this page vary depending on the selected mode. You can use the Search field above each list to narrow the scope of the list. Use the % character as a wild card.
    Note: For BIND PLAN commands that include DBRM members, you can add one or more libraries in which to search for the specified DBRM members by selecting DBRM Libraries mode. In this case, you can click Move Up or Move Down to change the search order.
  5. Do one of the following:
    • Click Execute to generate and execute the BIND command and add it to your bind script.
    • Click Update in Script to generate the BIND command and add it to your script for execution at a later time.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Package Specifications
Plan Specifications
Related reference
Bind Packages tab
Bind Plans tab
Bind Scripts tab


To execute one or all bind script lines

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS Manage Packages and Plans tool, either create or open a bind script file.
  2. Ensure that the script lines on the Bind Script Entries list appear in the order in which you want to execute them. If not, select a line and click Move Up or Move Down to change its position.
  3. Do one of the following:
    • To execute one script line only, select the script line you want to execute; then click Execute Selected. In this case, if a script command fails, HCOSS displays an error message.
    • To execute all script lines in the order in which they appear on the list, click Execute All. In this case, if a script command fails, HCOSS displays an error message enabling you to click Cancel to cancel all further execution, or OK to continue with the next script command.
    Note:
    • You must successfully execute all BIND PLAN script lines to make the plans available to your run-time application.
    • All bind script execution results appear on the Results tab.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Related reference
Bind Scripts tab
Results tab


To free one or more packages

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS interface, use the Manage Connections tool to ensure you have an active connection to your SQL Server database.
  2. Click Manage Packages and Plans to start the tool.
  3. From the Bind Scripts tab, select a SQL Server Connection from the drop-down list.
  4. Click the Free Packages tab.
  5. Do one of the following:
    • To free all bound packages listed on the Bound Packages list, click Free All Packages.
    • To free one or more packages:
      1. To show version information for each package on the Bound Packages list, check Show package version information. This turns on the Version column within the grid (Optional).
      2. On the Bound Packages list, select one or more packages to remove from your SQL Server database.
        Note: To select or unselect all packages, right-click and choose the appropriate menu option.
      3. Click Free Package(s).
  6. Click OK to confirm.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Freeing Packages and Plans
Related reference
Free Packages tab


To free one plan or all plans

Restriction: This topic applies to Windows environments only.
  1. From the HCOSS interface, use the Manage Connections tool to ensure you have an active connection to your SQL Server database.
  2. Click Manage Packages and Plans to start the tool.
  3. From the Bind Scripts tab, select a SQL Server Connection from the drop-down list.
  4. Click the Free Plans tab.
  5. Do one of the following:
    • To free all bound plans listed on the Bound Plans list, click Free All Plans.
    • To free a single plan:
      1. On the Bound Plans list, select a plan you want to remove from your SQL Server database.
      2. View the details of the plan by doing one or more of the following (optional):
        • Select either the Members or Packages mode to view the contents of the plan.
        • When in Packages mode, check Expand PKLIST to show package details if you want to view every package that resulted from the binding.
        • When Expand PKLIST to show package details is checked, you can also check Show package version information to display version information for each package.
      3. Click Free Plan.
  6. Click OK to confirm.
Parent topic: Manage Packages and Plans Tasks
Related concepts
Manage Packages and Plans Tool
Binding Applications
Freeing Packages and Plans
Related reference
Free Plans tab


Bind Applications

  • To bind from the command line
  • To bind as a post-build event
  • To manually code a bind script file
  • To bind from JCL
Parent topic: How to


To bind from the command line

Restriction: This topic applies to Windows environments only.
  1. Create a bind script file using the Manage Packages and Plans tool, or manually in a text editor. If you create the file in a text editor, be sure to give it a file extension of .hcodsn.
    Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.
  2. Using the Manage Connections tool, connect to your SQL Server database with a login ID and password that grants you permission to update the SYSIBM table.
  3. Open an Enterprise Developer command prompt.
  4. Enter the following command:

    DSN SYSTEM(SQLServerConnection) @"bindScriptFile"

    where SQLServerConnection is the name of your SQL Server connection, and bindScriptFile is the full path to and filename of your bind script file.

Parent topic: Bind Applications
Related concepts
DSN Bind Utility
Binding Applications
Related tasks
To manually code a bind script file
Related reference
DSN command
Bind Script Commands


To bind as a post-build event

Restriction: This topic applies to Windows environments only.
  1. Build your application using the DBRMLIB SQL compiler option to create DBRMs from your source code.
  2. Create a bind script file using the Manage Packages and Plans tool, or manually in a text editor. If you create the file in a text editor, be sure to give it a file extension of .hcodsn.
    Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.
  3. Using the Manage Connections tool, connect to your SQL Server database with a login ID and password that grants you permission to update the SYSIBM table.
  4. In Eclipse, open the properties for the project that contains your application.
  5. In the Properties window, expand Micro Focus > Build Configurations > Events.
  6. In the Post-build event command line field, type the following:

    DSN SYSTEM(SQLServerConnection) @"bindScriptFile"

    where SQLServerConnection is the name of your SQL Server connection, and bindScriptFile is the full path to and filename of your bind script file.

  7. Click OK twice to close both the Build Events and Advanced COBOL Settings dialog boxes.
Parent topic: Bind Applications
Related concepts
DSN Bind Utility
Binding Applications
Application Migration Process
Related tasks
To manually code a bind script file
Related reference
DSN command
Bind Script Commands


To manually code a bind script file

Restriction: This topic applies to Windows environments only.
  1. Open a text editor of your choice.
  2. Type each command on its own line.
    Note: For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.
  3. At the end of the file, type END.
  4. Save the file to a location of your choice, using a .hcodsn filename extension.
Parent topic: Bind Applications
Related concepts
DSN Bind Utility
Binding Applications
Related tasks
To bind from the command line
To bind as a post-build event
Related reference
DSN command
Bind Script Commands


To bind from JCL

Restriction: This topic applies to Windows environments only.
  1. In your JCL, code a DSN statement followed by appropriate BIND statements.
    //SYSTSIN  DD *
  DSN SYSTEM(XAResourceName)
  BIND bindArguments
  [BIND...]
  END

    For example:

    //SYSTSIN  DD *
  DSN SYSTEM(HCODemo)
  BIND PLAN(TWOPACKAGESET) ACTION(REPLACE) LIBRARY(DBRMLIB) -
  MEMBER(TWOPACKAGESET) QUALIFIER(PROD)
  END
  2. Save your JCL.
Note: For a listing of DSN commands supported by HCOSS, see the topic Bind Script Commands.
Parent topic: Bind Applications


Customize HCOSS

Restriction: This topic applies to Windows environments only.
  • To set HCOSS options
  • To customize data type mappings
  • To customize SQL name mappings
  • To customize SQLCode mappings
Parent topic: How to


To set HCOSS options

Restriction: This topic applies to Windows environments only.

By starting HCOSS in standalone mode:

  1. Start HCO for SQL Server in standalone mode or from Eclipse. See To start HCO for SQL Server for details.
  2. From the HCO for SQL Server interface, click Options.
  3. Set options as needed.
    Tip: Context help for each setting appears at the bottom of the window.
  4. Click OK to save your settings.
Parent topic: Customize HCOSS
Related concepts
HCOSS Toolset
Using HCOSS with Windows User Account Control (UAC)
Related tasks
To start HCO for SQL Server
Related reference
Options


To customize data type mappings

Restriction: This topic applies to Windows environments only.
  1. From the HCO for SQL Server interface, click Data Type Mappings.
  2. To change default mappings, use the drop-down list to select a new value for any entry on the page.
  3. To add a new mapping:
    1. Scroll down to the bottom of the page.
    2. In the blank row at the bottom of the page, select values for each column.
    Note: Each time you click a field in the blank bottom row, a new blank row appears underneath to enable you to add another new mapping.
  4. Click Save.
Parent topic: Customize HCOSS
Related concepts
Customizing Data Type Mappings
Related reference
Default Data Type Mappings
Data Mappings tab


To customize SQL name mappings

Restriction: This topic applies to Windows environments only.
  1. From the HCO for SQL Server interface, click SQL Name Mappings.
  2. To change default mappings, do one or more of the following:
    • To change the name of any DB2 Functions/Special Register or its SQL Server Equivalent, simply click in the field and type in your change.
    • To change the mapping type for any DB2 Function/Special Register, check one or both of its correponding check boxes.
  3. To add a new mapping:
    1. Scroll down to the bottom of the page.
    2. In the field at the bottom of the DB2 Function/Special Register column, type in the name of a DB2 function or special register that exists in your DB2 database but is not already listed as a default.
    3. Type a corresponding SQL Server equivalent name into the SQL Server Equivalent column.
    4. Depending on what applies to your new mapping, check the appropriate box or boxes in the Is Function or Special Register columns.
    Note: Each time you type into a field or check a box in the blank bottom row, a new blank row appears underneath to enable you to add another new mapping.
  4. Click Save.
Parent topic: Customize HCOSS
Related concepts
Customizing Functions and Special Registers
Customizing SQL Identifiers
Related reference
Default Function Mappings
Default Special Register Mappings
SQL Name tab


To customize SQLCode mappings

Restriction: This topic applies to Windows environments only.
  1. From the Customize SQLCode Mappings tool, click the SQLCode Mappings tab. HCOSS loads the SQLCode mappings found in the mfhcocds.txt file.
  2. To restore previous mappings from a backup file, click Restore (optional).
  3. To change the mappings, click any field on the grid and type in a new value. All values must be in valid SQLCode or SQLState value format.
  4. To add a new mapping, click the blank row at the bottom of the grid and type in a new value for each column.
    Note: Each time you click a field in the blank bottom row, a new blank row appears underneath to enable you to add another new mapping.
  5. To save your changes to the mfhcocds.txt file and create a backup file with the initial mappings, click Save.
  6. To deploy the changes to your SQL Server database (required when using SQL CLR stored procedures), click Deploy. This takes you to the Deploy / Extract tab.
  7. From the Data Source Name drop-down list, select the data source you want to update with the new mappings.
  8. Complete the User ID and Password fields only if required by your data source.
  9. Click Deploy to SS.
  10. To extract the SQLCode mapping information from the SQL Server database to a backup file, click Extract from SS (optional).
Parent topic: Customize HCOSS
Related concepts
Customize SQLCode Mappings Tool
Related reference
Deploy/Extract tab
SQLCode Mappings tab


Reference

  • Command Line Reference
  • SQL Compiler Directive Options - HCOSS
  • DBMAN Directive Settings - HCOSS
  • Required DB2 Catalog Tables
  • DB2 to SQL Server Conversion Reference
  • Bind Script Commands
  • HCOSS Messages
  • Log Files
  • User Interface Reference
Parent topic: HCO for SQL Server (HCOSS)


Command Line Reference

  • MFDataTransferCtlr command
    Executes the HCOSS Transfer Data tool from the command line.
  • MFDDLConverter command
    Executes the HCOSS Generate DDL tool from the command line.
  • MFExtractSchemaInfo command
    Executes the HCOSS Extract Schema tool from the command line.
  • MFObjectList command
    Executes the HCOSS Define Lists tool from the command line.
  • MFTestConversion command
    Executes the HCOSS Compare Data tool from the command line.
  • COMPARE Command File
    Explains how to code a COMPARE command file to use with the MFTestConversion command, IN parameter.
  • DSN command
    Executes the DSN Bind utility, which performs schema updates as necessary and executes the commands contained in an HCOSS bind script file.
Parent topic: Reference


MFDataTransferCtlr command

Executes the HCOSS Transfer Data tool from the command line.
Restriction: This topic applies to Windows environments only.

Syntax:

{MFDataTransferCtlr | MFDataTransferCtlr16} DB2=DB2dsn;
                                            [U1=DB2userID;]
                                            [P1=DB2Password;]
                                            SRV=SQLServerDSN;
                                            [U2=SQLServerUserID;]
                                            [P2=SQLServerPassword;]
                                            X=["]DataTransferList["];
                                            [XLocal={TRUE | FALSE};]
                                            [TRIG={TRUE | FALSE};]
                                            [CONSTR={TRUE | FALSE};]
                                            [ErrROW={TRUE | FALSE};]
                                            [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

MFDataTransferCtlr
The name of the command for SQL Server versions earlier than SQL Server 2016.
MFDataTransferCtlr16
The name of the command for SQL Server 2016.
DB2
The name of a cataloged and registered DB2 data source.
U1
The user ID required to access the DB2 data source specified by the DB2 parameter, if applicable.
P1
The password required for the user ID specified by the U1 parameter, if applicable.
SRV
The name of a cataloged and registered SQL Server data source.
U2
The user ID required to access the SQL Server data source specified by the SRV parameter. Not required when using Windows authentication.
P2
The password required for the user ID specified by the U2 parameter, if applicable.
X
The name of a transfer data task file containing a list of tables to be transferred and the queries required to transfer the data. Do not specify a file extension. The file extension for a transfer data task file is .hcodtt. If the transfer data task file name contains spaces, surround it with a set of double quotes ("). You can create a transfer data task file using the UI version of the HCOSS Transfer Data tool, or you can create one manually in a text editor. If you create a transfer data task file using the UI version of the tool, its location is determined by the selection of either the Local or Shared button for the transfer data task. If you create a data transfer task file manually, you must store it in the \DataTasks subdirectory of either the directory specified by the Local HCOSS Directory HCOSS option or the Shared HCOSS Directory HCOSS option.
XLocal
Determines the location of the transfer data task file. Transfer data task files are stored in the \DataTasks subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
TRIG
Specifies whether or not to fire all triggers during the data transfer. Default is FALSE.
CONSTR
Specifies whether or not SQL Server performs all defined checks during the data transfer. Default is FALSE.
ErrROW
Specifies whether or not HCOSS logs errors encountered during the data transfer. Default is FALSE.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.

Comments:

Before running this tool, be sure that the appropriate target tables exist in the SQL Server database.

Examples:

MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=LocalTransferList
MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=SharedTransferList; XLocal=FALSE
Parent topic: Command Line Reference
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task
Related reference
Transfer Data Tool Log Files
Transfer Data Tool Error Messages


MFDDLConverter command

Executes the HCOSS Generate DDL tool from the command line.
Restriction: This topic applies to Windows environments only.

Syntax

MFDDLConverter S=schemaExtractFile;
               [SLocal={TRUE | FALSE};]
               O=["]DDLOutputFile["];
               DROP={DR | CNE};
               SYSIBM={TRUE | FALSE};
               [M=["]dataMappingFile["];]
               [TYPE={TABLE | VIEW | ALL};]
               [SCHEMA=DB2Schema1[, DB2Schema2 ...];]
               [NAME=objectName;]
               [ROWSIZE={TRUE | FALSE};]
               [INCDEP={TRUE | FALSE};]
               [STITCH={TRUE | FALSE};]
               [TYPELOG={CONSOLE | FILE | BOTH};]
               [FOOTER={TRUE | FALSE};]
               [CCSID={KEEP | IGNORE};]

Parameters:

S
The name of a schema extract file generated using the HCOSS Schema Extract tool. Do not specify a file extension.
SLocal
Specifies the location of the generated schema extract file. Schema extract files are stored in the \Schemas subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
O
The full path to and filename of the generated DDL command file (usually given a .sql file extension). If this specification contains spaces, enclose it in double quotes (").
DROP
Determines how objects are handled in the generated DDL.
DR | Drop and recreate all objects
CNE | Create a new database object for each object in the object list that does not already exist in the database
SYSIBM
Specifies whether or not to include the SYSIBM schema in the generated DDL. Both the SYSIBM schema and its dependent objects are included when set to TRUE; however, the SYSIBM schema and its dependent objects must be present in the schema extract file to be included in the generated DDL.
M
Full path to and filename of the HCOSS data mapping file. If this specification contains spaces, enclose it in double quotes ("). Defaults to %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\DataMappings.hcomap.
TYPE
Limits objects to tables only or views only. Default is ALL.
SCHEMA
The name of one or more valid DB2 schemas to include in the generated DDL. Separate schema names with a comma (,). You may also use the % wild card character in schema names. Defaults to all schemas in the object list file.
NAME
Filters the generated DDL to include only the specified DB2 table or view name. You may use the % wild card character in table and view names. Defaults to all table and view names.
ROWSIZE
Specifies whether or not to check table column widths to determine if they exceed the SQL Server row width limit of 8060 and write the information to the log file.
TRUE | Check table column widths.
FALSE | Do not check table column widths. Default.
INCDEP
Specifies whether or not to include table and view dependencies when processing objects.
TRUE | Include table and view dependencies.
FALSE | Do not include table and view dependencies. Default.
STITCH
Specifies whether or not to include a DDL header in the generated DDL:
TRUE | Include DDL header.
FALSE | Exclude DDL header. Default.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.
FOOTER
Specifies whether or not to include a DDL footer in the generated DDL:
TRUE | Include DDL footer. Default.
FALSE | Exclude DDL footer.
CSSID
Specifies whether or not to preserve the mainframe sort order for text columns:
KEEP | Preserves the mainframe sort order by adding a CCSID clause to the table definition.
IGNORE | Returns text columns in the order specified by the SQL Server target database or table collation identifier. Default.

Example:

MFDDLConverter S=MySchemaExtract; O=c:\ProgramData\MyDDL.sql; DROP=DR; SYSIBM=TRUE
Parent topic: Command Line Reference
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
Generate DDL Tool Log Files
Generate DDL Tool Error Messages


MFExtractSchemaInfo command

Executes the HCOSS Extract Schema tool from the command line.
Restriction: This topic applies to Windows environments only.

Syntax:

MFExtractSchemaInfo [DB2={DB2Connection | SQLServerConnection;]
                    [ACTION={DELETE | EXTRACT | EXPORT | IMPORT | LIST};]
                    [U=DB2UserID;]
                    [P=DB2Password;]
                    [{NAME | OUT}=SchemaExtractFileName;]
                    [{OUTLocal={TRUE | FALSE}} |
                        LOCATION={LOCAL | SHARED}};]
                    [{SCHEMA={* | DB2Schema1[, DB2Schema2 ...]} |
                       TBS={DB2Tablespace1[, DB2Tablespace2 ...]}}];
                    [PATH=DirectoryPath;]
                    [ROWCOUNT={ESTIMATE | EXACT};]
                    [CATALOG=DB2SchemaName;]
                    [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

DB2
The name of a cataloged DB2 connection or, when using the Offline Extract Schema Solution, the name of a cataloged SQL Server connection. Required when ACTION=EXTRACT, which is the default setting.
ACTION
Specifies the action to perform:
DELETE | Deletes the schema extract file.
EXTRACT | Extract the schema(s) specified by the SCHEMA parameter. Default.
EXPORT | Copy the generated schema extract file to the directory specified by the PATH parameter, enabling you to use it to import the schema into the tool when the mainframe is not available.
IMPORT | Import a previously exported schema extract file, located in the directory specified by the PATH parameter.
LIST | Outputs a list to the console, showing the schema extract files located in the directory specified by the OUTLocal parameter setting.
The following matrix shows the additional required and optional parameters for each ACTION value:
ACTION
Parameter | DELETE | EXTRACT | EXPORT | IMPORT | LIST
DB2 | N/A | Required | N/A | N/A | N/A
U | N/A | Optional | N/A | N/A | N/A
P | N/A | Optional | N/A | N/A | N/A
NAME | OUT | Required | Required | Required | Required | N/A
OUTLocal | Optional | Optional | Optional | Optional | Optional
LOCATION | Optional | Optional | Optional | Optional | Optional
SCHEMA | TBS | N/A | Required | N/A | N/A | N/A
PATH | N/A | N/A | Required | Required | N/A
ROWCOUNT | N/A | Optional | N/A | N/A | N/A
CATALOG | N/A | Optional | N/A | N/A | N/A
TYPELOG | Optional | Optional | Optional | Optional | Optional
U
The user ID required to access the DB2 database specified by the DB parameter, if applicable.
P
The password required for the user ID specified by the U parameter, if applicable.
NAME | OUT
The name of the generated schema extract file for ACTION=DELETE, EXTRACT, IMPORT or EXPORT. Do not specify a file extension. The default file extension is .hcodbs.
OUTLocal
Determines the location of the generated schema extract file. Schema extract files are stored in the \Schemas subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
LOCATION
Sets the output directory for the schema extract file to:
LOCAL | Directory specified by the Local HCOSS Directory HCOSS option. Default.
SHARED | Directory specified by the Shared HCOSS Directory HCOSS option.
SCHEMA
The name of one or more valid DB2 schemas to extract. An asterisk (*) extracts all schemas in the catalog. Separate schema names with a comma (,).
TBS
The name of one or more valid DB2 tablespaces to extract. Separate tablespace names with a comma (,).
PATH
Specifies the directory to be used for IMPORT and EXPORT of schema extracts.
ROWCOUNT
Specifies the type of table row count information recorded:
ESTIMATE | Records the estimated table row count based on the schema statistics stored in SYSIBM.SYSTABLES. Use this option to improve performance. Default.
EXACT | Records both the estimated table row count and the actual row count as retrieved using a SELECT BIG-COUNT(*) query. Use this option to provide accuracy.
CATALOG
The name of the DB2 catalog schema. Defaults to SYSIBM.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.

Example:

MFExtractSchemaInfo DB2=MVS91; OUT=LocalSchemaExtract; SCHEMA=MFIREX,SDI002; TYPELOG=FILE
MFExtractSchemaInfo DB2=MVS91; OUT=SharedSchemaExtract; OUTLocal=FALSE; SCHEMA=MFIREX%,SDI002
Parent topic: Command Line Reference
Related concepts
Extract Schema Tool
Offline Extract Schema Solution
Related tasks
To extract DB2 schema objects
To modify a schema extract file
Related reference
Extract Schema Tool Log Files
Extract Schema Tool Error Messages


MFObjectList command

Executes the HCOSS Define Lists tool from the command line.

Syntax:

MFObjectList S=schemaExtractFile;
             [SLocal={TRUE | FALSE};]
             OUT=objectListOutputFile;
             [OUTLocal={TRUE | FALSE};]
             [M=["]dataMappingFile["];]
             [SYSIBM={TRUE | FALSE};]
             [TYPE={TABLE | VIEW | ALL};]
             [SCHEMA=DB2Schema1[, DB2Schema2 ...];]
             [NAME=objectName;]
             [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

S
The name of a schema extract file generated using the HCOSS Schema Extract tool. Do not specify a file extension.
SLocal
Determines the location of the schema extract file specified by the S parameter. Schema extract files are stored in the \Schemas subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
OUT
The name of the generated object list file. Do not specify a file extension. The default file extension is .hcolst.
OUTLocal
Determines the location of the generated object list file. Object list files are stored in the \TargetLists subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
M
Full path to and filename of the HCOSS data mapping file. If this specification contains spaces, enclose it in double quotes ("). Defaults to %ALLUSERSPROFILE%\Micro Focus\Enterprise Developer\hcoss\DataMappings.hcomap.
SYSIBM
Specifies whether or not to include the SYSIBM schema. Default is FALSE.
TYPE
Limits objects to tables only or views only. Default is ALL.
SCHEMA
The name of one or more valid DB2 schemas to include on the object list. Separate schema names with a comma (,). You may also use the % wild card character in schema names. Defaults to all schemas specified in the schema extract file.
NAME
Filters the object list to include only the specified DB2 table or view name. You may use the % wild card character in table and view names. Defaults to all table and view names.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.
MFObjectList S=LocalSchemaExtract; OUT=LocalObjectList; SCHEMA=MFIREX%,SDI002; TYPELOG=FILE
MFObjectList S=SharedSchemaExtract; SLocal=FALSE; OUT=SharedObjectList; OUTLocal=FALSE; SCHEMA=MFIREX%,SDI002;
Parent topic: Command Line Reference
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list
Related reference
Define Lists Tool Log Files
Define Lists Tool Error Messages


MFTestConversion command

Executes the HCOSS Compare Data tool from the command line.

Syntax:

MFTestConversion {X=["]compareDataTaskFile["] | IN=["]compareCommandsFile["]};
                 [XLocal={TRUE | FALSE};]
                 [INLocal={TRUE | FALSE};]
                 [DB2=DB2DataSource;]
                 [U1=DB2Userid;]
                 [P1=DB2Password;]
                 [SRV=SQLServerDataSource;]
                 [U2=SQLServerUserid;]
                 [P2=SQLServerPassword;]
                 [TYPELOG={CONSOLE | FILE | BOTH};]

Parameters:

X
The name of a compare data task file containing compare commands generated by the UI version of the Compare Data tool. Do not specify a file extension. The file extension for a compare data task file is .hcocpt. If the compare data task file name contains spaces, surround it with a set of double quotes ("). The location of a compare data task file is determined by the selection of either the Local or Shared button for the compare data task.
IN
A flat text input file containing HCOSS COMPARE commands designed to carry out a user-defined set of comparisons. You can code this file in any text editor. No filenaming convention is enforced for this file; however, if the file name contains spaces, surround it with a set of double quotes (").
XLocal
Specifies the location of the compare data task file. Compare data task files are stored in the \CompareTasks subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
INLocal
Determines the location of the compare commands file. Compare commands files are stored in the \CompareTasks subdirectory of either of the following, depending on the value specified:
TRUE | Directory specified by the Local HCOSS Directory HCOSS option. Default.
FALSE | Directory specified by the Shared HCOSS Directory HCOSS option.
DB2
The name of a cataloged and registered DB2 data source. Required when using the IN parameter, and required when using the X parameter only to override the connection specified in the compare data task file.
U1
The user ID required to access the DB2 data source specified either by the DB2 parameter or within the data task file, if applicable, and if the user ID for the DB2 data source is not stored with the specified connection.
P1
The password required for the user ID specified by the U1 parameter, if applicable, and if the password for the user ID specified in the U1 parameter is not stored with the specified connection.
SRV
The name of a cataloged and registered SQL Server data source. Required when using the IN parameter, and required when using the X parameter only to override the connection specified in the compare data task file.
U2
The user ID required to access the SQL Server data source specified either by the SRV parameter or within the data task file. Not required when using Windows authentication. If not using Windows Authentication, this is required only if the user ID for the SQL Server data source is not stored with the specified connection.
P2
The password required for the user ID specified by the U2 parameter, if applicable, and if the password for the user ID specified in the U2 parameter is not stored with the specified connection.
TYPELOG
Sets the type of logging to perform. Defaults to the equivalent of the value specified for the Type of logging to do HCOSS option.

Comment:

Parameters may be given in any order.

Example:

MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=LocalCompareData; TYPELOG=FILE
MFDataTransferCtlr DB2=MVS91; SRV=HCODemo; X=SharedCompareData; XLocal=FALSE
Parent topic: Command Line Reference
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
COMPARE Command File
Compare Data Tool Log Files
Compare Data Tool Error Messages


COMPARE Command File

Explains how to code a COMPARE command file to use with the MFTestConversion command, IN parameter.
Restriction: This topic applies to Windows environments only.

Syntax:

USE DB2;
SELECT arguments;
USE SRV;
SELECT arguments;
COMPARE [integer ROWS] [SKIP COL integer1 [integer2 ...]]
[USE DB2;
SELECT arguments;
USE SRV;
SELECT arguments;
COMPARE [integer ROWS] [SKIP COL integer1 [integer2 ...]]
[...]]

Parameters:

USE DB2
Execute the following SQL SELECT command against the DB2 connection specified on the MFTestConversion command line.
USE SRV
Execute the following SQL SELECT command against the SQL Server connection specified on the MFTestConversion command line.
SELECT arguments
Any valid SQL SELECT statement returning a set of values to be compared. Each SELECT statement applies to the database specified in the USE statement that immediately precedes it. You must code at least one SELECT statement corresponding to the preceding USE DB2 and USE SQL statements respectively before coding a COMPARE statement. The returned values for both SELECT statements preceding a COMPARE statement should include the same list of columns in the same order to ensure success. Qualifiers for table names and column names can differ, depending on how the tables are defined in their respective databases.
COMPARE
With no arguments, compares all rows and all columns in the result sets for each preceding SELECT statement.
integer ROWS
Compare only the first integer rows, where integer represents any number greater than zero (0).
SKIP COL integer [integer ...]
Do not return compare information for each column number specified by integer, where integer represents any number greater than zero (0) and less than the number of columns in the SELECT list or 749; separate each specified integer with a space.

Comments:

Code a COMPARE command file using any text editor and save with the filename of your choice in either the directory specified by the Local HCOSS Directory or the directory specified by the Shared HCOSS Directory HCOSS option.

You can code multiple comparisons into a single COMPARE command file.

USE and COMPARE commands and their respective arguments are not case sensitive.

SQL SELECT statements might be case sensitive depending on how the database handles case sensitivity.

You can combine the ROWS and SKIP COL options.

Synonyms for COL are:
  • COLUMN
  • COLUMNS
  • COLS

Examples:

Compare all returned tables and rows:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE;
Compare a limited number of rows:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE 10 ROWS;
Skip certain columns:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE SKIP COLS 3 5 15;
Compare a limited number of rows and skip certain columns:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE 10 ROWS SKIP COLS 3 5 15;
Include more than one comparison in a single COMPARE command file:
USE DB2;
SELECT * FROM EMPINFO2;
USE SRV;
SELECT * FROM EMPINFO2;
COMPARE 10 ROWS SKIP COLS 3 5 15;
USE DB2;
SELECT * FROM EMPINFO3;
USE SRV;
SELECT * FROM EMPINFO3;
COMPARE;
Parent topic: Command Line Reference
Related reference
MFTestConversion command


DSN command

Executes the DSN Bind utility, which performs schema updates as necessary and executes the commands contained in an HCOSS bind script file.
Restriction: This topic applies to Windows environments only.

Syntax

DSN SYSTEM(SQLServerConnection) @"bindScriptFile"
[ASUSER(userID.password)]

Parameters

SQLServerConnection | The name of an established connection to a SQL Server database.
bindScriptFile | The full path to and filename of the bind script (.hcodsn) file that contains the commands you want to execute.1
userID | The user ID required to log onto your SQL Server database. Enclose in double quotes (") if the user ID contains non-alphanumeric characters.2
password | The password required to log onto your SQL Server database. Enclose in double quotes (") if the password contains non-alphanumeric characters.2

1 For a listing of commands that are valid in HCOSS bind script files, see the topic Bind Script Commands.

2 The level of database access permissions required by these login credentials can vary. For details, see the topic DSN Bind Utility.

Comments

  • DSN.exe is in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.
  • Execute DSN.exe either from a command prompt in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory, or execute it as a post-build event.
  • When deploying to a remote server, you can optionally execute DSN.exe on your deployment server instead of your development server; however, to do this you must have appropriate permissions on the deployment server machine.
  • Create the bind script file either with the Manage Packages and Plans tool, or manually in a text editor.
  • If you omit the ASUSER parameter, DSN uses Windows authentication, prompting you for a username and password if it fails.
Parent topic: Command Line Reference
Related concepts
DSN Bind Utility
Binding Applications
Migration Scenarios
Deploying Native Applications
Related tasks
To bind from the command line
To bind as a post-build event
To manually code a bind script file
Related reference
BIND
Bind Script Commands


SQL Compiler Directive Options - HCOSS

Restriction: This topic applies to Windows environments only.
Important: When compiling from within Eclipse, set these directives by opening your projects Properties dialog box, choosing Micro Focus > Project Settings > COBOL and entering them in the Additional Directives field.
  • CHECKCALLPARAMS
    Directive automatically set by DIALECT=MAINFRAME. It evaluates the parameters on a stored procedure call to determine if they are input or output.
  • CHECKSP
    Checks the parameters set for the SPCALLLOCAL directive to ensure that they match the stored procedure definition.
  • DATE
    Specifies the explicit date format to use when date values are returned from SQL Server date columns in character output host variables.
  • DBRMLIB
    Enables generation of DBRMs containing the static SQL statements from COBOL programs, mimicking mainframe-style binding.
  • DETECTDATE
    Allows datetime values for PIC X character input host variables in a mainframe DB2 application to be in different formats than those supported by SQL Server.
  • DIALECT
    Enables SQL dialect compatibility features for HCOSS in the OpenESQL preprocessor, turning on automatic mapping of functions, special registers, data types, and all other automatic HCOSS conversions, and enabling the use of DIALECT statement prefixes. Converts DB2 SQL statements that are not compatible with SQL Server into equivalent T-SQL statements in most cases.
  • MEMBER
    Specifies a non-default name for the DBRM.
  • OPTION (deprecated)
    Enables non-default optional behavior.
  • PROMOTE
    Saves generated DBRMs to the shared HCOSS DBRM library.
  • QUALIFIER
    Qualifies unqualified table and view names.
  • SPCALLLOCAL
    For native HCOSS applications, transforms an SQL call to a SQL Server stored procedure (i.e., an EXEC SQL CALL statement) into a standard COBOL call to a local COBOL subroutine.
  • STRICTPARSE
    Provides enhanced diagnostics for SQL statements not recognized by the HCOSS DB2 parser.
  • TIME
    Specifies an explicit time format to use when time values are returned from SQL Server time columns in PIC X character output host variables.
  • VERSION
    Specifies a version for a DBRM.
Parent topic: Reference
Related concepts
Scope - HCOSS SQL Compiler Directive Options
HCO for SQL Server Compiler Directive Options for PL/I
Related reference
SQL Compiler Directive Options
DBMAN Directive Settings - HCOSS


CHECKCALLPARAMS

Directive automatically set by DIALECT=MAINFRAME. It evaluates the parameters on a stored procedure call to determine if they are input or output.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]CHECKCALLPARAMS

Properties:

Default: When DIALECT=MAINFRAME, CHECKCALLPARAMS

Otherwise, invalid directive

Dependencies:

When DIALECT=MAINFRAME is set and your stored procedure parameters are explicitly declared in your code as input or output, set NOCHECKCALLPARAMS to turn off the input/output evaluation of parameters.

Note: In versions of Enterprise Developer earlier than 2.3, DIALECT=MAINFRAME did not automatically set CHECKCALLPARAMS. When using an earlier version, you must specify CHECKCALLPARAMS explicitly to enable the input/out evaluation.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Scope - HCOSS SQL Compiler Directive Options
Related reference
DIALECT


CHECKSP

Checks the parameters set for the SPCALLLOCAL directive to ensure that they match the stored procedure definition.
Restriction: This topic applies to Windows environments only.

Syntax:

CHECKSP=SPDFileName

Properties:

Default: None

Parameters:

SPDFileName
A stored procedure definition (SPD) file, which is a flat file containing CREATE PROCEDURE statements extracted from the original stored procedure.

Dependencies:

Requires that DIALECT=MAINFRAME and SPCALLLOCAL also be set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Comments:

Be sure that the SPD file contains all stored procedure definitions required for CHECKSP to compare the definitions to the arguments used in calling programs.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Scope - HCOSS SQL Compiler Directive Options
Related reference
SPCALLLOCAL


DATE

Specifies the explicit date format to use when date values are returned from SQL Server date columns in character output host variables.
Restriction: This topic applies to Windows environments only.

When used in addition to DETECTDATE, specifies the explicit data format to recognize in character input host variables.

Restriction: This topic documents DATE as used as an HCOSS SQL compiler directive option and therefore assumes that you have set DIALECT=MAINFRAME. For information on using DATE as a generic SQL compiler directive option, see DATE under SQL Compiler Directive Options. For information on the DIALECT HCOSS SQL compiler directive option, see DIALECT.

Syntax

DATE={ODBC | ISO | USA | EUR | JIS}

Parameters:

ODBC
yyyy-mm-dd (SQL Server default format)
ISO
yyyy-mm-dd (mainframe default format)
USA
mm/dd/yyyy
EUR
dd.mm.yyyy
JIS
yyyy-mm-dd

Properties:

Default: ISO (mainframe default format)

Dependencies:

To use DATE, you must also set DIALECT=MAINFRAME.

For input host parameters, requires that the DETECTDATE HCOSS SQL compiler directive option also be set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Comments:

DATE changes the display format of output host variables as specified.

Note: If you do not specify an alternative format using DATE, HCOSS returns your SQL Server date columns using mainframe ISO format in your output character host variables by default, as specified in the Properties section of this topic.

When you specify both DATE and DETECTDATE, HCOSS uses DATE to recognize date values in your input host variables. See DETECTDATE for more information.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
HCO for SQL Server Compiler Directive Options for PL/I
Building Applications
Scope - HCOSS SQL Compiler Directive Options
HCOSS Datetime Data Type Handling
Related reference
DETECTDATE
DIALECT


DBRMLIB

Enables generation of DBRMs containing the static SQL statements from COBOL programs, mimicking mainframe-style binding.
Restriction: This topic applies to Windows environments only.

Syntax, Format 1:

DBRMLIB[=DBRMLIBName]

Syntax, Format 2:

NODBRMLIB

Parameters:

DBRMLIBName
A name for the DBRM library. The value provided must conform to the syntax for mainframe Partitioned Data Set names as follows:
  • Maximum length is 44 bytes.
  • Must specify one or more simple names separated by periods (‘.’). A simple name can be up to eight bytes in length, starts with a character, and is made up of a combination of alphabetic characters, digits, or the following special characters: @, #, $, -

Properties:

Default: DBRMLIB

This is the equivalent of DBRMLIB=DBRMLIB.

Dependencies:

Requires that DBMAN is set to ODBC.

Requires that the TARGETDB SQL directive be set to TARGETDB=MSSQLSERVER.

Automatically sets the CHECK SQL directive.

Mutually exclusive with both BIND and ACCESS.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Advantages:

  • Mainframe deployment compatibility, meaning you can bind using existing JCL.
  • You can bind a DBRM multiple times using different parameters each time, such as different default qualifiers.
  • You can apply security separately to procedures and data so that application users can only access and update data via the application.
  • You can use the Manage Packages and Plans tool to manage DBRM binding and freeing.
  • Enables HCOSS to maintain mainframe-compatible metadata in the database for bound packages and plans.
  • DBAs can review SQL after binding by browsing stored procedures without having to access source code.

Comments:

If required to fully emulate your mainframe setup, you can also specify the MEMBER and VERSION directives.

Before running your application, use the DSN command or the Manage Packages and Plans tool to bind DBRMs to packages and/or plans in the database.

Packages and plans are stored as SQL Server stored procedures.

When DBRMLIB is set, the precompiler and runtime system process the following statements:
SET CURRENT PACKAGESET
SET CURRENT PACKAGE PATH
SET APPLICATION PLAN

DBRMs are stored as XML files with an extension of .hcodbrm in the localHCOSSFiles\DBRMDataSets\DBRMLIBName directory, where localHCOSSFiles represents the value of the Local HCOSS Directory HCOSS option, and DBRMLIBName represents the value of the DBRMLIB directive.

DBRMLIB supports the following SET statements, with the runtime system processing them internally:
SET CURRENT PACKAGESET
VALUES INTO CURRENT PACKAGESET
SET CURRENT PACKAGE PATH
VALUES INTO CURRENT PACKAGE PATH

DBRMLIB enables use of the APPLICATION PLAN special register, that can be used in SET host-variableAssignment and VALUES INTO statements, and also supports the SET APPLICATION PLAN statement, which allows an application to set the application plan to be used when static SQL statements in DBRMs generated by the DBRMLIB directive are executed.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Building Applications
Managing DBRMs
Shared DBRMs and multi-user environments
Local DBRMs
Scope - HCOSS SQL Compiler Directive Options
Related reference
MEMBER
VERSION
DIALECT
QUALIFIER
PROMOTE


DETECTDATE

Allows datetime values for PIC X character input host variables in a mainframe DB2 application to be in different formats than those supported by SQL Server.
Restriction: This topic applies to Windows environments only.
Restriction: This topic applies to DETECTDATE as an HCOSS SQL compiler directive option only. For information on using the OpenESQL DETECTDATE SQL compiler directive option, see DETECTDATE under SQL Compiler Directive Options.
DETECTDATE enables you to specify alternative formats for input host variables. HCOSS manages the translation between the format specified by DETECTDATE and the format recognized by SQL Server. This is done for each SQL call on both input and output.

For example, SQL Server supports formatted values for datetime fields as cited in HCOSS Datetime Data Type Handling. For a mainframe DB2 application that uses datetime formats, such as EUR, that are not supported by SQL Server, with DETECTDATE you can still run it against a SQL Server database keeping the EUR datetime formats intact even though the SQL Server database does not accept those formats.

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 HCOSS Datetime Data Type Handling, and the information in the DATE and TIME 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, HCOSS recognizes specified datetime formats and translates the data into a format acceptable to SQL Server for processing. Specified datetime formats for input host variables are:
Date
Mainframe default, can be overridden by specifying the DATE HCOSS directive.
Time
Mainframe default, can be overridden by specifying the TIME HCOSS directive.
Timestamp
  • 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
Output Host Variables
For PIC X as well as SQLTYPE output character host variables, HCOSS returns the data for output host variables in the following datetime formats:
Date
Mainframe default, can be overridden by specifying the DATE HCOSS directive.
Time
Mainframe default, can be overridden by specifying the TIME HCOSS directive.
Timestamp
yyyy-mm-dd-hh.mm.ss.ffffff
SQLTYPE
Note: Deprecated feature starting with Enterprise Developer 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 - HCOSS SQL Compiler Directive Options for more information.

Comments:

  • Use DETECTDATE=CLIENT only when your mainframe DB2 application does not use character columns in the database to store data that is a match to any of the alternative formats for SQL Server date, time or datetime2 fields.
  • Use DETECTDATE=SERVER when your mainframe DB2 application uses datetime values in both datetime and character columns of tables in the SQL server database.
    Note: DETECTDATE=SERVER does cause HCOSS to perform extra overhead processing on each applicable SQL statement.
  • Datetime formats are defined implicitly unless you set them explicitly by specifying the DATE and/or TIME directives. See DATE and TIME for more information.
Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
HCO for SQL Server Compiler Directive Options for PL/I
Scope - HCOSS SQL Compiler Directive Options
HCOSS Datetime Data Type Handling
Related reference
DATE
TIME


DIALECT

Enables SQL dialect compatibility features for HCOSS in the OpenESQL preprocessor, turning on automatic mapping of functions, special registers, data types, and all other automatic HCOSS conversions, and enabling the use of DIALECT statement prefixes. Converts DB2 SQL statements that are not compatible with SQL Server into equivalent T-SQL statements in most cases.
Restriction: This topic applies to Windows environments only.

Syntax:

DIALECT={MAINFRAME | MIXED | NONE} [overrides]

Parameters:

MAINFRAME
  • All statements that are compatible with DB2 are converted by HCOSS
  • Unqualified table and view specifications in DB2-compatible statements can be qualified by the SQL(QUALIFIER) directive option or the QUALIFIER parameter on BIND PACKAGE and BIND PLAN commands
  • Supports the [NOPLAN], [NODIALECT] and [MAINFRAME] statement prefixes
  • When used with the [NODIALECT] statement prefix, conversion and qualification are disabled
MIXED
  • Performs no DB2 syntax conversion or table and view qualifications
  • Qualifications can be enabled for individual statements using the [MAINFRAME] statement prefix
NONE
  • Equivalent to not specifying DIALECT
  • Performs no DB2 syntax conversions or table and view qualifications
  • Supports only the [NOPLAN] statement prefix
overrides
SQL compiler directives, set to values other than their default values set by DIALECT, each separated by a space. The modified SQL compiler directives specified override the directives set as defaults by DIALECT.

Properties:

Default: DIALECT=NONE

Dependencies:

Requires that DBMAN be set to ODBC.

When set to MAINFRAME, DIALECT sets the following SQL compiler directive options:

  • CHECK
  • CHECKCALLPARAMS
  • CHECKSINGLETON
  • CHECKUPDCURSOR
  • DATE=ISO
  • DESCRIBEDTCHAR
  • DESCRIBEVARCHAR49
  • DETECTDATE=CLIENT
  • MARS
  • STRICTPARSE
  • TIME=ISO
When set to MIXED, DIALECT sets the following SQL compiler directive options:
  • CHECK
  • CHECKSINGLETON
  • CHECKUPDCURSOR
  • DATE=ISO
  • DESCRIBEDTCHAR
  • DESCRIBEVARCHAR49
  • DETECTDATE=CLIENT
  • MARS
  • TIME=ISO
When set to MAINFRAM or MIXED, DIALECT sets the OpenESQL preprocessor to skip over the following EXEC SQL statements, generating a compile-time warning for each instead:
  • SET CURRENT APPLICATION ENCODING SCHEME
  • SET CURRENT DEGREE
  • SET CURRENT [LOCALE] LC_CTYPE
  • SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION
  • SET CURRENT OPTIMIZATION HINT
  • SET CURRENT PRECISION
  • SET CURRENT REFRESH AGE
  • SET CURRENT RULES
  • SET CURRENT ENCRYPTION PASSWORD

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Advantages:

  • You do not need to convert DB2 statements to T-SQL.
  • You can change the default schema when a program is bound, or in some cases, change the default schema at compile time using the QUALIFIER SQL compiler directive option.

Comments:

Both DIALECT=MAINFRAME and DIALECT=MIXED accept both [NODIALECT] and [MAINFRAME] statement prefixes. Using these in the appropriate combinations enables you to effectively switch between the two DIALECT settings on the statement level in a single application. However, you must remove the [NODIALECT] and [MAINFRAME] prefixes from the code compiling with DIALECT=NONE.

You can override the CHECK directive by specifying NOCHECK, or by setting the DB directive to identify your database connection. If the connection you specify does not use Windows authentication, then you must also set the PASS directive specifying a valid user ID and password for the connection.

In the context of HCOSS, CHECK verifies the following:
  • HCOSS-converted SQL syntax, to determine if the converted syntax is compatible with SQL Server. This provides early detection of incompatibilities between DB2 and SQL Server that have not been resolved by HCOSS.
  • converted database object names (tables, views, columns and functions) are valid in SQL Server.

To fully enable compile-time checking of converted SQL statements using SQL Server, set the DB, PASS and QUALIFIER directives along with DIALECT=MAINFRAME or DIALECT=MIXED.

When DIALECT=MAINFRAME and more rows are returned from the database than the statement in the application is able to accept, then HCOSS returns:
SQLCODE = -811 SQLSTATE = 21000 SQLWARN4 = W

Example:

SQL(DIALECT=MAINFRAME NOCHECK NODETECTDATE)
Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
HCO for SQL Server Compiler Directive Options for PL/I
Building Applications
Application Progression from DB2 to SQL Server
Scope - HCOSS SQL Compiler Directive Options
HCOSS Datetime Data Type Handling
Related reference
DB2 to SQL Server Conversion
SQL Statement Prefixes for DIALECT Directive
Default Data Type Mappings
Default SQLCODE Mappings
Default Function Mappings
Default Special Register Mappings
DBRMLIB
CHECKCALLPARAMS
STRICTPARSE
DATE
TIME
QUALIFIER
SPCALLLOCAL
CHECKSINGLETON
CHECK
CHECKDUPCURSOR
DESCRIBEDTCHAR
DESCRIBEVARCHAR49
DETECTDATE
MARS
DATE
TIME


MEMBER

Specifies a non-default name for the DBRM.
Restriction: This topic applies to Windows environments only.

Syntax, Format 1:

MEMBER=mem-name

Syntax, Format 2:

NOMEMBER

Parameters:

mem-name
The name of a DBRM. A DBRM name can be up to eight bytes in length, starts with a character, and is made up of a combination of alphabetic characters, digits, or the following special characters: @, #, $, -

Properties:

Default: MEMBER=prog-name

Where prog-name is the COBOL program name.

Dependencies:

Requires that DBMAN is set to ODBC.

Requires that the DBRMLIB HCOSS directive also be set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Building Applications
Scope - HCOSS SQL Compiler Directive Options
Related reference
DBRMLIB
VERSION


OPTION (deprecated)

Enables non-default optional behavior.
Restriction: This topic applies to Windows environments only.
Note: OPTION is deprecated, and supported for backward compatibility only. We recommend that you use equivalent HCOSS SQL compiler directive options instead.

Syntax:

OPTION={CHECKCALLPARAMS | SQLCLRTRANS}...

Parameters:

CHECKCALLPARAMS
Evaluates the parameters on a stored procedure call to determine if they are input or output. Automatically set by DIALECT=MAINFRAME.
SQLCLRTRANS
Emulates mainframe behavior by substituting SQL Server savepoint operations for COMMIT and ROLLBACK when building both client applications and stored procedures. Uncommited work is rolled back when a stored procedure returns to the calling application unless the stored procedure was built with SPCOMMITONRETURN. Database locks are not released until the calling application performs a COMMIT or a ROLLBACK.
Note: If the client application is written in a language other than COBOL or PL/I, then it should also execute the SQL Server statement save transaction MF__SAVEPOINT at the start of every transaction (i.e., after every COMMIT or ROLLBACK statement) and when turning AUTOCOMMIT mode off.

Properties:

Default: None

Dependencies:

DIALECT=MAINFRAME automatically sets CHECKCALLPARAMS.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Comment:

Separate each instance of OPTION with a space.

Example:

SQL(OPTION=CHECKCALLPARAMS)
Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Scope - HCOSS SQL Compiler Directive Options
Related reference
CHECKCALLPARAMS


PROMOTE

Saves generated DBRMs to the shared HCOSS DBRM library.
Restriction: This topic applies to Windows environments only.

Syntax

[NO]PROMOTE

Properties:

Default: NOPROMOTE

Dependencies:

Requires that the DBRMLIB HCOSS directive also be set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Comments:

When set to NOPROMOTE (default), DBRMs are saved under the DBRMLIB subdirectory to the path specified in the Local HCOSS Directory HCOSS option.

When set to PROMOTE:
  • DBRMs are saved under the DBRMLIB subdirectory to the path specified in the Shared HCOSS Directory HCOSS option
  • If a DBRM with the same name as a newly generated DBRM exists in the local HCOSS directories, the local DBRM is deleted automatically
Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Managing DBRMs
Shared DBRMs and multi-user environments
Local DBRMs
Scope - HCOSS SQL Compiler Directive Options
Related reference
DBRMLIB


QUALIFIER

Qualifies unqualified table and view names.
Note: This topic applies to Windows environments only.

Syntax:

QUALIFIER=schema-name

Parameters:

schema-name
The name of the schema used to qualify unqualified table or view references in embedded SQL.

Dependencies:

Requires one of the following:
  • The DIALECT directive option is set to MAINFRAME
  • The DIALECT directive option is set to MIXED, and each targeted SQL statement includes the [MAINFRAME] statement prefix

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Comments:

When CHECK is specified, HCOSS qualifies unqualified table and view references before sending statements to SQL Server for checking.

When ACCESS and/or BIND is specified, HCOSS qualifies unqualified table and view references in generated stored procedures.

When DBRMLIB is specified, HCOSS leaves unqualified table and view references unqualified in the DBRM. You can qualify them by specifying a qualifier when executing BIND PACKAGE or BIND PLAN commands. With DBRMLIB you need only specify QUALIFIER if it is required to assist CHECK.

When none of DBRMLIB, ACCESS, and BIND are specified, HCOSS qualifies table and view references in generated code.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Building Applications
Application Progression from DB2 to SQL Server
Scope - HCOSS SQL Compiler Directive Options
Related reference
SQL Statement Prefixes for DIALECT Directive
DBRMLIB
DIALECT
BIND
Bind Script Commands


SPCALLLOCAL

For native HCOSS applications, transforms an SQL call to a SQL Server stored procedure (i.e., an EXEC SQL CALL statement) into a standard COBOL call to a local COBOL subroutine.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]SPCALLLOCAL

Properties:

Default: NOSPCALLLOCAL

Dependencies:

Must be used with DIALECT=MAINFRAME and DBMAN=ODBC.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Comments:

Some applications perform better when you replace SQL Server calls to stored procedures with local COBOL subroutines. This can be applicable, for example, to HCOSS applications that call a given stored procedure multiple times.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Scope - HCOSS SQL Compiler Directive Options
Related reference
DIALECT
CHECKSP


STRICTPARSE

Provides enhanced diagnostics for SQL statements not recognized by the HCOSS DB2 parser.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]STRICTPARSE

Properties:

Default: STRICTPARSE

Dependencies:

Must be used with DIALECT=MAINFRAME.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Scope - HCOSS SQL Compiler Directive Options
Related reference
DIALECT


TIME

Specifies an explicit time format to use when time values are returned from SQL Server time columns in PIC X character output host variables.
Restriction: This topic applies to Windows environments only.

When used in addition to DETECTDATE, specifies the explicit time format to recognize in character input host variables.

Note: This topic documents TIME as used as an HCOSS SQL compiler directive option and therefore assumes that you have set DIALECT=MAINFRAME. For information on using TIME as a generic SQL compiler directive option, see TIME under SQL Compiler Directive Options. For information on the DIALECT HCOSS SQL compiler directive option, see DIALECT.

Syntax:

TIME={ODBC | ISO | USA | EUR | JIS}

Parameters:

ODBC
hh:mm:ss (SQL Server default format)
ISO
hh.mm.ss (mainframe default format)
USA
hh:mm{AM|PM}
EUR
hh.mm.ss
JIS
hh:mm:ss

Properties:

Default: ISO (mainframe default format)

Dependencies:

For input host parameters, requires that the DETECTDATE HCOSS SQL compiler directive option also be set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Comments:

TIME changes the display format of output host variables as specified.

Note: If you do not specify an alternative format using TIME, HCOSS returns your SQL Server time columns using mainframe ISO format in your output character host variables by default, as specified in the Properties section of this topic.

When you specify both TIME and DETECTDATE, HCOSS uses TIME to 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 - HCOSS
Related concepts
HCO for SQL Server Compiler Directive Options for PL/I
Building Applications
Scope - HCOSS SQL Compiler Directive Options
HCOSS Datetime Data Type Handling
Related reference
DETECTDATE
DIALECT


VERSION

Specifies a version for a DBRM.
Restriction: This topic applies to Windows environments only.

Syntax:

VERSION=version

Parameters:

version
The version of the DBRM. This can be up to 64 bytes in length and must consist of a letter followed by a sequence of zero or more letters, digits, or underscore characters.

Dependencies:

Requires that DBMAN is set to ODBC.

Requires that the DBRMLIB HCOSS directive also be set.

Scope:

Used at compile time: | Yes
Behavior at run time: | Source file

See Scope - HCOSS SQL Compiler Directive Options for more information.

Parent topic: SQL Compiler Directive Options - HCOSS
Related concepts
Building Applications
Scope - HCOSS SQL Compiler Directive Options
Related reference
MEMBER
DBRMLIB


DBMAN Directive Settings - HCOSS

Restriction: This topic applies to Windows environments only.

All SQL compiler directive options for HCOSS are valid with DBMAN=ODBC.

Parent topic: Reference
Related reference
DBMAN
SQL Compiler Directive Options - HCOSS


Required DB2 Catalog Tables

Restriction: This topic applies to Windows environments only.

The login credentials used to connect to the mainframe DB2 database must grant read access to the following DB2 system catalog tables:

Note: In addition to these DB2 Catalog table permissions, the Microsoft OLE DB provider must be properly configured with mainframe DB2. Please see DB2 Database Migration Process for additional information.
Object Type | DB2 System Catalog Table
tables, columns | SYSTABLES, SYSCOLUMNS, SYSSEQUENCES
indexes | SYSINDEXES, SYSKEYS
constraints (relational, check, key) | SYSCHECKS, SYSCHECKDEP, SYSCHECKS2, SYSCONSTDEP, SYSTABCONST, SYSKEYCOLUSE, SYSRELS, SYSFOREIGNKEYS
views | SYSVIEWS, SYSVIEWDEPENDENCY
Parent topic: Reference
Related concepts
Extract Schema Tool
DB2 Database Migration Process
Related tasks
To create a DB2 connection
To extract DB2 schema objects
To modify a schema extract file


DB2 to SQL Server Conversion Reference

  • Date and Time Data Types
    The default formats for DB2 and SQL Server date and time specifications.
  • Default Data Type Mappings
    The default mappings HCOSS uses to convert DB2 data types into SQL Server data types.
  • Default Function Mappings
    The default mappings HCOSS uses to convert DB2 aggregate and scalar functions to SQL Server equivalents.
  • Default Special Register Mappings
    The default mappings HCOSS uses to convert DB2 special registers to SQL Server equivalents.
  • Default SQLCODE Mappings
    The default mappings HCOSS uses to convert DB2 SQLCODEs into SQL Server SQLCODEs.
  • DSNTIAR and DSNTIAC
    Converts SQL return codes to character-string messages.
Parent topic: Reference
Related concepts
HCOSS Conversion Rules


Date and Time Data Types

The default formats for DB2 and SQL Server date and time specifications.

These topics are included as a reference to assist you in determining conversion specifications for date and time data types going from DB2 to SQL Server.

  • Mainframe Date and Time Data Types
  • SQL Server Date and Time Data Types
Parent topic: DB2 to SQL Server Conversion Reference
Related reference
DB2 to SQL Server Conversion


Mainframe Date and Time Data Types

Restriction: This topic applies to Windows environments only.

The mainframe date and time data types are date, time and timestamp. Date has a range from 0001-01-01 to 9999-12-31. Time has a range from 00:00:00 to 23:59:59. The special value 24:00:00 is equivalent to 24:00:00. The range of datetime is 1-1-1 00:00:00.000000 to 9999-12-31 23:59:59.999999.

Character string representation of date values

Format Name | Abbreviation | Date Format | Example
International Standards Organization | ISO | yyyy-mm-dd | 1987-10-12
IBM USA Standard | USA | mm/dd/yyyy | 10/12/1987
IBM European Standard | EUR | dd.mm.yyyy | 12.10.1987
Japanese industrial standard Christian era | JES | yyyy-mm-dd | 1987-10-12
Installation-defined | LOCAL |  |

Character string representation of TIME values

Format Name | Abbreviation | Date Format | Example
International Standards Organization | ISO | hh.mm.ss | 13.30.05
IBM USA Standard | USA | hh:mm AM or PM | 1:30 PM
IBM European Standard | EUR | hh.mm.ss | 13.30.05
Japanese industrial standard Christian era | JES | hh:mm:ss | 13:30:05
Installation-defined | LOCAL |  |

Character string representation of timestamp values

The default format is yyyy-mm-dd-hh-hh.mm.ss.nnnnnn.

The ODBC/JDBC format is also accepted; this is yyyy-mm-dd hh:mm:ss.nnnnnn.

Parent topic: Date and Time Data Types


SQL Server Date and Time Data Types

Restriction: This topic applies to Windows environments only.
SQL Server legacy data types are:
  • datetime
  • smalldatetime
However, these are not recommended for mainframe application migration. To facilitate migration, SQL Server 2008 added these data types:
Data Type | Range | Fractional Second Digits
date | 0001-01-01 to 9999-12-31 |
time | 00:00:00.0000000 to 23:59:59.9999999 | 0 to 7
datetime2 | 0001-01-01 00:00:00.0000000 to 9999-12-31 23:59:59.9999999 | 0 to 7
datetimeoffset |  |

SQL Server provides considerable flexibility in reading date and time data as character strings, only a subset that is most directly relevant for migrations is presented here.

Default output format

SQL Server outputs date, time and datetime values in the following formats: yyyy-mm-dd, hh:m:ss.nnnnnnn (n is dependent on the column definition) and yyyy-mm-dd hh:mm:ss.nnnnnnn (n is dependent on the column definition).

Character string representation of date values

Format Type | Date Format | Example
ANSI/ISO | yyyy-mm-dd | 1987-10-12
Alphabetic | The month is specified as a three character abbreviation or the full month name. | Apr 15 1996 15 Apr 1996 1996 Apr 15
Numeric | The month is specified as a number and the separator can be slash, hyphen or period. The order of day, month year parts can be changed by a TSQL SET DATEFORMAT or SET LANGUAGE statements. The initial order is determined from the default language for the login. The default format for us_english is mdy. The settings are stored in the table sys.syslanguages. | 15/04/1996 04.15.1996 1996-4-15

Character string representation of time values

SQL Server accepts time values in the following formats: 14:30, 14:30:20, 14:30:20:145943, 2 PM, 2:30 PM, 2:30:20 PM 2:30:20.145943 PM.

Character string representation of datetime values

SQL Server accepts datetime values in ISO 8601 and ANSI formats, which are: yyyy-mm-ddThh:mm:ss.nnnnnn and yyyy-mm-dd hh:mm:ss.nnnnnn, respectively.

Parent topic: Date and Time Data Types


Default Data Type Mappings

The default mappings HCOSS uses to convert DB2 data types into SQL Server data types.
Restriction: This topic applies to Windows environments only.
DB2 Data Type | Encoding | Data Storage | SQL Server Data Type
BIGINT | All | None | BIGINT
BINARY | All | None | BINARY
BLOB | All | None | VARBINARY(MAX)
CHAR | All | For bit data | BINARY
CHAR | ASCII and EBCDIC | None | CHAR
CHAR | UNICODE | None | NCHAR
CLOB | ASCII | None | NVARCHAR(MAX)
CLOB | ASCII | For bit data | NVARCHAR(MAX)
CLOB | EBCDIC | For bit data | NVARCHAR(MAX)
CLOB | UNICODE | None | NVARCHAR(MAX)
CLOB | UNICODE | For bit data | NVARCHAR(MAX)
CLOB | EBCDIC | None | NVARCHAR(MAX)
DATALINK | All | None | VARCHAR(2083)
DATE | All | None | DATE
DBCLOB | All | None | NVARCHAR(MAX)
DECFLOAT | All | None | FLOAT(53)
DECIMAL | All | None | DECIMAL
DOUBLE | All | None | DOUBLE PRECISION
FLOAT | All | None | FLOAT
GRAPHIC | All | None | NCHAR
INT | All | None | INT
INTEGER | All | None | INTEGER
LONG VARCHAR | All | For bit data | VARCHAR(MAX)
LONG VARCHAR | All | None | VARCHAR(MAX)
LONG VARGRAPHIC | All | None | NVARCHAR(MAX)
LONGVARBIN | All | None | VARBINARY(MAX)
NUMERIC | All | None | NUMERIC
REAL | All | None | REAL
ROWID | All | None | BINARY(40)
SMALLINT | All | None | SMALLINT
TIME | All | None | TIME(0)
TIMESTMP | All | None | DATETIME2(6)
VARBIN | All | None | VARBINARY
VARCHAR | All | For bit data | BINARY
VARCHAR | All | None | VARCHAR
VARGRAPHIC | All | None | NVARCHAR
XML | All | None | XML
Parent topic: DB2 to SQL Server Conversion Reference
Related concepts
Customizing Data Type Mappings
Related tasks
To customize data type mappings
Related reference
DB2 to SQL Server Conversion
DIALECT


Default Function Mappings

The default mappings HCOSS uses to convert DB2 aggregate and scalar functions to SQL Server equivalents.
Restriction: This topic applies to Windows environments only.
Note: In addition to these default mappings, you can also define customized mappings. See Customizing Functions and Special Registers for more information.

z/OS DB2 Aggregate Functions in HCOSS

All of the following aggregate functions are fully supported:

  • AVG
  • COUNT
  • COUNT_BIG
  • MAX
  • MIN
  • STDDEV or STDDEV_SAMP
  • SUM

z/OS DB2 Scalar Functions in HCOSS

HCOSS provides either full or partial support for the following z/OS DB2 scalar functions.

DB2 Function | Support | Implementation1 | Not supported
ABS | Full |  |
ACOS | Full |  |
ADD_MONTHS | Full | ESQL runtime |
ASCII | Full |  |
ASCII_CHR | Full | SQL Name Mapping |
ASIN | Full |  |
ATAN | Full |  |
BIGINT | Full | ESQL runtime |
BINARY | Full | ESQL runtime |
BLOB | Full | ESQL runtime |
CEILING | Full |  |
CHAR | Partial | ESQL runtime | The third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
CLOB | Partial | ESQL runtime | The third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
COALESCE | Full | ESQL runtime |
COMPARE_DECFLOAT | Full |  |
CONCAT | Full | SQL Name Mapping using dbo.CONCAT |
CONCAT_BINARY | Full | SQL Name Mapping using dbo.CONCAT_BINARY |
COS | Full |  |
DATE | Full | ESQL runtime |
DAY | Full | ESQL runtime |
DAYOFMONTH | Full | ESQL runtime |
DAYOFWEEK | Full | ESQL runtime |
DAYOFWEEK_ISO | Full | ESQL runtime |
DAYOFYEAR | Full | ESQL runtime |
DAYS | Full | ESQL runtime |
DBCLOB | Partial | ESQL runtime | The third parameter – CODEUNITS16, or CODEUNITS32
DECFLOAT2 | Partial | ESQL runtime | The second parameter – 16 or 34
DECIMAL or DEC | Partial | ESQL runtime | The optional fourth parameter – decimal character
DEGREES | Full |  |
DIFFERENCE | Full |  |
DIGITS | Full | SQL Name Mapping using dbo.digits |
DOUBLE_PRECISION or DOUBLE | Full | ESQL runtime |
EXP | Full |  |
EXTRACT | Full | ESQL runtime |
FLOAT | Full | ESQL runtime |
FLOOR | Full |  |
GRAPHIC | Partial | ESQL runtime | The third parameter – CODEUNITS16, or CODEUNITS32
HEX | Full | SQL Name Mapping using dbo.hex |
HOUR | Full | ESQL runtime |
IDENTITY_VAL_LOCAL | Full | ESQL runtime |
IFNULL | Full | SQL Name Mapping using COALESCE |
INTEGER or INT | Full | ESQL runtime |
LAST_DAY | Full | SQL Name Mapping using dbo.lastday |
JULIAN_DAY | Full | SQL Name Mapping using dbo.julianday |
LCASE | Full | SQL Name Mapping using LOWER |
LEFT | Partial | ESQL runtime | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
LENGTH | Full | SQL Name Mapping using DATALENGTH |
LN | Full | SQL Name Mapping using LOG |
LOCATE | Partial | ESQL runtime | The optional fourth parameter – CODEUNITS16, or CODEUNITS32
LOG10 | Full |  |
LOWER | Partial |  | The optional second and third parameters are not supported by SQL Server
LPAD | Full | SQL Name Mapping using dbo.LPAD |
LTRIM | Partial |  | The optional second parameter is not supported by SQL Server
MICROSECOND | Full | ESQL runtime |
MIDNIGHT_SECONDS | Full | ESQL runtime |
MINUTE | Full | ESQL runtime |
MOD | Full | ESQL runtime |
MONTH | Full | ESQL runtime |
NEXT_DAY | Full | SQL Name Mapping using dbo.nextday |
POSSTR | Full |  |
POWER | Full | ESQL runtime |
QUARTER | Full | ESQL runtime |
RADIANS | Full |  |
RAND | Full |  |
REAL | Full | ESQL runtime |
REPEAT | Full | SQL Name Mapping using REPLICATE |
REPLACE | Full |  |
RIGHT | Partial | ESQL runtime | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
ROUND | Partial |  | ROUND function in SQL Server does not automatically expand precision for the result if arithmetic overflow occurs. For example, SQL Server treats ROUND(873.726,-3) as error whereas DB2 yields 1000.000
RPAD | Full | SQL Name Mapping using dbo.RPAD |
RTRIM | Partial |  | The optional second parameter is not supported by SQL Server
SECOND | Partial | ESQL runtime | The optional second parameter
SIGN | Full |  |
SIN | Full |  |
SMALLINT | Full | ESQL runtime |
SOUNDEX | Full |  |
SPACE | Full |  |
SQRT | Full |  |
STRIP | Full | SQL Name Mapping using dbo.strip |
SUBSTR | Full | SQL Name Mapping using SUBSTRING |
SUBSTRING | Full | ESQL runtime | The optional fourth parameter – CODEUNITS16, CODEUNITS32, or OCTETS
TAN | Full |  |
TIME | Full | ESQL runtime |
TIMESTAMP | Full | ESQL runtime |
TIMESTAMP_ISO | Full | ESQL runtime |
TIMESTAMPDIFF | Full | ESQL runtime |
TRANSLATE | Full | SQL Name Mapping using dbo.translate |
TRUNCATE or TRUNC | Full | ESQL runtime |
UCASE | Partial | SQL Name Mapping using UPPER | The optional second and third parameters
UNICODE | Full |  |
UPPER | Partial |  | The optional second and third parameters
VALUE | Full | SQL Name Mapping using COALESCE |
VARBINARY | Full | ESQL runtime |
VARCHAR | Partial |  | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
VARGRAPHIC | Partial |  | The optional third parameter – CODEUNITS16, CODEUNITS32, or OCTETS
WEEK | Full | ESQL runtime |
WEEK_ISO | Full | ESQL runtime |
XMLQUERY | Full | ESQL runtime |
YEAR | Full | ESQL runtime |
1 When blank, SQL Server and z/OS provide same functionality. 2 The value is converted to FLOAT.
Parent topic: DB2 to SQL Server Conversion Reference
Related concepts
Customizing Functions and Special Registers
Customizing SQL Identifiers
Related tasks
To customize SQL name mappings
To customize SQL name mappings
Related reference
DB2 to SQL Server Conversion
DIALECT


Default Special Register Mappings

The default mappings HCOSS uses to convert DB2 special registers to SQL Server equivalents.
Restriction: This topic applies to Windows environments only.
Note: In addition to these default mappings, you can also define customized mappings. See Customizing Functions and Special Registers for more information.

The following table shows supported DB2 special registers and their HCOSS default SQL Server equivalents.

DB2 Special Register | SQL Server Equivalent
CURRENT CLIENT_APPLNAME | APP_NAME()
CURRENT CLIENT_USERID | SYSTEM_USER
CURRENT CLIENT_WRKSTNNAME | HOST_NAME()
CURRENT DATE or CURRENT_DATE | CONVERT(date,SYSDATETIME())
CURRENT TIME or CURRENT_TIME | CONVERT(time(0), SYSDATETIME())
CURRENT TIMESTAMP or CURRENT_TIMESTAMP | CONVERT(datetime2(6), SYSDATETIME())
CURRENT LC_CTYPE or CURRENT_LC_TYPE | CONVERT(char(50), SERVERPROPERTY('collation'))
CURRENT LOCALE LC_CTYPE | CONVERT(char(50), SERVERPROPERTY('collation'))
CURRENT SCHEMA or CURRENT_SCHEMA | CONVERT(varchar(128), SCHEMA_NAME())
CURRENT SERVER | CONVERT(char(16), SERVERPROPERTY('servername'))
CURRENT SQLID | USER
SESSION_USER | USER
Parent topic: DB2 to SQL Server Conversion Reference
Related concepts
Customizing Functions and Special Registers
Customizing SQL Identifiers
Related tasks
To customize SQL name mappings
To customize SQL name mappings
Related reference
DB2 to SQL Server Conversion
DIALECT


Default SQLCODE Mappings

The default mappings HCOSS uses to convert DB2 SQLCODEs into SQL Server SQLCODEs.
Restriction: This topic applies to Windows environments only.
DB2 SQLCODE Value | SQL Server SQLCODE Value | SQLSTATE Value
-2601 | -803 | 23505
-19519 | -501 | 24501
-19516 | -502 | 24502
-2714 | -601 | 42710
-207 | -204 | 42704
-208 | -204 | 42704
Parent topic: DB2 to SQL Server Conversion Reference
Related reference
DB2 to SQL Server Conversion
DIALECT


Bind Script Commands

Restriction: This topic applies to Windows environments only.
The following mainframe DSN commands are supported in bind script files and as input to JCL:
DSN Command | Supported Parameters
BIND PACKAGE | ACTION, MEMBER, LIBRARY, PKLIST, QUALIFIER, FLAG1
BIND PLAN | ACTION, MEMBER, LIBRARY, PKLIST, QUALIFIER, FLAG1
FREE PACKAGE | FLAG
FREE PLAN | FLAG
REBIND PACKAGE2 | QUALIFIER, FLAG, DYNAMICRULES1
REBIND PLAN 2 | PKLIST, QUALIFIER, FLAG, DYNAMICRULES 1
END

1 HCOSS ignores any other parameters present on the command line and issues a warning for each ignored parameter.

2 You can specify this in a bind script file you create manually; however, you cannot generate this command using the Manage Packages and Plans tool.

Note: For complete information on the use of these DSN commands including syntax, see the IBM DB2 documentation for DSN commands and subcommands available on the IBM Web site.
Parent topic: Reference
Related concepts
DSN Bind Utility
Binding Applications
Related tasks
To bind from the command line
To bind as a post-build event
To manually code a bind script file
Related reference
BIND
DSN command
QUALIFIER


HCOSS Messages

Restriction: This topic applies to Windows environments only.

Lists the error messages and other non-error messages that are produced by HCOSS tools.

  • Compare Data Tool Error Messages
  • Define Lists Tool Error Messages
  • Extract Schema Tool Error Messages
  • Generate DDL Tool Error Messages
  • Manage Connections Tool Error Messages
  • Transfer Data Tool Error Messages
  • Build error messages
Parent topic: Reference
Related information
Data Related


Compare Data Tool Error Messages

Restriction: This topic applies to Windows environments only.

This topic describes the error messages that are related to the Compare Data tool.

Error Message | Description or Cause | Resolution
A shared task cannot have a local transfer list | A shared task must associate a shared transfer list. | Make sure the shared radio button is checked for the transfer list.
Build Query failed | Build customized query by OpenESQL failed. | Make sure the source database connection is still open.
Command file is invalid or was not found | The file does not exist in the specified folder; or the file contains syntax errors. | Make sure the file exists and has correct syntax in its content.
Compare list file is empty | Compare list file has no meaningful content. | Add the desired content to the file.
Connection failed | Connection to either source database or destination database failed. | Make sure the user ID and password are correct.
Data comparison terminated for this table, error count exceeds mismatch limit | Error count exceeds the mismatch limit. | Check the mismatch errors to figure out which table causes the failure.
Data comparison test FAILED! | Data comparison test failed due to unmatched rows or columns. | Make sure the data in both source table and destination table are of the same set.
Data for following column does not match | The values of data in the two databases do not match. | Check if the data tables contain the same set of data in terms of rows, columns and ordering
Error in writing to file | Error in writing a task to XML file. | Check task name or path for illegal characters.
Execution Error | Execution of compare data failed due to connection failure. | Check database connections.
File Access Violation | Either READ or WRITE permission is not granted to the user. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user file access.
Following required parameter is missing | A required command line parameter is missing. | Provide the required parameter.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the parameter.
Invalid command line syntax | Some parameter names are incorrect. | Use the correct parameter names.
Invalid Data Source Name | The name of the data source or data destination is empty. | Add the name of the data source or data destination to the command line argument.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
Invalid target object list | The XML target list file has syntax errors. | Check the target list file content or try regenerating the target list.
No task name is set | No task name is set on GUI. | Select the desired task name on GUI.
Number of result set columns do not match | The number of table columns in the destination database does not match the corresponding one in the source database. | Check the DDL generation script.
Number of result set rows do not match | The number of rows in the destination table does not match that in the source table. | Rerun the Transfer Data tool.
Query Failed = … | Execution of the query failed. | Check query syntax, database connection, and database access permission.
The destination DSN is not found | The destination DSN is not set or it is not defined. | Specify an existing connection or create one if the connection you want to use does not exist.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
The source DSN is not found | The source DSN is not set, or it is not defined. | Set the source DSN or create one if it does not exist.
The transfer list is not found in the directory | The transfer task file does not exist in the specified path. | Make sure the specified file exists in the path; or the file name is correct.
Unable to read list file | The transfer list file is corrupted. | Check the file content for syntax errors.
Parent topic: HCOSS Messages
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Log Files


Define Lists Tool Error Messages

Restriction: This topic applies to Windows environments only.

This topic describes the error messages that are related to the Define Lists tool.

Error Message | Description or Cause | Resolution
An unexpected error has occurred. Please report the following error to Micro Focus Support: | A generic error flag followed by a specific message. | See the following specific message for information.
Invalid XML schema input file | Errors in XML schema of the schema extract file. | Check the schema extract file (.hcodbs).
No schema files found. You must have at least one schema file to create object lists | No schema files in the specified directory. | Create schema files in the directory.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the file.
Unable to delete list file: | Unable to delete the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user DELETE permission on the file.
Unable to read list file: | Unable to read the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Unable to write list file: | Unable to write the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the file.
Parent topic: HCOSS Messages
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list
Related reference
MFObjectList command
Define Lists Tool Log Files


Extract Schema Tool Error Messages

Restriction: This topic applies to Windows environments only.

This topic describes the error messages that are specific to the Extract Schema tool.

Error Message | Description or Cause | Resolution
Connection no longer open - processing terminated. Please re-select Schemas and try again | Connection time out. | Re-select the schemas (as to reconnect).
Could not open database connection | Either the database is not available or the connection parameters have errors. | Check the database availability, permission, network connectivity, and parameters in the connection string.
Error inserting in SysConsDep | Error in accessing table SYSIBM. SysConsDep in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysChkConstraints | Error in accessing table SYSIBM.SYSCHECKS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysChkDepConstraints | Error in accessing table SYSIBM.SYSCHECKDEP in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysColumns | Error in accessing table SYSIBM. SysColumns in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysKeyColConstraints | Error in accessing table SYSIBM.SYSKEYCOLUSE in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysIndexes | Error in accessing table SYSIBM. SysIndexes in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysIndexCols | Error in accessing table SYSIBM.SYSKEYS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysRelConstraints | Error in accessing table SYSIBM.SYSRELS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysRelFkConstraints | Error in accessing table SYSIBM.SYSFOREIGNKEYS in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysTables | Error in accessing table SYSIBM. SysTables in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysTblConstraints | Error in accessing table SYSIBM.SYSTABCONST in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysViews | Error in accessing table SYSIBM. SysViews in DB2. | See the IBM SQL Message reference for the SQL error reported.
Error inserting in SysViewDep | Error in accessing table SYSIBM. SysViewDep in DB2. | See the IBM SQL Message reference for the SQL error reported.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the required parameter.
Invalid Data Source Name | The name of the data source or data destination is empty. | Add the name of the data source or data destination to the command line argument.
Parent topic: HCOSS Messages
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schema objects
To modify a schema extract file
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Log Files


Generate DDL Tool Error Messages

Restriction: This topic applies to Windows environments only.

This topic describes the error messages that are related to the Generate DDL tool.

Error Message | Description or Cause | Resolution
An unexpected error has occurred. Please report the following error to Micro Focus Support: | A generic error flag followed by a specific message. | See the following specific message for information.
Commit exception type: | Error in commit of DDL generation. | See the following message for details.
Connection failed | The target database connection failed. | Make sure the user ID and password correct.
Encountered problem reading source database schema | Error in reading the schema file. | See the preceding message for details.
Encountered problem during file/path checks | Error in the specified file name or path. | Check the specified file name and path.
Encountered problem reading XML mappings | Error in reading the mapping file. | Check the specified file name and path.
Encountered problem writing DDL command file | Error in writing the DDL file. | Check the file folder existence and WRITE permission.
Following required parameter is missing | A required parameter is not provided | Provide the specified parameter value
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the parameter.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
Invalid DDL output directory | Error in creating the DDL file directory. | Check the file directory existence and WRITE permission.
Invalid XML mapping input file | Error in reading the DDL file. | Check the file existence and READ permission.
Invalid XML schema input file | Error in reading the schema file. | Check the file existence and READ permission.
No list files found. You must have at least one list file to create scripts. | The original list file has been deleted or renamed. | Recreate the list file or delete the current task.
Rollback exception type: | Error in rollback of DDL generation. | See the message for details.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
Unable to create DDL output file | Error in creating the DDL file. | Check the file directory existence and WRITE permission.
Unable to create export file: | Unable to create the specified export file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the directory.
Unable to delete export file: | Unable to delete the specified export file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user DELETE permission on the file.
Unable to delete task file: | Error in deleting the task file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user DELETE permission.
Unable to read list file: | Unable to read the specified list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Unable to read script file: | Unable to read the specified script file. | Check the file existence. Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Unable to return to previous task file | Unable to set the previous task. The previous file is either missing or renamed. | Recreate the task file.
Unable to write list file: | Unable to write the specified script file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission on the directory.
Parent topic: HCOSS Messages
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Log Files


Manage Connections Tool Error Messages

Restriction: This topic applies to Windows environments only.

This topic describes error messages that are specific to the Manage Connections tool.

Error Message | Description or Cause | Resolution
32-bit ADO.NET connection failed | The specified 32-bit ADO.NET connection failed. | Check the connection parameters.
32-bit ODBC connection failed | The specified 32-bit ODBC connection failed. | Check the connection parameters.
64-bit ADO.NET connection failed | The specified 64-bit ADO.NET connection failed. | Check the connection parameters.
64-bit ODBC connection failed | The specified 64-bit ODBC connection failed. | Check the connection parameters.
(A connection) already exists and will not be imported | A warning message. | It can be ignored.
(A connection) cannot be imported. | An existing connection cannot be imported due to unsupported provider type. | Redefine the connection using a supported provider type.
An existing connection was found and no action was taken. If you wish to add or update an existing connection, please specify the FORCE=TRUE parameter. | An existing connection cannot be overwritten. | The user may choose to set the parameter FORCE=TRUE to overwrite, or do nothing.
An unexpected error has occurred. Please report the following error to Micro Focus Support: |  |
Following required parameter is missing | A required parameter is not provided. | Provide the specified parameter value.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the required parameter.
Invalid connection mode | The connection mode parameter “MODE” has no value. | Assign a value to the parameter.
Invalid connection name | The connection name parameter “DSN” has no value. | Assign a value to the parameter.
Invalid connection provider | The connection provider parameter “PROVIDER” has no value. | Assign a value to the parameter.
Invalid connection provider type | The connection provider type parameter “PTYPE” has no value. | Assign a value to the parameter.
Invalid connection save ADO.NET password flag | The connection save ADO.NET password flag parameter “ADOSAVEP” has no value. | Assign a value to the parameter.
Invalid connection server type | The connection server type parameter “STYPE” has no value. | Assign a value to the parameter.
Invalid connection type | The connection type parameter “CTYPE” has no value. | Assign a value to the parameter.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
The connection name specified already exists. Please provide a unique connection name. | The new connection name conflicts with an existing one. | Use a different name for the new connection.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
Unable to list SQL Server instances | Unable to list SQL Server instances in the local area network. | Check the network connectivity.
Unable to write DSN tracking file | XML schema error. | Contact Micro Focus support.
Validation of command line parameters failed | Some of the command line parameters have syntax errors. | Correct the syntax errors by following the sample format provided in the command line usage documentation topic.
Parent topic: HCOSS Messages
Related concepts
Manage Connections Tool
Connection Types
Related tasks
To create a DB2 connection
To create a system or user SQL Server connection
To import a connection
To export a connection
To repair a connection
Related reference
Manage Connections Tool Log Files


Transfer Data Tool Error Messages

Restriction: This topic applies to Windows environments only.

This topic describes the error messages that are related to the Transfer Data tool.

Error Message | Description or Cause | Resolution
A shared task cannot have a local transfer list | A shared task must associate a shared transfer list. | Make sure the shared radio button is checked for the transfer list.
A wrong row is selected | A wrong row is selected when updating the customization. | Make sure the last changed row is selected/highlighted.
Connection failed | Source or destination connection failed. | Make sure the user ID and password correct.
Deletion result: Failure | The user does not have the permission of DELETE for the table or database. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user permission of DELETE.
(DSN’s provider) is not an OLE DB Provider | The underlying database provider is not of OLE DB type. | Recreate the DSN using the recommended Microsoft OLE DB provider.
Error in writing to file | Error in writing a task to XML file. | Check the task name and path for illegal characters.
File Access Violation | Either READ or WRITE permission is not granted to the user. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user file access.
Invalid command line parameter | The specified parameter value is empty or out of range. | Assign a proper value to the parameter.
Invalid Data Source Name | The name of the data source or data destination is empty. | Add the name of the data source or data destination to the command line argument.
Invalid number of arguments | The command line has no arguments. | Add the required arguments to the command line.
Invalid target object list | Syntax error. There is no “=” operator. | Add an “=” operator.
No query is selected for customization | An action button is clicked before a row of query is selected for customization. | Make sure the row is highlighted first.
No task name is set | No task name is set on GUI. | Select the desired task name on GUI.
SSIS package execution result: Failure | Data in the source database is not accessible. Data type mapping is incompatible. | Make sure the data accessible for SELECT statement. Check the version of SQL Server Native Client provider. It should be 10.x or above.
SSIS package validation result: Failure | Either the source or destination connection fails. | Check the connection(s).
Target table does not exist | The target table in the destination database has not been created. | Create the table in the destination database.
The destination DSN is not found | The destination DSN is not set or it is not defined. | Specify an existing connection or create one if the connection you want to use does not exist.
The process does not have the READ permission to the file | The process does not have READ permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission.
The process does not have the WRITE permission to the file | The process does not have WRITE permission to the specific file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user WRITE permission.
The source DSN is not found | The source DSN is not set, or it is not defined. | Set the source DSN or create one if it does not exist.
The transfer list is not found in the directory | The transfer task file does not exist in the specified path. | Make sure the specified file exists in the path; and the file name is correct.
There is no object list file in the location | No transfer list files in the specified “local” or “shared” folder. | Run through Define List tool again.
There is no table in the Data Transfer list | The data transfer task file contains no tables. | Add the desired tables to the task file.
Unable to read list file | Unable to read the transfer list file. | Depending on the security policy of the organization, the resolution can be either Run as Administrator or Grant the user READ permission on the file.
Validation of command line parameters failed | Some of the command line parameters have syntax errors. | Correct the syntax errors by following the required format.
Workflow Error | The workflow is not in correct order. | Make sure the workflow in correct order.
Parent topic: HCOSS Messages
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Log Files


Build error messages

Restriction: This topic applies to Windows environments only.
All build errors are a result of linking problems.
Error Message | Resolution
unresolved external symbol _MFHCOCD2@4 | In the Properties for your project, select Micro Focus > Build Configurations > Link > Additional Link Files and add the appropriate MFDSNTIAR.LIB file. This file resides in your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib or %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib64 directory, depending on whether you are building a 32-bit or 64-bit application.
unresolved external symbol _mfsqlsmf@20 | In the Properties for your project, select Micro Focus > Build Configurations > Link > Additional Link Files and add the appropriate MFSQLSMF.LIB file. This file resides in your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib or %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\lib64 directory, depending on whether you are building a 32-bit or 64-bit application. If the application does not run under Enterprise Server, you can compile the program with SQL(NOSMFTRACE) directive.
Parent topic: HCOSS Messages
Related concepts
Building Applications


Log Files

  • Manage Connections Tool Log Files
  • Extract Schema Tool Log Files
  • Define Lists Tool Log Files
  • Generate DDL Tool Log Files
  • Transfer Data Tool Log Files
  • Compare Data Tool Log Files
  • Manage Packages and Plans Tool Log Files
Parent topic: Reference


Manage Connections Tool Log Files

Restriction: This topic applies to Windows environments only.

Log File Generation

The Manage Connections Tool creates one log file per GUI session.

File Location

logFileDir\Connections

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

CONMAN-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Parameter validation
  • Connection checking
  • Add actions
  • Update actions
  • Delete actions
Parent topic: Log Files
Related concepts
Manage Connections Tool
Connection Types
Related tasks
To create a DB2 connection
To create a system or user SQL Server connection
To import a connection
To export a connection
To repair a connection
Related reference
Manage Connections Tool Error Messages


Extract Schema Tool Log Files

Restriction: This topic applies to Windows environments only.

Log File Generation

GUI Tool

The GUI version of the Extract Schema tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFExtractSchemaInfo Command

When running the Schema Extract tool from the command line, HCOSS generates a log file when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\Schemas

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

SCHEMCAP-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schema objects
To modify a schema extract file
Related reference
MFExtractSchemaInfo command
Extract Schema Tool Error Messages


Define Lists Tool Log Files

Restriction: This topic applies to Windows environments only.

Log File Generation

GUI Tool

The GUI version of the Define Lists tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFObjectList Command

When running the Define Lists tool from the command line, HCOSS generates log files when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\TargetLists

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

TLMAN-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list
Related reference
MFObjectList command
Define Lists Tool Error Messages


Generate DDL Tool Log Files

Restriction: This topic applies to Windows environments only.

Log File Generation

GUI Tool

The GUI version of the Generate DDL tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFDDLConverter Command

When running the Generate DDL tool from the command line, HCOSS generates log files when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\DDLTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

GUI Tool

SCHEMMIG-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Parameter validation
  • Processing information
  • Object totals

    In some cases, when HCOSS encounters certain behavioral differences between DB2 and SQL Server, the total number of objects processed can exceed the original count of DB2 objects. For example, DB2 v7 and v8 support a primary key with no primary index. However, all primary keys in SQL Server, when defined, automatically create an associated index. In that case, you could have an extra index object in the SQL Server DDL. The opposite is true as well.

    Note: XML indexes are not currently supported by the DDL Converter tool. XML indexes existing in the DB2 database are not created in the DDL, nor are columns that are part of a index and are also mapped to the SQL Server XML data type. This is true even if the originating DB2 index and column are not of XML type.
  • Conversion information

    Where DB2 and SQL Server database formats have differences, HCOSS logs suggestions at each stage of operation as to possible workarounds.

Parent topic: Log Files
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL
Related reference
MFDDLConverter command
Generate DDL Tool Error Messages


Transfer Data Tool Log Files

Restriction: This topic applies to Windows environments only.

Log File Generation

GUI Tool

The GUI version of the Transfer Data tool generates one HCOSS log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file. It also generates one SSIS log file for each table processed, regardless of the Type of logging to do setting.

MFDataTransferCtlr Command

When running the Transfer Data tool from the command line, HCOSS generates a transfer data log file when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option. It also generates one SSIS log file for each table processed, regardless of the TYPELOG setting.

File Locations

Transfer Data Log Files

logFileDir\DataTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

SSIS Log Files

genHCOSSFiles\DataTasks

where genHCOSSFiles is the value of either the Local HCOSS Directory or Shared HCOSS Directory HCOSS option, depending on whether your data task is local or shared.

File Name

Transfer Data Log File

DATTRANS-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

SSIS Log Files

[SQLServerSchemaName]_[TableName]_RunTimeLog.log

File Contents

Transfer Data Log File

The HCOSS log file contains messages generated during package execution, including:
  • Package validation
  • Execution
  • Progress
  • Errors
  • Warnings
  • Diagnostics

SSIS Log File

The SSIS log file contains progress and error messages generated during the building of a package.

Parent topic: Log Files
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task
Related reference
MFDataTransferCtlr command
Transfer Data Tool Error Messages


Compare Data Tool Log Files

Restriction: This topic applies to Windows environments only.

Log File Generation

GUI Tool

The GUI version of the Compare Data tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

MFTestConversion Command

When running the Compare Data tool from the command line, HCOSS generates a log file when you have set the TYPELOG directive to either FILE or BOTH, and when TYPELOG is not specified, defaults to the value of the Type of logging to do HCOSS option.

File Location

logFileDir\CompareTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

DATACOMP-year-month-day-generatedTimestamp.log

where generatedTimestamp is a six- to eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons
Related reference
MFTestConversion command
Compare Data Tool Error Messages


Manage Packages and Plans Tool Log Files

Restriction: This topic applies to Windows environments only.

Log File Generation

The Manage Packages and Plans tool generates one log file per GUI session when you have set the Type of logging to do HCOSS option to either Write log messages just to file or Write log messages to both console and file.

File Location

logFileDir\BindTasks

where logFileDir is the value of the Directory to write log files to HCOSS option.

File Name

BINDTASKS-year-month-day-generatedTimestamp.log

where generatedTimestamp is an eight-digit string representing the timestamp.

File Contents

  • Processing information
  • Warning messages
  • Error messages
Parent topic: Log Files


User Interface Reference

  • Manage Connections
  • Extract Schema
  • Assess Data Migration
  • Define Lists
  • Generate DDL
  • Transfer Data
  • Compare Data
  • Assess Application Migration
  • Manage Packages and Plans
  • Data Mappings tab
  • SQL Name tab
  • Customize SQLCode Mappings
  • Options
Parent topic: Reference


Manage Connections

  • Connection List tab
  • DB2 Connection tab
  • SQL Server Connection tab
  • Export tab
  • Import tab
  • Log Files tab
Parent topic: User Interface Reference


Connection List tab

Restriction: This topic applies to Windows environments only.
Connection List
A list of all available connections.
Name
The data source name you specified for the connection when you created it.
Type
The type of database connection, SQL Server or DB2.
Status
The last known status of the connection:
Checking | HCOSS is checking the status of the connection
OK | Able to connect
Needs Repair | Unable to make the connection using the supplied information
Unknown | Shows for newly created or imported connections when your HCOSS Automatically Test Connections option is set to False, and before you Refresh the connection for the first time
New DB2 Connection
Switch to the DB2 Connection tab to create a new DB2 connection.
New SQL Server Connection
Switch to the SQL Server Connection tab to create a new SQL Server connection.
Edit
Switch to the SQL Server Connection or DB2 Connection tab, depending on the selected connection, where you can make changes to your connection specifications.
Remove
Remove the selected connection.
Repair
Repair a connection that reports Needs Repair in the Status column on the Connection List.
Refresh
Update information in the Status column for the selected connection.
Refresh All
Update the information in the Status column for all connections.
System
Create a system connection, and show only system connections on the Connections List grid.
User
Create a user connection, and show only user connections on the Connections List grid.
Encrypt ADO Connection Settings
In this version of HCOSS, this check box has no effect on the connection.
Enable Checking for New ODBC Drivers
When editing and repairing connections, HCOSS checks the current ODBC driver version and prompts you to upgrade if a more recent version is installed and available. Applies to System and User connection types only.
Parent topic: Manage Connections
Related concepts
Manage Connections Tool
Related tasks
To create a DB2 connection
To create a system or user SQL Server connection


DB2 Connection tab

Restriction: This topic applies to Windows environments only.
Data Source Name
Type a name for this connection.
User ID
Type the user ID you want to use for your DB2 database login.
Password
Type the password you want to use for your DB2 database login.
Allow Saving ADO.NET Connection Password
In this version of HCOSS, this check box has no effect on the connection.
Network Address
The IP address used on your network to connect to your mainframe DB2 database.
Network Port
The port number used to access your mainframe DB2 database.
Initial Catalog
The name of the catalog used by your DB2 database.
Package Collection
The name of the package collection your DB2 database connection uses to talk to mainframe DB2.
Host CCSID
Type the DB2 CCSID value to use in program connection strings, or click Get Default to connect to the mainframe using the connection information provided on this tab, and obtain the default CCSID value and populate the field.
Get Default
Connect to the mainframe using the connection information provided on this tab, and obtain the default CCSID value to populate the Host CCSID field.
Test
Verify that the information you have specified on this tab is sufficient to create a working DB2 database connection.
Save
Create a DB2 ADO.NET connection based on the information you have specified on this tab.
Parent topic: Manage Connections
Related concepts
Manage Connections Tool
Related tasks
To create a DB2 connection


SQL Server Connection tab

Restriction: This topic applies to Windows environments only.
ODBC Driver
Shows the name and version of the ODBC driver in use for the current connection. Visible for System and User connection types only.
Data Source Name
Type a name for this connection.
Integrated Windows Authentication
Automatically send your Windows user ID and password as login credentials for this connection.
Use SQL Server Login
Send the User ID and Password supplied in the corresponding fields as login credentials for this connection.
User ID
Type the user ID you want to use for your SQL Server login. This is required only when you have selected Use SQL Server Login.
Password
Type the password you want to use for your SQL Server login. This is required only when you have selected Use SQL Server Login.
Allow Saving ADO.NET Connection Password
In this version of HCOSS, this check box has no effect on the connection.
SQL Server Instance
Select a SQL Server instance from the drop-down list, or type the name of a SQL Server instance. Use . or (local) to specify your local machine.
Refresh
Refresh the list of available SQL Server instances.
Confirm Server
When you specify a SQL Server instance by typing into the SQL Server Instance field rather than selecting from the drop-down list, click this to confirm the specified instance and test its validity.
Use a database other than the default database: dbname
Activates the Database drop-down list, enabling you to specify an alternative database for this connection.
Database
Select a database from the drop-down list, which includes all SQL Server databases available for the login credentials you specified for this connection.
Test
Verify that the information you have specified on this tab is sufficient to create a working SQL Server connection.
Save
Create an ODBC and an ADO.NET SQL Server connection, each based on the information you have specified on this tab.
Parent topic: Manage Connections
Related concepts
Manage Connections Tool
Related tasks
To create a system or user SQL Server connection


Export tab

Restriction: This topic applies to Windows environments only.
Select All
Select all entries listed on the connections grid.
Unselect All
Unselect all entries listed on the connections grid.
Name
The data source name you specified for the connection when you created it.
Type
The type of database connection, SQL Server or DB2.
Status
The last known status of the connection:
OK | The connection is established and working properly
Needs Repair | The connection is established but is not working properly
Unknown | Shows for newly created or imported connections when your HCOSS Automatically Test Connections option is set to False, and before you Refresh the connection for the first time
Export to file
The full path to and filename of an XML (.xml) file to which you want to save your connection information.
Export
Export the selected connections.
Parent topic: Manage Connections
Related concepts
Manage Connections Tool
Related tasks
To export a connection


Import tab

Restriction: This topic applies to Windows environments only.
Import from file
The full path to and filename of an XML (.xml) file you want to import.
Read Available Connections
Loads all connections defined in the imported XML file into the connections grid.
Select All
Select all entries listed on the connections grid.
Unselect All
Unselect all entries listed on the connections grid.
Name
The name of the connection as specified by the <name> element in the imported XML file.
Connection String
The connection string required to create the connection, as specified in the <ConnectString> element of the imported XML file.
Import
Import the selected connections.
Progress
Shows the progress of the import process.
Parent topic: Manage Connections
Related concepts
Manage Connections Tool
Related tasks
To import a connection


Log Files tab

Restriction: This topic applies to Windows environments only.
Log file path
Shows the full path to the folder containing your log files.
Log files
This grid lists each log file residing in the Log file path, in reverse chronological order.
Delete Selected
Delete the log files selected on the list.
Delete All
Delete all log files on the list.
Filter by
Select a filter to dictate the contents shown in the Log file contents window.
Log file contents
Shows the contents of the selected log file based on the selected filter.
Parent topic: Manage Connections
Parent topic: Extract Schema
Parent topic: Define Lists
Parent topic: Generate DDL
Parent topic: Assess Application Migration
Parent topic: Manage Packages and Plans
Related concepts
Managing Log Files


Extract Schema

  • Schema Extract tab
  • Create New Schema Extract
  • Results tab
  • Log Files tab
Parent topic: User Interface Reference


Schema Extract tab

Restriction: This topic applies to Windows environments only.
Select schema(s) to extract
List of schemas available in the DB2 database specified by the DB2 data source connection. The list includes schemas that contain one or more tables, views, stored procedures, or any combination of tables, views, and stored procedures.
Schema Extract Name
A name for the schema extract file.
Local
Sets the Extract Schema tool to save the generated schema extract file to the directory specified by the Local HCOSS Directory HCOSS option.
Shared
Sets the Extract Schema tool to save the generated schema extract file to the directory specified by the Shared HCOSS Directory HCOSS option.
DB2 DSN
The DSN specified in the accompanying field is DB2.
SQL Server DSN
The DSN specified in the accompanying field is SQL Server.
Catalog Schema
The name of an IBM catalog schema to extract.
Estimated using schema statistics
Records the estimated table row count using statistics last updated by the mainframe DB2 RUNSTATS utility. Use this option to improve performance.
Both Estimated and Actual (COUNT(*))
Records both the estimated table row count and the actual row count as retrieved using a SELECT BIG_COUNT(*) query. Use this option to provide accuracy.
New
Create a new schema extract file.
Revert
Removes all changes made on this tab, setting each field and control to its last saved setting.
Save
Saves changes made on this tab.
Delete
Deletes the schema extract file.
Extract
Extract the schemas selected on the Select Schema(s) to Extract list.
Import
Import a previously exported schema extract file.
Export
Copy the generated schema extract file to a specified directory so that it can be used to import the schema into the tool when the mainframe is not available.
Parent topic: Extract Schema
Related concepts
Extract Schema Tool
Assess Data Migration Tool
Related tasks
To extract DB2 schema objects
To modify a schema extract file
To assess data migration


Create New Schema Extract

Restriction: This topic applies to Windows environments only.
Schema Extract Name
A name for the schema extract file.
Metadata/Catalog Schema Name
The name of a manually created schema containing views of the SYSIBM schema. Use this to enable access to SYSIBM tables without granting access to the catalog itself.
Parent topic: Extract Schema
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schema objects


Results tab

Schema Extract Results
Shows the results of the schema extract process.
Parent topic: Extract Schema
Related concepts
Extract Schema Tool
Related tasks
To extract DB2 schema objects
To modify a schema extract file


Assess Data Migration

  • Data Assessment Tasks tab
  • Create New Data Assessment Task dialog box
  • Results tab
Parent topic: User Interface Reference


Data Assessment Tasks tab

Restriction: This topic applies to Windows environments only.
Available Assessments list
List of previously created data assessment tasks.
Available Assessments Local button
Show local transfer lists on the Available Transfer Lists list.
Available Assessments Shared button
Show shared transfer lists on the Available Transfer Lists list.
Associated Schema Extract list
List of local or shared extracted schemas created using the Extract Schema tool.
Associated Schema Extract Local button
Show local extracted schemas on the Associated Schema Extract list.
Associated Schema Extract Shared button
Show shared extracted schemas on the Associated Schema Extract list.
New
Create a new data assessment task.
Save
Save the data assessment task specified in the Available Assessments field.
Delete
Delete the data assessment task specified in the Available Assessments field.
DB2 Connection
The name of an existing DB2 connection.
Table List grid
Shows the information available in the extracted schema on a table-by-table basis.
Count-Type column
Select Actual to show the actual number of rows; select Estimated to show the estimated number of rows.
Transfer Option column
Change this from the default HCOSS to OTHER for tables you want to exclude from the schema extract files.
Update Row Count
Update the schema extract file with changed information from the Table list grid.
Save Options
Save the options as they appear on the Table list grid.
Export Report (txt)
Save the data assessment specifications as a text file.
Export Details (csv)
Export the data assessment specifications to a CSV file compatible with spreadsheet software.
Parent topic: Assess Data Migration
Related concepts
Assess Data Migration Tool
Related tasks
To assess data migration


Create New Data Assessment Task dialog box

Restriction: This topic applies to Windows environments only.
Name
A name for the new data assessment task.
Schema Extract
Lists the schema extract files available to associate with the new data assessment task.
Parent topic: Assess Data Migration
Related concepts
Assess Data Migration Tool
Related tasks
To assess data migration


Results tab

Update Results
Shows any error messages generated while updating row count.
Parent topic: Assess Data Migration
Related concepts
Assess Data Migration Tool
Related tasks
To assess data migration


Define Lists

  • Transfer Lists tab
  • Create New List dialog box
  • Log Files tab
Parent topic: User Interface Reference


Transfer Lists tab

Restriction: This topic applies to Windows environments only.
Available Transfer Lists list
List of previously created local or shared transfer lists.
Available Transfer Lists Local button
Show local transfer lists on the Available Transfer Lists list.
Available Transfer Lists Shared button
Show shared transfer lists on the Available Transfer Lists list.
Associated Schema Extract list
List of local or shared extracted schemas created using the Extract Schema tool.
Associated Schema Extract Local button
Show local extracted schemas on the Associated Schema Extract list.
Associated Schema Extract Shared button
Show shared extracted schemas on the Associated Schema Extract list.
New
Create a new transfer list.
Save
Save the transfer list specified in the Available Transfer Lists field.
Delete
Save the transfer list specified in the Available Transfer Lists field.
Type
Filter the Available Objects list by Table, View, or both (all).
Schema
Filter the Available Objects list by schemas available in the specified extracted schema.
Name
Filter the Available Objects list by schema items (tables or views) available in the specified extracted schema. The items on this list are filtered by the Type and Schema specifications.
Available Objects
Lists the objects available for transfer, filtered by the values specified in the Type, Schema, and Name fields.
Selected Objects
Lists the objects selected for transfer. Gray rows show objects that are dependent on a selected object but were not necessarily selected from the Available Objects list. The number in the Seq column shows dependency relationships.
Add All
Add all objects on the Available Objects list to the Selected Objects list.
Add
Add selected items on the Available Objects list to the Selected Objects list. Objects dependent on selected objects are added automatically.
Remove
Remove selected objects from the Selected Objects list. Objects dependent on a selected object are removed automatically.
Remove All
Remove all objects from the Selected Objects list.
Revert
Set the Available Objects and Selected Objects lists back to their last saved state.
Parent topic: Define Lists
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list


Create New List dialog box

Restriction: This topic applies to Windows environments only.
Name
A name for the new transfer list.
Schema Extract
Lists the schema extract files available to associate with the new transfer list.
Parent topic: Define Lists
Related concepts
Define Lists Tool
Related tasks
To define an object transfer list


Generate DDL

  • DDL Tasks tab
  • Create New DDL Task dialog box
  • Customize DDL tab
  • Schema Mappings tab
  • Results tab
  • Log Files tab
Parent topic: User Interface Reference


DDL Tasks tab

Restriction: This topic applies to Windows environments only.
Available Tasks list
List of previously created local or shared generated DDL tasks.
Available Tasks Local button
Show local DDL tasks on the Available Tasks list.
Available Tasks Shared button
Show shared DDL tasks on the Available Tasks list.
Associated Transfer List list
List of local or shared transfer lists created using the Define Lists tool.
Associated Transfer List Local button
Show local transfer lists on the Associated Transfer List list.
Associated Transfer List Shared button
Show shared transfer lists on the Associated Transfer List list.
New
Create a new DDL task.
Save
Save the DDL task specified in the Available Tasks field.
Revert
Set changed fields and controls back to their last saved state.
Delete
Delete the DDL task specified in the Available Tasks field.
Drop and create objects
The generated DDL drops and creates objects in the destination SQL Server database. Default.
Restore missing objects
The generated DDL restores missing objects in the destination SQL Server database.
Connection for Check
The name of the SQL Server connection you want to use to test DLL task specifications. This defaults to the SQL Server data source specified for the Data source to use for testing DDL HCOSS Option, if set.
Connection for Execute
The name of the SQL Server connection you want to use when executing the DDL. This defaults to the SQL Server data source specified for the Name of the current/default target data source HCOSS Option, if set.
Preserve mainframe text sort order
When checked, HCOSS populates coded character set identifiers (CCSIDs), preserving the mainframe text sort order. If unchecked, the sort order is the default SQL Server order specified for the database. Default is unchecked.
Check
Checks the DDL task specifications against the SQL Server data source specified as the Connection for Check, and takes you to the Results tab to view the results of the check.
Execute
Generates the DDL and then executes it against the SQL Server data source specified as the Connection for Execute, and takes you to the Results tab to view the results.
Customize
Takes you to the Customize DDL tab where you can customize the SQL generated for the DDL.
Schema Mappings
Takes you to the Schema Mappings tab where you can change the name of your SQL Server schema.
Export SQL Script
Save the SQL generated for the DDL as an SQL script.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Create New DDL Task dialog box

Restriction: This topic applies to Windows environments only.
Name
The name of the new DDL task.
Transfer List
Lists the transfer lists available to associate with the new DDL task.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Customize DDL tab

Restriction: This topic applies to Windows environments only.
Objects grid
Lists the schema objects available in the transfer list specified in the Associated Transfer List field on the DDL Tasks tab, in the sequence in which they appear on the transfer list.
Check All
Checks all schema objects listed on the Objects grid against a SQL Server data source and takes you to the Results tab to view the results of the check. To use this option, you must have a test SQL Server data source specified in the Data source to use for testing DDL field of your HCOSS Options.
Revert All
Removes all changes to SQL code made for all objects on the Objects grid, setting the code back to its last saved state. Once saved, you cannot revert your changes.
Save All
Saves all changes to SQL code made for all objects on the Objects grid. Once saved, you cannot revert your changes.
Generated DDL
Shows the DDL generated by default for the object selected on the Objects grid.
Customized DDL
Edit the default DDL code for the object selected on the Objects grid to customize the code generated into the DDL.
Revert
Removes all changes made to the SQL code in the Customized DDL field, setting the code back to its default state. Once saved, you cannot revert your changes.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Schema Mappings tab

Restriction: This topic applies to Windows environments only.
DB2 Schema Name
Lists the DB2 schemas available in the transfer list specified in the Associated Transfer List field on the DDL Tasks tab.
SQL Schema Name
Lists the SQL schema name mapped to each corresponding DB2 schema name. Default SQL schema names are the same as their corresponding DB2 schema names.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Results tab

Restriction: This topic applies to Windows environments only.
Attempted DDL Command(s)
Shows the DDL commands tested against the test SQL Server data source specified in the Data source to use for testing DDL field of your HCOSS Options, or executed using the connection specified in the Destination Connection field on the DDL Tasks tab.
SQL Server Results
Shows results for the executed commands.
Parent topic: Generate DDL
Related concepts
Generate DDL Tool
Related tasks
To generate and execute DDL
To customize generated DDL
To customize schema mappings in DDL


Transfer Data

  • Transfer Data Tasks tab
  • Create New Transfer Data Task dialog box
  • Customize Transfer Data tab
  • Results tab
Parent topic: User Interface Reference


Transfer Data Tasks tab

Restriction: This topic applies to Windows environments only.
Available Tasks list
List of previously created local or shared transfer data tasks.
Available Tasks Local button
Show local transfer data tasks on the Available Tasks list.
Available Tasks Shared button
Show shared transfer data tasks on the Available Tasks list.
Associated DDL Task list
List of local or shared DDL tasks created using the Generate DDL tool.
Associated DDL Task Local button
Show local DDL tasks on the Associated DDL Task list.
Associated DDL Task Shared button
Show shared DDL tasks on the Associated DDL Task list.
New
Create a new transfer data task.
Save
Save the transfer data task specified in the Available Tasks field.
Revert
Set changed fields and controls back to their last saved state.
Delete
Delete the transfer data task specified in the Available Tasks field.
Source Connection
The name of an existing DB2 connection.
Destination Connection
The name of an existing SQL Server connection.
Transfer
Execute the task and transfer the data.
Clear
Clear the data tables in the destination SQL Server database.
Customize
Takes you to the Customize Transfer Data tab where you can customize the transfer specifiations for individual tables.
One SSIS package for each table
Generate one SSIS package for each table specified in the transfer data task.
Single SSIS package for all tables
Generate a single SSIS package containing all of the tables specified in the transfer data task. In the generation process, each table receives a sequence number to differentiate it from other tables in the package.
Export
Export SSIS package or packages as specified by the selected radio button.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Create New Transfer Data Task dialog box

Restriction: This topic applies to Windows environments only.
Name
The name of the new transfer data task.
DDL Task
Lists the DDL tasks available to associate with the new transfer data task.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Customize Transfer Data tab

Restriction: This topic applies to Windows environments only.

Tables grid

Seq
The sequence in which each object is transferred from the DB2 database to the SQL Server database.
Schema
The names of schemas containing data to be transferred.
Name
The names of tables containing data to be transferred.
Buffer rows
The maximum number of rows that can be held in an individual buffer during the transfer.
Query
Perform the transfer by running a query against the SQL Server via the SSIS engine.

Transfer Task Options group

Fail on Error
The data transfer fails when it encounters an error.
Log Error Rows
The Transfer Data tool logs an error for each row or series of rows containing an error, based on the number specified in the Commit Size field.
Commit Size
When Log Error Rows is selected, this editable field shows the number of error rows to identify before committing to the log file. Default it 10.
Ignore Error
The Transfer Data Tool ignores all errors and continues transferring data.
Fire Triggers
When checked, HCOSS fires all defined triggers during the data transfer. Default is unchecked.
Check Constraints
When checked, SQL Server performs all defined checks during the data transfer. Default is unchecked.

WHERE/ORDER BY in SELECT group

Build WHERE
Use the other controls in this group to build an WHERE clause for the query that corresponds to the tables selected on the grid.
Build ORDER BY
Use the other controls in this group to build an ORDER BY clause for the query that corresponds to the tables selected on the grid.
Column
Lists the columns available for the tables selected on the grid.
Conditional Operator
Lists valid conditional operators you can use for this clause.
AND
Inserts an AND into the clause.
OR
Inserts an OR into the clause.
Value
A literal value to insert into the clause.
>
Move completed clauses to the Predicate or Sort Order box.
<
Remove the clause from the Predicate or Sort Order box.
Predicate or Sort Order
Shows the code for a completed clause.

Transfer List Actions group

Update
Updates the selected query with the WHERE or ORDER BY clause in the Predicate or Sort Order box.
Save All
Saves all changes made to all table queries on the Objects list. Once saved, you cannot revert your changes.
Revert
Removes all changes made to the table queries selected on the Objects list, setting them back to their last saved state. Once saved, you cannot revert your changes.
Revert All
Removes all changes made to all table queries on the Objects list, setting them back to their last saved state. Once saved, you cannot revert your changes.

Source Table Row Count group

Estimate using schema statistics
Estimate the row count by querying CARDF in SYSIBM.SYSTABLES. Use this option for optimal performance if your schema statistics have been recently updated. This is the default setting when you have not specified a WHERE clause.
Acutal using COUNT_BIG(*)
Directly query the row count by executing SELECT COUNT_BIG(*) FROM targetTable. This option provides an accurate count of the rows to be transferred. This is the default setting when you specify a WHERE clause. Large tables can degrade performance.

Data Transfer Actions group

Clear
Clear the data tables in the destination SQL Server database.
Transfer
Transfer the data.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Results tab

Transfer Results
Shows the results of the data transfer process.
Parent topic: Transfer Data
Related concepts
Transfer Data Tool
Related tasks
To transfer data
To customize a transfer data task


Compare Data

  • Compare Data Tasks tab
  • Create New Compare Data Task dialog box
  • Customize Compare Data tab
  • Results tab
Parent topic: User Interface Reference


Compare Data Tasks tab

Restriction: This topic applies to Windows environments only.
Available Tasks list
List of previously created local or shared compare data tasks.
Available Tasks Local button
Show local compare data tasks on the Available Tasks list.
Available Tasks Shared button
Show shared compare data tasks on the Available Tasks list.
Associated DDL Task list
List of local or shared DDL tasks created using the Generate DDL tool.
Associated DDL Task Local button
Show local DDL tasks on the Associated DDL Task list.
Associated DDL Task Shared button
Show shared DDL tasks on the Associated DDL Task list.
New
Create a new compare data task.
Save
Save the compare data task specified in the Available Tasks field.
Revert
Set changed fields and controls back to their last saved state.
Delete
Delete the compare data task specified in the Available Tasks field.
Source Connection
The name of an existing DB2 connection.
Destination Connection
The name of an existing SQL Server connection.
Compare
Execute the task to compare the data.
Customize
Takes you to the Customize Compare Data tab where you can customize the specifiations for making the comparison.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Create New Compare Data Task dialog box

Restriction: This topic applies to Windows environments only.
Name
The name of the new compare data task.
DDL Task
Lists the DDL tasks available to associate with the new compare data task.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Customize Compare Data tab

Restriction: This topic applies to Windows environments only.

Task Attributes group

Task Name
The name of the Compare Data task being customized.
List Name
The name of the data transfer list specified in the associated DDL task.
Location
The location of the data transfer list, local or shared.
Source Schemas and Tables
A tree view showing the tables available for comparison.

WHERE/ORDER BY in SELECT group

Table
Shows the table selected on the Source Schemas and Tables tree view.
Build WHERE
Use the other controls in this group to build an WHERE clause for the specified table.
Build ORDER BY
Use the other controls in this group to build an ORDER BY clause for the specified table.
Column
Lists the columns available for the specified table.
Conditional Operator
Lists valid conditional operators you can use for this clause.
AND
Inserts an AND into the clause.
OR
Inserts an OR into the clause.
Value
A literal value to insert into the clause.
>
Move completed clauses to Customized Query Pair.
<
Remove the clause from Customized Query Pair.
Predicate or Sort Order
Shows the code for a completed clause.
Customized Query Pair
SQL statements associated with the table(s) selected on the Source Schemas and Tables tree view and appropriate clauses as built in the WHERE/ORDER BY in SELECT group.

Compare List Actions group

Save All
Saves all changes made to tables on the tree view. Once saved, you cannot revert your changes.
Revert All
Removes all changes made to tables on the tree view, setting them back to their default state. Once saved, you cannot revert your changes.
Compare
Compare the data.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Results tab

Comparison Results
Shows the results of the compare data process.
Parent topic: Compare Data
Related concepts
Compare Data Tool
Related tasks
To compare transferred data
To run customized data comparisons


Assess Application Migration

  • Assessment Tasks tab
  • Create New Assessment Task dialog box
  • Source Code tab
  • Results tab
  • Data Analysis tab
  • SQL Conversion tab
  • Log Files tab
Parent topic: User Interface Reference


Assessment Tasks tab

Restriction: This topic applies to Windows environments only.

Assessment Properties group

Available Assessments
List of previously created assessment tasks.
SQL Server Connection
The name of an existing SQL Server connection.
Qualifier (default schema)
The name of a schema to use as the default qualifier for this assessment. Optional.
Ignore Schema Errors
When checked, errors related to schema specification and HCOSS table and function names are ignored and not reported in the results. Default is checked.
Note: Do not uncheck this checkbox if you have not installed HCOSS on the server machine that contains your SQL Server database.
Source Code Path
The directory containing your COBOL source files or the parent directory to one or more subdirectories containing your COBOL source files. Use the browse button to select a directory.
New
Create a new assessment task.
Save
Save the assessment task specified in the Available Tasks field.
Delete
Delete the assessment task specified in the Available Tasks field.

File Counts group

Total
Total number of files available for assessment.
NoSQL
Total number of files that contain no SQL code.
Processed
Total number of files that have completed processing.
Pending
Number of files awaiting processing.

Statement Counts group

Total SQL Statements
The total number of DB2 SQL statements encountered in the processed files.
OK
For each of the As is, Code convert, HCOSS no BIND, and HCOSS with BIND conversion scenarios, reports the number of DB2 SQL statements that can be executed successfully in SQL Server.
Must fix
For each of the As is, Code convert, HCOSS no BIND and HCOSS with BIND conversion scenarios, reports the number of DB2 SQL statements that require a manual fix before they can execute successfully in SQL Server.
In doubt
For each of the As is, Code convert, HCOSS no BIND and HCOSS with BIND conversion scenarios, reports the number of DB2 SQL statements for which HCOSS cannot determine the potential for successful execution in SQL Server.
As is
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to use the code in its original state.
Code convert
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to manually convert your SQL DB2 statements to T-SQL statements before migrating to SQL Server.
HCOSS no BIND
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to use the code in its original state and compile your SQL Server application using the SQL(DIALECT) directive option without the SQL(DBRMLIB) directive option.
HCOSS with BIND
Reports the number of DB2 SQL statements that fall into each of the OK, Must fix, and In doubt categories if you were to use the code in its original state and compile your SQL Server application using both the SQL(DIALECT) and SQL(DBRMLIB) directive options. For more information, see the Manage Packages and Plans Tool and DSN BIND utility topics.

Summary grid

A file-by-file summary of the assessment, including a breakdown of the In doubt and Must fix counts represented in the Statement Counts group.

Assessment Actions group

Process Files
Run the assessment process.
Pause
Pause assessment processing.
Reset Status
After processing completes, clear all fields in preparation for rerunning the current assessment or for running a new assessment.
Export Report (txt)
Save the assessment specifications and results as a text file.
Export Details (csv)
Export the information in the Summary grid on the Results tab to a CSV file compatible with spreadsheet software.
Parent topic: Assess Application Migration
Related concepts
Assess Application Migration Tool
Manage Packages and Plans Tool
Binding Applications
DSN Bind Utility
Related tasks
To assess application migration
To export assessment results


Create New Assessment Task dialog box

Restriction: This topic applies to Windows environments only.
Name
A name for the new assessment task.
Source Code Path
The directory containing your COBOL source files or the parent directory to one or more subdirectories containing your COBOL source files. Use the browse button to select a directory.
Parent topic: Assess Application Migration
Related concepts
Assess Application Migration Tool
Related tasks
To assess application migration
To export assessment results


Source Code tab

Restriction: This topic applies to Windows environments only.
Source File
The full path to and filename of the selected source code file. If you have processed the assessment, this tab displays the converted code. Otherwise, it displays the original source code.
Next EXEC SQL
Search down and jump to the next EXEC SQL statement in the source code, wrapping back to the beginning of the file when it reaches the end.
Previous EXEC SQL
Search up and jump to the previous EXEC SQL statement in the source code, wrapping back to the end of the file when it reaches the beginning.
Parent topic: Assess Application Migration
Related concepts
Assess Application Migration Tool
Related tasks
To assess application migration


Results tab

Restriction: This topic applies to Windows environments only.

Error Details (double-click to view SQL in context) grid

A file-by-file summary of errors found during the assessment or code conversion processes.

File Path
The paths to and filenames of source files listed in the column.
Line Num
Line number in the program where the SQL statement is found.
Error Type
The type of SQL error generated for the statement.
Error Message
The error returned for the original DB2 SQL statement.
HCOSS Message
The message returned for the SQL statement after HCOSS conversion.
DB2 SQL
The source code of the original DB2 SQL statement.
File Path
The path to and filename of the source file selected on the grid.
Line
The line number in the program where the SQL statement is found in the selected source file.
Error Type
The type of SQL error generated for the statement for the selected source file.
Error Message
The error returned for the original DB2 SQL statement found in the selected source file.
HCOSS Message
The message returned for the SQL statement after HCOSS conversion of the selected source file.
DB2 SQL
The source code of the original DB2 SQL statement found in the selected source file.
Parent topic: Assess Application Migration
Related concepts
Assess Application Migration Tool
Related tasks
To assess application migration
To export assessment results


Data Analysis tab

Restriction: This topic applies to Windows environments only.
Select Schema Extract File
Lists schema extract files from which to choose.
Local
Sets the Assess Application Migration tool to look for schema extract files in and save output files to the directory specified by the Local HCOSS Directory HCOSS option.
Shared
Sets the Assess Application Migration tool to look for schema extract files in and save output files to the directory specified by the Shared HCOSS Directory HCOSS option.
Analyze Schema Extract
Analyze the schema selected from the Select Schema Extract File list.
Close Schema Extract
Closes the current schema extract file and clears the output window.
Save to File
Save the contents of the output window to a file.
Parent topic: Assess Application Migration
Related concepts
Why You Should Use the Assess Application Migration Tool
Related tasks
To analyze schema extract data


SQL Conversion tab

Restriction: This topic applies to Windows environments only.
Note: This tab becomes visible when you double-click a file listed on the Results tab.
File Path
The path to and filename of the original source code file.
Line
The line number where the displayed EXEC SQL statement appears in the original source code.
Error, no HCOSS
The HCOSS error message generated by the DB2 SQL statement displayed in the DB2 SQL window.
DB2 SQL
The DB2 SQL EXEC SQL statement found in the original source code file.
Message, HCOSS
The message generated for the same EXEC SQL statement after conversion to T-SQL.
Converted SQL
The T-SQL EXEC SQL statement found in the converted code.
Parent topic: Assess Application Migration
Related concepts
Assess Application Migration Tool
Related tasks
To assess application migration


Manage Packages and Plans

  • Bind Scripts tab
  • Bind Packages tab
  • Bind Plans tab
  • Free Packages tab
  • Free Plans tab
  • Results tab
  • Log Files tab
Parent topic: User Interface Reference


Bind Scripts tab

Restriction: This topic applies to Windows environments only.
New
Create a new bind script file.
Open
Open an existing bind script file.
Save
Save the bind script file.
Save As
Save the bind script file under a new name.
Bind Script File
Full path to and name of the bind script file.
SQL Server Connection
The data source name for your SQL Server connection.
Bind Script Entries
The BIND PACKAGE and BIND PLAN commands in the bind script file.
New Package
Switch to the Bind Packages tab to create a new package in the SQL Server database by generating a BIND PACKAGE command for the bind script file, and executing the command.
New Plan
Switch to the Bind Plans tab to create a new plan in the SQL Server database by generating a BIND PLAN command for the bind script file, and optionally executing the command as well.
Edit
Switch to either the Bind Packages or the Bind Plans tab, depending on the selection, to modify the selected command and generate and execute the changes as a new BIND PACKAGE command, or generate and optionally execute the changes as a new BIND PLAN command.
Move Up
Reposition the selected bind script command to appear before the command listed just above it.
Move Down
Reposition the selected bind script command to appear after the command listed just below it.
Delete
Delete the selected bind script command.
Execute Selected
Execute the command selected on the Bind Script Entries list.
Execute All
Execute all commands listed on the Bind Script Entries list.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Related tasks
To execute one or all bind script lines
To create a bind script file
To open an existing bind script file
To edit an existing BIND command


Bind Packages tab

Restriction: This topic applies to Windows environments only.
Collection Name
The name of the collection in which to store the package.
Library Name
The name of the library containing the source member from which you want to create the package. The <default> is DBRMLIB.
Member Name
The name of (program ID of) the source member from which you want to create the package.
Default Qualifier
The name of a schema to use as the default qualifier for this package. Optional.
Add
If the package does not already exist in the specified collection, add it to the collection.
Replace
If this package already exists in the collection, replace it; if it doesn't already exist, add it to the collection.
Replace Version
Replace the package version specified in the corresponding field with the generated package version.
Revert
Return all settings changed since opening the Packages tab to their original settings.
Execute
Execute the package to create it in the specified SQL Server database in preparation for binding into a plan. After binding, all versions of the bound package are automatically available to the plan.
Parent topic: Manage Packages and Plans
Related concepts
Package Specifications
Manage Packages and Plans Tool
Related tasks
To create a new package
To edit an existing BIND command


Bind Plans tab

Restriction: This topic applies to Windows environments only.
Plan Name
The name of a plan that you can bind to your application.
Default Qualifier
The name of a schema to use as the default qualifier for this plan. Optional.
Packages
Bind existing packages into the plan.
DBRM Members
Bind source members into the plan.
DBRM Libraries
Bind source libraries into the plan in the order they appear on the Selected Libraries list, which represents the order in which HCOSS searches the libraries for DBRM members, using the first-found instance of a specified member.
Add
If the plan does not already exist in the SQL Server database, add it to the database.
Replace
Replace an existing plan of the same name with this plan.
Revert
Return all settings changed since opening the Plans tab to their original settings.
Name
A search string on which to refine the options on the list below. You can use the wild-card character % to represent any string or string fragment.
Search
Refine the options on the list below to those matching the search string in the corresponding Name field.
Available Collections
List of collections available in the current SQL database. Available in Packages mode only.
Available Packages
Packages included in the collection selected on the Available Collections list. Available in Packages mode only.
Selected Packages
Packages selected to add to or replace in the plan. Available in Packages mode only.
Available Members
List of DBRM members available for binding into the plan. Available in DBRM Members mode only.
Selected Members
Members selected to add to or replace in the plan. Available in DBRM Members mode only.
Available Libraries
List of DBRM libraries available for binding into the plan. Available in DBRM Libraries mode only.
Selected Libraries
Libraries selected to add to or replace in the plan. The order in which the libraries appear on this list determines the search order HCOSS uses to locate specified DBRM members. Available in DBRM Libraries mode only.
Add
Add the items selected on the list or lists to the left to the list on the right.
Remove
Remove the items selected on the list to the right.
Move Up
Reposition the library selected on the Selected Libraries list to appear before the libary listed just above it, changing the order in which the libraries are searched for DBRM members. Available in DBRM Libraries mode only.
Move Down
Reposition the library selected on the Selected Libraries list to appear after the libary listed just below it, changing the order in which the libraries are searched for DBRM members. Available in DBRM Libraries mode only.
Add to Script
Generate a script line representing the settings on this tab, and add it to the list of bind script entries found on the Bind Scripts tab.
Execute
Generate and execute a command representing the settings on this tab, thereby updating the SQL Server database, and generate a script line with a command representing the settings on this tab and add it to the list of bind script entries found on the Bind Scripts tab.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Plan Specifications
Related tasks
To create a new plan
To edit an existing BIND command


Free Packages tab

Restriction: This topic applies to Windows environments only.
Bound Packages
Lists all available bound packages.
Show package version information
Toggle the Version column in the Bound Packages grid.
Free Package(s)
Free all packages selected on the Bound Packages list.
Free All Packages
Free all packages on the Bound Packages list.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Related tasks
To free one or more packages


Free Plans tab

Restriction: This topic applies to Windows environments only.
Bound Plans
Lists all available bound plans.
Members
For the plan selected on the Bound Plans list, populates the Bound Members list with the DBRM members bound into the plan.
Packages
For the plan selected on the Bound Plans list, populates the Bound Packages list with the packages bound into the plan.
Bound Members
Shows the DBRM members bound into the selected plan. Available only when Members is selected.
Bound Packages
Shows the packages bound into the selected plan. Available only when Packages is selected.
Expand PKLIST to show package details
View all packages that resulted when binding the plan. Available only when Packages is selected.
Show package version information
Show the version for each package listed. Available only when Expand PKLIST to show package details is checked.
Free Plan
Free the plan selected on the Bound Plans list.
Free All Plans
Free all plans on the Bound Plans list.
Parent topic: Manage Packages and Plans
Related concepts
Manage Packages and Plans Tool
Related tasks
To free one plan or all plans


Results tab

Command Results
Shows the results of the bind execution.
Parent topic: Manage Packages and Plans
Related tasks
To execute one or all bind script lines


Data Mappings tab

Restriction: This topic applies to Windows environments only.
DB2 Data Type
The DB2 database column type.
Encoding
The encoding associated with the corresponding DB2 data type, ASCII, EBCDIC, or UNICODE.
Data Storage Options
The method of data storage for the DB2 data type, For bit data, Mixed data, None, or SBCS data.
SQL Server Data Type
The SQL Server database column type to which HCOSS maps the corresponding DB2 Data Type.
Restore Defaults
Restores the default setting for each changed entry.
Parent topic: User Interface Reference
Related concepts
Customizing Data Type Mappings
Related tasks
To customize data type mappings


SQL Name tab

Restriction: This topic applies to Windows environments only.
DB2 Function/Special Register
The name of a DB2 function or special register from the originating application.
SQL Server Equivalent
The SQL Server equivalent function or special register to which the corresponding DB2 function or special register is migrated.
Is Function
Identifies corresponding DB2 and SQL Server entries as functions.
Is Special Register
Identifies corresponding DB2 and SQL Server entries as special registers.
Restore Defaults
Restores the default setting for each changed entry.
Parent topic: User Interface Reference
Related concepts
Customizing Functions and Special Registers
Related tasks
To customize SQL name mappings


Customize SQLCode Mappings

  • SQLCode Mappings tab
  • Deploy/Extract tab
Parent topic: User Interface Reference


SQLCode Mappings tab

Restriction: This topic applies to Windows environments only.
SQL Server SQLCode
Lists SQL Server SQLCode settings.
Map to z/OS DB2 SQLCode
Lists DB2 SQLCode settings that map to the corresponding SQL Server SQLCodes.
Map to z/OS DB2 SQLState
Lists DB2 SQLState settings that map to the corresponding DB2 SQLCodes.
Save
Saves changes to the mfhcocds.txt file and saves original mappings to a backup file.
Restore
Loads previously defined mappings from a backup file.
Deploy/Extract
Takes you to the Deploy/Extract tab where you can deploy changes to your SQL Server database.
Parent topic: Customize SQLCode Mappings
Related concepts
Customize SQLCode Mappings Tool
Related tasks
To customize SQLCode mappings


Deploy/Extract tab

Restriction: This topic applies to Windows environments only.
Data Source Name
The name of the SQL Server connection to the SQL Server database you want to update.
User ID
If required by your selected data source, type the user ID for your SQL Server login.
Password
If required by your selected data source, type the password for your SQL Server login.
Deploy to SS
Update the SQL Server database with changes made to the mfhcocds.txt file.
Extract from SS
Extract mapping information from the SQL Server database and saves it to a backup file.
Parent topic: Customize SQLCode Mappings
Related concepts
Customize SQLCode Mappings Tool
Related tasks
To customize SQLCode mappings


Options

Restriction: This topic applies to Windows environments only.

Assessment Tool Options

Tab size
Tab size used in COBOL source. Default is 4.

Compare Data Options

Compare interval refresh time
Time interval in seconds to refresh the compare progress in terms of row count. Default is 2.
Maximum number of failures
Stops the compare when the specified number of failures (non-matching rows) is reached. Default is 50.

Extract Schema Options

Cast STATEMENT column to VARCHAR during SysViews extract
True | Fixes view migration issues from z/OS DB2 version 10 and later.
False | Default.

HCOSS Connections

Automatically Test Connections
True | HCOSS automatically tests your established database connections and automatically updates their status. Default.
False | You must update the status of each connection using the Refresh button in the Manage Connections tool.
Data source to use for testing DLL
The name of the SQL Server connection you want to set as the default testing database when generating DDL. If you do not provide a SQL Server connection, HCOSS does not perform any tests when generating DLL. (optional)
Name of the current/default target data source
The name of the SQL Server connection that you want to set as the default connection. (optional)
Timeout value for each connection
When checking a connection status, the number of seconds HCOSS waits for a returned status before moving on to check the next connection listed on the Connection List tab of the Manage Connections tool. Applies only to the Connection List tab. The default is 5.

HCOSS Directories

Local HCOSS Directory
The parent directory to the subdirectory structure used to store local generated HCOSS files. The default is %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where genFileType is one of the following:
  • ApplicationAssessments
  • CompareTasks
  • DataTasks
  • DBRMDataSets
  • DDLTasks
  • Schemas
  • TargetLists
Shared HCOSS Directory
The parent directory to the subdirectory structure used to store shared generated HCOSS files. The default is %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where genFileType is one of the following:
  • ApplicationAssessments
  • CompareTasks
  • DataTasks
  • DBRMDataSets
  • DDLTasks
  • Schemas
  • TargetLists
Note: All users must have READ/WRITE access to this directory.

HCOSS UAC Behavior

Prompt to automatically run as Administrator
True | When you start HCO for SQL Server as a standard user from the Start menu, and you are a member of the Administrators group, HCOSS prompts you to run HCOSS as an Administrator. Default.
False | HCOSS does not prompt you to run HCOSS as an administrator.
Run as Administrator if in Administrators Group
True | When you start HCO for SQL Server as a standard user from the Start menu, and you are a member of the Administrators group, HCOSS automatically runs in administrator mode. At startup, a Windows UAC prompt appears. Default.
False | HCOSS does not automatically run HCOSS as an administrator, but prompts you to start as an administrator when you launch HCOSS from the Start menu as a standard user.
Warn non-Administrator users of limited functionality
True | When running HCOSS as a standard user, HCOSS presents this prompt at startup to warn you that some functionality is limited when running in standard user mode. Default.
False | HCOSS presents a prompt at startup to warn you of limited functionality.

Log File Options

Automatically delete log files
Enable or disable the automatic deletion of log files older than the number of days specified by the Days before automatically deleting log files option. The default is False.
Days before automatically deleting log files
The number of days to wait before automatically deleting log files. Valid when Automatically delete log files is set to True. The default is 30.
Directory to write log files to
The parent directory to the subdirectory structure used to store HCOSS-generated log files. The default is %LOCALAPPDATA%\Micro Focus\Enterprise Developer\hcoss\genFileType.
Where logFileType is one of the following:
  • BindTasks
  • CompareTasks
  • Connections
  • DataTasks
  • DDLTasks
  • Schemas
  • TargetLists
Note: HCOSS does not create log files when Type of logging to do is set to Write log messages just to console, which is the default setting.
Type of logging to do
Set HCOSS to send log information to the console, a log file, or both. Default is Write log messages just to console.

Startup

Type of HCO for SQL Server Startup
Specify the type of HCO for SQL Server startup environment, whether to start by loading information from the last session or to start with no previous information loaded. Default is Show empty environment.
Parent topic: User Interface Reference
Related concepts
HCOSS Toolset
Using HCOSS with Windows User Account Control (UAC)
Managing DBRMs
Shared DBRMs and multi-user environments
Related tasks
To start HCO for SQL Server
To set HCOSS options


IMS Support

To become familiar with the major features of IMS support, we recommend that you follow the procedures presented in either or both of the following sets of topics:

IMS: Tutorial
The IMS tutorial takes you through:
  • Creating an Enterprise Developer project
  • Adding IMS application and database files to the project
  • Building the application from the Enterprise Developer IDE
  • Using the Enterprise Server IMS template from the Enterprise Developer IDE to create and configure an enterprise server instance to run the application
  • Running the application on the enterprise server
IMS Installation Verification
The IMS Installation Verification topics take you through:
  • Preparing and compiling an IMS application using command-line tools
  • Using Enterprise Server to create and configure an enterprise server instance to run the application
  • Verifying CICS installation
  • Running the application on the enterprise server
  • IMS DB Compatible Production DBMS
    Describes the production IMS database for IMS DB applications.
  • IMS TM Compatible Transaction Manager
    Describes the production transaction processing engine used to deploy the IMS TM based applications.
  • IMS and GSAM Databases
  • IMS Installation Verification Procedure (IVP)
    Takes you through the process of preparing an IMS application using command-line tools, configuring an enterprise server region to run the application, and running the application on the enterprise server.
  • Developing IMS Applications
    Describes the basic operations you need to perform when developing IMS applications.
  • Deploying IMS Applications
    Describes the features available to deploy an IMS application to and run a production IMS application on Enterprise Server.
  • How to
  • Reference
Parent topic: Mainframe Programming
Related concepts
Tutorial: IMS Support


IMS DB Compatible Production DBMS

In Enterprise Server, we provide a production DBMS to deploy your IMS DB applications to the Linux, UNIX, or Windows platforms. It provides:
  • Support for the IMS data access elements of the application
  • Support for the IMS hierarchical data model
  • The actual database to hold the migrated IMS data
Together, these three key elements combine to offer a complete, low risk solution for re-hosting mainframe IMS applications, reducing operational costs and increasing agility. This production DBMS supports a variety of IMS applications, including:
  • Applications that use IMS TM and/or IMS DB
  • Applications that use CICS and IMS DB or JCL and IMS DB
  • Applications that run under VSE, OS390 or z/OS
  • Batch applications
  • Online applications

Supported IMS Features

DLI Functions
  • GU, GHU, GN, GHN, GNP, GHNP, ISRT, REPL, DLET
  • Fast Path: FLD, POS
  • GSAM: OPEN, CLSE
  • AIBTDLI: INQY
  • AERTDLI: CIMS, APSB, DPSB
  • CICS DL/I calls: PCB, SCHD, TERM
Database Access Types
IMS DB provides several database access types, typically chosen for best performance as determined by the application.
  • DEDB
  • GSAM
  • HALDB*
  • HDAM, HIDAM, HISAM, HSAM
  • INDEX
  • LOGICAL
  • MSDB
  • PHIDAM, PHDAM, PSINDEX
  • SHISAM, SHSAM
* HALDB is supported as a standard full-function database; however, extended features of HALDB are not supported. You can specify a HALDB database in the ACCESS parameter, but no special processing is performed for its extended features.
Database Segment Types
  • Uniquely keyed segments
  • Non-uniquely keyed segments - first, here and last rules
  • Non-keyed segments - first, here and last rules
  • Fixed and variable length segments
  • Segments containing source data for secondary index segments
  • Logical children and logical parents
  • DEDB sequential dependents (SDEP) segments
Database Recovery
DLI Program Batch Backout
Segment Search Argument (SSA)
Programs retrieve data by qualifying the retrieval with a Segment Search Argument (SSA). Enterprise Server provides compatible SSA support including:
  • Up to 15 SSAs per call, each SSA limited to 4,000 bytes
  • SSA relational operators supporting up to 125 boolean operations on each SSA
  • SSA command codes
User Exits
The IMS user exits within Enterprise Server provide a mechanism to implement custom extensions to maximize compatibility with the original mainframe implementation. However, within Enterprise Server, exit routines must be written in COBOL rather than in Assembler as mainframe Assembler is not supported in production on open systems. This means that during any migration, existing mainframe exit routines written in Assembler must be converted to or re-written in COBOL as part of the migration.
The following IMS-specific user exits are supported:
  • MFS field and segment edit routines.
  • Sparse index exits.
  • Data capture exits - The EXIT operand is supported for both the DBD and SEGM statements along with all of the EXIT options (DATA, PATH and CASCADE options) except the LOG option. The sub options for CASCADE (KEY, DATA and PATH) are also supported. A maximum of nine different exit routines can be specified for any one segment.
  • All fields in the XPCB and XSDB parameter blocks.

Maximum Database Size

IMS production databases are implemented as IDX-8 files, so the theoretical maximum size for an IMS database is tied to the maximum size for an IDX-8 file. Micro Focus has not performed tests or performance benchmarks on IMS databases larger than 300GB. Very large databases could prove to be impractical in terms of performance and maintenance (time to rebuild, etc.). We recommend that you allocate time to test for accounts that are migrating large databases as part of the prototype or proof of concept process.

The internal database structure within Enterprise Server uses symbolic keys, rather than pointers, and maintains some redundant key information, increasing the amount of actual storage required for the IMS database on Windows, UNIX or Linux. However, the key and data compression performed within the Enterprise Server file system typically compensates for this overhead.

Two Phase Commit Architecture

The IMS DB Compatible Production DBMS uses a two-step commit protocol. All registered resources are sent commit requests. The sequence for commit depends on whether the resource supports a two-step sequence or not. For two-step resources, a "Prepare" is issued to each resource before sending the "Commit" step. If all Prepares succeed, commit processing begins. If any prepare fails, backout starts. When a resource responds negatively to the prepare, it means that it cannot complete a commit but it can complete backout or has already backed out.

Our two-phase commit architecture is similar to the two-phase commit support in mainframe IMS, and shares some of the same benefits; however, it does not provide recovery from failures that might occur during backout processing or during the second step of commit processing.

The main benefit of this two-phase process over a "single-phase" commit protocol is that it eliminates the integrity window between the time the application last accessed a resource to when commit processing begins. The Prepare step catches any failures that occur during this interval and begins backout processing. Contrast this with two separate resources using a single-phase protocol. In single-phase there is no Prepare phase, only a commit or backout. If the first commit succeeded but the commit to the second resource failed, you could have a mixed outcome.

Parent topic: IMS Support


IMS TM Compatible Transaction Manager

The IMS TM compatible transaction manager is the production transaction processing engine used to deploy IMS TM-based applications to run on Linux, UNIX, and Windows target environments. It provides support for the following:
  • IMS transactions and communications
  • MFS screen management
  • System administration, monitoring, and diagnostics
DL/I Interface Functions
  • CHNG
  • GU
  • GN
  • ISRT
  • PURG
System Service Functions
  • CHKP
  • INIT
  • INQY (DBQUERY, ENVIRON, PROGRAM)
  • ROLL
  • ROLB
  • SYNC
  • XRST
Transaction Types
  • Conversational
  • Non-conversational
  • Response Mode
  • Non-response Mode
BMP Outbound Messages
A BMP (batch message processor) is a program executed by JCL. It does not have access to the IMS input message queue; however, it can send outbound messages such as checkpoint, restart, and other system service calls via an I/O PCB defined in the Linkage Section.
Transaction Scheduling
  • Class codes
  • Prioritization
  • Serialized or parallel transaction processing control
Message Region Management
This is part of the ESMAC SEP process. From here you can start and stop IMS message regions.
  • Start/Stop region
  • Control by transaction class
3270 Devices
  • Models 2, 3, 4, and 5
  • TN3270 interface
  • MFS or Bypass MFS Mode
Programming Languages
  • COBOL
  • PL/I
Supported MFS features
  • 3270 devices
  • Logical and physical paging
  • Multi-segmented messages
  • Dynamic and default attributes, extended attributes, cursor positioning
  • Printer support
  • Password support
  • MFS segment exit
  • MFS field exit
  • MFS language control
  • DBCS and mixed-mode character support
IMS Connect
This is an emulation of IBM IMS Connect.
Parent topic: IMS Support
Related concepts
Configuring IMS Printers
IMSDBU Exits
IMS Connect


IMS and GSAM Databases

You can use GSAM databases with Enterprise Developer just as you do with your mainframe IMS system. Access to your GSAM database data is controlled by JCL DD statements.

The name specified in the JCL DD statement DSN parameter is used to look up the actual filename in the system catalog. The GSAM data file properties, such as sequential or VSAM, are also defined in the system catalog.

The DD1 and DD2 parameters of the DATASET statement on the GSAM DBD specify the DD names used.

GSAM data can reside on a:
  • Local disk drive
  • Network redirected drive
  • Fileshare server

Concatenated DD statements are supported for input to GSAM databases. If specified, the concatenated files can be from any of the locations in the above list.

Enterprise Developer does not support the following:

  • GSAM Record Search Arguments (RSAs)
  • GSAM undefined length records
Parent topic: IMS Support
Related reference
Zeroload function
Load function
Unload function


IMS Installation Verification Procedure (IVP)

Takes you through the process of preparing an IMS application using command-line tools, configuring an enterprise server region to run the application, and running the application on the enterprise server.

These topics are intended both as an introduction to using IMS in Mainframe Subsystem Support (MSS), and as an Installation Verification Procedure (IVP).

Important: If you would prefer to complete the IMS IVP using the Enterprise Developer user interface rather than the command-line tools, follow the instructions in Tutorial: IMS instead. The tutorial uses the same demonstration application and enterprise server region.
  • Demonstration Application
    Describes the MFDEMO demonstration application used to complete the IMS Installation Verification Procedure.
  • Prepare the MFDEMO Application
    Takes you through the process of compiling and generating required MFDEMO source files, loading the IMS database, and importing IMS transactions. All of these tasks are done from the command line.
  • Create and Configure an IMS Enterprise Server
    Create and configure an enterprise server region on which to run the MFDEMO IMS application.
  • Run MFDEMO
    Use a TN3270 emulator to run the MFDEMO application on an enterprise server region.
Parent topic: IMS Support
Related concepts
Tutorial: IMS Support
Deploying IMS Applications


Demonstration Application

Describes the MFDEMO demonstration application used to complete the IMS Installation Verification Procedure.

The IVP is based on a demonstration program called MFDEMO, which is installed into %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\IVP for 32-bit, and IVP64 for 64-bit (Windows) or $COBDIR/demo/ims/ivp32 for 32-bit, and ivp64 for 64-bit (UNIX) , by default.

MFDEMO is a COBOL IMS TM application for creating and maintaining an IMS DB tabular database. User-defined tables are organized by table element within table name. The following components are used by this application:

IMS components:

  • DEMO03DD.DBD
  • DEMO03DD.DBU
  • DEMO001T.PSB
  • DEMO90.MFS
  • DEMO91.MFS
  • DEMO92.MFS
  • print.mfs
  • TRANCODE.TXT - IMS Stage 1 file

COBOL components:

  • DEMO001T.CBL
  • RGHTJUST.CBL
Parent topic: IMS Installation Verification Procedure (IVP)


Prepare the MFDEMO Application

Takes you through the process of compiling and generating required MFDEMO source files, loading the IMS database, and importing IMS transactions. All of these tasks are done from the command line.

Although the MFDEMO application is supplied with your application software, you need to perform a number of tasks on the source files to prepare the application for execution:

  • Copy the MFDEMO files to a working directory
  • Compile the COBOL programs
  • Generate the MFSs
  • Generate the DBD
  • Generate the PSB
  • Register the resource definition file
  • Load the database
  • Import the IMS transactions
Fastpath: We provide a batch file, build.bat, that performs all of the tasks required to prepare the MFDEMO application with the exception of registering the resource definition file. To use the batch file instead of performing these tasks one at a time as outlined in the following sections, start an Enterprise Developer command prompt, change to the directory where your MFDEMO files are located, and execute build.bat. Then follow the procedure to register the resource definition file.

Copy the MFDEMO Files

  1. Start an Enterprise Developer command prompt
    Note: Keep this command prompt open, and use it for each task included in this topic.
  2. Create a new directory to hold your copy of the MFDEMO application files.
    Note: From this point forward, we refer to this as your "working directory" in all topics that are part of the IMS Installation Verification documentation.
  3. Copy the MFDEMO application files from their installation location to your working directory. By default, the installation location is %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\IVP for 32-bit, and IVP64 for 64-bit (Windows) or $COBDIR/demo/ims/ivp32 for 32-bit, and ivp64 for 64-bit (UNIX) .

Compile the COBOL Programs

  • At the same Enterprise Developer command prompt in your working directory, enter the following commands, depending on your platform:

    Windows:

    cobol demo001b dialect(vsc24) noflag anim noobj charset(ascii) outdd"sysout 121 r e";
cobol cdlidemo dialect(mf) osvs cicsecm noflag charset(ascii) anim noobj;
cobol execdemo dialect(mf) cicsecm execdli noflag charset(ascii) anim noobj;
cobol demo001t dialect(vsc24) noflag charset(ascii) anim noobj;
cobol rghtjust dialect(mf) charset(ascii) anim noobj;

    UNIX:

    cob DEMO001B.cbl -C "dialect(vsc24) noflag anim noobj charset(ascii) outdd(sysout 121 r e)"
cob CDLIDEMO.cbl -C "dialect(mf) osvs cicsecm noflag charset(ascii) anim noobj"
cob EXECDEMO -C "dialect(mf) cicsecm execdli noflag charset(ascii) anim noobj"
cob DEMO001T.cbl -C "dialect(vsc24) noflag charset(ascii) anim noobj"
cob RGHTJUST.cbl -C "dialect(mf) charset(ascii) anim noobj"

Generate the MFS Files

MFDEMO includes the demo90, demo91, and demo92 MFS files. To generate them, do one of the following:

  • Enter these three commands consecutively:
    mfims mfsgen demo90.mfs nocls
mfims mfsgen demo91.mfs nocls
mfims mfsgen demo92.mfs nocls
mfims mfsgen print.mfs nocls
    Or,
  • Enter this command:
    for %i in (*.mfs) do mfims mfsgen %i nocls

Generate the DBD File

MFDEMO includes the demo03dd DBD file, which requires generation. The generated files, dbdgen2.dat and dbdgen2f.dat, contain information extracted from the DBD source and formatted into a smaller structure optimized for faster access during execution. They are indexed files and can contain information for one or more generated DBD members.

Important: Do not edit, move or delete the generated files.
  • Enter this command:
    mfims dbdgen demo03dd.dbd nocls echo(enderr,0,50)
    Note: If dbdgen2.dat does not already exist when you generate the DBD, you see the message DBDUT0U35U File not found DBDGEN2.DAT. This message is for information only. In this case, the dbdgen2.dat file is created during generation.

Generate the PSB File

MFDEMO includes the demo001t PSB file, which requires generation. The generated file, psbgen3.dat, contains information extracted from the PSB source and formatted into a smaller structure optimized for faster access during execution. This an indexed file, and can contain information for one or more generated PSB members.

  • Enter this command:
    mfims psbgen demo001t.psb nocls echo(enderr,0,50)
    Note: If psbgen3.dat does not already exist when you generate the PSB, you see the message DBDUT0U35U File not found PSBGEN3.DAT. This message is for information only. In this case, the psbgen3.dat file is created during generation.

Register the Resource Definition File

Enterprise Server supports two transaction types, named /CIC and /IMS respectively. They are defined in a provided resource definition file, dfhdrdat. When you register this resource definition file with Enterprise Server, it enables your enterprise server region to switch back and forth between CICS and IMS modes. This is required to run the MFDEMO application because IMS applications running on Enterprise Server use the automatic message processing region feature provided by our CICS technology.

In general, we recommend that you leave the installed dfhdrdat file intact in its default location, and copy a new instance of the file into your working directory.

  1. Copy the default resource definition file installed with Enterprise Developer, dfhdrdat, from its installation directory to your working directory. The default installation directory for dfhdrdat is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas.
  2. At an Enterprise Developer command prompt, change to your working directory.
  3. Enter the following command:
    caspcupg /dp=.

Load the Database

  • Enter this command:
    mfims imsdbu load demo03dd nocls

Import IMS Transactions

When you migrate an IMS application from the mainframe to Enterprise Developer, one of the required mainframe files is the stage 1 file containing your IMS transactions. In this demonstration, we have downloaded the MFDEMO stage 1 file for you, and then exported its contents to a flat text file, trancode.txt, which is included in the MFDEMO demonstration files. You need to create the standard data file used by Enterprise Server, imsgen2.dat, and import trancode.txt into it. To do both of these:

  • Enter this command:
    mfims stage1imp trancode.txt
Parent topic: IMS Installation Verification Procedure (IVP)
Related reference
mfims Generation
Load function


Create and Configure an IMS Enterprise Server

Create and configure an enterprise server region on which to run the MFDEMO IMS application.

Create an MSS-enabled enterprise server region

  1. To start Enterprise Server, enter the following address into your Web browser:

    http://localhost:86

  2. On the Home page of Enterprise Server Administration, click Add at the bottom of the table of servers.
  3. On the first Add Server page:
    1. Type IMSDEMO into the Server Name field.
    2. Under Working Mode, click 32-bit.
    3. Click Next.
  4. On the second Add Server page:
    1. Click Micro Focus Enterprise Server with Mainframe Subsystem Support enabled.
    2. Click Next.
  5. On the third Add Server page:
    1. In the Creation Options group, check Create TN3270 listener; then type 9004 into the using port field.
    2. Click Add.
  6. The Home page is redisplayed, and a row for the IMSDEMO enterprise server region is shown in the table of servers.

Configure IMS

  • In the table of servers, click the Edit button that corresponds to IMSDEMO.
Enable IMS support
  1. Click the Server, Properties, MSS, IMS and General tabs.
  2. Check IMS enabled.

    This specifies that the IMSDEMO enterprise server can use the IMS support.

Specify file locations
  1. On the same page, in both the Configuration directory and Gen file directory fields, specify the full path to the working directory you created to hold your copy of the MFDEMO application files (see the Copy the MFDEMO Files section of the Prepare the MDEMO Application) topic.
  2. Click Apply to save the changes.
  3. Click the Server, Properties, MSS, IMS, TM and General tabs.
  4. In the MFS path field, specify the full path to your working directory.
  5. Enter the same information into the Application path field.
  6. Click Apply to save the changes.
  7. Click the Server, Properties, MSS, IMS, DB, and General tabs.
  8. In the Database path field, specify the full path to your working directory.
  9. Click Apply to save the changes.
Enable JCL
JCL support is required for any IMS-enabled enterprise server that requires a message processing region to start whenever the enterprise server starts. You define such a message processing region later, so you need to enable JCL support in preparation.
  1. Click the Server, Properties, MSS, JES and General tabs.
  2. Check Job Entry Subsystem enabled.
  3. Click Apply.
Specify the SIT

You have now created the IMSDEMO enterprise server region and enabled it to use IMS and JCL, but you now need to specify that it uses the IMSSIT System Initialization Table (SIT), which enables you to define an automatic message processing region:

  1. Click the Server, Properties, MSS and CICS tabs.
  2. In the System Initialization Table field, type IMSSIT.
  3. Click Apply to save your change.
Define an automatic message processing region
You need at least one message processing region (MPR) to run an IMS application in an enterprise server.

To specify a message processing region for the IMSDEMO enterprise server region:

  1. Click the Server, Properties, MSS, IMS, TM and MPRs tabs.
  2. Click Add.
  3. In the Name field, enter: MPR01.
  4. In Transaction Class, enter: 001.
  5. In Description, enter: MPR for class 1.
  6. Click Add.
  7. Click Home at the upper left corner to return to the Home page of Enterprise Server Administration.
Define and configure a printer
To optionally add and test a printer, follow the steps outlined in the topics under Printers.
Parent topic: IMS Installation Verification Procedure (IVP)
Related tasks
To define specific printers for an IMS-enabled enterprise server
To enable printer security for an IMS-enabled enterprise server
To attach to an IMS printer
Printers


Run MFDEMO

Use a TN3270 emulator to run the MFDEMO application on an enterprise server region.

Start IMSDEMO

  • On the Enterprise Server Administration Home page, click the Start button that corresponds to the IMSDEMO enterprise server region.

    Wait until the text in the Status column changes to Started.

Start the MFDEMO Application

  1. Start a TN3270 emulator, for example, Rumba.
  2. Specify the following connection information.
    Note: Field names could vary depending on the 3270 emulator you are using.
    Field | Value
    Host name | The name of the computer the enterprise server is running on. If it is the current machine, you can usually specify localhost; however, some versions of Windows might prefer that you use the actual machine name or the 127.0.0.1 IP address instead.
    Port | The number you specified for the field using port in the section Creating an MSS-enabled Enterprise Server.
  3. Connect.
  4. On the IMS sign-on screen, type SYSAD into both the USERID and PASSWORD fields, using the Tab key to move from one to the other; then press Enter.
  5. Clear the screen.
    Note: If you are using Rumba, press Ctrl+Shift+Z to clear the screen.
  6. Enter MFDEMO with a trailing space.

Add Data

In the sections that follow, each set of instructions includes a screen shot showing the terminal emulator with required fields in green and red.

Tip: To navigate between fields on a terminal emulator screen, press Tab to move to the next field, and Shift+Tab to move to the previous field.
Create a TESTDEPT table
  1. In the FUNCTION CODE field, type A to select the <A>DD function.

    This action advances your cursor to the TABLE-ID field.

  2. In the TABLE-ID field, type TESTDEPT.
    Add table in the IMS application
  3. Press Enter.

    This action advances you to the DEMO92 input screen.

Input records
  1. Complete the following fields as indicated:
    DESCRIPTION | A TABLE OF TEST DEPARTMENTS
    NUMBER OF CHARACTERS IN ELEMENT KEY | 20
    NUMBER OF CHARACTERS IN ELEMENT | 50
    PASSWORD PROTECT | N
  2. Tab to the first entry field under ELEMENT KEY; then add the following records:
    ELEMENT KEY | ELEMENT VALUE/DESCRIPTION
    123 | DEPARTMENT 123
    234 | DEPARTMENT 234
  3. Tab to the RETURN field; then type X.
    Add Testept Elements
  4. Press Enter to return to the main menu.
Add an additional record
  1. In the FUNCTION CODE field, type C to select the <C>HANGE function.

    This action advances your cursor to the TABLE-ID field.

  2. In the TABLE-ID field, type TESTDEPT.
    Change Testdept Table
  3. Press Enter.

    This action advances you to the DEMO92 input screen.

  4. Tab to the first field in the third row under FUNC; then add the following record:
    FUNC | ELEMENT KEY | ELEMENT VALUE/DESCRIPTION
    A | 345 | DEPARTMENT 345
  5. Tab to the RETURN field; then type X.
    Add Testept Elements
  6. Press Enter to return to the main menu.
Add the TESTERS table and records
  1. Using the same methods as you did to create the TESTDEPT table and add records, add the TESTERS table using these values:
    DESCRIPTION | A TABLE OF TESTERS
    NUMBER OF CHARACTERS IN ELEMENT KEY | 20
    NUMBER OF CHARACTERS IN ELEMENT | 50
    PASSWORD PROTECT | N
  2. Then add the following records:
    ELEMENT KEY | ELEMENT VALUE/DESCRIPTION
    JOHN SMITH | IMS DC TEST TECHNICIAN
    JANE JONES | IMS DB TEST TECHNICIAN

    Add Testers Elements
  3. Press Enter to return to the main menu.
Exit MFDEMO
  1. On the main menu, type E into the FUNCTION CODE field; then press Enter.

    This action takes you to the TRANCODE - MFDEMO - ENDED screen.

    MFDEMO - ENDED
  2. Disconnect from the TN3270 display. To do this in Rumba, click Disconnect on the toolbar [image].
Parent topic: IMS Installation Verification Procedure (IVP)


Developing IMS Applications

Micro Focus provides support within Enterprise Developer that enables IMS Database (DB) and IMS Transaction Manager (TM) applications to be migrated to open systems, modernized, and deployed. This includes:
  • Analysis, development, debug, and testing tools
  • An IMS TM- and IMS DB-compatible production level environment that enables migrated COBOL/IMS applications to be deployed on Linux, UNIX, or Windows platforms with virtually no code changes
We provide several tools from within the Enterprise Developer and Enterprise Server IDEs to build IMS components, and to create, load, and test IMS databases. Many of these tools are also available as command-line tools and some can be executed through a JCL interface. These include utilities that:
  • Generate MFS, PSB, and DBD sources
  • Load, unload, and initialize IMS Databases
  • Rebuild corrupt IMS Databases
  • Create image copy IMS Databases
  • Recover IMS Databases
  • Enable you to edit an IMS database, verify and browse IMS data, test DLI calls, and create test data
Tip: To become familiar with the process of developing an IMS application, we recommend that you follow the procedures presented in the IMS: Tutorial topics.
  • Migrating Existing IMS Applications
    Describes the procedure you should use to migrate your IMS applications from the mainframe to Enterprise Server and lists issues you might encounter while doing so.
  • ASCII/EBCDIC Conversion Issues
    A discussion of issues that might arise concerning ASCII and EBCDIC conversion when executing IMSDBU commands or running online transactions.
  • MFS Double-byte Character Set (DBCS) Support
    Describes support for double-byte character sets (DBCS) and mixed data in static literals and in input and output fields.
  • IMS Projects
    Describes the components of an Enterprise Developer IMS project.
  • IMS Generation
    Describes the generation process and output for DBD, PSB, and MFS files.
  • Exit Routines
    Describes the exit routines available for IMS applications.
  • IMS Database Tools
    Describes the tools available for creating, accessing, and testing IMS databases.
Parent topic: IMS Support
Related concepts
Tutorial: IMS Support


Migrating Existing IMS Applications

If your goal is to move an IMS application off of your mainframe and run it in a local area network environment, you should follow the procedure outlined in this section to ensure that you download all of the relevant files and that you are familiar with the further work necessary to prepare the application to run in a LAN production environment.

Migration Procedure

The following is a summary of the migration procedure. For specific instructions on any phase of the migration, see the topics referenced below.

  1. On the mainframe, unload the IMS database
  2. Download the unload database and IMS source files from your mainframe to your local machine
  3. Create an Enterprise Developer project
  4. Add downloaded IMS source files to the new project
  5. Build the project, generating all PSB, DBD, and MFS database files
  6. Load the generated IMS database from the downloaded sequential file created when you unloaded the IMS database on the mainframe
  7. Create and configure an enterprise server instance to run your IMS application
  8. Export IMS transaction definitions from the downloaded IMS Stage 1 file
  9. Import IMS transaction definitions into your Enterprise Developer project
  10. Deploy the application to the enterprise server instance for testing
  • Unload an IMS Database
    Describes the process of unloading an IMS database on the mainframe in preparation for migration to Enterprise Developer.
  • Download IMS Files
    Describes the mainframe files you must download for IMS database migration.
  • Create an IMS Project
    Describes the project specifications for a migrated IMS application.
  • Build the IMS Project
    Describes the process of building a migrated IMS application in Enterprise Developer.
  • Load the IMS database
    Describes the process of loading a migrated IMS database.
  • Create an IMS-enabled Enterprise Server
    Describes the requirements for an IMS-enabled enterprise server.
  • Export IMS Transactions
    Describes exporting the IMS transactions contained in the downloaded stage 1 file.
  • Import the Transaction File
    Describes the process of importing transaction definitions.
  • Deploy and Run the IMS Application
    Points you to documentation that provides full information on deploying and running a migrated IMS application.
Parent topic: Developing IMS Applications
Related concepts
MFS Conversion Issues
Database Load Conversion Issues
Related tasks
To define the MFS null character
To define how MFS attributes are coded


Unload an IMS Database

You must unload the IMS database into a sequential file as follows:
  • The file must contain variable-length records
  • Each record must contain one segment
  • Each record must contain the record length, segment name, and segment data in fixed positions
We recommend that you use one of the following methods to unload the database:
Standard IBM unload utility for IMS/ESA
The standard IBM unload utility creates a sequential file with a variable-length record for each segment. In each record, the segment name begins in position 7 and the segment data begins in position 36. In this case, you must use either VRECGEN or Micro Focus Mainframe Access to download the file in order to preserve record length data.
Micro Focus IMSDBUV utility
The IMSDBUV utility enables you to unload an IMS database into a segment layout that provides for simpler loading of the migrated database. The physical characteristics of the file and data are stored in header and trailer records in the file. This includes items such as the placement of the segment name, segment data, and compression options.
The IMSDBUV utility is provided as a COBOL program file, IMSDBUV.CBL, and JCL, IMSDBUV.JCL. Both files are located in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples (Windows) or $COBDIR/demo/Mainframe/IMS/Classic/Examples (UNIX) directory by default.
Note: We also supply the IMSDBUC.CBL compressed program in the same directory.

The IMSDBUV program executes as a BMP or stand-alone DLI program using an application PSB. The IMSDBUV JCL contains sample JCL for running this program. It retrieves segments from a database. For each segment, it creates a variable-length record containing record length, segment name, and segment data.

We provide several options when using the IMSDBUV utility. For example, you can optionally:
  • Use the IMSDBUC.CBL compression program in conjunction with IMSDBUV.CBL
  • Add information such as the compression routine used
  • Decompress input and compress output files on a PC platform via the provided CBLDCIMS routine
  • Write a program to perform different segment encoding on a PC platform, enabled using the COMPRESS directive

Complete instructions for using the IMSDBUV utility are contained in the IMSDBUV.CBL file. The basic process is as follows:

  1. Transfer the IMSDBUV.CBL, IMSDBUV.JCL, and optionally the IMSDBUC.CBL files to your mainframe.
  2. Compile IMSDBUV.CBL on your mainframe.
  3. Edit the IMSDBUV.JCL, replacing the embedded question marks (?) with your system information.
  4. Run the compiled code via IMSDBUV.JCL.

When you use IMSDBUV, you can download the generated file using any download utility, such as FTP, to perform a binary download.

Third-party unload utility
You can use a third-party unload utility provided it generates an output file that meets the migration requirements. In this case, you must use either VRECGEN or Micro Focus Mainframe Access to download the file in order to preserve record length data.
Parent topic: Migrating Existing IMS Applications
Related concepts
IMS Database Utility (IMSDBU)


Download IMS Files

Download the following mainframe files to your local machine:
  • The unloaded IMS database sequential file
  • IMS application files, including all:
    • COBOL source files
    • Copybook files
    • PSB source code
    • DBD source code
    • MFS source code
    • IMS stage 1 definition file containing transaction definitions
    Important: When downloading COBOL and MFS source code, be sure to account for special characters. For example, the IBM mainframe 'not sign' relational operator for logical paging conditions is not on the PC keyboard, and therefore requires special handling. You might need to manually fix some characters using a text editor.
  • Assembler programs and exits (optional), which can be used for development and testing, but must be rewritten in COBOL for production
Parent topic: Migrating Existing IMS Applications
Related concepts
ASCII/EBCDIC Conversion Issues
Related reference
mfims stage1ext command
mfims tranexp command


Create an IMS Project

After downloading your IMS files, create a project in Enterprise Developer using the Mainframe Subsystem project template; then add the following downloaded components to the project:
  • COBOL source files
  • Copybook files
  • PSB source code
  • DBD source code
  • MFS source code
  • IMS stage 1 definition file containing transaction definitions
  • Assembler programs and exits (optional)

Set the following project properties:

Parent topic: Migrating Existing IMS Applications
Related concepts
IMS Projects
Related tasks
To set IMS project properties


Build the IMS Project

When you build the IMS project, Enterprise Developer compiles the COBOL code, generates all PSB, DBD, and MFS, and adds the compiled and generated files to the project.

Parent topic: Migrating Existing IMS Applications
Related concepts
IMS Generation


Load the IMS database

After building your IMS project, you are ready to load your IMS database using your DBD and generated .dat files.
  1. From the Enterprise Developer IDE COBOL Explorer, right-click a DBD in your project; then click Database Utilities > Load.
  2. In the Load IMS database dialog box, specify the .dat file to use in the Input/Output file name field.
  3. Set the correct File layout and any other settings as required, and click OK.
Parent topic: Migrating Existing IMS Applications
Related concepts
IMS Database Utility (IMSDBU)
Related tasks
To load an IMS database
Related reference
Load function


Create an IMS-enabled Enterprise Server

Before you can deploy and run your migrated IMS application, you must create an enterprise server on which to run it. Minimally, the enterprise server should be configured as follows:
  • Enable MSS
  • Enable CICS and JCL support if needed
  • Enable IMS support
Note: For complete information on configuring an enterprise server, see Creating and Configuring an Enterprise Server Instance for IMS .
Parent topic: Migrating Existing IMS Applications
Related concepts
Creating and Configuring an Enterprise Server Region for IMS
Related tasks
To create an MSS-enabled enterprise server for IMS applications from Enterprise Server
To enable IMS for an MSS-enabled enterprise server


Export IMS Transactions

To create a transaction file from your downloaded stage 1 file:
  1. Open an Enterprise Developer command prompta command prompt.
  2. Change to the directory that contains your downloaded stage 1 file.
  3. Enter the following:
    mfims stage1ext stage1file transactionfile
    where:
    stage1file | The stage 1 file downloaded from the mainframe.
    transactionfile | The name of the transaction file to be created.

    The transaction file is created in the current directory.

Parent topic: Migrating Existing IMS Applications
Related concepts
Import the Transaction File
Related tasks
To export IMS transactions
Related reference
mfims stage1ext command
mfims tranexp command


Import the Transaction File

Transaction definitions are added your Enterprise Developer project by importing them from your exported transaction file into a compiled project component file named IMSGEN2.DAT. This file is created automatically during the import process, or if imsgen2.dat already exists, the transaction definitions contained in your transaction file are added to it during the import process.

  1. Open an Enterprise Developer command prompt.
  2. Change to the directory that contains your transaction file.
    Note: If you want to import into an existing imsgen2.dat file, be sure that either the transaction file and the imsgen2.dat file are in the current directory, or that you have set the ES_IMSLIB environment variable to point to the location of the imsgen2.dat file.
  3. Enter the following:
    mfims stage1imp transactionfile [ADDREPL] [DELEXIST]

    where:

    transactionfile | The transaction file created from a stage 1 file or from Enterprise Server.
    ADDREPL | If the imsgen2.dat already exists, specifies adding new transactions and replacing existing transactions. If you do not specify ADDREPL, new transactions are added but existing transactions are left unchanged.
    DELEXIST | If the imsgen2.dat already exists, specifies that all the existing transaction definitions in the imsgen2.dat file be deleted before importing extracted transactions.
Parent topic: Migrating Existing IMS Applications
Related concepts
Export IMS Transactions
Related tasks
To import IMS transactions
Related reference
mfims stage1imp command


Deploy and Run the IMS Application

The deployment process for a migrated IMS application is the same as any IMS application developed in Enterprise Developer. For complete information on deploying and running a migrated IMS application, see Deploying IMS Applications.

Parent topic: Migrating Existing IMS Applications
Related concepts
Deploying IMS Applications
Database Load Conversion Issues


ASCII/EBCDIC Conversion Issues

When source modules – including COBOL programs, MFS, and DBD source – contain hexadecimal values, you must take special care to avoid problems that could occur when executing IMSDBU commands or running online transactions.

  • MFS Conversion Issues
  • Database Load Conversion Issues
Parent topic: Developing IMS Applications
Related concepts
Download IMS Files


MFS Conversion Issues

Some issues you might encounter with regard to MFS include but are not limited to:

MFS null character

Issue

On the mainframe, the MFS null character, which is used to truncate fields, is defined as x'3F'. In an IMS-enabled enterprise server, the MFS null character defaults to x'1A', which is the ASCII equivalent of x'3F'.

Resolution

You can change the MFS null character to another character or hex value by editing the enterprise server instance in Enterprise Server Administration and specifying the value in the MFS null character field on the Server, Properties, MSS, IMS, TM tab.

Important: If you change the null character, and your programs downloaded from the mainframe check for x'3F', update the program code to check for the new null value instead.
MFS attributes

Issue

If you have used character literals to specify the values of MFS attributes, the resulting values will be different when you compile using ASCII from those that you obtain when compiling using EBCDIC. For example, the two code fragments below give the same results when compiling with the EBCDIC character set. When using ASCII, however, the first example will give different behavior: '{A' now translates as hexadecimal 7B41 rather than C0C1.

Attributes specified using character literals:

05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR          PIC X(2) VALUE '{A'.
   10 ERROR-ATTR           PIC X(2) VALUE '{I'.
   10 OK-ATTR              PIC X(2) VALUE ' A'.
   10 PROT-ATTR            PIC X(2) VALUE ' 1'.

Attributes specified using hexadecimal/binary notation:

05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR          PIC X(2) VALUE X'C0C1'.
   10 ERROR-ATTR           PIC X(2) VALUE X'C0C9'.
   10 OK-ATTR              PIC X(2) VALUE X'00C1'.
   10 PROT-ATTR            PIC X(2) VALUE X'00F1'.

Resolution

To facilitate the migration of programs, you can specify at the level of the transaction or the system whether MFS attribute values have been coded using character or binary notation. (The value specified for the transaction definition overrides that for the system.)

Where you specify that the attribute values have been coded as character literals, Enterprise Server automatically translates the values of MFS attributes to those that would be used if the program were compiled as EBCDIC. For example, the hexadecimal 7B41 value produced by assigning '{A' to an attribute and compiling with ASCII, is converted to the correct C0C1 value. Where you specify attribute values as binary data, Enterprise Server takes no action.

As an alternative solution, edit your programs to use x'nn' notation (as used in the second example above) instead of characters.

MFS fill characters

Issue

In MFS source, input fill characters are specified in hex notation. For example:
MFLD  HEX102,LTH=030,FILL=X'DF'
Enterprise Server automatically converts those values to EBCDIC at run time, but your COBOL programs examine the field for X'DF'.

Resolution

To maintain the hexadecimal value of the fill character, i.e., do not convert it, you must generate the MFS using the HEXFILL directive. See HEXFILL for more information.

Parent topic: ASCII/EBCDIC Conversion Issues
Related concepts
Migrating Existing IMS Applications
Related tasks
To define the MFS null character
To define how MFS attributes are coded


Database Load Conversion Issues

Pay particular attention to DBD statements that specify hexadecimal values as they can cause trouble when loading an IMS database using the Load function.

Issue

Some statements contain conditions that are dependent upon a hexadecimal value, but that hexadecimal value is converted from EBCDIC to ASCII when loading the database.

In this example, a NULLVAL parameter on an XDFLD statement defines a secondary index using a hexadecimal value, and suppresses the creation of the secondary index when the value of the index key contains the hexadecimal value. For example:

XDFLD NAME=STREX013, SEGMENT=, NULLVAL=X'40',

When loading the database and converting the data from EBCDIC to ASCII, fields containing x'40' are converted to x'20'. Subsequently, the Load function could attempt to insert multiple segments with a key value of x'20', resulting in duplicate key values and causing the insert to fail. However, the intent of the statement is to suppress creation of index segments.

Resolution

To resolve this problem, change the hexadecimal value to its converted ASCII equivalent. For example:

XDFLD NAME=STREX013, SEGMENT=, NULLVAL=X'20',

Then, compile the DBD source and load the database using the Load function.

Parent topic: ASCII/EBCDIC Conversion Issues
Related concepts
Deploy and Run the IMS Application
Migrating Existing IMS Applications
Related tasks
To load an IMS database
Related reference
Load function


MFS Double-byte Character Set (DBCS) Support

In static literals and in input and output fields, Micro Focus IMS MFS supports double-byte character sets (DBCS) on their own, and also mixed data consisting of double- and single-byte characters.

MFS Code

For each literal and field that contains DBCS data only, specify the extended attribute EATTR=EGCS.

For each literal and field that contains mixed data that includes both DBCS and single-byte characters, specify the extended attribute EATTR=MIX.

For example:

FLD0001  DFLD  LTH=0008,POS=(02,02),ATTR=(NUM,PROT,MOD),
               EATTR=EGCS
         DFLD  'Double- and Single-byte Literals',X
               POS=(02,12),ATTR=HI,EATTR=MIX
Important: When editing MFS source containing DBCS data:
  • Use an editor that specifically supports ASCII Shift-JIS DBCS encoding. If you edit your MFS code in UTF-8 editing mode, the editor could automatically replace all Shift-JIS DBCS characters with the ASCII question mark (?) character (default Unicode substitution character). This automatic substitution could cause irrevocable corruption to the MFS file.
  • Do not enclose DBCS data in Shift Out/Shift In (SO/SI) characters as these are inserted as required during MFS generation.

MFS Generation

To generate MFS that contains DBCS data, specify the CBEGCS directive when executing mfims mfsgen. See CBEGCS for details.

Restrictions

MFS DBCS in Enterprise Developer does not support the following:

  • Continuation of DBCS or mixed data MFS literal strings, meaning that these strings cannot span multiple lines in an MFS file.
  • Dynamically changing the extended attribute (EATTR) that specifies the type of data. This means that you cannot dynamically change a double-byte field into single-byte field, and vice versa. This does not apply to any other extended attributes for double-byte or mixed fields, which can be modified as usual.
Parent topic: Developing IMS Applications


IMS Projects

When you create an Enterprise Developer project for an IMS application, you use the provided Mainframe Subsystem Application template. This creates the necessary infrastructure that enables the application to run on an enterprise server as if the application were running on an actual mainframe.

Once you have created the project, you then configure it as an IMS application by setting appropriate project properties.

You then create objects (items) for or add objects to the project, including programs, copybooks, MFS screens, PSBs, and DBDs.

From the Enterprise Developer project, you continue developing the application using the provided program/code editor. You can also compile all or part of the application, generate DBDs, PDBs, and MFS files, and deploy the application.

  • IMS Project Components
    Describes the components of an IMS project in Enterprise Developer.
  • IMS Project Properties
    Describes the types of properties you can set for IMS projects.
  • Building an IMS Project
    Describes the build process for an IMS project.
  • IMS Database Features
    Describes the IMS database features available from an Enterprise Developer IMS project.
Parent topic: Developing IMS Applications


IMS Project Components

The components of an IMS project in Enterprise Developer consist of files you create or add to the project manually, and files generated when you build the project.

You should add the following existing IMS components to a new Enterprise Developer project, or create them in Enterprise Developer:
  • COBOL program(s)
  • Copybooks included by the COBOL program(s)
  • PSBs
  • DBDs
  • MFSs
You can optionally add the following files to your project:
  • .dbu file - Data from an unloaded IMS database, created using the IMSDBU unload command.
  • dbdname.dat - An IMS database file.
After building an IMS project, Enterprise Developer adds some or all of the following generated files to the project, depending on your project property settings and the component types in the project. Some of the files are runtime files needed to execute a transaction, and some are informational files, such as listing files. The location of these files is determined by the settings specified in your project properties:
Runtime Files
Runtime files required to execute IMS transactions:
  • .dll or .exe - Compiled form of a COBOL program.
  • psbname.acb - Compiled form of a PSB.
  • dbdname.acb - Compiled form of a DBD.
  • psbgen3.dat - An index file generated from PSBs in the project, specially formatted for faster runtime execution. It can contain one or more PSB members.
  • dbdgen2.dat, and dbdgen2f.dat - An index file generated from DBDs in the project, specially formatted for faster runtime execution. It can contain one or more DBD members.
  • imsgen2.dat - Compiled form of the IMS transaction definitions.
  • .mid, .mod, .dif and .dof - Generated MFS files.
Note: To successfully run a deployed IMS application in Enterprise Server, you must set the ES_ACBLIB, ES_IMSLIB, and ES_MFSLIB environment variables to point to the directories that contain your runtime files. See IMS-Specific Environment Variables for more information.
Informational Files
These files are not required for running transactions. They contain information about generated files.
  • .lst - information from PSB, DBD, and MFS generation.
  • .mfsx - Lists all of the MFS runtime files, .mid, .mod, .dif and .dof, created during MFS generation.
Other Files
.tlog - Log files created when IMS Forward Recovery has been enabled. You must preserve these files to successfully execute an IMS Forward Recovery.
Parent topic: IMS Projects
Related concepts
Building an IMS Project
IMS Database Forward Recovery
Related reference
IMS-Specific Environment Variables


IMS Project Properties

The project properties you set determine the output generated when you build the project. For an IMS application, in addition to the generic project properties, you can set the following IMS-specific properties:
  • Location of generated output files
  • Build settings for MFS, DBDs, and PSBs

As part of the build settings for MFS, DBDs, and PDBs, you can specify directives to customize the output. For more information on IMS directives, see mfims directives.

For detailed information on each field and control that appears on the IMS properties pages, see the reference topics listed below.

Parent topic: IMS Projects
Related tasks
To set IMS project properties
To set project and file properties for .DBD, .MFS or .PSB source files
Related reference
mfims generation directives


Building an IMS Project

When you build an IMS project, Enterprise Developer:
  • Compiles COBOL programs and copybooks
  • Generates MFS files, DBDs, and PSBs
  • Generates other support files required for deploying the application, and adds them to the project
  • Generates and adds informational files to the project
Note: For a description of the files generated when you build an IMS project, see IMS Project Components.
Parent topic: IMS Projects
Related concepts
DBD Generation
PSB Generation
MFS Generation
IMS Project Components


IMS Database Features

Describes the IMS database features available from an Enterprise Developer IMS project.
IMSDBU Functions
IMS support in Enterprise Developer provides a database utility tool, IMSDBU, that you can access from your IMS project. You can perform the following IMSDBU functions from the Enterprise Developer IDE:
Load
Initializes a database and loads it from an input data file.
Unload
Writes database segment data to a sequential output file.
Zeroload
Create database data files and prime them for use.
Add
Add to or refresh segments in a database from an input data file.

Several additional IMSDBU functions are available from the command line and from the JCL interface. See mfims imsdbu Command and IMSDBU JCL Interface for more information.

IMS Database Editor
You can also access the IMS Database Editor from your Enterprise Developer project. The IMS Database Editor provides a graphical interface for viewing and manipulating data in an IMS database.
Parent topic: IMS Projects
Related concepts
IMS Database Utility (IMSDBU)
IMS Database Editor
Related reference
mfims IMSDBU


IMS Generation

DBD, PSB, and MFS files are generated automatically when you build your project from the Enterprise Developer IDE. You can also generate from the command line using the mfims command.

DBD, PSB, and MFS generation each produces a specific set of output files as explained in the following topics:

  • DBD Generation
  • PSB Generation
  • MFS Generation
Parent topic: Developing IMS Applications
Related concepts
Build the IMS Project
Related reference
mfims Generation


DBD Generation

To generate DBDs:
  • Add them to your project and then build the project from the IDE (Windows).
  • Open an Enterprise Developer command prompt and execute the mfims dbdgen command (UNIX).

Generating a DBD updates the following files:

  • dbdname.acb
  • dbdgen2.dat
  • dbdgen2f.dat

These files contain DBD source information that has been extracted and formatted into a smaller structure optimized for faster access during execution. The .dat files files are indexed files and can contain one or more generated DBD members.

The dbdgen*.* and dbdname.acb files are created in the directory specified in your project properties, on the IMS tab in the Generated files field. If no directory is specified there, the files are created in the project directory.
Note: When you deploy your application to an enterprise server, you must provide the enterprise server with the location of the generated files. See To specify the location of generated files for instructions.
Parent topic: IMS Generation
Related concepts
Building an IMS Project
PSB Generation
MFS Generation
Related tasks
To specify the location of generated files
Related reference
mfims generation command
DBDGEN Directives


PSB Generation

You can generate a PSB from the IDE by building a project that contains a PSB, or you can generate a PSB using the mfims psbgen command.

Generating a PSB updates the following files:

  • psbname.acb
  • psbgen3.dat

These files contain PSB source information that has been extracted and formatted into a smaller structure optimized for faster access during execution. psbgen3.dat is an indexed file and can contain one or more generated PSB members.

The psbgen3.dat and psbname.acb files are created in the directory specified in your project properties, on the IMS tab in the Generated files field.
Note: When you deploy your application to an enterprise server, you must provide the enterprise server with the location of the generated files. See To specify the location of generated files for instructions.
Parent topic: IMS Generation
Related concepts
Building an IMS Project
DBD Generation
MFS Generation
Related tasks
To specify the location of generated files
Related reference
mfims generation command
PSBGEN Directives


MFS Generation

To generate MFSs:
  • Add the MFS files to your Enterprise Developer project; then build the project (applies to Windows environments only).
  • Open an Enterprise Developer command prompt and execute the mfims mfsgen command (all platforms).

When you compile an IMS project, Enterprise Developer generates .mid, .mod, .dif and .dof files, which are analogous to those created on a mainframe. However, in Enterprise Developer, the .dif and .dof files do not generate hexadecimal file names. Instead, they generate character-based file names. In addition, the file mfsname.mfsx is generated and used by Enterprise Developer to control build dependencies.

All files are created in the current directory, or when specified, in the folder specified in the MFS Path field on the IMS tab in your project properties.

Parent topic: IMS Generation
Related concepts
Building an IMS Project
DBD Generation
PSB Generation
Related tasks
To specify the location of generated files
Related reference
mfims generation command
MFSGEN Directives


Exit Routines

Enterprise Developer and Enterprise Server support several IMS exit routines that enable you to customize your applications.

Note: Exit routines load and execute in the application address space, effectively becoming part of the application. For example, if 10 active applications, each executing in MPRs, or with JES initiators, etc. and each calling the same exit routine, results in 10 active copies of the same exit routine. These exit routines do not share memory with each other, and execute fully isolated from each other.
  • MFS Input Message Exits
    Describes the use of MFS input message segment exits and input message field exits.
  • MFSGEN Preprocessor Exit
    Enables you to make changes to MFS source using a COBOL program.
  • IMS Data Capture Exits
    Describes the use of IMS data capture exits.
  • IMS Print Exit
    Describes use of IMS print exit functionality.
  • IMS Sparse Index Exits
    Describes support for IMS sparse index exits.
  • IMS Non-discardable Messages Exit
    Handles input messages associated with abended IMS application programs.
  • IMSDBU Exits
    Describes the IMS Database Utility (IMSDBU) exits.
Parent topic: Developing IMS Applications


MFS Input Message Exits

Enterprise Server supports the use of MFS input message field and segment exits in COBOL, and enables you to edit MFS segment and field data from a COBOL program. This is an emulation of a mainframe feature.

Invocation
MFS input message exits are invoked automatically at run time.
Coding Requirements
MFS input message exits are specified using standard MFS syntax. To include MFS input message segment and field exits in IMS applications, follow these coding standards:
  • Write all input message segment and field exits in COBOL. This is different from IMS/ESA, where segment and field exits are written in Assembler.
  • Use the IMS/ESA naming convention as follows:
    DFSMEnnn
    Where nnn is the exit number expressed as a three-digit decimal number from 000 through 127. For example, for field exit number zero, use the name DFSME000.
  • Segment and field exits receive ASCII data. If the exit program is written for EBCDIC, it must also convert the IMS data it receives in ASCII from ASCII into EBCDIC, and convert the data from EBCDIC back to ASCII before exiting.
  • Be sure that segments are not modified such that they are rendered invalid. Invalid segments can cause runtime errors.
  • Do not use an exit to invoke IMS callable services, including storage services and control block services.
Note: If an MFS source references an exit that does not exist, the program behaves as if there were no exit coded in the MFS. Exception conditions returned by the exit are written to the server console log.
Run-time Requirements
The following are run-time requirements for IMS segment and field exits:
  • Compile all segment and field exits.
  • Place the compiled code in the directory specified by the ES_IMS_EXITPATH environment variable or, alternatively, in the directory specified by the COBPATH environment variable. Enterprise Server searches for segment and field exits in that order and uses the first matching exit found.
Run-time Behavior
The following describes the run-time behavior for IMS segment and field exits.
  • As the enterprise server is started, the names of the exits found are written to the server console log. For example, the following represents a typical server console log entry:
    120131 13172725 4684 IMSTEST CASTM5044I IMS TM exit programs loaded:
DFSME000.dll, DFSME127.dll 13:17:27
  • For input message field exits, the parameter list format passed to the exit has the same format as that passed by IMS/ESA.
  • For input message segment exits, the parameter list format passed to the exit has the same format as that passed by IMS/ESA with the exception of an extra field, DFSME-R1-RETURN, at the end of the control block. DFSME-R1-RETURN contains a user-defined error message number when the segment exit issues a return code of 12, canceling the message.
  • We do not support segment exit return code 16. A segment that returns a value of 16 does not send a message to the input device.
Examples
The sample segment and field exits provided are supported only for MFS source that uses the option 1 and 2 formats. All sample files are located in %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples (Windows) or $COBDIR/demo/ims/examples (UNIX) by default.
Field Exit Routine
We provide a sample program, DFSME000.cbl, containing a field exit routine. It is a COBOL implementation of the DFSME000 Assembler MFS field edit exit routine provided with the IMS/ESA product. This program contains comments further describing the use of input message field exits. The following is an excerpt from the Linkage Section of DFSME000.cbl, showing the parameter list format:
       01  FIELDEXIT-PARMS.
           05  FLDFLAG             PIC  X(01).
           05  FILLER              PIC  X(01).
           05  FLDELTH             PIC  X(01) COMP-X.
           05  FLDVECT             PIC  X(01) COMP-X.
           05  FLDLTH              PIC  X(04) COMP-X.
           05  FLDADDR             USAGE POINTER.
Segment Exit Routine
We provide a sample program, DFSME127.cbl containing a segment exit routine. It is a COBOL implementation of the DFSME127 Assembler MFS segment edit exit routine provided with the IMS/ESA product. The following is an excerpt from the Linkage Section of DFSME127.cbl, showing the parameter list format:
       01  DFSME-PARM.
           05  DFSME-FLAG              PIC X(01).
           05  FILLER                  PIC X(01).
           05  FILLER                  PIC X(01).
           05  DFSME-VECTOR            PIC X(01)   COMP-X.
           05  DFSME-LTH               PIC X(04)   COMP-X.
           05  DFSME-ADDR              POINTER.
           05  DFSME-FLDEXIT-RC        PIC X(04)   COMP-X.
           05  DFSME-NEXT-MODNAME      PIC X(08).
           *>  NEXT FIELD IS IN COBOL PARM BLOCK ONLY
           05  DFSME-R1-RETURN         PIC X(04)   COMP-X.
Troubleshooting
Segment and field exits can generate trace entries that are useful for troubleshooting.
Enabling Trace
You enable the generation of segment and field exit trace entries from Enterprise Server Administration as follows:
  1. From the Enterprise Server Administration Home page, start the enterprise server that runs your application.
  2. Click Edit for the started enterprise server.
  3. Click Server > Control > ES Monitor & Control.
  4. Click Control.
  5. Under Trace Points > Server, check exits.
Viewing Trace Entries
MSS writes trace information for Trace diagnostics A and B datasets to the files casauxta.rec and casauxtb.rec respectively. By default, both are located in the System directory, %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\es-name (where es-name is the name of the enterprise server). However, you can view trace entries in real time, including C/x trace information, by clicking Display.
Trace IDs
Trace entries are generated in entry and exit pairs using six-digit hexadecimal IDs as follows:
  • Digits one and two are 39. These indicate that the entry is for MFS.
  • Digits three and four are unique to the emitting source module.
  • Digit five is a 0 (zero).
  • Digit six indicates the type of trace entry, as follows:
    3 | entry
    4 | exit
    9 | error
The following lists MFS trace IDs along with their significance and the variable content of each.
x'390103', Segment exit entry, exit number, vector
x'390204', Segment exit exit, return code, segment number
x'390303', Field exit entry, exit number, vector
x'390404', Field exit exit, return code, max return code
x'390509', Segment exit missing, exit number, intended vector
x'390609', Field exit missing, exit number, intended vector
Example
In this example, the first field exit is for exit number 100 and vector 100. However, Enterprise Server has failed to load the module. In this case, the error is simply recorded and processing continues. The second trace entry reveals that exit 5 was given control for vector 5. The third trace entry records the return code and the running maximum return code for the field exits at the return of exit 5. Processing continues on to the next to the last trace entry where segment exit 126 is called with vector 14. The return from the segment exit is 0 (zero) and the current segment is 1.
Note: In trace output, the trace ID includes a prepended "39 " indicating that the entry is from casmfs.dll, and digit five is shown as 8 instead of 0 (zero).
                                  Seq  Task-Nbr  ProcessID +---ID--+ hhmmsshh
mfsFldExitER(  100 )v(   100 )    654      6652      12312 39 390689 22105958
mfsFldExit(      5 )v(     5 )    655      6652      12312 39 390383 22105958
mfsFldExitRC(    0 )max(   0 )    656      6652      12312 39 390484 22105958
mfsFldExit(      5 )v(     1 )    657      6652      12312 39 390383 22105958
mfsFldExitRC(    8 )max(   0 )    658      6652      12312 39 390484 22105958
mfsFldExit(      5 )v(     1 )    659      6652      12312 39 390383 22105958
mfsFldExitRC(    0 )max(   8 )    660      6652      12312 39 390484 22105958
mfsFldExit(      5 )v(     1 )    661      6652      12312 39 390383 22105958
mfsFldExitRC(    0 )max(   8 )    662      6652      12312 39 390484 22105958
mfsSegExit(    126 )v(    14 )    663      6652      12312 39 390183 22105958
mfsSegExitRC(    0 )seg(   1 )    664      6652      12312 39 390284 22105958
Parent topic: Exit Routines


MFSGEN Preprocessor Exit

The MFSGEN preprocessor is available only in Micro Focus COBOL development systems. It enables you to make changes to MFS source using a COBOL program.

Invocation
Invoked during MFS generation by specifying:
mfims mfsgen filename.mfs PREPROCESS(exitname)
where filename is the name of an MFS file, and exitname is the name of a COBOL program.
Example
Enterprise Developer provides a sample MFSGEN Preprocessor exit, MFSPREPR.cbl, which is located by default in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples (Windows) or $COBDIR/demo/ims/examples (UNIX) directory.
Parent topic: Exit Routines


IMS Data Capture Exits

Data capture exits enable updates to segments in a DL/I database to be passed to a data capture exit program. Mainframe IMS provides these exits to propagate data to DB2, commonly using the IBM Data Propagator product. Data Propagator takes the data capture exits and uses them to propagate data to DB2. You can also write your own data capture exits to perform propagation or other functions.

This is an emulation of a mainframe feature.

Invocation
Data capture exits are invoked at run time when a change or changes occur on a segment for which the exit routine is defined. You specify a data capture exit in one of two ways:
  • In JCL when invoking the DBD, using EXIT=exitname
  • In DBD source, using SEGM=exitname

Data capture is enabled by default. Therefore, if the database has exits defined, they are executed automatically.

Important: Be sure that all defined data capture exits are present. However, if your DBD source contains one or more data capture exits that are not needed to support a migrated application or not required for offload testing, you can do one of the following to prevent them from executing:
  • Remove all unneeded data capture exits from the DBD source and recompile.
  • Recompile using the mfims dbdgen command with the NODCX directive. This prevents Enterprise Server from loading any data capture exit routines specified in the DBD source. Use this option when none of the data capture exit routines in your DBD source are required, for example, during offload testing. This enables you to test without modifying your DBD source. See NODCX for details.
Coding Requirements
Enterprise Server supports the use of IMS data capture exits in COBOL coded using the specifications in the IBM mainframe IMS documentation, except as noted in this documentation; however, Enterprise Server does not support IBM Data Propagator functionality. See the IBM Web site for access to IBM documentation.
Note: We do not require that you compile or assemble all of the exits defined in your DBDs. Simply download the exits required by your application. If the runtime cannot locate a specific exit program, it writes a message to the console log and continues as if the exit were not defined in the DBD.
Use the following as guidelines when coding data capture exits:
  • Enterprise Server supports:
    • Data capture exits written in COBOL.
    • A maximum of nine exit routines for any one DBD segment, with no limit on the total number of data capture exits defined for all segments in a DBD.
    • All fields in the XPCB and XSDB parameter blocks, with appropriate actions for all XPCB return codes.
    • Databases that use logical relationships. In these, segment deletes can cascade across a maximum of 32 nested hierarchical relationships and up to a maximum of 99 segment levels.
    • Data capture exit programs that make DL/I calls to any PCB defined in the currently active PSB.
  • One IMS application region supports a maximum of 256 active exit routines. This means that you can define any number of exits in the DBDs referenced by PSBs; however, updates to segments cannot cause more than 256 exits to be called. An exit becomes active as its corresponding database segment is updated and calls the exit.
  • Data capture exits support the following operands:
    EXIT
    Supported for both DBD and SEGM statements with the following options:
    • KEY
    • DATA
    • PATH
    • CASCADE, including the KEY and DATA sub-options
    Note: Enterprise Server does not support the CASCADE PATH sub-option or the LOG option, meaning that data capture log records are not written to disk and therefore are not available for asynchronous processing.
    VERSION
    Supported for the DBD statement. The XPCB parameter block points to the value of the VERSION operand. The maximum length of the VERSION value is 128 bytes (after any substitution). If no VERSION operand is specified, a default 13-byte date-time stamp is generated. The &SYSDATE and &SYSTIME substitutable variables are also supported.
Run-time Behavior
The following describes the run-time behavior expected for data capture exits:
  • Data capture exits are called from all IMS application region types, including BMP and DL/I regions as well as CICS and the IMS Dynamic Database Attach (DDBA) region type.
  • We follow standard rules for the calling sequence of exits. This includes calling the exit multiple times, if necessary for path calls, in a top-down order. Exits are called in a bottom-up sequence for cascaded deletes.
  • Unlike mainframe IMS, we do not perform before- and after-image segment compare during replace operations. Replace calls always cause the segment to be updated, even if the data was not changed, meaning that we always call data capture exits for a replace call whether or not the data was modified.
  • If you compile the data capture exit program for debugging, it is shown by the respective debugger when the exit is called.
  • XPCB return codes of 8 or greater are recorded in the Enterprise Server console log.
Parent topic: Exit Routines
Related reference
NODCX


IMS Print Exit

IMS Print Exit functionality enables data otherwise destined for a printer to be redirected to the DFSPRINT exit routine.

Invocation
The print exit is invoked at run time.
Coding Requirements
To enable a print exit requires that you code an exit program named DFSPRINT, and also that you code an interface to DFSPRINT from your IMS COBOL program.
DFSPRINT
To enable the print exit functionality, you must code and build a module named DFSPRINT, and place the resulting executable in the directory specified by the ES_IMS_EXITPATH environment variable. Micro Focus provides a very basic DFSPRINT.cbl file to help you get started. DFSPRINT.cbl resides in your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits directory by default.
Important: The DFSPRINT print exit routine must be thread-safe.
Interface
Include the following interface in the Linkage-Section of your DFSPRINT program. The contents of this interface are sent to the DFSPRINT module:
01 print-exit-interface.
   03 data-destination     pic x(8).
   03 data-pending         pic x comp-x.
      88 more-to-come-88   value 1 false 0.
   03 page-count           pic x(4) comp-5.
   03 page-array-ptr       pointer.
01 page-array.
   03 page-data occurs 50 times depending on page-count.
      05 page-data-ptr     pointer.
      05 page-data-length  pic x(4) comp-5.
Field | Contents
data-destination | The name of the destination printer
more-to-come-88 | If true, indicates that more data is to come for this print job
page-count | The number of pages in the array pointed to by page-array-ptr
page-array-ptr | Pointer to the page-array structure containing the print data
page-data-ptr | Pointer to the TN3270 data for a single page
page-data-length | The length of the data pointed to by page-data-ptr
Run-time Requirements
To enable print exit functionality, you must have the following in place:
DFSPRINT executable
The DFSPRINT executable must be in the directory specified by the ES_IMS_EXITPATH environment variable.
Enterprise Server environment variables
You must set the following environment variables in the enterprise server region that runs your IMS application:
ES_IMS_EXITPATH
Set this to point to the directory that contains your DFSPRINT executable.
ES_IMS_OTMA_DEST
Set the ES_IMS_OTMA_DEST environment variable to identify each printer destination that is specified in the application for which you want to redirect the print data to the exit routine. Each specified destination consists of the destination name, the NONOTMA keyword, and the LU type (LU1 or LU3) separated by commas. Each destination definition is separated by a semi-colon.
IMS_OTMA_DEST=printerName,NONOTMA,LUtype[;...]

Entries in the ES_IMS_OTMA_DEST environment variable are separated by semi-colons. Each entry consists of the printer destination name, the NONOTMA keyword, and the LU type (LU1 or LU3) separated by commas. For example:

ES_IMS_OTMA_DEST=IMSPRLU1,NONOTMA,LU1;IMSPRLU3,NONOTMA,LU3

Where the first printer destination specifies an LU1 printer named IMSPRLU1; and the second destination specifies an LU3 printer named IMSPRLU3.

Run-time Behavior
The following describes the run-time behavior expected when a print exit routine is present:
  • IMS calls the routine before initiating any printing. Print data is sent to the exit routine as a TN3270 data stream.
  • When DFSPRINT handles the print data, it assigns a return code of 0 (zero) to the return-code field and exits.
  • When IMS receives a return code of 0 from the exit routine, IMS bypasses normal print processing.
  • When IMS receives a non-zero return code from the exit routine, IMS handles the printing as normal.
Parent topic: Exit Routines
Related reference
Environment variables in alphabetical order
IMS-Specific Environment Variables


IMS Sparse Index Exits

Sparse index exits suppress secondary index generation. This is an emulation of a mainframe feature.

Invocation
IMS sparse index exits are invoked at run time.
Coding Requirements
When an application program issues a call of a segment serving as an index source segment for one or more indexing relationships, the DL/I index maintenance routine is invoked. Enterprise Server supports the following segment calls:
DLET
An indexing segment is built corresponding to the existing index source segment. If it passes the null value test, the index exit routine is invoked. This routine indicates whether this indexing segment should appear in the index. If it should appear, the actual indexing segment is retrieved and deleted; otherwise, no delete is attempted.
ISRT
The indexing segment is built to correspond to the segment to be inserted, and the null value test and the exit routine tests are performed. If no suppression of indexing is indicated by either, it is inserted into the index.
REPL
Can be a combination of a DLET call and an ISRT call, a simple replace, or a NOP, depending on the fields changed in the replace. If a field in the Index Source Segment (ISS) is changed by a REPL call that changes the indexed data or subsequent data, the existing indexing segment is deleted and a new one inserted. The index edit routine is invoked for each operation. If the change in the ISS affects a source data field, a replace operation on the indexing segment is executed, unless the index exit routine indicated that indexing was suppressed. If the ISS replace made no changes in the indexing segment, no action is taken.
Index Supression
The suppression of indexing by the exit routine must be consistent. The same indexing segment cannot be examined at two different times and have suppression indicated only once. If the indexing segment contains user data, this user data cannot be used to evaluate suppression, since the actual indexing segment is seen by the exit routine just before the insertion of a new one. In the cases of replace and delete, only a prototype is passed. The prototype contains the constant, indexed data, subsequence data, duplicate data, and any symbolic pointer that was added. Therefore, index suppression must not be based on any user data.

The sparse index exit routine issues a return code and indicates either that the present index pointer segment belongs in the index or that it should be suppressed. The exit routine must not change any IMS control blocks, or any fields in the indexing segment.

Example
Enterprise Developer provides a sample sparse index exit, SPARSRTN.cbl, which is located by default in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples (Windows) or $COBDIR/demo/ims/examples (UNIX) directory.
Parent topic: Exit Routines


IMS Non-discardable Messages Exit

The non-discardable messages exit routine enables you to specify to Enterprise Server how to handle an input message associated with an abended IMS application program. The exit routine receives control when an application abends with an input message in process. If a non-discardable messages exit does not exist, Enterprise Server discards the input message.

Note: Data is always passed to and from the non-discardable messages exit in ASCII.

Invocation

The non-discardable messages exit routine is invoked when an application abends while an input message is in process.

Coding Requirements

Filename and Location
You must name the exit routine program DFSNDMX0.cbl, and it must reside in the directory specified by the ES_IMS_EXITPATH environment variable.
Processing Options
The following processing options are valid:
Continue normal processing
Continue normal processing is the default option. Request this option by setting the return code to zero before returning to Enterprise Server. If you request this option, Enterprise Server proceeds as if this exit routine had not been called. Enterprise Server stops the transaction that was being processed when the application abended, deletes the input message from the system, and issues a DFS555I message to the originating terminal (if possible).
Delete the input message from the system
Request this option by setting the return code to 4 before returning to Enterprise Server. If you request this option, Enterprise Server stops the transaction that was being processed, deletes the input message from the system, and issues a DFS555I message to the originating terminal.
Move the input message to the suspend queue
Request this option by setting the return code to 8 before returning to Enterprise Server. If you request this option, Enterprise Server stops the transaction that was being processed, moves the input message to the suspend queue of the transaction, and issues a DFS555I message to the originating terminal.
Requeue the input message to the original transaction
Request this option by setting the return code to 12 before returning to Enterprise Server. If you request this option, Enterprise Server requeues the input message to the normal processing queue of the transaction that was being processed. Enterprise Server stops the transaction and issues a DFS555I message unless directed to do otherwise by the contents of the NDMTRNST field of the NDM interface block (see below).
Queue the input message to an alternate destination
Request this option by setting the return code to 16 and placing a valid destination in the NDMDEST field of the NDM interface block before returning to Enterprise Server. The alternate destination can be a transaction code or an LTERM name. If you request this option, Enterprise Server stops the transaction that was being processed, queues the input message to the alternate destination, issues a succeeded message to the Enterprise Server console, and issues a DFS555I message to the originating terminal. If NDMDEST contains an invalid destination (such as zeros or blanks) or a destination that is unknown to Enterprise Server, Enterprise Server ignores the request to change the destination and continues normal processing.
Communication with Enterprise Server
To enable communication with Enterprise Server, the exit routine must specify parameters from the standard user exit parameter list and use the non-discardable messages (NDM) interface block. See Standard User Exit Parameters and Non-discardable Messages (NDM) Interface Block for more information.
Return Codes
Before returning to Enterprise Server, the exit routine must set one of the following return codes:
Return Code | Description
0 | Continue normal processing.
4 | Delete the input message from the system.
8 | Move the input message to the suspend queue.
12 | Requeue the input message to the original transaction.
16 | Queue the input message to an alternate destination that is named in the NDMDEST field of the NDM interface block.
Parent topic: Exit Routines
Related reference
Standard User Exit Parameter List
Non-discardable Messages (NDM) Interface Block
IMS-Specific Environment Variables


IMSDBU Exits

The IMS Database Utility (IMSDBU) exits are available only in Micro Focus COBOL development systems. They enable you to perform database functions, and consist of the following:

Database Segment Exit
The segment exit enables a user-written program to control segment selection and modify segment data during load and unload processing. The exit program is called for each database segment. It can delete the segment, modify the segment data, or pass it through unchanged. If a segment is deleted, all of its children segments are automatically deleted.
Database Compression Exit
The compression exit is used for the input file to the Load and the output file for Unload. It allows for segment compression and/or encryption of the input or output files. It is not used for the data stored in the MFIMS database. A standard routine named CBLDCIMS is provided to decompress input and compress output files. A user-written program can perform different segment encoding.
Database Progress Exit
Controls the frequency of progress reporting during the execution of database functions.
Invocation
IMSDBU exits are invoked upon the execution of the IMSDBU Load and Unload functions by specifying the following directives:
  • SEGEXIT - to execute the Database Segment exit
  • COMPRESS - to execute the Database Compression exit
    Note: If no exit name is specified, Enterprise Server executes the default compression routine, CBLDCIMS.
  • PROGRESS - to execute the Database Processing exit
Example
Enterprise Developer provides a sample file, DBUPARMS.cpy that documents all three IMSDBU exits. DBUPARMS.cpy is located by default in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples (Windows) or $COBDIR/demo/ims/examples (UNIX) directory.
Parent topic: Exit Routines
Related concepts
IMS Database Utility (IMSDBU)
IMS Database Editor
IMS TM Compatible Transaction Manager
Related reference
Load function
Unload function
COMPRESS
SEGEXIT
PROGRESS


IMS Database Tools

Enterprise Developer and Enterprise Server provide several tools for creating, accessing, and testing IMS databases. You can execute some of these tools from multiple places. For example, you can execute the database Load utility from the Enterprise Developer IDE, from the command line, or from a JCL interface. The IMS database tools include:

  • IMS Database Utility (IMSDBU)
    IMSDBU is an IMS database management tool that enables you to perform database functions such as initialize, load, unload, reorganize and many others.
  • DBUTIL Utility
    DBUTIL is a general-purpose tool executed from JCL for issuing DL/I calls and special functions against an IMS database. It runs as a BMP type program in IMS.
  • VRECGEN Utility
    VRECGEN is a utility program that runs on the mainframe, and enables you to preserve segment length information for IMS databases that have been unloaded using the standard IBM unload utility or a third party unload utility.
  • IMS Segment Layout Editor
    Enables you to view and edit formatted IMS data in the IMS Database Editor.
  • IMS Database Editor
    Describes the features of the IMS Database Editor, used to view and manipulate data.
Parent topic: Developing IMS Applications


IMS Database Utility (IMSDBU)

IMSDBU is a database management tool that offers a wide range of operational control. You can use it to initialize, load, unload and reorganize databases. You can tailor its operation to control file naming conventions, progress reporting, statistics, audit reports, and more.

IMSDBU runs as a standalone utility; a PSB is not required to use it. It operates on physical databases defined using the DBDGEN function. Because it runs outside of the Application Region, it can provide streamlined operation.

IMSDBU Features

Several IMSDBU features help you to manage your IMS databases, including:

High Performance
IMSDBU can load and unload a database in a fraction of the time taken by an application program issuing DL/I calls. This is because IMSDBU communicates directly to the physical access layer in the hierarchical database engine. This layer is common between the MFIMS DL/I language interface and IMSDBU to ensure consistent formatting of databases and segments.
Load and Unload Exits
The segment exit enables a user-written program to control segment selection and modify segment data during load and unload processing. The exit program is called for each database segment. It can delete the segment, modify the segment data, or pass it through unchanged. If a segment is deleted, all of its children segments are automatically deleted. The segment exit is enabled using the SEGEXIT directive.

The compression exit is used for the input file to the Load and the output file for Unload. It allows for segment compression and/or encryption of the input or output files. It is not used for the data stored in the MFIMS database. A standard routine named CBLDCIMS is provided to decompress input and compress output files. A user-written program can perform different segment encoding. This exit is enabled using the COMPRESS directive.

The IMSDBUV sample program for unloading IMS/ESA databases can create compressed files for input to the IMSDBU Load and decompressed using the CBLDCIMS routine.

Details of these exits are documented in the sample file DBUPARMS.CPY, located in the %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\IMS\Classic\Examples (Windows) or $COBDIR/demo/Mainframe/IMS/Classic/Examples (UNIX) directory by default..

Progress Reporting
IMSDBU reports the progress it makes while processing a database function. When performing a database load or a logical pointer update, it shows a 'percent complete' and an estimate of the time remaining. For database unloads, a percentage cannot be calculated so IMSDBU displays the segment number in process. The frequency of progress reporting is controlled by the PROGRESS directive.
Detailed Reporting and Statistics
A detailed report showing the results of a database function is available. This report is produced as an ASCII text file. It can reflect the most recent function or can maintain a historical record. This reporting is controlled by the LIST and LISTOPEN directives. Items included in this report are:
  • A starting message indicating the date/time, database name and the function performed.
  • 'Options in effect' which lists the directives used.
  • Information, warning and error messages issued during execution.
  • Database statistics with the Load and Unload functions. These include segment counts, maximum per root, and average per root listed by segment type.
  • The ending message produced by the function. This states the success or failure of the function and the ending return code value. This message also appears in the historical activity log.
Historical Activity Log
A historical activity log can be kept for all IMSDBU activity. An entry is written to the log when a function completes. This entry consists of the date and time, database name and the ending message for a function. The most recent entries are written to the end of the file. This log is produced as an ASCII text file and is controlled by the LOG directive.
Simplified Logical Loading
IMSDBU loads all physical databases in the same way - with the Load function. For databases containing logical children, a pointer update function connects the logical children to their parents and resolves paired segments after loading.

Logical database loading is further simplified by the use of the Makelist function. Makelist generates all of the required steps to load a complete set of logically related databases. You provide one DBD name and Makelist follows its relationships to create the set. From this, it generates a file for input to the Runlist function to execute the steps.

Specialized and Generic Load Inputs
IMSDBU provides a special-purpose input file layout for loading databases. This file layout is created by the IMSDBU Unload function or by the IMSDBUV program. IMSDBUV is provided as COBOL source code and is installed in the source directory. You can transfer this program to your mainframe, compile, and run it to extract IMS/ESA segment data.

This special-purpose layout provides for simpler loading of the database. The physical characteristics of the file and data are stored in header and trailer records in the file. This includes items such as the placement of the segment name, segment data, and compression options. Loading a database with this format is as easy as naming the input file and using the LAYOUT(D) directive. For reference, the IMSDBU layout file is a variable length file to reduce storage requirements and file transfer times.

IMSDBU also supports a special purpose IBM layout. This is specified using the LAYOUT(I) directive and supports input files created using IMS/ESA DB Unload Utilities such as DFSURGU0. This layout sets the directive values SEGM(7), DATA(36), RECFM(V) and NOCOMPRESS. This layout honors delete byte settings in the input file and directs IMSDBU to skip over segments marked as deleted.

IMSDBU supports sequential input files using the LAYOUT(S) directive. This enables you to load an IMS database from an input file produced from COBOL program or, on Windows platforms only, downloaded from the mainframe using Drag and Drop as a sequential file.

IMSDBU supports generic layouts for the input load files using the LAYOUT(G) directive. The generic layout must contain the segment name and segment data in the same position of each record. It can be a fixed or variable length segment. A SEGM directive indicates the position of the segment name in the record area. A DATA directive indicates the starting position of the segment data. The segments in the file must be in hierarchical order, but do not have to be in key sequence.

  • Accessing IMSDBU
    Describes the various methods of accessing IMSDBU.
  • Fast Path MSDBs
    Describes the support of Fast Path MSDBs in the context of an IMS application.
  • Converting Segments from EBCDIC to ANSI
    Describes the IMSDBUEA exit routine that provides support for EBCDIC to ANSI conversion.
  • IMSDBU Automation
    Describes methods for automating database management functions.
  • IMSDBU Functions
    Lists and describes the functions available with IMSDBU.
Parent topic: IMS Database Tools
Related concepts
Unload an IMS Database
Load the IMS database
IMSDBU Exits
IMS Database Features
Related tasks
To load an IMS database
Related reference
mfims imsdbu command
PROGRESS
LISTOPEN
LIST
LOG
LAYOUT
RECFM
SEGM
COMPRESS
DATA
SEGEXIT
Add function
Unload function


Accessing IMSDBU

We provide three options you can use to access all or some of the IMSDBU functions:

IMS Project in Enterprise Developer IDE
You can run the IMSDBU Load, Unload, Zeroload, and Add functions from your IMS project in Enterprise Developer.
Command Line
You can execute all IMSDBU functions from the command line using the mfims imsdbu command.
JCL
You can run the Load, Unload, ZeroLoad, Add, and PTRUpdate functions by executing the MFDBUJCL utility program from JCL.
Parent topic: IMS Database Utility (IMSDBU)
Related reference
MFDBUJCL Utility
mfims imsdbu functions
mfims IMSDBU
mfims imsdbu command


Fast Path MSDBs

MSDB databases are supported in a very similar way to full-function and DEDB databases. The MSDB support builds from this to add MSDB-specific features such as the FLD Verify and Change call.

MSDB databases are stored on disk and must be initialized using the Zeroload function. The Reorganize function can be used with MSDBs without any special consideration and is used for the same purposes as for other databases.

MSDBs are loaded using the Load function. The format of the input file to load MSDBs may be different than for other databases. This depends on which of the four types of MSDBs you are loading.

A non-terminal related MSDB without LTERM keys has the same input formats for Load as full-function and DEDB databases. This kind of MSDB is the easiest to manage since its segment is defined like other segments with a sequence field value provided by the application.

The other types of MSDBs use a different format. This is required to support the LTERM name which is used directly or indirectly as a key for the segments. The SEGM directive for the Load indicates the position of the LTERM name instead of the location of the segment name. Since MSDBs only have one segment, the segment name is not required for loading. The three types of MSDBs affected by this difference are:

  • Non-terminal related with LTERM keys
  • Terminal related fixed
  • Terminal related dynamic

The Unload function uses the SEGM directive the same as Load. For these three types, the SEGM directive indicates the location of the LTERM name for a generic Unload format.

You cannot use the IMSDBUV program to unload one of these kinds of MSDBs. You will need to create a program to format the type of input file required by the Load function.

Parent topic: IMS Database Utility (IMSDBU)


Converting Segments from EBCDIC to ANSI

Mainframe Subsystem Support includes a segment exit routine called IMSDBUEA that you can use to convert segments from EBCDIC to ANSI. You can use it in three ways:

  • when unloading, causing the output to be written in ANSI.
  • when loading, causing the file to be converted before it is loaded.
  • when adding segments, causing the segments to be converted before they are added.

IMSDBUEA uses a segment layout (.slf) file to determine which fields of each segment need to be converted, so you must create an .slf file using the IMS database editor before you can use IMSDBUEA. The .slf file must be in the directory specified by the ES_IMSDAT environment variable, or if the ES_IMSDAT environment variable is not set the .slf file must be in the current directory.

How you use IMSDBUEA depends on whether you are using the database management utility or the command line:

  • If you are using the database management utility specify IMSDBUEA in the SEGEXIT field when adding segments or loading or unloading a database.
  • If you are using the command line, add the following parameter:segexit=imsdbuea
It is not possible for IMSDBUEA to call one of your segment exit routines. However, if you need to perform some additional processing before converting from EBCDIC to ANSI you can write your own segment exit routine that performs the required processing, and then calls IMSDBUEA. To call this exit, which is actually an entry point, directly from your program, load its parent program, MFIMSDBU, first and use DBUPARMS.CPY. For example:
       PROCEDURE DIVISION.
      *=========================================================*

***** Load the MFIMSDBU module first.

     set ws-ptr to entry "MFIMSDBU"
     if ws-ptr = null
         display "Cannot Load MFIMSDBU DLL"
         display "Need to Die gracefully."
         stop run
      end-if

           MOVE 02                     TO SEGEXIT-VERSION
           MOVE 00                     TO SEGEXIT-FUNC
           MOVE 'P155'                 TO SEGEXIT-DBD
           MOVE 'P155SEG'              TO SEGEXIT-SEGM
           MOVE 10                     TO SEGEXIT-SEGM-LTH
           MOVE 10                     TO SEGEXIT-SEGM-MAX-LTH
           MOVE P155SEG                TO SEGEXIT-DATA

           CALL 'IMSDBUEA' USING SEGEXIT-PARMS
                                 SEGEXIT-DATA.

mftech     MOVE 02                     TO SEGEXIT-VERSION
mftech     MOVE 01                     TO SEGEXIT-FUNC
mftech     MOVE 'P155'                 TO SEGEXIT-DBD
mftech     MOVE 'P155SEG'              TO SEGEXIT-SEGM
mftech     MOVE 10                     TO SEGEXIT-SEGM-LTH
mftech     MOVE 10                     TO SEGEXIT-SEGM-MAX-LTH
mftech     MOVE P155SEG                TO SEGEXIT-DATA
mftech
mftech     CALL 'IMSDBUEA' USING SEGEXIT-PARMS
mftech                           SEGEXIT-DATA.
Note:
  • You cannot create another segment exit called IMSDBUEA.
  • IMSDBUEA performs the conversion using the COBOL program _CODESET. By default, _CODESET uses the EBCDIC and ANSI codepages in use on your PC. If you need to convert using different codepages you must use the codecomp utility to create customized mapping tables. For more information see The Codecomp Utility and the section Converting between EBCDIC and ASCII in the File Handling topic Converting Data Files.
Parent topic: IMS Database Utility (IMSDBU)


IMSDBU Automation

You can run IMSDBU functions using IMSDBU Runlist command files or operating system command prompt. Using these batch interfaces can simplify the execution of repetitive functions. LAN servers and other products provide timed-operation or command scheduling functions. Combining these functions with IMSDBU command execution can provide unattended operation.

Some example uses are:

  • Transferring files and loading databases overnight
  • Performing scheduled database reorganizations and/or backups
  • Refreshing test databases over a weekend

The command line interface executes IMSDBU functions from an operating system command file (or command prompt). Each IMSDBU command line runs one IMSDBU function. The system return code is set to the function's ending return code. A return code of 8 or above indicates that the function failed.

IMSDBU also supports its own Runlist command files. These are similar to operating system command files but allow you to process a series of commands as a group. One operating system command starts execution of the Runlist file which contains a list of functions.

The Runlist file may be easier to use when a function depends on a previous function completing successfully. When a function in a Runlist file fails, the remaining functions are canceled. With an operating system command file, ERRORLEVEL or return code checking must be used to bypass the remaining steps.

If you need to ensure a function runs, regardless of the outcome of a previous step, use operating system command files. A combination of operating system commands and Runlist files provides a great deal of flexibility for performing IMSDBU functions.

Example

This example demonstrates loading several databases using an operating system command file and two Runlist files. It uses four databases: A, B, C, and D. Databases A and B are logically related to each other, as are databases C and D.

A Runlist file is used to load databases A and B. The Runlist file will produce one detail list file for all of its steps. The LISTOPEN(NEW) directive on the first step creates a new listing file. The LISTOPEN(MOD) directive on the subsequent steps appends to this listing. If the Load of either database fails, there is no reason to continue the process. Both of the databases must load successfully before PtrUpdate can run. All four steps must complete successfully before the databases can be used by an application.

Runlist file LOADAB.RUN

LOAD A DSN(A.LOD) LIST(LOADAB.LST) LISTOPEN(NEW)
LOAD B DSN(B.LOD) LIST(LOADAB.LST) LISTOPEN(MOD)
PTRU A LIST(LOADAB.LST) LISTOPEN(MOD)
PTRU B LIST(LOADAB.LST) LISTOPEN(MOD)

A similar process (and Runlist file) is used to load databases C and D.

Runlist file LOADCD.RUN

LOAD C DSN(C.LOD) LIST(LOADCD.LST) LISTOPEN(NEW)
LOAD D DSN(D.LOD) LIST(LOADCD.LST) LISTOPEN(MOD)
PTRU C LIST(LOADCD.LST) LISTOPEN(MOD)
PTRU D LIST(LOADCD.LST) LISTOPEN(MOD)

An operating system command file is used to execute these two Runlist files. The following command file executes the Runlist files. The ECHO directive causes display of ending messages and error messages with a return code of 4 or greater. The ECHO stoplvl of 50 indicates that no prompting should occur for any IMSDBU messages.

LOADABCD.BAT

xx IMSDBU RUN LOADAB.RUN echo(errend,4,50) nocls
xx IMSDBU RUN LOADCD.RUN echo(errend,4,50) nocls

In this example, a failure during the load of database A would cancel the load of database B but not affect the loading of databases C and D. This operating system command file could be run unattended - the activity log and the detail list files contain the results of the execution.

Parent topic: IMS Database Utility (IMSDBU)
Related reference
LISTOPEN
ECHO


IMSDBU Functions

IMSDBU provides the following functions:
Add
Add to or refresh segments in a database from an input data file.
Delete
Delete segments in a database.
Load
Initializes a database and loads it from an input data file.
Makelist
Generates a Runlist command file.
PtrUpdate
Validates and establishes the pointers that maintain logical relationships.
Recover
Recover one or more databases using recovery log files.
Reorganize
Provides a simple mechanism for reorganizing a database or set of logically related databases.
Rollback
Roll back corrupted databases.
Runlist
Executes IMSDBU functions listed in a Runlist command file.
Unload
Writes database segment data to a sequential output file.
Useq
Unloads all sequential dependent segments (SDEPs) from a Fast Path DEDB.
Zeroload
Create database data files and prime them for use.
Parent topic: IMS Database Utility (IMSDBU)
Related reference
Add function
Delete function
Load function
Makelist function
PtrUpdate function
Recover function
Reorganize function
Rollback function
Runlist function
Unload function
Useq function
Zeroload function


DBUTIL Utility

DBUTIL is a general-purpose tool executed from JCL for issuing DL/I calls and special functions against an IMS database. It runs as a BMP type program in IMS. It is very useful in testing DL/I functions and verifying IMS data without having to write a program. However, to execute it requires a generated PSB.

See the DBUTIL reference topics for complete information on using the DBUTIL utility.

Parent topic: IMS Database Tools
Related reference
DBUTIL command in JCL
DBUTIL special functions
DBUTIL


VRECGEN Utility

VRECGEN is a utility program provided by Micro Focus that runs on the mainframe. Its purpose is to preserve segment length information when an IMS database has been unloaded using the standard IBM unload utility or a third party unload utility. It MUST NOT be used if the user has unloaded using IMSDBUV utility.

Parent topic: IMS Database Tools


IMS Segment Layout Editor

To enable you to view and edit formatted IMS data in the IMS Database Editor, you first use the IMS Segment Layout Editor to define the formatting for the data in IMS segments. The layout describes the name, length, and picture of each field in the segment.

You can create one or more segment layout files for each IMS database, depending on how many COBOL programs access that database. Each segment layout file can contain one or more segment layouts, based on the data structures contained in the Data Division of a COBOL program that accesses the database - one program per segment layout file.

The Segment Layout Editor extracts the data structure from the Data Division of a COBOL program by reading its debug information (.idy) file, which is generated by Enterprise Developer when you compile the program. For each layout definition, you attach a data field or structure to an IMS segment.

Once the segment layouts are defined, use the IMS Database Editor to apply the segment layout formatting.

Note: The IMS Segment Layout Editor is one of several Micro Focus data file tools. For more information, see Data File Tools.
  • Input
  • Segment Layout Types
  • Segment Layout Names
  • Output
Parent topic: IMS Database Tools
Related concepts
Creating and Using a Segment Layout File
IMS Database Editor
Classic Data File Tools
Related tasks
To create a debug information (.idy) file for layout file input


Input

The Segment Layout Editor uses the Data Division of a COBOL program as input for creating a segment layout. You can create one or more layouts from each Data Division.

To enable the Segment Layout Editor to read the Data Division of a COBOL program, you must first compile the program in Enterprise Developer to produce a debug information (.idy) file that can be read by the Segment Layout Editor. The segment layouts that you create from the .idy file describe the name, length, and picture of the fields in a data record.

Parent topic: IMS Segment Layout Editor
Related tasks
To create a debug information (.idy) file for layout file input
To start the Segment Layout Editor
To create a new segment layout file
To load program information


Segment Layout Types

Enterprise Developer supports two segment layout types:
Default
You can define one default segment layout for each IMS segment; however it is not mandatory. A default segment layout formats data that does not meet the conditions specified by any conditional segment layouts you have created for that segment type.
Conditional
You can define one or more conditional segment layouts for each IMS segment. When you create a conditional segment layout, you define a test that applies to one or more fields. To use a conditional segment layout, the data in a segment occurrence must satisfy all the tests defined for that layout.
Note:
  • When you initialize a segment occurrence you can choose to specify a segment layout for entering data.
  • When you modify data, the IMS Database Editor works out automatically which layouts to use for which occurrences.
Parent topic: IMS Segment Layout Editor
Related concepts
IMS Database Editor
Segment Layout Names
Related tasks
To define segment layouts


Segment Layout Names

A segment layout name is constructed from information in the segment and the Data Division from which it is created.

Default segment layout
A default segment layout name is constructed as follows:
segment-name-DEFAULT

where segment-name is the name of the segment in the IMS database. For example, the default segment layout for a segment named LD9S1 is LD9S1-DEFAULT. In the IMS Database Editor, the Layout Status Bar displays the name of a default segment layout simply as DEFAULT.

Conditional segment layouts
Conditional segment layout names are constructed as follows:
segment-name-record-name
where:
segment-name | is the name of the segment type in the IMS database
record-name | is the name of the COBOL record used to create the segment layout

For example, a COBOL record named 01 CUSTREC applied to a segment type named LD9S1 results the layout name LD9S1-CUSTREC. In the IMS Database Editor, the Layout Status Bar displays only the second part of the layout name. Therefore, for LD9S1-CUSTREC, simply CUSTREC is displayed.

Parent topic: IMS Segment Layout Editor
Related concepts
Segment Layout Types
Related tasks
To define segment layouts


Output

The default output file name for any new segment layout file is Layout.slf, and can be saved in a directory of your choice. However, if you follow these conventions, the IMS Database Editor automatically applies the appropriate segment layout file to a DBD or PSB when you open it for editing:
  • Save the segment layout file in the same directory as the DBD or PSB file
  • Name it using the same file prefix as the DBD or PSB file
  • Use the .slf file extension
Parent topic: IMS Segment Layout Editor
Related tasks
To create a new segment layout file
To define segment layouts


IMS Database Editor

The IMS Database Editor provides a graphical interface for viewing and manipulating data in an IMS database. Starting from either a DBD or a PSB, you can use the IMS Database Editor to:

View data
  • Look at the data for a single segment occurrence
  • Browse through segment occurrences to the end of the database
  • Switch between viewing the data in ANSI or EBCDIC
Navigate the database
  • Make a DL/I call easily - simply click on a toolbar button
  • Set up qualified and unqualified SSAs
  • Search forwards through the database for a string
  • Bookmark a segment occurrence, enabling you to return easily to that segment occurrence later on in the session or in a future editing session
  • Jump to a segment occurrence further on in the database, while browsing
Make changes to segment occurrences
  • Edit either unformatted or formatted data
  • Cut, copy, and paste selected text via the clipboard
  • Initialize data at field level or segment level
  • Undo your edits at segment level or field level
  • When your edits are complete, make the appropriate ISRT, REPL and DLET DL/I calls
Important: To view and edit formatted data, you must first of all define segment layouts for the segment types in the database. To do this you use the Segment Layout Editor. To find out more about the Segment Layout Editor, see IMS Segment Layout Editor.

The remaining topics in this section assume that you have segment layouts loaded to format your data.

Note: The IMS Database Editor is one of several Micro Focus data file tools. For more information, see Classic Data File Tools.
  • Configuring the IMS Database Editor
  • Navigating an IMS Database
  • Creating and Editing Data
Parent topic: IMS Database Tools
Related concepts
Creating and Using a Segment Layout File
IMSDBU Exits
IMS Database Features
IMS Segment Layout Editor
Segment Layout Types
Classic Data File Tools
Related tasks
To start the IMS Database Editor
To set Classic Data File Tools options


Configuring the IMS Database Editor

IMS Database Editor configuration is done from the IMS DB Editor tab of the Data Tools Options dialog box.

Warning Prompts

By default, the IMS Database Editor prompts you for confirmation each time you attempt to:

  • Edit a segment
  • Delete a segment

You can turn these prompts off by unchecking Update warning and Delete warning. Any changes made during an editing session take effect the next time you open a data file. You can also prevent a prompt from appearing again in a current session by checking its Do not show this message again box.

Segment Browser

By default, the Segment Browser displays 30 segment occurrences per page. You can change this default by entering a new value into the Number of segments per browser page field.

You might want to reduce the number of segment occurrences per page when, for example, you access a remote database or use a machine with a slow processor. In these cases, reducing the number of segments displayed can improve performance.

For more information on segment browsing, see Browsing Segment Occurrences.

Parent topic: IMS Database Editor
Related concepts
Browsing Segment Occurrences
Related tasks
To set Classic Data File Tools options


Navigating an IMS Database

The IMS Database Editor provides several navigational tools for your database:

  • Direct DL/I calls, with or without SSAs
  • A search utility
  • Bookmarks

You can navigate your way forwards through a database.

  • Retrieving Data
  • Searching for a String
  • Bookmarking Segment Occurrences
  • Browsing Segment Occurrences
Parent topic: IMS Database Editor
Related tasks
To make a DL/I call
To define an SSA
To find your current position in the database


Retrieving Data

You can retrieve data in an IMS database using DL/I calls, with or without Segment Search Arguments (SSAs).

The IMS Database Editor supports the following DL/I calls:

  • Get First With Hold
  • Get Next Segment With Hold
  • Get Next Segment Within Parent With Hold
  • Get Unique With Hold

When you use a DL/I call to change your position within a database, the Current Segment Arrow [image] in the tree view moves to the new segment type, if it has changed. The Field Layout View and the Segment Data and Field Data areas display data for the segment occurrence that is current.

When you reach the end of the database, the IMS Database Editor prompts you to reset your position to the start of the database.

Tip: To find out whether a DL/I call is successful, look at the status code on the IMS Database Editor status bar. The status code should be set to BLANKS. If there is an error, the IMS Database Editor displays a message containing the status code and a full description. See The IMS Database Editor Status Bar for more information.

You can qualify a DL/I call using a Segment Search Argument (SSA).

Note: Enterprise Server provides compatible SSA support including support for:
  • Up to 15 SSAs per call, with each SSA limited to 4,000 bytes
  • SSA relational operators supporting up to 125 boolean operations on each SSA
  • SSA command codes
Parent topic: Navigating an IMS Database
Related tasks
To make a DL/I call
To define an SSA


Searching for a String

You can search your IMS database for a string beginning from your current position in the database. You can search all of the database contents occurring after that position, or you can restrict the search to:

  • The current database record
  • The parent segment occurrence, including any twin or child segment occurrences (not relevant for the root segment)
  • The current segment type, including or excluding any child segment occurrences
  • Data between specified record offsets.

Searches can be case-sensitive or case-insensitive.

Note:
  • You can search through a database forwards but not backwards.
  • When you invoke a search, your current position in the database changes to the last segment searched even if the search operation fails to find the string you have entered.
Parent topic: Navigating an IMS Database
Related tasks
To search an IMS database for a string
Related reference
IMS Database Find dialog box


Bookmarking Segment Occurrences

You can bookmark a segment occurrence so that you can return to it later during the current editing session or during a later editing session.
Note: Bookmarks can be applied only to segment occurrences that have a unique concatenated key.

Bookmarking options

Bookmarking options are:
  • Add
    Note: You cannot add a bookmark while the Browse window is open.
  • Retrieve, either from the current bookmark list file or a different bookmark list file
  • Save, either to the current bookmark list file or a different bookmark list file
  • Delete

Bookmark list file

When you create a bookmark, the IMS Database Editor stores the name, segment occurrence, and a description in a bookmark list. Between editing sessions, the bookmark list is automatically stored in a bookmark file in the folder containing the database you are editing. The bookmark file name has a .bmf extension, and the prefix depends on the type of database:
Type of Database | Bookmark List Filename
Physical database | The name of the DBD
Logical database | The name of the PSB immediately followed by n, where n is the PCB number
Parent topic: Navigating an IMS Database
Related tasks
To bookmark a segment type
To go to a bookmarked segment type
To delete a bookmark
To save your bookmarks in a file
To load bookmarks from a file
Related reference
Add bookmark dialog box
Bookmarks dialog box


Browsing Segment Occurrences

You can browse forward through the segment occurrences, one page at a time, starting at your current position, and also browse backward, one page at a time, to your starting position. Therefore, to browse from the beginning to the end of a database, start at the beginning of the database.

In addition to viewing segment data, while in browse mode you can also view key information and hexadecimal data equivalents.

Parent topic: Navigating an IMS Database
Related concepts
Configuring the IMS Database Editor
Related tasks
To browse data in an IMS database
To set Classic Data File Tools options


Creating and Editing Data

The IMS Database Editor enables you to edit segment data and field data from various places in the IDE. While editing either segment or field data, you can:

  • Cut or copy data to the clipboard and paste in the data somewhere else.
  • Toggle between Insert and Overtype mode by pressing Insert.
  • Initialize a field that has invalid data, as long as the field is not a key field. An alphanumeric field is initialized to spaces. A numeric field is initialized to zeros.
Editing Area | Description
Segment data | Displays the contents of the segment buffer. The segment buffer contains character and hexadecimal representations of binary segment data for the current segment occurrence.
Layout view | After applying a segment layout file, you can edit a field in the Value column.
Field data | For formatted data, you can edit character and hexadecimal representations of binary data for the field that is selected in the Layout view.
  • Editing Field Data
  • Editing Segment Data
  • Initializing Segments and Fields
Parent topic: IMS Database Editor
Related tasks
To configure edit warnings
To undo edits
Related reference
IMS Database Editor window


Editing Field Data

You can edit character and hexadecimal representations of binary data for a field; however, to do so, you must have a defined segment layout for the segment occurrence. When you have finished editing fields for the segment occurrence, you can issue an ISRT or REPL DL/I call. You can undo segment buffer edits up until the point when you issue the ISRT or REPL call.

You can edit data from either of these two places within the IMS Database Editor:

Editing Area | Description
Field Layout view, Value column | Click in the Value column that corresponds to a field.
Field data | You can click inside this area to edit character and hexadecimal representations of binary data selected in the Layout view. To do so, you must first apply a segment layout for the segment occurrence. When you have finished editing a field, you can save your edits in the segment buffer by clicking inside another part of the IMS Database Editor window. To undo your edits, press Escape before clicking inside another part of the window.

When you have finished editing a field, you can save your edits in the segment buffer by pressing Enter. This updates the Segment Data area in the left-hand pane. You can undo the edits you have made to a field by pressing Escape instead of Enter.

Parent topic: Creating and Editing Data
Related tasks
To edit formatted field data
To edit unformatted field and segment data
Related reference
IMS Database Editor window


Editing Segment Data

You can directly edit character and hexadecimal representations of binary segment data for a segment occurrence, and you can use DL/I calls to add, modify, and delete segment occurrences.

The IMS Database Editor supports these DL/I calls:

DL/I Call | Function
ISRT | Add a new segment occurrence
REPL | Modify an existing segment occurrence
DLET | Remove a segment occurrence

If a segment is of variable length, you can also change the segment length.

Before issuing ISRT and REPL calls, you need to edit data.

Note: You cannot make changes to segment occurrences while the Browse window is open.
Adding a new segment occurrence
The method used to add a first child differs from the method used subsequently to add twins to the first child.

Once you have added the first child, you can add a twin very quickly. While the data for the previous twin is still in the segment buffer, you can edit the key field and any other fields that are different and then insert the data from the buffer.

The Segment data area initializes to the size of the child segment and fills it with default padding bytes. The Layout View and Field data area adopt the segment layout for that segment type, if one has been set up.

Before inserting the data into key fields, you must edit them to make them unique.

Initializing segment occurrences
The IMS Database Editor provides two options for initializing segment occurrences:
Initialize
Initialize the data in the segment buffer. As you enter new data, the IMS Database Editor loads the appropriate layout automatically. This option is quick because it does not require additional specifications.
Select Layout and Initialize
Specify the layout you want to use for the new segment occurrence and initialize the data in the segment buffer. The editor applies a default segment layout when you initialize.
Changing segment length
If you have a segment layout loaded for the current segment occurrence, you can edit the length field of a variable-length segment.
Note: If you do not have a segment layout loaded, you cannot edit the length field. Instead, use the IMS Segment Editor to change the length field.
Parent topic: Creating and Editing Data
Related tasks
To apply segment layouts
To add a first child segment occurrence
To add a twin segment occurrence
To delete a segment occurrence
To modify a segment occurrence
To change the length of a segment occurrence
To initialize data
Related reference
IMS Database Editor window


Initializing Segments and Fields

You can initialize a single field or all the fields in a segment. You might want to do this for testing purposes, or to reset a field or segment that contains invalid data. Initialization replaces the data in the field or segment, changing:

  • Alphanumeric fields to all spaces
  • Numeric fields to all zeros

Initialization does not affect conditions applied to fields by conditional segment layouts.

Parent topic: Creating and Editing Data
Related tasks
To initialize data
Related reference
Initialize Segment dialog box


Deploying IMS Applications

An IMS application developed in Enterprise Developer can be deployed to Enterprise Server and run there in production.

To become familiar with the process of creating and configuring an enterprise server instance to support your IMS application, we recommend that you follow the procedures presented in either of the following sets of topics:

IMS: Tutorial
The IMS tutorial takes you through:
  • Creating an Enterprise Developer project
  • Adding IMS application and database files to the project
  • Building the application from the Enterprise Developer IDE
  • Using the Enterprise Server IMS template from the Enterprise Developer IDE to create and configure an enterprise server instance to run the application
  • Running the application on the enterprise server
IMS Installation Verification
The IMS Installation Verification topics take you through:
  • Preparing and compiling an IMS application using command-line tools
  • Using Enterprise Server to create and configure an enterprise server instance to run the application
  • Verifying CICS installation
  • Running the application on the enterprise server
  • Creating and Configuring an Enterprise Server Region for IMS
    Describes the creation and configuration of an enterprise server region that runs an IMS application.
  • IMS Database Administration
    BTS Trace, IMS Database Locking and IMS Database Recovery.
  • WebSphere MQ Support
    Describes Enterprise Server support for communicating with WebSphere MQ to receive and process requests, and to return output back to WebSphere MQ.
Parent topic: IMS Support
Related concepts
IMS Installation Verification Procedure (IVP)
Tutorial: IMS Support
Deploy and Run the IMS Application


Creating and Configuring an Enterprise Server Region for IMS

To run IMS applications, you must create an enterprise server region that is MSS-enabled and appropriately configured to run an IMS application. You can do this either from the Eclipse IDE or Enterprise Server Administration. When you create the enterprise server region from the Eclipse IDE, much of the configuration is done for you; however, both methods require manual configuration as well.

Creating an enterprise server region from Eclipse using the IMS Template

Enterprise Developer provides an Enterprise Server template, IMSTemplate.xml, that you can use to simplify the process of creating and configuring an enterprise server region for an IMS application. IMSTemplate.xml is located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates by default. When you use the template to create the enterprise server region, the following is enabled or configured for you automatically based on your Enterprise Developer project properties and the information you supply when creating the enterprise server:

Default configuration for an IMS-enabled enterprise server region:
  • MSS is enabled
  • IMS is enabled
  • System Initialization Table is set to IMSSIT
  • Message processing region (MPR) is created
Configuration based on information required by the template:
  • Enterprise server region name
  • Project is associated with the enterprise server region
  • Working mode, 32- or 64-bit
Configuration based on Enterprise Developer project properties:
  • Application path
  • Configuration directory
  • Database path
  • GEN file directory
  • Map/MFS path
  • Transaction path

You must manually specify a TN3270 listener and port number.

Creating and configuring an enterprise server region from Enterprise Server Administration

When you create an enterprise server region from Enterprise Server Administration with the intent to run an IMS application on the enterprise server, you must configure the following as a minimum:

When initially creating the enterprise server region, specify:
  • A name for the enterprise server region
  • Mainframe Subsystem Support
  • Working mode, 32- or 64-bit
  • Specify a TN3270 listener and port number
Manually configure the following:
  • Enable IMS
  • Specify a System Initialization Table (SIT)
  • Specify the location of:
    • Application files
    • Database files
    • Generated files
    • Maps/MFS files
    • Transaction files
  • Specify a message processing region (MPR)
Optional IMS configuration:
You can also configure the following, based on the needs of your IMS application:
  • If your IMS application contains JCL, you must also configure the enterprise server for JCL
  • If you want to use IMS Connect to connect to the database, enable IMS Connect
  • Create a resource group
  • Add a resource group to a startup list
  • Define transactions
  • Calculate shared memory area requirements
  • Specify printers
Important:
  • Migrated IMS applications do not require that you define services, request handlers or implementation packages; however, you should not delete the system services and request handlers that are automatically associated with an enterprise server when you create it.
  • Resources, SITs and startup lists are all CICS concepts. However, our IMS support in Enterprise Server is closely integrated with support for CICS, and as a result, much of the configuration necessary to run CICS applications in an enterprise server is also necessary to run IMS applications. If you are not familiar with CICS concepts, we suggest you read MSS and CICS Support before continuing.
  • Our Enterprise Server product includes many tools and features you can use with IMS applications but that are not specific to IMS applications. Read the Configuration and Administration section to become familiar with other features you might find useful.
  • MSS and CICS Support
  • IMS Connect
  • Open Transaction Manager Access (OTMA)
  • Configuring IMS Multiple Sign-on Support
    Describes support for multiple sign-ons by a single user across multiple LUs.
  • IMS-enabled Enterprise Server Administration using ESMAC
  • Defining IMS Resources
  • Defining IMS Transactions
  • Configuring the IMS Message Queue
  • Configuring IMS Printers
  • Calculating Shared Memory Area Requirements
Parent topic: Deploying IMS Applications


MSS and CICS Support

This section provides a brief overview of the CICS concepts with which you need to be familiar in order to configure enterprise server for use with IMS. This is necessary because support for IMS in Enterprise Server is integrated with support for CICS. If you are familiar with basic CICS concepts you can skip this section.

In CICS, items of software or hardware for use by applications are called resources. Mainframe Subsystem Support adds to Enterprise Server facilities for defining, controlling and monitoring resources. These facilities have been extended to include resources needed by IMS applications. You don't need CICS experience to use these, but you do need a basic understanding of the structure, so for readers unfamiliar with the CICS model, here is a quick overview.

In CICS, you define sets of resources. These sets of resources are called resource groups.

A CICS region is an environment for running CICS applications. When you create a region, you specify a system initialization table (SIT), which gives details of how the region is to be configured. One item specified by the SIT is called a startup list; this is a list of resource groups that are to become available automatically when the region is started.

An enterprise server is equivalent to a CICS region, in Enterprise Server for Windows or UNIX. To run IMS applications, you need to define special service execution processes (SEPs) called message processing regions (MPRs). You define these MPRs as CICS-style resources. Resources always belong to resource groups, so you also need to define a resource group, which needs to be referenced by a startup list, which needs to be referenced by a system initialization table (SIT). You then need to specify that the enterprise server is to use this SIT.

The figure below shows the hierarchical structure of SITs, startup lists, resource groups, and individual resources. The bottom line of the figure shows some more types of CICS resources - a program control table (PCT), file control table (FCT) and program processing table (PPT).

Figure 1. Structure of CICS Resources
Structure of CICS Resources

For more information about CICS Support within MSS, see Part 2 of this book. For more information about Enterprise Server, see your Enterprise Server Configuration and Administration Guide.

Parent topic: Creating and Configuring an Enterprise Server Region for IMS


IMS Connect

IBM IMS Connect is an add-on product to mainframe IMS that provides TCP/IP connectivity to IMS/TM applications. IMS support in Enterprise Server includes emulation of IMS Connect to allow TCP/IP clients to connect for debugging of IMS/TM transactions.

The following IMS features are supported:

  • Conversational (SPA) and non-conversational transactions that do not use the IMS SETO functionality
  • Support for IMS commands
  • Security for all IMS Connect listeners
  • The following IBM-supplied I/O exits:
    • HWSIMSO0 '*IRMREQ*' Yes
    • HWSIMSO1 '*IRMRE1*' Yes
    • HWSSMPL0 '*SAMPLE*' Yes (unmodified - same as HWSIMSO0)
    • HWSSMPL1 '*SAMPL1*' Yes (unmodified - same as HWSIMSO1)
    • HWSJAVA0 '*HWSJAV*' Yes (unmodified)
    • HWSCSLO0 '*HWSCSL*' No
    No exit screening configuration is provided.
  • The return MOD name control
  • Persistent, non-persistent and transactional socket control
  • End-to-end ASCII flows

There is limited support for flow control and Syncpoint/Commit controls

The following are not supported:
  • Modified Sample I/O exits or target resolution exits
  • The return OTMA headers control
  • UTF and UCS codesets
  • The Translate control
  • The IRM timer
  • The One Message and One Message No Wait" controls
  • The Auto Flow and no Auto Flow controls
Parent topic: Creating and Configuring an Enterprise Server Region for IMS
Related concepts
IMS TM Compatible Transaction Manager


Open Transaction Manager Access (OTMA)

If you are using Open Transaction Manager Access (OTMA) to communicate with IMS, no special configuration is needed. However you can specify the amount of time that an OTMA client should wait for an MPR to process a message. The default is 120 seconds, but you can change this period using the environment variable ES_OTMA_TIMEOUT.

The Enterprise Server OTMA C/I (Call Interface) supports the following calls:
CALL FUNCTION otma_create
Creates storage structures to support communications but does not establish a connection with IMS.
otma_open
Establishes a connection with IMS. Issue an otma_create before establishing an otma_open call.
otma_alloc
Creates an independent transaction session.
otma_send_receive
Sends to IMS and passes parameters for receive functions.
otma_free
Releases the independent transaction session.
otma_close
Ends the connection with IMS.
Parent topic: Creating and Configuring an Enterprise Server Region for IMS


Configuring IMS Multiple Sign-on Support

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.

Multiple sign-on support is implemented using the following Enterprise Server environment variables:

ES_IMS_SINGLE
Enables or disables functionality that allows a single user to sign on to multiple LUs simultaneously.

Values

Y
Disables multiple sign-on functionality.
N
Enables multiple sign-on functionality.

When ES_IMS_SINGLE is set to N, and a user attempts to sign on to an LU using a sign-on that is currently active at another LU, IMS Transaction Manager (TM) assigns a temporary LTERM to the user and LU using a name constructed from the ES_IMS_LTERM_PREFIX setting followed by a numerical value totalling eight characters (see the IMS_LTERM_PREFIX entry in this topic for details). The temporary LTERM is the destination for the user and LU irrespective of activity at other LUs controlled by the user. When a user disconnects from an LU that is served by a temporary LTERM, the LTERM is returned to the temporary pool for reuse.

Also when ES_IMS_SINGLE is set to N, the execution of /dis USER all returns a sub-list for each user that shows all active connections. These connections persist throughout a session, and are dynamically recreated during a warm start.

Default

Y

Note: No KEYPOINT activity is associated with the use of ES_IMS_SINGLE.
ES_IMS_LTERM_PREFIX
Specify a one- to four-character LTERM prefix alternative to the default (OTMA) to use when the ES_IMS_SINGLE environment variable is set to N. Use of an alternative prefix to OTMA enables you to exercise control over name conflicts.

Syntax

ES_IMS_LTERM_PREFIX=1to4charprefix

Values

Use up to four characters of your choice. Enterprise Server pads the value specified with numeric digits up to eight characters, enabling the LTERM pool to be expanded from 9999 up to 999999. The pool size is dictated by the number of characters used in the specified prefix. For example, the LTERM pool size for a four-character prefix is 9999; for a three-character prefix is 99999; and so on.

Default

OTMA

Note: The default setting of this environment variable suggests that the LTERMS apply only to OTMA clients; however, this is not the case. LTERMS can also be applied to second and subsequent 3270 user connections.
Parent topic: Creating and Configuring an Enterprise Server Region for IMS


IMS-enabled Enterprise Server Administration using ESMAC

We provide the Enterprise Server Monitor and Control (ESMAC) feature as the primary tool to run and monitor production applications, including IMS applications. We suggest that you read and become familiar with group of topics in the Administering Enterprise Server Instances using ESMAC section of this documentation.

When you first view ESMAC for an IMS-enabled enterprise server, the Server Information page is displayed, as shown here:

Figure 1. ESMAC Server information page for IMS
ESMAC Server information page for IMS

When you run ESMAC on an IMS-enabled enterprise server, you can use it to perform a wide range of administrative functions. Because of the integration between support for IMS and CICS within Enterprise Server, most of these administrative functions are described in the topic Administering CICS-enabled Enterprise Servers. In addition, you can use ESMAC to create temporary MPRs.

Parent topic: Creating and Configuring an Enterprise Server Region for IMS


Defining IMS Resources

Enterprise Server IMS support includes two transactions, /CIC and /IMS, that you use to switch enterprise servers to CICS and IMS modes respectively. For these transactions to be available, you need to update your resource definition file at an Enterprise Developer command prompt using the caspcupg command as follows:

caspcupg /dp=resourcedefinitionpath /o

where resourcedefinitionpath is the path to the system resource definition file to be updated. If you are using the default system resource defintion file, dfhdrdat located by default in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas (Windows) or $COBDIR/etc/cas (UNIX), you can omit /dp=resourcedefinitionpath. See caspcupg for more information on the caspcupg command.

Updating a resource definition file with the /CIC and /IMS transactions in this way is a one-off process, meaning that once you have used caspcupg to upgrade a resource definition file, any enterprise server that uses the updated resource definition file can use the new transactions.

Resource Group

Before you can run an IMS application in an enterprise server you ensure that the following resources are included in a resource group:

Transactions
You must add a list of all transactions and their associated programs to a resource group. This is done by adding a PCT.
Messages
Add the message processing regions that the enterprise server uses.
Message Processing Region (MPR)

To run an IMS application in an enterprise server you need at least one specialized service execution process (SEP) called a message processing region (MPR). To specify that a message processing region starts each time an enterprise server starts, it must be included in a resource group that is specified by the startup list in the SIT used by the enterprise server.

You can add these resources to an existing resource group or create a new one for them.

Startup Lists

Having created a resource group for the resources needed by your IMS application, you need to add the resource group to a startup list.

Note: To update a resource group or startup list, you must first start the enterprise server then use Enterprise Server Monitor and Control (ESMAC). See Administering Enterprise Server Instances using ESMAC for more information on using ESMAC.
Parent topic: Creating and Configuring an Enterprise Server Region for IMS
Related tasks
To start a temporary MPR


Defining IMS Transactions

Usually, a transaction definition must exist for any program you want to run. There are two ways of creating transaction definitions:

  • Define them manually using Enterprise Server Monitor and Control (ESMAC)
  • Use the transaction export and import utilities to extract IMS transactions from an IMS stage 1 file downloaded from the mainframe, or from transaction file created from an enterprise server instance, and automatically add the transactions to your enterprise server instance. This is a two-step process.
Exporting
You export transaction definitions to a transaction file, which contains the transaction and printer definitions needed to subsequently import into Enterprise Server. It is a flat text file, so you can edit it to remove any definitions that are not needed for the application to run under Enterprise Server. You can create a transaction file in one of two ways: Either export from a stage 1 file from the mainframe, or export the transactions from a different enterprise server instance.
Importing
The import utility reads the transaction file created by the export utility, and adds the transaction definitions to the IMSGEN2.DAT file in the current directory. If IMSGEN2.DAT doesn't exist, it is created.
Parent topic: Creating and Configuring an Enterprise Server Region for IMS


Configuring the IMS Message Queue

You can configure the IMS message queue to best serve the application or applications that run in an enterprise server region. You can modify default settings before starting the region. Once started, some of these settings are static, meaning that changes cannot be applied until the region is restarted. Others are dynamic, meaning that you can change and apply the settings without restarting the region.

Most IMS message queue options can be set from the Enterprise Server Administration Server > Properties > MSS > IMS > TM > General page. See Server Instance Properties: MSS IMS TM General for a detailed description of each option including default values.

Static Options

Before starting your enterprise server region, you can replace the default for any static IMS message queue option with an alternative initial setting. Static IMS message queue configuration options include:

  • (Message queue) Name
  • Queue buffer count
  • MFS path
  • MFS attribute bias
  • MFS null character
  • Application path

After starting the region, any changes made to these settings cannot be applied until the region is restarted.

Dynamic Options

Just as with the static options, you can use the default or provide a custom initial value for most dynamic IMS message queue options. However, you can also change the value of a dynamic option while the enterprise server region is running, with the new value taking effect immediately. You can:

  • Adjust the data store size limit
  • Adjust the data store allocation cushion size
  • Adjust the length of time that a transaction can run
  • Adjust the generation frequency of keypoints
  • Tune the flush aggregation performance behavior

You can assign an initial value for the following dynamic settings from the Enterprise Server Administration Server > Properties > MSS > IMS > TM > General page:

  • Maximum Blocks
  • Activity keypoint frequency
  • Transaction threshold

The initial configuration for other dynamic IMS message queue options are based on the values set by ES_TMC_AGGREGATE environment variable.

Once the enterprise server region is started, you can make changes to dynamic IMS message queue options from ESMAC on the IMS Control page.

The following topics provide additional details for dynamic IMS message queue configuration:

  • Dynamic IMS Message Queue Expansion
    Describes the dynamic IMS message queue expansion feature.
  • Dynamic IMS Message Queue Performance Tuning
    Describes using the ES_TMC_AGGREGATE environment variable to set an initial IMS message queue performance level, and using ESMAC to then fine-tune its performance dynamically.
Parent topic: Creating and Configuring an Enterprise Server Region for IMS
Related reference
Server Instance Properties: MSS IMS TM General
IMS Control


Dynamic IMS Message Queue Expansion

In earlier versions of Enterprise Server, the Maximum blocks size as specified for an enterprise server region on the Enterprise Server Administration Server > Properties > MSS > IMS > TM > General page was a static allocated message queue size on a cold start. Subsequent changes had no effect until the execution of the next cold start.

Starting with Enterprise Server version 2.3, Maximum blocks specifies a size limit to which the message queue data store can expand. The initial (default) allocation is always the minimum number of blocks required, meaning the number of blocks initially allocated is equal to or greater than the number of buffers specified in the Queue buffer count. As the application runs, blocks are allocated and formatted as needed up to this limit.

In addition to increasing the size of the data store, you can also modify the percentage of allocated blocks to reserve as a cushion that provides enough emergency allocation space to enable graceful intervention should it be required due to lack of space.

The Maximum blocks specification is initially set to a default value of 32 blocks by Enterprise Server Administration. You can optionally alter this value before starting your enterprise server region. Once started, you can optionally increase the number of blocks and the cushion size, and apply the new settings from the IMS Control page in ESMAC while the region is running.

At any time, you can effectively reduce the maximum number of blocks down to the size of the current message queue physical allocation. Once physically allocated, message queue space cannot be reduced dynamically. This requires a cold start.

At startup, if the maximum size set in Enterprise Server Administration is smaller than the current physical message queue size, the maximum size is set to the message queue physical size.

After startup, you can adjust the maximum message queue size to any size starting with the number of blocks that represent the physical size of the current message queue, and up to the architectural limit of 63488 blocks.

Parent topic: Configuring the IMS Message Queue
Related tasks
To dynamically adjust the IMS message queue configuration
Related reference
Server Instance Properties: MSS IMS TM General
IMS Control


Dynamic IMS Message Queue Performance Tuning

By default, the Enterprise Server TM system unilaterally flushes operating system buffers to your physical disk at key transactional points. These flushes are required to guarantee the transactional integrity of the message queue in the event of a failure that abnormally stops Enterprise Server TM. The overhead required for this default behavior can significantly degrade performance. However, you can improve performance by setting alternative options at startup, and by adjusting those options on the fly.

ES_TMC_AGGREGATE environment variable

To initialize performance settings for the IMS message queue, and to enable dynamic performance tuning, we provide the ES_TMC_AGGREGATE environment variable. Specifically, its twofold purpose is to:

  • Specify, at startup, either the default or an alternative method for flushing operating system buffers to disk.
  • Enable you to dynamically change the flushing method and apply it to the message queue without having to restart the enterprise server region.

Set ES_TMC_AGGREGATE for a specific enterprise server region by adding it to the [ES Environment] section in the Configuration Information field located on the Administration Server > Properties > General tab. Use the following syntax:

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

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

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

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

Note:
  • Threads requesting a flush wait until the flush is confirmed.
  • Generally, when the message queue resides on a higher performance I/O subsystem such as one using SSDs, a smaller value, e.g. 1 or 2, produces the best results. A value of 10 or higher seldom improves performance.

Dynamic changes using ESMAC

You can adjust and apply IMS message queue performance settings dynamically from the TM System Overview and Control section on the ESMAC IMS Control page. Use this feature to test various performance settings, and to adjust performance on the fly when required.

Important: Performance results produced by the ES_TMC_AGGREGATE environment variable settings and the associated dynamic ESMAC settings are strictly dependent on the hardware and operating system on which Enterprise Server is running. Test rigorously before committing these settings to a production system.
Parent topic: Configuring the IMS Message Queue
Related tasks
To enable dynamic IMS message queue performance tuning
To dynamically tune IMS message queue performance
To dynamically adjust the IMS message queue configuration
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


Configuring IMS Printers

Enterprise Server supports LU1 and LU3 printers for use with enterprise servers configured to run IMS applications, and is specifically limited to printer clients that support the TCP TN3270 protocol. Non-TN3270 printer clients and the IMS Spool interface are not supported.

Prerequisites

Before configuring a printer, you must have an MSS-enabled enterprise server defined in Enterprise Server Administration. Once this is in place, do the following:
  • Specify a system initialization table
    We recommend that you either specify the provided SIT, IMSSIT, or that you copy the IMSSIT to another name and specify the newly copied SIT. IMSSIT is preconfigured with many of the requirements necessary to run a successful IMS application, including:
    • Initial Tran ID - This is set to /IMS, and specifies that interactive TN3270 clients initially connect to IMS TM.
    • IMSSTRT Startup List - Includes several resource groups that provide a number of resource definitions required for the basic operation of Enterprise Server. Group IMSGRP contains resource definitions that are specific to Enterprise Server and IMS operation.
    • IMSGRP Resource Group - Contains a TERM model definition for LU1 printers.
  • Ensure that your SIT is updated with current printer definitions

    When you upgrade from an earlier version of Enterprise Developer, user-specific resource groups such as IMSGRP are not updated automatically. We recommend that you add the current printer definitions manually. Do this by running the following command at an Enterprise Developer command prompt:

    caspcupg /o

Enabling Printer Support

The procedure for enabling printer support varies depending on your needs. Consider the following use case scenarios:

Use Case 1: Most or All Printers are LU1
No further configuration is required unless some printers are LU3 (see Use Case 3 below).
Use Case 2: Most or All Printers are LU3
In this case, rename the MLU1 printer Term Model definition in the IMSGRP resource group to MLU3, and redefine it as Term Model specifically for LU3 printers.
Important: You must rename and reconfigure the MLU1 definition, or remove it and create a new definition for LU3 printers. We do not support multiple Term Model printer definitions for TN32871.
Use Case 3: Define Specific Printers to Enterprise Server
In this case, you want to install explicit definitions for exceptions to Use Case 1 or 2, or for all printers. This requires that you add the printer definition or definitions to the IMSGRP resource group by adding a Term definition for each printer.

Additional Configuration

In addition to defining your printers, you must also configure the following:
  • Define the printer to Enterprise Server security
  • Configure your TN3270 emulator to attach to the printer

Assigning Client Names

In the process of configuring printers for an IMS-enabled enterprise server, you must provide a client name and other names in several areas of configuration. This can be tricky. Consider the following as you complete the configuration process:
  • The TN3270 client name is ultimately the IMS LTERM name that identifies the printer.
  • This client name must also appear in the Enterprise Server security system as a user ID. The printer operates under Enterprise Server with the security authorization assigned to this user ID.
  • When attached to Enterprise Server, this client name appears as the printer's Net Name on the Enterprise Server ESMAC Clients page.
  • If this client name/Net Name is not defined to Enterprise Server with a specific TERM definition, it is assigned the characteristics of the Enterprise Server TERM model definition with the model name of TN32871.
  • The TN3270 printer emulator Terminal Type definition must default to or be specified as IBM-3287-1. The TN3270 client name and terminal type are the controlling definitions.
  • Associated Enterprise Server definitions are used if they match the names specified in the TN3270 client.
Parent topic: Creating and Configuring an Enterprise Server Region for IMS
Related concepts
IMS TM Compatible Transaction Manager


Calculating Shared Memory Area Requirements

The shared memory area calculation for an IMS-enabled enterprise server is essentially the same as for a Web services enterprise server. Your calculation should also include 512 bytes for each 3270 client that is connected to the enterprise server. You must include your message processing regions in the total number of service execution processes.

If you are using CICS or JCL applications in the same enterprise server, in addition to the IMS calculation, perform the calculations described in the Shared Memory Area topics pertaining to CICS and JCL. Add the relevant results to the figure you calculated for IMS.

Parent topic: Creating and Configuring an Enterprise Server Region for IMS
Related concepts
Shared Memory Area
Shared Memory Area


IMS Database Administration

  • BTS Trace
    Describes the BTS trace feature, which enables you to view DL/I API calls and parameters issued by an IMS application.
  • IMS Database Locking
    Describes the tools available to lock your IMS database.
  • IMS Database Recovery
    Describes the options available for recovering a corrupted IMS database.
  • IMS Checkpoints
    Describes the IMS checkpoint functionality
Parent topic: Deploying IMS Applications


BTS Trace

The BTS trace feature logs DL/I API calls and parameters issued by an IMS application. You enable BTS trace from JCL. When JCL SSTM support is enabled, you can use the BTS trace feature to also trace IMS transactions, CICS transactions, and batch programs from CRUN.

Enable BTS Trace

You enable BTS trace from JCL using the following DD specifications:
IMSTRACE
Defines the output data set for the BTS trace. SYSOUT=* directs BTS output to the job. You can also direct output to a data file by specifying DCB=(RECFM=LSEQ,LRECL=80,DSORG=PS).
BTSCONFG
Enables control of BTS trace output options, and takes the following keywords:
SSA | Include segment search arguments, if any
PCB | Include the PCB area
PCBHELP | Include help text in the trace for invalid SSAs (AJ DL/I status code)
IOAREA | Include input-output buffer
STATS | Include call statistics
TIMES | Include call timings for performance measurement
DIAG | Include detailed diagnostic information
LISTFILE | In addition to the specified output data set, write BTS trace output to a compressed file named BTS-nnn.LST, where nnn is the process ID in decimal

These specifications apply to the current job step only, and override any BTS trace flags stored in the IMSCONFG.DAT configuration file.

Examples

Sample JCL
This sample JCL enables BTS trace in an IVP program named DEMO001B:
//S01       EXEC PGM=DFSRRC00,REGION=4M,
//          PARM='BMP,DEMO001B,DEMO001T,,,,,,,,,CDLI,,N,N'
//REPORT1   DD SYSOUT=*
//IMSERR    DD SYSOUT=*
//PRINTDD   DD SYSOUT=*
//SYSOUT    DD SYSOUT=*
//SYSPRINT  DD SYSOUT=*
//IMSTRACE  DD SYSOUT=*
//BTSCONFG  DD *
SSA
PCB
IOAREA
/*
//
Sample BTS output
This sample BTS output is from the DEMO001B program, and shows the DL/I call function, SSAs, PCB, and I/O area:
CBLTDLI:  ~~~~~~~~----+----1----+----2----+----3----+----4----+----5
CBLTDLI:  CALL   :GN
CBLTDLI:          4422
CBLTDLI:          7E00
CBLTDLI:  SSAS   : NONE
CBLTDLI:  PCB-003:DEMO03DD01  AP  ....DEMOHDRS...(............TEST
CBLTDLI:          44443344332245220000444444550002000000000000545522
CBLTDLI:          45DF034401001000000045DF84230008000200000000453400
CBLTDLI:
CBLTDLI:          22222222222222222222222222
CBLTDLI:          00000000000000000000000000
CBLTDLI:  IO AREA:........TEST                            Element Ta
CBLTDLI:          00000000545522222222222222222222222222224666667256
CBLTDLI:          00000000453400000000000000000000000000005C5D5E4041
CBLTDLI:          ble - Metals
CBLTDLI:          66622246766722222222222222222222222222222222222222
CBLTDLI:          2C50D0D541C300000000000000000000000000000000000000
CBLTDLI:                              ......N          .`0.
CBLTDLI:          22222222222222222222000000422222222220631222
CBLTDLI:          000000000000000000001C5C0CE0000000000000F000
CBLTDLI:  ~~~~~~~~----+----1----+----2----+----3----+----4----+----5
CBLTDLI:  CALL   :GN
CBLTDLI:          4422
CBLTDLI:          7E00
CBLTDLI:  SSAS   : NONE
CBLTDLI:  PCB-003:DEMO03DD02  AP  ....DEMOELES...F............TEST
CBLTDLI:          44443344332245220000444444450004000000000000545522
CBLTDLI:          45DF034402001000000045DF5C530006000200000000453400
CBLTDLI:                                    ..........Ag
CBLTDLI:          22222222222222222222222222000000000046222222222222
CBLTDLI:          00000000000000000000000000000000000017000000000000
CBLTDLI:
CBLTDLI:          222222
CBLTDLI:          000000
CBLTDLI:  IO AREA:..........Ag                  Silver
CBLTDLI:          00000000004622222222222222222256676722222222222222
CBLTDLI:          00000000001700000000000000000039C65200000000000000
CBLTDLI:
CBLTDLI:          22222222222222222222222222222222222222222222222222
CBLTDLI:          00000000000000000000000000000000000000000000000000
CBLTDLI:                    (    1 line(s) same as above )
CBLTDLI:                       ........
CBLTDLI:          22222222222220000000022222222222222222222222222222
CBLTDLI:          00000000000000000000C00000000000000000000000000000
CBLTDLI:
CBLTDLI:          222222222222222222222222
CBLTDLI:          000000000000000000000000
Parent topic: IMS Database Administration


IMS Database Locking

The type of database locking used for Enterprise Server applications that access IMS databases is based on their access mode, which can be either exclusive or shared.

Exclusive Access Mode Locking

Exclusive access mode is used for administration tools, utilities and batch application programs. Exclusive access locks an IMS database at the database level. The database is in non-sharing mode and available to a single process only. This access requires that the database is in a stopped state in Enterprise Server. Examples of exclusive access processes are:
IMS Database Editor tool
The tool is available only from the Enterprise Developer IDE and exclusively owned by the IDE process.
IMS Database Utility (IMSDBU)
Accessible from JCL, the command line, or the Enterprise Developer IDE. The IMS database data is opened exclusively by IMSDBU and owned by the process where IMSDBU was invoked.
Batch application program
A DLI or DBB batch application program running in a JES initiator uses the IMS Database Control process to open the database data exclusively on behalf of the application program running in a JCL initiator. In addition, you can use one of the following:
IMSLOCK DD statement
Enables you to direct batch program execution to process all IMS DB calls entirely in the JES initiator, providing significant performance improvement. To use this feature, add the following to your JCL:
//IMSLOCK DD *
(EXCLUSIVE | SHAREDGO)
/*
EXCLUSIVE
  • Highest performance batch
  • Requires exclusive access to the database
  • Does not allow GO sharing
  • Equivalent to setting the ES_IMS_ LOCALDLI environment variable
SHAREDGO
Shared get only (dirty read). Default.
ES_IMS_LOCALDLI environment variable
Deprecated. Directs batch program execution to process all IMS DB calls entirely in the JES initiator. All IMS DB control processes accessed from the batch program must be stopped before execution because they become exclusively owned by JES until the program completes.

Shared Access Mode Locking

Shared access mode is used for online programs such as IMS and CICS transactions and IMS BMPs.

Requirements

Shared access requirements are:

  • The application accessing the IMS database is running in an enterprise server instance
  • The database is not in a stopped state
The following are some examples of shared access:
  • IMS Transactions (MPP)
  • Batch message processing programs (BMP)
  • CICS transactions and batch programs from CRUN
  • ODBA applications from JES initiator using AERTDLI or DDBA interface

Locking

In shared access mode, IMS database locking occurs at the database record level. The DB record includes the root segment and all dependent segments. Secondary Index DBs lock the DB record of the target segment in the primary database. Logical relationships lock both the DB record where the logical child segment is defined and the DB record of the destination parent.

If a locked record is encountered while processing a DLI call, DB Control goes into lock retry. This retry continues until either the record lock is released or a wait time is exceeded. The wait time is controlled by environment variable:

 ES_IMS_LOCK_TIMEOUT=n

Where n is expressed seconds in the range of 0-65535. The default value is 30 seconds. A value of 0 indicates to wait forever.

The lock retry algorithm can also be tuned for performance. This delay interval controls the retry frequency and can be externally controlled by environment variable:

 ES_IMS_LOCK_RETRY_DELAY=n

Where n is expressed in milliseconds in the range of 0-65535. The default retry delay is 5 milliseconds.

When a lock wait period expires, a BD status code is returned to the DLI call and an error message written to the server console. It is not normal to have lock wait times expire; these should be researched. Possible causes for wait expirations are when an application holding locks is waiting on resources from another resource manager or suspended for some other reason. These can also happen when a system has become CPU starved due to other machine activity resulting in pausing of the application. This can be rectified by increasing the lock timeout value.

To help diagnose lock timeout issues, the following environment variable triggers a system dump when a timeout is detected:

 ES_IMS_DUMP_ON_TIMEOUT=1

Shared access databases can use one of two locking modes: traditional or IRLM. The locking mode is defined to IMS DB Control at Enterprise Server startup.

  • Traditional Locking
  • Internal Resource Lock Manager (IRLM)
  • Deadlocking
  • DB Control Queries
Parent topic: IMS Database Administration
Related tasks
To edit formatted field data
To edit unformatted field and segment data
Related reference
IMS-Specific Environment Variables


Traditional Locking

Traditional locking is the default locking mode and requires no configuration to implement. It uses the locking functions of the Micro Focus file handler. Locks are placed dynamically on the root segment at time of access and held until the unit-of-work reaches a commit point.

Locks are placed for both read and update DLI calls with no distinction between read locks, update intent locks or update locks. This implements the highest application isolation, which results in increased data contention and greater risk of deadlock.

Parent topic: IMS Database Locking


Internal Resource Lock Manager (IRLM)

IRLM locking closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock. Some benefits are:
  • Prevents multiple readers from blocking each other
  • Using passing scope lock release
  • Applications using a PCB that specifies PROCOPT=GO have no locking and no data constraint
  • Enabling IRLM Locking
  • IRLM Implementation
  • IRLM Lock Table Statistics
Parent topic: IMS Database Locking


Enabling IRLM Locking

To enable IRLM locking, you must set the following environment variable before starting your enterprise server instance:
ES_IMS_IRLM=1
Parent topic: Internal Resource Lock Manager (IRLM)
Related tasks
To edit formatted field data
To edit unformatted field and segment data
Related reference
IMS-Specific Environment Variables


IRLM Implementation

IRLM uses an IMS-specific lock table in DB Control. This lock table tracks locks by session using the database name and root segment relative-byte-address (RBA). This lock can define one of three lock states:

READ
Database record in use. Allows READ access from other sessions but blocks UPDATE-INTENT and UPDATE lock requests. If the application program PCB that issued the READ lock passes scope to another database record without updating any segments this READ lock is released.
UPDATE-INTENT
The database record is locked exclusively when accessed using a hold call (GHU, GHN, GHNP) which may be followed by a REPL or DLET call. If the application program PCB that issued the lock passes scope to another database record without updating any segments, this UPDATE-INTENT lock is released.
UPDATE
Database record has been updated via ISRT, REPL or DLET call and will remain locked until the application program reaches a commit point. These locks do not release on passing scope.
Parent topic: Internal Resource Lock Manager (IRLM)


IRLM Lock Table Statistics

From ESMAC, you can query lock table statistics using the following DB Control command:

/DIS DB /LOCK

A lock table query from ESMAC returns the:
  • Session ID
  • Relative PDB number
  • Lock type
  • Database
  • Relative byte address (RBA) of the locked database record

ESMAC Lock Table Query
Parent topic: Internal Resource Lock Manager (IRLM)


Deadlocking

IMS applications can deadlock, meaning that two or more programs cannot progress due to locking conflicts arising from accessing the same data resources at the same time, but in a different order. For example:

program-1 accesses segment-A, then segment-B

while at the same time,

program-2 access segment-B, then segment-A

This creates an AB-BA deadlock, halting progression for both applications.

Additional, more complex scenarios are also possible with three or more programs.

Resolving deadlock issues

The first line of defense against deadlocks is to avoid coding deadlock scenarios into your applications.

However, when a deadlock does occur, IMS DB Control can help by detecting deadlocks caused by contention for IMS database data.

Note: IMS DB Control does not detect deadlocks that involve multiple resource managers such as a data constraint between IMS DB and SQL.

When a deadlock occurs, DB Control chooses a loser and terminates the DLI call returning an FD status code. This FD status code triggers a system-issued ROLLBACK operation on behalf of the application program. IMS BMP and CICS programs receive the FD status code in response to the DLI call. IMS transactions automatically restart.

The deadlock loser is chosen based on the application type, number of DLI calls, and duration of execution. An IMS MPP is chosen before a CICS transaction, and a CICS transaction is chosen before a BMP. When the sessions involved in a deadlock are all of the same program type, the number of DLI calls in the current unit-of-work is compared and the session with the lowest number is chosen as the loser. If the number of DLI calls in the current UOW match, the session with the shortest duration is chosen as the loser.

By setting the ES_IMS_DEADLOCK_WAIT environment variable, you can delay the algorithm that tests for deadlocks. This ensures that DB Control threads don't spend CPU cycles at every data contention point:

 ES_IMS_DEADLOCK_WAIT=n

Where n is expressed in milliseconds in the range of 1-65535. The default value is 1000 milliseconds.

To help diagnose application deadlocks, the following environment variable triggers a system dump when a deadlock is detected.

 ES_IMS_DUMP_ON_DEADLOCK=1
Parent topic: IMS Database Locking
Related tasks
To edit formatted field data
To edit unformatted field and segment data
Related reference
IMS-Specific Environment Variables


DB Control Queries

From ESMAC, you can issue DB Control commands to view database statistics.
IMS DB Control status

Query IMS DB Control status using the command:

/DIS DB /STATUS

This returns various statistics for client sessions and DLI calls processed:
ESMAC Control Status

IMS DB Control session
Query the IMS DB Control session status using the command:

/DIS DB /SESSION

This returns various session statistics, including:

  • Session identifier (S-ID) - Corresponds to a JES initiator, MPP region or CICS SEP
  • Client process identifier (C-PID)
  • The ID of the process running the application
  • Control session status, which can be one of:
    Active | Thread actively processing the DLR call
    Idle | Thread idle waiting for application
    Blocked | Thread waiting on a blocked record
Additional statistics
In addition, the session query returns the:
  • Database
  • DLI function
  • Number of DLI calls in the current unit-of-work

If a session is blocked, the query also returns the:

  • RBA
  • Lock-holder session ID

ESMAC Session Query
Parent topic: IMS Database Locking


IMS Database Recovery

We provide several alternatives for recovering corrupted IMS databases:
  • Automatic Backward Recovery
  • Forward Recovery
  • Rebuild Utility

The Rebuild utility is part of Enterprise Developer File Handling. See Rebuild for more information.

To use Forward recovery, you must enable it. Backward Recovery is enabled by default. We recommend that you have both enabled, as together they provide the best coverage.

  • IMS Database Automatic Backward Recovery
    Describes the Backward Recovery feature used to protect the integrity of an IMS database.
  • IMS Database Forward Recovery
    Describes IMS database recovery using database image copies and forward recovery log files to restore the most recent database updates.
  • TLOG Files
    Describes the transaction log files (TLOGs) used in IMS database Backward and Forward recovery.
  • Rebuild Utility
  • IMS Batch Backout
  • Enterprise Server warm/cold start
Parent topic: IMS Database Administration


IMS Database Automatic Backward Recovery

Describes the Backward Recovery feature used to protect the integrity of an IMS database.

Automatic Backward Recovery is the first line of defense in protecting the integrity of an IMS database. It is the most expeditious method of restoring a database, thus minimizing the time that a particular database must be offline. Automatic Backward Recovery is disabled by default. When enabled, Enterprise Server invokes it automatically to check for and repair corrupted data when an IMS transaction or the IMS Database Engine fails, backing out uncommitted data for all databases specified in the unit of work, thereby restoring the database.

In addition, you can manually invoke Backward Recovery as a JCL job, or using the mfims imsdbu Rollback function from the command line. These options provide you with a means to control the time and circumstances under which a Backward Recovery is performed.

  • Automatic Backward Recovery Process
    Describes the Automatic Backward Recovery process.
  • Invoking Backward Recovery from JCL
    Describes how to invoke Backward Recovery from JCL.
Parent topic: IMS Database Recovery
Related concepts
IMS Database Forward Recovery
Recovery Utility
Rollback function
Related reference
Rollback function
Rebuild


Automatic Backward Recovery Process

Describes the Automatic Backward Recovery process.

By default, Automatic Backward Recovery is disabled.

Important: The handling of transaction log (TLOG) files for Backward Recovery differs depending on whether Forward Recovery is enabled or disabled. See TLOG Files for details.

Automatic Backward Recovery Disabled

During normal Enterprise Server startup or the restart of IMS Database Control, DBC determines whether or not the last execution of DBC shut down properly. If it did not, then DBC automatically scans the most current TLOG to determine if any databases require recovery. However, it does not initiate a recovery process. The name of each database that is determined to be corrupt is written to the ROLLBACK.LST file located by default in the %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESName (Windows) or /var/mfcobol/es/ESName (UNIX) directory, and DBC switches to a "suspend" mode. This means that normal transactional processing is prohibited. In this mode, DBC accepts only commands to recover, START, and STOP databases. In this case, you can manually recover any database from a JCL job or using the mfims imsdbu Rollback function. Once you have determined that all databases are properly recovered, use the /DBC RESUME command to restore DBC to full functionality. See IMS Database Control (DBC) Commands for more information.

Automatic Backward Recovery Enabled

You can enable automatic Backward Recovery by setting the ES_IMS_ROLLBACK environment variable in the configuration information for your enterprise server instance to 1. For example:
[ES-Environment]
ES_IMS_ROLLBACK=1

When started by a normal Enterprise Server startup or when triggered by an emergency, the IMS Database Control (DBC) process determines whether or not the last execution of DBC shut down properly. This is done by reading the DBC status file, IMSDBC.DAT, located by default in the %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESName (Windows) or /var/mfcobol/es/ESName (UNIX) directory. This file is updated with the status of each IMS database every time the database is shut down and each time its status changes.

When Enterprise Server starts up, DBC reads the most recent status for each database from the IMSDBC.DAT file and restores the databases that shut down normally to their most recent state.

If the IMSDBC.DAT indicates that one or more databases did not shut down properly, DBC invokes Backward Recovery automatically to restore each of those databases using the most recent transaction log (TLOG) file as input.

When recovery of all databases is complete, a summary of databases that were recovered and any warning or error messages returned during the recovery process are written to a list file, which by default is named ROLLBACK.LST and is located in the %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ESName (Windows) or /var/mfcobol/es/ESName (UNIX) directory.

Note: If DBC is unable to read the IMSDBC.DAT file for any reason, DBC starts up in a "suspend" mode, meaning that normal transactional processing is prohibited. In this mode, DBC accepts only commands to recover, START, and STOP databases. In this case, you can manually recover any database from a JCL job or using the mfims imsdbu Rollback function. Once you have determined that all databases are properly recovered, use the /DBC RESUME command to restore DBC to full functionality. See IMS Database Control (DBC) Commands for more information.
Parent topic: IMS Database Automatic Backward Recovery
Related concepts
Recovery Utility
Invoking Backward Recovery from JCL
TLOG Files
Related reference
Rollback function
Rebuild
Recover function
IMS Database Control (DBC) Commands


Invoking Backward Recovery from JCL

Describes how to invoke Backward Recovery from JCL.

To recover a database using JCL, you can invoke Backward Recovery.

To invoke Backward Recovery from JCL, include the following as part of a data SYSIN card:
TLOG=$ES_IMS_TLOG_PATH\tlogName.TLOG
where tlogName is the name of the TLOG file to be used in the recovery. For example:
//DBUJCL01 JOB 'IMS DATABASE UTILITY',CLASS=A,MSGCLASS=A
//*--------------------------------------------------------------------
//* Copyright (C) 1991-2010 Micro Focus (IP) Limited.
//* All rights reserved.
//*-------------------------------------------------------------------
//*
//* This job demonstrates using JCL to invoke Backward Recovery.
//*
//STEP01  EXEC PGM=MFDBUJCL,PARM='ROLLBACK'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
TLOG=$ES_IMS_TLOG_PATH\DMOAPPL-13070111330849.TLOG
/*
//
Note: As an alternative, you can recover a database from JCL using the Rebuild utility. See Rebuild Utility for details.
Parent topic: IMS Database Automatic Backward Recovery
Related concepts
Rebuild Utility
Automatic Backward Recovery Process
Related reference
Rollback function
Rebuild
Recover function


IMS Database Forward Recovery

Describes IMS database recovery using database image copies and forward recovery log files to restore the most recent database updates.

The process includes:

Preparing for Forward Recovery
  1. Run the Image Copy utility to make backups of all databases.
  2. Establish backup procedures to back up all databases at specified intervals moving forward.
  3. Enable forward recovery log files and set a location for generated log files.
  4. Establish backup procedures to back up all forward recovery log files at specified intervals moving forward.
Recovering IMS Databases
  1. Do one of the following:
    • Run the Image Restore utility to restore selected databases; then run the Recovery utility without specifying any image copy databases. This applies the updates from forward recovery log files to the databases found in the current location.
    • Run the Recovery utility specifying image copy databases. This restores the image copies and then applies the updates from forward recovery log files to the specified databases.
  2. Following each recovery done using the Recovery utility, always run the Image Copy utility to back up the recovered databases.
  • Preparing for Forward Recovery
    Describes procedures, prerequisites, and settings necessary for successful database recovery following a hardware or a system failure.
  • Image Copy Utility
    Describes the functions of the Image Copy utility and the JCL required to run it.
  • Image Restore Utility
    Describes the functions of the Image Restore utility and the JCL required to run it.
  • Recovery Utility
    Describes the functions of the Recovery utility, and the input and JCL required to run it.
Parent topic: IMS Database Recovery
Related concepts
IMS Project Components
IMS Database Automatic Backward Recovery
Rebuild Utility


Preparing for Forward Recovery

Describes procedures, prerequisites, and settings necessary for successful database recovery following a hardware or a system failure.

Back Up All Databases

Before you can recover a database, you must have a copy of it to restore. This requires that you perform database backups of all databases, and keep backup copies to use for recovery. Always back up your databases at predetermined recurring intervals. In the event that your database requires recovery, this can minimize the time required to restore the database, and minimizes risk when performing the recovery procedure.

Note: The Recovery utility always uses forward recovery log files to update an existing copy of the database even when, in certain situations, the restored backup copy is an empty, initialized database. Therefore, a backup copy of the database is always required for database recovery.

You can use any backup utility you choose. As an option, Micro Focus provides the Image Copy utility, which is part of our IMS Database Forward Recovery feature.

Important: Do not use any Micro Focus utilities on the backup image of a database before attempting to use the database copy for recovery. If you alter the database image in any way, the recovery fails.

Enable Forward Recovery Logging and Set Logfile Location

To use Forward Recovery, you must have the appropriate forward recovery log files in place. By default, forward recovery logging is turned off in Enterprise Server. Once enabled, Enterprise Server creates logs for all online database updates and for all database updates that occur as a result of executing a BMP transaction. To enable forward recovery logging and specify a location for generated forward recovery log files, include the following environment variables and settings in the [ES-Environment] specification entered into the Configuration Information field of Enterprise Server Administration for each enterprise server that updates an IMS database:

ES_IMS_ROLLFORWARD=YES
ES_IMS_TLOG_PATH=logFilePath
Important: Enterprise Server does not create forward recovery log files when databases are updated offline by batch programs running DLI or DBB mode. In these cases, we recommend that you create a backup of each affected database immediately following the completion of each batch job.

Set Up Log File Backup

Because the forward recovery log files are critical to database recovery, you must put something into place to back them up on a regular basis to preserve them. To successfully recover a database, all log files created by database activity that took place after the most recent database backup must be present for use by the recovery utility. All log files that contain records of database activity of any kind are required for a successful recovery, including log files that record only database query activity rather than database updates.

Never delete any log file until after the database has been backed up and you have verified that the log file is no longer needed.

Parent topic: IMS Database Forward Recovery


Image Copy Utility

Describes the functions of the Image Copy utility and the JCL required to run it.
The Image Copy utility copies all specified databases from their current location as defined by the ES_IMSDAT environment variable to a specified backup location. This is done using JCL that includes the following:
  • One STOP statement to stop each database you want to back up. All databases must be stopped before the Image Copy utility can back them up. For example:
    //STOP01    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
  • A JCL step to execute the Image Copy utility, IMAGECOPY. Optionally, you can also specify the VERIFY parameter to verify the contents of all copied databases. If a database is found to be corrupt, no copy is made. In this case, correct the problem by rebuilding the database before attempting to make another backup. The following example shows the VERIFY parameter in use:
    //IC       EXEC PGM=MFDBUJCL,PARM='IMAGECOPY,VERIFY'
  • Specify the name and location of each backed up database. The following example specifies that the copied databases be stored as GDGs, enabling you to keep multiple versions of the data:
    //BNKIC1   DD DSN=BNKTXN.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC3   DD DSN=BNKCUST.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC4   DD DSN=BNKACC.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(+1),DISP=(NEW,CATLG)
  • In the SYSIN statement, list each database you want to copy followed by the name of the DD that represents the location of the backed up database. Place the database name in the first eight columns. For example:
    //SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5

The following is a complete example of the JCL required to execute the Image Copy utility. It specifies that five databases, defined in the first eight bytes of SYSIN data, are to be copied to locations specified by the DD statements. Also, since the VERIFY parameter has been specified, an attempt is made to verify the integrity of the databases:

//RUNGDG JOB  'IC',CLASS=A,MSGCLASS=A
//*
//STOP01    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03    EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//IC       EXEC PGM=MFDBUJCL,PARM='IMAGECOPY,VERIFY'
//*
//SYSOUT   DD SYSOUT=*
//BNKIC1   DD DSN=BNKTXN.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC3   DD DSN=BNKCUST.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC4   DD DSN=BNKACC.IC.GDG(+1),DISP=(NEW,CATLG)
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(+1),DISP=(NEW,CATLG)
//SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START02  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START03  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//

If, for any reason, a database copy fails, the Image Copy utility creates an empty output dataset. In this case, you might want to delete the empty file before attempting to rerun the utility.

Important: Do not use any Micro Focus utilities on the backup image of a database before attempting to use the database image copy for recovery. If you alter the database image copy in any way, this causes the Recovery utility to fail.
Parent topic: IMS Database Forward Recovery


Image Restore Utility

Describes the functions of the Image Restore utility and the JCL required to run it.
The Image Restore utility copies a specified database image copy, overwriting the database with the same name, from the backup location to current location as defined by the ES_IMSDAT environment variable. If the ES_IMSDAT variable contains a concatenation of directories, each directory is searched for the matching database, and the database image copy is copied to the first directory found that contains a matching database. If the database is not found in any of the directories, the database image copy is copied to the first directory on the path.
Note: You can run the Image Restore utility to restore just the database, or you can restore the database and restore recent updates simultaneously using the Recovery utility.

An Image Restore job is run using JCL that includes the following:

  • One STOP statement to stop each database you want to restore. All databases must be stopped before the Image Restore utility can overwrite them. For example:
    //STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
  • A JCL step to execute the Image Restore utility, IMAGERESTORE. For example:
    //IC    EXEC PGM=MFDBUJCL,PARM='IMAGERESTORE'
  • Specify the name and location of each database you want to restore. The following example specifies that the copied databases are stored as GDGs, enabling you to keep multiple versions of the data:
    //BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2  DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3  DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5  DD  DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
  • In the SYSIN statement, list each database you want to restore followed by the name of the DD that represents the location of the backed up database. Place the database name in the first eight columns. For example:
    //SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5

The following is a complete example of the JCL required to execute the Image Restore utility. It specifies that five databases defined in the first eight bytes of SYSIN data are to be restored from the location specified by the DD statements to the location defined by the ES_IMSDAT environment variable:

//RUNGDG JOB  'IR',CLASS=A,MSGCLASS=A
//*
//STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP02  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//IC    EXEC PGM=MFDBUJCL,PARM='IMAGERESTORE'
//*
//SYSOUT   DD SYSOUT=*
//BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2  DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3  DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5  DD  DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
//SYSIN    DD *
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START04  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START05  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//
Parent topic: IMS Database Forward Recovery


Recovery Utility

Describes the functions of the Recovery utility, and the input and JCL required to run it.
Note: You can also run the Recovery utility as an mfims imsdbu function. See the Recover function topic for details.
Important: To successfully recover a database, all forward recovery log files containing records of all database activity that took place after the last database backup must be present for use by the Recovery utility. Log files must be unlocked to be used in recovery. To unlock log files, stop the server that created them.

The Recovery utility can restore image copy databases, the most recent database updates performed just before a hardware or a system failure, or database updates performed up until a specified point in time.

Upon completion, the Recovery utility output file reports the number of updates applied to each recovered database, according to each recovery log file specified. The updates include the number of writes, rewrites, deletes, and so on.

To restore database image copies, the Recovery utility accepts as input the name and location of each database backup file. Optionally, before running this utility, run the Image Restore utility to copy any database image copy to the current location. To update a database with the most recent changes, the relevant log files must be available on the path specified by the ES_IMS_TLOG_PATH environment variable. The Recovery utility determines the relevant log files required to recover each database.

The utility can recover up to 200 databases in each JCL job. Be aware, however, if the date and timestamp on any given database is significantly older than the other specified databases, we recommend that you recover that database separately to save time. To do otherwise could cause the utility to process a large number of log files unnecessarily, ultimately degrading performance.

By default, when one execution of a database forward recovery job specifies multiple databases, and the Recovery utility cannot recover one or more of the databases specified, it attempts to recover the remaining databases. This can happen, for example, when a required forward recovery log file is missing. In this case, the Recovery utility recovers the databases for which all log files are found. Upon completion of the job, the job SYSOUT dataset contains information indicating the databases recovered and those not recovered.

Optionally, you can specify that the recovery should abend upon encountering the first error. To do this, insert the keyword ABEND as the first statement following the SYSIN JCL card. If the ABEND keyword is specified and the recovery encounters an error, no databases are recovered.

Note: If you want to preserve the state of your current databases before recovery, be sure to copy them elsewhere before running the Recovery utility.

The Recovery utility copies database images as specified in the DD statements to the current location before applying the updates from the forward recovery log files. The JCL includes:

  • One STOP statement to stop each database you want to recover. All databases must be stopped before the Recovery utility can recover them. For example:
    //STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP04  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
  • A RECOVER statement to execute the Recovery utility. This statement must include the RECOVER and the SERVER parameters. The RECOVER parameter simply executes the utility; SERVER is required, and names the server that created the log files. The utility uses only those logs that are necessary to restore the specified databases. For example:
    //RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
  • Optionally, to specify a point in time at which to recover a database, add the PITR parameter. For example:
    //RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
//PITR=17123123595959

    For details on using the PITR parameter, see the Recover function topic.

  • If you want to restore one or more database image copies and simultaneously restore the information in the forward recovery log files, specify the name and location of each database you want to restore and also use the SYSIN statement to list each database, followed by the name of the DD that represents the location of the backed up database. Place the database name in the first eight columns. For example:
    //BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3   DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
.
.
.
//SYSIN    DD *
ABEND
BNKTXN       BNKIC1
BNKTXNX1     BNKIC2
BNKCUST      BNKIC3
BNKACC       BNKIC4
BNKTXNX2     BNKIC5
  • If you have previously restored the necessary databases using the Image Restore utility or any other database recovery utility, use the SYSIN statement to list each database you want to restore using forward recovery log files only:
    //SYSIN    DD *
ABEND
BNKTXN
BNKTXNX1
BNKTXNX2
BNKCUST
BNKACC

The following examples show the complete JCL required to execute the Recovery utility:

Example 1 - Restore database image copies, and database updates from forward recovery log files

//RUNGDG JOB  'RECOVERY',CLASS=A,MSGCLASS=A
//*
//STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP04  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//*
//RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
//*
//SYSOUT   DD SYSOUT=*
//BNKIC1   DD DSN=BNKTXN.IC.GDG(0),DISP=OLD
//BNKIC2   DD DSN=BNKTXNX1.IC.GDG(0),DISP=OLD
//BNKIC3   DD DSN=BNKCUST.IC.GDG(0),DISP=OLD
//BNKIC4   DD DSN=BNKACC.IC.GDG(0),DISP=OLD
//BNKIC5   DD DSN=BNKTXNX2.IC.GDG(0),DISP=OLD
//SYSIN    DD *
ABEND
BNKTXN         BNKIC1
BNKTXNX1     BNKIC2
BNKCUST       BNKIC3
BNKACC         BNKIC4
BNKTXNX2    BNKIC5
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START04  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START05  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*

Example 2 - Restore only database updates from forward recovery log files

//RUNGDG JOB  'RECOVERY',CLASS=A,MSGCLASS=A
//*
//STOP01  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//STOP03  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//STOP04  EXEC PGM=MFDBUJCL,PARM='/STO DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
//*
//RECOVER EXEC PGM=MFDBUJCL,PARM='RECOVER,SERVER=IMSBANK'
//*
//SYSOUT   DD SYSOUT=*
//SYSIN    DD *
ABEND
BNKTXN
BNKTXNX1
BNKTXNX2
BNKCUST
BNKACC
/*
//*
//START01  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKTXN'
//SYSOUT    DD SYSOUT=*
//START04  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKCUST'
//SYSOUT    DD SYSOUT=*
//START05  EXEC PGM=MFDBUJCL,PARM='/STA DB BNKACC'
//SYSOUT    DD SYSOUT=*
//*
Parent topic: IMS Database Forward Recovery
Related concepts
IMS Database Automatic Backward Recovery
Rebuild Utility
Automatic Backward Recovery Process
TLOG Files
Related reference
Rebuild
Recover function


TLOG Files

Describes the transaction log files (TLOGs) used in IMS database Backward and Forward recovery.

TLOG File Properties

You specify the properties for TLOG files using the following environment variables:

ES_IMS_DB_TLOG_WRITETHRU
When set to 0 (zero), forces the flushing of TLOG buffers to disk on COMMIT only (default). When set to 1, forces the flushing of TLOG buffers to disk on all database I/O.
ES_IMS_TLOG_PATH
The location of IMS DB transaction logging files. The default is the Enterprise Server system directory.
Note: Once created, you can move log files, but do not rename them. Before attempting to recover a database, all log files must reside in the directory specified by ES_IMS_TLOG_PATH.
ES_IMS_TLOG_COMPRESS
When set to 0 (zero), disables compression of the Backward Recovery TLOG file. When not compressed, the file contains only the information required to recover databases. The default is enabled.
Note: When enabled, Enterprise Server reclaims space in the file when information becomes obsolete.
ES_IMS_TLOG_FLUSH
When set to 1, forces the frequent flushing of TLOG and database buffers to disk.
Warning: Depending upon the number of database updates, the frequency of commits, and other computer activity, use of ES_IMS_TLOG_FLUSH could result in significant performance degradation.
Note: This environment variable is deprecated. Use ES_IMS_DB_TLOG_WRITETHRU to flush TLOG buffers and ES_IMS_DB_COMMIT_FLUSH to flush database buffers.
ES_IMS_TLOG_MAXSIZE
Maximum size of the IMS DB transaction logging file in bytes. The default is 4GB or h"FFF00000".
ES_IMS_TLOG_THRESHOLD
Threshold size of the IMS DB transaction logging file. When reached, the current TLOG file is closed and a new TLOG file created for subsequent transactions. The default is 2GB or h"7FFFFFFF".

TLOG File(s) used to Recover Databases

The actual TLOG file or files used to recover an IMS database depends on whether or not Forward recovery is enabled or disabled.

Forward Recovery Enabled
For both Forward and Backward recovery, use the most recent Forward recovery TLOG file.
Note: TLOG files created when Forward Recovery is enabled are not backed up because they are never overwritten.
Forward Recovery Disabled
For Backward recovery, use the default log file, IMSDB.TLOG, which is always backed up before a new one is created.

TLOG Naming Convention

With the exception of the IMSDB.TLOG file created and used when Forward recovery is disabled, Enterprise Server generates and renames TLOG files using this naming convention:

serverName-YYMMDDhhmmssmm.TLOG

Where serverName is the name of the server on which the database is stored, and YYMMDDhhmmssmm represents two digits for each: year, month, day, hour, minute, second, and millisecond.

Depending on the size of the database and the volume of transactions, recovery log files can become quite large. To better manage large-volume logs, Enterprise Server occasionally creates extension logs. The name of an extension log file is the same as the originating log file, plus an appended extension number such as 001, 002, etc.

During a recovery process, Enterprise Server uses log file time stamps to determine which log file or files are required for the restoration, and excludes out-of-date log files from the recovery. This minimizes the time required to complete the recovery.

TLOG File Contents

You can view the contents of a TLOG file using the cobfhtlog utility as follows:

  1. Start an Enterprise Developer command prompt. If you need instructions, see To start an Enterprise Developer command prompt.
  2. Change to the directory specified as your ES_IMS_TLOG_PATH environment variable.
  3. Enter:
    cobfhtlog filename
    Where filename is the name of a TLOG file.

The contents of the file are written to the screen. The following example represents a snippet of the contents of a TLOG file:

rollfwd data
    data len: 00019
    data    : 100000006 00000006
    …..
commit prep
     session: 0000000002
    sequence no: 00000000000000000006
    date time: 17081415252517
     …..
commit begun
     session: 0000000002
 sequence no: 00000000000000000007
     date time: 17081415252523
      …..
commit comp
     session: 0000000002
 sequence no: 00000000000000000008
     date time: 17081415252523
Note: In the above example, the date time value for commit comp represents a point in time you can use with the Recovery Utility and Recovery function PITR parameter. See Recovery function and Recovery Utility for details.
Parent topic: IMS Database Recovery
Related concepts
Automatic Backward Recovery Process
Recovery Utility
Related tasks
To start an Enterprise Developer command prompt
Related reference
Rollback function
IMS-Specific Environment Variables
Recover function


Rebuild Utility

When a database file has become corrupt and cannot be recovered by any other means, you must rebuild it. This situation is rare, but can occur if, for example, the file was open during a system crash.

To rebuild a corrupted database, use the Rebuild utility. You can execute Rebuild from the command line or from JCL. For complete documentation on using the Rebuild utility from the command line, see Rebuild.

To execute the Rebuild utility from JCL submission using MFDBUJCL:

  • The SYSIN data can specify a fully qualified database file or just the database file name.
  • Specify REBUILD as the parameter.
  • Use SYSIN data to name the file to be rebuilt and, optionally, an output file.

    With these files, the file extension, .DAT may be specified or not. If not specified, it is automatically appended.

  • The OUTPUT file is optional. If it is not included, then the database file is rebuilt in place.

    If you specify an OUTPUT file, then it becomes the rebuilt file and the INPUT file remains unchanged. In this situation, you must make sure that this output file is renamed to the original file name before it can be used.

Note:
  • If a database file requires a rebuild, then you should consider whether any associated index files should be rebuilt as well.
  • Make sure that there is enough free space on disk before submitting the rebuild job.

    You will need as much space as the file to be rebuilt requires, and if you have specified an OUTPUT file to be created in the same directory, then you need to account for the extra space requirement.

To invoke Rebuild from JCL, include the following step:
//STEP01  EXEC PGM=MFDBUJCL,PARM='REBUILD'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
OUT-PATH=DBPath
DB1
DB2
...
DBn
/*
//
where DBPath is the directory where the corrupted database files reside, and DB1, DB2, and DBn represent the names of each database to be rebuilt; however, the number of databases to rebuild is not limited. For example:
//STEP01  EXEC PGM=MFDBUJCL,PARM='REBUILD'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
OUT-PATH=C:\IMS\BACKUP\DATABASES
BNKCUST
BNKACC
BNKATYPE
/*
//
Parent topic: IMS Database Recovery
Related concepts
IMS Database Forward Recovery
Recovery Utility
Related reference
Rebuild


IMS Batch Backout

The Batch Backout utility allows database changes made by IMS batch applications (DLI and DBB) to be recovered either to a point prior to the start of the application or to a checkpoint.

Note:
  • Batch Backout is available only for offline batch IMS programs that access non-shared IMS databases. Batch IMS programs, both DLI and DBB, can only update IMS databases that are taken offline and made unavailable to online systems such as BMP programs, IMS transactions, CICS transactions and ODBA applications.
  • The Batch Backout utility can only be used for recovery of updates performed to offline IMS databases.
  • Batch Backout Implementation
  • Enabling Batch Backout Logging
  • Recovering Database Changes with the Batch Backout Utility
  • Restrictions and Limitations
  • Error Conditions
Parent topic: IMS Database Recovery


Batch Backout Implementation

To use the Batch Backout utility, you configure your IMS database update process to create batch backout log files. The Batch Backout process uses these log file to reverse changes. You can use the checkpoints that your applications set in these log files to back out selected changes only.

The Enterprise Server Batch Backout utility is similar in functionality to the IBM IMS batch backout implementation. The Enterprise Server implementation differs in the following ways:

  • The names of utilities, such as the backout program must not correspond to any names of similar utilities on the mainframe.
  • The format of the log files used as part of the database recovery process in the Enterprise Server implementation differs and is not compatible with the log files that are produced on the mainframe.
Note: Online IMS databases implemented in an Enterprise Server environment include dynamic (automatic) backout functionality. That is, when an application that has updated an online Enterprise Server environment IMS database abends, the uncommitted unit-of-work is backed out automatically, and does not require use of the Batch Backout utility. As a result, the features of Batch Backout that relate to the recovery of online databases are not needed and therefore unsupported in Enterprise Server.
Parent topic: IMS Batch Backout


Enabling Batch Backout Logging

Batch Backout logging for a batch IMS program is enabled in JCL by the presence of the BBOLOG DD statement. For example:

//BBOLOG  DD DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=(NEW,CATLG,DELETE)

IEFRDER and IEFRDER2 DD statements are ignored to avoid confusion with mainframe IMS logging and log record formats.

When enabled, updates to all IMS databases, along with checkpoint calls issued by the application program, are written to the BBOLOG dataset. Backup log files are extended as required in the event that they exceed size restrictions.

Standard JCL DSN management can be used for tracking these log datasets in the Enterprise Server catalog.

CAUTION:
When logging is enabled, the primary log file and any extensions must not exist. If the job detects that the primary or extended log file already exists, then the job terminates with an appropriate error message.

Below is sample batch JCL that specifies a BBOLOG dataset:

//IMSBATCH JOB 'MICRO FOCUS',CLASS=A,MSGCLASS=A
//* DLI PROGRAM EXECUTION
//*
//S01       EXEC PGM=DFSRRC00,REGION=4M,
//          PARM='BMP,DEMO001B,DEMO001T,,,,,,,,,CDLI,,N,N'
//REPORT1   DD  SYSOUT=*
//BTSLST    DD  SYSOUT=*
//IMSERR    DD  SYSOUT=*
//IEFRDER   DD  DUMMY
//BBOLOG    DD  DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=(NEW,CATLG,DELETE)
//PRINTDD   DD  SYSOUT=*
//SYSOUT    DD  SYSOUT=*
//SYSPRINT  DD  SYSOUT=*
//
Parent topic: IMS Batch Backout


Recovering Database Changes with the Batch Backout Utility

The Batch Backout utility processes a backout log file and removes the updates to the IMS databases that were issued from the program that created the log file. The log file is processed in reverse. Database updates can be rolled back either for the entire batch job or back to a specific checkpoint ID.

The input log file to the Batch Backout utility is specified on the BBOLOGI DD statement. The log file must be catalogued in Enterprise Server as follows:

//BBOLOGI DD DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=SHR

You can specify an optional recovery log file using the BBOLOGO DD statement. It too must be catalogued in Enterprise Server, for example:

//BBOLOGO DD DSN=HLQ.PRJ01.BBOLOG.RECOVERY,DISP=(NEW,CATLG,DELETE)

You can use this log output file in the event that the database file needs to be restored to its state before the backout utility was run. In this event, use this recovery log as the input log (BBOLOGI) to a subsequent run of the backout utility.

CAUTION:
it is important to be aware of the existence of the extension logs when backing up the logs or moving them to alternate locations. The recovery log to be created (that is the file associated with ddname BBOLOGO) data file and any extensions associated with it must not exist. In this event, the recovery job terminates with the appropriate error message.
  • Using Checkpoints with Batch Backout
  • Using Extended Log Files
  • Batch Backout Example JCL
Parent topic: IMS Batch Backout


Using Checkpoints with Batch Backout

Database updates can be rolled back either for the entire batch job or back to a specific checkpoint ID. The backout functionality is implemented in the MFDBUJCL IMS Database Utility JCL interface. You specify PARM='BBO' to activate batch backout. For example:

//BACKOUT EXEC PGM=MFDBUJCL,PARM='BBO'

If restarting from a checkpoint, the checkpoint ID is specified in the SYSIN DD, for example:

  //SYSIN   DD *
  CHKPT CHECK001
  /*

Checkpoint options are listed in the table below.

CHKPT Keyword | Behavior
LAST | Default. Restores to the point of the last successful checkpoint call.
ALL | Backs out all checkpoints.
checkpoint id | Restores to the checkpoint specified. This id is limited to eight characters.
Parent topic: Recovering Database Changes with the Batch Backout Utility


Using Extended Log Files

When database logging is enabled, it is possible that the log file can become so large that it is necessary to create one or more extended log files. In this event, the extended log file or files are created in the same directory as the primary log file. These files are not catalogued with Enterprise Server.

The naming convention for extended logs is that an underscore and a sequential numeric value is added to the end of the name of the primary log file. For example, if the primary log file is named BankDemoLog.dat, then the extended log files are named BankDemoLog.dat_1, BankDemoLog.dat_2, . . . BankDemoLog.dat_nn, . . .

CAUTION:
When a database batch job is submitted and logging is enabled, the primary log file and its extensions must not exist. If the job detects that the primary or extended log file already exists, then the job terminates with an appropriate error message. Similarly for the batch backout utility, if you want the optional recovery log to be created (that is the file associated with ddname BBOLOGO) , then that recovery data file and any extensions associated with it must not exist.

Consequently, it is important to be aware of the existence of the extension logs when backing up the logs or moving them to alternate locations.

Parent topic: Recovering Database Changes with the Batch Backout Utility


Batch Backout Example JCL

Below is sample JCL that invokes the backout process . In the example code:

  • The process uses the HLQ.PRJ01.BBOLOG.DEMO001T log file.
  • The backout process starts from the end of the log file, and backs out to the checkpoint CHECKOO1
  • The process creates the output log file: BBOLOG.BBOLOG2
//BBO    JOB 'IMSDBU BATCH BACKOUT',CLASS=A,MSGCLASS=A
//*
//* THIS JOB DEMONSTRATES THE BATCH BACKOUT UTILITY
//*
//BACKOUT EXEC PGM=MFDBUJCL,PARM='BBO'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
CHKPT CHECK001
/*
//BBOLOGI DD DSN=HLQ.PRJ01.BBOLOG.DEMO001T,DISP=SHR
//BBOLOGO DD DSN=HLQ.PRJ01.BBOLOG.BBOLOG2,DISP=(NEW,CATLG,DELETE)
Parent topic: Recovering Database Changes with the Batch Backout Utility


Restrictions and Limitations

Batch Backout is not supported for the following cases:

  • BMP programs: BMP programs participate with online shared IMS databases and are not eligible for backout processing.
  • GSAM databases are not supported for batch backout.
  • Databases which have been made available to online BMP programs, IMS transactions, CICS transactions or ODBA applications are no longer eligible for batch backout processing.
  • Batch Backout processing is currently limited to a single input log file. DD concatenation or multiple input DD statements are not supported. If there are multiple input log files, then you need to run the backout utility multiple times. Take care to process the files in the correct order.
  • Recovery after a crash in the Enterprise Server database engine may not be possible without external intervention.
Parent topic: IMS Batch Backout


Error Conditions

If the backout fails due to an error, the job returns an error condition of 20, and the database file is unchanged.

A return code of zero indicates success.

If an error occurs, then the following messages can be displayed in the job log. Use these messages to assist in problem determination and correction.

Message | Description
MFDBUJCL: PROBLEM WITH THE INPUT BACKOUT LOG | The input backout log may be corrupt or unreadable.
MFDBUJCL: PROBLEM WITH THE OUTPUT RECOVERY LOG. | In this event, the physical name of the recovery log file is displayed.
MFDBUJCL: PROBLEM WITH THE FILE TO BE RECOVERED | The physical name of the database file is displayed. If the file has been determined to be corrupt, then the error message indicates this as well as instructions for rebuilding the data file.
MFDBUJCL: ILLEGAL CONFIGURATION ITEM | This is an internal message.
MFDBUJCL: CHECKPOINT SET BUT NOT FOUND | A checkpoint was supplied in the SYSIN data but was not found in the log file.
MFDBUJCL: BACKOUT SUCCESSFUL. HOWEVER THE RECOVERY DATASET SHOULD NOT BE TRUSTED TO RUN A RECOVERY | This is a warning message. The backout of the dataset was complete, but the recovery log may be invalid and should not be used in a recovery of the dataset.

Additionally, the job log may display reason codes, files status codes or other messages which may help in problem determination.

Parent topic: IMS Batch Backout


Enterprise Server warm/cold start

The following applies to warm and cold starts of the Enterprise Server IMS Database Control feature.

  • All database statuses are set to NOTOPEN when an enterprise server is first started and when a cold start is performed.
  • When IMS Database Control is started via a warm restart, either by an automatic restart after the abnormal termination of Database Control or by a normal startup, database statuses are restored.
  • If a warm start is the result of Database Control termination and the databases have been left in an ambiguous state, they are recovered by the Backward Recovery process.
  • If a warm start is the result of Database Control termination and the databases are not recoverable, then they might be placed in a stopped state.
Parent topic: IMS Database Recovery


IMS Checkpoints

The following topics describe the IMS checkpoint functionality available in Enterprise Server:

  • Basic and Symbolic Checkpoint Calls
  • IMSLGR Files
  • Avoiding Dataset Contention
Parent topic: IMS Database Administration


Basic and Symbolic Checkpoint Calls

Enterprise Server supports basic checkpoint (CHKP) calls, and symbolic checkpoint and Extended Restart (XSRT) calls.

Basic CHKP Calls

The basic CHKP call is available from message-driven transactions as well as BMPs and batch programs. Basic CHKP commits the changes your program has made to the database and establishes places in your program from which you can restart your program in the event that it terminates abnormally.

Symbolic CHKP and XSRT Calls

Symbolic CHKP and XSRT calls are only available to BMPs and batch programs.

The symbolic CHKP call commits the changes your program has made to the database and establishes places in your program from which you can restart your program in the event that it terminates abnormally. In addition, the CHKP call:

  • Works with the XRST call to restart your program if it terminates abnormally. An XRST call is required before a CHKP call to indicate to IMS that symbolic check points are being taken.
  • Designates a checkpoint ID, which is a place within the program from which you can restart it should the program terminate abnormally.
  • Designates up to seven data areas in your program to be automatically restored when your program is restarted after an abnormal termination.

The checkpoint ID and save areas are stored in files named IMSLOGR.DAT and IMSLOGR.IDX.

If an XRST call indicates that a restart should take place, the save areas are restored into the program's Working-Storage section. The restart checkpoint ID can be specified in the XRST call itself or as part of the Batch Program Command used to start the batch program. All XSRT calls, successful or not, are logged in the IMS System Log.

If an XSRT call indicates that a restart should take place, the save areas are restored into the program's Working-Storage. The restart checkpoint ID can be specified in the XRST call itself or as part of the Batch Program Command used to start the batch program. All restart calls, successful or not, are logged in the IMS System Log.

Note:
  • An input GSAM file position RBA is saved on a checkpoint call and restored on a restart call.
  • An XRST call does not reposition any databases, nor does it restore any PCB information.
  • GSAM updates are committed to the data file when the update call completes.
Parent topic: IMS Checkpoints


IMSLGR Files

The IMSLOGR files contain the save areas and checkpoint IDs for Symbolic Checkpoint (CHKP) calls. The IMSLOGR files are created the first time a CHKP call is made, and appended for each subsequent CHKP call. It is read when a Symbolic Restart call (XRST) is issued to restore the program save areas. You should delete these files periodically as they could grow quite large; however, once deleted, you cannot use XRST calls to restart from the deleted checkpoints.

These files are created in the Listing folder of your Enterprise Developer project.

Parent topic: IMS Checkpoints


Avoiding Dataset Contention

IMS programs that make use of checkpoint/restart, for example the Batch Backout functionality can use the IMSLOGR DD statement to define the input log file to use.

You can use this in the JCL to avoid dataset contention with other concurrent checkpoint/restart programs. This log file is used to store checkpoint IDs, GSAM reposition information and application save areas during extended checkpoint processing.

Parent topic: IMS Checkpoints


WebSphere MQ Support

This version of Enterprise Server supports both the MQ-IMS Bridge and IMS trigger monitoring.

Prerequisites

In addition to Enterprise Server, you must have WebSphere MQ client or server installed on your PC. To see supported WebSphere MQ versions, see the WebSphere MQ section in Additional Software Requirements.

  • MQ-IMS Bridge
    Describes the MQ-IMS Bridge feature used to communicate with WebSphere MQ and process requests on Enterprise Server.
  • IMS Trigger Monitoring
    Describes Enterprise Server support for IMS Trigger Monitoring.
Parent topic: Deploying IMS Applications


MQ-IMS Bridge

The MQ-IMS Bridge feature enables you to capture incoming IMS transaction requests sent by an application to a WebSphere MQ queue, process those transactions on an enterprise server instance running an IMS application, and return output to the originating application via a WebSphere MQ output queue. When using an MQ listener with the MQ-IMS Bridge, this procedure requires no modifications to either the originating application or the IMS application.

Communications between Enterprise Server and WebSphere MQ are established by enabling MQ listener support and defining and enabling one or more MQ listeners in Enterprise Server.

An MQ listener is an Enterprise Server component that monitors messages sent to a specific WebSphere MQ queue. You can define an MQ listener to monitor either an input queue or an initiation queue. If you define the listener to monitor an initiation queue, Enterprise Server dynamically creates a listener for each associated input queue that receives inbound messages.

An MQ writer is an Enterprise Server component that sends messages back to a WebSphere MQ output queue. You do not define MQ writers. Enterprise Server creates them dynamically as needed.

The naming convention for all dynamically created listeners and writers is:

z#nnnnnn

nnnnnn is set initially to 000001, and is incremented by 1 with the creation of each subsequent listener or writer.

  • WebSphere MQ Configuration
    Describes the WebSphere MQ configuration requirements necessary to enable Enterprise Server to process MQ messages.
  • Enterprise Server Configuration
    Describes the Enterprise Server configuration requirements necessary to enable communication with WebSphere MQ.
  • MQ Listeners and Writers in ESMAC
    Describes what you can view and how you can modify MQ listeners and writers in ESMAC.
Parent topic: WebSphere MQ Support


WebSphere MQ Configuration

To use Enterprise Server MQ listeners and writers, you must configure WebSphere MQ Queue Manager to include an input queue and an output queue, and optionally an initiation queue:

Input Queue
This queue receives IMS transaction requests from your originating application.
Output Queue
This queue receives messages from the IMS application running on Enterprise Server.
Initiation Queue (optional)
If your queue manager in WebSphere MQ has a defined initiation queue, WebSphere MQ notifies that initiation queue when a message arrives at an input queue defined for the same queue manager. If you create your MQ listener in Enterprise Server to listen to an initiation queue rather than an input queue, Enterprise Server dynamically creates a listener for each input queue that receives a message. This can provide an advantage if your IMS application running on Enterprise Server is required to process messages from multiple input queues.

For complete information on creating and configuring MQ queues, see your IBM WebSphere MQ documentation.

Parent topic: MQ-IMS Bridge


Enterprise Server Configuration

To use Enterprise Server with the MQ-IMS Bridge, you must configure the following in an IMS-enabled enterprise server instance:

  1. Enable MQ listener support in Enterprise Server Administration.
  2. Create and enable an MQ listener for a WebSphere MQ queue.
Parent topic: MQ-IMS Bridge


MQ Listeners and Writers in ESMAC

With MQ listener support enabled, you can do the following in ESMAC with regard to MQ listeners and writers:

  • Monitor listener and writer activity
  • Start and stop listeners
  • Delete listeners and writers
  • Write dump information to the casdump.rec file
Parent topic: MQ-IMS Bridge


IMS Trigger Monitoring

Enterprise Server provides functionality for WebSphere MQ Trigger Monitoring for IMS, allowing IMS MPP programs to be scheduled when WebSphere MQ messages arrive on a designated WebSphere MQ queue.

Depending on your user granted permissions, you can do all or some of the following:

  • Start and stop the trigger monitor
  • Generate the PSB for the trigger monitor
  • Create the required XA resource

To enable trigger monitoring, IBM WebSphere MQ Server or IBM WebSphere MQ Client must be installed on the machine where Enterprise Server is running.

WebSphere MQ objects required for triggering must be defined. These are:
  • An application queue with the trigger control set on, a recommended trigger type of 'First'. The application queue will reference the process and initiation queue.
  • A process definition with the application type set to an integer value of 3 and an application id set to the IMS MPP transaction to be started. (The integer value of 3 for the application type is the numeric designation for IMS and ensures compatibility with WebSphere MQ UNIX installations.)
  • An initiation queue
The objects need to be defined from the WebSphere MQ command line or IDE. See IBM WebSphere MQ Queue Parameters documentation for details on how to do this.
  • Configuring Enterprise Server for WebSphere MQ Trigger Monitors
  • Security
  • Terminating an IMS Trigger Monitor Listener
Parent topic: WebSphere MQ Support


Configuring Enterprise Server for WebSphere MQ Trigger Monitors

The Enterprise Server region must be configured for both IMS and JES. For JES, you must define a batch initiator to process “class A” jobs. You need to ensure that enough initiators are defined for the job class to run all instances of the trigger monitor plus any other submitted jobs that will run under that class.

You also need to generate a PSB for the trigger monitor and create an XA resource to allow MPP applications to interface with IBM WebSphere MQ. A sample PSB definition file, csq4trmn.psb is included in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src (Windows) or $COBDIR/src/enterpriseserver/ims/mq (UNIX) folder.

The path to any IMS MPP transactions that are started by the Trigger Monitor must be present on the IMS TM Application Path.

If you have not installed the IBM MQ client or server in the default location, you must use the ES_MQ_LIB environment variable (or the ES_MQ_LIB_T environment variable for threaded environments) to identify the full name including the path of the IBM MQ library appropriate to your 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)"
In addition, you must also:
  • Enable MQ listener support in Enterprise Server Administration
  • Define an MQ listener to monitor the appropriate initiation queue
Parent topic: IMS Trigger Monitoring


Security

If security is enabled, the trigger monitor will run under the userid that submitted the JCL to start the trigger monitor.

Parent topic: IMS Trigger Monitoring


Terminating an IMS Trigger Monitor Listener

Trigger monitor listeners are automatically terminated when the enterprise server instance is stopped. However, you can also force termination of a trigger monitor listener using any of these methods:

  • Use the casout /o command.
  • Use a program to place the CSQ4TRMN:STOP message on the WebSphere MQ initiation queue that the trigger monitor monitors.
  • Submit CSQ4STOP.JCL using the JCL Control Page in ESMAC. CSQ4STOP.JCL is located by detault in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src (Windows) or $COBDIR/src/enterpriseserver/ims/mq (UNIX) .
  • Use an IBM-supplied utility such as amqsput or amqsputc.
Parent topic: IMS Trigger Monitoring


How to

  • IMS Projects
  • IMS Segment Layout Editor
  • IMS Database Editor
  • IMS Enterprise Server Configuration
Parent topic: IMS Support


IMS Projects

  • To set IMS project properties
  • To define the MFS null character
  • To define how MFS attributes are coded
  • To load an IMS database
  • To edit DBD, MFS, and PSB files
  • To set project and file properties for .DBD, .MFS or .PSB source files
  • To specify the location of the IMS copybook paths
Parent topic: How to


To set IMS project properties

  1. From the COBOL Explorer, double-click Properties under your IMS project.
  2. Expand Micro Focus > Project Settings > IMS.
  3. Use the Browse buttons to select a directory for your generated files and your IMS database.
  4. Click PSB Settings, DBD Settings, and MFS Settings to set properties for each.
    Note: To specify additional or non-default compiler directives, type them into the Additional Directives box, separating each by a space.
  5. Click Save, and close the Properties window.
Parent topic: IMS Projects
Related concepts
IMS Project Properties


To define the MFS null character

Transaction level

  1. In the drop-down list under Resources on the ESMAC menu, select IMS.
  2. Click Transact.
  3. Click Details for the transaction to be modified, or New if you are creating a new transaction.
  4. Select the appropriate value for the MFS Null field. Where you set this to [default], the value set at Enterprise Server level (see below) will be used.
  5. Click Add or Apply as appropriate.

Enterprise Server level

  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and TM tabs.
  3. Select the desired value for MFS null character field.
    Note: You can override this value at transaction level.
  4. Click Apply.
Note: This task is only applicable if the codeset bias being used is 'ASCII'.
Parent topic: IMS Projects
Parent topic: IMS Enterprise Server Configuration
Related concepts
Migrating Existing IMS Applications
MFS Conversion Issues


To define how MFS attributes are coded

Transaction level

  1. In the dropdown list under Resources on the ESMAC menu, select IMS.
  2. Click Transact.
  3. Click Details for the transaction to be modified, or New if you are creating a new transaction.
  4. Select the appropriate value for the MFS Attributes field. Where you set this to 'Default', the value set at Enterprise Server level (see below) will be used.
  5. Click Add or Apply as appropriate.

Enterprise Server level

  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and TM tabs.
  3. Select the desired value for MFS attribute bias field.
    Note: You can override this value at transaction level.
  4. Click Apply.
Note: This task is only applicable if the codeset bias being used is 'ASCII'.
Parent topic: IMS Projects
Parent topic: IMS Enterprise Server Configuration
Related concepts
Migrating Existing IMS Applications
MFS Conversion Issues


To load an IMS database

To load a database you can either use the database management utility (as described in the section IMSDBU Utility) or perform the following steps:

From within the IDE

  1. In COBOL Explorer, right-click a .dbd file in your project, and click Database Utilities > Load.
  2. In the Load IMS database dialog, specify the .dat file to use in the Input/Output file name field.
  3. Set the correct File layout and any other settings as required, and click OK.

From an Enterprise Developer command prompt

  1. Navigate to the folder containing the .dat files.
  2. Enter the following command for each .dat file:
    mfims imsdbu load datfilename
Note: If you have more than one database to load you can use the Windows for command to simplify this operation, for example:
for %i in (*.dat) do mfims imsdbu load %i
datfilename is case sensitive.
Note: datfilename is case sensitive.

By default, this loads the database from a file with the same basename as datfilename but with the extension .DBU. You can change this behavior using the DSN and LAYOUT options.

From JCL

Execute the MFDBUJCL utility:

//step EXEC PGM=MFDBUJCL,PARM='LOAD,database,dataset'
//SYSOUT DD SYSOUT=*

Where database is the name of the database and dataset is the data set where the database is located. For more information about the MFDBUJCL program, see IMSDBUJCL Utility.

Parent topic: IMS Projects
Related concepts
Load the IMS database
IMS Database Utility (IMSDBU)
Database Load Conversion Issues
Related reference
Load function


To edit DBD, MFS, and PSB files

To edit a .dbd, .mfs, or .psb file in an Eclipse editor:

  • In the COBOL Explorer, right-click a .dbd, .mfs, or .psb file; then select Open With from the context menu.
  • Depending on the type of file you want to edit, select DBD Editor, MFS Editor, or PSB Editor, respectively, from the context menu.

    These Eclipse editors provide a basic level of colorization for items such as reserved words and comments. They do not support background parsing or syntax checking.

In addition to directly editing one of these file types, you can also edit database data for .dbd and .psb files using Micro Focus Classic Data File Tools. For details, see IMS Database Editor .

Parent topic: IMS Projects


To set project and file properties for .DBD, .MFS or .PSB source files

You can set IMS properties that apply to all files in your project from the project properties:

  1. Click the project in COBOL Explorer.
  2. Click Project > Properties.
  3. Expand Micro Focus > Project Settings, and expand IMS to view the IMS-specific project properties.

Files in your project inherit the properties set for the entire project. If you set individual file properties, these settings override the properties set on project level:

  1. In COBOL Explorer, right-click a .dbd, .mfs or a .psb file, and click Properties.
  2. In the file properties dialog, specify settings and type Compiler directives as required.
  3. Click Apply, and then click OK.
Parent topic: IMS Projects
Related concepts
IMS Project Properties
Related reference
mfims generation directives


To specify the location of the IMS copybook paths

You use the IMSCPY environment variable to specify the location of the IMS copybook files at compile time for the DBDGEN, PSBGEN and MFSGEN utilities.

To set IMSCPY from within the IDE:

  1. In the project’s properties, expand Micro Focus, and click Build Path > Dependency Paths.
  2. Set Type to IMS Copy Paths, and select the paths to the folders that include IMS copybook files.

    The copybooks that are found in these folders will be used at compile time.

Parent topic: IMS Projects


IMS Segment Layout Editor

  • To create a debug information (.idy) file for layout file input
  • To start the Segment Layout Editor
  • To create a new segment layout file
  • To load program information
  • To define segment layouts
  • To define or edit a condition for a conditional layout
  • To edit an existing segment layout file
  • To view layout information in the Layout Editor window
Parent topic: How to


To start the Segment Layout Editor

To start the Segment Layout Editor from your Eclipse project:

  1. In Eclipse, open the project that contains your COBOL program.
  2. In the Project Explorer, expand the COBOL Programs folder to show the COBOL programs in the project.
  3. Right-click the COBOL program that contains the Data Division on which you want to base your new segment layout file; then select Create Segment Layout File from the context menu.
  4. Select an IMS database from the list; then click Create.

To start the Segment Layout Editor from Classic Data File Tools:

Note: To do this, you must start the Classic Data File Tools UI from your Eclipse project.
  1. In the Classic Data File Tools UI, click File > New > Segment Layout; then click OK.
  2. Select an IMS database from the list; then click Create.
  3. Navigate to and select the .idy file generated for the COBOL program that contains the Data Division on which you want to base the segment layouts; then click OK.
Parent topic: IMS Segment Layout Editor
Related concepts
Input
Related tasks
To create a debug information (.idy) file for layout file input
To start Classic Data File Tools
To create a new segment layout file
To load program information
Related reference
IMS Segment Layout Editor Window


To create a new segment layout file

  1. Create a debug information file for the program containing the data division you want to use for the new record layout file. See To create a debug information (.idy) file for layout file input for instructions.
  2. If you haven't compiled your DBD file since last making changes to it, compile it now.
  3. Start the Segment Layout Editor. See To start the Segment Layout Editor for instructions.
  4. To find out how to add segment layouts to the segment layout file, see the To define segment layouts.
  5. When you have finished, click File > Save to save the segment layout file.

    The folder defaults to the folder containing the IMS database. The filename defaults to the same name as the IMS database name with a .slf extension.

  6. Click Save.
  7. To close the Segment Layout Editor, click File > Close.
Note: As long as you retain the default settings when you save the segment layout file, the IMS Database Editor loads the file automatically with the database.
Parent topic: IMS Segment Layout Editor
Related concepts
Input
Output
IMS Database Editor
Related tasks
To define segment layouts
To create a debug information (.idy) file for layout file input
To start the Segment Layout Editor
Related reference
IMS Segment Layout Editor Window
New Segment Layout wizard


To load program information

  1. Generate an .idy debug information file for the COBOL program that contains the Data Division you want to load. See To create a debug information (.idy) file for layout file input for instructions.
  2. Start the Segment Layout Editor.
  3. Right-click inside the Segment Layout Editor window; then select Load Program Information from the context menu.
  4. Locate the .idy file that contains the Data Division from which you want to extract layouts.
  5. Click Open.

    The Segment Layout Editor loads the Data Division of the selected COBOL file into the left pane of the Segment Layout Editor window.

Parent topic: IMS Segment Layout Editor
Related concepts
Input
Related tasks
To create a debug information (.idy) file for layout file input
To start the Segment Layout Editor
To edit an existing segment layout file


To define segment layouts

  1. In the Segment Layout Editor with a Data Division loaded, expand the structure tree in the left pane; then and select a data item for which you want to create a segment layout.
  2. Right-click the data item; then select New Layout from the context menu. This starts the New Segment Layout wizard.
  3. Select a segment to which you want to apply the layout.
  4. Select either Default Layout or Conditional Layout; then click Next.
  5. Click Finish.
  6. Create additional layouts as required.
Note:
  • To delete a segment layout, right-click it in the right pane of the Segment Layout Editor; then click Delete.
  • Each segment layout file requires at least one segment layout, and may contain default or conditional layouts for the segments defined for the database.
  • For each conditional layout, you must define one or more conditions.
Parent topic: IMS Segment Layout Editor
Related concepts
Segment Layout Types
Segment Layout Names
Output
Related tasks
To create a new segment layout file
To edit an existing segment layout file
Related reference
New Segment Layout wizard


To edit an existing segment layout file

  1. From the Classic Data Tools UI, click File > Open.
  2. From the Files of type list, select All Files (*.*).
  3. Locate a segment layout (.slf) file in its folder; then click Open.
    The Segment Layout Editor shows only the segment layouts already defined in the current segment layout file. From here, you can:
    • Define new conditions
    • Edit existing conditions
    • Create additional layouts
      Note: To create additional layouts, you must first load program information. See To load program information for instructions.
  4. When you have finished, click File > Save .
Parent topic: IMS Segment Layout Editor
Related tasks
To load program information
To define segment layouts
To define or edit a condition for a conditional layout
Related reference
IMS Segment Layout Editor Window


IMS Database Editor

  • To add a twin segment occurrence
  • To add a first child segment occurrence
  • To apply segment layouts
  • To bookmark a segment type
  • To change the length of a segment occurrence
  • To configure edit warnings
  • To cut, copy, and paste data
  • To define an SSA
  • To delete a bookmark
  • To edit formatted field data
  • To edit unformatted field and segment data
  • To exclude or include segments in a browse session
  • To find your current position in the database
  • To go to a bookmarked segment type
  • To initialize data
  • To make a DL/I call
  • To modify a segment occurrence
  • To delete a segment occurrence
  • To load bookmarks from a file
  • To save your bookmarks in a file
  • To search an IMS database for a string
  • To set Classic Data File Tools options
  • To start the IMS Database Editor
  • To undo edits
  • To browse data in an IMS database
Parent topic: How to


To add a twin segment occurrence

  1. If browsing the database, click End Browse end browse.
  2. Optionally, click [image] on the IMS Database Editor toolbar to move to the start of the database.
  3. On the toolbar, click [image] until you are positioned on the segment for which you want to add a twin occurrence.
  4. Do one of the following:
    • Edit the data that is already there
    • From the IMS Database Editor menu, click Edit > IMS DB Editor > Initialize Segment to initialize the segment. When you do this, you can optionally choose a different segment layout than the current layout.
  5. Edit the key field to make it unique.
  6. Edit any other fields as required.
  7. When you have finished editing all the fields you want to change, click * to issue an ISRT DL/I call.

    Your current position in the database moves to the new segment occurrence.

Note:
  • If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
  • You cannot add a new segment occurrence while the Browse window is open.
  • Before clicking *, you can cancel the insert at any time by clicking Edit > IMS DB Editor > Undo Segment Edit.
Parent topic: IMS Database Editor
Related concepts
Editing Segment Data
Related tasks
To configure edit warnings
Related reference
IMS Database Editor window


To add a first child segment occurrence

  1. If browsing the database, click End Browse end browse.
  2. Optionally, click [image] on the IMS Database Editor toolbar to move to the start of the database.
  3. On the toolbar, click [image] until you are positioned on the parent segment for which you want to add a child occurrence.
  4. In the tree view, expand the parent segment type.
  5. Click the segment type that appears directly below the parent segment type.
  6. From the IMS Database Editor menu, click Edit > IMS DB Editor > Initialize Segment to initialize the segment. When you do this, you can optionally choose a different segment layout than the current layout.
  7. Edit the key field to make it unique.
  8. Edit other fields as required.
  9. When you have completed all required editing, click * to issue an ISRT DL/I call.

    Your current position in the database moves to the new segment occurrence.

Note:
  • If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
  • You cannot add a new segment occurrence while the Browse window is open.
  • Before clicking *, you can cancel the insert at any time by clicking Edit > IMS DB Editor > Undo Segment Edit.
Parent topic: IMS Database Editor
Related concepts
Editing Segment Data
Related tasks
To configure edit warnings
Related reference
IMS Database Editor window


To apply segment layouts

  1. From the IMS Database Editor, click File > IMS DB Editor > Load Segment Layouts.
  2. Use the Open dialog box to locate and open a .slf segment layout file.
Parent topic: IMS Database Editor
Related concepts
Editing Segment Data
Related reference
IMS Database Editor window


To bookmark a segment type

  1. On the tree view, right-click a segment type; then select Add bookmark from the context menu.
  2. Type a meaningful description into the Enter a note to be associated with this field. Optional.
  3. Click OK.
Note:
  • You can add a bookmark to the current segment occurrence only.
  • You cannot add a bookmark while the Browse window is open.
  • You can only bookmark a segment occurrence that has a unique concatenated key.
Parent topic: IMS Database Editor
Related concepts
Bookmarking Segment Occurrences
Related reference
Add bookmark dialog box
Bookmarks dialog box


To change the length of a segment occurrence

  1. Click Edit > IMS DB Editor > Set Segment Length.
  2. In the New segment length field, type a new segment length.
  3. Click OK.
Note:
  • The segment must be defined as variable length.
  • If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
Parent topic: IMS Database Editor
Related concepts
Editing Segment Data
Related tasks
To configure edit warnings
Related reference
IMS Database Editor window
Set Segment Length dialog box


To configure edit warnings

To turn edit warnings on or off as the default
  1. From the Classic Data File Tools UI, click Options > DataTools.
  2. To configure warnings for the IMS Database Editor, click the IMS DB Editor tab.
  3. To turn on the Delete and/or Update warning messages, check the appropriate box(es).
  4. To turn off the Delete and/or Update warning messages, uncheck the appropriate box(es).
  5. Click OK.
Important: Changes take effect the next time you open a database. Therefore, new settings do not take effect for any currently open databases.
To turn off edit warnings for the current editing session
  • When an edit warning prompt appears, check the Switch warning off box before responding to the prompt.
Parent topic: IMS Database Editor


To define an SSA

  1. From the tree view or the segment information window, double-click the segment type for which you want to define an SSA.
  2. Do one of the following:
    To define an unqualified SSA
    1. Select Unqualified SSA for segment-type, where segment-type is the selected segment type.
    2. If the segment does not have a unique key defined, select a code other than Null from the Command Code drop-down list.
    To define a qualified SSA
    1. Select Qualified SSA; then click Define.
    2. If the segment does not have a unique key defined, select a code other than Null from the Command Code drop-down list.
    3. Use the fields and controls in the Define qualifier section to build a list of qualifications on the Qualification list. See Qualifications for segment dialog box for a description of each field and control.
      Note: If you are using Boolean operators, the last qualification statement on the Qualification list must be blank.
    4. Click OK.
  3. Click OK.
Note:
  • The IMS Database Editor supports SSAs for up to 10 databases.
  • The IMS Database Editor does not support command codes for segments with unique keys defined. Therefore, for such segments, command codes are disabled.
Parent topic: IMS Database Editor
Related concepts
Navigating an IMS Database
Retrieving Data
Related reference
Define SSA dialog box
Qualifications for segment dialog box


To delete a bookmark

  1. Anywhere in the tree view area, right-click; then select Goto bookmark from the context menu.
  2. On the segment list, click the bookmark you want to delete; then click Delete bookmark.
Parent topic: IMS Database Editor
Related concepts
Bookmarking Segment Occurrences
Related reference
Add bookmark dialog box
Bookmarks dialog box


To edit formatted field data

  1. Start the IMS Database Editor.
  2. Apply a segment layout file.
  3. In the Layout view, click a field in the Value column.
  4. Do one of the following:
    • To add data to a blank field, type the data into the field.
    • To modify existing data, overtype the data in the field.
    • If the data in the field is invalid, you are prompted to initialize it; click Yes to initialize the field or No to leave it as it is.
  5. When you have finished editing the field, press Enter.
Note: The following apply when editing formatted field data:
  • If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
  • You can undo an edit after pressing Enter and before clicking in a different part of the IMS Database Editor window: Click Edit > IMS DB Editor > Undo Segment Edit.
  • You can toggle between Insert and Overtype mode by pressing Insert.
  • You can cut or copy data to the Windows clipboard and paste in the data somewhere else.
  • If you paste text into other editors, nulls are replaced with spaces.
  • For fields that are not PIC X fields, you can only select and copy the whole field. You cannot select part of the field and you cannot cut the field.
Parent topic: IMS Database Editor
Related concepts
Enabling IRLM Locking
Deadlocking
IMS Database Locking
Editing Field Data
Related reference
IMS-Specific Environment Variables
IMS Database Editor window


To edit unformatted field and segment data

  1. In the IMS Database Editor, retrieve a segment occurrence. The data for the occurrence appears in the Segment or Field data area at the bottom of the window.
  2. Click in the Segment or Field data area and do one or more of the following:
    • Edit the data fields directly.
    • Use ISRT, REPL, and DLET DL/I calls to insert, replace, and delete segments.
    • Progress from one segment to another using GHN, GHNP, and GNU DL/I calls.
Note: If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
Parent topic: IMS Database Editor
Related concepts
Enabling IRLM Locking
Deadlocking
IMS Database Locking
Editing Field Data
Related tasks
To configure edit warnings
Related reference
IMS-Specific Environment Variables
IMS Database Editor window


To exclude or include segments in a browse session

To exclude a segment
Right-click a segment on the tree view; then select Browse Exclude Segment segment-name from the context menu.

The Exclude segment go to current segment icon appears next to the segment name in the tree view. All child segments of the excluded segment are also excluded.

To include a segment
On the tree view, right-click a previously excluded segment; then select Browse Include Segment segment-name from the context menu.

The Exclude segment go to current segment icon disappears.

To override an exclude for a child segment
Although the include or exclude setting of a parent segment is automatically propagated to all child segments, you can manually change the setting of an individual child segment to override its setting. If you include a child segment, its parent segments are also included.
Parent topic: IMS Database Editor
Related tasks
To browse data in an IMS database


To find your current position in the database

  • Click *.

    The tree view displays the Current Segment Arrow * next to the current segment type.

Parent topic: IMS Database Editor
Related concepts
Navigating an IMS Database


To go to a bookmarked segment type

  1. On the tree view, right-click a segment type; then select Goto bookmark from the context menu.
  2. On the segment list, click the bookmark that marks the segment type you want to go to; then click Goto bookmark.
Parent topic: IMS Database Editor
Related concepts
Bookmarking Segment Occurrences
Related reference
Add bookmark dialog box
Bookmarks dialog box


To initialize data

To initialize a field
  1. In the Layout view, click the field you want to initialize.
  2. Click Edit > IMS DB Editor > Initialize Field.

    An alphanumeric field initializes to spaces. A numeric field initializes to zeros.

Note: Where the segment occurrence uses a conditional segment layout, you cannot initialize any test fields associated with that layout.
To initialize an unformatted segment occurrence or to initialize a formatted segment occurrence without changing its layout
  1. On the tree view, select a segment occurrence to initialize.
  2. Click Edit > IMS DB Editor > Initialize Segment.
Note: If the segment occurrence being initialized uses a conditional segment layout, test fields associated with that conditional layout are not initialized.
To initialize a formatted segment occurrence and change its layout in the process
  1. On the tree view, select a segment occurrence to initialize.
  2. Click Edit > IMS DB Editor > Select Layout and Initialize.
  3. Select a layout on the list; then click OK.
To initialize a formatted segment occurrence and reformat its data to use padding bytes
  1. On the tree view, select a segment occurrence to initialize.
  2. Click Edit > IMS DB Editor > Select Layout and Initialize.
  3. Select Use padding byte from the list; then click OK.
Parent topic: IMS Database Editor
Related concepts
Editing Segment Data
Initializing Segments and Fields
Related reference
IMS Database Editor window
Initialize Segment dialog box


To make a DL/I call

  1. From the tree view, select a segment type.
  2. Click the appropriate icon on the IMS Database Editor toolbar to issue the call. Roll over each icon to see its action, or see IMS Database Editor window for more information.
Parent topic: IMS Database Editor
Related concepts
Navigating an IMS Database
Retrieving Data
Related reference
IMS Database Editor window


To modify a segment occurrence

  1. If browsing the database, click End Browse end browse.
  2. Optionally, click [image] on the IMS Database Editor toolbar to move to the start of the database.
  3. On the toolbar, click [image] until you are positioned on the segment occurrence that you want to modify.
  4. Edit each field that you want to change.
  5. When you have finished making your edits, click *.
Note: If you have the Update warning option checked, click Yes to enable data updates. See To configure edit warnings for more information.
Parent topic: IMS Database Editor
Related concepts
Editing Segment Data
Related tasks
To configure edit warnings
Related reference
IMS Database Editor window


To delete a segment occurrence

  1. If browsing the database, click End Browse end browse.
  2. Optionally, click [image] on the IMS Database Editor toolbar to move to the start of the database.
  3. On the toolbar, click [image] until you are positioned on the segment occurrence that you want to delete.
  4. Click *.

    The segment occurrence is removed and your current position changes to the next segment occurrence in the database.

CAUTION:
When you delete a parent segment occurrence, you delete all child segments of that parent as well.
Note: If you have the Delete warning option checked, click Yes to enable deletion. See To configure edit warnings for more information.
Parent topic: IMS Database Editor
Related concepts
Editing Segment Data
Related tasks
To configure edit warnings
Related reference
IMS Database Editor window


To load bookmarks from a file

  1. Click File > IMS DB Editor > Load Bookmarks.
  2. Use the Open dialog box to select and open the bookmark file that contains the bookmarks you want to load.
Parent topic: IMS Database Editor
Related concepts
Bookmarking Segment Occurrences
Related reference
Add bookmark dialog box
Bookmarks dialog box


To save your bookmarks in a file

  1. Click File > IMS DB Editor > Save Bookmarks.
  2. Browse to a folder in which to save the bookmark file. We recommend that you save the file in the Enterprise Developer project folder specified as the MS Database folder in your project properties.
  3. In the File name field, type a file prefix that describes the contents.
  4. Click Save.
    Note: By default, the IMS Database Editor saves bookmark files with the file extension .bmf.
Parent topic: IMS Database Editor
Related concepts
Bookmarking Segment Occurrences
Related reference
Add bookmark dialog box
Bookmarks dialog box


To search an IMS database for a string

  1. Click Search > IMS DB Editor > Find.
  2. In the Find field, type in your search string.
  3. Optionally, do one or more of the following:
    • To specify a range for the search, select a range specification from the End drop-down list.
    • To restrict your search to the current segment type, check Only look in segment-name, where segment-name is the name of the current segment.
    • To make the search case sensitive, check Match case.
    • To indicate that the search should be restricted to certain positions within in each segment, specify the offsets in the Left and Right fields; then check Within offsets.
    • To base your search on the contents of an existing field, check Use field. This updates the search string and offset details with the relevant information for the currently selected field.
    • To change the field used when Use field is checked, select a different field; then click Refresh from field go to current segment to replace the current search criteria with information for the newly selected field.
      Note: The easiest way to search for a binary string when you have a segment layout file loaded is to use the Use field field and the Refresh from field button. If you do not have a segment layout file loaded, make sure you have checked Match case, to ensure the search is carried out as expected.
  4. When you have finished specifying the range and any restrictions, click Find to search for the next occurrence of your search string.
Note: The following rules apply:
  • You can only search forwards through the database.
  • Each time you search an IMS database, your current position changes to the last segment searched. This is true even if the search operation fails to find the string you are looking for.
Parent topic: IMS Database Editor
Related concepts
Searching for a String
Related reference
IMS Database Find dialog box


To start the IMS Database Editor

  1. In Eclipse, open an Enterprise Developer project that contains IMS database files.
  2. From the COBOL Explorer, right-click a .DBD or .PSB file; then select Open With > IMS Database Editor.
Parent topic: IMS Database Editor
Related concepts
IMS Database Editor


To undo edits

To undo a segment edit
  • Click Edit > IMS DB Editor > Undo Segment Edit.
CAUTION:
  • This action undoes all the edits you have made on the current segment occurrence in the Segment Data and Field Data areas and in the Field Layout View.
  • If you have used ISRT or REPL already, it is too late to undo segment edits.
To undo a field edit
Do either of the following:
  • While in field edit mode, press Escape.
  • While in field edit mode, right-click in the field and select Undo from the context menu.
Parent topic: IMS Database Editor
Related concepts
Creating and Editing Data
Related reference
IMS Database Editor window


To browse data in an IMS database

  1. In the IMS Database Editor, select a segment type on the Tree view; then click get first with hold to retrieve the first segment. The segment position icon go to current segment shows next to the retrieved segment.
    Note: Alternatively, issue a different DL/I call to ensure that a segment is loaded. The segment from which you start the browse must have a unique concatenated key.
  2. Optionally exclude or include segments. See To exclude or include segments in a browse session.
  3. Click Start Browse go to current segment.
  4. Do any of the following:
    • To move forward one page, click *.
    • To move back one page, click *.
    • To return to your current database position, click go to current segment.
    • To view key, data, and hex values on the Data Information bar at the bottom of the Browse window, click a listed segment occurrence.
  5. To close the browse session, do one of the following:
    • To end the browse session and maintain your current position in the database, right-click in the Browse window and select End Browse from the context menu.
    • To end the browse session and immediately edit the current segment occurrence, click Go to segment [image].
Note:
  • At any time, you may apply segment layouts. When you move from one segment to another, the segment layout view is updated to show the data for the selected segment occurrence.
  • You can change the number of segments that appear on each browser page by setting the Number of segments per browser page option.
  • The following rules apply when browsing:
    • You can only browse through the database one page at a time.
    • You cannot browse backwards through the database beyond your start position.
    • You cannot edit data during a browse session.
Parent topic: IMS Database Editor
Related concepts
Browsing Segment Occurrences
Related tasks
To exclude or include segments in a browse session


IMS Enterprise Server Configuration

  • To create an IMS-enabled enterprise server from the Enterprise Developer IDE
  • To create an MSS-enabled enterprise server for IMS applications from Enterprise Server
  • To enable MSS for an existing enterprise server
  • To enable IMS for an MSS-enabled enterprise server
  • To specify the location of generated files
  • To specify the location of application files
  • To define a message processing region
  • To enable IMS Connect
  • To define how MFS attributes are coded
  • To define the MFS null character
  • To run an IMS transaction from a 3270 session
  • To start a temporary MPR
  • To perform a cold start
  • Message Queue
  • Printers
  • Resources
  • Transactions
  • WebSphere MQ
Parent topic: How to


To create an IMS-enabled enterprise server from the Enterprise Developer IDE

  1. From the Enterprise Developer IDE, open Server Explorer.

    If it is hidden, display it by choosing Window > Show View > Server Explorer.

  2. Right-click Local [localhost:86], and click New > Enterprise Server.
  3. Typea name for your enterprise server instance into the Name field.
  4. Check either 32-bit or 64-bit.
  5. Click the browse button next to the Template field.

    This opens the location of the Enterprise Developer server templates which is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\ServerTemplates by default.

  6. Select IMSTemplate.xml, and click Open.
  7. In the Associate with projects box, check an IMS project that contains the application you want to run on the new enterprise server.
  8. Click Finish.

    The Console view displays a notification that the server has been created.

  9. Check Server Explorer to see that the new enterprise server has been added to localhost.
Parent topic: IMS Enterprise Server Configuration


To create an MSS-enabled enterprise server for IMS applications from Enterprise Server

  1. Start Enterprise Server Administration using one of the following methods:
    • From the Start menu: Click Start > All Programs > Micro Focus Enterprise Developer > Configuration > Enterprise Server Administration. This starts Enterprise Server Administration in a browser outside of the IDE.
    • From your Web browser, enter http://localhost:86 into the Address field.
  2. Click Add.
  3. In the Server Name field, type a name for the new enterprise server instance.
  4. Choose a Working mode option; then click Next.
  5. In the Server Type group, click Micro Focus Enterprise Server with Mainframe Subsystem Support; then click Next.
  6. In the Creation Options group, ensure that Set TN3270 listener is checked; then enter a port number into the Using port field. This is the port number used when you connect to the enterprise server with your TN3270 emulator.
  7. In the Description field, type a description of the new enterprise server
  8. Click Add.

    This displays the Enterprise Server Administration Home page with your new server on the list of available enterprise servers.

  9. Configure the new enterprise server instance for IMS.
Parent topic: IMS Enterprise Server Configuration
Related concepts
Create an IMS-enabled Enterprise Server
Creating and Configuring an Enterprise Server Region for IMS


To enable MSS for an existing enterprise server

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server for which you want to enable MSS.
  2. Click the MSS tab.
  3. Check Mainframe Subsystem Support enabled.

    This is the minimum you need do to enable MSS. By default the enterprise server uses the SIT DFH$IVP. The startup lists, groups and resources used by the enterprise server will, therefore, be those defined by DFH$IVP.

  4. If you want to use a SIT other than DFH$IVP, specify the name of the SIT in System Initialization Table.

    If you want to set a SIT that has a $ (dollar) character in its name you have to escape the $ character, for example MY\$SIT:

  5. If you specified a SIT other than DFH$IVP, specify CICS search paths, unless you are enabling MSS for JCL rather than CICS, in which case search paths are not required.
  6. Click Apply.
  7. Restart your server. The enterprise server will start as a MSS-enabled enterprise server, using either the default SIT, or the SIT you specified.
Note: You can disable or re-enable MSS by unchecking or checking Mainframe Subsystem Support enabled, then clicking OK and stopping and restarting the enterprise server.
  • To configure CICS search paths
Parent topic: IMS Enterprise Server Configuration
Parent topic: Control and Configuration
Parent topic: Enabling MSS for an Enterprise Server
Parent topic: Enabling JCL for an Enterprise Server


To enable IMS for an MSS-enabled enterprise server

  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server you want to enable.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and General tabs.
  3. Ensure that Mainframe Subsystem Support enabled is checked, then check IMS enabled.
  4. Click Apply.
Parent topic: IMS Enterprise Server Configuration
Related concepts
Create an IMS-enabled Enterprise Server
Creating and Configuring an Enterprise Server Region for IMS
Related information
To specify the location of generated files
To add PCT entries to a resource group
To add a message processing region to a resource group
To define a transaction manually


To specify the location of generated files

  1. From the Enterprise Server Administration Home page, in the table of servers, click Edit to the left of the row for the server you want to change.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS and General tabs.
  3. In both the GEN file directory and Configuration directory fields, specify the name of the folder that contains your generated DBD and PSB files. You can enter multiple locations, each separated by a semi-colon.
  4. Click Apply to save the change.
  5. Click the Server, Properties, MSS, IMS, TM and General tabs.
  6. In the MFS path field, specify the name of the folder that contains your generated MFS files. You can enter multiple locations, each separated by a semi-colon.
  7. Click Apply to save the changes.
  8. Click Home to return to the Home page of Enterprise Server Administration.
Parent topic: IMS Enterprise Server Configuration
Related concepts
DBD Generation
PSB Generation
MFS Generation
Related reference
mfims generation command


To specify the location of application files

  1. From the Enterprise Server Administration Home page, in the table of servers, click Edit to the left of the row for the server you want to change.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MSS, IMS, TM and General tabs.
  3. In the Application Path field, type the full path to your COBOL application files, which should be the same as the Output Path specified in your Enterprise Developer project COBOL properties.
  4. In the Transaction definition file directory field, type the full path to your transaction definition file. By default, this is dfhdrdat located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\cas (Windows) or $COBDIR/etc/cas (UNIX).
  5. Click Apply to save the changes.
  6. Click the Server, Properties, MSS, IMS, and DB tabs.
  7. In the Database path field, type the full path to your PSB and DBD database files.
  8. Click Apply to save the changes.
Parent topic: IMS Enterprise Server Configuration


To define a message processing region

  1. From the Enterprise Server Administration Home page, click Server, Properties, MSS, IMS, TM, and MPRs.
  2. Click Add.
  3. In the Name field, type a name for the MPR.
  4. In the Transaction Class field, type a three-digit number such as 001.
  5. Click Add.
  6. Click Home to return to the Home page of Enterprise Server Administration.
Note: You can specify a maximum of four classes in the Transaction Class field. You must separate each class by a comma. The classes you specify must be less than 32-bytes long. If you specify more than four classes only the first four are used. When you start the enterprise server instance you see a message (CASIP0013I) in the console.log that shows which classes have been registered for use.
Parent topic: IMS Enterprise Server Configuration


To enable IMS Connect

  1. From the Enterprise Server Administration Home page, click the Listeners tab.
  2. Click Add.
  3. Enter a unique name for the new listener.
  4. From the Endpoint Protocol drop-down list, select TCP .
  5. Enter an appropriate port for IMS Connect in the Endpoint Address text box.
  6. Select a Supported Conversation Type of Custom and enter mfcs-ims-connect in the text box.
  7. Optionally, add trace details in the Configuration Information text box, for example:
    [Trace]
trace=y
data-trace=all
allmax=255
  8. Click Add.
Parent topic: IMS Enterprise Server Configuration


To run an IMS transaction from a 3270 session

Note: See Configuring IMS-enabled Enterprise Servers for more info on how to define transactions in an enterprise server.

Before you run your IMS transaction in an enterprise server you must first run the /IMS transaction to set up the enterprise server to run in IMS mode. Once you have done this, you run an IMS transaction in the same way as you would run it on the mainframe. If you run it from a 3270 terminal or emulator, you enter transaction IDs at the terminal. Note that on a PC the keys assigned to act as the CICS keys depend on your TN3270 emulator. For example, in many cases the Escape key is used as the 3270 Clear key, and the right-hand Ctrl key is used as the 3270 Enter key.

To run an IMS transaction from a 3270 session:

  1. Enter /IMS to switch the enterprise server to IMS mode.
  2. Enter the name of your transaction. If the name of the transaction is shorter than eight characters, add a trailing space to the end of it.
Note:
  • To switch from IMS mode back to CICS mode, use the /CIC transaction.
  • The /CIC and /IMS transactions is defined in the DFHSIGN group. To add these transactions to your resource definition file you must run the caspcupg command, as described in the section Adding IMS-specific Resource Definitions in the chapter Configuring IMS-enabled Enterprise Servers for IMS in your Mainframe Subsystem Support Configuration and Administration Guide.
Parent topic: IMS Enterprise Server Configuration


To start a temporary MPR

As well as defining permanent message processing regions, you can define temporary ones that exist only until an enterprise server is stopped.

To start a temporary MPR:

  1. In the dropdown list under Resources on the ESMAC menu, select IMS.
  2. Click Control in the Resources part of the ESMAC menu.

    The IMS Control page that appears is for starting MPRs and creating an internal diagnostic view of IMS TM message queues.

  3. In MPR Classes field, type the list of message classes you want this MPR to be able to run.
  4. If you are defining an MPR for transactions that you want to debug, check Debug.
  5. Click Start.

    The MPR starts immediately and lasts until the enterprise server is stopped.

Note: You can specify a maximum of four classes in the Transaction Class field. You must separate each class by a comma. The classes you specify must be less than 32-bytes long. If you specify more than four classes only the first four are used. When you start the enterprise server instance you see a message (CASIP0013I) in the console.log that shows which classes have been registered for use.

Like all SEPs, any MPRs you define are shown, together with their statuses, on the SEPs page in ESMAC. Click SEPs near the top left of the ESMAC menu to display this. MPRs are displayed in the IMS MPR section.

Parent topic: IMS Enterprise Server Configuration
Related concepts
Defining IMS Resources


To perform a cold start

If your message processing regions for an enterprise server become unresponsive for some reason you need to perform a cold start. Performing a cold start involves deleting the IMS message queue for an enterprise server, so any outstanding messages are lost and need to be resubmitted after the cold start.

To perform a cold start you delete the file %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\ES_name\imsmesgq.dat, where ES_name is the name of the enterprise server whose message processing regions are unresponsive.

Parent topic: IMS Enterprise Server Configuration


Message Queue

  • To dynamically adjust the IMS message queue configuration
  • To enable dynamic IMS message queue performance tuning
  • To dynamically tune IMS message queue performance
Parent topic: IMS Enterprise Server Configuration


To dynamically adjust the IMS message queue configuration

  1. Start your enterprise server region.
  2. From the Enterprise Server Administration Home page, click the Details button in the Status column for your enterprise server region.
  3. Click ES Monitor & Control.
  4. On the sidebar menu under Resources, select IMS from the drop-down menu; then click the Control button below.
  5. In the TM System Overview and Control section, modify the Message Queue Max and/or Cushion fields as required. See the IMS Control topic for a description of each.
  6. When you have completed your changes, click Apply.

    Changes take effect immediately.

Parent topic: Message Queue
Related concepts
Dynamic IMS Message Queue Expansion
Dynamic IMS Message Queue Performance Tuning
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


To enable dynamic IMS message queue performance tuning

  1. If started, stop your enterprise server region .
  2. From the Home page in Enterprise Server Administration, click the Edit button that corresponds to your enterprise server region.
  3. Open the Server > Properties > General tabs.
  4. In the Configuration Information field, add an [ES-Environment] section, and set the ES_TMC_AGGREGATE environment variable. For example, to disable flush operations:
    [ES-Environment]
ES_TMC_AGGREGATE=,D
    See Dynamic IMS Message Queue Performance Tuning for detailed descriptions of each ES_TMC_AGGREGATE environment variable option.
  5. Click Apply.
Parent topic: Message Queue
Related concepts
Dynamic IMS Message Queue Performance Tuning
Related tasks
To dynamically tune IMS message queue performance
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


To dynamically tune IMS message queue performance

  1. In Enterprise Server Administration, be sure that you have set the ES_TMC_AGGREGATE environment variable. See To enable dynamic IMS message queue performance tuning for details.
  2. Start your enterprise server region.
  3. From the Enterprise Server Administration Home page, click the Details button in the Status column for your enterprise server region.
  4. Click ES Monitor & Control.
  5. On the sidebar menu under Resources, select IMS from the drop-down menu; then click the Control button below.
  6. In the TM System Overview and Control section, modify any of the following as required:
    • Transaction Threshold
    • Q Flush Aggregate, on, ms, Flush disable
    • Keypoint Freq

    See the IMS Control topic for a description of each.

  7. When you have completed your changes, click Apply.

    Changes take effect immediately.

Parent topic: Message Queue
Related concepts
Dynamic IMS Message Queue Performance Tuning
Related tasks
To enable dynamic IMS message queue performance tuning
Related reference
IMS-Specific Environment Variables
Server Instance Properties: MSS IMS TM General
IMS Control


Printers

  • To define specific printers for an IMS-enabled enterprise server
  • To enable printer security for an IMS-enabled enterprise server
  • To attach to an IMS printer
Parent topic: IMS Enterprise Server Configuration
Related concepts
Create and Configure an IMS Enterprise Server


To define specific printers for an IMS-enabled enterprise server

Note: This topic applies to Use Case 3: Define Specific Printers to Enterprise Server from the topic Configuring IMS Printers. See Configuring IMS Printers for information on LU1 and LU3 Term Model definitions.
  1. Start ES Monitor & Control for your IMS-enabled enterprise server.
  2. Edit the IMSGRP resource definition, found in the IMSSTRT startup list.
    Note: The IMSGRP resource definition is found in the IMSSIT system initialization table. If you have not specified IMSSIT for this enterprise server, create a new resource group.
  3. On the CICS GROUP page, click Term.
  4. In the Name field, type a four-character name for the new Term; generally, this is the last four characters of the Net Name, and must be unique within the Term name namespace for an enterprise server. A name conflict encountered for either specifically or dynamically defined clients can prevent definitions from installing properly at run time.
  5. Type a meaningful description into the Description field.
  6. From the Model drop-down list, select No.
  7. In the Net Name field, type a name. See Assigning Client Names for more information.
  8. In the Terminal Type field, type the terminal type that represents the printer. For example, for an LU3 printer, type LU3PRINT. LU3PRNT is a supplied T-TYPE definition in the DFHTERM definition group.
  9. Ensure that the Fixed Transaction field is set to /IMS. This specification ensures that Enterprise Server publishes this device to theEnterprise Server IMS TM.
  10. Click Add.
Parent topic: Printers
Related concepts
Create and Configure an IMS Enterprise Server


To enable printer security for an IMS-enabled enterprise server

Note: This topic applies specifically to the use of legacy SNT security for Enterprise Server. If using external security managers, the security manager that controls authentication (i.e., manages user IDs) must contain a user definition that matches the Net Name specified for the printer.
  1. Start ES Monitor & Control for your IMS-enabled enterprise server.
  2. From the list on the left side of the page, click Users.
  3. Click the Details button that corresponds to CICSUSER.
  4. Check Local ES Security Enabled.
  5. Click Apply.
  6. Add a user definition for each printer, providing a user ID for each that is the same as the printer's Net Name.
Parent topic: Printers
Related concepts
Create and Configure an IMS Enterprise Server


To attach to an IMS printer

In your TN3270 emulator, specify the client name (NETNAME), which is the IMS LTERM name under which it operates. For example, in Rumba type this name into the Device Name field on the TN3270 tab of the Connection Configuration dialog box. See Assigning Client Names for more information.

Parent topic: Printers
Related concepts
Create and Configure an IMS Enterprise Server


Resources

Note: You must perform the following tasks from the Enterprise Server Monitor and Control (ESMAC) interface.
  • To Start ESMAC for an enterprise server instance
  • To create a resource group
  • To modify a resource
  • To add a message processing region to a resource group
  • To add a resource group to a startup list
  • To add PCT entries to a resource group
  • To create an XA resource for a trigger monitor
Parent topic: IMS Enterprise Server Configuration


To Start ESMAC for an enterprise server instance

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

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

    The ESMAC screen is displayed.

Parent topic: Resources
Parent topic: Administering Enterprise Server Instances using ESMAC
Parent topic: Administer a Server Using ESMAC
Parent topic: To change the SIT associated with a server
Related tasks
To specify a CCSID table in the CICS SIT
To enable CICS Web interface support


To create a resource group

  1. Click Resources, by Group.
  2. Click Groups.
  3. Click New.
  4. Specify a name and a description for the group.
  5. Click Add.
  6. Click Group List.
  7. Add resources to the group as required: click one of the buttons at the foot of the page (FCT, TST etc), create the new table, and from the table page click Group List to return to the group list. Repeat to add more resources.
Parent topic: Resources
Parent topic: Resources


To modify a resource

  1. Click Details on any of the pages that list resources.

    The detailed information page shows various information relating to the resource you selected. The page title reflects the resource and the method you chose to view it. For example, if you choose to view resources by startup list, click FCT to display a list of FCTs, and then click Details next to an FCT listed in the table, the detailed information page for the FCT you selected is displayed. The detailed information page has the title CICS FCT - fct_name (grp), where fct_name is the name of the FCT, and grp the group to which the FCT belongs. In this case, the detailed information page displays all of the values set for the FCT.

  2. Edit the fields or change controls on the page as required.
  3. Click Apply. If your changes are successfully applied, you see the message "Update successful".
Note: If you do not have the required permissions to modify resources, the Apply button is not shown.
Parent topic: Resources
Parent topic: Resources


To add a message processing region to a resource group

  1. In the dropdown list under Resources on the ESMAC menu, select By Group.
  2. Click Groups, then click Details next to the resource group you want to update.
  3. Click JES.
  4. Specify IMS MPR in the Type field, the relevant classes in the Classes field, and an appropriate text in the Name and Description fields.
  5. Click Add.
  6. Click Group List.
Note: You can specify a maximum of four classes in the Transaction Class field. You must separate each class by a comma. The classes you specify must be less than 32-bytes long. If you specify more than four classes only the first four are used. When you start the enterprise server instance you see a message (CASIP0013I) in the console.log that shows which classes have been registered for use.
Note:

Defining a message processing reigon for an enterprise server in this way causes a message processing region to start each time the enterprise server is started. For information on creating a message processing region that only exists until an enterprise server stops, see the section Temporary MPRs in the chapter Administering IMS-enabled Enterprise Servers in your Mainframe Subsystem Support Configuration and Administration Guide.

Parent topic: Resources
Related information
To enable IMS for an MTO-enabled enterprise server
To specify the location of genned files
To add PCT entries to a resource group
To define a transaction manually


To add a resource group to a startup list

  1. In the list of buttons under Resources on the ESMAC menu, click Startup.
  2. Click Details next to the entry for the startup list to which you want to add the resource group.
  3. Specify the name of the resource group in the empty field at the bottom of the list of resource groups.
  4. Click Apply.
  5. Click Home to return to the Home page of Enterprise Server Administration.
Parent topic: Resources
Related information
To enable IMS for an MTO-enabled enterprise server
To specify the location of genned files
To add PCT entries to a resource group
To add a message processing region to a resource group
To define a transaction manually


To add PCT entries to a resource group

  1. In the drop-down list under Resources on the ESMAC menu, select By Group.
  2. Click Groups, then click Details next to the resource group you want to update.
  3. Click PCT.
  4. Specify the name of the transaction in the Name field and the name of the associated program in the Program Name field.
  5. Click Add.
  6. Click Group List.
Parent topic: Resources


To create an XA resource for a trigger monitor

Follow the steps in the topic To define an XA resource (XAR) for an enterprise server region using the following properties:

For one-phase commit transactions
ID | MQXA
Name | MQSERIES
Module | DFHEIBMQ
Open string | TPM=ESCICS,AXLIB=casaxlib,QMNAME=queue manager name
Enabled | checked

Example

TPM=CICS,AXLIB=casaxlib,QMNAME=TESTQ,CHANNEL_TESTQ,TCP,123.10.20.135(1414)
For two-phase commit transactions
ID | MQXA
Name | MQSERIES
Module | ESMQXA
Open string TPM=CICS,AXLIB=casaxlib,QMNAME=queue manager name, CHANNEL, TRPTYPE, CONNAME
TPM
The transaction manager being used. Must be set to CICS.
AXLIB
The name of the library that contains the transaction manager's ax_reg and ax_unreg functions. Must be set to casaxlib.
QMNAME
The name of the queue manager. This is a mandatory parameter.
CHANNEL
Optional - the name of an MQI channel. If this parameter is supplied, the CONNAME parameter must also be supplied.
TRPTYPE
Optional - the communications protocol for the MQI channel. The default is TCP. The following are valid values:
LU62
SNA LU 6.2
NETBIOS
NetBIOS
SPX
IPX/SPX
TCP
TCP/IP
CONNAME
The network address of the queue manager (connection name). The valid values of this parameter depend on the value of the TRPTYPE parameter. CONNAME is mandatory when multiple MQ listeners are defined to make an MQ connection from the Micro Focus Directory Server, and optional when connecting using a single MQ listener.
If TRPTYPE is set to: CONNAME must be:
LU62 A symbolic destination name, which identifies a CPI-C side information entry.

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

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

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

0a0b0c0d.804abcde23a1(5e86)

The default value is 5e86.

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

Example Open String

TPM=CICS,AXLIB=casaxlib,QMNAME=TESTQ,CHANNEL_TESTQ,TCP,123.10.20.135(1414)
Note: If you specify the CHANNEL, TRPTYPE, and CONNAME parameters, you must also set the MQSERVER environment variable, providing the same parameter values. See WebSphere MQ-Specific Environment Variables for more information.
Enabled | checked
Parent topic: Resources
Parent topic: WebSphere MQ
Parent topic: WebSphere MQ
Related tasks
To Define an XA Resource (XAR) for an Enterprise Server Region
Related reference
WebSphere MQ-Specific Environment Variables
Related information
XAR for WebSphere MQ


Transactions

  • To define a transaction manually
  • To export IMS transactions
  • To import IMS transactions
Parent topic: IMS Enterprise Server Configuration


To define a transaction manually

  1. From the ESMAC menu, in the drop-down list under Resources, select IMS.
  2. Click Transactions; then click New.
  3. On the Create, View and Edit an IMS Transaction page, specify the values you require for your new transaction.
  4. Click Add; then Apply.
Note: Add the new transaction to a resource group as a PCT entry.
Parent topic: Transactions


To export IMS transactions

Option 1: Export from a stage 1 file
The stage 1 file is read and all the transaction definitions are extracted into a transaction file.
To create a transaction file from a stage 1 file:
  1. Download your stage 1 file from the mainframe.
  2. Open an Enterprise Developer command prompta command prompt.
  3. Change to the directory that contains your downloaded stage 1 file.
  4. Enter the following:
    mfims stage1ext stage1file transactionfile
    where:
    stage1file | The stage 1 file downloaded from the mainframe.
    transactionfile | The name of the transaction file to be created.

    The transaction file is created in the current directory.

Option 2: Export from imsgen2.dat
To create a transaction file from an imsgen2.dat file:
  1. Open an Enterprise Developer command prompta command prompt.
  2. Enter the following:
    mfims tranexp [transactionfile]
    where:
    transactionfile The name of the transaction file to be created. Optional. If not specified, the name of the transaction file defaults to tranexp.txt.

    The transaction file is created in the current directory.

    Note: If the imsgen2.dat file is not in the current directory, it must be in the directory specified by the ES_IMSLIB environment variable.
Parent topic: Transactions
Related concepts
Export IMS Transactions
Related tasks
To import IMS transactions
Related reference
mfims stage1ext command
mfims tranexp command
IMS-Specific Environment Variables


To import IMS transactions

  1. Open an Enterprise Developer command prompt.
  2. Change to the directory that contains your transaction file.
    Note: If you want to import into an existing imsgen2.dat file, be sure that either the transaction file and the imsgen2.dat file are in the current directory, or that you have set the ES_IMSLIB environment variable to point to the location of the imsgen2.dat file.
  3. Enter the following:
    mfims stage1imp transactionfile [ADDREPL] [DELEXIST]

    where:

    transactionfile | The transaction file created from a stage 1 file or from Enterprise Server.
    ADDREPL | If the imsgen2.dat already exists, specifies adding new transactions and replacing existing transactions. If you do not specify ADDREPL, new transactions are added but existing transactions are left unchanged.
    DELEXIST | If the imsgen2.dat already exists, specifies that all the existing transaction definitions in the imsgen2.dat file be deleted before importing extracted transactions.
Parent topic: Transactions
Related concepts
Import the Transaction File
Related tasks
To export IMS transactions
Related reference
mfims stage1imp command
IMS-Specific Environment Variables


WebSphere MQ

  • To create an MQ listener
  • To create an XA resource for a trigger monitor
  • To delete an MQ listener
  • To delete an MQ writer
  • To edit an MQ listener
  • To enable MQ listener support
  • To generate a PSB for a Trigger Monitor
  • To start a WebSphere MQ trigger monitor
  • To stop and restart an MQ listener
  • To stop a WebSphere MQ trigger monitor
  • To view MQ listener or writer details
Parent topic: IMS Enterprise Server Configuration


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
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
Parent topic: WebSphere MQ


To delete an MQ writer

  1. Start ESMAC for the enterprise server instance that is running the writer you want to delete.
  2. On the ESMAC sidebar under Resources, select MQ from the drop-down menu.
  3. Click Writers.
  4. Click the Details button that corresponds to the writer you want to delete.
  5. Click Stop to stop the writer.

    Stopping the writer deletes it automatically.

Note: You can also delete writers using the casout command.
Parent topic: WebSphere MQ


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
Parent topic: WebSphere MQ


To enable MQ listener support

Note: Ensure that any duplicate entries for WebSphere MQ support are removed from the SIT, as this could cause connection conflicts.
  1. On the Home page of Enterprise Server Administration, click Edit next to the name of the enterprise server for which you want to enable WebSphere MQ support.
  2. The Edit page that appears contains a hierarchy of tabs. Click the Server, Properties, MQ, and General tabs.
  3. Check MQ listener support enabled; then click Apply.
Note: You can also enable MQ listener support by setting the ES_MQ_LISTENER environment variable, and by using the casout command.
Parent topic: WebSphere MQ
Parent topic: WebSphere MQ


To generate a PSB for a Trigger Monitor

  1. Copy the supplied file CSQ4TRMN.PSB to an appropriate location. This file can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src (Windows) or $COBDIR/src/enterpriseserver/ims/mq (UNIX) folder.
  2. At a command prompt enter the following command:
    mfims psbgen csq4trmn.psb nocls echo(enderr,0,55)
Parent topic: WebSphere MQ
Parent topic: WebSphere MQ


To start a WebSphere MQ trigger monitor

  1. Copy the supplied file CSQ4TRMN.JCL to an appropriate location. This file can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src (Windows) or $COBDIR/src/enterpriseserver/ims/mq (UNIX) 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
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
Parent topic: WebSphere MQ


To stop a WebSphere MQ trigger monitor

  1. Copy the supplied file CSQ4STOP.JCL to an appropriate location. This file can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src (Windows) or $COBDIR/src/enterpriseserver/ims/mq (UNIX) 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
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
Parent topic: WebSphere MQ


Reference

  • DBD, PSB, and MFS Statements
  • DBUTIL
  • EXEC DLI Statements
  • IMS DB system commands
    IMS DB system commands supported by Enterprise Server, which are a subset of all IMS DB commands.
  • IMS DB system command interfaces
    Lists the interfaces available for executing IMS DB system commands.
  • IMS Database Control (DBC) Commands
    Describes the IMS Database Control commands used with IMS database Forward and Automatic Backward Recovery.
  • MFDBUJCL Utility
    Describes the JCL required to execute IMSDBU functions using the MFDBUJCL utility program.
  • IMS Error Messages
  • IMS Tracing Flags
  • IMS-Specific Environment Variables
    Provides a summary description for each IMS-specific environment variable used by Enterprise Server.
  • mfims Command-line Utility
    Describes the purpose and application of the mfims command-line utility for IMS databases.
  • Non-discardable Messages (NDM) Interface Block
  • Standard User Exit Parameter List
  • User Interface Reference
Parent topic: IMS Support


DBD, PSB, and MFS Statements

The DBD, PSB, and MFS source statements are grouped in major categories of language control statements and definition statements. Language control statements, such as COPY, control the generation process. The definition statements define the DBD, PSB or MFS member. With each statement, the valid keywords or positional operands are listed with their possible values and a description of the support provided.

  • General Specifications
  • DBDGEN
  • PSBGEN
  • MFSGEN
Parent topic: Reference


General Specifications

The format of the statements, positional operands and keywords are the same as defined by your IBM mainframe IMS manuals. This includes continuation rules, comments and labels except as noted here.

  • Up to 39 continuation lines are supported. More than 40 lines for one statement generates a warning message and statement truncation.
  • Literal values cannot span more than two lines
  • All statements and keywords are assumed to be in upper case. Only literal values are processed correctly if lower case.
  • In general, keywords or positional operands whose values must be numeric are edited to ensure the value is numeric. If not numeric, you see a warning message and the value is assumed to be zero. This can result in a subsequent warning or severe error message depending on the keyword or positional operand. All numeric values are limited to a maximum of eight digits.
  • When the notes state the keyword and/or operand is edited, this indicates that at least some editing of the keyword, operand and/or value is performed. There is a complete list of the DBD, MFS and PSB warning and error messages in the section Error Messages in the online Reference help.
  • All keyword operands which specify the string "*NAME" are eight character names which follow the convention for valid IBM mainframe member names. These names are always assumed to be valid.
  • Except as noted, unrecognized keywords and/or values are ignored
  • Except as noted, language and macro control statements are ignored. For example, PRINT, TITLE, EJECT, .AIF, .AGO.
  • There is no edit recovery or MFS syntax error recovery. MFSGEN terminates when a severe error is encountered. MFSGEN does not try to recover from severe syntax errors.
Parent topic: DBD, PSB, and MFS Statements


DBDGEN

There are two areas, language control and statements.

  • DBDGEN Language Control - COPY
  • DBDGEN Statements
Parent topic: DBD, PSB, and MFS Statements


DBDGEN Language Control - COPY

Any number of COPY statements can be defined. Nested COPY statements are not supported by DBDGEN. COPY statements are edited. ++INCLUDE and -INC statements are supported as if the ++INCLUDE or -INC statement was a COPY statement. The extensions provided by these two library management statements are not supported.

Parent topic: DBDGEN


DBDGEN Statements

The following sections describe the DBDGEN statements:

  • AREA (DBDGEN Statements)
    The AREA statement does not affect the processing of Fast Path DEDB databases and is not edited. All segments in a DEDB reside in the same area.
  • DATASET (DBDGEN Statements)
    The DATASET statement's effect on GSAM is summarized.
  • DBD (DBDGEN Statements)
    Only one database can be defined in any one input data set.
  • DBDGEN (DBDGEN Statements)
    Supported and edited.
  • END (DBDGEN Statements)
    Supported and edited.
  • FIELD (DBDGEN Statements)
    A maximum of 1,000 FIELD statements can be listed in one DBD.
  • FINISH (DBDGEN Statements)
    Supported and edited.
  • LCHILD (DBDGEN Statements)
    The LCHILD statement is supported and edited for logical relationships and secondary indexes. The LCHILD statement for the primary index of a HIDAM database is not required and not edited.
  • SEGM (DBDGEN Statements)
    A maximum of 255 SEGM statements can be defined in one DBD.
  • XDFLD (DBDGEN Statements)
    A maximum of 32 secondary indexes can be defined in one DBD.
Parent topic: DBDGEN


AREA (DBDGEN Statements)

The AREA statement does not affect the processing of Fast Path DEDB databases and is not edited. All segments in a DEDB reside in the same area.
Parent topic: DBDGEN Statements


DATASET (DBDGEN Statements)

The DATASET statement's effect on GSAM is summarized.
Keyword | Values | Description
RECFM | F, FB, V, VB | Can be used to determine GSAM DBD's record format
 | U | GSAM undefined length records are not supported
REL | All values | Supported and edited
DD1 | *NAME | Can be used for GSAM input DD
DD2 | *NAME | Can be used for GSAM output DD
RECORD | max, min | Can be used to determine GSAM DBD's record length
SCAN | All values | Not supported but edited
FRSPC | All values | Not supported but edited
Parent topic: DBDGEN Statements


DBD (DBDGEN Statements)

Only one database can be defined in any one input data set.
Keyword | Values | Description
NAME *NAME Supported and edited

The database is known by this name and not the name of the input data set. The database data files are also known by this name.

Only the first name in a list is used. Shared secondary index databases must be defined as separate INDEX DBDs. The CONST keyword of the XDFLD statement is supported and appears in the index segment if processed as a stand-alone database.

ACCESS All types Supported. Assumed valid and is used for subsequent processing and editing.

All access types are supported. SHSAM and SHISAM databases cannot be read from a COBOL program's FD. GSAM databases can be read or written by a COBOL FD.

RMNAME | All values | Not supported but edited
PASSWD | All values | Ignored
EXIT | All values | All EXIT options are supported except LOG. A maximum of nine EXIT routines may be specified. See the chapter For the Database Administrator (DBA) for details on data capture exits.
VERSION | All values | The maximum length of the VERSION value is 128 bytes, after substitution. See the chapter For the Database Administrator (DBA) for details on data capture exits.
Others | Any keyword not listed produces a warning message
Parent topic: DBDGEN Statements


DBDGEN (DBDGEN Statements)

Supported and edited.
Parent topic: DBDGEN Statements


END (DBDGEN Statements)

Supported and edited.
Parent topic: DBDGEN Statements


FIELD (DBDGEN Statements)

A maximum of 1,000 FIELD statements can be listed in one DBD.

There is a restriction of 512 bytes on the length of the key that IMS Option uses internally to store each segment in a database. This length is calculated by summing the lengths of the longest sequence field at each level in the database and adding two bytes for each level in the database. For non-unique sequence fields (SEQ,M), add four bytes to its sequence field length for this calculation. For non-keyed segments, use four bytes as its length for this calculation. If this limitation is exceeded, you see DBDGEN error message number DBDUT0L11.

For example, a database with just three segments, a root and two children of the root. The root sequence field is 10 bytes long, the first child's sequence field is 15 bytes long and the second child's sequence field is 25 bytes long. The sum of the key lengths at each level is 10 plus 25 for a total of 35. Adding two bytes for each of the levels in the database gives an IMS Option key length of 39.

Keyword | Values | Description
NAME | *NAME | Supported and edited
 | SEQ | Supported and edited
 | U, M | Supported and edited
BYTES | All values | Supported and edited The maximum supported length of a field used in an SSA is 255 bytes. You see a warning message if this value exceeds 255.
START | All values | Supported and edited
TYPE | All values | Supported for MSDB and Field Level Sensitivity
Others |  | Any keyword not listed produces a warning message
Parent topic: DBDGEN Statements


FINISH (DBDGEN Statements)

Supported and edited.
Parent topic: DBDGEN Statements


LCHILD (DBDGEN Statements)

The LCHILD statement is supported and edited for logical relationships and secondary indexes. The LCHILD statement for the primary index of a HIDAM database is not required and not edited.

A maximum of 32 secondary indexes can be defined in one DBD.

A maximum of 32 logical children can be defined in one DBD.

Keyword | Values | Description
NAME | *NAME | Supported but not edited
PTR, POINTER | SYMB | Supported but not edited
 | All others | Ignored
PAIR | *NAME | Supported and edited
INDEX | All values | Ignored. INDEX DBDs are automatically assigned to their indexed fields
RULES | FIRST, LAST, HERE | Supported for logical parents but not edited
Parent topic: DBDGEN Statements


SEGM (DBDGEN Statements)

A maximum of 255 SEGM statements can be defined in one DBD.
Keyword | Values | SEGM Description
NAME | *NAME | Supported and edited
PARENT | 0, SEGNAME | Supported and edited
 | SNGL, DBLE | Ignored
 | logical parent | Supported and edited. The virtual/physical pointer option is ignored.
BYTES | All values | Supported and edited A maximum of 32,760 is supported. The value is not checked to see if it exceeds the device type capacity or the access method limits. A maximum of 1,792 is supported for a segment in an INDEX DBD.
TYPE | DIR, SEQ | Supported and edited
FREQ | All values | Ignored
PTR, POINTER | All values | Ignored. IMS Option uses a proprietary pointer technique. All needed pointers are automatically created.
RULES | logicals | Insert and replace rules are fully supported. Delete rules are partially supported.
 | FIRST, LAST, HERE | Non-uniquely keyed insert rules are supported and edited. Rules of HERE are changed to LAST for logical children and root segments.
SOURCE | All values | Supported and edited
COMPRTN | All values | Ignored. Compression can be enabled using the DB Catalog or System Configuration Catalog defaults.
SSPTR | All values | Not supported - causes a warning message
EXIT | All values | All EXIT options are supported except LOG. A maximum of nine EXIT routines may be specified. See the chapter For the Database Administrator (DBA) for details on data capture exits.
Others |  | Any keyword not listed produces a warning message
Parent topic: DBDGEN Statements


XDFLD (DBDGEN Statements)

A maximum of 32 secondary indexes can be defined in one DBD.
Keyword | Values | Description
NAME | *NAME | Supported and edited
SEGMENT | SEGM-name | Supported and edited
CONST | Constant | Supported and edited
SRCH | Fieldnames | Supported and edited
SUBSEQ | Fieldnames | Supported and edited
DDATA | Fieldnames | Supported and edited
NULLVAL | All values1 | Supported and edited
EXTRTN | *NAME | See the chapter For the Database Administrator (DBA) for details on sparse routines
EXTRNCBL | *NAME | This keyword can be used to indicate the name of a COBOL program for sparse indexing.
Others |  | Any keyword not listed produces a warning message
1 When set to BLANK, requires that you also set the BLANKVAL DBDGEN directive. See BLANKVAL for details.
Parent topic: DBDGEN Statements


PSBGEN

There are two areas, language control and statements.

  • PSBGEN Language Control - COPY
  • PSBGEN Statements
Parent topic: DBD, PSB, and MFS Statements


PSBGEN Language Control - COPY

Any number of COPY statements can be defined. Nested COPY statements are not supported by PSBGEN. COPY statements are edited. ++INCLUDE and -INC statements are supported as if the ++INCLUDE or -INC statement was a COPY statement. The extensions provided by these two library management statements are not supported.

Parent topic: PSBGEN


PSBGEN Statements

The following sections describe the PSBGEN statements:

  • END-- PSBGEN Statements
    This statement is ignored.
  • PCB
    A maximum of 500 PCBs can be defined in one PSB. There is no limit to the number of TP PCBs which can be defined, however, only the first 99 can be referenced by an application program.
  • PSB-- PSBGEN Statements
    Only one PSB can be defined in a single input data set.
  • SENFLD-- PSBGEN Statements
    A maximum of 10,000 SENFLD statements can be defined for one PSB. A maximum of 255 SENFLD statements can be defined for one SENSEG.
  • SENSEG (PSBGEN Statements)
    A maximum of 3,000 SENSEGs can be defined in one PSB when using the PSBGEN3 format for PSBGEN. The maximum is 1,000 SENSEGs when using PSBGEN2 format.
Parent topic: PSBGEN


END-- PSBGEN Statements

This statement is ignored.
Parent topic: PSBGEN Statements


PCB

A maximum of 500 PCBs can be defined in one PSB. There is no limit to the number of TP PCBs which can be defined, however, only the first 99 can be referenced by an application program.

PCB TYPE=TP

Keyword | Values | Description
LTERM | *NAME | Supported but not edited
NAME | *NAME | Supported but not edited
ALTRESP | YES, NO | Ignored
SAMETRM | YES, NO | Ignored
MODIFY | YES, NO | Supported but not edited
EXPRESS | YES, NO | Ignored
PCBNAME | *NAME | Supported and edited
LIST | YES, NO | Supported and edited
Others |  | Any keyword not listed produces a warning message
Keyword | Values | Description
NAME, DBDNAME | *NAME | Supported and edited
PROCOPT | G, I, R, D, A, P, L, O, E | Supported and edited. Additional editing performed during PSBGEN Verify and when DL/I calls are made.
 | GS, LS | Supported as G and L
KEYLEN | All values | Supported. Edited during PSBGEN Verify
POS | S, M | Supported and edited
PROCSEQ | *NAME | Supported. Edited during PSBGEN Verify
PCBNAME | *NAME | Supported and edited
LIST | YES, NO | Supported and edited
SB | NO, COND | Ignored
Others |  | Any keyword not listed produces a warning message.
Keyword | Values | GSAM PCB Description
NAME, DBDNAME | *NAME | Supported and edited
PROCOPT | G, L | Supported but not edited during PSBGEN. For more information about GSAM databases, see the sections GSAM Considerations in the chapter For the Database Administrator (DBA) and Unsupported DB Features in the chapter Product Summary.
 | S | Ignored
PCBNAME | *NAME | Supported and edited
LIST | YES, NO | Supported and edited
Others |  | Any keyword not listed produces a warning message.
Parent topic: PSBGEN Statements


PSB-- PSBGEN Statements

Only one PSB can be defined in a single input data set.
Keyword | Values | Description
PSBNAME | *NAME | Supported and edited
CMPAT | YES, NO | Supported but not edited
LANG | All values | Ignored
MAXQ | All values | Ignored
IOASIZE | All values | Ignored. There is no limit to the length of an I/O area in a path call.
SSASIZE | All values | Ignored. Each SSA is limited to 4,000 bytes with no cumulative limit
IOEROPN | All values | Ignored
OLIC | All values | Ignored
LOCKMAX | All values | Ignored
Others |  | Any keyword not listed produces a warning message
Parent topic: PSBGEN Statements


SENFLD-- PSBGEN Statements

A maximum of 10,000 SENFLD statements can be defined for one PSB. A maximum of 255 SENFLD statements can be defined for one SENSEG.
Keyword | Values | Description
NAME | *NAME | Supported and edited
START | All values | Supported and edited. Must not exceed 32,760
REPL, REPLACE | YES, Y, NO, N | Supported and edited
Others |  | Any keyword not listed produces a warning message
Parent topic: PSBGEN Statements


SENSEG (PSBGEN Statements)

A maximum of 3,000 SENSEGs can be defined in one PSB when using the PSBGEN3 format for PSBGEN. The maximum is 1,000 SENSEGs when using PSBGEN2 format.

A maximum of 255 SENSEGs can be defined for one PCB.

SENSEGs must be listed in the same physical sequence as they are defined in the DBD.

Keyword | Values | Description
NAME | *NAME | Supported and edited
PARENT | *NAME | Supported and edited
PROCOPT | G, I, R, D, A , K, P | Supported and edited. Most editing is performed when issuing DL/I calls.
 | E | Ignored
SSPTR | All values | Ignored. Causes a warning message
INDICES | All values | Ignored. Causes a warning message
Parent topic: PSBGEN Statements


MFSGEN

Describes MFSGEN language control, MOD and MOD statements, and device definition.

  • MFSGEN Language Control
  • MID and MOD Statements
  • Device Definition
Parent topic: DBD, PSB, and MFS Statements


MFSGEN Language Control

The following sections describe the MFSGEN language controls:

  • ALPHA
    Partially supported and edited.
  • COPY--MFSGEN Language Control
    Any number of COPY statements can be defined.
  • DO and ENDDO
    For a description of DO and ENDDO expansion, see MFLD and DFLD.
  • EQU
    The EQU statement is partially supported and edited.
  • RESCAN--MFSGEN Language Control
    The RESCAN statement is not supported.
  • STACK and UNSTACK--MFSGEN Language Control
    These statements are supported and edited. Multiple device types for the same MOD-name are processed differently than with mainframe IMS.
Parent topic: MFSGEN


ALPHA

Partially supported and edited.
Parent topic: MFSGEN Language Control


COPY--MFSGEN Language Control

Any number of COPY statements can be defined.

MFSGEN supports up to two levels of nesting for COPY statements. That is, a COPY member can contain a COPY statement whose member can also contain a COPY statement. COPY statements are edited. ++INCLUDE and -INC statements are supported as if the ++INCLUDE or -INC statement was a COPY statement. The extensions provided by these two library management statements are not supported.

Parent topic: MFSGEN Language Control


DO and ENDDO

For a description of DO and ENDDO expansion, see MFLD and DFLD.
Parent topic: MFSGEN Language Control
Related reference
MFLD
DFLD-- Device Definition


EQU

The EQU statement is partially supported and edited.
Parent topic: MFSGEN Language Control


RESCAN--MFSGEN Language Control

The RESCAN statement is not supported.
Parent topic: MFSGEN Language Control


STACK and UNSTACK--MFSGEN Language Control

These statements are supported and edited. Multiple device types for the same MOD-name are processed differently than with mainframe IMS.

For reference, any stacks are written as data sets, not stored in memory and are named by using the stack ID, if present, with a .stk extension. The default when no stack ID is present is $mfsstak.stk. A maximum of 32 unique stack IDs are supported. These files are created in the Project's Listing folder.

These files are deleted according to the UNSTACK statement. If the last UNSTACK statement keeps the stack, these files remain on disk. The use of KEEP and DELETE is fully supported.

Parent topic: MFSGEN Language Control


MID and MOD Statements

The following sections describe the MID and MOD statements for MFSGEN:

  • DO-- MID and MOD Statements
    The COUNT keyword is supported and edited; the SUF keyword is supported but not edited.
  • ENDDO-- MID and MOD Statements
    Supported and edited.
  • LPAGE-- MID and MOD Statements
    There is a limit of 16,386 LPAGE statements which can be defined in a single message.
  • MFLD
    There is a limit of 500 MFLDs which can be defined for a single input or output message. Only MFLDs which specify a DFLD-name are counted toward the limit of 500. That is, MFLD literals and MFLDs with only a LTH keyword are not counted. If the message contains LPAGE definitions, the limit is 500 MFLDs for each logical page. The limit of 500 is after any DO statement expansion.
  • MSG-- MID and MOD Statements
    There is a limit of 16,386 output messages which can be defined in a single input data set. The input message definition must be present in the same input data set as its corresponding output definition.
  • MSGEND-- MID and MOD Statements
    Supported and edited.
  • PASSWORD-- MID and MOD Statements
    The PASSWORD statement is not supported. However, any MFLDs defined after the PASSWORD and before the first SEG are logically removed from the input message. The mapping between the program and the input message is maintained.
  • SEG
    There is a limit of 100 SEG statements which can be defined in any one input or output message.
Parent topic: MFSGEN


DO-- MID and MOD Statements

The COUNT keyword is supported and edited; the SUF keyword is supported but not edited.
Keyword | Values | Description
COUNT | iterations | Supported and edited
SUF | starting suffix | Supported but not edited. No adjustment is made for COUNT and SUF combinations which exceed a two digit value of 99. The expanded MFLD statements do not appear in the MFSGEN listing file.
Parent topic: MID and MOD Statements


ENDDO-- MID and MOD Statements

Supported and edited.
Parent topic: MID and MOD Statements


LPAGE-- MID and MOD Statements

There is a limit of 16,386 LPAGE statements which can be defined in a single message.

LPAGE for MSG TYPE=INPUT

Keyword | Values | Description
SOR | DPAGE-name list | Supported and edited
NXT | MOD-name | Supported and edited

LPAGE for MSG TYPE=OUTPUT

Keyword | Values | Description
SOR | DPAGE-name | Supported and edited
NXT | MID-name | Supported and edited
COND | MFLD-name | Supported and edited
 | MFLD-name(n) | Supported and edited
 | SEG offset | Supported but not edited
 | Relational operator | Supported and edited
 | Compare value | Supported. Length is limited to 42 bytes
PROMPT | All values | Ignored
Parent topic: MID and MOD Statements


MFLD

There is a limit of 500 MFLDs which can be defined for a single input or output message. Only MFLDs which specify a DFLD-name are counted toward the limit of 500. That is, MFLD literals and MFLDs with only a LTH keyword are not counted. If the message contains LPAGE definitions, the limit is 500 MFLDs for each logical page. The limit of 500 is after any DO statement expansion.

MFLD for MSG TYPE=INPUT

Keyword | Values | MID MFLD Description
1st operand | DFLD-name | Supported and edited
literal value | Supported and edited. A maximum of 4,000 bytes of literal data is allowed for each input message. If the input message contains logical pages, the limit applies to each logical page.
(DFLD-name, literal) Supported and edited. A maximum of 6,000 bytes of default MID literal data is allowed for each input message. If the input message contains logical pages, the limit applies to each logical page.

If two MFLDs name the same DFLD and one MFLD specifies a default literal but the other does not, the default literal is returned to both MFLDs when no input data is received for the field.

Literals and default literals cannot exceed 92 bytes in length. All literals are truncated to the LTH value or are padded to the LTH value with the FILL character.

PF key field | Supported but not edited. The maximum length of a PF key MFLD is 50 bytes. Cannot appear more than twice in the same input message.
Cursor field | Supported but not edited. Can only appear once in the same input message.
LTH | value | Supported and edited
(pp, nn) | Partially supported and edited. A pp value other than one produces a warning message and one is assumed.
JUST | L | Supported and edited
R | Supported and edited if the length of the MFLD not including attribute bytes is equal to or less than the DFLD length. If the MFLD length is greater than the DFLD length, justification occurs but a FILL character of zero is assumed.
ATTR | YES, NO | Supported and edited
number of extended attribute bytes | Supported and edited. A maximum value of five is supported.
FILL | NULL | Supported and edited with restrictions.
All other values | Supported and edited. The FILL value for an MFLD which names a DFLD not present in the DPAGE is assumed to be spaces.
EXIT | number, vector | Supported and edited. Ignored if specified for an MFLD which names a DFLD not defined in the DPAGE.

MFLD for MSG TYPE=OUTPUT

Keyword | Values | Description
1st operand | DFLD-name | Supported but not edited
 | (DFLD-name, literal) | Supported but not edited. Literal values are truncated if longer than the LTH and padded if shorter than LTH. The FILL character is used to pad short literals. A maximum of 7,000 bytes of MOD literal data is allowed in one output message. If the message contains logical pages, the limit applies to each logical page.
 | (DFLD-name, SYS-LIT) | Supported and edited. All system literals are supported. LTSEQ and LPAGENO always contain a value of one. LTMSG is always spaces.
 | (, SCA) | Supported but not edited. Only the bit settings for 3270 Force Format Write and Erase Unprotected Fields are supported. If neither is set, nothing is erased. Other bit settings are ignored.
LTH | value | Supported and edited. A maximum length of 4095 is supported. The length is not checked to see if it exceeds the device capacity.
JUST | L | Supported and edited
 | R | Output MFLDs longer than the DFLD length have the right-most bytes of the MFLD displayed in the DFLD
ATTR | YES, NO | Supported and edited
 | number of extended attribute bytes | Supported and edited. A maximum value of five is allowed but only color and highlighting can be changed dynamically.
Parent topic: MID and MOD Statements


MSG-- MID and MOD Statements

There is a limit of 16,386 output messages which can be defined in a single input data set. The input message definition must be present in the same input data set as its corresponding output definition.

MSG TYPE=INPUT

Keyword | Values | Description
SOR | FMT-name | Supported and edited
 | IGNORE | Ignored
OPT | 1 | Supported
 | 2 | Supported as option 1
 | 3 | Not supported
NXT | MOD-name | Supported and edited

MSG TYPE=OUTPUT

Keyword | Values | Description
SOR | FMT-name | Supported and edited
 | IGNORE | Ignored
OPT | 1 | Supported
 | 2 | Supported as option 1
 | 3 | Not supported
NXT | MID-name | Supported and edited
PAGE | YES, NO | Not supported but edited. Always processed as YES.
FILL | All values | The FILL value is processed for /FOR commands and to fill short fields on an output message. Fields not provided in an output message are always filled with X'3F'. Value takes affect only if DPAGE specifies FILL=NONE.
Parent topic: MID and MOD Statements


MSGEND-- MID and MOD Statements

Supported and edited.
Parent topic: MID and MOD Statements


PASSWORD-- MID and MOD Statements

The PASSWORD statement is not supported. However, any MFLDs defined after the PASSWORD and before the first SEG are logically removed from the input message. The mapping between the program and the input message is maintained.
Parent topic: MID and MOD Statements


SEG

There is a limit of 100 SEG statements which can be defined in any one input or output message.

For MSG TYPE=INPUT

Keyword | Values | Description
EXIT | All values | Supported and edited.
GRAPHIC | YES, NO | Supported differently than mainframe IMS.

For MSG TYPE=OUTPUT

Keyword | Values | Description
GRAPHIC | YES, NO | Ignored
Parent topic: MID and MOD Statements


Device Definition

The following sections describe the statements for controlling MFSGEN device definition:

  • DEV-- Device Definition
    Only 3270 display, 3270 printers and SCS1 printer devices are supported.
  • DFLD-- Device Definition
    There is a limit of 500 labelled DFLDs that can be defined for a single device page (DPAGE).
  • DIV-- Device Definition
    The TYPE keyword for INOUT and OUTPUT are supported but not edited.
  • DO-- Device Definition
    Supports and edits most keywords as specified below.
  • DPAGE-- Device Definition
    There is a limit of 16,386 DPAGE statements which can be defined for any one FMT definition.
  • ENDDO-- Device Definition
    Supported and edited.
  • FMT-- Device Definition
    There is no limit to the number of formats which can be defined in any one input data set. However, only those formats which are referenced by a MOD are processed.
  • FMTEND-- Device Definition
    Supported and edited.
  • TABLE and IF-- Device Definition
    Only one TABLE can be defined in a single input data set.
Parent topic: MFSGEN


DEV-- Device Definition

Only 3270 display, 3270 printers and SCS1 printer devices are supported.
Keyword | Values | Description
TYPE | 3270P | A 3270 printer
 | SCS1 | An SCS1 printer. SCS1 printers are processed the same as 3270 printers.
 | 3270,1 3270-A5 | A 3270 model 1. This is processed the same as a model 2
 | 3270,2 3270-A2 | A 3270 model 2 24x80 screen
 | 3270-A3 | A 3270 model 3 32x80 screen
 | 3270-A4 | A 3270 model 4 43x80 screen
 | 3270-A7 | A 3270 model 5 27x132 screen
 | Other values | processed as a 3270 model 2

DEV for 3270 Display

Keyword | Values | Description
FEAT | All values | Ignored
PEN | All values | Ignored
CARD | All values | Ignored
SYSMSG | All values | Ignored
DSCA | x'00' and x'80' through x'F0' | Supported but not edited. Only the bit settings for 3270 Force Format Write and Erase Unprotected Fields are supported. If neither is set, nothing is erased. Bit settings for other hardware control, such as Sound Beep, are ignored.
SUB | All values | Ignored
PFK | *NAME | Supported and edited
 | integer= or positional literal | Both the positional and keyword syntax is supported for PF key value assignment
 | NEXTPP, NEXTMSG, NEXTMSGP, NEXTLP | Ignored. These values are processed as Enter which is equivalent to NEXTPP in IMS Option.
 | ENDMPPI | Supported for physical paging
PDB | All values | Ignored

DEV for 3270 Printer

Keyword | Values | Description
FEAT | 120, 126, 132 | Sets the page width if WIDTH is not specified
 | All others | Ignored
WIDTH | All values | Supported and edited. Width is limited to 133.
PAGE | line count | Supported but not edited
 | DEFN SPACE FLOAT | Page length control always processed as DEFN
DSCA | All values | Ignored
Parent topic: Device Definition


DFLD-- Device Definition

There is a limit of 500 labelled DFLDs that can be defined for a single device page (DPAGE).

If physical paging is used, the limit of 500 applies to each physical page. A labelled DFLD which is not referenced by an MFLD in the MID or MOD does not count toward this limit. The DFLD limit is after any DO statement iterations.

There is a cumulative limit of 19,996 bytes for a pool area to store MID literals, MID default literals, MOD literals, DFLD literals and PF key data. If this limit is exceeded, MFSGEN error message MFSUT0L17 is issued. The lengths are cumulative and are the lengths of the literals plus six bytes of overhead for each literal. Some of the 19,996 bytes is used for labelled DFLD data so the actual maximum size is somewhat less.

DFLD for 3270 Display

Keyword | Values | 3270 Display DFLD Description
1st operand | PASSWORD | DFLD containing PASSWORD is ignored
 | literal | Supported and edited. Length cannot exceed 133 bytes. The limit of EGCS DFLD literals (DBCS "G" literals) is 80 bytes.
POS | row, column, ppage | Supported and edited. A maximum of 12 physical pages can be defined.
LTH | value | Supported and edited. Cannot exceed 4094 bytes. The length is not checked to see if it exceeds the device capacity
PEN | All values | Ignored
ATTR | ALPHA NOPROT PROT NORM NODISP HI NOMOD MOD | Supported and edited
 | NUM | Not supported. Processed as ALPHA
 | DET IDET NODET STRIP NOSTRIP | Ignored
OPCTL | Table-name | Partially supported. See the IF and TABLE statements in this section.
EATTR | Highlight |
 | Color | Supported and edited
 | Input validation | Ignored
 | Programmed symbol sets | Ignored
 | Outlining | Keisen outlining supported with Japanese version of IMS Option only
 | EGCS | Supported with Japanese version of IMS Option only.
 | MIX, MIXD | Ignored. Mixed EGCS entry is always enabled with Japanese version of IMS Option unless EGCS is specified.

DFLD for 3270 Printer

Keyword | Values | Description
1st operand | literal | Supported and edited. Must not exceed 96 bytes if the LTH keyword is omitted. If LTH is specified, the limit is 87 bytes.
POS | Row, column | Supported and edited
 | ppage | Not supported for printers
LTH | value | Supported and edited. The combination of row, column and length cannot cause a field to exceed the page width
ATTR | YES, NO | Ignored
EATTR | All values | Ignored
Parent topic: Device Definition


DIV-- Device Definition

The TYPE keyword for INOUT and OUTPUT are supported but not edited.
Keyword | Values | Description
TYPE | INOUT, OUTPUT | Supported but not edited
Parent topic: Device Definition


DO-- Device Definition

Supports and edits most keywords as specified below.
Keyword | Values | Description
1st operand | Count | Supported and edited
2nd operand | Line increment | Supported and edited
3rd operand | MAX or column increment | Supported and edited
SUF | All values | Supported but not edited. No adjustment is made for Count and Suffix combinations which exceed a two digit value of 99. Expanded DFLD statements are not included in the MFSGEN listing file.
BOUND | FIELD | Supported but not edited
 | LINE | LINE is always processed as FIELD. This generally provides proper expansion as the first DFLD in a line is often the one which exceeds the column limit causing the entire line to be put on the next line as with FIELD.
Parent topic: Device Definition


DPAGE-- Device Definition

There is a limit of 16,386 DPAGE statements which can be defined for any one FMT definition.

For 3270 Display

Keyword | Values | Description
CURSOR | Row, Column, Fieldname | Supported but not edited. The cursor fieldname is optional but can be referenced in the MID or MOD. With physical paging, only the first 10 physical pages adhere to this default cursor position
FILL | All values | The FILL value is processed for /FOR command and is used to fill short fields for an inserted message. Fields not provided on insert are always filled with x'3F'.
MULT | YES | Ignored. All physical pages must be displayed before MID formatting.
PD | All values | Ignored
ACTVPID | All values | Ignored

For 3270 Printer

Keyword | Values | Description
FILL | All values | Ignored. Always filled with spaces
Parent topic: Device Definition


ENDDO-- Device Definition

Supported and edited.
Parent topic: Device Definition


FMT-- Device Definition

There is no limit to the number of formats which can be defined in any one input data set. However, only those formats which are referenced by a MOD are processed.
Parent topic: Device Definition


FMTEND-- Device Definition

Supported and edited.
Parent topic: Device Definition


TABLE and IF-- Device Definition

Only one TABLE can be defined in a single input data set.

Table processing is disabled if more than one TABLE is present. Only one IF statement is allowed within a TABLE. If more than one IF is present for a TABLE, the table is ignored. The only format allowed for the IF statement is:

IF DATA,^,' ',ENDMPPI

This statement generates an ENDMPPI command when the associated DFLD contains a non-blank value.

Parent topic: Device Definition


DBUTIL

Describes the JCL used to execute DBUTIL, and DBUTIL special functions.

  • DBUTIL command in JCL
    The DBUTIL command is executed from JCL and runs as a BMP type program in IMS.
  • DBUTIL special functions
    Lists the DBUTIL special functions and provides a description of each.
Parent topic: Reference
Related concepts
DBUTIL Utility


DBUTIL command in JCL

The DBUTIL command is executed from JCL and runs as a BMP type program in IMS.

Syntax:

//stepname PGM=pgmname,PARM=(BMP,DBUTIL,psbname)
//SYSIN      DD *
jobcardstatements

Parameters:

psbname
The PSB name for the IMS database. Because DBUTIL issues DL/I calls like any other application, the PCB must specify appropriate processing options for the calls applied via the control statement file.
DLIcall
A DL/I call to apply to the IMS database specified by psbname.
DBUTILspecialfunction
A DBUTIL special function to apply to the IMS database specified by psbname.
jobcardstatements
These statements include DL/I database calls and/or DBUTIL special functions. Each statement must be formatted as follows:
Columns 1 - 4
Positions one through four contain the DL/I call function or DBUTIL special function. You can specify any supported DL/I database call, such as GHU, REPL, DLET, or ISRT, or you can specify a DBUTIL special function. See DBUTIL special functions for a list of special functions and a description of each.
Column 5
A non-blank character in column 5 indicates the next line is a continuation of this line. This line becomes one of a set of records that is grouped to form one DL/I call. You cannot use this continuation to continue an IO function record.
Columns 6 - 32768
The data associated with the function:
  • For DL/I call functions and their continuation records, this is an SSA
  • For the IO function, this is the I/O area for ISRT, REPL and DLET calls. Variable length segments must contain the length code as the first two bytes of the data segment.
  • For the DBUTIL special functions, this is any data required by the function.
Example Job Card Statements
*Record Columns
*---+----10---+----20---+----30---+----40
*Set the PCB number
PCB= 03
*
*Issue get unique call with one SSA
GU   TESTSEG1
*
*Issue get unique call with three SSAs.
*(Note the continuation)
GU  XTESTSEG1*-(SEGKEY01 =10)
    XTESTSEG2*-(SEGKEY02 =20)
     TESTSEG3*-(SEGKEY03 =2000)
*
*Issue insert call with SSAs
ISRTXTESTSEG1*--(SEQFIELD =AA)
    XTESTSEG2*--(SEQFIELD =BBBB)
    XTESTSEG3
IO   NEWSEGMENTDATA

Example JCL for DBUTIL

//DBUTILTEST  EXEC PGM=DFSRRC00,PARM=(BMP,DBUTIL,SASTEST)
//SYSOUT     DD SYSOUT=*
//IMSTRACE   DD SYSOUT=*
//SYSIN      DD *
PCB= 02
ISRTXPOF0ROOT
IO   000000000000000000000000100 POF0ROOT 100
ISRTXPOF0LEG
IO   0100 POF0LEG 0100
ISRTXPOF0ALOD
IO   000000000000000000000000001 POF0ALOD 1
ISRTXPOF0ALOD
IO   000000000000000000000000002 POF0ALOD 2
ISRTXPOF0ALOD
IO   000000000000000000000000003 POF0ALOD 3
ISRTXPOF0COMP
IO   00000 POF0COMP 0 CORRECT
ISRTXPOF0COMP
IO   00001 POF0COMP 1 WRONG
ISRTXPOF0COMP
IO   00002 POF0COMP 2
ISRTXPOF0COMP
IO   00003 POF0COMP 3
ISRTXPOF0LEG
IO   0200 POF0LEG 0200
ISRTXPOF0ROOT
IO   000000000000000000000000200 POF0ROOT 200
PCB= 02
FREE
GU   XPOF0ROOT*D--(POFKEY   =000000000000000000000000100)
        XPOF0LEG *PD-(LEGNO    =0100)
          POF0ALOD*---
GNP  POF0ALOD*---
GNP  POF0ALOD*---
GNP  POF0ALOD*---
GNP  POF0COMP*F--(COMPKEY  >     )
/*
//*
Parent topic: DBUTIL
Related concepts
DBUTIL Utility


DBUTIL special functions

Function | Description
* | An asterisk (*) in column 1 indicates a comment line.
PCB= | Specifies the PCB against which subsequent DL/I calls and DBUTIL special functions are executed. Specify the relative PCB number (one to three digits) or DBD name.
IO | DL/I call, I/O area for ISRT, REPL, and DLET calls.
MSGS | Enable message tracing.
ABND |
DUMP |
PRNT | Print the contents of the database.
FREE |
SLEE | Issue a sleep command for n number of milliseconds.
SETA | Set character set to ASCII.
SETE | Set character set to EBCDIC.
BIN | Data is binary.
TEXT | Disable binary data.
STOP | Issue a STOP RUN.
STOF |
RETC | Set the return code.
Parent topic: DBUTIL
Related concepts
DBUTIL Utility


EXEC DLI Statements

These EXEC DLI statements and options are supported by the EXEC DLI preprocessor, which translates them into CBLTDLI calls. Not all EXEC DLI statements are supported; however, the EXEC DLI preprocessor does check for valid syntax. Unsupported EXEC DLI statements are not executed during debug or at runtime. Enterprise Developer supports both the OSVS and VS COBOL II dialects.

Note: You can specify a maximum of 400 input lines for one EXEC DLI/END-EXEC statement, not including comments or blank lines embedded within an EXEC DLI/END-EXEC statement.
ACCEPT
            STATUSGROUP(A)

CHECKPOINT | CHKP
            ID(area)  |  ID("literal")

DELETE | DLET
          [ USING  PCB(expression) ]
          [ VARIABLE ]
            SEGMENT(name)  |  SEGMENT((area))
          [ SEGLENGTH(expression) ]
            FROM(area)

DEQ
            LOCKCLASS(data_value)

GET UNIQUE  |  GUGET NEXT  |  GNGET NEXT IN PARENT  |  GNP
           [ USING  PCB(expression) ]
          [ KEYFEEDBACK(area) [ FEEDBACKLEN(expression) ] ]
            INTO(reference)

For each parent segment (optional)

               [ VARIABLE ]
               [ FIRST  |  LAST  |  CURRENT ]
                 SEGMENT(name)  |  SEGMENT((area))
               [ SEGLENGTH(expression) ]
               [ OFFSET(expression) ]
               [ INTO(area) ]
               [ LOCKED ]
               [ SETPARENT ]
               [ WHERE(qualification statement)
               [ FIELDLENGTH(expression) ] ]
               [ KEYS(area) [ KEYLENGTH(expression) ] ]

For the object segment ( optional for GN and GNP )

               [ VARIABLE ]
               [ FIRST  |  LAST ]
                 SEGMENT(name)  |  SEGMENT((area))
               [ SEGLENGTH(expression) ]
               [ OFFSET(expression) ]
               [ INTO(area) ]
               [ LOCKED ]
               [ SETPARENT ]
               [ WHERE(qualification statement)
               [ FIELDLENGTH(expression) ] ]
               [ KEYS(area) [ KEYLENGTH(expression) ] ]

INSERT  |  ISRT
          [ USING  PCB(expression) ]

For each parent segment (optional)

               [ VARIABLE ]
               [ FIRST  |  LAST  |  CURRENT ]
                 SEGMENT(name)  |  SEGMENT((area))
               [ SEGLENGTH(expression) ]
               [ OFFSET(expression) ]
               [ FROM(area) ]
               [ WHERE(qualification statement)
               [ FIELDLENGTH(expression) ] ]
               [ KEYS(area) [ KEYLENGTH(expression) ] ]

For the object segment (required)

               [ VARIABLE ]
               [ FIRST  |  LAST ]
                 SEGMENT(name)  |  SEGMENT((area))
               [ SEGLENGTH(expression) ]
               [ OFFSET(expression) ]
               [ FROM(area) ]

LOAD
          [ USING  PCB(expression) ]
               [ VARIABLE ]
                 SEGMENT(name)  |  SEGMENT((area))
               [ SEGLENGTH(expression) ]
               [ OFFSET(expression) ]
               [ FROM(area) ]

LOG
            FROM(area)
                 LENGTH(expression)

QUERY
            PCB(expression)

REFRESH
            DBQUERY

REPLACE | REPL
          [ USING  PCB(expression) ]

For each parent segment (optional)

               [ VARIABLE ]
                 SEGMENT(name)  |  SEGMENT((area))
               [ SEGLENGTH(expression) ]
               [ FROM(area) ]

For each object segment (required)

               [ VARIABLE ]
                 SEGMENT(name)  |  SEGMENT((area))
               [ SEGLENGTH(expression) ]
               [ FROM(area) ]

RETRIEVE
            USING  PCB(expression)
                 KEYFEEDBACK(area)
                 FEEDBACKLEN(expression)

ROLB

ROLL

ROLS
            TOKEN(token)
            AREA(data_area)

SCHEDULE | SCHD
            PSB(name)  |  PSB((area))

SETS
            TOKEN(token)
            AREA(data_area)

SETU
            TOKEN(token)
            AREA(data_area)

STATISTICS | STAT
          [ USING PCB(expression) ]
                 INTO(area)
               [ LENGTH(expression) ]
               [ VSAM | NOVSAM ]
               [ FORMATTED | UNFORMATTED | SUMMARY ]

SYMBOLIC CHECKPOINT | SYMCHKP
            ID(chkptid)  |  ID("literal")
               [ AREA1(area1)  LENGTH1(expression1) ]
               [ AREA2(area2)  LENGTH2(expression2) ]
               [ AREA3(area3)  LENGTH3(expression3) ]
               [ AREA4(area4)  LENGTH4(expression4) ]
               [ AREA5(area5)  LENGTH5(expression5) ]
               [ AREA6(area6)  LENGTH6(expression6) ]
               [ AREA7(area7)  LENGTH7(expression7) ]

TERMINATE | TERM

XRST
          [ ID(chkpid)  |  ID("literal") ]
               [ MAXLENGTH(expression) ]
               [ AREA1(area1)  LENGTH1(expression1) ]
               [ AREA2(area2)  LENGTH2(expression2) ]
               [ AREA3(area3)  LENGTH3(expression3) ]
               [ AREA4(area4)  LENGTH4(expression4) ]
               [ AREA5(area5)  LENGTH5(expression5) ]
               [ AREA6(area6)  LENGTH6(expression6) ]
               [ AREA7(area7)  LENGTH7(expression7) ]
Parent topic: Reference


IMS DB system commands

IMS DB system commands supported by Enterprise Server, which are a subset of all IMS DB commands.
/DIS
Displays the current status of specified databases.
Syntax:
/DIS[PLAY] DB {ALL | database1 [database2 [... database16]]}
Parameters:
ALL
Returns a status for all databases known to the enterprise server region, meaning databases that have been started or opened during the current enterprise server region session, and therefore does not necessarily include all databases defined in the enterprise server region.
Note: The list of known databases grows dynamically as they are accessed by system commands and applications running on the enterprise server region.
database1 [database2 [... database16]]
One or more database names separated by a space. Returns the status of each specified database, up to sixteen total databases.
Database statuses:
UNKNOWN
The database name is not valid. There is no ACB defined for this DB.
NOTOPEN
The database is defined but has not been accessed.
OPEN
The database is currently being accessed by an application program.
CLOSED
The database has been opened but is not currently open.
STOPPED
The database is stopped and not available to MPP, BMP or CICS-DLI programs.
/STO
Stops all specified databases. When stopped, a database cannot be accessed from MPP, BMP, or CICS-DLI programs; however, the database is still accessible from IMSDBU or batch DLI programs.
Note: This command is run synchronously. It suspends until the database is closed and stopped.
Syntax:
/STO[P] DB database1  [database2 [... ]]
Parameters:
database1 [database2 [...]]
One or more database names separated by a space. Stops each specified database.
/STA
Syntax:
Starts one or more specified databases, making them available to online, BMP, and CICS-DLI programs.
/STA[RT] DB database1  [database2 [... ]]
Parameters:
database1 [database2 [... ]]
One or more database names separated by a space. Starts each specified database.
Parent topic: Reference
Parent topic: IMS Support in Enterprise Server
Related reference
IMS DB system command interfaces


IMS DB system command interfaces

You can execute IMS DB system commands using any of the following interfaces:

TN3270
  • Database commands can be entered via a TN3270 session connected to /IMS.
  • The response output from the command will be sent back to the terminal session.
ESMAC
  • DB commands can be entered via the ESMAC IMS Control panel.
  • The response output is sent back to the ESMAC panel.
JCL
  • DB commands can be entered via the IMSDBU JCL interface using the PARM parameter
  • The response output is sent back to the job in the SYSOUT DD for the job step.
  • Step condition code is set if command fails.
  • Sample JCL step
    //STEP01  EXEC PGM=MFDBUJCL,PARM='/DIS DB DEMO03DD'
//SYSOUT  DD SYSOUT=*
  • Only one command can be entered per JOB step.
Parent topic: Reference
Parent topic: IMS Support in Enterprise Server
Related reference
IMS DB system commands


IMS Database Control (DBC) Commands

Describes the IMS Database Control commands used with IMS database Forward and Automatic Backward Recovery.
/DBC RESUME
Restores a database to full IMS function, and starts it in "suspend" mode.

When DBC starts an IMS database in "suspend" mode, normal transactional processing is prohibited. DBC accepts only commands to recover, START, and STOP databases.

DBC starts an IMS database in "suspend" mode when, on startup, it finds one or more corrupt databases. This can happen when Automatic Backward Recovery was previously disabled.

Use /DBC RESUME after all affected IMS databases have been recovered.

/DBC RESUME FORCE
Restores a database to full IMS function even when the database has not been recovered.
CAUTION:
Transactions run as normal and could access both corrupt and intact databases.
/DBC STATUS
Displays the current status of IMS Database Control.
/DBC SUSPEND
Puts IMS DBC into "suspend" mode.
Parent topic: Reference
Parent topic: IMS Support in Enterprise Server


MFDBUJCL Utility

The MFDBUJCL utility program enables you to execute the following IMSDBU functions from JCL:
  • Load
  • Unload
  • Zeroload
  • Add
  • PtrUpdate

In addition, you can use MFDBUJCL to execute the Rebuild utility.

Syntax

Format 1
//step EXEC PGM=MFDBUJCL,PARM='{LOAD | UNLOAD | ADD},database,dataset'
//SYSOUT DD SYSOUT=*
Format 2
//step EXEC PGM=MFDBUJCL,PARM='{LOAD | ADD},database'
//SYSOUT DD SYSOUT=*
//INPUT DD DSN={dataset | catalog},DISP=SHR
Format 3
//step EXEC PGM=MFDBUJCL,PARM='UNLOAD,database'
//SYSOUT DD SYSOUT=*
//OUTPUT DD DSN={dataset | catalog},DISP=SHR
Format 4
//step EXEC PGM=MFDBUJCL,PARM='{ZEROLOAD | PTRUPDATE},database'
//SYSOUT DD SYSOUT=*
Format 5
//step EXEC PGM=MFDBUJCL,PARM='REBUILD'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
[OUT-PATH=dbrebuildpath]
databasename1
[databasenameN
...]
/*

Parameters

step
Job step.
database
The name of your IMS database.
dataset
The name of the dataset that contains the data.
catalog
The name of the JCL catalog that contains the dataset.
OUT-PATH
Specifies a directory to contain rebuilt databases. If not specified, MFDBUJCL rebuilds databases in the current directory. Optional.
dbrebuildpath
The full path to a directory to contain rebuilt databases.
databasename1
The name of a database to rebuild.
databasenameN
The name of an additional database to rebuild. Specify each additional database name on its own line.

Comments

If your dataset is not contained in a JCL catalog, use Format 1 for LOAD, UNLOAD, and ADD functions.

If your dataset is contained in a JCL catalog, you can optionally use Format 2 for LOAD and ADD functions, and Format 3 for the UNLOAD function.

Examples

Format 1
//LOAD EXEC PGM=MFDBUJCL,PARM='LOAD,DEMO03DD,LOAD.DBU'
//SYSOUT DD  SYSOUT=*

//UNLOAD EXEC PGM=MFDBUJCL,PARM='UNLOAD,DEMO03DD,LOAD.DBU'
//SYSOUT DD SYSOUT=*

//ADD EXEC PGM=MFDBUJCL,PARM='ADD,DEMO03DD,LOAD.DAT'
//SYSOUT DD SYSOUT=*
Format 2
//LOAD EXEC PGM=MFDBUJCL,PARM='LOAD,DEMO03DD'
//SYSOUT DD  SYSOUT=*
//INPUT DD  DSN=HLQ.PRJ01.LOAD. DEMO03DD,DISP=SHR

//ADD EXEC PGM=MFDBUJCL,PARM='ADD,DEMO03DD’
//SYSOUT DD SYSOUT=*
//INPUT DD  DSN=HLQ.PRJ01.ADD. DEMO03DD,DISP=SHR
Format 3
//UNLOAD EXEC PGM=MFDBUJCL,PARM='UNLOAD,DEMO03DD'
//SYSOUT DD SYSOUT=*
//OUTPUT DD DSN=HLQ.PRJ01.UNLOAD. DEMO03DD,DISP=SHR
Format 4
//PTRUPDT EXEC PGM=MFDBUJCL,PARM='PTRUPDATE,DEMO03DD’
//SYSOUT DD SYSOUT=*

//PTRUPDT EXEC PGM=MFDBUJCL,PARM='PTRUPDATE,DEMO03DD’
//SYSOUT DD SYSOUT=*
Format 5
//STEP01  EXEC PGM=MFDBUJCL,PARM='REBUILD'
//SYSOUT  DD SYSOUT=*
//SYSIN   DD *
OUT-PATH=C:\IMS\REBUILT\DATABASES
BNKCUST
BNKACC
BNKATYPE
/*
//
Parent topic: Reference
Related concepts
Accessing IMSDBU
Related reference
Add function
Load function
Unload function
Zeroload function
PtrUpdate function
mfims imsdbu functions


IMS Error Messages

  • DBD Error Messages
  • DBUTIL Error Messages
  • IMS Database Editor Error Messages
  • IMS Run-time System Error Messages
  • MFS Error Messages
  • PSB Error Messages
  • SECRMT MSG ID: RMTSEC REMOTE IMS REQUESTER
  • IMS Stage 1 Import/Export Error Messages
Parent topic: Reference
Related information
Enterprise


DBD Error Messages

  • Messages DBDUT0401 to DBDUT0417
  • Messages DBDUT04A1 to DBDUT04A7
  • Messages DBDUT04E1 to DBDUT04E2
  • Messages DBDUT0801 to DBDUT0882
  • Messages DBDUT08A1 to DBDUT08A3
  • Messages DBDUT08P1 to DBDUT08P2
  • Messages DBDUT0L02 to DBDUT0L99
  • Messages DBDUT0LA1 to DBDUT0LA2
  • Messages DBDUT0LP1 to DBDUT0LP3
  • Messages DBDUT0U01 to DBDUT0U35
  • Messages DBDUT0W01 to DBDUT0W36
  • Messages DBDUT0WA1 to DBDUT0WA9
  • Messages DBDUT0WE1 to DBDUT0WE2
  • Messages DBDUT0WF1 to DBDUT0WF2
  • DBDUT0WP2W MFIMS supports a maximum of %2% data capture exit routines per segment, first %2% routines accepted
Parent topic: IMS Error Messages


Messages DBDUT0401 to DBDUT0417

  • DBDUT0401W More than one DBD macro present, all but the first ignored
  • DBDUT0402W DBD RMNAME operand invalid with ACCESS accesstype, RMNAME ignored
  • DBDUT0403W More than one DBDGEN statement present, all but the first ignored
  • DBDUT0404W Unknown keyword, keyword for macro, ignored
  • DBDUT0405W DBDGEN statement appeared before xxxxxxxx macro
  • DBDUT0406W Field TYPE=H (Halfword), assumed to be two bytes long
  • DBDUT0407W Field TYPE=F (Fullword), assumed to be four bytes long
  • DBDUT0408W DATASET SCAN operand is invalid for ACCESS accesstype, SCAN ignored
  • DBDUT0409W DATASET FRSPC operand is invalid for ACCESS accesstype, FRSPC ignored
  • DBDUT0410W Exceeded maximum of 10 DATASET macros with operands
  • DBDUT0411W Label labelname, only the first DATASET with a common label can contain operands
  • DBDUT0412W DATASET contains no operands but label labelname not previously defined
  • DBDUT0413W Duplicate DATASET DDNAME ddname in DD1, DD2, or OVFLW
  • DBDUT0414W Label labelname, DD1 ddname, previous DATASET group contains no segments
  • DBDUT0415W SEGM macro not preceded by DATASET macro. DATASET is required for access type: accesstype
  • DBDUT0416W Incorrect RULES specified for sequential dependent segment segname, FIRST rules assumed
  • DBDUT0417W Missing required DBDGEN macro statement, assumed present
  • DBDUT0418W More than one PART statement present, all but the first ignored
  • DBDUT0419W PART statement unsupported, treated as a DATASET statement.
Parent topic: DBD Error Messages


DBDUT0401W More than one DBD macro present, all but the first ignored

A warning message. Only the first DBD macro will be processed.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0402W DBD RMNAME operand invalid with ACCESS accesstype, RMNAME ignored

A warning message. RMNAME (randoming module name) is ignored for a database with this type of access.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0403W More than one DBDGEN statement present, all but the first ignored

A warning message. Only the first DBDGEN statement will be processed.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0404W Unknown keyword, keyword for macro, ignored

A warning message. The unknown keyword is ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0405W DBDGEN statement appeared before xxxxxxxx macro

A warning message. The keywords and macros should be put in the proper order.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0406W Field TYPE=H (Halfword), assumed to be two bytes long

A warning message. Fields of this type should be defined as two bytes in length.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0407W Field TYPE=F (Fullword), assumed to be four bytes long

A warning message. Fields of this type should be defined as four bytes in length.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0408W DATASET SCAN operand is invalid for ACCESS accesstype, SCAN ignored

A warning message. The SCAN operand is ignored for this database.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0409W DATASET FRSPC operand is invalid for ACCESS accesstype, FRSPC ignored

A warning message. The FRSPC operand is ignored for this database.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0410W Exceeded maximum of 10 DATASET macros with operands

A warning message. Only ten DATASET macros are recognized.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0411W Label labelname, only the first DATASET with a common label can contain operands

A warning message. Only the first DATASET macro with a common label can contain operands. Second set of operands ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0412W DATASET contains no operands but label labelname not previously defined

A warning message. The DATASET with this label contains no operands.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0413W Duplicate DATASET DDNAME ddname in DD1, DD2, or OVFLW

A warning message. This DDNAME has been used more than once.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0414W Label labelname, DD1 ddname, previous DATASET group contains no segments

A warning message. The DATASET with this label and ddname does not contain any segments.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0415W SEGM macro not preceded by DATASET macro. DATASET is required for access type: accesstype

A warning message. The DATASET macro is missing and is required for a database with this access.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0416W Incorrect RULES specified for sequential dependent segment segname, FIRST rules assumed

A warning message. The RULES specified for this segment are incorrect. Assuming FIRST rules will apply.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0417W Missing required DBDGEN macro statement, assumed present

A warning message. The DBDGEN macro is missing.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0418W More than one PART statement present, all but the first ignored

Parent topic: Messages DBDUT0401 to DBDUT0417


DBDUT0419W PART statement unsupported, treated as a DATASET statement.

Parent topic: Messages DBDUT0401 to DBDUT0417


Messages DBDUT04A1 to DBDUT04A7

  • DBDUT04A1W Continuation cannot start in column 1
  • DBDUT04A2W Expected "=", found "(", "=" is assumed
  • DBDUT04A3W Continuation expected, none received
  • DBDUT04A4W Invalid character following final quote "x"
  • DBDUT04A5W parm has a non-numeric value "value", assumed zero
  • DBDUT04A6W Duplicate keyword xxxxxxxx specified, last one used
  • DBDUT04A7W Expected "," found ")"
Parent topic: DBD Error Messages


DBDUT04A1W Continuation cannot start in column 1

A warning message. Data on a continuation line cannot begin in the first column.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04A1 to DBDUT04A7


DBDUT04A2W Expected "=", found "(", "=" is assumed

A warning message. There is a problem with the syntax. An equal sign is the expected token.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04A1 to DBDUT04A7


DBDUT04A3W Continuation expected, none received

A warning message. There is a problem with the syntax. A continuation character is expected in column 72.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04A1 to DBDUT04A7


DBDUT04A4W Invalid character following final quote "x"

A warning message. There is a problem with the syntax - an invalid data, 'x', follows the final quote.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04A1 to DBDUT04A7


DBDUT04A5W parm has a non-numeric value "value", assumed zero

A warning message. The non-numeric value for parm is not valid and a zero has been substituted.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04A1 to DBDUT04A7


DBDUT04A6W Duplicate keyword xxxxxxxx specified, last one used

A warning message. The keyword was found more than once, so the last one found was used.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04A1 to DBDUT04A7


DBDUT04A7W Expected "," found ")"

Parent topic: Messages DBDUT04A1 to DBDUT04A7


Messages DBDUT04E1 to DBDUT04E2

  • DBDUT04E1W EQU xxxxxxxx error, keyword already has data
  • DBDUT04E2W EQU xxxxxxxx error, data already has a keyword
Parent topic: DBD Error Messages


DBDUT04E1W EQU xxxxxxxx error, keyword already has data

A warning message. There is a problem with the EQUATE statement and an assumption has been made on what data is to be used.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04E1 to DBDUT04E2


DBDUT04E2W EQU xxxxxxxx error, data already has a keyword

A warning message. There is a problem with the EQUATE statement and an assumption has been made on what data is to be used.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT04E1 to DBDUT04E2


Messages DBDUT0801 to DBDUT0882

  • DBDUT0801E SEGM macro not preceded by DBD macro. DBD macro must be first statement in DBD source
  • DBDUT0802E DBD macro missing required NAME operand
  • DBDUT0803E HDAM or DEDB database missing required RMNAME operand
  • DBDUT0804E PARENT segment parentsegname for segment segname not previously defined in this database
  • DBDUT0805E Source segment segname for XDFLD fldname not defined
  • DBDUT0806E SEGM macro missing required NAME operand
  • DBDUT0807E Missing required DBDGEN statement
  • DBDUT0808E SEGM segname has missing or invalid BYTES operand
  • DBDUT0809E SEGM segname, minimum bytes (nnnn) exceeds maximum bytes (nnnn)
  • DBDUT0810E DEDB root segment segname, field fldname not unique
  • DBDUT0811E Non-related MSDB segment segname, field fldname not unique
  • DBDUT0812E INDEX DBD segment segname must contain a sequence field. Field fldname not a sequence field
  • DBDUT0813E FIELD macro not preceded by SEGM macro
  • DBDUT0814E Segment segname, FIELD macro missing required NAME operand
  • DBDUT0815E SEGM segname, FIELD fldname, contains invalid data in name parameter, 3rd operand xxxxxxxx
  • DBDUT0816E DEDB sequential dependent segment segname contains invalid sequence field fldname
  • DBDUT0817E SEGM segname, FIELD fldname contains invalid data in name parameter, 2nd operand xxxx not SEQ
  • DBDUT0818E Segment segname, sequence field fldname must be first field after SEGM for IMS/ESA compatibility. Use system config, IBM DLI PLATFORM setting for DOS/VS syntax
  • DBDUT0819E COPY statement missing required name parameter
  • DBDUT0820E COPY member copymember not found
  • DBDUT0821E Segment segname, field fldname not unique
  • DBDUT0822E Segment segname, field fldname packed length cannot exceed 16 bytes
  • DBDUT0823E Segment segname, field fldname, BYTES operand missing or invalid
  • DBDUT0824E Segment segname, field fldname missing required START operand
  • DBDUT0825E Field fldname extends beyond segment maximum size of nnnnn, field start nnnnn, length nnnnn
  • DBDUT0826E Segment name segname not unique within this DBD
  • DBDUT0827E accesstype ACCESS type requires DATASET DD1 operand when DATASET does not have a label
  • DBDUT0828E DATASET SCAN value of nnnnn, exceeds maximum of 255
  • DBDUT0829E DATASET FRSPC (free block frequency) of nnnnn must be in range of zero to 100, but not 1
  • DBDUT0830E DATASET FRSPC percentage of nnn must be in range of 0 to 99
  • DBDUT0831E LOGICAL DATASET not valid with ACCESS accesstype
  • DBDUT0832E MSDB missing required DATASET REL operand
  • DBDUT0833E Only 1 SEGM statement allowed in MSDB database
  • DBDUT0834E SEGM segname missing required PARENT operand
  • DBDUT0835E Segment segname, length nnnnnn exceeds maximum segment length of 32760
  • DBDUT0836E Segment segname level is deeper than 15, parent segment parentsegment
  • DBDUT0837E DBD ACCESS accesstype does not support Virtual segments
  • DBDUT0838E LCHILD missing required segment NAME operand
  • DBDUT0839E LCHILD segment operand dbdname missing required DBD NAME operand in index DBD
  • DBDUT0840E LCHILD PAIR operand not supported with ACCESS accesstype
  • DBDUT0841E XDFLD statement not supported with ACCESS accesstype
  • DBDUT0842E GSAM DATASET macro missing required RECFM operand
  • DBDUT0843E Missing required DBD macro statement
  • DBDUT0844E SEGM statement not found, DBD requires at least one
  • DBDUT0845E Paired segment segname not found in DBD or occurred more than once
  • DBDUT0846E Index DBD can contain only one LCHILD statement
  • DBDUT0847E Index DBD missing required LCHILD statement
  • DBDUT0848E XDFLD missing required NAME operand
  • DBDUT0849E XDFLD fldname missing required SRCH operand
  • DBDUT0850E XDFLD fldname precedes SEGM statement and is missing SEGMENT operand
  • DBDUT0851E XDFLD fldname has more than 5 SUBSEQ fields
  • DBDUT0852E XDFLD fldname has more than 5 DDATA fields
  • DBDUT0853E XDFLD fldname has more than 5 SRCH fields
  • DBDUT0854E LCHILD lchildname, XDFLD fldname, key length nnnn exceeds maximum CONST,SRCH,SUBSEQ length of 240
  • DBDUT0855E XDFLD fldname, SEGMENT sgmname not defined in database
  • DBDUT0856E XDFLD fldname, SRCH field srchfld not in source segment sgmname
  • DBDUT0857E XDFLD fldname, DDATA field ddatafld not in source segment sgmname
  • DBDUT0858E XDFLD fldname, source segment sgmname, DDATA field ddatafld cannot be a /SX field
  • DBDUT0859E XDFLD fldname, SUBSEQ field fldname not in source segment sgmname
  • DBDUT0860E XDFLD fldname, target segment sgmname not parent of source segment sourcesgmname
  • DBDUT0862E Sequence field fldname in root segment sgmname must be unique for database type accesstype
  • DBDUT0863E GSAM minimum record length exceeds maximum for RECFM=V
  • DBDUT0865E SEGM statement limit of 255 exceeded
  • DBDUT0866E FIELD statement limit of 1000 exceeded
  • DBDUT0867E Segment sgmname, key sequence field fldname, length nnnn exceeds maximum
  • DBDUT0868E Virtual logical child segment sgmname not referenced by an LCHILD PAIR statement
  • DBDUT0869E Paired (real) logical child segment sgmname missing logical PARENT specification
  • DBDUT0870E DBD statement missing required ACCESS operand
  • DBDUT0871E MSDB missing required DATASET REL operand
  • DBDUT0872E XDFLD has no preceding LCHILD statement
  • DBDUT0873E Sequence field fldname, start nnnnn, length nnnnn extends beyond SEGM minimum size of nnnnnbytes
  • DBDUT0874E Segment sgmname, sequence field fldname invalid, only 1 sequence field allowed for this segment type
  • DBDUT0875E Segment sgmname, field fldname, START value parmvalue not numeric or names a field which is not defined for this SEGM
  • DBDUT0876E EXIT parameter is not allowed with ACCESS of accesstype
  • DBDUT0877E Logical SEGM sgmname missing required SOURCE operand
  • DBDUT0878E Segment sgmname, hierarchy sequence error
  • DBDUT0879E First ACCESS statement must precede first SEGM
  • DBDUT0880E ACCESS statement contains mutually exclusive keywords RMRTN and REF
  • DBDUT0881E ACCESS statement only valid with DBD ACCESS=HD
  • DBDUT0882 Segment FIELD statement limit of 255 exceeded
Parent topic: DBD Error Messages


DBDUT0801E SEGM macro not preceded by DBD macro. DBD macro must be first statement in DBD source

An error message. Make sure the DBD macro is the first statement in the source.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0802E DBD macro missing required NAME operand

An error message. Specify the NAME operand for the DBD macro.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0803E HDAM or DEDB database missing required RMNAME operand

An error message. Specify a RMNAME for this database.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0804E PARENT segment parentsegname for segment segname not previously defined in this database

An error message. The parent segment must be defined in the DBD source.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0805E Source segment segname for XDFLD fldname not defined

An error message. The source segment must be defined in the DBD source.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0806E SEGM macro missing required NAME operand

An error message. Specify the NAME operand for the SEGM macro.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0807E Missing required DBDGEN statement

An error message. Specify the missing DBDGEN statement.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0808E SEGM segname has missing or invalid BYTES operand

An error message. The segment is missing the BYTES operand or it is invalid.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0809E SEGM segname, minimum bytes (nnnn) exceeds maximum bytes (nnnn)

An error message. The minimum number of bytes cannot exceed the maximum number for a variable length segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0810E DEDB root segment segname, field fldname not unique

An error message. For segment with access type, DEDB, the root key must be defined as unique.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0811E Non-related MSDB segment segname, field fldname not unique

An error message. For a non-terminal-related MSDB without terminal-related keys, the field must be defined as unique.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0812E INDEX DBD segment segname must contain a sequence field. Field fldname not a sequence field

An error message.

For an INDEX DBD, the segment must contain a sequence field.

INDEX DBDs must have a sequence field.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0813E FIELD macro not preceded by SEGM macro

An error message. This is a syntax error. A SEGM macro must precede a FIELD macro.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0814E Segment segname, FIELD macro missing required NAME operand

An error message. The FIELD macro is missing the NAME operand.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0815E SEGM segname, FIELD fldname, contains invalid data in name parameter, 3rd operand xxxxxxxx

An error message. The data, xxxxxxxx, is invalid as the third parameter.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0816E DEDB sequential dependent segment segname contains invalid sequence field fldname

An error message. A sequential dependent segment in a DEDB may not contain a sequence field.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0817E SEGM segname, FIELD fldname contains invalid data in name parameter, 2nd operand xxxx not SEQ

An error message. For this segment name and field name, there is an invalid data, xxxx, in the second operand.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0818E Segment segname, sequence field fldname must be first field after SEGM for IMS/ESA compatibility. Use system config, IBM DLI PLATFORM setting for DOS/VS syntax

An error message. For ESA compatibility, the sequence field must be the first field after the SEGM macro.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0819E COPY statement missing required name parameter

An error message. The COPY statement is missing the name of the file to copy.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0820E COPY member copymember not found

An error message. The file to copy was not found.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0821E Segment segname, field fldname not unique

An error message. fldname is not a unique field within this segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0822E Segment segname, field fldname packed length cannot exceed 16 bytes

An error message. The length of a packed field cannot exceed 16 bytes.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0823E Segment segname, field fldname, BYTES operand missing or invalid

An error message. An operand, BYTES, is missing for this field.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0824E Segment segname, field fldname missing required START operand

An error message. Missing operand, START, for this field.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0825E Field fldname extends beyond segment maximum size of nnnnn, field start nnnnn, length nnnnn

An error message. The start and/or length of this field positions it beyond the maximum size of the segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0826E Segment name segname not unique within this DBD

An error message. This segment name is not unique.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0827E accesstype ACCESS type requires DATASET DD1 operand when DATASET does not have a label

An error message. The operand, DATASET DD1, is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0828E DATASET SCAN value of nnnnn, exceeds maximum of 255

An error message. The SCAN value exceeds the maximum of 255.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0829E DATASET FRSPC (free block frequency) of nnnnn must be in range of zero to 100, but not 1

An error message. The free block frequency in invalid.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0830E DATASET FRSPC percentage of nnn must be in range of 0 to 99

An error message. The free block frequency percentage is invalid.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0831E LOGICAL DATASET not valid with ACCESS accesstype

An error message. This type of access is not valid with LOGICAL DATASET.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0832E MSDB missing required DATASET REL operand

An error message. The required operand, DATASET REL, is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0833E Only 1 SEGM statement allowed in MSDB database

An error message. A MSDB may only contain one SEGM statement.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0834E SEGM segname missing required PARENT operand

An error message. The PARENT operand is missing for this segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0835E Segment segname, length nnnnnn exceeds maximum segment length of 32760

An error message. The length specified for this segment exceeds the maximum.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0836E Segment segname level is deeper than 15, parent segment parentsegment

An error message. This segment hierarchy exceeds 15 levels.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0837E DBD ACCESS accesstype does not support Virtual segments

An error message. This database type does not support virtual segments.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0838E LCHILD missing required segment NAME operand

An error message. The NAME operand is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0839E LCHILD segment operand dbdname missing required DBD NAME operand in index DBD

An error message. The dbdname operand is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0840E LCHILD PAIR operand not supported with ACCESS accesstype

An error message. The PAIR operand is not supported with this database access type.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0841E XDFLD statement not supported with ACCESS accesstype

An error message. The XDFLD is not support with this database access type.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0842E GSAM DATASET macro missing required RECFM operand

An error message. The RECFM operand is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0843E Missing required DBD macro statement

An error message. The DBD macro is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0844E SEGM statement not found, DBD requires at least one

An error message. The DBD missing a required SEGM statement.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0845E Paired segment segname not found in DBD or occurred more than once

An error message. There is a problem with the specific segment. Either it is not found in the DBD or is defined more than once.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0846E Index DBD can contain only one LCHILD statement

An error message. Only one LCHILD statement can be present for an index DBD.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0847E Index DBD missing required LCHILD statement

An error message. The index DBD must have an LCHILD statement.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0848E XDFLD missing required NAME operand

An error message. The NAME operand is missing for the XDFLD statement.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0849E XDFLD fldname missing required SRCH operand

An error message. The SRCH operand is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0850E XDFLD fldname precedes SEGM statement and is missing SEGMENT operand

An error message. The XDFLD and SEGM statements are out of order and the SEGMENT operand is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0851E XDFLD fldname has more than 5 SUBSEQ fields

An error message. The limit of five SUBSEQ fields has been exceeded for this field.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0852E XDFLD fldname has more than 5 DDATA fields

An error message. The limit of five DDATA fields has been exceeded for this XDFLD.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0853E XDFLD fldname has more than 5 SRCH fields

An error message. The limit of five SRCH fields has been exceeded for this XDFLD.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0854E LCHILD lchildname, XDFLD fldname, key length nnnn exceeds maximum CONST,SRCH,SUBSEQ length of 240

An error message. The length of this XDFLD cannot exceed 240.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0855E XDFLD fldname, SEGMENT sgmname not defined in database

An error message. The SEGMENT for this XDFLD is not found in the database.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0856E XDFLD fldname, SRCH field srchfld not in source segment sgmname

An error message. The search field for this XDFLD is not found in the named source segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0857E XDFLD fldname, DDATA field ddatafld not in source segment sgmname

An error message. The DDATA field for this XDFLD is not found in the named source segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0858E XDFLD fldname, source segment sgmname, DDATA field ddatafld cannot be a /SX field

An error message. The DDATA field for this XDFLD in the named segment cannot be a /SX field.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0859E XDFLD fldname, SUBSEQ field fldname not in source segment sgmname

An error message. The SUBSEQ field for this XDFLD in no found in the source segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0860E XDFLD fldname, target segment sgmname not parent of source segment sourcesgmname

An error message. The target segment in this XDFLD is not the parent of the source segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0862E Sequence field fldname in root segment sgmname must be unique for database type accesstype

An error message. The sequence field in the root segment must be defined as unique.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0863E GSAM minimum record length exceeds maximum for RECFM=V

An error message. The maximum record length exceeds the minimum record length.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0865E SEGM statement limit of 255 exceeded

An error message. The maximum number of SEGM statements has been exceeded.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0866E FIELD statement limit of 1000 exceeded

An error message. The maximum number of FIELD statements has been exceeded.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0867E Segment sgmname, key sequence field fldname, length nnnn exceeds maximum

An error message. The key sequence field for this segment exceeds the maximum.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0868E Virtual logical child segment sgmname not referenced by an LCHILD PAIR statement

An error message. The virtual logical child segment is invalid.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0869E Paired (real) logical child segment sgmname missing logical PARENT specification

An error message. The named segment is missing the PARENT specification.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0870E DBD statement missing required ACCESS operand

An error message. The ACCESS operand is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0871E MSDB missing required DATASET REL operand

An error message. The DATASET REL operand is missing.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0872E XDFLD has no preceding LCHILD statement

An error message. And XDFLD must have a preceding LCHILD statement.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0873E Sequence field fldname, start nnnnn, length nnnnn extends beyond SEGM minimum size of nnnnnbytes

An error message. This field extends beyond the segment minimum size.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0874E Segment sgmname, sequence field fldname invalid, only 1 sequence field allowed for this segment type

An error message. Only one sequence field is permitted for this segment type.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0875E Segment sgmname, field fldname, START value parmvalue not numeric or names a field which is not defined for this SEGM

An error message. The START value for this field is either non-numeric or names a field not defined in this segment.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0876E EXIT parameter is not allowed with ACCESS of accesstype

An error message. The EXIT parameter is invalid with the access type.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0877E Logical SEGM sgmname missing required SOURCE operand

An error message. The named segment is missing the required SOURCE operand.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0878E Segment sgmname, hierarchy sequence error

An error message. The named segment is not in the correct hierarchy.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0879E First ACCESS statement must precede first SEGM

An error message. The first ACCESS statement must precede the first SEGM statement.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0880E ACCESS statement contains mutually exclusive keywords RMRTN and REF

An error message. The named keywords are mutually exclusive.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0881E ACCESS statement only valid with DBD ACCESS=HD

An error message. This is an invalid ACCESS statement for this access type.

Parent topic: Messages DBDUT0801 to DBDUT0882


DBDUT0882 Segment FIELD statement limit of 255 exceeded

An error message. The limit of 255 fields per segment has been exceeded.

Parent topic: Messages DBDUT0801 to DBDUT0882


Messages DBDUT08A1 to DBDUT08A3

  • DBDUT08A1E Unmatched parentheses
  • DBDUT08A2E Unmatched quotes
  • DBDUT08A3E Positional operand cannot follow keyword operand: operanddata
Parent topic: DBD Error Messages


DBDUT08A1E Unmatched parentheses

An error message. Unmatched parentheses were found.

Parent topic: Messages DBDUT08A1 to DBDUT08A3


DBDUT08A2E Unmatched quotes

An error message. Unmatched quotes were found.

Parent topic: Messages DBDUT08A1 to DBDUT08A3


DBDUT08A3E Positional operand cannot follow keyword operand: operanddata

An error message. The specified operand is out-of-order.

Parent topic: Messages DBDUT08A1 to DBDUT08A3


Messages DBDUT08P1 to DBDUT08P2

  • DBDUT08P1E Number of list operands exceeds MFIMS maximum of nnn
  • DBDUT08P2E Macro macro, keyword keyword has unmatched parentheses
Parent topic: DBD Error Messages


DBDUT08P1E Number of list operands exceeds MFIMS maximum of nnn

An error message. The number of operands has exceeded the limit.

Parent topic: Messages DBDUT08P1 to DBDUT08P2


DBDUT08P2E Macro macro, keyword keyword has unmatched parentheses

An error message. Unmatched parentheses were found for the specified macro and keyword.

Parent topic: Messages DBDUT08P1 to DBDUT08P2


Messages DBDUT0L02 to DBDUT0L99

  • DBDUT0L02E MFIMS does not support GSAM undefined length records
  • DBDUT0L05E Bidirectional pairings exceed MFIMS limit of nnnn per DBD
  • DBDUT0L09E XDFLD statements exceed MFIMS limit of nnnn per DBD
  • DBDUT0L10E Index DBD can only contain one SEGM statement in MFIMS. Shared index databases must be defined with separate DBDs
  • DBDUT0L11E This database requires a nnnnn byte MFIMS control key and exceeds the maximum of nnnn bytes
  • DBDUT0L12E XDFLD exceeds MFIMS maximum index record size of nnnnn
  • DBDUT0L13E MFIMS user data extension incorrectly used for XDFLD fldname. USTART operand is required when PTR=SYMB and concatenated key (CK) BYTES or START overridden
  • DBDUT0L14E MFIMS user data extension incorrectly used in XDFLD fldname. XDFLD USTART operand is not beyond lengths of CONST,SRCH,SUBSEQ, and DDATA fields
  • DBDUT0L15E Segment segname, IMS86KEY value keyvalue must be less than field fldname BYTES value nnnnn
  • DBDUT0L16E IMS86KEY operand only valid for sequenced segments
  • DBDUT0L17E Number of logical children segments exceed MFIMS limit of nnnn per DBD
  • DBDUT0L18E Segment segname, field fldname exceeds MFIMS limit of 8 sequence fields for a virtual logical child segment
  • DBDUT0L19E MFIMS supports a maximum of nn data capture EXITs per SEGM.
  • DBDUT0L20E Database dbname, specifies ACCESS=HD and requires MFIMS IBM DLI PLATFORM configuration to be set to DOS/VS
  • DBDUT0L21E ACCESS statements exceed MFIMS limit of nnnn per DBD
  • DBDUT0L99E Valid software license not present. Reason code (nnnn)
Parent topic: DBD Error Messages


DBDUT0L02E MFIMS does not support GSAM undefined length records

An error message. GSAM undefined length records are not supported.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L05E Bidirectional pairings exceed MFIMS limit of nnnn per DBD

An error message. The bidirectional pairings has exceeded the limit permitted for a DBD.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L09E XDFLD statements exceed MFIMS limit of nnnn per DBD

An error message. The number of XDFLD statements has exceeded the limit permitted for a DBD.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L10E Index DBD can only contain one SEGM statement in MFIMS. Shared index databases must be defined with separate DBDs

An error message. An Index DBD may contain only one SEGM statement.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L11E This database requires a nnnnn byte MFIMS control key and exceeds the maximum of nnnn bytes

An error message. The control key exceeds the maximum bytes allowed.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L12E XDFLD exceeds MFIMS maximum index record size of nnnnn

An error message. This XDFLD exceeds the maximum index record size permitted.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L13E MFIMS user data extension incorrectly used for XDFLD fldname. USTART operand is required when PTR=SYMB and concatenated key (CK) BYTES or START overridden

An error message. The User data extension is incorrectly used for this XDFLD.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L14E MFIMS user data extension incorrectly used in XDFLD fldname. XDFLD USTART operand is not beyond lengths of CONST,SRCH,SUBSEQ, and DDATA fields

An error message. The User data extension is incorrectly used for this XDFLD.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L15E Segment segname, IMS86KEY value keyvalue must be less than field fldname BYTES value nnnnn

An error message. For the named segment, the value for IMS86KEY must be less than the BYTES value for the named field.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L16E IMS86KEY operand only valid for sequenced segments

An error message. IMS86KEY not valid for non-sequenced segments.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L17E Number of logical children segments exceed MFIMS limit of nnnn per DBD

An error message. The number of logical child segments exceeds the maximum.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L18E Segment segname, field fldname exceeds MFIMS limit of 8 sequence fields for a virtual logical child segment

An error message. The maximum number of sequence fields for a virtual logical child segment has exceeded the maximum of 8.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L19E MFIMS supports a maximum of nn data capture EXITs per SEGM.

An error message. The number of data capture EXITs has been exceeded.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L20E Database dbname, specifies ACCESS=HD and requires MFIMS IBM DLI PLATFORM configuration to be set to DOS/VS

An error message .This database access type required configuration set to DOS/VS.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L21E ACCESS statements exceed MFIMS limit of nnnn per DBD

An error message. The number of ACCESS statements has exceeded the maximum permitted.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


DBDUT0L99E Valid software license not present. Reason code (nnnn)

An error message. Missing valid software license.

Parent topic: Messages DBDUT0L02 to DBDUT0L99


Messages DBDUT0LA1 to DBDUT0LA2

  • DBDUT0LA1E Positional operand cannot follow keyword operand: operanddata MFIMS does not perform MFSGEN syntax error recovery
  • DBDUT0LA2E Length of operand exceeds MFIMS maximum of nnnn bytes
Parent topic: DBD Error Messages


DBDUT0LA1E Positional operand cannot follow keyword operand: operanddata MFIMS does not perform MFSGEN syntax error recovery

An error message. The specified positional operand is out-of-order.

Parent topic: Messages DBDUT0LA1 to DBDUT0LA2


DBDUT0LA2E Length of operand exceeds MFIMS maximum of nnnn bytes

An error message. The length of the operand has exceeded the maximum.

Parent topic: Messages DBDUT0LA1 to DBDUT0LA2


Messages DBDUT0LP1 to DBDUT0LP3

  • DBDUT0LP1E Length of operand exceeds MFIMS size of nnnn bytes
  • DBDUT0LP2E Number of list operands exceeds MFIMS maximum of nnn
  • DBDUT0LP3E Length of list exceeds MFIMS maximum of nnnn bytes
Parent topic: DBD Error Messages


DBDUT0LP1E Length of operand exceeds MFIMS size of nnnn bytes

An error message. The length of the operand has exceeded the maximum.

Parent topic: Messages DBDUT0LP1 to DBDUT0LP3


DBDUT0LP2E Number of list operands exceeds MFIMS maximum of nnn

An error message. The number of list operands and exceeded the maximum.

Parent topic: Messages DBDUT0LP1 to DBDUT0LP3


DBDUT0LP3E Length of list exceeds MFIMS maximum of nnnn bytes

An error message. The length of the list has exceeded the maximum.

Parent topic: Messages DBDUT0LP1 to DBDUT0LP3


Messages DBDUT0U01 to DBDUT0U35

  • DBDUT0U01U File status status opening file filename. reason
  • DBDUT0U02U File status status issuing close for file filename. reason
  • DBDUT0U03U File status status issuing read for file filename. reason
  • DBDUT0U04U File status status issuing set/date for DBDGEN. reason
  • DBDUT0U05U File status status issuing close for DBDGEN file. reason
  • DBDUT0U06U File status status issuing close for DBDGEN field file. reason
  • DBDUT0U07U File status status issuing create file for DBDGEN. reason
  • DBDUT0U08U File status status issuing create file for DBDGEN field file. reason
  • DBDUT0U09U File status status issuing delete for DBDGEN. reason
  • DBDUT0U10U File status status issuing delete for DBDGEN field file. reason
  • DBDUT0U11U File status status issuing write for DBDGEN file. reason
  • DBDUT0U12U File status status issuing start/read for DBDGEN file. reason
  • DBDUT0U13U File status status issuing read by key for DBDGEN file. reason
  • DBDUT0U35U File not found filename
Parent topic: DBD Error Messages


DBDUT0U01U File status status opening file filename. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U02U File status status issuing close for file filename. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U03U File status status issuing read for file filename. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U04U File status status issuing set/date for DBDGEN. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U05U File status status issuing close for DBDGEN file. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U06U File status status issuing close for DBDGEN field file. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U07U File status status issuing create file for DBDGEN. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U08U File status status issuing create file for DBDGEN field file. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U09U File status status issuing delete for DBDGEN. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U10U File status status issuing delete for DBDGEN field file. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U11U File status status issuing write for DBDGEN file. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U12U File status status issuing start/read for DBDGEN file. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U13U File status status issuing read by key for DBDGEN file. reason

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


DBDUT0U35U File not found filename

An error message. An error occurred during the file operation.

Parent topic: Messages DBDUT0U01 to DBDUT0U35


Messages DBDUT0W01 to DBDUT0W36

  • DBDUT0W01W Nested COPY statements are not supported by MFIMS: stmtdata
  • DBDUT0W03W MFIMS statement continuation overflow, extras ignored. Maximum number of lines per statement is nn
  • DBDUT0W04W SEGM segname, SSPTR not supported by MFIMS, SSPTR ignored
  • DBDUT0W06W Segment segname, field fldname length nnnnn exceeds MFIMS SSA/FSA limit of nnn, length reduced to nnn
  • DBDUT0W08W XDFLD fldname, EXTRNCBL operand operand no longer required
  • DBDUT0W09W Segment segname, RULES=HERE for logical children is not supported by MFIMS, RULES changed to LAST
  • DBDUT0W10W Segment segname, RULES=HERE on a root segment is not supported by MFIMS, RULES changed to LAST
  • DBDUT0W11W MFIMS IMS86KEY extension specified for segment segname field fldname
  • DBDUT0W13W MFIMS does not support asynchronous data capture, EXIT option for exitname changed from LOG to NOLOG
  • DBDUT0W14W MFIMS does not support asynchronous data capture, EXIT parameter name "*" ignored
  • DBDUT0W15W Variable GSAM RECORD value missing minimum length, MFIMS assuming minimum length 1
  • DBDUT0W16W Unknown statement "stmt" ignored, unsupported by MFIMS
  • DBDUT0W17W DBDGEN VERSION truncated to MFIMS maximum 128 bytes
  • DBDUT0W18W Comment line continuation has non-blanks in columns 1-15, MFIMS assumes blank: data
  • DBDUT0W19W Duplicate keys for secondary index fldname not supported by MFIMS for DOS/VS ACCESS=HD database, index assumed unique. See Technical Reference "For the DBA" chapter.
  • DBDUT0W35W
  • DBDUT0W36W File has been created filename.
Parent topic: DBD Error Messages


DBDUT0W01W Nested COPY statements are not supported by MFIMS: stmtdata

A warning message. Nested COPY statements are not supported.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W03W MFIMS statement continuation overflow, extras ignored. Maximum number of lines per statement is nn

A warning message. The statement has exceeded the maximum number of lines permitted. The extra lines are ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W04W SEGM segname, SSPTR not supported by MFIMS, SSPTR ignored

A warning message. SSPTR is not supported and is ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W06W Segment segname, field fldname length nnnnn exceeds MFIMS SSA/FSA limit of nnn, length reduced to nnn

A warning message. The length of this field is too long and has been reduced.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W08W XDFLD fldname, EXTRNCBL operand operand no longer required

A warning message. The EXTRNCBL operand is not required and is ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W09W Segment segname, RULES=HERE for logical children is not supported by MFIMS, RULES changed to LAST

A warning message. MSS does not support the RULES=HERE clause on a SEGM statement for logical children. The RULES=HERE clause has been changed to RULES=LAST as HERE is not supported to logical children.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W10W Segment segname, RULES=HERE on a root segment is not supported by MFIMS, RULES changed to LAST

A warning message. The RULES has been changed to LAST as HERE is not supported for a root segment.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W11W MFIMS IMS86KEY extension specified for segment segname field fldname

A warning message. A MFIMS extension is being used for this segment and field.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W13W MFIMS does not support asynchronous data capture, EXIT option for exitname changed from LOG to NOLOG

A warning message. The option for this EXIT has been changed from LOG to NOLOG as asynchronous data capture is not supported.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W14W MFIMS does not support asynchronous data capture, EXIT parameter name "*" ignored

A warning message. The EXIT parameter name is ignored as asynchronous data capture is not supported.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W15W Variable GSAM RECORD value missing minimum length, MFIMS assuming minimum length 1

A warning message. A length is missing and a length of one is being assumed.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W16W Unknown statement "stmt" ignored, unsupported by MFIMS

A warning message. This statement is unknown and is ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W17W DBDGEN VERSION truncated to MFIMS maximum 128 bytes

Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W18W Comment line continuation has non-blanks in columns 1-15, MFIMS assumes blank: data

A warning message. The continuation has non-blanks in columns one through 15 that are ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W19W Duplicate keys for secondary index fldname not supported by MFIMS for DOS/VS ACCESS=HD database, index assumed unique. See Technical Reference "For the DBA" chapter.

A warning message. Duplicate keys for this secondary index field are not supported for this access type.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W35W

Parent topic: Messages DBDUT0W01 to DBDUT0W36


DBDUT0W36W File has been created filename.

Parent topic: Messages DBDUT0W01 to DBDUT0W36


Messages DBDUT0WA1 to DBDUT0WA9

  • DBDUT0WA1W BLANK line not allowed, MFIMS ignores blank lines
  • DBDUT0WA2W Exceeded MFIMS maximum number of operands, extras ignored
  • DBDUT0WA3W Columns 1-15 non-blank on continuation, MFIMS assumes blank
  • DBDUT0WA4W LABEL exceeds 8 bytes, MFIMS truncated to 8
  • DBDUT0WA5W Statement type must be on 1st line, ignored
  • DBDUT0WA6W stmt and other macro control statements not supported by MFIMS. This and subsequent control statements ignored
  • DBDUT0WA7W Column 16 on continuation was blank, MFIMS ignoring line
  • DBDUT0WA8W Missing comma for continuation, MFIMS assumed present
  • DBDUT0WA9W Invalid value "value" - MFIMS ignored keyword and value
Parent topic: DBD Error Messages


DBDUT0WA1W BLANK line not allowed, MFIMS ignores blank lines

A warning message. Blank lines are ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA2W Exceeded MFIMS maximum number of operands, extras ignored

A warning message. The extra operands are ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA3W Columns 1-15 non-blank on continuation, MFIMS assumes blank

A warning message. Continued lines should contain blanks in columns one through 15. Blanks have been assumed.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA4W LABEL exceeds 8 bytes, MFIMS truncated to 8

A warning message. Labels are limited to 8 bytes. The label has been truncated.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA5W Statement type must be on 1st line, ignored

A warning message. The statement type is ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA6W stmt and other macro control statements not supported by MFIMS. This and subsequent control statements ignored

A warning message. This control statement is not supported and ignored.
Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA7W Column 16 on continuation was blank, MFIMS ignoring line

A warning message. The continuation line is ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA8W Missing comma for continuation, MFIMS assumed present

A warning message. The missing continuation comma is assumed to be present.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


DBDUT0WA9W Invalid value "value" - MFIMS ignored keyword and value

A warning message. This value and the keyword are ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WA1 to DBDUT0WA9


Messages DBDUT0WE1 to DBDUT0WE2

  • DBDUT0WE1W MFIMS EQU limit of nnnn exceeded, extras ignored
  • DBDUT0WE2W EQU equate contains unbalanced quotes. Maximum MFIMS EQU length is nnnn
Parent topic: DBD Error Messages


DBDUT0WE1W MFIMS EQU limit of nnnn exceeded, extras ignored

A warning message. The extra EQU macros are ignored.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WE1 to DBDUT0WE2


DBDUT0WE2W EQU equate contains unbalanced quotes. Maximum MFIMS EQU length is nnnn

A warning message. The EQU parameter contains mismatched quotes.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WE1 to DBDUT0WE2


Messages DBDUT0WF1 to DBDUT0WF2

  • DBDUT0WF1W In-line CSECT or DSECT is not supported by MFIMS. Ignoring all statements until END statement
  • DBDUT0WF2W In-line macro definitions not supported by MFIMS. Ignoring all statements until MEND statement
Parent topic: DBD Error Messages


DBDUT0WF1W In-line CSECT or DSECT is not supported by MFIMS. Ignoring all statements until END statement

A warning message. CSECT and DSECT statements are not supported. All subsequent statements are ignored until the END statement is found.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WF1 to DBDUT0WF2


DBDUT0WF2W In-line macro definitions not supported by MFIMS. Ignoring all statements until MEND statement

A warning message. In-line macro definitions are not supported. All subsequent statements are ignored until the MEND statement is found.

Note: Warning messages do not prevent DBD generation from completing; however, Micro Focus does not guarantee the results.
Parent topic: Messages DBDUT0WF1 to DBDUT0WF2


DBDUT0WP2W MFIMS supports a maximum of %2% data capture exit routines per segment, first %2% routines accepted

Parent topic: DBD Error Messages


DBUTIL Error Messages

These messages are output by the IMS DBUTIL utility and have the prefix IMSUT. 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.

  • IMSUT0115I DBUTIL: Processing complete - %6 calls were issued
  • IMSUT0532E DD statement missing for %8
  • IMSUT0533E SYSIN LRECL exceeds DBUTIL maximum of %5%
  • IMSUT0534E Dynamic memory allocation failure. RC=%8% Size=%5%
  • IMSUT0535E Function is required for interactive calls
  • IMSUT0536E PCB Number is required for interactive calls
  • IMSUT0537E Cannot mix control cards with interactive call
  • IMSUT0538E SYSIN dataset not found. DSN=%60
  • IMSUT0539E SYSIN dataset open failure status=%5% DSN=%60
  • IMSUT0540E terminated "LDIX" due to status code of %2%
  • IMSUT0541E SEGM %8 is not in PCB for: %8
  • IMSUT0542E Dataset not found: %60
  • IMSUT0543E DBUTIL terminated %4 due to status code of %2%
  • IMSUT0544E Error status= %5% reading input dataset DSN=%60
  • IMSUT0545E Invalid length in record. Length=%8
  • IMSUT0546E Error opening input dataset. Status code: %5% DSN=%60
  • IMSUT0547E Input file not found. DSN=%60
  • IMSUT0548E "MLOD" can only be issued for MSDBs
  • IMSUT0549E Invalid command syntax. DSN required
  • IMSUT0550E Cannnot load remote database %8
  • IMSUT0551E Cannot "LOAD" "INDEX" database %8
  • IMSUT0552E Cannot "LOAD" database %8 USING "PROCSEQ" PCB
  • IMSUT0553E "USEQ" does not support "REMOTE" database
  • IMSUT0554E "USEQ" does not support "USER CAT" database
  • IMSUT0555E Error status %5% opening output dataset DSN=%60
  • IMSUT0556E LRECL for unload not given and default not available
  • IMSUT0557E "UNLO" of logical DBD requires a non-zero LRECL specification, or variable length RECFM
  • IMSUT0558E "USEQ" does not support variable length
  • IMSUT0559E Invalid command syntax. RC=%4
  • IMSUT0560E Invalid command syntax. DSN required
  • IMSUT0561E Database selected is not a DEDB
  • IMSUT0562E GSAM PCB missing required "RECLEN" parameter
  • IMSUT0563E PCB number %3 not defined in PSB
  • IMSUT0564E GSAM PCB missing required RECLEN parameter
  • IMSUT0565E Cannot issue calls against IO or ALT TP PCBs
  • IMSUT0566E DBD referenced by PCB number not defined
  • IMSUT0567E PCB number not numeric
  • IMSUT0568E PCB number cannot be zero
  • IMSUT0569E DBD name not found in PCB list
  • IMSUT0570E No PCB ID provided
  • IMSUT0571E Continuation error card number %6. Card=%65
  • IMSUT0572E "LOAD" of logical DBD requires a non-zero LRECL specification, or variable length RECFM
  • IMSUT0573E LRECL for load not given and default not available
  • IMSUT0574E This version of DBUTIL does not support %4
  • IMSUT0575E %4 function only available when run as DBB or DLI
  • IMSUT0576E This version of IMSDBU only supports the batch interface
  • IMSUT0577E SYSOUT dataset open failure status=%5% DSN=%60
  • IMSUT0578E Write to SYSOUT dataset failure status=%5%
  • IMSUT0580E Information for PSB %8 not found in configuration file
  • IMSUT0602E Input card dataset is busy. Try later. DSN=%60
Parent topic: IMS Error Messages


IMSUT0115I DBUTIL: Processing complete - %6 calls were issued

Parent topic: DBUTIL Error Messages


IMSUT0532E DD statement missing for %8

Parent topic: DBUTIL Error Messages


IMSUT0533E SYSIN LRECL exceeds DBUTIL maximum of %5%

Parent topic: DBUTIL Error Messages


IMSUT0534E Dynamic memory allocation failure. RC=%8% Size=%5%

Parent topic: DBUTIL Error Messages


IMSUT0535E Function is required for interactive calls

Parent topic: DBUTIL Error Messages


IMSUT0536E PCB Number is required for interactive calls

Parent topic: DBUTIL Error Messages


IMSUT0537E Cannot mix control cards with interactive call

Parent topic: DBUTIL Error Messages


IMSUT0538E SYSIN dataset not found. DSN=%60

Parent topic: DBUTIL Error Messages


IMSUT0539E SYSIN dataset open failure status=%5% DSN=%60

Parent topic: DBUTIL Error Messages


IMSUT0540E terminated "LDIX" due to status code of %2%

Parent topic: DBUTIL Error Messages


IMSUT0541E SEGM %8 is not in PCB for: %8

Parent topic: DBUTIL Error Messages


IMSUT0542E Dataset not found: %60

Parent topic: DBUTIL Error Messages


IMSUT0543E DBUTIL terminated %4 due to status code of %2%

Parent topic: DBUTIL Error Messages


IMSUT0544E Error status= %5% reading input dataset DSN=%60

Parent topic: DBUTIL Error Messages


IMSUT0545E Invalid length in record. Length=%8

Parent topic: DBUTIL Error Messages


IMSUT0546E Error opening input dataset. Status code: %5% DSN=%60

Parent topic: DBUTIL Error Messages


IMSUT0547E Input file not found. DSN=%60

Parent topic: DBUTIL Error Messages


IMSUT0548E "MLOD" can only be issued for MSDBs

Parent topic: DBUTIL Error Messages


IMSUT0549E Invalid command syntax. DSN required

Parent topic: DBUTIL Error Messages


IMSUT0550E Cannnot load remote database %8

Parent topic: DBUTIL Error Messages


IMSUT0551E Cannot "LOAD" "INDEX" database %8

Parent topic: DBUTIL Error Messages


IMSUT0552E Cannot "LOAD" database %8 USING "PROCSEQ" PCB

Parent topic: DBUTIL Error Messages


IMSUT0553E "USEQ" does not support "REMOTE" database

Parent topic: DBUTIL Error Messages


IMSUT0554E "USEQ" does not support "USER CAT" database

Parent topic: DBUTIL Error Messages


IMSUT0555E Error status %5% opening output dataset DSN=%60

Parent topic: DBUTIL Error Messages


IMSUT0556E LRECL for unload not given and default not available

Parent topic: DBUTIL Error Messages


IMSUT0557E "UNLO" of logical DBD requires a non-zero LRECL specification, or variable length RECFM

Parent topic: DBUTIL Error Messages


IMSUT0558E "USEQ" does not support variable length

Parent topic: DBUTIL Error Messages


IMSUT0559E Invalid command syntax. RC=%4

Parent topic: DBUTIL Error Messages


IMSUT0560E Invalid command syntax. DSN required

Parent topic: DBUTIL Error Messages


IMSUT0561E Database selected is not a DEDB

Parent topic: DBUTIL Error Messages


IMSUT0562E GSAM PCB missing required "RECLEN" parameter

Parent topic: DBUTIL Error Messages


IMSUT0563E PCB number %3 not defined in PSB

Parent topic: DBUTIL Error Messages


IMSUT0564E GSAM PCB missing required RECLEN parameter

Parent topic: DBUTIL Error Messages


IMSUT0565E Cannot issue calls against IO or ALT TP PCBs

Parent topic: DBUTIL Error Messages


IMSUT0566E DBD referenced by PCB number not defined

Parent topic: DBUTIL Error Messages


IMSUT0567E PCB number not numeric

Parent topic: DBUTIL Error Messages


IMSUT0568E PCB number cannot be zero

Parent topic: DBUTIL Error Messages


IMSUT0569E DBD name not found in PCB list

Parent topic: DBUTIL Error Messages


IMSUT0570E No PCB ID provided

Parent topic: DBUTIL Error Messages


IMSUT0571E Continuation error card number %6. Card=%65

Parent topic: DBUTIL Error Messages


IMSUT0572E "LOAD" of logical DBD requires a non-zero LRECL specification, or variable length RECFM

Parent topic: DBUTIL Error Messages


IMSUT0573E LRECL for load not given and default not available

Parent topic: DBUTIL Error Messages


IMSUT0574E This version of DBUTIL does not support %4

Parent topic: DBUTIL Error Messages


IMSUT0575E %4 function only available when run as DBB or DLI

Parent topic: DBUTIL Error Messages


IMSUT0576E This version of IMSDBU only supports the batch interface

Parent topic: DBUTIL Error Messages


IMSUT0577E SYSOUT dataset open failure status=%5% DSN=%60

Parent topic: DBUTIL Error Messages


IMSUT0578E Write to SYSOUT dataset failure status=%5%

Parent topic: DBUTIL Error Messages


IMSUT0580E Information for PSB %8 not found in configuration file

Parent topic: DBUTIL Error Messages


IMSUT0602E Input card dataset is busy. Try later. DSN=%60

Parent topic: DBUTIL Error Messages


IMS Database Editor Error Messages

  • Could not open database, IMS logon failed, rc=RC, rc2=RC2
    Your attempt to log on to the IMS component has failed, where:
  • Logoff for database failed, rc=RC, rc2=RC2
    Your attempt to log off from the IMS component has failed, where:
  • Cannot open database, abend 476, invalid PCB address. DBD database may not have been genned
    You have tried to open a database that IMS cannot find, where database is the name of the database.
  • Cannot open database, generate PCB from DBD failed, rc=RC, rc2=RC2
    When you tried to open a database, IMS could not generate a PCB from the DBD, where:
  • Cannot open database, generate PCB from PSB failed, rc=RC, rc2=RC2
    When you tried to open a database, IMS could not generate a PCB from the PSB, where:
  • Cannot open database, failed to read details required to edit DBD database, status: status
    When you attempted to open a database, IMS had problems reading the IMS Option database information, where:
  • Cannot open database, failed to read details required to edit PCB #PCB in PSB database, status: status
    When you attempted to open a database, IMS had problems reading the PSB information, where:
  • Cannot open PCB #PCB in PSB database, the secondary index must be genned before opening
    You have attempted to open a PCB before compiling the secondary index database definition (DBD), where:
  • Failed to load bookmark_file, status: status
    You have attempted to load a bookmark file and encountered a general failure:
  • Failed to load bookmarks, file is not an IMS DB Editor bookmark file
    You have attempted to download bookmarks from a file that is not a bookmark file, where file is the name of your selected file.
  • Failed to save bookmark_file, status: status
    When attempting to save a bookmark file, you encountered a general failure, where:
Parent topic: IMS Error Messages


Could not open database, IMS logon failed, rc=RC, rc2=RC2

database | is the name of the database
RC | is the RC value in the format RCnnnn
RC2 | is the RC2 value in the format RC2nnnn

Resolution:

If RC=0012:

See the IMS System log for more information.

Otherwise:

If the problem persists, report to Technical Support.

Parent topic: IMS Database Editor Error Messages


Logoff for database failed, rc=RC, rc2=RC2

database | is the name of the database
RC | is the RC value in the format RCnnnn
RC2 | is the RC2 value in the format RC2nnnn

Resolution:

If the problem persists, report to Technical Support.

Parent topic: IMS Database Editor Error Messages


Cannot open database, abend 476, invalid PCB address. DBD database may not have been genned

Resolution:

Recompile the database definition (DBD).

Parent topic: IMS Database Editor Error Messages


Cannot open database, generate PCB from DBD failed, rc=RC, rc2=RC2

RC | is the RC value in the format RCnnnn
RC2 | is the RC2 value in the format RC2nnnn

Resolution:

If the problem persists, report to Technical Support.

Parent topic: IMS Database Editor Error Messages


Cannot open database, generate PCB from PSB failed, rc=RC, rc2=RC2

RC | is the RC value in the format RCnnnn
RC2 | is the RC2 value in the format RC2nnnn

If RC=0012 and RC2=2053:

the PSB contains no database PCBs.

Otherwise:

the Schedule PSB (psbname) failed.

Resolution:

If RC=0012 and RC2=2053:

You cannot use this PSB to edit an IMS database.

Otherwise:

If the problem persists, report to Technical Support.

Parent topic: IMS Database Editor Error Messages


Cannot open database, failed to read details required to edit DBD database, status: status

database | is the name of the database
status | is the error returned from GIO

Resolution:

If the problem persists, report to Technical Support.

Parent topic: IMS Database Editor Error Messages


Cannot open database, failed to read details required to edit PCB #PCB in PSB database, status: status

database | is the name of the database
status | is the error returned from GIO

Resolution:

If the problem persists, report to Technical Support.

Parent topic: IMS Database Editor Error Messages


Cannot open PCB #PCB in PSB database, the secondary index must be genned before opening

PCB | is the PCB number
database | is the PSB-name

When using the IMS Database Editor to edit a PCB which specifies a secondary processing sequence (PROCSEQ), you must compile the secondary index database definition (DBD).

You can use a primary processing sequence to edit a database without compiling the secondary index DBD.

Resolution:

To use a secondary processing sequence (PROCSEQ) to edit the database, compile the secondary index database definition (DBD) beforehand. Otherwise, use a primary processing sequence to edit the database.

Parent topic: IMS Database Editor Error Messages


Failed to load bookmark_file, status: status

bookmark_file | is the filename of the bookmark file
status | is the Callable File Handler status code

Resolution:

Check that the bookmark file has not been corrupted.

Parent topic: IMS Database Editor Error Messages


Failed to load bookmarks, file is not an IMS DB Editor bookmark file

Resolution:

Locate the bookmark file you require and try again.

Parent topic: IMS Database Editor Error Messages


Failed to save bookmark_file, status: status

bookmark_file | is the filename you have chosen for the bookmark file
status | is the Callable File Handler status code

Resolution:

Examine the Callable File Handler status code and take appropriate action.

Parent topic: IMS Database Editor Error Messages


IMS Run-time System Error Messages

These messages are output by the IMS run-time system, so can be produced at any time when you are running your IMS application. 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. These messages have the prefix IMSRT.

  • IMSRT0000I <message text>
  • IMSRT0039E ACB failure for %8. %60%
  • IMSRT0040E PSB Authorization failure for %8.
  • IMSRT0041E No ACEE available. Function %4 can't test authorization of %8
  • IMSRT0042E Error initializing MFIMS - IMS terminating. %12% not found or incorrect version
  • IMSRT0043E Error initializing MFIMS - IMS terminating. Error opening/reading IMSCONFG file. File Status: %6 Description: %40%
  • IMSRT0044E Error initializing MFIMS - IMS terminating. Error opening %6 files. File Status: %6 Description: %40%
  • IMSRT0045E Error initializing MFIMS - IMS terminating. Failure reason code: %4
  • IMSRT0052I The following POP-UP was suppressed during shutdown
  • IMSRT0053I The following POP-UP was suppressed by system request
  • IMSRT0054I Suppression resulted in automatic termination
  • IMSRT0055I End of message
  • IMSRT0056I OPTION VALUE MUST BE "C" OR "T"
  • IMSRT0057I OPTION VALUE MUST BE "Y" OR "N"
  • IMSRT0058I OPTION VALUE MUST BE "R" OR "T"
  • IMSRT0059I INVALID KEY PRESSED
  • IMSRT0060I ONLY 4 DIGITS ARE ALLOWED
  • IMSRT0061I LIMIT VALUE NOT NUMERIC
  • IMSRT0062I STATUS CODE MUST BE TWO BYTE VALUE OR BLANK
  • IMSRT0063I OPTION MUST BE "C", "T", OR "S"
  • IMSRT0064I SAVE OPTION ONLY AVAILABLE ON WINDOWS NT
  • IMSRT0065I USERID IS A REQUIRED FIELD
  • IMSRT0066I PASSWORD IS A REQUIRED FIELD
  • IMSRT0068I MFIMS SYSTEM WINDOW ERROR
  • IMSRT0069I CONTACT TECHNICAL SUPPORT
  • IMSRT0070I PRESS ENTER TO TERMINATE
  • IMSRT0080E Error allocating memory for ACB DBD field blocks REF1: %4 REF2: %5
  • IMSRT0081E ACB create/modify failure: Too many DBD fields Total DBD fields required for this PSB exceeds: %6
  • IMSRT0082E ACB create/modify failure: Caching SENSEG/SENFLD SENSEG/SENFLD cache exceeded reserved memory
  • IMSRT0083E Error allocating memory for ACB PCB SENFLD blocks REF1: %4 REF2: %5
  • IMSRT0084E ACB create/modify failure: Too many SENFLD statements More than 10,000 SENFLDs in this PSB
  • IMSRT0087E Unrecoverable System Software Abend <abend-number>
  • IMSRT0105E Database ACCESS error for DB:
  • IMSRT0121E DLI call failure - <return/reason code> JCLXM0000I * DATABASE ERROR AO *
  • IMSRT1003W CHKP ID=id duplicates an existing ID. Pausing 1 second.
  • IMSRT1012E MFIMS DATABASE SHARING MANAGER A database record is in use by %12%. Database: %8 Root Key: %50%
Parent topic: IMS Error Messages


IMSRT0000I <message text>

<message text> is a general informational message that indicates a possible problem.

Parent topic: IMS Run-time System Error Messages


IMSRT0039E ACB failure for %8. %60%

Parent topic: IMS Run-time System Error Messages


IMSRT0040E PSB Authorization failure for %8.

Parent topic: IMS Run-time System Error Messages


IMSRT0041E No ACEE available. Function %4 can't test authorization of %8

Parent topic: IMS Run-time System Error Messages


IMSRT0042E Error initializing MFIMS - IMS terminating. %12% not found or incorrect version

Parent topic: IMS Run-time System Error Messages


IMSRT0043E Error initializing MFIMS - IMS terminating. Error opening/reading IMSCONFG file. File Status: %6 Description: %40%

Parent topic: IMS Run-time System Error Messages


IMSRT0044E Error initializing MFIMS - IMS terminating. Error opening %6 files. File Status: %6 Description: %40%

Parent topic: IMS Run-time System Error Messages


IMSRT0045E Error initializing MFIMS - IMS terminating. Failure reason code: %4

Parent topic: IMS Run-time System Error Messages


IMSRT0052I The following POP-UP was suppressed during shutdown

Parent topic: IMS Run-time System Error Messages


IMSRT0053I The following POP-UP was suppressed by system request

Parent topic: IMS Run-time System Error Messages


IMSRT0054I Suppression resulted in automatic termination

Parent topic: IMS Run-time System Error Messages


IMSRT0055I End of message

Parent topic: IMS Run-time System Error Messages


IMSRT0056I OPTION VALUE MUST BE "C" OR "T"

Parent topic: IMS Run-time System Error Messages


IMSRT0057I OPTION VALUE MUST BE "Y" OR "N"

Parent topic: IMS Run-time System Error Messages


IMSRT0058I OPTION VALUE MUST BE "R" OR "T"

Parent topic: IMS Run-time System Error Messages


IMSRT0059I INVALID KEY PRESSED

Parent topic: IMS Run-time System Error Messages


IMSRT0060I ONLY 4 DIGITS ARE ALLOWED

Parent topic: IMS Run-time System Error Messages


IMSRT0061I LIMIT VALUE NOT NUMERIC

Parent topic: IMS Run-time System Error Messages


IMSRT0062I STATUS CODE MUST BE TWO BYTE VALUE OR BLANK

Parent topic: IMS Run-time System Error Messages


IMSRT0063I OPTION MUST BE "C", "T", OR "S"

Parent topic: IMS Run-time System Error Messages


IMSRT0064I SAVE OPTION ONLY AVAILABLE ON WINDOWS NT

Parent topic: IMS Run-time System Error Messages


IMSRT0065I USERID IS A REQUIRED FIELD

Parent topic: IMS Run-time System Error Messages


IMSRT0066I PASSWORD IS A REQUIRED FIELD

Parent topic: IMS Run-time System Error Messages


IMSRT0068I MFIMS SYSTEM WINDOW ERROR

Parent topic: IMS Run-time System Error Messages


IMSRT0069I CONTACT TECHNICAL SUPPORT

Parent topic: IMS Run-time System Error Messages


IMSRT0070I PRESS ENTER TO TERMINATE

Parent topic: IMS Run-time System Error Messages


IMSRT0080E Error allocating memory for ACB DBD field blocks REF1: %4 REF2: %5

Parent topic: IMS Run-time System Error Messages


IMSRT0081E ACB create/modify failure: Too many DBD fields Total DBD fields required for this PSB exceeds: %6

Parent topic: IMS Run-time System Error Messages


IMSRT0082E ACB create/modify failure: Caching SENSEG/SENFLD SENSEG/SENFLD cache exceeded reserved memory

Parent topic: IMS Run-time System Error Messages


IMSRT0083E Error allocating memory for ACB PCB SENFLD blocks REF1: %4 REF2: %5

Parent topic: IMS Run-time System Error Messages


IMSRT0084E ACB create/modify failure: Too many SENFLD statements More than 10,000 SENFLDs in this PSB

Parent topic: IMS Run-time System Error Messages


IMSRT0087E Unrecoverable System Software Abend <abend-number>

Parent topic: IMS Run-time System Error Messages


IMSRT0105E Database ACCESS error for DB:

Parent topic: IMS Run-time System Error Messages


IMSRT0121E DLI call failure - <return/reason code> JCLXM0000I * DATABASE ERROR AO *

Parent topic: IMS Run-time System Error Messages


IMSRT1003W CHKP ID=id duplicates an existing ID. Pausing 1 second.

Description:

The cited checkpoint call is delayed due to a duplicate checkpoint ID.

Parent topic: IMS Run-time System Error Messages


IMSRT1012E MFIMS DATABASE SHARING MANAGER A database record is in use by %12%. Database: %8 Root Key: %50%

Parent topic: IMS Run-time System Error Messages


MFS Error Messages

  • Messages MFSUT0401 to MFSUT0435
  • Messages MFSUT04A1 to MFSUT04A7
  • Messages MFSUT04E1 to MFSUT04E2
  • Messages MFSUT0801 to MFSUT0847
  • Messages MFSUT08A1 to MFSUT08A3
  • Messages MFSUT08P1 to MFSUT08P2
  • Messages MFSUT0L01 to MFSUT0L29
  • Messages MFSUT0L91 to MFSUT0L99
  • Messages MFSUT0LA1 to MFSUT0LA3
  • Messages MFSUT0LP1 to MFSUT0LP3
  • Messages MFSUT0U01 to MFSUT0U35
  • Messages MFSUT0W01 to MFSUT0W23
  • Messages MFSUT0WA1 to MFSUT0WA9
  • Messages MFSUT0WE1 to MFSUT0WE2
  • Messages MFSUT0WF1 to MFSUT0WF2
  • Messages MFSUT0WP1 to MFSUT0WP3
Parent topic: IMS Error Messages


Messages MFSUT0401 to MFSUT0435

  • MFSUT0401W MSG %8 has invalid OPT=%1, defaulting to OPT=1
  • MFSUT0402W Cannot specify FILL on input MSG, FILL ignored
  • MFSUT0403W Cannot specify PAGE on input MSG, PAGE ignored
  • MFSUT0405W MFLD LTH operand missing, defaulting to LTH=0001. MFLD: %50%
  • MFSUT0406W EXIT ignored, only input MFLDs can use field exits. MFLD: %50%
  • MFSUT0407W MFLD literals cannot specify ATTR=YES, ATTR=NO assumed. MFLD literal: %45%
  • MFSUT0408W EXIT ignored, MFLD literals cannot use field exits. MFLD literal: %45%
  • MFSUT0409W ATTR=YES only valid when MFLD names DFLD, ATTR=NO assumed
  • MFSUT0410W MSG(%8), SEG GRAPHIC not YES or NO, assumed YES
  • MFSUT0411W MSG(%8), EXIT ignored, only input messages can use segment exits
  • MFSUT0412W MOD LPAGE's COND operand missing, assuming last LPAGE of set
  • MFSUT0413W MSG(%8), MSGEND statement missing, assumed present
  • MFSUT0414W No STACK is on to issue STACK OFF
  • MFSUT0415W MFLD's DFLD name in DO truncated to 6 characters
  • MFSUT0416W Initial cursor position defaulting to row 1, column 2
  • MFSUT0417W LABEL ignored, labeled DFLDs should not have PASSWORD
  • MFSUT0418W DFLD label in DO truncated to 6 characters
  • MFSUT0419W Recommended END statement missing, assumed present
  • MFSUT0420W ENDDO statement missing, assumed present
  • MFSUT0421W FMTEND statement missing, assumed present
  • MFSUT0422W MFLD JUST operand invalid with system literal %8. JUST operand ignored for MFLD %19
  • MFSUT0423W MFLD ATTR operand invalid with system literal %8. ATTR operand ignored for MFLD %19
  • MFSUT0424W MFLD LTH operand invalid with system literal %8. LTH operand ignored for MFLD %19
  • MFSUT0425W OPCTL operand ignored, not valid with literal DFLDs
  • MFSUT0426W MOD(%8), LPAGE(%3%) contains no MFLDs, this MOD/LPAGE bypassed
  • MFSUT0427W MOD(%8), MID(%8), DPAGE(%8), could not find MID for MOD/LPAGE selected or MID contains no MFLDs or all MIDs specified LPAGE and no SOR stated this DPAGE
  • MFSUT0428W FMT name %8 greater than 6 characters, truncated to 6 possibly causing duplicates
  • MFSUT0429W EGCS "G" literal missing an SO or SI character. Literal assumed to contain valid SO/SI pair. Card: %50%
  • MFSUT0430W EGCS "G" literal contains odd number of bytes, literal accepted as specified. Card: %50%
  • MFSUT0431W Invalid DFLD ATTR value "%8" ignored
  • MFSUT0432W SYSMSG parameter not valid
  • MFSUT0433W Message %8 has no format or is assigned to another format outside this MFS source
  • MFSUT0434W Format %6 has no messages
  • MFSUT0435W Device type of DPM not supported. Device ignored.
Parent topic: MFS Error Messages


MFSUT0401W MSG %8 has invalid OPT=%1, defaulting to OPT=1

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0402W Cannot specify FILL on input MSG, FILL ignored

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0403W Cannot specify PAGE on input MSG, PAGE ignored

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0405W MFLD LTH operand missing, defaulting to LTH=0001. MFLD: %50%

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0406W EXIT ignored, only input MFLDs can use field exits. MFLD: %50%

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0407W MFLD literals cannot specify ATTR=YES, ATTR=NO assumed. MFLD literal: %45%

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0408W EXIT ignored, MFLD literals cannot use field exits. MFLD literal: %45%

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0409W ATTR=YES only valid when MFLD names DFLD, ATTR=NO assumed

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0410W MSG(%8), SEG GRAPHIC not YES or NO, assumed YES

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0411W MSG(%8), EXIT ignored, only input messages can use segment exits

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0412W MOD LPAGE's COND operand missing, assuming last LPAGE of set

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0413W MSG(%8), MSGEND statement missing, assumed present

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0414W No STACK is on to issue STACK OFF

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0415W MFLD's DFLD name in DO truncated to 6 characters

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0416W Initial cursor position defaulting to row 1, column 2

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0417W LABEL ignored, labeled DFLDs should not have PASSWORD

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0418W DFLD label in DO truncated to 6 characters

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0419W Recommended END statement missing, assumed present

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0420W ENDDO statement missing, assumed present

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0421W FMTEND statement missing, assumed present

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0422W MFLD JUST operand invalid with system literal %8. JUST operand ignored for MFLD %19

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0423W MFLD ATTR operand invalid with system literal %8. ATTR operand ignored for MFLD %19

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0424W MFLD LTH operand invalid with system literal %8. LTH operand ignored for MFLD %19

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0425W OPCTL operand ignored, not valid with literal DFLDs

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0426W MOD(%8), LPAGE(%3%) contains no MFLDs, this MOD/LPAGE bypassed

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0427W MOD(%8), MID(%8), DPAGE(%8), could not find MID for MOD/LPAGE selected or MID contains no MFLDs or all MIDs specified LPAGE and no SOR stated this DPAGE

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0428W FMT name %8 greater than 6 characters, truncated to 6 possibly causing duplicates

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0429W EGCS "G" literal missing an SO or SI character. Literal assumed to contain valid SO/SI pair. Card: %50%

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0430W EGCS "G" literal contains odd number of bytes, literal accepted as specified. Card: %50%

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0431W Invalid DFLD ATTR value "%8" ignored

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0432W SYSMSG parameter not valid

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0433W Message %8 has no format or is assigned to another format outside this MFS source

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0434W Format %6 has no messages

Parent topic: Messages MFSUT0401 to MFSUT0435


MFSUT0435W Device type of DPM not supported. Device ignored.

Parent topic: Messages MFSUT0401 to MFSUT0435


Messages MFSUT04A1 to MFSUT04A7

  • MFSUT04A1W Continuation cannot start in column 1
  • MFSUT04A2W Expected "=", found "(", "=" is assumed
  • MFSUT04A3W Continuation expected, none received
  • MFSUT04A4W Invalid character following final quote "%1"
  • MFSUT04A5W %8 has a non-numeric value "%8", assumed zero
  • MFSUT04A6W Duplicate keyword %8 specified, last one used
  • MFSUT04A7W Expected "," found ")".
Parent topic: MFS Error Messages


MFSUT04A1W Continuation cannot start in column 1

Parent topic: Messages MFSUT04A1 to MFSUT04A7


MFSUT04A2W Expected "=", found "(", "=" is assumed

Parent topic: Messages MFSUT04A1 to MFSUT04A7


MFSUT04A3W Continuation expected, none received

Parent topic: Messages MFSUT04A1 to MFSUT04A7


MFSUT04A4W Invalid character following final quote "%1"

Parent topic: Messages MFSUT04A1 to MFSUT04A7


MFSUT04A5W %8 has a non-numeric value "%8", assumed zero

Parent topic: Messages MFSUT04A1 to MFSUT04A7


MFSUT04A6W Duplicate keyword %8 specified, last one used

Parent topic: Messages MFSUT04A1 to MFSUT04A7


MFSUT04A7W Expected "," found ")".

Parent topic: Messages MFSUT04A1 to MFSUT04A7


Messages MFSUT04E1 to MFSUT04E2

  • MFSUT04E1W EQU %8 error, keyword already has data
  • MFSUT04E2W EQU %8 error, data already has a keyword
Parent topic: MFS Error Messages


MFSUT04E1W EQU %8 error, keyword already has data

Parent topic: Messages MFSUT04E1 to MFSUT04E2


MFSUT04E2W EQU %8 error, data already has a keyword

Parent topic: Messages MFSUT04E1 to MFSUT04E2


Messages MFSUT0801 to MFSUT0847

  • MFSUT0801E MSG(%8) has TYPE=%6, must be INPUT or OUTPUT
  • MFSUT0802E MSG(%8) missing required SOR operand
  • MFSUT0803E MFLD indicates no DFLD, literal or LTH
  • MFSUT0804E MFLD JUST must be R or L
  • MFSUT0805E MFLD EXIT number %5% exceeds maximum value of 127. MFLD: %50%
  • MFSUT0806E MFLD EXIT vector %5% exceeds maximum value of 255. MFLD: %50%
  • MFSUT0807E MSG(%8), SEG EXIT number %5% exceeds maximum of 127
  • MFSUT0808E MSG(%8), SEG EXIT vector %5% exceeds maximum of 255
  • MFSUT0809E MSG(%8), LPAGE missing required SOR operand
  • MFSUT0810E MSG(%8), COND operand has %3% parameters, requires 3
  • MFSUT0811E MSG(%8), LPAGE COND operand missing, only last LPAGE in MOD may omit COND
  • MFSUT0812E LPAGE COND label %8 not an MFLD label in MOD %8
  • MFSUT0813E DO COUNT is not numeric
  • MFSUT0814E DO/ENDDO pair mismatch
  • MFSUT0815E First STACK parameter must be blank, ON, or OFF
  • MFSUT0816E Cannot start STACK before ending previous STACK
  • MFSUT0817E UNSTACK cannot appear within a STACK
  • MFSUT0818E UNSTACK requested unknown stack name %8
  • MFSUT0819E COPY statement missing required NAME parameter
  • MFSUT0820E COPY member %8 not found
  • MFSUT0821E DPAGE CURSOR column specification "%8" not numeric. Valid forms are CURSOR=name or CURSOR=(rrr,ccc,name)
  • MFSUT0822E DFLD %8 not preceded by DEV statement
  • MFSUT0823E DFLD literals cannot have a label starting in column 1
  • MFSUT0824E DFLD literals must be bound by single quotes
  • MFSUT0825E DFLD requires non-zero POS row and column
  • MFSUT0826E 3270 DFLD cannot start in row 1, column 1
  • MFSUT0827E DFLD %8, POS column value %3% exceeds DEV width value %4%
  • MFSUT0828E DFLD %8, POS column value %4% exceeds 3270 model 1 maximum value of 40
  • MFSUT0829E DFLD %8, POS column value %4% exceeds 3270 models 2,3,4 maximum value of 80
  • MFSUT0830E DFLD %8, POS column value %4% exceeds 3270 model 5 maximum value of 132
  • MFSUT0831E DFLD requires a literal, PASSWORD, or LTH
  • MFSUT0832E Duplicate DFLD label %8. Labels must be unique within DPAGE and physical page
  • MFSUT0833E FMT %6 contains no DFLDs. Verify that STACK and MODEL directives are properly set, or correct the format
  • MFSUT0834E Attribute for DFLD at row %2, col %3% overlaps prior field
  • MFSUT0835E DFLD at row %2, col %3% overlaps prior field
  • MFSUT0836E FMT %6, DPAGE %8, PPAGE %4 contains no DFLDs
  • MFSUT0837E DFLD %8 row value %4% exceeds 3270 model %1% maximum value of %2%
  • MFSUT0838E LPAGE COND relational operator "%2" invalid
  • MFSUT0839E DFLD %8 not preceded by DEV statement
  • MFSUT0840E MOD %8, FMT %8, DPAGE %8, could not find FMT or DPAGE for MOD/LPAGE selected or FMT or DPAGE contains no DFLD statements
  • MFSUT0841E MFLD LTH %5% is not larger than attribute bytes %5%. MFLD: %50%
  • MFSUT0842E DFLD PASSWORD cannot have a label starting in column 1
  • MFSUT0843E Required label missing for MSG statement
  • MFSUT0844E MFLD ATTR value "%14" not YES, NO, or number of extended attributes
  • MFSUT0845E DFLD ATTR value "%14" not YES, NO, or number of extended attributes
  • MFSUT0846E PAGE LENGTH specification "%8" not numeric.
    Enter a short description of your topic here (optional).
  • MFSUT0847E Device Page Option value "%14" not SPACE, EJECT, FLOAT, DEFN
Parent topic: MFS Error Messages


MFSUT0801E MSG(%8) has TYPE=%6, must be INPUT or OUTPUT

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0802E MSG(%8) missing required SOR operand

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0803E MFLD indicates no DFLD, literal or LTH

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0804E MFLD JUST must be R or L

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0805E MFLD EXIT number %5% exceeds maximum value of 127. MFLD: %50%

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0806E MFLD EXIT vector %5% exceeds maximum value of 255. MFLD: %50%

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0807E MSG(%8), SEG EXIT number %5% exceeds maximum of 127

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0808E MSG(%8), SEG EXIT vector %5% exceeds maximum of 255

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0809E MSG(%8), LPAGE missing required SOR operand

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0810E MSG(%8), COND operand has %3% parameters, requires 3

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0811E MSG(%8), LPAGE COND operand missing, only last LPAGE in MOD may omit COND

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0812E LPAGE COND label %8 not an MFLD label in MOD %8

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0813E DO COUNT is not numeric

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0814E DO/ENDDO pair mismatch

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0815E First STACK parameter must be blank, ON, or OFF

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0816E Cannot start STACK before ending previous STACK

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0817E UNSTACK cannot appear within a STACK

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0818E UNSTACK requested unknown stack name %8

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0819E COPY statement missing required NAME parameter

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0820E COPY member %8 not found

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0821E DPAGE CURSOR column specification "%8" not numeric. Valid forms are CURSOR=name or CURSOR=(rrr,ccc,name)

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0822E DFLD %8 not preceded by DEV statement

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0823E DFLD literals cannot have a label starting in column 1

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0824E DFLD literals must be bound by single quotes

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0825E DFLD requires non-zero POS row and column

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0826E 3270 DFLD cannot start in row 1, column 1

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0827E DFLD %8, POS column value %3% exceeds DEV width value %4%

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0828E DFLD %8, POS column value %4% exceeds 3270 model 1 maximum value of 40

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0829E DFLD %8, POS column value %4% exceeds 3270 models 2,3,4 maximum value of 80

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0830E DFLD %8, POS column value %4% exceeds 3270 model 5 maximum value of 132

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0831E DFLD requires a literal, PASSWORD, or LTH

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0832E Duplicate DFLD label %8. Labels must be unique within DPAGE and physical page

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0833E FMT %6 contains no DFLDs. Verify that STACK and MODEL directives are properly set, or correct the format

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0834E Attribute for DFLD at row %2, col %3% overlaps prior field

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0835E DFLD at row %2, col %3% overlaps prior field

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0836E FMT %6, DPAGE %8, PPAGE %4 contains no DFLDs

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0837E DFLD %8 row value %4% exceeds 3270 model %1% maximum value of %2%

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0838E LPAGE COND relational operator "%2" invalid

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0839E DFLD %8 not preceded by DEV statement

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0840E MOD %8, FMT %8, DPAGE %8, could not find FMT or DPAGE for MOD/LPAGE selected or FMT or DPAGE contains no DFLD statements

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0841E MFLD LTH %5% is not larger than attribute bytes %5%. MFLD: %50%

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0842E DFLD PASSWORD cannot have a label starting in column 1

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0843E Required label missing for MSG statement

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0844E MFLD ATTR value "%14" not YES, NO, or number of extended attributes

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0845E DFLD ATTR value "%14" not YES, NO, or number of extended attributes

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0846E PAGE LENGTH specification "%8" not numeric.

This is the start of your topic.

Parent topic: Messages MFSUT0801 to MFSUT0847


MFSUT0847E Device Page Option value "%14" not SPACE, EJECT, FLOAT, DEFN

Parent topic: Messages MFSUT0801 to MFSUT0847


Messages MFSUT08A1 to MFSUT08A3

  • MFSUT08A1E Unmatched parentheses
  • MFSUT08A2E Unmatched quotes
  • MFSUT08A3E Positional operand cannot follow keyword operand: %60%
Parent topic: MFS Error Messages


MFSUT08A1E Unmatched parentheses

Parent topic: Messages MFSUT08A1 to MFSUT08A3


MFSUT08A2E Unmatched quotes

Parent topic: Messages MFSUT08A1 to MFSUT08A3


MFSUT08A3E Positional operand cannot follow keyword operand: %60%

Parent topic: Messages MFSUT08A1 to MFSUT08A3


Messages MFSUT08P1 to MFSUT08P2

  • MFSUT08P1E Number of list operands exceeds MFIMS maximum of %3%
  • MFSUT08P2E Macro %8, keyword %8 has unmatched parentheses
Parent topic: MFS Error Messages


MFSUT08P1E Number of list operands exceeds MFIMS maximum of %3%

Parent topic: Messages MFSUT08P1 to MFSUT08P2


MFSUT08P2E Macro %8, keyword %8 has unmatched parentheses

Parent topic: Messages MFSUT08P1 to MFSUT08P2


Messages MFSUT0L01 to MFSUT0L29

  • MFSUT0L01E Exceeded MFIMS limit of %4% MFLD statements which name a DFLD in any one MSG/LPAGE
  • MFSUT0L02E Maximum MFIMS MFLD LTH is 4095 bytes
  • MFSUT0L04E Maximum number of extended ATTR bytes in MFIMS is 10. MFLD: %50%
  • MFSUT0L05E Exceeded maximum MFIMS MFLD literal length of 94, including outermost quotes and imbedded single quotes
  • MFSUT0L07E Maximum MFIMS DFLD LTH is 4095 bytes
  • MFSUT0L08E Exceeded MFIMS limit of %4% labeled DFLD statements per DPAGE
  • MFSUT0L09E MFIMS maximum DFLD literal length is %3% bytes
  • MFSUT0L10E MFS preprocessor requested MFSGEN termination due to:
  • MFSUT0L11E MFS preprocessor error, invalid return code: %5%
  • MFSUT0L12E MFS preprocessor not found. Preprocessor: %60%
  • MFSUT0L13E MFIMS limit of %3% physical pages per device page exceeded
  • MFSUT0L14E LPAGE COND literal value length %3% exceeds MFIMS limit of 42 bytes. Literal: %40%
  • MFSUT0L15E No FMT statements found in source input, MFIMS requires MID, MOD and FMT to be in same source input
  • MFSUT0L16E PF key length %4% exceeds MFIMS maximum of %3%
  • MFSUT0L17E The resultant control block for this format is %6% bytes and exceeds the MFIMS limit of %5%
  • MFSUT0L18E Exceeded MFIMS DFLD literal pool limit of %5%
  • MFSUT0L19E Exceeded MFIMS MOD literal pool limit of %5%
  • MFSUT0L20E Exceeded MFIMS MID default literal pool limit of %5%
  • MFSUT0L21E Exceeded MFIMS MID static literal pool limit of %5%
  • MFSUT0L22E Exceeded MFIMS limit of %3% SEG statements per MSG
  • MFSUT0L23E Exceeded MFIMS MFLD temporary table limit of %5% and possibly exceeded MFIMS limit of 500 MFLDs per SEG
  • MFSUT0L24E Exceeded MFIMS printer DPAGE literal pool limit of %5%
  • MFSUT0L25E Exceeded internal "DFLD" literal work buffer. Maximum work size is 160 bytes.
  • MFSUT0L26E Exceeded maximum PASSWORD segment length of 8 bytes.
  • MFSUT0L27E PASSWORD segment must come before any other input segments.
  • MFSUT0L28E PASSWORD segment valid only for input messages.
  • MFSUT0L29E PASSWORD segment ignored for option 3 input messages.
Parent topic: MFS Error Messages


MFSUT0L01E Exceeded MFIMS limit of %4% MFLD statements which name a DFLD in any one MSG/LPAGE

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L02E Maximum MFIMS MFLD LTH is 4095 bytes

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L04E Maximum number of extended ATTR bytes in MFIMS is 10. MFLD: %50%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L05E Exceeded maximum MFIMS MFLD literal length of 94, including outermost quotes and imbedded single quotes

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L07E Maximum MFIMS DFLD LTH is 4095 bytes

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L08E Exceeded MFIMS limit of %4% labeled DFLD statements per DPAGE

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L09E MFIMS maximum DFLD literal length is %3% bytes

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L10E MFS preprocessor requested MFSGEN termination due to:

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L11E MFS preprocessor error, invalid return code: %5%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L12E MFS preprocessor not found. Preprocessor: %60%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L13E MFIMS limit of %3% physical pages per device page exceeded

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L14E LPAGE COND literal value length %3% exceeds MFIMS limit of 42 bytes. Literal: %40%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L15E No FMT statements found in source input, MFIMS requires MID, MOD and FMT to be in same source input

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L16E PF key length %4% exceeds MFIMS maximum of %3%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L17E The resultant control block for this format is %6% bytes and exceeds the MFIMS limit of %5%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L18E Exceeded MFIMS DFLD literal pool limit of %5%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L19E Exceeded MFIMS MOD literal pool limit of %5%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L20E Exceeded MFIMS MID default literal pool limit of %5%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L21E Exceeded MFIMS MID static literal pool limit of %5%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L22E Exceeded MFIMS limit of %3% SEG statements per MSG

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L23E Exceeded MFIMS MFLD temporary table limit of %5% and possibly exceeded MFIMS limit of 500 MFLDs per SEG

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L24E Exceeded MFIMS printer DPAGE literal pool limit of %5%

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L25E Exceeded internal "DFLD" literal work buffer. Maximum work size is 160 bytes.

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L26E Exceeded maximum PASSWORD segment length of 8 bytes.

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L27E PASSWORD segment must come before any other input segments.

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L28E PASSWORD segment valid only for input messages.

Parent topic: Messages MFSUT0L01 to MFSUT0L29


MFSUT0L29E PASSWORD segment ignored for option 3 input messages.

Parent topic: Messages MFSUT0L01 to MFSUT0L29


Messages MFSUT0L91 to MFSUT0L99

  • MFSUT0L91E %5% DFLD records exceeds MFIMS maximum of %4% allowed
  • MFSUT0L92E %5% MID records exceeds MFIMS maximum of %4% allowed
  • MFSUT0L93E %5% MOD records exceeds MFIMS maximum of %4% allowed
  • MFSUT0L99E Valid software license not present. Reason code (%4%)
Parent topic: MFS Error Messages


MFSUT0L91E %5% DFLD records exceeds MFIMS maximum of %4% allowed

Parent topic: Messages MFSUT0L91 to MFSUT0L99


MFSUT0L92E %5% MID records exceeds MFIMS maximum of %4% allowed

Parent topic: Messages MFSUT0L91 to MFSUT0L99


MFSUT0L93E %5% MOD records exceeds MFIMS maximum of %4% allowed

Parent topic: Messages MFSUT0L91 to MFSUT0L99


MFSUT0L99E Valid software license not present. Reason code (%4%)

Parent topic: Messages MFSUT0L91 to MFSUT0L99


Messages MFSUT0LA1 to MFSUT0LA3

  • MFSUT0LA1E Positional operand cannot follow keyword operand: %60% MFIMS does not perform MFSGEN syntax error recovery
  • MFSUT0LA2E Length of operand exceeds MFIMS maximum of %4 bytes
  • MFSUT0LA3E Unexpected parsing error, report to Technical Support.
Parent topic: MFS Error Messages


MFSUT0LA1E Positional operand cannot follow keyword operand: %60% MFIMS does not perform MFSGEN syntax error recovery

Parent topic: Messages MFSUT0LA1 to MFSUT0LA3


MFSUT0LA2E Length of operand exceeds MFIMS maximum of %4 bytes

Parent topic: Messages MFSUT0LA1 to MFSUT0LA3


MFSUT0LA3E Unexpected parsing error, report to Technical Support.

Parent topic: Messages MFSUT0LA1 to MFSUT0LA3


Messages MFSUT0LP1 to MFSUT0LP3

  • MFSUT0LP1E Length of operand exceeds MFIMS size of %4% bytes
  • MFSUT0LP2E Number of list operands exceeds MFIMS maximum of %3%
  • MFSUT0LP3E Length of list exceeds MFIMS maximum of %4% bytes
Parent topic: MFS Error Messages


MFSUT0LP1E Length of operand exceeds MFIMS size of %4% bytes

Parent topic: Messages MFSUT0LP1 to MFSUT0LP3


MFSUT0LP2E Number of list operands exceeds MFIMS maximum of %3%

Parent topic: Messages MFSUT0LP1 to MFSUT0LP3


MFSUT0LP3E Length of list exceeds MFIMS maximum of %4% bytes

Parent topic: Messages MFSUT0LP1 to MFSUT0LP3


Messages MFSUT0U01 to MFSUT0U35

  • MFSUT0U01U File status %A5 opening file %C60. %B40%
  • MFSUT0U02U File status %A5 issuing close for file %C60. %B40%
  • MFSUT0U04U File status %5 issuing set/date for MFSPEF file. %40%
  • MFSUT0U05U File status %5 reading MFSGEN LPAGE control record. %40%
  • MFSUT0U06U File status %5 updating MFSGEN LPAGE control record. %40%
  • MFSUT0U07U File status %A5 writing %C8 to IMSVSFMT file. %B40%
  • MFSUT0U08U File status %5 writing MOD LPAGE to MFSPEF file. %40%
  • MFSUT0U09U File status %5 issuing delete for MFSPEF file. %40%
  • MFSUT0U10U File status %5 chaining LPAGE for MOD in MFSPEF file. %40%
  • MFSUT0U11U File status %5 issuing write for MFSPEF file. %40%
  • MFSUT0U12U File status %5 repositioning MOD LPAGE in MFSPEF file. %40%
  • MFSUT0U13U File status %5 writing MOD PPAGE to MFSPEF file. %40%
  • MFSUT0U14U File status %A5 issuing write for file %C60 %B40%
  • MFSUT0U15U File status %A5 issuing delete for file %C60 %B40%
  • MFSUT0U16U File status %5 reading MFSGEN PPAGE control record. %40%
  • MFSUT0U17U File status %5 updating MFSGEN PPAGE control record. %40%
  • MFSUT0U18U File status %5 chaining PPAGE for MOD in MFSPEF file. %40%
  • MFSUT0U19U File status %5 repositioning MOD PPAGE in MFSPEF file. %40%
  • MFSUT0U20U File status %A5 issuing create for file %C60 %40%
  • MFSUT0U35U File not found %C60
Parent topic: MFS Error Messages


MFSUT0U01U File status %A5 opening file %C60. %B40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U02U File status %A5 issuing close for file %C60. %B40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U04U File status %5 issuing set/date for MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U05U File status %5 reading MFSGEN LPAGE control record. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U06U File status %5 updating MFSGEN LPAGE control record. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U07U File status %A5 writing %C8 to IMSVSFMT file. %B40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U08U File status %5 writing MOD LPAGE to MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U09U File status %5 issuing delete for MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U10U File status %5 chaining LPAGE for MOD in MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U11U File status %5 issuing write for MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U12U File status %5 repositioning MOD LPAGE in MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U13U File status %5 writing MOD PPAGE to MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U14U File status %A5 issuing write for file %C60 %B40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U15U File status %A5 issuing delete for file %C60 %B40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U16U File status %5 reading MFSGEN PPAGE control record. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U17U File status %5 updating MFSGEN PPAGE control record. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U18U File status %5 chaining PPAGE for MOD in MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U19U File status %5 repositioning MOD PPAGE in MFSPEF file. %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U20U File status %A5 issuing create for file %C60 %40%

Parent topic: Messages MFSUT0U01 to MFSUT0U35


MFSUT0U35U File not found %C60

Parent topic: Messages MFSUT0U01 to MFSUT0U35


Messages MFSUT0W01 to MFSUT0W23

  • MFSUT0W01W MFLD LTHs of form LTH=(pp,nn) are not supported by MFIMS. The starting position is assumed to be 1 (pp=1). MFLD: %50%
  • MFSUT0W03W STACK processing disabled by use of STACKOFF directive
  • MFSUT0W04W STACK processing disabled by use of STACKAUTO directive. STACK follows DEV, assumed to be for multi-devices
  • MFSUT0W05W Exceeded maximum of %4% STACK statements suppressed by STACKAUTO directive. All subsequent UNSTACKs ignored
  • MFSUT0W06W UNSTACK suppressed by STACKAUTO directive
  • MFSUT0W07W Only two levels of nested copy statements are supported by MFIMS. Further nested COPYs ignored. Card: %50%
  • MFSUT0W08W Removing MFLD for PASSWORD, not supported by MFIMS
  • MFSUT0W09W Only ALPHA statements which contain the lower case characters a through z are supported by MFIMS
  • MFSUT0W10W DEV macro TYPE operand missing, only 3270 devices supported by MFIMS
  • MFSUT0W11W MFIMS statement continuation overflow, extras ignored. Maximum number of lines per statement is %2%
  • MFSUT0W12W %8 macro or statement not supported by MFIMS, ignored
  • MFSUT0W13W MFLD %8, FILL=NULL changed to FILL=C' '. MFIMS only supports NULL for PF key field with physical paging
  • MFSUT0W14W MID, MFLD %8 not defined in DFLDs so will always contain default literal or FILL value
  • MFSUT0W15W MID, MFLD %8 not defined in DFLDs so will always be compressed from MID due to FILL=NULL
  • MFSUT0W16W MOD, MFLD %8 not defined in DFLDs or listed more than once in MOD. Processed as MFLD LTH=%4%
  • MFSUT0W17W DFLD PASSWORD not supported by MFIMS, ignored
  • MFSUT0W19W Unknown statement "%8" ignored, unsupported by MFIMS
  • MFSUT0W20W Unknown keyword "%8" for "%8" ignored, unsupported by MFIMS
  • MFSUT0W21W ALPHA statement enables entry of lower case characters when the input message SEG statement specifies GRAPHIC=NO
  • MFSUT0W22W Out-of-place DFLD statement %8 ignored
  • MFSUT0W23W NXT= references %8 - undefined MID or not in this FMT
Parent topic: MFS Error Messages


MFSUT0W01W MFLD LTHs of form LTH=(pp,nn) are not supported by MFIMS. The starting position is assumed to be 1 (pp=1). MFLD: %50%

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W03W STACK processing disabled by use of STACKOFF directive

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W04W STACK processing disabled by use of STACKAUTO directive. STACK follows DEV, assumed to be for multi-devices

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W05W Exceeded maximum of %4% STACK statements suppressed by STACKAUTO directive. All subsequent UNSTACKs ignored

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W06W UNSTACK suppressed by STACKAUTO directive

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W07W Only two levels of nested copy statements are supported by MFIMS. Further nested COPYs ignored. Card: %50%

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W08W Removing MFLD for PASSWORD, not supported by MFIMS

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W09W Only ALPHA statements which contain the lower case characters a through z are supported by MFIMS

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W10W DEV macro TYPE operand missing, only 3270 devices supported by MFIMS

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W11W MFIMS statement continuation overflow, extras ignored. Maximum number of lines per statement is %2%

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W12W %8 macro or statement not supported by MFIMS, ignored

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W13W MFLD %8, FILL=NULL changed to FILL=C' '. MFIMS only supports NULL for PF key field with physical paging

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W14W MID, MFLD %8 not defined in DFLDs so will always contain default literal or FILL value

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W15W MID, MFLD %8 not defined in DFLDs so will always be compressed from MID due to FILL=NULL

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W16W MOD, MFLD %8 not defined in DFLDs or listed more than once in MOD. Processed as MFLD LTH=%4%

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W17W DFLD PASSWORD not supported by MFIMS, ignored

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W19W Unknown statement "%8" ignored, unsupported by MFIMS

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W20W Unknown keyword "%8" for "%8" ignored, unsupported by MFIMS

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W21W ALPHA statement enables entry of lower case characters when the input message SEG statement specifies GRAPHIC=NO

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W22W Out-of-place DFLD statement %8 ignored

Parent topic: Messages MFSUT0W01 to MFSUT0W23


MFSUT0W23W NXT= references %8 - undefined MID or not in this FMT

Parent topic: Messages MFSUT0W01 to MFSUT0W23


Messages MFSUT0WA1 to MFSUT0WA9

  • MFSUT0WA1W BLANK line not allowed, MFIMS ignores blank lines
  • MFSUT0WA2W Exceeded MFIMS maximum number of operands, extras ignored
  • MFSUT0WA3W Columns 1-15 non-blank on continuation, MFIMS assumes blank
  • MFSUT0WA4W LABEL exceeds 8 bytes, MFIMS truncated to 8
  • MFSUT0WA5W Statement type must be on 1st line, ignored
  • MFSUT0WA6W %8 and other macro control statements not supported by MFIMS. This and subsequent control statements ignored
  • MFSUT0WA7W Column 16 on continuation was blank, MFIMS ignoring line
  • MFSUT0WA8W Missing comma for continuation, MFIMS assumed present
  • MFSUT0WA9W Invalid value "%8" - MFIMS ignored keyword and value
Parent topic: MFS Error Messages


MFSUT0WA1W BLANK line not allowed, MFIMS ignores blank lines

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA2W Exceeded MFIMS maximum number of operands, extras ignored

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA3W Columns 1-15 non-blank on continuation, MFIMS assumes blank

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA4W LABEL exceeds 8 bytes, MFIMS truncated to 8

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA5W Statement type must be on 1st line, ignored

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA6W %8 and other macro control statements not supported by MFIMS. This and subsequent control statements ignored

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA7W Column 16 on continuation was blank, MFIMS ignoring line

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA8W Missing comma for continuation, MFIMS assumed present

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


MFSUT0WA9W Invalid value "%8" - MFIMS ignored keyword and value

Parent topic: Messages MFSUT0WA1 to MFSUT0WA9


Messages MFSUT0WE1 to MFSUT0WE2

  • MFSUT0WE1W MFIMS EQU limit of %4 exceeded, extras ignored
  • MFSUT0WE2W EQU %8 contains unbalanced quotes. Maximum MFIMS EQU length is %4
Parent topic: MFS Error Messages


MFSUT0WE1W MFIMS EQU limit of %4 exceeded, extras ignored

Parent topic: Messages MFSUT0WE1 to MFSUT0WE2


MFSUT0WE2W EQU %8 contains unbalanced quotes. Maximum MFIMS EQU length is %4

Parent topic: Messages MFSUT0WE1 to MFSUT0WE2


Messages MFSUT0WF1 to MFSUT0WF2

  • MFSUT0WF1W In-line CSECT or DSECT is not supported by MFIMS. Ignoring all statements until END statement
  • MFSUT0WF2W In-line macro definitions not supported by MFIMS. Ignoring all statements until MEND statement
Parent topic: MFS Error Messages


MFSUT0WF1W In-line CSECT or DSECT is not supported by MFIMS. Ignoring all statements until END statement

Parent topic: Messages MFSUT0WF1 to MFSUT0WF2


MFSUT0WF2W In-line macro definitions not supported by MFIMS. Ignoring all statements until MEND statement

Parent topic: Messages MFSUT0WF1 to MFSUT0WF2


Messages MFSUT0WP1 to MFSUT0WP3

  • MFSUT0WP1W MFIMS maximum of 24 PF Keys exceeded, extras ignored
  • MFSUT0WP2W MFIMS supports a maximum of %2% data capture exit routines per segment, first %2% routines accepted.
  • MFSUT0WP3W MFIMS maximum number of %3% default cursor positions exceeded. Remaining physical pages defaulting to (1,2)
Parent topic: MFS Error Messages


MFSUT0WP1W MFIMS maximum of 24 PF Keys exceeded, extras ignored

Parent topic: Messages MFSUT0WP1 to MFSUT0WP3


MFSUT0WP2W MFIMS supports a maximum of %2% data capture exit routines per segment, first %2% routines accepted.

Parent topic: Messages MFSUT0WP1 to MFSUT0WP3


MFSUT0WP3W MFIMS maximum number of %3% default cursor positions exceeded. Remaining physical pages defaulting to (1,2)

Parent topic: Messages MFSUT0WP1 to MFSUT0WP3


PSB Error Messages

  • Messages PSBUT0401 to PSBUT0453
  • Messages PSBUT04A1 to PSBUT04A6
  • Messages PSBUT04E1 to PSBUT04E2
  • Messages PSBUT0801 to PSBUT0873
  • Messages PSBUT08A1 to PSBUT08A3
  • Messages PSBUT08P1 to PSBUT08P2
  • Messages PSBUT0L01 to PSBUT0L99
  • Messages PSBUT0LA1 to PSBUT0LA3
  • Messages PSBUT0LP1 to PSBUT0LP3
  • Messages PSBUT0U01 to PSBUT0U58
  • Messages PSBUT0W01 to PSBUT0W55
  • Messages PSBUT0WA1 to PSBUT0WA9
  • Messages PSBUT0WE1 to PSBUT0WE2
  • Messages PSBUT0WF1 to PSBUT0WF2
Parent topic: IMS Error Messages


Messages PSBUT0401 to PSBUT0453

  • PSBUT0401W More than one PSBGEN macro, all but the first ignored
  • PSBUT0402W PCB(%3%) %8, TYPE=%8 invalid, assumed TYPE=DB
  • PSBUT0403W Invalid PCB PROCOPT "%6", assumed PROCOPT "%4"
  • PSBUT0404W PCB(%3%) %8, SENSEG %8 PROCOPT operand ignored. SENSEG PROCOPT must be omitted when PCB PROCOPT is %4
  • PSBUT0405W Unknown keyword %8 for %8 ignored
  • PSBUT0406 PCB #%3% %8, SENSEG %8 PROCOPT=%4 invalid.
  • PSBUT0407W PCBNAME or label %8 is not unique. This parameter has been ignored for PCB #%3% in PSB %8
  • PSBUT0451W PCB(%3%) %8, an I/O PCB will not be created when this PSB is used in a CICS program or an IMS program defined as a type DLI
  • PSBUT0452W PCB(%3%) %8, insert calls not allowed to INDEX DBD, ACBGEN will remove insert sensitivity
  • PSBUT0453W PCB(%3%) %8, SENSEG %8 must have sensitivity to sequence field for inserts using field level sensitivity
Parent topic: PSB Error Messages


PSBUT0401W More than one PSBGEN macro, all but the first ignored

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0402W PCB(%3%) %8, TYPE=%8 invalid, assumed TYPE=DB

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0403W Invalid PCB PROCOPT "%6", assumed PROCOPT "%4"

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0404W PCB(%3%) %8, SENSEG %8 PROCOPT operand ignored. SENSEG PROCOPT must be omitted when PCB PROCOPT is %4

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0405W Unknown keyword %8 for %8 ignored

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0406 PCB #%3% %8, SENSEG %8 PROCOPT=%4 invalid.

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0407W PCBNAME or label %8 is not unique. This parameter has been ignored for PCB #%3% in PSB %8

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0451W PCB(%3%) %8, an I/O PCB will not be created when this PSB is used in a CICS program or an IMS program defined as a type DLI

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0452W PCB(%3%) %8, insert calls not allowed to INDEX DBD, ACBGEN will remove insert sensitivity

Parent topic: Messages PSBUT0401 to PSBUT0453


PSBUT0453W PCB(%3%) %8, SENSEG %8 must have sensitivity to sequence field for inserts using field level sensitivity

Parent topic: Messages PSBUT0401 to PSBUT0453


Messages PSBUT04A1 to PSBUT04A6

  • PSBUT04A1W Continuation cannot start in column 1
  • PSBUT04A2W Expected "=", found "(", "=" is assumed
  • PSBUT04A3W Continuation expected, none received
  • PSBUT04A4W Invalid character following final quote "%1".
  • PSBUT04A5W %8 has a non-numeric value "%8", assumed zero
  • PSBUT04A6W Duplicate keyword %8 specified, last one used
Parent topic: PSB Error Messages


PSBUT04A1W Continuation cannot start in column 1

Parent topic: Messages PSBUT04A1 to PSBUT04A6


PSBUT04A2W Expected "=", found "(", "=" is assumed

Parent topic: Messages PSBUT04A1 to PSBUT04A6


PSBUT04A3W Continuation expected, none received

Parent topic: Messages PSBUT04A1 to PSBUT04A6


PSBUT04A4W Invalid character following final quote "%1".

Parent topic: Messages PSBUT04A1 to PSBUT04A6


PSBUT04A5W %8 has a non-numeric value "%8", assumed zero

Parent topic: Messages PSBUT04A1 to PSBUT04A6


PSBUT04A6W Duplicate keyword %8 specified, last one used

Parent topic: Messages PSBUT04A1 to PSBUT04A6


Messages PSBUT04E1 to PSBUT04E2

  • PSBUT04E1W EQU %8 error, keyword already has data
  • PSBUT04E2W EQU %8 error, data already has a keyword
Parent topic: PSB Error Messages


PSBUT04E1W EQU %8 error, keyword already has data

Parent topic: Messages PSBUT04E1 to PSBUT04E2


PSBUT04E2W EQU %8 error, data already has a keyword

Parent topic: Messages PSBUT04E1 to PSBUT04E2


Messages PSBUT0801 to PSBUT0873

  • PSBUT0801E PSBGEN macro missing required PSBNAME operand
  • PSBUT0802E Required PSBGEN macro statement missing
  • PSBUT0803E PCB(%3%), %4 PCB missing required NAME/DBDNAME operand
  • PSBUT0804E PCB(%3%) %8, SENSEG statement invalid for GSAM PCB
  • PSBUT0805E PCB(%3%) %8, SENSEG(%3%) missing required NAME operand
  • PSBUT0806E PCB(%3%) %8, senseg %8 missing required PARENT operand or more than one SENSEG in PCB indicates PARENT=0
  • PSBUT0807E PCB(%3%) %8, SENSEG %8, parent segment %8 not previously defined in this PCB
  • PSBUT0808E PCB(%3%) %8, SENSEG %8 not unique
  • PSBUT0809E PCB(%3%) %8, at least one SENSEG statement is required for a DB PCB
  • PSBUT0810E COPY statement missing required NAME parameter
  • PSBUT0811E COPY member %8 not found
  • PSBUT0812E PCB(%3%) %8, SENSEG statement limit of %4% per PSB exceeded.
  • PSBUT0813E PCB(%3%) %8 SENFLD statement limit of %5% per PSB exceeded
  • PSBUT0814E PCB(%3%) %8, SENSEG %8, SENFLD statement limit of %4% per SENSEG exceeded
  • PSBUT0815E SENFLD statement cannot precede PCB statement
  • PSBUT0816E PCB(%3%) SENFLD statement only valid with TYPE=DB PCB
  • PSBUT0817E PCB(%3%) SENFLD statement cannot precede SENSEG statement
  • PSBUT0818E PCB(%3%) %8, SENSEG %8, SENFLD statement missing required NAME operand
  • PSBUT0819E PCB(%3%) %8, SENSEG %8, SENFLD %8 statement missing required START operand
  • PSBUT0820E PCB(%3%) %8, SENSEG %8, SENFLD %8 START value exceeds 32767
  • PSBUT0821E PCB statement limit of %4% per PSB exceeded
  • PSBUT0822E SENSEG statement limit of %4% per PCB exceeded
  • PSBUT0823E PCB(%3%) %8, SENSEG %8, DOS/VS VIRFLD statement not valid for IMS/ESA (MVS) compatibility. Use system config IBM DLI PLATFORM for DOS/VS syntax
  • PSBUT0824E PCB(%3%), SENSEG %8, SENFLD %8's BYTES, TYPE, or RTNAME keywords not valid for IMS/ESA (MVS) compatibility. Use system config IBM DLI PLATFORM for DOS/VS syntax
  • PSBUT0825E SENSEG statement cannot precede PCB statement
  • PSBUT0826E PCB(%3%), SENSEG statement only valid with TYPE=DB PCB
  • PSBUT0827E PCB #%3% %8, SENSEG %8, PROCOPT=%4 invalid.
  • PSBUT0851E PCB (%3%) %8, DBD access %5 does not support alternate processing sequence %8
  • PSBUT0852E PCB (%3%) %8, SENSEG %8 not in database
  • PSBUT0853E PCB (%3%) %8, segment %8, SENSEG parent %8 is not same as database SEGM parent %8
  • PSBUT0854E PCB (%3%) %8, SENSEG %8 does not have DBD LCHILD statement for alternate processing sequence %8
  • PSBUT0855E PCB (%3%), SENSEG %8 logical DBD %8 refers to physical DBD %8 which has not been Genned
  • PSBUT0856E PCB (%3%), index database %8 refers to physical database %8 which has not been Genned
  • PSBUT0857E PCB (%3%) %8, dynamic ACBGEN failed, reason code %4%
  • PSBUT0858E PCB (%3%) %8, ACBGEN lookup failed, reason code %4%
  • PSBUT0859E PCB (%3%) %8, SENSEG %8, SENFLD %8 not defined as field in database
  • PSBUT0860E PCB (%3%) %8, GSAM PCB references non-GSAM DBD, access will result in 476 abend
  • PSBUT0862E PCB (%3%) %8, SENSEG %8 specifies incorrect logical child segment
  • PSBUT0863E PCB (%3%) %8, SENSEG %8 specifies incorrect destination parent segment
  • PSBUT0864E PCB (%3%) %8, SENSEG %8, invalid parentage structure
  • PSBUT0865E PCB (%3%) %8, SENSEG %8 is a duplicate of senseg %8
  • PSBUT0866E PCB (%3%) %8, SENSEG %8, logical parent segment %8 not found in source database %8
  • PSBUT0867E PCB (%3%) %8, SENSEG %8, invalid parentage structure in source database %8 for logical parent segment %8
  • PSBUT0868E PCB (%3%) %8, SENSEG %8 is not root segment and no PROCSEQ has been specified
  • PSBUT0869E PCB (%3%) %8, ACB block failure, reason code %4%.
  • PSBUT0870E PCB (%3%) %8, paired logical child segment %8 intersection data length mismatch
  • PSBUT0871E PCB (%3%) %8, SENSEG %8, DBD field %8 referenced by PCB SENFLD %8, overlaps variable length segment length code (LL)
  • PSBUT0872E PCB (%3%) %8, ACB(L2) verify failure, reason code %4%
  • PSBUT0873 PCB #%3%, DBD %8 not Genned, ACB will not be generated
Parent topic: PSB Error Messages


PSBUT0801E PSBGEN macro missing required PSBNAME operand

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0802E Required PSBGEN macro statement missing

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0803E PCB(%3%), %4 PCB missing required NAME/DBDNAME operand

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0804E PCB(%3%) %8, SENSEG statement invalid for GSAM PCB

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0805E PCB(%3%) %8, SENSEG(%3%) missing required NAME operand

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0806E PCB(%3%) %8, senseg %8 missing required PARENT operand or more than one SENSEG in PCB indicates PARENT=0

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0807E PCB(%3%) %8, SENSEG %8, parent segment %8 not previously defined in this PCB

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0808E PCB(%3%) %8, SENSEG %8 not unique

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0809E PCB(%3%) %8, at least one SENSEG statement is required for a DB PCB

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0810E COPY statement missing required NAME parameter

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0811E COPY member %8 not found

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0812E PCB(%3%) %8, SENSEG statement limit of %4% per PSB exceeded.

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0813E PCB(%3%) %8 SENFLD statement limit of %5% per PSB exceeded

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0814E PCB(%3%) %8, SENSEG %8, SENFLD statement limit of %4% per SENSEG exceeded

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0815E SENFLD statement cannot precede PCB statement

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0816E PCB(%3%) SENFLD statement only valid with TYPE=DB PCB

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0817E PCB(%3%) SENFLD statement cannot precede SENSEG statement

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0818E PCB(%3%) %8, SENSEG %8, SENFLD statement missing required NAME operand

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0819E PCB(%3%) %8, SENSEG %8, SENFLD %8 statement missing required START operand

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0820E PCB(%3%) %8, SENSEG %8, SENFLD %8 START value exceeds 32767

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0821E PCB statement limit of %4% per PSB exceeded

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0822E SENSEG statement limit of %4% per PCB exceeded

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0823E PCB(%3%) %8, SENSEG %8, DOS/VS VIRFLD statement not valid for IMS/ESA (MVS) compatibility. Use system config IBM DLI PLATFORM for DOS/VS syntax

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0824E PCB(%3%), SENSEG %8, SENFLD %8's BYTES, TYPE, or RTNAME keywords not valid for IMS/ESA (MVS) compatibility. Use system config IBM DLI PLATFORM for DOS/VS syntax

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0825E SENSEG statement cannot precede PCB statement

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0826E PCB(%3%), SENSEG statement only valid with TYPE=DB PCB

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0827E PCB #%3% %8, SENSEG %8, PROCOPT=%4 invalid.

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0851E PCB (%3%) %8, DBD access %5 does not support alternate processing sequence %8

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0852E PCB (%3%) %8, SENSEG %8 not in database

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0853E PCB (%3%) %8, segment %8, SENSEG parent %8 is not same as database SEGM parent %8

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0854E PCB (%3%) %8, SENSEG %8 does not have DBD LCHILD statement for alternate processing sequence %8

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0855E PCB (%3%), SENSEG %8 logical DBD %8 refers to physical DBD %8 which has not been Genned

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0856E PCB (%3%), index database %8 refers to physical database %8 which has not been Genned

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0857E PCB (%3%) %8, dynamic ACBGEN failed, reason code %4%

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0858E PCB (%3%) %8, ACBGEN lookup failed, reason code %4%

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0859E PCB (%3%) %8, SENSEG %8, SENFLD %8 not defined as field in database

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0860E PCB (%3%) %8, GSAM PCB references non-GSAM DBD, access will result in 476 abend

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0862E PCB (%3%) %8, SENSEG %8 specifies incorrect logical child segment

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0863E PCB (%3%) %8, SENSEG %8 specifies incorrect destination parent segment

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0864E PCB (%3%) %8, SENSEG %8, invalid parentage structure

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0865E PCB (%3%) %8, SENSEG %8 is a duplicate of senseg %8

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0866E PCB (%3%) %8, SENSEG %8, logical parent segment %8 not found in source database %8

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0867E PCB (%3%) %8, SENSEG %8, invalid parentage structure in source database %8 for logical parent segment %8

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0868E PCB (%3%) %8, SENSEG %8 is not root segment and no PROCSEQ has been specified

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0869E PCB (%3%) %8, ACB block failure, reason code %4%.

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0870E PCB (%3%) %8, paired logical child segment %8 intersection data length mismatch

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0871E PCB (%3%) %8, SENSEG %8, DBD field %8 referenced by PCB SENFLD %8, overlaps variable length segment length code (LL)

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0872E PCB (%3%) %8, ACB(L2) verify failure, reason code %4%

Parent topic: Messages PSBUT0801 to PSBUT0873


PSBUT0873 PCB #%3%, DBD %8 not Genned, ACB will not be generated

Parent topic: Messages PSBUT0801 to PSBUT0873


Messages PSBUT08A1 to PSBUT08A3

  • PSBUT08A1E Unmatched parentheses
  • PSBUT08A2E Unmatched quotes.
  • PSBUT08A3E Positional operand cannot follow keyword operand: %60%
Parent topic: PSB Error Messages


PSBUT08A1E Unmatched parentheses

Parent topic: Messages PSBUT08A1 to PSBUT08A3


PSBUT08A2E Unmatched quotes.

Parent topic: Messages PSBUT08A1 to PSBUT08A3


PSBUT08A3E Positional operand cannot follow keyword operand: %60%

Parent topic: Messages PSBUT08A1 to PSBUT08A3


Messages PSBUT08P1 to PSBUT08P2

  • PSBUT08P1E Number of list operands exceeds MFIMS maximum of %3%.
  • PSBUT08P2E Macro %8, keyword %8 has unmatched parentheses
Parent topic: PSB Error Messages


PSBUT08P1E Number of list operands exceeds MFIMS maximum of %3%.

Parent topic: Messages PSBUT08P1 to PSBUT08P2


PSBUT08P2E Macro %8, keyword %8 has unmatched parentheses

Parent topic: Messages PSBUT08P1 to PSBUT08P2


Messages PSBUT0L01 to PSBUT0L99

  • PSBUT0L01E MFIMS PCB macro statement limit reached. Only %4% PCB macros per PSB with PSBGEN format 2 files
  • PSBUT0L02E PCB(%3%) %8, minimum RECLEN exceeds maximum RECLEN
  • PSBUT0L03E PSBGEN format 2 SENSEG macro statement limit of %4% per PSB exceeded
  • PSBUT0L54E PCB (%3) %8, SENSEG %8, logical parent segment %8 concatenated key not unique in database %8. MFIMS requires that the LPCK is unique
  • PSBUT0L55E No DBDs have been genned, verify cannot complete
  • PSBUT0L99E Valid software license not present. Reason code (%4%)
Parent topic: PSB Error Messages


PSBUT0L01E MFIMS PCB macro statement limit reached. Only %4% PCB macros per PSB with PSBGEN format 2 files

Parent topic: Messages PSBUT0L01 to PSBUT0L99


PSBUT0L02E PCB(%3%) %8, minimum RECLEN exceeds maximum RECLEN

Parent topic: Messages PSBUT0L01 to PSBUT0L99


PSBUT0L03E PSBGEN format 2 SENSEG macro statement limit of %4% per PSB exceeded

Parent topic: Messages PSBUT0L01 to PSBUT0L99


PSBUT0L54E PCB (%3) %8, SENSEG %8, logical parent segment %8 concatenated key not unique in database %8. MFIMS requires that the LPCK is unique

Parent topic: Messages PSBUT0L01 to PSBUT0L99


PSBUT0L55E No DBDs have been genned, verify cannot complete

Parent topic: Messages PSBUT0L01 to PSBUT0L99


PSBUT0L99E Valid software license not present. Reason code (%4%)

Parent topic: Messages PSBUT0L01 to PSBUT0L99


Messages PSBUT0LA1 to PSBUT0LA3

  • PSBUT0LA1E Positional operand cannot follow keyword operand: %60% MFIMS does not perform MFSGEN syntax error recovery
  • PSBUT0LA2E Length of operand exceeds MFIMS maximum of %4 bytes
  • PSBUT0LA3 Unexpected parsing error, report to Technical Support.
Parent topic: PSB Error Messages


PSBUT0LA1E Positional operand cannot follow keyword operand: %60% MFIMS does not perform MFSGEN syntax error recovery

Parent topic: Messages PSBUT0LA1 to PSBUT0LA3


PSBUT0LA2E Length of operand exceeds MFIMS maximum of %4 bytes

Parent topic: Messages PSBUT0LA1 to PSBUT0LA3


PSBUT0LA3 Unexpected parsing error, report to Technical Support.

Parent topic: Messages PSBUT0LA1 to PSBUT0LA3


Messages PSBUT0LP1 to PSBUT0LP3

  • PSBUT0LP1E Length of operand exceeds MFIMS size of %4% bytes
  • PSBUT0LP2E Number of list operands exceeds MFIMS maximum of %3%
  • PSBUT0LP3E Length of list exceeds MFIMS maximum of %4% bytes
Parent topic: PSB Error Messages


PSBUT0LP1E Length of operand exceeds MFIMS size of %4% bytes

Parent topic: Messages PSBUT0LP1 to PSBUT0LP3


PSBUT0LP2E Number of list operands exceeds MFIMS maximum of %3%

Parent topic: Messages PSBUT0LP1 to PSBUT0LP3


PSBUT0LP3E Length of list exceeds MFIMS maximum of %4% bytes

Parent topic: Messages PSBUT0LP1 to PSBUT0LP3


Messages PSBUT0U01 to PSBUT0U58

  • PSBUT0U01U File status %A5 opening file %C60. %B40%
  • PSBUT0U02U File status %A5 issuing close for file %C60. %B40%
  • PSBUT0U03U File status %A5 issuing read for file %C60. %B40%
  • PSBUT0U04U File status %5 issuing close for PSBGEN file. %40%
  • PSBUT0U05U File status %5 issuing close for PSBGEN SENFLD file. %40%
  • PSBUT0U06U File status %5 issuing create file for PSBGEN. %40%
  • PSBUT0U07U File status %5 converting PSBGEN file. %40%
  • PSBUT0U08U File status %5 issuing delete for PSBGEN. %40%
  • PSBUT0U09U File status %5 issuing delete for PSBGEN field file. %40%
  • PSBUT0U10U File status %5 issuing read/rewrite for PSBGEN file. %40%
  • PSBUT0U11U File status %5 issuing write for PSBGEN file. %40%
  • PSBUT0U12U File status %5 issuing get lock for PSBGEN file. %40%
  • PSBUT0U13U File status %5 issuing set/date for PSBGEN. %40%
  • PSBUT0U35U File not found %C60.
  • PSBUT0U54U File status %5 issuing read for PSBGEN. %40%
  • PSBUT0U55U File status %5 issuing read for PSBGEN field file. %40%
  • PSBUT0U56U File status %5 issuing read for DBDGEN field file. %40%
  • PSBUT0U57U PSB %8 not genned, PSB must be genned prior to verification
  • PSBUT0U58U File status %5 issuing start/read for DBDGEN file. %40%
Parent topic: PSB Error Messages


PSBUT0U01U File status %A5 opening file %C60. %B40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U02U File status %A5 issuing close for file %C60. %B40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U03U File status %A5 issuing read for file %C60. %B40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U04U File status %5 issuing close for PSBGEN file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U05U File status %5 issuing close for PSBGEN SENFLD file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U06U File status %5 issuing create file for PSBGEN. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U07U File status %5 converting PSBGEN file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U08U File status %5 issuing delete for PSBGEN. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U09U File status %5 issuing delete for PSBGEN field file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U10U File status %5 issuing read/rewrite for PSBGEN file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U11U File status %5 issuing write for PSBGEN file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U12U File status %5 issuing get lock for PSBGEN file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U13U File status %5 issuing set/date for PSBGEN. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U35U File not found %C60.

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U54U File status %5 issuing read for PSBGEN. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U55U File status %5 issuing read for PSBGEN field file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U56U File status %5 issuing read for DBDGEN field file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U57U PSB %8 not genned, PSB must be genned prior to verification

Parent topic: Messages PSBUT0U01 to PSBUT0U58


PSBUT0U58U File status %5 issuing start/read for DBDGEN file. %40%

Parent topic: Messages PSBUT0U01 to PSBUT0U58


Messages PSBUT0W01 to PSBUT0W55

  • PSBUT0W01W MFIMS statement continuation overflow, extras ignored. Maximum number of lines per statement is %2%
  • PSBUT0W02W Only one level of nested copy statements supported by MFIMS, further nested COPYs ignored
  • PSBUT0W03W PCB(%3%), GSAM PCB %8 has MFIMS RECLEN of zero
  • PSBUT0W04W PCB(%3%), GSAM PCB %8, RECLEN operand truncated to 32768
  • PSBUT0W05W PCB(%3%) %8, SENSEG %8, SSPTR operand ignored. MFIMS does not support the SSPTR operand for DEDBs
  • PSBUT0W06W PCB(%3%) %8, SENSEG %8, INDICES operand ignored, not supported by MFIMS
  • PSBUT0W07W PCB(%3%) %8, SENSEG %8, VIRFLD statement ignored, not supported by MFIMS
  • PSBUT0W08W PCB(%3%), SENSEG %8, SENFLD %8, DOS/VS SENFLD keywords of BYTES, TYPE or RTNAME ignored, not supported by MFIMS. This message suppressed for other occurrences
  • PSBUT0W09W PCB(%3%), ALTRESP=YES not supported by MFIMS, changed to ALTRESP=NO
  • PSBUT0W10W PCB(%3%), VIEW=MSDB not supported by MFIMS, changed to VIEW=DEDB
  • PSBUT0W11W Unknown statement "%8" ignored, unsupported by MFIMS
  • PSBUT0W12W Comment line continuation has non-blanks in columns 1-15, assumed blank by MFIMS: %15%
  • PSBUT0W13W PCB #%3% %8, PROCSEQ=DSIV11 ignored, not supported by MFIMS.
  • PSBUT0W35W File not found %C60.
  • PSBUT0W51W PCB (%3%), DBD %8 not Genned, access will result in 476 abend
  • PSBUT0W52W PCB (%3%) %8, SENFLD statements not verified, physical DBD not Genned with MFIMS Version 2.5 or later
  • PSBUT0W53W PCB (%3%) %8, KEYLEN operand value %3 is less than concatenated key length %3
  • PSBUT0W54W PCB (%3%) %8, logical parent database %8 not Genned, access may produce unpredictable results
  • PSBUT0W55W No DBDs have been genned
Parent topic: PSB Error Messages


PSBUT0W01W MFIMS statement continuation overflow, extras ignored. Maximum number of lines per statement is %2%

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W02W Only one level of nested copy statements supported by MFIMS, further nested COPYs ignored

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W03W PCB(%3%), GSAM PCB %8 has MFIMS RECLEN of zero

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W04W PCB(%3%), GSAM PCB %8, RECLEN operand truncated to 32768

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W05W PCB(%3%) %8, SENSEG %8, SSPTR operand ignored. MFIMS does not support the SSPTR operand for DEDBs

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W06W PCB(%3%) %8, SENSEG %8, INDICES operand ignored, not supported by MFIMS

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W07W PCB(%3%) %8, SENSEG %8, VIRFLD statement ignored, not supported by MFIMS

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W08W PCB(%3%), SENSEG %8, SENFLD %8, DOS/VS SENFLD keywords of BYTES, TYPE or RTNAME ignored, not supported by MFIMS. This message suppressed for other occurrences

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W09W PCB(%3%), ALTRESP=YES not supported by MFIMS, changed to ALTRESP=NO

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W10W PCB(%3%), VIEW=MSDB not supported by MFIMS, changed to VIEW=DEDB

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W11W Unknown statement "%8" ignored, unsupported by MFIMS

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W12W Comment line continuation has non-blanks in columns 1-15, assumed blank by MFIMS: %15%

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W13W PCB #%3% %8, PROCSEQ=DSIV11 ignored, not supported by MFIMS.

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W35W File not found %C60.

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W51W PCB (%3%), DBD %8 not Genned, access will result in 476 abend

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W52W PCB (%3%) %8, SENFLD statements not verified, physical DBD not Genned with MFIMS Version 2.5 or later

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W53W PCB (%3%) %8, KEYLEN operand value %3 is less than concatenated key length %3

CAUTION:
This warning is an indication that the PSB is not valid on the mainframe. If you intend to move the PSB back to the mainframe, you must first correct it.
Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W54W PCB (%3%) %8, logical parent database %8 not Genned, access may produce unpredictable results

Parent topic: Messages PSBUT0W01 to PSBUT0W55


PSBUT0W55W No DBDs have been genned

Parent topic: Messages PSBUT0W01 to PSBUT0W55


Messages PSBUT0WA1 to PSBUT0WA9

  • PSBUT0WA1W BLANK line not allowed, MFIMS ignores blank lines
  • PSBUT0WA2W Exceeded MFIMS maximum number of operands, extras ignored
  • PSBUT0WA3W Columns 1-15 non-blank on continuation, MFIMS assumes blank
  • PSBUT0WA4W LABEL exceeds 8 bytes, MFIMS truncated to 8
  • PSBUT0WA5W Statement type must be on 1st line, ignored
  • PSBUT0WA6W %8 and other macro control statements not supported by MFIMS. This and subsequent control statements ignored
  • PSBUT0WA7W Column 16 on continuation was blank, MFIMS ignoring line.
  • PSBUT0WA8W Missing comma for continuation, MFIMS assumed present.
  • PSBUT0WA9W Invalid value "%8" - MFIMS ignored keyword and value
Parent topic: PSB Error Messages


PSBUT0WA1W BLANK line not allowed, MFIMS ignores blank lines

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA2W Exceeded MFIMS maximum number of operands, extras ignored

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA3W Columns 1-15 non-blank on continuation, MFIMS assumes blank

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA4W LABEL exceeds 8 bytes, MFIMS truncated to 8

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA5W Statement type must be on 1st line, ignored

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA6W %8 and other macro control statements not supported by MFIMS. This and subsequent control statements ignored

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA7W Column 16 on continuation was blank, MFIMS ignoring line.

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA8W Missing comma for continuation, MFIMS assumed present.

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


PSBUT0WA9W Invalid value "%8" - MFIMS ignored keyword and value

Parent topic: Messages PSBUT0WA1 to PSBUT0WA9


Messages PSBUT0WE1 to PSBUT0WE2

  • PSBUT0WE1W MFIMS EQU limit of %4 exceeded, extras ignored
  • PSBUT0WE2W EQU %8 contains unbalanced quotes. Maximum MFIMS EQU length is %4
Parent topic: PSB Error Messages


PSBUT0WE1W MFIMS EQU limit of %4 exceeded, extras ignored

Parent topic: Messages PSBUT0WE1 to PSBUT0WE2


PSBUT0WE2W EQU %8 contains unbalanced quotes. Maximum MFIMS EQU length is %4

Parent topic: Messages PSBUT0WE1 to PSBUT0WE2


Messages PSBUT0WF1 to PSBUT0WF2

  • PSBUT0WF1W In-line CSECT or DSECT is not supported by MFIMS. Ignoring all statements until END statement
  • PSBUT0WF2W In-line macro definitions not supported by MFIMS. Ignoring all statements until MEND statement
Parent topic: PSB Error Messages


PSBUT0WF1W In-line CSECT or DSECT is not supported by MFIMS. Ignoring all statements until END statement

Parent topic: Messages PSBUT0WF1 to PSBUT0WF2


PSBUT0WF2W In-line macro definitions not supported by MFIMS. Ignoring all statements until MEND statement

Parent topic: Messages PSBUT0WF1 to PSBUT0WF2


SECRMT MSG ID: RMTSEC REMOTE IMS REQUESTER

The following information is also displayed with this error:

SECRMT Security invalid.  Remote system requires userid and password.
SECRMT
SECRMT ---reserved internal for userid   field--- %10
SECRMT ---reserved internal for password field--- %10
SECRMT
SECRMT Enter userid, password, and select option:
SECRMT   C - Connect with these values
SECRMT   T - Terminate application
SECRMT   ---reserved for option S description---
Parent topic: IMS Error Messages


IMS Stage 1 Import/Export Error Messages

These messages are output by the IMS stage 1 import/export utility. 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. These messages have the prefix IMSUT.

  • IMSUT1000E Error opening input (STAGE 1) file, Status: %5 DSN: %60
  • IMSUT1001E Error opening output (EXTRACT) file, Status: %5 DSN: %60
  • IMSUT1002E Error opening input (EXTRACT) file, Status: %5 DSN: %60
  • IMSUT1003E No output (EXTRACT) file specified; stage1ext ending
  • IMSUT1004E Error opening .LST file, Status: %5 DSN: %60
Parent topic: IMS Error Messages


IMSUT1000E Error opening input (STAGE 1) file, Status: %5 DSN: %60

Parent topic: IMS Stage 1 Import/Export Error Messages


IMSUT1001E Error opening output (EXTRACT) file, Status: %5 DSN: %60

Parent topic: IMS Stage 1 Import/Export Error Messages


IMSUT1002E Error opening input (EXTRACT) file, Status: %5 DSN: %60

Parent topic: IMS Stage 1 Import/Export Error Messages


IMSUT1003E No output (EXTRACT) file specified; stage1ext ending

Parent topic: IMS Stage 1 Import/Export Error Messages


IMSUT1004E Error opening .LST file, Status: %5 DSN: %60

Parent topic: IMS Stage 1 Import/Export Error Messages


IMS Tracing Flags

A list of Enterprise Server IMS tracing flags used by MSS. Check all that apply.

Flag | Traces
api | IMS API calls
bts | Batch Terminal Simulator
cli | Client processing
data | (Not used)
db-ctl | DB control processing
db-enq | DB lock management
db-thread | DB thread management
db-trd-stg | DB thread storage management
es-db | DB control processing
es-stg | Storage management for MFS processing
i/o | Database I/O
rims | Remote IMS
stg | DB storage management
sys | (Not used)
tm-buffer | TM buffer management
tm-ctl | TM control processing
tm-enq | TM lock management
tm-mon | TM buffer monitor
tm-thread | TM thread management
tm-trd-stg | TM thread storage management
Parent topic: Reference
Parent topic: IMS Support in Enterprise Server


IMS-Specific Environment Variables

Provides a summary description for each IMS-specific environment variable used by Enterprise Server.

This topic lists environment variables related to configuring the IMS environment in an enterprise server region.

Important: This topic provides summary descriptions only. For complete information, see corresponding variables in the Environment variables in alphabetical order topic.
Variable | Description
ES_ACBLIB | The location of IMS ACB files.
ES_DFS3650 | The default transaction to execute or MOD file to be displayed after successfully signing on to IMS. You specify these by setting environment variables prior to the start of the region: ES_DFS3650 - set to MOD if a MOD file is to be sent, or TRX if a TRANSACTION is to be executed. If you set to MOD, ES_MOD3650 needs to be set to the name of the MOD you want to display. If you set to TRX, ES_TRX3650 needs to be set to the name of the transaction.
ES_IMS_BASIC_CHKP_OPT | When set to 1, enables a basic checkpoint call to process as if a SYNC call had been issued. The default is 0 (zero).
ES_IMS_BYPASS_OTMA_DEST_RES | By default, a CHNG call issued from an OTMA- or IMS Connect-submitted transaction assumes that the destination is the OTMA client. In some circumstances, the previous behavior of assuming a non-OTMA client is desirable. To use the previous behavior, set this environment variable to Y.
ES_IMS_CONFIG | The IMS TM parameters.
ES_IMS_DB_COMMIT_FLUSH | When set to 0 (zero), forces the flushing of database buffers to disk on CLOSE only (default). When set to 1, forces the flushing of database buffers to disk on COMMIT only.
ES_IMS_DB_TLOG_WRITETHRU | When set to 0 (zero), forces the flushing of TLOG buffers to disk on COMMIT only (default). When set to 1, forces the flushing of TLOG buffers to disk on all database I/O.
ES_IMS_DEADLOCK_WAIT | Time in milliseconds to wait before checking for a deadlock. The default is 1000 (1 second).
ES_IMS_DIAGNOSE | Marks IMS TM as diagnose mode only for IMSMSGQ.
ES_IMS_DOSVS_PCB | Emulates DOS/VSE PCB address alignment for EXEC DLI programs.
ES_IMS_DUMP_ON_DEADLOCK | Creates a system dump when a deadlock is detected.
ES_IMS_DUMP_ON_TIMEOUT | Creates a system dump when a lock timeout occurs.
ES_IMS_EXITPATH | The location of compiled code that contains segment, field, and/or print exits.
ES_IMS_FORCE_SIGNON | Enables a user to force a sign-on to IMS on the current terminal and sign off from other terminals.
ES_IMS_GOTO_CICS_ON_SIGNOFF | Returns to CICS upon logging off or timing out, rather than returning to the IMS sign-on screen, which is the default behavior.
ES_IMS_IBMPLATFORM Sets the emulation for the IMS run-time. Valid values are: M (for MVS) or D (for DOSVS). The default value is M.
Note: This variable is rarely required to be changed from its default, even for the majority of DOSVS users.
ES_IMS_IMSID | Allows the user to specify the IMS System ID returned to the AIBTDLI INQY ENVIRON call.
ES_IMS_INQY_OTMA | Returns TPIPE, MBR, SYNC, and MSYNC to an INQY call.
ES_IMS_INQY_UNKNOWN | Value returned to an INQY call.
ES_IMS_IRLM | Enables Internal Lock Resource Manager (IRLM) locking. IRLM locking more closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock.
ES_IMS_LOCALDLI | Deprecated. See IMS Database Locking. When set to 1, directs batch program execution to process all IMS DB calls entirely in the JES initiator providing significant performance improvement. All IMS DB control processes accessed from the batch program must be stopped before execution because they become exclusively owned by JES until the program completes.
ES_IMS_LOCK_TIMEOUT | The number of seconds during which IMS DB control continues to retry a locked record before timing out. Valid values are 0 to 65535. The default is 30 seconds; a value of 0 indicates an indefinite wait time.
ES_IMS_LTERM_PREFIX
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.

Enables specification of a one- to four-character alternative LTERM prefix to apply when ES_IMS_SINGLE is set to N. The default is OTMA.

ES_IMS_LU_LTERM | Determines the value of the LTERM literal returned by the MFS system. Valid values are: Y to return the LU name; N to return the user ID.
ES_IMS_MESGQ | Sets the configuration for the IMS TM message queue. See ES_IMS_MESGQ in Environment variables in alphabetical order for details.
ES_IMS_OTMA_DEST | Each specified destination consists of the destination name, the NONOTMA keyword, and the LU type (LU1 or LU3) separated by commas. Each destination definition is separated by a semi-colon.
ES_IMS_PATH | The location of compiled COBOL applications.
ES_IMS_PLI_INDIRECT_PCBADDR

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

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

The default is D (dynamic).

ES_IMS_RCLASS

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

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

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

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


mfims Command-line Utility

The mfims command-line utility enables you to interact with your IMS database from the command line. Using the mfims command, you can:

  • Execute all components of the IMSDBU Utility
  • Generate PSBs, DBDs, and MFSs
  • Export and import IMS transactions

Each of these three types of access require a specific set of command-line arguments. See mfims Generation, mfims IMSDBU, and mfims Export/Import for complete information.

  • mfims Generation
  • mfims IMSDBU
  • mfims Export/Import
Parent topic: Reference


mfims Generation

  • mfims generation command
  • mfims generation directives
Parent topic: mfims Command-line Utility
Related concepts
IMS Generation
Prepare the MFDEMO Application


mfims generation command

The mfims generation command enables you to generate DBDs, PSBs, and MFS files from the command line.

Syntax:

mfims utility filename [directives]

Parameters:

utility Can be one of:
  • dbdgen
  • mfsgen
  • psbgen
filename | The name of the .psb, .dbd, or .mfs file to generate.
directives | A sequence of one or more directives. Directives can appear after any filename. Each directive must be separated by a space and must not be broken across two lines.

Comments:

Run the mfims generation command from an Enterprise Developer command prompt.

For complete information on all generation directives, see mfims generation directives.

Examples:

DBD generation

mfims dbdgen demo003.dbd map

MFS generation

mfims mfsgen demo90.mfs hexfill

PSB generation

mfims psbgen demo001t.psb echo all
Parent topic: mfims Generation
Related concepts
DBD Generation
PSB Generation
MFS Generation
Related tasks
To specify the location of generated files
Related reference
SXRBAFORMAT


mfims generation directives

mfims generation supports several directives you can use on the command line to specify details of file generation. The following is an alphabetical list of all mfims generation directives.

  • BLANKVAL
    Specifies the character set to use when the XDFLD DBDGEN statement has its NULLVAL keyword set to BLANK.
  • CBEGCS
    Enables support of double-byte character sets (DBCS) by identifying DBCS or mixed data and attributes, and generating the appropriate output control block files such as .mid, .mod, .dif, .dof.
  • CLS
    Clears the screen before starting the utility.
  • CONTMVS
    Enables the compiler to parse MFS continuation lines (those continued without a terminating comma) by treating the line that follows as a comment line, just as is done on the mainframe.
  • COPYEXT
    Specifies the copybook extension to be used when generating the complete copybook name for a DBD, MFS or PSB COPY statement.
  • CP
    Enables the CP preprocessor.
  • DATACOMPRESS
    Specifies the type of data compression to be done on sequential and indexed files.
  • DEFAULTEXT
    Specifies the default file extension added to the input file name when no extension is specified.
  • ECHO
    Controls the interaction with the DBDGEN, MFSGEN and PSBGEN utilities.
  • EXCLUPDT
    Opens the output files for exclusive use by this instance of DBDGEN and no other task can read or update the DBDGEN files until DBDGEN completes.
  • HEXFILL
    Enables you to retain the hexadecimal value of input characters when deploying an IMS EBCDIC application.
  • IMSLIBNO
    Specifies which IMS Load library directory in Workgroups is updated when multiple IMS Load Library directories are used.
  • KEYCOMPRESS
    Specifies the type of key compression to be done on indexed files.
  • LIST
    Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
  • MAP
    Runs the DBDMAP utility upon successful completion of DBDGEN.
  • NODCX
    Prevents the execution of data capture exit routines contained in DBD source.
  • /PATH
    Specifies the directory in which to save control blocks generated by MFSGEN.
  • SHRUPDT
    Opens the output files for sharing so other tasks can read and update these files while the DBDGEN utility is running.
  • SXRBAFORMAT
    For an IMS database that uses a system-generated /SX field to make a secondary index unique, this directive enables you to control the size of system-generated /SX fields.
  • VERIFY
    Runs the PSB Verify utility upon successful completion of PSBGEN.
  • DBDGEN Directives
  • MFSGEN Directives
  • PSBGEN Directives
Parent topic: mfims Generation
Related concepts
IMS Project Properties
Related tasks
To set project and file properties for .DBD, .MFS or .PSB source files


BLANKVAL

Specifies the character set to use when the XDFLD DBDGEN statement has its NULLVAL keyword set to BLANK.
Note: Supported by the DBDGEN mfims utility.

Syntax:

>>-----BLANKVAL--(.--A--.)---><
                  +--E--+

Parameters:

A
ASCII; interprets a blank to be an x'20' (ASCII space character).
E
EBCDIC; interpret a blank to be an x'40' (EBCDIC space character).

Properties:

Default: BLANKVAL(A)

Dependencies:

Applies only when the XDFLD DBDGEN statement has its NULLVAL keyword set to BLANK.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives


CBEGCS

Enables support of double-byte character sets (DBCS) by identifying DBCS or mixed data and attributes, and generating the appropriate output control block files such as .mid, .mod, .dif, .dof.
Note: Supported by all mfims utilities.

Syntax:

>>-----CBEGCS------><

Parameters:

None

Properties:

Default: None

Comments:

Before generating the MFS and before running a DBCS transaction, remove environment variables that set CODEPAGE or CODESET.

Generated control block files contain EBCDIC strings with SO/SI pairs enclosing DBCS literals.

Example:

mfims mfsgen demo98.mfs CBEGCS
Parent topic: mfims generation directives
Parent topic: MFSGEN Directives


CLS

Clears the screen before starting the utility.
Note: Supported by all mfims utilities.

Syntax:

>>-.----.--CLS------><
   +-NO-+

Parameters:

None

Properties:

Default: CLS

Dependencies:

None

Comments:

NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Parent topic: MFSGEN Directives
Parent topic: PSBGEN Directives


CONTMVS

Enables the compiler to parse MFS continuation lines (those continued without a terminating comma) by treating the line that follows as a comment line, just as is done on the mainframe.
Note: Supported by all mfims utilities.

Syntax:

>>-----CONTMVS------><

Parameters:

None

Properties:

Default: None

Comments:

When not specified, the compiler assumes terminating commas and treats the line that follows as a line continuation.

Example:

mfims mfsgen demo98.mfs CONTMVS
Parent topic: mfims generation directives
Parent topic: MFSGEN Directives


COPYEXT

Specifies the copybook extension to be used when generating the complete copybook name for a DBD, MFS or PSB COPY statement.
Note: Supported by all mfims utilities.

Syntax:

>>-----COPYEXT--(ext)------><

Parameters:

ext
The file extension used to override the default file extension. This can be any one- to three-character extension, or NULL.

Properties:

Default: COPYEXT(defaultExt)

Where defaultExt is the file extension of the specified DBD, MFS, or PSB source copybook name.

Dependencies:

None

Comments:

By default, the file extension of the original DBD, MFS or PSB source copybook file name is appended to the COPY member name. For example, if the original MFS copybook name was MYMFS1.MFS, and a COPY statement asked to include member MYINDX, then the copybook MYINDX.MFS is copied. If you specify COPYEXT(CPY), for example, this produces an included copybook name of MYINDX.CPY.

COPYEXT(NULL) indicates that the copybook file name has no extension.

COPYEXT process -INC and ++INCLUDE statements as COPY statements.

Member names longer than eight characters are truncated to eight characters with no warning message.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Parent topic: MFSGEN Directives
Parent topic: PSBGEN Directives


CP

Enables the CP preprocessor.
Note: Supported by the MFSGEN mfims utility.

Syntax:

>>-.----.--CP------><
   +-NO-+

Parameters:

None

Properties:

Default: NOCP

Dependencies:

None

Comments:

Use CP to generate an MFS that includes multiple nested copybooks.

Runs during the syntax check phase.

$SET is initial.

Parent topic: mfims generation directives
Parent topic: MFSGEN Directives


DATACOMPRESS

Specifies the type of data compression to be done on sequential and indexed files.
Note: Supported by the DBDGEN mfims utility.

Use of the DATACOMPRESS DBDGEN directive maps directly to the DATACOMPRESS COBOL compiler directive. See DATACOMPRESS for details.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Related reference
DATACOMPRESS


DEFAULTEXT

Specifies the default file extension added to the input file name when no extension is specified.
Note: Supported by all mfims utilities.

Syntax:

>>-----DEFAULTEXT--(ext)------><

Parameters

ext
An input file name extension.

Properties:

Default: DEFAULTEXT(DBD)

Dependencies:

None

Comments:

The value specified for ext replaces the default extension. For example, when you specify DEFAULTEXT(PSB), an input file name of MYFILE results in a name of MYFILE.PSB.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Parent topic: MFSGEN Directives
Parent topic: PSBGEN Directives


ECHO

Controls the interaction with the DBDGEN, MFSGEN and PSBGEN utilities.
Note: Supported by all mfims utilities.

Syntax:

>>-----ECHO--(keyword,msglvl,stoplvl)------><

Parameters:

keyword
The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl
A value from 4 through 20 to indicate the severity of messages to display. See below for more information.
stoplvl
A value from 4 through 20 to indicate the severity of messages to stop for user input. See below for more information.

Properties:

Default: ECHO(MSGS,4,8)

Comments:

The msglvl and stoplvl parameters can take the following values:

Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Parent topic: MFSGEN Directives
Parent topic: PSBGEN Directives
Related concepts
IMSDBU Automation


EXCLUPDT

Opens the output files for exclusive use by this instance of DBDGEN and no other task can read or update the DBDGEN files until DBDGEN completes.
Note: Supported by all mfims utilities.

Syntax:

{SHR | EXCL}UPDT

Parameters:

None

Properties:

Default: None

Dependencies:

Mutually exclusive to the SHRUPDT mfims directive.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Parent topic: MFSGEN Directives
Parent topic: PSBGEN Directives


HEXFILL

Enables you to retain the hexadecimal value of input characters when deploying an IMS EBCDIC application.
Note: Supported by the MFSGEN mfims utility.

Syntax:

>>-----HEXFILL------><

Parameters:

None

Properties:

Default: None

Dependencies:

None

Comments:

When running EBCDIC applications under Enterprise Server, if there are input fill characters coded as hexadecimal values in the MFS source, and those values should not be converted to EBCDIC at run time, compile your source specifying the HEXFILL directive. This causes hexadecimal values to remain as hexadecimal values at run time, and are not converted to EBCDIC.

Parent topic: mfims generation directives
Parent topic: MFSGEN Directives


IMSLIBNO

Specifies which IMS Load library directory in Workgroups is updated when multiple IMS Load Library directories are used.
Note: Supported by all mfims utilities.

Syntax:

>>-----IMSLIBNO--(x)------><

Parameters:

x
An integer in the range 1 to 25 to indicate the load library directory to update.

Properties:

Default: IMSLIBNO(1)

Dependencies:

None

Comments:

During generation, the DBDGEN files updated by default are located in the first load library directory as defined in the Workgroup. This is load library 1. An IMSLIBNO x value of 2 through 25 updates one of the second through the twenty-fifth load libraries defined, depending on the value specified.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Parent topic: MFSGEN Directives
Parent topic: PSBGEN Directives


KEYCOMPRESS

Specifies the type of key compression to be done on indexed files.
Note: Supported by the DBDGEN mfims utility.

Use of the KEYCOMPRESS DBDGEN directive maps directly to the KEYCOMPRESS COBOL compiler directive. See KEYCOMPRESS for details.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Related reference
KEYCOMPRESS


LIST

Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Note: Supported by all mfims utilities.

Syntax:

>>-.---.-.-------LIST--(filespec)--.-----><
   +-/-+ +.----.-LIST--------------+
          +-NO-+

Parameters:

filespec
The name and location to use for the listing file. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, MFIMS or IMSDBU creates the listing file in the current directory.

Properties:

Default: LIST(*.LST)

Comments:

NOLIST suppresses the creation of the listing file.

To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.

Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory. If no path is specified, the listing file is created in the current directory.

Specifying LIST is equivalent to specifying LIST(*.LST).

The default setting of LIST(*.LST) creates a listing file with a name that uses the base filename part of the input file name plus a file extension of .LST. For example, with MYPSB.PSB as the input name, LIST(*.LST) creates a file named MYPSB.LST. The default setting creates a list file named DBDLIST.LST, MFSLIST.LST or PSBLIST.LST respectively. NOLIST suppresses the output listing.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Parent topic: MFSGEN Directives
Parent topic: PSBGEN Directives
Related concepts
IMS Database Utility (IMSDBU)


MAP

Runs the DBDMAP utility upon successful completion of DBDGEN.
Note: Supported by the DBDGEN mfims utility.

Syntax:

>>-.----.--MAP------><
   +-NO-+

Parameters:

None

Properties:

Default: NOMAP

Dependencies:

None

Comments:

The return code from the DBDMAP utility does not affect the ending return code from DBDGEN.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives


NODCX

Prevents the execution of data capture exit routines contained in DBD source.
Note: Supported by the DBDGEN mfims utility.

Syntax:

>>-----NODCX--------><

Parameters:

None

Properties:

Default: None

Dependencies:

None

Comments:

NODCX can facilitate offload testing in cases where data capture exit programs are not needed, but you do not want to modify your DBD source to remove exit definitions during testing.

Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Related concepts
IMS Data Capture Exits


/PATH

Specifies the directory in which to save control blocks generated by MFSGEN.
Note: Supported by the MFSGEN mfims utility.

Syntax:

>>-----/PATH=pathname------><

Parameters:

pathname
The full path to the directory in which to save control blocks generated by MFSGEN.

Properties:

Default: /PATH=currentDir

Where currentDir is the full path to the current directory.

Dependencies:

None

Comments:

The pathname you specify overrides the path specified by the ES_MFSLIB environment variable.

Parent topic: mfims generation directives
Parent topic: MFSGEN Directives


SHRUPDT

Opens the output files for sharing so other tasks can read and update these files while the DBDGEN utility is running.
Note: Supported by all mfims utilities.

Syntax:

>>-----SHRUPDT------><

Parameters:

None

Properties:

Default: SHRUPDT

Dependencies:

Mutually exclusive to the EXCLUPDT mfims directive.

Parent topic: mfims generation directives


SXRBAFORMAT

For an IMS database that uses a system-generated /SX field to make a secondary index unique, this directive enables you to control the size of system-generated /SX fields.
Note: Supported by the DBDGEN mfims utility.

Syntax:

>>-----SXRBAFORMAT--"integer"--------><

Parameters:

integer
One of the following:
0 | 4-byte RBA allows DBs up to 4GB in size (default)
1 | 4-byte RBA with compression allows DBs up to 32GB in size
2 | 8-byte RBA allows DBs up to 2TB

Properties:

Default: SXRBAFORMAT"0"

Dependencies:

None

Comments:

When using SXRBAFORMAT"2", the size of the system-generated /SX field is increased from four bytes to eight bytes. Applications that access the secondary index database directly require that you adjust for this difference.

For databases created using a version of Enterprise Developer earlier than 2.2 Update 2, Hotfix 4, you must regenerate the DBD and run one of the following mfims imsdbu functions against the database before using SXRBAFORMAT:

  • Zeroload function
  • Load function
  • Reorganize function
Parent topic: mfims generation directives
Parent topic: DBDGEN Directives
Related reference
Load function
Zeroload function
Reorganize function
mfims generation command


VERIFY

Runs the PSB Verify utility upon successful completion of PSBGEN.
Note: Supported by the PSBGEN mfims utility.

Syntax:

>>-.----.--VERIFY------><
   +-NO-+

Parameters:

None

Properties:

Default: NOVERIFY

Dependencies:

None

Parent topic: mfims generation directives
Parent topic: PSBGEN Directives


DBDGEN Directives

  • BLANKVAL
    Specifies the character set to use when the XDFLD DBDGEN statement has its NULLVAL keyword set to BLANK.
  • CLS
    Clears the screen before starting the utility.
  • COPYEXT
    Specifies the copybook extension to be used when generating the complete copybook name for a DBD, MFS or PSB COPY statement.
  • DATACOMPRESS
    Specifies the type of data compression to be done on sequential and indexed files.
  • DEFAULTEXT
    Specifies the default file extension added to the input file name when no extension is specified.
  • ECHO
    Controls the interaction with the DBDGEN, MFSGEN and PSBGEN utilities.
  • EXCLUPDT
    Opens the output files for exclusive use by this instance of DBDGEN and no other task can read or update the DBDGEN files until DBDGEN completes.
  • IMSLIBNO
    Specifies which IMS Load library directory in Workgroups is updated when multiple IMS Load Library directories are used.
  • KEYCOMPRESS
    Specifies the type of key compression to be done on indexed files.
  • LIST
    Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
  • MAP
    Runs the DBDMAP utility upon successful completion of DBDGEN.
  • NODCX
    Prevents the execution of data capture exit routines contained in DBD source.
  • NODFSMARSH
    Set this to ignore any data marshaling extensions in the DBD source.
  • SXRBAFORMAT
    For an IMS database that uses a system-generated /SX field to make a secondary index unique, this directive enables you to control the size of system-generated /SX fields.
Parent topic: mfims generation directives
Related concepts
DBD Generation
Related reference
Project Properties - DBD Settings


NODFSMARSH

Set this to ignore any data marshaling extensions in the DBD source.
Note: Supported by DBDGEN.

Syntax:

>>-----NODFSMARSH------><

Parameters:

None

Properties:

Default: NODFSMARSH

Dependencies:

None.

Comments:

Data marshaling is not supported and any DBD source extensions that use DFSMARSH produce warning messages in the DBD generation. Use the NODFSMARSH directive to suppress these warning messages.

Parent topic: DBDGEN Directives


MFSGEN Directives

  • CBEGCS
    Enables support of double-byte character sets (DBCS) by identifying DBCS or mixed data and attributes, and generating the appropriate output control block files such as .mid, .mod, .dif, .dof.
  • CONTMVS
    Enables the compiler to parse MFS continuation lines (those continued without a terminating comma) by treating the line that follows as a comment line, just as is done on the mainframe.
  • CLS
    Clears the screen before starting the utility.
  • COPYEXT
    Specifies the copybook extension to be used when generating the complete copybook name for a DBD, MFS or PSB COPY statement.
  • CP
    Enables the CP preprocessor.
  • DEFAULTEXT
    Specifies the default file extension added to the input file name when no extension is specified.
  • ECHO
    Controls the interaction with the DBDGEN, MFSGEN and PSBGEN utilities.
  • EXCLUPDT
    Opens the output files for exclusive use by this instance of DBDGEN and no other task can read or update the DBDGEN files until DBDGEN completes.
  • HEXFILL
    Enables you to retain the hexadecimal value of input characters when deploying an IMS EBCDIC application.
  • IMSLIBNO
    Specifies which IMS Load library directory in Workgroups is updated when multiple IMS Load Library directories are used.
  • LIST
    Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
  • /PATH
    Specifies the directory in which to save control blocks generated by MFSGEN.
Parent topic: mfims generation directives
Related concepts
MFS Generation
Related reference
Project Properties - MFS Settings


PSBGEN Directives

  • CLS
    Clears the screen before starting the utility.
  • COPYEXT
    Specifies the copybook extension to be used when generating the complete copybook name for a DBD, MFS or PSB COPY statement.
  • DEFAULTEXT
    Specifies the default file extension added to the input file name when no extension is specified.
  • ECHO
    Controls the interaction with the DBDGEN, MFSGEN and PSBGEN utilities.
  • EXCLUPDT
    Opens the output files for exclusive use by this instance of DBDGEN and no other task can read or update the DBDGEN files until DBDGEN completes.
  • IMSLIBNO
    Specifies which IMS Load library directory in Workgroups is updated when multiple IMS Load Library directories are used.
  • LIST
    Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
  • VERIFY
    Runs the PSB Verify utility upon successful completion of PSBGEN.
Parent topic: mfims generation directives
Related concepts
PSB Generation
Related reference
Project Properties - PSB Settings


mfims IMSDBU

  • mfims imsdbu command
  • mfims imsdbu functions
  • mfims imsdbu directives
Parent topic: mfims Command-line Utility
Related concepts
IMS Database Features
Accessing IMSDBU


mfims imsdbu command

The mfims imsdbu command enables you to run the IMSDBU utility from the command line.

Syntax:

mfims imsdbu function-id {database-name|filename}[directives]

Parameters:

function-id
An identifier denoting the function you want to perform. One of:
function-id | Function
ADD | Add
DEL | Delete
LOAD | Load
MAKE | Makelist
PTRU | PtrUpdate
RECV | Recover
REOR | Reorganize
ROLB | Rollback
RUN | Runlist
UNLO | Unload
USEQ | Useq
Zero | Zeroload

For complete information on each IMSDBU function, see IMSDBU functions.

database-name
The name of a database on which the function operates.
filename
The name of a file that supplies information to the function.
directives
Directives for this function. The help for each function includes full information on the directives it can take. For complete information on each mfsims imsdbu directive, see mfsims imsdbu directives.

Comments:

You can combine a series of commands in an operating system command file. IMSDBU also supports its own Runlist command files. These are similar to operating system command files but allow you to process a series of functions as a group. A combination of operating system commands and Runlist files provides a great deal of flexibility for automating repetitive functions.

The Rollback (ROLB) function does not require that you specify the database-name or the filename.

Parent topic: mfims IMSDBU
Related concepts
IMS Database Utility (IMSDBU)
Accessing IMSDBU


mfims imsdbu functions

The mfims imsdbu command and the IMSDBUJCL Utility use some or all of the following IMSDBU functions:

  • Add function
    Add to or refresh segments in a database from an input data file.
  • Delete function
    Delete segments in a database.
  • Load function
    Initializes a database and loads it from an input data file.
  • Makelist function
    Generates a Runlist command file.
  • PtrUpdate function
    Validates and establishes the pointers that maintain logical relationships.
  • Recover function
    Recover one or more databases using recovery log files.
  • Reorganize function
    Provides a simple mechanism for reorganizing a database or set of logically related databases.
  • Rollback function
    Roll back corrupted databases.
  • Runlist function
    Executes IMSDBU functions listed in a Runlist command file.
  • Unload function
    Writes database segment data to a sequential output file.
  • Useq function
    Unloads all sequential dependent segments (SDEPs) from a Fast Path DEDB.
  • Zeroload function
    Create database data files and prime them for use.
Parent topic: mfims IMSDBU
Related concepts
Accessing IMSDBU
Related reference
MFDBUJCL Utility
mfims imsdbu command


Add function

Add to or refresh segments in a database from an input data file.

The Add function adds segments to a database from an input data file. Its purpose is to add additional data to a database and/or to refresh some of the segments in the database. Therefore, do not attempt to use the Add function to load database, as part of a database reorganization, or for reloading a database after changing the DBD definition.

The Add function does not re-initialize the database and does not perform a Zeroload of the database.

Syntax - Command Line

mfims imsdbu ADD {database-name|filename}
     [[NO]CLS]
     [[NO]COMPRESS[(program)]]
     [DATA(position)]
     [DSN(filespec)]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [LAYOUT(type)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [LRECL(length)]
     [PROGRESS(no-of-segments)]
     [RECFM(format)]
     [[NO]REPLACE]
     [[NO]SEGEXIT[(program)]]
     [SEGM(position)]

Syntax - JCL

//ADD EXEC PGM=MFDBUJCL,PARM='ADD,database-name,{dataset-name | catalog-name}'
//SYSOUT   DD SYSOUT=*
//INPUT    DD  DSN=input-dataset,DISP=SHR

Parameters - Command Line

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
COMPRESS
Enables or disables the expansion of the input data file records.
Default: NOCOMPRESS
Sub-parameter
program The name of a compression/expansion routine to use instead of the system-supplied routine.
Syntax Rules
  1. Use COMPRESS only when LAYOUT(G) is specified. COMPRESS is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
  2. Specifying COMPRESS with no program name causes decompression using the CBLDCIMS program (built into the MFIMS software libraries). You can override the name of the compression/expansion routine by specifying a user-written program name.
DATA
Specifies the starting position of the segment data in the data record.
Default: DATA(9)
Sub-parameter
position The starting position of the segment data within the data record.
Syntax Rules
  1. A value of 1 corresponds to the first byte of the record data.
  2. When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value.
  3. Use DATA only when LAYOUT(G) is specified. COMPRESS is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
DSN
Specifies the dataset name of the input file containing the segment data.
Default: DSN(*.DBU)
Sub-parameter
filespec The dataset name of the input file containing the segment data.
Syntax Rules
  1. If you specify the base name of filespec as an asterisk (*) it is replaced by the DBD name.
  2. Use unique extensions for the input file names. This is enforced even if the database data files are in a different directory than the input file.
  3. The input dataset resides in the current directory unless you specify a drive and/or directory.
  4. The input file name, not including the drive and directory, must not be the same as the name of the files for the database. For example, the data files for a database named MYDBD would be MYDBD.DAT and MYDBD.IDX, and the input file name cannot be either of these file names.
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LAYOUT
Specifies the type of the input or output file.
Default: LAYOUT(D)
Sub-parameter
type The type of input file. One of:
D
The input file is an IMSDBU file layout. No additional directives are required to describe the input file.
G
The input file is a generic layout. Additional directives are required to describe the input file and its contents.
I
The input file is an IBM format. No additional directives are required to describe the input file.
S
The input file is a sequential file. Additional directives are required to describe the input file and its contents.
Syntax Rules
  1. The additional directives required for the G and S parameters are RECFM, LRECL, SEGM, and DATA.
General Rules
  1. LAYOUT(I) output files are not suitable for uploading to the mainframe and reloading IMS/ESA databases.
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
LRECL
Specifies the length for fixed length generic layout input records.
Default: LRECL(0)
Sub-parameter
length The length for fixed length generic layout input records.
Syntax Rules
  1. LRECL is required when loading from a fixed-length generic file; that is, when LAYOUT(G) is specified.
  2. LRECL is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.
RECFM
Specifies the format of the input or output records.
Default: RECFM(V)
Sub-parameter
format The format of the input records. One of:
V
Records are variable length. With LAYOUT(G), each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility. With LAYOUT(S), files are in Micro Focus record sequential format.
F
Records are a fixed length. Requires
Syntax Rules
  1. Use RECFM only when LAYOUT(G) or LAYOUT(S) is specified.
  2. RECFM is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.
  3. When format is set to V and LAYOUT(G) is specified, each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility.
  4. When format is set to V and LAYOUT(S) is specified, files are in Micro Focus record sequential format.
  5. When format is set to F, you must also specify LRECL to provide the record length.
REPLACE
Specifies how duplicate root segments are to be processed. When adding segments to a database, a root collision occurs when the key of a root segment in the input file already exists in the database. REPLACE causes the existing database root segment (and its children) to be deleted and the segments from the input file to be inserted.
Default: NOREPLACE
Syntax Rules
  1. NOREPLACE causes the segments in the input file to be ignored and the existing database segments to be left as they were.
SEGEXIT
Specifies the name of a user-supplied exit program that can be used to control selection and modification of segment data during the add process.
Default: NOSEGEXIT
Sub-parameter
program The name of the exit program to use.
Syntax Rules
  1. NOSEGEXIT disables this exit.
SEGM
Specifies the starting position of the 8-byte segment name in the data record.
Default: SEGM(1)
Sub-parameter
position The starting position of the 8-byte segment name in the data record.
Syntax Rules
  1. A value of 1 corresponds to the first byte of the record data.
  2. Use the SEGM directive only when LAYOUT(G) is specified.
  3. SEGM is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
  4. When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value. That is, if the segment name is the first field following the LL field in a variable length file, specify 1 for the SEGM value.
General Rules
  1. When loading Fast Path databases that use LTERM keys (related or non-related), the SEGM directive indicates the position of the LTERM name and not the segment name.

Parameters - JCL

database-name
The name of a database on which the function operates.
dataset-name
Dataset name of the data to be added.
catalog-name
If the dataset containing the data to be added is in the JCL catalog, then you can specify the catalog name instead of the dataset name.
input-dataset
The dataset containing input data.

Inputs

There are a variety of input file formats supported for the Add function. See the Specialized and Generic Load Inputs of the IMS Database Utility (IMSDBU) topic for complete details of the different formats.

The database for the segment Add function must be an existing primary physical database. It must be either Zeroloaded or previously loaded with data. An Add should not be run for any other kinds of databases. An error message results if you attempt an Add function on one of the following databases:

  • The primary index for a HIDAM database. A primary index database is not required. The .IDX component of an MFIMS database is the equivalent of this index and is modified automatically when adding segments to the primary database.
  • Secondary index databases. These are modified automatically when adding segments to the primary database they index.
  • Databases defined as ACCESS=LOGICAL. The physical databases contain the required pointers to support logical relationships.
  • GSAM databases. The Add function does not support GSAM databases.
  • A database which has not been Zeroloaded or previously loaded with data.

Exclusive use databases may be used with the Add function. IMSDBU does not support adding segments to User Exit databases. The DBUTIL utility can be used for adding segments to User Exit databases.

Outputs

The database data files are modified by this function. Any secondary index databases are also modified. If the database contains logical children definitions, the PtrUpdate function must be run before the database can be accessed by an application program.

Segments

To add segments to a database that contains logical relationships requires that the PtrUpdate function also be run against it. This resolves the links between logical children segments and their logical parents. When adding segments to several logically related databases, we recommend that you first perform the Add function against each database, and then run the PtrUpdate function against each database.

The Makelist function can assist in identifying the databases included in the set of logically related databases.

Parent topic: mfims imsdbu functions
Related concepts
IMS Database Utility (IMSDBU)
Related reference
MFDBUJCL Utility
COMPRESS
DATA
DSN
LAYOUT
LRECL
RECFM
REPLACE
SEGEXIT
SEGM


Delete function

Delete segments in a database.

The Delete function deletes segments in a database.

Syntax

mfims imsdbu DEL {database-name|filename}
     [[NO]CLS]
     DSN(filespec)
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [PROGRESS(no-of-segments)]

Parameters

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
DSN
Specifies the name of the data set you want to delete.
Default: None
Sub-parameter
filespec The name of the data set file you want to delete.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the current directory is the default.
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Syntax Rules

  1. DEL is available only in a Runlist command file.

General Rules

  1. DEL is used by the Reorganize function to delete the file containing the unloaded segment data.
Parent topic: mfims imsdbu functions


Load function

Initializes a database and loads it from an input data file.

The Load function initializes a database and loads it from an input data file. It can be used for initial loading of a database, as part of a database reorganization, or for reloading a database after changing the DBD definition.

Warning: The Load function automatically performs a Zeroload. Zeroloading an existing database re-initializes the database and all data is lost.

Syntax - Command Line

mfims imsdbu LOAD {database-name|filename}
     [[NO]CLS]
     [[NO]COMPRESS[(program)]]
     [DATA(position)]
     [DSN(filespec)]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [LAYOUT(type)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [LRECL(length)]
     [PROGRESS(no-of-segments)]
     [RECFM(format)]
     [[NO]SEGEXIT[(program)]]
     [SEGM(position)]

Syntax - JCL

//LOAD     EXEC PGM=MFDBUJCL,PARM='LOAD,database-name,{dataset-name | catalog-name}'
//SYSOUT   DD  SYSOUT=*
//INPUT    DD  DSN=input-dataset,DISP=SHR

Parameters - Command Line

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
DSN
Specifies the dataset name of the input file containing the segment data.
Default: DSN(*.DBU)
Sub-parameter
filespec The dataset name of the input file containing the segment data.
Syntax Rules
  1. If you specify the base name of filespec as an asterisk (*) it is replaced by the DBD name.
  2. Use unique extensions for the input file names. This is enforced even if the database data files are in a different directory than the input file.
  3. The input dataset resides in the current directory unless you specify a drive and/or directory.
  4. The input file name, not including the drive and directory, must not be the same as the name of the files for the database. For example, the data files for a database named MYDBD would be MYDBD.DAT and MYDBD.IDX, and the input file name cannot be either of these file names.
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LAYOUT
Specifies the type of the input or output file.
Default: LAYOUT(D)
Sub-parameter
type The type of input file. One of:
D
The input file is an IMSDBU file layout. No additional directives are required to describe the input file.
G
The input file is a generic layout. Additional directives are required to describe the input file and its contents.
I
The input file is an IBM format. No additional directives are required to describe the input file.
S
The input file is a sequential file. Additional directives are required to describe the input file and its contents.
Syntax Rules
  1. The additional directives required for the G and S parameters are RECFM, LRECL, SEGM, and DATA.
General Rules
  1. LAYOUT(I) output files are not suitable for uploading to the mainframe and reloading IMS/ESA databases.
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
LRECL
Specifies the length for fixed length generic layout input records.
Default: LRECL(0)
Sub-parameter
length The length for fixed length generic layout input records.
Syntax Rules
  1. LRECL is required when loading from a fixed-length generic file; that is, when LAYOUT(G) is specified.
  2. LRECL is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.
RECFM
Specifies the format of the input or output records.
Default: RECFM(V)
Sub-parameter
format The format of the input records. One of:
V
Records are variable length. With LAYOUT(G), each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility. With LAYOUT(S), files are in Micro Focus record sequential format.
F
Records are a fixed length. Requires
Syntax Rules
  1. Use RECFM only when LAYOUT(G) or LAYOUT(S) is specified.
  2. RECFM is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.
  3. When format is set to V and LAYOUT(G) is specified, each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility.
  4. When format is set to V and LAYOUT(S) is specified, files are in Micro Focus record sequential format.
  5. When format is set to F, you must also specify LRECL to provide the record length.
SEGEXIT
Specifies the name of a user-supplied exit program that can be used to control selection and modification of segment data during the add process.
Default: NOSEGEXIT
Sub-parameter
program The name of the exit program to use.
Syntax Rules
  1. NOSEGEXIT disables this exit.
SEGM
Specifies the starting position of the 8-byte segment name in the data record.
Default: SEGM(1)
Sub-parameter
position The starting position of the 8-byte segment name in the data record.
Syntax Rules
  1. A value of 1 corresponds to the first byte of the record data.
  2. Use the SEGM directive only when LAYOUT(G) is specified.
  3. SEGM is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
  4. When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value. That is, if the segment name is the first field following the LL field in a variable length file, specify 1 for the SEGM value.
General Rules
  1. When loading GSAM files, the SEGM value is ignored.
  2. When loading Fast Path databases which use LTERM keys (related or non-related), the SEGM directive indicates the position of the LTERM name and not the segment name.

Parameters - JCL

database-name
The name of a database on which the function operates.
dataset-name
Dataset name of the data to be loaded.
catalog-name
If the dataset containing the data to be loaded is in the JCL catalog, then you can specify the catalog name instead of the dataset name.
input-dataset
The dataset containing input data.

Inputs

There are a variety of input file formats supported for loading databases.

The database to be loaded must be a primary physical DBD or GSAM DBD which has been defined using DBDGEN. An automatic Zeroload is performed for physical databases. GSAM databases do not require the Zeroload step. A Load is not required, and should not be run, for any other kinds of databases. An error message results if you attempt to Load one of the following databases:

  • The primary index for a HIDAM database. A primary index database is not required. The .IDX component of an MFIMS database is the equivalent of this index and is created automatically when loading the primary database.
  • Secondary index databases. These are created automatically when loading the primary database they index. A secondary index DBD which defines non-unique keys must be Genned prior to performing a Load for the primary database. When loading a database which contains segment data, any 'user data' in the index will be lost.
  • Databases defined as ACCESS=LOGICAL. The physical databases contain the required pointers to support logical relationships.

Exclusive use databases can be loaded. IMSDBU does not support loading of User Exit databases. The DBUTIL utility can be used for loading User Exit databases.

Outputs

The database data files are created and loaded by this function. Any secondary index databases are also created and loaded. If the database contains logical children definitions, the PtrUpdate function must be run before the database can be accessed by an application program.

Logically Related Databases

Loading logically related databases requires multiple steps that must be performed in a fixed sequence. In most cases, this involves multiple databases. The Makelist function can assist in creating the steps required to load a set of logically related databases.

The Load function performs a physical load of the segment data. The Load function does not process logical relationships. Logical children are connected to their logical parents by the PtrUpdate function. PtrUpdate also connects or establishes paired logical child relationships. A database that contains logical children segments cannot be accessed by an application until the PtrUpdate completes.

Parent topic: mfims imsdbu functions
Related concepts
IMSDBU Exits
IMS and GSAM Databases
Prepare the MFDEMO Application
Load the IMS database
Database Load Conversion Issues
Related tasks
To load an IMS database
Related reference
MFDBUJCL Utility
SXRBAFORMAT
COMPRESS
DATA
DSN
LAYOUT
LRECL
RECFM
SEGEXIT
SEGM


Makelist function

Generates a Runlist command file.

Loading logically related databases involves multiple steps that must be performed in a fixed sequence. The Makelist function simplifies the process of creating these steps. Makelist generates a Runlist command file containing the steps required to load a set of logically related databases. You perform Runlist to execute the steps in the generated command file.

Syntax

mfims imsdbu MAKE {database-name|filename}
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [MAKELISTDSN(output-dsn)]
     [PROGRESS(no-of-segments)]

Parameters

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
MAKELISTDSN
Specifies the dataset name of the output file for the IMSDBU commands.
Default: MAKELISTDSN(MAKELIST.RUN)
Sub-parameter
output-dsn The dataset name of the output file for the IMSDBU commands.
General Rules
  1. This output file is written to the current directory if no drive or directory is provided.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Input

The input is the starting physical DBD name defined using DBDGEN. From this DBD, logical relationships are followed to create the set of logically related databases. The DBDGEN files are the input to Makelist.

Output

The output is a Runlist command file. Its name and location are controlled by the MAKELISTDSN directive. It is an ASCII text file. Any text editor can be used to modify this file for changing directives or file names.

Logically Related Databases

Makelist begins by creating a list of logically related databases. The DBDGEN definitions are used to determine the relationships. Once the set is determined, it creates the required load and logical pointer update steps to load the databases.

Makelist builds the list by starting with a single DBD name. The databases referenced by logical children in the input DBD are added to the list. These newly-added DBDs are scanned and databases referenced by their logical children are also added to the list. This continues until all of the relationships are located. Makelist requires that all of the physical DBDs have been genned. If a DBD referenced by a logical child is not found, an error message is issued and Makelist terminates. The error message includes the required DBD name. You should gen the DBD and re-run Makelist.

Databases referenced by logical children also need to be genned and at least zeroloaded. That is, if you need access to a database with a logical child, you must also gen the logical parent database and at least zeroload it.

However, if you need a database that contains only a logical parent for a unidirectional relationship, the database containing the logical child is not required. Thus, you may get different results from Makelist depending on the DBD name you start with.

You should review the output of Makelist for databases that define unidirectional logical relationships. You could also run Makelist multiple times with different initial DBD names and merge the output Runlist files. Database load steps can also be added by editing the Runlist command file manually. This is an ASCII text file and can be edited in any text editor. For any required logical child database which was not located, add a Load step at the top of the file and a PtrUpdate step at the bottom. All PtrUpdate steps should follow the Load steps.

The following uni-direction examples consider three logically related databases - 'A', 'B', and 'C'. Database A contains a logical child segment which defines a uni-directional logical relationship to database B. Database B contains the logical parent for database A's logical child. A second uni-directional logical relationship is defined between databases B and C. Database B contains a logical child segment which points to the logical parent in database C. In other words, database A points to database B and database B points to database C. A is related to B and B is related to C by uni-directional relationships.

Example 1

If database A is used as the starting DBD name, databases B and C are both included. Database C contains no logical child segments and does not require a pointer update step. The sequence of the load steps is:

LOAD A DSN(...
LOAD B DSN(...
LOAD C DSN(...
PTRUPDATE A ...
PTRUPDATE B ...

Example 2

If database B is used as the starting DBD name, only database C is included. Database C contains no logical child segments and does not require a pointer update step. The sequence of the load steps is:

LOAD B DSN(...
LOAD C DSN(...
PTRUPDATE B ...

If your application requires the use of database A, a Load and PtrUpdate step must be added manually. MFIMS does not require database A if you only access databases B and C. The Load step for A must be placed prior to the first PtrUpdate step. The PtrUpdate step can be placed anywhere after the last Load step.

Example 3

If database C is used as the starting DBD name, databases A and B are not included. The load step is simply:

LOAD C DSN(...

If your application requires the use of database A and B, the Load and PtrUpdate step must be added manually. You do not need databases A or B if you only need access to database C. The steps to load all three databases is shown in Example 1.

Parent topic: mfims imsdbu functions
Related reference
MAKELISTDSN


PtrUpdate function

Validates and establishes the pointers that maintain logical relationships.

PtrUpdate validates and establishes the pointers that maintain logical relationships. It connects logical children to their logical parents and matches paired logical children to each other. If logical child segments are loaded to a database, a PtrUpdate is required before making any calls to the database. A PtrUpdate is run after loading the physical databases containing the logical children and their logical parents.

Syntax

mfims imsdbu PTRU {database-name|filename}
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [PROGRESS(no-of-segments)]

Parameters

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Input

The input is the DBD name of a physical DBD that defines logical children segments. The IMSDBU Load function must have been performed for this DBD name and for any databases containing logical parents for the logical children. A database which defines logical children does not require PtrUpdate if no logical child segments were loaded to the database.

An error message is issued if you attempt to run PtrUpdate for:

  • A DBD which does not define any logical children
  • A DBD name which was not input to the IMSDBU Load function

A PtrUpdate can be run for exclusive use databases. IMSDBU does not support PtrUpdate or Load for User Exit databases.

Output

Updated database data files for the input DBD name and any database referenced by logical child occurrences in this database. Once PtrUpdate completes, the databases can be accessed from application programs using any of the supported physical and logical access paths.

Segments

The PtrUpdate function creates the pointers that establish logical relationships. Logical pointers are created between a logical child and its logical parent and between paired logical children. If two of these logically related segments cannot be connected, an adjustment is made. The adjustments ensure that all of the logical pointers in a database refer to valid segments.

The two adjustments that might be performed are:

  • A logical child segment is deleted when its logical parent segment does not exist. When this occurs, the logical child segment data and the logical parent concatenated key are included in the detail report listing.
  • If a paired segment to a logical child does not exist, it is created. The paired logical child is created in the same way it would be created for an application ISRT call.

The number of segments deleted and created because of these adjustments is included in the detail report listing. The number of logical child segments updated with a valid logical parent pointer is also included in this report. These counts are listed by segment name.

Parent topic: mfims imsdbu functions
Related reference
MFDBUJCL Utility


Recover function

Recover one or more databases using recovery log files.
The Recover function is a command-line version of the Recovery Utility, which is part of IMS Forward Recovery. It recovers a single database specified by name on the command line, or a list of databases specified in an input file. When complete, the output file shows the result of the recovery process. For complete details on the Recovery Utility, see Recovery Utility.
Important:
  • Before running the Recover function, copy the image database to the current directory or to the directory specified by the ES_IMDAT environment variable.
  • To use the Recover function, you do not need an active enterprise server because no JCL is required.

Syntax

mfims imsdbu RECV {database-name|filename}
     [PITR(YYMMDDhhmmssmm)]
     [ABEND(NO|YES)]
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     SERVER(server-name)
     [TLOGPATH(path)]

Parameters

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
PITR
Point-in-time recovery.
Sub-parameter
YYMMDDhhmmssmm The exact point in time at which you want to recover the database, represented here as two digits each for Year, Month, Day, hour, minute, second, and millisecond. Character delimiters are optional and unrestricted with regard to number and placement up to a limit of 25 characters in total.

To be valid, the date and time provided must match the date time of a commit comp as recorded in a TLOG file. For information on viewing this information in a TLOG file, see the TLOG Files topic.

ABEND
Determines behavior in the event of a date discrepancy found in the recovery log files.
Default: ABEND(NO)
Sub-parameters
NO | The recovery process continues even in the event of a date discrepancy found in the recovery log files.
YES | Recovery aborts in the event of a date discrepancy found in the recovery log files.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes recovery statistics having to do with the number of updates applied to each database, per each recovery log processed.
Default: RECOVER(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
SERVER
Specifies the name of an enterprise server.
Default: None
Sub-parameter
server-name The name of the enterprise server that was active when the recovery log files were created.
TLOGPATH
Specifies the location of the recovery log files.
Default: Checks the current directory first, and then the path specified by the ES_IMS_TLOG_PATH environment variable.
Sub-parameter
path The path to the location where the recovery log files reside.
Parent topic: mfims imsdbu functions
Related concepts
Automatic Backward Recovery Process
Recovery Utility
Invoking Backward Recovery from JCL
TLOG Files
Related reference
ABEND
SERVER
TLOGPATH


Reorganize function

Provides a simple mechanism for reorganizing a database or set of logically related databases.

The Reorganize function provides a simple mechanism for reorganizing a database or set of logically related databases. This automates the creation and running of separate Unload and Load functions. PtrUpdate steps are run automatically for any database containing logical children.

Syntax

mfims imsdbu REOR {database-name|filename}
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [PROGRESS(no-of-segments)]

Parameters

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Input

The database name input to the Reorganize function must be a primary physical database defined using DBDGEN. This DBD name must be a type of database which is supported by the Load function. See the Load Function for the database qualifications.

The database data files are read and updated by Reorganize using the Unload, Load, and PtrUpdate functions.

Secondary index databases do not need to be available when starting reorganization. They are recreated during the Load step.

The Unload function does not require the logical parent databases when unloading its logical child database. However, Reorganize uses Makelist to create Unload steps for each related database. All of the databases that are logically related must be available before starting Reorganize.

Output

Database unload work files containing the segment data are created during this process. These files are named using the DBD name with a .org extension. They are created in the project listing directory. For reference, they are an Unload file created with the directives LAYOUT(D) and COMPRESSION(CBLDC001), and are deleted upon successful completion of the Reorganize.

A Runlist command file is created with the name DBUREORG.RUN. It contains the steps to perform the reorganization. It is always placed in the current directory and is not deleted upon successful completion. You can use this file as a model for creating your own reorganization scripts. Be sure to copy it to a new name as the next Reorganize function recreates it. You might need this file to recover from an incomplete reorganization.

Processing

When a segment is deleted, the space it occupied is reused by the next segment inserted which is not larger than the deleted segment. However, if new segments are not inserted which 'fit' this deleted space, the space is not reclaimed until you reorganize the database. Also, as a database is updated, the internal pointers can become fragmented which reduces performance. A reorganization will restore the performance to that of a newly loaded database.

The Reorganize function combines the functions of the Load, Unload, PtrUpdate, and Delete functions to perform the reorganization. It creates the required steps using an advanced feature of the Makelist function. This Makelist feature is only available when using the callable API interface to IMSDBU. The interactive and command-line interfaces for Makelist only supports creating steps for loading databases. The callable interface adds the ability to create the steps for reorganizing databases.

The reorganization for a database with no logical children is simply to unload the database to a sequential file and load it using the sequential file.

Reorganizing a database containing logical children results in reorganizing it and all of its related databases. The steps to reorganize these databases are:

  1. Identify all of the related databases
  2. Unload each of the databases to a sequential file
  3. Load each of the databases from the sequential unload
  4. Run PtrUpdate for each database with logical children definitions
  5. Delete the sequential files created in step 2

Identifying the related databases is done by Makelist. The process Makelist uses to create this list is the same for Reorganize as it is for Load.

The sequential unload files are not deleted until all of the Load and PtrUpdate processing is complete. Although this requires more disk space than deleting them after the Load, it provides for restarting if a subsequent Load or PtrUpdate step fails. If you need to conserve disk space, you can change the DBUREORG.RUN file to re-sequence the Delete commands and use Runlist to run the commands. You could also create your own Runlist command file or run the required functions in an operating system command file.

When the detailed report filename *.LST is used, a separate list file is created for each database involved in the reorganization. For a combined listing, specify the directives LIST(file-spec) and LISTOPEN(MOD).

Recovery

The easiest way to recover from a failed Reorganize function is to restore the original database data files from a backup copy. In the event that a backup copy is not available, recovery can be performed using the files produced by the reorganization. Failures can occur for several possible reasons. One example is running out of disk space.

In the event of a failure, an error message is issued and the process is terminated. The sequential file unloads are kept. These files may be required to complete the reorganization.

The first thing step is to determine the cause of the failure and correct it. The error message issued from the reorganization is written to the detail report listing. This message should provide enough information to determine the cause of the failure. In some cases, the IMSMTO.LOG will provide additional information about the failure.

The IMSDBU activity log will indicate all of the steps which were successful and the step which failed. If the failing step was an Unload, database recovery is not necessary. Just restart the Reorganize function after correcting the cause of the failure.

Compare the functions listed in the log to the reorganization command file DBUREORG.RUN to identify which step in the command file failed. Use a text editor to modify the command file and remove or comment out all of the steps which completed successfully. A step is commented out by placing an asterisk (*) in column 1. Use Runlist with the modified command file to complete the reorganization.

Parent topic: mfims imsdbu functions
Related reference
SXRBAFORMAT


Rollback function

Roll back corrupted databases.

The Rollback function is a command-line version of Automatic Backward Recovery for IMS databases. This function rolls back all corrupt databases. When complete, the output list file shows the results of the rollback.

Syntax

mfims imsdbu ROLB * TLOG(tlogName)
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]

Parameters

TLOG
Specifies the name of the TLOG file to be used for rollback.
Default: None
Sub-parameter
tlogName The name of the rollback TLOG file.
Syntax Rules
  1. tlogName can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the specified file in the current directory.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes rollback statistics.
Default: ROLLBACK(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  3. NOLIST suppresses the creation of the listing file.
  4. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  5. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  6. If no path is specified, the listing file is created in the current directory.
  7. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  8. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
Parent topic: mfims imsdbu functions
Related concepts
IMS Database Automatic Backward Recovery
TLOG Files
Automatic Backward Recovery Process
Invoking Backward Recovery from JCL
Related reference
TLOG


Runlist function

Executes IMSDBU functions listed in a Runlist command file.

The Runlist function executes IMSDBU functions listed in a Runlist command file. This file can be created manually with a text editor or generated by Makelist.

Syntax

mfims imsdbu RUN {database-name|filename}
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [PROGRESS(no-of-segments)]

Parameters

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Input

The name of the command file containing IMSDBU functions. This is an ASCII text file with each function specified on a separate line. The format of this record is:

function dbdname [directives]

An individual command may not span multiple lines. An asterisk (*) in column 1 indicates a comment line.

All of the IMSDBU functions can be listed in a Runlist file except for Reorganize and Runlist functions. Reorganize uses Runlist to perform the reorganization and Runlist executions cannot be nested.

Output

The output is the results of the functions which were successfully executed and the IMSDBU listing and log report files.

Processing

The functions listed in the Runlist command file are processed in series. The highest error level set by an individual step is returned as the ending return code by Runlist. If a step fails with a return code of 8 or higher, all remaining steps are canceled. The ending return code is set to the return code of the failed step.

When running IMSBDU from the command line, the function-id to use for the Runlist function is RUN.

Any directives entered for Runlist are passed to the functions that Runlist is executing. When processing functions using Runlist, the sequence for processing directives is:

  1. IMSDBU programmed defaults.
  2. Directives in the .INI file override the programmed defaults.
  3. When starting Runlist from the interactive screen, any directives from the Runlist entry screen override the previous directives.
  4. When starting Runlist from the command line, any directives entered on the Runlist command line override the previous directives.
  5. Directives specified for a function in the Runlist command file take precedence over all other directives.

The Makelist function adds directives to the function commands in its output Runlist command file. It only adds directives which are specific to a function. Any changes to the .INI file directives between the Makelist and the Runlist will not affect the function directives in the Runlist command file. Makelist does not add any common directives. For example, the LIST, LOG, and ECHO directives. The common directives used by Runlist are the ones active when starting Runlist - not when creating the command file using Makelist.

You can add common directives to the Runlist command file if you want to ensure that changes to the .INI file directives will not affect the operation of Runlist.

Recovery

In the event of a failure, an error message is issued and the Runlist is terminated. The remaining steps in the Runlist command file are not executed. You must determine the cause of the failure and correct it. The error message issued from Runlist is also written to the detail report file. This message should provide enough information to determine the cause of the failure. In some cases, the IMSMTO.LOG file will provide additional information.

The activity log indicates all of the Runlist steps which were successful and the step which failed. Use this to identify the step to restart from. Compare the functions listed in the log to the original Runlist file and identify which step failed.

Use a text editor to modify the Runlist file and remove or comment out all the steps which completed successfully. A step is commented out by placing an asterisk (*) in column 1 of that line.

Rerun Runlist with the modified Runlist command file.

Parent topic: mfims imsdbu functions


Unload function

Writes database segment data to a sequential output file.

The Unload function writes database segment data to a sequential output file. It can be used as part of a database reorganization, for unloading a database prior to changing the DBD definition, or to create a flat file of database segment data for other purposes.

Syntax - Command Line

mfims imsdbu UNLO {database-name|filename}
     [[NO]CLS]
     [[NO]COMPRESS[(program)]]
     [DATA(position)]
     [DSN(filespec)]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [LAYOUT(type)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [LRECL(length)]
     [PROGRESS(no-of-segments)]
     [RECFM(format)]
     [[NO]SEGEXIT[(program)]]
     [SEGM(position)]

Syntax - JCL

//UNLOAD EXEC PGM=MFDBUJCL,PARM='UNLOAD,database-name,{dataset-name | catalog-name}'
//SYSOUT    DD SYSOUT=*
//OUTPUT    DD DSN=output-dataset,DISP=SHR

Parameters - Command Line

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
COMPRESS
Enables or disables the expansion of the input data file records.
Default: NOCOMPRESS
Sub-parameter
program The name of a compression/expansion routine to use instead of the system-supplied routine.
Syntax Rules
  1. Use COMPRESS only when LAYOUT(G) is specified. COMPRESS is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
  2. Specifying COMPRESS with no program name causes decompression using the CBLDCIMS program (built into the MFIMS software libraries). You can override the name of the compression/expansion routine by specifying a user-written program name.
General Rules
  1. When using an Unload file for a subsequent Load, the COMPRESS directive used for unloading must also be used when loading. For the IMSDBU-specific LAYOUT(D) formats, this is automatic as the compression setting is stored in the unload file header record. For generic format unloads, ensure that the COMPRESS directive is set correctly to avoid data corruption.
DSN
Specifies the dataset name of the input file containing the segment data.
Default: DSN(*.DBU)
Sub-parameter
filespec The dataset name of the output for the segment data.
Syntax Rules
  1. If you specify the base name of filespec as an asterisk (*) it is replaced by the DBD name.
  2. Use unique extensions for the output file names. This is enforced even if the database data files are in a different directory than the output file.
  3. The output dataset resides in the current directory unless you specify a drive and/or directory.
  4. The output file name, not including the drive and directory, must not be the same as the name of the files for the database. For example, the data files for a database named MYDBD would be MYDBD.DAT and MYDBD.IDX, and the output file name cannot be either of these file names.
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LAYOUT
Specifies the type of the input or output file.
Default: LAYOUT(D)
Sub-parameter
type The type of output file. One of:
D
The output file is an IMSDBU file layout. No additional directives are required to describe the input file.
G
The output file is a generic layout. Additional directives are required to describe the input file and its contents.
I
The output file is an IBM format. No additional directives are required to describe the input file.
S
The output file is a sequential file. Additional directives are required to describe the input file and its contents.
Syntax Rules
  1. The additional directives required for the G and S parameters are RECFM, LRECL, SEGM, and DATA.
General Rules
  1. LAYOUT(I) output files are not suitable for uploading to the mainframe and reloading IMS/ESA databases.
  2. LAYOUT(I) automatically sets the directives RECFM(V), LRECL(0), SEGM(7), DATA(36) and NOCOMPRESS.
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
LRECL
Specifies the length for fixed length generic layout output records.
Default: LRECL(0)
Sub-parameter
length The length for fixed length generic layout output records.
Syntax Rules
  1. LRECL is required when loading from a fixed-length generic file; that is, when LAYOUT(G) is specified.
  2. LRECL is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
  3. LRECL(0) causes IMSDBU to assign the smallest possible value. The value used will appear in the detail report listing.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.
RECFM
Specifies the format of the input or output records.
Default: RECFM(V)
Sub-parameter
format The format of the input records. One of:
V
Records are variable length. With LAYOUT(G), each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility. With LAYOUT(S), files are in Micro Focus record sequential format.
F
Records are a fixed length. Requires
Syntax Rules
  1. Use RECFM only when LAYOUT(G) or LAYOUT(S) is specified.
  2. RECFM is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.
  3. When format is set to V and LAYOUT(G) is specified, each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility.
  4. When format is set to V and LAYOUT(S) is specified, files are in Micro Focus record sequential format.
  5. When format is set to F, you must also specify LRECL to provide the record length.
SEGEXIT
Specifies the name of a user-supplied exit program that can be used to control selection and modification of segment data during the add process.
Default: NOSEGEXIT
Sub-parameter
program The name of the exit program to use.
Syntax Rules
  1. NOSEGEXIT disables this exit.
SEGM
Specifies the starting position of the 8-byte segment name in the data record.
Default: SEGM(1)
Sub-parameter
position The starting position of the 8-byte segment name in the data record.
Syntax Rules
  1. A value of 1 corresponds to the first byte of the record data.
  2. Use the SEGM directive only when LAYOUT(G) or LAYOUT(S) is specified.
  3. SEGM is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.
  4. When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value. That is, if the segment name is the first field following the LL field in a variable length file, specify 1 for the SEGM value.
General Rules
  1. When loading GSAM files, the SEGM value is ignored.
  2. When loading Fast Path databases which use LTERM keys (related or non-related), the SEGM directive indicates the position of the LTERM name and not the segment name.

Parameters - JCL

database-name
The name of a database on which the function operates.
dataset-name
Dataset name of the data to be unloaded.
catalog-name
If the dataset containing the data to be unloaded is in the JCL catalog, then you can specify the catalog name instead of the dataset name.
output-dataset
The dataset containing output data.

Input

The database to be unloaded must be a primary physical DBD or GSAM DBD which has been defined using DBDGEN. The data files for secondary index databases are not required by Unload. When unloading databases containing logical children, the database files for the logical parents is not required. An error message will result if you attempt to unload one of the following databases:

  • The primary index for a HIDAM database.
  • Secondary index databases. If you need to extract 'user data' from a secondary index, you can use the DBUTIL utility or develop your own program.
  • Databases defined as ACCESS=LOGICAL. IMSDBU manages logical relationships using the physical databases. If you need to unload data using a logical DBD, you can use the DBUTIL utility or develop your own program.

User Exit program Database Catalog types cannot be unloaded by IMSDBU. Unload is supported for single-user exclusive use databases and shared read-only databases. The DBUTIL utility can unload User Exit databases.

Output

There is a variety of output file formats supported for unloading databases. See the Specialized and Generic Load Inputs of the IMS Database Utility (IMSDBU) topic for complete details of the different formats. Any of the formats supported by the Load function can be created using Unload.

Parent topic: mfims imsdbu functions
Related concepts
IMSDBU Exits
IMS and GSAM Databases
IMS Database Utility (IMSDBU)
Related reference
MFDBUJCL Utility
COMPRESS
DATA
DSN
LAYOUT
LRECL
RECFM
SEGEXIT
SEGM


Useq function

Unloads all sequential dependent segments (SDEPs) from a Fast Path DEDB.

The Useq function unloads all sequential dependent segments (SDEPs) from a Fast Path DEDB. The unload file contains the segment data and the date and time the segment was inserted into the database. This file can be sorted for chronological processing.

Syntax

mfims imsdbu USEQ {database-name|filename}
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [PROGRESS(no-of-segments)]

Parameters

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Input

The DEDB database data files are input to this function. The DEDB must have an SDEP segment definition. An error message is issued if a Useq function is attempted for any other kind of database.

The SDEP unload cannot be performed for User Exit Program Database Catalog types. IMSDBU supports the Useq function for single-user exclusive use databases and shared read-only databases.

Output

The data file containing the SDEP segments. This is a fixed length record sequential file. The LRECL is automatically set to the length of the SDEP segment plus 16 bytes. The LRECL used is written to the detail report file.

The first 8 bytes of the record is a date/time stamp followed by the 8-character SDEP segment name followed by the segment data. The date/time stamp is a 3-byte unsigned packed decimal Julian date field and a 5-byte unsigned packed decimal time field.

Parent topic: mfims imsdbu functions
Related reference
DSN


Zeroload function

Create database data files and prime them for use.

The Zeroload function creates the database data files and primes them for use. The database data files contain the segment data and pointers for the database. A database must be Zeroloaded before an application can issue calls against it. An automatic Zeroload is performed by the IMSDBU Load function prior to loading the data. A Zeroload can also be performed by the stand-alone Zeroload utility or DBUTIL.

Warning: Zeroloading an existing database reinitializes the database and causes any data to be lost.

Syntax - Command Line

mfims imsdbu ZERO {database-name|filename}
     [[NO]CLS]
     [ECHO(keyword,msglvl,stoplvl
     [[NO]INI(filespec)]
     [[NO]LIST(filespec)]
     [LISTOPEN(disp)]
     [[NO]LOG(filespec)]
     [PROGRESS(no-of-segments)]

Syntax - JCL

ZERO     EXEC PGM=MFDBUJCL,PARM='ZEROLOAD,database-name'
//SYSOUT     DD SYSOUT=*

Parameters - Command Line

database-name
The name of a database on which the function operates.
filename
The name of a file containing a list of databases on which the function operates.
CLS
Clears the screen before starting the utility. NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.
Default: NOCLS
ECHO
Controls the display of and interaction with the messages displayed by IMSDBU.
Default: ECHO(MSGS,4,8)
Sub-parameters
keyword The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl | A value from 4 through 20 to indicate the severity of messages to display.1
stoplvl | A value from 4 through 20 to indicate the severity of messages to stop for user input. 1
1 Can take the following values:
Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
INI
Specifies the default directives file.
Default: None
Sub-parameter
filespec The name and location of the .INI file containing directives that override the IMSDBU programmed defaults.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.
  2. Directives listed in the .INI file override the IMSDBU programmed defaults.
  3. Directives entered on the command line or interactive screen override directives in the .INI file.
  4. Specifying NOINI prevents any .INI file from overriding the programmed defaults.
  5. If you specify an .INI file that does not exist, the programmed default directives are used as if NOINI were specified.
General Rules
  1. An .INI file is an ASCII text file containing a heading, [IMSDBU] on line 1, starting in column 1, followed by a list of mfims imsdbu directives; one directive per line. A line is terminated by a return or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:
    [IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
LIST
Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Default: LIST(*.LST)
Sub-parameter
filespec The name and location to use for the listing file.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU creates the listing file in the current directory.
  2. NOLIST suppresses the creation of the listing file.
  3. To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.
  4. Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory.
  5. If no path is specified, the listing file is created in the current directory.
  6. If you specify the base name of filespec as an asterisk (*), it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions that can operate on multiple databases. It also assists in maintaining historical detailed reports by DBD name.
  7. Specifying LIST with no filespec is equivalent to specifying LIST(*.LST).
LISTOPEN
Controls the open disposition of the detail listing file.
Default: LISTOPEN(NEW)
Sub-parameter
disp The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.
Syntax Rules
  1. LISTOPEN is ignored when NOLIST is specified.
LOG
Specifies the IMSDBU activity log, which shows the ending message status for each function.
Default: LOG(IMSDBU.LOG)
Sub-parameter
filespec The name and location of the file to use as the IMSDBU activity log.
Syntax Rules
  1. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is created in the current directory.
  2. Specifying NOLOG suppresses the log file output.
General Rules
  1. The log file is created if it does not exist.
  2. The log file is historical with the most recent entries written to the end of the file.
  3. As the log file grows in size over time, it might require deletion periodically.
PROGRESS
Controls the frequency of progress reporting.
Default: PROGRESS(200)
Sub-parameter
no-of-segments A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.
Syntax Rules
  1. We recommend that you do not reduce the number of segments specified to a value below its default of 200. Very small values measurably reduce the performance of the database function.
  2. For relatively fast systems, setting the value higher (such as to 1000 or larger) might improve performance slightly.
General Rules
  1. The progress message could show the number of segments processed, or the percentage complete and an estimate of the time remaining.

Parameters - JCL

database-name
The name of a database on which the function operates.

Input

The input to a Zeroload function is the name of a primary physical DBD which has been defined using DBDGEN. A Zeroload is not required, and should not be run, for any other kinds of databases.

Exclusive use databases can be Zeroloaded. Shared read-only, Remote IMS, and User Exit databases cannot be Zeroloaded. An attempt to run a Zeroload for an incorrect Database Catalog type will result in an error.

An error message is issued if you attempt to Zeroload the following databases:

  • The primary index for a HIDAM database. A primary index database is not required. The .IDX component of an MFIMS database is the equivalent of a primary index.
  • Secondary index databases. These are created automatically when Zeroloading the primary database they index. A secondary index DBD which defines non-unique keys must be genned before Zeroloading the primary database.
  • Databases defined as ACCESS=LOGICAL. The physical databases contain the required pointers to support logical relationships.
  • GSAM databases. See the GSAM topic for complete details for GSAM databases.

Output

The output from a Zeroload function is the set of data files for the primary database and any secondary indexes defined. Any database calls can be made against a Zeroloaded database. A PCB with processing option 'L' is not required to load an initial segment to a database.

Zeroload Database Names

After performing a Zeroload, the output dbdname.DAT and .IDX files are the initialized data files for the database segment data and segment pointers. Exclusive use database data files reside in the location indicated by the exclusive use setting in the IMS project settings. If not set, they will reside in the project DATA directory. For Fileshare databases, the shared update IMS project setting names the Fileshare Server and optionally, a drive and/or directory.

The names for secondary index data files are the XDFLD's LCHILD name suffixed with both .DAT and .IDX. These files contain the secondary index key and pointer to the primary physical database. They reside in the same directory as the primary database files.

The database files may be copied, moved, renamed, or deleted using any standard operating system command or utility for manipulating files. These actions must be performed on both the .DAT and .IDX file components. The same actions should be applied to the .DAT and .IDX components for any secondary indexes. If a physical database is logically related to other databases, all of the files for the set of related databases must be acted on.

Example

DBD NAME=TEST01DD,
    ACCESS=(HIDAM,VSAM)
SEGM NAME=TESTHDRS,PARENT=0,
     BYTES=120
FIELD NAME=(SEQFIELD,SEQ,U),
      BYTES=1,START=4
FIELD NAME=REQ,
      BYTES=20,START=5
LCHILD NAME=(TESTHDRI,TEST01PD),PTR=INDX
LCHILD NAME=(TESTHDRX,TEST012D),PTR=INDX
XDFLD NAME=XSEQ,SRCH=REQ

The name input to Zeroload is TEST01DD. An attempt to Zeroload the primary index TEST01PD or the secondary index TEST012D will result in an error message.

The resulting database files for the primary database are TEST01DD.DAT and TEST01DD.IDX.

There is no 'special' data file for the primary index of a HIDAM database. The index is automatically included within these data files.

The resulting database files for the secondary index TEST012D are TEST012D.DAT and TEST012D.IDX.

If you copy this database to another directory, copy all four of these files. For deleting, backup, or other operations, perform the same action for each of these four files.

Parent topic: mfims imsdbu functions
Related concepts
IMS and GSAM Databases
Related reference
MFDBUJCL Utility
SXRBAFORMAT


mfims imsdbu directives

The mfims imsdbu command invokes the IMSDBU utility, and can take several command-line directives that specify details of database management tasks for the various IMSDBU functions. The following is an alphabetical list of all mfims imsdbu directives.

  • ABEND
    Determines behavior in the event of a date discrepancy found in the recovery log files.
  • CLS
    Clears the screen before starting the utility.
  • COMPRESS
    Specifies whether compression was used when the input or output data file was created.
  • DATA
    Specifies the starting position of the segment data in the data record.
  • DSN
    Specifies the dataset name of the input file containing the segment data.
  • ECHO
    Controls the display of and interaction with the messages displayed by IMSDBU.
  • INI
    Specifies the default directives file.
  • LAYOUT
    Specifies the type of the input or output file.
  • LIST
    Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
  • LISTOPEN
    Controls the open disposition of the detail listing file.
  • LOG
    Specifies the IMSDBU activity log.
  • LRECL
    Specifies the length for fixed length generic layout input or output files.
  • MAKELISTDSN
    Specifies the dataset name of the output file for the IMSDBU commands.
  • PROGRESS
    Controls the frequency of progress reporting.
  • RECFM
    Specifies the format of the input or output records.
  • REPLACE
    Specifies how duplicate root segments are to be processed.
  • SEGEXIT
    Specifies the name of a user-supplied exit program that can be used to control selection and modification of segment data during the add, load, or unload process.
  • SEGM
    Specifies the starting position of the 8-byte segment name in the data record.
  • SERVER
    Specifies the name of an enterprise server.
  • TLOG
    Specifies the Backward Recovery TLOG file.
  • TLOGPATH
    Specifies the location of the recovery log files.
Parent topic: mfims IMSDBU


ABEND

Determines behavior in the event of a date discrepancy found in the recovery log files.
Note: Supported by the Recover mfims imsdbu function only.

Syntax:

>>-----ABEND(.-NO-.)---------><
             +-YES+

Parameters:

NO
The recovery process continues even in the event of a date discrepancy found in the recovery log files.
YES
Recovery aborts in the event of a date discrepancy found in the recovery log files.

Properties:

Default: ABEND(NO)
Parent topic: mfims imsdbu directives
Related reference
Recover function


CLS

Clears the screen before starting the utility.
Note: Supported by all mfims imsdbu functions.

Syntax:

>>-.----.--CLS------><
   +-NO-+

Parameters:

None

Properties:

Default: CLS

Dependencies:

None

Comments:

NOCLS prevents the initial clear screen and can be helpful when you are running a series of utilities in a command file.

Parent topic: mfims imsdbu directives
Related reference
mfims imsdbu functions


COMPRESS

Specifies whether compression was used when the input or output data file was created.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload

Syntax:

>>-.---.-.-------COMPRESS--(program)--.-----><
   +-/-+ +.----.-COMPRESS-------------+
          +-NO-+

Parameters:

program
The name of a compression/expansion routine to use instead of the system-supplied routine.

Properties:

Default: NOCOMPRESS

Comments:

The COMPRESS directive enables or disables the expansion of the input data file records.

The COMPRESS directive is only used when when LAYOUT(G) is specified. It is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.

Specifying COMPRESS with no program name causes decompression using the CBLDCIMS program (built-in to the MFIMS software libraries). You can override the name of the compression/expansion routine by specifying a user-written program name.

Add and Load functions
The compression directive for loading must match the setting used when creating the input file. The compression settings are ignored when loading LAYOUT(D) input files as the compression setting is stored in the unload file header record. For generic format loads, ensure that the COMPRESS directive is set correctly to avoid data corruption.
Unload function
When using an Unload file for a subsequent Load, the compression directive used for unloading must also be used when loading. For the IMSDBU-specific LAYOUT(D) formats, this is automatic as the compression setting is stored in the unload file header record. For generic format unloads, ensure that the COMPRESS directive is set correctly to avoid data corruption.
Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
IMSDBU Exits
Related reference
LAYOUT
Add function
Load function
Unload function
mfims imsdbu functions


DATA

Specifies the starting position of the segment data in the data record.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload

Syntax:

>>-----DATA--(position)------><

Parameters:

position
The starting position of the segment data within the data record.

Properties:

Default: DATA(9)

Comments:

A value of 1 corresponds to the first byte of the record data.

When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value.

Add and Load functions
The DATA directive is only used when LAYOUT(G) is specified. It is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
Unload function
The DATA directive is only used when LAYOUT(G) or LAYOUT(S) is specified. It is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.
Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
Related reference
LAYOUT
RECFM
LRECL
Add function
Load function
Unload function
mfims imsdbu functions


DSN

Specifies the dataset name of the input file containing the segment data.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload
  • Useq

Syntax:

>>-----DSN--(filespec)------><

Parameters:

filespec
Add and Load functions
The dataset name of the input file containing the segment data.
Unload function
The dataset name of the output file for the segment data.
Useq function
The dataset name of the output file for the SDEP segment data.

Properties:

Default: DSN(*.DBU)

Comments:

Add and Load functions
If you specify the basename of filespec as an asterisk (*) it is replaced by the DBD name. The input dataset resides in the current directory unless you specify a drive and/or directory.
The input file name, not including the drive and directory, must not be the same as the name of the files for the database. The data files for a database named MYDBD, for example, would be MYDBD.DAT and MYDBD.IDX, and the input file name cannot be either of these file names. We recommend using unique extensions for the output file names. This is enforced even if the database data files are in a different directory than the input file.
Unload and Useq functions
If you specify the basename of filespec as an asterisk (*) it replaced by the DBD name. The output file resides in the current directory unless you specify a drive and/or directory.
The output file name, not including the drive and directory, must not be the same as the name of the files for the database. The data files for a database named MYDBD, for example, would be MYDBD.DAT and MYDBD.IDX, and the output file name cannot be either of these file names. We recommend using unique extensions for the output file names. This is enforced even if the database data files are in a different directory than the output file.
Parent topic: mfims imsdbu directives
Related reference
Add function
Load function
Unload function
Useq function
mfims imsdbu functions


ECHO

Controls the display of and interaction with the messages displayed by IMSDBU.
Note: Supported by all mfims imsdbu functions.

Syntax:

>>-----ECHO--(keyword,msglvl,stoplvl)------><

Parameters:

keyword
The category of information displayed. One of the following:
ALL
Always displays processing messages, input source or detail information and the ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
MSGS
Always displays processing messages and the ending message. No source or detail information is displayed. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ERREND
Always displays the utility ending message. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values.
ENDMSG
Displays ending message only if the utility ending return code is equal to or greater than msglvl. A "Press any key to continue" message is displayed and stops for input if the utility ending return code is equal to or greater than the stoplvl. Enter a msglvl and/or stoplvl value of zero to display and/or stop on every ending message.
COND
Both the warning/error and ending messages are conditional on the msglvl and stoplvl values. Warning and error messages are displayed and stop for user input if the message level is equal to or greater than the msglvl and stoplvl values. The ending message is displayed if the ending return code is equal to or greater than msglvl. You see the message "Press any key to continue" which requires input if the utility ending return code is equal to or greater than the stoplvl.
ERRORS
You see warning and error messages which require input if the message level is equal to or greater than the msglvl and stoplvl. You do not see the ending message.
msglvl
A value from 4 through 20 to indicate the severity of messages to display. See below for more information.
stoplvl
A value from 4 through 20 to indicate the severity of messages to stop for user input. See below for more information.

Properties:

Default: ECHO(MSGS,4,8)

Comments:

The msglvl and stoplvl parameters can take the following values:

Value | Category | Example Cause
4 | General warning message | A minor coding error in DBD source which DBDGEN can make an assumption about and continue.
6 | IMS specific warning message | A warning that a keyword or statement is not supported and is ignored - processing can continue.
8 | General severe error | An incorrect coding in DBD source which cannot be compensated for, such as 'no DBD statement'.
10 | IMS Option specific severe error | An unsupported feature was defined which cannot be compensated for, such as 'Exceeded some maximum'.
12 | Severe error - possible temporary condition | A temporary I/O error such as a 'file locked' or 'database locked' status.
16 | Severe error- permanent - likely installation problem | A permanent I/O error, such as an invalid data set name or member name, was input to a utility or an environment variable is not set correctly.
20 | Severe error - permanent | An unrecoverable I/O error or some other unexpected error.
Parent topic: mfims imsdbu directives
Related reference
mfims imsdbu functions


INI

Specifies the default directives file.
Note: Supported by all mfims imsdbu functions.

Syntax:

>>-.---.-.-------INI--(filespec)--.-----><
   +-/-+ +.----.-INI--------------+
          +-NO-+

Parameters:

filespec
The name and location of the .INI file containing directives that will override the IMSDBU programmed defaults. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the named .INI file in the current directory.

Properties:

Default: None

Comments:

Directives listed in the .INI file override the IMSDBU programmed defaults. Directives entered on the command line or interactive screen override directives in the .INI file.

Specifying NOINI prevents any .INI file from overriding the programmed defaults.

If you specify an .INI that does not exist, the programmed default directives are used as if NOINI were specified.

An .INI file is an ASCII text file. mfims imsdbu directives are identified by the heading [IMSDBU], starting in column 1. The list of directives follows this heading. Only one directive is allowed per line. A line is terminated by the next heading or an end-of-file. Comment lines are indicated by an asterisk (*) or semi-colon (;) in column 1. For example:

[IMSDBU]
PROGRESS(1000)
;use local log
LOG(C:\MYDIR\MYDB.LOG)
Parent topic: mfims imsdbu directives
Related reference
mfims imsdbu functions


LAYOUT

Specifies the type of the input or output file.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload

Syntax:

>>-----LAYOUT--(type)------><

Parameters:

Add and Load functions
type
The type of input file. One of:
D
The input file is an IMSDBU file layout. No additional directives are required to describe the input file.
G
The input file is a generic layout. Additional directives are required to describe the input file and its contents.
I
The input file is an IBM format. No additional directives are required to describe the input file.
S
The input file is a sequential file. Additional directives are required to describe the input file and its contents.
Unload function
type
The type of output file. One of:
D
The output file is an IMSDBU file layout. No additional directives are required to describe the output file.
G
The output file is a generic layout. Additional directives are required to describe the output file and its contents.
I
The output file is an IBM format. No additional directives are required to describe the output file.
S
The output file is a sequential file. Additional directives are required to describe the output file and its contents.

Properties:

Default: LAYOUT(D)

Comments:

The additional directives required for the G and S parameters are RECFM, LRECL, SEGM, and DATA.

Add and Load functions
LAYOUT(I) output files are not suitable for uploading to the mainframe and reloading IMS/ESA databases.
Unload function
Specifying LAYOUT(I) automatically sets the directives RECFM(V), LRECL(0), SEGM(7), DATA(36) and NOCOMPRESS. LAYOUT(I) output files are not suitable for uploading to the mainframe and reloading IMS/ESA databases.
Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
Related reference
COMPRESS
DATA
SEGM
Add function
Load function
Unload function
mfims imsdbu functions


LIST

Controls the location and name of the detail listing file, which includes items such as source listings, completion status, error messages and execution statistics.
Note: Supported by all mfims imsdbu functions.

Syntax:

>>-.---.-.-------LIST--(filespec)--.-----><
   +-/-+ +.----.-LIST--------------+
          +-NO-+

Parameters:

filespec
The name and location to use for the listing file. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, MFIMS or IMSDBU creates the listing file in the current directory.

Properties:

Default: LIST(*.LST)

Comments:

NOLIST suppresses the creation of the listing file.

To specify a path, you can use the convention of placing a dollar sign ($) in front of the name of an environment variable that represents a path. For example, LIST($ENVVAR\*.DOC) creates a list file of dbdname.DOC in the directory named by the ENVVAR environment variable.

Specifying LIST(*.LST) or LIST(*.RPT) causes the listing file to be created in the project listing directory. If no path is specified, the listing file is created in the current directory.

Specifying LIST is equivalent to specifying LIST(*.LST).

If you specify the basename of filespec as an asterisk (*) it is replaced by the DBD name; this allows IMSDBU to provide separate reports for functions which can operate on multiple databases, such as Reorganize. It also assists in maintaining historical detailed reports by DBD name.

Parent topic: mfims imsdbu directives
Related reference
mfims imsdbu functions


LISTOPEN

Controls the open disposition of the detail listing file.
Note: Supported by all mfims imsdbu functions.

Syntax:

>>-----LISTOPEN--(disp)------><

Parameters:

disp
The disposition to use. One of:
NEW
Creates a new listing file or overwrites an existing one.
MOD
Appends the list output to an existing file or creates a new listing if one does not exist. MOD allows you to maintain a detailed historical record of database functions.

Properties:

Default: LISTOPEN(NEW)

Comments:

LISTOPEN is ignored when NOLIST is specified.

Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
IMSDBU Automation
Related reference
mfims imsdbu functions


LOG

Specifies the IMSDBU activity log.
Note: Supported by all mfims imsdbu functions.

Syntax:

>>-.---.-.-------LOG--(filespec)--.-----><
   +-/-+ +.----.-LOG--------------+
          +-NO-+

Parameters:

filespec
The name and location of the file to use as the IMSDBU activity log. filespec can include a drive and/or directory if required. If you do not specify a drive or directory, the listing is placed in the current directory.

Properties:

Default: LOG(IMSDBU.LOG)

Comments:

The activity log shows the ending message status for each function.

Specifying NOLOG suppresses the log file output.

The log file is created if it does not exist. The log file is historical. The most recent entries are written to the end of the file. This file grows in size and might require deletion periodically.

Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
Related reference
mfims imsdbu functions


LRECL

Specifies the length for fixed length generic layout input or output files.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload

Syntax:

>>-----LRECL--(length)------><

Parameters:

length
The length for fixed length generic layout input (Add and Load functions) or output (Unload function) records.

Properties:

Default: LRECL(0)

Comments:

An LRECL is required when loading from a fixed-length generic file; that is, when LAYOUT(G) is specified. It is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.

Unload function
LRECL(0) causes IMSDBU to assign the smallest possible value. The value used will appear in the detail report listing.
Parent topic: mfims imsdbu directives
Related reference
DATA
RECFM
Add function
Load function
Unload function
mfims imsdbu functions


MAKELISTDSN

Specifies the dataset name of the output file for the IMSDBU commands.
Note: Supported by the Makelist mfims imsdbu function.

Syntax:

>>----MAKELISTDSN--(output-dsn)------><

Parameters:

output-dsn
The dataset name of the output file for the IMSDBU commands.

Properties:

Default: MAKELISTDSN(MAKELIST.RUN)

Comments:

This file is written to the current directory if no drive or directory is provided.

Parent topic: mfims imsdbu directives
Related reference
Makelist function
mfims imsdbu functions


PROGRESS

Controls the frequency of progress reporting.
Note: Supported by all mfims imsdbu functions.

Syntax:

>>-------PROGRESS--(no-of-segments)---><

Parameters:

no-of-segments
A value between 0 and 9999 indicating the number of segments to process before displaying a progress message. 0 disables progress reporting.

Properties:

Default: PROGRESS(200)

Comments:

Depending of the function being carried out, the progress message shows the number of segments processed or the percentage complete and an estimate of the time remaining.

In general, we recommend not reducing this value below its default. Very small values measurably reduce the performance of the database function. For relatively fast systems, setting the value higher (such as to 1000 or larger) may improve performance slightly.

Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
IMSDBU Exits
Related reference
mfims imsdbu functions


RECFM

Specifies the format of the input or output records.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload

Syntax:

>>----RECFM--(format)------><

Parameters:

format
The format of the input (Add and Load functions) or output (Unload function) records. One of:
V
Records are variable length. With LAYOUT(G), each record is prefixed with a 2-byte record length (LL) and the file is in the same format as created by the VRECGEN utility. With LAYOUT(S), files are in Micro Focus record sequential format.
F
Records are a fixed length. Requires the LRECL directive to specify the record length.

Properties:

Default: RECFM(V)

Comments:

The RECFM directive is only used when LAYOUT(G) or LAYOUT(S) is specified. It is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.

Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
Related reference
DATA
LRECL
SEGM
Add function
Load function
Unload function
mfims imsdbu functions


REPLACE

Specifies how duplicate root segments are to be processed.
Note: Supported by the Add mfims imsdbu function.

Syntax:

>>-.----.--REPLACE------><
   +-NO-+

Parameters:

None

Properties:

Default: NOREPLACE

Comments:

When adding segments to a database, a root collision occurs when the key of a root segment in the input file already exists in the database. Specifying REPLACE causes the existing database root segment (and its children) to be deleted and the segments from the input file to be inserted. Specifying NOREPLACE causes the segments in the input file to be ignored and the existing database segments to be left as they were.

Parent topic: mfims imsdbu directives
Related reference
Add function
mfims imsdbu functions


SEGEXIT

Specifies the name of a user-supplied exit program that can be used to control selection and modification of segment data during the add, load, or unload process.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload

Syntax:

>>-.---.-.-------SEGEXIT--(program)--.-----><
   +-/-+ +.----.-SEGEXIT-------------+
          +-NO-+

Parameters:

program
The name of the exit program to use.

Properties:

Default: NOSEGEXIT

Comments:

NOSEGEXIT disables this exit.

Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
IMSDBU Exits
Related reference
Add function
Load function
Unload function
mfims imsdbu functions


SEGM

Specifies the starting position of the 8-byte segment name in the data record.
Note: Supported by the following mfims imsdbu functions:
  • Add
  • Load
  • Unload

Syntax:

>>-----SEGM--(position)------><

Parameters:

position
The starting position of the 8-byte segment name in the data record.

Properties:

Default: SEGM(1)

Comments:

A value of 1 corresponds to the first byte of the record data.

When RECFM(V) is specified, the variable length record prefix (LL) is not considered part of the record data and does not affect this value. That is, if the segment name is the first field following the LL field in a variable length file, specify 1 for the SEGM value.

Add function
When loading Fast Path databases which use LTERM keys (related or non-related), the SEGM directive indicates the position of the LTERM name and not the segment name.
Add and Load functions
The SEGM directive is only used when LAYOUT(G) is specified. It is not required and is ignored when LAYOUT(D), LAYOUT(I) or LAYOUT(S) is specified.
Load and Unload functions
When loading GSAM files, the SEGM value is ignored. When loading Fast Path databases which use LTERM keys (related or non-related), the SEGM directive indicates the position of the LTERM name and not the segment name.
Unload function
The SEGM directive is only used when when LAYOUT(G) or LAYOUT(S) is specified. It is not required and is ignored when LAYOUT(D) or LAYOUT(I) is specified.
Parent topic: mfims imsdbu directives
Related concepts
IMS Database Utility (IMSDBU)
Related reference
LAYOUT
RECFM
Add function
Load function
Unload function
mfims imsdbu functions


SERVER

Specifies the name of an enterprise server.
Note: Supported by the Recover mfims imsdbu function only.

Syntax:

>>-----SERVER--(server-name)------><

Parameters:

server-name
The name of the enterprise server that was active when the recovery log files were created.

Properties:

Default: None
Parent topic: mfims imsdbu directives
Related reference
Recover function
mfims imsdbu functions


TLOG

Specifies the Backward Recovery TLOG file.
Note: Supported by the Rollback mfims imsdbu function only.

Syntax:

>>-----TLOG--(tlogName)------><

Parameters:

tlogName
The name of the Backward Recovery TLOG file. By default, the filename is IMSDB.TLOG. tlogName can include a drive and/or directory if required. If you do not specify a drive or directory, IMSDBU looks for the specified file in the current directory.

Properties:

Default: None
Parent topic: mfims imsdbu directives
Related reference
Rollback function
mfims imsdbu functions


TLOGPATH

Specifies the location of the recovery log files.
Note: Supported by the Recover mfims imsdbu function only.

Syntax:

>>-----TLOGPATH--(path)------><

Parameters:

path
The path where the recovery log files reside.

Properties:

Default: Checks the current directory first, and then the path specified by the ES_IMS_TLOG_PATH environment variable.
Parent topic: mfims imsdbu directives
Related reference
Recover function
mfims imsdbu functions


mfims Export/Import

  • mfims stage1ext command
    Exports transactions defined in an IMS stage 1 file to a transaction file.
  • mfims tranexp command
    Export IMS transactions defined in an imsgen2.dat file to a transaction file.
  • mfims stage1imp command
    Import IMS transactions from a transaction file to an imsgen2.dat data file in your Enterprise Developer.
Parent topic: mfims Command-line Utility


mfims stage1ext command

Exports transactions defined in an IMS stage 1 file to a transaction file.

Syntax:

mfims stage1ext stage1file transactionfile

Parameters:

stage1file | The stage 1 file downloaded from the mainframe.
transactionfile | The name of the transaction file to be created.

Comments:

Run the mfims stage1ext command from an Enterprise Developer command prompt and from the directory that contains your stage 1 file.

If you do not specify the name of the transaction file, Enterprise Developer uses the default name of tranexp.txt.

The transaction definition file is created in the current directory.

Parent topic: mfims Export/Import
Related concepts
Download IMS Files
Export IMS Transactions
Related tasks
To export IMS transactions


mfims tranexp command

Export IMS transactions defined in an imsgen2.dat file to a transaction file.

Syntax:

mfims tranexp [transactionfile]

Parameters:

transactionfile The name of the transaction file to contain the exported transactions.

Comments:

Run the mfims tranexp command from an Enterprise Developer command prompt.

You must be in the directory containing the imsgen2.dat file, or you must set the ES_IMSLIB environment variable to point to the location of the imsgen2.dat file.

If you do not specify the name of the transaction file, Enterprise Developer uses the default name of tranexp.txt.

The transaction definition file is created in the current directory.

Parent topic: mfims Export/Import
Related concepts
Download IMS Files
Export IMS Transactions
Related tasks
To export IMS transactions
Related reference
IMS-Specific Environment Variables


mfims stage1imp command

Import IMS transactions from a transaction file to an imsgen2.dat data file in your Enterprise Developer.

Syntax:

mfims stage1imp transactionfile [ADDREPL] [DELEXIST]

Parameters:

transactionfile | An IMS transaction definition file created from a stage 1 file downloaded from the mainframe, or generated by Enterprise Server.
ADDREPL | If the imsgen2.dat already exists, specifies adding new transactions and replacing existing transactions. If you do not specify ADDREPL, new transactions are added but existing transactions are left unchanged.
DELEXIST | If the imsgen2.dat already exists, specifies that all the existing transaction definitions in the imsgen2.dat file be deleted before importing extracted transactions.

Comments:

Run the mfims stage1imp command from an Enterprise Developer command prompt and from the directory that contains your transaction file.

If you want to import into an existing imsgen2.dat, be sure that either the transaction file and the IMSGEN2.DAT are in the current directory, or that you have set the ES_IMSLIB environment variable to point to the location of the imsgen2.dat file.

Parent topic: mfims Export/Import
Related concepts
Import the Transaction File
Related tasks
To import IMS transactions
Related reference
IMS-Specific Environment Variables


Non-discardable Messages (NDM) Interface Block

The contents of the NDM interface block are:

Field | Offset | Length | Picture | Description
NDMEYE | X'00' | 4 | pic x(4) | Eye catcher ( value = 'NDM').
NDMTRAN | X'04' | 8 | pic x(8) | Transaction that the application was processing when it abended. This transaction is associated with the input message pointed to by NDMMSGA.
NDMPSBN | X'0C' | 8 | pic x(8) | PSB associated with the application that abended.
NDMUSID | X'14' | 8 | pic x(8) | User ID.
NDMGRPNM | X'1C' | 8 | pic x(8) | Group name.
NDMUSIDI | X'24' | 1 | pic x(1) | Indicator for the contents of NDMUSID (v alue = ' U ' , meaning the contents is a user ID).
NDMSRCFL | X'25' | 1 | pic x(1) comp-x | Flag that indicates the origin of the input message (v alue = 0, meaning the origin is an LTERM).
NDMLTERM | X'26' | 8 | pic x(8) | Name of the originating LTERM.
 | X'2E' | 110 |  | Reserved.
NDMABEND | X'9C' | 4 | pic s9(9) comp | Abend code in system format 00sssuuu, where: sss = System abend code uuu = User abend code
NDMTSLCL | X'A0' | 8 |  | Local time stamp of the arrival of the input message in the system. NDMTSLCL contains NDMDLCL and NDMTLCL.
NDMDLCL | X'A0' | 4 | pic s9(7) comp-3 | Local date that the message arrived, in format YYYYDDDf, where: YYYY = Year DDD = Julian day f = X'F'
NDMTLCL | X'A4' | 4 | pic s9(7) comp-3 | Local time that the message arrived, in format HHMMSSTf, where: HH = Hours MM = Minutes SS = Seconds T = Tenths of seconds f = X'F'
 | X'A8' | 12 |  | Reserved.
NDMSPAA | X'B4' | 4 | pointer | Address of the SPA if the transaction in NDMTRAN is a conversational transaction, otherwise this field contains zeros. If the SPA is present, the format is as follows: LL|ZZZZ|Trancode|Data, where: LL = Two-byte length field that includes the length of LLZZZZ ZZZZ = Four-byte field that always contains zeros Trancode = Eight-byte field that contains the transaction code for the conversation or blanks Data = SPA user data
NDMMSGA | X'B8' | 4 | pointer | Address of the input message. If this field is zero, there is no message segment and the message can be a SPA segment only. The format is as follows: LL|ZZ|Data, where: LL = Two-byte length field that includes the length of LLZZ ZZ = Two-byte field that always contains zeros except for the last segment which contains X'FFFF' Data = Message segment data For a multi-segment message, the pattern is: NDMMSGA = address of first segment NDMMSGA+LL 1 = address of second segment NDMMSGA+LL 1 +LL 2 = address of third segment Etc.
NDMMSGL | X'BC' | 4 | pic s9(9) comp | Total length of the input message.
 | X'C0' | 20 |  | Reserved.
NDMABRSN | X'D4' | 4 | pic s9(9) comp | Abend reason code (if available).
NDMTRNST | X'D8' | 4 | pic s9(9) comp | Transaction status flag. Enterprise Server examines this field on return from the exit routine. The exit routine can set this field to any one of the following values: Value = 1 means do not stop the abended transaction. Value = 2 means do not send the DFS555I message. Value = 3 means do not stop the abended transaction and do not send the DFS555I message.
NDMDEST | X'DC' | 8 | pic x(8) | Name of the alternate destination set by the exit routine to which the input message is to be queued. Enterprise Server only examines this field if you pass back return code 16, otherwise Enterprise Server ignores this field.
Parent topic: Reference
Parent topic: IMS Support in Enterprise Server


Standard User Exit Parameter List

The contents of the standard user exit parameter list are:

Field | Offset | Length | Picture | Description
SXPLVER | X'00' | 4 | pointer | Address of a fullword containing the version number of this parameter list.
 | X'04' | 4 |  | Reserved (value = 0).
SXPLAWRK | X'08' | 4 | pointer | Address of a 512-byte work area for use by the exit routine. The address is different each time that this exit routine is called .
SXPLFSPL | X'0C' | 4 | pointer | Address of the NDM interface block.
 | X'10' | 8 |  | Reserved (value = 0).
Parent topic: Reference
Parent topic: IMS Support in Enterprise Server


User Interface Reference

  • Project Properties - IMS
  • IMS Segment Layout Editor
  • IMS Database Editor
  • Enterprise Server
Parent topic: Reference


Project Properties - IMS

Generated Files
The full path to the directory where you want to store your generated IMS files. Type the full path or click Browse to select a directory.
IMS Database
The full path to the directory that contains your IMS database. Type the full path or click Browse to select a directory.
  • Project Properties - DBD Settings
  • Project Properties - MFS Settings
  • Project Properties - PSB Settings
Parent topic: User Interface Reference


Project Properties - DBD Settings

Message Level
Select the level of messaging you want to appear in the log file:
  • Warning
  • Severe
  • Error
Generate listing file
Generates a .lst file in the directory specified in the Generated Files field on the IMS page. Default is checked.
Generate Map for DBD
Generate an MFS map file for each DBD.
Clean removes DBD generated files
Check this to remove generated DBD files when you clean the project.
Additional directives
Type additional DBDGEN directives, each separated by a space. Optional.
Parent topic: Project Properties - IMS
Related reference
DBDGEN Directives


Project Properties - MFS Settings

Message Level
Select the level of messaging you want to appear in the log file:
  • Warning
  • Severe
  • Error
Generate listing file
Generates a .lst file in the directory specified in the Generated Files field on the IMS page. Default is checked.
Message Level
Select the level of messaging you want to appear in the log file:
  • Warning
  • Severe
  • Error
Generate listing file
Generates a .lst file in the directory specified in the Generated Files field on the IMS page. Default is checked.
STACK handling:
Select a method of STACK handling from the drop-down list:
  • Ignore after DEV statement (default)
  • Ignore always
  • Expand always
Use preprocessor
Check this to use a preprocessor; type the preprocessor name into the corresponding field.
Additional directives
Type additional MFSGEN directives, each separated by a space. Optional.
Parent topic: Project Properties - IMS
Related reference
MFSGEN Directives


Project Properties - PSB Settings

Message Level
Select the level of messaging you want to appear in the log file:
  • Warning
  • Severe
  • Error
Generate listing file
Generates a .lst file in the directory specified in the Generated Files field on the IMS page. Default is checked.
Verbose
Directs output to the screen as well as to the log file.
Validate PSB against DBDGENS
Check this to validate each PSB against its corresponding generated DBD.
Clean removes PSB generated files
Check this to remove generated PSB files when you clean the project.
Additional directives
Type additional PSBGEN directives, each separated by a space. Optional.
Parent topic: Project Properties - IMS
Related reference
PSBGEN Directives


IMS Segment Layout Editor

  • IMS Segment Layout Editor Window
  • New Segment Layout wizard
  • Field Properties dialog box
Parent topic: User Interface Reference


IMS Segment Layout Editor Window

Data Structures View
Structures from filename
Shows the name of the COBOL file that contains the Data Division structures shown in the lower part of the pane.
Tree view
Shows the loaded Data Division structures.
Layout view
Header Information Bar
Provides information about the status of the layout file and is made up of the following items:
Indicates that no layouts have been defined for the item selected in the left pane.
Indicates that the selected layout is usable.

Indicates that the selected conditional layout requires a defined condition.
No Layouts
No layouts are defined.
Layouts n
Indicates the number of layouts defined.
No Conditions
No conditions are defined.
Conditions n
Indicates the number of conditions defined for the selected layout.
ANSI
Indicates that the layout was created from a COBOL file that uses the ANSI character set.
EBCDIC
Indicates that the layout was created from a COBOL file that uses the EBCDIC character set.
Layout Indicators
Default layout.
Conditional layout.
Field with no defined condition and without conversion.
Field with a defined condition but no conversion.
Field with conversion but no defined condition.
Field with a defined condition and with conversion.
Parent topic: IMS Segment Layout Editor
Related tasks
To start the Segment Layout Editor
To create a new segment layout file
To edit an existing segment layout file
To view layout information in the Layout Editor window


New Segment Layout wizard

Segment Name
Lists the names of segment types in the current IMS database.
No
Shows the number of segment occurrences for the segment type.
Length
Shows the length of the segment type.
Default Layout
Create a default layout for the selected segment type.
Conditional Layout
Create a conditional layout for the selected segment type.
Parent topic: IMS Segment Layout Editor
Related tasks
To create a new segment layout file
To define segment layouts


Field Properties dialog box

Name
The name of the selected segment.
Range
Shows the position and length of the segment within the layout. The first character is the position of the first byte of the segment counting from one and the second digit is the length of the segment.
Character set
The character set used in the segment.
Convert
Controls whether the field is converted during an EBCDIC to ANSI or an ANSI to EBCDIC conversion. By default, Convert is switched on for all except for the following types of fields when, by default, it is switched off:
  • Computational fields
  • Redefined fields
Condition group
Build the condition you want to apply to this layout. Hex values show below the dotted line in each condition box.
Parent topic: IMS Segment Layout Editor
Related tasks
To define or edit a condition for a conditional layout


IMS Database Editor

  • IMS Database Editor window
  • Qualifications for segment dialog box
  • Define SSA dialog box
  • IMS Database Find dialog box
  • Add bookmark dialog box
  • Bookmarks dialog box
  • Initialize Segment dialog box
  • Set Segment Length dialog box
Parent topic: User Interface Reference


IMS Database Editor window

Toolbar

IMS Database Editor Toolbar
Each icon on the toolbar enables you to perform a task on a selected segment on the tree view.
Get first with hold
Get first segment with hold.
Get next segment with hold
Get next segment with hold.
Get next segment within parent, with hold
Get next segment within parent, with hold.
Get unique with hold
Get unique with hold.
Insert segment.
Replace segment.
Delete segment.
Define SSA.
Sync point.
Rollback.
Go to current segment
Go to current segment.
Start or end browse.
Browse previous page
Browse previous page.
Browse next page
Browse next page.
Go to segment
Go to segment.
ANSI / EBCDIC drop-down list
Select a format. Default is ANSI.
Tree view

Tree view
Shows all segments hierarchically so you can select a segment and see your current position in the database. From here, you can browse, include or exclude a segment, or add and go to bookmarks.
Segment Browser

Segment browser
Shows the segment level, name, and browsable segment data.
SSA list

SSA list
Lists the level, segment name, SSA information, key feedback area information, and length of each available segment. From here, you can browse, include or exclude a segment, or add and go to bookmarks.
Segment data

segment data
Shows the contents of the selected segment, which contains character and hexadecimal representations of binary segment data for the current segment occurrence. Click in this area to edit the data in decimal or in hexadecimal, which shows under the dotted line.
Field data

Field data
Shows the contents of the selected field, which contains character and hexadecimal representations of field data. Click in this area to edit the data in decimal or in hexadecimal, which shows under the dotted line.
Layout view

Layout view
This pane shows on the right, and only when a layout file has been applied.
Layout status bar
Displays the name of the layout applied, and its status. Use the up and down arrows on the far right to scroll through the list in the left pane.
Indicates that the selected layout is usable.

Indicates that the layout is in error.
Message
Describes the layout status, including error messages.
Field indicators
Field with no defined condition and without conversion.
Field with a defined condition but no conversion.
Field with conversion but no defined condition.
Field with a defined condition and with conversion.
Field contains invalid data.
Field Name
Shows the name of the COBOL field that corresponds to the selected data item.
Format
Shows the COBOL picture clause defined for each field.
Value
Shows the value assigned to the field from the selected record. This field is editable.
When a segment layout has been applied, this area shows in the right half of the IMS Database Editor window.

You can edit a field by clicking inside the Value column of the field. When you have finished editing a field, you can save your edits in the segment buffer by pressing Enter. This updates the Segment Data area in the left-hand pane. You can undo the edits you have made to a field by pressing Escape instead of Enter.

Parent topic: IMS Database Editor
Related concepts
Creating and Editing Data
Editing Field Data
Editing Segment Data
Editing Data
Related tasks
To configure edit warnings
To undo edits
To edit formatted field data
To edit unformatted field and segment data
To apply segment layouts
To add a first child segment occurrence
To add a twin segment occurrence
To delete a segment occurrence
To modify a segment occurrence
To change the length of a segment occurrence
To initialize data
To make a DL/I call


Qualifications for segment dialog box

Command code
Select a command code to apply to the SSA.
Define qualifier group
Enables you to construct one or more SSA qualifiers using the drop-down lists, entry field, and buttons in the group.
Key field drop-down list
Select a key field.
Relational operator drop-down list
Select a relational operator.
Search value field
Type a qualifying value for the selected key field. Hexadecimal values show a the bottom of the field.
Boolean operator drop-down list
Select a boolean operator to construct a compound qualifier. Optional.
Add button
Add the constructed qualifier to the Qualification list.
Replace button
Replace a definition selected on the Qualification list with the qualifier currently defined in the Define qualifier group.
Qualification list group
Lists qualifier definitions added from the Define qualifier group and enables you to change and/or delete them.
Definition grid
Lists the definitions added from the Define qualifier group.
Edit
Load the selected definition into the Define qualifier group to enable editing.
Delete
Delete the selected definition.
Parent topic: IMS Database Editor
Related tasks
To define an SSA


Define SSA dialog box

No SSA
No SSA defined for this segment type. Default
Unqualified SSA
Specify an unqualified SSA for this segment type.
Command code
Select a command code to apply to the SSA.
Qualified SSA
Specify a qualified SSA for this segment type.
Define
Define the qualifier(s) for the SSA.
Parent topic: IMS Database Editor
Related tasks
To define an SSA


IMS Database Find dialog box

Find field
Type a text string to find. The hexadecimal representation of the string shows below the dotted line.
Find button
Click this to find the specified text string.
Match case
Check this to conduct a case-sensitive search.
Left
First byte offset of search area.
Right
Last byte offset of search area.
Within offsets
Limit search to the area defined by the values in the Left and Right fields.
Use field
Use selected field definition for find string and search area.
Replace field definition
Replace field definition for find string and search area.
End
Select a point in the database at which to end the search.
Only look in segment-name
Check this to search only within the specified segment.
Parent topic: IMS Database Editor
Related concepts
Searching for a String
Related tasks
To search an IMS database for a string


Add bookmark dialog box

Segment
Shows the current segment name, which is saved with the bookmark.
Enter a note to be associated with this bookmark
Type a unique description of the bookmark that enables you to identify it.
Parent topic: IMS Database Editor
Related concepts
Bookmarking Segment Occurrences
Related tasks
To bookmark a segment type
To go to a bookmarked segment type
To delete a bookmark
To save your bookmarks in a file
To load bookmarks from a file


Bookmarks dialog box

Segment
Identifies the segment that contains the bookmark.
Note
Shows the unique description given to the bookmark when it was created.
Goto bookmark
Click this to jump to the location of the selected bookmark.
Delete bookmark
Click this to delete the selected bookmark.
Parent topic: IMS Database Editor
Related concepts
Bookmarking Segment Occurrences
Related tasks
To bookmark a segment type
To go to a bookmarked segment type
To delete a bookmark
To save your bookmarks in a file
To load bookmarks from a file


Initialize Segment dialog box

Select a Segment Layout
Lists all defined segment layouts and their lengths for the segment specified, plus an entry for padding bytes.
Layout Name
The name of the segment layout.
Length
The length of the segment layout.
Parent topic: IMS Database Editor
Related concepts
Initializing Segments and Fields
Related tasks
To initialize data


Set Segment Length dialog box

Set segment length
Type a new length for the selected segment.
Parent topic: IMS Database Editor
Related tasks
To change the length of a segment occurrence


Enterprise Server

  • Server Instance Properties: MQ Support
  • Server Instance Properties: MSS Support
  • ESMAC
Parent topic: User Interface Reference


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
  • 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: Enterprise Server
Parent topic: Edit Server Instance Properties


Server Instance Properties: MQ General

Use this page to enable MQ listener support.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MQ > General tabs.
MQ listener support enabled

When checked, enables MQ listener support for the MQ IMS bridge feature. Maps to the ES_MQ_LISTENER environment variable.

Parent topic: Server Instance Properties: MQ Support
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
Parent topic: Server Instance Properties: MQ Support


Server Instance Properties: Add MQ Listener

Use this page to define the details of a new MQ listener.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MQ > MQ Listeners tabs.
Name
Specify a name for the new MQ listener.
MQ Queue Name
Specify the name of an existing MQ Queue defined for the specified MQ Queue Manager.
MQ Queue Manager Name
Specify the name of an existing MQ Queue Manager. You create Queue Managers and Queues in WebSphere MQ.
Enabled

When checked, enables the new MQ listener.

Parent topic: Server Instance Properties: MQ Support
Parent topic: Server Instance Properties: MQ Support


Server Instance Properties: Edit MQ Listener

Use this page to edit the details of an existing MQ listener.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MQ > MQ Listeners tabs.
Name
Specify a name for the new MQ listener.
MQ Queue Name
Specify the name of an existing MQ Queue defined for the specified MQ Queue Manager.
MQ Queue Manager Name
Specify the name of an existing MQ Queue Manager. You create Queue Managers and Queues in WebSphere MQ.
Enabled

When checked, enables the MQ listener.

Parent topic: Server Instance Properties: MQ Support
Parent topic: Server Instance Properties: MQ Support


Server Instance Properties: MSS Support

Check Mainframe Subsystem Support enabled to .

Use this page to enable MSS for this enterprise server instance.

To access this page:

  1. On the server instance screen, select the Server > Properties > MSS tabs.
Note:

You can use the resolved value of an environment variable in any fields for the entry of file or directory paths. To do this, prefix the environment variable you want to include with a dollar ($) sign; for example:

$production\programs

where production is an environment variable.

If you want to use a dollar sign as part of the value, rather than as an indicator of an environment variable, you must escape the dollar sign character with a backslash(\); for example:

\$production\programs

In this case, $production will not be replaced by the value of the environment variable.

  • Server Instance Properties: MSS IMS General
  • Server Instance Properties MSS IMS DB General
  • Server Instance Properties MSS IMS DB Compression
  • Server Instance Properties: MSS IMS DB Locking
  • Server Instance Properties MSS IMS DB Recovery
  • Server Instance Properties: MSS IMS TM General
  • Server Instance Properties: MSS CICS
  • Server Instance Properties: MSS JES
  • Server Instance Properties: MSS IMS General
  • Server Instance Properties MSS IMS DB General
  • Server Instance Properties MSS IMS DB Compression
  • Server Instance Properties: MSS IMS DB Locking
  • Server Instance Properties MSS IMS DB Recovery
  • Server Instance Properties: MSS IMS TM General
  • Server Instance Properties: MSS IMS TM MPRs
Parent topic: Enterprise Server
Parent topic: Edit Server Instance Properties


Server Instance Properties: MSS IMS General

Use this page to enable Mainframe Subsystem Support (MSS) and configure IMS support for this enterprise server.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MSS > IMS > General tabs.
IMS enabled

Indicates whether or not IMS is enabled for this enterprise server.

Codeset bias

Choose the default codeset to use for transactions running on this enterprise server:

  • ASCII - Transactions use ASCII.
  • EBCDIC - Transactions use EBCDIC.
Configuration directory

This path maps to the ES_IMSCFG environment variable, and is reserved for future use.

ACB file directory

Specify the location of the .dat, .idx, and .acb files produced by DBDGENs, IMSGENs and PSBGENs. This field maps to the ES_ACBLIB environment variable.

GEN file directory

Specify the full path to the transaction definition file for this enterprise server. This field maps to the ES_IMSLIB environment variable.

Parent topic: Server Instance Properties: MSS Support
Parent topic: Server Instance Properties: MSS Support


Server Instance Properties MSS IMS DB General

Use this page to set the IMS database path.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MSS > IMS > DB > General tabs.
Database path

Specify the location of the IMS data files and any .slf files to be used by the IMSDBUEA segment exit routine.

Parent topic: Server Instance Properties: MSS Support
Parent topic: Server Instance Properties: MSS Support


Server Instance Properties MSS IMS DB Compression

Use this page to set IDX-8 KEY/DATA compression options.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MSS > IMS > DB > Compression tabs.
Key compression
Indicates whether or not key compression is turned on.
Data compression

The data compression routine number. Valid values are the same as those that can be specified for the Compiler directives DATACOMPRESS and KEYCOMPRESS.

Parent topic: Server Instance Properties: MSS Support
Parent topic: Server Instance Properties: MSS Support


Server Instance Properties: MSS IMS DB Locking

Use this page to set IMS database locking options.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MSS > IMS > DB > Locking tabs.
Enable IRLM locking

When checked, enables the Internal Lock Resource Manager (IRLM) locking algorithm. IRLM locking more closely parallels mainframe IMS database DB locking behavior, reducing data constraint and potential for deadlock. Maps to the ES_IMS_IRLM environment variable.

Dump on lock timeout

When checked, creates a system dump when IMS DB control is unable to access a locked record before the specified Locked resource timeout period expires. Maps to the ES_IMS_DUMP_ON_TIMEOUT environment variable.

Dump on deadlock
When checked, creates a system dump when a deadlock is detected. Maps to the ES_IMS_DUMP_ON_DEADLOCK environment variable.
Locked resource timeout

The number of seconds during which IMS DB control continues to retry a locked record before timing out. Valid values are 0 to 65535. The default is 30 seconds; a value of 0 indicates an indefinite wait time. Maps to the ES_IMS_LOCK_TIMEOUT environment variable.

Parent topic: Server Instance Properties: MSS Support
Parent topic: Server Instance Properties: MSS Support


Server Instance Properties MSS IMS DB Recovery

Use this page to enable IMS forward recovery and specify a path for forward recovery IMS transaction logs.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MSS > IMS > DB > Recovery tabs.
Enable rollforward recovery

When checked, enables the IMS forward recovery feature. Maps to the ES_IMS_ROLLFORWARD environment variable.

IMS transaction log path

Specify the path to a directory where IMS forward recovery log files are stored. Maps to the ES_IMS_TLOG_PATH environment variable.

Parent topic: Server Instance Properties: MSS Support
Parent topic: Server Instance Properties: MSS Support


Server Instance Properties: MSS IMS TM General

Use this page to configure IMS TM support for this enterprise server.

To access this page:

  1. From the Enterprise Server Administration home page, at the left of the Enterprise Server instance to configure, click Edit.
  2. On the server instance screen, select the Server > Properties > MSS > IMS > TM > General tabs.
Message queue

Use these fields to define the attributes of the IMS message queue.

Use default queue name
Check this to use the default queue path and filename, which by default is %USERPROFILE%\Documents\Micro Focus User\Enterprise Developer\WORKAREA\esname\IMSMESGQ.dat (Windows) or /var/mfcobol/es/esname/IMSMESGQ.dat (UNIX) where esname is the name of your enterprise server region.
Name

Provide an alternative path and filename for the IMS message queue.

Maximum blocks

The message queue consists of blocks of approximately 64K bytes. These blocks consist of 254 segments (not message segments) which are the allocation unit for queue space.

Specify the maximum number of blocks to be used to store the message queue. If necessary, you can dynamically change this number while the enterprise server is running. The value must be in the range of 4 through 63488. The default for an initial server definition is 32.

When space is not available, a TM thread waits until the allocation request can be satisfied. The failure mode for "out of space" is a hang condition.

Note: To decrease the likelihood of a hang condition due to lack of space, Enterprise Server reserves a percentage of the allocated space (a cushion) to enable graceful intervention should it be required. In this case, to facilitate recovery, other message queue operations are restricted. These restrictions are removed when the cushion allocation is reacquired by TM. You can change the cushion percentage dynamically. See IMS Control for details.
Queue buffer count
This is the tuning control. More buffers means less swapping of blocks in memory for message queue activity. The default is 2.
Note: Give careful thought before changing this setting.
Cold start

Choose what information is deleted when you next start this enterprise server:

  • None - No information is deleted. Default.
  • Stats only - Only statistics are deleted.
  • Definitions and stats - Resource definitions and statistics are deleted.
  • Everything - A fresh copy of the message queue dataset is allocated, discarding all previous content.
Persist

Check this to specify that the action you specified in the Cold start option occurs each time this enterprise server starts. Default is unchecked.

MFS path

Specify the location for the files produced by MFSGENs. Default is $IDE_MODPATH.

MFS attribute bias

Choose how attributes are assumed to be defined for transaction programs running on this enterprise server:

  • Binary - Default. The programs define attributes as binary values, for example:
    05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR    PIC X(2) VALUE X"C0C1".
   10 ERROR-ATTR     PIC X(2) VALUE X"C0C9".
   10 OK-ATTR        PIC X(2) VALUE X"00C1".
   10 PROT-ATTR      PIC X(2) VALUE X"00F1".
  • Character - The programs define attributes as characters, for example:
    05 ATTRIBUTE-VARIABLES.
   10 CURSOR-ATTR PIC X(2) VALUE "{A".
   10 ERROR-ATTR PIC X(2) VALUE "{I".
   10 OK-ATTR PIC X(2) VALUE " A".
   10 PROT-ATTR PIC X(2) VALUE " 1".

    This setting only has an effect on programs compiled using the ASCII character set; it is ignored for programs compiled using EBCDIC.

    Where you specify Character, Enterprise Server will automatically translate the values of MFS attributes to those that would be used if the program were compiled as EBCDIC. For example: the hexadecimal 7B41 value produced by assigning '{A' to an attribute and compiling with ASCII, will be converted to the correct C0C1 value. Where you specify that attribute values have been coded as binary data, Enterprise Server will take no action.

MFS null character

Specify the character to use as the MFS NULL character. You can enter the value in character or hexadecimal form. The default is Hexadecimal 0x00.

This setting only has an effect on programs compiled using the ASCII character set; it is ignored for programs compiled using EBCDIC.

Actvity keypoint frequency

Specify how many thread requests are to be processed before a keypoint is generated. This must be in the range 0 through 65535. The default is 64. Specifying 0 indicates that keypoints are only generated when the enterprise server starts and shuts down.

Trailing space

Check this to specify that you must add a trailing space when entering transaction names in this enterprise server. Default is checked.

Transaction threshold

Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. This must be in the range 0 through 65535. A value of 0 indicates that there is no threshold. Default is 0.

Application path

Specify the location of the transaction programs running on this enterprise server. Default is $IDE_LAODLIB.

Parent topic: Server Instance Properties: MSS Support
Parent topic: Server Instance Properties: MSS Support
Related concepts
Configuring the IMS Message Queue
Dynamic IMS Message Queue Expansion
Dynamic IMS Message Queue Performance Tuning
Related tasks
To enable dynamic IMS message queue performance tuning
To dynamically tune IMS message queue performance
To dynamically adjust the IMS message queue configuration
Related reference
IMS Control


ESMAC

  • IMS Control
  • MQ Listeners
  • MQ Writers
  • MQ Listener (listener-name)
  • MQ Writers (writer-name)
Parent topic: Enterprise Server
Parent topic: Resources


IMS Control

Use this page to start message processing regions (MPRs) and perform a number of other IMS-related administration functions for this server.

Commands
/dis TRAN all

Click this to execute a /dis TRAN all command. The results are displayed below the entry field.

/dis USER all

Click this to execute a /dis USER all command. The results are displayed below the entry field.

/dis DB all

Click this to execute a /dis DB all command. The results are displayed below the entry field.

/dump TM

Click this to execute a /dump TM command. The results are displayed below the entry field.

Enter

Click this to execute the command specified in the entry field to the right. The results are displayed below the entry field.

Start IMS MPRs (Message Processing Regions)
Start
Click this to start a message processing region.
MPR Classes

Specify the transaction classes that can run in the message processing region.

Debug

Click this if you want to debug the IMS transactions that will run in this message processing region.

Renew MFS Formats and IMS ACBs
Renew
Click this to delete information from the system cache and to reload the current information from disk.
MFS Formats
Select this to delete information on MFS format blocks.
ACBs
Select this to delete information on application control blocks

TM System Overview and Control
Message Queue Max
The number of blocks representing the maximum size to which the IMS message queue data store can expand. The value must be in the range of 4 through 63488.
Cushion
The size of the cushion to be reserved for graceful lack-of-space behavior is represented as a percentage of the maximum message queue size from 0% to 7.97%. The default is 4%.
Transaction Threshold
Specify the maximum length of time in seconds that a transaction can run before a message is logged to the console to indicate that it has exceeded its threshold. This must be in the range 0 through 65535. A value of 0 indicates that there is no threshold.
Q Flush Aggregate
on
Enables the aggregation of transactional flushing of operating system buffers to disk.
ms
An interval of time, in milliseconds, during which flush requests are held and allowed to accumulate before flushing. Valid values are 0 through 255.
Flush disable
Disables dynamic flushing, meaning that the TM system unilaterally flushes operating system buffers to your physical disk only at each keypoint.
Keypoint Frequency
Specify how many thread requests are to be processed before a keypoint is generated. This must be in the range 0 through 65535. The default is 64. Specifying 0 indicates that keypoints are only generated when the enterprise server starts and shuts down.
TM Message Queue Diagnostics
Display summary overview of IMS Message Queues
Click this to view the content of the IMS message queue.
Display block-number/segment of message queue

Click this to view a specified segment of the IMS message queue.

Parent topic: ESMAC
Parent topic: IMS
Related concepts
Configuring the IMS Message Queue
Dynamic IMS Message Queue Expansion
Dynamic IMS Message Queue Performance Tuning
Related tasks
To enable dynamic IMS message queue performance tuning
To dynamically tune IMS message queue performance
To dynamically adjust the IMS message queue configuration
Related reference
Server Instance Properties: MSS IMS TM General


MQ Listeners

Use this page to view information about the MQ listeners available on the current server.

Details
Click this to display detailed information for the listener. Each detail row shows the following:
  • Name of the listener
  • Status of the listener
  • Type of listener
  • Number of messages processed
  • Number of messages that produced errors
  • Name of the MQ queue that is being listened to
Parent topic: ESMAC


MQ Writers

Use this page to view information about the dynamically created MQ writers available on the current server.

Details
Click this to display detailed information for the writer. Each detail row shows the following:
  • Name of the writer
  • Status of the writer
  • Type of writer
  • Number of messages processed
  • Number of messages that produced errors
  • Name of the MQ queue being written to
Parent topic: ESMAC


MQ Listener (listener-name)

Use this page to view information about a particular MQ listener selected from the MQ Listeners page.

Start / Stop

Starts or stops the MQ listener. Toggle.

Name
The name of the MQ listener.
Queue
The name of the MQ queue being listened to.
Queue Manager
The name of the Websphere MQ queue manager that defines the queue being listened to.
Type
The type of MQ listener.
Message Count
The number of messages processed.
Error Count
Number of messages that produced errors.
Dump
Click this to write dump information for this for this MQ listener to the casdump.rec file.
Parent topic: ESMAC
Related reference
CASDUMP


MQ Writers (writer-name)

Use this page to view information about a particular MQ writer selected from the MQ Writers page.

Stop

Stops and deletes the MQ writer.

Name
The name of the MQ writer.
Queue
The name of the MQ queue being written to.
Queue Manager
The name of the Websphere MQ queue manager that defines the queue being written to.
Type
The type of MQ writer.
Message Count
The number of messages processed.
Error Count
Number of messages that produced errors.
Dump
Click this to write dump information for this MQ writer to the casdump.rec file.
Parent topic: ESMAC


JCL Support

  • Enterprise Server Integration with the IDE
    When you are developing JCL applications for running on Enterprise Server, you can use a number of Enterprise Server facilities available from within the IDE.
  • JCL development
  • Files and Data Sets
    This section provides introductory information on how MSS uses the following types of file: Project files, System catalog files, User catalog files, Catalog files, Data set files, and Spool files
  • Advanced Data Set Information
    This section expands on the information presented in the topic Files and Data Sets in your User's Guide.
  • Utility Programs
    MSS has a number of utility programs. Many of these emulate the functions of commonly-used mainframe batch utilities. You can invoke these utilities in a JCL jobstream or REXX exec.
  • MVS Emulation
    This chapter describes how MSS emulates various facilities provided under MVS, OS/390 and z/OS on the mainframe.
  • Micro Focus Batch Scheduler Integration
  • Using JCL User Exits
    The JCL component provides a facility called the JCL user exit, which enables you to monitor and control various events that occur during execution of a job or TSO session.
  • Using JCL Subsystem Exits
  • REXX Support
    This chapter describes how REXX is supported in MSS.
  • DSNREXX Support (Technology Preview)
  • Invoking JCL from CICS
    There are two widely-used methods of invoking JCL from a CICS application.
  • JCL API
Parent topic: Mainframe Programming


Enterprise Server Integration with the IDE

  • You can start and stop an enterprise server associated with a project, submit jobs and view the results.
  • You can submit jobs to remote enterprise servers.

Also at any time, whatever type of development you are doing, you can access the Enterprise Server Administration Web interface, from your COBOL development environment.

  • Using the Project-based Facilities
Parent topic: JCL Support


Using the Project-based Facilities

If you are working on a JCL application, and you want to run it in a JCL-enabled enterprise server, you need to stop and start the enterprise server. You can do this from outside the IDE, with ES Admin running in its own browser window, or from within the IDE. Stopping and starting with in the IDE is likely to be more convenient, since you don't need to switch between windows.

To stop and start within the IDE, you need to associate the current project with an enterprise server. You must use an enterprise server that:

  • Is defined on your machine
  • Is enabled for MSS and JES
  • Has two system services:
    • One with a service class of "MF ES".
    • One with a service class of "MF JES"
  • All new servers that you create as MSS servers automatically have these services. If you want to use an existing server, you need to enable it for MSS (if not already enabled), then add the services.

Once you have associated the project with an enterprise server, you can:

  • Start the server associated with the project
  • Stop the server associated with the project
  • View the catalog
  • View the spool queues
  • Submit a job to the server associated with the project; make sure you have built the project first
  • Debug a job

Be careful not to mix different ways of starting and stopping servers; if you start a server from the IDE, you must stop it from the IDE.

Parent topic: Enterprise Server Integration with the IDE
Related information
To enable MSS for an enterprise server
To add a service for JCL
To add a service for integration with the Micro Focus Development Tools


JCL development

  • Introduction
    MSS enables you to build an MVS mainframe application on Enterprise Developer, deploy it to Enterprise Server on Windows or UNIX, and run it in Enterprise Server. You can maintain JCL files either in Enterprise Developer or Enterprise Server.
  • Printer Exit Modules
  • Processing DEST Information
  • ACCEPT and DISPLAY Handling
  • ASCII/EBCDIC
  • Enabling JOBLIB DD and STEPLIB DD Processing
  • Output Limitation Support
  • System Abend Codes
Parent topic: JCL Support


Introduction

An important part of an MVS application is the JCL jobstream that controls its execution. MSS provides facilities to support the use of batch JCL jobstreams on the PC or UNIX workstation. Within Enterprise Developer, you can:
  • Create new jobstreams
  • Scan the jobstreams for syntax errors and dependencies
  • Submit the jobstreams for running in an enterprise server and view the spool output files
A major objective of the JCL support is to keep the operations in MSS as similar as possible to those done on the mainframe. Thus in MSS, you can:
  • Use mainframe data set names in the jobstream, even though the data is held in a file on the PC or UNIX workstation
  • Process jobstreams as if they were being run on the mainframe

  • View and process the SYSOUT listing and any other printed output produced by the jobstream

  • Use the functions of the many mainframe batch utilities
Before you start to use the JCL support in MSS, you need to understand more about the following topics:
  • JCL jobstreams
  • Data sets
  • Application programs
  • The JCL Editor
    The JCL editor provides the features you need for optimised and efficient JCL editing.
  • JCL Jobstreams
  • Data Sets
  • Application Programs
Parent topic: JCL development


The JCL Editor

In addition to a standard text editor, the IDE offers a JCL editor that contains a number of features for efficient JCL editing.

To use the JCL editor double-click a file that is associated with the JCL file type. Alternatively, right-click the file you want to edit in the COBOL Explorer or Project Explorer view and click Open With > JCL Editor. The JCL editor provides the following features:
Note: The VSE dialect is not supported in this release.

Block Selection

Enables you to select or deselect specific blocks of text from your code. You can toggle the selection using the Toggle Block Selection Mode button [image] on the toolbar or shortcut keys Alt+Shift+A.

Breadcrumb Navigation

Context breadcrumbs are enabled by default. You can use the Toggle Context Breadcrumbs button ( Toggle Context Breadcrumbs) on the toolbar to switch the functionality on and off. The breadcrumbs navigation bar displays at the top of each JCL editor tab, and lets you quickly view and open JCL files and include files along the trail of files for the current file. You can also use the breadcrumb navigation for quick context switching between include files.

Code Templates

The JCL editor provides a means of inserting code templates, also referred to as snippets. The use of code templates accelerates the creation of well-formed code. A template gives you an outline of a statement or construct syntax, leaving you to fill in the parameters. Press Ctrl+Space in the editor to access the code template list using the content assist pop-up.

Available templates are displayed at the bottom of the statement list. Use the scroll bar in the content assist pop-up to find the template that you require. Click once on the template to view the full code template in a pop-up. Double-click the chosen template name to insert the code template into the editor at the current cursor location. This gives you the outline of the syntax, so you can fill in its components.

You can add more templates using the templates preference page by clicking Window > Preferences > Micro Focus > JCL > Editor > Templates. You can create new templates, edit and delete existing templates, as well as import and export templates as .xml files to share with other users.

Content Assist

Content assist in the JCL editor supports JCL language statements. Content assist provides editing features to help you write syntactically correct code and constructs. You can use content assist to complete words and lookup the required parameters for statements.

Press Ctrl+Space to trigger content assistance that is contextually appropriate to the code you are typing. For example, if you are typing a JCL statement and press Ctrl+Space, the list of applicable items appears in the pop-up list, with the best matches at the top and highlighted in the content assist pop-up. Related keywords and templates using the highlighted statement also appear in the pop-up list.

Content assist only offers assistance for the statements that are in scope, based on the current cursor position. There are no JCL content assist settings in the preferences.

Contextual Help

Dynamic help in the JCL editor provides context help for the JCL statements in your code. Highlight the desired statement in your code and press F1. To open the Help view and display reference information for the highlighted item, click Help > Show Contextual Help.

Find References

Enables you to find all references of an item declared in all included JCL files. Place the cursor on the item, right-click, select Find References. Alternatively press Ctrl+Shift+G. The Search tab displays all the references found in any included JCL files. You can explore the results returned. Double-clicking on the item in the Search tab will move the cursor to the position in the relevant file.

Folding

Clicking on the positive and negative icons in the left margin of the JCL editor reveals and hides code blocks respectively. Jobs, procedures and steps are all folded if they span multiple lines. You can hover over a folded section to show its content expanded in a pop-up.

Go To Definition

Enables you to navigate to where an item, declared in all included JCL files, is defined. Place the cursor on the item you want to find the definition of, right-click and select Go To Definition. Alternatively press F3. The cursor moves to the location of the definition; it also highlights the item in the Outline view.

Go to Matching Block/Bracket

You can use this feature to locate the bracket that matches the one at your current cursor position. To move the cursor to the matching bracket, right-click in the JCL editor, and then click Go to Matching Block/Bracket. Alternatively, press Ctrl+Shift+P.

Horizontal Rule

The horizontal rule runs along the top of the JCL editor window. It marks the columns with a tick and numbers them into groups of 10. This is helpful when column alignment is required in JCL code.

You can configure Eclipse to hide or show the horizontal rule. To do this, click Window > Preferences > Micro Focus > JCL > Editor and check Show horizontal ruler. Showing or hiding the horizontal rule affects all files open in a JCL editor tab.

Line Numbering

Line numbers help you to improve code navigation. Standard JCL line numbers are inserted immediately to the right of area B, in columns 73 - 80, starting by default at 00000100 at the first line, and incrementing by 100 lines by default.

You can specify the number of lines to increment. To do this, click Windows > Preferences > Micro Focus > JCL > Editor > Line Numbering and type an integer number of lines.

To number or renumber the lines in a JCL source file, right-click the source code in the JCL editor, and click Source > Renumber. Alternatively, click Renumber on the Eclipse toolbar.

To remove the JCL line numbers from source code, right-click the source code and click Source > Unnumber Alternatively, click Unnumber on the Eclipse toolbar.

Outline View

Shows the structure of the program you are editing which is useful for navigating large programs. Double-click on a statement to reposition the cursor to the respective line of code. You can also right-click an item in the outline and click Find References to display matches in the Search tab. You can hover over items in the outline to display a pop-up containing the item's parameters.

Program Outline View

Similar to outline view, but displays the structure for all included JCL files.

Quick Outline View

Right-click in the JCL editor and click Quick Outline or press the shortcut keys Ctrl+O. This shows a pop-up containing the structure of the code similar to the outline view. When you type while quick outline view is displayed you filter the list of displayed elements for easier navigation.

Remove Trailing Whitespace

By default, trailing whitespace after column 80 is removed when you save a JCL file. You can remove all trailing whitespace when you save your JCL file. To configure your preferences for removing trailing whitespace, click Window > Preferences > Micro Focus > JCL > Editor. In the Remove trailing whitespace group, click your preference.

To disable this feature, uncheck Remove trailing whitespace on save.

To remove all trailing whitespace when required, click Source > Remove Trailing Whitespace. Alternatively, right-click in the JCL editor, and then click Source > Remove Trailing Whitespace.

Show/Hide Whitespace Characters

Click the Show Whitespace Characters button ( Show Whitespace Characters) on the toolbar to toggle between showing and hiding whitespace characters in the editor. Whitespace characters include spaces, carriage returns, and end-of-line markers. Showing or hiding whitespace characters affects any JCL editor window you view.

Syntax Error Reporting

The code you type is parsed continuously to identify errors. The errors are underlined with red squiggly lines, and warnings are underlined with yellow squiggly lines. You can hover over an error to see information about the error in an error message tool tip.

Tasks

You can manage tasks by adding the default TODO or FIXME tags in the JCL code comments. Eclipse visualizes these tags in the Task tab. Any text that follows the TODO or FIXME tags appears in the task description. To view the Task tab, click Window > Show View > Tasks or Windows > Show View > Other, expand General, click Tasks, then click OK. Double-clicking on the line in the Task tab takes you to the highlighted line in the editor.

Both TODO and FIXME tag lines are marked on the left margin of the editor with a clipboard icon ( [image]). Rows in the Task tab that are tagged TODO are high priority tasks and are highlighted with an exclamation point ( [image]).

You can customize the tags from Window > Preferences > Micro Focus > JCL > Editor > Task Tags. You can add, remove or edit tags, specifying their priority as high, normal or low.

  • Customizing the JCL Editor
  • Configuring Background Parsing
  • Configuring Smart Edit Mode
Parent topic: Introduction


Customizing the JCL Editor

You can customize the editor from Window > Preferences > Micro Focus > JCL > Editor. Alternatively, you can right-click in the editor and select Preferences. You can change or customize the features such as colors, templates and typing. You can associate files with extensions other than .jcl with the JCL editor. See Window > Preferences > General > Editors > File Associations.

Parent topic: The JCL Editor


Configuring Background Parsing

The code you type is parsed continuously to identify errors. The errors are underlined with red squiggly lines.

CAUTION:
You can turn off background parsing, but many of the IDE features depend on it, including outline and colorized text. If it is switched off these features will not work and might cause unexpected problems.
Switching off or delaying background parsing when Eclipse is running
You can turn off background parsing in the Preferences dialog box (select Window > Preferences > Micro Focus > JCL > Editor and deselect Background parsing).

Parsing is triggered when there is a pause in editing code; by default this is 500 milliseconds. By keeping Background parsing selected and entering a larger value in the Trigger delay field, you can make sure your code is parsed less frequently, and improve performance when developing projects with large numbers of source files.

Parent topic: The JCL Editor


Configuring Smart Edit Mode

Smart edit mode controls the behavior of word wrapping and indentation in the different JCL areas. With it enabled, you can change the following configuration options in the Typing preferences dialog box: select Window > Preferences > Micro Focus > JCL > Editor > Typing.

Wrapping
  • Wrap code when source code area end is reached - lines wrap when you reach column 71.
  • Wrapping moves the text in the right hand area to the new line - any comments in the right-hand area stay in the right-hand area but move to the next line when wrapping from column 71.
  • Wrap lines when deleting forwards and backwards - when you press Delete after the last non-white space in the area, the line beneath moves up, and comments in the right-hand area stay with the associated line of code. Similarly, when you press Backspace in column 1, the current line moves up, and comments in the right-hand area stay with the associated line of code.
Indentation
  • Enter key and smart wrapping adjust the indentation on the new line - automatic indentation options.
  • Tab/Shift-Tab keys adjust the indentation based on the area margins - changes the way the Home and End keys move the cursor in the JCL editor. Pressing Home repeatedly first moves the cursor immediately before the first non-white space in the current area, then at the beginning of the area, or to the first non-white space in the preceding area. Pressing End repeatedly first moves the cursor immediately after the last non-white space in the current area, and then at the start of the following area.
Comments
  • Continue comments on to new line - checked by default.
Parent topic: The JCL Editor


JCL Jobstreams

You can run the same JCL jobstreams in MSS as you can on the mainframe. MSS checks the JCL statements for errors as far as possible. Several parameters, especially on DD statements, have no meaning in MSS running on Windows or UNIX and are ignored. This section describes the differences that apply when using JCL jobstreams in the MSS environment instead of the MVS mainframe environment.

MSS supports both MVS JCL and VSE JCL. The following sections describe the levels of support for MVS JCL and VSE JCL.

  • MVS JCL Support
  • VSE JCL Support
    This section lists the POWER and JCL statements that Enterprise Developer can process.
  • Special Characters in JCL Program-names
  • Character Sets
Parent topic: Introduction


MVS JCL Support

The following sections outline the features and statements in MVS JCL that are supported.

  • MVS JCL Features
  • MVS JCL Statements
Parent topic: JCL Jobstreams


MVS JCL Features

The following MVS JCL features are supported:

  • Instream procedures
  • Cataloged procedures
  • Symbolic parameters
  • EXEC statement overrides
  • JOBLIB and STEPLIB DD statements
  • DD statement overrides
  • Conditional execution (specified by IF, THEN, ELSE, and ENDIF statements)
  • Job restart after execution failure
  • Concatenated data sets
  • Instream data sets (preceded by a DD * or DD DATA statement)
  • Partitioned data sets
  • Generation data groups
  • Temporary data sets
  • Comments (indicated by //*)
  • Normal mainframe nesting limits (that is, 15 levels of nested procedures and 15 levels of nested INCLUDE statements)

The following MVS JCL features are not supported:

  • Multiple jobs in one jobstream
  • Program control statements (enclosed by CNTL and ENDCNTL statements)
  • Other special DD statements that are not relevant to the PC or that are implemented differently by MSS. These statements have the following DD names:
    • JOBCAT
    • STEPCAT
    • SYSABEND
    • SYSMDUMP
    • SYSUDUMP
    • SYSCHK
    • SYSCKEOV

More information about the MVS JCL statements supported by MSS is given later in this section.

MSS supports the running of MVS JCL jobstreams either directly or via the TSO SUBMIT command and the Micro Focus extension ASUBMIT. You can run these TSO commands with the IKJEFT01 utility.

Files containing MVS JCL jobstreams and cataloged procedures can be created on the PC or UNIX machine. Cataloged procedures should be stored as members of partitioned data sets, known as procedure libraries. The procedure libraries are defined to MSS in two different ways:

  • The libraries defined in the JCLLIB statement, for a single job
  • The libraries defined to MSS, for all jobs.

MSS searches these libraries in the order specified above.

When the job is submitted to an enterprise server for running , the effect depends on the setting of the TYPRUN parameter to the JOB statement as shown below:

TYPRUN=SCAN | The syntax is scanned
TYPRUN=COPY | The job stream is copied to a SYSOUT data set
TYPRUN=HOLD | Holding of the job until explicitly released for execution
No TYPRUN | The job is executed immediately, assuming resources are available
Parent topic: MVS JCL Support


MVS JCL Statements

For a full description of MVS JCL statements, please refer to the IBM OS/390 MVS JCL Reference.

The following MVS JCL statements are supported:
Statement | Description
DD | Defines the allocation and disposition of a data set
EXEC | Defines a job step, including the program or cataloged procedure to be run

IF

THEN

ELSE

ENDIF

Specifies conditional execution of MVS JCL statements
INCLUDE | Specifies where pre-defined MVS JCL statements are to be included in the jobstream
JCLLIB | Specifies procedure libraries and their search order
JOB | Defines a job. MSS supports only one job per jobstream
JOBLIB | Specifies private libraries to be searched for programs identified in EXEC statements
PROC | Defines the start of an instream MVS JCL procedure
PEND | Defines the end of an instream MVS JCL procedure
SET | Defines the values to be assigned to symbolic parameters
STEPLIB | Specifies private libraries to be searched for programs identified in EXEC statements
OUTPUT Specifies the parameters that the job entry subsystem is to use for printing a SYSOUT data set. MSS supports all parameters with the following exceptions. Unsupported parameters, that are parsed but ignored:
  • MAILTO
  • MAILFROM
  • MAILCC
  • MAILBCC
  • REPLYTO
  • AFPPARMS
  • AFPSTATS
  • USERPATH
Unsupported parameters, that result in an error:
  • COPYCNT
  • MERGE

The following MVS JCL statements are not supported. They are checked only for correct syntax.

Statement | Description
COMMAND | Issues commands to MVS and JES2
CNTL | Defines the start of a set of program control statements
ENDCNTL | Defines the end of a set of program control statements
XMIT | Transmits records from JES3
Parent topic: MVS JCL Support
Related information
IBM OS/390 MVS JCL Reference


VSE JCL Support

This section lists the POWER and JCL statements that Enterprise Developer can process.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
  • Differences
    These are the differences in the Micro Focus support for VSE JCL.
  • External Features
    Enterprise Developer provides a number of external features that support the VSE solution.
  • VSE JCL Statements
    These are the VSE JCL statements that Enterprise Developer supports.
  • POWER Statements
  • VSE JCL Configuration Files
Parent topic: JCL Jobstreams


Differences

These are the differences in the Micro Focus support for VSE JCL.
DD persistence
DD’s cannot persist across a job boundary, except for standard labels.
Development environment
There is no VSE development environment (such as ICCF, DITTO or LIBR). The development work is done in the development environment - typically Visual Studio or Eclipse. COBOL executables are generated in the usual Micro Focus way.

There is no support for Compile/Link or Compile/Go using JCL. Enterprise Developer, however, supports ICCF type libraries for inclusion within JCL.

Dynamically-entered JCL
JCL statements can only be executed as part of a submitted file; that is, you cannot enter VSE JCL statements dynamically at the operator console.
JCL and POWER jobs
There must be a single JCL job within a POWER job and a single POWER job in a submitted JCL file.
Output listings
Output listings, such as joblog, do not have a VSE look and feel.
Partitions
There is no support for VSE BACKGROUND, FOREGRAND, STATIC or DYNAMIC partitions.
TAPE support
There is no TAPE support in PC environment. TLBL statements are processes and the associated datasets are being written to disk. For datasets defined as TAPE, some tape specific information from the TLBL statements is held on the catalog so they can be identified and written to specific directories using the default allocation override function which is described separately.
Parent topic: VSE JCL Support
Related information
VSE JCL and POWER Statements
POWER Statements


External Features

Enterprise Developer provides a number of external features that support the VSE solution.
  • CICS, IMS and DB2 are all supported.
  • JCL USER EXIT - provides a means of passing control to a user written exit program at various stages in the job execution when variables associated with the job can be viewed and updated.
  • Printing - SPOOL files are made available to a printer exit along. For VSE, all associated $$ LST and $$PUN settings are available. See Micro Focus Batch Scheduler Integration.
  • MVS JCL - you can submit jobs that contain either MVS JCL or VSE JCL through the same server. (MVS and VSE JCL must not be mixed in the same job). The system determines the type of JCL being submitted and processes it accordingly. This provides access to all the MVS utilities and MVS-only processing, for example Generation Data Groups.
  • Restart - see Micro Focus Batch Scheduler Integration.
  • Scheduling - it is possible to incorporate third-party scheduling. See Micro Focus Batch Scheduler Integration.
  • Security - see Micro Focus Batch Scheduler Integration.
Parent topic: VSE JCL Support
Related concepts
Micro Focus Batch Scheduler Integration


VSE JCL Statements

These are the VSE JCL statements that Enterprise Developer supports.
  • *
    Identifies a comment statement.
  • /.
    Identifies a label statement.
  • /*
    Identifies an end of data file statement.
  • /&
    Indicates an end of job statement.
  • /+
    Identifies an end of procedure statement.
  • ASSGN
    Assigns a logical I/O unit to a physical device, either directly or using another logical I/O.
  • DATE
    Places the specified date temporarily in the communication region. Parsed but not processed.
  • DLBL
    Associates a DD name with a dataset.
  • EXEC
    Executes a program, a JCL procedure or a REXX procedure.
  • EXTENT
  • GOTO
  • IF
    If the specified expression evaluates to TRUE, then the following statement is executed. If the expression evaluates to FALSE, then the following statement is skipped.
  • JOB
  • LIBDEF
    Defines which libraries are to be searched for members of a specified type.
  • LIBDROP
    Resets the library search paths set up by previous LIBDEF statements.
  • LIBLIST
    Displays the current library definitions on SYSLOG or SYSLST.
  • MTC
    Enables you to perform tape operations.
  • ON
    ON is a global condition function. During the execution of a JOB which includes ON statements, the test in the ON statement is performed after every step.
  • OPTION
    Changes job control options for the duration of the job.
  • PAUSE
    Halts execution and waits for a reply from the operator.
  • PROC
    The first statement in a cataloged procedure.
  • PWR
    Power commands are not supported within the JCL stream.
  • RESET
    Resets temporary LU assignments back to defaults.
  • SETPARM
    Stores a symbolic parameter and value.
  • SETPFIX
    Guarantees real storage will be available.
  • TLBL
    Associates a DD name with a tape dataset.
  • UPSI
    Sets the 8 switches in the UPSI (User Program Switch Indicator) byte.
  • ZONE
    Sets the time zone. Parsed but not processed*.
Parent topic: VSE JCL Support


*

Identifies a comment statement.
Parent topic: VSE JCL Statements


/.

Identifies a label statement.
Parent topic: VSE JCL Statements


/*

Identifies an end of data file statement.
Parent topic: VSE JCL Statements


/&

Indicates an end of job statement.
Parent topic: VSE JCL Statements


/+

Parent topic: VSE JCL Statements


ASSGN

Assigns a logical I/O unit to a physical device, either directly or using another logical I/O.

Syntax:

      *---------------------------------------------------------------
      *--- ASSGN OPERANDS
      *--- // ASSGN SYSxxx,
      *---         (address or address list or
      *---          UA or IGN               or
      *---          SYSyyy                  or
      *---          device class            or
      *---          device type),
      *---          and additionally for DISK devices
      *---          [TEMP or PERM],[VOL=volume],{SHR]
      *---          and additionally for TAPE devices
      *---         ,[mode],[ALT],[PERM],[VOL=VOLUME]
      *---------------------------------------------------------------

Where:

SYSxxx
The logical unit name: SYSRDR, SYSIPT, SYSIN, SYSPCH, SYSLST, SYSOUT, SYSLNK, or SYSLOG.

Or, when xxx is numeric, aprogrammer logical unit. For example, SYS040 for a program containing select report1 assign to SYS040 in the file control section.

address list
A physical device as defined in the VSE system configuration file (described separately).
UA or IGN
Parsed but not processed.
UA
Unassigns a logical unit.
IGN
Unassigns the specified logical unit and ignores any subsequent logical IOCS command.
SYSyyy
Associates SYSyyy with the same device as SYSxxx.

One of SYSLST, SYSOUT, SYSLNK, or SYSLOG.

device class
Parsed but not processed.

Use this specification if you are interested only in the specific class of device.

device type
Parsed but not processed.

Use this specification, if you are interested only in the specific type of device.

ALT
Parsed but not processed*.

Indicates alternate tape unit.

PERM
Parsed but not processed.

Indicates that this DLBL definition can be cleared only with an explicit CLEAR request.

VOL
Parsed but not processed*.

VOL=volser - specifies the volume serial number of the required device.

SHR
Parsed but not processed*.

For disk devices only. Means that the unit can be assigned to a disk device which is already assigned.

Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


DATE

Places the specified date temporarily in the communication region. Parsed but not processed.

Syntax:

    *---------------------------------------------------------------
    * DATE operands
    * // DATE   mm/dd/yyyy or -dd/mm/yyyy		parsed but not processed
    *---------------------------------------------------------------
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


DLBL

Associates a DD name with a dataset.

Syntax:

      *---------------------------------------------------------------
      *--- DLBL OPERANDS
      *--- // DLBL filename
      *---          file-id
      *---          date
      *---          codes
      *---          DSF
      *---          BLKSIZE
      *---          BUFND
      *---          BUFNI
      *---          BUFSP
      *---          CAT
      *- --         CISZ
      *- --         DISP
      *---          RECORDS
      *---          RECSIZE
      *---------------------------------------------------------------

Where:

Operand | Description
filename | DD name
file-id A unique name which identifies a dataset in the system catalog

DSNs that start with a $$$ prefix are treated as temporary ones - for example:

// DLBL filename, '$$$.xxx.yyyy'
date | Retention period in days (0 to 9999) or Julian date
codes | Parsed but not processed* | VSAM SD or DA
DSF | Parsed but not processed* | A data-secured file
BLKSIZE | Block size
BUFND | Parsed but not processed* | Number of I/O buffers
BUFNI | Parsed but not processed* | Number of index buffers
BUFSP | Parsed but not processed* | Number of bytes allocated for buffer space.
CAT | Parsed but not processed* | Catalog name; single system catalog in MF
CISZ | Parsed but not processed* | Control Interval size
DISP | Disposition opened, after normal step end, after abnormal step end
RECORDS | Parsed but not processed* | Number of records for primary and secondary space allocation
RECSIZE | Average record length
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


EXEC

Executes a program, a JCL procedure or a REXX procedure.

Syntax:

      *---------------------------------------------------------------
      *--- EXEC OPERANDS
      *---           format 1 to execute a program
      *--- // EXEC [PGM=]
      * --           program-name
      *---          REAL
      *---          SIZE=’value’
      *---          GO
      *---          PARM=’value’
      *---------------------------------------------------------------

Where:

program-name
Name of the program to be executed.
REAL
Execute in real storage. Parsed but not processed*.
SIZE
Size of the program in the partition. Parsed but not processed*.
GO
To compile, link and run in one step. Parsed but not processed*.
PARM
Enables you to pass a parameter to an application program.

Syntax:

      *---------------------------------------------------------------
      *--- EXEC OPERANDS
      *---           format 2 to execute a procedure
      *--- // EXEC PROC=procedure-name
      *---                            parm=parm-value
      *---------------------------------------------------------------

Where:

procedure-name
Name of the procedure to be executed.
parm and parm-value
Name of a symbolic parameter and a value to be substituted within the procedure.

Syntax:

      *---------------------------------------------------------------
      *--- EXEC OPERANDS
      *---           format 3 to execute a rexx procedure
      *--- // EXEC REXX=procedure-name
      *---
      *---------------------------------------------------------------

REXX is supported but cannot be executed in this way. You must use IKJEFT01 (TSO in batch) to invoke REXX in the same way as in MVS or z/OS.

Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


EXTENT

Syntax:

      *----------------------------------------------------------------
      *    EXTENT OPERANDS
      *    // EXTENT [logical-unit],
     *       [volser],
      *      [type],
      *       [seq-number],
      *       [relative-track | block ],
      *       [number of tracks | blocks ],
      *       [split-cylinder-track]
      *----------------------------------------------------------------

Where:

logical-unit
Logical unit (SYSxxx) of the volume for which this extent is effective. Parsed but not processed*.
volser
Logical unit (SYSxxx) of the volume for which this extent is effective. Parsed but not processed*.
type
Single character that indicates the type of extent. Parsed but not processed*.
relative-track or block
Number of the track where the extent is to begin. Parsed but not processed*.
number of tracks or blocks
Number of tracks to be allocated to the file. Parsed but not processed*.
split-cylinder-track
Upper track number for split cylinder in SAM files. Parsed but not processed*.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


GOTO

Syntax:

      *----------------------------------------------------------------
      *    GOTO OPERANDS
      *   // GOTO (label|$EOJ)
      *----------------------------------------------------------------

Where:

label or $EOJ
All statements in the following job stream are skipped up to the specified label statement.
Parent topic: VSE JCL Statements


IF

If the specified expression evaluates to TRUE, then the following statement is executed. If the expression evaluates to FALSE, then the following statement is skipped.

Syntax:

      *----------------------------------------------------------------
      *    IF OPERANDS
      *   // IF
      *      var1 + operator val
      *      ( {AND/OR}
      *      var2 + operator val)
      *     THEN
      *----------------------------------------------------------------

Where:

var
A $RC, $MRC or a parameter name.
operator
EQ or =, NE or ^=, GT or >, LT or <, GR or >+, LE or <+
val
Number to be compared to return code $RC or $MRC, or a character string to be compared to parameter name.
Parent topic: VSE JCL Statements


JOB

Syntax:

   *---------------------------------------------------------------
   *--- JOB OPERANDS
   *--- // JOB jobname accounting info
   *---------------------------------------------------------------

Where:

jobname
1 - 8 characters identifying the job. Defaults to NO NAME.
accounting info
Saved and used as required.
Parent topic: VSE JCL Statements


LIBDEF

Defines which libraries are to be searched for members of a specified type.

Syntax:

      *-----------------------------------------------------------------------------
      *   LIBDEF OPERANDS
      *--- // LIBDEF type[
      *                  [,SEARCH=(lib1.slib1......lib15,slib15]
      *                  [,CATALOG=lib.slib]
      *                  [,TEMP|PERM]
      *-----------------------------------------------------------------------------

Where:

Type
Either PHASE, OBJ, SOURCE, PROC, * or DUMP but only PROC is supported. The other options are parsed but not processed*.
SEARCH
Sets up a search chain of up to 15 libraries to be searched.
CATALOG
Library to receive output from a linkage editor or a dump. Parsed but not processed*.
TEMP
LIBDEF in effect for the duration of a JOB.
PERM
LIBDEF in effect permanently. Parsed but not processed*.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


LIBDROP

Resets the library search paths set up by previous LIBDEF statements.

Syntax:

      *-----------------------------------------------------------------------------
      *   LIBDROP OPERANDS
      *--- // LIBDROP type[
      *                  [,SEARCH=(lib1.slib1......lib15,slib15]
      *                  [,CATALOG=lib.slib]
      *                  [,TEMP|PERM]
      *-----------------------------------------------------------------------------
Parent topic: VSE JCL Statements


LIBLIST

Displays the current library definitions on SYSLOG or SYSLST.

Syntax:

*-----------------------------------------------------------------------------
*   LIBLIST OPERANDS
* // LIBLIST type[,BG | Fn | * ]
*-----------------------------------------------------------------------------

Where:

type
Type of library chain to be listed. Parsed but not processed.
BG, FN or *
Type of partition for which the libraries are listed. Parsed but not processed*.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


MTC

Enables you to perform tape operations.

Syntax:

*---------------------------------------------------------------
*     MTC OPERANDS
*     // MTC operation,
*        unit[,count]
*---------------------------------------------------------------

Where:

Operation
Parsed but not processed*.
Unit
Parsed but not processed*.
Count
Parsed but not processed*.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


ON

ON is a global condition function. During the execution of a JOB which includes ON statements, the test in the ON statement is performed after every step.

Syntax:

      *---------------------------------------------------------------
      *--- ON operands
      *--- // ON  condition [OR|AND condition]
      *        [GOTO label | CONTINUE ]
      *---------------------------------------------------------------
condition
Specifies the condition under which the action is to be taken. Takes any of the following forms:
  • $RC operator n - compares the return code to the numeric value n.
  • $CANCEL, if the cancel command has been given. Parsed but not processed*.
  • $ABEND, if the step has abended.
GOTO
Label to go to if the condition is satisfied.
CONTINUE
Continue processing at next step.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


OPTION

Syntax:

*------------------------------------------------------------------------------------------
*   OPTION operands
*--- // OPTION [PARSTD | PARSTD=ADD | STDLABEL | USRLABEL ]
*--- --------------------------------------------------------------------------------------

All operands are parsed but not processed*.

Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


PAUSE

Syntax:

*----------------------------------------------------------------------------------------------
*    PAUSE operands
*    // PAUSE multi-word message
*----------------------------------------------------------------------------------------------

This is implemented using a user exit which can be amended to suit the application. The user exit is a program called MFPAUSE.

A sample program is included which write a message to the console and waits for a reply.

Parent topic: VSE JCL Statements


PROC

The first statement in a cataloged procedure.

Syntax:

*----------------------------------------------------------------------------------------------
*    PPOC
*    // PROC parameter-name=value
*                   parameter-name=value…
*----------------------------------------------------------------------------------------------

Where:

parameter-name
Specifies the name of a symbolic parameter and assigns a value.
Parent topic: VSE JCL Statements


PWR

Power commands are not supported within the JCL stream.

Syntax:

 *------------------------------------------------------------
 *--- // PWR PRELEASE RDR,JOBNAME
 *--- // PWR PHOLD
 *---    POWER command
 *---------------------------------------------------------------

There are a number of options available instead:

  • Use the ESMAC job entry and job control system to enter the commands
  • Use a job scheduler to effect condition control of job hold and release
  • Use a provisional user exit to process the PWR command

There is a user exit program, MFJESPWR. This program verifies the syntax of the PWR statement and reports in the JESYSMSG whether a PWR was successful or not.

Parent topic: VSE JCL Statements


RESET

Resets temporary LU assignments back to defaults.

Syntax:

*   RESET Operands
*    // RESET  [ALL | SYS | PROG | SYSxxx ]
*---------------------------------------------------------------

Where:

ALL
Resets all LU assignments.
SYS
Resets temporary system LU assignments.
SYSxx
Resets all temporary assignments for specified LU.
PROG
Resets all programmer LU assignments.
Parent topic: VSE JCL Statements


SETPARM

Syntax:

*----------------------------------------------------------------------------------
*     SET operands
*     //[name] SET
*      symbol=value[,symbol=value...]
*      [comments]
*----------------------------------------------------------------------------------

Where:

symbol=value
Sets the named symbolic parameter to the specified value for use elsewhere in the JCL stream.
comments
Read-only, not processed.
Parent topic: VSE JCL Statements


SETPFIX

Guarantees real storage will be available.

Syntax:

*---------------------------------------------------------------
*--- // SETPFIX LIMIT=[x|(x,y)|(,y)[TEMP|,PERM]]
*---------------------------------------------------------------

All parameters are parsed but not processed*.

Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


TLBL

Associates a DD name with a tape dataset.

Syntax:

      *---------------------------------------------------------------
      *--- TLBL OPERANDS
      *--- // TLBL filename
      *---          file-id
      *---          date
      *---          file-serial-number
      *---          volume-sequence-number
      *---          file-sequence-number
      *---          generation-number
      *---          version-number
      *- --         DISP
      *---------------------------------------------------------------
Enter the actual information in this section (optional).

See also differences appendix at the end of this section

Where:

filename
The DD name.
file-id
A Uuique name which identifies a dataset in the system catalog.
date
The retention period in days (0 to 9999) or Julian date
file-serial-number
The serial number of the first reel of the file.

Parsed but not processed*.

volume-sequence--number data-secured file
The volume at which you want to start processing.

Parsed but not processed*.

file-sequence-number
The volume at which you want to start processing.

Parsed but not processed*.

generation-number
Generation number of file to be processed.

Parsed but not processed*.

DISP
Disposition opened, after normal step end, after abnormal step end.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


UPSI

Sets the 8 switches in the UPSI (User Program Switch Indicator) byte.

Syntax:

      *---------------------------------------------------------------
      * UPSI OPERANDS
      *    //  UPSI xxxxxxxx
      *------------------------------------------------------------------

Where:

xxxxxxxx
1 to 8 characters corresponding to the bit switches. Valid values for each character are:
0
Set switch to off.
1
Set switch to on.
X
Leave unchanged.
Parent topic: VSE JCL Statements


ZONE

Sets the time zone. Parsed but not processed*.
Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.
Parent topic: VSE JCL Statements


POWER Statements

Note: The command and operand combinations listed in these topics are supported unless indicated as "parsed but not processed". Where indicated, this means:
  • Parsed but not processed - indicates that the command and the operand are not supported, however, Enterprise Developer parses it and, if it fails validation, a JCL error is generated.
  • Parsed but not processed* - indicates that a number of the operands for JCL and POWER commands (for example, any tape or volume-specific operands) do not apply in the Micro Focus Enterprise Developer environment. See General Differences.

The POWER statements supplement VSE JCL with the following functions:

  • SPOOLING
  • SCHEDULING
  • Operator commands

Job Entry Control Language

Begin with the prefix $$.

* $$ JOB

* $$ JOB sets job-wide POWER parameter values.

Statement | Support Level
JNM=job-name |
BLDG= | parsed but not processed
BRTNC= | parsed but not processed
CLASS=jobclass |
DEPT= | parsed but not processed
DISP= | parsed but not processed
DSKTIN= | parsed but not processed
ECHO= | parsed but not processed
ECHOU= | parsed but not processed
EOJMSG= | parsed but not processed
LDEST= | parsed but not processed
NETACCT= | parsed but not processed
NTFY=notify |
PDEST= | parsed but not processed
PRI=priority |
PROGR= | parsed but not processed
PWD=password |
ROOM= | parsed but not processed
SEC= | parsed but not processed
SYSID= | parsed but not processed
PDEST= | parsed but not processed
USER= | parsed but not processed
XDEST= | parsed but not processed

* $$ LST

LST spool files are available to the printer exit. See the description of * $$ PUN.

* $$ PUN

PUN spool files are available to the printer exit. All of the following operands are parsed, saved and made available to the printer exit:

Operand
BRTNC=YES|NO
BURST=
CHARS=
CLASS=class
CMPACT=name|NO
COPY=copies
COPYG=
DEST=node_id,user-id,subsys)
DFLT=
DISP=disposition
DIST=dist-code
FCB=phasename
FLASH=
FNO=formnumber
FORMDEF=
JNM=
JSEP=n,option
LST=lstaddr
LTAB=linetab
MODIFY=
PAGEDEF=
PRMODE=value
PRI=priority
PURGE=NO
PUN=
PWD=password
RBC=norbc
RBM=norbm1,norbm2
RBS=norbs
REMOTE=remote-id
SYSID=n
TADDR=
UCS=
USER=user-info

* $$ SLI

$$ SLI starts a source library inclusion. A member from a VSE library or an ICCF library is included in the job prior to submission to the reader queue.

     *--- POWER SLI CARD PARAMETERS
     *--- * $$ SLI ICCF=(member-name),LIB=(nnnn)
     *---          or
     *--- * $$ SLI MEM=member-name[.type],S=lib.sublib,sublib[.bookname]
     *---                               up to three sub libraries

Where:

ICCF
member-name will be included from the library MFE.VSE.ICCF.LIBnnnn
SLI MEM
member-name will be included from first sublib where it is found.

* $$ EOJ

Power end-of-job card.

Scheduling

See Micro Focus Batch Scheduler Integration for more.

Operator commands

Various operator commands, such as PALTER, PDELETE, are used to control the processing of jobs under POWER.

The functionality is available using the ESMAC operator console, using scheduling or using the JCL user exit. See ESMAC.

Parent topic: VSE JCL Support
Related concepts
Micro Focus Batch Scheduler Integration
ESMAC


VSE JCL Configuration Files

At system start-up, VSE can set a number of values that are available to any job run on the system until shut down. MSS emulates this behavior with the use of a configuration file. You can use the configuration file to specify information about the following:

  • Devices. These can be designated as Printers, Punches, Tapes, Readers or Disks.
  • Logical Units. SYSxxx (where xxx is a 3 digit number) or one of the standard logical devices SYSIPT, SYSLST etc.
  • Standard labels. Commonly-used file names and the associated data sets can be set so that no DLBL statement for this filename/data set name is necessary in the JCL decks; the file is automatically allocated.

MSS reads the configuration file at the start of each job, so if you run a job then modify the configuration file, running the job again will pick up the modified configuration file.

  • Structure of a VSE JCL Configuration File
  • Specifying the Location of the VSE JCL Configuration File
  • Example VSE JCL Configuration File
Parent topic: VSE JCL Support


Structure of a VSE JCL Configuration File

A VSE JCL configuration file is a text file that contains a number of name-value pair entries, with each entry on a separate line. Blank lines or lines beginning with an asterisk (*) are treated as comment lines.

The format of the name-value pair entries are shown below.

For devices:

device_id      id
device_type    type

where:

id | is a three-digit code specifying the device address
type | is one of PRINTER, READER, PUNCH, DISK or TAPE.

For logical units:

assgn_lu        lu
assgn_device    device

where:

lu | is the logical unit to use.
device | is the device to assign to the logical unit lu.

For standard labels:

dlbl_dd         dd
dlbl_dsn        dsn

where:

dd | is the label to use.
dsn | is the data set name to assign to the label dd.
Note: There is an addtional name-value pair entry for defining partitions, but specifying it has no effect.
Parent topic: VSE JCL Configuration Files


Specifying the Location of the VSE JCL Configuration File

To make a VSE JCL configuration file available to MSS you specify its location using the VSE_STARTUP_CFG environment variable. For example, if you create the configuration file in c:\setup\vseconfg.cfg (on Windows) /home/setup/vseconfg.cfg (on UNIX), you would set VSE_STARTUP_CFG as follows:

SET VSE_STARTUP_CFG=c:\setup\vseconfg.cfg
VSE_STARTUP_CFG=/home/setup/vseconfg.cfg
export VSE_STARTUP_CFG
Parent topic: VSE JCL Configuration Files


Example VSE JCL Configuration File

* ========================================================================
* =     VSE SYSTEM START-UP
* ========================================================================
* ========================================================================
* =     devices
* ========================================================================
device_id        02A
device_type      PRINTER
*
device_id        02B
device_type      PRINTER
*
device_id        02C
device_type      PRINTER
*
device_id        02D
device_type      PRINTER
*
device_id        02E
device_type      PUNCH
*
device_id        02F
device_type      READER
*
device_id        02G
device_type      INTRDR
*
device_id        42E
device_type      PRINTER
*
device_id        43E
device_type      PRINTER
*
device_id        44E
device_type      PRINTER
*
device_id        45E
device_type      PRINTER
*
device_id        46E
device_type      PRINTER
*
device_id        020
device_type      DISK
*
* ========================================================================
* =     permanent assignments
* ========================================================================
*
assgn_lu         SYSIPT
assgn_device     02F
*
assgn_lu         SYSRDR
assgn_device     02G
*
assgn_lu         SYSLST
assgn_device     02A
*
assgn_lu         SYS001          SYSxxx logical unit
assgn_device     02B             cuu    device (device1 to device6)
*
assgn_lu         SYS002
assgn_lu_2       SYS001
*
assgn_lu         SYS002
assgn_lu_2       SYSLST
*
assgn_lu         SYSPCH
assgn_device     02E
* ========================================================================
* =     standard labels
* ========================================================================
 dlbl_dd         CMAST
 dlbl_dsn        CUSTOMER.MASTER.FILE
* ========================================================================
* =     Default In-stream input file.
* =       MVS PROGS these programs expect SYSIN and SYSPRINT
* =       by default. Max allowed = 100. IDCAMS, SORT and IPCPBTCH
* =       are assumed.
*
 USE_SYSIN       IEBGENER
 USE_SYSIN       MFJMATCH
* ========================================================================
*       POWER JOB DISP and LST DISP statements.
*         * $$ JOB DISP (hold or execute, delete or retain)
*         and
*         * $$ LST DISP (print or hold, delete or retain or spool to tape)
*         are normally parsed and ignored. If these options are set to 'Y'
*         then
*           the JOB DISP will override the JOB CLASS
*           the LST DISP will override the LST CLASS
*         so that the DISP processing can be emulated to some extent
*         via appropriate use of the CLASSES
*
 JOB_DISP        N
 LST_DISP        N
* ========================================================================
*      Controlling which DLBL and TLBL assignments are displayed.
*        By default all the current DLBL assignments will display in the
*        log for every step. Those which were not explicitly assigned
*        in the JCL for the current step will be preceded by ## and can be
*        suppressed by including the following line
  SHOW_##_ASSIGNS N
* ========================================================================
*      Controlling which messages are displayed on the log.
*        The following parameters will set values for the
*        MVS MSGLEVEL statement and message parameters respectively.
*        These control which JCL statements and messages appear in the log
 MESSAGE_LEVEL1  0                      valid values are 0,1,2
 MESSAGE_LEVEL2  0                      valid values are 0,1
* ========================================================================
*      Validation
*        If the config file fails validation the following message will
*        appear on the console:
*     JCLCM0198I JOB01208 ???????? VSE CONFIG FILE - FAIL CODE RC hh:mm:ss
* ========================================================================
* Values for the reason code (RC) are as follows:
*	01	Mismatched field name and value.
*	02	Too many devices specified - limit is 255
*	03	Device ID error
*	04	Device Type error
*	05	Too many assigns - limit is 300
*	06	Invalid ASSGN_LU_1
*	07	Invalid ASSGN_LU_2
*	08	Invalid ASSGN_DEVICE
*	09	Invalid DLBL or TLBL
*	10      not used
*	11	Invalid DLBL or TLBL
*	12 	System error
*	13      DLBL or TLBL label error
*	14	SHOW_##_ASSGNS error
*	15	MESSAGE_LEVEL1 error
*	16	MESSAGE_LEVEL2 error
*	17      Record with no valid keyword found
*	18, 19, 20 ,21	Unspecified Parse error
*	22	Config file OPEN failed - check VSE_STARTUP_CFG is correct
*	23	Config file READ failed
* ========================================================================
Parent topic: VSE JCL Configuration Files


Special Characters in JCL Program-names

MSS validates JCL program-names using IBM's list of valid characters. Valid characters in this list are @ # and $, although in some codepages the conversion of these characters causes incompatibilities with the name validation. If you experience problems using any of these special characters in the name of a JCL program, you should report these to Micro Focus.

Parent topic: JCL Jobstreams


Character Sets

You can run JCL applications on Enterprise Server either in EBCDIC or ASCII.

Parent topic: JCL Jobstreams
Related information
Character Sets


Data Sets

Support is provided for most mainframe data set organizations and record formats, as described in the topic Advanced Data Set Information .

Support is also provided for temporary data sets and in-stream data sets included in the jobstream.

Parent topic: Introduction
Related information
Advanced Data Set Information


Application Programs

MSS emulates the interface between application programs and MVS in order to allocate data sets and pass parameters. These facilities are described below.

  • Allocating Data Sets
  • Passing Parameters
Parent topic: Introduction


Allocating Data Sets

MVS provides a direct connection between the filename used in the program and the corresponding data set name used in the JCL. For example, for SYSUT1 in a COBOL program:

SELECT INFILE ASSIGN TO UT-S-SYSUT1

connects to

//SYSUT1 DD DSN=DSNAME1,DISP=OLD

and allocates to the program the PC file representing the data set named DSNAME1.

And, for SYSUT2:

SELECT OUTFILE ASSIGN TO UT-S-SYSUT2

connects to

//SYSUT2 DD DSN=DSNAME2,DISP=(NEW,CATLG),...

and allocates to the program a PC file representing the data set named DSNAME2. The file is created and cataloged automatically when the jobstream is run.

Parent topic: Application Programs


Passing Parameters

Parameters specified in the JCL PARM parameter are passed to the program using the same rules as the mainframe. Options specified in the parameters string are separated from any application parameters by a slash (/) character. For example:

PARMS(application-parameters/run-time-options)

The linkage area used when passing parameters is:

01 PARM.
     03 PARM-LENGTH    PIC 9(4)   COMP.
     03 PARM-DATA      PIC X OCCURS 100.
Parent topic: Application Programs
Related information
Passing Parameters


Printer Exit Modules

Enterprise Server JCL support provides the capability to view and browse job and report output using a browser based SDSF-like spool viewer. It does not include any other output or document management software per se, but instead allows you to utilize printer exit modules to integrate its batch printing capabilities with other third-party or external print subsystems.

A printer exit module (often abbreviated as simply printer exit) is a program that you can associate with a batch printer Server Execution Process (SEP). Instead of the SEP writing the output directly to a printer, it passes the output to the specified printer exit module. The printer exit module can then process the output before printing it. You might, for example, write an exit to present figures using graphical elements such as pie charts.

You can specify a unique printer exit module for each batch printer SEP, which means that you can set up specialized output processing for each output class if you wish. Printer exit modules have full access to related OUTPUT statement information contained in the JCL including destination, copies, routing, and form definition.

  • Writing a Printer Exit
Parent topic: JCL development


Writing a Printer Exit

An example of a printer exit module, sampprnx.cbl, is provided in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits /esjcl directory by default. This example simply takes each line and calls the COBOL run-time system's print routines to print it.

Printer exits need not be written in COBOL, but they must handle parameters as illustrated in sampprnx. These parameters are defined and documented in the cascbprn.cpy copybook. COBOL printer exits must be compiled with the non-mainframe dialect, which implies CHARSET(ASCII). They must be also built as an .int, a .gnt, or a .dll.

The linkage section of sampprnx, and the cascbprn.cpy are shown below.

linkage section.
 copy 'cascbprn.cpy' replacing ==(ws)== by ==lk==.
 01 lk-catalog-rec.
  copy 'mvscatlg.cpy' replacing ==(TAG)== by ==lk==.
 01 LK-OUTPUT.
  copy mvsdout  replacing ==()== by ==LK-OUTPUT==.
 01 LK-SPOOL.
  copy 'spool.cpy' replacing ==(tag)== by ==lk==.

       01  (ws)-prn-exit-interface.
           *>  What is the format of the structure used to call the
           *>  printer exit.  Will change with major revisions to this
           *>  Data Structure.
           03  (ws)-prn-version                     pic x(4) comp-5.
               88  (ws)-prn-current-version-88      value 1.
           *>  The printer exit is driven once as the batch printer SEP
           *>  starts, once for every print job, and once when the batch
           *>  printer is shut down.
           03  (ws)-prn-command                     pic x    comp-5.
               88  (ws)-prn-exit-init-88            value 0.
               88  (ws)-prn-exit-print-88           value 1.
               88  (ws)-prn-exit-term-88            value 2.
           *>  For the requested print job.  (ws)-prn-exit-print-88
           *>  what is the character set of the data being printed.
           03  (ws)-prn-char                        pic x.
               88  (ws)-prn-char-ascii-88           value 'A'.
               88  (ws)-prn-char-ebcdic-88          value 'E'.
               88  (ws)-prn-char-unknown-88         value '?'.
           *>  This is the file status returned by driving the procedure
           *>  pointers:
           *>              (ws)-prn-sysout-open-pptr
           *>              (ws)-prn-sysout-read-next-pptr
           *>              (ws)-prn-sysout-close-pptr
           *>
           03  (ws)-prn-sysout-status               pic x(2).
               88  (ws)-prn-sysout-status-ok-88     value '00'.
               88  (ws)-prn-sysout-status-eof-88    value '10'.
      ***--------------------------------------------------------------*
           *>  Procedure pointer to drive the open of the sysout dataset
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-sysout-open-pptr            procedure-pointer.
           *>  Procedure pointer to a read of the sysout dataset
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-sysout-read-next-pptr       procedure-pointer.
           *>  Procedure pointer to drive the close of the sysout dataset
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-sysout-close-pptr           procedure-pointer.
           *>  Procedure pointer to allow a message to be driven to the
           *>  console.  (all functions)
           03  (ws)-prn-message-pptr                procedure-pointer.
           *>  Procedure pointer to retrieve the next OUTPUT statement.
           *>  Returns a null (ws)-prn-output-record-ptr if none are
           *>  available.
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-output-read-next-pptr       procedure-pointer.
           03                                       procedure-pointer.
           03                                       procedure-pointer.
      ***--------------------------------------------------------------*
           *>  A pointer to the data structure contained in Spool.cpy
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-spool-record-ptr            pointer.
           *>  A pointer to the data structure contained in mvscatlg.cpy
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-catalog-record-ptr          pointer.
           *>  The printer handle for the printer assigned to the this SEP
           03  (ws)-prn-printer-handle              pic x(4) comp-5.
           *>  The LRECL of the dataset being printed.
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-lrecl                       pic x(4) comp-5.
           *>  The Maximum LRECL of the dataset being printed.
           *>  Same as ws-prn-lrecl.
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-lrecl-max                   pic x(4) comp-5.
           *>  The Minimum LRECL of the dataset being printed.
           *>  (Variable Length SYSOUT Datasets.
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-lrecl-min                   pic x(4) comp-5.
           03  (ws)-prn-file-disp                   pic x.
           *>  set to '1' to delete spool file on return
           03                                       pic x(3).
           *>  The length of the buffer used to return data when driving
           *>     (ws)-prn-sysout-read-next-pptr
           *>  (How much data was returned)
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-buffer-len                  pic x(4) comp-5.
           03  (ws)-prn-buffer.
               05  (ws)-prn-buffer-byte occurs 384 times pic x comp-x.
           *>  The "MVS" Name of the document being printed.
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-document.
               05  (ws)-prn-document-len            pic x(2) comp-5.
               05  (ws)-prn-document-title          pic x(128).
           *>  The name of the batch printer driving this print job.
           03  (ws)-prn-printer.
               05  (ws)-prn-printer-name-len        pic x(2) comp-5.
               05  (ws)-prn-printer-name            pic x(128).
           *>  The "physical" filename for the file being printed.
           *>  (eg.  Where does it reside on the disk pack)
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-sysout-file-name            pic x(260).
           *>  A pointer to an OUTPUT Statement associated with this
           *>  SYSOUT Dataset.  Points to the data structure contained
           *>  in IDADOUTP.CPY
           *>    (ws)-prn-exit-print-88 only
           03  (ws)-prn-output-record-ptr           pointer.
  • Accessing OUTPUT Statement Information
  • How the Exit is Called
  • Using the Exit
  • Responding to a Printer Exit Return Code
Parent topic: Printer Exit Modules


Accessing OUTPUT Statement Information

The exit can access the OUTPUT statement associated with the dataset through a pointer, (ws)-prn-output-record-ptr, defined in the cascbprn.cpy copybook. This points to a structure defined in the IDADOUTP.cpy copybook. For an illustration of this, please refer to the process-output-statements section of sampprnx.

Parent topic: Writing a Printer Exit


How the Exit is Called

A printer SEP that has been configured to use the printer exit module will call it as follows:

  • When the batch printer SEP is started. The printer exit module can do any initial processing that might be needed.
  • Repeatedly for each spool output file that would have been directed to the printer. Information about the spool output file is passed to the printer exit module instead. The exit module can copy the file, read and manipulate each line, print it, or do anything else that would be appropriate - for instance drive an external printing system.
  • When the batch printer SEP is terminated. The printer exit module can do any final processing that might be needed.
Parent topic: Writing a Printer Exit


Using the Exit

You can associate a printer exit module with a batch printer SEP defined as a permanent feature of an Enterprise Server, or with a batch printer SEP created during a session, or both. A printer exit module can also be associated with more than one batch printer SEP.

To create a printer SEP with an exit as a permanent feature, you use the Enterprise Server Administration JES Printer Tab:

  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the relevant server.
  2. Navigate to Server > Properties > MSS > JES > Printers .
  3. Click Add and specify the details for the printer, giving the name of the printer exit in the Exit Module field.
  4. Click Add.

The executable file of the printer exit module must be on either the MSS Transaction Path, the JES Program Path or the COBPATH. Alternatively, if the exit is a Windows dll, it must be in a directory specified in the PATH environment variable.

Parent topic: Writing a Printer Exit


Responding to a Printer Exit Return Code

The product verifies the return code from a JCL printer exit. If the code it is non-zero, the dataset that was sent to the printer exit has an Out Hold status, and not a Printed status.

If the code is zero, the record is marked as Printed.

Note: To release the dataset, click Release in the ESMAC view. This presents the dataset again to the printer exit.
Parent topic: Writing a Printer Exit


Processing DEST Information

The spool.cpy copybook in the cpylib folder in the product installation includes two fields, DEST-NODE ((TAG)-dest-node) and DEST-USERID ((TAG)-dest-userid). These fields hold the values of either a SYSOUT DEST= statement on the DD card or a JES2 /* ROUTE PRINT NODE statement. The order of precedence of these and the OUTPUT statement DEST value is different so a printer exit must determine which option to use.

The (TAG)-dest-source-is field in the spool.cpy copybook holds a space if the source of the DEST information is a SYSOUT DEST= statement. It the values are set from a /*ROUTE PRINT statement, then the field holds the value of (TAG)-dest-source-is-route.

To decide which value to use, a printer exit needs to check the spool copybook DEST-NODE field for a value. Then:

If a value is found, the exit needs to check if (TAG)-dest-source-is is equal to (TAG)-dest-source-is-route:

  • If (TAG)-dest-source-is is equal to (TAG)-dest-source-is-route - the exit then should also check to see if there is a DEST value in the OUTPUT statement associated with the dataset. And, if there is such value, then it should use the OUTPUT statement value for DEST.
  • If (TAG)-dest-source-is differs from (TAG)-dest-source-is-route, the printer exit should use the values of the DEST-NODE and DEST-USERID fields in the spool.cpy copybook.

For an example of how to pick these values up, see the sample printer exit, sampprnx.cbl, which is stored in the src\enterpriseserver\exits folder in the product installation.

Parent topic: JCL development


ACCEPT and DISPLAY Handling

You can run jobs on an enterprise server that include ACCEPT FROM CONSOLE and DISPLAY UPON CONSOLE statements. When execution reaches a DISPLAY statement, the display text is displayed in the console log and the job log. When execution reaches an ACCEPT FROM CONSOLE statement, the job pauses and asks for input using pages in ESMAC.

Parent topic: JCL development
Related information
Interacting with JCL Jobs


ASCII/EBCDIC

By default, Enterprise Server uses the ASCII character set. If you wish to use EBCDIC, you can override this default for an individual enterprise server.

To select ASCII or EBCDIC for an enterprise server, you use the environment variable MF_CHARSET. You specify it via ES Admin. On the Edit page for the enterprise server, on the General tab, you make the following entry in the [ES-Environment] section of the Configuration Information field:

MF_CHARSET=E

or:

MF_CHARSET=A

You can enter these as:

MF_CHARSET=EBCDIC

or:

MF_CHARSET=ASCII

for clarity if you wish. However, only the first character (E or A) is significant.

Your programs should be compiled with the CHARSET compiler directive that matches the character set of the enterprise server. The system will handle user program data appropriately for programs invoked as a result of an EXEC PGM= JCL statement, the RUN subcommand of the DSN command, or the TSO CALL command.

You should not mix ASCII and EBCDIC programs. If you do so, you are responsible for any conversion required. The compiler directive is:

CHARSET(EBCDIC)

or:

CHARSET(ASCII)

The character set attribute of all datasets is set to the current system character set. Based on their file’s character set, LSEQ datasets and SYSIN in-stream datasets are automatically converted to suit the program.

Parent topic: JCL development


Enabling JOBLIB DD and STEPLIB DD Processing

These statements specify directories that will be searched for the programs named in EXEC statements.

To enable JOBLIB/STEPLIB processing do the following:

  1. Create a dynamic PDS that represents each of the PC or UNIX subdirectories where your .gnt and .int files will reside. We recommend that you segregate .gnt and .int files into different subdirectories.
  2. Execute your JCL using JOBLIB and/or STEPLIB statements that reference the subdirectories you created in STEP1. The search order will be STEPLIB, JOBLIB, then the path specified in the JES Program Path field on the JCL > General tab in Enterprise Server.

If the partitioned data set referenced in a particular STEPLIB or JOBLIB statement exists as a catalog entry, the DD is allocated. Where there are multiple partitioned data sets referenced in a STEPLIB or JOBLIB concatenation, only those data sets that exist are mapped as part of the JOBLIB or STEPLIB concatenation.

Any job that has a STEPLIB and/or JOBLIB statement continues to run unmodified.

Parent topic: JCL development


Output Limitation Support

In line with mainframe practice, you can limit the amount of output sent to SYSOUT datasets. You can apply limits to the whole job by giving a value in the JCL job card. You can set global limits for the number of lines output using environment variables.

Limits to LINES, PAGES, CARDS, and BYTES

The LINES, PAGES, CARDS, and BYTES keyword parameters on the JCL job card are supported. PAGES, CARDS and BYTES are translated to a number of lines using the following values:

  • 60 LINES for every PAGE
  • 25 LINES for every CARD
  • 132 BYTES for every LINE

For example, an entry of PAGES=(100,CANCEL) on the job card equates to an output limit of 6000 lines before the job is cancelled.

Specifying limits with the OUTLIM parameter

Any SYSOUT DD statement can contain an OUTLIM parameter that specifies the maximum number of lines output to that dataset. When the limit has been reached the system will:
  • call the user exit, if it exists
  • process the global setting, if it exists
  • cancel the job

The OUTLIM value is ignored for SYSABEND, SYSMDUMP and SYSUDUMP datasets.

The user may implement an OUTLIM user exit to call if the output limit is reached. This can tell the system whether to continue or abend the job. The user exit program must be called MFJUSOXT, a sample of which is included in the source\enterpriseserver\exitssrc/enterpriseserver/exit folder of your product.

Specifying global limits with environment variables

Global limits are set by environment variables, either in the environment in which the enterprise server region was started or by entering the values in the enterprise server region's configuration settings. These values apply to all jobs that run in that region.

The format of the variable value is similar to that which would be entered in the JCL job card accounting information: it should contain the limit value and, optionally, the action to perform when that limit is reached. The actions you can specify are CANCEL, DUMP or WARNING. CANCEL and DUMP cause the job to abend at that point, WARNING issues a message but processing continues. If you give no action for LINES, PAGES, CARDS, and BYTES the system issues a warning and continues processing. If you give no action for OUTLIM the job is cancelled.

Environment Variable Value Range Example
ES_JES_LINES 0-99999999
ES_JES_LINES=(100,CANCEL)
Limit the number of lines output to 100000. When this limit is reached cancel the job. This results in an S722 Output limit exceeded system abend code being produced.
ES_JES_PAGES 0-99999999
ES_JES_PAGES=10
Each page is assumed to hold 60 lines, therefore when 600 lines (60×10) have been processed issue a warning and carry on.
ES_JES_CARDS 0-99999999
ES_JES_CARDS=(30,WARNING)
Each card is assumed to hold 25 lines, therefore at 750 lines (25×30) issue a warning message and carry on.
ES_JES_BYTES 0-999999
ES_JES_BYTES=(100,DUMP)
Value for bytes is in thousands, each line is assumed to hold 132 bytes, therefore at 100000/132 lines the job will be cancelled.
ES_JES_OUTLIM 1-16777215
ES_JES_OUTLIM=5000
The job will be cancelled if any of the SYSOUT datasets reaches 5000 lines.
Parent topic: JCL development
Related reference
System Abend Codes


System Abend Codes

The following system abend codes are supported when executing JCL.
Code | Description
S122 | The operator canceled the job and requested a dump
S222 | The operator canceled the job w/o a dump
S322 | Job timed out
S413 | Catalog file access error
S422 | The abend is a general use abend code
S522 | All of the tasks in a job step were in SVC wait state
S622 | Internal error
S722 | Output limit exceeded
S822 | Region not available
S922 | Initiator error
SA22 | Force command terminated the job
SB22 | EXCP failure
SD22 | Command processing error

Comments:

All system abends, except S722, cause the system to terminate the job step and bypass successive steps. For example, when executing an IF/THEN/ELSE/ENDIF statement in the JCL, any of the supported system abend codes (except S722) produced on the IF statement will bypass the THEN or ELSE clauses, regardless of any tests on the IF statement. When S722 is produced, the successive clauses are processed as normal.

Parent topic: JCL development


Files and Data Sets

This section provides introductory information on how MSS uses the following types of file: Project files, System catalog files, User catalog files, Catalog files, Data set files, and Spool files
  • Catalog Files
    MSS uses a catalog file to hold information about the data sets needed for the JCL jobs that run in an enterprise server. You specify the name and location of the catalog file when you configure an enterprise server for JCL. If the catalog file does not exist, MSS creates it when the enterprise server starts.
  • Data Set Files
  • Spool Files
Parent topic: JCL Support


Catalog Files

MSS uses a catalog file to hold information about the data sets needed for the JCL jobs that run in an enterprise server. You specify the name and location of the catalog file when you configure an enterprise server for JCL. If the catalog file does not exist, MSS creates it when the enterprise server starts.

The location and name of the catalog file is shown in the System Catalog field on the Server > Properties > MSS > JES page in ES Admin. You can change this field to use a different catalog file.

If the catalog file becomes corrupt, you can rebuild it using the fixcat utility.

To maintain a connection with the mainframe environment, you can continue to use MVS data set names in JCL statements and TSO commands. However, these names have no meaning in a non-mainframe environment, so MSS also requires the name of the local file that represents the data set. Both names are included in the catalog entry.

Tip: Although you can share a catalog between servers if access to it is controlled by Fileshare, we recommend you do not do so.
Parent topic: Files and Data Sets


Data Set Files

This section contains basic information about using MSS with data sets. For further information on this subject, see the chapter Advanced Data Set Information.

All data sets that are referenced in JCL statements or TSO commands must have an entry in the catalog so that MSS can locate the local file that represents the data set. These data sets include:

  • Cataloged procedures referenced by EXEC statements
  • JCL procedures referenced by INCLUDE statements or TSO SUBMIT commands
  • Input and output data sets referenced in DD statements supported by MSS. See the section JCL Features in the chapter JCL Support for more information.
  • Input and output data sets referenced in TSO ALLOCATE, FREE and DELETE commands
  • REXX execs referenced by TSO EXEC commands
  • Partitioned data sets (libraries) that contain any of the above data sets

On the mainframe, data sets can be either cataloged or uncataloged. You can locate cataloged data sets using their catalog entry, and locate uncataloged data sets using their VOLUME number. In the Windows and UNIX environments, you cannot use the VOLUME to map physical locations as you can on the mainframe. Therefore, we catalog all data sets on Windows and UNIX. The catalog entry for every data set contains a flag that indicates whether a data set is cataloged or uncataloged; however, all data sets, both cataloged and uncataloged, are actually located using the catalog.

When viewing the catalog you can choose to see just the cataloged data sets or to see both the cataloged and uncataloged data sets.

Data sets that are not referenced in JCL statements or TSO commands do not need entries in the catalog. For example, you can write a program that accesses a file that has no entry on the system catalog by specifying its physical filename in the SELECT clause in the Environment division.

There are three methods of including an entry in the catalog:

  • New on the Catalog page in ESMAC

    Click New on the Catalog page in ESMAC. You need to specify both the MVS name and the local physical filename.

  • Through the allocation of a new data set (DISP=NEW or DISP=MOD for a new file) by means of a DD statement in a jobstream or an ALLOCATE command in REXX exec. MSS assigns the physical filename.
  • Dynamically, by MSS, if a data set is used which does not already have an entry. MSS assigns the physical filename.

When MSS assigns the physical filename, it uses the default data file path set on the Properties > JES page of ES Admin, followed by the mainframe name with the extension .dat, For example, if the default path for data files is c:\catalog\data sets /catalog/data sets then a file with an MVS name of MFE2004.S1217.S160553.J01013.D00006.SYSOUT, will be stored locally as C:\CATALOG\data setS\MFE2004.S1217.S160553.J01013.D00006.SYSOUT.DAT /CATALOG/data setS/MFE2004.S1217.S160553.J01013.D00006.SYSOUT.DAT

Note: Default behavior is to allow new data sets to be cataloged without specifying a SPACE parameter. If you prefer that JCL missing the SPACE parameter fails in the same way it does on the mainframe, set the MF_NEWSPACE=Y environment variable.
  • Using Fileshare to Access Data Files
  • Partitioned Data Sets (PDSs)
Parent topic: Files and Data Sets
Related information
Advanced Data Set Information
JCL Features
Partitioned Data Sets (PDSs)


Using Fileshare to Access Data Files

You can share files on networks and multi-user systems using Fileshare. As you can connect up to sixteen Fileshare servers to your COBOL system, you can split your data across several machines.

There are three ways of configuring the use of Fileshare:

  • Specify explicit Fileshare server locations in the catalog
  • Specify explicit Fileshare server locations in SELECT clauses, for files that are not cataloged
  • Provide a Fileshare client configuration file that defines which files are located on Fileshare servers

You can use these methods in combination.

  • Specifying Fileshare Locations in the Catalog
  • Specifying Fileshare Locations in SELECT Clauses
  • Specifying Fileshare Locations in the Fileshare Client Configuration File
Parent topic: Data Set Files


Specifying Fileshare Locations in the Catalog

To specify that a file is located on a Fileshare server, give the full pathname of the file prefixed by $$servername in Physical File when you create a new catalog entry using New on the ESMAC Catalog page. Use the conventions appropriate to the server. For example, the file data01.dat on a UNIX server would require a pathname similar to:

$$unixserver/usr/accounts/data01.dat

while the same file located on a mainframe would require a pathname similar to:

$$MAINFRAME\FILES.ACCOUNTS.DATA01

Parent topic: Using Fileshare to Access Data Files


Specifying Fileshare Locations in SELECT Clauses

If you write programs that access files that are not cataloged, because they are not mainframe-style files, and you want to store these files on Fileshare servers, you can include the fileshare server name in the SELECT clause in the I-O-Section of the Environment Division, for example:

select datafile assign to "$$unixserver/usr/accounts/data01.dat".
Parent topic: Using Fileshare to Access Data Files


Specifying Fileshare Locations in the Fileshare Client Configuration File

The Fileshare client configuration file is called fhredir.cfg. If there is an fhredir.cfg file present, MSS consults it whenever it needs a file that has no explicit Fileshare server location specified in its catalog entry or SELECT clause. It does not consult it if an explicit Fileshare server location is specified.

If you want to specify a Fileshare location in the fhredir.cfg file for a cataloged file you must make sure you specify an explicit filename in Physical File that matches an entry in the fhredir.cfg file, rather than letting MSS allocate a name. Fileshare is case sensitive so filenames in the catalog and the fhredir.cfg file must use the same case.

You can either let the location of the fhredir.cfg file default to the current folder, or specify the location in the environment variable FHREDIR.

You must set the FHREDIR environment variable before you start the enterprise server.

For more information about setting FHREDIR and the use of Fileshare within Enterprise Server see the section Fileshare in the chapter Configuration in your Configuration and Administration Guide

You can use entries in the fhredir.cfg file in a variety of ways. For example, you can

  • Simply name one or more Fileshare servers, and MSS will search those servers in the order they appear in the configuration file.
  • Specify full pathnames for every file located on a Fileshare server
  • Use wild cards in pathnames, for example, to indicate that all the files in a certain directory are held on a Fileshare server
  • Specify that certain files are actually located locally

For full details of all the options and examples see the chapters Standard Operation and Configuration in your Fileshare Guide.

Parent topic: Using Fileshare to Access Data Files
Related information
Fileshare
Standard Operation


Partitioned Data Sets (PDSs)

In an MVS mainframe environment, a file can be defined as an individual data set or as part of a partitioned data set (PDS). MSS supports both of these methods.

In a partitioned data set (organization = PO), the individual data sets are known as members (organization = PDSM). You define a partitioned data set and its members to MSS like any other data set.

  • Procedure Libraries
  • Dynamic PDSs
Parent topic: Data Set Files


Procedure Libraries

Procedure libraries are partitioned data sets that contain procedures that can be specified in JCL jobstreams. MSS searches for the JCL procedures executed via an EXEC statement in the following order:

  1. In-stream procedures.
  2. Libraries specified on a JCLLIB statement in the JCL.

    You must allocate these libraries to the catalog.

  3. The libraries that you specified when you enabled JCL Support, on the Server > Properties > JES page of ES Admin.
Parent topic: Partitioned Data Sets (PDSs)


Dynamic PDSs

In MSS, each member of a PDS is implemented as a separate physical PC file. By default, you have to create a separate catalog entry for each such member, giving the filename of the physical file. This is not practicable if a PDS has a great many members. You can avoid it by using a dynamic PDS.

To define a dynamic PDS you create just one catalog entry. On its Catalog Entry page in ESMAC, you set the DS Org field to PO and then put a check mark by Dynamic PDS. This enables the Physical Filename and PDS Exts fields. The value you enter in the Physical File field is assumed to be the name of an existing directory. The members of the PDS are implemented as individual physical files within this directory.

The Physical Filename field must end with a backslash ("\") on Windows or a forward slash ("/") on UNIX. As in any catalog entry, it must specify the full path. You can use the string "<CATALOGFOLDER>" to represent the directory where the catalog is stored.
Restriction: No other formats for the Physical Filename (for example paths containing an environment variable) are supported.

In the PDS Exts field you specify one or more filename extensions, separated by spaces. When a PDS member is created, the physical file is given a name consisting of the member's name as the basename, and the first entry in this field as the filename extension.

On UNIX, all member names used in a dynamic PDS must be upper case. Any file that uses a lower case member name will not be found.

Example

If you define a Catalog Entry with

Field | Value
DS Name | SOURCE.PDS
Physical File | <CATALOGFOLDER>\PAYROLL\
DS Org | PO
Dynamic PDS | checked
PDS Exts | CBL CPY

where the catalog folder is C:\CATALOG, and you then run the following JCL:

/FILE1	   DD DSN=SOURCE.PDS(PAYUPD),DISP=OLD
/FILE2	   DD DSN=SOURCE.PDS(PAYREP),DISP=OLD

(note DISP= OLD because SOURCE.PDS already exists), then as long as ES_OLD_DYN_PDS=Y is set then the JCL creates physical files PAYUPD.CBL and PAYREP.CBL in directory C:\CATALOG\PAYROLL. It creates catalog entries for these individual PDS members (DSOrg = PDSM) automatically. If ES_OLD_DYN_PDS=N (the default) is set, physical files for the PDS members are only created and cataloged when you run JCL similar to that outlined in Creating a Dynamic PDS with JCL.

When a PDS member is being sought, the directory is searched for a file with the member's name plus each of the specified extensions in turn, and the first match is used. For example, if the directory contains PAYUPD.CBL, PAYUPD.CPY and PAYREP.CPY, then an attempt to access SOURCE.PDS(PAYUDP) will find PAYUPD.CBL. Because the search terminates once a match has been found, PAYUPD.CPY will never be found. An attempt to access SOURCE.PDS(PAYREP) will find PAYREP.CPY.

  • Creating a Dynamic PDS with JCL
Parent topic: Partitioned Data Sets (PDSs)


Creating a Dynamic PDS with JCL

You can create dynamic PDSs with JCL, by using the extension syntax illustrated in the following examples.

You must set the following variables in your JCL depending on whether the file is for data or source.
Variable | Value for a data PDS | Value for a source PDS
LRECL | Any number greater than zero | 0
RECFM | Either FB, V, VB, or F | LSEQ

Using a PDS for data files

//DD1      DD DSN='TEST.DYN1',DISP=(NEW,CATLG),
//            DCB=(RECFM=FB,LRECL=123,DSORG=PO)
//*MFE: %PCDSN=C:\DPDS\*.DAT

This will create TEST.DYN1 as a dynamic PDS whose members are files in the directory C:\DPDS with the extension .DAT.

Using a PDS for source files

//DD1      DD DSN='LORINCE.CTLLIB.PDS',DISP=(NEW,CATLG),
//            UNIT=SYSDA,SPACE=(CYL,(3,1,1)),
//            DCB=(RECFM=LSEQ,LRECL=0,DSORG=PO)
//*MFE: %PCDSN=C:\DCCPDS\*.TXT

This will create LORINCE.CTLLIB.PDS as a dynamic PDS that can be used for control cards or source for SORT, IDCAMS, REXX, JCL, and PROCs.

Deleting a Dynamic PDS

When you delete a dynamic PDS, this does not automatically delete the underlying PC files. To delete the underlying PC files, set the MF_DEL_DYNPDS environment variable to Y.

Parent topic: Dynamic PDSs


Spool Files

MSS emulates the spooler functions of the mainframe's job entry system. You can select emulation of VSE, JES2 or JES3.

MSS creates a spool file for each of the following:

  • Each job that is run. The spool file lists the jobstream and shows the results of each job step.
  • Each output data set that is directed to SYSOUT. The spool file shows the contents of the data set.

In MSS, a JCL jobstream can have only one job but the job can contain multiple job steps. You use an EXEC statement to specify the program to be executed by a job step. You can do this either directly:

EXEC PGM=program-name

or indirectly, using a cataloged procedure:

EXEC PROC=procedure-name ---------> EXEC PGM=program-name.

Although the Catalog page does not include spool files, they are assigned data set names.

If the data set name is not specified, the MVS name has the form:

Yyyyy.Smmdd.Shhmmss.Jjjjjjjj.Dnnnnn.ddname

If the data set is temporary, the MVS name has the form:

Yyyyy.Smmdd.Shhmmss.Jjjjjjjj.ANDAND.tempname

where:

  • yyyy is the year
  • mmdd is the month and day
  • hhmmss is the time
  • jjjjjjj is the job number
  • nnnnn is a number assigned by MSS. It indicates the order in which the data set was created by the job (00000 for the JOBLOG(JCL) file that shows the results of scanning or running a jobstream).
  • ddname is the DD name (for SYSOUT files only)
  • tempname is the temporary name, specified as &&tempname in the DD statement.
Parent topic: Files and Data Sets


Advanced Data Set Information

It covers the following subjects:
  • Data set organizations
  • Record formats
  • Logical record length
  • Mapping to local file formats
  • Dynamic PDS member lists
  • Support for mfextmap.dat and PROXMVS files
  • Support for Generation Data Groups
  • Data Set Organizations
  • Record Formats
  • Logical Record Length
  • Mapping to Physical File Formats
  • Support for Generation Data Groups
Parent topic: JCL Support
Related information
Files and Data Sets


Data Set Organizations

The data set organizations supported by MSS are shown in the following table.

Abbreviation | Organization | Comment
GDG | Generation data group |
IS | Indexed sequential |
ISU | Indexed sequential, unmoveable |
PDSM | Partitioned data set member | Micro Focus organization
PO | Partitioned |
POU | Partitioned, unmoveable |
PS | Physical sequential |
PSU | Physical sequential, unmoveable |
VSAM | Virtual storage access method |
Note: Although the direct access (DA) organization is not supported explicitly, you can emulate it by using the VSAM organization and relative record (RR) record format.
Parent topic: Advanced Data Set Information


Record Formats

The following table shows the record formats for all the data set organizations except VSAM.

Abbreviation | Format | Control Characters | Record Delimiters | Comment
F | Fixed | None | None |
FA | Fixed | ANSI | None |
FB | Fixed blocked | None | None | Same as F format
FBA | Fixed blocked | ANSI | None | Same as FA format
FBM | Fixed blocked | Machine | None | Same as FM format
FBS | Fixed blocked spanned | None | None | Same as F format
FM | Fixed | Machine | None |
FS | Fixed spanned | None | None | Same as F format
LSEQ | Line sequential | None | Carriage return/line feed |
U | Undefined |  |  | Results unpredictable on Windows or UNIX
V | Variable | None | Micro Focus type |
VA | Variable | ANSI | Micro Focus type |
VB | Variable blocked | None | Micro Focus type | Same as V format
VBA | Variable blocked | ANSI | Micro Focus type | Same as VA format
VBM | Variable blocked | Machine | Micro Focus type | Same as VM format
VBS | Variable blocked spanned | None | Micro Focus type | Same as V format
VM | Variable | Machine | Micro Focus type |
VS | Variable spanned | None | Micro Focus type | Same as V format
Note: Blocked and spanned record formats are accepted by MSS but have no meaning in a PC or UNIX environment.

The following table shows the record formats for VSAM files.

Abbreviation | Format | Control Characters | Comment
ES | Entry sequence | None |
KS | Key sequence | None |
LS | Linear sequence | None | Not supported
RR | Relative record | None |

Notes:

  • A cataloged VSAM file has two extra properties, LRECL Avg (average record length) and LRECL Max (maximum record length). If these two properties have the same value, MSS assumes that the file has fixed length records and does not use record delimiters to separate the records on Windows or UNIX.. If they have different values, MSS assumes that the record has variable length records and uses the Micro Focus type delimiters to separate records on Windows or UNIX.
  • If you have a program compiled to use EBCDIC, but that program reads a file with a RECFM of LSEQ and a character set of ASCII, the file's data is automatically converted to EBCDIC as part of the read. This automatic conversion is useful when reading files that do not contain hexadecimal data, such as control cards.
  • You allocate VSAM data sets to the MSS catalog using New on the ESMAC catalog page, or by submitting a batch job to define the file using IDCAMS.
  • If your application uses record-level locking on shared VSAM files, you might find that files larger than 1 GB (gigabyte) cannot be accessed. This is because the default record locking mechanism in MSS uses the top two bits of the file address for locking and compression bits, thus reducing the address space for the maximum offset from 4 GB to 1 GB for a shared idxformat 3 or 4 file. If you encounter this problem, set the LOCKTYPE Compiler directive to 2 when you compile the program affected. With this setting, the file handling mechanism creates a separate file for storing record locks, with the same basename as the file and a .lck extension.
Parent topic: Advanced Data Set Information


Logical Record Length

MSS works with logical record lengths as defined in the following table:

Record Format | Logical Record Length
Fixed | Actual record length
Variable | Actual record length + 4
LSEQ | Maximum record length

Note: If you have a program compiled to use EBCDIC, but that program reads a file with a RECFM of LSEQ, LRECL of 0 and a character set of ASCII, MSS automatically converts the file's data to EBCDIC as part of the read. This automatic conversion is useful when reading files such as control cards, that do not contain hexadecimal data.

Parent topic: Advanced Data Set Information


Mapping to Physical File Formats

MSS writes data sets to physical files on the PC and UNIX using the following organization and record format mapping:

Mainframe |  | Physical File
Data Set Organization | Record Format | File Organization | Record Format | Comment
DA, DAU, PS, PSU | Any fixed (Fnn) or variable (Vnn) format | Sequential | Micro Focus |
DA, DAU, PS, PSU | LSEQ | Line sequential | Micro Focus | Always uses ANSI character set. Can only be edited with a text editor
GDG |  |  |  | Catalog entry only
IS, ISU | Any fixed (Fnn) or variable (Vnn) format | Indexed sequential | Micro Focus |
PDSM | Any fixed (Fnn) or variable (Vnn) format | Sequential | Micro Focus |
PDSM | LSEQ | Line sequential | Micro Focus |
PO, POU |  |  |  | Catalog entry only
VSAM | ES | Sequential | ESDS |
VSAM | ES | Indexed sequential | ESDS | Alternate index defined
VSAM | KS | Indexed sequential | Micro Focus |
VSAM | LS | Not supported |  |
VSAM | RR | Relative | Micro Focus |
Parent topic: Advanced Data Set Information


Support for Generation Data Groups

A generation data group (GDG) consists of two parts: a GDG model and a series of physical sequential (PS) data sets, called biases (also known as generation data sets) that are associated with the GDG.

  • Creating Generation Data Groups
  • Generation Data Group Restrictions
Parent topic: Advanced Data Set Information


Creating Generation Data Groups

There are two main ways to set up a GDG:

  • By clicking Add on the ESMAC Catalog page. To define the model, specify the data set organization DSORG as "GDG". To define a bias, specify the DSORG as "PS" and provide the fully-qualified data set name. For example, if the model has the data set name MAG.TEST, the first bias might be named MAG.TEST.G0001V00, the second MAG.TEST.G0002V00, and so on (gaps in the numbering sequence are allowed).
  • By running an MFJAMS job that defines the GDG model and biases.

The following example illustrates a job that can be used to create a generation data group. STEP00 creates the GDG model and STEP01 creates five new GDG biases.

//MFIDMFGD JOB 'MFIDMFGD',CLASS=A,MSGCLASS=A,NOTIFY=MFIDF
//STEP00 EXEC PGM=IDCAMS
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//AMSDUMP DD SYSOUT=*
//SYSIN DD *
DELETE MFIDMF.TEST.GDG
DEFINE GENERATIONDATAGROUP(NAME(MFIDMF.TEST.GDG)
       EMPTY NOSCRATCH LIMIT(96))/*
//STEP01 EXEC PGM=IEFBR14
//SYSUXX DD DSN=MFIDMF.TEST.GDG(+1),DISP=(NEW,CATLG),SPACE=(TRK,(5,2))
//SYSUXY DD DSN=MFIDMF.TEST.GDG(+2),DISP=(NEW,CATLG),SPACE=(TRK,(5,2))
//SYSUXZ DD DSN=MFIDMF.TEST.GDG(+3),DISP=(NEW,CATLG),SPACE=(TRK,(5,2))
//SYSUXA DD DSN=MFIDMF.TEST.GDG(+4),DISP=(NEW,CATLG),SPACE=(TRK,(5,2))
//SYSUXB DD DSN=MFIDMF.TEST.GDG(+5),DISP=(NEW,CATLG),SPACE=(TRK,(5,2))

Five biases named MFIDMF.TEST.GDG.G0001V00, MFIDMF.TEST.GDG.G0002V00, MFIDMF.TEST.GDG.G0003V00, MFIDMF.TEST.GDG.G0004V00 and MFIDMF.TEST.GDG.G0005V00 are created by STEP01.

A bias can be processed by its relative number, its actual reference or as a part of the entire generation data group. For example, each of the following statements could be executed after running the previous job.

//SYSUT1 DD DSN=MFIDMF.TEST.GDG,DISP=SHR

This would cause the entire generation data group MFIDMF.TEST.GDG, consisting of a set of concatenated data sets MFIDMF.TEST.GDG.G0001V00 through MFIDMF.TEST.GDG.G0005V00, to be referenced.

//SYSUT1 DD DSN=MFIDMF.TEST.GDG(0),DISP=SHR

The relative number 0 would cause the data set named MFIDMF.TEST.GDG.G0005V00 to be referenced.

//SYSUT1 DD DSN=MFIDMF.TEST.GDG(-1),DISP=SHR

The relative number -1 would cause the data set named MFIDMF.TEST.GDG.G0004V00 to be referenced.

//SYSUT1 DD DSN=MFIDMF.TEST.GDG(+1),DISP=SHR

The relative number +1 would cause a new data set named MFIDMF.TEST.GDG.G0006V00 to be referenced.

//SYSUT1 DD DSN=MFIDMF.TEST.GDG.G0003V00,DISP=SHR

The actual reference G0003V00 would cause the data set named MFIDMF.TEST.GDG.G0003V00 to be referenced.

The increment of numbers occurs per job, so if you had two consecutive steps that referenced +1, then each step would be using the same data set.

Parent topic: Support for Generation Data Groups


Generation Data Group Restrictions

This section describes restrictions when using GDGs in MSS:

  • The maximum number of host GDG biases that you can reference is 255.
  • MSS does not support versioning of the GDG biases, so the only biases that versioning works for are those with a data set name ending with V00. For example, if the GDG model name is MFIDMF.TEST.GDG then the GDG biases must have the form MFIDMF.TEST.GDG.G0001V00 ... MFIDMF.TEST.G9999V00, with gaps in the numbering sequence. If you attempt to use a bias that ends, for example, in V01, it will not be found when GDG names are resolved during program execution.
  • A GDG model and all of its generation data sets (GDSs) must reside on the same platform. It is not possible to have a mixture of GDSs where some reside on the mainframe and others locally.
  • If you are using relative bias numbers to reference GDSs in your JCL, for example MFIDMF.TEST.GDG(-4) or MFIDMF.TEST.GDG(+1), the following restrictions apply:
    • If the GDSs are located on a Mainframe Access server, you cannot reference any numbers greater than zero. The only permitted numbers are 0 through -n, where n is the maximum number of GDSs supported by the GDG model.
    • If the GDSs are located on a PC or network, all processing is supported with only the limitations that are already documented in this section.
Parent topic: Support for Generation Data Groups


Utility Programs

There are two types of utility program:

  • Mainframe emulation utilities
  • Micro Focus utilities

This chapter also describes how, if required, you can write your own utility program; see the section Writing Your Own Utility Programs for details.

  • Emulations of Mainframe Utilities
  • Micro Focus Utilities
    This section describes the Micro Focus utilities MFJMATCH and MVSCATPB.
  • Writing Your Own Utility Programs
Parent topic: JCL Support
Related information
Mainframe emulation utilities
Micro Focus utilities
Writing Your Own Utility Programs


Emulations of Mainframe Utilities

This section describes the mainframe emulation utilities. You can invoke these utilities in a JCL jobstream or REXX exec by using the same program names, data sets and commands as on the mainframe. The mainframe utilities emulated by MSS are:

  • DFSORT and SORT, to perform sort/merge operations
  • DSNTEP2, to execute any SQL statement that can be executed dynamically
  • IDCAMS, to manage VSAM data sets
  • IEBCOMPR, to compare two sequential or partitioned data sets
  • IEBCOPY, to copy or merge partitioned data sets
  • IEBGENER, to copy sequential data sets
  • ICEGENER, like IEBGENER but with VSAM capabilities
  • IEBUPDTE, to create or modify sequential or partitioned data sets
  • IEFBR14, to provide a dummy program facility by simply returning to the caller
  • IKJEFT01, to submit TSO commands in batch mode (also IKJEFT1A and IKJEFT1B)
  • IRXJCL, to run a REXX exec in MVS batch mode
  • IEBDG, to create test data
  • IEBPTPCH, to print or punch sequential or partitioned datasets, or PDS members
These names are defined as aliases for the equivalent MSS utility.
Note: Input files are no longer optional, and it is possible to catalog a file without creating a physical file. To help prevent JES failures because of an apparent missing input file, you can use the MFJ_INPUTDS_ERROR=N environment variable. When it is specified, an input file for a JCL step is considered as optional and most utilities and user programs treat missing input files as though they were present but empty. Some utilities, such as SORT, still check for a physical file and generate and error if it is not found.

This section describes the special considerations that apply when you use these utilities in a MSS environment. It does not include information on behavior that is the same in mainframe and MSS environments. For full information on the mainframe utilities referred to in this section, see the relevant IBM documentation.

Note:

If you wish to debug programs invoked by IKJEFT01, you must specify its equivalent MSS utility, IDAEFT01, as the program to debug.

  • Executing TSO Commands in Batch Mode (IDAEFT01)
  • Mainframe Batch Database Tools (MBDT)
    Describes batch utilities that facilitate mainframe database migration.
  • Loading XDB Database Table Rows (XUTLB)
  • Executing Dynamic SQL statements (XTEP2)
  • Running REXX Execs in MVS Batch Mode (MFIRXJCL)
    MFIRXJCL emulates the IRXJCL mainframe utility program.
  • VSAM Access Method Services (MFJAMS)
    MFJAMS emulates some of the main functions of the IDCAMS mainframe utility.
  • Dummy Program (MFJBR14)
    MFJBR14 emulates the IEFBR14 mainframe utility. It provides a dummy program facility by simply returning to the caller.
  • Copying and Merging Partitioned Data Sets (MFJCOPY)
    MFJCOPY emulates the operation of the IEBCOPY mainframe utility for copying and merging partitioned data sets.
  • Generating Test Data (MFJDG)
    MFJDG emulates the IEBDG mainframe utility for creating test data.
  • Printing or Punching Data Sets (MFJPTPCH)
    MFJPTPCH emulates the IEBPTPCH mainframe utility for printing or punching datasets.
  • Copying Sequential Data Sets (MFJGENER and ICEGENER)
  • Comparing Data Sets (MFJMATCH - IEBCOMPR)
  • Sort/Merge Operations (MFJSORT)
  • Creating or Modifying Data Sets (MFJUPDTE)
    MFJUPDTE emulates the IEBUPDTE mainframe utility for creating or modifying sequential or partitioned data sets.
  • TSO Support in Enterprise Server
    Describes use of TSO commands in Enterprise Server using the ISAEDT01 utility.
Parent topic: Utility Programs


Executing TSO Commands in Batch Mode (IDAEFT01)

IDAEFT01 emulates the IKJEFT01 (and IKJEFT1A and IKJEFT1B) mainframe utility program. It starts a TSO session in batch, and the TSO session executes the TSO commands contained in the data set defined by the SYSTSINDD statement.

IDAEFT01 is typically used to run DB2/TSO applications in batch mode. Input for such applications is, at a minimum:

DSN SYSTEM(system)
RUN PROGRAM(name) PARM(parm-string)
 ....
END
SYSTEM(system)
Specifies the ID of the XA Resource Manager instance to use. See To define an XAR for an enterprise server region.
PROGRAM(name)
Specifies the name of the program to be executed. IDAEFT01 can execute any application program that is compiled within your COBOL development system, provided you have set the necessary directives.
PARM(parm-string)
Specifies the parameter string that is to be passed to the program through the standard linkage area.
  • JCL Statements
    This section describes the JCL statements used with the IDAEFT01 utility.
Parent topic: Emulations of Mainframe Utilities
Related tasks
HHADTHSERV08.html
Related information
To create a resource table
To add an XA resource to an enterprise server


JCL Statements

  • EXEC Statement
  • DD Statements
Parent topic: Executing TSO Commands in Batch Mode (IDAEFT01)


EXEC Statement

In the EXEC statement you need to specify the program name IDAEFT01 or its alias IKJEFT01. For example:

//STEPEXEC PGM=IKJEFT01,PARM='initial-command',.......
Parent topic: JCL Statements


DD Statements

The following DD statements are required:

SYSTSIN
This can be an in-stream data set, or sequential data set or PDS member with an 80 character record length.
SYSTSPRT
For the data set that contains output from IKFJEFT01.
SYSEXEC or SYSPROC
For the PDS containing any Rexx execs to be run under TSO.

You must also include any DD statements for sequential and VSAM data sets that are accessed by the application program.

Parent topic: JCL Statements


Mainframe Batch Database Tools (MBDT)

The MBDT toolset provides basic batch utility support for the following z/OS DB2 utilities:

DSNTEP2
Enables you to execute SQL DDL and DML in a target DBMS using an SQLTP2 alias.

DSNTEP2 accepts native DBMS DDL and DML syntax for DB2 LUW, Oracle, and SQL Server by default. DSNTEP2 also accepts z/OS DB2 DDL and DML syntax for SQL Server. See MBDT Configuration Utility for details.

DSNUTILB
Enables you to load or unload your data to or from the target DBMS using an SQLUTB alias.

The versions of DSNTEP2 and DSNUTILB provided by Micro Focus initialize the OpenESQL compiler directives required to set up the appropriate environment parameters, and then call OpenESQL runtime functions. They always use ODBC to communicate with target DBMSs. To enable ODBC support, you must define an XAR to Enterprise Server that uses the ODBC generic one-phase commit switch module. See Generic One-phase Commit for ODBC RM Switch Module for details.

Note: We provide MBDT for DB2 LUW, SQL Server, Oracle, and PostgreSQL for Windows and limited UNIX 32-bit and 64-bit environments. See Additional Software Requirements on Linux and UNIX for details. Additional restrictions apply as specified in this topic. Also, the MBDT Configuration Utility is supported on UNIX via command line only.
  • Batch Migration Process
    Describes the process of migrating databases using MBDT.
  • DSNTEP2 and DSNUTILB Aliases
    Describes the aliases MBDT uses to replace DSNTEP2 and DSNUTILB.
  • MBDT Configuration Utility
    Describes the options you can set for Mainframe Batch Database Tools (MDBTs).
  • SQLTP2 Utility - Executing Dynamic SQL Statements
    Describes the use of SQLTP2 to execute dynamic SQL statements.
  • SQLUTB Utility - Loading and Unloading SQL Tables
    Describes the use of SQLUTB to load and unload SQL tables.
  • Support for Partitioned Tables in DB2 LUW
    Describes MBDT DSNUTILB support for partitioned tables in DB2 LUW.
  • How to
  • Reference
Parent topic: Emulations of Mainframe Utilities
Related concepts
Mainframe Batch Database Tools
MBDT Configuration Utility
Generic One-phase Commit for ODBC RM Switch Module
Offline Extract Schema Solution


Batch Migration Process

The database migration process using MBDT consists of the following steps:

  1. Create a destination database and schemas using tools provided by your DBMS vendor.
  2. Create an ODBC connection to the new target database:
    • On Windows platforms, catalog an ODBC Data Source Name to the new target database using the 32- or 64-bit ODBC Data Source Administrator, depending on the COBOL working mode of your enterprise server instance.
    • On UNIX platforms, catalog an ODBC Data Source Name to the new target database using instructions from your ODBC Driver Manager documentation.
  3. Unload data and the LOAD control statement from z/OS DB2 with DSNUTILB UNLOAD.
  4. Using Enterprise Server, create an enterprise server instance with Mainframe Subsystem Support (MSS) that also supports JCL applications.
  5. Configure your enterprise server instance by creating an ODBC XAR and MBDT aliases.
  6. Copy the LOAD control statement to the MBDT Windows or UNIX machine.
  7. Copy and catalog the unloaded DB2 data on the MBDT Windows or UNIX machine.
  8. Using SQLTP2, execute DDL to create the tables in the new target database.
  9. Load the DB2 data into the new target database with SQLUTB, using the LOAD card generated on the mainframe.
  10. Using SQLTP2, execute DDL to create the DB2 constraints and indexes in the new target database.
Tip: To see a detailed example, review the Tutorial: DB2 Database Batch MIgration topic.
Parent topic: Mainframe Batch Database Tools (MBDT)
Related concepts
Tutorial: DB2 Database Batch Migration
Related reference
mbdtconfig command


DSNTEP2 and DSNUTILB Aliases

To use the MBDT versions of DSNTEP2 and DSNUTILB, you must configure your enterprise server instance to include an alias for each. You can do this in one of two ways:
Keep DSNTEP2 and DSNUTILB Program Names
If you want to keep the program names DSNTEP2 and DSNUTILB in your JCL, and have them execute the MBDT version of these utilities, add the following alias definitions:
Program | Alias
DSNTEP2 | SQLTP2
DSNUTILB | SQLUTB
Specify Alternative Program Names
If you want to specify a different program name in the JCL for each MBDT, you can do this instead. For example:
Program | Alias
HCOTEP2 | SQLTP2
HCOUTILB | SQLUTB
Parent topic: Mainframe Batch Database Tools (MBDT)


MBDT Configuration Utility

The MDBT Configuration Utility enables you to configure options for the following tools:

SQLTP2 - Database Selection
Enables you to specify how to handle dynamic SQL statements during migration.
HCOSS
For SQL Server databases in which dynamic SQL statements are z/OS DB2 statements. This option is required when you are using HCOSS to migrate the database and your code contains z/OS DB2 CREATE SCHEMA statements.
Agnostic
Default. For SQL Server, DB2 LUW, Oracle, and PostgreSQL databases in which dynamic SQL statements are specific to the DBMS vendor specifications.
SQLUTB - Commit
To specify the issuing of single or multiple commit statements during a LOAD operation. The default is a single commit issued after all records have been loaded.

We recommend that you use the single commit to provide optimal performance. However, if DBMS logging or other such issues are a concern, you might prefer the multiple commit. For the multiple commit, you also specify a batch size (number of rows). During the LOAD operation, a commit is issued each time the batch size has been reached.

On Windows platforms, you can run the MBDT Configuration Utility from Eclipse, from the Start menu, or from the command line. On UNIX platforms, the MBDT Configuration Utility is a command-line tool.

Parent topic: Mainframe Batch Database Tools (MBDT)
Related concepts
SQLUTB LOAD
SQLUTB UNLOAD
Mainframe Batch Database Tools (MBDT)
Related tasks
To start the MBDT Configuration Utility UI
Related information
SQLTP2 Utility - Executing Dynamic SQL Statements


SQLTP2 Utility - Executing Dynamic SQL Statements

The SQLTP2 utility is equivalent to DB2 DSNTEP2. It is used to execute dynamic SQL statements embedded in JCL, given an ODBC database connection that is established by an XAR definition in Enterprise Server. In the database migration process, we use it to execute DDL against a DBMS to create and modify schema objects.

Important: Because of referential integrity implementation differences between mainframe DB2 and other DBMSs, we recommend that you include an initial DSNTEP2 step to create your tables. After loading the data, you can run additional DSNTEP2 steps to create your indexes and constraints.

Executing SQLTP2

To use SQLTP2, either create a JCL application project or directly submit JCL using the JES CONTROL feature in Enterprise Server. The JCL syntax must be z/OS DB2 compatible.

When you run the MBDT Configuration utility, you have two options for processing SQL statements. These options are specified as the database type, which can be set to the default, A[gnostic], to use the native DBMS SQL dialect, or set to H[COSS] to use the DB2 dialect for SQL Server. When you set the database type to HCOSS (DB2 dialect for SQL Server), the SQLTP2 utility instructs the OpenESQL runtime to translate z/OS DB2 SQL statements to SQL Server statements before dispatching them for execution.

Note: As part of the environment setup, SQLTP2 initializes the ALLOWNULLCHAR SQL compiler directive option to preserve the X"00" null character in CHAR and VARCHAR fields. See ALLOWNULLCHAR for details.

The following is an example of JCL for a CREATE TABLE statement using the DB2 dialect for SQL Server:

Note: The MBDT Configuration utility HCOSS option does not support SQL statements of mixed dialects. In addition, any SQL Server-specific syntax in SQL statements could cause errors.
//DDLJOB2 JOB
//RESETDB  EXEC PGM=IKJEFT01
//SYSTSPRT DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//SYSPUNCH DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*
//SYSOUT   DD  SYSOUT=*
//SYSTSIN  DD  *
 DSN SYSTEM(HCOD)
 RUN  PROGRAM(DSNTEP2)
 END
/*
//SYSIN DD *
CREATE TABLE HCOSQL.EMP
(
EMPNO       CHAR(6) NOT NULL,
FIRSTNME    VARCHAR(12) NOT NULL,
MIDINIT     CHAR(1) NOT NULL,
LASTNAME    VARCHAR(15) NOT NULL,
WORKDEPT    CHAR(3),
PHONENO     CHAR(4),
HIREDATE    DATE,
JOB         CHAR(8),
EDLEVEL     SMALLINT,
SEX         CHAR(1),
BIRTHDATE    DATE,
SALARY      DECIMAL(9,2),
BONUS       DECIMAL(9,2),
COMM        DECIMAL(9,2),
PRIMARY KEY (EMPNO)
) IN XDBIBMDB.XDBIBMTS;

/*
//

Where HCOD is the ODBC XAR ID for your database connection, SQLTP2 has been established as an alias for DSNTEP2, and the semi-colon (;) is the SQL terminator.

Parameters

The SQLTP2 parameters supported are:

  • ALIGN (MID), ALIGN(LHS)
  • MIXED, NOMIXED
  • TOLWARN(YES), TOLWARN(NO)
  • SQLTERM (termchar)

Control Statements

Control statements for the SYSIN data set use the following syntax:
--#SET control-option-value
Where control-option-value can be any of the following:
  • TERMINATOR
  • ROWS_FETCH
  • ROWS_OUT
  • MAXERRORS
  • TOLARTHWRN
  • TOLWARN
The following control option values and error-raising values are not supported:
  • MULTI-FETCH
  • PREPWARN
  • SQLFORMAT
Note: To ensure proper parsing of SYSIN, do not include the tab character (ASCII decimal character code 9; EBCDIC decimal character code 5) in its contents. When parsed, the tab character could cause spurious, unintended errors.
Parent topic: Mainframe Batch Database Tools (MBDT)
Related concepts
MBDT Configuration Utility


SQLUTB Utility - Loading and Unloading SQL Tables

Starting with Enterprise Developer 2.3, SQLUTB supports both LOAD and UNLOAD. They are both equivalents of the DB2 for z/OS DSNUTILB utility, having the same basic features and options. Although they are primarily designated for database migration, you can also use them to perform routine LOAD and UNLOAD of data, emulating z/OS DSNUTILB LOAD and UNLOAD.

Note: As part of the environment setup, SQLUTB initializes the ALLOWNULLCHAR SQL compiler directive option to preserve the X"00" null character in CHAR and VARCHAR fields. See ALLOWNULLCHAR for details.
  • SQLUTB LOAD
  • SQLUTB UNLOAD
Parent topic: Mainframe Batch Database Tools (MBDT)
Related reference
ALLOWNULLCHAR


SQLUTB LOAD

SQLUTB LOAD is designed to work with LOAD cards generated by DSNUTILB UNLOAD on the mainframe as well as LOAD cards generated by SQLUTB UNLOAD itself. For example, the following UNLOAD control statements generate valid LOAD statements:
UNLOAD DATA FROM TABLE HCOSQL.CUSTOMER
UNLOAD TABLESPACE HCOSQL.HCOTS FROM TABLE HCOSQL.EMPLOYEE
Important: SQLUTB LOAD requires that you modify the LOAD control statement created on the mainframe to include either the REPLACE or the RESUME YES option. If neither is included, the JCL job terminates with an abend.

Executing SQLUTB LOAD

To use SQLUTB LOAD, either create a JCL application project or directly submit JCL using the JES CONTROL feature in Enterprise Server. The JCL syntax must be z/OS DB2 compatible.

The following is an example of JCL using a LOAD card generated on the mainframe:

//DSNCUSTM JOB
//DSNUTILB EXEC PGM=HCOUTILB,PARM='HCOD,SH      '
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//STPRIN01 DD   SYSOUT=*
//IDIOFF   DD   DUMMY
//*
//SYSUT1   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSUT1
//SORTOUT  DD   DISP=MOD,DSN=SH.DSNUTILB.SYSOUT
//SYSMAP   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSMAP
//SYSERR   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSERR
//SYSREC   DD   DISP=SHR,DSN=SH.HCOSQL.CUSTOMRS
//SYSIN    DD   *
LOAD DATA INDDN SYSREC LOG NO RESUME NO REPLACE
 EBCDIC  CCSID(00037,00000,00000)
 INTO TABLE
 "HCOSQL".
 "CUSTOMRS"
 WHEN(00001:00002) = X'0028'
 NUMRECS               242100
 ( "C_ID"
  POSITION(  00003:00006) INTEGER
 , "C_D_ID"
  POSITION(  00007:00008) SMALLINT
 , "C_W_ID"
  POSITION(  00009:00010) SMALLINT
 , "C_FIRST"
  POSITION(  00012:00029) VARCHAR
                          NULLIF(00011)=X'FF'
 , "C_MIDDLE"
  POSITION(  00031:00032) CHAR(00002)
                          NULLIF(00030)=X'FF'
 , "C_LAST"
  POSITION(  00034:00051) VARCHAR
                          NULLIF(00033)=X'FF'
 , "C_STREET_1"
  POSITION(  00053:00074) VARCHAR
                          NULLIF(00052)=X'FF'
 , "C_STREET_2"
  POSITION(  00076:00097) VARCHAR
                          NULLIF(00075)=X'FF'
 , "C_CITY"
  POSITION(  00099:00120) VARCHAR
                          NULLIF(00098)=X'FF'
 , "C_STATE"
  POSITION(  00122:00123) CHAR(00002)
                          NULLIF(00121)=X'FF'
 , "C_ZIP"
  POSITION(  00125:00133) CHAR(00009)
                          NULLIF(00124)=X'FF'
 , "C_PHONE"
  POSITION(  00135:00150) CHAR(00016)
                          NULLIF(00134)=X'FF'
 , "C_SINCE"
  POSITION(  00152:00177) TIMESTAMP EXTERNAL
                          NULLIF(00151)=X'FF'
 , "C_CREDIT"
  POSITION(  00179:00180) CHAR(00002)
                          NULLIF(00178)=X'FF'
 , "C_CREDIT_LIM"
  POSITION(  00182:00188) DECIMAL
                          NULLIF(00181)=X'FF'
 , "C_DISCOUNT"
  POSITION(  00190:00192) DECIMAL
                          NULLIF(00189)=X'FF'
 , "C_BALANCE"
  POSITION(  00194:00200) DECIMAL
                          NULLIF(00193)=X'FF'
 , "C_YTD_PAYMENT"
  POSITION(  00202:00208) DECIMAL
                          NULLIF(00201)=X'FF'
 , "C_PAYMENT_CNT"
  POSITION(  00210:00211) SMALLINT
                          NULLIF(00209)=X'FF'
 , "C_DELIVERY_CNT"
  POSITION(  00213:00214) SMALLINT
                          NULLIF(00212)=X'FF'
 , "C_DATA"
  POSITION(  00216:00717) VARCHAR
                          NULLIF(00215)=X'FF'
 )

/*
//

Where HCOD is the ODBC XAR ID for your database connection, SQLUTB has been established as an alias for program HCOUTILB, and SH.HCOSQL.CUSTOMRS is the cataloged data file mapped to SYSREC.

LOAD Options

Standard LOAD Options
DATA
Syntactically optional.
REPLACE
REPLACE is mutually exclusive to RESUME YES. Either REPLACE or RESUME YES is required.

If neither REPLACE nor RESUME YES are present, warnings are generated based on the target table having an empty status.

DISCARDDN
This option behaves differently from DB2 for z/OS in handling unique index. The utility does not check for duplicates in the input data set, but instead forwards all data to the database. If duplicate records exist in the data set, only the first instance is loaded into the target table, assuming that no existing record in the table has the same index.
LOG NO|YES
This option is syntactically accepted, but ignored, as LOG YES is the only supported behavior.
RESUME YES
RESUME YES is mutually exclusive to REPLACE. Either RESUME YES or REPLACE is required.

If neither RESUME YES nor REPLACE are present, warnings are generated based on the target table having an empty status.

Ignored, but Syntactically Recognized LOAD Options
  • CCSID
  • CONTINUE IF
  • COPYDDN
  • DISCARDS
  • ENFORCE
  • ERRDDN
  • FLOAT (S390/IEEE)
  • FORMAT-SPEC
  • FREQVAL
  • HISTORY
  • INCURSOR
  • INDEX
  • KEEPDICTIONARY
  • KEYCARD
  • MAPDDN
  • NOCOPYPEND
  • NOSUBS
  • PREFORMAT
  • RECOVERYDDN
  • REUSE
  • SHRLEVEL
  • SORTDEVT
  • SORTKEY
  • SORTNUMS
  • STATISTICS
  • WORKDDN
Unsupported LOAD Options
  • COPYDICTIONARY
  • DECFLOAT ROUNDMODE-SPEC
  • IDENTITYOVERRIDE
  • INDEXDEFER
  • PRESORTED

Specifications

INTO TABLE Specifications
The INTO TABLE specifications have a number of options.
INTO TABLE Supported Options
  • WHEN
  • NUMRECS
  • FIELD SPECIFICATION
  • PART (for DB2 LUW only)
Ignored, but Syntactially Recognized INTO TABLE Options
  • IGNOREFIELDS
  • PART (for all DBMSs but DB2 LUW)
LOAD Specification
  • INDDN SYSREC (or ddname)
  • EBCDIC/ASCII/UNICODE
Note: Unlike the mainframe, SQLUTB LOAD does not default to EBCDIC, but defaults to ASCII.
FIELD Specification
Supported SQL Data Types for FIELD Specification
  • INTEGER, BIGINT, SMALLINT
  • FLOAT, REAL
  • DECIMAL
  • CHAR, VARCHAR (UP TO VARCHAR(20000))
  • GRAPHIC, VARGRAPHIC
  • DATE, TIME, TIMESTAMP
  • BINARY, VARBINARY
Unsupported SQL Data Types for FIELD Specification
  • DECFLOAT
  • ROWID
  • BLOB
  • CLOB
  • DBCLOB
  • XML
Important: SQLUTB LOAD commit behavior can be configured to issue one commit or multiple commits. See MBDT Configuration Utility for details.
Note: To ensure proper parsing of SYSIN, do not include the tab character (ASCII decimal character code 9; EBCDIC decimal character code 5) in its contents. When parsed, the tab character could cause spurious, unintended errors.
Parent topic: SQLUTB Utility - Loading and Unloading SQL Tables
Related concepts
SQLUTB UNLOAD
MBDT Configuration Utility
Related reference
mbdtconfig command


SQLUTB UNLOAD

SQLUTB UNLOAD unloads data from a table in a DBMS, and places it into an output data set file. You can use SQLUTB UNLOAD to unload all rows from a table, or unload only those rows that meet certain criteria, such as those selected from a provided field specification list. Output data sets are compatible with z/OS DB2 in both encoding and formatting, and can be used as input to SQLUTB LOAD.

Executing SQLUTB UNLOAD

SQLUTB UNLOAD is similar to DSNUTILB LOAD. Include an SQLUTB UNLOAD card in your JCL, and execute it from an Enterprise Developer JCL project or by submitting the JCL directly using the JES CONTROL feature in Enterprise Server. The JCL syntax must be z/OS DB2 compatible.

The following is an example of JCL using a UNLOAD card:

//ULEMP001  JOB CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,REGION=0M
//DELETE  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE MCS.UNLOAD.ULEMP001
  SET    MAXCC=0
//DSNUTILB EXEC PGM=HCOUTILB,PARM='HCOD,ULEMP001'
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SORTOUT  DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSPRINT DD SYSOUT=*
//UTPRINT  DD SYSOUT=*
//SYSPUNCH DD SYSOUT=*
//SYSREC   DD DSN=MCS.UNLOAD.ULEMP001,DISP=(MOD,CATLG),
//            UNIT=SYSDA,SPACE=(CYL,(1,1)),
//            DCB=(RECFM=VB,LRECL=107,BLKSIZE=6500)
//SYSIN    DD *
   UNLOAD DATA FROM TABLE [DSN8910].[EMP] EBCDIC
/*
//
//         PARM='&SYSTEM,&UID,&UTPROC'
//*STEPLIB  DD   DSN=&LIB,DISP=SHR
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*

Where HCOD is the ODBC XAR ID for your database connection, SQLUTB has been established as an alias for program HCOUTILB, and MCS.UNLOAD.ULEMP001 is the cataloged output data file.

In contrast to DB2 for z/OS DSNUTILB UNLOAD, the default code set for the output of SQLUTB UNLOAD is ASCII instead of EBCDIC. Also, the default record format, RECFM, is FB. You can override the RECFM default with DCB in the SYSREC definition.

UNLOAD Options

Supported Specifications and Options
  • ASCII – default code set
  • EDCDIC – to override the default ASCII if needed
  • MAXERR
  • NOPAD
  • NOSUBS
  • PUNCHDDN
  • PART (for DB2 LUW only)
  • TABLESPACE – does not apply to SQL Server
  • UNICODE – code set
  • UNLDDN
Unsupported Specifications and Options
  • CHARDEL
  • COLDEL
  • CCSID
  • DECFLOAT_ROUNDMODE
  • DECPT
  • DELIMITED
  • FLOAT IEEE
  • FLOAT S390
  • FORMAT INTERNAL
  • FROMCOPY
  • FROMCOPYDDN
  • LIST
  • PART (for all DBMSs except DB2 LUW)
  • SHRLEVEL
Supported FROM TABLE Options
  • FIELD SPECIFICATION
  • HEADER
  • POSITION
  • STRIP
  • TRUNCATE
  • WHEN
Unsupported FROM TABLE Options
  • LIMIT
  • SAMPLE
Supported TABLE FIELD TYPES
  • BIGINT
  • BINARY
  • CHAR
  • CINSTANT
  • DATE EXTERNAL
  • DECIMAL (PACKED)
  • DECIMAL EXTERNAL
  • DOUBLE
  • FLOAT EXTERNAL
  • FLOAT
  • GRAPHIC
  • INTEGER EXTERNAL
  • INTEGER
  • REAL
  • SMALLINT
  • TIME EXTERNAL
  • TIMESTAMP EXTERNAL
  • VARBINARY
  • VARCHAR
  • VARGRAPHIC
Unsupported TABLE FIELD TYPES
  • BLOB
  • CLOB
  • DBCLOB
  • GRAPHIC EXTERNAL
  • ROWID
Note: To ensure proper parsing of SYSIN, do not include the tab character (ASCII decimal character code 9; EBCDIC decimal character code 5) in its contents. When parsed, the tab character could cause spurious, unintended errors.
Parent topic: SQLUTB Utility - Loading and Unloading SQL Tables
Related concepts
SQLUTB LOAD
MBDT Configuration Utility
Related reference
mbdtconfig command


Support for Partitioned Tables in DB2 LUW

Starting with Enterprise Developer 2.3 Update 2, Micro Focus MBDT DSNUTILB supports the DB2 LUW Table Partition Feature for all supported IBM versions of DB2 LUW in terms of data movement from and to partitioned tables in a single partition scope:

  • LOAD can load one partition of a partitioned table within one JCL job
  • UNLOAD can unload one partition of a partitioned table within one JCL job

Neither LOAD nor UNLOAD support parallel data movement from and to multiple partitions of a partitioned table within one JCL job.

To load data into a single partition of partitioned table, include the PART n option in the control statement in the JCL. For example:

//DB2LDPAR JOB
//DSNUTILB EXEC PGM=TSTUTILB,PARM='DB2C,SH      '
//*
//SYSPRINT DD   SYSOUT=*
//UTPRINT  DD   SYSOUT=*
//SYSUDUMP DD   SYSOUT=*
//STPRIN01 DD   SYSOUT=*
//IDIOFF   DD   DUMMY
//*
//SYSUT1   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSUT1
//SORTOUT  DD   DISP=MOD,DSN=SH.DSNUTILB.SYSOUT
//SYSMAP   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSMAP
//SYSERR   DD   DISP=MOD,DSN=SH.DSNUTILB.SYSERR
//SYSREC   DD   DISP=SHR,DSN=MCSDB2.UNLOAD.ULDB2EMP
//SYSIN    DD   *
LOAD DATA INDDN(SYSREC) ASCII
 INTO TABLE TEST.EMPLOYEE PART 1 REPLACE
 WHEN(00001:00002) = X'0001'
 ( "EMPNO"
        POSITION(  00003:00008) CHAR(00006)
 , "FIRSTNME"
        POSITION(  00009:00022) VARCHAR
 , "MIDINIT"
        POSITION(  00024:00024) CHAR(00001)
                          NULLIF(00023)=X'FF'
 , "LASTNAME"
        POSITION(  00025:00041) VARCHAR
 , "WORKDEPT"
        POSITION(  00043:00045) CHAR(00003)
                          NULLIF(00042)=X'FF'
 , "PHONENO"
        POSITION(  00047:00050) CHAR(00004)
                          NULLIF(00046)=X'FF'
 , "HIREDATE"
        POSITION(  00052:00061) DATE EXTERNAL
                          NULLIF(00051)=X'FF'
 , "JOB"
        POSITION(  00063:00070) CHAR(00008)
                          NULLIF(00062)=X'FF'
 , "EDLEVEL"
        POSITION(  00071:00072) SMALLINT
 , "SEX"
        POSITION(  00074:00074) CHAR(00001)
                          NULLIF(00073)=X'FF'
 , "BIRTHDATE"
        POSITION(  00076:00085) DATE EXTERNAL
                          NULLIF(00075)=X'FF'
 , "SALARY"
        POSITION(  00087:00091) DECIMAL
                          NULLIF(00086)=X'FF'
 , "BONUS"
        POSITION(  00093:00097) DECIMAL
                          NULLIF(00092)=X'FF'
 , "COMM"
        POSITION(  00099:00103) DECIMAL
                          NULLIF(00098)=X'FF'
 )
/*
//

The syntax and partition numbering of the JCL follow mainframe DB2 conventions. The partition numbering is 1-based whereas the numbering in DB2 LUW is 0-based. MBDT DSNUTILB converts the two conventions internally. The executed JCL job loads the data set into Partition 0 in DB2 LUW.

To unload data from a single partition of a partitioned table, include the PART n option in the control statement in the JCL in two forms:

UNLOAD TABLESPACE tabespacename PART n FROM TABLE
tablename

And:

UNLOAD TABLESPACE tabespacename PART n

For example:

//ULDB2PAR JOB CLASS=A,MSGCLASS=X,NOTIFY=&SYSUID,REGION=0M
/*JOBPARM  SYSAFF=ANY
//DELETE  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE MCSDB2.UNLOAD.ULDB2PAR
  SET    MAXCC=0
//*------------------------------------------------------------------
//*       EXECUTE DSNUPROC
//*------------------------------------------------------------------
//DSNUTILB EXEC PGM=TSTUTILB,PARM='DB2C,ULDB2PAR’
//SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SORTOUT  DD UNIT=SYSDA,SPACE=(CYL,(10,10))
//SYSPRINT DD SYSOUT=*
//UTPRINT  DD SYSOUT=*
//SYSPUNCH DD SYSOUT=*
//SYSREC   DD DSN=MCSDB2.UNLOAD.ULDB2PAR,DISP=(MOD,CATLG),
//            UNIT=SYSDA,SPACE=(CYL,(1,1))
//SYSIN    DD *
   UNLOAD TABLESPACE PARTSPACE1 PART 1
   FROM TABLE XINYUC.EMPLOYEE2
/*
//

Again, the partition numbering convention follows mainframe DB2 convention. The JCL specifies PART 1 and the actual partition number in DB2 LUW is 0. A punch card specified in the JCL is generated following execution. The unload data set, MCSDB2.UNLOAD.ULDB2PAR, is automatically cataloged by DSNUTILB. The default code set is ASCII, and can be optionally changed to EBCDIC.

Parent topic: Mainframe Batch Database Tools (MBDT)


How to

  • To start the MBDT Configuration Utility UI
  • To run the MBDT Configuration Utility from a command prompt
  • To set a default dialect for SQLTP2
  • To set a default commit behavior for SQLUTB
Parent topic: Mainframe Batch Database Tools (MBDT)


To start the MBDT Configuration Utility UI

Restriction: This topic applies to Windows environments only.
In standalone mode:
Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Configuration > MBDT Configuration Utility.
Windows 8.1
  • From the Windows Start screen, click the MBDT Configuration Utility tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > MBDT Configuration Utility.
From Eclipse:
  • From your Windows desktop, click Run > Tools > Configuration > MBDT Configuration Utility.
Parent topic: How to
Related concepts
MBDT Configuration Utility
Related tasks
To set a default dialect for SQLTP2
To set a default commit behavior for SQLUTB
To run the MBDT Configuration Utility from a command prompt


To run the MBDT Configuration Utility from a command prompt

  1. Start an Enterprise Developer command prompt
  2. Issue the mbdtconfig command.

See To start an Enterprise Developer command prompt and mbdtconfig command for details.

Parent topic: How to
Related tasks
To start the MBDT Configuration Utility UI
To start an Enterprise Developer command prompt


To set a default dialect for SQLTP2

Note: This topic applies to Windows environments only.
  1. Start the MBDT Configuration Utility.
  2. In the Database Selection group, select either HCOSS or Agnostic.
  3. Click Save to confirm changes.
  4. Click OK to close the MBDT Configuration Utility.
Parent topic: How to
Related tasks
To set a default commit behavior for SQLUTB
To start the MBDT Configuration Utility UI


To set a default commit behavior for SQLUTB

Restriction: This topic applies to Windows environments only.
  1. Start the MBDT Configuration Utility.
  2. In the Commit group, select either Single commit... or Multiple commit....
  3. If you have selected Multiple commit..., in the Batch Size field, type the number of rows to process in each batch before committing.
  4. Click Save to confirm changes.
  5. Click OK to close the MBDT Configuration Utility.
Parent topic: How to
Related tasks
To set a default dialect for SQLTP2
To start the MBDT Configuration Utility UI


Reference

  • mbdtconfig command
    Runs the command-line version of the MBDT Configuration Utility.
  • MBDT and DBMS Data Types
Parent topic: Mainframe Batch Database Tools (MBDT)


mbdtconfig command

Runs the command-line version of the MBDT Configuration Utility.
Important: In Windows environments, yYou must run this command from a 32-bit or a 64-bit Enterprise Developer command prompt. For instructions, see To start an Enterprise Developer command prompt.
Note: UNIX platforms support only the 32-bit version of mbdtconfig.

Syntax

mbdtconfig -t {{H[COSS] | A[gnostic]} | -s size={0 | n}}

Parameters

-t
Sets the database type.
H[COSS]
Indicates a SQL Server database in which CREATE SCHEMA object statements are z/OS DB2 statements.
A[gnostic]
Indicates a SQL Server, DB2 LUW, Oracle, or PostgreSQL database in which CREATE SCHEMA object statements are specific to the DBMS vendor specifications. This option does not support mainframe DB2 DDL. Default.
-s
Sets the commit behavior.
size=
Set this to zero (0) to issue a single commit after all records have been loaded. Default.

Provide a number, represented here as n, to indicate multiple commits, each after n rows have been processed.

Parent topic: Reference
Related concepts
SQLUTB LOAD
SQLUTB UNLOAD
Related tasks
To start an Enterprise Developer command prompt


MBDT and DBMS Data Types

The DSNTEP2 and DSNUTILB batch utilities use ODBC, and therefore ODBC data types, to communicate with a DBMS. The following table shows the supported DBMS data types these utilities support. Footnotes provide additional information and/or restrictions.

ODBC Data Types | HCOSS (DB2 for z/OS) | SQL Server | DB2 LUW | Oracle | PostgreSQL
SQL_CHAR | CHAR | CHAR | CHAR | CHAR | CHAR
SQL_LONG_VARCHAR | VARCHAR | VARCHAR | VARCHAR | VARCHAR2 | VARCHAR
SQL_WCHAR | GRAPHIC | NCHAR | GRAPHIC | NCHAR | CHAR
SQL_WVARCHAR | VARGRAPHIC | NVARCHAR | VARGRAPHIC | NVARCHAR2 | VARCHAR
SQL_BIGINT | BIGINT | BIGINT | BIGINT | NUMBER(19,0) | BIGINT
SQL_INTEGER | INT | INT | INT | NUMBER(10,0) | INT
SQL_SMALLINT | SMALLINT | SMALLINT | SMALLINT | NUMBER(5) | SMALLINT
SQL_TINYINT | SMALLINT 1 | TINYINT 1 | SMALLINT 1 | NUMBER(3) 1 | SMALLINT 1
SQL_DOUBLE | FLOAT | FLOAT(53) | FLOAT | BINARY_DOUBLE | DOUBLE PRECISION
SQL_REAL | REAL | REAL | REAL | BINARY_FLOAT | REAL
SQL_DECIMAL(p,s) | DECIMAL(p,s) | DECIMAL(p,s) | DECIMAL(p,s) | NUMBER(p,s) | DECIMAL(p,s) 2
SQL_NUMERIC(p,s) | NUMERIC(p,s) | NUMERIC(p,s) | NUMERIC(p,s) | NUMBER(p,s) | NUMERIC(p,s) 2
SQL_BIT | CHAR(1) 1 | BIT 1 | CHAR(1) 1 | NUMBER(3) 1 | BOOLEAN 1
SQL_GUID | CHAR(36) 1 | GUID 1 | CHAR(36) 1 | CHAR(36) 1 | CHAR(36) 1
SQL_BINARY | BINARY | BINARY | CHAR FOR BIT DATA | RAW 1 | BYTEA 1
SQL_VARBINARY | VARBINARY | VARBINARY | VARCHAR FOR BIT DATA | RAW 1 | BYTEA 1
SQL_LONGVARBINARY | BLOB 4 | BLOB 4 | BLOB 4 | LONG RAW 4 | BYTEA 4
SQL_WLONGVARCHAR | CLOB 4 | CLOB 4 | CLOB 4 | LONG 4 | TEXT 4
SQL_DATE | DATE | DATE | DATE | DATE 3 | DATE
SQL_TYPE_TIME | TIME | TIME | TIME | CHAR(15) 1 | TIME
SQL_TIMESTAMP | TIMESTAMP | DATETIME2(6) | TIMESTAMP | DATE 3 | TIMESTAMP

1 Supported in DSNTEP2 and DSNUTILB (LOAD and UNLOAD) with cited equivalent data types

  • For PostgreSQL data type BYTEA, the sqlvar.sqllen is 255
  • For Oracle data type RAW, the maximum width is 200
  • For SQL Server data type TINYINT, OpenESQL maps it to SMALLINT
  • For SQL Server data type BIT, OpenESQL maps it to TINY (one byte)
  • For SQL Server data type GUID, OpenESQL maps it to CHAR (36)
  • For PostgreSQL data type BOOLEAN, OpenESQL maps it to VARCHAR(5)

2 PostgreSQL data types DECIMAL and NUMERIC are supported in DSNTEP2 and DSNUTILB (LOAD and UNLOAD) where the supported range is s <= p <= 38.

3 Oracle DATE data type has both date and time, and is supported in DSNTEP2 and DSNUTILB (LOAD and UNLOAD)

4 Unsupported in DSNTEP2 and DSNUTILB (LOAD and UNLOAD)

Parent topic: Reference


Loading XDB Database Table Rows (XUTLB)

XUTLB emulates the functions of the DSNUTILB utility for loading rows into XDB tables.

Note: You can only use this utility with XDB databases.
  • JCL Statements
    This section describes the JCL statements used with the XUTLB utility.
Parent topic: Emulations of Mainframe Utilities


JCL Statements

In the EXEC statement you need to specify the program name XUTLB or its alias DSNUTILB. For example:

//STEPEXEC DSNUTILB, ...

The PARM parameters are the same as for DSNUTILB; however, XUTLB provides the following additional parameter:

FBD
Checks for x'00' in columns defined as CHAR, VARCHAR, or LONGVARCHAR; if found, the table column definition is changed to enable FOR BIT DATA.

For example:

//UTILSAMP EXEC PGM=DSNUTILB,REGION=1024K,
//             PARM='DB5B,MFIMAG,,FBD'
  • DD Statements
    The DD statements required by XUTLB are the same as for DSNUTILB.
Parent topic: Loading XDB Database Table Rows (XUTLB)


DD Statements

The DD statements required by XUTLB are the same as for DSNUTILB.

See the relevant IBM documentation for details.

Parent topic: JCL Statements


Executing Dynamic SQL statements (XTEP2)

XTEP2 emulates the functions of the DSNTEP2 utility for executing dynamic SQL statements.

Note: You can only use this utility with XDB databases.
  • JCL Statements
Parent topic: Emulations of Mainframe Utilities


JCL Statements

This section describes the JCL statements used with the XTEP2 utility

In the EXEC statement you need to specify the program name XTEP2 or its alias DSNTEP2. For example:

//STEPEXEC DSNTEP2, ...
  • DD Statements
    The DD statements required by XTEP2 are the same as for DSNTEP2.
Parent topic: Executing Dynamic SQL statements (XTEP2)


DD Statements

The DD statements required by XTEP2 are the same as for DSNTEP2.

See the relevant IBM documentation for details.

Parent topic: JCL Statements


Running REXX Execs in MVS Batch Mode (MFIRXJCL)

It starts an MVS session in batch mode and runs the REXX exec specified in the PARM parameter. For more information about the REXX support in MSS see the chapter REXX Support.

  • JCL Statements
    This section describes the JCL statements used with the MFIRXJCL utility.
Parent topic: Emulations of Mainframe Utilities
Related information
REXX Support


JCL Statements

  • EXEC Statement
  • DD Statements
Parent topic: Running REXX Execs in MVS Batch Mode (MFIRXJCL)


EXEC Statement

In the EXEC statement you need to specify the program name MFIRXJCL, or its alias IRXJCL, and the name of the REXX exec as the first word in the PARM parameter. For example:

//STEPEXEC PGM=IRXJCL,PARM='REXXEXEC'
Parent topic: JCL Statements


DD Statements

The following DD statements may be required:

SYSTSIN
For the data set that contains input to the REXX exec. It can be an instream data set.
SYSTSPRT
For the data set that contains output from the exec.
SYSEXEC
SYSPROC
If the exec is a member of a PDS.

You must also include any DD statements for data sets that are accessed by the exec.

Parent topic: JCL Statements


VSAM Access Method Services (MFJAMS)

MFJAMS emulates some of the main functions of the IDCAMS mainframe utility.
Note: The level of support is limited to the functionality specified in this section. Some commands and parameters not referenced in this section may be parsed and are safely ignored, but other such functionality not referenced may cause your application to fail.

This emulation provides the following management services for VSAM key-sequenced data sets (KSDS), entry-sequenced data sets (ESDS) and relative-record data sets (RRDS).

  • ALTER, to change the attributes of a VSAM data set
  • CANCEL, to terminate the processing of the IDCAMS command stream
  • DEFINE ALTERNATEINDEX, to define alternate indices for a VSAM data set
  • DEFINE CLUSTER, to define a new VSAM data set
  • DEFINE PATH, to support path data sets
  • DELETE, to delete data sets
  • DO-END, to be used in conjunction with IF-THEN-ELSE to conditionally process several commands
  • IF-THEN-ELSE, to be used to conditionally execute commands, or groups of commands if used in conjunction with the DO-END command sequence
  • LISTCAT, to list catalog entries
  • PRINT, to print a data set
  • REPRO, to copy a data set
  • SET, to change the condition code
  • VERIFY, to verify a VSAM data set

You can use some of these services for sequential data sets, partitioned data sets and generation data groups. All abbreviations of these commands and their parameters that are valid on the mainframe are supported by MFJAMS.

You can execute MFJAMS via a JCL jobstream or REXX exec.

For more information on VSAM access method services, see the IBM manual DFSMS/MVS Access Method Services for VSAM, SC26-4905.

  • Working with Empty Data Sets
  • File Structure
  • JCL Statements
  • Commands
  • Condition codes
Parent topic: Emulations of Mainframe Utilities


Working with Empty Data Sets

In previous versions of this software, an empty VSAM data set, for example a data set that had just been defined, did not show as being empty. As a result, some of the IDCAMS commands that MFJAMS emulates, for example REPRO and PRINT, processed zero records and generated a condition code of 0.

This behavior differs from the corresponding mainframe IDCAMS utility for newly-defined VSAM data sets which generates I/O errors with a condition code of 12.

The behavior of MFJAMS is now consistent with that of IDCAMS.

Note: Empty VSAM data sets created by previous versions of this software still generate a condition code of 0 in such cases. To ensure that these data sets are handled in a manner that is consistent with IDCAMS behavior you must delete and then redefine them.

Defining New VSAM files

When a new VSAM file is defined, its virgin file state is recorded in the catalog. Each request to the catalog for information about the file includes a check for the virgin status until the status is changed to non-virgin.

After that, no further checks are performed unless the user defined the file location using the ;MFE:%PCDSN extension to IDCAMS.

If you want to overlay a non-virgin file with a virgin one and have the catalog detect the virgin state, the original file definition using IDCAMS DEFINE must include the file location using the ;MFE:%PCDSN extension to IDCAMS.

Parent topic: VSAM Access Method Services (MFJAMS)
Related reference
IDCAMS Extensions
Related information
File Structure
JCL Statements
Commands
Condition codes


File Structure

Unlike the mainframe, a VSAM KSDS or ESDS data set is usually represented under Windows or UNIX by two files - a data file, which contains the actual data records for the VSAM data set, and an index file, which contains the primary and alternate key data. These files usually have filename extensions of .dat and .idx respectively. The exception is where IDXFORMAT8 files are in use; these have just a .dat file.

Although the two-file structure affects the way that IDCAMS commands are processed, it does not change the final outcome of the commands. The results of executing commands in a non-mainframe environment is the same as on the mainframe. MFJAMS ignores those parts of a command that have no relevance in a non-mainframe environment. For example, because the VSAM file structure under Windows or UNIX does not provide CI or CA sizes to manipulate, these command parameters are ignored.

Parent topic: VSAM Access Method Services (MFJAMS)
Related information
Working with Empty Data Sets
JCL Statements
Commands
Condition codes


JCL Statements

  • EXEC Statement
  • DD Statements
Parent topic: VSAM Access Method Services (MFJAMS)
Related information
Working with Empty Data Sets
File Structure
Commands
Condition codes


EXEC Statement

In the EXEC statement you need to specify the program name MFJAMS or its alias IDCAMS. For example:

//STEPEXEC PGM=IDCAMS,.......
Parent topic: JCL Statements


DD Statements

The following DD statements are required for all uses of MFJAMS:

SYSIN
For the data set that contains the input commands. It can be an in-stream data set
SYSPRINT
For the output listing data set. It must have an LRECL value of at least 121.

The following DD statements are used by some commands:

  • For the data sets that are used for input to the PRINT, REPRO and VERIFY commands. The DD statement can have any valid dd-name, such as INFILE.
  • For the data sets that are used for output from the PRINT and REPRO commands. The DD statement can have any valid dd-name, such as OUTFILE.
Parent topic: JCL Statements


Commands

  • ALTER
    The ALTER command changes the attributes of an MVS data set.
  • CANCEL
    The CANCEL command terminates the processing of the IDCAMS command stream, including any part of an IF-THEN-ELSE statement sequence or DO-END pair.
  • DEFINE ALTERNATEINDEX
    The DEFINE ALTERNATEINDEX command creates an alternate index for an existing VSAM data set. It also automatically reindexes the data set to maintain consistency between the data and index files on the PC. The alternate index is contained within the same file as the primary index.
  • DEFINE CLUSTER
    The DEFINE CLUSTER command creates a new VSAM data set. It creates the data and index files on the local machine and catalogs the data set name.
  • DEFINE PATH
    The DEFINE PATH command causes MFJAMS to create a dummy path data set so that any DD statement that refers to the data set will not fail. The data set is not needed for any other purpose because MFJAMS implements this function in a different way to the mainframe.
  • DELETE
    The DELETE command deletes up to 99 data sets. It can be used for both VSAM and non-VSAM data sets. It deletes the local files associated with the data set and removes the entry from the catalog.
  • DO-END
    The DO-END command sequence is used in conjunction with the IF-THEN-ELSE sequence to conditionally process several commands.
  • IF-THEN-ELSE
    The IF-THEN-ELSE command sequence is used to conditionally execute commands, or groups of commands if used in conjunction with the DO-END command sequence.
  • LISTCAT
    The LISTCAT command lists the data set names contained in the catalog.
  • PRINT
    The PRINT command prints the contents of both VSAM and non-VSAM data sets. It prints a complete data set or part of a data set in character format, hexadecimal format or both formats.
  • REPRO
    The REPRO command copies the contents of one data set to another. The data sets can have either VSAM or sequential organization.
  • SET
    The SET command alters a condition code set by previous MFJAMS commands in this job step.
  • VERIFY
    The VERIFY command attempts to open a VSAM data set in order to verify that it can be read and that the index is usable. The data set is assumed to be readable if it can be opened without error or if it is locked to another process.
Parent topic: VSAM Access Method Services (MFJAMS)
Related information
Working with Empty Data Sets
File Structure
JCL Statements
Condition codes


ALTER

The ALTER command changes the attributes of an MVS data set.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

data-set-name
Name of the data set to be renamed. This parameter is required.
{EMPTY|NOEMPTY}
Determines processing when the maximum number of generation data sets (GDSs) has been cataloged.
LIMIT(limit)
Determines the maximum number (between 1 and 255) of active generation data sets (GDSs) that might be associated with a generation data group (GDG) base.
NEWNAME(data-set-name)
The new name for the data set. This parameter is required.
When a data set is renamed, the underlying physical file is also renamed, as long as it is stored within a directory under the one in which the catalog file is stored. To rename a physical file stored outside of sub-directories of the catalog, set the environment variable MF_PCRENAME_LAX=Y. Setting this variable causes the filename to be changed, but the location is not changed. For allocation overrides to take effect, which may include changing the directory the file is stored in, set MF_PCRENAME_LAX=D.
Warning: When used on a Dynamic PDS, the name of the cataloged PO dataset will change, but not the location or names of the PDS members. If a file is moved from a disk-based file system to a Fileshare hosted one, or vice-versa, or between two different Fileshare servers, the file needs to be copied. This can take some time, depending on the number of records in the file.
{SCRATCH|NOSCRATCH}
Determines whether generation data sets, when they are uncataloged, are to be deleted.
SHAREOPTIONS(crossregion[ crosssystem])
Abbreviation: SHR
Used when a cluster, data or index component of a cluster or alternate index can be shared among users. No default value is assumed in this system. To nullify an existing value use SHAREOPTIONS(0,0). See the SHAREOPTIONS help topic for more information.
MANAGEMENTCLASS(class)
Abbreviation: MGMTCLAS
Gives the name, 1 to 8 characters, of the management class for a data set. This parameter is required.

Comments:

Within NEWNAME, you cannot use * as a qualifier to rename a number of data sets with one command. For example, ABC.*.FILE is not permitted.

Parent topic: Commands


CANCEL

The CANCEL command terminates the processing of the IDCAMS command stream, including any part of an IF-THEN-ELSE statement sequence or DO-END pair.

Parameters

The CANCEL command has no parameters.

Comments

This results int the stream being terminated with a return code in register 15 equal to the value of the highest condition code encountered before the CANCEL command was executed.

Parent topic: Commands


DEFINE ALTERNATEINDEX

The DEFINE ALTERNATEINDEX command creates an alternate index for an existing VSAM data set. It also automatically reindexes the data set to maintain consistency between the data and index files on the PC. The alternate index is contained within the same file as the primary index.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

NAME(data-set-name)
Name of the data set. This parameter is required.
KEYS(length offset)
Length and offset, relative to 0, of the alternate key field. The offset must be within the first 4,096 bytes of the record. Length plus offset must not exceed the maximum length of the record. The default is KEYS(64 0).
UNIQUEKEY
Each alternate key value in the records is unique.
NONUNIQUEKEY
The alternate key values may contain duplicates.
RELATE(data-set-name)
Name of a cataloged VSAM data set to which the alternate index is to be related.

Comments:

  • UNIQUEKEY and NONUNIQUEKEY are mutually exclusive. NONUNIQUEKEY is the default.
  • Because MFJAMS automatically reindexes the data set, the BLDINDEX parameter is assumed even if it is not specified.
  • You can create up to seven alternate indices in one invocation of MFJAMS. Enter separate commands for each index. MFJAMS performs a single reindexing operation for all the alternate indices.
  • MFJAMS does not support the Micro Focus split-key and key-compression features. MSS cannot open a VSAM data set that uses either of these features.
Parent topic: Commands


DEFINE CLUSTER

The DEFINE CLUSTER command creates a new VSAM data set. It creates the data and index files on the local machine and catalogs the data set name.

Syntax:

DEFINE CLUSTER (parameters) -
             [DATA(parameters)] -
             [INDEX(parameters)] -
             [CATALOG(parameters)]

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

NAME(data-set-name)
Name of the VSAM data set. This parameter is required.
CYLINDERS(primary[ secondary])
The amount of space, in cylinders, allocated to the cluster from the volume's available space. This parameter only has an effect when running in a mainframe environment.
KILOBYTES(primary[ secondary])
The amount of space, in kilobytes, allocated to the cluster from the volume's available space. This parameter only has an effect when running in a mainframe environment.
MEGABYTES(primary[ secondary])
The amount of space, in megabytes, allocated to the cluster from the volume's available space. This parameter only has an effect when running in a mainframe environment.
RECORDS(primary[ secondary])
The amount of space, in records, allocated to the cluster from the volume's available space. This parameter only has an effect when running in a mainframe environment.
TRACKS(primary[ secondary])
The amount of space, in tracks, allocated to the cluster from the volume's available space. This parameter only has an effect when running in a mainframe environment.
VOLUMES(volser[ volser...])
Specifies the volumes on which a cluster's components are to have space. This parameter only has an effect when running in a mainframe environment.
DATACLASS(class)
Specifies the name of the data class for the new data set.
CONTROLINTERVALSIZE(size)
The size of the control interval for the cluster. This parameter only has an effect when running in a mainframe environment.
MANAGEMENTCLASS
Specifies the name of the management class for the new data set.
REUSE|NOREUSE
Specifies whether or not the cluster can be opened again and again as a reusable cluster.
LINEAR
Indicates a data set for linear data is being defined.
INDEXED
Indicates a KSDS data set is being defined.
NONINDEXED
Indicates an ESDS data set is being defined.
NUMBERED
Indicates an RRDS data set is being defined.
KEYS(length offset)
Length and offset, relative to 0, of the primary key field for a KSDS data set. The offset must be within the first 4096 bytes of the record. length plus offset must not exceed the maximum length of the record. The default is KEYS(64 0).
RECORDSIZE(average maximum)
Average and maximum lengths of the records, expressed in decimal format. The default is RECORDSIZE(4089 4089).
MODEL(data-set-name)

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

Name of a cataloged VSAM data set that has the same KEYS and RECORDSIZE parameters as this new data set. It is an alternative to specifying the parameters explicitly.
SHAREOPTIONS(crossregion[ crosssystem])
Defines component or cluster sharing among users. To ensure integrity, you should be sure that share options specified at the DATA and INDEX levels are the same. See the SHAREOPTIONS help topic for details.
Note: SMS-managed volumes and catalogs with SMS-managed data sets must not be shared with non-SMS systems.

The values of the SHAREOPTIONS parameters is assumed to be (3,3) when the data set is accessed in VSAM RLS or DFSMStvs mode.

ACCOUNT
This parameter is parsed, but ignored.
BUFFERSPACE(size)
This parameter is parsed, but ignored.
BWO(TYPECICS|TYPEIMS|NO)
This parameter is parsed, but ignored.
EATTR(NO|OPT)
This parameter is parsed, but ignored.
ERASE|NOERASE
This parameter is parsed, but ignored.
EXCEPTIONEXIT(entry-point)
This parameter is parsed, but ignored.
FILE(ddname)
This parameter is parsed, but ignored.
FREESPACE(CI-percent [CA-percent]|0 0)
This parameter is parsed, but ignored.
FRLOG(ALL|NONE|REDO|UNDO)
This parameter is parsed, but ignored.
LOG(NONE|UNDO|ALL)
This parameter is parsed, but ignored.
LOGSTREAMID(logstream)
This parameter is parsed, but ignored.
OWNER(ownerid)
This parameter is parsed, but ignored.
RECATALOG|NORECATALOG
This parameter is parsed, but ignored.
SPANNED|NONSPANNED
This parameter is parsed, but ignored.
SPEED|RECOVERY
This parameter is parsed, but ignored.
STORAGECLASS(class)
This parameter is parsed, but ignored.
TO(date)|FOR(days)
This parameter is parsed, but ignored.
WRITECHECK|NOWRITECHECK
This parameter is parsed, but ignored.

Comments:

  • The file will be created as Variable Length records. This could be changed by the program that first writes to the file. If the first program accesses the file with fixed length records, then the file record type will be changed from variable to fixed.
  • INDEXED, NONINDEXED and NUMBERED are mutually exclusive. INDEXED is the default.
  • MFJAMS does not allow duplicate entries of the primary key.
  • KEYS and RECORDSIZE override the values obtained from MODEL.
  • MFJAMS does not support the Micro Focus split-key and key-compression features.

Example:

Here is a typical job to define a cluster:

//DEFCLUS  JOB  CLASS=A
//IDCSTEP  EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  DEFINE CLUSTER(NAME(TEST.KSDS.DUMMY) KEYS(5,0) -
       RECORDSIZE(80,80) CYL(1 1))

Note the use of the continuation character (-) in the DEFINE CLUSTER statement.

  • SHAREOPTIONS
    Details the SHAREOPTIONS property used in a VSAM cluster.
Parent topic: Commands


SHAREOPTIONS

Note: This feature currently is only enabled by setting the environment variable ES_SHAREOPT to Y.

For use with the VSAM DEFINE CLUSTER command, DATA, or INDEX components of a cluster, or the Alternate Index command, SHAREOPTIONS has the following syntax:

Syntax

SHAREOPTIONS(crossregion [crosssystem])

Options

crossregion specifies the sharing allowed among regions within the same system or within multiple systems using a single lock manager. Independent job steps in a JES region, or multiple JES regions using a single lock manager, and/or multiple CICS users, can have concurrent access. The user must use DISP=SHR in the data set's DD statement to share the data set. You can use these options:

  • 0 - SHAREOPTIONS values are not applied to the DSN.
  • 1 - The data set can be shared by multiple users for read-only processing, or by a single user for read and write processing.
  • 2 - The data set can be accessed by multiple users for read-only processing, and can also be accessed by a single user for write processing.
  • 3 - The data set can be fully shared by multiple users. Each user is responsible for maintaining both read and write integrity of the program data.
  • 4 - The data set can be fully shared by multiple users. Each user is responsible for maintaining both read and write integrity of the program data. VSAM refreshes the buffers used for direct processing before each request.

crosssystem defines the sharing allowed among systems. Cross-system sharing is not yet supported. However, any value set for crosssystem is read and stored in the catalog and in the data file, which can be included when sending a job step to the mainframe for processing. The values are:

  • 0 - SHAREOPTIONS values are not applied to the DSN.
  • 1 - Reserved.
  • 2 - Reserved.
  • 3 - The data set can be fully shared by multiple users. Each user is responsible for maintaining both read and write integrity of the program data.
  • 4 - The data set can be fully shared by multiple users. Each user is responsible for maintaining both read and write integrity of the program data. VSAM refreshes the buffers used for direct processing before each request.

Description

The cross-region parameter applies to either a single region or all regions that are part of an ES Cluster.

VSAM SHAREOPTIONS may be specified for a data set using the IDCAMS DEFINE CLUSTER command, together with the associated DATA, INDEX and AIX components, or the ALTER command. Unlike the mainframe, there is no default value. If the option is not specified then the additional share option processing is not performed. This is to ensure backward compatibility with existing file processing, and is equivalent to specifying SHAREOPTIONS option values of 3,3. If a data set with SHAREOPTIONS is being used by CICS, the FCT must be set to use the cataloged data set. Using the share options does involve additional processing so unless it is required, it is best not to set values for the options.

To nullify an existing SHAREOPTIONS setting, so that it is not used, you can use the ALTER command to set the value to (0,0).

Restrictions

Because a single lock manager is used, options are only valid within a single region or within multiple regions that are part of an Enterprise Server cluster.

Since the parameter values are held in the catalog record, all regions that wish to use VSAM SHAREOPTIONS must also be JES enabled. The crossregion option applies to either a single region or all regions that are part of an ES Cluster. The crosssystem option is not processed as both option 3 and 4 are the equivalent of the current file handling process. Within the Micro Focus File Handling system there is no difference between options 3 and 4 for either crossregion or crosssystem.

The crossregion options values 3 and 4 are considered the same because the File Handler has knowledge of the file state and refreshes data as required.

VSAM SHAREOPTIONS must not be modified for a file while the file is open.

Because there is no default value it is important to specifically set a SHAREOPTIONS value if you wish it to be used. All the CLUSTER and AIX components should have the same SHAREOPTIONS value, so that any of the components can be referenced by a batch job or by a CICS FCT and participate in the controlled shared access using the same value.

Parent topic: DEFINE CLUSTER


DEFINE PATH

The DEFINE PATH command causes MFJAMS to create a dummy path data set so that any DD statement that refers to the data set will not fail. The data set is not needed for any other purpose because MFJAMS implements this function in a different way to the mainframe.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

NAME(data-set-name)
Name of the path data set. This parameter is required.
Parent topic: Commands


DELETE

The DELETE command deletes up to 99 data sets. It can be used for both VSAM and non-VSAM data sets. It deletes the local files associated with the data set and removes the entry from the catalog.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

data-set-names
Names of the data sets to be deleted. This parameter is required. You can specify a list of names separated by blanks and enclosed in parentheses. You can also specify generic names by using '*' as a qualifier. For example, a generic data set name of ABC.*.FILE means all data sets with ABC as the first qualifier, any value as the second qualifier, and FILE as the third and last qualifier.
FORCE
All GDG data sets will be deleted in addition to the GDG catalog entry.
NOFORCE
The GDG catalog entry will not be deleted if any GDG data sets exist.

Comments:

FORCE and NOFORCE are mutually exclusive. NOFORCE is the default.

Parent topic: Commands


DO-END

The DO-END command sequence is used in conjunction with the IF-THEN-ELSE sequence to conditionally process several commands.

Parameters

The DO-END command sequence has no parameters.

Comments

The DO command specifies that the group of commands that follow is to be treated as a single unit, that is, to be executed as a result of a single IF command. The set of commands is terminated by END. A command following a DO must begin on a new line.

The END command specifies the end of a set of commands initiated by the nearest unended DO. END must be on a line by itself.

Note: Continuation characters should not be used in the DO-END sequence; they may be taken as a null command or cause unpredictable results.
Parent topic: Commands
Related reference
IF-THEN-ELSE


IF-THEN-ELSE

The IF-THEN-ELSE command sequence is used to conditionally execute commands, or groups of commands if used in conjunction with the DO-END command sequence.

Syntax

IF {LASTCC|MAXCC} operator number
THEN[ command |
 DO
 command set
 END]
[ELSE[command |
 DO
 command set
 END]]

Parameters

LASTCC

specifies that the condition code value that resulted from the immediately preceding function command is to be compared, as indicated by the operator, to the number following the operator. See Condition codes

MAXCC

specifies that the maximum condition code value that has been established by any previous function command or by a SET command is to be compared, as indicated by the operator, to the number following the operator to determine whether the THEN action is to be performed.

operator

specifies the comparison to be made between the variable and the following number. Can be one of:

Operator | Description
= or EQ | Equal
¬= or NE | Not equal
> or GT | Greater than
< or LT | Less than
>= or GE | Greater than or equal
<= or LE | Less than or equal
number

specifies the decimal integer that is to be compared with MAXCC or LASTCC. Both LASTCC and MAXCC are initialized to zero upon entry to access method services.

Any value can be used in the comparison. Refer to Condition Codes for the standard values set by MFJAMS, but you can set any value by use of the SET statement; for example:

...
IF LASTCC = 0 THEN
 DO
   SET LASTCC = 2
 END
IF LASTCC = 2...

Comments

Condition codes that are tested in the IF-THEN-ELSE command sequence or set by the SET command cannot be passed from one job step to the next. However, the maximum condition code value established by any previous functional command or SET command is passed to the operating system when the access method services processor returns control to the system.

When an IF command appears in a THEN or ELSE clause, it is called a nested IF command. The maximum level of nesting allowed is 10, starting with the first IF specified. Within a nest of IF commands, the innermost ELSE clause is associated with the innermost THEN clause, the next innermost ELSE clause with the next innermost THEN clause, and so on. Should there be an IF command that does not require an ELSE clause, follow the THEN clause with a null ELSE clause (ELSE), unless the nesting structure does not require one.

If THEN or ELSE is not followed by a continuation character or by a command in the same record, the THEN or ELSE results in no action. The null command supports an ELSE command that balances an IF-THEN-ELSE command sequence, and allows null THEN commands. The null command is, in essence, a THEN or ELSE command that is not followed by a command continuation character.

To indicate a null ELSE command, specify:

ELSE

To indicate a null THEN command, specify:

IF ... THEN
ELSE ...
Parent topic: Commands
Related reference
DO-END
Condition codes


LISTCAT

The LISTCAT command lists the data set names contained in the catalog.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

ALL
Causes the physical file, if any, to be listed in the output.
ENTRIES(data-set-names)
Names of the data sets to be listed. You can specify a list of names separated by blanks. You can also specify generic names by using '*' as a qualifier. For example, a generic data set name of ABC.*.FILE means all data sets with ABC as the first qualifier, any value as the second qualifier and FILE as the third and last qualifier.
LEVEL(level)
Prefix qualifier of the data sets to be listed. For example, a level of ABC means all data sets with ABC as the first, high-level, qualifier.

Comments:

ENTRIES and LEVEL are mutually exclusive; you can specify only one of them. LEVEL(*) is the default if neither is specified.

Output format:

The LISTCAT MFJAMS command generates a detailed columnar output report.
Column Heading | Description
DSN Dataset Name - e.g. xxxxxxxx - MFIDSA.DO.NOT.DELETE.B1057624.KSDS1 where xxxxxxxx is one of:
  • AIX
  • CLUSTER
  • DATA
  • INDEX
  • PATH
  • MODEL
  • GDG BASE
  • NONVSAM
C | Cataloged: Y=yes, N=uncataloged, S=Spool
C | CHARSET: EBCDIC or ASCII
DSOR | Dataset Organisation
RecF | Record Format
Lrecl | Logical Record Length
Blksi | Block Size
KyL | Key Length
KyOff | Key Offset
GDG/SHR | Maximum GDG generations or VSAM SHAREOPTIONS value. If the first entry returned by LISTCAT is a VSAM dataset, then the column heading is SHR to show the share options; otherwise, the heading is GDG to show the bias limit.
S | Roll-up disposition: S=SCRATCH, N=NOSCRATCH
E | GDG EMPTY (E) or NOEMPTY (N)
UK | UNIQUEKEY (UK) / NONUNIQUEKEY (NU) for AIX and PATHs
RU | REUSE (RE) / NOREUSE (NR)
XD | Extended dataset type (P=PDS, L=PDSE, I=PIPE, H=HFS)
XR | Extended RBA support (Y=yes)
XT | Extended Type: A=Aix, C=Cluster, P=Path, M=Model, E=Aix Index, J=Aix Data, I=Index, D=Data, ?=Unknown
Dataclas | The MGMTCLAS is shown on line #1 and DATACLAS on line #2
Volume | <null>
RecMn | Minimum Logical Record Length
RecMx | Maximum Logical Record Length
Changed Job/On/At | Jobname/date/time of the process that last updated the dataset's catalog record
Created Job/On/At | Jobname/date/time when created

If the ALL option is specified, a new line entitled PC FILE lists the physical file.

Parent topic: Commands


PRINT

The PRINT command prints the contents of both VSAM and non-VSAM data sets. It prints a complete data set or part of a data set in character format, hexadecimal format or both formats.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

INFILE(ddname)
Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be printed.
INDATASET(data-set-name)
Name of the data set that is to be printed.
OUTFILE(ddname)
Name of the DD statement for the printed output. The data set must have an LRECL value of at least 121. If you omit OUTFILE, the SYSPRINTDD statement is assumed.
FROMKEY(key)
For a VSAM KSDS data set only, the key of the first record to print. Printing starts at the record with the same primary key, or the record with the nearest higher key if an exact match does not occur. Alternate indices are not used.
TOKEY(key)
For a VSAM KSDS data set only, the key of the last record to print. Printing ends at the record with the same primary key, the record with the nearest higher key if an exact match does not occur, or end of file. Alternate indices are not used.
SKIP(number)
The number of records to skip before printing starts.
COUNT(number)
The number of records to print.
CHARACTER
Records are to be printed in character format. MFJAMS converts EBCDIC data sets to ANSI. Unprintable characters are printed as periods.
HEX
Records are to be printed in hexadecimal format. MFJAMS prints each byte in the record as a two-byte hexadecimal value.
DUMP
Records are to be printed as a storage dump, in both hexadecimal and character format. MFJAMS converts EBCDIC data sets to ANSI. Unprintable characters are printed as periods.

Comments:

  • INFILE and INDATASET are mutually exclusive. You must specify one of them.
  • FROMKEY and SKIP are mutually exclusive. If you specify neither, printing starts at the first physical record.
  • TOKEY and COUNT are mutually exclusive. If you specify neither, printing ends at end of file.
  • CHARACTER, HEX and DUMP are mutually exclusive. DUMP is the default.
  • MFJAMS converts key values to EBCDIC if necessary.
  • MFJAMS pads partial keys with spaces.
Parent topic: Commands


REPRO

The REPRO command copies the contents of one data set to another. The data sets can have either VSAM or sequential organization.

Thus the REPRO command can:

  • Load a sequential data set to a VSAM data set.
  • Load a VSAM data set to a VSAM data set, optionally replacing records that have the same primary key values as the input records.
  • Copy a VSAM data set to a sequential data set.
  • Copy a sequential data set to a sequential data set.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

INFILE(ddname)
Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be used for input.
INDATASET(data-set-name)
Name of the data set that is to be used for input.
OUTFILE(ddname)
Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be used for output.
OUTDATASET(data-set-name)
Name of the data set that is to be used for output.
FROMKEY(key)
For a VSAM KSDS only, the key of the first record to copy. Copying starts at the record with the same primary key, or the record with the nearest higher key if an exact match does not occur. Alternate indices are not used.
TOKEY(key)
For a VSAM KSDS only, the key of the last record to copy. Copying ends at the record with the same primary key, the record with the nearest higher key if an exact match does not occur, or end of file. Alternate indices are not used.
SKIP(number)
The number of records to skip before copying starts.
COUNT(number)
The number of records to copy.
REPLACE|NOREPLACE
For VSAM files only, the record in the input data set replaces/does not replace any record in the output data set that has the same primary key.
REUSE|NOREUSE
For VSAM data sets only. Specifies whether or not the target data can be opened as a reusable data set.
ERRORLIMIT(value)
The number of errors that the command will tolerate.
DBCS
This parameter is parsed, but ignored.
INSERTSHIFT((offset1 offset2) [(offset1 offset2)..])|INSERTALL
This parameter is parsed, but ignored.
MERGECAT|NOMERGECAT
This parameter is parsed, but ignored.
SKIPDBCSCHECK|NODBCSCHECK
This parameter is parsed, but ignored.
TOADDRESS
This parameter is parsed, but ignored.
VOLUMEENTRIES
This parameter is parsed, but ignored.
ENCIPHER
This parameter is parsed, but ignored.
DECIPHER
This parameter is parsed, but ignored.

Comments:

  • The following parameters are not supported: ENTRIES(entry-name [entry-name..])|LEVEL(level), FILE(ddname).
  • INFILE and INDATASET are mutually exclusive. You must specify one of them.
  • OUTFILE and OUTDATASET are mutually exclusive. You must specify one of them.
  • REPLACE and NOREPLACE are mutually exclusive. NOREPLACE is the default.
  • MFJAMS automatically adds alternate key entries to the output data set if they have been previously defined.
  • IDCAMSREPRO pads (with blanks) LSEQ input records to the minimum record length (for primary and alternate keys) for VSAM data sets.
Parent topic: Commands


SET

The SET command alters a condition code set by previous MFJAMS commands in this job step.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

MAXCC=number
Value that is to be set for the maximum condition code that was produced by all previous MFJAMS commands.
LASTCC=number
Value that is to be set for the last condition code that was produced by a MFJAMS command.

Comments:

In both cases, the highest valid value is 16. If you specify a higher value, MFJAMS sets the condition code to 16.

Parent topic: Commands
Related reference
Condition codes


VERIFY

The VERIFY command attempts to open a VSAM data set in order to verify that it can be read and that the index is usable. The data set is assumed to be readable if it can be opened without error or if it is locked to another process.

If the index is found to be unusable, the VERIFY command rebuilds the index by creating a new index file for the primary key and all alternate keys. The data portion of the data set is not changed.

Parameters:

MFJAMS supports the following parameters. They are supported as documented in the IBM documentation unless otherwise stated below:

FILE(ddname)
Name of the DD statement, contained in the JCL for this job step, that provides the name of the data set that is to be verified.
DATASET(data-set-name)
Name of the data set.

Comments:

FILE and DATASET are mutually exclusive. You must specify one of them.

Parent topic: Commands


Condition codes

MFJAMS follows the same condition code principles as the mainframe does:

Condition code | Description
0 | The function was executed as expected. An informational messages might display.
4 | A problem was encountered completing the function, but it was possible to continue. The continuation may cause unexpected results, but no permanent harm will have been done by such continuation. For example, the system was unable to locate an entry in a LISTCAT command. A warning message is displayed.
8 | The requested function was completed, but major specifications were unavoidably bypassed. For example, an entry to be deleted or altered could not be found in the catalog, or a duplicate name was found while an entry was being defined and the define action was terminated.
12 | The requested function could not be performed. This condition code is set as a result of a logical error. A logical error condition exists when inconsistent parameters are specified, when required parameters are missing, or when a value specified for key length, record size, or buffer space is too small or too large.
16 | A severe error occurred that caused the remainder of the command stream to be flushed. For example, a system output data set cannot be opened (a SYSPRINT DD statement was missing, for example).
Parent topic: VSAM Access Method Services (MFJAMS)
Related information
Working with Empty Data Sets
File Structure
JCL Statements
Commands


Dummy Program (MFJBR14)

MFJBR14 can be used, for example, in a job step to delete data sets at the appropriate time. You can also use it to replace a program that does not have a version on the local machine, so that you can still test data set allocation and disposition for the job step.

  • JCL Statements
    This section describes the JCL statements used with the MFJBR14 utility.
Parent topic: Emulations of Mainframe Utilities


JCL Statements

  • EXEC Statement
    In the EXEC statement you need to specify the program name MFJBR14 or its alias IEFBR14.
Parent topic: Dummy Program (MFJBR14)


EXEC Statement

For example:

//STEPEXEC PGM=IEFBR14,......
Parent topic: JCL Statements


Copying and Merging Partitioned Data Sets (MFJCOPY)

  • JCL Statements
    This section describes the JCL statements used with the MFJCOPY utility.
  • Control Statements
Parent topic: Emulations of Mainframe Utilities


JCL Statements

  • EXEC Statement
    In the EXEC statement you need to specify the program name MFJCOPY or its alias IEBCOPY.
  • DD Statements
Parent topic: Copying and Merging Partitioned Data Sets (MFJCOPY)


EXEC Statement

For example:

//STEPEXEC PGM=IEBCOPY, ...
Parent topic: JCL Statements


DD Statements

The following DD statements are required for all uses of MFJCOPY:

SYSPRINT
For the sequential data set used for listing control statements and messages.
SYSUT1 or anyname1
For the input partitioned data set.
SYSUT2 or anyname2
For the output partitioned data set.

The following DD statement is optional:

SYSIN
For the control data set.

The following DD statements, which are used by the mainframe utility, are ignored by MFJCOPY:

SYSUT3
For a spill data set when there is no further space in virtual memory for the input data set.
SYSUT4
For a spill data set when there is no space in virtual memory for the output data set.
Parent topic: JCL Statements


Control Statements

The following control statements are parsed but not processed:

  • ALTERMOD
  • COMPRESS
  • COPYGRP
  • COPYMOD

Additional differences between behavior on the mainframe and in MSS are as follows:

  • MSS does not differentiate between PDS and PDSE organizations, so operations specific to PDSEs are not processed.
  • On the mainframe, specifying the same data set for INDD and OUTDD results in the data set being compressed. On MSS, such compression is not available, so no processing takes place.
  • On the mainframe, you can unload a PDS to an unload data set (by specifying a PDS as the INDD and a sequential data set as the OUTDD with no SYSIN) and reload a member from an unload data set into a PDS (by specifying a sequential data set as the INDD and a PDS as the OUTDD). Neither of these operations are supported in MSS.
  • Operations on load modules are not processed in MSS.
Parent topic: Copying and Merging Partitioned Data Sets (MFJCOPY)


Generating Test Data (MFJDG)

  • JCL Statements
    This section describes the JCL statements used with the MFJDG utility.
  • Control statements
Parent topic: Emulations of Mainframe Utilities


JCL Statements

  • EXEC Statement
  • DD Statements
Parent topic: Generating Test Data (MFJDG)


EXEC Statement

In the EXEC statement, you need to specify the program-name MFJDG or IEBDG. For example:

//STEPEXEC PGM=IEBDG, ...

Any PARM on the exec statement is ignored.

Parent topic: JCL Statements


DD Statements

The following DD statements are required:

anyname1
For the optional input data set.
anyname2
For the output data set.
SYSIN
For the control data set.
SYSPRINT
For the output listing data set.
Parent topic: JCL Statements


Control statements

The EXIT sub-operand of the CREATE statement is parsed but not processed.

Parent topic: Generating Test Data (MFJDG)


Printing or Punching Data Sets (MFJPTPCH)

The MFJPTPCH program is a partial emulation of the IBM IEBPTPCH (Print-Punch) mainframe utility for printing or punching datasets.

Considerations

This program supports all the major functions and options with the exception of the EXITS and LABELS statements, the options CDSEQ, CDINCR, DBCS, and the FIELD clause conversion options CV and VC, which are parsed but not processed. The concatenation of datasets on the SYSUT1 DD statement is not supported.

To print or punch the equivalent of directory records, you need to specify (or allow to default) TYPORG=PS for a PDS. It is not necessary to use RECFM=U, BLKSIZE=256 to override the DCB. The four bytes following each member name contain spaces.

For more details about the parameters associated with the supported commands and options, see the IBM z/OS DFSMSdfp Utilities manual.

  • JCL Statements
    This section describes the JCL statements used with the MFJPTPCH utility.
  • Control Statements
Parent topic: Emulations of Mainframe Utilities


JCL Statements

This section describes the JCL statements used with the MFJPTPCH utility.
  • EXEC Statement
  • DD Statements
Parent topic: Printing or Punching Data Sets (MFJPTPCH)


EXEC Statement

You must specify either the program name MFJPTPCH or its alias IEBPTPCH in the EXEC statement.

For example:

//STEP01 EXEC PGM=IEBPTPCH
Parent topic: JCL Statements


DD Statements

The following DD statements are required:

SYSIN
For the command input data set. The record length must be 80 characters.
SYSUT1
For the input data set. Concatenation of data sets is not supported.
SYSUT2
For the output data set. The maximum record length is 145.
SYSPRINT
For the output listing data set. The record length must be 121.
Parent topic: JCL Statements


Control Statements

The following MFJPTPCH processes control statements behave differently to how they behave with IEBPTPCH:

  • The EXITS and LABELS statements are parsed but not processed.
  • For the PRINT or PUNCH statements, the DBCS operand is parsed but not processed.
  • For the MEMBER statement, any specified aliases are parsed but not processed.
  • For the RECORD statement, operands relating to double-byte characters sets (such as the conversion types CV and VC) are parsed but not processed.
Parent topic: Printing or Punching Data Sets (MFJPTPCH)


Copying Sequential Data Sets (MFJGENER and ICEGENER)

MFJGENER emulates the basic copy operations of the IEBGENER mainframe utility for sequential data sets (that is, PS or PSU data sets, or members of PO or POU data sets.)

Note: ICEGENER behaves like IEBGENER but it also accommodates VSAM files.
  • JCL Statements
    This section describes the JCL statements used with the MFJGENER utility.
  • Control Statements
Parent topic: Emulations of Mainframe Utilities


JCL Statements

  • EXEC Statement
  • DD Statements
Parent topic: Copying Sequential Data Sets (MFJGENER and ICEGENER)


EXEC Statement

In the EXEC statement you need to specify the program name MFJGENER or its alias IEBGENER. For example:

//STEPEXEC PGM=IEBGENER,......
Parent topic: JCL Statements


DD Statements

The following DD statements are required:

SYSIN
For the command input data set.
SYSUT1
For the input data sets. You can concatenate up to 16 data sets for SYSUT1.
SYSUT2
For the output data set.
SYSPRINT
For the output listing data set.
Parent topic: JCL Statements


Control Statements

The following list describes how MFJGENER processes control statements differently to IEBGENER:

  • The EXITS and LABELS statements are parsed but not processed.
  • For the GENERATE statement, the DBCS operand is parsed but not processed.
  • For the MEMBER statement, any specified aliases are parsed but not processed.
  • For the RECORD statement:
    • operands relating to double-byte characters sets (such as IDENTG and the conversion types CG and CV) are parsed but not processed.
    • conversion type HE is not supported.
    • the LABELS operand is parsed but not processed.
Parent topic: Copying Sequential Data Sets (MFJGENER and ICEGENER)


Comparing Data Sets (MFJMATCH - IEBCOMPR)

This topic describes how to use MFJMATCH to emulate the IEBCOMPR mainframe utility to compare two sequential or partitioned data sets. MFJMATCH works in two modes, depending on the EXEC statement you use to invoke it:

EXEC Statement | Description
PGM=IEBCOMPR | MFJMATCH emulates the IEBCOMPR mainframe utility.
PGM=MFJMATCH | MFJMATCH performs a data set comparison but does not emulate the IEBCOMPR mainframe utility.
Notes:
  • Both utilities are limited to a 9-digit record count as listed for their output.
  • For information on using the non-IEBCOMPR version of MFJMATCH, see the section Comparing Data Sets (MFJMATCH).
  • JCL Statements
    This section describes the JCL statements used with the MFJMATCH utility.
  • Control Statements
Parent topic: Emulations of Mainframe Utilities
Related information
Comparing Data Sets (MFJMATCH)


JCL Statements

  • EXEC Statement
  • DD Statements
Parent topic: Comparing Data Sets (MFJMATCH - IEBCOMPR)


EXEC Statement

In the EXEC statement you need to specify MFJMATCH's alias, IEBCOMPR. For example:

//STEPEXEC PGM=IEBCOMPR, ...
Note: Specifying MFJMATCH instead of IEBCOMPR in the EXEC statement causes MFJMATCH to behave as described in the section Comparing Data Sets (MFJMATCH).
Parent topic: JCL Statements
Related information
Comparing Data Sets (MFJMATCH)


DD Statements

The following DD statements are required for all uses of MFJMATCH:

SYSPRINT
For the sequential data set used for listing control statements and messages.
SYSUT1
For an input sequential or partitioned data set to be compared.
SYSUT2
For the input sequential or partitioned data set to be compared with SYSUT1.

The following DD statement is optional:

SYSIN
For the control data set.
Parent topic: JCL Statements


Control Statements

The COMPARE control statement is supported as follows:

COMPARE TYPORG=PS|PO

The following control statements are parsed but not processed:

EXITS
LABELS
Parent topic: Comparing Data Sets (MFJMATCH - IEBCOMPR)


Sort/Merge Operations (MFJSORT)

Note: MFJSORT and MFSORT are updated with new features on a regular basis but they do not offer a complete emulation of third-party sort utilities. If there are particular features that you need to use, please contact SupportLine to establish if they are available in MFJSORT or MFSORT.

MFJSORT provides the following sort/merge operations for sequential data sets:

  • Sorting data sets by ascending or descending keys
  • Merging data sets by ascending or descending keys
  • Copying data sets
  • Selecting the records to be processed
  • Rearranging the fields in the records
  • Correctly processing two-digit year fields
  • Transforming two-digit year fields to four-digit fields
  • Summing numeric fields in records with duplicate keys
  • Creating multiple output data sets
  • Performing limited arithmetic operations on reformatted outputs; see note.
  • Using an alternate collating sequence
  • Executing E15, E35 exit programs.
Note: For arithmetic operations:
  • The result of an arithmetic operation is an 18 digit ZD value, which can be converted to a different numeric format, or edited using pre-defined edit masks (M0-M26) or user-defined edit masks.
  • Complex arithmetic operations using parentheses are not supported.
  • Arithmetic operations performed on other arithmetic operations are not supported.
  • Arithmetic operations performed with decimal values like +20, +100, etc... (for example, OUTREC FIELDS=(1,2,BI,MUL,+20)) are not supported.
  • When PARM=SIGN-EBCDIC is set, numeric DISPLAY items with included signs are interpreted according to the EBCDIC convention. SIGN-EBCDIC is not required when MF_CHARSET is set to EBCDIC; 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.
  • JCL Statements
    This section describes the JCL statements used with the MFJSORT utility.
Parent topic: Emulations of Mainframe Utilities
Related concepts
PARM


JCL Statements

  • EXEC Statement
  • DD Statements
  • Program Control Statements
  • Exits
    MFJSORT, like its mainframe counterpart, invokes user exit programs for the E15 read exit and the E35 write exit.
  • SYNCSORT Emulation
Parent topic: Sort/Merge Operations (MFJSORT)


EXEC Statement

In the EXEC statement you need to specify the program named MFJSORT or its alias DFSORT or SORT. For example:

//STEPEXEC PGM=DFSORT,......
Parent topic: JCL Statements


DD Statements

The following DD statements are required for all uses of MFJSORT:

SYSIN
For the data set that contains the program control statements. It can be an in-stream data set.
SYSPRINT
For the output listing data set. It must have an LRECL value of at least 132.
SORTIN
For the input data sets. You can concatenate up to 16 data sets for SORTIN. It is not required if you use SORTIN nn
SORTOUT
For the output data set. It is not required if you use SORTOF nn.

The following DD statements are optional:

SORTINnn
For multiple input data sets. nn begins with 01 and increases by 1 up to a maximum of 16. SORTIN nn and SORTIN are mutually exclusive.
SORTOF nn
For multiple output data sets. nn begins with 01 and increases by 1 up to a maximum of 16. SORTOF nn is used by the OUTFIL statement.
Parent topic: JCL Statements


Program Control Statements

The program control statements supported by MFJSORT are listed below. The rules for coding the statements are identical to the mainframe utility.

Note: MFJSORT emulates most major functions of IBM's DFSORT product; see DFSORT and ICETOOL Emulation for more information.

Program Control Statements

ALTSEQ
Specifies an alternate collating sequence for AQ control fields.
END
Indicates the end of the program control statements. If omitted, MFJSORT reads to end of file.
INCLUDE
Includes records from the input data set based on comparison testing of one or more fields in the input record. Supports substring comparison and bit logic (bit operator and bit comparison) tests. You can specify up to 16 conditional expressions.
INREC
Rearranges input records before sorting or merging. Note that INREC may change the location of the control fields used by SORT, MERGE, OUTFIL, OUTREC and SUM statements.
MERGE
Defines a merge operation. You can include a COPY request in the MERGE statement. You can select portions of the input data sets for merging. You can define up to 32 control fields, but the total length of the control fields must not exceed 1,024 bytes. You can request ascending or descending sequences for the following control field types:
AQ
Alternate collating sequence.
BI
Binary.
CH
Character.
CLO
Signed numeric with leading overpunched sign.
CTO
Signed numeric with trailing overpunched sign.
CSF
Signed numeric with optional leading floating sign.
CSL
Signed numeric with leading separate sign.
CST
Signed numeric with trailing separate sign.
FI
Fixed integer.
FL
Floating point. Only 4-byte and 8-byte forms are supported. (COMP-1 and COMP-2).
FS
Signed numeric with optional leading floating sign.
LS
Signed numeric with leading separate sign.
OL
Signed numeric with leading overpunched sign.
OT
Signed numeric with trailing overpunched sign.
PD
Packed decimal.
PD0
Packed decimal, with sign and first digit ignored.
TS
Signed numeric with trailing separate sign.
Y2B
Two-digit, one-byte binary year data.
Y2C
Two-digit, two-byte character or zoned decimal year data.
Y2D
Two-digit, one-byte decimal year data.
Y2P
Two-digit, two-byte packed decimal year data.
Y2S
Two-digit, two-byte character or zoned decimal year data, with special indicators.
Y2Z
Two-digit, two-byte character or zoned decimal year data.
ZD
Zoned decimal.
MODS
Specifies the names of the E15 and E35 exit programs. Other exits are not supported.
OMIT
Excludes records from the input data set based on comparison testing of one or more fields in the input record. Supports substring comparison and bit logic (bit operator and bit comparison) tests. You can specify up to 16 conditional expressions.
OUTFIL
Writes multiple output files. OUTFIL allows for extensions.
  • Use the INCLUDE, OMIT and SAVE operands to select the records to be included in each output data set. The INCLUDE and OMIT operands provide all of the capabilities of the INCLUDE and OMIT statements, while SAVE can be used to select the records that are not selected for any other subset.
  • The OUTREC operand provides editing and control of the way numeric fields are presented with respect to length, leading or suppressed zeros, symbols, and so on. Twenty six pre-defined editing masks (M0 to M25) are available, and user-defined masks can be created using, for example, the EDIT, SIGNS and LENGTH options. Use the CHANGE option to select a character or hexadecimal string for output from a lookup table, based on a character, hexadecimal or bit string as input.
  • Use the STARTREC and ENDREC operands to select a range of records to be included in each output data set.
  • Use the SPLIT operand to distribute the records evenly among the output data sets.
  • Use the operands LINES, HEADER1, TRAILER1, HEADER2, TRAILER2, SECTIONS and NODETAIL, together with OUTREC, to create complex reports including, for example, totals, maximums, minimums and averages for numeric input fields.
OUTREC
Rearranges output records after sorting or merging. It can also insert literal variables into the output record. Supports reformatting of records as well as the creation of formatted reports. Also supports arithmetic operations on input fields, which can be further reformatted if needed.

Arithmetic operations can be done between two numeric fields using the operators ADD (addition), SUB (subtraction), MUL (multiplication), DIV (division). For example:

OUTREC FIELDS=(1,8,ZD,ADD,1,7,ZD,1X,2,5,PD,SUB,5,2,PD)

See note on Sort/Merge Operations (MFJSORT) for restrictions.

RECORD
Specifies record length information. Only the first value of this statement, which specifies the maximum record length, is used; all other values are ignored. The logical record length of the input data set overrides any value specified by the RECORD statement.
SORT
Defines a sort operation. You can include a COPY request in the SORT statement. You can define up to 32 control fields, but the total length of the control fields must not exceed 1,024 bytes. You can request ascending or descending sequences for the same control field types as described for the MERGE statement.
SUM
Produces only one output record for records with duplicate sort fields. Optionally, numeric fields in the duplicate records can be summed in the output record. The sum operation can be done for the following control field types:
AQ
Alternate collating sequence.
BI
Binary.
FI
Fixed integer.
FL
Floating point. Only 4-byte and 8-byte forms are supported. (COMP-1 and COMP-2).
FS
Signed numeric with optional leading floating sign.
PD
Packed decimal.
ZD
Zoned decimal.

OVFLO Parameter

The OVFLO parameter gives you control over the the action (continue or terminate), type of message (informational or error), and return code (0 or 16) that can be set during summary overflow. For example:
OPTION OVFLO=-----RC0-----
                      -----RC16-----
  • RC0 - When summary fields overflow: issues overflow message, sets the return code to 0, and continues processing. RC0 is the default value for the OVFLO parameter.
  • RC16 - When summary fields overflow: issues overflow message, terminates processing, and gives a return code of 16.
Parent topic: JCL Statements
Related reference
DFSORT and ICETOOL Emulation
Sort/Merge Operations (MFJSORT)


Exits

The exit programs should be written in COBOL and compiled by the Micro Focus syntax checker. They can be executed normally or debugged like any other COBOL program. Please refer to the mainframe documentation for instructions on writing and testing exit programs.

Linkage Area

MFJSORT provides a standard linkage area to the E15 and E35 exit program. It is compatible with the mainframe utility and should be defined as follows:
COBOL Statements Value
RECORD-FLAGS PIC 9(8) COMP.
 0 indicates the first record passed. 4 indicates subsequent records passed. 8 indicates the last record passed.
ENTRY-BUFFER PIC X(n).
 Contents of the input record. Do not change this area.
EXIT-BUFFER PIC X(n).
 Contents of the new or altered record provided by the exit.
UNUSED-ENTRY PIC 9(8) COMP.
 Not used
UNUSED-ENTRY PIC 9(8) COMP.
 Not used
ENTRY-RECORD-LENGTH PIC 9(8) COMP.
 Length of the input record.
EXIT-RECORD-LENGTH PIC 9(8) COMP.
 Length of the new or altered record provided by the exit.
UNUSED-ENTRY PIC 9(8) COMP.
 Not used
EXIT-AREA-LENGTH PIC 9(4) COMP.
 Length of the exit area scratchpad. Do not change this field.
EXIT-AREA PIC X(n).
 Exit area scratchpad used by the exit to maintain variables between calls to the exit program.

Return Codes

MFJSORT recognizes the same return codes from exit programs as the mainframe utility, as listed in the following table:
Return Code | Meaning
0 | No action required.
4 | Delete the current record. For E15, the record is not sorted. For E35, the record is not written to the output data set.
8 | Do not call this exit again; exit processing is no longer required.
12 | Insert the current record. For E15, the record is inserted for sorting. For E35, the record is written to the output data set.
16 | Terminate MFJSORT. The job step is terminated with the condition code set to 16.
20 | Alter the current record. For E15, the altered record is passed to the sort. For E35, the altered record is written to the output data set.
Parent topic: JCL Statements


SYNCSORT Emulation

MSS also provides emulation of SYNCSORT behavior. The behavior for SYNCSORT emulation is very similar to that of the DFSORT emulation. Refer to the SYNCSORT Emulation section for full details of the supported behavior.

To specify that you want to use SYNCSORT, set the environment variable MFJSENGINE=SYNCSORT in Configuration Information on the Server > Properties > General page for the enterprise server you are using.

Parent topic: JCL Statements
Related concepts
Supported SYNCSORT Syntax


Creating or Modifying Data Sets (MFJUPDTE)

  • JCL Statements
    This section describes the JCL statements used with the MFJUPDTE utility.
  • Control Statements
Parent topic: Emulations of Mainframe Utilities


JCL Statements

  • EXEC Statement
  • DD Statements
Parent topic: Creating or Modifying Data Sets (MFJUPDTE)


EXEC Statement

In the EXEC statement, you need to specify the program name MFJUPDTE or its alias IEBUPDTE. For example:

//STEPEXEC PGM=IEBUPDTE, ...
Parent topic: JCL Statements


DD Statements

The following DD statements are required:

SYSUT1
For the input data set.
SYSUT2
For the output data set.
SYSIN
For the control data set.
SYSPRINT
For the output listing data set.
Parent topic: JCL Statements


Control Statements

The following control statements are parsed but not processed:

  • ALIAS
  • LABEL

The following sub-operands for the function statement (ADD, CHANGE, REPL or REPRO) are parsed but not processed:

  • INHDR
  • INTLR
  • LEVEL
  • OUTDR
  • OUTTLR
  • SOURCE
  • SSI
  • TOTAL
Parent topic: Creating or Modifying Data Sets (MFJUPDTE)


TSO Support in Enterprise Server

Enterprise Server supports the use of TSO commands and REXX execs.

TSO commands can be run in a TSO batch (or background) session, using the IDAEFT01 (IKJEFF01) utility. TSO interactive processing is not supported in Enterprise Server.

Enterprise Server does not support CLIST processing.

  • TSO Commands and Micro Focus Extensions
    You can enter TSO commands and Micro Focus extensions individually within a REXX exec.
Parent topic: Emulations of Mainframe Utilities
Parent topic: Reference for MSS Deployment


TSO Commands and Micro Focus Extensions

The TSO commands and Micro Focus extensions supported by Enterprise Server are listed below. Please refer to the IBM TSO documentation for any additional information about TSO commands.

Note: In addition to the TSO commands referenced below, the following IDCAMS commands may also be used in a batch TSO job. For information about the individual commands, please refer to the IBM IDCAMS documentation.
  • ALTER
  • DEFINE CLUSTER, DATA, INDEX, ALTERNATEINDEX, GDG, PATH, NONVSAM, CATALOG, ALIAS, USERCATALOG, PAGESPACE

    ALIAS, USERCATALOG and PAGESPACE will be parsed but not actioned.

  • REPRO
  • PRINT
  • VERIFY
  • BLDINDEX

    BLDINDEX is not required for indexed files with this Micro Focus file system and is provided for compatibility with the mainframe.

  • ALLOCATE
    Allocates an MVS data set to the current user and defines the data set's DD name.
  • ATTRIB
    Allows DCB parameters to be dynamically defined and named for use in subsequent ALLOCATE commands.
  • CALL
    Invokes a program.
  • DELETE
    Deletes an MVS data set and its related PC file.
  • DSN
    Invokes the DSN command processor used to run DB2 programs.
  • EXEC
    Executes a TSO command, CLIST or REXX exec.
  • FREE
    Frees allocation of a data set.
  • LISTALC
    Displays the list of currently allocated DD names.
  • LISTCAT
    Lists the entries in the catalog with the high-level data set qualifier equal to the user ID defined to Enterprise Server.
  • LOGOFF
    Terminates the current TSO session.
  • PROFILE
    Allows you to specify different PREFIX and PROMPT settings.
  • RELATE
    A Micro Focus extension that relates an MVS data set name in the catalog to a PC file name.
  • REXX
    Executes a file containing a set of JCL statements.
  • SUBMIT
    Executes a file containing a set of JCL statements.
  • TIME
    Displays the current time and date and the CPU seconds used.
Parent topic: TSO Support in Enterprise Server


ALLOCATE

Allocates an MVS data set to the current user and defines the data set's DD name.

The following example allocates the existing data set TESTDATA.SORTED.DATA, with the DD name SYSUT1.

ALLOCATE FILE(SYSUT1) DATASET(TESTDATA.SORTED.DATA) OLD

Operands Support

The following operands are supported for ALLOCATE:

BLKSIZE | DUMMY | SHR
BLOCK | FILE | SPACE
CYLINDERS | LIKE | SYSOUT
DATACLAS | LRECL | TRACKS
DATASET | MOD | TRTCH
DDNAME | NEW | USING
DIR | OLD | WRITER
DSNAME | RECFM |
DSORG | REUSE |

The following are parsed and ignored:

ACCODE | DEN | NOBURST
ALTFILE | DEST | OPTCD
ATTRLIST | EROPT | OUTPUT
BFALN | EXPDT | PARALLEL
BFTEK | FCB | POSITION
BUFL | FLASH | RELEASE
BUFNO | FORMS | RETPD
BUFOFF | INPUT | ROUND
BURST | KEEP | UCS
CATALOG | KEYLEN | UNCATALOG
CHARS | LABEL | UNIT
COPIES | LIMCT | VOLUME
DELETE | NCP | VSEQ
Parent topic: TSO Commands and Micro Focus Extensions


ATTRIB

Allows DCB parameters to be dynamically defined and named for use in subsequent ALLOCATE commands.

The following example sets up an attribute called DATA1 that can be used in conjunction with an ALLOCATE command to provide DCB information for a DD name.

ATTRIB DATA1 BLKSIZE(32720) LRECL(80) DSORG(PS) RECFM(FB)

Operands Support

The following operands are supported for ATTRIB:

BLKSIZE | LRECL | TRTCH
DSORG | RECFM |

These operands produce identical output for SQL and VSAM datasets.

The following are parsed and ignored:

BFALN | BUFOFF | KEYLEN
BFTEK | DEN | NCP
BUFL | ERROPT | OPTCD
BUFNO | EXPDT | RETPD
Parent topic: TSO Commands and Micro Focus Extensions


CALL

Invokes a program.

The following example invokes program PROG1.

CALL PROG1

Operands Support

The following operands are supported for CALL:

ASIS | NOENVB | PASSENVB
CAPS | PARM | PROGRAM
Parent topic: TSO Commands and Micro Focus Extensions


DELETE

Deletes an MVS data set and its related PC file.

The following example deletes the data set TESTDATA.UNSORTED.DATA.

DELETE 'TESTDATA.UNSORTED.DATA'

Operands Support

The following operands are supported for DELETE:

DATASET | DSNAME
DDNAME | FILE

The following are parsed and ignored:

ALIAS | NONVSAM | PRG
CATALOG | NOPURGE | PURGE
CLUSTER | NOSCRATCH | SCRATCH
ERASE | NPRG | SPACE
GDG | NSCR | SPC
GENERATIONDATAGROUP | NVSAM | UCAT
NERASE | PAGESPACE | USERCATALOG
NOERASE | PGSPC |
Parent topic: TSO Commands and Micro Focus Extensions


DSN

Invokes the DSN command processor used to run DB2 programs.
In Enterprise Server, the subcommands ABEND, BIND, DCLGEN, FREE, REBIND, SPUFI, SYSTEM, RETRY, TEST and PLAN are passed to the database sub system which may or may not support them.

The following example invokes the DSN subcommand processor to execute the RUN subcommand, which invokes the program PROG1 with the parameter string "HELLO". The END subcommand terminates the DSN subcommand processor.

DSN
RUN PROGRAM(PROG1) PLAN(PLANX) PARMS('HELLO')
END

Refer to the IBM DB2 for z/OS documentation for any additional information about the DSN command.

Operands Support

The following operands are supported for DSN:

RUN SYSTEM

The following are parsed and ignored:

RETRY TEST

The following are passed to the database sub system which may or may not support them:

ABEND | DCLGEN | FREE
BIND | END | REBIND
DATA | ENDDATA | SPUFI
Parent topic: TSO Commands and Micro Focus Extensions


EXEC

Executes a TSO command, CLIST or REXX exec.

The following example executes the member ABCD from the partitioned data set MYPDS.CLIST.

EXEC 'MYPDS.CLIST(ABCD)'
Parent topic: TSO Commands and Micro Focus Extensions


FREE

Frees allocation of a data set.
The following example frees the allocation for the data set with DD name SYSUT1.
FREE FILE(SYSUT1)

Operands Support

The following operands are supported for FREE:

ALL | DDNAME | DSNAME
DATASET | DELETE | FILE
Parent topic: TSO Commands and Micro Focus Extensions


LISTALC

Displays the list of currently allocated DD names.

Operands Support

The following operands are supported for LISTALC:

HISTORY | STATUS
MEMBERS | SYSNAMES

Specifying MEMBERS for a PDS also lists the PDS member names.

Parent topic: TSO Commands and Micro Focus Extensions


LISTCAT

Lists the entries in the catalog with the high-level data set qualifier equal to the user ID defined to Enterprise Server.

Operands Support

If you invoke this command with the Micro Focus extension /F, it displays additional information.

The following operands are supported for LISTCAT:

ALL | /F | LVL
ENTRIES | LEVEL |

The following are parsed and ignored:

DATA | OFILE | USERCATALOG
INDEX | OUTFILE |
NONVSAM | SPACE |
Parent topic: TSO Commands and Micro Focus Extensions


LOGOFF

Terminates the current TSO session.
Once LOGOFF executes, remaining commands in the input stream are ignored.
Parent topic: TSO Commands and Micro Focus Extensions


PROFILE

Allows you to specify different PREFIX and PROMPT settings.

The following example adds a data set prefix of TVDF to any data set name not enclosed in quotes, and turns off prompting for REXX execs during the active TSO session.

PROFILE PREFIX(TVDF) NOPROMPT
Parent topic: TSO Commands and Micro Focus Extensions


RELATE

RELATE can be used in conjunction with an ALLOCATE command to set up tests in a TSO session.

The following example relates the MVS data set TESTDATA.SORTED.DATA to the PC file C:\MYFILE.DAT.

RELATE TESTDATA.SORTED.DATA C:\MYFILE.DAT

Operands Support

The following operands are supported for RELATE:

dataset name pc file name
Parent topic: TSO Commands and Micro Focus Extensions


REXX

Executes a file containing a set of JCL statements.

The following example executes the REXX statements contained in the PDS member IOCBL02.

REXX 'TEST.SYSEXEC(SBCS4315)'

Operands Support

The following operands are supported for REXX:

rexx name
Parent topic: TSO Commands and Micro Focus Extensions


SUBMIT

Executes a file containing a set of JCL statements.

The following example executes the JCL statements contained in IOCBL02.

SUBMIT 'TVDF.WORK.CNTL(IOCBL02)'

Operands Support

The following operands are supported for SUBMIT:

dataset name
Enter an example to illustrate your reference here (optional).
Parent topic: TSO Commands and Micro Focus Extensions


TIME

Displays the current time and date and the CPU seconds used.
The CPU seconds returned using the TIME command represent cumulative CPU time from LOGON. Current time and date are local.
Parent topic: TSO Commands and Micro Focus Extensions


Micro Focus Utilities

  • Comparing Data Sets (MFJMATCH)
    The MFJMATCH utility compares two MVS data sets. It accepts any record format, record length or data set organization supported by your COBOL development system.
  • Public SPOOL APIs
    Describes the APIs that you can use to access information in the JES spool files and JES spool control files.
  • Public Catalog API (MVSCATPB)
    Describes the Public Catalog API that you can use to access and update JES Catalog information.
Parent topic: Utility Programs


Comparing Data Sets (MFJMATCH)

If the data sets match, MFJMATCH ends with a return code of 0. If the two data sets do not match, when the MFJMATCH utility finds the first mismatch it writes the two records that differ to a third data set (with asterisks under the columns that differ), then ends with a return code of 12. Records following the first mismatch are not compared.

Note: You can also use the MFJMATCH utility to emulate the IEBCOMPR mainframe utility. For information on doing this, see the section Comparing Data Sets (MFJMATCH - IEBCOMPR).

If the data sets being compared are EBCDIC, the MFJMATCH utility also writes the hexadecimal representation.

  • JCL Statements
    This section describes the JCL statements used with the MFJMATCH utility.
Parent topic: Micro Focus Utilities
Related information
Comparing Data Sets (MFJMATCH - IEBCOMPR)


JCL Statements

  • EXEC Statement
  • DD Statements
  • Program Control Statements
    The program control statements define search criteria that limit matching to a particular range of records and to portions of the record. This topic lists the program control statements supported by MFJMATCH.
Parent topic: Comparing Data Sets (MFJMATCH)


EXEC Statement

In the EXEC statement you need to specify the program name MFJMATCH. For example:

//STEPEXEC PGM=MFJMATCH
Parent topic: JCL Statements


DD Statements

The following DD statements are required:

SYSUT1
For the first of the datasets to be compared.
SYSUT2
For the second of the datasets to be compared.
SYSIN
For the data set that contains the program control statements. It can be an in-stream data set.
SYSUT3
For the file to which results are written. It should also have the same DCB parameters as SYSUT1.
Parent topic: JCL Statements


Program Control Statements

KEY = ( start , length )
Defines a key field for use by FROMKEY and TOKEY program control statements. This statement can only occur once. The parameters are:
start
The position in the record at which the key starts.
length
The length of the key.

For VSAM keyed files, the KEY defaults to the actual key, although, as the files are processed sequentially, any field can be defined as the key for the purpose of specifying a range for record matching.

INCLUDE

Compare records only in the ranges defined by FROMKEYTOKEY or FROMRECCOUNT.

SKIP and INCLUDE are mutually exclusive.

IGNORE

Ignore records only in the ranges defined by FROMKEYTOKEY or FROMRECCOUNT.

SKIP and INCLUDE are mutually exclusive.

FROMKEY = ' value1 ' TOKEY = ' value1 '

Defines a range of records. value1 specifies the first record in the range, while value2 specifies the last record in the range. Hexadecimal values can be specified as x ' hhhhhh ' , where hhhhhh is a hexadecimal number.

FROMREC = recnum COUNT = count

Defines a range of record numbers, from record number x for the next y records.

FD = start , length

Defines a field to be ignored when comparing records. Used with INCLUDE only.

Example of Program Control Statements

In the following example:
  • The key field is defined as being the first ten bytes of the record
  • Records in the ranges AAAAAAAAAA to BBBBBBBBBB and WWWWWWWWW to ZZZZZZZZZZ are compared
  • Positions 11 to 15 and 21 to 25 are ignored in the second range
//SYSIN DD *
 KEY=(1,10)
 INCLUDE FROMKEY='AAAAAAAAAA' TOKEY='BBBBBBBBBB'
 INCLUDE FROMKEY='WWWWWWWWWW' TOKEY='YYYYYYYYYY'
 FD=(11,5)
 FD=(21,5)
Parent topic: JCL Statements


Public SPOOL APIs

There are two APIs that you can use to access the spool control files:

  • MVSSPLPB API
    This program enables the retrieval of all data from the spool control files SPLJOB, SPLMSG, SPLDSN, SPLOUT and SPLSUB. This is the recommended API to be used for all new spool enquiries.
  • MVSCASPB API
    This program is delivered for compatibility with earlier releases of Enterprise Developer, enabling you to access a subset of job status information held in the spool control files SPLJOB, SPLMSG, and SPLDSN.
Parent topic: Micro Focus Utilities


MVSSPLPB API

This section describes the recommended public SPOOL API - MVSSPLPB. Calling this API enables you to access all job information held in the JES spool control files (SPLJOB.dat, SPLMSG.dat, SPLDSN.dat, SPLOUT.dat, and SPLSUB.dat).

When you submit a batch job to Enterprise Server, job information is written to the spool control files, which are continually updated throughout the life of the job. This creates a chronological record of the stages of execution from the job submission stage through to job completion.

While the ESMAC spool queues interface enables you to view the status of current jobs in Enterprise Server, it does not provide full access to the information in the spool files. The MVSSPLPB API provides access to all fields in these files. When you call the API from a COBOL or PL/I program, you can retrieve all or some of this data in any supported sequence, using the functions and index options defined in the interface data structure.

  • Spool Data Files
    An overview of the files that make up the spool management facility.
  • Program Requirements
    There are a number of requirements that must be satisfied before you can call the MVSSPLPB API from your COBOL or PL/I programs.
  • Calling MVSSPLPB
    Call MVSSPLPB using the following syntax to provide access to information in the spool control files.
  • Functions
    Describes the functions you can use with the MVSSPLPB API.
  • Keys
    Describes the keys you can use with the MVSSPLPB API.
  • Sample Programs
    Enterprise Developer is shipped with a COBOL and a PL/I sample program that demonstrates how to call the MVSSPLPB API.
  • Debug or Run the Program
    Describes the steps required to debug or run a program that calls the MVSSPLPB API.
  • Return Codes
    Describes the return codes produced by the MVSSPLPB API.
  • Reason Codes
    Describes the reason codes produced by the MVSSPLPB API.
Parent topic: Public SPOOL APIs
Related information
MVSCASPB API


Spool Data Files

The following diagram shows the linked structure of the data files that form the spool management facility:

Key fields are listed in the first box associated with each file, and data fields are listed in the second box. Not all data fields are listed here - refer to the interface data structure for a full list of available fields.

Data file | Contains
SPLJOB | Single record per Job, keyed on Job number, plus additional indices for searching
SPLMSG | Single record per Job Message, keyed on Job number and Message Sequence Number
SPLDSN | Single record per Job SYSOUT file and OUTPUT reference number, keyed on Job number, SYSOUT DD number, and Output record Sequence number, plus additional indices for searching. (The SYSOUT DD number equates to the Dnnnnn number from the spool dataset DSN.)
SPLOUT | Single record per Job OUTPUT statement, keyed on Job number and OUTPUT reference number
SPLSUB | Single record per Job SUBSYS clause, keyed on Job number and SYSOUT DD number. (The SYSOUT DD number equates to the Dnnnnn number from the spool dataset DSN.)
Parent topic: MVSSPLPB API
Related information
Program Requirements
Calling MVSSPLPB
Functions
Keys
Sample Programs
Debug or Run the Program
Return Codes
Reason Codes


Program Requirements

Programs that access MVSSPLPB must:

  • Include the mfpubspl copybook in Working-Storage (for COBOL programs), or the mfpubspl include member (for PL/I programs); see below for more information.
  • Set the interface function code to an appropriate value.
  • Populate the key field(s) and the index-id (for SPLJOB and SPLDSN).
  • Call the mvssplpb utility passing the mfpubspl level one data name.

mfpubspl.cpy (COBOL users)

The mfpubspl.cpy file is located by default in the cpylib sub-directory of your installation directory on Windows systems, or the $COBDIR/cpylib directory on UNIX systems. We recommend that you open it in a file editor to become familiar with its contents.

mfpubspl.cpy contains all of the Working-Storage fields you need to access the MVSSPLPB API from a COBOL program, including function, key, and reason code fields. Add mfpubspl.cpy to your Enterprise Developer project, and include it in your COBOL program to enable the passing of information to and from the MVSSPLPB API.

When you include mfpubspl.cpy in your program:

  • Include it in Working-Storage as a child of an 01-level field.
  • Use copy...replacing syntax to replace () with a qualifier. For example:
    01 PUBSPL-AREA.
   copy 'mfpubspl.cpy' replacing ==()== by ==WS-API==.

mfpubspl.inc (PL/I users)

The mfpubspl.inc file is located by default in the include sub-directory of your installation directory on Windows systems, or the $COBDIR/include directory on UNIX systems. We recommend that you open it in a file editor to become familiar with its contents.

mfpubspl.inc contains all of the fields you need to access the MVSSPLPB API from a PL/I program, including function, key, and reason code fields. It also contains the entry point declaration for the interface program. Add mfpubspl.inc to your Enterprise Developer project, and include it in your PL/I program to enable the passing of information to and from the MVSSPLPB API.

Parent topic: MVSSPLPB API
Related information
Spool Data Files
Calling MVSSPLPB
Functions
Keys
Sample Programs
Debug or Run the Program
Return Codes
Reason Codes


Calling MVSSPLPB

Call MVSSPLPB using the following syntax to provide access to information in the spool control files.

COBOL Syntax

call mvssplpb using field-name

PL/I Syntax

call MVSSPLPB (field-name);

Parameters

field-name
The parent field that holds the mfpubspl copybook fields.

COBOL Example

Define a data structure in Working Storage to include mfpubspl copybook fields:
       01  pubcas-area.
       copy 'mfpubspl.cpy' replacing  ==()== by ==WS-API==.
Call MVSSPLPB:
call 'mvssplpb' using  pubcas-area

PL/I Example

Include the interface data structure:
%include mfpubspl;
Call MVSSPLPB:
call MVSSPLPB (field-name);
Parent topic: MVSSPLPB API
Related information
Spool Data Files
Program Requirements
Functions
Keys
Sample Programs
Debug or Run the Program
Return Codes
Reason Codes


Functions

The mfpubspl interface data structure contains several constant fields you can use to populate the API function field. These are documented in the structure itself, under a section labeled Function. The name of each field describes the function itself. There are single OPEN and CLOSE functions, but for each spool file there are the following functions:

START
Greater than, Less than, Greater than or equal to, and Less than or equal to. These functions allow you to establish a position in the files, relative to the key(s) provided in the associated key data area.
GET NEXT
Retrieve the next record in logical sequence, determined by the chosen index.
GET PREV
Retrieve the previous record in logical sequence.
GET UNIQUE
Retrieve the record matching the key(s) provided in the associated key data area.

For COBOL programs, the function names will be prefixed with the string specified in the replacing clause; see Program Requirements for an example. For PL/I programs, the function names will be prefixed with mfpubspl_.

COBOL example

...
      *=================================================================
      *    Function
      *=================================================================

           03  ()-FUNC                       PIC X(8).
              88 ()-FUNC-OPEN                        VALUE 'OPEN'.
              88 ()-FUNC-OPEN-IO                     VALUE 'OPEN-IO'.
              88 ()-FUNC-CLOSE                       VALUE 'CLOSE'.
      *             Get SPLJOB - Next, Previous, or Unique (i.e. by key)
              88 ()-FUNC-GN-JOB                      VALUE 'GN-JOB'.
              88 ()-FUNC-GP-JOB                      VALUE 'GP-JOB'.
              88 ()-FUNC-GU-JOB                      VALUE 'GU-JOB'.
...

PL/I example

...
    /*
       mfpubspl_FUNC_CONSTANTS
    */
    DCL mfpubspl_FUNC_OPEN                CHAR(8) VALUE('OPEN');
    DCL mfpubspl_FUNC_OPEN_IO             CHAR(8) VALUE('OPEN-IO');
    DCL mfpubspl_FUNC_CLOSE               CHAR(8) VALUE('CLOSE');
    /*          Get SPLJOB - Next, Previous, or Unique (i.e. by key) */
    DCL mfpubspl_FUNC_GN_JOB              CHAR(8) VALUE('GN-JOB');
    DCL mfpubspl_FUNC_GP_JOB              CHAR(8) VALUE('GP-JOB');
    DCL mfpubspl_FUNC_GU_JOB              CHAR(8) VALUE('GU-JOB');
...

To specify a function, set the value of one of these fields to the function field defined in the mfpubspl data structure. For example, in a COBOL program, if you have included mfpubspl.cpy in your program replacing () with WS-API:

set WS-API-FUNC-GN-JOB to TRUE.

Or in a PL/I program:

mfpubspl_FUNC = mfpubspl_FUNC_GN_JOB;

A typical sequence of calls could contain the following functions:

Seq no. | Function | Purpose
1 | OPEN | To open the spool files
2 | STGT-JOB | To position on a particular SPLJOB record (e.g., start, key greater than)
3 | GN-JOB | To get the next logical SPLJOB record
4 | STGE-DSN | To position on the first SPLDSN record for the job retrieved in (3) above. The JESYSMSG record (i.e. the job log) is always the first SPLDSN record for a job, with a DD number of zero. If there are no associated OUTPUT statements, the Output sequence number will be zero, otherwise there will be a record for each associated OUTPUT statement, with a non-zero Output sequence number.
5 | GN-DSN | To get the next logical SPLDSN record
6 | CLOSE | To close the files

Sequence number 5 would be repeated until no more SPLDSN records exist for the job (API return code 3 – Job number has changed), followed by a repeat of sequence numbers 2, and/or 3, to retrieve more job records.

Parent topic: MVSSPLPB API
Related information
Spool Data Files
Program Requirements
Calling MVSSPLPB
Keys
Sample Programs
Debug or Run the Program
Return Codes
Reason Codes


Keys

The SPLJOB.dat file includes seven keyed indexes. The MVSSPLPB interface uses these indexes to retrieve records in a particular sequence. To select an index, move its corresponding constant to the KEY-ID field; to illustrate this point, the following partial listing from mfpubspl.cpy shows the available indexes:

...
            03  ()-IDX-DATA.
      *         Available indices are:
             05  ()-JOB-IDX-ID                       PIC X.
      *             JES job number
                88 ()-IDX-IS-JOB-NBR                 VALUE '0'.
      *             job status, name, number
                88 ()-IDX-IS-STATUS-NAME             VALUE '1'.
      *             job status, userid, number
                88 ()-IDX-IS-STATUS-USER             VALUE '2'.
      *             job status, number
                88 ()-IDX-IS-STATUS-NBR              VALUE '3'.
      *             job status, submitted date/time, number
                88 ()-IDX-IS-STATUS-SUB              VALUE '4'.
      *             job status, class, priority, submitted date/time,
      *             job number
                88 ()-IDX-IS-STATUS-CLS-PRTY         VALUE '5'.
      *             job status, completion code, number
                88 ()-IDX-IS-STATUS-COND             VALUE '6'.
...
Parent topic: MVSSPLPB API
Related information
Spool Data Files
Program Requirements
Calling MVSSPLPB
Functions
Sample Programs
Debug or Run the Program
Return Codes
Reason Codes


Sample Programs

The sample programs SPOOLCOB and SPOOLPLI use calls to the MVSSPLPB API to retrieve data from the SPLJOB, SPLMSG and SPLDSN files, and write the returned data to an output file, in a report format.

The source files (SPOOLCOB.cbl and SPOOLPLI.pli) are located in the src sub-directory of your product installation directory.

Parent topic: MVSSPLPB API
Related information
Spool Data Files
Program Requirements
Calling MVSSPLPB
Functions
Keys
Debug or Run the Program
Return Codes
Reason Codes


Debug or Run the Program

Describes the steps required to debug or run a program that calls the MVSSPLPB API.

Debug or Run a Program in Enterprise Server

From your Enterprise Developer project

  1. In Enterprise Developer, create a program using either the Enterprise Server Application template, or the Mainframe Subsystem Application template.
  2. In the Enterprise Developer project, create and build a program that accesses the spool files via the MVSSPLPB API.
    Note: The COBOL interface copybook contains no fields specific to any one COBOL dialect; therefore you can compile your program with any dialect you wish.
  3. In Enterprise Server, create an enterprise server instance to run your program.
  4. Associate your enterprise server instance with your Enterprise Developer project.
  5. Debug or run the program in Enterprise Developer.

From Enterprise Server

  1. In Enterprise Developer, create a project using any appropriate project template.
  2. In the Enterprise Developer project, create and build a program that accesses the spool files via the MVSSPLPB API.
    Note: The COBOL interface copybook contains no fields specific to any one COBOL dialect; therefore you can compile your program with any dialect you wish.
  3. Write JCL to execute the program.
  4. In Enterprise Server, create an enterprise server instance to run your program.
  5. In Enterprise Server, execute the JCL.

Debug or Run a Program Outside of Enterprise Server

If your program was not created with either the Enterprise Server Application template or the Mainframe Subsystem Application template:

  1. Set the MFSYSCAT environment variable to the path and filename of the catalog data file, which by default is located in your Enterprise Developer project directory. For example:
    set MFSYSCAT=c:\myproject\catalog.dat
    Note: If your spool control files (e.g. SPLJOB.dat) are held in a different directory to the catalog, you must also set the following environment variable, for example:
    set MVSSPOOLDIR=c:\myproject\<spool-file-folder>
  2. Create and build the program in Enterprise Developer.
  3. Execute or debug the program from the project, or from an Enterprise Developer command prompt.
Parent topic: MVSSPLPB API
Related information
Spool Data Files
Program Requirements
Calling MVSSPLPB
Functions
Keys
Sample Programs
Return Codes
Reason Codes


Return Codes

Use a return code in conjunction with its corresponding file status or reason code to determine the result of a call to the API, and identify the cause of a problem or failure if one arises.

Return code | Description
00 | Success - for a Get Next or Get Previous function call there was no key change from the previous call.
01 | A Get Next or Get Previous function call resulted in retrieving a record with a different DD number from the previous call.
02 | A Get Next or Get Previous function call resulted in retrieving a record with a different Job Step or JCL Procedure Step sequence number from the previous call.
03 | A Get Next or Get Previous function call resulted in retrieving a record with a different job number from the previous call.
04 | Warning. May be accompanied with a Reason Code of 10, signalling End of File.
08 | Record not found for a Get Unique function call.
12 | Error - includes file I/O errors other than open or start - file status will be set in the interface.
16 | Severe error - includes file open and start failures, and spool file location errors.
20 | Fatal error - includes invalid function or invalid key.
Parent topic: MVSSPLPB API
Related information
Spool Data Files
Program Requirements
Calling MVSSPLPB
Functions
Keys
Sample Programs
Debug or Run the Program
Reason Codes


Reason Codes

All reason codes are documented in the mfpubspl interface structure, in a section labeled Reason codes. For example:

*=================================================================
*    Reason codes
*=================================================================
              88 ()-INVALID-FUNC                     VALUE 01.
              88 ()-INVALID-INDEX-ID                 VALUE 02.
              88 ()-INVALID-SPOOL-VERSION            VALUE 03.
              88 ()-INVALID-SPOOL-LOCATION           VALUE 04.
              88 ()-EOF                              VALUE 10.
              88 ()-BAD-OPEN-STATUS                  VALUE 11.
              88 ()-BAD-CLOS-STATUS                  VALUE 12.
              88 ()-BAD-GN-STATUS                    VALUE 13.

Match the returned reason code value to that of a reason code constant in the copybook. The field name provides the description of the code. The current file status code and name will be returned in the fields that immediately follow the reason code in the interface data structure.

Parent topic: MVSSPLPB API
Related information
Spool Data Files
Program Requirements
Calling MVSSPLPB
Functions
Keys
Sample Programs
Debug or Run the Program
Return Codes


MVSCASPB API

This program is delivered for compatibility with earlier releases of Enterprise Developer, enabling you to access a subset of job status information held in the spool control files SPLJOB, SPLMSG, and SPLDSN.
Note: This API only gives you access to a subset of the spool control files. For new spool queries, and for access to the complete set of spool control files, we recommend that you use the MVSSPLPB API.

When you submit a batch job to Enterprise Server, job information is written to the spool files, which are continually updated throughout the life of the job. This creates a chronological record of the stages of execution from the job submission stage through to job completion.

The interface for the ESMAC spool queues enables you to view the status of current jobs in Enterprise Server; however, it does not provide full access to the information in the spool files. The MVSCASPB API provides access to all fields previously held in casspool.dat. When you call it from a COBOL program, you can retrieve all or some of this data by referencing one or more keyed indexes.

  • COBOL Requirements
    Describes the COBOL program requirements for accessing the MVSCASPB API.
  • mfpubcas.cpy
    Describes the use of the mfpubcas.cpy file.
  • Calling MVSCASPB
    Call MVSCASPB using the following syntax to provide access to the job status information held in the JES spool files.
  • Functions
    Describes the functions you can use with the MVSCASPB API.
  • Keys
    Describes the keys you can use with the MVSCASPB API.
  • Sample Program
    Presents a sample COBOL program that calls the MVSCASPB API.
  • Debug or Run the Program
    Describes how to debug or run a program that calls the MVSCASPB API.
  • Return Codes
    Describes the return codes produced by the MVSCASPB API.
  • Reason Codes
    Reason codes describe the reason for a non-zero return code from the MVSCASPB API.
Parent topic: Public SPOOL APIs
Related information
MVSSPLPB API


COBOL Requirements

Describes the COBOL program requirements for accessing the MVSCASPB API.
Programs that access MVSCASPB must:
  • Include the mfpubcas copybook in Working-Storage.
  • Move a function code to the appropriate Working-Storage field.
  • Populate the key fields and the key-id.
  • Call the mvscaspb utility using the mfpubcas copybook fields in Working-Storage.
Parent topic: MVSCASPB API
Related information
mfpubcas.cpy
Calling MVSCASPB
Functions
Keys
Sample Program
Debug or Run the Program
Return Codes
Reason Codes


mfpubcas.cpy

Describes the use of the mfpubcas.cpy file.

The mfpubcas.cpy file is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) sub-directory. We suggest you open it in any file editor to become familiar with its contents.

mfpubcas.cpy contains all of the Working-Storage fields you need to access the MVSCASPB API, including function, key, and reason code fields. Add mfpubcas.cpy to your Enterprise Developer project, and include it in your COBOL program to enable the passing of information to and from the MVSCASPB API.

When you include mfpubcas.cpy in your program:
  • Include it in Working-Storage as a child of an 01-level field.
  • Use copy...replacing syntax to replace () with a qualifier. For example:
           01  pubcas-area.
       copy 'mfpubcas.cpy' replacing  ==()== by ==WS==.
Parent topic: MVSCASPB API
Related information
COBOL Requirements
Calling MVSCASPB
Functions
Keys
Sample Program
Debug or Run the Program
Return Codes
Reason Codes


Calling MVSCASPB

Call MVSCASPB using the following syntax to provide access to the job status information held in the JES spool files.

Syntax

call mvscaspb using field-name

Parameters

field-name
The parent field that holds the mfpubcas copybook fields.

Example

Define a data structure in Working Storage to include mfpubcas copybook fields:
       01  pubcas-area.
           copy 'mfpubcas.cpy' replacing  ==()== by ==WS==.
Call mvscaspb:
call 'mvscaspb' using  pubcas-area
Parent topic: MVSCASPB API
Related information
COBOL Requirements
mfpubcas.cpy
Functions
Keys
Sample Program
Debug or Run the Program
Return Codes
Reason Codes


Functions

Describes the functions you can use with the MVSCASPB API.

The mfpubcas.cpy copybook contains several 78-level fields you can use to call API functions. These are documented in the copybook itself, under a section labeled functions. The name of each field describes the function itself.

The following is a partial listing from mfpubcas.cpy:

...
      *=================================================================
      *    functions
      *=================================================================

           03  ()-FUNC                       PIC X(4).
                78  78-CAS-FUNC-OPEN         VALUE 'OP  '.
                78  78-CAS-FUNC-OPIO         VALUE 'OPIO'.
                78  78-CAS-FUNC-CLOS         VALUE 'CLOS '.
                78  78-CAS-FUNC-GN           VALUE 'GN  '.
...
To call a function from a COBOL program, move the value of one of these fields to the 03 ()-FUNC field defined in mfpubcas.cpy. For example, if you have included mfpubcas.cpy in your program, replacing () with WS:
move 78-CAS-FUNC-GN to WS-FUNC

A typical sequence of calls would contain the following functions:

Function | Purpose
78-CAS-FUNC-OPEN | To open the file.
78-CAS-FUNC-STGT | To position on a particular record (e.g., start, key greater than, etc.).
78-CAS-FUNC-GN | To get the next record, and then repeated to get each subsequent record until all required records have been returned.
78-CAS-FUNC-CLOS | To close the file.
Parent topic: MVSCASPB API
Related information
COBOL Requirements
mfpubcas.cpy
Calling MVSCASPB
Keys
Sample Program
Debug or Run the Program
Return Codes
Reason Codes


Keys

The SPLJOB.dat file includes six keyed indexes. The MVSCASPB interface uses these indexes to replicate the keys previously defined in casspool.dat. To select an index, move its corresponding 78-level field to the KEY-ID field; to illustrate this point, the following partial listing from mfpubcas.cpy shows the available indexes:

...
  *   ==============================================
          03  KEY-DATA.
             05  ()-key-id                   PIC x.
      *         available keys are:
                78  78-KEY-IS-type           value '1'.
      *             type, rec-class, rec-priorty, rec-version, job-nbr, job-seq
                78  78-KEY-IS-job-NUMBER     value '2'.
      *             job-nbr, job-seq
                78  78-KEY-IS-type-job-name  value '3'.
      *              type, job-name, job-nbr
                78  78-KEY-IS-type-userid    value '4'.
      *              type, userid, job-nbr
                78  78-KEY-IS-type-job-nbr   value '5'.
      *              type and job-nbr
                78  78-KEY-IS-type-date      value '6'.
      *              type, date, job-nbr
      *      ===========================================
...
Parent topic: MVSCASPB API
Related information
COBOL Requirements
mfpubcas.cpy
Calling MVSCASPB
Functions
Sample Program
Debug or Run the Program
Return Codes
Reason Codes


Sample Program

Presents a sample COBOL program that calls the MVSCASPB API.

This sample program uses the MVSCASPB API to retrieve various subsets of data, and writes the returned data to an output file.

       identification division.
       program-id. Program1.

       environment division.
       configuration section.
       input-output section.
       file-control.
               SELECT ASCII-FILE
               ASSIGN TO ASCII-DSN
               ORGANIZATION IS LINE SEQUENTIAL
               FILE STATUS ASCII-FILE-STATUS.
       data division.
            FILE SECTION.
       FD  ASCII-FILE
           LABEL RECORDS STANDARD.
       01  ASCII-DATA                  PIC X(80).
       working-storage section.
       01 ascii-file-status        pic xx.
       01 ascii-dsn                pic x(250).

       01 disp-rc                  pic 9999.
       01 disp-rsn                 pic 9999.
       01 disp-type                pic Z9.
       01 disp-job-nbr             pic 9(9). *> Increased to allow for
                                             *> 7 digit numbers
       01 disp-cc.
           03 disp-cc-type         pic x(01).
           03 disp-cc-nbr          pic 9(04).

       01  save-job-name           pic x(8).
       01  save-job-nbr            pic x(4) comp-x.

       01  ws-pb-get-version       pic 9(04).

       01  ws-pubcas-spl-format        pic x(01) comp-x.
           88 ws-SPL-FORMAT-1             VALUE 1.
                                               *> 5 digit casspool.dat
           88 ws-SPL-FORMAT-2             VALUE 2.
                                               *> unused
           88 ws-SPL-FORMAT-3             VALUE 3.
                                               *> restructed spljob
           88 ws-SPL-FORMAT-4             VALUE 4.
           88 ws-SPL-FORMAT-5             VALUE 5.

       01  ws-idx1             pic x(04) comp-5.

       01 pubcas-area.
       copy "mfpubcas.cpy" replacing ==()== by ==pubcas==.

       procedure division.

           *> specify were the output should be written
           move '$outdir/output.txt' to ASCII-DSN
           open output ascii-file
           if ascii-file-status <> '00'
               display 'open output  failed '  ascii-file-status
               goback
           end-if

           perform get-messages                *> type 6

           perform get-o-hold                  *> type 7

           perform get-ds-hold                 *> type 9

           perform get-ds-out                  *> type 10

           *> With the new spool control files (ws-SPL-FORMAT-3)
           *> there aren't any type 7 or 8 records.
           *> So next 4 methods will not return any records.
           *> Use type 9 and 10 (as above)

           perform get-o-hold-type-jobname     *> type 7 by job name

           perform get-o-hold-type-create-date *> type 7 by date

           perform o-spool-files-jobname       *> type 8 and associated
                                               *> type 10s

           perform o-held-spool-files-jobname  *> type 7 and associated
                                               *> type 9s
           if ws-SPL-FORMAT-3
               *> we are using the new spool control file format
               *> so we can ask for completed jobs
               perform get-completed-jobs          *> type 20
           end-if

           display 'test prog ended '

           goback.

       o-held-spool-files-jobname section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Jobs with held output spool files ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-job-name
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           *> loop through the type output records to find jobs with
           *> output spool files
           perform until pubcas-retcode <> 0
                      or pubcas-type    <>  pubcas-o-hold-78

               *> for each o-hold record
               *> print details
               *> save key
               *> get associated output spool records (ds-hold)
               *> reposition for next o-hold record
               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move pubcas-job-name    to save-job-name
               move pubcas-job-nbr     to save-job-nbr

               move low-values         to pubcas-area
               move 78-KEY-IS-job-NUMBER
                                       to pubcas-key-id
               move save-job-nbr       to pubcas-job-nbr

               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas
               perform until pubcas-retcode <> 0
                      or pubcas-job-nbr   <>  save-job-nbr
                   *> all the output spool files for this job
                   if pubcas-type = pubcas-ds-hold-78
                       move spaces to ascii-data
                       string
                         '     '                    delimited by size
                         pubcas-SYSOT-STEP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-PSTP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-DD-NAME       delimited by size
                       into ascii-data
                       perform write-outfile
                   end-if
                   perform call-pubcas
               end-perform

               *> reposition on the next job name that has a type 8 record
               move low-values         to pubcas-area
               move 78-KEY-IS-type-job-name
                                       to pubcas-key-id
               move pubcas-o-hold-78   to pubcas-type
               move save-job-name      to pubcas-job-name
               move save-job-nbr       to pubcas-job-nbr
               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               *> get next next job
               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas

               if  pubcas-job-name  = save-job-name
                   and
                   pubcas-job-nbr   = save-job-nbr
                   *> STGT and GN gets the same type 8
                   *> record ( duplicate keys allowed )
                   *> so need a second GN to get the next record
                   move 78-CAS-FUNC-GN     to pubcas-func
                   perform call-pubcas
               end-if

           end-perform

           move 78-CAS-FUNC-CLOS       to pubcas-func
           perform call-pubcas

       exit section.

       o-spool-files-jobname section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Jobs with output spool files ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-job-name
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-out-78      to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           *> loop through the type output records to find jobs with
           *> output spool files
           perform until pubcas-retcode > 4
                      or pubcas-type    <>  pubcas-out-78
                      or pubcas-rsncode = 78-EOF

               *> for each o-hold record
               *> print details
               *> save key
               *> get associated output spool records (ds-hold)
               *> reposition for next o-hold record
               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move pubcas-job-name    to save-job-name
               move pubcas-job-nbr     to save-job-nbr

               move low-values         to pubcas-area
               move 78-KEY-IS-job-NUMBER
                                       to pubcas-key-id
               move save-job-nbr       to pubcas-job-nbr

               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas
               perform until pubcas-retcode <> 0
                      or pubcas-job-nbr   <>  save-job-nbr
                   *> all the output spool files for this job
                   if pubcas-type = pubcas-ds-out-78
                       move spaces to ascii-data
                       string
                         '     '                    delimited by size
                         pubcas-SYSOT-STEP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-PSTP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-DD-NAME       delimited by size
                       into ascii-data
                       perform write-outfile
                   end-if
                   perform call-pubcas
               end-perform

               *> reposition on the next job name that has a type 8 record
               move low-values         to pubcas-area
               move 78-KEY-IS-type-job-name
                                       to pubcas-key-id
               move pubcas-out-78      to pubcas-type
               move save-job-name      to pubcas-job-name
               move save-job-nbr       to pubcas-job-nbr
               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               *> get next next job
               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas

               if  pubcas-job-name  = save-job-name
                   and
                   pubcas-job-nbr   = save-job-nbr
                   *> STGT and GN gets the same type 8
                   *> record ( duplicate keys allowed )
                   *> so need a second GN to get the next record
                   move 78-CAS-FUNC-GN     to pubcas-func
                   perform call-pubcas
               end-if

           end-perform

           move 78-CAS-FUNC-CLOS       to pubcas-func
           perform call-pubcas

       exit section.

       get-o-hold-type-create-date section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type and Date - hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-date
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode <> 0
                      or pubcas-type    <>  pubcas-o-hold-78

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-o-hold-type-jobname section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type and Job Name - o-hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-job-name
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78  to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 4
                      or pubcas-type    <>  pubcas-o-hold-78
                      or pubcas-rsncode = 78-EOF

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-ds-out section.
           move spaces to ascii-data
           perform write-outfile

           move 'By Type - ds-out ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-ds-out-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 4
                       or pubcas-type    <> pubcas-ds-out-78
                       or pubcas-rsncode = 78-EOF

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-sysot-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-step-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-pstp-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-dd-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-create-date
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-o-hold section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type - o-hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 4
                      or pubcas-type    <> pubcas-o-hold-78
                      or pubcas-rsncode = 78-EOF

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name delimited by size
                       ','             delimited by size
                       pubcas-sysot-create-date
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-ds-hold section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type - ds-hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-ds-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT    to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 4
                      or pubcas-type    <> pubcas-ds-hold-78
                      or pubcas-rsncode = 78-EOF

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-sysot-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-step-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-pstp-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-dd-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-create-date
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-messages section.

           move 'Messages '        to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-mesg-78     to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode <> 0
               or pubcas-type > pubcas-mesg-78

               move pubcas-type      to disp-type
               if pubcas-msglg-mesg-length > 256
                   move 256 to pubcas-msglg-mesg-length
               end-if
               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       pubcas-msglg-mesg(1:pubcas-msglg-mesg-length)
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-completed-jobs section.
           move spaces to ascii-data
           perform write-outfile

           move 'Completed Jobs' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-JOB-COMPLETED-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           IF pubcas-RETCODE > ZERO
               EXIT SECTION
           END-IF

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 4
                      or pubcas-type    <> pubcas-JOB-COMPLETED-78
                      or pubcas-rsncode = 78-EOF

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               move 1 to ws-idx1
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-JOB-NAME delimited by size
                       ','             delimited by size
                       pubcas-REC-CLASS    delimited by size
               into ascii-data with pointer ws-idx1

               *> If the COND-CODE value has a type indicator
               *> and exceeds 3 digits in value, e.g. U2052
               *> then, because of the limitation in space in the
               *> pubcas-INPUT-COND-CODE field, the
               *> pubcas-INPUT-CC-TYPE and pubcas-INPUT-CC-NUM
               *> format is used.
               if pubcas-rec-type-input-88
                   if pubcas-INPUT-CC-TYPE > x'f0'
                       evaluate true
                           when pubcas-INPUT-CC-TYPE-ERR-88
                               string
                                   ','     delimited by size
                                   'ERR'   delimited by size
                               into ascii-data with pointer ws-idx1
                           when pubcas-INPUT-CC-TYPE-SYS-88
                               string
                                   ','     delimited by size
                                   'SYS'   delimited by size
                               into ascii-data with pointer ws-idx1
                           when pubcas-INPUT-CC-TYPE-RTS-88
                               string
                                   ','     delimited by size
                                   'RTS'   delimited by size
                               into ascii-data with pointer ws-idx1
                           when pubcas-INPUT-CC-TYPE-USER-88
                               string
                                   ','     delimited by size
                                   'USR'   delimited by size
                               into ascii-data with pointer ws-idx1
                           when pubcas-INPUT-CC-TYPE-RC-88
                               string
                                   ','     delimited by size
                                   'RC '   delimited by size
                               into ascii-data with pointer ws-idx1

                           when other
                               string
                                   ','     delimited by size
                                   'XXX'   delimited by size
                               into ascii-data with pointer ws-idx1

                       end-evaluate
                       move pubcas-INPUT-CC-NUM to disp-cc-nbr
                       string
                           ','             delimited by size
                           disp-cc         delimited by size
                       into ascii-data with pointer ws-idx1
                   else
                       move pubcas-INPUT-COND-CODE to disp-cc
                       string
                           ','         delimited by size
                           'CC:'       delimited by size
                           disp-cc     delimited by size
                       into ascii-data with pointer ws-idx1
                   end-if

               end-if

               if pubcas-REC-TYPE-SYSOT-88
                   if pubcas-sysot-create-date is numeric
                        string
                           ','             delimited by size
                            pubcas-sysot-create-date
                                           delimited by size
                        into ascii-data with pointer ws-idx1
                   end-if

                   string
                       ','             delimited by size
                       pubcas-sysot-step-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-pstp-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-dd-name
                                       delimited by size
                   into ascii-data with pointer ws-idx1

                   *> If 7 digit job numbering is active then
                   *> the SYSOT JOB Number will be a COMP-X item
                   if pubcas-SYSOT-JOB-NBR-2 is numeric
                       *> 5 digit
                       move pubcas-SYSOT-JOB-JOBNUM-5 to disp-job-nbr
                   else
                       *> 7 digit
                       move pubcas-SYSOT-JOB-JOBNUM-COMPX
                           to disp-job-nbr
                   end-if
                   string
                       ",JN: "
                       disp-job-nbr  delimited by size
                   into ascii-data with pointer ws-idx1

               end-if
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       call-pubcas section.
           if pubcas-FUNC = 78-CAS-FUNC-OPEN
               *> Set the version to the current version
               if pubcas-VERSION <= spaces
                   move CURR-VERSION to pubcas-VERSION
               end-if
           end-if

           call "mvscaspb" using pubcas-area
           if pubcas-retcode > 8
               move pubcas-RETCODE to disp-rc
               move pubcas-RSNCODE to disp-rsn
               display 'call failed func ' pubcas-func ','
                                           disp-rc ',' disp-rsn
                                           ',' pubcas-file-status
               goback
           end-if
           if pubcas-FUNC = 78-CAS-FUNC-OPEN
               if pubcas-VERSION is numeric
                   move pubcas-VERSION to ws-pb-get-version
               else
                   move 1 to ws-pb-get-version
               end-if
               if ws-pb-get-version >= 2
                   *> Store the type of spool control file
                   *> were are using
                   move pubcas-SPL-INFO-FILES-FORMAT
                     to ws-pubcas-spl-format
               end-if
           end-if
       exit section.

       write-outfile section.
           write ASCII-DATA
           if ascii-file-status <> '00'
               display 'write output  failed '  ascii-file-status
               goback
           end-if
       exit section

       end program Program1.

       identification division.
       program-id. Program1.

       environment division.
       configuration section.
       input-output section.
       file-control.
               SELECT ASCII-FILE
               ASSIGN TO ASCII-DSN
               ORGANIZATION IS LINE SEQUENTIAL
               FILE STATUS ASCII-FILE-STATUS.
       data division.
            FILE SECTION.
       FD  ASCII-FILE
           LABEL RECORDS STANDARD.
       01  ASCII-DATA                  PIC X(80).
       working-storage section.
       01 ascii-file-status        pic xx.
       01 ascii-dsn                pic x(250).

       01 disp-rc                  pic 9999.
       01 disp-rsn                 pic 9999.
       01 disp-type                pic 9.
       01 disp-job-nbr             pic 9(6).

       01 directory-name           pic x(260).
       01 flags                    pic x(4) comp-5.
       01 name-length              pic x(4) comp-5.
       01 status-code              pic x(2) comp-5.

       01  save-job-name           pic x(8).
       01  save-job-nbr            pic x(4) comp-x.

       01 pubcas-area.
       copy "mfpubcas.cpy" replacing ==()== by ==pubcas==.

       procedure division.

           move '$outdir/output.txt' to ASCII-DSN
           open output ascii-file
           if ascii-file-status <> '00'
               display 'open output  failed '  ascii-file-status
               goback
           end-if

           move 0 to flags
           call "CBL_GET_CURRENT_DIR" using by value flags
                           by value       name-length
                           by reference   directory-name
                           returning      status-code

           perform get-messages                *> type 6

           perform get-o-hold                  *> type 7

           perform get-ds-hold                 *> type 8

           perform get-o-hold-type-jobname     *> type 7 by job name

           perform get-o-hold-type-create-date *> type 7 by date

           perform o-spool-files-jobname       *> type 8 and associated
                                               *> type 10s

           perform o-held-spool-files-jobname  *> type 7 and associated
                                               *> type 9s

           display 'test prog ended '

           goback.

       o-held-spool-files-jobname section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Jobs with held output spool files ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-job-name
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           *> loop through the type output records to find jobs with
           *> output spool files
           perform until pubcas-retcode > 8
                      or pubcas-type    <>  pubcas-o-hold-78

               *> for each o-hold record
               *> print details
               *> save key
               *> get associated output spool records (ds-hold)
               *> reposition for next o-hold record
               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move pubcas-job-name    to save-job-name
               move pubcas-job-nbr     to save-job-nbr

               move low-values         to pubcas-area
               move 78-KEY-IS-job-NUMBER
                                       to pubcas-key-id
               move save-job-nbr       to pubcas-job-nbr

               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas
               perform until pubcas-retcode > 8
                      or pubcas-job-nbr   <>  save-job-nbr
                   *> all the output spool files for this job
                   if pubcas-type = pubcas-ds-hold-78
                       move spaces to ascii-data
                       string
                         '     '                    delimited by size
                         pubcas-SYSOT-STEP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-PSTP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-DD-NAME       delimited by size
                       into ascii-data
                       perform write-outfile
                   end-if
                   perform call-pubcas
               end-perform

               *> reposition on the next job name that has a type 8 record
               move low-values         to pubcas-area
               move 78-KEY-IS-type-job-name
                                       to pubcas-key-id
               move pubcas-o-hold-78   to pubcas-type
               move save-job-name      to pubcas-job-name
               move save-job-nbr       to pubcas-job-nbr
               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               *> get next next job
               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas

               if  pubcas-job-name  = save-job-name
                   and
                   pubcas-job-nbr   = save-job-nbr
                   *> STGT and GN gets the same type 8
                   *> record ( duplicate keys allowed )
                   *> so need a second GN to get the next record
                   move 78-CAS-FUNC-GN     to pubcas-func
                   perform call-pubcas
               end-if

           end-perform

           move 78-CAS-FUNC-CLOS       to pubcas-func
           perform call-pubcas

       exit section.

       o-spool-files-jobname section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Jobs with output spool files ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-job-name
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-out-78      to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           *> loop through the type output records to find jobs with
           *> output spool files
           perform until pubcas-retcode > 8
                      or pubcas-type    <>  pubcas-out-78

               *> for each o-hold record
               *> print details
               *> save key
               *> get associated output spool records (ds-hold)
               *> reposition for next o-hold record
               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move pubcas-job-name    to save-job-name
               move pubcas-job-nbr     to save-job-nbr

               move low-values         to pubcas-area
               move 78-KEY-IS-job-NUMBER
                                       to pubcas-key-id
               move save-job-nbr       to pubcas-job-nbr

               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas
               perform until pubcas-retcode > 8
                      or pubcas-job-nbr   <>  save-job-nbr
                   *> all the output spool files for this job
                   if pubcas-type = pubcas-ds-out-78
                       move spaces to ascii-data
                       string
                         '     '                    delimited by size
                         pubcas-SYSOT-STEP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-PSTP-NAME     delimited by size
                         ','             delimited by size
                         pubcas-SYSOT-DD-NAME       delimited by size
                       into ascii-data
                       perform write-outfile
                   end-if
                   perform call-pubcas
               end-perform

               *> reposition on the next job name that has a type 8 record
               move low-values         to pubcas-area
               move 78-KEY-IS-type-job-name
                                       to pubcas-key-id
               move pubcas-out-78      to pubcas-type
               move save-job-name      to pubcas-job-name
               move save-job-nbr       to pubcas-job-nbr
               move 78-CAS-FUNC-STGT   to pubcas-func
               perform call-pubcas

               *> get next next job
               move 78-CAS-FUNC-GN     to pubcas-func
               perform call-pubcas

               if  pubcas-job-name  = save-job-name
                   and
                   pubcas-job-nbr   = save-job-nbr
                   *> STGT and GN gets the same type 8
                   *> record ( duplicate keys allowed )
                   *> so need a second GN to get the next record
                   move 78-CAS-FUNC-GN     to pubcas-func
                   perform call-pubcas
               end-if

           end-perform

           move 78-CAS-FUNC-CLOS       to pubcas-func
           perform call-pubcas

       exit section.

       get-o-hold-type-create-date section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type and Date - hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-date
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 8
                      or pubcas-type    <>  pubcas-o-hold-78

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-o-hold-type-jobname section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type and Job Name - o-hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type-job-name
                                   to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78  to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 8
                      or pubcas-type    <>  pubcas-o-hold-78

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-dat-time
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-ds-out section.
           move spaces to ascii-data
           perform write-outfile

           move 'By Type - ds-out ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-ds-out-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 8
                      or pubcas-type    <> pubcas-o-hold-78

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-o-hold section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type - o-hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-o-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 8
                      or pubcas-type    <> pubcas-o-hold-78

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-job-name delimited by size
                       ','             delimited by size
                       pubcas-sysot-create-date
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-ds-hold section.
           move spaces to ascii-data
           perform write-outfile
           move 'By Type - ds-hold ' to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-ds-hold-78   to pubcas-type
           move 78-CAS-FUNC-STGT    to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode > 8
                      or pubcas-type    <> pubcas-ds-hold-78

               move pubcas-type      to disp-type
               move pubcas-job-nbr   to disp-job-nbr

               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       disp-job-nbr    delimited by size
                       ','             delimited by size
                       pubcas-sysot-job-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-step-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-pstp-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-dd-name
                                       delimited by size
                       ','             delimited by size
                       pubcas-sysot-create-date
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       get-messages section.

           move 'Messages '        to ascii-data
           perform write-outfile

           move low-values         to pubcas-area
           move 78-KEY-IS-type     to pubcas-key-id

           move 78-CAS-FUNC-OPEN   to pubcas-func
           perform call-pubcas

           move pubcas-mesg-78     to pubcas-type
           move 78-CAS-FUNC-STGT   to pubcas-func
           perform call-pubcas

           move 78-CAS-FUNC-GN     to pubcas-func
           perform call-pubcas

           perform until pubcas-retcode <> 0
               or pubcas-type > pubcas-mesg-78

               move pubcas-type      to disp-type
               if pubcas-msglg-mesg-length > 256
                   move 256 to pubcas-msglg-mesg-length
               end-if
               move spaces to ascii-data
               string  disp-type       delimited by size
                       ','             delimited by size
                       pubcas-msglg-mesg(1:pubcas-msglg-mesg-length)
                                       delimited by size
                       into ascii-data
               perform write-outfile

               move 78-CAS-FUNC-GN  to pubcas-func
               perform call-pubcas
           end-perform

           move 78-CAS-FUNC-CLOS    to pubcas-func
           perform call-pubcas
       exit section.

       call-pubcas section.
           call "mvscaspb" using pubcas-area
           if pubcas-retcode > 8
               move pubcas-RETCODE to disp-rc
               move pubcas-RSNCODE to disp-rsn
               display 'call failed func ' pubcas-func ','
                                           disp-rc ',' disp-rsn
                                           ',' pubcas-file-status
               goback
           end-if
       exit section.

       write-outfile section.
           write ASCII-DATA
           if ascii-file-status <> '00'
               display 'write output  failed '  ascii-file-status
               goback
           end-if
       exit section

       end program Program1.
Parent topic: MVSCASPB API
Related information
COBOL Requirements
mfpubcas.cpy
Calling MVSCASPB
Functions
Keys
Debug or Run the Program
Return Codes
Reason Codes


Debug or Run the Program

Describes how to debug or run a program that calls the MVSCASPB API.

Debug or Run a Program in Enterprise Server

From your Enterprise Developer project

  1. In Enterprise Developer, create a program using either the Enterprise Server Application template, or the Mainframe Subsystem Application template.
  2. In the Enterprise Developer project, create and build a program that accesses the spool files via the MVSCASPB API.
    Note: Because the interface copybook contains fields declared as COMP-X, you need to compile your program using the MF dialect.
  3. In Enterprise Server, create an enterprise server instance to run your program.
  4. Associate your enterprise server instance with your Enterprise Developer project.
  5. Debug or run the program in Enterprise Developer.

From Enterprise Server

  • In Enterprise Developer, create a project using any appropriate project template.
  • In the Enterprise Developer project, create and build a program that accesses the spool files via the MVSCASPB API.
    Note: Because the interface copybook contains fields declared as COMP-X, you need to compile your program using the MF dialect.
  • Write JCL to execute the program.
  • In Enterprise Server, create an enterprise server instance to run your program.
  • In Enterprise Server, execute the JCL.

Debug or Run a Program Outside of Enterprise Server

If your program was not created with either the Enterprise Server Application template or the Mainframe Subsystem Application template:

  1. Set the MFSYSCAT environment variable to the path and filename of the catalog data file, which by default is located in your Enterprise Developer project directory. For example:
    set MFSYSCAT=c:\myproject\catalog.dat
    Note: If your spool files are held in a different directory to the catalog, you must also set the following environment variable, for example:
    set MVSSPOOLDIR=c:\myproject\<spool-file-folder>
  2. Create and build the program in Enterprise Developer.
  3. Execute or debug the program from the project, or from an Enterprise Developer command prompt.
Parent topic: MVSCASPB API
Related information
COBOL Requirements
mfpubcas.cpy
Calling MVSCASPB
Functions
Keys
Sample Program
Return Codes
Reason Codes


Return Codes

Describes the return codes produced by the MVSCASPB API.

Use a return code in conjunction with its corresponding file status or reason code to determine the cause of a problem or failure when calling the MVSCASPB API.

Code | Description
004 | An encountered key is a duplicate of the previous key (some indexes allow duplicate keys).
008 | End of file.
016 | File I/O error.
020 | Invalid function or invalid key.
Parent topic: MVSCASPB API
Related information
COBOL Requirements
mfpubcas.cpy
Calling MVSCASPB
Functions
Keys
Sample Program
Debug or Run the Program
Reason Codes


Reason Codes

Reason codes describe the reason for a non-zero return code from the MVSCASPB API.

All reason codes are documented in the mfpubcas.cpy copybook, in a section labeled reason codes. For example:

 *=================================================================
      *    reason codes
      *=================================================================
           78  78-INVALID-FUNC               VALUE 001.
           78  78-INVALID-KEY-ID             VALUE 002.
           78  78-MFSYSCAT                   VALUE 003.
           78  78-BAD-OPEN-STATUS            VALUE 010.
           78  78-BAD-OPIO-STATUS            VALUE 011.
           78  78-BAD-CLOS-STATUS            VALUE 012.
           78  78-BAD-GN-STATUS              VALUE 013.
           78  78-BAD-GP-STATUS              VALUE 014.
           78  78-BAD-GU-STATUS              VALUE 015.
           78  78-BAD-REPL-STATUS            VALUE 016.
           78  78-BAD-STNGT-STATUS           VALUE 017.
           78  78-BAD-STNLT-STATUS           VALUE 018.
           78  78-EOF                        VALUE 019.
           78  78-DUP-KEY                    VALUE 020.
           78  78-NOT-YET-SUPORTED           VALUE 021.

Match the return code value to that of a 78-level field reason code in the copybook. The field name provides the reason for the code.

Parent topic: MVSCASPB API
Related information
COBOL Requirements
mfpubcas.cpy
Calling MVSCASPB
Functions
Keys
Sample Program
Debug or Run the Program
Return Codes


Public Catalog API (MVSCATPB)

Describes the Public Catalog API that you can use to access and update JES Catalog information.

You can view and update some entries in the JES catalog from the ESMAC interface; however, ESMAC does not provide full access to the information stored in the catalog. The Public Catalog API enables you to access and update the information in the JES catalog, including information that is not available from the ESMAC interface.

You can gain full access to the information in the catalog by calling the API from a COBOL program. When you run the program in Enterprise Server, you can access and update the information in the catalog. When the API is called while under the control of Enterprise Server it enques and deques on datasets, preventing catalog entries from being updated while in use elsewhere. However, no such security is available when you run a program outside of Enterprise Server. Therefore, when you run a program outside of Enterprise Server, you can access information in the catalog, but you cannot make any updates.

  • COBOL Requirements
    Describes the COBOL program requirements for accessing the Public Catalog API.
  • mfpubcat.cpy
    Describes the use of the mfpubcat.cpy file.
  • Calling MVSCATPB
    Provides access to the Public Catalog API.
  • Functions
    Describes the functions you can use with the Public Catalog API.
  • Using the API for Catalog Error Reporting
  • Sample Program
    Presents a sample COBOL program that calls the Public Catalog API.
  • Debug or Run the Program
    Describes how to debug or run a program that calls the Public Catalog API.
  • Return Codes
    Describes the return codes produced by the Public Catalog API.
  • Reason Codes
    Reason codes describe the reason for a non-zero return code from the Public Catalog API.
Parent topic: Micro Focus Utilities


COBOL Requirements

Describes the COBOL program requirements for accessing the Public Catalog API.
Any COBOL program that accesses the Public Catalog API must:
  • Include the mfpubcat copybook in Working-Storage
  • Move a function code to the appropriate Working-Storage field
  • Call the mvscatpb utility using the mfpubcat copybook fields in Working-Storage
Parent topic: Public Catalog API (MVSCATPB)
Related reference
mfpubcat.cpy
Calling MVSCATPB
Functions
Sample Program


mfpubcat.cpy

Describes the use of the mfpubcat.cpy file.

The mfpubcat.cpy file is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) directory. We suggest you open it in any file editor to become familiar with its contents.

mfpubcat.cpy contains all of the Working-Storage fields you need to access the Public Catalog API, including function and reason code fields. Add mfpubcat.cpy to your Enterprise Developer project, and include it in your COBOL program to enable the passing of information to and from the Public Catalog API.

When you include mfpubcat.cpy in your program:
  • Include it in Working-Storage as a child of an 01-level field.
  • Use copy...replacing syntax to replace () with a qualifier. For example:
           01  PUBCAT-AREA.
       copy 'mfpubcat.cpy' replacing  ==()== by ==WS==.
Parent topic: Public Catalog API (MVSCATPB)
Related concepts
COBOL Requirements
Related reference
Functions
Sample Program
Reason Codes
Calling MVSCATPB


Calling MVSCATPB

Provides access to the Public Catalog API.

Syntax

call mvscatpb using field-name

Parameters

field-name
The parent field that holds the mfpubcat copybook fields.

Example

Define a data structure in Working Storage to include mfpubcat copybook fields:
       01  PUBCAT-AREA.
       copy 'mfpubcat.cpy' replacing  ==()== by ==WS==.
Call mvscatpb:
call 'mvscatpb' using  pubcat-area
Parent topic: Public Catalog API (MVSCATPB)
Related concepts
COBOL Requirements
Related reference
Sample Program
Return Codes
Reason Codes
mfpubcat.cpy


Functions

Describes the functions you can use with the Public Catalog API.

The COBOL copybook mfpubcat.cpy and PL/I include member mfpubcat.inc contain declarations of constants that you can use to populate the function field (FUNC) when calling the API. In the copybook, these are 78 level fields immediately following the FUNC field, and in the include member, they are declared immediately following the interface structure.

The functions supported are as follows:

Function code | Description
ALLC | Insert a new record into the catalog, using values provided in the interface area. If the associated physical file does not already exist, and the environment variable MFALLOC_PCFILE is not set to N, allocate the associated physical file.
DLET | Delete. Remove a record from the catalog based on the DSN named in the interface area and delete the associated physical file.
GCFE | Get Catalog File Errors. Returns the first catalog file error that occurred.
GCFS | Get Catalog File Status. Returns the file status details of the first catalog file or the catalog number specified by ()-cat-file-number (see mfpubcat.cpy).
GETC | Get Cluster. When passed a VSAM Cluster element (for example, an Alternate Index, dataset name), this function returns the Cluster that the element belongs to.
GN | Get Next. Retrieve the next catalog record, based on the DSN index. If a current position has not already been established, the results are undefined.
GNFE | Get Next Catalog File Error. Gets the next catalog file error. GCFE retrieves all the catalog file errors that occurred during the previous listing, and returns the first one. Follow that call with GNFE calls to iterate over the list.
GNFS | Get Next File Status. Gets the next catalog file status. GCFS retrieves all the catalog file status records, and returns the first one. Follow that call with GNFS calls to iterate over all the catalog file statuses.
GNPC | Get Next PCDSN. Retrieve the next catalog record, based on the PCDSN index. If a current position has not already been established, the results are undefined.
GP | Get Previous. If a current position has not already been established, the results are undefined.
GU | Get Unique. Retrieve the record associated with the DSN named in the interface area.
GUPC | Get Unique PCDSN. Retrieve the record associated with the PCDSN named in the interface data.
ISRT | Insert a new record into the catalog, using values provided in the interface area. If the associated physical file does not already exist, and the environment variable MFALLOC_PCFILE is not set to N, and the file location is the default allocated dataset location, allocate the associated physical file.
REN | Rename. Change the dataset name on an existing catalog record.
REPL | Replace. Update an existing catalog record using replacement values provided in the interface area. See Notes.
STN> | Start not greater than. Establish a position in the catalog determined by the value of the DSN field in the interface area. A record with this value need not exist.
STN< | Start not less than. Establish a position in the catalog determined by the value of the DSN field in the interface area. A record with this value need not exist.
STNE | Start Not Greater Than (as STN>) but switch Disable Additional Qualifiers on. This provides the same functionality as selecting Disable Additional Qualifiers on the ESMAC catalog listing page.
STNI | Start not greater than and ignore errors. Same as STN> but ignores catalog errors while listing records. At the end of the listing, use the GCFE call to retrieve any errors.

Notes:

If you are using wildcards to identify data sets on which to perform any of the above functions, and the data set name criteria is 44 characters or more, you should use the * wildcard as the first character of the criteria.

When updating the DSORG of a data set, using the REPL function, a check now verifies that the change is appropriate. If it is not, a return code of 20 and a reason code of 50 is produced.

Parent topic: Public Catalog API (MVSCATPB)
Related concepts
COBOL Requirements
Related reference
mfpubcat.cpy


Using the API for Catalog Error Reporting

When using the GCFS, GCFE, GNFS or GNFE function calls, the ()-CAT-FILE-STATUS-FIELDS is populated.

If a catalog file access error occurs during a call to the file, the MVSCATPB return code, ()-RETCODE, is populated with a value of 20, and the reason code, ()-RSNCODE, is populated with a value of 78-cat-file-access-error (46).

The ()-pc-dsn field contains the catalog file that gave the error, not the pc-dsn of the catalogued dataset record.

When the requested catalog number, ()-CAT-FILE-NUM, is greater than the number of catalogs, ()-NUM-CATS, reason code 78-invalid-cat-file-number is returned from the catalog file status calls.

Parent topic: Public Catalog API (MVSCATPB)


Sample Program

Presents a sample COBOL program that calls the Public Catalog API.

This sample program uses an input file to identify the catalog and to pass functions, dataset names, and member names. It also writes an output file containing the information retrieved from the catalog.

       IDENTIFICATION DIVISION.
       PROGRAM-ID.  TESTCNTL.
       AUTHOR.  MICRO FOCUS LTD.
       ENVIRONMENT DIVISION.
       INPUT-OUTPUT SECTION.
       FILE-CONTROL.
      *-----------------------------------------------------------
           SELECT INFILE
               ASSIGN TO IN-DSN
               ORGANIZATION IS LINE SEQUENTIAL
               FILE STATUS IN-STATUS.
          SELECT OUTFILE
               ASSIGN TO OUT-DSN
               ORGANIZATION IS LINE SEQUENTIAL
               FILE STATUS OUT-STATUS.
      *-----------------------------------------------------------
       DATA DIVISION.
       FILE SECTION.
       FD  INFILE
           LABEL RECORDS STANDARD.
       01  IN-REC.
           03  IN-COL1              PIC x.
           03  IN-FUNC              PIC x(4).
           03  FILLER               PIC x(4).
           03  IN-DSNAME            PIC x(44).
           03  FILLER               PIC x.
           03  IN-MEMBER            PIC x(8).
           03  FILLER               PIC x(18).
       FD  OUTFILE
           LABEL RECORDS STANDARD.
       01  OUT-REC              PIC X(500).

       working-storage section.
       01 IN-status              pic X(2).
       01 IN-dsn                 pic x(260).
       01 OUT-status             pic X(2).
       01 OUT-dsn                pic x(260).
       01 IN-REC-LEN             pic x(4) comp-x.

       01 ws-mfsyscat            pic x(255) value spaces.
      *---------------------------------------------------------------
       01 rec-type                pic x(8).
       01 field-name              pic x(15).
       01 field-value             pic x(50).
       01 field-value-len         pic xx comp-x.
       01 input-record-len        pic xx comp-x.

       01 string-start            pic xx comp-x.
       01 string-len              pic xx comp-x.

       01 ix                      pic xx comp-x.
      *----------------------------------------------------------------
       01  disp-retcode          pic 9(6).
       01  disp-rsncode          pic 9(6).
       01  disp-lrecl            pic 9(6).
       01  mvscatpb-pp           procedure-pointer.
       01  mvscatio-pp           procedure-pointer.
      *----------------------------------------------------------------
      *   parse catalog api fields
      *---------------------------------------------------------------
       01  CMD-PROCESSOR-PARM.
               10  CP-PARM-LEN         PIC 9(04) COMP.
               10  CP-PARM-STR         PIC X(4096).

      *----------------------------------------------------------------
      *   public catalog api fields
      *---------------------------------------------------------------
       01  PUBCAT-AREA.
       copy 'mfpubcat.cpy' replacing  ==()== by ==WS==.

       linkage section.
       procedure division.
           perform init-rtn
           perform main-process
           perform end-rtn
           goback.

       init-rtn section.
           set mvscatpb-pp to entry 'MVSCATPB'
           set mvscatio-pp to entry 'MVSCATIO'

           move length of in-rec   to in-rec-len
           move 'd:\visualstudio2010\projects\testcat\infile.dat'
                to in-dsn
           move 'd:\visualstudio2010\projects\testcat\outfile.dat'
                to out-dsn
           perform open-infile
           perform open-outfile

           exit section.

       main-process section.
           perform read-infile
           perform until in-status <> '00'
               evaluate in-rec (1:1)
               when '*'
                   continue        *> comment
               when space
                   move low-values to pubcat-area
                   move in-func    to ws-func
                   move in-dsname  to ws-dsname
                   move in-member  to ws-member
                   perform call-pub-api
                   perform build-string
                   perform write-outfile
               when 'C'
                   perform set-mfsyscat
               end-evaluate
               perform read-infile
           end-perform

           exit section.

        set-mfsyscat section.
            move    in-rec (2:79)          to ws-mfsyscat
            DISPLAY 'MFSYSCAT'             UPON ENVIRONMENT-NAME
            DISPLAY ws-mfsyscat            UPON ENVIRONMENT-VALUE

           exit section.

        call-pub-api section.
           call 'mvscatpb' using  pubcat-area
           exit section.

        build-string section.
           move spaces to out-rec
           move ws-rsncode to disp-rsncode
           move ws-retcode to disp-retcode
           move ws-lrecl   to disp-lrecl
           string
                 ' return code '        delimited by size
                 disp-retcode           delimited by size
                 ' reason code '        delimited by size
                 disp-rsncode           delimited by size
                 ' dsname '             delimited by size
                 ws-dsname              delimited by spaces
                 ' member '             delimited by size
                 ws-member              delimited by spaces
                  ' dsorg '             delimited by size
                 ws-dsorg               delimited by size
                 ' recfm '              delimited by size
                 ws-recfm               delimited by size
                  ' lrecl '             delimited by size
                 disp-lrecl             delimited by size
                 into out-rec
           exit section.

       end-rtn section.
           close infile
           close outfile

           exit section.

      *----------------------------------------------------------------
      * routines for accessing the files
      *----------------------------------------------------------------
       open-infile section.
           open input infile
           evaluate in-status
               when '00'
                   continue
               when other
                   DISPLAY 'OPEN infile FAILED '
                           in-status
                   goback
           end-evaluate
       exit section.

       open-outfile section.
           open output outfile
           evaluate out-status
               when '00'
                   continue
               when other
                   DISPLAY 'OPEN outfile FAILED '
                           out-status
                   goback
           end-evaluate
       exit section.

       read-infile section.
           read infile
           evaluate in-status
               when '00'
               when '10'
                   continue
               when other
                   DISPLAY 'read infile FAILED '
                           out-status
                   goback
           end-evaluate
       exit section.

       write-outfile section.
           write out-rec
           evaluate out-status
               when '00'
                   continue
               when other
                   DISPLAY 'write outfile FAILED '
                           out-status
                   goback
           end-evaluate
       exit section.

       error-rtn section.
           continue
       exit section.
Parent topic: Public Catalog API (MVSCATPB)
Related concepts
COBOL Requirements
Related reference
mfpubcat.cpy
Calling MVSCATPB


Debug or Run the Program

Describes how to debug or run a program that calls the Public Catalog API.

Debug or Run a Program in Enterprise Server

To make any updates to the catalog, you must run your program in Enterprise Server.

From your Enterprise Developer Project

  1. In Enterprise Developer, create a program using either the Enterprise Server Application template, or the Mainframe Subsystem Application template.
  2. In the Enterprise Developer project, create and build a program that accesses the catalog.
  3. In Enterprise Server, create an enterprise server instance to run your program.
  4. Associate your enterprise server instance with your Enterprise Developer project.
  5. Debug or run the program in Enterprise Developer.

From Enterprise Server

  • In Enterprise Developer, create a project using any appropriate project template.
  • In the Enterprise Developer project, create and build a program that accesses the catalog.
  • Write JCL to execute the program.
  • In Enterprise Server, create an enterprise server instance to run your program.
  • In Enterprise Server, execute the JCL.

Debug or Run a Program Outside of Enterprise Server

If your program does not update the catalog and was not created with the Enterprise Server Application or the Mainframe Subsystem Application template, simply create and build the program in Enterprise Developer, and then execute or debug it from the project, or from an Enterprise Developer command prompt.

Parent topic: Public Catalog API (MVSCATPB)
Related reference
Reason Codes
Return Codes


Return Codes

Describes the return codes produced by the Public Catalog API.

Use these return codes in conjunction with their accompanying reason codes to determine the cause for problems or failures when calling the Public Catalog API.

Code | Description
0 | Success.
4 | A record was not found in the system catalog, but it was found in a user catalog.
8 | Call completed with a warning; for example, when an insert is performed on a key that is already present, an update is performed instead.
12 | A call attempted to delete a catalog record for a key that was not found.
16 | Unsuccessful call.
20 | Unsuccessful call due to a validation error.
Parent topic: Public Catalog API (MVSCATPB)
Related reference
Calling MVSCATPB
Reason Codes
Debug or Run the Program
Setting Environment Variables


Reason Codes

Reason codes describe the reason for a non-zero return code from the Public Catalog API.

All reason codes are documented in the mfpubcat.cpy copybook, in a section labeled reason codes. For example:

...
      *=================================================================
      *    reason codes
      *=================================================================
           78  78-REC-NOT-FOUND              VALUE 001.
           78  78-INVALID-DYN-PDS            VALUE 002.
           78  78-INVALID-CATALOGED-FLAG     VALUE 003.
...

Match the returned reason code value to that of a 78-level field in the copybook. The field name provides the reason for the code.

Parent topic: Public Catalog API (MVSCATPB)
Related reference
mfpubcat.cpy
Calling MVSCATPB
Return Codes
Debug or Run the Program


Writing Your Own Utility Programs

You might need to write your own utility programs or obtain them from other software vendors. MSS passes a standard MVS parameter area to these programs when they are invoked by TSO commands or JCL statements.

For a COBOL program, the parameter area has the following definition:

01 PARM.
      03 PARM-LENGTH         PIC 9(4)COMP.
      03 PARM-DATA.
         05 PARM-DATA-ARRAY  PIC X OCCURS 100.

PARM-DATA contains the data specified in the parameter field of the TSO command or JCL statement. MSS converts it to the default data representation defined for your system - ANSI or EBCDIC. The utility program should inspect the parameter data, determine its data representation and convert it, if necessary, to the representation used by the program.

Important: The utility program must be compiled within your COBOL development system to ensure that all interactions with the system are handled correctly.

For a PL/I program, the parameter area can be declared as CHAR(100) VARYING, or a structure equivalent to the COBOL definition.

Parent topic: Utility Programs


MVS Emulation

  • MVS Control Blocks
  • MVS External Writer
  • DSNALI Functionality
  • DSNRLI Functionality
Parent topic: JCL Support


MVS Control Blocks

MSS emulates those MVS control blocks that are accessible to applications running in problem program state. The information stored in these control blocks is limited to that which has value and meaning to applications running in problem program state.

The MVS control blocks are constructed using the default program attributes of the SSTM, which are a mainframe dialect, AMODE(31), and a character set derived from the value of the environment variable MF_CHARSET. If this variable is not set, then a value of ASCII is used. This means that the pointers to the sub-block areas are in mainframe format, rather than native format.

Control blocks are accessed in MSS in the same way as they are on a mainframe, by referencing the appropriate field in the Communication Vector Table (CVT). The address of the CVT is stored at absolute address 16 in memory, as it is on the mainframe.

  • Low-memory Address Emulation in Assembler and COBOL
  • Control Blocks Supported
  • Accessing MVS Control Blocks from COBOL Programs
Parent topic: MVS Emulation


Low-memory Address Emulation in Assembler and COBOL

On the mainframe the prefixed save area (PSA) is mapped at absolute location 0. Many application programs access its contents. We provide software that allows your COBOL programs to access it as if they were running on the mainframe.

Parent topic: MVS Control Blocks


Control Blocks Supported

The table below lists the MVS control blocks that are emulated by MSS and specifies any differences between the non-mainframe versions and the mainframe versions.

Name | Description | Differences from mainframe
IHAACEE | Accessor Control Element | ACEEVRSN is set to 2
IHAASCB | Address Space Control Block
IHAASVT | Address Space Vector Table
IHAASXB | Address Space Extension Block
CVT Communication Vector Table CVTTOD is set to X'20', indicating that the Time Of Day clock is operational.

CVTMVSE - the X'80' bit in CVTDCB is always on, indicating that you are running under MVS/XA or later.

CVT4MPS - the X'04' bit in CVTDCB is on (indicating that you are running on System/360 Model 65 MP) only if the MVS control blocks are above the 16MB line (that is, all three-byte addresses are stored as four-byte addresses in the same location).

CVTDATE is set with the century number (that is, it uses "0cyyddds" format, where "c" is century number - 0 for 20th, 1 for 21st, etc.)

CVT | CVT Prefix | The CVT prefix is set to all binary zeros.
IHACDE | Contents Directory Entry | One "null" CDE is allocated. So it appears to be using a program for which the load module has not been loaded.
IDADDSA | Dynamic Storage Area (FSA - First Save Area) | This is an 88-byte save area pointed to by TCBFSA. It is used as the TCB First Save Area.
IEFJFCBN | Job File Control Block
IEZJSCB | Job Step Control Block
IHAPSA | Prefixed Save Area | The X'01' bit in byte 7 (the first byte being byte 0) is on only if the MVS control blocks are above the 16MB line (that is, all three-byte addresses are stored as four-byte addresses in the same location).
IEESMCA | SMF Control Area | SMCASID is set to 'MSTR'.
IDADTCA Task Communication Area

The PRV address is always zero.

The storage overflow routine does not provide overflow segments; it merely abends with the abend code S80A. You must ensure that the ISA setting is adequate for your application.

IDADTCA | TCA Prefix
IKJTCB | Task Control Block | The TCB protect key is set to key 8.
IEFTIOT1 | Task I/O Table | A maximum of 256 TIOT entries (representing the first 256 DDs in the job step) are supported.
Parent topic: MVS Control Blocks


Accessing MVS Control Blocks from COBOL Programs

MSS enables you to access MVS control blocks from a COBOL program. The following sample program shows how you can access the job, step, and program names for the currently running program.

Note: To run this program and its parent, you must compile them with the AMODE"31" (and by default DATA"31") compiler directive.
 IDENTIFICATION DIVISION.
 PROGRAM-ID. JOBINFO.

 DATA DIVISION.
 WORKING-STORAGE SECTION.
 01 JOB-NAME             PIC X(8).
 01 PROGRAM-NAME         PIC X(8).
 01 STEP-NAME            PIC X(8).

 LINKAGE SECTION.
 01 PSA.
    05 FILLER     PIC X(540).
    05 PSATOLD    POINTER.

 01 TCB.
    05 FILLER     PIC X(12).
    05 TCBTIO     POINTER.
    05 FILLER     PIC X(164).
    05 TCBJSCBB   POINTER.

 01 TIOT.
    05 TIOCNJOB   PIC X(8).
    05 TIOCSTPN   PIC X(8).

 01 JSCB.
    05 FILLER     PIC X(360).
    05 JSCBPGMN   PIC X(8).

 PROCEDURE DIVISION.
*    Address PSA
     SET ADDRESS OF PSA TO NULL

*    Address TCB
     SET ADDRESS OF TCB TO PSATOLD

*    Address TIOT
     SET ADDRESS OF TIOT TO TCBTIO

     MOVE TIOCNJOB TO JOB-NAME
     MOVE TIOCSTPN TO STEP-NAME

*    Address JSCB
     SET ADDRESS OF JSCB TO TCBJSCBB

     MOVE JSCBPGMN TO PROGRAM-NAME
     DISPLAY 'JOB NAME     = ' JOB-NAME
     DISPLAY 'STEP NAME    = ' STEP-NAME
     DISPLAY 'PROGRAM NAME = ' PROGRAM-NAME
     GOBACK
     .
Parent topic: MVS Control Blocks


MVS External Writer

Under MVS you can run a program that dynamically outputs a JCL job stream in the form of a SYSOUT data set, and you can specify that an external writer is to process the job stream. You can use the IBM-supplied external writer, INTRDR, or you can supply your own.

You can request an external writer in any of the following ways:

  • In JCL. The name of the external writer is a parameter in the DD statement for the SYSOUT data set
  • In a TSO ALLOCATE command
  • By issuing the DYNALLOC (SVC 99) service

MSS emulates the IBM-supplied external writer, INTRDR. It does not support user-supplied external writers.

The MSS emulation of INTRDR differs in the following ways from IBM's INTRDR:

  • IBM's INTRDR allows a program to submit a job without closing the data set, by writing records that contain control statements such as /*EOF, /*DEL, /*PURGE, and /*SCAN. Each of these statements effectively indicates that all data up to the statement is one or more complete jobs and that the action indicated by the statement should be carried out, for example, /*EOF causes the job to be submitted and is therefore equivalent to closing the data set. However, with the MSS emulation of INTRDR, the program must write an entire jobstream to the SYSOUT data set and then close the data set; the job is then submitted for execution. The program may then reopen the SYSOUT data set, write another complete jobstream and then close the data set for job submission.
  • IBM's INTRDR supports multiple jobs in one jobstream, regardless of whether the submission is triggered by a control statement or by the closing of the data set. The MSS emulation of INTRDR does not support multiple jobs in one submission, since MSS itself cannot handle such jobs. Each submission must contain only one job.
  • With IBM's INTRDR, the class of the submitted job defaults to the class of the SYSOUT data set. With the MSS emulation of INTRDR, the class of the submitted job is the same as it would be if the job were submitted without a class being specified.
  • You cannot request an external writer by issung the DYNALLOC (SVC 99) service
Parent topic: MVS Emulation


DSNALI Functionality

You use the DB2 Call Attach Facility (CAF) to access DB2 subsystems and the data they manage. You do this by calling DSNALI with the appropriate series of functions. The MSS emulation of this facility behaves exactly as on the mainframe, with the following exceptions:

  • CONNECT function.
    • The subsystem parameter (parameter number 2) must be present but is otherwise ignored.
    • The termination Event Control Block (ECB) parameter (parameter number 3) must be present but is otherwise ignored. This ECB is never posted.
    • The starting ECB parameter (parameter number 4) must be present but is otherwise ignored. This ECB is never posted.
    • The Release Information Block (RIB) pointer (parameter 5) must be present and is set to point to a constant value which contains items such as an eye-catcher "RIB" and the DB2 subsystem release number of 710 (for DB2 V7.1.0).
  • OPEN function.
    • The subsystem parameter (parameter number 2) must be present but is otherwise ignored.
  • TRANSLATE function.
    • No translation is performed. In the SQLCA, SQLCODE is always set to -924, and SQLSTATE is always set to 58006.
Parent topic: MVS Emulation


DSNRLI Functionality

  • DSNRLI Overview
    Explains the implementation of DSNRLI functionality in Enterprise Developer.
  • DSNRLI Functions used for RRSAF
    Describes the DSNRLI functions that can be used to interface with RRSAF.
  • DSNRLI Work Unit Functions
    Shows the DSNRLI functions used for connecting and performing database commits.
  • DSNRLI Error Reporting
    Explains how errors are reported when a DSNRLI function errors.
  • Limitations Using Micro Focus DSNRLI
    Details limitations and restrictions when using DSNRLI.
Parent topic: MVS Emulation


DSNRLI Overview

Important: It is strongly recommended that only dynamically registered XA switch modules are used with DSNRLI. If statically registered switches must be used, please ensure that a SRRCMIT or SRRBACK call occurs before a TERMINATE THREAD call. This is required as the DSNRLI implementation has no state knowledge of static RM participation in the global transaction.

DSNRLI is the language interface load module for the DB2 Resource Recovery Services attachment facility (RRSAF). It provides the interface to RRSAF only through the DSNRLI entry point. This entry point provides explicit service connection requests for any XA resource, including WebSphere MQ.

The interface is separate from the mainframe version of RRSAF, which provides closer control over DB2 connections. The interface is designed to provide the necessary functions to help ease application migration.

On the mainframe, the RRSAF language interface module (DSNRLI) is an extension to DB2 and, when used by a program, all DB2 SQL calls pass through one of its entry points, DSNHLIR. However, IBM's RRSAF is not available in DB2 LUW. Micro Focus provides its own version of this module to ease migration of customer applications. However, because it is not part of DB2, it does not provide all of the functions that the mainframe version does.

The Call Attachment Facility (CAF) DSNALI interface provides basic DB2 connection control functions: Connect, Open, Close etc.

In addition to the functions used to call transaction processing APIs, the Micro Focus DSNRLI functionality provides the Common Program Interface - Communications (CPIC) utility functions SRRCMIT (commit) and SRRBACK (rollback)

You can use either the appropriate XA resource COMMIT statement or the CPIC SRRCMIT function to commit work to RRSAF applications. Likewise, you can use either the appropriate XA resource ROLLBACK statement or the CPIC SRRBACK function to roll back work.

Use appropriate XA resource COMMIT and ROLLBACK statements if:

  • The only recoverable resource your application accesses is data that is managed by a single XA resource.
  • The address space where syncpoint processing initiates is the same as the address space of your application.

Use CPIC SRRCMIT and SRRBACK functions if:

  • Your application accesses other recoverable resources, or syncpoint processing and XA resource access are initiated from different address spaces.
  • You are using multiple XA Resources. Use DSNRLI to link those resources to your unit of work and then use SRRCMIT/SRRBACK to commit or rollback work changes.
Parent topic: DSNRLI Functionality


DSNRLI Functions used for RRSAF

DSNRLI is typically used as part of a SQL process to connect, open, execute SQL calls, commit or rollback changes, close and disconnect.

Any specified function parameters are read and stored. However, the only parameter used is the subsystem name, which equates to an XA Resource label. Refer to your IBM documentation for details of parameters for each function,

This table describes the DSNRLI functions that can be used to interface with RRSAF.

Function | Description
IDENTIFY | Initializes an XA resource's connection.
SIGNON | Establishes a primary authorization ID and can also establish one or more secondary authorization IDs for a connection.
CREATE THREAD | Allocates the XA resources that are required for an application to issue SQL or IFI requests. This function must complete before the application can execute SQL statements or IFI requests.
SWITCH TO | Directs RRSAF, SQL, or IFI requests to a specified XA resource's subsystem. Use the SWITCH TO function to establish connections to multiple XA resource subsystems from a single task. DSNRLI also provides functions for switching between different subsystems using the SWITCH TO function. On the mainframe, this function directs subsequent SQL calls to the subsystem specified using the ssnm parameter. Use this SWITCH TO followed by IDENTIFY, SIGNON and CREATE THREAD to associate and open another XA Resource. This prevents subsequent SQL from being directed to that resource. The direction is provided by existing SQL functionality. SWITCH TO tells DSNRLI which resource the next calls apply to.
TERMINATE THREAD | Deallocates XA resources that are associated with a plan and were previously allocated for an application using CREATE THREAD. You can then use CREATE THREAD to allocate another plan with the same connection.
TERMINATE IDENTIFY | Terminates an XA resource's connection. Calling the TERMINATE IDENTIFY function is optional. If you do not call it, DSNRLI performs the same functions when the task terminates.
SRRCMIT (CPIC) | Make all changes permanent (or committed) for the current logical unit of work. When a commit operation completes successfully, the changes to all protected resources associated with that logical unit of work are made permanent, and the updates are made available to other users of the protected resources.
SRRBACK (CPIC) | Used to return the protected resources in a logical unit of work to their respective states at the previous sync point. When you request the backout operation, all changes made to protected resources since the last synchronization point are discarded.
Parent topic: DSNRLI Functionality


DSNRLI Work Unit Functions

DSNRLI is typically used as part of the SQL process to connect, open, execute SQL calls, commit, rollback, close, and disconnect. However, the Micro Focus DSNRLI functions used in this process are shown in the table:

Process | DSNRLI Function | tx_CALL
Connect | IDENTIFY | tx_associate
 | SIGNON | tx_open
Open | CREATE THREAD | tx_begin
Commit | SRRCMIT | tx_commit
Rollback | SRRBACK | tx_rollback
Close | TERMINATE THREAD | tx_end, tx_close
Disconnect | TERMINATE IDENTIFY | none

For user executed SQL calls, use existing SQL architecture.

Multiple XA Resources can be used in a single unit of work. In those cases, the application should use DSNRLI IDENTIFY, SIGNON and CREATE THREAD calls to associate each additional XA Resource.

Parent topic: DSNRLI Functionality


DSNRLI Error Reporting

DSNRLI errors are reported back to the calling program, the dsnrli.cpy copybook contains a list of error and reason codes that are returned.

If a DSNRLI function is called that requires the association of an XA switch module with the current unit of work, and that association fails, DSNRLI will issue the following messages and shows the return code from the TX Associate call:

Reason | Error
For a failure in associating the switch module: | MVSXM0037S [Switch Module] XA resource is not enabled. ASSOCIATE call returned [Return Code].
For a switch module that does not exist | MVSXM0038S [Switch Module] XA resource has not been found. ASSOCIATE call returned [Return Code].

In both cases, DSNRLI will return a return-code of 8, and the reason code will be ERR-XA-RESOURCE-NOT-ENABLED (0x00F30002) or ERR-NOT-IDENTIFIED (0x00C12204), as appropriate.

If DSNRLI makes a TX call that does not return the expect value, the return code will be reported in a message to the job log and the return code from DSNRLI is be 8. The reason code reflects where the error occurred.

Error
MVSXM0050S [Switch Module] XA resource OPEN call returned [Return Code].
MVSXM0051S [Switch Module] XA resource BEGIN call returned [Return Code] where [Switch Module] is the XA resource name and [Return Code] is the return code from the TX call.
MVSXM0052S [Switch Module] XA resource CLOSE call returned [Return Code].
MVSXM0053S [Switch Module] XA resource END call returned [Return Code].

Where [Switch Module] is the XA resource name and [Return Code] is the return code from the TX call.

Parent topic: DSNRLI Functionality


Limitations Using Micro Focus DSNRLI

Using the Micro Focus implementation of DSNRLI has these limitations and restrictions:

  • The Micro Focus implementation of DSNRLI is not technically an extension of the XA specification, so it does not provide some of the functions the mainframe version does. Those not implemented include:
    • SIGNON
    • AUTH SIGNON
    • CONTEXT SIGNON - The connection details, including user ID, are included in the XA resource definition in Enterprise Server. Direct calls or SQL application handling calls are not made to the database. so these are no-operation calls.
    • SET_ID
    • SET_CLIENT_ID - See CONTEXT SIGNON.
    • FIND_DB2_SYSTEMS - A function to search DB2 systems is not needed since the required systems and XA resources are defined in the Enterprise Server configuration.
    • (Implicit connections) - On the mainframe, if the IDENTIFY, SIGNON, CREATE THREAD sequence is not called before the first EXEC SQL call, then DSNRLI performs an implicit connection. In this implementation, since DSNRLI is not aware of the EXEC SQL calls, it does not make an implicit connection. The application must make explicit calls to DSNRLI to associate specific XA resources with a unit of work.
    • DSNHLI, DSNHLR - The entry points for making SQL calls are not used. The applications must make EXEC SQL calls and use existing SQL functionality.
    • DSNWLI, DSNWLIR - The entry points for making Instrumentation Facility Interface (IFI) calls are not used, since the IFI is not available.
  • An issue with DB2 LUW prevents jobs that include 1 Phase Commit (1PC) programs from running after a 2 Phase Commit (2PC) program using DSNRLI has run in the same initiator. That is, programs that run under IKJEFTxx or use DSNALI fail if a DSNRLI program using the same DB2 Switch Module has previously run in the same initiator. A symptom of the problem would be a message sequence such as:
    JCLCM0188I JOB01001 MFIAFN2  JOB  STARTED
CASXO0001S XA Resource Manager initialization error. Resource DSN open failed, reason -00003
CASXO0016S DSN XA interface initialization failure
MVSXM0036S JOB01001 MFIAFN2  Database OPEN call failed "PROGRAM NAME"

    where MFIAFN2 is a job with a IKJEFT01 step using 'DSN SYSTEM(DSN)' and a program using DSNRLI and the same XA Resource (DSN) had previously run in the same initiator.

    To address this issue, append TOC=P to the open string specified in the XA resource configuration in Enterprise Server region settings. For example, the correct open string is DB=SAMPLE,UID=admin,PWD=passwd,TOC=P.

Parent topic: DSNRLI Functionality


Micro Focus Batch Scheduler Integration

This section explains how to use the Micro Focus Batch Scheduler Integration solution to allow feedback between Enterprise Server and a scheduler that controls JCL job execution.

  • Introduction
  • MFBSI Architecture
  • Supported Platforms
  • Components
  • Configuring the Server
  • The MFBSI Configuration File
  • MFBSIJCL Submit Process
  • Job Restart
  • Sending Alerts to the Scheduler
  • JCL Parameter Substitution
  • User Exit Before Submission to Enterprise Server/JCL
  • Additional Notes
Parent topic: JCL Support
Related concepts
External Features
ESMAC
Related information
POWER Statements


Introduction

To submit and start a JCL job to Enterprise Server, you execute the CASSUB command with the appropriate parameters. However, by design CASSUB only provides notification on the proper submission of the job to Enterprise Server if the JCL job syntax contains no errors. CASSUB can also end with a return code and output only to standard output (STDOUT).

If no initiator is available in Enterprise Server, the job is never executed. If an initiator is available, the job may fail with a JCL error such as data set not found, or with a User, SYS, or RTS error in a program step execution.

Whether the job ends successfully of not, when using a scheduler to submit and control Enterprise Server/JCL job execution, there is no mechanism to provide communication or feedback between the job execution and Enterprise Server. You can submit and monitor JCL jobs activity using Enterprise Server, but this requires manual intervention.

The Micro Focus Batch Scheduler Integration (MFBSI) provides this functionality, allowing for submission, execution and communication between JCL job execution in Enterprise Server and the scheduler.

Parent topic: Micro Focus Batch Scheduler Integration


MFBSI Architecture

For MFBSI usage, the scheduler launches a COBOL program named MFBSIJCL, which executes CASSUB/CASOUT commands. MFBSIJCL then communicates with Enterprise Server/JCL using the Event Manager user exit MFBSIEMX.

MFBSIJCL waits for Enterprise Server/JCL job execution to end. It then returns the JCL Job return code or a specific return code to the scheduler.

Communication between MFBSIJCL and MFBSIEMX is done through a semaphore file named JOBnnnnn.Sem, where nnnnn is the job number assigned by Enterprise Server/MSS JCL. These files are located in a folder shared by all MFBSIJCL instances and by MFBSIEMX. The environment variable MFBSI_DIR specifies this folder. If multiple Enterprise Server/MSS JCL server are used, each one requires its own MFBSI_DIR settings unless Enterprise Server clustering is used.

MFBSIEMX creates a zero byte file when Enterprise Server/JCL starts the job execution and adds a record containing the JCL return information when the job ends.

MFBSIJCL waits for the job start which creates JOBnnnnn.Sem, then for the job end in Enterprise Server/MSS, which updates JOBnnnnn.Sem. When ended, MFBSIJCL stops execution with the return code read from JOBnnnnn.Sem. See the topic on how MFBSIJCL handles return codes for more information.

Using this technique, MFBSIJCL and Enterprise Server can run on different machines and even on different operating systems. Only a file share between machines is required. For example, the scheduler agent can run under Windows, launch MFBSIJCL with the appropriate parameters to submit the job to a machine running UNIX. The MFBSIJCL process run under Windows can monitor any directory residing on the UNIX machine using a network share utility such as Samba.

MFBSIJCL includes a timeout mechanism to prevent an instance from running infinitely without feedback. An alert can be sent to the scheduler if a either a startup or run timeout is detected. The alert calls an appropriate action in ESMAC SEE Web Administrator.

  • If the job is cancelled, MFBSIJCL receives notification and sends that information to the scheduler.
  • If Enterprise Server/MSS JCL is not properly stopped, or do not retrieve any events, MFBSIJCL terminates with the appropriate return code, which is usually 225, 228 or 229.

MFBSIJCL may use a user exit MFBSIALR to send an alert to the scheduler. You must customize and compile/link MFBSIALR for a specific scheduler interaction. A skeleton program for MFBSIALR is available in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows), or $COBDIR/cpylib (UNIX/Linux).

Parent topic: Micro Focus Batch Scheduler Integration


Supported Platforms

MFBSI can be used on all the platforms supported by Enterprise Server/Enterprise Developer. 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.

As long as a shared folder can be defined, the scheduler can submit MFBSIJCL on one platform for execution of a JCL in MSS to another platform.

Parent topic: Micro Focus Batch Scheduler Integration


Components

MFBSI consists of the following components:

  • The user exit program for Enterprise Server/MSS Event Manager process (MFBSIEMX).
  • The trigger program launched by the scheduler to submit jobs to Enterprise Server/MSS JCL (MFBSIJCL).
  • A sample user-exit program for MFBSIJCL, used to send time-out alerts to the scheduler (MFBSIALR).
  • A sample user exit sample program that can modify the JCL file before submission (MFBSIUE1).
  • A sample user exit program that can be invoked just before MFBSIJCL termination (MFBSIUE2).
  • A configuration file model for MFBSIJCL (mfbsi.cfg).
  • MFBSIJCL
  • MFBSIEMX
Parent topic: Micro Focus Batch Scheduler Integration


MFBSIJCL

MFBSIJCL.exe (Windows) or mfbsijcl (UNIX/Linux) must be available on the system where the scheduler launches its jobs. At a minimum, the Micro Focus COBOL run-time system modules must also be accessible and configured on this system.

In Windows, start MFBSIJCL with the command MFBSIJCL commandLineParameters . In UNIX/Linux, start it with the command mfbsijcl commandLineParameters.

Tip: The command name mfbsijcl in UNIX/Linux is case sensitive.
Parent topic: Components


MFBSIEMX

This module is packaged as a .dll file in Windows, and as an .so file in UNIX/Linux. The module is loaded and initialized at region startup.

Parent topic: Components


Configuring the Server

The MFBSIEMX module must be defined as an Event Manager user exit and the variable MFBSI_DIR must be specified similar to that shown in the Configuration Information field as shown next:

Where:

  • ES_EMP_EXIT_n - n must be a number ranging from 1 to 9, based on the number of Event Manager user exits for the region:
    • This should be set to 1 if MFBSIEMX is the only Event Manager user exit for the region.
    • When multiple Event Manager user exits are defined, they must be specified in a sequence starting with ES_EMP_EXIT_1 - for example:
      ES_EMP_EXIT_1=mfbsiemx
ES_EMP_EXIT_2=mfmonemx
ES_EMP_EXIT_3=...
  • mfbsiemx must be in lowercase on UNIX and Linux environments.
  • MFBSI_DIR identifies the base folder to be used by MFBSI. This is the folder where the MFBSIJCL log files, any semaphore files (JOB#####.sem) and substituted JCL members are written into.

The MFBSIJCL component that is submitting jobs to the enterprise server requires the MFBSI_DIR environment variable with the same folder setting.

There are two ways to specify MFBSI_DIR for a specific enterprise server region:

  • By specifying a folder that has the name of enterprise server region as the last part of the MFBSI_DIR path - this is the Micro Focus-recommended way and the easiest way to configure MFBSI_DIR.
    Note: This was the only way to configure MFBSI_DIR in previous releases of this product. Starting with the 3.0 release of Enterprise Developer and Enterprise Server, this constraint has been relaxed.

    Alternatively:

  • You can set MFBSI_DIR to any path on your file system. In this case, you must specify the target region name either on the MFBSIJCL command line (by specifying REGION=ESRegionName) or in the configuration file (on a line that starts with REGION=ESRegionName).

See the following examples of how to specify MFBSI_DIR:

Important:
  • Ensure that the Enterprise Server admin user and the user authority which runs MFBSIJCL have a write access to the MFBSI_DIR location.
  • MFBSI_DIR supports long and spacey folder names. However, Micro Focus recommends that you avoid them.

Micro Focus recommends that you use the default settings for MFBSIJCL to specify the region name as part of MFBSI_DIR:

To set MFBSI_DIR to a path that ends up with a folder that has the same as the enterprise server region name and with the default settings for MFBSIJCL:

On Windows:

set MFBSI_DIR=x:\MF\…\MFBSI\ESRegionName

On UNIX:

export MFBSI_DIR=/MF/…/MFBSI/ESRegionName

To set MFBSI_DIR to any folder:

  1. To specify the region name at the MFBSIJCL command line, execute:

    On Windows:

    set MFBSI_DIR=x:\MF\...\MYDIR
mfbsijcl ...  REGION=ESRegionName

    Or, on UNIX:

    export MFBSI_DIR=/MF/.../MYDIR
mfbsijcl ...  REGION=ESRegionName
  2. To specify the region name in the default mfbsi.cfg file:
    1. Ensure mfbsi.cfg includes the following line:
      REGION=ESRegionName
    2. Set MFBSI_DIR to the location of mfbsi.cfg:

      On Windows:

      set MFBSI_DIR=x:\MF\...\MYDIR

      Or, on UNIX:

      export MFBSI_DIR=/MF/.../MYDIR
  3. To specify the region name in a custom configuration file, custom.cfg, located in x:\MF\...\MFBSICFG\ (Windows) or /MF/.../MFBSICFG/ (UNIX):
    1. Ensure custom.cfg includes the following line:
      REGION=ESRegionName
    2. Set MFBSI_DIR as follows:

      On Windows:

      set MFBSI_DIR=x:\MF\...\MYDIR

      Or, on UNIX:

      export MFBSI_DIR=/MF/.../MYDIR
    3. Specify the custom configuration file when executing MFBSIJCL as follows:

      On Windows:

      mfbsijcl ... CFG=x:\MF\...\MFBSICFG\custom.cfg

      Or, on UNIX:

      mfbsijcl ... CFG=/MF/.../MFBSICFG/custom.cfg

      Or, without specifying the CFG parameter:

      On Windows:

      mfbsijcl ...
export MFBSI_CFG=x:\MF\...\MFBSICFG\custom.cfg

      Or, on UNIX:

      mfbsijcl ...
export MFBSI_CFG=/MF/…/MFBSICFG/custom.cfg

After making these settings in the region configuration, restart the server and check the console log for the message CASAM3006I/CASAM3001I to verify successful initialization of MFBSIEMX. Log entries are similar to:

CASAM3006I Event Filter for (mfbsiemx) has been enabled. Filter string: "1:1,3&3:*&4:1,2"
CASAM3001I Event Manager exit enabled (mfbsiemx)

Server initialization creates a file named ESRegionName.Started in the MFBSI_DIR location. When the server shuts down, a file named EESRegionName.Shutdown replaces this file (where ESRegionName is the name of the region being used.

In order to restart any submitted jobs, you need to add some additional configuration settings in your enterprise server instance - see Job Restart.

Parent topic: Micro Focus Batch Scheduler Integration


The MFBSI Configuration File

To simplify scheduler configuration, you can store most MFBSIJCL command line parameters for a given Enterprise Server with Mainframe Subsystem Support in a configuration file. Storing parameters in a configuration file also means that potentially the only parameter you need in order to execute MFBSIJCL on a command line is the JCL member name.

By default, the name of the configuration file is mfbsi.cfg and it resides in the location specified by the MFBSI_DIR environment variable. You can change the default location and the file name as needed with the CFG=... command line parameter, or by setting a value for the MFBSI_CFG environment variable.

A template of the configuration file, named mfbsi.cfg_model, is in the <install-directory>\etc folder (Windows), or the $COBDIR/demo/mfbsi folder (UNIX, Linux).

That directory also contains a simple JCL file,rc08.jcl, that invokes IDCAMS. You can use this JCL with MFBSI for your initial tests.

Format of the mfbsi.cfg file

  • An asterisk (*) or a semi-colon (;) in position 1 of a line indicate a comment. To enable a parameter defined in the file, delete the comment symbol and specify a suitable value for the parameter.
  • Any blank lines in the file are ignored.
  • Parameter names are not case sensitive.
  • “Keyword” parameter values are case insensitive. Other parameter values may be case sensitive, especially with directory extensions on UNIX and Linux platforms.
  • If a parameter is defined both in the configuration file and on the command line, the command line definition takes precedence.
  • Some special parameters are only available from the configuration file and cannot be directly used from the command line.
  • If you use the access codes -j or -x on the MFBSIJCL command line, the values of the configuration parameters JCL-Submit and JCL-Ext in mfbsi.cfg are ignored.

When you use a configuration file, the minimum execution command line parameter you need to specify for mfbsijcl is the name of the JCL file to submit with or without the extension. In this case, specify the following parameters in mfbsi.cfg:

  • ES-Server=... - specifies how to access the enterprise server region (using -r, -l, or –sTCP)
  • JCL-Submit=... - -j/-xJCLpathLocation
  • JCL-Ext =… - extension to be used, if not specified in the command line parameter, referring to the JCL file
  • SJobID=JobNo|StdOut|JCL
  • JESYSMSG, if you need to retrieve the JCL JESSYSMSG execution log
  • REGION=… - the target region name when using a custom MFBSI_DIR

The template configuration file includes a list of the parameters you can use:

To access an enterprise server with Mainframe Subsystem support and specify its name and location:

ES-Server=-rES-JCL

ES-Server=-sTCP:10.1.1.101:32793

ES-Server=-sTCP:HostName:32793

ES-Server=-lES-SERV

To submit a JCL file (-x or –j) and specify the path to the JCL member directory:

JCL-Submit=-jPathToJCLfile

JCL-Submit=-xPathToJCLfile

Note:
  • Do not use double quotes for directory names that include spaces.
  • PathToJCLfile can use one or more references to environment variables. In this case, you need to prefix the environment variable with a $. For example: JCL-Submit=-x$SEE_JCL_BASE/$JCL_PDS.
  • The environment variables SEE_JCL_BASE and JCL_PDS will be substituted with their respective values.

When using a custom MFBSI_DIR setting (the last part of the MFBSI_DIR path does not specify the region name):

REGION=RegionName- where RegionName is the target enterprise server region name

To specify the JCL file extension to add to the JCL member name specified on the command line:

JCL-Ext=jcl.

The default is 'nothing to add' . You should not specify the period (".") before the extension.

To specify the startup timeout in seconds before issuing an alert:

StartupTimeout=300

To specify the run timeout in seconds before issuing an alert:

RunTimeout=600

To specify the alert back elapsed time in seconds:

AlertBackTimeout=600

To avoid stopping the MFBSIJCL execution when the enterprise server is stopped and the job is still waiting for execution:

ES-SHUTDOWN-JWAIT=CONTINUE - this is optional but recommended.

To request the JESYSMSG log from the enterprise server written in the SjobID.log file, use:

JESYSMSG

To request the JESYSMSG log from the enterprise server and write it to StdOut:

JESYSMSG=StdOut

To assign a name for the MFBSI jobLog file:

SJobID=JobNo - using the job number assigned by the enterprise server

SJobID=JCL - using the JCL member name

SJobID=StdOut - write the MFBSI job execution log to the standard output (StdOut)

To request the execution of a pre-submit user-exit module, use:

JCLExit=pgmName

JCLExitID=IdentString - associated string passed to the pre-submit user-exit module to determine what action to perform (a maximum of 32 characters)

To invoke a termination user exit just before terminating the execution of MFBSIJCL:

TerminateExit=pgmName

By default, performing a soft-kill on an MFBSIJCL process that is waiting for JOB termination also cancels the JOB in Enterprise Server before terminating.

Use the following parameter to avoid killing the JOB when the process is soft-killed:

ES_JOB_KILL=NO

By default, ES_JOB_KILL=YES is assumed.

To specify the type of JCL files other than the default one, JES2:

JCLType=VSE

JCLType=JES2

JCLType=JES3

To specify a user Id when MSS security is in place (optional):

UserID=myUser

To specify a password when MSS security is in place (optional):

Password=myPwd

To specify a security group when MSS security is in place (optional):

SGroup=securityGroup

Symbolic parameters substitution and using the Control-M AutoEdit Facility:

Note:
  • Using these parameters is mandatory when you use JCL parameters.
  • Substitution is requested with SkelProcessType.

To substitute parameters without accessing the Control-M AutoEdit facility, use:

SkelProcessType=MFBSI

To enable the specific Control-M AutoEdit Facility processing, use:

SkelProcessType=CONTROL-M or SkelProcessType=MFBSICTM

To substitute parameters even if no parameters are specified on the MFBSIJCL command line (this allows substitution of system parameters like DATE, DAY), (optional):

AutoEdit

To specify the parameter substitution prefix that substitutes one or two characters (optional):

SUBST-Prefix=parameterValue

The default value is %%: SUBST-Prefix=%%

To specify the day the week starts (optional):

StartOfWeek=Sunday|Monday

The default value is Monday.

To force submitting the substituted JCL by reference or by content, CASSUB –x, (optional):

CASSUB-CTM=BYREF|CONTENT

CASSUB... –j ... is used by default (CONTENT).

To specify the use of API calls for CASSUB/CASOUT in place of their native commands, and avoid having to create a new process for them (optional):

CASAPI

To specify the OS codes returned by MFBSIJCL if a job abends:

  • SYS-ABEND-RC=nnn - with a SYSTEM abend
  • USR-ABEND-RC=nnn - with a USER abend
  • RTS-ABEND-RC=nnn - with a Run-Time system abend

The default delays used by MFBSIJCL to check for a job state in Enterprise Server are as follows:

  • Two seconds before each check for "Job Started"
  • Ten seconds before each check for "Job Concluded".

You can use the following two parameters to configure these delays:

  • JOBSTART-LOOKUP-FREQ=nn|AUTO
  • JOBEND-LOOKUP-FREQ=nn|AUTO

Where:

  1. nn indicates a numeric value with a minimum of 1 and a maximum of 60 (in seconds)
  2. AUTO - MFBSIJCL automatically optimizes the lookup frequency

    When AUTO is used, MFBSIJCL uses an initial frequency of one second for three minutes after which the default values are restored.

Using these parameters significantly reduces the overhead elapsed time in MFBSIJCL when compared to the Enterprise Server JCL reported execution time of a job. This has an effect mainly in scenarios when you have short-running jobs that are frequently executed.

To specify the maximum allowed delay (in minutes) for an ended job to conclude in MSS/JCL (optional):

EMX-Timeout=nn

The default value is fix minutes.

MFDEBUG

To produce a detailed trace log of mfbsijcl execution. To be used if requested by Micro Focus Support. This is not recommended in a production environment.

Parent topic: Micro Focus Batch Scheduler Integration


MFBSIJCL Submit Process

The scheduler always executes the module MFBSIJCL, either directly or by executing a script. This submits a JCL job to Enterprise Server/JCL. MFBSIJCL ends execution when the job terminates, either normally or abnormally.

If Enterprise Server shuts down while submitted jobs are waiting for execution, other MFBSIJCL instances may still be running and waiting. When Enterprise Server restarts, jobs should be processed.

After the StartupTimeout / RunTimeout values have elapsed, alerts may be sent to the scheduler by customizing the MFBSIJCL user exit mfbsialr.

The environment variable MFBSI_DIR must be defined and known to the operating system before MFBSIJCL starts. MFBSI_DIR specifies the folder where the temporary files JOBnnnnn.Sem and JobId.Log are stored. This folder must be accessible from where MFBSIJCL executes, either directly or from a share, or from the system running Enterprise Server.

When MFBSIJCL executes, it takes execution parameters first from its command line, and then from the configuration file mfbsi.cfg. By default, the configuration file mfbsi.cfg is located in the folder specified by the MFBSI_DIR environment variable. mfbsi.cfg can specify parameters common to all submitted jobs.

Note: Some execution parameters are only valid in mfbsi.cfg and not allowed on the command line.
  • MFBSIJCL Command Line Parameters
  • MFBSIJCL Return Codes
Parent topic: Micro Focus Batch Scheduler Integration


MFBSIJCL Command Line Parameters

MFBSIJCL uses two sets of command line parameters. The parameter sets are optionally delimited by END [space-END-space].

One parameter set corresponds exactly to the parameters used by the CASSUB and CASOUT commands. See online help for details on these commands. With MFBSI, the parameters -j and -x let you use OS environment variables in the path specification. See the description of the mfbsi.cfg parameter JCL-Submit for details.

The other parameter set is specific to MFBSI as shown.

Parameter | Description
SJOBID Specifies the MFBSIJCL output destination. Required when SJOBID is not defined in mfbsi.cfg or when not using a configuration file.
  • SJOBID=[JobId]. The internal Job ID assigned by the scheduler. This creates a log file containing the CASSUB or CASOUT outputs and includes the JCL execution return code. The log file is named by the Job Id used (jobID.log).
  • SJOBID=JCL. The output log file name is set to the submitted JCL member name.
  • SJOBID=JOBNO. The output log file name is set to the job number assigned by the Enterprise Server/MSS JCL.
  • SJOBID=STDOUT. No log file is created. The MFBSIJCL output is directly written to the console (STDOUT).

Specifying the JESYSMSG parameter includes the Enterprise Server SysMsg log in the log file or STDOUT output.

REGION=ESregionName | When using a custom MFBSI_DIR setting (where the last part of the MFBSI_DIR path does not specify the region name), specifies the Enterprise Server region name to be used.
STARTUPTIMEOUT=nnnn The timeout period in seconds between the job submission and the Enterprise Server job start. Optional.

A value of 0 specifies an infinite wait. The default value is 300 (seconds).

You can use the MFBSIALR module to send an alert to the scheduler when the startup timeout period is reached.

RUNTIMEOUT=nnnn The timeout period in seconds between the Enterprise Server job start and job end. Optional.

A value of 0 specifies an infinite wait. The default value is 900 (seconds).

You can use the MFBSIALR module to send an alert to the scheduler when the run timeout period is reached.

JCLExit=moduleName Specifies a user exit module to call before job submission to Enterprise Server/JCL. Optional.

This user exit lets you modify the parts of the JCL such as parameters substitution, and return the full name of a new JCL file to be submitted. If needed, use JCLExitID to pass an identification string to the user exit.

TerminateExit=moduleName | Specifies a module to call just before terminating the MFBSIJCL process. Optional.
JESYSMSG | Extracts the Sysmsg log produced by Enterprise Server for the job and includes it in the specified output destination, which is either a log file or STDOUT. Optional.
PARMS … [ENDPARMS] Used to define substitution pairs (parameterName=parameterValue). Optional.

See the topic on parameters substitution for details.

AUTOEDIT If PARMS … END-PARMS is not specified, this invokes the symbolic parameter substitution module to translate systems parameters. Optional.

See the topic on parameters substitution for details.

CFG=[path/][filename][.ext] Specifies a file to use as an alternate mfbsi.cfg parameters file. Optional.

The folder specified by $MFBSI_DIR is used if no path is specified. The extension .cfg is used if no extension is specified.

CASAPI=ON|OFF|YES|NO Uses the CASSUB/CASOUT API call interfaces to submit the job, monitor the JCL region, and retrieve the JESYSMSG output. Optional.

By default, MFBSIJCL uses CASSUB/CASOUT external commands to submit the job, monitor the JCL region and retrieve the JESYSMSG output. Set this parameter to ON or YES for improved performance and tighter security.

Note: Do not use special configuration settings for the COBOL file handler (EXTFH) in the environment where MFBSIJCL is running. For example, do not use STRIPSPACE=OFF. If needed, you can specify special EXTFH parameters at the region level. Contact Micro Focus Support regarding EXTFH parameters.
Parent topic: MFBSIJCL Submit Process


MFBSIJCL Return Codes

This table shows return codes from MFBSIJCL.

Return Code | Description
200 CASSUB parameters missing

The minimum parameters required to execute cassub not specified or can't be configured from mfbsi.cfg

(-r/-l/sTCP:... -j|-x)
201 Too many parameters on the command line

More than 35 parameters found on the mfbsijcl command line

202 | Unknown command line parameter detected
203 | Scheduler jobLog not assigned (SJobID)
204 | MFBSI_DIR environment variable not set
205 | MFBSI_DIR defines an invalid dir/folder
206 | Invalid numeric value for TimeOut
207 JCL UserExit failed to execute / Rc <> 00

An mfbsi user exit returns with Rc not equal to zero

208 JES/JCL error detected

Job has been submitted but JES detected a JCL error

209 Job submission failed (See JobLog output)

JCL member not found. See message JCLSI0003I in mfbsi jobLog for details

210 JobConcluded signal event not returned

ES Event Manager user-exit (mfbsiemx) didn't return the event "job concluded"

211 Job ended, no numeric RC returned

Contact Micro Fous Support

212 CommandLine parameters missing

No commandLine parameters found when executing mfbsijcl

213 Configuration parameter unknown

Invalid/unknown commandLine parameters found when executing mfbsijcl

214 Unable to configure JCL to submit parameter

The cassub parameter "-j|-x" can't be determined

215 | TYPRUN=SCAN: scan successful
216 | TYPRUN=SCAN: scan failed
217 JCL UserExit program missing or not found

Module name specified in JCLexit=??? can't be loaded

Windows: ???.int/???.gnt/???.dll

UNIX: ???.int/???.gnt/???.so|???.sl

218 Terminate user-exit program missing or not found

Module name specified in TerminateExit==??? can't be loaded

219 | SEP execution process hard killed
220 Restart for Job failed

Job to restart not found in ES/JCL

ES_JES_RESTART=Y and/or MF_UCC11=Y missing in ES Configuration Information

221 Unable to call module "MFBSIPRM"

Internal error. Contact Micro Focus Support

222 Error during skeletal parameter(s) substitution

Internal error. Contact Micro Focus Support

223 MFBSI.cfg error: "SkelProcessType" unknown

Internal error. Contact Micro Focus Support

224

More than 10 ISPSLIB paths

Internal error. Contact Micro Focus Support

225 Server crashed/killed when job was waiting for execution

mfbsijcl is unable to correctly contact the JCL region to get the job state

226 | SYS/USR-ABEND-RC=nnn in MFBSI.cfg not numeric or greater than 199
227 JESYSMSG-RC=Y(es) requires parameter JESYSMSG

The parameter "JESYSMSG-RC=Y(es)" should no longer be used

228 Server crashed/killed when job was running

mfbsijcl is unable to correctly contact the JCL region to get the job state

229 Job state unknown or inconsistent. Check Job status via SEE Web admin

mfbsijcl is unable to correctly determine the job state

(Information from the Event Manager user-exit not in sync with job state)

230 Max number of parameters to substitute reached

When using parameter(s) substitution, maximum 500 parameters are allowed

On the command line, maximum 15 pairs ParamName/ParamValue are allowed

231 Parameter file used for variable substitution not found

A file to be used with parameters substitution can't be found

232 mfbsijcl execution cancelled by a SIGTERM/Break signal

mfbsijcl has been interrupted by a soft kill (e.g. Ctrl+C)

233 Submitted job cancelled before execution

A job waiting for execution in ES has been cancelled

234 MFBSI Control-M Post-Processing Handler Error

Internal error. Contact Micro Focus Support

235 Invalid special file name for mfbsi.cfg

The alternate path of mfbsi.cfg (default in MFBSI_DIR) is incorrect

236 Special file name for "mfbsi.cfg" not found

The alternate mfbsi.cfg can't be found

237 Invalid EMX-Timout parameter value. See mfbsi.cfg

Internal error. Contact Micro Focus Support

241 | MFBSISEC user-exit module not found
242 Invalid MFBSIEMX version level. MFBSIEMX v3. is required

An old version of the Event Manager user-exit is used

243 In MFBSI_DIR, "regionName.Started" not found

ES/JCL region not started or not configured for MFBSI

See ES "Configuration Information" MFBSI_DIR=… or ES_EMP_EXIT_#=mfbsiemx missing

# specifies the Event Manager user-exit sequence number (starting from 1. Max 9.)

244 Unexpected "Job Concluded" signal received from Enterprise Server during job execution.

The semaphore file JOB?????.sem does not reflect the end of the job. Nevertheless, the Enterprise Server JCL engine considers the job as ended.

You need to check console.log for any messages concerning the Enterprise Server Event Manger and mfbsiemx.

Then, ensure that the file system disk space used by MFBSI_DIR and any other Enterprise Server components is not full.

Parent topic: MFBSIJCL Submit Process
Related concepts
To Display MFBSIJCL Return Codes


Job Restart

Enterprise Server allows job restarts at the step or procStep level.

You must add environment variables to the Enterprise Server configuration information to allow the restart request for submitted jobs.

ES_JES_RESTART=Y and MF_UCC11=Y must be defined environment variables.

Refer to the following online documentation for more information regarding restarting jobs.

  • Micro Focus Server
  • Mainframe Support (CICS, IMS and JCL applications)
  • Mainframe Transaction Option Configuration and Administration Guide
  • JCL Support
  • Configuring an MSS-enabled Enterprise Server for JCL
  • The Restarting Jobs topic.
  • Job Restart Usage
Parent topic: Micro Focus Batch Scheduler Integration


Job Restart Usage

To use MFBSIJCL to restart a failed job at a given step, replace the JCL command line parameter. The JCL parameter is similar to this line:

[-j][y:\MFServerEE\...\JCL\] MYJCL [.jcl]

Replace this line with:

[-j][JOB]nnnnn:STEP[:PROCSTEP]

where:

  • [JOB]nnnnn is the number referring to the job that you would like to restart. The string JOB may be omitted.
  • STEP is the step name for the restart.
  • PROCSTEP is the Proc Step name (optional).
Note: Parameters in square brackets in the example are optional.

MFBSIJCL assumes a RESTART if [ -j][JOB]nnnnn:STEP[:PROCSTEP] is found in the JCL parameters as identified by -j or -J, or found in the assumed JCL member name.

For example, these commands are considered valid for a job restart:

MFBSIJCL ... -jJOB12345:step4 ...

MFBSIJCL ... /j12345:step4 ...

MFBSIJCL ... JOB12345:step4 ...

MFBSIJCL ... 12345:step4:PROC12 ...

MFBSIJCL ... 1234:step4 ...

Tip: MFBSIJCL normalizes the job as JOBnnnnn, that is the string JOB followed by 5 digits. StepName/ProcStepName is converted to upper-case.

Return code 220 from MFBSIJCL indicates a failed restart. If the stepName or the procStepName are invalid, it takes more than one minute for MFBSIJCL to end with return code 220. Check MFBSI job.log and the Enterprise Server console for more information.

A parameter defined for MFBSIUE1 and MFBSIUE2 user exits identifies the execution mode:

  • Normal: normal job submit
  • Restart: restart of a job

When an exit is invoked at job restart, the ESue1-JCLfile or ESue2-JCLfile variable in the interface contains JOBnnnnn:StepName[procStepName].

For a job restart request, if the parameter SJOBID=JCL is used, it changes to SJOBID=JOBNO. The log file name is saved as JOBnnnnn.log. The job log from the restart execution in the folder specified by the $MFBSI_DIR variable overwrites the job log file of the initial submit.

Parent topic: Job Restart


Sending Alerts to the Scheduler

If a submitted job does not start execution after the time specified by StartupTimeout (with a minimum of one minute), or if a job is still running after the time specified by RunTimeout (with a minimum of one minute), the user exit MFBSIALR is called. This allows a notification to be sent to the scheduler requesting action by the Enterprise Developer/MSS interface.

If after a first alert, the job is still in the same status after the specified time increment, subsequent alerts are sent at the specified time increment (AlertBackTimout) to re-invoke MFBSIALR.

By default, the MFBSIALR.cbl source provided as an example simply adds a new record in the file $MFBSI_DIR\Alert.txt displaying all the interface data.

The mfbsialr.cpy interface copybook file is located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) A sample COBOL program, mfbsialr.cbl, is located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits (Windows) or $COBDIR$COBDIR\cpylib (UNIX). Change this sample COBOL user exit program as needed for your environment, such as using the API provided by your scheduler.

  • MFBSIALR interface
Parent topic: Micro Focus Batch Scheduler Integration


MFBSIALR interface

This example shows the MFBSIALR interface.

*    -- copybook "MFBSIALR" --
01  ES-Alert-Exit-Interface.
**>
                    05  ESalrt-OS                   pic x(1).
            88 ESalrt-Windows             value '0'.
            88 ESalrt-UNIX                value '1'.
        05  ESalrt-Scheduler-Job-ID     pic x(16).
        05  ESalrt-AlertType.
         10  ESalrt-AlertType-Code   pic x(2).
                         88  Wait-on-Start         value '01'.
             88  Wait-on-EndOfRun      value '02'.
             88  No-Conclude-Signal    value '03'.
         10  ESalrt-AlertType-Txt    pic x(30).
     05  ESalrt-ES-Server            pic x(8).
     05  ESalrt-ES-Job               pic x(8).
     05  ESalrt-Date                 pic x(10).
     05  ESalrt-Time                 pic x(8).
Parent topic: Sending Alerts to the Scheduler


JCL Parameter Substitution

The JCL member submitted to MFBSIJCL may contain parameters that are substituted before submission to Enterprise Server/MSS. When a parameter is ended by a dot or using ++, these characters are suppressed after substitution.

The ParameterName/ParameterValue pair capability is provided in the MFBSIJCL command line, but can also be specified in a parameter file or as operating system environment variables. MFBSIJCL may also automatically handle system parameters like DATE, DAY, or WEEK. For example, for the JCL member MYJCL.jcl:

//MFIDPS01  JOB 'MFIDPS',CLASS=A,MSGCLASS=A
//STEP1    EXEC PGM=IEFBR14
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//DD1      DD DSN=%%HLQ..TEST.DSN,DISP=(MOD,DELETE)
//SYSIN    DD *
DATE    : %%DATE
/*
//
Note: In this example, %%HLQ is a user defined parameter and %%DATE is a system parameter (current date).

When submitted by MFBSIJCL (on 22 December 2013) using the command line parameters:

mfbsijcl MYJCL PARMS HLQ=MFIDPS [END-PARMS]

results in this JCL submitted to Enterprise Server/MSS

//MFIDPS01  JOB 'MFIDPS',CLASS=A,MSGCLASS=A
//STEP1    EXEC PGM=IEFBR14
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//DD1      DD DSN=MFIDPS.TEST.DSN,DISP=(MOD,DELETE)
//SYSIN    DD *
DATE    : 131222
/*
//
  • JCL Parameters Substitution Usage
  • System Parameters
  • Enabling Control-M AutoEdit Use
Parent topic: Micro Focus Batch Scheduler Integration


JCL Parameters Substitution Usage

To enable JCL parameters substitution, add this setting to the mfbsi.cfg configuration file:

SkelProcessType=MFBSI

Enabling parameters substitution also creates a folder under the folder specified by the $MFBSI_DIR variable that stores the modified JCL file.

JCL parameters substitution is enabled when AutoEdit (command-line or through mfbsi.cfg) or PARMS … [END-PARMS] in a command line command are used. If not specified, no parameter substitution is done. If specified on the command line, parameters definition is started by the keyword PARMS and ended with END-PARMS. END-PARMS is not needed if it is the last keyword on the command line.

The maximum authorized command line length with MFBSIJCL is 8191 characters.

A parameter definition is formed by parameterName, followed by the equal sign =, followed by parameterValue. A total of 500 parameters is allowed.

parameterName can have a maximum of 32 characters, which are automatically translated to upper case as needed. In JCL, parameterName is prefixed by one or two special characters that identify the parameter. By default, the characters %% are used for the prefix. You can change the default characters used in JCL for parameterName with the setting SUBST-Prefix in the mfbsi.cfg configuration file.

A parameterName in a JCL member ends with:

  • A space, period, comma, equal sign, single or double quotation marks and close parenthesis.
  • Two consecutive plus signs (++).
  • A new parameter starting with %% or SUBST-Prefix.

When a parameter is ended by a dot or using ++, these characters are suppressed after substitution.

parameterValue can have a maximum of 80 characters. To indicate a null value, use two consecutive double-quotes. Values that contain spaces should be enclosed by double-quotes.

Some or all parameters can be stored in a line sequential parameter file. Each parameterName=parameterValue pair must be on a single line and start in position 1. Prefix the full file location (path-baseName-extension) with the @ character. Delimit the file name using double quotes if it contains one or more spaces. For example:

MFBSIJCL ABC00231 PARMS HLQ=MF @"Y:\...\Parm File.Prm" WEEK=49
MFBSIJCL ABC02233 PARMS @/MF_ES/…/parmFile.prm END-PARMS

Parameters can also be specified as environment variables, using for example the OS command set / export parameterName=parameterValue. If PARMS … [END-PARMS] is not used, specify AUTOEDIT to enable substitution. On UNIX/Linux, parameter names are case sensitive.

The search order for parameters value resolution is:

  • Command line and parameter file
  • System parameters automatically defined by MFBSI
  • Environment variables

If requested, an MFBSI user exit before submission, such as mfbsiue1.cbl invokes after parameters substitution has successfully completed. The variable ESue1-JCLfile contains the full name of the substituted JCL file.

In case of job restart, PARMS … [END-PARMS] or AUTOEDIT are not allowed. No JCL substitution is done.

Parent topic: JCL Parameter Substitution


System Parameters

MFBSI automatically defines the system variables that can be used in your JCL member. These variables are resolved before job submission and are not reevaluated during job execution.

Parameter / Variable | Description
SJOBID | JobID assigned by the scheduler. Contains a maximum of 16 characters, translated to upper case.
MEMNAME | JCL member name, translated to upper case.
BLANK | One blank ( space character X'20')
BLANKn | Resolves to n blanks, where n is a number from 1 through 80
TIMEID | Current time of day, in hhmmss format. This variable receives the current time only when it is first resolved in a job. Subsequent resolutions within that job do not update the variable.
TIME | Current time of day, in hhmmss format. This parameter receives the current time each time it is invoked.
$CENT | First two digits in the current year (for example, 20 in the year 2009)
DATE | Current system date (format yymmdd)
DAY | Current system day (format dd)
MONTH | Current system month (format mm)
YEAR | Current system year (format yy)
WEEK | Current week in the year (that is, 01 through 53)
WDAY | Current system day of the week (Example: 1=Sunday, 2=Monday and 0=Saturday)
JULDAY | Current system day (Julian format jjj)
$JULDAY | Current system day (Julian format yyyyjjj)
$DATE | Current system date (format yyyymmdd)
$YEAR | Current system year (format yyyy)
Parent topic: JCL Parameter Substitution


Enabling Control-M AutoEdit Use

MFBSI provides a measure of support for the BMC Control-M AutoEdit facility. The support assists migrating JCL using Control-M AutoEdit control statements or variables to the MSS server. This support does not cover full compatibility with Control-M for z/OS. Refer to the BMC Control-M for OS/390 and z/OS User Guide for information on using the Control-M AutoEdit facility.

Specify these parameters in the mfbsi.cfg configuration file to enable the Control-M AutoEdit facility.

SkelProcessType=MFBSICTM
AutoEdit
StartOfWeek=Sunday|Monday //Optional. Default is Monday
  • Variables Substitution
  • Date System Variables
  • Resolving Original Scheduling (%%O and %%$O) System Date Variables
  • %%IF, %%ELSE, and %%ENDIF
  • %%SET
  • %%GLOBAL and %%LIBSYM
  • %%INCLIB and %%INCMEM
  • %%GOTO and %%LABEL
  • Displaying the Symbols Pool in JCL Command Lines
  • Error Handling
Parent topic: JCL Parameter Substitution


Variables Substitution

AutoEdit variables can be defined using:

  • MFBSIJCL parameter names/values (including @parms_file)
  • OS environment variables
  • %%GLOBAL or %%LIBSYM control statements
  • %%SET control statement

MFBSI maintains a single variables pool. All variables are managed the same way in this pool. The MFBSI variable pool does not contain OS environment variables, except for system scheduling dates. See the topic on resolving original scheduling system date variables for more information.

The variables are searched in this order:

  • MFBSI variables pool
  • OS environment variables
  • AutoEdit system variables

Variable names are case insensitive. Variable values can have a maximum 80 character length.

Parent topic: Enabling Control-M AutoEdit Use


Date System Variables

The MFBSI system date variables for use with the Control-M AutoEdit facility are:

TIME | TIMEID | RDATE
DATE | ODATE | RJULDAY
JULDAY | OJULDAY | $RJULDAY
$JULDAY | $OJULDAY | RDAY
DAY | ODAY | RWDATE
WDAY | OWDAY | RMONTH
MONTH | OMONTH | RYEAR
YEAR | OYEAR | RWEEK
WEEK | OWEEK | $RCENT
$CENT | $OCENT |
Parent topic: Enabling Control-M AutoEdit Use


Resolving Original Scheduling (%%O and %%$O) System Date Variables

The Control-M AutoEdit facility can define or export these OS environment variables before executing MFBSIJCL or the script that executes MFBSIJCL.

  • ODATE [YYMMDD] [%%ODATE]
  • CENT [CC] [%%CENT]

PARMS ODATE=%%ODATE [CENT=%%CENT] may also be used in the MFBSIJCL command line to set %%ODATE and %%CENT.

When MFBSIJCL starts execution, it retrieves ODATE and CENT OS environment variable values. These are saved in the MFBSI symbols pool to resolve %%ODATE, %%ODAY, %%OMONTH and %%OYEAR found in the JCL member to be executed. Based on the values of these variables, additional Control-M AutoEdit variables are evaluated and stored in MFBSI symbols pool:

  • $OYEAR [CCYY]
  • $ODATE [CCYYMMDD]
  • OWEEK [nn] where nn = 01 - 53
  • OWDAY [d] where d = 1 -7
  • OJULDAY [JJJ] where JJJ = Julian date
  • $OCENT [CC]

When MFBSI is used with a scheduler other than Control-M, the OS variables ODATE, ODAY, OMONTH, OYEAR and CENT must be explicitly defined whenever %%ODATE, %%ODAY, %%OMONTH, %%OYEAR, %%$DATE, %%$OYEAR, %%OJULDAY, %%$OJULDAY, %%OWEEK, %%OWDAT or %%$CENT require resolution in the JCL. Control-M resolves these system variables based on the current OS system date.

If CENT is not defined in the OS environment, the current OS system century is used.

Example

This example shows a Control-M set/export ODATE=010201 (1 Feb.) and CENT=20 (year 2001) and variables defined in the MFBSI symbols pool at MFBSIJCL initialization.

9 //* %%LISTVAR
10 //*
--------------------------------------------------------------------<LISTVAR
11 //* ODATE = [010201] <LISTVAR
12 //* OYEAR = [01] <LISTVAR
13 //* OMONTH = [02] <LISTVAR
14 //* ODAY = [01] <LISTVAR
15 //* $ODATE = [20010201] <LISTVAR
16 //* $OYEAR = [2001] <LISTVAR
17 //* OWEEK = [05] <LISTVAR
18 //* OWDAY = [4] (if first day of week is defined as Monday) <LISTVAR
19 //* OJULDAY = [032] <LISTVAR
20 //* $OJULDAY = [2001032] <LISTVAR
21 //* $OCENT = [20] <LISTVAR
22 //*
--------------------------------------------------------------------<LISTVAR
Parent topic: Enabling Control-M AutoEdit Use


%%IF, %%ELSE, and %%ENDIF

MFBSI supports a maximum of 100 nested %%IF levels.

This example shows %%IF, %%ELSE, and %%ENDIF variable substitution:

Statement/Expression Resolves as...
//* %%SET %%STEP=STEP1

//* %%IF %%STEP EQ STEP1
//STEP1    EXEC PGM=IEFBR14
//*        => To be executed
//SYSOUT   DD SYSOUT=*
//* %%ELSE
//STEP2    EXEC PGM=IEFBR14
//*        => To be excluded
//SYSOUT   DD SYSOUT=*
//* %%ENDIF
//* => Always executed
//STEP3    EXEC PGM=IEFBR14
//*        => Always executed
//SYSOUT   DD SYSOUT=*

//* %%SET %%STEP=STEP1

//* %%IF STEP1 EQ STEP1
//STEP1    EXEC PGM=IEFBR14
//*        => To be executed
//SYSOUT   DD SYSOUT=*
//* %%ELSE

//* %%ENDIF
//* => Always executed
//STEP3    EXEC PGM=IEFBR14
//*        => Always executed
//SYSOUT   DD SYSOUT=*

//* %%IF %%STEP NE STEP1
//STEP1    EXEC PGM=IEFBR14,PARM='%%DATE'
//*        => To be excluded
//SYSOUT   DD SYSOUT=*
//* %%ELSE
//STEP2    EXEC PGM=IEFBR14,PARM='%%ODATE'
//*        => To be executed
//SYSOUT   DD SYSOUT=*
//* %%ENDIF
//* => Always executed
//STEP3    EXEC PGM=IEFBR14,PARM='%%RDATE'
//SYSOUT   DD SYSOUT=*

//* %%IF STEP1 NE STEP1

//* %%ELSE
//STEP2    EXEC PGM=IEFBR14,PARM='110716'
//*        => To be executed
//SYSOUT   DD SYSOUT=*
//* %%ENDIF
//* => Always executed
//STEP3    EXEC PGM=IEFBR14,PARM='110716'
//SYSOUT   DD SYSOUT=*

//* %%SET %%STEP=STEP2

//* %%IF   %%STEP   EQ STEP1
//* %%ELSE
//STEP1    EXEC PGM=IEFBR14
//*        => To be executed
//SYSOUT   DD SYSOUT=*
//* %%ENDIF
//STEP2    EXEC PGM=IEFBR14
//*        => Always executed
//SYSOUT   DD SYSOUT=*

//* %%SET %%STEP=STEP2

//* %%IF STEP2 EQ STEP1
//* %%ELSE
//STEP1    EXEC PGM=IEFBR14
//*        => To be executed
//SYSOUT   DD SYSOUT=*
//* %%ENDIF
//STEP2    EXEC PGM=IEFBR14
//*        => Always executed
//SYSOUT   DD SYSOUT=*
Parent topic: Enabling Control-M AutoEdit Use


%%SET

The valid syntax for %%SET in MFBSI is:

%%SET %%VarName[space(s)]=[space(s)]Expression

Expression can be:

  • Constant or AutoEdit variable(s)
  • AutoEditFunction
  • AutoEditFunction %%PLUS|%%MINUS Number|AutoEdit variable

This example shows %%SET variable substitution:

Statement/Expression Resolves as...
%%SET %%PARM=XYZ

%%PARM:      [XYZ]

%%SET   %%PARM  =XYZ

%%PARM:      [XYZ]

%%SET %%PARM  =    XYZ

%%PARM:      [XYZ]

%%SET %%PARM  =    X Y   Z

%%PARM:      [XYZ]

%%SET %%PARM=ABC  DEF

%%PARM:      [ABCDEF]

%%SET %%PARM=ABC%%BLANK2DEF

%%PARM:	     [ABC  DEF]

%%SET %%PARM=ABC%%BLANKDEF

%%PARM:	     [ABC DEF]

%%SET %%PARM=ABCDEF%%BLANK5

%%PARM:	     [ABCDEF     ]

%%SET %%PARM=ABCDEF%%BLANK3

%%PARM:	     [ABCDEF   ]

%%SET %%PARM='ABCDEF%%BLANK5'

%%PARM:	     ['ABCDEF     ']

%%SET %%PARM=%%$ODATE%%.ABC

%%PARM:	     [20110701ABC]

%%SET %%PARM=%%$ODATE.ABC

%%PARM:	     [20110701.ABC]

%%SET %%PARM=%%$ODATEABC
 Error: %%$ODATEABC can't be resolved.
Note: If it exists in the pool, value of %%PARM is left as-is.
  %%SET %%A=1
  %%SET %%B=2
  %%SET %%A2=100

//       TAPE=TAPE%%A%%B,
//       TAPE=TAPE%%A.%%B,
//       PARM=PRM%%A%%.%%B,
//       PARM=PRM%%A%%..%%B,
//       PARM='%%A%%%BLANK3%%B',
//DDN  DD DSN=HLQ.DATASET.A%%A.%%B,
//DDN  DD DSN=HLQ.DATASET.A%%A..%%B,
//DDN  DD DSN=HLQ.DATASET.A%%A%%..%%B,
//DDN  DD DSN=HLQ.DATASET.A%%A%%B,

//       TAPE=TAPE100,
//       TAPE=TAPE1.2,
//       PARM=PRM12,
//       PARM=PRM1.2,
//       PARM=’1   2’,
//DDN  DD DSN=HLQ.DATASET.A12,
//DDN  DD DSN=HLQ.DATASET.A1.2,
//DDN  DD DSN=HLQ.DATASET.A1.2,
//DDN  DD DSN=HLQ.DATASET.A100,

%%$ODATE%%BLANK5%%#AS-IS%%BLANK5%%WEEK

20110716     %%AS-IS     28

This example shows resolution of date functions in the %%SET control statement.

Statement/Expression Resolves as...
%%$YEARWK# %%$DATE
%%$YEARWK# 20010214
%%$YEARWK# 20050101
%%$YEARWK# 20011231

%%$YEARWK# 20101220
%%$YEARWK# 20101227
%%$YEARWK# 20110102
%%$YEARWK# 20110103

%%$CALCDTE %%$ODATE +D1
%%$CALCDTE   %%$ODATE +1

%%SET %%ADD_DATE=7
%%$CALCDTE %%$ODATE +%%ADD_DATE
%%$CALCDTE 20110101 -1
%%$CALCDTE 20101231 +1
%%$CALCDTE 20110228 +1
%%$CALCDTE 20110228 +1

[2011W28]
[2011W28]
[2011W28]
[2011W28]

[2011W28]
[2011W28]
[2011W28]
[2011W28]

[20110717]
[20110717]

[7]
[20110723]
[20101231]
[20110101]
[20110301]
[20110301]

This example shows resolution of %%PLUS / %%MINUS in the %%SET control statement:

Statement/Expression Resolves as...
%%SET %%_SCRATCH1=10 %%PLUS 25
%%SET %%_SCRATCH2=  %%B   %%MINUS   %%A
%%SET %%_SCRATCH3=%%A %%PLUS %%B

[35]
[1]
[3]

This example shows resolution of %%SUBSTR in the %%SET control statement:

Statement/Expression Resolves as...
%%SET %%STR=00-01-02
%%SET %%TAPE_01=%%SUBSTR %%STR 4 2
%%SET %%TAPE_02=EE100002
%%SET %%TAPE_03=EE100003
%%SET %%TAPE_04=EE100004
%%SET %%TAPE_05=EE100005
%%SET %%TAPE_06=EE100006
%%SET %%TAPE_07=EE100007
%%SET %%TAPE_08=EE100008
%%SET %%TAPE_09=EE100009
%%SET %%TAPE_10=EE100010
%%SET %%TAPE_11=EE100011
%%SET %%TAPE_12=EE100012

//    UNIT=TAPE,VOL=SER=TAPE%%TAPE_01,
//    UNIT=TAPE,VOL=SER=%%TAPE%%OMONTH,

[00-01-02]
[01]
[EE100002]
[EE100003]
[EE100004]
[EE100005]
[EE100006]
[EE100007]
[EE100008]
[EE100009]
[EE100010]
[EE100011]
[EE100012]

//    UNIT=TAPE,VOL=SER=TAPE01,
//    UNIT=TAPE,VOL=SER=EE100007,
Parent topic: Enabling Control-M AutoEdit Use


%%GLOBAL and %%LIBSYM

%%GLOBAL and %%LIBSYM values are stored in text files. In these text files:

  • Each record specifies the parameter name and the associated value.
  • Blank lines are ignored.
  • Comment lines start with a semicolon.
  • Values that contain explicit spaces are enclosed in double quotes.

This shows an example of symbol file contents:

; some comment
ABC=ABC

def="ABC DEF"
 Group    =     XYZ
 Parm2    =     "'123 567'"

The environment variable DAGLOBAL or the catalog specifies the folder for the text file(s) used by %%GLOBAL. In a similar way, for %%LIBSYM members, the folder name is extracted from an environment variable or from the catalog.

When the catalog is used, define a PDS (type Dynamic, LRECL 80, LSEQ) that refers to the folder/directory containing the members.

For %%GLOBAL, the dataset name 'DAGLOBAL' is required; for %%LIBSYM, use the specified dataset name.

This example shows resolution of %%GLOBAL and %%LIBSYM control statements:

Statement/Expression Resolves As…
[//*] %%GLOBAL MBRNAME

The environment variable DAGLOBAL specifies the location of the MBRNAME text file. The DSN DAGLOBAL is used to locate the member name.

[//*] %%LIBSYM DATA.SET.NAME %%MEMSYM MBRNAME

The environment variable DATA.SET.NAME or DATA.SET.NAME as defined in the catalog specifies the MBRNAME text file location.

When an environment variable is used to locate the directory containing the member, the extension 'JCL' is used to find the member file name.

Parent topic: Enabling Control-M AutoEdit Use


%%INCLIB and %%INCMEM

The syntax for %%INCLIB and %%INCMEM are:

//* %%INCLIBDataSetName %%INCMEMmember

or

//* %%INCLIB DDNAME=ddName %%INCMEMmember

DataSetName or ddName must be exported as an environment variable and point to the folder where the file that defines member is found. Otherwise, the catalog is used. Extensions are not used in the syntax.

You can specify multiple paths with concatenation if using ddName. Each path is separated by a semicolon (Windows) or colon (UNIX/Linux).

Parent topic: Enabling Control-M AutoEdit Use


%%GOTO and %%LABEL

Use %%GOTO either subordinated to a conditional control statement such as %%IF or %%ELSE, or as an imperative statement. If used within a conditional control statement, %%GOTO implicitly terminates the conditional control statement.

The label names specified with %%GOTO or %% LABEL are constant, so they are resolved as a variable. The search for a %%LABEL associated to a %%GOTO is done in ascending order from the %%GOTO position.

Parent topic: Enabling Control-M AutoEdit Use


Displaying the Symbols Pool in JCL Command Lines

MFBSI has specific control statements that insert the existing symbols pool into JCL as command lines. Use the %%LISTVAR or %%LISTVARS control statements to do this.

9 //* %%LISTVAR
 10 //* --------------------------------------------------------------------<LISTVAR
 11 //* ODATE    = [010201]                                                 <LISTVAR
 12 //* OYEAR    = [01]                                                     <LISTVAR
 22 //* --------------------------------------------------------------------<LISTVAR
Parent topic: Enabling Control-M AutoEdit Use


Error Handling

When MFBSI detects an AutoEdit error, it inserts an error message in the JCL just before the statement in error. The error message text starts with //* ??? JCLSI0050E. The end of the message displays the number of the original JCL line.

For example:

 1 //MFIDPS01 JOB 'MFIDPS',CLASS=A,MSGCLASS=1
 2 //* %%GLOBAL				GLOBAL01
 3 //* %%LIBSYM    MFIDPS.CTRLM.SYMB %%MEMSYM SYMMBR01
 4 //* %%SET %%SYMBMBR=SYMMBR01
 5 //* %%LIBSYM MFIDPS.CTRLM.SYMB %%MEMSYM %%SYMBMBR
 6 //*
 7 //STEP1    EXEC PGM=IEFBR14
 8 //SYSOUT   DD SYSOUT=*
 9 //*??? JCLSI0050E For "DAGLOBAL(NOTFOUND)" file open error: 9/009. (9)
10 //* %%GLOBAL   NOTFOUND                                    << JCLin
11 //*

In case of AutoEdit error(s), MFBSI generates a bad JCL statement at the end of the JCL to abort the submitted job.

   21 //*
   22 // ***** MFBSI GENERATED JCL ERROR (AUTOEDIT FACILITY ERROR) *****
 **** JCLCM0409E INVALID OPERATOR
   23 //
 **** JCLCM0172E JOB FAILED - JCL ERROR

If this happens, the Control-M AutoEdit facility receives a get RC=208 message.

The submitted JCL can be found in the $MFBSI_DIR\JCLTemp folder.

Parent topic: Enabling Control-M AutoEdit Use


User Exit Before Submission to Enterprise Server/JCL

Introduction

If needed, the JCL file specified in the MFBSIJCL command can be edited before submission to JCL. This allows for any parameters substitution or additional site specific checking.

The parameter JCLExit specifies the name of the user exit module to be called. Use the mfbsiue1.cpy interface shown:

      *    -- copybook "MFBSIUE1" --

       01  ES-UserExit-JCLsubmit.
      **>  MFBSIJCL exit's common area
           05  ES-UE-CommonArea            pic x(1024).
      **>  Input parameters
           *>  OS Environment
           05  ESue1-OS                    pic x(1).
               88 ESue1-Windows              value '0'.
               88 ESue1-UNIX                 value '1'.
           *>  SJOBID
           05  ESue1-Scheduler-Job-ID      pic x(16).
           *>  User exit identifier
           05  ESue1-JCLexitID             pic x(32).
           *>  Execution mode: submit JCL or JOB restart
           05  ESue1-ExecutionMode         pic x(01).
               88  ESue1-ExecNormal          value 'N'.
               88  ESue1-ExecRESTART         value 'R'.
           05  filler                      pic x(14).
      *
      **>  Input/Output parameters
           05  ESue1-JCLfile               pic x(256).
      *
      **>  Output parameters
           05  ESue1-ReturnCode            pic x(2).
           05  ESue1-ReturnMsg             pic x(256).
      *
      **>  Delimiter
           05  ESue1-X00                   pic x(1).

The mfbsiue1.cpy copybook file can be found in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX).

User Exit usage

The user exit module retrieves the full path and filename of the original JCL file or substituted file name. You can use the optional parameter JCLExitID to specify work to be done by the user exit. The maximum length for this string is 32 characters.

Before returning, the user exit program sets the return code ESue1-ReturnCode to 00 and specifies the new file to submit (ESue1-JCLfile). If necessary, the submission process can be stopped. MFBSIJCL ends with a return code of 207. To do this:

  • Set the return code ESue1-ReturnCode <> "00".
  • Set your own error message with ESue1-ReturnMsg.
  • MFBSIJCL Termination User Exit
Parent topic: Micro Focus Batch Scheduler Integration


MFBSIJCL Termination User Exit

Just before terminating, MFBSIJCL can invoke a termination user exit.

Use the parameter TerminateExit to specify the name of the termination user exit module to be called. Use the Mfbsiue2.cpy interface as shown.

      *    -- copybook "MFBSIUE2" --

       01  ES-UserExit-MFBSIJCL-Terminate.
      **>  MFBSIJCL exit's common area
           05  ES-UE-CommonArea            pic x(1024).
      **>  Input parameters
           *>  OS Environment
           05  ESue2-OS                    pic x(1).
               88 ESue2-Windows              value '0'.
               88 ESue2-UNIX                 value '1'.
           *>  SJoBID
           05  ESue2-Job-ID                pic x(16).
           *>  ES server name
           05  ESue2-ESserver              pic x(8).
           *>  Full name of JCL file that was submitted
           05  ESue2-JCLfile               pic x(256).
           *>  MFBSI_DIR directory
           05  ESue2-MFBSI-DIR             pic x(256).
           *>  Execution mode: submit JCL or JOB restart
           05  ESue2-ExecutionMode         pic x(01).
               88  ESue2-ExecNormal          value 'N'.
               88  ESue2-ExecRESTART         value 'R'.
           05  filler                      pic x(14).
      *
      **>  Input/Output parameters
           05  ESue2-ReturnCode            pic 9(9) comp-5 .
      *
      **>  Delimiter
           05  ESue2-X00                   pic x(1).

This interface copybook file can be found in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX).

A sample COBOL program mfbsiue2.cbl can be found in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits (Windows) or $COBDIR$COBDIR\cpylib (UNIX).

User exit usage

This user exit module can be used for various duties, such as cleaning up files produced by the JCL exit functionality. If necessary, you can reset the return code returned by MFBSIJCL.

Parent topic: User Exit Before Submission to Enterprise Server/JCL


Additional Notes

  • RETURN-CODE, User, System, and RTS ABEND Handling
  • Enabling CTF Tracing for MFBSIEMX
  • Troubleshooting
  • To Display Configuration Information and Region State
  • To Display MFBSIJCL Return Codes
Parent topic: Micro Focus Batch Scheduler Integration


RETURN-CODE, User, System, and RTS ABEND Handling

If a User, System, or RTS abend occurs in a job step, MFBSIJCL returns the decimal value of the user, system, or RTS status code by default. If this value is greater than 199, MFBSIJCL returns a final return code of 16 to the scheduler. Otherwise, the return code corresponds to the status code; for example, a user abend with return code 12 returns code 12.

Nevertheless, a USR, SYS, or RTS abend can return a specified return code to the scheduler. In the MFBSI configuration file, the parameters SYS-ABEND-RC, USR-ABEND-RC, and RTS-ABEND-RC can be set to force the OS return code to be returned to the scheduler in these cases.

Note: These parameters cannot be set on the command line for MFBSIJCL; they must be set in the configuration file.

This table shows some of the specific OS codes returned from MFBSIJCL.

Return Code | Description
200-250 | These values should be reserved for MFBSIJCL use. They indicate an error specific to MFBSIJCL, such as MFBSI_DIR not set, unknown or missing parameters, or error during job submission (CASSUB/CASOUT). See the topic on specific return codes issued by MFBSIJCL for descriptions of each return code.
208 | JES/JCL error detected.
209 | Job submission failed (See JobLog output).
211 | Job ended, no numeric RC returned.
0-16 | Usual error codes returned by Enterprise Server/MSS JCL (job execution).
0 | JOB execution successful.
16 | Unsuccessful JOB execution.

To see the full list of MFBSI-specific return codes, execute one of the following commands from an Enterprise Developer command prompt (Windows) or a UNIX command shell where $COBDIR is set.

mfbsijcl /rc
mfbsijcl -h
mfbsijcl -help
mfbsijcl -?
Note: The parameters are case insensitive, and may be specified using / or -.

In the job log written by MFBSIJCL, either in SJobId.Log, JOB#####.log, or via STDOUT, JCLSI messages provide additional information. For example:

JCLSI0013E JOB????? => Rc:213 Configuration parameter unknown in MFBSI.cfg
JCLSI0014E JOB????? Parameter: ES_Server=-rES
JCLSI0077I JOB Ended with OS RC=0213. 13:12:59
JCLSI0028E JOB????? => Rc:243 In MFBSI_DIR,"regionName.Started" not found.
JCLSI0077I JOB Ended with OS RC=0243. 14:09:33
JCLSI0050I JOB01039 IEFBR14 JOB Concluded. (SYS=00002054 Reason=00000000 )[Job abended] 14:12:38

where SYS 2054 (decimal) = x'806' (Program not found). System Abend.

JCLSI0050I JOB01209 MFJCLRC JOB Concluded.  (RTS=00000173 Reason=00000000 ) [Job abended]    12:33:38

where RTS 173 signals a called program not found.

The purpose of these messages is to allow additional scheduler error processing, if needed.

Notes:

  • If the decimal value of the JCL return-code is greater than 254, it is converted to the value 16, and returned to the scheduler. This is also true if the JCL return-code falls in the range 200 - 254 (which is reserved for MFBSIJCL use).
  • Micro Focus recommends to set SYS-ABEND-RC, USR-ABEND-RC and RTS-ABEND-RC in mfbsi.cfg to easily identify these kind of errors from a scheduler perspective. For example:
    SYS-ABEND-RC=21
USR-ABEND-RC=22
RTS-ABEND-RC=23
Parent topic: Additional Notes


Enabling CTF Tracing for MFBSIEMX

MFBSIEMX, the Event Manager user exit for MFBSI is CTF-enabled. Its activity can be traced using the Micro Focus Consolidated Tracing Facility. Use the following procedure to enable tracing for MFBSIEMX:

  1. Create a text file using this sample:
    # MFTRACE configuration file

#mftrace.emitter.textfile#Format = $(TIME) $(THREAD) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
#mftrace.emitter.textfile#location = C:\MicroFocus\ProjectName\ES_JCL\MFBSI\ES-MFBSI

mftrace.dest                     = binfile
mftrace.emitter.binfile#location = C:\MicroFocus\ProjectName\ES_JCL\MFBSI\ES-MFBSI

mftrace.level                 = none
mftrace.level.mfbsi           = info
mftrace.comp.mfbsi.emx#all    = true

    Replace C:\MicroFocus\ProjectName\ES_JCL\MFBSI\ES-MFBSI with your CTF trace files folder.

  2. Access your configuration information and add the line MFTRACE_CONFIG=[Full_Location_of_CTF_cfg.file] to your configuration file.

    For example:

    MFTRACE_CONFIG=C:\MicroFocus\ProjectName\ES_JCL\MFBSI\ES-MFBSI\ctf.cfg

  3. Stop and restart your enterprise server.
  4. In the CTF folder, verify that a file named casevmgr.textfile.log exists. The file created is based on the emitter selection. In Windows, the bin file can be examined with the CTF Viewer.
    Event | Description
    0 | MFBSIEMX initialization started.
    1 | MFBSI_DIR setting not found.
    2 | File can not be created in the folder specified by MFBSI_DIR. Check the file status code.
    3 | MFBSIEMX initialization ended.
    9 | Enterprise server shutdown process started.
    10 | Job execution started.
    11 | Job execution ended.
    12 | Job concluded.
    19 | Batch SEP termination.
    20 Unexpected file status during MFBSIEMX execution.
    Note: File status 0/005 in the associated data usually indicates a JCL error.
Parent topic: Additional Notes


Troubleshooting

For general MFBSI troubleshooting, perform the following steps to identify an issue:
  1. Shutdown the Enterprise Server.
  2. Clean up the MFBSI_DIR folder by deleting all files except your mfbsi.cfg file.
  3. Start Enterprise Server JCL from a command line. In Windows, from an Enterprise Developer command prompt (32-bit or 64-bit), enter casstart -rES_name. In UNIX/Linux, start a session for the defined Enterprise Server user by entering casstart -rES_name.
  4. Check the console log for a correct initialization of MFBSIEMX, and ensure that the Enterprise Server Event Manager has not been stopped by MFBSIEMX.
  5. Verify that a file named ES_name.Started exists in the folder specified by the MFBSI_DIR environment variable (where ES_name is the name of the Enterprise Server started with CASSTART). If this file does not exist, verify that you can create a file in the MFBSI_DIR folder.
  6. In Windows, from an Enterprise Developer command prompt (32-bit or 64-bit), validate MFBSIJCL by executing the command mfbsijcl /show. In UNIX/Linux, validate MFBSIJCL in a user session that will submit JCL (UNIX), by executing the command mfbsijcl /show. The console output should be similar to:

  7. Enter the CASSUB command to validate that you can submit and execute a job in Enterprise Server/MSS JCL. For example:
    • cassub -rES-name -jC:\...\JCL\rc00.jcl (Windows).
    • cassub -rES-name -j/.../JCL/rc00.jcl (UNIX/Linux).
    This creates a file named JOBnnnnn.sem in the MFBSI_DIR folder, where nnnnn is the job number assigned by the Enterprise Server/MSS JCL.
  8. Execute MFBSIJCL from the command line using the same parameters, using STDOUT to output to the console. For example:
    • mfbsijcl -rES-name -jC:\...\JCL\rc00.jcl SJOBID=StdOut (Windows).
    • mfbsijcl -rES-name -j/.../JCL\rc00.jcl SJOBID=StdOut (UNIX/Linux).
    Verify successful execution. The file JOB#####.sem is deleted when MFBSIJCL completes execution.
  9. Execute MFBSIJCL again from the command line using the same parameters, only specify a file for the output. For example:
    • mfbsijcl -rES-name -jC:\...\JCL\rc00.jcl SJOBID=SJOB01 (Windows).
    • mfbsijcl -rES-name -j/.../JCL\rc00.jcl SJOBID=SJOB01 (UNIX/Linux).
    Verify successful execution. Review the log file SJOB01.log in the MFBSI_DIR folder to help troubleshoot your issue.
    Tip: Most issues in UNIX/Linux are the result of access denied, case sensitivity or authorization errors.
Parent topic: Additional Notes


To Display Configuration Information and Region State

You can output the current configuration from the MFBSI global configuration file and MFBSI region state to the console.
Do one of the following:
  • For Windows, Choose Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt (32-bit) or (64-bit). Execute the command mfbsijcl /Show from the command prompt.
  • For UNIX, from a session where your COBOL environment is defined, enter mfbsijcl /Show.
Current configuration information and MFBSI region state output to STDOUT.
This is an example of the output.
JCLSI0000I MFBSI Version 3.0.06  Copyright (C) 2013 Micro Focus. All rights reserved. TIP_20131022

JCLSI0000I MFBSI_DIR: C:\MicroFocus\Netxproj\ES_JCL\MFBSI\ES-MFBSI
JCLSI0000I Region name: ES-MFBSI
JCLSI0000I MFBSI Global configuration file found:
JCLSI0000I       - ES-Server=-rES-MFBSI
JCLSI0000I       - SYS-ABEND-RC=20
JCLSI0000I       - USR-ABEND-RC=20
JCLSI0000I       - JCL-Submit=-jC:\MicroFocus\Netxproj\ES_JCL\MFBSI\JCL
JCLSI0000I       - JCL-Ext=Jcl
JCLSI0000I       - SJobID=JobNo
JCLSI0000I       - JESYSMSG
JCLSI0000I       - SkelProcessType=MFBSI
JCLSI0000I       - AutoEdit
JCLSI0000I MFBSI region state: up and running.
JCLSI0000I
JCLSI0000I Validate the Server state using the Web Administration.
------------------------------------------------------------------------
Note: The MFBSI determines region state based on the existence of the file [RegionName].Started or [RegionName].Shutdown in the folder defined by MFBSI_DIR.
Parent topic: Additional Notes


To Display MFBSIJCL Return Codes

To display MFBSIJCL return codes, do one of the following:

  • For Windows, start a 32-bit or 64-bit command prompt and enter mfbsijcl /rc.
  • For UNIX/Linux, from a session where your COBOL environment is defined, enter mfbsijcl /rc.

As an alternative, /?, -rc or -help may be used.

Parent topic: Additional Notes
Related reference
MFBSIJCL Return Codes


Using JCL User Exits

Certain events enable the user exit to alter the actions that follow the event. For example, when a job is submitted for execution, the user exit can modify the job or create a new one.

  • Introduction
  • Background Information
  • JCL/TSO Events and Actions
  • Event Scenarios
  • Event Logging
  • User Exit Interface Block (mfjdxit.cpy)
Parent topic: JCL Support


Introduction

The JCL component provides a facility called the JCL user exit, which enables you to monitor and control various events that occur during execution of a job or TSO session. Certain events enable the user exit to alter the actions that follow the event. For example, when a job is submitted for execution, the user exit can modify the job or create a new one.

Parent topic: Using JCL User Exits


Background Information

This section introduces information that you need to be familiar with before you can take advantage of JCL user exits.

  • MSS Processes
  • User Exit Invocation, Rules, and Guidelines
Parent topic: Using JCL User Exits


MSS Processes

When you submit a job (by clicking Submit on the JCL Control page of ESMAC, for example), a new process, called the parent process, is created in which job preparation and all resource allocation for all job steps of the job occurs. Then, if the job preparation and resource allocation is successful, for each program execution,MSS creates a child process in which the program runs. When the program finishes, the child process ends and the parent process wakes up to perform resource deallocation including such actions as disposition processing.

As far as the user exit is concerned, it has knowledge of the following:

  • All of the child process events in the child process for the execution of a single program only.
  • All of the parent process events in the parent process for the entire job (job and job step preparation for all of the job steps).

A user exit in the child process has no knowledge of events in the parent process, and vice versa.

Parent topic: Background Information


User Exit Invocation, Rules, and Guidelines

The user exit, which must be named MFJUXIT (unless overridden with the MFJUXIT environment variable), is optional and is invoked with the user exit interface block (mfjdxit.cpy) as the only parameter. It contains:
  • A header part that contains among other items, the event code of the event and the action code that represents the action that can be requested.
  • A data part that contains the data describing the event.
mfjdxit.cpy describes in detail all the event codes, actions codes, and data associated with each event. When looking at mfjdxit.cpy, note the following:
  • Field names containing -I- (for example JXIT-I-size) are input to the user exit and must not be modified.
  • Field names containing -U- (for example JXIT-U-PGM-alias) are used for input and output. On entry to the user exit, they are set as appropriate and may be changed by the user exit to an acceptable value upon return.
  • All character data is in ASCII (ANSI). Null values are those appropriate for the data type; that is blanks for character data, and zeros for numeric and binary data.

The user exit is called as events occur.

Most events occur in the batch initiator SEP. The exceptions are:
  • For jobs submitted via the ESMAC console, the Event-job-ready, Event-job-queued, and Event-job-stmt-info events occur in an Admin SEP.
  • For all other job submission methods, the Event-job-ready, Event-job-queued, and Event-job-stmt-info events occur in a Normal (standard) SEP.
  • For SSTM jobs, the job-started through job-ended events occur once in each Normal SEP, but might be reported in the console log as occurring in a batch initiator SEP.
  • Depending on the submission method, the Event-job-concluded event could occur in an Admin SEP or a Normal SEP; however, it occurs only if the job is not intended for execution (specifies TYPRUN=COPY or TYPRUN=SCAN) or if it fails submission due to JCL errors.

A JCL user exit can remember only the events in the process from which it was invoked.

If the user exit fails for any reason, it is disabled in the failing process for all subsequent events.

Note:
  • The user exit must be named MFJUXIT, unless the name is overridden with the MFJUXIT environment variable - e.g MFJUXIT=<optional location specification>MYEXIT.int (Windows), or for UNIX: MFJUXIT=<optional location specification>MYEXIT.so.

    The source for the sample exit is available in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits (Windows) or $COBDIR/src/enterpriseserver/exit (UNIX).

    We recommend you use this as the base to build an exit to suit your needs. It uses a copybook for the user exit interface block. The source for this copybook (mfjdxit.cpy) is in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) . A listing of mfjdxit.cpy is provided in the section under User Exit Interface Block (mfjdxit.cpy).

  • The user exit must use the ASCII (ANSI) character set. We recommend that it uses the non-mainframe COBOL dialect "MF".
  • The user exit is optional. It may reside in any folder accessible to the dynamic program loader, or an alternative location may be set explicitly with the MFJUXIT environment variable. If the MFJUXIT environment variable is set, and the specified module is not found, then the region will not start successfully.
  • You must write the user exit in COBOL.
  • Directive NOOUTDD should be specified.
Parent topic: Background Information


JCL/TSO Events and Actions

For each event, this section defines the key (but not all) inputs and outputs and the actions that can be requested for the event. The following actions apply to all events:

  • The action-continue action code (which is the default action code) indicates to JCL/TSO that it should continue with normal processing as if the exit had never been invoked for that event..
  • The action-shut-exit action code indicates to JCL/TSO that it should stop calling the user exit for all future events in this process for the current job or TSO session. This is intended as a performance aid. The user exit should still be coded so that it can receive future events and ignore them using the default action code action-continue.

The event names listed below correspond in part to the level-88 name assigned to the event code. Similarly, action code names listed correspond in part to the level-88 name assigned to the action code. Having access to the mfjdxit.cpy file will help your understanding of the facilities being described here.

Important: Not all of the events described in this section are currently implemented. The description of an event indicates if it is not currently implemented. If any of the unimplemented events would be of use in your organization, please contact your Micro Focus Sales or Support representative.
  • Event-after-PGM-call
    Indicates that the program has returned control to the system. One of these events occurs for each Event-before-PGM-call. The purpose of this event is to enable your user exit to perform any processing (such as deleting of programs that were loaded when the Event-before-PGM-call occurred) after the end of the program.
  • Event-before-PGM-call
    Indicates that the initial program (equivalent to the PGM= JCL parameter) is about to be invoked. This event occurs once for each step (for PGM= program), once for each CALL command (for the program named on the command), and once for each RUN subcommand of the DSN command (for the program named on the subcommand).
  • Event-CALL-ended
    Indicates that the job step has ended.
  • Event-CALL-ready
    Indicates that a TSO CALL command is about to be executed.
  • Event-CALL-started
    This event indicates that the CALL command has started.
  • Event-job-concluded
    Indicates that the job execution has completely finished and any spool output is ready for viewing or printing. The purpose of this event is to allow the user exit (or processes triggered by it) to access the job’s log and other spool output.
  • Event-job-ended
    Indicates that the job has ended. This event enables the user exit to examine or change job termination information.
  • Event-job-flushed
    Indicates that a job has been flushed, either because the user exit requested it to be done or for other reasons for which JCL may flush the job, for example an invalid job name or missing JOB card.
  • Event-job-JCL-error
    Indicates that the job failed with a JCL error.
  • Event-job-queued
    Indicates that the job has been parsed and put on either the Input Ready queue or the Input Hold queue.
  • Event-job-ready
    Indicates that a request to submit a job has been received, although the job being submitted has not been read and nothing has been done to it. Note that it is possible that the file containing the job does not even exist, but it very likely does. This event enables the user exit to verify or modify the job that is being submitted.
  • Event-job-started
    Indicates that the job has been started.
  • Event-job-stmt-info
    Indicates that the JOB CARD of a submitted job has been parsed, and the elements of the job card are passed to the user exit, some of which may be changed by the user exit.
  • Event-RUN-ended
    Indicates that the job step has ended.
  • Event-RUN-ready
    Indicates that a DSNRUN subcommand is about to be executed.
  • Event-RUN-started
    Indicates that the RUN subcommand of the DSN command has started.
  • Event-step-bypassed
    Indicates that the job step has been bypassed. Event-specific data is exactly is exactly the same as Event-job-started.
  • Event-step-ended
    Indicates that the job step has ended.
  • Event-step-ready
    Indicates that a job step is about to be executed. This event is similar to Event-before-PGM-call, except that this event occurs in the parent process and enables the user exit to change information such as program name, whereas Event-before-PGM-call does not.
  • Event-step-started
    Indicates that the job step has been started.
  • Event-TSO-ended
    Indicates that a TSO session has ended.
  • Event-TSO-started
    Indicates that a TSO session has been started.
  • Event-uxit-chgd-job-name
    Indicates that the user exit has changed the job name.
Parent topic: Using JCL User Exits


Event-after-PGM-call

Indicates that the program has returned control to the system. One of these events occurs for each Event-before-PGM-call. The purpose of this event is to enable your user exit to perform any processing (such as deleting of programs that were loaded when the Event-before-PGM-call occurred) after the end of the program.

This event and Event-before-PGM-call occur in the child process. All other events occur in the parent process. Your exit cannot remember any events that occurred in the parent process.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job termination type, for example, normal, user-abend, or system-abend.
  • Return or abend code and reason code.
  • All of the data presented for Event-job-started.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions
Related information
Event-before-PGM-call
Event-job-started


Event-before-PGM-call

Indicates that the initial program (equivalent to the PGM= JCL parameter) is about to be invoked. This event occurs once for each step (for PGM= program), once for each CALL command (for the program named on the command), and once for each RUN subcommand of the DSN command (for the program named on the subcommand).

For a job step, the difference between this event and Event-step-ready is that this event occurs in the child process giving the user exit the opportunity to do things on behalf of the program about to be invoked. For example, if you need to load special modules that the program will be using, this would be the time to do it. This event does not permit you to change data such as program name, whereas Event-step-ready does.

The purpose of this event is to allow your user exit to perform any processing (such a loading of programs to avoid name conflicts or for other reasons) before the program is invoked.

This event and Event-after-PGM-call occur in the child process. All other events occur in the parent process. Your exit cannot remember any events that occurred in the parent process.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.
  • Step start date and time.
  • Step name and number.
  • Procedure step name and number.
  • All of the data presented for Event-step-ready.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions
Related information
Event-after-PGM-call
Event-step-ready


Event-CALL-ended

Indicates that the job step has ended.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job termination type, for example, normal, user-abend, or system-abend.
  • Return or abend code and reason code.
  • Step start date and time.
  • Step name and number.
  • All of the data presented for Event-job-started.

Actions:

The following actions can be requested for this event:

action-term-info
Indicates that JCL should use the modified version of information such as termination type and return/abend code.
Parent topic: JCL/TSO Events and Actions
Related information
Event-job-started


Event-CALL-ready

Indicates that a TSO CALL command is about to be executed.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Program name and alias.
  • Program parameter string; that is, the equivalent of the PARM= parameter of JCL.

Actions:

The following actions can be requested for this event:

action-PGM-info
Indicates that JCL should use the modified program alias and parameter string.
action-abend
Indicates that the step should be abended with the system abend S822 (Region not available). Execution of subsequent steps will be then be based on this abend.
Parent topic: JCL/TSO Events and Actions


Event-CALL-started

This event indicates that the CALL command has started.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.
  • Step start date and time.
  • Step name and number.
  • Procedure step name and number.
  • All of the data presented for Event-step-ready.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions
Related information
Event-step-ready


Event-job-concluded

Indicates that the job execution has completely finished and any spool output is ready for viewing or printing. The purpose of this event is to allow the user exit (or processes triggered by it) to access the job’s log and other spool output.

Event-specific data:

Data available for this event includes:

  • Job conclusion type:
    • normal
    • JCL error
    • user abend
    • system abend
  • Job conclusion return and reason (always zero) codes.

    These are not applicable to jobs that ended, abended, were cancelled, or failed authorization. For all other job conclusions, return code may be changed.

    Reason code, if changed, will be ignored.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions


Event-job-ended

Indicates that the job has ended. This event enables the user exit to examine or change job termination information.

Event-specific data:

Data available for this event includes:

  • Job termination type, for example, normal, user-abend, or system-abend.
  • Return or abend code and reason code.
  • All of the data presented for Event-job-started.

Actions:

The following actions can be requested for this event:

action-term-info
Indicates that JCL should use the modified version of information such as termination type and return/abend code.
Parent topic: JCL/TSO Events and Actions
Related information
Event-job-started


Event-job-flushed

Indicates that a job has been flushed, either because the user exit requested it to be done or for other reasons for which JCL may flush the job, for example an invalid job name or missing JOB card.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job number.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions


Event-job-JCL-error

Indicates that the job failed with a JCL error.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions


Event-job-queued

Indicates that the job has been parsed and put on either the Input Ready queue or the Input Hold queue.

If it is on the Input Ready queue, it is able to be run by a JES Initiator for that job class. If it is on the Input Hold queue, it will remain there until it is 'released', either via the ESMAC page or the casout command.

Event-specific data:

Data available for this event includes:
  • The Input queue that the job has been placed on; this will be either the Input Ready queue or the Input Hold queue.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions


Event-job-ready

Indicates that a request to submit a job has been received, although the job being submitted has not been read and nothing has been done to it. Note that it is possible that the file containing the job does not even exist, but it very likely does. This event enables the user exit to verify or modify the job that is being submitted.

Event-specific data:

Data available for this event includes:

  • Job number assigned to the job.
  • Physical file name (and if available, MVS data set name) of the job that is to be submitted. The MVS data set name exists only if an MVS data set corresponding to the physical file exists. The SUBMIT command always has an MVS data set associated with it. For example, for a PDS member, the MVS data set name may be MFIDSA.CNTL(MYJOB) or for a PS, it may be S0310.S070508.J01364.D00002.SYSUT2 (data set name assigned to an INTRDR SYSOUT data set).
  • The type of job submission (scan only or job execution).
  • Whether the job will be animated; that is, executed in debug mode.

Actions:

The following actions can be requested for this event:

action-MVS-dsn
Indicates that JCL should use the modified MVS data set name and submit it as the job.
action-pc-fname-dsn
Indicates that JCL should use the modified physical filename and submit it as the job.
action-flush
Indicates that JCL should flush the job.
Parent topic: JCL/TSO Events and Actions


Event-job-started

Indicates that the job has been started.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions


Event-job-stmt-info

Indicates that the JOB CARD of a submitted job has been parsed, and the elements of the job card are passed to the user exit, some of which may be changed by the user exit.

Event-specific data:

Data available for this event includes the following, all of which may be changed by the user exit:

  • Job Name - if the Job name is changed by the user exit, the user exit will later be called with the event uxit-chgd-job-name.
  • Job Class
  • Message Class and Level
  • User ID - if the User ID is changed by the user exit, the job card will be re-parsed using the new User ID
  • Group
  • Typrun
  • Programmer Name
  • Notify Node and User ID
  • Password (current and new)
  • Seclabel
  • Perform
  • Account Value
  • PRTY

Actions:

The following actions can be requested for this event:

action-flush
Indicates that JCL should flush the job
Parent topic: JCL/TSO Events and Actions
Related reference
Event-uxit-chgd-job-name


Event-RUN-ended

Indicates that the job step has ended.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job termination type, for example, normal, user-abend, or system-abend.
  • Return or abend code and reason code.
  • Step start date and time.
  • Step name and number.
  • All of the data presented for Event-job-started.

Actions:

The following actions can be requested for this event:

action-term-info
Indicates that JCL should use the modified version of information such as termination type and return/abend code.
Parent topic: JCL/TSO Events and Actions
Related information
Event-job-started


Event-RUN-ready

Indicates that a DSNRUN subcommand is about to be executed.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Program name and alias.
  • Program parameter string; that is, the equivalent of the PARM= parameter of JCL.

Actions:

The following actions can be requested for this event:

action-PGM-info
Indicates that JCL should use the modified program alias and parameter string.
action-abend
Indicates that the step should be abended with the system abend S822 (Region not available). Execution of subsequent steps will be then be based on this abend.
Parent topic: JCL/TSO Events and Actions


Event-RUN-started

Indicates that the RUN subcommand of the DSN command has started.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.
  • Step start date and time.
  • Step name and number.
  • Procedure step name and number.
  • All of the data presented for Event-step-ready.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions
Related information
Event-step-ready


Event-step-bypassed

Indicates that the job step has been bypassed. Event-specific data is exactly is exactly the same as Event-job-started.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions
Related information
Event-job-started


Event-step-ended

Indicates that the job step has ended.

Event-specific data:

Data available for this event includes:

  • Job termination type, for example, normal, user-abend, or system-abend.
  • Return or abend code and reason code.
  • Step start date and time.
  • Step name and number.
  • All of the data presented for Event-job-started.

Actions:

The following actions can be requested for this event:

action-term-info
Indicates that JCL should use the modified version of information such as termination type and return/abend code.
Parent topic: JCL/TSO Events and Actions
Related information
Event-job-started


Event-step-ready

Indicates that a job step is about to be executed. This event is similar to Event-before-PGM-call, except that this event occurs in the parent process and enables the user exit to change information such as program name, whereas Event-before-PGM-call does not.

This event enables the user exit to examine or change program alias name, program name and parameter string information.

This event does not occur for TSO sessions.

Event-specific data:

Data available for this event includes:

  • Program name and alias.
  • Program parameter string; that is, the equivalent of the PARM= parameter of JCL.

Actions:

The following actions can be requested for this event:

action-PGM-info
Indicates that JCL should use the modified program name or program alias and/or parameter string. If the program name, as opposed to program alias, is changed, it is looked up in the alias list to determine if there is an alias for it. If so, the new alias will be used.
action-abend
Indicates that the step should be abended with the system abend S822 (Region not available). Execution of subsequent steps will be then be based on this abend.
Parent topic: JCL/TSO Events and Actions
Related information
Event-before-PGM-call


Event-step-started

Indicates that the job step has been started.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.
  • Step start date and time.
  • Step name and number.
  • Procedure step name and number.
  • All of the data presented for Event-step-ready.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions
Related information
Event-step-ready


Event-TSO-ended

Indicates that a TSO session has ended.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job termination type, for example, normal, user-abend, or system-abend.
  • Return or abend code and reason code.
  • All of the data presented for Event-job-started.

Actions:

The following actions can be requested for this event:

action-term-info
Indicates that JCL should use the modified version of information such as termination type and return/abend code.
Parent topic: JCL/TSO Events and Actions
Related information
Event-job-started


Event-TSO-started

Indicates that a TSO session has been started.

This event is currently not implemented.

Event-specific data:

Data available for this event includes:

  • Job number.
  • Job name.
  • Job start date and time.

Actions:

You cannot request any actions for this event; only the default action will take place.

Parent topic: JCL/TSO Events and Actions


Event-uxit-chgd-job-name

Indicates that the user exit has changed the job name.

Event-specific data:

Data available for this event includes the following:

  • Job name (new)
  • Old job name

Actions:

You cannot request any actions for this event; it is broadcast only.

Parent topic: JCL/TSO Events and Actions


Event Scenarios

This section briefly describes the events that can occur in each of the following environments:

  • JCL Scenarios
  • TSO in Batch (IKJEFTxx JCL) Scenarios
Parent topic: Using JCL User Exits


JCL Scenarios

The events that can occur and their sequence are as follows:

  • Event-job-ready, followed by one of:
    • Event-job-flushed
    • Event-job-JCL-error
    • Event-job-started, followed by (for each step in the job, one or more times) :
      1. Event-step-ready, followed by one of :
        • Event-step-bypassed
        • Event-step-started, followed by:
          1. Event-before-PGM-call
          2. Event-after-PGM-call
          3. Event-step-ended
      2. Event-job-ended
Parent topic: Event Scenarios


TSO in Batch (IKJEFTxx JCL) Scenarios

The events that can occur and their sequence are as follows:

  • Event-job-ready, followed by one of:
    • Event-job-flushed
    • Event-job-JCL-error
    • Event-job-started, followed by (for each step in the job, one or more times):
      1. Event-step-ready, followed by one of
        • Event-step-bypassed
        • Event-step-started, followed by:
          1. Event-before-PGM-call, followed by any combinations of:
            • For each CALL command (zero or more times):
              1. Event-CALL-ready
              2. Event-CALL-started, followed by:
                1. Event-before-PGM-call
                2. Event-after-PGM-call
              3. Event-CALL-ended
            • For each DSNRUN subcommand (zero or more times):
              1. Event-RUN-ready
              2. Event-RUN-started, followed by:
                1. Event-before-PGM-call
                2. Event-after-PGM-call
              3. Event-RUN-ended
          2. Event-after-PGM-call
      2. Event-job-ended
Parent topic: Event Scenarios


Event Logging

There is no currently no support for logging Interactive TSO activity or for the TSO execution in JCL (TSO in batch). JCL activity is logged in the MVS data set MFMVS.SYSLOG.

You can use the user exit to control the logging of the implemented events as follows:

  • If log-event-on is set to true, the default, all events are logged along with the action requested by the user exit.
  • If log-event-on-action is set to true, only events that request an explicit action (action codes other than action-continue and action-shut-exit) are logged along with the action requested by the user exit.
  • If log-event-off is set to true, none of the events are logged.

This logging state persists until it is changed again by the user exit. You can change the logging state as often as required.

Parent topic: Using JCL User Exits


User Exit Interface Block (mfjdxit.cpy)

This section presents a listing of the mfjdxit.cpy copybook used by JXIT. The source for this copybook is in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX).

      *===============================================================
      *   Copyright (C) 1997-2017 Micro Focus.
      *   All rights reserved.
      *===============================================================
      *
      *  MFJDXIT - JCL User Exit Control Block
      *    Contains interface information and is passed as a parameter
      *    to the JCL user exit (MFJUXIT) which is invoked as
      *       call  'MFJUXIT' using JXIT
      *
      *  Notes:
      *    1. It should be included as follows (e.g.)
      *         1 JXIT.
      *         COPY MFJDXIT REPLACING ==(tag)== BY ==JXIT==.
      *    2. Fields beginning with JXIT-I- ( (tag)-I- ) are Input
      *       to the user exit and must not be modified
      *       e.g. JXIT-I-size
      *    3. Fields beginning with JXIT-U- ( (tag)-U- ) are Input and
      *       Output. On entry to the user exit, they are set as
      *       appropriate and may be changed by the user exit to an
      *       acceptable value upon return.
      *       e.g. (tag)-U-PGM-alias
      *    4. All data is ASCII(ANSI). Null values are those appropriate
      *       for the data type. i.e. blanks for character data,
      *       zeros for numeric and binary data
      *
      * --Date--- Who --What------------------------------------------
      * 2002Mar04 DSA Initial version
      * 2003Apr25 DSA Changes as a result of addition of support for
      *               Event-step-ready
      * 2005Sep07 DSA Added new event event-job-concluded and
      *                         event event-job-purged
      * 2006Oct13 - Added  Event-job-stmt-info and
      *                    Event-uxit-chgd-jobname
      * 2017MAR27 ANF Added Event-job-queued
      *
      *===============================================================

      *===============================================================
      * Header
      *===============================================================
           3 (tag)-I-header.
      *      Size of this block
             5 (tag)-I-size        pic s9(8) comp.
      *      Unless otherwise noted, all events occur for
      *      JCL, TSO, and TSO-in-batch (PGM=IKJEFTxx or IDAEFTxx)
      *      Event code of event. Ignore undefined event codes.
             5 (tag)-I-event       pic s9(8) comp.
      *        The following events occur for JCL and TSO-in-batch
      *        and represent execution of a JCL JOB stream
               88 (tag)-I-event-job-ready        value  1.
               88 (tag)-I-event-job-stmt-info    value  25. *> This
                  *> event is broadcast ONLY to the JCL user exit
               88 (tag)-I-event-uxit-chgd-jobname  value 26. *>
                  *> event is broadcast ONLY to the event manager
               88 (tag)-I-event-job-queued       value 27.
               88 (tag)-I-event-job-concluded    value  2.
               88 (tag)-I-event-job-started      value  3.
               88 (tag)-I-event-job-purged       value  4.
               88 (tag)-I-event-job-ended        value  5.
      *        The following events occur for an interactive TSO
      *        session only
               88 (tag)-I-event-TSO-started      value  6.
               88 (tag)-I-event-TSO-ended        value  7.
      *        The following events occur for JCL and TSO-in-batch
      *        and represnt execution of "EXEC PGM=" JCL stmt
               88 (tag)-I-event-step-ready       value  8.
               88 (tag)-I-event-step-started     value  9.
               88 (tag)-I-event-step-ended       value 10.
               88 (tag)-I-event-step-bypassed    value 11.
      *        The following events occur for TSO and TSO-in-batch
      *        (IKJEFT01) and
      *        ... represent execution of the TSO "CALL pgm" command
               88 (tag)-I-event-CALL-ready       value 12.
               88 (tag)-I-event-CALL-started     value 13.
               88 (tag)-I-event-CALL-ended       value 14.
      *        ... represent execution of the DSN subcommand
      *            "RUN PROG(pgm)"
               88 (tag)-I-event-RUN-ready        value 15.
               88 (tag)-I-event-RUN-started      value 16.
               88 (tag)-I-event-RUN-ended        value 17.
      *
      *        Under MFE, all events, except Event-before-PGM-call and
      *        Event-after-PGM-call, occur in the parent process.
      *        These two events occur in the child process.
      *
      *        Under ESJCL,
      *         - Event-job-ready, Event-uxit-chgd-jobname, and
      *           Event-job-purged events
      *           occur only in the Service Execution Process (SEP),
      *           not in the initiator SEP.
      *         - Event-job-concluded event occurs in the standard SEP
      *           only if the job is not intended for execution (i.e.
      *           it is TYPRUN=COPY or TYPRUN=SCAN) or it has JCL
      *           errors. Otherwise this event occurs in the initiator
      *           SEP.
      *         - All other events occur in the initiator SEP.
      *
      *
      *        The following events occur for all environments
      *        for execution of a program following all
      *        "...-started" events.
      *        ***Note*** that these events occur in the child process
      *        that executes the program. Any working storage used by
      *        the user exit will not be the same as that for
      *        other events which occur in the parent process.
      *        In the parent process, your user exit will not remember
      *        information prior to "event-before-PGM-call" or after
      *        "event-after-PGM-call". Since both of these events
      *        occur in the child process, the user exit will be
      *        able to remember information between these two events.
               88 (tag)-I-event-before-PGM-call  value 18.
               88 (tag)-I-event-after-PGM-call   value 19.
      *        Event codes 25, 26 and 28 thru 50
      *        are reserverd for JCL User exit
      *        Event codes 51 thru 99 reserverd for JES Monitor
      *        88 (tag)-I-event-job-stmt-info       value 25. See above
      *        88 (tag)-I-event-uxit-chgd-jobname   value 26. See above
      *        Event codes for file open, close and delete events for
      *        use by HSF stats - passed to ES Event manager
               88 (tag)-I-event-dd-file-open        value 51.
               88 (tag)-I-event-dd-file-close       value 52.
               88 (tag)-I-event-dd-file-delete      value 53.

      *===============================================================
      * Action codes for all events. Upon return from the user exit,
      * action code indicates next course of action to be taken.
      * Upon entry to the user exit, it is set to zero.
      *===============================================================
             5 (tag)-U-action      pic s9(8) comp.
      *        The JCL engine should continue as if the exit were
      *        never invoked. Any modified data will be ignored.
               88 (tag)-U-action-continue         value 0.
      *        The JCL engine should not call the exit any more in
      *        this process for this job/TSO session
               88 (tag)-U-action-shut-exit        value 1.

      *===============================================================
      *        Action codes for: event-job-ready
      *===============================================================
      *          The JCL engine should use all modified
      *          fields except pc-fname
                 88 (tag)-U-action-MVS-dsn        value 2.
      *          The JCL engine should use all modified
      *          fields except MVS-dsn
                 88 (tag)-U-action-pc-fname       value 3.
      *          The JCL engine should flush the job
                 88 (tag)-U-action-flush          value 4.

      *===============================================================
      *        Action codes for: event-job-stmt-info
      *===============================================================
      *          The JCL engine should use all modified
      *          job information (action-continue)
      *   See    88 (tag)-U-action-flush above

      *===============================================================
      *        Action codes for: event-step-ready
      *                          event-CALL-ready
      *                          event-RUN-ready
      *===============================================================
      *          The JCL engine should use all modified fields
                 88 (tag)-U-action-PGM-info       value 5.
      *          The JCL engine should abend this step/program.
      *          The step/program will be abended with
      *          S822 (Region not available)
                 88 (tag)-U-action-abend          value 6.

      *===============================================================
      *        Action codes for: event-job-ended
      *                          event-TSO-ended
      *                          event-step-ended
      *                          event-CALL-ended
      *                          event-RUN-ended
      *===============================================================
      *          The JCL engine should use all modified fields
                 88 (tag)-U-action-term-info      value 7.

      *===============================================================
      *        Action codes for: event-job-concluded
      *===============================================================
      *          The JCL engine should use all modified fields
                 88 (tag)-U-action-concl-info     value 8.

      *===============================================================
      *        Action codes for: event-job-started
      *                          event-TSO-started
      *                          event-step-bypassed
      *                          event-step-started
      *                          event-CALL-started
      *                          event-RUN-started
      *                          event-before-PGM-call
      *                          event-after-PGM-call
      *         - No Action codes defined other than 0
      *===============================================================

             5 (tag)-U-log-event   pic x.
      *        The JCL engine should log all events (default)
               88 (tag)-U-log-event-on            value x'00'.
      *        The JCL engine should log only those events for which
      *        the exit requests a explicit action (non- 0 or 1)
               88 (tag)-U-log-event-on-action     value x'01'.
      *        The JCL engine not log any events unless
      *        requested to do so otherwise in the future
               88 (tag)-U-log-event-off           value x'02'.
      *        The JCL engine should log most events,
      *        currently all except
      *          - job-event-concluded
               88 (tag)-U-log-event-on-min        value x'03'.
             5                     pic x(2).
      *        Job number - may be 0 if not yet available
             5 (tag)-I-this-jobnum          pic 9(5).
      *        Job name - may be '????????' if not yet available
             5 (tag)-I-this-jobname         pic x(8).
      *        Process id
             5 (tag)-I-this-proc-id         pic 9(9) comp.

      *===============================================================
      * Event related data - varies by event
      *===============================================================
           3 (tag)-I-data          pic x(368).

      *===============================================================
      * Data for: event-job-ready
      *===============================================================
           3                                   redefines (tag)-I-data.
             5 (tag)-I-data-job-ready.
      *        reserved (used to be Job number). Use I-this-jobnum
               7                       pic 9(5).
      *        Fully qualified PC file name.
               7 (tag)-U-pc-fname      pic x(260).
      *        If available, MVS data set name (including member if
      *        a PDS) assoicated with pc-fname, otherwise blanks.
      *        e.g. MFIDSA.CNTL(MYJOB) (for a PDS member) or
      *             S0310.S070508.J01364.D00002.SYSUT2 (for PS)
               7 (tag)-U-MVS-dsn       pic x(54).
      *
               7 (tag)-I-submit-type   pic x(1).
                 88 (tag)-I-submit-type-exec value 'E'.
                 88 (tag)-I-submit-type-scan value 'S'.
               7 (tag)-I-animate       pic x(1).
                 88 (tag)-I-animate-on       value 'Y'.
                 88 (tag)-I-animate-off      value 'N'.

      *===============================================================
      * Data for: event-uxit-chgd-jobname
      *===============================================================
           3                                   redefines (tag)-I-data.
             5 (tag)-I-data-uxit-chgd-jobname.
               7 (tag)-I-old-jobname   pic x(8).
               *> This was the jobname on the job card. it was changed
               *> by the JCL user exit to -i-this-jobname (above).

      *===============================================================
      * Data for: event-job-stmt-info
      *===============================================================
           3                                   redefines (tag)-I-data.
             5 (tag)-U-data-job-stmt-info.
               7 (tag)-U-jobname        pic x(8).
               7 (tag)-U-typrun         pic 9(4) comp.
                 88 (tag)-U-typrun-scan value 0.
                 88 (tag)-U-typrun-exec value 1.
                 88 (tag)-U-typrun-anim value 2.
                 88 (tag)-U-typrun-copy value 3.
                 88 (tag)-U-typrun-hold value 4.
               7 (tag)-U-msgclass       pic x(1).
               7 (tag)-U-msglevel-1     pic 9(1).
               7 (tag)-U-msglevel-2     pic 9(1).
               7 (tag)-U-userid         pic x(8).
               7 (tag)-U-pgmr-name      pic x(20).
               7 (tag)-U-jobclass       pic x(1).
               7 (tag)-U-prty           pic 9(4) comp.   *> 0-15
               7 (tag)-U-group          pic x(8).
               7 (tag)-U-notify-node    pic x(8).
               7 (tag)-U-notify-userid  pic x(8).
               7 (tag)-U-password       pic x(32).
               7 (tag)-U-password-new   pic x(32).
               7 (tag)-U-seclabel       pic x(8).
               7 (tag)-U-job-perform    pic 9(4) comp. *> 1-999
               7 (tag)-U-acct-len       pic 9(4) comp.
               7 (tag)-U-acct-value     pic x(143).
               7                        pic x(81).

      *===============================================================
      * Data for: event-job-concluded
      *   - concl-return-code and concl-reason-code not applicable to
      *     concl-rc-ended, concl-rc-abended, concl-rc-cancelled,
      *     concl-rc-authfailed.
      *     concl-reason-code is currently not used and is always 0.
      *===============================================================
           3                                   redefines (tag)-I-data.
             5 (tag)-I-data-job-concl.
      *        Job processing outcome
               7 (tag)-I-concl-rc        pic s9(8) comp.
                 88 (tag)-I-concl-rc-ended            value 1.
                 88 (tag)-I-concl-rc-abended          value 2.
                 88 (tag)-I-concl-rc-jcl-error        value 3.
                 88 (tag)-I-concl-rc-scanned          value 4.
                 88 (tag)-I-concl-rc-scan-failed      value 5.
                 88 (tag)-I-concl-rc-flush-no-job     value 6.
                 88 (tag)-I-concl-rc-flush-bad-job    value 7.
                 88 (tag)-I-concl-rc-flush-uxit       value 8.
                 88 (tag)-I-concl-rc-copied           value 9.
                 88 (tag)-I-concl-rc-cancelled        value 10.
                 88 (tag)-I-concl-rc-authfailed       value 11.
               7 (tag)-U-concl-return-code         pic s9(8) comp.
               7 (tag)-U-concl-reason-code         pic s9(8) comp.

      *===============================================================
      * Data for: event-job-flushed
      *   See event-job-ready.
      *     - Only the first field is relevant
      *===============================================================

      *===============================================================
      * Data for: event-job-queued
      *===============================================================
           3                                   redefines (tag)-I-data.
             5 (tag)-I-data-job-queued.
               7 (tag)-input-queue            pic 9(02).
                 88 (tag)-I-input-hold-88     value 1.
                 88 (tag)-I-input-ready-88    value 3.

      *===============================================================
      * Data for: event-job-started
      *           event-TSO-started
      *           event-step-bypassed
      *     - Field names containing "step" are irrelevant for non-step
      *       related events
      *===============================================================
           3                                   redefines (tag)-I-data.
             5 (tag)-I-data-job-started.
      $if ILGEN set
               7                       pic x(24).
      $else
               7                       pointer.
               7                       pointer.
               7                       pointer.
      $end
      *
      *        Active System and Subsystems combinations are:
      *               System Subsystem
      *               ----------------
      *               JCL    JCL
      *               JCL    TSO  (IKJEFTxx)
      *               JCL    IMS  (DFSRC000)
      *               TSO    TSO
      *               TSO    IMS  (CALL DFSRC000)
      *               IMS    IMS
      *               CICS   CICS
      *
      *        Active system
               7 (tag)-I-system          pic x.
                 88  (tag)-I-system-JCL  value x'00'.
                 88  (tag)-I-system-TSO  value x'01'.
                 88  (tag)-I-system-ims  value x'02'.
                 88  (tag)-I-system-cics value x'03'.
                 88  (tag)-I-system-null value x'63'.
      *        Active subsystem
               7 (tag)-I-subsystem           pic x.
                 88  (tag)-I-subsystem-JCL       value x'00'.
                 88  (tag)-I-subsystem-TSO       value x'01'.
                 88  (tag)-I-subsystem-ims       value x'02'.
                 88  (tag)-I-subsystem-cics      value x'03'.
                 88  (tag)-I-subsystem-TSO-sstm  value x'0B'.
                 88  (tag)-I-subsystem-ims-sstm  value x'0C'.
                 88  (tag)-I-subsystem-cics-sstm value x'0D'.
                 88  (tag)-I-subsystem-null      value x'63'.
               7 (tag)-I-jobname   pic x(8).
               7 (tag)-I-userid    pic x(8).
               7 (tag)-I-jobstep   pic x(8).
               7 (tag)-I-procstep  pic x(8).
               7 (tag)-I-jobnum    pic 9(5).
               7 (tag)-I-stepnum   pic 9(3).
               7 (tag)-I-procstepnum pic 9(3).
               7                   pic x(1).
               7                   pic x(1).
               7 (tag)-I-msgclass  pic x(1).
               7 (tag)-I-msglevel1 pic x(1).
               7 (tag)-I-msglevel2 pic x(1).
               7                   pic x.
               7                   pic x(1).
      *        Dates in YYYYMMDD format, times in HHMMSShh
               7 (tag)-I-job-start-date pic 9(8).
               7 (tag)-I-job-start-time pic 9(8).
               7 (tag)-I-step-start-date pic 9(8).
               7 (tag)-I-step-start-time pic 9(8).
             5 (tag)-I-job-acct.
               7 (tag)-i-job-acct-len    pic 9(4) comp.
               7 (tag)-i-job-acct-value  pic x(143).
             5 (tag)-I-jobclass    pic x(01).

      *===============================================================
      * Data for: event-job-ended
      *           event-TSO-ended
      *           event-step-ended
      *           event-CALL-ended
      *           event-RUN-ended
      *           event-after-PGM-call
      *   See event-job-started
      *     - plus the following data
      *===============================================================
             5 (tag)-U-data-job-ended.
               7 (tag)-U-term-type                 pic x.
                 88 (tag)-U-term-type-normal       value x'00'.
                 88 (tag)-U-term-type-user-abend   value x'01'.
                 88 (tag)-U-term-type-sys-abend    value x'02'.
                 88 (tag)-U-term-type-RTS-err      value x'03'.
                 88 (tag)-U-term-type-RU-err       value x'04'.
                 88 (tag)-U-term-type-unknown      value x'05'.
               7                                   pic x(3).
               7 (tag)-U-term-return-code          pic s9(8) comp.
               7 (tag)-U-term-reason-code          pic s9(8) comp.
                 *> 88 (tag)-   Currently this is always 0. In the
                 *> future, a non-zero value would indicate a unique
                 *> reason within the return-code above.

      *===============================================================
      * Data for: event-step-ready
      *           event-step-started
      *           event-CALL-ready
      *           event-CALL-started
      *           event-RUN-ready
      *           event-RUN-started
      *           event-before-PGM-call
      *   See event-job-started
      *     - Plus the following data
      *     - Field names containing "step" are relevant
      *===============================================================
             5 (tag)-I-data-step-ready.
               7 (tag)-U-PGM-name          pic x(8).
               7 (tag)-U-PGM-alias         pic x(8).
               7 (tag)-U-PGM-parm.
                 9 (tag)-U-PGM-parm-len    pic s9(4) comp.
                 9 (tag)-U-PGM-parm-txt    pic x(96).

      *===============================================================
      *    HSF Data - passed to ES Event Manager
      *===============================================================
           3                               redefines (tag)-I-data.
             5 (tag)-I-data-file-open.
               7 (tag)-ddname                     pic x(08).
               7 (tag)-dsname                     pic x(54).
               7 (tag)-ds-type                    pic x(1).
               7 (tag)-ds-access-type             pic x(1).

           3                               redefines (tag)-I-data.
             5 (tag)-I-data-file-close.
               7 (tag)-ddname                     pic x(08).
               7 (tag)-dsname                     pic x(54).
               7 (tag)-io-cnt-read                pic s9(8).
               7 (tag)-io-cnt-write               pic s9(8).
               7 (tag)-io-cnt-rewrite             pic s9(8).
               7 (tag)-io-cnt-delete              pic s9(8).

           3                               redefines (tag)-I-data.
             5 (tag)-I-data-file-delete.
               7 (tag)-ddname                     pic x(08).
               7 (tag)-dsname                     pic x(54).

      *= End of MFJDXIT ==============================================
Parent topic: Using JCL User Exits


Using JCL Subsystem Exits

  • Introduction
  • SUBSYS with DD Statements and SVC 99 Text Units
  • Subsystem Exit Invocation, Rules, and Guidelines
  • Events and Actions
    For each event, this section defines the key (but not all) inputs and outputs and the actions that can be requested for the event.
  • Interaction with the Enterprise Server Printer Exit
  • Subsystem Exit Interface Block (mfjdsxit.cpy)
  • Subsystem Exit for OODA Subsystem (mfjyooda.cbl)
  • JCL (subsys1b.jcl)
Parent topic: JCL Support


Introduction

JCL provides a facility known as the JCL Subsystem Exit (SUBSYS), which allows an installation to customize the behavior required by a subsystem by monitoring events and controlling the resultant actions performed by the system.

Parent topic: Using JCL Subsystem Exits


SUBSYS with DD Statements and SVC 99 Text Units

SUBSYS can be specified as a keyword on a DD statement and as a Text Unit (TU) on SVC 99. In call cases, the syntax is equivalent to:

SUBSYS=(subsystem-name[,subsystem-subparameter]...)

Where :

  • subsystem-name is a 1-4 character subsystem name
  • subsystem-subparameter is 0-254 parameter strings, each 0-67 characters in length and separated by commas

For example, on the DD statement:

//someddn DD SUBSYS=(OODA,A,DKP39CPM,’PPP3’,STD,,USER),
    //           DSN=MFIDSA.SUBSYS1B.NEW.OODA.NOTUSED,
    //           OUTPUT=(*.OUTSJ,*.OUTHORSE)
  • subsystem-name is OODA
  • subsystem-subparameter strings are A, DKP39CPM, PPP3, etc. These treated as if it were coded as single 30-character string OODA,A,DKP39CPM,PPP3,STD,,USER
  • SUBSYS processing
Parent topic: Using JCL Subsystem Exits


SUBSYS processing

If the DD statement has the SUBSYS keyword and the subsystem-subparameter string contains DDNAME=x anywhere in the string, it is processed as if DDNAME=x was coded on the DD statement. This applies only to the JCL DD statement regardless of the subsystem-name. It does not apply to SVC99 Text Units (TUs).

For each DD with SUBSYS, the exit is given control once just before resource allocation. It is not given control during execution for other events such as OPEN, CLOSE and WRITE.

Parent topic: SUBSYS with DD Statements and SVC 99 Text Units


Subsystem Exit Invocation, Rules, and Guidelines

The user exit, which must be named MFJYssss, and where ssss is the subsystem-name, is optional and is invoked as follows:

CALL 'MFJYssss' USING SXIT

Where SXIT is the user exit interface block (mfjdsxit.cpy). It contains

  • A header part that contains among other items, the event code of the event and the action code that represents the action that can be requested.
  • A data part that contains the data describing the event.

mfjdsxit.cpy describes in detail all of the event codes, actions codes, and the data associated with each event. When looking at mfjdsxit.cpy, note the following:

  • Field names containing -I- (for example SXIT-I-size) are input to the subsystem exit and must not be modified.
  • Field names containing -U- (for example SXIT-U-PGM-alias) are used for input and output. On entry to the subsystem exit, they are set as appropriate and may be changed by the subsystem exit to an acceptable value upon return.
  • All character data is in ASCII (ANSI). Null values are those appropriate for the data type; that is blanks for character data, and zeros for numeric and binary data.

The subsystem exit is called as events occur.

If the user exit fails for any reason, it is disabled in the failing process for all subsequent events.

Note:
  • The user exit must be named mfjyssss.cbl. The source for each sample exit is available in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\exits (Windows) or $COBDIR$COBDIR\cpylib (UNIX). We recommend you use this as the base to build an exit to suit your needs. It uses a copybook for SXIT (the subsystem exit interface block). The source for this copybook, mfjdsxit.cpy, is in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/include (UNIX). A listing of mfjdsxit.cpy is provided in the topic Subsystem Exit Interface Block (mfjdsxit.cpy).
  • The subsystem exit must use the ASCII (ANSI) character set. We recommend that it uses the non-mainframe COBOL dialect as it is a PC-specific program.
  • The exit is optional. The .dll (Windows) or .so (UNIX) file for the subsystem exit must be placed in a directory that is specified in the search path of PATH (Windows) or $COBDIR (UNIX). If you want it to be in a location independent of the project, then you may place it in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin (UNIX).
  • You must write the subsystem exit in COBOL.
Parent topic: Using JCL Subsystem Exits
Related information
Subsystem Exit Interface Block (mfjdsxit.cpy)


Events and Actions

For each event, this section defines the key (but not all) inputs and outputs and the actions that can be requested for the event.

Event-specific data

The following action applies to all events:
  • The action-continue action code (which is the default action code) indicates to the system that it should continue with normal processing as if the exit had never been invoked for that event.

The event names listed below correspond in part to the level-78 name assigned to the event code. Similarly, action code names listed correspond in part to the level-78 name assigned to the action code. Having access to mfjdsxit.cpy, mfjyooda.cbl and subsys1b.jcl files will help your understanding of the facilities being described here.

This event indicates that the source for the DD is about to be allocated. The purpose of this event is to allow the subsystem exit to verify and/or modify the DD that is being processed.

This event and Event-before-PGM-call occur in the child process. All other events occur in the parent process. Your exit cannot remember any events that occurred in the parent process.

Data available for this event includes:
  • The subsystem-subparameter string length
  • A pointer to the subsystem-subparameter string
  • A dataset name if available
  • The type of dataset (permanent, SYSOUT, etc.)
The exit can view or change the information and request that the system use the changed information. The information that can be changed includes:
  • The subsystem-subparameter string length
  • The subsystem-subparameter string
  • The type of dataset
Actions that can be requested:
  • action-use-updated-data
Parent topic: Using JCL Subsystem Exits


Interaction with the Enterprise Server Printer Exit

If the exit changes the DD to a SYSOUT, the printer exit is, in addition to accessing normal sysout related information such as OUTPUT statements, able to access subsystem-subparameter string information allowing further customization of the produced sysout output.

Parent topic: Using JCL Subsystem Exits


Subsystem Exit Interface Block (mfjdsxit.cpy)

This section presents a listing of the mfjdsxit.cpy copybook used by SXIT.

For the most up-to-date information refer to the source for this copybook in your product installation.

 *>==============================================================
      *> Copyright ©) 1997-2008 Micro Focus (IP) Ltd.
      *>   All rights reserved.
      *>
      *> This sample source code is provided for use by users of
      *> Micro Focus products (the "Software") and may be used,
      *> modified and distributed as part of your application provided
      *> that you properly acknowledge the copyright of Micro Focus in
      *> this material.
      *>
      *> All conditions, warranties and undertakings, express or implied,
      *> statutory or otherwise, on the part of Micro Focus are excluded,
      *> including without limitation those of merchantability or fitness
      *> for purpose. This shall not, however, purport to exclude or
      *> restrict the liability of Micro Focus to any extent not
      *> permitted by law.
      *>
      *> IN NO EVENT WILL MICRO FOCUS BE LIABLE FOR ANY INDIRECT,
      *> INCIDENTAL, SPECIAL, CONSEQUENTIAL OR OTHER DAMAGES ARISING OUT
      *> OF THE USE OF THE DEMONSTRATION PROGRAM DISTRIBUTED WITH THE
      *> SOFTWARE, WHETHER OR NOT INFORMED OF THE POSSIBILITIES OF
      *> DAMAGES IN ADVANCE.  THESE LIMITATIONS APPLY TO ALL CAUSES OF
      *> ACTION, INCLUDING BREACH OF CONTRACT, BREACH OF WARRANTY, STRICT
      *> LIABILITY, AND ANY ACTIONS IN TORTS.
      *>==============================================================

      *>==============================================================
      *> mfjdsxit - Micro Focus Subsystem user exit parameter block
      *>   Contains interface information and is passed as a parameter
      *>   to the subsystem exit which is ivoked as:
      *>      call  subsys-exit using sxit
      *>
      *> Notes:
      *>   1. It should be included as follows (e.g.)
      *>        copy mfjdsxit replacing ==()== by ==sxit==.
      *>   2. Fields beginning with sxit-I- ( ()-I- ) are Input
      *>      to the subsystem exit and must not be modified
      *>      e.g. sxit-I-size
      *>   3. Fields beginning with sxit-U- ( ()-U- ) are Input and
      *>      Output. On entry to the subsystem exit, they are set as
      *>      appropriate and may be changed by the subsystem exit to
      *>      an acceptable value upon return.
      *>      e.g. ()-U-ds-type
      *>   4. All data is ASCII(ANSI). Null values are those appropriate
      *>      for the data type. i.e. blanks for character data,
      *>      zeros for numeric and binary data
      *>==============================================================
         1 ().
           3 ()-header.
             5 ()-I-size           pic x(2) comp-x. *>Size of this blk
             5 ()-I-event          pic x(2) comp-x. *> event code
                  *> this event occurs before DD is allocated
               78 ()-I-event-dd-alloc-pre        value  1.
             5 ()-U-action         pic x(2) comp-x. *>action requested
               *> The system should continue as if the exit were
               *> never invoked. Do not modify any data.
               78 ()-U-action-continue            value 0.
               *> The system should use updated data and continue.
               78 ()-U-action-use-updated-data    value 4.
               *> Others - TBD
             5                     pic x(2) comp-x.
           3 ()-data.
             5 ()-I-jseb-ptr       pointer.
             5 ()-U-ds-name-ptr    pointer.
             5 ()-U-ds-type        pic x(1).
               78 ()-U-ds-type-perm     value x'00'.
               78 ()-U-ds-type-temp     value x'80'.
               78 ()-U-ds-type-dummy    value x'40'.
               78 ()-U-ds-type-sysout   value x'20'.
               78 ()-U-ds-type-terminal value x'10'.
               78 ()-U-ds-type-pc       value x'08'.
             5                     pic x(3).
               *>  DD statement SUBSYS= value length
             5 ()-U-subsys-len     pic x(4) comp-x.
               *> if SUBSYS= value length (previous field) is non-zero,
               *> a ptr to entire (including subsystem name, the 1st
               *> subparameter) DD SUBSYS= string
             5 ()-U-subsys-ptr     pointer.
             5                     pic x(20).
      *>==============================================================
Parent topic: Using JCL Subsystem Exits


Subsystem Exit for OODA Subsystem (mfjyooda.cbl)

This exit, for event-dd-alloc-pre, changes the following listed items and requests, with action-use-updated-data, that the changed information be used to allocate the DD, thus allocating it as a SYSOUT.
  • Dataset type to SYSOUT
  • Dataset name pointer to null

It also verifies that it received the expected subsystem-subparameter string.

For the most up-to-date information refer to the source for this copybook in your product installation.

 *>==============================================================
*> Use directives at least: /CHARSET"ASCII"
*> /DIALECT"MF"
/DEFAULTBYTE"00"
*>==============================================================
*> Copyright ©) 1997-2008 Micro Focus (IP) Ltd.
*> All rights reserved.
*>
*> This sample source code is provided for use by users of
*> Micro Focus products (the "Software") and may be used,
*> modified and distributed as part of your application provided
*> that you properly acknowledge the copyright of Micro Focus in
*> this material.
*>
*> All conditions, warranties and undertakings, express or implied,
*> statutory or otherwise, on the part of Micro Focus are excluded,
*> including without limitation those of merchantability or fitness
*> for purpose. This shall not, however, purport to exclude or
*> restrict the liability of Micro Focus to any extent not
*> permitted by law.
*>
*> IN NO EVENT WILL MICRO FOCUS BE LIABLE FOR ANY INDIRECT,
*> INCIDENTAL, SPECIAL, CONSEQUENTIAL OR OTHER DAMAGES ARISING OUT
*> OF THE USE OF THE DEMONSTRATION PROGRAM DISTRIBUTED WITH THE
*> SOFTWARE, WHETHER OR NOT INFORMED OF THE POSSIBILITIES OF
*> DAMAGES IN ADVANCE. THESE LIMITATIONS APPLY TO ALL CAUSES OF
*> ACTION, INCLUDING BREACH OF CONTRACT, BREACH OF WARRANTY, STRICT
*> LIABILITY, AND ANY ACTIONS IN TORTS.
*>==============================================================

*>==============================================================
*> Note that subsystem exit is ways named as MFJYssss, where
*> ssss is the subssystem name (1st sub-parameter of SUBSYS=)
*>==============================================================

*>==============================================================
*> SUBSYS Subsystem exit for OODA subsystem
*>==============================================================

identification division.
program-id. MFJYOODA.
environment division.
file-control.
data division.
*>=============================================================
working-storage section.
77 subsys-val-expected pic x(30)     value
                    'OODA,A,DKP39CPM,PPP3,STD,,USER'.
77 msg-dest-both       pic 9(8) comp value 0.
77 msg-len             pic 9(8) comp value 80.
77 msg-txt             pic x(80).
77 w-len               pic 99999.
linkage section. copy "mfjdsxit.cpy" replacing ==()== by ==sxit==.
01 subsys-val          pic x(32000).

*>=============================================================
procedure division using by reference sxit.

* Dsa temp >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
* call 'CBL_DEBUGBREAK'
* Dsa temp <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
            evaluate sxit-I-event
    when sxit-I-event-dd-alloc-pre
      *>=======================================================
      *> DD is about to be allocated. Change to SYSOUT=*
      *>=======================================================
      move sxit-U-ds-type-sysout to sxit-U-ds-type
      set sxit-U-ds-name-ptr to null
      move sxit-U-action-use-updated-data to sxit-U-action
      *>=======================================================
      *> The code below is informational only. Note that
      *> - sxit-U-subsys-ptr points to the the entire
      *>   SUBSYS string with syntactic quotes removed.
      *> - sxit-U-subsys-len is the length of the string
      set address of subsys-val to sxit-U-subsys-ptr
      if sxit-U-subsys-len <> length subsys-val-expected
        move sxit-U-subsys-len to w-len
        move ' ' to msg-txt
        string 'MFJYOODA - Length should be 30 but is '
                                            delimited by size
                w-len                       delimited by size
        into msg-txt
        call 'MFJZLOG' using msg-dest-both msg-len msg-txt
      end-if
      if subsys-val(1:length subsys-val-expected) <>
         subsys-val-expected
        move ' ' to msg-txt
        string 'MFJYOODA - Value incorrect. It is '
                                             delimited by size
                subsys-val(1:length subsys-val-expected)
                                             delimited by size
        into msg-txt
        call 'MFJZLOG' using msg-dest-both msg-len msg-txt
      end-if
      *> move subsys-val(1:sxit-U-subsys-len) to ...
      *>=======================================================
      goback
    when other
      *>=======================================================
      *> Ignore all other events
      *>=======================================================
      continue
  end-evaluate
  goback.
  *>===========================================================
Parent topic: Using JCL Subsystem Exits


JCL (subsys1b.jcl)

For the most up-to-date information refer to the source for this copybook in your product installation.

//MFIDSA1B JOB 'SUBSYS TESTS - VIA JCL',CLASS=A,MSGCLASS=A
  //OUTSJ    OUTPUT CLASS=X,DEST=SANJOSE.DAVINDER,DEFAULT=YES
  //OUTNWB   OUTPUT CLASS=Y,DEST=GARDEN.CLIVE,DEFAULT=YES
  //OUTHORSE OUTPUT CLASS=M,DEST=HORSES.THAIUSER,DEFAULT=NO
  //*-------------------------------------------------------------------
  //STEP1 EXEC PGM=IDCAMS
  //SYSPRINT DD SYSOUT=*
  //SYSUTX DD *
  REC1
  REC2
  //SYSIN DD *
  REPRO IFILE(SYSUTX) OFILE(OODA )
  REPRO IFILE(SYSUTX) OFILE(NONE )
  //OODA DD SUBSYS=(OODA,A,DKP39CPM,PPP3,STD,,USER),
 //        DSN=MFIDSA.SUBSYS1B.NEW.OODA.NOTUSED,
 //        OUTPUT=(*.OUTSJ,*.OUTHORSE)
 //NONE DD SUBSYS=(NONE,A,DKP39CPM,PPP3,STD,,USER),
 //        DSN=MFIDSA.SUBSYS1B.NEW.NONE.DELETED,
 //        OUTPUT=(*.OUTSJ,*.OUTHORSE)
//
Parent topic: Using JCL Subsystem Exits


REXX Support

  • Introduction
  • JCL Environment
  • Passing Parameters
  • Including Host Commands
  • Debugging an Exec
    You can use the REXX debugging facility to help you debug an exec. It lets you interact with the exec while it is running and monitor the values of variables.
  • Specifying Record Length for Zero-length Line Sequential Files
  • Specifying Alternative Characters for the OR, NOT and CONCAT Operators
  • Restrictions
Parent topic: JCL Support


Introduction

REXX is a high-level language with extensive facilities for manipulating text. CLISTs are not supported under Enterprise Server so we recommend that you convert your CLISTs to REXX programs.

For more information about the REXX language and how it is used, see the IBM OS/390 TSO/E REXX Reference and IBM OS/390 TSO/E REXX User's Guide.

A REXX program is called an exec. Before running an exec, you need to add the exec to your project, or download it from the mainframe, in the usual way. All REXX execs should start with a comment containing the character string REXX so that they can be distinguished from TSO CLISTs. For example:

/************** REXX **************/

REXX execs should have the file extension .rex.

Optionally, you can define an exec as a member of a partitioned data set (PDS). The DD names SYSEXEC and SYSPROC are normally used for PDSs containing REXX execs. More than one PDS can be allocated to each of these DD names. A SYSEXEC PDS can contain only execs.

MSS interprets an exec as it is run. There are no preceding compilation and linking stages.

MSS supports the use of REXX execs only in the JCL (non-TSO) environment. This can be used for execs that do not need interaction with the user and do not need access to TSO services.

Parent topic: REXX Support
Related information
JCL (non-TSO) environment


JCL Environment

In the JCL environment, you can use the IRXJCL utility to run a REXX exec.

For example, the following JCL jobstream runs the REXX exec named jcltest in the PDS named userid.rexx.exec that has been allocated to SYSEXEC.

//jobname  JOB ............
//*
//jobstep  EXEC PGM=IRXJCL,PARM='JCLTEST'
//SYSEXEC  DD DSN=USERID.REXX.EXEC,DISP=SHR
//SYSTSPRT DD SYSOUT=A
//SYSTSIN  DD *
input to exec
/*
//
Parent topic: REXX Support


Passing Parameters

You can pass parameters to a REXX exec in the usual way, for example:

  • rexx(add) 42 21 exec
  • add 42 21
  • %ADD 42 21
  • //jobstep  EXEC PGM=IRXJCL,PARM='ADD 42 21'

In the exec named add, you can use an ARG instruction to receive the two parameters, 42 and 21.

Parent topic: REXX Support


Including Host Commands

You can include a host command in a REXX exec by enclosing it in quotation marks, for example:

"EXECIO * DISKR MYINDD (FINIS STEM MYVAR"

The REXX language processor passes the command and any other source code that it does not recognize to the host command environment for execution.

MSS emulates the MVS host command environment. If you use a host command that is not recognized by the environment, the return-code variable RC is set to -3.

You can use the ADDRESS built-in function to find the name of the current environment and the ADDRESS instruction to change it.

Parent topic: REXX Support


Debugging an Exec

You can use the REXX debugging facility to help you debug an exec. It lets you interact with the exec while it is running and monitor the values of variables.

The TRACE instruction lets you start and control the debugging facility from within an exec.

Parent topic: REXX Support


Specifying Record Length for Zero-length Line Sequential Files

The MFREXX_LSEQ_RECSIZE_MAX environment variable enables you to specify 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.

You should set the environment variable before you start the enterprise server in the Configuration Information field on the Add Server or Edit Server pages of ES Admin, as follows:

[ES-Environment]
MFREXX_LSEQ_RECSIZE_MAX=rec-length

Alternatively, you can set in on the command line before you start the enterprise server:

SET MFREXX_LSEQ_RECSIZE_MAX=rec-length
MFREXX_LSEQ_RECSIZE_MAX=rec-length
export MFREXX_LSEQ_RECSIZE_MAX

where rec-length is the record length to use. The default is 255, which is the minimum value you can use. Specifying an invalid value, or a value less than 255, results in the default value being used.

Parent topic: REXX Support


Specifying Alternative Characters for the OR, NOT and CONCAT Operators

If you need to use characters other than the defaults for REXX's OR, NOT and CONCAT operators, MSS enables you to do this using three environment variables: MFREXX_OR, MFREXX_NOT and MFREXX_CONCAT. You must set these environment variables before you start the enterprise server for them to take effect, either in the Configuration Information field on the Add Server or Edit Server pages of ES Admin or on the command line.

You can specify one or more characters for each operator, and each character you specify is used in addition to the default operator; that is "|" for OR, "¬" for NOT and "||" for CONCAT. When specifying additional characters, you must ensure that each additional character is defined in single or double quotes, or in hexadecimal. When specifying more than one character, separate each one with a space or comma. Any error in the specification of the additional characters, including the specification of alphabetic or numeric characters, results in the environment variable being ignored.

  • Examples:
Parent topic: REXX Support


Examples:

[ES-Environment]
MFREXX_NOT="^"
MFREXX_NOT=0x5e "!"
MFREXX_NOT=X'5e' '!' "~"
Parent topic: Specifying Alternative Characters for the OR, NOT and CONCAT Operators


Restrictions

The following mainframe REXX facilities are not supported by MSS:

  • Sequence numbers in the last eight bytes of fixed-length source records are recognized but no checking is done on the order of these numbers. Sequence numbers in variable-length records are not recognized.
  • The TRACE S instruction is syntactically allowed but does not trace the remaining clauses in the exec. The exec is fully syntax checked when it is first loaded.
  • Numeric options entered during interactive debugging are not supported.
  • CICS REXX is not supported.
  • Compiled REXX execs are not supported.
  • APPCMVS, ATTACH, ATTACHMVS, ATTACHPGM, CONSOLE, CPICOMM, ISPEXEC, ISREDIT, LINK, LINKMVS, LINKPGM, and LU62 host command environments are not supported:
  • User-defined host command environments are not supported.
  • The following REXX programming services are not supported:
    • IRXEXCOM - variable access routine
    • IRXEXEC - exec processing routine
    • IRXHLT - halt condition routine
    • IRXIC - trace and execution control routine
    • IRXINIT - initialization routine
    • IRXLIN - LINESIZE function routine
    • IRXRLT - get result routine
    • IRXSAY - SAY instruction routine
    • IRXSUBCM - maintain entries in the host command environment table
    • IRXTERM - termination routine
    • IRXTXT - text retrieval routine
  • Replaceable routines and exits are not supported.
  • DBCS is not supported.
Parent topic: REXX Support


DSNREXX Support (Technology Preview)

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.

The Micro Focus support parallels DSNREXX on DB2 for z/OS but with the following limitation: Micro Focus DSNREXX is currently only available under Enterprise Server using the ODBC XA switch module on Windows platforms for SQL Server and DB2 LUW only. Additionally, UNIX support for DB2 LUW is available on some platforms. See Additional Software Requirements on Windows or Additional Software Requirements for Micro Focus Enterprise Developer Unix Components for more information.

The following table shows REXX static SQL statements and indicates whether they are supported using DB2 LUW:

REXX Statement | Supported | Notes
CALL | Partially | Only supports non-result set CALLs.
CLOSE | Yes |
CONNECT | Yes |
DECLARE CURSOR | Yes |
DESCRIBE prepared statement | Yes |
DESCRIBE CURSOR | No |
DESCRIBE INPUT | Yes |
DESCRIBE PROCEDURE | No |
EXECUTE | Yes |
EXECUTE IMMEDIATE | Yes |
FETCH | Yes |
OPEN | Yes |
PREPARE | Yes |
RELEASE connection | Partially | Syntax supported - Only performs a DISCONNECT.
SET CONNECTION | No |
SET CURRENT PACKAGE PATH | Yes |
SET CURRENT PACKAGESET | Partially | See Setting Isolation Level.
SET host variable = CURRENT DATE | Yes |
SET host variable = CURRENT DEGREE | Yes |
SET host variable = CURRENT MEMBER | Yes |
SET host variable = CURRENT PACKAGESET | No | DB2 LUW does not support this special register.
SET host variable = CURRENT PATH | Yes |
SET host variable = CURRENT SERVER | Yes |
SET host variable = CURRENT SQLID | Yes |
SET host variable = CURRENT TIME | Yes |
SET host variable = CURRENT TIMESTAMP | Yes |
SET host variable = CURRENT TIMEZONE | Yes |

The following table shows REXX static SQL statements and indicates whether they are supported using SQL Server with HCOSS.

Note: You must run the HCOSS install scripts before trying to access the supported special registers. See DSN command for more information.
REXX Statement | Supported | Notes
CALL | No |
CLOSE | Yes |
CONNECT | Yes |
DECLARE CURSOR | Yes |
DESCRIBE prepared statement | Yes |
DESCRIBE CURSOR | No |
DESCRIBE INPUT | Yes |
DESCRIBE PROCEDURE | No |
EXECUTE | Yes |
EXECUTE IMMEDIATE | Yes |
FETCH | Yes |
OPEN | Yes |
PREPARE | Yes |
RELEASE connection | Partially | Syntax supported - Only performs a DISCONNECT.
SET CONNECTION | No |
SET CURRENT PACKAGE PATH | No | HCOSS/SQL Server does not support this special register.
SET CURRENT PACKAGESET | Partially | See Setting Isolation Level.
SET host variable = CURRENT DATE | Yes |
SET host variable = CURRENT DEGREE | No | HCOSS/SQL Server does not support this special register.
SET host variable = CURRENT MEMBER | No | HCOSS/SQL Server does not support this special register.
SET host variable = CURRENT PACKAGESET | No | HCOSS/SQL Server does not support this special register.
SET host variable = CURRENT PATH | No | HCOSS/SQL Server does not support this special register.
SET host variable = CURRENT SERVER | Yes |
SET host variable = CURRENT SQLID | Yes |
SET host variable = CURRENT TIME | Yes |
SET host variable = CURRENT TIMESTAMP | Yes |
SET host variable = CURRENT TIMEZONE | Yes |

The SET CURRENT SCHEMA statement is not supported. For example:

Sqlsmt = "SET CURRENT SCHEMA PRODA"
ADDRESS DSNREXX "EXECSQL EXECUTE IMMEDIATE :Sqlsmt"

You must start each SQL statement with EXECSQL, followed by either:

  • An SQL statement enclosed in single or double quotes.
  • A REXX variable that contains the SQL statement.

For example:

ADDRESS DSNREXX EXECSQL “ROLLBACK”
rexxvar=”ROLLBACKT”
ADDRESS DSNREXX EXECSQL rexxvar
  • Equivalent Statements
  • Copybooks
  • Manipulating SQL Data
  • Setting the Isolation Level
  • SQL Error Checking
  • REXX SQLDA
  • JCL
  • CTF Tracing
Parent topic: JCL Support
Related concepts
Technology Preview Features
Additional Software Requirements on Windows
Additional Software Requirements for Micro Focus Enterprise Developer UNIX Components
Related reference
Setting the Isolation Level
DSN command


Equivalent Statements

The following statements run under z/OS but are not currently supported:

Not Supported | Equivalent Statement
CALL SQLDBS 'ATTACH TO' -ssid | ADDRESS DSNREXX 'CONNECT' -ssid
CALL SQLDBS 'DETACH' | ADDRESS DSNREXX 'DISCONNECT'
CALL SQLEXEC | ADDRESS DSNREXX 'EXECSQL'
Parent topic: DSNREXX Support (Technology Preview)


Copybooks

The EXECSQL INCLUDE statement is not valid for REXX. All host variables used in REXX must be defined as single data items, unless using SQLDA variables.

Parent topic: DSNREXX Support (Technology Preview)


Manipulating SQL Data

If you want to execute an SELECT, UPDATE, INSERT, or DELETE statement you must use an EXECSQL PREPARE, EXECUTE, or EXECUTE IMMEDIATE statement.

For example:

SQLSTMT= ,
'SELECT FIRSTNME, MIDINIT, LASTNAME' ,
'  FROM EMP WHERE EMPNO >= ? WITH UR'

ADDRESS DSNREXX "EXECSQL PREPARE S1 FROM :SQLSTMT"

IF SQLCODE \= "0" THEN DO
    SAY "PREPARE  FAILED "
    CALL DBERROR
END

ADDRESS DSNREXX "EXECSQL DECLARE C1 CURSOR FOR S1"
HVEMPNO = '000200'
ADDRESS DSNREXX "EXECSQL OPEN C1 USING :HVEMPNO"

IF SQLCODE \= "0" THEN DO
    SAY "OPEN FAILED "
    CALL DBERROR
END

 ADDRESS DSNREXX
       "EXECSQL FETCH C1 INTO :HV1, :HV2 :IV2,  :HV3"

  If SQLCODE = 0 Then Do
      SAY "FETCH =  " HV1 " " IV2 " " HV3
     END
ADDRESS DSNREXX "EXECSQL CLOSE C1"
Parent topic: DSNREXX Support (Technology Preview)


Setting the Isolation Level

You can use the SET CURRENT PACKAGESET statement to set the isolation level of the transaction. The table below lists the package names, the corresponding isolation levels and its equivalent COBOL ODBC SQL statements:

Package Name | Isolation Level | Equivalent COBOL ODBC SQL statement
DSNREXRR | Repeatable Read (RR) | EXEC SQL SET TRANSACTION ISOLATION REPEATABLE READ END-EXEC
DSNREXRS | Read Stability (RS) | EXEC SQL SET TRANSACTION ISOLATION SERIALIZABLE END-EXEC
DSNREXCS | Cursor Stability (CS) | EXEC SQL SET TRANSACTION ISOLATION READ COMMITTED END-EXEC
DSNREXUR | Uncommitted Read (UR) | EXEC SQL SET TRANSACTION ISOLATION READ UNCOMMITTED END-EXEC

For example, you can set the isolation level to repeatable read by executing the following code:

ADDRESS DSNREXX "EXECSQL SET CURRENT PACKAGESET=’DSNREXRR’ "

Using SET CURRENT PACKAGESET with a package name not listed in the table results in an SQL error. See SET TRANSACTION ISOLATION for more information.

Parent topic: DSNREXX Support (Technology Preview)
Related concepts
DSNREXX Support (Technology Preview)


SQL Error Checking

The EXECSQL WHENEVER statement is not valid for REXX. You must check either the SQLCODE or SQLSTATE value for errors or warnings after each EXECSQL call. Additionally, after an EXECSQL call the REXX RC special variable is set to a return code. Valid return codes are:

0
No SQL warning or error occurred.
+1
An SQL warning occurred.
-1
An SQL error occurred.
-3
Invalid or unsupported token found after DSNREXX.

For example:

SSID = "DB2T"
ADDRESS MVS "SUBCOM DSNREXX"
IF RC THEN S_RC = RXSUBCOM('ADD','DSNREXX','DSNREXX')
ADDRESS DSNREXX "CONNECT" SSID
IF RC /= 0 THEN DO
   SAY "FAILURE TO CONNECT TO DATABASE"
   EXIT 8
END

If you try to use Micro Focus DSNREXX with any DBMS other than DB2 LUW or SQL Server the return code of -1 is returned (SQL error) after the DSNREXX "CONNECT" statement.

You can check REXX SQLCA variables for more information about the SQL error or warning. You do not need to define these variables:
  • SQLCODE
  • SQLERRMC
  • SQLERRP
  • SQLERRD.1
  • SQLERRD.2
  • SQLERRD.3
  • SQLERRD.4
  • SQLERRD.5
  • SQLERRD.6
  • SQLWARN.0
  • SQLWARN.1
  • SQLWARN.2
  • SQLWARN.3
  • SQLWARN.4
  • SQLWARN.5
  • SQLWARN.6
  • SQLWARN.7
  • SQLWARN.8
  • SQLWARN.9
  • SQLWARN.10
  • SQLSTATE
Parent topic: DSNREXX Support (Technology Preview)


REXX SQLDA

The following EXECSQL statements require a REXX SQLDA:

CALL … USING DESCRIPTOR descriptor-name

DESCRIBE statement-name INTO descriptor-name

DESCRIBE INPUT statement-name INTO descriptor-name

EXECUTE … USING DESCRIPTOR descriptor-name

FETCH … USING DESCRIPTOR descriptor-name

OPEN … USING DESCRIPTOR descriptor-name

PREPARE … INTO descriptor-name

You can have more than one SQLDA in your REXX procedure. The SQLDA name consists of a set of REXX variables with a common stem. The stem must be a REXX variable name that does not contain periods and is the same as the descriptor-name value used in the EXECSQL statement. In the following example, the stem name is INSQLDA:

ADDRESS DSNREXX
   "EXECSQL DESCRIBE INPUT S2 INTO :INSQLDA "
   IF SQLCODE \= "0" THEN DO
      SAY "DESCRIBE INPUT FAILED "
      CALL DBERROR
   END

   INSQLDA.1.SQLDATA = HV1
   INSQLDA.1.SQLIND  = 0           /* Input variable is not null    */
   INSQLDA.2.SQLDATA = HV2
   INSQLDA.2.SQLIND  = 0           /* Input variable is not null    */
   INSQLDA.3.SQLDATA = HV3
   INSQLDA.3.SQLIND  = 0           /* Input variable is not null    */
   INSQLDA.4.SQLDATA = HV4
   INSQLDA.4.SQLIND  = 0           /* Input variable is not null    */

The following field make up the SQLDA when used with DB2 LUW:

Variable name | Usage | Notes
stem.SQLD | Number of columns described. |

Each SQLDA contains stem.SQLD of the following REXX variables. This set of variables is equivalent to the SQLVAR structure of SQLDA for other languages with some variables unique to REXX. The number of occurrences of the SQLDA SQLVAR structure is equivalent to 1<=n<=stem.SQLD.

stem.n.SQLTYPE | Data type of column. |
stem.n.SQLLEN | Length of column except for DECIMAL or NUMERIC columns. |
stem.n.SQLLEN.SQLPRECISION | Precision for DECIMAL or NUMERIC columns. |
stem.n.SQLLEN.SQLSCALE | Scale of DECIMAL or NUMERIC columns. |
stem.n.SQLCCSID | CCSID of the string column. | Not supported
stem.n.SQLUSECCSID | New CCSID for SQLDATA. | Not supported
stem.n.SQLLOCATOR | For procedures, result set locator. | Not supported
stem.n.SQLDATA | Value of input or output host variable depending on statement used. |
stem.n.SQLIND | Null value indicator: set to 0 if SQLDATA is not NULL and -1 if column is NULL or is being set to NULL. |
stem.n.SQLNAME | Name of column. |
Parent topic: DSNREXX Support (Technology Preview)


JCL

To run a REXX procedure you use the same JCL that is used to run any REXX procedure. If you are emulating MVS, run either IKJEFT01 or IRXJCL. If you are emulating TSO, run IKJEFT01.

For example:

//REXTEST JOB 'TEST DSNREXX SUPPORT',CLASS=A,MSGCLASS=A
//*
//* Test the REXX engine using IKJEFT01
//*
//STEP10 EXEC PGM=IKJEFT01
//SYSEXEC  DD DSN=USER.TEST.EXEC,DISP=SHR
//SYSTSIN  DD *
rextest1
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//*
//* Test the REXX engine using IRXJCL
//*
//STEP30   EXEC PGM=IRXJCL,PARM='rextest1'
//SYSEXEC   DD DSN=USER.TEST.EXEC,DISP=SHR
//SYSTSPRT  DD SYSOUT=*
//SYSTSIN   DD DUMMY

Where file rextest1.rex contains the REXX procedure.

For a complete example of DSNREXX support, see Tutorial: DSNREXX under mainframe tutorials.

Parent topic: DSNREXX Support (Technology Preview)
Related tasks
Tutorial: DSNREXX


CTF Tracing

You can enable CTF tracing for REXX procedures by creating a CTF configuration file and turning on CTF tracing in Enterprise Server.

For example, the CTF configuration file might look like this:

mftrace.dest = binfile
mftrace.emitter.binfile#location  = C:\Users\Public\REXXSAMPLE\rexx
mftrace.level.mf.rexx             = debug

mftrace.comp.mf.rexx#api          = true
mftrace.comp.mf.rexx#commands     = true
mftrace.comp.mf.rexx#exec         = true
mftrace.comp.mf.rexx#execload     = true

Where mftrace.emitter.binfile#location specifies the location you want the trace file to be located. You must specify the CTF trace configuration file to be use in the Enterprise Server Administration user interface. In the Configuration Information field, specify the MFTRACE_CONFIG environment variable, for example:

Parent topic: DSNREXX Support (Technology Preview)


Invoking JCL from CICS

There are two widely-used methods of invoking JCL from a CICS application:

  1. Submitting JCL via the Internal Reader
    The internal reader is a logical device similar to a card reader that lets you submit JCL jobs via JES.
  2. Submitting JCL via SSTM and the CICS Spooling Facility
    If you want to use the CICS spooling facility to submit JCL, you need to activate SSTM for your Enterprise Server.
Parent topic: JCL Support


Submitting JCL via the Internal Reader

The internal reader is a logical device similar to a card reader that lets you submit JCL jobs via JES.

To submit JCL via the internal reader from a CICS application executing in Enterprise Server, you need to:

  1. Create a CICS Resource Group and a DCT entry
    and add them to the appropriate startup list.
  2. Create a CICS Application
    that writes the JCL to a transient data queue.
  3. Create a TN3270 Listener
    Explains why the task should be performed and what it accomplishes. Written as complete sentence. Contains no more than two sentences.
  4. Run the Application
    to submit the JCL.
Parent topic: Invoking JCL from CICS
Next topic: Submitting JCL via SSTM and the CICS Spooling Facility


Create a CICS Resource Group and a DCT entry

You can use ESMAC to create a new resource group, providing the following fields:
  • Name: A name for the group - e.g. CICSJCL.
  • Description: A brief description - e.g. 'Submit JCL from CICS'.
Then, again using ESMAC, you can create a DCT (Destination Control Table) entry for the internal reader - a DCT entry describes a transient data queue. You should provide the following fields:
  • Name: A name for the DCT entry - e.g. IRDR.
  • Description: A brief description - e.g. 'Internal reader DCT entry'.
  • Type: Select Internal Rdr from the list.
  • Initial State: Select Open from the list.

After creating these resources, you should add the group to the CICS startup list for JCL applications - the changes will not take effect until you restart the Enterprise Server.

Note: In Micro Focus documentation, an external writer is more appropriately referred to as an internal reader when in a JCL context.
Parent topic: Submitting JCL via the Internal Reader
Next topic: Create a CICS Application


Create a CICS Application

The CICS application should use the CICS command WRITEQ TD to write the JCL job stream to the DCT you defined earlier. The program needs to be compiled with a non-mainframe dialect and with the CICSECM directive set.

Example

working-storage section.
 78 78-table-size value 22.
 01 ws-table.
     02 value '//CPJTEST JOB ''CPJX'',CLASS=A,MSGCLASS=A ' pic x(80).
     02 value '//*   NOTIFY=CPJ,                         ' pic x(80).
     02 value '//*   USER=CPJ,                           ' pic x(80).
     02 value '//*   PASSWORD=WIBBLE                     ' pic x(80).
     02 value '//*                                       ' pic x(80).
     02 value '//STEP00   EXEC PGM=IEFBR14               ' pic x(80).
     02 value '//A DD DUMMY                              ' pic x(80).
     02 value '//*                                       ' pic x(80).
     02 value '//DUMMY EXEC PGM=IEFBR14                  ' pic x(80).
     02 value '//NEWDSN DD DSN=MFICPJ.WORK.DATA,         ' pic x(80).
     02 value '//       DISP=(,CATLG),                   ' pic x(80).
     02 value '//       DCB=(LRECL=80,RECFM=FB,DSORG=PS),' pic x(80).
     02 value '//       SPACE=(800,(10,10)),UNIT=SYSDA   ' pic x(80).
     02 value '//*                                       ' pic x(80).
     02 value '//GENER EXEC PGM=IEBGENER                 ' pic x(80).
     02 value '//SYSPRINT DD SYSOUT=*                    ' pic x(80).
     02 value '//SYSUT1 DD *                             ' pic x(80).
     02 value 'Rec 1                                     ' pic x(80).
     02 value 'Rec 2                                     ' pic x(80).
     02 value '//SYSUT2 DD SYSOUT=*                      ' pic x(80).
     02 value '//                                        ' pic x(80).
     02 value '/*EOF                                     ' pic x(80).
 01 redefines ws-table.
     02 ws-table-line occurs 78-table-size times           pic x(80).
 01  ws-queue   value 'IRDR'           pic x(4).
 01  ws-x                              pic x(4) comp-5.
 procedure division.
     exec cics enq
        resource(ws-queue)
     end-exec
     perform varying ws-x from 1 by 1
          until ws-x > 78-table-size
          exec cics writeq td
               queue(ws-queue)
               from (ws-table-line(ws-x))
          end-exec
     end-perform
     exec cics send from(ws-table) erase end-exec
     exec cics return end-exec
     stop run.
Parent topic: Submitting JCL via the Internal Reader
Previous topic: Create a CICS Resource Group and a DCT entry
Next topic: Create a TN3270 Listener


Create a TN3270 Listener

Define a listener for TN3270 terminals to invoke the transaction on your Enterprise Server region:
  1. In the table of servers on the Home page of Enterprise Server Administration, click Details in the Communications Processes cell that corresponds to the server to which you want to add the listener.
  2. Click Add in the Listeners column for the communications process to which you want to add the listener.
  3. In the Name field, specify a suitable name - e.g. tn3270.
  4. Allow Endpoint Protocol to default to TCP.
  5. In Endpoint Address, set the port number for the listener to *.nnnn where nnnn is a port number. You can use any number above 5000 that isn't already in use.
  6. In the Supported Conversation Type group, click TN3270.
  7. Click Home.
  8. Restart the Enterprise Server - this starts the new listener.
Parent topic: Submitting JCL via the Internal Reader
Previous topic: Create a CICS Application
Next topic: Run the Application


Run the Application

If you were setting up your CICS environment for production, you would now create a PCT entry to associate the name of your program with a CICS transaction id. For this example however, we will use the Micro Focus generic run program CRUN which is useful for testing, and allows you to execute programs on an as-required basis without changing CICS tables.
  1. Start your terminal emulator and clear the screen. Note that you might need to configure your terminal emulator to communicate with the listener port you previously set up, and to connect to the right IP address, which is found on the Home page of Enterprise Server Administration, in the Communications Processes cell for your server.
  2. Enter CRUN progname where progname is the name of your program. This invokes the CICS application which submits the job by writing to the transient data queue defined as the internal reader. If you used the example program provided previously, your output screen will display the JCL submitted.
Parent topic: Submitting JCL via the Internal Reader
Previous topic: Create a TN3270 Listener


Submitting JCL via SSTM and the CICS Spooling Facility

If you want to use the CICS spooling facility to submit JCL, you need to activate SSTM for your Enterprise Server.

To submit JCL via SSTM and the CICS Spooling Facility, you need to:

  1. Activate SSTM for your Enterprise Server region
    by setting an environment variable and providing some JCL to initialize the SSTM environment.
  2. Create a CICS application
    that uses the CICS spool facility.
  3. Create a TN3270 Listener
    to allow you to invoke the transaction on the CICS region.
  4. Run the Application
    to submit the JCL via SSTM and use the CICS spooling facility.
Parent topic: Invoking JCL from CICS
Previous topic: Submitting JCL via the Internal Reader


Activate SSTM for your Enterprise Server region

To activate SSTM for your Enterprise Server region, you provide some initialization JCL and set the environment variable ES_SSTM_CICS to reference it. This information is picked up as your Enterprise Server region starts.

Example settings

  • SSTM initialization JCL
    //SSTMJCL JOB 'CICS JOB',MSGCLASS=A
//CICS     EXEC PGM=NOTUSED
//SYSOUT   DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//TEMPJCL  DD DSN=&&TEMPJCL,DISP=NEW
//OUTJCL   DD DSN=CICS.SSTM.OUTJCL,DISP=(MOD,CATLG)

    Note that the program name in the PGM= entry must be syntactically correct, but it does not need to exist. The DD OUTJCL is shared across CICS SEPs, but the other DDs are not shared, and are local to each SEP.

  • ES_SSTM_CICS
    ES_SSTM_CICS=C:\ES\SSTM\JCL\SSTMCICS.JCL
    This environment variable is set in the General tab of Enterprise Server Administration, in the Configuration Information section, for example:
    [ES-Environment]
ES_SSTM_CICS=C:\ES\SSTM\JCL\SSTMCICS.JCL

You will need to restart your Enterprise Server region for these changes to take effect. The message SSTM environment established successfully appears in the output console after a successful restart.

Parent topic: Submitting JCL via SSTM and the CICS Spooling Facility
Next topic: Create a CICS application


Create a CICS application

The CICS application should use the CICS SPOOLOPEN, SPOOLWRITE and SPOOLCLOSE commands and be compiled with a non-mainframe dialect, with the CICSECM directive set.

Example

WORKING-STORAGE SECTION.
       01  WS-RESP1                    PIC S9(9) COMP.
       01  WS-RESP2                    PIC S9(9) COMP.
       01  WS-TOKEN                    PIC X(8) VALUE SPACE.
       01  WS-JCL-LINES.
           03  FILLER                  PIC X(80) VALUE
           '//MFIPEH JOB MTS,PEH,CLASS=A,MSGCLASS=O'.
           03  FILLER                  PIC X(80) VALUE
           '//* CHECK CICS SPOOL API '.
           03  FILLER                  PIC X(80) VALUE
           '// EXEC PGM=IEFBR14'.
           03  FILLER                  PIC X(80) VALUE
           '// '.
       01  FILLER REDEFINES WS-JCL-LINES.
           03  WS-JCL                  PIC X(80) OCCURS 4
                                       INDEXED BY WS-JIX.
       01  WS-ERROR.
           03  FILLER                  PIC X(24) VALUE
           'ERROR OCCURRED. RESP1 = '.
           03  WS-ERR1                 PIC +9(8).
           03  FILLER                  PIC X(10) VALUE
           ', RESP2 = '.
           03  WS-ERR2                 PIC +9(8).
       01  WS-RUN-OK                   PIC X(20) VALUE
           'Test run OK'.
       01  WS-POINTER                  POINTER.
       01  WS-OUT-DESCR.
           03  FILLER                  PIC X(26) VALUE
           'USERID(XXXXXX) DEST(JES2W)'.
       LINKAGE SECTION.
       01  LK-OUT-DESCR.
           03  LK-LEN                  PIC S9(8) COMP.
           03  LK-OUT-DATA             PIC X(26).
           03  LK-POINTER              POINTER.
       PROCEDURE DIVISION.
           EXEC CICS GETMAIN
               SET(WS-POINTER)
               LENGTH(LENGTH OF LK-OUT-DESCR)
           END-EXEC
           SET ADDRESS OF LK-OUT-DESCR TO WS-POINTER
           MOVE WS-OUT-DESCR TO LK-OUT-DATA
           MOVE LENGTH OF LK-OUT-DATA TO LK-LEN
           SET LK-POINTER TO WS-POINTER
           SET WS-POINTER TO ADDRESS OF LK-POINTER
           EXEC CICS SPOOLOPEN OUTPUT
                     TOKEN(WS-TOKEN)
                     USERID('XXXXXX')
                     NODE('N1')
                     RESP(WS-RESP1)
                     RESP2(WS-RESP2)
           END-EXEC
           IF WS-RESP1 NOT = DFHRESP(NORMAL)
               GO TO ERR-DISP
           END-IF
           SET WS-JIX TO 1
           PERFORM 4 TIMES
               EXEC CICS SPOOLWRITE
                         TOKEN(WS-TOKEN)
                         FROM(WS-JCL(WS-JIX))
                         RESP(WS-RESP1)
                         RESP2(WS-RESP2)
               END-EXEC
               IF WS-RESP1 NOT = DFHRESP(NORMAL)
                   GO TO ERR-DISP
               END-IF
               SET WS-JIX UP BY 1
           END-PERFORM
           EXEC CICS SPOOLCLOSE
                     TOKEN(WS-TOKEN)
                     RESP(WS-RESP1)
                     RESP2(WS-RESP2)
           END-EXEC
           IF WS-RESP1 NOT = DFHRESP(NORMAL)
               GO TO ERR-DISP
           END-IF
           EXEC CICS SEND TEXT
                     FROM(WS-RUN-OK)
                     ERASE
                     FREEKB
           END-EXEC

           EXEC CICS RETURN END-EXEC

           GOBACK.
       ERR-DISP.
           MOVE WS-RESP1 TO WS-ERR1
           MOVE WS-RESP2 TO WS-ERR2
           EXEC CICS SEND TEXT
                     FROM(WS-ERROR)
                     ERASE
           END-EXEC
           EXEC CICS RETURN END-EXEC
           .
Parent topic: Submitting JCL via SSTM and the CICS Spooling Facility
Previous topic: Activate SSTM for your Enterprise Server region
Next topic: Create a TN3270 Listener


Create a TN3270 Listener

Define a listener for TN3270 terminals to invoke the transaction on your Enterprise Server region:
  1. In the table of servers on the Home page of Enterprise Server Administration, click Details in the Communications Processes cell that corresponds to the server to which you want to add the listener.
  2. Click Add in the Listeners column for the communications process to which you want to add the listener.
  3. In the Name field, specify a suitable name - e.g. tn3270.
  4. Allow Endpoint Protocol to default to TCP.
  5. In Endpoint Address, set the port number for the listener to *.nnnn where nnnn is a port number. You can use any number above 5000 that isn't already in use.
  6. In the Supported Conversation Type group, click TN3270.
  7. Click Home.
  8. Restart the Enterprise Server - this starts the new listener.
Parent topic: Submitting JCL via SSTM and the CICS Spooling Facility
Previous topic: Create a CICS application
Next topic: Run the Application


Run the Application

If you were setting up your CICS environment for production, you would now create a PCT entry to associate the name of your program with a CICS transaction id. For this example however, we will use the Micro Focus generic run program CRUN which is useful for testing, and allows you to execute programs on an as-required basis without changing CICS tables.
  1. Start your terminal emulator and clear the screen. Note that you might need to configure your terminal emulator to communicate with the listener prot you previously set up, and to connect to the right IP address, which is found on the Home page of Enterprise Server Administration, in the Communications Processes cell for your server.
  2. Enter CRUN progname where progname is the name of your program. This invokes the CICS application that submits the JCL via the CICS SPOOLOPEN, SPOOLWRITE and SPOOLCLOSE commands. If you used the example program provided, your output screen will display the message: Test run OK. Upon invocation of the spool service, a message is also sent to the output console, similar to:
    Spool service created, region SSTMDEMO, process-id = 8180 10:11:12
  3. You can examine the spool output by clicking Control and then ES Monitor & Control when on the Enterprise Server Administration screen for your region. Then select JES from the Resources list in the left-hand column, and click Spool.
Parent topic: Submitting JCL via SSTM and the CICS Spooling Facility
Previous topic: Create a TN3270 Listener


JCL API

There are a number of API calls that you can call from a COBOL program to carry out JCL-type tasks.

  • MFJZABND
    MFJZABND abends the current job step with a system or user abend.
  • MFJZLOG
    MFJZLOG writes a message to the syslog and/or the joblog.
  • MFJZS099
    MFJZS099 issues an SVC 99 call.
  • MFJZLPSA
    MFJZLPSA locates the Prefixed Save Area (PSA).
  • MFJZS099
    Enables you to use DYNamic ALLOCation (DYNALLOC - SVC99) functions.
Parent topic: JCL Support


MFJZABND

MFJZABND abends the current job step with a system or user abend.

Syntax:

call "MFJZABND" using abend-type abend-code

Parameters:

abend-code | pic 9(8) comp | The abend code.
abend-type | pic 9(8) comp | Type of abend to occur; 0 indicates a user abend; 1 indicates a system abend..
abend-sys | pic 9(8) comp value 1 |
abend-user | pic 9(8) comp value 0 |

Example:

Example 1. To cause an abend with user abend 1004:

77  abend-code                 pic  9(08) comp.
77  abend-type                  pic 9(08)  comp.
77  abend-sys                   pic  9(08) comp value 1.
77  abend-user                  pic  9(08) comp value 0.

...
Move 1004 to abend-code
call 'MFJZABND' using abend-user abend-code

Example 2. To cause an abend with system abend SDED (note that system abend codes are always hex not decimal):

77  abend-code                 pic  9(08) comp.
77  abend-type                  pic 9(08)  comp.
77  abend-sys                   pic  9(08) comp value 1.
77  abend-user                  pic  9(08) comp value 0.
...
Move h’ded’ to abend-code
call 'MFJZABND' using abend-sys abend-code
Parent topic: JCL API


MFJZLOG

MFJZLOG writes a message to the syslog and/or the joblog.

Syntax:

call "MFJZLOG" using msg-dest msg-len msg-txt

Parameters:

msg-dest | pic 9(8) comp | Message destination; A value of 1 sends it to the joblog, a value of 2 sends it to syslog, and a value of 0 sends it to both.
msg-dest-both | pic 9(8) comp |
msg-dest-joblog | pic 9(8) comp |
msg-dest-syslog | pic 9(8) comp |
msg-len | pic 9(8) comp | Length of the message text. Message length should be less than 108 bytes if you want to keep the whole message on one line.
msg-txt | x(118) | Text of the message.

Comments:

To use this API on IMS and CICS enterprise server regions, the region must be SSTM-enabled; see To enable JCL support from a CICS or IMS subsystem for more information. This API is not supported to run under ES for .NET.

The message length should be less than 108 bytes if you wish to keep the whole message on one line.

Note:
  • Where the characters in positions 6 ,7, 8 and 9 of your message string are digits (as is the case in the examples below) MFJZLOG assumes that you are supplying your own message code. In all other circumstances, it prepends your message with the default code, 'JCLXM0000I '.
  • If the message string contains the character 'I' at position 10 (as is the case where your original string is prepended with JCLXM0000I) the default user exit casumxit will exclude it from the system log.

Example:

Example 1. To write “MyMsg0001P Hi there!” to both the system log and the job log:

77 msg-dest-both     pic 9(8) comp value 0.
77 msg-dest-joblog   pic 9(8) comp value 1.
77 msg-dest-syslog   pic 9(8) comp value 2.
77  msg-txt          pic x(118) value ' MyMsg0001I Hi there!'.
77  msg-len          pic  9(08) comp value 20.

call 'MFJZLOG' using  msg-dest-both
                           msg-len
                           msg-txt

Example 2. To write “MyMsg0001P Hi there!” to just the job log:

77 msg-dest-both      pic 9(8) comp value 0.
77 msg-dest-joblog    pic 9(8) comp value 1.
77 msg-dest-syslog    pic 9(8) comp value 2.
77  msg-txt           pic x(118) value ' MyMsg0001I Hi there!'.
77  msg-len           pic  9(08) comp value 20.

call 'MFJZLOG' using msg-dest-joblog
                      msg-len
                      msg-txt
Parent topic: JCL API


MFJZS099

MFJZS099 issues an SVC 99 call.

Syntax:

call "MFJZS099" using s99rb caller-id returning retcode

Parameters:

s99rb | See below | SVC 99 request block mapped by IDAS99RB.CPY. You may use IDAS99TU.CPY to assist you in the construction of the Text Units (TUs).
caller-id | See Below | While using this parameter is recommended, it is not a requirement for COBOL programs compiled as INTs and GNTs. For non-COBOL programs, it is required and is used by the SVC 99 handler to interpret format of addresses and CHARSET of the character data. Binary data must always in z/OS (Big-Endian) format.
retcode | pic 9(8) comp | SVC 99 return code that would have been placed in the general purpose register 15. All other error and info codes are stored in SVC99RB.

Comments:

SVC99 uses the high-order bit of a TU (Text Unit) address to interpret it as the last TU address in the TU address array.

When the calling program is compiled with NOAMODE, the high order bit of a TU address will not be interpreted as an indication of the last address in the TU pointer array. In this case, you have two options:

  • Make sure the last TU address is indicated by a value of either x’80000000’ or x’00000080’. This will keep the source compatible with the host. If either of these could potentially be a legitimate address on the computer you are running on, then the following option is the only alternative.
  • Specify a last address value of your choice in the extension portion of the SVC99 Request Block (S99RB).

If the calling program is compiled with AMODE, no changes are required. It is recommended that you use a null address to signify the last address. For example, set TU last address to x’80000000’.

Example:

A program running with NOAMODE:

copy idas99rb
        replacing ==()== by ==s99rb==.
    copy idas99tu
        replacing ==()== by ==s99tu==.
    01 caller-id.
       03 caller-id-char               pic x(04) value 'S099'.
       03 caller-id-ptr                pointer.*> ptr to s99rb
       03 caller-id-bin                pic 9(8) comp value 1.
       03 caller-id-float              comp-1 value 1.
    01 .
       03 tu-ptr-list.
          05 tu-ptr-ddn                pointer.
          05 tu-ptr-dsn                pointer.
          05 etc                       pointer.
          05	                       pic x(4) value s99rb-last-ptr-val-x4-val.

     move low-values to s99rb
     move s99rb-len-mf-ext to s99rb-len
     move s99rb-last-ptr-val-x4-val to s99rb-last-ptr-val-x4
     set s99rb-s99tu-array-ptr to address tu-ptr-list
     set caller-id-ptr to address s99rb

     call 'MFJZS099' using  s99rb caller-id returning retcode
     if retcode = 0
        *> SVC99 ok
     else
        *> SVC99 not ok – check for errors
     end-if

A program running with AMODE:

copy idas99rb
        replacing ==()== by ==s99rb==.
    copy idas99tu
        replacing ==()== by ==s99tu==.
    01 caller-id.
       03 caller-id-char               pic x(04) value 'S099'.
       03 caller-id-ptr                pointer.*> ptr to s99rb
       03 caller-id-bin                pic 9(8) comp value 1.
       03 caller-id-float              comp-1 value 1.
    01 .
       03 tu-ptr-list.
          05 tu-ptr-ddn                pointer.
          05 tu-ptr-dsn                pointer.
          05 etc                       pointer.
          05	                       pic x(4) value x'80000000'

     move low-values to s99rb
     move s99rb-len-mf-ext to s99rb-len
     move s99rb-last-ptr-val-x4-val to s99rb-last-ptr-val-x4
     set s99rb-s99tu-array-ptr to address tu-ptr-list
     set caller-id-ptr to address s99rb

     call 'MFJZS099' using  s99rb caller-id returning retcode
     if retcode = 0
        *> SVC99 ok
     else
        *> SVC99 not ok – check for errors
     end-if
Parent topic: JCL API


MFJZLPSA

MFJZLPSA locates the Prefixed Save Area (PSA).

Syntax:

call 'MFJZLPSA' returning psa-ptr
*   on exception  *> reqd only if run on the mainframe
*   continue
Where:
 psa-ptr will be set to the address of the PSA upon return.

Parameters:

77 psa-ptr pointer

Comments:

This service must be used to locate the PSA if you are running NOAMODE. It can be used all the time regardless of your AMODE or CHARSET.

Example:

77 psa-ptr  pointer.
      call 'MFJZLPSA' returning psa-ptr
      set address of psa   to psa-ptr
      set address of cvt   to psa-cvt
Parent topic: JCL API


MFJZS099

Enables you to use DYNamic ALLOCation (DYNALLOC - SVC99) functions.
Note: The following information does not apply if you are invoking SVC 99 via a z/OS Assembler routine that issues the SVC 99 machine instruction.

You invoke the Micro Focus SVC 99 API, MFJZS099, as follows (skeletal code only is shown):

copy idas99rb replacing ==()== by ==s99rb==.
copy idas99tu replacing ==()== by ==s99tu==.
  1 caller-id.
  3 caller-id-char       pic x(04) value 'S099'.
  3 caller-id-ptr  pointer.     *> ptr to s99rb
  3 caller-id-bin pic 9(8) comp value 1.
  3 caller-id-float      comp-1 value 1.
1.
    3 tu-ptr-list.
    5 tu-ptr-ddn   pointer.
    5 tu-ptr-dsn    pointer.
    5 etc       pointer.
   3	  pic x(4) value
       --either—(1)
       x’80000000’
       --or--  (2)
          s99rb-last-ptr-val-x4-val.

     move low-values to s99rb
      --either— (3)
     move s99rb-len-host to s99rb-len
      --or--  (4)
     move s99rb-len-mf-ext to s99rb-len
     move s99rb-last-ptr-val-x4-val to s99rb-last-ptr-val-x4
      --and--
     set s99rb-s99tu-array-ptr to address tu-ptr-list
     set caller-id-ptr to address s99rb

     call 'MFJZS099' using  s99rb
         caller-id
         returning s99rb-retc

    if s99rb-retc = 0
      *> SVC99 ok
    else
      *> SVC99 not ok – check for errors
    end-if

The parameters are:

SVC 99 Request Block (mapped by IDAS99RB.CPY)
You may use IDAS99TU.CPY to assist you in the construction of the Text Units (TUs).
Caller-id
While this parameter (caller-id) is recommended, COBOL programs compiled as INTs and GNTs can omit it. For non-COBOL programs, it is required and is used by the SVC 99 handler to interpret format of addresses and CHARSET of the character data, Binary data must always be in z/OS (Big-Endian) format.
retcode

Return value in retcode will be the SVC99 return code value that would have been placed in the general purpose register 15. All other error and info codes are stored in SVC99RB.

SVC99 uses the high-order bit of a TU (Text Unit) address to interpret it as the last TU address in the TU address array.

If the calling program is compiled with AMODE, you need not make any changes. It is recommended that you use a null address to signify the last address, that is, set TU last address to x’80000000’ (see (1) in the example above).

When the calling program is compiled with NOAMODE, the high order bit of a TU (Text Unit) address will not be interpreted as an indication of the last address in the TU pointer array. In this case, you have one of two options:

  1. Make sure the last TU address is indicated by a value of either x’80000000’ or x’00000080’ (see (1) and (3) in the example above). This will keep the source compatible with the host. If either of these could potentially be a legitimate address on the computer you are running on, then option 2 is the only other alternative.
  2. Specify a specific last address value of your choice in the extension portion of the SVC99 Request Block (S99RB) (see (2) and (4) in the example above).

Examples

The following program is running with NOAMODE in effect:

copy idas99rb replacing ==()== by ==s99rb==.
copy idas99tu replacing ==()== by ==s99tu==.
  1 caller-id.
    3 caller-id-char       pic x(04) value 'S099'.
    3 caller-id-ptr  pointer.     *> ptr to s99rb
    3 caller-id-bin pic 9(8) comp value 1.
    3 caller-id-float      comp-1 value 1.
  1  .
    3 tu-ptr-list.
      5 tu-ptr-ddn   pointer.
      5 tu-ptr-dsn    pointer.
      5 etc       pointer.
     4	pic x(4) value
                  s99rb-last-ptr-val-x4-val.

           move low-values to s99rb
           move s99rb-len-mf-ext to s99rb-len
           move s99rb-last-ptr-val-x4-val to s99rb-last-ptr-val-x4
           set s99rb-s99tu-array-ptr to address tu-ptr-list
           set caller-id-ptr to address s99rb

call 'MFJZS099' using  s99rb
                   caller-id
                   returning s99rb-retc
            if s99rb-retc = 0
                    *> SVC99 ok
            else
                    *> SVC99 not ok – check for errors
            end-if

The following program is running with AMODE in effect:

copy idas99rb replacing ==()== by ==s99rb==.
copy idas99tu replacing ==()== by ==s99tu==.
  1 caller-id.
    3 caller-id-char       pic x(04) value 'S099'.
    3 caller-id-ptr  pointer.     *> ptr to s99rb
    3 caller-id-bin pic 9(8) comp value 1.
    3 caller-id-float      comp-1 value 1.
  1  .
    3 tu-ptr-list.
      5 tu-ptr-ddn   pointer.
      5 tu-ptr-dsn    pointer.
      5 etc       pointer.
      5 pic x(4) value x’80000000’.

   move low-values to s99rb
   move s99rb-len-host to s99rb-len
   set s99rb-s99tu-array-ptr to address tu-ptr-list
   set caller-id-ptr to address s99rb

   call 'MFJZS099' using  s99rb
       caller-id
       returning s99rb-retc
    if s99rb-retc = 0
       *> SVC99 ok
    else
       *> SVC99 not ok – check for errors
    end-if
Parent topic: JCL API


Mainframe Emulation

  • Compatibility with the Mainframe Environment
  • Assembler Programs
  • Language Environment (LE) Support
Parent topic: Mainframe Programming


Compatibility with the Mainframe Environment

The following topics discuss compatibility with the mainframe.

  • Mainframe Pointers
  • Entry Point Mapping for COBOL Programs
  • Support for Multiple Catalogs
  • Using SMS Data Classes
  • IBM Hexadecimal Format Floating Point Data
Parent topic: Mainframe Emulation


Mainframe Pointers

To provide compatibility with mainframe-style pointers in COBOL programs, this system:

  • Provides and sets the AMODE compiler directive
  • Enables continued access to the data of a canceled subprogram by the calling program
  • AMODE Compiler Directive
  • Accessing Data in a Canceled Program
Parent topic: Compatibility with the Mainframe Environment


AMODE Compiler Directive

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.

Enterprise Developer also provides and sets the DATA Compiler directive that can control the placement of the Data Division of a program compiled using the AMODE Compiler directive.

The following table shows the settings for AMODE and DATA that are required for a number of COBOL dialects:
COBOL Dialect | Directive
COBOL 370 | AMODE(31) DATA(31)
VS COBOL II (all releases) | AMODE(31) DATA(31)
OS/VS COBOL | AMODE(24)

You must specify the appropriate settings for these directives depending on the dialect you are using.

Parent topic: Mainframe Pointers
Related reference
AMODE
DATA


Accessing Data in a Canceled Program

On the mainframe, a COBOL program can continue to use the data defined in the Data Division of a subprogram even after that subprogram has been canceled. This facility has been emulated in Enterprise Developer, although we do not recommend it as good practice.

You can enable this facility by using the mfpm_access_cancelled_data tunable.

Before the subprogram is canceled, you should set pointer variables in the calling program to the addresses of the data in the subprogram that you want to continue to use. Then, after the subprogram is canceled, you can continue to use that data until Enterprise Developer releases the Working-Storage Section of the canceled subprogram. This can occur if:

  • There is insufficient storage available to satisfy a new storage request
  • The canceled subprogram is reloaded. In this case, the old Working-Storage area is released and a new area allocated and initialized.
  • The application terminates

Any attempt to use a pointer variable that still points to a released Working-Storage area will have unpredictable results.

Parent topic: Mainframe Pointers
Related reference
mfpm_access_cancelled_data


Entry Point Mapping for COBOL Programs

The Entry Point Mapping facility 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 which will not have been loaded prior to them being called.

To appreciate the functions that this facility performs, you need to understand how calls to entry points are normally resolved using the run-time system.

When a program makes a call to an entry point in which the entry point has not been resolved by statically linking the program, the run-time system looks for the entry point to resolve it dynamically.

When a 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. If it does not find one it returns an error.

Consequently, if your program calls an entry point that is not the name of an executable file or 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 the only case where you need to use the Entry Point Mapper.

This problem often occurs 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 Enterprise Developer, if the program containing the entry point has not already been called, the call to that entry point fails.

To get round this problem, you need to create an entry name map file containing an entry point table and make it available to the run-time system.

  • Creating an Entry Name Map File
  • Making Entry Name Map Files Available to the Run-time System
  • Creating an Alias
Parent topic: Compatibility with the Mainframe Environment


Creating an Entry Name Map File

You create your map file with a text editor. For each entry point you need to enter the following three lines:

[ENTRY-POINT] entry-point-name
[PROGRAM-NAME] main-program-name
[SUBPROGRAM-NAME] subprogram-containing-entry-point

Example

Consider a run unit with a main program A and subprogram C. Within the run unit, A calls entry point B which is in program C. The table entry in the entry name map file is:

[ENTRY-POINT] B
[PROGRAM-NAME] A
[SUBPROGRAM-NAME] C

You can also specify an optional [ALIASED-ENTRY-POINT] line following the [ENTRY-POINT] line. If specified, this line defines an entry point name onto which the entry point specified by [ENTRY-POINT] is aliased.

For example:

[ENTRY-POINT]  XYZ
[ALIASED-ENTRY-POINT] ENTA
[PROGRAM-NAME]  *
[SUBPROGRAM-NAME]  PGMA

causes XYZ to be aliased on the ENTA entry point in the program PGMA. This means that when XYZ is called by a program, entry point ENTA will be invoked.

Note: Notes:
  • A tag, that is, the text in square brackets, must be in upper case.
  • A line beginning with # is treated as a comment.
  • You can specify an asterisk (*) for program name to indicate that any program in the run unit can call entry point B in program C.
  • Entry point aliasing is only available for use with .int, .gnt, and .dll (Windows) or .so (UNIX) programs.
Parent topic: Entry Point Mapping for COBOL Programs


Making Entry Name Map Files Available to the Run-time System

You use the entry_point_mapper tunable to indicate to the run-time system that you want to use entry name mapping. If entry_point_mapper is set, how the run-time system searches for entry name map files depends on whether the ENTRYNAMEMAP environment variable is set:

  • If ENTRYNAMEMAP is set, the run-time system searches in the semi-colon delimited list of folders and entry name map files it specifies. For each folder specified, the run-time system looks for an entry name map file called mfentmap.dat.
  • If ENTRYNAMEMAP is not set, the run-time system searches for an entry name map file called mfentmap.dat in each folder specified by the COBDIR environment variable.

In either case, the run-time system could find more than one entry name map file, which means that the same entry point could be defined differently in different files. If this happens, precedence is given to the definition in the entry name map file that was found first. To change the order in which the run-time system finds entry name map files you need to change the order in which the files appear in the COBDIR or ENTRYNAMEMAP environment variable paths.

See the topic on the tunable entry_point_mapper.

Parent topic: Entry Point Mapping for COBOL Programs
Related reference
entry_point_mapper


Creating an Alias

To create an alias you use the Entry Point Mapper to emulate the alias function of an IBM mainframe linkage editor, which redirects the system to execute a program accessed via an alias name. To do this you must edit the entry name map file using a text editor.

At run time, your COBOL run-time system first looks for a program with the original name. If it finds one, it does not invoke the Entry Point Mapper.

Enter the alias on the [ENTRY-POINT] line and the actual program name on the [SUB-PROGRAM] line.

  • Example 1
  • Example 2
Parent topic: Entry Point Mapping for COBOL Programs


Example 1

Consider a run unit with a main program named progroot. Within the run unit, progroot issues a call using the name pacct001. The actual name of the subprogram required is tacct001. The table entry in the mfentmap.dat file is:

[ENTRY-POINT] pacct001
[PROGRAM-NAME] progroot
[SUBPROGRAM-NAME] tacct001
Parent topic: Creating an Alias


Example 2

Consider the situation where you want to load a program by using a different name to that given to the source program. For example, your JCL might contain an instruction to load myprogx, whereas the actual name of the program is myprog. On the mainframe, you could achieve this by linking the program and giving it the required name. However, you cannot link COBOL programs in your COBOL development system; you therefore need to use the Entry Point Mapper to make an association between the name used to load the program and the actual program name.

For example, suppose your program is called myprog, but you instead want to use myprogx as the name to load to the program. The table entry required in the mfentmap.dat file is:

 [ENTRY-POINT] myprogx
 [PROGRAM-NAME] *
 [SUBPROGRAM-NAME] myprog

where [ENTRY-POINT] defines the alias name and [SUBPROGRAM-NAME] is the name of the executable program.

Parent topic: Creating an Alias


Support for Multiple Catalogs

Typically, just one catalog is used to hold the information about all datasets used in a batch region. However, you can use up to 64 user catalogs, in addition to the main (system) catalog. Note that catalog entries are independent of dataset locations. Refer to the section Controlling where Datasets are Created for details of how to specify where the underlying physical files are stored.

  • Configuring Multiple Catalogs
    To enable multiple user catalogs in Enterprise Server, and to configure in which catalog a particular dataset's details are held, you must set the MFUSERCAT_NODE and MFUSERCAT_LOC environment variables.
  • Special Node Values
    There are two possible values of the MFUSERCAT_NODE variable that have special meaning.
  • Examples of Using Multiple Catalogs
    Examples of how to configure the MFUSERCAT_NODE and MFUSERCAT_LOC variables to use multiple catalogs.
Parent topic: Compatibility with the Mainframe Environment
Related reference
Using SMS Data Classes
Separating the Spool files from the main Catalog Location
Controlling where Datasets are Created
MFUSERCAT_BASE_LOC
MFUSERCAT_LOC
MFUSERCAT_NODE


Configuring Multiple Catalogs

To enable multiple user catalogs in Enterprise Server, and to configure in which catalog a particular dataset's details are held, you must set the following two environment variables:

  • MFUSERCAT_NODE - this variable holds the node specification or pattern of datasets whose details should be stored in a separate catalog.
  • MFUSERCAT_LOC - this variable specifies the location and name of each user catalog.

Both MFUSERCAT_NODE and MFUSERCAT_LOC are limited to 4096 characters.

Note: If several user catalogs share the same location, the environment variable MFUSERCAT_BASE_LOC can be used to specify where these catalogs are located, and their entries in the MFUSERCAT_LOC list need only specify the unqualified file names of the user catalog, rather than the full path and file name.

Both variables are required, and can hold multiple entries separated by semi-colons. A value specified in MFUSERCAT_NODE must have a corresponding value in MFUSERCAT_LOC. If the two lists do not contain the same number of entries, JES support for the ES region will not initialize successfully. See the Examples of using multiple catalogs section for more details.

If a specified catalog file does not exist, it is created when the system starts up, but if it cannot be created, the JES system will not start. However, if you set the ES_OPEN_CAT_ON_DEMAND environment variable to Y, an attempt to open a user catalog occurs only when it's required. With this variable set, only the main system catalog (if required) will be created and opened when the region starts. If a specified user catalog does not exist, it will not be created, which means that trying to access it will produce an error (such as file not found or otherwise unavailable), but the missing file will not stop the JES system from starting. When that catalog file is required again, the system will attempt to open it. The result in this process is a system that is more resilient to transient file access problems, such as network connections to remote file systems.

Note: An error accessing a catalog file is reported using error code 9908, and displayed in the ESAMC catalog page, where it displays information about any catalog errors, the catalog file that was being accessed, the file status returned, and whether the file exists or not.

For catalog files that have failed to open, you can use the environment variables ES_CAT_RETRY_COUNT and ES_CAT_RETRY_WAIT to set the number of times to retry the open before reporting the above error and how long to wait between retries (in seconds); however, be careful when setting these variables as they could impact the time taken to report an error and therefore will delay processing of the job whilst the checks take place. These variables can be useful if you experience file access problems that only last a second or two (for example, network connection drop-outs), so that it gives the system a chance to recover before aborting.

If a catalog file access error occurs when running a JCL job the job will abend with code S413 and a message will be included in the step or job output (usually message code 243U)

When Enterprise Server performs a catalog search for a specific dataset, it first compares the dataset name to the patterns defined in MFUSERCAT_NODE. If the name matches one of the defined patterns, it looks in the corresponding catalog file (this is usually named catalog.dat, but can be any name) for the information for that dataset. If the dataset is not found in the selected user catalog, the system catalog will then be searched. Similarly, when a request is made to catalog a new dataset, its name will be compared to the patterns defined in MFUSERCAT_NODE, and if a match is found, it will be cataloged in the corresponding user catalog. If no match is found, it will be cataloged in the system catalog.

The ESMAC catalog list function will search all available catalogs for datasets matching the search pattern, without reference to the node list, and display the resulting dataset list in alphabetical order.

Parent topic: Support for Multiple Catalogs
Related information
Special Node Values
Examples of Using Multiple Catalogs


Special Node Values

There are two possible values of the MFUSERCAT_NODE variable that have special meaning.
  • MVSSPOOL - this value can be used to direct catalog entries for all JES spool data files to a user catalog
  • SYSMFE1 - this value can be used to direct all SMS definitions (DATACLAS and/or MGMTCLAS) to a user catalog - see Using SMS Data Classes.
Parent topic: Support for Multiple Catalogs
Related information
Configuring Multiple Catalogs
Examples of Using Multiple Catalogs


Examples of Using Multiple Catalogs

Example 1

Consider the following example, where you might have some datasets with names that start with ABCD that should go into a catalog at C:\ABCD\CATALOG.DAT, and other datasets with names that start with WXYZ that should go into C:\WXYZ\CATALOG.DAT. Also, you might want to enable DATACLAS support (by setting MF_SMS=ON) and have an SMS catalog at C:\MAIN\SMS.DAT.

The MFUSERCAT_NODE variable must include the special SMS node, SYSMFE1, the ABCD node and the WXYZ node:

MFUSERCAT_NODE=SYSMFE1;ABCD;WXYZ

MFUSERCAT_LOC must include the corresponding locations for these catalogs:

MFUSERCAT_LOC=C:\MAIN\SMS.DAT;C:\ABCD\CATALOG.DAT;C:\WXYZ\CATALOG.DAT

Example 2

As the environment variable MFUSERCAT_NODE supports multiple dataset nodes and wildcards, you can use quite complex rules to direct catalog entries to specific user catalogs.

Consider the following definitions:

MFUSERCAT_NODE=MVSSPOOL;*.WORK;PROD??.VSAM;PROD??.SEQ;PROD??.LIB;USER01;USER02
MFUSERCAT_LOC=C:\MAIN\SPOOLCAT.DAT;C:\WORK\CATALOG.DAT;C:\PROD\VSAM\VSAMCAT.DAT;C:\PROD\SEQ\SEQCAT.DAT;C:\PROD\LIB\LIBCAT.DAT;C:\USER\USERCAT.DAT; C:\USER\USERCAT.DAT

The first node, MVSSPOOL, directs the catalog entries for all JES spool datasets to C:\MAIN\SPOOLCAT.DAT.

The second node, *.WORK, directs the catalog entries for all datasets whose second level qualifier is WORK to C:\WORK\CATALOG.DAT.

The third, fourth and fifth nodes direct the catalog entries for all datasets whose high level qualifier is six characters long, and begins with the string PROD, to catalogs specific to the dataset type, coded as the second level qualifier, VSAM, SEQ, and LIB.

The last two nodes direct the catalog entries for all datasets whose high level qualifiers are USER01 or USER02 to the same user-dataset catalog.

All other datasets will be cataloged in the system catalog, as specified under the MSS > JES tab, or via the environment variable MFSYSCAT.

Example 3

Square bracket notation may be used to build flexible node specifications that are aligned with your dataset naming convention.

Consider the following:

MFUSERCAT_NODE=A[DMP][OI][123].HLQ2[SVN];

For the first dataset name node, this would allow D, M, or P in the second position, O or I in the third position, and 1, 2, or 3 in the fourth position. For the second dataset name node, this would allow S, V or N in the fifth position.

The following dataset names all match the above specification:

ADO1.HLQ2S.HLQ3
ADI2.HLQ2V.HLQ3
AMO3.HLQ2N.HLQ3
AMI2.HLQ2S.HLQ3
APO1.HLQ2V.HLQ3
Parent topic: Support for Multiple Catalogs
Related information
Configuring Multiple Catalogs
Special Node Values


Using SMS Data Classes

A Storage Management Subsystem (SMS) data class is a template of data set attributes (such as record length and format) that you can specify is to be used when creating a new data set. Enterprise Developer enables applications running in an enterprise server to make use of SMS data classes.

Data class definitions are stored in a file that you must create using Enterprise Developer. Once you have created a data class definition file in Enterprise Developer you need to enable SMS support then specify the data class definition file that you want to use for an enterprise server.

To enable SMS and specify the data class definition file, perform the following steps:
  1. In the table of servers on the Home page of Enterprise Server Administration, click Edit to the left of the row for the server that you want to edit.
  2. Click the Properties tab then the General tab if they are not selected already.
  3. Specify the following variables in the [ES-Environment] section of :
    MF_SMS=ONConfiguration Information
MFUSERCAT_NODE=SYSMFE1
MFUSERCAT_LOC=definition-file

    where definition-file is the fully-qualified location and name of the data class definition file to use.

  4. Click OK.

You must now create one or more data classes; see the example JCL given in Using the SMS DATACLAS update utility with input from SYSIN. Once you have defined some data classes, you can refer to them using any of the following methods:

  • DATACLAS parameter of a JCL DD statement
  • DATACLASS parameter of a TSO ALLOCATE command
  • DATACLASS parameter of an IDCAMS DEFINE command
  • data class text unit (TU) of SVC 99 (DYNALLOC)

The same definition file can be used by more than one enterprise server, ensuring consistency of data class definitions. Whenever a data class specification is missing, a default data class called MFEDFTDC is used, if it exists. This data class must exist in an enterprise server's data class definition file for it to be available for that enterprise server.

When the data set is defined in the catalog, the DATACLAS and MGMTCLAS attributes are applied.

For full information on SMS, see the DFSMSdfp Storage Administration Reference available from the IBM BookManager Server Library.

  • Using the SMS DATACLAS update utility
  • Using SMS MGMT Classes
Parent topic: Compatibility with the Mainframe Environment


Using the SMS DATACLAS update utility

You can use the SMS DATACLAS update utility to create and modify SMS DATACLAS definitions. The SMS DATACLAS update utility is a batch utility that you execute using JCL, with the MFCMD program.

MFCMD allows you to access SMS maintenance. With the program, you use name/value pairs to supply parameters and corresponding values as

The SMS DATACLAS update utility takes input from SYSUT1 or SYSIN. MFCMD reads data from SYSIN if it is present, or from SYSUT1 if no SYSIN is present. The input consists of a DATACLAS definition identifier, folllowed by the name and value pairs that you want to set. The SMS DATACLAS update utility writes output to SYSPRINT and SYSUT2.

  • When using SYSUT1, you include the input as a text file. you can supply one to many records, one DATACLAS per record. The records can be any length up to 4096.
  • When using SYSIN, you are limited to 80 byte records and can specify only one DATACLAS with properties that can span multiple lines.
  • Setting up the environment
  • SMS DATACLAS functions
  • SMS DATACLAS Properties and values
  • Using the SMS DATACLAS update utility with input from SYSIN
  • Using the SMS DATACLAS update utility with input from SYSUT1
  • Using DATACLAS output
Parent topic: Using SMS Data Classes


Setting up the environment

Before you can use the utility, you need to set the following environment variables:

  • MFUSERCAT_NODE=SYSMFE1

    Sets that SMS is active. Specify exactly as shown.

  • MF_SMS=ON

    Sets that SMS is active. Specify exactly as shown.

  • MFUSERCAT_LOC=d:\estest\SMS.DAT

    Sets the fully qualified name of the SMS dataset. Supply the details for the dataset to use.

Parent topic: Using the SMS DATACLAS update utility


SMS DATACLAS functions

The following functions are available with the SMS DATACLAS update utility:

  • DLET deletes an item from the SMS DATACLAS
  • GN retrieves the next item in the SMS DATACLAS
  • GU retrieves a specific, named SMS DATACLAS
  • INSERT inserts a new item into the SMS DATACLAS
  • REPL replaces an existing named item in the SMS DATACLAS

For example, for the ABC dataclass, the following command:

DATACLAS NAME(ABC) RECFM(FB) LRECL(80) FUNC(ISRT)
  • Inserts a new DATACLAS named ABC
  • Sets the record format to FB
  • Sets the logical record length to 80 characters
Parent topic: Using the SMS DATACLAS update utility


SMS DATACLAS Properties and values

The following properties are available with the SMS DATACLAS update utility:

  • AVREC
  • AVVALUE
  • BLKSIZE
  • DIRECTORY
  • DSORG
  • KEYLEN
  • KEYOFF
  • LRECL
  • NAME
  • PRIMARY
  • RECFM
  • RECORG
  • SECONDARY
Parent topic: Using the SMS DATACLAS update utility


Using the SMS DATACLAS update utility with input from SYSIN

When using input from SYSIN, you are limited to 80 byte records and can specify only one DATACLAS with properties that can span multiple lines.

The following is an example of JCL that uses SMS DATACLAS with SYSIN.

//STEP20  EXEC PGM=MFCMD
//SYSUT1  DD DUMMY
//SYSIN DD *
   DATACLAS NAME(ABC) RECFM(FB) LRECL(80) FUNC(ISRT)
//SYSUT2 DD DSN=TEST.OUTPUT,DISP=OLD
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
Parent topic: Using the SMS DATACLAS update utility


Using the SMS DATACLAS update utility with input from SYSUT1

Each record read from SYSUT1 must contain the complete set of data necessary for one operation on one DATACLAS. For example, to perform a GU operation followed by two GN operations, you would use the following.

   DATACLAS  NAME(ABC) RECFM(FB) LRECL(80) FUNC(GU)
   DATACLAS  FUNC(GN)
   DATACLAS  FUNC(GN)

The following is an example of JCL that uses SMS DATACLAS with SYSUT1.

//STEP20  EXEC PGM=MFCMD
//SYSUT1  DD DSN=TEST.CMDFILE,DISP=OLD
//SYSUT2  DD DSN=TEST.OUTPUT,DISP=OLD
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
Parent topic: Using the SMS DATACLAS update utility


Using DATACLAS output

SMS DATACLAS produces output to SYSPRINT and SYSUT2. Output to SYSPRINT is a report that shows the results of execution.

Output to SYSUT2 is the NAME and Parameter Values for any DATACLAS records successfully retrieved. For example, for the following two commands:

  • DATACLAS NAME(ABC) RECFM(FB) LRECL(80) FUNC(ISRT)
  • DATACLAS NAME(ABC) FUNC(GU)

SYSUT2 would contain the following record:

DATACLAS NAME(ABC) RECFM(FB) LRECL(80)

You then could, for example edit, the output file to add FUNC(ISRT) and use it to load DATACLAS values to another SMS file.

Parent topic: Using the SMS DATACLAS update utility


Using SMS MGMT Classes

You can use batch jobs to define MGMT classes and to specify the EXPIRE AFTER time (in days).

Currently, other mainframe MGMTCLAS properties are not supported.

MGMTCLAS maintenance utility

You can use a TSO-like command executed with the IKJEFT01 utility to save, view and delete MGMTCLAS values.

The following is an example of using the MGMTCLAS utility:

//ISDCS01 JOB 'COPY01',CLASS=A,MSGCLASS=A
//*------------------------------------------------------------------
//STEP30   EXEC PGM=IKJEFT01
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSTSIN   DD *
   %SMS    MGMTCLAS  NAME(YYYY) EXPIREAFTER(000365) FUNC(ISRT)
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//

You can use MGMTCLAS with the following parameters:

%SMS
Invokes the SMS maintenance program.
MGMTCLAS
Accesses the MGTCLASS maintenance routines.
NAME
The name of the MGMTCLAS. This must be between one to eight characters long.
EXPIREAFTER
The number of days after which the dataset expires.
FUNC
A function to use for the MGMTCLAS. The available functions are:
DLET
Deletes the specified MGMTCLAS. Requires the NAME parameter.
GN
Gets the next MGMYCLAS record. Requires a pervious GU or STN< parameter.
GU
Retrieves the specified MGMTCLAS. Requires the NAME parameter.
ISRT
Inserts the specified MGMTCLAS. Requires the NAME and EXPIREAFTER parameters.
STN<
Starts not less than. Positions on the first MGMTCLAS not less than the specified NAME to set position for subsequent get next.

Using the MGMTCLAS maintenance utility in JCL

You can use the MGMTCLAS parameter on the DD statement to catalog a new dataset in JCL. For example:

//DEF     EXEC PGM=IEFBR14
//DEF1 DD DSN=TEST.MCLAS,DISP=(NEW,CATLG),
//        MGMTCLAS=(XXXX),UNIT=SYSDA

In this example, JCL uses the EXPIREAFTER value associated with the MGMTCLAS to calculate an expiry date for the dataset. This is held on the catalog and can be used by any catalog maintenance utilities to expire old datasets.

DATACLAS maintenance for the MGMTCLAS utility

The MGMTCLAS utility includes a DATACLAS maintenance function.

You can use the %SMS command to maintain DATACLAS - for example:

%SMS DATACLAS NAME(ABC) RECFM(FB) LRECL(80) FUNC(ISRT)

Where the DATACLAS parameters that this example uses are:

NAME
The name of the DATACLAS to be accessed. This is ABC in this example.
RECFM
A property of DATACLAS. This is FB in this example.

Other properties of DATACLAS that you can use are: AVREC, AVVALUE, BLKSIZE, DIRECTORY, DSORG, KEYLEN, KEYOFF, LRECL, NAME, PRIMARY, RECFM, RECORG and SECONDARY .

Parent topic: Using SMS Data Classes


IBM Hexadecimal Format Floating Point Data

Enterprise Developer enables you to use floating point data in either IEEE or IBM hexadecimal formats, enabling you to share floating point data seamlessly between mainframe and PC. This chapter describes how to use the different floating point formats in Enterprise Developer.

  • Using Different Floating Point Formats
  • The MAINFRAME_FLOATING_POINT Environment Variable
  • Editing Data Files
  • Range
Parent topic: Compatibility with the Mainframe Environment


Using Different Floating Point Formats

The following sections describe how you use the different formats of floating point data in Enterprise Developer.

  • Compiling
  • Running
Parent topic: IBM Hexadecimal Format Floating Point Data


Compiling

When compiling a program that always requires the use of a particular format of floating point data items, you use the NATIVE-FLOATING-POINT directive. Setting NATIVE-FLOATING-POINT specifies that IEEE format floating point data items are used, regardless of the setting of the MAINFRAME_FLOATING_POINT environment variable. Setting NONATIVE-FLOATING-POINT causes the floating point format to be determined by the MAINFRAME_FLOATING_POINT environment variable.

See the section Running for information on the MAINFRAME_FLOATING_POINT environment variable and NATIVE-FLOATING-POINT for more information on the NATIVE-FLOATING-POINT Compiler directive.

Parent topic: Using Different Floating Point Formats
Related reference
NATIVE-FLOATING-POINT
Related information
Running


Running

You control the floating point format that is used at run-time using either of the following:

  • mainframe_floating_point tunable. See mainframe_floating_point for more information.
  • MAINFRAME_FLOATING_POINT environment variable. See the section The MAINFRAME_FLOATING_POINT Environment Variablethe chapter Environment Variables in your User's Guide for more information.

If both are specified, the setting of the MAINFRAME_FLOATING_POINT environment variable overrides the setting of the mainframe_floating_point tunable.

Parent topic: Using Different Floating Point Formats
Related reference
Environment Variables
Environment variables (Windows)
mainframe floating point
Related information
The MAINFRAME_FLOATING_POINT Environment Variable


The MAINFRAME_FLOATING_POINT Environment Variable

Possible formats for the MAINFRAME_FLOATING_POINT environment variable are IBM hexadecimal and IEEE.

  • Syntax
  • Parameters
  • Comments
Parent topic: IBM Hexadecimal Format Floating Point Data
Related information
Running


Syntax

SET MAINFRAME_FLOATING_POINT=fp-status
Parent topic: The MAINFRAME_FLOATING_POINT Environment Variable


Parameters

fp-status
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.
Parent topic: The MAINFRAME_FLOATING_POINT Environment Variable


Comments

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. See NATIVE-FLOATING-POINT for more information.

You must set the MAINFRAME_FLOATING_POINT environment variable from an Enterprise Developer command prompt before you start Enterprise Developer for it to take effect.

Parent topic: The MAINFRAME_FLOATING_POINT Environment Variable
Related reference
NATIVE-FLOATING-POINT


Editing Data Files

When editing data files, you can specify whether floating-point data items are interpreted as IEEE format or IBM hexadecimal format. To do this, you use a new drop-down list on the Data File Toolbar, as shown below:

Figure 1. File Toolbar Showing the Floating-point Format Drop-down List
File Toolbar Showing the Floating-point Format Drop-down List

Select the format you want to use from the list, and the floating-point data items are displayed in the format you choose. The default is determined by the setting of the MAINFRAME_FLOATING_POINT environment variable.

Note:

You cannot edit floating-point data in the Data File Editor.

Parent topic: IBM Hexadecimal Format Floating Point Data


Range

IBM hexadecimal format floating point data items must contain values in the following ranges:

Type | Minimum Value | Maximum Value
COMP-1 | 5.5E-79 | 7.2E75
COMP-2 | 5.5E-79 | 7.2E75
Parent topic: IBM Hexadecimal Format Floating Point Data


Assembler Programs

The product now contains a command line version of MFASM, the mainframe assembler emulator for IBM High Level Assembler programs, that allows users to create assembler executables or data tables within the Eclipse environment. The MFASM component is an early adopter release intended to provide a test environment for COBOL applications to call needed assembler subroutines which have already been developed and debugged in other environments. This test environment is for Enterprise Developer only and does not include a debug facility for Assembler. Assembler executables do not run in production environments.

  • MFASM
    Use the MFASM command to assemble and link Assembler applications in one step, producing executable subroutines, and debugging modules.
  • Using the Generalized Trace Facility
  • Diagnosing Abends
Parent topic: Mainframe Emulation


MFASM

Use the MFASM command to assemble and link Assembler applications in one step, producing executable subroutines, and debugging modules.

Syntax:

MFASM filename.mlc [option ...][;]

Parameters:

filename
The name of an Assembler source file.
option
An Assembler compiler directive

Comments:

MFASM produces the following files:

  • filename.obj - An object module used by the assembler linker
  • filename.idf and filename.idx - debugging files used by the Assembler debugger
  • filename.390 - An executable Assembler program.
The most commonly-used Assembler compiler directives are:
  • NOANIM
  • NOLIST
  • BAL
  • AMODE(31)

Examples:

Example 1 - Producing an executable program

MFASM test.mlc NOANIM

Here the NOANIM option is also used to suppress the generation of unnecessary debug files. To ensure that the resulting executable file, in this example TEST.390, is picked up by the COBOL runtime, move it to the same subdirectory as other COBOL executables in the application. At CALL time, the COBOL runtime searches for and loads executables with the .390 file extension as it would any other executable file with extensions such as .dll.

Example 2 - Producing data tables

Assembler data tables are produced by using the OMF (MOD) directive to generate files with the .mod extension as follows:

MFASM test.mlc OMF(MOD)NOANIM NOLIST

To ensure that the resulting .mod file, in this example test.mod, is loaded into memory along with other CICS programs by use of the EXEC CICS LOAD command, move it to the same subdirectory as other COBOL executables in the application.

Parent topic: Assembler Programs
Parent topic: Assembler Command Line Reference


Using the Generalized Trace Facility

The Assembler Generalized Trace Facility (GTF) is a debugging tool that helps speed up the process of isolating the location and cause of a problem in an Assembler program. You use the GTF tool to create a trace file showing the operations performed by the program. You do not have to compile the program for debugging. You can request different levels of detail: for example, you can run a trace requesting program level information and then run a further trace on a specific section by specifying the level of detail and the start and end points for the trace.

Note: Under the Enterprise Server environment any trace file will be locked for exclusive access by the server, so in order to examine the file you must first stop the server.

To turn on the Generalized Trace Facility, set the environment variable GTFFILE to the absolute path and file name of the trace file. You set this environment variable in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin\MF370CTL.CFG file.

Configuring GTF

You can specify the following GTF options after the GTFFILE environment variable:

Option | Description
GTFIMIN | The instruction count at which to start the trace. The default is 00000000.
GTFIMAX | The instruction count at which to end the trace. The default is FFFFFFFF.
GTFAMIN | The instruction address at which to start the trace. The default is 00000000.
GTFAMAX | The instruction address at which to end the trace. The default is FFFFFFFF.
GTFOPT The level of detail. You can set this environment variable to one or more of the following three-character codes separated by commas to indicate the level of detail you want:
INS
Trace each instruction
BAL
Trace each BALR, BASR, and BASSM instruction
SVC
Trace each SVC instruction
PGM
Trace each LOAD, DELETE, and LINK
FOC
Trace each file OPEN and CLOSE operation
FIO
Trace each file input and output operation, as well as each OPEN and CLOSE
MEM
Trace GETMAIN, FREEMAIN, and STORAGE
ALL
All of the above trace options
REG
Trace the 16 general-purpose registers at each trace event
The default value is BAL, PGM, FOC.

The size of a trace file depends on the options that you specify and can be very large. Therefore we recommend that you always begin by running a trace with the default options to find out the optimum starting point for a detailed trace. When you run a detailed trace, using options such as FIO, INS or ALL, specify the start and end points using the GTFIMIN and GTFIMAX or the GTFAMIN and GTFAMAX options.

You can also specify the REG option with any other option if you want the contents of the 16 general-purpose registers at each trace point. Note that this increases the size of the trace file by a factor of three. The contents of the registers are shown as they were just before the trace operation, hence the REG option is most useful with the following options:
  • INS, because this traces every instruction
  • MEM and PGM, because with these options the trace is performed at the end of the instructions affected such as LOAD and GETMAIN

Regardless of the trace options you have specified, whenever a program interruption occurs the trace file contains extra lines for the instruction causing the interruption. These lines show the program status word (PSW), which contains the interruption code in the low-order byte of the first word, and the registers.

The Trace File

You can view or print the GTF trace file using any ASCII-compatible editor or word processor. The file begins with the GTF options used to generate the file, and the date and time the trace started. The last line of the file shows the date and time the trace ended. If this line is not present, the trace is probably incomplete because it was not closed properly. This can happen if you are running an interactive debugging session using the Assembler debugger with the Generalized Trace Facility turned on, and an unrecoverable error occurs. To ensure that the GTF trace file is complete, you must allow the debugging session to end without being forced: press S(tep) or G(o) to record the program exception on the trace file and then stop the debugging session.

In between the information at the beginning of the file and the last line are individual trace records. Each of these includes the following items of information:
  • Instruction count. This is a hexadecimal counter showing the total number of instructions executed up to the trace point. This count is very useful when you want to work out where to start a detailed trace at a point deep into a complex application where the same code may be executed many times before the point of failure. You use the option GTFIMIN to set the starting instruction count for a trace.
  • Instruction address. This is the linear address of the next instruction at the current trace point. This address provides an alternative way of specifying where you want a detailed trace to start. You use the option GTFAMIN to set the starting instruction address for a trace.
  • Instruction operation. This field indicates the machine instruction or run-time operation being performed at the trace point. Additional information may follow depending on the type of trace line:
    Trace Line Type | Description
    INS | The hexadecimal machine instruction, which can be 2, 4, or 6 bytes in length
    PGM | The program name and entry for LOAD, DELETE, or LINK
    FOC and FIO | The DCB, ACB, or DTF control block address
    MEM | Length and address of memory allocated or deallocated
Default Trace Option
Use the default trace option GTFOPT=PGM,BAL,FOC to trace LOAD, DELETE, LINK, BALR, BASR, OPEN, and CLOSE operations. This enables you to get an overview of what an application is doing and to identify possible starting and ending points for more detailed traces if required.

Below is an example trace file for a default trace of an IMS COBOL and Assembler application:

GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG
GTF option GTFOPT  =BAL,FOC,PGM
GTF option GTFIMIN =00000000
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=08495898
INS-CTR  INS-ADDR INS-OP
00000043 81000188 BALR     05EF
00000044 81005998 BALR     05F0
00000047 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00000051 810001E6 LOAD     NAME=LDDECTBL ENTRY=810059D8
000006DA 8100033A BALR     05EF
00000704 81005998 BALR     05F0
00000707 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00000762 81000E10 LOAD     NAME=CG#CTL   ENTRY=80012CF0
00000988 810059B0 BALR     05F0
0000098B 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001051 8100033A BALR     05EF
0000107B 81005998 BALR     05F0
0000107E 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
000012F7 810059B0 BALR     05F0
000012FA 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001360 8100033A BALR     05EF
0000139C 81005998 BALR     05F0
0000139F 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00001618 810059B0 BALR     05F0
0000161B 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001CDC 8100033A BALR     05EF
00001D06 81005998 BALR     05F0
00001D09 810059A2 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00001F82 810059B0 BALR     05F0
00001F85 810059BA LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00001F92 810003EA DELETE   NAME=LDDECTBL ENTRY=00000000
00001FED 81007628 BALR     05EF
00001FEE 8100CE38 BALR     05F0
00001FF1 8100CE42 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
00001FFB 81007686 LOAD     NAME=LDDECTBL ENTRY=80011228
00002684 810077DA BALR     05EF
000026AE 8100CE38 BALR     05F0
000026B1 8100CE42 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000270C 810082B0 LOAD     NAME=CG#CTL   ENTRY=8100CE78
00002932 8100CE50 BALR     05F0
00002935 8100CE5A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
00002FFB 810077DA BALR     05EF
.........................................
.........................................
0000B04A 81022160 BALR     05F0
0000B04D 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000B0AA 8101CAEA BALR     05EF
0000B0EF 81022148 BALR     05F0
0000B0F2 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000B114 81022160 BALR     05F0
0000B117 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000B174 8101CAEA BALR     05EF
0000B1B0 81022148 BALR     05F0
0000B1B3 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000B4A4 81022160 BALR     05F0
0000B4A7 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000B501 8101CAEA BALR     05EF
0000B519 81022160 BALR     05F0
0000B51C 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000BBE2 8101CAEA BALR     05EF
0000BC0C 81022148 BALR     05F0
0000BC0F 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000BE8D 81022160 BALR     05F0
0000BE90 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000BEED 8101CAEA BALR     05EF
0000BF32 81022148 BALR     05F0
0000BF35 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000BF51 81022160 BALR     05F0
0000BF54 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000BFB1 8101CAEA BALR     05EF
0000BFED 81022148 BALR     05F0
0000BFF0 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000C2E1 81022160 BALR     05F0
0000C2E4 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000C33E 8101CAEA BALR     05EF
0000C356 81022160 BALR     05F0
0000C359 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000C3BF 8101CAEA BALR     05EF
0000C3FB 81022148 BALR     05F0
0000C3FE 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000C67C 81022160 BALR     05F0
0000C67F 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000CD40 8101CAEA BALR     05EF
0000CD6A 81022148 BALR     05F0
0000CD6D 81022152 LINK     NAME=AIBTDLI  ENTRY=(COBOL)
0000CFEB 81022160 BALR     05F0
0000CFEE 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000CFFB 8101CB9A DELETE   NAME=LDDECTBL ENTRY=00000000
GTF trace file DATE=000114 TIME=08514748
Detailed Trace Option
Use the GTFOPT=ALL option to obtain a detailed trace.

Below is an example of a detailed trace of the last section of code starting with BALR (instruction count CFEB) in the default trace example above. Options GTFOPT=ALL and GTFIMIN=0000CFEB were used to obtain this trace.

GTF option GTFFILE =D:\MFUSER\CONFIG\GTF.LOG
GTF option GTFOPT  =ALL
GTF option GTFIMIN =0000CFEB
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=09370586
INS-CTR  INS-ADDR INS-OP
0000CFEB 81022160 BALR     05F0
0000CFEC 81022162 ICM      BF08F00D
0000CFED 81022166 LA       41F0F00E
0000CFEE 8102216A SVC      0A27
0000CFEE 8102216A LINK     NAME=ASMTDLI  ENTRY=(COBOL)
0000CFEF 8102216C BCR      07FE
0000CFF0 8101DBFA L        58D0D004
0000CFF1 8101DBFE L        58E0D00C
0000CFF2 8101DC02 BCR      07FE
0000CFF3 8101CAEC L        58E0B092
0000CFF4 8101CAF0 BCR      07FE
0000CFF5 8101C864 BAS      4DE0B3B4
0000CFF6 8101CB7A ST       50E0B092
0000CFF7 8101CB7E CLC      D501300AB484
0000CFF8 8101CB84 BC       4770B40C
0000CFF9 8101CB88 L        5860B446
0000CFFA 8101CB8C BAL      4500B3D2
0000CFFB 8101CB98 SVC      0A09
0000CFFB 8101CB9A DELETE   NAME=LDDECTBL ENTRY=00000000
0000CFFC 8101CB9A LTR      12FF
0000CFFD 8101CB9C BC       4770B412
0000CFFE 8101CBA0 L        5810B4B6
0000CFFF 8101CBA4 L        5890B4BE
0000D000 8101CBA8 L        5860B442
0000D001 8101CBAC LR       1809
0000D002 8101CBAE LH       48F0B3EE
0000D003 8101CBB2 BC       47000003
0000D004 8101CBB6 SVC      0A78
0000D004 8101CBB8 FREEMAIN  LOC=  00010EC8 LEN=  00000359
0000D005 8101CBB8 LTR      12FF
0000D006 8101CBBA BC       4770B412
0000D007 8101CBBE L        5810B4D6
0000D008 8101CBC2 LH       48F0B4D2
0000D009 8101CBC6 LA       4120B49A
0000D00A 8101CBCA LH       4830B482
0000D00B 8101CBCE SR       1B55
0000D00C 8101CBD0 MVCL     0E24
0000D00D 8101CBD2 L        58E0B092
0000D00E 8101CBD6 BCR      07FE
0000D00F 8101C868 L        58D0B04E
0000D010 8101C86C ST       50FD0010
0000D011 8101C870 LM       98ECD00C
0000D012 8101C874 BCR      07FE
0000D013 80000860 SVC      0A00
GTF trace file DATE=000114 TIME=09375776
Program Interruption Information
Here is the trace file for a program that attempts to add 1 to a packed decimal field containing spaces. The PSW contains interrupt code 7 corresponding to the MVS abend 0C7 that would occur on the mainframe.
GTF option GTFFILE =GTF.LOG
GTF option GTFOPT  =ALL
GTF option GTFIMIN =00000000
GTF option GTFIMAX =FFFFFFFF
GTF option GTFAMIN =00000000
GTF option GTFAMAX =FFFFFFFF
GTF trace file DATE=000114 TIME=10565281
INS-CTR  INS-ADDR INS-OP
00000001 81007FE8 BALR     05C0
00000002 81007FEA LA       41100002
00000003 81007FEE AP       FA10C00CC00E
 R0-R7 00000000 00000002 00000000 00000000 00000000 00000000 00000000 00000000
 R9-RF 00000000 00000000 00000000 00000000 81007FEA 00002870 00000860 01007FE8
00000003 81007FF4 PGMCHK   PSW=0000000781007FF4
GTF trace file DATE=000114 TIME=10565286
Parent topic: Assembler Programs


Diagnosing Abends

Why does my program abort with 0C5 addressing error immediately when it is called from COBOL?
The default COBOL compile option under Enterprise Developer is NOAMODE. This means any parameters passed to an assembler module will be in native PC addressing format and will generate an OC5 addressing error immediately at CALL time. To enable 370 mainframe style addressing in your COBOL program you must use the AMODE(24) or AMODE(31) compiler directive
Why does my program abend immediately when it is called from COBOL?
An abend can be caused by invalid 31 bit addresses being passed to a 24 bit assembler program. In this case, you should set the DATA(24) directive to force all COBOL working storage data addresses to be 24 bits.
What is the fastest way to get help debugging an abend in a large complex application?
Generating a GTF instruction trace might be the fastest way to find the problem. From a GTF trace file, you can determine the failing program, and the exact instruction path followed until the abend. Remember that the trace file gives the actual 370 machine code that is being emulated. This same machine code appears in assembler listing (.PRN) files and can be searched for with any text editor.
Parent topic: Assembler Programs


Language Environment (LE) Support

Language environment is a set of standard callable routines and run-time options that can be used in any MVS 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: Mainframe Emulation
Related information
IBM Language Environment Programming Reference
IBM Language Environment Programming Guide


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, or by setting the ES_LE370_SUPPORT environment variable. The method used depends on how you intend to use the support.
Enable LE support depending on your application type:

JCL

LE support is enabled by default unless the name of the program you are running begins with 'MF'; in which case, set the INITCALL"MFLEINIT" Compiler directive.

Enterprise Server (Excluding JCL)

For all other applications running in Enterprise Server, set the environment variable ES_LE370_SUPPORT=Y.

Other Native COBOL Use

For any other method, for example, an IMS or standard COBOL program, set the INITCALL"MFLEINIT" Compiler directive.

Managed JVM

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin.
    • For 64-bit environments you must use a 64-bit JVM. The mfle370.jar file is located at %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\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.*;.

Enabling LE Support in an Eclipse Project

JVM COBOL

For JVM COBOL applications, add the mfle370.jar file to the project JVM build path.

  1. Right-click the JVM COBOL project, and then click Properties.
  2. Click Micro Focus > JVM Build Path.
  3. Click the Libraries tab.
  4. Click Add External JARs.
  5. Navigate to the location of the mfle370.jar file, and then click Open.
  6. Click OK.
  7. There are two ways to apply this to your application:
    • In your code:
      1. Set the ILUSING directive with the com.microfocus.le370 namespace.
    • In your Additional directives in the project properties:
      1. Click Project > Properties > Micro Focus > Build Configuration.
      2. Type ILUSING"com.microfocus.le370" in the Additional directives field.

Java

For Java applications, add the mfle370.jar, mfcobol.jar and mfcobolrts.jar files to the project build path.

  1. Right-click the Java project, and then click Properties.
  2. Click Java Build Path.
  3. Click the Libraries tab.
  4. Click Add External JARs.
  5. Navigate to the location of the mfle370.jar file, and then click Open.
  6. Repeat the previous two steps for the mfcobol.jar and mfcobolrts.jar files.
  7. Click OK.
  8. In your code, add the import 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.
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 | No **
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 | 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 reference
File Handling and Dataset Environment Variables
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:

SET MFLECONFIG = c:\templates\prod\le_set1.cfg
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
Related information
IBM Language Environment Programming Reference


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


PL/I Programming

  • CodeWatch User's Guide
  • Open PL/I User's Guide
Parent topic: Mainframe Programming


CodeWatch User's Guide

This section describes how to use CodeWatch, which provides interactive, source-level debugging capability for PL/I development.

  • Overview
    This section provides an overview of the Micro Focus CodeWatch application.
  • Getting Started
    This section provides information to help get you up and running with CodeWatch. The following sections discuss program preparation, invoking the correct interface, CodeWatch files, multiple modules, and basic window and dialog navigation.
  • The Command-line Interface
    This section provides information on entering debugger commands. The command-line interface applies to the command-line version of the debugger (-classic), commands in action lists, and commands entered in the Command window of the graphical interface.
  • Debugging Concepts
    This section describes debugger concepts including action lists, pointers, environments, CodeWatch error messages, and program recovery.
  • CodeWatch Functionality
    This section describes the facilities that let you control the execution of your program, discusses environment control issues, explains how to examine, modify, and evaluate the contents of data items, and describes features such as the macro facility, debugger command files, and on-line help.
  • CodeWatch Commands
    This section lists and describes all of the CodeWatch commands in alphabetical order. The definitions consist of subsections that contain information on use, command syntax, a brief description, and a command-line example.
  • Debugging Open PL/I Programs
    This section describes CodeWatch features that relate to debugging PL/I programs and contains a sample command-line debugging session of an Open PL/I program. At the end of this section, the listing of the program used in the sample debugging session is provided. The source of the sample program is also available on the release media.
  • Troubleshooting
Parent topic: PL/I Programming


Overview

  • Introduction
  • Summary of Features
  • Prerequisites
Parent topic: CodeWatch User's Guide


Introduction

Effective source-level debugging can help shorten the time spent on finding programming errors. A program may behave abnormally even after being successfully compiled. Although such a program's syntax is correct, the program still contains programming errors, or bugs, that cause unpredictable consequences such as unintended changes to the values of variables, infinite loops, incorrect output, or abnormal program termination.

Debugging is the process of discovering these bugs and eliminating them. Source-level debugging involves examining and modifying the source language elements of a program while it executes.

CodeWatch is a powerful software development tool that can help you locate bugs in programs. There are two flavors of CodeWatch available: one with a command-line interface and one with a graphical user interface. The command-line version offers a traditional line-oriented interface allowing you to interactively enter commands from the keyboard. The graphical user interface offers at least two main windows: one that allows you to enter commands and one that allows you to view your source code. You access CodeWatch commands through pull-down menus and dialog boxes.

CodeWatch keeps track of variables, subroutines, and data types in terms of the symbols used in the source language. You can reference these items without having to consider the underlying machine language or architecture. You can use CodeWatch to access the source text of the program, to identify and reference program entities, and to detect errors in the program's algorithms and logic.

Parent topic: Overview


Summary of Features

The following is a list of CodeWatch features.

Controlling Program Execution

CodeWatch has control over the execution of the program. Program execution can be started at a specified point, stopped and resumed at different points, transferred from one point to another, and terminated at any point.

  • Breakpointing: Breakpoints can be set to suspend execution at specified source program statements. The status of the program can then be evaluated or modified.
  • Catching: Process control can be returned to the debugger when a given signal is generated.
  • Stepping: Program execution can be stepped by one or more source program statements at a time. The debugger can also step into, over, or out of a called procedure.
  • Tracing: Tracepoints can be set at statements or at procedure and block entries to track program execution.
  • Watchpointing: Watchpoints can be set to monitor given variables. When the contents of a watched variable change, program execution stops and control is returned to the debugger.

Examining the Source Program

CodeWatch allows you to examine the source program, find specified text strings, move to specified line numbers, and examine included source files.

Environment Control

CodeWatch allows you to set the evaluation environment it uses to provide scope for referencing a specific instance of a variable or statement.

Symbolic Access

The value of a variable can be examined and/or altered as program execution continues. Procedure entries and exits can be monitored at the debugger command level. Expressions can be evaluated using the Evaluate command.

Action Lists

One or more of the debugger commands can be combined and executed at step and breakpoints.

Macro Facility

Macros can be defined as a sequence of debugger commands that will be used repeatedly throughout a debugging session. The macros can then be used like any other debugger command.

Command Files

Debugger command files can be created with a text editor or by logging commands to a specified file during a debugging session. These command files can then be used to execute the predefined sequence of debugging commands automatically during a debugging session.

Issuing Error Messages

CodeWatch identifies error conditions and issues meaningful, complete sentence error messages.

Parent topic: Overview


Prerequisites

  • Java 6 (Java JRE 1.6) or later must be installed on the machine using Java CodeWatch for debugging.
  • Make sure you are logged with your personal account and not with the Windows SYSTEM account when starting the ES region from the ESMAC Web user interface interface, otherwise the debugger will not start up. This is due to the SYSTEM account not having an active Windows desktop in which to display the debugger interface to the user.
Parent topic: Overview


Getting Started

  • Program Preparation
  • Invoking CodeWatch
  • Debugging a Program with Multiple Modules
  • Ending a Debugging Session
Parent topic: CodeWatch User's Guide


Program Preparation

A program must be compiled using the -deb option before it can be run under the control of the debugger. This is because the compiler generates a data base file referred to as the STB file. This file contains symbolic information that the debugger needs to reference to manipulate source program symbols and entities; set breakpoints, tracepoints, and watchpoints; and control program execution. A program is referred to as being compiled in debug mode when one or more of the program modules have been compiled with the -deb option.

For example, a PL/I program contained in a source file named primes. pl1 is compiled in debug mode by entering the following command line:

mfplx primes.pl1 -deb
Parent topic: Getting Started


Invoking CodeWatch

Once the program has been compiled in debug mode and linked, you can use CodeWatch to debug your program. To invoke CodeWatch, use one of the following command formats:

GUI CodeWatch:

java –jar cw_java.jar <pgm_name> -sessionlog <filename> -commands <commands>
Note: The Enterprise Developer environment must be available when invoking CodeWatch.

where:

<pgm_name> | The name of program executable to debug.
-sessionlog | The fully qualified file name to write the log of debugger commands issued and command output received during the debugging session.
-commands | The list of debugger commands to execute upon CodeWatch start-up. Separate each command with a comma.
Tip: You can also use the MF_CODEWATCH_INIT environment to specify the fully qualified location of a file containing debugger commands to be executed upon start-up.

Command-line CodeWatch:

cwcmd [-classic]
      [-x]
      [-e]
      [-srcpath [source_directory [:source_directory] ...]]
      [-stbpath [STB_directory [:STB_directory] ...]]
      [-path [directory [:directory] ...]]
      [-usrin filename]
      [-usrout filename]
      [-8bit]
      [program-name]
      [program-arguments]

where:

-e (echo) | Specifies that every debugger command entered echoes back to the terminal.
-srcpath, -stbpath, and -path | Specify directory paths to be searched for source and STB files. See Searching for Source and STB Files for more information.
usrin and -usrout | Specify files to redirect user program input from or output to, respectively. See Redirecting User Program I/O for more information.
8bit | Allows CodeWatch to treat an extended set of ASCII characters as printable. See Extended ASCII Character Support for more information.
program-name | The name of the executable file to be debugged. If the debugger is invoked without a program-name argument, the a.out file in the current directory is used if it exists; otherwise, CodeWatch starts without loading a file for debugging.
program-arguments | Command-line arguments to be passed to the program.

CodeWatch does not require a program to load for debugging when starting. However, on UNIX systems, CodeWatch first looks for a.out as the default program name. When CodeWatch comes up standalone, a LOAD or ATTACH command must be used to specify the program to be debugged.

  • Starting the CodeWatch Debugger
    Describes various ways to access the CodeWatch debugger for PL/I programs.
  • Defining Debug Settings in PLIDEBUG.DAT
  • The STB File
  • Searching for Source and STB Files
  • Redirecting User Program I/O
  • Extended ASCII Character Support
  • Start-up Files
Parent topic: Getting Started
Related information
In Search of Source and STB Files


Starting the CodeWatch Debugger

Start the CodeWatch debugger by doing one of the following:
From the Visual Studio IDE | After creating the debug configuration for your project, right-click to select the project in the Solution Explorer and choose Debug > Start new instance , or Debug > Step into new instance.
From the Eclipse IDE | After creating the debug configuration for your project, click the Debug button in the Debug Configurations dialog box. You can also select the project in the PL/I explorer and choose Run > Debug. See Debugging a PL/I project for more on starting the CodeWatch debugger from the Eclipse IDE.
From the command line | Execute the command cwcmd <program name> from the command line, or execute the command cwcmd by itself to attach to a currently running process. See The Command-line Interface for more on using the CodeWatch debugger's command-line interface.
Using plidebug.dat | You can use plidebug.dat on Windows Enterprise Server to cause the PL/I run time to start the debugger automatically when your program starts. Note: This is currently supported only on Windows platforms. See Defining Debug Settings for more information on using the plidebug.dat to automatically start the debugger.
Call to PLITEST | Use a call to the PLITEST built-in in the user program to start and attach the debugger. The call to PLITEST can be used at any point in the user program to invoke the debugger. See PLITEST for more information on the parameters used in the built-in for invoking the debugger and a code sample.
Parent topic: Invoking CodeWatch
Related reference
PLITEST Subroutine
Related information
CodeWatch Commands


Defining Debug Settings in PLIDEBUG.DAT

Note: Using PLIDEBUG.DAT is currently only supported on Windows platforms.

CodeWatch lets you specify debug initialization settings for individual programs in the control file called PLIDEBUG.DAT. This file is utilized by the PL/I runtime whenever a program is initialized under Enterprise Server. It is automatically created if it doesn't exist in the location pointed to by the PL/I Configuration directory setting in the Enterprise Server Administration PL/I tab. You can edit this file from Enterprise Developer to define the program name and how to start and initialize CodeWatch.

When using PLIDEBUG.DAT, there should be only one record for each program you wish to debug under Enterprise Server.
Important: The control record is column sensitive so be careful when constructing a record for your program. A corresponding layout file (PLIDEBUG.STR) is available in the PL/I Enterprise Server demos for assistance with column/data alignment.
Example:
 --- 0---|--- 10---|--- 20---|--- 30---|--- 40---|--- 50---|--- 60---|--- 70---|--- 80---|--- 90---|
123456789|123456789|123456789|123456789|123456789|123456789|123456789|123456789|123456789|123456789|
TESTPGM1            N 0 SHLIB TESTPGM1.DLL;ENV TESTPGM;BR %ENTRY;BR %EXIT [DET;Q];C
Important: The starting column is assumed to be 0 as this is the default. It can be changed to 1 from the Data Tools Options.

This table outlines the values needed for each record in PLIDEBUG.DAT.

Column(s) | Value | Description
0 through 7 | <program name> | User program name (without file extension). For example: TESTPGM1
20 | Y/N (Yes/No) | Indicates whether to start the debugger when the program executes. Set to N to skip attaching the debugger.
22 0/1 The debugger flavor used to debug the entry. Values are:
  • 0 = Use the CodeWatch command line debugger.
  • 1 = Use the CodeWatch GUI debugger
24-nn | <text string> | Initial set of debugger commands to be issued by CodeWatch during start-up before control is given over to the user.

For example:

TESTPGM1            N 0 SHLIB TESTPGM1.DLL;ENV TESTPGM;BR %ENTRY;BR %EXIT [DET;Q];C

TESTPGM2            N 1 SHLIB TESTPGM2.DLL;ENV TESTPGM;BR %ENTRY;BR %EXIT [DET;Q];C

Editing PLIDEBUG.DAT

To open the and edit the debug configuration file:

  1. After running your JCL job to create the PLIDEBUG.DAT file, right-click the file in the Solution Explorer and choose Open File in Data Tools. The Micro Focus Data Tools application starts.
    Note: A message box may appear indicating that edits to the file are applied immediately. Select the Do not show this message again check box to prevent this message from appearing. Then click OK.
  2. Right-click in the record editor for PLIDEBUG.DAT and choose Insert Indexed Record. The Insert indexed record dialog box appears.
  3. Enter the value for the User program name without the file extension. This is the Unique key for the record. Click OK. A line appears showing the Unique key appears in the record editor.
  4. On the line with the new record, click on column 20 and enter Y or N to indicate whether to start the debugger when the program executes.
    Note: Make sure that the first Y is in column 20. The current line and column numbers are shown in the information bar at the bottom of the window. Note that the starting column is assumed to be 0 as this is the default. It can be changed to 1 from the Data Tools Options. If your starting point is 1, make sure that the first Y is in column 21.
  5. Click on column 22 and enter 0 or 1 to specify which debugger to use.
  6. Click on column 24 and enter the remaining values for the initialization text string. See the section CodeWatch Commands for detailed information on commands you can use in the initialization text string.
    Note:

    The Data Tools status bar shows the cursor's current column location. Changes are saved immediately to the file.

    When you begin to enter the remaining values for the record, a message box asks you to confirm that you want to edit the record. Click OK. You can also turn the update warning off for the file in the message box.

Parent topic: Invoking CodeWatch
Related information
CodeWatch Commands


The STB File

When a program source file is compiled in debug mode, a file called the STB file (symbol table file) is created, which contains important information needed by the debugger during the debugging session. The name of this file is constructed by replacing the extension of the source file name (for example, .pl1 for a PL/I program), with an .stb extension. This STB file is placed by default in the directory in which the compilation took place.

  • Compressed STB Files
Parent topic: Invoking CodeWatch


Compressed STB Files

Code Watch handles compressed STB files. If you wish to compress your STB files, do so, and the debugger will uncompress them when it needs to access them. This happens, for example, when you step into a new evaluation environment for which the STB file has been compressed. An STB file is only uncompressed once during a debug session and remains uncompressed until you quit the debugger.

When you quit the debugger, you will be given a list of STB files that have been uncompressed during the debug session. You will be asked whether or not you would like to re-compress the files.

When quitting the debugger, you need not wait while all the STB files are being re-compressed. The re-compression process is forked off into another process.

Debug sessions run by another user accessing the same set of STB files with which you are working will not compress or uncompress an STB file out from under you. When the debugger is in the process of uncompressing an STB file, it writes a lock file to the directory in which your STB files reside, telling other debugger processes to wait until the uncompression is finished (for that STB file).

Note:

To write the lock file and to do the actual uncompression you must have write permission to the directory in which your STB files exist.

It is possible to use a compression utility other than compress. To do this, you must set the following three environment variables:

CW_COMPRESS_COMMAND | Set this environment variable to the command used to compress the STB files.
CW_UNCOMPRESS_COMMAND | Set this environment variable to the command used to uncompress the STB files.
CW_COMPRESS_SUFFIX | Set this environment variable to the suffix that denotes that the file is compressed (.Z for the compress utility).

The following are command-line examples for setting these environment variables:

setenv CW_COMPRESS_COMMAND   pack
setenv CW_UNCOMPRESS_COMMAND unpack
setenv CW_COMPRESS_SUFFIX    .z

The following command-line switches are used for the handling of compressed STB files:

-nocompress | Tells the debugger not to look for compressed STB files. If you are not going to compress your STB files, this is a good switch to use, because it saves the debugger that extra time of looking for compressed STB files.
-forcecompress | Causes the debugger to re-compress automatically any files that have been uncompressed during the debug session, without prompting you when you Quit out of the debugger. In the command-line interface, you will still be given a list of which files will be re-compressed, but in the Windows interface you will not be given this information.
Parent topic: The STB File


Searching for Source and STB Files

After the program is linked and CodeWatch is invoked with the loaded executable file as an argument, the debugger requires access to both the program source file(s) and the STB file(s).

The source file(s) will, by default, be searched for first in the directory that was specified to the compiler (relative to the current directory), and if not found, then in the current directory.

The STB file(s) will, by default, be searched for first in the current directory (where they are created), and if they are not found, they will be searched for in the directory that was specified to the compiler. This is the exact opposite of the search algorithm used for source files.

It is possible through the use of debugger command-line arguments and/or environment variables to specify alternate directories in which to search for both source and STB files before the default directories are searched.

The CodeWatch options -srcpath and/or -stbpath, followed by a list of directory names separated by colons (:), may be given to specify a list of directories to be searched before any other directories are searched. These directory lists will be searched (in order) for source files and/or STB files, respectively. If a directory list starts with a colon, the current directory (.) is assumed to be first (a trailing colon is ignored). The -path option followed by a directory list will be used in place of the -srcpath option and/or the -stbpath option if one or both is not given.

If the source and/or STB files are not yet found after searching any directories specified when invoking CodeWatch, the debugger will search directories specified by environment variables in a similar manner. The environment variables CODEWATCH_SRCPATH and/or CODEWATCH_STBPATH may be set to a list of directory names, separated by colons. These directory lists will be searched (in order) for source files and/or STB files, respectively. The environment variable CODEWATCH_PATH followed by a directory list will be used in place of the CODEWATCH_SRCPATH environment variables and/or the CODEWATCH_STBPATH environment variables if one or both is not given.

For example, the following command:

cw_java -srcpath :/pl1progs/src:/src/pl1progs\ -stbpath /pl1progs/stb:/pl1progs/obj program-name

will cause the debugger to search for the source files in the following directories in order:

  1. /pl1progs/src
  2. /src/pl1progs
  3. The directory specified at compilation (if other than the current directory)
  4. The current directory (.)

The debugger will search for the STB files in the following directories in order:

  1. /pl1 progs/stb and /pl1 progs/obj
  2. The current directory (.)
  3. The directory specified at compilation (if other than the current directory)
Parent topic: Invoking CodeWatch


Redirecting User Program I/O

When a user program is run under CodeWatch, there are three ways to specify that input and/or output be directed to/from another file.

  • The command options -usrin and -usrout. Each of these takes a filename operand.
  • The ">" (output) and the "<" (input) parameters for the RELOAD command. See Reload for more information. Both of these parameters also take a filename operand.
  • The Stdin and Stdout edit fields in the Reload dialog.

When either the input or output is redirected, CodeWatch attempts to open the specified file(s) in the appropriate mode. If the open fails, CodeWatch prints an error message and exits.

Note:

When the program normally continues to completion (for example, by using the Continue or Step command) and is automatically reloaded by CodeWatch, output redirection is preserved in append mode, while using an explicit Reload resets output redirection to the terminal.

Parent topic: Invoking CodeWatch


Extended ASCII Character Support

Normally, the debugger considers a range of ASCII characters to be unprintable. When the debugger evaluates a given data item, a dot "." is printed instead of each character within that range. The "unprintable" ASCII range is usually any character whose ASCII value is less than 32, within the range of 127 to 159 inclusive, or greater than 254. When using the -8bit command-line option, the debugger will not assume that the ASCII characters within the range of 127 to 159 inclusive are unprintable. As a result, printable characters within the extended ASCII character set, which are supported by some terminals, are allowed to be printed. This is especially useful for terminals that support languages other than English.

Parent topic: Invoking CodeWatch


Start-up Files

Upon invocation of the debugger, a command file containing debugger commands is automatically executed, if present. The debugger searches for this file in the following locations in the given order:

  1. In the file specified by the environment variable CODEWATCH_INIT.
  2. In the file .codewatch in the user's current directory.
  3. In the file .codewatch in the user's home directory.

As soon as one of these files is found, the debugger commands contained within it are executed, after which normal interactive debugging may continue. It is not required that a start-up file exist.

Parent topic: Invoking CodeWatch


Debugging a Program with Multiple Modules

Not all source modules need to be compiled in debug mode to use CodeWatch. You may compile in debug mode only those modules you want to debug.

If you debug a program with multiple modules and the main program is compiled in debug mode, the initial environment will always be the main program module.

If the main program is not compiled in debug mode, the initial environment will be the first debug module specified in the link step.

The COBOL program amort.cob is an example of a program with multiple modules. To debug just the subprogram MPCALC, only mpcalc.cob needs to be compiled in debug mode. To do this, use the following command sequence:

$ lpicobol amort.cob
$ lpicobol mpcalc.cob -deb
$ ldcobol amort.o mpcalc.o -o amort
$ cwcmd amort
Note:

The dollar character ($) in this command sequence is the system prompt.

The debugger is then invoked and MPCALC is the initial evaluation environment.

Parent topic: Getting Started


Ending a Debugging Session

To end a debugging session, enter the QUIT command at the command-line prompt or select Exit from the File menu in the Windows interface.

Using either method causes normal termination of the debugger and the termination of your program. Once the debugging session has been terminated, the system prompt will be displayed.

Keyboard interrupts while the debugger is accepting commands are ignored, but a keyboard quit (for example, <Ctrl \>) will terminate the debugging session.

Programs that terminate normally while running under the control of the Codewatch GUI will complete the debug session and close the debugger.

Programs that terminate normally while running under the control of the command-line CodeWatch will automatically be re-initialized with any explicitly set breakpoints, watchpoints, and tracepoints (and any associated action-lists) preserved, so that execution may start from the beginning if desired. However, breakpoints that may have been set in shared libraries will not reset if the library is not loaded at program setup. The exit status with which the program exited is given. Refer to your UNIX documentation (exit (2)) for more information.

Parent topic: Getting Started


The Command-line Interface

  • Special Symbols
  • CodeWatch Commands and Options
  • Entering CodeWatch Commands
Parent topic: CodeWatch User's Guide


Special Symbols

CodeWatch commands may include certain symbols that have special meaning. The table below lists these symbols and their meanings.

Symbol
 | Definition
+ | Unary plus sign, and addition
- | Unary minus sign, and subtraction
= | Right-hand side qualifier for Let
; | Command separator
[ ] | Action-list delimiters
' or " | String delimiters (' or " depending on source language)
/ | Command option indicator
\ | Statement reference qualifier
% | Command line continuator, statement label indicator, procedure entry point, and exit point indicator
: | Activation number indicator
{ } | Logical expression delimiters
Parent topic: The Command-line Interface


CodeWatch Commands and Options

A debugger command is made up of one or two keywords. The debugger command line contains a debugger command and optional or required arguments, depending on the command.

In the general format for the command-line, optional items are enclosed in oversized, square brackets. Note that the regular-sized square brackets in the action-list argument are required delimiters.

The general command-line format is as follows:

command [ /option ] [ argument ] [[action-list]]

where:

command | Names the specific debugger action to be performed.
/option | Modifies the action of the command.
argument | Supplies required or optional information to the command.
[action-list] | Lists one or more debugger commands.

Two examples of debugger commands using special symbols follow:

BREAKPOINT 90 [EVALUATE var1; E var2]

This example sets a breakpoint at line 90. The program variables var1 and var2 will be evaluated when this breakpoint is encountered.

BREAKPOINT LABEL1 + 8; LBREAKPOINT /ALL

This example sets a breakpoint eight statements past the label LABEL1 and then lists all breakpoints.

  • Command Variations
Parent topic: The Command-line Interface


Command Variations

Many of the debugger commands allow a number of prefixes, which specify a variation of the command function. The table below contains an explanation of these prefixes.

Prefix
 | Description | Example | Description
Lcommand | Lists information on command. | LMACRO | Lists information on the current macro definition.
Dcommand | Sets the default values for command. | DSTEP | Sets the default values for the Step command.
Ncommand | Removes the instance of command. | NBREAKPOINT | Removes the breakpoints.
Parent topic: CodeWatch Commands and Options


Entering CodeWatch Commands

Commands may be entered in either upper case or lower case. The debugger is not case-sensitive except when processing quoted literals. Commands will be shown in upper case in all command-line examples.

Enter the commands at the keyboard in response to the command-line prompt (CodeWatch>). For example, the PRINT command displays the current line from the source program:

CodeWatch> PRINT

Several commands can be entered on a single line, separated by semicolons, as shown in the following example:

CodeWatch> BREAKPOINT 25; EVALUATE DISTANCE

Using abbreviations, the previous command line can also be written as:

CodeWatch> B 25; E DISTANCE

Commands are executed one at a time, from left to right. If any command causes an error message to be displayed, the rest of the command line may be discarded. If any command causes the program to resume execution, the rest of the command line will be executed when the debugger resumes control. For example, the following series of commands will be executed only until CONTINUE is reached. EVAL COUNT is not executed until a breakpoint or other condition returns control to the debugger.

CodeWatch> B 93; FIND COUNT; CONTINUE; EVAL COUNT

If a command line is too long for a single line, it can be continued on the next line by entering a space and a percent character (%) as the last character on the line, followed by a carriage return. The percent character is not part of the command. It simply informs the debugger that you want to continue entering commands. The debugger prompts with ". . . >" indicating it is ready for the continuation of command input. For example:

CodeWatch> BREAKPOINT 123 [ STEP IN; FIND EXPENSES; %
...> EVALUATE EXPENSES; CONTINUE ]
Parent topic: The Command-line Interface


Debugging Concepts

  • Using Action Lists
  • Pointer Concepts
  • Environment Concepts
  • CodeWatch Error Messages
  • Aborted Program Recovery
Parent topic: CodeWatch User's Guide


Using Action Lists

An action list is a set of one or more CodeWatch commands specified for execution at breakpoints, after steps, at watchpoints, at tracepoints, or as macro definitions. The command-line syntax requires action lists to be surrounded by square brackets ( [ ] ). The commands must be separated by semicolons. You may use spaces after semicolons to aid readability. The commands that you enter in an action list are not checked for correctness until they are executed. The command-line syntax for the action list is as follows:

[ command1; command2; ...; commandn ]

A typical action list that could be set at a breakpoint is as follows:

EVALUATE COUNTER; STEP; E DISTANCE; CONTINUE

In more advanced debugging, commonly used sequences of commands can be defined as an action list with the Macro facility. The single macro name can then be used repeatedly throughout the debugging session to refer to a complex series of actions.

Parent topic: Debugging Concepts
Related information
Macro


Pointer Concepts

The debugger maintains two conceptual pointers: the execution pointer and the source file pointer. This section explains these pointers and how they are used during a debugging session.

  • The Execution Pointer
  • The Source File Pointer
Parent topic: Debugging Concepts


The Execution Pointer

The debugger maintains a pointer to the current execution point. This is the point at which execution resumes or begins following a Step or Continue. The execution pointer is reset during execution of the program. The Reload command sets the execution pointer to the start of the program. Only a Goto or Return can directly reset the execution pointer. The WHERE command will display the current execution point. In the Windows interface, the highlighted line in the Source window indicates the current execution point.

Parent topic: Pointer Concepts


The Source File Pointer

The debugger also maintains a pointer to the line in the source file currently being displayed. The CodeWatch Source command changes the current source file being displayed. The POINT and PRINT commands change and display the source file pointer, respectively. The Environment command without any operands resets the source file pointer to the current execution point.

Parent topic: Pointer Concepts


Environment Concepts

The environment is a frame of reference for the debugger to identify program entities such as certain instances of statements and variables. This section explains these entities and how to refer to them in the context of a debugging session.

  • Program Blocks
  • Block Activation Numbers
  • Statement Identifiers
  • Referencing Included or Copied Files
Parent topic: Debugging Concepts


Program Blocks

Program blocks are units of code that provide scope and context for the debugger. Program blocks are defined according to the source language. Refer to the appropriate language chapter for language-specific definitions of program blocks.

Parent topic: Environment Concepts


Block Activation Numbers

Activation numbers pertain to only recursive procedures and to languages that allow recursive procedures.

A procedure is active when it has been called during program execution. Each new call to a procedure counts as a new activation. The activation number specifies a unique activation of a procedure when more than one activation exists. Multiple activations occur when a procedure is recursive (A calls A) or indirectly recursive (A calls B calls A). Activation numbers are either absolute or relative.

  • Absolute Activation Numbers
  • Relative Activation Numbers
  • Using Activation Numbers
Parent topic: Environment Concepts


Absolute Activation Numbers

An absolute activation number is simply a positive integer. Number 1 denotes the first activation of a procedure, number 2 the second, and so forth. To refer to an activation of a procedure using absolute activation numbers, the procedure name is followed by a colon (:) and the positive integer that denotes the activation.

Parent topic: Block Activation Numbers


Relative Activation Numbers

A relative activation number is either zero or a negative integer. A relative activation number specifies the number of activations to count backwards from the most recent activation. The number 0 denotes the most recent activation. The activation directly preceding the most recent activation is denoted by -1. For example, if there have been five activations of the procedure FACTORIAL, FACTORIAL:0 refers to the fifth activation and FACTORIAL:-2 refers to the third activation. This activation can also be referred to as FACTORIAL:3 (that is, using the absolute activation number 3).

Parent topic: Block Activation Numbers


Using Activation Numbers

Each activation of a procedure has its own distinct values for automatic (or local) data, and each activation may have different actual parameters or arguments. An activation number can be used to specify the environment for evaluating or displaying variables and procedure arguments. An activation number can also be used when setting a breakpoint in a particular activation of a procedure.

If the activation number is omitted from the name, the debugger uses a default of 0, the most recent activation. The only exception to this is Breakpoint, where omitting the activation number means that a breakpoint is to be taken on every activation of the procedure.

Parent topic: Block Activation Numbers


Statement Identifiers

Commands such as Breakpoint require identification of statements within the program being debugged. Statement identifiers are either source line numbers or statement labels.

  • Line Numbers
  • Labels
  • Line Number and Statement Offsets
  • Entry and Exit Points
  • Statement Qualification by Environment
Parent topic: Environment Concepts


Line Numbers

The simplest way to refer to a statement is by using its source line number, that is, the physical line number in the source file on which the statement starts.

If an unqualified source file line number is specified (no environment reference), the first executable statement on the specified line, if present, or the first executable line following that line is used by the debugger.

If a source file line number is qualified by an environment reference, for example, "SIFT\18", the translation of the line number to an executable statement is executed in the same manner as described for unqualified line numbers, except that the set of executable statements that the line number can be translated to is restricted to those contained in the specified environment block.

Parent topic: Statement Identifiers


Labels

The way to refer to a labeled statement is to use its statement label. For any language in which statement labels are numbers, such as Pascal or FORTRAN, a percent character (%) must be used in front of the statement label. For example, in the following Pascal code

325:
326: 9999: writeln('ERROR: INVALID DATA.');
327: end. {Program Terminates}

the statement references 326 and %9999 both refer to the writeln statement.

In the following PL/I code:

 9:  DUMMY
10:  %INCLUDE 'MYFILE.PL1';/*PL/I sample */
11:  CHKPAGE:
12:  if I = 66 then
13:        do; put skip; I = 0; goto DONEIT;
14:  end;
15:  I = I + 1; DONEIT: J = 0; K = 0;
16:  L = 0;

the CodeWatch commands B 11 and B CHKPAGE are equivalent, and both refer to statement number 11.

Parent topic: Statement Identifiers


Line Number and Statement Offsets

A line number offset can be used to locate a statement when it is not labeled or its source line number is unknown. A line number offset is formed by placing a plus character (+) followed by a positive integer after a source line number or a statement label. For example, line 15 in the example below can be referred to by the program as 11 + 4 or as CHKPAGE + 4. Of course, 15 + 0 refers to the same line.

 9:  DUMMY
10:  %INCLUDE 'MYFILE.PL1';/*PL/I sample */
11:  CHKPAGE:
12:  if I = 66 then
13:        do; put skip; I = 0; goto DONEIT;
14:  end;
15:  I = I + 1; DONEIT: J = 0; K = 0;
16:  L = 0;

A statement offset must be used to refer to an unlabeled statement that is not the first statement on a line. A statement offset is formed by placing a period followed by a positive integer (indicating the number of statements from the beginning of the line) after the line number offset. (If the line number offset equals zero, a plus character must be used.) For example, the K = 0 statement on line 15 of the example above can be referred to by the debugger as 15 + 0.2 or CHKPAGE + 4.2.

Parent topic: Statement Identifiers


Entry and Exit Points

Every procedure has two special statements: the entry point to and the exit point from the procedure. The entry point is the place during execution at which the procedure has been called, but before other prelude code has run. A procedure's entry point is referred to within CodeWatch by specifying the procedure name followed by a backslash (\) and %ENTRY (or simply %E), for example,

READ_INPUT\%ENTRY.

The entry point to the current activation of a procedure may simply be referred to as %ENTRY (or %E).

The exit point is the place after which the return value (if any) has been computed and the return statement has been executed. All local variables are still defined. An exit point is referred to by the procedure name followed by a backslash and %EXIT (or %Ex), for example,

READ_INPUT\%EXIT.

The exit point to the current activation of a procedure may be referred to by %EXIT (or %Ex).

Entry and exit points may not be referred to in conjunction with statement offsets.

Parent topic: Statement Identifiers


Statement Qualification by Environment

A statement reference may need to be qualified by a reference to the environment in which the statement occurs. This is done by putting the block name of the environment (with an optional activation number) and a backslash in front of the statement reference. For example:

PRINT_OUT\10

Using just the backslash without the block name refers to the environment containing the current execution point.

Parent topic: Statement Identifiers


Referencing Included or Copied Files

Many source programs have the contents of separate files inserted into the program at compilation. Programs written in PL/I use %INCLUDE, ++INCLUDE, -INC and/or EXEC SQL INCLUDE.

When the debugger encounters one of these statements in a program, you can display the contents of the included file by using Source followed by the filename cited in the INCLUDE directive. The lines in the file will be numbered consecutively from the first line in the file. To return to displaying lines from the source file containing the current environment, simply use the Source command with no arguments.

Support for include file handling has been added for Open PL/I. This applies to include files that contain executable code. The current set of functionality is implemented as follows:

  • Stepping "into" an include file, for example, when the next statement is a %INCLUDE directive, will cause the screen display to switch to the specified include file. Commands that deal with the source file, for example, PRINT, POINT, and so on, work as expected using the current include file.
  • Stepping "through" an include file is allowed.
  • Setting breakpoints within an include is not allowed. The setting of a breakpoint unambiguously refers to the original containing source file.
  • Stepping "over" an include file, for example, when the next statement is a %INCLUDE directive, is not explicitly allowed. This may be accomplished by setting a breakpoint in the containing source file, followed by the CONTINUE command.
  • Stepping "out of" an include file before its last statement is accomplished similarly to stepping "over," that is, by setting a breakpoint in the containing source file followed by the CONTINUE command.

Using the macro preprocessor mfpp with CodeWatch is also allowed. CodeWatch will use the original source file (rather than the expanded preprocessed output of mfpp). Stepping "through" macros works similarly to the include file support described above.

Parent topic: Environment Concepts
Related information
Examining the Source Program


CodeWatch Error Messages

When CodeWatch encounters an error condition, a message is displayed at your terminal. The following sections describe common CodeWatch error messages.

  • Start-up Warnings
  • Start-up Errors
  • Syntax Errors
  • Semantic Errors
Parent topic: Debugging Concepts
Related information
PL/I


Start-up Warnings

When the debugger session begins, the debugger may issue several different kinds of warnings.

A warning may be issued if the source file is newer than the program and/or STB file. Out-of-date files may be present for any of the following reasons:

  • The program has been edited but not re-compiled.
  • The program has been re-compiled but not re-linked.
  • The wrong SRCPATH is being used.
  • The wrong STBPATH is being used.

The following is an example of this type of warning message.

**Warning** Source file newer than program and .stb files for main.

A warning may be issued if an STB file for a module compiled in debug mode is not found. This would be an error if the debugger could not find any STB files; however, the debugger will issue a warning only if one or more (but less than all) STB files are missing.

The following is an example of this type of warning message.

**Warning** No debug data for environment
         ** Source file "y.pl1"
         ** Symbol table file "y.stb"
Parent topic: CodeWatch Error Messages


Start-up Errors

When the debugging session cannot begin, the debugger will display an error message at invocation. This indicates that a filename required by CodeWatch is an error because one or more of the following is true:

  • It does not exist or is not in the current directory.
  • The program file specified to be debugged is not an executable file.
  • None of the program modules in the program file was generated from a compilation using the -deb option.
  • The necessary debugger information files cannot be found in any of the specified or default directories.
Parent topic: CodeWatch Error Messages
Related information
In Search of Source and STB Files


Syntax Errors

The debugger issues a message when the command syntax is incorrect. The error message contains at least three lines of text: the first lines describe the error, the second to last line echoes the command line as it was entered, and the last line contains a caret ( ^ ), indicating the approximate location of the error in the command line above. After displaying an error message, the debugger issues a prompt and waits for another command. The following are examples of the message feature:

CodeWatch> TYPEPRIMES
**Error** Invalid Command
TYPEPRIMES
^
CodeWatch> TRACE EMTRY
**Error** Syntax error
TRACE EMTRY
      ^
Parent topic: CodeWatch Error Messages


Semantic Errors

Semantic errors occur when the debugger cannot correctly interpret a command line because of an incorrect variable name, an invalid argument, or some similar problem. With some semantic errors, the command line is echoed and a caret ( ^ ) is placed under it indicating the approximate location of the error. Two samples are shown from the command-line interface, as follows:

CodeWatch> EVALUATE ths_prime
**Error** Undefined variable or built-in function
EVALUATE ths_prime
                  ^
CodeWatch> BREAKPOINT 100000
**Error**   Statement 100000 not found in procedure
Parent topic: CodeWatch Error Messages


Aborted Program Recovery

CodeWatch has the ability to recover from and to reasonably debug user programs that have stopped because of certain operating system errors. When this occurs, the following are indicated by the debugger:

  • The error that caused the program to stop.
  • The current user program counter (the machine address of the execution point).
  • The name of the routine in which the error occurred.

If the routine in which the program stopped was compiled in debug mode, the source file line number of the execution point at the time of the error will also be given. The current evaluation environment will automatically be set to this environment and the debugging session may continue.

If the routine in which the program stopped was not compiled in debug mode, the environment of the most recently called routine that was compiled in debug mode is indicated, and the current evaluation environment is set to that environment. In this case, most debugger actions are allowed, including continuing execution from the point at which the program received the error. Note that it is not legal to use the Step or Goto commands from a non-debug routine.

Whether or not program execution stops because of a signal depends on the CodeWatch default catch settings for the signal. In most cases, you can modify the behavior by using the CATCH command.

The STACK command can provide a stack traceback to indicate the sequence of subroutine calls up to the time of the error.

Parent topic: Debugging Concepts
Related information
Catch


CodeWatch Functionality

  • Program Control
  • Environment Control
  • Symbolic Access
  • Examining the Source Program
  • Other Features
Parent topic: CodeWatch User's Guide


Program Control

This section explains the CodeWatch facilities that are used to control program execution. You may control the execution of your program in the following ways:

  • Setting breakpoints to suspend program execution at any executable statement.
  • Catching signals to return process control to the debugger.
  • Stepping through one or more executable statements at a time.
  • Setting watchpoints to monitor changes in specified variables.
  • Tracing statements and entries, allowing you to monitor every executable statement and the entry and exit points of a program.
  • Breakpoints
  • Catching Signals
  • Statement Stepping
  • Tracepoints
  • Watchpoints
  • Controlling Program Execution
  • Checking Program State with ON-unit Notification
    Describes how notifications can be sent when a condition that triggers an ON-unit is detected.
Parent topic: CodeWatch Functionality


Breakpoints

Breakpoints are used to suspend program execution at specified locations so that you may execute various debugging actions, such as evaluating variables, single statement stepping, and so on. The Breakpoint facility is used to set a breakpoint at a specified statement or to modify the characteristics of a breakpoint already set at that statement. Up to 64 breakpoints can be active at any one time. Breakpoints may be conditional and may have associated action lists (sequences of debugger commands to be executed when the breakpoint is incurred).

There are three pertinent commands to the Breakpoint facility: BREAKPOINT, NBREAKPOINT, and LBREAKPOINT:

  • The BREAKPOINT command is used for adding new breakpoints and modifying existing breakpoints.
  • The NBREAKPOINT command removes either a specified breakpoint or all breakpoints.
  • The LBREAKPOINT command lists information about breakpoints.
Parent topic: Program Control


Catching Signals

You may specify whether or not process control should return to the debugger when a specified signal is generated. This is done with the Catch facility. You may also specify whether or not the user program is to continue as if it had or had not incurred the given signal. This is done with the Ignore option.

There are three pertinent commands to the Catch facility: CATCH, NCATCH, and LCATCH:

  • The CATCH command specifies that a signal should be caught and allows you to specify whether or not the signal is to be ignored by the user program.
  • The NCATCH command specifies that the signal should not be caught.
  • The LCATCH command lists Catch settings for a specified signal or all signals.
Parent topic: Program Control


Statement Stepping

Program execution may be single stepped one or more source-level statements at a time. It is possible to set default stepping modes:

  • You may specify that a Step should, by default, step into or over a call to a subroutine.
  • You may specify a default Step action list to be executed every time the debugger executes a Step.
  • You may also specify that a Step to a user-defined breakpoint should either execute the default Step action list, the breakpoint action list, or both.

There are three pertinent commands to the Step facility: STEP, DSTEP, and LSTEP.

  • The STEP command starts program execution at the current location of the execution pointer and stops execution after one or a specified number of statements.
  • The DSTEP command allows you to modify the default stepping modes and action list.
  • The LSTEP command lists the current stepping modes and action lists.
Parent topic: Program Control


Tracepoints

Tracing enables information about all block entries and statements to be announced as the program executes. Entry tracing allows an action list to be associated and may be conditional.

There are three pertinent commands to the Trace facility: TRACE, LTRACE, and NTRACE.

  • The TRACE command enables statement or entry tracing.
  • The LTRACE command lists the current tracing mode.
  • The NTRACE command turns off statement or entry tracing.
Parent topic: Program Control


Watchpoints

Watchpoints are used to monitor specified variables. The Watchpoint facility is used to designate a given variable to be watched. When the contents of the watched variable change, program execution stops and control is returned to the debugger. Watchpoints may be conditional and may have associated action lists (sequences of debugger commands to be executed when the watchpoint is incurred).

There are three pertinent commands to the Watch facility: WATCH, NWATCH, and LWATCH.

  • The WATCH command is used for adding new watchpoints and modifying existing watchpoints.
  • The NWATCH command removes either a specified watchpoint or all watchpoints.
  • The LWATCH command lists information about watchpoints.
Parent topic: Program Control


Controlling Program Execution

During a debugging session, CodeWatch maintains an execution pointer, which tracks the current point of program execution. When execution of the program has been halted by a debugger action, the pointer maintains the location as the current execution point. The current execution point can always be determined using the WHERE command. This allows you to control the execution of the program by using one of several simple debugger facilities.

The CONTINUE command is used to begin program execution or to resume execution following a breakpoint or a step operation.

The GOTO command moves the execution pointer to a specified statement. Program execution resumes at this point when a Continue or Step is issued. The statement is specified by a line number, a simple statement label, or a statement label followed by a line number offset or statement offset. The named statement must exist in the current program block. Once the debugger has executed the Goto, it displays the new execution point.

The RELOAD command restarts the user program, preserving any explicitly set breakpoints, tracepoints, and watchpoints with associated action lists. A subsequent Continue or Step will start program execution from the beginning of the program.

The RETURN command transfers the current execution point to the exit point of the current procedure. If the procedure returns a value, an expression must be given indicating the value to be returned. For more information, see the section Modifying Return Values.

The QUIT command causes termination of the debugging session. Selecting the Exit item in the File menu is equivalent to issuing the QUIT command.

CodeWatch does not require a program-to-debug at startup time. If no program-to-debug is supplied to Code Watch, CodeWatch comes up standalone. However, on UNIX systems, it will first look for a.out as the default program name. When CodeWatch comes up standalone, a LOAD or ATTACH command must be used to specify the program to be debugged.

The LOAD command loads the symbol table from a specified file into CodeWatch as the primary executable for debugging. It also purges the internal CodeWatch symbol table of any previously loaded executables or shared libraries.

The ATTACH command attaches CodeWatch to the "pid" (a decimal number) and performs a LOAD command, as described above. Attached programs that call exit () or that die are not automatically reloaded. Use the RELOAD command for this.

Programs may also be attached at the time of invocation, for example,

cwcmd -pid 3268 myprog.out
Parent topic: Program Control
Related information
Modifying Return Values


Checking Program State with ON-unit Notification

You can use the CodeWatch debugger to verify various states in a PL/I program. The debugger can stop program execution and send a notice when it detects a condition that may trigger an ON-unit. This lets you to investigate the program's state prior to the execution of the ON-unit. You can then set up breakpoints as needed before continuing program execution. Sending notifications using ON-unit detection can be done using either GUI or Command-Line CodeWatch.

You can activate or deactivate for all supported ON-units.

  • Supported ON-units
    Lists the ON-units that can be used with notification with the CodeWatch debugger.
  • Activating CodeWatch ON-unit Triggering Notification
    Describes how to set environment variables to activate ON-unit notification for debugging.
  • Setting Notifications for ON-units
    Instructs on setting CodeWatch to notify whenever the debugger detects a condition that triggers an ON-unit.
Parent topic: Program Control


Supported ON-units

These are the ON-units that can be used with ON-unit condition notification in CodeWatch. See the Open PL/I Language Reference Manual for details about each supported ON-unit.

ANYCONDITION | KEY
AREA | OVERFLOW
ATTENTION | RECORD
CONDITION | SIZE
CONVERSION | UNDEFINEDFILE
ENDFILE | UNDERFLOW
ENDPAGE | USERCONDITION
ERROR | USERCONDITION(ss$_UNWIND)
FINISH | VAXCONDITION
FIXEDOVERFLOW | ZERODIVIDER
Parent topic: Checking Program State with ON-unit Notification


Activating CodeWatch ON-unit Triggering Notification

To use the CodeWatch ON-unit triggering notification feature, set the following environment variable in the configuration for the enterprise server you are using for debugging with CodeWatch.

MFPLI_CONFIG_DIR=<directory> : The read/write location where to create the CWNOTIF.DAT file that allows CodeWatch and the PL/I run time to communicate. This is typically the root directory of the current enterprise server instance that you are using.
Note: This variable is set automatically using the value in the PL/I Configuration Directory field on the General tab of the Enterprise Server Administrator (MSS > PL/I > General). You can use either that value or the root directory of the current enterprise server instance.
Parent topic: Checking Program State with ON-unit Notification


Setting Notifications for ON-units

You can set notifications for ON-units in CodeWatch, either from the command line or from GUI CodeWatch.

Using Command-line CodeWatch

  • Use the CATCH command to turn notification on for a specified ON-unit.
  • Use the NCATCH command to turn notification off for a specified ON-unit.
  • Use the LCATCH command to list the catch status of a specified ON-unit/signal, or the state of all signals and ON-units.

See the help topics for the CATCH, NCATCH, and LCATCH commands for details and examples of using these commands.

Using GUI CodeWatch

While debugging your PL/I program in GUI CodeWatch, do the following to set notification for specific ON-units:

  1. Choose Actions > Catch Exceptions > On Units. The Configure On Unit Exceptions dialog box appears with the supported ON-units.
  2. Select the check box of the supported ON-units for which you want to turn on notification, and clear the check box of the supported ON-units for which you want to turn off notification.
  3. Click OK.
Parent topic: Checking Program State with ON-unit Notification
Related reference
Catch
Lcatch
Ncatch


Environment Control

In many cases during a debugging session, it is necessary to refer to an environment to establish a frame of reference for identifying variables or statement identifiers. An environment is simply a program block, which the program refers to by specifying the name of the block or any statement within the block. This allows the debugger to find a specific instance of a variable or statement. Usually, a simple block name is adequate to specify an environment. It refers to the most recent activation of that block. To establish some other activation of the block as an environment, use a block activation number.

An active environment exists on the program stack as a stack frame containing automatic data for the environment. However, environments that do not exist on the program stack can also be referenced; such environments are called inactive environments. For example, a procedure that has not been called, and thus has no stack frame, is inactive. Another example of an inactive environment is one that is referenced by a block name followed by an activation number that is higher than the current activation of the block. It is possible to examine static and external data in inactive environments and to set breakpoints in them. An active environment must be specified to examine automatic data or procedure arguments.

  • Changing Environments
  • Stack Traceback
Parent topic: CodeWatch Functionality


Changing Environments

The Environment facility sets the current evaluation environment to provide scope to the debugger for identifying variables and statements. The environment specified can be a simple block name or a block name followed by an activation number or a statement identifier. An activation number is used to establish as an environment or an activation of a block other than the most recent one. A statement identifier is merely a convenient means of identifying the block that immediately contains the statement. If the environment argument is not specified, the evaluation environment is set to the environment containing the current execution point.

Whenever the debugger continues after program execution pauses (for example for a breakpoint or single step) the evaluation environment is reset to the environment containing the current execution point.

There are two pertinent commands to the Environment facility: ENVIRONMENT and LENVIRONMENT. The ENVIRONMENT command is used to change environments. The LENVIRONMENT command is used for listing information about environments.

Parent topic: Environment Control


Stack Traceback

The STACK command is used to print a traceback of a specified number of stack frames.

Parent topic: Environment Control


Symbolic Access

This section describes the various methods and facilities to access, modify, and display symbolic information.

  • Variable Names
  • Expression Evaluation
  • Variable Assignment
  • Listing Arguments
  • Modifying Return Values
  • Accessing Declaration Types
Parent topic: CodeWatch Functionality


Variable Names

The rules for identifying variables in the debugger are almost the same as the rules defined for the evaluation language. The same naming conventions are used, and all type and scope rules apply. One exception is that an environment name followed by a backslash (\) may be used to reference a variable in another program block. The names of variables are case-sensitive or case-insensitive, depending on the language of the module in which they are contained.

  • Referencing Elements of Arrays
Parent topic: Symbolic Access


Referencing Elements of Arrays

Elements of arrays are referenced using the constructs of the source language. CodeWatch allows access to array slices in programs written in Open PL/I.

For example, to evaluate the 15th array element in the example below in CodeWatch:

 DCL A(23) FIXED BIN(31);

enter:

ev A(15)
Parent topic: Variable Names


Expression Evaluation

The Evaluate command is used to evaluate and print the resultant value of expressions in the source language program. When the expression is evaluated, appropriate conversions are performed. Various display mode options (binary, decimal, octal, hexadecimal, and so on) are available.

Parent topic: Symbolic Access


Variable Assignment

The resultant value of an expression may be assigned to a named variable in the user program. When the expression is evaluated, appropriate type conversions are performed according to the rules of the source language. The resultant value is assigned to the named variable. If the type conversion is illegal, the debugger will issue an error message.

The LET command is used for variable assignment.

Parent topic: Symbolic Access


Listing Arguments

The Arguments command prints the arguments for an environment. The environment specified must be the name of an active procedure. If an environment argument is omitted, the debugger defaults to the current evaluation environment.

The ARGUMENTS command lists the arguments for the given (or default) environment.

Parent topic: Symbolic Access
Related information
Environment Control


Modifying Return Values

The Return facility allows you to set the return value of a procedure. Execution control is transferred to the exit point of the current procedure, and if an expression is specified, it is used as the return value for that procedure.

There are two pertinent commands to the Return facility: RETURN and LRETURN. The RETURN command transfers control to the exit point of the current procedure and allows you to set the return value. The LRETURN command lists the return value for the current procedure.

Parent topic: Symbolic Access


Accessing Declaration Types

The TYPE command prints the resultant data type of an expression in terms of the data descriptions of the current source language.

The TYPE command is used to access declaration types.

Parent topic: Symbolic Access


Examining the Source Program

This section describes the CodeWatch facilities for searching, printing, and displaying different locations in the source file(s).

  • String Search
  • Changing Source Files
  • The WHERE Command
  • The POINT Command
  • The PRINT Command
Parent topic: CodeWatch Functionality


String Search

The FIND command locates a line in the source file containing a specified text string.

Parent topic: Examining the Source Program


Changing Source Files

The Source facility allows you to change the source file being displayed or to list information about the source files in the executable being debugged.

There are two pertinent commands to the Source facility: SOURCE and LSOURCE. The SOURCE command allows you to change the source file to be displayed. The LSOURCE command lists information about source files in the user program.

Parent topic: Examining the Source Program


The WHERE Command

The WHERE command reports either a specified location or the current point of execution. The specified location may be a name of a routine, a line number, or a statement label.

Parent topic: Examining the Source Program


The POINT Command

The POINT command locates a line number within the debug source file and reports that line. If no line number is specified, the line corresponding to the current source file pointer is printed. The source file pointer is the pointer to the current line in the current source file.

In the graphical interface, double clicking on a line is equivalent to using the POINT command.

Parent topic: Examining the Source Program


The PRINT Command

The PRINT command prints a specified number of source lines from the current debug source file or prints the current source line.

Parent topic: Examining the Source Program


Other Features

This section describes additional features of CodeWatch.

  • Command Macros
  • Debugger Command Files
  • EBCDIC Support in CodeWatch
  • On-line Help
Parent topic: CodeWatch Functionality


Command Macros

The Macro facility is used to define a macro as shorthand for a series of debugger commands that may be reused during the debugging session. Sixty-four macros may be defined at any one time. The series of debugger commands is specified as an action list. Once a macro has been defined, its name may be used just like any other debugger command name. The macro in the command line is replaced by the debugger commands specified in the action list. Those commands are executed normally.

Note:

Do not choose a macro name that is the same as a debugger command name because the macro name will override the debugger command for that debugging session.

If the last (or only) command in the series of debugger commands does not end with a semicolon, any additional arguments that appear on the command line after the macro name are supplied as arguments to the last command in the macro definition.

There are three pertinent commands to the Macro facility: MACRO, LMACRO, and NMACRO. The MACRO command creates new macros. The LMACRO command lists macros. The NMACRO command deletes macros.

Parent topic: Other Features
Related information
Using Action Lists


Debugger Command Files

The SAVE command writes out commands to a specified disk file to reset all current breakpoint, watchpoint, and/or macro settings for use in a later debugging session. The file can be read in by using the Read command.

The READ command is used to execute debugger command files, displaying each command to the screen as the command is executed.

The LOG command can be used to create debugger command files by causing all subsequent debugger commands to be logged to a specified file.

Parent topic: Other Features


EBCDIC Support in CodeWatch

CodeWatch interprets character data as EBCDIC when the current debuggable module is compiled with the -ebcdic compiler option. Note that all character data which is input or displayed is always in human readable format (ASCII), and is converted to and from EBCDIC internally for that purpose.

For example, for a debuggable module compiler using the -ebcdic compiler option with a declaration dcl s char(4), using the debugger command Let s = 'abc '; the following table shows debugger commands and character results.

dcl s char(4)
Eval s | s = 'abc ' {character(4)} displays
Eval /h s | s = 81 82 82 40 (hex) {character (4)} displays
Eval trim(s) | 'abc' {character(3)} displays
Eval /h trim(s) | 81 82 83 (hex) {character (3)}
Eval 'abc'A | /.. {character (3)} displays. 0x616263 displays as readable characters. 0x61 is a slash (/. 0x61 and 0x62 are non-printable.
Eval /h 'abc'A | 61 62 63 (hex) {character (3)} displays
Parent topic: Other Features


On-line Help

Both the command-line interface and the graphical interface have a help facility. Click Help in the menu bar, or use the HELP command.

The HELP command with no parameters lists all of the available CodeWatch commands. If the HELP command is followed by command-name, help text for that command is displayed. If you need help for a specific command, you may specify the appropriate abbreviation for that command rather than the full command name.

Parent topic: Other Features
Related information
Help


CodeWatch Commands

  • Arguments
  • Attach
  • Breakpoint
  • Catch
  • Commandline
  • Continue
  • Detach
  • Dstep
  • Environment
  • Evaluate
  • Find
  • Goto
  • Help
  • Kill
  • Lbreakpoint
  • Lcatch
  • Lenvironment
  • Let
  • Lmacro
  • Load
  • Log
  • Lreturn
  • Lsource
  • Lstep
  • Ltrace
  • Lwatch
  • Macro
  • Nbreakpoint
  • Ncatch
  • Nload
  • Nlog
  • Nmacro
  • Nmap
  • Nshlib
  • Ntrace
  • Nwatch
  • Peek
  • Point
  • Poke
  • Print
  • Quit
  • Read
  • Registers
  • Reload
  • Return
  • Save
  • Shlib
  • Source
  • Stack
  • Step
  • Trace Entry
  • Trace Statement
  • Type
  • Watch
  • Where
  • !
Parent topic: CodeWatch User's Guide


Arguments

Use

Prints the arguments of a specified procedure environment.

Command Syntax

ARGUMENTS [environment]

where:

environment
Name of an active procedure

Description

The ARGUMENTS command prints the arguments to a named procedure environment. The procedure environment can be any program block.

If the environment name is omitted, the debugger defaults to the current evaluation environment.

Example

In this example, the arguments to the "sift" procedure are displayed.

CodeWatch> ARGUMENTS sift
N = 10 { fixed binary (31) }
Parent topic: CodeWatch Commands
Related information
Environment Control
Environment
Evaluate
Let
Stack


Attach

Use

Attaches CodeWatch to a "pid" and executes a LOAD command.

Command Syntax

ATTACH pid filename

where:

pid
A decimal process identification number.
filename
Name of a file to be loaded

Description

The ATTACH command attaches CodeWatch to the pid (a decimal number) and performs a LOAD command. Attached programs that call exit () or that die are not automatically reloaded. Use the RELOAD command for this.

Programs may also be attached at the time of invocation, for example, cwcmd -pid 3268 myprog.out

Example:

CodeWatch> ATTACH 3768 myprog.out
Parent topic: CodeWatch Commands
Related information
Detach
Kill
Load
Nload


Breakpoint

Use

Suspends program execution to allow for debugger actions.

Command Syntax

BREAKPOINT [statement-id]
           [[action-list]]
           [/IF {logical-expr} [/ELSE[action-list]]]
           [/SKIP=n]
           [/IGNORE  |  /NIGNORE [/ALL]]
           [/SILENT  | /NSILENT]

where:

statement-id
Identifies the statement at which the breakpoint will be set or modified
action-list
Specifies a set of one or more CodeWatch commands separated by semicolons.
logical-expr
Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables, returning a boolean value.

Description

The BREAKPOINT command is used to set a breakpoint at a specified statement or to modify the characteristics of a breakpoint already set at that statement. If the statement identifier is not specified, the breakpoint will be set at the current execution point; that is, the statement to be executed when program execution is resumed. The maximum number of breakpoints that can be active at one time is 64.

Breakpoints can be set at the entry point (%ENTRY) of external routines that have or have not been compiled in debug mode and at lines containing executable statements within routines that have been compiled in debug mode. Lines containing only comments or declarations, or only the keyword ELSE (else), are not valid breakpoint locations. If you try to set a breakpoint at one of these locations, the debugger will set the breakpoint at the first executable statement after the one named in the command.

Example

In the following example, a breakpoint is set at the entry point of the READ_INPUT procedure with an action list evaluating the value of MAXV.

CodeWatch> B READ_INPUT\%ENTRY [E MAXV]
CodeWatch> C
Break at PRIMES.READ_INPUT\%ENTRY
MAXV =                10 {fixed binary (31)}

In the following example, a conditional breakpoint is set on line 94. Program execution will stop if the variable COUNT is greater than 3; otherwise, the debugger will evaluate COUNT and continue.

CodeWatch> B SIFT\94 /IF {COUNT>3} /ELSE [E COUNT]
CodeWatch> CONTINUE
COUNT =              1 {fixed binary (31)}
COUNT =              2 {fixed binary (31)}
COUNT =              3 {fixed binary (31)}
Break at PRIMES.SIFT\94
  • Breaking at Specific Activations of a Block
  • Breakpoints with Action Lists
  • Skipping Multiple Iterations of a Breakpoint
  • Temporarily Ignoring Breakpoints
  • Suppressing the Breakpoint Message
  • Conditional Watchpoints
  • Incurring Breakpoints
Parent topic: CodeWatch Commands
Related information
Continue
Goto
Lbreakpoint
Nbreakpoint
Read
Save
Watch


Breaking at Specific Activations of a Block

If the statement identifier is qualified by a block name with an explicit activation number, the breakpoint applies only to that activation. If a block activation number is not specified, the breakpoint will be taken on every activation of the specified statement. The numbered activation may be higher than the most recent activation of the block. Relative activation numbers are converted to absolute activation numbers when the breakpoint is set.

Parent topic: Breakpoint
Related information
Block Activation Numbers


Breakpoints with Action Lists

If an action list is specified, it is set as the action to be performed when the breakpoint is taken. To remove an action list using command-line syntax, simply specify a null action-list, that is [ ]. To remove an action list using the Breakpoint dialog, simply delete the text in the Action List edit field. An action list of CONTINUE causes the breakpoint to act like a simple tracepoint; at each execution of the statement a message identifies the statement and execution continues.

Parent topic: Breakpoint


Skipping Multiple Iterations of a Breakpoint

A breakpoint counter is associated with each breakpoint. When the breakpoint is created, the counter is set to zero; each time the breakpoint is encountered the counter is incremented by one. All breakpoint counters are set to zero when the program is reloaded.

If a skip count is specified, a breakpoint skip counter is set to the value specified, causing the breakpoint to be skipped that number of times. Once the breakpoint skip counter is set, it remains in effect until its value decreases to zero.

Parent topic: Breakpoint


Temporarily Ignoring Breakpoints

If the Ignore option is specified, the breakpoint is flagged to be ignored and is not executed when it is encountered. The Ignore option is useful to temporarily disable a breakpoint. Turning off the Ignore flag sets the breakpoint in effect again. This is done by specifying the /NIGNORE option. It is possible to set all breakpoints to be ignored or not ignored. This is done by specifying the option /ALL in conjunction with /IGNORE or /NIGNORE.

Parent topic: Breakpoint


Suppressing the Breakpoint Message

When a breakpoint is encountered, CodeWatch normally prints a message specifying the line at which the breakpoint is set. This message can be suppressed by using the Silent option; this is especially useful if a debug-time "patch" is desired within your program. To create a patch, set a breakpoint at the beginning of the code that causes the program error. The breakpoint should include the Silent option and an action list that performs a work-around assignment ending with a GOTO command (to circumvent the program error) and a CONTINUE command. The debugger will then perform the specified action list at the breakpoint and continue execution without any interaction.

Parent topic: Breakpoint


Conditional Watchpoints

A conditional expression may be used to qualify the breakpoint; it must be the last option on the command line. When a breakpoint with the If option is set, the executing program will be suspended and the debugger will be activated whenever the breakpoint is encountered. The IF condition is then evaluated. The evaluation always takes place in the environment and language of the program statement. If the IF condition is false, program execution continues and the breakpoint is never reported. If the IF condition is true, the debugger incurs a breakpoint as usual.

Parent topic: Breakpoint


Incurring Breakpoints

When a breakpoint with a conditional expression is set at a particular program statement, the executing program will be suspended and the debugger will be activated whenever that program statement is about to be executed. The following will then occur:

  • The condition is evaluated; the evaluation always takes place in the environment and language of the program statement. If the condition is false and the Else action list has not been specified, program execution continues. If the condition is false and the Else action list has been specified, the Else action list is executed and program execution continues. If the condition is true, the debugger performs the following actions:
    • The breakpoint counter is incremented.
    • If the Ignore flag is on for this breakpoint, execution continues.
    • If the skip count for this breakpoint is non-zero, the count is decremented and execution continues. However, the skip count for an Ignored breakpoint is not affected.
    • The debugger reports an announcement of the breakpoint.
    • If an action list is specified, it is executed. The action list may specify that program execution is to continue.
Parent topic: Breakpoint


Catch

Use

Returns process control to the debugger when the given signal is generated. Also turns on notification for a specified ON-unit, or all default ON-units.

Command Syntax

CATCH {/DEFAULT | [/NIGNORE|/IGNORE] signal}

or

CATCH {ON-unit}{/DEFAULT}

where:

signal
Can be either a signal name mnemonic (such as SIGALRM, SIGINT, and so on) or the signal number corresponding to that mnemonic. Signal names may be specified in either uppercase or lowercase letters.
ON-unit
The name of an ON-unit at which you want notification whenever the debugger detects a condition that triggers the ON-unit.

Description

The occurrence of a signal that is set to be caught and ignored (/IGNORE) returns process control to the debugger. When the child process subsequently resumes (for example, by using Step or Continue), it continues as if it had not incurred the given signal.

The occurrence of a signal that is set to be caught and not ignored (/NIGNORE), returns process control to the debugger. When the child process subsequently resumes, it continues as if it had incurred the given signal. The occurrence of a signal that is not set to be caught does not return process control to the debugger.

By default, certain signals and on-units are caught by the debugger. The Default option resets all CATCH settings back to the debugger's default settings.

Use the LCATCH /ALL command to get a list of current signal and on-unit settings.

Note: The signals SIGILL and SIGTRAP are permanently set to be ignored by the debugger. These are special signals because they are used by the debugger for breakpoints. You cannot modify the settings for these two signals.

Example

In the following example, process control returns from the child process to the debugger when SIGALRM is generated.

CodeWatch> CATCH /IGNORE SIGALRM
Changing SIGALRM to be caught and ignored.

When the child process resumes, it ignores the SIGALRM and continues as if it had never generated a SIGALRM.

In the following example, the number 28 represents the signal SIGWINCH. Process control returns from the child process to the debugger when a SIGWINCH is generated.

CodeWatch> CATCH /NIGNORE 28
Changing SIGWINCH to be caught and not ignored.

When the child process resumes, it recognizes the signal SIGWINCH and continue as if it had incurred a SIGWINCH.

This example turns on notification for an endfile ON-unit.

CodeWatch> CATCH ENDFILE
Adding ENDFILE to be caught.
Note: The /IGNORE and /NIGNORE flags are not used specifying an ON-unit with CATCH, and are ignored with the message shown in this example:
CodeWatch> CATCH /IGNORE ENDFILE
/IGNORE and NIGNORE flags are not allowed with On units - ignored.
Adding ENDFILE to be caught.
Parent topic: CodeWatch Commands
Related concepts
Setting Notifications for ON-units
Related information
Lcatch
Ncatch


Commandline

Use

Displays CodeWatch command-line arguments.

Command Syntax

COMMANDLINE

Description

The COMMANDLINE command displays the command-line arguments specified to the user program. Command- line arguments may be specified to the user program either on the CodeWatch command line upon invocation of the debugger, or by using the RELOAD command.

Example

In the following two separate examples, the command-line arguments are displayed. Note that the primes executable file being debugged takes no command-line arguments, whereas the myprog executable file was invoked with two command-line arguments.

CodeWatch> COMMANDLINE
Command line : "primes"

CodeWatch> COMMANDLINE
Command line : "myprog" "-b" "-verbose"
Parent topic: CodeWatch Commands
Related information
Reload


Continue

Use

Begins or continues program execution.

Command Syntax

CONTINUE

Description

The CONTINUE command is used to begin program execution initially or following a reload operation, or to resume program execution following a breakpoint or a step operation.

The CONTINUE command is often the last command in an action-list.

Example

In this example, program execution is continued until the breakpoint is encountered.

CodeWatch> CONTINUE
Break at PRIMES.READ_INPUT\%ENTRY

In the following example, a breakpoint is set at line 119 of the main program and a watchpoint is set on the variable n with an action list to continue program execution. The debugger will report when the contents of n have changed.

CodeWatch> BREAKPOINT 119
CodeWatch> WATCH n /ACTION [C]
CodeWatch> CONTINUE

Input maximum prime boundary: 10
Program Stopped due to a Watchpoint
Watched variable N modified about line PRIMES\118
New Value: 10 {fixed bin (31))
Break at PRIME\119
Parent topic: CodeWatch Commands
Related information
Breakpoint
Watch


Detach

Use

Detaches from the currently attached process.

Command Syntax

DETACH

Description

Detaches CodeWatch from the currently attached process.

Note: The DETACH command may not be supported on some systems.
Parent topic: CodeWatch Commands
Related information
Attach
Kill
Load
Nload


Dstep

Use

Sets the default mode and/or action-list for Step.

Command Syntax

DSTEP [ IN|OVER ]
      [ BACTION | SACTION | BOTH ]
      [ [action-list] ]

where:

action-list
Specifies a set of one or more CodeWatch commands separated by semicolons

Description

The DSTEP command sets the default stepping mode to either In or Over called routines and/or sets the default action-list for Step. If Dstep is not used, Over is the default stepping mode.

The Baction, Saction, and Both default stepping modes are intended to be used to step to a user-specified breakpoint. You may specify that the breakpoint action list be executed (Baction), the default step action list be executed (Saction), or both action lists be executed (Both).

Example

In the following example, the default stepping mode is set to In and the PRINT command is set as the default action to be executed at each step. When the subsequent Step is executed, the current execution point is displayed and the current source line is printed.

CodeWatch> DSTEP IN [PRINT]
CodeWatch> STEP
Step at PRIMES.SIFT\%ENTRY
  76: sift: procedure(n);
Parent topic: CodeWatch Commands
Related information
Lstep
Step


Environment

Use

Sets the current evaluation environment.

Command Syntax

ENVIRONMENT [environment]

where:

environment
Can be a simple block name or a block name followed by an activation number or a statement identifier

Description

The ENVIRONMENT command sets the current evaluation environment to provide scope to the debugger for identifying variables and statements.

An activation number is used to establish, as an environment, an activation of a block other than the most recent one. If the environment argument is not specified, the evaluation environment is set to the environment containing the current execution point, and the current source file pointer is set to the current execution point. Whenever the environment changes during program execution, the evaluation environment is reset to the environment containing the current execution point.

Example

In the following example, the current evaluation environment is changed to PRIMES, and then it is reset to the previous evaluation environment by using Environment without any arguments.

CodeWatch> ENVIRONMENT PRIMES
CodeWatch> E n
N =                5 {fixed binary (31)}
CodeWatch> ENV
Environment reset to PRIMES.READ_INPUT
Parent topic: CodeWatch Commands
Related information
Lenvironment


Evaluate

Use

Evaluates and prints the resultant value of expressions.

Command Syntax

display mode
One of ASCII, BIT, FLOAT, HEX, INTEGER, or OCTAL
expression
Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables.

Description

The EVALUATE command evaluates and prints the value of expressions in the source language program. If the expression is omitted, Evaluate uses the previous expression that was evaluated. If no previous expression was evaluated, an error message generates.

The value of simple variables may be changed using the LET command. Array evaluation and array slice evaluation is also supported.

The display mode is the mode in which the value of the expression is to be printed. The valid display modes are Ascii, Bit, Float, Hex, Integer, and Octal. The display modes are defined in the table below.

Display
 | Mode Definition
AScii | Displays the value as a series of Ascii characters.
Bit | Displays each bit in the value as a 1 or a zero.
Float | Displays the value as a single-precision floating-point number.
Hex | Displays the value as a series of hexadecimal numbers.
Integer | Displays the value as a series of signed decimal numbers.
Octal | Displays the value as a series of unsigned octal numbers.
Note: CodeWatch allows evaluation of Widechar and Graphic variables only. Evaluation of Widechar and Graphic expressions is currently not supported.

For WIDECHAR variable evaluation, half byte-pairs outside the ASCII range display as a '.' character. Use the EVALUATE command with the /h option to display hexadecimal values for each byte-pair. For example:

dcl wc wchar (8) init('003900370038'Wx);

…

eval /h wc

WC = 00 39 00 37 00 38 00 20 00 20 00 20 00 20 00 20 (hex)  {widechar (8)}

dcl gc graphic (8)  init(‘82588256825781408140814081408140’Gx);

…

eval /h gc

GC = 82 58 82 56 82 57 81 40 81 40 81 40 81 40 81 40 (hex)  {graphic (8)}

In the above example, the Widechar and Graphic strings correspond to the ASCII string ‘978’. For Graphic, codepage of 932 - SHIFT-JIS – Japanese is assumed. For each, Evaluate without /hex will print the “raw” Widechar or Graphic value to the terminal window.

The SUBSTR and LENGTH built-ins may be applied to variable references as part of EVALUATE.

Example

In this example, the value of data items in the SIFT routine is evaluated.

CodeWatch> EVALUATE THIS_PRIME
THIS_PRIME =         7 {fixed binary (31))

In this example, a cross section of the array PRIMES from 1 to count -1, where count equals 4, is evaluated.

CodeWatch> EVALUATE PRIMES (1 : count - 1)
PRIMES(1) =              1 {fixed binary (31))
PRIMES(2) =              2 {fixed binary (31))
PRIMES(3) =              3 {fixed binary (31))

Restrictions

None.

Parent topic: CodeWatch Commands
Related information
Let
Type


Find

Use

Locates and prints a specified string.

Command Syntax

FIND [/IGNORE] [string]

where:

string
Is a sequence of characters

Description

The FIND command locates a line in the source file containing a specified string and reports that line.

Quotation marks may be used to delimit the string but they are not required. If the string is not specified, the default value will be the string specified in the previous Find. If there is no string specified in the first instance of Find, an error message will be generated.

The debugger finds the first occurrence of the string after the current file position in the source file, then prints the line containing that occurrence of the string. By default, Find is case-sensitive, so that string "ABC" differs from "abc" and "Abc". When the ignore case option is turned on with Find, it is case-insensitive, so that the string "ABC" is the same as the string "abc" and "Abc".

If the string is not found, the current source file pointer is positioned at the last line of the user program.

Example

In this example, the string "main" is located.

CodeWatch> FIND main
 108:       /* main procedure */

If the string is not identical in terms of case to the string in the source file, it will not be found. For example:

CodeWatch> FIND MAIN
String not found: "MAIN"

In the following example, the search is case-insensitive.

CodeWatch> FIND /IGNORE MAIN
 108:       /* main procedure */
Parent topic: CodeWatch Commands
Related information
Point
Print


Goto

Use

Moves the execution pointer to a specified statement.

Command Syntax

GOTO statement-id

where:

statement-id
Can be a line number, a simple statement label, or a statement label followed by a line number offset or statement offset

Description

The GOTO command moves the execution pointer to a specified statement. Program execution resumes at this point when a Continue or Step is issued. The named statement must exist in the current program block.

Note:

It is not valid to put an activation number on the statement-id. If the activation number of an existing previous block invocation is put on the statement-id, it is ignored; otherwise, the following error message is displayed:

specified activation does not
             exist

It is not possible to use Goto to go to the %EXIT point of a block. The RETURN command, however, can be used to go to the %EXIT point.

When a Goto is executed, the debugger displays the current execution point.

Example

In this example, the execution point is changed to line 21 from the previous execution point as displayed by the Where command.

CodeWatch> WHERE
Current execution point is PRIMES.READ_INPUT\%ENTRY
CodeWatch> GOTO 21
Execution point is now PRIMES.READ_INPUT\21
Parent topic: CodeWatch Commands
Related information
Where
Continue
Step


Help

Use

Displays help text for debugger commands.

Command Syntax

HELP [command-name]

where:

command-name
Is the full spelling of a CodeWatch command or its accepted abbreviation

Description

The HELP command with no parameters lists all of the available CodeWatch commands. If the HELP command is followed by command-name, help text for that command is displayed.

Example

The following is an excerpt of the text displayed when invoking the HELP command with the BREAKPOINT command name abbreviation.

CodeWatch> HELP B
The BREAKPOINT command suspends execution to allow for debugger actions.

Command Syntax
         Breakpoint [ statement-id ]
                    [[action-list] ]
                    [/IF { logical-expr } [/ELse [action-list] ]]
                    [/Skip=n]
                    [/Ignore | /Nlgnore [/All]]
                    [/SILent | /NSILent]
Parent topic: CodeWatch Commands


Kill

Use

Kills the current child process.

Command Syntax

KILL

Description

Kills the current child process, and purges the CodeWatch internal symbol table.

Example

CodeWatch> KILL
Parent topic: CodeWatch Commands
Related information
Attach
Detach
Load
Nload


Lbreakpoint

Use

Lists information on breakpoints.

Command Syntax

LBREAKPOINT  [statement-id|/ALL ]

where:

statement-id
Names the statement at which the breakpoint is to be listed

Description

The LBREAKPOINT command lists information on a single breakpoint or on all breakpoints.

If the statement identifier is omitted, information is listed on the breakpoint at the current execution point. If /ALL is specified, information is listed on all breakpoints. The information listed includes the skip count, execution count (the number of times the breakpoint has been encountered) and any specified action-list.

Example

In this example, all breakpoints are listed.

CodeWatch> LBREAKPOINT /ALL
Break set at PRIMES\114 (count = 1)
Break set at PRIMES\119 (count = 2)
Break set at PRIMES.READ_INPUT\%ENTRY (count=1) [E maxv;]
Break set at PRIMES.ISPRIME\%ENTRY (count = 1)
Parent topic: CodeWatch Commands
Related information
Breakpoint
Nbreakpoint


Lcatch

Use

Lists CATCH settings for a given signal, the CATCH status for a specified ON-unit, or the state of all signals and ON-units.

Command Syntax

LCATCH [/ALL | signal]

or

LCATCH [ON-unit]

where:

ALL
Lists signals to be caught and signals not to be caught.
signal
Can be either a signal name mnemonic (such as SIGALRM, SIGINT, and so on) or the signal number corresponding to that signal. Signal names may be specified in either uppercase or lowercase letters. If neither a signal name nor /ALL command is specified, all of the signals currently set to be caught display.
ON-unit
The name of an ON-unit at which you want stop notification whenever the debugger detects a condition that triggers the ON-unit.

Description

When used with the /ALL option, LCATCH lists two sets of signals, those that are currently set to be caught and those that are currently set to not be caught. The LCATCH command, with a signal name specified, lists Catch settings for that given signal.

Example

In the following example, the current Catch settings for the signal SIGALRM are listed.

CodeWatch> LCATCH SIGALRM
SIGALRM not being caught.

In this example, the signals currently set to be caught and those that are set not to be caught are listed.

CodeWatch> LCATCH /ALL

CATCH:
  (signals)
    SIGQUIT[3]      SIGIOT[6] 					SIGUSR1[10]      SIGSEGV[11]      SIGSUR2[12]
    SIGPIPE[13]     SIGTERM[15]    SIGTTIN[21]      SIGTTOU[22]      SIGURG[23]

  (on units)
    ENDFILE
CATCH (ignore):
  (signals)
    SIGINT[2]       SIGILL[4]      SIGTRAP[5]

NCATCH:
  (signals)
    SIGHUP[1]       SIGBUS[7]      SIGPFE[8]       SIGKILL[9]       SIGALRM[14]
    SIGSTKFLT[16]   SIGCHLD[17]    SIGCONT[18]     SIGSTOP[19]
    SIGTSTP[20]     SIGXCPU[24]    SIGXFSZ[25]     SIGVTALRM[26]
    SIGPROF[27]     SIGWINCH[28]   SIGPOLL[29]     SIGPWR[30]       SIGSYS[31]

More...
  (on units)
    ANYCONDITION                   AREA
    ATTENTION                      CONDITION
    CONVERSION                     ENDPAGE
    ERROR                          FINISH
    FIXEDOVERFLOW                  KEY
    OVERFLOW                       RECORD
    SIZE                           UNDEFINEDFILE
    UNDERFLOW                      USERCONDITION
    USERCONDITION(SS$_UNWIND)      VAXCONDITION
    ZERODIVIDE
Parent topic: CodeWatch Commands
Related concepts
Setting Notifications for ON-units
Related information
Catch
Ncatch


Lenvironment

Use

Lists the current evaluation environment.

Command Syntax

LENVIRONMENT [/ALL ] [/FULL]

Description

The LENVIRONMENT command lists the current evaluation environment.

The All option lists all environments within the source file.

The Full option lists the current environment, the first and last source file line numbers in that environment, and the text offsets for the beginning and end of code in that environment. The offsets correspond to those found in the expanded listing generated by the Compiler.

Example

In this example, the current evaluation environment displayed is PRIMES.READ_INPUT.

CodeWatch> LENVIRONMENT
Evaluation environment is PRIMES.READ_INPUT
Parent topic: CodeWatch Commands
Related information
Environment


Let

Use

Assigns a value of an expression to a name.

Command Syntax

LET name = expression

where:

name
Is the name of any variable or destination construct (such as a substring or based reference in PL/I) that occurs in the source language program
expression
Can be any expression allowed by the source language whose value can be converted to the data type of the named variable. You can also assign a hexadecimal literal constant to a variable with an X, XN, Z, A or E expression. For example:
L FCD_ORGANIZATION = '01'x

Description

The LET command assigns a value of an expression to a name. When the expression is evaluated, appropriate type conversions are performed. The resultant value is assigned to the named variable. If the type conversion is illegal, the debugger will issue an error message.

The value of a character string constant can be changed by enclosing the expression within single or double quotation marks, depending on the source language.

In C, assignments are merely expression operators with side effects. Therefore, Evaluate provides the same functionality as Let in other languages.

Breakpoints are disabled during function calls using the LET command. If you want a breakpoint in a called routine to be incurred, use the CALL command.

The SUBSTR and LENGTH built-ins may be applied to variable references as part of LET.

Note: The Graphic and Widechar data types are supported in the LET command. Only variables references are allowed (not full expressions).
dcl wc wchar (8) varying;
dcl  val fixed bin (15) init (978);

…

let wc = i;      /* Codewatch will convert  val to WideChar and assign to wc */
eval /h wc

WC = 00 00 20 00 20 00 20 00 39 00 37 00 38 (hex)  {widechar varying (8)}
eval length(w)

6  {fixed binary (15)}

dcl gc graphic (8) varying;

…

let gc = val  /* Codewatch will val to Graphic and assign to gc */
eval /h gc

GC = 81 40 81 40 81 40 82 58 82 56 82 57 (hex)  {graphic varying (8)}

e length(gc)
6  {fixed binary (15)}

In the above example, the Widechar and Graphic strings correspond to the ASCII string ‘978’. For Graphic, codepage of 932 - SHIFT-JIS – Japanese is assumed. For each, Evaluate without /hex will print the “raw” Widechar or Graphic value to the terminal window.

Example

In this example, the value of MAXV is assigned a new value (MAXV/ 2).

CodeWatch> EVALUATE MAXV
MAXV =             10 {fixed binary (31))
CodeWatch> LET MAXV = MAXV/2
CodeWatch> EVALUATE MAXV
MAXV =              5 [fixed binary (31))

Restrictions

None.

Parent topic: CodeWatch Commands
Related information
Arguments
Evaluate


Lmacro

Use

Lists the macro definitions.

Command Syntax

LMACRO { macro1, macro2, ..., macron | /ALL }

Description

The LMACRO command lists the definition of one or more specified macros or the definitions for all currently defined macros. The debugger lists the action-list that was defined for the macro. Either the indicated macro-name(s) or /ALL must be specified.

Example

In this example, all of the macro definitions are listed.

CodeWatch> LMACRO /ALL
FIG = [FIND /IGNORE]
INFO = [LB /A; LENV; LMA /A; WHERE]
Parent topic: CodeWatch Commands
Related information
Macro
Nmacro


Load

Use

Loads the symbol table from a specified file as the primary executable file.

Command Syntax

LOAD filename

Description

The LOAD command loads the symbol table from filename into CodeWatch as the primary executable file for debugging. It also purges the internal CodeWatch symbol table of any previously loaded executable files or shared libraries.

Example

CodeWatch> LOAD myprog.out
Parent topic: CodeWatch Commands
Related information
Attach
Detach
Kill
Nload


Log

Use

Logs debugger commands and, optionally, output to a specified file or files.

Command Syntax

LOG [/FuLL]filename

where:

filename
Is the pathname of any file allowing write permission to the user

Description

The Log command causes all subsequent debugger commands to be appended to the specified file.

The /FULL option specifies that all output from the debugger be logged to the specified file in addition to all debugger commands. It is possible to log commands to one file and commands-and-output to another file. This would be done by the commands:

CodeWatch> LOG filel
CodeWatch> LOG /FULL file2

The NLOG command takes an optional file name that tells the debugger which log session to stop. If no file name is given, the debugger will first check if commands are being logged to a file (no /FULL). If so, that log session is stopped. If there is no such log session, the debugger checks to see if commands-and-output to a file (/FULL) are being logged. If so, that log session is stopped.

Example

CodeWatch> LOG temp
CodeWatch> FIND Main
77 REM       ** Main Program **
CodeWatch> BREAKPOINT 89
CodeWatch> PRINT 20
   77:            REM    ** Main Program **
   78:            INTEGER max_value, max_primes, n
   79:            REM      REAL a
   80:
   81:            max_value  = 1000
   82:            max_primes = 500
CodeWatch> NLOG
Ending debugger command logging to "temp"
CodeWatch> !cat temp
FIND Main
BREAKPOINT 89
PRINT 20
Parent topic: CodeWatch Commands
Related information
Nlog
Read


Lreturn

Use

Lists the return value of a function.

Command Syntax

LRETURN

Description

When the current execution point is at the exit point of a function, Lreturn prints the value to be returned by the function.

Example

In this example, the return value for the PRIMES function is listed.

CodeWatch> LRETURN
Return value for PRIMES is 15 {fixed binary (31)}
Parent topic: CodeWatch Commands
Related information
Return


Lsource

Use

Prints the name of the current source file being displayed.

Command Syntax

LSOURCE [/ALL] [/FULL]

The All, Full, Both, and Map buttons access the Lsource dialog. The Lsource dialog is for information only and no action may be executed. Specifying the Both button is the same as specifying both the /ALL and /FULL command-line options.

Description

The LSOURCE command prints the name of the source file currently being displayed as well as the time and date of its creation. If the source file being displayed does not contain the current evaluation environment, Lsource also displays the source file that does contain the current evaluation environment.

If the Full option is specified, the name of the symbol table file associated with the source file containing the current evaluation environment will also be displayed. If the All option is specified, all of the source files in the program being debugged that were compiled in debug mode will be displayed.

Example

In this example, the name of the symbol table file associated with the source file containing the current evaluation environment, the source file, and the source file currently being displayed are listed.

CodeWatch> LSOURCE
Current display source file is "primes.pl1" (PL/I) Apr 11 11:06:51 1991
Parent topic: CodeWatch Commands
Related information
Source


Lstep

Use

Lists the current stepping mode and the default action-list.

Command Syntax

LSTEP

Description

The LSTEP command lists the current mode of stepping, that is, either In or Over, the default action-list, and the default action-list to be executed when stepping to a breakpoint.

Example

In this example, the default stepping mode is in, the step action-list contains the Print command, and the action-list that will be executed upon stepping to a user breakpoint is the step action (Print).

CodeWatch> LSTEP
Step IN; Execute STEP action
Action = [PRINT;]
Parent topic: CodeWatch Commands
Related information
Dstep
Step


Ltrace

Use

Lists the current tracing mode.

Command Syntax

LTRACE

Description

The LTRACE command lists the current mode of tracing, that is, statement and/or entry.

Example

In this example, the current tracing mode is listed. Note that no conditional expression is specified.

CodeWatch> LTRACE
TRACE ENTRY [C;] /IF {}
Parent topic: CodeWatch Commands
Related information
Ntrace
Trace Entry
Trace Statement


Lwatch

Use

Lists information on watchpoints.

Command Syntax

LWATCH {variable|/ALL}

where:

variable
Specifies a variable in the source program

Description

The LWATCH command lists information on the given watchpoint. If /ALL is specified, information is listed on all watchpoints. The information listed includes the skip count, execution count (the number of times the watchpoint has been incurred), specified switch settings, and any specified action-list.

Example

In the following example, all of the existing watchpoints are listed.

CodeWatch> LWATCH /ALL
Watchpoint set for N (count = 1) /NSILENT /NIGNORE [C;]
Parent topic: CodeWatch Commands
Related information
Nwatch
Watch


Macro

Use

Defines a macro.

Command Syntax

MACRO macro-name = [action-list]

where:

action-list
Specifies a set of one or more CodeWatch commands separated by semicolons

Description

The MACRO command is used to define a macro as shorthand for an action-list. Sixty-four macros can be defined at any one time.

Note: Do not choose a macro name that is the same as a debugger command name, because the macro name will override the debugger command.

The action-list is specified in the usual way.

Once a macro has been defined, its name may be used just like any other debugger command name. The macro in the command line is replaced by the debugger commands specified in the action-list. Those commands are then executed normally.

If the last (or only) command in the action-list does not end with a semicolon, any additional arguments to that command can appear on a command line after the macro name. For example, suppose the following macro has been defined:

FOO = [ LET A = A + ]

The command FOO 3 can then be entered to add 3 to A.

Example

In this example, the macro info is defined that lists all breakpoints, the current evaluation environment, all macros, and the current execution point.

CodeWatch> MACRO info = [LB /ALL; LENV; LMACRO /ALL; WHERE]
CodeWatch> info
Break set at PRIME\118 (count = 2)
Break set at PRIMES.READ_INPUT\%ENTRY
Break set at PRIME.ISPRIME\%ENTRY (COUNT = 1)
Evaluation environment is PRIMES.ISPRIME
   info = [LB /ALL; LENV; LMA /ALL; WHERE]
Current execution point is PRIMES.ISPRIME\%EXIT

In the following example, the macro fig is defined to perform a case-insensitive search for the string you wish to specify as an argument.

CodeWatch> MACRO fig = [FIND /IGNORE]
CodeWatch> fig MAIN
  /* Main program */
Parent topic: CodeWatch Commands
Related information
Using Action Lists
Lmacro
Nmacro
Read
Save


Nbreakpoint

Use

Removes breakpoints.

Command Syntax

N BREAKPOINT [statement-id | /ALL ]

where:

statement-id
Is used to name the statement at which the breakpoint is to be removed

Description

The NBREAKPOINT command removes the breakpoint at the specified statement.

If the statement-id is omitted, the breakpoint at the current execution point is removed. If /ALL is specified, all breakpoints currently set are removed.

Example

In the following example, the breakpoint at line 94 is removed.

CodeWatch> NB 94

In the following example, all breakpoints are removed.

CodeWatch> NBREAKPOINT /ALL
Parent topic: CodeWatch Commands
Related information
Breakpoint
Lbreakpoint


Ncatch

Use

Prevents process control from returning to the debugger when the given signal or ON-unit is generated. Also turns off notification for a specified ON-unit.

Command Syntax

NCATCH signal

or

NCATCH {ON-unit}

where:

signal
Can be either a signal name mnemonic (such as SIGALRM, SIGINT, and so on) or the signal number corresponding to that signal. Signal names may be specified in either uppercase or lowercase
ON-unit
The name of an ON-unit at which you want stop notification whenever the debugger detects a condition that triggers the ON-unit.

Description

The NCATCH command prevents process control from returning to the debugger when the given signal or ON-unit is generated. The child (user) process continues without interruption, as if the given signal had been generated. This implies that user-defined handlers are executed.

Example

In the following example, the process control will not return from the child process to the debugger when a SIGALRM is generated.

CodeWatch> NCATCH SIGALRM
Changing SIGALRM to no longer be caught.

As a result, NCATCH allows the child process to continue uninterrupted when a SIGALRM is generated. If the user process has its own signal handler for a SIGALRM, that signal handler will be executed.

This example uses NCATCH to stop catching an ENDFILE ON-unit.

CodeWatch> NCATCH ENDFILE
Changing ENDFILE to no longer be caught.
Parent topic: CodeWatch Commands
Related concepts
Setting Notifications for ON-units
Related information
Catch
Lcatch


Nload

Use

Kills the current child process.

Command Syntax

NLOAD

Description

Kills the current child process and purges the CodeWatch internal symbol table.

Example

CodeWatch> NLOAD
Parent topic: CodeWatch Commands
Related information
Attach
Detach
Kill
Load


Nlog

Use

Stops the logging of debugger commands and/or commands-and-output to a file or files.

Command Syntax

NLOG [filename]

where:

filename
Is the name of a log file specified in a previous LOG command

Description

The NLOG command ceases logging of debugger commands or commands-and-output to a file or files specified in the previous LOG command.

Example

CodeWatch> LOG temp
CodeWatch> FIND Main
77  REM      ** Main Program **
CodeWatch> BREAKPOINT 89
CodeWatch> PRINT 20
   77:           REM      ** Main Program **
   78:            INTEGER max_value, max_primes, n
   79:           REM      REAL a
   80:
   81:            max_value  = 1000
   82:            max_primes = 500
CodeWatch> NLOG
Ending debugger command logging to "temp"
The file "temp" will contain
CodeWatch> !cat temp
FIND Main
BREAKPOINT 89
PRINT 20
Parent topic: CodeWatch Commands
Related information
Log
Read


Nmacro

Use

Removes macro definitions.

Command Syntax

NMACRO {macro1, macro2, …, macron, | /ALL }

Description

The NMACRO command removes the definition of one or more specified macros or the definitions of all currently defined macros. Either the specific macro name(s) or /ALL must be specified.

Example

In this example, the macro named info is removed.

CodeWatch> NMACRO info

In this example, all macro definitions are removed.

CodeWatch> NMACRO /ALL
Parent topic: CodeWatch Commands
Related information
Lmacro
Macro


Nmap

Use

Reads the dynamic loader map and displays information about the currently loaded shared libraries.

Description

Shared library debugging has these limitations: CodeWatch does not dynamically monitor the dynamic load map. If a shared library is loaded into CodeWatch via the SHLIB command, and that library is being programmatically loaded and unloaded, you must manually load and unload the symbols via SHLIB and NSHLIB, since there is no guarantee that the library will always be mapped to the same virtual address. However, use of the NMAP command and noting load addresses will indicate whether this is actually necessary.

Parent topic: CodeWatch Commands


Nshlib

Use

Purges the symbols of the shared library specified by slibfile from the CodeWatch internal symbol table.

Parent topic: CodeWatch Commands


Ntrace

Use

Disables entry or statement tracing.

Command Syntax

NTRACE {ENTRY | STATEMENT}

Description

The NTRACE command disables entry or statement tracing. If ENTRY is specified, any action-list and condition are removed as well.

Example

In this example, TRACE STATEMENT is disabled.

CodeWatch> NTRACE STATEMENT
Parent topic: CodeWatch Commands
Related information
Ltrace
Trace Entry
Trace Statement


Nwatch

Use

Removes watchpoints.

Command Syntax

NWATCH {variable|/ALL}

where:

variable
Specifies the variable being watched

Description

The NWATCH command removes the watchpoint for the given variable. If /ALL is specified, all watchpoints currently set are removed.

Example

In the following example, the watchpoint for the variable n is removed from the current listing.

CodeWatch> LWATCH /ALL
Watchpoint set for n (count = 1) /NSILENT /NIGNORE [C;]
CodeWatch> NWATCH n
CodeWatch> LWATCH /ALL
No watchpoints are currently set.
Parent topic: CodeWatch Commands
Related information
Lwatch
Watch


Peek

Use

Displays the contents of a specified area of user memory in a specified format.

Command Syntax

PEEK [/TEXT  | /DATA]
     [/HEX   | /DECIMAL  | /OCTAL]
     [/LONG  | /SHORT    | /BYTE]
     [/count] address

where:

count
Is a numeric constant
address
Is a numeric constant. (For format information, see the following Description section.)

Description

The PEEK command displays the contents of a designated amount of user program memory in a designated format starting at a given address.

If the Text option is specified, the user text segment of the program is read.

If the Data option is specified, the user data segment of the program is read. The Data option is the default.

The base of the displayed memory may be specified as being hexadecimal or decimal, depending on the options /HEX or /DECIMAL, respectively. /HEX is the default.

The size of each displayed memory unit may be specified as being 4 bytes (32 bits), 2 bytes (16 bits), or 1 byte (8 bits) by specifying the options /LONG, /SHORT, or /BYTE, respectively. When the option /BYTE is specified, the ASCII representation of the byte is also displayed. /LONG is the default.

The number of memory units to be displayed may be specified by using the /count option. This consists of a slash "/" followed by a decimal number. A count of one is the default.

The format of the given address may be either hexadecimal or decimal, depending on how it is written. A hexadecimal number must begin with a 0x or 0X or contain at least one of the hexadecimal digits "a" through "f" (case in-sensitive). A decimal number may contain only any of the decimal digits "0" through "9".

Example

The following PEEK command displays five lines (4-bytes) in hexadecimal format beginning at address 0x23d8.

Initial evaluation environment is PGM:(inactive)
CodeWatch> p12
    1:  pgm: proc options(main);
    2:
    3:      dcl string char (32) varying;
    4:
    5:      string = 'Hello World.';
    6:
    7:      put skip list (string);
    8:
    9:      put skip list (string);
   10:  end;
   11:  BOTTOM
CodeWatch> b 7
CodeWatch> c
Break at PGM\7
CodeWatch> e addr(string)
FFBFF94E (hex)  {pointer}
CodeWatch> peek /data /byte /7 0xFFBFF94E
<data> 0xffbff94e: 0x00   <nul>
<data> 0xffbff94f: 0x0c   CTRL-L
<data> 0xffbff950: 0x48   H
<data> 0xffbff951: 0x65   e
<data> 0xffbff952: 0x6c   l
<data> 0xffbff953: 0x6c   l
<data> 0xffbff954: 0x6f   o
CodeWatch> peek /next
<data> 0xffbff955: 0x20   <space>
<data> 0xffbff956: 0x57   W
<data> 0xffbff957: 0x6f   o
<data> 0xffbff958: 0x72   r
<data> 0xffbff959: 0x6c   l
<data> 0xffbff95a: 0x64   d
<data> 0xffbff95b: 0x2e   .
CodeWatch> s

Hello World. Step at PGM\9     <Note: prints ‘Hello World.’ 12 chars>
CodeWatch> po
    9:      put skip list (string);
CodeWatch> poke /data /short 0xFFBFF94E,5
<data> 0xffbff94e: 0x000c ---> 0x0005
CodeWatch> s

Hello Step at PGM\10           <Note: prints ‘Hello’ 5 chars>
CodeWatch> q
CodeWatch Quit...Bye!
Parent topic: CodeWatch Commands
Related information
Evaluate
Poke
Watch


Point

Use

Resets and displays the source file pointer within the current source file.

Command Syntax

POINT [+n|–n|n]

where:

n
Is the line number you specify

Description

The POINT command relocates the source file pointer within the current source file and prints that line.

If a sign is specified, the debugger relocates the source file pointer to the line that is n lines before (–) or after (+) the current source file pointer. Otherwise, the debugger relocates the source file pointer to the line specified by n. The debugger then prints out the new pointed to line. If n is omitted, the source file pointer is reset to the current execution point, and that line is printed.

Example

In the following example, the source file pointer is reset to line 116 and displayed.

CodeWatch> POINT 116
  116:  call read input (n);

In this example, the source file pointer is reset to two lines before the current source file pointer, and that line is displayed.

CodeWatch> POINT -2
  114:  put skip (2);
Parent topic: CodeWatch Commands
Related information
Print


Poke

Use

Changes the contents of a specified area of user memory in a specified format.

Command Syntax

POKE [/TEXT | /DATA]
     [/LONG | /SHORT | /BYTE]
     address, data-value

where:

address
Is an address value specifying the memory location to examine. The address value has the same format as the data-value described below. The data segment is the default.
data-value
The format of the given data value (or address) may be either hexadecimal or decimal depending on how it is written. A hexadecimal number must begin with a 0x or 0X or contain at least one of the hexadecimal digits "a" through "f" (case in-sensitive). A decimal number may contain only any of the decimal digits "0" through "9”.

Description

The /BYTE, /SHORT, and /LONG options, used with integer values, specify the size of memory to be altered (1, 2, or 4 bytes, respectively). /LONG is the default.

Example

The following POKE command stores the hexadecimal value 99 at address 0x7FFFE480.

Initial evaluation environment is PGM:(inactive)
CodeWatch> p12
    1:  pgm: proc options(main);
    2:
    3:      dcl string char (32) varying;
    4:
    5:      string = 'Hello World.';
    6:
    7:      put skip list (string);
    8:
    9:      put skip list (string);
   10:  end;
   11:  BOTTOM
CodeWatch> b 7
CodeWatch> c
Break at PGM\7
CodeWatch> e addr(string)
FFBFF94E (hex)  {pointer}
CodeWatch> peek /data /byte /7 0xFFBFF94E
<data> 0xffbff94e: 0x00   <nul>
<data> 0xffbff94f: 0x0c   CTRL-L
<data> 0xffbff950: 0x48   H
<data> 0xffbff951: 0x65   e
<data> 0xffbff952: 0x6c   l
<data> 0xffbff953: 0x6c   l
<data> 0xffbff954: 0x6f   o
CodeWatch> peek /next
<data> 0xffbff955: 0x20   <space>
<data> 0xffbff956: 0x57   W
<data> 0xffbff957: 0x6f   o
<data> 0xffbff958: 0x72   r
<data> 0xffbff959: 0x6c   l
<data> 0xffbff95a: 0x64   d
<data> 0xffbff95b: 0x2e   .
CodeWatch> s

Hello World. Step at PGM\9     <Note: prints ‘Hello World.’ 12 chars>
CodeWatch> po
    9:      put skip list (string);
CodeWatch> poke /data /short 0xFFBFF94E,5
<data> 0xffbff94e: 0x000c ---> 0x0005
CodeWatch> s

Hello Step at PGM\10           <Note: prints ‘Hello’ 5 chars>
CodeWatch> q
CodeWatch Quit...Bye!
Parent topic: CodeWatch Commands
Related information
Evaluate
Peek
Watch


Print

Use

Prints the next line or a number of lines.

Command Syntax

Print x

or

P x

where x is the number of lines that are going to be printed. x is optional and if it is omitted, only one line will be printed.

Description

Print displays a line or a number of lines in the output window. If you want to print a number of lines, specify the number after the PRINT command.

Example

This example shows the output of PRINT:

CodeWatch> P
  119: do while (n > 1);

The following example shows the output of PRINT plus a specified number of lines:

CodeWatch> PRINT 15
109       /* main procedure */
110
111       declare n fixed binary(31);
112
113       put skip;
114       put list (' *** Sieve of Eratosthenes ***');
115       put skip (2);
116
117       call read_input(n);
118
119       do while (n > 1);
120          call sift(n);
121          call read_input(n);
122       end;
123
124   end;
Parent topic: CodeWatch Commands


Quit

Use

Terminates a debugging session.

Command Syntax

QUIT

Description

Quit causes termination of the debugging session. Selecting the Exit item in the File menu is equivalent to issuing the QUIT command.

Example

This example shows the message the debugger displays as it exits.

CodeWatch> QUIT
CodeWatch Quit ... Bye!
Parent topic: CodeWatch Commands
Related information
Save


Read

Use

Reads and executes debugger commands from a specified file.

Command Syntax

READ filename

where:

filename
Is any file containing debugger commands. If the file is not in the current working directory, its pathname must be specified

Description

The READ command is used to execute debugger commands, which are contained in the specified filename. Each command is printed to the terminal as it is executed. Seven levels of Read commands may be nested in debugger command files.

Example

In this example, debugger commands are read in from a file called dbg. After all the commands are read and executed, the debugger prompts for the next command to be entered.

CodeWatch> READ dbg
**** Reading commands from "dbg" ...
CodeWatch> BREAKPOINT PRIMES\119 /SKIP=0
CodeWatch> BREAKPOINT PRIMES.READ_INPUT\%ENTRY /SKIP=0 [e maxv;]
CodeWatch> BREAKPOINT PRIMES.ISPRIME\%ENTRY /SKIP=0
CodeWatch> BREAKPOINT PRIMES.PRINT_OUT\60 /SKIP=0
CodeWatch> BREAKPOINT PRIMES.PRINT_OUT\59 /SKIP=0
CodeWatch> MACRO info=[ lb /a;lenv;lma /a; where ]
CodeWatch>
**** Done reading commands from "dbg"
Parent topic: CodeWatch Commands
Related information
Log
Nlog
Save


Registers

Use

Displays the contents of the general machine registers.

Command Syntax

REGISTERS

Description

The REGISTERS command displays the contents of all the machine registers as long hexadecimal values. Floating-point registers may or may not be displayed, depending on the target.

Example

The following input from the REGISTERS command is target-specific and may not match what is displayed on your system.

CodeWatch> REGISTERS

D0: 0x0000003C D1: 0x00000004 D2: 0x00000001 D3:0x00000000
D4: 0x00000000 D5: 0x00000000 D6: 0x00000000 D7:0x00000000
A0: 0x0EFFFD94 A1: 0x0002037C A2: 0x00000000 A3:0x0EFFFDC8
A4: 0x0EFFFDD0 A5: 0x00000000 A6: 0x0EFFFDB0 A7:0x0EFFFD90
SR: 0x00000000 PC: 0x000023D8

FO: 0x7FFF0000FFFFFFFFFFFFFFFF F1: 0x7FFF0000FFFFFFFFFFFFFFFF
F2: 0x7FFF0000FFFFFFFFFFFFFFFF F3: 0x7FFF0000FFFFFFFFFFFFFFFF
F4: 0x7FFF0000FFFFFFFFFFFFFFFF F5: 0x7FFF0000FFFFFFFFFFFFFFFF
F6: 0x7FFF0000FFFFFFFFFFFFFFFF F7: 0x7FFF0000FFFFFFFFFFFFFFFF

FPCR: 0x0000F400 FPSR: 0x00000000 FPIAR: 0x00000000
Parent topic: CodeWatch Commands


Reload

Use

Reloads the user program.

Command Syntax

RELOAD [/ARGUMENTS command-line-arguments]
       [/NEWARG command-line-arguments]
       [< filename]
       [> filename]

where:

command-line-arguments
Is a list of text strings to be passed to the user program as its arguments. This must be the last option on the RELOAD command line
filename
Is the pathname of any file

Description

The RELOAD command will reinitialize the user program while preserving any explicitly set breakpoints and any associated action lists. All breakpoint counters will be reset to zero.

A subsequent Continue or Step will execute the user program from the beginning.

Example

In this example, the debugging session is restarted in the original evaluation environment, with all breakpoints preserved and without returning to the system level.

CodeWatch> RELOAD
Command line : "primes"
Reloading..ok
Initial evaluation environment is PRIMES:(inactive)
CodeWatch>

In this example, user program output is redirected to the file primes.out

CodeWatch> RELOAD > primes.out
Reloading..ok
Initial evaluation environment is PRIMES:(inactive)
CodeWatch>
  • Changing Command-line Arguments
  • Redirecting User Program I/O
  • Redirecting I/O Back to the Terminal
Parent topic: CodeWatch Commands
Related information
Arguments
Continue
Step


Changing Command-line Arguments

If the Arguments option is not specified, the program will be initialized with the command-line arguments specified when CodeWatch was invoked. If the Arguments option is specified, the given arguments will be used as command-line arguments to the reinitialized program. If more than one argument is specified, they must be separated by a space. These command-line arguments will be in effect until the next time the program reloads.

If you want to permanently change the command-line arguments of the program being debugged, that is, for the remainder of the debugging session, this is possible using the /NEWARG command-line option. This specifies that the given command-line arguments be used for the remainder of the debugging session. These may be reset by again using the /ARGUMENTS or /NEWARG command-line options.

Parent topic: Reload


Redirecting User Program I/O

User program input may be redirected by either specifying the command-line option < filename or by entering a file name in the Stdin edit field of the Reload dialog box.

User program output may be redirected by either specifying the command-line option > filename or by entering a file name in the Stdout edit field of the Reload dialog box. Any error opening filename for either input or output will result in an error message and CodeWatch exiting.

Note:

In the RELOAD command-line syntax, there must be a space between the "<" or the ">" and the file name.

By default, user input and output is redirected to and from the xterm window from which CodeWatch was invoked. However, this may be changed using the RELOAD command.

Parent topic: Reload


Redirecting I/O Back to the Terminal

It is possible to redirect input or output back to the terminal after having redirected it elsewhere. To do this, specify the following:

RELOAD < /dev/tty

or:

RELOAD > /dev/tty

for input and output, respectively.

Parent topic: Reload


Return

Use

Transfers the execution pointer to the exit point of the current procedure and allows a return value to be set.

Command Syntax

RETURN [expression]

where:

expression
Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables

Description

The RETURN command transfers the current execution pointer to the exit point (%EXIT) of the current procedure. If the procedure returns a value, an expression indicating the return value must be given. An expression should not be given if the procedure does not return a value.

If the current execution point is already at the exit point of the current procedure, no action is taken if the procedure does not return a value, or the return value is set to the given expression if the procedure does return a value.

Example

In this example, the return value of the ISPRIME routine is set to "15".

CodeWatch> RETURN 15
CodeWatch> LRETURN
Return value for PRIMES.ISPRIME is 15 {fixed binary(31)}
Parent topic: CodeWatch Commands
Related information
Lreturn


Save

Use

Writes out commands to reset all currently set breakpoints, watchpoints, and/or macros to a specified file.

Command Syntax

SAVE [{/BREAKPOINT |/WATCH |/MACRO}…|/ALL]
     filename

where:

filename
Is the specified file that will contain the breakpoints, watchpoints, and/or macros settings

Description

The SAVE command writes out commands to a specified disk file to reset all current breakpoint, watchpoint, and/or macro settings for use in a later debugging session. The file can be read in by using the READ command.

If no options or the All option is specified, commands to reproduce all breakpoint, watchpoint, and macro settings will be written to the specified file.

If the Breakpoint option is specified, the breakpoint commands for all current breakpoint settings will be written to the specified file. If the Watch option is specified, the watchpoint commands for all current watchpoint settings will be written to the specified file. If the Macro option is specified, the macro commands for all current macros will be written to the specified file. Any combination of Breakpoint, Watch, and Macro may be used.

The SAVE command will create, not append, the specified file. If the file already exists, the Save will fail and an error will be issued. For more information, see the section Read.

Example

In this example, two debugging sessions are used to demonstrate the SAVE command. In the first session, macros, breakpoints, and watchpoints are saved in the dbg file; in the second session, the saved commands are read from the dbg file.

Session one:

$ cwcmd primes
CodeWatch setting up "primes". Wait...

CodeWatch> BREAKPOINT PRIMES\114
CodeWatch> BREAKPOINT PRIMES\119
CodeWatch> BREAKPOINT PRIMES.READ_INPUT\%ENTRY [E maxv;]
CodeWatch> BREAKPOINT PRIMES.ISPRIME\%ENTRY
CodeWatch> WATCH N /ACTION [C;]
CodeWatch> MACRO fig = [FIND /IGNORE]
CodeWatch> MACRO info=[ LB /A;LENV;LMA /A; WHERE ]
CodeWatch> SAVE dbg
Environment saved to file "dbg"
CodeWatch> QUIT

Session two:

$ cwcmd primes
CodeWatch setting up "primes". Wait...

CodeWatch> READ dbg
**** Reading commands from "dbg" ...
CodeWatch> BREAKPOINT PRIMES\114 /SKIP=0
CodeWatch> BREAKPOINT PRIMES\119 /SKIP=0
CodeWatch> BREAKPOINT PRIMES.READ_INPUT\%ENTRY /SKIP=0 [E maxv;]
CodeWatch> BREAKPOINT PRIMES.ISPRIME\%ENTRY /SKIP=0
CodeWatch> WATCH N /ACTION [C;]
CodeWatch> MACRO fig = [FIND /IGNORE]
CodeWatch> MACRO info = [ LB /A;LENV;LMA /A; WHERE ]
CodeWatch>
**** Done reading commands from "dbg"
Parent topic: CodeWatch Commands
Related information
Read
Breakpoint
Macro
Watch


Shlib

Use

Loads the symbols from the specified shared library, slibfile, into the CodeWatch internal symbol table.

Description

If slibfile is compiled using the -deb option, the command ENV displays the shared library source and other normal symbolic debugging.

If slibfile is specified with a simple filename, such as file.sl, CodeWatch first searches the current directory for this shared library. Failing that, it uses the search path indicated by the LD_LIBRARY_PATH environment variable on Solaris 2 (which is the same variable that is used by the dynamic loader). If using the -L option at link time to specify library locations, slibfile must specify the full pathname for the shared library.

When executed, SHLIB attempts to load all the debug symbols for a .so (UNIX/Linux) or .dll (Windows). If SHLIB is not fully qualified, for example SHLIB MYSO.so, then any paths specified by the CODEWATCH_STBPATH environment variable are used to search for the .stb. If SHLIB is fully qualified, for example SHLIB /home1/hub/staff/opli/steplib1/MYSO.so, then the directory containing the shared object is searched first. If unsuccessful, any paths specified by CODEWATCH_STBPATH are used.

CODEWATCH_SRCPATH must be set to include the directories where the source resides. It does not look in directories referenced by the SHLIB command.

The shared library file specified is evaluated as case-insensitive, with the file extension stripped. For example, if specifying MYFILE.dll, myfile is used to compare load events received during program execution.

Parent topic: CodeWatch Commands


Source

Use

Changes the current source file to be displayed.

Command Syntax

SOURCE [filename]

where:

filename
Is the name of the source file to be displayed

Description

The SOURCE command changes the source file to be displayed. This may be used, for instance, when you want to look at the contents of "COPY" or "INCLUDE" files. Referencing these files is discussed in the section Referencing Included or Copied Files in the chapter Debugging Concepts.

If the filename is omitted, the current source file is set to the source file associated with the current execution point. The current source file pointer is not explicitly set. To reset the current source file pointer to the current execution pointer, use Environment without any arguments.

Activation of the SOURCE command applies to the current debugger action only. Its effect is lost when the program resumes execution; that is, the current source file is set to the source file associated with the current execution point.

Example

In the following example, the source file from which lines are to be displayed is var.in. The LSOURCE command prints the name of the current source file as well as the name of the source file for the current environment, because it is different.

CodeWatch> SOURCE var.in
CodeWatch> LSOURCE
Current display source file is "var.in"
Source file of current environment is "x.pl1"
Current display source file is "var.in" (PL/I) Apr 11 11 :06 :51 1991
Parent topic: CodeWatch Commands
Related information
Referencing Included or Copied Files
Lsource


Stack

Use

Displays information on a specified number of stack frames.

Command Syntax

STACK [nframes|/ALL]
      [/FULL]
      [/ARGUMENTS]
      [/LOCALS]

where:

nframes
Is an integer specifying the count of the most recent stack frames to be displayed

Description

The STACK command is used to display information on a specified number of stack frames.

If the All option is specified, all stack frames back to your main program are displayed. There are typically a number of system start-up routines called before your main program. The frames for these start-up routines will not be displayed unless the Full option is specified. The Full option is useful only if specified in conjunction with a specified Count or the All option. If neither a specified Count nor the All option is present, only the current stack frame is displayed.

If the Arguments option is specified, the arguments to each procedure are displayed.

If the Locals option is specified, all local variables for each stack frame are displayed.

Example

In this example, information is displayed on all stack frames and the arguments to each procedure.

CodeWatch> STACK /ARGUMENT /ALL

Stack contains 5 frame(s).
Current execution point is PRIMES.SIFT\94

5: Owner is "PRIMES.SIFT"
   Arguments:
     N = 10 {fixed binary (31)}
   Called from PRIMES\119

4: Owner is "PRIMES"
   Arguments: None
   Main program
Parent topic: CodeWatch Commands
Related information
Arguments
Environment


Step

Use

Executes a specified number of statements.

Command Syntax

STEP [OUT]
     [IN|OVER]
     [count]
     [[action-list]]

where:

count
Is an integer specifying the number of statements to be executed

Description

action-list specifies a set of one or more CodeWatch commands separated by semicolons.

The STEP command starts program execution at the current location of the execution pointer and stops execution after one or a specified number of statements.

To execute a single statement, use Step with no options specified. To execute a number of statements, specify a count parameter.

If Step Out is specified, the debugger steps to the exit point of the current routine. If Step Out is specified with a count parameter, the first step is to the exit point of the current routine, and each step thereafter is to a succeeding statement in the calling routine. Thus, if the execution pointer is in a called routine and you want to step to the next executable statement in the calling routine, issue STEP OUT 2. The first step is to the exit point of the current routine, and the second step returns and steps forward in the calling routine. If the execution pointer is already at the exit point of the called routine, issuing Step Out causes the execution pointer to step to the exit point of the calling routine.

If Step In is specified and the current execution point is at a subroutine call, the debugger steps to the entry point of the called routine. If Step In is specified with a count parameter, the entry point is the first step, the first executable statement is another, and so on.

If Step Over is specified, the debugger steps over calls to routines. Step Over is the default mode for the STEP command.

If an action-list is present, it is performed at the last step and is set as the action to be taken for any other Step. To remove the Step action-list, supply a null action-list as an argument to Step. Use the DSTEP command to do this without stepping.

At the completion of a step operation, the debugger issues a message indicating the current execution point in the following format:

Step at x

where x is the location of the current execution point, that is, the statement that is about to be executed.

Note:

Step cannot be used when the current execution point of the user program is at a non-local Goto.

Example

In the following example, the default stepping mode is set to step in and the stepping action-list is set to print the current source line. Two step commands are executed (the second command with a count of 2).

CodeWatch> DSTEP IN [P]
CodeWatch> STEP
Step at PRIMES.SIFT\95
  95: primes(count) = this_prime;
CodeWatch> S 2
Step at PRIMES.SIFT\97
  97: do while (k < n);

In the following example, the debugger steps out of the sift routine.

CodeWatch> STEP OUT
Number of primes found was (prime) 5

1  2  3    5  7

Step at PRIMES.SIFT\%EXIT
  106: end sift;
Parent topic: CodeWatch Commands
Related information
Continue
Dstep
Lstep


Trace Entry

Use

Displays all procedure and block entries information during program execution.

Command Syntax

TRACE ENTRY [[action-list]]
            [/IF {logical-expr}]

where:

action-list
Specifies a set of one or more CodeWatch commands separated by semicolons
logical-expr
Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables, returning a boolean value

Description

Tracing enables information about all procedure and block entries to be reported as the program executes.

The TRACE ENTRY command sets tracepoints, which enable tracing of all procedure and block entries by printing a message each time a procedure or block is entered.

When entry tracing is enabled, the debugger will be activated as each procedure or block is entered, and activated again as each procedure or block is exited. The specified action-list applies only to the entry tracepoint; exit tracepoints always print a message and continue.

If an action-list is specified, the debugger will process the commands and print the results. If an action-list is omitted, a default action-list of [CONTINUE] is supplied. A common action-list is [ARGUMENTS; CONTINUE]. An action-list may not refer to statements or variables in a way that is dependent on scope. To take a breakpoint and enter interactive debugging at each entry, supply an explicit null action-list, that is, TRACE ENTRY [ ] .

If a conditional expression is specified, each time an entry point is reached, the value of the expression is evaluated, and if it is true, the message is printed; if it is false, no message is printed.

Example

In the following example, entry tracing is turned on and program execution is continued.

CodeWatch> TRACE ENTRY
CodeWatch> C
Input maximum prime boundary: 10
**** PRIMES.READ_INPUT\%EXIT
Break at PRIMES\119
  • Animating the Program in the Source Window
Parent topic: CodeWatch Commands
Related information
Continue
Ltrace
Ntrace
Trace Statement


Animating the Program in the Source Window

In the graphical interface, the TRACE ENTRY command is especially useful because it allows you to watch your code execute. Rather than simply issuing a message as entry and exit points are reached, CodeWatch updates the Source window with the source file for the current environment and highlights the line corresponding to each entry or exit point.

Parent topic: Trace Entry


Trace Statement

Use

Displays each source statement as it is executed.

Command Syntax

TRACE STATEMENT

Description

The TRACE STATEMENT command sets tracepoints, which enable the tracing of every statement by printing a message identifying the statement.

At each statement, if there is no other action to be performed (that is, if there is no breakpoint, entry trace, single step action, and so on), the identifying message is printed and execution continues.

Example

In the following example, statement tracing is turned on and program execution is continued.

CodeWatch> TRACE STATEMENT
CodeWatch> CONTINUE
**** PRIMES\112
**** PRIMES\113
Break at PRIMES\114
  • Animating the Program in the Source Window
Parent topic: CodeWatch Commands
Related information
Continue
Ltrace
Ntrace
Trace Entry


Animating the Program in the Source Window

In the graphical interface, the Trace Statement command is especially useful because it allows you to watch your code execute. Rather than simply issuing a message as statements are reached, CodeWatch updates the Source window with the source file for the current environment and highlights each line as it executes.

Parent topic: Trace Statement


Type

Use

Displays the resultant type of an expression.

Command Syntax

TYPE [/FULL] expression

where:

expression
Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables

Description

The TYPE command prints the resultant type of an expression.

If the expression refers to a structure or record, the Full option can be used to display the entire structure or record.

Example

In the following example, declaration information about various data items is displayed.

CodeWatch> TYPE COUNT
COUNT fixed binary (31) automatic
CodeWatch> TY FLAGS
FLAGS(1:1000) bit (1) automatic
Parent topic: CodeWatch Commands


Watch

Use

Sets watchpoints on specified variables.

Command Syntax

WATCH variable
      [/SILENT|/NSILENT]
      [/IGNORE|/NIGNORE]
      [/SKIP=n]
      [/ACTION[action-list]
      [/IF{logical-expr}]

where:

variable
Specifies the variable to be watched
n
Is the value you assign to the skip counter
action-list
Specifies a set of one or more CodeWatch commands separated by semicolons
logical-expr
Can be any expression that may occur in the source language program, including references to simple as well as aggregate (such as array, record, and structure elements) type variables, returning a boolean value

Description

Watchpoints are used to monitor any changes to data. The WATCH command designates the given variable to be watched. When the contents of the watched variable change, program execution stops and control is returned to the debugger.

Restrictions

  • The Watch variable cannot be a NONCONNECTED array reference.
  • The Watch variable cannot be a multi-dimensional array with array slices.
  • If the Watch variable is BASED, and its memory was allocated via ALLOCATE and subsequently freed via FREE, the watchpoint must be manually removed via the NWATCH command (cwcmd) or via the applicable UI method; otherwise, CodeWatch will continue to monitor the freed memory location.
  • Suppressing the Watchpoint Message
  • Temporarily Ignoring Watchpoints
  • Skipping a Watchpoint Multiple Times
  • Watchpoints with Action Lists
  • Conditional Watchpoints
  • Incurring Watchpoints
Parent topic: CodeWatch Commands


Suppressing the Watchpoint Message

The Silent option will not output modified variables when a watchpoint is encountered; the output simply reports that the program has stopped because of a watchpoint. Turning off the Silent option allows the debugger to output the modified variable, the location of the change, and the old and new values of the watched variable.

Parent topic: Watch


Temporarily Ignoring Watchpoints

The Ignore option allows the debugger to disregard a watched variable. In other words, when the given watchpoint is encountered, it will not be reported and the program will continue without interruption. Turning off the Ignore option allows the debugger to recognize and report any occurrence of the given watchpoint.

Parent topic: Watch


Skipping a Watchpoint Multiple Times

A watchpoint counter is associated with each watchpoint. When the watchpoint is created, the counter is set to zero; each time the watchpoint is incurred, the counter is incremented by one. When a program is reloaded, all counters are set to zero.

The Skip option assigns a watchpoint skip counter to the given variable, which is set to the value you specify. As a result, the watchpoint will be skipped the specified number of times. Once the watchpoint skip counter is set, it remains in effect until the value decreases (resets) to zero.

Parent topic: Watch


Watchpoints with Action Lists

An action-list is one or more debugger commands separated by a semicolon, which may specify that program execution is to continue. Any specified action-list is executed when a watchpoint is incurred.

Note:

It is not necessary to enclose the action list for the Watch dialog in square brackets (as is necessary for the command syntax).

Parent topic: Watch


Conditional Watchpoints

A conditional expression may be used to qualify the watchpoint; it must be the last option on the command line. When a watchpoint with the If option is set, the executing program will be suspended and the debugger will be activated whenever the watched variable is changed. The IF condition is then evaluated. The evaluation always takes place in the environment and language of the program statement. If the IF condition is false, program execution continues and the watchpoint is never reported. If the IF condition is true, the debugger incurs a watchpoint as usual.

Parent topic: Watch


Incurring Watchpoints

Description

A watchpoint is incurred when a watched variable has changed, the skip counter is either zero or not specified, and the Ignore option is not specified. When a watchpoint is encountered, the following occurs:

  • If an IF condition is specified, it is evaluated.
  • The watchpoint counter is incremented.
  • If the Ignore option is set for the given watchpoint, execution continues.
  • If the skip count for this watchpoint is non-zero, the count is decremented and execution is continued; the skip count for an ignored watchpoint is not affected.
  • The debugger announces the occurrence of the watchpoint. Output from the WATCH command includes the block name, the activation number, the line number where the change occurred, and the new and old hexadecimal values of the variable.
  • If an action-list is specified, it is executed.
  • The debugger prompt appears on the screen.

Example

In the following example, a watchpoint is set on variable n with an action-list to continue program execution. The value of n is input from the user.

CodeWatch> WATCH n /ACTION [C]
CodeWatch> CONTINUE

Input maximum prime boundary: 10
Program Stopped due to a Watchpoint
Watched variable N modified about line PRIMES\118
New Value: 10 {fixed binary (31)}
Break at PRIME\119
Parent topic: Watch
Related reference
Lwatch
Nwatch
Read
Save


Where

Use

Displays either the current execution point or the location of a specified statement.

Command Syntax

WHERE [statement-id]

where:

statement-id
Is a statement label or a source line number

Description

The WHERE command prints a location as the name of a routine followed by a statement label.

If the statement identifier is a statement label, the name of the routine containing the label and the source line number of the label are printed. If the statement identifier is a source line number, the name of the routine is printed. If the statement identifier argument is omitted, the name of the routine and the line number of the current execution point are printed.

Example

In the following example, the next executable statement is located and the location is displayed.

CodeWatch> WHERE 108
Line 108 is not an executable statement ...
WHERE using statement PRIMES\112 instead.
PRIMES\112

In this example, the current execution point is displayed.

CodeWatch> WHERE
Current execution point is PRIMES.READ_INPUT\%ENTRY
Parent topic: CodeWatch Commands
Related information
Lenvironment
Point


!

Use

Invokes the host operating system command interpreter to perform a specified command.

Command Syntax

! command
(Press <Return> to continue)

Description

The ! command invokes the command interpreter to read the remainder of the line following the ! command.

The ! command followed by the UNIX sh command pushes to a new command interpreter in UNIX. To return to the debugger, type <Ctrl D> or exit.

Example

In this example, the UNIX pwd command is invoked, which lists the current working directory.

CodeWatch> !pwd
/usr/hicks/pllprogs
Parent topic: CodeWatch Commands


Debugging Open PL/I Programs

  • Program Blocks
  • Built-in Function Support
  • Referencing Arrays and Aggregate Structures
  • Debugging PL/I Programs Under CICS
    Describes how to use the CICS preprocessor to activate debugging for a PL/I program run under CICS.
  • Debugging PL/I Programs Containing Macro Code
  • Support for Open PL/I Include Files
  • Sample CodeWatch Session Using Open PL/I
  • Program Listing
Parent topic: CodeWatch User's Guide


Program Blocks

Program blocks are units of code that provide scope and context for the debugger. An Open PL/I program block is a procedure block or a BEGIN block.

  • Block Names
  • Referencing Nested Blocks
Parent topic: Debugging Open PL/I Programs


Block Names

A procedure block is referred to by the name of that procedure. A begin block is referred to by its label (if present) or by the string %BEGIN followed immediately by the line number on which the block begins. For example, an unlabeled begin block that starts on line 119 of the source file is referred to as %BEGIN119.

Parent topic: Program Blocks


Referencing Nested Blocks

Open PL/I program blocks may be nested. Rules for naming nested blocks are as follows:

  1. If a block defined within the compilation unit is contained within or contains the debugger's current evaluation environment, the block may be referred to simply by its name. The name may need to be qualified to make it unique within the external procedure.

    If the block contains the debugger's current evaluation environment, the search for the referenced block begins from the current environment and continues through each successive containing (parent) block until the referenced block is found.

  2. If a block is in some other external procedure, it must be qualified with at least the external procedure name, and it may require further qualification. Furthermore, a fully qualified name to a block in some other external procedure may be the same as a partially qualified block name in the current procedure. To force the debugger to search outside the current procedure, qualify the block name with %EXTERN. (This is seldom necessary if ambiguous naming is avoided.)

    For example:

    A: proc;        /* 1 */        B: proc;             /* 8 */
  B: proc;      /* 2 */          C: proc;           /* 9 */
    C: proc;    /* 3 */            D: proc;         /* 10 */
      D: proc;  /* 4 */            end D;
      end D;                     end C;
    end C;                         B: proc;         /* 11 */
  end B;                             A: proc;       /* 12 */
  C: proc:      /* 5 */                A: proc      /* 13 */
    B: proc;    /* 6 */                  B: proc;   /* 14 */
      C:proc;   /* 7 */                  end B;
      end C;                           end A;
    end B;                           end A;
  end C;                           end B;
end A;                          end B;

The following describes how each block can be referenced given the current evaluation environment in the external procedure %EXTERN.A (block 1).

Block
 | Reference
1 | A or %EXTERN.A
2 | A.B, B, or %EXTERN.A.B
3 | B.C, A.B.C, or %EXTERN.A.B.C.
4 | D, C.D, B.C.D, A.B.C.D, %EXTERN.A.B.C.D, B.D, A.B.D, %EXTERN.A.B.D, A.D, or %EXTERN.A.D
5 | C, A.C, or %EXTERN.A.C
6 | C.B, A.C.B, or %EXTERN.A.C.B
7 | C.C, C.B.C, A.C.C, %EXTERN.A.C.C, A.C.B.C, or %EXTERN.A.C.B.C
8 | %EXTERN.B
9 | %EXTERN.B.C
10 | %EXTERN.B.D, or %EXTERN.B.C.D
11 | B.B or %EXTERN.B.B
12 | B.B.A or %EXTERN.B.B.A
13 | B.A.AB.B.A.A, %EXTERN.B.A.A, or %EXTERN.B.B.A.A
14 | B.B.B B.A.B B.A.A.B, B.B.A.B, %EXTERN.B.B.B, %EXTERN.B.A.B, %EXTERN.B.A.A.B, %EXTERN.B.B.A.B, or%EXTERN.B.B.A.A.B

If the current evaluation environment is in the internal procedure block %EXTERN.A.B.C.D (block 4), the following is true in the debugger:

B | refers to block 2
B.C | refers to block 3
C | refers to block 3
%EXTERN.B.A | is an ambiguous reference (block 12 or 13)
%EXTERN.B.B.A | refers to block 12
%EXTERN.B.C | refers to block 9

If the current evaluation environment is in the external procedure block %EXTERN.B (block 8), the following is true in the debugger:

A.B.C.D | refers to block 1
A | is an ambiguous reference (block 12 or 13)
B | refers to block 11
B.A | refers to block 12
A.B | refers to block 14
B.A.B | refers to block 14
Parent topic: Program Blocks


Built-in Function Support

The following PL/I built-in functions are supported by CodeWatch:

ADD | COPY | LENGTH | SEARCH
ADDR | DECIMAL | LOW | SEARCHR
ADDRDATA | DIMENSION | LOWERCASE | STORAGE
BINARY | FIXED | MAXLENGTH | SUBSTR
BINARYVALUE | FLOAT | MULTIPLY | TALLY
BIT | HBOUND | NULL | TRIM
BYTE | HEX | PACKAGENAME | UPPERCASE
CENTER | HEXIMAGE | POINTERVALUE | UNSPEC
CENTERLEFT | HIGH | RANK | VERIFY
CHARACTER | LBOUND | REVERSE |
COLLATE | LEFT | RIGHT |

The following abbreviations for PL/I built-in functions are recognized:

  • BIN for BINARY
  • BINVALUE for BINARYVALUE
  • CHAR for CHARACTER
  • DEC for DECIMAL
  • DIM for DIMENSION
  • PTRVALUE for POINTERVALUE
  • STG for STORAGE
Parent topic: Debugging Open PL/I Programs


Referencing Arrays and Aggregate Structures

Arrays and aggregate structures can be referenced in their entirety by referring to them by their array or structure name, or individual subfields or members can be referenced using the conventional PL/I syntax, as in REC_NAME.FIELD. A subfield can be referenced directly as long as its name is unique.

A specified range of an array can be evaluated using the following command-line syntax:

EVALUATE array-name [m:n]

or

EVALUATE array-name (m:n)

where m is the starting point of the array range and n is the ending point of the array range.

An asterisk (*) specifies that all elements of a dimension are to be evaluated. For example:

EVALUATE array-name[*,3:5]

or

EVALUATE array-name(*,3:5)

displays the third through fifth columns of all the rows in a two-dimensional array.

Specifying only the array name for PL/I will cause the evaluation of every element of every dimension of the array. Similarly, specifying a structure, record, or group name will cause the evaluation of every member of the group.

Parent topic: Debugging Open PL/I Programs


Debugging PL/I Programs Under CICS

You can use CodeWatch to debug PL/I programs running under CICS, either by calling the PLITEST built-in subroutine directly or by using the CICS preprocessor to call the PLITEST.

Use the -optexec option with the plitest parameter to allow the CICS preprocessor to insert the call. When using this method, specify values for the CODEWATCH_SRCPATH and CODEWATCH_STBPATH environment variables, to match the locations for the appropriate program source and debug files. See PLITEST Subroutine for more information on using PLITEST to start CodeWatch. See the -optexec option in Compiler Options for more information on -optexec.

Parent topic: Debugging Open PL/I Programs
Related reference
PLITEST Subroutine
Compiler Options


Debugging PL/I Programs Containing Macro Code

Most users of simple PL/I macros prefer to debug a macro as if it were executable code within the original source, even though it can generate 0-n lines of underlying PL/I statements. To address this, CodeWatch provides a WYSIWYD (What You See Is What You Debug) experience where a single step executes all of the lines of generated macro code as if it were a single PL/I statement. You can query variable values before and after execution, as if a single line of code has been executed. However, due to the nature of the PL/I macro language where a single macro can generate a small portion of an executable line, an entire line, or multiple lines, CodeWatch can not always provide that experience. In those cases you can use the techniques discussed in Debugging Internal Macro Code for a PL/I Program to facilitate your debugging.

By default, CodeWatch does not debug macro code within PL/I programs. When debugging a PL/I program with macro code, the debugger simply debugs through the lines that contain macro calls.

Consider this code sample, which contains multiple macro calls.

DEMO: PROC OPTIONS(MAIN);

  dcl x fixed bin(31) init(0);

%DCL $PGMSG ENTRY;
%$PGMSG: PROC (PGM) STATEMENT RETURNS (CHAR);
  DCL  PGM    CHAR;
  DCL  MSG    CHAR;
  DCL  SPACES CHAR;
  /*  Uncomment following 2 lines to recreate RPI 1087809 */

  SPACES = '
           ';

  msg =
  '  DO; '   || spaces ||
  '    /* Tracing Block for: ' || pgm ||  ' */'         || spaces ||
  '    put skip list("Pre Execution: ' || pgm || '");'  || spaces ||
  '    call ' || pgm || '(x);'                          || spaces ||
  '    put skip list("Complete: ' || pgm || '"); '      || spaces ||
  '    put skip; '                                      || spaces ||
  '  END; ';

   RETURN ( msg );
%END $PGMSG;

   x = x + 1; x = x + 2;

   $PGMSG(ADD10);
   $PGMSG(ADD20);

   x = x + 3;

   $PGMSG(SUBTRACT30);
   put skip data(x);

   $PGMSG(ADD10);

   put skip data(x);

   /**********************************/
   /*  Start of Internal Procedures  */
   /**********************************/

   /**********************/
     add10: proc(x);
   /**********************/
       dcl x fixed bin(31);
       put skip list('add10:  adding 10 to x');
       x = x + 10;
       put skip list('add10 (complete):  ' || x);

     end add10;

   /**********************/
     add20: proc(x);
   /**********************/
       dcl x fixed bin(31);
       put skip list('add20:  adding 20 to x');
       x = x + 20;
       put skip list('add20 (complete):  ' || x);

     end add20;

   /**********************/
     subtract30: proc(x);
   /**********************/
       dcl x fixed bin(31);
       put skip list('subtract30:  subtracting 30 from x');
       x = x - 30;
       put skip list('subtract30 (complete):  ' || x);

     end subtract30;

 END DEMO;

If during debugging, you are at the second statement in the line that precedes the two macro call lines:

x = x + 1; x = x + 2;

Pressing F10 to step debugs through the lines with the macro calls to the next statement in the code:

When CodeWatch debugs through macro code in your PL/I programs, the lines containing the macro calls execute without any debugging on the top level macro code. The output in the Terminal window shows values were derived and statements executed, indicating that the macro calls are executed without the code being debugged.

When program code containing macros also contains a CALL statement, you can debug the CALL statement code. To do this, place a breakpoint on the first line of code that executes for the statement. Press F10 to step to the breakpoint. Any variable values or other values appear in the CodeWatch window.

For example, the code sample above contains a call to (x): which is a call to subtract 30 from x. If you place a breakpoint at this line in the code sample:

put skip list('subtract30:  subtracting 30 from x');

Pressing F10 to step into the line lets you see the variable values and other output, but does not let you view code at the top level of the macro. See Debugging Internal Macro Code for a PL/I Program for information on debugging inside of a macro.

  • Debugging Internal Macro Code for a PL/I Program
Parent topic: Debugging Open PL/I Programs


Debugging Internal Macro Code for a PL/I Program

If you are serious user of PL/I macro language or maintaining a program that uses of macros extensively to generate code, you may be required to debug at the level of the generated source, just as you may for EXEC CICS, EXEC DLI, or EXEC SQL. In these instances, use these techniques to step through every line of generated code, examining and changing variable values to understand what is happening in your program. This is particularly useful for discovering macro behavior that you do not understand or expect. By debugging at the generated code level, you can work out exactly what is happening.

Code that is actually present in the macro code is not part of PL/I source file. However, the macro code is available in the preprocessed file. To debug code that is actually present in the in the macro you must debug the preprocessed file.

You can create a preprocessed output file for the source file you are debugging and debug the output file. To do this, you must:

  • Set the -nodebuginfo compiler option set for the project.
  • Enable Macro preprocessor output for the project.

To set the -nodebuginfo compiler option for the project

  1. In Visual Studio, open the solution containing the project you want to debug.
  2. Right-click the desired project in the Solution Explorer and choose Properties. The Properties window appears.
  3. Click the Compile tab.
  4. In the Other options field, enter -nodebuginfo.
  5. Click Save in the toolbar to save the updates to the project.
  1. Open the solution containing the project you want to debug.
  2. In the Application Explorer view, right-click on the project and choose Micro Focus > Project Settings > PL/I Compile Settings > Macro Preprocessor. The Macro Preprocessor page appears in the Properties Window.
  3. Select the Use Macro Preprocessor check box if it is not selected.
  4. In the No debug information (-nodebuginfo) field, select Yes from the Value list.
  5. Click OK to save your changes.
  6. Rebuild the project. This creates the output file used to debug the macro code.

To enable Macro preprocessor output for a project

Use this procedure to create the output file for the source file you want to debug. Preprocessor output files have a .pp file extension.

  1. Click the Pre-Processors tab.
  2. Under the Preprocessor (Macro) group, set the value for Macro preprocessor output to Yes.
  1. Open the solution containing the project you want to debug.
  2. In the Application Explorer view, right-click on the project and choose Micro Focus > Project Settings > PL/I Compile Settings > Macro Preprocessor. The Macro Preprocessor page appears in the Properties Window.
  3. Under Common macro preprocessor options > Additional options, enter -pp outputfile, where outputfile is a name you specify for the output file.

    If you do not specify an output file, the input filename is used. See the help topic Macro Preprocessor options for more information.

  4. Click OK to save your changes.
  5. Rebuild the project. This creates the output file used to debug the macro code.

Once an output file is created. Pressing F10 to debug step into the code debugs the preprocessor file. The CodeWatch debugging window shows the preprocessor file as the source being debugged. This output file contains the infused macro code.

For example, for a program file that contains a statement with macro calls:

    x = x + 1; x = x + 2;

    $PGMSG(ADD10);
    $PGMSG(ADD20);

The output file includes the infused code for the macro calls.

    x = x + 1; x = x + 2;

      DO;
              /* Tracing Block for: ADD10 */
              put skip list (PreExecution: ADD10");
              call ADD10(x);
              put skip list (Complete: ADD10");
              put skip;
            END;
      DO;
              /* Tracing Block for: ADD20 */
              put skip list (PreExecution: ADD20");
              call ADD20(x);
              put skip list (Complete: ADD20");
              put skip;
            END;

You can step into this code and debug it as you would with any other code.

Parent topic: Debugging PL/I Programs Containing Macro Code


Support for Open PL/I Include Files

The following list describes the rules applying to CodeWatch support for Open PL/I include files. This support applies to include files that contain executable code. The rules are as follows:

  • Stepping into an include file, for example, when the next statement is a %INCLUDE directive, will cause the screen display to switch to the specified include file.
  • Commands that deal with the source file, such as PRINT and POINT, work as expected when using the current include file.
  • Stepping through an include file is allowed.
  • Setting breakpoints within an include file is NOT allowed. The setting of a breakpoint unambiguously refers to the original containing source file.
  • Stepping over an include file, for example, when the next statement is a %INCLUDE directive, is not explicitly allowed. This may may be accomplished by setting a breakpoint in the containing source file followed by the CONTINUE command.
  • Stepping out of an include file before its last statement is accomplished similarly to stepping over, that is, by setting a breakpoint in the containing source file followed by the CONTINUE command.
  • Using CodeWatch with the Open PL/I Macro Preprocessor
Parent topic: Debugging Open PL/I Programs


Using CodeWatch with the Open PL/I Macro Preprocessor

CodeWatch can be used with PL/I programs to which the Open PL/I macro preprocessor mfpp has been applied. CodeWatch uses the original source file (rather than the expanded preprocessed output of mfpp). Stepping through macros works similarly to the include file support described for include files.

Parent topic: Support for Open PL/I Include Files


Sample CodeWatch Session Using Open PL/I

This debugging session illustrates how to use the commands and features of CodeWatch when debugging programs compiled with Open PL/I. Following the session is the source listing of the sample PL/I program. The source file for this program is also available on the CodeWatch installation media.

The sample program, primes.pl1, calculates the number of prime numbers within a given range, but it doesn't do it very well. There is a bug somewhere that causes the program to print out too many values. Observe the following output:

*** Sieve of Eratosthenes ***

Input maximum prime boundary:
10
Number of primes found was     6
1      2      3      5      7      11

The program had been compiled using the -deb option to produce the necessary information for the debugger and the -l option to produce a listing file. It was then linked using Ipild. For example,

mfpli primes.pl1 -deb -l
ldpli primes.o -o primes

In this sample session, comments (which are not part of the session) are the bullet items. The system prompt is $. Note that user-supplied text is in bold typewriter font. For clarity, the abbreviated form of the command is used only after the command has been previously spelled out in its entirety.

  • Invoke CodeWatch at the system prompt.
    $ cwcmd primes

******************************************************************************
* CodeWatch, 08.00                                                           *
* ----------------                                                           *
* Copyright 2009 Micro Focus                                   *
******************************************************************************
Initial evaluation environment is PRIMES:(inactive)
  • Find the string "main".
    CodeWatch> FIND main
    3: primes: procedure options (main);
CodeWatch> FIND main
  109:    /* main procedure */
  • Print 20 lines.
    CodeWatch> PRINT 20
109       /* main procedure */
110
111       declare n fixed binary(31);
112
113       put skip;
114       put list (' *** Sieve of Eratosthenes ***');
115       put skip (2);
116
117       call read_input(n);
118
119       do while (n > 1);
120          call sift(n);
121          call read_input(n);
122       end;
123
124   end;
125   BOTTOM
  • The program calls read_input on line 117 to get user input, so set a break at line 119 to see if things are still working correctly.
    CodeWatch> BREAK 119
  • Continue to the breakpoint. The program will request input; enter 10.
    CodeWatch> CONTINUE

*** Sieve of Eratosthenes ***

Input maximum prime boundary:
10
Break at PRIMES\119
  • Print a line of text. Evaluate n, which is the variable read in on line 117.
    CodeWatch> P
  119: do while (n > 1);
CodeWatch> EVALUATE n
N = 10 {fixed binary (31)}
  • Access the declaration type of n.
    CodeWatch> TYPE n
N fixed binary (31) automatic
  • Everything seems to be fine. Set the default stepping action list to print one line and Step.
    CodeWatch> DSTEP [P]
CodeWatch> STEP
Step at PRIMES\120
  120:      call sift(n);
  • Step into sift and see what's happening there.
    CodeWatch> S IN
Step at PRIMES.SIFT\%ENTRY
   77: sift: procedure (n);
  • Use the ARGUMENTS command to see the arguments to this routine.
    CodeWatch> ARGUMENTS
N = 10 {fixed binary (31)}
  • Do a stack traceback.
    CodeWatch> STACK /ALL

Stack contains 7 frame(s).
Current execution point is PRIMES.SIFT\%ENTRY

7: Owner is "PRIMES.SIFT"
     In [ primes.exe ]
   Called from PRIMES\121
6: Owner is "PRIMES"
     In [ primes.exe ]
   Called from _lpi_main+0x71 (non-debug)
5: Owner is "_lpi_main"
     In [ primes.exe ]
   Called from _tmainCRTStartup+0x10f (non-debug)
4: Owner is "_tmainCRTStartup"
     In [ primes.exe ]
   Called from 0x750c339a
3: Owner is "0x750c339a"
     In [ C:\Windows\syswow64\kernel32.dll ]
   Called from 0x76f69ef2
2: Owner is "0x76f69ef2"
     In [ C:\Windows\syswow64\ntdll.dll ]
   Called from 0x76f69ec5
1: Owner is "0x76f69ec5"
  • To demonstrate statement tracing, set the source file pointer to line 98 and print five lines.
    CodeWatch> POINT 98
   98:         do while (k < n);
CodeWatch> P 5
   98:         do while (k < n);
   99:           /* cancel all multiples */
  100:           flags(k) = FALSE;
  101:           k = k + this_prime;
  102:         end;
  • Set a break at line 100, which will put you in the middle of this small loop. Continue.
    CodeWatch> B 100
CodeWatch> C
Break at PRIMES.SIFT\100
  • Set statement tracing and continue twice. Each statement is reported as it is executed.
    CodeWatch> TRACE STATEMENT
CodeWatch> C
**** PRIMES.SIFT\101
**** PRIMES.SIFT\102
**** PRIMES.SIFT\98
Break at PRIMES.SIFT\100
CodeWatch> C
**** PRIMES.SIFT\101
**** PRIMES.SIFT\102
**** PRIMES.SIFT\98
Break at PRIMES.SIFT\100
  • Set a macro "fig" to do FIND/IGNORE. This will be useful; by default, the FIND command is case-sensitive. The /IGNORE option ignores case.
    CodeWatch> MACRO fig=[FIND /IGNORE]
CodeWatch> fig PRINT_OUT
  105:    call print_out(primes,count);  /* should be count - 1 */
  • Break at line 105 (the call to print_out). Turn off statement tracing and delete the breakpoint at the current line (NBREAK with no parameter deletes the breakpoint at the current line). Continue to the call to print_out.
    CodeWatch> NBREAK
CodeWatch> B 105
CodeWatch> NTRACE S

CodeWatch> C
Break at PRIMES.SIFT\105
  • Evaluate count, which you are about to pass to print_out.
    CodeWatch> E count
COUNT = 6 {fixed binary (31)}
  • Six prime numbers are found. That's not right. Only five should have been found: 1, 2, 3, 5, and 7. Set a break at the entry point of sift, reload the program and continue execution (twice) to get back to the entry of sift. (Enter 10 again for input.)
    CodeWatch> B sift\%ENTRY
CodeWatch> RELOAD
Command line : "primes"
Reloading..ok
Initial evaluation environment is PRIMES:(inactive)
CodeWatch> C

*** Sieve of Eratosthenes ***

Input maximum prime boundary:
10
Break at PRIMES\119
CodeWatch> C
Break at PRIMES.SIFT\%ENTRY
  • Step once and print 15 lines.
    CodeWatch> S
Step at PRIMES.SIFT\85
   85:    do I = 1 to n;
CodeWatch> P 15
   85:    do I = 1 to n;
   86:      flags(I) = TRUE;
   87:    end;
   88:
   89:    count = 1;
   90:    primes(1) = 1;
   91:
   92:    do I = 1 to n;
   93:      if flags(I) = TRUE then do;
   94:        this_prime = I + 1;
   95:        count = count + 1;
   96:        primes(count) = this_prime;
   97:        k = I + this_prime;
   98:        do while (k < n);
   99:          /* cancel all multiples */
  • Set a break at line 95. This is a conditional breakpoint with an ELSE action list. The debugger will not break at line 95 unless count > 4. It will instead evaluate count and continue on. Continue.
    CodeWatch> B 95 /IF {count > 4} /ELSE [E count]
CodeWatch> C
COUNT = 1 {fixed binary (31)}
COUNT = 2 {fixed binary (31)}
COUNT = 3 {fixed binary (31)}
COUNT = 4 {fixed binary (31)}
Break at PRIMES.SIFT\95
Break at PRIMES.SIFT\105
  • Delete this breakpoint. Print one line.
    CodeWatch> NB
CodeWatch> P
Break at PRIMES.SIFT\105
 105: call print_out(primes,count); /* should be count - 1 */
  • Back at the call to print_out. Evaluate count. Assign count-1 to count and continue. (Enter 10 again for input.)
    CodeWatch> E count
COUNT 6 {fixed binary (31)}
CodeWatch> LET count=count-1
CodeWatch> C
Number of primes found was            (prime itself)    5

1      2      3      5      7

Input maximum prime boundary:
10
Break at PRIMES\119
  • This appears to be the solution. Reload the program and delete all breakpoints.
    CodeWatch> RE
Command line : "primes"
Reloading..ok
Initial evaluation environment is PRIMES:(inactive)
CodeWatch> NBREAK /ALL
  • You can do a run-time patch to the program, without even exiting the debugger. This is a temporary fix to see what source changes you may need to make. This breakpoint will not report itself (/SILENT); it will simply execute its action list and continue. Continue program execution. Try 10 and 100 for user input. Exit the program by entering 0.
    CodeWatch> B 105 /SILENT [LET count=count-1;C]
CodeWatch> C

*** Sieve of Eratosthenes ***

Input maximum prime boundary:
10
Number of primes found was      (prime itself)     5

1      2      3      5      7

Input maximum prime boundary:
100
Number of primes found was   26
1      2      3      5      7      11     13     17     19     23
29     31     37     41     43     47     53     59     61     67
71     73     79     83     89     97

Input maximum prime boundary:
0
Program exited with status 0
Reloading..ok
Initial evaluation environment is PRIMES:(inactive)
  • So now you know that if you change line 105 of primes. pl1 from:
    call print_out(primes,count);

    to:

    call print_out(primes,count-1);

    the program will work just fine! Quit out of the debugger session.

    CodeWatch> QUIT
CodeWatch Quit...Bye!
Parent topic: Debugging Open PL/I Programs


Program Listing

Compiler:  Open PL/I 08.00.B2 - Copyright (c) 2009 Micro Focus (IP) Limited
Date/Time: December 11, 2009 (15:35:27)
File:      primes.pl1
Directory: C:\Program Files\Micro Focus\Open PLI 8.0\EXAMPLES\OPEN-PLI
Options:   deb l noopt Pentium obj primes.obj list primes.lst
       1   /* Sieve of Eratosthenes: Copyright (c) 2009 Micro Focus (IP) Limited */
       2
       3   primes: procedure options (main);
       4
       5   %replace FALSE      by '0'B;
       6   %replace TRUE       by '1'B;
       7
       8   %replace MAX_VALUE  by 1000;
       9   %replace MAX_PRIMES by  500;
      10
      11
      12   read_input: procedure (maxv);
      13
      14       declare maxv fixed binary(31);
      15       declare instring char(4) varying;
      16
      17       declare ok bit(1);
      18
      19       ok = FALSE;
      20
      21       do while (^ok);
      22           put list ('Input maximum prime boundary:');
      23           put skip;
      24           get list (instring);
      25           maxv = decimal(instring);
      26           if maxv > MAX_VALUE then do;
      27               put list ('Value too big.  Try again.');
      28               put skip;
      29           end;
      30           else do;
      31               ok = TRUE;
      32           end;
      33       end;
      34
      35   end read_input;
      36
      37   isprime: procedure (number,values,total) returns (fixed binary(31));
      38
      39       declare number                fixed binary(31),
      40                   values(1:MAX_PRIMES)  fixed binary(31),
      41           total                 fixed binary(31);
      42       declare n                     fixed binary(31);
      43
      44           do n = 1 to total;
      45           if number = values(n) then
      46                  return (number);
      47           end;
      48
      49           return(-1);
      50
      51   end isprime;
      52
      53   print_out: procedure (values,total);
      54
      55       declare values(1:MAX_PRIMES) fixed binary(31),
      56           total                fixed binary(31);
      57
      58       declare i fixed binary(15);
      59
      60       put list ('Number of primes found was');
      61       if isprime (total,values,total) >= 0 then
      62           put list(' (prime itself)');
      63       put edit (total) (F(4));
      64       put skip (2);
      65
      66       do i = 1 to total;
      67           put edit (values(i)) (F(7));
      68           if mod(i,10) = 0 then do;
      69               put skip;
      70           end;
      71       end;
      72
      73       put skip (2);
      74
      75   end print_out;
      76
      77   sift: procedure (n);
      78
      79       declare n fixed binary(31);
      80
      81       declare (i, k, count, this_prime) fixed binary(31),
      82           flags(1:MAX_VALUE) bit(1),
      83           primes(1:MAX_PRIMES) fixed binary(31);
      84
      85       do i = 1 to n;
      86           flags(i) = TRUE;
      87       end;
      88
      89       count = 1;
      90       primes(1) = 1;
      91
      92       do i = 1 to n;
      93           if flags(i) = TRUE then do;
      94               this_prime = i + 1;
      95               count = count + 1;
      96               primes(count) = this_prime;
      97               k = i + this_prime;
      98               do while (k < n);
      99                   /* cancel all multiples */
     100                   flags(k) = FALSE;
     101                   k = k + this_prime;
     102               end;
     103           end;
     104       end;
     105       call print_out(primes,count);  /* should be count - 1 */
     106
     107   end sift;
     108
     109       /* main procedure */
     110
     111       declare n fixed binary(31);
     112
     113       put skip;
     114       put list ('*** Sieve of Eratosthenes ***');
     115       put skip (2);
     116
     117       call read_input(n);
     118
     119       do while (n > 1);
     120           call sift(n);
     121           call read_input(n);
     122       end;
     123
     124   end;
Parent topic: Debugging Open PL/I Programs


Troubleshooting

  • Issues with Displaying Text in CodeWatch
Parent topic: CodeWatch User's Guide


Issues with Displaying Text in CodeWatch

You may encounter issues with the text not displaying properly or disappearing if you hover the CodeWatch menus with your mouse, especially on virtual machines.

Figure 1. Text disappearing from the menu bar

Figure 2. Text disappearing from the context menu

To fix such issues:

  1. Ensure there is only one version of JVM installed on the machine.
  2. Set the following environment variable in the Windows System properties (navigate to Control Panel > System > Advanced System Settings and click Environment Variables):
    • Variable Name: J2D_D3D
    • Variable Value: FALSE
  3. Reboot the machine.
Parent topic: Troubleshooting


Open PL/I User's Guide

This book shows you how to operate Micro Focus's Open PL/I application.

  • Using Open PL/I
    This chapter explains how to install the Open PL/I Compiler and how to enter, compile, link, and run Open PL/I programs.
  • Language Concepts
    This chapter describes the Open PL/I language implementation for your system. For detailed information on the Open PL/I programming language, see your Open PL/I Language Reference Manual.
  • Open PL/I SQL Options
    This chapter describes the SQL Options available with Open PL/I. These include the DB2 SQL Option that provides support for IBM's DB2 on UNIX.
  • Open PL/I Compiler Diagnostic Messages
    This appendix describes the format of Open PL/I compiler diagnostic messages and their levels.
  • Open PL/I Run-time Error Messages
    This appendix contains information on Open PL/I run-time errors, UNIX system error codes, and Open File Manager (OFM) error codes. Run-time errors are detected by the Open PL/I run-time system, or by the operating system.
  • Value Table for ONCODE Built-in Function
    You may use the ONCODE built-in function in any unit to determine the nature of the error condition that caused invocation of that ON-unit. This appendix lists the values returned by the ONCODE built-in function and the errors or conditions corresponding to each value.
  • National Locale Support
  • Character Sets
    This appendix provides you with the ASCII equivalents of EBCDIC characters.
  • Environment Variables
  • Migration to Micro Focus File Formats
Parent topic: PL/I Programming


Using Open PL/I

  • Compiling a Program
  • Linking a Program
  • Running a Program
  • Program Debugging
  • Using Open PL/I with Other Software Products
  • Using the PL/I Message User Exit
  • Linking an Open PL/I Application Using Separate Shared Objects for Each Subroutine
  • Compiling, Linking and Debugging of Fetchable Procedures
  • Data File Tools Support for PL/I
    Describes the Data File Tools support for PL/I programs.
  • EXEC DLI Support in PL/I
    Describes EXEC DLI support in PL/I.
  • Calling PL/I subroutines from a COBOL Application
  • Test Coverage
Parent topic: Open PL/I User's Guide


Compiling a Program

Attention: You must recompile and relink your Open PL/I applications to use them with this Enterprise Developer release.

Open PL/I consists of the following executable programs:

  • The Open PL/I Macro Preprocessor, named mfpp
  • An Include Preprocessor, named mfinclpp
  • A CICS Preprocessor
  • An HCO for DB2 LUW Preprocessor
  • A DL/I Preprocessor
  • An OpenESQL Preprocessor
  • A DB2 Preprocessor, named mfdb2 (deprecated)
  • The Compiler itself, named mfpli
  • A command-line driver that allows compiling and linking in one step, named mfplx

Note that in the names mfpli and mfplx the fourth character is the lowercase of the letter "L".

mfpp is executed prior to the compilation, and its output is passed to the Open PL/I Compiler.

You can run mfpp directly, but the recommended way to run it is by use of the -macro option with mfplx when you are compiling your program. This allows the mfpp output to be automatically directed to the Compiler.

mfpli allows only one filename, accepts only Open PL/I Compiler options, and requires a separate ldpli step. The suffix of the filename to be compiled by mfpli is not restricted.

mfplx allows multiple filenames and accepts mfpli options as well as many standard UNIX or Windows system compiler and linker options, such as -c and -o. The -c option specifies compilation without linking. When -c is used, the -o option is passed to the compiler; when -c is not used, -o is passed to ldpli. Note that some file name suffixes are restricted to .pl1 or .pli when using mfplx.

The Include Preprocessor processes selected or default "include" statements and produces a deck that can then be treated as a single source file by another preprocessor or the Open PL/I Compiler. It is normally run under control of mfplx and is always run as the first preprocessor. Its output becomes the input to the next preprocessor or the Open PL/I Compiler.

Note: The best way to determine the command needed to invoke this preprocessor directly is to use the -# option on the mfplx command and use the command it would have used. For example:
mfplx -# -incl myprog.pli –isuffix .inc –path e:\source\include –ppincl myprog.out –optincl sp

The CICS preprocessor converts EXEC statements into native PL/I code that is then possibly further macro processed and then finally compiled and linked.

The OpenESQL and DB2 preprocessors process SQL statements before the compilation.

See the following sections for descriptions of the syntax to invoke mfpp, mfpli, or mfplx.

  • Compiling in 64-Bit Mode
  • mfpp Syntax
  • mfpli Syntax
  • mfplx Syntax
  • Preprocessor Order of Execution
  • mfplx Options
  • Include Preprocessor Options
  • Macro Preprocessor Options
  • CICS Preprocessor Options
  • HCO for DB2 LUW Preprocessor Options
  • DB2 Preprocessor Options (deprecated)
  • Compiler Options
  • Compiler Listings
  • Open PL/I Compiler Implementation Limits
  • Open PL/I Compiler restrictions
    Describes permanent restrictions of the Open PL/I compiler
  • Compilation Statistics
  • Temporary Files
  • Optimization
Parent topic: Using Open PL/I


Compiling in 64-Bit Mode

On x64 Windows, when you open Start > All Programs > Micro Focus Enterprise Developer > Tools > Enterprise Developer Command Prompt (64-bit), the compiler and debugger that will be running in the background will be 64-bit and the output application will be 64-bit too.

On UNIX, you need to set 64-bit mode using the COBMODE environment variable. For more information, see Environment variables in alphabetical order.
Note: The following 64-bit UNIX platforms are supported: Solaris (SPARC), Red Hat Linux (Intel), SUSE Linux (Intel). AIX, HP-UX Itanium and z/Linux are not currently supported.
Restriction:
  • -coffdebug compiler option is not supported on 64-bit Windows.
  • The deprecated mfdb2 preprocessor is not available on 64-bit Windows. Please use the EXEC preprocessor (invoked by -sql db2).
Parent topic: Compiling a Program


mfpp Syntax

The valid format for the mfpp command is:

mfpp [–ipath dir][-{isuffix|x} suffix] [–pp outfile]infile

where dir is a directory name, suffix defines a string to be appended to any unquoted filename in a %INCLUDE statement, infile specifies a source filename, and outfile specifies an output filename. At least one input file must be specified.

The preprocessor input is a file containing an Open PL/I source module, possibly including Open PL/I Macro Preprocessor statements. The preprocessor output is an Open PL/I source module containing no further preprocessor statements, but with the source code modified according to the semantics of the preprocessor statements that were encountered in the input file.

mfpp is usually run by use of the -macro option with mfplx.

Parent topic: Compiling a Program
Related information
Macro Preprocessor Options


mfpli Syntax

The valid format for the mfpli command is:

mfpli [option] ... file [option]...

where option represents a Compiler option and file represents any single specified source file. There is no restriction on the suffix of the filename. option arguments can go either before or after file. (An error may result if the -I or -o option appears before file without specifying a list filename or object filename.)

Parent topic: Compiling a Program


mfplx Syntax

The valid format for the mfplx command is:

 mfplx {option | source_file | object_file} ...

where option represents an Open PL/I Compiler option or a system Compiler or linker option.

source_file represents any specified source file. Files with a .pl1 or .pli suffix are passed to mfpli. On UNIX systems, files with an .s suffix are passed to the system assembler. On Windows systems, files with an .asm suffix are passed to the system assembler.

mfplx supports wildcard characters and indirect files (@files).

object_file represents any specified object file (with an .o suffix for UNIX systems or a .obj suffix for Windows systems) or any specified library (with an .a suffix for UNIX systems or an .lib suffix for Windows systems). Files with an .o (or .obj) or an .a (or .lib) suffix are passed to mfpli, as are specified files with unknown or absent suffixes. The command line that mfpli constructs for each of these invocations is limited to 4096 characters. The .o files can be linked (possibly with other object files and/or libraries) using ldpli or mfplx -o.

mfplx processes options in one of the following ways:

  • Passes the option to the preprocessor (mfpp).
  • Passes the option to the compiler (mfpli).
  • Passes the option to the linker (ldpli).
  • Executes the option (for example, -c) in a fashion similar to cc.
  • Ignores the option.

Program execution begins at the main entry point.

Parent topic: Compiling a Program
Related information
Compiler Options
Compiling a Program
Linking a Program
Main Procedure


Preprocessor Order of Execution

The Open PL/I preprocessors are run by mfplx in the following order:

  1. Open PL/I Include Preprocessor
  2. Open PL/I Macro Preprocessor
  3. DL/I Preprocessor
  4. OpenESQL Preprocessor
  5. CICS Preprocessor
  6. Open PL/I Macro Preprocessor
  7. DB2 Preprocessor
    Note: The DB2 Preprocessor is deprecated and will be removed in a future release.

The ordering of the Compiler switches you use has no impact.

You may change the order, if necessary, by separately invoking the preprocessor you choose.

It is recommended that you run the preprocessors in this order via mfplx, but if you want to run the preprocessors separately, run mfplx with the preprocessor arguments you want and the -# flag to see what command lines are generated.

The running of the preprocessor is controlled by the following flags:

  • -incl [-ppincl [output_file]]
  • -macro [-pp [output_file]]
  • -dli [-ppdli [output_file]]
  • -cics [-ppcics [output_file]]
  • -sql [-ppsql [output_file]]
  • -db2 [-ppdb2 [output_file]]

-incl, -macro, -dll, -cics, -db2 and -sql cause respective preprocessors to run. -ppincl, -pp, -ppdli, -ppcics, -ppdb2 and -ppsql cause the preprocessor's output to be kept and the optional output_file says to give the output file a particular name.

  • Examples
Parent topic: Compiling a Program


Examples

Example 1: Equivalent to an ordinary compilation with -macro.

The command line

mfplx -macro sample.pl1 -#

produces:

mfpp sample.pl1 -pp sample.pp
mfpli sample.pp -o sample.oobj
rm -f sample.pp
ldpli sample.oobj

Example 2: Equivalent to an ordinary compilation with -macro and two preprocessors.

The command line

mfplx -db2 -macro sample.pl1 -cics -#

produces:

mfpp sample-pl1 -pp sample.pp
mfcics -i sample.pp -o sample.pp1
mfpp sample.pp1 –pp sample.pp2
mfdb2 -i sample.pp2 -o sample.pp3
mfpli sample.pp3 -o sample.oobj
rm -f sample.pp sample.pp1 sample.pp2 sample.pp3
ldpli sample.oobj

Example 3: Run macro preprocessor and CICS preprocessor only, preserving the intermediate output files.

The command line

mfplx -E sample.pl1 -macro -cics -#

produces:

mfpp sample.pl1 -pp sample.pp
mfcics -i sample.pp -o sample.pp1
mfpp sample.pp1 –pp sample.pp2

Example 4: Ordinary compile, preserving CICS preprocessor output.

The command line

mfplx -cics -ppcics cicsout.out sample.pl1 -#

produces:

kixplt -i sample.pl1 -o cicsout.pl1
mfpli cicsout.pl1 -o sample.oobj
ldpli sample.oobj

Example 5: Multiple compilations.

The command line

mfplx -db2 -cics sample.pl1 sample2.pl1 -#

produces:

sample.pl1:
mfpp sample.pl1 -pp sample.pp
mfcics -i sample.pp -o sample.pp1
mfpp sample.pp1 -pp sample.pp2
mfdb2 -i sample.pp2 -o sample.pp3
mfpli sample.pp3 -o sample.oobj
del sample.pp sample.pp1 sample.pp2 sample.pp3
sample2.pl1:
mfpp sample2.pl1 -pp sample2.pp
mfcics -i sample2.pp -o sample2.pp1
mfpp sample2.pp1 -pp sample.pp2
mfdb2 -i sample.pp2 -o sample2.pp3
mfpli sample2.pp3 -o sample2.oobj
del sample2.pp sample2.pp1 sample.pp2 sample2.pp3
ldpli -db2 sample.oobj sample2.oobj
Parent topic: Preprocessor Order of Execution


mfplx Options

mfplx allows multiple filenames and accepts mfpli options as well as many standard UNIX or Windows system compiler and linker options, such as -c and -o. The -c option specifies compilation without linking. When -c is used, the -o option is passed to the compiler; when -c is not used, -o passes to ldpli.

On UNIX, mfplx always passes the -map option to the compiler for a storage allocation map in the listing file.

On Windows, when using the -c option for compiling without linking, mfplx passes the -map option to the compiler for a storage allocation map in the listing file. When linking is performed, mfplx passes -map to ldpli to create a loader map.

Some of the options available for use with the mfplx command are explained in the following table.

Option | Explanation
-# | Shows preprocessor(s) and compile/load commands (echo only).
-c | Specifies compilation without linking.
-db2 | Indicates using the mfdb2 preprocessor and/or link with mfdb2 DB2 support. (deprecated)
-dli | Runs the DL/I preprocessor and/or links with mfexecpp DL/I support.
-help | Prints help text on STDOUT.
-incl | Invokes the Include preprocessor.
-l | Specifies an include search path.
-macro | Runs the PL/I macro preprocessor.
-nodebuginfo | Tells mfplx not to generate %FILE, %LINE, %SDEBUG and %RDEBUG information.
-nomacro | Suppresses the invocation of the Open PL/I Macro Preprocessor.
-O | Selects optimization level 0,1, 2, or 3 (equivalent to -opt.)
-pp | Specifies PL/I macro preprocessor's output filename and saves it.
-ppdb2 | Specifies DB2 SQL preprocessor's output filename and saves it.
-sql | Indicates using the mfexecpp SQL preprocessor (for DB2, OCI, or ODBC).
-systemcics | Compiles and/or links to execute under CICS.
-systemims | Compiles and/or links to execute under IMS.
-systemmvs | Compiles and/or links to execute under MVS.
-v | Shows the version number of the compiler.
Parent topic: Compiling a Program


Include Preprocessor Options

The Include pre-processor has the following general syntax:

mfinclpp input-file-name -incl [-ppincl output-file-name] [-optincl incl-pp-options]

The only required option is the input-file-name. The other options are:

Option | Explanation
-ppincl output-file-name | Overrides the default output file name, which will be input-file-name with an extension of .ppi. Example: -ppincl myprog.dek
-optincl options-string Specifies which INCLUDE statements you wish the Include preprocessor to process. options-string is any or all of the following single letters (upper or lowercase) specified in any order without any intervening commas or spaces:
  • S - processes EXEC SQL INCLUDE statements
  • P - processes Panvalet ++INCLUDE statements. The ++INCLUDE statement must be on a line by itself, must be all uppercase including member-name, and must have the following syntax:
    [spaces] ++INCLUDE [spaces] member-name [spaces]  [;]
  • L - processes Librarian -INC statements. The -INC statement must be on a line by itself, must be all uppercase including member-name, and must have the following syntax:
    [spaces] -INC [spaces] member-name [spaces]  [;]
  • I - processes PL/I %INCLUDE and %XINCLUDE statements. Full mainframe syntax for these statements is supported.

If this option is not specified, SPLI is the default. i.e. all of these INCLUDE statements are processed.

  • Examples
Parent topic: Compiling a Program


Examples

Example 1:

mfexecpp myprog.pli –isuffix .inc –path e:\source\include –ppincl myprog.out –optincl si

Will process only EXEC SQL INCLUDE, %INCLUDE and %XINLUCE statements. ++INCLUDE and -INC will not be processed.

Example 2:

mfexecpp myprog.pli –isuffix .inc –path e:\source\include –ppincl myprog.out –optincl ps

Will process only ++INCLUDE and EXEC SQL INCLUDE statements.

Example 3:

mfexecpp -incl myprog.pli –isuffix .inc –path e:\source\include

Will process all types of include statements producing myprog.ppi as the output file.

Parent topic: Include Preprocessor Options


Macro Preprocessor Options

The options available for use with the mfpp command are explained in the following table. The -ipath and -suffix options obey the rules that apply when they are invoked as compiler options.

Option | Explanation
-currency_symbol | Provides a currency symbol for picture specification. It can take the character, decimal number, or hex constant of the form 0xDD, for example, -currency_symbol £, -currency_symbol 163, -currency_symbol 0xa3.
-define name[=value] mynum[='value' (value)] Using name[=value] causes value to be used in place of name wherever the identifier name appears.

Using mynum[='value' (value)] defines a preprocessor variable called MYNUM to the PL/I Macro Preprocessor. The presence or absence of single quotes around the value determines whether the defined variable is of type CHAR or type FIXED.

For example, -define mynum='1234' defines the variable as type CHAR. It is equivalent to coding the following in the PL/I program processed by the macro preprocessor:
%DCL MYNUM CHAR;
%MYNUM = '1234';
To define a FIXED type variable, omit the quotes and use a numeric value. For example, -define mynum=1234 is equivalent to coding the following in the PL/I program processed by the macro preprocessor:
%DCL MYNUM FIXED;
%MYNUM = 1234;

On UNIX/LINUX, any single quotes around the value are stripped prior to being handled by the macro preprocessor. So for example, -define mynum='1234' is interpreted by the macro preprocessor as -define mynum=1234, thereby defining MYNUM as of type FIXED instead of type CHAR.

To define MYNUM as a CHAR preprocessor variable, you must add an additional set of double quotes around the single quoted string. For example, -define mynum="'1234'" is equivalent to coding the following in the PL/I program processed by the macro preprocessor:

%DCL MYNUM CHAR;
%MYNUM = '1234';
-incafter filename | Allows for the use of an include file without having to modify sources. The named file is infused as the first line of source.
-includes | Tells the preprocessor to process %INCLUDE statements.
-ipath dir | The -ipath and -isuffix options obey the rules that apply when they are invoked as Compiler options. This option specifies the folder location to search for include files.
-isuffix suffix (or -x suffix) | The -ipath and -isuffix options obey the rules that apply when they are invoked as compiler options.
-margins I,r Sets the margins within which characters of the source file are interpreted as source code and outside which all characters are ignored by the Compiler. l is the column number of the leftmost character and r is the column number of the rightmost character to be interpreted as source code. Note that, if tabs are used, each tab is counted as a single character.

The -margins option on a *PROCESS card is ignored if the macro pre-processor is in use (either by executing mfpp or mfplx with the -macro option); in this case, if the source margins are not 1,256, the actual margins must be specified with the -margins option.

-nodebuginfo | Specifies that the preprocessor will not generate the normal debug information that it passes to the Compiler. This is useful if you wish to debug using the post-preprocessing PL/I source file rather than the original source file.
-noincludes | Tells the preprocessor not to handle %INCLUDE statements.
-[no]namesstring1 [string2] Provides extended character support. For example,
-names 'string1' ['string2']
where string1 are extralingual characters to add to identifiers, and string2 are optional corresponding uppercase characters. Hex constants of the form 0xDD are accepted in place of the strings. The default is -names.
-not_symbol | Provides a not symbol. It can take the character, decimal number, or hex constant of the form 0xDD.
-or_symbol | Provides an or symbol. It can take the character, decimal number, or hex constant of the form 0xDD.
-pp outfile (or -o outfile) | Names the output file the name you specify with outfile. If -pp is not specified, the default name of the file is xxx.pp, where xxxis the input filename up to, but not including, the last "." (if any) in the name. For example, if the input filename is prog.pl1, the default output filename is prog.pp.
-T | Causes the preprocessor to examine a %INCLUDE file name for the characters @, #, and $, and to replace @ with A, # with N, and $ with D.
-undefine name | Removes a definition for name, if name was created by a -define option, and leaves the identifier name in the source as name. It does not preclude a %REPLACE statement or %name=expr from changing the value of name.
-variant string | Supplies a string to be used in place of the VARIANT built-in function.
Parent topic: Compiling a Program


CICS Preprocessor Options

The CICS Preprocessor options are explained in the following table.
Option | Explanation
-# | Displays the mfexecpp command line.
-bigendian | Default to BIGENDIAN integers. Note: It is applied by default.
-deb | Allows debugging.
-i | Specifies input file.
-margins | Specifies the margins (-margins left,right)
-native | Default to LITTLEENDIAN integers.
-nonnative | Default to BIGENDIAN integers.
-not_symbol | Selects alternate NOT symbol
-o | Specifies output file.
-or_symbol | Selects alternate OR symbol
Parent topic: Compiling a Program


HCO for DB2 LUW Preprocessor Options

Syntax

Use this syntax to set an HCO for DB2 LUW preprocessor option for the PL/I compiler.

mfplx pliProgName –sql db2 –optsql "DB2PrecompilerOption [...]"

Required Options

Since the HCO for DB2 LUW preprocessor must connect to the DB2 LUW server to convert EXEC SQL statements to API calls, you must use the DB option for PL/I when building applications using SQL.

The PL/I DB2 LUW Preprocessor uses the same preprocessor options as used with the equivalent COBOL HCO preprocessor.

ko

Examples

These examples specify a server named SAMPLE to connect to and compiles programs named sample1 and sample2 respectively:

mfplx sample1.sqb –sql db2 –optsql "DB=SAMPLE"
mfplx sample2.sqb –sql db2 –optsql "DB=SAMPLE"
Note: You do not need to link with db2api.lib library as PL/I dynamically loads all required code.
Parent topic: Compiling a Program
Related concepts
HCO for DB2 LUW Preprocessor


DB2 Preprocessor Options (deprecated)

The DB2 Preprocessor options are listed in the table below:

-action | Refer to the IBM DB2 documentation.
-bind | Specifies that a bind file should be created.
-bindname | Specifies name of bindfile to create.
-block | Specifies type (unambig, all or no) of row blocking.
-catalog | Refer to the IBM DB2 documentation.
-charsub | Refer to the IBM DB2 documentation.
-connect | Specifies if the CONNECT statement should be of type 1 or 2.
-collection | Specifies the collection schema name.
-datetime | Specifies date/time format (def, usa, eur, iso, jis, loc).
-dbname | Specifies name of database to preprocess against.
-dec | Refer to the IBM DB2 documentation.
-decdel | Refer to the IBM DB2 documentation.
-degree | Refer to the IBM DB2 documentation.
-disconnect | Refers to disconnections (explicit, automatic or conditional).
-dynamicrules | Refer to the IBM DB2 documentation.
-explain | Refer to the IBM DB2 documentation.
-explsnap | Stores an Explain snapshot (no, all or yes)
-funcpath | Specifies functional path for types and functions in static SQL.
-insert | Refers to data buffering (def or buf).
-isolation | Specifies isolation level (ss, rr, ur).
-level | Refer to the IBM DB2 documentation.
-nobind | Specifies that no .bnd file is created.
-nooptimize | Specifies that no SQLDA initialization optimizations are done.
-package | Causes package creation.
-packagename | Specifies name of package. Implies -package.
-optimize | Specifies that SQLDA initialization optimizations are done.
-optlevel | Same as -optimize. Impacts initializations of SQLDAs.
-owner | Refer to the IBM DB2 documentation.
-queryopt | Optimization of static SQL. The default level is 5.
-qualifier | Refer to the IBM DB2 documentation.
-release | Refer to the IBM DB2 documentation.
-replver | Refer to the IBM DB2 documentation.
-retain | Refer to the IBM DB2 documentation.
-schema | Refer to the IBM DB2 documentation.
-sqlerror | Specifies action following error(s).
-sqlflag | Reports on deviations on SQL syntax.
-sqlrules | Refers to connects (std or db2).
-sqltwop | Performs two passes because variable usage precedes declarations.
-sqlwarns | Refers to dynamic SQL.
-stds | Refer to the IBM DB2 documentation.
-syncpoint | Refers to commits or rollbacks (onephase, none, twophase)
-syntax | Suppresses package or binding. Validity checking.
-text | Refer to the IBM DB2 documentation.
-validate | Refer to the IBM DB2 documentation.
-version | Refer to the IBM DB2 documentation.
Parent topic: Compiling a Program


Compiler Options

Note: When compiling from the command line, enclose any compiler option values that contain special characters (including spaces) in double quotes (" "). For example, enter:
-optexec  vtrace,plitest(b 10)

and

-optexec  plitest(b 10)

as:

-optexec  "vtrace,plitest(b 10)"

and

-optexec  "plitest(b 10)"

Compiler option values can always be enclosed in double quotes even if containing no special characters. However, do not use single quotes to enclose compiler option values.

The list below describes each of the Compiler options and its default setting, when applicable.

-#
Provides information on how the Compiler and linker would be invoked without actually invoking them. This option also shows which UNIX options are translated to Micro Focus options; for example, when the standard UNIX -O option is given on the driver command line, it is translated on the Compiler invocation line as -opt.
-adt
-adt [adt-filename]

Generates a file containing the data structures processed by the PL/I compiler. If adt-filename is not specified, a file with the name program-name.adt is generated. This file is consumed by the Record/Segment Layout Editor, which creates Segment Layout Files (SLF) and Record Layout Files (STR) using these PL/I structure descriptions. Data File Tools can then use these layout files to aid in processing/editing the segments or records (Data File Convert, Data File Editor, IMS Database Editor, IMS Database loader).

Use the ADT file with the Layout Editor to create SLF and STR files.

-agginit
Performs initialization of aggregates compatible with 7.x versions of Open PL/I (scalar arrays only).

Example:

dcl myarr(4) fixed bin(31) static init (1);
put skip list (myarr);

results in:
             1               1               1               1

By default, without -agginit, only the first element is initialized.

-ascii
Specifies to use the ASCII character encoding for all character data. This option is set by default.
-bigendian
Specifies that all FIXED BINARY, CHARACTER VARYING, GRAPHIC VARYING and WIDECHAR VARYING items are implicitly declared with the BIGENDIAN data attribute, unless the NATIVE attribute is explicitly applied to a data item.
-bitsltr
Stores bit strings left-to-right within each byte. This is similar to Big Endian bit ordering (Intel only). The Intel default is to store bit strings right-to-left, but when the option is used, bit strings are stored left-to-right within each byte.
-c
Suppresses linking and produces a relocatable object file. This option applies to mfplx only.
-cics
Invokes the CICS preprocessor for EXEC CICS support. This allows EXEC CICS statements to be recognized and processed to generate native PL/I source code.
-coffdebug
Emits line number information for the Visual Studio debugger to enable breakpoints, statement tracing, and call stack information of Open PL/I source code.
Restriction:
  • Evaluation of variables is not supported.
  • -coffdebug is not supported on 64-bit Windows.
-compact_msgs
Do not break the line for messages.
-currency_symbol
Allows an alternate currency symbol for picture specification. It can take a character, decimal number, or hex constant of the form 0xDD, for example, -currency_symbol £, -currency_symbol 163, -currency_symbol 0xa3.
-db2
Invokes the DB2 preprocessor, mfdb2. The default DB2 preprocessor output file name is xxx.pp2, where xxx is the name of the source file. If the -ppdb2 option is not specified, the file xxx.pp2 is deleted after the compilation phase is completed. The -db2 option applies to mfplx only.
Warning: This option is required for the mfdb2 preprocessor, which is deprecated. Please use the EXEC preprocessor (invoked by -sql db2)
-deb (-debug)
Produces debugging information for CodeWatch, Micro Focus's source-level debugger. You must specify this option when using CodeWatch to debug source. When using -deb, you may specify only optimization levels 1 or 2. The default is -opt 2.
-default_binary
Causes the BINARY attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL.
-default_decimal
Causes the DECIMAL attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL. This option is the Compiler default.
-defext
Causes external variables to be defined in the data section. You must use this option for programs using external files.

The -defext option causes the initialized values of STATIC EXTERNAL variables and external file constants to be defined. Each STATIC EXTERNAL variable that has an INITIAL value must be declared in one and only one module that has been compiled with -defext. Failure to do so causes the INITIAL value to have no effect. The default is -nodefext.

Also, each file constant must be declared in one and only one module that has been compiled with -defext. When -defext is used, file attributes specified in the file declaration merges with attributes specified when the file opens. This is critical when doing VSAM/INDEXED I/O.

-dli
Invokes the DL/I preprocessor for EXEC DLI support. This allows EXEC DLI statements to be recognized and processed to generate native PL/I source code. This option is processed and supported by the EXEC preprocessor (EXEC PP).
-dll
Generates an object that can be used as a fetchable procedure. Use -dll to build shared fetchable procedure objects based on your operating system.
-E
Causes any specified preprocessors (-macro, -db2) to be run on the source file, and saves their output, but stops without running the Compiler.
-ebcdic
Specifies to use EBCDIC character encoding for all character data.
Note: The WIDECHAR and GRAPHIC data types are not supported with the -ebcdic compiler option.
-err_on_stdout
Displays or prints compiler error messages to STDOUT instead of STDERR.
-exp
Produces an expanded listing of the generated code in the form of assembly language statements in the listing file.
-f
Synonymous with -flag.
-fb7asfb15
Treats Fixed Binary (7) as Fixed Binary (15). Use for backward compatibility with previous versions of Open PL/I.
-fbmaxp n
Specifies the maximum Fixed Binary precision. The values can be:
31
Sets the maximum signed Fixed Binary intermediate result precision to 31. For unsigned fixed binary operands, the maximum intermediate precision is 32.
63
Sets the maximum signed Fixed Binary intermediate result precision to 63. This is the Open PL/I default.
Note: For –fbmaxp 63, arithmetic operations with fixed binary operands (p <= 31) will result in a maximum intermediate precision of p=31. For operands (32 >= p <= 63), the result precision will be promoted according to result precision rules with maximum fixed binary precision p=63. For unsigned fixed binary operands, the maximum intermediate precision is (p+1).

You can also use -fixed_bin_max_p as a synonym to -fbmaxp.

-fdasfb
Causes Float Decimal data to be internally coded as Float Binary. This option produces much faster code but loses precision in the least significant digits of arithmetic results. -fdasfb is the default. See also the -nofdasfb option.
-fdmaxp n
Specifies the maximum FIXED DECIMAL precision n. Recommended values are:
15
The z/OS default.
18
Open PL/I default for Enterprise Developer release 2.1 and earlier.
31
Open PL/I default for Enterprise Developer release 2.2 and later.

Fixed decimal precision 31 is the maximum allowed.

You can also use -fixed_dec_max_p as a synonym to -fdmaxp.

-fixed_bin_max_p
The same as -fbmaxp.
-fixed_dec_max_p
The same as -fdmaxp.
-flag
Specifies the minimum diagnostic level of messages. Diagnostics below this level are suppressed. Synonymous with -f.
-flag minimum diagnostic level
The minimum diagnostic level can be:
I
Emits diagnostic messages beginning at the Informational level (Lists all messages. This is the default).
W
Emits diagnostic messages beginning at the Warning level.
E
Emits diagnostic messages beginning at the Error level.
S
Emits diagnostic messages beginning at the Severe level.
-fmaxp
Causes floating-point precision to be used for the trigonometric built-ins and for the following arithmetic built-ins: EXP, LOG, LOG10, LOG2, SQRT. -fmaxp is the default. Use -nofmaxp for the standard PL/I conversion rules for the trigonometric and the named arithmetic built-ins.
-fpcobol
Tells the Compiler to generate code compatible with COBOL handling of floating-point parameters.
-full_list
Tells the macro preprocessor to omit %NOLIST directives normally placed before code included by the %INCLUDE statement, thereby allowing the included code to be visible in the compilation listing.
-graphic
Enables support for the GRAPHIC data type.
Note: EBCDIC data and constants in conjunction with -graphic is not supported .
-help
Prints out a list of available compiler options to the console or STDOUT output, and to EXIT.
-highbif
This option allows changing the value returned by the HIGH() built
n function. For example, -highbif 127 (the default value is 255; the value 127 may be used for compatibility with earlier versions of Open PL/I).
-incl
Invokes the Include preprocessor which will process selected or default include statements and produce a deck that may then be treated as a single source file by another preprocessor or the Open PL/I Compiler.
-ipath dirlist
Directs the Compiler to search specified directories for files to be included in the source program text by use of the %INCLUDE statement. dirlist is an ordered list of directories of the form
dirname[:dirname] ...

The -ipath option instructs the Compiler to use these directories in the specified order in its search for files to satisfy %INCLUDE statements (except in cases where an absolute directory path is specified in the %INCLUDE statement).

For example, suppose the source program contains:

%INCLUDE partlist;

and the Compiler invocation command is:

mfplx source_file -ipath .:/u/libr1:/u/libr2

In this case, the Compiler will first search for "PARTLIST" in the current working directory, then /u/ libr1, and finally /u/ libr2. If that fails, it will search for "partlist" (lowercase) in the same directories.

In a Windows environment, the equivalent Compiler invocation is:

mfplx source_file -ipath .;drive:\libr1;drive:\libr2
-ipubr
Causes bits for unsigned integers created using INT or POSINT and bit strings returned with UNSPEC to be inversed.
-isuffix string
Causes string to be appended to the filename specified in %INCLUDE statements, except those in which the quoted filename form of the %INCLUDE statement is used.

For example, suppose the source program contains:

%INCLUDE partlist;

and the Compiler invocation command is:

mfplx source_file -isuffix .INC

In this case, the Compiler searches for a file named partlist.inc.

-l [ file]
Produces a Compiler listing where file is the name of the file to which the listing is output. If you do not supply a filename, you must place this option after the source filename on the command line; otherwise, an error message appears. The default name of the file containing the listing is xxx.list, where xxx is the source filename (excluding the pathname) up to, but not including, the last "." (if any) in the name. For example, if the source filename is prog.pl1, the default listing is prog.list (prog.lst for Windows systems). A Compiler listing is produced by default whenever -exp, -map, or -xref is specified.
-laxbased
Disables storage checking of BASED variables. This is Open PL/I default. See also –nolaxbased.
-laxdefined
Disables type and storage checking of DEFINED variables. This is Open PL/I default. See also –nolaxdefined.
-laxinit
Disables dependency ordering of automatic initializers in block prologue. The declaration order is used.
-longint
Changes the default precision of Fixed Binary variables from (15) to (31).
-lowercase
Converts all uppercase names of internal and external variables and constants to lowercase.
-macro
Invokes the Open PL/I Macro Preprocessor, mfpp. The default preprocessor output file name is xxx.pp, where xxx is the name of the source file. If the -pp option is not specified, the xxx.pp file is deleted after the compilation phase is completed. The -macro option applies to mfplx only.
-map
Produces a storage allocation map at the end of the listing file.
-map
Does one of the following:
  • When used without a colon or any arguments, -map produces a storage allocation map at the end of the listing file.
  • When used with a colon and an argument, for example -map:filename (where filename is the filename of a linker map file), this option passes to ldpli and to generate a linker map for the specified filename.

-map add -map:filename can be used together.

-margini s
Specifies a character that will be places in the column preceding the left-hand margin, and also in the column after the right-hand margin, of the listings produced by the INSOURCE and SOURCE options. c is a character which delimits the left and right margins in the source listing.
-margins l,r
Sets the margins within which characters of the source file are interpreted as source code and outside which all characters are ignored by the Compiler. l is the column number of the leftmost character, and r is the column number of the rightmost character to be interpreted as source code. Note that if tabs are used, each tab is counted as a single character. The -margins option can be overridden by a *PROCESS statement in the source.
Note: There must be no spaces around the comma separating the left and right margin.
-maxmsg
Specifies the maximum number of diagnostics of a specified severity or higher which will be produced during compilation.
-maxmsg Level,n

where Level is one of I, W, E, S as follows:

I
Counts all compiler messages starting at I-level (Informational) against the maximum.
W
Counts all compiler messages starting at W-level (Warning) against the maximum.
E
Counts all compiler messages starting at E-level (Error) against the maximum.
S
Counts only S-level (Severe) against the maximum.
n

The maximum number.

The default is -maxmsg W,1000.

Compilation terminates if the number of messages exceeds the maximum number allowed. If messages are below the specified severity, they are not counted in the number. The value of n can range from 0 to 32767. If you specify 0, the compilation terminates when the first error of the specified severity is encountered.

An unrecoverable A-level (Abort) error message always results in termination.

-names
Adds extralingual characters to identifiers via the compiler options, similar in nature to *PROCESS NAMES().

Example:

-names 'string1' [ 'string2' ]
string1
Extralingual characters to add to identifier.
string2

Corresponding upper case characters. Optional.

The default is:

-names '$@#' '$@#'

For additional characters you must specify the default $@# or subset if desired, plus the additional lingual characters.

-names '$@#?'

For convenience, hex constants of the form 0xDD..DD are accepted in place of the strings above.

-names 0x402324a3
-nest
Causes the nesting of DO ... END, PROC ... END, and so on to be shown in the listing file. See the -l option for more information about the listing file.
-nocicsdebug
Allows use of CodeWatch to debug the original source file, rather than the intermediate file generated by the CICS preprocessor. Also, causes Compiler diagnostics to use line numbers referencing the original source file. This is the default. The -nocicsdebug command applies to mfplx and kixplt only.
-nodebuginfo
Tells the Compiler to not break the line for %FILE and %LINE information.
-nodefext

The -nodefext option prevents definition of initialized values of STATIC EXTERNAL variables and external file constants (default). See the -defext compiler option for more information.

Also, each file constant must be declared in one and only one module that has been compiled with -defext. When -defext is used, file attributes specified in the file declaration will be merged with attributes specified when the file is opened. This is critical when doing VSAM/INDEXED I/O.

-nofdasfb
Causes Float Decimal data to be internally coded as Binary Coded Decimal. The default setting is -fdasfb.
-nofmaxp
Causes standard PL/I conversion rules to be used to determine the precision of trigonometric and certain arithmetic built-ins. The default is -fmaxp.
-noincludes
Tells the Compiler and/or macro preprocessor not to include the contents of %INCLUDE files in the compiled source.
-nolaxbased
For BASED variables declared using the form BASED (ADDR(x), enables storage checking with the base reference “x”. –laxbased is the Open PL/I default.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or –ims imply –nolaxbased. This can be overridden when used in combination with –laxbased.

Example:

DCL S1 CHAR(10); DECLARE S2 CHAR(20) DEFINED (S1);

will result in an appropriate diagnostic.

-nolaxdefined
For DEFINED variables, enables both type and storage checking on DEFINED variable and the base variable. –laxdefined is the Open PL/I default.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or –ims imply –nolaxdefined. This can be overridden when used in combination with –laxdefined.

Example:

DCL X FIXED BIN (15); DECLARE Y FIXED BIN (31) BASED (ADDR(X));

will result in an appropriate diagnostic.

-nolaxdcl
Tells the Compiler to not allow compiler declarations for undeclared variables.
-nolaxinit
Enables dependency ordering of automatic initializers in block prologue. This is the Open PL/I default.
-nomacro
Suppresses the invocation of the Open PL/I Macro Preprocessor. The default is -nomacro.
-noobj
Compiles for syntax and semantic checking only. Does not produce an object file.
-noopt
Compiles without optimization. This is the default.
-norange
This option is deprecated and will be removed in a future release. See the -prefix option.
-noopt
Compiles without optimization. This is the default.
-not_symbol
Lets you specify an alternate NOT symbol. It can take a character, decimal number, or hex constant of the form 0xDD. See also %PROCESS in the Language Reference Manual.
-nounixdebug
Avoids generating the additional object file data needed to report source file and line number when a fatal run-time error occurs, or for use by the ONLOC built-in function.
-nounrefexternals
Prevents external entry symbols that are not referenced in the program from being generated in the object file. This is the default.
-nowarn
Suppresses all INFORMATIONAL and WARNING level diagnostics. This is equivalent to setting the –flag option to E.
-[no]xref
Tells the compiler to not include a cross-reference table of names that are used in the program. See the -xref compiler option for more information.
-O
Invokes the optimization phase of the Compiler. This option applies to mfplx only and is equivalent to the -opt option.
-o file
Names the object file the name you specify with file. If -o is not specified, the default name of the file is xxx.o, where xxx is the source filename up to, but not including, the last "." (if any) in the name. For example, if the source filename is prog.pl1, the default object filename is prog.o (prog.obj for Windows).

If -c is specified, the -o option is passed to the compiler; if -c is not specified, -o is passed to ldpli.

-opt [level]
Specifies the level of optimization by the Open PL/I Compiler, where level stands for the level (1 – 3) of optimization. The default setting is -noopt. If level is not included, the program is optimized at level 3. If -deb is specified, -opt 2 is the maximum level allowed. Note, -opt-deb is equivalent to -opt 2 -deb.
-optcics
Allows the CICS options to be passed to the CICS ECM
-optdli
Allows the DL/I options to be passed to the DL/I (IMS) ECM
-optexec {sub-option}[,sub-option]
Lets you specify options for the EXEC preprocessor. You can use the following for the -optexec option.
[NO]PLITEST
Tells the EXEC preprocessor to inject an automatic call to start the GUI CodeWatch debugger.

Using the -optexec option with the PLITEST parameter also lets you debug PL/I programs that run under CICS. During execution, the program stops at the first executable statement (either the PROCEDURE statement or the first statement following the PROCEDURE statement, depending on the execution environment). Specify the appropriate program source files and debug files with the CODEWATCH_SRCPATH and CODEWATCH_STBPATH environment variables when using PLITEST with this option.

NEWNAME(newname)
Specifies a name for the outermost external procedure in addition to other names that may have been specified on the PROCEDURE statement. Use this when the name on the procedure does not match the name of the executable. (newname) is the same name as the name of the executable.
trace
Causes the preprocessor to create a file source.trc where source is the name of your source file.
ctrace
Creates a trace file for submission to Technical Support if requested.
strace
Creates a log file from the internal functions called by the program.
vtrace
Creates a dynamic visual trace of the program.
-options

Adds information about translated *PROCESS directives and command-line option processing to the compiler listing (-options implies –l). See the section on *PROCESS directives for more information.

-optsql
Allows the SQL options to be passed to the SQL ECM
-or_symbol
Lets you specify an alternate OR symbol. It can take a character, decimal number, or hex constant of the form 0xDD. See also %PROCESS in the Language Reference Manual.
-pass
Connects to a remote DB2 database. You can use this option with a specified username and password. The format is:
–pass myid.mypass

Where myid is the username and mypass is the password for the remote DB2 connection. mfplx first checks the -pass for a username/password and uses these values if specified. If not specified, it uses the values set for the DB2_USERNAME and DB2_PASSSWORD environment variables.

-pic
Generates position-independent code, suitable for linking into a shared library. This option is only available on Solaris, SUSE Linux and Red Hat Linux.
Use this option when compiling code for inclusion in a shared object.
-pl1g
Causes Open PL/I to retain the behavior of releases prior to Open PL/I 5.0 for certain operations that have been changed in such a way as to become incompatible with that former behavior. For example, TIME() returns a value including three fractional digits (thousandths), but -pl1g causes it to return only two fractional digits (hundredths).
-plitdli

Specifies IMS linkage when calling a PLITDLI entry point name rather than a user supplied PLITDLI. This option allows for DCL PLITDLI ENTRY; declared as such in the user program (without an entry descriptor list and/or return type).

-pp [file]
Specifies the file name for the output file of the Open PL/I Macro Preprocessor. An output file created with the -pp option is preserved after the compilation phase is completed. This option applies to mfplx and mfpp only.
-ppcics [file]
Specifies the file name for the output of the CICS preprocessor. An output file created with the -ppcics option is preserved after the compilation phase is completed. This option applies to mfplx only.
-ppdli[file]
Specifies the file name for the output of the DL/I preprocessor. An output file created with the -ppdli option is preserved for consumption by a downstream preprocessor or the PL/I compiler.
-ppdb2 [file]
Specifies the file name for the output of the DB2 preprocessor. An output file created with the -ppdb2 option is preserved after the compilation phase is completed. This option applies to mfplx only.
-pporder
Selects which preprocessors are to be invoked and in what order. This option applies to mfplx only.

Syntax:

-pporder “pp-name [ (pp-string)] [ pp-name [ (pp-string)] ] … “
Note: The surrounding quotes are required.
pp-name
The name of the preprocessor. The preprocessor names must be one of must be one of MACRO,SQLDB2, SQLOCI, SQLODBC, CICS, or DLI.
pp-string
An argument associated with each preprocessor.

For INCL, no pp-string argument is applicable (or allowed).

For MACRO, the pp-string argument, if supplied, must be one of ‘CASE(ASIS)’ or ‘CASE(UPPER)’. This argument overrides any command-line argument –case_asis of –case_upper, if given.

For SQLDB2, SQLOCI, SQLODBC, the pp-string argument, if supplied, is what would be supplied to the –optsql option. This argument overrides any command-line argument for –optsql, if given. Refer to the Micro Focus SQL documentation for more information.

For CICS, the pp-string argument, if supplied is what is would be supplied to the –optcics option. This argument overrides any command-line argument for –optcics, if given. Refer to the Micro Focus CICS documentation for more information.

For DLI, the pp-string argument, if supplied, is what is would be supplied to the –optdli option. This argument overrides any command-line argument for –optdli, if given. Refer to the Micro Focus DLI documentation for more information.

A maximum of 31 invocations are allowed.

Note: If the –pporder option is not used, then the default ordering is applied, which is: INCL, MACRO, DLI, SQL, CICS, MACRO.

Selection of the above preprocessors to invoke is dependent upon the combination of given options –incl, –macro, -dli, -sql, and –cics. Refer to the Micro Focus documentation for more information on these options.

-ppsql [file]
Specifies the file name for the output of the SQL preprocessor. An output file created with the -ppsql option is preserved after the compilation phase is completed. This option applies to mfplx only.
-prefix condition-prefix[,condition-prefix]…
This option allows you attach one or more condition prefixes to your program without the need to edit the source code. These condition prefixes are logically prefixed to the beginning of the (implicit or explicit) PACKAGE statement, which in turn has the affect of logically prefixing these to each external (level 1) procedure in the program being compiled.

The default for -prefix is:

-prefix conversion,fixedoverflow,invalidop,overflow,underflow,zerodivide,nosize,nostringrange,nostringsize,nosubscriptrange
-proto
Provides more extensive prototype checking on arguments vs. parameters in entry declarations (also assumed by default when using -vax).

Example:

declare myproc external entry(
      fixed binary(31),
      fixed binary(15),
      fixed binary(15));

   myproc: procedure(a,b,c);        /* mismatch diagnosed, -proto and -vax */
      declare a fixed binary(15);
      declare b fixed binary(15);
      declare c fixed binary(15);

   end t660;
-range
This option is deprecated and will be removed in a future release. You should use -prefix stringrange,subscriptrange instead.

While accepted, -range is effectively is treated as -prefix stringrange,subscriptrange and it overrides the same condition prefixes specified in -prefix.

See the -prefix option.

-rc n,0
Specifies the maximum error code level n which will result in a zero return code from mfplx. The default is –rc 4,0. The allowed values are:
  • -rc 0,0
  • -rc 4,0
  • -rc 8,0
The compiler error code levels and mfplx return codes are shown in the table below:
Compilation Error Code Leve | Return Code | Description
0 | 0 | No diagnostic messages or I-level ( Informational) only.
0 | 4 | W-level (Warning) diagnostic messages (object code generated)
1 | 8 | E-level (Error) diagnostic messages (object code generated but execution behavior is not defined – the source code is in error and should be corrected)
1 | 12 | S-level (Severe) ) diagnostic messages (object code not generated)
1 | 16 | Compiler Abort
The command-line driver mfplx returns 0 upon success and 1 upon failure. If a link is invoked after successful compilation, the mfplx return code is 0 if successful and 1 if failure.
-report [file]
Specifies the file name for the output of the Open PL/I Source Checker. If this option is not used, the output of the checker will be directed to the standard error file. This option applies to mfplx only.
-setnull n
Designates a null pointer value n to be returned by the NULL built-in function, where n is a decimal value. If this option is not specified, the value of the NULL built-in function is an address with all bits set to 1.
-setstack
Initializes automatic storage to zero.
-so
Generates an object that can be used as a fetchable procedure. Use -so or -dll to build shared fetchable procedure objects based on your operating system.
-shortint
Tells the Compiler to set the default FIXED BINARY precision to 15.
-sql
Invokes the SQL preprocessor for EXEC SQL support. This allows EXEC SQL statements to be recognized and processed to generate native PL/I source code. This option is processed and supported by the EXEC preprocessor (EXEC PP). You can use the following for the -sql option.
odbc
Specifies an ODBC-compliant database.
db2
Specifies an IBM, DB2, or UDB database.
oci
Specifies an oracle "Call" interface database.
-stardesc
Tells the Compiler to produce argument descriptors for calls only when array bounds or string lengths in the parameter declaration are represented by the asterisk (*) symbol. (This was compiler behavior in releases prior to release 7.0.) When this option is not used, the Compiler produces descriptors for array, structure, and string arguments.
-stat
Prints Compiler statistics to the standard output as each Compiler phase completes.
-stbout
Generates an .stb file in the same directory as the output object file.
Note: You may need to set the CODEWATCH_STBPATH and CODEWATCH_SRCPATH variables to the appropriate locations when using this option.
-strip (ldpli)
Tells ldpli to not generate debugging information.
-structure_fillers
Tells the Compiler to produce warnings for structures containing fillers.
-systemcics

Specifies that this OPTIONS(MAIN) program will execute under the control of CICS. Such a program may have 0, 1, or 2 parameters, all of which must be POINTER. Such a program, almost always, will specify -cics and may also specify one or more of –sql and –dli.

-systemims
Specifies that this OPTIONS(MAIN) program will execute under the control of IMS. Such a program may have 0 thru n parameters, all of which must be POINTER. Such a program may also specify one or more of –sql and –dli.
-systemmvs
Specifies that this OPTIONS(MAIN) program will execute under the control of MVS. Such a program may have at most one parameter which must be CHAR(n) VARYING where “n” is not *. Such a program may also specify one or more of -cics, –sql and –dli.
-unaligned
This compile-time switch has been added for use on RISC architectures. This switch causes byte instructions to be generated for all based references, which might point anywhere in memory.
-unrefexternals
Causes external entry symbols to be generated in the object file, even if they are not referenced in the program.
-v
Prints information to stdout relating to the compilation and link-step phases. This option applies to mfplx only.
-variant string
Passes the variant string string to the Open PL/I Macro Preprocessor. This option applies to mfplx only.
-vax
Makes the following adaptations for programs originally written with Digital Equipment Corporations's PL/I Compiler for the VAX platform:
  • Enables Float Binary(24) as equivalent to Float Binary(23).
  • Enables Float Binary(53) as equivalent to Float Binary(52).
  • Causes the BINARY attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL.
-warn
Does not suppress INFORMATIONAL and WARNING level diagnostics. This is equivalent to setting the -flag option to I. This is the default.
-window
Sets the value for the w window argument used in various date-related built-in functions.
w
Either a positive four-digit integer such as 1976 that represents the start of a fixed window or a negative integer that specifies a “sliding” window. For example, -window -50 indicates a window that starts 50 years prior to the year when the program runs.
-xref fullshort
Produces cross-reference information in the listing file and specifies the type of cross reference information produced. The cross-reference shows names used in the program with the numbers of the statements where they are either declared of referenced. Only label references on END statements are not included in the listing when using -xref.

Use full with -xref to include all identifiers and attributes in the listing. Use short with -xref to exclude unreferenced identifiers.

-zalign
Specifies z/OS aggregate mapping and alignment rules.
  • Affects mapping of structure members. z/OS structure mapping rules use a "shift-to-align" algorithm to minimize compiler inserted pad bytes for the alignment requirement of structure members. This differs from the default Open PL/I structure mapping rules described in the Structure topic, which are compatible with other UNIX and Windows compilers for inter-language compatibility.
  • Sets the default FLOAT BINARY single precision to 21 and the default FLOAT BINARY double precision to 53 ( implies -zfloat). The Open PL/I default is 23 and 52 respectively.
  • Specifies that the default alignment attribute for the CHAR, CHAR VAR, GRAPHIC, GRAPHIC VAR, WIDECHAR, WIDECHAR VAR and PICTURE data types is unaligned (implies -zchar). The Open PL/I default is aligned.
  • Implies double-word alignment of double precision FLOAT BINARY on Intel 32-bit systems (the Open PL/I and Intel native default alignment is word on Intel 32-bit systems)
  • Implies double-word alignment of AREA on Intel 32-bit systems (the Open PL/I default alignment is word on Intel 32-bit systems)

Structure Layout Example (Open PL/I default)

The following shows structure ST with size 8 bytes; member "C" is at offset 0 (byte alignment) and member "X" is at offset 4 (word alignment), with 3 compiler-inserted pad bytes between.

       1
       2      dcl 1 ST,
       3            2  C CHAR,
       4            2  X FIXED BIN(31);
       5

NAME             CLASS      SIZE      LOCATION    ATTRIBUTES

ST               BASED      8                    LEVEL 1 STRUCTURE
C               MEMBER      1         00000000   LEVEL 2 CHAR(1)
                            3         00000001    -pad-
X               MEMBER      4         00000004   LEVEL 2 FIXED BIN(31,0)

Structure Layout Example (-zalign)

The following shows structure ST with size 5 (8 bytes are allocated in memory); member "C" is at offset 0 (byte alignment) and member "X" is at offset 1 (word alignment). In this example each member is shifted by 3 bytes (OFFSET=3 as shown below) to properly align each member on its required boundary, thus minimizing (and in this case eliminating) compiler-inserted bytes. Effectively, the "shift-to-align" algorithm propagates pad bytes that fill natural alignment gaps between members toward the beginning of the structure. Pad bytes which have been shifted outside the structure (that is, preceding the first member) are known as "hang bytes".

       1
       2      dcl 1 ST,
       3            2  C CHAR,
       4            2  X FIXED BIN(31);
       5

NAME             CLASS      SIZE      LOCATION    ATTRIBUTES

ST               BASED      5                     LEVEL 1 STRUCTURE OFFSET=3
C               MEMBER      1         00000000    LEVEL 2 CHAR(1) UNALIGNED
X               MEMBER      4         00000001    LEVEL 2 FIXED BIN(31,0)
Note:
  • The use of this option is recommended only when structure mapping is required to match z/OS structure mapping rules. An example when required might be reading files imported from the mainframe containing record structures that have z/OS compiler-inserted (and possibly removed) pad bytes for alignment purposes.
  • If -zalign is used for the compilation of one module, it is recommended that all modules in a given program be compiled as such for compatibility. Mixing --zalign with compilation units in the same program may work, but this can be problematic if the modules compiled with -zalign are not "self-contained".
  • For adjustable structures (having REFER-extents or non-constant sized members), the -zalign "shift-to-align" algorithm will cause more code to be generated to access structure members with non-constant offsets (seen in the -map listing as (-V-) under the Location Field). Depending upon structure layout, the amount of code generated can be extensive as compared against the Open PL/I default mapping rules (when not using -zalign). Compiler optimization at a minimum level of -opt 2 is recommended.
Restriction:
  • For structures with multiple REFER-extents, compiler resources may be impacted resulting in a Compiler Abort. Please contact Micro Focus SupportLine.
Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.
-zchar
Specifies that the default alignment attribute for the CHAR, CHAR VAR , GRAPHIC, GRAPHIC VAR, WIDECHAR, WIDECHAR VAR and PICTURE data types is unaligned. The Open PL/I default is aligned.
Note: This affects storage requirements for CHAR VAR , GRAPHIC VAR, and WIDECHAR VAR. It also affects parameter and descriptor matching at CALL statements.

Example (Open PL/I default):

Dcl c  char;
Dcl sub entry (char unaligned);

    Call sub(c);  /* A dummy argument is created for “c” */

Dcl c  char;
Dcl sub entry (char aligned);

Call sub(c);  /* “c” is passed by reference */

Example (-zchar)

Dcl c  char;
Dcl sub entry (char unaligned);

    Call sub(c);  /* “c” is passed by reference */

Dcl c  char;
Dcl sub entry (char aligned);

Call sub(c);  /* A dummy argument is created for “c”  */
-zfloat
Specifies the Float Binary single precision default as 21; specifies the Float Binary double maximum as 53. The Open PL/I defaults are 23 and 52, respectively.
Note: Floating point precisions that are less than or equal to 21 are implemented as IEEE single precision floating point. Floating point precisions that are greater than 21 are implemented as IEEE double precision floating point.
-zp1
Causes all structures to be mapped as if the UNALIGNED attribute is specified at the level 1 structure level. The option is for compatibility with versions of DEC VAX PL/I.

Compiling with -zp1 effectively packs all structures so that any pad bytes used for data alignment are eliminated. This is useful when files originating from the mainframe have records in which the data items are packed or unaligned.

When -zp1 is set, the compiler needs to take certain precautions, especially on RISC architectures where misaligned data can cause a hardware exception.

The -zp1 compiler options affects the following:

  • All structure members are packed without any pad bytes for alignment as if the UNALIGNED attribute were specified at the level 1 structure level.
  • All based variables are treated as if unaligned.
  • All parameters are treated as if unaligned.
  • All Character Varying data items are treated as if unaligned. The Open-PL/I default alignment for CHAR VAR is HALFWORD which is the natural alignment of the leading fixed bin (15) length.

When using -zp1, to maintain consistency in passing arguments without modifying the source code, the compiler disables creating dummy arguments at call points when the argument is a structure member and the argument and parameter descriptors do not explicitly differ between the UNALIGNED and ALIGNED attributes.

Note: Using -zp1 can have an overall impact on performance. On RISC architectures such as SPARC and RS6000, the compiler must generate sequences of byte addressable instructions to access unaligned data items in the memory. On Intel, no changes are required for code generation, but additional clock cycles are required for the hardware to access misaligned data items.
Important: If you are using this release as an upgrade to Enterprise Developer 2.2 Update 1, after the upgrade you must rebuild any applications that are compiled using the –zp1 option.

The behavior of the –zp1 option has been reverted to that of versions of Enterprise Developer earlier than 2.2 Update 1, with an additional correction relating to Char Varying data items.

The behavior has been restored to that in Enterprise Developer versions earlier than 2.2 where, when compiling with –zp1, all parameters are treated as unaligned. (In Enterprise Developer 2.2 Update 1, the behavior when compiling with –zp1 was to not treat parameters as if unaligned).

When using the –zp1 compiler option, all Character Varying data items are now treated as if unaligned. In previous versions of Open PL/I, for Character Varying data items, the –zp1 unaligned requirement was applied only to structure members and parameters.

To illustrate the change, consider the following example:

zptest: proc options(main);

   dcl 1 st1,
     2 c char,
     2 x(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl y(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz');

   dcl sub entry ((4) char(7) var);

   call sub (x);

   call sub (y);

end;

sub: proc (z);

   dcl z(4) char(7) var;

   dcl i fixed bin(31);

  do i = 1 to hbound(z);
      z(i)  = 'x';
  end;

end;

Where:

  • For x and z, each char (7) var item is 7 plus 2 bytes which equals 9 and then multiplied by 4 equals 36.
  • If y were aligned on half-word by default, each array element is half-word aligned and each equals 10 bytes (9 + 1 pad byte), and the total size equals 40 bytes.
  • At call sub (x), the calling argument and parameter are matched.
  • At the call sub (y), the y element size (10 bytes) is mismatched against the parameter z element size (9 bytes) due to –zp1. This is incorrect and causes unexpected program behavior.

Due to this correction of treating all Char Varying data items as if unaligned when using –zp1, the size of CHAR VARYING arrays now differs from previous versions of Open-PL/I. For example:

   dcl X(4) char(7) var;

   Put skip list (size(X))  /* size is 36 bytes vs. 40 bytes in previous versions of Open-PL1 */
  • Intel-Specific Options
Parent topic: Compiling a Program
Related information
Optimization
The -exp Option
The -l Option
The -map Option
External Names
Open PL/I Compiler Diagnostic Messages
Compilation Statistics
Structure


Intel-Specific Options

The Intel-specific options and their default settings are listed below. Use the default settings of the Compiler options to generate the most efficient code for your system.

-f287
Generates Intel287 floating-point coprocessor instructions where possible. This is the default if an Intel387 coprocessor is not present.
-i386
Produces code for the Intel386 processor avoiding optimizations designed for the Intel486 processor. Programs compiled with the -i386 option run correctly on the Intel486, but may perform better when they are compiled with the -i486 option. -i386 is the default when the Compiler is run on an Intel386 processor.
-i486
Produces code for the Intel486 processor, using optimizations designed for the Intel486. Programs compiled with the -i486 option may not run on an Intel386 processor. -i486 is the default when the Compiler is run on an Intel486 processor.
Parent topic: Compiler Options


Compiler Listings

The Compiler listing options are:

  • -l (list)
  • -map (storage allocation map)
  • -xref (cross-reference)
  • -exp (expanded code)

All listing information is directed to the listing file. When any of the listing options are specified, the -l option is invoked by default.

  • The -l Option
  • The -map Option
  • The -xref Option
  • The -exp Option
Parent topic: Compiling a Program


The -l Option

The -l option produces a listing file, which is named by default with the source program name (up to but not including the last ".") and the suffix .list. You can choose another name for the listing file by specifying a name after the -l option, in the following format:

-l file

The listing file contains a program listing, which consists of a copy of the source program with line numbers beginning at 1 in a column to the left of the source line.

Parent topic: Compiler Listings


The -map Option

The -map option produces a storage allocation map, which displays the location and allocation size of each program entity. The map categorizes this information by name, class, size, location, and attributes.

This information is presented in five columns:

Column | Description
NAME | Indicates the name of each entity in the program.
CLASS | Indicates the storage class of each program entity; for example, AUTOMATIC, CONSTANT, STATIC, PARAMETER, CONTROLLED, or BASED.
SIZE | Indicates the size of the entity, usually in bytes. If the size is measured in bits, the size number is followed by a B. If the size of the entity is not constant, a -V- is displayed in the location listing. Entities of class ENTRY or BUILTIN have no size or location listing.
LOCATION Gives the offset location of the entity in hexadecimal notation.
  • For automatic variables, the location column gives the memory offset from the frame pointer
  • For static variables, it gives the memory offset from the beginning of static data
  • For controlled and based variables, it displays the value -V-
ATTRIBUTES Displays the data type of the entity, for example, FIXED DEC, FLOAT BIN, CHAR, CHAR VAR, BIT ALIGNED, and ENTRY.

Displays BUILTIN for an entity of BUILTIN class. Displays the precision and scale of the entity, where applicable, in parentheses: for example, FIXED BIN(15,0).

Program entities are listed in the order in which they appear in the procedure.

The map first lists external entry points to the program: external constants, subroutines, or programs, including the source program itself. These entry points are listed with name, class, and attributes.

The map then lists program procedures and entities by line number.

Parent topic: Compiler Listings


The -xref Option

The -xref option provides cross-reference information for each program entity, displaying the line number on which it was declared and the line numbers of all references to it.

The -xref listing for a program is added to the map listing; when you specify the -xref option, you receive a data storage allocation map by default. The cross-reference information appears on the map in the ATTRIBUTES column for each entity, after the line of map attributes information.

References to each entity are listed in the following format:

 DEF line_number REF line_number[...]

A sample map listing with the -xref option follows.

Figure 1-1 Sample Output from the -xref Option

EXTERNAL ENTRY POINTS
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES
SYSPRINT     CONSTANT                        FILE EXTERNAL
                                             DEF 41 REF 41 48 49
PRIMES       CONSTANT                        ENTRY(MAIN)EXTERNAL
PROCEDURE PRIMES ON LINE 10
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES
STORE_CLASS  CONSTANT                        ENTRY
                                             DEF 90 REF 45
ARITH_STR    CONSTANT                        ENTRY
                                             DEF 56 REF 43
PROCEDURE ARITH_STR ON LINE 56
NAME         CLASS           SIZE  LOCATION  ATTRIBUTES
DECIMAL      BUILTIN                   BUILTIN
ESC          AUTOMATIC 6     FFFFFFD8  PICTURED
FLT_BIN      AUTOMATIC 4     FFFFFFE4  FLOAT BIN(15)
                                       DEF 63 REF 71
FIX_DEC      AUTOMATIC 3     FFFFFFEC  FIXED DEC(4,2)
                                       DEF 62 REF 70
CHR_STR      AUTOMATIC 4     FFFFFFEO  CHAR(4)
                                       DEF 61 REF 69
BIT_STR      AUTOMATIC 4B    FFFFFFD4  BIT(4)
                                       DEF 60 REF 68
PROCEDURE STORE_CLASS ON LINE 90
NAME         CLASS     SIZE  LOCATION  ATTRIBUTES
NUMBER       AUTOMATIC 16B   FFFFFFE8  UNION
 FIXED_N     MEMBER    2     00000000  FIXED BIN(15,0)
 FIXED_N_BIT MEMBER    16B   00000000  BIT(16)
STAT_A_EX    STATIC    3     External  FIXED DEC(5,0)EXTERNAL
Y            BASED     4     -V-       FLOAT BIN(23)
Parent topic: Compiler Listings


The -exp Option

The -exp option produces an expanded code listing at the end of the listing file, providing the location and low-level language translation for each instruction and label in the program. The following information is displayed for each statement, in five columns:

Column | Displays
First | The source statement line number.
Second | The offset location of each instruction in the statement.
Third | The hexadecimal representation of each instruction.
Fourth | The instruction in a pseudo-assembly code dialect.
Fifth | Information about the operands used by each instruction.
Parent topic: Compiler Listings


Open PL/I Compiler Implementation Limits

The Compiler generates messages if your source program exceeds certain Open PL/I Compiler implementation limits. The following table lists these implementation limits.

Message | Limit
Depth of nesting of a structure | 16
Maximum length of an ‘external’ string constant | 30721
Maximum length of an ‘internal ’ string constant | 327672
Maximum length of a string constant with repeat specifier | 32767
Maximum length of source line | 1024
Maximum length of an identifier | 100
Maximum size of storage for AREA data | 2GB Note: Very Large area sizes may be impacted by system resources.
Array dimensions | 8
Nesting level of INCLUDE statements | 7
Nesting of DO, PROCEDURE, BEGIN, SELECT, and simple ON-unit statements | 643
Number of arguments in a subroutine or function call | 239
Number of data and format list pairs in an edit-directed specification | 256
Number of diagnostics (see the -maxmsg option in Compiler Options for information on configuring this limit.) | 1000
Maximum VSAM key size | 120 bytes
Scale factor of variables | 0 ? scale factor ? 128
Scale factor of a constant | 0 ? scale factor ? 127
Scale factor of a conversion built-in function | 0 ? scale factor ? 127
Value of a format's repeat, w, or d field | 254
Precision for a fixed binary number | 31
Precision for a fixed decimal number (maximum) | 31
Precision for a float binary number | 52
Precision for a float decimal number | 16
Internal Limits |
Number of tokens in a statement | 20,000
Parent topic: Compiling a Program
Related information
Compiler Options
1

The spelling of an external string constant (as presented in the user program) is limited to 3072 characters, where the spelling includes the surrounding quotation marks, the extra quotation mark when two single quotation marks represent a single quotation mark inside the string, and the possible combination of postfix characters such as B or X.

2

The internal spelling of a character string constant (i.e., a compiler generated string constant as the result of Restricted Expression Evaluation) of is limited to 32767 characters, where the spelling includes the surrounding quotation marks.

3

64 including the top level procedure.


Open PL/I Compiler restrictions

  • The compiler does not diagnose the use of uninitialized automatic variables in the procedure block prolog.
  • The compiler does not detect dependencies in order of evaluation of automatic variables in the procedure block prolog nor does it diagnose those dependencies.
Parent topic: Compiling a Program


Compilation Statistics

The -stat compiler option provides a listing of statistics for each phase of the compilation. The statistics are displayed at the terminal by default or can be redirected to a file. The following figure is a sample terminal display from a UNIX system.

Figure 1-2 Sample Output from the -stat Option (UNIX)

PHASE            USER     SYSTEM    CPU  REAL  13:43:26
Parser Pass 1    0.05       0.02   0.07     0  13:43:26
Declare          0.00       0.00   0.00     0  13:43:26
Parser Pass 2    0.08       0.03   0.11     0  13:43:26
Allocator        0.01       0.00   0.01     0  13:43:27
Code Generator   0.71       0.05   0.76     1  13:43:27
Total            0.85       0.10   0.95     1  13:43:27

Total source lines:                  38
Lines per minute (CPU):           2,400
Lines per minute (real):          2,280

Text size:                 2,574 bytes
Data size:                   914 bytes
Bss Size:                      0 bytes

The following names and describes each of the columns displayed in the printout.

Column | Description
PHASE | Defines the various phases of the compilation. Each phase and its corresponding statistics displays upon completion.
USER | Indicates the CPU time spent on this phase of compilation, excluding CPU time spent by the operating system on behalf of the Compiler.
SYSTEM | Indicates the CPU time used by the operating system while executing the corresponding phase.
CPU | Indicates the CPU time used by the Compiler while executing the corresponding phase. This is simply the sum of USER and SYSTEM.
REAL | Indicates the number of seconds elapsed during the corresponding phase.
The final column | Displays the current time of day in 24-hour notation (on Intel systems only).
Parent topic: Compiling a Program


Temporary Files

Compiler-generated temporary files are normally placed in the /tmp directory. If you wish to put them in your current working directory, use the command appropriate to your shell program.

Bourne/Korn shell users: | TMPDIR=. ; export TMPDIR
C shell users: | setenv TMPDIR .

To store Compiler-generated temporary files elsewhere, specify a pathname by using the command appropriate to your shell program.

Bourne/Korn shell users: | TMPDIR=pathname; export TMPDIR
C shell users: | setenv TMPDIR pathname
Windows users: | set TMPDIR=pathname
Parent topic: Compiling a Program


Optimization

By default, programs are not optimized during compilation. You can specify optimization at level 1, 2, or 3, using the following syntax:

-opt level

For example, "-opt 2". If you specify -opt with no level, level 3 optimizations are performed by default. (Remember that if you use the -deb option, only level 1 or 2 is allowed. If you use -deb and specify -opt with no level, level 2 optimizations are performed.) A brief description of the optimizations performed at each level follows.

Level | Description
1 | Operator pattern replacement and Boolean conditional expression optimizations.
2 | Common subexpression elimination; all level 1 optimizations.
3 All level 1 and level 2 optimizations plus the following:
  • branch chaining
  • dead code elimination
  • strength reduction
  • loop induction
  • loop invariant code motion
  • removal of redundant register saves and loads
  • removal of mathematical identities
  • peephole optimizations
  • constant folding
Parent topic: Compiling a Program


Linking a Program

Attention: You must recompile and relink your Open PL/I applications to use them with this Enterprise Developer release.

To link an Open PL/I program, use either mfplx or ldpli.

  • mfplx compiles and links in one step, automatically invoking ldpli if the -c option is not used. For the use of mfplx, see the section mfplx Syntax .
  • ldpli links pre-compiled objects, and is the recommended link command when using mfpli. For the use of ldpli, see the section mfplx Syntax .

To link, creating a non-shared executable, use

ldpli MODULE1.o [MODULE2.O [MODULEn.o]] [options…]

To create an executable to run under Enterprise Server you also need to add to the command one of the options below:

  • -systemmvs - for programs executed under the control of JCL.
  • -systemims - for programs executed under the control of IMS.
  • -systemcics - for programs executed under the control of CICS.
  • Link Options
  • Using ldpli
  • Creating a Shareable Library
  • Creating a DLL
Parent topic: Using Open PL/I
Related information
Creating a Shareable Library
mfplx Syntax


Link Options

The table below lists link options that permit the use of Open PL/I with other software products. For more information, see the section Using Open PL/I with Other Software Products.

Option | Explanation
-mvs | Allows linking of programs running under the control of JCL. Note: -mvs is deprecated and will be removed in a future release. Please use the -systemmvs option instead.
-ims | Allows linking of programs running under the control of IMS. Note: -ims is deprecated and will be removed in a future release. Please use the -systemmims option instead.
-cics | Allows linking of programs running under the control of CICS.
-db2 | This option is required for the mfdb2 preprocessor, which is deprecated. Please use the EXEC preprocessor (invoked by -sql db2).
-systemcics | Compiles and/or links to execute under CICS.
-systemims | Compiles and/or links to execute under IMS.
-systemmvs | Compiles and/or links to execute under MVS.
-dll | Generates a dynamically linked library.
-so | Generates a shared object.
-strip | Tells ldpli to strip the debugging information.
-nostrip | Tells ldpli to not strip the debugging information. This is the default.
-o | Specifies executable file name.
-L | Specifies library search path.
-l | Specifies library.
-Q [option] | Specifies nativeld options.
-verbose/-stat | Prints information/statistics to the standard output as each linker phase completes.
-version/-v | Shows the version number of the linker.
-fixedvalidate | Causes the RTS to turn on additional checking to ensure that FIXED DECIMAL field contents are can contain characters 0 through 9 and CDF hex values. This option raises the CONVERSION condition if the assignment or the result of a math operation causes the FIXED DECIMAL field to contains an invalid character. The default is -nofixedvalidate.
-fixedoverflow | Enables checking that raises the SIZE condition if an operation causes a FIXED DECIMAL value to overflow. The default is -nofixedoverflow.
-z | Creates a shared library suitable for use with cob.
Note: System linker options are not accepted directly. They can be added using the -Q option.
Note: To create a UNIX/Linux shareable object that can be run under Enterprise Server, you must use ldpli or mfplx. For more information, see Creating a Shareable Library.
Parent topic: Linking a Program
Related information
Creating a Shareable Library
Using Open PL/I with Other Software Products


Using ldpli

Attention: You must recompile and relink your Open PL/I applications to use them with this Enterprise Developer release.

ldpli references the components, such as libraries, that were installed with Open PL/I. ldpli generates executable files and shared libraries from relocatable object files.

Tip:

The first and fourth characters of the ldpli command are lowercase letter "L".

The ldpli command-line syntax is as follows:

ldpli [option] ... object_file [object_file] ... [optional_library] ...

where

ldpli | The command that invokes the linker.
option | Represents the linker options. To see all valid options enter the ldpli command with no arguments. Note: System linker options are not accepted directly. They can be added using the -Q option.
object_file | Specifies object files that are to be linked.
optional_library | Represents library specifications for libraries that are required for your special application. These are needed only if you explicitly CALL library routines from your program. The standard system libraries, such as libc.a on a UNIX system, are always included in the link.
Note: If linking using your own shell scripts and/or driving ld directly, you must change from using -lmf to use -lmfpliz (PL/I in Enterprise Developer) or -lmfpli (Open PL/I). libespli.so and libespliz.so are no longer used.
  • Using ldpli with Windows Systems
Parent topic: Linking a Program


Using ldpli with Windows Systems

In addition to supporting all LINK32 options, ldpli includes the following support for Windows systems:

  • Indirect files (@ files).
  • The -# option, which echoes the command line used to invoke LINK32. This can also be used to redirect output for later use in indirect files.

ldpli enhances the default behavior of the following LINK32 options:

  • If -out:filename is not specified, ldpli will generate an executable file with an extension .exe using the basename of the first object file rather than defaulting to noname.exe.
  • If -map is specified without specifying the filename (-map:filename), ldpli will generate a map file with the extension .map using the basename of the first object file.

If -deb was used on the command line at compilation time for debugging purposes with CodeWatch, -deb must also be supplied on the command line to ldpli. If using mfplx for both compilation and linking, mfplx will automatically invoke ldpli with -deb.

Note: If linking using your own shell scripts and/or driving ld directly, you must change from using -lmf to use -lmfpliz (PL/I in Enterprise Developer) or -lmfpli (Open PL/I). libespli.so and libespliz.so are no longer used.
Parent topic: Using ldpli


Creating a Shareable Library

Open PL/I can be used to create shareable libraries (also known as shared libraries) on any supported operating system.

To produce code that can be included in a shareable library, you must ask Open PL/I to produce position-independent code by using the -pic option. Once you have object files generated as position-independent code, you link them into a shareable library using the -so option to ldpli or mfplx.

Note: The -pic option is not required and has no effect for AIX, because all Open PL/I code on AIX is position-independent.

Example: Creating a shareable library using mfplx

File lib1.pli:

library_one: proc;
display('This is library routine one');
end;

File lib2.pli:

library_two: proc;
display('This is library routine two');
end;

File myprog.pli:

dcl library_one entry;
dcl library_two entry;

foo: proc options(main);
call library_one;
call library_two;
end;

Compile and link using commands:

mfplx –pic –so –omylib.so lib1.pli lib2.pli
mfplx –omyprog myprog.pli mylib.so

Example: Using a shared object as a fetchable program

Note: If you intend to use your shared object as a fetchable program, it is important to note that your PL/I proc needs to have the same external name as the shared object or Open PL/I will not be able to load the .so.

File myfetch.pli:

myfetch: proc external(‘myfetch’);
display(‘Inside fetchable function’);
end;

File myprog.pli:

dcl myfetch entry options(fetchable) external(‘myfetch’);

foo: proc options(main);
call myfetch;
end;

Compile and link using commands:

mfplx –pic –so –omyfetch.so myfetch.pli
mfplx –omyprog myprog.pli
Parent topic: Linking a Program


Creating a DLL

To create a .dll, you need to compile and link one or more object files. This is done by using the command below:

mfplx newdll.pli -deb -defext -dll

In this example, newdll.pli is your source file. You compile and link it in one step with the command-line driver mfplx.

-deb produces debugging information for CodeWatch.

-defext causes external variables to be defined in the .data section. You must use the link option -dll to create a .dll.

You also need to add to the command one of the options below:

  • -mvs - for programs executed under the control of JCL.
  • -ims - for programs executed under the control of IMS.
  • -cics - for programs executed under the control of CICS.
  • -db2 - for programs executed under the control of DB2.
Parent topic: Linking a Program


Running a Program

To run an Open PL/I program, invoke the executable object file produced by the link utility.

The name of the executable object file produced by the linker defaults to a.out. However, if you include the -o filename option on the link command line, the executable object file has the filename that you specified.

For example, "-o sample" on the mfplxldpli command line produces an executable object file named "sample".

  • Run-time Errors
  • Accessing Command-Line Arguments in Open PL/I Programs
  • Associating a Logical Open PL/I File with a Physical Disk Data File
  • Using CodeWatch
Parent topic: Using Open PL/I


Run-time Errors

If an error occurs at run time, a message appears on the terminal.

You can use Open PL/I's ON statement to develop handlers for the conditions that can occur in your program. The ON ERROR statement can be used for arbitrary errors. The ONLOC built-in function can be used in an ON-unit to report the name of an entry in which a condition was raised, and the ONCODE built-in function can be used to report the status value of a run-time error.

Note:

If an error is not caught by an ON-unit, Open PL/I displays the source file and line number where the error occurred. For these features to work, however, you must have compiled the source file with the default option -unixdebug.

This feature is currently available only in the Sun Solaris 2 and IBM AIX versions of Open PL/I.

When a fatal error condition occurs at run time, a message is displayed naming the condition that has been raised; the program address where this occurred; and the source file, entry, and line number at which the condition was raised, as well as the lines in each procedure above it in the call stack. For example:

*** Condition ERROR raised
***Unhandled condition ZERODIVIDE at PC=00010233
CALCDIV line 26 in /dirl/dir2/calcs.pl1
SUBR3 line 444 in /dirl/dir2/subprog.pl1
MYPROG line 871 in /dirl/dir2/mainprog.pl1

In this example,

CALCDIV | Is the entry in which the "ZERODIVIDE" condition was raised.
SUBR3 | Is the entry that called "CALCDIV" (at line 444).
MYPROG | Is the program that called SUBR3.

If you have compiled your program using the -nounixdebug option, only the program address where the condition was raised will be displayed:

*** Condition ERROR raised
*** Unhandled condition ZERODIVIDE at PC=00010233
Parent topic: Running a Program
Related information
Open PL/I Run-time Error Messages


Accessing Command-Line Arguments in Open PL/I Programs

It is sometimes useful to be able to execute a program specifying one or more arguments on the command line in order to cause a variation in the program's behavior. For example, to run a departmental expense report program, you might issue the command deptexp summary to indicate that you wish to see only category totals rather than all the line items.

Command-line arguments can be accessed in a PL/I main program using the following technique:

/* PL/I main program accessing command line args. */

PMAIN: PROCEDURE OPTIONS(MAIN);

   dcl getargc entry() returns(fixed bin(31)) external('__lpi_get_argc' );
   dcl getargv entry() returns(pointer) external('__lpi_get_argv' );
   DECLARE ARGC_     FIXED BIN(31) NATIVE init(getargc());
   DECLARE ARGV_     POINTER              init(getargv());
   DECLARE ARG(10)   POINTER BASED;
   DECLARE ARGS      CHAR(50) BASED;
   DECLARE ARGSV     CHAR(50) VARYING;
   DECLARE I         FIXED BIN(31);

   PUT SKIP EDIT(ARGC_)(f(2));
   DO I = 1 TO ARGC_;
      ARGSV = SUBSTR(ARGV_->ARG(I)->ARGS,1,
            INDEX(ARGV_->ARG(I)->ARGS,BYTE(0))-1);
      PUT SKIP EDIT('"',argsv,'"')(a,a,a);
      END;
   PUT SKIP;

   END PMAIN;

If your PL/I program is controlled by a C main program, you can pass the command-line arguments through to the PL/I program in the following manner:

/* C main program calling PL/I subroutine */

main(argc,argv)
   int argc;
   char **argv;
{
   PSUBR(argc,argv);
}

/* PL/I subroutine receiving command line args
   from C main program */

PSUBR: PROCEDURE(ARGC,ARGV);

   DECLARE ARGC      FIXED BIN(31) VALUE;
   DECLARE ARGV      POINTER VALUE;
   DECLARE ARG(10)   POINTER BASED;
   DECLARE ARGS      CHAR(50) BASED;
   DECLARE ARGSV     CHAR(50) VARYING;
   DECLARE I         FIXED BIN(31);

   PUT SKIP EDIT(ARGC)(f(2));
   DO I = 1 TO ARGC;
      ARGSV = SUBSTR(ARGV->ARG(I)->ARGS,1,
            INDEX(ARGV->ARG(I)->ARGS,BYTE(0)));
      PUT SKIP EDIT('"',ARGSV,'"')(a,a,a);
      END;
   PUT SKIP;

END PSUBR;
Parent topic: Running a Program


Associating a Logical Open PL/I File with a Physical Disk Data File

Open PL/I supports a number of ways to associate your physical disk data files with the logical file names used in Open PL/I sources.

  • Method 1 (Default)
  • Method 2
  • Method 3
Parent topic: Running a Program


Method 1 (Default)

The run-time environment will use the name of the file variable (or constant) used in the source, shifted to all uppercase.

Example

dcl Payroll file input;
open file(Payroll);

A file named PAYROLL will be used for all I/O operations using file Payroll.

Parent topic: Associating a Logical Open PL/I File with a Physical Disk Data File


Method 2

Using the TITLE option on the OPEN statement allows one to specify an explicit disk file name with an optional directory prefix. The use of the TITLE option takes precedence over method 1.

Example

dcl Payroll file input;
open file(Payroll) title ('/global/acct/sep-95.days')

A file named /global/acct/sep-95.days will be used for all I/O operations using file Payroll.

dcl Payroll file input;
dcl filename character(100) varying;
<assignment into filename>
open file(Payroll) title (filename);
                                   /* Using a variable name */

The value of filename determines the file that will be used for all I/O operations using file Payroll.

Note:

Once the file has been opened, changing the value of filename will have no impact. The association is made only once, at the time of the open.

Parent topic: Associating a Logical Open PL/I File with a Physical Disk Data File


Method 3

The physical disk file name can be specified with the use of UNIX shell environment variables. This method takes precedence over methods 1 and 2. This method allows you to easily alter the physical disk file used for different invocations of the same application.

The environment variable name is the value of the derived name from either of the above methods with MF_ or DD_ prefixed.

Example

dcl file data2 update;
dcl file specs output;

open file (data2);
open file (specs) title('report');

By setting the following environment variables:

  • setenv MF_DATA2 /common/data
  • setenv MF_REPORT /common/report

I/O operations for file data2 will access /common/data and I/O for file specs will access /common/report.

Note that to override the name for file variable "specs", the name MF_REPORT was used, because of the title option on its OPEN statement.

In the above example, environment variables of the names DD_DATA2 and DD_report would also be allowed.

Note:

To assign a physical file to the following special file declarations you will need to use the corresponding environment variables:

SYSIN | use DD_STDIN
SYSPRINT | use DD_STDOUT
SYSOUT | use DD_STDOUT
Parent topic: Associating a Logical Open PL/I File with a Physical Disk Data File


Using CodeWatch

CodeWatch is a powerful software development tool that can help you locate bugs in your Open PL/I programs. There are two versions of CodeWatch available with Open PL/I:

  • a command-line interface
  • a Windows interface

The command-line version offers a traditional line-oriented interface allowing you to interactively enter commands from the keyboard. The Windows interface offers at least two main windows: one that allows you to enter commands and one that allows you to view your source code. You access CodeWatch commands through pulldown menus and dialogs. The Windows interface runs on a graphical workstation running X-Windows.

CodeWatch enables you to control program execution to set breakpoints, monitor what is happening, examine static type data, and evaluate results. CodeWatch keeps track of variables, subroutines, and data types in terms of the symbols used in the source language. You can reference these items without having to consider the underlying machine language or architecture. You can use CodeWatch to access the source text of the program, to identify and reference program entities, and to detect errors in the program's algorithms and logic.

Note: Your programs must be compiled using the -deb option before they can be run under the control of the debugger. (Every module need not be compiled in -deb mode, but at least one must be; CodeWatch debugs only the modules compiled in -deb mode.) When executed with the -deb option, the Compiler generates a separate symbol table file, filename.stb, in the current directory. filename.stb contains symbolic information that the debugger uses to reference and manipulate source program symbols and entities; set breakpoints, tracepoints, and watchpoints; and control program execution.

See the CodeWatch User's Guide for detailed information on CodeWatch.

Parent topic: Running a Program


Program Debugging

  • Using PLIDUMP
  • Debugging CICS Applications with EXEC CICS LINK Statements
    Describes how to PL/I that calls a CICS program using EXEC CICS LINK.
  • PL/I Debugging in JCL and IMS
    Provides a debugging strategy for programs JCL- or IMS-based programs in PL/I
Parent topic: Using Open PL/I


Using PLIDUMP

This section describes dump options and syntax used to call PLIDUMP, and describes PL/I-specific information included in the dump that can help you debug your programs.

This shows an example of a PL/I routine calling PLIDUMP to produce a Program Environment dump. In this example, the main routine PLIDMP calls PLIDMPA, which then calls PLIDMPB. The call to PLIDUMP is made in routine PLIDMPB.

%PROCESS MAP GOSTMT SOURCE STG LIST OFFSET LC(101);
 PLIDMP: PROC OPTIONS(MAIN) ;

   Declare   (H,I) Fixed bin(31) Auto;
   Declare   Names Char(17) Static init('Bob Teri Bo Jason');
   H = 5;	 I = 9;
   Put skip list('PLIDMP Starting');
   Call PLIDMPA;

     PLIDMPA:  PROC;
       Declare (a,b) Fixed bin(31) Auto;
       a = 1;	 b = 3;
       Put skip list('PLIDMPA Starting');
       Call PLIDMPB;

         PLIDMPB:  PROC;
           Declare  1 Name auto,
             2 First   Char(12) Varying,
             2 Last    Char(12) Varying;
           First = 'John';
           Last = 'Thompson';
           Put skip list('PLIDMPB Starting');
           Call PLIDUMP('TBFC','PLIDUMP called from procedure PLIDMPB');
           Put Data;
         End PLIDMPB;
     End PLIDMPA;
 End PLIDMP;

This example is referenced throughout this section.

Consider the following when using PLIDUMP:

  • Use a unique user-identifier for each PLIDUMP invocation when calling PLIDUMP a number of times in a routine. This simplifies identifying the beginning of each dump.
  • A DD statement with the ddname PLIDUMP can be used to define the data set for the dump. Any data set defined by these DD statements should specify a logical record length (LRECL) of at least 300/304 to prevent dump records from wrapping. If using SYSOUT as the target in any of these DDs, specify MSGFILE(SYSOUT,FBA,300,0) or MSGFILE(SYSOUT,VBA,304,0) to prevent line wrapping.
  • If you want the program unit name, program unit address, and program unit offset listed correctly in the dump traceback table, compile your PL/I program with the -debug option. The -debug option can be used with the -opt or -opt3 options. To get symbols and line information in the dump, you must compile using the -debug option to generate the .stb files.
  • Generated .stb files should either be stored in the same location as the .exe, .dll or .so files. or in a location specified by the environment variable CODEWATCH_STBPATH. Otherwise the dump generated by PLIDUMP contains much less useful information.
  • On Windows platforms, an additional .pdb file must also be stored in one of the concatenated directories referenced by the CODEWATCH_STBPATH environment variable or stored in the same location as the .dll it is associated with. Otherwise a S0C4 abend may occur while trying to process the call stack when running under Enterprise Server.

Using PLIDUMP to generate a dump of your PL/I routine helps to ensure portability across system platforms.

  • Finding Variables in PLIDUMP Output
Parent topic: Program Debugging


Finding Variables in PLIDUMP Output

Compile your program with the MAP option to find variables in the PLIDUMP output. The MAP option tells the compiler to add a table to the listing that shows the offset within AUTOMATIC and STATIC storage of all level-1 variables that are AUTOMATIC or STATIC.

  • Finding AUTOMATIC Variables
Parent topic: Using PLIDUMP


Finding AUTOMATIC Variables

AUTOMATIC variables automatically display in the dump. You do not need to find offsets within automatic using the output from the MAP option.

STATIC and CONTROLLED variables are currently not used.

Parent topic: Finding Variables in PLIDUMP Output


Debugging CICS Applications with EXEC CICS LINK Statements

Use this command in the PL/I debugger before the LINK statement runs to debug called programs in code when the EXEC CICS LINK statement is used.

shlib [pgm].dll

where [pgm] is the name of the program executed with EXEC CICS LINK.

Executing this command before the LINK statement runs raises a load event (signal #6) when the program loads prior to execution.

This program contains a link to the program PGMB using EXEC CICS LINK.

PGMA: proc(comm_ptr) options(main,reentrant) reorder;
  dcl comm_ptr pointer;
  dcl data_lngth        fixed bin(15) init(100);
  dcl commarea char(100) based(comm_ptr);

  if eibcalen = 0 then
    do;
      alloc commarea set(comm_ptr);
      commarea = '%from pgma';
    end;
  else;

  exec cics link
      program('pgmb ')
      commarea(commarea)
      length(data_lngth);

  free commarea;

  exec cics return;
end;

In this sample, executing the command shlib pgmb.dll before the LINK statement runs causes the debug session to raise the load event before the program loads. Once the load event is received, executing the ENV command (in this case ENV pgmb) to the new program allows you to then set one or more breakpoints before continuing execution. Note that shlib works on the filename level, so the file extension is required in the command.

Parent topic: Program Debugging


PL/I Debugging in JCL and IMS

PL/I programs containing EXEC SQL, EXEC CICS, or EXEC DLI statements can use the preprocessor -optexec option with the plitest parameter. This causes the preprocessor to inject a PL/I macro into the code. The macro invokes the debugger through an infused PLITEST() call. This is done automatically and does not require editing a side file such as PLIDEBUG.DAT. It also does not require knowledge of explicit CodeWatch commands.

However, this debugging method cannot be used for batch programs that do not have EXEC language capability, or for IMS-based programs that use PLITDLI instead of EXEC DLI.

For these types of programs, you can use a technique similar to that used by the EXEC preprocessor, but in the PL/I Macro preprocessor, to automatically generate a PLITEST() call.

  1. Put the following code anywhere within the execution path of the program to be debugged:
    %if ATTACHDEBUGGER %then
%do;
    DCL JAVAUI FIXED BIN(31) NATIVE VALUE(1);
    CALL PLITEST("shlib " || procedurename() || ".dll;" ||
                 "env "   || procedurename() || ";br STARTDEBUG;" ||
                 "br %exit [det;q];c",
                 " ", JAVAUI);
    STARTDEBUG:;
%end;

    This code causes a debugger to automatically attach itself during program execution, and stop on the STARTDEBUG label.

    Note: The above code assumes a Windows environment with the assumption that a .DLL is being used. If working in a UNIX environment, just replace .dll with .so. It uses the PL/I built-in function PROCEDURENAME() to dynamically determine the environment and the shlib argument.
  2. If compiling the program from the command line, add the following options to the mfplx command (or just the -define option if invoking mfpp explicitly):
    –deb -macro -define attachdebugger
  3. Start the Enterprise Server and execute the program.
    Note: If working in a Windows environment, the Enterprise Server must be started from an Enterprise Developer command prompt using casstart, or the debugger won't be attached.

In the code sample, the %if..%do condition is functionally similar to $IF in COBOL or #ifdef in C. The sample as a whole is a functional equivalent to CBL_DEBUGBREAK, with the added capability of being ably to specify any additional CodeWatch commands, such as setting breakpoints, to be executed upon startup.

Parent topic: Program Debugging


Using Open PL/I with Other Software Products

Because Open PL/I supports a wide range of data types and because it supports standard calling sequences, Open PL/I can be used with many other software products. These include other Micro Focus products as well as products from other companies. This section lists some of the products that Open PL/I is known to work with and gives some hints about using them with Open PL/I.

  • Open PL/I Migration Issues and Restrictions
    Lists migration issues related to Open PL/I
  • DB2
  • C++/Views
  • Open PL/I and Informix
  • Open PL/I and IBM WebSphere MQ
Parent topic: Using Open PL/I


Open PL/I Migration Issues and Restrictions

These are issues related to migrating Open PL/I programs to PL/I in Enterprise Developer.

  • If you are using DSNTIAR or DSNTIAC APIs, you must delete declarations (DECLARE) of any entry point(s).
  • DB2 LUW does not support ROWSET operations.
  • Because DB2 LUW does not support arrays, the DB2 LUW ECM also does not support arrays. As a result, MFEXECPP can stop responding if it attempts to use a host variable that is an array of structures.
  • As PL/I projects only compile for x86 platforms, some of the upgraded projects might target unsupported platforms and might not be configured to build. You must open the solution properties and, on the Configuration Properties, ensure all projects are set to build and set their target platform to x86.
Parent topic: Using Open PL/I with Other Software Products


DB2

Open PL/I can be used with the IBM's DB2 database system. Open PL/I has a preprocessor for embedded EXEC SQL statements in your PL/I programs, and a DB2 LUW preprocessor used by COBOL applications that is based on the HCO for DB2 LUW preprocessor.

Note:

Since the HCO for DB2 LUW preprocessor must connect to the DB2 LUW server to convert EXEC SQL statements to API calls, you must use the DB option for PL/I when building applications using SQL. Invoke the DB2 LUW preprocessor with the -db2 option to the mfplx command.

Open PL/I's DB2 support is license managed. You must obtain a special license from Micro Focus to use it.

You must also have IBM's DB2 product, or the IBM DB2 LUW DS Client V9.5 or later, and your system path must be set to the include the install product location.

Parent topic: Using Open PL/I with Other Software Products
Related information
Precompiler and Preprocessor Order of Execution
Open PL/I SQL Options


C++/Views

C++/Views is Intersolv's object-oriented graphical user interface (GUI) program framework. C++/Views includes an interactive graphical designer, as well as an extensive C++ class library. Using C++/Views, you can create the framework for an application with an attractive and efficient graphical user interface. Your C++ framework can then call procedures written with Open PL/I to do your ordinary data processing work.

C++/Views is not yet available on the following platform supported by Open PL/I:

  • Intel-based computers running UNIX SVR4 or Windows
Parent topic: Using Open PL/I with Other Software Products


Open PL/I and Informix

Open PL/I follows the native C compiler's naming conventions. This allows you to mix subroutines and functions compiled with Open PL/I with any other language or third-party library that supports a C language interface. However, you must link the Open PL/I run-time libraries into the final stand-alone program. The -cisam link option enables the C-ISAM package from Informix for VSAM/indexed files.

Informix fully documents their Application Programming Interface for the C language. In general, you should follow the Informix directions for mixing Informix and C, simply treating the modules compiled with Open PL/I as C modules.

The following examples illustrate the command used to link an Open PL/I program that uses the Informix libraries. For the purposes of this illustration the Open PL/I Compiler and Informix modules are running on a Sun Solaris system. The Open PL/I modules are called "testobj1.o" and "testobj 2.o", the Open PL/I Compiler has been installed in /opt /pl1, and the environment variable $MFPLI_PRODUCT_DIR has been set to that directory.

ldpli testobj1.o testobj2.o -o testprogram
/opt/informix/lib/esql/libsql.a
/opt/informix/lib/esql/libgen.a
/opt/informix/lib/esql/libos.a
/usr/ucblib/libucb.a
/opt/SUNWspro/SC3.0/lib/cg92/_fstd.o

Note that the names and locations of the Open PL/I and Informix libraries are specific to your installation of Informix and Open PL/I. This illustrates a typical installation.

Parent topic: Using Open PL/I with Other Software Products
Related information
Language Concepts


Open PL/I and IBM WebSphere MQ

You can create and run PL/I applications with Enterprise Developer that perform messaging using IBM WebSphere MQ software. The integration must be done on machines that have both Enterprise Developer and IBM WebSphere MQ software installed. See the PL/I tutorials section of the help for more information on installation requirements, supported releases, and using PL/I with IBM WebSphere MQ software.

Parent topic: Using Open PL/I with Other Software Products


Using the PL/I Message User Exit

The PL/I message user exit allows an installation to monitor compile-time and run-time issued messages. Every message that is issued by various PL/I components is presented to the user exit. If it is a compiler-issued message, it is then subjected to the -f compile-time option.

The user exit can:

  • Do nothing and allow the message to be processed by PL/I as is.
  • Change the severity of the message one severity level up or down. Note that I-level (severity level 0) cannot be lowered and U-level (severity level 4) cannot be raised. Thereafter, the message will be issued as is (with the same exact text, including severity level) with a "+" (for raised severity) or "-" (for lowered severity) indication but the new severity will be used for return code purposes.

    Example:

    plisql1.pp (0,0) : Error MPLIE00042W : Errors have ...

    If the severity is lowered, the message will be shown as:

    plisql1.pp (0,0) : Warning MPLIE00042W-: Errors have ...

    The return code will be 4 instead of 8.

    If the severity is raised, the message will be shown as:

    plisql1.pp (0,0) : Severe MPLIE00042W+: Errors have ...

    The return code will be 12 instead of 8.

    Upon return from the exit, the message is not subjected to the -f option. Note the + or - sign that follows MPLIE00042W as this indicates the change in severity.

  • Suppress the message altogether. The severity of the suppressed message still carries through and participates in return code evaluation.
    Important: We strongly recommend that you do not suppress run-time messages.
Note: The user exit API is a trusted interface and is running as part of PL/I and therefore could affect the stability of the run-time system and of the compiler and other components involved.

Enterprise Developer provides a skeleton default user exit that you can modify to suit your needs. It can be used to gather compile-time information for later or real-time analysis. Ensure that your modified user exit either takes precedence over or replaces the provided skeleton user exit.

The compile-time user exit should be built as follows:

  • On Windows:
    mfplx mfplictx.pli -macro -dll -native -opt -nolaxdcl -vax -pp mfplictx.pp”
  • On UNIX:
    mfplx mfplictx.pli -macro -dll -native -opt -nolaxdcl -vax -pp mfplictx.pp -o mfplictx.so

It must have an executable name of mfplictx (lower case) and be placed in a directory that is on the search path (PATH on Windows, LD_LIBRARY_PATH on Linux and Solaris SPARC, and LIBPATH on AIX).

Parent topic: Using Open PL/I


Linking an Open PL/I Application Using Separate Shared Objects for Each Subroutine

Open PL/I allows you to link applications in such a way that all called subroutines are linked as separate shared objects (.so). This functionality is available on any of the following operating systems:

  • SUSE Linux
  • Red Hat Linux
  • Solaris SPARC
Parent topic: Using Open PL/I
Related information
Linking a Program


Compiling, Linking and Debugging of Fetchable Procedures

  • Compiling and Linking of Programs That Are to Be Used As Fetchable Procedures
  • Debugging of Fetchable Procedures
Parent topic: Using Open PL/I


Compiling and Linking of Programs That Are to Be Used As Fetchable Procedures

On UNIX/Linux, mfplx and ldpli support two synonymous options, -dll and -so on all platforms. To compile a program to be used as a fetchable procedure, enter the command:

mfplx -dll -defext -pic myfetch.pli

or

mfplx -so -defext -pic myfetch.pli
Tip: On UNIX/Linux, when compiling a program to be used as a fetchable procedure, use the -pic compiler option.

If your fetchable program contains a subroutine, the syntax is:

mfpli -defext -pic suba.pli -o suba.obj
mfplx -dll -defext -pic myfetch.pli suba.obj  -o MYFETCH.so

Use the appropriate output extension compiler option for your operating system (-dll or -so).

You can use the -dll or -so options with the ldpli command as shown:

ldpli -so myfetch.obj suba.obj -o MYFETCH.so

The output executable image is in upper case. By default, Open PL/I generates uppercase external references. For example, the source statement in a main program fetch myfetch; searches for the executable MYFETCH.so. If linked as myfetch.so (lower case), it is not found and ONCODE 9250 is triggered.

Note: The compiler options -mvs, -ims, -cics should only be used for the OPTIONS(MAIN) programs. The use of -dll or -so indicates that it is a dynamically linked called subroutine.
Parent topic: Compiling, Linking and Debugging of Fetchable Procedures
Related information
Restrictions


Debugging of Fetchable Procedures

To debug the logic contained within a fetchable procedure you need to use the shlib command to load its symbolic information into the debugger. If you want to stop the debugger just before the invocation of MYFETCH, use the following command:

shlib MYFETCH.soMYFETCH.dll

As result of this a breakpoint will be set when MYFETCH.soMYFETCH.dll is loaded and you can then use the env command to switch to the appropriate source code display within MYFETCH.soMYFETCH.dll and set breakpoints where you think it is appropriate.

If you do not issue the shlib command, the execution will work as expected but you won't be able to debug MYFETCH. Additionally, if a trap occurs within MYFETCH.soMYFETCH.dll you will not see the source line where the trap occurred but will simply receive a message indicating a hex offset with MYFETCH.

Parent topic: Compiling, Linking and Debugging of Fetchable Procedures


Data File Tools Support for PL/I

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

The Data File Tools enable you to create record layout and segment layout files using Open PL/I structures. The Data File Editor and IMS Database Editor use these layout files to present records or segments a a formatted data item view that enables easier editing.

When you compile a PL/I program for debug, Enterprise Developer creates an output file containing the PL/I structures that are required as input for the Record Layout Editor and the Segment Layout Editor Data File Tools, which use the information to map PL/I data item types to the COBOL data item types used by the Data File Editor and IMS Database Editor Data File Tools. The output file is added to your Enterprise Developer project, and has a .adt file extension.

  • PL/I to COBOL Data Item Type Mapping
    Describes how the Data File Tools map PL/I data item types to COBOL data item types.
  • Creating and Using a Record Layout File
  • Creating and Using a Segment Layout File
Parent topic: Using Open PL/I


PL/I to COBOL Data Item Type Mapping

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

PL/I data item types are mapped to COBOL data item types for use within the Data File Editor and IMS Database Editor.

Open PL/I data item type COBOL data item type Comments
char(n)

pic x

Treated as a character string

pic '(n)9'

pic 9  <= 18 digits
pic x   > 18 digits

9 and V symbols are supported

Treated as a character string

 pic '(n)Z9'

pic x

When containing symbols other than 9 and V, treated as a character string

fixed bin(1) - fixed bin(31)

  native1
  non-native

comp-5
comp

PL/I treats length 1 to 6 as length 7

fixed dec(1) - fixed dec(31)

  native
  non-native

comp-3 <= 18 digits
        > 18 digits

Formatted editing allowed

Formatted editing indicates data item contains an illegal value

float bin(1)- float bin(24)

comp-1

Editing disabled for Floating Point

float bin(25) - float bin(52)

comp-2

Editing disabled for Floating Point

float dec(1) - float dec(6)

comp-1

Editing disabled for Floating Point

float dec(7) - float dec(16)

comp-2

Editing disabled for Floating Point

char(n)var

  native1
  non-native

pic x

comp-5 length
comp   length

Treated as a character string plus two bytes for the length preceding the string

widechar(n)

pic x

Treated as a character string of two bytes times n

widechar(n) var

  native1
  non-native

pic x

comp-5 length
comp   length

Treated as a character string of two bytes times n plus two bytes for the length preceding the string

bit(n)

pic x

Bits mapped to the byte(s) that contain them with an indication shown for the bit positions occupied, e.g., (--bbb---)

Note: PL/I bit storage format is either bit swapped or left to right.
pointer

pointer

structure

group item

union

group item
1The native option could present problems for data files that contain comp-5 binary fields. Data File Tools cannot interpret files created on a byte swapped platform that are subsequently moved to a non-byte swapped platform. In this case, where files are used on different byte order platforms, specify the non-native option instead.

Mapping Restrictions

The following Open PL/I data item types are not supported in their original form, but are mapped to a form of COBOL pic x as indicated:

Open PL/I data type item COBOL pic x
char varying

pic x(n +2 for length bytes)
bit

pic x(len/8)

widechar

pic x(n*2)

widechar varying

pic x(n*2 + 2 for length bytes)

The following Open PL/I data item types are not supported:

  • PL/I unique features such as BIT and OFFSET not present in COBOL
  • BASED data items with the REFER option; however, data items up to the first REFER are included in the structure description
  • Arrays of more than three dimensions
  • Arrays with lower bounds of zero or a negative value
Parent topic: Data File Tools Support for PL/I


Creating and Using a Record Layout File

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

The record layout allows you to edit the records in a data file using the right pane of the Data File Tools window. To create a record layout file:

  1. Right-click on the PL/I program file containing the record data and select Compile to compile it.
  2. Right-click on the PL/I program file containing the record data and select Create Record Layout File to open it in the Layout window. The Data File Tools Layout editor appears with the selected file loaded. The file's data structures display in the left pane, with data from the declarations displaying as separate nodes under the Declarations folder.
    Note: If the character sets used in the Data File Tools editor and the file being opened differ, a message box appears asking if you want to use the character set specified for the file or the character set used in the editor.
  3. To see the record layouts for a given node in the Declarations folder, click and drag the node from the left pane to the right pane. The New Record Layout dialog box appears.
  4. Choose Next, then Finish.
  5. Save the file with the same name as the data (.dat) file, but with a .str extension. So if, for example, the data file is mydata.dat, you must name this file mydata.str in order for the Data File Editor to be able to display the record layout properly.

Loading the record layout in the Data File Editor

Once the .str file is created for a data file, you can view and edit the records in the right pane of the Data File Editor.

  1. In the Solution Explorer, double-click the data file to open it in the Data File Editor.
    Note: The Data File Editor shows the file in the raw display if the .str and .dat names are not the same.
  2. Choose File > Data File Editor > Load record layout.
  3. Select the .str file that was created from the .dat file.

    The file loads in the Data File Editor with the records properly formatted in the right pane.

  4. Edit records as needed. Changes are saved as soon as they are made in the Data File Editor.

For complete information on using these Data File Tools, see Record Layout Editor and Data File Editor.

Parent topic: Data File Tools Support for PL/I
Related concepts
Record Layout Editor
Data File Editor


Creating and Using a Segment Layout File

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

The segment layout allows you to edit the IMS segments in a data file using the right pane of the Data File Tools window. To create a segment layout file:

  1. Right-click on the PL/I program file containing the record data and select Compile to compile it.
  2. Right-click on the PL/I program file containing the record data and select Create Segment Layout File.
  3. Select an IMS database from the list; then click Create to open the layout file in the Layout window. The Data File Tools Layout editor appears with the selected file loaded. The file's data structures display in the left pane, with data from the declarations displaying as separate nodes under the Declarations folder.
    Note: If the character sets used in the Data File Tools editor and the file being opened differ, a message box appears asking if you want to use the character set specified for the file or the character set used in the editor.
  4. To see the segment layouts for a given node in the Declarations folder, click and drag the node from the left pane to the right pane. The New Segment Layout dialog box appears.
  5. Choose Next, then Finish.
  6. Save the file with the same name as the IMS database (.dbd or .psb) file, but with a .slf extension. So if, for example, the database file is mydata.dbd, you must name this file mydata.slf in order for the IMS Database Editor to be able to display the segment layout properly.

Loading a segment layout in the IMS Database Editor

Once the .slf file is created for a database, you can view and edit the segments in the right pane of the IMS Database Editor. If the IMS database file and the segment layout file have the same file prefix name, the IMS Database Editor automatically loads the appropriate segment layout when you start the tool. However, if the filename prefixes do not match, or if you want to apply an alternative segment layout file:

  1. Start the IMS Database Editor.
  2. Choose File > IMS Database Editor > Load Segment Layouts.
  3. Select a .slf file that was created from the database file.

    The file loads in the IMS Database Editor with the segments properly formatted in the right pane.

  4. Edit segments as needed. Changes are saved as soon as they are made.

For complete information on using these Data File Tools, see IMS Segment Layout Editor and IMS Database Editor.

Parent topic: Data File Tools Support for PL/I
Related concepts
IMS Segment Layout Editor
IMS Database Editor


EXEC DLI Support in PL/I

PL/I programs that contain EXEC DLI statements can be compiled and executed in the IMS or the CICS environments. EXEC DLI statements are imbedded in user programs much like EXEC CICS statements are. These statements manipulate data in IMS data bases while running under control of IMS or CICS.

The EXEC preprocessor PP support EXEC DLI statements and generates code to execute of these statements.

IMS ECM (imsecm), distinguishes between PL/I and COBOL source code to support EXEC DLI statements in the source code of either language. The EXEC DLI support fully recognizes PL/I variable names, and expressions that contain dashes as well as other PL/I elements as syntactical units.

In Enterprise Developer, you can specify DLI preprocessor options as you would with other preprocessor options.

Parent topic: Using Open PL/I


Calling PL/I subroutines from a COBOL Application

Note: The information below is specific to programs executing under Enterprise Server, but also applicable to standalone applications running outside of Enterprise Server as well.

To use PL/I subroutines executing under the control of a COBOL Application you need to initialize the PL/I runtime prior to invoking the PL/I program and shut it down before termination. The initialization call (__lpi_init()) can be made within a COBOL "initcall" program, but the de-initialization call (__lpi_fini_and_return() ) must not be made from a COBOL EXIT Proc as the processing happens after the File Handler has closed all open files at step termination and will result in any buffered stream output being lost.

A very simple example COBOL program which initializes the PL/I runtime, calls a PL/I subroutine and then terminates the PL/I runtime is shown below.

      $SET CASE
       identification division.
       program-id. FETCHER.

       environment division.
       configuration section.
       special-names.
          call-convention 8 is litlink.

       data division.
       working-storage section.
       01 pli-lang                     pic x(02) comp-5 value 0.
       01 pli-retcode                  pic x(04) comp-5.
       01 argv                         pointer value null.

       procedure division.

           *> Initialize PL/I RTS
           call litlink '__lpi_init' using by value 0 size 4
                                             by reference argv
                                             by reference argv
                                             by value pli-lang

           *> Call the PL/I subroutine
           call 'PLISUB'

           *> Shutdown the PL/I RTS
           call litlink '__lpi_fini_and_return' using
                                            by value pli-lang
                                            by reference pli-retcode

           move 0 to return-code
           goback.

       end program FETCHER.
Parent topic: Using Open PL/I


Test Coverage

  • Overview
  • Using Test Coverage
  • Results
  • Creating a Test Coverage Report
  • Restrictions
Parent topic: Using Open PL/I


Overview

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.

Parent topic: Test Coverage


Using Test Coverage

To enable test coverage for a PL/I program or module use the -testcover option when compiling with mfplx or mfpli.

mfplx -debug -testcover myprog.pli

or

mfpli -debug -testcover prog1.pli
    mfpli prog2.pli
    ldpli prog1.o prog2.o

Test coverage is only supported for code compiled for debug. If the -testcover option is used, the code will be compiled for debug even if -debug is not specified. Note that by using mfpli and ldpli to compile and link you can freely mix modules compiled with and without test coverage.

Parent topic: Test Coverage


Results

When code compiled for test coverage is executed, test coverage data is written to a binary results file called pli.tci in the current working directory. Test coverage data from multiple runs and different programs will all be accumulated in the same file. To start a fresh set of test coverage runs, delete or move the pli.tci file.

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.

Parent topic: Test Coverage


Creating a Test Coverage Report

To create a report on PL/I test coverage data use the tcpli utility.

tcpli with no arguments lists the modules for which test coverage information is available in the current pli.tci file. Modules are identified by the name of the corresponding .stb debug information file.

tcpli myprog.stb will output a test coverage report for the myprog program or module. The report consists of a listing of the source file(s) for program myprog, with each line preceded by a count of the number of times code in that line has been executed. Lines that do not contain any executable code will be preceded by '---'. Example:

$ tcpli myprog.stb
Source file myprog.pli
--- foo: proc options(main);
--- dcl x fixed bin(31) init(0);
  1 display(x);
  1 do until (x = 10);
 10 x = x + 1;
 10 display(x);
 10 end;
  1 end;
Note: Use tcpli -help to see other supported options for the tcpli utility.

If the program contains %INCLUDE files, they will be included in the report listing only if they contain executable code.

Parent topic: Test Coverage


Restrictions

  • Test coverage is only available for PL/I on x86-based systems (Windows, Red Hat Enterprise Linux, SUSE Linux).
  • Test coverage does not work for OPTIONS(FETCHABLE) functions.
Parent topic: Test Coverage


Language Concepts

This chapter describes the Open PL/I language implementation for your system. For detailed information on the Open PL/I programming language, see your Open PL/I Language Reference Manual.
  • Line Boundaries
  • Main Procedure
  • Data Types
  • Arithmetic Precision
  • External Procedures
  • Maximum Number of Arguments for a Function or Subroutine Call
  • Open PL/I Calling Conventions
  • Special Programming Tasks
    Describes other useful PL/I programming tasks
  • CBL_GET_PROGRAM_INFO (PL/I)
    Returns information for a named program, or a program in the current call stack.
Parent topic: Open PL/I User's Guide


Line Boundaries

A line boundary consists of a new-line character (CRLF on a Windows system), and the line boundary in a quoted string constant is considered part of the string constant.

Parent topic: Language Concepts


Main Procedure

Exactly one of the external procedures that is linked into an executable file must specify the main entry point to the program by including the OPTIONS(MAIN) clause on the PROCEDURE statement. This designates that procedure as the main entry point at which execution should begin, after some run-time initialization has been completed. This option must appear even if the entire program is a single procedure contained in a single source file. Failure to specify a main program, or specifying more than one main program, will cause errors to occur during program linkage.

The main procedure is not required to be a PL/I procedure; that is, it can be written in another language.

Parent topic: Language Concepts


Data Types

The table below lists the Open PL/I data types, along with the alignment and size of their machine representations.

Alignment is the same for Intel, AIX/Power, and Sun SPARC, unless otherwise specified.

Data Type | Size | Alignment: aligned data | Alignment: unaligned data
Fixed Binary Signed (p <= 7) 1 | 1 byte | 1 byte | byte
Fixed Binary Signed (8 <= p <= 15) | 2 bytes | 2 bytes | byte
Fixed Binary Signed (16 <= p <= 31) | 4 bytes | 4 bytes | byte
Fixed Binary Signed (32 <= p <= 63) | 8 bytes | 4 bytes (32-bit system) 8 bytes (64-bit system) | byte
Fixed Binary Unsigned (p <= 8) 2 | 1 byte | 1 byte | byte
Fixed Binary Unsigned (9 <= p <= 16) | 2 bytes | 2 bytes | byte
Fixed Binary Unsigned (17 <= p <= 32) | 4 bytes | 4 bytes | byte
Fixed Binary Unsigned (33 <= p <= 64) | 8 bytes | 4 bytes (32-bit system) 8 bytes (64-bit system) | byte
Fixed Decimal (p,q) | [(p+2)/2] bytes | byte | byte
Float Binary (p <= 23) | 4 bytes | 4 bytes | byte
Float Binary (p > 23) | 8 bytes | 4 bytes (Intel 32-bit), 8 bytes ( Intel 64-bit, Sparc, RS/6000) | byte
Float Decimal (p) | 12 bytes | 4 bytes | byte
Character (n) | n bytes | byte | byte
Character (n) Varying | n+2 bytes | 2 bytes | byte
Character (n) Varyingz | n+1 bytes | byte | byte
Graphic(n) | n*2 bytes | byte | byte
Graphic(n) Varying | n*2+2 bytes | 2 bytes | byte
Graphic(n) Varyingz | n*2+2 bytes | byte | byte
Widechar (n) | n*2 bytes | byte | byte
Widechar (n) Varying | n*2+2 bytes | Half-word | byte
Widechar(n) Varyingz | n*2+1 bytes | byte | byte
Bit (n) | n bits | bit | bit
Bit (n) Aligned | [(n+7)/8] bytes | byte | –
Pointer (32-bit) | 4 bytes | 4 bytes | byte
Pointer (64-bit) | 8 bytes | 8 bytes | byte
Picture | n bytes | byte | byte
Label | 8 bytes | 4 bytes | byte
Entry Variable | 8 bytes | 4 bytes | byte
File Variable | 4 bytes | 4 bytes | byte
Structure3 | sum of members + gaps for alignment | max of members | byte
Area (n) | (((n+7)/8)*8)+8 bytes | 8 bytes | –
Offset | 4 bytes | 4 bytes | byte

Subsequent sections provide additional information about the size, alignment, internal representation including byte ordering, and range, where applicable.

The byte ordering on the IBM RS/6000 and Sun SPARC platforms is Big Endian, while the Intel-based platforms have Little Endian byte ordering.

Note:

In the descriptions of data types that follow, the alignment specified is the default, which is ALIGNED for all data types except Bit. For the alignment of each data type with the UNALIGNED attribute, refer to the table above.

  • Fixed Binary Signed (p <= 7)
  • Fixed Binary (8 <= p <= 15)
  • Fixed Binary Signed (16 <= p <= 31)
  • Fixed Binary Signed (32 <= p <= 63)
  • Fixed Binary Unsigned (p <= 8)
  • Fixed Binary Unsigned(9 p 16)
  • Fixed Binary Unsigned (17 <= p <= 32)
  • Fixed Binary Unsigned (33 <= p <= 64)
  • Fixed Decimal (p,q)
  • Float Binary (p <= 23)
  • Float Binary (23 < p <= 52)
  • Float Decimal (p)
  • Character (n)
  • Character (n) Varying
  • Widechar (n)
  • Widechar (n) Varying
  • Bit (n)
  • Bit (n) Aligned
  • Pointer
  • Label
  • Picture
  • Entry
  • File Variable
  • Structure
  • Area (n)
  • Offset
Parent topic: Language Concepts
1 Fixed Binary Signed (p <= 7 ) is handled as a one-byte signed binary integer by default. To override this default and handle as a two-byte signed binary integer, use the -fb7asfb15 compiler option.
2 Fixed Binary Unsigned (p <= 8) is handled as a one-byte unsigned binary integer by default. To override this default and handle as a two-byte unsigned binary integer, use the -fb7asfb15 compiler option.
3 See the Structure topic for mapping conventions.


Fixed Binary Signed (p <= 7)

Fixed Binary (p <= 7) is an 8-bit, signed, 2's complement binary integer by default. The low order 7 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value is negative, 0 if the value is positive or zero. Use the -fb7asfb15 option to provide compatibility with previous versions of Open PL/I.

Size | Alignment | Range
1 byte | 1 byte | -128 to 127
Parent topic: Data Types


Fixed Binary (8 <= p <= 15)

Fixed Binary (8 <= p <= 15) is a 16-bit, signed, 2's complement binary integer. The low order 15 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value is negative, 0 if the value is positive or zero.

Size | Alignment | Range
2 bytes | 2 bytes | -32768 to 32767
Parent topic: Data Types


Fixed Binary Signed (16 <= p <= 31)

Fixed Binary Signed (16 <= p <= 31) is a 32-bit, signed, 2's complement binary integer. The low order 31 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value represented is negative.

Size | Alignment | Range
4 bytes | 4 bytes | -2,147,483,648 to 2,147,483,647
Parent topic: Data Types


Fixed Binary Signed (32 <= p <= 63)

Fixed Binary Signed (32 <= p <= 63) is a 64-bit, signed, 2's complement binary integer. The low order 63 bits contain the integer, the high order bit contains the sign. The sign bit (S) is 1 if the value represented is negative.

Size | Alignment | Range
8 bytes | 8 bytes (64-bit system) 4 bytes (32-bit system) | -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
Parent topic: Data Types


Fixed Binary Unsigned (p <= 8)

Fixed Binary Unsigned (p <= 7) is an 8-bit, unsigned, 2's complement binary integer.

Size | Alignment | Range
1 byte | 1 byte | 0 to 255
Parent topic: Data Types


Fixed Binary Unsigned(9 p 16)

Fixed Binary Unsigned (9 <= p <= 16) is a 16-bit, unsigned, 2's complement binary integer.

Size | Alignment | Range
2 bytes | 2 bytes | 0 to 65535
Parent topic: Data Types


Fixed Binary Unsigned (17 <= p <= 32)

Fixed Binary Unsigned (17 <= p <= 32) is a 32-bit, unsigned, 2's complement binary integer.

Size | Alignment | Range
4 bytes | 4 bytes | 0 to 4294967295
Parent topic: Data Types


Fixed Binary Unsigned (33 <= p <= 64)

Fixed Binary Unsigned (33 <= p <= 64) is a 64-bit, unsigned, 2's complement binary integer.

Size | Alignment | Range
8 bytes | 8 bytes (64-bit system) 4 bytes (32-bit system) | 0 to 18,446,744,073,709,551,615
Parent topic: Data Types


Fixed Decimal (p,q)

Fixed Decimal (p,q) is a fixed-point number that contains p digits, where q of those digits are fraction digits. Fixed decimal values are typically used only when fraction digits are required. Fixed-point decimal values are always stored as an accurate representation of decimal fractions. The most significant digits are stored at the lowest memory address, and the byte containing the least significant digit and the sign (hexadecimal C for positive or D for negative) is stored at the highest memory address.

Size | Alignment | Range
[(p+2)/2] bytes | byte | -(10p-q - 10-q) to +(10p-q -10-q
Parent topic: Data Types


Float Binary (p <= 23)

Float Binary (p <= 23) is a single-precision, basic format, binary floating-point number (ASCII/IEEE 754-1985 compliant). It contains a 1-bit sign, 8-bit biased exponent (bias = 127), and 23+(1)-bit binary fraction (hidden bit).

An exponent of 255 represents +/- infinity or not-a-number. +/- infinity is represented by an exponent of 255 and zero as the fraction part; the sign bit denotes the + or - infinity. Not-a-number is represented by an exponent of 255 and any non-zero value in the fraction part; the sign bit of not-a-number is not significant. An exponent of 0 denotes a denormalized small value of reduced precision. Both +0 and -0 are possible. Note that the range is approximate and indicates representable values, which include zero and both negative and positive numbers.

Size | Alignment | Approximate Absolute Value of Range
4 bytes | 4 bytes | 1.40E-45 to 3.40E+38
Parent topic: Data Types


Float Binary (23 < p <= 52)

Float Binary (23 < p <= 52) is a double-precision, basic format, binary floating-point number (ANSI/IEEE 754-1985 compliant). It consists of a 1-bit sign, 11-bit biased exponent (bias = 1023), and 52+(1)-bit binary fraction (hidden bit).

An exponent of 2047 represents +/- infinity or not-a-number. +/- infinity is represented by an exponent of 2047 and zero as the fraction part; the sign bit (S) denotes the + or - infinity. Not-a-number is represented by an exponent of 2047 and any non-zero value in the fraction part; the sign bit of not-a-number is not significant. An exponent of 0 denotes a denormalized value of reduced precision. Both +0 and -0 are possible. Note that the range is approximate and indicates representable values, which include zero and both negative and positive numbers.

Size | Alignment | Approximate Absolute Value of Range
Size | Alignment | Approximate Absolute Value of Range
Size | Alignment | Approximate Absolute Value of Range
8 bytes | 4 bytes (Little Endian) 8 bytes (Big Endian) | 4.9E-324 to 1.8E+308
8 bytes | 4 bytes (Little Endian) 8 bytes (Big Endian) | 4.9E-324 to 1.8E+308
8 bytes | 4 bytes (Little Endian) 8 bytes (Big Endian) | 4.9E-324 to 1.8E+308
Parent topic: Data Types


Float Decimal (p)

For compatibility with IBM PL/I, data declared as float decimal is stored and processed by default as 4-byte or 8-byte float binary. (If the specified precision is ? 6, 4-byte float binary is used.)

Alternatively, float decimal data can be stored and processed as 12-byte Binary Coded Decimal BCD float decimal data by using the -nofdasfb ("no float dec as float bin") compiler option. In this case, Float Decimal (p) is a decimal floating-point number, stored in packed decimal format. It consists of a sign, an exponent sign, two bits used for infinity, not-a-number (usually 0), a 3-digit (base 10) exponent and a 17-digit (base 10) fraction. Both the exponent and fraction have a separate sign bit. All digits are packed Binary Coded Decimal (BCD), such that the entire string fits in 96 bits (12 bytes). The fraction contains at least p decimal digits.

Size | Alignment | Approximate Absolute Value of Range
12 bytes | 4 bytes | 9.9999999999999999x10 -999 to 9.9999999999999999x10 999
Parent topic: Data Types


Character (n)

Character (n) is a character-string variable where n is an integer that specifies the length of the string value held by the variable. Character (n) is a sequence of 8-bit ASCll characters stored as 1 character per byte. In Open PL/I, the maximum length of a string variable is 32767 characters.

Size | Alignment
n bytes | byte
Parent topic: Data Types


Character (n) Varying

Character (n) Varying is a character-string variable. The VARYING attribute causes the string variable to hold values of varying length. The representation of a varying string variable in storage is such that any string up to n characters may be held by the variable, and the length of the current string is retained as part of the value. Character (n) Varying is stored as follows: the first two bytes contain the length of the string (represented by a Fixed Binary (15) number) followed by a sequence of 8-bit ASCII characters stored as 1 character per byte. In Open PL/I, the maximum length of a string value is 32767 characters.

Note that the character string is not terminated with a null (ASCII 0) character.

Size | Alignment
n+2 bytes | 2 bytes
Parent topic: Data Types


Widechar (n)

Widechar (n) is a character-string variable where n is an integer that specifies the length of the string value held by the variable. Widechar (n) is a sequence of "byte-pairs" stored as 1 wide character in adjacent bytes (Big Endian order). In Open PL/I, the maximum length of a wide string variable is 16383 wide characters.

Widechar byte table

Size | Alignment
n*2 bytes | byte
Parent topic: Data Types


Widechar (n) Varying

Widechar (n) Varying is a wide character-string variable. The VARYING attribute causes the string variable to hold values of varying length. The representation of a varying string variable in storage is such that any string up to n wide characters may be held by the variable, and the length of the current string is retained as part of the value. Widechar (n) Varying is stored as follows: the first two bytes contain the length of the string (represented by a Fixed Binary (15) number stored in machine native format) followed by a sequence of wide characters stored as 1 wide character (or "byte-pair") in adjacent bytes (Big Endian order). In Open PL/I, the maximum length of a wide string value is 16383 characters.

Widechar (n) Varying byte table

Size | Alignment
n*2+2 bytes | Half-word
Parent topic: Data Types


Bit (n)

Bit (n) is a bit-string variable where n is an integer valued expression that specifies the length of the string value held by the variable. Bit (n) is a sequence of binary digits (bits) that always occupies exactly n bits of storage.

For Intel platforms, using the -bitsltr compiler option stores bit strings as Big-Endian. See -bitsltr in the Compiler Options help topic for more information.

Big-endian platforms:

If the high-order bit of the bit-string does not occur on a byte boundary, the remaining bits in the last byte might be part of another bit-string variable. Within each byte, the bits of the string are stored from the low-order to the high-order bit position. Note the bit positions are zero-relative similar to the hardware bit-numbering. For example, Bit (23) would be stored as follows (assuming an unaligned starting bit offset of 5):

Little-endian platforms:

If the low-order bit of the bit-string does not occur on a byte boundary, the remaining bits in the last byte might be part of another bit-string variable. Within each byte, the bits of the string are stored from the low-order to the high-order bit position (on Intel platforms). Note the bit positions are zero-relative similar to the hardware bit-numbering. For example, Bit (23) would be stored as follows (assuming an unaligned starting bit offset of 5):

On little-endian platforms, bit-strings are essentially stored "right-to-left" according the Intel hardware bit-ordering, but all bit operations are performed according to PL/I language semantics.

Note: Overlaying fixed bin and bit items is non-portable between big-endian and little-endian architectures.
Size | Alignment
n bits | bit (none)
Parent topic: Data Types
Related information
Compiler Options


Bit (n) Aligned

Bit (n) Aligned is a bit-string variable. The ALIGNED attribute causes the bit-string variable for which it is declared to be byte-aligned, resulting in more efficient access. This attribute may also cause the variable to occupy more than n bits, but it does not increase the length of the value that can be stored in the variable. The ALIGNED attribute has no effect on operations performed on the variable, but is considered part of the data type for purposes of argument/parameter matching and storage sharing.

For Intel platforms, using the -bitsltr compiler option stores bit strings as Big-Endian. See -bitsltr in the Compiler Options help topic for more information.

Bit (n) Aligned size is in bytes. If the length, n, is not a multiple of eight (for example, Bit (27) Aligned) then the remaining bits in the last byte are unused. Within each byte, the bits of the string are stored from the high-order to the low-order position. For example, Bit (27) Aligned would be stored as follows:

Size | Alignment
[(n+7)/8] bytes | byte

On Little Endian platforms, bits are reversed on each byte.

Parent topic: Data Types
Related information
Compiler Options


Pointer

Pointer is a 4-byte, 32-bit word variable capable of holding the address of any variable except unaligned bit variables. Pointers are normally used to locate the storage of dynamically allocated BASED variables rather than as a mechanism for accessing another variable's storage. A pointer is used with a template to access the storage to which it points. A pointer value cannot be represented by a constant. Pointer values can be assigned, compared for equality or inequality, passed as arguments, and returned from functions. No calculations or conversions can be performed on them, and they cannot be transmitted in stream I/O.

Size | Alignment
4 bytes | 4 bytes
Parent topic: Data Types


Label

Label is an 8-byte, 32-bit word pair variable consisting of a 4-byte text address and a 4-byte frame pointer value. The text address identifies the first instruction of a labeled statement in the containing procedure. The frame pointer value identifies the address of the stack frame of the block containing the statement. Label values can be assigned, compared for equality or inequality, passed as arguments, and returned from functions. No calculations or conversions can be performed on them, and they cannot be transmitted in stream I/O.

Size | Alignment
8 bytes | 4 bytes
Parent topic: Data Types


Picture

Picture is a fixed-point decimal value stored internally as a character string. The string contains the characters that represent the numeric value, and may be formatted with special embedded symbols such as a period (.) or a comma (,). Picture data is best used to manipulate a quantity arithmetically and then print or display its value.

Size | Alignment
n bytes | byte
Parent topic: Data Types


Entry

Entry is an 8-byte, 32-bit word pair variable consisting of a 4-byte descriptor pointer and a 4-byte frame pointer value. The descriptor pointer points to a data area that specifies the text address of the procedure entry and the table of contents pointer for the procedure. The frame pointer (relevant only with internal procedures) designates the stack frame of the containing procedure, if any. For external procedures, the frame pointer value is zero (0).

Size | Alignment
8 bytes | 4 bytes
Parent topic: Data Types


File Variable

File Variable is represented internally as a 4-byte, 32-bit word containing the address of a file control block. When evaluated, the value of the file variable is the address of the file control block for the file with which the variable is associated. A file variable can be assigned any file value; it is declared using both the FILE and VARIABLE attributes.

Size | Alignment
4 bytes | 4 bytes
Parent topic: Data Types


Structure

Structure is a hierarchically ordered set of values that may be of different data types. The immediate components of a structure are called "members" of the structure. An entire structure can be transmitted in stream or record I/O, passed as an argument, or assigned to another structure of identical size and shape and having members of corresponding identical data types. No conversions or calculations can be performed on entire structures.

Size | Alignment
Sum of members + gaps for alignment | Most stringent of members' alignment requirements

In Open-PL/I, structure mapping is as follows:

  • Each member is aligned to its natural boundary (offset from the start of the structure) as determined by the native machine architecture. Each member offset is effectively "pushed ahead" to map to its natural boundary, and where necessary, pad bytes may be introduced.
  • The alignment of the top-level structure (and substructures) will inherit the most stringent alignment requirement of its members.
Parent topic: Data Types


Area (n)

Area (n) is a variable describing a region of storage whose size in bytes is defined by the integer n. An area variable is a region of storage in which based variables can be allocated and freed. An area can be passed as an argument or it can be assigned to another area. It can also be transmitted in its entirety in a record I/O operation. No other operations, calculations, or conversions can be performed on area variables.

Size | Alignment
n bytes rounded to 8 byte boundary, plus 8 byte header [ (((n+7)/8)*8)+8] bytes | 8 bytes

Related Topics

Offset

Parent topic: Data Types
Related information
Offset


Offset

An offset variable is a locator used only in conjunction with an area variable. The value of an offset variable specifies the location of a based variable within an area, relative to the beginning of the area.

Offset variables can be assigned, compared for equality and inequality, passed as arguments, and returned as function results. No calculations or conversions can be performed on them, except in the context of explicit conversion to a Pointer, using Open PL/I's POINTER built-in function.

Size | Alignment
4 bytes | 4 bytes
Parent topic: Data Types
Related information
Area n


Arithmetic Precision

Each arithmetic data type has a default precision and a maximum precision as specified in Table 2-2. The range of the scale factor of fixed-point decimal data is 0 through 31 (0 ? q ? 31).

Data Type | Maximum Precision | Default Precision
Fixed Binary | 31 | 15*
Fixed Decimal | 31 | 5
Float Binary | 52 | 23
Float Decimal | 16 | 6

* The -longint option changes the default precision of fixed binary from 15 to 31.

Parent topic: Language Concepts


External Procedures

Open PL/I adheres to the calling conventions of the native architecture. Programs compiled by Open PL/I can be linked with object modules produced by other language products, and the resulting object program will run if the following conditions are met:

  • The calling conventions used by other language product(s) also adhere to the calling conventions of the native architecture. Note that the system C compiler on UNIX and the Windows Visual C/C++ compiler meet this requirement.
  • Declarations for formal and actual parameters in the calling and called programs must be written in their respective languages, so that the data representations assumed in the declarations agree with each other.
  • External Names
Parent topic: Language Concepts


External Names

Certain rules apply with regard to name length and the use of lowercase letters when specifying an identifier name:

  1. Name length: Open PL/I allows names up to 256 characters long.
  2. Lowercase names: By default, Open PL/I treats all names, including external names, as if all lowercase letters were upper case. When interfacing with non-PL/I external procedures, it may be necessary to work around this. For example, the C language preserves the case of all external names.

    If Open PL/I is calling a C function or vice-versa, one of the following options is available.

    • Spell with uppercase letters the external names in the C function where needed.
    • Use the EXTERNAL('name') option on the PLI ENTRY declaration to specify the exact name of the external C entry point.
    • Use the Open PL/I -lowercase Compiler option, which maps all external names to lower case instead of upper case. Note that all external names produced are lower case, not just the entry point to a procedure.
Parent topic: External Procedures


Maximum Number of Arguments for a Function or Subroutine Call

The maximum number of arguments that may be passed in an Open PL/I program is given by the following formula, which holds generally for any function or subroutine call argument list:

N + M= 241

where:

N | Is the actual number of arguments specified.
M | Is the position of the last *-extent argument, or zero if none exists.

Example:

DECLARE (S, T, U, V) CHAR (32),
   (I, J, K, L) BINARY (15),
   MYSUB ENTRY (BINARY(15), BINARY (15), CHAR(*),
         CHAR(*), BINARY(15), BINARY(15));
.
.
.
   CALL MYSUB(I,J,K,S,T,L);

where:

N | = 6 (the number or arguments specified)
M | = 5 (the position of "T" in the argument list)

which gives:

N+ M = 11 (6 actual arguments; 3 dummy descriptors for I, J, and K; and 2 actual descriptors for S and T).
Parent topic: Language Concepts


Open PL/I Calling Conventions

The following sections describe the calling conventions for HP, Intel, RS/6000, and Sun Sparc systems.

  • Calling Other Languages
  • Argument Passing Conventions
  • Register Save Conventions
  • Function Result Conventions
  • Open PL/I Equivalent Data Types
Parent topic: Language Concepts


Calling Other Languages

If you are calling a function written in another language, the result type must be able to be mapped to a PL/I data type.

C often expects character strings to be null terminated, that is, the string is delimited by an '\0' byte immediately following the last character of interest. When constructing a character value in PL/I that is passed to a C function expecting a null terminator, the PL/I procedure must supply an explicit null character in the appropriate position. The BYTE built-in function can be used for this purpose, as shown in the following example.

call CFUNC('abcde' || BYTE(0))

or without the BYTE built-in using z-character constants,

call CFUNC('abcde'Z)
  • C Calling Conventions
Parent topic: Open PL/I Calling Conventions


C Calling Conventions

The following program illustrates how to declare and call two standard C library functions, "atoi" and "strtol":

int atoi(const char *str)

long strtol(const char *str, char **endptr, int base)

Please note the following points:

  1. Since C is case-sensitive and PL/I is not, use EXTERNAL('name') to map the PL/I name to the function's real name.
  2. Since C arguments are passed by immediate value, specify the BYVALUE attribute for FIXED BINARY parameters.
  3. Because PL/I arguments are normally passed by reference, the BYVALUE attribute is not necessary for char * arguments declared CHARACTER(n). However, when a char * argument is declared POINTER, as in the ATOI_2 declaration, the BYVALUE attribute is required.
  4. By convention, C strings are terminated with a NULL byte.
  5. In this example, although char * is declared CHARACTER(80), any length long enough to hold the string and a terminating null byte would be all right. Of course, if the C function expected a pointer to a character string of a certain length, the PL/I and C declarations should agree.
  6. Note the use of the z-character constants for compatibility with C-style null-terminated strings, and the use of the SYSNULL() built-in, which returns 0, as opposed to the NULL() built-in, which returns -1 by default.
    CALLC: PROCEDURE OPTIONS(MAIN);

DECLARE

ATOI   ENTRY(CHARACTER(80))
       RETURNS(FIXED BINARY(31))
       EXTERNAL('atoi'),

ATOI_2 ENTRY(POINTER BYVALUE)
       RETURNS(FIXED BINARY(31))
       EXTERNAL('atoi'),

STRTOL ENTRY(CHARACTER(80),
             POINTER BYVALUE,
             FIXED BINARY(31) BYVALUE)
       RETURNS(FIXED BINARY(31))
       EXTERNAL('strtol'),

BASE   FIXED BINARY(31),
ENDPTR POINTER,
INT    FIXED BINARY(31),
LONG   FIXED BINARY(31),
STR    CHARACTER(80),
STRPTR POINTER;

STR    = '2147483647'z;
INT    = ATOI(STR);

PUT SKIP LIST(INT);

STRPTR = ADDR(STR);
INT    = ATOI_2(STRPTR);

PUT SKIP LIST(INT);

STR    = '0x7fffffff'z;
ENDPTR = SYSNULL();
BASE   = 16;
LONG   = STRTOL(STR, ENDPTR, BASE);

PUT SKIP LIST(LONG);

PUT SKIP LIST(STRTOL('0x7fffffff'z, SYSNULL(), 16));

END CALLC;
Parent topic: Calling Other Languages


Argument Passing Conventions

The following sections detail the argument passing conventions for HP, Intel, RS/6000, and Sun Sparc platforms.

  • HP Argument Passing Conventions (32-bit)
  • Intel Argument Passing Conventions (32-bit)
  • RS/6000 Argument Passing Conventions (32-bit)
  • Sun Sparc Argument Passing Conventions (32-bit)
Parent topic: Open PL/I Calling Conventions


HP Argument Passing Conventions (32-bit)

Arguments are passed in General Purpose Registers (GR) 26–23, Single-Precision Floating-Point Registers (FR) 4–7, Double-Precision Floating-Point Registers (FR) 5 and 7, and in the parameter area of the stack, according to the Open PL/I standard calling conventions.

  • If the function returns a value in a temporary storage area, a pointer to that area is passed in GR28.
  • The argument list contains addresses of the actual arguments in order or their appearance. If any arguments have the BYVALUE attribute, the actual argument is passed.
  • If OPTIONS(VARIABLE) is used, any missing arguments are replaced by null pointers.
  • If any of the function's parameters have variable extents, for example, asterisks(*), the addresses of dope vectors describing the arguments are appended to the explicit argument list.
Parent topic: Argument Passing Conventions


Intel Argument Passing Conventions (32-bit)

  • The calling procedure pushes the addresses of the actual arguments (pointers) onto the stack in the reverse order of their appearance in an argument list. In other words, the address of the last argument is pushed first and the address of the first argument is pushed last.
  • A call to a function returning one of the data types that requires a return temporary must push a pointer to the area for the result value onto the stack.

The external procedure is called by executing a CALL instruction.

Parent topic: Argument Passing Conventions


RS/6000 Argument Passing Conventions (32-bit)

Arguments are passed in General Purpose Registers (GPR) 3–10, Floating-point Registers (FPR) 1–13, and in the parameter area of the stack according to the Open PL/I standard calling conventions.

  • If the function returns a value in a temporary storage area, a pointer to that area is passed in GPR3 and all other arguments are displaced by one.
  • The argument list contains addresses of the actual arguments in order of their appearance. If any arguments have the BYVALUE attribute, the actual argument is passed.
  • If OPTIONS(VARIABLE) is used, any missing arguments are replaced by null pointers.
  • If any of the function's parameters have variable extents, for example asterisks (*), the addresses of dope vectors describing the arguments are appended to the explicit argument list.
Parent topic: Argument Passing Conventions


Sun Sparc Argument Passing Conventions (32-bit)

External procedures are called using the CALL instruction and are returned using the RET and RESTORE sequence.

  • The first six parameters are passed in the output registers; that is, the first parameter is passed in register o0, the second in register o1 and the sixth one in register o5. Parameters beyond the sixth are passed on the stack.
  • If OPTIONS(VARIABLE) is used, any missing arguments in the call to the procedure are replaced by null pointers.
  • The external procedure is called by executing a CALL instruction.
Parent topic: Argument Passing Conventions


Register Save Conventions

The following sections detail the register save conventions for HP, Intel, and Sun Sparc systems.

  • HP Register Save Conventions (32-bit)
  • Intel Register Save Conventions (32-bit)
  • RS/6000 Register Save Conventions (32-bit)
  • Sun Sparc Register Save Conventions (32-bit)
Parent topic: Open PL/I Calling Conventions


HP Register Save Conventions (32-bit)

The called procedure is expected to save and restore values in registers GR3–GR18 and FR12–FR21. The calling procedure can assume that those registers are preserved across the call. The function result is in GR28, FR4, or the result temporary provided by the caller, depending on the result data type. For more information, see the section HP Function Result Conventions.

Parent topic: Register Save Conventions
Related information
HP Function Result Conventions


Intel Register Save Conventions (32-bit)

The contents of ebx, esi, and edi must be preserved across a subroutine call. If a subroutine uses one of these registers, it must save the original value and restore it before returning to the caller.

Registers eax, ecx, and edx are scratch registers. A subroutine can change the value in a scratch register without saving its previous value.

When the Intel floating-point coprocessor is used, the floating-point stack registers must be empty before entry and upon exit from a subroutine. However, if the subroutine returns a floating-point value, the value is returned on top of the stack in register fp0 and the remainder of the stack is empty.

A called procedure is responsible for establishing a new stack frame for itself and saving and restoring all preserved registers. The procedure establishes the stack frame with the following sequence:

pushl ebp
movl esp, ebp
subl #framesize, esp
pushl ebx         //only if used within function
pushl esi         //only if used within function
pushl edi         //only if used within function

Note that the code sequence may be abbreviated if -opt is specified.

A return must store any function result value, restore any preserved registers it used, pop its stack frame, and return to the caller.

A procedure that returns one of the data types that requires a return temporary must remove the extra pointer(s) from the stack entry; callers to such routines push these hidden arguments. The called routine must load register eax with the pointer to the return area that its caller passed before returning. Such a routine will start with the following code before establishing a frame:

popl edx
xchgl edx, 0 (esp)

Then it saves the return pointer in a local variable in its stack frame.

Parent topic: Register Save Conventions


RS/6000 Register Save Conventions (32-bit)

The called procedure is expected to save and restore values in registers GPR13 through GPR31 and FPR14 through FPR31. The calling procedure can assume that those registers are preserved across the call. The function result is in GPR3, FPR1, or the result temporary provided by the caller, depending on the result data type.

Parent topic: Register Save Conventions


Sun Sparc Register Save Conventions (32-bit)

The called procedure is expected to save and restore all local and input registers (10 through 17 and i0 through i7). The calling procedure can assume that only these registers are preserved across the call. The function result is general ally in o0, f0, or both f0 and f1, or the result temporary provided by the caller, depending on the result data type. For more information, see the section Sun Sparc Function Result Conventions.

A called procedure is responsible for establishing a new stack frame for itself and saving and restoring all local and input registers. This is accomplished by a SAVE instruction. Before returning, the called procedure must store any function result value, restore all local and input registers, and adjust the stack frame. This is accomplished by a load of i0, f0, or both f0 and f1, or a store to a result temporary and a RESTORE instruction.

Parent topic: Register Save Conventions
Related information
Sun Sparc Function Result Conventions


Function Result Conventions

A function returns its result to the caller in one of four ways. The following sections detail the function result conventions on HP, Intel, RS/6000, and Sun Sparc systems.

  • HP Function Result Conventions (32-bit)
  • Intel Function Result Conventions (32-bit)
  • RS/6000 Function Result Conventions (32-bit)
  • Sun Sparc Function Result Conventions (32-bit)
  • Return of Data Types
Parent topic: Open PL/I Calling Conventions


HP Function Result Conventions (32-bit)

A function procedure returns its result value to the calling procedure in one of three ways, depending upon the data type: in register GR28, in register FR4, or in a temporary storage area provided by the caller.

If the result is returned in a temporary storage area, the calling procedure provides the temporary area and passes its address in GR28.

Parent topic: Function Result Conventions


Intel Function Result Conventions (32-bit)

On Intel x86 systems, the result of a function is returned in one of the following three ways, depending upon the result's data type and if the floating-point coprocessor is used:

  • In register eax
  • In a temporary storage area provided by the caller
  • On top of the Intel floating-point coprocessor's stack in register fp0
Parent topic: Function Result Conventions


RS/6000 Function Result Conventions (32-bit)

A function procedure returns its result value to the calling procedure in one of three ways, depending upon the data type:

  1. In register GPR3
  2. In register FPR1
  3. In a temporary storage area provided by the caller

If the result is returned in a temporary storage area, the calling procedure provides the temporary area and passes its address as the first (hidden) parameter in the call.

Parent topic: Function Result Conventions


Sun Sparc Function Result Conventions (32-bit)

On the Sun Sparc, the result of a function is returned in one of the following four ways, depending upon the result's data type:

  1. In register o0
  2. In a temporary storage area
  3. In register f0
  4. In registers f0 and f1

On Sun Sparc systems, the calling procedure provides the temporary area and stores the address to the temporary area in the one-word hidden parameter of the user frame at %sp+0x40 prior to the call.

Parent topic: Function Result Conventions


Return of Data Types

The table below lists the Open PL/I data types and the registers to which they are returned on each platform.

Open PL/I Data Type | Register Returned in
 | HP | Intel | RS/6000 | Sun Sparc
Fixed Binary Character(1), not * or Varying Bit(1), not * Pointer Offset File | GR28 | eax | GPR3 | o0
Float Binary | FR4 | on top of the floating-point coprocessor stack | FPR1 | f0/f1
Fixed Decimal Float Decimal Character( n), n > 1 or n = * Character( n) Varying Bit( n), n > 1 or n = * Picture Label Entry | Returned in Temporary Storage Area
Parent topic: Function Result Conventions


Open PL/I Equivalent Data Types

This table lists compatible data types for determining equivalent argument type correspondence. Some data types (for example, char in C) are used more than once in the table to show the correspondence of equivalent types in more than two languages. The subscripts used in the table have the following meanings:

PL/I | COBOL | C | C++ | FORTRAN | BASIC | PASCAL
Fixed Bin, P <= 7 | COMP PIC S9 (1) – S9 (2) | char | char | INTEGER*1 | – | –
Fixed Bin, 8 <= P <= 15 | COMP PIC S 9 (3) – S 9 (4) | short | short | INTEGER*2 | INTEGER (%) | Integer
Fixed Bin, P >15 | COMP PIC S 9 (5) – S 9 (9) | int or long | int or long | INTEGER*4 | – | Integer
– | – | char | char | INTEGER*1 | – | Packed Array[1...5]
Character (n) | DISPLAY A(n) or PIC X(n) | char [n] | char[n] | CHARACTER*n | – | –
Character (N) Varying | DISPLAY PIC X OCCURS num1 to num2 DEPENDING on N | struct {short s; char c[n];} | struct {short s; char c[n];} | – | – | Char
Character (1) | DISPLAY PIC X | char | char | CHARACTER*1 | – | –
Character (*) | – | char[ ] | char[ ] | – | – | –
Fixed Decimal | COMP–3 PIC S9 (n) | – | – | – | – | –
 | DISPLAY PIC S9(n) SIGN TRAILING | – | – | – | – | –
– | DISPLAY PIC S9(n) SIGN LEADING SEPARATE | – | – | – | – | –
– | DISPLAY PIC S9(n) SIGN TRAILING SEPARATE | – | – | – | – | –
Bit(1) | – | – | – | – | – | –
Bit(1) Aligned | – | char | char | – | – | Boolean
Bit(N) Aligned | COMP–5 PIC [S] 9 (n), n<5 | – | – | – | – | Set
– | – | int or long | int or long | LOGICAL*4 | – | –
– | – | short | short | LOGICAL*2 | – | –
– | – | char | char | LOGICAL*1 /BYTE | – | –
Float Bin, p > 23 | COMP–2 | double | double | REAL*8 | REAL (#) (MBASIC) | –
Float Bin, p <= 22 | COMP–1 | float | float | REAL*4 | REAL (1) (MBASIC) | Real
– | – | struct {float real, imaginary;} | struct {float real, imaginary;} | COMPLEX*8 | – | –
– | – | struct {double real; double imaginary} | #include <complex.h> class complex | COMPLEX*16 | – | –
Pointer | – | Pointer | Pointer | – | – | Pointer
Label | – | – | – | alternate return | – | –
Entry | DISPLAY PIC X(32) | – | – | Dummy procedure | – | –
Float Decimal | – | – | – | – | REAL (CBASIC) | –
– | – | – | – | – | STRING ($) | –
Area | – | – | – | – | – | –
Offset | COMP PIC S 9 (5) – S 9 (9) | int or long | int or long | INTEGER*4 | – | integer
Parent topic: Open PL/I Calling Conventions


Special Programming Tasks

  • XML Parser Support in PL/I
    Brief description of concept. Should be written as a fragment. Contains no more than two sentences.
Parent topic: Language Concepts


XML Parser Support in PL/I

PL/I provides a SAX-like event-based interface for parsing XML documents. The parser invokes an application-supplied handler for parser events, passing references to the corresponding document fragments.

For an event-based API, the parser reports events to the application through call backs. Events include the start of the document, the beginning of an element, the end of the document and other document-related activities. The application must provide a handler to deal with each of the events reported by the parser. The simple SAX API follows SAX interfaces provided for other languages such as C, for which there is no standard.

The PL/I SAX parsers include the PLISAXA, PLISAXB, and PLISAXC built-in subroutines. THE PLISAXD built-in subroutine is not yet supported.

The parser can:

  • Provide high-performance, but non-standard interfaces.
  • Support XML files encoded in either Unicode UTF-16 or any of several single-byte code pages.
  • Check XML well-formedness and generate exception events.

XML documents have two levels of conformance: well-formedness and validity, both of which are defined in the XML standard. Basically, an XML document is well-formed when it complies with the basic XML grammar, and with a few specific rules, such as the requirement for matching start and end element tags names. A well-formed XML document also includes an associated document type declaration (DTD) that complies with the constraints expressed in the DTD.

A PL/I function must accept the appropriate parameters and return the appropriate return value for each parser event. Also, the return value must be returned as a BYVALUE.

XML Parser Support Restrictions

If using the -ebcdic option to compile your program, the callback event logic should account for the fact that the data passed back to the call backs is in ASCII, even if the input format was in EBCDIC. Because of this, the data must be translated prior to use within the callbacks. In addition, all reference values passed as a FIXED BIN(31) are for ASCII character encoding.

On UNIX, if your XML input is EBCDIC and contains open and close square brackets (e.g. []) and they are of the value X'BA' and X'BB', then you need to create your own custom codeset module for translation of these routines, and where you execute them, you need to set the environment variable MFCODESET to point to your custom codeset. This does not apply for ASCII input.

It is assumed that your program is built using the -bigendian compiler option if operating on an Intel Chip. If compiling your program without using the -bigendian compiler option, then you must convert the parameter types from big-endian to little-endian prior to use.

  • Using the PLISAXA and PLISAXB XML parsers
    Explains the use of the PLISAXA and PLISAXB built-ins for XML parsing.
  • Notes on PLISAXA and PLISAXB XML parsing support and differences with IBM's implementation
  • Using the PLISAXC XML parser
  • Notes on PLISAXC XML parsing support and differences with IBM's implementation
    Describes restrictions to PLISAXC XML parsing support on Open PL/I.
  • SAX event structures
  • XML document coded character sets
  • Exceptions
Parent topic: Special Programming Tasks


Using the PLISAXA and PLISAXB XML parsers

The PLISAXA and PLISAXB built-in subroutines provide basic XML parsing capability. XML parsing lets PL/I programs consume and use inbound XML documents, check the well-formedness of the documents, and react to their contents. SAX parsing is based on the libxml2 XML parser.

These subroutines do not provide XML generation, which must instead be accomplished by PL/I program logic or by using the XMLCHAR built-in function.

PLISAXA and PLISAXB have no special environmental requirements. They execute in all the principal run-time environments, including CICS, IMS, WebSphere MQ, and TSO.

The PLISAXA and PLISAXB built-ins do not support XML name spaces or Unicode UTF-8 documents. They require that the entire XML document be passed in a buffer or a file before any parsing is performed. However, the PLISAXC built-in does not have these limits.

Parent topic: XML Parser Support in PL/I


Notes on PLISAXA and PLISAXB XML parsing support and differences with IBM's implementation

The Event Handler structure must be AUTOMATIC storage and initialized with the call back values or be assigned prior to invoking PLISAXA or PLISAXB. The Event Handler structure must be populated with an appropriate callback for each element of the structure. If the assignment is done manually using assignment statements, then it can be AUTOMATIC or STATIC.

The following are considerations if migrating an existing z/OS based application:

  • A call back EVENT must be provided for every member of the Event Handler structure. Change ENTRY LIMITED alias definitions for Event Handler Items to ENTRY to prevent the compiler from generating an E Level diagnostic. Also, remove all references to LINKAGE(OPTLINK) from ENTRY and Procedure declarations.
  • The event unknown_attribute_reference (E20), which is part of the PLISAXA and PLISAXB event structure (but not part of PLISAXC) is generated with the same content as IBM's SAX processor but occurs earlier in the parsing.
  • The reference for the event unknown_content_reference (E21) is expanded to be its actual value.
  • The events start_of_prefix_mapping (E22) and end_of_prefix_mapping (E23) are currently not supported to maintain compatibility with applications written using IBM's PLISAXA and PLISAXB functionality.
  • When using the SAX Parser, the exception event (E24) is driven only one time indicating an error, as opposed to having the exception event driven one time per character. See the topic XML Parsing Exception Event error codes for a list of Micro Focus error codes for the exception event (E24).
  • PLISAXB accepts filenames as the third parameter in the form file://dd:ddname under batch, where ddname is the name of the DD statement that specifies the filefile://filename under UNIX, where filename is the name of a UNIX file. The character string specifying the input file should have no leading or trailing blanks. If this is not the format, the parameter value is assumed to be the actual filename. Only files of RECFM=F, FB, FS, FBS and LSEQ are acceptable input.
Parent topic: XML Parser Support in PL/I


Using the PLISAXC XML parser

The PLISAXC built-in subroutine provides basic XML parsing capability. XML parsing lets PL/I programs consume and use inbound XML documents, and react to their contents. SAX parsing is based on the libxml2 XML parser.

The XML parser used by PLISAXC is non-validating, but does partially check for well-formedness errors, and generates exception events if it discovers any. It does not provide XML generation, which must instead be accomplished by PL/I program logic or by using the XMLCHAR built-in function.

PLISAXC has no special environmental requirements except that it is not supported in AMODE 24. It executes in all the principal run-time environments, including CICS, IMS, WebSphere MQ, and TSO.

Parent topic: XML Parser Support in PL/I


Notes on PLISAXC XML parsing support and differences with IBM's implementation

If using the FLAGS parameter of the content_characters event as a BIT(8) array, you must take into account bit ordering differences on Intel from z/OS. If evaluated as a single byte and not a bit array, then bit ordering matches z/OS bit ordering. See the online help topic Bit (n) for a discussion of bit ordering in a bit array on little endian platforms.

If XML content contains predefined reference characters, separate content_characters events are driven for the characters preceding the predefined reference characters, the reference character, and the characters after the reference characters. For example, the XML snippet <meat>Ham &amp; turkey</meat> generates three content_characters events using PLISAXC; one for Ham, one for &, and one for Turkey.

For the FLAGS parameter of the content_characters event, the flag to indicate the next event contains content_characters ('80'x). This currently only indicates if the next event contains content_characters when the current event contains a character which must be escaped back to XML. Also, the flag to indicate that no characters are escaped back to XML ('40'x) is only set if the character string contains one of the predefined reference characters for PLISAXA.

Parent topic: XML Parser Support in PL/I
Related information
Bit (n)


SAX event structures

  • SAX event structure descriptions for PLISAXA and PLISAXB
    Describes the 24 ENTRY variables in the SAX event structure for PLISAXA and PLISAXB.
  • SAX event structure descriptions for PLISAXC
    Describes the 24 ENTRY variables in the SAX event structure for PLISAXA and PLISAXB.
  • PLISAXA and PLISAXB XML Parser event function parameters
  • PLISAXC XML Parser event function parameters
  • XML Parser exception event error codes
    Lists the available exception event error codes for PL/I XML parsing.
  • PLISAXA and PLISAXB event structure example
    Shows an example of a SAX event structure for PLISAXA and PLISAXB.
  • PLISAXC event structure example
    Shows an example of a SAX event structure for PLISAXC.
  • Event differences
    Describes the event structure differences between PLISAXA/PLISAXB and PLISAXC
Parent topic: XML Parser Support in PL/I


SAX event structure descriptions for PLISAXA and PLISAXB

The event structure has 24 ENTRY variables. These variables point to functions invoked by the parser for various events.

Descriptions of each event in this topic refer to this XML document example.
xmlDocument =
   '<?xml version="1.0" standalone="yes"?>'
|| '<!--This document is just an example-->'
|| '<sandwich>'
|| '<bread type="baker&quot;s best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham &amp; turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| '<![CDATA[We should add a <relish> element in future!]]>'
|| '</sandwich>'
|| 'junk';

The term XML text in the descriptions is the string, which is formed based on the pointer and length passed to the event. The parser may recognize these events in their order of appearance in the structure.

start_of_document
Occurs once, at the beginning of parsing the document. The parser passes the address and length of the entire document, including any line-control characters, such as LF (Line Feed) or NL (New Line). For the above example, the document is 305 characters in length.
version_information
Occurs within the optional XML declaration for the version information. The parser passes the address and length of the text containing the version value ("1.0" in the example above).
encoding_declaration
Occurs within the XML declaration for the optional encoding declaration. The parser passes the address and length of the text containing the encoding value.
standalone_declaration
Occurs within the XML declaration for the optional standalone declaration. The parser passes the address and length of the text containing the standalone value ("yes" in the example).
document_type_declaration
Occurs when the parser finds the document type declaration. A document type declaration begins with the character sequence <!DOCTYPE" and ends with a > character. Fairly complicated grammar rules describe the content in between.

The parser passes the address and length of the text containing the entire declaration. This includes the opening and closing character sequences. This is the only event where XML text includes the delimiters. The example above does not have a document type declaration.

end_of_document
Occurs once, when document parsing has completed.
start_of_element
Occurs once for each element start tag or empty element tag. The parser passes the address and length of the text containing the element name. The first start_of_element event during parsing in the example contains the string sandwich.
attribute_name
Occurs for each attribute in an element start tag or empty element tag, after recognizing a valid name. The parser passes the address and length of the text containing the attribute name. The only attribute name in the example is type.
attribute_characters

Occurs for each fragment of an attribute value. The parser passes the address and length of the text containing the fragment. An attribute value normally consists of a single string only, even if it is split across lines:

<element attribute="This attribute value is
split across two lines"/>

The attribute value might consist of multiple pieces, however. For instance, the value of the type attribute in the sandwich example at the beginning of the example has three fragments: the string baker, the single character ' and the string s best. The parser passes these fragments as three separate events. It passes each multiple-character string as attribute_characters events, and the single character as an attribute_predefined_reference event.

attribute_predefined_reference
Occurs in attribute values for the five pre-defined entity references &, ', >, <, and ". The parser passes a CHAR(1) or WIDECHAR(1) value that contains one of &, ', >, <, or " respectively.
attribute_character_reference

Occurs in attribute values for numeric character references of the form

&#dd;

or

&#xhh;

where d and h represent decimal and hexadecimal digits, respectively. The parser passes a FIXED BIN(31) value that contains the corresponding integer value.

end_of_element
Occurs once for each element end tag or empty element tag whenever the parser recognizes a closing angle bracket of the tag. The parser passes the address and length of the text containing the element name.
start_of_CDATA_section
Occurs at the start of a CDATA section. CDATA sections begin with the string <![CDATA[ and end with the string ]], and are used to escape blocks of text containing characters that would otherwise be recognized as XML markup. The parser passes the address and length of the text containing the opening characters <![CDATA[. The parser also passes the content of a CDATA section between these delimiters as a single content-characters event. The content-characters event is passed the text We should add a <relish> element in future!.
end_of_CDATA_section
This event occurs when the parser recognizes the end of a CDATA section. The parser passes the address and length of the text containing the closing character sequence, “]]”.
content_characters

This event represents the main body of an XML document. This is the character data between element start and end tags. The parser passes the address and length of the text containing this data, which usually consists of a single string only, even if it is split across lines:

<element1>This character content is
split across two lines"</element1>

If the content of an element includes any references or other elements, the complete content may comprise several segments.

For example, the content of the meat element in the example includes the string Ham , the character & and the string turkey. There is a trailing space in the first string fragment and a leading space in the second string fragment. The parser passes these content fragments as separate events. It passes the string content fragments, Ham and turkey, as content_characters events, and the single & character as a content_predefined_reference event. The parser also uses the content_characters event to pass the text of CDATA sections to the application.

content_predefined_reference
Occurs in element content for the pre-defined entity references &, ', >, <, and ". The parser passes a CHAR(1) or WIDECHAR(1) value that contains one of &, ', >, <, or ", respectively.
content_character_reference

Occurs in element content for numeric character references of the form:

&#dd;

or

&#xhh;

where d and h represent decimal and hexadecimal digits, respectively. The parser passes a FIXED BIN(31) value that contains the corresponding integer value.

processing_instruction
Processing instructions (PIs) allow XML documents to contain special instructions for applications. This event occurs when the parser recognizes the name following the PI opening character sequence, <?. The event also covers the data following the PI target, up to but not including the PI closing character sequence, ?>. Trailing, but not leading white space characters in the data are included. The parser passes the address and length of the text containing the target, spread in the example, and the address and length of the text containing the data, please use real mayonnaise in the example.
comment
Occurs for any comments in the XML document. The parser passes the address and length of the text between the opening and closing comment delimiters, <!-- and -->, respectively. The only comment text in the example is This document is just an example.
unknown_attribute_reference
Occurs within attribute values for entity references other than the pre-defined entity references, listed for the event attribute_predefined_reference. The parser passes the address and length of the text containing the entity name.
unknown_content_reference
Occurs within element content for entity references other than the pre-defined entity references listed for the content_predefined_reference event. The parser passes the address and length of the text containing the entity name.
start_of_prefix_mapping
This event is currently not generated.
end_of_prefix_mapping
This event is currently not generated.
exception
The parser generates this event when it detects an error processing the XML document.
Parent topic: SAX event structures


SAX event structure descriptions for PLISAXC

The event structure has 19 ENTRY variables. These variables point to functions invoked by the parser for various events.

Descriptions of each event in this topic refer to this XML document example.
xmlDocument =
   '<?xml version="1.0" standalone="yes"?>'
|| '<!--This document is just an example-->'
|| '<sandwich>'
|| '<bread type="baker&quot;s best"/>'
|| '<?spread please use real mayonnaise ?>'
|| '<meat>Ham &amp; turkey</meat>'
|| '<filling>Cheese, lettuce, tomato, etc.</filling>'
|| '<![CDATA[We should add a <relish> element in future!]]>'
|| '</sandwich>'
|| 'junk';

The term XML text in the descriptions is the string, which is formed based on the pointer and length passed to the event. The parser may recognize these events in their order of appearance in the structure.

start_of_document
Occurs once, at the beginning of parsing the document. The parser passes no parameters to this event (except the user token).
version_information
Occurs within the optional XML declaration for the version information. The parser passes the address and length of the text containing the version value ("1.0" in the example above).
encoding_declaration
Occurs within the XML declaration for the optional encoding declaration. The parser passes the address and length of the text containing the encoding value.
standalone_declaration
Occurs within the XML declaration for the optional standalone declaration. The parser passes the address and length of the text containing the standalone value ("yes" in the example).
document_type_declaration
Occurs when the parser finds the document type declaration. A document type declaration begins with the character sequence <!DOCTYPE" and ends with a > character. Fairly complicated grammar rules describe the content in between.

The parser passes the address and length of the text containing the entire declaration. This includes the opening and closing character sequences. This is the only event where XML text includes the delimiters. The example above does not have a document type declaration.

end_of_document
Occurs once, when document parsing has completed. The parser passes no parameters to this event (except the user token).
start_of_element
Occurs once for each element start tag or empty element tag. The parser passes the address and length of the text containing the element name as well as any applicable namespace information. The first start_of_element event during parsing in the example contains the string sandwich.
attribute_name
Occurs for each attribute in an element start tag or empty element tag, after recognizing a valid name. The parser passes the address and length of the text containing the attribute name as well as any applicable namespace information. The only attribute name in the example is type.
attribute_characters

Occurs for each fragment of an attribute value. The parser passes the address and length of the text containing the fragment. An attribute value normally consists of a single string only, even if it is split across lines:

<element attribute="This attribute value is
split across two lines"/>
end_of_element
Occurs once for each element end tag or empty element tag whenever the parser recognizes a closing angle bracket of the tag. The parser passes the address and length of the text containing the element name as well as any applicable namespace information.
start_of_CDATA_section
Occurs at the start of a CDATA section. CDATA sections begin with the string <![CDATA[ and end with the string ]]. They are are used to escape blocks of text containing characters that would otherwise be recognized as XML markup. The parser passes no parameters to this event (except the user token).

After this event, the parser passes the content of a CDATA section between these delimiters as as one or more content-characters events. In the preceding example, the content-characters event is passed the text We should add a <relish> element in future!

end_of_CDATA_section
This event occurs when the parser recognizes the end of a CDATA section. The parser passes no parameters to this event (except the user token).
content_characters

This event represents the main body of an XML document. This is the character data between element start and end tags. The parser passes the address and length of the text containing this data, which usually consists of a single string only, even if it is split across lines:

<element1>This character content is
split across two lines"</element1>

The parser also passes a flag byte which indicates if the next event provides additional characters that form part of the content. This can be true when there is a lot of data between the start and end tags.

The parser also uses the content_characters event to pass the text of CDATA sections to the application.

processing_instruction
Processing instructions (PIs) allow XML documents to contain special instructions for applications. This event occurs when the parser recognizes the name following the PI opening character sequence, <?. The event also covers the data following the PI target, up to but not including the PI closing character sequence, ?>. Trailing, but not leading white space characters in the data are included. The parser passes the address and length of the text containing the target, spread in the example, and the address and length of the text containing the data, please use real mayonnaise in the example.
comment
Occurs for any comments in the XML document. The parser passes the address and length of the text between the opening and closing comment delimiters, <!-- and -->, respectively. The only comment text in the example is This document is just an example.
namespace_declare
Occurs for any namespace declarations in the XML document. The parser passes the address and length of the namespace prefix (if any) as well as the address and length of the namespace URI. If there is no namespace prefix, the passed length is zero and the value of the address should not be used. There is no corresponding event in the PLIXSAXA and PLISAXB built-ins.
end_of_input
This event occurs whenever the parser reaches the end of the current input buffer. The parser passes (along with the BYVALUE user token) two BYADDR parameters: the address and length of the next buffer for it to process. This event and the content character events are the only events that have any BYADDR parameters, but this is the only event that has parameters that the called event should change. There is no corresponding event in the PLIXSAXA and PLISAXB built-ins, and it is this event that allows PLISAXC to parse an XML document of arbitrary size.
unresolved_reference
This event occurs for any unresolved references in the XML document. The parser passes the address and length of the unresolved reference.
unknown_attribute_reference
Occurs within attribute values for entity references other than the pre-defined entity references, listed for the event attribute_predefined_reference. The parser passes the address and length of the text containing the entity name.
exception
The parser generates this event when it detects an error processing the XML document.
Parent topic: SAX event structures


PLISAXA and PLISAXB XML Parser event function parameters

All PLISAXA and PLISAXB event functions must return a BYVALUE FIXED BIN(31) value that is a return code to the parser. For the parser to continue normally, this value should be zero.

For the first argument, the event functions pass a POINTER. This is the token value passed originally as the second argument to the built-in function.

With the following exceptions, all of the functions will also be passed a POINTER and a FIXED BIN(31) that supply the address and length of the text element for the event. The following functions and events are different:

end_of_document | No argument other than the user token is passed.
attribute_predefined_reference | In addition to the user token, one additional argument is passed: a CHAR(1) or, for a UTF-16 document, a WIDECHAR(1) that holds the value of the predefined character.
content_predefined_reference | In addition to the user token, one additional argument is passed: a CHAR(1) or, for a UTF-16 document, a WIDECHAR(1) that holds the value of the predefined character.
attribute_character_reference | In addition to the user token, one additional argument is passed: a FIXED BIN(31) that holds the value of the numeric reference.
content_character_reference | In addition to the user token, one additional argument is passed: a FIXED BIN(31) that holds the value of the numeric reference.
processing_instruction In addition to the user token, these additional arguments are passed:
  • a POINTER that is the address of the target text
  • a FIXED BIN(31) that is the length of the target text
  • a POINTER that is the address of the data text
  • a FIXED BIN(31) that is the length of the data text
exception In addition to the user token, these additional arguments are passed:
  • a POINTER that is the address of the offending text
  • a FIXED BIN(31) that is the byte offset of the offending text
  • a FIXED BIN(31) representing the value of the exception code
Parent topic: SAX event structures


PLISAXC XML Parser event function parameters

All of these functions must return a BYVALUE FIXED BIN(31) value that is a return code to the parser. If any value other than zero is returned, the parser terminates.

All of these functions are passed as the first argument a POINTER. This pointer is the token value that is passed originally as the second argument to the built-in.

With the following exceptions, all of the functions have a POINTER and a FIXED BIN(31) passed to them that provide the address and length of the text element for the event. The following functions and events are different:

start_of_document | No argument other than the user token is passed.
end_of_document | No argument other than the user token is passed.
start_of_CDATA | No argument other than the user token is passed.
end_of_CDATA | No argument other than the user token is passed.
start_of_element

In addition to the usual parameters, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
end_of_element

In addition to the usual parameters, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
attribute_name

In addition to the usual parameters, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
namesace_declare

In addition to the user token, these additional arguments are passed.

  • a POINTER that is the address of the namespace prefix
  • a FIXED BIN(31) that is the length of the namespace prefix
  • a POINTER that is the address of the namespace URI
  • a FIXED BIN(31) that is the length of the namespace URI
content_characters In addition to the usual three parameters, a BYVALUE ALIGNED BIT(8) flag byte is passed which indicates:
  • If more content characters are in the next event. This is true if the first bit is on (if the field ANDed with '80'BX is non-null).
  • If there are no characters that need to be escaped if converted back to XML. This is true if the second bit is on(if the field ANDed with '40'BX is non-null).
end_of_input

In addition to the user token, these additional arguments are passed.

  • a POINTER that is the address of the next input buffer
  • a FIXED BIN(31) that is the length of the next input buffer
processing_instruction In addition to the user token, four additional arguments are passed:
  • a POINTER that is the address of the target text
  • a FIXED BIN(31) that is the length of the target text
  • a POINTER that is the address of the data text
  • a FIXED BIN(31) that is the length of the data text
exception In addition to the user token, three additional arguments are passed:
  • a POINTER that is the address of the offending text
  • a FIXED BIN(31) that is the return code for the exception
  • a FIXED BIN(31) that is the reason code for the exception
Parent topic: SAX event structures


XML Parser exception event error codes

There are subtle differences in how errors are handled in our parser vs. IBM's. For example, the Exception event is driven one time per character. When using the SAX Parser, the Exception event is driven one time indicating an error.

This list shows the available exception event error codes for PL/I XML parsing.

XML_ERR_OK = 0,

XML_ERR_INTERNAL_ERROR, /* 1 */

XML_ERR_NO_MEMORY, /* 2 */

XML_ERR_DOCUMENT_START, /* 3 */

XML_ERR_DOCUMENT_EMPTY, /* 4 */

XML_ERR_DOCUMENT_END, /* 5 */

XML_ERR_INVALID_HEX_CHARREF, /* 6 */

XML_ERR_INVALID_DEC_CHARREF, /* 7 */

XML_ERR_INVALID_CHARREF, /* 8 */

XML_ERR_INVALID_CHAR, /* 9 */

XML_ERR_CHARREF_AT_EOF, /* 10 */

XML_ERR_CHARREF_IN_PROLOG, /* 11 */

XML_ERR_CHARREF_IN_EPILOG, /* 12 */

XML_ERR_CHARREF_IN_DTD, /* 13 */

XML_ERR_ENTITYREF_AT_EOF, /* 14 */

XML_ERR_ENTITYREF_IN_PROLOG, /* 15 */

XML_ERR_ENTITYREF_IN_EPILOG, /* 16 */

XML_ERR_ENTITYREF_IN_DTD, /* 17 */

XML_ERR_PEREF_AT_EOF, /* 18 */

XML_ERR_PEREF_IN_PROLOG, /* 19 */

XML_ERR_PEREF_IN_EPILOG, /* 20 */

XML_ERR_PEREF_IN_INT_SUBSET, /* 21 */

XML_ERR_ENTITYREF_NO_NAME, /* 22 */

XML_ERR_ENTITYREF_SEMICOL_MISSING, /* 23 */

XML_ERR_PEREF_NO_NAME, /* 24 */

XML_ERR_PEREF_SEMICOL_MISSING, /* 25 */

XML_ERR_UNDECLARED_ENTITY, /* 26 */

XML_WAR_UNDECLARED_ENTITY, /* 27 */

XML_ERR_UNPARSED_ENTITY, /* 28 */

XML_ERR_ENTITY_IS_EXTERNAL, /* 29 */

XML_ERR_ENTITY_IS_PARAMETER, /* 30 */

XML_ERR_UNKNOWN_ENCODING, /* 31 */

XML_ERR_UNSUPPORTED_ENCODING, /* 32 */

XML_ERR_STRING_NOT_STARTED, /* 33 */

XML_ERR_STRING_NOT_CLOSED, /* 34 */

XML_ERR_NS_DECL_ERROR, /* 35 */

XML_ERR_ENTITY_NOT_STARTED, /* 36 */

XML_ERR_ENTITY_NOT_FINISHED, /* 37 */

XML_ERR_LT_IN_ATTRIBUTE, /* 38 */

XML_ERR_ATTRIBUTE_NOT_STARTED, /* 39 */

XML_ERR_ATTRIBUTE_NOT_FINISHED, /* 40 */

XML_ERR_ATTRIBUTE_WITHOUT_VALUE, /* 41 */

XML_ERR_ATTRIBUTE_REDEFINED, /* 42 */

XML_ERR_LITERAL_NOT_STARTED, /* 43 */

XML_ERR_LITERAL_NOT_FINISHED, /* 44 */

XML_ERR_COMMENT_NOT_FINISHED, /* 45 */

XML_ERR_PI_NOT_STARTED, /* 46 */

XML_ERR_PI_NOT_FINISHED, /* 47 */

XML_ERR_NOTATION_NOT_STARTED, /* 48 */

XML_ERR_NOTATION_NOT_FINISHED, /* 49 */

XML_ERR_ATTLIST_NOT_STARTED, /* 50 */

XML_ERR_ATTLIST_NOT_FINISHED, /* 51 */

XML_ERR_MIXED_NOT_STARTED, /* 52 */

XML_ERR_MIXED_NOT_FINISHED, /* 53 */

XML_ERR_ELEMCONTENT_NOT_STARTED, /* 54 */

XML_ERR_ELEMCONTENT_NOT_FINISHED, /* 55 */

XML_ERR_XMLDECL_NOT_STARTED, /* 56 */

XML_ERR_XMLDECL_NOT_FINISHED, /* 57 */

XML_ERR_CONDSEC_NOT_STARTED, /* 58 */

XML_ERR_CONDSEC_NOT_FINISHED, /* 59 */

XML_ERR_EXT_SUBSET_NOT_FINISHED, /* 60 */

XML_ERR_DOCTYPE_NOT_FINISHED, /* 61 */

XML_ERR_MISPLACED_CDATA_END, /* 62 */

XML_ERR_CDATA_NOT_FINISHED, /* 63 */

XML_ERR_RESERVED_XML_NAME, /* 64 */

XML_ERR_SPACE_REQUIRED, /* 65 */

XML_ERR_SEPARATOR_REQUIRED, /* 66 */

XML_ERR_NMTOKEN_REQUIRED, /* 67 */

XML_ERR_NAME_REQUIRED, /* 68 */

XML_ERR_PCDATA_REQUIRED, /* 69 */

XML_ERR_URI_REQUIRED, /* 70 */

XML_ERR_PUBID_REQUIRED, /* 71 */

XML_ERR_LT_REQUIRED, /* 72 */

XML_ERR_GT_REQUIRED, /* 73 */

XML_ERR_LTSLASH_REQUIRED, /* 74 */

XML_ERR_EQUAL_REQUIRED, /* 75 */

XML_ERR_TAG_NAME_MISMATCH, /* 76 */

XML_ERR_TAG_NOT_FINISHED, /* 77 */

XML_ERR_STANDALONE_VALUE, /* 78 */

XML_ERR_ENCODING_NAME, /* 79 */

XML_ERR_HYPHEN_IN_COMMENT, /* 80 */

XML_ERR_INVALID_ENCODING, /* 81 */

XML_ERR_EXT_ENTITY_STANDALONE, /* 82 */

XML_ERR_CONDSEC_INVALID, /* 83 */

XML_ERR_VALUE_REQUIRED, /* 84 */

XML_ERR_NOT_WELL_BALANCED, /* 85 */

XML_ERR_EXTRA_CONTENT, /* 86 */

XML_ERR_ENTITY_CHAR_ERROR, /* 87 */

XML_ERR_ENTITY_PE_INTERNAL, /* 88 */

XML_ERR_ENTITY_LOOP, /* 89 */

XML_ERR_ENTITY_BOUNDARY, /* 90 */

XML_ERR_INVALID_URI, /* 91 */

XML_ERR_URI_FRAGMENT, /* 92 */

XML_WAR_CATALOG_PI, /* 93 */

XML_ERR_NO_DTD, /* 94 */

XML_ERR_CONDSEC_INVALID_KEYWORD, /* 95 */

XML_ERR_VERSION_MISSING, /* 96 */

XML_WAR_UNKNOWN_VERSION, /* 97 */

XML_WAR_LANG_VALUE, /* 98 */

XML_WAR_NS_URI, /* 99 */

XML_WAR_NS_URI_RELATIVE, /* 100 */

XML_ERR_MISSING_ENCODING, /* 101 */

XML_WAR_SPACE_VALUE, /* 102 */

XML_ERR_NOT_STANDALONE, /* 103 */

XML_ERR_ENTITY_PROCESSING, /* 104 */

XML_ERR_NOTATION_PROCESSING, /* 105 */

XML_WAR_NS_COLUMN, /* 106 */

XML_WAR_ENTITY_REDEFINED, /* 107 */

XML_ERR_UNKNOWN_VERSION, /* 108 */

XML_ERR_VERSION_MISMATCH, /* 109 */

XML_NS_ERR_XML_NAMESPACE = 200,

XML_NS_ERR_UNDEFINED_NAMESPACE, /* 201 */

XML_NS_ERR_QNAME, /* 202 */

XML_NS_ERR_ATTRIBUTE_REDEFINED, /* 203 */

XML_NS_ERR_EMPTY, /* 204 */

XML_NS_ERR_COLON, /* 205 */

XML_DTD_ATTRIBUTE_DEFAULT = 500,

XML_DTD_ATTRIBUTE_REDEFINED, /* 501 */

XML_DTD_ATTRIBUTE_VALUE, /* 502 */

XML_DTD_CONTENT_ERROR, /* 503 */

XML_DTD_CONTENT_MODEL, /* 504 */

XML_DTD_CONTENT_NOT_DETERMINIST, /* 505 */

XML_DTD_DIFFERENT_PREFIX, /* 506 */

XML_DTD_ELEM_DEFAULT_NAMESPACE, /* 507 */

XML_DTD_ELEM_NAMESPACE, /* 508 */

XML_DTD_ELEM_REDEFINED, /* 509 */

XML_DTD_EMPTY_NOTATION, /* 510 */

XML_DTD_ENTITY_TYPE, /* 511 */

XML_DTD_ID_FIXED, /* 512 */

XML_DTD_ID_REDEFINED, /* 513 */

XML_DTD_ID_SUBSET, /* 514 */

XML_DTD_INVALID_CHILD, /* 515 */

XML_DTD_INVALID_DEFAULT, /* 516 */

XML_DTD_LOAD_ERROR, /* 517 */

XML_DTD_MISSING_ATTRIBUTE, /* 518 */

XML_DTD_MIXED_CORRUPT, /* 519 */

XML_DTD_MULTIPLE_ID, /* 520 */

XML_DTD_NO_DOC, /* 521 */

XML_DTD_NO_DTD, /* 522 */

XML_DTD_NO_ELEM_NAME, /* 523 */

XML_DTD_NO_PREFIX, /* 524 */

XML_DTD_NO_ROOT, /* 525 */

XML_DTD_NOTATION_REDEFINED, /* 526 */

XML_DTD_NOTATION_VALUE, /* 527 */

XML_DTD_NOT_EMPTY, /* 528 */

XML_DTD_NOT_PCDATA, /* 529 */

XML_DTD_NOT_STANDALONE, /* 530 */

XML_DTD_ROOT_NAME, /* 531 */

XML_DTD_STANDALONE_WHITE_SPACE, /* 532 */

XML_DTD_UNKNOWN_ATTRIBUTE, /* 533 */

XML_DTD_UNKNOWN_ELEM, /* 534 */

XML_DTD_UNKNOWN_ENTITY, /* 535 */

XML_DTD_UNKNOWN_ID, /* 536 */

XML_DTD_UNKNOWN_NOTATION, /* 537 */

XML_DTD_STANDALONE_DEFAULTED, /* 538 */

XML_DTD_XMLID_VALUE, /* 539 */

XML_DTD_XMLID_TYPE, /* 540 */

XML_DTD_DUP_TOKEN, /* 541 */

XML_HTML_STRUCURE_ERROR = 800,

XML_HTML_UNKNOWN_TAG, /* 801 */

XML_RNGP_ANYNAME_ATTR_ANCESTOR = 1000,

XML_RNGP_ATTR_CONFLICT, /* 1001 */

XML_RNGP_ATTRIBUTE_CHILDREN, /* 1002 */

XML_RNGP_ATTRIBUTE_CONTENT, /* 1003 */

XML_RNGP_ATTRIBUTE_EMPTY, /* 1004 */

XML_RNGP_ATTRIBUTE_NOOP, /* 1005 */

XML_RNGP_CHOICE_CONTENT, /* 1006 */

XML_RNGP_CHOICE_EMPTY, /* 1007 */

XML_RNGP_CREATE_FAILURE, /* 1008 */

XML_RNGP_DATA_CONTENT, /* 1009 */

XML_RNGP_DEF_CHOICE_AND_INTERLEAVE, /* 1010 */

XML_RNGP_DEFINE_CREATE_FAILED, /* 1011 */

XML_RNGP_DEFINE_EMPTY, /* 1012 */

XML_RNGP_DEFINE_MISSING, /* 1013 */

XML_RNGP_DEFINE_NAME_MISSING, /* 1014 */

XML_RNGP_ELEM_CONTENT_EMPTY, /* 1015 */

XML_RNGP_ELEM_CONTENT_ERROR, /* 1016 */

XML_RNGP_ELEMENT_EMPTY, /* 1017 */

XML_RNGP_ELEMENT_CONTENT, /* 1018 */

XML_RNGP_ELEMENT_NAME, /* 1019 */

XML_RNGP_ELEMENT_NO_CONTENT, /* 1020 */

XML_RNGP_ELEM_TEXT_CONFLICT, /* 1021 */

XML_RNGP_EMPTY, /* 1022 */

XML_RNGP_EMPTY_CONSTRUCT, /* 1023 */

XML_RNGP_EMPTY_CONTENT, /* 1024 */

XML_RNGP_EMPTY_NOT_EMPTY, /* 1025 */

XML_RNGP_ERROR_TYPE_LIB, /* 1026 */

XML_RNGP_EXCEPT_EMPTY, /* 1027 */

XML_RNGP_EXCEPT_MISSING, /* 1028 */

XML_RNGP_EXCEPT_MULTIPLE, /* 1029 */

XML_RNGP_EXCEPT_NO_CONTENT, /* 1030 */

XML_RNGP_EXTERNALREF_EMTPY, /* 1031 */

XML_RNGP_EXTERNAL_REF_FAILURE, /* 1032 */

XML_RNGP_EXTERNALREF_RECURSE, /* 1033 */

XML_RNGP_FORBIDDEN_ATTRIBUTE, /* 1034 */

XML_RNGP_FOREIGN_ELEMENT, /* 1035 */

XML_RNGP_GRAMMAR_CONTENT, /* 1036 */

XML_RNGP_GRAMMAR_EMPTY, /* 1037 */

XML_RNGP_GRAMMAR_MISSING, /* 1038 */

XML_RNGP_GRAMMAR_NO_START, /* 1039 */

XML_RNGP_GROUP_ATTR_CONFLICT, /* 1040 */

XML_RNGP_HREF_ERROR, /* 1041 */

XML_RNGP_INCLUDE_EMPTY, /* 1042 */

XML_RNGP_INCLUDE_FAILURE, /* 1043 */

XML_RNGP_INCLUDE_RECURSE, /* 1044 */

XML_RNGP_INTERLEAVE_ADD, /* 1045 */

XML_RNGP_INTERLEAVE_CREATE_FAILED, /* 1046 */

XML_RNGP_INTERLEAVE_EMPTY, /* 1047 */

XML_RNGP_INTERLEAVE_NO_CONTENT, /* 1048 */

XML_RNGP_INVALID_DEFINE_NAME, /* 1049 */

XML_RNGP_INVALID_URI, /* 1050 */

XML_RNGP_INVALID_VALUE, /* 1051 */

XML_RNGP_MISSING_HREF, /* 1052 */

XML_RNGP_NAME_MISSING, /* 1053 */

XML_RNGP_NEED_COMBINE, /* 1054 */

XML_RNGP_NOTALLOWED_NOT_EMPTY, /* 1055 */

XML_RNGP_NSNAME_ATTR_ANCESTOR, /* 1056 */

XML_RNGP_NSNAME_NO_NS, /* 1057 */

XML_RNGP_PARAM_FORBIDDEN, /* 1058 */

XML_RNGP_PARAM_NAME_MISSING, /* 1059 */

XML_RNGP_PARENTREF_CREATE_FAILED, /* 1060 */

XML_RNGP_PARENTREF_NAME_INVALID, /* 1061 */

XML_RNGP_PARENTREF_NO_NAME, /* 1062 */

XML_RNGP_PARENTREF_NO_PARENT, /* 1063 */

XML_RNGP_PARENTREF_NOT_EMPTY, /* 1064 */

XML_RNGP_PARSE_ERROR, /* 1065 */

XML_RNGP_PAT_ANYNAME_EXCEPT_ANYNAME, /* 1066 */

XML_RNGP_PAT_ATTR_ATTR, /* 1067 */

XML_RNGP_PAT_ATTR_ELEM, /* 1068 */

XML_RNGP_PAT_DATA_EXCEPT_ATTR, /* 1069 */

XML_RNGP_PAT_DATA_EXCEPT_ELEM, /* 1070 */

XML_RNGP_PAT_DATA_EXCEPT_EMPTY, /* 1071 */

XML_RNGP_PAT_DATA_EXCEPT_GROUP, /* 1072 */

XML_RNGP_PAT_DATA_EXCEPT_INTERLEAVE, /* 1073 */

XML_RNGP_PAT_DATA_EXCEPT_LIST, /* 1074 */

XML_RNGP_PAT_DATA_EXCEPT_ONEMORE, /* 1075 */

XML_RNGP_PAT_DATA_EXCEPT_REF, /* 1076 */

XML_RNGP_PAT_DATA_EXCEPT_TEXT, /* 1077 */

XML_RNGP_PAT_LIST_ATTR, /* 1078 */

XML_RNGP_PAT_LIST_ELEM, /* 1079 */

XML_RNGP_PAT_LIST_INTERLEAVE, /* 1080 */

XML_RNGP_PAT_LIST_LIST, /* 1081 */

XML_RNGP_PAT_LIST_REF, /* 1082 */

XML_RNGP_PAT_LIST_TEXT, /* 1083 */

XML_RNGP_PAT_NSNAME_EXCEPT_ANYNAME, /* 1084 */

XML_RNGP_PAT_NSNAME_EXCEPT_NSNAME, /* 1085 */

XML_RNGP_PAT_ONEMORE_GROUP_ATTR, /* 1086 */

XML_RNGP_PAT_ONEMORE_INTERLEAVE_ATTR, /* 1087 */

XML_RNGP_PAT_START_ATTR, /* 1088 */

XML_RNGP_PAT_START_DATA, /* 1089 */

XML_RNGP_PAT_START_EMPTY, /* 1090 */

XML_RNGP_PAT_START_GROUP, /* 1091 */

XML_RNGP_PAT_START_INTERLEAVE, /* 1092 */

XML_RNGP_PAT_START_LIST, /* 1093 */

XML_RNGP_PAT_START_ONEMORE, /* 1094 */

XML_RNGP_PAT_START_TEXT, /* 1095 */

XML_RNGP_PAT_START_VALUE, /* 1096 */

XML_RNGP_PREFIX_UNDEFINED, /* 1097 */

XML_RNGP_REF_CREATE_FAILED, /* 1098 */

XML_RNGP_REF_CYCLE, /* 1099 */

XML_RNGP_REF_NAME_INVALID, /* 1100 */

XML_RNGP_REF_NO_DEF, /* 1101 */

XML_RNGP_REF_NO_NAME, /* 1102 */

XML_RNGP_REF_NOT_EMPTY, /* 1103 */

XML_RNGP_START_CHOICE_AND_INTERLEAVE, /* 1104 */

XML_RNGP_START_CONTENT, /* 1105 */

XML_RNGP_START_EMPTY, /* 1106 */

XML_RNGP_START_MISSING, /* 1107 */

XML_RNGP_TEXT_EXPECTED, /* 1108 */

XML_RNGP_TEXT_HAS_CHILD, /* 1109 */

XML_RNGP_TYPE_MISSING, /* 1110 */

XML_RNGP_TYPE_NOT_FOUND, /* 1111 */

XML_RNGP_TYPE_VALUE, /* 1112 */

XML_RNGP_UNKNOWN_ATTRIBUTE, /* 1113 */

XML_RNGP_UNKNOWN_COMBINE, /* 1114 */

XML_RNGP_UNKNOWN_CONSTRUCT, /* 1115 */

XML_RNGP_UNKNOWN_TYPE_LIB, /* 1116 */

XML_RNGP_URI_FRAGMENT, /* 1117 */

XML_RNGP_URI_NOT_ABSOLUTE, /* 1118 */

XML_RNGP_VALUE_EMPTY, /* 1119 */

XML_RNGP_VALUE_NO_CONTENT, /* 1120 */

XML_RNGP_XMLNS_NAME, /* 1121 */

XML_RNGP_XML_NS, /* 1122 */

XML_XPATH_EXPRESSION_OK = 1200,

XML_XPATH_NUMBER_ERROR, /* 1201 */

XML_XPATH_UNFINISHED_LITERAL_ERROR, /* 1202 */

XML_XPATH_START_LITERAL_ERROR, /* 1203 */

XML_XPATH_VARIABLE_REF_ERROR, /* 1204 */

XML_XPATH_UNDEF_VARIABLE_ERROR, /* 1205 */

XML_XPATH_INVALID_PREDICATE_ERROR, /* 1206 */

XML_XPATH_EXPR_ERROR, /* 1207 */

XML_XPATH_UNCLOSED_ERROR, /* 1208 */

XML_XPATH_UNKNOWN_FUNC_ERROR, /* 1209 */

XML_XPATH_INVALID_OPERAND, /* 1210 */

XML_XPATH_INVALID_TYPE, /* 1211 */

XML_XPATH_INVALID_ARITY, /* 1212 */

XML_XPATH_INVALID_CTXT_SIZE, /* 1213 */

XML_XPATH_INVALID_CTXT_POSITION, /* 1214 */

XML_XPATH_MEMORY_ERROR, /* 1215 */

XML_XPTR_SYNTAX_ERROR, /* 1216 */

XML_XPTR_RESOURCE_ERROR, /* 1217 */

XML_XPTR_SUB_RESOURCE_ERROR, /* 1218 */

XML_XPATH_UNDEF_PREFIX_ERROR, /* 1219 */

XML_XPATH_ENCODING_ERROR, /* 1220 */

XML_XPATH_INVALID_CHAR_ERROR, /* 1221 */

XML_TREE_INVALID_HEX = 1300,

XML_TREE_INVALID_DEC, /* 1301 */

XML_TREE_UNTERMINATED_ENTITY, /* 1302 */

XML_TREE_NOT_UTF8, /* 1303 */

XML_SAVE_NOT_UTF8 = 1400,

XML_SAVE_CHAR_INVALID, /* 1401 */

XML_SAVE_NO_DOCTYPE, /* 1402 */

XML_SAVE_UNKNOWN_ENCODING, /* 1403 */

XML_REGEXP_COMPILE_ERROR = 1450,

XML_IO_UNKNOWN = 1500,

XML_IO_EACCES, /* 1501 */

XML_IO_EAGAIN, /* 1502 */

XML_IO_EBADF, /* 1503 */

XML_IO_EBADMSG, /* 1504 */

XML_IO_EBUSY, /* 1505 */

XML_IO_ECANCELED, /* 1506 */

XML_IO_ECHILD, /* 1507 */

XML_IO_EDEADLK, /* 1508 */

XML_IO_EDOM, /* 1509 */

XML_IO_EEXIST, /* 1510 */

XML_IO_EFAULT, /* 1511 */

XML_IO_EFBIG, /* 1512 */

XML_IO_EINPROGRESS, /* 1513 */

XML_IO_EINTR, /* 1514 */

XML_IO_EINVAL, /* 1515 */

XML_IO_EIO, /* 1516 */

XML_IO_EISDIR, /* 1517 */

XML_IO_EMFILE, /* 1518 */

XML_IO_EMLINK, /* 1519 */

XML_IO_EMSGSIZE, /* 1520 */

XML_IO_ENAMETOOLONG, /* 1521 */

XML_IO_ENFILE, /* 1522 */

XML_IO_ENODEV, /* 1523 */

XML_IO_ENOENT, /* 1524 */

XML_IO_ENOEXEC, /* 1525 */

XML_IO_ENOLCK, /* 1526 */

XML_IO_ENOMEM, /* 1527 */

XML_IO_ENOSPC, /* 1528 */

XML_IO_ENOSYS, /* 1529 */

XML_IO_ENOTDIR, /* 1530 */

XML_IO_ENOTEMPTY, /* 1531 */

XML_IO_ENOTSUP, /* 1532 */

XML_IO_ENOTTY, /* 1533 */

XML_IO_ENXIO, /* 1534 */

XML_IO_EPERM, /* 1535 */

XML_IO_EPIPE, /* 1536 */

XML_IO_ERANGE, /* 1537 */

XML_IO_EROFS, /* 1538 */

XML_IO_ESPIPE, /* 1539 */

XML_IO_ESRCH, /* 1540 */

XML_IO_ETIMEDOUT, /* 1541 */

XML_IO_EXDEV, /* 1542 */

XML_IO_NETWORK_ATTEMPT, /* 1543 */

XML_IO_ENCODER, /* 1544 */

XML_IO_FLUSH, /* 1545 */

XML_IO_WRITE, /* 1546 */

XML_IO_NO_INPUT, /* 1547 */

XML_IO_BUFFER_FULL, /* 1548 */

XML_IO_LOAD_ERROR, /* 1549 */

XML_IO_ENOTSOCK, /* 1550 */

XML_IO_EISCONN, /* 1551 */

XML_IO_ECONNREFUSED, /* 1552 */

XML_IO_ENETUNREACH, /* 1553 */

XML_IO_EADDRINUSE, /* 1554 */

XML_IO_EALREADY, /* 1555 */

XML_IO_EAFNOSUPPORT, /* 1556 */

XML_XINCLUDE_RECURSION=1600,

XML_XINCLUDE_PARSE_VALUE, /* 1601 */

XML_XINCLUDE_ENTITY_DEF_MISMATCH, /* 1602 */

XML_XINCLUDE_NO_HREF, /* 1603 */

XML_XINCLUDE_NO_FALLBACK, /* 1604 */

XML_XINCLUDE_HREF_URI, /* 1605 */

XML_XINCLUDE_TEXT_FRAGMENT, /* 1606 */

XML_XINCLUDE_TEXT_DOCUMENT, /* 1607 */

XML_XINCLUDE_INVALID_CHAR, /* 1608 */

XML_XINCLUDE_BUILD_FAILED, /* 1609 */

XML_XINCLUDE_UNKNOWN_ENCODING, /* 1610 */

XML_XINCLUDE_MULTIPLE_ROOT, /* 1611 */

XML_XINCLUDE_XPTR_FAILED, /* 1612 */

XML_XINCLUDE_XPTR_RESULT, /* 1613 */

XML_XINCLUDE_INCLUDE_IN_INCLUDE, /* 1614 */

XML_XINCLUDE_FALLBACKS_IN_INCLUDE, /* 1615 */

XML_XINCLUDE_FALLBACK_NOT_IN_INCLUDE, /* 1616 */

XML_XINCLUDE_DEPRECATED_NS, /* 1617 */

XML_XINCLUDE_FRAGMENT_ID, /* 1618 */

XML_CATALOG_MISSING_ATTR = 1650,

XML_CATALOG_ENTRY_BROKEN, /* 1651 */

XML_CATALOG_PREFER_VALUE, /* 1652 */

XML_CATALOG_NOT_CATALOG, /* 1653 */

XML_CATALOG_RECURSION, /* 1654 */

XML_SCHEMAP_PREFIX_UNDEFINED = 1700,

XML_SCHEMAP_ATTRFORMDEFAULT_VALUE, /* 1701 */

XML_SCHEMAP_ATTRGRP_NONAME_NOREF, /* 1702 */

XML_SCHEMAP_ATTR_NONAME_NOREF, /* 1703 */

XML_SCHEMAP_COMPLEXTYPE_NONAME_NOREF, /* 1704 */

XML_SCHEMAP_ELEMFORMDEFAULT_VALUE, /* 1705 */

XML_SCHEMAP_ELEM_NONAME_NOREF, /* 1706 */

XML_SCHEMAP_EXTENSION_NO_BASE, /* 1707 */

XML_SCHEMAP_FACET_NO_VALUE, /* 1708 */

XML_SCHEMAP_FAILED_BUILD_IMPORT, /* 1709 */

XML_SCHEMAP_GROUP_NONAME_NOREF, /* 1710 */

XML_SCHEMAP_IMPORT_NAMESPACE_NOT_URI, /* 1711 */

XML_SCHEMAP_IMPORT_REDEFINE_NSNAME, /* 1712 */

XML_SCHEMAP_IMPORT_SCHEMA_NOT_URI, /* 1713 */

XML_SCHEMAP_INVALID_BOOLEAN, /* 1714 */

XML_SCHEMAP_INVALID_ENUM, /* 1715 */

XML_SCHEMAP_INVALID_FACET, /* 1716 */

XML_SCHEMAP_INVALID_FACET_VALUE, /* 1717 */

XML_SCHEMAP_INVALID_MAXOCCURS, /* 1718 */

XML_SCHEMAP_INVALID_MINOCCURS, /* 1719 */

XML_SCHEMAP_INVALID_REF_AND_SUBTYPE, /* 1720 */

XML_SCHEMAP_INVALID_WHITE_SPACE, /* 1721 */

XML_SCHEMAP_NOATTR_NOREF, /* 1722 */

XML_SCHEMAP_NOTATION_NO_NAME, /* 1723 */

XML_SCHEMAP_NOTYPE_NOREF, /* 1724 */

XML_SCHEMAP_REF_AND_SUBTYPE, /* 1725 */

XML_SCHEMAP_RESTRICTION_NONAME_NOREF, /* 1726 */

XML_SCHEMAP_SIMPLETYPE_NONAME, /* 1727 */

XML_SCHEMAP_TYPE_AND_SUBTYPE, /* 1728 */

XML_SCHEMAP_UNKNOWN_ALL_CHILD, /* 1729 */

XML_SCHEMAP_UNKNOWN_ANYATTRIBUTE_CHILD, /* 1730 */

XML_SCHEMAP_UNKNOWN_ATTR_CHILD, /* 1731 */

XML_SCHEMAP_UNKNOWN_ATTRGRP_CHILD, /* 1732 */

XML_SCHEMAP_UNKNOWN_ATTRIBUTE_GROUP, /* 1733 */

XML_SCHEMAP_UNKNOWN_BASE_TYPE, /* 1734 */

XML_SCHEMAP_UNKNOWN_CHOICE_CHILD, /* 1735 */

XML_SCHEMAP_UNKNOWN_COMPLEXCONTENT_CHILD, /* 1736 */

XML_SCHEMAP_UNKNOWN_COMPLEXTYPE_CHILD, /* 1737 */

XML_SCHEMAP_UNKNOWN_ELEM_CHILD, /* 1738 */

XML_SCHEMAP_UNKNOWN_EXTENSION_CHILD, /* 1739 */

XML_SCHEMAP_UNKNOWN_FACET_CHILD, /* 1740 */

XML_SCHEMAP_UNKNOWN_FACET_TYPE, /* 1741 */

XML_SCHEMAP_UNKNOWN_GROUP_CHILD, /* 1742 */

XML_SCHEMAP_UNKNOWN_IMPORT_CHILD, /* 1743 */

XML_SCHEMAP_UNKNOWN_LIST_CHILD, /* 1744 */

XML_SCHEMAP_UNKNOWN_NOTATION_CHILD, /* 1745 */

XML_SCHEMAP_UNKNOWN_PROCESSCONTENT_CHILD, /* 1746 */

XML_SCHEMAP_UNKNOWN_REF, /* 1747 */

XML_SCHEMAP_UNKNOWN_RESTRICTION_CHILD, /* 1748 */

XML_SCHEMAP_UNKNOWN_SCHEMAS_CHILD, /* 1749 */

XML_SCHEMAP_UNKNOWN_SEQUENCE_CHILD, /* 1750 */

XML_SCHEMAP_UNKNOWN_SIMPLECONTENT_CHILD, /* 1751 */

XML_SCHEMAP_UNKNOWN_SIMPLETYPE_CHILD, /* 1752 */

XML_SCHEMAP_UNKNOWN_TYPE, /* 1753 */

XML_SCHEMAP_UNKNOWN_UNION_CHILD, /* 1754 */

XML_SCHEMAP_ELEM_DEFAULT_FIXED, /* 1755 */

XML_SCHEMAP_REGEXP_INVALID, /* 1756 */

XML_SCHEMAP_FAILED_LOAD, /* 1757 */

XML_SCHEMAP_NOTHING_TO_PARSE, /* 1758 */

XML_SCHEMAP_NOROOT, /* 1759 */

XML_SCHEMAP_REDEFINED_GROUP, /* 1760 */

XML_SCHEMAP_REDEFINED_TYPE, /* 1761 */

XML_SCHEMAP_REDEFINED_ELEMENT, /* 1762 */

XML_SCHEMAP_REDEFINED_ATTRGROUP, /* 1763 */

XML_SCHEMAP_REDEFINED_ATTR, /* 1764 */

XML_SCHEMAP_REDEFINED_NOTATION, /* 1765 */

XML_SCHEMAP_FAILED_PARSE, /* 1766 */

XML_SCHEMAP_UNKNOWN_PREFIX, /* 1767 */

XML_SCHEMAP_DEF_AND_PREFIX, /* 1768 */

XML_SCHEMAP_UNKNOWN_INCLUDE_CHILD, /* 1769 */

XML_SCHEMAP_INCLUDE_SCHEMA_NOT_URI, /* 1770 */

XML_SCHEMAP_INCLUDE_SCHEMA_NO_URI, /* 1771 */

XML_SCHEMAP_NOT_SCHEMA, /* 1772 */

XML_SCHEMAP_UNKNOWN_MEMBER_TYPE, /* 1773 */

XML_SCHEMAP_INVALID_ATTR_USE, /* 1774 */

XML_SCHEMAP_RECURSIVE, /* 1775 */

XML_SCHEMAP_SUPERNUMEROUS_LIST_ITEM_TYPE, /* 1776 */

XML_SCHEMAP_INVALID_ATTR_COMBINATION, /* 1777 */

XML_SCHEMAP_INVALID_ATTR_INLINE_COMBINATION, /* 1778 */

XML_SCHEMAP_MISSING_SIMPLETYPE_CHILD, /* 1779 */

XML_SCHEMAP_INVALID_ATTR_NAME, /* 1780 */

XML_SCHEMAP_REF_AND_CONTENT, /* 1781 */

XML_SCHEMAP_CT_PROPS_CORRECT_1, /* 1782 */

XML_SCHEMAP_CT_PROPS_CORRECT_2, /* 1783 */

XML_SCHEMAP_CT_PROPS_CORRECT_3, /* 1784 */

XML_SCHEMAP_CT_PROPS_CORRECT_4, /* 1785 */

XML_SCHEMAP_CT_PROPS_CORRECT_5, /* 1786 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_1, /* 1787 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_1_1, /* 1788 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_1_2, /* 1789 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_2, /* 1790 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_3, /* 1791 */

XML_SCHEMAP_WILDCARD_INVALID_NS_MEMBER, /* 1792 */

XML_SCHEMAP_INTERSECTION_NOT_EXPRESSIBLE, /* 1793 */

XML_SCHEMAP_UNION_NOT_EXPRESSIBLE, /* 1794 */

XML_SCHEMAP_SRC_IMPORT_3_1, /* 1795 */

XML_SCHEMAP_SRC_IMPORT_3_2, /* 1796 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_4_1, /* 1797 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_4_2, /* 1798 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_4_3, /* 1799 */

XML_SCHEMAP_COS_CT_EXTENDS_1_3, /* 1800 */

XML_SCHEMAV_NOROOT = 1801,

XML_SCHEMAV_UNDECLAREDELEM, /* 1802 */

XML_SCHEMAV_NOTTOPLEVEL, /* 1803 */

XML_SCHEMAV_MISSING, /* 1804 */

XML_SCHEMAV_WRONGELEM, /* 1805 */

XML_SCHEMAV_NOTYPE, /* 1806 */

XML_SCHEMAV_NOROLLBACK, /* 1807 */

XML_SCHEMAV_ISABSTRACT, /* 1808 */

XML_SCHEMAV_NOTEMPTY, /* 1809 */

XML_SCHEMAV_ELEMCONT, /* 1810 */

XML_SCHEMAV_HAVEDEFAULT, /* 1811 */

XML_SCHEMAV_NOTNILLABLE, /* 1812 */

XML_SCHEMAV_EXTRACONTENT, /* 1813 */

XML_SCHEMAV_INVALIDATTR, /* 1814 */

XML_SCHEMAV_INVALIDELEM, /* 1815 */

XML_SCHEMAV_NOTDETERMINIST, /* 1816 */

XML_SCHEMAV_CONSTRUCT, /* 1817 */

XML_SCHEMAV_INTERNAL, /* 1818 */

XML_SCHEMAV_NOTSIMPLE, /* 1819 */

XML_SCHEMAV_ATTRUNKNOWN, /* 1820 */

XML_SCHEMAV_ATTRINVALID, /* 1821 */

XML_SCHEMAV_VALUE, /* 1822 */

XML_SCHEMAV_FACET, /* 1823 */

XML_SCHEMAV_CVC_DATATYPE_VALID_1_2_1, /* 1824 */

XML_SCHEMAV_CVC_DATATYPE_VALID_1_2_2, /* 1825 */

XML_SCHEMAV_CVC_DATATYPE_VALID_1_2_3, /* 1826 */

XML_SCHEMAV_CVC_TYPE_3_1_1, /* 1827 */

XML_SCHEMAV_CVC_TYPE_3_1_2, /* 1828 */

XML_SCHEMAV_CVC_FACET_VALID, /* 1829 */

XML_SCHEMAV_CVC_LENGTH_VALID, /* 1830 */

XML_SCHEMAV_CVC_MINLENGTH_VALID, /* 1831 */

XML_SCHEMAV_CVC_MAXLENGTH_VALID, /* 1832 */

XML_SCHEMAV_CVC_MININCLUSIVE_VALID, /* 1833 */

XML_SCHEMAV_CVC_MAXINCLUSIVE_VALID, /* 1834 */

XML_SCHEMAV_CVC_MINEXCLUSIVE_VALID, /* 1835 */

XML_SCHEMAV_CVC_MAXEXCLUSIVE_VALID, /* 1836 */

XML_SCHEMAV_CVC_TOTALDIGITS_VALID, /* 1837 */

XML_SCHEMAV_CVC_FRACTIONDIGITS_VALID, /* 1838 */

XML_SCHEMAV_CVC_PATTERN_VALID, /* 1839 */

XML_SCHEMAV_CVC_ENUMERATION_VALID, /* 1840 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_1, /* 1841 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_2, /* 1842 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_3, /* 1843 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_2_4, /* 1844 */

XML_SCHEMAV_CVC_ELT_1, /* 1845 */

XML_SCHEMAV_CVC_ELT_2, /* 1846 */

XML_SCHEMAV_CVC_ELT_3_1, /* 1847 */

XML_SCHEMAV_CVC_ELT_3_2_1, /* 1848 */

XML_SCHEMAV_CVC_ELT_3_2_2, /* 1849 */

XML_SCHEMAV_CVC_ELT_4_1, /* 1850 */

XML_SCHEMAV_CVC_ELT_4_2, /* 1851 */

XML_SCHEMAV_CVC_ELT_4_3, /* 1852 */

XML_SCHEMAV_CVC_ELT_5_1_1, /* 1853 */

XML_SCHEMAV_CVC_ELT_5_1_2, /* 1854 */

XML_SCHEMAV_CVC_ELT_5_2_1, /* 1855 */

XML_SCHEMAV_CVC_ELT_5_2_2_1, /* 1856 */

XML_SCHEMAV_CVC_ELT_5_2_2_2_1, /* 1857 */

XML_SCHEMAV_CVC_ELT_5_2_2_2_2, /* 1858 */

XML_SCHEMAV_CVC_ELT_6, /* 1859 */

XML_SCHEMAV_CVC_ELT_7, /* 1860 */

XML_SCHEMAV_CVC_ATTRIBUTE_1, /* 1861 */

XML_SCHEMAV_CVC_ATTRIBUTE_2, /* 1862 */

XML_SCHEMAV_CVC_ATTRIBUTE_3, /* 1863 */

XML_SCHEMAV_CVC_ATTRIBUTE_4, /* 1864 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_3_1, /* 1865 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_3_2_1, /* 1866 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_3_2_2, /* 1867 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_4, /* 1868 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_5_1, /* 1869 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_5_2, /* 1870 */

XML_SCHEMAV_ELEMENT_CONTENT, /* 1871 */

XML_SCHEMAV_DOCUMENT_ELEMENT_MISSING, /* 1872 */

XML_SCHEMAV_CVC_COMPLEX_TYPE_1, /* 1873 */

XML_SCHEMAV_CVC_AU, /* 1874 */

XML_SCHEMAV_CVC_TYPE_1, /* 1875 */

XML_SCHEMAV_CVC_TYPE_2, /* 1876 */

XML_SCHEMAV_CVC_IDC, /* 1877 */

XML_SCHEMAV_CVC_WILDCARD, /* 1878 */

XML_SCHEMAV_MISC, /* 1879 */

XML_XPTR_UNKNOWN_SCHEME = 1900,

XML_XPTR_CHILDSEQ_START, /* 1901 */

XML_XPTR_EVAL_FAILED, /* 1902 */

XML_XPTR_EXTRA_OBJECTS, /* 1903 */

XML_C14N_CREATE_CTXT = 1950,

XML_C14N_REQUIRES_UTF8, /* 1951 */

XML_C14N_CREATE_STACK, /* 1952 */

XML_C14N_INVALID_NODE, /* 1953 */

XML_C14N_UNKNOWN_NODE, /* 1954 */

XML_C14N_RELATIVE_NAMESPACE, /* 1955 */

XML_FTP_PASV_ANSWER = 2000,

XML_FTP_EPSV_ANSWER, /* 2001 */

XML_FTP_ACCNT, /* 2002 */

XML_FTP_URL_SYNTAX, /* 2003 */

XML_HTTP_URL_SYNTAX = 2020,

XML_HTTP_USE_IP, /* 2021 */

XML_HTTP_UNKNOWN_HOST, /* 2022 */

XML_SCHEMAP_SRC_SIMPLE_TYPE_1 = 3000,

XML_SCHEMAP_SRC_SIMPLE_TYPE_2, /* 3001 */

XML_SCHEMAP_SRC_SIMPLE_TYPE_3, /* 3002 */

XML_SCHEMAP_SRC_SIMPLE_TYPE_4, /* 3003 */

XML_SCHEMAP_SRC_RESOLVE, /* 3004 */

XML_SCHEMAP_SRC_RESTRICTION_BASE_OR_SIMPLETYPE, /* 3005 */

XML_SCHEMAP_SRC_LIST_ITEMTYPE_OR_SIMPLETYPE, /* 3006 */

XML_SCHEMAP_SRC_UNION_MEMBERTYPES_OR_SIMPLETYPES, /* 3007 */

XML_SCHEMAP_ST_PROPS_CORRECT_1, /* 3008 */

XML_SCHEMAP_ST_PROPS_CORRECT_2, /* 3009 */

XML_SCHEMAP_ST_PROPS_CORRECT_3, /* 3010 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_1, /* 3011 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_2, /* 3012 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_3_1, /* 3013 */

XML_SCHEMAP_COS_ST_RESTRICTS_1_3_2, /* 3014 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_1, /* 3015 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_1_1, /* 3016 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_1_2, /* 3017 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_1, /* 3018 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_2, /* 3019 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_3, /* 3020 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_4, /* 3021 */

XML_SCHEMAP_COS_ST_RESTRICTS_2_3_2_5, /* 3022 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_1, /* 3023 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_1, /* 3024 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_1_2, /* 3025 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_2, /* 3026 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_1, /* 3027 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_3, /* 3028 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_4, /* 3029 */

XML_SCHEMAP_COS_ST_RESTRICTS_3_3_2_5, /* 3030 */

XML_SCHEMAP_COS_ST_DERIVED_OK_2_1, /* 3031 */

XML_SCHEMAP_COS_ST_DERIVED_OK_2_2, /* 3032 */

XML_SCHEMAP_S4S_ELEM_NOT_ALLOWED, /* 3033 */

XML_SCHEMAP_S4S_ELEM_MISSING, /* 3034 */

XML_SCHEMAP_S4S_ATTR_NOT_ALLOWED, /* 3035 */

XML_SCHEMAP_S4S_ATTR_MISSING, /* 3036 */

XML_SCHEMAP_S4S_ATTR_INVALID_VALUE, /* 3037 */

XML_SCHEMAP_SRC_ELEMENT_1, /* 3038 */

XML_SCHEMAP_SRC_ELEMENT_2_1, /* 3039 */

XML_SCHEMAP_SRC_ELEMENT_2_2, /* 3040 */

XML_SCHEMAP_SRC_ELEMENT_3, /* 3041 */

XML_SCHEMAP_P_PROPS_CORRECT_1, /* 3042 */

XML_SCHEMAP_P_PROPS_CORRECT_2_1, /* 3043 */

XML_SCHEMAP_P_PROPS_CORRECT_2_2, /* 3044 */

XML_SCHEMAP_E_PROPS_CORRECT_2, /* 3045 */

XML_SCHEMAP_E_PROPS_CORRECT_3, /* 3046 */

XML_SCHEMAP_E_PROPS_CORRECT_4, /* 3047 */

XML_SCHEMAP_E_PROPS_CORRECT_5, /* 3048 */

XML_SCHEMAP_E_PROPS_CORRECT_6, /* 3049 */

XML_SCHEMAP_SRC_INCLUDE, /* 3050 */

XML_SCHEMAP_SRC_ATTRIBUTE_1, /* 3051 */

XML_SCHEMAP_SRC_ATTRIBUTE_2, /* 3052 */

XML_SCHEMAP_SRC_ATTRIBUTE_3_1, /* 3053 */

XML_SCHEMAP_SRC_ATTRIBUTE_3_2, /* 3054 */

XML_SCHEMAP_SRC_ATTRIBUTE_4, /* 3055 */

XML_SCHEMAP_NO_XMLNS, /* 3056 */

XML_SCHEMAP_NO_XSI, /* 3057 */

XML_SCHEMAP_COS_VALID_DEFAULT_1, /* 3058 */

XML_SCHEMAP_COS_VALID_DEFAULT_2_1, /* 3059 */

XML_SCHEMAP_COS_VALID_DEFAULT_2_2_1, /* 3060 */

XML_SCHEMAP_COS_VALID_DEFAULT_2_2_2, /* 3061 */

XML_SCHEMAP_CVC_SIMPLE_TYPE, /* 3062 */

XML_SCHEMAP_COS_CT_EXTENDS_1_1, /* 3063 */

XML_SCHEMAP_SRC_IMPORT_1_1, /* 3064 */

XML_SCHEMAP_SRC_IMPORT_1_2, /* 3065 */

XML_SCHEMAP_SRC_IMPORT_2, /* 3066 */

XML_SCHEMAP_SRC_IMPORT_2_1, /* 3067 */

XML_SCHEMAP_SRC_IMPORT_2_2, /* 3068 */

XML_SCHEMAP_INTERNAL, /* 3069 non-W3C */

XML_SCHEMAP_NOT_DETERMINISTIC, /* 3070 non-W3C */

XML_SCHEMAP_SRC_ATTRIBUTE_GROUP_1, /* 3071 */

XML_SCHEMAP_SRC_ATTRIBUTE_GROUP_2, /* 3072 */

XML_SCHEMAP_SRC_ATTRIBUTE_GROUP_3, /* 3073 */

XML_SCHEMAP_MG_PROPS_CORRECT_1, /* 3074 */

XML_SCHEMAP_MG_PROPS_CORRECT_2, /* 3075 */

XML_SCHEMAP_SRC_CT_1, /* 3076 */

XML_SCHEMAP_DERIVATION_OK_RESTRICTION_2_1_3, /* 3077 */

XML_SCHEMAP_AU_PROPS_CORRECT_2, /* 3078 */

XML_SCHEMAP_A_PROPS_CORRECT_2, /* 3079 */

XML_SCHEMAP_C_PROPS_CORRECT, /* 3080 */

XML_SCHEMAP_SRC_REDEFINE, /* 3081 */

XML_SCHEMAP_SRC_IMPORT, /* 3082 */

XML_SCHEMAP_WARN_SKIP_SCHEMA, /* 3083 */

XML_SCHEMAP_WARN_UNLOCATED_SCHEMA, /* 3084 */

XML_SCHEMAP_WARN_ATTR_REDECL_PROH, /* 3085 */

XML_SCHEMAP_WARN_ATTR_POINTLESS_PROH, /* 3085 */

XML_SCHEMAP_AG_PROPS_CORRECT, /* 3086 */

XML_SCHEMAP_COS_CT_EXTENDS_1_2, /* 3087 */

XML_SCHEMAP_AU_PROPS_CORRECT, /* 3088 */

XML_SCHEMAP_A_PROPS_CORRECT_3, /* 3089 */

XML_SCHEMAP_COS_ALL_LIMITED, /* 3090 */

XML_SCHEMATRONV_ASSERT = 4000, /* 4000 */

XML_SCHEMATRONV_REPORT,

XML_MODULE_OPEN = 4900, /* 4900 */

XML_MODULE_CLOSE, /* 4901 */

XML_CHECK_FOUND_ELEMENT = 5000,

XML_CHECK_FOUND_ATTRIBUTE, /* 5001 */

XML_CHECK_FOUND_TEXT, /* 5002 */

XML_CHECK_FOUND_CDATA, /* 5003 */

XML_CHECK_FOUND_ENTITYREF, /* 5004 */

XML_CHECK_FOUND_ENTITY, /* 5005 */

XML_CHECK_FOUND_PI, /* 5006 */

XML_CHECK_FOUND_COMMENT, /* 5007 */

XML_CHECK_FOUND_DOCTYPE, /* 5008 */

XML_CHECK_FOUND_FRAGMENT, /* 5009 */

XML_CHECK_FOUND_NOTATION, /* 5010 */

XML_CHECK_UNKNOWN_NODE, /* 5011 */

XML_CHECK_ENTITY_TYPE, /* 5012 */

XML_CHECK_NO_PARENT, /* 5013 */

XML_CHECK_NO_DOC, /* 5014 */

XML_CHECK_NO_NAME, /* 5015 */

XML_CHECK_NO_ELEM, /* 5016 */

XML_CHECK_WRONG_DOC, /* 5017 */

XML_CHECK_NO_PREV, /* 5018 */

XML_CHECK_WRONG_PREV, /* 5019 */

XML_CHECK_NO_NEXT, /* 5020 */

XML_CHECK_WRONG_NEXT, /* 5021 */

XML_CHECK_NOT_DTD, /* 5022 */

XML_CHECK_NOT_ATTR, /* 5023 */

XML_CHECK_NOT_ATTR_DECL, /* 5024 */

XML_CHECK_NOT_ELEM_DECL, /* 5025 */

XML_CHECK_NOT_ENTITY_DECL, /* 5026 */

XML_CHECK_NOT_NS_DECL, /* 5027 */

XML_CHECK_NO_HREF, /* 5028 */

XML_CHECK_WRONG_PARENT,/* 5029 */

XML_CHECK_NS_SCOPE, /* 5030 */

XML_CHECK_NS_ANCESTOR, /* 5031 */

XML_CHECK_NOT_UTF8, /* 5032 */

XML_CHECK_NO_DICT, /* 5033 */

XML_CHECK_NOT_NCNAME, /* 5034 */

XML_CHECK_OUTSIDE_DICT, /* 5035 */

XML_CHECK_WRONG_NAME, /* 5036 */

XML_CHECK_NAME_NOT_NULL, /* 5037 */

XML_I18N_NO_NAME = 6000,

XML_I18N_NO_HANDLER, /* 6001 */

XML_I18N_EXCESS_HANDLER, /* 6002 */

XML_I18N_CONV_FAILED, /* 6003 */

XML_I18N_NO_OUTPUT /* 6004 */

Parent topic: SAX event structures


PLISAXA and PLISAXB event structure example

This shows an example of a SAX event structure for PLISAXA and PLISAXB.

saxtest: proc options( main );

    dcl
      1 eventhandler /* static  */

        ,2 e01 type event
               init( start_of_document )
        ,2 e02 type event
               init( version_information )
        ,2 e03 type event
               init( encoding_declaration )
        ,2 e04 type event
               init( standalone_declaration )
        ,2 e05 type event
               init( document_type_declaration )
        ,2 e06 type event_end_of_document
               init( end_of_document )
        ,2 e07 type event
               init( start_of_element )
        ,2 e08 type event
               init( attribute_name )
        ,2 e09 type event
               init( attribute_characters )
        ,2 e10 type event_predefined_ref
               init( attribute_predefined_reference )
        ,2 e11 type event_character_ref
               init( attribute_character_reference )
        ,2 e12 type event
               init( end_of_element )
        ,2 e13 type event
               init( start_of_cdata )
        ,2 e14 type event
               init( end_of_cdata )
        ,2 e15 type event
               init( content_characters )
        ,2 e16 type event_predefined_ref
               init( content_predefined_reference )
        ,2 e17 type event_character_ref
               init( content_character_reference )
        ,2 e18 type event_pi
               init( processing_instruction )
        ,2 e19 type event
               init( comment )
        ,2 e20 type event
               init( unknown_attribute_reference )
        ,2 e21 type event
               init( unknown_content_reference )
        ,2 e22 type event
               init( start_of_prefix_mapping )
        ,2 e23 type event
               init( end_of_prefix_mapping )
        ,2 e24 type event_exception
               init( exception )
        ;
Parent topic: SAX event structures


PLISAXC event structure example

This shows an example of a SAX event structure for PLISAXC.

This shows an example of a SAX event structure for PLISAXA and PLISAXB.

saxtest: proc options( main );

// eventHandler for PLISAXC
  dcl
    1 eventHandler_c

      ,2 e01 type event_without_data
              init( start_of_document )
      ,2 e02 type event
              init( version_information )
      ,2 e03 type event
              init( encoding_declaration )
      ,2 e04 type event
             init( standalone_declaration )
      ,2 e05 type event
             init( document_type_declaration )
      ,2 e06 type event_without_data
             init( end_of_document )
      ,2 e07 type event_with_namespace
             init( start_of_element )
      ,2 e08 type event_with_namespace
             init( attribute_name )
      ,2 e09 type event
             init( attribute_characters )
      ,2 e10 type event_with_namespace
             init( end_of_element )
      ,2 e11 type event_without_data
             init( start_of_cdata )
      ,2 e12 type event_without_data
             init( end_of_cdata )
      ,2 e13 type event_with_flag
             init( content_characters )
      ,2 e14 type event_pi
             init( processing_instruction )
      ,2 e15 type event
             init( comment )
      ,2 e16 type event_namespace_dcl
             init( namespace_declare )
      ,2 e17 type event_end_of_input
             init( end_of_input )
      ,2 e18 type event
             init( unresolved_reference )
      ,2 e19 type event_exception
             init( exception )
      ;
Parent topic: SAX event structures


Event differences

These events are part of the PLISAXA and PLISAXB event structure, but are not in PLISAXC:

  • attribute_predefined_reference
  • attribute_character_reference
  • content_predefined_reference
  • content_character_reference
  • unknown_attribute_reference
  • unknown_content_reference
  • start_of_prefix_mapping
  • end_of_prefix_mapping

These events are not part of the PLISAXA and PLISAXB event structure, but are in PLISAXC:

  • namespace_declare
  • unresolved_reference
  • end_of_input

These events are common to PLISAXA/PLISAXB and PLISAXC, but different parameters are passed to PLISAXA/PLISAXB than are passed to PLISAXC:

start_of_document
No parameters are passed.
start_of_element
With PLISAXC, namespace data is also passed.
end_of_element
With PLISAXC, namespace data is also passed.
attribute_name
With PLISAXC, namespace data is also passed.
content_characters
With PLISAXC, a flag byte is also passed.
exception
With PLISAXC, a return and reason code is passed instead of an error id.
start_of_cdata
No parameters are passed.
start_of_cdata
No parameters are passed.
Parent topic: SAX event structures


XML document coded character sets

The PLISAX built-in subroutines only work with XML documents in WIDECHAR encoded using Unicode UTF-16, or in CHARACTER encoded using one certain supported single-byte character sets. The parser uses up to three sources of information about the encoding of your XML document, and signals an exception XML event if it discovers any conflicts between these sources:

  • The parser determines the basic encoding of a document by inspecting its initial characters.
  • If the previous step succeeds, the parser then looks for any encoding declaration.
  • Finally, it refers to the codepage value on the applicable PLISAX built-in call.

If the XML document begins with an XML declaration that includes an encoding declaration specifying one of the supported code pages listed below, the parser honors the encoding declaration if it does not conflict with either the basic document encoding or the encoding information from the PLISAX built-in. If the XML document does not have an XML declaration at all, or if the XML declaration omits the encoding declaration, the parser uses the encoding information from the PLISAX built-in to process the document, as long as it does not conflict with the basic document encoding.

  • Supported EBCDIC and ASCII code pages
  • Specifying a code page
Parent topic: XML Parser Support in PL/I


Supported EBCDIC and ASCII code pages

EBCDIC

This table shows the supported EBCDIC code pages. In each row, the first number is the Euro Country Extended Code Page (ECECP), the second number is the Country Extended Code Page (CECP).

CCSID | Code Page Locale/Description
01208 | Unicode UTF-8 (PLISAXC only)
01047 | Latin 1 / Open Systems
01140, 00037 | USA, Canada, etc.
01141, 00273 | Austria, Germany
01142, 00277 | Denmark, Norway
01143, 00278 | Finland, Sweden
01144, 00280 | Italy
01145, 00284 | Spain, Latin America (Spanish)
01146, 00285 | UK
01147, 00297 | France
01148, 00500 | International
01149, 00871 | Iceland

ASCII (PLISAXA and PLISAXB only)

This table shows the supported ASCII code pages.

CCSID | Code Page Locale/Description
00813 | ISO 8859-7 Greek / Latin
00819 | ISO 8859-1 Latin 1 / Open Systems
00920 | ISO 8859-9 Latin 5 (ECMA-128, Turkey TS-5881)
Parent topic: XML document coded character sets


Specifying a code page

If your document does not include an encoding declaration in the XML declaration, or does not have an XML declaration at all, the parser uses the encoding information provided by the PLISAX built-in call in conjunction with the basic encoding of the document.

You can also specify the encoding information for the document in the XML declaration, with which most XML documents begin. An example of an XML declaration that includes an encoding declaration is:

<xml version="1.0" encoding="ibm-1140">

If your XML document includes an encoding declaration, ensure that it is consistent with the encoding information provided by the PLISAX built-in and with the basic encoding of the document. If there is any conflict between the encoding declaration, the encoding information provided by the PLISAX built-ins and the basic encoding of the document, the parser signals an exception XML event.

Specify the encoding declaration as follows:

Using a number

You can specify the CCSID number (with or without any number of leading zeroes), prefixed by any of the following (in any mixture of upper or lower case):

IBM_ | CP | CCSID_
IBM- | CP_ | CCSID-
 | CP- |

Using an alias

You can use any of the following supported aliases (in any mixture of lower and upper case):

Code Page | Aliases
037 | EBCDIC-CP-US, EBCDIC-CP-CA, EBCDIC-CP-WT, EBCDIC-CP-NL
500 | EBCDIC-CP-BE, EBCDIC-CP-CH
813 | ISO-8859-7, ISO_8859-7
819 | ISO-8859-1, ISO_8859-1
920 | ISO-8859-9, ISO_8859-9
1200 | UTF-16
Parent topic: XML document coded character sets


Exceptions

For most exceptions, the XML text contains the part of the document that was parsed up to and including the point where the exception was detected. For encoding conflict exceptions, which are signaled before parsing begins, the length of the XML text is either zero or the XML text contains just the encoding declaration value from the document.

The kinds of exceptions are:

  • Continuable exceptions - Allow you to continue parsing optionally. Continuable exceptions have exception codes in the range 1 through 99, 100,001 through 165,535, or 200,001 to 265,535. The exception event in the example above has an exception number of 1 and thus is continuable.
  • Fatal exceptions - Do not allow continuation. Fatal exceptions have exception codes greater than 99 (but less than 100,000).

Returning from the exception event function with a non-zero return code normally causes the parser to stop processing the document, and return control to the program that invoked the PLISAXA or PLISAXB built-in.

For continuable exceptions, returning from the exception event function with a zero return code tells the parser to continue processing the document, although further exceptions may occur.

A special case applies to exceptions with exception numbers in the ranges 100,001 through 165,535 and 200,001 through 265,535. These ranges of exception codes indicate that the document's CCSID (determined by examining the beginning of the document, including any encoding declaration) is not identical to the CCSID value provided (explicitly or implicitly) by the calling built-in (PLISAXA or PLISAXB ), even if both CCSIDs are for the same basic encoding, EBCDIC or ASCII. For these exceptions, the exception code passed to the exception event contains the document's CCSID, plus 100,000 for EBCDIC CCSIDs, or 200,000 for ASCII CCSIDs. For instance, if the exception code contains 101,140, the document's CCSID is 01140. The CCSID value provided by the PLISAXA or PLISAXB built-in is either set explicitly as the last argument on the call or implicitly when the last argument is omitted and the value of the CODEPAGE compiler option is used.

Depending on the value of the return code after returning from the exception event function for these CCSID conflict exceptions, the parser takes one of these actions:

  • If the return code is zero, the parser proceeds using the CCSID provided by the PLISAX built-in being used.
  • If the return code contains the document's CCSID (that is, the original exception code value minus 100,000 or 200,000), the parser proceeds using the document's CCSID. This is the only case where the parser continues after a non-zero value is returned from one of the parsing events.
  • Otherwise, the parser stops processing the document, and returns control to the PLISAXA or PLISAXB built-in, which raises the ERROR condition.
Parent topic: XML Parser Support in PL/I


CBL_GET_PROGRAM_INFO (PL/I)

Returns information for a named program, or a program in the current call stack.

For COBOL, the CBL_GET_PROGRAM_INFO uses the save area defined for a COBOL program. The COBOL run-time system loads both .int and .gnt, providing access to the relevant save area for these types of programs.

A native object code program, however, may be in a state where it has been loaded by the COBOL run-time system, but not yet called. Until called, there is no save area and as such CBL_GET_PROGRAM_INFO could not be used on a native object code program (shared object, dynamic link library or executable).

To resolve this, you can embed a predefined structure into the program's resulting objects based on the compiler (COBOL or PL/I). That structure should contain a known symbol so the run time can easily locate the structure during execution. If the native object code program is loaded, but not yet executed, or if the object is a PL/I object, then this symbol can be located and program information can be extracted from the embedded structure.

The compiler creates the following structure for object code programs:

struct
{
    unsigned int version;
    unsigned int flags;
    union
    {
        void * p_savarea;
        Unsigned int PLI_attributes;
    }x;
} _mFinfo_<NAME>;

/* PLI_attributes bit values        */
#define PLI_AMODE24           0x00000001
#define PLI_AMODE31           0x00000002
#define PLI_EBCDIC            0x00000004
#define RESERVED1             0x000000F8
#define LANGUAGE              0x00000700
#define LANGUAGE_SPECIFIC     0x01FFF800
#define PLI_LENDIAN           0x00000800
#define PLI_FUTURE            0x01FFF000
#define RESERVED2             0xFE000000

Where:

<NAME> | The name of the main entry point or program
version | The version of the structure (initially set to 1)
flags | 0 = COBOL program 1 = PL/I program
p_savarea | The pointer to the COBOL program's savarea.
PLI_attributes | The returned PL/I attributes

The _mFinfo_<NAME> symbol must be made visible so the run time can locate it when necessary. In the COBOL run time, CBL_GET_PROGRAM_INFO works as normal except when the named program is found but no save area exists. When this happens, if the _mFinfo_<NAME> symbol is found, the associated structure is deciphered depending on version and flags. For COBOL, a pointer to the program's save area (p_savarea) allows you to access and return all relevant information for the given program. For PL/I, the relevant program information is extracted and returned from the PLI_attributes data item.

For PL/I, CBL_GET_PROGRAM_INFO return the program's attributes as it does for a COBOL program. The PL/I program returned bit meanings are:

Bit 0
0 | Program not compiled using the AMODE"24" Compiler directive.
1 | Program compiled using the AMODE"24" Compiler directive .
Bit 1
0 | Program not compiled using the AMODE"31" Compiler directive.
1 | Program compiled using the AMODE"31" Compiler directive .
Bit 2
0 | Program compiled using the CHARSET(ASCII) Compiler directive.
1 | Program compiled using the CHARSET(EBCDIC) Compiler directive.
Bit 3-5
Reserved for future use.
Bit 6
0 | Program not compiled using the DATA(24) Compiler directive.
1 | Program compiled using the DATA(24) Compiler directive.
Bit 7
0 | Program not compiled using the DATA-CONTEXT Compiler directive.
1 | Program compiled using the DATA-CONTEXT Compiler directive.
Bit 8-10
0 | Language is unknown.
1 | PL/I.
2 through 7 | Reserved.
Bit 11
Language-specific flag.
0 | PL/I-specific (little-endian).
1 | PL/I-specific (big-endian).
Bit 12-24
Language-specific flags.
Bit 25
0 | Program is not an application controller.
1 | Program is an application controller.
Bit 26
Reserved for future use.
Bit 27
0 | Program is not a .390 assembler program.
1 | Program is a .390 assembler program.
Bit 28-30
Reserved for future use.
Bit 31
Set for PL/I programs.
0 | COBOL.
1 | Non-COBOL.

The CBL_GET_PROGRAM_INFO routine modifies bits 8-10 to set the PL/I language and set bit 31 to indicate non-COBOL. The rest of the data item returns as is. Bits 3-7, and 25-30 are reserved to not conflict with existing programs that do not correctly check bit 31.

Getting program information on the current program and then iterating up the stack to retrieve caller program information is not supported for PL/I programs in the stack.

Parent topic: Language Concepts


Open PL/I SQL Options

  • DB2 SQL Support
  • HCO for SQL Server Compiler Directive Options for PL/I
    Using HCO for SQL compiler directive options with PL/I.
  • OpenESQL Support for Oracle PL/I Applications (Technology Preview)
    OpenESQL provides a run-time system that uses Oracle's native OCI API. You can use the OCI API to run Open PL/I applications.
  • OpenESQL Compiler Options for Open PL/I
Parent topic: Open PL/I User's Guide


DB2 SQL Support

Open PL/I enables you to develop PL/I applications that make use of databases maintained by IBM DB2 LUW. Open PL/I's DB2 SQL preprocessor allows you to compile and link PL/I applications containing embedded DB2 SQL statements to access these databases. This document gives the special instructions needed to code, compile, and link such Open PL/I applications.

Support for DB2 SQL is included in the standard Open PL/I product set, but you must obtain from Micro Focus a DB2 SQL license before it can be used. Also, before you can take advantage of EXEC SQL support, you must have installed and started IBM's DB2 product on your system.

You can code DB2 EXEC SQL statements in Open PL/I applications using the language defined in the IBM document DATABASE 2 Client/Server SOL Reference. Specific requirements for your SQL code are described in the sections that follow.

  • PL/I DB2 Stored Procedures
  • HCO for DB2 LUW Preprocessor
    Describes the HCO for DB2 LUW preprocessor.
  • DB2 SQL Preprocessor Options (deprecated)
  • Coding DB2 SQL Statements in Open PL/I Applications
  • Sample Programs
  • Equivalent HCO for DB2 LUW Preprocessor Options
Parent topic: Open PL/I SQL Options


PL/I DB2 Stored Procedures

DB2 LUW allows embedded SQL calls to be executed as stored procedures. Stored procedures are routines executed directly by a DB2 LUW Server instance, rather than indirectly via a call to a routine from within a client application. The benefits of using DB2 stored procedures over SQL calls include enhanced modularity, security, and performance.

Stored procedures are stored at a local or remote DB2 LUW Server. Local DB2 LUW Server applications or remote DRDA applications can use the SQL statement CALL to invoke a stored procedure.

Note:
  • If you are running your stored procedure on DB2 for OS/390, through the DB2 Connect product, see your IBM DB2 documentation for other steps necessary to run the stored procedure.
  • For complete information on writing stored procedures and setting options for DB2 Database for Linux, UNIX, and Windows (LUW), see IBM's documentation on Developing User-defined Routines (SQL and External) and also their SQL reference material.
  • Working with Stored Procedures
  • Writing and Preparing Stored Procedures
  • Writing and Preparing Applications to Use Stored Procedures
  • Defining Stored Procedures under DB2 LUW
  • Compiling and linking stored procedures under DB2 LUW
  • Testing DB2 LUW Stored Procedures
  • Creating a CTF Trace for DB2 LUW Stored Procedures
  • Debugging PL/I DB2 LUW Stored Procedures
Parent topic: DB2 SQL Support


Working with Stored Procedures

Important: Any machine on which a PL/I stored procedure is executed must have a Micro Focus Enterprise 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:
    On Windows, do one of the following:
    1. Add your installation's executable (bin) directory to the PATH statement.
    2. Copy the following DLLs to the directory from which you execute the stored procedure. You need to do this for DB2 to be able to execute a PL/I stored procedure:
      • cblrtsm.dll
      • mffh.dll
      • mfhcolib.dll
      • mfsqlsmf.dll
      • cblctf.dll
      • dbghelp.dll
      • libxml2.dll
      • mfplimd.dll
      • mplicppm.dll
      • mpliemsg.lng
      • plidump.dll
      • xerces-c_2_8.dll

    In addition, see the IBM documentation for Building Micro Focus COBOL Routines on Windows.

    On UNIX, see the IBM documentation for Building Micro Focus COBOL Routines on UNIX.

  2. Code and prepare a stored procedure. See Writing and Preparing Stored Procedures for instructions.
  3. Code and prepare an application that calls the stored procedure. An SQL statement, CALL, in that application must use the same parameter list and linkage convention as the stored procedure that it invokes. See Writing and Preparing Applications to Use Stored Procedures for instructions.
  4. Define your stored procedure to the DB2 LUW Server by issuing a CREATE PROCEDURE command, which will place a row in the appropriate system table(s). See Defining Stored Procedures under DB2 LUW for additional details.
  5. Compile and link your stored procedure. See Compiling and Linking Stored Procedures under DB2 LUW for additional details.
  6. Debug and test your stored procedure. See Debugging Stored Procedures under DB2 LUW for additional details.
Parent topic: PL/I DB2 Stored Procedures
Related information
Compiling and linking stored procedures under DB2 LUW
Debugging PL/I DB2 LUW Stored Procedures
Defining Stored Procedures under DB2 LUW
Writing and Preparing Applications to Use Stored Procedures
Writing and Preparing Stored Procedures


Writing and Preparing Stored Procedures

A stored procedure is an application program that runs in the DB2 LUW Server's address space. It can contain most statements that an application program normally contains. It can consist of more than one program. Your stored procedure can call other programs as well as nested stored procedures but there are restrictions.

The application program that invokes the stored procedure can be in any language that supports SQL statements. You can write a stored procedure using many languages such as C, JAVA, COBOL or now SQL Procedure Language which is consistent with the Persistent Stored Module definition of the ANSI SQL99 standard.

The store procedure can be written in one language, for example JAVA, with the client written in another language, for example COBOL. When the languages differ, DB2 transparently passes the values between the client and the stored procedure so each program gets the values in the expected format defined by the CREATE PROCEDURE statement.

  • Preparing Stored Procedures
  • How an Application Works With a Stored Procedure
Parent topic: PL/I DB2 Stored Procedures


Preparing Stored Procedures

The following are high level tasks that must be completed before a stored procedure can be run on a DB2 LUW Server:

  1. Prepare the application according to your embedded SQL documentation for creating stored procedure.
  2. Define the stored procedure to the DB2 LUW Server. See Defining Stored Procedures under DB2 LUW.
  3. Place the stored procedure DLL (Windows) or module (UNIX) on the DB2 LUW Server machine in a location specified in the CREATE PROCEDURE statement. If not specified, the default location is the function subdirectory under sqllib in the home directory of your DB2 LUW instance.
Note: IBM provides specific documentation on preparing stored procedures. Look in your IBM documentation for information on creating external routines and developing user-defined routines.
Parent topic: Writing and Preparing Stored Procedures


How an Application Works With a Stored Procedure

A typical stored procedure contains two or more SQL statements, and some manipulative or logical processing. In this example, your application, CALLSTPR, runs on a workstation client and calls a stored procedure, GETPRML. The following process occurs:

  1. The workstation application establishes a connection to the DB2 LUW Server.
  2. The SQL statement CALL tells the DB2 LUW Server that the application is going to run the stored procedure, GETPRML. The calling application provides the necessary parameters.
  3. The DB2 LUW Server searches the system tables for rows associated with stored procedure GETPRML.
  4. The DB2 LUW Server passes information about the request to the stored procedure.
  5. The stored procedure executes SQL statements.
  6. The stored procedure assigns values to the output parameters and then exits.
  7. Control returns to the calling application, which receives the output parameters.

The application can call more stored procedures or it can execute more SQL statements. The application designer determines whether to COMMIT work in the stored procedure that runs on the server, or in the client as a single transaction.

Parent topic: Writing and Preparing Stored Procedures


Writing and Preparing Applications to Use Stored Procedures

To invoke a stored procedure and to pass a list of parameters to the procedure, use the SQL statement CALL. Your application program can call several stored procedures.

After connecting to its server, an application can mix calls to stored procedures with SQL statements sent to the server.

  • Executing the SQL Statement CALL
  • Parameter Conventions
  • Using Indicator Variables to Speed Processing
  • Declaring Data Types for Passed Parameters
  • Limitations
Parent topic: PL/I DB2 Stored Procedures


Executing the SQL Statement CALL

Use the CALL statement to execute each series of SQL statements in your application.

Example 1

To call the stored procedure described in the topic How an Application Works with a Stored Procedure, your application might use this statement:

EXEC SQL
 CALL GETPRML(:V1, :V2);

If you use host variables in the CALL statement, you must declare them before using them.

Example 2

The example above is based on the assumption that none of the input parameters can have null values. To allow null values, code a statement like this:

EXEC SQL
 CALL GETPRML (:V1 :IV1, :V2 :IV2)

where :IV1 and :IV2 are indicator variables for the parameters.

Example 3

To use a host variable for the name of the stored procedure, code a statement like this:

EXEC SQL
 CALL :PROCNAME (:V1, :V2);

where :PROCNAME is the name of the stored procedure.

Parent topic: Writing and Preparing Applications to Use Stored Procedures


Parameter Conventions

See the IBM DB2 documentation for external routine parameter styles.

Note: Because DB2 LUW passes information to and from the stored procedure, specify NATIVE when passing any numeric parameters. For example:
PROC(EMPNO, SQLCD)

   DECLARE EMPNO CHAR(6),
           SQLCD FIXED BIN(31) NATIVE,
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Using Indicator Variables to Speed Processing

If any of your output parameters require a lot of storage, do not pass the entire storage areas to your stored procedure, but declare an indicator variable for every large output parameter in your SQL statement CALL. Indicator variables are used in the calling program to pass only a two-byte area to the stored procedure and to receive the entire area from the stored procedure.

Note: If you are using the GENERAL WITH NULLS linkage convention, you must declare indicator variables for all of your parameters, so you do not need to declare another indicator variable for the large output parameters.

Assign a negative value to each indicator value associated with a large output variable. Then include the indicator variables in the CALL statement. This technique can be used whether the stored procedure linkage is GENERAL or GENERAL WITH NULLS.

For example, suppose that a stored procedure, STPROC2 defined with the GENERAL linkage convention takes one integer input parameter and one character output parameter of length 5000. It is wasteful to pass the 5000 byte storage area to the stored procedure. Instead, a PL/I program containing these statements passes only two bytes to the stored procedure for the output variable and receives all 5000 bytes from the stored procedure:

INNUM  FIXED BIN(31);
OUTCHAR CHAR(5000)
IND  FIXED BIN(15);
.
.
.
IND = -1;
EXEC SQL CALL STPROC2(:INNUM, :OUTCHAR :IND);
Parent topic: Writing and Preparing Applications to Use Stored Procedures


Declaring Data Types for Passed Parameters

A stored procedure must declare each parameter passed to it. In addition, the DATA TYPE declared in the declaration must be valid for the data source being used and must use a compatible host variable data type when calling the stored procedure. See SQL Data Types for more information.

For example:

CREATE PROCEDURE GETPRML
 (IN  PROCNM CHAR(18)
  ,IN SCHEMA CHAR (8)
  ,INOUT OUTCODE INTEGER
  ,INOUT PARMLIST CHAR (26)
  )
   LANGUAGE COBOL
   DETERMINISTIC
   READS SQL DATA
   NO DBINFO
   FENCED
   NOT THREADSAFE
   EXTERNAL NAME "GETPRML!GETPRML"
   PARAMETER STYLE GENERAL
   PROGRAM TYPE SUB
   RESULT SETS 0;
Note: Specify LANGUAGE COBOL since DB2 LUW does not directly support PL/I as an option. Also, the EXTERNAL name definition should match the case of the PL/I routine.

Define the stored procedure GETPRML as shown to match the definitions in the CREATE PROCEDURE statement:

GETPRML:
  PROC(PROCNM, SCHEMA, OUTCODE, PARMLST)
  external('GETPRML');

  DECLARE PROCNM CHAR(18),               /* INPUT parm -- PROCEDURE name */
          SCHEMA CHAR(8),                /* INPUT parm -- User's SCHEMA  */
          OUTCODE FIXED BIN(31) native, /* INOUT -- SQLCODE from        */
          PARMLST CHAR(26);              /* INOUT -- CURRENT TIMESTAMP   */

  EXEC SQL INCLUDE SQLCA;

  DECLARE TIMESTAMP CHAR(26);

  /************************************************************/
  /* Execute SELECT from SYSIBM.SYSDUMMY1 if TEST passed      */
  /************************************************************/

  if PROCNM = ‘TEST’ then
    do;
      exec sql
        SELECT CURRENT TIMESTAMP INTO :TIMESTAMP
          FROM SYSIBM.SYSDUMMY1;
    end;
  else
    do;
      TIMESTAMP = ‘PASS’;
      SQLCODE = -12;
    end;

  PARMLST = TIMESTAMP;
  OUT_CODE = SQLCODE;         /* return SQLCODE to caller */
  RETURN;
END GETPRML;
Parent topic: Writing and Preparing Applications to Use Stored Procedures


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:

Windows:

C:> db2 -td; -vf creproc.sql

UNIX:

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 (UNIX only) 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: PL/I DB2 Stored Procedures


Compiling and linking stored procedures under DB2 LUW

Compiling and linking a PL/I stored procedure using DB2 LUW is a bit different than compiling and linking most PL/I applications. Use this procedure to compile and link DB2 stored procedures under DB2 LUW.

  1. Use mfplx to compile the program you want to use as a stored procedure with the DB2 SQL Option just like any DB2 LUW program. In this case though, you just want to create an OBJ file. To do this, specify the -c compiler option with mfplx.
    If your program contains stored procedure CALL statements, you must specify the CALL_RESOLUTION DB2 SQL option to prevent SQL error SQL0204 from occurring. For example:
    mfplx -sql db2 -optsql DB=SAMPLE getprml.pli -nolaxdcl –ppsql -c
    Note: Compile stored procedures using the -noaxdcl compiler option to prevent undeclared variables. Undeclared variables can cause a range of problems with stored procedures.

  2. Windows:

    To link the program as a Dynamic Link Library (.dll), you use CBLLINK rather than the normal PL/I link command.

    To link a PL/I DB2 stored procedure, you must link extra modules so that DB2 LUW can load the PL/I run time and load the PL/I routine properly.

    If the stored procedure is not defined with an OPTION of MAIN, add the systemsql.obj and setupdeffiles.obj object modules, as well as the mfplimd.lib and the 32-bit db2api.lib library files to the link command. For example:

    cbllink /d /V /K GETPRML.obj db2api.lib mfplimd.lib systemsql.obj setupdeffiles.obj

    If the stored procedure is not defined with an OPTION of MAIN, link these additional modules in the link command:

    • lpimainstub.obj
    • lpimain.obj
    • mfexttbl.lib

    For example:

    cbllink /d /V /K GETPRML.obj db2api.lib mfplimd.lib mfexttbl.lib systemsql.obj setupdeffiles.obj lpimainstub.obj lpimain.obj

    UNIX:

    To link the stored procedure, you must build the module using cob, ensuring that the resultant module has no file extension.

    On AIX platforms, you should use the following command to build the stored procedure as an executable :

    cob -x GETPRML.o -e GETPRML -L$COBDIR/lib -lmfpliz -lplidump

    On other UNIX platforms, you should use the following command format to build the stored procedure as a self-contained Callable Shared Object :

    cob -y GETPRML.o -o GETPRML -e GETPRML $COBDIR/lib/32/dllmain_cob.o -L$COBDIR/lib -lmfpliz -lplidump

  3. Copy the stored procedure object that is produced to the function directory under your DB2 instance.

    Note: By default, after calling a stored procedure, DB2 LUW does not unload it called until DB2 LUW is stopped. To avoid issues copying the .dll, you can do one of the following if you are not in a production environment.

    • Execute db2stop, copy the DLL, then execute db2start from a DB2 administrative command prompt.

    • Execute the following command from a DB2 command prompt:

    db2 update dbm cfg using KEEPFENCED NO

    Executing this command in a production environment has a significant performance impact, so it should not be used. Refer to your IBM documentation for more information on this command.

Parent topic: PL/I DB2 Stored Procedures


Testing DB2 LUW Stored Procedures

For testing DB2 LUW stored procedures in PL/I, you can use options other than coding a test client that require no coding.

  • If you have IBM's Data Studio product installed, you can use that to enter parameter information and execute the stored procedure.
  • Use a DB2 command prompt by first connecting to database and then calling the stored be entering CALL <stored procedure name> (parm1, parm2…..)

If the parameter is OUTPUT only, specify a question mark (?).

For example, to test the stored procedure defined earlier in this section, enter:

db2 connect to Sample
db2 call GETPRML ('TEST', 'TEST', 0, 'TEST')
Parent topic: PL/I DB2 Stored Procedures


Creating a CTF Trace for DB2 LUW Stored Procedures

Use this procedure to get a CTF trace for a PL/I DB2 stored procedure.

  1. Create a CTF configuration file with appropriate commands. For example:

    Windows:

    ## MFTRACE configuration file
mftrace.emitter.textfile#Format = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
mftrace.dest=textfile
mftrace.emitter.binfile#location=c:\ctflogs
mftrace.emitter.textfile#location=c:\ctflogs
#  CTF Configuration Starting point for Open PLI Problem Determination
#  (Maximum amount of Open PL/I CTF tracing  )#
mftrace.emitter.es#level = 9999
# Maximum file size in "k" bytes
mftrace.emitter.textfile#MaxFilesize = 26000
# Maximum number of log files to keep.
mftrace.emitter.textfile#MaxGeneration = 6
################################################
# PL/I RTS Tracing
################################################
mftrace.level.mf.rts                    = info
mftrace.comp.mf.rts#api                 = true
mftrace.comp.mf.rts#syspgm              = true
mftrace.comp.mf.rts#pgm                 = true
mftrace.level.mf.rts.pli                = debug
mftrace.comp.mf.rts.pli#all             = true
mftrace.level.mf.pli.macropp            = info
mftrace.comp.mf.pli.macropp#compsrc     = true

    UNIX:

    ## MFTRACE configuration file
mftrace.emitter.textfile#Format = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
mftrace.dest=textfile
mftrace.emitter.binfile#location=/tmp/ctflogs
mftrace.emitter.textfile#location=/tmp/ctflogs
#  CTF Configuration Starting point for Open PLI Problem Determination
#  (Maximum amount of Open PL/I CTF tracing  )#
mftrace.emitter.es#level = 9999
# Maximum file size in "k" bytes
mftrace.emitter.textfile#MaxFilesize = 26000
# Maximum number of log files to keep.
mftrace.emitter.textfile#MaxGeneration = 6
################################################
# PL/I RTS Tracing
################################################
mftrace.level.mf.rts                    = info
mftrace.comp.mf.rts#api                 = true
mftrace.comp.mf.rts#syspgm              = true
mftrace.comp.mf.rts#pgm                 = true
mftrace.level.mf.rts.pli                = debug
mftrace.comp.mf.rts.pli#all             = true
mftrace.level.mf.pli.macropp            = info
mftrace.comp.mf.pli.macropp#compsrc     = true
    See the help topic "Configuration File for CTF" for more information on creating a CTF configuration file.
  2. Open a DB2 administrative command prompt and stop DB2 LUW by issuing one of these commands:
    db2stop
    or
    db2stop FORCE
  3. Enable CTF by setting the MFTRACE_CONFIG environment variable to the configuration file you just created. For example:

    Windows:

    SET MFTRACE_CONFIG=C:\CTFLOGS\CHKCTF.CFG

    UNIX:

    MFTRACE_CONFIG=/tmp/CHKCTF.CFG
export MFTRACE_CONFIG
  4. Restart DB2 LUW by executing this command in a DB2 administrative command prompt:
    db2start
  5. Run program that calls the PL/I DB2 stored procedure.

    A CTF trace file generates, and the trace filename starts with the characters db2fmp.

Parent topic: PL/I DB2 Stored Procedures
Related information
Configuration File for CTF


Debugging PL/I DB2 LUW Stored Procedures

Restriction: This topic applies to Windows environments (local development) only.

It is possible to debug PL/I DB2 LUW Stored Procedures but care should be used when doing this. It is not recommended that production DB2 LUW servers be used because of the impact on processing and potential security issues. Using a VM image to debug the stored procedure is one option or using a single user version of the software like DB2 Express-C on a development workstation is another option.

Do the following before attempting to debug stored procedures:

  • When you install the DB2 LUW software, do not install the software using local system account as the ID to start all DB2 processes. Use the default setting of DB2ADMIN. Using local system account can cause the CodeWatch debugger to not attach the db2fmp process correctly.
  • The external name for the stored procedure definition needs to be in upper case so the definition would look something like this:
    CREATE PROCEDURE GETPRML
 (IN PROCNM CHAR(18)
 ,IN SCHEMA CHAR(8)
 ,INOUT OUTCODE INTEGER
 ,INOUT PARMLST CHAR(26)
 )
  LANGUAGE COBOL
  DETERMINISTIC
  READS SQL DATA
  NO DBINFO
  FENCED
  NOT THREADSAFE
  EXTERNAL NAME "GETPRML!GETPRML"
  PARAMETER STYLE GENERAL
  PROGRAM TYPE SUB
  RESULT SETS 0;
  • You should not use the EXTERNAL parameter in the PROC statement of the PL/I program. If you normally do, comment that code out like this:
    PROC(PROCNM, SCHEMA, OUTCODE, PARMLST); /* EXTERNAL('getprml'); */
  • Build and link the stored procedure for debugging. The commands would look like this:
    mfplx -sql db2 -optsql db=sample -deb -coffdebug -defext getprml.pli -c –ppsql
    SET LINK=-DEBUG
    cbllink /d /V /K getprml.obj db2api.lib mfplimd.lib systemsql.obj setupdeffiles.obj
  • Copy the DLL, STB, and PDB files to the \sqllib\function directory. STB files are created when setting the environment variable LINK=-DEBUG
  • Execute the stored procedure so that it gets loaded - for example using the DB2 command to call it.
  • Open an Enterprise Developer command prompt (32-bit) as ADMINISTRATOR
  • Set the CODEWATCH_SRCPATH and CODEWATCH_STBPATH environment variables to the \sqllib\function directory. For example:
    set CODEWATCH_SRCPATH=C:\Program Files\IBM\SQLLIB\FUNCTION
    set CODEWATCH_STBPATH=C:\Program Files\IBM\SQLLIB\FUNCTION
  • Find the PID for the DB2 LUW process that loaded the stored procedure. Look for db2fmp.exe.

    It is easier to find if you have 64-bit version of DB2 LUW installed since it is a 32-bit version.

    One tool that you could use is PSLIST which is available from www.sysinternals.com under PsTools download. The command to execute is:

    PSLIST DB2FMP

    The results would look something like this using 64-bit DB2 LUW:

    Name         Pid Pri Thd  Hnd   Priv       CPU Time    Elapsed Time
db2fmp64    2240   8   9  211  16660    0:00:00.655     0:00:50.512
db2fmp64    2240   8   9  211  16660    0:00:00.655     0:00:50.512
db2fmp64    2056   8   4  143  10888    0:00:00.046     0:00:15.241
db2fmp      2528   8   3  117  12172    0:00:00.140     0:00:15.163

    If more than one PID for db2fmp is listed, try them one at a time to determine which one is the stored procedure you want to debug. You could also use CTF trace to determine which PID is being used.

  • In the Enterprise Developer 32-bit command prompt, enter java -jar <installation path>/cw_java.jar -pid nnnn where nnnn is the PID number. For example, using the last PID displayed above, the command would be:
    java –jar <installation path>/cw_java.jar –pid 2528

    The CodeWatch window appears.

  • Select Shared Library from the Actions menu, enter the .dll name of the stored procedure you want to debug and click OK. For example:

  • Load the source symbols by typing the proc name of the stored procedure in the Env dropdown. For example:

  • Set a break point on the line where you want to stop the debugger. To do this, double click the line number. For example, double clicking line 15 will stop execution on line 15.

  • In the CodeWatch window, click Continue [image] to wait until the stored procedure is called again.
  • Call the stored procedure again in another process.
  • Switch back to the CodeWatch debugger window. If attached to the correct process, the debugger stops at the line set in the breakpoint.

    You can now perform debugging tasks including evaluating variables and stepping through code. When you return, the results of the stored procedure call are available to the calling process.

Parent topic: PL/I DB2 Stored Procedures


HCO for DB2 LUW Preprocessor

Micro Focus provides the same DB2 LUW preprocessor used by COBOL applications based on the HCO for DB2 LUW preprocessor. This preprocessor gives you access to all DB2 LUW preprocessor options, most options are not case sensitive, and it supports similar command line syntax used for creating ODBC, OCI or HCOSS application.

Note: Micro Focus also provides the original DB2 SQL preprocessor for backward compatibility which is now deprecated.
Parent topic: DB2 SQL Support
Related information
HCO for DB2 LUW Preprocessor Options


DB2 SQL Preprocessor Options (deprecated)

The following DB2 SQL preprocessor options are supported by the Open PL/I driver program, mfplx:

-bind or -nobind
Determines whether or not a bind file is created. The bind file's name is specified by the -bindname option, if that option is used. Otherwise, the name defaults to the name of the input source file with the suffix .bnd.
-bindname b
Specifies the bind file name, b, if one is created.
-block t
Specifies the type of record blocking, t, to be used and how ambiguous cursors are to be treated. The valid types are:
unambig | Blocking occurs for read-only cursors, those that are not specified as FOR UPDATE OF, have no static DELETE WHERE CURRENT OF statements, and have no dynamic statements. Ambiguous cursors can be updated.
all | Blocking occurs for read-only cursors, those that are not specified as FOR UPDATE OF, and for which no static DELETE WHERE CURRENT OF statements are executed. Ambiguous and dynamic cursors are treated as read-only.
no | No blocking is done on any cursors in the package. Ambiguous cursors can be updated.
-datetime d
Determines the date and time format used when date and time fields are assigned to string representations in host variables. The possible formats are:
def | Use the date/time format associated with the country code of the database. This is also the default if -datetime is not specified.
usa IBM standard for United States form:

mm/ddlyyyy hh:mm xM (AM or PM).

eur IBM standard for European form:

dd.mm.yyyy hh.mm.ss.

iso International Standards Organization form:

yyyy–mm–dd hh.mm.ss.

jis Japanese Industrial Standards form:

yyyy–mm–dd hh:mm:ss.

loc | Local form, not necessarily equal to def.
-db2
Specifies that the DB2 version of SQL is to be used.
-dbname d
Specifies the original or alias name of a database. This option directs the preprocessor to process SQL statements against the specified database, d. If you omit this option, the preprocessor uses the default database. The default database is specified by the environment variable DB2DBDFT.
-E
Allows you to run the DB2 SQL preprocessor without running the Open PL/I compiler. The preprocessor output is saved using the file specified by the -ppdb2 option, if that option is used. Otherwise, the name defaults to the name of the input source file with the suffix .pp2. This option is useful for a faster syntax and semantic checking of your SQL statements.
-isolation I
Specifies the isolation level at which your program runs. The values of Iare:
cs | Cursor stability
rr | Repeatable read
ur | Uncommitted read
-optimize or -nooptimize
If you specify -optimize, SQLDA initialization is optimized for SQL statements that use host variables. Do not specify this option when using AUTOMATIC host variables or in other situations when the address of a host variable might change during execution of the program. -nooptimize is the default.
-plan or -noplan
Determines whether or not an access plan is created.
-ppdb2 [f]
Specifies the DB2 SQL preprocessor output file. This is useful when using the -E option.
-sqltwop
It is good programming practice to declare all SQL host variables before using them in SQL statements. However, if you are not able to do this, -sqltwop provides support for declarations of host variables subsequent to their use. This is done by making a preliminary pass over the source to detect all declarations, followed by a second pass to process the remaining SQL statements. In general, you should not need to use this option and incur the extra overhead it entails.
Parent topic: DB2 SQL Support


Coding DB2 SQL Statements in Open PL/I Applications

Specific requirements for your embedded SQL code are described in the sections that follow.

  • Defining the DB2 SQL Communications Area
  • Defining SQL Descriptor Areas
  • Embedding SQL Statements
  • Using Host Variables
  • Determining Equivalent SQL and PL/I Data Types
  • Determining Compatibility of SQL and PL/I Data Types
  • Using Host Structures
  • Using Indicator Variables
  • CONNECT TO Statement
  • COMPOUND Statement
  • Handling SQL Error Return Codes
Parent topic: DB2 SQL Support


Defining the DB2 SQL Communications Area

An Open PL/I program that contains SQL statements must include an SQL communications area (SQLCA). As shown in the example below, SQLCA includes an SQLCODE variable and an SQLSTATE variable.

The SQLCODE value is set by the Database Manager after each SQL statement is executed. An application can check the SQLCODE value to determine whether the last SQL statement was successful.

The SQLSTATE variable can be used as an alternative to the SQLCODE variable when analyzing the result of an SQL statement. Like the SQLCODE variable, the SQLSTATE variable is set by the Database Manager after each SQL statement is executed.

The SQLCA should be included by using the SQL INCLUDE statement:

exec sql include sqlca;

The SQLCA must not be defined within an SQL declare section. The scope of the SQLCODE and SQLSTATE declarations must include the scope of all SQL statements in the program.

/*--------------------------------------------------------------- */
/* DB2 SQL Communications Area                                    */
/* This should be included by the                                 */
/* 'EXEC SQL INCLUDE SQLCA;' statement.                           */
/* Do not place this within a SQL declare statement.              */
/*--------------------------------------------------------------- */
declare 1 sqlca,
  2 sqlcaid char(8),                 /* Eyecatcher = 'SQLA '      */
  2 sqlcabc fixed bin(31),           /* SQLCA size in bytes = 136 */
       2 sqlcode fixed bin(31),      /* SQL return code           */
       2 sqlerrm char(70) varying,   /* Error message tokens      */
       2 sqlerrp char (8),           /* Diagnostic information    */
       2 sqlerrd(1:6) fixed bin(31), /* Diagnostic information    */
       2 sqlwarn,                    /* Warning flags             */
         3 sqlwarn0 char(1),
         3 sqlwarnl char(1),
         3 sqlwarn2 char(1),
         3 sqlwarn3 char(1),
         3 sqlwarn5 char(1),
         3 sqlwarn6 char(1),
         3 sqlwarn7 char(1),
       2 sqltext,
         3 sqlwarn8 char(1),
         3 sqlwarn9 char(1),
         3 sqlwarna char(1),
         3 sqlstate char(5); /* State corresponding to SQLCODE */

/*    End of SQL Communications Area declaration */
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Defining SQL Descriptor Areas

The following statements require an SQLDA:

  • PREPARE statement-name INTO descriptor-name FROM host-variable
  • EXECUTE ... USING DESCRIPTOR descriptor-name
  • FETCH ... USING DESCRIPTOR descnptor-name
  • OPEN ... USING DESCRIPTOR descriptor-name
  • DESCRIBE statement-name INTO descriptor-name

Unlike the SQLCA, there can be more than one SQLDA in a program, and an SQLDA can have any valid name. An SQLDA should be included by using the SQL INCLUDE statement:

exec sql include sqlda;

The SQLDA must not be defined within an SQL declare section.

The Open PL/I SQLDA template includes %REPLACE statements for the SQL data types.

/*-------------------------------------------------------------------------------- */
/* DB2 SQL Descriptor Template                                                         */
/* This should be included by the 'EXEC SQL INCLUDE SQLDA;' statement.                 */
/* Do not place this within an SQL declare statement.                                  */
/*------------------------------------------------------------------------------------ */
declare 1 sqlda based(sqldaptr),                                                       */
   2 sqldaid        char(8),                     /* Eye catcher 'SQLDA   '             */
   2 sqldabc fixed bin(31),                      /* SQLDA size in bytes 16 + 44 * SQLN */
   2 sqln           fixed bin(15),               /* Number of SQLVAR elements          */
   2 sqld           fixed bin(15),               /* Number of used SQLVAR elements     */
   2 sqlvar(1:sqlsize refer(sqln)),              /* Variable descriptor                */
     3 sqltype      fixed bin(15),               /* Variable data type                 */
     3 sqllen       fixed bin(15),               /* Variable length                    */
     3 sqldata      pointer,                     /* Pointer to variable data value     */
     3 sqlind       pointer,                     /* Pointer to null indicator          */
     3 sqlname      char(30) var;                /* Variable name                      */
declare sqlsize fixed bin(15);                   /* Number of sqlvars (sqln)           */
declare sqldaptr pointer;
/* End of SQL Descriptor Template declaration */

/* replaces for SQL type codes                                                         */
/* replaces of the SQL_TYP_Nxxnnn means with Null indicator                            */
%replace SQL_TYP_DATE      by 384; /* DATE */
%replace SQL_TYP_NDATE     by 385;
%replace SQL_TYP_TIME      by 388; /* TIME */
%replace SQL_TYP_NTIME     by 389;
%replace SQL_TYP_STAMP     by 392; /* TIMESTAMP */
%replace SQL_TYP_NSTAMP    by 393;
%replace SQL_TYP_VARCHAR   by 448; /* VARCHAR(I) varying length string I<=4000*/41)
%replace SQL_TYP_NVARCHAR  by 449;
%replace SQL_TYP_CHAR      by 452; /* CHAR(I) - fixed length string */
%replace SQL_TYP_NCHAR     by 453;
%replace SQL_TYP_LONG      by 456; /* LONG VARCHAR - varying length I > 4000 */
%replace SQL_TYP_NLONG     by 457;
%replace SQL_TYP_CSTR      by 460; /* varying length string for C */
%replace SQL_TYPNCSTR      by 461;
%replace SQL_TYP_VARGRAPH  by 464; /* VARGRAPHIC(I) - varying length */
%replace SQL_TYP_NVARGRAPH by 465;
%replace SQL_TYP_GRAPHIC   by 468; /* GRAPHIC(I) - fixed length graphic */
%replace SQL_TYP_NGRAPHIC  by 469;
%replace SQL_TYP_LONGRAPH  by 472; /* LONG VARGRAPHIC(I) - varying length */

%replace SQL_TYP_NLONGRAPH by 473;
%replace SQL_TYP_LSTR      by 476; /* varying length string for Pascal */
%replace SQL_TYP_NLSTR     by 477;
%replace SQL_TYP_FLOAT     by 480; /* FLOAT - 8-byte floating point */
%replace SQL_TYP_NFLOAT    by 481;
%replace SQL_TYP_DECIMAL   by 484; /* DECIMAL (p,q), sqllen q + (256 * p) */
%replace SQL_TYP NDECIMAL  by 485;
%replace SQL_TYP_ZONED     by 488; /* Zoned Decimal -> DECIMAL (m,n) */
%replace SQL_TYP_NZONED    by 489;
%replace SQL_TYP_INTEGER   by 496; /* INTEGER - 4-byte signed integer */
%replace SQL_TYP_NINTEGER  by 497;
%replace SQL_TYP_SMALL     by 500; /* SMALLINT - 2-byte signed integer*/
%replace SQL_TYP NSMALL    by 501;
%replace SQL_TYP_NUMERIC   by 504; /* NUMERIC -> DECIMAL (m,n) */
%replace SQL_TYP_NNUMERIC  by 505;

/* End of EXEC SQL INCLUDE SQLDA  -------------------------------------------------*/
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Embedding SQL Statements

You can add SQL statements to your program wherever executable statements can appear. Each SQL statement must begin with EXEC (or EXECUTE) SQL and end with a semicolon (;).

For example, an UPDATE statement might be coded as follows:

exec sql update Department
   set Mgrno    = :Mgr_Num
   where Deptno = :Int_Dept;

Comments

PL/I comments can be included in embedded SQL statements wherever a blank is allowed.

Continuation

The line continuation rules for embedded SQL statements are the same as for other PL/I statements.

Including Code

SQL statements or PL/I host variable declaration statements can be included by placing the following SQL statement at the point in the source code where the statements are to be embedded:

exec sql include {filename | 'filename'};

filename can be enclosed in single quote characters ('). Quotes are required if filename contains any non-alphanumeric characters, as for example,

'inventory.db001'.

Names

Any valid PL/I variable name can be used for a host variable, subject to the following restriction: Do not use host variable names or external entry names that begin with "SQL". These names are reserved for the database manager or Open PL/I. The length of a host variable name must not exceed 30 characters.

Statement Labels

With the exception of the END DECLARE SECTION statement and the INCLUDE text-filename statement, executable SQL statements, like PL/I statements, can have a label prefix.

WHENEVER Statement

The target for a GOTO clause in an SQL WHENEVER statement must be a label in the PL/I source code and must be within the scope of any SQL statements affected by the WHENEVER statement.

Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Using Host Variables

All host variables used in SQL statements must be explicitly declared. A host variable used in an SQL statement must be declared prior to the first use of the host variable in an SQL statement, except when the -sqltwop precompiler option is used. In addition:

  • All host variables within an SQL statement must be preceded by a colon (:).
  • The names of host variables must be unique within a program, even if the host variables are in different blocks or procedures.
  • An SQL statement that uses a host variable must be within the scope of the statement in which the variable is declared.
  • A host variable cannot be declared as an array.
  • Declaring Host Variables
  • Numeric Host Variables
  • Character Host Variables
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Declaring Host Variables

Host variable declarations can be made at the same places as ordinary PL/I variable declarations.

Not all PL/I data types are acceptable for host variables. The precompiler does not use the data attribute defaults specified in the PL/I DEFAULT statement. If the declaration for a variable is not recognized, any statement that references the variable may result in the message "The host variable token ID is not valid".

The SQL precompiler uses only the names and data attributes of host variable declarations; the alignment, scope, and storage class attributes are ignored.

Parent topic: Using Host Variables


Numeric Host Variables

The syntax for numeric host variable declarations is as follows:

DECLARE var-name-spec {BINARY | DECIMAL} scale-spec align-scope-storage ;

where:

var-name-spec | is {variable-name | (variable-name, ...) }
scale-spec | is {FIXED [(precision [,scale])] | FLOAT [(precision)]}
align-scope-storage | is any set of PL/I alignment, scope, or storage class attributes
Note:
  • BINARY | DECIMAL and FIXED | FLOAT can be specified in either order.
  • The precision and scale attributes can follow BINARY | DECIMAL instead of FIXED | FLOAT.
  • A value for scale can be specified only for DECIMAL FIXED.
  • DCL, BIN, and DEC are accepted as abbreviations for DECLARE, BINARY, and DECIMAL, respectively.

Parent topic: Using Host Variables


Character Host Variables

The syntax for character host variable declarations is as follows:

DECLARE var-name-spec CHARACTER [(length)] [VARYING] align-scope-storage ;

where:

var-name-spec | is {variable-name | (variable-name, ...) }
align-scope-storage | is any set of PL/I alignment, scope, or storage class attributes

Note:
  • For non-varying character host variables, length must be a constant no greater than the maximum length for SQL CHAR data.
  • For varying-length character host variables, length must be a constant greater than the maximum length for SQL LONG VARCHAR data.
  • DCL, CHAR, and VAR are accepted as abbreviations for DECLARE, CHARACTER, and VARYING, respectively.
Parent topic: Using Host Variables


Determining Equivalent SQL and PL/I Data Types

The base SQLTYPE and SQLLEN of host variables are determined according to the following table. If a host variable appears with an indicator variable, the SQLTYPE is the base SQLTYPE plus one.

PL/I Data Type | SQLTYPE of Host Variable | SQLLEN of Host Variable | SQL Data Type
BIN FIXED(n), n < 16 | 500 | 2 | SMALLINT
BIN FIXED(n), 16 ? n ? 31 | 496 | 4 | INTEGER
DEC FIXED(p,s) | 484 | p (byte 1) s (byte 2) | DECIMAL(p,s)
BIN FLOAT(p), 24 ? n ? 52 | 480 | 8 | FLOAT
CHAR(n), 1 ? n ? 254 | 452 | n | CHAR(n)
CHAR(n) VARYING, 1 ? n ? 4000 | 448 | n | VARCHAR(n)
CHAR(n) VARYING, n > 4000 | 456 | n | LONG VARCHAR
  • For FLOAT data, only double-word BIN FLOAT is supported.
  • Precisions, where appropriate, must be specified with integer constants. Default values are not provided.
  • The SQLDA include file has %REPLACE statements for the SQL data types.

The following table can be used to determine the PL/I data type that is equivalent to a given SQL data type.

SQL Data Type | PL/I Equivalent | Notes
SMALLINT | BIN FIXED(15) |
INTEGER | BIN FIXED(31) |
DECIMAL(p,s) | DEC FIXED(p) or DEC FIXED(p,s) | 1 ? p ? 31 and 0 ? s ? p
FLOAT | BIN FLOAT(p) | 24 ? p ? 52
CHAR(n) | CHAR(n) | 1 ? n ? 254
VARCHAR(n) | CHAR(n) VAR | 1 ? n ? 4000
LONG VARCHAR | CHAR(n) VAR | 4000 < n
DATE | CHAR(n) | 10 ? n
TIME | CHAR(n) | 8 ? n
TIMESTAMP | CHAR(n) | 26 ? n
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Determining Compatibility of SQL and PL/I Data Types

PL/I host variables in SQL statements must be type compatible with the columns that use them:

  • Numeric data types are compatible with each other. A SMALLINT, INTEGER, DECIMAL, or FLOAT column is compatible with a PL/I host variable of BIN FIXED(15), BIN FIXED(31), DECIMAL(p,s), or BIN FLOAT(n), where 24 ? n ? 53.
  • Character data types are compatible with each other. A CHAR or VARCHAR column is compatible with a fixed-length or varying-length PL/I character host variable. When necessary, the Database Manager automatically converts a fixed-length character string to a varying-length string or a varying-length string to a fixed-length string.
  • Datetime data types are compatible with character host variables. A DATE, TIME, or TIMESTAMP column is compatible with a fixed-length or varying-length PL/I character host variable.
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Using Host Structures

A PL/I host structure name can be a structure name. For example:

dcl 1 A,
      2  B,
        3  C1 char(...),
        3  C2 char(...);

In this example, B is the name of a host structure consisting of the scalar members C1 and C2.

However, structures (whether level 1 structures or substructures) may not be referenced in SQL statements. Only scalar members may be so referenced.

A fully qualified member name must be no more than 30 characters in length.

Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Using Indicator Variables

An indicator variable is a two-byte integer (BIN FIXED(15)). On retrieval, an indicator variable is used to show whether its associated host variable has been assigned a null value. On assignment to a column, a negative indicator value is used to indicate that a null value should be assigned.

Indicator variables are declared in the same way as host variables and the declarations of the two can be mixed in any way that seems appropriate.

Given the statement:

exec sql fetch Cls_Cursor into  :Cls_Cd,
                                :Day  :Day_Ind,
                                :Bgn  :Bgn_Ind,
                                :End  :End_Ind;

the variables could be declared as follows:

exec sql begin declare section;
dcl Cls_Cd     char(7);
dcl Day        bin fixed(15);
dcl Bgn        char(8);
dcl End        char(8);
dcl (Day_Ind, Bgn_Ind, End_Ind) bin fixed(15);
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


CONNECT TO Statement

You can use a host variable to represent the database name you want your application to connect to. For example:

exec sql connect to :dbase;

If a host variable is specified:

  • It must be a character or character varying variable.
  • It must be preceded by a colon and must not be followed by an indicator variable.
  • The server-name that is contained within the host variable must be left-justified.
  • If the length of the server-name is less than the length of the fixed-length character host variable, it must be padded on the right with blanks.
    dcl dbase char(10);
dbase = 'SAMPLE';    /*four blanks are */
                     /* automatically appended */
exec sql connect to :dbase;
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


COMPOUND Statement

Open PL/I requires a trailing semicolon after the start of an SQL compound statement. For example:

exec sql begin compound atomic static;
      select count(*) into :tmp3 from department;
      select count(*) into :tmp4 from project;
end compound;
Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Handling SQL Error Return Codes

Your DB2 product includes a routine that translates SQLCODE error values into readable text messages. When you process your program source with Open PL/I's DB2 SQL precompiler, an %INCLUDE statement is inserted into your program, and the include file this incorporates into your program contains a declaration of this SQLCODE translator routine as an entry, as follows:

declare sqldb2err entry(fixed bin(15) value,
                                    /* Buffer Size   */
               fixed bin(15) value, /* Line Width    */
               any,                 /* SQLCA         */
               any)                 /* Buffer        */
      returns(fixed bin(15))
      external('sqlgintp');

The return code values are:

  • >0 Length of message
  • -1 Internal DB2 error
  • -2 No error, SQLCODE = 0
  • -3 Invalid SQLCODE, no such error
  • -4 Line width is 0
  • -5 Invalid SQLCA, bad buffer address or bad buffer size

Example:

declare errmsg character(200);

exec sql connect to MYDB;
if sqlca.sqlcode < 0 then do;
   put skip list('Connect failed');
   /* Now print out reason for failure for most */
   /* recent SQL statement (i.e., the connect) */
   msg_len = sqldb2err(size(errmsg),0,sqlca,errmsg);
   put skip list(substr(errmsg,1,msg_len));
   return;
   end;

You do not need to declare sqldb2err. This is done for you automatically, as described above.

For more information about this routine, see SQLGINTP (Get Error Message) in your IBM platform-specific DATABASE 2 Programming Reference manual.

Parent topic: Coding DB2 SQL Statements in Open PL/I Applications


Sample Programs

  • Open PL/I DB2 SQL Sample 1 Program
  • Compilation, Linking, and Execution
  • Open PL/I DB2 SQL Sample 2 Program
Parent topic: DB2 SQL Support


Open PL/I DB2 SQL Sample 1 Program

filename: sample1.sqp

sample1: proc options(main);

/*                                                  */
/* This program shows the usage of host-variables,  */
/* indicators, and some common SQL statements       */

/* The database this program uses is the IBMSAMPL   */
/* database that your DB2 product uses. You must be */
/* able to run the IBM DB2 demo sample program in   */
/* order to be able to run this program.            */
/*                                                  */

dcl idx fixed bin(15);
dcl errmsg character(200);
dcl msg_len fixed bin(15);

exec sql include sqlca;

exec sql begin declare section;
   dcl cnt fixed bin(15);
   dcl projno char(6);
   dcl projname char(24) varying;
   dcl deptno char(6);
   dcl respemp char(6);

   dcl prstaff float bin(24);
   dcl prstaff_ind fixed bin(15);

   dcl prstdate char(10);
   dcl prstdate_ind fixed bin(15);

   dcl prendate char(10);
   dcl prendate_ind fixed bin(15);

   dcl majproj char(6);
   dcl majproj_ind fixed bin(15);
exec sql end declare section;

/* Set up error label for all SQL statements. */
exec sql whenever sqlerror goto err_label;

/* Connect to the IBM DB2 sample demo data base */
exec sql connect to IBMSAMPL;

/* Determine how many rows are in table project. */
exec SQL SELECT COUNT(*) INTO :cnt from project;

put skip edit('Number of rows in table project:', cnt) (a(40),x,f(3,0));
put skip list('All the rows for project are:');
put skip;

/* Declare and use a cursor to fetch each row. */
exec sql declare cl cursor for
  select projno, projname, deptno, respemp, prstaff,
         prstdate, prendate, majproj
  from project;

exec sql open cl;
do idx = 1 to cnt;
   prstaff = 0;       /* re-init */
   prstdate = ' ';    /* re-init */
   prendate = ' ';    /* re-init */
   majproj = ' ';     /* re-init */
   exec sql fetch cl into :projno,
                          :projname,
                          :deptno,
                          :respemp,
                          :prstaff  :prstaff_ind,
                          :prstdate :prstdate_ind,
                          :prendate :prendate_ind,
                          :majproj  :majproj_ind;
   put edit (projno, projname, deptno, respemp, prstaff, prstdate,
             prendate, majproj)
            (a(6),x,a(24),x,a(3),x,a(6),x,f(5,2),x,a(10),x,a(10),x,a(6));
   put skip;
   end;

 return;

err_label:
   msg_len = sqldb2err(200,0,sqlca,errmsg);
   put skip list(substr(errmsg,1,msg_len));

end sample1;
Parent topic: Sample Programs


Compilation, Linking, and Execution

mfplx –sql db2 –optsql db=sample sample1.sqp

sample1.sqp
Number of rows in table project:         20
All the rows for project are:
AD3100 ADMIN SERVICES        DO1 000010  6.50 01/01/1982 02/01/1983
AD3110 GENERAL ADMIN SYSTEMS D21 000070  6.00 01/01/1982 02/01/1983 AD3100
AD3111 PAYROLL PROGRAMMING   D21 000230  2.00 01/01/1982 02/01/1983 AD3110
AD3112 PERSONNEL PROGRAMMING D21 000250  1.00 01/01/1982 02/01/1983 AD3110
AD3113 ACCOUNT PROGRAMMING   D21 000270  2.00 01/01/1982 02/01/1983 AD3110
IF1000 QUERY SERVICES        CO1 000030  2.00 01/01/1982 02/01/1983
IF2000 USER EDUCATION        CO1 000030  1.00 01/01/1982 02/01/1983
MA2100 WELD LINE AUTOMATION  DO1 000010 12.00 01/01/1982 02/01/1983
MA2110 W L PROGRAMMING       Dl1 000060  9.00 01/01/1982 02/01/1983 MA2100
MA2111 W L PROGRAM DESIGN    Dl1 000220  2.00 01/01/1982 12/01/1982 MA2110
MA2112 W L ROBOT DESIGN      Dl1 000150  3.00 01/01/1982 12/01/1982 MA2110
MA2113 W L PROD CONT PROGS   D11 000160  3.00 02/15/1982 12/01/1982 MA2110
OP1000 OPERATION SUPPORT     E01 000050  6.00 01/01/1982 02/01/1983
0P1010 OPERATION             E11 000090  5.00 01/01/1982 02/01/1983 OP1000
0P2000 GEN SYSTEMS SERVICES  E01 000050  5.00 01/01/1982 02/01/1983
OP2010 SYSTEMS SUPPORT       E21 000100  4.00 01/01/1982 02/01/1983 OP2000
OP2011 SCP SYSTEMS SUPPORT   E21 000320  1.00 01/01/1982 02/01/1983 0P2010
OP2012 APPLICATIONS SUPPORT  E21 000330  1.00 01/01/1982 02/01/1983 0P2010
092013 DB/DC SUPPORT         E21 000340  1.00 01/01/1982 02/01/1983 0P2010
PL2100 WELD LINE PLANNING    B01 000020  1.00 01/01/1982 09/15/1982 MA2100
Parent topic: Sample Programs


Open PL/I DB2 SQL Sample 2 Program

filename: sample2.sqp

sample2: proc options(main);

   /* Sample program 2                                              */
   /* Example of using a user defined SQLDA                         */

   /* The database this program uses is the IBMSAMPL database that  */
   /* your DB2 product uses. You must be able to run the IBM DB2    */
   /* demo sample program in order to be able to run this program   */

   /* Uses a table of the form:                                     */
   /*    create table project                                       */
   /*       (projno char(6) not null,                               */
   /*       projname varchar(24) not null,                          */
   /*       deptno char(3) not null,                                */
   /*       respemp char(6) not null,                               */
   /*       prstaff dec(5,2),                                       */
   /*       prstdate date)                                          */

dcl k fixed bin(15);

exec sql include sqlca;
exec sql include sqlda;

exec sql begin declare section;
   dcl cnt fixed bin(15);
exec sql end declare section;

sqlsize 6;                     /* Lets only look at the 1st 6 columns */
allocate sqlda set(sqldapntr); /* sets sqln */
sqldaptr->sqld = 6;

dcl projno char(6) based;
sqldaptr->sqlda.sqlvar(1).sqltype = SQL_TYP_CHAR;
allocate projno set(sqldaptr->sqlda.sqlvar(1).sqldata);
sqldaptr->sqlda.sqlvar(1).sqllen = 6;

dcl projname char(24) var based;
saldaptr->sqlda.sqlvar(2).sqltype = SQL_TYP VARCHAR;
allocate projname set(sqldaptr->sqlda.sqlvar(2).sqldata);
sqldaptr->sqlda.sqlvar(2).sqllen = 24;

dcl deptno char(3) based;
sqldaptr->sqlda.sqlvar(3).sqltype = SQL_TYP_CHAR;
allocate deptno set(sqldaptr->sqlda.sqlvar(3).sqldata);
sqldaptr->sqlda.sqlvar(3).sqllen = 3;

dcl respemp char(6) based;
sqldaptr->sqlda.sqlvar(4).sqltype = SQL_TYP_CHAR;
allocate respemp set(sqldaptr->sqlda.sqlvar(4).sqldata);
sqldaptr->sqlda.sqlvar(4).sqllen = 6;

dcl prstaff float(24) binary based;
sqldaptr->sqlda.sqlvar(5).sqltype = SQL_TYP_FLOAT;
allocate prstaff set(sqldaptr->sqlda.salvar(5).sqldata);
sqldaptr->sqlda.sqlvar(5).sqllen = 8;

dcl prstdate char(10) based;
sqldaptr->sqlda.sqlvar(6).sqltype = SQL_TYP_CHAR;
allocate prstdate set(sqldaptr->sqlda.sqlvar(6).sqldata);
sqldaptr->sqlda.sqlvar(6).sqllen = 10;

exec sql connect to IBMSAMPL;
if SQLCA.SQLCODE < 0 THEN do;
   put skip list('Connect failed');
   return;
   end;
  else put skip list('Connect OK');
  put skip;
  exec sql whenever sqlerror goto err_label;
  put skip list('Projno Projname                 Dpt Respemp Prst Prstdate');
  put skip;

  exec sql declare cl cursor for select * from project;
  exec sql open cl;
  exec sql whenever not found go to done;
  do while ('1'b1);  /* do till fetch raises not found error */
     exec sql fetch c1 using descriptor :sqldaptr;
     put edit (sqldaptr->sqlda.sqlvar(1).sqldata->projno,
               sqldaptr->sqlda.sqlvar(2).sqldata->projname,
               sqldaptr->sqlda.sqlvar(3).sqldata->deptno,
               sqldaptr->sqlda.sqlvar(4).sqldata->respemp,
               sqldaptr->sqlda.sqlvar(5).sqldata->prstaff,
               sqldaptr->sqlda.sqlvar(6).sqldata->prstdate)
              (a(6),x,a(24),x,a(3),x,a(6),x,f(5,2),x,a(10));
     put skip;
     end;
done:
   exec sql whenever not found continue;   /* turn off */

   put skip;
   return;
err_label:
   put skip list('Branched to err_label');
   put skip list('sqlcode =', sqlcode);
   put skip list('sqlerrm =' , sqlerrm);
   put skip list('sqlstate =', sqlstate);
   return;

end sample2;

Output

Connect OK

Projno Projname              Opt Respemp  Prst Prstdate
AD3100 ADMIN SERVICES        D01 000010   6.50 01/01/1982
AD3110 GENERAL ADMIN SYSTEMS D21 000070   6.00 01/01/1982
AD3111 PAYROLL PROGRAMMING   D21 000230   2.00 01/01/1982
AD3112 PERSONNEL PROGRAMMING D21 000250   1.00 01/01/1982
AD3113 ACCOUNT PROGRAMMING   D21 000270   2.00 01/01/1982
1F1000 QUERY SERVICES        CO1 000030   2.00 01/01/1982
1F2000 USER EDUCATION        CO1 000030   1.00 01/01/1982
MA2100 WELD LINE AUTOMATION  DO1 000010  12.00 01/01/1982
MA2110 W L PROGRAMMING       D11 000060   9.00 01/01/1982
MA2111 W L PROGRAM DESIGN    D11 000220   2.00 01/01/1982
MA2112 W L ROBOT DESIGN      D11 000150   3.00 01/01/1982
MA2113 W L PROD CONT PROGS   D11 000160   3.00 02/15/1982
OP1000 OPERATION SUPPORT     E01 000050   6.00 01/01/1982
OP1010 OPERATION             E11 000090   5.00 01/01/1982
OP2000 GEN SYSTEMS SERVICES  E01 000050   5.00 01/01/1982
OP2010 SYSTEMS SUPPORT       E21 000100   4.00 01/01/1982
OP2011 SCP SYSTEMS SUPPORT   E21 000320   1.00 01/01/1982
0P2012 APPLICATIONS SUPPORT  E21 000330   1.00 01/01/1982
0P2013 DB/DC SUPPORT         E21 000340   1.00 01/01/1982
PL2100 WELD LINE PLANNING    B01 000020   1.00 01/01/1982
Parent topic: Sample Programs


Equivalent HCO for DB2 LUW Preprocessor Options

This table shows equivalent HCO for DB2 LUW preprocessor -optsql DB2 preprocessor options to the DB2 SQL preprocessor options.

HCO for DB2 LUW Preprocessor Option | DB2 Preprocessor Option
bind | -bind
bind=file_name | -bindname file_name
block=block_option | -block block_option
format=date/time_format | -datetime date/time_format
db=name | -dbname name
nobind | -nobind
isolation=option | -isolation option
access=package_name | -package package_name

To create a package TEST1 using a database named sample and a BIND file test1.bnd would be:

-optsql "db=sample access=test1 bind=test1"
Parent topic: DB2 SQL Support


HCO for SQL Server Compiler Directive Options for PL/I

Restriction: This topic applies to Windows environments (local development) only.

Syntax

To set an HCO for SQL Server compiler directive option for the PL/I compiler, use the following syntax:
mfplx pliProgName –sql odbc –optsql "SQLPrecompilerOption [...]"

Recommended Options

We recommend that you set the following HCO for SQL Server compiler directive options for PL/I when emulating mainframe settings using SQL:

  • BEHAVIOR=OPTIMIZED
  • CHECKDUPCURSOR
  • CHECKSINGLETON
  • DATE=USA
  • DBMAN=ODBC
  • DETECTDATE
  • DIALECT=MAINFRAME
  • MARS
  • NOCHECK
  • TARGETDB=MSSQLSERVER
  • TIME=USA
Note: Some of these options are specific to HCO for SQL Server, and some are available to both HCO for SQL Server and standard SQL.

Examples

Compiling
Compile a batch program to qualify tables using the QUALIFIER directive:
mfplx TESTPGM.PLI –sql odbc –optsql "QUALIFIER=HCOSQL" -isuffix cblrtssi –nologo
Compiling, Linking, and Binding
Compile 3 subroutines with a main program that calls routines to object files so it can be linked and then bound:
mfplx defplan0.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w –c
mfplx defplan1.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w –c
mfplx defplan2.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w –c
mfplx defplan3.pli -sql odbc -optsql "DBRMLIB" -isuffix -f w -c
Link object files:
ldpli defplan0.obj defplan1.obj defplan2.obj defplan3.obj cblrtssi -out:defplan0.exe
Bind:
dsn system(hcodemo) @defplan0.hcodsn
Parent topic: Open PL/I SQL Options
Related reference
BEHAVIOR
CHECK
CHECKDUPCURSOR
CHECKSINGLETON
DBMAN
DATE
DETECTDATE
DIALECT
MARS
TARGETDB
TIME
SQL Compiler Directive Options - HCOSS


OpenESQL Support for Oracle PL/I Applications (Technology Preview)

OpenESQL provides a run-time system that uses Oracle's native OCI API. You can use the OCI API to run Open PL/I applications.
Note: This is a technology preview feature only. It is being made available to allow you to test and provide feedback on this new capability; however, this feature is not intended for production use and it is not supported as such. Furthermore, Micro Focus does not guarantee that this feature will be delivered at a GA level and if it is, then the functionality provided might differ considerably from this technology preview.

The benefits of this run-time system are:

  • Better performance and reliability compared to Oracle's ODBC drivers
  • Support for BLOB, CLOB, BLOB_LOCATOR and CLOB_LOCATOR host variables
  • A date and timestamp formatting option that conforms to Oracle session settings for NLS_DATE_FORMAT, NLS_TIMESTAMP_FORMAT and NLS_TIMESTAMP_TZ_FORMAT
  • More comprehensive compile time checking with the SQL CHECK directive
  • Switch module support for Oracle OCI, as well as for JES-initiated transactions connecting to Oracle data sources using OCI.
  • Compiling a PL/I application for OCI
    Gives instruction on use of directives when compiling a PL/I application for OCI
  • Setting BLOB and CLOB variables
    Describes and illustrates how to declare BLOB and CLOB variables for compiling PL/I programs for Oracle OCI.
  • Date and Timestamp Formatting with OpenESQL for OCI
    Shows the Oracle OpenESQL date and timestamp statements executed in PL/I when opening an OCI connection.
  • Additional Considerations for Oracle
    Applications migrating from OpenESQL for ODBC, or from other database systems, should note the following.
  • Recommended OpenESQL Directives for Open PL/I
    Describes the SQL directives to use with Open PL/I for compatibility with OODBC, when migrating DB2 applications, and for Oracle date/time formatting.
  • Supported OpenESQL Compiler Options
    Lists supported OpenESQL compiler options for SQL ODBC and SQL OCI.
  • Switch Module Support
    Describes switch modules ESOCIXA.CBL and ESOCIOPC.CBL, used to connect to Oracle using OCI.
  • Using the OpenESQL OCI Directive with PL/I: Examples
    Provides examples of how to compile and link PL/I programs for OpenESQL OCI.
Parent topic: Open PL/I SQL Options
Related concepts
Technology Preview Features


Compiling a PL/I application for OCI

To compile an Open PL/I application for OCI, use the PL/I directive -SQL OCI rather than -SQL ODBC. To use SQL CHECK directive when compiling for OCI, the SQL DB directive setting must match the appropriate entry in the tnsnames.ora configuration file. For example:

-OPTSQL "DB=XE CHECK"
Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


Setting BLOB and CLOB variables

For compiling a PL/I application for OCI, declare BLOB and CLOB variables as shown:

    DCL TEST_BLOB SQL TYPE IS BLOB(4K);
    DCL TEST_CLOB SQL TYPE IS CLOB(2M);

You can specify BLOB or CLOB host variable sizes in kilobytes (K), megabytes (M), Gigabytes (G), or as an integer value. For a Unicode CLOB, use the type DBCLOB. A large object (LOB) host variable is equivalent to this declaration:

DCL 1 name,
     5 name_length      fixed bin(31),
     5 name_data        char(<size>);

where name_data can be an array of CHARs as appropriate if the LOB is greater than 32K.

These examples show how to declare LOB locator host variables.

DCL TEST_BLOB_LOC SQL TYPE IS BLOB_LOCATOR;
DCL TEST_CLOB_LOC SQL TYPE IS CLOB_LOCATOR;

A locator host variable is effectively a pointer to a LOB value, and can generally be used wherever a LOB host variable can be used. The advantage of using locators is that the whole LOB value is not transferred between the application and the server. For example, an application could duplicate a BLOB value from one row into another row.

exec sql
    select lob_col into :test_blob_loc from mytable where key = :k1;
exec sql
    update table2 set lob2_col = :test_blob_loc
    where key2 = :k2;
Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


Date and Timestamp Formatting with OpenESQL for OCI

OpenESQL for OCI supports the regular SQL formatting directives DATE, TIME, DATEDELM, TIMEDELIM and TSTAMPSEP. The default format is the same as ODBC. When an OCI connection opens, OpenESQL executes these Oracle SQL statements to achieve date/time formatting.

alter session set nls_date_format = 'YYYY-MM-DD HH24:MI:SS'
alter session set NLS_TIMESTAMP_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9'
alter session set NLS_TIMESTAMP_TZ_FORMAT = 'YYYY-MM-DD HH24:MI:SS.FF9 TZH:TZM'

If you want to use Oracle's default session settings or use alter session statements in your application, you must use -OPTSQL "DATE=EXTERNAL". In this case, OpenESQL passes values directly to and from Oracle without any additional formatting.

Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


Additional Considerations for Oracle

Applications migrating from OpenESQL for ODBC, or from other database systems, should note the following.

Positioned updates and HOLD cursors

OpenESQL for OCI converts positioned updates and deletes to searched updates using Oracle ROWIDs. When a FOR UPDATE cursor is opened, Oracle locks rows up to the first COMMIT. Thereafter OpenESQL still performs positioned updates, but rows fetched after the first COMMIT are not locked.

Scrollable cursors

In OCI, scrollable cursors are always read only. In all other ways, OCI scrollable cursors behave like ODBC keyset cursors. OpenESQL for OCI converts all non-forward only cursors to OCI read only scrollable cursors.

Isolation levels

Oracle OCI does not support read uncommitted isolation and defaults to read committed, based on snapshot/read consistency. However, since Oracle uses row versioning, reads generally do not block. Oracle OCI also does not support repeatable read isolation, so OpenESQL for OCI converts repeatable read isolation to serializable.

EXEC SQL Connect statement processing

  • CONNECT WITH PROMPT is not supported
  • Type 6 connect (user supplied connection string) is not supported
  • Output connection strings are not supported

Dynamic SQL

For dynamic SQL DESCRIBE, OCI may return different data types for NUMBER columns with a scale of 0. Some ODBC drivers may describe these as DECIMAL or NUMERIC. OCI describes them as tinyint (scale <= 2), smallint (scale <= 4), int (scale <= 9), bigint (scale <=18) or decimal (scale > 18).

Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


Recommended OpenESQL Directives for Open PL/I

To provide maximum compatibility with OpenESQL for ODBC applications, simply change -SQL ODBC to -SQL OCI.

This example shows how to use directives for optimum performance of Open PL/I applications with OCI.

-SQL OCI
-OPTSQL "BEHAVIOR=OPTIMIZED"

This example shows the additional SQL directives to use when migrating mainframe DB2 applications.

DATE=USA // or EUR, ISO or JIS as appropriate
DETECTDATE
CHECKDUPCURSOR
CHECKSINGLETON

This example shows the directives to use to provide Oracle date/time formatting.

-SQL OCI
-OPTSQL "DATE=EXTERNAL"
Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


Supported OpenESQL Compiler Options

This table shows supported OpenESQL Compiler Directive Options for SQL ODBC and SQL OCI.

Directives | SQL ODBC Support | SQL OCI Support
ADOPICXISANSI
ALLOWNULLCHAR | X | X
ANSI92ENTRY | X | X
AUTOCOMMIT | X | X
AUTOFETCH | X
BEHAVIOR (includes primitive directives) | X | X
  • DEF_CURSOR
X X
  • IC_FH_ISOLATION
X
  • PF_RO_CURSOR
X X
  • PF_UPD_CURSOR
X X
  • RO_CURSOR
X
  • TRANSACTION
X
  • UPD_CONCURRENCY
X
  • UPD_CURSOR
X
CHECK | X | X
CHECKDUPCURSOR | X | X
CHECKSINGLETON | X | X
CONCAT | X | X
CONNECTIONPOOL | X
CURSORCASE | X | X
DATE | X | X
DATEDELIM | X | X
DB | X | X
DECDEL | X | X
DETECTDATE | X | X
ESQLVERSION | X | X
FIPSFLAG | X | X
GEN-CC2 | X | X
GEN-INIT-FLAG | X | X
GEN-CLASS-VAR | X | X
HSFTRACE | X | X
IGNORE-NESTED | X | X
INIT | X | X
ISOLATION | X
JIT | X | X
MARS | X
NIST | X | X
NOT | X | X
ODBCTRACE | X | X
ODBCV3 | X | X
OPTIMIZECURSORS | X | X
PARAMARRAY | X
PASS | X | X
PRE | X | X
PREFETCH | X
QUALFIX | X | X
RESULTARRAY | X
STMTCACHE | X | X
TARGETDB | X
TESTSQLSTATE | X | X
TIME | X | X
TIMEDELIM | X | X
THREAD | X | X
TRACELEVEL | X | X
TSTAMPSEP | X | X
USERCURLIB | X
Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


Switch Module Support

This release includes an additional switch module, ESOCIXA.CBL, for use with container-managed applications connecting to Oracle using OCI, and for JES-initiated transactions connecting to Oracle using OCI.

The build script has been updated to provide an additional option, oci, to build this module.

Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


Using the OpenESQL OCI Directive with PL/I: Examples

Compiling

This example compiles a mainframe migrated batch program to maximum performance.

mfplx TESTPGM.PLI –sql oci –optsql
"BEHAVIOR=OPTIMIZED,DATE=USA,DETECTDATE,CHECKDUPCURSOR,CHECKSINGLETON" -ipath
$MFPLI_PRODUCT_DIR/include -isuffix .inc

Compiling and Linking

This example shows three subroutines compiled with a main program that calls routines to object files so it can be linked and bound.

mfplx defplan0.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc
mfplx defplan1.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc
mfplx defplan2.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc
mfplx defplan3.pli -sql oci -optsql "BEHAVIOR=OPTIMIZED" –c -ipath $MFPLI_PRODUCT_DIR/include -isuffix .inc

The link object files are:

ldpli defplan0.obj defplan1.obj defplan2.obj defplan3.obj -out:defplan0.exe

ldpli defplan0.o defplan1.o defplan2.o defplan3.o -out:defplan

Parent topic: OpenESQL Support for Oracle PL/I Applications (Technology Preview)


OpenESQL Compiler Options for Open PL/I

Syntax

This syntax sets OpenESQL compiler options for the Open PL/I compiler.

mfplx pliProgName –sql odbc –optsql "SQLPrecompilerOption [...]"

Recommended Options

These OpenESQL compiler options are recommended for PL/I when emulating mainframe settings using SQL.

  • BEHAVIOR=OPTIMIZED
  • CHECKDUPCURSOR
  • CHECKSINGLETON
  • DATE=[LOCAL COUNTRY]
  • TIME=[LOCAL COUNTRY]
  • DETECTDATE

Examples

This example compiles a batch program to qualify tables using MAINFRAME and DATE options.

mfplx TESTPGM.PLI –sql odbc –optsql "BEHAVIOR=OPTIMIZED  DATE=USA"
This example compiles three subroutines and a main program that calls routines to object files so it can be linked.
mfplx testpgm0.pli -sql odbc –optsql  "BEHAVIOR=OPTIMIZED DATE=USA"  –c
mfplx testsub1.pli -sql odbc -optsql  "BEHAVIOR=OPTIMIZED DATE=USA " –c
mfplx testsub2.pli -sql odbc –optsql  "BEHAVIOR=OPTIMIZED DATE=USA " –c
mfplx testsub3.pli -sql odbc -optsql  "BEHAVIOR=OPTIMIZED DATE=USA " –c
This example to links the object files and creates an executable file.
ldpli testpgm0.obj testsub1.obj testsub2.obj testsub3.obj -out:test.exe

Setting Project Options to Compile from Visual Studio

  1. Load the project in Visual Studio.
  2. Select Project > Properties and click the Compile tab.
  3. In the Other options field, type -sql odbc –optsql “SQLPrecompilerOption [...]”.
  4. Press CTRL + S to save your updates.
Parent topic: Open PL/I SQL Options


Open PL/I Compiler Diagnostic Messages

  • Interpreting Diagnostic Messages
Parent topic: Open PL/I User's Guide


Interpreting Diagnostic Messages

The format for Open PL/I compilation diagnostic messages is as follows:

filename (line, col)  :  diagnostic level  MFPLI + diagnostic number + first letter of the diagnostic level :  diagnostic message
filename
The name of the file that caused the diagnostic message.
(line, col)
Line number and column number. If the column number is 0, the column is not available.
diagnostic level
There are five diagnostic levels: Info, Warning, Error, Severe and Abort.
MFPLI + diagnostic number + first letter of the diagnostic level
This consists of "MFPLI", the diagnostic number and the first letter of the diagnostic level (Info - "I", Warning - "W", Error - "E", Severe - "S" and Abort - "A").
diagnostic message
A brief statement of the diagnostic.

Example

hex2.pl1 (10,0) : Severe MFPLI01253S : The first argument of the HEX built-in function must be a variable reference.
Note: An object file is not generated if an error at the Severe or Abort level is encountered.
Parent topic: Open PL/I Compiler Diagnostic Messages
Related information
Compiler Options


Open PL/I Run-time Error Messages

  • Run-time Errors
  • PL/I Run-time Error Codes
Parent topic: Open PL/I User's Guide


Run-time Errors

A run-time error is a program exception that occurs during execution. Some examples of program exceptions are:

  • Overflow on a floating-point computation
  • An invalid I/O operation on a file
  • A UNIX signal
  • An address violation trap
  • An invalid operand to a math routine.

When such errors occur, the run-time system responds by raising an appropriate condition. If the program has established a handler for the particular condition, the handler is invoked; otherwise, the run-time system performs a default action. A program establishes handlers for various conditions by means that differ from language to language: PL/I procedures can establish handlers by using ON-units, FORTRAN procedures can establish handlers for certain kinds of exceptions by using the ERR= and END= specifiers on I/O statements, and other languages provide no means of handling exceptions.

In the absence of a handler, the default action performed by the run-time system for most conditions except the ENDPAGE (f), FINISH, UNDERFLOW, and ERROR conditions is simply to raise the ERROR condition.

  • As the default action for the UNDERFLOW condition, the Open PL/I run-time system substitutes a true zero for the result and continues the computation.
  • As the default action for the ENDPAGE condition, the Open PL/I run-time system does a PUT(f)PAGE.
  • As the default action for the ERROR condition, the run-time system writes a message line to the standard output file (usually the terminal), closes all opened files, and terminates execution of the program.
  • As the default action for the FINISH condition, the Open PL/I run-time system continues execution.

The message line has the following form:

*** Condition ERROR raised

If the ERROR condition was raised as the default action for another condition, the above line is followed by another line:

*** Unhandled condition cccccc[for 000000 on file ffffff] at PC=xxxxxxxx

where

cccccc | Is the name of a condition and indicates the nature of the program exception as described in the remainder of this section.
000000 | Describes the I/O operation.
ffffff | Is the name of the file.
xxxxxxxx | Is the hexadecimal value of the PC at the time the error was detected (usually the address of an instruction in a routine from a run-time library).

If the error is related to an I/O operation on a file, the optional part of the message appears.

I/O errors are program exceptions related to operations on files. End-of-file on sequential input may raise the ENDFILE condition, and errors opening a file usually raise the UNDEFINEDFILE condition. The condition name used by the run-time system for other I/O errors has the form

I0_ERROR_nnn

where nnn is the error code for the particular error: either a run-time system error code or a UNIX system error code.

The AREA condition is raised in two situations: (1) if an attempt is made to allocate a based variable within an area that has insufficient free storage for the allocation, or (2) if an attempt is made to assign one area to another where the maximum size of the source area exceeds that of the target area.

Floating point exceptions raise conditions OVERFLOW, UNDERFLOW, ZERODIVIDE, CONVERSION, INVALID_OPERAND, or INVALID_mmmm, where mmmm is the name of a floating-point function or operation.

OVERFLOW | Indicates that the magnitude of a computational result is too large to represent.
UNDERFLOW | Indicates that the magnitude of a computational result is too close to zero to represent.
ZERODIVIDE | Indicates an attempt to divide by zero (note that the special case of zero divided by zero raises SIGFPE, however). Note: This condition is not recognized in cases where integer division is performed. In this case, the ONCODE for a general computational error (99200) is returned.
CONVERSION | Is raised when a floating-point value cannot be correctly converted to an integer, to or from another floating-point value of a different size, or to or from a character string representation.
INVALID_OPERAND | Results when an operand to a floating-point function (such as SIN, COS, TAN, EXP, and LOG) is out of the range capable of being handled accurately by the system.
INVALID_mmmm | Usually denotes an invalid operand to the indicated floating-point function or operation: the operand is Not-a-Number, +/- infinity, or is outside the mathematical domain of the function or operation.

RTS errors are program exceptions detected by the run-time system not related to I/O. The condition name raised for these errors has the form

 RTS_ERROR_nnn

where nnn is one of the error codes listed in Table B-1. An RTS error related to the conversion of a value from one data type to another is sometimes reported as the CONVERSION condition.

Finally, UNIX signals are errors detected by the system and reported to the program by the system's signaling mechanism. Signaled condition names have the form

SIGxxxx

where xxxx depends on the signal value. The various UNIX signal values are described in your UNIX documentation. On some UNIX systems, floating-point exceptions appear as SIGFPE.

Parent topic: Open PL/I Run-time Error Messages


PL/I Run-time Error Codes

The table below lists the run-time system error codes (100 –170). The UNIX system error codes (001 – 099) correspond exactly to the UNIX system error codes and are listed in your UNIX documentation.

Code | Description
100 | Duplicate record
101 | File not open
102 | Illegal argument
103 | Illegal key descriptor
104 | Too many files open
105 | Bad isam file format
106 | Non-exclusive access
107 | Record locked
108 | Key already exists
109 | Is primary key
110 | End of file reached
111 | No record found
112 | No current record
113 | File locked
114 | File name too long
115 | Can't create lock file
116 | Duplicate record (warning)
117 | Current record pointer undefined
118 | Can't allocate memory
119 | Bad custom collating
120 | Invalid operation
121 | Boundary violation on write
122 | Boundary violation on sequential file
123 | Not available, file locking or closed w/ lock
124 | Inconsistent attributes
125 | Open -APPEND on KEYED file
126 | Open -DAM on non-IDIRECT file
127 | Open -SAM on KEYED file
128 | File not open or is open for output only
129 | File not open or is open for input only
130 | Open on file not yet closed
131 | KEY specified on sequential file
132 | KEY specified on stream file
133 | No KEY specified on KEYED file
134 | Not a PRINT file
135 | Not a STREAM file
136 | CALL dataname name not found
137 | B-format error (35)
138 | BI format error (36)
139 | C format error (32)
140 | E format error (34)
141 | I/O stack overflow
142 | Conversion error
143 | LIST input item too long
144 | Implicit open failed
145 | EOF found while parsing edited input
146 | End of string on GET/PUT string
147 | Invalid format item for GET/PUT string
148 | Invalid format for GET
149 | Cannot initialize RPG screens
150 | File not open for input
151 | REWRITE on input file
152 | File not open on non-optional "sequential"
153 | File open on optional
154 | Sequential error on REW or DELE COBOL85
155 | Sequential error no next record COBOL85
156 | Bad record size on current record
157 | Cannot read log record
158 | Bad log record
159 | Cannot open log file
160 | Cannot write log file
161 | No transaction
162 | No shared memory
163 | No begin work yet
164 | Can't use nfs
165 | Audit trail exists
166 | F format error
167 | Record number too big for data item
168 | Open of wrong file type within transaction
169 | CLOSE REEL on non reel file
170 | No READ or WRITE before DELETE of record
171 | Return from subroutine specified a value
172 | Return from function did not specify a value
173 | Bad definition for creating a VSAM file
174 | No -defext used
175 | SET requires INDEXED or VSAM files
176 | Missing FROM on REWRITE and not VSAM
177 | -ebm requires EBM_ddname usage
178 | Unknown file-type specifier in EBM_ddname
179 | Undefined env var reference within EBM_ddname
180 | Invalid record-length value in EBM_ddname
181 | Unknown record-format in EBM_ddname
182 | File system is out of free space
Parent topic: Open PL/I Run-time Error Messages
Related information
PL/I


Value Table for ONCODE Built-in Function

  • Introduction
  • Table of values returned by ONCODE
Parent topic: Open PL/I User's Guide


Introduction

For more information on ON conditions, see the section ON in the chapter Statements and the section ONCODE Function in the chapter Open PL/I Built-Ins, both in your Open PL/I Language Reference Manual.

Note that the value returned by ONCODE for some conditions is implementation-dependent; in fact, some conditions that occur on one implementation may not be raised at all on another implementation, even by an identical source program run on both implementations. Further, subsequent releases of Open PL/I may change these ONCODE values. Therefore, to make programs more portable, avoid writing Open PL/I programs that depend on specific ONCODE return values to function properly; failing that, use replace constants to represent needed values so that implementation-specific values can be changed easily.

Parent topic: Value Table for ONCODE Built-in Function


Table of values returned by ONCODE

The tables below lists the values (codes) in ascending order, in sections marked by error category.

Code | Meaning
0 | ONCODE has been used outside of an active ON-unit

System-Defined Condition Codes

Code | Meaning
001 – 099 | A UNIX system error has occurred; the value returned corresponds exactly to the UNIX system error codes as listed in your system documentation.
100 – 89999 | A run-time error has occurred; the value returned corresponds exactly to the Open PL/I run-time error codes, as documented in Appendix C. (Note that 89999 is the highest possible error number and that not all error numbers are currently being used.)
9250 | A fetchable procedure was not found.

Unix Signal Condition Codes

Code | Meaning
90000 | Shell exit for any reason other than UNIX signals, including EOF.
90nnn | UNIX signal number nnn has been caught by the run-time system. The value nnn corresponds exactly with the signal number as defined in your system documentation, except for the following signals: SIGINT – Treated as PL/I ATTENTION condition. SIGFPE – Treated as computational error condition.

PL/I Condition Codes

Code | Meaning
99001 | ERROR condition raised by SIGNAL ERROR statement.
99011 | FINISH condition
99020 | ATTENTION condition
99110 | ENDFILE condition
99120 | ENDPAGE condition
99130 | KEY condition
99140 | UNDEFINEDFILE condition
99150 | RECORD condition
99151 | SIZE condition is triggered
99200 | Computational error; some operating systems indicate the precise cause of the error, in which case ONCODE will return the number corresponding to the more specific error description.
99201 | OVERFLOW condition
99202 | UNDERFLOW condition
99203 | ZERODIVIDE condition
99204 | SUBSCRIPTRANGE condition
99205 | CONVERSION condition
99206 | CONDITION condition
99207 | AREA condition
99210 | INVALID OPERAND condition
99211 | INVALID_ADD_SUBTRACT condition
99212 | INVALID_MULTIPLY condition
99213 | INVALID_DIVIDE condition
99214 | INVALID_MOD condition
99215 | INVALID_COMPARISON condition
99251 | INVALID_SQRT condition
99252 | INVALID_ASIN_ACOS condition
99253 | INVALID_ATAN2 condition
99254 | INVALID_LOG condition
99255 | INVALID_POWER condition
99256 | INVALID_ATANH condition
99257 | INVALID_COMPLEX_OPERAND condition
99301 | Stack unwind condition raised during non-local GOTO. This corresponds to the SS$_UNWIND value.
99310 | STRINGRANGE condition
Parent topic: Value Table for ONCODE Built-in Function


National Locale Support

The National Locale Support (NLS) facility provides a means of adapting your program to the character code set for a particular country, without the need for your application to know what these are in advance. This facility is also useful in English-speaking countries for handling codepages, collating upper- and lower-case letters correctly, selecting the appropriate currency symbol and selecting alphabetic extenders (for the $, # and @ signs) for PL/I identifier names.

The NLS facility provides you with the means to use codepages appropriate for your country when using UPPERCASE, LOWERCASE, PLIASCII, and PLIEBCDIC built-ins.

NLS can also be used to create messages in your language if messages for your language are provided by the appropriate release of the product.

  • Compiling Programs with NLS
  • Setting Up the National Locale Environment
  • Using the LANG Environment Variable
  • Running Your NLS Program
  • NLS Initialization
  • NLS Operations
Parent topic: Open PL/I User's Guide


Compiling Programs with NLS

Use the following compiler options to obtain NLS support:

  • -currency_symbol to control the currency symbol
  • -names to specify alphabetic extenders that can be used in the formation of PL/I identifier names
  • -or_symbol to specify the or symbol used as an "or" or (when paired) "concatenate" operator. This feature while not strictly NLS related does facilitate use of alternate symbols
  • -not_symbol to specify the not symbol used as the "not" operator. This feature while not strictly NLS related does facilitate use of alternate symbols
Parent topic: National Locale Support


Setting Up the National Locale Environment

Before you run a program with the facility, you must define your locale. A locale is the combination of language, territory and codepage. The locale used by the run-time system is initially set to the value of the regional settings for the operating system.

Parent topic: National Locale Support


Using the LANG Environment Variable

You define a locale using the LANG environment variable. LANG is set using the operating system command SET:

set LANG=language

You can also set this to obtain compile-time messages in a language of your choice assuming the messages in your language are provided by the release of the product you are using.

Parent topic: National Locale Support


Running Your NLS Program

You run programs containing NLS in the same way as you run programs without it. When the program runs:

  • The operating system's regional settings are used to determine which language environment to set up for this program. Use the LANG environment variable to provide the desired settings.
  • The NLS facility performs various operations in accordance with the rules of the language specified in the LANG environment variable.
Parent topic: National Locale Support


NLS Initialization

The run-time system initializes the NLS facility only once during an application's run. It uses the operating system's regional settings to determine which language environment to set up for this program using the LANG environment variable.

The run-time system uses the same language environment for any subsequent programs within the application which are compiled using NLS facilities.

If an error occurs during this initialization process, for example the language specified in the LANG environment variable is not supported, the run-time system reports the error:

40  National Language initialization not set up correctly

and terminates its run.

You can also receive this error if the LANG environment variable was set up by a third party product in a format different from that used by this PL/I system. If this occurs, use the COBLANG environment variable instead of the LANG environment variable.

If the run-time system cannot find the NLS run-time support modules, it issues the message:

46  NLS support module not found

and terminates its run.

Parent topic: National Locale Support


NLS Operations

When you run a program which has been compiled with the NLS directive set, certain operations are carried out in accordance with the rules of the language specified in the LANG environment variable.

Other language-dependent features, such as the currency character are controlled by the appropriate compiler option.

Certain NLS definitions have characters other than the ASCII characters 0-9 defined as numerics. Such characters are not valid in numeric picture strings, nor can they be used in numeric operations. Note that in all NLS operations, a numeric item must be formed only from the ASCII digits 0-9, with or without the ASCII signs "+" or "-" as well as other picture characters. There is no means of automatically converting the NLS representation to the ASCII equivalent.

The following are not affected by NLS:

  • String comparisons
  • SORT and MERGE Key Comparisons when SORT facility is in use
  • Case Conversion via UPPERCASE and LOWERCASE built-ins
  • Character conversion between EBCDIC and ASCII via PLIASCII and PLIEBCDIC built-ins
  • Collating Sequence Operations
  • Editing and computations on PICTURE data
Warning: Mixing programs with and without NLS can have unpredictable results
Parent topic: National Locale Support


Character Sets

  • Using the EBCDIC Character Set
    Describes how the EBCDIC character set is supported by the Open PL/I compiler and run time.
  • EBCDIC/ASCII Equivalents
Parent topic: Open PL/I User's Guide


Using the EBCDIC Character Set

The Open PL/I compiler and run time support character data encoded in EBCDIC format as well as ASCII format. For EBCDIC, this essentially means that the user program understands all character data as EBCDIC. Humans see all character data as readable text when it is read from input devices and written to display devices. When EBCDIC data is written to a file or read from a file, the data is always encoded as EBCDIC

Compiling a program in EBCDIC mode does not mean that the source file is in EBCDIC format. The source file is always in ASCII format, and character string literals such as 'abc' are converted to EBCDIC by the compiler. Run time support in EBCDIC mode likewise maintains all character data in EBCDIC format, and only translates to and from ASCII for human readable input or output devices.

For any given program, it is expected that all modules are compiled in either ASCII mode or EBCDIC mode.

The following compiler switches are supported:

-ascii | all character data in the user program is stored in ASCII format (default)
-ebcdic | all character data in the user program is stored in EBCDIC format

These examples show how the compiler treats character data in EBCDIC mode:

'abc' | stored as 0x818283
'abc ' | stored as 0x81828340
'abc 'E | stored as 0x81828340
'abc 'A | stored as '0x61626320
dcl s char (4) init (''); | stored as 0x40404040
dcl s char (4) init (''E); | stored as 0x40404040 (''E the null string padded with 4 EBCDIC spaces 0x040)
dcl s char (4) init (''A); | stored as 0x40404040 (''A the null string padded with 4 EBCDIC spaces 0x040)

These examples show how the compiler treats character data in ASCII mode:

'abc' | stored as 0x616263
'abc ' | stored as 0x61626320
'abc 'E | stored as 0x81828340
'abc 'A | stored as '0x61626320
dcl s char (4) init (''); | stored as 0x20202020
dcl s char (4) init (''E); | stored as 0x20202020 (''E the null string padded with 4 ASCII spaces 0x020)
dcl s char (4) init (''A); | stored as 0x20202020 (''A the null string padded with 4 ASCII spaces 0x020)
Note: In the above examples, the postfix characters for "E and "A are superfluous because the null string is padded with spaces accordingly with EBCDIC or ASCII mode.

When compiling in EBCDIC or ASCII mode through a server, output is dependent on the MF_CHARSET setting on the server. This table shows expected output formats of SYSPRINT for EBCDIC or ASCII-compiled programs based on the MF_CHARSET setting on the server.

Program Compiled | Server Running As | DCB | Expected Format of SYSPRINT
ASCII | ASCII | SYSOUT=* | ASCII
EBCDIC | EBCDIC | SYSOUT=* | EBCDIC
ASCII | ASCII | SYSOUT=*,DCB=(RECFM=LSEQ) | ASCII
EBCDIC | EBCDIC | SYSOUT=*,DCB=(RECFM=LSEQ) | ASCII
ASCII | EBCDIC | SYSOUT=*,DCB=(RECFM=LSEQ) | ASCII

Note that EBCDIC datasets are in EBCDIC and display correctly in ESMAC. LSEQ Datasets are flipped to ASCII and display correctly in ESMAC

Parent topic: Character Sets


EBCDIC/ASCII Equivalents

Index | EBCDIC (Hex) | Character | ASCII (Hex) | Notes
000 | 00 | NUL | 00 | null
001 | 01 | SOH | 01 |
002 | 02 | STX | 02 |
003 | 03 | ETX | 03 |
004 | 04 | PF | EC |
005 | 05 | HT | 09 | horizontal tab
006 | 06 | LC | CA |
007 | 07 | DEL | 7F | delete
008 | 08 |  | E2 |
009 | 09 |  | D2 |
010 | OA | SMM | D3 |
011 | OB | VT | OB | vertical tab
012 | OC | FF | OC | form feed
013 | OD | CR | OD | carriage return
014 | OE | SO | OE |
015 | OF | SI | A9 |
016 | 10 | DLE | 10 |
017 | 11 | DC1 | 11 |
018 | 12 | DC2 | 12 |
019 | 13 | TM | 13 |
020 | 14 | RES | EF |
021 | 15 | NL | C5 |
022 | 16 | BS | 08 |
023 | 17 | IL | CB |
024 | 18 | CAN | 18 |
025 | 19 | EM | 19 |
026 | 1A | CC | DC |
027 | 1B | CU1 | D8 |
028 | 1C | IFS | 1C |
029 | 1D | IGS | 1D |
030 | 1E | IRS | 1E |
031 | 1F | IUS | 1F |
032 | 20 | DS | B7 |
033 | 21 | SOS | B8 |
034 | 22 | FS | B9 |
035 | 23 |  | BB |
036 | 24 | BYP | C4 |
037 | 25 | LF | OA | line feed (new line)
038 | 26 | ETB | 17 |
039 | 27 | ESC | 1B |
040 | 28 |  | CC |
041 | 29 |  | CD |
042 | 2A | SM | CF |
043 | 2B | CU2 | DO |
044 | 2C |  | D1 |
045 | 2D | ENQ | 05 |
046 | 2E | ACK | 06 |
047 | 2F | BEL | 07 | bell
048 | 30 |  | D9 |
049 | 31 |  | DA |
050 | 32 | SYN | 16 |
051 | 33 |  | DD |
052 | 34 | PN | DE |
053 | 35 | RS | DF |
054 | 36 | UC | E0 |
055 | 37 | EOT | 04 | end transmission
056 | 38 |  | E3 |
057 | 39 |  | E5 |
058 | 3A |  | E9 |
059 | 3B | CU3 | EB |
060 | 3C | DC4 | B0 |
061 | 3D | NAK | B1 |
062 | 3E |  | 9E |
063 | 3F | SUB | 1A |
064 | 40 | SP | 20 | space
065 | 41 |  | C9 |
066 | 42 |  | 83 |
067 | 43 |  | 84 |
068 | 44 |  | 85 |
069 | 45 |  | A0 |
070 | 46 |  | F2 |
071 | 47 |  | 86 |
072 | 48 |  | 87 |
073 | 49 |  | A4 |
074 | 4A | ¢ | D5 |
075 | 4B | . | 2E | period
076 | 4C | < | 3C |
077 | 4D | ( | 28 |
078 | 4E | + | 2B |
079 | 4F | I | 7C |
080 | 50 | & | 26 |
081 | 51 |  | 82
082 | 52 |  | 88 |
083 | 53 |  | 89 |
084 | 54 |  | 8A |
085 | 55 |  | A1 |
086 | 56 |  | 8C |
087 | 57 |  | 8B |
088 | 58 |  | 8D |
089 | 59 |  | E1
090 | 5A | ! | 21 |
091 | 5B | $ | 24 |
092 | 5C | * | 2A |
093 | 5D | ) | 29 |
094 | 5E | ; | 3B | semicolon
095 | 5F | ¬ | 7E | ASCII tilde (~)
096 | 60 | - | 2D | hyphen
097 | 61 | / | 2F |
098 | 62 |  | B2 |
099 | 63 |  | 8E |
100 | 64 |  | B4 |
101 | 65 |  | B5 |
102 | 66 |  | B6 |
103 | 67 |  | 8F |
104 | 68 |  | 80 |
105 | 69 |  | A5 |
106 | 6A |  | B3 |
107 | 6B | , | 2C | comma
108 | 6C | % | 25 |
109 | 6D | _ | 5F | underscore
110 | 6E | > | 3E |
111 | 6F | ? | 3F |
112 | 70 |  | BA
113 | 71 |  | 90 |
114 | 72 |  | BC |
115 | 73 |  | BD |
116 | 74 |  | BE |
117 | 75 |  | F3 |
118 | 76 |  | C0 |
119 | 77 |  | C1 |
120 | 78 |  | C2 |
121 | 79 | ´ | 60 | accent grave
122 | 7A | : | 3A | colon
123 | 7B | # | 23 |
124 | 7C | @ | 40 |
125 | 7D | ' | 27 | apostrophe (accent acute)
126 | 7E | = | 3D |
127 | 7F | " | 22 | quotation mark
128 | 80 |  | C3 |
129 | 81 | a | 61 |
130 | 82 | b | 62 |
131 | 83 | c | 63 |
132 | 84 | d | 64 |
133 | 85 | e | 65 |
134 | 86 | f | 66 |
135 | 87 | g | 67 |
136 | 88 | h | 68 |
137 | 89 | I | 69 |
138 | 8A |  | AE |
139 | 8B |  | AF |
140 | 8C |  | C6 |
141 | 8D |  | C7 |
142 | 8E |  | C8 |
143 | 8F |  | F1 |
144 | 90 |  | F8 |
145 | 91 | j | 6A |
146 | 92 | k | 6B |
147 | 93 | l | 6C |
148 | 94 | m | 6D |
149 | 95 | n | 6E |
150 | 96 | o | 6F |
151 | 97 | p | 70 |
152 | 98 | q | 71 |
153 | 99 | r | 72 |
154 | 9A |  | 5E | ASCII caret ( ^ )
155 | 9B |  | A7 |
156 | 9C |  | 91 |
157 | 9D |  | CE |
158 | 9E |  | 92 |
159 | 9F |  | 0F |
160 | A0 |  | E6 |
161 | A1 |  | A6 |
162 | A2 | s | 73 |
163 | A3 | t | 74 |
164 | A4 | u | 75 |
165 | A5 | v | 76 |
166 | A6 | w | 77 |
167 | A7 | x | 78 |
168 | A8 | y | 79 |
169 | A9 | z | 7A |
170 | AA |  | AD |
171 | AB |  | A8 |
172 | AC |  | D4 |
173 | AD |  | 5B | ASCII left bracket ( [ )
174 | AE |  | D6 |
175 | AF |  | D7 |
176 | B0 |  | 9B |
177 | B1 |  | 9C |
178 | B2 |  | 9D |
179 | B3 |  | FA |
180 | B4 |  | 9F |
181 | B5 |  | 15 |
182 | B6 |  | 14 |
183 | B7 |  | AC |
184 | B8 |  | AB |
185 | B9 |  | FC |
186 | BA |  | AA |
187 | BB |  | FE |
188 | BC |  | E4 |
189 | BD |  | 5D | ASCII right bracket (])
190 | BE |  | BF |
191 | BF |  | E7 |
192 | C0 |  | 7B | ASCII left brace ( { )
193 | C1 | A | 41 |
194 | C2 | B | 42 |
195 | C3 | C | 43 |
196 | C4 | D | 44 |
197 | C5 | E | 45 |
198 | C6 | F | 46 |
199 | C7 | G | 47 |
200 | C8 | H | 48 |
201 | C9 | I | 49 |
202 | CA |  | E8 |
203 | CB |  | 93 |
204 | CC |  | 94 |
205 | CD |  | 95 |
206 | CE |  | A2 |
207 | CF |  | ED |
208 | D0 |  | 7D | ASCII right brace ( } )
209 | D1 | J | 4A |
210 | D2 | K | 4B |
211 | D3 | L | 4C |
212 | D4 | M | 4D |
213 | D5 | N | 4E |
214 | D6 | O | 4F |
215 | D7 | P | 50 |
216 | D8 | Q | 51 |
217 | D9 | R | 52 |
218 | DA |  | EE |
219 | DB |  | 96 |
220 | DC |  | 81 |
221 | DD |  | 97 |
222 | DE |  | A3 |
223 | DF |  | 98 |
224 | E0 |  | 5C | ASCII backslash ( \ )
225 | E1 |  | F0 |
226 | E2 | S | 53 |
227 | E3 | T | 54 |
228 | E4 | U | 55 |
229 | E5 | V | 56 |
230 | E6 | W | 57 |
231 | E7 | X | 58 |
232 | E8 | Y | 59 |
233 | E9 | Z | 5A |
234 | EA |  | FD |
235 | EB |  | F5 |
236 | EC |  | 99 |
237 | ED |  | F7 |
238 | EE |  | F6 |
239 | EF |  | F9 |
240 | F0 | 0 | 30 |
241 | F1 | 1 | 31 |
242 | F2 | 2 | 32 |
243 | F3 | 3 | 33 |
244 | F4 | 4 | 34 |
245 | F5 | 5 | 35 |
246 | F6 | 6 | 36 |
247 | F7 | 7 | 37 |
248 | F8 | 8 | 38 |
249 | F9 | 9 | 39 |
250 | FA |  | DB |
251 | FB |  | FB |
252 | FC |  | 9A |
253 | FD |  | F4 |
254 | FE |  | EA |
255 | FF |  | FF |
Parent topic: Character Sets


Environment Variables

  • Environment Variables Summary
Parent topic: Open PL/I User's Guide


Environment Variables Summary

This is a list of the most commonly used environment variables.

Variable | Description
CODEWATCH_STBPATH | The location of STB files for the debugger to use if none are found in directories specified when invoking CodeWatch.
CODEWATCH_SRCPATH | The location of source files for the debugger to use if none are found in directories specified when invoking CodeWatch.
ES_PL1_MFFH | Enables Micro Focus File Handler to perform all Open PL/I I/O operations. The default value is Y. If it is set to N, then all I/O are routed to old Liant file handlers.
ES_PL1_MFFH_JCL | Enables you to run Open PL/I programs that access JCL data definitions. The default value is N.
ES_PLI_SUPPORT | Tells the CICS Emulation that it needs to load its subsystem support for PL/I user programs. The default value is N.
MFPLI_PRODUCT_DIR | The location of the Open PL/I installation. It is used to find files needed for compiling and linking.
MFPLI_CONFIG_DIR | The location of the PLIDEBUG.DAT file. The folder defined by the MFPLI_PRODUCT_DIR environment variable is searched before using this location.
Parent topic: Environment Variables


Migration to Micro Focus File Formats

  • Overview
  • Reasons for Migrating to Micro Focus File Formats
  • Determine What File Formats You Are Using
  • Liant Indexed (aka) IBM/Informix CISAM
  • Liant Indexed (aka) IBM/Informix CISAM Conversion Process
  • Liant Variable Length Sequential Conversion Process
  • Liant Relative Record Conversion Process
  • Appendix - Unload Program
  • Appendix - Load Program
  • Appendix - Sample Shell Script to Build/Run
  • Appendix - Sample extfh.cfg
Parent topic: Open PL/I User's Guide


Overview

This guide shows you how to migrate your data to Micro Focus file formats so that it can be processed and manipulated using standard processes.

Parent topic: Migration to Micro Focus File Formats


Reasons for Migrating to Micro Focus File Formats

Micro Focus has its own file handler called Micro Focus ISAM that it has developed and enhanced for over two decades to provide file processing support for all Micro Focus COBOL-based applications. Within version 8.1 of Open PL/I we have therefore switched to using this core technology from Micro Focus rather than relying on the 3rd party file handler for Indexed files that was used originally within Open PL/I.

This will enable Micro Focus to provide ongoing support for all the file processing requirements of our Open PL/I customers from a single technology shared with all Micro Focus COBOL customers, but it does require data to be unloaded from original files formats and loaded into new Micro Focus file formats.

Parent topic: Migration to Micro Focus File Formats


Determine What File Formats You Are Using

These are the available file formats:

  • Line Sequential - no conversion necessary
  • Liant Sequential Fixed Length - no conversion necessary
  • Liant Indexed (aka) - IBM/Informix CISAM - conversion necessary *
  • Liant Relative Record - conversion optional **
  • Liant Sequential (Variable Length) - conversion optional **
Parent topic: Migration to Micro Focus File Formats
* Conversion is necessary if utilizing PLI IO Verbs.
** Conversion is only necessary if you intend to utilize the data within Micro Focus Enterprise Server and/or share the files with Micro Focus COBOL Programs.


Liant Indexed (aka) IBM/Informix CISAM

If you are using native PL/I I/O Verbs, you must convert data to Micro Focus Indexed Format.

If you are using IBM/Informix "IsXXXXX" APIs, you have two options:
  • Convert API calls to native PL/I I/O Verbs (and convert data)
  • Purchase a copy of CISAM from IBM and continue to use your existing datasets and "IsXXXXX" APIs.
    ( isaddindex () isbuild () isclose () isdelcurr () isdelete () iserase () isindexinfo () isopen () isread () isrelease () isrewcurr () isrewrite () ISRELOCK () isstart () isdef () iswrite () )
Parent topic: Migration to Micro Focus File Formats


Liant Indexed (aka) IBM/Informix CISAM Conversion Process

Unload is a very simple generic program needing only maximum record length and file names.

Load is a very simple generic program needing only maximum record length, file names, and key offset and length. Sample code is provided in Appendix A.

Load requires use of extfh.cfg to prevent null bytes from being stripped from output.

Note: SCALARV in the diagram above stands for SCALARVARYING.

The source programs in Appendix A are small and very simple. If you find that you have a large number of files that need to be converted, then one approach would be to use a shell script to generate the unload and load programs.

The easiest way to automate the process and generate the conversion programs via scripts would be to place all of the %REPLACE statements and the VSAM File Declarations in a PLI %INCLUDE. You should then be able to compile up the programs and be off and running.

In our testing of this process we had both the Open PL/I 7.4 Compiler and Open PL/I 8.1 Compiler and RTS Environments running side by side with no problems.

Parent topic: Migration to Micro Focus File Formats


Liant Variable Length Sequential Conversion Process

Load and Unload programs are very simple generic programs needing only maximum record length and file names to be provided. Sample code provided in Appendix A can be easily modified.

Load requires use of extfh.cfg to prevent null bytes from being stripped from output.

Note: SCALARV in the diagram above stands for SCALARVARYING.
Parent topic: Migration to Micro Focus File Formats


Liant Relative Record Conversion Process

Load and Unload programs are very simple generic programs needing only maximum record length and file names to be provided. Sample code provided in Appendix A can be easily modified.

Load requires use of extfh.cfg to prevent null bytes from being stripped from output.

Note: SCALARV in the diagram above stands for SCALARVARYING.
Parent topic: Migration to Micro Focus File Formats


Appendix - Unload Program

unload_liant_files: proc() options(main);
%replace MAX_REC_LEN               by 100;
%replace MAX_REC_LEN_SV            by 102;
%replace INPUT_TITLE               by 'liantCISAM';
%replace OUTPUT_TITLE              by 'fixed_cisam.dat';
 dcl inputfile    file record         env(vsam  recsize( MAX_REC_LEN ) );
 dcl outputfile    file record output env(f recsize( MAX_REC_LEN_SV ));

 dcl record_buff char(MAX_REC_LEN ) varying;
 dcl fixed_buf   char( MAX_REC_LEN_SV ) based(addr(record_buff));
 dcl vsam_buff   char( MAX_REC_LEN );

 on endfile(inputfile) goto doneinputfile;

 open file(inputfile) title(INPUT_TITLE) keyed sequential input;
 open file(outputfile) title(OUTPUT_TITLE);

 substr(fixed_buf, 2, length(fixed_buf) - 2) = '';
 read file(inputfile) into(record_buff);
 do while(1);
    write file(outputfile) from (fixed_buf);
    substr(fixed_buf, 2, length(fixed_buf) - 2) = '';
    read file(inputfile) into(record_buff);
 end;

doneinputfile:
 close file(inputfile);
 close file(outputfile);
end;
Parent topic: Migration to Micro Focus File Formats


Appendix - Load Program

load_microfocus_files: proc() options(main);

%replace MAX_REC_LEN               by 100;
%replace MAX_REC_LEN_SV            by 102;
%replace INPUT_TITLE               by 'fixed_cisam.dat';
%replace OUTPUT_TITLE              by 'microfocusIndexed.dat';
%include ‘vsamrec.in’;

 dcl inputfile    file record input env(f recsize( MAX_REC_LEN_SV ));
 dcl outputfile    file record
     env(vsam  recsize( MAX_REC_LEN ) keyloc(11) keylength(10));
 dcl 1 fixed_buf based(addr(in_rec)),
       5 fixed_buf_len  fixed bin(15),
       5 fixed_buf_data char( MAX_REC_LEN );
 dcl in_rec    char( MAX_REC_LEN ) varying;
 on endfile(inputfile) goto done;
 open file(inputfile) title(INPUT_TITLE);
 open file(outputfile) title(OUTPUT_TITLE) keyed sequential output;
 read file(inputfile) into(fixed_buf);
 do while(1);
    string(vsam_rec) = in_rec;
    write file(outputfile) from (vsam_rec) keyfrom(last_name);
    read file(inputfile) into(fixed_buf);
 end;
done:
 close file(inputfile);
 close file(outputfile);
end;
Parent topic: Migration to Micro Focus File Formats


Appendix - Sample Shell Script to Build/Run

echo ‘Solaris Sparc Shell Script’
rm liant*
rm microfocus*
rm fixed_*

lpiplx -deb -defext -cisam create_liant_files.pli -o create_liant_files
lpiplx -deb -defext -cisam test_liant_files.pli   -o test_liant_files
lpiplx -deb -defext -cisam unload_liant_files.pli -o unload_liant_files

mfplx  -deb -defext load_microfocus_files.pli -o load_microfocus_files
mfplx  -deb -defext test_microfocus_files.pli -o test_microfocus_files

echo 'Running create_liant_files'
./create_liant_files
echo 'Running test_liant_files'
./test_liant_files
echo 'Running unload_liant_files'
./unload_liant_files
echo 'Running load_microfocus_files'
./load_microfocus_files
echo 'Running test_microfocus_files'
./test_microfocus_files
Parent topic: Migration to Micro Focus File Formats


Appendix - Sample extfh.cfg

[XFH-DEFAULT]
IDXFORMAT=8
INSERTNULL=OFF
Parent topic: Migration to Micro Focus File Formats


SQL Option for DB2

Restriction: This topic applies to Windows environments only.
Note: Throughout this documentation, the terms XDB, SQL Option, and SQL Option for DB2 are equivalent.
  • SQL Option User Guide
    This collection of topics provides conceptual information about the main components of the SQL Option for DB2 feature.
  • SQL Option Server Administration Guide
    This collection of topics provides conceptual information about the architecture, configuration, and use of the XDB Server.
  • SQL Option Link Configuration Guide
    This collection of topics provides the information you need to configure SQL Option (XDB) Link to link your applications.
  • SQL Option Preprocesor Guide
    This collection of topics provides information on using the SQL Option Preprocessor to develop applications containing embedded SQL and test them against a full-featured, relational database system.
  • How to...
    Step-by-step instructions on how to use the main components of the SQL Option for DB2 feature.
  • Reference
    Topics that provide reference information on the use of commands and directives, and descriptions of each error message you might encounter when using the SQL Option for DB2 feature. This reference also includes topics that describe the user interface for each SQL Option for DB2 component.
Parent topic: Mainframe Programming
Related concepts
Database Access Features


SQL Option User Guide

Restriction: This topic applies to Windows environments only.
  • Introducing SQL Option for DB2
  • Bind Utility
  • Declaration Generator
  • Gateway Profile Utility (Link Profile)
  • JDBC
  • Migrate Utility
  • Options Utility
  • SQL Wizard
  • Stored Procedures
Parent topic: SQL Option for DB2


Introducing SQL Option for DB2

Restriction: This topic applies to Windows environments only.

With SQL Option, you can compile and run programs that contain Embedded SQL statements from the IDE without requiring access to a mainframe or LAN-based database system.

SQL Option uses the same technology as the popular XDB database system. An XDB database behaves exactly like a mainframe DB2 database but it runs on the PC. A personal XDB Server is installed on your PC, providing you with a completely self-contained development and test environment for DB2 applications.

For Windows environments

SQL Option allows the EBCDIC environment on the PC to be fully compatible with your mainframe's EBCDIC environment. See the section SQL Option NLS Environment for details.

If you are developing in a workgrouping environment, your system administrator can configure SQL Option so that you can access one or more shared, LAN-based XDB Servers in addition to your personal XDB Server. This two-tier configuration provides you with several further options for testing your application. For example, you can:

  • Maintain a complete copy or a subset of your mainframe test data on a shared XDB Server. Members of your workgroup can test against this directly or import the necessary tables into their personal XDB Server in situations where data needs to be isolated from other users.
  • Duplicate test data on the shared XDB Server and workgroup members' personal XDB Servers. The shared XDB Server can then be used for integration testing, with workgroup members performing development and unit tests against their personal XDB Servers.
  • Distribute data across a shared XDB Server and personal XDB Servers. For example, larger, more static tables can be left on the shared XDB Server, with smaller, more volatile tables being exported to the PC.

In addition, with appropriate configuration, you can access mainframe DB2 databases seamlessly with SQL Option's connectivity features. With this third tier configured, you have access to the full range of development and test options, giving you complete freedom to devise an effective workflow customized to your environment. For example, you can:

  • Use the mainframe DB2 test environment for all testing
  • Use the mainframe for integration testing, with workgroup members performing development and unit tests against either their personal XDB Servers or a shared XDB Server
  • Distribute test data across all three tiers, keeping very large tables on the mainframe and providing others on a shared XDB Server. Workgroup members can then download specific data to their personal XDB Server where necessary for isolation purposes.
  • SQL Option Tools
  • SQL Option NLS Environment
  • Using Existing XDB Data
  • SQL Option Demonstration Programs
  • Tips
Parent topic: SQL Option User Guide


SQL Option Tools

Restriction: This topic applies to Windows environments only.

SQL Option for DB2 consists of an embedded SQL precompiler and a number of client, configuration, and server tools, and graphical data utilities:

  • XDB Server
  • SQLWizard
  • Migrate utility
  • Options utility
  • Bind utility
  • XDB Link
  • Gateway Profile utility
  • Declaration Generator utility
  • SQL Option Preprocessor
  • Configuration utility
  • User Profile utility
  • Interactive SQL utility
  • Client and Server Configuration utility
  • Interactive SQL

For information on starting an SQL Option tool, see To access SQL Option for DB2 tools.

Parent topic: Introducing SQL Option for DB2


SQL Option NLS Environment

Restriction: This topic applies to Windows environments only.

SQL Option allows you to create XDB locations that emulate all the various mainframe EBCDIC code pages. When you access these locations with SQL Wizard or a COBOL program, your data in these locations appears identical to the data on the mainframe.

The five steps necessary to ensure complete compatibility with the mainframe and/or your COBOL development system are as follows:

  1. Decide which EBCDIC code page you want to emulate.

    Typically, you would use the mainframe's code page. (If you do not know what it is, you may be able to use XDB Link to find out.) If you do not have a mainframe, you can choose whichever code page you prefer.

  2. Create a local EBCDIC location for this code page.

    Use SQL Wizard's Create Location dialog box. Pick the EBCDIC code page you want in the Sort Sequence box.

  3. Ensure that your project's national language support (NLS) setting is the same as your EBCDIC location.

    When you compile a COBOL program with Enterprise Developer, it can be associated with a particular EBCDIC code page.

  4. If you have XDB Link, configure it to access the mainframe.

    Use the Gateway Profile utility to define your DB/2 locations to the PC software, then specify the single Workstation Code Page as 911 (in the local Workstation Configuration). Next, use SQL Wizard to access the DB/2 location on the mainframe. A file named cpg_info.txt is created in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bindirectory by default, identifying the EBCDIC code page of the DB/2 location on the mainframe. The following table defines this EBCDIC code page number:

    NLS Setting | Code Page Number
    31 Dutch | 37
    33 French | 297
    34 Spanish | 284
    39 Italian | 280
    43 Austrian German | 273
    44 English (UK) | 285
    45 Danish | 277
    46 Swedish | 278
    47 Norwegian | 277
    49 German | 273
    351 Portugese | 37
    358 Finnish | 278
    437 English (US) | 37
    500 International | 500
  5. Populate your local EBCDIC location with data from the mainframe.

    If you have XDB Link for the mainframe, there are two ways to do this: using Migrate or using SQL Wizard.

    • To use Migrate, all you need to do is point to the DB/2 location on your mainframe as the source location, and point to the local EBCDIC location as the destination location.
    • To use SQL Wizard, first export your mainframe's data in DSNTIAUL format, then import it into SQL Wizard. When you use the DSNTIAUL format, you need to specify a code page translation for both exports and imports: for exports, use the PC's ANSI code page to EBCDIC code page translation; for imports, use the reverse translation. For example, suppose you want to extract from a Swedish EBCDIC DB/2 location. For the export, you would pick the ANSI to EBCDIC translation 1252 - 278, for the import, 278 - 1252.

    If you don't have XDB Link for the mainframe, extract the data from the mainframe into a file with DSNTIAUL format, then import the data into your local EBCDIC location using SQL Wizard's import function, citing the appropriate EBCDIC to ANSI code page translation.

XDB EBCDIC databases are stored using the default OEM character set for your machine (typically, code page 437 in the United States, or code page 850 almost everywhere else). The names of database objects such as tables and indexes are also validated using this character set. You can optionally specify that database object-names should be validated using any of the following character sets if, for example, you want to use accented characters in the names:

MS-DOS Code Page | Character Set
437 | US Latin 1
850 | International Latin 1
857 | Turkish
863 | French Canada
865 | Nordic
860 | Portuguese

To specify that an XDB Server should use one of the supported code pages for name validation, you must add two lines to the xdb.ini file in %ProgramData%\Micro Focus\Enterprise Developer\mfsql\cfg:

[SERVER] XDBCP=codepage

where codepage is the three-digit number of the code page you require.

Where a location has been created as an EBCDIC location (for example, the default location, MAINTAIN), data is automatically converted to EBCDIC before it is passed to the client application. Conversion between ASCII data on the PC and EBCDIC data on the mainframe is handled by the DB2 Link gateway if you are using the Migrate utility. If you are using the data import and export facilities in SQL Wizard, you can control the conversion used by choosing the DSNTIAUL data format and selecting an appropriate code page conversion. See the topics Import/Export NSL Considerations for more information.

For information about EBCDIC conversions and theWindows Data File Converter, see the topic Converting Data Files.

Parent topic: Introducing SQL Option for DB2


Using Existing XDB Data

Restriction: This topic applies to Windows environments only.

If you already use XDB databases, you might be able to access them using SQL Option for DB2, providing that the locations in which they were created are compatible.

Parent topic: Introducing SQL Option for DB2


SQL Option Demonstration Programs

Restriction: This topic applies to Windows environments only.

To help you get working with SQL Option as quickly as possible, we supply several demonstration programs located in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\Mainframe\sql\xdb folder. The following lists each demonstration program and summarizes the functionality demonstrated by each:

test1.cbl | OPEN, FETCH, CLOSE, DELETE, and EXECUTE IMMEDIATE statements
test2.cbl | Scrolling through records and entering Y or N at the prompt
test3.cbl | CREATE TABLE, ALTER TABLE, UPDATE, and CREATE INDEX statements
test4.cbl | Joining tables
test5.cbl | Using Dynamic SQL PREPARE and EXECUTE statements
test6.cbl | OPEN, FETCH, UPDATE, DELETE, and CLOSE statements
OO_Sample.app | Coding an OO application for use with the SQL Option
Parent topic: Introducing SQL Option for DB2


Tips

Restriction: This topic applies to Windows environments only.
  • Use the Query Design window in SQL Wizard when you want to add new DML commands to your program but are not sure of the correct syntax. Create your query and run it until you are happy that results are correct. Then open the SQL window and copy the SQL statements into your program, between the EXEC SQL and the end-of-procedure statements.
  • If you are writing a program that needs to create a table and you have a test table with the correct structure, use SQL Wizard's Export capabilities to generate the DDL commands for your program.
  • If you create date columns in a test table using the WITH DEFAULT constraint, you can use the Date Warp feature of the IDE to change the system date on a row-by-row basis, without having to restart the XDB Server.
  • SQL Option automatically commits changes to a database when the end of a program procedure is reached with no errors. If an error occurs or if you stop debugging prior to reaching the end of a procedure, a rollback is performed instead. You do not need to use the LOGOFF directive when running a COBOL application.
Parent topic: Introducing SQL Option for DB2


Bind Utility

Restriction: This topic applies to Windows environments only.

The Bind utility enables you to create static SQL packages in a remote DB2 location accessed using DRDA, providing that the target location is registered appropriately at the DB2 Link gateway and that your AuthID has Bind authority at the target location. This applies to Windows environments (local development) only.

The Bind Utility generates a static package in DB2 from the contents of a local database request module (DBRM). A package is a single, bound DBRM containing optimized access paths to data. A DBRM contains all the information needed to create a package in a remote database.

Every application that runs against DB2 (including XDB Link) must have an application package to support the execution of statically-bound and dynamic SQL contained in the program. You must create a default package for XDB Link for each DB2 location with which you want to use the Link (applies to Windows environments only). See the Link Configuration Guide for more information.

Use the Bind Utility if you are configuring the XDB Link and you are ready to create a default DBRM and package for the Link, or you used the Static Bind Administrator to generate a DBRM and package for your application and you would like to modify or drop the package.

Note: For Windows environments

You do not need to bind your application if you use the default SQL precompiler settings, as these enable Embedded SQL statements in your programs to be run dynamically against the remote system. Running Embedded SQL dynamically is useful in situations where you want to access remote DB2 data but do not want to keep rebinding your application as it changes; for example, while debugging the application. You can optionally change the precompiler settings to produce static SQL database request modules to bind the application for deployment purposes. For more information on the precompiler options, see the topic XDB Directive Options.

A package at a location is identified by a collection identifier, a program identifier, a version label and a consistency token. Typically, you would use the collection identifier as a way of grouping the packages used in a single application consisting of one or more programs. The precompiler creates a program identifier for a package from the root of the program filename. You can specify a version label or accept the default value (01). You do not have to specify a version label, because the current package can be identified from its consistency token, generated from a timestamp at the start of precompilation. Note that each time you recompile a DB2 application, the timestamp changes and you must rebind the application to the DB2 host location if you are using static SQL packages. An alternative approach to avoid having to rebind your application each time you compile it is to debug against data stored in an EBCDIC location on your personal XDB Server. You can then test it against mainframe data when you have achieved a satisfactory level of stability.

The Bind utility enables you to specify a number of options for an application, including a version number and the isolation level of the application (applies to Windows environments only). These options can be stored in a file for future use.

Parent topic: SQL Option User Guide


Declaration Generator

Restriction: This topic applies to Windows environments only.
Note: This applies to Windows environments (local development) only.

The Declaration Generator automates the process of creating copybooks to declare host variables. You specify the table for which you want to generate a copybook and the Declaration Generator creates a copybook with data declarations that match the data names and types used in the XDB system. The Declaration Generator can be used interactively or in batch mode and can create a separate copybook for each table or one copybook containing declarations for many tables.

You can use the Declaration Generator to declare a table in C, COBOL or PL/I. For each language, the Declaration Generator creates a complete SQL DECLARE statement and the appropriate record definition (COBOL) or structure (C and PL/I). Depending upon the language, the following file types are created:

Language | Declaration File
COBOL | Copybook file (.cpy file)
C | Header file (.h file)
PL/I | Include file (.inc file)

You can run the Declaration Generator interactively (from a dialog box) or in batch mode (from the command line). Batch mode is useful for generating declarations for many tables at one time.

Regardless of whether you run the Declaration Generator interactively or in batch mode, you must specify the following:

  • The name of the table for which you want to generate a declaration file. Unless you specify otherwise, the name of the table is used as the name of the structure (C and PL/I) or record (COBOL).
  • The programming language in which you want the declaration written.
  • The name of the file to which the declaration statements will be written. The Declaration Generator automatically affixes the correct extension to the file name depending upon the programming language you select. If you specify a file that already exists, you can replace it or append the new statements to it.

You can specify language-dependent options. For example, when you create a COBOL declaration, you can select the computation type for whole-number fields; when you create a C declaration, you can select upper or lowercase element names.

To access DB2 data from an application program, you need to create host variables that are common data items between the SQL statements in your query and in your program. A data item declaration in the program must have the same name as that used in your SQL statement and must conform to the relevant DB2 data type for the column concerned. This applies to Windows environments (local development) only.

  • Examples
Parent topic: SQL Option User Guide


Examples

Restriction: This topic applies to Windows environments only.
  • Example COBOL Declaration
  • Example C Structure
  • Example PL/I Structure Declaration
  • Example Transaction Statement
Parent topic: Declaration Generator


Example COBOL Declaration

Restriction: This topic applies to Windows environments only.

The following shows the result of a COBOL declaration. In this example, level 2 was assigned to the record definition.

01 DCLEMPLOYEE.
  2 E-NO PIC S9(4) COMP.
  2 LNAME PIC X(10).
  2 FNAME PIC X(10).
  2 STREET PIC X(20).
  2 CITY PIC X(15).
  2 ST PIC X(2).
  2 ZIP PIC X(5).
  2 DEPT PIC X(4).
  2 PAYRATE PIC S9(13)V9(2) COMP-3.
  2 COM PIC SV9(2) COMP-3.
Parent topic: Examples


Example C Structure

Restriction: This topic applies to Windows environments only.

The following shows the result of a C declaration. In this example, the structure was declared without using the Declare The Structure option. Therefore, the structure describes a data type (called dcl_employee), but does not declare it as a variable. In this example, field prefixing has not been used.

struct dcl_employee
  {
  short e_no;
  char lname[11];
  char fname[11];
  char street[21];
  char city[16];
  char st[3];
  char zip[6];
  char dept[5];
  double payrate;
  double com;
  };
  short c_employee_ind[10];

Note that an array called c_employee_ind is also declared after the structure. This array is to be used to hold the null indicators for this table. (for example, c_employee_ind[0] can hold the indicator for e-no, c_employee_ind[1] the indicator for lname, c_employee_ind[2] the indicator for fname, and so forth).

Parent topic: Examples


Example PL/I Structure Declaration

Restriction: This topic applies to Windows environments only.

The following shows the result of a PL/I declaration. This sample was generated using the Generate Indicator Variables option.

DECLARE
  1 DCLEMPLOYEE,
  5 E_NO BIN FIXED(15),
  5 LNAME CHAR(10),
  5 FNAME CHAR(10),
  5 STREET CHAR(20),
  5 CITY CHAR(15),
  5 ST CHAR(2),
  5 ZIP CHAR(5),
  5 DEPT CHAR(4),
  5 PAYRATE DEC FIXED(15, 2),
  5 COM DEC FIXED(2, 2);
  DCL IEMPLOYEE(10) BIN FIXED(15);

Notice that the array of indicator variables was generated for you.

Parent topic: Examples


Example Transaction Statement

Restriction: This topic applies to Windows environments only.

The following example shows a simple transaction statement. In this example, the Declaration Generator reads the EMPLOYEE table and writes a declaration file called EMP_FILE.CPY. Because a language is not specified, COBOL is assumed.

employee emp_file.cpy

In a batch declaration file with multiple transactions, each transaction must be entered on a separate line, with no blank lines between them. The following example shows a .DGE file containing three transactions.

employee employee.cpy l=cobol s=dclempl p=sales u=real c=4 v=4
employee employee.h l=c s=c_employee p=sales u=real
orders orders.h l=c s=c_orders u=n/a a=upper d=decl

This example produces COBOL and C language output for the EMPLOYEE table. C output is also created for the ORDERS table.

Parent topic: Examples


Gateway Profile Utility (Link Profile)

Restriction: This topic applies to Windows environments only.

Host (mainframe) teleprocessing applications are usually designed for standard terminal environments that access large enterprise data stores. These applications do not usually have the power and graphics capabilities of PCs. While host applications are limited in this way, PC applications are also usually limited to processing local data in development or limited-production modes.

With XDB Link, you can combine both environments in a distributed application running on the PC or host and have access to both host and PC relational databases.

XDB Link consists of 32-bit software components based on IBM's Distributed Relational Database Architecture (DRDA), which specifies a standard way for different relational databases on different operating systems to communicate over a network. XDB Link runs on Windows NT, Windows 95, and Novell NetWare servers, with a copy of the XDB Server relational database management system and a copy of a communication subsystem, such as:

  • SNA Server (Windows NT)
  • SAA Server (Novell NetWare)

These communication subsystems provide APPC and TCP/IP protocol support.

XDB Link uses client/server architecture that allows networked PCs access to host data using IBM's DRDA.

PCs have access to host data through XDB Link AR (Application Requester). The Application Requester allows remote DBMS platforms to broadcast requests for RDBMS access across the Systems Network Architecture (SNA) network.

  • Link AR
  • XDB Link AR Architecture
  • XDB Link AR Security
  • XDB Link Installation and Configuration
  • Gateway Profile Utility
  • Host Option for TCP/IP
  • Code Mappings
  • Troubleshooting XDB Link Issues
Parent topic: SQL Option User Guide


Link AR

Restriction: This topic applies to Windows environments only.

XDB Link AR allows your PC applications to quickly and easily access different types of host data, bringing the power of PC processing and graphical user interfaces to enterprise-wide data applications. XDB Link AR gives you access to host data for both development and production PC applications.

PC production application support is provided by remote static bind access from the PC to create static SQL packages on the host. Code page translation between PC and host platforms is provided in XDB Link.

When using the optional XDB Link host option for MVS in conjunction with XDB Link AR, additional SQL and non-SQL host data can be accessed through the use of remote procedures and the Customer Information Control System (CICS). XDB Host option also provides TCP/IP access from the PC.

Parent topic: Gateway Profile Utility (Link Profile)


XDB Link AR Architecture

Restriction: This topic applies to Windows environments only.

XDB Link AR consists of two main components: the Gateway on the PC and the optional host component on the mainframe. XDB Link AR also enables SQL applications in a PC LAN environment to access host-based relational databases without providing special application code for network traversal or data type conversion.

Parent topic: Gateway Profile Utility (Link Profile)


XDB Link AR Security

Restriction: This topic applies to Windows environments only.

Security for XDB Link AR is handled by the XDB Server and your existing mainframe security scheme. The user is required to provide user ID and password before accessing local or remote data.

If Global Security is turned on and the location includes the XDB Server, then the security scheme is controlled by the existing scheme on the host. Otherwise, when using XDB Server, you must set up user IDs and passwords that match the user IDs and passwords on the remote DBMS. For example, if you have a user ID of 'DAVIDH' for DB2, you should also create a user ID of 'DAVIDH' for XDB Server. This is easily accomplished with the User Administration function of SQLWizard.

If you are using the host option of XDB Link AR, you can set up additional security on the mainframe. The host programs can be secured by external security managers, such as RACF or Top Secret, and can be maintained from the PC through XDB Link AR using the PEM utility. This process is described in the Link Configuration Guide.

Parent topic: Gateway Profile Utility (Link Profile)


XDB Link Installation and Configuration

Restriction: This topic applies to Windows environments only.

XDB Link provides a very powerful and easy-to-use method for cooperative processing to access both PC and mainframe data. XDB Link can be used in a variety of ways, depending upon corporate requirements. Listed below are the basic steps to get your application up and running with XDB Link. For more detailed instructions, see the Link Configuration Guide.

To install the client, some sort of client application is required. The client application can be another Micro Focus product, or, it could be an application developed using a Micro Focus interface.

The XDB Server software must be installed, configured, and started. It is the mechanism for transferring information to and from the mainframe, as well as maintaining XDB Server databases. This step assumes that the SNA or TCP/IP communications utility for your operating system has been installed on the XDB Server machine (such as NetWare SAA server). The Gateway installation and configuration procedure is outlined in the Link Configuration Guide

In addition (if not using Global Security), you must use SQLWizard to create user IDs to match those used on the mainframe. See the SQLWizard documentation for specific procedures.

If the host option was purchased, it must be installed and configured. This option is necessary if you want TCP/IP access to DB2 or if you want to use TCP/IP. See the Link Configuration Guide for details on installing the host software.

The host option does not need to be installed for DRDA access to remote locations.

Before the XDB Server can access mainframe locations, you must provide certain information about these locations. This information is registered in the communication database. Use the Gateway Profile utility to register mainframe locations that you want to access.

Use the Bind utility to create default database request modules (DBRM) for each of your DRDA locations. Bind this DBRM on each remote DRDA location you want to access via XDB Link AR. The package created when the DBRM is bound is used by all applications when accessing DRDA data via XDB Link AR.

Embed SQL statements in COBOL, use a Micro Focus application programming interface, or build your ODBC application. Create a program that has remote procedure calls.

Run the program you have created or run an XDB Server database management utility.

Be sure to read the instructions for installing and configuring XDB Link AR before attempting to access remote data.

Parent topic: Gateway Profile Utility (Link Profile)


Gateway Profile Utility

Restriction: This topic applies to Windows environments only.

Before clients can access data from remote locations, you must use the Gateway Profile Utility to:

  • Define remote locations to the XDB Link so that client applications can access data in those locations
  • Configure the settings the XDB Link needs to translate data correctly and control client conversations

After the initial configuration, you can use the Gateway Profile Utility to modify existing settings or define additional remote locations.

The XDB Link may be installed:

  • On an XDB Server machine as part of a gateway configuration

    or

  • On an client machine as part of a direct-connect configuration

If you are configuring the Link on an XDB Server machine as part of a gateway configuration, see the topic Configuring XDB Link with the Gateway Profile Utility before you run the Gateway Profile Utility.

To display the main window of the Gateway Profile Utility, double-click the Gateway Profile Utility icon.

Parent topic: Gateway Profile Utility (Link Profile)
Related information
Configuring XDB Link with the Gateway Profile Utility
Configuring the Link for a Gateway Server


Host Option for TCP/IP

Restriction: This topic applies to Windows environments only.

With the XDB Link Host Option for TCP/IP (or Host Option for TCP/IP) installed, the XDB Link can use the TCP/IP protocol to access DB2 data on the host. The XDB Link becomes a TCP/IP multi-user, multi-threaded server that processes DRDA-compliant requests for access to DB2 over a TCP/IP network.

The Host Option for TCP/IP consists of:

  • Scheduler Subsystem
  • LU 6.2 Communications Subsystem
  • TCP/IP Communications Subsystem
  • Administrative Subsystem
  • Trace Facility
  • Scheduler Subsystem
  • LU 6.2 Communications Subsystem
  • TCP/IP Communications Subsystem
  • Administrative Subsystem
  • Trace Facility
  • Issuing Commands to the Host Option for TCP/IP
  • Access List Message
Parent topic: Gateway Profile Utility (Link Profile)


Scheduler Subsystem

Restriction: This topic applies to Windows environments only.

The scheduler subsystem is the main task of the Host Option for TCP/IP. It initializes subtasks and creates an environment based on system parameters in the parameter file. It also initializes the access list.

Parent topic: Host Option for TCP/IP


LU 6.2 Communications Subsystem

Restriction: This topic applies to Windows environments only.

The LU 6.2 communications subsystem opens the Host Option for TCP/IP and initializes control blocks to interface with ACF/VTAM. When a client requests a connection to the remote DB2 location, it initializes a PLU of the DB2 LU 6.2 block and allocates a conversation with client-supplied information such as user ID, password and DB2 APPLID LU name.

This subsystem fills all necessary Function Management Header (FMH5) file information including LUWID. It transfers DDM flow to the remote DB2 location and receives messages from DB2. In case of an LU 6.2 communication error, the LU 6.2 communications subsystem formats an error packet and schedules a transmission request to the TCP/IP subtask.

Parent topic: Host Option for TCP/IP


TCP/IP Communications Subsystem

Restriction: This topic applies to Windows environments only.

This task handles all TCP/IP traffic to and from clients. It accepts client connection requests and validates requester's IP addresses based on the access list. It creates multitasking subtasks to communicate with multiple clients.

How to...

Parent topic: Host Option for TCP/IP


Administrative Subsystem

Restriction: This topic applies to Windows environments only.

The administrative subsystem manages the task and displays:

  • Conversation status.
  • PLU status.
  • Information about an XDB Link-started task through WTOR operator console commands.
Parent topic: Host Option for TCP/IP


Trace Facility

Restriction: This topic applies to Windows environments only.

The trace facility cuts GTF trace records for diagnostic purposes and to establish audit trails. A system administrator assigns the GTF event ID in the started task parameter.

Parent topic: Host Option for TCP/IP


Issuing Commands to the Host Option for TCP/IP

Restriction: This topic applies to Windows environments only.

There are several administrative commands that can be issued to control the Host Option for TCP/IP and to check its status. These commands are entered as replies to the following WTOR (Write To Operator with Reply) message prompt (which is displayed on the system console when you start the Host Option for TCP/IP):

@08 Enter XDBLINK Command

All Host Option for TCP/IP commands are issued in the following format:

R nn,command

where:

nn is the reply number message related to the Host Option for TCP/IP, and

command is the name of the Host Option for TCP/IP command.

Parent topic: Host Option for TCP/IP


Access List Message

Restriction: This topic applies to Windows environments only.

When the Host Option for TCP/IP is installed, a list of client IP addresses to be permitted or rejected is created (the Link Configuration Guide describes how to create this list). If the Host Option for TCP/IP receives a request from a client that is not in this list, a WTOR message is issued to the system console.

The operator can issue a PERMIT to accept the connection or REJECT to reject the connection. Issuing a PERMIT temporarily grants access to the requesting client.

The following example shows a WTOR message followed by both possible operator responses:

@08 Enter XDBLINK Action Command for IP: 204.177.148.64
R 8,PERMIT
R 8,REJECT
Parent topic: Host Option for TCP/IP


Code Mappings

Restriction: This topic applies to Windows environments only.
  • SQLCODE (DB2 Mode)
  • SQLCODE (XDB Mode)
  • SQLERRD
  • SQLSTATE Values
  • SQLSTATE Values (sorted by DB2 Code)
  • SQLSTATE Values (sorted by SQLSTATE Code)
Parent topic: Gateway Profile Utility (Link Profile)


SQLCODE (DB2 Mode)

Restriction: This topic applies to Windows environments only.

SQLCODE is an element of the SQLCA that stores a warning or return code from an SQL process. If you are running in DB2 mode, the value in SQLCODE is a DB2 warning or return code. To determine the appropriate error code, you must translate it into an XDB error message ID using the formula listed in the table below.

SQLCODE Value | Error Type | Formula | Msg File
-1 to -999 | Remote DBMS Error | Take absolute value and prefix with "L" | XDBMF.ERR
-1001 to -1650 | Database Engine Error | Take absolute value, subtract 1000, prefix with "X". | XDBRES.ERR
-1651 to -3000 | Network Error | Take absolute value, subtract 1650, prefix with "N". | XDBNET.ERR
-3001 to -29,999 | Not used. | -- | --
-30,000 to -30,100 | Distributed DBMS Communication Error | Take absolute value and prefix with "L". | XDBMF.ERR
Note:

Error messages -1 through -999 and -30,000 through -30,100 that come back through XDB Link are native to the remote DBMS being accessed.

Parent topic: Code Mappings


SQLCODE (XDB Mode)

Restriction: This topic applies to Windows environments only.

The following table describes the SQLCODE values when you are running in XDB mode.

SQLCODE is an element of SQLCA that stores the error code returned by an SQL process. If you are running in XDB mode, the value in SQLCODE is expressed as XDB error code. To determine the appropriate error code, you must translate it into an XDB error message ID using the formula listed in the table below.

SQLCODE Value | Error Type | Formula | Msg File
-1 to -650 | Remote DBMS Error | Take absolute value and prefix with "L". | XDBMF.ERR
-651 to -2000 | Database Engine Error | Take absolute value, subtract 1000, prefix with "X" | XDBRES.ERR
-2001 to -3000 | Network Error | Take absolute value, subtract 1650, prefix with "N" | XDBNET.ERR
-3001 to -3999 | Not used. | -- | --
-4000 to -4,100 | Distributed DBMS Communication Error | Take absolute value and prefix with "L". | XDBMF.ERR
Parent topic: Code Mappings


SQLERRD

Restriction: This topic applies to Windows environments only.

The SQLERRD(1) element in SQLCA contains the XDB error code returned by an SQL process. If you are running in DB2 mode, the DB2-equivalent of this error code is contained in SQLCODE (See the topic SQLCODE (DB2 Mode)).

To determine the appropriate error code, you must translate it into an XDB error message ID using the formula listed in the table below.

SQLERRD(1) Value | Error Type | Formula | Msg File
-1 to -650 | Database Engine Error | Take absolute value and prefix with "X". | XDBRES.ERR
-651 to -2000 | Network Error | Take absolute value, subtract 650, prefix with "N". | XDBNET.ERR
-2001 to -3000 | Not Used | -- | --
-3001 to -3999 | Remote DBMS Error | Take absolute value, subtract 3000, prefix with "L". | XDBMF.ERR
-4000 to -4,100 | Distributed DBMS Communication | Take absolute value, add -26,000, and prefix with "L". | XDBMF.ERR
Parent topic: Code Mappings


SQLSTATE Values

Restriction: This topic applies to Windows environments only.

The following table describes the ANSI equivalents to XDB mode and DB2 error codes. The ANSI error value is stored in the SQLSTATE element of SQLCA.

XDB mode SQLCODE | DB2 SQLCODE | ANSI SQLSTATE
+100 | N/A | 02000
0 | N/A | 00000
-2 | -198 | 37517
-4 | -405 | 53020
-6 | -102 | 54002
-7 | -10 | 37503
-9 | -206 | 52003
-11 | -401 | 53018
-12 | -401 | 53018
-16 | -501 | 24501
-18 | -803 | 23505
-19 | -101 | 54001
-20 | -84 | 37512
-23 | -302 | 22001
-26 | -129 | 54004
-28 | -159 | 52004
-32 | -913 | 40502
-35 | -913 | 40502
-40 | -803 | 23505
-43 | -402 | 53019
-44 | -685 | 58002
-46 | -602 | 54008
-47 | -107 | 54003
-48 | -601 | 52010
-50 | -614 | N/A
-51 | -603 | 22515
-54 | -117 | 53002
-55 | -121 | 52001
-56 | -601 | 52010
-57 | -117 | 53002
-58 | -408 | 53021
-59 | -404 | 22001
-61 | -680 | 54011
-66 | -125 | 53005
-71 | -412 | 53023
-72 | -112 | 37507
-73 | -122 | 53003
-75 | -122 | 53003
-76 | -913 | 40502
-79 | -150 | 56013
-80 | -127 | 56005
-82 | -421 | 53026
-83 | -415 | 53025
-86 | -407 | 23502
-87 | -107 | 54003
-88 | -107 | 54003
-91 | -551 | 42501
-103 | -119 | 53003
-104 | -607 | 53032
-106 | -155 | N/A
-108 | -153 | 56008
-118 | -601 | 52010
-119 | -107 | 54003
-124 | -607 | 53032
-125 | -514 | 26501
-127 | -414 | 53024
-130 | -618 | 53032
-138 | -156 | 53009
-140 | -160 | 53013
-141 | -161 | 23501
-144 | -652 | 23501
-146 | -616 | 23503
-153 | -913 | 40502
-154 | -913 | 40502
-155 | -913 | 40502
-156 | -911 | 40000
-157 | -913 | 40502
-158 | -913 | 40502
-159 | -913 | 40502
-160 | -913 | 40502
-174 | -601 | 52010
-177 | -107 | 54003
-179 | -604 | 37511
-185 | -126 | 53029
-188 | -305 | 22002
-212 | -104 | 37501
-214 | -502 | 24502
-215 | -501 | 24501
-227 | -531 | 23504
-228 | -532 | 23504
-229 | -530 | 23503
-231 | -510 | 53028
-244 | -118 | 56002
-246 | -534 | 21502
-247 | -181 | 22007
-277 | -551 | 42501
-278 | -553 | 42503
-279 | -107 | 54003
-280 | -204 | 52004
-281 | -601 | 52010
-284 | -637 | 37514
-287 | -513 | 56024
-288 | -512 | 56023
-289 | -644 | 37515
-290 | -620 | 53001
-291 | -199 | 37501
-305 | N/A | 22002
-343 | -925 | 56201
-344 | -926 | 40502
-803 | N/A | 23505
-811 | N/A | 21000
Parent topic: Code Mappings


SQLSTATE Values (sorted by DB2 Code)

Restriction: This topic applies to Windows environments only.

The following table describes the ANSI equivalents to an XDB mode error codes. The ANSI error value is stored in the SQLSTATE element of the SQLCA.

DB2 SQLCODE | XDB mode SQLCODE | ANSI SQLSTATE
N/A | -811 | 21000
N/A | -803 | 23505
N/A | +100 | 02000
N/A | 0 | 00000
N/A | -305 | 22002
-10 | -7 | 37503
-84 | -20 | 37512
-101 | -19 | 54001
-102 | -6 | 54002
-104 | -212 | 37501
-107 | -47 | 54003
-107 | -87 | 54003
-107 | -88 | 54003
-107 | -119 | 54003
-107 | -177 | 54003
-107 | -279 | 54003
-112 | -72 | 37507
-117 | -54 | 53002
-117 | -57 | 53002
-118 | -244 | 56002
-119 | -103 | 53003
-121 | -55 | 52001
-122 | -73 | 53003
-122 | -75 | 53003
-125 | -66 | 53005
-126 | -185 | 53029
-127 | -80 | 56005
-129 | -26 | 54004
-150 | -79 | 56013
-153 | -108 | 56008
-155 | -106 | N/A
-156 | -138 | 53009
-159 | -28 | 52004
-160 | -140 | 53013
-161 | -141 | 23501
-181 | -247 | 22007
-198 | -2 | 37517
-199 | -291 | 37501
-204 | -280 | 52004
-206 | -9 | 52003
-302 | -23 | 22001
-305 | -188 | 22002
-401 | -11 | 53018
-401 | -12 | 53018
-402 | -43 | 53019
-404 | -59 | 22001
-405 | -4 | 53020
-407 | -86 | 23502
-408 | -58 | 53021
-412 | -71 | 53023
-414 | -127 | 53024
-415 | -83 | 53025
-421 | -82 | 53026
-501 | -16 | 24501
-501 | -215 | 24501
-502 | -214 | 24502
-510 | -231 | 53028
-512 | -288 | 56023
-513 | -287 | 56024
-514 | -125 | 26501
-530 | -229 | 23503
-531 | -227 | 23504
-532 | -228 | 23504
-534 | -246 | 21502
-551 | -91 | 42501
-551 | -277 | 42501
-553 | -278 | 42503
-601 | -48 | 52010
-601 | -56 | 52010
-601 | -118 | 52010
-601 | -174 | 52010
-601 | -281 | 52010
-602 | -46 | 54008
-603 | -51 | 22515
-604 | -179 | 37511
-607 | -104 | 53032
-607 | -124 | 53032
-614 | -50 | N/A
-616 | -146 | 23503
-637 | -284 | 37514
-644 | -289 | 37515
-652 | -144 | 23501
-680 | -61 | 54011
-685 | -44 | 58002
-803 | -18 | 23505
-803 | -40 | 23505
-911 | -156 | 40000
-913 | -32 | 40502
-913 | -35 | 40502
-913 | -76 | 40502
-913 | -153 | 40502
-913 | -154 | 40502
-913 | -155 | 40502
-913 | -157 | 40502
-913 | -158 | 40502
-913 | -159 | 40502
-913 | -160 | 40502
-925 | -343 | 56201
-926 | -344 | 40502
Parent topic: Code Mappings


SQLSTATE Values (sorted by SQLSTATE Code)

Restriction: This topic applies to Windows environments only.

The following table describes the ANSI equivalents to an XDB mode error codes. The ANSI error value is stored in the SQLSTATE element of the SQLCA.

ANSI SQLSTATE | XDB mode SQLCODE | DB2 SQLCODE
N/A | -50 | -614
N/A | -106 | -155
00000 | 0 | N/A
02000 | +100 | N/A
21000 | -811 | N/A
21502 | -246 | -534
22001 | -23 | -302
22001 | -59 | -404
22002 | -188 | -305
22002 | -305 | N/A
22007 | -247 | -181
22515 | -51 | -603
23501 | -141 | -161
23501 | -144 | -652
23502 | -86 | -407
23503 | -229 | -530
23503 | -146 | -616
23504 | -227 | -531
23504 | -228 | -532
23505 | -18 | -803
23505 | -40 | -803
23505 | -803 | N/A
24501 | -16 | -501
24501 | -215 | -501
24502 | -214 | -502
26501 | -125 | -514
37501 | -291 | -199
37501 | -212 | -104
37503 | -7 | -10
37507 | -72 | -112
37511 | -179 | -604
37512 | -20 | -84
37514 | -284 | -637
37515 | -289 | -644
37517 | -2 | -198
40000 | -156 | -911
40502 | -32 | -913
40502 | -35 | -913
40502 | -76 | -913
40502 | -153 | -913
40502 | -154 | -913
40502 | -155 | -913
40502 | -157 | -913
40502 | -158 | -913
40502 | -159 | -913
40502 | -160 | -913
40502 | -344 | -926
42501 | -277 | -551
42501 | -91 | -551
42503 | -278 | -553
52001 | -55 | -121
52003 | -9 | -206
52004 | -28 | -159
52004 | -280 | -204
52010 | -48 | -601
52010 | -56 | -601
52010 | -118 | -601
52010 | -174 | -601
52010 | -281 | -601
53001 | -290 | -620
53002 | -54 | -117
53002 | -57 | -117
53002 | -54 | -117
53002 | -57 | -117
53003 | -73 | -122
53003 | -75 | -122
53003 | -103 | -119
53005 | -66 | -125
53009 | -138 | -156
53013 | -140 | -160
53018 | -11 | -401
53018 | -12 | -401
53019 | -43 | -402
53020 | -4 | -405
53021 | -58 | -408
53023 | -71 | -412
53024 | -127 | -414
53025 | -83 | -415
53026 | -82 | -421
53028 | -231 | -510
53029 | -185 | -126
53032 | -104 | -607
53032 | -124 | -607
53032 | -130 | -618
54001 | -19 | -101
54002 | -6 | -102
54003 | -47 | -107
54003 | -87 | -107
54003 | -88 | -107
54003 | -119 | -107
54003 | -177 | -107
54003 | -279 | -107
54004 | -26 | -129
54008 | -46 | -602
54011 | -61 | -680
56002 | -244 | -118
56005 | -80 | -127
56008 | -108 | -153
56013 | -79 | -150
56023 | -288 | -512
56024 | -287 | -513
56201 | -343 | -925
58002 | -44 | -685
Parent topic: Code Mappings


Troubleshooting XDB Link Issues

Restriction: This topic applies to Windows environments only.

The following table gives a list of common problems and possible solutions.

Problem | Solution
A DOS system error is returned on startup of IBM LAN Requester. | Your Communications Manager, LAN feature profile is using a station address that is identical to another workstation's address. Change the station address to be unique within the LAN.
When booting the Communications Manager, LU 6.2 sessions are not allowed on the SNA gateway for a downstream Gateway. Only the 3270 session allocates on the SDLC/Token Ring Gateway. | Ensure you are using the correct CFG for Communications Manager and that it allows APPC. Ensure the CFG pointed to in config.sys for Communications Manager allows APPC.
The LAN Requester abends when selected from the Communications Manager main menu.

NetBIOS support is missing from config.sys and the Communications Manager CFG. Correct your Communications Manager CFG, access the LAN feature profiles section and configure the IEEE802 option (you may choose not to use Univ Admin Addresses and opt to create your own). Now you may reboot your machine and try to access the LAN Requester. If this fails to work, you must re-install Communications Manager. Remove the existing manager and re-install using the CFG file already modified above.
Import is taking a long time to transfer records. DB2 is slow. Timeout errors are occurring. Import was started without a commit interval being specified. Since no interval was specified, DB2 is filling up its buffer pool with a single unit of work. Run Import using the command:
xdbimpor /cnnn

where nnn is the commit interval. Try 50 to start.
Parent topic: Gateway Profile Utility (Link Profile)


JDBC

Restriction: This topic applies to Windows environments only.

The Micro Focus Direct Flight JDBC driver provides JDBC support for XDB Server. See the chapter SQL Option for DB2 for more information on XDB Server.

You can use the Direct Flight driver to:

  • Establish a connection to an XDB Server
  • Send SQL statements to an XDB Server
  • Process results from an XDB Server
Note:

Before you can connect to an XDB Server you must load the Direct Flight driver. See the topic Loading the Direct Flight Driver for more information.

To use the Direct Flight driver you must have:

  • Java 2 Version 1.2 or higher installed
  • Access to an XDB Server
  • Loading the Direct Flight Driver
  • Connecting to an XDB Server
  • Calling COBOL Stored Procedures
Parent topic: SQL Option User Guide


Loading the Direct Flight Driver

Restriction: This topic applies to Windows environments only.

You must load the Direct Flight driver before you can connect to an XDB Server. The simplest way to load the driver is to use the following code:

Class.forName ("mf.jdbc.DFDriver");

Where DFDriver is the name of the Micro Focus Direct Flight driver.

This creates an instance of the mf.jdbc.DFDriver class which represents the Direct Flight driver and registers the driver with your Java development environment Driver Manager.

The following code examples demonstrate two other methods for loading the driver:

In this example, the driver is loaded before calling the DriverManager.getConnection method:

Connection login(String sUser, String sPassword)
throws SQLException {

String sURL = “jdbc.mf://myhost”;
Driver driver = new mf.jdbc.DFDriver();

return DriverManager.getConnection(sURL, sUser, sPassword);

}

In this example, mf.jdbc.DFDriver is instantiated within the static code of the class that connects to the XDB Server:

Class MyClass {
      static {
              try {
                      Driver driver = new mf.jdbc.DFDriver();
              }
              catch  (Exception e)
              {
                      e.printStackTrace();
              }
      }
}
Parent topic: JDBC


Connecting to an XDB Server

Restriction: This topic applies to Windows environments only.

Once you have loaded the Direct Flight driver, you can connect to an XDB Server. You do this by passing information to one of the three overloads for the DriverManager.getConnection method. See the section Overloads for the DriverManager.getConnection Method for more information. The following table shows you where different types of information can be passed to the overloads:

Information | Passed Where? | Required?
The name of an XDB Server (or a list of XDB Servers for fault tolerance) | Only in the URL | Required
An AuthID and password recognized by the XDB Server As explicit parameters for Overload 1 or as properties:
  • In the URL
  • In a Properties Object
Required
Additional property values (including a data profile)
  • In the URL
  • In a Properties Object
Optional

See the sections Direct Flight URL Syntax, Direct Flight Data Connection Properties and Defining a JDBC Data Profile for more information.

There is an order of precedence for property value definitions. The order is:

  1. A URL overrides all other definitions
  2. A Property Object overrides values defined in a data profile
  3. A data profile does not override any other definitions
Note:

If you have defined a data profile and set its canoverride property to "No," the property values defined in the data profile are not overridden by values in the URL or Properties Object. See the section Defining a JDBC Data Profile for more information.

  • Overloads for the DriverManager.getConnection Method
  • Direct Flight URL Syntax
  • Direct Flight Data Connection Properties
  • Defining a JDBC Data Profile
Parent topic: JDBC


Overloads for the DriverManager.getConnection Method

Restriction: This topic applies to Windows environments only.

The DriverManager.getConnection method has three overloads. The URL syntax is the same for all three overloads. See the section Direct Flight URL Syntax for more information.

You connect to an XDB Server by calling one of these overloads in your Java applet or application. The overload you choose depends on the parameters that are supported by your Java development environment and on the data connection properties that you need to specify.

This section describes the three overloads for the DriverManager.getConnection method and their parameters.

  • Overload 1
    URL, AuthID and password.
  • Overload 2
    URL and Properties Object.
  • Overload 3
    URL only.
Parent topic: Connecting to an XDB Server
Related information
Direct Flight URL Syntax


Overload 1

Restriction: This topic applies to Windows environments only.

Parameters:

URL | The XDB Server URL (String)
AuthID | The AuthID used to log on to the XDB Server (String)
Password | The password associated with the AuthID (String)
Connection Properties | Data connection properties defined in the URL itself or in a data profile

Comments:

Use Overload 1 if you:

  • Only have a few properties values to set
  • Have defined a data profile in which most of the values of the data connection properties are set
  • Do not want to define a Properties Object
  • Need to change from using the Direct Flight driver to other JDBC drivers in your code

Examples:

Parent topic: Overloads for the DriverManager.getConnection Method


Overload 2

Restriction: This topic applies to Windows environments only.

Parameters:

URL | The XDB Server URL (String)
Connection Properties | The data connection properties defined in a single instance of a Properties Object

Comments:

Use Overload 2 if you have a Java development environment that supports Properties Objects and you have a number of properties that you want to set for each data connection.

In addition to specifying the property values in a Properties Object, you can:

  • Override property values in the URL itself
  • Use predefined property values by specifying the name of a data profile in your Properties Object

Example:

Parent topic: Overloads for the DriverManager.getConnection Method


Overload 3

Restriction: This topic applies to Windows environments only.

Parameters:

URL The XDB Server URL (String)

Comments:

If you need to, you can specify the AuthID and password for logging on to the XDB Server, as well as any other data connection properties, in the URL itself.

You can also include the name of a data profile in the URL.

Parent topic: Overloads for the DriverManager.getConnection Method


Direct Flight URL Syntax

Restriction: This topic applies to Windows environments only.

The Direct Flight URL syntax is the same for all three overloads for the method. The URL is used to call the DriverManager.getConnection method. Your URL must use the following syntax:

jdbc:mf://server-list[/profile][@location][?property-list]

Where the parameters are:

server-list A comma-separated list of XDB Gateway Servers with the following format:
host1[:port1][,host2[:port2],...hostn[:portn]]

Where the parameters are:

server-list A comma-separated list of XDB Gateway Servers with the following format:
host1[:port1][,host2[:port2],...hostn[:portn]]

Where the parameters are:

profile | The name of a data profile defined in the SYSXDB.SYSPROFILES table. The default is the data profile specified in the data profile default property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
location | The name of the XDB location to which the applet or application connects. The default is the location specified in the data profile location property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
property-list An ampersand-separated list of property value pairs with the following format:
prop1=val1[[&prop2=val2]&...propn=valn]

Where the parameters are:

See the section Direct Flight Data Connection Properties for more information on the properties that you can set.

hostx | The DNS name, host name, or IP address of an XDB Server.
portx | The port number of the XDB Server on that machine. The default port for an XDB Server is 8898.
propx | The name of a data connection property.
valx | A valid value for the data connection property.
profile | The name of a data profile defined in the SYSXDB.SYSPROFILES table. The default is the data profile specified in the data profile default property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
location | The name of the XDB location to which the applet or application connects. The default is the location specified in the data profile location property, if one has been specified. See the section Defining a JDBC Data Profile for more information on data profiles.
property-list An ampersand-separated list of property value pairs with the following format:
prop1=val1[[&prop2=val2]&...propn=valn]

Where the parameters are:

See the section Direct Flight Data Connection Properties for more information on the properties that you can set.

Note:

You can add the prefix mf. to any property name in the URL except user and password.

Parent topic: Connecting to an XDB Server
Related information
Defining a JDBC Data Profile
Direct Flight Data Connection Properties


Direct Flight Data Connection Properties

Restriction: This topic applies to Windows environments only.

This section describes the data connection properties that you can set in your Java applet or application. You can specify data connection properties in the URL or in a Properties Object. See the section Connecting to an XDB Server for more information.

  • user
    Sets the AuthID that an applet or application will use to log on to the XDB Server.
  • password
    Sets the password for the AuthID specified in the user property.
  • profile
    Sets the name of the data profile an applet or application will use to retrieve the values of data connection properties defined in the SYSXDB.SYSPROFILES table.
  • profile.location
    Sets the name of the location on the XDB Server where an applet or application will first log on.
  • profile.canoverride
    Determines whether the properties associated with profile can be overridden in the URL or in a Properties Object.
  • profile.default
    Determines whether the entry represents the default profile.
  • maxrows
    Sets the maximum number of rows the Direct Flight driver will return in response to a query.
  • maxfieldsize
    Sets the size of the largest data field the Direct Flight driver will return in response to a query.
  • numthreads
    Sets the number of threads for which the Direct Flight driver will optimize the data connection.
  • timeout
    Sets the number of milliseconds an applet or application will wait for a response from the XDB Server before causing an exception.
  • cache.numrecs
    Sets the maximum number of records that the Direct Flight driver will prefetch for read-only queries.
  • cache.size
    Sets the maximum number of bytes that the Direct Flight driver will prefetch for read-only queries.
  • cache.fetch.numrecs
    Sets the maximum number of records that the Direct Flight driver will fetch in one batch when prefetching records for read-only queries.
  • cache.fetch.size
    Sets the maximum number of bytes that the Direct Flight driver will fetch in one batch when prefetching records for read-only queries.
Parent topic: Connecting to an XDB Server
Related information
Connecting to an XDB Server


user

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Any valid AuthID with access to the data referenced in an applet or application
Default: | None

Comments:

You must specify a value for this property

Parent topic: Direct Flight Data Connection Properties


password

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | The current password for the AuthID specified in the user property. For AuthIDs that have no password, use an empty string as the value for this property.
Default: | None

Comments:

You must specify a value for this property

Parent topic: Direct Flight Data Connection Properties


profile

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Any data profile name with one or more property entries defined in the SYSXDB.SYSPROFILES table in the system location of an XDB Server
Default: | None

Comments:

This property is optional. You can connect to an XDB Server without defining any properties in a data profile.

Parent topic: Direct Flight Data Connection Properties


profile.location

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL, in a Properties Object or in a data profile in the SYSXDB.SYSPROFILES table
Possible Values: | The name of any location on the XDB Server
Default: | SYSTEM

Comments:

Make sure that you specify the correct location as the value for this property. Note that the default location (SYSTEM) is not suitable for most applets and applications.

If you specify the value of this property in a data profile, do not prefix the property name with the name of the profile (profile).

Parent topic: Direct Flight Data Connection Properties


profile.canoverride

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | Only in a data profile in the SYSXDB.SYSPROFILES table
Possible Values: | Yes or no
Default: | Yes

Comments:

You can prevent users setting data connection properties to inappropriate values when they enter the URL, by setting canoverride to "No". If you want to use the canoverride property for this purpose, make sure that all the profiles have canoverride set to "No." If even one profile has canoverride set to "Yes," users can specify that profile and set other data connection properties to any values they choose.

To create a single profile that cannot be overridden, set this property to "No" and make sure that the default property entry is also present.

Do not prefix the property name with the name of the profile (profile).

Parent topic: Direct Flight Data Connection Properties


profile.default

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | Only in a data profile in the SYSXDB.SYSPROFILES table.
Possible Values: | Anything
Default: | The presence of this entry in the table makes its profile the default

Comments:

Make sure that only one data profile includes this property. Using multiple default profiles generates unpredictable results.

Do not prefix the property name with the name of the profile (profile).

Parent topic: Direct Flight Data Connection Properties


maxrows

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of rows) or 0 (all rows – no limit)
Default: | 0 (all rows – no limit)

Comments:

This property and its default value match the JDBC standard. You can reset this limit within the scope of a statement in your code. Each individual statement uses the initial limit specified by the value of this property.

Parent topic: Direct Flight Data Connection Properties


maxfieldsize

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of rows) or 0 (all rows – no limit)
Default: | 0 (all rows – no limit)

Comments:

This property and its default value match the JDBC standard. You can reset this limit within the scope of a statement in your code. Each individual statement uses the initial limit specified by the value of this property.

Parent topic: Direct Flight Data Connection Properties


numthreads

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of threads)
Default: | 4

Comments:

You should set this value to the number of threads you expect to access the XDB Server at the same time, for optimum performance.

If you set numthreads too high, your application will drain system resources. If you set numthreads too low, your application performance will drop.

Parent topic: Direct Flight Data Connection Properties


timeout

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of milliseconds) or -1 (disable timeout)
Default: | 5000

Comments:

This value represents the milliseconds between the time a packet is sent and the time a packet is received.

Parent topic: Direct Flight Data Connection Properties


cache.numrecs

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of records) or -1 (disable limit)
Default: | -1 (disabled)

Comments:

Do not disable both cache.numrecs and cache.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


cache.size

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of bytes) or -1 (disable limit)
Default: | 131072(128K)

Comments:

Do not disable both cache.numrecs and cache.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


cache.fetch.numrecs

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of records) or -1 (disable limit)
Default: | 100

Comments:

Do not disable both cache.fetch.numrecs and cache.fetch.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


cache.fetch.size

Restriction: This topic applies to Windows environments only.

Properties:

Where it can be set: | In the URL or in a Properties Object
Possible Values: | Integer (representing the number of bytes) or -1 (disable limit)
Default: | 8196

Comments:

Do not disable both cache.fetch.numrecs and cache.fetch.size. At least one of these properties must specify a limit. When both limits are enabled, the Direct Flight driver uses the smaller limit.

Parent topic: Direct Flight Data Connection Properties


Defining a JDBC Data Profile

Restriction: This topic applies to Windows environments only.

A data profile is a set of property values defined in one location and referred to, as often as required, by a single profile name. Using property values from a data profile enables you to keep the URL short. This is convenient for development environments where you are required to retype the URL. If you are developing multiple applications, you can use data profiles to centralize your data configurations on one XDB Server and perform all of your maintenance in a single location.

Defining a data profile is optional. You can also set property values in the URL or in a Properties Object, depending on which overload for the DriverManager.getConnection method you use. See the section Overloads for the DriverManager.getConnection Method for more information.

You define a data profile by adding a set of entries to the SYSXDB.SYSPROFILES table in the SYSTEM location of your XDB Server. Each entry in the SYSXDB.SYSPROFILES table defines a profile property. The following data connection properties are available:

  • location
  • canoverride
  • default

You can use the SQL Wizard to alter the SYSXDB.SYSPROFILES table. For instructions on how to alter tables, see the topic Altering a Table in your SQL Wizard Online Reference. To define your data profile:

  1. Choose a name for the data profile. The maximum name length is 32 characters.

    Make sure that you enter the name consistently for each entry you add to the table. The profile name in the table must be the same as the one you specify in the URL when you call the getConnection method.

  2. Add an entry for the location property. Set its value to the name of the XDB Server location where your applet or application will first log on when it is executed.

    A minimal profile definition could consist of just a location entry. All other profile properties have default values.

  3. Add an entry for the canoverride property. Set its value to "No" if you do not want to be able to override the property associated with this profile.

    Ignore this property or set its value to "Yes" if you want to be able to override these values in the URL or in a Properties Object.

  4. Add an entry for the default property, if you want this data profile to be the default profile.

    You do not need to specify a value for the default property.

Note:

Do not add the prefix mf. to any of the properties defined in a data profile.

You can prevent a specific profile from being overridden by setting its canoverride property value to "No" and ensuring that the default property is also present. If you specify multiple profiles, make sure that all canoverride values are set to "No". For example:

Profile Name | Property name | Property Value
DEF | location | PASSTHRU
DEF | canoverrride | no
DEF | default | yes

If you add a second profile and leave its canoverride value set to "Yes" (the default), it will defeat the purpose of the first profile. In the following example, a user could specify the ALT profile and successfully override the data connection properties of the DEF profile in the URL:

Profile Name | Property name | Property Value
DEF | location | PASSTHRU
DEF | canoverrride | no
DEF | default | yes
ALT | location | ALTERNATE
ALT | canoverride | yes
Parent topic: Connecting to an XDB Server
Related information
Overloads for the DriverManager.getConnection Method


Calling COBOL Stored Procedures

Restriction: This topic applies to Windows environments only.
Restriction: This topic applies to Windows environments (local development) only.

You can augment your Java code by calling stored procedures written in COBOL. You can execute stored procedures with the XDB Server running either in the blue screen character mode or as a service. For information on setting up stored procedures using XDB Server, see the section Stored Procedures in your SQL Reference.

The demonstration program mfExample3.java, located in your %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples\mfsql\demo directory, demonstrates calling the COBOL stored procedure salraise.cbl. Consult the JDBCDEMO readme.txt file for detailed instructions on running the program.

Parent topic: JDBC


Migrate Utility

Restriction: This topic applies to Windows environments only.

Migrate provides an easy, interactive way to copy one or more data tables between XDB Server locations or between an XDB Server location and a DB2 subsystem. You can use Migrate to quickly download a copy of a table from a mainframe for development and testing purposes. Or, you can use it to regularly copy up-to-date information from a production database on an XDB Server to a DB2 database on the mainframe.

Migrate simplifies the process of copying data from one location or database to another by eliminating intermediate file transfers and by eliminating the hand-editing of indexes and foreign keys. With Migrate, you can copy keys, indexes and tables in a single step. You can also quickly copy a subset of a table (certain columns or rows) by extracting data with a SELECT statement.

For complex migrations, you can use the Migrate utility's referential-integrity feature to detect data dependencies automatically and copy tables in the correct order. You can also produce a preliminary "impact analysis" report, which describes the effect of a migration before it is performed. If you copy certain tables regularly, you can save the specification in a .mig file. You can then run this file in batch mode, enabling you to perform a migration without respecifying it manually.

If your system administrator has configured the mainframe connectivity facilities of SQL Option, you can use the Migrate utility to import or export data between XDB locations, or between an XDB location and a DB2 subsystem.

  • Migration Paths Overview
  • To migrate between XDB Servers
  • To migrate between an XDB Server and a mainframe
  • Catalog Browser Overview
  • Schema Viewer Overview
  • Generating Reports
  • The Impact Analysis Report
  • The Post Execution Analysis Report
  • The Error File
Parent topic: SQL Option User Guide


Migration Paths Overview

Restriction: This topic applies to Windows environments only.

Migrate lets you copy data between the following kinds of locations:

  • Mainframe to Mainframe
  • Mainframe to Server
  • Server to Mainframe
  • Server to Server
Parent topic: Migrate Utility


To migrate between XDB Servers

Restriction: This topic applies to Windows environments only.

Migrate can copy data between any locations that are accessible to the server to which you are connected. To migrate tables between two XDB Servers, the server you log onto must have access to the other server via server-to-server communications. For information about establishing server-to-server connectivity, see your XDB Server Administration Guide.

Parent topic: Migrate Utility


To migrate between an XDB Server and a mainframe

Restriction: This topic applies to Windows environments only.

To migrate tables between a mainframe and an XDB Server, XDB Link must be installed on at least one of the XDB Servers to which you have access. See the XDB Link documentation for information about setting up a mainframe location for remote access.

Parent topic: Migrate Utility


Catalog Browser Overview

Restriction: This topic applies to Windows environments only.

The Catalog Browser graphically represents XDB Server database objects. In Migrate, you use the Catalog Browser to select the table(s) you want to copy, or to recall a query that you have created and saved with a data management tool such as SQLWizard.

The Catalog Browser shows you all of the locations that are known to the server to which you are connected (even locations that are on another server or on a mainframe). Database objects, such as locations, tables and indexes, are graphically represented in a hierarchical structure. Using the + and - buttons, you can expand and collapse the hierarchy to show just the elements you want to work with.

Note:

If you don't see the location that you want to migrate tables to or from, use Options to verify that you are connected to the correct server. If your server connection is correct, verify that the locations are listed in the server's SYSIBM.SYSLOCATIONS table. Your server must have access to both the source and target locations. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about setting up server-to-server communications.

Parent topic: Migrate Utility


Schema Viewer Overview

Restriction: This topic applies to Windows environments only.

The Schema Viewer displays the schemas of tables selected for migration. If related tables are contained in the viewer, they are connected with arrowed lines.

You can add tables to the Schema Viewer by dragging them from the Catalog Browser (see The Catalog Browser). To remove a table from the Schema Viewer, select the table in the Schema Viewer, then choose the Remove command from the Object menu.

Parent topic: Migrate Utility


Generating Reports

Restriction: This topic applies to Windows environments only.

Migrate can create selected reports during a migration. Reports are written to files that you specify in the Run dialog box. You can display a report by selecting it from the View menu. Once a report is open, you can print it using the Print command on the File menu.

Parent topic: Migrate Utility


The Impact Analysis Report

Restriction: This topic applies to Windows environments only.

The Impact Analysis Report describes the schemas of the selected source and destination tables, and lists the options you have selected. You can use this report to review your specifications before you run a migration.

To create an Impact Analysis Report, select the Impact Analysis Report option in the Migrate Options dialog box before you run the migration. Type the name of the file to which you want the report written in the text-entry field next to the checkbox. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

Note:

When an Impact Analysis Report is selected, Migrate does not execute the migration. It simply describes what would happen if it were performed.

To view the report after it has been generated, select the Impact Analysis command on the View menu. Migrate automatically displays the last Impact Analysis file specified. To display a report other than the last one, specify the file with the Migrate command on the Options menu before you select the Impact Analysis command.

If you want to print the report once it is displayed, choose Print from the File menu.

The following is an example of an Impact Analysis Report.

                   IMPACT ANALYSIS REPORT

  Generated: 07/09/1996

                   Source               Destination
                   --------------       -------------
  Location:        SALES                SALES

    Table:
      Name:        CUSTOMERS            CUSTOMERS
      Authid:      DEV001               DEV001
      Database:
      Tablespace:

      Definition:
         Migrate:  Yes                  *
         Columns:  name(CHAR(20))       name(CHAR(20))
                   city(CHAR(20))       city(CHAR(20))
                   state(CHAR(2))       state(CHAR(2))

      Primary Key: CKEY                 CKEY
          Migrate: No
          Columns: NAME                 NAME

      Comments:
          Migrate: No
      Src Table Comment:
      Dst Table Comment:

      Synonyms:
          Migrate: No

      Privileges:
          Migrate: No
Parent topic: Migrate Utility


The Post Execution Analysis Report

Restriction: This topic applies to Windows environments only.

The Post Execution Analysis Report provides a listing of the tables that were copied during a migration. It also reports the source and destination locations of those tables.

To create a Post Execution Analysis Report, select the Post Execution Report checkbox in the Run dialog box when you execute your migration. Type the name of the file to which you want the report written in the text-entry field next to the checkbox. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

Note:

You can specify the same filename for the Post Execution Analysis and the Error File to combine both reports into a single file.

To view the report after a migration has been executed, open the file using the Post Execution Analysis command on the View menu. Migrate automatically displays the last Post Execution file specified. To display a report other than the last one, specify the file with the Migrate command on the Options menu before you select the Post Execution Analysis command.

If you want to print the report once it is displayed, choose Print from the File menu.

The following is an example of a Post Execution Analysis Report.

                   POST EXECUTION REPORT

  Generated: 07/09/1996

                   Source              Destination
                   --------------      -------------
  Location:        SALES               TEST

    Table:
      Name:        CUSTOMERS           CUSTOMERS
      Authid:      DEV001              DEV001
      Database:
      Tablespace:

  Table created at 13:00:39 on 7/9/1996
  156 records inserted
Parent topic: Migrate Utility


The Error File

Restriction: This topic applies to Windows environments only.

The Error File reports the number and type of errors detected while migrating your tables. An error file is created each time you select it in the Run dialog box; however, it will contain errors only if errors were generated by a migration.

To request an error file, select the Error File checkbox in the Run dialog box when you execute your migration. Type the name of the file to which you want the report written in the text-entry field next to the checkbox. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

Note:

You can specify the same filename for the Error File and the Post Execution Analysis to combine both reports into a single file.

To view the error file after a migration has been executed, open the file using the Error File command on the View menu. Migrate automatically displays the last Error File specified. To display a report other than the last one, specify the file with the Migrate command on the Options menu before you select the Error File command.

If you want to print the report once it is displayed, choose Print from the File menu.

Parent topic: Migrate Utility


Options Utility

Restriction: This topic applies to Windows environments only.

Use the Options utility for configuring the SQL Option client-side software and its connectivity with XDB and DB2 database servers.

The settings that you can change fall into the following categories:

  • Connect

    For configuring the connection between a client application (for example, SQL Wizard or a program that you have developed) and the XDB or DB2 database that it uses.

  • Paths

    For specifying where SQL Wizard and other SQL Option files are to be found or written.

  • Format

    For specifying formats for dates, times and numeric fields.

  • Multi-user

    For specifying options for a multi-user XDB Server in a networked environment. For example, you can control isolation levels and autocommit.

  • Browser

    For specifying which database objects are shown in the Catalog Browser window.

  • Query

    For specifying default options for working with queries. For example, you can specify whether unqualified table-names can be used and whether Cartesian products are permitted. These options can be overridden for a particular query when you are editing the query.

  • Query run

    For specifying options for running queries with SQL Wizard. For example, you can control whether the result is displayed in table or form view and limit the number of rows returned.

  • SQL

    For specifying defaults for various SQL operational parameters, including compatibility and sort sequence. For example, you can set DB2 or SQL/DS compatibility and whether to use ASCII or EBCDIC sort sequences. You can also set the escape character and SysAuthID.

  • Security

    For specifying security options. You can switch on client security (required if you want to use an XDB Server that has security switched on), as well as controlling the enforcement criteria for user passwords.

The Options utility has a Summary page that enables you to obtain a list of all the current configuration settings. You cannot make changes to any of the options from the Summary tab but you can print it for reference purposes.

To access the Options utility from the main menu, Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Client Options.

The Options window is made up of several pages, each labeled with a tab. To view or change information on a particular page, click its tab.

The options that you select are stored in the xdb.ini file.

To ensure backward compatibility, the settings are also written to the config.xdb file. These files are usually found in your configuration directory. For more information about xdb.ini, see xdb.ini File Structure.

Note: If SQLWizard is running when you change your preferences using Options, you must exit from SQLWizard and restart it before the changes take effect.

Along the left edge of the window is a set of general-purpose buttons. Depending upon which tab you are working in, some or all of these buttons will be available to you.

OK | This button accepts the current configuration and writes the settings to the xdb.ini and CONFIG.XDB files, and any other configuration files used by your system. Exits Options.
Cancel | This button discards the changes made during the current session and exits Options.
Browse | This button becomes active when your cursor is in a field requiring a path, filename or location. Clicking Browse provides a dialog box for you to select a name.
Edit | This button is displayed when the current tab offers editable fields such as formats for days or months.
Help | This button displays a help window containing information about the current tab.
  • Picture Definitions Overview
  • US ASCII Table
  • xdb.ini File Structure
Parent topic: SQL Option User Guide
Related concepts
XDB xa_open string
Related information
xdb.ini File Structure


Picture Definitions Overview

Restriction: This topic applies to Windows environments only.

The Options utility permits you to define input and display pictures to be used as the default masks for various types of columns.

Note that once a format has been defined for a data type or a variable, the system will not accept values that are not consistent with or are outside the range defined by the picture. For numeric fields, enter masks to handle the largest values you expect to enter and display.

  • Numeric Masks Overview
  • Numeric Picture Characters
  • Numeric Picture Examples
  • Date Pictures Overview
  • Date Picture Elements
  • Date Picture Examples
  • Time Pictures Overview
  • Time Picture Elements
  • Time Picture Examples
  • Character Strings Overview
  • Character Picture Examples
Parent topic: Options Utility


Numeric Masks Overview

Restriction: This topic applies to Windows environments only.

All numeric masks (that is: smallint, int, float, decimal and money) are defined in the same way. The basic format for a numeric mask is:

mask [$='money'] [.='decimal'] [,='grouping']

where:

mask is a picture that defines the appearance of the variable when displayed on the screen or sent to the printer.

money is a money symbol (enclosed in single quotes) to be substituted for a dollar sign in numeric pictures. The money clause is optional. Money symbols can be up to five characters long. For example, to use the money symbol DM in place of a dollar sign, use:

$='DM'

decimal is a decimal point character (enclosed in single quotes) to be substituted for a period in numeric pictures. The decimal clause is optional. The grouping character and decimal point character cannot be the same. For example, to use a comma as the decimal point character, and a period as a grouping character, you would use:

.=',' ,='.'

grouping is a grouping character (enclosed in single quotes) to be substituted for a comma in numeric pictures. This clause is optional. The grouping character and decimal point character cannot be the same, as demonstrated in the example above.

Note that the optional money, decimal and grouping clauses are used only for numeric variables. If omitted, the default will be the money, decimal and grouping symbols specified through the Options utility. When defining decimal masks, keep in mind that precision refers to the total number of digits (before and after the decimal place) and scale is the number of digits to the right of the decimal point. For example decimal (10,4) allows six digits to the left of the decimal point, and four digits to the right of the decimal point.

To use a character that does not appear on your keyboard in your edit mask, use the facilities provided by your operating environment for entering extended characters. For example:

  • In DOS, hold down Alt key while entering the ASCII decimal code for the character on your numeric keypad. In US ASCII, the >= symbol is created by holding down Alt key while pressing 156. (For a list of decimal codes for US ASCII, see the US ASCII Table.)
  • In Windows, use the Character Map application from the Accessories window to select special characters.

Given the picture:

$$,$$$,$$9.99 $='>='

the value 23456.78 is displayed as >=23,456.78.

For additional information, see Numeric Picture Characters.

Parent topic: Picture Definitions Overview


Numeric Picture Characters

Restriction: This topic applies to Windows environments only.

The following table describes the special characters that can be used when defining numeric pictures. Some numeric masks are illustrated in Numeric Picture Examples.

Picture | Result
+ | Indicates position of the minus or plus sign. Sign is placed as close to significant digits as possible. If z, 9, or $ appear after +, the sign will never be closer to the decimal place than the last + sign.
- | Same as + except signs are not displayed.
9 | Indicates a digit. Leading zeroes are displayed.
z | Indicates a digit. Leading zeros are replaced with blanks to allow alignment of decimal points and money symbols. (Lower case z only.)
. | Indicates the position of the decimal point. To use a different symbol for the decimal point (a comma, for example), use the period in the picture, but redefine the decimal point character by adding the .= decimal clause (for example: .=',').
, | Comma indicates relative position of grouping character. Grouping length is counted from the right, beginning with the first nonfractional digit. Only the grouping character closest to the decimal point is required. To use a different symbol for the grouping character (for example `.'), use the comma in the picture, but redefine the grouping character by adding the ,=grouping clause (for example: ,='.').
$ | Indicates the position of the money symbol. When several dollar signs appear together ($$,$$$.99 for example) the dollar sign will be shown next to the left-most digit (or decimal point) displayed. Using the example picture, the variable value 12.34 will therefore be displayed as $12.34. To use a different money symbol (>= for example), Use the dollar sign in the picture, but then redefine the money symbol by adding the $=money clause to the PICTURE command ($='>=' for example).
r | Indicates the number is to be rounded. If used, must appear at very end of the mask (zz,zz9.99+r for example).
Parent topic: Picture Definitions Overview


Numeric Picture Examples

Restriction: This topic applies to Windows environments only.

The following table shows the effect of various numeric picture formats.

Picture | Input | Output
9999 | 123 | 0123
zzz.99 | 13.456 | 13.45
zz99 | 123 | 123
+999.99 | -13.4 | -013.40
++++.99 | -013.4 | -13.40
+zz99.9 | -13.456 | - 13.4
+++z9.9 | -130.456 | -130.4
zzz.9r | -13.456 | -13.5
+++.99r | 13.456 | 13.46
+999.99r | -13.456 | -013.46
$999.99 | 40 | $040.00
$$$$.99 | 40 | $40.00
$$$$.99+ | -40 | $40.00-
$$$$$,$$9.99 $='£' | 13.456 | £13.45
zzzzz,zz9 ,='.' | 12345 | 12.345
Parent topic: Picture Definitions Overview


Date Pictures Overview

Restriction: This topic applies to Windows environments only.

A Date picture contains the components used to define date display pictures. You may order the Day, Month, Year and Weekday components any way you like (for example: dd/mm/yy, mm/dd/yy, yy/mm/dd). You can include characters to separate the components. Data must be entered according to the picture format, with a day and year component required.

The strings used for the mmm and mmmm month and www and wwww weekday pictures are defined on the Options utility's FORMAT tab. Separators can be any other characters, and will be displayed in the relative position they occupy in the mask. Commonly used separators are slash (/), hyphen (-), space ( ), and comma (,). In procedures, a date cannot consist of simply a month component.

For additional information, see Date Picture Elements.

Parent topic: Picture Definitions Overview


Date Picture Elements

Restriction: This topic applies to Windows environments only.

The following table describes the elements that can be included in a Date Picture. Examples are shown in Date Picture Examples.

Clause | Picture | Result
Day | d | Integer between 1 and 31, corresponding to day of month. Does not display leading zeroes.
 | dd | Integer between 1 and 31, corresponding to day of month. Displays leading zeroes.
 | ddd | Integer between 1 and 365 (366 in a leap year), corresponding to number of days since first of the year. Does not display leading zeroes.
Month | m | Integer between 1 and 12, corresponding to a month. Note that this format does not display leading zeroes.
 | mm | Integer between 1 and 12, corresponding to a month. Displays leading zeroes.
 | mmm | A three character abbreviation for the month corresponding to stored month number (for example: JAN, FEB, MAR,...).
 | mmmm | Month corresponding to the stored month number (for example: January, February, March,...).
Year | yy | Displays last two digits of stored year.
 | yyyy | Displays the stored year.
Weekday | ww | An integer corresponding to the day of the week (Monday=1, Tuesday=2, etc.)
 | www | Three-character abbreviation for the day of the week (for example: MON, TUE, WED,...).
 | wwww | The day of the week a date falls on.
Parent topic: Picture Definitions Overview


Date Picture Examples

Restriction: This topic applies to Windows environments only.

The following examples show various date pictures using the date August 31, 1995:

Date Picture | Displayed Date
m/d/yy | 8/31/95
mm/dd/yy | 08/31/95
mm/dd/yyyy | 08/31/1995
dd-mm-yy | 31-08-95
yyyy-mm-dd | 1995-08-31
mmm-dd-yyyy | AUG-31-1995
mmmm dd, yy | August 31, 1995
yyddd | 95242
dd | 31
wwww, mmmm dd | Monday, August 31
mmm 'yy | AUG '95
wwww | Monday
Parent topic: Picture Definitions Overview


Time Pictures Overview

Restriction: This topic applies to Windows environments only.

A Time Picture contains the components used to define time pictures. You can use optional separators to separate the Hour, Minute and Second components.

Data must be entered according to the picture format, with an hour and minute component required. Midnight is 12:00:00 am for 12 hour clocks, and 24:00:00 for 24 hour clocks. One second after midnight is 12:00:01 am for 12 hour clocks, and 00:00:01 for 24 hour clocks.

Separators can be any other characters, and will be displayed in the relative position they occupy in the mask.

Commonly used separators are colon (:), hyphen (-), and period (.).

For 12 hour clocks, you can include the characters AM in your picture in the location you want AM or PM to appear. Use the case you want used in the display.

For a 24 hour clock, place the number 24 at the end of the picture. For a 12 hour clock, place the number 12 at the end of the picture. If you do not specify the clock type, a 24 hour clock is assumed, unless you have set the default time format to a 12 hour clock through the Options utility. Note that in procedures a time picture cannot consist of a minute component alone.

For additional information, see Time Picture Elements.

Parent topic: Picture Definitions Overview


Time Picture Elements

Restriction: This topic applies to Windows environments only.

The following table describes elements of a Time picture. Examples are shown in Time Picture Examples.

Clause | Picture | Result
Hour | h | An integer between 0 and 24 (inclusive), corresponding to the hour of the day. Does not display leading zeroes
 | hh | An integer between 0 and 24 (inclusive), corresponding to the hour of the day. Displays leading zeroes.
Minute | m | An integer between 0 and 59 (inclusive), corresponding to a number of minutes. Does not display leading zeroes.
 | mm | An integer between 0 and 59 (inclusive), corresponding to a number of minutes. Displays leading zeroes.
Second | s | An integer between 0 and 59 (inclusive), corresponding to a number of seconds. Does not display leading zeroes.
 | ss | An integer between 0 and 59 (inclusive), corresponding to a number of seconds. Displays leading zeroes.
Parent topic: Picture Definitions Overview


Time Picture Examples

Restriction: This topic applies to Windows environments only.

The following examples show some time format masks and the resulting output, using the time 15:08:25.

Clock Format | Time Picture | Displayed Time
12 hour clock | hh:mm:ss am 12 | 03:08:25 pm
 | hh.mm 12 | 03.08
 | AM h-m-s 12 | PM 3-8-25
24 hour clock | hh:mm:ss 24 | 15:08:25
 | hh.mm 24 | 15.08
 | h-m-s 24 | 15-8-25
Parent topic: Picture Definitions Overview


Character Strings Overview

Restriction: This topic applies to Windows environments only.

Character pictures are defined using the special characters. Character Picture Examples, contains examples.

Picture | Result
x | Any character can be displayed or entered in this position. A positive integer n, in parentheses after the `x' indicates the string can be up to n characters long.
u | Alphabetic characters in this position are to be displayed in upper case. Adding a positive integer n, in parentheses after the `u' forces the next n characters to be displayed in upper case, and limits the length of the string to n characters.
l | Alphabetic characters in this position are to be displayed in lower case. Adding a positive integer n in parentheses after the `l' forces the next n characters to be displayed in lower case, and limits the length of the string to n characters.
9 | Indicates a digit from 0 to 9.
Parent topic: Picture Definitions Overview


Character Picture Examples

Restriction: This topic applies to Windows environments only.

The following table contains examples of Character Pictures. All examples use the string "Example String 10" as input.

Picture | Displayed String
x(5) | Examp
x(16) | Example String 1
u(5) | EXAMP
u(17) | EXAMPLE STRING 10
l(5) | examp
l(17) | example string 10
u(2)x(15) | EXample string 10
u(2)x(13)99 | EXample string 10
Parent topic: Picture Definitions Overview


US ASCII Table

Restriction: This topic applies to Windows environments only.

The following table shows the US ASCII character set and codes (in decimal).

Note that the first 32 ASCII codes usually are nonprintable; they have alternate meanings as special signal codes. The first 32 ASCII codes cannot be used for picture definitions.

ASCII | Char | ASCII | Char | ASCII | Char | ASCII | Char
0 | NUL | 32 | space | 64 | @ | 96 | `
1 | SOH | 33 | ! | 65 | A | 97 | a
2 | STX | 34 | " | 66 | B | 98 | b
3 | ETX | 35 | # | 67 | C | 99 | c
4 | EOT | 36 | $ | 68 | D | 100 | d
5 | ENQ | 37 | % | 69 | E | 101 | e
6 | ACK | 38 | & | 70 | F | 102 | f
7 | BEL | 39 | ' | 71 | G | 103 | g
8 | BS | 40 | ( | 72 | H | 104 | h
9 | HT | 41 | ) | 73 | I | 105 | i
10 | LF | 42 | * | 74 | J | 106 | j
11 | VT | 43 | + | 75 | K | 107 | k
12 | FF | 44 | , | 76 | L | 108 | l
13 | CR | 45 | - | 77 | M | 109 | m
14 | SO | 46 | . | 78 | N | 110 | n
15 | SI | 47 | / | 79 | O | 111 | o
16 | DLE | 48 | 0 | 80 | P | 112 | p
17 | DC1 | 49 | 1 | 81 | Q | 113 | q
18 | DC2 | 50 | 2 | 82 | R | 114 | r
19 | DC3 | 51 | 3 | 83 | S | 115 | s
20 | DC4 | 52 | 4 | 84 | T | 116 | t
21 | MAK | 53 | 5 | 85 | U | 117 | u
22 | SYN | 54 | 6 | 86 | V | 118 | v
23 | ETB | 55 | 7 | 87 | W | 119 | w
24 | CAN | 56 | 8 | 88 | X | 120 | x
25 | EM | 57 | 9 | 89 | Y | 121 | y
26 | SUB | 58 | : | 90 | Z | 122 | z
27 | ESC | 59 | ; | 91 | [ | 123 | {
28 | FS | 60 | < | 92 | \ | 124 | |
29 | GS | 61 | = | 93 | ] | 125 | }
30 | RS | 62 | > | 94 | ^ | 126 |
31 | US | 63 | ? | 95 | _ | 127 | 
Parent topic: Options Utility


xdb.ini File Structure

Restriction: This topic applies to Windows environments only.

Sample xdb.ini File

Below is an example xdb.ini file. You will make most of the changes to this file through the Options utility. Do not change any of the sections that contain a warning not to change them. In most cases such changes will have no effect on the system. You must change such settings through the Options utility.

[CLIENT]
XDBCFG=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\
[SERVER]
XDBSERVE=XDBLOCAL
XSRVCFG=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg
[ConnectionDefaults]
AutoConnect=On
Protocol=Win32Local,NetBIOS,TCP/IP
ProtocolMap=64,1,8
Servers=XDBLOCAL
DefaultServerName=XDBLOCAL
NodeName=cXDBCLIENT
[ClientFormats]
DateFormat=ISO
DatePicture=yyyy-mm-dd
TimeFormat=ISO
TimePicture=hh.mm.ss 24
MoneyPicture=-$$$$$$$$$,$$9.99
DecimalPicture=-zzzzzzzzz,zz9.99
WeekdayPicture=WWW
FloatDecimalPlaces=2
TimeZone=0
ShortMonthNames=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec
LongMonthNames=January,February,March,April,May,June,July,August,September,October,November,December
ShortWeekNames=Mon,Tue,Wed,Thu,Fri,Sat,Sun
LongWeekNames=Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday
[MultiUser]
IsolationLevel=Cursor Stability
TimeOutInterval=10
AutoCommit=On
BackwardLog=Off
ForwardLog=Off
[Preferences]
Confirm=NO
SortMode=US (Portuguese,Dutch) EBCDIC
SortSequence=EBCDIC
AbortCharacter=<27>
EscapeCharacter=`
CompatibilityMode=DB2
CobolLiterals=Default
DynamicSqlLiterals=Default
CommaDecimal=0
SQLPath=
[QueryRunOption]
MaxRecords=ALL
Execute=First Command
ResultView=Table
AllowEditing=Off
AutoCommit=On
NoLookForPrimaryKey=Off
ShowPositiveSqlcode=Off
HighlighNulls=Red
UseHex=Off
NoDispEmptyResult=Off
ReadOnlyAlert=Off
[QueryDefinition]
QueryUsing=3PartName
ProhibitCartesian=On
ShowTablename=Off
AutoJoinForeignKey=On
AutoJoinPrimaryKey=Off
AutoJoinLikeName=Off
[Browser]
ConfigType=-560
AutoRefresh=Off
AutoStartup=On
[SysAuthID]
SysIBM=SYSIBM
SysXdb=SYSXDB
[Security]
ClientSecurity=Off
PasswordEnforceLevel=1
[ClientPaths]
Executables=C:\Program Files (x86)\Micro Focus\Enterprise Developer\bin\
Application=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\
System=SYSTEM
Temporary=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\tmp\
Overflow=C:\ProgramData\Micro Focus\Enterprise Developer\mfsql\cfg\tmp\
[Connection XDBLOCAL]
Protocol=Win32Local
PrimaryAuthorizationID=TUTORIAL
CurrentLocation=SYSTEM

File Structure

The xdb.ini file contains values used by Micro Focus client applications (such as SQLWizard). It specifies which Server you will use, what protocol will be used, and other default values. You set set these values using Options before you start your client program.

All of the changes you will make to xdb.ini should be made through the Options utility, accessible from the Options icon in the Micro Focus group window. There are comments in xdb.ini indicating those sections that should not or cannot be edited by hand. Some of these items are actually duplicates of values found in other configuration files, maintained in xdb.ini to ensure backward compatibility with older products. Others have too many choices to be edited easily.

However, there are some parameters that must be edited by hand. xdb.ini is a text file that can be edited with any standard text editor.

Note: If xdb.ini is locked or in use by some other program (such as a text editor), SQLWizard (or your own client application program) will not operate correctly. In this case, when you start SQLWizard (or the clinet application), you will get an error that xdb.ini cannot be found. If you try to run queries, you will get no records back. To avoid this problem, make certain that xdb.ini is not being held open by some other program.

Each of the sections described below corresponds to an SQLWizard-related section of xdb.ini. There may be other sections in your xdb.ini file. These are used by other products, and are described in the related documentation.

For items that provide a choice of settings, the default is shown in bold.

[ConnectionDefaults]

The Connection Defaults section stores information about what to use as the default connection, and also about what protocols are available.

Servers=server1, server2

The Servers item lists all servers that you can access. When a new server becomes available, the server name is added to this list. Each server should have a corresponding [Connection server-name] section.

NodeName=client-name

This is the name by which your machine is known to all XDB Servers you use. This name should be unique among all machines that are trying to access any XDB Server or XDB Link on your network.

DefaultServerName=server-name

This is the name of the XDB Server you want to use.

AutoConnect=On|Off

If on, the Connect dialog box is not displayed when you start SQLWizard (unless security is also on). If off, the Connect dialog box will be displayed so that you can specify a Server, AuthID and Location when connecting.

Protocol=protocol1, protocol2
ProtocolMap=n1,n2

If you are running SQLWizard against an XDB Server Version 4 (or newer), you may need to add several values (separated by commas) to the Protocol and ProtocolMap parameters in the [ConnectionDefaults] section of your xdb.ini file. The xdb.ini file segment shown below adds TCP/IP and IPX/SPX protocol support to SQLWizard:

[ConnectionDefaults]
Protocol=local,netbios,tcpip,spx
ProtocolMap=32,1,8,4

The table below shows allowable values for the Protocol and ProtocolMap parameters:

Protocol | ProtocolMap
netbios | 1
namedpipes | 2
spx | 4
tcpip | 8
appc | 16
local | 32
win32local | 64
[ClientPaths]

The paths in this section of xdb.ini correspond to the paths that you set on the Paths tab of the Options utility. For more complete descriptions of these options, see Paths Tab.

Executables=default-directory

Path to the directory where executables are stored.

Application=application-path\

Path to the directory where the system should write or look for application files such as SQL scripts and import/export batch files.

Temporary=temporary-path\

Path to the directory where SQLWizard writes temporary files, such as temporary query result files.

Overflow=alternate-temporary-path

Not currently used. An alternative directory where SQLWizard can write temporary files.

System=system-location

The name of the system location.

[ClientFormats]

This section of xdb.ini corresponds to the items that you set on the Formats tab of the Options utility. For more complete descriptions of these options, see Format Tab.

DateFormat=USA|EUR|ISO|JIS|LOCAL

Indicates the default date format to be used when displaying or entering dates.

DatePicture=dd.mm.yyyy

Indicates the date picture to be used if DateFormat is set to LOCAL. See Date Pictures Overview for a description of the date picture format.

TimeFormat=USA|EUR|ISO|JIS|LOCAL

Indicates the time format to be used when displaying or entering dates.

TimePicture=hh.mm.ss 24

Indicates the time picture to be used if TimeFormat is set to LOCAL. See Time Pictures Overview for a description of the time picture format.

MoneyPicture=-$$$$$$$$$,$$9.99

The money picture to be used when displaying or entering monetary amounts. See Numeric Masks Overview for a description of the money picture format.

DecimalPicture=-zzzzzzzzz,zz9.99

The decimal picture to be used when displaying or entering decimal numbers. See Numeric Masks Overview for a description of the decimal picture format.

WeekdayPicture=WWW

The format to be used when displaying or entering weekdays. See the Date Picture Elements for the weekday picture format.

FloatDecimalPlaces=2

Number of decimal places to be displayed for float fields.

TimeZone=0

The timezone offset from Greenwich Mean time. This is used for time math.

ShortMonthNames=Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec

The strings to be used for the MMM formatted month portion of the date format.

LongMonthNames=January,February,March,April,May,June,July,August,September,October,November,December

The strings to be used for the MMMM formatted month portion of the date format.

ShortWeekNames=Mon,Tue,Wed,Thu,Fri,Sat,Sun

The strings to be used for the WWW formatted weekday portion of the date format.

LongWeekNames=Monday,Tuesday,Wednesday,Thursday,Friday,Saturday,Sunday

The strings to be used for the WWWW formatted weekday portion of the date format.

[MultiUser]

This section of xdb.ini corresponds to the items that you set on the Multiuser tab of the Options utility. For more complete descriptions of these options, refer to the Multiuser Tab.

IsolationLevel=Lock Current

Indicates the isolation level to be used by default.

AutoCommit=On|Off

Indicates whether AUTOCOMMIT should by default be turned on or off.

TimeOutInterval=n

Indicates (in seconds) how long to wait before retrying when a lock conflict occurs.

BackwardLog=On|Off

Indicates whether the Backward Log is on or off. Not used when accessing an XDB Server Version 5.0 or higher.

ForwardLog=On|Off

Indicates whether the forward log (used for recovery) is on or off. Ignored by remote XDB Servers (Win3.x).

[Preferences]

This section of xdb.ini corresponds to the items that you set on the SQL tab of the Options utility. For more complete descriptions of all of these options, refer to the SQL Tab.

Other xdb.ini items that correspond to items on the SQL tab are described later in the description of the [SysAuthID] section.

CompatibilityMode=DB2|XDB|ANSI

The SQL compatibility mode to be used. This option indicates which set of SQL rules will be enforced.

EscapeCharacter=`

The character used to precede a special character to turn it into a literal.

AbortCharacter=<27>

The character used to halt some operations. For future use.

SortSequence=Case Insensitive ASCII (A=a,...)

Specifies the sort sequence that is to be used as the default for creating a location.

[QueryRunOption]

This section of xdb.ini corresponds to the items that you set on the Query Run tab of the Options utility. For more complete descriptions of these options, refer to the Query Run Tab.

MaxRecords=ALL|n

Indicates if all records should be retrieved or only the first n records when a query is run.

Execute=All Command|First Command|Current
     Command

Indicates if only the first, the current, or all commands in the current query window should be executed. The ALL and FIRST options apply to the SQL Edit window and batch SQL scripts. The CURRENT option applies only to the SQL Edit window.

ResultView=Table|Form

Indicates whether the default Result view should be a RESULT TABLE or a RESULT FORM window.

AllowEditing=On|Off

Indicates whether the system should by default try to go into Edit Mode when displaying a query result. If off, you must switch to Edit Mode yourself.

NoLookForPrimaryKey=On|Off

Specifies whether, during an edit-mode query, SQLWizard automatically searches the SYSINDEX and SYSKEYS tables and adds unique key fields to the query, even if the user has not explicitly selected them. Such action allows SQLWizard to generate the appropriate WHERE clause should the user subsequently choose to update any of the extracted data.

On certain databases (such as large DB2 3.x locations without a shadow catalog), the search for unique key fields can result in extremely long query times.

If your database has been designed so that a unique key is always selected, this option can be turned on to eliminate the search for unique keys, thereby improving performance.

AutoCommit=On|Off

Indicates whether AUTOCOMMIT should be on or off.

[QueryDefinition]

This section of xdb.ini corresponds to the items that you set on the Query tab of the Options utility. For more complete descriptions of these options, refer to the Query Tab.

QueryUsing=3PartName|2PartName|1PartName

Indicates if table names should be qualified when they are inserted into queries or dragged to the SQL Edit window from the Catalog Browser.

ShowTablename=On|Off

Indicates whether the default for the Query Design window should be to show table names in the Query Conditions Grid. If on, table names are shown.

ProhibitCartesian=On|Off

Indicates whether the default for prohibiting Cartesian products should be on or off.

AutoJoinForeignKey=On|Off

Indicates if tables should be automatically joined on foreign key relationships.

AutoJoinPrimaryKey=On|Off

Indicates if tables should be automatically joined on primary keys and columns with like names in another table.

AutoJoinLikeName=On|Off

Indicates if tables should be automatically joined on like column names. Turn off with care!

[Browser]

This section of xdb.ini corresponds to the items that you set on the Browser tab of the Options utility. For more complete descriptions of these options, refer to the Browser Tab.

ConfigType=n

Modify this option only through Options.

AutoRefresh=Off|On

Not currently used. Always off

AutoStartup=On|Off

If on, the Catalog Browser is automatically loaded when SQLWizard is started (you may want to do this to make SQLWizard load faster). If off, you must access the Catalog Browser through the View menu.

[SysAuthID]

This section of xdb.ini corresponds to the items that you set in the SysAuthID section of the SQL tab of the Options utility. Other xdb.ini items that correspond to items on the SQL tab are described previously in the description of the [Preferences] section. If you receive errors when you try to connect to DB2, you should suspect that you do not have privileges on the system catalog tables or views with the AuthIDs currently set. For more complete descriptions of all of these options, refer to the SQL Tab.

SysIBM=SYSIBM

Specifies the AuthID to be used when issuing queries against system catalog tables owned by SYSIBM. Often you will only have privileges on a view on the system catalog tables. Usually the view is created using the same table name, but a different AuthID than the underlying table. When running against XDB Link to DB2, you will usually use SYSIBM=XDB instead of SYSIBM=SYSIBM.

SysXdb=SYSXDB

Specifies the AuthID to be used when issuing queries against system catalog tables owned by SYSXDB. Often you will only have privileges on a view on the system catalog tables. Usually the view is created using the same table name, but a different AuthID than the underlying table. When running against XDB Link to DB2, you will usually use SYSXDB=XDB instead of SYSXDB=SYSXDB.

[Security]

This section of xdb.ini corresponds to the Client Security items that you set on the Security tab of the Options utility. For a more complete description of this option, refer to the Security Tab. (Other items that may appear in this section are used to configure server security.)

ClientSecurity=On|Off

If on, you will have to provide a password to connect to the XDB Server. If off, you will not be asked for a password.

[Connection server-name]

There should be an instance of this section for every server listed in the Servers statement in the [Connection Defaults] section. The items specified here indicate how to make a connection to the named server. They are used in the Options Connect page.

Protocol=protocol

This is the protocol to be used when accessing the specified server. See the Connection Defaults section for a list of protocols.

PrimaryAuthorizationID=authid

This is the default user name that will be used when you connect to this server.

CurrentLocation=location-name

This is the name of the default location that will be provided when you connect to this server.

[Client]

This section contains client-side parameters.

XDBCFG=configuration-directory

This is the path of the configuration directory on the client.

ReceiveBufferSize=size

This is the size of the communications buffer on the client side. The default is approximately 60 Kb.

BulkFetch=0|1

If 1, the default, bulkfetch is on.

ANSICP=ANSI-code-page

The ANSI code page to use on the client-side.

OEMCP=OEM-code-page

The OEM code page to use on the client-side.

[Server]

This section contains server side parameters

XDBSERVE=server-name

This is the name of the default server.

XSRVCFG=configuration-directory

This is the path of the configuration directory on the server.

ReceiveBufferSize=size

This is the size of the communications buffer on the server side. The default is approximately 60 Kb.

[Trace]

This section specifies parameters that need to be set if you want to generate debugging information by turning on client/server traces.

RedirSndRcvTrace=redir-trace-path

This is the path of the client redirector rrace file, for example, c:\redir.trace.

RouterTrace=router-trace-path

This is the path of the router trace file, for example, c:\router.trace.

TraceType=type

This is usually set to 1, although Micro Focus Technical Support representatives might ask you to change this setting.

FileName=engine-trace-path

This is the path of the engine trace file, for example, c:\server.trace.

Flush=0|1

This determines whether or not the trace file is flushed to disk after each trace file entry. The default is 1, which causes the trace file to be flushed to disk after each entry.

ErrorLog=log-file-path

This is the path of the error log file, for example, c:\xmem.errors.

Parent topic: Options Utility


SQL Wizard

Restriction: This topic applies to Windows environments only.

SQL Wizard is a graphical utility that makes it easy to create, maintain and query XDB and DB2 databases. You can use SQL Wizard to:

  • Manage system security and priorities
  • Manage locations, tables and queries
  • Create and run queries
  • Enter data directly into a table
  • Import and export data
  • Run batch scripts
  • Managing Locations, Tables and Queries
  • Create and Manage Database Objects
  • Explore Your Database
  • Add Data to Your Tables
  • Importing and Exporting Data
  • Get Answers to Your Questions
  • Examine Your Results, Change Your Mind
  • Transport Your Data
  • Perform Batch Processing
  • Manage Users, Passwords, and Priorities
  • Connect Dialog Box Overview
  • Introducing the Catalog Browser
  • Common Database Management Features
  • Queries
  • Query Results
  • Data Entry
  • Batch SQL Scripts Overview
  • Import
  • Import NLS Considerations
  • Using Batch Import
  • Export
  • Export NLS Considerations
  • Using Batch Export
  • User Administration
  • Security and Authority Overview
Parent topic: SQL Option User Guide


Managing Locations, Tables and Queries

Restriction: This topic applies to Windows environments only.

SQL Wizard's Catalog Browser window provides an easy way to manage locations, tables and queries, including XDB Server system tables (providing your AuthID has suitable authority). You can open it by clicking any entry on the View menu of SQL Wizard or by clicking
*
on the toolbar. The Catalog Browser has three tabs: Locations, Table and Query.

If you are a superuser, you can use the Locations tab to manage locations. A superuser can create, alter and drop locations, as well as set the currently active location. Other users can only view a list of available locations.

The Table tab displays the hierarchy of locations, AuthIDs, tables and columns. From this page you can create, open, alter and drop tables, as well as view table definitions and indexes, primary keys, foreign keys, views, aliases and synonyms. Note that only a superuser can edit system tables.

The Query tab displays all stored queries accessible to the current server under the Location, AuthID and Query hierarchy. From this page you can create, open, run and delete queries.

Parent topic: SQL Wizard


Create and Manage Database Objects

Restriction: This topic applies to Windows environments only.

Using SQLWizard, you can create a new location (including the system catalog tables) with a touch of a button. You can also create a new table complete with indexes, keys, and foreign keys.

Advanced option dialog boxes generate the appropriate SQL commands for creating DB2 tables, indexes, and other objects.

Parent topic: SQL Wizard


Explore Your Database

Restriction: This topic applies to Windows environments only.

The Catalog Browser provides instant access to SQLWizard's database management facilities. You can expand and collapse the levels to find the object or definition for which you are looking. Double click a table name to open the table. Drag a query to the workspace to edit it, or use the Create, Alter, and Drop buttons to manage database objects.

Parent topic: SQL Wizard


Add Data to Your Tables

Restriction: This topic applies to Windows environments only.

Once you have created a table, you can enter data in several ways.

You can use the Import facility to read data from other file formats into a table.

You can open a table and type data directly into the rows displayed in a Result window.

You can run a program containing embedded SQL to insert data into the table. The Micro Focus application development products are available to assist you in creating programs using COBOL and C.

Parent topic: SQL Wizard


Importing and Exporting Data

Restriction: This topic applies to Windows environments only.

SQL Option can import and export data in a variety of formats. You can specify import and export settings by clicking New > Import or New > Export on the File menu of SQL Wizard. You can optionally save these settings in an .imp or .exp file that you can subsequently run as a batch file for routine data conversions.

Use SQL Option's import capabilities to run programs against test data prepared in another file format. For example, you could export suitable test data held in a Microsoft Access database, or a Microsoft Excel or Lotus 1-2-3 spreadsheet, to delimited or fixed-field ASCII files. You could then import these files into XDB Server.

You can import data into an XDB database from any of the following sources:

  • Free ASCII files (Delimited)

    Imports data from delimited (free-format) ASCII files.

  • Fixed-format ASCII files (Columnar)

    Imports data from columnar (fixed-format) ASCII files.

  • DSNTIAUL

    Imports data downloaded from IBM's DB2 using IBM's DSNTIAUL facilities.

Use SQL Option's export capabilities to transfer data from an XDB database to a mainframe DB2 database if you do not have gateway connectivity, or to create the DDL commands required to create a table.

You can export data from an XDB database into any of the following targets:

  • Free ASCII files (Delimited)

    Exports data to delimited (free-format) ASCII files.

  • Fixed width ASCII files (Columnar)

    Exports data to columnar (fixed-format) ASCII files.

  • DSNTIAUL

    Exports data to DSNTIAUL files. DSNTIAUL files can be read into DB2 systems.

  • SQL statements

    Generates DDL commands that can be used to re-create a table, insert data into it and create indexes on the table. COMMENT, WHERE and SYNONYM statements can be included.

Parent topic: SQL Wizard


Get Answers to Your Questions

Restriction: This topic applies to Windows environments only.

Once your tables are created and populated with data, you are ready to write queries that answer questions about your data. SQLWizard's Query Design facility assists both new and experienced users in writing SQL statements by providing interactive windows, online help, syntax checking, and access to database object information.

If you prefer, you can type and edit SQL statements yourself using the SQL Edit window. A key feature is the ability to execute SQL statements that contain host variables directly from SQLWizard. With support for cut/copy/paste (using the clipboard), you can copy SQL code directly from your host programs, paste it into an SQL Edit window, and test the SQL without having to execute the host program. Likewise, you can use SQLWizard's Query Design facility to create your queries, switch to the SQL Edit window, and copy/paste the SQL statement to your COBOL program.

Parent topic: SQL Wizard


Examine Your Results, Change Your Mind

Restriction: This topic applies to Windows environments only.

Even after you run a query, you can make changes to it. For example:

  • You can rearrange the column order.
  • You can hide columns if you decide you don't need them.
  • You can lock one or more columns in place, so that you can keep an eye on them as you scroll through the other columns.
  • You can sort the retrieved result on any combination of columns.

You get this flexibility without having to continuously rewrite and rerun your queries.

Query Result windows support bi-directional scrolling, and can be viewed and edited in either form or tabular views. You can send the results to a printer, or output them to a file.

Parent topic: SQL Wizard


Transport Your Data

Restriction: This topic applies to Windows environments only.

Import and Export facilities are integrated into SQLWizard. Using Import you can read data from other file formats into a new or an existing XDB Server table. Supported import formats include delimited and tabular ASCII files, DSNTIAUL files, and others.

Export allows you to extract entire or partial sets of data from XDB Server tables and write them to external file formats. You can also export to SQL commands (which results in batch SQL files containing appropriate CREATE and INSERT statements). The Export facility can export a subset of columns, reorder the columns, and apply WHERE criteria to selection of data.

Both interactive and batch modes are provided for Import and Export facilities.

Parent topic: SQL Wizard


Perform Batch Processing

Restriction: This topic applies to Windows environments only.

SQLWizard supports batch processing of SQL statements, including SQL that contains host variables. You can use SQL Wizard to run the following kinds of batch scripts:

  • Prompted queries
  • SQL scripts, including DDL and DML
  • Import files
  • Export files

To run a batch script, click Run Batch on the File menu in SQL Wizard.

Several other SQL Option utilities can create batch files; you can also run these from the appropriate utility. For example:

  • Use the Migrate utility to create and run .mig files
  • Use the Declaration Generator to create and run .dge files

SQLWizard also offers batch export and import facilities.

Parent topic: SQL Wizard


Manage Users, Passwords, and Priorities

Restriction: This topic applies to Windows environments only.

You can perform user administration functions from the Admin menu. You can assign AuthIDs and passwords to users, and establish groups of users who will share the same privilege sets.

Parent topic: SQL Wizard


Connect Dialog Box Overview

Restriction: This topic applies to Windows environments only.

Use the Connect dialog box to specify the parameters needed to establish a connection between SQLWizard and an XDB Server. The information appearing in this dialog box reflects the entries in the Options utility.

  • Suppressing the Connect Dialog with Autoconnect
  • Using Security
Parent topic: SQL Wizard


Suppressing the Connect Dialog with Autoconnect

Restriction: This topic applies to Windows environments only.

If security is off, you can turn on Autoconnect in the Options utility to prevent the Connect dialog box from displaying. When the dialog box is not displayed, the defaults you specified for the Server, Location, and AuthID in Options are used to establish the connection.

Parent topic: Connect Dialog Box Overview


Using Security

Restriction: This topic applies to Windows environments only.

If you are connecting to a multi-user XDB Server on a LAN, or if you are using XDB Link to access DB2 or another database system, your XDB Server Administrator will most likely require you to run with Security on, and you will have to enter a password. (If you are running against an XDB Server that is running with its security feature on, then you must turn SQLWizard's security on.)

To turn SQLWizard's security on, enable the Client Security option on the Security tab in the Options utility. This option causes the Connect dialog box to appear when SQLWizard is loaded, allowing you to enter a password.

Parent topic: Connect Dialog Box Overview


Introducing the Catalog Browser

Restriction: This topic applies to Windows environments only.

The Catalog Browser provides access to locations, tables, indexes, and other objects stored in your XDB Server databases. Buttons at each level of object access allow you to create, alter, drop, and open database objects, as well as run queries. Opening a table is as simple as locating the table's name and dragging it to the SQLWizard workspace, or clicking the Open button; much simpler than having to type SELECT * FROM tablename in an SQL Edit window.

Parent topic: SQL Wizard


Common Database Management Features

Restriction: This topic applies to Windows environments only.

The information in this chapter explains how to create, alter, and drop various database objects. Several features are common to many of the windows that you use to perform these functions. These include:

  • SQL button
  • Comments (Remarks) field
  • Options button
  • Managing Locations
  • Managing Tables
  • Managing Indexes
  • Managing Table Relationships
  • Managing Synonyms
  • Managing Aliases
  • Comments (Remarks) Field
  • Options Button
Parent topic: SQL Wizard


Managing Locations

Restriction: This topic applies to Windows environments only.

A location is a collection of tables, databases, and related objects organized in a specific structure. An XDB Server can have multiple locations, all managed by the same database server. Depending on the options you have installed, SQLWizard can also access locations managed by other XDB Servers, as well as DB2 and other DRDA systems. Through the use of a three-part naming convention and related security measures, you can access more than one location at a time, including remote locations.

Connecting to a location provides you direct access to that location, without having to qualify table names with a location name. You set your initial (default) location in the Options utility. You can choose a different location each time you start SQLWizard by selecting a location on the Connect dialog box. After SQLWizard is running, you can change your current location using the Set Location command from the Location menu.

SQLWizard displays the current location and current SQLID in the status bar at the lower right of the SQLWizard window. Whenever you create, alter, or access a data object, this location and SQLID is used to qualify the table names.

You will also see a SYSTEM location listed in the Catalog Browser dialog box. This location contains system administration and security information. Do not store your data objects in this location. It is reserved for system use. Keep your data in locations that you or your XDB Server Administrator create.

Note: An XDB Server location roughly corresponds to a DB2 subsystem. However, you cannot use the XDB Server location windows to manage a DB2 subsystem. These windows are intended only for use with XDB Server locations.
Parent topic: Common Database Management Features


Managing Tables

Restriction: This topic applies to Windows environments only.

As a relational database management system, SQLWizard stores data in a collection of tables. A table is a named data object made up of columns and rows of data. The data in one or more columns can usually be used to uniquely identify the rows of a table. These identifying columns are known as the primary key columns. Tables can be related to each other based on the data in one or more columns of the related tables. Indexes can be built on the table to speed retrieval and enforce uniqueness among records.

Often a table is identified with a three-part naming convention, where the table name is preceded by the Location and AuthID. The three parts of the name are separated by periods. For example, the table name SYSTEM.SYSIBM.SYSTABLES identifies the SYSTABLES table as being in the SYSTEM location and owned by the SYSIBM AuthID.

Parent topic: Common Database Management Features


Managing Indexes

Restriction: This topic applies to Windows environments only.

An index is a data structure that speeds retrieval or enforces certain constraints, such as uniqueness, on the records in a table. This data structure is separate from the table and can be deleted and recreated without affecting table data. There are three types of indexes:

  • Index

    An index is an organized set of pointers to the rows of a database. Each index is based on the values of data in one or more columns.

  • Unique Index

    A unique index prevents the table from containing two or more rows with the same value in the index key.

  • Primary Key Index (for Referential Integrity)

    A primary key is a column or set of columns used to uniquely identify a row. Primary keys are required for referential integrity relationships. A table may contain at most one primary key.

    You can specify a primary key when you create a new table or when you alter an existing table. You can alter or drop a primary key. The method for creating, altering, and dropping a primary key is the same as for an index. The only difference is that the Type option must be set to Primary Key.

    You must define all columns involved in a primary key either as NOT NULL or NOT NULL WITH DEFAULT. When you define a primary key for a table, the Column Definition Grid on the Create/Alter Table dialog box is modified automatically. Any column that was defined with nulls allowed (False in the Not Null column) is changed to NOT NULL (True in the Not Null column). You can change the value in the Column Definition Grid to w/Default if you wish.

Parent topic: Common Database Management Features


Managing Table Relationships

Restriction: This topic applies to Windows environments only.

You can use SQLWizard to relate the information in one table to that in another table. But, to be able to match records, the foreign key in the dependent table must have a column or collection of columns that match primary key columns in a referenced table.

For example, consider the EMPLOYEE and DEPT tables. Each employee must work in a department that exists. If every existing department must have a row in the DEPT table, then a foreign key built on the Dept column of the Employee table references the primary key of the DEPT table, which is the DEPT column.

If you try to assign an employee to a department that does not exist, you will get an error. If you try to delete a department that has employees working in it, you will get an error. Depending on how you define the foreign key, SQLWizard could automatically delete the employees for you.

If you change the Department ID for a department, SQLWizard may cascade these changes to the employees in that department, or display an error message depending on how you define the foreign key.

Figure 1. *
*

Referential integrity constraints ensure that data from one table that must match data in another table is not altered inadvertently. If you look at the Create Relationship dialog box you see three options that help you to enforce referential integrity between your tables. Restrict is the default.

Parent topic: Common Database Management Features


Managing Synonyms

Restriction: This topic applies to Windows environments only.

A synonym is another name given to an existing table or view. Usually a synonym is used to define a more meaningful name for a particular application or for the use of a particular set of users. You can use a synonym to refer only to a table or view in the current location. Use an alias to provide an alternate name for an object that can be accessed by users from other locations.

Parent topic: Common Database Management Features


Managing Aliases

Restriction: This topic applies to Windows environments only.

An alias is an alternate name for a table or view, similar to a synonym. When you assign an alias to a table, you specify in which locations users can use that alias. You can specify the current location as well as remote locations. This differs from a synonym, which provides an alternate name for a table only to users in the location where the table resides.

Parent topic: Common Database Management Features


Comments (Remarks) Field

Restriction: This topic applies to Windows environments only.

Most database objects (locations, tables, indexes, etc.) may be described by entering comments in the system catalog. In SQLWizard, this is accomplished by entering the comment or description in the Comments field of the Create or Alter dialog box. Comments entered in this manner appear in the Catalog Browser dialog box when the Details option is checked.

Parent topic: Common Database Management Features


Options Button

Restriction: This topic applies to Windows environments only.

The primary Create, Alter, and Drop dialog boxes provide access to dialog boxes that allow you to enter additional information. These options are used to describe the database object or to specify some of the less common attributes for the object. In many (but not all) cases, these additional items relate to compatibility with DB2 or other non-XDB Server databases with which SQLWizard may be used.

*
To access these additional items, click the Options button. Specify any options desired, then close the Table Options dialog box to return to the dialog box you were using.

Parent topic: Common Database Management Features


Queries

Restriction: This topic applies to Windows environments only.
  • What is a Query
  • Why Use Queries
  • Creating and Running SQL Queries
  • How are Queries Written
  • Query Design Window Overview
  • Table Display Area
  • Entering Data Directly into a Table
  • Query Conditions Grid
  • SQL Edit Window Overview
  • Results That Cannot Be Edited
  • Query Options
  • Querying Multiple Tables
Parent topic: SQL Wizard


What is a Query

Restriction: This topic applies to Windows environments only.

A query is a question about your data that allows you to retrieve specific information from your database. It is an instruction to the database system to search for a particular set of data that is of interest to you, and to present it in a useful format.

A query is written as an SQL SELECT statement, as in the following example of a fairly complex query that finds the number of customers in each city in New York or California that has at least one customer. The result is sorted by state and city.

SELECT   St, City, Count(C_no)
FROM     Customer
WHERE    St="CA"  OR  City="New York"
GROUP BY St, City
HAVING   count(*) > 0
ORDER BY St, City

The SELECT statement consists of several important clauses.

  • SELECT Clause

    Lists the columns to be retrieved from the table(s).

  • FROM Clause

    Lists the tables from which data is to be retrieved.

  • WHERE Clause

    Consists of a set of conditions that the rows of data must satisfy.

  • GROUP BY Clause

    Organizes data into subsets or groups based on the values in the grouped columns. It is frequently used to create summary rows containing totals, sums, counts, averages, minimum values, and maximum values.

  • HAVING Clause

    Defines conditions that summary rows of data must satisfy.

  • ORDER BY Clause

    Specifies the order in which the rows of data should be sorted.

Parent topic: Queries


Why Use Queries

Restriction: This topic applies to Windows environments only.

These are some of the reasons for writing a query:

  • To view all of the data in a table.
  • To view a subset of the columns in a table.
  • To view a subset of the rows in a table.
  • To sort the rows of a table.
  • To view new columns based on data in existing columns.
  • To provide data to be used as the basis of a report, or for processing by some other program.
Parent topic: Queries


Creating and Running SQL Queries

Restriction: This topic applies to Windows environments only.

You can create SQL queries either by entering SQL statements directly into an SQL window (click
*
on the SQL Wizard toolbar), or by using a prompted query in the Query Design window (click
*
on the toolbar). You do not need to understand SQL to create a prompted query. The Query Design window is split into two areas:

  • A schema view that shows the tables involved in your query and any relationships between them. This area of the window is called the table display area.
  • A query-by-example view, which shows the columns resulting from your query with any filters that you have applied to them. This area of the window is called the query conditions grid.

When you create a prompted query, you first select the table and columns. Then you apply conditions and sort criteria to the columns to achieve the final result set. Further choices are available from the menus, including joins, the creation of computed columns and the use of built-in functions such as minimum, maximum and average.

As you create a prompted query, the equivalent SQL statements are built up by SQL Wizard. To see them, click
*
. You can edit the SQL statements directly but the changes you make do not appear in the Query Design window. To go back to the Query Design window, click
*
. It's a good idea to save your prompted query before you try editing it in the SQL window. You can run your query and see the results at any time by clicking
*
.

Parent topic: Queries


How are Queries Written

Restriction: This topic applies to Windows environments only.

Queries to XDB Server and other supported database systems are always written in the form of an SQL SELECT statement. When you use SQLWizard to create a query, you can type the SELECT command yourself in an SQL Edit window, or you can use a Query Design window to assist you in generating the statement.

SQLWizard's Query Design facility assists both new and experienced users in writing SQL statements by providing interactive screens, online help, syntax checking, and access to database object information.

Because of the advantages of the prompted method of writing queries, we will focus primarily on this method. However, the section on the SQL Edit window will provide you with the information you need to know if you would rather type queries yourself. In addition, some SQL statements, including some variations of the SELECT statement, cannot be created or executed from the Query Design window. You will need to use the SQL Edit window to create and run these statements. Often you can use a Query Design window to help you write significant portions of these types of SQL statements.

Parent topic: Queries


Query Design Window Overview

Restriction: This topic applies to Windows environments only.

As you use SQLWizard's prompted query facility to generate an SQL statement, you will become familiar with the Query Design window. You can have more than one copy of the Query Design window open at any given time. If a Query Design window is the active window, it will come to the front of other document windows and be known as the current query or active window.

The Query Design window consists of two sections:

  • The Table Display Area.
  • The Query Conditions Grid.

These sections are separated by a splitter bar. By positioning your mouse over the splitter bar and holding down the right mouse button, you can drag the splitter bar up or down to resize the two sections.

Parent topic: Queries


Table Display Area

Restriction: This topic applies to Windows environments only.

The upper section of the Query Design window is known as the Table Display Area. The tables you select are added to the Table Display Area and are shown in Column Selection Lists. It is in this way that you can choose specific columns in a table for your query while in Query Design mode. The name of each table selected appears in the title bar of each Column Selection List. If there is a join relationship between two tables, you will see a line connecting the tables.

Parent topic: Queries


Entering Data Directly into a Table

Restriction: This topic applies to Windows environments only.

SQL Wizard provides both a spreadsheet-like table view and a form view that enable you to enter and edit data directly. Use the table view to see many records at once and the form view to see one record at a time.

You must have appropriate access privileges to edit tables. Only a superuser can edit system tables. Ordinary users can edit tables created using either their own AuthID or a GroupID to which they belong. They can also edit tables to which they have specifically been given access using the GRANT statement. In all cases, you must select Allow Editing on the Record menu before editing is enabled.

You can open or create a table at any time from the Catalog Browser. See the topic Managing Locations, Tables and Queries for more information. The Table view opens automatically to show the result of a query.

Parent topic: Queries


Query Conditions Grid

Restriction: This topic applies to Windows environments only.

The lower section of the Query Design window is known as the Query Conditions Grid. This is the area where you can Query-by-Example (QBE). Each column in your query appears as a column in the Query Conditions Grid. The rows of the grid allow you to type in conditions that the data in the columns must meet, as well as sort conditions, and other instructions for performing your query.

Parent topic: Queries


SQL Edit Window Overview

Restriction: This topic applies to Windows environments only.

While there are many advantages to using the prompted query facility to generate your SELECT statements, there will be many times that you will need to type in SQL statements, or paste SQL statements from the clipboard. Using the SQL Edit window, you can write and execute any type of SQL statement.

You can also include multiple SQL statements in an SQL Edit window and execute each in turn, or skip through them one at a time, or run just the currently selected command.

Although many of the menu items and toolbar buttons used by the Query Design window are disabled in the SQL Edit window, you will run and save queries in the same way, regardless of which window you use.

Parent topic: Queries


Results That Cannot Be Edited

Restriction: This topic applies to Windows environments only.

SQLWizard allows you to use the Result window to insert, update, and delete records after you run a query. However, some query results cannot be updated. For example, the query result for a query that includes a join, an ORDER BY clause, a GROUP BY clause, computed columns, or UNIONS is not updatable.

If you use the Query Design window to create a query that cannot be updated, the Allow Editing command on the Query menu is disabled before you run the query. In addition, the Allow Editing command on the Record menu in the Result window is disabled after you run the query.

Parent topic: Queries


Query Options

Restriction: This topic applies to Windows environments only.

Query options are divided into two types: Query Design options, and Query Run options.

Query Design Options

These options control how your Query Design window appears, and how SQL is generated.

Define Query
3-Part Names | If checked, uses fully qualified table names in queries. If you get X28 errors, you should try checking this box.
2-Part Names | If checked, qualifies names with AuthID.
Unqualified Names | If checked, does not qualify names.
Show Table Names
If checked, adds a row to the Query Conditions Grid to show the name of the table from which a column comes.
Note:

*
Click the Show Table Names button to display the name of the table from which a column comes.

Auto Join Defaults
These options indicate the rules the system should use when automatically defining join conditions.
Join on Foreign Keys | If checked, automatically joins all columns involved in a foreign key relationship when the referenced and referencing tables appear in the Table Display Area of the Query Design window. This method of auto joining produces good results, since foreign keys are built on columns that are meant to be joinable.
Join on Primary Key With Like Names | If checked, automatically joins a primary key column with a column (or collection of columns) having the same name(s) in another table, provided both tables appear in the Table Display Area of the Query Design window. This method can result in some unintended joins if the primary key column name is a common name like CITY.
Join on Like Names | If checked, automatically joins a column with another column of the same name in another table, provided both tables appear in the Table Display Area of the Query Design window. This option should be used with care. It is frequently the case that columns that should not be joined have the same name as another column in a different table. If you use this option, you should carefully check each join that is generated automatically to make certain it is meaningful.
Prohibit Cartesian Products
If checked, looks for any queries that are executed from within this program to determine if they will yield Cartesian products.

Query Run Options

These options take effect when a query executes.

Execute
Only one of these options can be enabled at a time.
All Commands | If enabled, executes every command in the current SQL Edit window or .SQL script. If Step Mode is on, you have to use the Query menu Continue command to execute each step.
First Command | If enabled, executes only the first command in the SQL Edit window or .SQL script.
Current Command | If enabled, executes the command at the current cursor location if bounded by semicolons.
Default Result View
These options indicate if you want the default view for a result window to be a Result Table view (like a spreadsheet, showing multiple records at one time), or a Result Form view (shows one record at a time, with the fields arranged vertically). This option defines the default. You can switch to the other view at any time before or after a query is executed.
Edit Options
Allow Editing | If a query result can be edited, signals the system to go directly to edit mode. If a result cannot be edited, it has no effect and the Allow Editing option is grayed out.
AutoCommit | If a query result can be edited, indicates that the system should perform an automatic commit each time a record is updated, deleted, or inserted.
Max Records to Retrieve
You can limit run away queries by checking the First n Recordoption, and providing a reasonable value for n. Otherwise, every row has the potential of being retrieved. Note that SQLWizard tries to be intelligent when retrieving results. If you do not try to look at or otherwise access all of the rows in a result, it does not fetch all of them. However, if you perform a count, or if you print the result, or scroll to the bottom of the result, all rows will be retrieved, which could take some time depending on the query.
Parent topic: Queries


Querying Multiple Tables

Restriction: This topic applies to Windows environments only.

Good database design usually results in a database with multiple tables related to each other by the values in certain columns. Even though the data is stored in separate tables, you will often want to see it in a single result. When you combine the data from two or more tables into a single result, you create a join.

Parent topic: Queries


Query Results

Restriction: This topic applies to Windows environments only.
  • Introducing the Result Window
  • Result Window Views Overview
  • The Result Table View
  • The Result Form View
  • Current Record and Total Record Counts
Parent topic: SQL Wizard


Introducing the Result Window

Restriction: This topic applies to Windows environments only.

The Result window displays when you successfully run a query or when you open a table using the Catalog Browser dialog box. Specifically, the Result window appears when you:

  • Run a query from the Query Design window using the Run command from the Query menu, or the Run button on the toolbar.
  • Run a query from the SQL Edit window using the Run command from the Query menu, or the Run button on the toolbar.
  • Execute a batch SQL script (.SQL file) Open or Run Batch commands from the File menu.
  • Open a table using the Catalog Browser dialog box.
Parent topic: Query Results


Result Window Views Overview

Restriction: This topic applies to Windows environments only.

The Result window has two views: the Result Table view and the Result Form view. You can switch between these views by clicking the Result Table and Result Form buttons on the toolbar, or by using the Result Table and Result Form commands on the View menu.

Parent topic: Query Results


The Result Table View

Restriction: This topic applies to Windows environments only.

The Result Table view displays the result of your query in a tabular grid-like format that shows multiple records at a time like a spreadsheet. Each row in the Result window corresponds to a row (or record) from the table. You may have to scroll horizontally to see all columns in the result, and scroll vertically to see all the rows in the result.

Note:

*
Click the Result Table button on the toolbar to place the Result window in Result Table view.

Parent topic: Query Results


The Result Form View

Restriction: This topic applies to Windows environments only.

The Result Form view displays the results of your query one record at a time. The Result Form view shows each record (or as much as will fit in the window) with the fields arranged one above the other. If your records contain many fields or long fields, you may have to scroll horizontally to see all the fields of a given record.

Note:

*
Click the Result Form button to place the Result window in Result Form view.

Parent topic: Query Results


Current Record and Total Record Counts

Restriction: This topic applies to Windows environments only.

While in the Result window, SQLWizard retrieves enough records to show a complete page in the window. Each time you scroll or page to display more records, you are commanding SQLWizard to retrieve the additional records. There are two major advantages to this approach:

  • Results are displayed more quickly.
  • Many records can be viewed simultaneously.
Note:

You can limit the total number of records that a query can retrieve by setting the Max Rows To Retrieve option in the Current Query Options dialog box or through the Options utility.

Notice that as you move the cursor to different records in a result, SQLWizard updates the RECORD n OF m message on the status bar at the bottom of the screen. The first number in this message is the current record number and the second is the total number of records in the query result. If the total number of records is unknown, you will see a ? in place of the record count. If you need to know the actual record count, you can request that the system perform a count by selecting the Count command on the Record menu.

To find the total record count for the result:

  1. Open the Record menu.
  2. Click the Count command.

    SQLWizard displays the current record number (relative to the retrieved set of records) and the total number of records in the result on the status bar.

    Note:

    Performing a count causes the SQLWizard to retrieve all of the records in the result. For some results, such as joins on large tables, this could take quite some time. This is why SQLWizard does not automatically perform a count for you.

Parent topic: Query Results


Data Entry

Restriction: This topic applies to Windows environments only.
  • Using the Result Window for Data Entry Overview
  • Transaction Processing
  • Working in Autocommit Mode
  • Using Commit and Rollback
Parent topic: SQL Wizard


Using the Result Window for Data Entry Overview

Restriction: This topic applies to Windows environments only.

SQLWizard allows you to use the Result window to insert, update, and delete records. To enter data, you must enable the Allow Editing option either before you run the query or after the result is displayed.

Parent topic: Data Entry


Transaction Processing

Restriction: This topic applies to Windows environments only.

A transaction is an atomic unit of work, meaning that all of the steps in a transaction must be performed completely, all must be undone completely. SQLWizard supports the concept of a transaction by allowing you to commit or rollback all edits made to the result since the last commit or rollback.

Note: If accessing an XDB Server version 4.x or lower, you must turn on the Backward Log using the Options utility. If the Backward Log is not on, rollback commands will have no effect.
Parent topic: Data Entry


Working in Autocommit Mode

Restriction: This topic applies to Windows environments only.

When SQLWizard is installed on your machine, the default setting for data entry transaction processing is Autocommit On. In this mode, all changes made to a record are committed as soon as you move to the next record. This means that you do not have to remember to commit periodically, and it frees any locks that might be held on records you are editing, so that other users have access to the data. However, it means that you have little chance to rollback changes.

For this reason, SQLWizard provides two undo commands. The Undo command in the Edit menu restores changes to the current field. The Undo command in the Record menu re-reads the current record from the database. Since the record changes were never written to the database, there is no need to perform a rollback. However, you cannot use the Undo command once you have left the modified record.

Parent topic: Data Entry


Using Commit and Rollback

Restriction: This topic applies to Windows environments only.

If you turn Autocommit mode off, the Rollback and Commit commands in the Record menu are enabled. You can now make changes to several records, and then decide whether to commit (accept) or rollback (undo) all of these changes. Choose the appropriate command from the Record menu.

Note:

If accessing an XDB Server version 4.x or lower, you must turn on the Backward Log using the Options utility. If the Backward Log is not on, rollback commands will have no effect.

Parent topic: Data Entry


Batch SQL Scripts Overview

Restriction: This topic applies to Windows environments only.

A batch script is a set of SQL statements that have been stored in a text file. A script is usually created by saving the contents of the SQL Edit window to an .SQL file. Once the script has been saved, it can be replayed at any time using the SQLWizard's Run Batch command. It can also be executed directly from your system's command line.

Any operation that can be performed interactively can be performed from a script-- you can create tables, insert and delete records, view query results, and more. A batch script is particularly useful to automate tasks that are run on a regular basis. Once you have created a script, it can be used over and over.

Parent topic: SQL Wizard


Import

Restriction: This topic applies to Windows environments only.
  • Introducing Import
  • Using Other Import Features
  • Importing a File Overview
  • Source File Information
  • XDB Server Table Information
  • Import File Formats Overview
Parent topic: SQL Wizard


Introducing Import

Restriction: This topic applies to Windows environments only.

SQLWizard Import allows you to insert data from various file formats into new or existing XDB Server tables or views. You can view the source file to be imported, set options for recording import process errors, have the system calculate a new table definition from your source file, and set up and run Batch Import commands.

Batch import is particularly useful if you repeatedly import data with the same or similar table definition. Each time you open an Import window and provide import specifications and then save the specifications to a file, you create a Batch Import file. Before using Batch Import, you should be familiar with interactive import for the file type you are importing.

The following is a list of file formats supported by SQLWizard. Depending on the format you select, you may need to specify a number of options before activating the import.

  • Free ASCII Files (Delimited)

    Imports data from delimited (free-format) ASCII files into XDB Server tables.

  • Fixed-format ASCII Files (Columnar)

    Imports data from columnar (fixed-format) ASCII files into XDB Server tables.

  • DSNTIAUL

    Imports data downloaded from IBM's DB2 using IBM's DSNTIAUL facilities.

Parent topic: Import


Using Other Import Features

Restriction: This topic applies to Windows environments only.

Other features available with Import allow you to clear all import specifications from an Import window, specify error handling options, and view the contents of your source file or Batch Import file.

Parent topic: Import


Importing a File Overview

Restriction: This topic applies to Windows environments only.

The Import window is separated into two sections. The Source File Information section is where you specify the file you want to import, specify the format of the file, and define other format-specific requirements. The XDB Server Table Information section is where you specify the destination XDB Server table. You can import data to an existing table (with options to append or replace data) or create a new table to hold the imported data.

Parent topic: Import


Source File Information

Restriction: This topic applies to Windows environments only.

This section of the Import window is where you specify the name of the file from which you will import data, as well as the format of that file and any other parameters required for the selected format.

File Name | Enter the drive, path, and name of the file whose data you want to import.
Format | Use the drop-down list to select the format of the file you are importing. SQLWizard can import data from free- or fixed-format ASCII files, and DSNTIAUL files.
Other Source File Parameters | Depending on the format of the file being imported, additional parameters may be required.
Parent topic: Import


XDB Server Table Information

Restriction: This topic applies to Windows environments only.

This section of the Import window is where you specify the name of the XDB Server Table that is to receive your imported data. You can import data into an existing XDB Server table, or create a new table and define its table definition structure right on the Import window.

Table
Enter the name of the XDB Server table that will receive your data.

To import data to an existing XDB Server table, use the Browse button to select a table. Check the Replace Data checkbox if you want the imported data to replace existing data in the table. To append the imported data to the existing data in the table, be sure the Replace Data checkbox is unchecked.

To use the imported data to create a new XDB Server table, check the Create Table checkbox and specify the items in the Table Definition Grid at the bottom of the window.

Create Table
Check this box when you want to use the imported data to create a new XDB Server table.
Replace Data
Check this box when importing data to an existing XDB Server table and you want to replace the existing data. When this option is checked, all data in the existing table is deleted and is replaced in its entirety with the new data coming from the file you are importing.
Table Definition Grid
When importing to an existing XDB Server table, this area of the screen shows the table structure.

When creating a new XDB Server table to hold your imported data, SQLWizard provides a suggested table definition. You can make changes as desired.

Name (Column Name)
If you do not specify column names when importing to a new table, Import attempts to read the field names from the source file (if the Heading checkbox is marked or the format indicates that field names are in the first record). Otherwise, the import program provides default names (Field1, Field2, ... Fieldn).
Type (Field Type)
When importing data to a new XDB Server table, you must specify field types. You do not necessarily need to use the same data types as in the source file. For example, you can redefine a NUMERIC field to be a CHARACTER field, but you should not redefine a CHARACTER field that contains non-numeric data as SMALLINT, INTEGER, OR FLOAT.
Length (Field Length)
If you choose to specify field lengths, you can specify the lengths of CHARACTER, VARCHAR, GRAPHIC, VARGRAPHIC, CHAR FOR BIT DATA, and VARCHAR FOR BIT DATA fields. You must also specify the precision and scale for DECIMAL fields (default is 5,0). Other field lengths refer to storage length and are provided automatically.
Null (Null Values)
Specify the null permission of the field. Indicate Yes if nulls are allowed, No if nulls are not allowed, and DEF if nulls should be converted to the default value for the field. The DEF option is the same as NOT NULL WITH DEFAULT.
Pic
Indicate if you want to use the mask specified on the Format tab in Options when importing MONEY, DECIMAL, DATE, and TIME fields:
  • Yes: Use the Options mask.
  • No: Do not use the Options mask. Instead, use the following default format masks:
    Type | Default Picture
    Time | hh:mm:ss
    Date | mm/dd/yyyy
    Decimal | <sign><digits>[.<digits>][E[+-]<digits>]
    Money | <sign><digits>[.<digits>][E[+-]<digits>]
    where:

    <sign> includes any combination of + - $ >=

    <digits> are 0 through 9; also comma (,) if to the left of the decimal place.
Src Off (Source Offset)
For importing fixed-format ASCII files. Should indicate the starting column number for each field in the source file. The system suggests offsets based on the white space found in the heading row of the source file.
Src Len (Source Length)
For importing fixed-format ASCII files. Should indicate the length of each data field. You might have to edit the Src Len column to correctly describe the source file.

When importing a fixed-format ASCII file to a new table, you must specify field lengths or use the HEADING= and SPACES= statements in your batch file. If the import program finds HEADING=Y and SPACES=1 or more, it will be able to determine the field lengths.

Parent topic: Import


Import File Formats Overview

Restriction: This topic applies to Windows environments only.

This topic contains detailed information about each file format that you can import to an XDB Server table. These include:

  • Delimited (free-format) ASCII files
  • Columnar (fixed-format) ASCII files
  • DSNTIAUL files
  • Delimited (Free-Format) ASCII Files
  • Columnar (Fixed-format) ASCII Files
  • DSNTIAUL Files
  • Summary of Import Parameters by File Format
Parent topic: Import


Delimited (Free-Format) ASCII Files

Restriction: This topic applies to Windows environments only.

Use this format to import data from delimited, free-format ASCII files. ASCII format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII output files. There are two ASCII file formats:

  • Delimited, free-format ASCII Files allow variable field lengths-- each field is separated by a field delimiter.
  • Columnar, fixed-format ASCII Files have fixed field lengths-- data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

The new XDB Server table definition suggested by SQLWizard when it examines a free-format ASCII file depends entirely on the data found in the file. You can examine the file yourself by using the Source File command from the View menu. If needed, you can change the suggested table definition in the table display area on the Import window.

When you use the Browse button to choose a file to import, SQLWizard defaults the file listing to the *.fre extension. The file you are importing can have a different extension.

The default field delimiter assumed for free-format ASCII files is an @ symbol. You can change this on the Import window or you can change the default by using the Defaults command from the Import menu.

The following table shows you the delimited ASCII format options:

Field Delimiter You must specify the field delimiter that is used to indicate where each field ends. The field delimiter differs from the record delimiter. The field delimiter is entered as a keyboard character or as an ASCII decimal code for a character. Decimal codes must be enclosed in angled brackets. For example, if the source file uses a # as the field delimiter, enter the character # or the string <35>. To use the < or > character as a delimiter, you must enter the ASCII decimal codes <60> or <62>, respectively.

If you don't know what the field delimiter is, use the Source File command from the View menu to display the source file. Optionally, you can use an ASCII text editor to examine the contents of the source file. If the field delimiter contains nonvisible ASCII characters, you might have to use a hex editor to examine the contents of the file.

If you specify a field delimiter that is not found in the file, you will not be allowed to continue. If your data uses a delimiter character that also appears in the data values, the system might try to create a table with too many fields. You can use a delimiter that is found in the data values only if the data values are surrounded by double quotes.

If you use a double quote character as the delimiter, the fields cannot also be enclosed in quotes. Do not use a comma as the delimiter if your data contains numeric values having commas as a grouping character.
Record Delimiter | The record delimiter for standard ASCII files is a carriage-return followed by a line-feed, as indicated by the default <013><010>. If your file uses a different end-of-record delimiter, you can change this setting. For example, you can import a file using the record delimiter <005><010>.
Values In Quotes If field values in your data contain quotes, click the Quotes checkbox to select it. Otherwise, be sure the Quotes checkbox is deselected. If data values contain quotes, you cannot use a quote as the field or record delimiter.

If fields are enclosed in quotes (either double- or single-), any delimiter character found within a pair of quotes is treated as part of the string. For example, if you are using a comma as a delimiter, and your source file contains the string "Washington, DC 20021", the entire string will be treated as one field, even though it contains the delimiter character. There must be a matching quote character for every quote character in the file. If your fields are enclosed in quotes, do not use quotes as a delimiter.

The system suggests a character data type for any columns of data enclosed in quotes; you can change the data type on the Field Definitions Grid at the bottom of the Import window.
Heading

If the first row of the file you are importing contains field names, click the Heading checkbox to select it. This tells Import to use those names as the column names in the table you are creating. If record data begins in the first row, then uncheck the Heading checkbox to turn off inclusion of a heading row.
Insert Nulls As Defaults | Select this checkbox if you would like to insert the columns' default values in place of NULLs in the source file for those defined WITH DEFAULT.
Parent topic: Import File Formats Overview


Columnar (Fixed-format) ASCII Files

Restriction: This topic applies to Windows environments only.

Use this format to import data from columnar, fixed-format ASCII files. This format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII output files. There are two ASCII file formats:

  • Delimited, free-format ASCII Files allow variable field lengths-- each field is separated by a field delimiter.
  • Columnar, fixed-format ASCII Files have fixed field lengths-- data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

The new XDB Server table definition suggested by SQLWizard when it examines a free-format ASCII file depends on the data found in the file and the parameters you enter on the Import window. You can examine the file by using the Source File command from the View menu. If needed, you can change the suggested table definition in the table display area on the Import window. You must specify the following:

  • Spaces
  • Heading
  • Offset
  • Source Length

When you use the Browse button to choose a file to import, SQLWizard defaults the file listing to the *.fix extension. The file you are importing can have a different extension.

The following table shows you the fixed-format ASCII format options:

Spaces |  | The Import utility requires that you confirm the number of blank spaces between columns. This is done by providing a number in the Spaces entry field on the Import window.
Heading |  | If the first row of the file you are importing contains field names, click the Heading checkbox to select it. This tells Import to use those names as the column names in the table you are creating. If record data begins in the first row, then uncheck the Heading checkbox to turn off inclusion of a heading row.
Table Definition |  | When importing fixed-format ASCII files in interactive mode, SQLWizard suggests a table definition based on the contents of the data file. You must examine and modify the source file offsets and lengths in the suggested table definition before you import the file. This must be done for all fixed-format ASCII imports, even if you are importing to an existing XDB Server table.
 | Offsets | Each column of data in a fixed-format ASCII file begins at a fixed point. The Offsets parameter indicates the number of characters from the beginning of the record to the beginning of the column specified. The system examines the row containing the column names (if any) to determine the offset. If the column names appear in the first row and consist of a single word that is left-justified over the column, the system should find the correct offset for you. Otherwise you will have to examine the data to determine the offset, and enter it in the appropriate location in the Offset column of the Table Definition Grid. Use the Source File command from the View menu to display the source file. The ruler at the top of the window corresponds to the offset. Use the beginning column number as the offset for each column. For example, in the following file, the offset for the E_NO column is 1, the offset for the LNAME column is 11, etc.
 | Src Len (Source Length) | When importing fixed-format ASCII files, Source Length refers to the width of the column in the source file. This value is used to determine where a column of data ends. Even if the target XDB Server table already exists, you must supply the length of each column in the source file. SQLWizard suggests a length for fields based on the source file structure. You must check and correct the source length for all columns in the Table Definition Grid before attempting to import the table.
Parent topic: Import File Formats Overview


DSNTIAUL Files

Restriction: This topic applies to Windows environments only.

Code Page Support

If any translation tables are defined in SYSIBM.SYSSTRINGS, they will appear on the Import window in the Codepage list box. The format in the list box is FROM n1 TO n2, where n1 is the number of the code page being translated from and n2 is the number of the code page being translated to.

When you select an item from the Codepage list box, Import loads the translation table for that conversion and uses it to convert character data during the import operation. You can specify which fields to convert by selecting Yes or No in the EBCDIC column of the Table Definition Grid. Normally, a conversion is performed for all applicable fields.

The format of the SYSIBM.SYSTRINGS table is as follows:

Column Name | Type | Length | Description
INCCSID | int | 2 | Code page number to translate From.
OUTCCSID | int | 2 | Code page number to translate To.
TRANSTYPE | CHAR | 2 | Not used by Import.
ERRORBYTE | CHAR | 1 | Not used by Import.
SUBBTYPE | CHAR | 1 | Not used by Import.
TRANSPROC | CHAR | 8 | Not used by Import.
IBMREQD | CHAR | 1 | Not used by Import.
TRANSTAB | VARCHAR for bit data | 256 | Translation table to convert from INCCSID code page to OUTCCSID code page.
Parent topic: Import File Formats Overview


Summary of Import Parameters by File Format

Restriction: This topic applies to Windows environments only.

The following table shows which import parameters are required for each file format.

Import Parameters |  | Batch Keyword | Free ASCII | Fixed ASCII | DSNTIAUL
Source File Name |  | FILENAME | Required | Required | Required
Fld names in 1st row? |  | HEADING | Required | Required |
Field delimiter |  | FLD_DELIMITER | Required |  |
End of rec delimiter |  | REC_DELIMITER | Required |  |
Values in quotes? |  | QUOTE | Required |  |
How many fields? |  |  |  | Required |
Insert Null as blank? |  | INS_NULL | Required | Required | Required
XDB Server Table name |  | TABLE | Required | Required | Required
If table exists: |  |  |  |  |
 | Append or Replace | REPLACE |  | Required | Required | Required
If table does not exist: |  |  |  |  |
 | Name | FIELDS |  | Required | Required | Required
 | Type | TYPES |  | Required | Required | Required
 | Length | LENGTH |  | Required | Required | Required
 | Null? | NULL_PERM |  | Required | Required | Required
 | PIC? | USE_PIC |  | Required | Required | Required
Source Offset |  | OFFSETS |  | Required |
Source Length |  | SRC_LENS |  | Required |
Source File type |  | FORMAT | Required | Required | Required
Convert EBCDIC values to ASCII |  | EBCDIC_TO_ASCII |  |  | Required
Code Page |  | EBCDIC_CODEPAGE |  |  | Required
 |  | ASCII_CODEPAGE |  |  |
Insert Mode |  | INSERT_MODE | Required | Required | Required
Commit Interval |  | COMMIT_INTERVAL | Required | Required | Required
Log Errors |  | ERR_LOG_FILE | Required | Required | Required
On Error |  | ON_ERROR | Required | Required | Required
Parent topic: Import File Formats Overview


Import NLS Considerations

Restriction: This topic applies to Windows environments only.

You need to be aware of character set conversion issues when importing data, especially if:

  • Your data contains diacritical (accented) or other characters that lie outside the first half of the ASCII character set
  • Your data was created using a variety of EBCDIC code pages

If you are importing EBCDIC data using SQL Wizard, we recommend using the DSNTIAUL data format as this enables you to specify an appropriate EBCDIC to ANSI or ANSI to EBCDIC conversion.

You specify the appropriate conversion by picking an entry in the code page window. For example, to import a Spanish EBCDIC table, you would pick the EBCDIC to ANSI translation 284 - 1252.

Parent topic: SQL Wizard


Using Batch Import

Restriction: This topic applies to Windows environments only.

When you enter import specifications and use the Save As command from the File menu, you are saving the contents of the Import window. The saved file is a Batch Import file containing one import transaction. It has an .imp file name extension. A Batch Import file can also be created using any ASCII text editor. You can preview how an import specification would look as a batch file by clicking on Batch Import Commands from the View menu.

Batch Import is particularly useful when you have a number of similar files to import, or when you import the same files on a regular basis. Once you have created a Batch Import file, you may use it over and over, with or without modification.

Parent topic: SQL Wizard


Export

Restriction: This topic applies to Windows environments only.
  • Introducing Export
  • Using Other Export Features
  • Exporting a Table Overview
  • Saving and Reusing Export Specifications Overview
  • Export File Formats Overview
Parent topic: SQL Wizard


Introducing Export

Restriction: This topic applies to Windows environments only.

SQLWizard Export allows you to transfer the contents of any XDB Server table or view into a file in any of the supported file formats. You can export the columns of an existing table in any order or export a subset of the columns. In addition, you can specify a WHERE condition to export only selected data from the original table. Features are available to log the export process, set your own defaults for various export options, and set up and run Batch Export commands.

Batch export is particularly useful if you repeatedly export data from the same tables. Each time you open an Export window and provide export specifications and then save the specifications to a file, you create a Batch Export file. Before using Batch Export, you should be familiar with interactive export for the type of file to which you are exporting.

The following is a list of file formats supported by SQLWizard. Depending on the format you select, you may need to specify a number of options before activating the export.

  • Free ASCII Files (Delimited)

    Exports data from XDB Server tables to delimited (free-format) ASCII files.

  • Fixed Width ASCII Files (Columnar)

    Exports data from XDB Server tables to columnar (fixed-format) ASCII files.

  • DSNTIAUL

    Exports data from XDB Server tables to DSNTIAUL files. DSNTIAUL files can be read into DB2 systems.

  • SQL Statements

    Generates SQL commands that can be used to re-create a table, insert data into it, and create indexes on the table. COMMENT, WHERE, and SYNONYM statements can be included.

Note: XDB Server indexes are specific to the XDB Server environment and are not relevant to any other environment. Index information is environment-specific and depends on the operating system. Therefore, SQLWizard Export will not export the indexes when it exports a table. However, if exporting to SQL statements, you can generate the SQL CREATE INDEX command that will re-create an index on an XDB Server or DB2 system.
Parent topic: Export


Using Other Export Features

Restriction: This topic applies to Windows environments only.

Other features available with Export allow you to clear all export specifications from an Export window, specify error handling options, and view the contents of your target file or batch import or Batch Export files.

Parent topic: Export


Exporting a Table Overview

Restriction: This topic applies to Windows environments only.

The Export window is divided into two sections. The Target File Information section is where you specify the file that will receive your exported data. The Source Table Information section is where you specify the table whose data you will be exporting. There are two versions of the Source Table Information section. You choose which one to use by selecting Design Mode or SQL Mode from the View menu, or by specifying your preference in the Export Default Settings dialog box.

Parent topic: Export


Saving and Reusing Export Specifications Overview

Restriction: This topic applies to Windows environments only.

Export specifications can be saved and reused. Saving a specification as it appears on an Export window creates a Batch Export file containing one export transaction. The saved file can be redisplayed and run in an Export window, or can be run using the Batch Export facility. Using an editor, you can copy and paste to combine the contents of multiple batch files to run them as one job.

Parent topic: Export


Export File Formats Overview

Restriction: This topic applies to Windows environments only.

This topic contains detailed information about each file format to which you can export XDB Server data. These include:

  • Delimited (Free Format) ASCII files
  • Columnar (fixed-format) ASCII files
  • DSNTIAUL files
  • SQL statements
  • Delimited (Free Format) ASCII Files
  • Columnar (Fixed-Format) ASCII Files
  • DSNTIAUL Files
  • SQL Statements Overview
Parent topic: Export


Delimited (Free Format) ASCII Files

Restriction: This topic applies to Windows environments only.

Use this format to export data from an XDB Server table or view to a free-format ASCII file. ASCII format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII files. There are two ASCII file formats:

  • Delimited Free Format ASCII Files allow variable field lengths - each field is separated by a field delimiter.
  • Fixed-format ASCII Files have fixed field lengths - data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

When you use the Browse button to choose a target file, Export will search for the selected file format. Free format is indicated by the file name extension .fre.

You must specify a field delimiter to indicate where each field ends. The field delimiter differs from the record delimiter. The field delimiter can be typed as keyboard characters or as ASCII decimal codes enclosed in angle brackets. For example, to use a colon for a field delimiter, enter the character : or the string <58>. To use an angle bracket character ( < or > ) as a delimiter, you must enter the ASCII decimal codes <60> or <62>, respectively.

When specifying a delimiter, take care not to use a character found in your data, or in the default masks for the data types in the exported table. For example, do not use a comma as the delimiter if your data contains numeric or money values grouped with a comma. The default delimiter is an @ symbol.

Record Delimiter | Enter a character to be used as the end-of-record delimiter. The record delimiter for standard ASCII files is a carriage-return followed by a line-feed, as indicated by the default <013><010>. You can specify a different record delimiter to handle other file structures. For example, you could specify the field delimiter as <008><010> and the record delimiter as <005><010>.
Quotes | Select the Quotes checkbox if you want character fields in your target file to be enclosed in quotes. When character fields are enclosed in quotes (either double- or single-), any delimiter character found within the quotes is treated as part of the string. For example, if you are using a comma as a delimiter, and your source file contains the string "Washington, DC 20021", the entire string will be treated as one field even though it contains the delimiter character. Note: If your fields are enclosed in quotes, do not use quotes as a delimiter.
Heading | Select this option if you want to insert the column names in the first row of the target file. If you do not want columns names to appear in the first row, deselect the Heading checkbox.
Parent topic: Export File Formats Overview


Columnar (Fixed-Format) ASCII Files

Restriction: This topic applies to Windows environments only.

Use this format to export data from an XDB Server table or view to a fixed-format ASCII file. This format is a common means of transferring data from one program to another. Many software applications (including SQLWizard) provide a means of creating and reading ASCII files. There are two ASCII file formats:

  • Free Format ASCII Files allow variable field lengths-- each field is separated by a field delimiter.
  • Fixed-format ASCII Files have fixed field lengths-- data is arranged in columns. Every record fits into a standard form, so field delimiters are not required.

Because every record fits into a standard form, field delimiters are not required for this format. However, you do need to specify number of space characters to be entered between columns and whether or not a header row should be exported.

When you use the Browse button to choose a target file, export will search for the selected file format. Fixed-format is indicated by the file name extension .fix.

The following table shows you the columnar fixed-format ASCII format options:

Spaces | Enter a number to indicate how many space characters should be inserted between columns of data in the exported file.
Heading | Select this option if you want to insert the column names in the first row of the target file. If you do not want columns names to appear in the first row, deselect the Heading checkbox.
Parent topic: Export File Formats Overview


DSNTIAUL Files

Restriction: This topic applies to Windows environments only.

Use this format to export data from an XDB Server table or view into the DSNTIAUL file format. DSNTIAUL is a mainframe format (File UNLOAD Utility) that is used with DB2.

When you use the Browse button to choose a target file, export will search for the selected file format. DSNTIAUL format is indicated by the file name extension .dsn.

In DSNTIAUL files, all data is consecutive (no delimiters), and padded for the full length of the field, making it more like a columnar (fixed-format) ASCII file. If nulls are allowed, a one-byte trailer after each field indicates null status:

  • A zero (0) indicates NOT NULL.
  • An EBCDIC question mark (?) indicates NULL.

Data types are exported as follows:

  • Text fields are stored in EBCDIC format.
  • Date, Time, and Timestamp fields are stored as text.
  • Decimal and Money fields are stored in BCD format.
  • Smallint fields are stored in binary format. As the field is read, its byte order is automatically transformed from standard Intel format (where the least significant byte is first) into standard binary format (where the most significant byte is first).
  • Integer fields are stored in binary format. As the field is read, its byte order is automatically transformed from standard Intel format (where the least significant byte is first) into standard binary format (where the most significant byte is first).
  • Float fields are stored in binary format (different from PCs).
  • Varchar fields have a two-byte header containing the length of the text.

The DSNTIAUL file format directly depends on the null permissions of the exported table. Therefore the null permissions of the table you import into must match the table's null permissions from which you exported.

The DSNTIAUL format uses a page-oriented storage for each record in the table. The typical page size is approximately 4K bytes. When the table contains a long varchar field (which is 4056 bytes long), information in this field may be truncated. The size of the long varchar field is truncated to the page size minus the sum of the sizes of the other fields in the table.

Export to DSNTIAUL format can make use of Code Page Support. This allows you to export objects to DSNTIAUL in EBCDIC and retain object names containing foreign characters. By default, Export assumes character data is stored in the source tables using the American ASCII character set and converts it to the American ASCII character set before writing it to a target file. See "ASCII Table" for a listing of the decimal ASCII character sets.

You can have the Export utility translate character data containing characters from any international EBCDIC character set using the code page feature in Export. For the EBCDIC code page, use the default EBCDIC character set for your country. Code page support is provided by the INCCSID and OUTCCSID fields in the SYSIBM.SYSSTRINGS table at the SYSTEM location.

The following table shows the structure of the SYSIBM.SYSSTRINGS table.

Column Name | Type | Length | Description
INCCSID | int | 2 | Code page number to translate FROM.
OUTCCSID | int | 2 | Code page number to translate TO.
TRANSTYPE | CHAR | 2 | Not used by Export.
ERRORBYTE | CHAR | 1 | Not used by Export.
SUBBTYPE | CHAR | 1 | Not used by Export.
TRANSPROC | CHAR | 8 | Not used by Export.
IBMREQD | CHAR | 1 | Not used by Export.
TRANSTAB | VARCHAR for bit data | 256 | Translation table to convert from INCCSID code page to OUTCCSID code page (ASCII to EBCDIC)

When the Export utility uses code page options, the values entered for INCCSID and OUTCCSID are compared with values in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert XDB Server data in ASCII format to DSNTIAUL data in EBCDIC format.

Parent topic: Export File Formats Overview


SQL Statements Overview

Restriction: This topic applies to Windows environments only.

Use this option to generate a file containing standard SQL CREATE, INSERT, INDEX, SYNONYM, CHECK, and COMMENT ON commands that will allow a table or view and the data it contains to be re-created in another SQL environment. This option generates a standard Batch SQL file that can be used directly by SQLWizard's Batch SQL or other SQL DBMS applications. You can run an exported SQL file on a mainframe DB2 system as a means of copying tables and data from XDB Server to DB2.

The standard SQL commands you can create with this Export format are:

  • CREATE TABLE
  • CREATE INDEX
  • CREATE SYNONYM
  • COMMENT ON
  • INSERT
  • ALTER TABLE...CHECK.

When you use the Browse button to choose a target file, export will search for the selected file format. The SQL Statement format is indicated by the file name extension .SQL.

Specify what types of SQL statements you would like to have generated from the source table or view by clicking on the desired SQL statement checkboxes. The table below describes each option.

SQL Option | Generated SQL Statements
CREATE | Generates a CREATE TABLE or CREATE VIEW statement that will re-create the table or view when the exported SQL file is run in Batch SQL.
INSERT | Generates INSERT INTO statement(s) that will insert the source table data into the re-created table or view when the exported file is run in Batch SQL.
INDEX | Generates CREATE INDEX statement(s) that will create index(es) for the recreated table when the exported file is run in Batch SQL.
SYNONYM | If synonyms exist for the source table (or view) or for any columns in the source table, this option generates CREATE SYNONYM statement(s) that will create the same synonyms when the exported file is run in Batch SQL.
CHECK | If exporting a table, this option generates an ALTER TABLE command with the CHECK option. You can modify the statement to define the conditions for the check constraint. If exporting a view that was originally created using the WITH CHECK OPTION, the WITH CHECK OPTION is included in the CREATE VIEW statement generated by this utility.
COMMENT | Generates COMMENT ON statement(s) for the table and for each column.
SQL Statement Option | Description
DB2 Options for CREATE TABLE | Enter DB2 options if you are planning to run your exported SQL file on a mainframe DB2 system. Click the Create (Create Table) checkbox to select it, and then click the DB2 button to the right of it to specify mainframe options for the IN DATABASE clause to be generated. These options make the SQL statements more compatible with your target environment.
DB2 Options for CREATE INDEX | Enter DB2 options if you are planning to run your exported SQL file on a mainframe DB2 system. Click the Index checkbox and then click the DB2 button to the right of it to specify DB2 Create Index options. These options make the SQL statements more compatible with your target environment.
Parent topic: Export File Formats Overview


Export NLS Considerations

Restriction: This topic applies to Windows environments only.

You need to be aware of character set conversion issues when exporting data, especially if:

  • Your data contains diacritical (accented) or other characters that lie outside the first half of the ASCII character set
  • Your data was created using a variety of EBCDIC code pages

If you are exporting EBCDIC data using SQL Wizard, we recommend using the DSNTIAUL data format as this enables you to specify an appropriate EBCDIC to ANSI or ANSI to EBCDIC conversion.

You specify the appropriate conversion by picking an entry in the code page window. For example, suppose you want to export a Swedish EBCDIC table. During the export, you would pick the ANSI to EBCDIC translation 1252 - 278.

Parent topic: SQL Wizard


Using Batch Export

Restriction: This topic applies to Windows environments only.

When you enter export specifications and use the Save As command from the File menu, you are to saving the contents of the Export window. The saved file is a Batch Export file containing one export transaction. It has a .exp file name extension. A Batch Export file also can be created using any ASCII text editor. You can preview how an export specification would look as a batch file by clicking on Batch Export Commands from the View menu.

Batch Export is particularly useful when you have a number of similar tables to export, or when you export the same table(s) on a regular basis. Once you have created a Batch Export file you can use it over and over, with or without modification.

Parent topic: SQL Wizard


User Administration

Restriction: This topic applies to Windows environments only.
  • Introducing Administrative Features
  • Managing Users and XDB Server Access Overview
  • Managing Groups Overview
  • Setting XDB Server Priorities
Parent topic: SQL Wizard


Introducing Administrative Features

Restriction: This topic applies to Windows environments only.

This topic provides information on setting up AuthIDs, Groups, and Privileges. In addition, access to the XDB Server can be limited using the Governor features.

The AuthID is used for identification and security purposes when you access an XDB Server, utilities, and database objects. Passwords provide additional access security. Groups enable XDB Server Administrators to easily grant privileges to subsets of the user population who have similar needs. The Governor is used to invoke special access limitations.

System security can be complex. A complete discussion of the inter-relationships of the various security options is provided in "Security and Authority." You should be familiar with that information before setting up system security, AuthIDs, groups, authorities, and privileges.

Information you enter using the Admin menu commands is transformed into standard SQL UPDATE, INSERT, and DELETE statements that are sent to the XDB Server for execution against the appropriate system tables. Other security measures can be activated through the use of the SQL GRANT and REVOKE commands.

Parent topic: User Administration


Managing Users and XDB Server Access Overview

Restriction: This topic applies to Windows environments only.

The Users command on the Admin menu allows an XDB Server Administrator (super user) to add, view, and modify AuthID specifications for all users of the currently connected XDB Server, including whether a password is required at connect time and the type of user (user or super user). The XDB Server Administrator can also assign a selected user to one or more groups, thus providing an easier means of granting database privileges to subsets of the user population who have similar needs. In addition, XDB Server Administrators can remove users (temporarily or permanently), assign priorities to users for XDB Server access, and provide a SecondaryID. (SecondaryIDs provide an alternate means of assigning privileges to groups of users.

When the Users command is selected from the Admin menu, the Add/Modify User dialog box is displayed. This is where you will add, delete, and update AuthIDs.

Parent topic: User Administration


Managing Groups Overview

Restriction: This topic applies to Windows environments only.

A group allows an XDB Server Administrator to control location, database, and table level privileges using a GroupID. An XDB Server Administrator can define groups and assign them to users using the Groups dialog box. Using the SQL GRANT command, database and table privileges are then assigned to the GroupID rather than to each individual user who needs access to those database objects. This method gives the same privilege set to each user in the group. If a user belongs to multiple groups, that user has the privileges of all those groups.

Once a group has been created, it appears in the Group Membership list on the Add/Modify User dialog box. This provides an alternate means of assigning a user to a group.

Note: In some cases it might be better to give users a common Secondary ID.
Parent topic: User Administration


Setting XDB Server Priorities

Restriction: This topic applies to Windows environments only.

Priorities are a set of usage restrictions imposed on an AuthID. Setting priorities gives an XDB Server Administrator the ability to define XDB Server usage priorities for peak hour processing, or to restrict users who do particularly intensive queries to off-peak hours.

You control a user's access to an XDB Server by defining a priority (a set of usage restrictions) and then assigning the priority to the user's AuthID. An AuthID that exceeds any of the limits of it's assigned priority is disconnected from the XDB Server.

Note:

If you are not running against an XDB Server version that supports priorities, or if the XDB Server has the Governor feature turned off, the Priorities command is grayed out on the Admin menu.

A new or changed priority does not take effect until the XDB Server is shut down and restarted.

Priorities are defined through the Define Priority dialog box. Priorities can be defined to limit users by number of API calls, amount of time in the XDB Server SQL engine, amount of time processing calls, amount of idle time and/or the number of fetches. You can also set the times of the day when these limits are in effect.

All the limits set for a priority are checked by the Governor on the XDB Server. Using the Server Configuration utility, you set the MAXIMUM GOVERNOR CYCLE TIME to define how often the governor checks whether a user has exceeded priority limits. To turn off the XDB Server Governor, set this cycle time to zero. Because the frequency with which the governor checks the user's limit status is not infinitely small, it is possible for the limits to be slightly exceeded before the governor takes action. For more information about the Governor features of the XDB Server, see the description of the Maximum Governor Cycle Time option in the section Governor Cycle Timein the chapter Server Configuration Utility in your SQL Option Server Administration Guide.

Parent topic: User Administration


Security and Authority Overview

Restriction: This topic applies to Windows environments only.

XDB Servers provide a full featured security system, including the ability to define Primary Authorization IDs (AuthIDs), SecondaryIDs, and groups for users, the ability to grant and revoke privileges for users and groups at system, database, table, and column levels, and a choice of using a four- to eight-character password mask (with conditions).

  • Security System Concepts
  • Managing System Security and Priorities
  • System Level Access Control
  • Password Enforcement Level
  • XDBACF Database
  • AuthID Types
  • Current SQLID
  • AuthID Ownership and Usage Rules
  • Effect of AuthIDs on Object Names and Usage
  • Granted Authorities and Privileges
  • Predefined XDB Server Authorities for GRANT and REVOKE
  • The DSNDB06 Database
  • Granting and Revoking Privileges
Parent topic: SQL Wizard


Security System Concepts

Restriction: This topic applies to Windows environments only.

XDB Servers are shipped with security turned off to allow you unlimited access to the system. You can continue to operate without security indefinitely, if desired, even in a multi-user environment.

If you do plan to use the XDB Server security features, starting with security off gives you a flexible development environment. You can create locations, databases, and other objects, and set up the required AuthIDs (user names), passwords, groups, and privilege sets you will need for controlling user access before you turn on security.

In a multi-user environment, if security is on at the server, all users must have security on at their individual workstations. If security is off at the server, individual users can have security on, if desired, to protect against unauthorized access at the workstation.

After security is turned on, each user or process must log in with a valid AuthID. If the AuthID has a password defined and required, the password must be entered as well.

To turn server security off, a user must have a valid AuthID with appropriate privileges to be able to access the Security Option in the XDB Server Configuration utility or the Options window as appropriate.

One special AuthID, INSTALL, is created when you install the XDB Server. The INSTALL user is an XDB Server super user. If you do not turn on security, you will not need to be concerned with this special AuthID or its password.

Note:

As long as security remains off and you do not create additional AuthIDs, all objects you create will belong to the Primary AuthID indicated in your Profile (that AuthID becomes the qualifying name in the three-part object name:location-name.authid.object-name). When you install XDB Server, the default AuthID in Options is TUTORIAL. You might wish to change this AuthID if you plan to turn security on and add more users to your system at a later date.

You can change the AuthID that is used for object creator names by any of the following methods:

  • Change each client's Primary AuthID by entering the value into the AUTHID field of the Options dialog box's Connect tab.
  • Issue the SET CURRENT SQLID command before you create the object.
  • Explicitly specify a valid AuthID when you create the object (by specifying a two- or three-part name in the CREATE statement (if specifying a three-part name, the location part of the name must be the current location).

Alternatively, you can create several AuthIDs and grant a different privilege set to each, using these AuthIDs for different purposes. You can also create a group, which allows you to grant the same privilege set to several or many AuthIDs.

When security is on, the super user is a special user. A super user is the only one who can:

  • Create and drop locations.
  • Edit (update) system tables.
  • Assign super-user privileges to another AuthID.

The Admin menu commands are used to assign super-user privileges. The SQL Grant and Revoke commands cannot be used for assigning super-user privileges.

On a multi-user system (or any system where security is an issue), you should assign a password to the INSTALL SUPER USER AuthID. You might wish to set up a few additional AuthIDs with super-user privileges before you turn on security. This allows you to have several other trusted users as a backup to the XDB Server Administrator.

Parent topic: Security and Authority Overview


Managing System Security and Priorities

Restriction: This topic applies to Windows environments only.

SQL Option is provided with the security and administration features you would expect of a database system. Depending on how you intend to use it, however, you might not need to enable the security features. For this reason, your personal XDB Server and its client tools and utilities are initally installed with security switched off.

Security is controlled separately at the server and at the client. If you switch security on for an XDB Server, it can only be accessed by clients that also have security switched on. (In this context, a client is one of the XDB configuration tools or graphical data utilities. The client applications that you develop are expected to handle authorization in the usual way by means of CONNECT statements). If you are developing a DB2 application that handles passwords, you may want to work with a test environment that has security switched on to enable user authentication.

Use the Admin menu of SQL Wizard to manage system security. You can control security at three levels:

  • All users
  • Named groups of users
  • Individual users

When security is switched off for an XDB Server, all users are effectively superusers because:

  • No passwords are required
  • All users share a common AuthID, specified on the Connect tab of the Options utility
  • All users have access to both client and server utilities

Server security status is set using the Server Configuration utility (accessible by clicking SQL For DB2 > XDB Server on the Options menu). Once security has been enabled, users must log on with a valid AuthID and, if required, password. The user's actual AuthID replaces the shared one, which means that a user cannot access a database unless they have been granted the appropriate access privileges by the database owner using GRANT and REVOKE statements.

An AuthID that has been assigned superuser status can change user, group and priority settings that affect all databases on an XDB Server. Initially an AuthID called INSTALL is set as the superuser. If you log on with this AuthID, you can create further superusers as required by clicking Users on the Admin menu and giving each user the appropriate status.

Ordinary users can use the Admin menu only to change their password. Ordinary users who want to change access privileges for specific databases and tables that they own should click New > SQL on the File menu and use the SQL statements GRANT and REVOKE to change access privileges. The AuthID of the creator of a table is deemed to be its owner.

As well as managing system security, a superuser can assign priorities to individual users or groups of users. Priorities control how much processing resource is available to the user or group, depending on criteria set by the superuser.

Note:

When you install SQL Option, the default AuthID is set to TUTORIAL. This AuthID has user privileges and is not authorized to access system tables. This means that, if you switch security on for your personal XDB Server, you cannot use this AuthID to log on to the client utilities.

You should log on using the default superuser AuthID, INSTALL. You can then either set the TUTORIAL AuthID to have superuser status or you can grant it suitable authority on system tables, as appropriate. The INSTALL superuser AuthID has no password assigned initially: you should allocate one to it as soon as possible after switching XDB Server security on.

Parent topic: Security and Authority Overview


System Level Access Control

Restriction: This topic applies to Windows environments only.

System level access control refers to that part of the security system that controls the login process, passwords, the assignment of users to groups, and the definition of SecondaryIDs.

Parent topic: Security and Authority Overview


Password Enforcement Level

Restriction: This topic applies to Windows environments only.

Before setting up initial passwords for users (or before users change their passwords), the XDB Server Administrator (super user) should select a password enforcement level from the options provided in the Options utility. Use the copy of this utility that resides on the XDB Server machine.

Password level options are:

  • Level 1 - Password must be four or more characters.
  • Level 2 - Password must be six or more characters and include at least one digit (numeric).
  • Level 3 - Password must be six or more characters, include at least one digit (numeric), and must include the two randomly generated characters that appear in the prompt message on the User Control screen.

Users can change their passwords by using the CHANGE PASSWORD command from the ADMIN menu.

Note:

If you are using XDB-Link, your XDB Server AuthID and password are passed to the mainframe as a login UserID and password. To successfully access a DB2 location, your XDB Server AuthID and password must be valid on the mainframe system.

Depending on your security needs, you might wish to establish two AuthID/Password accounts on XDB Server, one for times when you are working only on XDB Server locations and one for times when you plan to access a DB2 location.

If you are using a version 2.40 or 2.41 utility or tool with XDB Server Version 3.x (or higher) and XDB Link, other considerations may apply for DB2 access. See the SQL Option Link User's Guide for more information.

Parent topic: Security and Authority Overview


XDBACF Database

Restriction: This topic applies to Windows environments only.

The system location for each XDB Server contains a database called XDBACF (XDB Access Control Facility). This database contains information you enter for each user and group via the Admin menu commands. Information in the XDBACF database applies to all users and all locations on the server.

The XDBACF database contains the following tables and columns. For the specific format of each of these tables, see the topic List Of System Tables.

SYSXDB.SYSACFUSERS Contains a list of all users, including the following information for each user:
  • AuthID
  • SecondaryID
  • Password
  • DateOP (date of password)
  • TimeOP (time of password)
  • AccessAuthority
  • RequirePassword
  • UserType
  • Remarks
Note:

If you are a super user, do not edit or update a user's PASSWORD or TIMEOP information in this table. Use the Admin menu commands instead.

SYSXDB.SYSACFGROUPS Contains a list of all GroupIDs that have been defined. Columns in this table are:
  • GroupAuthID
  • Remarks
SYSXDB.SYSACFMEMBERS Contains a list of AuthIDs and the GroupIDs that each is authorized to use. Each user (Primary AuthID) can have several entries, one entry for each GroupID that the person is authorized to use. Columns in this table are:
  • UserAuthID
  • GroupAuthID
SYSXDB.SYSGOVERNOR Contains information on the type of activities that can be performed by certain users during certain periods. Columns in this table are:
  • EndFreeTime
  • MaxFetches
  • MaxIdleTime
  • MaxNumApiCalls
  • MaxTimeEngine
  • MaxTimePerApi
  • Priority
  • StartFreeTime
SYSXDB.SYSUSERPRIORITY Contains information about priorities that have been assigned to users.
Parent topic: Security and Authority Overview
Related information
System Table Overview


AuthID Types

Restriction: This topic applies to Windows environments only.

Primary AuthIDs, GroupIDs, and SecondaryIDs can be used in combination when setting up system security. These IDs are defined as follows:

  • Primary AuthID
  • Group or GroupID
  • SecondaryID (optional)
  • Current SQLID
  • Primary AuthID
  • Group or GroupID
  • SecondaryID (optional)
Parent topic: Security and Authority Overview


Primary AuthID

Restriction: This topic applies to Windows environments only.

This is the primary identifier for all users of an XDB Server. A Primary AuthID can be assigned to a process or program that requires access to XDB Server data.

  • Used for logging in to an XDB Server.
  • Appears as an identifier on server screens that are used to monitor activity of users.
  • Used as the default for the AuthID portion of a database object's three-part name when the user creates the object. A different ID will become the default if the SET CURRENT SQLID command is issued or if a SecondaryID is defined.
  • Determines privileges when a user attempts to access a database object. If a different ID is in effect (from issuance of a SET CURRENT SQLID command), that ID's privileges are available also. If the Primary AuthID belongs to a group, the privileges granted to the GroupID also are available to the user of the Primary AuthID. If a SecondaryID is defined, the Primary AuthID's privileges are not valid, but rather the SecondaryID's privileges take effect (along with its groups, if any).
Parent topic: AuthID Types


Group or GroupID

Restriction: This topic applies to Windows environments only.

This is a special identifier that can be assigned to one or more Primary AuthIDs. The privileges granted to the GroupID are available to every Primary AuthID to which the GroupID is assigned. In addition, each Primary AuthID can have multiple GroupIDs assigned to it, thus gaining the privileges of all of those groups combined. Other privileges can be granted to the Primary AuthID, providing the user with the assigned group privileges plus the privileges assigned specifically to the Primary AuthID.

Note:

If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.

Parent topic: AuthID Types


SecondaryID (optional)

Restriction: This topic applies to Windows environments only.

If defined, this AuthID replaces the Primary AuthID as soon as the user logs in to the XDB Server. The user (or process) is given the privileges that have been granted to the SecondaryID. If the Primary AuthID had privileges granted to it, those privileges would be ignored. When a user with a SecondaryID creates an object, the AuthID portion of the object's name is the SecondaryID. All other users who use the same SecondaryID will have all privileges on that object.

Note:
  • The XDB Server SecondaryID is not the same as the DB2 Secondary Authorization ID. The IBM method of defining multiple Secondary Authorization IDs and assigning them to Primary AuthIDs in RACF (Resource Access Control Facility) is similar to XDB Server's group concept.
  • If you use an object creator's AuthID as a SecondaryID for other users, those other users will all have all privileges on the object. A user with a SecondaryID is seen by the system as being the SecondaryID, and therefore has all privileges on all objects that carry that AuthID as the second part of the object name. Privileges cannot be revoked from the creator of an object, or from a user who's Current SQLID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on the privileges of an object's creator/owner.
Parent topic: AuthID Types


Current SQLID

Restriction: This topic applies to Windows environments only.

The Current SQLID is a special register that keeps track of which AuthID is in effect for a given client session. A user with SYSADM or super-user authority can issue the SET CURRENT SQLID command to change the SQLID to any valid AuthID. If a user has a SecondaryID, the Current SQLID changes from the Primary AuthID to the SecondaryID at the start of the client session.

Parent topic: Security and Authority Overview


AuthID Ownership and Usage Rules

Restriction: This topic applies to Windows environments only.

When security is on, the Primary AuthID and Password are used when each user (or process) logs in to the XDB Server. The system then checks the SYSXDB.SYSACFUSERS table for the existence of a SecondaryID. If present, the user (or process) assumes the identity of the SecondaryID and is accorded all privileges that have been defined for the SecondaryID. If no SecondaryID exists for the user, then privileges are based on what has been granted for the Primary AuthID and the group(s) to which it belongs.

Multiple users can be assigned the same SecondaryID. In effect, this provides an alternate method for granting a particular set of privileges to a group of users without having to define those privileges for each user individually. The privileges are granted to the SecondaryID (essentially just another AuthID). However, the preferred method for assigning the same privilege set to many users is to use the XDB Server Group, which is similar to the DB2 concept of assigning multiple secondary authorization IDs to a primary authorization in IBM's RACF (Resource Access Control Facility).

Note:

If several users have the same SecondaryID, all the objects they create will be owned by the SecondaryID and not by the individual users. All users having that same SecondaryID will have all privileges on those objects. The GRANT and REVOKE commands have no effect on privileges of an object's creator/owner, which in this case includes all users with the SecondaryID that is also the AuthID portion of the object's name. All of these users are seen by the system as being the owner of the object.

Parent topic: Security and Authority Overview


Effect of AuthIDs on Object Names and Usage

Restriction: This topic applies to Windows environments only.

The following table illustrates how various GroupID and SecondaryID assignments can affect the naming of and access to database objects.

Primary AuthID | Secondary ID | Group Name | Creates Table...1 | Owner | Authorized Users
TECHPUBS | -- | -- | Created as a Primary AuthID. Privileges are assigned. Used as a SecondaryID for one or more Primary AuthIDs.
-- | -- | WRITER | Created as a group. Privileges are assigned to the group. GroupIDs are assigned to Primary AuthIDs.
ERIC | -- | -- | ERIC.TABLE1 | ERIC | ERIC
DEBBIE | -- | -- | DEBBIE.TABLE1 | DEBBIE | DEBBIE
DAVID | -- | WRITERS | DAVID.TABLE1 | DAVID | DAVID and, if access is granted to WRITERS, also ARLENE.
ARLENE | -- | WRITERS | ARLENE.TABLE1 | ARLENE | ARLENE and, if access is granted to WRITERS, also DAVID.
ROCHELLE | TECHPUBS | -- | TECHPUBS.TABLE1 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and, if access is granted to WRITERS, also DAVID, ARLENE.
STEVE | TECHPUBS | -- | TECHPUBS.TABLE2 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and, if access is granted to WRITERS, also DAVID, ARLENE.
PABLO | TECHPUBS | WRITERS (ignored)2 | TECHPUBS.TABLE3 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)
BRUCE | TECHPUBS | WRITERS (ignored)2 | TECHPUBS.TABLE4 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)

1All scenarios described here assume that the user does NOT specify an AuthID when creating the object and the user has NOT changed his Current SQLID.

2Pablo and Bruce do NOT have privileges defined for the group WRITERS because as soon as they log in, they both become TECHPUBS, and TECHPUBS is not assigned to the group WRITERS in this example.

As shown in the table above, the AuthID portion of the name assigned to a database object when it is created, and the users who have access to that object depend on how AuthIDs, GroupIDs, and SecondaryIDs are defined. The object naming and usage rules are as follows:

  • If a user belongs to a group and creates an object, the AuthID portion of the object name will be the user's own Current SQLID, and not the GroupID. This allows more than one user to create objects of the same name within the same location. For example:

    If user DAVID (who is in the WRITERS group) creates a table called STAFF in the location called BOOKS, the table's three-part name would be BOOKS.DAVID.STAFF. If user ARLENE (who is also assigned to the WRITERS group) attempts to create a table called STAFF, the table's three-part name would be BOOKS.ARLENE.STAFF. Since the three-part names of the two tables are unique, each user can have a table of the same one-part name within a location.

    Note:
    • If a user has no Secondary ID and has not otherwise changed his Current SQLID, the Current SQLID is the user's Primary AuthID.
    • If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.
  • If a GRANT command gives privileges to a GroupID, all users who are members of that group will have those privileges.
  • If a user belongs to multiple-groups, the user has privileges that have been granted to all the groups.
  • If a user has a SecondaryID and creates an object, the AuthID portion of the object name will be the SecondaryID (assuming that the user has not changed his Current SQLID, which by default takes the value of the SecondaryID). Two users with the same SecondaryID cannot create objects of the same name within a location. For example:

    If user ROCHELLE (who has a SecondaryID of TECHPUBS) creates a table called STAFF in the location called BOOKS, the table's three-part name would be BOOKS.TECHPUBS.STAFF. If user STEVE (who also has TECHPUBS as his SecondaryID) attempts to create a table called STAFF, the table's three-part name would also be BOOKS.TECHPUBS.STAFF. This is not allowed.

  • Any object whose name has a SecondaryID as the AuthID qualifier can be accessed by any user who has that same SecondaryID as his Current SQLID. GRANT and REVOKE commands have no effect on these users' access to the objects because these users are all seen by the system as being the owner of the object. All users who have the SecondaryID that is the owner of the object will have all privileges on the object.

    Users ROCHELLE, STEVE, PABLO, and BRUCE all have all privileges on TECHPUBS.TABLE1, TECHPUBS.TABLE2, TECHPUBS.TABLE3, and TECHPUBS.TABLE4. GRANT and REVOKE commands for these users and tables will have no effect.

    If an object has a different owner, then granting privileges to the SecondaryID will give those privileges to all users who have that SecondaryID as their Current SQLIDs.

  • If a user has a SecondaryID (as his Current SQLID) and belongs to a group and creates an object, the AuthID portion of the object name will be the SecondaryID. Other users in the group do not have access to the object, because privileges on the object have not been granted to the group. The object is owned by the SecondaryID. Only users with the same SecondaryID (as their Current SQLIDs) can access the object. (However, the original user who created the object of this example can access other objects to which the group has been granted privileges.)
Parent topic: Security and Authority Overview


Granted Authorities and Privileges

Restriction: This topic applies to Windows environments only.

When security is on, databases and tables are protected from being accessed and manipulated unless the user's Current SQLID is either the owner of the object or has been granted specific privileges in the location where the object resides. Privileges can be granted to a Primary AuthID, a GroupID or a SecondaryID.

An AuthID can also be granted an authority, which is a pre-defined set of privileges. Notice that the Authorities are suggestive of different levels of responsibility. These responsibilities might or might not suit your needs.

Privileges (and authorities) can be granted at the location level (SYSADM or SYSCTRL), database level (DBADM, DBCTRL or DBMAINT), or by table or column within a table. AuthIDs must be granted privileges within each location they are authorized to use. Privileges in one location do not carry over to another location.

Note: If using XDB-Link to access a DB2 location from an XDB Server, you must have appropriate authorities granted on DB2 for the objects you will be using in that mainframe location. Authorities and privileges granted on XDB Server (including INSTALL and SYSADM) are not used by the mainframe system.
Parent topic: Security and Authority Overview


Predefined XDB Server Authorities for GRANT and REVOKE

Restriction: This topic applies to Windows environments only.

To assign privileges to a given AuthID in two or more locations, the XDB Server Administrator (super user) can set up groups. Each GroupID is then assigned privileges for one location. The groups that represent the locations for which the user is to be allowed privileges are then assigned to the user's AuthID.

To allow a user to have unlimited privileges throughout the system (all locations), the user's Primary AuthID must be given super-user privileges.

Note:

Only a super user can create locations, drop locations, edit (update) system tables, and assign super-user status to another user. Super-user privileges can be assigned with the ADMIN menu commands, or by editing the USERTYPE column in the user's record in the SYSXDB.SYSACFUSERS table.

Users cannot grant privileges to themselves and cannot revoke privileges from themselves. Likewise, GRANT and REVOKE commands have no effect on users whose AuthIDs (or SecondaryIDs or GroupIDs) are the same as the AuthID portion of an object's name.

Parent topic: Security and Authority Overview


The DSNDB06 Database

Restriction: This topic applies to Windows environments only.

The DSNDB06 database, which is a system catalog database provided in each location, contains the specific authorities and privileges that you define for each AuthID, SecondaryID or GroupID with the SQL GRANT and REVOKE commands. This information is stored in the following security-related tables:

  • SYSIBM.SYSDBAUTH (Database Authorization)
  • SYSIBM.SYSUSERAUTH (User Authorization)
  • SYSIBM.SYSTABAUTH (Table Authorization)
  • SYSIBM.SYSCOLAUTH (Column Authorization)
Parent topic: Security and Authority Overview


Granting and Revoking Privileges

Restriction: This topic applies to Windows environments only.

After the XDB Server Administrator (super user) has set up the AuthIDs, SecondaryIDs and groups, the privileges and authority for each can be defined. This is accomplished with the SQL GRANT and REVOKE commands. You can set up the granted privileges before or after turning on security. However, any grants you issue when security is off will not take effect until you turn security on.

Note: Be sure you are operating in the location for which you want to define privileges. Each location has its own DSNDB06 database for maintaining authorization information. (To change locations, use the SET LOCATION TO command or change your default location on the Options dialog box.)
Parent topic: Security and Authority Overview


Stored Procedures

Restriction: This topic applies to Windows environments only.

A stored procedure is a compiled program that can execute SQL statements. Stored procedures are stored at a local or remote XDB Server. Local XDB Server applications or remote DRDA applications can use the SQL statement CALL to invoke a stored procedure.

Design the application to use stored procedures if the application program operates in a client/server environment, and if either of the following two problems apply:

  • The application accesses host variables for which you want to guarantee security and integrity.
  • The application executes a series of SQL statements, creating many network send and receive operations, which significantly increase CPU and elapsed time costs.

Use of stored procedures removes SQL applications from the workstation, which prevents workstation users from manipulating the contents of sensitive SQL statements and host variables. The use of stored procedures also allows you to combine many of your application's SQL statements into a single message to the DB2 subsystem or XDB Server, reducing network traffic to a single send and receive operation for a series of SQL statements.

Note: If you are running your stored procedure on DB2 MVS, through the XDB Link product, then see your IBM DB2 documentation for other steps necessary to run the stored procedure.

To get a stored procedure up and running:

  1. Code and prepare a stored procedure. See Writing and Preparing Stored Procedures for instructions.
  2. Code and prepare an application that calls the stored procedure. An SQL statement, CALL, in that application must use the same parameter list and linkage convention as the stored procedure that it invokes. See Writing and Preparing Applications to Use Stored Procedures for instructions.
  3. Define your stored procedure to the XDB Server by issuing a CREATE PROCEDURE command, which will place a row in the appropriate SYSIBM table(s). See Defining Stored Procedures under SQL Option for additional details.
  4. Compile and define a LOADLIB entry for your stored procedure. The LOADLIB entry tells the XDB Server where your stored procedure is. See Compiling Stored Procedures under SQL Option for additional details.
  5. Access mainframe tables using stored procedures under SQL Option. The steps necessary to do this are in Accessing Mainframe Tables With Stored Procedures.
  6. Check the current Limitations with Stored Procedures under SQL Option if you experience problems.
  • How an Application Works With a Stored Procedure
  • What You Can Do in a Stored Procedure
  • Preparing Stored Procedures
  • Executing the SQL Statement CALL
  • Linkage Conventions
  • Using Indicator Variables to Speed Processing
  • Declaring Data Types for Passed Parameters
  • Defining Stored Procedures under SQL Option
  • Compiling Stored Procedures under SQL Option
  • Accessing Mainframe Tables with Stored Procedures under SQL Option
  • Limitations with Stored Procedures under SQL Option
  • Stored Procedure Test Tool
Parent topic: SQL Option User Guide


How an Application Works With a Stored Procedure

Restriction: This topic applies to Windows environments only.

A typical stored procedure contains two or more SQL statements, and some manipulative or logical processing that you cannot include in an SQL statement. In this example, your application, CALLSTPR, runs on a workstation client and calls a stored procedure, STPROC1. The following process occurs:

  1. The workstation application establishes a connection to the XDB Server.
  2. The SQL statement CALL tells the XDB Server that the application is going to run the stored procedure, STPROC1. The calling application provides the necessary parameters.
  3. The XDB Server searches the catalog table SYSIBM. SYSROUTINES for rows associated with stored procedure STPROC1.
  4. The XDB Server passes information about the request to the stored procedure.
  5. The stored procedure executes SQL statements.
  6. The stored procedure assigns values to the output parameters and then exits.
  7. Control returns to the calling application, which receives the output parameters. The XDB Server:
    • Closes all cursors that the stored procedure opened that weren't defined as WITH RETURN. Cursors that were defined as WITH RETURN are closed by the XDB Server when a COMMIT WORK command is issued if the WITH HOLD attribute was not declared on the stored procedure generated cursor.
    • Discards all SQL statements that the stored procedure prepared.
    • Reclaims the working storage that the stored procedure used.

    The application can call more stored procedures or it can execute more SQL statements.

  8. Once control is returned to the program that invoked the stored procedure, the XDB Server will treat all the work generated by the stored procedure (and subsequently by the calling program) as a single transaction.
Parent topic: Stored Procedures


What You Can Do in a Stored Procedure

Restriction: This topic applies to Windows environments only.

A stored procedure is similar to any other SQL application.

The following restrictions apply to stored procedures:

  • Both C and COBOL stored procedures must be dynamic link library (DLL) files. See the appropriate language documentation for further information.
  • The XDB Server returns an SQL error code when a location other than the current location is used in an alias or three part name.
  • Do not include these SQL statements in your stored procedure:
    • COMMIT
    • SET CURRENT SQLID

    When these statements are encountered, it places the thread in a must roll back state. When control returns to the calling program, it must do one of the following things:

    • Execute the ROLLBACK statement, so that it is free to execute other SQL statements after rollback is complete.
    • Terminate, causing an automatic rollback of the unit of work.
Parent topic: Stored Procedures


Preparing Stored Procedures

Restriction: This topic applies to Windows environments only.

The following are tasks which must be completed before a stored procedure can be run on an XDB Server:

  1. Prepare the application according to your embedded SQL documentation for creating stored procedure DLLs.
  2. Define the stored procedure to the XDB Server. See Defining Stored Procedures under SQL Option.
  3. Place the stored procedure DLL on the XDB Server machine in a location accessible by the XDB Server. The XDB Server uses the appropriate operating system call for loading the stored procedure, and searches the directory cited by the StProcLoadLib entry in the XDB.INI's server section for that stored procedure.
Parent topic: Stored Procedures
Related information
Defining Stored Procedures under SQL Option
Stored Procedures


Executing the SQL Statement CALL

Restriction: This topic applies to Windows environments only.

Use the CALL statement to execute each series of SQL statements in your application. For example, to call the stored procedure described in How an Application Works With a Stored Procedure, your application might use this statement:

EXEC SQL
  CALL STPROC1
    (:V1, :V2)
END-EXEC

If you use host variables in the CALL statement, you must declare them before using them.

  • The example above is based on the assumption that none of the input parameters can have null values. To allow null values, code a statement like this:
    EXEC SQL
  CALL STPROC1 (:V1 :IV1, :V2 :IV2)
END-EXEC

    where :IV1 and :IV2 are indicator variables for the parameters.

  • To pass integer or character string constants or the null value to the stored procedure, code a statement like this:
    EXEC SQL
  CALL STPROC1 (2, NULL)
END-EXEC
  • To use a host variable for the name of the stored procedure, code a statement like this:
    EXEC SQL
  CALL :PROCNAME (:V1, :V2)
END-EXEC

    Assume that the stored procedure name is STPROC1. The host variable PROCNAME is a character variable of length 254 or less that contains the value STPROC1. You should use this technique if you do not know in advance the name of the stored procedure, but you do know the parameter list convention.

  • To pass your parameters in a single structure, rather than as separate host variables, code a statement like this:
    EXEC SQL
  CALL STPROC1 USING DESCRIPTOR :ADDVALS
END-EXEC

    where ADDVALS is the name of an SQLDA.

  • To use a host variable name for the stored procedure with an SQLDA, code a statement like this:
    EXEC SQL
  CALL :PROCNAME USING DESCRIPTOR :ADDVALS
END-EXEC

    This form gives you extra flexibility because you can use the same CALL statement to invoke different stored procedures with different parameter lists.

    Your client program must assign a stored procedure name to the host variable PROCNAME and load the SQLDA ADDVALS with the parameter information before making the SQL CALL statement.

Each of the above CALL statement examples uses an SQLDA. If you do not explicitly provide an SQLDA, the precompiler generates the SQLDA based on the variables in the parameter list.

You can execute the CALL statement only from an application program. You cannot use the CALL statement dynamically.

Parent topic: Stored Procedures


Linkage Conventions

Restriction: This topic applies to Windows environments only.

When an application executes the CALL statement, the XDB Server builds a parameter list for the stored procedure, using the parameters and values provided in the statement. The XDB Server obtains information about parameters from the catalog table SYSIBM. SYSPARMS See Defining Stored Procedures under SQL Option for more information. Parameters are defined as one of these types in SYSIBM.ROUTINES:

IN | Input-only parameters, which provide values to the stored procedure
OUT | Output-only parameters, which return values from the stored procedure to the calling program
INOUT | Input/output parameters, which provide values to or return values from the stored procedure

If a stored procedure fails to set one or more of the output-only parameters, the XDB Server does not detect the error in the stored procedure. Instead, the XDB Server returns the output parameters to the calling program, with the values established on entry to the stored procedure.

The XDB Server supports the DB2SQL linkage convention, as cited in detail for the CREATE PROCEDURE command.

Parent topic: Stored Procedures
Related information
Defining Stored Procedures under SQL Option
Stored Procedures


Using Indicator Variables to Speed Processing

Restriction: This topic applies to Windows environments only.

If any of your output parameters require a great deal of storage, it is wasteful to pass the entire storage areas to your stored procedure. You can use indicator variables in the calling program to pass only a two-byte area to the stored procedure and to receive the entire area from the stored procedure. To accomplish this, declare an indicator variable for every large output parameter in your SQL statement CALL.

Note:

If you are using the SIMPLE WITH NULLS linkage convention, you must declare indicator variables for all of your parameters, so you do not need to declare another indicator variable for the large output parameters.

Assign a negative value to each indicator value associated with a large output variable. Then include the indicator variables in the CALL statement. This technique can be used whether the stored procedure linkage is SIMPLE or SIMPLE WITH NULLS.

For example, suppose that a stored procedure, STPROC2 defined with the SIMPLE linkage convention takes one integer input parameter and one character output parameter of length 5000. It is wasteful to pass the 5000 byte storage area to the stored procedure. Instead, a COBOL program containing these statements passes only two bytes to the stored procedure for the output variable and receives all 5000 bytes from the stored procedure:

INNUM    PIC S9(9) COMP
OUTCHAR  PIC X(5000)
IND    PIC S9(4) COMP
.
.
.
MOVE -1 TO IND
EXEC SQL CALL STPROC2(:INNUM, :OUTCHAR :IND);
Parent topic: Stored Procedures


Declaring Data Types for Passed Parameters

Restriction: This topic applies to Windows environments only.

A stored procedure must declare each parameter passed to it. In addition, the TYPENAME column of the catalog table SYSIBM.SYSPARMS must contain a compatible SQL data type declaration for each parameter. For TYPENAME string and corresponding language declarations, see the SQL data types table in the appropriate precompiler manual.

Parent topic: Stored Procedures


Defining Stored Procedures under SQL Option

Restriction: This topic applies to Windows environments only.

A stored procedure is unusable until it is defined - use the CREATE PROCEDURE command to do this. At the command's conclusion, a record is placed in the SYSIBM.SYSROUTINES This record is used by the XDB Server when the stored procedure is executed.

The following is an example of a CREATE PROCEDURE command:

  create procedure MYAUTHID.STPROC1 (
             in    in1    char(4),
             out  out1  char(4),
             out  out2   smallint
   )
   external name STPROC1
   parameter style general with nulls
   language cobol
   collid  MYCOLLID
   result sets 1
   commit on return no
   ;

The create procedure statement must uniquely identify a stored procedure. You cannot have more than one row in SYSIBM.SYSROUTINES with the same values for the PROCEDURE, AUTHID, and LUNAME columns because the combination of PROCEDURE, AUTHID, and LUNAME uniquely identifies a stored procedure. You also will provide specific application information, such as what language the stored procedure is written in, whether you are using result-sets, what parameters are passed, and how they are passed.

Parent topic: Stored Procedures
Related reference
CREATE PROCEDURE
Related information
SYSIBM.SYSROUTINES


Compiling Stored Procedures under SQL Option

Restriction: This topic applies to Windows environments only.

To compile a stored procedure under SQL Option, carry out the following steps:

  1. The project used for stored procedure development should always be declared as "Uses SQL". To indicate that an existing project uses SQL, click Project Settings on the Project menu, then select Project uses SQL on the SQL tab.
  2. To use the ECM SQL preprocessor, check the Preproc tab of the Build Settings dialog box and ensure that EXEC SQL is checked. If additional directives are needed, for instance the PKGSET directive to emulate SET CURRENT PACKAGESET functionality, click the More button next to the EXEC SQL checkbox and specify the directives there.
  3. SQL Option requires a LOADLIB directory to be able to find .dll files that execute as stored procedures. When Enterprise Developer compiles programs, it typically places the .dll files in a LOADLIB directory under the project directory.
Parent topic: Stored Procedures


Accessing Mainframe Tables with Stored Procedures under SQL Option

Restriction: This topic applies to Windows environments only.

You can set up a special location to access mainframe tables from a stored procedure. Since the stored procedure must run under the XDB engine, the current location must be an SQL Option location. Access to DB2 tables and views is provided by using aliases.

To activate this functionality, the STProcRemoteAccess variable must be set to one in the server section of the xdb.ini file which, in Windows environments, is in the %ProgramData%\Micro Focus\Enterprise Developer\mfsql\cfg directory. The following is an example of setting the STProcRemoteAccess variable (applies to Windows environments only):

[CLIENT]
XDBCFG=c:\mfuser\config\
[SERVER]
XDBSERVE=myserver
XSRVCFG=c:\mfuser\config
StProcLoadLib=c:\mfuser\projects\MyProject\LOADLIB;c:\mfuser\projects\MyProject2\LOADLIB
StProcAnimate=yes
STProcRemoteAccess=1
.
.
.

You can easily create aliases for mainframe tables using the CREATE ALIAS SQL command. If you can use a three-part name to select from a table on the mainframe, the CREATE ALIAS command can be used to alias that table.

For instance, if the following command returns rows:

select * from MFLOCATION.MYAUTHID.MYTABLE;

an alias can be created in the MYLOCAL location using the following command:

create alias MYAUTHID.MYTABLE for MFLOCATION.MYAUTHID.MYTABLE;

CREATE ALIAS statements can be generated using SQL SELECT statements and the remote locations metadata. For instance, the following query will generate CREATE ALIAS syntax for all tables in a DB2 location that don't have a creator of SYSIBM:

SELECT 'CREATE ALIAS '
                  CONCAT
                  STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
                  CONCAT
                  ' FOR '
                  CONCAT
                  STRIP(CURRENT SERVER, TRAILING, ' ') CONCAT '.' CONCAT
                  STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
                  CONCAT
                  ';'
FROM SYSIBM.SYSTABLES
WHERE CREATOR NOT IN ('SYSIBM')
ORDER BY 1
FOR FETCH ONLY;

If the above query is run under SPUFI, you must take care to set up the SPUFI defaults appropriately - you need to ensure that settings such as MAX SELECT LINES in SPUFI are set to enable all the rows to be returned. Using SPUFI, the output data set will have output that looks as follows:

---------+---------+---------+---------+---------+---------+---------+---------
CREATE ALIAS MYAUTHID.PROC_TEST_TAB_1 FOR CSIMVSDB2.MYAUTHID.PROC_TEST_TAB_1;
CREATE ALIAS MYAUTHID.PROC_TEST_TAB_2 FOR CSIMVSDB2.MYAUTHID.PROC_TEST_TAB_2;
CREATE ALIAS MYAUTHID.PROC_TEST_TAB_3 FOR CSIMVSDB2.MYAUTHID.PROC_TEST_TAB_3;

The query can be adjusted to retrieve the tables necessary by using sub-queries or joins to limit the data retrieved. The following is an example of generating CREATE ALIAS commands for all tables and views within a particular DB2 database. Note that this query will not retrieve tables in other databases that are referenced by the views.

SELECT 'CREATE ALIAS '
       CONCAT
       STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
       CONCAT
       ' FOR '
       CONCAT
       STRIP(CURRENT SERVER, TRAILING, ' ') CONCAT '.' CONCAT
       STRIP(CREATOR, TRAILING, ' ') CONCAT '.' CONCAT NAME
       CONCAT
       '; -- ALIAS OF TABLE'
  FROM SYSIBM.SYSTABLES
 WHERE DBNAME = 'MYDB2DB'
   AND TYPE = 'T'
 UNION
SELECT 'CREATE ALIAS '
       CONCAT
       STRIP(SVDP.DCREATOR, TRAILING, ' ') CONCAT '.' CONCAT SVDP.DNAME
       CONCAT
       ' FOR '
       CONCAT
       STRIP(CURRENT SERVER, TRAILING, ' ') CONCAT '.' CONCAT
       STRIP(SVDP.DCREATOR, TRAILING, ' ') CONCAT '.' CONCAT SVDP.DNAME
       CONCAT
       '; -- ALIAS OF VIEW'
  FROM SYSIBM.SYSTABLES  STBL,
       SYSIBM.SYSVIEWDEP SVDP
 WHERE STBL.DBNAME = 'MYDB2DB'
   AND STBL.TYPE = 'T'
   AND STBL.CREATOR = SVDP.BCREATOR
   AND STBL.NAME  = SVDP.BNAME
 ORDER BY 1
   FOR FETCH ONLY
;

Because the stored procedure is running under the SQL Option engine and DB2 is being used only for the retrieval of data, certain operations must still be set up under the SQL Option engine. In particular, SET CURRENT PACKAGE SET commands must be set up under SQL Option. SET CURRENT PACKAGE SET commands will not be passed to the mainframe DB2 region since the identification of data entities must take place under the SQL Option engine. Additionally, SYNONYMS must be created on the SQL Option location if your DB2 processing uses SYNONYMS.

Parent topic: Stored Procedures


Limitations with Stored Procedures under SQL Option

Restriction: This topic applies to Windows environments only.

You should be aware of the following limitations when working with stored procedures under SQL Option:

  • Stored procedures cannot be debugged when the XDB server is running as a service.
  • We recommend you do not use STOP RUN statements within a stored procedure. If you use STOP RUN instead of GOBACK you will receive a -471 sqlcode on the EXEC SQL CALL STATEMENT.

    Note that IBM also recommends against the use of STOP RUN statements in stored procedures. This is because in the DB2 subsystem, a STOP RUN terminates the Language Environment enclave, so the next time a DB2 stored procedure is called, the Language Environment enclave has to be rebuilt. This extra work being done by the DB2 region severely impacts the benefits of running the stored procedure as a DB2 subprogram.

  • Currently, the VALIDATE preprocessor directive will provide minimal assistance with stored procedure SQL statements (CALL, ASSOCIATE, ALLOCATE).
  • No support is provided for performing a PREPARE statement using ALLOCATE CURSOR or ASSOCIATE LOCATORS syntax. ALLOCATE CURSOR and ASSOCIATE LOCATORS statements must be embedded within the SQL language EXEC SQL ... END-EXEC delimiters. ALLOCATE CURSOR and ASSOCIATE LOCATORS statements cannot be dynamically prepared.
Parent topic: Stored Procedures


Stored Procedure Test Tool

Restriction: This topic applies to Windows environments only.

The Stored Procedure Test tool (SP Test tool) makes the testing of stored procedures easier. It enables you to test various input values for a stored procedure, see the results, and optionally create test scripts without having to write COBOL code to invoke the stored procedure. However, if you want to invoke the stored procedure from a COBOL program, the tool also provides an option that enables you to generate such a program containing all of the required COBOL host variables.

The Stored Procedure Test tool also provides three wizards that enable you to generate both the SQL and the COBOL code for stored procedures, external table functions, and external scalar functions:

The SP Test tool accesses your stored procedures by connecting to the XDB server you specify, building a list of stored procedures and functions defined for that server.

  • Options
  • Testing a Stored Procedure
  • Test Scripts
  • Generating a COBOL Program
  • Command Line Interface
  • How to...
Parent topic: Stored Procedures
Related tasks
To start the Stored Procedure Test tool


Options

Restriction: This topic applies to Windows environments only.

The SP tool comes configured to test your stored procedures using a set of default options. You can change the default options to customize the behavior of the SP Test tool. For example, you can set startup, execution and testing options, control the generation of COBOL code and certain files, specify a particular editor, specify directories, and set Wizard options.

You can set the following options to control the behavior of the SP Test tool. Default settings appear in a regular typeface. Non-default settings, directories and filenames appear bold. Read-only options are grayed-out.
Generate COBOL Code Generates a COBOL program that invokes:
  • The stored procedure
  • Result sets generated by the stored procedure
  • Host variables required to invoke the appropriate functions

Default: True

COBOL Specifies the directory where the SP Test tool stores the COBOL it generates, if any.

Default: %LOCALAPPDATA%

Input Saved Parameters Specifies the directory where the SP Test tool retrieves the XML file containing input parameters.

Default: %LOCALAPPDATA%

Output Saved Parameters Specifies the directory where the SP Test tool stores the XML file it generates containing output parameters.

Default: %LOCALAPPDATA%

Stored Procedures Specifies the debug directory for stored procedures. You must set this option before attempting to debug a stored procedure to prevent it from hanging during execution.

Default: %LOCALAPPDATA%.

Use Project Settings Specifies whether or not to apply the settings defined for the current project to the SP Test tool as well.

Default: False

Editor for Side Files Optionally provide the full path and executable filename of a non-Micro Focus editor you want to use to edit side files.

Default: Blank

Allow Output Side Files Enable the SP Test tool to save output results in a side file rather than viewing them on-screen. This is useful when large amounts of data are returned for a parameter.

Default: False

Alternate Entry Map Name Optionally specify the path to a directory that contains entry point map files.

Default: Blank

Timeout

The amount of time in milliseconds to process requests, such as REFRESH, before being prompted to continue waiting. To turn this option off, set the value to 0.

Default: 5000 (equivalent to 5 seconds)

Automatically Save Input File Save input files in XML format, automatically generating input filenames based on the value of the Format Input Filename field. This option is automatically set to False if you have set the Format Input Filename to No Default Format, and is automatically set to True when Format Input Filename is set to either Stored Procedure name + “_IN_” + current date or Stored Procedure name + “_IN_” + number.

Default: True

Encoding of Side Files Specify the type of encoding to use for side files. Available types are:
  • ASCII
  • EBCDIC
  • UNICODE
Note:

If you specify EBCDIC, the tool translates the value to ASCII using the Micro Focus codeset defined for your machine.

Default: ASCII

Format Input File Name Set a default filename format for generated XML input files, or specify no default filename format. The XDB Stored Procedure Test tool uses the specified format for input files when Automatically Save Input File is set to True. The options are:
  • Stored procedure name + “_IN_” + number
  • Stored procedure name + “_IN_” + current date
  • No default format

Default: Stored procedure name + “ _IN_” + number

Format Output File Name Set a default filename format for generated XML output files, or specify no default filename format. The options are:
  • Stored procedure name + number
  • Stored procedure name + current date
  • No default format

Default: Stored procedure name + number

Generate Output File Name Save output files in XML format, automatically generating ouput filenames based on the value of the Format Output Filename field. This option is automatically set to False if you have set the Format Output Filename to No Default Format, and is automatically set to True when Format Output Filename is set to either Stored Procedure name + current date or Stored Procedure name + number.

Default: True

Refresh List on Startup Build a new list of stored procedures and functions each time you invoke the XDB Stored Procedures Test tool, saved to a local XML file. For this option to work properly, you must have the XDB Server started before you invoke the tool.
Note: We recommend disabling this option in cases where the time required to rebuild the list is prohibitive, for example, when connecting to a mainframe DB2 server using XDB LINK. When disabled, the tool presents the list from your previous session. You can then refresh the list manually by clicking Refresh list of stored procedures.

Default: True

Test Coverage Config File Specify the configuration file to use when executing the stored procedure in test coverage mode. This is only applicable if you have set the Use Test Coverage option to True.

Default: Blank

Use Test Coverage Specify whether or not the tool executes stored procedures in test coverage mode.

Default: False

Test Script Generation Set the tool either to write the commands used to test a stored procedure to an ASCII command file, or to not save the commands. The options are:
  • Automatically save commands
  • Prompt before saving
  • Don't save commands

See the section Test Scripts for more information.

Default: Automatically save commands

Abend Options Specifies the behavior of the routine when it encounters a failure. The options are as follows:
  • Use Default Setting
  • STOP AFTER SYSTEM DEFAULT FAILURES
  • STOP AFTER nn FAILURES
  • CONTINUE AFTER FAILURE
Note: If you select STOP AFTER nn FAILURES, you must specify the number of failures (represnted by "nn") in the Abend field on the Wizard's Specify Options page.

Default: Use Default Setting1

ASU Time | Specifies the total amount of processor time, in CPU service units, that a single invocation of the routine can run. Default: 0
Commit on Return Specifies whether or not DB2 commits the transaction immediately upon return from the routine. The options are:
  • Use Default Setting
  • YES
  • NO

Default: Use Default Setting1

DBINFO Parameter Specifies whether or not additional status information is passed when the routine is invoked.
Note:

This parameter is used only when the Parameter Style option is set to SQL.

Default: False

DETERMINISTIC | Specifies whether or not the routine returns the same results each time it is called with the same IN and INOUT arguments. Default: False
Dynamic Result Sets | Specifies the maximum number of result sets that the routine can return. Default: 0
Execute on FINISH | Specifies whether or not the Wizard executes the generated routine when you click Finish. Default: False
Fenced | Specifies whether or not the routine runs in an external address space to prevent user programs from corrupting DB2 storage. Default: False
Parameter CCSID Specifies the encoding scheme for string parameters. The options are:
  • ASCII
  • EBCDIC
  • UNICODE

Default: EBCDIC

Parameter Style Specifies the linkage convention used to pass parameters to and return values from the routine. The options are:
  • GENERAL
  • GENERAL WITH NULLS
  • SQL

Default: GENERAL

Language Specifies the language used to interface with the routine. The options are:
  • COBOL
  • C
  • PLI
  • ASSEMBLER
  • REXX

Default: COBOL

Run-time options | Specifies the Language Environment run-time options for the routine. Default: none (blank)
Security Specifies how the routine interacts with an external security product to control access to non-SQL resources. The options are:
  • Use Default Setting
  • DB2
  • USER
  • DEFINER

Default: Use Default Setting1

SQL Statement Defaults Specifies which SQL statements, if any, can be executed in this routine or any routine that is called from this routine. The options are:
  • Modifies SQL Data
  • Reads SQL Data
  • Contains SQL
  • No SQL

Default: Modifies SQL Data

Stay Resident Specifies whether or not the routine's load module remains resident in memory when the routine ends.

Default: False

Use Default Special Register Specifies whether or not special registers are initialized to the default values.

Default: False

WLM Environment Specifies the name of the WLM (workload manager) environment in which the routine is to run when the DB2 stored procedure address space is WLM-established.

Default: Blank

1The default setting for this option depends on the type of code the Wizard is generating - stored procedure, external table function, or external scalar function. The default setting for each type of code is that which appears in the field corresponding to this option when you first invoke the Wizard's Specify Options page.

Note: You can override Wizard options on the Specify Options page of each wizard.
Parent topic: Stored Procedure Test Tool
Related concepts
Test Scripts
Related tasks
To set Stored Procedure Test tool options
To generate a stored procedure
To generate an external table function
To generate an external scalar function


Testing a Stored Procedure

Restriction: This topic applies to Windows environments only.

Once you have started and configured the SP Test tool, you are ready to test your stored procedures. These are listed on the IDE by schema name in the tree view on the left under Stored Procedures. The procedure to test a stored procedure is as follows:

  1. Set input and output parameters
  2. Specify filenames for generated files
  3. Execute the stored procedure
  4. Read the results
  • Setting Input and Output Parameters
  • Specifying Filenames for Generated Files
  • Executing a Stored Procedure
  • Testing with Third-party Software
  • Reading Test Results
  • Displaying Saved Results
Parent topic: Stored Procedure Test Tool


Setting Input and Output Parameters

Restriction: This topic applies to Windows environments only.

You can optionally provide a value for each input and/or output parameter associated with the stored procedure. All parameters defined in a stored procedure selected in the tree view appear on the Parms tab. Input parameters are identified by either a P (for input) or a B (for input/output) in the I/O column. Output parameters are identified by an O in the I/O column.

You assign a value to an input parameter using one of the following methods:

  • Type the value directly into the Value field
  • Type the value into the Edit Entry Value editor
  • Specify a side file (.dat file) to contain the value
  • Specify a special register that defines the value

If you want to store the value of an output parameter as the stored procedure executes, set the Allow Output Side Files option to True. This enables you to specify a side file or a special register to hold the value.

Note: If you want to specify an EBCDIC side file to contain the value but do not already have one available, you can create one.
Parent topic: Testing a Stored Procedure
Related tasks
To specify an input parameter value for a stored procedure
To edit an input parameter value for a stored procedure
To specify a side file for a parameter value
To specify a special register for a parameter value


Specifying Filenames for Generated Files

Restriction: This topic applies to Windows environments only.

You can set your options to automatically generate filenames for XML input and output files, and to also automatically generate a filename for generated COBOL code using default file naming conventions. However, you can also specify your own filenames for these files from the Files tab.

Parent topic: Testing a Stored Procedure
Related tasks
To set Stored Procedure Test tool options
To specify input, output, and generated COBOL filenames


Executing a Stored Procedure

Restriction: This topic applies to Windows environments only.

You must have specified a default filenaming convention for input and output files via the Options dialog box or have specified input and output filenames via the Files tab before your stored procedure will execute. If no filename or filenaming convention is specified, the SP Test tool calls the Files tab before executing the stored procedure, requiring you to specify the appropriate filenames at that time.

The results of the stored procedure execution are automatically displayed on the Results tab following execution.

Parent topic: Testing a Stored Procedure
Related concepts
Reading Test Results
Related tasks
To execute a stored procedure
To set Stored Procedure Test tool options


Testing with Third-party Software

Restriction: This topic applies to Windows environments only.

You can use the SP Test tool to generate an ASCII or a hexadecimal text string command that can run your stored procedure in a third-party test tool. Before generating the command, be sure you have specified all of the appropriate input parameters.

Parent topic: Testing a Stored Procedure
Related tasks
To generate a test command


Reading Test Results

Restriction: This topic applies to Windows environments only.

The Results tab shows you the following information:

Type or RS Name

Shows whether this is a parameter or a result set. Result set names correspond to the cursor name defined in the DECLARE CURSOR statement.

Data Name

The parameter name or the column name of the data in the result set.

Row Number

Parameters display a row number of 0; result sets display the row number fetched from the result set that corresponds to the cursor name defined in the DECLARE CURSOR statement.

Value

  • Input - the value of the input parameter
  • Output - the value of the output parameter
  • Input only side file - the value that was found in the side file
  • Input/Output or Output side file - the side file name
  • Special register - the name of the special register (not the value of the special register)
Note:

Reporting the name of the special register rather than its value makes it somewhat easier to do regression testing in that you get consistent results when using special registers such as CURRENT DATE.

Parent topic: Testing a Stored Procedure
Related concepts
Displaying Saved Results


Displaying Saved Results

Restriction: This topic applies to Windows environments only.

In addition to viewing the results each time you test a stored procedure, you can also view the results of any previously run stored procedure using the Display Saved Results command. This command enables you to choose any saved XML output file for viewing on the Results tab or on one or more customized tabs. Each customized tab displays one result set, and the name of the tab is the same as the SQL cursor name used to produce the result set. All information on customized tabs is displayed in a familiar tabular format with column names in the data grid taken from the columns names used in the query that selected the data.

Parent topic: Testing a Stored Procedure
Related concepts
Reading Test Results
Related tasks
To display saved results from output XML


Test Scripts

Restriction: This topic applies to Windows environments only.

You can save the commands that the SP Test tool uses to test a stored procedure as a script that you can execute without having to reset options, input and output parameters, or filenames. This enables you to easily retest your stored procedures.

Test scripts are saved as ASCII command files in the following format:

TEST_storedprocedurename.cmd

Test script files are stored in the same directory as is specified for the COBOL option on the Options dialog box.

Each script includes the input and output file names used when the stored procedure is executed. The following is an example test script named TEST_GETEMPD.cmd:

MFXDBRUNSP IN=G:\temp\xml\GETEMPD_IN_0001.xml; OT=G:\temp\xml\GETEMPD_OUT_0001.xml;
MFXDBRUNSP IN=G:\temp\xml\GETEMPD_IN_0002.xml; OT=G:\temp\xml\GETEMPD_OUT_0002.xml;

This script runs two commands, one using XML input file GETEMPD_IN_0001.xml and another using XML input file GETEMPD_IN_0002.xml. The “OT” token specifies an output XML file.

The SP Test tool automatically creates a script file for each stored procedure you execute if you set the Test Script Generation option to Automatically save commands or Prompt before saving.

You can edit a generated test script in any text editor. You can also write your own test scripts by creating a command file that invokes individual stored procedure test scripts. See the topic Command Line Interface for additional commands you can specify in a test script.

Parent topic: Stored Procedure Test Tool
Related concepts
Options
Command Line Interface
Related tasks
To set Stored Procedure Test tool options


Generating a COBOL Program

Restriction: This topic applies to Windows environments only.

When you set the Generate COBOL Code option to True, the SP Test tool automatically generates a COBOL program that calls the stored procedure. This COBOL program reflects the extent to which code was executed when you ran the stored procedure. If an error occurs within the stored procedure, the generated program is incomplete.

You can view the generated program on the Code tab after the stored procedure executes. Parameter values are generated as host variable names unless you specified a special register. In that case the special register name is generated as part of the EXEC SQL CALL statement. For example:
EXEC SQL
  CALL GETEMPD2 (CURRENT TIMESTAMP - 255 DAYS, :GETEMPD2-RSLT)
END EXEC
Parent topic: Stored Procedure Test Tool
Related tasks
To set Stored Procedure Test tool options
To specify input, output, and generated COBOL filenames


Command Line Interface

Restriction: This topic applies to Windows environments only.
You can run stored procedures generated by the SP Test tool from the command line using the following syntax:
inputfilename; OT=<outputfilename; CD=<COBOLfilename
Where inputfilename is the full path to and filename of the XML input file, outputfilename is the full path to and filename of the XML output file, and COBOLfilename is the name of the generated COBOL program file. To execute multiple commands separate each command with a semi-colon (;).
Parent topic: Stored Procedure Test Tool
Related concepts
Test Scripts
Related tasks
To display saved results from output XML
To specify input, output, and generated COBOL filenames


How to...

Restriction: This topic applies to Windows environments only.
  • To start the Stored Procedure Test tool
  • To set Stored Procedure Test tool options
  • To edit the list of stored procedures displayed
  • To specify an input parameter value for a stored procedure
  • To edit an input parameter value for a stored procedure
  • To specify a side file for a parameter value
  • To specify a special register for a parameter value
  • To specify input, output, and generated COBOL filenames
  • To execute a stored procedure
  • To generate a stored procedure
  • To display saved results from output XML
  • To generate a test command
  • To generate an external table function
  • To generate an external scalar function
Parent topic: Stored Procedure Test Tool


To start the Stored Procedure Test tool

Restriction: This topic applies to Windows environments only.
In standalone mode
Windows 7 and Earlier
  • From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2 > Client > Stored Procedure Test tool.
Windows 8.1
  • From the Windows Start screen, click the Stored Procedure Test tool tile.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2 > Client > Stored Procedure Test tool.
From Eclipse:
  • From your Windows desktop, click Run > Tools > Data Tools > SQL Option for DB2 > Client > Stored Procedure Tool.
Parent topic: How to...
Related concepts
Stored Procedure Test Tool


To set Stored Procedure Test tool options

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool toolbar, click Options Options.
  2. Scroll to the option you want to set and click its corresponding field in the right-hand column.
  3. Change the value in this field using one of the following mechanisms, depending on which is available:
    • Type a value directly into the field
    • Browse to a path and/or filename by clicking Browse Browse
    • Select a value from the drop-down menu
Note: Default settings appear in a regular typeface. Non-default settings, directories and filenames appear bold. Read-only options are grayed-out.
Parent topic: How to...
Related concepts
Options
Test Scripts
Specifying Filenames for Generated Files
Executing a Stored Procedure
Reading Test Results
Generating a COBOL Program


To edit the list of stored procedures displayed

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool, right-click anywhere on the tree view; then click Edit List of Stored Procedures Displayed.
  2. If you have checked Also remove from database, the SP Test tool invokes the File Name to Save Drop Commands dialog box. Here, you specifiy the name of a command file that the SP Test tool generates to drop the checked stored procedures from their XDB location(s). The SP Test tool executes this command file when you click Save.
  3. Check the box to the right of each stored procedure you want to remove from the list.
  4. If you want to remove the checked stored procedures from the repository as well as the displayed list, check Also remove from database (optional).
  5. Click Remove to remove the checked stored procedures.
Note: If you leave Also remove from database unchecked, stored procedures you have removed from the list reappear when you start the Stored Procedure Test tool again, or when you click Refresh list of stored procedures Refresh list of stored procedures.
Parent topic: How to...


To specify an input parameter value for a stored procedure

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, click the Value column corresponding to the parameter whose value you want to specify.
  3. Type the value of the parameter.
  4. Tab to another column to ensure that the value is saved properly.
Note:
  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • You can also specify a value using the Edit Entry Value editor or by specifying a side file or special register.
  • Values typed directly into the Value field or into the Edit Entry Value editor are limited to the length of the parameter.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To edit an input parameter value for a stored procedure
To specify a side file for a parameter value
To specify a special register for a parameter value


To edit an input parameter value for a stored procedure

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, right-click the Value column corresponding to the parameter whose value you want to edit, then click Edit value.
  3. In the Edit Entry Values editor, type the value of the parameter.
  4. Click OK.
  5. Tab to another column to ensure that the value is saved properly.
Note:
  • To view or enter the value in hexadecimal, check Display value in hexadecimal.
  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • You can also specify a value by entering it directly into the Value column or by specifying a side file or special register.
  • Values typed directly into the Value field or into the Edit Entry Value editor are limited to the length of the parameter.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To specify an input parameter value for a stored procedure
To specify a side file for a parameter value
To specify a special register for a parameter value


To specify a side file for a parameter value

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, right-click the Value column corresponding to the parameter whose value you want to edit, then click Insert side file.
  3. Navigate to the side file (.dat file) you want to use, or type the full path and filename of the side file into the File name field, then click Open.
  4. On the SP Test tool IDE, tab to another column to ensure that the value is saved properly.
Note:
  • The side file specification appears in the Value column in the following format:

    <SF=path/filename>

    If you have set the Encoding of Side Files option to EBCDIC, <ENC=E> is appended to the end.

  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • For input parameters, you can also specify a value by entering it directly into the Value column, using the Edit Entry Values editor, or by specifying a special register.
  • You cannot specify a side file to store an output parameter value unless you have set the Allow Output Side Files option to True.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To specify an input parameter value for a stored procedure
To edit an input parameter value for a stored procedure
To specify a special register for a parameter value


To specify a special register for a parameter value

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Parms tab, right-click the Value column corresponding to the parameter whose value you want to edit, then click Insert special register.
  3. From the drop-down menu that appears, click the special register you want to use to store the parameter value.
  4. Click Insert special register again to paste the reference into the Value column.
Note:
  • The special register specification appears in the Value column in the following format:

    <SR=specialregistername>

    Do not manually modify the SR= portion of this specification. Doing so can cause the stored procedure to execute improperly.

    However, you can modify the specialregistername portion of the specification by typing over it. For example, if you selected the CURRENT DATE special register, you could modify it to be CURRENT DATE - 100 DAYS which is then used instead of CURRENT DATE. Be advised that modified special registers cannot be validated.

  • Numeric parameter values must be valid for the stored procedure to execute properly.
  • For input parameters, you can also specify a value by entering it directly into the Value column, using the Edit Entry Values editor, or by specifying a side file.
  • You cannot specify a special register to store an output parameter value unless you have set the Allow Output Side Files option to True.
Parent topic: How to...
Related concepts
Setting Input and Output Parameters
Related tasks
To specify an input parameter value for a stored procedure
To edit an input parameter value for a stored procedure
To specify a side file for a parameter value


To specify input, output, and generated COBOL filenames

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool, click a stored procedure on the tree view.
  2. On the Files tab in the appropriate field, type the full path to and filename of the file you want to specify, or click the field's corresponding Browse Browse button to navigate to and select an appropriate file.
Note:
  • The Files tab automatically appears when you run a stored procedure for which no input or output filenames have been specified either directly or by selecting filenaming conventions via the Options dialog box, enabling you to specify these filenames at that time.
  • If you have set your Options to automatically generate COBOL code but have not specified a filename on the Files tab, the Files tab appears automatically when you run the stored procedure, enabling you to specify the filename at that time.
Parent topic: How to...
Related concepts
Specifying Filenames for Generated Files
Generating a COBOL Program
Command Line Interface


To execute a stored procedure

Restriction: This topic applies to Windows environments only.
  • From the SP Test tool, click a stored procedure on the tree view, then click Run Run.
Note:
  • The Files tab automatically appears when you run a stored procedure for which no input or output filenames have been specified either directly or by selecting filenaming conventions via the Options dialog box, enabling you to specify these filenames at that time.
  • If you have set your Options to automatically generate COBOL code but have not specified a filename on the Files tab, the Files tab appears automatically when you run the stored procedure, enabling you to specify the filename at that time.
  • If you have set the Prompt Save Script option to True, you are prompted after the stored procedure executes to save or not save the command in the test script. If the stored procedure encounters errors while executing you do not receive this prompt.
Parent topic: How to...
Related concepts
Executing a Stored Procedure
Reading Test Results


To generate a stored procedure

Restriction: This topic applies to Windows environments only.
  1. Start the Stored Procedure Test tool.
  2. Click Create a new Stored Procedure Create new stored procedure.
  3. Complete each page of the Wizard. For help on a specific page and help on a specific field or control on a page, click Help.
Note: The Wizard writes one COBOL and one SQL file containing the generated code. The location of these files is specified in your SP Test tool Options, and the filenames are as follows:
  • SQL file - procedurename.sql
  • COBOL file - procedurename.cbl
Parent topic: How to...
Related concepts
Options
Related tasks
To generate an external table function
To generate an external scalar function


To display saved results from output XML

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool tree view, right-click the Stored Procedure for which you want to display saved results; then click Display Saved Results.
  2. From the Select Results to be Displayed dialog box, click the XML output file that contains the results you want to display; then click Open.
  3. Click the customized tab for the result set you want to view.
  4. Use Next and Previous to browse through the results sets.
Parent topic: How to...
Related concepts
Displaying Saved Results
Command Line Interface


To generate a test command

Restriction: This topic applies to Windows environments only.
  1. From the SP Test tool tree view, right-click the Stored Procedure for which you want to generate a test command; then click Generate Test Command.
  2. From the Generate Stored Procedure Test Command dialog box, highlight the generated command.
  3. Right-click the highlighted command and click copy or cut from the menu.
    Note: If you want a hexadecimal equivalent for the command, check Display value in hexadecimal before copying or cutting the command.
  4. Click OK to close the Generate Stored Procedure Test Command dialog box.
  5. To run the command, paste it into an appropriate place in the third-party test tool of your choice and run it according to the instructions for that test tool.
Parent topic: How to...
Related concepts
Testing with Third-party Software


To generate an external table function

Restriction: This topic applies to Windows environments only.
  1. Start the Stored Procedure Test tool.
  2. Click Create a new (external) Table Function Create new table function.
  3. Complete each page of the Wizard. For help on a specific page and help on a specific field or control on a page, click Help.
Note: The Wizard writes one COBOL and one SQL file containing the generated code. The location of these files is specified in your SP Test tool Options, and the filenames are as follows:
  • SQL file - functionname.sql
  • COBOL file - functionname.cbl
Parent topic: How to...
Related concepts
Options
Related tasks
To generate a stored procedure
To generate an external scalar function


To generate an external scalar function

Restriction: This topic applies to Windows environments only.
  1. Start the Stored Procedure Test tool.
  2. Click Create a new (external) Scalar Function Create new scalar function.
  3. Complete each page of the Wizard. For help on a specific page and help on a specific field or control on a page, click Help.
Note: The Wizard writes one COBOL and one SQL file containing the generated code. The location of these files is specified in your SP Test tool Options, and the filenames are as follows:
  • SQL file - functionname.sql
  • COBOL file - functionname.cbl
Parent topic: How to...
Related concepts
Options
Related tasks
To generate a stored procedure
To generate an external table function


SQL Option Server Administration Guide

Restriction: This topic applies to Windows environments only.

The XDB Server, utilizing a high performance SQL engine, supports multiple locations and multiple databases within a location. The XDB Server, when combined with accompanying client software, provides a full-featured, client-server based database management system. The XDB Server and client software are available for a variety of operating platforms. In all cases, responsible parties need to understand the storage architecture and the various system and user configuration parameters.Note:If you want to access mainframe DB2 data directly, your system administrator must first install and configure a number of SQL connectivity components. Once this is done, your system administrator can advise you how to connect to mainframe data.

  • Client-Server Architecture
  • Advantages of Using SQL Option Server
  • Storage Architecture
  • Basic Tasks
  • Server Configuration Utility
  • Monitor Utility
  • Security and Authority
  • Server-to-server Connectivity
  • Multiserver Security
  • Backup and Recovery
  • Storage Requirements
  • Performance Tuning
  • Location Management
  • Environment Variables
  • Server Files
  • Troubleshooting
Parent topic: SQL Option for DB2


Client-Server Architecture

Restriction: This topic applies to Windows environments only.

The XDB Server makes use of a client-server architecture, which allows an application to be split into front-end (client) and back-end (server) components. The front-end components correspond to the end user's view of the application. The back-end is the XDB Server, which performs the actual database processing functions.

The front-end and back-end can reside on the same machine or they can be installed on a back-end server machine, with front-end client sessions initiated from separate workstations.

Parent topic: SQL Option Server Administration Guide


Advantages of Using SQL Option Server

Restriction: This topic applies to Windows environments only.

There are many advantages to using the XDB Server. A server allows people throughout the organization to share data and resources. With the database server located on a separate machine, more memory is available on client machines for other applications. The XDB Server also allows the transparent integration of clients and servers running different operating systems. The server's security system allows for a separation of responsibilities and access privileges, if desired.

Distributed processing and server-to-server connectivity are supported. This allows the user of a single-workstation XDB Server, for example, to access data from other XDB Servers.

Parent topic: SQL Option Server Administration Guide


Storage Architecture

Restriction: This topic applies to Windows environments only.

The XDB Server uses a logical storage architecture modeled after the architecture used by IBM's DB2. This architecture allows you to use the same three-part naming conventions (location-name.authid.object-name) typically used on the mainframe.Because much of the physical storage architecture employed on the mainframe has no equivalent in PC environments, the physical storage between the environments differs significantly. However, the physical implementation of the XDB Server generally makes these differences transparent to the user.The XDB Server allows you to explicitly define where data is to be stored or to use the system-generated defaults. With either method, data is accessed by using the logical names of objects, not by referencing the physical storage locations. The XDB Server performs the mapping between physical and logical layers automatically.

  • Locations
  • Storage Groups (Stogroups)
  • Databases
  • Table Spaces, Tables, and Indexes
  • Summary and Example
Parent topic: SQL Option Server Administration Guide


Locations

Restriction: This topic applies to Windows environments only.

At the highest level of the logical storage hierarchy is the location. You can have multiple locations defined and available under one copy of the XDB Server software. This differs slightly from the IBM DB2 concept of locations, but the naming convention of location-name.authid.object-name is the same on both platforms.

Note: Do not copy, alter, or move the files in locations. Doing so can corrupt the system location and jeopardize all the data managed by the XDB Server.
  • Mainframe DB2 Location (Subsystem) Structure. On a mainframe, each copy of DB2 software (subsystem) is assigned its own location name. There may be one or more databases (each containing multiple tables) within a location. Each database can have one or more table spaces and tables, with associated index spaces, indexes, views, and synonyms.

    A system catalog (a set of catalog tables) maintains information about each table and database and its components, including which tables belong to which databases and where objects are located on disk. There is one system catalog per copy of DB2 software (one catalog per location or subsystem).

  • XDB Location Structure. One XDB Server can manage one or more locations. A system location is provided by default. The "super" user (usually the database or system administrator) can create other locations.

    Like the mainframe, there may be one or more databases within a location. Each database can have one or more table spaces and tables, with associated indexes, views, and synonyms.

A system catalog database called DSNDB06 resides in each location to maintain information about the location and all tables and databases in that location, including which tables and indexes belong to which databases and where objects are located on disk. The system location also contains two other system-related databases: DSNDDF and XDBACF. The DSNDDF database contains tables such as SYSXDB.SYSLOCALS and SYSIBM.SYSLOCATIONS which together serve as an index to local and remote locations. The XDBACF database contains tables for system security.

Each location, including the system location, also contains a DSNDB04 database. This database is the default database for storing tables and other objects that a user creates without specifying a database name.

The mainframe system catalog tables have a two-part name, using SYSIBM as the AuthID qualifier (for example, SYSIBM.SYSDATABASES and SYSIBM.SYSTABLES). The XDB Server uses this same AuthID for all system tables that have a corresponding table on DB2. The XDB Server has additional system catalog tables that have no counterparts on mainframe DB2. These catalog tables are prefixed with the SYSXDB AuthID (except SYSIBM.SYSXDBMAP).

When you install the XDB Server, the system catalog databases in the SYSTEM location are stored in subdirectories under the SYSTEM subdirectory of your XDB Directory. (Your "XDB Directory" refers to the directory where you installed the XDB Server and related executable software.)

Note: Do not run DDL files in the SYSTEM location.

For example, if you install the XDB Server in c:\xdb\ /xdb/ , then the system databases will be placed in the following subdirectories:

Windows:
  • c:\xdb\system\dsndb06\
  • c:\xdb\system\dsndb07\
  • c:\xdb\system\dsnddf\
  • c:\xdb\system\xdbacf\
  • c:\xdb\system\dsndb04\
UNIX:
  • /xdb/system/dsndb06/
  • /xdb/system/dsndb07/
  • /xdb/system/dsnddf/
  • /xdb/system/xdbacf/
  • /xdb/system/dsndb04/

Whenever you create a new location you must specify a Location Name (up to 16 characters long) according to the following guidelines:

  • You must place your data tables in locations other than the system location. (You can have one or more databases and/or tables per location.)
  • Two locations with the same name cannot exist simultaneously under the same XDB Server (or engine). An error message is presented if you attempt to create a location using an existing location name.
  • If Distributed Unit of Work (DUW) processing is anticipated, location names must be unique across the entire system, that is, across the multiple servers and/or geographic sites that will be included in remote processing activities. (See Distributed Processing for more information.)

In addition to specifying a location name when you create a new location, you must also specify a directory for it on disk, according to the conventions for your operating system. For example, you could use the command:

Windows:
 CREATE LOCATION locat1 IN c:\xdb\locat1
UNIX:
 CREATE LOCATION locat1 IN /xdb/locat1

When you issue this command, the XDB Server creates the directory on disk and adds information about the new location to the SYSXDB.SYSLOCALS and the SYSIBM.SYSLOCATIONS tables in the SYSTEM location. Other options are available on the CREATE LOCATION command to allow you to specify the sort sequence, forward log name and other items. You can edit the SYSXDB.SYSLOCALS table to change these parameters.

Note: In an XDB database, the sort sequence (EBCDIC, ASCII, etc.) is defined when the location is created. You can change the sort sequence of a location with the ALTER LOCATION command.

You can execute the following utility command any place you can issue SQL commands to specify the current location:

SET LOCATION TO location-name

Your default current location is maintained in your client configuration. See the setup and configuration documentation that came with your client application for details. If you want to use or create objects in a location other than your current location, use SET LOCATION TO prior to entering your other SQL statements. In embedded SQL, and to access remote locations, you must use the CONNECT command.

Note: Distributed Unit of Work (DUW) Processing is also available for accessing data in locations other than your own. See Distributed Processing for more information.
Parent topic: Storage Architecture


Storage Groups (Stogroups)

Restriction: This topic applies to Windows environments only.

On a mainframe system, Storage Groups (Stogroups) provide a means of specifying the physical DASD volume where data will be stored. The XDB Server provides an analogous function by allowing you to associate a drive and pathname with a stogroup name.

You can define one or more stogroups in each location as needed. Later, when you create a database or table space in a location that has one or more stogroups defined, you can specify a stogroup to be used for storing the database or table(s). Thus, you can specifically define the physical location (on what volume-- disk drive and directory) of each database or table space.

Note: Use of stogroups is optional. Once you define a location directory, subdirectory paths for other objects are created automatically as needed when you create the objects (for example, CREATE DATABASE). The XDB System Catalog keeps track of where objects are stored for each location and database.

To use stogroups to their full advantage, you must create the path(s) on your operating system. Then use the CREATE STOGROUP command to specify the drive and path name to be associated with a stogroup name. Lastly, modify two columns in the SYSIBM.SYSVOLUMES table to define the path to the XDB Server. (It is also possible to define a stogroup without assigning a path in SYSIBM.SYSVOLUMES. This provides compatibility with mainframe DB2 in terms of maintaining the stogroup-related entries in system tables but allows the XDB Server database software to use its default path creation and naming routines.)

If you do not specify a path in SYSIBM.SYSVOLUMES and/or you do not specify stogroups for your table spaces, the XDB Server will create a subdirectory under the location name directory to store your database files when you create the database. A typical database path created by the XDB Server could be :\XDB\LOCAT1\DBNAME\ (Windows) or /xdb/locat1/dbname/ (UNIX).

Note: The XDB SYSIBM.SYSVOLUMES table contains two columns that are not included in the analogous DB2 table. These columns are XDBPRIMEVOLPATH and XDBVOLPATH.

See the SQL Reference for detailed information regarding the storage structure and naming conventions that apply when creating various table and database objects, with and without stogroups.

Example

The following CREATE commands will create two storage groups (named STOR1 and STOR2) on two separate disk volumes (named MINE and YOURS). The UPDATE commands will then define the disk drive and directory for each of the named volumes.

Windows:

CREATE STOGROUP stor1 VOLUMES (mine) VCAT xdb;
CREATE STOGROUP stor2 VOLUMES (yours) VCAT xdb;
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y",
        XdbVolPath = "d:\stor1\"
    WHERE Volid = "mine";
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y",
        XdbVolPath = "e:\stor2\"
    WHERE Volid = "yours";

Before you can create databases or table spaces in these stogroups, you must create the two directories (d:\stor1 and e:\stor2).

UNIX:

CREATE STOGROUP stor1 VOLUMES (mine) VCAT xdb;
CREATE STOGROUP stor2 VOLUMES (yours) VCAT xdb;
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y" ,
        XdbVolPath = "/stor1/"
  WHERE Volid = "mine";
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y" ,
        XdbVolPath = "/stor2/"
  WHERE Volid = "yours";

Before you can create databases or table spaces in these stogroups, you must create the two directories (/stor1/ and /stor2/).

Note: The VCAT parameter is required only when running in DB2 compatible mode. It is checked for syntax only, and recorded in the appropriate system table.

To complete this example, you would use CREATE commands such as the following to specify storage locations for objects you create:

CREATE DATABASE xyz stogroup STOR1;

or

CREATE TABLESPACE abc IN xyz
    USING STOGROUP stor1;
Parent topic: Storage Architecture


Databases

Restriction: This topic applies to Windows environments only.

A database object is a 1-to-8 character name assigned to a collection of tables and indexes. When creating a database (without specifying a stogroup) the XDB Server also creates a subdirectory on disk using the database name. The subdirectory is created under the directory of the current location. (For example: c:\xdb\locat1\dbname (Windows) or /xdb/locat1/dbname (UNIX))

When you create a table, you can specify the name of the database with which you want it to be associated. If you are using table spaces, you specify the name of the database and table space. If you do not specify a database name, then the tables and other objects are stored in the DSNDB04 default database which is automatically included in each location.

If you have defined stogroups (see above), you can specify which stogroup should be the default stogroup for the database. The directory (path) defined for that stogroup will then be used to store the various database files (tables, indexes, etc.).

If you do not specify a stogroup for the database, the XDB Server uses the default stogroup (SYSDEFLT) which causes files for database objects to be stored under the ..\location-name\dbname\ (Windows) or location-namedbname (UNIX) structure described above. (It is also possible to specify a stogroup for each table space that you define for your tables and indexes, if you use table spaces.)

See the SQL Reference for detailed information regarding the storage structure and naming conventions that apply when creating various database objects with and without stogroups.

Parent topic: Storage Architecture


Table Spaces, Tables, and Indexes

Restriction: This topic applies to Windows environments only.

On a mainframe system, table spaces and stogroups provide a means of organizing tables and indexes on specific disk storage devices. Generally, each table space and index is associated with a stogroup. A table can be created within a specific table space, which associates the table with the stogroup of the table space. When an index is created, it can be associated with a stogroup as well.

The XDB Server supports the table space/stogroup structure, and provides syntactical/semantic support for relating an index to a stogroup.

Note: Use of table spaces and stogroups is optional. If you choose to specify table spaces, you can do so with or without stogroups.

If you have defined stogroups in an XDB database, you can specify which stogroup should be used when you create a table space. For example:

CREATE TABLESPACE brspace
    IN databas1 USING STOGROUP stor1;

When you create tables and indexes in a database, use either or both of the following methods:

  • Allow the XDB Server to define table spaces and directory paths for the tables and indexes you create. For example:
    CREATE TABLE branch
    ( fld1 SMALLINT, fld2 CHAR 1 )
    IN databas1;
CREATE INDEX brindex ON branch(fld1);

    If the database has a stogroup defined, the XDB Server uses its path to store the table and index files.

    If the database does not have a stogroup defined, the XDB Server uses the SYSDEFLT stogroup routine which uses the ..\location-name\database-name\ (Windows) or ../location-name/database-name/ (UNIX) path structure. In this situation, the XDB Server creates table and index files under the database-name subdirectory to store each table and index. For example:

    Windows:
    • c:\xdb\locat1\databas1\branch.tab
    • c:\xdb\locat1\databas1\brindex.idx
    • c:\xdb\locat1\databas1\brindex.ptr
    UNIX:
    • /xdb/locat1/databas1/branch.tab
    • /xdb/locat1/databas1/brindex.idx
    • /xdb/locat1/databas1/brindex.ptr

    The table space name will be the first eight characters of the table or index name, as appropriate. If the eight character name would duplicate an existing table space name, the system creates a unique name for the table space.

  • Specify a pre-defined table space for a table. The index will be placed in the table space where its associated table resides. For example:
    CREATE TABLE branch
    ( fld1 SMALLINT, fld2 CHAR 1 )
    IN databas1.brspace;
CREATE INDEX brindex ON branch(fld1);

    In this case, all tables you create with the named table space will be stored under the stogroup directory that was defined for the table space. Indexes created on those tables will be stored in the same stogroup path.

    For example:

    Windows:
    • d:\stor1\branch.tab
    • d:\stor1\brindex.idx
    • d:\stor1\brindex.ptr
    UNIX:
    • /stor1/branch.tab
    • /stor1/brindex.idx
    • /stor1/brindex.ptr
Note:

If your database is the default DSNDB04 database, you do not have to specify the database name in the above commands.

Any table you create without specifying a database name will be placed in DSNDB04 automatically.

To summarize, when you create a table, you usually specify the database in which you want it to be created. Optionally, if you created table spaces in the location, you can specify a table space name in which to store the data. The system catalog keeps track of which tables belong to each database and where they are located on disk.

When you create an index, you specify the table to which it applies. Again, the system catalog keeps track of which indexes belong to each database and table, and where they are located on disk.

See the SQL Reference for detailed information regarding the storage structure and naming conventions that apply when creating various database objects with and without stogroups.

Example

In this example, a database and two table spaces are created in the current location. The first table space does not specify a stogroup, and thus the default database subdirectory will be used to store tables for this table space ( c:\xdb\locat1\dbname\ (Windows) or /xdb/locat1/dbname/ (UNIX)). The other table space will reside in one of the previously defined stogroup directories ( d:\stor1 (Windows) or /stor1 (UNIX)).

Notice that when tables are defined, they are qualified with an IN clause to specify to which database they belong (and optionally, which table space should be used to store the physical data). In this example, the first two tables use specific table spaces. The third table is defined without a table space. The index for the BRANCH table will reside in the same table space as the BRANCH table.

CREATE DATABASE databas1;
CREATE TABLESPACE brchspc IN databas1;
CREATE TABLESPACE acctspc IN databas1
    USING STOGROUP stor1;
CREATE TABLE branch (
           BRANCH_ID   INTEGER,
           BRANCH_BAL  DECIMAL(15,2) )
    IN databas1.brchspc;
CREATE INDEX BIDX ON BRANCH(BRANCH_ID);
CREATE TABLE account (
           ACCT_ID     INTEGER,
           BRANCH_ID   INTEGER,
           ACCT_BAL    DECIMAL(15,2) )
    IN databas1.acctspc;
CREATE TABLE history (
           ACCT_ID     INTEGER,
           BRANCH_ID   INTEGER,
           ACCT_BAL    DECIMAL(15,2) )
    IN databas1;
Parent topic: Storage Architecture


Summary and Example

Restriction: This topic applies to Windows environments only.

The XDB Server fully supports the naming conventions and data storage structures that are available on a mainframe DB2 subsystem. Features include the following structures and objects:

  • Locations
  • Storage Groups
  • Databases
  • Table Spaces
  • Tables
  • Indexes

Example

The following is a scenario for creating a new location with two databases. Each database has a table space defined. One table in each database is created in a table space. The other table in each database is created without a table space.

Use the SQL Wizard to execute these commands (applies to Windows environments only). See the SQLWizard User's Guide or on-line help for information.

Use the Interactive SQL tool to execute these commands (applies to UNIX environments only). See the Reference Help for more information.

CREATE LOCATION testxdb
    IN c:\xdb\testxdb\/xdb/test/xdb/;
SET LOCATION TO testxdb;
CREATE DATABASE testdb1;CREATE DATABASE testdb2;CREATE TABLESPACE ts4db1 IN testdb1;
CREATE TABLESPACE ts4db2 IN testdb2;
CREATE TABLE table1 (Field1 integer, Field2 integer)
    IN DATABASE testdb1;
CREATE TABLE table2 (Field3 integer, Field4 integer)
    IN testdb1.ts4db1;
CREATE TABLE tableA (FieldA integer, FieldB integer)
    IN DATABASE testdb2;
CREATE TABLE tableB (FieldC integer, FieldD integer)
    IN testdb2.ts4db2;
CREATE INDEX inx ON table1 (Field1);
Parent topic: Storage Architecture


Basic Tasks

Restriction: This topic applies to Windows environments only.
  • Starting an XDB Server
  • Shutting Down an XDB Server
  • Client Sessions and Multiple Logins
  • Administrative (Authority) Levels
  • Administrative Tasks
Parent topic: SQL Option Server Administration Guide


Starting an XDB Server

Restriction: This topic applies to Windows environments only.

A personal XDB Server is installed on your machine when you install SQL Option for DB2 (applies to Windows environments only). This local copy of XDB Server is the default server. It must be running before you can debug or run client applications against a local XDB database. The personal XDB Server can be installed as a Windows Service that is started automatically.

You can also run the XDB Server Blue Screen mode.

After installing and configuring the XDB Server and at least one client, you are ready to run your XDB Server.

When the XDB Server completes its initialization, users can access the locations controlled by the XDB Server immediately. See the topic Shutting Down an XDB Server for information about shutting down an XDB Server.

Parent topic: Basic Tasks
Related information
Shutting Down an XDB Server
To start the XDB Server in blue screen mode


Shutting Down an XDB Server

Restriction: This topic applies to Windows environments only.

Use either of the following procedures to shut down the server:

  • Press F10 when viewing the XDB Monitor Utility main menu. If users are active, the monitor asks you to confirm the action.
  • Issue the SQL SHUTDOWN command from a client program (i.e. SQLWizard (Windows) or Interactive SQL (UNIX) ). If security is on, your AuthID must have super user authority. For information, about the SHUTDOWN command, see the SQL Reference.
  • Double-click the XDB Server icon in the Control Panel, and click Stop.

Keep the following in mind when you shut down an XDB Server:

  • If users are active when you shut down an XDB Server, their sessions are terminated in mid-transaction, as though the XDB Server crashed. When the XDB Server is restarted, all incomplete transactions are rolled back the next time that location is accessed. Use care, since user programs running on the workstations may not handle a case where the XDB Server no longer responds.
  • If a query is active when you shut down an XDB Server, the XDB Server waits until the query is complete before shutting down.
Parent topic: Basic Tasks


Client Sessions and Multiple Logins

Restriction: This topic applies to Windows environments only.

An XDB client running on Windows or UNIX platforms can have several concurrent sessions. For example, a Windows user could open a window and start the SQLWizard. Next, the same user could open another window and start the XDB Migrate Utility, logging in to the XDB Server with the same AuthID and Node Name. The XDB Server will show two user sessions, both with the same AuthID and Node Name, but each running a different process, and each showing a different Session ID number. Likewise, a Windows client can start several sessions by clicking on multiple program icons. Again, the user's multiple sessions show up on the XDB Server, all having the same AuthID and Node Name but with unique Session ID numbers.

When a client session fails or otherwise aborts without logging out, the XDB Server automatically detects the aborted session and releases all resources and locks. Any in-process transactions are rolled back. If the user has other sessions running, they are not affected.

Parent topic: Basic Tasks


Administrative (Authority) Levels

Restriction: This topic applies to Windows environments only.

Assign system administration activities and responsibilities to others, depending upon the size and complexity of your installation. With the exception of the special super user privilege set, all authorities are effective only within the location where they are defined.

Suggested responsibilities include:

  • Super User. A special set of XDB Server privileges that can be assigned to one or more system users. This privilege set is assigned automatically to the INSTALL AuthID during installation. Super user authority allows access to all functions on the system. Only the super user can create locations, drop locations and edit system tables.
  • System Administrator (SYSADM). A user who has access to almost all functions within the defined location, including the authority to grant and revoke privileges for other users in that location, but excluding the special super user privileges defined above.
  • System Control (SYSCTRL). A user whose privileges apply only to the location in which SYSCTRL is granted. These privileges include almost all privileges except access to user data.
  • Database Administrator (DBADM). A user who has all database-level privileges but only for a specified database.
  • Database Control (DBCTRL). A user who can use DROP on one specified database, and whose privileges include DBMAINT privileges.
  • Database Maintenance (DBMAINT). A user who can use CREATAB, CREATETS, STARTDB, AND STOPDB for one specified database.

With the exception of super user, any of these suggested responsibility levels can be granted by using the appropriate authority (DBADM, SYSCTRL, etc.) on the GRANT command. See the chapter Security and Authority for more information about security, including use of the GRANT and REVOKE commands.

Parent topic: Basic Tasks


Administrative Tasks

Restriction: This topic applies to Windows environments only.

This collection of topics covers the following administrative tasks:

  • Configuring System Parameters
  • Managing System Structures and Space Requirements
  • Packing Data Files to Create Free Space
  • Insuring Database Integrity
  • Evaluating and Improving Database Performance
  • Controlling Access at the System, Database, and Table Levels
  • Backing Up and Restoring Data
  • Maintaining Storage Media
Parent topic: Basic Tasks


Configuring System Parameters

Restriction: This topic applies to Windows environments only.

The database administrator should be responsible for setting parameters in the XDB Server Configuration utility for multiuser systems, and for assisting users with the parameters in their individual XDB Server Options and Server Configuration utilities.

Parent topic: Administrative Tasks
Related information
To start the XDB Server Configuration Utility


Managing System Structures and Space Requirements

Restriction: This topic applies to Windows environments only.

The database administrator should also examine the structure of the various locations on the system and the databases defined within each location with an eye towards reducing unnecessary or redundant data storage. The XDB Server supports distributed processing at various levels. See the chapter Storage Architecture for more information about the system architecture.

The system catalog tables provide information about the tables in a database. To determine the space occupied by a given table or index, use the directory DIR (Windows) or ls (UNIX) command from your operating system prompt to list the tables in a given directory. The directory DIR (Windows) or ls (UNIX) command lists the amount of space occupied by each file in addition to the number of free bytes remaining on the disk. You can use the SQL SELECT command to query any of the system catalog tables. See the SQL Reference for a description of the SELECT command. See the chapter Storage Requirements for more information about estimating data storage requirements.

Parent topic: Administrative Tasks


Packing Data Files to Create Free Space

Restriction: This topic applies to Windows environments only.

Tables, directories and locations should be periodically packed to improve performance and reduce storage requirements. The SQL COMPACT command can be used to:

  • Free space that was formerly occupied by deleted records.
  • Optimize the dictionary files by freeing space that was formerly used for tables that have since been altered or dropped.
  • Rebuild indexes:
    • When converting from a previous version of the XDB Server.
    • After performing many updates or deletions, to optimize space utilization.
    • To rebuild corrupt index files.
  • Re-order the data in a table according to the order of records in a clustered index.

You can call the SQL COMPACT command from any utility that allows you to issue standard SQL commands (such as the SQLWizard on Windows platform, or Interactive SQL on UNIX). You can also use the SQL COMPACT command in Embedded SQL in COBOL . For more information about this command, see the SQL Reference.

Note:

If you are using XDB Link, you cannot use the COMPACT command against DB2 objects on the mainframe. Instead, log on to the mainframe and use the REORG facility to perform this task.

Parent topic: Administrative Tasks


Insuring Database Integrity

Restriction: This topic applies to Windows environments only.

The database administrator needs to oversee data entry and programming tasks that impact each database to insure that proper data validation techniques are enforced.

The XDB Server implements referential and domain integrity checks at the schema level. Data integrity can be directly controlled through the use of these integrity features. For more information, see the ALTER or CREATE command in the SQL Reference.

Parent topic: Administrative Tasks


Evaluating and Improving Database Performance

Restriction: This topic applies to Windows environments only.

The database administrator determines if the performance of a database is satisfactory for the application environment. Some factors that influence database performance include:

  • Indexes
  • Optimizing the structure of SQL statements
  • Locking (in multiuser versions)
  • Clustering
  • Database design
  • Caching
  • Storage organization, including use of storage groups (stogroups)
Parent topic: Administrative Tasks


Controlling Access at the System, Database, and Table Levels

Restriction: This topic applies to Windows environments only.

The database administrator is responsible for protecting the security of the system, locations, databases, and tables. This is accomplished by creating and deleting AuthIDs (user names) and groups, as well as granting and revoking privileges at various levels within the system.

Activate security privileges by turning security on with the XDB Server Configuration utility. Use the SQLWizard (Windows) or Interactive SQL (UNIX) to add and delete AuthIDs. See the chapter Security and Authority for more information.

Privileges on system functions and database objects are managed through the SQL GRANT and REVOKE commands, which are described in the SQL Reference.

Parent topic: Administrative Tasks


Backing Up and Restoring Data

Restriction: This topic applies to Windows environments only.

The database administrator is expected to establish a regular schedule for backing up locations and their log files. The frequency of backups depends on the frequency of database updates, the importance of data, and the difficulty involved in recreating the data. You should always backup a location during special operations, such as after using the COMPACT command or before installing a new version of XDB Server software.

Backups can be performed using the BACKUP LOCATION command or by using an operating system backup command.

If you operate a location with recovery turned on, log files are maintained (ideally on a different disk drive). The log files contain after images of records that were changed by database transactions within the location. In the event of a system failure, the log files can be applied to the latest restored backup of the location to recover the changes recorded in the log files. The XDB Server provides a ROLLFORWARD command for this purpose.

See the chapter Backup and Recovery for more information.

Parent topic: Administrative Tasks


Maintaining Storage Media

Restriction: This topic applies to Windows environments only.

The database administrator is also expected to ensure that timely and proper procedures are implemented and observed for verifying the integrity of storage media. For example, all drives should be checked regularly for lost clusters, fragmentation and other damage that might accumulate over time to threaten data.

There are various commercially available utilities for checking and repairing disk problems. Check your operating system documentation for more information on this or other comparable commands.

Parent topic: Administrative Tasks


Server Configuration Utility

Restriction: This topic applies to Windows environments only.
The Server Configuration utility enables you to change the configuration of your personal XDB Server. For example, you can change the following:
  • The XDB Server name
  • Whether XDB Server security is enabled or not
  • Which protocol is used to access the XDB Server
  • Whether other people can use the XDB Server
  • The amount of system resources available to XDB Server
  • Accessing the Server Configuration Utility
  • Server Configuration Parameters
Parent topic: SQL Option Server Administration Guide
Related information
To start the XDB Server Configuration Utility


Accessing the Server Configuration Utility

For Windows environments

You can run the XDB Server Configuration utility in one of two modes:

Blue screen
You have two options:
From Enterprise Developer
  • From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Server > XDB Server Monitor.
From the Start menu
  • Click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2 > Server > XDB Server Monitor
As a Windows service
  1. Start your Windows Control Panel.
  2. Double-click Micro Focus XDB Server.
  3. Click Configure.

For UNIX environments

To start the XDB Server Configuration utility, enter xdbsrvco at an Enterprise Developer command prompt.

Parent topic: Server Configuration Utility


Server Configuration Parameters

Restriction: This topic applies to Windows environments only.

This collection of topics covers the following:

  • System Location Path
  • Temporary File Path
  • Server Security
  • Server Version
  • System Usage Monitor
  • Sort Space Size
  • Maximum Number Of Users
  • Lock Table Size
  • Maximum Number of Open Queries
  • Maximum Number of Open Files
  • Governor Cycle Time
  • XDB Server Name
  • Communications Protocols
  • Global Security and Global Security Location Name
  • Buffer Pool Size
Parent topic: Server Configuration Utility


System Location Path

Restriction: This topic applies to Windows environments only.

The system location path specifies where the XDB Server looks for system tables containing information about all locations that are accessible to this XDB Server. These system tables are in addition to the system tables that are maintained in the DSNDB06 database for each location.

Enter a path to a specific drive (volume) and directory. Do not specify a location name.

Note: You specify this path when you install the XDB Server. Change the system path only when you need to physically move the files comprising your SYSTEM location.

To set the parameter on UNIX:

  1. Press F2 Location and Path Selection.
  2. Press F1 System Location Path.
  3. Enter the path and press Enter.

To set the parameter on Windows 2000:

  1. Click the Paths tab.
  2. Enter the path in the System Location Path text box.
Parent topic: Server Configuration Parameters


Temporary File Path

Restriction: This topic applies to Windows environments only.

Set the temporary path to identify where the system should write temporary files used by the XDB Server, such as temporary files that are written when a sort operation overflows the allocated Sort Space Size. Enter a path to a specific drive (volume) and directory. This directory must be accessible to the XDB Server.

To set the parameter on UNIX systems:

  1. Press F2 Location and Path Selection.
  2. Press F2 Temporary File Path.
  3. Enter the path and press Enter.

To set the parameter on Windows 2000:

  1. Click the Paths tab.
  2. Enter the path in the Temporary File Path text box.
Parent topic: Server Configuration Parameters


Server Security

Restriction: This topic applies to Windows environments only.

The XDB Server is shipped with security turned off. If you enable security at the server, you must also enable security at each client workstation accessing the XDB Server. Otherwise, the XDB Server will reject the client logon.

Enabling security requires each user to log in to the XDB Server using a valid AuthID (user name) and password. To set AuthIDs, groups and passwords, use the Admin menu of the SQLWizard (Windows) or Interactive SQL utility to execute CREATE USER statements (UNIX). See the Security and Authority chapter, or User Administration in the SQLWizard User's Guide for more information.

If you enable security, the system will also check any privileges configured using the GRANT and REVOKE commands. For information about the GRANT and REVOKE commands, see the SQL Reference.

See the chapter Security and Authority for detailed information about how to plan and construct a security scheme.

To set the parameter on UNIX:

  1. Press F3 SQL Engine Options.
  2. Press F1 XDB Server Security.

To set the parameter on Windows 2000:

  1. Click the General tab.
  2. Mark the Server Security checkbox.
Note: There is no password protection provided by the XDB Server Configuration utility. Anyone with access to the server can run the utility and enable or disable the security. Make sure that the server is physically secure from unauthorized access.
Parent topic: Server Configuration Parameters


Server Version

Restriction: This topic applies to Windows environments only.

The XDB Server is shipped with version set to DB2V6.

To set the parameter:

  1. Press F3 SQL Engine Options.
  2. Press F2 Server Version.
  3. Press F1 to select DB2V6 or F2 for DB2V7.
Parent topic: Server Configuration Parameters


System Usage Monitor

Restriction: This topic applies to Windows environments only.

The Usage Monitor is a facility for recording location usage. While utilization monitoring is on, the system stores utilization information in the SYSXDB.SYSUSAGE table in the DSNDB06 subdirectory of the system location's directory. If you enable the usage monitor and security, the system will automatically maintain this table, and modify it each time a user logs in or out of a location. You can query the table to audit location usage.

Note: Because the Usage Monitor tracks usage data by individual user session, it contains worthwhile information only when server security is enabled, which forces users to log in.
Note: Enabling the Usage Monitor can decrease performance and require large amounts of disk space.

If the SYSXDB.SYSUSAGE table becomes too large, delete entries from the table using the DELETE or TRUNCATE TABLE command. After deleting entries, you must pack the SYSXDB.SYSUSAGE table using the COMPACT command. COMPACT frees space formerly occupied by deleted records. It is good practice to perform this procedure each time you back up the system location when using the System Usage Monitor.

See the SQL Reference for the structure of the SYSXDB.SYSUSAGE table, and for information about the DELETE, TRUNCATE TABLE, and COMPACT commands. As is the case for all XDB Server system tables, the structure of the SYSXDB.SYSUSAGE table is subject to change.

To set the parameter on UNIX:

  1. Press F3 SQL Engine Options.
  2. Press F3 System Usage Monitor.

To set the parameter on Windows 2000:

  1. Click the General tab.
  2. Mark the System Usage Monitor checkbox.
Parent topic: Server Configuration Parameters


Sort Space Size

Restriction: This topic applies to Windows environments only.

Set the sort space size to specify the maximum amount of memory that the XDB Server will attempt to acquire when performing a sort operation. Sort space is acquired on a per-sort basis. The sort space size does not define a common pool shared by all users, but rather the maximum amount of space provided for each individual sort request. If a particular sort process does not require the total amount of memory allocated by the Sort Space Size setting, the excess amount of memory is released back to the operating system.

Increasing the sort space size allows the system to process large sorts more quickly, and store larger amounts of data at a single time, requiring fewer merges of sorted information. However, if you set this value too high, relative to the number of concurrent sorts or users, query processing may slow down significantly due to over-allocated memory.

To set the parameter on UNIX:

  1. Press F4 Configure System Minimums/Maximums.
  2. Press F1 Sort Space Size.
  3. Enter the desired sort space size in KB and press Enter.

To set the parameter on Windows 2000:

  1. Click the Limits tab.
  2. Enter the desired size in the Sort Space Size text box, or drag the slider.
Note: Do not set the combined amounts of Sort Space Size and other cache to a number greater than the total amount of physical memory (RAM) available on a machine. Doing so can degrade performance due to operating system swapping. When determining how much cache to allocate, be sure to consider all types of caching, including the Caching Options, the XDB Server Sort Space Size option, and operating system cache.
Parent topic: Server Configuration Parameters


Maximum Number Of Users

Restriction: This topic applies to Windows environments only.

Set the maximum number of concurrent users logged in the XDB Server to an integer between 1 and 128. Each user will require an additional 128 bytes of memory.

To set the parameter:

  1. Press F4 Configure System Minimums/Maximums.
  2. Press F2 Maximum Number of Users.
  3. Enter the desired number and press Enter.
Parent topic: Server Configuration Parameters


Lock Table Size

Restriction: This topic applies to Windows environments only.

Set the size of the lock table to an integer between 4 and 1000 (kilobytes). The recommended setting is 60KB. The XDB Server returns an error code when the lock table is full.

To set the parameter (UNIX):
  1. Press F4 Configure System Minimums/Maximums.
  2. Press F3 Lock Table Size.
  3. Enter the desired lock table size in KB and press Enter.
To set the parameter (Windows):
  1. Click the Limits tab.
  2. Enter the desired size in the Lock Table Size text box, or drag the slider.
Parent topic: Server Configuration Parameters


Maximum Number of Open Queries

Restriction: This topic applies to Windows environments only.

You can set the XDB Server to support anywhere from 10 to 9,999 open queries. Each additional query specified here requires an additional, but negligible amount of memory. However, specifying too large a number can impact performance because the array of queries is scanned each time a transaction completes. The more queries that are allowed, the longer the scan will be each time.

To set the parameter (UNIX):

  1. Press F4 Configure System Minimums/Maximums.
  2. Press F5 Maximum Number of Open Queries.
  3. Enter the desired number and press Enter.

To set the parameter (Windows 2000):

  1. Click the Limits tab.
  2. Enter the desired number in the Maximum Open Queries text box, or drag the slider.
Parent topic: Server Configuration Parameters


Maximum Number of Open Files

Restriction: This topic applies to Windows environments only.

Set the XDB Server to allow between 256 and 32,767 logically open files at any time. Each additional open file adds approximately 100 bytes of memory overhead to the XDB Server.

Once a file has been accessed, the XDB Server keeps the file logically open. A least recently used (LRU) algorithm determines which files to physically close when the limit is reached. The LRU significantly reduces the overhead related to physically opening and closing files during query processing.

If query processing is slow, increase the maximum number of open files.

To set the parameter (UNIX):

  1. Press F4 Configure System Minimums/Maximums.
  2. Press F6 Maximum Number of Open Files.
  3. Enter the desired number and press Enter.

To set the parameter (Windows:

  1. Click the Limits tab.
  2. Enter the desired number in the Maximum Open Files text box, or drag the slider.
Parent topic: Server Configuration Parameters


Governor Cycle Time

Restriction: This topic applies to Windows environments only.

If security is enabled, set the governor cycle time to an integer between 1 and 255 to specify the frequency, in seconds, at which the server checks user activity against limits set in the SYSXDB.SYSGOVERNOR table.

The XDB Server terminates sessions of users who have passed their limits. Limit users by the:

  • Number of API calls
  • Amount of time in the SQL engine
  • Amount of time processing calls
  • Amount of idle time
  • Number of fetches

For example, if Governor Cycle Time is set to 30 seconds, the system checks user activity against governor limits every 30 seconds. A cycle that is too short increases system overhead and decreases performance.

For more information about the XDB Governor and how to assign restrictions to users, see the description in the chapter Security and Authority.

To set the parameter (UNIX):

  1. Press F4 Configure System Minimums/Maximums.
  2. Press F9 Maximum Governor Cycle time.
  3. Enter the desired cycle time in seconds and press Enter. To disable the governor, the cycle time to zero (0).

To set the parameter (Windows):

  1. Click the General tab.
  2. Mark the Governor checkbox (if it is not already enabled).
  3. Enter the desired cycle time in the Cycle Time text box, or drag the slider.
Parent topic: Server Configuration Parameters


XDB Server Name

Restriction: This topic applies to Windows environments only.

Use this option to set the name by which this XDB Server is known to client applications. Multiple XDB Servers, each with a unique name, can coexist on the same network. Users must supply the appropriate XDB Server Name, using the Options Utility, to connect their client applications to a particular server.

The name given here must also be specified in other places, depending on the client-to-server communications protocol and operating system:

  • For servers using TCP/IP, the xdbnet.ini file contains additional protocol information about each XDB Server on the LAN.

Other networks or operating systems may have other naming conventions and restrictions. Consult your network or operating system documentation for more information.

To set the parameter on UNIX:

  1. Press F5 Multiuser Configuration.
  2. Press F1 XDB Server Name.
  3. Enter the name and press Enter.

To set the parameter on Windows:

  1. Click the About tab.
  2. Enter the name in the XDB Server Name text box.
Parent topic: Server Configuration Parameters


Communications Protocols

Restriction: This topic applies to Windows environments only.
Local (Windows)
Turn this option on to enable communication between client and server on the same Windows machine.
TCP/IP (all platforms)
Turn this option on to enable communication between TCP/IP clients and the server.
To set the parameter (UNIX):
  1. Press F5 Multiuser Configuration.
  2. Press the function key for the desired communications protocol.
  3. Press F1 to toggle the communications protocol on or off.
To set the parameter (Windows):
  1. Click the General tab.
  2. Mark the checkbox next to the desired communications protocol.
Parent topic: Server Configuration Parameters


Global Security and Global Security Location Name

Restriction: This topic applies to Windows environments only.

Once you enable server security, you may enable Global Security if this XDB Server will access another XDB Server or mainframe location for security information (such as AuthIDs and password validation). If you enable Global Security, you must enter the name of the location that contains the global security information.

  • If the global security location is on an XDB Server, you must set up server-to-server connections, including registering the security location of the remote XDB Server in the appropriate system tables of the local XDB Server. See the chapter Server-to-Server Connectivity for more information.

If Global Security is OFF and the XDB Server's regular security feature is ON, AuthID and password validation are performed on the local XDB Server's SYSXDB.SYSACFUSERS, SYSXDB.SYSACFGROUPS and SYSXDB.SYSACFMEMBERS tables in the SYSTEM location.

See the chapter Security and Authority, or User Administration in the SQLWizard User's Guide for information about setting up AuthIDs and groups for users. See the chapter Server-to-Server Connectivity for information about setting up server-to-server connectivity. See the chapter Multiserver Security for information about setting up global security.

When using global security, the following are granted on the XDB Server where the user will be accessing data: server-to-server connections and inbound/outbound mapping database privileges, governor limits, and similar user controls.

To set the parameter (UNIX):

  1. Press F5 Multiuser Configuration.
  2. Press F9 Enforce Global Security.
  3. Enter the global security location name and press Enter.

To set the parameter (Windows):

  1. Click the General tab.
  2. Mark the Global Security checkbox.
  3. Enter the global security location name in the Location text box.
Parent topic: Server Configuration Parameters


Buffer Pool Size

Restriction: This topic applies to Windows environments only.

You can set a buffer pool size to allocate the total amount of memory, in kilobytes, available for caching table, index, and dictionary files. A buffer pool size can range from 16K to 131,072K. The value of BP(0) sets the buffer pool size for data, and the value of BP(1) sets the buffer pool size for indexes. However, if you set BP(0) to a value of zero, this sets the buffer pool size to zero for both data and indexes.

Micro Focus's buffer management system is designed to enhance performance. Memory is allocated by the cache manager at XDB Server start up and then released at XDB Server shut down.

Note: Do not set cache to a number greater than the total amount of physical memory (RAM) available on a machine. Doing so can degrade performance due to operating system swapping. When determining how much cache to allocate, be sure to consider all types of caching, including Caching Options, Sort Space Size, and operating system cache.

To set the cache size for UNIX environments, or Windows when in blue screen mode:

  1. Press F6 Caching Options.
  2. Press F1 BP(0) Cache Size or F1 BP(1) Cache Size.
  3. Enter the appropriate cache size in KB and press Enter.
To set the cache size from the Windows XDB Server Configuration Utility service (Windows):
  1. Click the Cache tab.
  2. Type a cache size into each of the appropriate fields, or drag the slider to select a value for each.
  • About Caching
Parent topic: Server Configuration Parameters


About Caching

Restriction: This topic applies to Windows environments only.

There is one buffer pool cache per XDB Server, and all applications connecting to the XDB Server share this global memory. The overall size of the buffer cache has a large impact on database performance. If the cache is large enough to keep the required data in memory, less disk activity occurs and performance increases. If the cache pool is not large enough, the overall performance of the XDB Server can decrease, with the XDB Server becoming I/O-bound, as physical disk activity is required to service application requests.

The buffer pool cache effectiveness increases with multiple users, when a large amount of repeated access to the same data and index pages occur, and when one primary location is accessed.

The cache manager stores pages (4K each) of database object data. (Therefore, the number of pages is the cache size divided by four.) These database objects consist of table, index, and dictionary pages for all accessed locations. The dictionary pages originate from the dictionary files that reside in every location. As an application requests data from one of these object types, pages containing the data are transferred from the disk into the buffer pool.

Pages are not written to disk until one of the following occurs:

  • The XDB Server is shut down.
  • A checkpoint occurs.
  • Another page needs to be read into a full buffer pool.

Consider the following when determining how much RAM to allocate to cache:

  • A large cache usually speeds up online transaction processing (OLTP). However, if the checkpoint frequency is too infrequent, there can be detectable processing delays each time the checkpoint causes data to be written to the location tables. If checkpoint delays are a problem, either lower the cache amount or increase the checkpoint frequency. For more information about the CHECKPOINT command and the Checkpoint Frequency parameter, see the SQL Reference and the chapter Backup and Recovery chapter in this guide.
  • Decision support systems usually benefit from a larger cache, but the amount of cache does not necessarily have to be as large as the combined size of the database tables and indexes. For example, in a database where much of the data is historical (and rarely accessed), the amount of cache would only have to be large enough to contain the currently active data -- such as the current month or quarter.
  • On systems where sort operations are heavy, you might find that an increase in Sort Space Size gives a better performance gain than increasing or decreasing the cache. Once the appropriate Sort Space Size is defined, you should find it easier to determine the amount of cache needed.

Use the Cache Statistics screen of the Monitor Utility to help determine the best amount of cache for your system. When your XDB Server has reached a steady state (work is well in progress), check the percentage shown for Pages in Use. If Pages in Use is running at or near 100% and the Number of Tosses is high, then most of your allocated cache is being used and you might want to try increasing it. If Pages in Use and Tosses are running low, you have more cache allocated than you need.

Parent topic: Buffer Pool Size
Related information
Performance Tuning


Monitor Utility

Restriction: This topic applies to Windows environments only.

The Monitor Utility enables you to monitor the activity of the SQL Option Server.

  • Access and Control
  • Function Summary
  • User Activity
  • Server Status
  • User Resource Statistics
  • Memory Manager Statistics
  • Cache Statistics
  • Halt Query
  • Delete User
  • Shutdown Server
Parent topic: SQL Option Server Administration Guide


Access and Control

Restriction: This topic applies to Windows environments only.

Once the XDB Server is running, you can monitor XDB Server activity in any of the following ways:

  • Direct Access. You can run the Monitor Utility xdbmonn.exe (Windows) or xdbmon.exe (UNIX) on the server machine.
  • Remote Access. You can run the Monitor Utility xdbmonn.exe (Windows) or xdbmon.exe (UNIX) from a client machine.
  • Virtual Statistics Queries. You can use SQL to query the Virtual Statistics Tables. See the chapter Performance Tuning for more information on Virtual Statistics Tables.
Parent topic: Monitor Utility


Function Summary

Restriction: This topic applies to Windows environments only.

The Monitor utility provides access to the information described in the following table. The remainder of this chapter presents detailed information about each function.

Function | Description
User Activity | Displays information about each currently logged on user. Information includes isolation level and time logged on. An asterisk preceding an AuthID indicates that the user has a query open.
Server Status | Provides information on the number of users logged in, the number of queries open, and other useful information.
User Resource Statistics | Displays each user's system resource usage, including the number of queries, table locks (exclusive and shared), and record locks (exclusive and shared).
Memory Manager Statistics | Displays information about the amount of memory currently in use.
Cache Statistics | Displays caching and input/output statistics for the XDB Server cache manager. Monitor cache statistics when your system is running at steady state will help you determine the most effective amount of cache to allocate.
Halt Query | Stops a potentially long sort or query that is in progress.
Delete User | Aborts a user session when a user's workstation fails. The interrupted transaction is rolled back automatically.
Shutdown Server | Shuts down the XDB Server.
Parent topic: Monitor Utility


User Activity

Restriction: This topic applies to Windows environments only.

User Activity displays information about the users currently logged in to the XDB Server. If the lines of data exceed the screen size, the information will scroll automatically, pausing at each section.

Note: When a user performs certain functions (such as viewing a list of locations) in text mode tools, the system creates a new internal user in order to access the system location. The monitor will display this user in the User Activity information (with a system-generated name) along with the other "real" users.
User Name
Generally, this is the AuthID used to log on to the XDB Server. If the value in this field is prefixed with an asterisk (*), the user has a query open.

When security is on, the USER NAME displayed is the AuthID under which the user logged into the XDB Server. If security is off, the USER NAME displayed is the same as the Primary AuthID for the client, as set through Options Utility (Windows) or Interactive SQL Utility (UNIX).

If the user has a Secondary ID, the Secondary ID will be shown. If the user has been reassigned a different AuthID via server-to-server inbound or outbound mapping, the re-assigned (new) AuthID is shown.

Some user operations that access the SYSTEM location (such as displaying a list of tables or other browse features) temporarily create a pseudo user, PUBLIC1.

Node ID
This field displays the name of the node from which the user is working. The node name is set through Options Utility for SQLWizard clients (Windows) or Configuration Utility for XDBSQL clients (UNIX) on the client workstation. Each client machine must have a unique node name. If there are several clients (AuthIDs or sessions) with the same node name, the node name is appended with a number to indicate the session ID of the client session.

While the same AuthID and node name can be used to log in multiple times (from several different Wintel sessions, for example), the combination of AuthID, node name and session ID together are always unique.

Current Location
This field displays the name of the currently open location.
ILevel
This field displays the isolation level at which the user is currently working. The isolation level is set in any of the following ways:
  • Through the Options Utility (Windows) or User Profile Utility (UNIX)
  • By using the SET ISOLATION command
  • By using the new WITH clause on certain SQL statements (DB2 4.x)

See the SQL Reference for information about the SET ISOLATION command and the WITH clause.

Autocommit
This field displays the user's current autocommit level. Set the autocommit level with the Options Utility (Windows) or User Profile Utility (UNIX), or use the SET AUTOCOMMIT command. See the SQL Reference for information about the SET AUTOCOMMIT command.
Logged in Since
This field displays the date and time the user logged in to the XDB Server.
Parent topic: Monitor Utility


Server Status

Restriction: This topic applies to Windows environments only.

Server Status information includes the type and number of requests the XDB Server is currently processing and the XDB Server configuration settings.

Note:

When running remotely, the Monitor Utility cannot read the server configuration, and therefore cannot display all of the information in Server Status. The term "N/A" replaces unavailable information.

Server Status displays two types of information:

  • Dynamic information for the current and set maximum of a number of XDB Server parameters.
  • Static information that is constant while the XDB Server is running.
  • Dynamic Server Information
  • Static Server Information
Parent topic: Monitor Utility


Dynamic Server Information

Restriction: This topic applies to Windows environments only.

Dynamic server information displays current server activity (CURRENT column), and the limit set in the server configuration (MAXIMUM column) for the following values:

Values | Description
Users | Number of users logged into the XDB Server.
Active Users | Number of users with open SELECT queries.
Open Locations | Number of locations with open SELECT queries.
Open Files | Number of logically open files.
Open Queries | Number of open SELECT queries.
Lock Blocks In Use | Number of lock blocks in use.

Use the XDB Server Configuration Utility to set the limits for open locations, open files, open queries, and lock table size.

Parent topic: Server Status


Static Server Information

Restriction: This topic applies to Windows environments only.

Static server information is constant while the XDB Server is running, and includes:

Values | Description
Server Running Since | Date and time the XDB Server was started.
System Location Path | Path where the SYSTEM location for the XDB Server resides.
Temporary Path | Path where temporary files for the XDB Server are stored.
System Usage Monitor | Status of the system usage monitor (on or off).
System Security | Status of system security (on or off).
Packet Ver | Current XDB Server packet version.

Set the system location path, temporary path, system usage monitor, and system security parameters using the XDB Server Configuration utility.

Parent topic: Server Status


User Resource Statistics

Restriction: This topic applies to Windows environments only.

User Resource Statistics information includes query and lock statistics for each AuthID/Node currently using the XDB Server. If the user information exceeds the screen size, use PgUp, PgDn, up-arrow, and down-arrow to scroll through the information.

User

Generally, this is the AuthID used to log on to the XDB Server. When security is on, the USER NAME displayed is the AuthID with which the user logged into the XDB Server. If security is off, the USER NAME displayed is the same as the Primary AuthID for the client, as set through the Options Utility (Windows) or User Profile Utility (UNIX).

If the user has a Secondary ID, the Secondary ID will be shown. If the user has been reassigned a different AuthID via server-to-server inbound or outbound mapping, the re-assigned (new) AuthID is shown.

Some user operations that access the SYSTEM location (such as displaying a list of tables or other browse features) temporarily create a pseudo user, PUBLIC1.

Information Description
Node

This field displays the node name from which the user is working. The node name is set through the Options Utility (Windows) or Configuration Utility (UNIX) on the client workstation. Each client machine must have a unique node name. If there are several users (AuthIDs or sessions) with the same node name, the node name is appended with a number to indicate the session ID of the client session.

While the same AuthID and node name can be used to log in multiple times (from several different Windows sessions, for example), the combination of AuthID, node name and session ID together are always unique.

QDs

This field displays the number of open queries.

TsLocks

This field displays the number of shared table locks.

TxLocks

This field displays the number of exclusive table locks.

RsLocks

This field displays the number of shared record locks.

RxLocks

This field displays the number of exclusive record locks.

Parent topic: Monitor Utility


Memory Manager Statistics

Restriction: This topic applies to Windows environments only.

The Memory Manager Statistics Screen displays information about the amount of memory currently in use as follows:

Information | Description
Total Memory From OS | Total Memory From OS displays the total number of bytes (cumulative) allocated from the operating system.
Number Allocations From OS | Number Allocations From OS is the total number of memory allocations from the operating system (cumulative).
Current Allocations From OS | Current Allocations From OS is the current number of outstanding memory allocations from the operating system.
Parent topic: Monitor Utility


Cache Statistics

Restriction: This topic applies to Windows environments only.

The Cache Statistics screen displays caching statistics based on the cache option configured via the XDB Server Configuration utility. The screen displays information in units of 4K memory pages. You can use this information to analyze cache hit ratios and monitor cache effectiveness. The statistics include caching information for all table, dictionary, and index files.

Information | Description
Total Pages | Shows the number of pages in the cache.
Page Size | Size of each page in bytes.
Pages in Use | Percentage of the cache pages allocated to all files that use this cache.
Dirty | Percentage of total pages in the cache that have not yet been written to disk.
Cache Reads | Total number of pages requested from the cache.
Pages Read | Total number of pages read into the cache from disk.
Disk Reads | Total number of read I/O calls performed. Matches pages read, since pages are requested only one at a time.
Read Hit | Percentage of pages requested that did not require a disk read I/O operation.
Cache Writes | Total number of dirty pages released to the cache.
Pages Written | Total number of pages written to disk.
Disk Writes | Total number of disk write I/O calls performed. This number may be less than pages written since flushing causes a series of pages to be written to an accumulator first, and then all written together in one I/O.
Write Hit | Percentage of pages released dirty to the cache that were not written to the disk.
Tosses | Number of cache pages allocated to a file that were written out to disk to make room for a new page.
Checkpoints | Number of checkpoint calls made to this cache.
Parent topic: Monitor Utility


Halt Query

Restriction: This topic applies to Windows environments only.

Use the Halt Query option to stop the processing of any DML command (DELETE, INSERT, SELECT, and UPDATE). Halt Query is especially useful when a user's workstation hangs or when a potentially long query needs to be aborted.

If security is on, you must have SYSADM authority on the SYSTEM location (or have super user privileges) to perform this operation.

To halt a query:

  1. Press F8. A window containing AuthIDs (user names) and nodes appears.
  2. Use the up-arrow and down-arrow keys to highlight the name of the user whose query you want to halt.
  3. Press Enter. Confirm the action when requested.
Parent topic: Monitor Utility


Delete User

Restriction: This topic applies to Windows environments only.

Use the Delete User option to deactivate (cancel) a particular user session. If security is on, you must have SYSADM authority on the SYSTEM location (or have super user privileges) to perform this operation.

To delete a user:

  1. Press F9. A window containing AuthIDs (user names) and nodes appears.
  2. Use the up-arrow and down-arrow keys to highlight the name of the user whose query you want to halt.
  3. Press Enter. Confirm the action when requested.

If the logging system is on, the XDB Server will roll back and delete the session for the user selected.

Parent topic: Monitor Utility


Shutdown Server

Restriction: This topic applies to Windows environments only.

You can press the F10 key to shut down the server. If users are active, the monitor asks you to confirm the action.

  • If users are active when you shut down an XDB Server, their sessions will be terminated in mid-transaction, as though the XDB Server crashed. When the XDB Server is restarted, all incomplete transactions will be rolled back the next time that location is accessed. Use care, since user programs running on the workstations may not handle a case where the XDB Server no longer responds.
  • If a query is active when you shut down an XDB Server, the XDB Server will wait until the function is completed before shutting down.
Parent topic: Monitor Utility


Security and Authority

Restriction: This topic applies to Windows environments only.
  • Security System Concepts
  • Setting Up Security
  • System Level Access Control
  • Granted Authorities and Privileges
  • Security User Exit
  • AuthID List User Exit
Parent topic: SQL Option Server Administration Guide


Security System Concepts

Restriction: This topic applies to Windows environments only.

XDB Servers are shipped with security turned off to allow you unlimited access to the system. You can continue to operate without security indefinitely, if desired, even in a multiuser environment.

In a multiuser environment, if security is on at the server, then all users must have security on at their individual workstations. After security is turned on, each user or process must log in with a valid AuthID (a "user ID"). If the AuthID has a defined and required password, the password must be entered as well. When the user attempts to access a table, the server also verifies that the user has privileges to that table, which were set up using the GRANT and REVOKE commands. Only someone with super user privileges can establish AuthIDs and passwords.

Super Users

Each XDB Server is shipped with one super user called INSTALL. A super user is the only user who can:

  • Create and drop locations.
  • Add and remove users
  • Edit (update) system tables.
  • Assign super user privileges to another user ID.

You can create other super users at your discretion using the SQLWizard Users command on the Admin menu. (Windows) or by executing the CREATE USER SQL command in the Interactive SQL Utility (UNIX). (The SQL GRANT and REVOKE commands cannot be used for assigning super user privileges.)

The syntax for CREATE USER is as follows:

CREATE USER username TYPE [ USER | SUPERUSER ] PASSWORD password REQUIRED [ YES | NO ] option_list

where option_list is defined as:

SECONDARY ID authid GROUP group_list PRIORITY priority ACCESS AUTHORITY [ YES | NO ] COMMENT quoted-string

Requirements for XDB passwords can be controlled on an XDB user basis. ACCESS AUTHORITY set to NO completely disables an XDB user id. The SECONDARY ID, GROUPS, and PRIORITY concepts are all discussed in greater detail in the section System Level Access Control.

Super user privileges should be limited to a few trusted users with database administration expertise.

Note: In effect, when security is off, all users are super users. As long as security remains off, the Primary AuthID indicated in your client configuration is used as the qualifying name in the three-part object name:

location-name.authid.object-name.

Note: The INSTALL user ID that is shipped with an XDB Server does not have a password assigned to it. Use the SQLWizard Users command or run the ALTER PASSWORD SQL command to assign a password to this user ID as soon as possible. The syntax for ALTER PASSWORD is as follows:
 ALTER PASSWORD old_password TO new_password
Parent topic: Security and Authority


Setting Up Security

Restriction: This topic applies to Windows environments only.

The following is an overview of the process used to set up and activate security. This procedure must be performed by someone with super user authority.

Note: The following procedure assumes a single-server environment. If you are working in a multiserver environment or you are using a global security server, see the chapter Multiserver Security for additional setup procedures.

To set up security for an XDB Server:

  1. At the XDB Server, use the XDB Server Configuration utility to enable the server security option. See the chapter Server Configuration Utility for details.

    Note: No one else is allowed access to the server until you are finished setting up user IDs and passwords.
  2. At the XDB Server or at any client workstation attached to the XDB Server, use the client options utilities (Options UtilityUser Profile Utility) to select the XDB Server, specify your super-user ID, and enable security in the Options UtilityConfiguration Utility

    To set the options:

    Windows:
    • On the Connect tab, select the XDB Server on which you want to set up security.
    • On the Connect tab, specify your super user ID (e.g., INSTALL).
    • On the Security tab, enable the Client Security option.
    • On the Security tab, specify the Default Enforcement Level. This value determines the level of complexity that all passwords must have. See the topicPassword Enforcement Level for more information.
    UNIX:
    • On the main menu of the User Profile utility, select Multiuser Options.
    • Press F4 XDB Server.
    • Enter the XDB Server on which you want to set up security.
    • Press F7 Primary Authorization ID.
    • Enter your super user ID (e.g., INSTALL).
    • On the main menu of Configuration Utility, select Set Security Options.
    • Press Password Security to toggle it on and off.
    • Select ON and exit.

  3. Use SQLWizard's User command or the CREATE USER SQL syntax to create a user ID, password, and user type (user or super user) for each user of this XDB Server. Only the users that you define during this step will be allowed to log on to the Server, and they must present the proper user ID/password combination when they do so.

    Note: Apart from permitting access to an XDB Server, the user ID you create in this step also serves as a users default AuthID. You can override this default assignment by assigning a Secondary ID to the user, or the user can change it using the SET CURRENT SQLID command.
  4. A group ID allows you to assign location-level, database-level, and table-level privileges to a group of users. To set up group IDs, you can either use SQLWizard's Group command or run the following command:
     insert into sysxdb.sysacfgroups('group_name', '');

    You can also use a SecondaryID for this purpose. See the section AuthID Ownership and Usage Rules for a comparision of group IDs and SecondaryIDs.

  5. Run the SQL GRANT and REVOKE commands from an SQL utility (i.e. SQLWizard) to assign specific privileges (or pre-defined sets of privileges called authorities) to each AuthID or GroupID. Privileges and authorities are granted within each location. See the topic Granted Authorities and Privileges topic for more information.
  6. When you are finished creating users, run client options/configuration utilities at each user's workstation and turn on the Client Security option. On the Security tab, specify the Default Enforcement Level. Each client must agree with the server about the password enforcement level. See the section Password Enforcement Level for more information. You must also inform your users of their new user IDs and passwords. Once they log on, they can change their password using the SQLWizard Change Password command or run the ALTER PASSWORD SQL command.
Parent topic: Security and Authority


System Level Access Control

Restriction: This topic applies to Windows environments only.

System-level access control refers to that part of the security system that controls the login process, passwords, the assignment of users to groups, and the definition of SecondaryIDs. These aspects of security are described in this topic.

  • Password Enforcement Level
  • XDBACF Database
  • AuthID Ownership and Usage Rules
Parent topic: Security and Authority


Password Enforcement Level

Restriction: This topic applies to Windows environments only.

Before setting up initial passwords for users (or before users change their passwords), select a password enforcement level from the options provided on the Options Utility.

Password level options are:

Level | Options
Level 1: | Password must be four or more characters.
Level 2: | Password must be six or more characters and include at least one digit (numeric).
Level 3: | Password must be six or more characters, include at least one digit (numeric), and must include the two randomly generated characters that appear in the prompt message on the SQLWizard Add/Modify User screen. (From the SQLWizard Admin menu, select User.)

Users can change their passwords by using the SQLWizard Change Password command.

Note:

Depending on your security needs, you might wish to establish two AuthID/Password accounts on the server; one for Micro Focus locations and one for DB2 locations.

Parent topic: System Level Access Control


XDBACF Database

Restriction: This topic applies to Windows environments only.

The system location for each XDB Server contains a database called XDBACF (Access Control Facility). This database contains information you enter for each user and group via the SQLWizard Admin menu. Information in the XDBACF database applies to all users and all locations on the server.

The XDBACF database contains the following tables and columns:

  • SYSXDB.SYSACFUSERS contains a list of all users, including the following information for each user:
    AuthID | AccessAuthority
    SecondaryID | RequirePassword
    Password | UserType
    DateOP (date of password) | Remarks
    TimeOP (time of password)
    Note:

    If you are a super user, do not edit or update a user's PASSWORD or TIMEOP in this table. Use the SQLWizard instead.

  • SYSXDB.SYSACFGROUPS contains a list of all GroupIDs that have been defined. Columns in this table are:
    GroupAuthID
    Remarks
  • SYSXDB.SYSACFMEMBERS contains a list of AuthIDs and the GroupIDs that each is authorized to use. Each user (Primary AuthID) can have several entries, one entry for each GroupID that the person is authorized to use. Columns in this table are:
    UserAuthID
    GroupAuthID
  • SYSXDB.SYSGOVERNOR contains information on the type of activities that can be performed by certain users during certain periods. Columns in this table are:
    Priority | MaxIdleTime
    MaxNumApiCalls | MaxFetches
    MaxTimeEngine | StartFreeTime
    MaxTimePerApi | EndFreeTime
  • SYSXDB.SYSUSERPRIORITY contains information about priorities that have been assigned to users.

See the SQL Reference for the specific format of each of these tables.

Parent topic: System Level Access Control


AuthID Ownership and Usage Rules

Restriction: This topic applies to Windows environments only.

Primary AuthIDs, GroupIDs and SecondaryIDs can be used in combination when setting up system security. These IDs are defined and used as follows:

  • Primary AuthID. This is the primary identifier for all users of an XDB Server. A Primary AuthID can be assigned to a process or program that requires access to XDB Server data.
    • Used for logging in to an XDB Server.
    • Appears as an identifier on server screens that are used to monitor activity of users.
    • Used as the default for the AuthID portion of a database object's three-part name when the user creates the object. A different ID will become the default if the SET CURRENT SQLID command is issued, if a SecondaryID is defined, or if a security user exit modifies the Current SQLID (applies to Windows environments only). See the Security User Exit topic for information.
    • Used to determine privileges when user attempts to access a database object. If a different ID is in effect (from issuance of a SET CURRENT SQLID command), that ID's privileges are available also. If the Primary AuthID belongs to a group, the privileges granted to the GroupID also are available to the user of the Primary AuthID. If a SecondaryID is defined, the Primary AuthID's privileges are not valid, but rather the SecondaryID's privileges take effect (along with its groups, if any).
  • Group or GroupID. This is a special identifier that can be assigned to one or more Primary AuthIDs. The privileges granted to the GroupID are available to every Primary AuthID to which the GroupID is assigned. In addition, each Primary AuthID can have multiple GroupIDs assigned to it, thus gaining the privileges of all of those groups combined. Other privileges can be granted to the Primary AuthID, providing the user with the assigned group privileges plus the privileges assigned specifically to the Primary AuthID.
    Note: If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.
  • SecondaryID (optional). If defined, this AuthID replaces the Primary AuthID as soon as the user logs in to the XDB Server. The user (or process) is given the privileges that have been granted to the SecondaryID. If the Primary AuthID had privileges granted to it, those privileges would be ignored. When a user with a SecondaryID creates an object, the AuthID portion of the object's name is the SecondaryID. All other users who use the same SecondaryID will have all privileges on that object.
    Note: The XDB Server SecondaryID is not the same as the DB2 Secondary Authorization ID. The IBM method of defining multiple Secondary Authorization IDs and assigning them to Primary AuthIDs in RACF (Resource Access Control Facility) is similar to Micro Focus' group concept.
    Note: If you use an object creator's AuthID as a SecondaryID for other users, those other users will all have all privileges on the object. A user with a SecondaryID is seen by the system as being the SecondaryID, and therefore has all privileges on all objects that carry that AuthID as the second part of the object name. Privileges cannot be revoked from the creator of an object, or from a user who's Current SQLID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on the privileges of an object's creator/owner.
  • Current SQLID. The Current SQLID is a special register that keeps track of which AuthID is in effect for a given client session. A user with SYSADM or super user authority can issue the SET CURRENT SQLID command to change the SQLID to any valid AuthID. If a user has a SecondaryID, the Current SQLID changes from the Primary AuthID to the SecondaryID at the start of the client session.

The table and the descriptions following it illustrate how various GroupID and SecondaryID assignments can affect the naming of and access to database objects.

When security is on, the Primary AuthID and Password are used when each user (or process) logs in to the XDB Server. The system then checks the SYSXDB.SYSACFUSERS table for the existence of a SecondaryID. If present, the user (or process) assumes the identity of the SecondaryID and is accorded all privileges that have been defined for the SecondaryID. If no SecondaryID exists for the user, then privileges are based on what has been granted for the Primary AuthID and the groups to which it belongs.

To grant a particular set of privileges to a group of users, without having to define those privileges for each user individually, assign multiple users to the same SecondaryID. Grant the privileges to the SecondaryID (essentially just another AuthID). However, the preferred method for assigning the same privilege set to many users is to use the XDB Group, which is similar to the DB2 concept of assigning multiple secondary authorization IDs to a primary authorization in IBM's RACF (Resource Access Control Facility).

Note: If several users have the same SecondaryID, all the objects they create will be owned by the SecondaryID and not by the individual users. All users having that same SecondaryID will have all privileges on those objects. The GRANT and REVOKE commands have no effect on privileges of an object's creator/owner, which in this case includes all users with the SecondaryID that is also the AuthID portion of the object's name. All of these users are seen by the system as being the owner of the object.
Primary AuthID | Secondary ID | Group Name | Creates Table... (see note 1) | Owner | Authorized Users
TECHPUBS | -- | -- | Created as a Primary AuthID. Privileges are assigned. Used as a SecondaryID for one or more Primary AuthIDs.
-- | -- | WRITERS | Created as a group. Privileges are assigned to the group. GroupIDs are assigned to Primary AuthIDs.
ERIC | -- | -- | ERIC. TABLE1 | ERIC | ERIC
DEBBIE | -- | -- | DEBBIE TABLE1 | DEBBIE | DEBBIE
DAVID | -- | WRITERS | DAVID. TABLE1 | DAVID | DAVID and if access is granted to WRITERS, then also ARLENE.
ARLENE | -- | WRITERS | ARLENE. TABLE1 | ARLENE | ARLENE and if access is granted to WRITERS, then also DAVID.
ROCHELLE | TECHPUBS | -- | TECHPUBS. TABLE1 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and if access is granted to WRITERS, then also DAVID, ARLENE.
STEVE | TECHPUBS | -- | TECHPUBS. TABLE2 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE) and if access is granted to WRITERS, then also DAVID, ARLENE.
PABLO | TECHPUBS | WRITERS (ignored, see note 2) | TECHPUBS. TABLE3 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)
BRUCE | TECHPUBS | WRITERS (ignored, see note 2) | TECHPUBS. TABLE4 | TECHPUBS | Users with TECHPUBS as SecondaryID (ROCHELLE, STEVE, PABLO, BRUCE)

Table Notes

  1. All scenarios described here assume that the user does not specify an AuthID when creating the object and the user has not changed his Current SQLID.
  2. Pablo and Bruce do not have privileges defined for the group writers because as soon as they log in, they both become techpubs, and techpubs is not assigned to the group writers in this example.

As shown in the above table, the AuthID portion of the name assigned to a database object when it is created, and the users who have access to that object depend on how AuthIDs, GroupIDs and SecondaryIDs are defined. The object naming and usage rules are as follows:

  1. If a user belongs to a group and creates an object, the AuthID portion of the object name will be the user's own Current SQLID, and not the GroupID. This allows more than one user to create objects of the same name within the same location.

    For example, if user david (who is in the writers group) creates a table called staff in the location called books, the table's three-part name would be books.david.staff. If user arlene (who is also assigned to the writers group) attempts to create a table called staff, in the location called books, the table's three-part name would be books.arlene.staff. Since the three-part names of the two tables are unique, each user can have a table of the same one-part name within a location.

    Note: If a user has no Secondary ID and has not otherwise changed his Current SQLID, the Current SQLID is the user's Primary AuthID.
    Note: If you specify a GroupID as the second part of an object's three-part name, all users who are assigned to that group will automatically have all privileges on the object. Privileges cannot be revoked from a user whose GroupID is the same as the object creator's AuthID. The GRANT and REVOKE commands have no effect on these privileges.
  2. If a GRANT command gives privileges to a GroupID, all users who are members of that group will have those privileges.
  3. If a user belongs to multiple-groups, the user has all privileges that have been granted to each group.
  4. If a user has a SecondaryID and creates an object, the AuthID portion of the object name will be the SecondaryID (assuming that the user has not changed his Current SQLID, which by default takes the value of the SecondaryID). Two users with the same SecondaryID cannot create objects of the same name within a location.

    For example, if user rochelle (who has a SecondaryID of techpubs) creates a table called staff in the location called books, the table's three-part name would be books.techpubs.staff. If user steve (who also has techpubs as his SecondaryID) attempts to create a table called staff, the table's three-part name would also be books.techpubs.staff. This is not allowed.

  5. Any object whose name has a SecondaryID as the AuthID qualifier can be accessed by any user who has that same SecondaryID as his Current SQLID. GRANT and REVOKE commands have no effect on these users' access to the objects because these users are all seen by the system as being the owner of the object. All users who have the SecondaryID that is the owner of the object will have all privileges on the object.

    Users rochelle, steve, pablo, and bruce all have all privileges on techpubs.table1, techpubs.table2, techpubs.table3, and techpubs.table4. GRANT and REVOKE commands for these users and tables will have no effect.

    If an object has a different owner, then granting privileges to the SecondaryID will give those privileges to all users who have that SecondaryID as their Current SQLIDs.

  6. If a user has a SecondaryID (as his Current SQLID) and belongs to a group and creates an object, the AuthID portion of the object name will be the SecondaryID. Other users in the group do not have access to the object, because privileges on the object have not been granted to the group. The object is owned by the SecondaryID. Only users with the same SecondaryID (as their Current SQLIDs) can access the object. (However, the original user who created the object of this example can access other objects to which the group has been granted privileges.)
Parent topic: System Level Access Control


Granted Authorities and Privileges

Restriction: This topic applies to Windows environments only.

When security is on, the user's Current SQLID must either be the owner of the object, or have specific privileges in the location where the object resides. You can grant privileges to a Primary AuthID, a GroupID or a SecondaryID. An AuthID can be granted an authority, which is a pre-defined set of privileges.

Authorities are suggestive of different levels of responsibility. These responsibilities might or might not suit your needs. See the SQL GRANT command in the SQL Reference for detailed information.

Privileges (and authorities) can be granted at the location level (SYSADM or SYSCTRL), database level (DBADM, DBCTRL or DBMAINT), or by table or column within a table. AuthIDs must be granted privileges within each location they are authorized to use. Privileges in one location do not carry over to another location.

To assign privileges to a given AuthID in two or more locations, set up groups, then assign privileges to each GroupID for one location. The groups that represent the locations for which the user is to be allowed privileges are then assigned to the user's AuthID.

To allow a user to have unlimited privileges throughout the system (all locations), grant super user privileges to the user's Primary AuthID.

Note:

Only a super user can create locations, drop locations, edit (update) system tables, and assign super user status to another user. Super user privileges can be assigned in SQLWizard or by editing the USERTYPE column in the user's record in the SYSXDB.SYSACFUSERS table.

Users cannot grant privileges to themselves and cannot revoke privileges from themselves. Likewise, GRANT and REVOKE commands have no effect on users whose AuthIDs (or SecondaryIDs or GroupIDs) are the same as the AuthID portion of an object's name.

  • The DSNDB06 Database
  • Granting and Revoking Privileges
Parent topic: Security and Authority


The DSNDB06 Database

Restriction: This topic applies to Windows environments only.

The DSNDB06 database, which is a system catalog database provided in each location, contains the specific authorities and privileges that you define for each AuthID, SecondaryID or GroupID with the SQL GRANT and REVOKE commands. This information is stored in the following security-related tables:

  • SYSIBM.SYSDBAUTH (Database Authorization)
  • SYSIBM.SYSUSERAUTH (User Authorization)
  • SYSIBM.SYSTABAUTH (Table Authorization)
  • SYSIBM.SYSCOLAUTH (Column Authorization)

See the SQL Reference for a complete definition of each of these tables.

Parent topic: Granted Authorities and Privileges


Granting and Revoking Privileges

Restriction: This topic applies to Windows environments only.

After you set up the AuthIDs, SecondaryIDs and groups, you can define the privileges and authority for each, using the SQL GRANT and REVOKE commands. Set up the granted privileges before or after turning on security. However, any grants you issue when security is off will not take effect until you turn security on.

Note: Warning:

Be sure you are operating in the location for which you want to define privileges. Each location has its own DSNDB06 database for maintaining authorization information. (To change locations, use the SET LOCATION TO command in interactive SQL or change your default location in the SQLWizard or Options Utility.)

The basic GRANT command formats supported by XDB Servers are shown below. The REVOKE command formats are similar.

  • Database Privileges
    GRANT privilege
    ON DATABASE database-name
    TO authid
    [ WITH GRANT OPTION ]
  • System Privileges
    GRANT privilege
    TO authid
    [ WITH GRANT OPTION ]
  • Table or View Privileges
    GRANT {ALL | privilege}
    ON TABLE table-name
    TO {PUBLIC | PUBLIC AT ALL LOCATIONS | authid}
    [WITH GRANT OPTION]
  • Column Privileges
    GRANT UPDATE(column-name)
    ON TABLE table-name
    TO {PUBLIC | PUBLIC AT ALL LOCATIONS | authid}
    [WITH GRANT OPTION]

where:

privilege | is one or more Authorities and/or privileges, separated by commas
authid | is a user's Primary AuthID, a SecondaryID or a GroupID.
UPDATE (column-name) | is one or more occurrences of this phrase separated by commas. You must enter the word UPDATE and the column name in parentheses for each column on which the update privilege is to be granted.
PUBLIC | is used to grant the privilege to all users at the current location.
PUBLIC AT ALL LOCATIONS | is used to grant the privilege to all users, including remote users who are accessing this location.

See the SQL Reference for detailed information about using these commands, including descriptions of the various privileges and authorities that are available for each.

Parent topic: Granted Authorities and Privileges


Security User Exit

Restriction: This topic applies to Windows environments only.

The Security user exit allows you to use a security program other than the one provided by the XDB Server, such as a network security system or a custom written program.

A custom security system must be compiled into a dynamic link library. On Windows systems this dynamic link library is called XSEC41.DLL, and must be placed in the XDB directory. This security scheme is then used instead of the standard security system.

Parent topic: Security and Authority


AuthID List User Exit

Restriction: This topic applies to Windows environments only.

AuthID list user exit allows you to retrieve AuthID, Current SQLID, group membership, and super user information from a source other than the XDB Server user database.

You must compile the AuthID List program into a dynamic link library. On Windows systems this dynamic link library is called XAUT41N.DLL, and must be placed in the XDB directory. This AuthID List is then used instead of the standard XDB Server user database.

Parent topic: Security and Authority


Server-to-server Connectivity

Restriction: This topic applies to Windows environments only.

The server-to-server connectivity capability provided with the XDB Server allows a client accessing one XDB Server to actually access the data in a location controlled by another XDB Server in a distributed environment. Server-to-server connectivity extends the concepts of remote unit of work (RUW) and distributed unit of work (DUW) to encompass data controlled by multiple XDB Servers.Location access can be done in two ways: either by using a three-part name (location.authid.object) or alias; or by using the SET LOCATION command or embedded CONNECT command. Server-to-server connectivity removes the need to have to change the client settings to access another remote XDB Server.To allow access to a remote location, you must maintain the system tables to reflect known locations and server names.Throughout the XDB Server documentation, the term primary server is used to refer to the XDB Server to which the user is connected. The term remote server is the XDB Server elsewhere on the LAN that controls the location the user wishes to access.Whether three-part names or connect access is used, information about remote locations must be registered with the XDB Server to which you are currently connected. This is done by inserting information into tables in the system catalog. The system tables that must be updated, as well as sample entries, are listed in each section.Because the information is registered in the system catalog tables, the user does not have to know which XDB Server controls which location. You simply need to know the name of the location to be accessed.

  • Three-Part Name Access
  • Connect (Set Location) Access
Parent topic: SQL Option Server Administration Guide


Three-Part Name Access

Restriction: This topic applies to Windows environments only.

One method of accessing data in a remote location involves using a three-part name. An application simply uses the fully qualified name (location.authid.object) of a table or view that resides in another location. Based on information in the system catalog tables on the current XDB Server, the request is sent to the appropriate XDB Server and data is returned. This configuration is also referred to as a distributed unit of work (DUW).

Multiple locations controlled by multiple XDB Servers can be queried in this way. A client application can request data from any XDB Server in the distributed environment, as long as the server and the locations it controls are registered in the system catalog tables.

An alias of a three-part name can also be used. Remember that aliases actually provide better location transparency because the first part of the three-part name need not be specified. Throughout the Server-to-Server Connectivity an alias can also be used wherever a three-part name can be used.

  • Disconnecting
  • Privileges
  • Examples
  • System Tables
  • Sample System Tables
  • Setting Up Server-to-Server Connectivity
Parent topic: Server-to-server Connectivity


Disconnecting

Restriction: This topic applies to Windows environments only.

Generally, the connection between the primary and remote server is not broken until the client application ends the session by logging out of the primary server. If the access of the remote server was done interactively, it cannot explicitly disconnect from the remote server. If the access was done through embedded SQL, the program can use the CONNECT RESET command. See the SQL Reference for a description of the CONNECT RESET command.

Parent topic: Three-Part Name Access


Privileges

Restriction: This topic applies to Windows environments only.

Control privileges at each individual server. Each server controls its own access security. Privileges granted at each server affect all users who connect to it, whether by logging in directly or accessing the server via a three-part name or alias. Additional access control can be had by using security mapping and global security. See the chapter Multiserver Security for a more detailed discussion of security mapping and global security.

Parent topic: Three-Part Name Access


Examples

Restriction: This topic applies to Windows environments only.

Client1 is logged into the XDB Server xdbserve and is running the SQL Wizard (Windows) or Interactive SQL (UNIX). Client1 issues a SELECT command that references the table orders.eastern.may.

This request is received by the XDB Server xdbserve. The xdbserve server checks its system catalog table SYSIBM.SYSLOCATIONS. This table indicates that the location orders is controlled by the XDB Server sales.

The request is then passed on to the XDB Server sales, which processes the query. The query result is returned to xdbserve, which passes the data back to the SQL Wizard (Windows) or Interactive SQL (UNIX) on client1.

Now consider that, in the next SQL statement issued, client1 references products.gui.productlist. Again, the same system catalog tables on xdbserve are checked.

This time, the request is sent to the XDB Server, develop.

Parent topic: Three-Part Name Access


System Tables

Restriction: This topic applies to Windows environments only.

You must insert data into two XDB Server system tables, SYSIBM.SYSLUNAMES and SYSIBM.SYSLOCATIONS, on the primary XDB Server in order to use three-part names or aliases for server-to-server connectivity. This can be done through SQL commands in the SQL Wizard (Windows) or Interactive SQL (UNIX).

Note: When updating SYSLOCATIONS and SYSLUNAMES, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use server-to-server connectivity. All other columns can have NULL values. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSLOCATIONS
Parent topic: Three-Part Name Access


SYSIBM.SYSLUNAMES

Restriction: This topic applies to Windows environments only.

The columns of this table contain information on LUNAMES used for server-to-server or XDB Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used in XDB Server.
USERNAMES | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSLOCATIONS

Restriction: This topic applies to Windows environments only.

The columns of this table contain information about all locations that are accessible for RUW and DUW processing, including local locations in SYSXDB.SYSLOCALS plus remote locations accessible using server-to-server connectivity or XDB Link.

Name | Type | Len | Description
LOCATION required | CHAR | 16 | Name of the location.
LOCTYPE required | CHAR | 1 | Indicates the location type:
 |  |  | X | XDB
 |  |  | R | RPC
 |  |  | C | CICS
 |  |  | D | DRDA
LINKNAME required | CHAR | 8 | Name of the XDB Server which controls the location, if using server-to-server connectivity. LUNAME for the accessible system if using XDB Link.
LINKATTR required | VARCHAR | 64 | Type of protocol used to connect to the XDB Server when using server-to-server connectivity:
 |  |  | S | SPX
 |  |  | B | NetBIOS
 |  |  | N | Named Pipes
 |  |  | T | TCP/IP (Set the hostname and IP address in the XDBNET.INI file.)
 |  |  | or The name of the mainframe program with which XDB Link will communicate if using XDB Link.
Parent topic: System Tables


Sample System Tables

Restriction: This topic applies to Windows environments only.

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server xdbserve to execute the examples for three-part name or alias access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
sales |  |  |  |  |
develop |  |  |  |  |

The first row indicates that the XDB Server sales can be accessed. The second row indicates that the XDB Server develop can be accessed.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server xdbserve to execute the examples for three-part name or alias access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
staff | X |  |
orders | X | Sales | B
products | X | Develop | N

The first row indicates that the staff location is an XDB location controlled by the current (primary) XDB Server xdbserve.

The second row indicates that the orders location is an XDB location controlled by a remote XDB Server sales and can be reached via the NetBIOS protocol.

The third row indicates that the products location is an XDB location controlled by a remote XDB Server develop and can be reached via the Named Pipes protocol.

Parent topic: Three-Part Name Access


Setting Up Server-to-Server Connectivity

Restriction: This topic applies to Windows environments only.

In order to set up server-to-server connectivity, you must configure both the primary XDB Server and the remote XDB Server. The primary XDB Server is the XDB Server which clients will log into. From this server, they will be able to access remote XDB locations by using either three-part names or aliases. The instructions in this topic discuss one primary server with one remote server.

If you wish to have a fully distributed environment, complete the Primary Server Configuration instructions for each XDB Server that you wish to be a primary XDB Server. Complete the Remote Server Configuration instructions for each XDB Server you wish to be a remote XDB Server.

The following instructions assume that security is turned on (through the XDB Server Configuration utility) for the primary XDB Server.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Three-Part Name Access


Primary Server Configuration

Restriction: This topic applies to Windows environments only.

To configure a server as a primary XDB Server, you must update the system tables. In the examples, the primary XDB Server is xdbserve.

To update the system tables:

Note:

Do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.

  1. On any client logged in to the primary XDB Server, start SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. Open an SQL Window and set the current location to the SYSTEM location:

    SET LOCATION TO system;

  4. Issue the following SQL command to insert information about a remote server into the SYSIBM.SYSLUNAMES table:
    INSERT INTO sysibm.syslunames
    VALUES ("remote-server","","","","","");

    where remote-server is the name of a remote XDB Server to be accessed. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on using these values.

    In the examples used in this topic, the SQL command:

    INSERT INTO sysibm.syslunames
    VALUES ("sales","","","","","");

    would have been issued on the XDB Server XDBSERVE.

  5. Issue the following SQL command to insert information about a remote location into the SYSIBM.SYSLOCATIONS table:
    INSERT INTO sysibm.syslocations
    VALUES ("remote-location","X",
            "remote-server","link-type");

    where:

    remote-location | is the name of the remote location to be accessed (unique among all locations on all servers that are used in distributed processing).
    X | indicates it is an XDB Server.
    remote-server | is the name of the remote server that controls the remote location.

    link-type is the communication protocol used to connect to the remote server.

    In the examples used in this topic, the SQL command:

    INSERT INTO sysibm.syslocations
    VALUES ("orders","X","sales","B");

    would have been issued on the XDB Server XDBSERVE.

  6. Repeat Steps 4 and 5 for each remote XDB Server and location that will be accessed from this primary server.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
Parent topic: Setting Up Server-to-Server Connectivity


Remote Server Configuration

Restriction: This topic applies to Windows environments only.

The remote XDB Server must be configured and started, and privileges must be granted. In the examples, the remote XDB Server is sales.

If security is on, clients must have privileges on the tables they wish to access on the remote server. Be sure to grant the appropriate privileges to each client on the remote server.

AuthIDs (usernames) are created using the SQL Wizard Admin menu (Windows) or the CREATE USER command in Interactive SQL (UNIX). Privileges are granted using SQL GRANT command from the SQL Wizard (Windows) or Interactive SQL (UNIX). See the chapter Security and Authority for more information on AuthIDs and privileges.

AuthID mapping can make this task much easier in a large distributed environment. See the chapter Multiserver Security for more information about AuthID mapping.

Parent topic: Setting Up Server-to-Server Connectivity


Connect (Set Location) Access

Restriction: This topic applies to Windows environments only.

The second method of accessing data in a remote location involves connecting to the remote XDB Server. To connect to the remote XDB Server interactively, use the SET LOCATION command (an SQL extension). To connect to the remote XDB Server with embedded SQL, use the CONNECT command.

A client interactively issues a SET LOCATION command or an application created using embedded SQL issues a CONNECT command. Based on information in the system catalog tables on the current XDB Server, the client's connection is transferred to the appropriate XDB Server and data is returned. This configuration is also referred to as a remote unit of work (RUW).

When a client is connected to a remote server while still logged in to the initial XDB Server, the system tables used for any new queries are the system tables on the remote location. Note that when connecting to a different XDB Server, you are not completely detached from previous XDB Servers. The routing software on each XDB Server is still used to determine from where the request came and to where it should go.

In this way, a client application can connect to any XDB Server in the distributed environment, as long as the Server and the locations it controls are registered in the system catalog tables.

  • Disconnecting
  • Privileges
  • Examples
  • System Tables
  • Configuring Server-to-Server Connectivity
Parent topic: Server-to-server Connectivity


Disconnecting

Restriction: This topic applies to Windows environments only.

Note that when the client application is done with the location on the remote server, the client application can disconnect from the remote server (using the embedded SQL command CONNECT RESET). By disconnecting, all links to the remote server are removed and the connection is returned to the primary server. If multiple XDB Servers have been accessed in sequence, the connection will be returned to the XDB Server most recently controlling the client.

Note:

If SET LOCATION TO was used by any client to connect to the second server, there is no way to break the connection until the user ends the session.

Parent topic: Connect (Set Location) Access


Privileges

Restriction: This topic applies to Windows environments only.

Control privileges at each individual server. Each server controls its own access security. Privileges granted at each server affect all users who connect to it, whether by logging in directly or accessing the server by connecting from another server. Additional access control can be had by using security mapping and global security. See the chapter Multiserver Security for a more detailed discussion of security mapping and global security.

Parent topic: Connect (Set Location) Access


Examples

Restriction: This topic applies to Windows environments only.

All of the examples assume that each XDB Server has already been set up with the appropriate information in the system tables. If a request is made to connect to an unknown location not listed in the system tables, an X288 error message (Statement reference to remote object is invalid) is returned to the user.

Client1 is logged into the XDB Server xdbserve and is running the SQL Wizard (Windows) or Interactive SQL (UNIX). Client1 issues a SET LOCATION TO ORDERS command. The xdbserve server checks its system table SYSIBM.SYSLOCATIONS, which indicates that the location orders is controlled by the XDB Server sales.

The xdbserve server transfers the clients connection to the XDB Server sales. Note that each communication between client1 and the XDB Server sales must go through xdbserve (shown by the dashed lines through xdbserve).

Now, any requests that are sent by the client are verified by the system tables on the XDB Server sales. If client1 issues a SELECT query that references the table eastern.may without specifying a location, it is assumed that this table is in the location orders on the XDB Server sales.

To continue the example, client1 (who is logged in to xdbserve but connected to sales) issues a SET LOCATION TO PRODUCTS command. In this case, sales checks its system catalog table SYSIBM.SYSLOCATIONS, which indicates that the location products is controlled by the XDB Server develop.

Sales transfers the client's connection to the XDB Server develop. Any requests that are sent by the client are verified by the system catalog tables on the XDB Server develop. Communication between client1 and develop must still pass between the other XDB Servers to which it has been connected, xdbserve and sales. This communication is shown by the dashed lines through the XDB Servers.

Finally, consider that client1, connected to develop via xdbserve and sales, issues a SET LOCATION TO STAFF command. In this case, develop checks its system catalog table SYSIBM.SYSLOCATIONS, which indicates that the location staff is controlled by the XDB Server xdbserve.

This will create a communications loop back to xdbserve. This type of looping is not recommended, as the connections between the various servers creates congestion on each server. In addition, response time is increased because queries have to be passed between multiple servers.

Instead, keep track of the locations and servers you have accessed. If you are working interactively (for example, through the SQL Wizard (Windows) or Interactive SQL (UNIX)), then log out and log back in. If you are using embedded SQL, issue CONNECT RESET commands after you no longer need the data on a particular server.

Parent topic: Connect (Set Location) Access


System Tables

Restriction: This topic applies to Windows environments only.

You must insert data into two system tables, SYSIBM.SYSLUNAMES and SYSIBM.SYSLOCATIONS, on the primary XDB Server in order to use server-to-server connectivity via connect access. The tables on the primary server must be updated so that clients can get from the primary to the remote server.

Note: When updating SYSLOCATIONS and SYSLUNAMES, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use server-to-server connectivity. All other columns can have NULL values. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSLOCATIONS
  • Sample System Tables
Parent topic: Connect (Set Location) Access


SYSIBM.SYSLUNAMES

Restriction: This topic applies to Windows environments only.

The columns in this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used in XDB Server.
USERNAMES | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSLOCATIONS

Restriction: This topic applies to Windows environments only.

The columns in this table contain information about all locations that are accessible for RUW and DUW processing, including local locations in SYSXDB.SYSLOCALS plus remote locations accessible using server-to-server connectivity or XDB Link.

Name | Type | Len | Description
LOCATION required | CHAR | 16 | Name of the location.
LOCTYPE required | CHAR | 1 | Indicates the location type:
 |  |  | X | XDB
 |  |  | R | RPC
 |  |  | C | CICS
 |  |  | D | DRDA
LINKNAME required | CHAR | 8 | Name of the XDB Server which controls the location, if using server-to-server connectivity. LUNAME for the accessible system if using the XDB Link.
LINKATTR required | VARCHAR | 64 | Type of protocol used to connect to the XDB Server when using server-to-server connectivity:
 |  |  | S | SPX
 |  |  | B | NetBIOS
 |  |  | N | Named Pipes
 |  |  | T | TCP/IP (Set the hostname and IP address in the XDBNET.INI file.)
 |  |  | or The name of the mainframe program with which XDB Link will communicate if using XDB Link.
Parent topic: System Tables


Sample System Tables

Restriction: This topic applies to Windows environments only.

The tables in this topic show the values needed in the system tables on various XDB Servers to execute the examples discussed.

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server xdbserve to execute the examples discussed in this topic for connect access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
sales |  |  |  |  |

This table indicates that the XDB Server sales can be accessed from xdbserve.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server xdbserve to execute the examples discussed in this topic for connect access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
staff | X |  |
orders | X | Sales | B

The first row indicates that the staff location is an XDB Server location controlled by the current (primary) XDB Server xdbserve.

The second row indicates that the orders location is an XDB Server location controlled by a remote XDB Server sales, and can be reached via the NetBIOS protocol.

  • Sales Server
  • Develop Server
Parent topic: System Tables


Sales Server

Restriction: This topic applies to Windows environments only.

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the XDB Server sales to execute the examples discussed in this topic for connect access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
Develop |  |  |  |  |

This table indicates that the XDB Server develop can be accessed from sales.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server sales to execute the examples discussed in this topic for connect access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
orders | X |  |
products | X | develop | N

The first row indicates that the orders location is an XDB Server location controlled by the current XDB Server sales.

The second row indicates that the products location is a location controlled by a remote XDB Server sales, and can be reached via the Named Pipes protocol.

Parent topic: Sample System Tables


Develop Server

Restriction: This topic applies to Windows environments only.

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the XDB Server develop to execute the examples discussed in this topic for connect access.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
xdbserve |  |  |  |  |
sales |  |  |  |  |

The first row indicates that the XDB Server xdbserve can be accessed from develop.

The second row indicates that the XDB Server sales can be accessed from develop.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server develop to execute the examples discussed in this topic for connect access.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
staff | X | xdbserve | B
products | X |  |

The first row indicates that the staff location is a location controlled by a remote XDB Server xdbserve, and can be reached via the NetBIOS protocol.

The second row indicates that the products location is an XDB location controlled the current XDB Server, develop.

Parent topic: Sample System Tables


Configuring Server-to-Server Connectivity

Restriction: This topic applies to Windows environments only.

In order to set up server-to-server connectivity, you must configure both the primary XDB Server and the remote XDB Server. The primary XDB Server is the XDB Server which clients will log into. From this server, they will be able to access remote locations by connecting to the remote server. The instructions in this topic discuss one primary server with one remote server.

If you wish to have a fully distributed environment, complete the Primary Server Configuration instructions for each XDB Server that you wish to be a primary XDB Server. Complete the Remote Server Configuration instructions for each XDB Server you wish to be a remote XDB Server.

The following instructions assume that security is turned on (through the XDB Server Configuration utility) for the Primary XDB Server.

  • Primary Server Configuration
  • Remote Server Configuration
  • Configuring Server Access
Parent topic: Connect (Set Location) Access


Primary Server Configuration

Restriction: This topic applies to Windows environments only.

To configure a server as a primary XDB Server, you must update the system tables. In the examples, the primary XDB Server is xdbserve.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. On any client logged in to the primary XDB Server, start SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. From an SQL Window set the current location to the SYSTEM location:
    SET LOCATION TO system;
  4. Issue the following SQL command to insert information about a remote server into the SYSIBM.SYSLUNAMES table:
    INSERT INTO sysibm.syslunames
    VALUES ("remote-server","","","","","");

    where remote-server is the name of a remote XDB Server to be accessed. Several of the other columns in the SYSIBM.SYSLUNAMES table are used for security mapping. See the chapter Multiserver Security for more information on using these values.

    In the examples , the SQL command:

    INSERT INTO SYSIBM.SYSLUNAMES
    VALUES ("sales","","","","","");

    would have been issued on the XDB Server XDBSERVE.

  5. Issue the following SQL command to insert information about a remote location into the SYSIBM.SYSLOCATIONS table:
    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES ("remote-location","X",
            "remote-server","link-type");

    where:

    remote-location | is the name of the remote location to be accessed (unique among all locations on all servers that are used in distributed processing).
    X | indicates it is an XDB Server.
    remote-server | is the name of the remote server that controls the remote location.
    link-type | is the communication protocol used to connect to the remote server.

    In the examples used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES ("orders","X","sales","B");

    would have been issued on the XDB Server XDBSERVE.

  6. Repeat Steps 4 and 5 for each remote XDB Server and location that will be accessed from this primary server.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
Parent topic: Configuring Server-to-Server Connectivity


Remote Server Configuration

Restriction: This topic applies to Windows environments only.

The remote XDB Server must be configured and privileges must be granted. In the examples, the remote XDB Server is sales.

If security is on, clients must have privileges on the tables they wish to access on the remote server. Be sure to grant the appropriate privileges to each client on the remote server.

AuthIDs are created using the SQL Wizard Admin menu (Windows) or the CREATE USER command in Interactive SQL (UNIX). Privileges are granted using the SQL GRANT command via the SQL Wizard (Windows) or Interactive SQL (UNIX). See the chapter Security and Authority for more information on AuthIDs and privileges.

AuthID mapping can make this task much easier in a large distributed environment. See the chapter Multiserver Security for more information about AuthID mapping.

Parent topic: Configuring Server-to-Server Connectivity


Configuring Server Access

Restriction: This topic applies to Windows environments only.

Once you have configured the primary and remote servers, use the following procedure to configure access:

  1. From the Client Options dialog box, Connect tab, configure the following:
    Control Group | Control Name | Value
    Network Info | Server Name | A new server name
    Communication Protocol | TCP/IP
    IP Address | The remote machine name or its IP address
    TCP Port | Port to use on the remote machine (8898 is the default)
    Connect To | Locations | A unique name for the remote location, different from all local location names
  2. Click OK.
  3. Using SQL Wizard, attempt to log onto the remote server. If you are not successful, verify that your settings are correct. To do this:
    1. At a command prompt, use the Windows ping command to verify that the machine name or IP address in the IP Address field is correct and can be resolved. If this doesn't work, verify with IT that the machine name or IP address can be resolved and the destination is reachable.
    2. At a command prompt, use the Windows telnet command to verify that you can establish a connection to the server (telnet machine port). If a connection is refused:
      • Verify that the remote server is running
      • Using the IPCONFIG on the remote machine, verify that the machine name/IP Address is valid
      • Using the NETSTAT command, verify that the server is running and listening on the proper port
      • Ensure that your firewall software isn't preventing the connection
  4. From the Connect tab on the Options dialog box, set the Server Name back to your local server; then click OK.
  5. From SQL Wizard, enter the following INSERT statements to add the server location to the local servers SYSTEM location:

    INSERT INTO SYSTEM.SYSIBM.SYSLUNAMES (LUNAME) VALUES (" ServerName ");

    INSERT INTO SYSTEM.SYSIBM.SYSLOCATIONS VALUES (" LocationName ","X", " ServerName ","T");

    where ServerName is the server name you specified in step 1, and LocationName is the name of the remote location you specified in step 1.

  6. Shut down and restart the local server to ensure that the local server picks up the new location.
  7. Start SQLWizard on the local machine.

The new location should now appear on the list of locations in the Catalog Browser. The remote location should be accessible through the SQLWizard Catalog Browser and available for any program or utility connecting to the local server.

Parent topic: Configuring Server-to-Server Connectivity


Multiserver Security

Restriction: This topic applies to Windows environments only.

In a distributed environment with server-to-server connectivity, there will generally be more than two servers and a large number of users. There can be duplicate AuthIDs on different servers, such as a Bob in development and a Bob in sales.

Different servers can have different levels of privileges and table access. For example, on the XDB Server develop all users might be allowed access to all tables in the products location. On the XDB Server sales, access to the orders location might be restricted to a particular group or AuthID.

The XDB Server provides several methods of security and administration control. Outbound mapping allows you to translate an AuthID (username) and password before a request is sent to a remote XDB Server, providing another method of controlling communications with other XDB Servers. Inbound mapping translates an AuthID on a remote server after login, providing another method of controlling access on an XDB Server.

Trusting allows you to bypass verifying a name and password with the system catalog tables on the remote server, eliminating one step in the login and verification process. Global security allows you to set up one server to handle all security, eliminating redundancy and reducing the possibility of erroneous entries in the system catalog tables.

In a distributed environment with multiple administrators, users and servers, cooperation among administrators is imperative. Coordination can eliminate duplicate location names and AuthIDs. Rejected logins and lack of privileges can also be avoided.

Throughout this documentation, the term primary server is used to refer to the XDB Server to which the user is connected. The term remote server is the XDB Server elsewhere on the LAN that controls the location the user wishes to access.

Note:

Be sure to read this Multiserver Security topic carefully before attempting to map AuthIDs or passwords. When using multiple servers, mappings and trusting, it is very easy to miss one step and confuse everything.

  • Outbound Mapping
  • Inbound Mapping
  • Trusting
  • Global Security
  • Outbound, Inbound and Trusting Used Together
Parent topic: SQL Option Server Administration Guide


Outbound Mapping

Restriction: This topic applies to Windows environments only.

Outbound mapping allows you to translate an AuthID and passwords before a request is sent to a remote XDB Server. A request can be sent that either references a remote location controlled by another XDB Server (using a three-part name) or the remote XDB Server itself (using CONNECT). The values in the system catalog table SYSIBM.SYSLUNAMES indicate that requests going to the remote XDB Server should be translated. Based on the values in SYSIBM.SYSUSERNAMES, the AuthID is mapped and the request is sent to the remote server as if it came from the newly mapped AuthID.

Mapping AuthIDs before they leave an XDB Server can be useful when a particular remote XDB Server is configured to accept requests from only one or two AuthIDs. This allows you to translate all AuthIDs going to that XDB Server into valid AuthIDs for a remote XDB Server. Outbound mapping can also be used to eliminate duplicate AuthIDs at different XDB Servers. Any potential duplicate AuthID (or all AuthIDs) can be mapped to different AuthIDs before requests are sent to remote XDB Servers.

While remote XDB Servers can be configured to allow all users access from your XDB Server, outbound mapping keeps the administration tasks on one XDB Server. In a distributed environment with many XDB Servers, it can quickly become confusing to have to track the current valid AuthIDs for all other XDB Servers in order to maintain your own system tables. Outbound mapping allows you to control how queries appear when leaving a particular XDB Server.

  • Privileges
  • Examples
  • System Tables
  • Sample System Tables
  • Setting up Outbound Mapping
Parent topic: Multiserver Security


Privileges

Restriction: This topic applies to Windows environments only.

Control privileges at each individual server. Each server controls its own access security. When using outbound mapping, make sure that the new AuthID given is a valid AuthID at the remote XDB Server to which the request is being sent. The new AuthID must be a valid AuthID, created by the SQL Wizard Admin menu (Windows) or the CREATE USER command in Interactive SQL (UNIX) and listed in the SYSXDB.SYSACFUSERS table. If inbound mapping is not being used on the remote XDB Server, the AuthID sent must also have the appropriate privileges to access data.

Parent topic: Outbound Mapping


Examples

Restriction: This topic applies to Windows environments only.

Bob is logged in to the XDB Server develop. He issues a SELECT command referencing orders.eastern.may. This request is received by the XDB Server develop. Develop determines that the orders location is controlled by the XDB Server sales. Develop checks its system catalog table SYSIBM.SYSLUNAMES, which indicates that any request going to sales is subject to outbound mapping.

Develop then checks the system table SYSIBM.SYSUSERNAMES, which indicates the AuthID of Bob should be translated to devbob for all requests to the XDB Server sales. The SELECT request referencing ORDERS.EASTERN.MAY is sent to sales with an AuthID of devbob.

The SELECT request is then received at the XDB Server sales. If inbound mapping is not being used, sales verifies that the AuthID devbob is a valid AuthID in the SYSXDB.SYSACFUSERS table. The SELECT query is processed, privileges are checked and a result is returned to Bob via the XDB Server develop.

As another example, consider that any user accessing develop issues a request referencing data on the XDB Server sales. According to the system table SYSIBM.SYSUSERNAMES on develop, the AuthID on all outbound requests to sales are mapped to developr.

In this case, the system administrator of the XDB Server sales needs to maintain only one account, developr, for users from the XDB Server develop. As users are added and removed from develop, the system administrator of sales does not need to modify accounts or system tables to reflect these changes. No matter what the AuthID on develop, it will be mapped to developr before it is sent to sales.

Parent topic: Outbound Mapping


System Tables

Restriction: This topic applies to Windows environments only.

Outbound mapping requires you to update the SYSIBM.SYSLUNAMES and SYSIBM.SYSUSERNAMES tables with information for mapping users on the primary XDB Server that will be performing outbound mapping. This can be done through the SQL Wizard (Windows) or Interactive SQL (UNIX).

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use outbound mapping. All other columns can have NULL values. Other columns in SYSIBM.SYSLUNAMES are used for trusting. See the section Trusting for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSUSERNAMES
Parent topic: Outbound Mapping


SYSIBM.SYSLUNAMES

Restriction: This topic applies to Windows environments only.

The columns in this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used.
USERNAMES required | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSUSERNAMES

Restriction: This topic applies to Windows environments only.

The columns in the following table contain information used by the XDB Server for processing requests to other XDB Servers using server-to-server connectivity or to DB2 locations through XDB Link.

Name | Type | Len | Description
TYPE required | CHAR | 1 | Indicates how the row is to be used:
 |  |  | I | For inbound IDs.
 |  |  | O | For outbound IDs.
AUTHID required | CHAR | 8 | An authorization ID that is allowed and perhaps translated. If blank, any AuthID with the corresponding LUNAME is translated in the same manner.
LUNAME required | CHAR | 8 | The name of the XDB Server, if using server-to-server connectivity, or LUNAME, if using XDB Link, for which the AuthID is to be translated. If blank, the corresponding AuthID is translated the same for all XDB Servers.
NEWAUTHID required | CHAR | 8 | The translated value of the AuthID. If blank, the translated AuthID and password are the same as the original AuthID.
PASSWORD required | CHAR | 8 | Password for an outbound request.
Parent topic: System Tables


Sample System Tables

Restriction: This topic applies to Windows environments only.

The following table shows values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server, develop, to implement the examples discussed in this topic for outbound mapping (without trusting).

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
sales |  |  |  |  | O

This table indicates that all requests sent to the XDB Server sales are subject to outbound mapping.

The following table shows the values needed in the system table SYSIBM. SYSUSERNAMES on the XDB Server develop to implement the outbound mapping examples used in this topic. This table also shows several other valid records, explained after the table. Please note that the NO. column is not actually part of the table, and is only displayed for reference.

NO. | TYPE | AUTHID | LUNAME | NEWAUTHID | PASSWORD
1 | O | bob | sales | devbob | devbpass
2 | O | debbie | sales | developr | devpass
3 | O | bruce | sales | developr | devpass
4 | O | eric | sales |  | devepass
5 | O | david |  | devdavid | devdpass
6 | O | arlene |  |  | arlpass
7 | O |  | sales | developr | devpass

Row 1 maps Bob to devbob for all requests sent to sales. This is the configuration used in the examples on outbound mapping.

Rows 2 and 3 map Debbie and Bruce to developr for all requests sent to sales. Here, developr is assumed to be a group of people.

Row 4 does not map Eric when sending requests to sales. Eric is assumed to be an AuthID on SALES. If Eric tried to go to SALES, the Row 4 mapping would take precedence over the Row 7 mapping because it mentions a specific AuthID.

Row 5 maps David to devdavid anytime outbound requests are sent to any server.

Row 6 does not map Arlene when sending request to any remote servers. Arlene is assumed to be an AuthID on all other servers.

Row 7 maps all AuthIDs to developr when sending requests to sales. The mappings of rows 1 through 6 take precedence over Row 7 mapping because they mention specific AuthIDs.

Parent topic: Outbound Mapping


Setting up Outbound Mapping

Restriction: This topic applies to Windows environments only.

In order to use outbound mapping, you must update system tables on the primary XDB Server which will perform the outbound mapping. On the remote XDB Server, you must set up the appropriate AuthIDs, mappings and privileges.

The instructions in each topic discuss outbound mapping on one XDB Server. If you wish to have a fully distributed environment, complete the Primary Server instructions on each XDB Server that will perform outbound mapping. Complete the Remote Server instructions on each XDB Server which will accept mapped AuthIDs.

All of the following instructions assume that security is turned on (through the XDB Server Configuration Utility) for both the Primary and Remote XDB Servers.

The instructions in this topic are written as if you have already set up server-to-server connectivity before setting up outbound mapping. These instructions also assume you will not be setting up inbound mapping on the remote server.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Outbound Mapping


Primary Server Configuration

Restriction: This topic applies to Windows environments only.

These steps must be performed on the XDB Server that will be performing outbound mapping. In the examples, the XDB Server develop is performing outbound mapping.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. On any client logged in to the primary XDB Server, start SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. From an SQL Window, set the current location to the system location:
    SET LOCATION TO system;
  4. Issue the following SQL command to update information in the SYSIBM.SYSLUNAMES table about server-to-server connectivity and outbound mapping.
    UPDATE sysibm.syslunames SET username = "O"
    WHERE luname = "remote-server";

    where:

    O | indicates that requests going to the remote XDB Server will be subject to outbound mapping.
    remote-server | is the name of a remote XDB Server for which AuthIDs will be mapped.

    Other columns in the SYSIBM.SYSLUNAMES table are used for trusting servers. See the section Trusting for more information on using these values.

    In the examples on outbound mapping used in this topic, the SQL command:

    UPDATE sysibm.syslunames SET username = "O"
    WHERE luname = "sales";

    would have been issued on the XDB Server develop.

  5. Issue the following SQL command to insert information into the SYSIBM.SYSUSERNAMES table about AuthIDs that will be subject to outbound mapping.
    INSERT INTO SYSIBM.SYSUSERNAMES
    VALUES("O","authid","servername",
           "newauthid","password");

    where:

    O | indicates outbound mapping will be performed.
    authid | is the name of the AuthID to be translated from.
    servername | is the name of the server for which this AuthID will be translated.
    newauthid | is the new AuthID that will be given.
    password | is the password to be used with the new AuthID. Enter the password as regular ASCII text. It will be encrypted by the engine before being stored. Subsequent displays of PASSWORD column data show the encrypted password.

    In the examples on outbound mapping used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSUSERNAMES
    VALUES("O","bob","sales", "devbob","devbpass");

    would have been issued on the XDB Server develop.

  6. Repeat Step 4 for each Server for which outbound requests will be mapped. Repeat Step 5 for each AuthID that will be subject to outbound mapping.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
Parent topic: Setting up Outbound Mapping


Remote Server Configuration

Restriction: This topic applies to Windows environments only.

The remote XDB Server that will receive the translated ID must be configured to accept the new AuthID and database privileges must be given. In the examples, the remote XDB Server is sales.

Make sure the translated AuthID is a valid AuthID in SYSXDB.SYSACFUSERS. Use the SQL Wizard (Windows) or Interactive SQL Utility (UNIX) to add users. In the examples used earlier, the AuthID of devbob would have to be a valid AuthID on the XDB Server sales.

If inbound mapping will not be used on the remote server, grant the appropriate privileges to the translated AuthID using the SQL GRANT command. In the examples used earlier, the AuthID of devbob would have to be given privileges on the XDB Server sales.

If inbound mapping will be used, make sure there is a record in the SYSIBM.SYSLUNAMES on the remote server that references the server from which the request comes. Also, make sure there is a record in SYSIBM.SYSUSERNAMES on the remote server that references the translated AuthID. See the section Outbound, Inbound and Trusting Used Together for more information.

Parent topic: Setting up Outbound Mapping


Inbound Mapping

Restriction: This topic applies to Windows environments only.

Inbound mapping means that an AuthID (username) is mapped to a different value after logging in at an XDB Server. A request is received at either the remote server that references a location controlled by the remote server (using three-part names) or the server itself (using CONNECT).

The values in the SYSIBM.SYSLUNAME table indicate that requests coming from the primary XDB Server should be translated. If a password is present, the AuthID and password are checked against SYSXDB.SYSACFUSERS. See the section Trusting for more about password checking. Then, the SYSIBM.SYSUSERNAMES table is checked and the AuthID is mapped. Finally, the request is processed with the AuthID obtained by inbound mapping.

Mapping AuthIDs on an XDB Server that will accept requests from other XDB Servers allows you to have more control over which AuthIDs have access. If inbound mapping is not used, you must update the SYSXDB.SYSACFUSERS table with all AuthIDs that will have access. These users must also be given the appropriate privileges. In a distributed environment, this can mean keeping track of hundreds of individual AuthIDs. You can map incoming AuthIDs into a manageable number of AuthIDs. Then only the mapped AuthIDs must be given privileges to access data objects.

  • Privileges
  • Examples
  • System Tables
  • Sample System Tables
  • Setting Up Inbound Mapping
Parent topic: Multiserver Security


Privileges

Restriction: This topic applies to Windows environments only.

Control privileges at each individual server. Each server controls its own access security. When using inbound mapping, make sure that the new AuthID has the appropriate privileges to access data.

Parent topic: Inbound Mapping


Examples

Restriction: This topic applies to Windows environments only.

Debbie is logged in to the XDB Server develop. She issues a SELECT command referencing orders.eastern.may. This request is received by the XDB Server develop. Based on the system tables on develop, outbound mapping might occur. Assuming that outbound mapping does not occur, the SELECT request referencing orders.eastern.may is sent to sales with an AuthID of debbie.

The SELECT request is then received at the XDB Server sales. After the presence of a password is checked (see the section Trusting), the SYSIBM.SYSLUNAMES table is checked and indicates requests from the Server develop are subject to inbound mapping. The AuthID of debbie and the accompanying password are checked against the SYSXDB.SYSACFUSERS table.

Next, the values in SYSIBM.SYSUSERNAMES indicate that any request from the XDB Server develop should be mapped to an AuthID of developr. Finally, the SELECT command referencing orders.eastern.may is processed with an AuthID of developr. Privileges are checked and a result is returned to debbie via the XDB Server develop.

Parent topic: Inbound Mapping


System Tables

Restriction: This topic applies to Windows environments only.

Inbound mapping requires you to update the SYSIBM.SYSLUNAMES and SYSIBM.SYSUSERNAMES tables with information for mapping users on the remote XDB Server that will be performing inbound mapping. This can be done through SQL commands in the SQL Wizard (Windows) or Interactive SQL (UNIX).

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use inbound mapping. All other columns can have NULL values. Other columns in SYSIBM.SYSLUNAMES are used for trusting. See the section Trusting for more information on these values.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSUSERNAMES
Parent topic: Inbound Mapping


SYSIBM.SYSLUNAMES

Restriction: This topic applies to Windows environments only.

The columns of this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used.
USERNAMES required | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


SYSIBM.SYSUSERNAMES

Restriction: This topic applies to Windows environments only.

The columns in this table contain user information used by the XDB server for processing requests to other XDB Servers using server-to-server connectivity or to DB2 locations through XDB Link.

Name | Type | Len | Description
TYPE required | CHAR | 1 | Indicates how the row is to be used:
 |  |  | I | For inbound IDs.
 |  |  | O | For outbound IDs.
AUTHID required | CHAR | 8 | An authorization ID that is allowed and perhaps translated. If blank, any AuthID with the corresponding LUNAME is translated in the same manner.
LUNAME required | CHAR | 8 | The name of the XDB Server, if using server-to-server connectivity, or LUNAME, if using XDB Link, for which the AuthID is to be translated. If blank, the corresponding AuthID is translated the same for all XDB Servers.
NEWAUTHID required | CHAR | 8 | The translated value of the AuthID. If blank, the translated AuthID and password are the same as the original AuthID.
PASSWORD | CHAR | 8 | Password for an outbound request.
Parent topic: System Tables


Sample System Tables

Restriction: This topic applies to Windows environments only.

The following table shows values needed in the system table SYSIBM.SYSLUNAMES on the remote XDB Server sales to implement the examples discussed in this topic for inbound mapping (without trusting).

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
develop |  |  |  |  | I

This table indicates that all requests received from the XDB Server develop are subject to inbound mapping.

The following table shows the values needed in the system table SYSIBM. SYSUSERNAMES on the XDB Server sales to implement the inbound mapping examples used in this topic. This table also shows several other valid records, explained after the table. Please note that the NO. column is not actually part of the table, and is only displayed for reference.

NO. | TYPE | AUTHID | LUNAME | NEWAUTHID | PASSWORD
1 | i | debbie | develop | developr |
2 | i | arlene | develop | nora |
3 | i |  | develop | developr |
4 | i | harold |  | harry |

Row 1 maps Debbie to developr for all requests received from the XDB Server develop. This is the configuration used in the examples on inbound mapping.

Row 2 maps arlene to nora for all requests from the XDB Server develop.

Row 3 maps any AuthID to developr for request received from the XDB Server develop.

Row 4 maps harold to harry for requests received from any XDB Server.

In this example, rows 1, 2 and 4 take precedence over row 3 because they mention specific AuthIDs.

Parent topic: Inbound Mapping


Setting Up Inbound Mapping

Restriction: This topic applies to Windows environments only.

In order to use inbound mapping, you must update system tables and privileges on each remote XDB Server that will perform the inbound mapping. If server trusting is not being used, nothing needs to be done on the servers sending requests.

The instructions in each topic discuss inbound mapping on one XDB Server. If you wish to have a fully distributed environment, complete the Remote Server instructions on each XDB Server that will perform inbound mapping.

All of the following instructions assume that security is turned on (through the XDB Server Configuration Utility) for both the primary and remote XDB Servers.

The instructions in this topic assume you have already setup server-to-server connectivity before setting up inbound mapping. These instructions also assume you will not be setting up outbound mapping on the primary server.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Inbound Mapping


Primary Server Configuration

Restriction: This topic applies to Windows environments only.

On the primary XDB Server, simply setup server-to-server connectivity so that requests can reach the remote server. No additional configuration is needed on the primary XDB Server to use inbound mapping. However, if you wish to use inbound and outbound mapping together, consult the topic on Outbound, Inbound and Trusting Used Together for more information.

Parent topic: Setting Up Inbound Mapping


Remote Server Configuration

Restriction: This topic applies to Windows environments only.

These steps must be performed on the XDB Server that will be performing inbound mapping. In the examples, the XDB Server sales is performing inbound mapping.

To update the system tables:

Note:

When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.

  1. On any client logged in to the remote XDB Server, start the SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
  2. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  3. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  4. Issue the following SQL command to update information in the SYSIBM.SYSLUNAMES table about server-to-server connectivity and inbound mapping.
    UPDATE sysibm.syslunames SET username = "I"
    WHERE luname = "servername";

    where:

    I | indicates inbound mapping will be performed.
    servername | is the name of another XDB Server from which AuthIDs will be mapped.

    Other columns in the SYSIBM.SYSLUNAMES table are used for trusting servers.

    In the examples on inbound mapping used in this topic, the SQL command:

    UPDATE sysibm.syslunames SET username = "I"
    WHERE luname = "develop";

    would have been issued on the XDB Server SALES.

  5. Issue the following SQL command to insert information into the SYSIBM.SYSUSERNAMES table about AuthIDs that will be subject to inbound mapping.
    INSERT INTO SYSIBM.SYSUSERNAMES
    VALUES("I","authid","servername",
           "newauthid","");

    where:

    I | indicates inbound mapping will be performed.
    authid | is the name of the AuthID to be translated from.
    servername | is the name of the server from which the AuthID to be translated will originate.
    newauthid | is the new AuthID that will be given.

    In the examples on inbound mapping used in this topic, the SQL command:

    INSERT INTO sysibm.sysusernames
    VALUES("I","debbie","develop","developr","");

    would have been issued on the XDB Server sales.

  6. Repeat Step 4 for each server from which inbound requests will be mapped. Repeat Step 5 for each AuthID that will be subject to inbound mapping.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit the SQL Wizard (Windows) or Interactive SQL Utility (UNIX).

Use the SQL GRANT command to grant the appropriate privileges to the new AuthIDs. In the examples on inbound mapping in this topic, the AuthID developr would have to be granted SELECT privileges on the table MAY in the location orders.

Parent topic: Setting Up Inbound Mapping


Trusting

Restriction: This topic applies to Windows environments only.

Without trusting, any time a login request is received by an XDB Server, the AuthID and password must be verified. Trusting (available only in conjunction with inbound mapping) allows an XDB Server to bypass verifying the password with SYSXDB.SYSACFUSERS each time a request is received via server-to-server connectivity. The remote server receives a request that references either a location controlled by the remote server (using three-part names) or the server itself (using CONNECT). If no password is sent to the remote XDB Server, SYSIBM.SYSLUNAMES is checked to ensure that the request from the primary server is already verified and a password is not needed.

The SYSIBM.SYSLUNAMES table is also checked to determine if inbound mapping is being used. If inbound mapping is being used the presence of a password is again checked. If a password was sent, the AuthID and password are verified with SYSXDB.SYSACFUSERS. If no password is included, then the AuthID is not verified because the information from that primary server can be trusted. Then, SYSIBM.SYSUSERNAMES is checked and the AuthID is mapped. Finally, privileges are checked and the query is processed.

If inbound mapping is not being used, the AuthID and password are verified with SYSXDB.SYSACFUSERS. Privileges are then checked and the query is processed.

Trusting can only been performed in conjunction with inbound mapping on a remote server. The remote server will be changing any AuthIDs received from a particular server. The AuthIDs to be mapped can be maintained in SYSXDB.SYSUSERNAMES.

  • Example
  • System Tables
  • Sample System Tables
  • Setting Up Trusting
Parent topic: Multiserver Security


Example

Restriction: This topic applies to Windows environments only.

Bruce is logged in to the XDB Server develop. He issues a SELECT command referencing orders.eastern.may. This request is received by the XDB Server develop. Based on the system tables on develop, outbound mapping might occur. Assuming that outbound mapping does not occur, the SELECT request referencing orders.eastern.may is sent to sales with an AuthID of bruce and no password.

The SELECT request is then received at the XDB Server sales with an AuthID of bruce and no password. Since no password is present, SYSIBM.SYSLUNAMES is checked on sales. The values in this table indicate that all requests coming from the XDB Server develop are to be trusted. The values in SYSIBM.SYSLUNAMES also indicate that requests from the XDB Server develop are subject to inbound mapping.

Since no password accompanied the request, SYSIBM.SYSUSERNAMES is checked next. The values in this table indicate that any request from the XDB Server develop should be mapped to an AuthID of developr. Finally, the SELECT command referencing orders.eastern.may is processed with an AuthID of developr. Privileges are checked and a result is returned to bruce via the XDB Server develop.

Parent topic: Trusting


System Tables

Restriction: This topic applies to Windows environments only.

Trusting requires you to update the SYSIBM.SYSLUNAMES table on the remote XDB Server that will be receiving requests. Updates can be performed using the SQL Wizard (Windows) or Interactive SQL (UNIX).

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use trusting.

  • SYSIBM.SYSLUNAMES
Parent topic: Trusting


SYSIBM.SYSLUNAMES

Restriction: This topic applies to Windows environments only.

The columns in this table contain information on LUNAMES used for server-to-server or Link connectivity.

Name | Type | Len | Description
LUNAME required | CHAR | 8 | Name of the XDB Server, if using server-to-server connectivity. Name of the LU for one or more accessible DB2 systems if using XDB Link. Blank indicates the current XDB Server.
SYSMODENAME | CHAR | 8 | Mode used to establish intersystem conversations.
USERSECURITY required | CHAR | 1 | Acceptance option for a remote attach:
 |  |  | C | "Conversation." A request is checked by the internal security system and must include a password.
 |  |  | A | "Already Verified." A request does not need a password, although a password is checked if it is sent. A is the default.
 |  |  | Any character that is not C is treated as an A.
ENCRYPTPSWDS | CHAR | 1 | Included for DB2 compatibility only. Tells whether passwords for DB2 LUs are encrypted:
 |  |  | Y | Passwords are encrypted.
 |  |  | N | Passwords are not encrypted.
 |  |  | The XDB Server always uses encrypted passwords, even if set to N.
MODESELECT | CHAR | 1 | Not used.
USERNAMES required | CHAR | 1 | Whether an ID accompanying a remote attach request is subject to translation.
 |  |  | I | Inbound ID, from the corresponding LUNAME, is subject to translation.
 |  |  | O | Outbound ID, sent to the corresponding LUNAME, is subject to translation.
 |  |  | B | Both inbound and outbound IDs are subject to translation.
 |  |  | blank | No translation is done for either inbound or outbound IDs.
Parent topic: System Tables


Sample System Tables

Restriction: This topic applies to Windows environments only.

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the remote XDB Server sales to implement the trusting examples (without outbound mapping) used in this topic.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
develop |  | A |  |  | I

This table shows that sales should regard all requests from the XDB Server develop as coming from users who are already verified.

The values needed in the system table SYSIBM.SYSUSERNAMES to implement trusting are the same as those required for inbound mapping. The following table shows the values needed to implement the trusting example used in this topic. This table also shows other valid records for trusting, explained after the table.

TYPE | AUTHID | LUNAME | NEWAUTHID | PASSWORD
I | bruce | develop | developr |
I | david | develop |  |
I |  | develop |  |
I | arlene |  |  |

Row 1 maps bruce to developr for all requests received from the XDB Server develop. This is the configuration used in the examples on trusting.

Row 2 does not map david when requests are received from develop.

Row 3 does not map any AuthIDs from develop.

Row 4 does not map arlene when requests are received from any XDB Server.

In this example, rows 1, 2 and 4 take precedence over row 3 because they mention specific AuthIDs.

Parent topic: Trusting


Setting Up Trusting

Restriction: This topic applies to Windows environments only.

In order to use trusting you must update system tables on the remote server which will trust the requests. On the remote XDB Server, you must also set up the appropriate AuthIDs, mappings and privileges.

The instructions in each topic discuss trusting between two XDB Servers. If you wish to have a fully distributed environment, complete the primary XDB Server instructions on each XDB Server from which request will be trusted. Complete the remote XDB Server instructions on each XDB Server which will trust requests.

All of the following instructions assume that security is turned on (through the XDB Server Configuration Utility) for both the primary and remote XDB Servers.

The instructions in this topic are written as if you have already set up server-to-server connectivity and inbound mapping before setting up trusting, and are not using outbound mapping.

  • Primary Server Configuration
  • Remote Server Configuration
Parent topic: Trusting


Primary Server Configuration

Restriction: This topic applies to Windows environments only.

On the primary XDB Server, set up server-to-server connectivity so that requests can reach the remote server. No additional configuration on the primary XDB server is needed to use trusting. To use trusting in conjunction with outbound mapping, see the section Outbound, Inbound and Trusting Used Together for more information.

Parent topic: Setting Up Trusting


Remote Server Configuration

Restriction: This topic applies to Windows environments only.

You must perform these steps on the XDB Server that will trust requests and perform inbound mapping. In the examples, the XDB Server sales is trusting and performing inbound mapping.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. On any client logged in to the remote XDB Server, start the SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
  2. Once inside the XDB Server Configuration Utility, press F5 to access the Multiuser Configuration screen.
  3. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  4. Issue the following SQL command to update information in the SYSIBM.SYSLUNAMES table about server-to-server connectivity and inbound mapping and trusting.
    UPDATE sysibm.syslunames SET usersecurity = "A"
    WHERE luname = "servername" AND usernames = "I";

    where:

    A | indicates that requests from the XDB Server should be trusted.
    servername | is the name of another XDB Server from which AuthIDs will be mapped.
    I | indicates inbound mapping will be performed.

    In the examples on inbound mapping used in this topic, the SQL command:

    UPDATE sysibm.syslunames SET usersecurity = "A"
    WHERE luname = "develop" AND usernames = "I";

    would have been issued on the XDB Server sales.

  5. Issue the following SQL command to insert information into the SYSIBM.SYSUSERNAMES table about AuthIDs that will be subject to inbound mapping.
    INSERT INTO sysibm.sysusernames
    VALUES("I","authid","servername",
           "newauthid","");

    where:

    I | indicates inbound mapping will be performed.
    authid | is the name of the AuthID to be translated from.
    servername | is the name of the server from which the AuthID to be translated will originate.
    newauthid | is the new AuthID that will be given.

    In the examples on inbound mapping used in this topic, the SQL command:

    INSERT INTO sysibm.sysusernames
    VALUES("I","bruce","develop","developr","");

    would have been issued on the XDB Server sales.

  6. Repeat Step 4 for each server that will be subject to inbound mapping. Repeat Step 5 for each AuthID that will be subject to inbound mapping.
  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit the SQL Wizard (Windows) or Interactive SQL Utility (UNIX).

Use the SQL GRANT command to grant the appropriate privileges to the new AuthIDs. In the examples on inbound mapping and trusting used in this topic, the AuthID developr would have to be granted SELECT privileges on the table may in the location orders.

Parent topic: Setting Up Trusting


Global Security

Restriction: This topic applies to Windows environments only.

The XDB Server allows you to set up one location that will validate access security for all XDB Servers on a LAN. This eliminates duplicate AuthIDs and passwords in a distributed environment.

Using global security, each XDB Server in a distributed environment is configured to point to one location as the security server. This is done through the XDB Server Configuration Utility and by inserting values into the system catalog tables on each XDB Server.

Whenever a user attempts to login to any XDB Server using global security, the AuthID and password are passed to the global security location for verification. Global security extends server-to-server connectivity by allowing all XDB servers to use just one location for verifying passwords.

Note that a user must have a valid AuthID on each XDB Server in SYSXDB.SYSACFUSERS, with valid access to data, on every XDB Server that will be accessed. Global security only verifies AuthIDs and passwords.

The information in the global security system catalog tables can also be used to map AuthIDs and passwords. Be particularly careful when setting up this sort of scheme.

Multiple global security locations can be set up in a distributed environment. This allows you to have multiple security schemes for different XDB Servers. It also allows you to set up a redundant global security system to be used in case of hardware failure on your original global security server.

  • Example
  • System Tables
  • Setting Up Global Security
Parent topic: Multiserver Security


Example

Restriction: This topic applies to Windows environments only.

The user Bob tries to login to the XDB Server develop, as shown in the following figure. Develop checks the server configuration settings (in SRVCONFG.XDB) and determines that it is using global security, and that the global security location is on the XDB Server XDBSERVE. The AuthID and password are sent to xdbserve for verification.

On XDBSERVE, the AuthID and password are verified against SYSXDB.SYSACFUSERS in the global security location. Verification is then returned from the XDB Server XDBSERVE and Bob is logged in to develop. Secondary IDs and privileges are then assigned.

Parent topic: Global Security


System Tables

Restriction: This topic applies to Windows environments only.

You must insert data into two XDB system tables, SYSIBM.SYSLUNAMES and SYSIBM.SYSLOCATIONS on the primary XDB Server in order to use global security. The only system tables that must be modified on the global security server are modified by using the SQL Wizard (Windows) or Interactive SQL (UNIX). Updates can be made to the tables on the primary XDB Server using the SQL Wizard (Windows) or Interactive SQL (UNIX).

Note: When updating system tables, do not change or delete any records that appear blank. These records contain a space character in certain columns and are required to define the locations controlled by your local machine.

You must insert values into columns labeled "required" in order to use global security.

  • SYSIBM.SYSLUNAMES
  • SYSIBM.SYSLOCATIONS
  • Sample System Tables
Parent topic: Global Security


SYSIBM.SYSLOCATIONS

Restriction: This topic applies to Windows environments only.

The columns in this table contain information about all locations that are accessible for RUW and DUW processing, including local locations in SYSXDB.SYSLOCALS plus remote locations accessible using server-to-server connectivity or XDB Link.

Name | Type | Len | Description
LOCATION required | CHAR | 16 | Name of the location.
LOCTYPE required | CHAR | 1 | Indicates the location type:
 |  |  | X | XDB
 |  |  | R | RPC
 |  |  | C | CICS
 |  |  | D | DRDA
LINKNAME required | CHAR | 8 | Name of the XDB Server which controls the location, if using server-to-server connectivity. LUNAME for the accessible system if using XDB Link.
LINKATTR required | VARCHAR | 64 | Type of protocol used to connect to the XDB Server when using server-to-server connectivity:
 |  |  | S | SPX
 |  |  | B | NetBIOS
 |  |  | N | Named Pipes
 |  |  | T | TCP/IP (Set the hostname and IP address in the XDBNET.INI file.)
 |  |  | or The name of the mainframe program with which XDB Link will communicate if using XDB Link.
Parent topic: System Tables


Sample System Tables

Restriction: This topic applies to Windows environments only.

The following table shows the values needed in the system table SYSIBM.SYSLUNAMES on the primary XDB Server develop to implement the examples discussed in this topic for global security.

LUNAME | SYSMODE-NAME | USER-SECURITY | ENCRYPT-PSWDS | MODE-SELECT | USER-NAMES
xdbserve |  |  |  |  |

This table indicates that the XDB Server xdbserve can be accessed.

The following table shows the values needed in SYSIBM.SYSLOCATIONS on the XDB Server develop to implement the examples discussed above for global security.

LOCATION | LOCTYPE | LINKNAME | LINKATTR
sysglobal | X | xdbserve | B

This table indicates that the sysglobal location is an XDB location controlled by a remote XDB Server xdbserve and can be reached via the NetBIOS protocol.

Parent topic: System Tables


Setting Up Global Security

Restriction: This topic applies to Windows environments only.

In order to set up global security, you must configure both the primary XDB Server and the global security XDB Server. The primary XDB Server is the XDB Server which clients will log into. The global security server will verify AuthIDs and passwords. The instructions in this topic discuss one primary server and one global security server.

If you wish to have a fully distributed environment, complete the Primary Server Configuration instructions (page 8-37) for each XDB Server that you wish to be a primary XDB Server. Complete the Global Security Configuration instructions (page 8-41) for each XDB Server you wish to be a global security XDB Server.

Note: We strongly recommend that you plan your global security scheme before implementing it, especially if you will be allowing outbound mapping, inbound mapping and trusting between servers using global security. Be sure to consider items that are assigned on a per server basis (groups and governor privileges) and those that are assigned on a per location basis (database and table privileges).

Because global security is an extension of server-to-server security, you must register the global security server and location as you would any other server or location. If you have already configured other locations on your global security server, you might need to update values in the system tables rather than insert new ones. See the chapter Server-to-Server Connectivity for detailed instructions.

  • Primary Server Configuration
  • Global Security Server Configuration
Parent topic: Global Security


Primary Server Configuration

Restriction: This topic applies to Windows environments only.

To configure the primary server for global security, you must update the system tables before you configure the server. You must follow these procedures in the order in which they appear because you cannot configure the primary server to use a global security location that it cannot access.

To update the system tables:

Note: When updating system tables, do not delete any seemingly empty records; these contain space characters in some columns and refer to locations controlled by your local XDB Server.
  1. From the primary XDB Server, start the XDB Server.
  2. On any client logged in to the primary XDB Server, start SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
  3. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  4. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  5. Issue the following SQL command to insert information about a remote server into the SYSIBM.SYSLUNAMES table:
    INSERT INTO sysibm.syslunames
    VALUES ("remote-server","","","","","");

    where

    remote-server is the name of a remote XDB Server to be accessed.
    Note:

    If you have already set up server-to-server connectivity for the global security server, use the UPDATE command to update existing records in the SYSIBM.SYSLUNAMES table.

    In the examples used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSLUNAMES
    VALUES ("xdbserve","","","","","");

    would have been issued on the XDB Server develop.

  6. Issue the following SQL command to insert information about the global security location into the SYSIBM.SYSLOCATIONS table:
    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES (remote-location,"X", remote-server,link-type);

    where:

    remote-location | is the name of the remote location to be accessed (unique among all locations on all servers that are used in distributed processing).
    X | indicates it is an XDB Server.
    remote-server | is the name of the remote server that controls the remote location.
    link-type | is the communication protocol used to connect to the remote server.

    In the examples used in this topic, the SQL command:

    INSERT INTO SYSIBM.SYSLOCATIONS
    VALUES ("sysglobal","X","xdbserve","B");

    would have been issued on the XDB Server develop.

  7. Issue the following SQL command to refresh the system:
    REFRESH LOCATIONS;
  8. Exit from SQL Wizard (Windows) or Interactive SQL Utility (UNIX).
  9. Shut down the primary XDB Server, as you need to make some changes to the server's configuration.

To configure the server:

  1. From the primary XDB Server, run the XDB Server Configuration Utility.
  2. Press F5 to access Multiuser Configuration options.
  3. Press F9 to turn on Global Security.
  4. Enter the name of the global security location. All logins to the XDB Server will be verified against the SYSXDB.SYSACFUSERS table in the location you specify. In the examples in this topic, the global security location is sysglobal.
  5. Press Enter to save the new location. Then, exit the utility.

Windows 2000

  1. From the primary XDB Server, run the XDB Server Configuration Utility.
  2. Click the Multiuser tab.
  3. Mark the Global Security checkbox.
  4. Enter the name of the global security location. All logins to the XDB Server will be verified against the SYSXDB.SYSACFUSERS table in the location you specify. In the examples in this topic, the global security location is sysglobal.
  5. Click OK.

Even though AuthIDs (usernames) and passwords are verified by a global security server, clients must have access to the tables they wish to use on the primary server. This can be done by granting the appropriate privileges to each client on the primary server. AuthIDs are created using SQL Wizard (Windows) or Interactive SQL Utility (UNIX). Privileges are granted using the SQL GRANT command from SQL Wizard (Windows) or Interactive SQL Utility (UNIX). See the chapter Security and Authority for more information on creating users and setting privileges.

Parent topic: Setting Up Global Security


Global Security Server Configuration

Restriction: This topic applies to Windows environments only.

The global security server must be configured to contain information about all of the AuthIDs and passwords that it will verify. In the examples, the global security XDB Server is xdbserve.

Before using global security, you must first create a global security location on the global security server. This process involves renaming your SYSTEM location with the name of your global security location. In the examples, the global security location is sysglobal.

To create a global security location:

  1. From the primary XDB Server, start the XDB Server.
  2. On any client logged in to the primary XDB Server, start the SQL Wizard (Windows) or Interactive SQL (UNIX).
  3. Log in with an AuthID that has super user privileges, such as the INSTALL AuthID, provided with the XDB Server.
  4. From an SQL Window, set the current location to the SYSTEM location:
    SET LOCATION TO system;
  5. Issue the following SQL command to update the information about the global security location in the SYSIBM.SYSLOCATIONS table:
    UPDATE sysibm.syslocations
    SET location = "global-security-location"
      WHERE location = "system";

    In the examples used in this topic, the SQL command:

    UPDATE sysibm.syslocations
    SET location = "sysglobal"
      WHERE location = "system";

    would have been issued on the XDB Server xdbserve.

  6. Issue the following SQL command to update the information about the global security location in the SYSXDB.SYSLOCALS table:
    UPDATE sysxdb.syslocals
    SET location = "global-security-location"
      WHERE location = "system";

    In the examples used in this topic, the SQL command:

    UPDATE sysxdb.syslocals
    SET location = "sysglobal"
      WHERE location = "system";

    would have been issued on the XDB Server xdbserve.

  7. Exit the SQL Wizard (Windows) or Interactive SQL (UNIX).

In order to verify AuthIDs (usernames) and passwords, there must be values in the appropriate system tables, primarily SYSXDB.SYSACFUSERS, on the global security server.

AuthIDs are created using the SQL Wizard Admin menu (Windows) or the CREATE USER command in Interactive SQL (UNIX). Use this utility to enter AuthIDs and passwords for all users who will be accessing any XDB Server using this global security server.

  1. To enter AuthIDs and passwords from the global security XDB Server, start the XDB Server.
  2. On any client logged in to the global security XDB Server, start the SQL Wizard (Windows) or Interactive SQL (UNIX).
  3. Create AuthIDs and passwords for all users who will log into the primary XDB Server, and have their AuthIDs and passwords verified by the global security server.

To implement this topic's examples, create an AuthID Bob on XDBSERVE.

Parent topic: Setting Up Global Security
Related information
Security and Authority


Outbound, Inbound and Trusting Used Together

Restriction: This topic applies to Windows environments only.

When used independently of each other, outbound mapping, inbound mapping, and trusting are easy procedures to set up. However, if you wish to use these features together, you should plan out your mapping and trusting scheme before implementing it.

Some concepts, such as AuthID, password, groups, and priorities are controlled on a per server basis. Others, such as database and table privileges, are controlled on a per location basis.

If you will be using inbound mapping and outbound mapping between two servers you must be sure that your system tables cover all possible mappings. For example, requests from Bob on the XDB Server develop to the XDB Server sales will be subject to outbound mapping on develop. Requests from Debbie on develop to sales will be subject to inbound mapping on sales.

To allow this scenario, you must have one additional row in the SYSIBM.SYSUSERNAMES tables on each XDB Server (sales and develop) that indicates requests from these users should not be mapped.

Parent topic: Multiserver Security


Backup and Recovery

Restriction: This topic applies to Windows environments only.
  • Log Files
  • Server Configuration
  • Backing Up Locations
  • System Recovery
Parent topic: SQL Option Server Administration Guide


Log Files

Restriction: This topic applies to Windows environments only.

Instead of building separate forward and backward logs, the unified logging system automatically builds and names a series of log files for each location when that location is created. These location log files provide protection against both transient system failures (e.g., power outages, operating system crashes), and media failures, such as a hard disk crash.

  • Log File Naming
  • Location of Log Files
  • Log Files During Recovery
  • Turning Logging On and Off
Parent topic: Backup and Recovery


Log File Naming

Restriction: This topic applies to Windows environments only.

Each time a location is created the XDB Server logging system creates a file named anchor.log. This file holds information on how to recover the location after a transient system failure or media failure. As work commences in the location, the logging system automatically creates a second log file named a0000000.log, which records all current transaction information necessary for transient system failure recovery.

A series of log files (beginning with a0000000.log) are automatically created by the logging system to record all data table changes since the location was created (or since logging was reset for that location). Log files are named automatically by the system according to the following convention:

xyyyyyyy.log

where the x prefix is a letter of the alphabet, and each y represents a digit of a hexadecimal number (seven digits long). The first in the series of log files built is always named a0000000.log, with the hexadecimal portion of each subsequent log file name indexed upward by one (for example, a0000001.log, a0000002.log, etc.).

Parent topic: Log Files


Location of Log Files

Restriction: This topic applies to Windows environments only.

All logging files are stored in the same log path directory, which by default is the parent location directory. This path can be (and should be) set to a separate physical storage device, providing greater protection against a system hard disk crash. The path for your location log files can be changed by issuing a SET LOG command from the SQL Wizard (Windows) or Interactive SQL (UNIX). Make sure that each location on the server has a unique log path.

Parent topic: Log Files


Log Files During Recovery

Restriction: This topic applies to Windows environments only.

The server tries to find the anchor.log file each time a location is opened. If anchor.log is not there, the server creates a new one and initializes the new stream of log file names to begin with a0000000.log. If anchor.log is present and the location was shut down normally after its last use, the server will continue writing entries to the end of the last log file created.

If anchor.log is present and the location experienced transient system failure (due to a power outage, operating system failure, etc.) after its last use, the server automatically recovers the location to a logically consistent point. It ensures that all data that was committed before the crash is applied to the location tables, and all other data is rolled back. This recovery occurs when the first user accesses the location. The logging system then continues functioning normally, appending new work to the end of the last log file -- just as if the system had been shut down normally.

Parent topic: Log Files


Turning Logging On and Off

Restriction: This topic applies to Windows environments only.

If you have SYSADM authority or higher and exclusive use of the server, you can temporarily turn the logging system off. When issued from the SQL Wizard (Windows) or Interactive SQL (UNIX), the SET LOG OFF command temporarily suspends logging for the location during the remainder of the current session. Turning logging off for a particular location is a temporary expedient for an exclusive user that does not want to incur the overhead of logging during administrative tasks.

Logging is turned off for the current session, only. Logging can be activated again in the current session by issuing a SET LOG ON command. Exiting the session toggles the status of location logging back to on (the default). The next session that accesses the location therefore has logging turned on. Setting the logging system on or off from the SQL Wizard (Windows) or Interactive SQL (UNIX) does not affect the logging configuration settings in your xdbsrvco.ini file.

Parent topic: Log Files


Server Configuration

Restriction: This topic applies to Windows environments only.

Control the behavior of the XDB Server logging system by setting the four parameters described in this topic.

  • Delete Old Logs (Recovery)
  • Log File Size
  • Log Buffer Size
  • Checkpoint Frequency
Parent topic: Backup and Recovery


Delete Old Logs (Recovery)

Restriction: This topic applies to Windows environments only.

If you want to issue the ROLLFORWARD command to initiate location recovery, you must set the bDeleteOldLogs parameter to 0 (off).

To set the parameter (UNIX):

  1. Add the following to the [XdbLogManager] topic of the xdbsrvco.ini server configuration file:
    bDeleteOldLogs=0

To set the parameter (Windows):

  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Turn Recovery on.

See the section Media Failure Recovery and the SQL Reference for information about the ROLLFORWARD command.

CAUTION:
Run-time or mission-critical XDB Servers should always run with recovery turned on (bDeleteOldLogs=0).

Set bDeleteOldLogs to 1 (on) to allow developers to automatically delete location log files not needed for transient system failure recovery from the hard disk. Even with bDeleteOldLogs set to 1 (on), the server will recover to a logically consistent state after a transient system failure, such as terminating abnormally due to a power loss, or operating system failure. The logging system always preserves the last transaction.

To set the parameter (UNIX):

  1. Add the following to the [XdbLogManager] topic of the xdbsrvco.ini server configuration file :
    bDeleteOldLogs=1

To set the parameter (Windows):

  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Turn Recovery off.
Parent topic: Server Configuration


Log File Size

Restriction: This topic applies to Windows environments only.

Set the log file size to specify a maximum size for individual log files (ranging from 1 MB to 10 MB). Log file size values are in increments of 1KB, with a default value of 1024 (1 MB). When the server writes the specified number of bytes out to the log file, it will close that file and create the next one. This feature allows users to backup individual log files while the system is up. You can configure log files to fit on a floppy diskette.

To set the parameter on Windows:

  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Enter the desired log file size in the Log File Size text box, or drag the slider.
Parent topic: Server Configuration


Log Buffer Size

Restriction: This topic applies to Windows environments only.

The log buffer size parameter governs the size of the internal write buffer used by the logging system. Internal write buffer values are in increments of 1 KB, with a default value of 128.

Note: The quotient of the log file size divided by the buffer size must be a whole number. If this ratio is not an integer value, the logging system adjusts the buffer size and possibly the log file size until an integer ratio is achieved.
To set the parameter (UNIX):
  1. Add the following to the [XdbLogManager] topic of the xdbsrvco.ini server configuration file:
    lLogBufSize=n
To set the parameter (Windows):
  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Enter the desired log buffer size in the Log Buffer Size text box, or drag the slider.
Parent topic: Server Configuration


Checkpoint Frequency

Restriction: This topic applies to Windows environments only.

The checkpoint frequency parameter determines the amount of time between automatic logging system checkpoints. These automatic checkpoints cause the contents of log buffer cache to be written to table files on disk, removing the need for applications to issue checkpoints manually. See the SQL Reference for a description of the CHECKPOINT command.

The checkpoint frequency parameter is one of the factors affecting the length of time needed to return location data objects to a logically consistent state after a transient system failure, such as a power outage, or operating system failure. If you increase the checkpoint interval, the system requires more time for log recovery after a transient system failure. Conversely, a shorter checkpoint interval reduces average recovery time, but increases system overhead.

To set the parameter (UNIX):
  1. Add the following to the [XdbLogManager] topic of the xdbsrvco.ini server configuration file:
    lCheckpointFreq=n
To set the parameter (Windows):
  1. Click the Logging tab within the XDB Server Configuration Utility.
  2. Enter the desired checkpoint frequency in seconds in the Checkpoint Frequency text box, or drag the slider.
Parent topic: Server Configuration


Backing Up Locations

Restriction: This topic applies to Windows environments only.

We strongly recommend that you implement a regularly scheduled and frequent procedure for backing up your locations and data to avoid losses due to media, machine or operator failure. Backup rules for your installation will vary with each application. The frequency with which you run backups depends on the importance of the data, how often it changes, the maximum time needed to recover, and how large the data tables and location are. For each application, you must weigh the time and space costs of backups against the risk of data loss.

The BACKUP LOCATION and Restore batch files commands operate on a specific location and include all paths and files for all data objects in the location. In order to restore any combination of data objects from a particular location you must restore the entire location. The ROLLFORWARD command also operates on an entire location, applying a specified series of log files to a restored backup copy of the location data. See the following topics and the SQL Reference for detailed descriptions of the updated BACKUP LOCATION command and ROLLFORWARD command.

If you use an operating system backup command or another backup utility, be sure to back up all the files in all the paths that are defined for the location, including storage group (stogroup) paths and paths defined in various environment variables, if any. Be sure to archive and then delete the current series of log files after executing each location backup. Deleting the current log files resets location logging, causing a new series of log files to be built the next time the location is accessed.

Note:

If you want to use your operating system's backup, you must first shut down the server or take its locations off line, using the SQL OFFLINE command. See the SQL Reference for detailed descriptions of the ONLINE and OFFLINE commands.

  • BACKUP LOCATION Command
  • Resetting Location Logging
  • Restore
  • ROLLFORWARD Command
  • COMPACT Command
  • Backup Procedure
  • Other Backup Options
Parent topic: Backup and Recovery


BACKUP LOCATION Command

Restriction: This topic applies to Windows environments only.

The BACKUP LOCATION command creates copies of all files that reside in the paths defined for the specified location. If stogroups are used in the location, appropriate files are also copied from all the drives and paths that are defined by the stogroups. If you have special paths defined by environment variables (such as XDB_index-name_location-name or XDBIDX_location-name) in the [Server] topic of your server machine's xdb.ini file, files in most of these paths are also backed up.

You can use the BACKUP LOCATION command only if the location being backed up is not currently in use by you or another user. The BACKUP LOCATION command copies the files to the target device and path you specify. The target directory must not already exist. See the BACKUP LOCATION command in the SQL Reference for more information. This can be a file server or a different hard disk drive. Tape drives and diskettes are not recommended.

The syntax of the BACKUP LOCATION command is:

BACKUP LOCATION location-name TO path-name [ AND INDEX | NOT INDEX ]

The AND INDEX | NOT INDEX parameter is optional. If not specified, AND INDEX is assumed and the system copies all appropriate index files along with the other files. If NOT INDEX is specified, the *.idx and *.ptr files are not copied. If you need to restore a location from a backup that did not include the index files, you will need to rebuild the indexes using the COMPACT LOCATION AND INDEX command.

Note:
  • To avoid confusion, always use a different path for each backup of each location. This will provide an xdbrest.cmd or xdbrest.bat file for each backup of each location.
  • BACKUP LOCATION does not copy files onto multiple diskettes.
Note:
  • If the contents of a location are too large to fit on one diskette, and you do not have an alternate high capacity device, use your operating system's backup command or an equivalent utility instead.
  • Be sure to back up all files in all relevant subdirectories.
  • Reset your log files after backing up a location. See the section Resetting Location Logging for more information.
Parent topic: Backing Up Locations


Resetting Location Logging

Restriction: This topic applies to Windows environments only.

Whenever a new location is created, the logging system automatically creates a series of log files just for that location. For an existing location, we recommend that these location log files be manually reset after each location backup process. Manually resetting location logging immediately after backing up speeds recovery in the event of a serious media failure, since only log entries originating after your location backup need be replayed against your location tables.

The XDB Server logging system automatically creates a series of log files when a new location is created. Logging should be manually reset as a part of the location backup process.

To manually reset location logging:

  1. Shut down server.
  2. Copy log files from the location logging directory to a separate archive directory.
  3. Depending on whether you are using the BACKUP LOCATION command or an operating system backup command, do one of the following:
    • Bring the server back up and run the BACKUP LOCATION command from the SQL Wizard (Windows) or Interactive SQL Utility (UNIX). (Be sure you execute the BACKUP LOCATION command from a location other than the one you are backing up.)
    • Run your operating system (or other) backup utility as appropriate (be sure to archive all directories associated with the XDB location).
  4. Shut down the server (if using BACKUP LOCATION).
  5. Delete all log files (*.log) from your location logging directory. The next time the location is accessed, a fresh series of log files will automatically be created by the logging system.

Location logging should be manually reset after any type of location backup (that is BACKUP LOCATION command or operating system backup).

Parent topic: Backing Up Locations


Restore

Restriction: This topic applies to Windows environments only.

BACKUP LOCATION also creates a batch file (xdbrest.bat) that can be run from the operating system command line to restore the location's data objects. xdbrest.bat is created in the same path you designate for the backup files.

Parent topic: Backing Up Locations


ROLLFORWARD Command

Restriction: This topic applies to Windows environments only.

The ROLLFORWARD command does not recover the following kinds of changes:

  • Data Control Language (DCL) commands, such as GRANT and REVOKE.
  • Utility commands such as SET.
  • Compact command.
  • TRUNCATE TABLE command.

Therefore, a backup should be performed after any of the above operations.

Parent topic: Backing Up Locations


COMPACT Command

Restriction: This topic applies to Windows environments only.

You must always backup up your location and reset location logging (that is delete old location log files) after performing a COMPACT.

Note:

Never perform a COMPACT on a restored location before replaying log files. Compacting a location modifies the location table data and makes the old log files incompatible with the newly compacted location.

Parent topic: Backing Up Locations


Backup Procedure

Restriction: This topic applies to Windows environments only.

The BACKUP LOCATION command will not archive off log files. Log files must be archived manually, after which location logging must be manually reset.

To backup a location using the BACKUP LOCATION command and reset location logging:

  1. Ensure that nobody is currently accessing the location you are backing up, and ensure that no incomplete transactions are in progress. You must be running in Isolation Level EU (exclusive use).
  2. Log into a location other than the one you are backing up (for example, SYSTEM location).
  3. Enter the BACKUP LOCATION command from the SQL Wizard (Windows) or Interactive SQL (UNIX).
  4. If you use removable storage media for your backups, carefully record vital information on the backup media's labels, including:
    • Location Name
    • Database Name
    • Stogroup and log file path names
    • Names of special paths that are defined in the server machine's xdb.ini file such as paths for indexes
    • Logging system information
    • Backup time and date
  5. Bring the server down.
  6. Archive the current series of log files. This series of files should be clearly marked and archived in a separate directory. They may be needed for playing against an older backup, in the event the latest location backup is corrupted or unavailable. Serial numbers can be used to ensure that the correct series of log files are applied to the correct backup copy of the location.
  7. Once Step 6 is complete, delete the current series log files from the location logging directory.
  8. Bring the server back up. Next time the location is accessed, a new set of log files is automatically created in the location logging directory.
Parent topic: Backing Up Locations


Other Backup Options

Restriction: This topic applies to Windows environments only.

Most commercially available archival utilities can be used to back up locations. When using a backup utility, it is important to keep in mind that you must backup the contents of all directories for the entire location, including storage group paths (if any) and all subdirectories. This last point is important, as the server could have duplicate file names in different directories, which need to be kept separate on the backup device.

Note:
  • Do not attempt to shortcut the process by backing up only the *.tab files. a *.tab file is useless without the index files (*.idx and *.ptr) and other files associated with the tables.
  • If you want to copy tables or views between locations, use Migrate. See the Migrate User's Guide for more information. Do not use an operating system copy command to copy individual tables from one directory to another.
Parent topic: Backing Up Locations


System Recovery

Restriction: This topic applies to Windows environments only.

If your system terminates abnormally due to transient system failure or media failure (disk crash), you can restore all previously committed work by following either the Transient System Failure or Media Failure scenario instructions.

  • Transient System Failure
  • Transient System Failure Recovery
  • Media Failure
Parent topic: Backup and Recovery


Transient System Failure

Restriction: This topic applies to Windows environments only.

Transient system failure can occur from power outages, operating system crashes, or termination of the server with users still logged on.

Parent topic: System Recovery


Transient System Failure Recovery

Restriction: This topic applies to Windows environments only.

In cases of transient system failure, system recovery occurs automatically either the next time any user attempts to login to a location in which a transaction was abnormally terminated or the next time a SET LOCATION command is issued against an affected location. For any transaction that was abnormally terminated before it completed, the before image stored in the location log files is used to automatically rollback all uncommitted transactions and restore the data tables involved to a logically consistent state.

This transient system failure recovery feature (the same functionality provided by backward logging in previous versions of the XDB Server) is permanently defaulted to on, with no user intervention required.

The average length of time necessary to bring all location data objects to a logically consistent state is affected by the value of the Checkpoint Frequency configuration parameter. This parameter allows the user to adjust the time between automatic logging system checkpoints. See the section Server Configuration for information about setting the Checkpoint Frequency parameter.

When the logging system issues a checkpoint, the contents of the entire log buffer cache are flushed to disk, that is, written to table files.

Parent topic: System Recovery


Media Failure

Restriction: This topic applies to Windows environments only.

Media failure is a serious hardware mishap such as a disk crash.

Media Failure Recovery

You can restore a backup copy of a location's files and replay the contents of a discrete series of log files against the restored location using the ROLLFORWARD command.

A discrete series of log files consists of all changes made to the data objects within an location since the last time the logging system for that location was reset (usually after the last location backup). You must configure the server to ensure that your system is keeping log files. See the section Server Configuration - Delete Old Logs for more information.

If you have made periodic backups of your location (resetting the logging system after each backup), and you have configured your server to keep old logs, you can usually recover from a media failure.

To recover from a media failure:

  1. Shut down the server.
  2. For every location affected by a media failure, use your operating system copy command to archive the current series of log files to a drive and path that is different from any of the location directories you are recovering. Under ideal circumstances, the location log files should be on a different physical drive, separate from the corrupted location files.
  3. Delete current series of log files from the location logging directory.
  4. Locate the latest backup copy of the appropriate location, associated stogroup directories and other related directories.
  5. Restore the backup to the respective drives and paths, using one of the following sets of instructions:

    • If you used the BACKUP LOCATION command:

      Make sure that the server is shut down, and that all destination directories and subdirectories exist (the restore program will not create directories). Then, change to the drive and directory where the backup batch file resides and enter the following at the operating system command line:

      xdbrest

      Any files in the destination directories will be overwritten. Log files will not be restored.

    • If you used your operating system or other utility:

      You must restore files using the compatible operating system restore command prior to recovery.

      If you need to restore location files on a different drive or in different paths than they previously resided, be sure to edit the appropriate system tables to make the XDB Server aware of the new location names and paths. Edit SYSXDB.SYSLOCALS and SYSIBM.SYSLOCATIONS tables to specify location names and path names. Edit SYSIBM.SYSSTOGROUP and SYSIBM.SYSVOLUMES to specify stogroup information. Also check the server machine's configuration file for other special directories, such as index paths.

  6. Bring the server back up.
  7. Before replaying the log files with the ROLLFORWARD command, be sure you are running in Exclusive Use (EU) isolation level. Use the SET ISOLATION command or the Options Utility to change your isolation level. Running in EU gives you total control over the server. Likewise, no incomplete transactions can still be in progress.
  8. Even if only one or more tables within a location need to be restored, the ROLLFORWARD command reconstructs the entire location in question. The ROLLFORWARD command operates on the location level only, restoring one complete location with each execution.
  9. In preparation for replaying all outstanding series of log files against the restored location, create a temporary log file directory and copy the current series of log files (or the most current series of log files if more than one) into that directory. Although not strictly required, resetting location logging after each backup ensures that your current series of log files have recorded only those transactions occurring since the last backup.
  10. From the SQL Wizard (Windows) or Interactive SQL (UNIX), execute a ROLLFORWARD command naming the restored location and the temporary log file directory containing the log files.

    Issue the following SQL command:

    ROLLFORWARD location-name
    USING log-path

    where location-name is the name of the location containing the restored backup files and log-path is the drive and path name of the directory containing the anchor file and series of log files to be replayed against the restored location. This directory should contain the anchor.log file plus one or more log files beginning with the file named ?0000000.log (where ? = [a-z]).

    For example, the following ROLLFORWARD command would apply the log files contained in the directory c:\xdbnt\logfiles (Windows) or /xdb/logfiles (UNIX) to the system location

    Windows:
    ROLLFORWARD system
    USING c:\xdbnt\logfiles
    UNIX:
    ROLLFORWARD system
    USING /xdb/logfiles

    During a ROLLFORWARD, all transactions contained in the location log files are replayed against the restored location.

  11. More than one series of log files may need to be replayed in cases where the location was not backed up (or the backup was corrupted or lost) each time location logging was reset. In these cases, multiple series of log files must be played against the last available backup beginning with the oldest series of log files and finishing with the most recent series.

    In cases where multiple series of log files are being replayed against an older location backup:

    1. Follow the directions in Step 9 to replay the oldest series of log files first (by indicating the directory containing this first series of log files in the ROLLFORWARD command).
    2. Repeat Step A with the next oldest series of log files, being sure to indicate a new directory containing these log files (the same directory can be used as long as the previously replayed series of log files are erased and replaced by the next series).
    3. When the most recent series of log files is ready to be replayed, follow Step 9 one last time to complete the location recovery.

    The sum total of all ROLLFORWARD operations applied against a restored location causes the logging system to run through all the transaction data contained in each series of log files, returning the location to the state it was in immediately before the system failure.

    When the recovery process is complete, press Esc to exit the SQL Wizard (Windows) or Interactive SQL (UNIX).

  12. Shut down the server.
  13. Reset the logging system. See the section Resetting Location Logging.
  14. Start the server. The server is now ready for normal operations to resume.

After all recent log files have been applied to the restored backup copy of the location, your data tables should be returned to a state existing prior to the media failure.

Parent topic: System Recovery


Storage Requirements

Restriction: This topic applies to Windows environments only.

Disk storage space requirements depend on which version of the XDB Server you are using and the optional related products you have installed.Each location you create requires a minimal amount of overhead to account for system tables and the default database structure. The overhead for a location, not counting user tables, indexes, and other user objects is approximately 320K.

  • Table Storage Requirements
  • Index Space Requirements
  • Temporary Storage Requirements
  • Log Requirements
  • Other Storage Requirements
Parent topic: SQL Option Server Administration Guide


Table Storage Requirements

Restriction: This topic applies to Windows environments only.

To estimate the bytes of disk space a table will occupy you must consider overhead as well as space occupied by data. You must also have a realistic idea of the maximum number of records to be stored in the table.

Formulas for estimating space requirements for tables are described in this topic. The formulas use the following variables:

E | Estimated table storage required (bytes)
I | Estimated index storage required (bytes)
P | Physical record length (maximum 32,767 bytes)
N | Number of records in the table (estimate)
T | Table overhead (88 bytes per table)
F | Field overhead (86 bytes per field)
R | Record overhead (2 bytes per record)
Di | Data storage requirement for field i per record (Depends on data type. See the following table.)
Oi | Overhead for field i per record (2 bytes) (While the number of bytes for data overhead is given as 2 for all data types, character fields of odd length actually require only 1 byte of overhead per record.)
f | Number of fields in table

The formula for calculating the physical record length, P, is:

The general formula for estimating bytes of storage required by a table is:

Substituting for P yields the formula:

Use the following table to find the data storage (D) and overhead (O) for the i-th field, depending on the data type.

Note:

The maximum physical record length is 32,767, which includes overhead. When determining the length of long records, use the formula for P, given earlier.

VARCHAR and LONG VARCHAR data types are provided for ANSI and DB2 compatibility only. Data for these types is currently stored as regular character data. All of the BLOB data types (image, binary, varbinary and long varbinary) are stored in separate files-- one file per blob column.

Data Type | D | O
smallint | 2 | 2
int | 4 | 2
float 4 | 4 | 2
float 8 | 8 | 2
money | 8 | 2
decimal | (precision/2)+1 | 2
date | 6 | 2
time | 6 | 2
char (odd length) | length | 1
char (even length) | length | 2
varchar (odd length) | length | 1
varchar (even length) | length | 2
long varchar | 4056 | 2
graphic (odd length) | length | 1
graphic (even length) | length | 2
vargraphic (odd length) | length | 1
vargraphic (even length) | length | 2
long vargraphic | 4056 | 2
blob (image, binary, varbinary or long varbinary) | stored in separate file; up to 2GB each | 4
Parent topic: Storage Requirements


Index Space Requirements

Restriction: This topic applies to Windows environments only.

Estimating the amount of space occupied by an index is difficult. The XDB Server uses B-tree indexes. The values in an indexed field and a pointer to the record containing it are stored in the *.idx file for the index; pointers to each duplicate instance of the value are stored in the *.ptr file for the index. The *.ptr file will contain 0 bytes if the index was created using the UNIQUE option.

Before you start you must have an estimate of the number of records in the table and the number of distinct values in the index.

Formulas for estimating space requirements for indexes are described in this topic. The formulas use the following variables:

I | Estimated index storage required (bytes)
V | Number of distinct values in index (estimate)
N | Number of records in the table (estimate)
S | Storage requirement for index value (Depends on index type)
Dj | Data storage requirement for field j (Depends on data type. See the following table.)
Oj | Overhead for field j (Depends on data type. See the following table.)
f | Number of fields in index

The bytes of storage required for an index is calculated as follows:

Note that if the index is created using the UNIQUE option, the number of records is equal to the number of distinct values, and the equation for calculating index storage requirements is reduced to:

In either case, S, the storage requirement for indexed values, depends on the type of index.

Regular Index

To compute the storage requirement S for a single field index, use this formula:

Compound Index

To compute the storage requirement S for a compound index on f fields, use this formula:

Parent topic: Storage Requirements


Temporary Storage Requirements

Restriction: This topic applies to Windows environments only.

You should have enough space in the temporary directory to store the largest result you anticipate retrieving from the database. As a rule of thumb, you should have at least two to three times the space required for your largest table in order to perform joins. However, the space required for your particular application might differ considerably.

Parent topic: Storage Requirements


Log Requirements

Restriction: This topic applies to Windows environments only.

The amount of space required by location logs depends on several factors, including:

  1. Frequency of Location Backups.

    If you backup your locations (and the location log files) frequently, the location log will contain fewer entries, and will therefore require less space.

  2. Frequency and Number of Table Inserts, Updates, Deletes.

    The log file stores the after image and the before images of all records changed by a table transaction. If changes occur often, or changes involve many records, the log file will be large.

Parent topic: Storage Requirements


Other Storage Requirements

Restriction: This topic applies to Windows environments only.

Storage requirements for static database components such as forms, report command files, and menus can be determined after each component is created. Use your operating system directory list command to view the size of files after they have been created.

While the size of various components might vary considerably, these files do not generally change size once the components are developed. You might use the size of a component that performs a similar function as an estimate for a new component you are developing.

Parent topic: Storage Requirements


Performance Tuning

Restriction: This topic applies to Windows environments only.
  • Optimizing Query Processing
  • Improving Production Processing
  • Increasing Data Import Speed
  • Improving Performance During Object Creation
  • Administrative Performance Tools
Parent topic: SQL Option Server Administration Guide


Optimizing Query Processing

Restriction: This topic applies to Windows environments only.

The Query Optimizer uses advanced performance optimizing techniques when processing queries, especially when appropriate indexes are available. Most of the query processing algorithms described in this section are automatic; they do not require user intervention. However, understanding how the various processing algorithms use indexes will help you to decide when indexes are needed as well as help you construct more efficient queries. A list of query guidelines is provided at the end of this section.

  • Indexes and Performance
  • Overriding the Optimizer
  • Retrieval Speed vs. Update Speed
  • List Prefetch
  • Aggregate Clause Processing
  • Predicates
  • Expressions
  • LIKE Predicate
  • Index Usage with AND and OR
  • Nested Queries
  • Correlated Queries
  • Join Optimization
  • Sorting
  • IN LIST with a Range Condition
  • Joins with Non-Join Predicates
  • Join Restrictive List Analysis
  • Query Performance Summary
Parent topic: Performance Tuning


Indexes and Performance

Restriction: This topic applies to Windows environments only.

The XDB Server uses B-tree indexes to speed retrieval. Like a book index, a database index reduces the amount of data that must be searched to find an answer. The XDB Server performs automatic query optimization to select the best index to use for a query.

In general, the fewer records accessed, the faster the retrieval time. The XDB Server uses available indexes whenever they help to speed retrieval. But, while indexes generally speed up retrieval, they can slow down updates, inserts and deletes.

Usually, it is faster to execute a query using one or more indexes than to examine every record in the tables involved in the query. The XDB query optimization algorithms examine the indexes available and pick which indexes, if any, to use for a particular query. The user does not need to specify which indexes to use.

The query optimization algorithms analyze the selectivity of a column to determine how to process a query. Selectivity of a column is determined by calculating how unique the values in the column are. The more unique the values, the more likely the column will be a candidate for index use. Selectivity is determined by the formula, 1/x, where x is the number of distinct values in a column or index. The larger the number of distinct values, the more unique the column is and the lower the selectivity is. This increases the probability that the optimizer will use the index.

If a command does not contain a WHERE, ORDER BY, HAVING, or GROUP BY clause, the server generally will not perform an index search; instead, it processes the table sequentially. Some aggregate functions can cause an index to be used in certain cases. Usually, if a column in the WHERE clause is indexed, the index is a candidate for use. Other factors, such as the number of distinct values in an index, determine final index selection.

Parent topic: Optimizing Query Processing


Overriding the Optimizer

Restriction: This topic applies to Windows environments only.

You can force the use of an index for a particular query, or force the system to not use an index.

To force the use of an index, enter an asterisk (*) in parentheses after the name of the indexed column when you construct the query. To force the system to ignore the index, use enter a hyphen (-) in parentheses after the name of the indexed column when you construct the query.

For example, assuming that an index exists on C_NO:

This query uses the C_NO index.

SELECT c_no, o_no, o_date
    FROM orders
    WHERE c_no(*)<20

This query does not use the index.

SELECT c_no, o_no, o_date
    FROM orders
    WHERE c_no(-)<20

The (*) and (-) options are valid only for column names that appear in a WHERE clause. You cannot use the (*) and (-) options in GROUP BY, HAVING or ORDER BY clauses.

Parent topic: Optimizing Query Processing


Retrieval Speed vs. Update Speed

Restriction: This topic applies to Windows environments only.

There is a trade off between retrieval speed and update speed when indexes are used, since each time a value in an indexed column is changed, the system must also update the index. Overall database performance can actually deteriorate if indexes are built on columns that are seldom searched but are frequently updated. You might want to build a number of indexes on a read-only table, but limit a frequently updated table to a minimal set of indexes.

When importing data into a table, it is significantly faster to create indexes after the data has been inserted. Prior to importing, you should drop all indexes that are not required to enforce uniqueness. Use a batch SQL file or procedure to re-create indexes after importing.

Parent topic: Optimizing Query Processing


List Prefetch

Restriction: This topic applies to Windows environments only.

List Prefetch is an Query Optimizer routine that extracts the Record IDs (RIDs) that match a specific search criteria from a particular index. These RIDs are sorted in ascending order, thereby enabling sequential table access. By accessing the table data pages in a sequential fashion, disk head seek time can be drastically reduced and data page prefetching performed. The server considers list prefetch when table data page access is required, when a multiple index access condition is detected, or if data needs to be retrieved in physical order.

Note: List prefetch can be affected by the size of the RID Pool buffer. See the section Improving Production Processing for more information.
Parent topic: Optimizing Query Processing


Aggregate Clause Processing

Restriction: This topic applies to Windows environments only.

When all aggregate functions in a query are on the same indexed field, the system will determine the result from the index rather than by using the slower process of accessing the base table. For example, given the following query, the server does not need to look at the table file if an index exists on PAYRATE; the index alone is sufficient to give the result.

SELECT MAX(payrate), MIN(payrate), AVG(payrate)
    FROM employee

Likewise, any COUNT aggregate using a WHERE clause that can be resolved via an index will not access the base table. For example, if an index exists on columns A and B in TABLE1 and the following query is issued:

SELECT COUNT(*) FROM table1
    WHERE a=2 AND b=3;

the information will be available via the index. The base table (TABLE1) is not accessed.

Parent topic: Optimizing Query Processing


Predicates

Restriction: This topic applies to Windows environments only.

In the case of a simple predicate involving an indexed column, the XDB Server will generally use the index to speed retrieval. For example, given an index on ZIP, that index will be used to process the following query:

SELECT * FROM employee
    WHERE zip = "20441"
Parent topic: Optimizing Query Processing


Expressions

Restriction: This topic applies to Windows environments only.

If an indexed column appears in a query only as a part of an expression that alters the column, the index will not be used. For example, given the following query, an index on the PAYRATE column will not be used, even if it exists:

SELECT * FROM employee
    WHERE payrate * 1.10 > 13.00

Likewise, the index will not be used in the following query:

SELECT * FROM employee
    WHERE payrate > 13.00/1.10

Usually, it is best to perform the constant calculations prior to executing the query.

Parent topic: Optimizing Query Processing


LIKE Predicate

Restriction: This topic applies to Windows environments only.

When constructing queries containing a LIKE predicate that involves an indexed column, try to avoid pattern matching strings that begin with percent (%) or underbar (_). If the string in a LIKE predicate begins with either of these two characters, it automatically indicates that a sequential search must be performed on the entire index. For example, given an index on LNAME, the query:

SELECT * FROM employee
    WHERE lname LIKE "_risp%"

might take significantly longer than the query:

SELECT * FROM employee
    WHERE lname LIKE "Krisp%"
      OR lname LIKE "Crisp%"

In the first case, the entire index must be searched for any names that have "risp" as the second through fifth letter. This is virtually the same as having no index at all. In the second case, the search is for two specific starting strings; these are more quickly found because the search does not have to go through the entire index.

Parent topic: Optimizing Query Processing


Index Usage with AND and OR

Restriction: This topic applies to Windows environments only.

In the case of compound predicates connected with AND, the server will use all available indexes to find the intersection. For example, given indexes on columns ZIP and DEPT, both indexes might be used to process the following query:

SELECT * FROM employee
    WHERE zip = "20441"
      AND dept = "2020"
      AND payrate < 12.00

If an index had existed on PAYRATE, it would be used, but its absence does not prevent the use of the other indexes.

In the case of compound predicates connected with OR, the server uses an index, only if the two conditions reference the same column (and that column has an index). For example:

This query uses the index on the DEPT column:

SELECT * FROM employee
    WHERE dept = "2020"
       OR dept = "2021"

This query does not use the index on the DEPT or PAYRATE columns:

SELECT * FROM employee
    WHERE dept = "2020"
       OR payrate = 12.00
Parent topic: Optimizing Query Processing


Nested Queries

Restriction: This topic applies to Windows environments only.

While algorithms exist on some systems to convert any nested query into a flat join, the benefit of such algorithms is not always significant. Therefore, the server does not perform the conversion. Instead, the server continually makes use of feedback from intermediate results to avoid unnecessary searches. If the server methodology is not the most efficient for your data, you can restructure the query as a flat join.

When processing a nested query, the server first evaluates the inner query (subquery). Consider the following query:

SELECT * FROM dept
    WHERE mgr IN
        SELECT e_no FROM employee
            WHERE city = "Wild Woods"

The XDB Server first finds all employees who live in Wild Woods, and modifies the nested query to process the outer query. If an index exists on MGR, it might be used after the nested query has been processed.

Parent topic: Optimizing Query Processing


Correlated Queries

Restriction: This topic applies to Windows environments only.

When processing a correlated query, the outer query is processed first. The server compares the previous value to the current value to see if the inner query needs to be executed again. For example, given the following query to find the supplier who supplies the largest quantity of each product:

SELECT sno, pno FROM partsupp p
    WHERE qty =
        SELECT MAX(quantity) FROM items
            WHERE pno = p.pnoORDER BY pno

For each record in the PARTSUPP table, the inner query is evaluated to find the maximum quantity. If the next PARTSUPP record is for the same product, the maximum quantity is already known, and therefore the subquery is not performed. If PNO is indexed, then adding the ORDER BY PNO clause makes the query faster because the records with the same PNO values are all grouped together.

A correlated query whose correlated query block always evaluates to false is detected and does not continue to execute. If the correlation condition is not the condition that causes the query block to be false, the query block is always false.

For example, in this query:

SELECT * FROM table1 x
    WHERE EXISTS
        SELECT * FROM table2 y,table3 z
            WHERE y.f1 = z.f1
              AND x.f2 = z.f2
              AND y.f3 > 10;

if the inner SELECT does not retrieve any records without evaluating the correlation condition (X.F2=Z.F2), it can be determined that the query will not return any records; no records match the non-correlated criteria.

If only one correlation condition exists, the previous value of the correlation will unconditionally be saved for comparison with the next correlated value. (In previous versions of the XDB Server, this was only saved and compared if the correlated condition was not embedded in a NOT, AND or OR condition.)

Parent topic: Optimizing Query Processing


Join Optimization

Restriction: This topic applies to Windows environments only.

The XDB Server uses a number of optimization techniques for processing joins. When performing a multitable join, performance might improve significantly if you specify all possible join conditions; this allows the system to perform the joins with the optimal selectivity ratio first, thus reducing the number of comparisons required.

For example, imagine three tables: EMPLOYEE, DEPARTMENT and PROJECT. Every employee works in a department. Every project is the responsibility of a department. Every project is managed by an employee from the responsible department.

Thus there are three possible join conditions that can be used to join the three tables:

  • DEPARTMENT.DEPT_ID=EMPLOYEE.DEPT_ID
  • DEPARTMENT.DEPT_ID=PROJECT.RESPONSIBLE_DEPT_ID
  • EMPLOYEE.EMPLOYEE_ID=PROJECT.PROJECT_MANAGER_ID

While it is sufficient to provide any two of these join conditions in your query, you might experience significant performance improvement if you provide all three join conditions.

As a general rule, when joining n tables, you should provide at least n-1 join conditions. When the context of a query permits, optimal performance might be achieved by providing any additional, valid join conditions. However the use of redundant join conditions must be balanced against the readability and parsing cost of the query.

Parent topic: Optimizing Query Processing


Sorting

Restriction: This topic applies to Windows environments only.

When records are to be retrieved in a sorted order, indexes will speed up sorting.

If no appropriate indexes exist, qualifying records are located by performing a sequential search on the table. The resulting subset of records is sorted. The efficiency of the sort operation is affected by the Sort Space Size setting specified in the Configuration Utility.

If an index exists, a sequential search of the index (index walk) will be performed in some cases. For example, if an index exists on the PNO column, an index walk is performed to process the query:

SELECT * FROM part
    ORDER BY pno

In the following query, the index walk algorithm will make use of a compound index on the SNO and PNO columns:

SELECT * FROM partsupp
    ORDER BY sno, pno

When possible, the server uses the compound index if the first element in the compound index is referenced in a predicate or ORDER BY clause, even if the other columns are not referenced. For example, if the ORDER BY clause in the query above included only the SNO column, the compound index would be used. If the ORDER BY clause included only the PNO column, the index would not be used.

In the case of queries involving predicates and ORDER BY clauses, if appropriate indexes exist, the server will use the index to find the qualifying records, and then sort just those records. For example, given the following query, with indexes on PNO and QTY, the server uses the index on QTY to find the records that qualify, and then orders the result. The index on PNO is not currently used.

SELECT * FROM partsupp
    WHERE qty >= 200
    ORDER BY pno
Parent topic: Optimizing Query Processing


IN LIST with a Range Condition

Restriction: This topic applies to Windows environments only.

If an IN LIST exists in conjunction with a range condition, a compound index can be used. In the following example, there is an index on columns A, B and C in TABLE1:

SELECT * FROM table1
    WHERE a = 3
      AND b IN (6,7)
      AND c BETWEEN 2 AND 20;
Parent topic: Optimizing Query Processing


Joins with Non-Join Predicates

Restriction: This topic applies to Windows environments only.

Joins will take advantage of additional non-join predicates when compound indexes exist that involve both the join condition and the predicate.

For example, a compound index exists on TABLE2 (A,B,C):

SELECT * FROM table1,table2
    WHERE table1.a = table2.a
      AND table2.b = 3
      AND table2.c BETWEEN 1/1/1992 AND 12/31/1992;

If TABLE2 is an inner table of the join, the additional constraints will be applied when the join condition is applied.

Parent topic: Optimizing Query Processing


Join Restrictive List Analysis

Restriction: This topic applies to Windows environments only.

If a restrictive list exists and has been prefetched on the inner table of a join, it might be discarded if the size of the list is larger than a certain percentage of the table size. If the restrictive list is discarded, the join index will be used (no merging is performed).

Parent topic: Optimizing Query Processing


Query Performance Summary

Restriction: This topic applies to Windows environments only.

The guidelines listed below summarize the ways you can improve query performance.

  • If nested or correlated queries do not seem to process efficiently, restructure the query as a flat join to see if that method improves processing speed.
  • Use a correlated query instead of a nested query if the correlated column is indexed and the nested query returns a large amount of data.
  • Try to index the columns that have the lowest selectivity values (those with the largest number of different values), and construct your queries to include predicates involving these columns.
  • Try to avoid OR conditions on different columns. Use a union of queries containing AND conditions instead.
  • When creating compound indexes, try to list columns in the same order they appear in the ORDER BY clauses of your queries to allow the compound index to be used to speed up sorts.
  • Avoid numeric conversions. Try to make comparisons between columns of the same type.
  • Avoid the use of LIKE predicates beginning with % or __.
  • Avoid arithmetic expressions in a predicate, especially those that evaluate to a constant. Perform the calculation beforehand, if possible.
  • Select only the columns you need. Avoid SELECT * FROM when possible, especially when retrieving data across a network. Unneeded data creates unnecessary network traffic.
  • Avoid using COUNT(*) to check for existence.
  • Evaluate the benefits of single vs. compound indexes. Use compound index ordering if suitable. If possible, order the columns in the compound index by highest selectivity (that is, order the columns with the most unique values first).
  • Provide redundant information when joining tables, so that the system can select the lowest cost solution for you.
  • If a table is frequently updated or if most searches on the table are sequential searches (every record is accessed), avoid building any indexes on the table except for those used to enforce uniqueness.
  • Use views only when absolutely necessary. Each view access requires additional I/O and processing costs.
Parent topic: Optimizing Query Processing


Improving Production Processing

Restriction: This topic applies to Windows environments only.

This section describes options that can help improve overall processing speed when using the XDB Server.

  • Integrity Constraints and Processing Speed
  • Locking Options
  • Caching
  • Special Read-Only Caching
  • Record ID (RID) Pool Buffer
  • Number of Open Files
  • Number of Open Queries
  • Governor Settings
  • Miscellaneous
  • Reducing Disk I/O Contention
Parent topic: Performance Tuning


Integrity Constraints and Processing Speed

Restriction: This topic applies to Windows environments only.

The XDB Server supports schema level domain and referential integrity constraints. While integrity checking is a valuable facility, it can impact database performance considerably, especially on UPDATE, INSERT and DELETE operations.

You must determine whether the advantages of schema level integrity constraints outweigh the additional time required to enforce them. You might want to eliminate some of these checks at the schema level, and instead perform them through the validation facilities of the front-end data entry application. Remember that in a LAN environment use of integrity features creates additional network traffic.

Note that some indexes are automatically created and maintained by the system when integrity constraints are imposed on the database. These indexes can be dropped only by dropping the associated constraints.

For more information about referential constraints, see the following in the SQL Reference:

  • PRIMARY KEY, FOREIGN KEY and REFERENCES options on the CREATE or ALTER TABLE command.
  • WITH CHECK OPTION clause on the CREATE VIEW command.
Parent topic: Improving Production Processing


Locking Options

Restriction: This topic applies to Windows environments only.

In multiuser systems, the time spent waiting for locks can be considerable. The XDB Server offers three means of adjusting the effect of locks on performance.

  • Isolation Level.

    Adjust the isolation level to increase or decrease the length of time that locks (especially shared or read-only locks) are held. The sooner a lock is released, the sooner the resource can be locked by another transaction. The trade-off for increased concurrency is decreased consistency.

    Each user can set a default isolation level in the client configuration. To specify the isolation level during a session, use the SET ISOLATION command.

    On a single-workstation XDB Server that will be operating only one client session at a time, using the Exclusive Use (EU) isolation level will eliminate locking overhead.

  • Lock Granularity.

    The time to perform many batch operations that affect many records of a table can often be greatly decreased by acquiring a table lock. Table locks are acquired by issuing the LOCK TABLE command. (See the SQL Reference for more information on the LOCK TABLE command.) Performance improves because there is no need to lock individual records as they are accessed. However, in some cases it will take a considerable amount of time to acquire a table lock. Also, other processes that need to access the locked table must wait until the table lock is released.

  • Timeout Period.

    Users can adjust the amount of time the system tries to acquire a lock. If the time is too short, performance might deteriorate because transactions cannot acquire locks and must be continuously rolled back. On the other hand, if the time is too long, performance might deteriorate because it takes longer to resolve potential deadlocks.

    Users can set their own timeout periods by setting the Lock Request Timeout in the client configuration.

Parent topic: Improving Production Processing


Caching

Restriction: This topic applies to Windows environments only.

Caching is available for all database objects, including tables, indexes and data dictionary files. The cache size is specified at the server level using the Caching Options screen of the XDB Server Configuration Utility. Cache memory usage and other related information can be monitored on the XDB Cache Statistics screen while the server is running.

The major benefit of using cache is to keep frequently accessed disk blocks in RAM to ensure that subsequent access to these blocks requires no additional disk I/O. The buffer manager uses a searching algorithm to determine if a block exists in cache before deciding to retrieve that block from disk. If a block does not exist in the cache, this searching time can be classified as additional overhead because the search and the disk I/O must be performed.

The buffer manager also has a tossing algorithm. If the cache is full, some current cache blocks must be discarded before new blocks can be added. The determination of which blocks to discard is based upon a modified clock algorithm.

The cache manager can provide a performance boost only if the reduction in I/Os outweighs the CPU cost required to search and toss. The more objects there are to cache and the more random the access, the less useful a cache manager becomes.

For example, consider a database that is significantly larger than available RAM, with a large number of indexes (to optimize query processing) and data access patterns that are mostly random. All those indexes are eligible for caching, but the random access nature of the queries means that there will probably be a high percentage of cache tossing and low percentage of cache hits. This would indicate that each query was accessing either different I/O disk blocks or I/O blocks that had previously been tossed from the cache. In this situation, large cache sizes would have limited use.

If your system shows a high percentage of tossing and low percentage of cache hits, you should choose a cache size that would not assume I/O overlap between the query set, but would allow I/O reduction for an individual query. In this fashion, each individual query could benefit from common disk I/O access, while reducing the amount of CPU time required by the cache manager to search and toss.

It is important to check the cache hits and misses when all or most of your users are actively accessing data. Generally, the cache hit ratio increases as the number of users grows, especially when those users are performing similar tasks.

Parent topic: Improving Production Processing


Special Read-Only Caching

Restriction: This topic applies to Windows environments only.

Outside of the normal cache manager, the server provides additional buffer management techniques specific to read-only data. These techniques are available when the user isolation level is set to dirty read (DR), snapshot read (SR) or exclusive use (EU).

In this cases, the server provides buffered I/O at the cursor level.

If sequential access of a database object is detected within an individual cursor, sequential prefetch of data can be triggered, allowing multiple data pages to be read into a buffer controlled by that individual cursor. This method of buffer management enjoys the benefits of reduced I/O without the normal cache manager overhead (search and toss), and eliminates the need for critical sections.

Parent topic: Improving Production Processing


Record ID (RID) Pool Buffer

Restriction: This topic applies to Windows environments only.

The Query Optimizer makes use of a Record ID (RID) Pool Buffer when using the list prefetch algorithm for analyzing data access paths. See the section Optimizing Query Processing for more information on the list prefetch algorithm. List prefetch retrieves Record IDs from an index (in response to the constraints of a particular WHERE condition). The RID Pool Buffer is used to store the Record IDs. If required, the records are sorted before being stored in the RID Pool Buffer.

If the number of Record IDs fetched exceeds the available RID Pool size, the list prefetch is aborted and less efficient processing routines are used. For best performance, the size of the RID Pool Buffer should be large enough to contain the number of Record IDs expected from an index search.

The RID Pool size is specified in the XDBRIDPOOL environment variable in the server machine's configuration file. See XDBRIDPOOL in the appendix Environment Variables for more information on using this environment variable, and for a formula for calculating RID Pool Size.

Parent topic: Improving Production Processing


Number of Open Files

Restriction: This topic applies to Windows environments only.

The XDB Configuration Utility allows you to specify the Maximum Number of Open Files. This setting, which represents the maximum number of files that can be kept logically open, should include only the required number of files. When a file is opened in response to a user request, the system scans an internal array to see if the file is already open. If it is, then processing time is improved.

Parent topic: Improving Production Processing


Number of Open Queries

Restriction: This topic applies to Windows environments only.

The XDB Configuration Utility allows you to specify the Maximum Number of Open Queries. This setting, which represents the maximum number of queries that can be open at a given time, should include only the required number of queries. When an SQL statement is committed or rolled back, the system scans an internal array of open queries to find the one that should be closed. If the number specified for the Number of Open Queries is approximately the same as the number actually open at any given time, then processing time is usually improved. Specifying too large a number can increase processing time.

Parent topic: Improving Production Processing


Governor Settings

Restriction: This topic applies to Windows environments only.

Use the Governor to limit user activity on the XDB Server. The settings you enter for the Governor can affect performance. The more frequently the Governor checks a user's activities, the slower the XDB Server will run. There is a trade-off among frequency of checking, performance, and how long the Governor will wait before terminating a user session.

Every n seconds, the Governor checks the status of the various options against actual server activity. Because the monitoring is not constant, the limits you set could be slightly exceeded before the Governor ends the user session. For example, a user might actually make 104 engine calls before the Governor sees that the user was allowed only 100 engine calls. You can make the Governor more accurate by setting the frequency for checking higher (such as every 10 seconds as opposed to every 30 seconds). However, there is a performance penalty for more frequent checking. See the chapter Server Configuration Utility for information about setting the governor cycle time.

Parent topic: Improving Production Processing


Miscellaneous

Restriction: This topic applies to Windows environments only.

Some general guidelines that can improve processing speed include the following:

  • Close queries as soon as possible.
  • Commit transactions as soon as possible.
  • Change to dirty read (DR) when doing read-only operations where reading uncommitted changes are acceptable (some report writing, for example).
  • Balance work between the client CPU and the XDB Server CPU. For example, try to minimize ORDER BYs and aggregates. When writing COBOL programs, take advantage of the COBOL sort facility (which can process on the client's workstation) instead of using ORDER BY (which processes on the XDB Server).
  • To improve batch processing speed, consider turning off auto commit and forward logging if the process can be easily re-run.
  • When using embedded SQL in a program (any language), and you are executing many similar queries (same structure, but different values), use a PREPARE statement and multiple EXECUTE statements. For example, specify one PREPARE to set up the structure. Then EXECUTE repeatedly using different host variables for each.
Parent topic: Improving Production Processing


Reducing Disk I/O Contention

Restriction: This topic applies to Windows environments only.

The XDB Server allows a single database to span multiple physical devices, as long as no single object of the database spans more than one physical device. Thus, while no database object (table or index) can exceed the size of its physical storage device, objects can be spread among many devices to reduce I/O contention.

For example:

  • Table Placement.

    Ideally, each table should be stored on a different disk drive so queries requiring access to multiple tables will not create I/O contention on one disk. If there are more tables than disk drives, tables can be arranged such that those least likely to be accessed in the same query would be grouped together.

  • Index Placement.

    Generally, indexes should not be placed on the same disk drive as other information (tables or indexes) that will likely be accessed by a query that uses the index. Some indexes, however, can be placed with any other object without creating disk I/O contention.

    If an index is used for list prefetch or an index contains coverage for a particular table (all columns referenced for a particular table are within the index), the index will not be accessed at the same time as the base table. See the section Optimizing Query Processing for more information on list prefetch. Thus, all indexes used for list prefetch can be placed on any physical device because these indexes are accessed once, and only once, during the processing of a particular query. Likewise, an index which contains full coverage and is not involved in a join will be the only object accessed in a particular query, and thus could be placed on any physical device as well.

  • Temporary File Placement.

    Temporary files should be written to or read from a disk drive other than the one used to store data and indexes, or a drive containing data that is little used by most queries. Temporary files are created when the SQL engine performs a sort that overflows the configured Sort Space Size (as specified in the Configuration Utility). Operations that perform sorts include CREATE INDEX statements and SELECTS that involve DISTINCT, ORDER BY, UNION or GROUP BY.

The guiding principle in determining object location is to spread the workload evenly among the drive controllers and disk heads. If disk head movement can be kept to a minimum and drive controller usage evenly dispersed, optimal performance can be obtained. Table and index caching can improve performance even more. See the section Improving Production Processing for more information.

Given that the server stores database objects in separate files, tuning of database object locations can be done at any time. By simply copying the database object file to a different physical device and updating the stogroup or environment variable pathname for that particular database object, different space allocation strategies can be tested.

Paths for stogroups are maintained in the SYSIBM.SYSVOLUMES table. If a table space was created without specifying a stogroup, the table space's path will be that of the database (either ..\loc-path\dbname (Windows) or ../loc-path/dbname (UNIX) or the path of the stogroup that was used to create the database). For greatest flexibility, each table should be associated with its own stogroup (drive and path) when it is created.

Paths for indexes and other objects can be specified in environment variables in the server machine's configuration file. (See the chapter Environment Variables for more information.)

Guidelines on how to position tables, indexes and temporary files are provided on the following pages.

  • Positioning Tables
  • Positioning Indexes
Parent topic: Improving Production Processing


Positioning Tables

Restriction: This topic applies to Windows environments only.

Each database table can be associated with a physical device (drive and path) by using a stogroup and table space concept similar to that of DB2.

A stogroup is defined and associated with a physical device (drive and path). A database is then created using a particular stogroup. By default, any table subsequently created within that database is placed physically on the device (drive and path) specified by the database's stogroup.

To distribute tables to various disk drives, table spaces and stogroups are created. Each table space is associated with a stogroup, which in turn is associated with a drive and path. When a table is created, a table space can be specified, thus physically placing the table on the drive and path that is associated with the named table space.

For example, the following CREATE commands will create two stogroups (named STOR1 and STOR2) on two separate disk volumes (named MINE and YOURS). The UPDATE commands will define the disk drive and directory for each. (The directories must be created ahead of time using the operating system MAKE DIRECTORY (MD) command.)

CREATE STOGROUP stor1 VOLUMES (mine) VCAT xdb;
CREATE STOGROUP stor2 VOLUMES (yours) VCAT xdb;
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y" ,
        XdbVolPath = "d:\stor1\" (Windows) or
                "/stor1/" (UNIX)
    WHERE Volid = "mine";
UPDATE SYSIBM.SYSVOLUMES
    SET XdbPrimeVolPath = "y" ,
        XdbVolPath = "e:\stor2\" (Windows) or
                "/stor2/" (UNIX)
    WHERE Volid = "yours";
Note: The fields XdbPrimeVolPath and XdbVolPath are XDB Server extensions to the SYSIBM.SYSVOLUMES table. These columns do not appear in DB2.

To complete the example, you would use CREATE commands such as the following to specify storage locations for objects you create, in this case tables.

CREATE DATABASE xyz STOGROUP stor1;
CREATE TABLESPACE abc in DATABASE xyz
    USING STOGROUP stor2;
CREATE TABLE firsttable
    (fld1 SMALLINT, fld2 CHAR 1)
    IN xyz;
CREATE TABLE secondtable
    (fld1 SMALLINT, fld2 CHAR 1)
    IN xyz.abc;

The table FIRSTTABLE will reside on d:\stor1 (Windows) or /stor1 (UNIX) because it uses the stogroup defined for the database. The table SECONDTABLE will reside on e:\stor2 (Windows) or /stor2 (UNIX) because it uses the stogroup defined for the table space. If desired, you can create a separate table space for each table, each with its own associated stogroup/path.

To move a table to a different device, copy the *.tab file to the desired drive and path, and update the path name for the associated stogroup in the SYSIBM.SYSVOLUMES table. If the index files (*.idx and *.ptr) are stored with the tables and do not have special paths defined for them in environment variables, be sure to copy them along with the related table. (See the section Positioning Indexes for more information about moving indexes.)

See the SQL Reference for more information about the storage architecture (including examples) and the commands shown here.

Parent topic: Reducing Disk I/O Contention


Positioning Indexes

Restriction: This topic applies to Windows environments only.

An XDB index can be stored on a physical device different from the device where its related tables are stored by using an environment variable and an extension to the VCAT parameter of the CREATE INDEX command.

  • To store each index on its own path, use the XDB_index-name_ location-name environment variable to specify the path for storing each index. Then create each index using the VCAT NAME option on the CREATE INDEX command (using the index-name specified in the environment variable). If a qualifier is required for the index, you can enter a two-part name such as XDB_eric.orderidx_location1.
  • To store all indexes for a given location on the same path, use the XDBIDX_location-name environment variable to specify the path for storing all indexes for the location. Then create indexes for the location using the VCAT PATH option on the CREATE INDEX command.

For example:

  1. Enter the environment variable XDB_index-name_location-name in the computer's configuration file to specify a drive and path. You can create one or more index paths, such as:
    Windows:
    SET XDB_customerindex_location1= d:\indexes\customer
    SET XDB_ordersindex_location1= d:\indexes\orders
    UNIX:
    SET XDB_customerindex_location1= /indexes/customer
    SET XDB_ordersindex_location1= /indexes/orders
  2. Reboot.
  3. Create the indexes with the VCAT NAME parameter, as follows:
    CREATE INDEX customerindex ON customer(c_no)
    USING VCAT NAME;
    CREATE INDEX ordersindex ON orders(o_no)
    USING VCAT NAME;

    The VCAT NAME option causes the XDB Server to check the environment variable for the drive and path to use when creating the index. XDB index files are placed on the path associated with the environment variable for that particular index.

To move an index to a different device, simply copy the *.idx and *.ptr files to the desired drive and path, and change the path specification in the XDB_index-name_location-name or the XDBIDX_location-name environment variable. If the index path is not specified in an environment variable, then the index files must be in the same path as the related table.

See the CREATE INDEX command in the SQL Reference for more information about VCAT NAME and VCAT PATH. See the chapter Environment Variables for more information about the index environment variables.

Parent topic: Reducing Disk I/O Contention


Increasing Data Import Speed

Restriction: This topic applies to Windows environments only.

The SQLWizard Import Utility provides interactive and batch capabilities for transferring data from various formats into tables, including the DSNTIAUL format that can be generated from mainframe DB2 data. The DSNTIAUL format stores data in its internal DB2 representation, thus requiring little or no conversion before insertion into the database.

One additional feature is available in the Import Utility, to speed the processing of import data even more, called Direct Write. This option bypasses all referential integrity features normally imposed by the SQL engine and eliminates all engine overhead that would be encountered during normal record insertions. Instead, information is written directly to the table file. This method of data loading achieves maximum performance.

See the SQLWizard User's Guide for more about the Import Utility and the Direct Write Import feature.

Parent topic: Performance Tuning


Improving Performance During Object Creation

Restriction: This topic applies to Windows environments only.

XDB bufferpool caching is consolidated into a buffer management system. Instead of specifying separate cache sizes for table, index and dictionary buffers, a single unified cache size is specified for all accessed locations. The server also provides tuning options for improving the speed at which tables and indexes are created, as well as performance improvements that depend on the methods or options used during object creation. These include:

  • Specifying cache size
  • Using clustered indexes
  • Specifying the percentage of free space for indexes (read-only environments)
  • Specifying the blocking factor for duplicate Record IDs
  • Specifying sort buffer size
  • Buffer Management System
  • Clustered Indexes
  • Read-Only Environments
  • Block Size for Duplicate Record IDs
  • Sort Space Size
Parent topic: Performance Tuning


Buffer Management System

Restriction: This topic applies to Windows environments only.

The buffer manager is designed to enhance performance. The buffer manager uses sophisticated search and toss algorithms and is tightly integrated with the log manager. You configure buffer manager memory as a single buffer as opposed to specifying memory amounts for each database object type. This single buffer manager handles access to tables, indexes and dictionary information, and simplifies configuration by allowing more intelligent cache use. Memory is allocated by the cache manager at server start up and released at server shut down.

Use the Configuration Utility to specify the cache size at the server level, and to set the checkpoint frequency parameter, which controls periodic purging of logging system cache. See the chapter Server Configuration Utility chapter for information.

Parent topic: Improving Performance During Object Creation


Clustered Indexes

Restriction: This topic applies to Windows environments only.

In read-only environments, or for any table that does not have frequent inserts, it might be beneficial to define a clustered index. (You can have only one clustered index per table.) Specifying the CLUSTER option on the CREATE INDEX command gives you the option to later reorganize (re-order) the table's records into the same sequence as the related clustered index. For example:

CREATE INDEX pnoindex ON part (pno) CLUSTER

To reorganize the table's records into the same sequence as the clustered index's Record IDs, you must use the SQL COMPACT command with the CLUSTER BY INDEX option. For example:

COMPACT TABLE part CLUSTER BY INDEX pnoindex

Determining how often a table needs to be reorganized depends on how often records are added (inserted). The server leaves records in place when an update is issued (maintaining the order of records), but always inserts new records at the end of a table. A table that has many inserts would therefore need a reorganization more often than one that has few inserts.

Note:

If an update is made to the clustering key, the order of records in the table may be compromised. Use COMPACT to correct this situation.

See the CREATE INDEX and COMPACT command descriptions in the SQL Reference for more information about clustered indexes.

Parent topic: Improving Performance During Object Creation


Read-Only Environments

Restriction: This topic applies to Windows environments only.

In a read-only environment, you can create all indexes with the parameter PCTFREE 0. This parameter allows all index blocks to be filled to capacity, thus reducing the size and number of index levels. This reduction in size allows faster index creation and searching.

Parent topic: Improving Performance During Object Creation


Block Size for Duplicate Record IDs

Restriction: This topic applies to Windows environments only.

A blocking factor for duplicate key Record IDs can be specified using the DUPQTY parameter on the CREATE INDEX command. For best performance, the DUPQTY parameter for each index should closely resemble the index's distribution of duplicates. Indexes with high duplicate content should have high DUPQTY blocking factors, while more unique indexes should have low DUPQTY blocking factors.

Parent topic: Improving Performance During Object Creation


Sort Space Size

Restriction: This topic applies to Windows environments only.

The XDB Server performs sorts in a variety of situations, such as the processing of ORDER BY, DISTINCT, UNION and other clauses that appear in SQL statements. Creating or rebuilding indexes, and re-clustering with the COMPACT command requires a significant amount of sorting.

To enhance sorting operations, you can set the amount of memory that the XDB Server will attempt to acquire for this purpose (use the XDB Configuration Utility). You might want to specify a higher amount when creating indexes or compacting/reclustering tables, and set it back to a lower amount for normal operations. The higher the number, the faster large sorts can be processed. Also, larger amounts of data can be processed at a single pass, thus requiring fewer merges of data. However, if set too high relative to the number of concurrent sorts, users or available RAM, processing of queries can be slowed.

The amount you allocate for sorting is the amount of memory that will be made available for each sort request that the system receives. This is not a common pool for all users, but rather a per-sort amount. If a particular sort request does not require the full amount allocated, the excess is released back to the operating system.

Parent topic: Improving Performance During Object Creation


Administrative Performance Tools

Restriction: This topic applies to Windows environments only.

The following tools can help you determine how queries are being processed, how memory and cache are being used, and other performance-related information.

  • Virtual Statistics Tables
Parent topic: Performance Tuning


Virtual Statistics Tables

Restriction: This topic applies to Windows environments only.

Virtual statistics tables allow you to run SQL queries against a snapshot of server usage data. The kinds of information you can extract depends on the query you construct and run against these special tables. For example, you can create such information as:

  • The number of users currently logged in.
  • A list of logged in users; most recent first (or last).
  • A list of users who have more than one query open and in repeatable read isolation level.
  • Number of users doing joins in a particular location.

The Virtual Statistics Tables contain dynamic information about the state of the server. The tables are populated when they are queried to give you current information. Apart from their dynamic nature, they can be accessed just like normal system tables, using joins, conditional clauses, sorts, aggregate functions, etc. Some of the information in these tables duplicates the data displayed on the various server screens, while some display other kinds of information.

All of the Virtual Statistics Tables have the AuthID XDBSTAT and are created (when queried) in the DSNDB07 database. They have no indexes. The format and content of the Virtual Statistics Tables are defined in detail in the SQL Reference. Examples of queries that can be run against these tables to extract information are presented below and on the next page.

  • Example: Number of Users Currently Logged In
    SELECT COUNT(DISTINCT nodename)
    FROM xdbstat.userlist;
  • Example: List of All Users, Most Recent First
    SELECT * FROM xdbstat.userlist

    ORDER BY attachts desc;

  • Example: List of All Users Having Greater than One Query Open in Repeatable Read (RR)
    SELECT username||"@"||nodename
    FROM xdbstat.userlist a, xdbstat.userresources b
    WHERE a.username = b.username
      AND a.nodename = b.nodename
      AND b.numqds >1
      AND a.ilevel = "RR";
  • Example: Number of Users Doing Joins in System Location
    SELECT COUNT(*)
  FROM xdbstat.queryinfo
  WHERE locname = "SYSTEM"
    AND numtables > 1;
Parent topic: Administrative Performance Tools


Location Management

Restriction: This topic applies to Windows environments only.

This collection of topics provides information on configuring XDB Server and managing security, access, concurrency, locking, backup and recovery.

  • Security and Access Control
  • Transaction Processing
  • Concurrency Control
  • ROLLFORWARD Logging
  • Location Backup Options
  • Location Recovery and ROLLFORWARD
  • Distributed Processing
Parent topic: SQL Option Server Administration Guide


Security and Access Control

Restriction: This topic applies to Windows environments only.

Table access may be performed interactively, or through a program running in batch mode, or through a CICS or IMS transaction. In all cases it is necessary to control access to the system and to the data stored in table objects. The XDB Server controls access to the system using Authorization IDs (AuthIDs) and passwords. The XDB Server controls access to location objects using privileges. The XDB Server supports both explicit and implicit privileges.

  • Turning Security On
  • User Control
  • Logging On to the XDB Server
  • Ownership
  • Granting and Revoking Privileges
  • Authorization IDs
  • Special Registers
  • Security for Distributed Processing
  • Auditing System Usage
  • The DSNDB06 Database
  • The XDBACF Database
  • Additional Security Information
Parent topic: Location Management


Turning Security On

Restriction: This topic applies to Windows environments only.

The XDB Server provides various levels of security, including the ability to turn security on or off. When the XDB Server is initially installed, security is turned off by default. With security off, the system does not require a valid user ID or password to sign on to the system, nor does it check to see whether a user has privileges to perform an operation.

Security is turned on or off through the Configuration Utility. Turning security on or off is usually the responsibility of one of the database or system administrators, rather than of the individual user.

When you turn security on from a client you can also define a password enforcement level, which establishes rules for creating passwords, including password length, and permitted characters.

Once security is turned on you will usually be required to provide a valid user ID and password before you can connect to the system.

If security is on you must have authority to perform certain tasks.

Parent topic: Security and Access Control


User Control

Restriction: This topic applies to Windows environments only.

You use theSQL Wizard (Windows) or Interactive SQL Utility (UNIX) to add new AuthIDs and GroupIDs to the system, and modify existing information, including passwords The information is stored in the system catalog, as described below. The SQL Wizard (Windows) or Interactive SQL Utility (UNIX) can also be used to make an AuthID a member of a group, so that the AuthID has the privileges of the group.

Note: It is possible to temporarily deny an AuthID access to the system by turning off access authority through the SQL Wizard (Windows) or Interactive SQL Utility (UNIX) (or by editing the appropriate row of the SYSXDB.SYSACFUSERS table). This method keeps all privileges and memberships intact. See the chapter Multiserver Security for various ideas on setting up security when using multiple XDB Servers.
Parent topic: Security and Access Control


Logging On to the XDB Server

Restriction: This topic applies to Windows environments only.

If security is on, when you attempt to access the XDB Server or a local XDB Server, most programs will ask you to log on to the system. Usually you will see a window requesting a user name (or AuthID), followed by a password. When writing your own programs you can modify the log on procedure to meet your needs. This is described in the documentation for the language interface you are using.

Parent topic: Security and Access Control


Ownership

Restriction: This topic applies to Windows environments only.

Implicit privileges exist for the owner of an object. For example, the owner of a table has all privileges on that table, including the privilege to drop or alter it. The default owner of an object is the SQLID at the time the object is created. However, a different owner can be recorded by using an AuthID to qualify the object (in the form creator-authid.object-name) when creating the object. For example, using the table name smith.orders when issuing a CREATE TABLE statement creates a table called orders that is owned by the AuthID smith. For additional information on ownership of a particular object, see the appropriate CREATE statement in the command reference topic of this manual.

Note:

If security is turned off, the server uses the default SQLID of the client as the creator of any database objects, and the grantor of privileges.

Parent topic: Security and Access Control


Granting and Revoking Privileges

Restriction: This topic applies to Windows environments only.

Explicit privileges are conferred using the GRANT statement, and can be canceled using the REVOKE statement. Both are documented in detail in the command reference topic of this manual. Because the server provides a wide range of privileges covering database objects, components and activities, very precise control over data is achievable. For example, a user can be granted privileges to update, insert or delete rows of a table, to alter the structure of a table, to retrieve data from a table, and so on.

Privileges are generally associated with an object type. (For example, there are table privileges and database privileges.) In addition there are a number of special administration authorities used to confer comprehensive sets of privileges to certain types of users. See the chapter Security and Authority, and the topics on GRANT and REVOKE in the SQL Reference for more information. Included in these types of authorities are database administrator (DBADM), and super user authorities.

Information on privileges and authorities is stored in the system catalog tables. Each location stores privileges on objects within the location. In addition, the SYSTEM location stores information on administrator authorities for the system and for each location.

Parent topic: Security and Access Control


Authorization IDs

Restriction: This topic applies to Windows environments only.

An Authorization ID (AuthID) is a string from one to eight characters long. While AuthIDs may logically represent a person, an organizational group, or a function, the server only acknowledges the unique AuthID string itself as the owner of a privilege or database object.

The XDB Server supports three types of AuthIDs to administer security: Primary AuthID, GroupID and SQL AuthID (SQLID). Individual Primary AuthIDs can also be mapped to something called a SecondaryID, which replaces the Primary AuthID as soon as the user logs in to the XDB Server.

How an AuthID is used at a given time determines the type of the AuthID. A given AuthID may be the Primary AuthID for one process, the SQLID for another, and a GroupID for a third. In order for an AuthID to be used as a Primary AuthID, however, it must be registered through the SQL Wizard (Windows) or CREATE USER command in Interactive SQL (UNIX). See the chapters Security and Authority and Multiserver Security for a full treatment of security issues.

  • Primary AuthID
  • SecondaryID
  • Group or GroupID
  • SQL AuthID (SQLID)
Parent topic: Security and Access Control


Primary AuthID

Restriction: This topic applies to Windows environments only.

The Primary AuthID is the AuthID used to identify a process to XDB. Primary AuthIDs, and must be registered through the SQL Wizard (Windows) or Interactive SQL Utility (UNIX). They are typically used with a password to verify that the user is actually entitled to use that particular AuthID. Note that while a Primary AuthID is usually associated with an individual, it might be used by a group of people. For example, if several users will be using a system at different times, they might all be able to log on using the same AuthID and password.

Generally, it is recommended that each individual who accesses the system be assigned a unique AuthID and password. In this way the system is able to maintain more accurate records of who is actually using the system, and password security is more effective because the passwords are not shared. If security is off, the default Primary AuthID stored in the client configuration is used for internal system identification. This default can be modified through the Options Utility.

Parent topic: Authorization IDs


SecondaryID

Restriction: This topic applies to Windows environments only.

When the SQL Wizard (Windows) or Interactive SQL Utility (UNIX) is used to create a Primary AuthID (with its corresponding password), you are also allowed to specify a SecondaryID. If a SecondaryID is defined, it is used instead of the Primary AuthID to determine the actual privileges available to the session.

Once the user or process logs in, the value defined for the SecondaryID is used wherever the Primary AuthID would normally be used. It is as though the user or process had logged in using the SecondaryID instead of the Primary AuthID. For example, the SecondaryID appears in the special register USER, which normally contains the Primary AuthID of a session.

Note: The SecondaryID is not the same as the DB2 Secondary Authorization ID. The IBM method of defining multiple Secondary Authorization IDs and assigning them to Primary AuthIDs in RACF is similar to the GroupID concept.
Parent topic: Authorization IDs


Group or GroupID

Restriction: This topic applies to Windows environments only.

Often an individual using a database system to perform a function is just one of many people who are authorized to perform that function. Rather than granting the privileges necessary to perform the function to each person, the privileges can be granted to an AuthID associated with a group, known as a GroupID. A GroupID is a special identifier that can be assigned to one or more Primary AuthIDs. The privileges granted to the GroupID are available to every Primary AuthID to which the GroupID is assigned.

Individual users can still log in using their own Primary AuthID, but because they are members of a group (with specifically defined privileges), they also possess the group privileges. A Primary AuthID can be a member of several groups -- in which case the AuthID possesses the combination of privileges granted directly to the Primary AuthID, plus the privileges defined for each group to which the Primary AuthID belongs.

All GroupIDs are recorded in the SYSXDB.SYSACFGROUPS table in the SYSTEM location. The relationship between a Primary and GroupID is established in the SQL Wizard (Windows) or Interactive SQL Utility (UNIX) by making the Primary AuthID a member of the group. The concept of the GroupID in the XDB Server is analogous to the Secondary Authorization ID in DB2.

Parent topic: Authorization IDs


SQL AuthID (SQLID)

Restriction: This topic applies to Windows environments only.

The SQLID (also called SQL Authorization ID in DB2) is the AuthID used as the implicit qualifier for a table, view or index name in dynamic SQL statements, and for authorization checking of dynamic SQL statements. It also performs a special role as the default creator for CREATE statements, and as the grantor for GRANT statements.

Initially the SQLID is the Primary AuthID of a session. If a SecondaryID exists, the SQLID (and the Primary AuthID) is set to the SecondaryID. The SQLID in use by a particular user or process can be changed using the SET CURRENT SQLID statement, or through a Security User ExitThis applies to Windows environments (local development) only. . See Security User Exit for more information. See the SQL Reference for more information on the SET CURRENT SQLID statement. Usually the current SQLID must be the Primary AuthID, SecondaryID, or a GroupID of the session.

If security is off, the default Primary AuthID stored in the client configuration is used for internal system identification. This default can be modified through the Options Utility.

Parent topic: Authorization IDs


Special Registers

Restriction: This topic applies to Windows environments only.

The XDB Server provides two special registers to store Authorization ID information. These registers can be used like column names in SQL commands.

USER

This register stores the Primary AuthID for the process. Note that if a Secondary AuthID exists for the Primary AuthID, the Secondary AuthID will appear in this register instead. If security is off, the Primary AuthID set through the Options Utility will appear in this register.

Current SQLID

This register is initially set to the value of the register USER. This register reflects the execution of a SET CURRENT SQLID command.

Parent topic: Security and Access Control


Security for Distributed Processing

Restriction: This topic applies to Windows environments only.

Security for distributed processing is controlled by the AuthID privileges that have been granted in each location, regardless of which XDB Server controls the location. For a user to be able to access objects or data in a location other than his default location, his AuthID must have privileges at that other location for the objects he is accessing.

Parent topic: Security and Access Control


Auditing System Usage

Restriction: This topic applies to Windows environments only.

The system catalog table called SYSXDB.SYSUSAGE audits system usage. If the Utilization Monitor is turned on at a user's workstation (using the Options Utility), the table stores audit information for that user's sessions, including location start time, end time, Primary AuthID, number of illegal access attempts, etc. To track utilization for all users, the Utilization Monitor must be turned on at the server using the XDB Configuration Utility. This overrides the Utility Monitor settings of individual users.

Note that the SYSXDB.SYSUSAGE table exists in the DSNDB06 database of the SYSTEM location only. Because of the overhead involved in maintaining the utilization data, this table should be purged periodically. See the chapter Server Configuration Utility, or the Options User's Guide (Windows) for information on periodically purging the SYSXDB.SYSUSAGE table.

Parent topic: Security and Access Control


The DSNDB06 Database

Restriction: This topic applies to Windows environments only.

Every location contains a set of system catalog tables, stored in the DSNDB06 database. The system catalog contains the following security-related tables, which store various types of authorities and privileges:

  • SYSIBM.SYSDBAUTH (Database Authorization)
  • SYSIBM.SYSUSERAUTH (User Authorization)
  • SYSIBM.SYSTABAUTH (Table Authorization)
  • SYSIBM.SYSCOLAUTH (Column Authorization)

Provided that you have the necessary authority, you can query these tables in the same way you would query any data table.

Parent topic: Security and Access Control


The XDBACF Database

Restriction: This topic applies to Windows environments only.

The SYSTEM location contains a database called XDBACF (XDB Server Access Control Facility), which contains the following tables:

  • SYSXDB.SYSACFUSERS

    Contains a list of all users, including AuthIDs and Passwords for each user.

  • SYSXDB.SYSACFGROUPS

    Contains a list of all GroupIDs that have been defined.

  • SYSXDB.SYSACFMEMBERS

    Contains a list of users and the GroupIDs they are authorized to use. Each user (Primary AuthID) may have several entries, one entry for each group ID that the person is authorized to use.

See the SQL Reference for detailed information about the contents of these tables.

Parent topic: Security and Access Control


Additional Security Information

Restriction: This topic applies to Windows environments only.

For more information on security, consult the references listed in the following table:

Document Topics
SQL Reference
  • SQL Commands
  • System Tables
The on-line help or the SQLWizard User's Guide
  • User Administration
Server Administration Guide
  • Configuration Utility
  • Security and Authority
  • Server-to-Server Connectivity
  • Multiserver Security
  • Security User Exit
  • AuthID List User Exit
Parent topic: Security and Access Control


Transaction Processing

Restriction: This topic applies to Windows environments only.

A transaction is an atomic sequence of database operations. When a transaction is executed, either all or none of the operations are performed. The logging system automatically retains all table changes for any transaction in progress until that transaction is either rolled back or committed.

  • Committing a Transaction
  • Rolling Back a Transaction
Parent topic: Location Management


Committing a Transaction

Restriction: This topic applies to Windows environments only.

When all of the data changes in a transaction are complete, commit the transaction using the COMMIT command. The effect of the COMMIT command is to request the system to accept permanently all of the data changes made by the transaction. The point of time at which the COMMIT operation occurs is known as a commit point. Normal exit from an XDB utility or application program causes the system to perform an implicit COMMIT. Alternatively, setting the autocommit feature causes all commands to automatically commit upon execution. See the section Autocommit for more information.

Parent topic: Transaction Processing


Rolling Back a Transaction

Restriction: This topic applies to Windows environments only.

Sometimes an unacceptable condition is detected by a user or by the system after some changes have been made to the data. Additionally, two or more concurrently executing transactions could enter into a deadlock waiting for each other to release locked objects, and the system may force one of the transactions to abort. In all cases, all changes made to the data by an aborted transaction must be reversed in order to maintain the data in a consistent state. If the system detects a problem that requires the transaction to abort, it automatically reverses all the changes made to the data by the transaction. If the transaction decides to abort itself, it is the responsibility of the transaction to request a rollback of all changes it made to the data.

When a transaction is to be aborted, all of the changes made to the data during the current transaction must be undone. The ROLLBACK command is provided for this purpose. The effect of ROLLBACK is to undo all of the changes made to the data since the transaction began. Starting the server after a system failure triggers an automatic ROLLBACK of any incomplete transaction.

Note:

The XDB Server does not roll back or recover the Data Control Language (DCL) commands such as GRANT and REVOKE; or utility commands such as SET and DROP TABLE. When working in a production environment, it is recommended that you back up your location before and after such commands.

A program may contain multiple transactions. The first transaction begins when the program starts, and ends with either a ROLLBACK or COMMIT command. Subsequent transactions begin with the last COMMIT or ROLLBACK command, and end with the next COMMIT or ROLLBACK command.

Parent topic: Transaction Processing


Concurrency Control

Restriction: This topic applies to Windows environments only.

Concurrency is the ability for multiple transactions to access table resources simultaneously. An integral consideration of data consistency is ensuring that changes made by one user do not negatively affect other users.

Locking is the method used to address both data consistency and concurrency requirements. A trade-off exists between database consistency and concurrency. It is necessary for the locking scheme to strike some sort of balance between consistency and concurrency.

The XDB Server controls concurrency by implementing locking schemes with choices of isolation levels. Each user may select the desired level of data locking.

  • Locking
  • Isolation Levels
  • Lock Compatibility
  • Timeout and Deadlock
  • Autocommit
Parent topic: Location Management


Locking

Restriction: This topic applies to Windows environments only.

Locks have three basic attributes: object, mode and duration. Lockable objects include records and tables. Lock modes are shared and exclusive. Duration refers to the length of time a lock is held. Duration is dependent on the type of object locked, the lock mode, and the isolation level currently established.

The XDB Server supports automatic record level locking (R locks). Programs never have to request record level locks explicitly. The server can lock one record at a time, rather than a minimum of a page or block of data, which might result in reduced concurrency among users. In addition to record level locking, the XDB Server provides table locking. Table level exclusive (TX) and table level shared (TS) locks are acquired by using the LOCK command.

The server provides both shared and exclusive locks. In general, shared locks (S locks) are placed on an object when the object will be read only (not updated). This type of lock prevents any other transaction from changing the locked record for the duration of the lock. Other transactions may still read the locked record. The release of shared locks depends on the type and isolation level of the lock.

Exclusive locks (X locks) must be acquired before an object can be changed. When an exclusive lock is held on an object, no other transaction can reference the locked object. Exclusive locks are generally held until the end of the transaction that owns them (or until the transaction issues a COMMIT or ROLLBACK command).

Intentional table level locks will also be automatically acquired by the server. Before any shared record lock is granted, the server first places an intentional share lock (IS lock) on the table. Similarly, the server places an intentional exclusive lock (IX lock) on the table before an exclusive record lock is granted.

Parent topic: Concurrency Control


Isolation Levels

Restriction: This topic applies to Windows environments only.

The isolation level in effect determines the manner in which locks are acquired and released by the system. The XDB Server provides the following isolation levels:

  • Level 1: Exclusive Use (EU). At Level 1 the system locks an entire location for the exclusive use of the current user. In essence, the system is operating in single user mode. This level of isolation should be used when performing such tasks as compacting the location, backing up the location, and recovering the location.
  • Level 2: Repeatable Read (RR). Level 2 guarantees that records read will not have been changed by another transaction from the time a lock is acquired on an object until the end of the transaction; that is, at this level of isolation all locks are held until the transaction is either committed or rolled back. This level provides a high degree of consistency and a relatively low degree of concurrency.
  • Level 3: Cursor Stability (CS). Cursor Stability is the default server isolation level. Under Level 3 exclusive locks are retained until commit or roll back, but record level share locks are released when the cursor leaves the record. The system automatically handles the release of all record locks types. This level of isolation provides less consistency and more concurrency than the RR level of isolation.

    The CS level of isolation is often used in combination with autocommit off by interactive applications where users may browse through records one at a time. In such an environment it is only necessary to maintain a lock on a record if the record is modified in some way. After the user moves to the next record, locks on unchanged records are released.

    Level 4: Lock Current (LC). At Level 4 the system acquires a lock when a record is referenced, but holds the lock only until the cursor moves to the next record. Note that exclusive locks are also released when the cursor moves to the next record; therefore this level should be used for read-only transactions, or used only when autocommit is turned on. Autocommit generates a commit command after each update takes place.

    Level 5: Dirty Read (DR). At Level 5 the system acquires no locks on a referenced record. The transaction operates in read-only mode and cannot make changes to database objects. This isolation level can be used to generate reports without delays while the system attempts to lock records. Records read at this isolation level may reflect changes made, but not committed. Note that these changes may be subsequently rolled back.

    Level 6: Snapshot Read (SR). At Level 6 a read-only snapshot of the data is made at the time of execution. No locks are held on the data, so other users can access and make changes to the data without waiting for the transaction working at SR to complete. The transaction working at SR isolation level is assured that the data it is working with will remain the same for the duration of the transaction. The SR transaction cannot make changes to the data.

The locks described above are automatically acquired by the system. At any isolation level it is also possible to explicitly request and release table level locks using the LOCK and UNLOCK commands. Table level locks may also be automatically acquired by the system if a command that affects the table definition is issued (for example, ALTER, RENAME, CREATE INDEX). Table level locks that are held at a commit point are automatically released, therefore it is not necessary to explicitly release a table level lock.

The default level of isolation for the XDB Server is CS (Cursor Stability). In order to ensure a different level of isolation it is necessary to issue a command to reset the isolation level. The startup isolation level is set through the Options Utility. You can also temporarily change the isolation level by using the SET ISOLATION command (described in this manual) and by using the WITH clause (available in DB2 4.x and beyond) on certain SQL statements.

It is important to consider how different users' isolation level settings impact the integrity of the database. The database administrator must coordinate the isolation level requirements for all users, and define those cases in which exceptions will be permitted.

Parent topic: Concurrency Control


Lock Compatibility

Restriction: This topic applies to Windows environments only.

A transaction can acquire a lock on an object that is already locked only if the existing lock is compatible with the lock the transaction is trying to acquire.

In the lock compatibility matrices in the following two tables, table locks are exclusive (TX) or shared (TS), record locks are exclusive (RX) or shared (RS). In addition, IX and IS table locks are set by the system automatically when RX and RS locks are placed on records of that table.

 | TX | TS | IX | IS
TX | No | No | No | No
TS | No | Yes | No | Yes
IX | No | No | Yes | Yes
IS | No | Yes | Yes | Yes
 | RX | RS
RX | No | No
RS | No | Yes

For example, assume two transactions, a and b, want to access the part table. When transaction a reads a record in the part table, the system must acquire an RS lock on the record, and implicitly acquires an IS lock on the part table. If transaction b tries to read the same record, there is no conflict, so transaction b will be granted an RS lock on the record and an IS lock on the part table. If transaction b tries to update the current record, a conflict occurs because the RS lock held by transaction a, and the RX lock required by transaction b are incompatible.

The deadlock avoidance mechanism takes one of the following actions:

  • Permits transaction b to wait a user-defined period of time, during which the system periodically attempts to acquire the lock. If, by the end of the timeout period, the system has not acquired the RX lock for transaction b, the transaction must be rolled back and retried (if desired).
  • Withdraws the lock request immediately if it is determined that granting it might possibly result in a deadlock situation. Transaction b must be rolled back and retried (if desired).

However, if transaction b tries to update a different record in the part table, the system will acquire an RX lock on the record, and an IX lock on the table, and transaction b can be completed successfully. If transaction a had explicitly requested a TS lock on the part table, transaction b would not be allowed to update any record in the table, since both TX and IX locks are incompatible with a TS lock.

Parent topic: Concurrency Control


Timeout and Deadlock

Restriction: This topic applies to Windows environments only.

The timeout period refers to the length of time a transaction waits to acquire a lock before it gives up. A deadlock occurs when two or more transactions are waiting for each other in a cyclic fashion.

When a transaction is waiting for a resource that is locked by another transaction, it waits until one of the following occurs:

  • The lock is granted.
  • The end of a timeout period occurs.

It is the responsibility of the program to roll back changes already applied, thereby releasing all locks. When a lock is not granted, a lock error message is returned to the program.

If the timeout period concludes before a lock is acquired, the transaction may perform other processing before attempting again to acquire a lock. Alternatively, it may roll back the entire transaction and retry it later. It is the responsibility of a program to retry a transaction that has been rolled back.

The timeout period is measured in seconds and can be set in the client configuration.

Parent topic: Concurrency Control


Autocommit

Restriction: This topic applies to Windows environments only.

To shorten the length of time a lock is held and to reduce network overhead while maintaining a reasonable degree of database consistency, configure the system to automatically commit a command as soon as it is executed. Autocommit increases concurrency by immediately committing commands that change tables within a location. Since the transaction is a single command long, the use of ROLLBACK is limited to occasions when a failure occurs that automatically triggers a rollback. When using autocommit, it is important to remember that while you cannot explicitly roll back a transaction, the system is able to roll back a failed command.

For example, under autocommit, if you issue an UPDATE command from within the SQL Wizard (Windows) or Interactive SQL (UNIX), the command is executed and immediately committed if successful. If you issue a ROLLBACK command at this point, it will not roll back the completed UPDATE command; on the other hand, other programs do not wait for you to either explicitly commit the update command or exit from the SQL Wizard (Windows) or Interactive SQL (UNIX) before they can acquire locks on the records you just updated.

If a system failure occurs during the UPDATE command (for example, the power goes off), the partially completed update command will be automatically rolled back when the system restarts. If the server discovers that an application node has failed, the server automatically rolls back any incomplete transaction belonging to the failed node.

When working at the LC (Lock Current) isolation level, autocommit should be turned on. The combination of the LC isolation level and autocommit are particularly useful in interactive processing. When a record is updated, inserted or deleted, the change is immediately committed, and all locks released.

Autocommit can be turned on or off through the Options Utility. Autocommit may also be turned on or off temporarily using the SET AUTOCOMMIT command.

Parent topic: Concurrency Control


ROLLFORWARD Logging

Restriction: This topic applies to Windows environments only.

The logging system tracks all changes made to each location's tables since the last time the XDB Server BACKUP command was used on the location (or since the last time logging was reset for the location). The logging system maintains a separate series of log files for each location.

In the event of a serious system failure, such as a disk crash or other media failure, you can restore a backup copy of the location's tables and then issue the ROLLFORWARD command to apply the contents of the location's current log files to the restored location tables. These actions bring your tables up to date (to the time just prior to the system failure).

By default, the Forward Log path (where location log files are stored) is the same as your location path. You can and should change the name and path for your location log file storage. Ideally, log files should be placed on a different physical device than the location tables they are logging. This precaution protects against an independent media failure such as a hard disk crash.

You can change the current log path for a location by using the SET LOG command. See the SQL Reference for more information on the SET LOG command.

Location logging should be reset after using the BACKUP command to archive a location and its log files. If you use a different method to create your backups (such as an operating system BACKUP command), you can reset the location log files by deleting the current log files from your operating system prompt.

The logging system automatically creates a new series of location log files when you commence entering transactions. See the chapter Backup and Recovery for more information.

Parent topic: Location Management


Location Backup Options

Restriction: This topic applies to Windows environments only.

The BACKUP command operates at the location level, including all paths and files for all tables in the location. Likewise, the ROLLFORWARD command, which applies the current series of location log files to a backup copy of the location data, also operates at the location level. If you have more than one database in a location and only one of those databases needs to be restored and rolled forward, you still have to restore and roll forward all of the databases in the location.

If you use an operating system backup command or other backup utility, and you intend to use the location's log files to reconstruct the data for that location, be sure that you have backed up all the files in all the paths that are defined for the location, including stogroup paths, if any. Also, be sure to reset the location logging after each backup is completed.

If your location backups are infrequent or if activity is high and the number of log files grows rapidly, you may wish to back up your location log files periodically to ensure that logging is available if you need it. Use an operating system BACKUP command or utility to back up the log files.

  • BACKUP Command
  • Other Backup Options
Parent topic: Location Management


BACKUP Command

Restriction: This topic applies to Windows environments only.

The BACKUP command creates copies of all files that reside in the paths defined for the specified location, including paths associated with storage groups.

You can use the BACKUP command only if the location being backed up is not currently in use by you or another user. You can use the BACKUP command with or without using the roll forward logging feature.

When backing up a location you can specify whether you want to back up index files. If you need to restore a location from a backup that did not include the index files, you will need to rebuild the indexes using COMPACT LOCATION AND INDEX command.

BACKUP copies the files to the device and path you specify. This may be a tape drive, a file server, or a different disk drive. Use the Restore Utility to return the archived location to your hard disk.

Note: BACKUP does not copy files onto multiple diskettes. If the contents of the location are too large to fit on one diskette, use another backup option.

See the chapter Backup and Recovery and the SQL Reference for additional information on the BACKUP command.

Parent topic: Location Backup Options


Other Backup Options

Restriction: This topic applies to Windows environments only.

Most commercially available archival utilities can be used to backup locations. When using a backup utility, it is important to keep in mind that you must backup the contents of all directories for the entire location, including stogroup paths (if any) and including all subdirectories. This last point is important since the server may have duplicate file names in different directories, which need to be kept separate on the backup device.

Parent topic: Location Backup Options


Location Recovery and ROLLFORWARD

Restriction: This topic applies to Windows environments only.

If you are maintaining location log files and have made periodic backups of your location, you can usually recover from system failure by restoring the backup copies of the location files (this process copies the backed-up files into their proper directories and subdirectories in the location). Replay the current location log files against the restored location by using the ROLLFORWARD command. See the chapter Backup and Recovery for a more detailed description of this process.

Note: ROLLBACK and ROLLFORWARD do not recover Data Control Language (DCL) commands, such as GRANT and REVOKE, and utility commands, such as SET.
Note: Do not compact tables (or locations) before replaying log files. The log files must be applied to a non-compacted data object. Once a compact is performed, the current set of location log files is useless.
Parent topic: Location Management


Distributed Processing

Restriction: This topic applies to Windows environments only.

Distributed processing is an integral part of the XDB Server architecture. It allows a session concurrent access to multiple locations. In conjunction with the multilocation architecture, support is provided for three-part object names (location-name.authid.object-name). These features allow users to access data outside of their default locations (restricted only by the security measures that have been implemented).

In a LAN environment, the locations can be distributed across various volumes on a network simply by specifying the desired path name when creating the location. Support of stogroups provides further opportunity to physically organize databases and tables (using table spaces) on specific volumes. Installation of XDB Link adds to the distributed processing capabilities by providing a transparent connection to a mainframe DB2 location using the Distributed Relational Database Architecture (DRDA) protocol.

  • Distributed Unit of Work (DUW) Processing.
  • Remote Unit of Work (RUW) Processing - XDB Locations
  • Remote Unit of Work (RUW) Processing - DB2 Locations
  • Server-to-Server Connectivity
  • DSNDDF Communications Database
Parent topic: Location Management


Distributed Unit of Work (DUW) Processing.

Restriction: This topic applies to Windows environments only.

Use DUW processing to remain connected to your default (or current) location, and have the ability to execute a limited range of statements on data objects in another local or remote location. You can use INSERT, UPDATE, DELETE, and SELECT commands with three-part object names, while OPEN, FETCH and CLOSE commands are valid for DUW processing with embedded SQL.

An application simply uses the fully qualified name (location-name.authid.object-name) of a table or view that resides in the other location. Based on information in the system catalog tables on the current XDB Server, the request is sent to the appropriate XDB Server and data is returned.

Note:

Use of the DUW option requires that you reference no more than one location per SQL statement. If you need to work with objects in several locations, you must use multiple statements, one location per statement.

The XDB Server does not currently support two-phase commit or distributed queries.

Parent topic: Distributed Processing


Remote Unit of Work (RUW) Processing - XDB Locations

Restriction: This topic applies to Windows environments only.

Use RUW processing to work with locations and applications at a local or remote location other than your normal (default) location. Remote locations run on another XDB Server on your network. With RUW, you are actually working at the other location. That is, the location you connect to becomes your current location.

You can specify either a local or remote location with which you wish to work by issuing the CONNECT command in embedded SQL, or the SET LOCATION TO command in interactive SQL.

Parent topic: Distributed Processing


Remote Unit of Work (RUW) Processing - DB2 Locations

Restriction: This topic applies to Windows environments only.

This form of distributed processing operates in the same manner as the RUW for locations. If you use the SET LOCATION TO command in the SQL Wizard (Windows) or Interactive SQL Utility (UNIX) to attach to an XDB Link location, you can get back to a location through that same the SQL Wizard (Windows) or Interactive SQL Utility (UNIX) session from within that the SQL Wizard (Windows) or Interactive SQL Utility (UNIX) session. Within embedded SQL, a CONNECT RESET command can be used to return to a location.

XDB Link plus a few special entries in the XDB SYSTEM location's DSNDDF database are required to allow access to the mainframe DB2 Location. XDB Link provides transparent access to objects on the mainframe as though the mainframe were just another location on the server. The Distributed Relational Database Architecture (DRDA) is used in this configuration.

Parent topic: Distributed Processing


Server-to-Server Connectivity

Restriction: This topic applies to Windows environments only.

Server-to-server connectivity allows a client accessing one XDB Server to access data in a location controlled by another XDB Server in a distributed environment. Server-to-server connectivity works only with SQL Data Manipulation Language (DML) statements, such as INSERT, UPDATE, DELETE and SELECT. Location access is done interactively, either by using a three-part-name (location-name.authid.object-name) or alias, or by using the SET LOCATION command.

Server-to-server connectivity eliminates the need to change the client configuration settings to access a remote XDB Server or DB2 location (through XDB Link). In order to access a remote location, a system administrator must maintain the system tables to reflect known locations and server names. See the chapter Server-to-Server Connectivity for further information on using server-to-server connectivity for RUW and DUW, and for server-to-server setup options.

Parent topic: Distributed Processing


DSNDDF Communications Database

Restriction: This topic applies to Windows environments only.

Information about the local and remote locations that are accessible to users is stored in a communications database called DSNDDF in the SYSTEM location. This database contains the tables described below.

Data is entered automatically in the appropriate tables whenever a location is created with the SQL CREATE command, the XDB Server menu system, or the XDB conversion program. If necessary, you can edit these tables.

  • SYSXDB.SYSGATEWAY

    Contains information needed by XDB Link for accessing DB2 locations on a mainframe. For more information about XDB Link, see the XDB Link User's Guide.

  • SYSXDB.SYSGOVERNOR

    Contains information on the type of activities that can be performed by certain users during certain periods. See the SQLWizard User's Guide or on-line help for further information on governor features.

  • SYSXDB.SYSLOCALS

    Contains information about each "local" location, including all locations defined under the XDB Server to which this SYSXDB.SYSLOCALS table belongs.

  • SYSIBM.SYSLOCATIONS

    Contains information about all locations that are accessible for DUW and RUW processing including local locations in SYSXDB.SYSLOCALS, plus remote locations accessible using server-to-server connectivity and XDB Link. With DUW and RUW processing, any object that is referenced by a three-part name (location-name.authid.object-name) or a CONNECT command must have its location defined in this table. Remote locations may include mainframe DB2, DB2/VM or SQL/400 locations, or locations running under another XDB Server.

  • SYSIBM.SYSLUMODES

    Contains information needed by XDB Link for accessing DB2 locations. Each row provides mainframe VTAM with conversation limits for a specific LUNAME/MODENAME combination.

  • SYSIBM.SYSLUNAMES

    Contains LUNAME information needed by XDB Link and server-to-server connectivity. The table defines the name of each XDB Server if using server-to-server connectivity, or the name of the mainframe Logical Unit (LU) for one or more accessible DB2 systems if using the XDB Link. The names identified here are the same names identified in the LINKNAME column of the SYSIBM.SYSLOCATIONS catalog table.

  • SYSIBM.SYSMODESELECT

    Maintained for compatibility with DB2. Not used on XDB Server, but on the mainframe contains information for associating a MODENAME with any conversations created to support an outgoing SQL request.

  • SYSIBM.SYSUSERNAMES

    Contains user information needed by XDB Link for processing requests to and from a DB2 location, and for processing requests to other XDB Servers using XDB's server-to-server connectivity. Each row is used to carry out either an outbound or inbound ID translation or both.

Parent topic: Distributed Processing


Environment Variables

Restriction: This topic applies to Windows environments only.
  • XDB_ index-name_ location-name
  • XDBCP
  • XDBIDX_ location-name
  • XDBINI
  • XDBNETINI
  • XDBRIDPOOL
  • XSRVCFG
Parent topic: SQL Option Server Administration Guide


XDB_ index-name_ location-name

Restriction: This topic applies to Windows environments only.

XDB_index-name_location-name is an optional environment variable that is used in conjunction with the VCAT NAME option of the SQL CREATE INDEX command. To physically locate each index on a specific storage device (drive and path), specify a path in the [Server] topic of the xdb.ini file for each index/location combination, and subsequently create the index using the VCAT NAME option.

The format for this environment variable is:

XDB_index-name_location-name=drive-and-path

If a qualifier is required, enter a two-part name for the index-name, such as:

Windows:
XDB_eric.orderidx_location1=m:\anypath
UNIX:
XDB_eric.orderidx_location1=/anypath

For example, to create and store an index called customerindex on d:\indexes\customer (Windows) or /indexes/customer (UNIX) and another index called ordersindex on e:\indexes\orders (Windows) or /indexes/orders (UNIX) (both for tables in the TUTORIAL location), you would make two entries in the xdb.ini file, and issue two SQL CREATE INDEX commands as follows:

  1. In the [Server] topic of the xdb.ini file, enter the following:
    Windows:
    XDB_customerindex_tutorial=d:\indexes\customer XDB_ordersindex_tutorial=e:\indexes\orders/indexes/orders
    UNIX:
    XDB_customerindex_tutorial=/indexes/customer XDB_ordersindex_tutorial=/indexes/orders
  2. Using the USING VCAT Index Options under the Create/Alter Table function in SQL Wizard (Windows) or Interactive SQL or Batch SQL (UNIX), issue the following commands:
    CREATE INDEX customerindex ON customer(c_no)
    USING VCAT NAME;
CREATE INDEX ordersindex ON orders(o_no)
    USING VCAT NAME;
Parent topic: Environment Variables


XDBCP

Restriction: This topic applies to Windows environments only.

To support a number of non-American code page character sets, set the parameter XDBCP=codepage in the xdbsrvco.ini file [environment] group. Codepages that are directly supported are:

Number | Name
850 | MS-DOS Latin1 (used in the entire European Community except Greece)
863 | MS-DOS French Canada
865 | MS-DOS Nordic
942 | Japanese
949 | Korean
437 | MS-DOS Latin US
860 | MS-DOS Portuguese
Parent topic: Environment Variables


XDBIDX_ location-name

Restriction: This topic applies to Windows environments only.

XDBIDX_location-name is an optional environment variable that is used in conjunction with the VCAT PATH option of the SQL CREATE INDEX command. To physically locate all indexes for a location on a specific storage device (drive and path), specify an index path in the xdb.ini file for each location, and subsequently create indexes using the VCAT PATH option.

The format for this environment variable is:

XDBIDX_location-name=drive-and-path

For example, to create and store all indexes for the TUTORIAL location in the path d:\indexes\tutorial (Windows) or /indexes/tutorial (UNIX), you would:

  1. Make the following entry in the XDB Server machine's configuration file:
    XDBIDX_tutorial=d:\indexes\tutorial/indexes/tutorial
  2. Using the USING VCAT PATH Index Option under the Create/Alter Table function in SQLWizard (Windows) or Interactive or Batch SQL (UNIX), issue the following command:
    CREATE INDEX customerindex ON customer(c_no)
    USING VCAT PATH;
Parent topic: Environment Variables


XDBINI

Restriction: This topic applies to Windows environments only.

The XDBINI variable specifies the directory where the xdb.ini file lives; this file contains both client and server side information for the SQL Option.

Parent topic: Environment Variables


XDBNETINI

Restriction: This topic applies to Windows environments only.

The XDBNETINI variable specifies the directory containing the xdbnet.ini file is; this file contains the TCP/IP information necessary so SQL Option client-side software can speak to a XDB server.

Parent topic: Environment Variables


XDBRIDPOOL

Restriction: This topic applies to Windows environments only.

XDBRIDPOOL is an optional environment variable that is specified in the [Server] topic of the xdb.ini file to enhance performance of the Query Optimizer.

The Query Optimizer may at times choose to use an algorithm called list prefetch when analyzing data access paths. This algorithm entails retrieving Record IDs (RIDs) from an index file and then sorting them. List prefetch is invoked when multiple index access is required or when data needs to be retrieved in physical order.

The format for this environment variable is:

XDBRIDPOOL=number-of-kilobytes

where number-of-kilobytes is the amount of memory to allocate for each statement's RID pool. The maximum size that can be specified is dependent on the amount of system memory that is available.

The RID Pool is the buffer that the server uses to store RIDs of this type. The default RID pool size is 512K per query. Since each RID contains 4 bytes, this default RID pool size can hold a maximum of 131,072 RIDs. If the RID pool size is exceeded, the list prefetch algorithm may be aborted, severely hampering performance.

The number of RIDs that can possibly enter the RID pool is determined by the selection criteria defined by a particular WHERE clause. A good rule of thumb for estimating an appropriate RID Pool Size is to determine the number of records that exist in the largest table, and then use the following formula:

RID Pool Size = (max records) * (.20) * (4 bytes per RID)

For example, a table containing 3,000,000 records would have an optimal RID Pool Size determined as shown below:

3,000,000 * .20 * 4 = 2,400,000 bytes

Converting this to kilobytes, we get:

2,400,000 / 1024 = 2344K

This RID Pool Size would allow an index condition that qualifies up to 20% of the table's rows to fit into the RID Pool.

The following XDBRIDPOOL environment variable setting would make available a 2400 kilobyte RID Pool per statement.

XDBRIDPOOL=2400
Parent topic: Environment Variables


XSRVCFG

Restriction: This topic applies to Windows environments only.

XSRVCFG is an environment variable (an entry in the xdb.ini file) that indicates the drive and path on which the XDB Server configuration files reside:

  • The crvconfg.xdb file contains configuration parameters for the XDB Server as entered via the XDB Server Configuration utility.
  • The xdbsrvco file contains settings for the XDB Server logging and checkpoint features.
  • The xdbnet.ini file contains information for XDB Servers and clients who use TCP/IP.

The [Server] topic of the xdb.ini file contains various settings for the XDB Server, including the environment variables described in this chapter. If a copy of SQLWizard is on the same machine, it also uses xdb.ini to store configuration settings (applies to Windows environments only).

These files are usually located in the directory where the XDB Server software is installed. The XSRVCFG environment variable is entered in the [Server] section of the xdb.ini file when you install the XDB Server.

The format for this environment variable is:

Windows:
XSRVCFG=drive-and-path
UNIX:
XSRVCFG=path

For example, if the XDB Server and its configuration files are located on the \xdbnt (Windows) or /xdbnt (UNIX) directory of the XDB Server machine (on theC drive if a Windows machine), the XSRVCFG environment variable would be entered as follows:

Windows:
XSRVCFG=c:\xdbnt
UNIX:
XSRVCFG=/xdbnt
Parent topic: Environment Variables


Server Files

Restriction: This topic applies to Windows environments only.
  • Location and Database Files
  • Configuration Files
  • Help, Message and Error Files
Parent topic: SQL Option Server Administration Guide


Location and Database Files

Restriction: This topic applies to Windows environments only.

Each location consists of a number of files and subdirectories to store location data, system catalog tables, and user-defined tables and indexes for each database in the location. Storage group (stogroup) directories might be used to organize the physical placement of some files. See the Data Storage Architecture for more information.

File Name | Description
numeric. * | Most file names are derived from the first 8 characters of their corresponding objects (location name, table name, etc.) If the first 8 characters do not produce a unique name, a random 8-digit number is generated by the XDB Server and is used as the file name.
location.ddt | Contains information on the tables in a location.
location.ddf | Contains information on the columns in tables in a location.
location.ddi | Contains information on indexes in a location.
location.ddv | Contains information on the XDB Server version.
sys*.tab | XDB Server system catalog tables. (Due to similarity of names, many system tables carry a numeric filename as explained above.)
table.tab | Contains the data stored in an XDB Server table.
index.idx | Contains index values for indexed columns.
index.ptr | Contains record pointers to duplicate occurrences of values. (Contain 0 bytes if the index is unique.)
Parent topic: Server Files


Configuration Files

Restriction: This topic applies to Windows environments only.

There are a number of files used to store the configuration items you specify for your XDB Server operating environment. The stored configuration data are used as needed by the various XDB Server programs and utilities you run. These files generally reside in the Directory.

Other configuration files, such as config.sys, autoexec.bat (Windows) or *.ini (all platforms) sometimes contain XDB information as well. See the appropriate installation guide for specific information.

File Name | Description
srvconfg.xdb | XDB Server environment configuration file. The environment variable XSRVCFG points to the location of this file.
product.ver | Contains version number for installed version of product. To see all .ver files found in the current directory, enter the command XDBVER on an operating system command line.
sort-sequence.seq | Pre-defined user sort sequence files that can be used in place of our standard ASCII or EBCDIC sort sequences.
Parent topic: Server Files


Help, Message and Error Files

Restriction: This topic applies to Windows environments only.

Most XDB Server modules have help, message and error files associated with them. Generally, these files have the same file name as the module to which they refer. The extensions of these files use the following conventions:

  • Help and Message files end with the extension .hlp or .xsg.
  • Error files end with the extension .err or .xrr.

See the Error Messages bookonline help for a list and description of messages displayed by XDB Server software.

Parent topic: Server Files


Troubleshooting

Restriction: This topic applies to Windows environments only.

This collection of topics describes troubleshooting scenarios and solutions for XDB Server, and accessing trace information.

  • Scenarios and Solutions
  • Tracing
Parent topic: SQL Option Server Administration Guide


Scenarios and Solutions

Restriction: This topic applies to Windows environments only.

The following sections describe several trouble scenarios and their possible solutions.

  • My client cannot find my xdbnet.ini file.
  • My server-to-server TCP/IP connections are not working.
  • I get the message: Can't assign requested address bind() = 10049 when I try to bring up my XDB Server with TCP/IP threads.
  • I need to verify that a particular IP address is correct when configuring TCP/IP connections.
Parent topic: Troubleshooting


My client cannot find my xdbnet.ini file.

Restriction: This topic applies to Windows environments only.

Ensure the xdbnet.ini file is placed in a directory pointed to by the XDBCFG or xdbnet.ini entry in the xdb.ini file. If both XDBCFG and xdbnet.ini have entries, then xdbnet.ini overrules XDBCFG.

Parent topic: Scenarios and Solutions


My server-to-server TCP/IP connections are not working.

Restriction: This topic applies to Windows environments only.
  • First check that the basic XDB Server installation is functioning for each XDB Server by itself. If you have problems making a server-to-server connection, try connecting the client directly with each XDB Server (using the same protocol) and observe what happens. Also, if one protocol does not work for a particular connection, then try another one (if available).
  • Ensure that xdbnet.ini is built and present on your XDB Server machine.
  • Insert a single letter T (for TCP/IP) in the LINKATTR column of your SYSIBM.SYSLOCATIONS table. This single character value determines which address information in xdbnet.ini is used for the connection.
Parent topic: Scenarios and Solutions


I get the message: Can't assign requested address bind() = 10049 when I try to bring up my XDB Server with TCP/IP threads.

Restriction: This topic applies to Windows environments only.

Ensure that your TCP/IP protocol is loaded. You may need to use the TCP/IP vendor's PING utility to help track down the problem. See the next scenario for information about using PING.

Parent topic: Scenarios and Solutions


I need to verify that a particular IP address is correct when configuring TCP/IP connections.

Restriction: This topic applies to Windows environments only.

Use the PING utility (provided by your TCP/IP vendor) to test each XDB Server and client IP address in your Internet environment. PING takes the IP address as input and tests individual server-server, server-client and client-server machine connections for packet loss.

Perform the following PING tests to verify that your TCP/IP network connections are functioning properly:

  1. PING your XDB Server machine from your XDB Server machine.

    This verifies that your server-server machine TCP/IP connection is functioning properly, allowing local clients to both send and receive packets with your XDB Server.

  2. Because each remote client-server TCP/IP connection can employ a unique packet route in each direction across the internet, you should perform the following for each remote client that communicates with the XDB Server:
    • PING your XDB Server machine from your XDB Client machine.
    • PING your Client machine from your XDB Server machine.
Parent topic: Scenarios and Solutions


Tracing

Restriction: This topic applies to Windows environments only.

Running a communications trace or an engine trace may help solve configuration and usage problems, and aid in performance tuning. For example, the engine trace file contains timing information that you can use to help you locate bottlenecks in your application. Micro Focus Technical Support will instruct you as to when and how to run a trace.

Contact Micro Focus Technical Support for assistance.

Parent topic: Troubleshooting


SQL Option Link Configuration Guide

Restriction: This topic applies to Windows environments only.
  • System Requirements
  • Planning for XDB Link
  • Convening a Planning Meeting
  • Started Task Parameters
  • The Access List
  • xdbappc.ini Parameters
  • Code Page (CCSID) Tables
  • XDB Link Host Option Commands
  • Worksheets
Parent topic: SQL Option for DB2


System Requirements

Restriction: This topic applies to Windows environments only.

Before you begin to configure your environment for XDB Link, review the following table and verify that you have the required hardware and software. Also check that your software is at the required levels.

Host System Requirements

 | XDB Link to host via TCP/IP | XDB Link to host via SNA
Hardware |  |
IBM S/390, S/370, or 100% compatible computer | Required | Required
Software |  |
MVS, Version 4.2 or higher | Required | Required
VTAM, Version 3.2 or higher | Required | Required
NCP, Version 4.3 or higher |  | Optional
IBM TCP/IP, Version 2.1 or higher or INTERLINK TCP/IP, Version 4.1 or higher | Required |
RACF or CA-ACF-2 or CA Top Secret | Optional | Optional
DB2/MVS Version 3.1 or higher | Required | Required

PC System Requirements

 |  | XDB Link to host via TCP/IP | XDB Link to host via SNA
Hardware |  |  |
80486-based microcomputer (or higher) |  | Required | Required
40-MB free hard-disk space |  | Required | Required
System and Communications Software |  |  |
If using Windows NT, you need: |  |  |
 | Windows NT 3.5 or higher | Required | Required
 | Microsoft SNA Server 2.1 or higher |  | Required
 | Winsock DLL | Required |
 | Winsock DLL | Required |
If using Windows 98, you need: |  |  |
 | Winsock DLL | Required |
Network |  |
One of the following protocols: |  |  |
 | SNA |  | Required
 | TCP | Required |
Note:

Minimum requirements (for native TCP/IP access) are DB2 V5.1 AND OS/390 V1R3. Review the PSP for HDB5510 and apply any PTF's applying to DDF and TCP/IP access. Complete the steps outlined in the DB2 for OS/390 Installation Guide (GC26-8970-00) chapter 3-3.

Parent topic: SQL Option Link Configuration Guide


Planning for XDB Link

Restriction: This topic applies to Windows environments only.

After verifying that you have the appropriate hardware and software, you should do the following:

  1. Review and select the worksheets that apply to your environment. Micro Focus provides these worksheets to help you gather the information you need to configure the software on both your host system and the computer where XDB Link is installed. The worksheets also ensure that configuration values match, where necessary, across platforms and components.
  2. Convene a planning meeting.
Parent topic: SQL Option Link Configuration Guide


Convening a Planning Meeting

Restriction: This topic applies to Windows environments only.

To launch the project, Micro Focus suggests that you schedule a meeting of the project team to plan the configuration effort and ensure that each organization understands its role in the process. The primary objectives of this meeting are to:

  • Identify who must do what and when.
  • Distribute and/or complete the worksheets.
  • Ensure that everyone has the information they need to successfully configure the component for which they are responsible.
  • Define the security measures you will implement between XDB Link and the host.

Because the configuration process involves steps on both the host and the server, some or all of the following people will need to attend:

  • VTAM systems programmers
  • Database administrators for all database systems that XDB Link will access
  • LAN system administrators
  • TCP/IP network administrators
  • Security systems administrators
Parent topic: SQL Option Link Configuration Guide


Started Task Parameters

Restriction: This topic applies to Windows environments only.

Sample parameters are shipped in xdblink.v100.PARAM(PARMTCP). This file member contains the following definitions.

Note:

Do not use commas or periods when assigning a numeric value to a parameter.

Parameter Description
ORGANIZATION=
Specifies the organization ID of the owner of the XDB Link software license. The format is:

ORGANIZATION=org-id

where org-id is the organization ID. This parameter must be a string of up to 60 characters. There is no default.

PORT=
Specifies the port number that the Host Option will use. The format is:
PORT=port-number

where port-number is the number of the TCP/IP port dedicated to the XDB Link Host Option. This parameter must be an integer from 1 to 32767. There is no default.

BACKLOG=
 Specifies the length of the backlog queue maintained in TCP/IP for connection requests that have not yet been assigned sockets by the listener. The format is:
BACKLOG=backlog-length

where backlog-length is the length of the backlog queue. This parameter must be an integer from 1 to 32767. The default is 5.

NETWORK ID=
 Specifies the SSCP (system services control point) network ID for ACF/VTAM (the host node). The format is:
NETWORK ID=sscp-id

where sscp-id is the SSCP network ID. This must be a string of up to eight characters. There is no default.

LU6.2 APPLID=
 Specifies the APPLID (LU or ACBNAME) for XDB Link. The format is:
APPLID=applid

where applid is the APPLID for XDB Link. This is a string of up to eight characters, and equals the ACBNAME defined for the VTAM application. There is no default.

APPLID PASSWORD=
 Specifies the password of the APPLID defined in the PTRCT parameter of the VTAM APPLID definition. The format is:
APPLID PASSWORD=applid-pw

where applid-pw is the password. This must be a string of up to eight characters. There is no default.

TRACE=
 Specifies the trace facility name. The format is:
TRACE={GTF | WTOR | SYSPRINT}

This parameter can be set to GTF, WTOR, or SYSPRINT trace facilities. There is no default.

EID=
 Specifies the event ID of the GTF (Generalized Trace Facility) trace record. The format is:
EID=event-id

where event-id is the event ID of the GTF trace record. This must be a two-byte hexadecimal number (for example, 88FF), and it must match the USR value in the GTF trace parameter. There is no default.

TIME OUT FOR CONNECTION=
 Specifies the timeout period used for the TCP/IP accept call to get the connection request. The format is:
TIME OUT FOR CONNECTION=timeout

where timeout is the time out for connection in minutes. This must be an integer from 1 to 32767. Zero (0) specifies no timeout. There is no default.

COMPRESS=
 Not used.
ROUTE=
 Specifies the WTO (Write To Operator) and WTOR (Write To Operator with Reply) console route parameters.
ROUTE=(number1,number2)

Refer to the MVS/ESA SP V5 Auth Assembler Services Reference manual (GC28-1478) for descriptions of the values and their valid ranges. There are no defaults.

PRODUCT PASSWORD=
 Specifies the product password assigned for the software license. The format is:
PRODUCT PASSWORD=password

where password is the assigned product password. This is a six-byte hexadecimal number. The correct password will already be specified in this parameter, so there is no need for you to edit it. There is no default.

Example

The following is an example of a complete parameter definition. Lines beginning with "*" are comments.

****************************************************
  * *
  * XDB STARTED TASK INITIALIZATION PARAMETERS *
  * XDBLINK V1.00 *
  * *
  ****************************************************
  *
  * ORGANIZATION ID
  *
  ORGANIZATION=XDB SYSTEMS, INC.
  *
  * STARTED TASK TCPIP PORT NUMBER
  PORT=5170
  *
  * TCPIP LISTEN BACKLOG PARAMETER
  BACKLOG=5
  *
  * SNA NETWORK ID OF DB2 DDF
  NETWORK ID=USXDB
  *
  * STARTED TASK APPLID
  LU62 APPLID=XDB62APP
  *
  * STARTED TASK APPLID PASSWORD
  APPLID PASSWORD=XDB62APP
  *
  * TRACE OPTION
  TRACE=GTF
  *
  * GTF TRACE EID
  EID=00E9
  *
  * TCPIP ACCEPT TIME OUT PARAMETER
  TIME OUT FOR CONNECTION=0
  *
  * COMPRESSION OPTION
  COMPRESS=YES
  *
  ROUTE=(2,11)
  *
  * PRODUCT PASSWORD
  PRODUCT PSWD=2D0910D9A1C0
  *
  END
Parent topic: SQL Option Link Configuration Guide


The Access List

Restriction: This topic applies to Windows environments only.

The access list in xdblink.v100.ACCESS determines whether the XDB Link Host Option accepts or rejects a packet from a particular IP address. You can use the access list to provide an extra layer of security between XDB Link and DB2. For example, you might use it to accept only packets that come from addresses on your company Intranet.

The XDB Link Host Option accepts requests from IP addresses specified by the PERMIT= parameters in the access list, and denies requests from addresses specified by the REJECT= parameters. If an address is not defined by either a PERMIT= or REJECT= parameter, a WTOR message is sent to the console, allowing the operator to reply "PERMIT" to accept the connection or "REJECT" to reject the connection.

The PERMIT= and REJECT= parameters are specified as follows:

PERMIT=IPaddress

REJECT=IPaddress

where IPaddress is the IP address in dotted decimal notation (for example, 204.177.148.255). You can mask an IP address by omitting trailing octets. For example, "PERMIT=204.177.148" accepts requests from IP addresses 204.177.148.0 to 204.177.148.255.

Examples

The following example accepts client connection requests from IP addresses 204.177.148.0 to 204.177.148.255, except for 204.177.148.244.

PERMIT=204.177.148

REJECT=204.177.148.244

The following example accepts client connection requests from IP addresses 198.202.128.18 and 98.2.82.0 to 98.2.82.255, but rejects addresses 204.0.0.0 to 204.255.255.255.

PERMIT=198.202.128.18

PERMIT=98.2.82

REJECT=204

Parent topic: SQL Option Link Configuration Guide


xdbappc.ini Parameters

Restriction: This topic applies to Windows environments only.

The following table describes the parameters used by xdbappc.ini.

PU Definition Section

Parameter Description
PU
 Physical Unit name. This parameter must match the entry in the CSCON profile named "Peripheral CP Name."
Profile
 Profile name. This name must match the name of the profile configured with CSCON and loaded with CSLOAD.
Network
 Network Identifier. This parameter must match the entry in the CSCON profile named "SNA Network ID."
LuName
 Logical Unit Name. This is the LU name configured on the host that identifies this computer.
LuAlias
 Logical Unit Alias Name. This is the name of the LU as it will be known locally. We recommend that you use the XDB Server name as the alias.
LocAddr
 LU local address. This address must be 0 for independent LUs.
SessionLimit
 LU Session Limit. This value specifies the number of sessions this LU can have with the host. The value should be less than or equal to the entry in the CSCON profile named "Independent Sessions."
MaxTPs
 Maximum Transaction Program Limit. This entry indicates the number of transaction programs that can use this LU. It should be less than or equal to the session limit above. Each user connected through XDB Link gets an individual session and TP, so MaxTPs represents the maximum XDB Link connections possible with the host.
QueueDepth
 Depth of incoming allocate queue. This is the number of allocate requests that can be in the queue, waiting to be serviced by this LU.
PLU
 Partner Logical Unit Name. This specifies the remote database as it is known to the SNA network. For MVS/VTAM, this is the VTAM DB2 APPLID name.
Network ID
 Network Identifier. This is the name of the SNA network to which the partner LU belongs. This allows for a fully-qualified partner LU name.
Alias
 Partner Logical Unit Alias. This is the name of the partner LU as it will be known locally. The value of this parameter is used by the Gateway Profile Utility to identify the remote database.
Security
 Partner Logical Unit Security Capabilities.
  • 1 = Already Verified
  • 2 = Conversation Level security
  • 4 = Session Level security
  • 128 = Activate link to PLU at Attach LU time

Combinations of security capabilities can be added together. For Example: 3 is Conversation Level security and Already Verified (1 OR 2).

SessionLimit
 Partner Logical Unit Session Limit. This entry is the maximum number of sessions for which this partner is configured.
MaxMcSendLL
 Maximum Mapped Conversation Send Logical Length. Maximum size of data to send on a mapped conversation. The value 0 means use the largest possible value (32767).
DlcName
 Data Link Control Name. This entry identifies the connection type to the host system. Possible values are:
  • SDLC - Synchronous Data Link Control
  • ITRN - Token Ring or Ethernet
  • QLLC - Qllc connection
  • CUSTOM - Custom connection

AdaptNum
 Adapter Number. Indicates which adapter to use. For Token Ring use 0 to indicate the Primary adapter or 1 to indicate the Secondary adapter. All other DLCs should use 0.
AdaptAddr
 Adapter address:
  • SDLC - Omit this entry for this DLC type. It is not used.
  • ITRN - This is a 12-digit hexadecimal value of the locally administered address of a front-end processor (3174/37X5, PC gateway, etc.).
  • QLLC - Target name of the record in the call support layer (CSL) database defined in the NWSAA server. This entry can be up to 16 ASCII characters in length.
  • CUSTOM - Symbolic name used by the custom data link adapter. This entry can be up to 16 ASCII characters in length.

ModeName
 Mode Name. This entry is used to identify which mode definition to use for this partner LU.

Mode Definition Section

Parameter Description
Mode
 The Mode Name. The name of the mode to use for setting up sessions between the Local LU and the Partner LU. The recommended value is IBMRDB.
MaxRu
 Maximum Request/Response Unit. The maximum size (in bytes) of a Request/Response Unit.
MinRu
 Minimum Request/Response Unit. The minimum size (in bytes) of a Request/Response Unit.
MaxNegotiable
 The Maximum Negotiable Session Limit. This value is used to override the PLU max session limit.
Pacing
 Pacing Limit. The maximum number of Request/Response Units allowed before confirmation between LU and PLU.
Parent topic: SQL Option Link Configuration Guide


Code Page (CCSID) Tables

Restriction: This topic applies to Windows environments only.

Code page files (TAB files) provided with this version of XDB Link include the following:

Decimal Rep | TAB files (Hex EBCDIC <==> ASCII)
290 - 1041 | 01220411.TAB / 04110122.TAB
300 - 301 | 012C012D.TAB / 012D012C.TAB
930 - 942 | 03A203AE.TAB / 03AE03A2.TAB
933 - 949 | 03A503B5.TAB / 03B503A5.TAB
437 - 37 | 01B50025.TAB / 002501B5.TAB
850 - 37 | 03520025.TAB / 00250352.TAB
273-37 | 01110025.TAB / 0025011.TAB
273 - 437 | 011101B5.TAB / 01B5011.TAB
273 - 500 | 011101F4.TAB / 01F40111.TAB
273 - 850 | 01110352.TAB / -352-111.TAB
500 - 437 | 01F401B5.TAB / 01B50352.TAB
500 - 37 | 01F40025.TAB / 002501F4.TAB
850 - 437 | 035201B5.TAB / 01B50352.TAB
850 - 500 | 035201F4.TAB / 01F40352.TAB

For every code page pair there are 2 TAB files having the format SSSSTTTT.TAB

where:

SSSS | is the source code page value in hex.
TTTT | is the target code page in hex.

Check to see whether the code pages you require are included in the XDB program directory. If you do not find the code pages you need, run the xcpgtab.exe program in the XDB Link program directory. This program will extract additional codes pages for the installed version of XDB Link.

If after running xcpgtab.exe you do not find the code pages you need, contact Micro Focus Technical Support.

Parent topic: SQL Option Link Configuration Guide


XDB Link Host Option Commands

Restriction: This topic applies to Windows environments only.

Use the following commands to monitor and control the XDB Link Host Option. In the following command descriptions, stcname represents the name of the started task on MVS.

/F stcname, DISPLAY STATUS
 Displays the DB2 LU status, the conversation status, and the status of the started task.
/F stcname, DISPLAY LU
 Displays the DB2 LU status. If more than one DB2 connection exists, multiple LUs are displayed.
/F stcname, DISPLAY CONVERSATION
 Displays the status of LU6.2 conversations and TCP/IP connection information.
/F stcname, CANCEL
 Abruptly terminates the XDB Host Option without performing the standard shut-down procedure. Use this command only when the STOP command does not work.
/F stcname, STOP
 Stops the XDB Link Host Option using the standard shut-down procedure. It usually takes a few minutes for the program to complete its termination process after you have entered this command.
S stcname
 Starts the XDB Link Host Option.
P stcname
 Stops the XDB Link Host Option using the standard shut-down procedure. It usually takes a few minutes for the program to complete its termination process after you have entered this command.
Parent topic: SQL Option Link Configuration Guide


Worksheets

Restriction: This topic applies to Windows environments only.
  • VTAM Worksheet
  • DB2 Worksheet
  • PC LAN Worksheet (Gateway Configuration)
  • SNA Server Worksheet (V2.11)
  • SNA Server Worksheet (V3.x)
  • xdbappc.ini Worksheet
  • TCP XDBPARM Worksheet
  • TCP Host/Service Worksheet
Parent topic: SQL Option Link Configuration Guide


VTAM Worksheet

Restriction: This topic applies to Windows environments only.

Have a VTAM systems programmer complete this worksheet. Record your values in the space provided. Where suggested values are given, verify that your settings in VTAM match the suggested values.

Key

  • R denotes required information for XDB Link connections of this type. Settings must be verified or modified to match requirements.

    I denotes informational values may be useful in coordinating installation or in tracking down problems.

Note:

For VTAM, the minimum level is 3.2.

NCP is not required by XDB Link, but it must be at least version 4.2 if it is used.

TCP SNA Parameter Suggested Value Your Value Ref
R PU Definition
DLOGMOD=ANY3270
XID=YES
PUTYPE=2
STATOPT='XDB SAMPLE'

Accept system default for all other values

 A1
R PU Address

Used by SNA software on the PC

 A2
R PU CP Name

Used by SNA software on the PC

 A3
R IDNUM

Used by SNA software on the PC

 A4
R IDBLK

Used by SNA software on the PC

 05D for 3172 device A5
R LU6.2 Mode Entry

(MODEENT ID)

May be used by SNA software on the PC

 Use IBMRDB or the following:
TYPE = X'00'
FMPROF = X'13'
TSPROF = X'07'
PRIPROT = X'B0'
SECPROT = X'B0'
COMPROT = X'50B1'
RUSIZES = X'8989'
PSERVIC = X'060200000000000000002F00'
 A6
R LU Name for LU6.2 Terminals

Used by SNA software on the PC

XDBLU621 LU LOCADDR=0,MODETAB=RDBMODES,
RESSCB=20
 A7
I LU Name for 3270
XDB32701 LU LOCADDR=02,
          LOGAPPL=your3270mode
 A8
R R DB2 APPLID

Used by SNA software on the PC

See the IBM Manual Distributed Relational Database Connectivity Guide.

AUTH=(ACQ)
AUTOSES=1
SECACPT=ALREADYV
SRBEXIT=YES
VERIFY=NONE
VPACING=2

See your DB2 Administration Guide for other values

 A9
R TCP for APPLID, required only if using XDB Link Host Option.
APPL=YES,
AUTH=(ACQ),
DLOGMOD=IBMDB2LM,
DMINWNL=10,
DSESLIM=20,
SECACPT=ALREADYV,
SRBEXIT=YES,
VPACING=8
 A10

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


DB2 Worksheet

Restriction: This topic applies to Windows environments only.

Record your values in the space provided. Verify that the settings for DB2 meet the minimum requirements or match suggested values.

Parameter | Minimum Requirement | Suggested Value | Your Value | Ref
DB2 version | Version 3.1 or higher. |  |  | B1
DDF facility | Activated |  |  | B2
Security access to DDF | Required |  |  | B3
MAXDBAT in DSNZParms | MAXDBAT>=20 |  |  | B4
AuthID with authority to bind Used when creating XDB package or plan |  |  |  | B5
DB2 package name for XDB Used when binding XDB Link |  | XDBSYS |  | B6
DB2 collection ID for XDB Used when binding XDB Link |  | XDBDFT |  | B7
Users with plan access |  | PUBLIC/Specific users |  | B8
DB2 location name |  |  |  | B9
DB2 CCSID code page |  |  |  | B10

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


PC LAN Worksheet (Gateway Configuration)

Restriction: This topic applies to Windows environments only.

Give this worksheet to your PC LAN administrator or systems support staff. Verify that settings for the PC LAN and the XDB gateway machine meet the minimum requirements or match the suggested values. Record your values in the space provided.

Key:

  • R denotes required information for XDB Link connections of this type. Settings must be verified or modified to match requirements.
  • I denotes informational values that may be useful in coordinating installation or in tracking down problems.
TCP | SNA | Parameter | Minimum Requirement | Suggested Value | Your Value | Ref
R | R | Mainframe connection TCP/IP or SNA |  |  |  | C2
R | R | LAN ID Used by SNA software on the PC |  |  |  | C3
I | R | Cluster Controller Network Address Used by SNA software on the PC |  |  |  | C4
I | I | Communications cards Type of card in the gateway machine |  |  |  | C5
I | I | Max RU size for communication card | 512 |  |  | C6
I | I | 3270 access on gateway machine |  |  |  | C7
I | I | Client workstations | Verify that client workstations meet minimum software and hardware requirements specified in the XDB setup guide. |  |  | C8
R |  | IP address of host system |  |  |  | C9
I |  | IP address of gateway |  |  |  | C10

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


SNA Server Worksheet (V2.11)

Restriction: This topic applies to Windows environments only.

Give this worksheet to your PC LAN administrator or system support staff. Verify that settings for the SNA Server match the required value for the field in the specified dialog box. To help you determine the value to use when configuring SNA Server, the value's common name (nick name) and source definition are shown in the table below.

Record your values in the space provided. You will use your values when configuring the SNA Server.

Dialog boxes and field values that are not shown on this worksheet are not used by XDB Link.

Dialog Box | Field | Value Needed for XDB Link Configuration | Suggested Value | Your Value | Ref
Server Properties Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ACSTRxx)

 D1
Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

Nick Name: CPNAME

Source: VTAM PU definition

 D2
Connection Properties | Connection Name | A name for the connection between this server and the remote system. This value is used internally by the SNA Server. | D3
Link Service The DLC type used to reach the host.(802.2 for either Ethernet or Token Ring.)
Note:

Verify that the selected protocol has been installed on the SNA Server machine.

 SnaDlc1 D4
Remote End One of the following system types
  • Host System
  • Peer System
  • Down Stream

For DB2 FOR OS/390, use Host System

 D5
Activation One of the following activation events that SNA Server will use to start this connection.
  • Startup
  • On Demand
  • Manually (by Admin)
 Startup D6
Connection Properties | Allowed Directions | Outgoing. Incoming optional. | Outgoing and Incoming | D7
SETUP Remote Network Address The 12-digit hexadecimal network address (MAC address) for this server. This address starts with 4000...for Token Ring, and with 02...for Ethernet.

Nick Name: Target Mac Address

Source: VTAM controller definition

 D8
Local Node Name Local Node ID The 8-digit hexadecimal local ID number for this server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK.

Nick Name: IDNUM & IDBLK

Source: VTAM PU definition

 D9
Remote Node Name Network Name The SNA network name (NETID) for VTAM. Can be blank for APPN Peer-to-Peer.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 D10
Control Point The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP. Can be blank for APPN Peer-to-Peer.

Nick Name: SSCPNAME

Source: SYS1.VTAMLST (ATCSTRxx)

 D11
XID Format | Format 3 | Format 3 | Format 3 | D12
Remote Node ID IDNUM and IDBLK parameter in VTAM

Nick Name: Remote target NODE ID

 blank D13
APPC LU Properties LU6.2 Type Independent

Nick Name: LOCADDR = 0

Source: VTAM LU definition

 Independent Independent D14
APPC LU Properties | LU Alias | A name that represents this machine in its local SNA communications configuration. We recommend that you use the XDB Server name as the alias. | XDBSERVE | D15
Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 D16
LU Name The LU name for this APPC LU. Must match the independent LU name specified in VTAM.

Nick Name: Independent LU Name

Source: VTAM LU Definition

 D17
Enable Automatic Partnering | Enabled | Enabled | Enabled | D18
Implicit Incoming | (None) | (None) | (None) | D19
APPC Remote LU Properties | LU Alias | A name that will represent the remote APPC LU in this server's SNA communication configuration. | D20
Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

D21
LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPL definition

 D22
Uninterpreted LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPLS

 D23
Mode Mode Name IBMRDB or the mode name (DLOGMODE) defined for LU definition in VTAM.
Note:

MODETAB Name = VTAM mode table

DLOGMODE name = mode name for LU.

Nick Name: DLOGMODE

Source: ISTINCLM (or other specified name for the LOGMODE table)

 D24

1If you have a multi-domain network, use the parameter CDRM = (CDRM name). If you have a single-domain network, use the value found in library member SYS1.VTAMLIST(ATCSTRxx).

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


SNA Server Worksheet (V3.x)

Restriction: This topic applies to Windows environments only.

Give this worksheet to your PC LAN administrator or system support staff. Verify that settings for the SNA Server match the required value for the field in the specified dialog box. To help you determine the value to use when configuring SNA Server, the value's common name (nick name) and source definition are shown in the table below.

Record your values in the space provided. You will use your values when configuring the SNA Server.

Dialog boxes and field values not shown on this worksheet are not used by XDB Link.

Dialog/Tab | Field | Value Needed for XDB Link | Suggested Value | Your Value | Ref
SNA Servers General Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E1
Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

Nick Name: CPNAME

Source: VTAM PU definition

 E2
Connection General | Name | A name for the connection between this server and the remote system. This value is used internally by the SNA Server. | E3
Link Service The DLC type used to reach the host. (802.2 for either Ethernet or Token Ring.)
Note:

Verify that the selected protocol has been installed on the SNA Server machine.

 SnaDlc11 E4
Remote End One of the following system types
  • Host System
  • Peer System
  • Down Stream

For DB2 FOR OS/390, use Host System

 E5
Allowed Directions | Outgoing. Incoming optional. | Both | E6
Connection General Activation One of the following activation events that SNA Server will use to start this connection.
  • Startup
  • On Demand
  • Manually (by Admin)
 Startup E7
Connection Address Remote Network Address The 12-digit hexadecimal network address (MAC address) for this server. This address starts with 4000...for Token Ring, and with 02...for Ethernet.

Nick Name: Target Mac Address

Source: VTAM controller definition

 E8
Remote SAP Address SAP address defined by the hardware for this connection. VTAM controller definition

Source: Communications controller

 04 E9
Connection System Identification Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E10
Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

Nick Name: CPNAME

Source: VTAM PU definition

 E11
Local Node ID The 8-digit hexadecimal local ID number for this server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK

Nick Name: IDNUM & IDBLK

Source: VTAM PU definition

 E12
XID Type | Format 3 | Format 3 | Format 3 | E13
Connection System Identification Network Name The SNA network name (NETID) for VTAM. Can be blank for APPN Peer-to-Peer.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E14
Control Point The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP. Can be blank for APPN Peer-to-Peer.

Nick Name: SSCPNAME

Source: SYS1.VTAMLST (ATCSTRxx)

 E15
Remote Node ID IDNUM and IDBLK parameter in VTAM

Nick Name: Remote target NODE ID

 blank E16
Connection 802.2 DLC Max BTU Length The maximum for the BTU length. Use one of the following:
  • Token Ring 4 MB = 4195
  • Token Ring 16MB = 16393
  • Ethernet = 1493

Nick Name: VTAMLST - MAXDATA value

Note: BTU value must be less than or equal to MAXDATA in the VTAM PU definition.

 E17
Local APPC LU Properties General | LU Alias | A name that represents this machine in its local SNA communications configuration. We recommend that you use the XDB Server name as the alias. | XDBSERVE | E18
Local APPC LU Properties General Network Name The SNA network name (NETID) for VTAM.1

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E19
LU Name The LU name for this APPC LU. Must match the independent LU name specified in VTAM.

Nick Name: Independent LU Name

Source: VTAM LU Definition

 E20
Local APPC LU Properties Advanced | Member Def. Outgoing Local APPC LU Pool | Disabled | Disabled | Disabled | E21
Implicit Incoming | (None) | (None) | E22
LU6.2 Type Independent

Nick Name: LOCADDR = 0

Source: VTAM LU definition

 Independent Independent E23
SyncPoint Support | Disabled | Disabled | Disabled | E24
Remote APPC LU Properties General | Connection | Must match connection name in E3. | E25
LU Alias | An name that will represent the remote APPC LU in this server's SNA communication configuration. | E26
Network Name The SNA network name (NETID) for VTAM.

Nick Name: NETID

Source: SYS1.VTAMLST (ATCSTRxx)

 E27
Remote APPC LU Properties General LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPL definition

 E28
Uninterpreted LU Name VTAM APPLID for DB2 subsystem.

Nick Name: DB2 APPLID

Source: VTAM APPL definition

 E29
Remote APPC LU Properties Options | Supports Parallel Sessions | Enabled if the client is using an independent LU. | Enabled | E30
Implicit Incoming | (None) | (None) | E31
Session-Level Security | Only if using security keys | No Session-Level Security | E32
Mode General Mode Name IBMRDB or the mode name (DLOGMODE) defined for LU definition in VTAM.
Note:

MODETAB Name = VTAM mode table

DLOGMODE name = mode name for LU.

Nick Name: DLOGMODE

Source: ISTINCLM (or other specified name for the LOGMODE table)

 IBMRDB E33
Mode Limits Parallel Session Limit Defined by the number of users accessing the mainframe. Matches DSESLIM in your PU definition.

Nick Name: DSESLIM

Source: PU definition in SYS1_VTAMLST

 >E34

1If you have a multi-domain network, use the parameter CDRM = (CDRM name). If you have a single-domain network, use the value found in library member SYS1.VTAMLIST(ATCSTRXX).

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


xdbappc.ini Worksheet

Restriction: This topic applies to Windows environments only.

If you are using the SAA Server for NetWare, the XDB appc.ini file must be created in the root directory of the volume where XDB Link is installed. Verify that the settings in this file match the suggested values. Record your values in the space provided.

Section | Parameter | Minimum Requirement | Suggested Value | Your Value | Ref
PU Definition | Define PU | Must match the entry in the CSCON profile named "Peripheral CP Name" | NETWCP |  | H1
 | Profile | Must match the name of the profile configured with CSCON and loaded with CSLOAD | NETNODE |  | H2
 | Network | Must match the entry in the CSCON profile named "SNA Network ID" | XDBNET |  | H3
 | LuName | Must be configured for independent LU |  |  | H4
 | LuAlias | We recommend that you use the XDB Server name as the alias. | XDBSERVE |  | H5
 | LocAddr | Must be 0 for independent LUs |  |  | H6
 | SessionLimit | Should be less than or equal to the entry in the CSCON profile named "Independent Sessions" |  |  | H7
 | MaxTPs | Should be less than or equal to the session limit (SessionLimit) |  |  | H8
 | QueueDepth | Depth of incoming allocate queue |  |  | H9
PLU Definition | Define PLU | Define PLU name. For MVS/VTAM: The VTAM DB2 APPLID name |  |  | H10
 | Network | Network Identifier |  |  | H11
 | Alias | PLU alias | DRDAHOST |  | H12
 | Security | PLU security capabilities | 3 |  | H13
 | SessionLimit | PLU session limit |  |  | H14
PLU Definition | MaxMcSendLL | Maximum mapped conversation send logical length | 0 |  | H15
 | DlcName | Possible values: SDLC, ITRN, QLLC, CUSTOM |  |  | H16
 | AdaptNum | Token ring primary adapter, and all other DCLs use 0. Token ring secondary adapter use 1 |  |  | H17
 | AdaptAddr | Possible values: SDLC, ITRN, QLLC, CUSTOM |  |  | H18
 | ModeName | For sessions between Local LU and Partner LU | IBMRDB |  | H19
Mode Definition | Define Mode | Same as ModeName in PLU Definition Section | IBMRDB |  | H20
 | MaxRu | Maximum Request/Response Unit | 4096 |  | H21
 | MinRu | Minimum Request/Response Unit | 256 |  | H22
 | MaxNegotiable | Maximum Negotiable Session Limit | 16 |  | H23
 | Pacing | Pacing Limit | 4 |  | H24

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets
Related information
xdbappc.ini Parameters
Configure the PC


TCP XDBPARM Worksheet

Restriction: This topic applies to Windows environments only.

Give this worksheet to your MVS systems programmer or system support staff if you are using the XDB Link Host Option on MVS. Record your values in the space provided. The XDBPARM file is located in a PDS file on the host (XDBLINK.V100.PARAM).

Parameter | Requirements | Suggested Value | Your Value | Ref
Organization | Organization ID | Your company name |  | I1
Port | Must match the port number defined in the SERVICES File | 5170 |  | I2
Backlog | A value greater than 0 | 5 |  | I3
Network ID | SNA Network ID |  |  | I4
LU6.2 APPLID | Must match the APPLID defined in the VTAMLST | XDB62APP |  | I5
APPLID Password | Must match the APPLID password defined in the VTAMLST | XDB62APP |  | I6
Trace | Must be GTF or WTOR | GTF |  | I7
GID | Must match the USR value in the GTF trace parameter | 0E9 |  | I8
Time Out for Connection | Between 1 and 32767 | 0 |  | I9
Compress | Not Used |  |  | I10
Route | A value for WTO and WTOR | (2,11) |  | I11
Product Password | Must be the password given by XDB |  |  | I12

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


TCP Host/Service Worksheet

Restriction: This topic applies to Windows environments only.

If you are using TCP/IP to connect XDB Link to the host system, you must edit the HOSTS and SERVICES files on the machine where XDB Link is installed to define the IP address and port number of the host system. Record your values in the space provided.

File | Parameter | Requirements | Suggested Value | Your Value | Ref
Hosts | IP address | The IP address defined for the host |  |  | J1
 | Host name | A name that represents this IP address |  |  | J2
Services | Service name | A name that represents this port number | We recommend that you use the name of the XDB Server as the service name. |  | J3
 | Port number | The port number assigned to the XDB Link Host Option | 5170 |  | J4
 | Protocol | TCP protocol | tcp | tcp | J5

Specify the IP address and host name values in the HOSTS file on the machine where XDB Link is installed. For example, you would enter the line:

240.195.165.202 LUDB2

to assign the host name LUDB2 to the IP address 240.195.165.202.

Specify the service name, port number, and protocol in the SERVICES file on the machine where XDB Link is installed. For example, you would enter the line:

XDBSRV 5170/tcp

to assign the service name XDBSRV to tcp port 5170.

Please return this worksheet to the XDB Link Installation Coordinator.

Parent topic: Worksheets


SQL Option Preprocesor Guide

Restriction: This topic applies to Windows environments only.
  • Creating and Embedding SQL in COBOL
  • Using Dynamic SQL in COBOL
  • Static Binding
  • Security
  • DSNTIAR Facility
  • XDB Preprocessor
Parent topic: SQL Option for DB2


Creating and Embedding SQL in COBOL

Restriction: This topic applies to Windows environments only.

There are certain requirements your COBOL programs must meet before they can be compiled and debugged. This chapter outlines the processes for creating or modifying SQL code for COBOL programs. It also details the statements that all COBOL programs containing embedded SQL must contain.Use of dynamic SQL in your program is described in the chapter Using Dynamic SQL in COBOL.

  • Using Copybooks
  • Creating a Copybook
  • Representing Data
  • Using Directives
  • SQL Communications Area (SQLCA)
  • SQL Descriptor Area (SQLDA)
  • Sample COBOL Program with Embedded SQL
Parent topic: SQL Option Preprocesor Guide
Related information
Using Dynamic SQL in COBOL


Using Copybooks

Restriction: This topic applies to Windows environments only.

In a typical development effort, different COBOL programs access the same data tables. Copybooks allow host variable definitions for a table's columns to be inserted within your COBOL code, allowing data from those columns to be used in your program. If a modification is made to a table (such as a change of data type or column length), then it is only necessary to modify the copybook rather than the source code definition for that table in all the programs that use it.

Parent topic: Creating and Embedding SQL in COBOL


Creating a Copybook

Restriction: This topic applies to Windows environments only.

You can use the SQL Option Declaration Generator to create declarations of your tables. See the SQL Option Declaration Generator User's Guide for specific procedures.

  • Copybook Format
  • Including Copybooks in Programs
  • Host Variables
Parent topic: Creating and Embedding SQL in COBOL


Copybook Format

Restriction: This topic applies to Windows environments only.

The format of a copybook is shown by the following example. This declaration defines the SQL Option EMPLOYEE table in the TUTORIAL location:

 01 EMP-TABLE.
     03 ENO PIC S9(4) COMP.
     03 LNAME PIC X(10).
     03 FNAME PIC X(10).
     03 STREET PIC X(20).
     03 CITY PIC X(15).
     03 ST PIC XX.
     03 ZIP PIC X(5).
     03 DEPT PIC X(4).
     03 PAYRATE PIC S9(13)V99 COMP-3.
     03 COM PIC S9V99 COMP-3.

All sample tables are shown in the SQL Reference manual.

Parent topic: Creating a Copybook


Including Copybooks in Programs

Restriction: This topic applies to Windows environments only.

When including a copybook in your program, make sure that the Compiler can locate the copybook. For more information see the section Copy Libraries in the chapter Using the Compiler in yourUser's Guide.

If a copybook contains embedded SQL or host variable declarations, include it using one of the following three methods:

  • EXEC SQL INCLUDE ... END-EXEC
  • COPY
  • -INC
Parent topic: Creating a Copybook


EXEC SQL INCLUDE ... END-EXEC

Restriction: This topic applies to Windows environments only.

For example:

EXEC-SQL
    INCLUDE EMPREC
END-EXEC
Parent topic: Including Copybooks in Programs


COPY

Restriction: This topic applies to Windows environments only.

For example:

COPY EMPREC.

The file named after the COPY verb can contain any COBOL statements that a copybook can, including EXEC SQL statements.

The SQL Option preprocessor works like the mainframe DB2 preprocessor does. However with the SQL Option preprocessor, you need to specify the preprocessor directive COPY to allow host variables to be defined in COPY statements.

Note:

If you specify EXEC SQL statements using the COPY verb, the SQL Option preprocessor will compile the program and will generate an error message for any host variable referenced from the copybook without the COPY directive being set. If you port the same program to the mainframe, the SQL code may not precompile unless your installation has a product that expands copybooks before passing them to the DB2 mainframe preprocessor.

Parent topic: Including Copybooks in Programs


-INC

Restriction: This topic applies to Windows environments only.

For example:

-INC EMPREC

The file specified after the -INC verb can contain any COBOL statements that a copybook can, including EXEC SQL statements.

Parent topic: Including Copybooks in Programs


Host Variables

Restriction: This topic applies to Windows environments only.

Host variables are used to hold data that is accessed by both COBOL and SQL commands. You define a host variable as a data structure that represents the column names and data types of the tables that are accessed by the COBOL program.

Host variables are usually defined in copybooks. Copybooks can be quickly created from any SQL Option or DB2 table using the SQL Option Declaration Generator utility (applies to Windows environments only).

There are two ways to use host variables:

  • To store information returned by the database engine as the result of an SQL statement.
  • To store information sent to the database engine and/or dynamic information that controls what is returned by a SELECT statement.

All host variables appearing inside an EXEC SQL ... END-EXEC block should be preceded by a colon, as shown for the host variable DEPT-NUM in the following example:

 EXEC SQL
     DECLARE EMPCURS CURSOR FOR
     SELECT LNAME, FNAME, PAYRATE, HOURS
       FROM EMPLOYEE
       WHERE DEPT = :DEPT-NUM
 END-EXEC

DB2 V5 does not require all host variables to be preceded by a colon, but DB2 V6 does. If you plan to upgrade in the future, you should set your message level to WARNING in the build setting for every SQL programs in the project.

The use of host variables allows you to design more flexible queries, and to interactively define the criteria for data selection. In the preceding example, the host variable specifies the department for which data will be selected.

For information about null values in host variables, see the section Using Indicator Variables .

Parent topic: Creating a Copybook


Representing Data

Restriction: This topic applies to Windows environments only.

When you access data with SQL statements in COBOL programs, you must provide corresponding data definitions in your COBOL source code. This requirement is usually accomplished by stating the data definitions in a copybook and including that copybook in your COBOL source code.

The copybook EMPREC contains a COBOL representation of the column names and data types for the EMPLOYEE sample table. The Declaration Generator generates copybooks from tables, automatically creating a COBOL data definition for each table column (applies to Windows environments only)You can modify the generated copybook file as needed. See the SQL Option Declaration Generator User's Guide for more information about using the SQL Option Declaration Generator.

Note: The SQL Option Precompiler does not accept all COBOL data types. If the COBOL data item you code is not consistent with those shown in the section Allowed Data Declarations, it will not be recognized as a host variable.

The following guidelines are offered to assist you in working with host variables and data declarations.

  • For data declarations of host variables use level number 01 to 77.
  • A varying-length character string data item must have group level 01. The group contains two, level 49 elementary items consisting of:
    • Length Item.

      The first elementary item must be a 2-byte integer variable; for example, PICTURE S9(4) COMP. It represents the length of the character string.

    • Value Item.

      The second elementary item must have the same description as a fixed-length character string; for example, PICTURE X(80), where 80 is the maximum length of the string. This item is used to contain the value of the character string. If you use the host variable to insert a character string into a table, the database manager inserts only as many characters as are indicated by the length item. Also, when data is placed into the field, only the number of characters defined in the length item is returned. This can cause previous information stored in this field not to be cleared.

    The data item and elementary items can have any acceptable COBOL name. However, in SQL statements, refer to this host variable by its group name.

  • COBOL host variables used in SQL statements must be of a type compatible with the database columns with which they are to be used.
    • Numeric data types are compatible with each other. A SMALLINT, INTEGER, DECIMAL, or FLOAT column is compatible with a COBOL host variable of COMP, COMP-2, COMP-3, COMP-4, or COMP-5.
    • Character data types such as CHAR and VARCHAR are compatible with each other. The database manager automatically converts a fixed-length character string to a varying-length string, or vice versa, when necessary.
  • Be careful of overflow. For example, if you retrieve an INTEGER column value into a PICTURE S9(4) host variable and the column value is larger than 32767 or smaller than -32768, you will get an overflow error.
  • Be careful of truncation. For example, if you retrieve an 80-character CHAR column value into a PICTURE X(70) host variable, the rightmost 10 characters of the retrieved string will not be included.

    Retrieving a floating-point or decimal column value into a COMP host variable removes any fractional value.

  • The COBOL declarations for SMALLINT and INTEGER data types are expressed as a number of decimal digits. The database manager uses the full size of the binary integers, and may place larger values than would be allowed in the specified number of digits in the COBOL declaration. This situation can cause data truncation. Ensure that the size of any numbers in your application is within the allowable number of digits.
  • The SQL Option preprocessor also supports using host variables defined with the SQL TYPE IS declaration. The actual data definition for the host variable is then determined by the preprocessor. For example, a host variable for a RESULT SET LOCATOR could be defined as:
    01 my-locator usage SQL TYPE IS RESULT-SET-LOCATOR varying.
  • Allowed Data Declarations
  • Allowed Data Declaration Abbreviations
  • Using Indicator Variables
Parent topic: Creating and Embedding SQL in COBOL


Allowed Data Declarations

Restriction: This topic applies to Windows environments only.

The following table shows the COBOL declarations that are allowed for defining host variables. All other types of COBOL declarations will be rejected. Allowed abbreviations are shown in the section Allowed Data Declaration Abbreviations.

Data Type | COBOL Data Declaration | Comments
char | 01 identifier PIC X(n). 01 identifier PICTURE IS X(n). | n is a positive integer representing the length of the CHAR column value assigned to the host variable.
varchar | 01 identifier 49 identifier PIC S9(ni) COMP. 49 identifier PIC X(nc). | ni is a positive integer from 1 to 4, representing the length of the numeric column value assigned to the variable containing the string length. nc is a positive integer equal to the length of the largest VARCHAR column value that can be assigned to the host variable.
smallint | 01 identifier PIC S9(4) COMP. 01 identifier PIC S9(n) COMP. 01 identifier PIC S9(n) USAGE IS COMP. | n is a positive integer from 1 to 4, representing the variable length. No decimal points are allowed. Anything other than 9s in the Picture clause makes data item unacceptable as a host variable. PIC S and COMP are required. You may use COMP-4 or COMP-5 in place of COMP if necessary.
integer | 01 identifier PIC S9(9) COMP. 01 identifier PIC S9(n) COMP. 01 identifier PIC S9(n) USAGE IS COMP. | n is a positive integer from 5 to 9. No decimal point is allowed. Anything other than 9s in the Picture clause will make the data item unacceptable as a host variable. PIC S and COMP are required. You may use COMP-4 or COMP-5 in place of COMP if necessary.
decimal | 01 identifier PIC S9V COMP-3. 01 identifier PIC S9(n) V COMP-3. 01 identifier PIC S9(n) V9(m) COMP-3. 01 identifier PIC S9(n) V9(m) USAGE IS COMP-3. | n and m are positive integers; n + m cannot exceed 15. You must include a V to denote the decimal point. Anything other than 9s and a V in the Picture clause will make the data item unacceptable as a host variable. PIC S and COMP-3. are required.
float | 01 identifier COMP-2. 01 identifier USAGE IS COMP-3. | COMP-2. or COMP-3. is required.
date | 01 identifier PIC X(n). 01 identifier PICTURE IS X(n). | n must be an integer representing the length of the date string. For example, if the date string is in the format MM/DD/YY, n may equal 8. If in the format MM/DD/YYYY, n should equal 10. Make sure your date format is set correctly in the Options (Windows) or User Profile (UNIX)utility. See the Option utility's online help for information about modifying the date/time representation.
time | 01 identifier PIC X(n). 01 identifier PICTURE IS X(n). | n must be an integer representing the length of the time string. To include seconds, n must be at least 8. For example, a time string in the format HH:MM requires that n equal at least 5, while a time string in the format HH:MM:SS requires that n equal at least 8.
result set locator | 01 identifier SQL TYPE IS RESULT-SET- LOCATOR. | A 4-byte value used by DB2 to uniquely identify a query result set returned by a stored procedure.
Parent topic: Representing Data


Allowed Data Declaration Abbreviations

Restriction: This topic applies to Windows environments only.

The following table shows the COBOL abbreviations allowed for host variables. For a complete list of allowed data types, see the topic Allowed Data Declarations.

Abbreviation | Can be used for...
PIC | PICTURE or PICTURE IS
COMP | COMPUTATIONAL or USAGE IS COMPUTATIONAL
PIC IS | PICTURE IS
USAGE | USAGE IS
S9(5) | S99999
X(10) | XXXXXXXXXX
Parent topic: Representing Data
Related information
Allowed Data Declarations


Using Indicator Variables

Restriction: This topic applies to Windows environments only.

An indicator variable is a 2-byte integer variable that can be used for either of the following purposes:

  • To indicate whether its associated host variable has been assigned a null value. If the value for the column you are retrieving is null, a negative value is placed in the indicator variable.
  • To verify that a retrieved character string value has not been truncated. If the indicator variable contains a positive integer, it specifies the original length of the string.

When a column's value is retrieved, you can test the indicator variable. If the indicator variable's value is less than zero, you know the retrieved column's value is null. When a null value is retrieved, nothing is put into the associated host variable that is used to contain the column's value; thus, the value of the host variable is unchanged.

Define indicator variables in the same manner as small-integer host variables. Specify an indicator variable, preceded by a colon, immediately after the host variable to which it relates. For example:

 EXEC SQL
     SELECT PHONENO INTO :CBLPHONE :INDNULL FROM CORPDATA
       WHERE EMPNO = "EMPID"
 END-EXEC

You can then test INDNULL to see if it contains a negative value. If it does contain a negative value, then you know that a null value was retrieved for the row's PHONENO (that is, phone number) column, and you can disregard the contents of CBLPHONE.

When a column value is fetched using a cursor, you can use the same technique to determine whether the retrieved value is null or not.

You can also use an indicator variable to set a null value in a column. When processing UPDATE statements, the indicator variable is checked. If the indicator variable contains a negative value, set the column value to "null value." If the indicator variable is greater than -1, the associated host variable contains a value for the column.

Parent topic: Representing Data


Using Directives

Restriction: This topic applies to Windows environments only.

Directives are compiler options that convey information to your compiler and the SQL Option Precompiler. For example, the DBRM directive is used to create a database request module during the compile.

Parent topic: Creating and Embedding SQL in COBOL
Related information
XDB Preprocessor Options


SQL Communications Area (SQLCA)

Restriction: This topic applies to Windows environments only.

Every COBOL program containing embedded SQL must have an SQL Communications Area (SQLCA) or the field SQLCODE defined in its Working-Storage Section. This definition is normally accomplished by including the SQLCA copybook provided with Enterprise Developer. A complete description of the SQLCA structure is provided in the SQL Reference.

Important: Enterprise Developer does not default to using the XDB SQLCA. This can lead to problems using DSNTIAR. To ensure that Enterprise Developer uses the XDB SQLCA, you must add the path to the provided XDB copybooks to the Linked Resources list in your project properties. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib\xdb (Windows) or $COBDIR/copylib/xdb (UNIX). To do this, see the section To link to a folder containing copybooks in the topic To link to copybooks or sources outside the project. Be sure to specify the path to the XDB copybook files, and be sure this path appears at the top of the list of linked resources.

The SQLCA holds information on the status of the SQL statement last executed. It is updated after the execution of each EXEC SQL ... END-EXEC block of code.

Information in the SQLCA can be used in many ways. For example:

  • You can use it to debug your code.
  • You can use it to control the flow of your program by testing its values. For example, when SQLCA indicates an error, you can branch to an error-processing routine. Similarly, you can use it to detect the end-of-data and exit a loop.

The following SQLCA codes are particularly useful:

Table 1.
Field | Description
SQLSTATE The SQL Option Preprocessor provides limited support for DB2-compliant SQLSTATE return codes within COBOL application programs. This limited support is provided on top of already existing support for SQLCODE. SQL Option maps a subset of SQLSTATE values from equivalent SQLCODE return values. SQLSTATE support is limited to applications running against an SQL Option Server in DB2 mode. If running against the SQL Option Link, support for the full range of SQLSTATE return codes is provided by DB2 directly (applies to Windows environments only). (Consult your DB2 documentation.) See the SQL Option Link User's Guide for a complete listing of SQLSTATE values supported by SQL Option, plus a table mapping error message return codes.

SQLSTATE values provide COBOL application programs with a standardized set of return codes corresponding to common SQL statement error conditions. SQLSTATE values are structured so that application programs can test for specific errors or classes of errors. In an application program, the SQLSTATE is a status parameter (similar to SQLCODE) that indicates either that an SQL statement completed successfully or that an exception condition was raised during execution. Unlike the SQLCODE (which is an integer parameter), the SQLSTATE is a character string parameter which for COBOL language applications is of data type COBOL PICTURE X(5).

SQLCODE The SQLCODE element in SQLCA contains a return code relating to the last SQL statement executed:
  • If an error occurred, the SQLCODE in the SQLCA will contain a negative number corresponding to the DB2. The equivalent SQL Option Server error code is returned in the SQLERRD (1) field. See Error Messages in your Reference Help for codes and meanings.
  • If SQLCODE is 0, the statement executed successfully but may have had warnings (as indicated in the SQLWARN fields).
  • A code of +100 indicates no more records.

The SQL Option DSNTIAR facility may be used to convert an SQL return code (from the SQLCODE field in SQLCA) to a character string. See the chapter DSNTIAR Facility for more information.

SQLERRD(3) | The SQLERRD (3) element in SQLCA holds the number of rows that were inserted, updated, or deleted by an SQL statement.
SQLERRML | The SQLERRML element in SQLCA is the length of SQLERRMC. If zero, the value of SQLERRMC is not pertinent. For more information, see the description for SQLERRMC.
SQLERRMC The SQLERRMC element in SQLCA holds a character string that describes an error condition. If there is an error, it will contain one or more tokens, separated by X'FF'.

The tokens are substituted for the variables in the descriptions of error messages (for example, the name of a file or table).

SQLWARN0 | The SQLWARN0 element in SQLCA is a warning flag that indicates if any other SQLWARNn field is signaling a potential problem. If SQLWARN0 is blank, then all other SQLWARNn fields are blank (no warnings exist). If SQLWARN0 contains a W, then at least one of the other SQLWARNn variables has a W. For information on the meanings of the other SQLWARNn fields, see the SQL Reference manual.
Parent topic: Creating and Embedding SQL in COBOL


SQL Descriptor Area (SQLDA)

Restriction: This topic applies to Windows environments only.

COBOL programs that include dynamic SQL must have an SQL Descriptor Area (SQLDA) defined. This definition is usually accomplished by including the SQLDA copybook provided with Enterprise Developer.

Important: Enterprise Developer does not default to using the XDB SQLDA. To ensure that Enterprise Developer uses the XDB SQLDA, you must add the path to the provided XDB copybooks to the Linked Resources list in your project properties. By default, this is %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib\xdb (Windows) or $COBDIR/copylib/xdb (UNIX). To do this, see the section To link to a folder containing copybooks in the topic To link to copybooks or sources outside the project. Be sure to specify the path to the XDB copybook files, and be sure this path appears at the top of the list of linked resources.

The default SQLDA copybook used by the SQL Option preprocessor is not mainframe DB2 compatible. Instead it is designed for easy compatibility if you are upgrading from older version of XDB or SQL Option software.

A mainframe compatible SQLDA is provided in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib\xdb (Windows) or $COBDIR/copylib (UNIX) directory with filename of sqlda.cpy. If you want to use that copybook instead, just rename it. You then need to compile all programs that use this copybook or SQLDA's defined using the mainframe SQLDA structure with the SQL preprocessor directive SQLDA-VER=1 or the program will not map data properly and probably trap.

The SQLDA holds information about dynamic SQL queries, and is required for allocating the proper amount of space for the query.

For more information about dynamic SQL and the SQLDA, see the topic Using Dynamic SQL in COBOL. For a complete description of the SQLDA structure, see the SQL Reference. Refer to your preprocessor documentation on the use of pointer variables and for additional information on dynamic SQL in COBOL programs.

Parent topic: Creating and Embedding SQL in COBOL
Related information
Using Dynamic SQL in COBOL


Sample COBOL Program with Embedded SQL

Restriction: This topic applies to Windows environments only.

The following program shows how SQL statements can be embedded in a COBOL program. Note that the copybook EMPREC has been included in the program using the INCLUDE statement.

This program declares a cursor, opens it, and then fetches data into a set of host variables. The host data is displayed. (Note the use of the indicator variable used with the commission variable COM.) When the end of data is reached, or when the user is finished viewing data, the loop is terminated, the cursor is closed, and the program ends.

 IDENTIFICATION DIVISION.

 PROGRAM-ID. TESTALL.
 AUTHOR-NAME. ME.

 ENVIRONMENT DIVISION.

 CONFIGURATION SECTION.
 SOURCE-COMPUTER. IBM-AT.
 OBJECT-COMPUTER. IBM-AT.

 INPUT-OUTPUT SECTION.
 FILE-CONTROL.

 DATA DIVISION.

 FILE SECTION.

 WORKING-STORAGE SECTION.

 EXEC SQL
   INCLUDE EMPREC
 END-EXEC.

 01 DISP-RATE PIC $$$,$$$,$$9.99.
 01 DISP-COM PIC Z.99.
 01 DISP-CODE PIC ----9.
 01 FAKE-CHAR PIC X.
 01 ANSS PIC X.
 01 COM-NULL-IND PIC S9(4) COMP.

 EXEC SQL
   INCLUDE SQLCA
 END-EXEC.

 PROCEDURE DIVISION.

 100-MAIN.
* declare cursor for select
     EXEC SQL
         DECLARE EMPTBL CURSOR FOR
         SELECT *
           FROM EMPLOYEE
         ORDER BY LNAME
     END-EXEC

* open cursor
     EXEC SQL
         OPEN EMPTBL
     END-EXEC
     MOVE SQLCODE TO DISP-CODE
     DISPLAY 'open ' DISP-CODE

* fetch a data item
     EXEC SQL
         FETCH EMPTBL INTO
           :ENO,:LNAME,:FNAME,:STREET,:CITY,
           :ST,:ZIP,:DEPT,:PAYRATE,
           :COM :COM-NULL-IND
     END-EXEC.

 100-test.
     MOVE SQLCODE TO DISP-CODE
     DISPLAY 'fetch ' DISP-CODE

* loop until no more data
     PERFORM UNTIL SQLCODE < 0 OR SQLCODE = 100

* display the record
     MOVE PAYRATE TO DISP-RATE
     MOVE COM TO DISP-COM
     DISPLAY 'department ' DEPT
     DISPLAY 'last name ' LNAME
     DISPLAY 'first name ' FNAME
     DISPLAY 'street ' STREET
     DISPLAY 'city ' CITY
     DISPLAY 'state ' ST
     DISPLAY 'zip code ' ZIP
     DISPLAY 'payrate ' DISP-RATE
     IF COM-NULL-IND < 0
         DISPLAY 'commission is null'
     ELSE
         DISPLAY 'commission ' DISP-COM
     END-IF
     DISPLAY 'Do you want to see the next record? (y/n)'
     ACCEPT ANSS
     IF ANSS = 'Y' OR 'y'
         EXEC SQL
           FETCH EMPTBL INTO
             :ENO,:LNAME,:FNAME,:STREET,:CITY,
             :ST,:ZIP,:DEPT,:PAYRATE,
             :COM :COM-NULL-IND
         END-EXEC
     ELSE
         GO TO CLOSE-LOOP
     END-IF
     MOVE SQLCODE TO DISP-CODE
     DISPLAY 'fetch ' DISP-CODE
     END-PERFORM

     DISPLAY 'All records in this table have been selected'.

 CLOSE-LOOP.
* close the cursor
     EXEC SQL
         CLOSE EMPTBL
     END-EXEC.

 100-EXIT.
     STOP RUN.
Parent topic: Creating and Embedding SQL in COBOL


Using Dynamic SQL in COBOL

Restriction: This topic applies to Windows environments only.

Dynamic SQL refers to a special type of embedded SQL statement that is prepared and executed within an application program while the program is running. It differs from static embedded SQL in that part or all of the actual SQL commands may be stored in a host variable, whose value may change numerous times during execution of the program. In the extreme case, the SQL commands are generated in their entirety by the application program at run time.While dynamic SQL is more flexible than static embedded SQL, it does require additional overhead and more programming sophistication.

  • Overall Considerations
  • Non-Select SQL Statements
  • Fixed-List Select Statements
  • Varying-List Select Statements
Parent topic: SQL Option Preprocesor Guide


Overall Considerations

Restriction: This topic applies to Windows environments only.

The varying-list SELECT requires use of the SQLDA and address functions (COBOL pointer variables). The other types of dynamic SQL may require those features under certain conditions.

The SQL Descriptor Area (SQLDA) is a data structure that holds information about the execution of dynamic SQL statements. See the SQL Reference for more information about including an SQLDA in your program. Also see your COBOL documentation for an explanation of the use of address functions.

Some SQL statements cannot be executed dynamically, usually because they are needed to enable dynamic SQL commands themselves. The SQL commands that cannot be executed dynamically are shown below.

  • BEGIN DECLARE SECTION
  • FETCH
  • CLOSE
  • INCLUDE
  • DECLARE
  • OPEN
  • DESCRIBE
  • PREPARE
  • END DECLARE SECTION
  • SELECT INTO
  • EXECUTE
  • SET host-variable
  • EXECUTE IMMEDIATE
  • WHENEVER
Parent topic: Using Dynamic SQL in COBOL


Non-Select SQL Statements

Restriction: This topic applies to Windows environments only.

When non-SELECT statements are issued dynamically, the coding task is relatively easy because there is no need to dynamically allocate main storage.

To issue a non-SELECT statement dynamically:

  1. (Optional) Test each SQL statement using the SQLWizard (Windows) or Interactive SQL (UNIX) to see that proper results are obtained.
  2. Load the SQL statement into a data area.
  3. Issue a PREPARE and then an EXECUTE (or EXECUTE IMMEDIATE) statement.

    Be sure to handle any errors that result.

The following example executes an UPDATE statement that gives every employee a 10 percent raise:

     MOVE 'update employee set payrate=payrate*1.10'
                                                TO SQLCMD
     EXEC SQL
         EXECUTE IMMEDIATE :sqlcmd
     END-EXEC
     ...
Parent topic: Using Dynamic SQL in COBOL


Fixed-List Select Statements

Restriction: This topic applies to Windows environments only.

A fixed-list SELECT statement is a statement that returns a predictable number of data items of a known type from an open cursor. For each of these items, a host variable is required to accommodate incoming data.

To issue a fixed-list SELECT statement dynamically:

  1. (Optional) Test each SQL statement using the SQLWizard (Windows) or Interactive SQL (UNIX) to see that proper results are obtained.
  2. Load the SQL statement into a data area.
  3. Use PREPARE to validate the statement and translate it into an executable form.
  4. Use DECLARE to declare a cursor for the statement.
  5. Use OPEN to open the cursor.
  6. Use FETCH to retrieve a row into a fixed list of variables.
  7. When the end of data is reached, use CLOSE to close the cursor.

    Be sure to handle any errors.

The following example shows how to execute a fixed-list SELECT statement dynamically.

* include SQLDA copybook
     EXEC SQL
         INCLUDE SQLDA
     END-EXEC

* assign value to variable sqlcmd.
     MOVE 'select e_no, ' &
          'lname from employee where dept="1050"' TO sqlcmd

* prepare SELECT command.
     EXEC SQL
         PREPARE q1 FROM :sqlcmd
     END-EXEC

* declare cursor for SELECT command.
     EXEC SQL
         DECLARE c1 CURSOR FOR q1
     END-EXEC

* open cursor.
     EXEC SQL
         OPEN c1
     END-EXEC

* fetch data into program variables EMPNO, LASTNME and
* FIRSTNME.
     EXEC SQL
         FETCH c1 INTO :EMPNO, :LASTNME
     END-EXEC

* close cursor.
     EXEC SQL
         CLOSE c1
     END-EXEC
Parent topic: Using Dynamic SQL in COBOL


Varying-List Select Statements

Restriction: This topic applies to Windows environments only.

A varying-list SELECT statement is one that retrieves data items of varying number and format. Because the number and type of data items are not known, you cannot define host variables in advance.

However, by including the SQLDA in your program, you can use PREPARE to define a SELECT statement and follow it with a DESCRIBE statement. This process inserts the data item information into the SQLDA, which your program can use to execute a SELECT statement. Likewise, record fetches are performed using the SQLDA.

To issue a varying-list SELECT statement:

  1. Include the SQLDA copybook in your program.
  2. Use PREPARE to define a statement (either already in a statement buffer or to be read) so that it may be translated to executable form.
  3. Use DESCRIBE for the prepared statement to determine how many columns will be retrieved and their data types. You may use a PREPARE INTO to PREPARE and DESCRIBE in a single statement.
  4. If the SQLDA is not large enough to contain column descriptions for each column, your program must determine how much space is needed, obtain that storage space, build a new SQLDA, and DESCRIBE again.
  5. The program must now determine how much space is needed for the data in each column (and possibly an indicator variable). Storage must be obtained so that when a value is fetched, your program will know where to put the data. Acquiring this storage is accomplished by analyzing the SQLDA. For more information on the SQLDA, see the SQL Option SQL Reference.
  6. Execute the SELECT statement by declaring and opening a cursor for the prepared statement.
  7. Fetch a row of data by specifying USING DESCRIPTOR SQLDA on the FETCH statement.
  8. When end of data is reached, close the cursor.

The following program excerpt shows how to execute a varying-list SELECT statement dynamically.

* include SQLDA copybook.
     EXEC SQL
         INCLUDE SQLDA
     END-EXEC

* assign value to variable sqlcmd.
     MOVE 'select * from employee where dept="1050"'
                                                   TO sqlcmd

* prepare SELECT command.
     EXEC SQL
         PREPARE q1 FROM :sqlcmd
     END-EXEC

* allocate space for an SQLDA ...
     MOVE 20 TO SQLN

* describe SELECT command.
     EXEC SQL
         DESCRIBE q1 INTO SQLDA
     END-EXEC

* make sure SQLDA is big enough.
     IF (SQLN <= SQLD)
            PERFORM ...
             ...
             MOVE SQLD TO SQLN.
             EXEC SQL
                 DESCRIBE q1 INTO SQLDA
             END-EXEC
         END-PERFORM
     END-IF

* analyze results of DESCRIBE.
...
* allocate storage to hold one row of the result. ...
* declare cursor for SELECT command.
     EXEC SQL
         DECLARE c1 CURSOR FOR q1
     END-EXEC

* open cursor.
     EXEC SQL
         OPEN c1
     END-EXEC

* fetch data into program variables EMPNO, LASTNME and
* FIRSTNME.
     EXEC SQL
         FETCH c1 USING DESCRIPTOR SQLDA
     END-EXEC

* display results fetching next record as long as there
* is one.
     PERFORM UNTIL SQLCODE <> 0
         DISPLAY ...
         EXEC SQL
             FETCH c1 USING DESCRIPTOR SQLDA
         END-EXEC
     END-PERFORM
     DISPLAY 'END OF LIST'.

* close cursor.
     EXEC SQL
         CLOSE c1
     END-EXEC
Parent topic: Using Dynamic SQL in COBOL


Static Binding

Restriction: This topic applies to Windows environments only.
  • Overview
  • Creating a DBRM
  • Binding a DBRM
  • Autobinding
  • Specifying Options with AUTOBIND
  • Binding SQL Statements With Literals
  • Using AUTHID to Change Table Qualifier
  • Examples of DBRM Directives
  • Examples of Autobinding Multiple DBRM's
Parent topic: SQL Option Preprocesor Guide


Overview

Restriction: This topic applies to Windows environments only.

SQL Option, by default, uses dynamic SQL. However, depending on your application the use of static SQL can have a significant impact on performance. Most applications will run faster when executing static as opposed to dynamic SQL. Also, default qualifiers can be specified during the bind to allow a program to use a particular AUTHID to qualify one part table names when the user does not have authority to execute a SET CURRENT SQLID command. Many sites are reluctant to use SET CURRENT SQLID since it may require SYSADM authority to execute.

Parent topic: Static Binding


Creating a DBRM

Restriction: This topic applies to Windows environments only.

To have your program use static SQL, you must create a DBRM (database request module) and bind it to the SQL Option server you are going to run against. To create a DBRM, you need to compile your program with at least the following SQL Option preprocessor directives:

  • DBRM=dbrm-name
  • COLLECTION-ID=collection-id
Parent topic: Static Binding


Binding a DBRM

Restriction: This topic applies to Windows environments only.

You must bind the DBRM using the BIND utility provided with SQL Option. After you have bound the DBRM your application will be running static SQL. If you change any SQL statements in the program you will need to rebuild and rebind your DBRM. For details on how to BIND the DBRM, see the BIND Guide.

Parent topic: Static Binding


Autobinding

Restriction: This topic applies to Windows environments only.

If you have too many programs to bind using the BIND utility or just don't want to have to manually bind each program, you can compile each program with the SQL Option preprocessor directive called AUTOBIND. When this directive is specified the preprocessor will call BIND for you and will automatically bind the DBRM at the end of the compile.

XDB now supports writing out multiple DBRM's for a single program and you can automatically bind up to 10 DBRM's. The directives that support multiple options are DBRM, COLLECTION-ID, AUTHID, and LOCATION. You must also specify AUTOBIND for this to work properly.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Specifying Options with AUTOBIND

Restriction: This topic applies to Windows environments only.

The Bind Guide specifies many bind options. New directives have been added so you can set these options using the AUTOBIND directive. These directives are optional - you do not need to specify them if you want to use default values (recommended in most cases). These additional directives are:

  • EXIST-CHECK
  • GRANT-EXECUTE
  • DEFAULT-CHAR
  • BLOCKING

If any errors occur during the automated bind process, no DBRM will be generated. However in its place will be a log file with name dbrm-name.log The log file will record all errors reported during the bind process. Consult your error documentation to resolve the error.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Binding SQL Statements With Literals

Restriction: This topic applies to Windows environments only.

If you have literals in your SQL statements, you need to make sure that the quote character matches your build settings or you could have problems binding the DBRM.

The SQL Option preprocessor defaults to the compiler setting for literals in the build settings. If you use the same character to enclose literals in your SQL statements as you did for COBOL literals, you don't have to do anything. If you use a different character for literals in SQL statements, then you have to use the preprocessor directive of either QUOTE or APOST.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Using AUTHID to Change Table Qualifier

Restriction: This topic applies to Windows environments only.

If you have two identical sets of tables, for example YYYYYYYY.table1 and XXXXXXXX.table1 and want to test against both sets of tables, you can use the AUTHID preprocessor directive to switch which qualifier is used.

For example, if you set it to:

XDB(AUTHID=XXXXXXXX)

XXXXXXXX becomes the default qualifier. To run against both sets of data all you need to do is change the value of the AUTHID directive to YYYYYYYY and recompile. The next time you run your application you will be pointing to YYYYYYY.table1.

Parent topic: Static Binding


Examples of DBRM Directives

Restriction: This topic applies to Windows environments only.

The following are examples of various DBRM directives used together:

XDB(dbrm=mydbrm location=mvsprod grant-execute=public
    collection-id=nasecoll)
XDB(collection-id=nasecoll authid=naseprod autobind
    exist-check=required)

Directives can be entered on multiple lines or as one long string. Each string must start with "XDB", unless entered on the IDE/Build Settings/EXEC SQL/Preproc Additional directives entry field.

Parent topic: Static Binding


Examples of Autobinding Multiple DBRM's

Restriction: This topic applies to Windows environments only.

The following are examples of how to autobind a program and generate multiple DBRM's:

XDB(dbrm=mydbrm1;mydbrm2 location=mvsprod;mvstest
    grant-execute=public collection-id=nasecoll;dbnats
    autobind)
XDB(collection-id=nasecoll authid=naseprod;nasetest
    autobind dbrm=testdbrm1;testdbrm2 exist-check=required )

When multiple directives are specified, they must be delimited by a semi-colon with no spaces in between. Commas and blanks are option delimiters and may cause the directive string to not be processed correctly.

Parent topic: Static Binding
Related information
Preprocessor Directives and Options


Security

Restriction: This topic applies to Windows environments only.

SQL Option security measures control access to the system and protect data stored in table objects. If the security option is turned on at both the server and on the client, you will be prompted for a user ID and password when you compile using the VALIDATE preprocessor directive or execute a program containing embedded SQL.

  • Using the Logon and Logoff Commands
  • Validating Tables
Parent topic: SQL Option Preprocesor Guide


Using the Logon and Logoff Commands

Restriction: This topic applies to Windows environments only.

Use the SQL Option Logon and Logoff commands to avoid repeatedly logging into an XDB Server or SQL Option Link during the compile and test phase of development.

To log on to the SQL Option Server once per session, follow these steps:

From the Tools menu, select SQL Option

Select Logon

Enter your user ID and password

The SQL Option Server will automatically reuse your user ID and password each time you compile or execute the program, until you select Logoff or restart your system.

Parent topic: Security


Validating Tables

Restriction: This topic applies to Windows environments only.

The following describes how to set up your environment to validate tables during the compile process:

  • With Security Off, the user ID will be the same authorization ID defined as the primary ID unless you define a secondary ID.
  • With Security On, the user ID will be the same ID that you enter in the logon screen and optionally the secondary ID if defined (not applicable to SQL Option Link).

To access tables with the same user ID and authorization ID, use the VALIDATE preprocessor directive. To access tables with different user ID and authorization ID, do one of the following:

  • Use VALIDATE and AUTHID preprocessor directives.
  • Define group IDs or issue a GRANT to the user ID to have access to the authorization ID defined in the AUTHID preprocessor directive.
  • Define secondary IDs.
Parent topic: Security


DSNTIAR Facility

Restriction: This topic applies to Windows environments only.

The SQL Option DSNTIAR facility, or DSNTIAC for CICS programs, converts an SQL return code into a character string error message (similar to the IBM DSNTIAR and DSNTIAC facility on the mainframe). It takes an SQL return code from the SQLCODE element of comm-area (usually, SQLCA), and converts it to a descriptive character string. The resulting string is placed in the output area error-message, which is an array. The first element of error-message indicates the length of the message to follow. The second element is the actual message, which is usually defined as a string of the logical record length, error-rec-length, occurring n times. If at run time, the length of the message to be output is larger than one logical record (error-rec-length), and the message is treated as a set of fixed length records of length error-rec-length. The message is word wrapped and indented based on the logical record length. Every logical record begins with a space for carriage control.

  • Calling DSNTIAR or DSNTIAC
  • Example
Parent topic: SQL Option Preprocesor Guide
Related information
Calling DSNTIAR or DSNTIAC


Calling DSNTIAR or DSNTIAC

Restriction: This topic applies to Windows environments only.

The format for calling DSNTIAR from a COBOL program is:

CALL 'DSNTIAR' USING comm-area
                     error-message
                     error-rec-length

The format for calling DSNTIAC from a CICS COBOL program is:

CALL 'DSNTIAC' USING comm-area
                     error-message
                     error-rec-length

where:

comm-area | The communications area to be used, generally set to SQLCA. The SQLCODE element of this area should contain the error code for which DSNTIAR will generate a message.
error-message | An array of records of size error-rec-length used to store error message output. The two components of the error-message array are:
error-length | containing an integer indicating the length of the second element, error-text. error-length >= 240.
error-text | which is the actual message. Generally this message is defined as an array of strings, each having a length of error-rec-length, and occurring n times so that error-length is the larger of 240 and error-rec-length * n.
Code | Description
Error-rec-length | A n integer indicating the logical record length of output messages. 72 <= error-rec-length <= 240. If the message is longer than error-rec-length, several logical records will be used to store it.
0 | Successful execution.
4 | More data was available than could fit into the provided message area.
8 | The error-rec-length was not within acceptable limits. (72 <= error-rec-length <= 240)
12 | The message area was not large enough. Message length was >= 240.
16 | Error in message routine.

The following table shows the return codes that result from calling the DSNTIAR or DSNTIAC utility.

Code | Description
0 | Successful execution.
4 | More data was available than could fit into the provided message area.
8 | The error-rec-length was not within acceptable limits. (72 <= error-rec-length <= 240)
12 | The message area was not large enough. Message length was >= 240.
16 | Error in message routine.
Parent topic: DSNTIAR Facility


Example

Restriction: This topic applies to Windows environments only.
 01 ERROR-MESSAGE.
     02 ERROR-LENGTH PIC S9(4) COMP VALUE +288.
     02 ERROR-TEXT PIC X(72) OCCURS 4 TIMES.
 77 ERROR-REC-LENGTH PIC S9(9) COMP VALUE +72.
    ...
     CALL 'DSNTIAR' USING SQLCA ERROR-MESSAGE ERROR-REC-LENGTH
Parent topic: DSNTIAR Facility


XDB Preprocessor

Restriction: This topic applies to Windows environments only.

The XDB Preprocessor uses a type of preprocessor interface called an External Compiler Module (ECM) interface which is tightly integrated with the Compiler and debugger. The ECM only gets passed statements that begin with EXEC SQL.

  • Setting the XDB Preprocessor and Compiler Directive Options
    Instructions on the methods provided to set the XDB preprocessor and its options.
  • XDB Compiler Directive Options
  • Setting SQL Option Background Syntax Checking Options
    Explains how to set options that determine the level at which the XDB preprocessor checks syntax in the background.
Parent topic: SQL Option Preprocesor Guide


Setting the XDB Preprocessor and Compiler Directive Options

Restriction: This topic applies to Windows environments only.
You can specify the XDB preprocessor and its directive options using any of the following methods:
In your Enterprise Developer Project
Before compiling from within Enterprise Developer:
  1. Open your project properties and expand Micro Focus > Project Settings > COBOL > SQL Settings.
    Note: You can also set compiler directive options under Micro Focus > Build Configurations > COBOL > SQL Settings. If you do this, the setting applies only when the build configuration is active, and the compiler directive option is not set to something else in the Project Settings or on the program level.
  2. If unchecked, check Enable configuration-specific settings and Use SQL Preprocessor.
  3. From the Preprocessor Type drop-down list, select XDB.
  4. Use the grid to select directive options and set appropriate values. Click Apply after each setting.

Alternatively, you can enter the preprocessor specification and options as additional directives:

  1. Open your project properties and expand Micro Focus > Project Settings > COBOL.
    Note: You can also set the preprocessor under Micro Focus > Build Configurations > COBOL. If you do this, the setting applies only when the build configuration is active, and the preprocessor is not set to something else in the Project Settings or on the program level.
  2. On the COBOL page, check Enable file specific settings.
  3. Click in the Additional directives field and type:
    XDB[(XDBdirOpts)]

    Where XDBdirOpts is one or more additional directive options, each separated by a space.

On the Command Line
Use the XDB compiler directive, followed by optional preprocessor options:
XDB[(XDBdirOpts)]

Where XDBdirOpts is one or more additional directive options, each separated by a space.

In a Directives File
You can include XDB preprocessor directives in the cobol.dir system-wide directives file, a user directives file, or both. See System-wide Directives File, cobol.dir and User Directives File for details.
Embedded in a Program
You can also specify the XDB preprocessor and compiler directive options on the program level by embedding a $SET statement into the program itself starting in column 1 on the first line of the program:
$SET XDB

Where XDBdirOpts is one or more directive options, each separated by a space.

Important: Use this method only when the program requires a preprocessor different from other programs in an application.
Parent topic: XDB Preprocessor
Related concepts
Specifying an SQL Preprocessor and Compiler Directive Options
Related reference
User Directives File
System-wide Directives File, cobol.dir
XDB Directive Options


XDB Compiler Directive Options

Restriction: This topic applies to Windows environments only.

The SQL Option for DB2 preprocessor is specified by the XDB compiler directive, which is used with several options. Certain of these options, such as DB2, are automatically set to a default value. Most XDB compiler directive options have an alternate (or negative) syntax whereby the condition established by the option can be turned off. XDB compiler directive options are not case sensitive. For a complete list of options for the XDB compiler directive, see the topic XDB Directive Options.

For a list of XDB preprocessor error messages, see the topic SQL Preprocessor Errors.

Parent topic: XDB Preprocessor
Related information
XDB Directive Options
SQL Preprocessor Errors


Setting SQL Option Background Syntax Checking Options

Restriction: This topic applies to Windows environments only.
Before compiling an XDB application, you can set options that determine the level at which the XDB preprocessor checks syntax in the background. To do this, click Window > Preferences > Micro Focus > COBOL > Editor > XDB Background Parse. Select one of the following options:
No checking
The preprocessor does not connect to the DBMS and does not validate EXEC SQL statements; however, the preprocessor does check host variables.
Basic
The preprocessor does not connect to the DBMS and does not validate EXEC SQL statements; however, the preprocessor does check simple SQL statements and host variables.
Complete
This option sends all embedded SQL statements to the DBMS for validation, and requires a connection to the DBMS used by the program. Select this option for database providers that do not require SQL statement execution to perform validation.

See your Eclipse documentation for information on setting properties.

Parent topic: XDB Preprocessor


How to...

Restriction: This topic applies to Windows environments only.
  • To access SQL Option for DB2 tools
  • To add a Data Source Name (DSN) for an ODBC driver
  • To install and uninstall the ODBC driver for SQL Option
  • To log onto an XDB Server
  • To log off an XDB Server
  • Bind Utility
  • Declaration Generator
  • Link Configuration
  • Link Utility
  • Migrate Utility
  • Options Utility
  • SQL Wizard
  • SQL Option Server Administration
Parent topic: SQL Option for DB2


To access SQL Option for DB2 tools

Restriction: This topic applies to Windows environments only.
From your Windows desktop:
Windows 7 and Earlier
  1. From your Windows desktop, click Start > All Programs > Micro Focus Enterprise Developer > Data Tools > SQL Option for DB2.
  2. Depending on the tool you want to run, expand Client, Configuration, or Server.
  3. From your Windows desktop, click a tool on the list to start it.
Windows 8.1
  • From the Windows Start screen, click the tile that corresponds to the tool you want to start.
Windows 10 and Later
  • From your Windows desktop, click Start > Micro Focus Enterprise Developer; then click the tool you want to start.
From Eclipse:
  • From your Windows desktop, click Run > Tools > Data Tools > SQL Option for DB2 and select a tool from the submenus.
Parent topic: How to...


To add a Data Source Name (DSN) for an ODBC driver

Restriction: This topic applies to Windows environments only.
  1. Start the ODBC Data Source Administrator. If you need instructions, see To start the ODBC Data Source Administrator.
  2. On the System DSN tab, click Add.
  3. Select Micro Focus XDB for Studio 6.0, from the list of ODBC drivers.
  4. Click Finish.
  5. Configure the DSN by filling in the following fields:
    • Data Source Name - Any name you choose.
    • XDB Path – Accept the default of %ProgramData%\Micro Focus\Enterprise Developer\mfsql\cfg.
    • Connection – Choose between local and remote. If you choose remote, specify the IpAddress and TcpPort of your XDB server.
    • Server – The name of your XDB Server.
    • Location – The XDB location you want to use.
    • User ID – The XDB userid to use when connecting with this data source.
    • Current SQLID – The authorization ID to use when connecting with this data source (optional). If you don't specify an SQLID, the UserID is used.
  6. Click OK to close the ODBC Driver Setup window.
  7. Click OK to close the ODBC Data Source Administrator.
Parent topic: How to...
Related tasks
To start the ODBC Data Source Administrator
Related information
To install and uninstall the ODBC driver for SQL Option


To install and uninstall the ODBC driver for SQL Option

Restriction: This topic applies to Windows environments only.
  1. To install the ODBC driver:
    1. At an Enterprise Developer command prompt, enter:

      xdbodbcinst -i -p product-identifier

      Where product-identifier is one of the following:
      • MFE3.1
      • NETX5.1
      • NETX6.0
      • DX4.0
      Note: The NETX6.0 driver is installed by default when you install Enterprise Developer.
    2. Create and configure Data Source Names (DSNs) for the driver.
  2. To uninstall the ODBC driver, enter the following at an Enterprise Developer command prompt:

    xdbodbcinst -u -p product-identifier.

Parent topic: How to...
Related information
To add a Data Source Name (DSN) for the ODBC driver for SQL Option


To log onto an XDB Server

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > Log On.
  2. Enter your user name (AuthID) and password.
  3. Click OK.
Note: You need only log on to an XDB Server if server security is enabled. To access an XDB Server that has security enabled, you must enable client security before you try to log on.
Parent topic: How to...
Related information
To log off an XDB Server


To log off an XDB Server

Restriction: This topic applies to Windows environments only.
  • From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > Log Off.
Parent topic: How to...
Related information
To log on to an XDB Server


Bind Utility

Restriction: This topic applies to Windows environments only.
  • To bind an application to a DB2 database
  • To create a default DBRM and package in DB2 for XDB Link
  • To modify an existing package
  • To rebind
  • To drop a package from DB2
  • To bind a DBRM to DB2 from the command line
  • To create a bind transaction file
Parent topic: How to...


To bind an application to a DB2 database

Restriction: This topic applies to Windows environments only.
  1. Build your application.
  2. Ensure that client security for SQL Option is enabled.
  3. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Bind Utility.
  4. Select the location of the DB2 database from the Remote Location list.
  5. Type your current SQLID in SQLID.
  6. Click Bind.
  7. Make the selections you require on the Bind Package dialog box.
  8. Click OK.
Note: You need only bind an application when you are executing static SQL against a remote DB2 location accessed using DRDA. The database must be configured in system tables on the gateway XDB Server. Contact your system administrator if you experience difficulty in locating or binding to a DB2 database.
Parent topic: Bind Utility
Related information
To enable client security


To create a default DBRM and package in DB2 for XDB Link

Restriction: This topic applies to Windows environments only.

Before you can use XDB Link, you must create a default DBRM for the link, and bind it to DB2. The default DBRM creates a package that XDB Link uses to execute dynamic SQL statements from your application, and to execute statically-bound SQL statements contained in the XDB Link program itself.

Follow these directions only once for each DB2 location with which you will use the XDB Link. See the Link Configuration Guide for more information.

Note:

Do not use the same default package in DB2 for more than one user group or application. To support multiple user groups or applications, you must generate a separate default DBRM and package for each on. After the first application or group uses the Gateway Profile Utility's default values, the development team must agree on the package name and collection ID with which to identify the remaining default packages. See the Link Configuration Guide for more information.

  1. In the Bind Utility window, from the Remote Location drop-down list, select the desired DB2 location.
  2. Click Default. The Create Default DBRM dialog box appears.
  3. Specify the Collection ID, Package Name, Host System, and number of Dynamic Sections.
  4. Click Create. Bind generates a default DBRM that you will use to create a package for the Link. The DBRM is stored locally in your default working directory as a .DBR file.
    Note:

    The DBRM for XDB Link contains three packages. The name of these packages are derived by combining the XDB Link package name with the letters A, B and C. For example, if your package name is XDBSYS, packages XDBSYSA, XDBSYSB and XDBSYSC are created.

  5. In the Bind Utility main window, click Bind. The Bind Package dialog box appears.
  6. In the Bind Package dialog box, select the name of the DBRM file you just created from the DBRM File Name drop-down list.
  7. If desired, set the Package Version, Isolation Level, and Action.
  8. If desired, click the Bind... button to configure additional bind options.
  9. If desired, click the Format... button to specify data formats associated with the DBRM.
  10. Click Execute. Bind creates a package in the selected DB2 location and updates the relevant DB2 tables. The Status bar indicates when the procedure is complete.
Note:
  • The Bind Utility automatically grants execute privileges to all users. Use the SQLWizard to revoke GRANT EXECUTE privileges where necessary.
  • Each time you bind a DBRM, the Bind Utility creates a log file (.LOG) in which it records all errors that occur during the bind. The .LOG file is stored in locally in the same directory as your DBRM (.LOG).

    If no error has occurred during the binding of a particular DBRM, the log file does not exist.

Parent topic: Bind Utility
Related information
SQL Option Link Configuration Guide


To modify an existing package

Restriction: This topic applies to Windows environments only.

When you generate a DBRM in the Static Bind Administrator, it automatically binds the DBRM, using default bind options, to create the package in DB2.

Follow this procedure if you would like to modify the package by binding the DBRM again with different parameters.

  1. In the Bind Utility window, from the Remote Location drop-down list, select the DB2 location of your application's package.
  2. Click Bind. The Bind Package dialog box appears.
  3. Select the DBRM you want to bind from the DBRM File Name drop-down list.
  4. If desired, set the Package Version, Isolation Level, and Action.
  5. If desired, click the Bind... button to configure additional bind options.
  6. If desired, click the Format... button to specify data formats associated with the DBRM.
  7. Click Execute. Bind creates a package in the selected DB2 location and updates the appropriate DB2 system tables. The Status bar indicates when the procedure is complete.
Note:

Each time you bind a DBRM, the Bind Utility creates a log file (.LOG) in which it records all errors that occur during the bind. The .LOG file is stored in locally in the same directory as your DBRM (.DBR).

If no error has occurred during the binding of a particular DBRM, the .LOG file does not exist.

Parent topic: Bind Utility


To rebind

Restriction: This topic applies to Windows environments only.

The Rebind procedure does not read the DBRM. Rather, it recalculates path optimizations for the DBRM information in the existing package.

If you want bind to read the DBRM, see To Modify an Existing Package.

  1. In the Bind Utility window, from the Remote Location drop-down list, select the host location of the package you want to rebind.
  2. Click Rebind. The Rebind Package dialog box appears.
  3. Select the package you want to rebind from the Package drop-down list.
  4. If desired, specify a Package Version and the Isolation Level.
  5. If desired, click Bind under Modify Options to set other rebind options.
  6. Click Execute. The Bind Utility rebinds the package using the options you specified.
Parent topic: Bind Utility
Related information
To modify an existing package


To drop a package from DB2

Restriction: This topic applies to Windows environments only.
  1. In the Bind Utility window, from the Remote Location drop-down list, select the host location of the package you want to drop.
  2. Click Drop. The Drop Package dialog box appears.
  3. From the Package drop-down list, select the package you want to remove from the host
  4. Click Execute to drop the package.
Note:

When you drop a package, it is deleted immediately, without confirmation.

Parent topic: Bind Utility


To bind a DBRM to DB2 from the command line

Restriction: This topic applies to Windows environments only.

Use the command line if you:

  • Need to run a bind unattended (from a scheduler, for example)
  • Run a particular bind routinely
  • Wish to bind multiple programs in a single operation

Enter the following at your system command line:

BIND40N /d dbr-file /l location [option option option ...]

or

BIND40N /f transaction-file [option option option ...]

where:

dbr-file
The name of the DBRM you want to bind. If you do not specify a path, your DBRM must be in the current directory or in the XDB application path (as specified by Options). If you do not specify an extension, your DBRM must have a .DBR extension.
location
The name of the location to which the DBRM will be bound. (This is the name of the DB2 subsystem as it is registered with XDB Link.)
transaction-file
The name of the bind transaction file (.BND). Be sure to include a space between /f and the filename.
/c stop-status
stop-status can take one of the following values:
N
causes the bind to stop if an error occurs. This is the default.
Y
causes the bind to continue when an error occurs.
/s sqlID
sqlID is the ID used to set the current SQL ID at the time the package is bound.
/name=userID
userID is the user ID that will be used when the Bind Utility logs on the XDB Server.

If the /name option is not specified, you will be prompted for a user ID when the Bind Utility begins to execute.

/pass=password
password is the password that will be used when the Bind Utility logs on the XDB Server.

If the /pass option is not specified, you will be prompted for a password when the Bind Utility begins to execute.

/l location
location is the name of the remote location to which the DBRM will be bound. (This is the name of the DB2 subsystem as it is registered on the XDB Link.)
/existencechecking check-status
check-status can take one of the following values:
optional
creates a package even if the required database objects do not exist. This is the default.
required
creates a package only if the objects exist.
/grantexecute priviliges
priviliges can take one of the following values:
public
grants execute privileges to public. This is the default.
authid
grants execute privileges to authid.
/blocking block-mode
block-mode can take one of the following values:
FSR
Forced Single Row does not use block fetching regardless of cursor type.
SR
Single Row uses block fetching for read-only cursors and fetches a row at a time for ambiguous cursors.
LB
Limited Block uses block fetching for read-only and ambiguous cursors. This is the default.
/defaultchar subtype
subtype can take one of the following values:
BITS
specifies that the target relational database uses the FOR BITS DATA SQL character subtype for all new character columns for which an explicit subtype is not specified.
SBCS
specifies that the target relational database uses the FOR SBCS DATA SQL character subtype for all new character columns for which an explicit subtype is not specified.
DBCS
specifies that the target relational database uses the FOR MIXED DATA SQL character subtype for all new character columns for which an explicit subtype is not specified.
SYSDEFAULT
specifies that the target relational database uses the system default character subtype for all new character columns for which an explicit subtype is not specified. This is the default (and recommended) setting.
/d dbr-file
dbr-file is the name of the DBRM you want to bind. If you do not specify a path, the file must be in the current directory or in the XDB application path (as specified by Options). If you do not specify an extension, your DBRM must have a .DBR extension.
Note:

If you are running a bind unattended, be sure to include the /name and /pass options.

Parent topic: Bind Utility
Related information
To create a bind transaction file


To create a bind transaction file

Restriction: This topic applies to Windows environments only.

To run the Bind Utility in batch mode from the command line, you must create a .BND file that contains at least one transaction. A transaction is a statement that specifies the name of a DBRM file and the location to which it will be bound. A .BND file is an ASCII text file. It can contain multiple bind transactions.

Use any ASCII text editor and type each transaction using the following format. Be sure to include a semicolon at the end of each transaction.

/d dbr-file /l location [/s sqlID];

where:

dbr-file | is the name of the DBRM you want to bind. If you do not specify a path, the file must be in the current directory or in the XDB application path (as specified by Options).
location | is the name of the location to which the DBRM will be bound. (This is the name of the DB2 subsystem as it is registered on the XDB Link.)
sqlID | is the ID to which the current SQL ID will be set when the package is bound. If SqlID is not specified, the current SqlID assignment is used (the assignment specified on the XDBBIND command line or assigned to an earlier transaction in the .BND file, whichever is more recent). Otherwise, AuthID is used.
Parent topic: Bind Utility


Declaration Generator

Restriction: This topic applies to Windows environments only.
  • To generate a copybook for a table
  • To run interactively
  • Creating a COBOL Copybook File
  • To create a C header file
  • Creating a PL/I Include File
  • Running From the Command Line
  • Running in Batch Mode
  • Creating a .DGE File
  • Running a .DGE File
Parent topic: How to...


To generate a copybook for a table

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > Declaration Generator.
  2. On the XDB Declaration Generator window, specify the table you require in the Table group.
  3. In the Declaration group, type a location and name for the copybook in the Output File field.
  4. Optionally, in the Structure Name field, type a name for the group data item to be created.
  5. Optionally, click Options to specify a level for the group data item to be created.
  6. In the Field Prefix group, type a prefix to be added to the column names in the table to create host variables. For example, you might use EMP as the column name prefix for a table called EMPLOYEES.
  7. Select Text if you want the column name to be appended to the specified prefix to create the host variable name.

    Alternatively, select Numbered if you want the column's numeric position in the table to be appended to the specified prefix to create the host variable name.

  8. In the Computation group, click the data format you require for the host variables.
  9. Click Generate.

A copybook containing host variables for accessing the specified table is created.

Tip:

Click Save As to save the settings you made on the Declaration Generator window. You can use the .DGE file that is produced to run the Declaration Generator in batch mode. For more information, see Running in Batch Mode in the Declaration Generator help.

Parent topic: Declaration Generator


To run interactively

Restriction: This topic applies to Windows environments only.

To generate a declaration file in interactive mode (through a dialog box), start the Declaration Generator as described below. To specify the procedure from the command line, see Running From the Command Line.

To use the Declaration Generator utility:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > Declaration Generator.
  2. Provide your AUTHID and desired LOCATION if the Connect dialog box is displayed.

    You must have SELECT privileges on the table for which you are generating a declaration and on the following system tables:

    • SysIBM.SYSLOCATIONS
    • SysIBM.SYSTABLES
    • SysXDB.SYSACFUsers
  3. In the Declaration Generator dialog box, select the language in which you want the declaration file written, and complete the remainder of the dialog box, then click GENERATE.
Parent topic: Declaration Generator
Related information
Running From the Command Line
Creating a COBOL Copybook File


Creating a COBOL Copybook File

Restriction: This topic applies to Windows environments only.

In COBOL, a copybook file is used to define data elements that can be referenced by many programs. When the Declaration Generator creates a declaration for a COBOL program, it writes it to a copybook file (.cpy file).

To create a COBOL copybook, start the Declaration Generator utility, then follow the steps below:

  1. In the Language group box, click the COBOL button.
  2. In the Table group box, select the Location, AuthID and Table Name that identifies the table for which you want to create a copybook.
  3. If you want to change the name of the file to which the copybook is written, type a new name in the Output File field (the Declaration Generator automatically places a default name based on the table name in this field).

    If you don't specify a path, the copybook is written to the first directory specified in the COBCPY environment variable. If this variable isn't found, the copybook is written to the current application path (the application path is specified in the PATHS tab in Options).

    If you specify a file that already exists, you are given the choice of appending to it or overwriting it at run time.

  4. If you want to change the name of the record description, type a new name in the Structure field.
  5. If you want to add a prefix to each of the elementary item names, type it in the Field Prefix box. You can end the prefix with a special character such as a dash (-) to set it off from the rest of the name. For example, if a prefix of EMP- were specified, field names would be written as follows:
    EMP-lname PIC X(15)
        EMP-fname PIC X(10)
        EMP-dept PIC X(12)
        .
        .
        .

    Remember the COBOL variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the compiler or one that might make the elementary item name too long.

  6. When you specify a prefix, you can optionally check the Numbered option to assign numbers instead of field names to the elementary items. If Numbered were checked using the EMP- prefix in last example, the declaration would be written as follows:
    EMP-001 PIC X(15)
        EMP-002 PIC X(10)
        EMP-003 PIC X(12)
        .
        .
        .
  7. In the Computation box, select the COMP type that you want use for the table's Int and Smallint fields.
  8. Click Options and set the following options as needed:
    For this option... | Specify...
    Level | The level number you want assigned to the record description. If you leave this field blank, Level 1 is assigned.
    Graphic Type | The PIC type you want to use for graphic, vargraphic and long vargraphic fields in the table.
    Page Size | The page size you want assigned to long varchar, long vargraphic, and long varbinary fields.
  9. Click OK to close the Declare Options dialog.
  10. If you want to save your specifications, click the Save As button, specify a file name and click OK. The specifications will be saved to a .DGE file, which can be used as input to the Declaration Generator's batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.
  11. Click the Generate button to generate the COBOL copybook file.
Parent topic: Declaration Generator


To create a C header file

Restriction: This topic applies to Windows environments only.

In C, a header file declares constants, functions and structures. The header file can be referenced (using the #include statement) by many programs. When the Declaration Generator creates a declaration for a C program, it writes the declaration to a header file (.h file). It also generates a corresponding array of short data types to hold the null-indicator variable for each column in the table.

To create a C header file, start the Declaration Generator utility, then follow the steps below:

  1. In the Language group box, click the C button.
  2. In the Table group box, select the Location, AuthID and Table that identifies the table for which you want to create a header file.
  3. If you want to change the name of the file to which the header file is written, type a new name in the Output File field (the Declaration Generator automatically places a default name based on the table name in this field).

    If you don't specify a path, the header file is written to the directory specified by the current application path (the application path is specified in the PATHS tab in Options).

    If you specify a file that already exists, you are given the choice of appending to it or overwriting it at run time.

  4. If you want to change the name of the structure, type a new name in the Structure field.
  5. If you want to add a prefix to each element name, type it in the Field Prefix box. You can end the prefix with a special character such as an underscore (_) to set it off from the rest of the name. For example, if a prefix of emp_ were specified, element names would be written as follows:
    char emp_lname[15];
        char emp_fname[10];
        char emp_dept[12];
        .
        .
        .

    Remember to take into account C variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the compiler or one that might make the variable name too long.

  6. If you want to assign numbers instead of field names as element names, check the Numbered option. (This option can be selected only when a field prefix is used. See the previous step.) If the Numbered option were checked in the example above, the declaration would be written as follows:
    char emp_001[15];
        char emp_002[10];
        char emp_003[12];
        .
        .
        .
  7. Click the Options button.
  8. In the C Declaration Options dialog box, specify the way in which you want the structure written.
    • Use the options in the Structure Elements box to specify the case in which you want the element names written.
    • Use the Declare The Structure option to assign a variable name to the structure as shown in the following example. The variable name is derived from the Structure field specified in step 4).
      .
        .
        .
        double emp_payrate;
        double emp_com;
        } dcl_employee;

    If you don't set Declare The Structure, the structure is written as a data-type definition. The name specified in the Structure field is assigned as the name of the data type, as shown in the following:

    struct dcl_employee
        {
        short emp_ssn;
        char emp_lname[11];
        char emp_fname[11];
        .
        .
        .
  9. If you want to save your specifications, click the Save As button, specify a file name and click OK. The specifications will be saved to a .DGE file, which can be used as input to the Declaration Generator batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.
  10. Click the Generate button to generate the C header file.
Parent topic: Declaration Generator
Related information
Running in Batch Mode
Example C Structure


Creating a PL/I Include File

Restriction: This topic applies to Windows environments only.

In PL/I, an include (.inc) file declares constants, functions and structures. The include file can be referenced (using the %include statement or by EXEC SQL include ) by many programs. When the Declaration Generator creates a declaration for a PL/I program, it writes the declaration to a include file. If you choose, it also generates a corresponding array of null-indicator variables for each column in the table.

To create a PL/I include file, start the Declaration Generator utility, then follow the steps below:

  1. In the Language group box, click the PL/I button.
  2. In the Table group box, select the Location, AuthID and Table that identifies the table for which you want to create a header file.
  3. If you want to change the name of the file to which the include file is written, type a new name in the Output File field. (The Declaration Generator automatically places a default name based on the table name in this field.)

    If you don't specify a path, the include file is written to the first directory specified in the COBCPY environment variable. If this variable isn't found, the include file is written to the current application path (the application path is specified in the PATHS tab in Options).

    If you specify a file that already exists, you are given the choice of appending to it or overwriting it at run time.

  4. If you want to change the name of the structure, type a new name in the Structure field.
  5. If you want to add a prefix to each element name, type it in the Field Prefix box. You can end the prefix with a special character such as an underscore (_) to set it off from the rest of the name. For example, if a prefix of emp_ were specified, element names would be written as follows:
    DECLARE
        1 DCLEMPLOYEE,
        5 EMP_E_NO BIN FIXED(15),
        5 EMP_LNAME CHAR(10),
        5 EMP_FNAME CHAR(10),
        .

    Remember to take into account PL/I variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the compiler or one that might make the variable name too long.

  6. If you want to assign numbers instead of field names as element names, check the Numbered option. (This option can be selected only when a field prefix is used. See the previous step.) If the Numbered option were checked in the example above, the declaration would be written as follows:
    DECLARE
        1 DCLEMPLOYEE,
        5 EMP_001 BIN FIXED(15),
        5 EMP_002 CHAR(10),
        5 EMP_003 CHAR(10),
  7. Click the Options button.
  8. In the PL/I Declaration Options dialog box, specify this option if you want the Declaration Generator to generate an array of indicator variables.
  9. If you want to save your specifications, click the Save As button, specify a file name and click OK. The specifications will be saved to a .DGE file, which can be used as input to the Declaration Generator batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.
  10. Click the Generate button to generate the PL/I include file.
Parent topic: Declaration Generator


Running From the Command Line

Restriction: This topic applies to Windows environments only.

You can create your declaration file without opening the Declaration Generator window. This is done by running the Declaration Generator and specifying its options from your Enterprise Developer command prompt.

To run the Declaration Generator from the Enterprise Developer command prompt, you call the dclg40n program using the following syntax:

dclg40n -tTableName [option1 option2 option3...]

where TableName specifies the name of the table for which a declaration file will be generated. Location and AuthID can be specified using location.authid.tablename notation.

The following table describes the command line options.

Option | Description
-a | Writes element names in a C structure in uppercase. If -a is not specified, element names are written in lowercase.
-cCompValue CompValue specifies the computation type assigned to COBOL binary integers.

CompValue must be one of the following numeric values:

  • 0 - uses COMP
  • 4 - uses COMP-4
  • 5 - uses COMP-5

If this option is not included, 0 (COMP) is used.

-d | Includes a variable declaration for the defined C structure. If -d is not specified, a C structure is defined, but it is not declared as a variable.
-fDecFileName DecFileName specifies the name of the file to which the Declaration Generator will write the declaration.

If you do not include this option, the source table name will be used as the declaration file name (with the extension .h for C, .cpy for COBOL, or .inc for PL//I).

If a path is not specified, the file is written to the directory specified in the application path. Do not include an extension with the file name.

If you specify a file name that already exists, and the -r option is not specified, the Declaration Generator will ask whether you want to replace or append to the file at run time. If -r is specified, the file will automatically be overwritten (see -r below).

-gPicType Pictype specifies the COBOL data type that will be used for graphic, vargraphic and long vargraphic fields.

Pictype must be one of the following:

  • PICN declares graphic fields as PIC N(x).
  • PICG declares graphic fields as PIC G(x) DISPLAY-1
  • PICX declares graphic fields as PIC X(x)

If this option is not included, PICN is used.

-h | Opens the Declaration Generator help file.
-iIniFileName IniFileName specifies the disk, directory, filename and extension of the initialization file to be used.

If this option is not included, the XDB.INI file in the current working directory is used.

-kPageSize PageSize specifies the page size that will be assigned to COBOL declarations for long varchar, long vargraphic, and long varbinary fields.

PageSize must be one of the following:

  • 4k
  • 32k

If this option is not included, 4K is used.

-lLanguage Language specifies the language in which the Declaration Generator will write the declaration file.

Language must be one of the following:

  • C
  • COBOL
  • PLI

If this option is not included, COBOL is used.

-n | Runs the Declaration Generator without stopping on errors or for user responses.
-pPrefix Prefix is a 1 - 27 character string to be prefixed to each field name to form an element name.

For example, if the option -pemp_ were used, the field names ssn and lname would become element names emp_ssn and emp_lname, respectively.

-r | Automatically replaces a declaration file if it already exists. If -r is not specified, the program asks whether to replace or append to a file that already exists.
-sStructure Structure specifies the name to be assigned to the record definition (COBOL) or structure (C).

If this option is not included, the table name is assigned to the structure.

-uNames Specifies whether field names will be concatenated with the string specified by -pPrefix (above), or whether they will be replaced with numbers.

If Names is set to real, field names are concatenated to Prefix.

If Names is set to n/a, a 3-digit, sequential number is concatenated to prefix.

For example, if the option -ureal were used, field names would be concatenated with the string specified in -pPrefix.

If -psales- and -un/a were used, the prefix sales- would be combined with a three-digit number to form element names such as sales-001, sales-002, and so on.

-vLevel | Level assigns a level number to a COBOL record description. If -v is not used, field-level definitions are set to 2.

Example Command Line

The following example shows the command line for a COBOL copybook created for an EMPLOYEE table on a Windows system.

dclg40n -ic:\xdb\xdb.ini -tinstall.employee -lcobol -femployee.cpy -sdclemployee -psales -ureal -c4 -v2

In this example, the Declaration Generator will assign the name dclemployee to the record definition, and will prefix each elementary item with the string sales. COMP-4 class will be assigned to int and smallint fields. Level 2 will be assigned to the field-level definitions.

Parent topic: Declaration Generator


Running in Batch Mode

Restriction: This topic applies to Windows environments only.

If you have several tables for which you want to generate declaration files, you can create them using the Declaration Generator's "batch mode."

In batch mode, you can type the specifications for one or more tables in a .DGE file, then use the file as input to the Declaration Generator program. This process lets you generate declaration files for several tables in a single operation rather than generating them one-by-one interactively or from the command line.

Parent topic: Declaration Generator


Creating a .DGE File

Restriction: This topic applies to Windows environments only.

To run the Declaration Generator in batch mode, you must create a .DGE file specifying the tables for which you want declaration files generated, and the language(s) in which you want the declaration files written.

A .DGE file can be created in two ways:

  • You can enter your specifications in the Declaration Generator window and save them with the SAVE AS button. See Running Interactively.
  • You can create a .DGE file using any ASCII text editor.

The .DGE file must be stored in the DEFAULT APPLICATION PATH as specified in Options, PATHS tab, and it must have a .DGE extension.

A .DGE file contains the instructions needed to generate one or more declaration files. Each line in the file specifies a single "transaction," which creates a single declaration file in a single language (COBOL, C or PL/I). A transaction is specified as follows:

            tablename
            decFileName [option1
            option2
            option3...]

Where:

tablename specifies the name of the table for which a declaration file is generated. You can specify location and AuthID information using location.authid.tablename notation.

decFileName specifies the name of the file to which the declaration statements are written.

  • Do not include path information in decFileName. The Declaration Generator automatically writes the file to the application path (the application path is specified in the PATHS tab of Options).
  • Do not include an extension in decFileName. An extension is automatically assigned based on the language you've specified.

The option parameters specify the programming language, structure name and other parameters, if you don't want to use the defaults. See

DGE File Transaction Options

The following table describes the optional parameters you can include in a transaction statement. If an option is not included in a transaction statement, a default value is used.

Option Description Example
a=Case Where Case determines whether C element names are written in upper or lower case.

If Case is set to upper, element names are written in uppercase.

If Case is set to lower, or if this option is not set, element names are written in lowercase.

 a=upper generates uppercase elements.
c=CompValue CompValue specifies the COMP type assigned to binary integers (for COBOL only; this option is ignored if language is set to C).

CompValue must be one of the following:

  • 0 - uses COMP
  • 4 - uses COMP-4
  • 5 - uses COMP-5
  • 0 (COMP) is the default.
 c=4 assigns COMP-4 to binary integers.
d=DStuc Where DStruc determines whether a C structure is written as a variable declaration.

If DStruc is set to decl, the structure is declared as a variable.

If DStruc is set to nodecl, or if this option is not set, the C structure is defined as a data type, but is not declared as a variable.

 d=decl creates a variable declaration from the structure.
g=PicType Where Pictype specifies the COBOL data type that will be used for graphic, vargraphic and long vargraphic fields.

Pictype must be one of the following:

  • PICN declares graphic fields as PIC N(x).
  • PICG declares graphic fields as PIC G(x) DISPLAY-1
  • PICX declares graphic fields as PIC X(x)
  • PICN is the default.
 g=PICG declares graphic fields as follows:

PIC G(x) DISPLAY-1,

k=PageSize Where PageSize specifies the page size that will be assigned to COBOL declarations for long varchar, long vargraphic, and long varbinary fields.

PageSize must be one of the following:

  • 4K
  • 32K
  • 4K is the default.
 k=32K assigns a 32k pages size to long variables.
l=Language Language specifies the language in which the declaration will be written. Language must be one of the following:
  • C
  • COBOL
  • COBOL is the default.
 l=C generates a C header file.

l=COBOL generates a COBOL copybook.
p=Prefix Prefix specifies the prefix that will be affixed to each of the element names.

Depending upon the state of the u=Names option, this prefix will either be concatenated with a field name or a number to form an element name.

See u=Names, below.

 p=sales- u=real

combines the prefix sales- with the field names to form element names such as sales-dept, sales-mgr, and so on.

p=sales- u=n/a

combines the prefix sales- with a three-digit number to form element names such as sales-001, sales-002, and so on.

s=Structure Structure specifies the name of the record definition (COBOL) or structure (C). This name must be valid for the chosen language.

If Structure is not specified, the following defaults are used:

  • For C: c_tablename
  • For COBOL: dcltablename
 s=c_SalesReps assigns the name c_SalesReps to the generated structure
u=Names Where Names specifies whether field names or numbers are concatenated to Prefix to form element names (see p=Prefix, above).

If Names is set to real, field names are concatenated to Prefix.

If Names is set to n/a, or if this option is not set, numbers are concatenated to Prefix.

 p=sales- u=real

combines prefix sales- with field names to form element names such as sales-dept,sales-mgr, and so on.

p=sales- u=n/a

combines the prefix sales- with a three-digit number to form element names such as sales-001, sales-002, and so on.

v=Level Where Level is an integer specifying the number to be assigned to the field-level definitions in a COBOL record description. v=3 writes level-3 field definitions, for example:
3 ST PIC X(2).
3 ZIP PIC X(5)
Parent topic: Declaration Generator


Running a .DGE File

Restriction: This topic applies to Windows environments only.

Once you have created a batch declaration file, you can run the batch version of the Declaration Generator from your Enterprise Developer command prompt.

To run the Declaration Generator in batch mode, you call the dclg40n program using the following syntax:

dclg40n [-iIniFile -r -n]-b FileName

where:

IniFile specifies the disk, directory, filename and extension of the initialization file to use. If this option is not included, the initialization file in the current working directory is used.

FileName is the name of the .DGE file containing the transactions you want to run. If you don't specify a path, the Declaration Generator looks for the .DGE file in the application path (the application path is specified by in the PATHS tab in Options).

-r and -n are options that affect the presentation of error messages and the treatment of existing declaration files. For more information about these options, see Running From the Command Line.

The following example generates the declaration files specified by the EMPDATA.DGE file.

dclg40n -b c:\BATCH\EMPDATA

The following example generates the declaration files specified by the EMPDATA.DGE file, using the EMP.INI initialization file.

dclg40n -iEMP.INI -b c:\BATCH\EMPDATA
Parent topic: Declaration Generator
Related information
Running From the Command Line


Link Configuration

Restriction: This topic applies to Windows environments only.
  • Configure the Host
  • Configure the PC
  • Configure DB2 Access
Parent topic: How to...


Configure the Host

Restriction: This topic applies to Windows environments only.
  • Configuring the Host for TCP/IP Access to XDB Link
  • XDB Link Host Option
  • Installing and Configuring the XDB Link Host Option
  • Starting the XDB Link Host Option on the Mainframe
  • Configuring the Host for SNA Access to XDB Link
  • Configuring DB2 to Accept DRDA Requests
Parent topic: Link Configuration
Related information
Configure the PC
Configure DB2 Access


Configuring the Host for TCP/IP Access to XDB Link

Restriction: This topic applies to Windows environments only.

If you are using TCP/IP to connect XDB Link to OS/390, and you are using a version of DB2 that does not support direct access to the DDF facility via TCP, you must install and configure the XDB Link Host Option on the host. This program receives TCP/IP packets containing DRDA-compliant requests from XDB Link and routes them to DB2 via APPC. If DB2 security is a concern, it is suggested the XDB Link be used in all cases.

Parent topic: Configure the Host
Related information
XDB Link Host Option
Installing and Configuring the XDB Link Host Option
Configure the Host


XDB Link Host Option

Restriction: This topic applies to Windows environments only.
  1. Before installing the XDB Link Host Option, verify the host IP address and reserve a port number for XDB Link.
  2. Install and configure the XDB Link Host Option.
  3. Start the XDB Link Host Option on the mainframe.
  4. Work with the Access List.
Parent topic: Configure the Host
Related information
Installing and Configuring the XDB Link Host Option
Starting the XDB Link Host Option on the Mainframe
The Access List


Installing and Configuring the XDB Link Host Option

Restriction: This topic applies to Windows environments only.

The following describes the steps to install and configure the XDB Link Host Option.

Note:

To install the software, you will need the information provided by your TCP/IP network administrator on the TCP XDBPARM worksheet. If you do not have a completed copy of this worksheet, get one before you begin.

To install the XDB Link Host Option

  1. Create and install JCL PDS with FB LRECL 80.
  2. Create and submit the following JCL to unload the INSTALL JCL file (file 1) of the installation tape:
    //jobname JOB jobcard information
        //STEP1 EXEC PGM=IEBGENER
        //SYSPRINT DD SYSOUT=A
        //SYSUT1 DD DSN=XDBLINK.V100T.INSTALL,DISP=OLD,
        // UNIT=inputdev,VOL=SER=volser,LABEL=(1,SL),
        // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3120)
        //SYSUT2 DD DSN=xdblink.v100.INSTALL,
        // DISP=(,CATLG),
        // UNIT=dasd,VOL=SER=vvvvvv, // DCB=*.SYSUT1,SPACE=(TRK,(1,1))
        //SYSIN DD DUMMY

    where:

    inputdev | is the tape input device unit parameter
    volser | is the input tape volume serial number
    xdblink | is the XDB Link installation data set prefix
    v100 | is the high-level data set prefix
    dasd | is the DASD device unit of the install data set to be created
    vvvvvv | is the volume serial number of the install data set
  3. Edit and submit the JCL created by step 2 (xdblink.v100.INSTALL). Correct errors and rerun the job if the return code is not zero.
  4. Edit the sample VTAM application definition for XDB Link in xdblink.v100.CNTL(VTAMLST). The value of the LU62 APPLID parameter must match the ACBNAME of the XDB Link Host Option. Also, the value of the APPLID PASSWORD parameter must match the PRTCT parameter of the application definition.
  5. Edit the sample access list in xdblink.v100.ACCESS.
  6. If you are a RACF user, edit and submit the sample JCL (optional) in xdblink.v100.CNTL(RACFACC) to protect the access list. Otherwise, create and submit equivalent JCL.
  7. Edit the xdblink.v100.CNTL(XDBGTF) member (optional) and copy it to a cataloged procedure library. Modify the DSNAME for IEFRDER to conform to the naming standards for your site.
  8. Edit the xdblink.v100.CNTL(GTFXDB) member for the GTF procedure (optional). USR=(xxx) must match the EID parameter in the parameter member.
  9. Edit the sample parameter member in xdblink.v100.PARAM(PARMTCP).
  10. Copy the VTAM application definition to the active VTAMLST library and put the major node into the ATCCONxx member of the VTAMLST library. VTAM must be cycled for the updated ATCCONxx member to take effect.
    Note:

    To avoid cycling VTAM, use the VTAM vary command to activate the major node.

  11. Edit the sample started task xdblink.v100.CNTL(#PROCLNK) and copy it to a system procedure library.
Parent topic: Configure the Host
Related information
Started Task Parameters
Configure the Host


Starting the XDB Link Host Option on the Mainframe

Restriction: This topic applies to Windows environments only.

The XDB Link Host Option must be running in order for XDB Link to access DB2 using TCP/IP. To start the Host Option, issue the following command from the system console:

S stcname

where stcname is the name of the started task created in step 11.

To display the status of the started task and verify that the correct port number is selected, use the following command:

F stcname, DISPLAY STATUS
Parent topic: Configure the Host


Configuring the Host for SNA Access to XDB Link

Restriction: This topic applies to Windows environments only.

To use XDB Link with SNA:

  1. Verify that VTAM is set up to allow independent LU6.2 access to host data. Have the VTAM systems programmer complete the VTAM Worksheet.
  2. Ensure that independent LU6.2 and 3270 support have been generated for the physical unit (PU) supporting XDB Link:
    • Create the PU.
    • Create an independent LU definition.
    • Create a mode entry that supports parallel sessions and is compatible with IBMRDB.
Note: Do not discard the VTAM worksheet when you are finished configuring VTAM. It contains information that you will use to configure other parts of XDB Link.
Parent topic: Configure the Host
Related information
VTAM Worksheet
Configuring XDB Link for DB2 Access


Configuring DB2 to Accept DRDA Requests

Restriction: This topic applies to Windows environments only.

To use XDB Link to access DB2 data on an OS/390 system, have a database administrator (DBA) or the DB2 system administrator configure DB2 to accept DRDA requests as described in the following steps.

To configure DB2 to accept DRDA requests from XDB Link

  1. Complete the DB2 worksheet and ensure that the Distributed Data Facility (DDF) is activated.
  2. Execute one of the following statements to add a record to the DB2 SYSIBM.LUNAMES table (for DB2 Version 5 and later) or to SYSIBM.SYSLUNAMES (for DB2 Version 4 and earlier). These statements enable any remote location (including XDB Link) to access DB2 if a valid user ID and password are supplied.

    For DB2 Version 4 and earlier, execute the following statement:

    INSERT INTO sysibm.syslunames (luname, sysmodename, usersecurity,encryptpswds, modeselect, usernames) VALUES (' ', ' ', 'C', 'N', 'N', ' ');

    For DB2 Version 5 and later, execute the following statement:

    INSERT INTO sysibm.lunames (luname, sysmodename, security_in, security_out, encryptpswds, modeselect, usernames) VALUES (' ', ' ', 'A', 'A', 'N', 'N', ' ');
  3. Execute the following statement to add a record to the DB2 SYSIBM.LOCATIONS table (for DB2 Version 5 and later) or to SYSIBM.SYSLOCATIONS (for DB2 Version 4 and earlier). This statement specifies the local location name for DB2:

    For DB2 Version 4 and earlier, execute the following statement:

    INSERT INTO sysibm.syslocations (location, loctype, linkname, linkattr) VALUES ('your-location-id', ' ', ' ', ' ');

    For DB2 Version 5 and later, execute the following statement:

    INSERT INTO sysibm.locations (location, loctype,   linkname, linkattr) VALUES ('your-location-id', ' ', ' ', ' ');
  4. Cycle DDF to put the updated tables into effect.
Note:

Do not discard the DB2 worksheet when you are finished configuring DB2. It contains information that you will use to configure other parts of XDB Link.

Parent topic: Configure the Host
Related information
DB2 Worksheet
Worksheets


Configure the PC

Restriction: This topic applies to Windows environments only.
  • Configuring TCP/IP Software for the PC
  • Configuring the Microsoft SNA Server
  • Installing the DLC Protocol
  • Configuring SNA Server 2.11
  • Configuring SNA Server 3.0
Parent topic: Link Configuration
Related information
Configure the Host
Configure DB2 Access


Configuring TCP/IP Software for the PC

Restriction: This topic applies to Windows environments only.

Use the following procedure to configure the TCP/IP software for XDB Link. Use your values from the TCP Host/Service worksheet to complete these steps.

To configure TCP/IP perform the following steps:

  1. Install a TCP/IP protocol. If a TCP/IP protocol is already installed (for example, Microsoft TCP/IP), ensure that it is enabled.
  2. Make a backup copy of the HOSTS and SERVICES files (under Windows 95, these files are called HOSTS.SAM and SERVICES.SAM).
    If you a running under... | Look for these files in...
    Windows NT | C:\WinNT\SYSTEM32\DRIVERS\ETC
    Windows 95 or 98 | C:\WINDOWS
  3. Add the following line to the HOSTS file:
    IPAddress IPName

    where:

    • IPAddress specifies the TCP/IP address of the host system. Use the value in J1 of the TCP Host/Service worksheet.
    • IPName is a name that you assign to this address. Type IPName in uppercase letters. Lowercase characters will cause problems under certain circumstances. Use the value in J2 of the TCP Host/Service Worksheet.

    For example: 204.17.148.230 LUDB2

    Note:

    If this is the last line in the HOSTS file, type a carriage return at the end of the line.

  4. Edit the SERVICES file by adding the following line:
    ServiceName Port/tcp

    where:

    ServiceName specifies a name that represents the port number on the host system. (You will use this name when you configure XDB Link in a later step.) Type the ServiceName in uppercase letters. Lowercase characters will cause problems under certain circumstances.

    Port specifies the dedicated TCP/IP port assigned to the XDB Link Host Option on the host system. Use the value in J4 of the TCP Host/Service worksheet.

    For example:

    XDBSRV 5170/tcp
    Note:

    If this is the last line in the SERVICES file, type a carriage return at the end of the line.

When connecting to DB2 with native TCP/IP:

  • Choose DRDA(TCP/IP) as your Connection Type
  • The Remote Host entry should match the mainframe's IP address entry in your HOSTS file.
  • The port entry should match the DB2 port entry in your SERVICES file. IBM's default port is 446/tcp but users should check with their administrators to find out what port their DB2 listens on.
Parent topic: Configure the PC
Related information
TCP Host/Service Worksheet
Worksheets


Configuring the Microsoft SNA Server

Restriction: This topic applies to Windows environments only.

Use the following procedures to configure Microsoft SNA Server for XDB Link. After initially configuring the server, you can make additional modifications to boost throughput, add more users, or add another connection.

To configure the SNA Server

  1. Install the DLC protocol on your server
  2. Configure the SNA Server settings for for SNA Server 2.11 or SNA Server 3.0.
Parent topic: Configure the PC
Related information
Configure the PC
Installing the DLC Protocol


Installing the DLC Protocol

Restriction: This topic applies to Windows environments only.

You must install the DLC protocol on your server machine before you configure the Microsoft SNA Server software.

This procedure assumes that you have installed the SNA Server. If you have not already done this, install this software before proceeding.

Note: If the program cannot find the DLC Protocol files on your workstation, it will ask you to insert the Windows NT CD. Make sure you have this CD on hand during this procedure.

When the installation is finished, the program will ask you to reboot the system. If this is a production machine, you may want to schedule this task for a maintenance period or for off-peak hours.

To install the DLC protocol:

  1. In the Windows Control Panel, select Network.
  2. In the Network Settings dialog box, select the Protocols tab (4.0 only) and click Add or Add Software.
  3. Select DLC Protocol from the network settings list and click Continue or OK.
  4. Complete the installation process as directed by the instructions on the screen.
  5. After you reboot, make a backup copy of your current SNA configuration (optional) and then configure SNA Server Version 2.11 or SNA Server Version 3.0.
Note: Micro Focus provides a sample configuration file, xdb_novl.sna, for you to examine and use as a guide. This file is located in your XDB application directory. It defines an Ethernet connection to a network node.
Parent topic: Configure the PC
Related information
Configuring SNA Server 3.0


Configuring SNA Server 2.11

Restriction: This topic applies to Windows environments only.

This procedure describes the steps you use to configure the SNA Server 2.11 software. Be sure that you complete all four tasks.

Use the values from your SNA Server worksheet (V2.11).

  1. Configure server properties
    1. Start the SNA Server Admin program if it is not already running.
    2. If the Servers and Connections window is not open, double-click the Servers and Connections icon.
    3. In the left pane of the Servers and Connections window, double-click the name of your SNA Server to open the Server Properties dialog box.
      In this field... Specify...
      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value D1.

      Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

      Worksheet value D2.

    4. Click OK to apply your settings and close the Server Properties dialog box.
  2. Create and configure a connection
    1. In the left pane of the Servers and Connections window, highlight the name of your SNA Server, then select New Connection from the Services menu.
    2. In the Insert Connection dialog box, select 802.2, then click OK.
    3. In the Connection Properties dialog box, type a name for this connection in the Connection Name field. Use the value in D3 of the TCP Host/Service Worksheet.

      Then, complete the following:

      In this field... | Select...
      Link Service | SnaDlc1
      Remote End | Host System
      Activation The event that will activate this connection. We recommend that you select On Server Startup.

      Worksheet value D6.
      Allowed Directions | Outgoing Calls and Incoming Calls
    4. Click Setup to open the 802.2 Setup dialog box and specify the following:
      In this field... | Specify...
      Remote Network Address The 12-digit hexadecimal network address (MAC address) as defined in the MACADDR= parameter in VTAM or NCP controller definition.

      Worksheet value D8.

      Local Node ID The 8-digit hexadecimal local ID number for this SNA server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK

      Worksheet values D9.
      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value D1.

      Control Point Name The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP.

      Worksheet value D11.

      Remote Node ID | Leave blank.
    5. Click Advanced>> to display the advanced options
    6. In the XID Type group box, select Format 3.
    7. Click OK to close the 802.2 Setup dialog box.
    8. Click OK to close the Connection Properties dialog box.
  3. Create and configure the Local APPC LU
    1. In the left pane of the Servers and Connections window, highlight the name of your SNA Server.
    2. Select the Insert command from the Edit menu.
    3. In the Insert dialog box, select APPC [Local] and click OK.
    4. In the New APPC LU Properties dialog box, complete the following:
      In this field... | Specify...
      LU6.2 Type | Independent
      LU Alias A name that represents this machine in its local SNA communications configuration.

      We recommend that you use the XDB Server name as the alias for this machine.

      Worksheet value D15.

      LU Name The LU name of this APPC LU as it is specified in VTAM.

      Worksheet value D17.

      Enable Automatic Partnering | Enable
      Implicit Incoming Remote LU | (None)
    5. Click OK to close the APPC LU Properties dialog box.
  4. Create and configure the remote APPC LU
    1. In the left pane of the Servers and Connections window, highlight the name of the Microsoft SNA server connection you created and select the Insert command from the Edit menu.
    2. In the Insert dialog box, select APPC [Remote] and click OK.
    3. In the New APPC Remote LU Properties dialog box, complete the following:
      In this field... | Specify...
      LU Alias A name to represent the remote APPC LU in this SNA server's communication configuration.

      Worksheet value D20.

      LU Name The VTAM APPLID for DB2.

      Worksheet value D22.

      Uninterpreted LU Name | The same VTAM APPLID specified in LU Name above, or nothing (leave blank).
      Supports Parallel Sessions | Enable
      Enable Automatic Partnering | Enable
      Implicit Incoming Mode IBMRDB, an independent mode definition that you have defined, or (None)

      If you use your own mode definition, it must support parallel sessions.

    4. Click Partners to open the LU6.2 Partner LUs dialog box, then click Add.
    5. In the Add APPC LU Partner dialog box, select the following:
      In this field... | Select...
      Partner LU | The Local LU you created when you configured Microsoft SNA Server.
      Mode | IBMRDB
    6. Click OK to close the Add APPC LU Partner dialog box. Click Close to close the LU6.2 Partner LUs dialog box, then click OK to close the New APPC Remote LU Properties dialog box.
    7. Select Save Configuration from the File menu to save the new configuration, then restart the server to put the new configuration into effect.

      The connection is ready to use with XDB Link.

Parent topic: Configure the PC


Configuring SNA Server 3.0

Restriction: This topic applies to Windows environments only.

This procedure describes the steps for configuring the SNA Server, version 3.0. Be sure to complete all tasks. Use the values from your SNA Server Worksheet (3.0).

  1. Insert a Link Service
    1. Start the SNA Server Manager if it is not already running.
    2. In the Server Manager window, select the name of your SNA Server.
    3. Select the Link Service command from the Insert menu.
    4. Select DLC 802.2 Link Service in the Insert Link Service dialog box, then click Add.
    5. Click OK in the DLC 802.2 Link Services Properties dialog box to accept the default settings.
  2. Configure SNA Server Properties
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the Properties command from the View menu.
    3. On the General tab in the Properties dialog box, set the following:
      In this field... Specify the following...
      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value E1.

      Control Point The control point name (CPNAME) for this server as specified in the PU definition of VTAM or NCP.

      Worksheet value E2.

    4. Click OK to close the Properties dialog box.
  3. Create and configure a connection
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the Connection command from the Insert menu, then select 802.2.
    3. On the General tab in the Connection Properties dialog box, set the following:
      In this field... | Specify...
      Name A name for this connection.

      Worksheet value E3.

      Link Service | SnaDlc1
      Support Dynamic Remote APPC LU Definition | Enable
      Remote End | Host System
      Allowed Directions | Both Directions
      Activation The event that will activate this connection. We recommend that you select Server Startup.

      Worksheet value E7.
    4. Select the Address tab in the Connection Properties dialog box and set the following:
      In this field... Specify...
      Remote Network Address The 12-digit hexadecimal network address (MAC address) as defined in the MACADDR= parameter in VTAM or NCP controller definition.

      Worksheet value E8.

      Remote SAP Address The remote SAP address. For most installations, the default value of 04 is appropriate.

      Worksheet value E9.

    5. Select the System Identification tab in the Connection Properties dialog box and set the following:
      In this field... | Specify...
      Network Name

      (Local)

              The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx). (The Network Name specified in TASK 2 will automatically appear in this field.)

      Worksheet value E1.

      Control Point

      (Local)

              The control point name of your VTAM system as defined by the VTAM PU. (The Control Point name specified in TASK 2 will automatically appear in this field.)

      Worksheet value E11.
      Local Node ID The 8-digit hexadecimal local ID number for this server. The first three digits must match the IDNUM parameter in VTAM, and the last five digits must match IDBLK

      Worksheet value E12.

      XID Type | Format 3
      Network Name

      (Remote)

              The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx).

      Worksheet value E1.

      Control Point

      (Remote)

              The system services control point name (SSCPNAME) of the host node as specified in the PU definition of VTAM or NCP.

      Worksheet value E15.

      Remote Node ID | Leave blank
    6. Select the 802.2 tab in the Connection Properties dialog box and verify that the Max BTU Length is less than or equal to MAXDATA in the VTAM PU definition.
    7. Click OK to close the Connection Properties dialog box.
  4. Create and configure the APPC Mode Definition
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the APPC command from the Insert menu, then select Mode Definition.
    3. On the General tab in the Remote APPC Mode Definition dialog box, set the following:
      In this field... Specify the following...
      Mode Name IBMRDB or an independent mode definition that you have defined in VTAM.

      If you use your own mode definition, it must support parallel sessions.

      Worksheet value E33.

    4. Select the Limits tab and set the following:
      In this field... | Specify the following...
      Parallel Session Limit The DSESLIM value for your PU definition in SYS1_VTAMLST.

      Worksheet value E34.

      Minimum Contention Winner Limit | Half the number specified in the Parallel Session Limit field.
    5. Complete the Limits tab by setting the following suggested values or specifying appropriate values for your network configuration:
      Field Name | Suggested Value...
      Partner Minimum Contention Winner Limit | 0
      Automatic Activation Limit | 0
    6. Select the Characteristics tab and set the following suggested values or use values appropriate for your network configuration:
      Field Name | Suggested Value...
      Pacing Send Count | 7
      Pacing Receive Count | 7
      Max Send RU Size | 4096
      Max Receive RU Size | 4096
      High Priority Mode | Enabled
    7. Click OK to close the Local APPC LU Properties dialog box.
  5. Create and configure the local APPC LU
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the APPC command from the Insert menu, then select Local LU.
    3. On the General tab in the Local APPC LU Properties dialog box, set the following:
      In this field... Specify...
      LU Alias A name that represents this machine in its local SNA communications configuration.

      We recommend that you use the XDB Server name as the alias for this machine.

      Worksheet value E18.

      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx). The Network Name specified earlier should automatically appear in this field.

      Worksheet value E1.

      LU Name The LU name of this APPC LU as it is specified in VTAM.

      Worksheet value E20
    4. Select the Advanced tab in the Local APPC LU Properties dialog box and set the following:
      In this field... | Specify the following...
      Member of Default Outgoing Local APPC LU Pool | Disable
      Implicit Incoming Remote LU IBMRDB, an independent mode definition that you have defined, or <None>.

      If you use your own mode definition, it must support parallel sessions.

      LU6.2 Type | Independent
      SyncPoint Support | Disabled
    5. Click OK to close the Local APPC LU Properties dialog box.
  6. Create and configure the Remote APPC LU
    1. In the Server Manager window, select the name of your SNA Server.
    2. Select the APPC command from the Insert menu, then select Remote LU.
    3. On the General tab in the Remote APPC LU Properties dialog box, set the following:
      In this field... | Specify...
      Connection | The name of your connection
      LU Alias A name to represent the remote APPC LU in this server's SNA communication configuration.

      Worksheet value E26.

      Network Name The SNA network name (NETID) of your VTAM system as defined in SYS1_VTAMLST(ATCSTRxx). The Network Name specified earlier should automatically appear in this field.

      Worksheet value E1.

      LU Name The VTAM APPLID for DB2.

      Worksheet value E28 and A9.

      Uninterpreted LU Name | The same VTAM APPLID specified in LU Name above, or nothing (leave blank).
    4. Select the Options tab in the Remote APPC LU Properties dialog box and set the following:
      Set this field... | To...
      Supports Parallel Sessions | Enabled
      Implicit Incoming IBMRDB, an independent mode definition that you have defined, or <None>

      If you use your own mode definition, it must support parallel sessions.

      Session-Level Security | No Session-Level Security
    5. Click OK to close the Local APPC LU Properties dialog box.
    6. Select the Save command on the File menu to save this configuration, then restart the server to put the new configuration into effect.

      The connection is ready to use with XDB Link.

Parent topic: Configure the PC
Related information
SNA Server Worksheet (V3.x)
Worksheets


Configure DB2 Access

Restriction: This topic applies to Windows environments only.
  • Configuring XDB Link with the Gateway Profile Utility
  • Defining Remote XDBHOST Connection Types
  • Defining Remote DRDA(APPC) Connection Types
  • Binding XDB Link to DB2
  • Creating Required Tables and Views
  • Configuring the Client Workstation
  • Configuring XDB Link Security
  • Creating User IDs for XDB Link
  • Enabling Security on the Client Workstation
  • Configuring Communications Software on the PC
Parent topic: Link Configuration
Related information
Configure the Host
Configure the PC


Configuring XDB Link with the Gateway Profile Utility

Restriction: This topic applies to Windows environments only.

You can use the Gateway Profile Utility to:

  • Define remote locations to XDB Link so that XDB client applications can access data in those locations.
  • Configure the settings XDB Link needs to translate data correctly and control client conversations.

If you have installed XDB Link on an XDB Server as part of a gateway configuration, you must:

  • Have super-user privileges on the XDB Server where XDB Link is installed.
  • Run the Gateway Profile Utility on the machine where XDB Link is installed.

If you need additional information about the Gateway Profile Utility while doing this procedure, see the topic Gateway Profile Utility.

To configure XDB Link using the Gateway Profile Utility

  1. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  2. Start the Options utility. (If you are using the gateway configuration, do this at the machine where XDB Link is installed).
  3. When the Options window opens, set the following values on the Connect page:
    If you are using ... | Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Location field, select the SYSTEM location.

    In the Protocol field, select the Local protocol.

    Direct-connect configuration | In the Protocol field, select DRDA.
  4. Click OK to save your settings and close Options.
  5. Start the Gateway Profile Utility by selecting its icon in the XDB program group or folder. (If you are using the gateway configuration, do this at the machine where XDB Link is installed.) If prompted for a user ID, enter an ID that has super-user or SYSADM privileges.
  6. When the Gateway Profile Utility window opens, click Register to display the Location Configuration dialog box. You use this dialog box to add the remote database to XDB Link.
  7. In the Location Name field, type the name of the remote database from row B9 in your DB2 worksheet. This is the DB2 location name used by the DDF facility.
    Note:

    A common mistake is to specify theDB2 APPLID in VTAM or the 4-character SUBSYSTEM name for DB2. These names are usually NOT the same name as the DB2 location name (although your DB2 systems programmer may have decided that all three of these names should be the same.) See your DB2 systems programmer to determine the DB2 location name.

  8. Complete the configuration process using the appropriate steps for your connection type:
    If XDB Link will use ... | Follow the procedures in the section ...
    TCP/IP to access DB2 | Configuring XDB Link for DB2 Access.
    SNA to access DB2 | Configuring XDB Link for DB2 Access.
Parent topic: Configure DB2 Access
Related information
Gateway Profile Utility
Defining Remote XDBHOST Connection Types
Defining Remote DRDA(APPC) Connection Types


Defining Remote XDBHOST Connection Types

Restriction: This topic applies to Windows environments only.

Use the following procedure to complete the Location Configuration dialog box if you are using TCP/IP to access DB2 through the XDB Link Host Option.

To define an XDBHOST connection

  1. Select XDBHOST(TCP/IP) from the Connection Type list box.
  2. In the DRDA Setup group box, specify the Package Name and Collection Identifier of the package that XDB Link will use to pass dynamic SQL to DB2. If your DBA or XDB administrator has already created a package on the host for XDB Link, make sure that you enter the package name and collection ID as it has been specified on the host.
    Note:

    If you have an earlier version of XDB Link, give this version a new package name. We suggest that you adopt a package naming convention that includes the XDB Link version number-- for example, XLNK600, XLNK601, XLNK602. In a multiple-gateway environment, this allows XDB Links with older software to continue to function. It also preserves the original package name in case you want to revert to the earlier version of XDB Link software.

  3. In the TCP/IP Setup group box, set the following values:
    In this field... Specify the following...
    Remote APPLID The APPLID of the remote DB2 subsystem.

    Worksheet row A9.
    Remote HOST The name of the host IP address as specified in the HOSTS file on this machine.

    Worksheet row J2.
    Port The name of the TCP/IP port dedicated to the XDB Link Host Option as specified in the SERVICES file on this machine.

    Worksheet row J3.
    Note:

    The Local HOST field in this group box displays the name of the XDB Server on which your XDB Link software resides. You cannot change this value.

  4. Modify other settings as you need or accept the defaults. See the XDB Bind Utility User's Guide for additional information about the Location Configuration dialog box.
    Note:

    The host code page values are the current default settings. The actual code page values used for this connection are dynamically determined when XDB Link connects with this remote host. (See Code Mappings for more information regarding host code pages.)

  5. Click Update to add this location to XDB Link.
  6. Click Exit to close the Location Configuration dialog box.
Parent topic: Configure DB2 Access


Defining Remote DRDA(APPC) Connection Types

Restriction: This topic applies to Windows environments only.

Use the following procedure to complete the Location Configuration dialog box if you are using an SNA connection to access DB2.

To define a DRDA(APPC) connection

  1. Select DRDA(APPC) from the Connection Type list box.
  2. In the DRDA Setup group box, specify the Package Name and Collection Identifier of the package that XDB Link will use to pass dynamic SQL to DB2. If your DBA or XDB administrator has already created a package on the host for XDB Link, make sure that you enter the package name and collection ID as it has been specified on the host.
  3. Note:

    If you have an earlier version of XDB Link, give this version a new package name. We recommend that you adopt a package naming convention that includes the XDB Link version number-- for example, XLNK600, XLNK601, XLNK602. In a multiple-gateway environment, this allows XDB Links with older software to continue to function. It also preserves the original package name in case you want to revert to the earlier version of XDB Link software.

  4. In the APPC Setup group box, set the following values:
    In this field... | Specify the following...
    Local LU Alias The name that represents this machine in its local SNA communications configuration.

    This value must match the Local LU Alias that you assigned to this computer when you configured its SNA software.

    Worksheet row D15, E19, F13, or H5, depending on which SNA server you use.
    Partner LU Alias The name that represents the remote APPC LU in this machine's local SNA communications configuration.

    This value must match the Partner (or Remote) LU Alias you assigned to the host LU when you configured the SNA software on this machine.

    Worksheet row D20, E27F16, or H12, depending on which SNA server you use.
    Mode Name IBMRDB or the name of an independent LU6.2 mode definition that you have specified in the mode table (MODETAB) associated with this machine's LU definition in VTAM.

    If you use your own mode definition, it must support parallel sessions.

    VTAM worksheet row A6
    Transaction ID | X'07F6C4C2'
  5. Modify other settings as you need or accept the defaults. See the topic Location Configuration Window for information about the Location Configuration dialog box.
    Note:

    The host code page values are the current default settings. The actual code page values used for this connection are dynamically determined when XDB Link connects with this remote host. (See Code Mappings for more information regarding host code pages.)

  6. Click Update to add this location to XDB Link.
  7. Click Close to close the Location Configuration dialog box.
Parent topic: Configure DB2 Access


Binding XDB Link to DB2

Restriction: This topic applies to Windows environments only.

Every DB2 application must have an application package to support the execution of statically-bound and dynamic SQL contained in the program. Under DB2, an application package is created when you bind the application using the BIND PACKAGE subcommand.

Because XDB Link runs against DB2, it must have an application package on the host. XDB Link uses its application package to process dynamic SQL from client applications (statically bound SQL is executed through the appropriate application package) and to execute statically-bound SQL statements contained in the XDB Link program itself.

To create the application package for XDB Link, you must create a database resource module (DBRM) for XDB Link and bind it to DB2 using the XDB Bind Utility.

Note:

You only need to bind XDB Link once. If this version of XDB Link has already been bound with your DB2 database, you can skip this procedure.

To perform these steps, you must have a valid user ID and password on the XDB Server where XDB Link is installed (if you are using XDB Link in a gateway configuration) and on the host system. Additionally, your user ID must have the following privileges under DB2 on the host.

  • BINDADD authority
  • BIND authority for XDB Link
  • CREATE authority for the XDB Link collection ID (needed only if your DB2 system imposes collection ID security)

If you do not have these privileges, you (or someone authorized to grant such privileges) must execute the following SQL statements on DB2.

GRANT BINDADD to UserID
GRANT BIND ON PACKAGE PackageName TO UserID
GRANT CREATE ON COLLECTION CollectionID TO UserID

where:

UserID | is your user ID
PackageName | is the name of the XDB Link package as specified in the Gateway Profile Utility
CollectionID | is the collection ID assigned to XDB Link in the Gateway Profile Utility

For additional information about these SQL statements, see your DB2 SQL Reference.

If you need additional information about the XDB Bind Utility while performing the following procedure, see the XDB Bind Utility User's Guide.

To create the default package for XDB Link

  1. On the machine where XDB Link is installed, start the communications software (SNA or TCP/IP) if it is not already running.
  2. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  3. On the machine where XDB Link is installed, or from any client workstation with access to that machine, start Options by selecting its icon in the XDB program group or folder.
  4. When the Options window opens, set the following values on the Connect page:
    If you are using a... | Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Protocol field, select protocol this machine will use to commu-nicate with the XDB Server on which XDB Link is installed.
    Direct-connect configuration | In the Protocol field, select DRDA.
  5. Click OK to close Options and save your settings.
  6. Start the XDB Bind Utility by selecting its icon in the XDB program group or folder.
  7. When the XDB Bind Utility window opens, select the name of the host system from the Remote Location drop-down list.
  8. Click Default to display the Generate Default DBRM screen and complete the following:
    In this field... | Specify...
    Package Name | The package name for XDB Link. This value must match the package name assigned to XDB Link in the Gateway Profile Utility.
    Collection ID | The collection ID for XDB Link. This value must match the collection ID given to XDB Link in the Gateway Profile Utility.
    Host System The type of DRDA host to which you want to bind XDB Link.

    Select MVS if you are using a DB2 version that does not support stored procedures (versions below 4.1)

    Select MVS + SPC if you are using a version of DB2 that supports stored procedures (version 4.1 or higher).
    Dynamic Sections | The number of dynamic sections that DB2 will include in the package it builds for XDB Link. This value determines how many dynamic SQL statements a client can have open at one time. The default value (32) is appropriate for most applications.
  9. Click Create to generate the default DBRM in your XDB application directory.
  10. Click Cancel to return to the XDB Bind Utility window, then click Bind to display the Bind Package dialog box.
  11. In the DBRM File Name list, select the name of the DBRM file created in step 9. Modify the other settings in this dialog box as you need or accept the defaults.
  12. Click Execute to bind XDB Link to DB2.
  13. When the bind process is finished, click Cancel to exit the Bind Utility.
  14. Use SQLWizard or another database management tool execute the following statement to grant public EXECUTE privileges for XDB Link.
    GRANT EXECUTE ON PACKAGE collid.* TO PUBLIC

    where collid is the collection id of your XDB Link package.

Parent topic: Configure DB2 Access


Creating Required Tables and Views

Restriction: This topic applies to Windows environments only.

A few Micro Focus development tools, such as SQLWizard and XDB Migrate, use special tables in which they maintain control information. These programs also need access to system tables. Before you can successfully use these tools with XDB Link, you must do the following in DB2:

  1. Create the special tables these programs need.
  2. Grant public access to these special tables or grant access to XDB Link users on a user-by-user basis.
  3. Create views of the system tables these programs use (optional).
  4. Grant public access to these system tables (or views), or grant access to XDB Link users on a user-by-user basis.

Micro Focus provides a script file (XDBLINK.SQL, in the XDB program directory) to create the necessary files and grant the required privileges. Ask your DB2 database administrator to examine this script file and customize it for your DB2 site. He or she may want to edit this script to:

  • create views of the system tables rather than allowing users direct access to them
  • grant access to all users (public access) or to specific users
  • create the new tables in a database other than the default

After the script is customized, run it against your DB2 location using a tool such as SPUFI on the host. Or, use the following steps to run the script with SQLWizard from an XDB client workstation.

To perform these steps, you must have SELECT privileges on the DB2 system tables and you must be authorized to create tables.

To run the XDBLINK script using SQLWizard

  1. On the machine where XDB Link is installed, start the communications software (SNA or TCP/IP) if it is not already running.
  2. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  3. On the machine where XDB Link is installed, or from any client workstation with access to that machine, start Options by selecting its icon in the XDB program group or folder.
  4. When the Options window opens, set the following values on the Connect page:
    If you are using XDB Link in a... Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Location field, specify the name of the DB2 location.

    In the Protocol field, select protocol this machine will use to commu-nicate with the XDB Server on which XDB Link is installed.
    Direct-connect configuration In the Location field, specify the name of the DB2 location.

    In the Protocol field, select DRDA.
  5. Set these additional options:
    • On the Security page, enable the Client Security option.
    • On the SQL page, set SQL Compatibility Mode to DB2.
  6. Click OK to close Options and save your settings.
  7. Start SQLWizard by selecting its icon in the XDB program group or folder.
  8. Use the Run Batch command on the File menu to run the script file XDBLINK.SQL against each host location. This file is located in the XDB program directory.
Parent topic: Configure DB2 Access


Configuring the Client Workstation

Restriction: This topic applies to Windows environments only.

To access a DB2 database through XDB Link from an XDB client application, you must use the Options program to point the workstation to the DB2 database and establish an operating environment compatible with the DB2 host system.

To configure the client workstation, take the following steps before you execute an XDB client application.

To configure an XDB client workstation for DB2

  1. On the machine where XDB Link is installed, start the communications software (SNA or TCP/IP), if it is not already running.
  2. If you are using XDB Link in a gateway configuration, start the XDB Server on the machine where XDB Link is installed.
  3. At the client workstation, start Options by selecting its icon from the XDB program group or folder.
  4. When the Options window opens, set the following values on the Connect page:
    If you are using a... Make these selections...
    Gateway configuration In the Server Name field, select the name of the XDB Server on which XDB Link is installed.

    In the Location field, specify the name of the DB2 location.

    In the Protocol field, select protocol this machine will use to communicate with the XDB Server on which XDB Link is installed.

    Direct-connect configuration In the Location field, specify the name of the DB2 location.

    In the Protocol field, select DRDA.

  5. Set these additional options:
    • On the Security page, enable the Client Security option.
    • On the SQL page, set SQL Compatibility Mode to DB2.
  6. Click OK to save your settings and close Options.
  7. Run the client application.
Parent topic: Configure DB2 Access
Related information
Enabling Security on the Client Workstation
Configure DB2 Access


Configuring XDB Link Security

Restriction: This topic applies to Windows environments only.

Because of the security imposed by DB2 and the host system, you must implement the following security measures on your network.

  • On the machine where XDB Link is installed, create a user ID and password for each user that will access DB2 using XDB Link. (Gateway configuration only.)
  • On the machine where XDB Link is installed, set the XDB Server Security option using the XDB Server Configuration Utility (Gateway configuration only). For specific procedures, see the SQL Option Server Administration Guide.
  • On each client machine that will access DB2 though XDB Link, enable the XDB Client Security feature.
Parent topic: Configure DB2 Access
Related information
Creating User IDs for XDB Link
Configure DB2 Access


Creating User IDs for XDB Link

Restriction: This topic applies to Windows environments only.

If you are using XDB Link in a gateway configuration, each user that will access DB2 through XDB Link, must have a valid user ID and password on the host, and must have a matching user ID and password on the machine where XDB Link is installed. This is because XDB Link automatically presents a client's XDB user ID and password to the host when the client requests data from DB2. If the XDB user ID and password are not also valid on the host machine, the user won't be allowed on the system.

To create user IDs and passwords on the XDB Server, use the Users or Groups command in SQLWizard (you must have super-user authority to do this). Make sure the user ID and password you create with SQLWizard match the user ID and password on the host.

Note:

When passwords are created, note the XDB software is case-sensitive.

For users who will connect only to DB2, and not to databases on an XDB Server, you can configure their user IDs to bypass the password checking process. Doing so eliminates a redundant password check and prevents confusion when a user changes a password on one machine and not another. You may also want to configure a system where the host system acts as a "global" security server.

For complete information about designing a security scheme, see the SQL Option Server Administration Guide. For more information about creating user IDs on an XDB Server, see the topic Managing Users and XDB Server Access Overview.

Parent topic: Configure DB2 Access


Enabling Security on the Client Workstation

Restriction: This topic applies to Windows environments only.

To use XDB Link with DB2, you must enable the Client Security option on your workstation using Options. This option instructs the XDB runtime software to prompt you for a user ID (AuthID) and password when it connects to an location (including the location that represents DB2).

To enable security on a client workstation using Options

  1. At the client workstation, start Options by selecting its icon from the program group or folder.
  2. When the Options window opens, select the Security page and enable the Client Security option.
  3. Click OK to save your settings and close Options.
Parent topic: Configure DB2 Access


Configuring Communications Software on the PC

Restriction: This topic applies to Windows environments only.

Use one of the following procedures to configure the communications software on the machine where XDB Link is installed:

  • If XDB Link will connect to the host via TCP/IP, follow the procedure described in the section Configuring TCP/IP Software for the PC.
  • If XDB Link will connect to the host via SNA, follow the procedure described in the section Configuring the Microsoft SNA Server . When the procedure asks you to enter the VTAM APPLID for DB2, enter the VTAM APPLID assigned to the XDB Link Host Option for PEM instead.
Parent topic: Configure DB2 Access
Related information
Configure the PC
Configuring TCP/IP Software for the PC
Configuring the Microsoft SNA Server


Link Utility

Restriction: This topic applies to Windows environments only.
  • Configuring the Link for a Gateway Server
  • Starting a GTF Trace
  • Starting the Host Option for TCP/IP
Parent topic: How to...


Configuring the Link for a Gateway Server

Restriction: This topic applies to Windows environments only.

To configure the Link for a Gateway Configuration, you must:

  • Run the Gateway Profile Utility locally on the machine where the XDB Server and Link are installed
  • Have super-user privileges that give you write access to the XDB Server's system location tables
  • Check your client application settings in Options to make sure they point to the system location of the local XDB Server

See the Options Utility Overview for instructions.

Parent topic: Link Utility
Related information
Starting a GTF Trace
Starting the Host Option for TCP/IP


Starting a GTF Trace

Restriction: This topic applies to Windows environments only.

To start the GTF trace procedure, issue the following command from the MVS console:

S _GTF_procedure

or

S XDBGTF

Respond to the "AHL125A RESPECIFY TRACE OPTION OR REPLY U" message with:

R nn,U

where nn is the WTOR message number.

Parent topic: Link Utility
Related information
Configuring the Link for a Gateway Server
Starting the Host Option for TCP/IP


Starting the Host Option for TCP/IP

Restriction: This topic applies to Windows environments only.

To start the Host Option for TCP/IP, issue the following command from the MVS system console:

S Catalogued Procedure name for Host Option for TCP/IP

or

S XDBLink

The following message is displayed on the system console:

@08 Enter XDBLINK Command

Next issue the following command to verify the status of the started task and verify the port number:

R nn,DISPLAY STATUS

where nn is the reply number message related to the Host Option for TCP/IP.

Parent topic: Link Utility
Related information
Configuring the Link for a Gateway Server
Starting a GTF Trace


Migrate Utility

Restriction: This topic applies to Windows environments only.
  • To start the Migrate Utility
  • To open and close the Browser
  • To refresh the Catalog Browser
  • To open and close the Schema Viewer
  • To log onto a server
  • To migrate tables
  • To migrate one or more databases
  • To migrate certain rows and columns
  • To replicate data
  • To add SQL to a migration
  • To save your migration specifications
  • To recall a migration specification
  • To run a MIG file without opening it
  • To run a MIG File from the command line
  • To create an SQL script file of the migration
  • To transfer data and its metadata definitions between a DB2 subsystem and an XDB server
Parent topic: How to...


To start the Migrate Utility

Restriction: This topic applies to Windows environments only.
  • From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > Migrate.
Parent topic: Migrate Utility
Related information
To log onto a server
The Migrate Window


To open and close the Browser

Restriction: This topic applies to Windows environments only.

The Catalog Browser is automatically displayed when you open Migrate. To close the Browser, double-click the Control-menu ( *) button.

To reopen the Catalog Browser after it has been closed, click the Catalog Browser button in the toolbar ( *) or select the Catalog Browser command from the View menu.

Parent topic: Migrate Utility


To refresh the Catalog Browser

Restriction: This topic applies to Windows environments only.

*
To refresh the contents of the Catalog Browser, click the Catalog Browser button, or click Catalog Browser on the View menu. You must do this at the end of a migration in order to display the names of the newly migrated tables.

Parent topic: Migrate Utility


To open and close the Schema Viewer

Restriction: This topic applies to Windows environments only.

The Schema Viewer is automatically displayed when you open Migrate. Only one Schema Viewer is active at a time. To close the Schema Viewer, double-click its Control-menu button in the upper-left corner.

Note:

When you close the Schema Viewer, the table and query specifications it contains are discarded.

To open a new Schema Viewer, select the New command from the File menu. When a new Schema Viewer is opened, Migrate clears the current table and query specifications. If you want to save these specifications, you must do so before opening a new Schema Viewer.

Parent topic: Migrate Utility


To log onto a server

Restriction: This topic applies to Windows environments only.

When you start Migrate, it attempts to connect to your "default" XDB Server and location. Depending on how your AutoConnect and Security options are set, you receive either the Connect dialog box (from which you can select the server and location to which you want to connect) or you are automatically connected to your default server and location.

  • The Connect dialog box appears if the Security option in Options is enabled, or if AutoConnect is disabled.
  • The Connect dialog box is bypassed if the AutoConnect option in Options is enabled.

See the Options Utility online help for more information about the AutoConnect and Security options.

Parent topic: Migrate Utility


To migrate tables

Restriction: This topic applies to Windows environments only.

The procedure in this section describes how to copy tables from one location to another. If you want to migrate only certain rows and/or columns of a table, see Migrating Certain Rows and Columns.

Before you begin, review the following:

  • If you are migrating tables to/from the mainframe, make sure XDB Link is installed and operating properly.
  • If you are migrating tables between servers, make sure the SYSLUNAMES and SYSLOCATIONS tables on the server to which you are connected are configured for all locations to which you need access. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about setting up server-to-server communications.
  • Make sure you have SELECTprivileges on the tables you are migrating and on the following system catalog tables:
    SYSIBM.DATABASE | SYSIBM.SYSRELS
    SYSIBM.SYSCOLUMNS | SYSIBM.SYSSYNONYMS
    SYSIBM.SYSFOREIGNKEYS | SYSIBM.SYSTABLES
    SYSIBM.SYSINDEXES | SYSXDB.SYSLOCALS
    SYSIBM.SYSKEYS | SYSXDB.SYSPROMPTQUERY
    SYSIBM.SYSLOCATIONS | SYSXDB.SYSQUERY

    For more information about system catalog tables, see the SQL Reference or consult your XDB Server Administrator.

    Make sure the Catalog Browser and the Schema Viewer are open.

    *
    Open the Browser by selecting the Catalog Browser button on the toolbar. Open the Schema Viewer by selecting New from the File menu.

    Note:

    The location to which you want to migrate a table must exist. If it does not, you must first create it using a database management tool such as SQLWizard.

  1. In the Catalog Browser, locate and highlight the table you want to migrate.
    • Click the + buttons to expand the hierarchy and show subordinate objects.
    • Tables can be selected and migrated. Databases and locations cannot.

    For more information about using the Catalog Browser, see The Catalog Browser.

  2. Drag the highlighted table to the Schema Viewer. When you release the mouse button in the Schema Viewer, the table's schema displays in the viewer.
    Note:
    • You can double-click the table name to place it in the Schema Viewer.
    • You can hold the Shift or Ctrl key while you click the tables in the Catalog Browser to select multiple tables.
  3. If you want to migrate tables that are dependent on or referenced by a particular table (a referential integrity constraint), click the table in the Schema Viewer (its title bar will be highlighted indicating that it is "selected") and select the Show Dependent or Show Referenced command in the Object menu.

    When you select Show Dependent or Show Referenced, dependent and referenced tables (respectively) are automatically placed in the Schema Viewer along with arrowed lines showing their foreign key/primary key relationships.

    If all the rows of the referenced table are migrated, Migrate processes the DDL and DML so that the referential integrity constraints are not violated. However, if the user intends to restrict the domain of data being processed by Migrate, the domain (subset of the rows) must be defined by using the Define Query command on the Object menu. Queries can then be constructed against the referenced and dependent tables to ensure that only the rows matching the search criteria will be migrated. This will guarantee that foreign key values in the referenced and the dependent tables are consistent with each other. See Migrating Certain Rows and Columns for more information.

    Note:

    You can select the Show Dependent and Show Referenced commands from the control menu. To access this menu, click the Control-menu button in the upper-left corner of the table's schema window.

  4. Click the Table/Query Options * button in the toolbar or select the Table/Query Options command on the Object menu.
    In this field... | Specify the following...
    AuthID The name to be used as the creator of the destination table.

    If you want Migrate to use the source table's Auth ID by default, select the Default To Source checkbox next to the Auth ID text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify an Auth ID by typing it in text box.

    Table | The name of the table to which you will be migrating the data. If this table doesn't exist, Migrate will create it for you.
    Tbl Space The table space name for the target table to which you will be migrating the data.

    If you want Migrate to use the name of the source table space by default, select the Default To Source checkbox next to the Tbl Space text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a table space name by typing it in this text box.

    Database The database name for the target table where you will be migrating the data.

    If you want Migrate to use the name of the source database from which the source table is selected by default, select the Default To Source checkbox next to the Database text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a database name by typing it in this text box. If this field is left blank, the default database name "DSNDB04" is used.

  5. In the Migrate group box, select the database objects you want to copy with the table. You can migrate primary keys, unique keys, indexes, foreign keys, synonyms, comments, privileges and distinct types.
    CAUTION:
    If you do not migrate primary keys, unique keys, and foreign keys, applications that are dependent on the database to implement these business rules may not work.
  6. In the If Table Already Exists group box, specify the action you want Migrate to take if the target table already exists.
    Select... | If you want Migrate to...
    Abort | End the migration.
    Append Data | Append the migrated records to the existing table.
    Replace Data | Replace all records in the existing table with the migrated records (all data in the existing table will be deleted).
    Replace Table | Drop the existing table and create a new table with the migrated records.

    For information about the Update No Insert, Update Insert, and Delete Match options, see the instructions for Replicating Data.

  7. In the Limit Data To group box, specify how much data you want Migrate to copy.
    Select... | If you want Migrate to...
    All Rows | Copy all records from the source table to the destination.
    No Data Copy no records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature.

    The behavior of this option depends on the following:

    If the destination table does not exist, an "empty" table is created.

    If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).

    If the destination table exists, and the Append Data option is used, no records are copied to it.

    First N Rows | Copy the first N records from the source table to the destination.
    Every Nth Row | Copy every N records from the source table to the destination.
  8. In the Commit Work After group box, specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
  9. Click OK to confirm the settings.
  10. Repeat steps 1 through 9 for each table you want to migrate. If you want to remove a table that you have inadvertently added to the Schema Viewer, select the table in the Schema Viewer, then select the Remove command in the Object menu.
  11. Once all the tables you want to migrate are in the Schema Viewer, open the To drop-down list on the toolbar and select the location to which you want the tables copied.
    Attention: If a location to which you want to migrate records is not listed in the drop-down list, check that you are connected to the correct server and verify that the server has access to the location you need. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about server-to-server communications.
  12. When you are ready to begin the migration, click the Run ( *) button in the toolbar, or from the Commands menu, select Run.
  13. In the Run dialog box, make sure the Execute Migrate checkbox is selected. If this box is not selected, Migrate will not copy any records to the destination. This option can be disabled if you want to generate SQL without performing a migration. See Creating an SQL Script File of the Migration.
  14. In the Migrate Options group box, select the kind of reports and SQL scripts you want Migrate to produce when it migrates your data.
    Select this option... To request...
    Generate SQL A copy of the SQL script used to execute the migration. (This script contains the DDL statements used to define the destination table, but does not contain the individual INSERT statements for each migrated record.)

    In the text-entry field next to the checkbox, type the name of the file to which you want the script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new SQL script.

    Post Execution Report A report that lists the tables that were migrated.

    In the text-entry field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

    Error File A report that lists any errors encountered during the migration. If there are no errors during the migration, this error file will be empty.

    In the text box, type the name of the file to which you want the errors written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Error File and the Post Execution Report to combine these two reports into one file.

    Tip: If you want to produce a report describing the effect of the specified migration, select the Impact Analysis Report. This option gives you a report describing the schemas of the currently selected source and destination tables, without performing the migration. See Generating Reports for more information about this and other reports.
  15. Click OK to start the migration. The migration's progress is reported in the Status bar at the bottom of the window.
  16. When the migration is finished, click the Catalog Browser ( *) button to refresh the contents of the Catalog Browser. The destination tables, if they are new, do not appear in the Browser until you do this.
    Tip: You can save your migration as a MIG file to save time recreating it later. See Saving Your Migration Specifications.
Parent topic: Migrate Utility


To migrate one or more databases

Restriction: This topic applies to Windows environments only.
  1. Start the Migrate Utility.
  2. Click Commands > Migrate Database.
  3. From the Database list, click a database you want to migrate, or press Shift or Cntl as you click to select more than one database. This populates the Migrate Tables list with the tables defined for the database or databases you selected.
  4. To exclude one or more tables from the migration, on the Migrate Tables list, select the tables to exclude. To select one table, click it. To select more than one, press Shift or Cntl as you click. Then click Exclude. This puts the table or tables you selected onto the Not Included list. Optional.
  5. To include one or more tables that you previously excluded, on the Not Included list, select the tables to include. Then click Add. This places the selected tables back onto the Migrate Tables list. Optional.
  6. To set options for a table on the Migrate Tables list, click the table, then click Options. On the Table Options dialog box, set the options for the selected table, then click OK. Optional.
    Note:

    The default options for each table are those defined on the Default Options dialog box.

  7. Click Save. In the File name field, type a name for the .mig script file you want to contain the information you specified for this migration, then click Save. Optional.
  8. Click Execute to invoke the Run dialog box.
  9. From the To drop-down list, select a location to migrate to.
  10. Make any necessary changes to the migration options by checking or unchecking the appropriate checkboxes. Optional.
  11. Click OK to perform the migration.
Note:
  • If you choose to save the migration information, the Migrate Utility generates a .mig script file. The script file created here works the same as any other .mig script file except that you cannot view it in the Schema Viewer. However, you can execute it using the Execute Batch command or from the command line as often as you would like. You cannot execute a saved .mig script file from the from the Migrate Database dialog box.
  • Information pertaining to migration execution appears in the Execution Information window. Following successful migration, you can close this window.
Parent topic: Migrate Utility


To migrate certain rows and columns

Restriction: This topic applies to Windows environments only.

You can copy certain columns or certain rows from one table to another using Migrate's query feature. You can also use this feature to combine data from different tables into one result.

See Replicating Data if you wish to update, insert, or delete specific rows and columns.

Note:

Migrate's query feature is designed to migrate tables. It is not an all-purpose SQL processor. Do not use it to perform any SQL other than a single SELECT statement; for example, do not try to CREATE or DROP a location. If you need to include SQL with your migration, use prologue and epilogue scripts. See Adding SQL to a Migration.

The procedure in this section describes how to create a query and migrate its result. Before you begin, review the following prerequisites:

  • If you are migrating tables to/from the mainframe, make sure XDB Link is installed and operating properly.
  • If you are migrating tables between servers, make sure the SYSLUNAMES and SYSLOCATIONS tables on the server to which you are connected are configured for all locations to which you need access. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about server-to-server communications.
  • Make sure that you connect to a "non-mainframe" location when you start Migrateyou will not be able to migrate data to any other location, otherwise. See Logging onto a Server.
  • Make sure the Catalog Browser and the Schema Viewer are open.

    *
    Open the Catalog Browser by selecting the Catalog Browser button on the toolbar. Open the Schema Viewer by selecting New from the File menu.

  • Make sure you have SELECTprivileges on the tables you are migrating and on the following system catalog tables:
    SYSIBM.DATABASE | SYSIBM.SYSRELS
    SYSIBM.SYSCOLUMNS | SYSIBM.SYSSYNONYMS
    SYSIBM.SYSFOREIGNKEYS | SYSIBM.SYSTABLES
    SYSIBM.SYSINDEXES | SYSXDB.SYSLOCALS
    SYSIBM.SYSKEYS | SYSXDB.SYSPROMPTQUERY
    SYSIBM.SYSLOCATIONS | SYSXDB.SYSQUERY

    For more information about system catalog tables, see the SQL Reference or consult your XDB Server Administrator.

Note:

The location to which you want to migrate the results of your query must already exist. If it does not, you must first create it using a database management tool such as SQLWizard.

  1. In the From drop-down list, select the location containing the tables you want to query.
  2. In the To drop-down list, select the location to which you want the query result migrated.
    Note:

    If a location to which you want to migrate records is not listed in the drop-down list, check that you are connected to the correct server and verify that the server has access to the location you need. See your XDB Server Administration Guide or consult your XDB Server Administrator for information about server-to-server communications.

  3. Select the Define Query command on the Object menu to display an empty Query window.
  4. In the upper pane of the Query window, enter a Table and AuthID for the result of the query.
    Note:

    If this table does not exist already, Migrate will create it for you. If it does exist, the result of your query must match the existing table's schema exactly. That is, it must produce the same number of columns, of the same size and type, and in the same order as the destination table.

  5. If you want the result stored to a specific database and table space, type their names in the Database and Tablespace fields.
  6. In the lower pane, type a single SELECT statement. If you want to open a saved query that you have created using SQLWizard, double-click its name in the Catalog Browser's Query tab. For more information about recalling a saved query, see The Query Tab.

    You can enter any valid SELECT statement, even those containing joins and unions.

    Note:

    To ensure a successful query, specify your tables using fully-qualified (i.e., three-part) names.

    The following are examples of valid query statements:

    SELECT *
        FROM tutorial.tutorial.employee
        WHERE city = 'miami'
        SELECT e_no, lname, city
        FROM tutorial.tutorial.employee
        SELECT pname, qty
        FROM tutorial.tutorial.part p1,
        tutorial.tutorial.partsupp p2
        WHERE p1.pno = p2.pno
  7. After you have entered a SELECT statement, click the Table/Query Options (
    *
    ) button in the toolbar or select the Table/Query Options command on the Object menu.
  8. In the Query Options dialog box, specify how you want the results of this query written, then click OK. You can specify what action Migrate should take if the destination table already exists, and how many total records should be copied.

    If you need specific information about an option in this dialog box, click Help or see Query Options.

  9. If you want to process multiple queries, repeat steps 1 - 8. Each SELECT statement must use a separate Query window (you can minimize a Query window to reduce screen clutter).
  10. When you have finished specifying the query(s), click the Run
    *
    button in the toolbar, or select the Run SQL command on the Commands menu.
  11. In the Run dialog box, make sure the Execute Migrate check box is selected. If this box is not selected, Migrate will not copy any records to the destination. This option can be disabled if you want to generate SQL without performing a migration. See Creating an SQL Script File of the Migration.
  12. In the Migrate Options group box, select the kind of reports and scripts you want Migrate to produce when it migrates your data.
    Select this option... To request...
    Generate SQL A copy of the SQL script used to execute the migration. (This script contains the DDL statements used to define the destination table, but does not contain the individual INSERT statements for each migrated record.)

    In the text-entry field next to the checkbox, type the name of the file to which you want the script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new SQL script.

    Post Execution Report A report that lists the tables that were migrated.

    In the text-entry field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

    Error File A report that lists any errors encountered during the migration. If there are no errors during the migration, this error file will be empty.

    In the text box, type the name of the file to which you want the errors written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

    You can specify the same file name for the Error File and the Post Execution Report to combine these two reports into one file.

    Note:

    If you want to produce a report describing the effect of the specified migration, select the Impact Analysis Report. This option gives you a report that describes the schemas of the currently selected source and destination tables without performing the migration. See Generating Reports for more information about this and other reports.

  13. Click OK to start the migration. The migration's progress is reported in the Status bar at the bottom of the window and in a progress window.

    When a migration is processed, queries are processed after any tables in the Schema Viewer. When multiple queries are specified, they are processed in window-number order.

  14. When the migration is finished, click the Catalog Browser (
    *
    ) button to refresh the contents of the Catalog Browser. The destination tables, if they are new, do not appear in the Browser until you do this.
    Note:

    You can save your migration as a MIG file to save time recreating it later. See Saving Your Migration Specifications.

Parent topic: Migrate Utility


To replicate data

Restriction: This topic applies to Windows environments only.

Production database users can specify insert, update, and delete actions for tables that already exist. The instructions for replicating data are the same as Migrating Certain Rows and Columns, with the following exceptions:

  • In the Query Options window, choose one of the following options from the "If table already exists" group:
    • Update No Insert

      update the information only if a row with the key already exists

    • Update Insert

      update the existing row, or insert new row

    • Delete Match

      delete existing matching row

  • In the Define Query window, if you selected either the Update No Insert option or the Update Insert option, click the Update Rule button. In the Query Update Rules window:
    1. Identify the key fields.
    2. The Update Rule value of each field will change between None and Replace, depending on whether or not the field is a key.
      • Replace

        overwrite existing data with new data

      • None

        take no action

Parent topic: Migrate Utility


To add SQL to a migration

Restriction: This topic applies to Windows environments only.

Migrate gives you two ways to incorporate additional SQL in a migration.

  • You can execute a "prologue script" script before the migration to perform preparatory operations such as location creation and table initialization. A prologue script can be any batch SQL file containing valid SQL statements.

    To include a prologue script, select the Prologue option in the Migrate Options dialog box when you execute the migration. In the text box next to this option, specify the name of the SQL file that you want Migrate to run.

  • You can execute an "epilogue script" script after the migration to perform "housekeeping" operations such as dropping temporary tables or creating an index. An epilogue script can be any batch SQL file containing valid SQL statements.

    To execute an epilogue script, select the Epilogue option in the Migrate Options dialog box when you execute the migration. In the text box next to this option, specify the name of the SQL file that you want Migrate to run.

    Note:

    Prologue and Epilogue SQL statements are executed against the destination location.

Parent topic: Migrate Utility


To save your migration specifications

Restriction: This topic applies to Windows environments only.

Once you have specified a migration, you can save your specifications so they can be reused at a future date. To save a migration, select the Save As command from the File menu. In the Specify Batch File dialog box, specify a file name and click OK.

Note:

If a Query window is active when you select Save As, you can save just the query (to an SQL file) or the entire migration (to a MIG file). To specify which type of file you want Migrate to create, select *.SQL or *.MIG in the Save As dialog box before you click OK.

Migration specifications are saved in MIG files. A MIG file records the following information about a migration:

  • Source and destination settings
  • Tables selected for migration
  • Query statements
  • Table, query and run option settings
  • Migration option settings, including prologue and epilogue script specifications.

Using a MIG file, you can run a migration in "batch mode" (that is, run the migration without respecifying its options manually). Batch mode is useful for executing a migration that is run on a regular basis, or for running a migration in unattended mode. For information about running a migration from a MIG file, see Recalling a Migrate Specification.

Parent topic: Migrate Utility


To recall a migration specification

Restriction: This topic applies to Windows environments only.

If you have saved your migration specifications to a MIG file, you can recall the specifications using the Open command on the File menu.

Note:

When you open a MIG file, the specifications from the file replace the current migration specifications. If you want to preserve your current specifications, save them before opening a MIG file.

After opening a MIG file, you can examine and modify its specifications before executing the migration. (If you want to save the revised migration, use the Save or Save As command on the File menu.)

You can view the contents of a MIG file using the Batch Commands command on the View menu. After the file is displayed, you can print it using the Print command on the File menu.

Parent topic: Migrate Utility


To run a MIG file without opening it

Restriction: This topic applies to Windows environments only.

Migrate's Execute Batch command lets you run a migration without opening the MIG file in the Migrate window. To run a MIG file in this way, select Execute Batch from the File menu. In the Select Batch File dialog box, select the MIG file you want to run. When you click OK, the migration is immediately executed.

The Execute Batch command does not affect the current migration settings (e.g., selected tables and options). Specifications in effect before Execute Batch is invoked will be in effect when execution of the MIG file is complete.

Parent topic: Migrate Utility


To run a MIG File from the command line

Restriction: This topic applies to Windows environments only.

If you have saved your migration specifications to a MIG file, you can rerun the migration without opening Migrate. This is done by invoking Migrate from your development environment's command prompt and giving it the name of your MIG file.

The command used to invoke Migrate with a MIG file is as follows:

xmig40n -bMIGFile -iINIFile

where:

MIGFile | is the name of your MIG file. If this file isn't in the application path specified in the Path tabs of Options, you must specify the path in addition to the filename.
INIFile | is the name of the initialization file under which you want Migrate initialized. If you don't include the -i parameter, Migrate uses XDB.INI in the current working directory.
Parent topic: Migrate Utility


To create an SQL script file of the migration

Restriction: This topic applies to Windows environments only.

To create a script file containing the DDL statements used to perform the migration, select the Generate SQL checkbox in the Run dialog box when you execute the migration. In the text-entry field next to the checkbox, type the name of the file to which you want the script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new script.

Note:

The script that Migrate creates contains only the DDL statements that define the destination table. It does not contain individual INSERT statements for each migrated record.

You can use the SQL command on the View menu to display the contents of an SQL script file, including one to which you have saved migration SQL.

When the Select SQL File dialog box is displayed, select the SQL file and click OK.

After the file is displayed, you can print it using the Print command on the File menu.

Parent topic: Migrate Utility


To transfer data and its metadata definitions between a DB2 subsystem and an XDB server

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > Migrate.
  2. Specify the information required
  3. Click OK.
Parent topic: Migrate Utility


Options Utility

Restriction: This topic applies to Windows environments only.
  • To enable client security
  • To change the default XDB Server
  • To define and configure remote DB2 data locations
  • To enable connection to a new remote XDB Server
  • To set up or configure an XDB Server's parameters
Parent topic: How to...


To enable client security

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Client Options.
  2. Click the Security tab.
  3. Select Client Security Enabled.
  4. Click OK.
Parent topic: Options Utility


To change the default XDB Server

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Client Options.
  2. Click the Connect tab.
  3. In the Network Info group, choose a server from the Server Name list.
  4. Click OK.
Parent topic: Options Utility
Related information
To start the XDB Server
To stop the XDB Server


To define and configure remote DB2 data locations

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Link Profile.
  2. Specify the information required
  3. Click OK.
Parent topic: Options Utility


To enable connection to a new remote XDB Server

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Client Options.
  2. Click the Connect tab.
  3. In the Network Info group, type the server name in the Server Name field.
  4. Select the communications protocol you want to use to connect to the XDB Server from the list.
  5. In the Connect To group, type a default location for the new server.
  6. Type the AuthID you want to user to connect to the new server.
  7. Click OK.
Note: Some communications protocols require additional information to be specified in the xdb.ini file. Contact your system administrator if you experience difficulty in connecting to a new server.
Parent topic: Options Utility


To set up or configure an XDB Server's parameters

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Server Configuration.
  2. Specify the information required.
  3. Click OK.
Parent topic: Options Utility


SQL Wizard

Restriction: This topic applies to Windows environments only.
  • To start SQL Wizard
  • To exit SQL Wizard
  • Use the Catalog Browser
  • Manage Databases
  • Query Databases
  • Work with Query Results
  • Use the Result Window for Data Entry
  • Import Files
  • Export Files
  • Use Batch SQL Scripts
  • Administer XDB Users and Groups
  • Implement Security and Authority
Parent topic: How to...


To start SQL Wizard

Restriction: This topic applies to Windows environments only.
  • From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.

The Connect Dialog Box

The Connect dialog box is used to specify the XDB Server you want to use with SQLWizard and to enter a password if one is required.

The Connect dialog box may or may not be displayed when you start SQLWizard, depending on certain settings you make in the Options Utility. Likewise, certain items may or may not be selectable, depending on the settings in Options.

To use the Connect dialog box:

  1. Type the name of the XDB Server you want to access, or click the down arrow button next to the Server field to select an XDB Server from the drop-down list.

    To connect to an XDB Server that you never used before, run the Options utility before starting SQLWizard. Use the Connect tab in Options to set up the communication protocol, client node name, and default location.

    If the server name is displayed as a label rather than in a text-entry field, you cannot select or type a different server name.

  2. In the Location field, type the name of the location you want to access, or click the Browse button to select a location from the Browse Dialog box. The Browse Dialog box shows all locations known to the selected XDB Server.
    Note:

    Each time you access the Browse Dialog box, the selected XDB Server is checked for the list of all known locations available and you are logged in to the specified XDB Server with the current AuthID and password. If security is on, you must have SELECT privileges on the XDB Server's system location for this feature to operate correctly. (For more information, refer to the description of the WSQL043 message in online help.)

    If you do not click the location drop-down list, the XDB Server is not accessed until you connect.

  3. Type your AuthID in the Username field. If you need to access a multi-user XDB Server on the LAN, ask your XDB Server Administrator what AuthID to use.
  4. If security is turned on, type your password. Asterisks (*) are displayed for each character you type to prevent others from seeing your password.
    Note: Passwords are case-sensitive; be sure to use the correct combination of upper and lower case letters.

    If security is off, the Password field will not be displayed on the Connect dialog box.

  5. After making your selections, click OK to start SQLWizard and connect to the specified XDB Server and location.
    Note: If the Catalog Browser is set up to load on SQLWizard startup and the location you are trying to connect is an XDB Link location, a transaction dialog box appears. This dialog box asks you to complete the transaction to free up locks and close queries. Of the three options the dialog box presents you with, Commit and Rollback free the locks, while Proceed keeps them in place. Keeping the locks interferes with other DB2 users who are attempting to perform Data Definition Language (DDL) SQL statements.

If you enter your AuthID or password incorrectly, an error message is displayed. You have three chances to enter the correct AuthID and password.

Parent topic: SQL Wizard


To exit SQL Wizard

Restriction: This topic applies to Windows environments only.

You exit SQLWizard in just the same way you exit most other standard Windows or Presentation Manager applications.

To exit SQLWizard:

  1. Click the File menu to open it.
  2. Click the Exit command.

Optionally, you can double click the Control Menu button in the top left corner of the SQLWizard main window.

If there are open windows on your SQLWizard screen and you have not yet saved changes, you will be asked if you want to save before exiting. If you answer yes, you may be asked to provide a name for the object being saved, just as if you had clicked the Save As command in the File menu. If you answer no, the changes will be discarded. If you click Cancel, SQLWizard remains running and all open windows remain open.

Parent topic: SQL Wizard


Use the Catalog Browser

Restriction: This topic applies to Windows environments only.
  • Accessing the Catalog Browser
  • Closing the Catalog Browser
  • Opening Tables with the Catalog Browser
  • Opening Queries with the Catalog Browser
  • Selecting Items
  • Select and Drag
  • Filtering Items in the Catalog Browser
Parent topic: SQL Wizard


Accessing the Catalog Browser

Restriction: This topic applies to Windows environments only.

To access the Catalog Browser, click the Catalog Browser button on the toolbar. Alternatively, click the Locations, Tables, or Queries command from the View menu.

Catalog Browser Button * | The Catalog Browser button on the toolbar makes the Catalog Browser dialog box active. This button is useful when the Catalog Browser dialog box is covered by other SQLWizard windows or when the Browser's AUTOSTARTUP feature has been turned off.
View Menu Commands | The first three commands in the View menu always change the active window to the Catalog Browser dialog box. The Locations command displays the Location tab. The Tables command displays the Table tab, and the Queries command displays the Query tab.
Parent topic: Use the Catalog Browser


Closing the Catalog Browser

Restriction: This topic applies to Windows environments only.

By default, the Catalog Browser dialog box opens when you start SQLWizard. To prevent the Catalog Browser dialog box from automatically loading when you start SQLWizard, turn off AUTOSTARTUP on the Browser tab in the Options utility.

To close the Catalog Browser dialog box, use the Control or Close button in the title bar.

Note:

To provide quick access to system catalog information, the Catalog Browser dialog box is never actually closed while SQLWizard is active. When you close the Catalog Browser dialog box, SQLWizard just hides it. This improves performance by keeping the Catalog Browser dialog box active in memory, which reduces the need to continually re-query the system catalog tables.

Parent topic: Use the Catalog Browser


Opening Tables with the Catalog Browser

Restriction: This topic applies to Windows environments only.

You can use the Catalog Browser to open a table for viewing or editing.

To examine and open tables from the Catalog Browser:

  1. Access the Catalog Browser dialog box, then click the Table tab. Notice the list of locations, each preceded by a + button.
  2. Click a Location's + button to display a list of AuthIDs. Each AuthID is preceded by a + button.

    Notice that as you click each + button, SQLWizard displays a list of the sub-items for that object, and replaces the + button with a - button. Click the + button to expand an object list and the - button to collapse the list. If no button appears next to an item, no sub-items are available.

  3. Click the + button preceding an AuthID. SQLWizard displays the Tables/Views/Synonyms/Aliases objects.
  4. Click the + button in front of Tables to see a list of the tables.
  5. Click the + button preceding a table. SQLWizard displays a list of columns in the table. The Catalog Browser lets you view the column names in your table without displaying the table. Click the - button to remove the columns from the Catalog Browser display.
  6. Click a table name to highlight it.
  7. Click the Open button, or click and drag the table's name to the SQLWizard desktop.

    SQLWizard displays the table in a Result window.

  8. Close the Result window using the Close command from the File menu, or double click the Control Menu box in the upper left corner of the window.
Parent topic: Use the Catalog Browser


Opening Queries with the Catalog Browser

Restriction: This topic applies to Windows environments only.

You can use the Catalog Browser to open a previously saved query. Once open, you can run the query. If desired, you can change the query before running it. Optionally, you can use the Catalog Browser to run a query in Batch mode (without first opening and displaying it).

To examine and open queries from the Catalog Browser:

  1. With the Catalog Browser dialog box displayed, click the Query tab.

    The Catalog Browser lists the locations, the AuthIDs, and the queries available to you from your current server. If you do not see these three levels of organization, click the + buttons preceding locations and AuthIDs to expand the detail beneath them.

  2. Click a query name to highlight it.
  3. Click the Open button or drag the query's name to the SQLWizard desktop.

    SQLWizard displays the query for you to view, edit, or run.

Parent topic: Use the Catalog Browser


Selecting Items

Restriction: This topic applies to Windows environments only.

To select an object in the Catalog Browser dialog box, click its name or on the object icon. SQLWizard highlights the object that you select.

Double clicking on an object performs the default command for that object. For example, double clicking on a table is the same as selecting the table and then clicking the Open button.

You can select more than one item by holding down Ctrl while you click an item with the mouse. For example, you can Ctrl+click to select multiple tables, release Ctrl, and then click Open to display the Result window.

You can select a contiguous group of objects by first using the mouse to click the name of the first one; then while holding down Shift, click another object further up or down the list to select all objects in between, including the first and last objects you clicked. Once the desired objects are highlighted, release Shift and click Open to display the Result window.

Parent topic: Use the Catalog Browser


Select and Drag

Restriction: This topic applies to Windows environments only.

You can select (highlight) one or more tables and drag them to the Query Design or SQL Edit window. You can select multiple columns and drag them to an SQL Edit window or a Create/Alter Table window. Dragging a table name to the SQLWizard desktop will open the table (displaying the data in a Result window).

The mouse pointer changes shape to indicate where you can drop the object.

*
When the mouse pointer is in the Catalog Browser or in an area where you can drop the object, the mouse pointer appears as a pile of papers.

*
When the mouse pointer is in an area that cannot accept the object, the mouse pointer appears as the international NO symbol.

Note:

You can select from only one hierarchy level at a time.

Parent topic: Use the Catalog Browser


Filtering Items in the Catalog Browser

Restriction: This topic applies to Windows environments only.

The Set Database/Authid/Table Filter dialog box (displayed by clicking Filter on the Catalog Browser's Location tab) enables you to control the databases, AuthIDs and table items that are displayed in the Catalog Browser for any particular location.

To specify the desired pattern of characters (or filters) for the database, AuthID, and table levels, specify values into the Database Pattern, Authid Pattern, and Table Pattern text boxes respectively. Clicking OK refreshes the Catalog Browser according to the filter settings entered in these text boxes. If no error occurs, the filter settings are saved to the xdb.ini file.

The values you specify in the Database Pattern, Authid Pattern, and Table Pattern text boxes must follow DB2's rules for specifying character patterns for the SQL LIKE predicate. The following examples use the TUTORIALS location:

  • Database Pattern: DSN%

    Authid Pattern: TUT%

    Table Pattern: PART%

    This set of filters will only make databases whose names begin with "DSN" visible in the Catalog Browser. If a database object is expanded, only tables that begin with the string "PART" under an authid that begins with the string "TUT" will be displayed. In this case, two tables, TUTORIAL.PARTS and TUTORIAL.PARTSUPPS would match.

  • Authid Pattern: TUTORIA_

    Table Pattern: PART____

    This set of filters uses the underscore character (_) to match any given character. In this case, there is one underscore at the end of the authid pattern (TUTORIA_) and four underscores in the Table Pattern (PART____) so table TUTORIAL.PARTSUPP would be a match.

Parent topic: Use the Catalog Browser


Manage Databases

Restriction: This topic applies to Windows environments only.
  • To view and copy SQL statements
  • Changing Your Current Location and SQLID
  • Creating a Location
  • Altering a Location
  • Dropping a Location
  • Creating a Table
  • To create a new table
  • Altering a Table
  • To edit a table
  • Dropping a Table
  • To drop a table
  • To change the structure of a table
  • Creating an Index on a Table
  • Altering an Index
  • Dropping an Index
  • Creating a Foreign Key Relationship
  • Altering a Foreign Key Relationship
  • Dropping a Foreign Key Relationship
  • To create a new index or key
  • To change an index or key
  • To drop an index or key
  • To create new relationships
  • To change relationships
  • To drop relationships
  • Creating Synonyms
  • Dropping Synonyms
  • Creating Aliases
  • Dropping and Altering Aliases
Parent topic: SQL Wizard


To view and copy SQL statements

Restriction: This topic applies to Windows environments only.
  1. Enter data into the fields on a Create, Alter, or Drop dialog box as described elsewhere.
  2. Click the SQL button to access the Show SQL window and display the resulting SQL statement.
  3. Use your mouse to highlight the desired text. Click the Copy command from the Edit menu.
  4. Switch to your editor or open an SQL Edit window (from the File menu, click New, then click SQL).
  5. With your cursor positioned in the desired destination text field, click Paste from the Edit menu.
  6. Return to SQLWizard and close the Show SQL window and return to the Create, Alter, or Drop dialog box you were using.
Parent topic: Manage Databases


Changing Your Current Location and SQLID

Restriction: This topic applies to Windows environments only.

SQLWizard allows you to connect to a different location than the one you are currently using without exiting the program. If you have an alternate AuthID, you can change that also. These changes are made by clicking on the Set Location command from the Location menu or by clicking the Set button on the Catalog Browser dialog box.

In some cases, it may not be necessary to change to another location. For example, to query data that resides in another location of the XDB Server to which you are connected, simply enter a three-part name for the table being queried. It is also possible to set up alias names for tables in other locations.

Note: To change to a location on another XDB Server on your LAN, you must exit SQLWizard and restart it, choosing the desired server and location when the Connect dialog box appears. To change your default XDB Server and Location, use the Connect tab in the Options utility. If your organization uses the server-to-server connectivity features, you can access locations on multiple XDB Servers without having to log on to each individually.

To set the current location and SQLID:

  1. From the Location menu, choose the Set Location command.
    Note:

    *
    From the Catalog Browser dialog box, click the Location tab; then click the Set button.

    SQLWizard displays the Set Location/SQLID dialog box.

  2. Enter a location name in the Current Location field or select a location from the drop-down list. For more about setting locations, see the description for the Set Location command in the .
  3. Enter a new SQLID if you wish to work using a different name. (Note that you are still logged in as the AuthID you used at the Connect dialog box, even though you changed your SQLID to a different name.) For more about CURRENT SQLID, see the description for the Set Current SQLID command.
  4. Click OK to accept the changes. The current location and SQLID are displayed in the status bar at the bottom of the SQLWizard window.
Parent topic: Manage Databases


Creating a Location

Restriction: This topic applies to Windows environments only.

When SQLWizard creates a location, the system creates a directory structure for the new location, as well as all of the system catalog tables required by the location. Information about the new location is added to the catalog tables in the SYSTEM location. You create a location using the Create command from the Location menu. See Create/Alter/Drop Location Dialog Box for an explanation of each option on this dialog box.

To create a location:

  1. Click the Create command from the Location menu.
    Note:

    *
    From the Catalog Browser dialog box, click the Location tab; then click the Create button.

    SQLWizard displays the Create Location dialog box.

  2. Provide a name for the new location in the Location Name field. The name can be up to 16 characters long. This name must be unique among all locations you can access on the current XDB Server. To be sure you do not attempt to use the name of an existing location, click the down-arrow button to view the existing names on the drop-down list.
  3. Provide a drive and directory in the Location Path field. SQLWizard creates the location in this directory. Use a different directory for each XDB Server location you create. Do not use an XDB Server location directory for storing anything else.
  4. If you want to change the name of the file to which the Forward Log is written, type a new name in the Forward Log Name field (in XDB Server version 4.x and earlier, only).
  5. If you want to change the directory to which the Forward Log is written, type a new path name in the Forward LogPath field (in XDB Server version 5 and later; the Backward Log is placed in this directory too).

    If possible, assign the log file to a physical device different from that of your database. This will ensure that you can recover if the disk containing your database fails.

    Note:

    You must specify a directory that will be used exclusively for this location's log files. Be certain not to specify a directory that is already assigned to another location.

    The directory path is limited to 255 bytes. This restriction is due to limits imposed by the XDB SYSTEM location.

  6. If you want to disable forward logging, clear the Forward Log On checkbox (XDB Server version 4.x and earlier, only; this checkbox will be grayed if you're running version 5 or later).

    Since the forward logging facility used by XDB Servers version 4.x and earlier increases your overhead, you may choose not to use it for performance reasons. Be aware, however, that disabling this option will significantly limit your ability to recover data in the event of a failure.

  7. Select a Sort Sequence for the location, or use the default specified. Click the down-arrow button to view the existing options on the drop-down list. The sort sequence is used for XDB Server indexes, as well as for user-program sorts.
  8. Click OK to create the location.
Parent topic: Manage Databases


Altering a Location

Restriction: This topic applies to Windows environments only.

Once you have created a location, you cannot change its name, path, or sort sequence. You can change the Location Creator, Forward Log settings, and Remarks as necessary.

To alter a location:

  1. Click the Alter command from the Location menu.
    Note:

    *
    From the Catalog Browser dialog box, choose a location from the Location folder and click the Alter button.

    SQLWizard displays the Alter Location dialog box .

  2. Specify the name of the location you want to alter in the Location Name field. Click the down-arrow button to view the existing names on the drop-down list. SQLWizard reads the system catalog entries for the location and displays the appropriate information.

    Optionally, you can type a name in the Location Name field instead of choosing a name from the drop-down list. If you type a location name, be sure to click a different field on the window to let SQLWizard know that you are done typing.

  3. Modify fields by typing in new information.
    Note:

    You cannot change the Location Path. This field is disabled.

  4. Click OK to accept the location changes.
Parent topic: Manage Databases


Dropping a Location

Restriction: This topic applies to Windows environments only.

When you drop a location, its directory and all of the tables, indexes, and associated files are deleted. You cannot reverse this process. Use the Drop command with care!

Note:

To drop a location, you must be connected to a different location. To change your current location, click Set Location on the Location menu.

You cannot drop a location to which you are attached. If you receive the error "X131:Attempt to drop location in use" when dropping a location, exit SQLWizard and restart the program, logging onto a different location. Then drop the other location.

To drop a location:

  1. Click the Drop command from the Location menu.
    Note:

    *
    From the Catalog Browser dialog box, choose a location from the Location folder and click the Drop button.

    SQLWizard displays the Drop Location dialog box.

  2. Specify the name of the location you want to drop in the Location Name field. Click the down-arrow button to view the existing names on the drop-down list. SQLWizard reads the system catalog entries for the location and displays the appropriate information.

    Optionally, you can type a name in the Location Name field instead of choosing a name from the drop-down list. If you type a location name, be sure to click a different field on the window to let SQLWizard know that you are done typing.

  3. Review the information to verify that this is the location you want to drop and that you are currently connected to a different location. Your current location is displayed in the status bar at the bottom right of the SQLWizard window.
  4. Click OK to drop the location.
  5. Click OK to confirm dropping the location.
Parent topic: Manage Databases


Creating a Table

Restriction: This topic applies to Windows environments only.

You can use SQLWizard to create and manage your database tables. You can define indexes, primary keys, foreign keys, synonyms, and aliases using buttons available from the Create Table dialog box.

To create a table:

  1. Click the Create command from the Table menu.
    Note:

    *
    From the Catalog Browser dialog box, click the Table tab; then click the Create button.

    SQLWizard displays the Create Table dialog box.

  2. Type a name in the Table Name field. You can enter a one, two, or three-part name.
    Note:

    If you create a table in a different location than your current location, SQLWizard performs a connect to that location and then resets the location after the create is complete.

  3. Position the cursor in the Column Definition Grid in the lower half of the dialog box. Start in Field Name of Fld No. 1 and type a name for the first column of your table.

    You must define at least one column in the table when you create it. You can alter the table later to add, delete, or move columns.

  4. Position the cursor in the Data Type field to display a down-arrow button. Click the down-arrow button to display a drop-down list of data types. (This button does not become visible until the cursor is positioned in the Data Type field.) Choose a data type from the list.

    Alternatively, you can type a data type without displaying the list. Usually, the first letter you type is enough; SQLWizard completes the entry.

  5. Provide Length and Not Null information, or accept the defaults.
  6. Add, delete, or move rows as desired.

    Add rows to the table by clicking on the + button, while the cursor is inside the Column Definition Grid. The + button adds a row immediately after the row of the cursor's position. (Alternatively, press the keyboard down arrow cursor key to move the screen cursor down to a new row.)

    Delete a row by clicking on a number under the Fld. No. column to select a row. Click the - button to delete the selected field number from the list. You can select any number of rows to be deleted at one time.

    Move a column definition up or down in the list by selecting the row to move and clicking on its field number under the Fld No. column. Click the up or down arrow buttons to move the fields up or down the list, one row at a time. You can move more than one row at a time if you highlight contiguous rows by clicking on the field-number button on the left.

  7. If your table requires the specification of options relating to compatibility with DB2 or another supported database, click the Options button to display the Table Options dialog box. When you have finished specifying table options, click OK to return to the Create Table dialog box.
  8. Click OK to create the table.
Parent topic: Manage Databases


To create a new table

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click Create.
  5. Type a name for the table in Table Name.

    If you use a three-part table name and the location is not the current one, a temporary connection to the new location is established.

  6. Define the columns (fields) in your table by typing a column name, data type, length and whether nulls are accepted in the appropriate fields.

    To define a new column, click +.

  7. When you have finished, click OK to create the table.
Parent topic: Manage Databases


Altering a Table

Restriction: This topic applies to Windows environments only.

The Alter Table dialog box lets you add, change, or delete a table's columns, as well as to add or change an existing table's indexes, primary keys, foreign keys, synonyms, and aliases.

If you are running against an XDB Server (local or multi-user), just about any part of a table specification can be altered, even if the table already contains data. You can rename the table or its columns, change column data types, change the ordering of the columns, and add or drop columns.

Note:

If you are running against DB2, there are limits on the changes you can make to a table because the DB2 ALTER TABLE statement is not as comprehensive as the XDB Server ALTER TABLE statement. When connected to DB2 via XDB Link, only those functions that are supported on DB2 (such as adding columns) are enabled on the Alter Table dialog box.

To alter a table:

  1. Click the Alter command from the Table menu.
    Note:

    *
    From the Catalog Browser dialog box, click the Table tab and choose a table; then click the Alter button.

    SQLWizard displays the Open dialog box.

  2. Choose a table and click OK. SQLWizard displays the Alter Table dialog box.
  3. Modify the table specification as you wish. Making changes is similar to the initial entry of table specifications when creating a table.
    Note:

    If you wish to change the data type of an existing field, be sure that the new data type is compatible with the old data type. For example, you would not be allowed to change a date field to a decimal field. Other changes may be possible, but not desirable, such as changing an integer field to a character field.

  4. Click OK to alter the table.
  5. Click OK to confirm the table alterations.
Parent topic: Manage Databases


To edit a table

Restriction: This topic applies to Windows environments only.

Before you start, ensure that the current location is set to the location where the table resides.

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want to edit.
  5. Click Open.
  6. Enable editing by clicking Allow Editing on the Record menu.
  7. Edit the table as required.
  8. Close the Result Table window.
Parent topic: Manage Databases


Dropping a Table

Restriction: This topic applies to Windows environments only.

When you drop an XDB Server table, SQLWizard deletes all files associated with the table and removes its entries from the system catalog. Related indexes, keys, and relationships are also dropped. You cannot reverse a drop table action. Use the Drop command with care!

To drop a table:

  1. Click the Drop command from the Table menu.
    Note:

    *
    From the Catalog Browser dialog box, click the Table tab and choose table; then click the Drop button.

    SQLWizard displays the Open dialog box.

  2. Choose a table and click OK. SQLWizard displays the Drop Table dialog box.

    The table definition is shown so that you can verify it is the table you wish to drop. All fields in this window are disabled except for the five main buttons on the right.

  3. Click OK to drop the table.
  4. Click OK to confirm dropping the selected table.
Parent topic: Manage Databases


To drop a table

Restriction: This topic applies to Windows environments only.

To drop a table in the current location:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want to drop.
  5. Click Drop.
  6. Click OK to confirm your request.

SQL Wizard deletes the files associated with the table and removes the entries about the table from the system catalog.

Note: You cannot recover a table once it has been dropped.
Parent topic: Manage Databases


To change the structure of a table

Restriction: This topic applies to Windows environments only.

Before you start, ensure that the current location is set to the location where the table resides.

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want to alter.
  5. Click Alter.
  6. Change the column definitions, indexes, keys and relationships as required.

    You can look at the SQL statements that will be used to make your changes by clicking SQL at any time.

  7. Click OK.
Note: XDB databases support extensive alterations to a table, even if it contains data. DB2 databases support a much more restricted set of alterations. If the target database is a DB2 database, unsupported options are not available on the Alter Table window.
Parent topic: Manage Databases


Creating an Index on a Table

Restriction: This topic applies to Windows environments only.

After defining the columns for your table, you are ready to define its indexes. You can define an index when you create the table, or you can use the Alter Table window to define an index for an existing table.

Options are provided for compatibility with DB2 and other XDB Server-supported databases.

To create an index:

  1. Click the Create command from the Table menu to display the Create Table or Alter Table dialog box, or click the Alter command to display the Open Table dialog box and choose a table. If you are creating a new table, or you need to change the column specifications for an existing table, make the column entries before proceeding.
    Note:

    *
    From the Catalog Browser dialog box, click the Table tab; then click the Create button, or choose a table and click the Alter button

  2. Click the Create button in the Indexes and Keys group box.

    SQLWizard displays the Create Index dialog box.

  3. Type a name for your index in the Index Name field.
  4. Choose the type of index by clicking one of the three types in the Type group box: Index, Unique Index, or Primary Key.
  5. Choose the column(s) you wish to use as the key for the index. Any column names included in the Index Columns list when you exit the Create Index dialog box are used as your index key(s). Use the following descriptions as a guide for choosing columns.

    To move a column name from one list to the other, click its name to highlight it; then click the right or left arrow button to move it to the other list. Alternatively, double-click a column name to move it to the other list.

    To select multiple contiguous items, hold down the Shift key when clicking on the first and last entry of the desired list of names. To select multiple non-contiguous items, hold down the Ctrl key while clicking on each item you want to select. When the desired items are highlighted, click the appropriate arrow button to move them to the other list.

    To move all column names from one list to the other, click a double-arrow button.

  6. To change the order of columns in the Index Columns list, click a column name and click the up- or down-arrow button.
  7. Click the Options button to specify additional index items.

    Most of these additional options are provided for compatibility with DB2 or other XDB Server-supported databases. For DB2, these include the equivalents of USING BLOCKS, FREE BLOCKS, CLUSTERS, BUFFER POOLS and other options.

  8. Click OK to accept the index definition.

    SQLWizard adds the name of the new index to the Indexes And Keys group box, preceded by a + sign to indicate a new index definition.

  9. Click OK from the Create/Alter Table dialog box to create the new index.

    SQLWizard creates the new index definition for the selected table.

Parent topic: Manage Databases


Altering an Index

Restriction: This topic applies to Windows environments only.

When you alter an index, the index is actually dropped and recreated using your new specifications.

Additional options are provided for those requiring compatibility with mainframe DB2 or other XDB Server-supported databases.

To alter an existing index:

  1. Click the Alter command from the Table menu.

    SQLWizard displays the Open Table dialog box.

  2. Choose the desired table and click OK. If you need to change column specifications for an existing table, make these entries before proceeding.
    Note:

    *
    From the Catalog Browser dialog box, click the Table tab and choose a table; then click the Alter button.

  3. Choose an index from the Indexes And Keys list on the Alter Table dialog box either by double clicking on an index name or by highlighting a name and clicking the Alter button.
  4. Modify the column selection using the arrow buttons.
  5. Change any DB2-related index items by clicking on the Options button. These include the equivalents of Using Blocks, Free Blocks, Clusters, Buffer Pools and other options.
  6. Click OK to accept the changes.

    SQLWizard returns you to the Alter Table dialog box. An asterisk (*) precedes the index entry in the Indexes And Keys list to show that the index definition has been changed.

  7. Click OK to exit the Alter Table dialog box.
  8. Click OK to confirm altering the table.

    SQLWizard modifies the index specifications on the selected table.

Parent topic: Manage Databases


Dropping an Index

Restriction: This topic applies to Windows environments only.

When you drop an index using the Alter Table facility, there is no effect on the table data because the index is a structure independent of the table.

Once index specifications are saved for a table, you can drop them by reopening the Create/Alter/Drop Table dialog box and accessing the Alter Index dialog box. You can also use the Undo button from this dialog box to cancel a drop index specification before resaving the table information from the Create/Alter/Drop Table dialog box. Once completed, SQLWizard drops the old index and creates a new one using the new specifications you provide, if any.

To drop an index:

  1. Click the Drop command from the Table menu.

    SQLWizard displays the Open Table dialog box.

  2. Choose the desired table and click OK.

    SQLWizard displays the Drop Table dialog box.

    Note:

    *
    From the Catalog Browser dialog box, click the Table tab and choose a table; then click the Drop button.

  3. Choose an index from the Indexes And Keys list on the Drop Table dialog box by highlighting a name and clicking the Drop button.

    SQLWizard modifies the index entry by preceding it with a - sign to indicate it will be dropped when exiting the Drop Table dialog box.

    Note:

    If you decide you want to keep an index before exiting the Drop Table dialog box, double click the name of the index to display the Drop Index dialog box. Click the Undo button. The - sign will be removed and the index will remain intact.

  4. Click OK from the Drop Table dialog box to drop all indexes that have the - sign.
  5. Click OK to confirm altering the table.

    SQLWizard drops the selected indexes on the selected table.

Parent topic: Manage Databases


Creating a Foreign Key Relationship

Restriction: This topic applies to Windows environments only.

You can create a foreign key when you are creating or altering a table. Instructions on how to create a foreign key are provided below.

To create a foreign key relationship:

  1. Verify that your key columns in the referenced table and the dependent table have the same data types, sizes, and null status. You can examine these column attributes using the Catalog Browser dialog box.
  2. Display the Create Table or Alter Table dialog box for the dependent table. This is the table on which you are creating a foreign key.
  3. Click the Create button from the Relationships group box.

    SQLWizard displays the Create Relationship dialog box.

  4. Type a name for your foreign key in the Foreign Key Name field.
  5. Type the name of a table in the Referenced Table field, or click the Browse button and choose a table from the Open Table dialog box. When you specify a referenced table, remember that it must have a primary key already defined.
  6. The Table Columns list displays the column names from the dependent table (the EMPLOYEE table in the example above). These are available for you to match to the Referenced Columns that are displayed in the other list.
  7. Match a column name from the Table Columns list to each of the Referenced Columns. There are two ways to do this:
    • Highlight a column name and click the right arrow button.
    • Double-click a column name.

    SQLWizard moves the selected field from the dependent Table Columns list to the Foreign Key Cols list, next to the first available referenced column.

    If you make any errors in assigning fields, highlight the name in the Foreign Key Cols list and move it back to the Table Columns list by clicking on the left arrow button.

  8. To change the ordering of the foreign key columns, click a foreign key column and use the up and down arrows to reposition it next to the correct column from the referenced table. The column only moves up or down if there is another matching referenced column (i.e., the same data type, length, and null permission) above or below it in the list.
  9. Click OK to accept the relationship definition.

    SQLWizard displays the name of the foreign key in the Relationships group box on the Alter Table dialog box, preceded by a + sign to indicate a new relationship. The name of the referenced table appears in parentheses.

  10. Click OK from the Alter Table dialog box.
  11. Click OK to confirm altering the table.

    SQLWizard creates the foreign key on the selected table.

Parent topic: Manage Databases


Altering a Foreign Key Relationship

Restriction: This topic applies to Windows environments only.

You can alter some of the specifications of a relationship, particularly the On Delete and On Update options.

Instructions for how to alter a relationship are provided below.

To alter a foreign key relationship:

  1. Display the Alter Table dialog box for the dependent table.
  2. In the Relationships group box, either highlight a relationship name and click the Alter button, or double click a relationship name. The Alter Relationship dialog box is displayed.
  3. Make changes to any field or selection in the foreign key definition.
  4. Click OK to accept the changes and return to the Alter Table dialog box.

    SQLWizard displays the name of the foreign key in the Relationships group box. The relationship name is preceded by an * to indicate that the foreign key specifications have been modified.

  5. Click OK to accept the foreign key changes.
  6. Click OK to confirm altering the table.
Parent topic: Manage Databases


Dropping a Foreign Key Relationship

Restriction: This topic applies to Windows environments only.

To drop a foreign key, use the Alter Table dialog box. Instructions for how to drop a foreign key relationship are provided below.

To drop a foreign key relationship:

  1. Display the Alter Table dialog box for the dependent table.
  2. In the Relationships group box, highlight a relationship name and click the Drop button.

    SQLWizard displays a - sign preceding the foreign key name to indicate it will be dropped when you exit the Alter Table dialog box.

    Note:

    If you realize you want to keep a foreign key (relationship) before exiting the Alter Table dialog box, double click the name of the foreign key and display the Drop Relationship dialog box. Click the Undo button. The - sign will be removed, and the foreign key will remain intact.

  3. Click OK from the Alter Table dialog box to drop the foreign key.
  4. Click OK to confirm altering the table.
Parent topic: Manage Databases


To create a new index or key

Restriction: This topic applies to Windows environments only.

To create an index or key on a table in the current location:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. Click Create in the Indexes and Keys group.
  7. Type a name for your index or key.
  8. Select the type of index or key you want to create.
  9. Use the arrow pushbuttons to create a list of columns that define the index or key.
  10. When you have finished, click OK to close the Create Index dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  11. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To change an index or key

Restriction: This topic applies to Windows environments only.

To change an index or key on a table in the current location:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. In the Indexes and Keys group, select the index or key you want to change from the list.
  7. Click Alter.
  8. Make the changes you require.
  9. When you have finished, click OK to close the Alter Index dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  10. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To drop an index or key

Restriction: This topic applies to Windows environments only.

To drop an index or key on a table in the current location:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. In the Indexes and Keys group, select the index or key you want to change from the list.
  7. Click Drop.
  8. Click OK to close the Create Index dialog box.
  9. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To create new relationships

Restriction: This topic applies to Windows environments only.

To create relationships on columns in a table in the current location:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. In the Relationships group, click Create.
  7. Type a name for the foreign key.
  8. Type the name of the parent (referenced) table for the foreign key or click Browse to search for it.
  9. Select the behaviour you require in the On Delete and On Update groups.
  10. Use the arrow pushbuttons to create a list mapping columns that you want to be foreign keys to the corresponding primary key columns in the parent table.
  11. When you have finished, click OK to close the Create Relationship dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  12. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To change relationships

Restriction: This topic applies to Windows environments only.

To change relationships on columns in a table in the current location:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. Select the name of the foreign key you want to alter from the list.
  7. In the Relationships group, click Alter.
  8. Make the changes you require.
  9. When you have finished, click OK to close the Alter Relationship dialog box.

    You can look at the SQL statements that will be used to make your changes by clicking SQL.

  10. Click OK to close the Alter Table window.
Parent topic: Manage Databases


To drop relationships

Restriction: This topic applies to Windows environments only.

To drop relationships on columns in a table in the current location:

  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Table tab is selected.
  4. Click the table you want.
  5. Click Alter.
  6. Select the name of the foreign key you want to drop from the list.
  7. In the Relationships group, click Drop.
  8. Click OK to close the Alter Table window.
Parent topic: Manage Databases


Creating Synonyms

Restriction: This topic applies to Windows environments only.

You can create a synonym when you are creating or altering a table. Synonyms are defined on the Table Options dialog box.

To create a synonym:

  1. Display the Create Table or Alter Table dialog box.
  2. Click the Options button to display the Table Options dialog box.
  3. Click the Create button in the Synonyms group box.

    SQLWizard displays the Create Synonym dialog box.

  4. Type a name for the synonym in the Synonym Name field.
  5. Click OK to accept the synonym.

    Your new synonym is now listed in the Synonym group box of the Table Options window with a + sign preceding it.

  6. Click OK from the Table Options dialog box.
  7. Click OK from the Create Table or Alter Table dialog box to create the synonym.
  8. Click OK to confirm altering the table.

    SQLWizard creates the new synonym.

Parent topic: Manage Databases


Dropping Synonyms

Restriction: This topic applies to Windows environments only.

A synonym is not dropped until you exit the Alter Table dialog box. Before you exit this dialog box, be sure you have made all appropriate changes and wish to save the table specifications.

To drop a synonym:

  1. Display the Alter Table dialog box for the table on which the synonym is defined.
  2. Click the Options button to display the Table Options dialog box.
  3. Highlight a synonym in the Synonyms group box and click the Drop button. The Table Options dialog box displays the synonym with a - sign preceding it to indicate that it will be dropped.
    Note:

    If you mark a Synonym name and then realize you want to keep it, before exiting the Alter Table dialog box, double click the name of the Synonym to display the Drop Synonym dialog box. Then click the Undo button. The - sign will be removed, and the original synonym will remain intact.

  4. Click OK from the Table Options dialog box and click OK in the Alter Table dialog box to drop the synonym.
  5. Click OK to confirm altering the table.
Parent topic: Manage Databases


Creating Aliases

Restriction: This topic applies to Windows environments only.

Before you create an alias for a table, you must be connected to the location where the table resides.

To create an alias:

  1. Display the Create/Alter Table dialog box.
  2. Click the Options button.

    SQLWizard displays the Table Options dialog box.

  3. Click the Create button in the Aliases group box.

    SQLWizard displays the Create Alias dialog box.

  4. Type a name for the alias in the Alias Name field.
  5. Select target locations from the Target Location group box. These are the locations from which you want this alias to be accessible. Users in each of these locations can also use the alias to access the table.

    There are two ways to select location names:

    • Double click a location name on the Not Selected list to move it to the Selected list.
    • Click a location name on the Not Selected list; then click the right-arrow button to move it to the Selected list.
  6. Click OK to accept the information and return to the Table Options dialog box.

    Your new alias is now listed in the Aliases group box of the Table Options dialog box with a + sign preceding it.

  7. Click OK from the Table Options dialog box.
  8. Click OK from the Create Table or Alter Table dialog box to create the alias.
  9. Click OK to confirm altering the table.

    SQLWizard creates the new alias.

Parent topic: Manage Databases


Dropping and Altering Aliases

Restriction: This topic applies to Windows environments only.

An alias is not dropped until you exit the Alter Table dialog box. Before you exit this window, be sure you have made all appropriate changes and wish to save the table specifications.

To drop an alias:

  1. Display the Alter Table dialog box for the table on which the alias is defined.
  2. Click the Options button from the Aliases group box to display the Table Options dialog box.
  3. Highlight an alias in the Aliases group box and click the Drop button. The Table Options dialog box displays the alias with a - sign preceding it to indicate that it will be dropped. Only aliases created in the same location as the table they are associated with will appear in the Aliases group box.
    Note:

    If you mark an alias name and then realize you want to keep it, before exiting the Create/Alter Table dialog box, double click the name of the alias to display the Drop Alias dialog box. Then click the Undo button. The - sign will be removed, and the original alias will remain intact.

  4. Click OK from the Table Options dialog box and click OK in the Alter Table dialog box to drop the alias.
  5. Click OK to confirm altering the table.
Parent topic: Manage Databases


Query Databases

Restriction: This topic applies to Windows environments only.
  • Creating a Query
  • To create a query
  • Viewing Queries in SQL Edit Mode
  • Saving a Query
  • Opening a Saved Query
  • Running a Query
  • Viewing Results
  • Closing a Result Window
  • Example
  • Example
  • Setting Query Options
  • Choosing Columns
  • Moving Columns
  • Hiding Columns
  • Defining Conditions for a Single Column
  • Matching a Range of Values
  • Using AND and OR on One Column
  • Using AND and OR on Different Columns
  • Referring to Other Columns in Conditions
  • Including Calculations in Conditions
  • Selecting From a List of Values
  • Defining Computed Columns
  • Renaming Fields
  • Finding Distinct Values
  • Adding Extended Conditions (And and Where)
  • Specifying Sort Order
  • Retrieving Data From Two or More Tables
  • Displaying Table Names
  • Avoiding Cartesian Products
  • Prohibiting Cartesian Products
  • Manual Joins
  • Preventing Cartesian Products with Auto Joins
  • Non-equijoins
  • Outer Joins
  • Creating a Summary Query
  • Searching for Duplicate Values
  • Creating a Union
  • Creating a View
  • Creating a DELETE Statement
  • Creating an UPDATE Statement
  • Creating an INSERT Statement
Parent topic: SQL Wizard


Creating a Query

Restriction: This topic applies to Windows environments only.

In this topic, you will learn to write a simple prompted query that retrieves everything in a table - all of the columns and rows. For this example, the Query Design window that produces a prompted query is used.

To create a new query:

  1. Open a new Query Design window.

    SQLWizard displays the Add Table dialog box.

  2. Click one of the tables from the Table Name list box. If you do not see the table you want to use, you may have to change the Location or AuthID.
  3. Once you have highlighted a table, click the Add button to copy the table to the Query Design window. Notice that the columns in the selected table are shown in a Column Selection List.
    Note: When adding tables to a Query Design window, you can pick more than one table. A query that gets data from more than one table is called a join. For now, just select a single table.
  4. Click the Done button to close the Add Table dialog box. If you click the Done button before you add a table to the query, you will need to use the Add Table command from the Query menu.
    Note:

    *

    *
    Click the Add button on the toolbar or, from the Catalog Browser dialog box, drag a table to the Table Display Area.

  5. Examine the Column Selection List in the Table Display Area of the Query Design window. The table name is shown in the title bar. Beneath the title bar is a list box containing all column names in the selected table. You can select one column to be added in your query or you can use the asterisk (*) to select all columns in the table.
  6. Click the asterisk in the Column Selection List to add all of the columns in the table to the query.

    Notice that the columns are added to the Query Conditions Grid in the order they appear in the Column Selection List.

Parent topic: Query Databases


To create a query

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. If the Catalog Browser window is not open, click * to open it.
  3. On the Catalog Browser window, ensure the Query tab is selected.
  4. Click New.
  5. Click the table names that you are interested in and click Add.
  6. When you have added all the required tables, click Done.
  7. In each table, click the fields that you are interested in.
  8. Under each field, type any conditions you require.
  9. Click Save As on the file menu to save your query.
  10. Close the Query Design window.
  11. Click Refresh, to see your new query listed.
Note: To execute your query, click on the query and click Batch.
Parent topic: Query Databases


Viewing Queries in SQL Edit Mode

Restriction: This topic applies to Windows environments only.

You can examine the SQL statements generated by the Query Design window by switching to the SQL Edit window.

To switch to the SQL Edit window:

  1. Click the SQL command from the View menu.
    Note:

    *
    Click the SQL Edit button on the toolbar

    While in the SQL Edit view, you can make changes to your query that would be difficult to make through the prompted Query Design window. You can also edit other types of commands that are not currently supported by the Query Design window.

  2. Click the Design command from the View menu to return to the Query Design window.
    Note:

    *
    Click the Query Design button for Query Design mode.

Note:

If you make changes to the SQL statement while in the SQL Edit window, you will not be able to go back to the Query Design window without discarding those changes. You can, however, first save the prompted query in Query Design mode, switch to SQL Edit mode, and save the modified SQL statement as an SQL script file.

Parent topic: Query Databases


Saving a Query

Restriction: This topic applies to Windows environments only.

If you think you will want to use a query, save the query before you try to run it. Saving a query places the information in the system catalog tables, where it can be accessed later by you (and others if you save it as a shared query).

To save a query that has never been named before, or to save a query under a different name:

  1. From the File menu, click the Save As command.
    Note:

    *
    Click the Save button on the toolbar

    SQLWizard displays the Save As dialog box.

  2. Type a name for the query. You may want to change the location and AuthID for the query before you save it.
  3. Click the Options button to display the Set Query Options dialog box and type a comment or description for your query. This description will appear in the list of queries on the Catalog Browser dialog box.
  4. In the Query Type group box, choose to save your query as a Prompted Query (to be retrieved later into the Query Design window) or as an SQL Edit Query (to be retrieved later into the SQL Edit window or run as a batch SQL script file).
    Note:

    If you are saving a query from the SQL Edit window, and that query has been changed so that it no longer can be used in the Query Design window, you will only be able to save it as an SQL Edit Query, and not as a Prompted Query.

  5. In the Access group box, choose to make the query Private (available only to you) or Shared (available to other users on the XDB Server). With a Shared Query, the other users must have appropriate access authority to read the tables that the query uses.
  6. Click OK to exit back to the Save As dialog box.
  7. Click OK to save the query.

To resave a query:

Once a query is saved, you can use the Save command on the File menu or the Save button on the toolbar to resave any changes. The Save command does not prompt for a query name and does not provide access to the Set Query Options dialog box if the query has already been saved with a name.

Parent topic: Query Databases


Opening a Saved Query

Restriction: This topic applies to Windows environments only.

There are several ways to open a saved query.

To open a saved query from the menu:

  1. From the File menu, click the Open command.

    SQLWizard displays the Open dialog box.

  2. Click the down-arrow button for the List Objects Of Type field to display the object types drop-down list; click Queries.
  3. Click the desired query to open. Note that you may have to change the Location or AuthID to find the query you want to open.
  4. Click OK.
Note:

*

*
Click the Open button on the toolbar and choose the desired query or, from the Catalog Browser dialog box, click the Query tab, a query, and the Open button.

Parent topic: Query Databases


Running a Query

Restriction: This topic applies to Windows environments only.

Running a query causes the SQL command to be sent to the XDB Server where the desired columns and rows are retrieved and sent back to SQLWizard to display in a Result window. Before you can run a query, you must have specified at least one table and one column.

To run an open query from a Query Design window:

  1. Click the Query Design window to make it the current window.
  2. From the Query menu, click the Run command
Note:

*

*
Click the Run button on the toolbar or, from the Catalog Browser dialog box, click the Query tab, a query, and the Batch button.

Related Topics

Parent topic: Query Databases


Viewing Results

Restriction: This topic applies to Windows environments only.

When you run a query, the results of the query are displayed in a Result window. There are two result views: Result Table and Result Form. These are available from the View menu after a query is run.

A Result Table shows the rows of the result in a spreadsheet-like format. You can scroll in any direction to see the columns and rows of the result.

A Result Form shows the result one record at a time, with the fields displayed one beneath another. You move between records much like you turn the pages of a book. You can have multiple Query Result windows open at the same time.

To switch between Result Table and Result Form views:

  1. Click the Result Table command from the View menu, or click the window to make it active.
  2. Click the Result Form command from the View menu, or click the window to make it active.
Note:

*

*
Click the Result Table or Result Form button on the toolbar.

Parent topic: Query Databases


Closing a Result Window

Restriction: This topic applies to Windows environments only.

To close the current Result window, click the Close command from the File menu, or double click the Window Control Menu box at the upper left corner of the Result window.

Parent topic: Query Databases


Example

Restriction: This topic applies to Windows environments only.

The following example returns a list of all customer companies located in California. Even though the state column, St, appears in the Query Conditions Grid, it does not appear in the result.

  1. Open a new query.
  2. Add the CUSTOMER table and click Done to close the Add Table dialog box.
  3. Click the COMPANY column in the Column Selection List to add it to the Query Conditions Grid.
  4. Click the ST column to add it to the grid.
  5. Move down to the Query Conditions Grid and enter the string CA in the Conditions row under the ST column name.
  6. Click the ST column to select it.
  7. Click the Hide Column button on the toolbar (or use the Hide Column command from the Column menu).
  8. Run the query. Only the COMPANY column is shown in the Result window, displaying the names of only those companies in California.
  9. Close the Result window.
  10. Examine the SQL code generated for this command by clicking on the SQL button on the toolbar. Notice that the ST column does not appear in the SELECT clause of the query, but it is mentioned in the WHERE clause.
  11. Click the Query Design button on the toolbar to switch back to Query Design mode. Save the query if you want to keep it, and close the Query Design window.
Parent topic: Query Databases


Example

Restriction: This topic applies to Windows environments only.

This example creates a query that shows all of the cities that employees live in, and summarizes employee information into a column containing the count of employees living in each city. There will be one row returned for each city, regardless of how many employees live in that city.

  1. Open a new query and select the table of interest. In this case, open the EMPLOYEE table. Add it to the query and then click the Done button.
  2. Click the columns you want displayed in the query. Do not include the columns that contain data that you want to summarize yet. For this example, add the CITY and STATE columns.

  3. *
    Click the Create Computed Column button on the toolbar (or the Create Computed Column command from the Column menu) to display the Create Computed Column dialog box.
  4. From the Aggregate Function drop-down list, double-click Count.
  5. From the Table/Column drop-down list, double-click E_NO.

    It is a good idea, when generating a count, to choose a column that uniquely identifies the records that you want to count. You could also use an asterisk, which indicates that you want a count of all the records. The column name should be positioned inside the parentheses that appear after the count function.

  6. A column name is provided for the column, but you may want to change it to something more meaningful. Click the Column Name field and type in EmployeeCount.
    Note:

    Column names must satisfy the rules for a long identifier, discussed in the SQL Reference. That is, they may be up to 18 characters long and must begin with a letter. They cannot contain spaces.

  7. Click OK to accept the Computed Column.
  8. Now examine the Query Conditions Grid. You will notice that a new column called EMPLOYEECOUNT has been added at the end of the column list. The Order/Group row has also been added to the grid. You first saw this row when you defined a sort order for a query. Now it contains some new icons. The
    *
    symbol indicates that the column is a computed column. If you click this symbol, the Modify Computed Column dialog box for this column is displayed so that you can modify the column definition.
  9. In addition, a
    *
    symbol appears in the STATE and CITY columns. Whenever an aggregate function appears in a query, all other columns must be grouped. SQLWizard does this for you automatically. Click the
    *
    symbol.

    The Group By dialog box is displayed. Notice that there are two lists. The UnGrouped Columns includes the computed column EMPLOYEECOUNT, which SQLWizard will not allow you to group. The Grouped Columns include the CITY and STATE columns, which SQLWizard will not allow you to ungroup unless you delete the EMPLOYEECOUNT column.

  10. The order in which columns appear in the GROUP BY clause is important. SQLWizard places the columns in the list in the order in which they appear on the Query Conditions Grid. If this is not the correct order for your query, you should rearrange them. To do so, click a column to select it, and then use the Up and Down buttons to reposition the column. When positioning the columns, keep in mind that a column that contains a subset of the rows of another column should appear later in the list. In this example, the CITY column should appear after the STATE column, because there are a number of cities in each state. Move the STATE column to the top of the list.
  11. Once you have ordered the columns correctly, click OK to close the Group By dialog box. Notice the number that appears to the right of the GROUP symbol shows that STATE is the first grouped column, and CITY is the second grouped column.

  12. *
    You have now created a query containing summary rows. Use the SQL button on the toolbar to examine the SELECT statement generated for this command. Notice the COUNT function and the GROUP BY clause.

  13. *
    Use the Query Design button on the toolbar to return to the Query Design window.
  14. Save the query if you would like to keep it.

  15. *
    Click the Run button to run the SQL command. When the result appears you will see a row for every city in the EMPLOYEE table. The number of EMPLOYEE records that have a matching CITY value will appear in the EMPLOYEECOUNT column.
  16. Exit from the Result window
Parent topic: Query Databases


Setting Query Options

Restriction: This topic applies to Windows environments only.

SQLWizard provides options for designing and running your queries. You can set the defaults for all queries using the Options utility, as well as set specific options for a currently open Query Design or SQL Edit window.

To set options for the current query:

  1. From the Query menu, click the Current Query Options command.

    SQLWizard displays the Query Options dialog box.

  2. Make changes to the available items as desired.
  3. Click OK to accept the changes.
Parent topic: Query Databases


Choosing Columns

Restriction: This topic applies to Windows environments only.

There may be times when you do not want to show all of the columns in a table in your result. You can specify which columns to show, and the order in which they will appear in the Result window.

To add a single column to the Query Conditions Grid:

  1. Open or create a new query.
  2. Scroll through the list in the Column Selection List to find the column you want to add.
  3. Click the column to add it to the Query Conditions Grid. The column will be highlighted in the Column Selection List to show that it is added to the grid.
  4. Continue adding columns by clicking on them. As you click the names, they appear in the Query Conditions Grid. If you click a name by mistake, click it again to remove it.

    Notice that as you add a column to the query, it is added at the end of the set of columns in the Query Conditions Grid.

Note: If you decide you do not like your current column selection, you can easily start over by clicking once on the asterisk in the Column Selection List to select all columns, and a second time to remove all columns from the Query Conditions Grid.
Parent topic: Query Databases


Moving Columns

Restriction: This topic applies to Windows environments only.

The order in which columns appear in the Query Conditions Grid determines the order they appear in your result window.

To change the order of columns:

  1. Click a column name in the Query Conditions Grid to select it.
  2. Click and drag the column to a new location on the grid.
  3. Drop the column over the divider between two columns. The selected column will be repositioned between these two columns.

    You can also wait and rearrange the columns after the query is run.

Note: You can select and move more than one column at a time. Simply hold down Ctrl while you click a collection of column names. Or hold down Shift while you click a second column name to pick all columns between (and including) the first and second selection.
Parent topic: Query Databases


Hiding Columns

Restriction: This topic applies to Windows environments only.

If you want to specify a condition on a column in one of your tables, but you do not want the column to appear in your result, you can hide the column. There are several ways to hide a column that appears in the Query Conditions Grid:

  • Double click the column title to toggle the selected column between visible and hidden states. A column is visible if the title appears as a button. A column is hidden if it appears as a pressed button.
  • Click the column to select it, and use the Hide Column command from the Column menu to hide the column.
  • Click the Select Hidden Column command from the Column menu. The Select Hidden Column(s) dialog box allows you to move columns between a Visible and Hidden list by selecting and using the buttons between the lists. Click OK to accept the column specification on the dialog box.
Parent topic: Query Databases


Defining Conditions for a Single Column

Restriction: This topic applies to Windows environments only.

Usually when you define a Select command, you want to add filter conditions to restrict the rows retrieved.

To add simple search conditions on the columns in a query:

  1. Open the query.
  2. Click the Conditions row of one of the columns.
  3. Type in a value that the column should match. For example, under the ST column, enter the values DC, MD, and VA on separate rows. Quotes appear around the values if they are needed. The three values are treated as OR conditions.
Note: If you want to compare a column with another field, you will use the join mechanism.
Parent topic: Query Databases


Matching a Range of Values

Restriction: This topic applies to Windows environments only.

You can specify a range of values that a column should satisfy using the BETWEEN predicate. Type the condition BETWEEN followed by a number, then the keyword AND, then another number. For example:

Between 2 and 8
Parent topic: Query Databases


Using AND and OR on One Column

Restriction: This topic applies to Windows environments only.

You can enter a compound condition containing an AND or an OR in a single cell of the Query Conditions Grid. This condition will be enclosed in parentheses in the SQL statement. For example, you could enter the following condition in the LNAME column of the EMPLOYEE table:

"Hurwood" OR "Kerin"
Parent topic: Query Databases


Using AND and OR on Different Columns

Restriction: This topic applies to Windows environments only.

Values in different columns on the same row are treated as AND conditions. Values in different rows are treated as OR conditions. Look at the following Query Conditions Grid example.

This yields the following SELECT statement:

SELECT  E1.e_no, E1.lname, E1.payrate, E1.st, E1.com
FROM    TUTORIAL.TUTORIAL.EMPLOYEE E1
WHERE    ((E1.e_no Between 2 and 8)
        OR (E1.lname like ""hur%"")
        OR ((E1.payrate >4
            AND E1.payrate < 15)
            AND (E1.com is null))
            OR (E1.st <> "MD"))
Parent topic: Query Databases


Referring to Other Columns in Conditions

Restriction: This topic applies to Windows environments only.

You can refer to another column in the query from within a cell. For example, you type the following condition into the LNAME column of the EMPLOYEE table to test for a last name equal to a first name:

=fname
Parent topic: Query Databases


Including Calculations in Conditions

Restriction: This topic applies to Windows environments only.

If you want to include an expression in a condition, simply type it in. For example, you could include the following condition in the COM column of the EMPLOYEE table:

> (payrate*1.25)
Parent topic: Query Databases


Selecting From a List of Values

Restriction: This topic applies to Windows environments only.

You can use the IN predicate to check for a records having values that match a member of a list of values. For example, you could type the following into a cell of the EMPLOYEE table's ST column:

IN ('MD', 'VA', 'DC', 'NY')
Parent topic: Query Databases


Defining Computed Columns

Restriction: This topic applies to Windows environments only.

You can create a computed column that compares two or more columns in a table and produces aggregate and/or scalar results.

To create a computed column:

  1. *
    Click the Create Computed Column command from the Column menu, or click the Computed Column button on the toolbar.
  2. In the Computed Column dialog box, type or pick from the function and column lists to create a calculated field. For example, the following uses the string concatenation operator to combine last and first names into a single name.
      lname||","||fname
Parent topic: Query Databases


Renaming Fields

Restriction: This topic applies to Windows environments only.

If you want to rename the columns that appear in your result, you can create a computed column that contains, as an expression, just the name of the column you want to rename. Type in a new name in the Computed Column Name field. Your result column is automatically renamed. If you do not provide a name, a default (Column 1) is used.

Note:

This option is not supported by DB2 version 3.x and earlier. Therefore, it is not available in DB2 mode.

Parent topic: Query Databases


Finding Distinct Values

Restriction: This topic applies to Windows environments only.

You can create a computed column using the DISTINCT keyword to try to find all unique values in a column. When the DISTINCT keyword is used (instead of the default ALL), duplicate values are discarded. For example, querying the EMPLOYEE table enter the formula:

DISTINCT lname

and the computed column and resulting query do not show two rows with the LNAME Hurwood.

Parent topic: Query Databases


Adding Extended Conditions (And and Where)

Restriction: This topic applies to Windows environments only.

Some of the conditions on columns that can be added to a query cannot be expressed easily using the Query Conditions Grid. In these cases, you have two alternatives:

  • Edit the SQL statement, in which case you can include any valid condition (including nested SELECTS).
  • Include an extended search condition.

An extended search condition is simply another set of conditions that are appended to the Query Conditions Grid as AND conditions.

To define an extended search condition:

  1. Open a new or existing query.
  2. Click the Where (?) button on the toolbar.

    SQLWizard displays the Search Condition dialog box. You compose a series of extended search conditions at the top of this dialog box, one per row.

  3. On the first row, the first drop-down list contains only the NOT qualifier. You should use this if you want to negate the condition you create on this row.
  4. The next field is used to specify the left-hand side of the expression. Move to this field and type in the expression, or compose it using the tools at the bottom of the dialog box. There are drop-down lists containing functions, as well as operators and column names that are used to build the expression.
  5. The next control is a drop-down list containing comparison operators, including SQL predicates such as BETWEEN and IN. Select an operator from this list.
  6. The next field is used to specify the right-hand side of the expression. Move to this field and complete the expression.
  7. The last control on the row is a button to add another condition row to the dialog box. Click it to add another condition row.
  8. Move to the next row and click the down-arrow button on the first drop-down list. While in the first row, the drop-down list only contains the NOT option, in the second and subsequent rows, this list contains connection operators AND and OR, with or without the NOT qualifier. Choose one of the connection operators.
  9. Complete the expression on this row as you did for the previous row.
  10. When you are finished with the extended search condition, click OK to accept the changes.
  11. Examine the Query Conditions Grid. You will see that a new area labeled AND has been added, showing the conditions that you just defined. If you want to make changes to the conditions, double click the area to redisplay the Search Condition dialog box.

If you want to add conditions that cannot be expressed through the Query Conditions Grid columns or the Search Condition dialog box, switch to the SQL view and edit the SQL statement directly. Note that once you have made changes to the statement in the SQL Edit window, you will not be able to switch back to the Query Design window without discarding the changes. Therefore, you should save your query in the Query Design window before switching to the SQL Edit window, and save it from the SQL Edit window using a different name if you make changes.

Parent topic: Query Databases


Specifying Sort Order

Restriction: This topic applies to Windows environments only.

Often you will want to make data easier to understand by presenting it in a particular order. You can sort the result at the time the query is executed by creating an ORDER BY clause for the SELECT statement, or you can sort columns after the result is returned.

The advantages of sorting the query results using an ORDER BY clause are:

  • You can sort on columns that you do not retrieve.
  • Because the sort criteria are stored as part of the query, the query will always be properly sorted each time you run it.

The disadvantages of sorting the result using an ORDER BY clause are:

  • You are asking the database server to do additional work, which may affect the speed of other applications that are trying to use the database server.
  • If you are creating an ad hoc query, and don't know if you need all of the rows of the result, you still need to wait until they are retrieved and sorted before you can see any of the rows of the result.

This topic teaches you how to use SQLWizard's Query Design window to add an ORDER BY clause to your query.

To create an ORDER BY clause on a single column:

  1. Add the column you want to sort on to the Query Conditions Grid. If you do not want to see the column in the result, still add it to the grid, and then double click the title to hide it in the result.
  2. Click the title of the column to select the column.
  3. Click the Sort Column command from the Column menu.
  4. Choose Ascending or Descending from the Sort Column submenu. Ascending means the columns are sorted from 0 to 9 and A to Z (or as appropriate for international versions). Descending means the columns are sorted from 9 to 0 and Z to A (or as appropriate for international versions).
    Note: You can repeat the process above as many times as you like. Each time you add another column, it is appended to the ORDER BY clause. To see or modify all of the columns in the ORDER BY clause, switch to the SQL view, or follow the instructions for creating an ORDER BY clause on multiple columns.

To create an ORDER BY clause on multiple columns:

  1. Add all of the columns that you want to see in the result to the Query Conditions Grid.
  2. If there are columns that you do not want to see in the result, but that you want to use for ordering the result, add them to the Query Conditions Grid as well. For these columns, double click the column name to exclude the column from the columns displayed in the query result.
  3. Click the Sort command from the Query menu or use the Sort button on the toolbar.

    SQLWizard displays the Order By dialog box. This dialog box contains two lists: one containing all of the columns in the Query Conditions Grid, and the other containing the columns that will be included in the ORDER BY clause used to sort the result records. When you display the Order By dialog box for the first time, the list of Sorted columns is empty.

  4. To add a column to the ORDER BY clause, locate the column in the Unsorted Columns list and click it to select it. Then click the > button to move the name from the Unsorted Columns list to the Sorted Columns list. You can remove a column from the Sort Columns list by selecting it and using the < key. The >> button moves all columns in the Unsorted Columns list to the Sorted Columns list, while the << button moves all columns from the Sorted Columns list to the Unsorted Columns list.
  5. Once you have picked the columns you want to use for ordering the result, you can rearrange the order in which they appear in the ORDER BY clause. The first column in the ORDER BY clause is the primary sort column. Each additional column sorts the records in the group defined by the previous column. To move a column up in the list, click it and use the Up or Down buttons.
    Note: The first column in the list is the most significant column. Data is first sorted by this column, and each of the other columns are applied to the sorted rows in turn.
  6. You can also specify whether an ascending or descending sort sequence is to be used in sorting by a particular field. Ascending sorts go from 0-9 and A-Z (or as appropriate for international versions). Descending sort sequences go from 9-0 and Z-A (or as appropriate for international versions). To toggle between Ascending and Descending, click the arrow buttons beside a column name in the Sorted Columns list.

    *
    indicates ascending order.

    *
    indicates descending order.

  7. Once you are satisfied with the Sorted Columns list, click OK to close the dialog box.
  8. Now examine the Query Conditions Grid. You now see a new row labeled ORDER/GROUP, containing numbers and icons. The number indicates the order of the column in the ORDER BY clause, and the
    *
    or
    *
    symbol indicates whether the column is to be sorted in ascending or descending sequence.
  9. You can change the ORDER BY clause by redisplaying the Order By dialog box and modifying the Sorted Columns list as described above. Or you can click the ORDER/GROUP row and change the number and ascending/descending specification.
Parent topic: Query Databases


Retrieving Data From Two or More Tables

Restriction: This topic applies to Windows environments only.

In order to create a join, you need to have two or more tables visible in the Table Display Area.

To add more tables to create a join:

  1. From the Query Design window, click the Add Table button on the toolbar or the Add Table command from the Query menu.

    SQLWizard displays the Add Table dialog box.

  2. Click on the table you want to add.
    Note:

    Attempting to run a query involving tables from different locations will generate an error.

  3. Click the Add button to copy the table to the Table Display Area.
  4. Continue to add tables in this way until you have added all of the tables you want to join.
  5. When you are finished adding tables, click the Done button.
    Note:

    There is a limit of 15 tables in a FROM clause when running against XDB Server or DB2. Adding more than this number of tables will generate an error when you attempt to run the query.

    You can create nested SELECT statements that access many more tables than this limit. The limit applies to a single FROM clause.

Parent topic: Query Databases


Displaying Table Names

Restriction: This topic applies to Windows environments only.

When you are creating queries involving multiple tables, it is often useful to see the names of the table from which a column comes in the Query Conditions Grid. To add a row containing table names, click the Show Table Names button in the toolbar, or use the Show Table Names item in the Query menu.

Parent topic: Query Databases


Avoiding Cartesian Products

Restriction: This topic applies to Windows environments only.

The following method may be used to avoid Cartesian products when you create a join.

  • Usually you should have at least t-1 join conditions for a join between t tables.
  • If there are multi-column primary keys on a referenced table, there should be as many join conditions between the child table and the referenced table as there are columns in the primary key of the referenced table.
  • Turn on the Prohibit Cartesian Products option.
Parent topic: Query Databases


Prohibiting Cartesian Products

Restriction: This topic applies to Windows environments only.

If you do not want to rely solely on your own tests for avoiding Cartesian products, you can set an option to prohibit Cartesian products. With this option set, each time you run a query, it is tested to determine whether or not there are join conditions between the tables. If there are no join conditions, an error results.

The test does not determine whether or not the join conditions are logical or correct for your application. However, by blocking Cartesian products in this way, you will reduce the chance that you will forget to put any join conditions on your query.

Note:

This test is only effective for queries run from within the SQLWizard. Queries embedded in host programs or executed from other programs are not affected. You may want to test your queries in SQLWizard before running them in other programs.

Another way to minimize the chance that you will generate a Cartesian product is to make use of SQLWizard's Auto Join facilities.

To prohibit (block) Cartesian products:

  1. From the Query menu, click the Current Query Options command (or, in the Micro Focus Program Group or Folder, click the Options icon).
  2. If using Options to set this item as your default, click the Query tab to access the Query options.
  3. Click the Prohibit Cartesian Products checkbox to select it.
  4. Close the Query Options dialog box (or Options window, as appropriate).

    Now when you run an SQL query in SQLWizard, it will be tested to determine if it might return a Cartesian product.

Parent topic: Query Databases


Manual Joins

Restriction: This topic applies to Windows environments only.

When you put more than one table into the Schema View of a prompted query, you should define a join condition. SQLWizard provides several methods for doing this, including Auto Join capabilities.

The following are steps to define a join on your own:

To define a join manually:

  1. Click the New Query button, or click the New command from the File menu followed by the Query command from the submenu.

    SQLWizard displays the Add Table dialog box.

  2. Click the EMPLOYEE and DEPT tables and click the Add button to add them to the query.
  3. Click the Done button to close the Add Table dialog box. When the Query Design window is displayed, you will see both tables side by side in the Table Display Area.
  4. Select some columns from each table by clicking on them. You now have a join, but it is the type of join known as a Cartesian product, which is a combination of all the rows in one table with all of the rows in the other table.

    To prevent the occurrence of a Cartesian product, you need to define a join condition, which relates a column in one table to a column in another table. The EMPLOYEE and DEPT tables are joined on the DEPT field. Scroll through the EMPLOYEE table's Column Selection List until you see the DEPT field. Click it, and drag to the DEPT field in the DEPT table. A line representing the join will appear.

Parent topic: Query Databases


Preventing Cartesian Products with Auto Joins

Restriction: This topic applies to Windows environments only.

When you select from more than one table without defining a join condition that maps the rows of one table to the rows of another table, you create a Cartesian product, which is generally an expensive result that includes every combination of records between the tables, and usually has no real meaning.

SQLWizard supports automatic joining of columns in three cases. Note that the third case is not usually a very good method for automatically joining tables. Frequently, there are like column names that have no join relationship with each other. It is recommended that you use the first two options whenever possible, or manually define joins.

To define an automatic join, click the Current Query Options command from the Query menu to display the Query Options dialog box, and check the desired auto join methods. Alternatively, click the Auto Join command from the Query menu to display a submenu of the desired methods. Note that if you change the auto join options after having selected your tables, you are asked if you want to apply the join criteria after the fact.

The three cases on which automatic joins can be performed between the columns of two tables are when:

  • There exists a foreign menu key relationship between two tables.
  • There exists a primary key column in one table, and a column with the same name in another table.
  • There is a column in one table that has a name that matches a column in the other table.
Parent topic: Query Databases


Non-equijoins

Restriction: This topic applies to Windows environments only.

An equijoin is the most common kind of join condition. It tests whether the two sides of the condition are equal. A non-equijoin uses a comparison operator other than =. You can test if a column from one table contains values that are >, ?, <, ? or < > values in another column.

To create a non-equijoin condition:

  1. Define a regular equijoin using the auto join facilities, or by dragging from one column to another.
  2. Double click the = operator in the small box on the join line.

    SQLWizard displays the Join Options dialog box.

  3. Select a comparison operator from the drop-down list in the center of the dialog box. The operators that contain a + are for defining outer joins.
  4. Click OK. The new comparison operator appears in the join condition.

    When the Join Options dialog box closes, the new operator appears on the join line between the joined tables.

Parent topic: Query Databases


Outer Joins

Restriction: This topic applies to Windows environments only.

Suppose you wanted to display information about all suppliers and the parts they supply. Joining the SUPPLIER and PARTSUPP tables will retrieve this information for every supplier that has provided parts. But you would not see any information for suppliers that have not yet supplied parts. You would have no indication that such a supplier even existed.

An outer join is a special kind of join that solves this problem by finding all of the matches between the joined columns, just like a regular join. However, unlike a regular join, those records in one table that have no match at all in the second table are identified.

An outer join is designated by a plus sign in parentheses on the side of the child table. The parent table is the one for which you want rows even if there are no matching child records in the other table.

To create an outer join condition:

  1. Define a regular equijoin using the auto join facilities, or by dragging from one column to another.
  2. Double click the = operator in the small box on the join line.

    SQLWizard displays the Join Options dialog box.

  3. Select a comparison operator from the drop-down list in the center of the dialog box. Make sure the operator includes the (+) on the child side - that is, on the side where you expect to see null values.
  4. Click OK. The new comparison operator appears in the join condition.
  5. When you run the command you should see some rows with values for the parent table fields, but only null values for the child rows.
    Note:

    Outer joins are not supported against all database systems. For example, outer joins are not supported against XDB Server in DB2 mode, or when running against DB2.

Parent topic: Query Databases


Creating a Summary Query

Restriction: This topic applies to Windows environments only.

There may be times when you want to generate rows of data that summarize data in your tables. For example, you may want to find a sum or an average for the values in a column. To do this, you create a computed column that includes aggregate (column) functions.

If a computed column involving an aggregate function is added to a query, the system automatically defines a GROUP BY clause for you. If you want to modify this system-defined GROUP BY clause, or if you want to add a GROUP BY clause for a query that does not require one, use the Group command from the Query menu or the Group button on the toolbar.

To add a column to the GROUP BY clause, move it from the left list box to the right list box using the arrow buttons. To change the relative order of columns within the GROUP BY clause, use the Up and Down buttons.

Note:

When including aggregate functions in queries, SQLWizard requires that non-aggregate columns be grouped. SQLWizard automatically performs this grouping for you, and will not allow you to make illegal moves between boxes. You can, however, change the order of the columns in the GROUP BY list.

Uses for summary queries include:

  • Finding the total number of records in a query.
  • Finding the number of records in a group.
  • Finding the sum of a column for the set of records in a group.
  • Finding the sum of a column for all records in a query.
  • Finding the min or max of a set of values.
  • Finding the min or max for all records in a query.
  • Finding the average for all records in a query.
  • Finding the average of a column for all records in a group.
  • Finding rows that contain duplicate values.
  • Finding rows that contain unique values.
  • Finding rows that match the average, min, or max value in a column.
Parent topic: Query Databases


Searching for Duplicate Values

Restriction: This topic applies to Windows environments only.

Before you can create a unique index on a column, you must make certain that there are no duplicate values in the column. An easy way to do this is to use a summary query that groups records based on the index fields, and include a HAVING condition that tests to see if the count of records in any group is greater than 1.

To search for duplicate values:

  1. Open or create a query that includes just the columns on which you want to build a unique index. These are the columns you need to test for duplicates.
  2. Open the Group By dialog box using the Group button on the toolbar or select the Group command from the Query menu.
  3. Move all columns to the Grouped Columns list by clicking the >> button.
  4. The order of the columns in the GROUP BY clause is not important in this particular query. However, it is always a good idea to list the columns in hierarchical order. For example, City should come after State, because each state can contain many cities.
  5. Click the OK button to accept the Group specification.
  6. Click the Having command on the Query menu .
  7. Enter the expression Count(*) > 1, as shown below.
  8. Click OK to accept the Having specifications.
  9. The query is now ready to run or save. When you run the query, you see the list of records that have duplicate values in the candidate index columns.
Parent topic: Query Databases


Creating a Union

Restriction: This topic applies to Windows environments only.

A union is a set of SELECT statements pasted together with a UNION clause. The union returns the combined result sets from both queries. You can use SQLWizard to help you build a union .

Note:

SQLWizard allows you to combine up to approximately 33 query results using the UNION operator (the maximum number will depend upon the complexity of your query). You must make certain when writing these queries that the data types of the columns in the SELECT clause match.

To create a union:

  1. Create the first query using the Query Design window.
  2. Create the second query using another Query Design window. Make certain that there is a one-to-one correspondence between the columns in each SELECT clause.
  3. Now switch to SQL view by clicking on the SQL button on the toolbar.
  4. Copy the SELECT statement to the clipboard by selecting it and then clicking the Copy command from the Edit menu.
  5. Click the other Query Design window, and switch it to the SQL view.
  6. Go to the end of the second SELECT statement and type the keyword UNION.
  7. Now paste the query from the clipboard after the UNION keyword to complete the union. You are ready to save or run.
Note:

When you save, you must save from the SQL view because UNION is not supported by the Query Design window. When you save the query, you will be warned that you will lose your prompted SQL changes.

Parent topic: Query Databases


Creating a View

Restriction: This topic applies to Windows environments only.

A view is a virtual table that is logically defined over one or more tables. Its definition includes a SELECT statement that determines the fields as well as the values it can contain at any point in time. Views permit you to query subsets of data or joins of multiple tables as though they are an actual table. Only the view definitions are stored - not the data retrieved by the view. Some views can be updated. An update of a view affects the underlying table. Views may make it easier to access data by organizing it in more meaningful ways, or by restricting the rows retrieved to those that pertain to the needs of a particular application. Views can also be used for security reasons, since privileges can be granted on a view instead of on the underlying table.

You can use a SELECT command generated through the Query Design window as the basis of a CREATE VIEW statement.

To create a view from a SELECT statement:

  1. Create a new query or open a saved query. It is a good idea to run the query to see if it was correctly designed, and that it retrieves the rows you expected it would.
  2. Switch to SQL view using the SQL button on the toolbar.
  3. Position the cursor in front of the SELECT clause of your query.
  4. To create a view called TodaysOrders, type the clause CREATE VIEW TodaysOrders AS in front of the SELECT statement.
    Note:

    You cannot create a view using a SELECT statement that contains an ORDER BY or UNION.

    The simplest way to determine whether or not a view is updatable is to try to create it with the WITH CHECK OPTION clause. If the view cannot be updated, an error will occur when you try to create it.

Parent topic: Query Databases


Creating a DELETE Statement

Restriction: This topic applies to Windows environments only.

The easiest way to delete individual records is to run a query and switch to ALLOW EDIT mode. However, if you want to perform a batch delete, you can use the WHERE condition generated for a query as the WHERE condition for a DELETE statement.

To convert a SELECT command to a DELETE command:

  1. Create a query that retrieves the rows that you want to delete. You may want to test the query to make certain it retrieves the correct rows. You should also save the query before proceeding if you want to access it again in the Query Design window. You must include at least one column in this query.
  2. Switch to SQL view.
  3. Block the SELECT clause and click the DEL key to delete it.
  4. In place of the SELECT clause, type the keyword DELETE.
  5. Run or save the SQL statement from the SQL Edit window.
Parent topic: Query Databases


Creating an UPDATE Statement

Restriction: This topic applies to Windows environments only.

The easiest way to update individual records is to run a query, and switch to ALLOW EDIT mode. However, if you want to perform a batch update, you can use the WHERE condition generated for a query as the WHERE condition for an UPDATE statement.

To convert a SELECT command to an UPDATE statement:

  1. Create a query that retrieves the columns and rows that you want to update. You may want to test the query to make certain it retrieves the correct rows. You should also save the query before proceeding if you want to access it again in the Query Design window.
  2. Switch to SQL view.
  3. Replace the keyword SELECT with the keyword UPDATE.
  4. Enter the name of the table you are updating, and follow it with the keyword SET.
  5. After each of the column names, enter an = and an expression. If you decide you do not want to update the column, delete it from the list.
  6. Run or save the SQL statement from the SQL Edit window.
    Note: You cannot update a join or a query that contains DISTINCT, ORDER BY, GROUP BY, UNION, or Computed Columns.
Parent topic: Query Databases


Creating an INSERT Statement

Restriction: This topic applies to Windows environments only.

The easiest way to insert individual records is to run a query, and switch to ALLOW EDIT mode. However, if you want to perform a batch insert, you can use a query as the basis for an INSERT with SELECT statement.

To convert a SELECT statement to an INSERT statement :

  1. Create a query that retrieves the columns and rows from one table that you want to insert in another table. You may want to test the query to make certain it retrieves the correct rows. You should also save the query before proceeding if you want to access it again in the Query Design window.
  2. Switch to SQL view.
  3. In front of the SELECT keyword, enter the keywords INSERT INTO followed by the name of the table into which you want to insert rows.
  4. If the order of the columns in your SELECT clause does not match the order of the target columns in the table you are adding records to, you will have to create a comma-separated list of columns inside of parentheses. This list should be placed immediately after the name of the target table, and before the SELECT clause. You can drag the column names from the Catalog Browser so you don't have to type them.
  5. Run or save the SQL Statement from the SQL Edit window.
    Note: Insert Into is an XDB Server SQL extension. It is not available when running against non-XDB Server databases or when running in DB2 mode.
Parent topic: Query Databases


Work with Query Results

Restriction: This topic applies to Windows environments only.
  • Working with Columns Overview
  • Fixing a Column in Place
  • Rearranging Result Columns
  • Hiding Columns
  • Printing a Result
  • Changing the Result View
  • Saving a Result to a File
Parent topic: SQL Wizard


Working with Columns Overview

Restriction: This topic applies to Windows environments only.

The Column menu commands are available only if a Result window is active and data is displayed in Result Table view. These commands operate on the currently selected column(s).

To select a column, double click the column name.

Parent topic: Work with Query Results


Fixing a Column in Place

Restriction: This topic applies to Windows environments only.

You can lock one or more columns against the left edge of the Result window to use for reference while you horizontally scroll the other columns.

To fix a column in place:

  1. Double click a column name to highlight the column.
  2. Click the Fix command from the Column menu.

    The column will be locked against the left edge of the window (if you selected a non-edge column, it will automatically be moved to the left edge). Note that when you scroll the Result window horizontally, the fixed column remains in place, while the other columns scroll by.

  3. Repeat steps 1 and 2 for each column you want to lock to the left side of the window. The columns will appear in the order in which you fixed them.

To free a fixed column:

  1. Click the Free command in the Column menu.

    The right-most fixed column is released. The scroll bar is readjusted to allow horizontal scrolling of this column.

  2. Repeat step 1 for each column you want to release.
    Note: Fixed columns that had initially occupied a non-edge position in the table are not returned to their original position when they are freed. If you want to return a column to its original position, you may do so by dragging it back into place.
Parent topic: Work with Query Results


Rearranging Result Columns

Restriction: This topic applies to Windows environments only.

When you are in the Result Table view, you can rearrange the columns on your Result window by dragging them to a new position. Changes you make to the result by rearranging the columns only affects the current Result window. The next time you run the query, the columns will be in the order designated by the query. You can change the order of columns in the SELECT clause of the query if you want them to always appear in a specific order. Regardless of the order in which columns are shown in a result, the order of columns stored in the database is not changed.

To move columns in a Result Table view:

  1. Click the name of a column and hold down the left mouse button.

    SQLWizard displays a phantom outline the size of the column title.

  2. Keeping the mouse button pressed, drag the outline right or left to a position between two other columns. Release the mouse button to drop the column in the new position.

    SQLWizard rearranges the columns to move the dragged column between the other two columns.

Parent topic: Work with Query Results


Hiding Columns

Restriction: This topic applies to Windows environments only.

You may find times when it would be easier to examine your result if you could temporarily exclude one or more columns from the Result window. SQLWizard allows you to do this in two ways.

To temporarily remove a single column from the result table view:

  1. Double click a column name to select the column you want to hide.
  2. Click the Hide Column command from the Column menu. The selected column will be removed from the Result window.
    Note:

    You cannot hide fixed columns. You must free a fixed column before you can hide it.

To temporarily remove or redisplay several columns on a result table view:

  1. Click the Select Hidden Column command on the Column menu to display the Select Hidden Column(s) dialog box.
  2. Move each column name to the desired list. The columns listed in the Displayed Columns list will be displayed on the Result Table when the dialog box is closed; those in the Hidden Columns list will be temporarily removed from the Result table.

    To move a column from one list to the other, click its name to highlight it; then click the appropriate arrow button to move it to the other list. Alternatively, double click a field name to move it to the other list.

    To select multiple contiguous names on a list, hold down the Shift key while clicking on the first and last entry of the desired list of names. To select multiple non-contiguous names, hold down the Ctrl key while clicking on each name you want to select.

    When the selected names are highlighted, click the appropriate arrow button to move the highlighted names to the other list.

  3. When the columns are in the desired lists, click the OK button to return to the Result window.

    When the Result window redisplays, you will be able to scroll to see all of the columns you placed in the Displayed Columns list, but those in the Hidden Columns list will not be shown.

Parent topic: Work with Query Results


Printing a Result

Restriction: This topic applies to Windows environments only.

To print the contents of a Result window:

  1. Be sure that the Result window you want to print is the active window.
  2. Click the Print command from the File menu to display the Print dialog box.
  3. Specify your desired print options.
  4. Click OK to send the results to the printer or print queue.
Parent topic: Work with Query Results


Changing the Result View

Restriction: This topic applies to Windows environments only.

When you successfully run a query or open a table, SQLWizard displays the results in the view you specify. You specify the desired views in any of the following ways:

  • You can set a default view using the Options utility.
  • You can set a default view for the session using the Current Query Options command from the Query menu.
  • You can select a result view before you run the query, using the Result Table View or Result Form View command on the Query menu.
  • After a Result window is displayed, you can switch between Table and Form views using either the Result Table or Result Form command from the Query menu, or by clicking on the Table View or Form View button on the toolbar.
Parent topic: Work with Query Results


Saving a Result to a File

Restriction: This topic applies to Windows environments only.

To output the contents of a Result window to a file rather than to the printer, choose the Output command from the File menu.

To save the contents of a Result window to a file:

  1. Make certain that the Result window you want to save is the active window.
  2. Click the Output command from the File menu to display the Output File (Save As) dialog box.
  3. Specify a file name.
  4. Click OK to save the results to a file.
Parent topic: Work with Query Results


Use the Result Window for Data Entry

Restriction: This topic applies to Windows environments only.
  • Enabling Edit Mode
  • Updating Records
  • Inserting New Records
  • Deleting Records
  • Undeleting a Deleted Record
Parent topic: SQL Wizard


Enabling Edit Mode

Restriction: This topic applies to Windows environments only.

Because there is additional overhead in preparing a query result for Edit mode, the default is to disable Edit mode when a query is run. If you want to make Edit mode the default for all queries that you run, use the Query Run tab in the Options utility to set Allow Editing on.

Note: Certain query results are not editable. For example, a join cannot be edited. Also, if you are running against a database other than XDB Server, and the Check Unique Key option is enabled, your tables must have a primary key or unique index defined before you will be allowed to enable Edit mode.

To enable Edit mode:

  • To enable Edit mode before you run a query, click the Allow Editing command on the Query menu.
  • To enable Edit mode after you run a query (a Result window is active), click the Allow Editing command on the Record menu.
Parent topic: Use the Result Window for Data Entry


Updating Records

Restriction: This topic applies to Windows environments only.

When you are in Edit mode, you can type in changes directly on the Result Table or Result Form. As you make the changes, they will be reflected in the Result window.

You can use the clipboard features of your operating environment to copy data from records and paste it into other applications. When you are in Edit mode you can copy data from one field and paste it into another field in the Result window.

Note: You can only cut, copy, or paste the data from one field at a time. You cannot copy an entire record or set of records to the clipboard.
Note: When cutting, copying, or pasting large amounts of data (such as in a varchar or longvarchar field), it may be faster to open a zoom window instead of working in the cell of the Result window. To open a zoom window, double click the desired field in the Result window, or place your cursor in the field and click Zoom from the View menu.
Parent topic: Use the Result Window for Data Entry


Inserting New Records

Restriction: This topic applies to Windows environments only.

SQLWizard allows you to type in the values for a new record by moving to the blank record provided at the end of every Result window or by using Data Entry mode. If you are working with a large result set, and do not want to take the time to move to the end of the result set, you can switch to Data Entry mode, which shows only newly inserted records.

To insert a record in a result window:

  1. Make certain you are in Edit mode by checking the Allow Editing command in the Record menu.
  2. Click the New command from the Record menu. This will move the cursor to a blank record at the end of the result set, marked with an @ symbol.
  3. Begin typing the data for the new record. As you type, a new blank record is appended at the end of the result set, so that you will be ready to insert the next record.
  4. Move out of the current record to insert it into the database.

To insert records in Data Entry mode:

Data Entry mode provides you with a special view of a Result window that only shows newly inserted records. All existing records are temporarily hidden from view.

  1. Make certain that you are in Edit mode by checking the Allow Editing command on the Record menu.
  2. Click the Data Entry command from the Record menu. The Result window will be redisplayed. Initially you will only see a blank record into which you enter data for a new record.
  3. Enter data into the new record. A new blank record will appear at the bottom of the result set.
  4. As you enter the data for each record and move to the next record, the new record is inserted into the database.
Parent topic: Use the Result Window for Data Entry


Deleting Records

Restriction: This topic applies to Windows environments only.

You can delete a single record from the Result window. If you want to delete many records at once, you should write an SQL DELETE statement.

To delete a record:

  1. Click the record number in the left column to select the record.
  2. From the Record menu, click the Delete command.
  3. At the confirmation dialog box, click OK to confirm the delete action.
Parent topic: Use the Result Window for Data Entry


Undeleting a Deleted Record

Restriction: This topic applies to Windows environments only.

After you delete a record, you can undo the delete operation using the Undo Delete command on the Record menu. The record will be marked undeleted and will reappear in the Result window.

To undo a delete:

  1. Open the Record menu.
  2. Click the Undo Delete command, if it is enabled.

    If the Undo Delete command is not enabled, the record cannot be undeleted from the Result window. If you are working with Autocommit turned off, you may still be able to rollback the operation.

Parent topic: Use the Result Window for Data Entry


Import Files

Restriction: This topic applies to Windows environments only.
  • Accessing the Import Utility
  • To import data downloaded from a mainframe
  • To import data from a PC application
  • Choosing a File Format and Source File
  • Choosing an Existing Table to Receive Your Data
  • Creating a New Table to Receive Your Data
  • Saving an Import Specification
  • Opening an Import Specification
  • Clearing Specifications from the Import Window
  • Resolving Import Errors
  • Viewing Your Source File
  • Viewing Your Batch Command File
  • Setting Import Options
  • Setting Import Defaults
  • Constructing a Batch Import File
  • Running a Batch Import File
  • Running Batch Import from the Command Line
Parent topic: SQL Wizard


Accessing the Import Utility

Restriction: This topic applies to Windows environments only.

The SQLWizard Import utility is accessed using the New command on the File menu.

To access the Import window:

  1. From the File menu, click the New command.
  2. Click Import from the submenu.

    SQLWizard displays the Import window.

    Notice that the name in the title bar remains untitled until you save the specifications to an import batch file. This is accomplished using the Save As command from the File menu or by exiting the Import window. When you exit the Import window without saving, you are prompted to save the Import file. This will save an import batch file to the path and file name you specify.

Parent topic: Import Files


To import data downloaded from a mainframe

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. Click New on the File menu.
  3. Click Import.
  4. On the Import window, select the type of file from the Format list.
  5. Change the settings as appropriate for the type of file you are importing.
  6. Click Browse to find the file you want to import (or type its location and name and press Enter).

    The data structure appears in the XDB Table Information group.

  7. Make any changes you require to the data types and other table structure information.
  8. Select Create Table if you want to create a new table.
  9. Select Replace Data if the table already exists and you want to replace its data with the imported data.
  10. Click Browse to specify the table's location and name (or type the location and name in the Table field and press Enter).
  11. Click Run on the Import menu.

    A new table is created or an existing table is updated with the imported data.

Parent topic: Import Files


To import data from a PC application

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. Click New on the File menu.
  3. Click Import.
  4. On the Import window, select the type of file from the Format list.
  5. Change the settings as appropriate for the type of file you are importing:
    • Delimited (Free-Format) ASCII Files - fields are delimited by a fixed character, usually a comma or a tab
    • Columnar (Fixed-format) ASCII Files - fields and records have fixed lengths
  6. Click Browse to find the file you want to import (or type its location and name and press Enter).

    The data structure appears in the XDB Table Information group.

  7. Make any changes you require to the data types and other table structure information.
  8. Select Create Table if you want to create a new table.
  9. Select Replace Data if the table already exists and you want to replace its data with the imported data.
  10. Click Browse to specify the table's location and name (or type the location and name in the Table field and press Enter).
  11. Click Run on the Import menu.

    A new table is created or an existing table is updated with the imported data.

Parent topic: Import Files
Related information
Delimited (Free-Format) ASCII Files
Columnar (Fixed-format) ASCII Files


Choosing a File Format and Source File

Restriction: This topic applies to Windows environments only.

The first step when importing a file into an XDB Server table is to choose a source file and specify the format of that source file. Some source file formats require you to specify additional parameters. The following steps are required when importing most source file types.

To specify a source file:

  1. Choose a format that reflects the type of file you want to import from the drop-down list.
  2. Specify the format items required for the selected format. As you choose different formats, the requirements displayed in the Source File Information section vary.
  3. Click the Browse button in the Source File Information section to display the Open Import dialog box. Use the List Files Of Type drop-down list to select the type of files to display.
  4. Choose the path and name of a source file. The default path is the application path. Click OK.

    SQLWizard examines the source file, creates a suggested table definition for the table (if not DSNTIAUL) and displays it in the XDB Table Information section of the window.

    Note:

    If importing large files, use the Options command from the Import menu to limit the number of records that will be read to determine the suggested table definition.

  5. At this point, you have two options for the destination of your imported data.
    • You can specify an existing XDB Server table as the destination for your data. In this case, you can choose to overwrite or append the import data.
    • You can create a new table to receive the imported data. You can use the suggested table format or modify the format as desired.
Parent topic: Import Files


Choosing an Existing Table to Receive Your Data

Restriction: This topic applies to Windows environments only.

The following steps are required when choosing an existing XDB Server table into which you want to insert the imported data.

To choose a table to receive your imported data:

  1. Specify the file whose contents you want to import.
  2. Click the Browse button in the XDB Table Information section on the Import window.

    SQLWizard displays the Open dialog box.

  3. Choose the desired location, AuthID, and table name of the destination table and click OK.

    The selected location, AuthID, and table name appear in the Table field on the Import window. Also, SQLWizard retrieves the table definition from the system catalog and displays it in the Table Definition Grid at the bottom of the Import window.

    Note:

    *
    Instead of selecting a destination table as described in steps 2 and 3, click the Table tab in the Catalog Browser dialog box, and drag a table name to the Table field on the Import window.

  4. You can now choose whether to append or replace data. If you wish to replace (overwrite) the data that exists in the selected table, click the Replace Data checkbox. Otherwise, new data from the file will be appended to the existing data in the table.
  5. Click the Run button or click the Run command from the Import menu to import the data.

    The status of the import operation is displayed in the status bar across the bottom of the window. When the import completes, this line indicates that the import is complete and lists the number of records imported.

Parent topic: Import Files


Creating a New Table to Receive Your Data

Restriction: This topic applies to Windows environments only.

You can use SQLWizard Import to create a table to hold the data you are importing.

To create a new table to receive your imported data:

  1. Specify the file whose contents you want to import.
  2. Review the suggested table definition and decide if you need to change it. There are two ways to change the table definition:
    • Revise specifications on the Table Definition Grid on the Import window, as explained in Step 3.
    • Use the definition of an existing XDB Server table as a template for creating the new table. To do this, choose an existing table using the Browse button in the XDB Server Table Information section or drag a table from the Catalog Browser dialog box. Then change the name of the table. The Create Table checkbox will automatically be checked. You can make any desired changes to this new table's definition as described in Step 3.
  3. You can modify any of the non-gray fields in the Table Definition Grid. To make a change, click the desired field and change any information. If there are multiple entries for the selected field, a drop-down list appears as shown below. Otherwise, type the desired information.
    Note: If you need to restore the XDB Server-suggested table definition (based on the source file), use the Recalculate command on the Import menu. This command will reread the source file and recalculate a table definition from it.

  4. *
    When you have finished entering your specifications, click the Run command on the Import menu or click the Run button on the toolbar.

    The status of the import operation appears in the status bar at the bottom of the window. When the import completes, a completion message appears and the number of imported records is listed.

Parent topic: Import Files


Saving an Import Specification

Restriction: This topic applies to Windows environments only.

You save an import specification in the same manner as you would save any file. You can save an import specification before or after you run it.

To save an import specification:

  1. *
    Click the Save button on the toolbar, or click the Save or Save As command from the File menu. If you click Save As, or if you click Save and this file has never been saved before, the standard Save dialog box is displayed.
  2. Choose a destination drive and path where you want to store the Batch Import file. Enter or select a file name. The default path is the current Application Path. The default file extension is .imp.
Parent topic: Import Files


Opening an Import Specification

Restriction: This topic applies to Windows environments only.

An import specification that has been saved can be opened and reused to save time respecifying the import options.

To open an import specification:

  1. *
    Click the Open button on the toolbar or click the Open command from the File menu.

    SQLWizard displays the Open dialog box. If an Import window is active, the List Objects Of Type field shows the *.imp extension and all files with that extension are listed. If an Import window is not active, click the down-arrow button for the List Objects Of Type field to display the drop-down list; select the *.imp extension.

  2. Choose the name of the import file you want to open to display its specifications in the Import window.
    Note:

    Only batch files containing one import transaction can be opened into an Import window. To run a Batch Import file containing more than one transaction, use the Run Batch command from the File menu.

Parent topic: Import Files


Clearing Specifications from the Import Window

Restriction: This topic applies to Windows environments only.

After an import process completes, you can clear the contents of the Import window before entering specifications for the next file you want to import.

To clear current import specifications from the Import window, click the Clear Form command from the Import menu. The current specifications are removed from the Import window and are replaced with default settings where appropriate. Defaults are based on your settings in the Import Options dialog box and the Default Settings dialog box

Parent topic: Import Files


Resolving Import Errors

Restriction: This topic applies to Windows environments only.

SQLWizard Import allows you to set error handling options on the Import Options dialog box. You can specify the action to be taken when an error is encountered, and you can have Import generate two different kinds of log files.

If you encounter errors, use the Source File command from the View menu to compare the source file against selections made on the Import window. This is most effective with free- and fixed-format ASCII files.

Parent topic: Import Files


Viewing Your Source File

Restriction: This topic applies to Windows environments only.

The Import utility allows you to view the contents of your source file. If the file has delimiters, this feature allows you to see what the delimiter characters are. For fixed column files, you can use this feature to check the column lengths and starting positions.

To view the contents of a source file:

  1. Click the Source File command from the View menu.

    SQLWizard displays the Open Source File dialog box.

  2. Choose the source file you want to view.
  3. Click OK.

    The contents of your source file are displayed in a scrollable, sizable window. You can view source files of any format. However, this feature is most effective with ASCII files (see note regarding binary files, below).

    A ruler is provided so that you can quickly assess the column positions in your source file. Use the cursor keys to navigate through the source file contents.

    Note:

    If you are viewing a binary file, you may find that the viewer stops displaying data before it reaches the end of your file. This will occur if your data contains a null character (00 hex), which to the viewer, signals the end of data.

Parent topic: Import Files


Viewing Your Batch Command File

Restriction: This topic applies to Windows environments only.

The Import utility allows you to view the current import specifications as they would appear if they were saved to a Batch Import file. You can copy these commands to any text editor. This allows you to use SQLWizard to create any number of Batch Import transactions, and copy/append them in a file in your text editor. Later, you can use SQLWizard to run the series of import transactions as a batch file.

To view import specifications in Batch Import file format:

  1. Enter your import specifications.
  2. Click Batch Import Commands from the View menu.

    The import specifications are displayed in a scrollable and sizable window. Use the cursor keys to navigate through the import specifications. Use the Save As command from the File menu to save the import command as a Batch Import file.

Parent topic: Import Files


Setting Import Options

Restriction: This topic applies to Windows environments only.

Options you select on the Import Options dialog box remain in effect for the duration of the current session or until you change them. In this case, a session is defined as an open occurrence of the Import window. You can have multiple Import windows open at the same time and each Import window can be using a different set of values for the options.

Instructions for how to set import options are provided below.

To set import options:

  1. Click the Options command from the Import menu.

    SQLWizard displays the Import Options dialog box.

  2. Click to choose an Insert Mode.
    Note:

    Be aware of the limitations of using Engine Direct Write.

  3. Click to choose an On Error option to control error handling.
  4. For the Recalculate option, choose All or specify the number of records to be examined when SQLWizard suggests a table definition for the file you are importing.
  5. To specify a Commit Interval, click the checkbox in this section and enter a value to indicate how many records should be imported between each commit.
  6. To convert data from one code page to another, select an entry from the ASCII Conversion box. Leave the field set to (None) if no conversion is required.
  7. Click to choose the desired Logging methods. To track overall import errors, select the Errors checkbox and provide a file name. To track bad records and have them inserted in a file, select the Records checkbox and provide a file name.
  8. Click OK.
Parent topic: Import Files


Setting Import Defaults

Restriction: This topic applies to Windows environments only.

The Default Settings dialog box allows you to specify your preferred settings for import options. Choosing your own defaults means that each time you open a new Import window, your preferred settings will be in effect automatically. You can revert to SQLWizard's suggested default values at any time by clicking the Defaults button.

Default values can be set for Free-format ASCII, Fixed-format ASCII, and DSNTIAUL formats. In addition, you can set default values for the insert mode, commit interval, existing table append/replace option, and number of records to be read for the recalculate table function.

Instructions for how to set import options are provided below.

To set default parameters for Import:

  1. Click the Defaults command from the Import menu.

    SQLWizard displays the Default Settings dialog box.

  2. Select the desired defaults in each section of the dialog box. To revert to SQLWizard's suggested defaults, click the Defaults button.
  3. Click OK. The new defaults are available the next time you open a new Import window.
Parent topic: Import Files


Constructing a Batch Import File

Restriction: This topic applies to Windows environments only.

A Batch Import file may include many transactions to import many files of the same or different types, as necessary. A complete transaction must be defined for each file being imported. Collectively, the batch commands for a given transaction are a set of parameters that describe the source file and the destination table.

Perhaps the easiest way to construct a Batch Import file containing multiple imports is to let SQLWizard create the batch commands for you. For each file you want to include in your Batch Import file, fill in the required information on an Import window. Then use the Save As command from the File menu to save the Batch Import specifications. After you have created these individual Batch Import files, use any text editor to copy and paste all of the batch commands into one file. Add comments as desired.

When constructing a Batch Import file, keep in mind the following:

  • Each transaction in a Batch Import file must begin with a name or label in square brackets to separate each set of batch commands. For example, you might want to enter the name of the table to identify the transaction, such as [EmployeeTable].
  • Each Batch Import command must end with a semicolon (;).
  • You may include spaces and blank lines as needed to improve readability. The spaces and blank lines are ignored by SQLWizard.
  • C-style comments can be used in the specifications. For example: /* comment */.
  • All commands are case-insensitive. You may use any combination of upper and lower case letters (for example, INSERT_MODE is the same as Insert_Mode).

Not all Batch Import commands are required for all file types. For instance, the field and record delimiter (FLD_DELIMITER and REC_DELIMITER, respectively) commands are required only for importing delimited, free-format ASCII files. Likewise, the OFFSETS command is required only for importing from columnar, fixed-format ASCII files.

Parent topic: Import Files


Running a Batch Import File

Restriction: This topic applies to Windows environments only.

Saved Batch Import files have a file name extension of *.imp and are typically saved in the current application path. You can specify a different path for your batch file when you save it.

To run a Batch Import session:

  1. From the File menu, click the Run Batch command.
  2. Choose the desired Batch Import file.
  3. Click OK. If you choose an old-format batch file, import will prompt you to convert the file so that SQLWizard can run it.
    Note:

    If you are running under Windows, you can start a batch session by double clicking the .imp file name in the File Manager.

    Commands initiated from the .imp file begin to run in batch mode. If any bad data is found, error messages will be displayed depending on the way you set up your import options. (To set import options, use the Options command from the Import menu.)

    Import processing messages are displayed across the bottom of the SQLWizard window in the status bar.

Parent topic: Import Files


Running Batch Import from the Command Line

Restriction: This topic applies to Windows environments only.

In addition to running Batch Import from within SQLWizard, you can run it directly from the development environment's command prompt.

To run an import from the development environment's command prompt, call the xwiz40n program file, and pass it the name of your Batch Import file as shown below:

xwiz40n [-iiniFile] filename.IMP

where:

iniFile | specifies which .ini file Wizard should use when it runs the import. If you do not specify an .ini file, xdb.ini in the working directory is used.
filename | is the name of your Batch Import file. The filename must include the extension .imp in its name (such as imfile.imp). If you do not specify the path to filename, the .imp file must be in the current application path (the application path is specified on the PATHS tab).

The following example shows how a Batch Import file called "iempfile" would be run. In this example, the contents of file emp.ini is used to establish SQLWizard's operating configuration.

xwiz40n -ic:\emp.ini iempfile.imp
Parent topic: Import Files


Export Files

Restriction: This topic applies to Windows environments only.
  • Accessing the Export Utility
  • To export data for uploading to a mainframe
  • To export data to a PC application
  • To export DDL commands
  • Choosing a Target File and File Format
  • Specifying the Source Table in Design Mode
  • Specifying the Source Table in SQL Mode
  • Saving an Export Specification
  • Opening Export Specifications
  • Clearing Specifications from the Export Window
  • Resolving Export Errors
  • Viewing Your Target File
  • Viewing Batch Command Files
  • Setting Export Options
  • Setting Export Defaults
  • Constructing a Batch Export File
  • Running a Batch Export Session
  • Running Batch Export From the Command Line
Parent topic: SQL Wizard


Accessing the Export Utility

Restriction: This topic applies to Windows environments only.

The SQLWizard Export utility is accessed using the New command on the File menu.

To access the Export window:

  1. From the File menu, click the New command.
  2. Click Export from the submenu.

    SQLWizard displays the Export window.

    When you access the Export window, notice that the name in the title bar remains untitled until you save the specifications to a Batch Export file. This is accomplished using the Save As command from the File menu or by exiting the Export window. If you exit the Export window without saving, you are prompted to save the Export file specification. You can save the specification to a batch import or Batch Export file.

Parent topic: Export Files


To export data for uploading to a mainframe

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. In SQL Wizard, click New > Export on the File menu.
  3. On the Export window, in the Source Table Information group, click Browse to specify the table's location and name (or type the location and name in the Table Name field and press Enter).

    The names of all columns in the table appear in the Included list.

  4. Remove the names of any columns you don't want to export by clicking them in the list and clicking <<.
  5. Optionally, change the order of columns in the table by selecting a column name and clicking Up or Down to change its position in the list.
  6. Optionally, type a condition (in SQL syntax) in the Where Condition field to export a subset of rows in the table. For example: CUST_NO < 12850
  7. In the Target File Information group, select the type of file from the Format list.
  8. Change the settings as appropriate for the type of file you want to create.
  9. Click Browse to specify a location and name for the file you want to create (or type a location and name and press Enter).
  10. Click Run on the Export menu.

    A new file is created containing the data you specified.

Parent topic: Export Files


To export data to a PC application

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. In SQL Wizard, click New > Export on the File menu.
  3. On the Export window, in the Source Table Information group, click Browse to specify the table's location and name (or type the location and name in the Table Name field and press Enter).

    The names of all columns in the table appear in the Included list.

  4. Remove the names of any columns you don't want to export by clicking them in the list and clicking <<.
  5. Optionally, change the order of columns in the table by selecting a column name and clicking Up or Down to change its position in the list.
  6. Optionally, type a condition (in SQL syntax) in the Where Condition field to export a subset of rows in the table. For example: CUST_NO < 12850
  7. In the Target File Information group, select the type of file from the Format list.
  8. Change the settings as appropriate for the type of file you are importing:
    • Delimited (Free-Format) ASCII Files - fields are delimited by a fixed character, usually a comma or a tab
    • Columnar (Fixed-format) ASCII Files - fields and records have fixed lengths
  9. Click Browse to specify a location and name for the file you want to create (or type a location and name and press Enter).
  10. Click Run on the Export menu.

    A new file is created containing the data you have specified.

Parent topic: Export Files
Related information
Delimited (Free-Format) ASCII Files
Columnar (Fixed-format) ASCII Files


To export DDL commands

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Client > SQL Wizard.
  2. In SQL Wizard, click New > Export on the File menu.
  3. On the Export window, in the Source Table Information group, click Browse to specify the table's location and name (or type the location and name in the Table Name field and press Enter).

    The names of all columns in the table appear in the Included list.

  4. Remove the names of any columns you don't want to export by clicking them in the list and clicking <<.
  5. Optionally, change the order of columns in the table by selecting a column name and clicking Up or Down to change its position in the list.
  6. Optionally, type a condition (in SQL syntax) in the Where Condition field to export a subset of rows in the table. For example: CUST_NO < 12850
  7. In the Target File Information group, select SQL Statements from the Format list.
  8. Check any options you want to include.
  9. Click Browse to specify a location and name for the file you want to create (or type a location and name and press Enter).
  10. Click Run on the Export menu.

    A new file is created containing the DDL corresponding to the options you selected.

Parent topic: Export Files


Choosing a Target File and File Format

Restriction: This topic applies to Windows environments only.

The first step in exporting table data to a file is to specify a file to receive the data and the format for that file. Some file formats require you to specify additional parameters. Instructions for defining the Target File are provided below.

To specify a target file to receive data:

  1. Click the Browse button to display the Open Export File dialog box and select an existing file. Alternatively, you can type a path and file name in the File Name field.
  2. Choose a format for the selected target file. Click the down-arrow button from the Format field to display a drop-down list. Notice that as you choose different formats, the requirements displayed in the Target File Information section vary.
  3. Specify the format items required for the selected format.
  4. At this point, you have two options for how to specify the source table from which you will be exporting data. You can use Design mode or SQL mode to specify this information.
    • Export Design mode allows you to select a table to export and specify a WHERE condition to limit the number of records that will be exported. In addition, you can select specific fields to export and change the order of the fields exported. Design mode is the default export display for the Export window unless you change your default to SQL mode using the Defaults command from the Export menu. See Specifying the Source Table in Design ModeSpecifyingtheSourceTableinDesignMode.307 to continue setting up your export specifications.
      Note:

      *
      Click the Export Design button on the toolbar to switch to Design Mode.

    • Export SQL mode allows you to specify export criteria using an SQL SELECT statement.
      Note:

      *
      Click the Export SQL button on the toolbar to switch to SQL Mode.

    Note:

    If you switch from Design mode to SQL mode after specifying table, column, and WHERE clause information, all of these specifications will be shown as an SQL SELECT statement in the SQL Query section of the Export window.

Parent topic: Export Files


Specifying the Source Table in Design Mode

Restriction: This topic applies to Windows environments only.

In Design mode, you choose an XDB Server table and the fields you want to include or exclude in the Source Table Information section of the Export window. You can add a WHERE condition to limit the data that will be exported from the table. If you do not specify a WHERE condition, all rows in the table will be exported.

Note: XDB Server indexes are not exported with the table. One exception to this rule is that if the table uses indexes and you export the table specifications and data to SQL Statements format, you can choose to have Export generate the SQL statement to re-create the indexes.

Instructions on how to choose a source table using Design mode are provided below.

To specify source table information and export using Design Mode:

  1. Click the Browse button in the Source Table Information section on the Export window.

    SQLWizard displays the Open dialog box. (Alternatively, you can type a fully qualified table name and skip to Step 3.)

  2. Choose the desired location, AuthID, and table; then click OK.

    The selected table name appears in the Table field as a three-part name. If you have not already entered a destination file name in the Source File Information area at the top of the Export window, a default target file name is entered for you. The default name uses the first eight characters of the table name and the extension for the format that has been specified.

    Note:

    *
    From the Catalog Browser dialog box, click the Table tab and drag a table name to the Table field on the Export window.

  3. Choose which columns you want to export by moving them to the Included and Not Included lists as desired. The default is to export all columns.

    To move a column from one list to the other, click its name to highlight it, then click the appropriate arrow button to move it to the other list. Alternatively, double click a column name to move it to the other list.

    To select multiple contiguous items on a list, hold down the Shift key while clicking on the first and last entry of the desired list of items. To select multiple non-contiguous items, hold down the Ctrl key while clicking on each name you want to select. When the selected items are highlighted, click the appropriate arrow button to move the highlighted items to the other list. To move all columns from one list to the other, click the appropriate double-arrow button.

  4. If desired, you can re-arrange the order of the columns. Your exported data can list the columns of information in a different order than the original table.

    To move a column within the Selected list, click its name to highlight it, then click the Up or Down button as desired.

  5. If desired, you can limit the number of records to be exported by specifying a WHERE condition. This allows you to export only those records that meet the condition. If you do not specify a WHERE condition, all rows in the specified XDB Server table will be exported.

    To specify a WHERE condition, type a standard SQL WHERE clause. You do not need to type the word where.

  6. Click the Run command from the Export menu to start the export process.
    Note:

    *
    Click the Run button on the toolbar to start the export process.

    SQLWizard displays the progress of the export operation in the status bar. When the export is complete, the status bar reports the number of records exported.

Parent topic: Export Files


Specifying the Source Table in SQL Mode

Restriction: This topic applies to Windows environments only.

When in SQL mode, the Export window permits direct entry of an SQL SELECT statement in the Query area to specify the table and columns to be exported. You can include a WHERE condition to limit the number of records that are selected for export.

Note:

*
Click the SQL Mode button on the toolbar to change from Design Mode to SQL Mode.

If you enter table, column, or WHERE condition information while in Design Mode, and then switch to SQL Mode, the SELECT statement will be generated for you. You can modify it as desired and export the table, or copy the SQL statement to a text editor.

Likewise, you can copy an SQL statement from the SQL Edit window or your text editor and paste it into the Query field on the Export window.

Note:

If you modify the SELECT statement in certain ways (add a JOIN, for example) you will not be able to switch to Design Mode.

Instructions on how to choose a source table using SQL mode are provided below.

To specify and export a source table using SQL mode:

  1. Click in the Query display area of the Export window to position your cursor in the text entry box.
  2. Type an SQL SELECT statement. Enter a WHERE clause if desired. Alternatively, you can copy a select statement from another SQLWizard window or from a text editor, and paste it into the Query display area of the Export window.
  3. Click the Run command from the Export menu.
    Note:

    *
    Click the Run button on the toolbar to start the export process.

    SQLWizard displays the progress of the export operation in the status bar. When the export is complete, the status bar reports the number of records exported.

Parent topic: Export Files


Saving an Export Specification

Restriction: This topic applies to Windows environments only.

You save an export specification in the same manner as you would save any file. You can save the export specification before or after you run it.

To save an export specification:

  1. Select the Save or Save As command from the File menu.
    Note:

    *
    Click the Save button on the toolbar.

    If you select the Save As command, or if save and this file has never been saved before, SQLWizard displays the standard Save As dialog box.

  2. Choose a destination drive and path, and enter or select a name for the export specification. The default paths are the current application path. The default file extension is .exp.
Parent topic: Export Files


Opening Export Specifications

Restriction: This topic applies to Windows environments only.

You can retrieve an Export specification that you previously saved with SQLWizard, and display it in an Export window.

To open an export specification:

  1. Click the Open command from the File menu.
    Note:

    *
    Click the Open button on the toolbar.

    SQLWizard displays the Open dialog box. If an Export window is active, the List Objects Of Type field shows the *.exp extension and all files with that extension are listed. If an Export window is not active, you may need to click the List Files Of Type drop-down menu to select the *.exp extension.

  2. Choose the name of the export file you want to open. Once selected, the specifications will display in the Export window.
    Note:

    Only batch files containing one export transaction can be opened into an Export window. To run a Batch Export file containing more than one transaction, use the Run Batch command from the File menu.

Parent topic: Export Files


Clearing Specifications from the Export Window

Restriction: This topic applies to Windows environments only.

After completing an export process, you can clear the contents of the Export window before entering specifications for the next table you want to export.

To clear current export specifications from the Export window, click the Clear Form command from the Export menu. The current specifications are removed from the Export window and are replaced with default settings where appropriate. Defaults are based on your settings in the Export Options dialog box and the Default Settings dialog box.

Parent topic: Export Files


Resolving Export Errors

Restriction: This topic applies to Windows environments only.

SQLWizard Export allows you to set error handling options on the Export Options dialog box. You can specify the action to be taken when an error is encountered, and you can have Export generate a log file.

If you encounter errors , use the Target File command from the View menu to compare the file containing the exported data against selections made on the Export window. This is most effective with free- and fixed-format ASCII files.

Parent topic: Export Files


Viewing Your Target File

Restriction: This topic applies to Windows environments only.

After you export a table, you can view the contents of the target file.

To view the contents of a target file:

  1. Click the Target File command from the View menu.

    SQLWizard displays the File Open dialog box.

  2. Choose the target file you want to view.
  3. Click OK.

    SQLWizard displays the contents of your target file in a scrollable and sizable window. You can view target files of any format. A ruler is provided so that you can quickly assess information about your target file.

Parent topic: Export Files


Viewing Batch Command Files

Restriction: This topic applies to Windows environments only.

The Export utility allows you to view the current export specifications as that would appear if they were saved to a Batch Export file.

Likewise, you can view the Batch Import commands that would be generated from the information currently appearing on the Export window. This is the SQL that would be saved if you use the Save or Save As command and saved the file as an Import (*.IMP) file.

Generating a batch import file at the time you are exporting data can help you when you plan to import the data onto another XDB Server. You would take the exported data file and the corresponding batch import file to the other XDB Server. Then use batch import on that machine to transfer the data onto that XDB Server.

To view export specifications in batch file formats:

  1. Enter specifications on the Export window.
  2. Click Batch Export Commands from the View menu to display the Batch Export form of the specifications in a scrollable, sizable window.
  3. Click Batch Import Commands from the View menu to display the batch import form of the specifications.
  4. If you plan to reuse this specification, click the Save As command from the File menu to save the batch file.
Parent topic: Export Files


Setting Export Options

Restriction: This topic applies to Windows environments only.

Options you select on the Export Options dialog box remain in effect for the duration of the current session or until you change them. In this case, a session is defined as an open occurrence of an Export window. You can have multiple Export windows open at the same time, and each Export window can be using a different set of values for the options.

Instructions for how to set export options are provided below.

To set export options:

  1. Click the Options command from the Export menu.

    SQLWizard displays the Export Options dialog box.

  2. Click to choose an On Error option to control error handling.
  3. To convert data from one code page to another, select an entry from the ASCII Conversion box. Leave the field set to (None) if no conversion is required.
  4. If you want to log errors that may be encountered during an export process, click the On checkbox in the Error Logging section and type a fully qualified file name. To choose an existing file for logging errors, click the Browse button to display the File Open dialog box.
  5. Click OK to save your preferences.
Parent topic: Export Files


Setting Export Defaults

Restriction: This topic applies to Windows environments only.

The Default Settings dialog box allows you to specify your preferred settings for exporting to Free ASCII, Fixed ASCII, and DSNTIAUL formats. In addition, you can specify which view of the Export window you would rather use: Design Mode or SQL Mode. Choosing your own defaults means that each time you open a new Export window, your preferred settings will be in effect automatically. You can revert to XDB Server's suggested default values at any time by clicking the Defaults button.

Instructions for how to set export defaults are provided below.

To set default format parameters for Export:

  1. Click the Defaults command from the Export menu.

    SQLWizard displays the Default Settings dialog box.

  2. Type your own defaults to use for each format.
  3. Click OK to save your defaults. These defaults will be used each time you open a new Export window.
Parent topic: Export Files


Constructing a Batch Export File

Restriction: This topic applies to Windows environments only.

A Batch Export command file can include many transactions to export many tables of the same or different types. A complete transaction must be defined for each table being exported. Collectively, the batch commands for a given transaction are composed of a set of parameters that describe the source table and the destination file.

Perhaps the easiest way to construct a Batch Export file containing multiple exports is to let SQLWizard create the batch commands for you. For each file you want to include in your Batch Export file, fill in the required information on an Export window. Then use the Save As command from the File menu to save the Batch Export specifications. After you have created these individual Batch Export files, use any text editor to copy and paste all of the batch commands into one file. Add comments as desired.

When construction a Batch Export file, keep in mind the following:

  • Each transaction in a Batch Export file must begin with a name or label in square brackets to separate each set of batch commands. For example, you might want to enter the name of the table to identify the transaction, such as [EmployeeTable].
  • Each Batch Export command must end with a semicolon ( ; ).
  • You may include spaces and blank lines as needed to improve readability. The spaces and blank lines are ignored by SQLWizard.
  • C-style comments (/*  comment  */) can be used in the specifications.
  • All commands are case-insensitive. You may use any combination of upper and lower case letters. (For example, FORMAT= FIXASC; is the same as Format = FIXasc.)

Not all commands are required for all file types. For instance, the FLD_DELIMITER and REC_DELIMITER commands are required only for exporting to free-format ASCII files. The SPACE command is required only for fixed-format ASCII files.

Parent topic: Export Files


Running a Batch Export Session

Restriction: This topic applies to Windows environments only.

Saved Batch Export files have a file name extension of .exp and are typically saved in the current application path. You can specify a different path for your batch file when you save it.

To run the Batch Export session:

  1. Click the Run Batch command from the File menu.
  2. Choose the desired Batch Export file.
  3. Click OK. If you choose an old-format batch file, Export will prompt you to convert the file so that SQLWizard can run it.
    Note:

    If you are running under Windows, you can start a batch session by double clicking the .exp file in the File Manager.

Commands initiated from the .exp file begin to run in batch mode. If any bad data is found, error messages will be displayed depending on the way you set up your Export Options. (To set Export options, use the Options command from the Export menu.)

Export processing messages are displayed across the bottom of the SQLWizard window in the status bar.

Parent topic: Export Files


Running Batch Export From the Command Line

Restriction: This topic applies to Windows environments only.

In addition to running Batch Export from within SQLWizard, you can run it directly from the development environment's command prompt.

To run an export from the development environment's command prompt, call the xwiz40n program file, and pass it the name of your Batch Export file as shown below:

xwiz40n [-iiniFile] filename.EXP

where:

iniFile | specifies which .ini file Wizard should use when it runs the export. If you don't specify an .ini file, xdb.ini in the working directory is used.
filename | is the name of your Batch Export file. The filename must include the extension exp in its name (for example, xfile.exp). If you do not specify the path to filename, the .exp file must be in the current application path (the application path is specified on the PATHS tab.

In following example, a Batch Export file called "xempfile" would be run. In this example, the contents of file emp.ini is used to establish SQLWizard's operating configuration.

xwiz40n -ic:\xdb\emp.ini xempfile.exp
Parent topic: Export Files


Use Batch SQL Scripts

Restriction: This topic applies to Windows environments only.
  • Creating a Script File
  • Saving and Reusing a Script
  • Running a Script
  • Running in Step Mode
  • Running From the Command Line
  • Using Host Variables
  • Changing Host Variable Values
Parent topic: SQL Wizard


Creating a Script File

Restriction: This topic applies to Windows environments only.

A script file is generally created by saving SQL statements from the SQL Edit window. For example, you can create a script by performing a query, then switch to the Edit window to incorporate additional SQL commands. You can also incorporate any of the special batch SQL commands, which functionality specific to batch operation.

SQLWizard's Export facility provides another way to create a script file. When you export data from XDB Server, you can optionally include SQL statements with it. This process creates a script file that, when run, automatically recreates the table from the exported data.

If you prefer, you can create a script by typing your SQL statements directly into a file using any ASCII text editor. Regardless of how you create your script file, the following script-file syntax must be observed:

  • Commands can be placed on separate lines terminated by a semicolon (;) or on the same line terminated by a semicolon (;).
  • Commands may be typed in upper or lower case.
  • Spaces and blank lines can be included to improve readability. Spaces and blank lines are ignored by SQLWizard.
  • Spaces are not required before and after an equal sign ( = ), however they can be included to improve readability.
  • Comments can be inserted by bracketing them in comment characters (e.g., /*comment text */), or by prefixing them with two hyphens.

    Both comment types are shown below.

      /* Get customer list with company & state   */
  /* List customers with balance over $2,000. */
  SELECT company, state, balance  --retrieve columns
  FROM customer             --from customer table
  WHERE balance>$2,000;        --show records with
  --balance over $2000
Parent topic: Use Batch SQL Scripts


Saving and Reusing a Script

Restriction: This topic applies to Windows environments only.

You can save the contents of an SQL Edit window to a .SQL file and retrieve it later to edit or run.

To save an SQL script from an active SQL Edit window:

  1. From the File menu, click the Save As command.

    SQLWizard displays the Save As dialog box.

  2. Choose SQL Scripts (*.SQL) from the list of Object Types.
  3. Provide a name for the file.
  4. Click OK to save the file.

To open an SQL script from an active SQL Edit window:

  1. From the File menu, click the Open command.
  2. Choose SQL Scripts (*.SQL) from the list of Object Types.
  3. Locate and select the file you want to open; then click OK.

    The script is opened in an SQL Edit window.

  4. Edit the file adding and deleting the necessary SQL commands. You can also incorporate batch commands.
Parent topic: Use Batch SQL Scripts


Running a Script

Restriction: This topic applies to Windows environments only.

You can run a batch script from within SQLWizard, with or without opening the script file in an SQL Edit window. You can also execute a script without opening SQLWizard, by calling the file from your development environment's command prompt.

To run a batch SQL script from an active SQL Edit window:

  1. From the File menu, click the Run Batch command.
  2. When the Run Batch dialog box appears, select the .SQL script file you want to run.
  3. Click OK. The batch SQL script is loaded and immediately begins to execute.

    After execution, a message box is displayed telling you that you will not be able to edit the contents of the selected batch SQL script in the current SQL Edit window. To edit the script, reopen it in a separate SQL Edit window.

  4. Click Continue.

    The results are displayed in the Result window.

Parent topic: Use Batch SQL Scripts


Running in Step Mode

Restriction: This topic applies to Windows environments only.

Use "step mode" to execute your batch SQL script one SQL command at a time.

To use the Step Mode feature:

  1. From the Query menu, click the Current Query Options command.

    SQLWizard displays the Query Options dialog box.

  2. Select the All Commands option in the Execute group box. This option ensures that the entire script is executed at run time.
  3. Click OK.
  4. From the Query menu, click Step Mode.
  5. Follow the steps described in Running a Script to run your batch SQL script.

    SQLWizard steps through the script one SQL command at a time, and displays the results of each command in a separate Result window.

Parent topic: Use Batch SQL Scripts


Running From the Command Line

Restriction: This topic applies to Windows environments only.

In addition to running a SQL script from SQLWizard, you can run it directly from your development environment's command prompt.

Note: You can run a script file by double clicking the SQL file name in the Windows File Manager.

To run a script from the development environment's command prompt, call the xwiz40n program file, and pass it the name of your script file as shown below:

xwiz40n [-iiniFile] filename.SQL

where:

iniFile | is the initialization file that SQLWizard uses when it runs the script. If you don't specify an initialization file, XDB.INI in the working directory is used.
filename | is the name of your SQL script file. If you do not specify the path to filename the script file must be in the current application path (the application path is specified on the Paths tab. Note: The filename must include the extension "SQL" in its name (for example, sfile.sql).

The following example shows how a script called "newmember" would be called. In this example, the contents of file member.ini will establish SQLWizard's operating configuration.

xwiz40n -ic:\member.ini newmember.sql
Parent topic: Use Batch SQL Scripts


Using Host Variables

Restriction: This topic applies to Windows environments only.

When you include host variables in batch SQL scripts, you are prompted for values. You can also specify values for host variables by using the Parameters command from the Query menu so that you will not be prompted at run time for values.

To run a batch SQL script that uses host variables:

  1. Select the Run Batch command from the File menu.

    SQLWizard displays the Run Batch dialog box.

  2. Choose the .SQL file you want to run; then click OK.

    The selected batch SQL script is loaded and it begins to execute.

  3. When prompted for host variables, type in the value.
  4. Click the Quotes checkbox if the value needs to be enclosed in quotes.

    Results of the batch SQL script are displayed in the Result window.

Parent topic: Use Batch SQL Scripts


Changing Host Variable Values

Restriction: This topic applies to Windows environments only.

After a query containing host variables has run (you have entered values for the host variables when prompted), the host variable values are saved. This allows you to re-run the query without being prompted each time.

It you need to change the values of the host variables, use the Parameters command from the Query menu. You can also use this command to preset the values for the host variables so that you are not prompted at run time.

To change or preset host variable values:

  1. From the Query menu, click the Parameters command.

    The Enter Host Variable Values dialog box is displayed containing all of the host variables for the current query, if previously run or previously specified.

  2. Make changes as needed.
  3. Click OK.
Parent topic: Use Batch SQL Scripts


Administer XDB Users and Groups

Restriction: This topic applies to Windows environments only.
  • Adding Users to the System
  • Deleting an AuthID
  • Updating an Existing User Specification
  • Adding a New Group and Assigning Users
  • Deleting a Group
  • Updating Your Group Information
  • Adding Priorities
  • Deleting Priorities
  • Updating Priorities
Parent topic: SQL Wizard


Adding Users to the System

Restriction: This topic applies to Windows environments only.

*
The Add button on the Add/Modify User dialog box allows you to add a new AuthID and its associated specification into the appropriate XDB Server system tables using the information currently displayed on the dialog box. Once information for a user has been inserted, it remains on the dialog box. You can type another new AuthID (using the previous AuthID's information as a template) to add more users.

When connecting to an XDB Server, the AuthID is checked against values in XDB Server System tables on the XDBACF database in the SYSTEM location to determine if there are any SecondaryIDs or groups associated with it. All available groups are displayed in a scrollable list. Groups to which a particular AuthID is assigned (if any) are highlighted.

Instructions for adding new users to an XDB Server's list of AuthIDs are provided below. See the description of the Add/Modify User dialog box for information about each item on that dialog box.

To add a new AuthID and privileges for a new user:

  1. Click the Users command from the Admin menu to display the Add/Modify User dialog box.
  2. Type a new AuthID in the User ID field or click the User ID drop-down arrow and select an existing user. You can use an existing user's specifications for a new user by typing a new AuthID over the old one.
  3. In the Security Options group:
    • Select Password Required if this user will be required to enter a password when connecting to the XDB Server.
    • Select Access Authority to enable this user to access the XDB Server. You can temporarily disable an existing AuthID by deselecting the Access Authority box, leaving all other AuthID information intact.
  4. If you checked Password Required, type a Password according to the required Enforcement Level setting at the bottom of the dialog box. Retype the same password in the Verification field. Be sure to tell the user the password you have assigned, and explain how the user can change it.
  5. In the User Types section, click User or Super User. A super user has special system-wide privileges as explained in the description of the Add/Modify User dialog box. Super-user status is usually reserved for XDB Server Administrators and their assistants.
  6. Specify optional items: Comments, Groups, and Priorities.

    If desired, type a comment in the User Comments field.

    If you have created groups, they will be displayed in the Group Membership list. Assign the user to one or more groups by clicking on the desired group name(s). (You can also assign users to groups when you create the groups.

    If you have created priorities, they will be displayed in the Priorities list. Assign the user to one or more priorities by clicking on the desired priority name(s).

    Note: To select multiple, contiguous names on a list, hold down Shift while clicking on the first and last entry of the desired list of names. To select multiple non-contiguous names, hold down Ctrl while clicking on each name you want to select.
  7. Click the Add button to insert this user's information to SQLWizard security tables.
  8. Add, delete or update other users if desired. When done, click the Close button to exit the Add/Modify User dialog box.
Parent topic: Administer XDB Users and Groups


Deleting an AuthID

Restriction: This topic applies to Windows environments only.

*
The Delete button allows you to remove an AuthID from the system based on the AuthID displayed. Confirmation is required before an AuthID is removed.

Note: You can temporarily deny a user's access to the system without deleting the AuthID or changing any specifications. To deny access, de-select the Access Authority checkbox, then click the Update button.

Instructions for deleting AuthIDs from an XDB Server's list of AuthIDs are provided below. See the description of the Add/Modify User dialog box for information about each item on that dialog box.

To delete an AuthID:

  1. Click the Users command from the Admin menu to display the Add/Modify User dialog box.
  2. Use the User Name drop-down list to choose the AuthID to be removed.
  3. Click the Delete button. SQLWizard prompts you to confirm the removal of the selected AuthID.
  4. Add, delete, or update other users if desired. When done, click the Close button to exit the Add/Modify User dialog box.
Parent topic: Administer XDB Users and Groups


Updating an Existing User Specification

Restriction: This topic applies to Windows environments only.

*
The Update button changes information for an existing AuthID. Any modifications you make for an AuthID on the Add/Modify User dialog box are not saved to the system tables until you click the Update button.

Instructions for modifying AuthID specifications are provided below. See the description of the Add/Modify User dialog box for information about each item on that dialog box.

To update modified specifications for an existing AuthID:

  1. Click the Users command from the Admin menu to display the Add/Modify User dialog box.
  2. Use the User Name drop-down list to choose the AuthID to be changed.
  3. Modify the desired specifications for the selected AuthID.
  4. Click the Update button to save your changes to the XDB Server security database.
  5. Add, delete or update other users if desired. When done, click the Close button to exit the Add/Modify User dialog box.
Parent topic: Administer XDB Users and Groups


Adding a New Group and Assigning Users

Restriction: This topic applies to Windows environments only.

*
Groups provide a method for controlling location, database, and table level access according to GroupID (GROUP NAME). Users with certain system needs can be given the required access by being in a group that has been granted privileges. When you grant an authority or privilege to a GroupID (using the SQL GRANT command), all users who are members of that group will have the privilege assigned to the group.

Instructions for how to create a new group and assign users to it are provided below. (If a group already exists, you also have the option to assign users to the group by using the Add/Modify User dialog box.

To add a new group and assign users:

  1. Click the Groups command from the Admin menu to display the Groups dialog box.
  2. Type a name in the Group Name (GroupID) field. The GroupID can be up to eight characters long and must follow the rules for a short identifier.
  3. If desired, type a comment about the new GroupID or its purpose in the Comments field. You can enter up to 254 characters.
  4. While you are still viewing the Groups dialog box, you can assign users to the group you are now creating by moving their AuthIDs from the User ID list to the Member Of list. AuthIDs remaining on the User ID list will not be members of the group. You can also assign a user to a group from the Add/Modify User dialog box.

    To move an AuthID from one list to the other, click its name to highlight it and then click the appropriate arrow button to move it to the other list. Alternatively, double click an AuthID to move it to the other list. Use a double-arrow button to move all AuthIDs to the other list.

    To select multiple contiguous names on a list, hold down Shift while clicking on the first and last entry of the desired list of names. To select multiple non-contiguous names, hold down Ctrl while clicking on each name you want to select. When the selected AuthIDs are highlighted, click the appropriate arrow button to move the highlighted AuthIDs to the other list.

  5. Click the Add button to create the group and its assigned members.
  6. Add, delete, or update other groups if desired. When done, click the Close button to exit the Groups dialog box.
Parent topic: Administer XDB Users and Groups


Deleting a Group

Restriction: This topic applies to Windows environments only.

*
When you delete a GroupID, all privileges associated with that group are deleted and all members of the deleted group are dissociated from that group.

Instructions for how to delete a group are provided below. See the description of the Groups dialog box for information about each item on that dialog box.

To delete a group:

  1. Click the Groups command from the Admin menu to display the Groups dialog box.
  2. Click the Group Name drop-down list to select the GroupID you want to delete.
  3. Click the Delete button. You are prompted to confirm deletion of the selected group.
  4. Add, delete, or update other groups if desired. When done, click the Close button to exit the Groups dialog box.
Parent topic: Administer XDB Users and Groups


Updating Your Group Information

Restriction: This topic applies to Windows environments only.

*
There are two items of information you can change in a group definition. You can modify the comment that describes the group or its purpose and you can change the list of users who are members of the group. (Another way to change group membership is by accessing an AuthID using the Add/Modify User dialog box.

Instructions for how to change items in a group definition are provided below. See the description of the Groups dialog box for information about each item on the that dialog box.

To modify an existing GroupID's comment and/or membership:

  1. Click the Groups command from the Admin menu to display the Groups dialog box.
  2. Click the Group Name drop-down list to select the GroupID you want to change.
  3. Change the comment or memberships as desired.
  4. Click the Update button. A message box is displayed giving you a summary of the modifications you made.
  5. Add, delete, or update other groups if desired. When done, click the Close button to exit the Groups dialog box.
Parent topic: Administer XDB Users and Groups


Adding Priorities

Restriction: This topic applies to Windows environments only.

*
Instructions for defining a new priority are provided below. See the description of the Define Priority dialog box for information about each item on that dialog box.

To add a new set of priorities:

  1. Click the Priorities command from the Admin menu to display the Define Priority dialog box.
  2. Click in the Priority Name field and type a name for the new priority set. (Click the Priority Name drop-down list to view the names of existing priorities.)
  3. Click in each field on the dialog and type the desired setting. (You can use Tab to move from field to field.
  4. Click the Add button to add the new priority and its specifications.

    As soon as a priority is defined, it can be assigned to an AuthID (use the Users command from the Admin menu.). However, it will not take effect until the XDB Server has been shut down and restarted.

  5. Add, delete or update other priorities if desired. When done, click the Close button to exit the Define Priority dialog box.
Parent topic: Administer XDB Users and Groups


Deleting Priorities

Restriction: This topic applies to Windows environments only.

*
When you delete a priority, all users who were assigned that priority are no longer restricted by any Governor limitations.

Instructions for deleting a priority are provided below. See the description of the Define Priority dialog box for information about each item on that dialog box.

To remove a priority from the system:

  1. Click the Priorities command from the Admin menu to display the Define Priority dialog box.
  2. Click the Priority Name drop-down list and select the priority you want to drop.
  3. Click the Delete button. A message box is displayed asking you to confirm deleting the currently displayed Priority.
  4. Add, delete or update other priorities if desired. When done, click the Close button to exit the Define Priority dialog box.
Parent topic: Administer XDB Users and Groups


Updating Priorities

Restriction: This topic applies to Windows environments only.

*
You can change any of the fields on the Define Priority dialog box, and update the system tables to reflect the new restrictions. Any user who has been assigned that priority will be under the new restrictions the next time the XDB Server is shut down and restarted.

Instructions for updating a priority are provided below. See the description of the Define Priority dialog box for information about each item on that dialog box.

To change an existing priority:

  1. Click the Priorities command from the Admin menu to display the Define Priority dialog box.
  2. Click the Priority Name drop-down list and select the priority you want to change.
  3. Click in each field on the dialog that you want to change and type the desired setting. (You can use Tab to move from field to field.)
  4. Click the Update button. A message box is displayed stating that the priority has been updated.
  5. Add, delete, or update other priorities if desired. When done, click the Close button to exit the Define Priority dialog box.
Parent topic: Administer XDB Users and Groups


Implement Security and Authority

Restriction: This topic applies to Windows environments only.
  • Setting Up Security
Parent topic: SQL Wizard


Setting Up Security

Restriction: This topic applies to Windows environments only.

The following is an overview of the process used to set up and activate security on an XDB Server. This procedure must be performed by someone with super-user authority.

Note: The following procedure assumes a single-server environment. If you are working in a multi-server environment or you are using a "global" security server, see your SQL Option Server Administration Guide for additional setup procedures.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Server Configuration.
  2. From the XDB Server or from any client workstation attached to the XDB Server, use Options to select the XDB Server, specify your super-user ID, and enable security. Set the options as follows:
    • On the Connect tab, select the XDB Server on which you want to set up security.
    • On the Connect tab, specify your super-user ID (e.g., INSTALL).
    • On the Security tab, enable the Client Security option.
  3. Use SQLWizard to create a "user ID" and password for each user of this XDB Server. Only the users that you define during this step will be allowed to log on to the Server, and they must present the proper user ID/password combination when they do so.
    Note: Apart from permitting access to an XDB Server, the user ID you create in this step 2 also serves as a user's default AuthID. You can override this default assignment by assigning a Secondary ID to the user, or the user can change it using the SET CURRENT SQLID command.

    When you create a user ID, you must also specify whether that user will have user or super user privileges. A super user can access any table on the Server and can perform operations such as creating and dropping locations. An XDB Server is shipped with one super user called INSTALL. You can create others at your discretion. However, super-user privileges should be limited to a few trusted users with database administration expertise. There are other classes of privileges you can assign to other users using the GRANT command. For details, see your SQL Option Server Administration Guide and topics for the GRANT command.

  4. When you are finished creating users, run the Options utility at each user's workstation and turn on the Client Security option. You must also inform your users of the user ID and password you assigned to them in step 3. Once they log on, they can change their password using SQLWizard's Change Password command.
Parent topic: Implement Security and Authority


SQL Option Server Administration

Restriction: This topic applies to Windows environments only.
  • To start the XDB Service Controller
  • To start the XDB Server Configuration Utility
  • To start the XDB Server
  • To start the XDB Server in blue screen mode
  • To stop the XDB Server
Parent topic: How to...


To start the XDB Service Controller

Restriction: This topic applies to Windows environments only.
  • From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Server > XDB Server Control.
Parent topic: SQL Option Server Administration


To start the XDB Server Configuration Utility

Restriction: This topic applies to Windows environments only.

Do one of the following:

  • From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Configuration > Server Configuration.
  • From the XDB Service Controller, click Configure.
Parent topic: SQL Option Server Administration
Related information
To start the XDB Service Controller


To start the XDB Server

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Servers > Server Control.
  2. Click Start.
  3. Once started, click Close.
Parent topic: SQL Option Server Administration
Related information
To start the XDB Service Controller
To shut down the XDB Server
To log on to an XDB Server
To log off an XDB Server


To start the XDB Server in blue screen mode

Restriction: This topic applies to Windows environments only.
  • From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Server > XDB Server Monitor.
Parent topic: SQL Option Server Administration


To stop the XDB Server

Restriction: This topic applies to Windows environments only.
  1. From the main menu, click Run > Tools > Data Tools > SQL Option for DB2 > Servers > Server Control.
  2. Click Stop.
  3. Once stopped, click Close.
Parent topic: SQL Option Server Administration
Related information
To start the XDB Service Controller
To start the XDB Server
To log on to an XDB Server
To log off an XDB Server


Reference

Restriction: This topic applies to Windows environments only.
  • SQL Reference
  • XDB Directive Options
  • Batch SQL Commands
  • Batch Import Commands
  • Batch Export Commands
  • SQL Option for DB2 Error Messages
  • User Interface Reference
Parent topic: SQL Option for DB2


SQL Reference

Restriction: This topic applies to Windows environments only.
  • Overview
  • SQL Commands
  • Syntax Notation
  • DB2 Support
  • SQL Statements
  • Clauses
  • Functions Overview
  • System Table Overview
  • Overview of XDB Server Specifications
  • XDB Server Reserved Words
  • SQL Communications Area (SQLCA)
  • SQL Descriptor Area (SQLDA)
  • SQL Option Server TUTORIAL Location
  • Objects Used by the SQL Option Server
Parent topic: Reference


Overview

Restriction: This topic applies to Windows environments only.

In the relational model, data are logically presented in two dimensional tables made up of rows and columns, as shown in the figure below. The intersection of a row and a column is known as a field. Fields contain individual data items called field values. The rows of a table, also known as records, are made up of a sequence of values that describes an occurrence of an entity (for example, a set of values that describes a particular employee). The columns of a table consist of a collection of attributes, which are characteristics of an entity. For example, each employee has an employee ID and a name.

When creating database objects, you must follow certain conventions. For example, every table must have a unique name, and within a table, every column must have a unique column name and a data type. When you ask the XDB Server to retrieve or modify data, it performs the job on the set of rows and columns you specify. An action may affect rows, columns or fields.

Colums and Rows

There exists no universally accepted standard for database terminology. Throughout this reference and other XDB Server documentation, we use a number of relational terms that have specific meanings that may differ from normal usage.

  • Database
  • Data Objects
  • Language Elements
  • Naming Conventions
  • Three-Part Names
  • Code Page Support
  • Data Types
  • Other Data Types
  • Assignment And Comparison
  • Constants
  • Special Registers
  • Labeled Duration
Parent topic: SQL Reference


Database

Restriction: This topic applies to Windows environments only.

The use of the term database varies widely in the industry. The term database, as used in XDB Server documentation, has two meanings:

  • Relational Database

    In the generic sense, a database is an entire collection of data managed by a database management system. It is in this sense that the term database is used most often in XDB Server documentation.

  • XDB Server Database

    In a more specialized sense, a database is a named object created using the CREATE DATABASE command. A database consists of a collection of tables or a collection of table spaces and index spaces. Generally, if used in this sense, the term database is followed by the database name (if it is not clear from the context that an XDB Server database object is being discussed).

Parent topic: Overview


Data Objects

Restriction: This topic applies to Windows environments only.

Most of the following terms are named data elements or objects that together allow you to organize data to best suit your needs. Both simple data models and complex systems that mirror mainframe configurations can be constructed with the building blocks provided. Except for records (rows), all database objects are created using one of the forms of the CREATE statement.

  • Alias
  • AuthID
  • Catalog
  • Column
  • Database
  • Index
  • Index Space
  • Key
  • Location
  • Query
  • Record
  • Storage Group
  • Synonym
  • Table
  • Table Space
  • View
Parent topic: Overview


Alias

Restriction: This topic applies to Windows environments only.

An alias is an alternate one-part name for the three-part name of a table or view. An alias can be assigned to a table in the current location or in a remote location. This differs from a synonym, which can rename an object only in the current location. Aliases can be used by anyone, while synonyms can only be used by the AuthID that created them.

For example, the one-part name, EMPLOYEE, can be created as an alias for the three-part name, TUTORIAL.TUTORIAL.EMPLOYEE. Thereafter, the alias, EMPLOYEE , can be used to reference TUTORIAL.TUTORIAL.EMPLOYEE.

Parent topic: Data Objects


AuthID

Restriction: This topic applies to Windows environments only.

An authorization ID, or AuthID, is a name associated with a user or process for auditing, monitoring and security purposes. An AuthID is also the second part of a three part name.

Parent topic: Data Objects


Catalog

Restriction: This topic applies to Windows environments only.

The system catalog is a collection of special system defined tables that contain information about objects in the system. Most of the system tables are automatically maintained by the system when administrative tasks are performed, but there are some that must be updated manually. The XDB Server catalog consists of DB2-compatible tables (created with AuthID SYSIBM) and XDB Server-specific tables (created with AuthID SYSXDB.)

Parent topic: Data Objects


Column

Restriction: This topic applies to Windows environments only.

A column is an attribute (or characteristic) of the entities described by the rows of a database table or result table. Each column is associated with a column name and a data type. Although the terms field and column are frequently used interchangeably in discussions of SQL programming; when we use the term field in the context of relational tables, we are referring to the intersection of a row and a column in a table or query result.

Parent topic: Data Objects


Database

Restriction: This topic applies to Windows environments only.

An XDB Server database is a collection of tables, indexes and table spaces. Each database definition occupies a separate directory. A database consists of a number of files that may span several directories and disks if stogroups are used. Database names are stored in the system table SYSIBM.SYSDATABASE. A database is created using the CREATE DATABASE statement. Every location contains a default database (DSNDB04) and a system catalog database (DSNDB06). In addition a location may include a number of user-defined databases. The SYSTEM location includes two additional databases: XDBACF (stores information on security and access) and DSNDDF (stores information on other locations.)

Parent topic: Data Objects


Index

Restriction: This topic applies to Windows environments only.

An index is an optional data structure used to speed retrieval of data or enforce certain constraints (such as uniqueness) on the records in a table. When you create an index on a column (or columns), the XDB Server stores an appropriately ordered list of all the values in that column as a separate index file. While this can greatly improve the performance of queries, maintaining an index slows down DML update operations (such as INSERT and DELETE) somewhat, and the index itself takes up memory. You must make a decision about creating indexes each time you create a table.

Parent topic: Data Objects


Index Space

Restriction: This topic applies to Windows environments only.

An index space is a defined area of mainframe disk storage that is used to store the entries of an index. The XDB Server currently provides only syntactical support for index spaces. No entries are made into the system catalog when index space commands are executed.

Parent topic: Data Objects


Key

Restriction: This topic applies to Windows environments only.

A key is one or more columns used to identify a row, or to establish a constraint such as uniqueness or referential integrity relationships. When you create or alter a table, you can establish keys which place constraints on the values that can be entered into that table's columns. Establishing a Foreign Key, for example, causes the XDB Server to reject any column values that violate the criteria defined for that Foreign Key constraint. The XDB Server supports three types of keys: primary, candidate and foreign.

Parent topic: Data Objects


Location

Restriction: This topic applies to Windows environments only.

A location is a collection of tables, databases and related objects organized in a structured fashion. An XDB Server database system can have multiple locations, all managed by the same XDB Server. Through the use of a three-part naming scheme and other security measures, users can access more than one location at a time, as well as access remote locations, which are managed by other copies of an XDB Server, or by DB2 (accessed through XDB Link). The current location is set using the SET LOCATION TO or the CONNECT statement.

In order to operate, the XDB Server requires a SYSTEM location, which contains information on other locations, as well as security information. It is strongly recommended that you store your own data in a location other than the SYSTEM location.

Parent topic: Data Objects


Query

Restriction: This topic applies to Windows environments only.

A query is a SELECT command that generates a result table or an intermediate result table. A query may be a subcomponent of another type of SQL statement, such as an INSERT or CREATE VIEW command. A nested query may also be part of a search condition. There are three forms of a query: subselect, fullselect and select-statement. For more information on these three query forms (as well as the SELECT INTO statement), see the SELECT command in SQL Commands. See also SELECT Clause, FROM Clause, and WHERE Clause. Queries are not named data objects, however XDB Server provides special facilities for saving and recalling queries as though they were named objects. Also, when writing programs containing embedded SQL, queries are usually associated with a cursor, which can be equated with a query name in the scope of the program.

Parent topic: Data Objects


Record

Restriction: This topic applies to Windows environments only.

A record is a row of a table that presents information about a particular object, event or relationship. The words row and record are used interchangeably in this reference. A record is identified by the values contained in its fields. Note that a record is not a named data object. It is uniquely identified by the data it holds.

Parent topic: Data Objects


Storage Group

Restriction: This topic applies to Windows environments only.

A storage group (stogroup) is a name assigned to a specific drive and directory used for physical storage. When using XDB Link to access DB2, a stogroup refers to a set of DASD volumes on which data is stored.

Parent topic: Data Objects


Synonym

Restriction: This topic applies to Windows environments only.

A synonym is another name given to an existing table or view. Usually a synonym is used to define a more meaningful name for use by a particular application, or by a particular set of users. Synonyms are frequently used to replace two or three-part object names with one-part names (synonyms themselves can only be defined as one-part names). Synonyms can only be used to refer to a data objects in the current location, and can only be used by the AuthID that created them. This differs from aliases, which can rename objects in other locations, and can be used by anyone.

Parent topic: Data Objects


Table

Restriction: This topic applies to Windows environments only.

A table is named data object that consists of a collection of homogeneously defined rows, all with consistent column names and data types. A table is the data object that actually stores the data that describes an entity or relationship. A result table is the output of a query (SELECT command). A result table also presents data in a two-dimensional format consisting of rows and columns. However, a result table is unnamed and transient.

Parent topic: Data Objects


Table Space

Restriction: This topic applies to Windows environments only.

A table space is a physical area of disk space that holds a table. The table space object is provided for compatibility with DB2, and its use is optional when running against an XDB Server database. The XDB Server records all information about table spaces in the system catalog, but does not actually create table spaces.

Parent topic: Data Objects


View

Restriction: This topic applies to Windows environments only.

A view is a virtual table that is logically defined over one or more tables in a location. Its definition includes a SELECT statement that determines the columns displayed, as well as the values it contains at any point in time. Views permit you to query subsets of data or joins of multiple tables as though they are an actual table. Only the view definition is stored in the location -- not the data retrieved by a view. Some views are updatable. Update commands performed on views actually affect the underlying table(s). Views may make it easier to access data by organizing it in more meaningful ways, or by restricting the rows retrieved to those that pertain to the needs of a particular application. Views can also be used for security reasons. For example, a user might be given access to only a specified set of records or columns.

Parent topic: Data Objects


Language Elements

Restriction: This topic applies to Windows environments only.

This topic describes the basic syntax elements used to construct SQL keywords, command statements and object names.

More:

  • Characters
  • Tokens
  • Identifiers
  • NULL Value
  • Characters
  • Tokens
  • Identifiers
  • NULL Value
Parent topic: Overview


Characters

Restriction: This topic applies to Windows environments only.

The elementary symbols of the SQL language are ASCII characters -- which may be classified as letters, digits and special characters -- plus non-English characters (or extended character sets) provided by IBM standard code pages.

  • Letters

    These are the letters of the alphabet (A-z). Letters are stored as entered by the user, however the sort sequence used for ordering and comparing data (including case sensitivity) is set by the XDB Server administrator for a particular location. A user can use the location default or define a special sort sequence.

  • Digits

    These are the numeric characters between 0 and 9.

  • Special Characters

    These are all characters other than letters and digits.

  • Extended Character Sets

    These are non-English characters.

Parent topic: Language Elements


Tokens

Restriction: This topic applies to Windows environments only.

The syntactical elements of the SQL language are called tokens. Tokens are divided into two types:

  • Ordinary Tokens

    These are numeric constants, ordinary identifiers, or keywords. Ordinary tokens cannot include spaces, and must be followed by either delimiter tokens or spaces.

  • Delimiter Tokens

    These are string constants, delimited identifiers, operators (=, <=, <, >=, >, !=, ^=), or special characters identified in command syntax.

When a command extends to more than one line, tokens cannot be broken in the middle.

Parent topic: Language Elements


Identifiers

Restriction: This topic applies to Windows environments only.

Identifiers are tokens used to form names. They fall into two categories:

  • Ordinary Identifiers

    These must begin with a letter (A-z), and may include letters (including standard IBM code page extended characters), digits and the special characters #$%&{}. The maximum length of ordinary identifiers depends on the object they name, as shown below. See XDB Server Specifications for a complete list of identifier limits.

    Short Identifiers. These are up to 8 characters long. Examples are database names and AuthIDs.

    Long Identifiers. These are up to 18 characters long (except location names are up to 16 characters.) Examples are column and table names.

    Follow the character selection rules below when naming short or long identifiers:

    • The first character can be chosen only from the letters of the alphabet (A-z) if using XDB mode.
    • If using DB2 mode, the letters of the alphabet (A-z), the special characters @#$, and IBM Code Page extended characters can be chosen for the first character position.
    • All following characters can follow the rules for Ordinary Identifiers defined above (which apply equally to XDB mode and DB2 mode).
  • Delimited Identifiers

    These consist of one or more characters enclosed within double (") or single quotes ('). A delimited identifier may contain either double quotes or apostrophes (or single quotes), in which case the identifier is usually delimited by the other type of quote. For example, the string Joe's Place can be used as a delimited identifier when written as:

    "Joe's Place"

    You can place both " and ' characters within the same string by using "" for " if you are using " as the string delimiter, or '' for ' if you are using ' as the string delimiter. For example, to enter the string value 5'11" into a character field, use a command like:

    UPDATE patient
SET height='5''11"'
WHERE name="o'HARA"
Parent topic: Language Elements


NULL Value

Restriction: This topic applies to Windows environments only.

A NULL value is an undefined value for a field, indicating there is no data available. For sorting purposes, the NULL value's ordinal value depends on its location's definition. The XDB server considers NULL values to be the smallest possible value in all non-EBCDIC environments and with sensitive EBCDIC locations. In all other EBCDIC locations, NULL is sorted as the highest possible value.

Note that NULL values are not the same as blank or zero. NULL values are treated as undefined in mathematical operations, with the result that many expressions involving NULL are in turn resolved as NULL, or undefined.

Parent topic: Language Elements


Naming Conventions

Restriction: This topic applies to Windows environments only.

On an XDB Server, database objects are assigned names, or identifiers, made up of ASCII characters (with the option of specifying extended character sets). Naming conventions depend on the object being named. The following list defines the terms used for certain types of database object names. Keep in mind that a short identifier is up to 8 characters long, while a long identifier is up to 18 characters long.

More:

  • AuthID
  • Column Name
  • Database Name
  • Index Name
  • Location Name
  • Table Name
  • Table Space Name
  • View Name
  • AuthID
  • Column Name
  • Database Name
  • Index Name
  • Location Name
  • Table Name
  • Table Space Name
  • View Name
Parent topic: Overview


AuthID

Restriction: This topic applies to Windows environments only.

A short identifier that is associated with a user or process for auditing, monitoring and security purposes. AuthIDs must be unique within the system. However, an AuthID can be used by more than one individual or session.

Parent topic: Naming Conventions


Column Name

Restriction: This topic applies to Windows environments only.

A long identifier that designates a table, view or result column. A column-name may be qualified or unqualified. A qualified column-name is prefixed with a qualifier followed by a period. A qualifier may be a table-name, view-name, correlation-name, or query-name.

The column name can be used to:

  • Define the name of the column in a table or view, as in a CREATE TABLE command.
  • Identify a column in a table or view, as in a CREATE INDEX or a COMMENT ON command.
  • Specify values of a column or intermediate result, as in a function, expression, GROUP BY clause, ORDER BY clause, or search condition.

In the above contexts only, column names may be qualified by prefixing them with a table name, view name or correlation name, followed by a period. Qualification is used to express correlated references, or to resolve ambiguous references. It can also be used simply as a matter of convenience.

Note that column names must be qualified when appearing in COMMENT ON commands.

Parent topic: Naming Conventions


Database Name

Restriction: This topic applies to Windows environments only.

A short identifier that designates a database. Database-names must be unique within a location.

Parent topic: Naming Conventions


Index Name

Restriction: This topic applies to Windows environments only.

A long identifier that designates an index. An index-name qualified by an AuthID must be unique within a location.

Parent topic: Naming Conventions


Location Name

Restriction: This topic applies to Windows environments only.

An identifier that designates a subsystem. For compatibility with DB2, a location-name is limited to 16 characters in length, but otherwise follows the rules for a long identifier. Location-name must be unique within all locations to be accessed by a particular copy of the XDB Server.

Parent topic: Naming Conventions


Table Name

Restriction: This topic applies to Windows environments only.

A long identifier that designates a table. A table name may be qualified or unqualified. A qualified table name is prefixed with a qualifier followed by a period. Table names that are qualified by location name and AuthID are known as three-part-names. A table name must be unique within all locations when it is qualified by location name and AuthID. An unqualified table name must be unique among all tables within a location that have the same owner.

Parent topic: Naming Conventions


Table Space Name

Restriction: This topic applies to Windows environments only.

A short identifier that designates a table space. A table space name must be unique within a physical XDB Server database.

Parent topic: Naming Conventions


View Name

Restriction: This topic applies to Windows environments only.

A long identifier that designates a view. It must satisfy the same rules as a table name, and must be unique among table names.

Parent topic: Naming Conventions


Three-Part Names

Restriction: This topic applies to Windows environments only.

A data object name can be partially or fully qualified, or unqualified -- consisting of the table-identifier alone. Three-part names are provided by the XDB Server to support the concept of distributed units of work (DUW), which allows an application to access data at different servers and locations.

More:

  • Fully Qualified Table Names
  • Partially Qualified Table Names
  • Fully Qualified Table Names
  • Partially Qualified Table Names
Parent topic: Overview


Fully Qualified Table Names

Restriction: This topic applies to Windows environments only.

A fully qualified (or three-part) table name consists of three distinct elements separated by periods:

location-name.authid.table-identifier

The first qualifier, location-name, indicates which location should be searched for the table. On an XDB Server, there can be multiple locations per server, while in DB2 the location name designates the DBMS (or subsystem) at which the table is stored. The SYSTEM.SYSIBM.SYSLOCATIONS table catalogs all locations accessible to the XDB Server.

The second qualifier, authid, is the Authorization ID (AuthID) that designates the owner of the table.

Parent topic: Three-Part Names


Partially Qualified Table Names

Restriction: This topic applies to Windows environments only.

Partially qualified table names can be one-part or two-part names. A two-part table name consists of the table-identifier qualified by the authid, and implicitly qualified by the location-name of the current location.

A one-part table name consists of the table-identifier only, which is implicitly qualified by the location-name of the current location, and the Current SQLID special register. The value of the Current SQLID special register is determined by the following rules:

  • For static SQL statements, the Current SQLID is the identifier specified in the QUALIFIER option of the BIND command used to bind the SQL statements, or the owner of the plan or package.
  • For dynamic SQL statements, the Current SQLID is the identifier contained in the Current SQLID special register -- initially the same as USER, but changing to reflect execution of a SET CURRENT SQLID command. The Current SQLID can also be influenced by security exits and SecondaryID specifications.
Note:

Aliases and synonyms can be used for alternative names for a table or view. Aliases can be used to assign alternative names for tables and views that are not in the current location. Synonyms can only be used to rename tables or views in the current location.

Parent topic: Three-Part Names


Code Page Support

Restriction: This topic applies to Windows environments only.

The character set used for naming database objects includes code page support for several standard IBM Code Pages. Code pages allow you to choose from a wide range of non-English characters when naming database objects. The XDB Server supports several IBM standard code pages that provide an extended character set when naming database objects, and when typing data into tables. The code pages supported and their character set definitions are shown in Code Page Character Sets.

The code page characters are in addition to the base character set. The base character set depends on the SQL Compatibility Mode under which you are running:

  • In XDB mode, the base character set includes: a-z, A-Z, 0-9, and the special characters # $ % & { } and _.
  • In DB2 mode, the base character set includes: a-z, A-Z, 0-9, and the special characters # @ $ and _. (Do not use an underscore (_) in an AuthID.)

The SQL Compatibility Mode is set in the Options Utility. For more information on the SQL Compatibility Mode, see the Options User's Guide. Characters from the selected code page may be used in:

Alias Names | Index Space Names
AuthIDs | Stogroup Names
Collection Names | Synonyms
Column Names | Table Names
Constraint Names | Table Space Names
Data Entry | View Names
Index Names |

Do not use any code page characters in a database name or location name. To maintain consistency with DB2, database and location names are restricted to the characters in the base character set.

Parent topic: Overview


Data Types

Restriction: This topic applies to Windows environments only.

A column can contain any of the data types discussed in this topic. The following table lists the limits (minimum and maximum values) for each data type in XDB mode. The limits of XDB Server and DB2 data types are identical, except in the cases of float and char types. (See the footnotes in the table). The system rejects, or truncates (depending on the data type) values that fail to satisfy the rules for a data type.

Type | Minimum | Maximum | Storage
Smallint | -32,768 | 32,767 | 2 bytes
Int[eger] | -2,147,483,648 | 2,147,483,647 | 4 bytes
float (single) (See note 1.) | 1.2E-38 | 3.4E+38 | 4 bytes
float (double) (See note 1.) | 2.2E-308 | 1.8E+308 | 8 bytes
Dec[imal] | 1-10E+31 | 10E+31 | (precision/2)+1
Money | -10E+12 | 10E+12 | 8 bytes
DATE | 1/1/0001 | 12/31/9999 | 6 bytes
TIME | 00:00:01 | 24:00:00 | 6 bytes
Timestamp | 0001-1-01- 00.00.000000 | 9999-12-31- 24.00.000000 | 12 bytes
Char(See note 2.) | 1 byte | 254/4056 bytes (See note 3.) | n bytes
varchar (See note 2.) | 1 byte | 32706 | >= n bytes
long varchar (See note 2.) | 1 byte | 32706 | <= n bytes
Graphic | 2 bytes | 127 bytes | <= n bytes
Vargraphic | 2 bytes | 16353 | <= n bytes
Long Vargraphic | 2 bytes | 16353 | <= n bytes
BLOB(See note 4.) | zero bytes | 2 GB | separate file

Table Notes:

  1. The DB2 limits are 5.4E-79 to 7.2E+75 and 5.4E-79 to 7.2E+75 for single and double precision floating point values respectively.
  2. Can be defined as FOR BIT DATA, which means the column's fields contain a stream of bits that are not to be interpreted as ASCII (or EBCDIC) character codes.
  3. Character fields can store up to 4056 bytes in XDB mode, but only 254 bytes in DB2 mode.
  4. Includes image, binary, varbinary, and long varbinary data types.

More:

  • Smallint
  • Int[eger]
  • Float
  • Dec[imal]
  • Money
  • Date
  • Time
  • Timestamp
  • Char
  • Varchar
  • Long Varchar
  • Graphic
  • Vargraphic
  • Long Vargraphic
  • BLOB
  • Smallint
  • Int[eger]
  • Float
  • Dec[imal]
  • Money
  • Date
  • Time
  • Timestamp
  • Char
  • Varchar
  • Long Varchar
  • Graphic
  • Vargraphic
  • Long Vargraphic
  • BLOB
Parent topic: Overview


Smallint

Restriction: This topic applies to Windows environments only.

This data type defines a field that holds whole numbers between -32,768 and 32,767. Smallint fields require 2 bytes of storage. Fractional values inserted into a small integer field are truncated. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Int[eger]

Restriction: This topic applies to Windows environments only.

Defines a field containing a whole number between -2,147,483,648 and 2,147,483,647. Fractional values inserted into an integer field are truncated. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Float

Restriction: This topic applies to Windows environments only.

FLOAT [(integer)]

This data type defines an IEEE standard 754 floating-point field. Floating-point fields can be defined as single or double (default) precision based on the value of integer. If the value of integer is between 1 and 21, the type is single precision floating-point, which requires 4 bytes of storage. If the value of integer is between 22 and 53 inclusive, the type is double precision floating-point, which requires 8 bytes of storage. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Dec[imal]

Restriction: This topic applies to Windows environments only.

DEC[IMAL][(precision[,scale])]

This type of field holds fixed decimal point numbers between approximately 1-10E+31 and 10E+31. Precision is the total allowed number of digits including decimal places. The maximum precision is 31. The default precision is 5. Scale is the number of fractional digits (or decimal places.) The default scale is 0. Scale cannot be greater than precision. If only one parameter is given, it is treated as precision, and the default scale 0 is used. To estimate the storage requirement for decimal fields, round up the result of precision divided by two. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Money

Restriction: This topic applies to Windows environments only.

This data type contains a dollar amount between -10E+12 and 10E+12. Money fields are stored as decimal (15,2) fields, and are displayed in a user-defined format. To specify special money formats (for example, foreign currencies), see the Options User's Guide (applies to Windows environments only). If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by zero.

Parent topic: Data Types


Date

Restriction: This topic applies to Windows environments only.

Dates designate a point in time according to the Gregorian calendar. Historical dates may not follow this calendar. Arithmetic may be performed on dates within the range shown in the table under Data Types. The standard input format for this data type is mm/dd/yy or mm/dd/yyyy (automatic conversion is performed between these two formats). Character representations of other date formats shown in the following table are permitted in SQL commands. When included in SQL commands, these special date formats must be enclosed in quotes.

When the XDB Server encounters a string in a location where it expects a date, it determines which of the formats is being used, and performs the internal conversion required. For more information on date formats, see the Windows Options User's Guide. Dates are stored as three 2-byte integers. If the field is specified as NOT NULL WITH DEFAULT, null values will be replaced by current date.

Format | Name | Date Format | Example
ISO | International Standards Organization | yyyy-mm-dd | 1992-03-20
USA | IBM USA Standard | mm/dd/yyyy | 03/20/1992
EUR | IBM European Standard | dd.mm.yyyy | 20.03.1992
JIS | Japanese Industrial Standard Christian Era | yyyy-mm-dd | 1992-03-20
LOCAL | Installation-defined | any defined format |
Parent topic: Data Types


Time

Restriction: This topic applies to Windows environments only.

The time field data type is defined by the standard input format of hh:mm:ss, using a 24-hour clock. Character representations of other time formats shown in the following table are permitted in SQL commands. Note that when included in SQL commands, these special time formats must be enclosed in quotes. When the XDB Server encounters a string in a location where it expects a time, it determines which of the formats is being used, and performs the internal conversion required. Time requires 3 bytes of storage. If a time field is specified as NOT NULL WITH DEFAULT, null values will be replaced by the current time.

Format | Name | Date Format | Example
ISO | International Standards Organization | hh.mm.ss | 14:30:05
USA | IBM USA Standard | hh:mm AM or PM | 2:30 PM
EUR | IBM European Standard | hh.mm.ss | 14.30.05
JIS | Japanese Industrial Standard Christian Era | hh.mm.ss | 14.30.05
LOCAL | Installation-defined | Any defined format |
Parent topic: Data Types


Timestamp

Restriction: This topic applies to Windows environments only.

This combination date and time data type is displayed in the format yyyy-mm-dd-hh.mm.ss.nnnnnn. The following table describes the various components of this field. As an example, the timestamp for 7:45:34pm on June 18, 1992 would be 1992-06-18-19.45.34.000000. When including a timestamp value in an SQL command, enclose it in quotes. Timestamp requires 12 bytes of storage. If the column is specified as NOT NULL WITH DEFAULT, null values will be replaced by the current timestamp.

Format | Description
YYYY | An integer from 0001 to 9999, representing a year.
MM | An integer from 1 to 12 representing a month.
DD | An integer from 1 to 31 (maximum depends on the month and year) representing the day of the month.
hh | An integer from 0 to 24, representing the hour.
mm | An integer from 0 to 59, representing minutes.
ss | An integer from 0 to 59 representing seconds (default 0).
nnnnnn | An integer (up to 6 digits) representing microseconds. If any trailing digit is omitted, 0 is assumed.
Parent topic: Data Types


Char

Restriction: This topic applies to Windows environments only.

CHAR (field-length)

A data type containing a fixed length alphanumeric string with a maximum length of field-length characters. The field-length must be a positive number not exceeding 4056 in XDB mode (254 in DB2 mode). This data type can be defined as FOR BIT DATA. If the column is specified as NOT NULL WITH DEFAULT, null values will be replaced by spaces.

Parent topic: Data Types


Varchar

Restriction: This topic applies to Windows environments only.

VARCHAR (field-length)

This data type consists of variable length alphanumeric string values with a maximum length of field-length characters. field-length must be a positive number not exceeding 32,706. See the CREATE TABLE command for more information on determining lengths of VARCHAR and LONG VARCHAR variables. Can be defined as FOR BIT DATA. If the column is specified as NOT NULL WITH DEFAULT, null values will be replaced by spaces.

Note: Currently all varchar and vargraphic fields are stored as fixed length fields. In future releases the storage required for these field types will vary according to the data to be stored.
Parent topic: Data Types


Long Varchar

Restriction: This topic applies to Windows environments only.

A data type containing variable length alphanumeric strings (maximum length of 32,706 characters). See the CREATE TABLE command for more information on determining lengths of LONG VARCHAR and VARCHAR variables. The storage required depends on the actual length of the value stored. Can be defined as FOR BIT DATA. If the field is specified as NOT NULL WITH DEFAULT, null values are replaced by spaces.

Parent topic: Data Types


Graphic

Restriction: This topic applies to Windows environments only.

GRAPHIC (field-length)

Fields of this data type contain fixed length strings (field-length characters long), intended for storing double byte data. The field-length must be a positive number not exceeding 127.

Parent topic: Data Types


Vargraphic

Restriction: This topic applies to Windows environments only.

VARGRAPHIC (field-length)

This data type holds variable length strings (maximum length of 2028 characters), intended for storing double byte data. The amount of storage required depends on the actual length of the value stored.

Parent topic: Data Types


Long Vargraphic

Restriction: This topic applies to Windows environments only.

This data type contains variable length strings (maximum length of 2028 characters), intended for storing double byte data. The amount of storage required depends on the actual length of the value stored.

Parent topic: Data Types


BLOB

Restriction: This topic applies to Windows environments only.

BLOB is a generic term describing any arbitrarily sized block of data. This data type can also be referred to as image, binary or bitdata. A BLOB can be created using one of four syntaxes -- all of which are functionally equivalent. Various syntaxes are provided for compatibility with industry standards and different vendors. The available BLOB data type syntaxes are:

  • image[BLOCK SIZE n]
  • binary(x)
  • varbinary(x)
  • long varbinary

where n is the size of the block used for storage. The x parameter for the binary, varbinary and long varbinary syntaxes is not currently used. The minimum size of a BLOB data type is zero bytes. BLOB data types do not have NULLs. Since BLOB fields can not be used in WHERE clauses or aggregate functions, there is no need for NULLs. However, any BLOB can have a length of zero, which can only be determined by using an API call from a host application.

The BLOB data type allows you to save and manage binary disk files, such as image and sound files. Unlike char, int, and decimal, which have defined purposes and semantics, BLOB data is considered to be "unstructured" and "anonymous" and is not interpreted in any way by the database. Apart from certain limitations, BLOB fields can be accessed and manipulated like any other column in a table.

Tables can have more than one BLOB field; and tables with BLOB fields can be joined in any fashion. There is no maximum size for a BLOB data type. Data stored as a BLOB data type is not stored in the XDB Server table (.TAB) file as other data types are. Instead, each BLOB field is stored as a separate file in the same storage group as the XDB Server table file. Each BLOB file name has the same root file name as the .TAB file.

Each BLOB field in a table is stored in a separate file. The files are partitioned into blocks, and each BLOB record is stored as a linked-list of blocks. The default block size is 2K, and can be set (using the BLOCK SIZE clause) to any value between 64 bytes and 32K during table creation. A free list of blocks is maintained and blocks are reused.

Note:

BLOB data types are not supported with the DOS single-user engine.

Parent topic: Data Types


Other Data Types

Restriction: This topic applies to Windows environments only.

For ANSI compatibility, the XDB Server allows you to issue commands to create or alter tables using the following data types. These data types are converted to appropriate XDB Server data types, as shown.

More:

  • Double Precision
  • Numeric
  • Real
  • Double Precision
  • Numeric
  • Real
Parent topic: Overview


Double Precision

Restriction: This topic applies to Windows environments only.

When creating or altering a column as a DOUBLE or DOUBLE PRECISION data type, the column is created as (or modified to) a double precision FLOAT type.

Parent topic: Other Data Types


Numeric

Restriction: This topic applies to Windows environments only.

NUMERIC[(precision[, scale])]

If the data type NUMERIC is used when creating or altering a table, the column is created as (or modified to) a data type DECIMAL, with the specified precision and scale.

Parent topic: Other Data Types


Real

Restriction: This topic applies to Windows environments only.

When creating or altering a column as a REAL data type, the column is created as (or modified to) a single precision FLOAT type.

Parent topic: Other Data Types


Assignment And Comparison

Restriction: This topic applies to Windows environments only.

When running against an XDB Server, character strings, dates, times and numbers are not compatible. That is, one type of value cannot always be compared or assigned to an object of another type. NULL values can be assigned to any type of column, except those defined as NOT NULL.

More:

  • Assignment
  • Comparison
  • Assignment
  • Comparison
Parent topic: Overview


Assignment

Restriction: This topic applies to Windows environments only.

If an attempt is made to assign a numeric value to a column not large enough to hold it, the fractional part may be truncated. If the integer portion cannot be assigned to a column, an error message is displayed. If an attempt is made to assign a character string to a target field that is too short, the value will be truncated on the right.

Parent topic: Assignment And Comparison


Comparison

Restriction: This topic applies to Windows environments only.

Numeric values are compared according to their algebraic values. Character strings are compared by comparing the two strings according to the sort sequence specified for the location, beginning with the leftmost characters. For more information on specifying a sort sequence, see the Options User's Guide and the SQLWizard User's Guide. The default sort sequence is a modified ASCII sequence that does not distinguish between upper and lower case letters.

Parent topic: Assignment And Comparison


Constants

Restriction: This topic applies to Windows environments only.

Constants are specific values. Constants may be classified as character string, date, time, timestamp or numeric constants. Character string constants appear inside quotes (single or double) in SQL commands. Numeric constants are subdivided into integer (including both integer and smallint), float, and money constants, according to the data type into which they fall. In SQL commands, date constants should be in the form mm/dd/yy or mm/dd/yyyy (the slash ( / ) is not interpreted as a division operator if the value is determined to be a date). If another date format is used, the date string must be enclosed in quotes. In SQL commands, time constants should be of the format hh:mm:ss. If another time format is used, the date string must be enclosed in quotes. Timestamp constants should be in the format yyyy-mm-dd-hh.mm.ss.nnnnnn.

Parent topic: Overview


Special Registers

Restriction: This topic applies to Windows environments only.

The XDB Server supports a set of special keywords that refer to the contents of system variables, which can be referenced in SQL commands.

More:

  • BOTTOM
  • CURRENT DATE
  • CURRENT DEGREE
  • CURRENT PACKAGESET
  • CURRENT RULES
  • CURRENT SERVER
  • CURRENT SQLID
  • CURRENT TIME
  • CURRENT TIMESTAMP
  • CURRENT TIMEZONE
  • LEVEL
  • NULL
  • ROWID
  • BOTTOM
  • CURRENT DATE
  • CURRENT DEGREE
  • CURRENT PACKAGESET
  • CURRENT RULES
  • CURRENT SERVER
  • CURRENT SQLID
  • CURRENT TIME
  • CURRENT TIMESTAMP
  • CURRENT TIMEZONE
  • LEVEL
  • NULL
  • ROWID
Parent topic: Overview


BOTTOM

Restriction: This topic applies to Windows environments only.

Lowest recursion level (used with PREVIOUS function). The Data type is smallint.

Parent topic: Special Registers


CURRENT DATE

Restriction: This topic applies to Windows environments only.

Today's date, read from system clock. (Also TODAY in XDB mode.) The data type is date. XDB Server also recognizes CURRENT_DATE as a synonym for the CURRENT DATE special register.

Parent topic: Special Registers


CURRENT DEGREE

Restriction: This topic applies to Windows environments only.

This special register is supported functionally in that it returns the default value or a value specified with the SET CURRENT DEGREE command. This value does not actually reflect the "degree of parallelism."

Parent topic: Special Registers


CURRENT PACKAGESET

Restriction: This topic applies to Windows environments only.

This special register is syntactically supported by the XDB Server for the SET CURRENT PACKAGESET command and the SET Host Variable command. On mainframe DB2 systems, CURRENT PACKAGESET is used to specify the Collection ID of a package that will be used to execute subsequent SQL statements. The data type is CHAR(18) and is padded with blanks to fill out the field. The initial value is blanks.

Parent topic: Special Registers


CURRENT RULES

Restriction: This topic applies to Windows environments only.

The new special register CURRENT RULES allows you to specify the SQL rules that apply to the execution of SQL statements. The value in CURRENT RULES also effects the enforcement of table check constraints. See the SET CURRENT RULES statement for further information.

Parent topic: Special Registers


CURRENT SERVER

Restriction: This topic applies to Windows environments only.

This special register is similar to the CURRENT SERVER in DB2. The Current Server special register identifies the DBMS to which your application is actively connected.

When running against an XDB Server, this is the name of the current location to which you are connected.

Parent topic: Special Registers


CURRENT SQLID

Restriction: This topic applies to Windows environments only.

The CURRENT SQLID is initially the same as USER. The value changes to reflect execution of a SET CURRENT SQLID command. The data type is char(8). CURRENT SQLID can also be influenced by security exits and SecondaryID specifications.

Parent topic: Special Registers


CURRENT TIME

Restriction: This topic applies to Windows environments only.

The CURRENT TIME register value is read from the system clock. The data type is time. (Also XTIME in XDB mode.) The XDB Server also recognizes CURRENT_TIME as a synonym for the CURRENT TIME special register.

Parent topic: Special Registers


CURRENT TIMESTAMP

Restriction: This topic applies to Windows environments only.

The CURRENT TIMESTAMP register value consists of the current date and time, both of which are read from the system clock. The data type is timestamp. The XDB Server also recognizes CURRENT_TIMESTAMP as a synonym for the CURRENT TIMESTAMP special register.

Parent topic: Special Registers


CURRENT TIMEZONE

Restriction: This topic applies to Windows environments only.

A time duration between -24 and 24 hours representing difference in hours between local time and Greenwich Mean Time (GMT). The data type is decimal(6,0). The default returned by CURRENT TIMEZONE is 0.

Parent topic: Special Registers


LEVEL

Restriction: This topic applies to Windows environments only.

Recursion level (number of times the PREVIOUS function's recursion algorithm is applied). The data type is smallint.

Parent topic: Special Registers


NULL

Restriction: This topic applies to Windows environments only.

Absence of a value. NULL can be used for any data type.

Parent topic: Special Registers


ROWID

Restriction: This topic applies to Windows environments only.

DB2 mode only. Data type is integer. Contains the physical row number of the current record. The XDB Server reports this value when a referential integrity error occurs or when a duplicate value is detected in a unique index. You can use ROWID anywhere an expression can be used. For example:

SELECT * FROM CUSTOMER WHERE ROWID = 22;

gets the record in physical row 22. And,

SELECT ROWID,NAME,ADDRESS, FROM CUSTOMER;

gets the row numbers along with other fields in the CUSTOMER table.

When ROWID is used with a join, it represents the row number of the first table in the join.

Parent topic: Special Registers


Labeled Duration

Restriction: This topic applies to Windows environments only.

The following table contains keywords known as labeled durations. Each labeled duration keyword corresponds to a specific time unit, interpreted as it normally would be against a calendar or clock. A labeled duration can only be used in an arithmetic expression having date, time or timestamp expressions (or columns) as one of the operands. The expression must resolve to the proper data type. For example, DATE("1993-12-12") + DAY is a valid expression, as is BIRTHDATE + 15 YEARS + 8 MONTHS.

The expression BIRTHDATE + (15 YEARS + 8 MONTHS), on the other hand, cannot be resolved because the system would attempt to add the expression in parentheses first, which contains no date or time operand.

A labeled duration is converted into a decimal (15,0) number before it is applied. If present, decimal places are truncated. All of the keywords listed in the following table can also be used in singular form as labeled durations (for example, YEAR is the same as YEARS, MONTH is the same as MONTHS, etc.)

Duration | Example
YEARS | goldenanniv = weddingdate + 50 years
MONTHS | eligibledate = hiredate + 6 months
DAYS | nextcall = current date + 14 days
HOURS | endshift = beginshift + 8 hours
MINUTES | sampletime = current time + 10 minutes
SECONDS | eta = depart + second(travel) seconds
MICROSECONDS | adjustedtime=recordedtime - 200 microseconds
Parent topic: Overview


SQL Commands

Restriction: This topic applies to Windows environments only.
  • SQL Command Category Overview
  • Data Definition Language (DDL)
  • Data Manipulation Language (DML)
  • Data Control Language (DCL)
  • Utility Commands
  • Embedded and Dynamic SQL
Parent topic: SQL Reference


SQL Command Category Overview

Restriction: This topic applies to Windows environments only.

Standard SQL statements supported by the XDB Server can be divided into three functional command categories:

  • Data Definition Language (DDL) statements create, alter and drop relational database objects such as databases, tables and indexes.
  • Data Manipulation Language (DML) statements select, update, insert, and delete data values within relational database tables.
  • Data Control Language (DCL) statements establish system security by controlling access to data objects, plus regulating concurrency and transaction processing.

In addition, there are utility commands (that perform administrative functions on the XDB Server) and embedded and dynamic SQL commands.

Parent topic: SQL Commands


Data Definition Language (DDL)

Restriction: This topic applies to Windows environments only.

Data Definition Language (or DDL) includes those SQL statements that create and drop locations, databases and database objects such as tables and indexes. DDL also includes statements to alter database objects and impose integrity constraints on tables. All DDL statements automatically update the appropriate system catalog tables.

  • ALTER DATABASE

    Changes information parameters for a database under the currently set XDB Server location.

  • ALTER INDEX

    Changes the configuration of an existing index (DB2). This command is supported syntactically by the XDB Server to maintain compatibility with DB2.

  • ALTER LOCATION

    Converts a location to DB2 Version 4 or DB2 Version 5 compatibility.

  • ALTER SEQUENCE

    Changes the attributes of a sequence at the current server.

  • ALTER STOGROUP

    Changes the specifications of an existing storage group (stogroup) defined within the current XDB Server location.

  • ALTER TABLE

    Adds, removes or renames table columns, or changes the data types of columns. In XDB mode, the ALTER TABLE command can create or drop UNIQUE, PRIMARY, FOREIGN KEY and CHECK constraints used to enforce referential and domain integrity, plus uniqueness (the DB2-specific syntax of the ALTER TABLE statement is supported in DB2 mode).

  • ALTER TABLESPACE

    Changes the specifications of a table space within the currently set XDB Server location.

  • ALTER VIEW

    Regenerates a view using an existing view definition at the current server.

  • COMMENT ON

    Places a remark about an object in the catalog tables at the currently set location.

  • CREATE ALIAS

    The CREATE ALIAS command defines an alias for an existing table or view, and records the alias definition in the catalog tables at the currently set location. It is not required that the table or view be described under the same location as the alias.

  • CREATE DATABASE

    Defines a logical database, which under default operating conditions consists of a subdirectory of the same name, under the active location root directory. The database directory, normally under the location root directory, holds the physical table and index files that are logically associated with the database. By using stogroups (described in the Server Administration Guide), users have the option of implicitly specifying different storage directories for individual database objects (or groups of objects).

  • CREATE GLOBAL TEMPORARY TABLE

    Creates a description of a temporary table at the current server.

  • CREATE INDEX

    Creates an index on one or more columns of a table. Indexes speed data retrieval and can enforce uniqueness constraints.

  • CREATE LOCATION

    Creates a new XDB Server location in a subdirectory path specified by the user. A location on an XDB Server is similar to a DB2 subsystem. In addition to a SYSTEM location (used for overall system administration and security), the XDB Server allows additional user-defined locations to be created.

  • CREATE SEQUENCE

    Creates a sequence at the application server.

  • CREATE STOGROUP

    Creates a DB2 style storage group (stogroup) that can be associated with a directory path. Stogroups are used to define a physical directory area for storing database objects.

  • CREATE SYNONYM

    Creates an alternate name for a table or view within the currently set location.

  • CREATE TABLE

    Creates a table by defining all columns in the table, including the data type and field length of each column. Primary and Foreign keys for the table also can be created using this command.

  • CREATE TABLESPACE

    Creates a DB2 style table space that can be used with a stogroup to store tables from the same logical database in different directory paths.

  • CREATE VIEW

    Defines a virtual table that usually restricts data retrieval and updating to a subset of columns and rows from one or more base tables.

  • DROP ALIAS

    Deletes an alternate name for a table or view from the location's system catalog.

  • DROP DATABASE

    Deletes a database defined within the current location. Also deletes all objects logically associated with the database, and then deletes the database subdirectory. If the database subdirectory is empty (with no objects logically associated with that database), then this command removes the empty subdirectory.

  • DROP INDEX

    Deletes an index existing at the current location. Note that an index created as the result of a UNIQUE, PRIMARY or FOREIGN KEY constraint can only be dropped by first dropping the existing constraint with the ALTER command.

  • DROP LOCATION

    Removes a user-defined XDB Server location, along with accompanying catalog tables and directory structure. Also deletes all objects associated with the location.

  • DROP STOGROUP

    Deletes a stogroup defined within the currently set location. This action severs the logical connection between any data objects that were defined using the stogroup, and the directory path specified in the deleted stogroup definition (does not delete objects associated with the stogroup) -- USE WITH CAUTION.

  • DROP SYNONYM

    Deletes an alternate name for a table or view from the location's system catalog.

  • DROP TABLE

    Deletes a table created under the current location, along with all associated indexes, views and synonyms built on that table.

  • DROP TABLESPACE

    Deletes a table space defined within the current location, along with all tables logically associated within that table space.

  • DROP VIEW

    Deletes a view from the system catalog of the current location. In addition, all other views defined on the dropped view are dropped also.

  • LABEL ON

    Replaces or adds descriptive text labels to the catalog tables of the currently set location. These text labels describe tables, views, aliases, or columns existing at the current location.

  • RENAME

    Changes a table name.

Parent topic: SQL Commands


Data Manipulation Language (DML)

Restriction: This topic applies to Windows environments only.

Data Manipulation Language (or DML) consists of SQL statements used to retrieve, insert, update and delete records from database tables. DML statements are the only statements that can be rolled back or recovered.

  • DELETE

    Deletes specified rows from a table. Also has a special format (DELETE WHERE CURRENT OF) for embedded SQL.

  • INSERT

    Inserts a specified number of rows into a table.

  • SELECT

    Retrieves data from one or more tables. Also has a special format (SELECT INTO) for embedded SQL.

  • UPDATE

    Modifies data in specified rows of a table. Also has a special format (UPDATE WHERE CURRENT OF) for embedded SQL.

Parent topic: SQL Commands


Data Control Language (DCL)

Restriction: This topic applies to Windows environments only.

Data Control Language (or DCL) consists of statements that control security and concurrent access to table data.

  • COMMIT

    Instructs the XDB Server to make permanent all data changes resulting from DML statements executed by a transaction.

  • CONNECT

    Connects the application process (or user) to a designated XDB Server or DB2 location. This location becomes the current location for the application process or user.

  • GRANT (Database Privileges)

    Assigns access privileges to XDB Server users or applications.

  • GRANT (Sequence Privileges)

    Grants privileges on a user-defined sequence.

  • LOCK TABLE

    Extends XDB Server's automatic record and table level locking functions (in a multi-user system) by acquiring explicit locks on a particular table.

  • REVOKE (Database Privileges)

    Cancels access privileges for XDB Server users or applications.

  • REVOKE (Sequence Privileges)

    Revokes the privileges on a user-defined sequence.

  • ROLLBACK

    Instructs the XDB Server to reverse the effect of any DML commands executed on a database by a transaction. Information recorded in a backward log is used to restore the database to a state existing before the transaction.

  • UNLOCK TABLE

    Removes table locks (in a multi-user system) acquired with the LOCK TABLE command.

Parent topic: SQL Commands


Utility Commands

Restriction: This topic applies to Windows environments only.

Utility commands perform administrative functions on the XDB Server.

  • ALTER PASSWORD

    Enables you to change passwords.

  • BACKUP LOCATION

    Makes a backup copy of an entire XDB Server location to a specified directory path.

  • BULK [ON | OFF]

    BULK ON turns the Bulk Upload feature on for all subsequent transactions. Bulk uploading allows data to be transferred to the client in bulk, instead of one row at a time (used with XDB Link). BULK OFF turns the Bulk Upload feature off.

  • CHECKPOINT

    Flushes the entire logging system cache buffer to disk and flushes database cache buffer.

  • COMPACT

    Recycles unused disk space by packing tables, rebuilding indexes and reorganizing directory files.

  • CREATE USER

    Creates additional XDB user accounts.

  • DISABLE LOGIN

    Prevents additional users from logging on to the server.

  • ENABLE LOGIN

    Permits users to log on to the server again after a DISABLE LOGIN command has been issued.

  • EXPLAIN

    Acquires access path selection information about an "explainable" SQL statement, and inserts the information into a special table (automatically created by the XDB Server) named PLAN_TABLE. Users have the option of creating their own plan_table structure.

  • HALT QUERY FROM

    Terminates a specific query.

  • REFRESH LOCATIONS

    Directs the XDB Server to re-read the information contained in the SYSIBM.SYSLOCATIONS catalog table. REFRESH LOCATIONS is typically issued after information in this table has been manually updated by the user.

  • REFRESH TABLE

    Refreshes the data in a materialized query table.

  • ROLLFORWARD

    Applies all DML changes recorded in a forward log file to a location backup copy. The ROLLFORWARD command restores the information in a location to the condition existing before the last location backup.

  • SET AUTOCOMMIT

    Sets the autocommit feature on or off. Setting autocommit to "on" causes a commit to be automatically generated after any DML command.

  • SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION

    Changes the value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register.

  • SET CURRENT PACKAGE PATH

    Assigns a value to the CURRENT PACKAGE PATH special register.

  • SET CURRENT PACKAGESET

    Assigns a value to the CURRENT PACKAGESET special register.

    Note: This command is supported only syntactically by the XDB Server, where packages are bound with a particular qualifier.
  • SET CURRENT REFRESH AGE

    Changes the value of the CURRENT REFRESH AGE special register.

  • SET CURRENT RULES

    Assigns a value to the CURRENT RULES special register.

  • SET CURRENT SQLID

    Changes the AuthID value stored in the CURRENT SQLID special register.

  • SET ISOLATION

    Defines the isolation level used to determine appropriate lock acquiring and lock releasing procedures for an executing transaction.

  • SET LOCATION location-name OFFLINE/ONLINE

    Lets the system administrator prevent or permit access to a specific location.

  • SET LOCATION TO

    Logs a user onto a new location, creating an implied connection between the user's current session and the specified location. The value of the CURRENT LOCATION special register is temporarily updated to reflect the new active location. The user's default location is not changed.

  • SET LOG

    Allows database administrators (with SYSADM authority or higher) to suspend logging system operation during an administrative session, and change the path where location log files are stored.

  • SET SCHEMA

    Assigns a value to the CURRENT SCHEMA special register.

  • SET SORTSPACE

    Changes the size of the sort space while the XDB Server is running.

  • SHUTDOWN

    Stops an XDB Server from a remote client.

  • START DATABASE

    Allows users to have access to the contents of the named database.

  • STOP DATABASE

    Restricts all access to the named database.

  • TRUNCATE TABLE

    Deletes records from a table much like the DELETE command, but proceeds much faster since the deleted data is not logged.

Parent topic: SQL Commands


Embedded and Dynamic SQL

Restriction: This topic applies to Windows environments only.

XDB Server statements that are used in embedded and dynamic SQL programming are summarized below. While most SQL commands can be embedded in host programming languages (for example, COBOL, C and PL/I), the following commands can only appear as embedded or dynamic SQL statements.

  • ALLOCATE CURSOR

    Defines a cursor and associates it with a result set locator variable.

  • ASSOCIATE LOCATORS

    Gets the result set locator value for each result set returned by a stored procedure.

  • BEGIN DECLARE SECTION

    Marks the beginning of declarations for host variables to be used by SQL commands (optional in COBOL).

  • CALL

    Runs stored procedures on the mainframe (through XDB Link), or procedures on an XDB Server, from an application.

  • CLOSE

    Closes a previously opened cursor (OPEN command).

  • DECLARE CURSOR

    Defines a cursor.

  • DECLARE STATEMENT

    Identifies prepared SQL statements for later use in application programs.

  • DECLARE TABLE

    Provides the precompiler with information for checking embedded SQL statements. DECLARE TABLE is also used for application program documentation.

  • DESCRIBE

    Obtains information about either a prepared statement (PREPARE command), or an existing table or view.

  • DESCRIBE CURSOR

    Obtains information about the result set that is associated with the cursor and places the information into a descriptor.

  • DESCRIBE PROCEDURE

    Obtains information about the result sets returned by a stored procedure, and places the information into a descriptor.

  • END DECLARE SECTION

    Marks the end of declarations for host variables to be used by SQL commands (required if BEGIN DECLARE SECTION statement is used).

  • EXECUTE

    Executes a prepared (PREPARE command) SQL statement.

  • EXECUTE IMMEDIATE

    Prepares (PREPARE command) and executes (EXECUTE command) an SQL statement in one step.

  • FETCH

    Positions a cursor on the next row of a result, and assigns the values of that row to host program variables.

  • GET DIAGNOSTICS

    Provides diagnostic information about the last SQL statement (other than a GET DIAGNOSTICS statement) that was executed.

  • INCLUDE

    Inserts declarations or code into a source program for use by SQL, as well as the host language.

  • OPEN

    Opens a previously prepared (PREPARE command) cursor prior to fetching (FETCH command) result rows.

  • PREPARE

    Prepares an SQL statement for execution.

  • SELECT INTO

    Retrieves one row of values from a table or view, and then assigns these values to one or more host variables specified in the SELECT INTO command statement.

  • SET Host Variable

    Assigns special register values to host variables.

  • WHENEVER

    Specifies the host language statement to be executed whenever a specified exception condition takes place.

Parent topic: SQL Commands


Syntax Notation

Restriction: This topic applies to Windows environments only.

The SQL statement syntax in this reference shows all the clauses, object types and predicates that can be incorporated into a particular statement. The following standard notation conventions are used in the statement syntax:

  • Italics are used to distinguish general parameter information and data object categories in a statement syntax. The clause "PASSWORD password," for example, contains the keyword PASSWORD, and the parameter password (indicating that the user should supply a password).
  • Square brackets ( [ ] ) enclose optional items in a command statement. Do not type the brackets. For example, the statement "COMMIT [WORK]" indicates that the keyword COMMIT must be used, but the keyword WORK is optional.
  • Ellipses ( ... ) indicate that the preceding item may be repeated one or more times. Do not type the ellipses.
  • Ellipses are sometimes preceded with a comma ( ,... ) indicating that the preceding item may be repeated one or more times, with each repeated item separated from the last by a comma. For example, the clause "column-name [,...]" indicates that at least one column name must be specified, with an option to add any number of other column names (with each column name separated from the last by a comma).
  • Vertical bars ( | ) indicate that whatever item precedes the bar can be replaced by the item following the bar. This character operates as an OR conjunction, offering a choice between the item appearing before and after. Do not type the vertical bar.
  • Braces ( { } ) group items to be selected as a single element of the command statement. One item within the braces must be chosen. For example, "{A | B}" means choose either A or B. Do not type the braces.
  • Parentheses appearing within the statement syntax are part of the statement syntax and need to be typed as shown.
  • Underlined items indicate a default option. For example, "PRIQTY {3 | integer}" indicates that the PRIQTY clause has a default value of three. The statement "SELECT [ALL | DISTINCT]" indicates that SELECT (by itself) is interpreted the same as SELECT ALL.

More:

  • Syntax Support Only
  • Case Sensitivity
  • Comments
  • Line Continuation
  • Syntax Support Only
  • Case Sensitivity
  • Comments
  • Line Continuation
Parent topic: SQL Reference


Syntax Support Only

Restriction: This topic applies to Windows environments only.

A DB2-mainframe statement that has no functional equivalent on the XDB Server. It is fully supported only when running against a DB2-mainframe location using XDB Link. If running against an XDB Server location, only the syntax of these clauses is checked. An error message is returned to the user if a spelling or syntax error is found. Refer to the appropriate DB2 documentation for full explanations of these commands.

Parent topic: Syntax Notation


Case Sensitivity

Restriction: This topic applies to Windows environments only.

To enhance readability in this reference, command keywords always appear in capital letters. For actual database operations, however, XDB Server keywords are not case sensitive and may be entered in either all upper case, all lower case, or any combination of upper and lower case letters.

The character sort sequence for each XDB Server location defaults to case insensitive -- which can be changed to standard ASCII, standard EBCDIC or a user defined sorting scheme. XDB Server Administrators can change the sort sequence for an XDB Server location. Users can choose to use the default location sort or specify their own sort through client configuration, described in your client tools documentation.

Parent topic: Syntax Notation


Comments

Restriction: This topic applies to Windows environments only.

The XDB Server receives and processes SQL commands as continuous, nondelimited strings. Comments can be included anywhere in an SQL command, provided they are bracketed by the characters /* and */. The XDB Server ignores all characters enclosed between these special characters. For example, the following command statement has the comment string "info on parts & suppliers" attached:

SELECT *
    FROM partsupp /* info on parts & suppliers */

An alternative means of entering comments is provided in SQLWizard, where users may place comments at the end of a statement line, separating them from the statement text by a double hyphen (--). Anything on the line after the double hyphen is ignored by the system.

Parent topic: Syntax Notation


Line Continuation

Restriction: This topic applies to Windows environments only.

Although the XDB Server requires that an SQL commands be processed as a single string of text characters, in most XDB Server environments you can split commands over several lines without requiring special line continuation marks. A semicolon generally indicates the end of a complete command statement.

Parent topic: Syntax Notation


DB2 Support

Restriction: This topic applies to Windows environments only.

When running in DB2-mode, the XDB Server provides either full or partial DB2-mainframe support for all SQL statements and clauses. When running against a mainframe location using XDB Link, XDB Link effectively becomes the DB2 subsystem, providing complete DB2-mainframe support for all SQL statements issued by the user.

However, when running against an XDB Server location in a non-mainframe environment, some combination of the following three categories of DB2-mainframe support applies to each SQL statement and clause:

  • Functionally Supported

    These clauses actually perform some function within the XDB Server. This implementation may not exactly mirror the DB2-mainframe implementation, but is functional in some respect.

  • Syntactically Supported

    None of the information contained within these clauses has a functional purpose within the XDB Server. XDB technology does, however, check the spelling and syntax of these clauses, returning an error to the user if the syntax deviates from correct DB2-mainframe usage. It is also possible that some clause information may be recorded within XDB Server catalog tables. These clauses appear as bold text in syntax statements.

Parent topic: SQL Reference


SQL Statements

Restriction: This topic applies to Windows environments only.
  • ALLOCATE CURSOR
    The ALLOCATE CURSOR statement defines a cursor and associates it with a result set locator variable.
  • ALTER DATABASE
    The ALTER DATABASE statement changes the description of the specified database under the currently set XDB Server location.
  • ALTER FUNCTION
    The ALTER FUNCTION statement changes the description of an external scalar or external table function at the current server.
  • ALTER FUNCTION (SQL)
    The ALTER FUNCTION (SQL) statement changes the description of a user-defined SQL scalar function at the current server.
  • ALTER INDEX
    On a mainframe DB2 subsystem, this statement changes the configuration of an existing index. See the ALTER TABLE command for information on altering indexes that result from UNIQUE, PRIMARY and FOREIGN keys. In some cases, it may be necessary to drop an index and re-create it using the DROP INDEX and CREATE INDEX commands.
  • ALTER LOCATION
    The ALTER LOCATION statement converts (upgrades) a location to DB2 Version 6, 7 or 8 compatibility.
  • ALTER PASSWORD
    The ALTER PASSWORD statement enables you to change passwords.
  • ALTER PROCEDURE (external)
    The ALTER PROCEDURE statement changes the description of a stored procedure at the current server.
  • ALTER PROCEDURE (SQL)
    The XDB Server operating environment only provides syntax support for external Procedures (SQL) at this time.
  • ALTER SEQUENCE
    The ALTER SEQUENCE statement changes the attributes of a sequence at the current server. Only future values of the sequence are affected by the ALTER SEQUENCE statement.
  • ALTER STOGROUP
    The ALTER STOGROUP statement changes the specifications of an existing storage group (stogroup) defined within the current XDB Server location.
  • ALTER TABLE
    The ALTER TABLE statement changes the description of a table at the current server.
  • ALTER TABLESPACE
    The ALTER TABLESPACE statement changes the specifications of a table space within the currently set XDB Server location.
  • ALTER VIEW
    The ALTER VIEW statement regenerates a view using an existing view definition at the current server.
  • ASSOCIATE LOCATORS
    The ASSOCIATE LOCATORS statement gets the result set locator value for each result set returned by a stored procedure.
  • BACKUP LOCATION
    This XDB Server utility command copies the entire contents of an XDB Server location to the specified drive and path while the XDB Server location is still generally available.
  • BEGIN DECLARE SECTION
    The BEGIN DECLARE SECTION statement (embedded SQL only) marks the beginning of a host variable declare section in an application program.
  • BULK
    The BULK ON command activates the Bulk Upload feature which increases the efficiency of your transactions between the mainframe and XDB Link. The BULK OFF command turns off the Bulk Upload feature.
  • CALL
    The XDB Server can run a stored procedure on the mainframe (through XDB Link) or on an XDB Server through use of the CALL statement.
  • CHECKPOINT
    CHECKPOINT is an SQL command which flushes the database and log files.
  • CLOSE
    The CLOSE command (embedded SQL only) closes a cursor previously opened by a DECLARE CURSOR command. If a temporary table is created as a result of the cursor, that table is deleted when the cursor is closed.
  • COMMENT ON
    The COMMENT ON statement adds or replaces descriptive text comments for aliases, columns, distinct types (currently not supported), stored procedures, tables, triggers, user-defined functions, and views located within the current XDB Server location. All comments are stored in the catalog tables belonging to that location.
  • COMMIT
    The COMMIT statement is used to mark the end of a transaction (unit of work) and preserve all of the database changes made by the transaction.
  • COMPACT
    Use the COMPACT command to pack table, index and dictionary files in order to reuse disk storage space.
  • CONNECT
    The CONNECT statement (embedded SQL only) connects the application process to the specified XDB Server or DB2 (through XDB Link) location. This location becomes the current location for the application process.
  • CREATE ALIAS
    The CREATE ALIAS command defines an alternate name for an existing table or view, and records the alias definition in the XDB Server system catalog at the currently set location. It is not required that the table or view be in the current location.
  • CREATE AUXILIARY TABLE
    The CREATE AUXILIARY TABLE statement creates an auxiliary table at the current server for storing LOB data.
  • CREATE DATABASE
    The CREATE DATABASE command creates a logical database structure at the currently set XDB Server location.
  • CREATE DISTINCT TYPE
    The CREATE DISTINCT TYPE statement defines a distinct type, which is a data type that a user defines. A distinct type must be sourced on one of the built-in data types. Successful execution of the statement also generates:
  • CREATE FUNCTION
    The CREATE FUNCTION statement registers a user-defined function with an application server. You can register three different types of functions with this statement, each of which is described separately.
  • CREATE FUNCTION (external scalar)
    This CREATE FUNCTION statement registers a user-defined external scalar function with an application server.
  • CREATE FUNCTION (external table)
    This CREATE FUNCTION statement registers a user-defined external table function with an application server.
  • CREATE FUNCTION (sourced)
    This CREATE FUNCTION statement registers a user-defined function that is based on an existing scalar or column function with an application server.
  • CREATE FUNCTION (SQL Scalar)
    This statement is used to define a user-defined SQL scalar function. A scalar function returns a single value each time it is invoked. Specifying a function is generally valid wherever an SQL expression is valid.
  • CREATE GLOBAL TEMPORARY TABLE
    Create a temporary table to store the intermediate results of SQL transactions. The CREATE GLOBAL TEMPORARY TABLE statement creates a description of a temporary table at the current server.
  • CREATE INDEX
    Creates an index on one or more columns of a table at the current location.
  • CREATE LOCATION
    The CREATE LOCATION command allows you to define multiple XDB Server locations under the same XDB Server. Each XDB Server location contains a set of catalog tables for that location.
  • CREATE PROCEDURE
    The CREATE PROCEDURE command defines a Stored Procedure to the SQL engine. You can then embed an SQL CALL statement in a program to invoke the stored procedure.
  • CREATE PROCEDURE
    The CREATE PROCEDURE statement defines an SQL procedure at the current server and specifies the source statements for the procedure.
  • CREATE SEQUENCE
    The CREATE SEQUENCE statement creates a sequence at the application server.
  • CREATE STOGROUP
    The CREATE STOGROUP command creates an XDB Server stogroup which associates a user-specified directory path with the named stogroup. Once the SYSIBM.SYSVOLUMES catalog table has been updated to reflect this path assignment, newly created objects can be physically stored in this directory path by designating the named stogroup when creating the objects.
  • CREATE SYNONYM
    The CREATE SYNONYM command is used to define alternate names for tables or views within the currently set location.
  • CREATE TABLE
    The CREATE TABLE statement defines a table. The definition must include its name and the names and attributes of its columns. The definition can include other attributes of the table, such as its primary key and its table space.
  • CREATE TABLESPACE
    This statement defines a table space in the current location. A table space in the XDB Server system architecture is logically compatible with DB2 table spaces. However, an XDB Server table space does not physically store XDB Server table (.TAB) files. This XDB Server interpretation of table spaces differs from a DB2 subsystem, where a table space can physically store multiple tables. Refer to the appropriate DB2 documentation for details on the mainframe implementation of table spaces.
  • CREATE TRIGGER
    The CREATE TRIGGER statement defines a trigger in a schema and builds a trigger package at the current server.
  • CREATE USER
    The CREATE USER statement enables you to create additional XDB user accounts.
  • CREATE VIEW
    The CREATE VIEW command is used to define a view or virtual table that is based on one or more tables or views. The view definition is stored at the current location. While a view does not actually contain data, it provides indirect access to data contained in the tables upon which the view is based. Views may be used to define subsets of tables, or to combine data from several tables into a logical view. Views may contain expressions that are computed from other columns, including aggregate functions such as averages, totals, etc.
  • DECLARE CURSOR
    The DECLARE CURSOR command (embedded SQL only) is used to define a cursor, which is a named control structure that points to a row in a set of records defined by a query.
  • DECLARE GLOBAL TEMPORARY TABLE
    The DECLARE GLOBAL TEMPORARY TABLE statement defines a declared temporary table for the current application process and instantiates an empty instance of the table for the process.
  • DECLARE STATEMENT
    The DECLARE STATEMENT command (embedded SQL only) identifies prepared SQL statements for later use in application programs.
  • DECLARE TABLE
    The DECLARE TABLE statement (embedded SQL only) is used for application program documentation and providing the precompiler with information for checking embedded SQL statements.
  • DELETE (Positioned)
    The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).
  • DELETE (Searched)
    The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).
  • DESCRIBE
    The DESCRIBE statement (embedded SQL only) obtains information about a previously prepared (PREPARE command) SQL statement and places this information inside an SQL Descriptor Area (SQLDA). This information is needed in dynamic SQL queries that utilize a varying-list SELECT statement. A varying-list SELECT statement is a SELECT statement where the number of columns retrieved is not known before runtime. Alternatively, the DESCRIBE statement can provide information about a specified table or view.
  • DESCRIBE CURSOR
    The DESCRIBE CURSOR statement gets information about the result set that is associated with the cursor. The information, such as column information, is put into a descriptor. Use DESCRIBE CURSOR for result set cursors from stored procedures. The cursor must be defined with the ALLOCATE CURSOR statement.
  • DESCRIBE INPUT Example
  • DESCRIBE PROCEDURE
    The DESCRIBE PROCEDURE statement gets information about the result sets returned by a stored procedure. The information, such as the number of result sets, is put into a descriptor.
  • DISABLE LOGIN
    Use this command to prevent all users, except those with SYSADM privileges, from logging on to the XDB Server. This command does not affect users who are already logged on.
  • DROP
    The DROP statement removes (erases) an object from the current location. When an object is deleted, its description is also deleted from the system catalog at the current location.
  • ENABLE LOGIN
    Use this command to return a server to service after it has been taken out of service with the DISABLE LOGIN command.
  • END DECLARE SECTION
    The END DECLARE SECTION statement (embedded SQL only) marks the end of a host variable declaration block in an application program.
  • END DECLARE SECTION Example
  • EXECUTE
    The EXECUTE command (embedded SQL only) executes a previously prepared nonquery statement. To prepare and execute in one step, see the EXECUTE IMMEDIATE command.
  • EXECUTE IMMEDIATE
    The EXECUTE IMMEDIATE statement (embedded SQL only) prepares an executable statement from a character string and then immediately executes the statement.
  • EXPLAIN
    The EXPLAIN statement uses the optimizer to acquire access path selection information about SELECT, INSERT (and the searched form of UPDATE or DELETE) statements. This information is placed by the XDB Server into a table named PLAN_TABLE. The XDB Server creates this table automatically if it has not already been created by the user.
  • FETCH
    The FETCH command (embedded SQL only) positions a cursor on a row of its result table. It can return zero, one, or multiple rows and assigns the values of the rows to host variables if there is a target specification.
  • FREE LOCATOR
    The FREE LOCATOR statement removes the association between a LOB locator variable and its value.
  • GET DIAGNOSTICS
    The GET DIAGNOSTICS statement provides diagnostic information about the last SQL statement (other than a GET DIAGNOSTICS statement) that was executed. This diagnostic information is gathered as the previous SQL statement is executed. Some of the information available through the GET DIAGNOSTICS statement is also available in the SQLCA.
  • GRANT (Database Privileges)
    The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
  • GRANT (Function or Procedure Privileges)
    This form of the GRANT statement grants privileges on user-defined functions, cast functions that are generated for distinct types, and stored procedures.
  • GRANT (Table or View Privileges)
    The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
  • GRANT (Sequence Privileges)
    This form of the GRANT statement grants privileges on a user-defined sequence.
  • GRANT (System Privileges)
    The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
  • HALT QUERY FROM
    Use the HALT QUERY FROM command to terminate a running query. You can specify the query by user ID or by node name. This command is useful for canceling a query operation that is monopolizing the server computer.
  • HOLD LOCATOR
    The HOLD LOCATOR statement allows a LOB locator variable to retain its association with a value beyond a unit of work. The XDB operating environment does not support the LOB data type at this time.
  • INCLUDE
    The INCLUDE statement (embedded SQL only) inserts declarations or code into source programs from external files.
  • INSERT
    The INSERT command is an SQL command used to insert zero or more rows of data values (or records) into an existing table or view. The table or view receiving the new rows can be at the current location or any other location accessible to the XDB Server. Inserting a row into a view also inserts the row into that view's underlying table (if the view is updatable).
  • LABEL ON
    The LABEL ON statement adds or replaces descriptive text labels in the system catalog for the current location. These text labels describe tables, views, aliases, or columns existing at the current location.
  • LOCK TABLE
    The LOCK TABLE statement is used to acquire a shared or exclusive lock on a table at the current location.
  • OPEN
    The OPEN command (embedded SQL only) opens a previously declared cursor creating a result table containing row data.
  • PREPARE
    The PREPARE statement (embedded SQL only) transforms a character string form of an SQL statement into an executable form of the same statement. The resulting executable statement is known as a prepared statement, while the original character string is known as the statement string.
  • REFRESH LOCATIONS
    REFRESH LOCATIONS is an XDB Server utility command (not supported in DB2 mode) that re-reads the SYSIBM.SYSLOCATIONS catalog table and updates the system with any new location changes. The REFRESH LOCATIONS command is necessary only if a location has been manually inserted into SYSIBM.SYSLOCATIONS. If a new location is created using the CREATE LOCATION command, the system is automatically reset (and the catalog tables updated) to include the new location information.
  • REFRESH TABLE
    The REFRESH TABLE statement refreshes the data in a materialized query table. The statement deletes all rows in the materialized query table, executes the fullselect in the table definition to recalculate the data from the tables specified in the fullselect, inserts the calculated result into the materialized query table, and updates the catalog for the refresh timestamp and cardinality of the table. The table can exist at the current server or at any DB2 subsystem with which the current server can establish a connection.
  • RELEASE (connection)
    The RELEASE statement places one or more connections in the release pending state.
  • RELEASE SAVEPOINT
    The RELEASE SAVEPOINT statement releases the identified savepoint and any subsequently established savepoints within a unit of recovery.
  • RENAME
    The RENAME statement renames an existing table.
  • REVOKE (Database Privileges)
    The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
  • REVOKE (Function or Procedure Privileges)
    This form of the REVOKE statement revokes privileges on user-defined functions, cast functions that were generated for distinct types, and stored procedures.
  • REVOKE (Sequence Privileges)
    This form of the REVOKE statement revokes the privileges on a user-defined sequence.
  • REVOKE (System Privileges)
    The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
  • REVOKE (Table or View Privileges)
    The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
  • ROLLBACK
    ROLLBACK is used to mark the end of a transaction and back out of all changes made by the transaction at the current location. The XDB Server does not rollback data definition language (DDL) commands such as CREATE, DROP, ALTER; data control language (DCL) commands such as GRANT, and REVOKE; or utility commands such as SET and COPY. When working in a production environment, it is recommended that you backup your location before and after such commands.
  • ROLLFORWARD
    ROLLFORWARD allows users to roll forward the transactions stored in supplied log files to a specified location. This command must be run while in exclusive use mode.
  • SAVEPOINT
    The SAVEPOINT statement sets a savepoint within a unit of recovery to identify a point in time within the unit of recovery to which relational database changes can be rolled back.
  • SELECT
    SELECT commands (or queries) all retrieve information from data tables and display this information in a results table. For purposes of classification, SELECT commands can be subdivided into three general categories including, subselects (and subqueries), fullselects and select statements.
  • SELECT INTO
    The SELECT INTO command (embedded SQL only) retrieves one row of values from a table or view, and then assigns these values to one or more host variables specified in the SELECT INTO command statement.
  • SET AUTOCOMMIT
    The SET AUTOCOMMIT command is used to turn autocommit on or off. When autocommit is on, a command is automatically committed as soon as it is successfully executed.
  • SET COMPATIBILITY
    The SET COMPATIBILITY command is used to specify a mode of operation. When a particular mode is in effect, SQL commands must adhere to the syntax of that mode.
  • SET CONNECTION
    The SET CONNECTION statement establishes the application server of the process by identifying one of its existing connections.
  • SET CURRENT DEGREE
    This command is supported only syntactically by the XDB Server.
  • SET CURRENT LOCALE LC_CTYPE
    The SET CURRENT LOCALE LC_CTYPE statement assigns a value to the CURRENT LOCALE LC_CTYPE special register. The special register allows control over the LC_CTYPE locale for statements that use a function that refers to a locale, such as LCASE, UCASE, and TRANSLATE (with a single argument).
  • SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION
    The SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION statement changes the value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register.
  • SET CURRENT OPTIMIZATION HINT
    The SET CURRENT OPTIMIZATION HINT statement assigns a value to the CURRENT OPTIMIZATION HINT special register.
  • SET CURRENT PACKAGE PATH
    The SET CURRENT PACKAGE PATH assigns a value to the CURRENT PACKAGE PATH special register.
  • SET CURRENT PACKAGESET
    On mainframe DB2 and XDB Servers, this command assigns a value to the CURRENT PACKAGESET special register. This command is partially supported by the XDB Server, which adopts the CURRENT SQLID as the qualifier for the package.
  • SET CURRENT PATH
    The SET CURRENT PATH statement assigns a value to the CURRENT PATH special register.
  • SET CURRENT REFRESH AGE
    The SET CURRENT REFRESH AGE statement changes the value of the CURRENT REFRESH AGE special register.
  • SET CURRENT RULES
    The SET CURRENT RULES statement assigns a value to the CURRENT RULES special register.
  • SET CURRENT SQLID
    The SET CURRENT SQLID statement changes the AuthID value stored in the CURRENT SQLID special register.
  • SET Host Variable
    The SET host-variable assignment statement assigns values, either of expressions or NULL values, to host variables.
  • SET Transitional Variable
    The SET transition-variable assignment statement assigns values, either of expressions or NULL values, to transition variables.
  • SET ISOLATION
    The SET ISOLATION command is used to set the isolation level for locking in multi-user versions.
  • SET LOCATION TO
    The SET LOCATION command logs a user onto a new location, creating an implied connection between the user's sessions and the specified location. The value of the CURRENT SERVER special register is also updated to reflect the new active location.
  • SET LOCATION
    Use this command to prevent all users, except for those with SYSADM privileges, from logging on to a location on the XDB Server. This command does not affect users who are already using the location.
  • SET LOG
    The SET LOG command allows Database Administrators (with SYSADM authority or higher) to suspend logging system operation during an administrative session, and change the path where location log files are stored.
  • SET SCHEMA
    The SET SCHEMA statement assigns a value to the CURRENT SCHEMA special register. If the package is bound with the DYNAMICRULES BIND option, this statement does not affect the qualifier that is used for unqualified database object references.
  • SET SORTSPACE
    Use this command to dynamically reset the size of the sort space on the XDB Server. Active sorts are not affected by this command.
  • SHUTDOWN
    Use the SHUTDOWN command to close the XDB Server program at a specified time. You can also use a variant of this command to cancel a SHUTDOWN request that you have issued.
  • SIGNAL SQLSTATE
    The SIGNAL SQLSTATE statement is used to signal an error. It causes an error to be returned with the specified SQLSTATE and error description.
  • START DATABASE
    The START DATABASE command allows users access to the contents of a named database.
  • START PROCEDURE
    The START PROCEDURE command checks the argument list for a stored procedure already defined to the SQL engine. If the stored procedure meta-data has been imported from another system, this command can be used to check that the argument list is compatible with XDB syntax rules.
  • STOP DATABASE
    The STOP DATABASE command restricts all access to the named database.
  • TRUNCATE TABLE
    The TRUNCATE TABLE command performs the same function as the DELETE command, except TRUNCATE TABLE removes all records from a table without recording the changes in the Forward and Backward Log files.
  • UNLOCK TABLE
    UNLOCK TABLE is used in multi-user versions to release table locks acquired using the LOCK TABLE command.
  • UPDATE (Searched)
    The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.
  • UPDATE (Positioned)
    The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.
  • VALUES
    The VALUES statement provides a method for invoking a user-defined function from a trigger. Transition variables and transition tables can be passed to the user-defined function.
  • VALUES INTO
    The VALUES INTO statement assigns one or more values to host variables.
  • WHENEVER
    The WHENEVER statement (embedded SQL only) has three different forms, each of which changes the execution of a host language program according to the occurrence of specified exception conditions.
Parent topic: SQL Reference


ALLOCATE CURSOR

The ALLOCATE CURSOR statement defines a cursor and associates it with a result set locator variable.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program. It is an executable statement that can be dynamically prepared. It cannot be issued interactively.

Authorization

No authorization is required for this statement.

Syntax

ALLOCATE CURSOR cursor-name
CURSOR FOR RESULT SET rs-locator-variable

Parameters:

cursor-name | Names the cursor. The name must not identify a cursor that has already been declared in the source program.
rs-locator-variable | Names a result set locator variable that has been declared in the application program. The result set locator variable must contain a valid result set locator value, as returned by the ASSOCIATE LOCATORS or DESCRIBE PROCEDURE statements. In the ALLOCATE CURSOR statement, rs-locator-variable is always a host variable.

Description

When an ALLOCATE CURSOR statement is dynamically prepared, the EXECUTE statement with the USING clause must be used to execute the prepared statement. As with all dynamically prepared statements, parameter markers (question marks) must appear where the host variables would appear in the prepared statement. The USING clause of the EXECUTE statement should specify the host variables for which the values are to be substituted for the parameter markers in the dynamically prepared ALLOCATE CURSOR statement.

You cannot use a statement identifier for an ALLOCATE CURSOR statement if the same statement identifier has been used for a DECLARE CURSOR statement.

The following rules apply when you use an allocated cursor:

  • For this statement to be successful, an application must be currently connected to the site where the stored procedure was executed.
  • You cannot open an allocated cursor by using the SQL OPEN cursor statement.
  • You can close an allocated cursor by using the SQL CLOSE cursor statement. This closes the cursor in the stored procedure as well.
  • You can allocate only one cursor to each result set.

Rollback, and an implicit and explicit close destroy allocated cursors. A commit destroys allocated cursors that are not defined WITH HOLD by the stored procedure. Destroying an allocated cursor closes the associated cursor in the stored procedure.

Parent topic: SQL Statements


ALTER DATABASE

The ALTER DATABASE statement changes the description of the specified database under the currently set XDB Server location.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER DATABASE command, users must possess either DBADM or DBCTRL authority for the database, DROP privilege on the database, overall SYSADM or SYSCTRL authority for the location, or be the owner of the database affected.

Syntax

ALTER DATABASE database-name

[BUFFERPOOL bpname]
    [INDEXBP bpname]
    [STOGROUP stogroup-name]
    [CCSID ccsid-value]

Parameters:

database-name | Identifies the database to be altered. The database must exist within the currently set location.
BUFFERPOOL bpname | Identifies the default buffer pool for the table spaces within the database. It does not apply to table spaces that already exist within the database. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9 If the database is a work file database, 8KB and 16KB buffer pools cannot be specified.
INDEXBP bpname | Identifies the default buffer pool for the indexes within the database. It does not apply to indexes that already exist within the database. The name must identify a 4KB buffer pool. INDEXBP cannot be specified for a work file database.
stogroup-name | Identifies an optional stogroup for this database, if stogroups are used.
ccsid-value | Identifies the default CCSID for table spaces within the database. It does not apply to existing table spaces in the database. ccsid-value must identify a CCSID value that is compatible with the current value of the CCSID for the database. CCSID cannot be specified for a work file data base or a TEMP database.

Description

The ALTER DATABASE command offers users the option of assigning a stogroup designation to a logical database. This command can also specify whether or not the database is used as a Read-Only Shared database.

BUFFERPOOL

This clause has no functional equivalent in the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, BP32K, BPK1...BPK9). The first fifty bufferpools are for tables with 4K page sizes, while the last ten are for tables with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server catalog tables.

CCSID

This clause has no functional equivalent in the XDB Server operating environment.

STOGROUP

This clause allows the user to change the default stogroup to which all objects created under this database will be physically stored. This clause does not affect the storage locations of tables and indexes already created under the database. On an XDB Server, a stogroup designates a particular drive (and/or directory) on which all objects created under a logical database are physically stored. A stogroup is usually assigned to a database, or table space within a database, when these objects are created.

Example:

Change the default buffer pool for both table spaces and indexes within database ABCDE to BP2.

ALTER DATABASE ABCDE
    BUFFERPOOL BP2
    INDEXBP BP2;
Parent topic: SQL Statements


ALTER FUNCTION

The ALTER FUNCTION statement changes the description of an external scalar or external table function at the current server.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER FUNCTION command, users must possess either overall SYSADM or SYSCTRL authority for the location, or be the owner of the function affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER FUNCTION function-name [(parameter-type[,...])] |
SPECIFIC FUNCTION specific-name
    [EXTERNAL NAME {'string' | identifier}]
    [LANGUAGE {ASSEMBLE | C | COBOL | PLI}]
    [[NOT] DETERMINISTIC]
    [{RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT}]
    [{CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA | NO SQL}]
    [[NO] EXTERNAL ACTION]
    [{NO SCRATCHPAD | SCRATCHPAD length}]
    [[NO] FINAL CALL]
    [{ALLOW PARALLEL | DISALLOW PARALLEL}]
    [[NO] DBINFO]
    [CARDINALITY integer]
    [{NO COLLID | COLLID collection-id}]
    [WLM ENVIRONMENT {name | (name,*)}]
    [ASUTIME {NO LIMIT | LIMIT integer}]
    [STAY RESIDENT {NO | YES}]
    [PROGRAM TYPE {SUB | MAIN}]
    [SECURITY {DB2 | USER | DEFINER}]
    [STOP AFTER SYSTEM DEFAULT FAILURES |
      STOP AFTER integer FAILURES |
      CONTINUE AFTER FAILURE]
    [RUN OPTIONS run-time-options]

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE table-name as LOCATOR}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

[SMALLINT]
[INTEGER | INT]
[{DECIMAL | DEC | NUMERIC} [(integer[,...])]
[{FLOAT [(integer)] | REAL [PRECISION] | DOUBLE}]
[{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) } [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | I} |[{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
    {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] }]
[{BINARY LARGE OBJECT | BLOB} [(integer [K|M|G])]]
[{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB [(integer [K|M|G])] } [CCSID {EBCDIC | ASCII}]]
[DATE | TIME | TIMESTAMP]
[ROWID]

Description

One of the following three clauses identifies the function to be changed.

FUNCTION function-name

Identifies the external function by its function name. The name is implicitly or explicitly qualified with a schema name. If the name is not explicitly qualified, it is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is prepared dynamically, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The identified function must be an external function. There must be exactly one function with function-name in the schema. The function can have any number of input parameters. If the schema does not contain a function with function-name or contains more than one function with this name, an error occurs.

FUNCTION function-name (parameter-type,...)

Identifies the external function by its function signature, which uniquely identifies the function.

function-name | gives the function name of the external function. If the function name is not qualified, it is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.
(parameter-type,...) | identifies the number of input parameters of the function and their data types.

The data type of each parameter must match the data type that was specified in the CREATE FUNCTION statement for the parameter in the corresponding position. The number of data types and the logical concatenation of the data types are used to uniquely identify the function. Therefore, you cannot change the number of parameters or the data types of the parameters.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match.FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).
  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.
  • The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:
    CHAR | CHAR(1)
    GRAPHIC | GRAPHIC(1)
    DECIMAL | DECIMAL(5,0)
    FLOAT | DOUBLE (length of 8)

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement

For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that XDB ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

A function with the function signature must exist in the explicitly or implicitly specified schema; otherwise, an error occurs.

SPECIFIC FUNCTION specific-name

Identifies the external function by its specific name. The name is implicitly or explicitly qualified with a schema name. A function with the specific name must exist in the schema; otherwise, an error occurs.

If the specific name is not qualified, it is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.

The following clauses change the description of the function that has been identified to be changed.

EXTERNAL NAME 'string' or identifier

Identifies the name of the module that contains the user-written code that implements the logic of the function. The external program name can be a string constant that is no longer than 8 characters or a short identifier.

The module is created when the program that contains the function body is compile . The module does not need to exist when the ALTER FUNCTION statement is executed. However, it must exist and be accessible by the current server when the function is invoked.

LANGUAGE

Specifies the application programming language in which the function is written. All programs must be designed to run in IBM's Language Environment environment .

ASSEMBLE | The function is written in Assembler. (Not currently available with XDB Server)
C | The function is written in C or C++. (Not currently available with XDB Server)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PL/I | The function is written in PL/I. (Not currently available with XDB Server)

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the function returns the same results for identical input arguments.

NOT DETERMINISTIC The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements.

Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.

If a view or a materialized query table definition refers to the function, the function cannot be changed to NOT DETERMINISTIC. To change the function, drop any views or materialized query tables that refer to the function first.

DETERMINISTIC The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input.

XDB does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

RETURNS NULL ON NULL INPUT or CALLED ON NULL INPUT

Specifies whether the function is called if any of the input arguments is null at execution time.

RETURNS NULL ON NULL INPUT | The function is not called if any of the input arguments is null. For an external scalar function, the result is the null value. For an external table function, the result is an empty table, which is a table with no rows.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. For an external scalar function, the function can return a null or nonnull value. For an external table function, the function can return an empty table, depending on its logic.

NO SQL, MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL

Indicates whether the function issues any SQL statements and, if so, what type.

NO SQL | The function cannot execute any SQL statements.
MODIFIES SQL DATA | The function can execute any SQL statement except those statements that are not supported in any function. Do not specify MODIFIES SQL DATA for external table functions or with ALLOW PARALLEL.
READS SQL DATA | The function cannot execute SQL statements that modify data. SQL statements that are not supported in any function return a different error.
CONTAINS SQL | The function cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.

NO EXTERNAL ACTION or EXTERNAL ACTION

This clause has no functional equivalent in the XDB Server operating environment.

NO SCRATCHPAD or SCRATCHPAD

Specifies whether XDB provides a scratchpad for the function. It is strongly recommended that external functions be reentrant, and a scratchpad provides an area for the function to save information from one invocation to the next.

NO SCRATCHPAD A scratchpad is not allocated and passed to the function.
SCRATCHPAD When the function is invoked for the first time, XDB allocates memory for a scratchpad. A scratchpad has the following characteristics:
  • Length must be between 1 and 32767. The default value is 100 bytes.
  • XDB initializes the scratchpad to all binary zeros (X'00's).
  • The scope of a scratchpad is the SQL statement. For each reference to the function in an SQL statement, there is one scratchpad. For example, assuming that function UDFX was defined with the SCRATCHPAD keyword, three scratchpads are allocated for the three references to UDFX in the following SQL statement:
    SELECT A, UDFX(A) FROM TABLEB WHERE UDFX(A) > 103 OR UDFX(A) < 19;

    If the function is run under parallel tasks, one scratchpad is allocated for each parallel task of each reference to the function in the SQL statement. This can lead to unpredictable results. For example, if a function uses the scratchpad to count the number of times that it is invoked, the count reflects the number of invocations done by the parallel task and not the SQL statement. Specify the DISALLOW PARALLEL clause for functions that do not work correctly with parallelism.

  • The scratchpad is persistent. XDB preserves its content from one invocation of the function to the next. Any changes that the function makes to the scratchpad on one call are still there on the next call. XDB initializes the scratchpads when it begins to execute an SQL statement. XDB does not reset scratchpads when a correlated subquery begins to execute.
  • The scratchpad can be a central point for the system resources that the function acquires. If the function acquires system resources, specify FINAL CALL to ensure that XDB calls the function one more time so that the function can free those system resources.

Each time that the function is invoked, XDB passes an additional argument to the function that contains the address of the scratchpad.

NO FINAL CALL or FINAL CALL

Specifies whether a final call is made to the function. A final call enables the function to free any system resources that it has acquired. A final call is useful when the function has been defined with the SCRATCHPAD keyword and the function acquires system resource and anchors them in the scratchpad.

The effect of NO FINAL CALL or FINAL call depends on whether the external function is a scalar function or a table function.

For an external scalar function:

NO FINAL CALL

A final call is not made to the external scalar function. The function does not receive an additional argument that specifies the type of call.

FINAL CALL

A final call is made to the external scalar function. See the following description of call types for the characteristics of a final call. When FINAL CALL is specified, the function receives an additional argument that specifies the type of call to enable the function to differentiate between a final call and another type of call.

For an external table function:

NO FINAL CALL

A first and final call are not made to the external table function.

FINAL CALL

A first call and final call are made to the external table function in addition to one or more other types of calls.

ALLOW or DISALLOW PARALLEL

This clause has no functional equivalent in the XDB Server operating environment.

NO DBINFO or DBINFO

Specifies whether specific information that XDB knows is passed to the function when it is invoked.

NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function. For details about the argument and its structure, see your DB2 Application Programming and SQL Guide.

CARDINALITY integer

Specifies an estimate of the expected number of rows that the function returns. The number is used for optimization purposes. The value of integer must range from 0 to 2147483647.

If a function has an infinite cardinality--the function never returns the "end-of-table" condition and always returns a row, then a query that requires the "end-of-table" to work correctly, will need to be interrupted. Thus, avoid using such functions in queries that involve GROUP BY and ORDER BY.

Do not specify CARDINALITY for external scalar functions.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the function is executed.

NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of the function can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a function, setting a limit can be helpful if the function gets caught in a loop.

NO LIMIT | There is no limit on the service units.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the load module for the function remains resident in memory when the function ends.

NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the function program runs as a main routine or a subroutine.

SUB | The function runs as a subroutine.
MAIN | The function runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures. The following options must not be specified for SQL functions or sourced functions.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

Note:

Changes are immediate: Any changes that the ALTER FUNCTION statement causes to the definition of an external function take effect immediately. The changed definition is used the next time that the function is invoked.

Examples:

Assume that there are two functions CENTER in the PELLOW schema. The first function has two input parameters with INTEGER and FLOAT data types, respectively. The specific name for the first function is FOCUS1. The second function has three parameters with CHAR(25), DEC(5,2), and INTEGER data types.

Using the specific name to identify the function, change the WLM environment in which the first function runs from WLMENVNAME1 to WLMENVNAME2.

ALTER SPECIFIC FUNCTION PELLOW.FOCUS1 WLM ENVIRONMENT WLMENVNAME2;

Change the second function that is described above so that it is not invoked when any of the arguments are null. Use the function signature to identify the function,

 ALTER FUNCTION PELLOW.CENTER (CHAR(25), DEC(5,2), INTEGER)
     RETURNS NULL ON NULL INPUT;

You can also code the ALTER FUNCTION statement without the exact values for the CHAR and DEC data types:

 ALTER FUNCTION PELLOW.CENTER (CHAR(), DEC(), INTEGER)
     RETURNS NULL ON NULL INPUT;

If you use empty parentheses, XDB ignores the length, precision, and scale attributes when looking for matching data types to find the function.

Parent topic: SQL Statements


ALTER FUNCTION (SQL)

The ALTER FUNCTION (SQL) statement changes the description of a user-defined SQL scalar function at the current server.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set defined below must include at least one of the following:

  • Ownership of the function
  • The ALTERIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the ALTERIN privilege on the schema.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the authorization IDs of the process. The specified function name can include a schema name (a qualifier). However, if the schema name is not the same as one of these authorization IDs, one of the following conditions must be met:

  • The privilege set includes SYSADM or SYSCTRL authority.
  • An authorization ID of the process has the ALTERIN privilege on the schema.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER {FUNCTION function-name [(parameter-type[,...])] |
    SPECIFIC FUNCTION specific-name}
    option-list

parameter-type

{data-type [AS LOCATOR] | TABLE LIKE table-name AS LOCATOR}

data-type

{built-in-type | distinct-type-name}

built-in-type

[SMALLINT]
[INTEGER | INT]
[DECIMAL | DEC | NUMERIC} [(5,0) | (integer [,integer])]
[FLOAT [(53) | (integer)] | REAL [PRECISION] | DOUBLE}]
[{{CHARACTER | CHAR} [(1) | (integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] |
    {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(1M) | (integer [K | M | G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] }]
[{GRAPHIC [(1) | (integer)] | VARGRAPHIC (integer) | DBCLOB [(1M) | (integer [K | M | G])]}
    [CCSID {ASCII | EBCDIC | UNICODE}]]
[{BINARY LARGE OBJECT | BLOB} [(1M) | (integer [K | M | G])]]
[DATE | TIME | TIMESTAMP]
[ROWID]

option-list

LANGUAGE SQL
    [DETERMINISTIC | NOT DETERMINISTIC]
    [EXTERNAL ACTION | NO EXTERNAL ACTION]
    [CONTAINS SQL | READS SQL DATA]
    [STATIC DISPATCH CALLED ON NULL INPUT]
Parent topic: SQL Statements


ALTER INDEX

On a mainframe DB2 subsystem, this statement changes the configuration of an existing index. See the ALTER TABLE command for information on altering indexes that result from UNIQUE, PRIMARY and FOREIGN keys. In some cases, it may be necessary to drop an index and re-create it using the DROP INDEX and CREATE INDEX commands.
Restriction: This topic applies to Windows environments only.

Invocation

When issued against an XDB Server, this statement only supports the ADD COLUMN clause, but is fully supported when issued against a DB2 database through XDB Link.

Syntax

ALTER INDEX index-name
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [COPY {YES | NO}]
    [DSETPASS password]
    [PART integer]
    [FREEPAGE integer]
    [PCTFREE integer]
    [USING {VCAT catalog-name
            | STOGROUP stogroup-name}]
    [PRIQTY {3 | integer}]
    [SECQTY {3 | integer}]
    [ERASE {YES | NO}] [GBPCACHE {CHANGED | ALL}]
    [CONVERT TO {TYPE 1 [SUBPAGES {4 | 1 | 2 | 8 | 16}] | TYPE 2}]
    [PIECESIZE integer {K | M | G}]
    [PART integer [VALUES (constant[,...])]
        [[using-block | free-block | gbpcache-block][...]][,...]]
    [{CLUSTER | NOT CLUSTER}]
    [{PADDED | NOT PADDED}]
    [ADD COLUMN (column-name [{ASC | DESC}] )]

Parameters:

bpname A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.

Description

index-name

Identifies the index to be altered. The name must identify a user-created index that exists at the current server. The name must not identify an index that is defined on a declared temporary table.

BUFFERPOOL

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, BP32K, BPK1...BPK9). The first fifty bufferpools are for indexes with 4K page sizes, while the last ten are for indexes with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server catalog tables.

COPY

Indicates whether the COPY utility is allowed for the index.

NO | Does not allow full image or concurrent copies or the use of the RECOVER utility on the index.
YES | Allows full image or concurrent copies and the use the RECOVER utility on the index.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

PIECESIZE integer

Specifies the maximum addressability of each piece (data set) for a nonpartitioning index. Be very aware that when you alter the PIECESIZE value, the index is placed into REBUILD-pending (PSRBD) status and the entire index space becomes inaccessible. You must run the REBUILD INDEX or the REORG TABLESPACE utility to remove that status.

The subsequent keyword K, M, or G, indicates the units of the value specified in integer.

K | Indicates that the integer value is to be multiplied by 1 024 to specify the maximum piece size in bytes. The integer must be a power of two between 256 and 67 108 864.
M | Indicates that the integer value is to be multiplied by 1 048 576 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 65 536.
G | Indicates that the integer value is to be multiplied by 1 073 741 824 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 64

The piece size limit for partitioned table spaces with more than 254 partitions is 4096.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

Using Block for Nonpartitioning Indexes

For nonpartitioning indexes, the USING clause specifies whether the data sets for the index are to be managed by the user or managed by DB2. The USING clause applies to every data set that can be used for the index. (A nonpartitioning index can have more than one data set if PRIQTY+118 * SECQTY is at least 2 gigabytes.)

If you specify USING, the index must be in the stopped state when the ALTER INDEX statement is executed.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

USING Block for Partitioning Indexes:

For a partitioning index, there is an optional PART clause for each partition. A using-block can be specified at the global level or at the partition level. A using-block within a PART clause applies only to that partition. A using-block specified before any PART clauses applies to every partition except those with a PART clause with a using-block.

For DB2-managed data sets, the values of PRIQTY, SECQTY, and ERASE for each partition are given by the first of these choices that applies:

  • The values of PRIQTY, SECQTY, and ERASE given in the using-block within the PART clause for the partition. Do not use more than one using-block in any PART clause.
  • The values of PRIQTY, SECQTY, and ERASE given in a using-block before any PART clauses
  • The current values of PRIQTY, SECQTY, and ERASE

For data sets that are being changed from user-managed to DB2-managed, the values of PRIQTY, SECQTY, and ERASE for each partition are given by the first of these choices that applies:

  • The values of PRIQTY, SECQTY, and ERASE given in the using-block within the PART clause for the partition. Do not use more than one using-block in any PART clause.
  • The values of PRIQTY, SECQTY, and ERASE given in a using-block before any PART clauses
  • The default values of PRIQTY, SECQTY, and ERASE, which are:

    PRIQTY 12

    SECQTY 12, if PRIQTY is not specified in either using-block, or 10% of PRIQTY or 3 times the index page size (whichever is larger) when PRIQTY is specified

    ERASE NO

Any partition for which USING or ERASE is specified (either explicitly at the partition level or implicitly at the global level) must be in the stopped state when the ALTER INDEX statement is executed.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

VCAT catalog-name

Specifies a user-managed data set with a name that starts with the specified catalog name. You must specify the catalog name in the form of a short identifier. Thus, you must specify an alias if the name of the integrated catalog facility catalog is longer than eight characters.

If n is the number of the partition, the identified integrated catalog facility catalog must already contain an entry for the nth data set of the index. Refer to appropriate DB2 documentation for a full explanation of DB2 naming conventions for data sets.

One or more DB2 subsystems could share integrated catalog facility catalogs with the current server. To avoid the chance of having one of those subsystems attempt to assign the same name to different data sets, select a value for catalog-name that is not used by the other DB2 subsystems.

DB2 assumes one and only one data set for each partition.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

STOGROUP stogroup-name

If USING STOGROUP is used, stogroup-name must identify a storage group that exists at the current server and the privilege set must include SYSADM authority, SYSCTRL authority, or the USE privilege for the storage group.

DB2 assumes one and only one data set for each partition.

Omitting or specifying -1 for the PRIQTY or SECQTY clause implicitly specifies the default value for that clause. For more information on the PRIQTY, SECQTY, and ERASE clauses, see the description of those clauses for nonpartitioning indexes.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

FREEPAGE integer

Specifies how often to leave a page of free space when index entries are created as the result of executing a DB2 utility. One free page is left for every integer pages. The value of integer can range from 0 to 255. The change to the description of the index or partition has no effect until it is loaded or reorganized using a DB2 utility.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

PCTFREE integer

Determines the percentage of free space to leave in each nonleaf page and leaf page when entries are added to the index or partition as the result of executing a DB2 utility. The first entry in a page is loaded without restriction. When additional entries are placed in a nonleaf or leaf page, the percentage of free space is at least as great as integer.

The value of integer can range from 0 to 99, however, if a value greater than 10 is specified, only 10 percent of free space will be left in nonleaf pages. The change to the description of the index or partition has no effect until it is loaded or reorganized using a DB2 utility.

If the index is partitioning, the values of FREEPAGE and PCTFREE for a particular partition are given by the first of these choices that applies:

  • The values of FREEPAGE and PCTFREE given in the PART clause for that partition. Do not use more than one free-block in any PART clause.
  • The values given in a free-block before any PART clauses.
  • The current values of FREEPAGE and PCTFREE for that partition.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

GBPCACHE

Specifies what index pages are written to the group buffer pool in a data sharing environment. In a non-data-sharing environment, you can specify this option, but it is ignored.

CHANGED | When there is inter-DB2 R/W interest on the index or partition, updated pages are written to the group buffer pool. When there is no inter-DB2 R/W interest, the group buffer pool is not used. Inter-DB2 R/W interest exists when more than one member in the data sharing group has the index or partition open, and at least one member has it open for update. If the index is in a group buffer pool that is defined as GBPCACHE(NO), CHANGED is ignored and no pages are cached to the group buffer pool.
ALL | Indicates that pages are to be cached to the group buffer pool as they are read in from DASD, with one exception. When the page set is not GBP-dependent and one DB2 data sharing member has exclusive R/W interest in that page set (no other group members have any interest in the page set), no pages are cached in the group buffer pool. Hiperpools are not used for indexes or partitions that are defined with GBPCACHE ALL. If the index is in a group buffer pool that is defined as GBPCACHE(NO), ALL is ignored and no pages are cached to the group buffer pool.
NONE | Indicates that no pages are to be cached to the group buffer pool. DB2 uses the group buffer pool only for cross-invalidation. If you specify NONE, the index or partition must not be in group buffer pool recover pending (GRECP) status.

If the index is partitioned, the value of GBPCACHE for a particular partition is given by the first of these choices that applies:

  1. The value of GBPCACHE given in the PART clause for that partition. Do not use more than one gbpcache-block in any PART clause.
  2. The value given in a gbpcache-block before any PART clauses.
  3. The current value of GBPCACHE for that partition.

If you specify GBPCACHE in a data sharing environment, the index or partition must be in the stopped state when the ALTER INDEX statement is executed. You cannot alter the GBPCACHE value for the following indexes on catalog table SYSIBM.SYSINDEXES: DSNDXX01, DSNDXX02, DSNDXX03.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

PART integer

Identifies a partition of the index. For an index that has n partitions, you must specify an integer in the range 1 to n. You must not use this clause if the index is nonpartitioned. You must use this clause if the index is partitioned and you specify the VALUES clause.

VALUES(constant,...) Specifies the highest value of the index key for the identified partition of the partitioning index. In this context, highest means highest in the sorting sequences of the index columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC), the lowest actual value is highest in the sorting sequence.

You must use at least one constant after VALUES in each PART clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition of the index. The length of each highest key value (also called the limit key) is the same as the length of the partitioning index.

The use of the constants to define key values is subject to these rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must have the same data type as its corresponding column.
  • If a key includes a ROWID column (or a column with a distinct type that is sourced on a ROWID data type), the values of the ROWID column are assumed to be in the range of X'000...00' to X'FFF...FF'. Only the first 17 bytes of the constant that is specified for the corresponding ROWID column are considered.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'; if the column is descending, the padding character is X'00'.
  • Using fewer constants than there are columns in the key has the same effect as using the highest possible values for all omitted columns for an ascending index. For a descending index, it has the same effect as using the lowest possible values for all omitted columns.
  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition.
  • The highest value of the key in the last partition depends on how the table space was defined. For table spaces created without the LARGE or DSSIZE option, the constants you specify after VALUES are not enforced. The highest value of the key that can be placed in the table is the highest possible value of the key.For table spaces created with the LARGE or DSSIZE options, the constants you specify after VALUES are enforced. The value specified by the constants is the highest value of the key that can be placed in the table. Any keys that are made invalid after the ALTER statement is executed are placed in a discard data set when you run REORG. If the last partition is in REORG pending, regardless of whether you changed its limiting key values, you must specify a discard data set when you run REORG.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

CLUSTER or NOT CLUSTER

Specifies whether the index is the clustering index for the table.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

CLUSTER

The index is used as the clustering index for the table. This change takes effect immediately. Any subsequent INSERT statements will use the new clustering index. Existing data remains clustered by the previous clustering index until the table space is reorganized.

The implicit or explicit clustering index is ignored when data is inserted into a table space that is defined with MEMBER CLUSTER. Instead of using cluster order, DB2 chooses where to locate the data based on available space. The MEMBER CLUSTER attribute affects only data that is inserted with the INSERT statement; data is always loaded and reorganized in cluster order.

Do not specify CLUSTER if the table is an auxiliary table or if CLUSTER was used already for a different index on the table.

NOT CLUSTER

The index is not used as the clustering index of the table. If the index is already defined as the clustering index, it continues to be used as the clustering index by DB2 and the REORG utility until clustering is explicitly changed by specifying CLUSTER for a different index.

Specifying NOT CLUSTER for an index that is not a clustering index is ignored.

If the index is the partitioning index for a table that uses index-controlled partitioning, the table is converted to use table-controlled partitioning. The high limit key for the last partition is set to the highest possible value for ascending key columns or the lowest possible value for descending key columns.

NOT PADDED or PADDED

Specifies how varying-length string columns are to be stored in the index. If the index contains no varying-length columns, this option is ignored, and a warning message is returned.

The XDB server operating environment syntactically verifies this clause, and records information in the appropriate catalog tables.

NOT PADDED

Specifies that varying-length string columns are not to be padded to their maximum length in the index. The length information for a varying-length column is stored with the key.

NOT PADDED is ignored and has no effect if the index is on an auxiliary table. Indexes on auxiliary tables are always padded.

When PADDED is changed to NOT PADDED, the index key length is recalculated with the varying-length formula (2000 - n - 2m, where n is the number of columns that can contain null values and m is the number of varying-length columns in the key). If it is possible that the index key length may exceed the maximum length (because before when it was padded, the formula 2000 - n was used), an error occurs.

PADDED

Specifies that varying-length string columns within the index are always padded with the default pad character to their maximum length.

When an index with at least one varying-length column is changed from PADDED to NOT PADDED, or vice versa, the index is placed in restricted REBUILD-pending status (RBDP). The index cannot be accessed until it is rebuilt from the table (REBUILD INDEX, REORG TABLESPACE, or LOAD REPLACE utility). For nonpartitioned secondary indexes (NPSIs), the index is placed in page set REBUILD-pending status (PSRBD), and the entire index must be rebuilt. In addition, plans and packages that are dependent on the table are quiesced, and dynamically cached statements that are dependent on the index are invalidated.

ADD COLUMN column-name

Adds column-name to the index. column-name must be unqualified, must identify a column of the table, must not be one of the existing columns of the index, and must not be a LOB column or a distinct type column based on a LOB data type. The total number of columns for the index cannot exceed 64.

For PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000 - n, where n is the number of columns that can contain null values.

For NOT PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000 - n -2m, where n is the number of nullable columns and m is the number of varying-length columns.

The index cannot be any of the following types of indexes:

  • A system-defined catalog index
  • An index that enforces a primary key, unique key, or referential constraint
  • A partitioning index when index-controlled partitioning is being used
  • A unique index required for a ROWID column defined as GENERATED BY DEFAULT
  • An auxiliary index

If the column is added to the table and that same column is added to an associated index within the same commit scope and within that commit scope no data rows were inserted, the index is left in advisory REORG-pending (AREO*) state; otherwise, the index is left in REBUILD-pending (RBDP) state.

  • ASC - Index entries are put in ascending order by the column.
  • DESC - Index entries are put in descending order by the column.

Examples:

Alter the index DSN8610.XEMP1. Indicate that XDB is not to close the data sets that support the index when there are no current users of the index.

 ALTER INDEX DSN8610.XEMP1
     CLOSE NO;

Alter the index DSN8610.XPROJ1. Use BP1 as the buffer pool that is to be associated with the index, indicate that full image or concurrent copies on the index are allowed, and change the maximum size of each data set to 8 megabytes.

 ALTER INDEX DSN8610.XPROJ1
     BUFFERPOOL BP1
     COPY YES
     PIECESIZE 8M;
Parent topic: SQL Statements


ALTER LOCATION

The ALTER LOCATION statement converts (upgrades) a location to DB2 Version 6, 7 or 8 compatibility.
Restriction: This topic applies to Windows environments only.
Note:

By default, XDB Server creates locations that are compatible with DB2 Version 6, 7 or 8.

Invocation

ALTER LOCATION is an executable command that can be issued interactively, embedded in a host language or dynamically prepared.

Authorization

To execute the ALTER LOCATION command, users must have INSTALL or SYSADM privileges.

Syntax

ALTER LOCATION location-name TO {VERSION {V41 | V51 | V60 | V71 | V80} | SORT SEQUENCE language-name EBCDIC}

Parameters:

location-name

Identifies the location to be converted.

  • swedish
  • classic
  • dutch
  • french
  • spanish
  • italian
  • uk
  • danish
  • norwegian
  • finnish
  • german
  • austrian
  • portuguese
  • us
  • international
  • turkish

Description

You can use most DB2 Version 7.0 and Version 8.0 features without converting your existing XDB Server locations. However, you cannot use new DDL-related features without upgrading. Once you convert a location to DB2 Version 7.0 and Version 8.0 compatibility, you cannot use it with an earlier version of the XDB Server.

Example:

alter location jbl to sort sequence german ebcdic;
Parent topic: SQL Statements


ALTER PASSWORD

The ALTER PASSWORD statement enables you to change passwords.
Restriction: This topic applies to Windows environments only.

Syntax

ALTER PASSWORD old_password TO new_password
Parent topic: SQL Statements


ALTER PROCEDURE (external)

The ALTER PROCEDURE statement changes the description of a stored procedure at the current server.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER PROCEDURE command, users must possess either overall SYSADM or SYSCTRL authority for the location, or be the owner of the stored procedure affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER PROCEDURE procedure-name
    [DYNAMIC RESULT {SET | SETS} integer]
    [EXTERNAL NAME {'string' | indentifier}]
    [LANGUAGE {ASSEMBLE | C | COBOL | COMPJAVA | PLI | REXX}]
    [PARAMETER STYLE {DB2SQL | GENERAL | GENERAL WITH NULLS | JAVA}]
    [{DETERMINISTIC | NOT DETERMINISTIC}]
    [{CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA | NO SQL}]
    [{DBINFO | NODBINFO}]
    [{NO COLLID | COLLID collection-id}]
    [{WLM ENVIRONMENT {name | (name,*)}} | NO WLM ENVIRONMENT}]
    [ASUTIME {NO LIMIT | LIMIT integer}]
    [STAY RESIDENT {NO | YES}]
    [PROGRAM TYPE {SUB | MAIN}]
    [SECURITY {DB2 | USER | DEFINER}]
    [RUN OPTIONS run-time-options]
    [COMMIT ON RETURN {NO | YES}]
    [CALLED ON NULL INPUT]
    [{STOP AFTER SYSTEM DEFAULT FAILURES |
     STOP AFTER integer FAILURES |
     CONTINUE AFTER FAILURE}]

Description

procedure-name

Identifies the stored procedure to be altered. The name is implicitly or explicitly qualified by a schema name. If the name is not explicitly qualified, it is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

DYNAMIC RESULT SET integer or DYNAMIC RESULT SETS integer

Specifies the maximum number of query result sets that the stored procedure can return. The value must be between 0 and 32767.

EXTERNAL NAME 'string' or identifier

Identifies the program that runs when the procedure name is specified in a CALL statement.

The name can be a string constant that is no longer than 8 characters or a short identifier.

The program does not need to exist when the ALTER PROCEDURE statement is executed. However, it must exist and be accessible by the current server when a CALL statement for the stored procedure is issued.

LANGUAGE

Specifies the application programming language in which the stored procedure is written. Assembler, C, COBOL, and PL/I programs must be designed to run in IBM's Language Environment.

ASSEMBLE | The stored procedure is written in Assembler. (Not currently available with XDB Server.)
C | The stored procedure is written in C or C++. (Not currently available with XDB Server.)
COBOL | The stored procedure is written in COBOL, including the OO-COBOL language extensions.
COMPJAVA | The stored procedure is written in Java and is a compiled program. (Not currently available with XDB Server.)
PL/I | The stored procedure is written in PL/I. (Not currently available with XDB Server.)
REXX | The stored procedure is written in REXX. Do not specify LANGUAGE REXX when PARAMETER STYLE DB2SQL or NO WLM ENVIRONMENT is in effect. (Not currently available with XDB Server.)

PARAMETER STYLE

Identifies the linkage convention used to pass parameters to the stored procedure. All of the linkage conventions provide arguments to the stored procedure that contain the parameters specified on the CALL statement. Some of the linkage conventions pass additional arguments to the stored procedure that provide more information to the stored procedure. For more information on linkage conventions, refer to appropriate DB2 documentation for a full explanation.

DB2SQL In addition to the parameters on the CALL statement, the following arguments are also passed to the stored procedure:
  • A null indicator for each parameter on the CALL statement
  • The SQLSTATE to be returned to DB2
  • The qualified name of the stored procedure
  • The specific name of the stored procedure
  • The SQL diagnostic string to be returned to DB2

If DBINFO is specified, an additional parameter, the DB2INFO structure, might also be passed. Do not specify DB2 SQL when LANGUAGE REXX is in effect.

GENERAL | Only the parameters on the CALL statement are passed to the stored procedure. The parameters cannot be null.
GENERAL WITH NULLS | In addition to the parameters on the CALL statement, another argument is also passed to the stored procedure. The additional argument contains a vector of null indicators for each of the parameters on the CALL statement that enables the stored procedure to accept or return null parameter values.
JAVA | The stored procedure uses a convention for passing parameters that conforms to the Java and SQLJ specifications. INOUT and OUT parameters are passed as single-entry arrays. The DBINFO structure is not passed. JAVA can be specified only if LANGUAGE is COMPJAVA. For REXX stored procedures (LANGUAGE REXX), GENERAL and GENERAL WITH NULLS are the only valid values for PARAMETER STYLE. For LANGUAGE COMPJAVA, JAVA is the only valid value.

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the stored procedure returns the same result from successive calls with identical input arguments.

NOT DETERMINISTIC | The stored procedure might not return the same result from successive calls with identical input arguments.
DETERMINISTIC | The stored procedure returns the same result from successive calls with identical input arguments. XDB does not verify that the stored procedure code is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

NO SQL, MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL DATA

Indicates whether the stored procedure issues any SQL statements and, if so, what type.

NO SQL | The stored procedure cannot execute any SQL statements.
MODIFIES SQL DATA | The stored procedure can execute any SQL statement except those statements that are not supported in any stored procedure.
READS SQL DATA | The stored procedure cannot execute SQL statements that modify data. SQL statements that are not supported in any stored procedure return a different error.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any stored procedure return a different error.

NO DBINFO or DBINFO

Specifies whether specific information known by XDB is passed to the stored procedure when it is invoked.

NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the stored procedure is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the procedure might be inserting into or updating, and identification of the database server that invoked the procedure.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the stored procedure is executed.

NO COLLID | The package collection for the stored procedure is the same as the package collection of the program that invokes the stored procedure. If a trigger invokes the stored procedure, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

NO WLM ENVIRONMENT

Indicates that the stored procedure is to run in the XDB-established stored procedure address space.

Do not specify NO WLM ENVIRONMENT if the definition of the stored procedure implicitly or explicitly includes the following clauses or parameters:

  • The PROGRAM TYPE SUB clause
  • The SECURITY USER or SECURITY DEFINER clause
  • The LANGUAGE REXX clause
  • Parameters with a LOB data type or a distinct type based on a LOB data type

To change the procedure to run in the XDB-established stored procedure address space, you must have appropriate authority for the XDB-established stored procedure address space.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of a stored procedure can run. The value is unrelated to the ASUTIME column in the resource limit specification table.

When you are debugging a stored procedure, setting a limit can be helpful in case the stored procedure gets caught in a loop.

NO LIMIT | There is no limit on the service units.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the stored procedure uses more service units than the specified value, the stored procedure is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the stored procedure load module remains resident in memory when the stored procedure ends.

NO | The load module is deleted from memory after the stored procedure ends. Use NO for non-reentrant stored procedures.
YES | The load module remains resident in memory after the stored procedure ends.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the stored procedure runs as a main routine or a subroutine.

SUB | The stored procedure runs as a subroutine.
MAIN | The stored procedure runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

COMMIT ON RETURN

Indicates whether XDB commits the transaction immediately on return from the stored procedure.

NO XDB does not issue a commit when the stored procedure returns.
YES XDB issues a commit when the stored procedure returns if the following statements are true:
  • The SQLCODE that is returned by the CALL statement is not negative.
  • The stored procedure is not in a must abort state.

The commit operation includes the work that is performed by the calling application process and the stored procedure.

If the stored procedure returns result sets, the cursors that are associated with the result sets must have been defined WITH HOLD to be usable after the commit.

CALLED ON NULL INPUT

Specifices that the stored procedure will be called even if any of the input arguments is null, making the procedure responsible for testing for null argument values. The result is the null value.

Note:

Changes are immediate: Any changes that the ALTER PROCEDURE statement cause to the definition of a procedure take effect immediately.

The changed definition is used the next time that the procedure is called.

Restrictions for nested stored procedures: A stored procedure, user-defined function, or trigger cannot call a stored procedure that is defined with the COMMIT ON RETURN clause.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

Example:

Assume that stored procedure SYSPROC.MYPROC is currently defined to run in WLM environment PARTSA and that you have appropriate authority on that WLM environment and WLM environment PARTSEC. Change the definition of the stored procedure so that it runs in PARTSEC.

ALTER PROCEDURE SYSPROC.MYPROC WLM ENVIRONMENT PARTSEC;
Parent topic: SQL Statements


ALTER PROCEDURE (SQL)

The XDB Server operating environment only provides syntax support for external Procedures (SQL) at this time.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER PROCEDURE command, users must possess either overall SYSADM or SYSCTRL authority for the location, or be the owner of the stored procedure affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER PROCEDURE procedure-name
    [DYNAMIC RESULT {SET | SETS} integer]
    [EXTERNAL NAME {'string' | identifier}]
    [{DETERMINISTIC | NOT DETERMINISTIC}]
    [{CONTAINS SQL | READS SQL DATA | MODIFIES SQL DATA}]
    [{NO COLLID | COLLID collection-id}]
    [{WLM ENVIRONMENT {name | (name,*)}} | NO WLM ENVIRONMENT}]
    [ASUTIME {NO LIMIT | LIMIT integer}]
    [STAY RESIDENT {NO | YES}]
    [PROGRAM TYPE {SUB | MAIN}]
    [SECURITY {DB2 | USER | DEFINER}]
    [RUN OPTIONS run-time-options]
    [COMMIT ON RETURN {NO | YES}]
    [INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
    [{STOP AFTER SYSTEM DEFAULT FAILURES |
     STOP AFTER integer FAILURES |
     CONTINUE AFTER FAILURE}]

Description

procedure-name

Identifies the stored procedure to be altered. The name is implicitly or explicitly qualified by a schema name. If the name is not explicitly qualified, it is implicitly qualified with a schema name according to the following rules.

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

DYNAMIC RESULT SET integer or DYNAMIC RESULT SETS integer

Specifies the maximum number of query result sets that the stored procedure can return. The value must be between 0 and 32767.

EXTERNAL NAME 'string' or identifier

Specifies the name of the MVS load module for the program that runs when the procedure name is specified in an SQL CALL statement. The value must conform to the naming conventions for MVS load modules: the value must be less than or equal to 8 bytes, and it must conform to the rules for an ordinary identifier with the exception that it must not contain an underscore.

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the stored procedure returns the same result from successive calls with identical input arguments.

NOT DETERMINISTIC | The stored procedure might not return the same result from successive calls with identical input arguments.
DETERMINISTIC | The stored procedure returns the same result from successive calls with identical input arguments. XDB does not verify that the stored procedure code is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL DATA

Indicates whether the stored procedure can execute any SQL statements and, if so, what type.

MODIFIES SQL DATA | The stored procedure can execute any SQL statement except those statements that are not supported in any stored procedure.
READS SQL DATA | The stored procedure cannot execute SQL statements that modify data. SQL statements that are not supported in any stored procedure return a different error.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any stored procedure return a different error

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the stored procedure is executed.

NO COLLID | The package collection for the stored procedure is the same as the package collection of the program that invokes the stored procedure. If a trigger invokes the stored procedure, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the stored procedure is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of a stored procedure can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a stored procedure, setting a limit can be helpful in case the stored procedure gets caught in a loop.

NO LIMIT | There is no limit on the service units.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2 GB. If the stored procedure uses more service units than the specified value, the stored procedure is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the stored procedure load module remains resident in memory when the stored procedure ends.

NO | The load module is deleted from memory after the stored procedure ends.
YES | The load module remains resident in memory after the stored procedure ends.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the stored procedure runs as a main routine or a subroutine.

SUB | The stored procedure runs as a subroutine.
MAIN | The stored procedure runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

COMMIT ON RETURN

Indicates whether XDB commits the transaction immediately on return from the stored procedure.

NO XDB does not issue a commit when the stored procedure returns.
YES XDB issues a commit when the stored procedure returns if the following statements are true:
  • The SQLCODE that is returned by the CALL statement is not negative.
  • The stored procedure is not in a must abort state.

The commit operation includes the work that is performed by the calling application process and the stored procedure.

If the stored procedure returns result sets, the cursors that are associated with the result sets must have been defined as WITH HOLD to be usable after the commit.

Note:

Any changes that the ALTER PROCEDURE statement cause to the definition of a procedure take effect immediately.

The changed definition is used the next time that the procedure is called.

A stored procedure, user-defined function, or trigger cannot call a stored procedure that is defined with the COMMIT ON RETURN clause.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

Example:

Modify the definition for an SQL procedure so that SQL changes are committed on return from the SQL procedure and the SQL procedure runs in the WLM environment named WLMSQLP.

 ALTER PROCEDURE UPDATE_SALARY_1
    COMMIT ON RETURN YES
    WLM ENVIRONMENT WLMSQLP;
Parent topic: SQL Statements


ALTER SEQUENCE

The ALTER SEQUENCE statement changes the attributes of a sequence at the current server. Only future values of the sequence are affected by the ALTER SEQUENCE statement.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set that is defined below must include at least one of the following:

  • Ownership of the sequence
  • The ALTER privilege for the sequence
  • The ALTERIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the ALTERIN privilege on the schema.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process.

Syntax

ALTER SEQUENCE sequence-name {RESTART [WITH numeric-constant] |
     INCREMENT BY numeric-constant |
     {MINVALUE numeric-constant | NO MINVALUE} |
     {MAXVALUE numeric-constant | NO MAXVALUE} |
     {CYCLE | NO CYCLE} |
     {CACHE integer-constant | NO CACHE} |
     {ORDER | NO ORDER}
     } [...]

Description

SEQUENCE sequence-name
Identifies the sequence. The combination of sequence name and the implicit or explicit qualifier must identify an existing sequence at the current server. sequence-name must not identify a sequence that is generated by the system for an identity column.
RESTART
Restarts the sequence. If numeric-constant is not specified, the sequence is restarted at the value specified implicitly or explicitly as the starting value on the CREATE SEQUENCE statement that originally created the sequence.
WITH numeric-constant
Specifies the value at which to restart the sequence. The value can be any positive or negative value that could be assigned to a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point.

If RESTART is not specified, the sequence is not restarted. Instead, it resumes with the current values in effect for all the options after the ALTER statement is issued.

After a sequence is restarted or changed to allow cycling, sequence numbers may be duplicates of values generated by the sequence previously.

INCREMENT BY numeric-constant
Specifies the interval between consecutive values of the sequence. The value can be any positive or negative value (including 0) that could be assigned to a column of the data type that is associated with the sequence without any non-zero digits existing to the right of the decimal point. The default is 1.

If INCREMENT BY numeric-constant is positive, the sequence ascends. If INCREMENT BY numeric-constant is negative, the sequence descends. If INCREMENT BY numeric-constant is 0, the sequence is treated as an ascending sequence.

The absolute value of INCREMENT BY can be greater than the difference between MAXVALUE and MINVALUE.

NO MINVALUE
Specifies that the minimum end point of the range of values for the sequence has not been specified explicitly. In such a case, the value for MINVALUE becomes one of the following:
  • For an ascending sequence, the value is the original starting value.
  • For a descending sequence, the value is the minimum of the data type that is associated with the sequence.
MINVALUE MINVALUEnumeric-constant
Specifies the minimum value at which a descending sequence either cycles or stops generating values, or an ascending sequence cycles to after reaching the maximum value. The last value that is generated for a cycle of a descending sequence will be equal to or greater than this value. MINVALUE is the value to which an ascending sequence cycles to after reaching the maximum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

NO MAXVALUE
Specifies either explicitly or implicitly that the minimum end point of the range of values for the sequence has not be set. In such a case, the default value for MAXVALUE becomes one of the following:
  • For an ascending sequence, the value is the maximum value of the data type that is associated with the sequence
  • For a descending sequence, the value is the original starting value.

If NO MAXVALUE is explicitly specified in the ALTER SEQUENCE statement, the value of the MAXVALUE column in the catalog table is reset to the maximum value of the data type associated with the sequence if the sequence is ascending or the value stored in the START column of the catalog table if the sequence is descending. Whether the sequence is ascending or descending depends on whether or not the INCREMENT BY option is reset. If it is, the new INCREMENT BY VALUE determines if the sequence is ascending or descending. If it is not explicitly reset, the value stored in the INCREMENT column of the catalog table determines if the sequence is ascending or descending.

MAXVALUE numeric-constant
Specifies the maximum value at which an ascending sequence either cycles or stops generating values or a descending sequence cycles to after reaching the minimum value. The last value that is generated for a cycle of an ascending sequence will be less than or equal to this value. MAXVALUE is the value to which a descending sequence cycles to after reaching the minimum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

CYCLE

Specifies that the sequence continue to generate values after either the maximum or minimum value has been reached. If this option is used, after an ascending sequence reaches its maximum value, it generates its minimum value. After a descending sequence reaches its minimum value, it generates its maximum value. The maximum and minimum values for the sequence defined by the MINVALUE and MAXVALUE options determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by the sequence. When a sequence is defined with CYCLE, any application conversion tools for converting applications from other vendor platforms to DB2 should also explicitly specify MINVALUE, MAXVALUE, and START WITH values.

NO CYCLE
Specifies that the sequence cannot generate more values once the maximum or minimum value for the sequence has been reached.
NO CACHE
Specifies that values of the sequence are not to be preallocated. This option ensures that there is not a loss of values in the case of a system failure. When NO CACHE is specified, the values of the sequence are not stored in the cache. In this case, every request for a new value for the sequence results in synchronous I/O.
CACHE integer-constant
Specifies the maximum number of sequence values that XDB can preallocate and keep in memory. Preallocating values in the cache reduces synchronous I/O when values are generated for the sequence. The actual number of values that XDB caches is always the lesser of the number in effect for the CACHE option and the number of remaining values within the logical range. Thus, the CACHE value is essentially an upper limit for the size of the cache.

In the event of a system failure, all cached sequence values that have not been used in committed statements are lost (that is, they will never be used). The value specified for the CACHE option is the maximum number of sequence values that could be lost in case of system failure.

The minimum value is 2.

In a data sharing environment, you can use the CACHE and NO ORDER options to allow multiple XDB members to cache sequence values simultaneously.

NO ORDER
Specifies that the sequence numbers do not need to be generated in order of request.
ORDER
Specifies that the sequence numbers are generated in order of request. Specifying ORDER may disable the caching of values. There is no guarantee that values are assigned in order across the entire server unless NO CACHE is also specified. ORDER applies only to a single-application process.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for next value assignments from different members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the same sequence, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested for next value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that sequence numbers are generated in strict numeric order among multiple members using the same sequence concurrently, specify the ORDER option.

Comments:

  • The changes to the attributes of a sequence take effect after the ALTER SEQUENCE statement is committed. If the ALTER SEQUENCE request results in an error or is rolled back, nothing is changed; however, unused cache values may be lost. You cannot use the ALTER SEQUENCE statement to change the data type of a sequence. To change the data type, drop the sequence and recreate it. Altering a sequence may cause unused cache values to be lost.
  • To provide compatibility with previous releases, XDB supports the following keywords:
    • NOCACHE (single key word) as a synonym for NO CACHE
    • NOCYCLE (single key word) as a synonym for NO CYCLE
    • NOMINVALUE (single key word) as a synonym for NO MINVALUE
    • NOMAXVALUE (single key word) as a synonym for NO MAXVALUE
    • NOORDER (single key word) as a synonym for NO ORDER
Parent topic: SQL Statements


ALTER STOGROUP

The ALTER STOGROUP statement changes the specifications of an existing storage group (stogroup) defined within the current XDB Server location.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute this command, users must either be the owner of the referenced stogroup, or possess SYSADM or SYSCTRL authority for the location.

Syntax

ALTER STOGROUP stogroup-name
    [PASSWORD password]
    [ADD VOLUMES (volume-id[,...])]
    [REMOVE VOLUMES (volume-id[,...])]

Parameters:

stogroup-name | Identifies the stogroup to be altered. The stogroup identified must exist within the currently set XDB Server location.
volume-id | Refers to the volume serial number of a mainframe storage volume.

Description

ALTER STOGROUP allows users to add and remove logical volume ID designations from an existing stogroup. The XDB Server also records any mainframe assigned password in the location catalog tables (DB2 mode).

PASSWORD

This option is utilized in the mainframe-DB2 environment. Any password parameter values are recorded in the catalog tables for the current XDB Server location.

ADD VOLUMES (volume-id,...) or ADD VOLUMES('*',...)

XDB records the volumes added to a stogroup in the catalog tables for that location. One or more volume-id numbers (corresponding to volume serial numbers) can be specified in this clause, each with a maximum of six characters (specified as an identifier or a string constant).

A volume-id must not be specified if any volume of the storage group is designated by an asterisk (*). An asterisk must not be specified if any volume of the storage group is designated by a volume-id.

You cannot add a volume that is already in the storage group unless you first remove it with REMOVE VOLUMES.

REMOVE VOLUMES (volume-id,...) or REMOVE VOLUMES('*',...)

XDB Server can associate up to 133 volumes with one stogroup. The REMOVE VOLUMES option removes one or more volumes (identified by volume-id) associated with the storage group. The XDB Server applies the REMOVE VOLUMES clause to the current list of stogroup volumes, before applying any ADD VOLUMES clauses.

Parent topic: SQL Statements


ALTER TABLE

The ALTER TABLE statement changes the description of a table at the current server.
Restriction: This topic applies to Windows environments only.

Altering the structure of a table may require a time consuming reorganization of the table. The original table is not recoverable; take care when using this command. ALTER TABLE (in XDB mode and DB2 mode) alters the structure of an existing table. Use ALTER TABLE to add new columns, and create and drop integrity constraints.

In XDB mode, the ALTER TABLE command includes the following additional options: delete, rename and modify existing columns, add and drop unique keys and check conditions, and specify any parent table unique key (also called a candidate key) when adding a foreign key reference.

ALTER TABLE clauses can add and drop check constraints, along with WITH RESTRICT ON DROP clauses. Columns with user-defined defaults or check constraints can also be added.

Invocation

This statement can be embedded in an application program or issued interactively.

The ALTER TABLE command can be dynamically prepared (PREPARE command).

Authorization

To execute an ALTER TABLE statement, users must possess either DBADM authority on the database, the ALTER privilege on the table being altered, overall SYSADM or SYSCTRL authority for the location, or ownership of the table affected. If a FOREIGN KEY clause is included in the ALTER TABLE statement, the user must possess the ALTER privilege on the parent table.

Additional privileges might be required in the following cases:

  • FOREIGN KEY, DROP PRIMARY KEY, DROP FOREIGN KEY, or DROP CONSTRAINT is specified
  • the data type of a column that is added to the table is a distinct type
  • A fullselect is specified
  • A column is defined as a security label column

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER TABLE table-name
    [ALTER [COLUMN] column-alteration | partition-alteration]
                ROTATE partition-rotation

    [ADD column-definition]
                [VALIDPROC {program-name | NULL}]
    [AUDIT {NONE | CHANGES | ALL}]
    [[ADD] PRIMARY KEY key-name (column-list)]
    [ADD check-constraint]
                [ADD add-partition]
                [ADD partitioning-clause]
    [DROP CHECK constraint-name]
    [[ADD] referential-constraint]
    [DATA CAPTURE {NONE | CHANGES}]
                [{VOLATILE | NOT VOLATILE} [CARDINALITY]]
    [DROP PRIMARY KEY]
    [DROP FOREIGN KEY constraint-name]
    [DROP CONSTRAINT constraint-name]
    [{ADD | DROP} RESTRICT ON DROP]
{
    | DELETE column-name[,...]
    | RENAME old-column-name new-column-name[,...]
    | MODIFY column-name column-type [FOR BIT DATA]
        [NOT NULL [WITH DEFAULT]] [,...]
    | UNIQUE KEY key-name (column-list)
    | FOREIGN KEY [constraint-name] (column-list)
        REFERENCES referenced-table [key-name]
        [ON UPDATE {RESTRICT | CASCADE| SET NULL}]
    | DROP KEY key-name
    | CHECK (search-condition)
    | DROP CHECK
    | ADD [[MATERIALIZED] QUERY] materialized-query-definition
    | DROP [MATERIALIZED] QUERY
    | ALTER [MATERIALIZED] QUERY materialized-query-definition
                }

column-alteration:

[COLUMN] column-name
 {SET DATA TYPE altered-data-type |
                generation-alteration |
  [generation-alteration] identity-alteration}

altered-data-type

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...] | (5,0)] |
{FLOAT [integer | 53] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer) | (1)] |
  {CHARACTER | CHAR} VARYING (integer) |
  VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA]  |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G]) | (1M)] }
[FOR {SBCS | MIXED} DATA] } |
{GRAPHIC [(integer) | (1M)] | VARGRAPHIC (integer)

generation-alteration

SET GENERATED {ALWAYS | BY DEFAULT}

partition-rotation:

PARTITION FIRST TO LAST ENDING [AT] (constant[,...]) [INCLUSIVE] RESET

materialized-query-definition:

(fullselect) refreshable-table-options

refreshable-table-options:

DATA INITIALLY DEFERRED REFRESH DEFERRED
[MAINTAINED BY SYSTEM | MAINTAINED BY USER]
[ENABLE QUERY OPTIMIZATION | DISABLE QUERY OPTIMIZATION]

referential-constraint:

FOREIGN KEY [constraint-name] (column-name[,...]
REFERENCES referenced-table [column-name ,...]
[ON DELETE {RESTRICT | CASCADE | SET NULL | NO ACTION}]

references-clause:

REFERENCES referenced-table
    [column-name ,...]
    [ON DELETE {RESTRICT | CASCADE | SET NULL | NO ACTION}]
    [ENFORCED | NOT ENFORCED]
    [ENABLE QUERY OPTIMIZATION]

check-constraint:

[CONSTRAINT constraint-name] CHECK (check-condition)

add-partition:

PARTITION ENDING [AT] (constant) [,...] [INCLUSIVE]

partitioning-clause:

PARTITION BY [RANGE] (partition-expression[,...]) (partition-element[,...])

partition-expresion:

                column-name [NULLS LAST] [ASC | DESC]

partition-element:

PARTITION integer ENDING [AT] (constant[,...]) [INCLUSIVE]

partition-alteration:

PARTITION integer ENDING [AT] (constant[,...]) [INCLUSIVE]

column-definition:

column-name data-type
    [NOT NULL]
    [FOR {BIT | SBCS | MIXED} DATA]
    [default-clause]
    [GENERATED {ALWAYS | BY DEFAULT} [as-identity-clause]]
    [references-clause]
    [check-constraint]
                [FIELDPROC program-name [(constant[,...])]]
    [AS SECURITY LABEL]

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT | {INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
                {BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

default-clause:

[WITH] DEFAULT [{constant | USER | CURRENT SQLID | NULL | cast-function-name ({constant |
   USER | CURRENT SQLID | NULL})}]

as-identity-clause:

AS IDENTITY
    [({START WITH {numeric-constant | 1}
     | INCREMENT BY {numeric-constant | 1}
     | {MINVALUE numeric-constant | NO MINVALUE} |
     | {MAXVALUE numeric-constant | NO MAXVALUE} |
     | {CYCLE | NO CYCLE} |
     | {CACHE 20 | NO CACHE | CACHE integer}}
     | [ORDER | NO ORDER] ])[,..]]

Parameters

table-name | Identifies the table to be altered. The name must identify a table that exists at the current server. The name must not identify an auxiliary table, declared temporary table, or view. If the name identifies a catalog table, DATA CAPTURE CHANGES is the only clause that can be specified.
column-name | Identifies a column in the table.
column-type Identifies a valid XDB Server column data type. Valid data types are detailed in Basic Concepts. If the column data type is CHAR or VARCHAR, and no character length is specified when altering (or creating) the table, a default character length of one becomes part of the column type specification. If the column type is DECIMAL, precision and scale may also be specified (default is 5,0).

FOR BIT DATA is an optional keyword for CHAR, VARCHAR, and LONG VARCHAR data columns. The presence of these keywords indicates that the contents of the column data values are to be treated as bit (binary) data. This option is important for COBOL programming that uses character and variable character fields to store integers, structures, etc. If not specified as FOR BIT DATA, the column is assumed (by default) to contain ASCII characters. Default character modes (such as EBCDIC) are set using the CREATE LOCATION statement. Note that the FOR BIT DATA keywords must precede any NULL specification for that column.

NOT NULL is an optional instruction that prevents the column from containing null values.

NOT NULL WITH DEFAULT prevents columns from containing null values. When an attempt is made to place a NULL value in a column field, a default value depending on the data type is inserted instead.

key-name | Designates an original name for a UNIQUE KEY.
column-list Identifies one or more columns (separated by commas) on which the key is created. Up to 64 columns can be included in a key constraint. For information on the total character (or byte) limitations of an XDB Server key constraint (or index), see the CREATE INDEX statement.

When establishing a PRIMARY KEY, a unique index must already be created on the table. The PRIMARY KEY constraint must contain the same column names, in the same order, as the unique index. If these requirements are met, the unique index is transformed into the PRIMARY KEY for that table.

constraint-name Identifies a FOREIGN KEY constraint. If a constraint name is not specified in the command, the system generates a constraint name by taking the first eight characters of the first column name, and checking for uniqueness. If these characters are not unique, the XDB Server adds a number to the first seven characters of the first column name. If still not unique, then two numbers are added to the first six characters, etc. -- until the new constraint name becomes unique among all constraint names for that table.

Also defines a table CHECK constraint within the CONSTRAINT...CHECK clause, and constraints within the DROP FOREIGN KEY, DROP CONSTRAINT and DROP CHECK clauses. The constraint-name is an SQL long identifier. A constraint-name cannot be specified more than once for the same table. (See the CONSTRAINT, DROP CONSTRAINT, DROP CHECK, and DROP keywords.)

check-condition | Can consist of a single predicate, or two or more predicates joined by AND or OR. The first operand of each predicate must be the name of a column of the table. The second operand can be a column name or a constant. A check-condition can evaluate to unknown if a column that is an operand of the predicate is null. A check-condition that evaluates to unknown does not violate the check constraint (see CHECK clause).
referenced-table Identifies the parent table referenced by the FOREIGN KEY clause. ON DELETE tells the XDB Server how to handle dependent records in the referencing table when an attempt is made to delete a referenced record in the parent table. The RESTRICT option (default) prevents the referenced record from being deleted from the parent table.

The CASCADE option deletes the dependent records from the referencing table, and also deletes the parent record. The SET NULL option causes the FOREIGN KEY data values in the dependent records to be set to NULL before the parent record is deleted.

search-condition | Represents any search condition, except a join condition or a subselect.

Description

In XDB mode, only one optional clause can be included in any ALTER TABLE statement. For example, one ALTER TABLE command might ADD one or more columns, while another ALTER TABLE command could DELETE one or more columns. In DB2 mode, multiple clauses can be included in each ALTER TABLE statement, as long as the same clause is not specified more than once. Information contained in the VALIDPROC, AUDIT and DATA CAPTURE clauses is recorded in the XDB Server catalog tables for the current location, but is not otherwise used by the XDB Server. These clauses are operational when used against a DB2 database through XDB Link.

ALTER COLUMN column-alteration

Alters the definition of an existing column, including the attributes of an existing identity column. Only the attributes specified are altered. Other attributes remain unchanged. Only future values of the column are affected by the changes made with an ALTER TABLE ALTER COLUMN statement.

The table being altered must not be in an incomplete state because of a missing unique index on a unique constraint (primary or unique key). A column can only be referenced once in an ALTER COLUMN clause in a single ALTER TABLE statement. However, that same column can be referenced multiple times for adding or dropping constraints in the same ALTER TABLE statement. An ALTER TABLE ALTER COLUMN statement may not be processed in the same unit of work as an INSERT, DELETE, or UPDATE statement. A column cannot be altered if the table is used in a materialized query table definition or if the table is a materialized query table.

You can modify all the attributes of an existing identity column, except for the data type of the column. To change the data type of an identity column, drop the table containing the column and recreate it.

column-name Identifies the column to be altered. The name must not be qualified and must identify an existing column in the table being altered when the ALTER statement is processed. The column must not be part of a referential constraint or have a field procedure. The column must not be defined as a security label column. When the attributes of an identity column are altered, the column of the specified column-name must exist in the specified table and must have been defined with the IDENTITY attribute.
SET DATA TYPE (altered-data-type) Specifies the new data type of the column to be altered. For a character or CLOB column, you can also use the clause to change the definition of the subtype that is stored in the XDB catalog and OBD.The column cannot be an identity column. The new data type must be compatible with the existing data type of the column. The existing data type of the column cannot be a ROWID, LOB, date, time, timestamp, or distinct type.

If the data type is a character or graphic string, the new length attribute must be at least as large as the existing length attribute of the column. If the data type is a numeric data type, the specified precision and scale must be at least as large as the existing precision and scale. If a decimal fraction is being converted to floating point, the ALTER statement will fail if there is a unique index or a unique constraint on the column.

If the specified column has a default value, the existing default value must represent a value that could be assigned to a column with the new data type in accordance with the rules for assignment. The default value is updated to reflect the new data type.

If the column is specified in a unique constraint (unique key or primary key) or unique index, the new column length must not exceed the limit on an index size. For PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000-n, where n is the number of columns that can contain null values. For NOT PADDED indexes, the sum of the length attributes of the columns must not be greater than 2000-n-2m, where n is the number of nullable columns and m is the number of varying length columns.

The total byte count of columns after the alteration must not exceed the maximum row size. If the column is in the partitioning key, the new partitioning key cannot exceed 255-n.

The following numeric data type alterations are supported for SET DATA TYPE:

The following character data type alterations are supported for SET DATA TYPE:

When columns are converted from CHAR to VARCHAR, normal assignment rules apply, which means that trailing blanks are kept instead of being stripped out. If you want varying length character strings without trailing blanks, use the STRIP function for data in the column after changing the data type to VARCHAR.

If the table being altered has an edit procedure or valid procedure, an error occurs. If a materialized query table is defined on this table or if this table is defined as being a materialized query table, then an error also occurs.

The table space that contains the table being altered is left in an advisory REORG-pending (AREO) status. If the column being altered is part of an index, an exception state may be set for the index as shown in the table below:

The length of more than one column can be changed in a single ALTER TABLE statement if each ALTER COLUMN clause identifies a unique column of the table. The ALTER COLUMN clause and ADD CHECK CONSTRAINT clause can identify the same column.

ADD column-definition

Adds a column to the table. Except for a ROWID column and an identity column, all values of the column in existing rows are set to its default value. If the table has n columns, the ordinality of the new column is n+1. The value of n cannot be greater than 749. For a dependent table, n cannot be greater than 748.

The column cannot be added if the increase in the total byte count of the columns exceeds the maximum row size. The maximum row size for the table is eight less than the maximum record size. A column also cannot be added to a table that has an edit procedure.

If you add a LOB column and the table does not already have a ROWID column, XDB creates a hidden ROWID column. You cannot add a LOB or ROWID column to a created temporary table.

You cannot add an identity column to a table that has an identity column or to a created temporary table.

column-name | Is the name of the column you want to add to the table. Do not use the name of an existing column of the table. Do not qualify column-name.
built-in-data-type | Specifies the data type of the column is one of the built-in data types.
distinct-type-name | Specifies the distinct type (user-defined data type) of the column. User-defined data types are not yet supported by the XDB Server operating environment.

NOT NULL

Prevents the column from containing null values. If NOT NULL is specified, the DEFAULT clause must be used to specify a nonnull default value for the column unless the column has a row ID data type or is an identity column. For a ROWID column, NOT NULL must be specified, and DEFAULT must not be specified. For an identity column, although NOT NULL can be specified, DEFAULT must not be specified

For example, the ALTER statement below adds three new data columns to the SUPPLIER table:

ALTER TABLE supplier
    ADD state CHAR 2, zip CHAR 5,
        founded DATE NOT NULL WITH DEFAULT

To disallow NULL values in a new column, first add data to the column, and then issue another ALTER TABLE statement with the MODIFY clause to specify the column as NOT NULL.

DEFAULT

The default value assigned to the column in the absence of a value specified on INSERT or LOAD. Do not specify DEFAULT for a ROWID column, an identity column (a column that is defined AS IDENTITY) or a security label column (a column that is defined AS SECURITY LABEL); XDB generates default values. If a value is not specified after the DEFAULT keyword and the column is not nullable, the default value depends on the data type of the column.

Data Type | Default Value
numeric | 0
date | current date
time | current time
timestamp | current date and time
character | Blanks
Varchar | Blanks
graphic | Blanks

For example, if you want to record the identity of anyone inserting rows into a table, define the table with two additional columns:

PRIMARY_ID

CHAR(8)

WITH DEFAULT USER,

SQL_ID

CHAR(8)

WITH DEFAULT CURRENT SQLID,

You can allow updates and inserts to the table only through a view that omits those columns. Then, the primary authorization ID and the SQLID of the process are added by default.

constant

Specifies a constant as the default value for the column. The value of the constant must conform to the rules for assigning that value to the column.

A character or string constant must be short enough so that its UTF-8 representation requires no more than 1536 bytes. In addition, a hexadecimal graphic string (GX) constant cannot be specified.

USER

Specifies the value of the USER special register at the time of INSERT or LOAD as the default for the column. If USER is specified, the data type of the column must be a character string with a length greater than or equal to the length attribute of the USER special register. For existing rows, the value is that of the USER special register at the time the ALTER TABLE statement is processed.

CURRENT SQLID

Specifies the value of the SQL authorization ID of the process at the time of INSERT or LOAD as the default for the column. If CURRENT SQLID is specified, the data type of the column must be a character string with a length greater than or equal to the length attribute of the CURRENT SQLID special register. For existing rows, the value is the SQL authorization ID of the process at the time the ALTER TABLE statement is processed.

NULL

Specifies null as the default value for the column.

cast-function-name

The XDB Server operating environment does not currently provide this functionality.

GENERATED

Indicates that XDB generates values for the column. GENERATED is applicable only to ROWID columns and identity columns. If the data type of the column is a ROWID (or a distinct type that is based on a ROWID), the default is GENERATED ALWAYS.

ALWAYS Indicates that XDB will generate a value for the column when a row is inserted into the table. ALWAYS is the recommended value unless you are using data propagation.

If you specify ALWAYS, you must not specify a value for the column when a row is inserted into the table. Also, you cannot update the value of the column

BY DEFAULT Indicates that XDB will generate a value for the column when a row is inserted unless a value is specified.into the table only if a value is not specified. Otherwise, XDB uses the value that you specify.

For a ROWID column, XDB uses a specified value only if it is a valid row ID value that was previously generated by XDB and the column has a unique, single-column index. Until this index is created on the ROWID column, the SQL INSERT statement and the LOAD utility cannot be used to add rows to the table. If the value of special register CURRENT RULES is 'STD' when the ALTER TABLE statement is processed, XDB implicitly creates the index on the ROWID column. The name of this index is 'I' followed by the first ten characters of the column name followed by seven randomly generated characters. If the column name is less than ten characters, XDB adds underscore characters to the end of the name until it has ten characters. The implicitly created index has the COPY NO attribute.

For an identity column, XDB inserts a specified value but does not verify that it is a unique value for the column unless the identity column has a unique, single-column index; without a unique index, XDB can guarantee unique values only among the set of system-generated values.

BY DEFAULT is the recommended value only when you are using data propagation.

AS SECURITY LABEL

Indicates that the table is defined with multilevel security with row level granularity and specifies that the column will contain the security label values. A table can have only one security label column. To define a table with a security label column, the primary authorization ID of the statement must have a valid security label, and the RACF SECLABEL class must be active. In addition, the following conditions are also required:

  • The data type of the column must be CHAR(8).
  • The subtype of the column must be SBCS.
  • The column does not have any field procedures, check constraints, or referential constraints.
  • The column must be defined as NOT NULL and WITH DEFAULT clauses.
  • The table does not have an edit procedure.
  • The table is not the source table for a materialized query table.
  • You are using z/OS Version 1 Release 5 or later.

For existing rows in the table, the value of the security label column defaults to the security label of the user at the time the ALTER statement is executed.

AS IDENTITY

Specifies that the column is an identity column for the table. A table can have only one identity column. AS IDENTITY can be specified only if the data type for the column is an exact numeric type with a scale of zero (SMALLINT, INTEGER, DECIMAL with a scale of zero, or a distinct type based on one of these types). Separator commas between identity column attribute specifications are optional when the identity column is defined.

An identity column is implicitly NOT NULL. When adding an identity column to a table, you must also specify GENERATED ALWAYS or GENERATED BY DEFAULT.

START WITH numeric-constant | Specifies the first value for the identity column. The value can be any positive or negative value that could be assigned to the column without non-zero digits exisitng to the right of the decimal point. The default is 1.
INCREMENT BY numeric-constant | Specifies the interval between consecutive values of the identity column. The value can be any positive or negative value (including 0) that does not exceed the value of a large integer constant and could be assigned to the column without any non-zero digits existing to the right of the decimal point. The default is 1. If the value is positive, the sequence of values for the identity column ascends. If the value is negative, the sequence of values descends.

MINVALUE or NO MINVALUE

Specifies the minimum value at which a descending identity column either cycles or stops generating values or an ascending identity column cycles to after reaching the maximum value.

NO MINVALUE

Specifies that the minimum end point of the range of values for the identity column has not been specified explicitly. In such a case, the value for MINVALUE becomes one of the following:

  • For an ascending identity column, the value is the START WITH value or 1 if START WITH was not specified.
  • For a descending identity column, the value is the minimum value of the data type of the column.

MINVALUE numeric-constant

Specifies the numeric constant that is the minimum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

MAXVALUE or NO MAXVALUE

Specifies the maximum value at which a ascending identity column either cycles or stops generating values or a descending identity column cycles to after reaching the minimum value.

NO MAXVALUE

Specifies that the minimum end point of the range of values for the identity column has not be set. In such a case, the default value for MAXVALUE becomes one of the following:

  • For an ascending identity column, the value is the maximum value of the data type of the column.
  • For a descending identity column, the value is the START WITH value or -1 if START WITH is not specified.

MAXVALUE numeric-constant

Specifies the numeric constant that is the maximum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

NO CYCLE or CYCLE

Specifies whether this identity column should continue to generate values after reaching either its maximum or minimum value.

NO CYCLE

Specifies that values will not be generated for the identity column after the maximum or minimum value has been reached. This is the default.

CYCLE

Specifies that values continue to be generated for this column after the maximum or minimum value has been reached. If this option is used, after an ascending identity column reaches the maximum value, it generates its minimum value. After a descending identity column reaches its minimum value, it generates its maximum value. The maximum and minimum values for the identity column determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by XDB for an identity column. However, if a unique index exists on the identity column and a non-unique value is generated for it, an error occurs.

CACHE or NO CACHE

This clause has no functional equivalent in the XDB Server operating environment.

NO ORDER or ORDER

Specifies whether the sequence numbers must be generated in order of request.

NO ORDER

Specifies that the values do not need to be generated in order of request.

ORDER

Specifies that the values are generated in order of request. Specifying ORDER may disable the caching of values. ORDER applies only to a single-application process.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for identity values from different XDB members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the identity column, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested a value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that identity values are generated in strict numeric order among multiple XDB members using the same identity column, specify the ORDER option.

REFERENCES

The references portion of the referential-constraint clause is a separate clause. A single column can be identified as a foreign key of a referential constraint by using the references-clause in a column definition.

Do not specify references-clause in the definition of a LOB, ROWID column, or security label column because a LOB, ROWID, or security label column cannot be a foreign key.

The parent key of the referential constraint is composed of the identified columns. The identified column cannot be a LOB, ROWID, or security label column. The same column must not be identified more than once.

Define a key that consists of more than one column by listing the column names. A foreign key can reference a unique key or a primary key. When a foreign key refers to a nonprimary unique key, you must specify the columns of the key.

If the foreign key includes a column defined as a distinct type, the corresponding column of the nominated parent key must be the same distinct type. If a column of the foreign key has a field procedure, the corresponding column of the nominated parent key must have the same field procedure and an identical field description. A field description is a description of the encoded value as it is stored in the database for a column that has been defined to have an associated field procedure.

ENFORCED or NOT ENFORCED

Indicates whether or not the referential constraint is enforced by the database manager during normal operations, such as insert, update, or delete.

ENFORCED

Specifies that the referential constraint is enforced by the database manager during normal operations (such as insert, update, or delete) and that it is guaranteed to be correct. This is the default.

NOT ENFORCED

Specifies that the referential constraint is not enforced by the database manager during normal operations, such as insert, update, or delete. This option should only be used when the data that is stored in the table is verified to conform to the constraint by some other method than relying on the database manager.

ENABLE QUERY OPTIMIZATION

Specifies that the constraint can be used for query optimization. XDB uses the information in query optimization using materialized query tables with the assumption that the constraint is correct. This is the default.

ADD RESTRICT ON DROP

Indicates that the table cannot be dropped. Also, the database and table space that contain the table cannot be dropped.

DROP RESTRICT ON DROP

Removes the restriction on dropping the table and the database and table space that contain the table.

CONSTRAINT

Names a table check constraint. If a constraint-name is not specified, a unique constraint name is derived from the name of the first column in the check-condition specified in the definition of the table check constraint.

Do not specify a check constraint in the definition of a LOB, ROWID, or security label column.

DROP CONSTRAINT

Drops the constraint constraint-name. The constraint-name must identify an existing check constraint or referential constraint defined on the table.

CHECK

Table check constraints can be defined on individual columns within both the CREATE TABLE and ALTER TABLE command statements. The check constraint is the check condition that defines the values that designated columns of the table can contain.

Do not specify a table check constraint in the definition of a ROWID column.

ADD PARTITION

Specifies that a partition is added to the table and each partitioned index on the table. The new partition is the next physical partition not being used until the maximum for the table space has been reached. ADD PARTITION must not be specified for nonpartitioned tables. If the table uses index-controlled partitioning, it is converted to use table-controlled partitioning.

The maximum number of partitions allowed depends on how the table space was originally created. If DSSIZE was specified when the table space was created, it is non-zero in the catalog. The maximum number of partitions allowed is shown in the following table.

DSSIZE | Page size 4Kb | Page size 8 Kb | Page size 16 Kb | Page size 32 Kb
1-4 Gb | 4096 | 4096 | 4096 | 4096
8 Gb | 2048 | 4096 | 4096 | 4096
16 Gb | 1024 | 2048 | 4096 | 4096
32 Gb | 512 | 1024 | 2048 | 4096
64 Gb | 256 | 512 | 1024 | 4096

If LARGE was specified when the table space was created, the maximum number of partitions is shown in the fourth row of the following table. For more than 254 partitions when LARGE or DSSIZE is not specified, the maximum number of partitions is determined by the page size of the table space.

Type of table space | Number of existing partitions | Maximum partitions
non-large | 1-16 | 16
non-large | 17-32 | 32
non-large | 33-64 | 64
large | N/A | 4096

The existing table space PRIQTY and SECQTY attributes of the previous logical partition are used for the space attributes of the new partition. For each partitioned index, the existing PRIQTY and SECQTY attributes of the previous partition are used.

To specify specific space attributes for the new partition, use additional ALTER TABLESPACE and ALTER INDEX statements.

Adding a partition is not allowed if the table is a materialized query table or a materialized query table is defined on the table. A partition cannot be added if the table space definition is incomplete because a partitioning key or partitioning index is missing.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant, ...)

Specifies the high key limit for the new partition. The new partition's key limit must be higher when partitioning is ascending and lower when it is descending. Specify at least one constant after ENDING AT in the PARTITION clause. You can use as many values as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition of the index. The use of constants to define key values is subject to the following rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must have the same data type as its corresponding column. A hexadecimal graphic string constant (GX) cannot be specified.

    Using fewer constants than there are columns in the key has the same effect as using the highest or lowest values for the omitted columns, depending on whether they are ascending or descending.

  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition.
  • The constants specified for the last partition are enforced. The value specified for the last partition is the highest value of the key that can be placed in the table. If the limit was not previously enforced, any existing key values greater than the value specified for the added partition are placed into the discard data set when REORG is run.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'. If the column is descending, the padding character is X'00'.
  • If a key includes a ROWID column or a column with a distinct type that is based on a ROWID data type, then 17 bytes of the constant that is specified for the corresponding ROWID column are considered.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

ADD PARTITION BY RANGE

Specifies the range partitioning scheme for the table (the columns used to partition the data). When this clause is specified, the table uses table-controlled partitioning. The number of partitions specified in the ADD PARTITION BY RANGE clause has to be the same as the number of partitions defined in the table space.

This clause applies only to tables in a partitioned table space. If the table is already complete by having established either table-controlled partitioning or index-controlled partitioning, the ADD PARTITION BY RANGE clause is not allowed. If this clause is used, then the ENDING AT clause cannot be used on a subsequent CREATE INDEX statement for this table.

This clause is only implemented syntactically in the XDB Server operating environment.

partition-expression

Specifies the key data over which the range is defined to determine the target data partition of the data.

column-name

Specifies the columns of the key. Each column-name must identify a column of the table. Do not specify more than 64 columns, the same column more than once, a LOB column, a column with a distinct type that is based on a LOB data type, or a qualified column name. The sum of length attributes of the columns must not be greater than 255 - n, where n is the number of columns that can contain null values.

NULLS LAST

Specifies that null values are treated as positive infinity for purposes of comparison.

ASC

Puts the entries in ascending order by the column. ASC is the default.

DESC

Puts the entries in descending order by the column.

partition-element

Specifies ranges for a data partitioning key and the table space where rows of the table in the range will be stored.

PARTITION integer

Identifies the partition to apply the boundary specified in the subsequent ENDING AT clause. It must be in the range of 1 to n where n is the number of partitions in the table.

ENDING AT(constant, ...)

Specifies the highest value of the partitioning key for the new partition. Specify at least one constant after ENDING AT in each PARTITION clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition. The length of each highest key value (the limit key) is the same as the length of the partitioning key. The use of constants to define key values is subject to the rules listed for the ENDING AT clause for a partition definition.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

ALTER PARTITION

Specifies that the partitioning limit key for the identified partition is to be altered. Specify ALTER PARTITION only if the table is partitioned.

This clause applies only to tables in a partitioned table space. If the table is already complete by having established either table-controlled partitioning or index-controlled partitioning, the ADD PARTITION BY RANGE clause is not allowed. If this clause is used, then the ENDING AT clause cannot be used on a subsequent CREATE INDEX statement for this table.

This clause is only implemented syntactically in the XDB Server operating environment.

integer

If integer is specified, it must be in the range 1 to n, where n is the number of partitions in the table. Altering a partition boundary is not allowed if the table is a materialized query table or if a materialized query table is defined on this table. When this option is specified for any partition except for the last, both the identified partition and the partition following are placed in REORG-pending (REORP) status.

ENDING AT(constant, ...)

Specifies the highest value of the partitioning key for the identified partition.

In this context, highest means highest in the sorting sequences of the columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC) the lowest actual value is highest in the sorting sequence.

Specify at least one constant after ENDING AT in each ALTER PARTITION clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition. The length of each highest key value (the limit key) is the same as the length of the partitioning key. The use of constants to define key values is subject to the rules listed for the ENDING AT clause for a partition definition. The value that is specified must not be equal to or beyond the range of the partition boundaries of the adjacent partitions.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

If the table uses index-controlled partitioning, it is converted to use table-controlled partitioning. The high limit key for the last partition is set to the highest possible value for ascending key columns or the lowest possible value for descending key columns.

ROTATE PARTITION FIRST TO LAST

Specifies that the first logical partition should be rotated to become the last logical partition. This keyword must be followed by the ENDING AT clause, which specifies the new high key limit for this partition, which is now logically last. The new partitioning key value must be higher than the current high key limit if partition values are ascending. If partition values are descending, the new key limit must be lower than the current low key limit.

Rotating a partition occurs immediately. If there is a referential constraint with DELETE RESTRICT on the table, the ROTATE might fail. If the table uses index-controlled partitioning, it is converted to use table-controlled partitioning.

If the table has a security label column, the user must have a valid security label to rotate partitions. In addition, if write-down is in effect, the user must have the write-down privilege.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant, ...)

The ENDING AT clause specifies the new high key limit for the existing partition holding the oldest data.

In this context, highest means highest in the sorting sequences of the columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC) the lowest actual value is highest in the sorting sequence.

Specify at least one constant after ENDING AT. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition. The length of each highest key value (the limit key) is the same as the length of the partitioning key. The use of constants to define key values is subject to the rules listed for the ENDING AT clause for a partition definition.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

RESET

Specifies that the existing data in the oldest partition is deleted. In a partitioned table with limit values that are in ascending sequence, ALTER TABLE ALTER PARTITION ROTATE FIRST TO LAST logically operates as if the partition with the lowest high key limit were dropped and then a new partition was added with the specified high key limit. The partition's new key limit must be higher than any other partition in the table. For descending limit keys, the rotation operates as the partition with the highest limit values becomes the partition with the lowest limit values.

If the partition contains referential integrity parent relationships, has DATA CAPTURE logging enabled, or has a delete row trigger, then each data row in the partition must be deleted individually. If a table does not have any of these attribute settings, then the data rows are removed by deleting and redefining the underlying data sets.

SYSCOPY and SYSLGRNGX rows associated with the partition being reset are deleted. This includes the rows for the table space partition, partitioned index partitions, LOB table spaces, and auxiliary indexes.

This clause is only implemented syntactically in the XDB Server operating environment.

ADD MATERIALIZED QUERY materialized-query-definition

Changes a base table to a materialized query table. Supplies a definition for a regular table to make it a materialized query table. The table specified by table-name and the result columns of the fullselect must not have the following characteristics:

  • Be already defined as a materialized query table
  • Have any primary keys, unique constraints (unique indexes), referential constraints (foreign keys), check constraints, or triggers defined
  • Be referenced in the definition of another materialized query table
  • Be directly or indirectly referenced in the fullselect
  • Be in an incomplete state

If table-name does not meet these criteria, an error occurs. fullselect defines the query on which the table is based. The columns of the existing table must meet the following characteristics:

  • Have the same number of columns
  • Have exactly the same column definitions
  • Have the same column names in the same ordinal positions

If fullselect is specified, the owner of the table being altered must have the SELECT privilege on the tables or views referenced in the fullselect. Having SELECT privilege means that the owner has at least one of the following authorizations:

  • Ownership of the tables or views referenced in the fullselect
  • The SELECT privilege on the tables and views referenced in the fullselect
  • SYSADM authority
  • DBADM authority for the database in which the table of the fullselect reside

If the owner of the table does not have the SELECT privilege, the following authorization IDs must have SYSADM authority or DBADM authority for the database in which the tables of the fullselect reside:

  • For embedded statements, the authorization ID of the owner of the plan or package
  • For dynamically prepared statements, the SQL authorization ID of the process

Altering a table to change it from a base table to a materialized query table with REFRESH DEFERRED causes any plans and packages dependent on the table to be invalidated.

This clause is only implemented syntactically in the XDB Server operating environment.

refreshable-table-options

Specifies the materialized query table options for altering a regular table to a materialized query table.

DATA INITIALLY DEFERRED

Specifies that the data in the table is not validated as part of the ALTER TABLE statement. A REFRESH TABLE statement can be used to make sure the data in the materialized query table is the same as the result of the query in which the table is based.

REFRESH DEFERRED

Specifies that the data in the table can be refreshed at any time using the REFRESH TABLE statement. The data in the table only reflects the result of the query as a snapshot at the time when the REFRESH TABLE statement is processed or as updated by the user for a user-maintained materialized query table.

MAINTAINED BY SYSTEM or MAINTAINED BY USER

Specifies how the data in the materialized query table is maintained.

MAINTAINED BY SYSTEM

Specifies that the data in the materialized query table table-name is to be maintained by the system. Only the REFRESH TABLE statement is allowed on the table.

MAINTAINED BY USER

Specifies that the data in materialized query table table-name is to be maintained by the user, who can use LOAD utility or the INSERT, DELETE, UPDATE, and REFRESH TABLE statements on the table.

ENABLE QUERY OPTIMIZATION or DISABLE QUERY OPTIMIZATION

Specifies whether this materialized query table can be used for optimization.

ENABLE QUERY OPTIMIZATION

Specifies that the materialized query table can be used for query optimization. If the fullselect specified does not satisfy the restrictions for query optimization, an error occurs.

DISABLE QUERY OPTIMIZATION

Specifies that the materialized query table cannot be used for query optimization. The table can still be queried directly.

DROP MATERIALIZED QUERY

Changes a materialized query table so that it is no longer considered a materialized query table. The table specified by table-name must be defined as a materialized query table. The definition of columns and data of the name are not changed, but the table can no longer be used for query optimization and is no longer valid for use with the REFRESH TABLE statement.

Altering a table to change from a materialized query table to a base table with the DROP MATERIALIZED QUERY clause causes any plans and packages dependent on the table to be invalidated.

This clause is only implemented syntactically in the XDB Server operating environment.

ALTER MATERIALIZED QUERY materialized-query-table-alteration

Changes attributes of a materialized query table. The table-name must identify a materialized query table.

This clause is only implemented syntactically in the XDB Server operating environment.

SET refreshable-table-alteration

Changes how the table is maintained or whether the table can be used in query optimization.

MAINTAINED BY SYSTEM

Specifies that the data in a materialized query table table-name is to be maintained by the system.

MAINTAINED BY USER

Specifies that the data in the materialized query table table-name is to be maintained by the user.

ENABLE QUERY OPTIMIZATION

Specifies that materialized query table table-name can be used in query optimization. If the fullselect specified for the materialized query table does not satisfy the restrictions for automatic query optimization, an error occurs.

DISABLE QUERY OPTIMIZATION

Specifies that materialized query table table-namecannot be used for query optimization. The table can still be queried directly.

DROP CHECK

Drops the check constraint constraint-name. The constraint-name must identify an existing check constraint defined on the table.

DELETE

This clause (available in XDB mode only) deletes one or more data columns from an existing table, by listing the column names (separated by commas) after the DELETE keyword. The corresponding field values are actually removed from each record in the table; all data values in the deleted columns are lost. The ALTER TABLE statement below removes the three columns that were added in the ADD example shown above:

ALTER TABLE supplier
    DELETE state, zip, founded

RENAME

This clause (available in XDB mode only) renames one or more existing columns within an existing table. For each column to be renamed, list the old-column-name, a space, followed by the new-column-name. If more than one column needs renaming, separate the pairs of old and new names with commas.

For example:

ALTER TABLE supplier
    RENAME sno Supplier_No, sname Supplier_Name

MODIFY

This clause (available in XDB mode only) changes the data type or null permission for one or more existing table columns. The new data type must be compatible with the old data type, with conversion being performed whenever possible. The following example changes the character length of the STATUS and CITY columns:

ALTER TABLE supplier
    MODIFY status CHAR 2, city CHAR 15

If the conversion cannot be performed because of incompatible data field types or possible loss of data, an error message is displayed. If a character field is not long enough to hold a string value, the string is truncated on the right.

The following table defines the data conversions permitted. The "Y" values indicate that the intersecting data types are compatible (meaning one type can be switched to the other). The "N" values indicate that the intersecting data types are not compatible.

From/To | small- int | int | float | float4 | dec | Money | date | time | Time- stamp | char | vchar (See note 1) | graph | vgraph (See note 2)
smallint | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
integer | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
float | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
float(4) | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
decimal | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
money | Y | Y | Y | Y | Y | Y | N | N | N | Y | Y | Y | Y
date | N | N | N | N | N | N | Y | N | Y | Y | Y | Y | Y
time | N | N | N | N | N | N | N | Y | Y | Y | Y | Y | Y
timestamp | N | N | N | N | N | Y | Y | Y | Y | Y | Y | Y | Y
char | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
varchar | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
graphic | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
vargraph | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y | Y
image | This BLOB data type cannot be modified within SQL.
Note:
  • Varchar and Long Varchar are treated the same way for data type conversions.
  • Vargraphic and Long Vargraphic are treated the same way for data type conversions.

In addition to changing data types and null permissions, the MODIFY clause can change character string lengths, along with decimal scale and precision. For example, to change the length of the column named SNAME in the SUPPLIER table to ten characters, enter the following command:

ALTER TABLE supplier
    MODIFY sname CHAR 10

Note that the length of INT and MONEY column fields cannot be changed. To increase the length of a SMALLINT field, change it to INT type. You can also change numeric field types to DECIMAL or FLOAT if you need to accommodate larger numbers.

The MODIFY option can also specify whether or not null values are permitted in a column. The NULL or NOT NULL keywords should appear after the name and data type specifications of the data column. Use the NULL keyword to permit null values in the data column, and the NOT NULL keywords to restrict null values in the column. Use the NOT NULL WITH DEFAULT option to insert default data values in place of null values (current time, current date, zero, etc.).

An error message is displayed if a MODIFY clause attempts to change a data column containing NULL values to NOT NULL. If a null option is not specified in the ALTER TABLE command, no change is made to the null permission currently defined for that column. For example, if the SNO column in the SUPPLIER table was originally defined as "sno CHAR(4)," you can change the null permission to prevent entry of null values using the following command. Note that the data type must be specified, even though it is not changed:

ALTER TABLE supplier
    MODIFY sno char(4) NOT NULL

You can change both field length and null permission to permit nulls by entering:

ALTER TABLE supplier
    MODIFY sno CHAR(6) NULL

UNIQUE KEY

Defines a unique key composed of the identified columns with the specified constraint-name. If a constraint-name is not specified, a name is generated. Each column name must be an unqualified name that identifies a column of the table except a LOB or ROWID column, and the same column must not be identified more than once. Each identified column must be defined as NOT NULL. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 - n for padded indexes and 2000 - n - 2m for nonpadded indexes, where n is the number of columns that can contain null values and m is the number of varying-length columns in the key.

Note:

The various domain and referential constraints discussed in these paragraphs utilize indexes in the background to implement the checks efficiently.

When key-name refers to a unique index created on a parent table (other than the PRIMARY KEY), or when the key-name optionally appears after the referenced-table parameter in the REFERENCES clause of an ADD FOREIGN KEY clause (XDB mode only), that special type of unique index can also be referred to as a candidate-key.

The example below creates a unique index named pskey that constrains each row of the PARTSUPP table to contain a unique set of values in the PNO and SNO columns:

ALTER TABLE partsupp
    UNIQUE KEY pskey (pno, sno)

When the ALTER TABLE...UNIQUE command is issued, the system checks the table to verify whether there are duplicate values in the specified columns. The system creates and maintains a unique index called pskey on the named columns. The index created as a result of a uniqueness constraint cannot be dropped using the DROP INDEX command, since it is required to enforce the uniqueness constraint. To drop the index you must drop the uniqueness constraint.

PRIMARY KEY

The purpose of the primary key is to enforce entity integrity -- that is, to uniquely identify each row of a table. A PRIMARY KEY constraint is similar to a UNIQUE constraint, except that a table can have at most one constraint condition specified as a PRIMARY KEY.

Note that the fields in the primary key must be defined as NOT NULL. The column names must appear in the CREATE UNIQUE INDEX command in exactly the same order as in the PRIMARY KEY constraint. This index will be designated as the primary key of the table. If there is more than one index that satisfies the criteria for a primary key, one is selected arbitrarily as the primary key.

For example, to define columns PNO and SNO as the primary key of the PARTSUPP, use the command:

ALTER TABLE partsupp
    PRIMARY KEY (pno, sno)

To define the column SNO as the primary key of the SUPPLIER table, use a command like:

ALTER TABLE supplier
    PRIMARY KEY (sno)

Again, a unique index must exist on the SUPPLIER table SNO column.

Each column name must be an unqualified name that identifies a column of the table except a LOB or ROWID column, and the same column must not be identified more than once. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 -2m, where m is the number of varying-length columns in the key. The table must not have a primary key and the identified columns must be defined as NOT NULL.

FOREIGN KEY

A FOREIGN KEY constraint is used to enforce referential integrity -- the relationship between a referencing or dependent table and a referenced or parent table. The referential integrity rule requires that, for any value in the dependent column(s), there must exist a row in the parent table such that the value of the dependent column(s) equals the value of the corresponding column(s) in the primary key of the parent table. This is enforced as follows:

  1. When an update or insert is performed on the dependent table, the set of values placed in the referencing columns must match a set of values that exists in the parent table.
  2. If an attempt is made to delete or update a row of the parent table that contains values matching those in a dependent table, the system uses the ON DELETE (or ON UPDATE) clause to determine the delete rule to be used. The options are:
    • RESTRICT

      Prevents records from being deleted from the parent table if dependents exist. This is the default setting.

    • NO ACTION

      Prevents records from being deleted from the parent table (as in the RESTRICT option), except the referential constraint is enforced at the end of the statement. This is the default setting if the CURRENT RULES special register is STD (SQL standard).

    • CASCADE

      Deletes the dependent records from the current table and then deletes the parent records.

    • SET NULL

      Causes each nullable column in the foreign key of each dependent record to be set to NULL before the corresponding parent records are deleted.

Note that whenever a cyclical situation exists (for example a foreign key of table B references the primary key of table A, and a foreign key of table A references a primary key of table B), the delete rules should be the same for all foreign keys, and the SET NULL option should not be used.

To create a referential integrity constraint you must create a FOREIGN KEY constraint on the referencing table. The FOREIGN KEY constraint must reference the existing PRIMARY KEY or UNIQUE KEY of the referenced table.

FOREIGN KEY columns do not have to have the same names as the corresponding columns in the PRIMARY KEY of the referenced table, but the columns must match in type, number and order.

A constraint-name is used to uniquely identify the FOREIGN KEY constraint. The constraint-name should be a short identifier (up to eight characters) that is unique among all constraints built on the table. The constraint-name is stored in the RELNAME column of the SYSIBM.SYSFOREIGNKEYS catalog table, and is displayed in the error message generated when the constraint is violated.

It is a good practice to provide a meaningful constraint-name, however, if a constraint-name is not supplied, the system automatically generates one by first checking the first eight characters of the first column name (in the column list) for uniqueness. If these eight characters are not unique, the XDB Server truncates the last character and substitutes a number -- checking again for uniqueness. If necessary, one letter at a time is removed from the end of the constraint name and replaced with a number until the constraint name becomes unique among all constraint names that exist on the table.

The foreign key of the referential constraint is composed of the identified columns. Each column-name must be an unqualified name that identifies a column of T1 except a ROWID column or security label column, and the same column must not be identified more than once. The number of identified columns must not exceed 64 and the sum of their length attributes must not exceed 255 minus the number of columns that allow null values. The referential constraint is a duplicate if the FOREIGN KEY and the parent table are the same as the FOREIGN KEY and parent table of an existing referential constraint on T1. The specification of a duplicate referential constraint is ignored with a warning.

Indexes on Foreign Keys

The XDB Server automatically builds an index on your FOREIGN KEY columns. The system will generate the name of the index and store it in the REFKEYNAME column of theSYSIBM.SYSREF catalog table. DB2, in contrast, does not automatically create an index on FOREIGN KEY columns.

If you are using your DB2 data definition language (DDL) script, and this script contains CREATE INDEX commands on FOREIGN KEY columns, you can end up with redundant indexes. For optimal performance, you should modify your DB2 DDL script to remove any CREATE INDEX commands on FOREIGN KEY columns.

To demonstrate the use of a FOREIGN KEY constraint, consider the SUPPLIER and PARTSUPP tables (see XDB Server Tutorial Location). There should not be any values in the SNO column of the PARTSUPP table that do not appear in the SUPPLIER table, since you cannot order from a supplier that does not exist. To enforce this rule, a PRIMARY KEY is built on the SNO column of the SUPPLIER table. Next a FOREIGN KEY constraint is built on the SNO column of the PARTSUPP table. The PARTSUPP table is the referencing table and the SUPPLIER table is the referenced table. The example below adds a foreign key constraint named ps_fkey to the PARTSUPP table:

ALTER TABLE partsupp
    FOREIGN KEY ps_fkey (sno)
    REFERENCES supplier

If an attempt is made to remove a supplier from the SUPPLIER table, it will be permitted only if there are no matching records in the PARTSUPP table. It is possible, therefore, to delete the row where SNO equals S5, since supplier S5 supplies no parts. But the row where SNO equals S1 cannot be deleted, since supplier S1 supplies many parts. Each matching record in the PARTSUPP table must be deleted before the S1 record could be deleted from the SUPPLIER table.

If the command was specified using the ON DELETE CASCADE option, as shown below, the SUPPLIER record S5 could be deleted, but all PARTSUPP records for S5 would also be deleted.

ALTER TABLE partsupp
    FOREIGN KEY ps_fkey (sno)
    REFERENCES supplier
    ON DELETE CASCADE

CHECK

In XDB mode, you can also add a CHECK constraint to a table, consisting of a search condition that must be true for every row of the table. If an attempt is made to update or insert a row that does not satisfy the search condition, an error results. Any SQL search condition can be used. CHECK conditions are stored in the SYSIBM.SYSCHECK table (see XDB Server System Tables).

Note:

The system does not check the data currently in the table to verify whether it satisfies the CHECK constraint. You should delete or update the rows that violate the constraint before issuing the ALTER TABLE...CHECK statement.

For example, to impose the constraint that no part be supplied in quantities greater than 500, use the following ALTER TABLE statement:

ALTER TABLE partsupp
    CHECK qty <= 500

A CHECK constraint may be a compound condition. For example, you may issue the command:

ALTER TABLE employee
    CHECK (payrate <= 20
           AND hours <= 60
           AND dept = 2020)
           OR (payrate <= 25
               AND hours <= 40
               AND dept = 1050)

This constraint always checks to verify that employees in Department 2020 are not paid more than $20.00 an hour, and do not work more than 60 hours a week. On the other hand, employees in department 1050 cannot receive pay greater than $25.00 an hour or work more than 40 hours a week.

You may use nested queries and nested joins in the CHECK condition, if desired.

DROP

This option is used to drop uniqueness, referential or check constraints. If no constraint is found, the command has no effect.

For example, to drop the PRIMARY KEY on the employee table, issue the statement:

ALTER TABLE employee
    DROP PRIMARY KEY

To drop a UNIQUE KEY named ps_key on the PARTSUPP table columns SNO and PNO, issue the statement:

ALTER TABLE partsupp
    DROP KEY ps_key

To drop a FOREIGN KEY constraint called ps_fkey on the PARTSUPP table, issue the statement:

ALTER TABLE partsupp
    DROP FOREIGN KEY ps_fkey

To drop a CHECK constraint on the PARTSUPP table, issue the statement:

ALTER TABLE partsupp
    DROP CHECK
Note:

When using ALTER TABLE, there are restrictions for adding columns. You cannot add:

  • A column to a table that has an edit procedure
  • A ROWID column to a table that already has a ROWID column
  • An identity column to a table that already has an identity column
  • A ROWID, or identity column to a created temporary table

Adding a ROWID column

When you add a ROWID column to an existing table, XDB ensures that the same, unique row ID value is returned for a row whenever it is accessed. Reorganizing a table space has no effect on the values in a ROWID column.

Altering the length of a column

Only the length of VARCHAR columns can be changed. When changing the length of a column, be aware of the following information about indexes, limit keys, check constraints, and invalidation.

The length of a VARCHAR column cannot be changed if any of the following conditions are true:

  • The column is referenced in a referential constraint or view.
  • The column has a field procedure routine
  • The table has an edit or validation routine
  • The table is defined with DATA CAPTURE CHANGES
  • The table is a created temporary table

The XDB Server operating environment does not currently provide this functionality.

Indexes

After the ALTER TABLE statement is executed, each index on the table with a key that includes a column whose length was increased remains available. However, SQL operations against such an index are not allowed until the changes from the ALTER TABLE statement are committed.

The maximum number of distinct alters that increase the index key length is sixteen or less. If the maximum number of alters is exceeded, SQLCODE -148 is returned, and the index must be reorganized or rebuilt. An alter is considered distinct when it occurs in a different unit of work than the previous alter. For example, changing an index column length, committing database changes, and changing the column length of that index column or another index column counts as two distinct alters. Whereas, changing an index column length twice before committing any changes counts as one distinct alter; the second changes replace the first because it was in the same commit scope. Changing the length of two different index columns before committing the changes also counts as one distinct alter.

Check constraints

If a table check constraint refers to the column being altered, the length of the column is also changed in the check constraint.

Examples

Column DEPTNAME in table DSN8610.DEPT was created as a VARCHAR(36). Increase its length to 50 bytes. Also, add the column BLDG to the table DSN8610.DEPT. Describe the new column as a character string column that holds SBCS data.

 ALTER TABLE DSN8610.DEPT
   ALTER COLUMN DEPTNAME SET DATA TYPE VARCHAR(50)
   ADD BLDG CHAR(3) FOR SBCS DATA;

Assign a validation procedure named DSN8EAEM to the table DSN8610.EMP.

 ALTER TABLE DSN8610.EMP
   VALIDPROC DSN8EAEM;

Disassociate the current validation procedure from the table DSN8610.EMP. After the statement is executed, the table no longer has a validation procedure.

 ALTER TABLE DSN8610.EMP
   VALIDPROC NULL;

Define ADMRDEPT as the foreign key of a self-referencing constraint on DSN8610.DEPT.

 ALTER TABLE DSN8610.DEPT
   FOREIGN KEY(ADMRDEPT)
      REFERENCES DSN8610.DEPT ON DELETE CASCADE;

Add a check constraint to the table DSN8610.EMP which checks that the minimum salary an employee can have is $10,000.

 ALTER TABLE DSN8610.EMP
   ADD CHECK (SALARY >= 10000);

Alter the PRODINFO table to define a foreign key that references a non-primary unique key in the product version table (PRODVER_1). The columns of the unique key are VERNAME, RELNO.

 ALTER TABLE PRODINFO
   FOREIGN KEY (PRODNAME,PRODVERNO)
      REFERENCES PRODVER_1 (VERNAME,RELNO) ON DELETE RESTRICT;

The check pending status prevents further updating or reading by other SQL applications. It does not affect the application process that issues ALTER TABLE. However, we do not recommend that a process create or alter a permanent table and then access it.

Parent topic: SQL Statements


ALTER TABLESPACE

The ALTER TABLESPACE statement changes the specifications of a table space within the currently set XDB Server location.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the ALTER TABLESPACE command, users must possess either DBADM authority for the database, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table space affected.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER TABLESPACE [database-name.]tablespace-name
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [DSETPASS password]
    [PART integer]
    [FREEPAGE integer]
    [PCTFREE integer]
    [USING {VCAT catalog-name | STOGROUP stogroup-name}]
    [PRIQTY integer]
    [SECQTY integer]
    [ERASE {YES | NO}]
    [COMPRESS {NO | YES}]
    [GBPCACHE {CHANGED | ALL | SYSTEM | NONE}]
    [LOCKMAX {SYSTEM | integer}]
    [LOCKSIZE {ANY | TABLESPACE | TABLE | PAGE | ROW | LOB}]
    [TRACKMOD {YES | NO}]
    [LOG {YES | NO}]
    [LOCKPART {NO | YES}]
    [MAXROWS integer]

Parameters:

database-name.tablespace-name | Identifies the table space to be altered. The table space must exist at the currently set XDB Server location. If the database-name qualifier is omitted, then the XDB Server assumes the table space is located in the default DSNDB04 database (within the current location).
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.
password | Consists of a short identifier.
integer | Specifies a whole number in the range of 1 to n.

Description

Although all of the information contained in the following ALTER TABLESPACE optional clauses is recorded in the XDB Server catalog tables, the XDB Server system architecture does not physically support many of these options. Refer to appropriate DB2 documentation for complete descriptions of these mainframe-specific options.

BUFFERPOOL

This clause has no functional equivalent withing the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for table spaces with 4K page sizes, while the last ten are for table spaces with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server catalog tables.

LOCKSIZE

Specifies the size of locks used within the table space and, in some cases, also the threshold at which lock escalation occurs. Do not specify LOCKSIZE for a table space in a work file database or a TEMP database.

In most cases, DB2 uses LOCKSIZE PAGE LOCKMAX SYSTEM for non-LOB table spaces and LOCKSIZE LOB LOCKMAX SYSTEM for LOB table spaces. However, when the number of locks acquired for the table space exceeds the maximum number of locks allowed for a table space (an installation parameter), the page or LOB locks are released and locking is set at the next higher level. If the table space is segmented, the next higher level is the table. If the table space is nonsegmented, the next higher level is the table space.

TABLESPACE | Specifies table space locks.
TABLE | Specifies table locks. Use TABLE only for a segmented table space.
PAGE | Specifies page locks. Do not use PAGE for a LOB table space.
ROW | Specifies row locks. Do not use ROW for a LOB table space.
LOB | Specifies LOB locks. Use LOB only for a LOB table space.

This option is semantically checked and recorded in the XDB Server system catalog tables. See DB2 documentation for a full discussion of keyword options.

TRACKMOD

Specifies whether DB2 tracks modified pages in the space map pages of the table space or partition. Do not specify TRACKMOD for a LOB table space. For a table space in a TEMP database, DB2 uses TRACKMOD NO regardless of the value specified.

YES | DB2 tracks changed pages in the space map pages to improve the performance of incremental image copy. For data sharing, changing TRACKMOD to YES causes additional SCA (shared communication area) storage to be used until after the next full or incremental image copy is taken or until TRACKMOD is set back to NO.
NO | DB2 does not track changed pages in the space map pages. It uses the LRSN value in each page to determine whether a page has been changed.

LOCKMAX

Specifies the maximum number of page, row, or LOB locks an application process can hold simultaneously in the table space. If a program requests more than that number, locks are escalated. The page, row, or LOB locks are released and the intent lock on the table space or segmented table is promoted to S or X mode. If you specify LOCKMAX a for table space in a TEMP database, DB2 ignores the value because these types of locks are not used.

For an application that uses Sysplex query parallelism, a lock count is maintained on each member.

Integer | Specifies the number of locks allowed before escalating, in the range 0 to 2 147 483 647. Zero (0) indicates that the number of locks on the table or table space are not counted and escalation does not occur.
SYSTEM | Indicates that the value of field LOCKS PER TABLE(SPACE) on installation panel DSNTIPJ specifies the maximum number of page, row, or LOB locks a program can hold simultaneously in the table or table space.

If you change LOCKSIZE and omit LOCKMAX, the following results occur:

LOCKSIZE | Resultant LOCKMAX
TABLESPACE or TABLE | 0
PAGE ROW, or LOB | Unchanged
ANY | SYSTEM

If the lock size is TABLESPACE or TABLE, LOCKMAX must be omitted, or its operand must be 0.

CLOSE

When the limit on the number of open data sets is reached, specifies the priority in which data sets are closed.

YES | Eligible for closing before CLOSE NO data sets. This is the default unless the table space is in a TEMP database.
NO | Eligible for closing after all eligible CLOSE YES data sets are closed.

For a table space in a TEMP database, DB2 uses CLOSE NO regardless of the value specified.

This option is semantically checked and recorded within the XDB Server system catalog tables. See DB2 documentation for a full discussion of keyword options.

DSETPASS

This option records a password for a DB2 subsystem dataset inside the XDB Server system catalog. To remove a password, specify a delimited string of blank characters as the password name. For example:

DSETPASS " "

PART

XDB does not physically support partitioned table spaces, however, this clause can be used to identify a table space partition number (integer) defined within a DB2 subsystem that is being accessed through XDB Link. Do not use this clause if the DB2 table space is not partitioned.

If the DB2 table space is partitioned, the PART clause must be used if the FREEPAGE, PCTFREE, USING, PRIQTY, SECQTY, or ERASE clause appears in the ALTER TABLESPACE statement. Under these circumstances, all alterations specified in the later clause options apply specifically to the table space partition identified in the PART clause.

FREEPAGE

This option specifies the number of pages left free within a segmented table space defined on a DB2 subsystem. The integer whole number value can range from 0 to 255, but must be less than the SEGSIZE value. In situations where the number of pages free is greater than or equal to the SEGSIZE, the number of pages free is corrected downward to the SEGSIZE value minus one.

PCTFREE

This option specifies a whole number value (integer) ranging from 0 to 99. This clause is semantically checked after which the values are recorded in the appropriate XDB Server catalog tables. See DB2 documentation for a full discussion of keyword options.

USING

This clause specifies either a user-managed or DB2-managed dataset for a table space or partition in a DB2 subsystem. For partitioned table spaces, the USING clause is applied only to the dataset within the partition identified in the PART clause. For nonpartitioned table spaces, the USING clause is applied to every dataset that is eligible for a particular table space.

VCAT catalog-name | Designates a user-managed dataset starting with catalog-name. The catalog-name must be a short identifier.
STOGROUP stogroup-name | Identifies a stogroup described in the DB2 catalog. Before applying a new description for a table space, the storage group description must include at least one volume serial number. This volume serial number is entered into the SYSIBM.SYSVOLUMES catalog table, and can be used to locate tables created in this table space on different physical paths (see CREATE STOGROUP).

If the current dataset for the table space or partition is DB2-managed and USING STOGROUP is specified, then omitting the PRIQTY clause implicitly defines the current PRIQTY value. Additionally, omitting the SECQTY clause implicitly defines the current SECQTY value, while omitting the ERASE clause implicitly specifies the current ERASE rule.

If the current dataset for the table space or partition is user-managed and USING STOGROUP is specified, then the omission of the various clauses below implicitly specifies the following:

  • PRIQTY values of 12 for a table space with 4K pages and 96 for a table space with 32K pages, when omitting the PRIQTY clause.
  • SECQTY values of 12 for a table space with 4K pages and 96 for a table space with 32K pages, when omitting the SECQTY clause.
  • Default value of ERASE NO, when omitting the ERASE clause.

PRIQTY

Indicates the replacement value for the last primary space allocation for the table space or partition dataset. This clause can be specified only under one of the following conditions:

  • USING STOGROUP is also specified.
  • The USING clause is not specified, and the table space or partition dataset is DB2-managed.

The value integer is the primary space allocation in kilobytes. Any whole number can be specified up to a limit of 4,194,304. Values greater than 4,194,304 are reduced to 4,194,304. When specifying a number less than 12 for a table space with a page size of 4K, the system increases the number to 12. When specifying a number less than 96 for a table space with a page size of 32K, the system increases the number to 96. If PRIQTY -1 is specified, DB2 uses a default value for the primary space allocation.

If PRIQTY is specified, the primary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

  • For 4KB page sizes, if integer is less than 12, n is 12.
  • For 8KB page sizes, if integer is less than 24, n is 24.
  • For 16KB page sizes, if integer is less than 48, n is 48.
  • For 32KB page sizes, if integer is less than 96, n is 96.
  • For any page size, if integer is greater than 4194304, n is 4194304.

For LOB table spaces, the exceptions are:

  • For 4KB pages sizes, if integer is less than 200, n is 200.
  • For 8KB pages sizes, if integer is less than 400, n is 400.
  • For 16KB pages sizes, if integer is less than 800, n is 800.
  • For 32KB pages sizes, if integer is less than 1600, n is 1600.
  • For any page size, if integer is greater than 4194304, n is 4194304.
  • Do not specify the PRIQTY clause for user-managed datasets.

SECQTY

Indicates the replacement value for the last secondary space allocation for the table space or partition dataset. This clause can be specified only under one of the following conditions:

  • USING STOGROUP is also specified.
  • The USING clause is not specified, and the table space or partition dataset is DB2-managed.

The value integer is the secondary space allocation in kilobytes. For a dataset or table space using 4K pages, any whole number can be specified up to a limit of 131,068. Values greater than 131,068 are reduced to 131,068. The maximum allowable secondary allocation for 32K page size datasets is 131,040. If a value of zero is specified, the dataset cannot be extended. If SECQTY -1 is specified, DB2 uses a default value for the secondary space allocation.

If SECQTY is specified, the secondary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

  • If integer is greater than 4194304, n is 4194304. A value of 0 for integer indicates that no data set can be extended.

For LOB table spaces the exceptions are:

  • For 4KB page sizes, if integer is greater than 0 and less than 200, n is 200.
  • For 8KB page sizes, if integer is greater than 0 and less than 400, n is 400.
  • For 16KB page sizes, if integer is greater than 0 and less than 800, n is 800.
  • For 32KB page sizes, if integer is greater than 0 and less than 1600, n is 1600.
  • For any page size, if integer is greater than 4194304, n is 4194304.

Do not specify the SECQTY clause for user-managed datasets.

ERASE

This clause can be specified only under one of the following conditions:

  • USING STOGROUP is also specified.
  • The USING clause is not specified, and the table space or partition dataset is DB2-managed.

Do not specify the ERASE clause for user-managed datasets.

COMPRESS

Specifies whether data compression applies to the rows of the table space or partition. Do not specify COMPRESS for a LOB table space.

Either the option specified or the default value is recorded in the SYSIBM.SYSTABLEPART system catalog table. This option does not compress data in any way.

GBPCACHE

In a data sharing environment, specifies what pages of the table space or partition are written to the group buffer pool in a data sharing environment. In a non-data-sharing environment, you can specify GBPCACHE for a table space other than one in a work file or TEMP database, but it is ignored. Do not specify GBPCAHCE for a table space in a work file database or in a TEMP database in either environment (data sharing or not).

CHANGED When there is inter-DB2 R/W interest on the table space or partition, updated pages are written to the group buffer pool. When there is no inter-DB2 R/W interest, the group buffer pool is not used. Inter-DB2 R/W interest exists when more than one member in the data sharing group has the table space or partition open, and at least one member has it open for update.

If the table space is in a group buffer pool that is defined to be used only for cross-invalidation (GBPCACHE NO), CHANGED is ignored and no pages are cached to the group buffer pool.

ALL Indicates that pages are to be cached in the group buffer pool as they are read in from DASD.

Exception: In the case of a single updating DB2 when no other DB2s have any interest in the page set, no pages are cached in the group buffer pool.

Hiperpools are not used for table spaces or partitions that are defined with GBPCACHE ALL.

If the table space is in a group buffer pool that is defined to be used only for cross-invalidation (GBPCACHE NO), ALL is ignored and no pages are cached to the group buffer pool.

SYSTEM Indicates that only changed system pages within the LOB table space are to be cached to the group buffer pool. A system page is a space map page or any other page that does not contain actual data values.

SYSTEM is the default for a LOB table space. Use SYSTEM only for a LOB table space.

NONE Indicates that no pages are to be cached to the group buffer pool. DB2 uses the group buffer pool only for cross-invalidation.

If you specify NONE, the table space or partition must not be in recover pending status.

If you specify GBPCACHE in a data sharing environment, the table space or partition must be in the stopped state when the ALTER TABLESPACE statement is executed. You cannot alter the GBPCACHE value for the following table spaces:

  • DSNDB06.SYSDBASE
  • DSNDB06.SYSDBAUT
  • DSNDB06.SYSPKAGE
  • DSNDB06.SYSPLAN
  • DSNDB06.SYSUSER (exception: the attribute can be altered if authorization includes installation SYSADM authority.)

LOG

Specifies whether changes to a LOB column in the table space are to be written to the log. Use LOG only for a LOB table space.

YES Indicates that changes to a LOB column are to be written to the log. You cannot use YES if the auxiliary table in the table space stores a LOB column that is greater than 1 gigabyte in length.

When you change the value of LOG to YES, the LOB table space is placed in copy pending status.

NO Indicates that changes to a LOB column are not to be written to the log.

LOG NO has no effect on a commit or rollback operation; the consistency of the database is maintained regardless of whether the LOB value is logged. All committed changes and changes that are rolled back reflect the expected results.

Even when LOG NO is specified, changes to system pages and to the auxiliary index are logged. During the log apply operation of the RECOVER utility, LPL recovery, or GPB recovery, all LOB values that were not logged are marked invalid and cannot be accessed by a SELECT or FETCH statement. Invalid LOB values can be updated or deleted.

LOCKPART

You can specify the LOCKPART clause, but it has no effect. Starting with Version 8, DB2 treats all partitioned table spaces as if they were defined as LOCKPART YES. LOCKPART YES specifies the use of selective partition locking. When all the conditions for selective partition locking are met, DB2 locks only the partitions that are accessed. When the conditions for selective partition locking are not met, DB2 locks every partition of the table space.

Running utilities

You cannot execute the ALTER TABLESPACE statement while a DB2 utility has control of the table space.

Altering more than one partition

To change FREEPAGE, PCTFREE, USING, PRIQTY, SECQTY, COMPRESS, ERASE, or GBPCACHE for more than one partition, you must use separate ALTER TABLESPACE statements.

Altering storage attributes

The USING, PRIQTY, SECQTY, and ERASE clauses define the storage attributes of the table space or partition. If you specify USING or ERASE when altering storage attributes, the table space or partition must be in the stopped state when the ALTER TABLESPACE statement is executed. You can use a STOP DATABASE...SPACENAM... command to stop the table space or partition.

If the catalog name changes, the changes take effect after you move the data and start the table space or partition using the START DATABASE...SPACENAM... command. The catalog name can be implicitly or explicitly changed by the ALTER TABLESPACE statement. The catalog name also changes when you move the data to a different device

Changes to the secondary space allocation (SECQTY) take effect the next time DB2 extends the data set; however, the new value is not Reflected in the integrated catalog until you use the REORG, RECOVER, or LOAD REPLACE utility on the table space or partition. The changes to the other storage attributes take effect the next time the page set is reset. For a non-LOB table space, the page set is reset when you use the REORG, RECOVER, or LOAD REPLACE utilities on the table space or partition. For a LOB table space, the page set is reset when RECOVER is run on the LOB table space or LOAD REPLACE is run on its associated base table space. If there is not enough storage to satisfy the primary space allocation, a REORG might fail. If you change the primary space allocation parameters or erase rule, you can have the changes take effect earlier if you move the data before you start the table space or partition

Examples:

Alter table space DSN8S61E in database DSN8D61A. CLOSE NO means that the data sets of the table space are not to be closed when there are no current users of the table space.

 ALTER TABLESPACE DSN8D61A.DSN8S61E
     CLOSE NO;

Alter table space DSN8S61D in database DSN8D61A. BP2 is the buffer pool associated with the table space. PAGE is the level at which locking is to take place.

 ALTER TABLESPACE DSN8D61A.DSN8S61D
     BUFFERPOOL BP2
     LOCKSIZE PAGE;
Parent topic: SQL Statements


ALTER VIEW

The ALTER VIEW statement regenerates a view using an existing view definition at the current server.
Restriction: This topic applies to Windows environments only.

The XDB Server operating environment only provides syntax support for this statement at this time.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set that is defined below must include at least one of the following:

  • Ownership of the view
  • SYSADM authority
  • SYSCTRL authority

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is the union of the privilege sets that are held by each authorization ID of the process.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

ALTER VIEW view-name REGENERATE

Description

view-name
Identifies the view to be regenerated. The name must identify a view that exists at the current server.
REGENERATE
Specifies that the view is to be regenerated. The view definition in the catalog is used, and existing authorizations and dependent views are retained. The catalog is updated with the regenerated view definition. If the view cannot be successfully regenerated, an error is returned.
Parent topic: SQL Statements


ASSOCIATE LOCATORS

The ASSOCIATE LOCATORS statement gets the result set locator value for each result set returned by a stored procedure.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program. It is an executable statement that can be dynamically prepared. It cannot be issued interactively.

Authorization

No authorization is required for this statement.

Syntax

ASSOCIATE [RESULT SET] {LOCATOR | LOCATORS}
    (rs-locator-variable ,...)
    WITH PROCEDURE {procedure-name | host-variable}

Parameters

RESULT SET
This optional item has no effect on the execution of the statement. Use it only to improve the readability of the statement.

More than one locator can be assigned to a result set. You can issue the same ASSOCIATE LOCATORS statement more than once with different result set locator variables.

If the number of result set locator variables that are listed in the ASSOCIATE LOCATORS statement is less than the number of locators returned by the stored procedure, all variables in the statement are assigned a value, and a warning is issued.

If the number of result set locator variables that are listed in the ASSOCIATE LOCATORS statement is greater than the number of locators returned by the stored procedure, the extra variables are assigned a value of 0.

The ASSOCIATE LOCATORS statement assigns result set locator values from the SQLVAR sections of the SQLDA to result set locator variables. For languages other than REXX, the first SQLDATA field is assigned to the first locator variable, the second SQLDATA field to the second locator variable, and so on. For REXX, the first SQLLOCATOR field is assigned to the first locator variables, the second SQLLOCATOR field to the second locator variable, and so on.

If a stored procedure is called more than once with a one-part name at the same location, only the most recent result sets are accessible.

LOCATOR | LOCATORS
Specifies the use of a locator or locators.
rs-locator-variable
Identifies a result set locator variable that has been declared according to the rules for declaring result set locator variables. One result set locator variable is required for each result set that is returned by the stored procedure. If the stored procedure returns fewer result sets than the number of result set locator variables specified, the extra variables are assigned a value of 0.
WITH PROCEDURE

Identifies the stored procedure that returned result set locators by the specified procedure name or the procedure name contained in the host variable.

A procedure name is a qualified or unqualified name. Each part of the name is a long SQL identifier that must be composed of SBCS characters:

  • A fully qualified procedure name is a three-part name. The first part is a location name that identifies the DBMS where the procedure is stored. The next two parts identify the stored procedure. A period must separate each of the parts. Any or all of the parts can be a delimited identifier.
  • An implicitly qualified procedure name is a two-part name that is qualified by the location name of the current server. The two parts identify the schema name and the name of the stored procedure. A period must separate the two parts. The first part identifies the stored procedure at the server. The location name of the first part depends on the application server.
  • An unqualified procedure name is a one-part name with two implicit qualifiers. The first implicit qualifier is the location name of the current server. The second implicit qualifier identifies the stored procedure at the server. The meaning of the second implicit qualifier depends on the application server (for MVS, it is SYSPROC). The name and its implicit qualifiers identifies a stored procedure.

    Successful execution of the ASSOCIATE LOCATOR statement only requires that the unqualified procedure name in the statement is the same as the procedure name in the most recently executed CALL statement that was specified with an unqualified procedure name. (The implicit schema name for the unqualified name in the CALL statement is not considered in the match.) The rules for how the procedure name must be specified are described below.

If a host variable is used:

  • It must be a character string variable with a length attribute that is not greater than 254.
  • It must be preceded by a colon and must not be followed by an indicator variable.
  • The value of the host variable is a specification that depends on the application server. Regardless of the application server, the specification must:
    • Be left justified within the host variable
    • Not contain embedded blanks
    • Be padded on the right with blanks if its length is less than that of the host variable

The procedure name in the ASSOCIATE LOCATORS statement must be specified the same way that it was specified on the CALL statement. For example, if a two-part name was specified on the CALL statement, you must use a two-part name in the ASSOCIATE LOCATORS statement. However, there is one condition under which the names do not have to match. If the CALL statement was made with a three-part name and the current server is the same as the location in the three-part name, you can omit the location name and specify a two-part name.

procedure-name
Identifies the stored procedure that returned result set locators by the specified procedure name.
host-variable
Identifies the stored procedure that returned result set locators by the procedure name contained in the host variable.

Description

The ASSOCIATE LOCATORS statement assigns result set locator values from the SQLVAR sections of the SQLDA to result set locator variables so that the first SQLDATA field is assigned to the first locator variable, the second SQLDATA field to the second locator variable, and so on.

More than one locator can be assigned to a result set. You can issue the same ASSOCIATE LOCATORS statement more than once with different result set locator variables.

If the number of result set locator variables listed in the ASSOCIATE LOCATORS statement is less than the number of locators returned by the stored procedure, all variables in the statement are assigned a value, and a warning is issued.

If the number of result set locator variables listed in the ASSOCIATE LOCATORS statement is greater than the number of locators returned by the stored procedure, the extra variables are assigned a value of 0.

When the ASSOCIATE LOCATORS statement is executed, the procedure name or specification must identify a stored procedure that the requestor has already invoked using the CALL statement.

Note: For this statement to be successful, the application must be currently connected to the site at which the stored procedure was executed.

Examples

The statements in the following examples are assumed to be in COBOL programs.

Use result set locator variables LOC1 and LOC2 to get the result set locator values for the two result sets returned by stored procedure P1. Assume that the stored procedure is called with a one-part name from current server SITE2.

 EXEC SQL CONNECT TO SITE2;
 EXEC SQL CALL P1;
 EXEC SQL ASSOCIATE RESULT SET LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE P1;

Repeat the scenario above, but use a two-part name to specify an explicit schema name for the stored procedure to ensure that stored procedure P1 in schema MYSCHEMA is used.

 EXEC SQL CONNECT TO SITE2;
 EXEC SQL CALL MYSCHEMA.P1;
 EXEC SQL ASSOCIATE RESULT SET LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE MYSCHEMA.P1;

Use result set locator variables LOC1 and LOC2 to get the result set locator values for the two result sets that are returned by the stored procedure named by host variable HV1. Assume that host variable HV1 contains the value SITE2.MYSCHEMA.P1 and the stored procedure is called with a three-part name.

 EXEC SQL CALL SITE2.MYSCHEMA.P1;
 EXEC SQL ASSOCIATE LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE :HV1;

The preceding example would be invalid if host variable HV1 had contained the value MYSCHEMA.P1, a two-part name. For the example to be valid with that two-part name in host variable HV1, the current server must be the same as the location name that is specified on the CALL statement as the following statements demonstrate. This is the only condition under which the names do not have to be specified the same way and a three-part name on the CALL statement can be used with a two-part name on the ASSOCIATE LOCATORS statement.

 EXEC SQL CONNECT TO SITE2;
 EXEC SQL CALL SITE2.MYSCHEMA.P1;
 EXEC SQL ASSOCIATE LOCATORS (:LOC1, :LOC2)
          WITH PROCEDURE :HV1;
Parent topic: SQL Statements


BACKUP LOCATION

This XDB Server utility command copies the entire contents of an XDB Server location to the specified drive and path while the XDB Server location is still generally available.
Restriction: This topic applies to Windows environments only.

Invocation

BACKUP LOCATION can be executed interactively, embedded in a host language, or dynamically prepared.

Authorization

To use the BACKUP LOCATION command you must be a super user.

Syntax

BACKUP LOCATION location-name TO path-name
[INCREMENTAL]

Parameters:

location-name | Identifies the location to be backed up.
path-name | Specifies the parent target directory where backups are stored. Inside this directory, a subdirectory will be created that contains this backup’s contents. This subdirectory’s name is of the form xdbYYYYMMDDHHMMSSnnnnnn, where YYYYMMDDHHMMSS is the time of the backup, and nnnnnn is a relative sequence number.
INCREMENTAL | Indicates that you want to backup only your log files. Omitting this option results in your log files and your location’s database files being backed up.

Description

The BACKUP LOCATION command is used for backing up locations (including all associated databases, tables, catalog tables, and log files) to a secure device, such as a file server, or a different disk drive.

This is useful for avoiding losses due to media or machine failure. For instance, if the drive where your XDB location was located becomes inoperable, provided that you have issued a BACKUP LOCATION command that saved the entire contents of that location to another disk you can ROLLFORWARD that backup to recreate the corrupted location.

While the standard BACKUP LOCATION command copies both database and log files, in addition to creating a recovery script (xdbdata.bat), a BACKUP LOCATION INCREMENTAL backs up only the log files for your location.

After performing a standard backup (which is mandatory for all recovery scenarios), which type of backup you perform is up to you. Always performing standard backups takes longer than performing incremental backups but the recovery process from them is much easier and quicker. Performing incremental backups is quicker than performing standard backups but more ROLLFORWARD steps might be necessary to recreate your location.

Examples:

BACKUP LOCATION (Standard)
The following command creates a directory, such as d:\backuplocs\xdb20051017151315000001, that contains an xdbdata.bat script, database files and log files:
BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
BACKUP LOCATION (Incremental)
The following command creates a directory, such as d:\backuplocs\xdb20051017151315000002, that contains only log files:
BACKUP LOCATION MYLOC TO D:\BACKUPLOCS INCREMENTAL
Recovery with Standard Backups
The following sequence of events shows the typical steps in performing standard backups and subsequently recovering from a media failure:
  1. On Friday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  2. On Monday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  3. On Tuesday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  4. On Wednesday morning recover from a media failure using the following steps:
    1. Stop the XDB Server.
    2. Copy the contents of the current logs to another directory, such as d:\currlocs.
    3. Remove the contents of the original XDB location.
    4. Run the xdbdata.bat script in Tuesday afternoon’s d:\backuplocs subdirectory.
    5. Start the XDB Server in exclusive use mode.
    6. Issue the following ROLLFORWARD command:
      ROLLFORWARD MYLOC USING D:\CURRLOGS
    7. Stop the XDB Server.
    8. Restart the XDB Server for general availability.
Recovery with Incremental Backups
The following sequence of events shows the typical steps in performing incremental backups and subsequently recovering from a media failure:
  1. On Friday afternoon perform a standard backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS
  2. On Monday afternoon perform an incremental backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS INCREMENTAL

    This creates directory xdb20051015153015000002, for instance.

  3. On Tuesday afternoon perform an incremental backup using the following command:
    BACKUP LOCATION MYLOC TO D:\BACKUPLOCS INCREMENTAL

    This creates directory xdb20051016144416000003, for instance.

  4. On Wednesday morning recover from a media failure using the following steps:
    1. Stop the XDB Server.
    2. Copy the contents of the current logs to another directory, such as d:\currlocs.
    3. Remove the contents of the original XDB location.
    4. Run the xdbdata.bat script in Friday afternoon’s d:\backuplocs subdirectory.
    5. Start the XDB Server in exclusive use mode.
    6. Issue the following ROLLFORWARD commands:
      ROLLFORWARD MYLOC USING D:\BACKUPLOCS\XDB20051015153015000002
ROLLFORWARD MYLOC USING D:\BACKUPLOCS\XDB20051016144416000003
ROLLFORWARD MYLOC USING D:\CURRLOGS
    7. Stop the XDB Server.
    8. Restart the XDB Server for general availability.
Parent topic: SQL Statements


BEGIN DECLARE SECTION

The BEGIN DECLARE SECTION statement (embedded SQL only) marks the beginning of a host variable declare section in an application program.
Restriction: This topic applies to Windows environments only.

Invocation

BEGIN DECLARE SECTION is not an executable statement. It can only be embedded in a host language.

Authorization

No special authorization is required.

Syntax

BEGIN DECLARE SECTION

Description

BEGIN DECLARE SECTION may be used in an application program to mark the beginning of the section of code where host variables are declared. If a BEGIN DECLARE SECTION is used, the host variable declaration section must end with the END DECLARE SECTION statement.

When programming in C, or when the DECLARE or ANSI COBOL preprocessor directives are used, BEGIN and END DECLARE SECTION commands must surround the declarations for all host variables, to create host variable declaration blocks. As illustrated in the COBOL example below, a host variable declaration block can appear anywhere that the host language allows variable declarations:

EXEC SQL BEGIN DECLARE SECTION;
        short int cust_num = 28;
        char name[30];
EXEC SQL END DECLARE SECTION;

The following rules are enforced by the precompiler, only if C is the host language, or if the DECLARE or ANSI COBOL precompiler option is specified:

  • Variables referenced within SQL statements must be declared within the variable declaration section of the host program.
  • There must be a paired set of BEGIN DECLARE SECTION and END DECLARE SECTION statements.
Note:

Only if the DECLARE or the ANSI COBOL precompiler directive is specified or the host language is C, are host variable declaration sections required. Any source program, in any host language, can be made to conform to the SAA definition of SQL by specifying a declare section. If variable declaration sections are used when they are not required, all variables declared outside the declare section must have a name different from all variable names declared within the declare section.

Parent topic: SQL Statements


BULK

The BULK ON command activates the Bulk Upload feature which increases the efficiency of your transactions between the mainframe and XDB Link. The BULK OFF command turns off the Bulk Upload feature.
Restriction: This topic applies to Windows environments only.

Invocation

BULK ON and BULK OFF are not executable statements. They can only be embedded in a host language.

Note:

To use the BULK ON and BULK OFF commands, you must include the XDBFUNCS directive as explained in your COBOL precompiler manual.

Authorization

No special authorization is required.

Syntax

BULK [ON | OFF]

Description

The BULK ON command optimizes communications between the mainframe and XDB Link. BULK ON sets internal indicators allowing XDB Link to operate in Bulk Upload mode -- whereby INSERT, UPDATE and DELETE statements are sent to the mainframe as usual, but the SQLCA response buffers are not sent back to the XDB Link until a bulk interval has been reached. This reduction in the number of SQLCA responses optimizes upload performance by reducing the number of LU6.2 line turn-around events associated with the upload procedure.

The bulk interval for the upload is determined by the Upload Pacing Limit value specified in the Location Configuration dialog box in the Gateway Profile Utility or by a COMMIT statement. If, for example, the interval is set to 10, then every tenth SQL upload statement (such as INSERT, UPDATE and DELETE) contains an active SQLCA indicating the true SQLCODE for the bulk process.

Bulk Upload mode can be deactivated by issuing a BULK OFF statement, which terminates Bulk Upload mode for all subsequent transactions. If an SQL error has occurred in the bulk upload interval, it is returned in the next live SQLCA. A live SQLCA (reporting the true status of the bulk interval) is returned either at the end of a bulk interval or with the next statement following a BULK OFF command.

Note:

A live SQLCA is also returned if a SELECT statement is inadvertently issued in the middle of a bulk upload process. It must be noted that this SQLCA is reporting the status of the bulk interval, and not the SELECT statement.

Error Handling

With any SQL error, a nonzero SQLCODE is returned. The SQLERRD[3] field of the SQLCA indicates the first statement to fail in the bulk interval. You can also terminate the interval with a COMMIT. The COMMIT in this case is not executed, and you can choose to re-issue the COMMIT (not recommended) or ROLLBACK the entire bulk upload interval.

SQLCA Status

SQLCA information is loaded after each SQL call. The status of the SQLCA is indicated by the SQLERRD[3] field:

SQLERRD[3] = -1

Inactive SQLCA. A pseudo-SQLCA is being sent to the client because the client application is in the middle of a bulk upload interval.

SQLERRD[3] = 0

Active SQLCA. Indicates a successful return of all SQLCAs for all SQL statements in the bulk upload interval. Along with the SQLCODE, shows the status of the bulk process.

SQLERRD[3] > 0

Active SQLCA. An error has occurred in this bulk interval. SQLERRD[3] is indicating the number of SQL statements that qualify for failure based on the first SQL statement failure. SQLCODE shows the SQL error for the failing SQL statement.

Examples:

In the following scenario the Bulk Interval is set to a value of 10, with the third SQL statement in error:

SQLERRD[3] = 8

Indicates that eight SQL statements (the third through the tenth) are in doubt (with the first two being all right).

SQLCODE = -551

Indicates that an authorization error occurred on the third (or failed) SQL statement.

You could choose to ROLLBACK this bulk process, and re-execute (using BULK OFF) to monitor each failure.

The following steps are recommended for turning off bulk upload mode, and checking for errors:

EXEC SQL BULK OFF
EXEC SQL COMMIT

Finally, test the SQLCODE value for errors. If errors are found, issue a ROLLBACK.

Parent topic: SQL Statements


CALL

The XDB Server can run a stored procedure on the mainframe (through XDB Link) or on an XDB Server through use of the CALL statement.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

The privileges required to execute the CALL statement are determined by the owner of the package or plan that contains the CALL statement. If the server is DB2 for MVS/ESA (or an XDB Server), that AuthID must have either the EXECUTE privilege on the package associated with the stored procedure, ownership of the package associated with the stored procedure, PACKADM authority for the package's collection, or SYSADM authority.

The authorization ID that must have the EXECUTE privilege on the stored procedure depends on the form of the CALL statement:

  • For static SQL programs that use the syntax CALL procedure, the owner of the plan or package that contains the CALL statement must have one of the following:
    • The EXECUTE privilege on the stored procedure
    • Ownership of the stored procedure
    • SYSADM authority
  • For static SQL programs that use the syntax CALL host variable (ODBC applications use this form of the CALL statement), the authorization ID of the plan or package that contains the CALL statement must have one of the following:
    • The EXECUTE privilege on the stored procedure
    • Ownership of the stored procedure
    • SYSADM authority

The authorization that is required to run the stored procedure package and any packages that are used under the stored procedure apply to any form of the CALL statement as follows:

Stored procedure package

One of the authorization IDs that are defined below under Set of authorization IDs must have at least one of the following on the stored procedure package:

  • The EXECUTE privilege on the package
  • Ownership of the package
  • PACKADM authority for the package's collection
  • SYSADM authority

A PKLIST entry is not required for the stored procedure package.

Syntax

CALL {procedure-name | host-variable}
[({expression | NULL | TABLE transition-table-name}[,...]) |
USING DESCRIPTOR descriptor-name]

Parameters:

procedure-name | A qualified or unqualified name that identifies the stored procedure. Procedure names can be three-part, two-part or unqualified one-part names. A fully qualified procedure name begins with a location name that identifies the DBMS at which the procedure is stored. The second and third parts identify the stored procedure. A period must separate each of the parts.
host-variable-1 | Character string variable with a maximum length of 254 bytes that identifies the stored procedure by the value of the specified host variable. This host variable must be preceded by a colon and must not be followed by an indicator variable.
host-variable-2 | Identifies a parameter of the CALL statement. The host variable must identify a host variable (not a structure) described in the program according to the rules for declaring host variables. The data type of the variable must be compatible with the data type of the corresponding parameter of the stored procedure.
constant | A parameter of the stored procedure expressed as a constant in the CALL statement. The data type of the constant must be compatible with the corresponding parameter of the stored procedure and that parameter must be defined as IN.
NULL | A parameter of the stored procedure expressed as a NULL value in the CALL statement. The corresponding parameter of the stored procedure must be defined as IN, and the description of the stored procedure must allow for null parameters.
descriptor-name | Identifies an SQLDA that must contain a valid description of host variables. In C, the descriptor-name can be a pointer to an SQLDA.

Description

A stored procedure is invoked by the CALL statement, which passes a list of parameters to the procedure. When the CALL statement is executed, the procedure name specified must identify a stored procedure that exists at the application server. If the server is DB2 for MVS/ESA (or an XDB Server), the last or only part of the name must be equal to some value of the NAME column of the SYSIBM.SYSROUTINES catalog table.

DB2 and the XDB Server use the information stored in SYSIBM.SYSROUTINES and SYSIBM.SYSPARMS to automatically activate a stored procedure definition, which includes identification of the parameter list used to implement the stored procedure. The parameters issued in your procedure's CALL statement must correspond to the parameters defined in SYSIBM.SYSPARMS.

procedure-name or host-variable

Identifies the stored procedure to call. The procedure name can be specified as a character string constant or within a host variable.

A procedure name is a qualified or unqualified name. Each part of the name must be composed of SBCS characters:

  • A fully qualified procedure name is a three-part name. The first part is a long identifier that contains the location name that identifies the DBMS at which the procedure is stored. The second part is a short identifier that contains the schema name of the stored procedure. The last part is a long identifier that contains the name of the stored procedure. A period must separate each of the parts. Any or all of the parts can be a delimited identifier.
  • A two-part procedure name has one implicit qualifier. The implicit qualifier is the location name of the current server. The two parts identify the schema name and the name of the stored procedure. A period must separate the two parts.
  • An unqualified procedure name is a one-part name with two implicit qualifiers. The first implicit qualifier is the location name of the current server. The second implicit qualifier depends on the application server. If the server is DB2 for OS/390, the implicit qualifier is the schema name. DB2 uses the SQL path to determine the value of the schema name.
  • If the procedure name is specified as a literal on the CALL statement (CALL procedure-name), the SQL path is the value of the PATH bind option that is associated with the calling package or plan.
  • If a host variable is specified for the procedure name on the CALL statement (CALL host-variable), the SQL path is the value of the CURRENT PATH special register.

DB2 searches the schema names in the SQL path from left to right until a stored procedure with the specified schema name is found in the DB2 catalog. When a matching schema.procedure-name is found, the search stops only if the following conditions are true:

  • The user is authorized to call the stored procedure.
  • The number of parameters in the definition of the stored procedure matches the number of parameters specified on the CALL statement.
  • The create timestamp for the stored procedure must be older than the bind timestamp for the package or plan in which the procedure is invoked.

If the list of schemas in the SQL path is exhausted before the procedure name is resolved, an error is returned.

If a host variable is used:

  • It must be a character string variable with a length attribute that is not greater than 255.
  • It must not be followed by an indicator variable.
  • The value of the host variable is a specification that depends on the application server. Regardless of the application server, the specification must:
    • Be left justified within the host variable
    • Not contain embedded blanks
    • Be padded on the right with blanks if its length is less than that of the host variable

In addition, the specification can:

  • Contain upper and lowercase characters. Lowercase characters are not folded to uppercase.
  • Use a delimited identifier for any part of a the three-part procedure name.

When the CALL statement is executed, the procedure name or specification must identify a stored procedure that exists at the application server.

When the package that contains the CALL statement is bound, the stored procedure that is invoked must be created if VALIDATE(BIND) is Specified. Although the stored procedure does not need to be created at bind time if VALIDATE(RUN) is specified, it must be created when the CALL statement is executed.

Parameters (Expression, Null, Table Transition-Table-Name)

Identifies a list of values to be passed as parameters to the stored procedure. If USING DESCRIPTOR is specified, each host variable described by the identified SQLDA is a parameter of the CALL statement. If host structures are not specified in the CALL statement, the nth parameter of the CALL statement corresponds to the nth parameter in the stored procedure, and the number of parameters in each must be the same. Otherwise, each reference to a host structure is replaced by a reference to each of the variables contained in that host structure, and the resulting number of parameters must be the same as the number of parameters defined for the stored procedure.

Each parameter of a stored procedure is described at the server. In addition to attributes such as data type and length, the description of each parameter indicates how the stored procedure uses it:

  • IN means as an input value
  • OUT means as an output value
  • INOUT means both as an input and an output value

When the CALL statement is executed, the value of each of its parameters is assigned to the corresponding parameter of the stored procedure. In cases where the parameters of the CALL statement are not an exact match to the data types of the parameters of the stored procedure, each parameter specified in the CALL statement is converted to the data type of the corresponding parameter of the stored procedure at execution. The conversion occurs according to the same rules as assignment to columns.

Conversion can occur when precision, scale, length, encoding scheme, or CCSID differ between the parameter specified in the CALL statement and the data type of the corresponding parameter of the stored procedure. Conversion might occur for a character string parameter specified in the CALL statement when the corresponding parameter of the stored procedure has a different encoding scheme or CCSID. For example, an error occurs when the CALL statement passes mixed data that actually contains DBCS characters as input to a parameter of the stored procedure that is declared with an SBCS subtype. Likewise, an error occurs when the stored procedure returns mixed data that actually contains DBCS characters in the parameter of the CALL statement that has an SBCS subtype.

expression

The parameter is the result of the specified expression, which is evaluated before the stored procedure is invoked.

If expression is a single host variable, the corresponding parameter of the procedure can be defined as IN, INOUT, or OUT. Otherwise, the corresponding parameter of the procedure must be defined as IN. In addition, the host variable can identify a structure. Any host variable or structure that is specified must be described in the application program according to the rules for declaring host structures and variables. A reference to a host structure is replaced by a reference to each of the variables contained in the host structure.

If the result of the expression can be the null value, either the description of the procedure must allow for null parameters or the corresponding parameter of the procedure must be defined as OUT.

The following additional rules apply depending on how the corresponding parameter was defined in the CREATE Procedure statement for the procedure:

  • expression can contain references to multiple host variables. expression cannot include a column name or column function or a user-defined function that is sourced on a column function.
  • INOUT or OUT expression can only be a single host variable.

NULL

The parameter is a null value. The corresponding parameter of the procedure must be defined as IN and the description of the procedure must allow for null parameters.

TABLE transition-table-name

The parameter is a transition table and it is passed to the procedure as a table locator. . You can use the CALL statement with the TABLE clause only within the definition of the triggered action of a trigger. The name of a transition table must be specified in the CALL statement if the corresponding parameter of the procedure was defined in the TABLE LIKE clause of the CREATE PROCEDURE statement.

The XDB Server operating environment does not currently provide this functionality.

USING DESCRIPTOR descriptor-name

Identifies an SQLDA that contains a valid description of the host variables that are to be passed as parameters to the stored procedure. If the stored procedure has no parameters, an SQLDA is ignored.

Before the CALL statement is processed, the user must set the following fields in the SQLDA:

  • SQLN to indicate the number of SQLVAR occurrences provided in the SQLDA. This number must not be less than SQLD. This field is not part of the REXX SQLDA and therefore does not need to be set for REXX programs.
  • SQLDABC to indicate the number of bytes of storage allocated for the SQLDA. This number must be not be less than SQLN*44+16. This field is not part of the REXX SQLDA and therefore does not need to be set for REXX programs.
  • SQLD to indicate the number of variables used in the SQLDA when processing the statement. This number must be the same as the number of parameters of the stored procedure.
  • SQLVAR occurrences to indicate the attributes of the variables.

Variable Usage

Each specification of a host-variable, constant or NULL is a parameter of the CALL statement. If USING DESCRIPTOR is specified, each host variable described by the identified SQLDA is a parameter of the CALL statement. The nth parameter of the CALL statement corresponds to the nth parameter of the stored procedure. When the CALL statement is executed, the number of parameters of the stored procedure and each pair of corresponding parameters must be consistent.

A description of each parameter describes how that parameter is used by the stored procedure. In addition to parameter attributes such as data type and length, the following information on each parameter is also stored in SYSIBM.SYSPROCEDURES:

  • IN: used only as an input value
  • OUT: used only as an output value
  • INOUT: used as both input and output value
Note:

When a trigger issues a CALL statement to invoke a stored procedure, the parameters that are specified in the CALL statement cannot be host variables and the USING DESCRIPTOR clause cannot be specified.

A program that is executing as a stored procedure, a user-defined function, or a trigger can issue a CALL statement. When a stored procedure, user-defined function, or trigger calls a stored procedure, user-defined function, or trigger, the call is considered to be nested. Stored procedures, user-defined functions, and triggers can be nested up to 16 levels deep on a single system. Nesting can occur within a single DB2 subsystem or when a stored procedure or user-defined function is invoked at a remote server.

If a stored procedure returns any query result sets, the result sets are returned to the caller of the stored procedure. If the SQL CALL statement is nested, the result sets are visible only to the program that is at the previous nesting level.

Some stored procedures cannot be nested. A stored procedure, user-defined function, or trigger cannot call a stored procedure that is defined with the COMMIT ON RETURN attribute. A stored procedure can call another stored procedure only if they execute in the same type of address space; they must both execute in a DB2-established address space or in a WLM-established address space.

Example:

The following CALL statement activates a stored procedure named alpha:

EXEC SQL CALL alpha (:P1, :A1, :ED1, :type, :code)
Parent topic: SQL Statements


CHECKPOINT

CHECKPOINT is an SQL command which flushes the database and log files.
Restriction: This topic applies to Windows environments only.

Invocation

CHECKPOINT is an executable command that can be issued interactively or embedded in a host language.

Authorization

SYSADM or higher authority is required to use the CHECKPOINT command.

Syntax

CHECKPOINT

Description

Under normal operating conditions CHECKPOINT commands are issued automatically by the logging system at regular time intervals (see lCheckpointFreq Parameter below). Some occasions, however, warrant issuing a CHECKPOINT command within SQLWizard as a precautionary measure. If you know (or suspect) that the server must be taken down, and you can still access SQLWizard, then issue a CHECKPOINT. This action minimizes crash recovery time when the server is brought back up.

lCheckpointFreq Parameter

One of the factors affecting the length of time needed to return location data objects to a logically consistent state after a transient system failure (for example, power outage, operating system failure) is the value of the lCheckpointFreq configuration parameter. Changing the value of this parameter (set in the [XDBLogManager] section of thexdbsrvco.ini file) allows the user to increase or decrease the time interval between automatic checkpoints issued by the logging system.

lCheckpointFreq is defaulted to a value of 300 seconds, which means that the logging system automatically performs a checkpoint every five minutes. If this checkpoint interval is adjusted upward, more time could be necessary for log recovery after a transient system failure. Conversely, a shorter checkpoint interval could reduce average recovery time, but increase system overhead. See the Server Administration Guide for more information on the lCheckpointFreq parameter.

Parent topic: SQL Statements


CLOSE

The CLOSE command (embedded SQL only) closes a cursor previously opened by a DECLARE CURSOR command. If a temporary table is created as a result of the cursor, that table is deleted when the cursor is closed.
Restriction: This topic applies to Windows environments only.

Invocation

CLOSE is an executable command that can only be embedded in a host language. CLOSE cannot be dynamically prepared.

Authorization

See Authorization under the DECLARE CURSOR command topic for the authorization required to use a cursor.

Syntax

CLOSE cursor-name

Parameters:

cursor-name: Identifies the cursor opened by a DECLARE CURSOR command.

Description

A CLOSE command is checked for all syntactical elements. The cursor must have been previously declared relative to the source program line in which CLOSE is encountered.

Example:

The following example (in the C language) declares a cursor named deptemp using the EMPLOYEE table, and then closes the cursor:

EXEC SQL
    DECLARE CURSOR deptemp FOR
        SELECT * FROM employee
            WHERE dept = :deptno
;....
EXEC SQL
    CLOSE deptemp;
Note: If the WITH HOLD option is not specified in the declaration of a cursor, then that cursor (when opened) is implicitly closed when a unit of work is terminated. Performance can be improved, however, by explicitly closing cursors as soon as possible. A CLOSE command does not necessarily commit or rollback system changes or updates (unless AUTOCOMMIT is on).
Parent topic: SQL Statements


COMMENT ON

The COMMENT ON statement adds or replaces descriptive text comments for aliases, columns, distinct types (currently not supported), stored procedures, tables, triggers, user-defined functions, and views located within the current XDB Server location. All comments are stored in the catalog tables belonging to that location.
Restriction: This topic applies to Windows environments only.

Invocation

COMMENT ON is an executable command that can be issued interactively or embedded in a host language. COMMENT ON can be dynamically prepared.

Authorization

For a comment on a table, view, alias, index, or column, the privilege set that is defined below must include at least one of the following:

  • Ownership of the table, view, alias, or index
  • DBADM authority for its database (tables and indexes only)
  • SYSADM or SYSCTRL authority

For a comment on a distinct type, stored procedure, trigger, or user-defined function, the privilege set that is defined below must include at least one of the following:

  • Ownership of the distinct type, stored procedure, trigger, or user-defined function
  • The ALTERIN privilege on the schema (for the addition of comments)
  • SYSADM or SYSCTRL authority

For a comment on a plan or package, the privilege set that is defined below must include at least one of the following:

  • Ownership of the plan or package
  • SYSADM or SYSCTRL authority

For a comment on a sequence, the privilege set that is defined below must include at least one of the following:

  • Ownership of the sequence
  • The ALTER privilege for the sequence
  • The ALTERIN privilege on the schema
  • SYSADM or SYSCTRL authority

Syntax

COMMENT ON
{
TABLE {table-name | view-name}
    | COLUMN {table-name | view-name}.column-name
    | ALIAS alias-name
    | DISTINCT TYPE distinct-type-name
    | FUNCTION function-name [(parameter-type[,...])]
    | PROCEDURE procedure-name
    | SPECIFIC FUNCTION specific-name
    | TRIGGER trigger-name
    | PACKAGE collection-id.package-name [VERSION | version-id]
    | PLAN plan-name
    | PROCEDURE procedure-name
    | SEQUENCE sequence-name
}
IS string-constant

or:

COMMENT ON {table-name | view-name}
(column-name IS string-constant [,...])

Parameters:

table-name or view-name or alias-name | Identifies the table, view or alias affected.
column-name | Identifies the name of the column affected. When the COLUMN keyword is used, column names must be qualified with the name of the table or view that contains them.
string-constant | Specifies the comment you want to place in the system table. The string may be up to 254 characters in length, enclosed in double or single quotation marks.

Description

The COMMENT ON statement is used for adding a comment to, or replacing an existing comment in the REMARKS column of the SYSIBM.SYSCOLUMNS or SYSIBM.SYSTABLES table. These comments prove very useful in documenting the purpose of tables, views, columns and aliases, and may be selected using a SELECT command, and incorporated into application documentation. Remarks columns are defined as character fields, with a maximum length of 254 characters.

ALIAS alias-name

The ALIAS clause is used to comment on an alias. If you use the COMMENT ON ALIAS format, the comment is placed in the REMARKS column of the SYSIBM.SYSTABLES table, in the row describing the specified table or view.

COLUMN table-name.column-name or view-name.column-name

Identifies the column to which the comment applies. The name must identify a column of a table or view that exists at the current server. The name must not identify a column of a declared temporary table. The comment is placed into the REMARKS column of the SYSIBM.SYSCOLUMNS catalog table, for the row that describes the column.

Do not use TABLE or COLUMN to comment on more than one column in a table or view. Give the table or view name and then, in parentheses, a list in the form:

  • column-name IS string-constant,
  • column-name IS string-constant,...

The column names must not be qualified, each name must identify a column of the specified table or view, and that table or view must exist at the current server.

DISTINCT TYPE distinct-type-name

Identifies the distinct type to which the comment applies. distinct-type-name must identify a distinct type that exists at the current server.

The comment is placed in the REMARKS column of the SYSIBM.SYSDATATYPES catalog table for the row that describes the distinct type.

FUNCTION

Identifies the function to which the comment applies. The function must exist at the current server, and it must be a function that was defined with the CREATE FUNCTION statement or a cast function that was generated by a CREATE DISTINCT TYPE statement. The comment is placed in the REMARKS column of the SYSIBM.SYSROUTINES catalog table for the row that describes the function.

If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name

Identifies the particular function, and is valid only if there is exactly one function with function-name.

FUNCTION function-name (parameter-type,...)

Provides the function signature, which uniquely identifies the function.

function-name | Identifies the name of the function.
(parameter-type,...) | Identifies the parameters of the function.

The data types of the parameters must match the data types that were specified on the CREATE FUNCTION statement in the

corresponding position. The number of data types and the logical concatenation of the data types are used to identify the specific function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that DB2 ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

    CHAR CHAR(1)

    GRAPHIC GRAPHIC(1)

    DECIMAL DECIMAL(5,0)

    FLOAT DOUBLE (length of 8)

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that DB2 ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name

Identifies the particular function using the specific name either specified or defaulted to when the function was created.

PROCEDURE procedure-name

Identifies the stored procedure to which the comment applies. procedure-name must identify a stored procedure that has been defined with the CREATE PROCEDURE statement at the current server. The comment is placed in the REMARKS column of the SYSIBM.SYSROUTINES catalog table for the row that describes the stored procedure.

TABLE table-name or view-name

Identifies the table or view to which the comment applies. table-name or view-name must identify a table, auxiliary table, or view that exists at the current server. table-name must not identify a declared temporary table. The comment is placed in the REMARKS column of the SYSIBM.SYSTABLES catalog table for the row that describes the table or view.

TRIGGER trigger-name

Identifies the trigger to which the comment applies. trigger-name must identify a trigger that exists at the current server. The comment is placed in the REMARKS column of the SYSIBM.SYSTRIGGERS catalog table for the row that describes the trigger.

PACKAGE collection-id.package-name

Identifies the package to which the comment applies. You must qualify the package name with a collection ID. collection-id.package-name must identify a package that exists at the current server. The name plus the implicitly or explicitly specified version-id must identify a package that exists at the current server. Omitting version-id is an implicit specification of the null version.

PLAN plan-name

Identifies the plan to which the comment applies. plan-name must identify a plan that exists at the current server.

PROCEDURE procedure-name

Identifies the stored procedure to which the comment applies. procedure-name must identify a stored procedure that has been defined with the CREATE PROCEDURE statement at the current server. The comment is placed in the REMARKS column of the SYSIBM.SYSROUTINES catalog table for the row that describes the stored procedure.

SEQUENCE sequence-name

Identifies the sequence to which the comment applies. The combination of name and implicit or explicit schema name must identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs. sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column. The comment is placed in the REMARKS column of the SYSIBM.SYSSEQUENCES catalog table for the row that describes the sequence.

IS string-constant

Introduces the comment that you want to make. string-constant can be any SQL character string constant of up to 254 characters.

Examples:

To place a comment on the PART table, use a command like:

COMMENT ON TABLE part
    IS "Information on all parts in use."

To place a comment on a view named redparts use a command like:

COMMENT ON TABLE redparts
    IS "View of parts table containing info on all red parts in use."

To place a comment on the CITY column of the SUPPLIER table, use a command like:

COMMENT ON COLUMN supplier.city
    IS "City where supplier is headquartered."

To place a comment on both the COMPANY and BALANCE columns of the CUSTOMER table, use the command below:

COMMENT ON customer
    (company IS "Corporate name of the client",
     balance IS "Outstanding as of last billing")
Parent topic: SQL Statements


COMMIT

The COMMIT statement is used to mark the end of a transaction (unit of work) and preserve all of the database changes made by the transaction.
Restriction: This topic applies to Windows environments only.

Invocation

COMMIT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared. COMMIT cannot be used in CICS or IMS environments.

Authorization

No special authorization is required.

Syntax

COMMIT [WORK]

Description

A transaction begins when a previous transaction ends or when logging begins (see the SET LOG command). A transaction is terminated by a COMMIT or ROLLBACK command.

Only the results of SQL commands executed within a single, uncommitted transaction are affected by the COMMIT command. When the COMMIT command is issued, all table changes caused by EXPLAIN, GRANT, REVOKE, COMMENT ON, LABEL ON, INSERT, UPDATE, and DELETE commands in the transaction are made permanent, and can no longer be rolled back (the CREATE, DROP and ALTER commands can never be rolled back).All savepoints that were set within the transaction are released

In DB2 mode, open cursors declared without the WITH HOLD option are closed and any statements prepared for those cursors are destroyed. All open cursors declared with the WITH HOLD option are preserved, along with any statements that were prepared for these cursors. In XDB mode, all cursors remain open at commit time.

For existing connections, all LOB locators are disassociated, except for those locators for which a HOLD LOCATOR statement has been issued without a corresponding FREE LOCATOR statement.

All implicitly acquired locks are released, except:

  • Locks that are required for the cursors that were not closed
  • Table and table space locks when the RELEASE parameter on the bind command was not RELEASE(COMMIT)
  • LOB locks and LOB table space locks that are required for held LOB locators

An implicit COMMIT is always performed when exiting from the current session. All locks acquired during a transaction are released by the COMMIT command.

All rows of every declared temporary table of the application process are deleted with these exceptions:

  • The rows of a declared temporary table that is defined with the ON COMMIT PRESERVE ROWS atttribute are not deleted.
  • The rows of a declared temporary table that is defined with the ON COMMIT DELETE ROWS attribute are not deleted if any program in the application process has an open WITH HOLD cursor that is dependent on that table.

The optional keyword WORK is provided for compatibility with the SAA definition of SQL, and is available in DB2. COMMIT and COMMIT WORK perform identically.

Parent topic: SQL Statements


COMPACT

Use the COMPACT command to pack table, index and dictionary files in order to reuse disk storage space.
Restriction: This topic applies to Windows environments only.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

No special authorization is required.

Syntax

COMPACT
{
    LOCATION [AND INDEX] [NO CLUSTER] [NOSTOP] [RULES DB2]|
    DIRECTORIES |
    TABLE table-name [AND INDEXES] [NO CLUSTER] [RULES DB2]|
    TABLES [LIKE pattern] [IN DATABASE db-name] [NOSTOP] [CLUSTER BY INDEX index-name] [RULES DB2]|
    INDEXES [LIKE pattern] [IN DATABASE db-name] [NOSTOP]
}
Note:

Keyword order is significant. When used, keywords must appear in the order specified below.

Parameters:

table-name | Identifies the name of the table that you want to compact.
index-name | Identifies the name of a table index that determines the physical order of records in the table.
db-name | Identifies the name of the database that you want to compact.
pattern | Defines pattern-matching criteria for a 2-part table name (use same pattern-matching syntax as for the LIKE Operator). For example, SYS%.SYSC% and SALES%.%.

Description

XDB Server locations consist of table, index and dictionary files. When these object are altered or deleted, the files may become disorganized, increasing the amount of space occupied and the amount of time required to perform searches. To optimize table and dictionary file structures, you can pack specific location objects using the COMPACT command.

During processing, the COMPACT command must create a temporary copy of the specified file(s).. If the size of the largest file exceeds the free space on the storage device you are using, an error results, and the object being packed is restored to its original condition.

LOCATION

If the keyword LOCATION appears in the command syntax, the entire location is packed (including all tables and dictionary files), and all location indexes rebuilt. If a clustered index exists on a table, then the records in that table are also reclustered (swapped so they are arranged in the same physical order as the clustering index), unless the NO CLUSTER option is specified.

Use the RULES DB2 clause to pad char fields (non-FOR BIT DATA only) with blank characters during the compacting process. This option is useful for converting tables initially populated in XDB mode to standard DB2 format for character data.

Use the NOSTOP clause to enable the XDB Server to continue processing after an error. Without the NOSTOP clause, the server stops executing the COMPACT command as soon as it encounters the first error. With the NOSTOP clause, if the server encounters an error as it processes a table, it writes the error to a trace file then continues packing the next table. This option is useful for performing a COMPACT in unattended mode.

Note: We strongly recommend that you make a backup copy of the location to be compacted before executing the COMPACT LOCATION command.

DIRECTORIES

The keyword DIRECTORIES packs only location dictionary files to remove information about deleted data objects. Table and index files are not affected.

TABLE

The TABLE keyword is used to compact a single table. The optional AND INDEXES and NO CLUSTER clauses function the same on a single table as with multiple tables (when using the TABLES keyword).

The optional CLUSTER BY INDEX clause is used to physically reorder the table records according to the index-name specified. The CLUSTER BY INDEX and NO CLUSTER clauses are mutually exclusive. If you use both CLUSTER BY INDEX and NO CLUSTER, the NO CLUSTER clause is ignored.

Use the RULES DB2 clause to pad char fields (non-FOR BIT DATA only) with blank characters during the compacting process. This option is useful for converting tables initially populated in XDB mode to standard DB2 format for character data.

TABLES

If the keyword TABLES appears without the AND INDEXES clause, only the table files within the current location are compacted. Indexes are rebuilt only if a table contains deleted records. If a table contains deleted records and a clustered index, then the clustered index is rebuilt and the table records reordered (unless the NO CLUSTER clause is added).

Including the optional AND INDEXES clause forces all table indexes in the location (including all primary, unique and foreign keys) to be dropped and rebuilt. All tables with clustered indexes are therefore reclustered, unless the NO CLUSTER clause is specified.

Use the NOSTOP clause to enable the XDB Server to continue processing after an error. Without the NOSTOP clause, the server stops executing the COMPACT command as soon as it encounters the first error. With the NOSTOP clause, if the server encounters an error as it processes a table, it writes the error to a trace file then continues packing the next table. This option is useful for performing a COMPACT in unattended mode.

Use the RULES DB2 clause to pad char fields (non-FOR BIT DATA only) with blank characters during the compacting process. This option is useful for converting tables initially populated in XDB mode to standard DB2 format for character data.

INDEXES

The INDEXES keyword rebuilds location indexes only and leaves the tables alone. If clustered indexes exist on any tables, those tables are reclustered unless NO CLUSTER is specified.

Use the NOSTOP clause to tell the XDB Server to automatically continue to with the next index when an error occurs in the one it is processing. (If this option is not used, the entire process terminates immediately on error.) COMPACT writes the error to a trace file (XDBTRACE.OUT) before continuing to the next index. This option is useful for performing a COMPACT in unattended mode.

Example:

To compact the CUSTOMER table use the command:

COMPACT TABLE customer

To compact only the dictionary files of the current location, use the command:

COMPACT DIRECTORIES

To compact the entire current location, including the dictionary files and all tables, use the command:

COMPACT LOCATION

To compact the EMPLOYEE table, and physically reorder the records by PAYRATE column values (assuming the index payidx has already been built on the PAYRATE column of the EMPLOYEE table) use the following command:

COMPACT TABLE employee CLUSTER BY INDEX payidx

If the payidx index was built as a clustered index the command:

COMPACT TABLE employee

could be used without the explicit CLUSTER BY INDEX clause.

To rebuild all indexes that exist on the EMPLOYEE table, issue the command:

COMPACT TABLE employee AND INDEX

To compact all tables in the current location, issue the command:

COMPACT TABLES

To compact all indexes in the current log, issue the command:

COMPACT INDEXES

To compact all XDB Server system tables, issue the command:

COMPACT TABLES LIKE SYSXDB%.%
Parent topic: SQL Statements


CONNECT

The CONNECT statement (embedded SQL only) connects the application process to the specified XDB Server or DB2 (through XDB Link) location. This location becomes the current location for the application process.
Restriction: This topic applies to Windows environments only.

Invocation

CONNECT is an executable statement that can only be embedded in an application program. It cannot be dynamically prepared.

Authorization

The primary AuthID for the application process must be authorized to connect to the specified location. The specific AuthID required is determined by that location, with the authorization check also performed by that location.

Syntax

CONNECT
    [TO {location-name | host-variable}]
    [RESET]

Parameters:

location-name | Identifies a specific XDB Server system location.
host-variable | Names a host variable name containing a location name.

Description

The CONNECT statement is the embedded SQL equivalent of the interactive SET LOCATION TO command. The CONNECT statement connects an application process to a designated location or a host-variable containing a location name. When the CONNECT statement is executed, the location name must be known to the local XDB Server running the application, or the location name must appear in the LOCATION column of the SYSIBM.SYSLOCATIONS catalog within the SYSTEM location.

Host variables must conform to the following requirements:

  • Must be a character string variable with a length attribute of at least 16 characters.
  • Must be preceded by a colon and not be followed by an indicator variable.
  • Within the host variable, the location name must be left-justified and conform to the rules for forming an ordinary location identifier.
  • If the location name length is less than the length of the host variable, the remainder of the host variable must be padded on the right with blanks.

If the CONNECT statement execution is successful:

  • The application process is connected to the identified location.
  • The CURRENT SERVER special register is updated to contain the specified location name.
  • The SQLERRP field of the SQLCA is set to contain information about the location. This information has the format pppvvrrm, where:
    ppp | identifies the product (for example, XDB or DB2)
    vv | contains a two-digit version identifier (for example, '04')
    rr | contains a two-digit release identifier (for example, '00')
    m | is a one-letter operating system indicator as follows:
    D

    DOS

    N

    Windows NT

    O

    OS/2

    For example, if running XDB Server for OS/2, the SQLERRP is XDB0400O.

Examples:

The following code excerpt connects the application process to the system location:

EXEC SQL
    CONNECT TO system;

To connect the application to a location named in the host variable nameloc, execute the following command:

EXEC SQL
    CONNECT TO :nameloc;

The XDB Server implements the CONNECT command identically to DB2, except that the XDB Server improves performance by leaving the old location open after connecting with the new location.

CONNECT RESET

The CONNECT RESET statement is equivalent to a CONNECT TO specifying the local XDB Server location.

Note:

Issuing this command is the only way to get back to an XDB Server location after connecting to a DB2 subsystem through the XDB Link.

CONNECT

The keyword CONNECT by itself returns information about the currently set XDB Server location. This information is placed in the SQLERRP field of the application SQLCA.

Note:

The initial server of an application process is the currently set XDB Server location. An explicit or implicit execution of a CONNECT [TO] statement can establish a different location. A CONNECT [TO] statement directed to the currently set location is treated like any other CONNECT [TO]. The CURRENT SQLID special register is not reinitialized when CONNECT [TO] is used to connect back to the currently set location.

Parent topic: SQL Statements


CREATE ALIAS

The CREATE ALIAS command defines an alternate name for an existing table or view, and records the alias definition in the XDB Server system catalog at the currently set location. It is not required that the table or view be in the current location.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE ALIAS command, you must possess either the CREATEALIAS privilege, or overall SYSADM or SYSCTRL authority for the location. If the alias-name specified includes an authorization name qualifier that does not match the AuthID, the privilege set must include SYSADM or SYSCTRL authority for the location. When the specified alias-name includes an authorization name qualifier that does not match the process AuthID, any authorization name qualifier is valid, if the application process privilege set includes SYSADM or SYSCTRL authority.

Syntax

CREATE ALIAS alias-name
    FOR {table-name | view-name}

Parameters:

alias-name | Names the alias, and must not match the name of any table, view, alias, or synonym that already exists at the currently set location.
table-name or view-name | Identifies the table or view for which the alias is defined. If a table is identified, it must not be an auxiliary table or a declared temporary table. The table or view need not exist at the time the alias is defined. If it does exist, it can be at the current server or at another server. The name must not be the same as the alias name and must not identify an alias that exists at the current server.

Description

The alias name can be either a one-part, two-part or three-part qualified name (location-name.AuthID.alias-name). The AuthID qualifier within alias-name identifies the alias owner. If the CREATE ALIAS statement is dynamically prepared and the alias name is unqualified, the application process AuthID becomes the alias owner.

The table or view need not exist when the CREATE ALIAS statement is executed. Already defined tables or views can exist at either the currently set location or a different location. The table or view name must not match the alias name, and must not match any other alias names described in the catalog at the current XDB Server location.

An alias can be defined for a table, view or other alias whose name does not exist under the current XDB Server location. In this case, the existence of the referenced object is not verified by the XDB Server when the alias is created. The XDB Server can detect an alias specified for a location other than the current location. In these cases, the full three-part name that the alias references is substituted in the query for the alias name. The new query is then sent to the location specified in the three-part name.

Example:

The following example creates an alias called bob, and then uses that alias in a query:

CREATE ALIAS bob FOR tutorial.tutorial.customer

When the query shown below references bob, the three-part name value defined above is substituted, and the query sent to the TUTORIAL location.

SELECT * FROM bob
Parent topic: SQL Statements


CREATE AUXILIARY TABLE

The CREATE AUXILIARY TABLE statement creates an auxiliary table at the current server for storing LOB data.
Restriction: This topic applies to Windows environments only.

Invocation

Do not use this statement if the value of special register CURRENT RULES is 'STD' when the statement is executed. When the register's value is 'STD' and a base table is created with LOB columns or altered such that LOB columns are added, DB2 automatically creates the LOB table space, auxiliary table, and index on the auxiliary table for each LOB column. DB2 chooses the names and characteristics of these objects.

This statement can be embedded in an application program or issued interactively if the value of special register CURRENT RULES is 'DB2' when the statement is executed.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATETAB privilege for the database implicitly or explicitly specified by the IN clause
  • DBADM, DBCTRL, or DBMAINT authority for the database
  • SYSADM or SYSCTRL authority

Privilege set

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the specified table name includes a qualifier that is not the same as this authorization ID, the privilege set must include SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process. However, if the specified table name includes a qualifier that is not the same as this authorization ID, the following rules apply:

  1. If the privilege set includes SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, any qualifier is valid.
  2. If the privilege set does not include any of the authorities listed in item 1 above, the qualifier is valid only if it is the same as one of the authorization IDs of the process and the privilege set that are held by that authorization ID includes all privileges needed to create the table.

Syntax

CREATE {AUXILIARY | AUX} TABLE aux-table-name
    IN [database-name] table-space-name STORES table-name
    COLUMN column-name [PART integer]

Parameters:

aux-table-name Names the auxiliary table. The name must not identify a table, view, alias, or synonym that exists at the current server.

If qualified, the name can be a two-part or three-part name. If a three-part name is used, the first part must match the value of field DB2 LOCATION NAME on installation panel DSNTIPR at the current server. (If the current server is not the local DB2, this name is not necessarily the name in the CURRENT SERVER special register.) Whether the name is two-part or three-part, the authorization ID that qualifies the name is the table's owner.

If the table name is unqualified and the statement is embedded in a program, the owner of the table is the authorization ID that serves as the implicit qualifier for unqualified object names. This is the authorization ID in the QUALIFIER operand when the plan or package was created or last rebound. If QUALIFIER was not used, the owner of the table is the owner of the package or plan.

If the table name is unqualified and the statement is dynamically prepared, the SQL authorization ID is the owner of the table.

IN database-name.table-space-name or IN table-space-name Identifies the table space in which the auxiliary table is created. The name must identify an empty LOB table space that currently exists at the current server.

If you specify a database and a table space, the table space must belong to the specified database. If you specify only a table space, it must belong to database DSNDB04.

Description

AUXILIARY or AUX

Specifies a table that is used to store the LOB data for a LOB column (or a column with a distinct type that is based on a LOB data type).

STORES table-name COLUMN column-name

Identifies the base table and the column of that table that is to be stored in the auxiliary table. If the base table is nonpartitioned, an auxiliary table must not already exist for the specified column. If the base table is partitioned, an auxiliary table must not already exist for the specified column and specified partition.

The encoding scheme for the LOB data stored in the auxiliary table is the same as the encoding scheme for the base table. It is either ASCII or EBCDIC depending on the value of the CCSID clause when the base table was created.

The auxiliary table can store a BLOB, CLOB, or DBCLOB value that is greater than 1 gigabyte in length only if the LOB table space for the auxiliary table was defined with LOG NO.

PART integer

Specifies the partition of the base table for which the auxiliary table is to store the specified column. You can specify PART only if the base table is defined in a partitioned table space, and no other auxiliary table exists for the same LOB column of the base table.

Note:

The number of auxiliary tables to create depends on the number of LOB columns in the base table and whether the base table is partitioned. If the base table is nonpartitioned, you need one LOB table space and one auxiliary table for each LOB column in the base table. If the base table is partitioned, you need one LOB table space and one auxiliary table for each partition for each LOB column. For example if the base table has four partitions and two LOB columns, you need to create a total of eight auxiliary tables in eight different LOB table spaces.

Example:

Assume that a column named EMP_PHOTO with a data type of BLOB(110K) has been added to sample employee table DSN8610.EMP for each employee's photo. Create auxiliary table EMP_PHOTO_ATAB to store the BLOB data for the BLOB column in LOB table space DSN8D61A.PHOTOLTS.

CREATE AUX TABLE EMP_PHOTO_ATAB
    IN DSN8D61A.PHOTOLTS
    STORES DSN8610.EMP
    COLUMN EMP_PHOTO;
Parent topic: SQL Statements


CREATE DATABASE

The CREATE DATABASE command creates a logical database structure at the currently set XDB Server location.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE DATABASE command, you must possess either CREATEDBA or CREATEDBC privileges, or overall SYSADM or SYSCTRL authority for the location.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE DATABASE database-name
    [BUFFERPOOL bpname]
    [INDEXBP bpname]
    [ROSHARE {OWNER | READ}]
    [AS {WORKFILE | TEMP} [FOR member-name]]
    [STOGROUP stogroup-name]
    [CCSID {ASCII | EBCDIC | UNICODE}]

Parameters:

database-name | Names the new database, which must not already exist at the current location.
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.
member-name | The name of the DB2 subsystem that the database will become part of.
stogroup-name | Identifies a user-defined XDB Server stogroup (drive and path) where database files can be stored.

Description

The CREATE DATABASE command creates a logical database the current XDB Server location. If a subdirectory for the database does not exist and a stogroup is not specified, a new subdirectory is created under the current location path (with the subdirectory taking on the name of the newly created database). The creator of a database is given DBADM authority for the database.

The CREATE DATABASE command has been enhanced to reflect the new XDB Server system architecture. The BUFFERPOOL clause (DB2-mainframe only) along with the ROSHARE and STOGROUP clauses have been added. The ROSHARE clause is used to create XDB Server read-only shared (ROSHARE) databases, while the STOGROUP clause allows you to store database objects within a user defined XDB Server stogroup (or directory path).

With DB2 V7, XDB locations (either EBCDIC or ASCII) can now contain Unicode data. If you create a database with CCSID UNICODE, all character data in corresponding tables is stored in UTF-8 format and all graphic data is stored in UTF-16 format.

BUFFERPOOL bpname

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, The XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for tables with 4K page sizes, while the last ten are for tables with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server system catalog tables.

Specifies the default buffer pool name to be used for table spaces created within the database. If the database is a work file database, 8KB and 16KB buffer pools cannot be specified.

If you omit the BUFFERPOOL clause, the buffer pool specified for user data on installation panel DSNTIP1 is used. The default value for the user data field on that panel is BP0.

INDEXBP bpname

Specifies the default buffer pool name to be used for the indexes created within the database. The name must identify a 4KB buffer pool.If the database is a work file database, INDEXBP cannot be specified.

If you omit the INDEXBP clause, the buffer pool specified for user indexes on installation panel DSNTIP1 is used. The default value for the user indexes field on that panel is BP0.

AS WORKFILE or AS TEMP

Indicates that this is a work file database or a database for declared temporary tables (a TEMP database).

AS WORKFILE | Specifies the database is a work file database. AS WORKFILE can be specified only in a data sharing environment. Only one work file database can be created for each DB2 member.
AS TEMP | Specifies the database is for declared temporary tables only. AS TEMP must be specified to create a database that will be used for declared temporary tables; otherwise, the database will not be used for declared temporary tables. Only one TEMP database can be created for each DB2 subsystem or data sharing member. A TEMP database cannot be shared between DB2 subsystems or data sharing members. PUBLIC implicitly receives the CREATETAB privilege (without GRANT authority) to define a declared temporary table in the TEMP database. This implicit privilege is not recorded in the DB2 catalog and cannot be revoked.

FOR member-name

Specifies the member for which this database is to be created. Specify FOR member-name only in a data sharing environment.

If FOR member-name is not specified, the member is the DB2 subsystem on which the CREATE DATABASE statement is executed.

ROSHARE

This optional clause is used for the creation of read-only shared (or ROSHARE) databases. The OWNER keyword identifies the database as the owner created and controlled database, while the READ keyword identifies a reading (or dummy) database that can only read (or SELECT) data from the owner database.

STOGROUP

Identifies an optional XDB Server-created stogroup where database objects (tables, indexes, views, etc.) can be stored (stogroups allow you to define a path for storing data). To use the defined stogroup, first modify the special XDBPRIMEVOLPATH and XDBVOLPATH column values in the SYSIBM.SYSVOLUMES table to associate the stogroup's VOLID column value with the stogroup path (see CREATE STOGROUP command summary). If a stogroup is specified when creating the database, the XDB Server does not create a database subdirectory under the current location path, but uses the stogroup path instead.

If the optional STOGROUP clause is omitted, the stogroup associated with the new database defaults to SYSDEFLT -- a system default, not representing any physical storage entity on the XDB Server. This omission of a stogroup name causes the XDB Server to create a new database subdirectory under the currently set location directory path, with this information being recorded within the current location system tables.

CCSID

The CCSID clause is only syntactically supported for EBCDIC and ASCII. This is because the definition of the XDB location itself defines how character data is stored.

If you specify UNICODE, your character and graphic data is stored as UNICODE within the database.

Examples:

Create database DSN8D61P. Specify DSN8G610 as the default storage group to be used for the table spaces and indexes in the database. Specify 8KB buffer pool BP8K1 as the default buffer pool to be used for table spaces in the database, and BP2 as the default buffer pool to be used for indexes in the database.

CREATE DATABASE DSN8D61P
    STOGROUP DSN8G610
    BUFFERPOOL BP8K1
    INDEXBP BP2;

Create database DSN8TEMP. Use the defaults for the default storage group and default buffer pool names. Specify ASCII as the default encoding scheme for data stored in the database.

CREATE DATABASE DSN8TEMP
    CCSID ASCII;
Parent topic: SQL Statements


CREATE DISTINCT TYPE

The CREATE DISTINCT TYPE statement defines a distinct type, which is a data type that a user defines. A distinct type must be sourced on one of the built-in data types. Successful execution of the statement also generates:
Restriction: This topic applies to Windows environments only.
  • A function to cast between the distinct type and its source type
  • A function to cast between the source type and its distinct type
  • As appropriate, support for the use of comparison operators with the distinct type

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Privilege set

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID

of the owner of the plan or package.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process. The specified distinct type name can include a schema name (a qualifier). However, if the schema name is not the same as the SQL authorization ID, one of the following conditions must be met:

  • The privilege set includes SYSADM or SYSCTRL authority.
  • The SQL authorization ID of the process has the CREATEIN privilege on the schema.

Syntax

CREATE DISTINCT TYPE distinct-type-name AS source-data-type
    [WITH COMPARISONS]

source-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] |
  {CHARACTER | CHAR} VARYING (integer) |
  VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}]|
{DATE | TIME | TIMESTAMP} |
ROWID

Description

distinct-type-name

Names the distinct type. The name is implicitly or explicitly qualified by a schema name. The name, together with the implicit or explicit schema name, must not identify a distinct type that exists at the current server.

The unqualified form of distinct-type-name is a long SQL identifier.

distinct-type-name must not be the name of a built-in data type, BOOLEAN, or any of following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |

The unqualified name is implicitly qualified with a schema name according to the following rules:

  • If the CREATE DISTINCT TYPE statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the CREATE DISTINCT TYPE statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of distinct-type-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name can be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the distinct type is determined by how the CREATE DISTINCT TYPE statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

Although the information is not recorded in the catalog, the owner is given the USAGE privilege on the distinct type. The owner is also given the EXECUTE privilege with the GRANT option on each of the generated cast functions.

source-data-type

Specifies the data type that is used as the basis for the internal representation of the distinct type. The data type must be a built-in data type. You can use any of the built-in data types that are allowed for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead.

If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:

CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)

If the distinct type is sourced on a character string data type, the FOR clause indicates the subtype. If you do not specify the FOR clause, the distinct type is defined with the default subtype. The default is SBCS when the value of field MIXED DATA on installation panel DSNTIPF is NO. The default is MIXED when the value is YES.

If the distinct type is sourced on a string data type, the CCSID clause indicates whether the encoding scheme of the data is ASCII or EBCDIC. If you do not specify CCSID ASCII or CCSID EBCDIC, the encoding scheme is the value of field DEF ENCODING SCHEME on installation panel DSNTIPF.

WITH COMPARISONS

Specifies that system-generated comparison operators are to be created for comparing two instances of the distinct type. Do not specify WITH COMPARISONS if the source data type is BLOB, CLOB, or DBCLOB; otherwise, a warning occurs and the comparison operators are not generated. You must specify WITH COMPARISONS for all other source data types.

DB2 implicitly creates comparison functions for the following comparison operators for use with the distinct type:

BETWEEN | IS NULL | < | ¬<
NOT BETWEEN | IS NOT NULL | > | ¬>
IN | = | <= | >=
NOT IN | ¬= | <>

The name of the function is the same as the comparison operator. You cannot invoke the comparison functions using function notation syntax, for example, '<'(C1,C2). Instead, use the syntax C1 < C2.

You must not specify the comparison operations for distinct types that are sourced on a CLOB, BLOB, or DBCLOB, or that have a length greater than 255 bytes. (Distinct types that are sourced on a VARCHAR or VARGRAPHIC can have a length greater than 255 bytes).

Source data types with DBCS or mixed data

If you specify a GRAPHIC source type and the ASCII encoding scheme, or a string source type with a mixed data subtype (FOR MIXED DATA), the value of field FOR MIXED DATA on installation panel DSNTIPF must be YES; otherwise, an error occurs. In addition, to create a distinct type on a GRAPHIC data type, the corresponding CCSID must be defined for the implicitly or explicitly specified encoding scheme.

Generated cast functions

The successful execution of the CREATE DISTINCT TYPE statement causes DB2 to generate the following cast functions:

  • A function to convert from the distinct type to its source data type
  • A function to convert from the source data type to the distinct type
  • A function to cast from a data type A to distinct type DT, where A is promotable to the source data type S of distinct type DT

For some source data types, DB2 supports an additional function to convert from:

  • INTEGER to the distinct type if the source type is SMALLINT
  • VARCHAR to the distinct type if the source type is CHAR
  • VARGRAPHIC to the distinct type if the source type is GRAPHIC
  • DOUBLE to the distinct type if the source type is REAL

The cast functions are created as if the following statements were executed:

CREATE FUNCTION source-type-name (distinct-type-name)
    RETURNS source-type-name ...
CREATE FUNCTION distinct-type-name (source-type-name)
    RETURNS distinct-type-name ...

Even if you specified a length, precision, or scale for the source data type in the CREATE DISTINCT TYPE statement, the name of the cast function that converts from the distinct type to the source type is simply the name of the source data type. The data type of the value that the cast function returns includes any length, precision, or scale values that you specified for the source data type.

The name of the cast function that converts from the source type to the distinct type is the name of the distinct type. The input parameter of the cast function has the same data type as the source data type, including the length, precision, and scale.

For example, assume that a distinct type named T_SHOESIZE is created with the following statement:

CREATE DISTINCT TYPE CLAIRE.T_SHOESIZE AS VARCHAR(2) WITH COMPARISONS

When the statement is executed, DB2 also generates the following cast functions. VARCHAR converts from the distinct type to the source type, and T_SHOESIZE converts from the source type to the distinct type.

FUNCTION CLAIRE.VARCHAR (CLAIRE.T_SHOESIZE) RETURNS SYSIBM.VARCHAR (2)
FUNCTION CLAIRE.T_SHOESIZE (SYSIBM.VARCHAR (2)) RETURNS CLAIRE.T_SHOESIZE

Notice that function VARCHAR returns a value with a data type of VARCHAR(2) and that function T_SHOESIZE has an input parameter with a data type of VARCHAR(2).

The schema of the generated cast functions is the same as the schema of the distinct type. No other function with the same name and function signature must already exist in the database.

In the preceding example, if T_SHOESIZE had been sourced on a SMALLINT, CHAR, or GRAPHIC data type instead of a VARCHAR data type, another cast function would have been generated in addition to the two functions to cast between the distinct type and the source data type. For example, assume that T_SHOESIZE is created with this statement:

CREATE DISTINCT TYPE CLAIRE.T_SHOESIZE AS CHAR(2) WITH COMPARISONS

When the statement is executed, DB2 generates these cast functions:

FUNCTION CLAIRE.CHAR (CLAIRE.T_SHOESIZE) RETURNS SYSIBM.CHAR (2)
FUNCTION CLAIRE.T_SHOESIZE (SYSIBM.CHAR (2)) RETURNS CLAIRE.T_SHOESIZE
FUNCTION CLAIRE.T_SHOESIZE (SYSIBM.VARCHAR (2)) RETURNS CLAIRE.T_SHOESIZE

Notice that the third function enables the casting of a VARCHAR(2) to T_SHOESIZE. This additional function is created to enable casting a constant, such as 'AB', directly to the distinct type. Without the additional function, you would have to first cast 'AB', which has a data type of VARCHAR, to a data type of CHAR and then cast it to the distinct type.

You cannot explicitly drop a generated cast function. The cast functions that are generated for a distinct type are implicitly dropped when the distinct type is dropped with the DROP statement.

Built-in functions

When a distinct type is defined, the built-in functions (such as AVG, MAX, and LENGTH) are not automatically supported for the distinct type. You can use a built-in function on a distinct type only after a sourced user-defined function, which is based on the built-in function, has been created for the distinct type.

Example:

Create a distinct type named SHOESIZE that is sourced on an INTEGER data type.

CREATE DISTINCT TYPE SHOESIZE AS INTEGER WITH COMPARISONS;

The successful execution of this statement also generates two cast functions. Function INTEGER(SHOESIZE) returns a value with data type INTEGER, and function SHOESIZE(INTEGER) returns a value with distinct type SHOESIZE.

Create a distinct type named MILES that is sourced on a DOUBLE data type.

CREATE DISTINCT TYPE MILES AS DOUBLE WITH COMPARISONS;

The successful execution of this statement also generates two cast functions. Function DOUBLE(MILES) returns a value with data type DOUBLE, and function MILES(DOUBLE) returns a value with distinct type MILES.

Parent topic: SQL Statements


CREATE FUNCTION

The CREATE FUNCTION statement registers a user-defined function with an application server. You can register three different types of functions with this statement, each of which is described separately.
Restriction: This topic applies to Windows environments only.

External Scalar

CREATE FUNCTION (external scalar)

The function is written in a programming language and returns a scalar value. The external executable is registered with an application server along with various attributes of the function.

External Table

CREATE FUNCTION (external table)

The function is written in a programming language and returns a complete table. The external executable is registered with an application server along with various attributes of the function.

Sourced

CREATE FUNCTION (sourced)

The function is implemented by invoking another function (either built-in, external, or sourced) that is already registered with an application server.

Parent topic: SQL Statements


CREATE FUNCTION (external scalar)

This CREATE FUNCTION statement registers a user-defined external scalar function with an application server.
Restriction: This topic applies to Windows environments only.

A scalar function returns a single value each time it is invoked.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE FUNCTION function-name ([parameter-declaration[,...]])
RETURNS {data-type2 [AS LOCATOR] |
    data-type3 CAST FROM data-type4 [AS LOCATOR]} option-list

option-list:

[SPECIFIC specific-name]
[EXTERNAL [NAME {'string' | identifier}] LANGUAGE {ASSEMBLE | C | COBOL | PLI}]
[PARAMETER STYLE DB2SQL [DETERMINISTIC | NOT DETERMINISTIC] [FENCED]]
[RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT]
[READS SQL DATA | NO SQL | MODIFIES SQL DATA | CONTAINS SQL]
[EXTERNAL ACTION | NO EXTERNAL ACTION]
[NO SCRATCHPAD | SCRATCHPAD [100 | length]]
[FINAL CALL | NO FINAL CALL]
[ALLOW PARALLEL | DISALLOW PARALLEL]
[DBINFO | NODBINFO]
[NO COLLID | COLLID collection-id]
[WLM ENVIRONMENT {name | (name)}]
[ASUTIME NO LIMIT | ASUTIME LIMIT integer]
[STAY RESIDENT NO | STAY RESIDENT YES]
[PROGRAM TYPE SUB | PROGRAM TYPE MAIN]
[SECURITY DB2 | SECURITY {USER | DEFINED}]
[STOP AFTER SYSTEM DEFAULT FAILURES |
 STOP AFTER integer FAILURES |
 CONTINUE AFTER FAILURE]
[INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
[RUN OPTIONS run-time-options]

parameter-declaration:

[parameter-name] parameter-type

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] |
    {CHARACTER | CHAR} VARYING (integer)|
    VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] |
VARGRAPHIC (integer) |
DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

Description

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type of each parameter (without regard for any length, precision, scale, subtype or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

You can use the same name for more than one function if the function signature of each function is unique.

The unqualified form of function-name is a long SQL identifier. The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |

The unqualified function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of function-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name can be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Identifies the number of input parameters of the function, and specifies the data type of each parameter. All the parameters for a function are input parameters. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is a long SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |
built-in-data-type | The data type of the input parameter is a built-in data type. You can use the same built-in data types as for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead. If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
data-type2 | Specifies the data type of the output.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if data-type4 is a LOB data type or a distinct type based on a LOB data type.
data-type3 CAST FROM data-type4 Specifies the data type of the output of the function (data-type4) and the data type in which that output is returned to the invoking statement (data-type3). The two data types can be different For example, for the following definition, the function returns a DOUBLE value, which DB2 converts to a DECIMAL value and then passes to the statement that invoked the function:
CREATE FUNCTION SQRT(DECIMAL(15,0))
    RETURNS DECIMAL(15,0) CAST FROM DOUBLE
ASSEMBLE | The function is written in Assembler. (Not currently available with XDB Server.)
C | The function is written in C or C++. (Not currently available with XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available with XDB Server.)
NOT DETERMINISTIC The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements.

NOT DETERMINISTIC is the default.

Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.

DETERMINISTIC The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input.

DB2 does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is the null value.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return a null or nonnull value.
NO SQL | The function cannot execute any SQL statements.
MODIFIES SQL DATA | The function can execute any SQL statement except those statements that are not supported in any function. Do not specify MODIFIES SQL DATA when ALLOW PARALLEL is in effect.
READS SQL DATA The function cannot execute SQL statements that modify data. SQL statements that are not supported in any function return a different error.

READS SQL DATA is the default.

CONTAINS SQL | The function cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.
NO SCRATCHPAD

A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.

SCRATCHPAD length

When the function is invoked for the first time, XDB allocates memory for a scratchpad.

NO FINAL CALL | A final call is not made to the external scalar function. The function does not receive an additional argument that specifies the type of call.
FINAL CALL | A final call is made to the external scalar function. See the following description of call types for the characteristics of a final call. When FINAL CALL is specified, the function receives an additional argument that specifies the type of call to enable the function to differentiate between a final call and another type of call.
NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function. For details about the argument and its structure, see your DB2 Application Programming and SQL Guide.
NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.
NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.
NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.
SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.
  • A distinct type parameter is passed as the source type of the distinct type.

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB Server operating environment does not support the LOB data type at this time.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACES.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

XDB Server operating environment does not support transition table parameters at this time.

RETURNS

Identifies the output of the function. Consider this clause in conjunction with the optional CAST FROM clause.

data-type2 | Specifies the data type of the output.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if data-type4 is a LOB data type or a distinct type based on a LOB data type.
data-type3 CAST FROM data-type4 Specifies the data type of the output of the function (data-type4) and the data type in which that output is returned to the invoking statement (data-type3). The two data types can be different For example, for the following definition, the function returns a DOUBLE value, which DB2 converts to a DECIMAL value and then passes to the statement that invoked the function:
CREATE FUNCTION SQRT(DECIMAL(15,0))
    RETURNS DECIMAL(15,0) CAST FROM DOUBLE

The value of data-type4 must not be a distinct type and must be castable to data-type3. The value for data-type3 can be any built-in data type or distinct type.

SPECIFIC specific-name

Specifies a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is a long SQL identifier. The qualified form is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk , XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

EXTERNAL

Specifies that the function being registered is based on code that is written in an external programming language and adheres to the documented linkage conventions and interface of that language.

If you do not specify the NAME clause, 'NAME function-name' is implicit. In this case, function-name must not be longer than 8 characters.

NAME 'string' or identifier

Identifies the name of the MVS load module that contains the user-written code that implements the logic of the function. The name can be a string constant that is no longer than 8 characters or a short identifier, The name must conform to the naming conventions for MVS load modules.

DB2 loads the load module when the function is invoked. The load module is created when the program that contains the function body is compiled and link-edited. The load module does not need to exist when the CREATE FUNCTION statement is executed. However, it must exist and be accessible by the current server when the function is invoked.

You can specify the EXTERNAL clause in one of the following ways:

EXTERNAL
EXTERNAL NAME PKJVSP1
EXTERNAL NAME 'PKJVSP1'

If you specify an external program name, you must use the NAME keyword. For example, this syntax is not valid:

EXTERNAL PKJVSP1

LANGUAGE

Specifies the application programming language in which the function program is written. All programs must be designed to run in IBM's Language Environment environment.

ASSEMBLE | The function is written in Assembler. (Not currently available with XDB Server.)
C | The function is written in C or C++. (Not currently available with XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available with XDB Server.)

PARAMETER STYLE DB2SQL

Specifies the linkage convention that the function program uses to receive input parameters from and pass return values to the invoking SQL statement.

DB2SQL indicates that parameters for indicator variables are associated with each input and return value to allow for null values. The parameters that are passed between the invoking SQL statement and the function include:

  • The first n parameters are the input parameters that are specified for the function
  • A parameter for the result of the function
  • n parameters for the indicator variables for the input parameters
  • A parameter for the indicator variable for the result
  • The SQLSTATE to be returned to DB2
  • The qualified name of the function
  • The specific name of the function
  • The SQL diagnostic string to be returned to DB2

Zero to three additional parameters might also be passed:

  • The scratchpad, if SCRATCHPAD is specified
  • The call type, if NO FINAL CALL is specified
  • The DBINFO structure, if DBINFO is specified

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the function returns the same results for identical input arguments.

NOT DETERMINISTIC | The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements. NOT DETERMINISTIC is the default. Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.
DETERMINISTIC | The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input. DB2 does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

FENCED

This clause has no functional equivalent in the XDB Server operating environment.

RETURNS NULL ON NULL INPUT or CALLED ON NULL INPUT

Specifies whether the function is called if any of the input arguments is null at execution time.

RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is the null value.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return a null or nonnull value.

NO SQL, MODIFIES SQL DATA, READS SQL DATA, or CONTAINS SQL

Indicates whether the function can execute any SQL statements and, if so, what type.

NO SQL | The function cannot execute any SQL statements.
MODIFIES SQL DATA | The function can execute any SQL statement except those statements that are not supported in any function. Do not specify MODIFIES SQL DATA when ALLOW PARALLEL is in effect.
READS SQL DATA | The function cannot execute SQL statements that modify data. SQL statements that are not supported in any function return a different error. READS SQL DATA is the default.
CONTAINS SQL | The function cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.

EXTERNAL ACTION or NO EXTERNAL ACTION

This clause has no functional equivalent in the XDB Server operating environment.

NO SCRATCHPAD or SCRATCHPAD

Specifies whether XDB provides a scratchpad for the function. It is strongly recommended that external functions be reentrant, and a scratchpad provides an area for the function to save information from one invocation to the next.

NO SCRATCHPAD | A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.
SCRATCHPAD length | When the function is invoked for the first time, XDB allocates memory for a scratchpad.

A scratchpad has the following characteristics:

  • length must be between 1 and 32767. The default value is 100 bytes.
  • XDB initializes the scratchpad to all binary zeros (X'00''s).
  • The scope of a scratchpad is the SQL statement. For each reference to the function in an SQL statement, there is one scratchpad. For example, assuming that function UDFX was defined with the SCRATCHPAD keyword, three scratchpads are allocated for the three references to UDFX in the following SQL statement:
    SELECT A, UDFX(A) FROM TABLEB
    WHERE UDFX(A) > 103 OR UDFX(A) < 19;

    If the function is run under parallel tasks, one scratchpad is allocated for each parallel task of each reference to the function in the SQL statement. This can lead to unpredictable results. For example, if a function uses the scratchpad to count the number of times that it is invoked, the count reflects the number of invocations done by the parallel task and not the SQL statement. Specify the DISALLOW PARALLEL clause for functions that will not work correctly with parallelism.

  • The scratchpad is persistent. XDB preserves its content from one invocation of the function to the next. Any changes that the function makes to the scratchpad on one call are still there on the next call. XDB initializes the scratchpads when it begins to execute an SQL statement. XDB does not reset scratchpads when a correlated subquery begins to execute.
  • The scratchpad can be a central point for the system resources that the function acquires. If the function acquires system resources, specify FINAL CALL to ensure that XDB calls the function one more time so that the function can free those system resources.

    Each time the function invoked, XDB passes an additional argument to the function that contains the address of the scratchpad.

NO FINAL CALL or FINAL CALL

NO FINAL CALL | A final call is not made to the external scalar function. The function does not receive an additional argument that specifies the type of call.
FINAL CALL | A final call is made to the external scalar function. See the following description of call types for the characteristics of a final call. When FINAL CALL is specified, the function receives an additional argument that specifies the type of call to enable the function to differentiate between a final call and another type of call.

ALLOW or DISALLOW PARALLEL

This clause has no functional equivalent in the XDB Server operating environment.

NO DBINFO or DBINFO

Specifies whether specific information that XDB knows is passed to the function when it is invoked.

NO DBINFO | Additional information is not passed.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function. For details about the argument and its structure, see your DB2 Application Programming and SQL Guide.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the function is executed.

NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of the function can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a function, setting a limit can be helpful if the function gets caught in a loop.

NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the load module for the function remains resident in memory when the function ends.

NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the function program runs as a main routine or a subroutine.

SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

Choosing data types for parameters

When you choose the data types of the input and output parameters for your function, consider the rules of promotion that can affect the values of the parameters. For example, a constant that is one of the input arguments to the function might have a built-in data type that is different from the data type that the function expects, and more significantly, might not be promotable to that expected data type. Based on the rules of promotion, using the following data types for parameters is recommended:

  • INTEGER instead of SMALLINT
  • DOUBLE instead of REAL
  • VARCHAR instead of CHAR
  • VARGRAPHIC instead of GRAPHIC

For portability of functions across platforms that are not DB2 for OS/390, do not use the following data types, which might have different representations on different platforms:

  • FLOAT. Use DOUBLE or REAL instead.
  • NUMERIC. Use DECIMAL instead.

Determining the uniqueness of functions in a schema

At the current server, the function signature of each function, which is the qualified function name combined with the number and data types of the input parameters, must be unique. If the function has more than 30 input parameters, only the data types of the first 30 are used to determine uniqueness. This means that two different schemas can each contain a function with the same name that have the same data types for all of their corresponding data types. However, a single schema must not contain multiple functions with the same name that have the same data types for all of their corresponding data types.

When determining whether corresponding data types match, XDB does not consider any length, precision, scale, subtype or encoding scheme attributes in the comparison. XDB considers the synonyms of data types (DECIMAL and NUMERIC, REAL and FLOAT, and DOUBLE and FLOAT) a match. Therefore, CHAR(8) and CHAR(35) are considered to be the same, as are DECIMAL(11,2), DECIMAL(4,3), and NUMERIC(4,2).

Assume that the following statements are executed to create four functions in the same schema. The second and fourth statements fail because they create functions that are duplicates of the functions that the first and third statements created.

CREATE FUNCTION PART (INT, CHAR(15)) ...
CREATE FUNCTION PART (INTEGER, CHAR(40)) ...
CREATE FUNCTION ANGLE (DECIMAL(12,2)) ...
CREATE FUNCTION ANGLE (DEC(10,7)) ...

Overriding a built-in function

Giving an external function the same name as a built-in function is not a recommended practice unless you are trying to change the functionality of the built-in function.

If you do intend to create an external function with the same name as a built-in function, be careful to maintain the uniqueness of its function signature. If your function has the same name and data types of the corresponding parameters of the built-in function but implements different logic, XDB might choose the wrong function when the function is invoked with an unqualified function name. Thus, the application might fail, or perhaps even worse, run successfully but provide an inappropriate result.

Example:

Assume that you want to write an external function program in C that implements the following logic:

output = 2 * input – 4

The function should return a null value if and only if one of the input arguments is null. The simplest way to avoid a function call and get a null result when an input value is null is to specify RETURNS NULL ON NULL INPUT on the CREATE FUNCTION statement or allow it to be the default.

Write the statement needed to register the function, using the specific name MINENULL1.

CREATE FUNCTION NTEST1 (SMALLINT)
    RETURNS SMALLINT
    EXTERNAL NAME 'NTESTMOD'
    SPECIFIC MINENULL1
    LANGUAGE C
    DETERMINISTIC
    NO SQL
    FENCED
    PARAMETER STYLE DB2SQL
    RETURNS NULL ON NULL INPUT
    NO EXTERNAL ACTION;

Assume that user Smith wants to register an external function named CENTER in schema SMITH. The function program will be written in C and will be reentrant. Write the statement that Smith needs to register the function, letting DB2 generate a specific name for the function.

CREATE FUNCTION CENTER (INTEGER, FLOAT)
    RETURNS FLOAT
    EXTERNAL NAME 'MIDDLE'
    LANGUAGE C
    DETERMINISTIC
    NO SQL
    FENCED
    PARAMETER STYLE DB2SQL
    NO EXTERNAL ACTION
    STAY RESIDENT YES;

Assume that user McBride (who has administrative authority) wants to register an external function named CENTER in the SMITH schema. McBride plans to give the function specific name FOCUS98. The function program uses a scratchpad to perform some one-time only initialization and save the results. The function program returns a value with a FLOAT data type. Write the statement McBride needs to register the function and ensure that when the function is invoked, it returns a value with a data type of DECIMAL(8,4).

CREATE FUNCTION SMITH.CENTER (FLOAT, FLOAT, FLOAT)
    RETURNS DECIMAL(8,4) CAST FROM FLOAT
    EXTERNAL NAME 'CMOD'
    SPECIFIC FOCUS98
    LANGUAGE C
    DETERMINISTIC
    NO SQLFENCED
    PARAMETER STYLE DB2SQL
    NO EXTERNAL ACTION
    SCRATCHPAD
    NO FINAL CALL;
Parent topic: SQL Statements


CREATE FUNCTION (external table)

This CREATE FUNCTION statement registers a user-defined external table function with an application server.
Restriction: This topic applies to Windows environments only.

A scalar function returns a single value each time it is invoked.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE FUNCTION function-name ([parameter-declaration[,...]])
    RETURNS TABLE (column-name data-type [AS LOCATOR] [,...]) option-list

option-list:

    [SPECIFIC specific-name]
    [EXTERNAL [NAME {'string' | identifier}] LANGUAGE {ASSEMBLE | C | COBOL | PLI}]
    [PARAMETER STYLE DB2SQL [DETERMINISTIC | NOT DETERMINISTIC]
    [FENCED]]
    [RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT]
    [READS SQL DATA | NO SQL | MODIFIES SQL DATA | CONTAINS SQL]
    [EXTERNAL ACTION | NO EXTERNAL ACTION]
    [NO SCRATCHPAD | SCRATCHPAD [100 | length]]
    [FINAL CALL | NO FINAL CALL]
    [DISALLOW PARALLEL]
    [DBINFO | NODBINFO]
    [CARDINALITY integer]
    [NO COLLID | COLLID collection-id]
    [WLM ENVIRONMENT {name | (name)}]
    [ASUTIME NO LIMIT | ASUTIME LIMIT integer]
    [STAY RESIDENT NO | STAY RESIDENT YES]
    [PROGRAM TYPE SUB | PROGRAM TYPE MAIN]
    [SECURITY DB2 | SECURITY {USER | DEFINED}]
    [RUN OPTIONS run-time-options]
    [STOP AFTER SYSTEM DEFAULT FAILURES |
     STOP AFTER integer FAILURES |
     CONTINUE AFTER FAILURE]

parameter-declaration:

    [parameter-name] parameter-type

parameter-type:

    {data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

    {built-in-data-type | distinct-type-name}

built-in-data-type:

    SMALLINT |
    {INTEGER | INT} |
    {DECIMAL | DEC | NUMERIC} [integer[,...]] |
    {FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
    { {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer)|
    VARCHAR (integer) }
        [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
        {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
        [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
    {BINARY LARGE OBJECT | BLOB} (integer [K|M|G])
    |{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
    {DATE | TIME | TIMESTAMP} |
    ROWID

Description

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type of each parameter (without regard for any length, precision, scale, subtype or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

You can use the same name for more than one function if the function signature of each function is unique.

The unqualified form of function-name is a long SQL identifier. The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE

The unqualified function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of function-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name can be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Identifies the number of input parameters of the function, and specifies the data type of each parameter. All the parameters for a function are input parameters. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is a long SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
column-name | Specifies the name of the column. The name is a long identifier and must be unique within the RETURNS TABLE clause for the function.
data-type | Specifies the data type of the column. The data type can be any built-in data type, except LONG VARCHAR or LONG VARGRAPHIC. The data type can also be any distinct type.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only for a LOB data type or a distinct type based on a LOB data type.
ASSEMBLE | The function is written in Assembler. (Not currently available in XDB Server.)
C | The function is written in C or C++. (Not currently available in XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available in XDB Server.)
NOT DETERMINISTIC | The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements. NOT DETERMINISTIC is the default. Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.
DETERMINISTIC | The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input. XDB does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.
RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is an empty table, which is a table with no rows. RETURNS NULL ON NULL INPUT is the default.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return an empty table, depending on its logic.
NO SQL | The function cannot execute any SQL statements.
READS SQL DATA | The function cannot execute any SQL statements that modify data. SQL statements that are not supported in any function return a different error. READS SQL DATA is the default.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.
NO SCRATCHPAD | A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.
SCRATCHPAD | length When the function is invoked for the first time, XDB allocates memory for a scratchpad. A scratchpad has the following characteristics:
First call | A first call occurs only if the function was defined with FINAL CALL. Before a first call, the scratchpad is set to binary zeros. Argument values are passed to the function, and the function might acquire memory or perform other one-time only resource initialization. However, the function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments.
Open call | An open call occurs unless the function returns an error. The scratchpad is set to binary zeros only if the function was defined with NO FINAL CALL. Argument values are passed to the function, and the function might perform any one-time initialization actions that are required. However, the function should not return any data to XDB.
Fetch call | A fetch call occurs unless the function returns an error during the first call or open call. Argument values are passed to the function, and XDB expects the function to return a row of data or the end-of-table condition. If a scratchpad is also passed to the function, it remains untouched from the previous call.
Close call | A close call occurs unless the function returns an error during the first call, open call, or fetch call. No SQL-argument or SQL-argument-ind values are passed to the function, and if the function attempts to examine these values, unpredictable results may occur. If a scratchpad is also passed to the function, it remains untouched from the previous call. The function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments. Also on close call, a function that is defined with NO FINAL CALL should release any system resources that it acquired. (A function that is defined with FINAL CALL should release any acquired resources on the final call.)
Final | The final call balances the first call, and like the first call, occurs only if the function was defined with FINAL CALL. The function can set return values for the SQL-state and diagnostic-message arguments. The function should also release any system resources that it acquired. A final call occurs at these times:
NO DBINFO | No additional information is passed. NO DBINFO is the default.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function.
NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.
NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.
NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.
SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.
  • A distinct type parameter is passed as the source type of the distinct type.

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB operating environment does not support the LOB data type at this time.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACES.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

The XDB operating environment does not support transition table parameters at this time.

RETURNS TABLE(column-name data-type ...)

Identifies that the output of the function is a table. The parentheses that follow the keyword enclose the list of names and data types of the columns of the table.

column-name | Specifies the name of the column. The name is a long identifier and must be unique within the RETURNS TABLE clause for the function.
data-type | Specifies the data type of the column. The data type can be any built-in data type, except LONG VARCHAR or LONG VARGRAPHIC. The data type can also be any distinct type.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only for a LOB data type or a distinct type based on a LOB data type.

SPECIFIC specific-name

Specifies a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is a long SQL identifier. The qualified form is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk , XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

EXTERNAL

Specifies that the function being registered is based on code that is written in an external programming language and adheres to the documented linkage conventions and interface of that language.

If you do not specify the NAME clause, 'NAME function-name' is implicit. In this case, function-name must not be longer than 8 characters.

NAME 'string' or identifier

Identifies the name of the MVS load module that contains the user-written code that implements the logic of the function. The name can be a string constant that is no longer than 8 characters or a short identifier, The name must conform to the naming conventions for MVS load modules.

XDB loads the load module when the function is invoked. The load module is created when the program that contains the function body is compiled and link-edited. The load module does not need to exist when the CREATE FUNCTION statement is executed. However, it must exist and be accessible by the current server when the function is invoked.

You can specify the EXTERNAL clause in one of the following ways:

EXTERNAL
EXTERNAL NAME PKJVSP1
EXTERNAL NAME 'PKJVSP1'

If you specify an external program name, you must use the NAME keyword. For example, this syntax is not valid:

EXTERNAL PKJVSP1

LANGUAGE

Specifies the application programming language in which the function program is written. All programs must be designed to run in IBM's Language Environment environment.

ASSEMBLE | The function is written in Assembler. (Not currently available in XDB Server.)
C | The function is written in C or C++. (Not currently available in XDB Server.)
COBOL | The function is written in COBOL, including the object-oriented language extensions.
PLI | The function is written in PL/I. (Not currently available in XDB Server.)

PARAMETER STYLE DB2SQL

Specifies the linkage convention that the function program uses to receive input parameters from and pass return values to the invoking SQL statement.

DB2SQL indicates that parameters for indicator variables are associated with each input and return value to allow for null values. The parameters that are passed between the invoking SQL statement and the function include:

  • The first n parameters are the input parameters that are specified for the function
  • A parameter for the result of the function
  • n parameters for the indicator variables for the input parameters
  • A parameter for the indicator variable for the result
  • The SQLSTATE to be returned to DB2
  • The qualified name of the function
  • The specific name of the function
  • The SQL diagnostic string to be returned to DB2

Zero to three additional parameters might also be passed:

  • The scratchpad, if SCRATCHPAD is specified
  • The call type, if NO FINAL CALL is specified
  • The DBINFO structure, if DBINFO is specified

NOT DETERMINISTIC or DETERMINISTIC

Specifies whether the function returns the same results for identical input arguments.

NOT DETERMINISTIC | The function might not return the same result for identical input arguments. The function depends on some state values that affect the results. XDB uses this information when processing a SELECT, UPDATE, DELETE, or INSERT statement to disable merging of views that refer to the function. An example of a function that is not deterministic is one that generates random numbers, or any function that contains SQL statements. NOT DETERMINISTIC is the default. Some functions that are not deterministic can receive incorrect results if the function is executed by parallel tasks. Specify the DISALLOW PARALLEL clause for these functions.
DETERMINISTIC | The function always returns the same result for identical input arguments. XDB can use this information to optimize view processing for SELECT, UPDATE, DELETE, or INSERT statements. An example of a deterministic function is a function that calculates the square root of the input. XDB does not verify that the function program is consistent with the specification of DETERMINISTIC or NOT DETERMINISTIC.

FENCED

This clause has no functional equivalent in the XDB Server operating environment.

RETURNS NULL ON NULL INPUT or CALLED ON NULL INPUT

Specifies whether the function is called if any of the input arguments is null at execution time.

RETURNS NULL ON INPUT | The function is not called if any of the input arguments is null. The result is an empty table, which is a table with no rows. RETURNS NULL ON NULL INPUT is the default.
CALLED ON NULL INPUT | The function is called regardless of whether any of the input arguments is null, making the function responsible for testing for null argument values. The function can return an empty table, depending on its logic.

NO SQL, READS SQL DATA, or CONTAINS SQL

Indicates whether the function can execute any SQL statements and, if so, what type.

NO SQL | The function cannot execute any SQL statements.
READS SQL DATA | The function cannot execute any SQL statements that modify data. SQL statements that are not supported in any function return a different error. READS SQL DATA is the default.
CONTAINS SQL | The stored procedure cannot execute any SQL statements that read or modify data. SQL statements that are not supported in any function return a different error.

EXTERNAL ACTION or NO EXTERNAL ACTION

This clause has no functional equivalent in the XDB Server operating environment.

NO SCRATCHPAD or SCRATCHPAD

Specifies whether XDB provides a scratchpad for the function. It is strongly recommended that external functions be reentrant, and a scratchpad provides an area for the function to save information from one invocation to the next.

NO SCRATCHPAD | A scratchpad is not allocated and passed to the function. NO SCRATCHPAD is the default.
SCRATCHPAD | length When the function is invoked for the first time, XDB allocates memory for a scratchpad. A scratchpad has the following characteristics:
  • length must be between 1 and 32767. The default value is 100 bytes.
  • XDB initializes the scratchpad to all binary zeros (X'00''s).
  • The scope of a scratchpad is the SQL statement. For each reference to the function in an SQL statement, there is one scratchpad. For example, assuming that function UDFX was defined with the SCRATCHPAD keyword, three scratchpads are allocated for the three references to UDFX in the following SQL statement:
    SELECT A, UDFX(A) FROM TABLEB WHERE UDFX(A) > 103 OR UDFX(A) < 19;

    If the function is run under parallel tasks, one scratchpad is allocated for each parallel task of each reference to the function in the SQL statement. This can lead to unpredictable results. For example, if a function uses the scratchpad to count the number of times that it is invoked, the count reflects the number of invocations done by the parallel task and not the SQL statement. Specify the DISALLOW PARALLEL clause for functions that will not work correctly with parallelism.

  • The scratchpad is persistent. XDB preserves its content from one invocation of the function to the next. Any changes that the function makes to the scratchpad on one call are still there on the next call. XDB initializes the scratchpads when it begins to execute an SQL statement. XDB does not reset scratchpads when a correlated subquery begins to execute.
  • The scratchpad can be a central point for the system resources that the function acquires. If the function acquires system resources, specify FINAL CALL to ensure that XDB calls the function one more time so that the function can free those system resources.

    Each time the function invoked, XDB passes an additional argument to the function that contains the address of the scratchpad.

FINAL CALL or NO FINAL CALL

Specifies whether a first call and a final call are made to the function.

FINAL CALL

A first call and final call are made to the function in addition to one or more open, fetch, or close calls. FINAL CALL is the default.

NO FINAL CALL

A first call and final call are not made to the function.

The types of calls are:

First call | A first call occurs only if the function was defined with FINAL CALL. Before a first call, the scratchpad is set to binary zeros. Argument values are passed to the function, and the function might acquire memory or perform other one-time only resource initialization. However, the function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments.
Open call | An open call occurs unless the function returns an error. The scratchpad is set to binary zeros only if the function was defined with NO FINAL CALL. Argument values are passed to the function, and the function might perform any one-time initialization actions that are required. However, the function should not return any data to XDB.
Fetch call | A fetch call occurs unless the function returns an error during the first call or open call. Argument values are passed to the function, and XDB expects the function to return a row of data or the end-of-table condition. If a scratchpad is also passed to the function, it remains untouched from the previous call.
Close call | A close call occurs unless the function returns an error during the first call, open call, or fetch call. No SQL-argument or SQL-argument-ind values are passed to the function, and if the function attempts to examine these values, unpredictable results may occur. If a scratchpad is also passed to the function, it remains untouched from the previous call. The function should not return any data to XDB, but it can set return values for the SQL-state and diagnostic-message arguments. Also on close call, a function that is defined with NO FINAL CALL should release any system resources that it acquired. (A function that is defined with FINAL CALL should release any acquired resources on the final call.)
Final | The final call balances the first call, and like the first call, occurs only if the function was defined with FINAL CALL. The function can set return values for the SQL-state and diagnostic-message arguments. The function should also release any system resources that it acquired. A final call occurs at these times:
  • End of statement: When the cursor is closed for cursor-oriented statements, or the execution of the statement has completed.
  • End of transaction: When normal end of statement processing does not occur. For example, the logic of an application, for some reason, bypasses closing the cursor.

If a commit operation occurs while a cursor defined as WITH HOLD is open, a final call is made when the cursor is closed or the application ends. If a commit occurs at the end of a parallel task, a final call is made regardless of whether a cursor defined as WITH HOLD is open.

If a commit, rollback, or abort operation causes the final call, the function cannot issue any SQL statements when it is invoked.

DISALLOW PARALLEL

This clause has no functional equivalent in the XDB Server operating environment.

NO DBINFO or DBINFO

Specifies whether specific information that DB2 knows is passed to the function when it is invoked.

NO DBINFO | No additional information is passed. NO DBINFO is the default.
DBINFO | An additional argument is passed when the function is invoked. The argument is a structure that contains information such as the application run-time authorization ID, the schema name, the name of a table or column that the function might be inserting into or updating, and identification of the database server that invoked the function.

CARDINALITY integer

Specifies an estimate of the expected number of rows that the function returns. The number is used for optimization purposes. The value of integer must range from 0 to 2147483647.

If you do not specify CARDINALITY, DB2 assumes a finite value. The finite value is the same value that DB2 assumes for tables for which the RUNSTATS utility has not gathered statistics.

If a function has an infinite cardinality--the function never returns the "end-of-table" condition and always returns a row, then a query that requires the "end-of-table" to work correctly will need to be interrupted. Thus, avoid using such functions in queries that involve GROUP BY and ORDER BY.

NO COLLID or COLLID collection-id

Identifies the package collection that is used when the function is executed.

NO COLLID | The package collection for the function is the same as the package collection of the program that invokes the function. If a trigger invokes the function, the collection of the trigger package is used. If the invoking program does not use a package, XDB resolves the package by using the CURRENT PACKAGE PATH special register or the CURRENT PACKAGESET special register.
COLLID collection-id | The name of the package collection that is used when the function is executed.

WLM ENVIRONMENT

This clause has no functional equivalent in the XDB Server operating environment.

ASUTIME

Specifies the total amount of processor time, in CPU service units, that a single invocation of the function can run. The value is unrelated to the ASUTIME column of the resource limit specification table.

When you are debugging a function, setting a limit can be helpful if the function gets caught in a loop.

NO LIMIT | There is no limit on the service units. NO LIMIT is the default.
LIMIT integer | The limit on the service units is a positive integer in the range of 1 to 2GB. If the function uses more service units than the specified value, the function is canceled.

The XDB Server operating environment only provides NO LIMIT at this time.

STAY RESIDENT

Specifies whether the load module for the function remains resident in memory when the function ends.

NO | The load module is deleted from memory after the function ends. Use NO for non-reentrant functions. NO is the default.
YES | The load module remains resident in memory after the function ends. Use YES for reentrant functions.

The XDB Server provides an operating environment where the function does not remain resident.

PROGRAM TYPE

Specifies whether the function program runs as a main routine or a subroutine.

SUB | The function runs as a subroutine. SUB is the default.
MAIN | The function runs as a main routine.

SECURITY

This clause has no functional equivalent in the XDB Server operating environment.

RUN OPTIONS run-time-options

This clause has no functional equivalent in the XDB Server operating environment.

STOP AFTER SYSTEM DEFAULT FAILURES, STOP AFTER integer FAILURES, or CONTINUE AFTER FAILURE

Specifies whether the routine is to be put in a stopped state after some number of failures.

  • STOP AFTER SYSTEM DEFAULT FAILURES.
  • STOP AFTER integer FAILURES.
  • CONTINUE AFTER FAILURE.

This clause is only implemented syntactically in the XDB Server operating environment.

Example:

The following registers a table function written to return a row consisting of a single document identifier column for each known document in a text management system. The first parameter matches a given subject area and the second parameter contains a given string.

Within the context of a single session, the table function will always return the same table; therefore, it is defined as DETERMINISTIC. In addition, the DISALLOW PARALLEL keyword is added because table functions cannot operate in parallel.

Although the size of the output for DOCMATCH is highly variable, CARDINALITY 20 is a representative value, and is specified to help DB2.

CREATE FUNCTION DOCMATCH (VARCHAR(30), VARCHAR(255))
        RETURNS TABLE (DOC_ID CHAR(16))
    EXTERNAL NAME ABC
    LANGUAGE C
    PARAMETER STYLE DB2SQL
    NO SQL
    DETERMINISTIC
    NO EXTERNAL ACTION
    FENCED
    SCRATCHPAD
    FINAL CALL
    DISALLOW PARALLEL
    CARDINALITY 20;
Parent topic: SQL Statements


CREATE FUNCTION (sourced)

This CREATE FUNCTION statement registers a user-defined function that is based on an existing scalar or column function with an application server.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

CREATE FUNCTION function-name ([parameter-declaration[,...]])
RETURNS data-type2 [AS LOCATOR] [SPECIFIC specific-name]
SOURCE {function-name | SPECIFIC specific-name | function-name (parameter-type [,...])}

parameter-declaration:

[parameter-name] parameter-type

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer)
| VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type of each parameter (without regard for any length, precision, scale, subtype or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

If the function is sourced on an existing function to enable the use of the existing function with a distinct type, the name can be the same name as the existing function. In general, more than one function can have the same name if the function signature of each function is unique.

The unqualified form of function-name is a long SQL identifier. The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |

The unqualified function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The qualified form of function-name is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

The schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Identifies the number of input parameters of the function, and specifies the data type of each parameter. All the parameters for a function are input parameters. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is a long SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY | NOT | =
BETWEEN | NULL | ¬=
DISTINCT | ONLY | <
EXCEPT | OR | <=
EXISTS | OVERLAPS | ¬<
FALSE | SIMILAR | >
FOR | SOME | >=
FROM | TABLE | ¬>
IN | TRUE | <>
IS | TYPE |
built-in-data-type | The data type of the input parameter is a built-in data type. You can use the same built-in data types as for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead. If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)
data-type2 Specifies the data type of the output.

You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result. To specify a LONG VARCHAR or LONG VARGRAPHIC, use VARCHAR or VARGRAPHIC with an explicit length instead.

AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.
function-name | Identifies the function name of the source function. If you specify an unqualified name, XDB searches the schemas of the SQL path; otherwise, XDB searches the named schema.
parameter-type,... Provides a list of data types, separated by commas, that must match the data types of the parameters of the source function. XDB uses the number of data types and the logical concatenation of the data types to identify the source function.

For data types that have length, precision, or scale attributes, you can either specify a value for the attribute or use a set of empty parentheses (with the noted exceptions):

Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match. For example, DEC() will match a parameter whose data type is DEC(7,2).FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement for the source function. For example, DECIMAL(7,4) does not match a parameter whose data type is DECIMAL(7,2). Coding specific values for length, precision, scale, subtype, and encoding scheme attributes ensures that the source function you intend to use is used.

The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.
  • A distinct type parameter is passed as the source type of the distinct type.

You can specify any built-in data type or distinct type that matches or can be cast to the data type of the corresponding parameter of the source function (the function that is identified in the SOURCE clause). Length, precision, or scale attributes do not have be specified for data types with these attributes. When specifying data types with these attributes, follow these rules:

An empty set of parentheses can be used to indicate that the length, precision, or scale is the same as the source function.

If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB operating environment does not support the LOB data type at this time.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACES.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

XDB Server operating environment does not support transition table parameters at this time.

RETURNS

Identifies the output of the function.

data-type2 | Specifies the data type of the output. You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result. To specify a LONG VARCHAR or LONG VARGRAPHIC, use VARCHAR or VARGRAPHIC with an explicit length instead.
AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.

SPECIFIC specific-name

Specifies a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is a long SQL identifier. The qualified form is a short SQL identifier (the schema name) followed by a period and a long SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk , XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

SOURCE

Specifies that the function that you are registering is a sourced function. A sourced function is implemented by another function (the source function). The source function can be any previously created user-defined function except an external table function. The source function can also be any built-in function except the following (if a particular syntax is shown, only the indicated form cannot be specified):

  • COUNT(*)
  • COUNT_BIG(*)
  • CHAR(datetime-expression, second-argument) where second-argument is ISO, USA, EUR, JIS, or LOCAL
  • COALESCE
  • NULLIF
  • RAISE-ERROR
  • STRIP with any optional parameters specified
  • VALUE

If you base the sourced function directly or indirectly on an external scalar function, the sourced function inherits the attributes of the external scalar function. This can involve several layers of sourced functions. For example, assume that function A is sourced on function B, which in turn is sourced on function C. Function C is an external scalar function. Functions A and B inherit all of the attributes that are specified on the EXTERNAL clause of the CREATE FUNCTION statement for function C.

EXECUTE authority is required on the source function.

To specify a built-in function as the source function, use the last syntax variation in the following list, function-name (parameter-type, ...).

function-name

Identifies the function to be used as the source function by its function name. A schema name implicitly or explicitly qualifies the name. Only one function with this name must exist in the schema.

If you specify an unqualified function-name, XDB uses the SQL path of the authorization ID (the value of the CURRENT PATH special register) to locate the function. The first schema that has only one function with this name on which the user has EXECUTE authority is selected. XDB returns an error if it cannot find a function or encounters a schema that has more than one function with this name.

If you specify a qualified function-name, XDB returns an error if there is no function with this name in the named schema or more than one function with this name exists in the schema.

SPECIFIC specific-name

Identifies the function to be used as the source function by its specific name. A schema name implicitly or explicitly qualifies the name.

If you specify an unqualified specific-name, XDB uses the SQL path of the authorization ID (the value of the CURRENT PATH special register) to locate the schema. XDB searches the SQL path and selects the first schema that contains a function with this specific name for which the user has EXECUTE authority. XDB returns an error if it cannot find a function with the specific name in one of the schemas in the SQL path.

If you specify a qualified specific-name, XDB searches the named schema for the function. XDB returns an error if it cannot find a function with the specific name.

function-name (parameter-type,...)

Identifies the function to be used as the source function by its function signature. You must use this form of the syntax if the source function is a built-in function. You cannot use this form of the syntax if the source function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table). Instead, identify the function with its function name, if unique, or with its specific name.

XDB does not use function resolution to select the source function because the function signature uniquely identifies the function.

ALL | LIKE | UNIQUE
AND | MATCH | UNKNOWN
ANY NOT =
BETWEEN NULL ¬=
DISTINCT ONLY <
EXCEPT OR <=
EXISTS OVERLAPS ¬<
FALSE SIMILAR >
FOR SOME >=
FROM TABLE ¬>
IN TRUE <>
IS | TYPE
built-in-data-type The data type of the input parameter is a built-in data type. You can use the same built-in data types as for the CREATE TABLE statement except LONG VARCHAR or LONG VARGRAPHIC. Use VARCHAR or VARGRAPHIC with an explicit length instead.

If you do not specify a specific value for the data types that have length, precision, or scale attributes (CHAR, GRAPHIC, DECIMAL, NUMERIC, FLOAT), the defaults are as follows:

distinct-type-name | The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
data-type2 Specifies the data type of the output.

You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result. To specify a LONG VARCHAR or LONG VARGRAPHIC, use VARCHAR or VARGRAPHIC with an explicit length instead.

AS LOCATOR | Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.
parameter-type,... Provides a list of data types, separated by commas, that must match the data types of the parameters of the source function. XDB uses the number of data types and the logical concatenation of the data types to identify the source function.

For data types that have length, precision, or scale attributes, you can either specify a value for the attribute or use a set of empty parentheses (with the noted exceptions):

Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match. For example, DEC() will match a parameter whose data type is DEC(7,2).FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement for the source function. For example, DECIMAL(7,4) does not match a parameter whose data type is DECIMAL(7,2). Coding specific values for length, precision, scale, subtype, and encoding scheme attributes ensures that the source function you intend to use is used.

The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

CHAR | CHAR(1)
GRAPHIC | GRAPHIC(1)
DECIMAL | DECIMAL(5,0)
FLOAT | DOUBLE (length of 8)

For either empty parentheses or specific values, the synonyms for data types are considered a match. For example, DEC and NUMERIC will match.

If you omit the FOR DATA or CCSID clause for data types with a subtype or encoding scheme attribute, XDB ignores the attribute when determining whether the data types match.

If no function with the specified signature exists in the explicitly or implicitly specified schema, an error occurs.

The number of input parameters in the function that is being created must be the same as the number of parameters in the source function. If the data type of each input parameter is not the same as or castable to the corresponding parameter of the source function, an error occurs. The data type of the final result of the source function must match or be castable to the result of the sourced function.

Choosing data types for parameters

When you choose the data types of the input and output parameters for your function, consider the rules of promotion that can affect the values of the parameters. For example, a constant that is one of the input arguments to the function might have a built-in data type that is different from the data type that the function expects, and more significantly, might not be promotable to that expected data type. Based on the rules of promotion, using the following data types for parameters is recommended:

  • INTEGER instead of SMALLINT
  • DOUBLE instead of REAL
  • VARCHAR instead of CHAR
  • VARGRAPHIC instead of GRAPHIC

For portability of functions across platforms that are not DB2 for OS/390, do not use the following data types, which might have different representations on different platforms:

  • FLOAT. Use DOUBLE or REAL instead.
  • NUMERIC. Use DECIMAL instead.

Determining the uniqueness of functions in a schema

At the current server, the function signature of each function, which is the qualified function name combined with the number and data types of the input parameters, must be unique This means that two different schemas can each contain a function with the same name that have the same data types for all of their corresponding data types. However, a single schema must not contain multiple functions with the same name that have the same data types for all of their corresponding data types.

When determining whether corresponding data types match, XDB does not consider any length, precision, scale, subtype or encoding scheme attributes in the comparison. XDB considers the synonyms of data types (DECIMAL and NUMERIC, REAL and FLOAT, and DOUBLE and FLOAT) a match. Therefore, CHAR(8) and CHAR(35) are considered to be the same, as are DECIMAL(11,2), DECIMAL(4,3), and NUMERIC(4,2).

Assume that the following statements are executed to create four functions in the same schema. The second and fourth statements fail because they create functions that are duplicates of the functions that the first and third statements created.

CREATE FUNCTION PART (INT, CHAR(15)) ...
CREATE FUNCTION PART (INTEGER, CHAR(40)) ...
CREATE FUNCTION ANGLE (DECIMAL(12,2)) ...
CREATE FUNCTION ANGLE (DEC(10,7)) ...

Rules for creating sourced functions

For the discussion in this section, assume that the function that is being created is named NEWF and the source function is named SOURCEF. Consider the following rules when creating a sourced function:

  • The unqualified names of the sourced function and source function can be different (NEWF and SOURCEF).
  • The number of input parameters for NEWF and SOURCEF must be the same; otherwise, an error occurs when the CREATE FUNCTION statement is executed.
  • When specifying the input parameters and output for NEWF, you can specify a value for the precision, scale, subtype, or encoding scheme for a data type with any of these attributes or use empty parentheses.

    Empty parentheses, such as VARCHAR(), indicate that the value of the attribute is the same as the attribute for the corresponding parameter of SOURCEF, or that is determined by data type promotion. If you specify any values for the attributes, XDB checks the values against the corresponding input parameters and returned output of SOURCEF as described next.

  • When the CREATE FUNCTION statement is executed, XDB checks the input parameters of NEWF against those of SOURCEF. The data type of each input parameter of NEWF function must be either the same as, or promotable to, the data type of the corresponding parameter of SOURCEF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, an argument that matches the data type and length or precision attributes of a NEWF parameter might not be promotable if the corresponding SOURCEF parameter has a shorter length or less precision. In general, do not define the parameters of a sourced function with length or precision attributes that are greater than the attributes of the corresponding parameters of the source function.

  • When the CREATE FUNCTION statement is executed, XDB checks the data type identified in the RETURNS clause of NEWF against the data type that SOURCEF returns. The data type that SOURCEF returns must be either the same as, or promotable to, the RETURNS data type of NEWF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, the value of a result that matches the data type and length or precision attributes of those specified for SOURCEF's result might not be promotable if the RETURNS data type of NEWF has a shorter length or less precision. Consider the possible effects of defining the RETURNS data type of a sourced function with length or precision attributes that are less than the attributes defined for the data type returned by source function.

Examples:

Assume that you created a distinct type HATSIZE, which you based on the built-in data type INTEGER. You want to have an AVG function to compute the average hat size of different departments. Create a sourced function that is based on built-in function AVG.

CREATE FUNCTION AVE (HATSIZE) RETURNS HATSIZE
    SOURCE SYSIBM.AVG (INTEGER);

When you created distinct type HATSIZE, two cast functions were generated, which allow HATSIZE to be cast to INTEGER for the argument and INTEGER to be cast to HATSIZE for the result of the function.

After Smith registered the external scalar function CENTER in his schema, you decide that you want to use this function, but you want it to accept two INTEGER arguments instead of one INTEGER argument and one FLOAT argument. Create a sourced function that is based on CENTER.

CREATE FUNCTION MYCENTER (INTEGER, INTEGER)
    RETURNS FLOAT
    SOURCE SMITH.CENTER (INTEGER, FLOAT);
Parent topic: SQL Statements


CREATE FUNCTION (SQL Scalar)

This statement is used to define a user-defined SQL scalar function. A scalar function returns a single value each time it is invoked. Specifying a function is generally valid wherever an SQL expression is valid.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set defined below must include at least one of the following:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

Syntax

CREATE FUNCTION function-name ([parameter-declaration[,...]])
RETURNS data-type2
[LANGUAGE SQL] option-list RETURN-statement

parameter-declaration:

[parameter-name] parameter-type

parameter-type:

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer)
| VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

Description

function-name

Names the user-defined function. The name is implicitly or explicitly qualified by a schema name. The combination of name, schema name, the number of parameters, and the data type each parameter (without regard for any length, precision, scale, subtype, or encoding scheme attributes of the data type) must not identify a user-defined function that exists at the current server.

If the function is sourced on an existing function to enable the use of the existing function with a distinct type, the name can be the same name as the existing function. In general, more than one function can have the same name if the function signature of each function is unique.

  • The unqualified form of function-name is an SQL identifier.

    The name must not be any of the following system-reserved keywords even if you specify them as delimited identifiers:

    ALL | LIKE | UNIQUE
    AND | MATCH | UNKNOWN
    ANY NOT =
    BETWEEN NULL ¬=
    DISTINCT ONLY <
    EXCEPT OR <=
    EXISTS OVERLAPS ¬<
    FALSE SIMILAR >
    FOR SOME >=
    FROM TABLE ¬>
    IN TRUE <>
    IS | TYPE

    The unqualified function name is implicitly qualified with a schema name according to the following rules:

    • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
    • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.
  • The qualified form of function-name is an SQL identifier (the schema name) followed by a period and an SQL identifier.

    The schema name can be "SYSTOOLS" if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with "SYS" unless the schema name is "SYSADM".

The owner of the function is determined by how the CREATE FUNCTION statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

The owner is implicitly given the EXECUTE privilege with the GRANT option for the function.

(parameter-declaration,...)

Specifies the number of input parameters of the function and the data type of each parameter. All the parameters for a function are input parameters and are nullable. There must be one entry in the list for each parameter that the function expects to receive. Although not required, you can give each parameter a name.

A function can have no parameters. In this case, you must code an empty set of parentheses, for example:

CREATE FUNCTION WOOFER()

parameter-name

Specifies the name of the input parameter. The name is an SQL identifier, and each name in the parameter list must not be the same as any other name.

data-type

Specifies the data type of the input parameter. The data type can be a built-in data type or a distinct type.

built-in-type

The data type of the input parameter is a built-in data type.

You can use the same built-in data types as for the CREATE TABLE statement.

For parameters with a character or graphic data type, the PARAMETER CCSID clause or CCSID clause indicates the encoding scheme of the parameter. If you do not specify either of these clauses, the encoding scheme is the value of field DEF ENCODING SCHEME on installation panel DSNTIPF.

distinct-type-name

The data type of the input parameter is a distinct type. Any length, precision, scale, subtype, or encoding scheme attributes for the parameter are those of the source type of the distinct type.

The implicitly or explicitly specified encoding scheme of all the parameters with a string data type must be the same - either all ASCII, all EBCDIC, or all UNICODE.

Although parameters with a character data type have an implicitly or explicitly specified subtype (BIT, SBCS, or MIXED), the function program can receive character data of any subtype. Therefore, conversion of the input data to the subtype of the parameter might occur when the function is invoked.

Parameters with a datetime data type or a distinct type are passed to the function as a different data type:

  • A datetime type parameter is passed as a character data type, and the data is passed in ISO format.

    The encoding scheme for a datetime type parameter is the same as the implicitly or explicitly specified encoding scheme of any character or graphic string parameters. If no character or graphic string parameters are passed, the encoding scheme is the value of field DEF ENCODING SCHEME on installation panel DSNTIPF.

  • A distinct type parameter is passed as the source type of the distinct type.

You can specify any built-in data type or distinct type that matches or can be cast to the data type of the corresponding parameter of the source function (the function that is identified in the SOURCE clause). Length, precision, or scale attributes do not have be specified for data types with these attributes. When specifying data types with these attributes, follow these rules:

  • An empty set of parentheses can be used to indicate that the length, precision, or scale is the same as the source function.
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default values are used.

AS LOCATOR

Specifies that a locator to the value of the parameter is passed to the function instead of the actual value. Specify AS LOCATOR only for parameters with a LOB data type or a distinct type based on a LOB data type. Passing locators instead of values can result in fewer bytes being passed to the function, especially when the value of the parameter is very large.

The AS LOCATOR clause has no effect on determining whether data types can be promoted, nor does it affect the function signature, which is used in function resolution.

The XDB operating environment does not support the LOB data type.

TABLE LIKE table-name or view-name AS LOCATOR

Specifies that the parameter is a transition table. However, when the function is invoked, the actual values in the transition table are not passed to the function. A single value is passed instead. This single value is a locator to the table, which the function uses to access the columns of the transition table. A function with a table parameter can only be invoked from the triggered action of a trigger.

The use of TABLE LIKE provides an implicit definition of the transition table. It specifies that the transition table has the same number of columns as the identified table or view. The columns have the same data type, length, precision, scale, subtype, and encoding scheme as the identified table or view, as they are described in catalog tables SYSCOLUMNS and SYSTABLESPACE. The number of columns and the attributes of those columns are determined at the time the CREATE FUNCTION statement is processed. Any subsequent changes to the number of columns in the table or the attributes of those columns do not affect the parameters of the function.

The name specified after TABLE LIKE must identify a table or view that exists at the current server. The name must not identify a declared temporary table. The name does not have to be the same name as the table that is associated with the transition table for the trigger. An unqualified table or view name is implicitly qualified according to the following rules:

  • If the CREATE FUNCTION statement is embedded in a program, the implicit qualifier is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the implicit qualifier is the owner of the plan or package.
  • If the CREATE FUNCTION statement is dynamically prepared, the implicit qualifier is the SQL authorization ID in the CURRENT SQLID special register.

When the function is invoked, the corresponding columns of the transition table identified by the table locator and the table or view identified in the TABLE LIKE clause must have the same definition. The data type, length, precision, scale, and encoding scheme of these columns must match exactly. The description of the table or view at the time the CREATE FUNCTION statement was executed is used.

Additionally, a character FOR BIT DATA column of the transition table cannot be passed as input for a table parameter for which the corresponding column of the table specified at the definition is not defined as character FOR BIT DATA. (The definition occurs with the CREATE FUNCTION statement.) Likewise, a character column of the transition table that is not FOR BIT DATA cannot be passed as input for a table parameter for which the corresponding column of the table specified at the definition is defined as character FOR BIT DATA.

The XDB operating environment does not support transition table parameters.

RETURNS

Identifies the output of the function.

data-type2

Specifies the data type of the output. The output is nullable.

You can specify any built-in data type or distinct type that can be cast to from the data type of the source function's result.

AS LOCATOR

Specifies that the function returns a locator to the value rather than the actual value. You can specify AS LOCATOR only if the output from the function has a LOB data type or a distinct type based on a LOB data type.

The XDB operating environment does not support the LOB data type.

SPECIFIC specific-name

Provides a unique name for the function. The name is implicitly or explicitly qualified with a schema name. The name, including the schema name, must not identify the specific name of another function that exists at the current server.

The unqualified form of specific-name is an SQL identifier. The qualified form is an SQL identifier (the schema name) followed by a period and an SQL identifier.

If you do not specify a schema name, it is the same as the explicit or implicit schema name of the function name (function-name). If you specify a schema name, it must be the same as the explicit or implicit schema name of the function name.

If you do not specify the SPECIFIC clause, the default specific name is the name of the function. However, if the function name does not provide a unique specific name or if the function name is a single asterisk, XDB generates a specific name in the form of:

SQLxxxxxxxxxxxx

where xxxxxxxxxxxx is a string of 12 characters that make the name unique.

The specific name is stored in the SPECIFIC column of the SYSROUTINES catalog table. The specific name can be used to uniquely identify the function in several SQL statements (such as ALTER FUNCTION, COMMENT ON, DROP, GRANT, and REVOKE). However, the function cannot be invoked by its specific name.

PARAMETER CCSID

Indicates whether the encoding scheme for string parameters is ASCII, EBCDIC, or UNICODE. The default encoding scheme is the value specified in the CCSID clauses of the parameter list or RETURNS clause, or in the field DEF ENCODING SCHEME on installation panel DSNTIPF.

This clause provides a convenient way to specify the encoding scheme for all string parameters. If individual CCSID clauses are specified for individual parameters in addition to this PARAMETER CCSID clause, the value specified in all of the CCSID clauses must be the same value that is specified in this clause.

This clause also specifies the encoding scheme to be used for system-generated parameters of the routine such as message tokens and DBINFO.

SOURCE

Specifies that the new function is being defined as a sourced function. A sourced function is implemented by another function (the source function). The source function must be a scalar or aggregate function that exists at the current server, and it must be one of the following types of functions:

  • A function that was defined with a CREATE FUNCTION statement
  • A cast function that was generated by a CREATE DISTINCT TYPE statement
  • A built-in function

If the source function is not a built-in function, the particular function can be identified by its name, function signature, or specific name.

If the source function is a built-in function, the SOURCE clause must include a function signature for the built-in function. The source function must not be any of the built-in functions shown in the table below. If a particular syntax is shown, only the indicated form cannot be specified.

Type of Function | Restricted Functions
Aggregate | COUNT(*)
 | COUNT_BIG(*)
 | Scalar function | CHAR(datetime-expression, second-argument) where second-argument is ISO, USA, EUR, JIS, or LOCAL
COALESCE
DECRYPT_CHAR where second argument is DEFAULT
GETVARIABLE where second argument is DEFAULT
MAX
NULLIF
XML2CLOB
XMLELEMENT
XMLNAMESPACES

If you base the sourced function directly or indirectly on an external scalar function, the sourced function inherits the attributes of the external scalar function. This can involve several layers of sourced functions. For example, assume that function A is sourced on function B, which in turn is sourced on function C. Function C is an external scalar function. Functions A and B inherit all of the attributes that are specified on the EXTERNAL clause of the CREATE FUNCTION statement for function C.

function-name

Identifies the function that is to be used as the source function. The source function can be defined with any number of parameters. If more than one function is defined with the specified name in the specified or implicit schema, an error is returned.

If you specify an unqualified function-name, XDB searches the schemas of the SQL path. XDB selects the first schema that has only one function with this name on which the user has EXECUTE authority. An error is returned if a function is not found or a schema has more than one function with this name.

function-name (parameter-type,...)

Identifies the function that is to be used as the source function by its function signature, which uniquely identifies the function. Thefunction-name (parameter-type,...) must identify a function with the specified signature. The specified parameters must match the data types in the corresponding position that were specified when the function was created. XDB uses the number of data types and the logical concatenation of the data types to identify the specific function instance. Synonyms for data types are considered a match.

If function-name() is specified, the identified function must have zero parameters.

To use a built-in function as the source function, this syntax variation must be used. You cannot use this form of the syntax if the source function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table). Instead, identify the function with its function name, if unique, or with its specific name.

function-name

Identifies the function name of the source function. If you specify an unqualified name, XDB searches the schemas of the SQL path. Otherwise, XDB searches for the function in the specified schema.

parameter-type,...

Identifies the parameters of the function.

If an unqualified distinct type name is specified, XDB searches the SQL path to resolve the schema name for the distinct type.

Empty parentheses are allowed for some data types that are specified in this context. For data types that have a length, precision, or scale attribute, use one of the following specifications:

  • Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match. For example, DEC() is considered a match for a parameter of a function that is defined with a data type of DEC(7,2). However, FLOAT cannot be specified with empty parentheses because its parameter value indicates a specific data type (REAL or DOUBLE).
  • If a specific value for a length, precision, or scale attribute is specified, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement. If the data type is FLOAT, the precision does not need to exactly match the value that was specified because matching is based on the data type (REAL or DOUBLE).
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default attributes of the data type are implied. The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

If you omit the FOR subtype DATA clause or the CCSID clause for data types with a subtype or encoding scheme attribute, XDB is to ignore the attribute when determining whether the data types match.An exception to ignoring the attribute is FOR BIT DATA. A character FOR BIT DATA parameter of the new function cannot correspond to a parameter of the source function that is not defined as character FOR BIT DATA. Likewise, a character parameter of the new function that is not FOR BIT DATA cannot correspond to a parameter of the source function that is defined as character FOR BIT DATA.

The number of input parameters in the function that is being created must be the same as the number of parameters in the source function. If the data type of each input parameter is not the same as or castable to the corresponding parameter of the source function, an error occurs. The data type of the final result of the source function must match or be castable to the result of the sourced function.

AS LOCATOR

Specifies that the function is defined to receive a locator for this parameter. If AS LOCATOR is specified, the data type must be a LOB or distinct type that is based on a LOB.

SPECIFIC specific-name

Identifies the function to be used as the source function by its specific name.

If you specify an unqualified specific-name, XDB searches the SQL path to locate the schema. XDB selects the first schema that contains a function with this specific name for which the user has EXECUTE authority. XDB returns an error if it cannot find a function with the specific name in one of the schemas in the SQL path.

If you specify a qualified specific-name, XDB searches the named schema for the function. XDB returns an error if it cannot find a function with the specific name.

Choosing data types for parameters

When you choose the data types of the input and output parameters for your function, consider the rules of promotion that can affect the values of the parameters. For example, a constant that is one of the input arguments to the function might have a built-in data type that is different from the data type that the function expects, and more significantly, might not be promotable to that expected data type. Based on the rules of promotion, we recommend using the following data types for parameters:

  • INTEGER instead of SMALLINT
  • DOUBLE instead of REAL
  • VARCHAR instead of CHAR
  • VARGRAPHIC instead of GRAPHIC

For portability of functions across platforms that are not DB2 UDB for z/OS, do not use the following data types, which might have different representations on different platforms:

  • FLOAT. Use DOUBLE or REAL instead.
  • NUMERIC. Use DECIMAL instead.

Specifying the encoding scheme for parameters

The implicitly or explicitly specified encoding scheme of all the parameters with a string data type (both input and output parameters) must be the same--either all ASCII, all EBCDIC, or all UNICODE.

Determining the uniqueness of functions in a schema

At the current server, the function signature of each function, which is the qualified function name combined with the number and data types of the input parameters, must be unique. This means that two different schemas can each contain a function with the same name that have the same data types for all of their corresponding data types. However, a schema must not contain two functions with the same name that have the same data types for all of their corresponding data types.

When determining whether corresponding data types match, XDB does not consider any length, precision, scale, subtype or encoding scheme attributes in the comparison. XDB considers the synonyms of data types (DECIMAL and NUMERIC, REAL and FLOAT, and DOUBLE and FLOAT) a match. Therefore, CHAR(8) and CHAR(35) are considered to be the same, as are DECIMAL(11,2), DECIMAL(4,3), and NUMERIC(4,2).

Assume that the following statements are executed to create four functions in the same schema. The second and fourth statements fail because they create functions that are duplicates of the functions that the first and third statements created.

    CREATE FUNCTION PART (INT, CHAR(15)) ...
    CREATE FUNCTION PART (INTEGER, CHAR(40)) ...

    CREATE FUNCTION ANGLE (DECIMAL(12,2)) ...
    CREATE FUNCTION ANGLE (DEC(10,7)) ...

Rules for creating sourced functions

For the discussion in this section, assume that the function that is being created is named NEWF and the source function is named SOURCEF. Consider the following rules when creating a sourced function:

  • The unqualified names of the sourced function and source function can be different (NEWF and SOURCEF).
  • The number of input parameters for NEWF and SOURCEF must be the same; otherwise, an error occurs when the CREATE FUNCTION statement is executed.
  • When specifying the input parameters and output for NEWF, you can specify a value for the precision, scale, subtype, or encoding scheme for a data type with any of these attributes or use empty parentheses.

    Empty parentheses, such as VARCHAR(), indicate that the value of the attribute is the same as the attribute for the corresponding parameter of SOURCEF, or that is determined by data type promotion. If you specify any values for the attributes, XDB checks the values against the corresponding input parameters and returned output of SOURCEF as described next.

  • When the CREATE FUNCTION statement is executed, XDB checks the input parameters of NEWF against those of SOURCEF. The data type of each input parameter of NEWF function must be either the same as, or promotable to, the data type of the corresponding parameter of SOURCEF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, an argument that matches the data type and length or precision attributes of a NEWF parameter might not be promotable if the corresponding SOURCEF parameter has a shorter length or less precision. In general, do not define the parameters of a sourced function with length or precision attributes that are greater than the attributes of the corresponding parameters of the source function.

  • When the CREATE FUNCTION statement is executed, XDB checks the data type identified in the RETURNS clause of NEWF against the data type that SOURCEF returns. The data type that SOURCEF returns must be either the same as, or promotable to, the RETURNS data type of NEWF; otherwise, an error occurs.

    This checking does not guarantee that an error will not occur when NEWF is invoked. For example, the value of a result that matches the data type and length or precision attributes of those specified for SOURCEF's result might not be promotable if the RETURNS data type of NEWF has a shorter length or less precision. Consider the possible effects of defining the RETURNS data type of a sourced function with length or precision attributes that are less than the attributes defined for the data type returned by source function.

Scrollable cursors specified with user-defined functions

A row can be fetched more than once with a scrollable cursor. Therefore, if a scrollable cursor is defined with a nondeterministic function in the select list of the cursor, a row can be fetched multiple times with different results for each fetch. Similarly, if a scrollable cursor is defined with a user-defined function with external action, the action is executed with every fetch.

Parent topic: SQL Statements


CREATE GLOBAL TEMPORARY TABLE

Create a temporary table to store the intermediate results of SQL transactions. The CREATE GLOBAL TEMPORARY TABLE statement creates a description of a temporary table at the current server.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

Your privilege set must include at least one of the following:

  • The CREATETMTAB system privilege
  • The CREATETAB database privilege for any database
  • DBADM, DBCTRL, or DBMAINT authority for any database
  • SYSADM or SYSCTRL authority

You may require additional authorization if you use the LIKE keyword.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE GLOBAL TEMPORARY TABLE table-name
    (column-spec ,...)
    [LIKE {table-name | view-name}]
    [CCSID {ASCII | EBCDIC}]

column-spec:

column-name data-type
    [FOR {BIT | MIXED | SBCS} DATA]
    [NOT NULL]

Parameters:

table-name | Names the temporary table. The name, including the implicit or explicit qualifier, must not identify a table, view, alias, synonym, or temporary table that exists at the current server. In the LIKE clause, table-name specifies that the columns of the table have the exact same name and description as the columns of the identified table.
view-name | Specifies that the columns of the table have exactly the same name and description as the columns of the identified view.
column-name | Names the column. The name must not be qualified and must not be the same as the name of another column in the table.
data-type | Specifies the data type of the column. The types allowed and the rules followed are the same as those for the CREATE TABLE statement.

FOR {BIT | MIXED | SBCS} DATA

Specifies a subtype for a character string column. The subtypes allowed and the rules followed are the same as those for the CREATE TABLE statement.

data-type

Specifies the data type of the column. The data type can be a built-in data type or a distinct type.

built-in-data-type | Any built-in data type that can be specified for the CREATE TABLE statement with the exception that you cannot define a temporary table with a LOB or ROWID column.
distinct-type | Any distinct type except one that is based on a LOB or ROWID data type. The privilege set must implicitly or explicitly include the USAGE privilege on the distinct type.

NOT NULL

Specifies that the column cannot contain nulls. Omission of NOT NULL indicates that the column can contain nulls.

LIKE {table-name | view-name}

Specifies that the columns of the table have exactly the same name and description as the columns of the identified table or view. The name specified after LIKE must identify a table, view, or temporary table that exists at the current server. The privilege set must implicitly or explicitly include the SELECT privilege on the identified table or view.

This clause is similar to the LIKE clause on CREATE TABLE, but it has the following differences:

  • If any column of the identified table or view has an attribute value that is not allowed for a column in a temporary table, that attribute value is ignored. The corresponding column in the new temporary table has the default value for that attribute unless otherwise indicated.
  • If any column of the identified table or view allows a default value other than null, then that default value is ignored and the corresponding column in the new temporary table has no default value. A default value other than null is not allowed for any column in a temporary table.
Parent topic: SQL Statements


CREATE INDEX

Creates an index on one or more columns of a table at the current location.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE INDEX command, users must possess either INDEX privileges on the table, DBADM authority on the database containing the table, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table. If the index name specified is qualified with another AuthID (different from the application AuthID), the user must possess SYSADM or SYSCTRL authority for the location.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE [TYPE 2] [UNIQUE [WHERE NOT NULL]]
INDEX index-name
    ON {table-name (column-name [ASC | DESC] [,...]) | aux-table-name}
    [using-block | free-block | gbpcache-block | DEFINE {YES|NO}] [...]
    [GBPCACHE {CHANGED | ALL}]
    [DUPQTY number-records]
    [[CLUSTER | NOT CLUSTER]
    [PARTIONED]
    [PADDED | NOT PADDED]
    [using-block]
    [free-block]
    [gbpcache-block]
    [DEFINE YES | DEFINE NO] [...]]
    [PARTITION BY [RANGE] (partition-element
    [using-block | free-block | gbpcache-block] [...] [,...])]]
    [SUBPAGES {4 | 1 | 2 | 8 | 16}]
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [DSETPASS password]
    [DEFER {NO | YES}]
    [COPY YES]
    [PIECESIZE integer {K | M | G}]

using-block:

USING
{
VCAT {WITH | ROOT | PATH | NAME}
| STOGROUP stogroup-name
    [PRIQTY {3 | integer}]
    [SECQTY {3 | integer}]
    [ERASE {NO | YES}]
}

free-block:

[FREEPAGE {0 | integer}]
[PCTFREE {10 | integer}]

partition-element:

PARTITION integer
[ENDING [AT] (constant[,...]) [INCLUSIVE]]

Parameters:

index-name | Uniquely identifies the index among the other indexes and keys in the database. Index names must follow the rules for long identifiers.
table-name | Names the table being indexed.
column-name | Name of the column on which the index is created. If more than one column name is listed, a compound index is built on the named columns. A maximum of 64 columns may be included in a compound index.
integer | A whole number value from zero to 99, specifying the percentage of index space to be left free.
number-records | Specifies the amount of space to allocate for each .ptr block to hold duplicate record numbers.
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.

Description

The CREATE INDEX command syntactically checks many mainframe-specific clauses(bold text). You can specify various XDB Server index file storage options with the USING VCAT clause.

Any number of indexes can be created on a table. An index can be created or dropped at any time. Indexes are maintained automatically by the system. While indexes can speed up retrieval, they do require storage space. Therefore, the tradeoff between space and retrieval speed might become an issue in larger databases. Since it takes time to maintain indexes there also exists a tradeoff between retrieval, and update, delete and insert speed.

Indexes can be created on any or all columns of a table. Only the first 190 characters of the combined indexed field values are used in creating a compound index. The actual number of characters permitted depends on the number and type of columns in the index, with single field character indexes using up to the first 254 characters of a value in an index.

TYPE 2

Specifies a type 2 index. The TYPE 2 clause is not required. A type 2 index is always created.

UNIQUE

This optional keyword (when appearing without the WHERE NOT NULL clause) creates a unique index with no duplicate values allowed. While indexes are generally used to speed data retrieval, unique indexes are also used to prevent the entry of duplicate values in a column or compound key (such as, a key made up of several column values).

A table also requires a unique index if there is a ROWID column that is defined as GENERATED BY DEFAULT.

A unique index cannot be created on a materialized query table.

WHERE NOT NULL

When preceded with the UNIQUE keyword, a single-column index key defined with the UNIQUE WHERE NOT NULL clause can contain more than one null value, but all other non-null values must be unique. A good example would be a table of client data containing a column for Internet addresses. An index on NETADDR, defined with UNIQUE WHERE NOT NULL, allows any number of null values for clients with no Internet address, while still ensuring that any Internet addresses added or updated are unique.

In the case of an index key on multiple columns defined with the UNIQUE WHERE NOT NULL clause, any of the key columns in a particular record can be null and still be a valid key value. An index created with the attribute UNIQUE WHERE NOT NULL is recorded in the catalog table SYSIBM.SYSINDEXES with the value 'N' in the UNIQUERULE column.

ON table-name or aux-table-name

Identifies the table on which the index is created. The name can identify a base table, a declared temporary table, or an auxiliary table.

table-name

Identifies the base table or declared temporary table on which the index is created. The name must identify a table that exists at the current server. (The name of a declared temporary table must be qualified with SESSION.) The name must not identify a created temporary table.

(column-name,...) Specifies the columns of the index key.

Each column-name must identify a column of the table. Do not specify more than 64 columns, the same column more than once, or a LOB column (or a column with a distinct type that is based on a LOB data type). Do not qualify column-name.

The sum of the length attributes of the columns must not be greater than the following limits, where n is the number of columns that can contain null values and m is the number of varying-length columns in the key:

  • 2000 - n for a padded, nonpartitioning index
  • 2000 - n - 2m for a nonpadded, nonpartitioning index
  • 255 - n for a partitioning index (padded or nonpadded)

aux-table-name

Identifies the auxiliary table on which the index is created. The name must identify an auxiliary table that exists at the current server. If the auxiliary table already has an index, do not create another one. An auxiliary table can only have one index.

Do not specify any columns for the index key. The key value is implicitly defined as a unique 19-byte value that is system generated.

If qualified, table-name or aux-table-name can be a two-part or three-part name. If a three-part name is used, the first part must match the value of the field DB2 LOCATION NAME of installation panel DSNTIPR at the current server. (If the current server is not the local DB2, this name is not necessarily the name in the CURRENT SERVER special register.) Whether the name is two-part or three-part, the authorization ID that qualifies the name is the owner of the index.

ASC & DESC

These keywords are supported syntactically only. The XDB Server always creates indexes in ascending (ASC) order.

CLUSTER or NOT CLUSTER

Specifies whether the index is the clustering index for the table.

This clause is only implemented syntactically in the XDB Server operating environment.

CLUSTER

The index is to be used as the clustering index of the table. Do not specify CLUSTER for an index on an auxiliary table.

NOT CLUSTER

The index is not to be used as the clustering index of the table.

PARTITIONED

Specifies that the index is data partitioned (that is, partitioned according to the partitioning scheme of the underlying data). A partitioned index can be created only on a partitioned table space. The types of partitioned indexes are partitioning and secondary.

An index is considered a partitioning index if the specified index key columns match or comprise a superset of the columns specified in the partitioning key, are in the same order, and have the same ascending or descending attributes.

If PARTITION BY was not specified when the table was created, the CREATE INDEX statement must have the ENDING AT clause specified to define a partitioning index and use index-controlled partitioning. This index is created as a partitioned index even if the PARTITIONED keyword is not specified. When a partitioning index is created, if both the PARTITIONED and ENDING AT keywords are omitted, the index will be nonpartitioned. If PARTITIONED is specified, the USING block with PRIQTY and SECQTY specifications are optional. If these space parameters are not specified, default values are used.

A secondary index is any index defined on a partitioned table space that does not meet the definition of the partitioning index. For partitioned secondary indexes (data-partitioned secondary indexes), the ENDING AT clause is not allowed because the partitioning scheme of the index is predetermined by that of the underlying data. UNIQUE and UNIQUE WHERE NOT NULL are also not allowed. If a partitioned secondary index is created on a table that uses index-controlled partitioning, the table is converted to use table-controlled partitioning.

This clause is only implemented syntactically in the XDB Server operating environment.

NOT PADDED or PADDED

Specifies how varying-length string columns are to be stored in the index. If the index contains no varying-length columns, this option is ignored, and a warning message is returned. Indexes that do not have varying-length string columns are always created as physically padded indexes.

NOT PADDED

Specifies that varying-length string columns are not to be padded to their maximum length in the index. The length information for a varying-length column is stored with the key.

NOT PADDED is ignored and has no effect if the index is being created on an auxiliary table. Indexes on auxiliary tables are always padded.

PADDED

Specifies that varying-length string columns within the index are always padded with the default pad character to their maximum length.

When the index contains at least one varying-length column, the default for the option depends on the value of field PAD INDEXES BY DEFAULT on installation panel DSNTIPE:

  • When the value of this field is NO, which is the default for sites that newly installed Version 8, new indexes are not padded unless PADDED is specified.
  • When the value of this field is YES, which is the default value for sites that migrated to Version 8, new indexes are padded unless NOT PADDED is specified.

PCTFREE

This option leaves a percentage of the space free in the index block. The default percentage is 20. The range is 0 to 99. Read-only indexes should be created with PCTFREE 0.

Do not specify PCTFREE for an index on a declared temporary table.

DUPQTY

XDB uses B-tree indexes. Each index consists of two files, with the file extensions .IDX and .PTR. The .PTR extension file will be empty if there are no duplicate values in the indexed column. The DUPQTY option specifies the duplicate index block size. XDB Server index-name.PTR files contain Record IDs (RIDs) of duplicate index values. The DUPQTY clause uses the number-records parameter to specify the amount of space to allocate for each .PTR block (to hold record numbers of duplicate index values).

When one .PTR block is full, it links to another block of the same size. The more links that are required, the slower the system performs when accessing duplicate index RIDs. The smaller the DUPQTY value, the smaller the disk space required. The default is 16 records. Specify a value that is closest to the average number of duplicates per index value. For more information on estimating the storage requirements of an index, see the Server Administration Guide.

DEFER

This clause is supported syntactically and currently does NOT affect when the index is created (since it is always created immediately).

PIECESIZE integer

Specifies the maximum addressability of each piece (data set) for a secondary index . The subsequent keyword K, M, or G, indicates the units of the value specified in integer.

K | Indicates that the integer value is to be multiplied by 1 024 to specify the maximum piece size in bytes. The integer must be a power of two between 256 and 67 108 864.
M | Indicates that the integer value is to be multiplied by 1 048 576 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 65 536.
G | Indicates that the integer value is to be multiplied by 1 073 741 824 to specify the maximum piece size in bytes. The integer must be a power of two between 1 and 64.

This clause is only implemented syntactically in the XDB Server operating environment.

COPY

Indicates whether the COPY utility is allowed for the index. Do not specify COPY for an index on a declared temporary table.

NO | Does not allows full image or concurrent copies or the use of the RECOVER utility on the index. NO is the default.
YES | Allows full image or concurrent copies and the use of the RECOVER utility on the index.

This clause is only implemented syntactically in the XDB Server operating environment.

PARTITION BY RANGE

Specifies the partitioning index for the table, which determines the partitioning scheme for the data in the table.

This clause is only implemented syntactically in the XDB Server operating environment.

partition-element

Specifies the range for each partition.

PARTITION integer

A PARTITION clause specifies the highest value of the index key in one partition of a partitioning index. In this context, highest means highest in the sorting sequences of the index columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC), the lowest actual value is highest in the sorting sequence.

If you use CLUSTER, and the table is contained in a partitioned table space, you must use exactly one PARTITION clause for each partition (defined with NUMPARTS on CREATE TABLESPACE). If there are p partitions, the value of integer must range from 1 through p.

The length of the highest value of a partition (also called the limit key) is the same as the length of the partitioning index.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant,...)

Specifies that this is the partitioning index and indicates how the data will be partitioned. The table space is marked complete after this partitioning index is created. You must use at least one constant after ENDING AT in each PARTITION clause. You can use as many as there are columns in the key. The concatenation of all the constants is the highest value of the key in the corresponding partition of the index unless the VALUES statement was already specified when the table or previous index was created.

The use of the constants to define key values is subject to these rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must conform to the rules for assigning that value to the column. A hexadecimal string constant (GX) cannot be specified.
  • If a key includes a ROWID column (or a column with a distinct type that is based on a ROWID data type), only the first 17 bytes of the constant that is specified for the corresponding ROWID column are considered.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'; if the column is descending, the padding character is X'00'.
  • Using fewer constants than there are columns in the key has the same effect as using the highest possible values for all omitted columns.
  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition.
  • The combination of the number of table space partitions and the corresponding limit key size cannot exceed the number of partitions * (106 + limit key size in bytes) <65394.
  • If the key exceeds 255 bytes, only the first 255 bytes are considered.
  • The highest value of the key in the last partition depends on the type of table space. For table spaces that are not large partitioned table spaces, the constants you specify after ENDING AT are not enforced. The highest value of the key that can be placed in the table is the highest possible value of the key.

    For large partitioned table space, the constants you specify are enforced. The value specified for the last partition is the highest value of the key that can be placed in the table. Any key values greater than the value specified for the last partition are out of range.

    When you define a table space with DSSIZE, you automatically give the same size to all indexes that point to that table space.

    ENDING AT can be specified only if the ENDING AT clause was not specified on a previous CREATE or ALTER TABLE statement for the underlying table.

INCLUSIVE

Specifies that the specified range values are included in the data partition.

BUFFERPOOL

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for indexes with 4K page sizes, while the last ten are for indexes with 32K page sizes. Although not functionally supported, this new information is semantically checked and recorded in the XDB Server system catalog tables.

The default is the default buffer pool for indexes in the database.

USING VCAT

USING VCAT allows you to specify one of the four values below. This XDB Server extension to the VCATNAME specification allows you to specify various storage location options when creating individual indexes.

Do not specify VCAT for an index on a declared temporary table.

WITH | The default value, stores the index files in the same subdirectory as the table file.
ROOT | Stores the index files in the root directory of the current location.
PATH Stores the index files in the path previously specified in the XDB Server index path environment variable.

To use the VCAT PATH option, you must have the XDBIDX_location-name environment variable set, generally in your computer's configuration file. Enter an index path for each location's index files. For example, statements similar to the following might be included in the OS/2 config.sys file:

SET XDBIDX_location1 = e:\xdb\loc1\indexes
SET XDBIDX_location2 = p:\xdb\loc2\indexes
NAME Stores an individual index file on the path specified by the XDB Server_index name_location name environment variable (OS/2 only). Allows the files for individual indexes to be located on separate storage devices.

Take, for example, an index named COIDX that is to be created in the TUTORIAL location. The physical files for the index are to be placed in C:\IDXSTORE. Given this scenario, first set the following environment variable in your CONFIG.SYS file:

SET XDB_COIDX_TUTORIAL=C:\IDXSTORE

Then issue the following command (from SQLWizard, for example):

CREATE INDEX COIDX ON COMPANY(COKEY) USING VCAT NAME;

By allowing storage on a per index basis, the system can more flexibly use multiple physical devices, thereby increasing capacity and performance.

PRIQTY integer

Specifies the minimum primary space allocation for a DB2-managed data set. When you specify PRIQTY (with a value other than -1), the primary space allocation is at least n kilobytes, where n is:

  • 12 if integer is less than 12
  • integer if integer is between 12 and 4194304
  • 4194304 if integer is greater than 4194304

If you do not specify PRIQTY or specify PRIQTY -1, DB2 uses a default value for the primary space allocation.

If you specify PRIQTY and do not specify a value of -1, DB2 specifies the primary space allocation to access method services using the smallest multiple of 4KB not less than n. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the space requested.

When determining a suitable value for PRIQTY, be aware that two of the pages of the primary space are used by DB2 for purposes other than storing index entries.

This clause is only implemented syntactically in the XDB Server operating environment.

SECQTY integer

Specifies the minimum secondary space allocation for a DB2-managed data set. If you do not specify SECQTY, DB2 uses a formula to determine a value.

If you specify SECQTY and do not specify a value of -1, DB2 specifies the secondary space allocation to access method services using the smallest multiple of 4KB not less than n. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the space requested.

This clause is only implemented syntactically in the XDB Server operating environment.

GBPCACHE

In a data sharing environment, specifies what index pages are written to the group buffer pool. In a non-data-sharing environment, the option is ignored unless the index is on a declared temporary table. Do not specify GBPCAHCE for an index on a declared temporary table in either environment (data sharing or non-data-sharing).

CHANGED When there is inter-DB2 R/W interest on the index or partition, updated pages are written to the group buffer pool. When there is no inter-DB2 R/W interest, the group buffer pool is not used. Inter-DB2 R/W interest exists when more than one member in the data sharing group has the index or partition open, and at least one member has it open for update. GBPCACHE CHANGED is the default.

If the index is in a group buffer pool that is defined as GBPCACHE( NO), CHANGED is ignored and no pages are cached to the group buffer pool.

ALL Indicates that pages are to be cached in the group buffer pool as they are read in from DASD.

Exception: In the case of a single updating DB2 when no other DB2s have any interest in the page set, no pages are cached in the group buffer pool.

Hiperpools are not used for indexes or partitions that are defined with GBPCACHE ALL.

If the index is in a group buffer pool that is defined as GBPCACHE(NO), ALL is ignored and no pages are cached to the group buffer pool.

NONE Indicates that no pages are to be cached to the group buffer pool. DB2 uses the group buffer pool only for cross-invalidation.

If the index is partitioning, the value of GBPCACHE for a particular partition is given by the first of these choices that applies:

  1. The value of GBPCACHE given in the PART clause for that partition. Do not use more than one gbpcache-block in any PART clause.
  2. The value given in a gbpcache-block that is not in any PART clause.
  3. The default value is CHANGED.

This clause is only implemented syntactically in the XDB Server operating environment.

Regular Index

The following example creates an index called suppidx on the SNO column of the SUPPLIER table:

CREATE INDEX suppidx
    ON supplier (sno)

This index is used to speed data retrieval.

Unique Index

Unique indexes provide a means of preventing the insertion of duplicate data in a column which should have only one occurrence of a given value (including NULL values). For example, in the table PART, there should be only one part with the number P1. Building a unique index on PNO will prevent the entry of another P1. The command to build this index is:

CREATE UNIQUE INDEX pnoidx
    ON part (pno)

The system also can use unique indexes to speed data retrieval.

Compound Index

A compound index is an index made up of multiple columns. The XDB Server's compound indexes can contain up to 64 columns of a table, with a combined length of up to 190 characters. A compound index can be used to speed up processing of records that are usually ordered according to the field values in the index columns. However, the primary purpose of a unique compound index is to prevent entry of duplicate keys in a table.

A key consists of one or more table columns, the field values of which are used to identify records in a table. If the PARTSUPP table has a unique key containing the PNO and SNO columns, then there should exist one and only one record for each part supplied by a particular supplier. This can be ensured by creating a unique compound index with the command:

CREATE UNIQUE INDEX psidxON partsupp(pno, sno)
Note:

For a primary key constraint to function when running in DB2 mode, you must have created a unique index on the PNO and SNO columns of the PARTSUPP table using a command like:

CREATE UNIQUE INDEX ps_key
    ON partsupp (pno, sno)

The system checks for duplicate keys in the table when an attempt is made to create a unique compound index. If you are unable to create a unique compound index because your table creates duplicate keys, you should execute a query to determine which values have duplicates. To do this, select and group by all compound fields by using a clause such as:

HAVING COUNT(*) > 1

For example, if you want to create a unique compound index on the PNO and SNO columns of the PARTSUPP table, first execute the following command to verify whether there are any duplicate keys:

SELECT pno, sno
    FROM partsupp
    GROUP BY pno, sno
    HAVING COUNT(*) > 1

If this query retrieves any records, they are duplicates, and must be removed before creating the unique compound index.

Clustered Index

A clustered index is an index that physically orders the table data in the same sequence as the index. Only one clustered index is allowed per table. Building a clustered index causes all other indexes on the table to be rebuilt. Therefore, if the table is large (and contains many indexes) be sure to create the clustered index first.

The DUPQTY, CLUSTER and PCTFREE clauses can appear in any order after the CREATE INDEX clause. For example:

CREATE INDEX aidx ON employee(e_no)
    PCTFREE 10 CLUSTER;
CREATE INDEX aidx ON employee(lname)
    CLUSTER PCTFREE 30;
CREATE INDEX aidx ON employee(fname)
    CLUSTER;
CREATE INDEX aidx ON employee(payrate)
    PCTFREE 50 DUPQTY 16;

Examining Index Definitions

Creating or dropping an index causes the system to automatically update system tables for that location. You can query the system catalog tables for table, view, column, and index information. The query results can be formatted into your own reports. See XDB System Tables for descriptions of the system tables.

You can use the Catalog Browser function of SQLWizard to list table, view and index definitions using the format:

If a column is indexed, the name(s) of the index or indexes are listed after the column name, separated by a slash (/). Index type indicators consisting of a letter or a number may appear within parentheses after the index name.

Indicator | Meaning
no letter | Regular index (duplicate values permitted)
p | Primary key
c | Candidate (Unique) key
f | Foreign key
u | Unique index
no number | Single column index
# | Compound index; # is sequence number indicating order of column in a compound index

Next, the data type of the column is listed. The NOT NULL or NOT NULL WITH DEFAULT keywords specifies the null permission of the column. If omitted, nulls are permitted in the column.

Dropping an Index

Partitioning indexes can only be dropped by dropping the associated table space. Nonpartitioning indexes that are not indexes on auxiliary tables can be dropped simply by dropping the indexes. An empty index on an auxiliary table can be explicitly dropped; a populated index can be dropped only by dropping other objects.

Examples

Create a unique index, named DSN8610.XDEPT1, on table DSN8610.DEPT. Index entries are to be in ascending order by the single column DEPTNO. DB2 is to define the data sets for the index, using storage group DSN8G610. Each data set (piece) should hold 1 megabyte of data at most. Use 512 kilobytes as the primary space allocation for each data set and 64 kilobytes as the secondary space allocation. These specifications enable each data set to be extended up to 8 times before a new data set is used--512KB + (8*64KB)= 1024KB.

The data sets can be closed when no one is using the index and do not need to be erased if the index is dropped.

CREATE UNIQUE INDEX DSN8610.XDEPT1
    ON DSN8610.DEPT(DEPTNO ASC)
    USING STOGROUP DSN8G610
        PRIQTY 512
        SECQTY 64
        ERASE NO
    BUFFERPOOL BP1
    CLOSE YES
    PIECESIZE 1 M;

For the above example, the underlying data sets for the index will be created immediately, which is the default (DEFINE YES). Assuming that table DSN8610.DEPT is empty, if you wanted to defer the creation of the data sets until data is first inserted into the index, you would specify DEFINE NO instead of accepting the default behavior.

Create a cluster index, named XEMP2, on table EMP in database DSN8610. Put the entries in ascending order by column EMPNO. Let DB2 define the data sets for each partition using storage group DSN8G610. Make the primary space allocation be 36 kilobytes, and allow DB2 to use the default value for SECQTY, which for this example is 12 kilobytes (3 times 4KB). If the index is dropped, the data sets need not be erased.

There are to be 4 partitions, with index entries divided among them as follows:

Partition 1 | entries up to H99
Partition 2 | entries above H99 up to P99
Partition 3 | entries above P99 up to Z99
Partition 4 | entries above Z99

Associate the index with buffer pool BP1 and allow the data sets to be closed when no one is using the index. Enable the use of the COPY utility for full image or concurrent copies and the RECOVER utility.

CREATE INDEX DSN8610.XEMP2
    ON DSN8610.EMP(EMPNO ASC)
    USING STOGROUP DSN8G610
        PRIQTY 36
        ERASE NO
    CLUSTER(
        PART 1 VALUES('H99'),
        PART 2 VALUES('P99'),
        PART 3 VALUES('Z99'),
        PART 4 VALUES('999'))
    BUFFERPOOL BP1
    CLOSE YES
    COPY YES;

Create a nonpartitioning index, named DSN8610.XDEPT1, on table DSN8610.DEPT. Put the entries in ascending order by column DEPTNO. Assume that the data sets are managed by the user with catalog name DSNCAT and each data set (piece) is to hold 1 gigabyte of data at most before the next data set is used.

CREATE UNIQUE INDEX DSN8610.XDEPT1
    ON DSN8610.DEPT(DEPTNO ASC)
    USING VCAT DSNCAT
    PIECESIZE 1048576 K;

Assume that a column named EMP_PHOTO with a data type of BLOB(110K) was added to the sample employee table for each employee's photo and auxiliary table EMP_PHOTO_ATAB was created in LOB table space DSN8D61A.PHOTOLTS to store the BLOB data for the column. Create an index named XPHOTO on the auxiliary table. The data sets are to be user-managed with catalog name DSNCAT.

CREATE UNIQUE INDEX DSN8610.XPHOTO
    ON DSN8610.EMP_PHOTO_ATAB
    USING VCAT DSNCAT
    COPY YES;

In this example, no columns are specified for the key because auxiliary indexes have implicitly generated keys.

Parent topic: SQL Statements
Related information
Syntax Support Only
System Table Overview


CREATE LOCATION

The CREATE LOCATION command allows you to define multiple XDB Server locations under the same XDB Server. Each XDB Server location contains a set of catalog tables for that location.
Restriction: This topic applies to Windows environments only.

Invocation

CREATE LOCATION is an executable command that can be issued interactively, embedded in a host language or dynamically prepared.

Authorization

Users must possess the INSTALL authority (or be a super user) to create or drop XDB Server locations.

Syntax

CREATE LOCATION <location-name> IN <location-path>
        SORT SEQUENCE {<language-name> EBCDIC | EBCDIC | INSENSITIVE | SENSITIVE | USER}]
    [XDB SYSTEM TABLES]
    [VERSION V23 | V31 | V41 | V51 | V60| V71| V80]

Parameters:

location-name | Specifies a 1 to 16 character name for a new user-created location. This name must be unique among all location names created under this XDB Server.
location-path | Preceded by the keyword IN, specifies a path for storing the new location files. This path is usually a subdirectory under the XDB Server directory, but can be any user-specified path.

Description

When the CREATE LOCATION command is issued, the XDB Server creates a directory structure for the new location and adds information about the new location to the SYSXDB.SYSLOCALS, and SYSIBM.SYSLOCATIONS catalog tables in the SYSTEM location.

A unique name must be specified for each location (following the rules for long identifiers), along with a directory path for the location's files and database subdirectories. The first eight characters of the location-name parameter also serve as the file name for a set of dictionary files, which are automatically created by the XDB Server for each new location, and stored in the location's root directory (location-path parameter).

location-name.DDT | Contains information about the tables associated with a location.
location-name.DDF | Contains information about the table columns associated with a location.
location-name.DDI | Contains information about the indexes associated with a location.
location-name.DDV | Contains information on the XDB Server version used to create the location.

These location dictionary files are automatically maintained and updated by the XDB Server and cannot be accessed by users.

SORT SEQUENCE

This clause allows you to choose between a case SENSITIVE, case INSENSITIVE, EBCDIC, or USER defined sort sequence for the new location. The XDB Server default is case INSENSITIVE.

FORWARD LOG

If Forward Log archiving for the location is desired, you can assign both a Forward Log name and optional path designation. If no Forward Log name is specified, the XDB Server creates a default log name by taking the first eight characters of the location name and appending a .FWD file extension. Forward Log files should ideally be stored on separate disk drives, allowing for extra insurance in the event of a location drive failure. Forward Log options are stored in the SYSXDB.SYSLOCALS catalog table in the SYSTEM location.

VERSION

Since system catalog tables differ with each XDB Server version, locations created with an older version XDB Server are not compatible with a newer version XDB Server. This optional clause creates an XDB Server location compatible with DB2 3.1, 4.1, 5.1, 6.0, 7.1 or 8.0 by using a value of V31, V41, V51, V60, V71 or V80 within the VERSION clause. V23, V31, V41, V51, V60, V71 and V80 are the only valid options for the VERSION clause.

Example:

The following command creates a location subdirectory named locat1 under the XDB Server directory (C:\XDB60):

CREATE LOCATION jbl IN d:\qa\jbl sort sequence german ebcdic;
Parent topic: SQL Statements


CREATE PROCEDURE

The CREATE PROCEDURE command defines a Stored Procedure to the SQL engine. You can then embed an SQL CALL statement in a program to invoke the stored procedure.
Restriction: This topic applies to Windows environments only.

Invocation

CREATE PROCEDURE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the CREATE PROCEDURE command, users must possess one (or more) privileges listed in the SYSADM or SYSCTRL authority.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE PROCEDURE procedure-name
    [(parameter-declaration [,...])]
    option-list

parameter-declaration

[IN | OUT | INOUT] [parameter-name] parameter-type

parameter-type

{data-type [AS LOCATOR] | TABLE LIKE {table-name | view-name} AS LOCATOR}

data-type

{built-in-type | distinct-type-name}

built-in-type

{SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [(5,0) | (integer [,integer])] |
{FLOAT [(1) | (integer)] | REAL [PRECISION] | DOUBLE} |
{{{CHARACTER | CHAR} [(1) | (integer)] | {{CHARACTER | CHAR} VARYING | VARCHAR} (integer)}
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {ASCII | EBCDIC | UNICODE}] |
 {{CHARACTER |CHAR} LARGE OBJECT | CLOB} [(1M) | (integer [K | M | G])] [FOR {SBCS | MIXED} DATA]
    [CCSID {ASCII | EBCDIC | UNICODE}] } |
{{GRAPHIC [(1) | (integer)] | VARGRAPHIC (integer) | DBCLOB [(1M) | (integer [K | M | G])]}
    [CCSID {ASCII | EBCDIC | UNICODE}]} |
{{BINARY LARGE OBJECT | BLOB} [(1M) | (integer [K | M | G])]} |
{DATE | TIME | TIMESTAMP} |
ROWID}

option-list

[DYNAMIC RESULT SETS 0 | DYNAMIC RESULT SETS integer]
[PARAMETER CCSID {ASCII | EBCDIC | UNICODE}]
[EXTERNAL [NAME {'string' | identifier}]]
[LANGUAGE {ASSEMBLE | C | COBOL | JAVA | PLI | REXX}]
[MODIFIES SQL DATA | READS SQL DATA | CONTAINS SQL | NO SQL]
[PARAMETER STYLE {SQL | GENERAL | GENERAL WITH NULLS | JAVA}]
[DETERMINISTIC | NOT DETERMINISTIC]
[FENCED]
[DBINFO | NO DBINFO]
[COLLID collection-id | NO COLLID]
[WLM ENVIRONMENT {name | (name,*)}]
[ASUTIME NO LIMIT | ASUTIME LIMIT integer]
[STAY RESIDENT YES | STAY RESIDENT NO]
[PROGRAM TYPE {SUB | MAIN}]
[SECURITY {DB2 | USER | DEFINER}]
[STOP AFTER SYSTEM DEFAULT FAILURES | STOP AFTER integer FAILURES | CONTINUE AFTER FAILURE]
[RUN OPTIONS run-time-options]
[COMMIT ON RETURN YES | COMMIT ON RETURN NO]
[INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
[CALLED ON NULL INPUT]

Parameters:

Procedure-name | If unqualified, the procedure name is any long identifier that uniquely names the procedure. A qualified procedure name is schema name (short identifier), a period, and then a long identifier. If unqualified, the schema name is the SQL authorization ID in the CURRENT SQLID special register.The schema name can be 'SYSIBM' or 'SYSPROC'. It can also be 'SYSTOOLS' if the user who executes the CREATE statement has SYSADM or SYSCTRL privilege. Otherwise, the schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.
Load-module-name | Load module name is a short identifier naming the procedure executable module. The load module name specifies the name of a DLL file.

Comments:

If no length is specified for CHAR, VARCHAR, GRAPHIC, or VARGRAPHIC, the default length is 1. If precision is not specified for DECIMAL, the default is DECIMAL (5,0).

Parameter-name:

A parameter name is a long identifier naming the parameter.

RESULT SETS clause:

Specifies the maximum number of result sets that the stored procedure can return to the invoking program. The default is RESULT SETS 0, indicating there are no result sets being returned.

PARAMETER STYLE clause:

Identifies the convention used to pass arguments to the stored procedure. When using GENERAL, none of the arguments can be null. GENERAL WITH NULLS passes an additional argument after the arguments on the CALL PROCEDURE statement. The additional argument is an array of null indicators, one for each of the defined arguments for the stored procedure.

PROGRAM TYPE clause:

For stored procedures defined as LANGUAGE COBOL or PLI, there is no difference between MAIN or SUB.

COMMIT ON RETURN clause:

This default for this clause is NO. If COMMIT ON RETURN YES is specified, the SQL engine will issue a commit when the stored procedure returns if the transaction is not in a must rollback state. If the stored procedure uses the WITH RETURN clause to define cursors that will be returned as result sets, the cursors must also be defined as WITH HOLD if COMMIT ON RETURN YES is specified or the cursors will be closed by the SQL engine.

Parent topic: SQL Statements


CREATE PROCEDURE

The CREATE PROCEDURE statement defines an SQL procedure at the current server and specifies the source statements for the procedure.
Restriction: This topic applies to Windows environments only.

The XDB Server operating environment only provides syntax support for external Procedures (SQL) at this time.

Invocation

This statement can only be dynamically prepared, but the DYNAMICRULES run behavior must be specified implicitly or explicitly. It is intended to be processed using one of the following methods:

  • JCL
  • The DB2 UDB for z/OS SQL procedure processor (DSNTPSMP)

Issuing the CREATE PROCEDURE statement from another context will result in an incomplete procedure definition even though the statement processing returns without error.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATEIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

The privilege set is the privileges that are held by the SQL authorization ID of the process.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process. The specified procedure name can include a schema name (a qualifier). However, if the schema name is not the same as the SQL authorization ID, one of the following conditions must be met:

  • The privilege set includes SYSADM or SYSCTRL authority.
  • The SQL authorization ID of the process has the CREATEIN privilege on the schema.

The authorization ID that is used to create the stored procedure must have authority to create programs that are to be run either in the DB2-established stored procedure address space or the specified workload manager (WLM) environment.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE PROCEDURE procedure-name
    [(parameter-declaration [,...])] LANGUAGE SQL
    option-list SQL-routine-body

parameter-declaration

[IN | OUT | INOUT] parameter-name parameter-type

parameter-type

{built-in-type | TABLE LIKE table-name AS LOCATOR}

built-in-type

[SMALLINT]
[INTEGER | INT]
[DECIMAL | DEC | NUMERIC} [(5,0) | (integer [,integer])]
[FLOAT [(53) | (integer)] | REAL [PRECISION] | DOUBLE}]
[{{CHARACTER | CHAR} [(1) | (integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] |
    {{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(1M) | (integer [K | M | G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII | UNICODE}] }]
[{GRAPHIC [(1) | (integer)] | VARGRAPHIC (integer) | DBCLOB [(1M) | (integer [K | M | G])]}
    [CCSID {ASCII | EBCDIC | UNICODE}]]
[{BINARY LARGE OBJECT | BLOB} [(1M) | (integer [K | M | G])]]
[DATE | TIME | TIMESTAMP]
[ROWID]

option-list

[DYNAMIC RESULT SETS 0 | DYNAMIC RESULT SETS integer]
[PARAMETER CCSID {ASCII | EBCDIC | UNICODE}]
[EXTERNAL [NAME {'string' | identifier}]]
[MODIFIES SQL DATA | READS SQL DATA | CONTAINS SQL]
[DETERMINISTIC | NOT DETERMINISTIC]
[FENCED]
[NO DBINFO]
[COLLID collection-id | NO COLLID]
[WLM ENVIRONMENT {name | (name,*)}]
[ASUTIME NO LIMIT | ASUTIME LIMIT integer]
[STAY RESIDENT YES | STAY RESIDENT NO]
[PROGRAM TYPE {SUB | MAIN}]
[SECURITY {DB2 | USER | DEFINER}]
[STOP AFTER SYSTEM DEFAULT FAILURES | STOP AFTER integer FAILURES | CONTINUE AFTER FAILURE]
[RUN OPTIONS run-time-options]
[COMMIT ON RETURN YES | COMMIT ON RETURN NO]
[INHERIT SPECIAL REGISTERS | DEFAULT SPECIAL REGISTERS]
[CALLED ON NULL INPUT]
Parent topic: SQL Statements


CREATE SEQUENCE

The CREATE SEQUENCE statement creates a sequence at the application server.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set that is defined below must include at least one of the following:

  • The CREATEIN privilege on the schema
  • SYSADM or SYSCTRL authority

The authorization ID that matches the schema name implicitly has the CREATEIN privilege on the schema.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process.

If the data type of the sequence is a distinct type, the privilege set must include the USAGE privilege on the distinct type.

Syntax

CREATE SEQUENCE sequence-name [AS {INTEGER | data-type} |
     START WITH numeric-constant |
     {INCREMENT BY 1 | INCREMENT BY numeric-constant} |
     {MINVALUE numeric-constant | NO MINVALUE} |
     {MAXVALUE numeric-constant | NO MAXVALUE} |
     {CYCLE | NO CYCLE} |
     {CACHE 20 | CACHE integer-constant | NO CACHE} |
     {ORDER | NO ORDER}
     ] [,...]
Note: The same clause must not be specified more than once. Separator commas may or may not be specified between sequence attributes when a sequence is defined.

Description

SEQUENCE sequence-name

Names the sequence. The combination of name and the implicit or explicit name must not identify an existing sequence at the current server, including the internal names generated by DB2 for identity names.

The unqualified form of sequence-name is an SQL identifier. The unqualified name is implicitly qualified with a schema name according to the following rules:

  • If the CREATE SEQUENCE statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not specified, the schema name is the owner of the plan or package.
  • If the CREATE SEQUENCE statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

The contents of the SQL PATH are not used to determine the implicit qualifier of a sequence name.

The qualified form of sequence-name is a schema followed by a period and an SQL identifier. The schema name must not begin with 'SYS' unless the schema name is 'SYSADM'.

The owner of the sequence is determined by the following conditions. If the CREATE SEQUENCE statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package. If the CREATE SEQUENCE statement is dynamically prepared, the owner is the SQL authorization ID contained in the CURRENT SQLID special register. The owner has the ALTER and USAGE privileges on the new sequence with the GRANT option. These privileges can be granted by the owner and cannot be revoked from the owner.

AS data-type

Specifies the data type to be used for the sequence value. The data type can be any exact numeric data type (SMALLINT, INTEGER, or DECIMAL with a scale of zero), or a user-defined distinct type for which the source type is an exact numeric data type with a scale of zero. The default is INTEGER.

START WITH numeric-constant

Specifies the first value for the sequence. The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point.

If the START WITH key word is not explicitly specified with a value, the default is the MINVALUE for ascending sequences and MAXVALUE for descending sequences.

This value is not necessarily the value that a sequence would cycle to after reaching the maximum or minimum value of the sequence. The START WITH clause can be used to start a sequence outside the range that is used for cycles. The range used for cycles is defined by MINVALUE and MAXVALUE.

INCREMENT BY numeric-constant

Specifies the interval between consecutive values of the sequence. The value can be any positive or negative value (including 0) that could be assigned to a column of the data type that is associated with the sequence without any non-zero digits existing to the right of the decimal point. The default is 1.

If INCREMENT BY is positive, the sequence ascends. If INCREMENT BY is negative, the sequence descends. If INCREMENT is 0, the sequence is treated as an ascending sequence.

The absolute value of INCREMENT BY can be greater than the difference between MAXVALUE and MINVALUE.

MINVALUE or NO MINVALUE

Specifies the minimum value at which a descending sequence either cycles or stops generating values or an ascending sequence cycles to after reaching the maximum value. The default is NO MINVALUE.

MINVALUE numeric-constant

Specifies the minimum end of the range of values for the sequence. The last value that is generated for a cycle of a descending sequence will be equal to or greater than this value. MINVALUE is the value to which an ascending sequence cycles to after reaching the maximum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

NO MINVALUE

Specifies that the minimum end point of the range of values for the sequence has not been specified explicitly. In such a case, the default value for MINVALUE becomes one of the following:

  • For an ascending sequence, the value is the START WITH value or 1 if START WITH is not specified.
  • For a descending sequence, the value is the minimum value of the data type that is associated with the sequence.

MAXVALUE or NO MAXVALUE

Specifies the minimum value at which an ascending sequence either cycles or stops generating values or an descending sequence cycles to after reaching the minimum value. The default is NO MAXVALUE.

MAXVALUE numeric-constant

Specifies the maximum end of the range of values for the sequence. The last value that is generated for a cycle of an ascending sequence will be less than or equal to this value. MAXVALUE is the value to which a descending sequence cycles to after reaching the minimum value.

The value can be any positive or negative value that could be assigned to the a column of the data type that is associated with the sequence without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

NO MAXVALUE

Specifies the maximum end point of the range of values for the sequence has not been specified explicitly. In such a case, the default value for MAXVALUE becomes one of the following:

  • For an ascending sequence, the value is the maximum value of the data type that is associated with the sequence.
  • For a descending sequence, the value is the START WITH value or -1 if START WITH is not specified.

CYCLE or NO CYCLE

Specifies whether or not the sequence should continue to generate values after reaching either its maximum or minimum value. The boundary of the sequence can be reached either with the next value landing exactly on the boundary condition or by overshooting it. The default is NO CYCLE.

CYCLE

Specifies that the sequence continue to generate values after either the maximum or minimum value has been reached. If this option is used, after an ascending sequence reaches its maximum value, it generates its minimum value. After a descending sequence reaches its minimum value, it generates its maximum value. The maximum and minimum values for the sequence defined by the MINVALUE and MAXVALUE options determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by the sequence. When a sequence is defined with CYCLE, any application conversion tools for converting applications from other vendor platforms to DB2 should also explicitly specify MINVALUE, MAXVALUE, and START WITH values.

NO CYCLE

Specifies that the sequence cannot generate more values once the maximum or minimum value for the sequence has been reached. The NO CYCLE option (the default) can be altered to CYCLE at any time during the life of the sequence.

When the next value is being generated for a sequence if the maximum value (for an ascending sequence) or the minimum value (for a descending sequence) of the logical range of the sequence is exceeded and the NO CYCLE option is in effect, an error occurs.

CACHE or NO CACHE

Specifies whether or not to keep some preallocated values in memory for faster access. This is a performance and tuning option.

CACHE integer-constant

Specifies the maximum number of values of the sequence that XDB can preallocate and keep in memory. Preallocating values in the cache reduces synchronous I/O when values are generated for the sequence. The actual number of values that XDB caches is always the lesser of the number in effect for the CACHE option and the number of remaining values within the logical range. Thus, the CACHE value is essentially an upper limit for the size of the cache.

In the event of a system failure, all cached sequence values that have not been used in committed statements are lost (that is, they will never be used). The value specified for the CACHE option is the maximum number of sequence values that could be lost in case of system failure.

The minimum value is 2. The default is CACHE 20.

In a data sharing environment, you can use the CACHE and NO ORDER options to allow multiple XDB members to cache sequence values simultaneously.

NO CACHE

Specifies that values of the sequence are not to be preallocated. This option ensures that there is not a loss of values in the case of a system failure. When NO CACHE is specified, the values of the sequence are not stored in the cache. In this case, every request for a new value for the sequence results in synchronous I/O.

ORDER or NO ORDER

Specifies whether the sequence numbers must be generated in order of request. The default is NO ORDER.

ORDER

Specifies that the sequence numbers are generated in order of request. Specifying ORDER may disable the caching of values. There is no guarantee that values are assigned in order across the entire server unless NO CACHE is also specified. ORDER applies only to a single-application process.

NO ORDER

Specifies that the sequence numbers do not need to be generated in order of request.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for next value assignments from different members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the same sequence, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested for next value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that sequence numbers are generated in strict numeric order among multiple members using the same sequence concurrently, specify the ORDER option.

Note:
  • MINVALUE must not be greater than MAXVALUE. Although MINVALUE is typically less than MAXVALUE, MINVALUE can equal MAXVALUE. If START WITH were the same value as MINVALUE and MAXVALUE, the sequence would be constant. The request for the next value in a constant sequence appears to have no effect because all of the values that are generated by the sequence are in fact the same value.
  • When you define a sequence, you can choose to have it cycle automatically or not when the maximum or minimum value for the sequence has been reached.
    • Implicitly or explicitly defining a sequence with NO CYCLE causes the sequence to not cycle automatically after the boundary is reached. However, you can use the ALTER SEQUENCE statement to cycle the sequence manually. ALTER SEQUENCE allows you to restart or extend the sequence, which causes sequence values to continue to be generated.
    • Explicitly defining a sequence with CYCLE causes the sequence to cycle automatically after the boundary is reached. Sequence values continue to be generated after the sequence cycles.

      When a sequence is defined to cycle automatically, the maximum or minimum value that is generated for a sequence may not be the actual MAXVALUE or MINVALUE value that is specified if the increment is a value other than 1 or -1. For example, the sequence defined with START WITH=1, INCREMENT=2, MAXVALUE=10 will generate a maximum value of 9, and will not generate the value 10.

      When a sequence is defined with CYCLE, any application conversion tools (for converting applications from other vendor platforms to DB2) should also explicitly specify MINVALUE, MAXVALUE, and START WITH.

  • You can define a sequence such that it always returns the same (or a constant) value. To create a constant sequence, use either of these techniques when defining the sequence:
    • Specify an INCREMENT value of zero and a START WITH value that does not exceed MAXVALUE.
    • Specify the same value for START WITH, MINVALUE, and MAXVALUE, and specify CYCLE. A constant sequence can be used as a numeric global variable. You can use ALTER SEQUENCE to adjust the values that are generated for a constant sequence.
  • After XDB generates a value for a sequence, that value can be said to be "consumed" regardless of whether or not that value is utilized by the application or not. The value is not reused within the current cycle. A consumed value may not be utilized when the statement that caused the value to be generated fails for some reason or is rolled back after the value was generated. Generated but unused values may constitute gaps in a sequence.
  • Consecutive values in a sequence differ by the constant INCREMENT BY value specified for the sequence. However, gaps can be introduced in a sequence in situations like the following ones:
    • A transaction has advanced the sequence and then rolls back.
    • The SQL statement leading to the generation of the next value fails after the value was generated.
    • The NEXT VALUE expression is used in the SELECT statement of a cursor in a DRDA environment where the client uses block-fetch and not all retrieved rows are fetched by the application.
    • The sequence is altered and then the alteration is rolled back.
    • The sequence is dropped and then the dropping is rolled back.

      Values of such gaps are not available for the current cycle, unless the sequence is altered and restarted in a specific way to make them available.

      A sequence is incremented independently of a transaction. Thus, a given transaction increments the sequence two times may see a gap in the two numbers that it receives if other transactions concurrently increment the same sequence. Most applications can tolerate these instances as these are not really gaps.

  • It is possible the duplicate values can be generated for a sequence. Duplicate values are most likely to occur when a sequence is defined with the CYCLE option, is defined as a constant sequence, or is altered. For example, the following situations could cause duplicate sequence values:
    • A sequence is defined with the attributes START WITH=2, INCREMENT BY 2, MINVALUE=2, MAXVALUE=10, and CYCLE.
    • The ALTER SEQUENCE statement is used to restart the sequence with a value that has already been generated.
    • The ALTER SEQUENCE statement is used to reverse the ascending direction of a sequence by changing the INCREMENT BY value from a positive to a negative.
  • A sequence can be referenced using a sequence reference. A sequence reference can appear in most places that an expression can appear. A sequence reference can specify whether the value to be returned is a newly generated value or the previously generated value. A NEXT VALUE sequence expression is used to generate a new value. A PREVIOUS VALUE sequence expression is used to obtain the last assigned value of a sequence.
  • To provide compatibility with previous releases, XDB supports the following keywords:
    • NOMINVALUE (single key word) as a synonym for NO MINVALUE
    • NOMAXVALUE (single key word) as a synonym for NO MAXVALUE
    • NOCYCLE (single key word) as a synonym for NO CYCLE
    • NOCACHE (single key word) as a synonym for NO CACHE
    • NOORDER (single key word) as a synonym for NO ORDER
Parent topic: SQL Statements


CREATE STOGROUP

The CREATE STOGROUP command creates an XDB Server stogroup which associates a user-specified directory path with the named stogroup. Once the SYSIBM.SYSVOLUMES catalog table has been updated to reflect this path assignment, newly created objects can be physically stored in this directory path by designating the named stogroup when creating the objects.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The XDB Server checks to verify whether the AuthID issuing this command has either the CREATESG privilege, or SYSADM or SYSCTRL authority for the location.

Syntax

CREATE STOGROUP stogroup-name
    VOLUMES (volume-id[,...])
    VCAT catalog-name [PASSWORD password]

Parameters:

stogroup-name | Identifies the stogroup. This 1 to 8 characters name must be unique among stogroup names created at the currently set location.
volume-id | Identifies one or more Volume IDs, any of which can be associated (by updating the SYSIBM.SYSVOLUMES table) with a path designated specifically for the named stogroup.
catalog-name | Identifies an Integrated Catalog Facility catalog existing on a DB2-mainframe system.
password | Furnishes a VSAM control or master level password for the ICF catalog on a DB2-mainframe system.

Description

The stogroup feature allows XDB Server users greater control in assigning objects to specific directory paths. For example, you can assign storage of individual data objects to specially created stogroup directories (such as E:\STOR1\ or D:\STOR2\).

VOLUMES

This clause assigns a series of volume-id values (limit of 133) to the named stogroup. The XDB Server stores these values in the VOLID column of the SYSIBM.SYSVOLUMES catalog table. Whenever the stogroup is specified in an object creation command, the XDB Server uses these volume-id values to physically store the new objects on the path recorded in SYSIBM.SYSVOLUMES for the named stogroup. Users must first manually update the XDBPRIMEVOLPATH and XDBVOLPATH columns in SYSIBM.SYSVOLUMES. These columns associate a physical path with the value recorded in the VOLID column.

Asterisks are recognized only by Storage Management Subsystem (SMS). Contact your site's storage administrator to determine if the SMS Guaranteed Space attribute applies. If SMS Guaranteed Space does not apply for SMS-managed data sets, it is recommended that the VOLUMES clause be specified with one asterisk, VOLUMES('*' ). If SMS Guaranteed Space does apply, contact your site storage manager and refer to DFSMS/MVS: Access Method Services for the Integrated Catalog and DFSMS/MVS: Storage Administration Reference for DFSMSdfp for information on how to specify the VOLUMES clause.

Note:

There is no specific limit on the number of volumes that can be defined for a storage group. However, the maximum number of volumes that can be managed for a storage group is 133. Thus, there is no point in creating a storage group with more than 133 volumes.

VCAT

Although this clause has no physical functionality within the XDB Server system architecture, the keyword VCAT and a catalog-name value of "xdb" must be specified when working in DB2 mode. This information is recorded in the catalog tables for the current XDB Server location. The password parameter is also mainframe-specific, and is recorded in the XDB Server catalog tables.

Example:

The following command (executed in DB2 mode) creates a stogroup named STOR1 and assigns a volume-id value of "myid" to the VOLID column of the SYSIBM.SYSVOLUMES catalog table:

CREATE STOGROUP stor1 VOLUMES (myid) VCAT xdb;

The next example updates the SYSIBM.SYSVOLUMES catalog table by associating a user-created path (D:\STOR1) with myid:

UPDATE SYSIBM.SYSVOLUMES
    SET xdbprimevolpath = "y"
    , xdbvolpath = "d:\stor1\"
WHERE volid = "myid";
Parent topic: SQL Statements


CREATE SYNONYM

The CREATE SYNONYM command is used to define alternate names for tables or views within the currently set location.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

No special authorization is required. However, you must possess the appropriate privileges on the object to which the synonym refers before you can use the synonym. If dynamically prepared, the synonym is owned by the CURRENT SQLID.

In the case of users with SYSADM authority, ownership can be assigned to other users by first changing the CURRENT SQLID special register value, and then issuing the CREATE SYNONYM statement. The originally recorded AuthID for a synonym is the only AuthID for which the synonym is defined, and the only AuthID that can drop the synonym.

Syntax

CREATE SYNONYM synonym
FOR authorization-name.{table-name | view-name}

Parameters:

synonym | Specifies the alternate name you want to define. The synonym may be up to 18 characters long, and must meet all other criteria for a table or view name. The synonym must be unique among the set of all table names, view names and synonyms in the current location.
authorization-name.{table-name or view-name} | Identifies an existing table or view (with associated AuthID) to which you intend to assign a synonym. The name must consist of two parts and must identify a table, view, or alias that exists at the current server. If a table is identified, it must not be an auxiliary table or a declared temporary table. If an alias is identified, it must be an alias for a table or view at the current server and the synonym is defined for that table or view.

Description

Synonyms can be used to assign alternate names to existing tables or views at the current location. Synonyms may be used interchangeably with their corresponding view or table names in SQL commands. If using a synonym name when granting or revoking privileges or creating indexes, the actual table or view name is substituted for the synonym name before the command is executed.

If a CREATE SYNONYM command denotes an alias name instead of an actual table or view, that table or view (not the named alias) is recorded in the system catalog as the object of the synonym. In these cases the connection between the synonym and alias is severed. If the original alias name is later dropped and redefined, the synonym naming the original table or view is still in effect.

Example:

The example below assigns the alternate name syscolumns for the system table SYSIBM.SYSCOLUMNS:

CREATE SYNONYM syscolumns FOR SYSIBM.SYSCOLUMNS

Once this synonym is created, the query:

SELECT * FROM syscolumns

returns the same result as:

SELECT * FROM SYSIBM.SYSCOLUMNS
Parent topic: SQL Statements


CREATE TABLE

The CREATE TABLE statement defines a table. The definition must include its name and the names and attributes of its columns. The definition can include other attributes of the table, such as its primary key and its table space.
Restriction: This topic applies to Windows environments only.

CREATE TABLE clauses have been extended to include options for defining and dropping table check constraints, and specifying columns with user-defined defaults.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE TABLE command, users must possess one (or more) privileges listed in at least one of the following:

  • DBADM, DBCTRL, DBMAINT or CREATETS authority for the database.
  • Overall SYSADM or SYSCTRL authority for the location.
  • CREATETAB privilege for the database that is implicitly or explicitly specified by the IN clause.

Additional privileges might be required in the following conditions:

  • The clause IN, LIKE or FOREIGN KEY is specified.
  • The data type of a column is a distinct type.
  • The table space is implicitly created.
  • A fullselect is specified.
  • A column is defined as a security label column.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package.

  • If the privilege set lacks SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table must be the same as the authorization ID of the owner of the plan or package.
  • If the privilege set includes SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table can be any authorization ID.

If the statement is dynamically prepared, the privilege set is the privileges that are held by the SQL authorization ID of the process.

  • If the privilege set lacks SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table must be the same as one of the authorization IDs of the process and the privilege set that is held by that authorization ID includes all privileges needed to create the table.
  • If the privilege set includes SYSADM or SYSCTRL authority, DBADM authority for the database, or DBCTRL authority for the database, the qualifier (owner) of the table can be any authorization ID.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE TABLE table-name
{
    (column-definition
        [unique-constraint]
        [referential-constraint]
        [select-command]
        [check-constraint] [,...])
     | LIKE {table-name | view-name} [INCLUDING IDENTITY [COLUMN ATTRIBUTES]]
     | materialized-query-definition
}
    [WITH RESTRICT ON DROP]
    [{IN [database-name.]tablespace-name
        | IN DATABASE database-name}]
    [partitioning-clause]
    [EDITPROC program-name]
    [VALIDPROC program-name]
    [AUDIT {NONE | CHANGES | ALL}]
    [OBID integer]
    [DATA CAPTURE {NONE | CHANGES}]
    [WITH RESTRICT ON DROP]
    [CCSID {ASCII | EBCDIC | UNICODE}]
     [{VOLATILE | NOT VOLATILE} [CARDINALITY]]

unique-constraint:

{UNIQUE | PRIMARY KEY}(column-name[,...])

referential-constraint:

FOREIGN KEY [constraint-name] (column-name[,...])
    references-clause

references-clause:

REFERENCES referenced-table
    [column-name ,...]
    [ON DELETE {RESTRICT | NO ACTION | CASCADE | SET NULL}]
    [ENFORCED | NOT ENFORCED]
    [ENABLE QUERY OPTIMIZATION]

check-constraint:

[CONSTRAINT constraint-name] CHECK (check-condition)

column-definition:

column-name data-type
    [NOT NULL]
    [column-constraint]
    [{UNIQUE | PRIMARY KEY}]
    [FOR {BIT | SBCS | MIXED} DATA]
    [default-clause]
    [GENERATED {ALWAYS | BY DEFAULT} [as-identity-clause]
    [references-clause]
    [check-constraint]
    [FIELDPROC program-name [(constant[,...])]]
    [AS SECURITY LABEL]

default-clause:

[WITH] DEFAULT
[{constant | USER | CURRENT SQLID | NULL | cast-function-name ({constant | USER | CURRENT SQLID | NULL})}]

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
[FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
[FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

as-identity-clause:

AS IDENTITY
[({START WITH {numeric-constant | 1}
| INCREMENT BY {numeric-constant | 1}
| MINVALUE numeric-constant | NOMINVALUE
| MAXVALUE numeric-constant | NOMAXVALUE
| CYCLE | NOCYCLE
| ORDER | NO ORDER
| {CACHE 20 | NO CACHE | CACHE integer}}][,..])]

partitioning-clause:

PARTITION BY [RANGE] (partition-expression[,...]) (partition-element[,...])

partition-expresion:

column-name [NULLS LAST] [ASC | DESC]

partition-element:

PARTITION integer ENDING [AT] (constant[,...]) [INCLUSIVE]

materialized-query-definition:

[(column-name[,...])] AS (fullselect)
{WITH NO DATA [copy-options] | refreshable-table-options}

copy-options:

[EXCLUDING IDENTITY [COLUMN ATTRIBUTES] |
INCLUDING IDENTITY [COLUMN ATTRIBUTES]]
[EXCLUDING [COLUMN] DEFAULTS | INCLUDING [COLUMN] DEFAULTS | USING TYPE DEFAULTS]

refreshable-table-options:

DATA INITIALLY DEFERRED REFRESH DEFERRED
[[MAINTAINED BY SYSTEM | MAINTAINED BY USER]
[ENABLE QUERY OPTIMIZATION | DISABLE QUERY OPTIMIZATION] ...]

Parameters:

table-name
Any long identifier naming the table. The name must uniquely identify the table, and must not match any other table, view, alias, or synonym name existing within the current location. If qualified, the table name consists of a two-part or three-part name. If a three-part name is specified, the first part must match the value of the CURRENT SERVER special register -- that is, the current location. In any case, the AuthID qualifying the table name is the table owner.
column-name
Any long identifier naming the column. Each column in a table must have an unqualified column name, unique within the table. Dependent tables (tables containing a foreign key referencing a primary key in another table) can have up to 749 columns named, while nondependent tables (tables containing the primary key) may have 750 named columns. Column names are optional only when the select-command statement is included, in which case the column names from the source table are used.
constant
FIELDPROC clause: a parameter passed to the field procedure when it is invoked during execution of the CREATE TABLE statement. A parameter list is optional, and the number of parameters and the data type of each are determined by the field procedure. The maximum length of the parameter list is 254 bytes, including commas but excluding insignificant blanks and the delimiting parentheses.

[WITH] DEFAULT clause: names the default value for the column. The value of the constant must conform to the rules for assigning that value to the column. A default value can be specified for a column with a data type of LONG VARCHAR or LONG VARGRAPHIC and a maximum length of 254 bytes.

A character or graphic string constant must be short enough so that its UTF-8 representation requires no more than 1536. In addition, a hexadecimal graphic string constant (GX) cannot be specified.

data-type
Specifies the column data type. Data type is optional only when a select-command statement is included. FOR BIT DATA is optional; it is for use with CHAR, VARCHAR and LONG VARCHAR columns to indicate that the contents of the field values are to be treated as bit (binary) data. This is important for COBOL programs that use character and variable character fields to store integers, structures, etc. If not specified as FOR BIT DATA, the field is assumed to contain ASCII characters. Note that the FOR BIT DATA clause must precede the NULL specification for the field.

To conform with DB2 mainframe-specific operations, the XDB Server also records the FOR SBCS DATA and FOR MIXED DATA clause options in the appropriate system catalog tables.

NOT NULL is an optional instruction that prevents the column from containing null values.

NOT NULL WITH DEFAULT prevents columns from containing null values. When an attempt is made to place a NULL value in such a column, a default value is inserted. The default value is dependent on the data type as shown in the following table.

built-in-data-type
Specifies the data type of the column as one of the following built-in data types, and for character string data types, specifies the subtype. If you define the table with a LOB column (CLOB, DBCLOB, or BLOB), you must also define a ROWID column.

[WITH] DEFAULT clause: In a given column definition neither NOT NULL nor DEFAULT can be specified more than once. Both NOT NULL and DEFAULT cannot be specified. Omitting NOT NULL and DEFAULT implies that DEFAULT NULL is intended.

Data Type | Default Value
Numeric | 0
Date | current date
Time | current time
Timestamp | current timestamp
Character | Blanks
Varchar | Blanks
Graphic | Blanks
select-command
Can consist of any SELECT statement that retrieves data values from a database and inserts them into the newly created table. See CREATE With SELECT below.
column-name
Names a column on which a key is to be created. Up to 64 columns can be included in the key. If creating a PRIMARY key, a unique index must be created on the table; in this index exactly the same column names must appear, in exactly the same order as in the PRIMARY KEY constraint. The index will be designated the primary key. See PRIMARY KEY below and the CREATE GLOBAL TEMPORARY TABLE command for more information.
constraint-name
Defines a FOREIGN KEY constraint (which cannot be a unique index). If constraint-name is not specified in the command, the system generates a constraint name by taking the first eight characters of the first column name and checking for uniqueness. If not unique, the XDB Server adds a number to the first seven characters of the this first column name, and checks for uniqueness again. If necessary, additional character(s) at the end of the column name string are replaced with numbers until the name becomes unique among all constraint names on the table.

Also defines a table CHECK constraint within the CONSTRAINT...CHECK clause. The constraint-name is an SQL long identifier. A constraint-name cannot be specified more than once for the same table (see CONSTRAINT keyword).

check-condition
Provides a shorthand method of defining a check constraint that applies to a single column.

A check condition can consist of a single predicate, or two or more predicates joined by AND or OR. The first operand of each predicate must be the name of a column of the table. The second operand can be a column name or a constant. A check-condition can evaluate to unknown if a column that is an operand of the predicate is null. A check-condition that evaluates to unknown does not violate the check constraint (see CHECK clause).

For conformance with the SQL standard, if CHECK is specified in the column definition of column C, no columns other than C should be referenced in the check condition of the check constraint. The effect is the same as if the check condition were specified as a separate clause.

referenced-table
Identifies the table referenced by the referential integrity constraint (or the parent table containing the primary key referenced).

The ON DELETE or ON UPDATE (XDB mode only) clause tells the system how to handle dependent records in this table when a corresponding record in the parent table is being deleted. The RESTRICT option (default) prevents the record from being deleted from the parent table. The CASCADE option deletes or updates the dependent records from the current table, and allows the deletion or updating of the parent record. The SET NULL option causes the foreign key fields in the dependent records to be set to NULL before the parent record is deleted.

Description

XDB Server tables can be created using the CREATE TABLE command. Tables can also be created using SQLWizard. For more information on SQLWizard, see the SQLWizard User's Guide. The XDB Server supports a CREATE with SELECT command which allows a table to be created and populated in one command execution. The CREATE LIKE command allows the creation of a table using an existing table or view specification. See CREATE LIKE below.

The following example creates the table INVENT:

CREATE TABLE invent
    (item_no SMALLINT NOT NULL,
     description CHAR (12),
     model CHAR (6),
     type CHAR 12,
     weight FLOAT,
     qoh INTEGER,
     unit_cost DECIMAL(6,3),
     price MONEY)

The INVENT table will have the structure shown in the following table:

Column Name | Data Type
item_no | SMALLINT (nulls not permitted)
Description | CHAR 12
Model | CHAR 6
Type | CHAR 12
Weight | FLOAT
Qoh | INTEGER
unit_cost | DECIMAL(6,3)
Price | MONEY

Once a table has been created, data can be entered or indexes created. The column types and the number of columns can be changed using the ALTER TABLE command. The table name can be changed by the RENAME command. The table can also be altered or renamed using SQLWizard (applies to Windows environments only). (For more information on SQLWizard, see the SQLWizard User's Guide.)

With DB2 V7, XDB locations (either EBCDIC or ASCII) can now contain Unicode data. If you create a table with CCSID UNICODE, all character data in corresponding tables is stored in UTF-8 format and all graphic data is stored in UTF-16 format.

FOR subtype DATA
Specifies a subtype for a character string column, which is a column with a data type of CHAR, VARCHAR, LONG VARCHAR, or CLOB. Do not use the FOR DATA clause with columns of any other data type (including any distinct type). subtype can be one of the following:
SBCS | Column holds single-byte data.
MIXED | Column holds mixed data. Do not specify MIXED if the value of field MIXED DATA on installation panel DSNTIPF is NO.
BIT | Column holds BIT data. Do not specify BIT for a CLOB column.

If you do not specify the FOR clause, the column is defined with a default subtype. The default is SBCS when the value of field MIXED DATA on installation panel DSNTIPF is NO. The default is MIXED when the value is YES.

A security label column is always considered SBCS data, regardless of the encoding scheme of the table.

XDB Server operating environment does not support the CLOB data type at this time.

GRAPHIC (integer)
For a fixed-length graphic string of length integer, which can range from 1 to 127. If the length specification is omitted, a length of 1 character is assumed.
VARGRAPHIC (integer)
For a varying-length graphic string of maximum length integer, which must range from 1 to n/2, where n is the maximum row size minus 2 bytes. An integer longer than 127 defines a long string column.
ROWID

For a row ID type.

A table can have only one ROWID column. The values in a ROWID column are unique for every row in the table and cannot be updated. You must specify NOT NULL with ROWID.

NOT NULL

Prevents the column from containing null values.

PRIMARY KEY

Provides a shorthand method of defining a primary key composed of a single column. Thus, if PRIMARY KEY is specified in the definition of column C, the effect is the same as if the PRIMARY KEY(C) clause is specified as a separate clause.

The NOT NULL clause must be specified with this clause. Each column-name must be an unqualified name that identifies a column of the table except a LOB or ROWID column (including a distinct type that is based on a LOB or ROWID), and the same column must not be identified more than once. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 -2m, where m is the number of varying-length columns in the key.

The table is marked as unavailable until its primary index is explicitly created unless the CREATE TABLE statement is processed by the schema processor. In that case, DB2 implicitly creates an index to enforce the uniqueness of the primary key and the table definition is considered complete.

UNIQUE

Provides a shorthand method of defining a unique key composed of a single column. Thus, if UNIQUE is specified in the definition of column C, the effect is the same as if the UNIQUE(C) clause is specified as a separate clause.

The NOT NULL clause must be specified with this clause. UNIQUE cannot be specified more than once in a column definition and must not be specified if the PRIMARY KEY clause is specified in the column definition or if the definition is for a LOB column. The number of identified columns must not exceed 64. In addition, the sum of the length attributes of the columns must not be greater than 2000 -2m, where m is the number of varying-length columns in the key.

Each column-name must be an unqualified name that identifies a column of the table except a LOB column, and the same column must not be identified more than once.

DEFAULT

The default value assigned to the column in the absence of a value specified on INSERT or LOAD. Do not specify DEFAULT for a ROWID column, an identity column (a column that is defined AS IDENTITY) or a security label column (a column that is defined AS SECURITY LABEL); DB2 generates default values. If a value is not specified after DEFAULT, the default value depends on the data type of the column, as follows:

Data Type | Default Value
Numeric | 0
Fixed-length string | Blanks
Varying-length string | A string of length 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP
Distinct type | The default of the source data type

A default value other than the one that is listed above can be specified in one of the following forms, except for a LOB column. The only form that can be specified for a LOB column is DEFAULT NULL. Unlike other varying-length strings, a LOB column can only have the default value of a zero-length string as listed above or null.

GENERATED

Specifies that XDB generates values for the column. GENERATED must be specified if the column is to be considered an identity column. If the data type of the column is a ROWID (or a distinct type that is based on a ROWID), the default is GENERATED ALWAYS.

ALWAYS Indicates that XDB will always generate a value for the column when a row is inserted into the table. ALWAYS is the recommended value unless you are using data propagation.
BY DEFAULT Indicates that XDB will generate a value for the column when a row is inserted into the table unless a value is specified.

For a ROWID column, XDB uses a specified value only if it is a valid row ID value that was previously generated by XDB and the column has a unique, single-column index. Until this index is created on the ROWID column, the SQL INSERT statement and the LOAD utility cannot be used to add rows to the table. If the value of special register CURRENT RULES is 'STD' when the CREATE TABLE statement is processed, XDB implicitly creates the index on the ROWID column. The name of this index is 'I' followed by the first ten characters of the column name followed by seven randomly generated characters. If the column name is less than ten characters, XDB adds underscore characters to the end of the name until it has ten characters. The implicitly created index has the COPY NO attribute.

For an identity column, XDB inserts a specified value but does not verify that it is a unique value for the column unless the identity column has a unique, single-column index. Without a unique index, XDB can guarantee unique values only among the set of system-generated values.

BY DEFAULT is the recommended value only when you are using data propagation.

AS SECURITY LABEL

Specifies that the column will contain security label values. This also indicates that the table is defined with multilevel security with row level granularity. A table can have only one security label column. To define a table with a security label column, the primary authorization ID of the statement must have a valid security label, and the RACF SECLABEL class must be active. In addition, the following conditions are also required:

  • The data type of the column must be CHAR(8).
  • The subtype of the column must be SBCS.
  • The column must be defined with the NOT NULL and WITH DEFAULT clauses.
  • No field procedures, check constraints, or referential constraints are defined on the column.
  • An edit procedure is not defined on the table.
  • You are using z/OS Version 1 Release 5 or later.
AS IDENTITY

Specifies that the column is an identity column for the table. A table can have only one identity column. AS IDENTITY can be specified only if the data type for the column is an exact numeric type with a scale of zero (SMALLINT, INTEGER, DECIMAL with a scale of zero, or a distinct type based on one of these types).

An identity column is implicitly NOT NULL.

START WITH numeric-constant Specifies the first value for the identity column. The value can be any positive or negative value that could be assigned to the column without non-zero digits exisiting to the right of the decimal point. The default is 1.
INCREMENT BY numeric-constant Specifies the interval between consecutive values of the identity column. The value can be any positive or negative value (including 0) that does not exceed the value of a large integer constant, and could be assigned to the column without any non-zero digits existing to the right of the decimal point. The default is 1.

If this value is negative, the values for the identity column descend. If this value is 0 or positive, the values for the identity column ascend. The default is 1.

MINVALUE or NO MINVALUE

Specifies the minimum value at which a descending identity column either cycles or stops generating values or an ascending identity column cycles to after reaching the maximum value. The default is NO MINVALUE.

NO MINVALUE

Specifies that the minimum end point of the range of values for the identity column has not be set. In such a case, the default value for MINVALUE becomes one of the following:

  • For an ascending identity column, the value is the START WITH value or 1 if START WITH was not specified.
  • For a descending identity column, the value is the minimum value of the data type of the column.
MINVALUE numeric-constant

Specifies the numeric constant that is the minimum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be less than or equal to the maximum value.

MAXVALUE or NO MAXVALUE

Specifies the maximum value at which an ascending identity column either cycles or stops generating values or a descending identity column cycles to after reaching the minimum value. The default is NO MAXVALUE.

NO MAXVALUE

Specifies that the minimum end point of the range of values for the identity column has not be set. In such a case, the default value for MAXVALUE becomes one of the following:

  • For an ascending identity column, the value is the maximum value of the data type of the column.
  • For a descending identity column, the value is the START WITH value or -1 if START WITH is not specified.
MAXVALUE numeric-constant

Specifies the numeric constant that is the maximum value that is generated for this identity column. This value can be any positive or negative value that could be assigned to this column without non-zero digits existing to the right of the decimal point. The value must be greater than or equal to the minimum value.

NO CYCLE or CYCLE

Specifies whether this identity column should continue to generate values after reaching either its maximum or minimum value.

NO CYCLE

Specifies that values will not be generated for the identity column after the maximum or minimum value has been reached. This is the default.

CYCLE

Specifies that values continue to be generated for the identity column after the maximum or minimum value has been reached. If this option is used, after an ascending identity column reaches the maximum value, it generates its minimum value. After a descending identity column reaches its minimum value, it generates its maximum value. The maximum and minimum values for the identity column determine the range that is used for cycling.

When CYCLE is in effect, duplicate values can be generated by DB2 for an identity column. However, if a unique index exists on the identity column and a non-unique value is generated for it, an error occurs.

CACHE or NO CACHE

This clause has no functional equivalent in the XDB Server operating environment.

NO ORDER or ORDER

Specifies whether the identity column values must be generated in order of request. The default is NO ORDER.

NO ORDER

Specifies that the values do not need to be generated in order of request.

ORDER

Specifies that the values are generated in order of request. Specifying ORDER may disable the caching of values. ORDER applies only to a single-application process.

In a data sharing environment, if the CACHE and NO ORDER options are in effect, multiple caches can be active simultaneously, and the requests for identity values from different DB2 members may not result in the assignment of values in strict numeric order. For example, if members DB2A and DB2B are using the identity column, and DB2A gets the cache values 1 to 20 and DB2B gets the cache values 21 to 40, the actual order of values assigned would be 1,21,2 if DB2A requested a value first, then DB2B requested, and then DB2A again requested. Therefore, to guarantee that identity values are generated in strict numeric order among multiple DB2 members using the same identity column, specify the ORDER option.

PARTITION BY RANGE

Specifies the range partitioning scheme for the table (the columns used to partition the data). When this clause is specified, the table space is complete, and it is not necessary to create a partitioned index on the table. If this clause is used, the ENDING AT clause cannot be used on a subsequent CREATE INDEX statement for this table.

If this clause is specified, the IN database-name.table-space-name clause is required. This clause applies only to tables in a partitioned table space.

This clause is only implemented syntactically in the XDB Server operating environment.

partition-expression

Specifies the key data over which the range is defined to determine the target data partition of the data.

column-name

Specifies the columns of the key. Each column-name must identify a column of the table. Do not specify more than 64 columns, the same column more than once, a LOB column, a column with a distinct type that is based on a LOB data type, or a qualified column name. The sum of length attributes of the columns must not be greater than 255 - n, where n is the number of columns that can contain null values.

NULLS LAST

Specifies that null values are treated as positive infinity for purposes of comparison.

ASC

Puts the entries in ascending order by the column. ASC is the default.

DESC

Puts the entries in descending order by the column.

partition-element

Specifies ranges for a data partitioning key and the table space where rows of the table in the range will be stored.

PARTITION integer

integer is the physical number of a partition in the table space. A PARTITION clause must be specified for every partition of the table space. In this context, highest means highest in the sorting sequences of the columns. In a column defined as ascending (ASC), highest and lowest have their usual meanings. In a column defined as descending (DESC), the lowest actual value is highest in the sorting sequence.

This clause is only implemented syntactically in the XDB Server operating environment.

ENDING AT(constant, ...)

constant defines the limit key for a partition boundary. Specify at least one constant after ENDING AT in each PARTITION clause. You can use as many constants as there are columns in the key. The concatenation of all the constants is the highest value of the key for ascending and the lowest for descending. The use of constants to define key values is subject to the following rules:

  • The first constant corresponds to the first column of the key, the second constant to the second column, and so on. Each constant must conform to the rules for assigning that value to the column. A hexadecimal string constant (GX) cannot be specified.

    Using fewer constants than there are columns in the key has the same effect as using the highest or lowest values for the omitted columns, depending on whether they are ascending or descending.

  • The highest value of the key in any partition must be lower than the highest value of the key in the next partition for ascending cases.
  • The constants specified for the last partition are enforced. The value specified for the last partition is the highest value of the key that can be placed in the table. Any key values greater than the value specified for the last partition are out of range.
  • The precision and scale of a decimal constant must not be greater than the precision and scale of its corresponding column.
  • If a string constant is longer or shorter than required by the length attribute of its column, the constant is either truncated or padded on the right to the required length. If the column is ascending, the padding character is X'FF'. If the column is descending, the padding character is X'00'.
  • If a key includes a ROWID column or a column with a distinct type that is based on a ROWID data type, then 17 bytes of the constant that is specified for the corresponding ROWID column are considered.
INCLUSIVE

Specifies that the specified range values are included in the data partition.

CREATE With SELECT

The CREATE command may include an optional SELECT command (XDB mode only) that selects data from an existing table to insert into the new table. The order of the selected columns defines the column order of the new table. However, the number of columns selected does not need to match the number of columns defined for the new table. If the new table has more columns than the SELECT statement, the extra columns are assigned NULL values. If the new table has fewer columns than the SELECT command, the system uses only as many of the first columns as will fit into the new table. If no column names are given in the create command, the column names listed in the SELECT command are used to create the table.

Any search condition can be used in the SELECT statement including a join condition or a subselect. See WHERE Clause for more information on search conditions. The columns selected do not have to match the data type of the new table columns, but they must be type-compatible. The new table, for example, accepts floating point data in a column defined as an integer -- however, the fractional part of the data is truncated. See the ALTER TABLE command for a type compatibility matrix. When converting from character data to another type, if the conversion is not possible the new value will be NULL.

Three examples of CREATE with SELECT are given below:

CREATE TABLE parispno
    (pno CHAR 2, pname CHAR 6, city CHAR 6,
     weight DECIMAL(4,3))
    SELECT pno, pname, city
        FROM part
        WHERE city = "PARIS"
CREATE TABLE lowinv
    SELECT *
        FROM partsupp
        WHERE qty < 400
CREATE TABLE (a, b, c)
    SELECT A.a, B.b, C.c
        FROM A, B, C
        WHERE A.x = B.x
          AND B.x = C.x
Subselects and Locations

When populating new tables with subselects, the subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

CREATE TABLE tutorial.tutorial.sample
    SELECT * FROM tutorial.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM debloc.debbie.employee
                WHERE st = "MD";

Valid:

CREATE TABLE tutorial.tutorial.sample
    SELECT * FROM tutorial.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM tutorial.debbie.employee
                WHERE st = "MD";
CREATE LIKE

The LIKE table-name or LIKE view-name clause is used to create a new table with the same definition as an existing table or view. The columns of the table will have exactly the same names and column specifications (data type, null permission, etc.) as the source table or view. However, neither the primary nor foreign keys, nor any check option existing on the source table or view are defined for the new table. Data from the source table is NOT transferred to the new table.

An example of the CREATE TABLE...LIKE command is:

CREATE TABLE personnel LIKE employee

Creating a table like a view

If the LIKE clause is specified and the definition of the table is being based on a view, the view must not include a ROWID column or an identity column. A view column is considered to be an identity column if the corresponding column of the table or view indirectly or directly maps to the name of an identity column in a base table with these exceptions:

  • The select-list of the view definition identifies the same identity column more than once.
  • The select-list of the view definition references multiple identity columns and thus involves a join.
  • A column in the view definition includes an expression that refers to an identity column.
IN or IN DATABASE

Specifies a database-name alone (preceded by keyword IN DATABASE), or both a tablespace-name with an optional database-name qualifier (preceded by keyword IN). If a database is named, it must be described in the system catalog for the current location, and must not be the DSNDB06 catalog database.

If a table space name is not explicitly specified, a table space is created implicitly within database-name. In these cases, the XDB Server checks the privileges held by the user for either SYSADM or SYSCTRL authority for the location, DBADM, DBCTRL or DBMAINT authority for the database, or the CREATETS privilege for the database. The table space name is taken from the table name specified in the CREATE TABLE command. Except for the name, the other attributes of this table space match those that would result from a CREATE TABLESPACE statement minus all its optional clauses.

If tablespace-name is specified, this name must not reference an already existing table space that was implicitly created. If both a database and table space are specified, the table space must belong to the named database. If only a table space is named, it must belong to the default DSNDB04 database for the current location. If the table space references a stogroup, then any tables created with that table space name are stored in the path specified for the stogroup.

A subselect and an IN DATABASE clause cannot be used in the same CREATE TABLE statement. Instead, create the table in the database and then use an INSERT INTO command with a subselect to populate the table.

For example:

Invalid:

CREATE TABLE tutorial.debbie.employee
SELECT * FROM tutorial.tutorial.employee
    WHERE st = "MD"
IN DATABASE debdb;

Valid:

CREATE TABLE tutorial.debbie.employee (e_no SMALLINT NOT NULL,
    lname CHAR 10 NOT NULL,
    fname CHAR 10 NOT NULL, street CHAR 20,
    city CHAR 15, st CHAR 2, zip CHAR 5,
    dept CHAR 4, payrate MONEY, com DECIMAL(2,2))
IN DATABASE debdb;
INSERT INTO tutorial.debbie.employee
    SELECT * FROM tutorial.tutorial.employee
        WHERE st = "MD";
OBID integer

Identifies the OBID to be used for this table. An OBID is the identifier for an object's internal descriptor.

The OBID keyword option is used with ROSHARE databases, and can be viewed by querying the SYSIBM.SYSTABLES catalog table. The integer must not identify an existing or previously used OBID of the database. If you omit OBID, DB2 generates a value.

The following statement retrieves the value of OBID:

SELECT OBID
    FROM SYSIBM.SYSTABLES
    WHERE CREATOR = 'ccc' AND NAME = 'nnn';

Here, nnn is the table name and ccc is the table's creator

UNIQUE

Defines a unique key composed of the identified columns. Each column name must be an unqualified name that identifies a column of the table, and the same column must not be identified more than once. A unique key is a duplicate if it is the same as the primary key or a previously defined unique key. A unique key on a single column can be defined in a column definition. In a given column definition neither UNIQUE nor PRIMARY KEY can be specified more than once, nor can UNIQUE and PRIMARY KEY both be specified for the same column.

PRIMARY KEY

A table can have at most one constraint condition specified as a PRIMARY KEY. The purpose of the primary key is to enforce entity integrity -- that is, to uniquely identify each row of a table. Note that the columns in the primary key must be defined as NOT NULL when the columns are specified.

Note:

You must create an index for a primary key or a unique key if the CREATE TABLE statement is processed by the XDB Server. XDB Server does not implicitly create an index.

A primary key on a single column can be defined in a column definition. In a given column definition neither UNIQUE nor PRIMARY KEY can be specified more than once, nor can UNIQUE and PRIMARY KEY both be specified for the same column.

You cannot create foreign keys on tables that are in a pending state. A table is in a pending state if a primary key clause has been specified but a unique index has not been built on those columns.

For example, to define the SNO and PNO columns as the primary key of the PARTSUPP table, use the command:

CREATE TABLE partsupp(sno SMALLINT NOT NULL,
    pno SMALLINT NOT NULL,
    qty SMALLINT, PRIMARY KEY (sno, pno))

To define the SNO column as the primary key of the SUPPLIER table, use a command like:

CREATE TABLE supplier(sno CHAR 3 NOT NULL,
    sname CHAR 5, status SMALLINT,
    city CHAR 6, PRIMARY KEY (sno))
FOREIGN KEY

A FOREIGN KEY constraint is used to enforce referential integrity -- the relationship between a referencing (or dependent) table and a referenced (or parent) table. The referential integrity rule requires that, for any value in the dependent columns, there must exist a row in the parent table such that the value of the dependent columns equals the value of the corresponding columns in the primary key of the parent table. This is enforced as follows:

  1. When an update or insert is performed on the dependent table, the set of values placed in the referencing columns must match a set of values that exists in the parent table.
  2. If an attempt is made to delete or update a row of the parent table that contains values matching those in a dependent table, the system uses the ON DELETE or ON UPDATE (XDB Server extension only, not available on DB2 or other modes) clause to determine the delete rule to use. The options are:
    • RESTRICT

      Prevents record deletion from the parent table if dependents exist. RESTRICT is the default value.

    • NO ACTION

      Prevents records from being deleted from the parent table (as in the RESTRICT option), except the referential constraint is enforced at the end of the statement. This is the default setting if the CURRENT RULES special register is STD (SQL standard).

    • CASCADE

      Deletes the dependent records from the current table and then deletes the parent records.

    • SET NULL

      Causes each nullable column in the foreign key of each dependent record to be set to NULL before the corresponding parent records are deleted.

Note that whenever a cyclical situation exists (for example a foreign key of table B references the primary key of table A, and a foreign key of table A references a primary key of table B, the delete rules should be the same for all foreign keys, and the SET NULL option should not be used.

In order to create a referential integrity constraint you must create a FOREIGN KEY constraint on the referencing table. The FOREIGN KEY constraint must reference the existing PRIMARY KEY of the referenced table.

Foreign key columns do not need to have the same names as the corresponding columns in the PRIMARY KEY of the referenced table, but the columns must match in type, number and order.

Each column-name must be an unqualified name that identifies a column of the table except a LOB, ROWID, or security label column, and the same column must not be identified more than once. The number of identified columns must not exceed 64, and the sum of their length attributes must not exceed 255 minus the number of columns that allow null values. The referential constraint is a duplicate if the FOREIGN KEY and parent table are the same as the FOREIGN KEY and parent table of a previously defined referential constraint. The specification of a duplicate referential constraint is ignored with a warning.

A constraint name is used to uniquely identify a FOREIGN KEY constraint, and is stored in the appropriate system catalog table. The constraint name should be a short identifier (up to eight characters) that is unique among all constraints built on the table. Since this constraint name is also used in error messages to indicate constraint violation, it is important to use a meaningful name.

Although it is good practice to provide a meaningful constraint name, if one is not supplied, the system automatically generates one by taking the first eight characters of the first column (appearing in the column list) and then checking for uniqueness. If this name is not unique, the XDB Server takes the first seven characters of the first column name plus a number. If necessary one letter at a time is removed from the end of this constraint name and replaced with a number, until the constraint name becomes unique among all constraint names existing for the table.

Indexes on Foreign Keys

The XDB Server automatically builds an index on your FOREIGN KEY columns. The system will generate the name of the index and store it in the REFKEYNAME column of the SYSIBM.SYSREF catalog table. DB2, in contrast, does not automatically create an index on FOREIGN KEY columns. If you are using your DB2 data definition language (DDL) script, and this script contains CREATE INDEX commands on FOREIGN KEY columns, you can end up with redundant indexes. For optimal performance, you should modify your DB2 DDL script to remove any CREATE INDEX commands on FOREIGN KEY columns.

REFERENCES

The references portion of the referential-constraint clause is a separate clause. A single column can be identified as a foreign key of a referential constraint by using the references-clause in a column definition. Define a key that consists of more than one column by listing the column names to which the REFERENCES privilege applies.

Do not specify references-clause in the definition of a LOB, ROWID, or security label column; a LOB, ROWID, or security label column cannot be a foreign key.

A foreign key can reference a unique key or a primary key. When a foreign key refers to a nonprimary unique key, you must specify the columns of the key. If the foreign key includes a column defined as a distinct type, the corresponding column of the nominated parent key must be the same distinct type.

ENFORCED or NOT ENFORCED

Indicates whether or not the referential constraint is enforced by DB2 during normal operations, such as insert, update, or delete.

ENFORCED

Specifies that the referential constraint is enforced by the DB2 during normal operations (such as insert, update, or delete) and that it is guaranteed to be correct. This is the default.

NOT ENFORCED

Specifies that the referential constraint is not enforced by DB2 during normal operations, such as insert, update, or delete. This option should only be used when the data that is stored in the table is verified to conform to the constraint by some other method than relying on the database manager.

ENABLE QUERY OPTIMIZATION

Specifies that the constraint can be used for query optimization. DB2 uses the information in query optimization using materialized query tables with the assumption that the constraint is correct. This is the default.

LIKE table-name or view-name

Specifies that the columns of the table have exactly the same name and description as the columns of the identified table or view. The name specified after LIKE must identify a table or view that exists at the current server, and the privilege set must implicitly or explicitly include the SELECT privilege on the identified table or view. An identified view must not include a column that is an explicitly defined ROWID column (including a distinct type that is based on a ROWID) or an identity column.

The use of LIKE is an implicit definition of n columns, where n is the number of columns in the identified table or view. The implicit definition includes all attributes of the n columns as they are described in SYSCOLUMNS with these exceptions:

  • When a table is identified in the LIKE clause and a column in the table has a field procedure, the corresponding column of the new table has the same field procedure and the field description. However, the field procedure is not invoked during the execution of the CREATE TABLE statement.
  • When a table is identified in the LIKE clause and a column in the table an identity column, the corresponding column of the new table inherits only the data type of the identity column; none of the identity attributes of the column are inherited unless the INCLUDING IDENTITY clause is specified.
  • When a table is identified in the LIKE clause and a column in the table is a security label column, the corresponding column of the new table inherits only the data type of the security label column; none of the security label attributes of the column are inherited.
  • When a table is identified in the LIKE clause and the table contains a ROWID column (explicitly-defined, hidden, or both), the corresponding columns of the new table inherits the ROWID columns.
  • When a view is identified in the LIKE clause, the default value that is associated with the corresponding column of the new table depends on the column of the underlying base table for the view. If the column of the base table does not have a default, the new column does not have a default. If the column of the base table has a default, the default of the new column is:
    • Null if the column of the underlying base table allows nulls.
    • The default for the data type of the underlying base table if the underlying base table does not allow nulls.
  • When a table that uses table-controlled partitioning is identified in the LIKE clause, the new table does not inherit that table's partitioning scheme. If desired, these partition boundaries can be added by specifying ALTER TABLE with the ADD PARTITION BY RANGE clause.
  • The CCSID of the column is determined by the implicit or explicit CCSID clause.

The above defaults are chosen regardless of the current default of the base table column. Also, no column in the new table has a field procedure because the catalog descriptions of view columns do not include field procedures.

The implicit definition does not include any other attributes of the identified table or view. For example, the new table does not have a primary key or foreign key. The table is created in the table space implicitly or explicitly specified by the IN clause, and the table has any other optional clause only if the optional clause is specified.

EXCLUDING IDENTITY COLUMN ATTRIBUTES or INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies whether identity column attributes are inherited from the definition of the source of the result table.

EXCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that identity column attributes are not inherited from the source result table definition. This is the default.

INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that, if available, identity column attributes (such as START WITH, INCREMENT BY, and CACHE values) are inherited from the definition of the source table. These attributes can be inherited if the element of the corresponding column in the table, view, or fullselect is the name of a column of a table or the name of a column of a view that directly or indirectly maps to the column name of a base table with the identity attribute. In other cases, the columns of the new temporary table do not inherit the identity attributes. The columns of the new table do not inherit the identity attributes in the following cases:

  • The select list of the fullselect includes multiple instances of an identity column name (that is, selecting the same column more than once).
  • The select list of the fullselect includes multiple identity columns (that is, it involves a join).
  • The identity column is included in an expression in the select list.
  • The fullselect includes a set operation (union).
Using an identity column

When a table has an identity column, DB2 can automatically generate unique, sequential numeric values for the column as rows are inserted into the table. Thus, identity columns are ideal for primary keys. Identity columns and ROWID columns are similar in that both types of columns contain values that DB2 generates and guarantees as unique. ROWID columns are used in large object (LOB) table spaces and can be useful in direct-row access. ROWID columns contain values of the ROWID data type, which returns a 40-byte VARCHAR value that is not regularly ascending or descending. ROWID data values are therefore not well suited to many application uses, such as generating employee numbers or product numbers. For data that is not LOB data and that does not require direct-row access, identity columns are usually a better approach, because identity columns contain existing numeric data types and can be used in a wide variety of uses for which ROWID values would not be suitable.

When a table is recovered to a point-in-time, it is possible that a large gap in the sequence of generated values for the identity column might result. For example, assume a table has an identity column that has an incremental value of 1 and that the last generated value at time T1 was 100 and DB2 subsequently generates values up to 1000. Now, assume that the table space is recovered back to time T1. The generated value of the identity column for the next row that is inserted after the recovery completes will be 1001, leaving a gap from 100 to 1001 in the values of the identity column.

Sometimes you may need to change the attributes of an identity column, For example, if you had defined an identity column with a data type of SMALLINT and then run out of assignable values, you need to redefine the column as INTEGER. To change the attributes of an identity column, you unload the data from the table, drop the table, recreate the table, and reload athe data.

But when you recreate the table, you must specify GENERATED BY DEFAULT and a new START WITH value for the identify column.Using GENERATED BY DEFAULT allows LOAD to reload the previously existing identity column values. You cannot use GENERATED ALWAYS in this case, but not using it is not a problem since DB2 always generates a value if a column value is not provided during insertion of an identity column defined as GENERATED BY DEFAULT. The new START WITH value should be the next value in the sequence from where the original sequence of values left off; this value is the next value that DB2 would generate first.

WITH RESTRICT ON DROP

Indicates that the table cannot be dropped. Also, the database and table space that contain the table cannot be dropped.

If a table space is named, it must not be one that was created implicitly, be a partitioned table space that already contains a table, or be a LOB table space. If you name a partitioned table space, you cannot load or use the table until its partitioned index is created.

CCSID

The CCSID clause is only syntactically supported for EBCDIC and ASCII. This is because the definition of the XDB location itself defines how character data is stored.

If you specify UNICODE, your character and graphic data is stored as UNICODE within the table.

VOLATILE or NOT VOLATILE

Specifies how DB2 is to choose access to the table.

VOLATILE

Specifies that index access should be used on this table whenever possible for SQL operations. However, be aware that list prefetch and certain other optimization techniques are disabled when VOLATILE is used.

One instance in which use of VOLATILE may be desired is for a table whose size can vary greatly. If statistics are taken when the table is empty or has only a few rows, those statistics might not be appropriate when the table has many rows. Another instance in which use of VOLATILE may be desired is for a table that contains groups of rows, as defined by the primary key on the table. All but the last column of the primary key of such a table indicate the group to which a given row belongs. The last column of the primary key is the sequence number indicating the order in which the rows are to be read from the group. VOLATILE maximizes concurrency of operations on rows within each group, since rows are usually accessed in the same order for each operation.

NOT VOLATILE

Specifies that SQL access to this table should be based on the current statistics. NOT VOLATILE is the default.

CARDINALITY

An optional keyword that currently has no effect, but that is provided for DB2 family compatibility.

materialized-query-definition

Specifies that the column definitions are based on the result of a fullselect. If materialized-query-table-options are specified, the table is a materialized query table and the REFRESH TABLE statement can be used to populate the table with the results of the fullselect.

column-name

Names the columns in the table. If a list of column names is specified, it must consist of as many names as there are columns in the result table of the fullselect. Each column-name must be unique and unqualified. If a list of column names is not specified, the columns of the table inherit the names of the columns of the result table of the fullselect.

A list of column names must be specified if the result table of the fullselect has duplicate column names or an unnamed column. An unnamed column is a column derived from a constant, function, expression, or set operation that is not named using the AS clause of the select list.

AS(fullselect)

Specifies that the table definition is based on the column definitions from the result of a query expression. The use of AS (fullselect) is an implicit definition of n columns for the table, where n is the number of columns that would result from the fullselect. The columns of the new table are defined by the columns that result from the fullselect. Every select list element must have a unique name. The AS clause can be used in the select-clause to provide unique names. The implicit definition includes the column name, data type, and nullability characteristic of each of the result columns of fullselect.

If the fullselect is specified, for the statement that is embedded or prepared dynamically, the owner of the table being created must have the SELECT privilege on the tables or views referenced in the fullselect, or the privilege set must include SYSADM or DBADM authority for the database in which the tables of the fullselect reside. Having SELECT privilege means that the owner has at least one of the following authorizations:

  • Ownership of the tables or views referenced in the fullselect
  • The SELECT privilege on the tables and views referenced in the fullselect
  • SYSADM authority
  • DBADM authority for the database in which the tables of the fullselect reside

The rules for establishing the qualifiers for names used in the fullselect are the same as the rules used to establish the qualifiers for table-name. The fullselect must not refer to host variables or include parameter markers.

When WITH NO DATA is specified, the fullselect must not:

  • Reference a remote object.
  • Result in a column having a ROWID data type or a distinct type based on ROWID.
  • Result in a column having a BLOB, CLOB, or DBCLOB data type or a distinct type based on these data types.
  • Contain PREVIOUS VALUE or a NEXT VALUE expression.
  • Include an INSERT statement in the FROM clause. When a materialized query table is defined, the column attributes, such as DEFAULT and IDENTITY, are not inherited from the fullselect.

When DISABLE QUERY OPTIMIZATION is specified, the following additional restrictions apply:

  • The fullselect cannot contain a reference to a created global temporary table or a declared global temporary table.
  • The fullselect cannot reference another materialized query table.

When a materialized query table is defined with ENABLE QUERY OPTIMIZATION specified, the following additional restrictions apply:

  • The fullselect must be a subselect.
  • The subselect cannot include a function that is nondeterministic or has external actions. For example, a user-defined function that is defined with either EXTERNAL ACTION or NOT DETERMINISTIC or the RAND built-in function cannot be referenced.
  • The subselect cannot contain any predicates that include subqueries.
  • The subselect cannot contain:
    • A nested table expression or view that requires temporary materialization
    • A join using the INNER JOIN syntax
    • An outer join
    • A special register
    • A scalar fullselect
    • A row expression predicate
    • Sideway references
  • The outermost SELECT list of the subselect must not reference data that is encoded with different CCSID sets.
  • If the subselect references a view, the fullselect in the view definition must satisfy the preceding restrictions.

When fullselect does not satisfy the restrictions, an error occurs.

WITH NO DATA

Specifies that the query is used only to define the attributes of the new a table. The table is not populated using the results of the query and the REFRESH TABLE statement cannot be used. When the WITH NO DATA clause is specified, the table is not considered a materialized query table.

The columns of the table are defined based on the definitions of the columns that result from the fullselect.

copy-options

Specifies whether identity column attributes and column defaults are inherited from the definition of the source of the result table.

EXCLUDING IDENTITY COLUMN ATTRIBUTES or INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies whether identity column attributes are inherited.

EXCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that identity column attributes are not inherited from the definition of the source of the result table. This is the default.

INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that, if available, identity column attributes (such as START WITH, INCREMENT BY, and CACHE values) are inherited from the definition of the source table. These attributes can be inherited if the element of the corresponding column in the table, view, or fullselect is the name of a column of a table or the name of a column of a view that directly or indirectly maps to the column name of a base table with the identity attribute. In other cases, the columns of the new temporary table do not inherit the identity attributes. The columns of the new table do not inherit the identity attributes in the following cases:

  • The select list of the fullselect includes multiple instances of an identity column name (that is, selecting the same column more than once).
  • The select list of the fullselect includes multiple identity columns (that is, it involves a join).
  • The identity column is included in an expression in the select list.
  • The fullselect includes a set operation (union).
EXCLUDING COLUMN DEFAULTS, INCLUDING COLUMN DEFAULTS, or USING TYPE DEFAULTS

Specifies whether column defaults are inherited.

EXCLUDING COLUMN DEFAULTS

Specifies that the column defaults are not inherited from the definition of the source table. The default values of the column of the new table are either null or there are no default values. If the column can be null, the default is the null value. If the column cannot be null, there is no default value, and an error occurs if a value is not provided for a column on INSERT for the new table.

INCLUDING COLUMN DEFAULTS

Specifies that column defaults for each updatable column of the definition of the source table are inherited. Columns that are not updatable do not have a default defined in the corresponding column of the created table.

USING TYPE DEFAULTS

Specifies that the default values for the table depend on data type of the columns that result from fullselect, as follows:

Data type | Default value
Numeric | 0
Fixed-length string | Blanks
Varying-length string | A string length of 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP
refreshable-table-options

Specifies the options for a refreshable materialized query table.

DATA INITIALLY DEFERRED

Specifies that the data is not inserted into the materialized query table when it is created. Use the REFRESH TABLE statement to populate the materialized query table, or use the INSERT statement to insert data into a user-maintained materialized query table.

REFRESH DEFERRED

Specifies that the data in the table can be refreshed at any time using the REFRESH TABLE statement. The data in the table only reflects the result of the query as a snapshot at the time when the REFRESH TABLE statement is processed or when it was last updated for a user-maintained materialized query table.

MAINTAINED BY SYSTEM or MAINTAINED BY USER

Specifies how the data in the materialized query table is maintained.

MAINTAINED BY SYSTEM

Specifies that the materialized query table is maintained by the system. Only the REFRESH statement is allowed on the table. This is the default.

MAINTAINED BY USER

Specifies that the materialized query table is maintained by the user, who can use the LOAD utility or the INSERT, DELETE, UPDATE, SELECT FOR UPDATE, or REFRESH TABLE statements on the table.

ENABLE QUERY OPTIMIZATION or DISABLE QUERY OPTIMIZATION

Specifies whether this materialized query table can be used for optimization.

ENABLE QUERY OPTIMIZATION

Specifies that the materialized query table can be used for query optimization. If the fullselect specified does not satisfy the restrictions for query optimization, an error occurs. This is the default.

DISABLE QUERY OPTIMIZATION

Specifies that the materialized query table cannot be used for query optimization. The table can still be queried directly.

CONSTRAINT

Names a table check constraint. If a constraint-name is not specified, a unique constraint name is derived from the name of the first column in the check-condition specified in the definition of the table check constraint.

CHECK

Table check constraints can be defined on individual columns within the CREATE TABLE command. The check constraint is the check condition that defines the values that designated columns of the table can contain, with the following restrictions:

  • It can refer only to columns of table table-name; however, the columns cannot be LOB or ROWID columns.
  • It can be up to 3800 bytes long, not including redundant blanks.

It must not contain any of the following:

  • Subselects
  • Built-in or user-defined functions
  • Cast functions other than those created when the distinct type was created
  • Host variables
  • Parameter markers
  • Special registers
  • Columns that include a field procedure
  • CASE Expressions
  • Quantified predicates
  • EXISTS predicates
  • Row expressions
  • DISTINCT predicates
  • GX literals (hexadecimal graphic string constants)

For example, the CREATE TABLE command below builds the EMPLOYEE table with the following constraints:

  • Employee names must be a value other than NULL (this constraint is equivalent to specifying NOT NULL).
  • The Department number must be 1050.
  • The commission rate must be less than or equal to six percent.
CREATE TABLE EMPLOYEE
(
e_no         SMALLINT
lname        CHAR 10              CHECK (lname IS NOT NULL),
fname        CHAR 10              CHECK (fname IS NOT NULL),
street       CHAR 20,
city         CHAR 15,
st           CHAR 2,
zip          CHAR 5,
dept         CHAR 4               CHECK (dept='1050'),
payrate      MONEY,
com          DECIMAL(2,2),
CONSTRAINT   com CHECK (com <= 06)
)

A table check constraint is not enforced on the default value of a column when the constraint is defined. A table check constraint is enforced on the default value of a column when rows are inserted or updated.

The syntax of a table check constraint is checked when the constraint is defined but the meaning is not checked. A table check constraint is not checked for consistency with other types of constraints.

Check Constraint Storage

Table check information is stored in two new catalog tables:

  • SYSIBM.SYSCHECKS

    Contains one row for each table check constraint defined on a table.

  • SYSIBM.SYSCHECKDEP

    Contains a row for each reference to a column in a table check constraint.

Enforcing Check Constraints

After table check constraints are defined on a table, any change must satisfy those constraints if it is made by an INSERT or UPDATE statement. A row satisfies a check constraint if its condition evaluates either to true or to unknown. A condition can evaluate to unknown for a row if one of the columns named contains the null value for that row. For INSERT or UPDATE statements, table check constraints are enforced on views and their underlying tables.

CURRENT RULES Special Register

For populated tables, the enforcement of a table check constraint is determined by the value, STD or DB2, of the CURRENT RULES special register.

  • If the value is STD, a check constraint is enforced immediately when it is defined. If a row does not conform, the table check constraint is not added to the table and an error occurs.
  • If the value is DB2, the check constraint is added to the table description but its enforcement is deferred. Because there might be rows in the table that violate the check constraint, the table is placed in check pending status.
DEFAULT

You can define a table column that has a default value other than null. When a row is inserted and no value is specified for the column, the default you defined is assigned to the column.

The default value depends on the data type of the column. The DEFAULT clause allows you to specify a default value in one of the following forms:

  • A constant
  • The execution time value of the USER special register
  • The SQL authorization ID (SQLID) of the process
  • The null value
NOT NULL clause

In a given column definition neither NOT NULL nor DEFAULT can be specified more than once. Both NOT NULL and DEFAULT cannot be specified. Omitting NOT NULL and DEFAULT implies that DEFAULT NULL is intended.

For example, if you want to record the identity of anyone inserting rows into a table, define the table with two additional columns:

PRIMARY_ID | CHAR(8) | WITH DEFAULT USER,
SQL_ID | CHAR(8) | WITH DEFAULT CURRENT SQLID,

You can allow updates and inserts to the table only through a view that omits those columns. Then, the primary authorization ID and the SQLID of the process are added by default.

Examples

Constraint Examples

The following shows how referential integrity can be used to enforce common business rules by defining relationships between the CUSTOMER, ORDERS, PRODUCTS, ITEMS, and EMPLOYEE tables in the TUTORIAL location.

All of the tables named already exist in the TUTORIAL location. However, if the tables did not already exist (or if you create them in another location), you could specify the referential integrity constraints at the same time you created the table.

The order in which the commands are executed is important. You cannot create a table that references another table until the referenced table is created. For example, the CUSTOMER table must be created before the ORDERS table.

Business Rule 1
An order can be placed for a customer only if complete customer information is available.

Database Relationships

Before inserting or updating into the ORDERS table, check for matching C_NO values in the CUSTOMER table. Do not delete CUSTOMER table record if orders for customer exist in the ORDERS table.
Primary key: customer(c_no)
Foreign key: orders(o_no)
Delete rule: RESTRICT
Business Rule 2
Orders must be taken by an employee of the company. If a salesperson for an order is unknown, the order is treated as a house order.

Database Relationships

Before updating or inserting into the ORDERS table, check whether S_NO value has matching E_NO in the EMPLOYEE table. Before deleting EMPLOYEE table records, set S_NO of corresponding ORDERS table records to null.
Primary key: employee(e_no)
Foreign key: orders(s_no)
Delete rule: SET NULL
Business Rule 3
A request for an item must always be associated with a specific order.

Database Relationships

Before inserting or updating the ITEMS table, check whether O_NO columns have matching O_NO values in the ORDERS table. If ORDERS record is deleted, delete matching ITEMS table records.
Primary key: orders(o_no)
Foreign key: items(o_no)
Delete rule: CASCADE
Business Rule 4
Only items that are carried can be requested on an order.

Database Relationships

Before inserting or updating records in ITEMS, make sure P_NO matches a P_NO in the PRODUCTS table. Prevent deletion of a PRODUCTS table record if dependent ITEMS table records exist.
Primary key: products(p_no)
Foreign key: items(p_no)
Delete rule: RESTRICT
Batch SQL Example
As presented, these commands could be run through interactive or batch SQL (with SQLWizard).
CREATE TABLE customer (c_no SMALLINT NOT NULL,
    company CHAR(25), address CHAR(20), city CHAR(15),
    state CHAR(2), zip CHAR(5), phone CHAR(14),
    balance MONEY,
PRIMARY KEY (c_no));
CREATE UNIQUE INDEX custpkey ON customer(c_no)
CREATE TABLE employee (e_no SMALLINT NOT NULL,
    lname CHAR(10), fname CHAR(10), street CHAR(20),
    city CHAR(15), st CHAR(2), zip CHAR(5), dept CHAR(4),
    payrate MONEY, com DECIMAL(2,2),PRIMARY KEY (e_no));
CREATE UNIQUE INDEX emppkey ON employee(e_no)
CREATE TABLE products (p_no SMALLINT NOT NULL,
    description CHAR(18), price MONEY,PRIMARY KEY (p_no));
CREATE UNIQUE INDEX prodpkey ON products(p_no)
CREATE TABLE orders (o_no SMALLINT NOT NULL,
    c_no SMALLINT, o_date DATE, s_no SMALLINT,
    PRIMARY KEY (o_no),
    FOREIGN KEY bad_cust (c_no)
        REFERENCES customer ON DELETE RESTRICT,
    FOREIGN KEY bad_emp (s_no)
        REFERENCES employee ON DELETE SET NULL);
CREATE UNIQUE INDEX ordpkey ON orders(o_no)
CREATE TABLE items (o_no SMALLINT, p_no SMALLINT,
    quantity SMALLINT, price MONEY,
    FOREIGN KEY bad_ord(o_no)
        REFERENCES orders ON DELETE CASCADE,
    FOREIGN KEY bad_prod(p_no)
        REFERENCES products ON DELETE CASCADE);

If the tables already exist you can specify the referential constraints using the ALTER TABLE command. This simply requires that you append the appropriate PRIMARY KEY and FOREIGN KEY clauses onto an ALTER TABLE table-name clause. The CREATE INDEX commands would remain the same, but should be issued before the ALTER TABLE ... PRIMARY KEY commands.

Examining the System Catalog

Creating, dropping or altering a table causes the system to automatically update the sysibm.systables and sysibm.syscolumns tables. You can query the system catalog tables for table, view, column and index information. The query results can be formatted into your own reports. See XDB Server System Tables for a description of the system catalog tables.

Optionally, you can use SQLWizard to examine table definitions interactively. In addition, the Catalog Browser function of SQLWizard lists table, view and index definitions.

If a column is indexed, the name(s) of the index or indexes are listed after the column name, separated by a slash (/). Index type indicator codes (see the following table) appear in parentheses after the index name.

Next, the data type of the column is listed. The NOT NULL or NOT NULL WITH DEFAULT clauses specifies the null permission of the column. If omitted, nulls are permitted in the column.
Indicator | Meaning
no letter | Regular index (duplicate values permitted)
p | Primary key
c | Candidate (Unique) key
f | Foreign key
u | Unique index
no number | Single column index
# Compound index; # is sequence number indicating order of column in a compound index
Parent topic: SQL Statements


CREATE TABLESPACE

This statement defines a table space in the current location. A table space in the XDB Server system architecture is logically compatible with DB2 table spaces. However, an XDB Server table space does not physically store XDB Server table (.TAB) files. This XDB Server interpretation of table spaces differs from a DB2 subsystem, where a table space can physically store multiple tables. Refer to the appropriate DB2 documentation for details on the mainframe implementation of table spaces.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

To execute the CREATE TABLESPACE command, users must possess either DBADM, DBCTRL or DBMAINT authority for the database, overall SYSADM or SYSCTRL authority for the location, or the CREATETS privilege for the database.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

CREATE [LARGE | LOB] TABLESPACE tablespace-name
    [IN {DSNDB04 | database-name}]
    [using-block]
    [free-block]
    [GBPCACHE {CHANGED | ALL}]
    [trackmod-block]
    [LOG {YES | NO}]
    [DEFINE {YES | NO}]
    [DSSIZE integer G]
    [{NUMPARTS integer]
    [(PART integer {using-block | free-block | gbpcache-block | trackmod-block | COMPRESS {YES | NO})]
    [COMPRESS {NO | YES}] [,...])]|
    SEGSIZE integer}]
    [BUFFERPOOL bpname]
    [CLOSE {YES | NO}]
    [DSETPASS password]
    [COMPRESS {NO | YES}]
    [LOCKSIZE {ANY | TABLESPACE | TABLE | LOB | {PAGE | ROW}
    [LOCKMAX {0 | integer | SYSTEM}]}]
    [CCSID {ASCII | EBCDIC | UNICODE}]
    [LOCKPART {NO | YES}]
    [MAXROWS integer]

using-block:

USING {VCAT catalog-name
        | STOGROUP stogroup-name
            [PRIQTY {3 | integer}]
             [SECQTY {3 | integer}]
             [ERASE {NO | YES}]}

free-block:

[FREEPAGE {0 | integer}]
[PCTFREE {5 | integer}]gbpcache-block:[GBPCACHE {CHANGED | ALL | SYSTEM | NONE}]

trackmod-block:

[TRACKMOD {YES | NO}]

Parameters:

tablespace-name | Identifies a unique table space name under the current location. The table space can be explicitly qualified with a database name by using the IN database-name clause.but must not identify a table space, index space, or LOB table space that exists at the current server. If a database is not specified, the table space will be associated with the dsndb04 default database for the location.
database-name | Identifies a unique database name (under the current location) in which the table space is created. The system catalog database (dsndb06) must not be specified for any type of table space and a work file database must not be specified for a LOB table space. The default database is the DSNDB04 database for the current location.
bpname | A name that identifies a bufferpool. The 4K bufferpools are named BP0, BP1, BP2...BP49. The 32K bufferpools are named BP32K, BP32K1, BP32K2...BP32K9.

Description

In DB2, when you create tables in a table space, all of the tables are physically stored in the same DASD volume (assuming no storage groups). Both logically and physically, each table is in the same table space. On an XDB Server, you can create a table space and have several different tables logically associated with that table space. Physically, however, the tables are stored in their own .TAB files.

All mainframe-specific option clauses of the CREATE TABLESPACE command are recorded in the XDB Server system catalog. The XDB Server also checks the syntax for each option. The XDB Server system architecture does not physically support many of these clauses. Refer to appropriate DB2 documentation for complete descriptions of these mainframe-specific options.

With DB2 V7, XDB locations (either EBCDIC or ASCII) can now contain Unicode data. If you create a table space with CCSID UNICODE, all character data in corresponding tables is stored in UTF-8 format and all graphic data is stored in UTF-16 format.

LARGE

Identifies that each partition of a partitioned table space has a maximum partition size of 4 GB, which enables the table space to contain more than 64 GB of data. The preferred method to specify a maximum partition size of 4 GB and larger is the DSSIZE clause. The LARGE clause is for compatibility of releases of DB2 for OS/390 prior to Version 6. Do not specify LARGE if LOB or DSSIZE is specified.

LOB

Identifies the table space as LOB table space. A LOB table space is used to hold LOB values.

The LOB table space must be in the same database as its associated base table space.

PRIQTY integer

Specifies the minimum primary space allocation for a DB2-managed data set. The primary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

If PRIQTY integer is specified:

  • For 4KB page sizes, if integer is less than 12, n is 12.
  • For 8KB page sizes, if integer is less than 24, n is 24.
  • For 16KB page sizes, if integer is less than 48, n is 48.
  • For 32KB page sizes, if integer is less than 96, n is 96.
  • For any page size, if integer is greater than 4194304, n is 4194304.
  • If PRIQTY is omitted, n is 12, 24, 48, or 96 for 4KB, 8KB, 16KB, and 32KB page sizes, respectively.

For LOB table spaces, the exceptions are:

If PRIQTY integer is specified:

  • For 4KB page sizes, if integer is less than 200, n is 200.
  • For 8KB page sizes, if integer is less than 400, n is 400.
  • For 16KB page sizes, if integer is less than 800, n is 800.
  • For 32KB page sizes, if integer is less than 1600, n is 1600.
  • For any page size, if integer is greater than 4194304, n is 4194304.
  • If PRIQTY is omitted, n is 200, 400, 800, or 1600 for 4KB, 8KB, 16KB, and 32KB page sizes, respectively.

If you do not specify PRIQTY or specify PRIQTY -1, DB2 uses a default value for the primary space allocation.

DB2 specifies the primary space allocation to access method services using the smallest multiple of pKB not less than n, where p is the page size of the table space. The allocated space can be greater than the amount of space requested by DB2.

For example, it could be the smallest number of tracks that will accommodate the request. The amount of storage space requested must be available on some volume in the storage group based on VSAM space allocation restrictions. Otherwise, the primary space allocation will fail. To more closely estimate the actual amount of storage, see the description of the DEFINE CLUSTER command in DFSMS/MVS: Access Method Services for the Integrated Catalog.

Executing this statement causes only one data set to be created. However, you might have more data than this one data set can hold. DB2 automatically defines more data sets when they are needed. Regardless of the value in PRIQTY, when a data set reaches its maximum size, DB2 creates a new one. To avoid wasting space, use the following formula to make sure that PRIQTY and its associated secondary extent values do not exceed the maximum size of the data set:

PRIQTY + (number of extents * SECQTY) <= DSSIZE (implicit or explicit)

This clause is only implemented syntactically in the XDB Server operating environment.

SECQTY integer

Specifies the minimum secondary space allocation for a DB2-managed data set. If you do not specify SECQTY DB2 uses a formula to determine a value.

If you specify SECQTY and do not specify a value of -1, DB2 specifies the secondary space allocation to access method services using the smallest multiple of p KB not less than n, where p is the page size of the table space. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the request.

The secondary space allocation is at least n kilobytes, where n is the value of integer with the following exceptions:

  • If SECQTY integer is specified and integer is greater than 4194304, n is 4194304. A value of 0 for integer indicates that no data set can be extended.
  • If SECQTY and PRIQTY are omitted:
    • For 4KB page sizes, n is 12.
    • For 8KB page sizes, n is 24.
    • For 16KB page sizes, n is 48.
    • For 32KB page sizes, n is 96.
  • If SECQTY is omitted and PRIQTY is specified, n is either 10% of PRIQTY or 3 times the page size of the table space, whichever is larger.

For LOB table spaces the exceptions are:

  • If SECQTY integer is specified:
    • For 4KB page sizes, if integer is greater than 0 and less than 200, n is 200.
    • For 8KB page sizes, if integer is greater than 0 and less than 400, n is 400.
    • For 16KB page sizes, if integer is greater than 0 and less than 800, n is 800.
    • For 32KB page sizes, if integer is greater than 0 and less than 1600, n is 1600.
    • For any page size, if integer is greater than 4194304, n is 4194304.
  • If SECQTY is omitted, n is either 10% of PRIQTY or 50 times the page size of the table space, whichever is larger.

DB2 specifies the secondary space allocation to access method services using the smallest multiple of pKB not less than n, where p is the page size of the table space. The allocated space can be greater than the amount of space requested by DB2. For example, it could be the smallest number of tracks that will accommodate the request.

This clause is only implemented syntactically in the XDB Server operating environment.

PCTFREE integer

Indicates what percentage of each page to leave as free space when the table is loaded or reorganized. integer can range from 0 to 99. The first record on each page is loaded without restriction. When additional records are loaded, at least integer percent of free space is left on each page.

The default is PCTFREE 5. Do not specify PCTFREE for a LOB table space, or a table space in a work file database or a TEMP database.

This clause is only implemented syntactically in the XDB Server operating environment.

TRACKMOD

Specifies whether DB2 tracks modified pages in the space map pages of the table space or partition. Do not specify TRACKMOD for a LOB table space. For a table space in a TEMP database, DB2 uses TRACKMOD NO regardless of the value specified.

YES DB2 tracks changed pages in the space map pages to improve the performance of incremental image copy. YES is the default unless the table space is in a TEMP database.
NO DB2 does not track changed pages in the space map pages. It uses the LRSN value in each page to determine whether a page has been changed.

If the table space is partitioned, the value of TRACKMOD for a particular partition is given by the first of these choices that applies:

  1. The value of TRACKMOD given in the PART clause for that partition.
  2. The value given in a trackmod-block that is not in any PART clause.

The default value YES.

This clause is only implemented syntactically in the XDB Server operating environment.

LOG

Specifies whether changes to a LOB column in the table space are to be written to the log. You can use the LOG clause only for a LOB table space.

YES Indicates that changes to a LOB column are to be written to the log. You cannot use YES if the auxiliary table in the table space stores a LOB column that is greater than 1 gigabyte in length.

YES is the default.

NO Indicates that changes to a LOB column are not to be written to the log.

LOG NO has no effect on a commit or rollback operation; the consistency of the database is maintained regardless of whether the LOB value is logged. All committed changes and changes that are rolled back reflect the expected results.

Even when LOG NO is specified, changes to system pages and to the auxiliary index are logged. During the log apply operation of the RECOVER utility, LPL recovery, or GPB recovery, all LOB values that were not logged are marked invalid and cannot be accessed by a SELECT or FETCH statement. Invalid LOB values can be updated or deleted.

This clause is only implemented syntactically in the XDB Server operating environment.

DSSIZE integer G

A value in gigabytes that indicates the maximum size for each partition or, for LOB table spaces, each data set. If you specify DSSIZE, you must also specify NUMPARTS or LOB.The following values are valid:

1G | 1 gigabyte
2G | 2 gigabytes
4G | 4 gigabytes
8G | 8 gigabytes
16G | 16 gigabytes
32G | 32 gigabytes
64G | 64 gigabytes

To specify a value greater than 4G, the following conditions must be true:

  • DB2 is running with DFSMS Version 1 Release 5.
  • The data sets for the table space are associated with a DFSMS data class that has been specified with extended format and extended addressability.

For all table spaces except LOB table spaces, if DSSIZE (or LARGE) is omitted, the default for the maximum size of each partition depends on the value of NUMPARTS:

If NUMPARTS is ...Maximum partition size is...

1 to 16 | 4 GB
17 to 32 | 2 GB
33 to 64 | 1 GB
65 to 254 | 4 GB

The partition size shown is not necessarily the actual number of bytes used or allocated for any one partition; it is the largest number that can be logically addressed. Each partition occupies one data set.

For LOB table spaces, if DSSIZE is not specified, the default for the maximum size of each data set is 4 GB. The maximum number of data sets is 254.

When you give a table space a DSSIZE value, you also give the same size to all the indexes that point to that tablespace.

This clause is only implemented syntactically in the XDB Server operating environment.

NUMPARTS integer

Indicates that the table space is partitioned.

Integer is the number of partitions, and can range from 1 to 254 inclusive. NUMPARTS must be specified if DSSIZE is specified and LOB is omitted, or LARGE is specified.

The maximum size of each partition depends on the value specified for DSSIZE or LARGE. If DSSIZE or LARGE is not specified, the number of partitions specified determines the maximum size of each partition

If you omit NUMPARTS, the table space is not partitioned and initially occupies one data set. Do not specify NUMPARTS for a LOB table space, or a table space in a work file database or a TEMP database.

LOCKSIZE

Specifies the size of locks used within the table space and, in some cases, also the threshold at which lock escalation occurs. Do not use this clause for a table space in a work file database or a TEMP database.

ANY | Specifies that DB2 can use any lock size. Currently, DB2 never chooses row locks, but reserves the right to do so. In most cases, DB2 uses LOCKSIZE PAGE LOCKMAX SYSTEM for non-LOB table spaces and LOCKSIZE LOB LOCKMAX SYSTEM for LOB table spaces. However, when the number of locks acquired for the table space exceeds the maximum number of locks allowed for a table space (an installation parameter), the page or LOB locks are released and locking is set at the next higher level. If the table space is segmented, the next higher level is the table. If the table space is nonsegmented, the next higher level is the table space.
TABLESPACE | Specifies table space locks.
TABLE | Specifies table locks. Use TABLE only for a segmented table space.
PAGE | Specifies page locks. Do not use PAGE for a LOB table space.
ROW | Specifies row locks. Do not use ROW for a LOB table space.
LOB | Specifies LOB locks. Use LOB only for a LOB table space.

This clause is only implemented syntactically in the XDB Server operating environment.

CCSID

The CCSID clause is only syntactically supported for EBCDIC and ASCII. This is because the definition of the XDB location itself defines how character data is stored.

If you specify UNICODE, your character and graphic data is stored as UNICODE within the table space.

LOCKMAX

Specifies the maximum number of page, row, or LOB locks an application process can hold simultaneously in the table space. If a program requests more than that number, locks are escalated. The page, row, or LOB locks are released and the intent lock on the table space or segmented table is promoted to S or X mode. If you specify LOCKMAX for table space in a TEMP database, DB2 ignores the value because these types of locks are not used.

Integer | Specifies the number of locks allowed before escalating, in the range 0 to 2 147 483 647. Zero (0) indicates that the number of locks on the table or table space are not counted and escalation does not occur.
SYSTEM | Indicates that the value of LOCKS PER TABLE(SPACE), on installation panel DSNTIPJ, specifies the maximum number of page, row, or LOB locks a program can hold simultaneously in the table or table space.
LOCKSIZE | Resultant LOCKMAX
ANY | SYSTEM
TABLESPACE, TABLE, PAGE ROW, or LOB | 0

If the lock size is TABLESPACE or TABLE, LOCKMAX must be omitted, or its operand must be 0.

For an application that uses Sysplex query parallelism, a lock count is maintained on each member.

This clause is only implemented syntactically in the XDB Server operating environment.

USING

XDB records either the catalog-name (preceded by VCAT keyword), or the stogroup-name (preceded by STOGROUP) that is associated with the table space. If the USING clause is left out, a default stogroup for the database must already exist. If a path has already been associated with stogroup-name (through the SYSIBM.SYSVOLUMES catalog table), then any objects created within the table space are implicitly located in that stogroup path.

CLOSE

When the limit on the number of open data sets is reached, specifies the priority in which data sets are closed.

YES | Eligible for closing before CLOSE NO data sets. This is the default unless the table space is in a TEMP database.
NO | Eligible for closing after all eligible CLOSE YES data sets are closed.

For a table space in a TEMP database, DB2 uses CLOSE NO regardless of the value specified.

COMPRESS

Either the option specified or the default value is recorded in the SYSIBM.SYSTABLEPART system catalog table. This option does not compress data in any way. Do not specify COMPRESS for a LOB table space or a table space in a TEMP database.

SEGSIZE integer

Indicates that the table space will be segmented. integer specifies how many pages are to be assigned to each segment. integer must be a multiple of 4 such that 4 <= integer <= 64. If the SEGSIZE clause is not specified, the table space is not segmented.

SEGSIZE must be specified for a table space in a TEMP database because the table space must be segmented. Do not specify SEGSIZE for a LOB table space or a table space in work file database; neither can be segmented.

A segmented table space cannot be partitioned. Therefore, do not specify NUMPARTS if you specify SEGSIZE.

This clause is only implemented syntactically in the XDB Server operating environment.

MAXROWS integer

Specifies the maximum number of rows that DB2 will consider placing on each data page. The integer can range from 1 through 255. This value is considered for INSERT, LOAD, and REORG. For LOAD and REORG (which do not apply for a table space in the TEMP database), the PCTFREE specification is considered before MAXROWS; therefore, fewer rows might be stored than the value you specify for MAXROWS.

If you do not specify MAXROWS, the default number of rows is 255.

Do not use MAXROWS for a LOB table space or a table space in a work file database.

This clause is only implemented syntactically in the XDB Server operating environment.

BUFFERPOOL

This clause has no functional equivalent within the XDB Server operating environment. However, for DB2 compatibility purposes, the XDB Server records any of the sixty possible bufferpools (BP0...BP49, and BP32K, BP32K1...BP32K9). The first fifty bufferpools are for table spaces with 4K page sizes, while the last ten are for table spaces with 32K page sizes. Although not functionally supported, this new information is checked syntactically and recorded in the XDB Server system catalog tables.

If the table space is in a group buffer pool that is defined to be used only for cross-invalidation (GBPCACHE NO), CHANGED is ignored and no pages are cached to the group buffer pool.

Note:

When a table space is created in a workfile database, the following clauses are not allowed:

DEFINE NO | LOB | NUMPARTS
FREEPAGE | LOG | PCTFREE
GBPCACHE | LOCKSIZE | SEGSIZE

When a table space is created in a TEMP database, the following clauses are not allowed:

CCSID | GBPCACHE | LOG
COMPRESS | LARGE | MEMBER CLUSTER
DEFINE NO | LOB | NUMPARTS
DSSIZE | LOCKSIZE | PCTFEE
FREEPAGE | LOCKPART | TRACKMOD

When a LOB table space is created, the following clauses are not allowed:

CCSID | LOCKSIZE PAGE | PCTFREE
COMPRESS | LOCKSIZE ROW | SEGSIZE
FREEPAGE | NUMPARTS | LOCKSIZE TABLE
TRACKMOD |  |

If neither LOB, NUMPARTS, nor SEGSIZE are specified, the table space that is created is a simple table space.

Example:

The following example creates a table space named abc within the xyz database, while specifying the stor1 stogroup for that table space:

CREATE TABLESPACE abc IN xyz
    USING STOGROUP stor1;

In the above case, all objects created within the abc table space are stored in the path associated with the stor1 stogroup. This last result is true even if the logical database xyz is associated with a different stogroup.

In this example, assume that a column named EMP_PHOTO with a data type of BLOB(110K) has been added to the sample employee table for each employee's photo. Create LOB table space PHOTOLTS in database DSN8D61A for the auxiliary table that will hold the BLOB data.

Let DB2 define the data sets for the table space, using storage group DSN8G610. For each data set, the primary space allocation is 3200 kilobytes, and the secondary space allocation is 1600 kilobytes. The data sets do not need to be erased before they are deleted.

CREATE LOB TABLESPACE PHOTOLTS
    IN DSN8D61A
    USING STOGROUP DSN8G610
        PRIQTY 3200
        SECQTY 1600
    LOCKSIZE LOB
    BUFFERPOOL BP16K0
    GBPCACHE SYSTEM
    LOG NO
    CLOSE NO;
Parent topic: SQL Statements


CREATE TRIGGER

The CREATE TRIGGER statement defines a trigger in a schema and builds a trigger package at the current server.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

The privilege set that is defined below must include all of the following:

Either of these privileges:

  • The CREATEIN privilege for the schema or all schemas
  • SYSADM or SYSCTRL authority

The TRIGGER privilege on the table. The privilege set must include at least one of the following:

  • The TRIGGER privilege on the table on which the trigger is defined
  • The ALTER privilege on the table on which the trigger is defined
  • DBADM authority on the database that contains the table
  • SYSADM or SYSCTRL authority

The SELECT privilege on the table on which the trigger is defined if any transition variables or transition tables are specified

The SELECT privilege on any table or view to which the search condition of triggered action refers

The EXECUTE privilege on any user-defined function or stored procedure that is invoked in the triggered action

The necessary privileges to invoke the triggered SQL statements in the triggered action

Syntax

CREATE TRIGGER trigger-name {NO CASCADE BEFORE | AFTER}
    {INSERT | DELETE | UPDATE [OF column-name[,...]]} ON table-name
    [REFERENCING {OLD [AS] correlation-name |
                  NEW [AS] correlation-name |
                  OLD TABLE [AS] identifier |
                  NEW TABLE [AS] identifier}
    {FOR EACH ROW | FOR EACH STATEMENT} MODE DB2SQL triggered-action]

triggered-action:

[WHEN (search-condition) BEGIN ATOMIC triggered-SQL-statement;... END]

Description

trigger-name

Names the trigger. The name is implicitly or explicitly qualified by a schema. The name, including the implicit or explicit schema name, must not identify a trigger that exists at the current server.

The name is also used to create the trigger package; therefore, the name must also not identify a package that is already described in the catalog. The schema name becomes the collection-id of the trigger package.

  • The unqualified form of trigger-name is a short SQL identifier. The unqualified name is implicitly qualified with a schema name according to the following rules:

    If the statement is embedded in a program, the schema name of the trigger is the authorization ID in the QUALIFIER bind option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name of the trigger is the owner of the package or plan.

    If the statement is dynamically prepared, the schema name of the trigger is the SQL authorization ID of the process.

  • The qualified form of trigger-name is a short SQL identifier (the schema name) followed by a period and a short SQL identifier. The schema name must not begin with 'SYS' unless the name is 'SYSADM'. The schema name that qualifies the trigger name is the trigger's owner.

The owner of the trigger is determined by how the CREATE TRIGGER statement is invoked:

  • If the statement is embedded in a program, the owner is the authorization ID of the owner of the plan or package.
  • If the statement is dynamically prepared, the owner is the SQL authorization ID in the CURRENT SQLID special register.

NO CASCADE BEFORE

Specifies that the trigger is a before trigger. XDB executes the triggered action before it applies any changes caused by an insert, delete, or update operation on the triggering table. It also specifies that the triggered action does not activate other triggers because the triggered action of a before trigger cannot contain any updates.

AFTER

Specifies that the trigger is an after trigger. XDB executes the triggered action after it applies any changes caused by an insert, delete, or update operation on the triggering table.

INSERT

Specifies that the trigger is an insert trigger. XDB executes the triggered action whenever there is an insert operation on the triggering table.

However, if the insert trigger is defined on PLAN_TABLE, DSN_STATEMNT_TABLE, or DSN_FUNCTION_TABLE, and the insert operation was

caused by XDB adding a row to the table, the triggered action is not be executed.

DELETE

Specifies that the trigger is a delete trigger. XDB executes the triggered action whenever there is a delete operation on the triggering table.

UPDATE

Specifies that the trigger is an update trigger. XDB executes the triggered action whenever there is an update operation on the triggering table.

If you do not specify a list of column names, an update operation on any column of the triggering table, including columns that are subsequently added with the ALTER TABLE statement, activates the triggered action.

OF column-name,... Each column-name that you specify must be a column of the subject table and must appear in the list only once. An update operation on any of the listed columns activates the triggered action.

ON table-name

Identifies the subject table with which the trigger is associated. The name must identify a base table at the current server. It must not identify a temporary table, an auxiliary table, an alias, a synonym, or a catalog table.

REFERENCING

Specifies the correlation names for the transition variables and the table names for the transition tables. For the rows in the subject table that are modified by the triggering SQL operation (insert, delete, or update), a correlation name identifies the columns of a specific row. A table name identifies the complete set of modified rows.

Each row that is modified by the triggering operation is available to the triggered action by using column names that are qualified with correlation names that are specified as follows:

OLD AS correlation-name | Specifies the correlation name that identifies the state of the row prior to the triggering SQL operation.
NEW AS correlation-name | Specifies the correlation name that identifies the state of the row as modified by the triggering SQL operation and by any SET statement in a before trigger that has already been executed.

The complete set of rows that is modified by the triggering operation is available to the triggered action by using a temporary table name that is specified as follows:

OLD TABLE AS identifier | Specifies the name of a temporary table that identifies the state of the complete set of rows that are modified rows by the triggering SQL operation prior to any actual changes. identifier is a long SQL identifier.
NEW TABLE AS identifier | Specifies the name of a temporary table that identifies the state of the complete set of rows as modified by the triggering SQL operation and by any SET statement in a before trigger that has already been executed. identifier is a long SQL identifier.

At most, the trigger definition can include two correlation names (OLD and NEW) and two table names (OLD TABLE and NEW TABLE). All the names must be unique from one another.

FOR EACH ROW

Specifies that XDB executes the triggered action for each row of the subject table that the triggering SQL operation modifies. If the triggering SQL operation does not modify any rows, the triggered action is not executed.

FOR EACH STATEMENT

Specifies that XDB executes the triggered action only once for the triggering SQL operation. Even if the triggering SQL operation does not modify any rows, the triggered action is executed once. Do not specify FOR EACH STATEMENT for a before trigger.

MODE DB2SQL

Specifies the mode of the trigger. Currently, XDB supports only MODE DB2SQL.

triggered-action

Specifies the action to be performed when the trigger is activated. The triggered action is composed of one or more SQL statements and by an optional condition that controls whether the statements are executed.

WHEN (search-condition) | Specifies a condition that evaluates to true, false, or unknown. The condition for a before trigger must not include a subselect that references the triggering table. The triggered SQL statements are executed only if the search condition evaluates to true, or if WHEN is omitted.
BEGIN ATOMIC triggered-SQL-statement;... END | Specifies the SQL statements that are to be executed for the triggered action. The statements are executed in the order in which you specify them. The keywords BEGIN ATOMIC and END are required only if you specify more than one SQL statement. In which case, you must enclose the SQL statements in these keywords and end each statement with a semicolon (;).

The statements in the triggered action have these restrictions:

  • They must not refer to host variables, parameter markers, undefined transition variables, or declared temporary tables.
  • They must only refer to a table or view that is at the current server.
  • They must only invoke a stored procedure or user-defined function that is at the current server. An invoked routine can, however, access a server other than the current server.
  • They must not contain a fullselect that refers to the subject table if the trigger is defined as BEFORE

The triggered action may refer to the values in the set of affected rows. This action is supported through the use of transition variables and transition tables.

Transition variables use the names of the columns in the subject table qualified by a specified name that identifies whether the reference is to the old value (before the update) or the new value (after the update). A transition variable can be referenced in search-condition or triggered-SQL-statement of the triggered action wherever a host variable is allowed in the statement if it were issued outside the body of a trigger.

Transition tables can be referenced in the triggered action of an after trigger. Transition tables are read-only. Transition tables also use the name of the columns of the subject table but have a name specified that allows the complete set of affected rows to be treated as a table. The name of the transition table can be referenced in triggered-SQL-statement of the triggered action whenever a table name is allowed in the statement if it were issued outside the body of a trigger. The name of the transition table can be specified in search-condition or triggered-SQL-statement of the triggered action whenever a column name is allowed in the statement if it were issued outside the body of a trigger.

In addition, a transition table can be passed as a parameter to a user-defined function or procedure specifying the TABLE keyword before the name of the transition table. When the function or procedure is invoked, a table locator is passed for the transition table.

A transition variable or transition table is not affected after being returned from a procedure invoked from within a triggered action regardless of whether the corresponding parameter was defined in the CREATE PROCEDURE statement as IN, INOUT, or OUT.

The implicitly created trigger package

When you create a trigger, DB2 automatically creates a trigger package with the same name as the trigger name. The collection name of the trigger package is the schema name of the trigger, and the version identifier is the empty string. Multiple versions of a trigger package are not allowed.

The user executing the triggering SQL operation does not need authority to execute a trigger package. The trigger package does not need to be in the package list for the plan that is associated with the program that contains the SQL statement.

A trigger package becomes invalid if an object or privilege on which it depends is dropped or revoked. The next time the trigger is activated, DB2 attempts to rebind the invalid trigger package. If the automatic rebind is unsuccessful, the trigger package remains invalid.

You cannot create another package from the trigger package, such as with the BIND COPY command. The only way to drop a trigger package is to drop the trigger or the triggering table. Dropping the trigger drops the trigger package; dropping the subject table drops the trigger and the trigger package.

DB2 creates the trigger package with the following attributes:

  • ACTION(ADD)
  • CURRENTDATA(YES)
  • DBPROTOCOL(DRDA)
  • DEGREE(1)
  • DYNAMICRULES(BIND)
  • ENABLE(*)
  • EXPLAIN(NO)
  • FLAG(I)
  • ISOLATION(CS)
  • NOREOPT(VARS) and NODEFER(PREPARE)
  • OWNER(authorization ID)
  • QUERYOPT(1)
  • PATH(path)
  • RELEASE(COMMIT)
  • SQLERROR(NOPACKAGE)
  • QUALIFIER(authorization ID)
  • VALIDATE(BIND)

The values of OWNER, QUALIFIER, and PATH are set depending on whether the CREATE TRIGGER statement is embedded in a program or issued interactively. If the statement is embedded in a program, OWNER and QUALIFIER are the owner and qualifier of the package or plan. PATH is the value from the PATH bind option. If the statement is issued interactively, both OWNER and QUALIFIER are the SQL authorization ID. PATH is the value in the CURRENT PATH special register.

This functionality is only implemented syntactically in the XDB Server operating environment.

Activating a trigger

Only the SQL statements INSERT, DELETE, or UPDATE, or an update or delete operation that occurs as the result of a referential constraint with ON DELETE SET NULL or ON DELETE CASCADE can activate a trigger. Loading a table with the LOAD utility does not activate any triggers that are defined for the table.

This functionality is only implemented syntactically in the XDB Server operating environment.

Simultaneously activated triggers

Multiple triggers that have the same triggering SQL operation and activation time (BEFORE or AFTER) can be defined on a table. The triggers are activated in the order in which they were created. For example, the trigger that was created first is executed first; the trigger that was created second is executed second; and so on.

This functionality is only implemented syntactically in the XDB Server operating environment.

Adding columns to subject tables or tables that the triggered action references

If a column is added to a table for which a trigger is defined (the subject table), the following rules apply:

  • If the trigger is an update trigger that was defined without an explicit list of column names, an update to the new column activates the trigger.
  • If the SQL statements in the triggered action refer to the subject table, the new column is not accessible to the SQL statements until the trigger package is rebound.
  • The transition tables contain the new column. If the transition tables are passed to a user-defined function or a stored procedure, the user-defined function or stored procedure must be recreated with the new definition of the table (that is, the function or procedure must be dropped and recreated), and the package for the user-defined function or stored procedure must be rebound.

If a column is added to any table to which the SQL statements in the triggered action refers, the new column is not accessible to the SQL statements until the trigger package is rebound.

This functionality is only implemented syntactically in the XDB Server operating environment.

Adding triggers to enforce constraints

Creating a trigger on a table that already has rows does not cause the triggered action to be executed. Thus, if the trigger is designed to enforce constraints on the data in the table, the data in the existing rows might not satisfy those constraints.

Defining triggers on plan, statement, and function tables: You can create a trigger on PLAN_TABLE, DSN_STATEMNT_TABLE, or DSN_FUNCTION_TABLE. However, insert triggers that are defined on these tables are not activated when XDB adds rows to the tables.

This functionality is only implemented syntactically in the XDB Server operating environment.

Renaming triggering tables or tables that the triggered action references

You cannot rename a table for which a trigger is defined (the triggering table). Except for the triggering table, you can rename any table to which the SQL statements in the triggered action refer. After renaming such a table, drop the trigger and then re-create the trigger so that it refers to the renamed table.

Dependencies when dropping objects and revoking privileges: The following dependencies apply to a trigger:

  • Dropping the subject table (the table on which the trigger is defined) causes the trigger and its package to also be dropped.
  • Dropping any table, view, alias, or index that is referenced or used within the SQL statements in the triggered action causes the trigger and its package to be invalidated. Dropping a referenced synonym has no effect.
  • Dropping a user-defined function that is referenced by the SQL statements in the triggered action is not allowed. An error occurs.
  • Revoking a privilege on which the trigger depends causes the trigger and its package to be invalidated.

This functionality is only implemented syntactically in the XDB Server operating environment.

Result sets for stored procedures

If a trigger invokes a stored procedure that returns result sets, the application that activated the trigger cannot access those result sets.

Values of special registers

The values of the special registers are saved before a trigger is activated and are restored on return from the

trigger.

Errors when binding triggers

When a CREATE TRIGGER statement is bound, the SQL statements within the triggered action may not be fully parsed. Syntax errors in those statements might not be caught until the CREATE TRIGGER statement is executed.

Errors when executing triggers

Severe errors that occur during the execution of triggered SQL statements are returned with SQLCODE -901, -906, -911, and -913 and the corresponding SQLSTATE. Non-severe errors raised by a triggered SQL statement that is a SIGNAL SQLSTATE statement or that contains a RAISE_ERROR function are returned with SQLCODE -438 and the SQLSTATE that is specified in the SIGNAL SQLSTATE statement or the RAISE_ERROR condition. Other non-severe errors are returned with SQLCODE -723 and SQLSTATE 09000.

Warnings are not returned.

Limiting processor time

XDB's resource limit facility allows you to specify the maximum amount of processor time for a dynamic, manipulative SQL statement (SELECT, INSERT, UPDATE, and DELETE). The execution of a trigger is counted as part of the triggering SQL statement.

Example:

Create two triggers that track the number of employees that a company manages. The subject table is the EMPLOYEE table, and the triggers increment and decrement a column with the total number of employees in the COMPANY_STATS table. The tables have these columns:

EMPLOYEE table: ID, NAME, ADDRESS, and POSITION

COMPANY_STATS table: NBEMP, NBPRODUCT, and REVENUE

This example shows the use of transition variables in a row trigger to maintain summary data in another table.

Create the first trigger, NEW_HIRE, so that it increments the number of employees each time a new person is hired; that is, each time a new row is inserted into the EMPLOYEE table, increase the value of column NBEMP in table COMPANY_STATS by 1.

CREATE TRIGGER NEW_HIRE
    AFTER INSERT ON EMPLOYEE
    FOR EACH ROW MODE DB2SQL
    BEGIN ATOMIC
        UPDATE COMPANY_STATS SET NBEMP = NBEMP + 1;
    END

Create the second trigger, FORM_EMP, so that it decrements the number of employees each time an employee leaves the company; that is, each time a row is deleted from the table EMPLOYEE, decrease the value of column NBEMP in table COMPANY_STATS by 1.

CREATE TRIGGER FORM_EMP
    AFTER DELETE ON EMPLOYEE
    FOR EACH ROW MODE DB2SQL
    BEGIN ATOMIC
        UPDATE COMPANY_STATS SET NBEMP = NBEMP - 1;
    END
Parent topic: SQL Statements


CREATE USER

The CREATE USER statement enables you to create additional XDB user accounts.
Restriction: This topic applies to Windows environments only.

Syntax

CREATE USER username
         TYPE [ USER | SUPERUSER ]
         PASSWORD password REQUIRED [ YES | NO ]
         option_list

option-list:

SECONDARY ID authid
        GROUPS group_list
        PRIORITY priority
        ACCESS AUTHORITY [ YES | NO ]
        COMMENT quoted-string

Description

Requirements for XDB passwords can be controlled on an XDB user basis. ACCESS AUTHORITY set to NO completely disables an XDB user id. The SECONDARY ID, GROUPS, and PRIORITY concepts are all discussed in the section System Level Access Control in the Security and Authority chapter in your SQL Option Server Administration Guide

Parent topic: SQL Statements


CREATE VIEW

The CREATE VIEW command is used to define a view or virtual table that is based on one or more tables or views. The view definition is stored at the current location. While a view does not actually contain data, it provides indirect access to data contained in the tables upon which the view is based. Views may be used to define subsets of tables, or to combine data from several tables into a logical view. Views may contain expressions that are computed from other columns, including aggregate functions such as averages, totals, etc.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively.

Authorization

For every table or view identified in the subselect of the CREATE VIEW statement, you must possess either DBADM authority for the database, SELECT privilege on the table or view, overall SYSADM or SYSCTRL authority for the location, or be the owner of the source table or view.

Authority requirements for using the view depend on the owner assigned to the view. (See the view-name parameter description under Syntax.) In order to use a view you must have the appropriate SELECT, UPDATE, INSERT, or DELETE privilege on the view.

The following authorization rules apply with using CREATE VIEW with an XDB Server:

  • If the AuthID for the application process possesses SYSADM authority, the view owner can be any AuthID.
  • If the view satisfies the rule in the previous bullet, and if the CREATE VIEW statement is error-free, the view is created, whether or not the owner has privileges on the tables and views identified in the view subselect.
  • If the AuthID for the application process does not possess SYSADM or SYSCTRL authority, only the AuthIDs of the process can own the view. In these circumstances, the view privileges match those held by the AuthID selected for ownership.

Syntax

CREATE VIEW view-name [(view-col-name[,...])]
    AS subselect [WITH [CASCADED | LOCAL] CHECK OPTION]

Parameters:

view-name Is any long identifier naming the view. This view name cannot have the same name as another view, table or synonym in the same location. If qualified, the name can be two-part or three-part name. If the name has three-parts, the first part must match the value of the CURRENT LOCATION register. The AuthID that qualifies the view name becomes the view owner. If the view name is unqualified in the CREATE VIEW statement, then the view owner is the SQL AuthID of the application process.

The view owner always acquires the authority to drop the view, as well as the SELECT privilege on the view. The owner must already possess grantable SELECT privileges on every table or view identified in the first FROM clause of the view subselect statement, in order to obtain a grantable SELECT privilege on the view. These grantable privileges must be acquired by the owner before the creation of the view.

INSERT, UPDATE and DELETE privileges on the view are also acquired by the owner if the view is not "read only." In these cases, the first FROM clause of the subselect identifies a single table or view only. If the owner already has either INSERT, UPDATE or DELETE privileges on this table or view, the owner acquires that privilege on the newly created view. These privileges are grantable only if the object privileges from which the view was derived are also grantable. These privileges must be acquired by the owner before the new view is created.

view-col-name | Any long identifier specifying a column in the view. Column names for views must satisfy the same naming criteria as table column names. If multiple view-col-name items are specified, the number of these columns must match the number of columns in the result table specified in the subselect. If the view-col-name list is missing, the view columns take the names of the columns specified in the subselect result table. If the result table of the subselect has duplicate column names or unnamed columns derived from constants, functions or expressions, a view-col-name list must be specified.
subselect | A SELECT command statement (following the keyword AS) producing a results table constituting the data contained in the view.

When creating views with subselects all referenced table(s) and all subselects in a single SQL statement must be from the same location -- which must also be the current location. subselect must not refer to any declared temporary tables. It must also not refer to host variables or include parameter markers (question marks). CREATE VIEW is not a DUW or RUW capable command.

Description

When a view is created or dropped, the system automatically updates the appropriate system catalog tables containing the definitions of all views in the current location. When a user queries the view, the system reads the view definition, and performs the corresponding query to obtain the result.

Note:

If you modify the underlying tables used by a view, you should drop the view and recreate it.

Updatable Views

When data in a view is updated, the changes are reflected in the underlying database table. For views to be updatable, the subselect used to define the view must satisfy the following criteria:

  • The query cannot contain DISTINCT.
  • The SELECT clause can contain only column names (no expressions or functions, including aggregate functions.)
  • The FROM clause can contain only one table name.
  • GROUP BY, ORDER BY or HAVING clauses are not permitted.

A simple way to determine whether a view can be defined as an updatable view is to attempt to create it using the WITH CHECK OPTION clause. If the view cannot be defined as updatable view, an error message is displayed.

CHECK OPTION must not be specified if any of the following conditions are true:

  • The view is read-only.
  • The search condition of the view includes a subquery, or the search condition of an underlying view includes a subquery.
  • The search condition of the view includes a user-defined function that is nondeterministic or has an external action.
  • The subselect refers to a created temporary table.

Expressions

Expressions, including those involving aggregate functions, are permitted in views. If expressions are selected, you must explicitly name all columns of the view. Such views are read-only views.

Joins

You may create views by joining other tables and views. The SELECT statement must explicitly name all columns if the tables or views being joined contain duplicate names. Views containing joins are read-only views.

GROUP BY and HAVING

Views defined using GROUP BY cannot be joined with another table or view. These views cannot be updated. HAVING clauses are allowed in view definitions containing GROUP BY.

ORDER BY

ORDER BY clauses are not permitted in the SELECT statement that defines a view.

UNION

The UNION operator cannot be used in the definition of a view.

WITH CHECK OPTION

The search condition of a view is specified in the first WHERE clause of the subselect that defines the view. The WITH CHECK OPTION specifies that every row of the view must conform to the search condition of this WHERE clause. The XDB Server enforces this constraint whenever rows of the view are inserted or updated. If an updatable view is created using the WITH CHECK OPTION clause, the system automatically tests whether inserts or updates to the view will satisfy the WHERE clause of the view definition. If they do not, the system signals an error, and any changes to the underlying tables are aborted.

To prevent the search condition of the view from checking insert or update operations, omit the WITH CHECK OPTION clause. This omission allows the insertion of "nonconforming" rows of data into the underlying table, as well as the updating of table rows in such a way that these rows will no longer be retrievable by the original view.

The two forms of the check option (CASCADED and LOCAL) are meaningful only when views are defined on each other. The view upon which another view is directly or indirectly defined is an underlying view.

  • CASCADED

    Update and insert operations must satisfy the search conditions of the view and underlying views, regardless of whether the underlying views were defined with a check option. This value is the default.

  • LOCAL

    Update and insert operations must satisfy the search conditions of the view and underlying views that are defined with a check option.

View Definitions

Creating or dropping a view causes the system to automatically update the SYSIBM.SYSTABLES, SYSIBM.SYSCOLUMNS and SYSIBM.SYSVIEWS catalog tables. Dropping a table or view causes all views dependent on that table or view to be dropped as well. You can query the system catalog tables for table, view, column and index information. The query results can be formatted into your own reports. See XDB Server System Tables for a list of the system catalog tables used for this purpose.

You can use SQLWizard to examine table definitions interactively. In addition, the Catalog Browser function of SQLWizard lists table, view and index definitions.

Read-only views

A view is read-only if one or more of the following statements is true of its definition:

  • The first FROM clause identifies more than one table or view, or identifies a table function
  • The first SELECT clause specifies the keyword DISTINCT
  • The outer subselect contains a GROUP BY clause
  • The outer subselect contains a HAVING clause
  • The first SELECT clause contains a column function
  • It contains a subquery such that the base object of the outer subselect, and of the subquery, is the same table
  • The first FROM clause identifies a read-only view

A read-only view cannot be the object of an INSERT, UPDATE, or DELETE statement. A view that includes GROUP BY or HAVING cannot be referred to in a subquery of a basic predicate.

Examples:

The following example defines a view that is a subset of the PART table. The optional view column list is omitted. The view column names will be the same as the PART table column names:

CREATE VIEW redparts AS
    SELECT *
        FROM part
        WHERE color = 'RED'
        WITH CHECK OPTION

If you retrieve all records from the REDPARTS view, the result would be:

pno | pname | color | weight | city
P1 | NUT | RED | 12 | LONDON
P4 | SCREW | RED | 14 | LONDON
P6 | COG | RED | 19 | LONDON

This view is not updatable. However, since the view was created using the WITH CHECK OPTION clause, you cannot update the view or insert any records into the view that do not satisfy the condition color = 'RED'.

The next example shows a read-only view defined by joining three tables, PART, SUPPLIER and PARTSUPP:

CREATE VIEW s_ps_p
    (s#, supplier, p#, part, quantity) AS
        SELECT sno, sname, pno, pname, qty
            FROM supplier s, partsupp ps, part p
            WHERE s.sno = ps.sno
              AND p.pno = ps.pno

If you retrieve all records from the S_PS_P view, the result would be:

s# | supplier | p# | part | quantity
S1 | SMITH | P1 | NUT | 300
S1 | SMITH | P3 | CAM | 400
S2 | JONES | P2 | BOLT | 400
S3 | BLAKE | P2 | BOLT | 200
S1 | SMITH | P2 | BOLT | 200
S1 | SMITH | P4 | SCREW | 200
S1 | SMITH | P5 | CAM | 100
S1 | SMITH | P6 | COG | 100
S2 | JONES | P1 | NUT | 300
S4 | CLARK | P2 | BOLT | 200
S4 | CLARK | P4 | SCREW | 300
S4 | CLARK | P5 | CAM | 400

The following is an example of a read-only view containing aggregate functions and a GROUP BY clause:

CREATE VIEW order_statistics
    (o_no, total_items, total_order) AS
    SELECT o_no, COUNT(p_no), SUM(quantity * price)
        FROM items
        GROUP BY o_no

Selecting all records from the view would produce the following result:

o_no | tot_items | total_order
1 | 1 | $120.00
2 | 2 | $985.00
3 | 1 | $240.00
4 | 2 | $830.00
5 | 2 | $2,070.00
Parent topic: SQL Statements


DECLARE CURSOR

The DECLARE CURSOR command (embedded SQL only) is used to define a cursor, which is a named control structure that points to a row in a set of records defined by a query.
Restriction: This topic applies to Windows environments only.

Invocation

DECLARE CURSOR is not an executable statement. It can only be embedded in an application language.

Authorization

For each table (or view) identified in the SELECT portion of the DECLARE CURSOR statement, users must possess either DBADM authority for the corresponding database (tables only), the SELECT privilege on the table or view, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table or view.

The SELECT statement specified as an argument within the DECLARE CURSOR statement can be either a standard SELECT statement (select-statement) or a dynamically prepared (PREPARE command) select statement stored in a declared SQL statement (statement-name). Each of these distinct SELECT statement types must have access to different sets of authorization privileges in order to execute.

If a select-statement is specified, then the privileges available for this SELECT statement match those held by the CURRENT SQLID when the cursor is opened.

If a statement-name is specified, the available privileges for the prepared SELECT statement are a combination of the privileges held by the AuthID of the application process. The authorization check is performed when the SELECT statement is prepared. The cursor cannot be opened (OPEN command) unless the SELECT statement has been successfully prepared.

Syntax

DECLARE cursor-name
    [[NOSCROLL] | {ASENSITIVE | INSENSITIVE} SCROLL | SENSITIVE [DYNAMIC | STATIC] SCROLL]
    CURSOR [holdability | returnability | rowset-positioning [...]]
    FOR {select-statement | statement-name}

holdability

[WITH HOLD | WITHOUT HOLD]

returnability

[WITH RETURN [TO CALLER] | WITHOUT RETURN]

rowset-positioning

[WITH ROWSET POSITIONING | WITHOUT ROWSET POSITIONING]

Parameters:

cursor-name | Any valid identifier that names the new cursor and does not identify an already declared cursor in the source program.
select-statement | Specifies an actual query (SELECT statement) represented by the cursor. This SELECT statement can include host variables, the declarations for which must precede the DECLARE CURSOR statement in the source program.
statement-name | Indicates that the query occurring when opening the cursor originated from a prepared SELECT statement identified by statement-name. The statement-name must not match any other statement-name specified within any other DECLARE CURSOR statement in the source program.

Description

The DECLARE CURSOR command is only available when SQL is embedded in a host language such as COBOL or C. The DECLARE CURSOR command is checked for the following syntactical elements:

  • Is the command a SELECT or a statement-name? The SELECT may be a full select statement as defined in this reference. If it is a statement-name, it must be the name of a previously prepared SELECT command.
  • The DECLARE CURSOR statement must precede all commands that explicitly reference the cursor defined by the DECLARE CURSOR command.
  • A cursor may only be referenced within the source program in which it is defined.
Note:

The sample programs contain examples of declaring cursors.

NO SCROLL or SCROLL

Specifies whether the cursor is scrollable or not scrollable.

NO SCROLL

Specifies that the cursor is not scrollable. This is the default.

SCROLL

Specifies that the cursor is scrollable. For a scrollable cursor, whether the cursor has sensitivity to inserts, updates, or deletes depends on the cursor sensitivity option in effect for the cursor. If a sensitivity option is not specified, ASENSITIVE is the default. The sensitivity options include the following ones:

asensitivity

Specifies the desired sensitivity of the cursor to inserts, updates, or deletes that made to the rows underlying the result table. The sensitivity of the cursor determines whether XDB can materialize the rows of the result into a temporary table.

ASENSITIVE

Specifies that the cursor should be as sensitive as possible. This is the default.

A cursor that defined as ASENSITIVE will be either insensitive or sensitive dynamic; it will not be sensitive static.

INSENSITIVE

Specifies that the cursor does not have sensitivity to inserts, updates, or deletes that are made to the rows underlying the result table. As a result, the size of the result table, the order of the rows, and the values for each row do not change after the cursor is opened. In addition, the cursor is read-only. The SELECT statement or attribute-string of the PREPARE statement cannot contain a FOR UPDATE clause, and the cursor cannot be used for positioned updates or deletes.

SENSITIVE

Specifies that the cursor has sensitivity to changes that are made to the database after the result table is materialized. The cursor is always sensitive to updates and deletes that are made using the cursor (that is, positioned updates and deletes using the same cursor). When the current value of a row no longer satisfies the select-statement or statement-name, that row is no longer visible through the cursor. When a row of the result table is deleted from the underlying base table, the row is no longer visible through the cursor.

If XDB cannot make changes visible to the cursor, then an error is issued at bind time for OPEN CURSOR. XDB cannot make changes visible to the cursor when the cursor implicitly becomes read-only. Such is the case when the result table must be materialized, as when the FROM clause of the SELECT statement contains more than one table or view.

The default is DYNAMIC.

DYNAMIC

Specifies that the result table of the cursor is dynamic, meaning that the size of the result table may change after the cursor is opened as rows are inserted into or deleted from the underlying table, and the order of the rows may change. Rows that are inserted, deleted, or updated by statements that are executed by the same application process as the cursor are visible to the cursor immediately. Rows that are inserted, deleted, or updated by statements that are executed by other application processes are visible only after the statements are committed. If a column for an ORDER BY clause is updated via a cursor or any means outside the process, the next FETCH statement behaves as if the updated row was deleted and re-inserted into the result table at its correct location. At the time of a positioned update, the cursor is positioned before the next row of the original location and there is no current row, making the row appear to have moved.

If a SENSITIVE DYNAMIC cursor is not possible, an error is returned. For example, if a temporary table is needed (such as for processing a FETCH FIRST n ROWS ONLY clause), an error is returned. The SELECT statement of a cursor that is defined as SENSITIVE DYNAMIC cannot contain an INSERT statement.

STATIC

Specifies that the size of the result table and the order of the rows do not change after the cursor is opened. Rows inserted into the underlying table are not added to the result table regardless of how the rows are inserted. Rows in the result table do not move if columns in the ORDER BY clause are updated in rows that have already been materialized. Positioned updates and deletes are allowed if the result table is updatable. The SELECT statement of a cursor that is defined as SENSITIVE STATIC cannot contain an INSERT statement.

A STATIC cursor has visibility to changes made by this cursor using positioned updates or deletes. Committed changes made outside this cursor are visible with the SENSITIVE option of the FETCH statement. A FETCH SENSITIVE can result in a hole in the result table (that is, a difference between the result table and its underlying base table). If an updated row in the base table of a cursor no longer satisfies the predicate of its SELECT statement, an update hole occurs in the result table. If a row of a cursor was deleted in the base table, a delete hole occurs in the result table. When a FETCH SENSITIVE detects an update hole, no data is returned (a warning is issued), and the cursor is left positioned on the update hole. When a FETCH SENSITIVE detects a delete hole, no data is returned (a warning is issued), and the cursor is left positioned on the delete hole.

Updates through a cursor result in an automatic re-fetch of the row. This re-fetch means that updates can create a hole themselves. The re-fetched row also reflects changes as a result of triggers updating the same row. It is important to reflect these changes to maintain the consistency of data in the row.

Using a nondeterministic function (built-in or user-defined) in the WHERE clause of the select-statement or statement-name of a SENSITIVE STATIC cursor can cause misleading results. This situation occurs because XDB constructs a temporary result table and retrieves rows from this table for FETCH INSENSITIVE statements. When XDB processes a FETCH SENSITIVE statement, rows are fetched from the underlying table and predicates are re-evaluated. Using a nondeterministic function can yield a different result on each FETCH SENSITIVE of the same row, which could also result in the row no longer being considered a match.

A FETCH INSENSITIVE on a SENSITIVE STATIC SCROLL cursor is not sensitive to changes made outside the cursor, unless a previous FETCH SENSITIVE has already refreshed that row; however, positioned updates and delete changes with the cursor are visible.

STATIC cursors are insensitive to insertions.

WITH HOLD Clause

This optional clause prevents a commit operation from closing the cursor. Instead, a COMMIT statement logs all the changes from the current unit of work, leaving in place those locks required to maintain the cursor. After the commit operation, a single FETCH statement must initially be executed before a subsequently positioned UPDATE or DELETE statement can be executed on the cursor. After this FETCH, the cursor pointer can be advanced onto the next cursor row (or the row following the current row before the COMMIT). A ROLLBACK command, however, will close the cursor.

Omitting the WITH HOLD option from the cursor declaration causes that cursor to be implicitly closed by a COMMIT operation. A CONNECT or ROLLBACK operation also implicitly closes all cursors.

Closing a cursor before a COMMIT operation, has the same effect as declaring the cursor without the WITH HOLD option.

WITH RETURN Clause

This optional clause specifies that the cursor, if it is declared in a stored procedure, can return a result set to the caller.

Result Table

A result table is a temporary table of row data created when an OPEN command is issued against a previously declared cursor. This temporary table remains in memory until a CLOSE command is issued against the cursor (or a COMMIT or ROLLBACK occurs). The query criteria specified in the cursor's original PREPARE statement determines the row data retrieved into the result table. An opened (OPEN command) cursor consists of both a result table and a position pointer that moves among the table rows.

Read-Only Result Tables

A read-only result table occurs in any of the following situations:

  • When the first FROM clause of the cursor query identifies more than one table or view.
  • The first SELECT clause specifies the keyword DISTINCT.
  • The outer subselect contains either a GROUP BY or HAVING clause.
  • The first SELECT clause contains a column function.
  • The cursor contains a subquery in which the base table of the outer subselect is the same as the subquery table.
  • The first FROM clause of the cursor query identifies either a read-only view or a catalog table with no updatable columns.
  • The first FROM clause identifies a table function
  • The first FROM clause contains a nested table expression
  • A UNION or UNION ALL operator is present in the cursor query.
  • An ORDER BY clause or a FOR FETCH ONLY clause is present in the cursor query.

COBOL Usage

In COBOL source programs, a DECLARE CURSOR command is checked to verify whether host variables exist in either the LINKAGE or WORKING STORAGE section. In COBOL applications (as mentioned above), an application called from another application cannot use a cursor that was declared by the calling application. The scope of the cursor is the source program in which it is defined, which limits cursor references to statements precompiled along with the cursor declaration.

ExampleS:

The following COBOL language examples illustrate PREPARE, DECLARE, OPEN, and FETCH cursor statements:

EXEC SQL
    DECLARE d1 CURSOR FOR
        SELECT deptno, dname
            FROM dept
            WHERE mgrno = :mgrno
END-EXEC

or:

EXEC SQL
    PREPARE emp_in_dept FROM
        SELECT e_no, lname
            FROM employee
            WHERE dept = ?
END-EXEC

EXEC SQL
    DECLARE e1 CURSOR FOR emp_in_dept
END-EXEC

EXEC SQL
    OPEN e1 USING :deptnum
END-EXEC

EXEC SQL
    FETCH e1 INTO :enum, :last_name
END-EXEC
Parent topic: SQL Statements


DECLARE GLOBAL TEMPORARY TABLE

The DECLARE GLOBAL TEMPORARY TABLE statement defines a declared temporary table for the current application process and instantiates an empty instance of the table for the process.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required, unless the LIKE clause is specified when additional privileges might be required.

PUBLIC implicitly has the following privileges without GRANT authority for declared temporary tables:

  • The CREATETAB privilege to define a declared temporary table in the database that is defined AS TEMP, which is the database for declared temporary tables.
  • The USE privilege to use the table spaces in the database that is defined as TEMP.
  • All table privileges on the table and authority to drop the table. (Table privileges for a declared temporary table cannot be granted or revoked.)

These implicit privileges are not recorded in the DB2 catalog and cannot be revoked.

Syntax

DECLARE GLOBAL TEMPORARY TABLE table-name
{
    (column-spec[,...]) |
    LIKE {table-name | view-name} [INCLUDING INDENTITY [COLUMN ATTRIBUTES]] |
    AS (subselect) DEFINITION ONLY [as-attribute]
}
    [CCSID {EBCDIC | ASCII}]
    [ON COMMIT PRESERVE ROWS]

column-spec:

column-name data-type
[NOT NULL]
[[WITH] DEFAULT [constant | USER | CURRENT SQLID | NULL]]
[GENERATED {ALWAYS | BY DEFAULT} [as-identity-clause}]

as-attribute:

[INCLUDING IDENTITY [COLUMN ATTRIBUTES]]
[INCLUDING [COLUMN] DEFAULTS]
[USING TYPE DEFAULTS]

as-identity-clause:

AS IDENTITY
    [({START WITH {numeric-constant | 1} | INCREMENT BY {numeric-constant | 1} |
    {CACHE 20 | NO CACHE | CACHE integer}}][,..])]

table-name

Names the temporary table. The qualifier, if specified explicitly, must be SESSION. If the qualifier is not specified, it is implicitly defined to be SESSION.

If a table, view, synonym, or alias already exists with the same name and an implicit or explicit qualifier of SESSION:

  • The declared temporary table is still defined with SESSION.table-name. An error is not issued because the resolution of a declared temporary table name does not include the persistent and shared names in the XDB catalog tables.
  • Any references to SESSION.table-name will resolve to the declared temporary table rather than to any existing SESSION.table-name whose definition is persistent and is in the XDB catalog tables.

PUBLIC implicitly acquires ALL PRIVILEGES on the table and authority to drop the table. These implicit privileges are not recorded in the XDB catalog and cannot be revoked.

column-spec

Defines the attributes of a column for each instance of the table. The number of columns defined must not exceed 750. The maximum record size must not exceed 32714 bytes. The maximum row size must not exceed 32706 bytes (8 bytes less than the maximum record size).

column-name

Names the column. The name must not be qualified and must not be the same as the name of another column in the table.

data-type

Specifies the data type of the column. The data type can be any built-in data type that can be specified for the CREATE TABLE statement except for a LOB (BLOB, CLOB, and DBCLOB) or ROWID type. The FOR subtype DATA clause can be specified as part of data-type.

NOT NULL

Specifies that the column cannot contain nulls. Omission of NOT NULL indicates that the column can contain nulls.

DEFAULT

The default value assigned to the column in the absence of a value specified on INSERT. Do not specify DEFAULT for a column that is defined AS IDENTITY (an identity column); XDB generates default values.

If DEFAULT is not specified, the default value for the column is the null value.

If DEFAULT is specified without a value after it, the default value of the column depends on the data type of the column, as follows:

Data type | Default value
Numeric | 0
Fixed length string | Blanks
Varying-length string | A string of length 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP

A default value other than the one that is listed above can be specified in one of the following forms:

Constant | Specifies a constant as the default value for the column. The value of the constant must conform to the rules for assigning that value to the column.
USER | Specifies the value of the USER special register at the time of INSERT or LOAD as the default value for the column. If USER is specified, the data type of the column must be a character string with a length attribute greater than or equal to the length attribute of the USER special register, which is 8 bytes.
CURRENT SQLID | Specifies the value of the SQL authorization ID of the process at the time of INSERT or LOAD as the default value for the column. If CURRENT SQLID is specified, the data type of the column must be a character string with a length attribute greater than or equal to the length attribute of the CURRENT SQLID special register, which is 8 bytes.
NULL | Specifies null as the default value for the column.

In a given column definition:

  • NOT NULL and DEFAULT NULL cannot both be specified.
  • DEFAULT cannot be specified for an identity column.
  • Omission of NOT NULL and DEFAULT for a column other than an identity column is an implicit specification of DEFAULT NULL. For an identity column, it is an implicit specification of NOT NULL, and XDB generates default values.

GENERATED

Specifies that XDB generates values for the column. You must specify GENERATED if the column is to be considered an identity column (a column defined with the AS IDENTITY clause).

ALWAYS | Specifies that XDB always generates a value for the column when a row is inserted into the table.
BY DEFAULT | Specifies that XDB generates a value for the column when a row is inserted into the table unless a value is specified. BY DEFAULT is the recommended value only when you are using data propagation.
AS IDENTITY | Specifies that the column is an identity column for the table. A table can have only one identity column. AS IDENTITY can be specified only if the data type for the column is an exact numeric type with a scale of zero (SMALLINT, INTEGER, DECIMAL with a scale of zero).

LIKE table-name or view-name

Specifies that the columns of the table have exactly the same name and description as the columns of the identified table or view. The name specified must identify a table, view, synonym, or alias that exists at the current server. The identified table must not be an auxiliary table or a declared temporary table.

The privilege set must include the SELECT privilege on the identified table or view.

This clause is similar to the LIKE clause on CREATE TABLE, but it has the following differences:

  • If LIKE results in a column having a LOB data type, a ROWID data type, or distinct type, the DECLARE GLOBAL TEMPORARY TABLE statement fails.
  • In addition to these data type restrictions, if any column has any other attribute value that is not allowed in a declared temporary table, that attribute value is ignored. The corresponding column in the new temporary table has the default value for that attribute unless otherwise indicated.

When the identified object is a table, the column name, data type, nullability, and default attributes are determined from the columns of the specified table; any identity column attributes are inherited only if the INCLUDING IDENTITY COLUMN ATTRIBUTES clause is specified. When the identified object is a view, only the column name, data type, and nullability attributes are determined from the columns of the specified view.

INCLUDING IDENTITY COLUMN ATTRIBUTES Specifies that the new table inherits all of the identity attributes of the identity column. If the table identified by LIKE does not have an identity column, the INCLUDING IDENTITY clause is ignored. If the LIKE clause identifies a view, INCLUDING IDENTITY COLUMN ATTRIBUTES cannot be specified.

AS (subselect) DEFINITION ONLY

Specifies that the columns of the table are to have the same name and description as the columns that would appear in the derived result table of the subselect if the subselect were to be executed. The use of AS subselect is an implicit definition of n columns for the table, where n is the number of columns that would result from the subselect.

DEFINITION ONLY indicates that the subselect is not executed. Therefore, there is no result table with a set of rows with which to automatically populate the declared temporary table. However, you can use the INSERT INTO statement with the same subselect specified in the AS clause to populate the declared temporary table with the set of rows from the result table of the subselect.

The implicit definition includes all the attributes of the n columns of subselect that are applicable for a declared temporary table with the exception of these column attributes:

  • The default value assigned to a column when a value is not specified on INSERT
  • The identity attribute, if any

The behavior of these column attributes are controlled with the INCLUDING or USING TYPE DEFAULTS clauses, which are defined below.

If subselect results in a column having a LOB data type, a ROWID data type, or a distinct type, the DECLARE GLOBAL TEMPORARY statement fails.

If subselect results in other column attributes that are not applicable for a declared temporary table, those attributes are ignored in the implicit definition for the declared temporary table.

The implicitly defined columns of the declared temporary table inherit the names of the columns from the result table of the subselect. Therefore, a column name must be specified in the subselect for all result columns. For result columns that are derived from expressions, constants, and functions, the subselect must include the AS column-name clause immediately after the result column.

The subselect must not refer to host variables or include parameter markers (question marks).

INCLUDING IDENTITY COLUMN ATTRIBUTES

Specifies that the declared temporary table inherits the identity attribute, if any, of the columns resulting from subselect. In general, the identity attribute is copied if the element of the corresponding column in the table, view, or subselect is the name of a table column or the name of a view column that directly or indirectly maps to the name of a base table column with the identity property. The columns of the new table do not inherit the identity attribute in the following cases:

  • The select list of the subselect includes multiple instances of an identity column name (that is, selecting the same column more than once).
  • The select list of the subselect includes multiple identity columns (that is, it involves a join).
  • The identity column is included in an expression in the select list.
  • The subselect includes a set operation (union).

If INCLUDING IDENTITY is not specified, the declared temporary table will not have an identity column.

INCLUDING COLUMN DEFAULTS

Specifies that the declared temporary table inherits the default values of the columns resulting from subselect. A default value is the value assigned to a column when a value is not specified on an INSERT.

Do not specify INCLUDING COLUMN DEFAULTS, if you specify USING TYPE DEFAULTS.

If neither INCLUDING COLUMN DEFAULTS nor USING TYPE DEFAULTS is specified, the default values of the columns of the declared temporary table are either null or there are no default values. If the column can be null, the default is the null value; if the column cannot be null, there is no default value, and an error occurs if a value is not provided for a column on an INSERT for the declared temporary table.

USING TYPE DEFAULTS

Specifies that the default values for the declared temporary table depend on the data type of the columns that result from subselect, as follows:

Data type | Default value
Numeric | 0
Fixed-length string | Blanks
Varying-length string | A string of length 0
Date | CURRENT DATE
Time | CURRENT TIME
Timestamp | CURRENT TIMESTAMP

Do not specify USING TYPE DEFAULTS, if you specify INCLUDING COLUMN DEFAULTS.

ON COMMIT commit-action ROWS

Specifies whether the contents of the table are to be deleted or preserved across a commit operation.

DELETE | The rows of the table are deleted if no WITH HOLD cursors are open on the table. DELETE is the default.
PRESERVE | The rows of the table are preserved. Thread reuse capability is not available to any application process or thread that contains, at its most recent COMMIT, an active declared temporary table that was defined with the ON COMMIT PRESERVE ROWS clause.

Example:

Define a declared temporary table with column definitions for an employee number, salary, commission, and bonus.

DECLARE GLOBAL TEMPORARY TABLE SESSION.TEMP_EMP
   (EMPNO   CHAR(6)        NOT NULL,
    SALARY  DECIMAL(9, 2),
    BONUS   DECIMAL(9, 2),
    COMM    DECIMAL(9, 2))
    CCSID EBCDIC
    ON COMMIT PRESERVE ROWS;
Parent topic: SQL Statements


DECLARE STATEMENT

The DECLARE STATEMENT command (embedded SQL only) identifies prepared SQL statements for later use in application programs.
Restriction: This topic applies to Windows environments only.

Invocation

DECLARE STATEMENT is not an executable statement. It can only be embedded in an application language.

Authorization

None required.

Syntax

DECLARE statement-name[,...] STATEMENT

Parameters:

statement-name Names one or more prepared SQL statements to be used in an application program.

Description

This nonexecutable statement is used in application programs to identify statement-name variables that can later be substituted for various kinds of SQL statements.

Example:

The C language example below first declares an SQL statement variable named mystatement. Next the contents of the host variable hostvar (typically the text of an SQL statement assembled in the host application) are placed into mystatement using the PREPARE command:

EXEC SQL
    DECLARE mystatement STATEMENT
;
...

EXEC SQL
    PREPARE mystatement FROM :hostvar
;
...
Parent topic: SQL Statements


DECLARE TABLE

The DECLARE TABLE statement (embedded SQL only) is used for application program documentation and providing the precompiler with information for checking embedded SQL statements.
Restriction: This topic applies to Windows environments only.

Invocation

DECLARE TABLE is not an executable statement. It can only be embedded in an application language.

Authorization

None required.

Syntax

This command is supported only syntactically.

DECLARE {table-name | view-name}
    TABLE (column-name {built-in-data-type | distinct-type-name}
    [NOT NULL]
    [NOT NULL WITH DEFAULT] [,...])

This command is supported only syntactically.

DECLARE {table-name | view-name}
    TABLE (column-name {built-in-data-type | distinct-type-name}
    [NOT NULL]
    [NOT NULL WITH DEFAULT] [,...])

Parameters:

table-name or view-name Is the name of the table or view you want to document. If the table is defined in your application program, the description of the table in the SQL statement in which it is defined (for example, CREATE TABLE or DECLARE GLOBAL TEMPORARY TABLE statement) and the DECLARE TABLE statement must be identical.
column-definition One or more column definitions (separated by commas) can be chosen as specified below:
column-name data-type [NOT NULL]
[NOT NULL WITH DEFAULT]

Description

The XDB Server supports the DECLARE TABLE command syntactically only. The VALIDATE directive can be used to achieve the same functionality when precompiling. Use the Declaration Generator utility to generate declarations for tables and views. Mainframe DB2 users should use the DCLGEN utility.

built-in-data-type

Is the built-in data type of the column. Use one of the built-in data types.

distinct-type-name

Is the distinct type (user-defined data type) of the column. An implicit or explicit schema name qualifies the name.

Parent topic: SQL Statements


DELETE (Positioned)

The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).
Restriction: This topic applies to Windows environments only.

Invocation

DELETE is an executable command that can be issued interactively or embedded in a host language. DELETE can be dynamically prepared. The Positioned DELETE command (explained below) can be used only with embedded SQL.

Authorization

Authorization requirements depend on whether the object identified in the statement is a table or a view. To execute the DELETE command on a table, users must possess either DBADM authority for the database containing the table, DELETE privilege on the table, overall SYSADM authority for the location, or be the owner of the table.

To execute the DELETE command on a view, users must possess the DELETE privilege on the view or have overall SYSADM authority. For more information on view privileges, see CREATE VIEW. If a subselect is specified within the view or table, the user must have the necessary privileges to execute the subselect.

To execute a DELETE at another location, the set of available privileges consists only of those privileges recorded in the system catalog at the location where the DELETE statement is to be executed.

Syntax

DELETE FROM {table-name | view-name}
    [correlation-name]
    WHERE CURRENT OF cursor-name
    [FOR ROW [host-variable | integer-constant] OF ROWSET]

Parameters:

table-name or view-name | Names an object (table or view) from which records are to be deleted. If a view name is identified, the view must be an updatable view since the underlying table will be affected. The named table or view may exist at a location other than the current location, as long as the correct location is either implicitly specified (SET LOCATION TO or CONNECT command precedes the DELETE command) or explicitly specified in the object name (location-name.AuthID.object-name).
correlation-name | Identifies an optional correlation name that then qualifies table or view column references within the search-condition.
search-condition | Determines which records to delete. Can be any valid query search condition, with each column name (other than in a subquery) identifying a column in table-name or view-name. The search condition must not include a subquery that also operates on either table-name or view-name.
cursor-name | Identifies a previously defined, opened, and fetched cursor, which points to the row to be deleted.

Description

Both Searched DELETE and Positioned DELETE are supported -- with the first type of command deleting one or more rows (with the option of including a WHERE clause), and the second type deleting only one row at a time, using the row pointer position within a cursor result table. When the DELETE command is embedded in a host language such as COBOL, C, or PL/I, it can contain host variables.

The Positioned DELETE can only be used in embedded SQL, since it involves the use of a previously defined cursor. When a positioned DELETE is executed, the row that the cursor currently points to is deleted.

When a record is deleted, the XDB Server simply marks the record as deleted. The data are still present in the table. If the Backward Log is set to ON, the ROLLBACK command can remove these delete markers and return the records to their former state. See the SELECT command for information on how to view records marked for deletion.

Index Considerations

If an index exists on a table, deleting records automatically updates the index. This could lead to a performance penalty if many records are deleted because each record deleted will cause the index to be updated. When deleting a large number of records from a table, it is sometimes more efficient to drop the index, delete the records, then re-create the index.

FOREIGN KEY Considerations

When deleting records from a table involved in a FOREIGN KEY constraint, the rule defined for the FOREIGN KEY will be followed. See the ALTER TABLE and CREATE TABLE commands for more information on deleting records containing FOREIGN KEYs.

DELETE vs. TRUNCATE TABLE

When deleting all records from a table, the TRUNCATE TABLE command can save time and system overhead. TRUNCATE TABLE deletes all records in a table without logging the deleted records or maintaining the table indexes. The system will not be able to rollback the deleted records. This command is not allowed on a table containing a primary key, since it may be referenced by another table.

WHERE CURRENT OF

This keyword clause identifies the cursor to be used in a positioned DELETE statement. The cursor-name specified must identify an already declared cursor. When a DELETE statement is executed, the cursor must already be positioned on the row to be deleted. After deleting the row, a FETCH statement should be executed to retrieve the next result table row.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Examples:

A sample DELETE statement appears below:

DELETE FROM partsupp
    WHERE sno = "S1"

This command deletes all the records where the supplier is S1.

The more complex example shown below deletes all suppliers who supply part P4:

DELETE FROM supplier
    WHERE sno IN
    SELECT sno
    FROM partsupp
    WHERE pno = "P4"

If the optional WHERE clause is not included, all records in the table are deleted. After the DELETE command is issued, the table will not contain any active records, but the table still exists and still appears in the directory of active tables. You cannot recover deleted records if DELETE is issued without a WHERE condition. You can reenter new data at any time using either the INSERT command or the SQLWizard data entry facility. For example, the following command removes all of the records from the SUPPLIER table:

DELETE FROM supplier

When the DELETE command is embedded in a host language, it must appear within the "EXEC SQL ... END-EXEC" or "EXEC SQL ...;" delimiters, as required by the XDB Server host language preprocessor. The following COBOL language example shows a positioned DELETE command. It is assumed that the cursor EMPTBL has been declared, opened and fetched to the row desired:

EXEC SQL
    DELETE FROM employee
    WHERE CURRENT OF emptbl;
Parent topic: SQL Statements
Related reference
CREATE VIEW
SELECT
ALTER TABLE
CREATE TABLE
DELETE (Searched)


DELETE (Searched)

The DELETE statement removes any number of records from a table or view. The table or view can be within the current location or any other location with which the XDB Server can establish a connection, provided that the user has privileges in that other location. Deleting a row from a view actually deletes the row from the base table on which the view was created (if it is an updatable view).
Restriction: This topic applies to Windows environments only.

Invocation

DELETE is an executable command that can be issued interactively or embedded in a host language. DELETE can be dynamically prepared.

Authorization

Authorization requirements depend on whether the object identified in the statement is a table or a view. To execute the DELETE command on a table, users must possess either DBADM authority for the database containing the table, DELETE privilege on the table, overall SYSADM authority for the location, or ownership of the table.

To execute the DELETE command on a view, users must possess the DELETE privilege on the view or have overall SYSADM authority. For more information on view privileges, see CREATE VIEW. If a subselect is specified within the view or table, the user must have the necessary privileges to execute the subselect.

To execute a DELETE at another location, the set of available privileges consists only of those privileges recorded in the system catalog at the location where the DELETE statement is to be executed.

The SELECT privilege is required in addition to the DELETE privilege when the option for the SQL standard is set as follows:

  • For static SQL statements, if the SQLRULES (STD) bind option was specified
  • For dynamic SQL statements, if the CURRENT RULES special register is set to STD

Syntax

DELETE FROM {table-name | view-name} [correlation-name]
    [WHERE search-condition]
    [WITH {CS | RR}][QUERYNO integer]

Description

Both Searched DELETE and Positioned DELETE are supported -- with the first type of command deleting one or more rows (with the option of including a WHERE clause), and the second type deleting only one row at a time, using the row pointer position within a cursor result table. When the DELETE command is embedded in a host language such as COBOL, C, or PL/I, it can contain host variables.

The Searched DELETE uses the standard SQL syntax for a DELETE statement, which relies on a WHERE condition to determine the records to be deleted. The WHERE condition is defined in the same way as it would be for a SELECT command. To determine which records a searched DELETE command will delete, first SELECT from the table using the same WHERE condition. See WHERE Clause for more information on searching for records.

When using subselects as search conditions, the subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

DELETE FROM tutorial.tutorial.employee
    WHERE e_no IN
        SELECT e_no FROM debloc.debbie.employee
            WHERE st = "MD";

Valid:

DELETE FROM tutorial.tutorial.employee
    WHERE e_no IN
        SELECT e_no FROM tutorial.debbie.employee
            WHERE st = "MD";
Note:

If no WHERE condition is specified, all records in the table are deleted.

When a record is deleted, the XDB Server simply marks the record as deleted. The data are still present in the table. If the Backward Log is set to ON, the ROLLBACK command can remove these delete markers and return the records to their former state. See the SELECT command for information on how to view records marked for deletion.

Index Considerations

If an index exists on a table, deleting records automatically updates the index. This could lead to a performance penalty if many records are deleted because each record deleted will cause the index to be updated. When deleting a large number of records from a table, it is sometimes more efficient to drop the index, delete the records, then re-create the index.

FOREIGN KEY Considerations

When deleting records from a table involved in a FOREIGN KEY constraint, the rule defined for the FOREIGN KEY will be followed. See the ALTER TABLE and CREATE TABLE commands for more information on deleting records containing FOREIGN KEYs.

DELETE vs. TRUNCATE TABLE

When deleting all records from a table, the TRUNCATE TABLE command can save time and system overhead. TRUNCATE TABLE deletes all records in a table without logging the deleted records or maintaining the table indexes. The system will not be able to rollback the deleted records. This command is not allowed on a table containing a primary key, since it may be referenced by another table.

WHERE

This keyword identifies rows to be deleted in a searched DELETE. If WHERE is omitted, all rows of the table or view named are deleted. The search condition following the WHERE keyword is applied to each row of the named table or view, deleting all rows for which the search condition is true. A subquery with no correlated references will be executed just once. A subquery with a correlated reference will be executed once for each row identified in the WHERE clause.

WITH Clause

Specifies an isolation level with which the statement is executed in Searched DELETE statements. You can override the isolation level of the statement using the new WITH {RR | CS} clause. Because WITH UR only applies to read only operations, you cannot use it on a DELETE statement. The WITH clause overrides the default isolation level only for the statement in which it appears.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Searched DELETE and SQL standard rules

If SQL standard rules are in effect and the search-condition in a searched DELETE contains a reference to a column of the table or view, the privilege set must include at least one of the following:

  • The SELECT privilege on the table or view
  • SYSADM authority

SQL standard rules are in effect as follows:

  • For static SQL statements, if the SQLRULES(STD) bind option was specified
  • For dynamic SQL statements, if the CURRENT RULES special register is set to 'STD

Examples:

A sample DELETE statement appears below:

DELETE FROM partsupp
    WHERE sno = "S1"

This command deletes all the records where the supplier is S1.

The more complex example shown below deletes all suppliers who supply part P4:

DELETE FROM supplier
    WHERE sno IN
        SELECT sno
            FROM partsupp
            WHERE pno = "P4"

If the optional WHERE clause is not included, all records in the table are deleted. After the DELETE command is issued, the table will not contain any active records, but the table still exists and still appears in the directory of active tables. You cannot recover deleted records if DELETE is issued without a WHERE condition. You can reenter new data at any time using either the INSERT command or the SQLWizard data entry facility. For example, the following command removes all of the records from the SUPPLIER table:

DELETE FROM supplier

When the DELETE command is embedded in a host language, it must appear within the "EXEC SQL ... END-EXEC" or "EXEC SQL ...;" delimiters, as required by the XDB Server host language preprocessor. The following COBOL language example shows a searched DELETE command containing a host variable in the WHERE clause:

EXEC SQL
    DELETE FROM employee
    WHERE lname = :ENAME
END-EXEC
Parent topic: SQL Statements
Related reference
CREATE VIEW
SELECT
ALTER TABLE
CREATE TABLE
DELETE (Positioned)
Related information
WHERE Clause Syntax and Description


DESCRIBE

The DESCRIBE statement (embedded SQL only) obtains information about a previously prepared (PREPARE command) SQL statement and places this information inside an SQL Descriptor Area (SQLDA). This information is needed in dynamic SQL queries that utilize a varying-list SELECT statement. A varying-list SELECT statement is a SELECT statement where the number of columns retrieved is not known before runtime. Alternatively, the DESCRIBE statement can provide information about a specified table or view.
Restriction: This topic applies to Windows environments only.

Invocation

DESCRIBE is an executable command that can only be embedded in a host language. DESCRIBE cannot be dynamically prepared.

Authorization

No special privileges are required when describing a prepared statement. However, when describing a table or view, the privileges held by the AuthID owning the application must include either ownership of the table, SELECT, INSERT, UPDATE, or DELETE privilege on the table or view, ALTER or INDEX privilege on the table, DBADM authority over the database containing the object (tables only), or SYSADM or SYSCTRL authority for the location.

See the PREPARE statement description for authorization privileges required to prepare a command.

Syntax

DESCRIBE {statement-name | TABLE host-variable}
    INTO descriptor-name [USING {NAMES | LABELS | ANY | BOTH}]

Parameters:

statement-name | Identifies an SQL statement already prepared by an application process at the current location.
host-variable | The combination of the keyword TABLE followed by host-variable, identifies a table or view. The name must not identify an auxiliary table
descriptor-name | preceded by the keyword INTO, names an SQL Descriptor Area (SQLDA) variable.

Description

You may have a uniquely named SQLDA defined for every cursor utilized in an application process. When the DESCRIBE statement is applied to a prepared query statement, the information returned to the specified SQLDA describes the columns of the result table (for that cursor). When a table or view is named in the DESCRIBE statement, the information returned in the SQLDA defines the columns in the table or view.

The SQLDA must be allocated before the DESCRIBE statement is executed. Once allocated, the SQLDA consists of the SQLDAID, SQLDABC, SQLN, and SQLD fields followed by the SQLVAR array structure (containing one or more occurrences). The number of elements within the SQLVAR must be equal to or greater than the number of columns in the described table. For more details on the SQLDA, see XDB Server SQL Descriptor Area (SQLDA).

Before executing the DESCRIBE statement, the SQLN field in the SQLDA must be set to indicate the number of SQLVAR occurrences in the SQLDA (this value is not changed by the XDB Server). Once SQLN is determined, performance can be improved by resetting this value after the DESCRIBE statement is first executed. With the exception of SQLN, all other SQLDA fields are set by the XDB Server software or are ignored, as indicated in the field descriptions below. Please note that the following descriptions do not necessarily apply to SQLDA usage with PREPARE, EXECUTE, OPEN, and FETCH statements:

  • SQLDAID is set to "SQLDA" by the XDB Server software.
  • SQLDABC is the length of the SQLDA in bytes, and equals SQLN*44+16 (as set by the XDB Server software).
  • SQLD is set to either the number of columns in the object being described or to zero (if DESCRIBE is applied to a nonquery statement). In order for the SQLDA to be large enough for the information requested, the returned value of SQLD must be less than or equal to the value of SQLN. If SQLD is larger than SQLN, no information is returned from the query into the SQLDA.
  • SQLVAR array values are assigned for each column in the object being described, such that the first array value describes the first column in the object, the second array value describes the second column, etc.
  • SQLTYPE is a code indicating the data type of the column and whether or not the column can contain null values.
  • SQLLEN is the length of the result column, which varies according to the data type of the column.
  • SQLDATA stores a dynamic memory address for the column.
  • SQLIND stores an indicator variable address for nullable columns.
  • SQLNAME is the unqualified name of the column.

Allocating SQLDA

To aid in the allocation of SQLDA memory space, first execute a DESCRIBE statement into an SQL Descriptor Area where the SQLN variable is deliberately set to zero. The value returned for the SQLD variable will equal the number of columns that need to be processed in the select list (which is the required value of SQLN). Use this returned value of SQLD to allocate another SQLDA, with the SQLN value preset to at least SQLD (or more) occurrences of the SQLVAR array. Execute the DESCRIBE statement again specifying this new SQLDA.

  • First technique

    Allocate an SQLDA with enough occurrences of SQLVAR to accommodate any select list that the application will have to process. At the extreme, the number of SQLVARs could equal three times the maximum number of columns allowed in a result table. After the SQLDA is allocated, the application can use the SQLDA repeatedly.

    This technique uses a large amount of storage that is never deallocated, even when most of this storage is not used for a particular select list.

  • Second technique

    Repeat the following for every processed select list:

    1. Execute a DESCRIBE statement with an SQLDA that has no occurrences of SQLVAR; that is, an SQLDA for which SQLN is zero.
    2. Allocate a new SQLDA with enough occurrences of SQLVAR. Use the values that are returned in SQLD and SQLCODE to determine the number of SQLVAR entries that are needed. The value of SQLD is the number of columns in the result table, which is either the required number of occurrences of SQLVAR or a fraction of the required number If the SQLCODE is +236, +237, +238, or +239, the number of SQLVAR entries that is needed is two or three times the value in SQLD, depending on whether USING BOTH was specified. Set SQLN to reflect the number of SQLVAR entries that have been allocated.
    3. Execute the DESCRIBE statement again, using the new SQLDA.

    This technique allows better storage management than the first technique, but it doubles the number of DESCRIBE statements.

  • Third technique

    Allocate an SQLDA that is large enough to handle most (hopefully, all) select lists but is also reasonably small. If an execution of DESCRIBE fails because SQLDA is too small, allocate a larger SQLDA and execute the DESCRIBE statement again.

    For the new larger SQLDA, use the values that are returned in SQLD and SQLCODE from the failing DESCRIBE statement to calculate the number of occurrences of SQLVAR that are needed, as described in technique two. Remember to check for SQLCODEs +236, +237, +238, and +239, which indicate whether extended SQLVAR entries are needed because the data includes LOBs or distinct types.

    This third technique is a compromise between the first two techniques. Its effectiveness depends on a good choice of size for the original SQLDA.

SQLDAID

XDB sets the first 6 bytes to 'SQLDA ' (5 letters followed by the space character) and the eighth byte to a space character. The seventh byte is set to indicate the number of SQLVAR entries that are needed to describe each column of the result table as follows:

space

The value of space occurs when:

  • USING BOTH was not specified and the columns being described do not include LOBs or distinct types. Each column only needs one SQLVAR entry. If the SQL standard option is yes, XDB sets SQLCODE to warning code +236. Otherwise, SQLCODE is zero.
  • USING BOTH was specified and the columns being described do not include LOBs or distinct types. Each column needs two SQLVAR entries. XDB sets SQLD to two times the number of columns of the result table. The second set of SQLVARs is used for the labels.

2

Each column needs two SQLVAR entries. Two entries per column are required when:

  • USING BOTH was not specified and the columns being described include LOBs or distinct types or both. XDB sets the second set of SQLVAR entries with information for the LOBs or distinct types being described.
  • USING BOTH was specified and the columns include LOBs but not distinct types. XDB sets the second set of SQLVAR entries with information for the LOBs and labels for the columns being described.

3

Each column needs three SQLVAR entries. Three entries are required only when USING BOTH is specified and the columns being described include distinct types. The presence of LOB data does not matter. It is the distinct types and not the LOBs that cause the need for three SQLVAR entries per column when labels are also requested. XDB sets the second set of SQLVAR entries with information for the distinct types (and LOBs, if any) and the third set of SQLVAR entries with the labels of the columns being described.

SQLD

If the prepared statement is a query, XDB sets the value to the number of columns in the object being described (the value is actually twice the number of columns in the case where USING BOTH was specified and the result table does not include LOBs or distinct types).

Otherwise, if the statement is not a query, XDB sets the value to 0.

SQLVAR

An array of field description information for the column being described. There are two types of SQLVAR entries--the base SQLVAR and the extended SQLVAR.

If the value of SQLD is 0, or is greater than the value of SQLN, no values are assigned to any occurrences of SQLVAR. If the value of SQLN was set so that there are enough SQLVAR occurrences to describe the specified columns (columns with LOBs or distinct types and a request for labels increase the number of SQLVAR entries that are needed), the values are assigned to the first n occurrences of SQLVAR so that the first occurrence of SQLVAR contains a description of the first column, the second occurrence of SQLVAR contains a description of the second column, and so on. This first set of SQLVAR entries are referred to as base SQLVAR entries. Each column always has a base SQLVAR entry.

If the DESCRIBE statement included the USING BOTH clause, or the columns being described include LOBs or distinct types, additional SQLVAR entries are needed. These additional SQLVAR entries are referred to as the extended SQLVAR entries. There can be up to two sets of extended SQLVAR entries for each column.

The base SQLVAR

SQLTYPE | A code that indicates the data type of the column and whether the column can contain null values.
SQLLEN | A length value depending on the data type of the result columns. SQLLEN is 0 for LOB data types.
SQLDATA | The CCSID of a string column.
SQLIND | Reserved.
SQLNAME | The unqualified name or label of the column, depending on the value of USING (NAMES, LABELS, ANY, or BOTH). The field is a string of length 0 if the column does not have a name or label.

The extended SQLVAR

SQLLONGLEN | The length attribute of a BLOB, CLOB, or DBCLOB column.
* | Reserved.
SQLDATALEN | Not Used.
SQLDATATYPE-NAME | For a distinct type, the fully qualified distinct type name. Otherwise, the value is the fully qualified name of the built-in data type. For a label, the label for the column.

USING

Indicates what value to assign to each SQLNAME variable in the SQLDA. If the requested value does not exist, SQLNAME is set to a length of 0.

NAMES | Assigns the name of the column. This is the default.
LABELS | Assigns the label of the column. (Column labels are defined by the LABEL ON statement.)
ANY | Assigns the column label, and if the column has no label, the column name.
BOTH | Assigns both the label and name of the column. In this case, two or three occurrences of SQLVAR per column, depending on whether the result set contains distinct types, are needed to accommodate the additional information. To specify this expansion of the SQLVAR array, set SQLN to 2¦n or 3¦n, where n is the number of columns in the object being described. For each of the columns, the first n occurrences of SQLVAR, which are the base SQLVAR entries, contain the column names. Either the second or third n occurrences of SQLVAR, which are the extended SQLVAR entries, contain the column labels. If there are no distinct types, the labels are returned in the second set of SQLVAR entries. Otherwise, the labels are returned in the third set of SQLVAR entries.

For a declared temporary table, the name of the column is assigned regardless of the value specified in the USING clause because declared temporary tables cannot have labels.

Performance considerations

Although XDB does not change the value of SQLN, you might want to reset this value after the DESCRIBE statement is executed. If the contents of SQLDA from the DESCRIBE statement is used in a later FETCH statement, set SQLN to n (where n is the number of columns of the result table) before executing the FETCH statement.

Example:

EXEC SQL
    DESCRIBE getcust INTO mydesc
END-EXEC

where mydesc is a defined SQLDA in working storage and getcust is a previously prepared command.

Parent topic: SQL Statements


DESCRIBE CURSOR

The DESCRIBE CURSOR statement gets information about the result set that is associated with the cursor. The information, such as column information, is put into a descriptor. Use DESCRIBE CURSOR for result set cursors from stored procedures. The cursor must be defined with the ALLOCATE CURSOR statement.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program only. It is an executable statement that cannot be dynamically prepared.

Authorization

No authorization is required for this statement.

Syntax

DESCRIBE CURSOR {cursor-name | host-variable}
    INTO descriptor-name

Parameters:

cursor- name | Indentifies a cursor by the specified cursor name. The name must identify a cursor that has already been allocated in the source program.
host-variable | Indentifies a cursor by the cursor name contained in the host variable. The name must identify a cursor that has already been allocated in the source program.
descriptor-name | Identifies an SQL descriptor area (SQLDA). The information returned in the SQLDA describes the columns in the result set associated with the named cursor.
Note:

For the statement to execute successfully, the application program must be connected to the site at which the stored procedure was executed.

Parent topic: SQL Statements


DESCRIBE INPUT Example

Restriction: This topic applies to Windows environments only.

Execute a DESCRIBE INPUT statement with an SQLDA that has enough SQLVAR occurrences to describe any number of input parameters a prepared statement might have. Assume that five parameter markers at most will need to be described and that the input data does not contain LOBs.

/* STMT1_STR contains INSERT statement with VALUES clause */

EXEC SQL PREPARE STMT1_NAME FROM :STMT1_STR;

/* code to set SQLN to 5 and to allocate the SQLDA */

EXEC SQL DESCRIBE INPUT STMT1_NAME INTO :SQLDA;
Parent topic: SQL Statements


DESCRIBE PROCEDURE

The DESCRIBE PROCEDURE statement gets information about the result sets returned by a stored procedure. The information, such as the number of result sets, is put into a descriptor.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program only. It is an executable statement that cannot be dynamically prepared.

Authorization

No authorization is required for this statement.

Syntax

DESCRIBE PROCEDURE {procedure-name | host-variable}
    INTO descriptor-name

Parameters:

procedure-name | Identifies the stored procedure to describe by the specified procedure name.
host-variable | Identifies the stored procedure to describe by the procedure name contained in the host variable.
descriptor-name | Identifies an SQL descriptor area (SQLDA). The information returned in the SQLDA describes the result sets returned by the stored procedure. Considerations for allocating and initializing the SQLDA are similar to those for DESCRIBE TABLE.

Description

When the DESCRIBE PROCEDURE statement is executed, the procedure name or specification must identify a stored procedure that the requestor has already invoked by using a CALL statement.

A procedure name is a qualified or unqualified name. Each part of the name is a long SQL identifier that must be composed of SBCS characters:

  • A fully qualified procedure name is a three-part name. The first part is a location name that identifies the DBMS at which the procedure is stored. The next two parts identify the stored procedure. The last part is a long identifier that contains the name of the stored procedure. A period must separate each of the parts.
  • An implicitly qualified procedure name is a two-part name that is qualified by the location name of the current server. The name and its implicit qualifier identifies a stored procedure. A period must separate the two parts. The first part identifies the stored procedure at the server. The meaning of the first part depends on the application server.
  • An unqualified procedure name is a one-part name with two implicit qualifiers. The first implicit qualifier is the location name of the current server. The second implicit qualifier identifies the stored procedure at the server. The meaning of the second implicit qualifier depends on the application server (for MVS, the qualifier is SYSPROC). The name and its implicit qualifiers identifies a stored procedure.

If a host variable is used:

  • It must be a character string variable with a length attribute that is not greater than 254.
  • It must be preceded by a colon and must not be followed by an indicator variable.
  • The value of the host variable is a specification that depends on the application server. Regardless of the application server, the specification must:
    • Be left justified within the host variable
    • Not contain embedded blanks
    • Be padded on the right with blanks if its length is less than that of the host variable

The procedure name in the DESCRIBE PROCEDURE statement must be specified the same way that it was specified on the CALL statement. For example, if a two-part name was specified on the CALL statement, you must use a two-part name in the DESCRIBE PROCEDURE statement. However, there is one condition under which the names do not have to match. If the CALL statement was made with a three-part name and the current server is the same as the location in the three-part name, you can omit the location name and specify a two-part name.

Example:

The statements in the following examples are assumed to be in PL/I programs.

Place information about the result sets returned by stored procedure P1 into the descriptor named by SQLDA1. Assume that the stored procedure is called with a one-part name from current server SITE2.

EXEC SQL CONNECT TO SITE2;
EXEC SQL CALL P1;
EXEC SQL DESCRIBE PROCEDURE P1 INTO :SQLDA1;
Parent topic: SQL Statements


DISABLE LOGIN

Use this command to prevent all users, except those with SYSADM privileges, from logging on to the XDB Server. This command does not affect users who are already logged on.
Restriction: This topic applies to Windows environments only.

This command is useful for removing the XDB Server from service for routine maintenance, upgrades or repairs.

To make the server available again, use the ENABLE LOGIN command.

Note:

This command functions only when server security is on.

Invocation

This command can be embedded in a host language or executed interactively .

Authorization

Any of the following:

  • A super user
  • A user with SYSADM privileges

Syntax

DISABLE LOGIN
Parent topic: SQL Statements


DROP

The DROP statement removes (erases) an object from the current location. When an object is deleted, its description is also deleted from the system catalog at the current location.
Restriction: This topic applies to Windows environments only.
Note:

With the exception of removed storage groups, any objects directly or indirectly dependent on the deleted object are also removed.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The XDB Server checks to ensure that users dropping different kinds of objects possess the following privileges as appropriate:

  • To drop a table, table space, or index, users must possess either DBADM for the database, SYSADM or SYSCTRL authority for the location, or be the owner of the object.
  • To drop an alias, storage group or view, users must possess either SYSADM or SYSCTRL authority or be the owner of the object.
  • To drop a database, users must possess either SYSADM or SYSCTRL authority for the location, DBADM or DBCTRL authority for the database or the DROP privilege on the database.
  • To drop a synonym, users must be owners of the synonym.

To drop a distinct type, stored procedure, trigger, or user-defined function, users must possess ownership of the object, the DROPIN privilege for the schema or all schemas, or SYSADM or SYSCTRL authority.

The DROP statement has access to the same privileges held by the combined AuthIDs of the application process.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

DROP
{
    ALIAS alias-name
    | DATABASE database-name
    | DISTINCT TYPE distinct-type-name RESTRICT
    | FUNCTION function-name (parameter-type[,...]) RESTRICT
    | INDEX index-name
    | SEQUENCE sequence-name
    | STOGROUP stogroup-name
    | LOCATION location-name
    | SYNONYM synonym
    | TABLE table-name
    | TABLESPACE [database-name.]tablespace-name
    | VIEW view-name
    | {PACKAGE | PROGRAM} collection-id.package.id[[VERSION] version-id]
    | PROCEDURE procedure-name RESTRICT
    | SPECIFIC FUNCTION specific-name RESTRICT
    | TRIGGER trigger-name
}

parameter-type:

{data-type [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] |
REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] |
    {CHARACTER | CHAR} VARYING (integer) |
    VARCHAR (integer) } [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{{CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

Parameters:

alias-name | Identifies the alias to be dropped. The name must identify an alias that exists at the current server. Dropping an alias has no effect on any view, materialized query table, or synonym that was defined using the alias.
database-name | Identifies the database to be dropped.
location-name | Identifies a user-created location to be dropped.
index-name | Identifies the index to be dropped.
stogroup-name | Identifies the storage group to be dropped.
synonym | Identifies the synonym to be dropped.
table-name | Identifies the table to be dropped.
[database-name.]tablespace-name | Identifies the table space (optionally qualified with a database name) to be dropped.
view-name | Identifies the view to be dropped.

Description

DELETE command rules do not apply when using the DROP command. When dropping a table, for instance, parent and dependent table relationships are not a consideration.

If the user-defined storage group for a database is dropped, then that database no longer has an active default storage group. A USING clause must be specified when creating future table space or indexes within that database. The USING clause must be specified until either another storage group is created with the same name (using CREATE STOGROUP) or another default storage group is designated for the database (using ALTER DATABASE).

ALIAS

This keyword indicates that an alias is to be dropped. The alias must exist at the current location. Dropping an alias does not affect any view or synonym previously defined using the dropped alias.

DATABASE

The keyword indicates that a database is to be dropped. This database must not be a system database (DSNDB04, DSNDB06, DSNDDF, XDBACF, etc.), and must exist at the current location. The database, along with all table spaces, tables and indexes associated with the database are dropped.

DISTINCT TYPE distinct-type-name RESTRICT

Identifies the distinct type to be dropped. The name must identify a distinct type that exists at the current server. The default keyword RESTRICT indicates that the distinct type is not dropped if any of the following dependencies exist:

  • The definition of a column of a table uses the distinct type.
  • The definition of an input or result parameter of a user-defined function uses the distinct type.
  • The definition of a parameter of a stored procedure uses the distinct type.
  • A sequence exists for which the data type of the sequence is the distinct type.

Whenever a distinct type is dropped, all privileges on the distinct type are also dropped. In addition, the cast functions that were generated when the distinct type was created and the privileges on those cast functions are also dropped.

FUNCTION

Identifies the user-defined function to be dropped. The name must identify a function that has been defined with the CREATE FUNCTION statement at the current server. The name must not identify a cast function that was generated for a distinct type or a function that is in the SYSIBM schema. The required keyword RESTRICT enforces the rule that the function is not dropped if any of the following dependencies exist:

  • Another function is sourced on the function.
  • A view uses the function.
  • A trigger package uses the function.

Whenever a function is dropped, all privileges on the user-defined function are also dropped. Any plans or packages that are dependent on the function dropped are made inoperative.

You can identify the particular function to be dropped by its name, function signature, or specific name. If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name RESTRICT | Identifies the function by its name. There must be exactly one function with function-name in the implicitly or explicitly specified schema; otherwise, an error occurs.
FUNCTION function-name (parameter-type,...) RESTRICT | Provides the function signature, which uniquely identifies the function. There must be exactly one function with the function signature in the implicitly or explicitly specified schema; otherwise, an error occurs. If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to uniquely identify the function. Instead, use one of the other syntax variations to identify the function with its function name, if unique, or its specific name.
function-name | Identifies the name of the function.
(parameter-type,...) | Identifies the parameters of the function.

If an unqualified distinct type name is specified, XDB searches the SQL path to resolve the schema name for the distinct type.

The data types of the parameters must match the data types that were specified on the CREATE FUNCTION statement in the corresponding position. The number of data types and the logical concatenation of the data types are used to identify the function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that XDB ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.
  • The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.
  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:
    CHAR | CHAR(1)
    GRAPHIC | GRAPHIC(1)
    DECIMAL | DECIMAL(5,0)
    FLOAT | DOUBLE (length of 8)

The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that XDB ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name RESTRICT Identifies the function by its specific name, which was explicitly specified or implicitly created when the function was created. There must be exactly one function with specific-name in the implicitly or explicitly specified schema.

INDEX

The name must identify a user-defined index that exists at the current server but must not identify a populated index on an auxiliary table. A populated index on an auxiliary table can only be dropped by dropping the base table.

If the index that is dropped was created by specifying the ENDING AT clause to define partition boundaries, the table is converted to use table-controlled partitioning. The high limit key for the last partition is set to the highest possible value for ascending key columns or the lowest possible value for descending key columns.

Whenever an index is directly or indirectly dropped, its index space is also dropped. The name of a dropped index space cannot be reused until a commit operation is performed.

If the index is a unique index used to enforce a unique constraint (primary or unique key), the unique constraint must be dropped before the index can be dropped. In addition, if a unique constraint supports a referential constraint, the index cannot be dropped unless the referential constraint is dropped.

However, a unique index (for a unique key only) can be dropped without first dropping the unique key constraint if the unique key was created in a release of DB2 before Version 7 and if the unique key constraint has no associated referential constraints.

If a unique index is dropped and that index was defined on a ROWID column that is defined as GENERATED BY DEFAULT, the table can still be used, but rows cannot be inserted into that table.

If an empty index on an auxiliary table is dropped, the base table is marked incomplete.

LOCATION

This keyword indicates that a user-created location is to be dropped. All database and other objects stored within the location are also dropped. INSTALL authority is needed to drop a location. When dropping a location, not all files are cleaned up. Some files may be left in the directory that contained the location. If you attempt to create another location in the same directory, these files will be overwritten. If you wish to clean up your hard drive, delete these files -- just make sure that you are deleting files from an already deleted location.

Note:

You cannot drop a location that was created in the same session. You must first exit the interactive SQL session during which you created the location, and then start another interactive SQL session to drop the newly created location.

PROCEDURE procedure-name RESTRICT

Identifies the stored procedure to be dropped. The name must identify a stored procedure that has been defined with the CREATE PROCEDURE statement at the current server. The required keyword RESTRICT prevents the procedure from being dropped if a trigger definition contains a CALL statement with the name of the procedure.

When a procedure is directly or indirectly dropped, all privileges on the procedure are also dropped. In addition, any plans or packages that are dependent on the procedure are made inoperative.

SEQUENCE sequence-name

Identifies the sequence to be dropped. The name must identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs.

sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column. Sequences generated by the system for identity columns cannot be dropped with the DROP SEQUENCE statement. A sequence object for an identity column is implicitly dropped when the table containing the identify column is dropped.

The default keyword RESTRICT indicates that the sequence is not dropped if any of the following dependencies exist:

  • A trigger that uses the sequence in a NEXT VALUE or PREVIOUS VALUE expression exists.
  • An inline SQL function that uses the sequences in a NEXT VALUE or PREVIOUS VALUE expression exists.

Whenever a sequence is dropped, all privileges on the sequence are also dropped, and the plans and packages that refer to the sequence are invalidated. Dropping a sequence, even if the drop process is rolled back, results in the loss of the still-unassigned cache values for the sequence.

STOGROUP

This keyword indicates that a stogroup is to be dropped. The storage group must exist at the current location and must not be the default storage group (SYSDEFLT) or a storage group still used by any table space or index space. Objects defined within a stogroup are not automatically dropped when the stogroup is dropped. Users must first drop the individual objects in the stogroup or alter the objects to utilize a different stogroup. An error occurs when attempting to drop a stogroup being used by a table space.

SYNONYM

This keyword indicates that a synonym is to be dropped. In a dynamic DROP SYNONYM statement, the synonym identified must be owned by the CURRENT SQLID. Dropping a synonym does not affect any view or alias previously defined using the synonym. A user with SYSADM privileges can drop synonyms owned by other users.

Dropping a synonym has no effect on any view, materialized query table, or alias that was defined using the synonym, nor does it invalidate any plans or packages that use such views, materialized query tables, or aliases.

TABLE

This keyword indicates that a table is to be dropped. The table must exist at the current location and must not be a system catalog table. When a table is dropped (either directly or indirectly), all privileges on the table are dropped. Additionally, all parent or dependent referential constraints built on the table, all synonyms, views, and indexes defined on the table are also dropped.

A table in a partitioned table space can only be dropped by dropping the table space. A populated auxiliary table can only be dropped by dropping the associated base table.

Whenever a table is directly or indirectly dropped, all materialized query tables defined on the table are also dropped. Whenever a materialized query table is directly or indirectly dropped, all privileges on the materialized query table and all synonyms, views, and indexes that are defined on the materialized query table are also dropped. Any alias defined on the materialized query table is not dropped. Any plans or packages that are dependent on the dropped materialized query table are marked invalid.

If a table with LOB columns is dropped, the auxiliary tables associated with the table and the indexes on the auxiliary tables are also dropped. Any LOB table spaces that were implicitly created for the auxiliary tables are also dropped.

If an empty auxiliary table is dropped, the definition of the base table is marked incomplete.

If the table has a security label column, the primary authorization ID of the DROP statement must have a valid security label, and the RACF SECLABEL class must be active.

TABLESPACE

This keyword indicates that a table space is to be dropped. All tables in the dropped table space are also dropped.

The table space must exist at the current location (and must not be in the DSNDB06 database). Table spaces that were created implicitly cannot be dropped. If a database name qualifier is not included, than the default DSNDB04 database for that location is implicitly specified.

A table space in a TEMP database can be dropped only if it does not contain an active declared temporary table. A LOB table space can be dropped only if it does not contain an auxiliary table.

Whenever a base table space that contains tables with LOB columns is dropped, all the auxiliary tables and indexes on those auxiliary tables that are associated with the base table space are also dropped.

TRIGGER trigger-name

Identifies the trigger to be dropped. The name must identify a trigger that exists at the current server.

Whenever a trigger is directly or indirectly dropped, all privileges on the trigger are also dropped and the associated trigger package is freed. The name of that trigger package is the same as the trigger name and the collection ID is the schema name.

VIEW

This keyword indicates that a view is to be dropped. The name must identify a view that exists at the current server.

Whenever a view is directly or indirectly dropped, all privileges on the view and all synonyms and views that are defined on the view are also dropped. Whenever a view is directly or indirectly dropped, all materialized query tables defined on the view are also dropped.

Dependencies when dropping objects

Whenever an object is directly or indirectly dropped, other objects that depend on the dropped object might also be dropped. (The catalog stores information about the dependencies of objects on each other.) The following semantics determine what happens to a dependent object when the object that it depends on (the underlying object) is dropped:

Cascade (D) | Dropping the underlying object causes the dependent object to be dropped. However, if the dependent object cannot be dropped because it has a restrict dependency on another object, the drop of the underlying object fails.
Restrict (R) | The underlying object cannot be dropped if a dependent object exists.
Inoperative (O) | Dropping the underlying object causes the dependent object to become inoperative.
Invalidation (V) | Dropping the underlying object causes the dependent object to become invalidated.

Example:

The statements in the following examples are assumed to be in PL/I programs.

Place information about the result sets returned by stored procedure P1 into the descriptor named by SQLDA1. Assume that the stored procedure is called with a one-part name from current server SITE2.

EXEC SQL CONNECT TO SITE2;
EXEC SQL CALL P1;
EXEC SQL DESCRIBE PROCEDURE P1 INTO :SQLDA1;
Parent topic: SQL Statements


ENABLE LOGIN

Use this command to return a server to service after it has been taken out of service with the DISABLE LOGIN command.
Restriction: This topic applies to Windows environments only.
Note:

This command functions only when server security is on.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSADM privileges

Syntax

ENABLE LOGIN
Parent topic: SQL Statements


END DECLARE SECTION

The END DECLARE SECTION statement (embedded SQL only) marks the end of a host variable declaration block in an application program.
Restriction: This topic applies to Windows environments only.

Invocation

END DECLARE SECTION is not an executable statement. It can only be embedded in a host language.

Authorization

No special authorization is required.

Syntax

END DECLARE SECTION

Description

END DECLARE SECTION may be used in an application program to mark the end of the section of code where host variables are declared. If an END DECLARE SECTION is used, the host variable declaration section must begin with the BEGIN DECLARE SECTION statement.

When programming in C, or when the DECLARE or ANSI COBOL preprocessor directives are used, BEGIN and END DECLARE SECTION commands must surround the declarations for all host variables, creating host variable declaration blocks. The host variable declaration blocks can appear anywhere the host language allows variable declarations, but they cannot be nested.

Example:

EXEC SQL BEGIN DECLARE SECTION;
    short in cust_num = 28;
    char name[30];
EXEC SQL END DECLARE SECTION;
Parent topic: SQL Statements


END DECLARE SECTION Example

Restriction: This topic applies to Windows environments only.
EXEC SQL BEGIN DECLARE SECTION;
    short in cust_num = 28;
    char name[30];
EXEC SQL END DECLARE SECTION;
Parent topic: SQL Statements


EXECUTE

The EXECUTE command (embedded SQL only) executes a previously prepared nonquery statement. To prepare and execute in one step, see the EXECUTE IMMEDIATE command.
Restriction: This topic applies to Windows environments only.

Invocation

EXECUTE is an executable command that can only be embedded in a host language. EXECUTE cannot be dynamically prepared.

Authorization

The user must have the authority to use the previously prepared command.

Syntax

EXECUTE statement-name
    [USING {host-variable[,...] |
    DESCRIPTOR descriptor-name} |
    multiple-row-insert]

multiple-row-insert

USING {{host-variable-array | host-variable} [,...]}
   | DESCRIPTOR descriptor-name}
   [FOR {host-variable | integer-constant} ROWS]

Parameters:

statement-name | Identifies a previously prepared nonquery statement to be executed.
host-variable | Identifies a variable described in the application program in accordance with the rules for declaring host variables in the application language.
descriptor-name | Identifies an SQLDA containing a valid description of the host variables to be inserted into the prepared statement during execution.

Description

The EXECUTE command is always used in conjunction with the PREPARE statement, since the main argument for EXECUTE is a previously prepared SQL statement. The PREPARE statement tells the XDB Server about the statement to be executed, while the EXECUTE statement executes that statement, substituting host variable values where specified.

USING

This optional keyword precedes a list of host variables whose values are substituted for the parameter markers (question marks) in the prepared statement. If the prepared statement includes parameter markers, the USING clause must be included in the EXECUTE statement.

The total number of host variables specified must equal the total number of parameter markers in the prepared statement. The order of host variables specified determines their order of substitution into the prepared statement -- with the first variable substituting for the first parameter marker in the prepared statement, etc.

DESCRIPTOR

This keyword indicator precedes a valid SQL Descriptor Area (SQLDA) name. The total number of host variables (as stored in SQLD) must match the total number of parameter markers in the prepared statement. The length of the SQLDA (as stored in SQLDABC) must be sufficient to accommodate all host variables. As with ordinary host variables, there is an ordered one-to-one correspondence between each host variable described in the SQLDA, and the parameter markers inside the prepared statement.

The SQLDA must have enough storage to contain all SQLVAR occurrences.

Parameter Marker Replacement

Before the prepared statement is executed, each parameter marker in the prepared statement string is essentially replaced by a corresponding host variable from the application. This replacement operation transfers the value of the host variable (source) to the corresponding parameter marker (target) within the prepared SQL statement string. The attribute of each host variable -- once transferred into its new "target position" within the SQL statement string -- depends on the original location (and role) of the replaced parameter marker.

Example:

In COBOL, host-variables are data structures defined in working storage. In the following example, we PREPARE inscust and substitute the values of the host variables c_no and company.

EXEC SQL
    PREPARE inscust
        FROM
            INSERT INTO customer(c_no, company) VALUES(?, ?)
END-EXEC
EXEC SQL
    EXECUTE inscust USING :CNO, :CNAME
END-EXEC
Parent topic: SQL Statements
Related information
EXECUTE IMMEDIATE


EXECUTE IMMEDIATE

The EXECUTE IMMEDIATE statement (embedded SQL only) prepares an executable statement from a character string and then immediately executes the statement.
Restriction: This topic applies to Windows environments only.

Invocation

EXECUTE IMMEDIATE is an executable command that can only be embedded in a host language. EXECUTE IMMEDIATE cannot be dynamically prepared.

Authorization

The authorization required for EXECUTE IMMEDIATE conforms exactly with whatever authorization is needed to dynamically prepare the SQL statement indicated in the statement string argument. Consult individual SQL command descriptions in this reference for authorization requirements.

Syntax

EXECUTE IMMEDIATE
    {string-expression | host-variable}

Parameters:

string-expression | A delimited character string that can contain any valid SQL command except CLOSE, DESCRIBE, EXECUTE, EXECUTE IMMEDIATE, FETCH, INCLUDE, OPEN, PREPARE, WHENEVER, or SELECT.
host-variable | Identifies a variable defined in working storage (according to the rules for declaring character string variables in the host language) that contains a valid string expression (statement string).

Description

The EXECUTE IMMEDIATE command prepares and executes non-SELECT SQL commands within a statement string. You should check the syntax of the SQL statement you plan to use before placing that statement into an EXECUTE IMMEDIATE command. This check can be performed with SQLWizard.

The statement string cannot contain parameter markers (question marks) or references to host variables. The statement cannot begin with EXEC SQL or end with END-EXEC (or a semicolon). If the SQL command appearing in the statement string is invalid, an error condition is reported to the SQLCA.

The statement string must be one of the following SQL statements:

ALTER | RENAME
COMMENT ON | REVOKE
COMMIT | ROLLBACK
CREATE | SET CURRENT DEGREE
DELETE | SET CURRENT LOCALE LC_CTYPE
DROP | SET CURRENT OPTIMIZATION HINT
EXPLAIN | SET CURRENT PATH
GRANT | SET CURRENT PRECISION
INSERT | SET CURRENT RULES
LABEL ON | SET CURRENT SQLID
LOCK TABLE | UPDATE

Examples:

Host variables cannot be used in the string expressions.

EXEC SQL
    EXECUTE IMMEDIATE
    'DELETE FROM employee WHERE fname = "Elvis"'
END-EXEC

EXEC SQL
    EXECUTE IMMEDIATE
        'UPDATE employee
    SET fname = "Elvis"
    WHERE e_no = 1'
END-EXEC

Another example of EXECUTE IMMEDIATE embedded in COBOL appears below:

MOVE 'UPDATE employee SET fname = "Elvis"
    WHERE e_no = 1'
    TO exstr

EXEC SQL
    EXECUTE IMMEDIATE :exstr
END-EXEC
Parent topic: SQL Statements


EXPLAIN

The EXPLAIN statement uses the optimizer to acquire access path selection information about SELECT, INSERT (and the searched form of UPDATE or DELETE) statements. This information is placed by the XDB Server into a table named PLAN_TABLE. The XDB Server creates this table automatically if it has not already been created by the user.
Restriction: This topic applies to Windows environments only.

Invocation

EXPLAIN is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

The authorization privileges needed for an EXPLAIN statement are the same privileges required to execute the SQL statement for which you are requesting explanation.

If the EXPLAIN statement is embedded in an application program, the authorization rules that apply are those defined for embedding the specified SQL statement in an application program. In addition, the authorization ID of the owner of the plan or package must also have one of the following characteristics:

  • Be the owner of a plan table named PLAN_TABLE
  • Have an alias on a plan table named owner.PLAN_TABLE and have SELECT and INSERT privileges on the table

If the EXPLAIN statement is dynamically prepared, the authorization rules that apply are those defined for dynamically preparing the specified SQL statement. In addition, the SQL authorization ID of the process must also have one of the following characteristics:

  • Be the owner of a plan table named PLAN_TABLE
  • Have an alias on a plan table named owner.PLAN_TABLE and have SELECT and INSERT privileges on the table.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

EXPLAIN { {PLAN | ALL} [SET QUERYNO=integer]
    FOR explainable-sql-statement
    | STMTCACHE {STMTID {id-host-variable|integer-constant} |
                 STMTTOKEN {token-host-variable|string-constant}} }

Parameters:

integer Preceded by the keywords SET QUERYNO=, specifies an integer to be inserted into the QUERYNO column of the plan_table.
explainable-sql-statement Preceded by the keyword FOR, specifies the SQL statement for which information is returned to the plan table. Only SELECT and INSERT statements or the searched form of an UPDATE or DELETE statement, can be the SQL statement in an EXPLAIN command. The statement must not be a statement-name or a host-variable, and must refer to objects at the current location.

explainable-sql-statement must not contain a QUERYNO clause. To specify the value of the QUERYNO column in plan table for the statement being explained, use the SET QUERYNO = clause of the EXPLAIN statement.

If embedded in an application program, the EXPLAIN statement can contain host variable references. These host variables must be defined in the application program.

SET QUERYNO=

When these optional keywords are specified, the plan table column QUERYNO is given the value integer for each subsequent row inserted by the EXPLAIN statement. If this clause is not specified, XDB Server assigns its own number to QUERYNO.

STMTCACHE STMTID id-host-variable or integer-constant

Specifies that the cached statement with the specified statement ID is to be explained. The value contained in id-host-variable or specified by integer-constant identifies the statement ID. The statement ID is an integer that uniquely identifies a statement that has been cached in the dynamic statement cache. The statement ID of a cached statement can be retrieved through IFI monitor facilities from IFCID 316 or 124. Some diagnostic trace records, such as 173, 196, and 337, also show the statement ID.

For every row that the EXPLAIN statement inserts into the plan table, statement table, or function table, the QUERYNO column contains the value of the statement ID.

STMTCACHE STMTOKEN id-host-variable or integer-constant

Specifies that the cached statements with the specified statement token are to be explained. The value contained in token-host-variable or specified by string-constant identifies the statement token. The statement token must be a character string that is no longer than 240 bytes. The application program that originally prepares and inserts a statement into the cache associates a statement token with the cached statement. The program can make this association with the RRSAF SET_ID function, or the sqleseti API if the program is connected remotely.

For every row that the EXPLAIN statement inserts into the plan table, statement table, or function table, the STMTTOKEN column contains the value of the statement token, and the QUERYNO column contains the value of the statement ID for the cached statement with the statement token.

PLAN_TABLE Output

The XDB Server explain facility is highly compatible with the explain facility in DB2. While a one-to-one correspondence exists in the order and naming of XDB Server and DB2 PLAN_TABLE columns, differences do occur in some of the values which the optimizer writes to the PLAN_TABLE columns. In those cases where the optimizer produces a PLAN_TABLE column value that varies from that produced by a comparable EXPLAIN statement under DB2, the variation is noted.

If it does not already exist, the XDB Server creates an empty table named PLAN_TABLE for the user's CURRENT SQLID at the current location. Each time an EXPLAIN statement is executed, the XDB Server appends another row of information to the PLAN_TABLE. This information accumulates, allowing comparison and analysis of individual query information.

The following table describes the standard column arrangement in PLAN_TABLE. Each step in the execution of a query or subquery (in an explainable statement) is described in its own row in PLAN_TABLE. Each column value in a row identifies an aspect of the execution step -- such as the query or subquery, which tables are involved, and the access path used to carry out the step.

Column Name | Description
integer | Preceded by the keywords SET QUERYNO=, specifies an integer to be inserted into the QUERYNO column of the plan_table.
explainable-sql-statement Preceded by the keyword FOR, specifies the SQL statement for which information is returned to the plan table. Only SELECT and INSERT statements or the searched form of an UPDATE or DELETE statement, can be the SQL statement in an EXPLAIN command. The statement must not be a statement-name or a host-variable, and must refer to objects at the current location.

explainable-sql-statement must not contain a QUERYNO clause. To specify the value of the QUERYNO column in plan table for the statement being explained, use the SET QUERYNO = clause of the EXPLAIN statement.

If embedded in an application program, the EXPLAIN statement can contain host variable references. These host variables must be defined in the application program.

QUERYNO | A number identifying the explained statement. Can be specified with the SET QUERYNO clause.
QBLOCKNO | A number to identify subqueries.
APPLNAME | BLANK (XDB Server currently only explains individual queries)
PROGNAME | BLANK (XDB Server currently only explains individual queries)
PLANNO | Constant value of "1" (since only one individual query can be described per EXPLAIN command)
METHOD | Constant value of "1" (the XDB Server currently processes all joins using the "nested loop" method)
CREATOR | Creator of the table accessed.
TNAME | The name of the table accessed.
TABNO | A number distinguishing multiple references to the same table.
ACCESSTYPE Method of accessing the table:
I
An index (identified in ACCESSCREATOR and ACCESSNAME)
I1
One-fetch index scan
N
Index scan when predicate contains keyword IN
R
Sequential scan of its pages (commonly called table space scan)
M
Multiple index scan; followed by MX, MI, or MU
MX
Index scan on the index named in ACCESSNAME
MI
Intersection of multiple indexes
MU
Union of multiple indexes
blank
Not applicable to current row
MATCHCOLS | The number of index keys matched in the index scan. Zero (0) for a nonmatching index scan.
ACCESSCREATOR | The creator of the index named in ACCESSNAME.
ACCESSNAME | Name of the index referred to in ACCESSTYPE.
INDEXONLY | "Y" if data pages need not be accessed.
SORTN_UNIQ | Always "N"
SORTN_JOIN | Always "N"
SORTN_ORDERBY | Always "N"
SORTN_GROUPBY | Always "N"
SORTC_UNIQ | "Y" if sort on result table is required to remove duplicate rows.
SORTC_JOIN | Always "N"
SORTC_ORDERBY | "Y" if sort on result table is required for ORDER BY.
SORTC_GROUPBY | Always "N"
TSLOCKMODE | Always "IS"
TIMESTAMP | The time at which the EXPLAIN statement was processed.
REMARKS | Optional user remarks.
PREFETCH Whether or not prefetch can be used to read pages in advance:
P
Pure sequential prefetch
L
Prefetch through a page list
COLUMN_FN_EVAL Normally Blank. Contains a nonblank value "R" only when the XDB Server can evaluate the function directly from the index.

If the statement:

SELECT COUNT(field1)
    FROM table1
    WHERE field1 = ?

did not contain a WHERE clause, then the aggregate would be evaluated from the index (providing a simple index exists on field1).

MIXOPSEQ | A number indicating the sequence in which the steps of a multiple index operation are preformed. Zero (0) if ACCESSTYPE is other than MX, MI or MU.
VERSION | Always Blank.
COLLID | Always Blank.

Comments:

Table Creation Options

Plan tables can function with fewer columns than those described in the previous table. The XDB Server accepts three configurations (corresponding to different DB2 versions) of plan tables. The PLAN_TABLE format on the XDB Server defaults to the same 30 column table as used in DB2. Users have the option of explicitly creating their own 25, 28 or 30 column PLAN_TABLE:

  • A 30 column table ending with the COLLID column (used with DB2 Version 2.3).
  • A 25 column table ending with the REMARKS column.
  • A 28 column table ending with the MIXOPSEQ column.

A plan table must include one of the following sets of columns:

  • All the columns up to and including REMARKS (COLCOUNT = 25)
  • All the columns up to and including MIXOPSEQ (COLCOUNT = 28)
  • All the columns up to and including COLLID (COLCOUNT = 30)
  • All the columns up to and including JOIN_PGROUP_ID (COLCOUNT = 34)
  • All the columns up to and including IBM_SERVICE_DATA (COLCOUNT = 43)
  • All the columns up to and including BIND_TIME (COLCOUNT = 46)
  • All the columns shown in the CREATE statement (COLCOUNT = 58)

Whichever option is used, the columns must appear in the same order indicated in the previous table. A plan table can be modified with an ALTER TABLE command, as long as the final table configuration matches one of the three options above.

When using the 58-column format for the plan table, remember that many columns (PROGNAME, COLLID, CREATOR, TNAME, ACCESSCREATOR, ACCESSNAME, CORRELATION_NAME) must be defined as VARCHAR(128). In previous releases of DB2, these columns were smaller.

Plan table migration

You can migrate existing plan tables to subsequent releases or fall back to prior releases. If you fall back to a prior release, the extra columns are simply ignored when EXPLAIN is executed. If you migrate to a subsequent release, the missing columns are likewise ignored.

Example:

The following example places a description of the steps taken by the XDB Server to execute the SELECT statement shown into the user's plan table. The QUERYNO value of "1212" uniquely marks the PLAN_TABLE row entries as pertaining to this SELECT statement:

EXPLAIN PLAN SET QUERYNO = 1212 FOR
    SELECT pno, shipcost = weight * 1.15
        FROM part
        WHERE city = "LONDON"

To retrieve the PLAN_TABLE row entries belonging solely to the SELECT statement "explained" above, query the PLAN_TABLE by specifying a value of "1212" for the QUERYNO column:

SELECT *
    FROM plan_table
    WHERE queryno = 1212
Parent topic: SQL Statements


FETCH

The FETCH command (embedded SQL only) positions a cursor on a row of its result table. It can return zero, one, or multiple rows and assigns the values of the rows to host variables if there is a target specification.
Restriction: This topic applies to Windows environments only.

There are two forms of this statement:

  • Single row fetch: positions the cursor and, optionally, retrieves data from a single row of the result table.
  • Multiple row fetch: positions the cursor on zero or more rows of the result table and, optionally, returns data if there is a target specification.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

To execute a FETCH command on an opened cursor, the user requires the same authority needed to declare that cursor for a given table or set of tables.

Syntax

FETCH [SENSITIVE | INSENSITIVE] fetch-orientation [FROM]
    cursor-name [single-row-fetch | multiple-row-fetch]

fetch-orientation

{BEFORE |
 AFTER |
 row-positioned |
 rowset-positioned}

row-positioned

[NEXT |
 PRIOR |
 FIRST |
 LAST |
 CURRENT |
 ABSOLUTE {host-variable | integer-constant} |
 RELATIVE {host-variable | integer-constant}]

rowset-positioned

[NEXT ROWSET |
 PRIOR ROWSET |
 FIRST ROWSET |
 LAST ROWSET |
 CURRENT ROWSET |
 ROWSET STARTING AT {ABSOLUTE | RELATIVE} {host-variable | integer-constant}]

single-row-fetch

[INTO {host-variable [,...] | DESCRIPTOR descriptor-name}]

multiple-row-fetch

[FOR {host-variable | integer-constant} ROWS]
[INTO {host-variable-array [,...] | DESCRIPTOR descriptor-name}]

Description

The FETCH command retrieves data from the next row of a cursor result table. A cursor defines the current row of the result. A FETCH statement also advances this cursor to the next available row in the result table. The result table is a collection of rows of data that satisfy the conditions of a SELECT statement defined in a DECLARE CURSOR statement.

If currently positioned before a row of its result table, the FETCH command moves the cursor onto that row and assigns the column values in that row to the host variables as specified by either the INTO or USING clauses. If positioned on a row (other than the last row), the FETCH command moves the cursor onto the next row, assigning the column values of that row to the host variables specified. Once the cursor becomes positioned on or after the last row, a value of +100 is assigned to the SQLCODE indicator field (SQLCA), and the FETCH command positions the cursor after the last row. No values are assigned to the host variables indicated.

INSENSITIVE

Returns the row from the result table as it is. If the row has been previously fetched with a FETCH SENSITIVE, it reflects changes made outside this cursor before the FETCH SENSITIVE statement was issued. Positioned updates and deletes are reflected with FETCH INSENSITIVE if the same cursor was used for the positioned update or delete.

INSENSITIVE can only be specified for cursors declared as INSENSITIVE or SENSITIVE STATIC (or if the cursor is declared as ASENSITIVE and DB2 defaults to INSENSITIVE). Otherwise, if the cursor is declared as SENSITIVE DYNAMIC (or if the cursor is declared as ASENSITIVE and DB2 defaults to SENSITIVE DYNAMIC), an error occurs and the FETCH statement has no effect. For an INSENSITIVE cursor, specifying INSENSITIVE is optional because it is the default.

SENSITIVE

Updates the fetched row in the result table from the corresponding row in the base table of the cursor's SELECT statement and returns the current values. Thus, it reflects changes made outside this cursor. SENSITIVE can only be specified for a sensitive cursor. Otherwise, if the cursor is insensitive, an error occurs and the FETCH statement has no effect. For a SENSITIVE cursor, specifying SENSITIVE is optional because it is the default.

When the cursor is declared as SENSITIVE STATIC and a FETCH SENSITIVE is requested, the following steps are taken:

  1. SQL Option retrieves the row of the database that corresponds to the row of the result table that is about to be fetched.
  2. If the corresponding row has been deleted, a "delete hole" occurs in the result table, a warning is issued, the cursor is repositioned on the "hole", and no data is fetched. (SQL Option marks a row in the result table as a "delete hole" when the corresponding row in the database is deleted.)
  3. If the corresponding row has not been deleted, the predicate of the underlying SELECT statement is re-evaluated. If the row no longer satisfies the predicate, an "update hole" occurs in the result table, a warning is issued, the cursor is repositioned on the "hole," and no data is fetched. (SQL Option marks a row in the result table as an "update hole" when an update to the corresponding row in the database causes the row to no longer qualify for the result table.)
  4. If the corresponding row does not result in a delete or an update hole in the result table, the cursor is repositioned on the row of the result table and the data is fetched.

AFTER

Positions the cursor after the last row of the result table. Values are not assigned to host variables. The number of rows of the result table are returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA for cursors with an effective sensitivity of INSENSITIVE or SENSITIVE STATIC.

BEFORE

Positions the cursor before the first row of the result table. Values are not assigned to host variables.

row-positioned

Positioning of the cursor with row-positioned fetch orientations NEXT, PRIOR, and RELATIVE is done in relation to the current cursor position. Following a successful row-positioned FETCH statement, the cursor is positioned on a single row of data. If the cursor is enabled for rowsets, positioning is performed relative to the first row of the current rowset, and the cursor is positioned on a rowset consisting of a single row.

NEXT

Positions the cursor on the next row or rows of the result table relative to the current cursor position, and returns data if a target is specified. NEXT is the only row-positioned fetch operation that can be explicitly specified for cursors that are defined as NO SCROLL. NEXT is the default if no other cursor positioning is specified. If a specified row reflects a hole, a warning is issued and data values are not assigned to host variables for that row.

The following table shows situations for different cursor positions and the results when NEXT is used.

Current state of the cursor | Result of FETCH NEXT
Before the first row | Cursor is positioned on the first row and data is returned if requested.
On the last row or after the last row | A warning occurs, values are not row assigned to host variables, and the cursor is positioned after the last row.
Before a hole | For a SENSITIVE STATIC cursor, a warning occurs for a delete hole or an update hole, values are not assigned to host variables, and the cursor is positioned on the hole.
Unknown | An error occurs, values are not assigned to host variables, and the cursor position remains unknown.

PRIOR

Positions the cursor on the previous row or rows of the result table relative to the current cursor position, and returns data if a target is specified. If a specified row reflects a hole, a warning is issued, and data values are not assigned to host variables for that row.

The following table shows situations for different cursor positions and the results when PRIOR is used.

Current state of the cursor | Result of FETCH PRIOR
Before or on the first row | A warning occurs, values are not first row assigned to host variables, and the cursor is positioned before the first row.
After a hole | For a SENSITIVE STATIC cursor, a warning occurs for a delete hole or an update hole, values are not assigned to host variables, and the cursor is positioned on the hole.
After the last row | Cursor is positioned on the last row.
Unknown | An error occurs, values are not assigned to host variables, and the cursor position remains unknown.

FIRST

Positions the cursor on the first row of the result table, and returns data if a target is specified. For a SENSITIVE STATIC cursor, if the first row of the result table is a hole, a warning occurs for a delete hole or an update hole and values are not assigned to host variables.

LAST

Positions the cursor on the last row of the result table, and returns data if a target is specified. The number of rows of the result table is returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA for an insensitive or sensitive static cursor. For a SENSITIVE STATIC cursor, if the last row of the result table is a hole, a warning occurs for a delete hole or an update hole and values are not assigned to host variables.

CURRENT

The cursor position is not changed, data is returned if a target is specified. If the cursor was positioned on a rowset of more than one row, then the cursor position is on the first row of the rowset.

The following table shows situations in which errors occur with CURRENT.

Current state of the cursor | Result of FETCH CURRENT
Before the first row or after the last row | A warning occurs, values are not last row assigned to host variables.
On a hole | For a SENSITIVE STATIC or a SENSITIVE DYNAMIC cursor, a warning occurs for a delete hole or an update hole, values are not assigned to host variables, and the cursor is positioned on the hole. A hole is detected for a SENSITIVE DYNAMIC cursor when the current row is deleted or updated so that it no longer meets the selection criterion, and a FETCH CURRENT or a FETCH RELATIVE +0 is executed without repositioning the cursor.
Unknown | An error occurs, values are not assigned to host variables, and the cursor position remains unknown.

ABSOLUTE

host-variable or integer-constant is assigned to an integral value k. If a host-variable is specified, it must be an exact numeric type with zero scale and must not include an indicator variable. The possible data types for the host variable are DECIMAL(n,0) or integer. The DECIMAL data type is limited to DECIMAL(18,0). An integer-constant can be up to 31 digits, depending on the application language.

If k=0, the cursor is positioned before the first row of the result table. Otherwise, ABSOLUTE positions the cursor to row k of the result table if k>0, or to k rows from the bottom of the table if k<0. For example, "ABSOLUTE -1" is the same as "LAST".

Data is returned if the specified position is within the rows of the result table, and a target is specified.

If an absolute position is specified that is before the first row or after the last row of the result table, a warning occurs, values are not assigned to host variables, and the cursor is positioned either before the first row or after the last row. If the resulting cursor position is after the last row for INSENSITIVE and SENSITIVE STATIC scrollable cursors, the number of rows of the result table are returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA. If row k of the result table is a hole, a warning occurs and values are not assigned to host variables.

FETCH ABSOLUTE 0 results in positioning before the first row and a warning is issued. FETCH BEFORE results in positioning before the first row and no warning is issued.

The following table shows some synonymous specifications.

Specification | Alternative
ABSOLUTE 0 (but with a warning) | BEFORE (without a warning)
ABSOLUTE +1 | FIRST
ABSOLUTE -1 | LAST
ABSOLUTE -m, 0<m=n | ABSOLUTE n+1-m
ABSOLUTE n | LAST
ABSOLUTE -n | FIRST
ABSOLUTE x (with a warning) | AFTER (without a warning)
ABSOLUTE -x (with a warning) | BEFORE (without a warning)

RELATIVE

host-variable or integer-constant is assigned to an integral value k. If a host-variable is specified, it must be an exact numeric type with zero scale and must not include an indicator variable. The possible data types for the host variable are DECIMAL(n,0) or integer. The DECIMAL data type is limited to DECIMAL(18,0). An integer-constant can be up to 31 digits, depending on the application language.

Data is returned if the specified position is within the rows of the result table, and a target is specified.

RELATIVE positions the cursor to the row in the result table that is either k rows after the current row if k>0, or ABS(k) rows before the current row if k<0. For example, "RELATIVE -1" is the same as "PRIOR". If k=0, the position of the cursor does not change (that is, "RELATIVE 0" is the same as "CURRENT").

If a relative position is specified that results in positioning before the first row or after the last row, a warning is issued, values are not assigned to host variables, and the cursor is positioned either before the first row or after the last row. If the resulting cursor position is after the last row for INSENSITIVE and SENSITIVE STATIC scrollable cursors, the number of rows of the result table is returned in the SQLERRD1 and SQLERRD2 fields of the SQLCA. If the cursor is positioned on a hole and RELATIVE 0 is specified or if the target row is a hole, a warning occurs and values are not assigned to host variables. If the cursor position is unknown and RELATIVE 0 is specified, an error occurs.

The following table shows some synonymous specifications.

Specification | Alternative
RELATIVE +1 | NEXT
RELATIVE -1 | PRIOR
RELATIVE 0 | CURRENT
RELATIVE +r (with a warning) | AFTER (without a warning)
RELATIVE -r (with a warning) | BEFORE (without a warning)

rowset-positioned

Positioning of the cursor with rowset-positioned fetch orientations NEXT ROWSET, PRIOR ROWSET, and ROWSET STARTING AT RELATIVE is done in relation to the current rowset. The number of rows in the rowset is determined either explicitly or implicitly. The FOR n ROWS clause in the multiple-row-fetch clause is used to explicitly specify the size of the rowset. Following a successful rowset-positioned FETCH statement, the cursor is positioned on all rows of the rowset.

A rowset-positioned fetch orientation must not be specified if the current cursor position is not defined to access rowsets. NEXT ROWSET is the only rowset-positioned fetch orientation that can be specified for cursors that are defined as NO SCROLL.

If a row of the rowset reflects a hole, a warning is returned, data values are not assigned to host variable arrays for that row (that is, the corresponding positions in the target host variable arrays are untouched), and -3 is returned in all provided indicator variables for that row. If a hole is detected, and at least one indicator variable is not provided, an error occurs.

NEXT ROWSET

Positions the cursor on the next rowset of the result table relative to the current cursor position, and returns data if a target is specified. The next rowset is logically obtained by fetching the row that follows the current rowset and fetching additional rows until the number of rows that is specified implicitly or explicitly in the FOR n ROWS clause is obtained or the last row of the result table is reached.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the cursor is not positioned because of a prior error, values are not assigned to the host-variable-array, and an error is returned. If a row of the rowset would be after the last row of the result table, values are not assigned to host-variable-arrays for that row and any subsequent requested rows of the rowset, and a warning is returned.

NEXT ROWSET is the only rowset positioned fetch orientation that can be explicitly be specified for cursors that are defined as NO SCROLL.

PRIOR ROWSET

Positions the cursor on the previous rowset of the result table relative to the current position, and returns data if a target is specified.

The prior rowset is logically obtained by fetching the row that follows the current rowset and fetching additional rows until the number of rows that is specified implicitly or explicitly in the FOR n ROWS clause is obtained or the last row of the result table is reached.

If a row would be before the first row of the result table, the cursor is positioned on a partial rowset that consists of only those rows that are prior to the current position of the cursor starting with the first row of the result table, and a warning is returned. Values are not assigned to the host-variable-arrays for the rows in the rowset for which the warning is returned.

Although the rowset is logically obtained by fetching backwards from before the current rowset, the data is returned to the application starting with the first row of the rowset, to the end of the rowset.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the cursor is not positioned because of a prior error, values are not assigned to the host-variable-array, and an error is returned.

FIRST ROWSET

Positions the cursor on the first rowset of the result table, and returns data if a target is specified.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the result table contains fewer rows than specified implicitly or explicitly in the FOR n ROWS clause, values are not assigned to host-variable-arrays after the last row of the result table, and a warning is returned.

LAST ROWSET

Positions the cursor on the last rowset of the result table and returns data if a target is specified. The last rowset is logically obtained by fetching the last row of the result table and fetching prior rows until the number of rows in the rowset is obtained or the first row of the result table is reached. Although the rowset is logically obtained by fetching backwards from the bottom of the result table, the data is returned to the application starting with the first row of the rowset, to the end of the rowset, which is also the end of the result table.

If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned.

If the result table contains fewer rows than specified implicitly or explicitly in the FOR n ROWS clause, the last rowset is the same as the first rowset, values are not assigned to host-variable-arrays after the last row of the result table, and a warning is returned.

CURRENT ROWSET

If the FOR n ROWS clause specifies a number different from the number of rows specified implicitly or explicitly in the FOR n ROWS clause on the most recent FETCH statement for this cursor, the cursor is repositioned on the specified number of rows, starting with the first row of the current rowset. Otherwise, the position of the cursor on the current rowset is unchanged. Data is returned if a target is specified.

With isolation level UR or a sensitive dynamic scrollable cursor, it is possible that different rows will be returned than the FETCH that established the most recent rowset cursor position. This can occur while refetching the first row of the rowset when it is determined to not be there anymore. In this case, fetching continues moving forward to get the first row of data for the rowset. This can also occur when changes have been made to other rows in the current rowset such that they no longer exist or have been logically moved within (or out of) the result table of the cursor.

If the cursor is not positioned because of a prior error, values are not assigned to the host-variable-array, and an error occurs.

If the current rowset contains fewer rows than specified implicitly or explicitly in the FOR n ROWS clause, values are not assigned to host-variable-arrays after the last row, and a warning is returned.

ROWSET STARTING AT ABSOLUTE or RELATIVE host-variable or integer-constant

Positions the cursor on the rowset beginning at the row of the result table that is indicated by the ABSOLUTE or RELATIVE specification, and returns data if a target is specified.

host-variable or integer-constant is assigned to an integral value k. If host-variable is specified, it must be an exact numeric type with scale zero, and must not include an indicator variable. The possible data types for the host variable are DECIMAL(n,0) or integer, where the DECIMAL data type is limited to DECIMAL(18,0). If a constant is specified, the value must be an integer.

If a row of the result table would be after the last row or before the first row of the result table, values are not assigned to host-variable-arrays for that row and a warning is returned.

ABSOLUTE

If k=0, an error occurs. If k>0, the first row of the rowset is row k. If k<0, the rowset is positioned on the ABS(k) rows from the bottom of the result table. Assume that ABS(k) is equal to the number of rows for the rowset and that there are enough row to return a complete rowset:

  • FETCH ROWSET STARTING AT ABSOLUTE -k is the same as FETCH LAST ROWSET.
  • FETCH ROWSET STARTING AT ABSOLUTE 1 is the same as FETCH FIRST ROWSET.

RELATIVE

If k=0 and the FOR n ROWS clause does not specify a number different from the number most recently specified implicitly or explicitly for this cursor, then the position of the cursor does not change (that is, "RELATIVE ROWSET 0" is the same as "CURRENT ROWSET"). If k=0 and the FOR n ROWS clause specifies a number different from the number most recently specified implicitly or explicitly for this cursor, then the cursor is repositioned on the specified number of rows, starting with the first row of the current rowset. Otherwise, RELATIVE repositions the cursor so that the first row of the new rowset cursor position is on the row in the result table that is either k rows after the first row of the current rowset cursor position if k>0, or ABS(k) rows before the first row of the current rowset cursor position if k<0. Assume that ABS(k) is equal to the number of rows for the resulting rowset

  • FETCH ROWSET STARTING AT RELATIVE -k is the same as FETCH PRIOR ROWSET.
  • FETCH ROWSET STARTING AT RELATIVE k is the same as FETCH NEXT ROWSET.
  • FETCH ROWSET STARTING AT RELATIVE 0 is the same as FETCH CURRENT ROWSET.

When ROWSET STARTING AT RELATIVE -n is specified and there are not enough rows between the current position of the cursor and the beginning of the result table to return a complete rowset:

  • A warning is returned.
  • Values are not assigned to the host-variable-arrays.
  • The cursor position remains unchanged.

If a row of the rowset reflects a hole, If a row of the rowset reflects a hole, the following actions occur:

  • A warning is returned.
  • Data values are not assigned to the host-variable-arrays for that row (that is, the corresponding positions in the target host-variable-arrays are untouched).
  • A value of -3 is returned in all of the indicator variables that are provided for the row.

If a hole is detected and at least one indicator variable is not provided, an error is returned. If a row of the rowset is unknown, values are not assigned to host variable arrays for that row, and an error is returned. If a row of the rowset would be after the last row or before the first row of the result table, values are not assigned to host-variable-arrays for that row, and a warning is returned.

cursor-name

Identifies the cursor to be used in the fetch operation. The cursor name must identify a declared cursor, as explained in the description of the DECLARE CURSOR statement in "DECLARE CURSOR" in topic 5.42, or an allocated cursor, as explained in "ALLOCATE CURSOR" in topic 5.2. When the FETCH statement is executed, the cursor must be in the open state.

If a single-row-fetch or multiple-row-fetch clause is not specified, the cursor position is adjusted as specified, but no data is returned to the user.

single-row-fetch

When single-row-fetch is specified, SENSITIVE or INSENSITIVE can be specified though there is a default. The default depends on the sensitivity of the cursor. If the sensitivity of the cursor is INSENSITIVE, then the default is INSENSITIVE. If the effective sensitivity of the cursor is SENSITIVE DYNAMIC or SENSITIVE STATIC, then the default is SENSITIVE. The single-row-fetch or multiple-row-fetch clause must not be specified when the FETCH BEFORE or FETCH AFTER option is specified. They are required when FETCH BEFORE or FETCH AFTER is not specified. If an individual fetch operation causes the cursor to be positioned or to remain positioned on a row if there is a target specification, the values of the result table are assigned to host variables as specified by the single-fetch-clause.

INTO host-variable,...

Specifies a list of host variables. Each host-variable must identify a structure or variable that is described in the application program in accordance with the rules for declaring host structures and variables. A reference to a structure is replaced by a reference to each of its variables. The first value in the result row is assigned to the first host variable, the second value to the second host variable, and so on.

INTO DESCRIPTOR descriptor-name

Identifies an SQLDA that contains a valid description of the host output variables. Result values from the associated SELECT statement are returned to the application program in the output host variables.

Before the FETCH statement is processed, you must set the following fields in the SQLDA:

  • SQLN to indicate the number of SQLVAR occurrences provided in the SQLDA

    A REXX SQLDA does not contain this field.

  • SQLABC to indicate the number of bytes of storage allocated in the SQLDA
  • SQLD to indicate the number of variables used in the SQLDA when processing the statement
  • SQLVAR occurrences to indicate the attributes of the variables

The SQLDA must have enough storage to contain all SQLVAR occurrences. Each SQLVAR occurrence describes a host variable or buffer into which a value in the result table is to be assigned. If LOBs are present in the results, there must be additional SQLVAR entries for each column of the result table. If the result table contains only base types and distinct types, multiple SQLVAR entries are not needed for each column. However, extra SQLVAR entries are needed for distinct types as well as for LOBs in DESCRIBE and PREPARE INTO statements.

SQLD must be set to a value greater than or equal to zero and less than or equal to SQLN.

multiple-row-fetch

Retrieves multiple rows of data from the result table of a query. The FOR n ROWS clause of the FETCH statement controls how many rows are returned on a single FETCH statement. The fetch orientation determines whether the resulting cursor position (for example, on a single row, rowset, before, or after the result table). Fetching stops when an error is returned, all requested rows are fetched, or the end of data condition is reached.

Fetching multiple rows of data can be done with scrollable or non-scrollable cursors. The operations used to define, open, and close a cursor used for fetching multiple rows of data are the same as for those used for single row FETCH statements.

If the BEFORE or AFTER option is specified, neither single-row-fetch or multiple-row-fetch can be specified.

FOR host-variable or integer-constant ROWS

host-variable or integer-constant is assigned to an integral value k. If a host variable is specified, it must be an exact numeric type with a scale of zero and must not include an indicator variable. Furthermore, k must be in the range, 0<k<=32767.

This clause must not be specified if a row-positioned fetch-orientation clause was specified. This clause must also not be specified for a cursor that is defined without rowset access.

If a rowset fetch orientation is specified and this clause is not specified, the number of rows in the resulting rowset is determined as follows:

  • If the most recent FETCH statement for this cursor was a rowset-positioned FETCH, the number of rows of the rowset is implicitly determined by the number of rows that was most recently specified (implicitly or explicitly) for this cursor.
  • When the most recent FETCH statement for this cursor was either FETCH BEFORE or FETCH AFTER and the most recent FETCH statement for this cursor prior to that was a rowset-positioned FETCH, the number of rows of the rowset is implicitly determined by the number of rows that were most recently specified (implicitly or explicitly) for this cursor.
  • Otherwise, the rowset consists of a single row.

For result set cursors, the number of rows for a rowset cursor position, established in the procedure that defined the rowset, is not inherited by the caller when the rowset is returned. Use the FOR n ROWS clause on the first rowset FETCH statement for the result set in the calling program to establish the number of rows for the cursor. Otherwise, the rowset consists of a single row.

The cursor is positioned on the row or rowset that is specified by the orientation clause (for example, NEXT ROWSET), and those rows are fetched if a target is specified. After the cursor is positioned on the first row being fetched, the next k-1 rows are fetched. Fetching moves forward from the cursor position in the result table and continues until the end of data condition is returned, k-1 rows have been fetched, or an assignment error is returned.

The resulting cursor position depends on the fetch orientation that is specified:

  • For a row-positioned fetch orientation, the cursor is positioned at the last row successfully retrieved.
  • For a rowset-positioned fetch orientation, the cursor is positioned on all the rows retrieved.

The values from each individual fetch are placed in data areas that are described in the INTO or USING clause. If a target specification is provided for a rowset-positioned FETCH, the host variable arrays must be specified as the target specification, and the arrays must be defined with a dimension of 1 or greater. The target specification must be defined as an array for a rowset-positioned FETCH even if the number of rows that is specified implicitly or explicitly is one.

INTO host-variable-array

Identifies for each column of the result table a host-variable-array to receive the data that is retrieved with this FETCH statement. If the number of host-variable-arrays is less than the number of columns of the result table, the SQLWARN3 field of the SQLCA is set to 'W'. No warning is given if there are more host-variable-arrays than the number of columns in the result table.

Each host-variable-array must be defined in the application program in accordance with the rules for declaring an array. A host-variable-array is used to return the values for a column of the result table. The number of rows to be fetched must be less than or equal to the dimension of each of the host-variable-arrays.

An optional indicator array can be specified for a host-variable-array. It should be specified if the SQLTYPE of any SQLVAR occurrence indicates that the column of the result table is nullable. Additionally, if an operation may result in null values, such as an UPDATE operation that results in a hole, is performed in the application, an indicator array should be specified. Otherwise an error occurs if null values are encountered. The indicators are returned as small integers.

INTO DESCRIPTOR descriptor-name

Identifies an SQLDA that must contain a valid description of zero or more host-variable-arrays or buffers into which the values for a column of the result table are to be returned.

Before the FETCH statement is processed, you must set the following fields in the SQLDA:

  • SQLN to indicate the number of SQLVAR occurrences provided in the SQLDA.
  • SQLABC to indicate the number of bytes of storage allocated for the SQLDA.
  • SQLD to indicate the number of variables used in the SQLDA when processing the statement.
  • SQLVAR occurrences to indicate the attributes of an element of the host-variable-array. Within each SQLVAR representing an array:
    • SQLTYPE indicates the data type of the elements of the host-variable-array.
    • SQLDATA field points to the first element of the host-variable-array.
    • The length fields (SQLLEN and SQLLONGLEN) are set to indicate the maximum length of a single element of the array.
    • SQLNAME - The length of SQLNAME must be set to 8, and the first two bytes of the data portion of SQLNAME must be initialized to X'0000'. The fifth and sixth bytes must contain a flag field and the seventh and eighth bytes must be initialized to a binary small integer (half word) representation of the dimension of the host-variable-array, and the corresponding indicator array, if one is specified.

The SQLVAR entry for the number of rows must also contain a flag value. The number of rows to be fetched must be less than or equal to the dimension of each of the host variable arrays.

You set the SQLDATA and SQLIND pointers to the beginning of the corresponding arrays. The SQLDA must have enough storage to contain all SQLVAR occurrences. Each SQLVAR occurrence describes a host-variable-array or buffer into which the values for a column in the result table are to be returned. If any column of the result table is a LOB, two SQLVAR entries must be provided for each SQLVAR, and SQLN must be set to two times the number of SQLVARS. SQLD must be set to a value greater than or equal to zero and less than or equal to SQLN.

Example:

The host-variables parameter identifies a list of COBOL variables defined in working storage. The following is an example of a FETCH statement. We assume that custbl is a cursor previously defined in a DECLARE CURSOR statement.

EXEC SQL
    FETCH custbl
    INTO :CNO, :CNAME
END-EXEC
Parent topic: SQL Statements


FREE LOCATOR

The FREE LOCATOR statement removes the association between a LOB locator variable and its value.
Restriction: This topic applies to Windows environments only.

The XDB Server operating environment does not provide support for FREE LOCATOR at this time.

Invocation

This statement can only be embedded in an application program. It cannot be issued interactively. It is an executable statement that can be dynamically prepared. However, the EXECUTE statement with the USING clause must be used to execute the prepared statement. FREE LOCATOR cannot be used with the EXECUTE IMMEDIATE statement.

Authorization

None required.

Syntax

FREE LOCATOR {host-variable}

Description

host-variable,...

Identifies a host-variable locator variable that must have been previously declared according to the rules for declaring host-variable locator variables. The locator variable type must be a binary large object locator, a character large object locator, or a double-byte character large object locator.

After the FREE LOCATOR statement is executed, each locator variable in the host-variable list is no longer associated with the string value it represented.

If a locator variable is not an established locator within the current unit of work, an invalid locator error occurs. When this error occurs and more than one host variable was specified in the FREE LOCATOR statement, only the locators up to the first invalid locator are freed. Locators listed after the first invalid locator are not freed.

Example:

Assume that the employee table contains columns RESUME, HISTORY, and PICTURE and that locators have been established in a program to represent the column values. Free the CLOB locator variables LOCRES and LOCHIST, and the BLOB locator variable LOCPIC.

EXEC SQL FREE LOCATOR :LOCRES, :LOCHIST, :LOCPIC
Parent topic: SQL Statements


GET DIAGNOSTICS

The GET DIAGNOSTICS statement provides diagnostic information about the last SQL statement (other than a GET DIAGNOSTICS statement) that was executed. This diagnostic information is gathered as the previous SQL statement is executed. Some of the information available through the GET DIAGNOSTICS statement is also available in the SQLCA.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

GET DIAGNOSTICS {statement-information | condition-information | combined-information}

statement-information:

{host-variable1 = statement-information-item-name | host-variable1 = DB2_GET_DIAGNOSTICS_DIAGNOSTICS} [,...]

statement-information-item-name:

{DB2_LAST_ROW | DB2_NUMBER_PARAMETER_MARKERS | DB2_NUMBER_RESULT_SETS |
        DB2_RETURN_STATUS | DB2_SQL_ATTR_CURSOR_HOLD |
        DB2_SQL_ATTR_CURSOR_ROWSET | DB2_SQL_ATTR_CURSOR_SCROLLABLE |
        DB2_SQL_ATTR_CURSOR_SENSITIVITY | DB2_SQL_ATTR_CURSOR_TYPE |
        MORE | NUMBER | ROW_COUNT} [,...]

condition-information:

CONDITION {host-variable2 | integer}
       {host-variable3 = {condition-information-item-name | connection-information-item-name}} [,...]

condition-information-item-name:

{CATALOG_NAME | CONDITION_NUMBER | CURSOR_NAME | DB2_ERROR_CODE1 |
DB2_ERROR_CODE2 | DB2_ERROR_CODE3 | DB2_ERROR_CODE4 | DB2_INTERNAL_ERROR_POINTER |
DB2_MESSAGE_ID | DB2_MODULE_DETECTING_ERROR | DB2_ORDINAL_TOKEN_n | DB2_REASON_CODE |
DB2_RETURNED_SQLCODE | DB2_ROW_NUMBER | DB2_SQLERRD_SET | DB2_SQLERRD1 | DB2_SQLERRD2 |
DB2_SQLERRD3 | DB2_SQLERRD4 | DB2_SQLERRD5 | DB2_SQLERRD6 | DB2_TOKEN_COUNT | MESSAGE_TEXT |
RETURNED_SQLSTATE | SERVER_NAME}

connection-information-item-name:

{DB2_AUTHENTICATION_TYPE | DB2_AUTHORIZATION_ID | DB2_CONNECTION_STATE |
DB2_CONNECTION_STATUS | DB2_ENCRYPTION_TYPE | DB2_SERVER_CLASS_NAME | DB2_PRODUCT_ID}

combined-information:

host-variable4 = ALL {STATEMENT | {CONDITION | CONNECTION} [host-variable5 | integer]} [,...]
Note:
  • STATEMENT can only be specified once.
  • CONDITION and CONNECTION can only be specified once if host-variable5 or integer is not also specified.

Description

Diagnostic information is provided in three main areas: statement information, condition information, and combined information. After the execution of an SQL statement, information about the execution of the statement is provided as statement information, and at least one instance of condition information is provided. The number of instances of the condition information is indicated by the NUMBER item that is available in the statement information. Combined information contains a text representation of all the information gathered about the execution of the SQL statement.

The diagnostic information that is provided is specific to the server. If you are connected to a server other than DB2 UDB for z/OS, see that product's documentation for the diagnostic information that is returned.

statement-information

Provides information about the last SQL statement executed.

host-variable1

Identifies a variable described in the program in accordance with the rules for declaring host variables. The data type of the host variable must be the data type as specified in Data types for GET DIAGNOSTICS items.

The host variable is assigned the value of the specified statement information item. If the value is truncated when assigning it to the host variable, a warning is returned and the GET_DIAGNOSTICS_DIAGNOSTICS item of the diagnostics area is updated with the details of this condition. If a DIAGNOSTICS item is not set, then the host variable is set to a default value, based on its data type: 0 for an exact numeric field, an empty string for a VARCHAR field, and blanks for a CHAR field.

DB2_GET_DIAGNOSTICS_DIAGNOSTICS

Contains textual information about errors or warnings that may have occurred in the execution of the GET DIAGNOSTICS statement. The format of the information is similar to what would be returned by a GET DIAGNOSTICS :hv = ALL statement.

statement-information-item-name:

DB2_LAST_ROW

For a multiple-row FETCH statement, contains a value of +100 if the last row currently in the table is in the set of rows that have been fetched. For cursors that are not sensitive to updates, there would be no need to do a subsequent FETCH, because the result would be an end-of-data indication. For cursors that are sensitive to updates, a subsequent FETCH may return more data if a row had been inserted before the FETCH was executed. For statements other than multiple-row FETCH statements, or for multiple-row FETCH statements that do not contain the last row, this variable contains the value 0.

DB2_NUMBER_PARAMETER_MARKERS

For a PREPARE statement, contains the number of parameter markers in the prepared statement. Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_NUMBER_RESULT_SETS

For a CALL statement, contains the actual number of result sets returned by the procedure. Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_NUMBER_ROWS

If the previous SQL statement was an OPEN or a FETCH that caused the size of the result table to be unknown, returns the number of rows in the result table. For SENSITIVE DYNAMIC cursors, this value can be thought of as an approximation because rows that are inserted and deleted will affect the next retrieval of this value. If the previous SQL statement was a PREPARE statement, returns the estimated number of rows in the result table for the prepared statement. Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_RETURN_STATUS

Identifies the status value returned from the stored procedure associated with the previously executed SQL statement, provided that the statement was a CALL statement that invoked a procedure that returns a status. . Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_SQL_ATTR_CURSOR_HOLD

For an ALLOCATE or OPEN statement, indicates whether a cursor can be held open across multiple units of work.

  • N indicates that this cursor does not remain open across multiple units of work.
  • Y indicates that this cursor remains open across multiple units of work.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_ROWSET

For an ALLOCATE or OPEN statement, indicates whether or not a cursor can be accesses using rowset positioning.

  • N indicates that this cursor supports only row positioned operations.
  • Y indicates that this cursor supports rowset positioned operations.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_SCROLLABLE

For an ALLOCATE or OPEN statement, indicates whether or not a cursor can be scrolled forward and backward.

  • N indicates that this cursor is not scrollable.
  • Y indicates that this cursor is scrollable.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_SENSITIVITY

For an ALLOCATE or OPEN statement, indicates whether or not a cursor does or does not show updates to cursor rows made by other connections.

  • I indicates insensitive.
  • S indicates sensitive.

Otherwise, a blank is returned.

DB2_SQL_ATTR_CURSOR_TYPE

For an ALLOCATE or OPEN statement, indicates the type of cursor, whether a cursor type is forward-only, static, or dynamic.

  • F indicates a forward cursor.
  • D indicates a dynamic cursor.
  • S indicates a static cursor.

Otherwise, a blank is returned.

MORE

Indicates whether some of the warning and errors from the previous SQL statement were stored or discarded.

  • N indicates that all the warnings and errors from the previous SQL statement are stored in the diagnostic area.
  • Y indicates that some of the warnings and errors from the previous SQL statement were discarded because the amount of storage needed to record warnings and errors exceeded 65535 bytes.

NUMBER

Returns the number of errors and warnings detected by the execution of the previous SQL statement, other than a GET DIAGNOSTICS statement, that have been stored in the diagnostics area. If the previous SQL statement returned an SQLSTATE of 00000 or no previous SQL statement has been executed, the number returned is one.

The GET DIAGNOSTICS statement itself may return information via the SQLSTATE parameter, but does not modify the previous contents of the diagnostics area, except for the DB2_GET_DIAGNOSTICS_DIAGNOSTICS item.

ROW_COUNT

Identifies the number of rows associated with the previous SQL statement that was executed.

If the previous SQL statement is a DELETE, INSERT, or UPDATE statement, ROW_COUNT identifies the number of rows deleted, inserted, or updated by that statement, excluding rows affected by either triggers or referential integrity constraints.

If the previous SQL statement is a multiple-row FETCH, ROW_COUNT identifies the number of rows fetched.

A value of -1 indicates a mass delete from a table in a segmented table space.

Otherwise, or if the server only returns an SQLCA, the value zero is returned.

condition-information

Assigns the values of the specified condition information to the associated host variables. The host variable specified must be of the data type that is compatible with the data type of the specified diagnostic-ID or an error occurs. If the value of the condition is truncated when assigning it to the host variable, an error occurs. If an indicator variable was provided, the length of the value is returned in the indicator variable.

If a DIAGNOSTICS item is not set, then the host variable is set to a default value, based on the data type of the item. The specific value will be 0 for a numeric field, an empty string for a VARCHAR field, and blanks for a CHAR field.

host-variable2 or integer

Identifies the diagnostic for which information is requested. Each diagnostic that occurs while executing an SQL statement is assigned an integer. The value 1 indicates the first diagnostic, 2 indicates the second diagnostic, and so on. If the value is 1, the diagnostic information that is retrieved corresponds to the condition that is indicated by the SQLSTATE value actually returned by the execution of the previous SQL statement (other than a GET DIAGNOSTICS statement). The host variable specified must be a numeric data type or an error occurs. An indicator variable is not allowed for this host variable. If a value is specified that is less than or equal to zero or greater than the number of available diagnostics, an error occurs.

host-variable3

Identifies a variable described in the program in accordance with the rules for declaring host variables. The data type of the host variable must be the data type as specified in Data types for GET DIAGNOSTICS items for the indicated condition-information item.

condition-information-item-name:

CATALOG_NAME

If the returned SQLSTATE is any one of the following values, the constraint that caused the error is a referential, check, or unique constraint. The location (RDB) name of the server that generated the condition is returned.

  • Class 09 (Triggered Action Exception)
  • Class 23 (Integrity Constraint Violation)
  • Class 27 (Triggered Data Change Violation)
  • 40002 (Transaction Rollback - Integrity Constraint Violation)
  • 40004 (Transaction Rollback - Triggered Action Exception)

If the returned SQLSTATE is class 42 (Syntax Error or Access Rule Violation), the server name of the table that caused the error is returned.

If the returned SQLSTATE is class 44 (WITH CHECK OPTION Violation), the server name of the view that caused the error is returned.

Otherwise, the empty string is returned.

The actual server name may be different than the server name specified, either implicitly or explicitly, on the CONNECT statement because of the use of aliases or synonyms.

CONDITION_NUMBER

Returns the number of the diagnostic returned.

CURSOR_NAME

If the returned SQLSTATE is class 24 (Invalid Cursor State), the name of the cursor is returned. Otherwise, the empty string is returned.

DB2_ERROR_CODE1

Returns an internal error code (SQLERRD1). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_ERROR_CODE2

Returns an internal error code (SQLERRD2). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_ERROR_CODE3

Returns an internal error code (SQLERRD3). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_ERROR_CODE4

Returns an internal error code (SQLERRD4). Otherwise, or if the server only returns an SQLCA, the value 0 is returned.

DB2_INTERNAL_ERROR_POINTER

For some errors, this is a negative value that is an internal error pointer. Otherwise, the value 0 is returned.

DB2_MESSAGE_ID

Corresponds to the message that is contained in the MESSAGE_TEXT diagnostic item (for example, DSNT102I or DSNU180I).

DB2_MODULE_DETECTING_ERROR

Returns an identifier indicating which module detected the error. For a SIGNAL statement that is issued from a routine, the value 'ROUTINE' is returned. Otherwise, the string 'DSN ' is returned.

DB2_ORDINAL_TOKEN_n

Returns the nth token. n must be a value from 1 to 100. For example, DB2_ORDINAL_TOKEN_1 would return the value of the first token, DB2_ORDINAL_TOKEN_2 the second token, and so on. A numeric value for a token is converted to characters before being returned. If there is no value for the token, or if the server only returns an SQLCA, an empty string is returned.

DB2_REASON_CODE

Contains the reason code for errors that have a reason code token in the message text. Otherwise, the value zero is returned.

DB2_RETURNED_SQLCODE

Returns the SQLCODE for the specified diagnostic.

DB2_ROW_NUMBER

Returns the number of the row where the condition was encountered, when such information is available and applicable.

DB2_SQLERRD_SET

A value of Y indicates that the DB2_SQLERRD1 through DB2_SQLERRD items might be set. These items are set only when communicating with a server that returns the SQLCA SQL communications area and not the new diagnositics area. Otherwise, a blank is returned.

DB2_SQLERRD1

Returns the value of sqlerrd(1) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD2

Returns the value of sqlerrd(2) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD3

Returns the value of sqlerrd(3) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD4

Returns the value of sqlerrd(4) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD5

Returns the value of sqlerrd(5) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_SQLERRD6

Returns the value of sqlerrd(6) from the SQLCA that is returned by the server. Otherwise, the value zero is returned.

DB2_TOKEN_COUNT

Returns the number of tokens available for the specified diagnostic ID.

MESSAGE_TEXT

Returns the message text that is associated with the SQLCODE. This is the short text, including substituted tokens. The message text does not contain the message number.

RETURNED_SQLSTATE

Returns the SQLSTATE for the specified diagnostic.

SERVER_NAME

If the previous SQL statement is a CONNECT, DISCONNECT, or SET CONNECTION statement, returns the name of the server specified in the previous statement is returned. Otherwise, the name of the server where the statement executes is returned.

connection-information-item-name

Provides information about the last SQL statement executed if it was a CONNECT statement.

DB2_AUTHENTICATION_TYPE

Contains an authentication type value of:

  • 'S' for a server authentication
  • 'C' for client authentication
  • Otherwise, or if the server only returns an SQLCA, a blank is returned

DB2_AUTHORIZATION_ID

Authorization ID used by connected server. Because of user ID translation and authorization exits, the local user ID may not be the authorized ID used by the server.

DB2_CONNECTION_STATE

Contains the connection state:

  • -1 if the connection is unconnected
  • 1 if the connection is connected

Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_CONNECTION_STATUS

Contains a value of:

  • 1 if committable updates can be performed on the connection for this unit of work
  • 2 if no committable updates can be performed on the connection for this unit of work

Otherwise, or if the server only returns an SQLCA, the value zero is returned.

DB2_SERVER_CLASS_NAME

For a CONNECT or SET CONNECTION statement, contains one of the following values:

  • QAS for DB2 UDB for iSeries(TM)
  • QDB2 for DB2 UDB for OS/390 and z/OS
  • QDB2/2 for DB2 UDB for OS/2
  • QDB2/6000 for DB2 UDB for AIX
  • QDB2/6000 PE for DB2 UDB for AIX Parallel Edition
  • QDB2/AIX64 for DB2 UDB for AIX 64-bit
  • QDB2/HPUX for DB2 UDB for HP-UX
  • QDB2/HP64 for DB2 UDB for HP-UX 64-bit
  • QDB2/LINUX for DB2 UDB for Linux
  • QDB2/LINUX390 for DB2 UDB for Linux
  • QDB2/LINUXIA64 for DB2 UDB for Linux
  • QDB2/LINUXPPC for DB2 UDB for Linux
  • QDB2/LINUXPPC64 for DB2 UDB for Linux
  • QDB2/LINUXZ64 for DB2 UDB for Linux
  • QDB2/NT for DB2 UDB for NT
  • QDB2/NT64 for DB2 UDB for NT 64-bit
  • QDB2/PTX for DB2 UDB for NUMA-Q
  • QDB2/SCO for DB2 UDB for SCO UnixWare
  • QDB2/SGI for DB2 UDB for Silicon Graphics
  • QDB2/SNI for DB2 UDB for Siemens Nixdorf
  • QDB2/SUN for DB2 UDB for SUN Solaris
  • QDB2/SUN64 for DB2 UDB for SUN Solaris 64-bit
  • QDB2/Windows 95 for DB2 UDB for Windows 95 or Windows 98
  • QSQLDS/VM for DB2 for VM and VSE
  • QSQLDS/VSE for DB2 for VM and VSE

Otherwise, the empty string is returned.

DB2_ENCRYPTION_TYPE

The level of encryption for the connection:

  • A indicates only the authentication tokens (authid and password) are encrypted.
  • D indicates all data is encrypted for the connection.

Otherwise, a blank is returned.

DB2_PRODUCT_ID

Returns a product signature. If the application server is an IBM relational database product, the form is pppvvrrm, where:

  • ppp identifies the product as follows:
    • ARI for DB2 Server for VSE & VM
    • DSN for DB2 UDB for z/OS
    • QSQ for DB2 UDB for iSeries
    • SQL for all other DB2 UDB products
  • vv is a two-digit version identifier such as '08'
  • rr is a two-digit release identifier such as '01'
  • m is a one-digit maintenance level identifier such as '5' (Values 0, 1, 2, 3, and 4 are for maintenance levels in compatibility and enabling-new-function mode. Values 5, 6, 7, 8, and 9 are for maintenance levels in new-function mode.)

For example, if the application server is Version 8 of DB2 UDB for z/OS in new-function mode with the latest maintenance, the value would be 'DSN08015'.

combined-information

Provides a text representation of all the information gathered about the execution of the SQL statement.

ALL

Indicates that all diagnostic items that are set for the last SQL statement executed are to be combined into one string. The format of the string is a semicolon separated list of all of the available diagnostic information in the form:

item-name[(condition-number)]=value-converted-to-character;... as shown in the following example:

NUMBER=1;RETURNED_SQLSTATE=02000;DB2_RETURNED_SQLCODE=+100;

host-variable4

Identifies a variable described in the program in accordance with the rules for declaring host variables. The data type of the host variable must be VARCHAR. If the length of host-variable4 is not sufficient to hold the full returned diagnostic string, the string is truncated, a warning is returned, and the GET_DIAGNOSTICS_DIAGNOSITICS item of the diagnostics area is updated with the details of this condition.

STATEMENT

Indicates that all statement-information-item-name diagnostic items that are set for the last SQL statement executed should be combined into one string. The format is the same as described for the ALL option.

CONDITION

Indicates that all condition-information-item-name diagnostic items that are set for the last SQL statement executed should be combined into one string. If host-variable5 or integer is supplied after CONDITION, the format is the same as described above for the ALL option. If host-variable5 or integer is not supplied, the format includes a condition number entry at the beginning of the information for that condition in the form:

CONDITION_NUMBER=X;item-name=value-converted-to-character;... where X is the number of the condition, as shown in the following example:

CONDITION_NUMBER=1;RETURNED_SQLSTATE=02000;RETURNED_SQLCODE=100;

  CONDITION_NUMBER=2;RETURNED_SQLSTATE=01004;

CONNECTION

Indicates that all connection-information-item-name diagnostic items that are set for the last SQL statement executed should be combined into one string. If host-variable5 or integer is supplied after CONNECTION, the format is the same as described for the ALL option. If host-variable5 or integer is not supplied, then the format includes a condition number entry at the beginning of the information for that condition in the form:

CONNECTION_NUMBER=X;item-name=value-converted-to-character;... where X is the number of the condition, as shown in the following example:

CONNECTION_NUMBER=1;CONNECTION_NAME=SVL1;DB2_PRODUCT_ID=DSN08010;

host-variable5 or integer

Identifies the diagnostic for which ALL CONDITION or ALL CONNECTION information is requested. The host variable specified must be a numeric data type or an error occurs. An indicator variable is not allowed for this host variable or an error occurs. If a value is specified that is less than or equal to zero or greater than the number of available diagnostics, an error occurs.

Note:

The GET DIAGNOSTICS statement does not change the contents of the diagnostics area (SQLCA). If an SQLSTATE or SQLCODE special variable is declared in the SQL procedure, these are set to the SQLSTATE or SQLCODE returned from issuing the GET DIAGNOSTICS statement. The SQLSTATE and SQLCODE values from before the GET DIAGNOSTICS statement was issued are still available in the diagnostics area by issuing a GET DIAGNOSTICS for RETURNED_SQLSTATE and DB2_RETURNED_SQLCODE.

Data types for GET DIAGNOSTICS items

Item | Data Type
Statement Information
DB2_GET_DIAGNOSTICS_DIAGNOSTICS | VARCHAR(32672)
DB2_LAST_ROW | INTEGER
DB2_NUMBER_PARAMETER_MARKERS | INTEGER
DB2_NUMBER_RESULT_SETS | INTEGER
DB2_NUMBER_ROWS | DECIMAL(31,0)
DB2_RETURN_STATUS | INTEGER
DB2_SQL_ATTR_CURSOR_HOLD | CHAR(1)
DB2_SQL_ATTR_CURSOR_ROWSET | CHAR(1)
DB2_SQL_ATTR_CURSOR_SCROLLABLE | CHAR(1)
DB2_SQL_ATTR_CURSOR_SENSITIVITY | CHAR(1)
DB2_SQL_ATTR_CURSOR_TYPE | CHAR(1)
MORE | CHAR(1)
NUMBER | INTEGER
ROW_COUNT | DECIMAL(31,0)
CATALOG NAME | VARCHAR(128)
CONDITION_NUMBER | INTEGER
CURSOR_NAME | VARCHAR(128)
DB2_ERROR_CODE1 | INTEGER
DB2_ERROR_CODE2 | INTEGER
DB2_ERROR_CODE3 | INTEGER
DB2_ERROR_CODE4 | INTEGER
DB2_INTERNAL_ERROR_POINTER | INTEGER
DB2_MESSAGE_ID | CHAR(10)
DB2_MODULE_DETECTING_ERROR | CHAR(8)
DB2_ORDINAL_TOKEN_n | VARCHAR(515)
DB2_REASON_CODE | INTEGER
DB2_RETURNED_SQLCODE | INTEGER
DB2_ROW_NUMBER | DECIMAL(31,0)
DB2_TOKEN_COUNT | INTEGER
MESSAGE_TEXT | VARCHAR(32672)
RETURNED_SQLSTATE | CHAR(5)
SERVER_NAME | VARCHAR(128)
Connection Information
DB2_AUTHENTICATION_TYPE | CHAR(1)
DB2_AUTHORIZATION_ID | VARCHAR(128)
DB2_CONNECTION_STATE | INTEGER
DB2_CONNECTION_STATUS | INTEGER
DB2_ENCRYPTION_TYPE | CHAR(1)
DB2_PRODUCT_ID | VARCHAR(8)
DB2_SERVER_CLASS_NAMED | CHAR(128)
ALL | VARCHAR(32672)
Note:
  • The GET DIAGNOSTICS statement is supported from a DB2 UDB for z/OS Version 8 client, regardless of the level of the server (a DB2 UDB for z/OS Version 7 or a DB2 UDB for Windows Version 7, for example). When connected to servers that do not support the Open Group Version 3 DRDA standard, a subset of diagnostic information is generated based on the returned SQLCA. The condition contains the following information:
    • The DB2_RETURNED_SQLCODE is set based on the SQLCODE.
    • The RETURNED_SQLSTATE is set based on the SQLSTATE.
    • The DB2_GET_DIAGNOSTICS_DIAGNOSTICS item contains the information from the SQLCA that came from the server.

    Only if you are using multi-row fetch or insert is there a need to have the extended diagnostic information that is provided by servers that support the Open Group Version 3 DRDA standard.

  • To provide compatibility with previous releases of DB2 or other products in the DB2 UDB family, DB2 supports the following keywords:
    • RETURN_STATUS as a synonym for DB2_RETURN_STATUS
    • EXCEPTION as a synonym for CONDITION
Parent topic: SQL Statements


GRANT (Database Privileges)

The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
Restriction: This topic applies to Windows environments only.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. Since the XDB Server does not functionally use these types of privileges, they are not detailed in this reference. Users are encouraged to consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

GRANT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To grant privileges on an object, users must either possess a specific privilege WITH GRANT OPTION for the object, be the owner of the object, or possess overall SYSADM authority for the location. Users with DBADM authority over a database also possess GRANT option privileges on tables (except for views) within that database, provided DBADM authority was acquired with the GRANT option. When embedded in a host language or dynamically prepared, the GRANT command has access to the same privileges held by the CURRENT SQLID of the application process.

Syntax

This format is used to grant privileges on a specified database. Please note that to grant the CREATETAB privilege, you must also grant CREATETS privileges for that database to the same AuthID. One or more privilege option keywords (separated with commas) may be specified after GRANT, allowing multiple privileges to be granted in one statement.

For a TEMP database, PUBLIC implicitly has the CREATETAB privilege (without GRANT authority) to define declared temporary tables; this privilege is not recorded in the DB2 catalog, and it cannot be revoked.

In every case, the privileges chosen are granted only to the logical database(s) named in the GRANT statement.

GRANT
        [DBADM[, ]]
        [DBCTRL[, ]]
        [DBMAINT[, ]]
        [CREATETAB[, ]]
        [CREATETS[, ]]
        [DROP[, ]]
        [STARTDB[, ]]
        [STATS[, ]]
        [STOPDB[, ]]
    ON DATABASE database-name[,...]
    TO [AuthID][,...][PUBLIC]
    [WITH GRANT OPTION]

Parameters:

DBADM | Database administrator authority.
DBCTRL | Database control authority.
DBMAINT | Database maintenance authority.
CREATETAB | Privilege to create new tables.
CREATETS | Privilege to create new table spaces.
DROP | Privilege to issue the DROP or ALTER DATABASE statements for the designated databases.
STARTDB | Privilege to issue the START DATABASE command.
STOPDB | Privilege to issue the STOP DATABASE command.
Note: The DISPLAYDB, IMAGCOPY, LOAD, RECOVERDB, REORG and REPAIR, and STATS database grant/revoke privileges are specific to the DB2 mainframe environment, and control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, the XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.
database-name | Identifies a database on which privileges are to be granted. The grantor must already possess all the privileges specified with the GRANT option, for each database named. Each database named must exist at the current location.
AuthID | Identifies a user authorization ID being granted the privilege(s) specified. The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), granting privileges to all valid authorization IDs at the current location.

Description

The GRANT command is used to confer system, database, table and view privileges to specified AuthID(s). The XDB Server supports three separate formats for the GRANT command, depending on the type of privilege granted. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

The privileges resulting from the execution of a GRANT command statement are recorded as one or more individual grants in the current location system catalog. Each individual grant involves the granting of one privilege by a grantor to one grantee. A grantee can be any AuthID (as recorded in the system catalog for that location), plus the PUBLIC or PUBLIC AT ALL LOCATIONS designations. The status of each privilege granted is recorded in the system catalog for each AuthID.

The same privilege can be granted to a single grantee by several different grantor AuthIDs. The grantee retains the privilege as long as one (or more) of these grants remains recorded in the system catalog. Individual grants (or groups of grants) can be removed from the system catalog by executing REVOKE commands.

WITH GRANT OPTION

If the WITH GRANT OPTION clause is used, the grantee can grant the privileges specified in the GRANT command to other valid AuthIDs. If users attempt to assign GRANT authority to either PUBLIC or PUBLIC AT ALL LOCATIONS, the privileges named in the GRANT command are granted, but without GRANT authority. Specifying WITH GRANT OPTION is valid but unnecessary when granting SYSADM privileges, since whoever is granted this high-level system privilege automatically receives the ability to assign privileges to other AuthIDs.

PUBLIC

Privileges may be granted to a specific set of users by listing their AuthIDs in the TO clause of the GRANT statement. To grant privileges to all system users in the location, use the keyword PUBLIC. To GRANT to all users system-wide, use PUBLIC AT ALL LOCATIONS in the TO clause of the GRANT statement. Users who have not been specifically granted any privileges have only those privileges granted to PUBLIC. When a privilege is granted to PUBLIC, the system continues to maintain the list of user names that have been specifically granted the privilege.

Example:

To grant database administrator (DBADM) authority on the EMPLOYEE database to AuthID usera:

GRANT DBADM
    ON DATABASE employee
    TO usera;
Parent topic: SQL Statements


GRANT (Function or Procedure Privileges)

This form of the GRANT statement grants privileges on user-defined functions, cast functions that are generated for distinct types, and stored procedures.
Restriction: This topic applies to Windows environments only.

Syntax

GRANT EXECUTE ON
{   FUNCTION {function-name [(parameter-type[,...])] | * } |
    SPECIFIC FUNCTION specific-name[,...] |
    PROCEDURE {procedure-name[,...] |
    *
}
    TO {authorization-name[,...] | PUBLIC} [WITH GRANT OPTION]

parameter-type:

{data-type [AS LOCATOR]}

data-type:

{built-in-data-type | distinct-type-name}

built-in-data-type:

SMALLINT |
{INTEGER | INT} |
{DECIMAL | DEC | NUMERIC} [integer[,...]] |
{FLOAT [integer] | REAL [PRECISION] | DOUBLE} |
{ {CHARACTER | CHAR} [(integer)] | {CHARACTER | CHAR} VARYING (integer) | VARCHAR (integer) }
    [FOR {SBCS | MIXED | BIT} DATA] [CCSID {EBCDIC | ASCII}] |
{ {CHARACTER | CHAR} LARGE OBJECT | CLOB} [(integer [K|M|G])] }
    [FOR {SBCS | MIXED} DATA] [CCSID {EBCDIC | ASCII}] } |
{BINARY LARGE OBJECT | BLOB} (integer [K|M|G]) |
{GRAPHIC [(integer)] | VARGRAPHIC (integer) | DBCLOB (integer [K|M|G])} [CCSID {EBCDIC | ASCII}] |
{DATE | TIME | TIMESTAMP} |
ROWID

EXECUTE

Grants the privilege to run the identified user-defined function, cast function that was generated for a distinct type, or stored procedure.

FUNCTION or SPECIFIC FUNCTION

Identifies the function on which the privilege is granted. The function must exist at the current server, and it must be a function that was defined with the CREATE FUNCTION statement or a cast function that was generated by a CREATE DISTINCT TYPE statement.

If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name

Identifies the function by its name. You can identify a function by its name only if there is exactly one function with function name in the schema. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified on unqualified function-name. An * (or schema-name.*) indicates that the privilege is granted on all the functions in the schema including those that do not currently exist. Specifying an * does not affect any EXECUTE privileges that are already granted on a function.

FUNCTION function-name (parameter-type,...)

Identifies the function by its function signature, which uniquely identifies the function.

function-name Specifies the name of the function. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.
(parameter-type,...) Identifies the number of input parameters of the function and their data types.

The data type of each parameter must match the data type that was specified in the CREATE FUNCTION statement for the parameter in the corresponding position. The number of data types and the logical concatenation of the data types is used to uniquely identify the function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that DB2 ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:
    • CHAR implies CHAR(1)
    • GRAPHIC implies GRAPHIC(1)
    • DECIMAL implies DECIMAL(5,0)
    • FLOAT implies DOUBLE (length of 8)

    The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that DB2 ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name

Identifies the function by its specific name.

PROCEDURE procedure-name

Identifies a stored procedure that is defined at the current server. If you do not explicitly qualify the procedure name with a schema name, the procedure name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified or unqualified procedure-name. An * (or schema-name.*) indicates that the privilege is granted on all the stored procedures in the schema including those that do not currently exist. Specifying an * does not affect any EXECUTE privileges that are already granted on a stored procedure.

Example:

Grant the EXECUTE privilege on function CALC_SALARY to user JONES. Assume that there is only one function in the schema with function name CALC_SALARY.

GRANT EXECUTE ON FUNCTION CALC_SALARY TO JONES;

Grant the EXECUTE privilege on procedure VACATION_ACCR to all users at the current server.

GRANT EXECUTE ON PROCEDURE VACATION_ACCR TO PUBLIC;

Grant the EXECUTE privilege on function DEPT_TOTALS to the administrative assistant and give the assistant the ability to grant the EXECUTE privilege on this function to others. The function has the specific name DEPT85_TOT. Assume that the schema has more than one function that is named DEPT_TOTALS.

GRANT EXECUTE ON SPECIFIC FUNCTION DEPT85_TOT TO ADMIN_A
    WITH GRANT OPTION;

Grant the EXECUTE privilege on function NEW_DEPT_HIRES to HR (Human Resources). The function has two input parameters with data types of INTEGER and CHAR(10), respectively. Assume that the schema has more than one function that is named NEW_DEPT_HIRES.

GRANT EXECUTE ON FUNCTION NEW_DEPT_HIRES (INTEGER, CHAR(10))
    TO HR;

You can also code the CHAR(10) data type as CHAR().

Parent topic: SQL Statements
Related information
GRANT (Table or View Privileges)
GRANT (System Privileges)
GRANT (Database Privileges)


GRANT (Table or View Privileges)

The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
Restriction: This topic applies to Windows environments only.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. Since the XDB Server does not functionally use these types of privileges, they are not detailed in this reference. Users are encouraged to consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

GRANT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To grant privileges on an object, users must either possess a specific privilege WITH GRANT OPTION for the object, be the owner of the object, or possess overall SYSADM authority for the location. Users with DBADM authority over a database also possess GRANT option privileges on tables (except for views) within that database, provided DBADM authority was acquired with the GRANT option. When embedded in a host language or dynamically prepared, the GRANT command has access to the same privileges held by the CURRENT SQLID of the application process.

Syntax

This format is used to grant privileges on individual tables or views. One or more of the privilege keywords defined below (separated with commas) or the optional keyword(s) ALL [PRIVILEGES] may be specified after GRANT, allowing multiple table privileges to be evoked in one GRANT statement. Does not include ALTER, INDEX, REFERENCES, or TRIGGER for a grant to PUBLIC AT ALL LOCATIONS.

GRANT
{
        [ALTER[, ]]
        [DELETE[, ]]
        [INDEX[, ]]
        [INSERT[, ]]
        [SELECT[, ]]
        [UPDATE [(column-name[,...])]]
        [TRIGGER]
        [REFERENCES [(column-name [,...])]]
        | ALL [PRIVILEGES]
}
    ON [TABLE] {table-name[,...] | view-name[,...]}
    TO [AuthID][,...][PUBLIC [AT ALL LOCATIONS]]
    [WITH GRANT OPTION]

This format is used to grant privileges on individual tables or views. One or more of the privilege keywords defined below (separated with commas) or the optional keyword(s) ALL [PRIVILEGES] may be specified after GRANT, allowing multiple table privileges to be evoked in one GRANT statement. Does not include ALTER, INDEX, REFERENCES, or TRIGGER for a grant to PUBLIC AT ALL LOCATIONS.

GRANT
{
        [ALTER[, ]]
        [DELETE[, ]]
        [INDEX[, ]]
        [INSERT[, ]]
        [SELECT[, ]]
        [UPDATE [(column-name[,...])]]
        [TRIGGER]
        [REFERENCES [(column-name [,...])]]
        | ALL [PRIVILEGES]
}
    ON [TABLE] {table-name[,...] | view-name[,...]}
    TO [AuthID][,...][PUBLIC [AT ALL LOCATIONS]]
    [WITH GRANT OPTION]

Parameters:

ALTER | Privilege to use the ALTER TABLE statement ALTER cannot be granted to PUBLIC AT ALL LOCATIONS. (cannot specify an auxiliary table or view).
DELETE | Privilege to use the DELETE statement.
INDEX | Privilege to use the CREATE INDEX statement (cannot specify a view).
INSERT | Privilege to use the INSERT statement (cannot be granted on an auxiliary table.)
SELECT | Privilege to use the SELECT statement. (cannot be granted on an auxiliary table.)
UPDATE | Privilege to use the UPDATE statement on all columns of the tables named in the ON clause. When followed by (column-name[,...]), the update privilege applies only to the columns specified in parentheses.( must not identify a column of an auxiliary table.)
REFERENCES | Privilege to create/drop a foreign key. (cannot specify an auxiliary table or view).
column-name | Specifies an individual column in a table for which the UPDATE or the REFERENCES privilege is being granted. If you specify a list of columns after the REFERENCES keyword, each column-name must be the unqualified name of a column in a table that is identified in the ON clause.
table-name or view-name | Preceded by the keyword(s) ON [TABLE], identifies a table or view affected.
authID | Identifies a user authorization ID being granted the privilege(s) specified. The optional PUBLIC [AT ALL LOCATIONS] keyword(s) can be specified along with (or in place of) an AuthID (or a list of AuthIDs). The PUBLIC AT ALL LOCATIONS keyword option grants the specified table privileges to all users at every location.
Note:

To grant privileges to all tables (or views) contained within a database, simply grant the privilege to the database.

If the ALL [PRIVILEGES] keywords are specified following GRANT, all table or view privileges (for which the issuer has GRANT authority) are granted for the objects identified in the ON clause.

In every case, the privileges specified are granted only on the tables or views named in the ON [TABLE] clause. Multiple table and/or view names can be listed, provided they are separated by commas. Table privileges may be granted by users possessing DBADM for the database or by the creator of the table or view the privilege is granted on. ALTER or INDEX privileges are not included in a grant to PUBLIC AT ALL LOCATIONS.

For an auxiliary table, only the INDEX privilege can be granted. DELETE, INSERT, SELECT, and UPDATE privileges on the base table that is associated with the auxiliary table extend to the auxiliary table.

Description

The GRANT command is used to confer system, database, table and view privileges to specified AuthID(s). The XDB Server supports three separate formats for the GRANT command, depending on the type of privilege granted. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

The privileges resulting from the execution of a GRANT command statement are recorded as one or more individual grants in the current location system catalog. Each individual grant involves the granting of one privilege by a grantor to one grantee. A grantee can be any AuthID (as recorded in the system catalog for that location), plus the PUBLIC or PUBLIC AT ALL LOCATIONS designations. The status of each privilege granted is recorded in the system catalog for each AuthID.

The same privilege can be granted to a single grantee by several different grantor AuthIDs. The grantee retains the privilege as long as one (or more) of these grants remains recorded in the system catalog. Individual grants (or groups of grants) can be removed from the system catalog by executing REVOKE commands.

WITH GRANT OPTION

If the WITH GRANT OPTION clause is used, the grantee can grant the privileges specified in the GRANT command to other valid AuthIDs. If users attempt to assign GRANT authority to either PUBLIC or PUBLIC AT ALL LOCATIONS, the privileges named in the GRANT command are granted, but without GRANT authority. Specifying WITH GRANT OPTION is valid but unnecessary when granting SYSADM privileges, since whoever is granted this high-level system privilege automatically receives the ability to assign privileges to other AuthIDs.

PUBLIC

Privileges may be granted to a specific set of users by listing their AuthIDs in the TO clause of the GRANT statement. To grant privileges to all system users in the location, use the keyword PUBLIC. To GRANT to all users system-wide, use PUBLIC AT ALL LOCATIONS in the TO clause of the GRANT statement. Users who have not been specifically granted any privileges have only those privileges granted to PUBLIC. When a privilege is granted to PUBLIC, the system continues to maintain the list of user names that have been specifically granted the privilege.

Example:

The example below grants authority for the individuals with the AuthIDs userb and userc to update the PART table.

GRANT UPDATE
    ON part
    TO userb, userc

To grant privileges to all users in the location to select, update, insert, and delete records from the PART and SUPPLIER tables, use the command:

GRANT SELECT, UPDATE, INSERT, DELETE
    ON part, supplier
    TO PUBLIC

To grant privileges on a subset of the columns in the EMPLOYEE table to usera, and at the same time give usera the ability to grant the privilege to other users, issue the command:

GRANT UPDATE(address, city, state, zip, phone)
    ON employee
    TO usera
    WITH GRANT OPTION

In this case AuthID usera does not have the ability to update employee number, name, department, or pay rate values.

To grant all privileges on the EMPLOYEE table to AuthID usera:

GRANT ALL
    ON TABLE employee
    TO usera;
Parent topic: SQL Statements
Related information
REVOKE (Table or View Privileges)
GRANT (Database Privileges)
GRANT (System Privileges)
GRANT (Function or Procedure Privileges)


GRANT (Sequence Privileges)

This form of the GRANT statement grants privileges on a user-defined sequence.
Restriction: This topic applies to Windows environments only.

Syntax

GRANT {ALTER | USAGE} [,...] ON SEQUENCE sequence-name [,...]
TO {authorization-name | PUBLIC} [,...] [WITH GRANT OPTION]
Note: The keyword SELECT is an alternative keyword for USAGE.

Description

ALTER

Grants the privilege to alter a sequence or record a comment on a sequence.

USAGE

Grants the USAGE privilege to use a sequence. This privilege is needed when the NEXT VALUE or PREVIOUS VALUE expression is invoked for a sequence name.

SEQUENCE sequence-name

Identifies the sequence. The name, including the implicit or explicit schema qualifier, must uniquely identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs. sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column.

TO

Specifies to what authorization IDs the privileges are granted.

authorization-name,...

Lists one or more authorization IDs. The value of CURRENT RULES determines whether you can use the ID of the GRANT statement itself (to grant privileges to yourself). When CURRENT RULES is:

DB2 | You cannot use the ID of the GRANT statement.
STD | You can use the ID of the GRANT statement.

PUBLIC

Grants the privileges to all users at the current server, including database requesters using DRDA access.

PUBLIC AT ALL LOCATIONS

Grants the privileges to all users in the network. Applies to table privileges only, excluding ALTER, INDEX, REFERENCES, and TRIGGER. PUBLIC AT ALL LOCATIONS applies to DB2 private protocol access only.

WITH GRANT OPTION

Allows the named users to grant the privileges to others. Granting an administrative authority with this option allows the user to specifically grant any privilege belonging to that authority. If you omit WITH GRANT OPTION, the named users cannot grant the privileges to others unless they have that authority from some other source. GRANT authority cannot be passed to PUBLIC or to PUBLIC AT ALL LOCATIONS. When WITH GRANT OPTION is used with either of these, a warning is issued, and the named privileges are granted, but without GRANT authority.

Parent topic: SQL Statements


GRANT (System Privileges)

The GRANT command confers database, table or view, and system privileges to AuthIDs. The XDB Server supports three separate GRANT statement formats for granting database, table and system privileges. All relevant objects must be located in the current location's catalog tables. Granted privileges are recorded in the system catalog for the current location. Specific privileges may later be revoked (see REVOKE statement).
Restriction: This topic applies to Windows environments only.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. Since the XDB Server does not functionally use these types of privileges, they are not detailed in this reference. Users are encouraged to consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

GRANT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To grant privileges on an object, users must either possess a specific privilege WITH GRANT OPTION for the object, be the owner of the object, or possess overall SYSADM authority for the location. Users with DBADM authority over a database also possess GRANT option privileges on tables (except for views) within that database, provided DBADM authority was acquired with the GRANT option. When embedded in a host language or dynamically prepared, the GRANT command has access to the same privileges held by the CURRENT SQLID of the application process.

Syntax

This format is used to grant system privileges. In every case, the system privileges specified are granted only to the AuthID(s) specified in the TO clause. One or more of the privilege option keywords defined below (separated with commas) may be specified after GRANT, allowing multiple system privileges to be granted in one GRANT statement.

GRANT
        [CREATEALIAS[, ]]
        [CREATEDBA[, ]]
        [CREATEDBC[, ]]
        [CREATETMTAB[, ]]
        [CREATESG[, ]]
        [SYSADM[, ]]
        [SYSCTRL[, ]]
    TO [AuthID][,...][PUBLIC]
    [WITH GRANT OPTION]

This format is used to grant system privileges. In every case, the system privileges specified are granted only to the AuthID(s) specified in the TO clause. One or more of the privilege option keywords defined below (separated with commas) may be specified after GRANT, allowing multiple system privileges to be granted in one GRANT statement.

GRANT
        [CREATEALIAS[, ]]
        [CREATEDBA[, ]]
        [CREATEDBC[, ]]
        [CREATETMTAB[, ]]
        [CREATESG[, ]]
        [SYSADM[, ]]
        [SYSCTRL[, ]]
    TO [AuthID][,...][PUBLIC]
    [WITH GRANT OPTION]

Parameters:

CREATEALIAS | Privilege to use the CREATE ALIAS statement.
CREATEDBA | Privilege to issue the CREATE DATABASE statement and acquire DBADM authority over those databases.
CREATEDBC | Privilege to issue the CREATE DATABASE statement and acquire DBCTRL authority over those databases.
CREATETMTAB | Privilege to issue the CREATE GLOBAL TEMPORARY TABLE statement.
CREATESG | Privilege to create new storage groups.
SYSADM | Grants system administrator authority for the location, which includes all privileges except for a few reserved for INSTALL authority. These privileges are all grantable, including the SYSADM authority itself.
SYSCTRL | Grants the system control authority for the location, allowing the holder most of the privileges of a system administrator, but excluding privileges to read or change user data.
Note:

The ARCHIVE, BINDADD, BINDAGENT, BSDS, DISPLAY, MONITOR1, MONITOR2, RECOVER, STOPALL, STOSPACE, SYSOPR, and TRACE system privileges are specific to the DB2 mainframe environment, and control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, the XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.

AuthID Identifies a user authorization ID being granted the specified privilege(s). The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), granting privileges to each valid AuthID at the current location.

Description

The GRANT command is used to confer system, database, table and view privileges to specified AuthID(s). The XDB Server supports three separate formats for the GRANT command, depending on the type of privilege granted. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

The privileges resulting from the execution of a GRANT command statement are recorded as one or more individual grants in the current location system catalog. Each individual grant involves the granting of one privilege by a grantor to one grantee. A grantee can be any AuthID (as recorded in the system catalog for that location), plus the PUBLIC or PUBLIC AT ALL LOCATIONS designations. The status of each privilege granted is recorded in the system catalog for each AuthID.

The same privilege can be granted to a single grantee by several different grantor AuthIDs. The grantee retains the privilege as long as one (or more) of these grants remains recorded in the system catalog. Individual grants (or groups of grants) can be removed from the system catalog by executing REVOKE commands.

WITH GRANT OPTION

If the WITH GRANT OPTION clause is used, the grantee can grant the privileges specified in the GRANT command to other valid AuthIDs. If users attempt to assign GRANT authority to either PUBLIC or PUBLIC AT ALL LOCATIONS, the privileges named in the GRANT command are granted, but without GRANT authority. Specifying WITH GRANT OPTION is valid but unnecessary when granting SYSADM privileges, since whoever is granted this high-level system privilege automatically receives the ability to assign privileges to other AuthIDs.

PUBLIC

Privileges may be granted to a specific set of users by listing their AuthIDs in the TO clause of the GRANT statement. To grant privileges to all system users in the location, use the keyword PUBLIC. To GRANT to all users system-wide, use PUBLIC AT ALL LOCATIONS in the TO clause of the GRANT statement. Users who have not been specifically granted any privileges have only those privileges granted to PUBLIC. When a privilege is granted to PUBLIC, the system continues to maintain the list of user names that have been specifically granted the privilege.

Example:

The following example grants SYSADM authority for the TUTORIAL location to the individual with the AuthID usera. With SYSADM authority AuthID usera acquires authority to perform all functions on the TUTORIAL location, including authority to grant privileges.

GRANT SYSADM TO usera
Parent topic: SQL Statements


HALT QUERY FROM

Use the HALT QUERY FROM command to terminate a running query. You can specify the query by user ID or by node name. This command is useful for canceling a query operation that is monopolizing the server computer.
Restriction: This topic applies to Windows environments only.
Note:

The HALT QUERY FROM command affects only running queries--ones that are literally in process on the XDB Server at the moment the command is issued. It does not cancel queries that are not actively under execution; for example, ones in which the client is simply fetching records from a result table. A query in this state is active, but is not running on the server. To cancel a query in this state, you must terminate it from the client application or force the user off the system using the XDB Server Monitor.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following

  • The owner of the query
  • A super user
  • A user with SYSADM or SYSCTRL privileges

Syntax

HALT QUERY FROM USER user-name

or ...

HALT QUERY FROM node-name

Parameters:

user-name | Is the user ID of the user (or program) that initiated the query. The HALT QUERY FROM USER command cancels all running queries for the specified ID. For example, if three users were each running a query program that logged on to the server using the same ID, all three queries would be canceled. If you need to cancel one specific user's query, use HALT QUERY FROM node-name instead
node-name | Is the name of the node from which the query was issued. To display a list of the active node names, use the XDB Server Monitor or query the Virtual Statistics table (XDBSTAT.USERLIST). Specify the entire name of the node as displayed by the XDB Server Monitor or listed in the Virtual Statistics table, including the :number part of the name
Parent topic: SQL Statements


HOLD LOCATOR

The HOLD LOCATOR statement allows a LOB locator variable to retain its association with a value beyond a unit of work. The XDB operating environment does not support the LOB data type at this time.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be embedded in an application program. It cannot be issued interactively. It is an executable statement that can be dynamically prepared. However, the EXECUTE statement with the USING clause must be used to execute the prepared statement. HOLD LOCATOR cannot be used with the EXECUTE IMMEDIATE statement.

Authorization

None required.

Syntax

HOLD LOCATOR {host-variable}

Description:

host_variable,...

Identifies a host-variable locator variable that must have been previously declared according to the rules for declaring host variables. The locator variable type must be a binary large object locator, a character large object locator, or a double-byte character large object locator.

After the HOLD LOCATOR statement is executed, each locator variable in the host-variable list has the hold property. If a locator variable is not an established locator within the current unit of work, an invalid locator error occurs. When this error occurs and more than one host variable was specified in the HOLD LOCATOR statement, only the locators up to the first invalid locator are held. Locators listed after the first invalid locator are not held.

A host-variable LOB locator variable that has the hold property is freed (has its association between it and its value removed) when:

  • The SQL FREE LOCATOR statement is executed for the locator variable.
  • The SQL ROLLBACK statement is executed.
  • The SQL session is terminated.

Example:

Assume that the employee table contains columns RESUME, HISTORY, and PICTURE and that locators have been established in a program to represent the values represented by the columns. Give the CLOB locator variables LOCRES and LOCHIST, and the BLOB locator variable LOCPIC the hold property.

EXEC SQL HOLD LOCATOR :LOCRES, :LOCHIST, :LOCPIC
Parent topic: SQL Statements


INCLUDE

The INCLUDE statement (embedded SQL only) inserts declarations or code into source programs from external files.
Restriction: This topic applies to Windows environments only.

Invocation

INCLUDE can only be embedded in a host language. INCLUDE is not an executable command and cannot be dynamically prepared.

Authorization

No special authorization is needed for INCLUDE.

Syntax

INCLUDE {SQLCA | SQLDA | member-name}

Parameters:

member-name The member name (or file name) can contain any host language source statements or SQL statements, except the INCLUDE statement. In COBOL, the statement "INCLUDE member-name" must not appear anywhere other than the DATA DIVISION or the PROCEDURE DIVISION section. See your XDB Server precompiler documentation for specifics about the member-name parameter.

Description

The INCLUDE statement is used to bring external files (containing either data definitions or segments of program code that must be precompiled) into an application. When precompiled, the INCLUDE statement is replaced by the source statements. The INCLUDE statement must therefore be specified at a point in the application program where the resulting source statements are accepted by the compiler. The INCLUDE statement cannot introduce source statements that themselves contain INCLUDE statements. Depending on the host language used, INCLUDE can also identify SQL communication and descriptor areas.

SQLCA

Indicates an SQL communication area (SQLCA) description is to be included. Do not specify INCLUDE SQLCA more than once in the same application program. See XDB Server SQL Communications Area (SQLCA) for more information about the SQLCA.

SQLDA

Indicates an SQL descriptor area (SQLDA) description is to be included. See XDB Server SQL Descriptor Area (SQLDA) for more information about the SQLDA.

Example:

The file must reside in the directory specified by the environment variable COBCPY (Micro Focus) or SYSLIB (CA-Realia II). The XDB Server precompiler looks for the file extensions .CPY and .CBL if the XDBCPY directive is active. With CA-Realia II, the XDB Server precompiler looks for the .COB extension by default. Consult your XDB Server precompiler documentation for further details.

EXEC SQL
    INCLUDE emprec
END-EXEC
Parent topic: SQL Statements


INSERT

The INSERT command is an SQL command used to insert zero or more rows of data values (or records) into an existing table or view. The table or view receiving the new rows can be at the current location or any other location accessible to the XDB Server. Inserting a row into a view also inserts the row into that view's underlying table (if the view is updatable).
Restriction: This topic applies to Windows environments only.

Invocation

INSERT is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

Authority requirements depend on whether the object identified in the statement is a table or view. When rows are inserted into a table, the privileges held by the user must include either the INSERT privilege on the table, ownership of the table, DBADM authority on the database containing the table, or overall SYSADM authority for the location. When rows are inserted into a view, the privileges held by the user must include either the INSERT privilege on the view, or overall SYSADM authority.

Users should be aware that a view owner (unlike a table owner) may not have INSERT authority on the view, since the nature of the view itself could preclude its use for INSERT. Alternatively, the view owner might possess INSERT authority, but be unable to grant it to others. Additionally, if a subselect is specified, the user must possess authority to execute the subselect.

If the INSERT command is prepared at a location other than the current location, the total available privileges include all privileges recorded in the system catalog where the INSERT is executed.

If an expression that refers to a function is specified, the privilege set must include any authority that is necessary to execute the function.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke.)

Syntax

INSERT INTO {table-name | view-name}
    [(column-name [,...])]
    [OVERRIDING USER VALUE]
    {VALUES {{expression | DEFAULT | NULL} | ({expression | DEFAULT | NULL}[,...]) |
    [WITH common-table-expression [,...]] fullselect [isolation-clause] [QUERYNO integer] |
    multiple-row-insert}

isolation-clause

WITH {RR | RS | CS

multiple-row-insert

VALUES {expression | host-variable-array | NULL | DEFAULT |
    ({expression | host-variable-array | NULL | DEFAULT} [,...]})
    [FOR [host-variable | integer-constant] ROWS]
    [ATOMIC | NOT ATOMIC CONTINUE ON SQLEXCEPTION]

Parameters:

table-name or view-name | Preceded by the keyword INTO, identifies the object (table or view) of the INSERT statement. If a view, the view must be updatable, in which case the underlying table is affected. A catalog table (or a view of a catalog table) or an auxiliary table cannot be specified.
column-list | Specifies an optional list of columns into which the data is to be inserted. The column list, if specified, must be enclosed in parentheses, with each column name separated by a comma. If the column list is omitted, all columns in the target table or view are assigned values -- proceeding in order from left to right.
value-list | Preceded by the keyword VALUES, specifies one row of values (composed of constants, host-variables, NULLs, or special-registers) to be inserted into the target table or view. Each host variable named must represent a declared variable or structure, properly described in the application program in accordance with the rules for declaring variables and structures in the host language.
subselect | Indicates a subselect that retrieves data from another table to insert into the table named in the INSERT command. The same table cannot be the base object of both the INSERT command and the subselect (or any subquery of the subselect). An INSERT command cannot include both a subselect statement and a VALUES clause.

Tables referenced in all selects (or subselects) contained in a single INSERT command must be from the same location as the table or view into which data is being inserted. That is, you cannot INSERT into the TUTORIAL location and select from the DEBLOC location.

Invalid:

INSERT INTO tutorial.tutorial.practice
    SELECT * FROM debloc.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM debloc.debbie.employee
                WHERE st = "MD";

Valid:

INSERT INTO tutorial.tutorial.practice
    SELECT * FROM tutorial.tutorial.employee
        WHERE e_no IN
            SELECT e_no FROM tutorial.debbie.employee
                WHERE st = "MD";

Description

The INSERT command is used to insert one or more record(s) into an existing table. Data inserted with the INSERT command can be specified by the user in the INSERT command or retrieved from other tables using a subselect statement. The INSERT command takes on one of the following two configurations:

  • The INSERT statement using the VALUES keyword inserts a single row into the table or view, using the values provided or referenced.
  • The INSERT statement with a subselect inserts zero or more rows into the table or view, using values retrieved from other tables and/or views by the subselect.

OVERRIDING USER VALUE

Specifies that the value specified in the VALUES clause or produced by a subselect for a column that is defined as GENERATED ALWAYS is ignored. Instead, a system-generated value is inserted, overriding the user-specified value.

Specify OVERRIDING USER VALUE only if the insert involves a column defined as GENERATED ALWAYS, such as a ROWID column or an identity column.

VALUES

The number of individual data items in the VALUES clause must equal the number of items in the column list. The first data item in the value list is inserted in the first column in the column list, the second value in the second column, etc. A value list must be included if a subselect is not specified. The value list must be enclosed in parentheses. Values must be separated from each other by commas. Character strings should appear in quotes (single or double). If the value to be inserted in a column is null, the keyword NULL should appear in the appropriate location in the value list.

expression | Any expression of the type described in "Expressions" in topic 3.19. The expression must not include a column name. If expression is a single host variable, the host variable can identify a structure. Any host variable or structure that is specified must be described in the application program according to the rules for declaring host structures and variables.
DEFAULT | The default value assigned to the column. If the column is a ROWID column or an identity column, DB2 will generate a unique value for the column. You can specify DEFAULT only for columns that have an assigned default value, ROWID columns, and identity columns.
NULL | The null value.

WITH Clause

Overrides the isolation level of the statement using the WITH {RR | CS} clause, specifying the isolation level with which a searched INSERT statement is executed. The WITH clause specifies an isolation level only for the INSERT statement in which it appears. WITH UR only applies to read only operations, and cannot be used in INSERT statements. The WITH clause overrides the default isolation level for the statement in which it appears.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Data Compatibility

If the insert value for a column is a number, the column must be configured as a numeric data type column with the capability of representing the integral part of the inserted number value. If the insert value for a column is a string, the column must be configured either as a string column (with a length greater than or equal to the string length) or a datetime column (if the string represents a date, time, or timestamp).

If a table (or the base table of a view) named in an INSERT statement contains unique indexes, then each row of values inserted into the table must comply with the uniqueness constraints imposed by these indexes. If the table has a check constraint, each row of data must comply with the check condition.

When a view named in an INSERT statement includes a WITH CHECK OPTION clause in its definition, each row inserted into the view must comply with the view as specified in its definition. If the named view contains other views in its definition -- and these views happen to contain WITH CHECK OPTION clauses in their definitions, the row data values inserted must also comply with these other views as specified in their definitions. An INSERT statement might cause triggers to be activated. A trigger might cause other statements to be executed or raise error conditions based on the insert values.

A named view with no WITH CHECK OPTION clause in its definition can allow nonconforming rows to be inserted into the view's base table(s). However, these rows cannot be retrieved again using the view. Additionally, each non-null insert value must conform to any foreign and parent key relationships defined for target tables -- such that a value inserted into a column defined as a foreign key must equal some value in the primary key column of the parent table.

Locking

Unless appropriate locks already exist, one or more exclusive locks are acquired at the execution of a successful INSERT statement. Until a commit or rollback operation releases the locks, only the application process that performed the insert can access the inserted row. If LOBs are not inserted into the row, application processes that are running with uncommitted read can also access the inserted row. The locks can also prevent other application processes from performing operations on the table. However, application processes that are running with uncommitted read can access locked pages and rows.

Example:

An example of the INSERT command is:

INSERT INTO part
    VALUES ("P7", "WHEEL", "WHITE", 2, "ATHENS")

This statement inserts P7, a two pound white wheel made in Athens, into table PART. To perform this operation correctly, you must enter the data in exactly the order it is to appear in the table. If the column list is specified, it determines the insertion sequence.

To insert a NULL (empty) value, enter NULL in the appropriate column location of the INSERT command statement. Any table column can record inserted NULL values, unless a CREATE or ALTER TABLE command originally defined the column as either NOT NULL or NOT NULL WITH DEFAULT. In the later case, NULL values can be inserted, but will not be recorded in the table (the default values for the column data type will be recorded instead). For example, if the weight and color of the part we are about to insert are not known, type:

INSERT INTO part
    VALUES ("P7", "WHEEL", NULL, NULL, "ATHENS")

If a value list is not specified for the INSERT command, a SELECT command must be specified. The order of the columns selected must match the order in the column list specification. However, the number of columns selected does not need to match the number of columns defined in the column list. If the column list has more columns than the SELECT command, the extra columns will be assigned NULL values. If the column list has fewer columns than the SELECT command, the system will use only as many columns as are available.

The columns selected do not need to match the data type of the column list. They must, however, be type compatible. See the ALTER TABLE command for the definition of compatible conversions.

Try the following sequence of commands using the part-supplier database. First enter the command:

CREATE TABLE bluparts(pno CHAR 2, pname CHAR 5)

This creates a new table called BLUPARTS. Next enter the command:

INSERT INTO bluparts
    (pno, pname)
    SELECT pno, pname
        FROM part
        WHERE color = "blue"

Note that because the PART table has a different number of columns than the BLUPARTS table, you should be careful when specifying the columns selected from the PART table to insert into the BLUPARTS table.

Parent topic: SQL Statements


LABEL ON

The LABEL ON statement adds or replaces descriptive text labels in the system catalog for the current location. These text labels describe tables, views, aliases, or columns existing at the current location.
Restriction: This topic applies to Windows environments only.

Invocation

LABEL ON is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the LABEL ON command, users must possess either DBADM authority on the database, overall SYSADM or SYSCTRL authority for the location, or be the owner of the table, view, or alias affected.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke.)

Syntax

LABEL ON
{
    TABLE {table-name | view-name} |
    ALIAS alias-name |
    COLUMN {table-name.column-name | view-name.column-name}
}
    IS string-constant

Use the following syntax of the LABEL ON command when labeling more than one column per statement.

LABEL ON {table-name | view-name}
    (column-name IS string-constant[,...])

Parameters:

table-name or view-name | Identifies the table or view described by the label (string-constant).
alias-name | Identifies the alias to which the comment (string-constant) applies.
column-name | Preceded with an optional qualifier of [table-name.] or [view-name.], identifies a column to which the comment (string-constant) applies.
string-constant | Preceded by the keyword IS, any character string constant (up to 30 bytes in length) enclosed in quotes.

Description

Choose one of the following object keywords (with corresponding object name) for labeling in the system catalog.

TABLE

Keyword indicating that a table or view is being labeled. The identified object must exist at the current location. The string-constant specified in the LABEL ON command is recorded in the SYSIBM.SYSTABLES catalog table, in the LABEL column of the row describing the table or view. table-name must not identify a declared temporary table.

ALIAS

Keyword indicating that an alias is being labeled. The alias identified must exist at the current location. The string-constant specified in the LABEL ON command is recorded in the SYSIBM.SYSTABLES catalog table, in the LABEL column of the row describing the alias.

COLUMN

Keyword indicating that a column is being labeled. The column identified must belong to a table or view existing at the current location. The string-constant specified in the LABEL ON command is recorded in the SYSIBM.SYSCOLUMNS catalog table -- in the LABEL column of the row describing the column. The column name must not identify a column of a declared temporary table.

Parent topic: SQL Statements


LOCK TABLE

The LOCK TABLE statement is used to acquire a shared or exclusive lock on a table at the current location.
Restriction: This topic applies to Windows environments only.

Invocation

LOCK TABLE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the LOCK TABLE command, users must either possess DBADM authority on the database, overall SYSADM or SYSCTRL authority for the location, SELECT privilege on the table identified, or be the owner of the table.

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke.)

Syntax

Bold text indicates clauses or options that are supported only syntactically.

LOCK TABLE table-name [PARTITION integer]
    IN {SHARE | EXCLUSIVE} MODE

Parameters:

table-name Identifies the table to be locked. The table must exist at the current server, and cannot be a view, temporary table (created or declared) or system catalog table.

Description

Locking is effective in multi-user environments only. However, the command is accepted in single-user environments, so that you can run your applications unchanged in either environment. The XDB Server automatically acquires record level locks as required during processing, so it is not necessary to acquire table level locks. However, table level locks may reduce the amount of time required to process large numbers of records in the same table. Two table locking modes are supported: exclusive and shared. All types of locks are released by a ROLLBACK or COMMIT command. For more information about the use of locks, see the Server Administration Guide.

IN EXCLUSIVE MODE

The keyword EXCLUSIVE is used to acquire an exclusive lock on an existing table, usually when the intent of the transaction is to modify a number of records in the table. Until the lock is released, it prevents concurrent processes from executing any operations on the table. However, unless the lock is on a LOB table space, concurrent processes that are running at an isolation level of uncommitted read (UR) can execute read-only operations on the table.

When an exclusive table level lock is acquired, update transactions progress more quickly because there is no delay waiting for individual record level locks. However, an exclusive lock may take longer to acquire, and it does reduce concurrency by preventing any other transactions from accessing the locked table. For these reasons, the exclusive mode should be reserved for use by high volume record update transactions or when a transaction has a high priority. The loss of concurrency and the possible need to undo many changes when the transaction is rolled back can be minimized by keeping transactions as short as possible.

IN SHARE MODE

The keyword SHARE is used to acquire a shared lock on an existing database table, usually when the intent of the transaction is to read many records or perform repeatable reads. When a shared lock is acquired on a table, other users may read the records in that table, but cannot perform inserts, updates or deletes. Other users must acquire an exclusive record level lock on the table first, before executing INSERT, UPDATE and DELETE transactions.

All table level locks may be released by the UNLOCK TABLE command. The XDB Server protects against deadlock by regulating the persistency of lock requests. You can change the timeout interval through the Options utility. A single attempt to acquire a lock will last no longer than the period specified.

Example:

The example below shows the command to acquire an exclusive lock on the PART table:

LOCK TABLE part IN EXCLUSIVE MODE

The next example shows the command to acquire a shared lock on the PARTSUPP table:

LOCK TABLE partsupp IN SHARE MODE

Acquiring a table lock on a table ensures the correctness of "repeatable reads." For example, the query

SELECT SUM(qty)
    FROM partsupp

will be correct because no other transaction will have the opportunity to change values in the QTY column while the lock is held.

Parent topic: SQL Statements


OPEN

The OPEN command (embedded SQL only) opens a previously declared cursor creating a result table containing row data.
Restriction: This topic applies to Windows environments only.

Invocation

OPEN is an executable command that can only be embedded in a host language. OPEN cannot be dynamically prepared.

Authorization

The privileges required to execute an OPEN statement correspond to those privileges required for declaring the cursor being opened. See the authorization description under the DECLARE CURSOR command.

Syntax

OPEN cursor-name
    [USING {host-variable[,...]
    | DESCRIPTOR descriptor-name }]

Parameters:

cursor-name | Identifies a previously declared cursor.
host-variable | Identifies a variable described in the application program in accordance with the rules for declaring host variables.
descriptor-name | Preceded by the keyword DESCRIPTOR, identifies an SQLDA containing a valid description of application program host variables, which contains certain field values that must be set in order prior to executing an OPEN statement.

Description

The cursor must be in the closed state in order to execute an OPEN command. The OPEN command has two basic configurations. The first syntax format is the simple OPEN command, consisting of the keyword OPEN followed by the name of a previously declared cursor name. The second syntax format is used in dynamic SQL applications, and includes a USING clause. The USING clause introduces either a list of host variables (previously defined in the application) or an SQL Descriptor Area (SQLDA) also containing host variable information (including SELECT statement column information) previously described into the SQLDA. (See the DESCRIBE command.)

The cursor select statement can either be a SELECT statement specified in the DECLARE CURSOR statement or a previously prepared (see PREPARE command) SELECT statement identified by a statement name, which can also be specified in the DECLARE CURSOR statement. The OPEN command evaluates the cursor select statement and determines a result table for that cursor. This result table includes current values of any special registers specified in the cursor select statement, as well as the current values of any host variables specified in either the cursor select statement or the USING clause of the OPEN statement.

Result table rows can be determined either during the execution of the OPEN statement (in which case a temporary table will be created to hold them) or these rows can be determined during the execution of subsequent FETCH statements preformed on the opened cursor. In either case, the cursor is opened, and the cursor pointer is positioned before the first row of the result table. If the table happens to be empty, the cursor pointer is considered to be positioned after the last (nonexistent) row. The XDB Server does not alert users to an empty result table when the OPEN statement is executed, but does indicate an empty table by returning an SQLCODE value of +100 upon execution of the first FETCH statement on that result table.

USING

Before the OPEN statement is executed, each target parameter marker in the cursor query is assigned the value of its corresponding host variable. The USING clause introduces a list of host variables whose values are substituted for the parameter markers (question mark characters) appearing in a prepared SELECT statement. The number of host variables must equal the number of parameter markers. The USING clause must be specified if the DECLARE CURSOR statement names a prepared statement containing parameter markers. If the prepared statement has no parameter markers, the XDB Server ignores the USING clause.

The USING clause is intended primarily for cursors declared with prepared select statements containing parameter markers. When the prepared select statement of the cursor is evaluated, each parameter marker is replaced by its corresponding host variable listed in the USING clause. The USING clause also functions in those cases when the DECLARE CURSOR statement contains the actual select statement, which typically includes host variables rather than parameter markings. In these cases, the OPEN statement is executed as if each host variable in the cursor select statement is a parameter marker. The values of the cursor select statement host variables are replaced by the values of the host variables specified in the USING clause.

If an SQLDA is specified (preceded by the keyword DESCRIPTOR), the user must have already set the value of certain SQLDA fields. The SQLN field must contain a value indicating the number of values in the SQLVAR array variable. Additionally, the SQLDABC field must indicate the bytes of storage allocated for the SQLDA, while the SQLD field value must denote the total number of variables used in the SQLDA when processing the OPEN statement. Lastly, each entry in the SQLVAR array must describe the attributes of an individual variable. If LOBs or distinct types are present in the results, there must be additional SQLVAR entries for each input host variable.

The value stored in SQLDABC must be calculated according to the formula SQLN*44+16, in order for the SQLDA to contain enough storage for all SQLVAR array values. Additionally, the SQLD field must be set to a value greater than or equal to zero, and less than or equal to the value of the SQLN field. This field value must equal the number of parameter markers in the prepared statement.

Note:

FETCH statements retrieve rows from the result table of a cursor when the cursor is open. The only way to open a closed cursor is by executing an OPEN statement. All cursors in an application process are in a closed state when the application process is started or when a new unit of work for the application process is commenced (unless WITH HOLD is specified in the DECLARE CURSOR statement). Additionally, performing a CONNECT closes any open cursors in an application.

Example:

The parameter host-variables is a list of host variables defined in the Working-Storage Section.

Assume that CUSTBL is a cursor opened on a command that was previously prepared. This prepared command will have one substitution parameter. Note that HOSTVAR1 must be defined in the Working-Storage Section of your COBOL program.

EXEC SQL
    OPEN custbl
END-EXEC
EXEC SQL
    OPEN custbl USING :hostvar1
END-EXEC
Parent topic: SQL Statements
Related reference
DECLARE CURSOR
DESCRIBE
PREPARE


PREPARE

The PREPARE statement (embedded SQL only) transforms a character string form of an SQL statement into an executable form of the same statement. The resulting executable statement is known as a prepared statement, while the original character string is known as the statement string.
Restriction: This topic applies to Windows environments only.

Invocation

PREPARE is an executable command that can only be embedded in a host language. PREPARE cannot be dynamically prepared.

Authorization

Users must have authorization to execute the command in the PREPARE statement.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

PREPARE statement-name
    [INTO descriptor-name [USING {NAMES | LABELS | ANY | BOTH}]]
    {[ATTRIBUTES attr-host-variable] FROM host-variable |
     FROM string-expression}

attr-host-variable

{{ASENSITIVE | INSENSITIVE | SENSITIVE [DYNAMIC | STATIC]} |
{SCROLL | NOSCROLL} |
holdability |
returnability |
rowset-positioning |
fetch-first-clause |
{read-only-clause | update-clause} |
optimize-clause |
isolation-clause |
{FOR MULTIPLE ROWS | FOR SINGLE ROW} |
{ATOMIC | NOT ATOMIC CONTINUE ON SQLEXCEPTION} [...] }

holdability

[WITH HOLD | WITHOUT HOLD]

returnability

[WITH RETURN [TO CALLER] | WITHOUT RETURN]

rowset-positioning

[WITH ROWSET POSITIONING | WITHOUT ROWSET POSITIONING]

Parameters:

statement-name | Names the prepared statement. If a prepared statement by that name already exists, then that prepared statement is destroyed and replaced by the newer version specified in this PREPARE statement.
descriptor-name | Preceded by the keyword INTO, identifies an SQLDA containing a valid description of host variables. See Overview for information about SQLDA.
host-variable | Preceded by the keyword FROM, must identify a variable (containing an SQL statement) described in the application program in accordance with the rules for declaring character string variables in the host language.

Description

The PREPARE statement is used by application programs to dynamically prepare an SQL statement for later use by an EXECUTE statement. Any SQL statement other than CLOSE, COMMIT, DECLARE CURSOR, DESCRIBE, EXECUTE, EXECUTE IMMEDIATE, FETCH, INCLUDE, OPEN, PREPARE, ROLLBACK, and WHENEVER may be prepared.

The prepared statement may not begin with an EXEC SQL or end with a statement terminator. Neither may the prepared statement contain references to host variables nor include comments. Although a statement may not contain host variables, it may include parameter markers. A parameter marker is a question mark character that will be replaced by a host variable at execution time.

INTO

The optional INTO clause places information about the prepared statement into the SQLDA specified in descriptor-name. This optional clause has the same effect as executing an extra DESCRIBE statement for the SQLDA (see DESCRIBE statement).

USING

Indicates what value to assign to each SQLNAME variable in the SQLDA when INTO is used. If the requested value does not exist, SQLNAME is set to length 0.

NAMES | Assigns the name of the column. This is the default.
LABELS | Assigns the label of the column. (Column labels are defined by the LABEL ON statement.)
ANY | Assigns the column label, and, if the column has no label, the column name.
BOTH | Assigns both the label and name of the column. In this case, two or three occurrences of SQLVAR per column, depending on whether the result set contains distinct types, are needed to accommodate the additional information. To specify this expansion of the SQLVAR array, set SQLN to 2¦n or 3¦n, where n is the number of columns in the object being described. For each of the columns, the first n occurrences of SQLVAR, which are the base SQLVAR entries, contain the column names. Either the second or third n occurrences of SQLVAR, which are the extended SQLVAR entries, contain the column labels. If there are no distinct types, the labels are returned in the second set of SQLVAR entries. Otherwise, the labels are returned in the third set of SQLVAR entries.

Parameter markers

The two types of parameter markers are typed and untyped:

Typed parameter marker

A parameter marker that is specified with its target data type. A typed parameter marker has the general form:

CAST(? AS data-type)

This notation is not a function call, but rather is a "promise" that the data type of the host variable at run time will be the same as, or can be converted to, the data type that was specified.

In the following example, the value of the argument that is provided for the TRANSLATE function at run time must be VARCHAR(12) or a data type that can be converted to VARCHAR(12).

UPDATE EMPLOYEE
    SET LASTNAME = TRANSLATE(CAST(? AS VARCHAR(12)))
    WHERE EMPNO = ?

Untyped parameter marker

A parameter marker that is specified without its target data type. An untyped parameter marker has the form of a single question mark. The context in which the parameter marker appears determines its data type. For example, in the above UPDATE statement, the data type of the untyped parameter marker in the predicate is the same as the data type of the EMPNO column.

Typed parameter markers can be used in dynamic SQL statements wherever a host variable is supported and the data type is based on the promise made in the CAST function.

Example:

In COBOL the host-variable must be a varying-length string variable defined in working storage of the code.

EXEC SQL
    PREPARE getcust
        FROM 'SELECT cno, name FROM cust'
END-EXEC

Another example of PREPARE also involving EXECUTE:

EXEC SQL
    PREPARE inscust FROM INSERT
        INTO cust(cno, name)
        VALUES (?, ?)
END-EXEC
.
. assign values to CNO and CNAME
.
EXEC SQL
    EXECUTE inscust
        USING :CNO, :CNAME
END-EXEC

Alternatively, it is possible to move an SQL string into a host variable and prepare that:

MOVE 'INSERT INTO cust (cno, name) VALUES (?, ?)'
    TO HOLD
EXEC SQL
    PREPARE inscust FROM :HOLD END-EXEC
.
. assign values to CNO and CNAME
.
EXEC SQL
    EXECUTE inscust
        USING :CNO, :CNAME
END-EXEC
Parent topic: SQL Statements
Related reference
DESCRIBE
Related information
Syntax Support Only


REFRESH LOCATIONS

REFRESH LOCATIONS is an XDB Server utility command (not supported in DB2 mode) that re-reads the SYSIBM.SYSLOCATIONS catalog table and updates the system with any new location changes. The REFRESH LOCATIONS command is necessary only if a location has been manually inserted into SYSIBM.SYSLOCATIONS. If a new location is created using the CREATE LOCATION command, the system is automatically reset (and the catalog tables updated) to include the new location information.
Restriction: This topic applies to Windows environments only.

Invocation

REFRESH LOCATIONS is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

REFRESH LOCATIONS requires no special privilege or authority. However, only a super user can edit the SYSIBM.SYSLOCATIONS catalog table.

Syntax

REFRESH LOCATIONS

Description

In order for the XDB Server to take advantage of Remote Unit of Work (RUW) or Distributed Unit of Work (DUW) processing, location information must be recorded in the SYSIBM.SYSLOCATIONS catalog table. This location information is read into memory the first time any application or user logs into the XDB Server.

If new location information is manually inserted into SYSIBM.SYSLOCATIONS (after the initial logging on), a REFRESH LOCATIONS command must be issued to reset the system to recognize this newly recorded location. The CREATE LOCATION command, however, automatically resets the system with the new location information.

Parent topic: SQL Statements


REFRESH TABLE

The REFRESH TABLE statement refreshes the data in a materialized query table. The statement deletes all rows in the materialized query table, executes the fullselect in the table definition to recalculate the data from the tables specified in the fullselect, inserts the calculated result into the materialized query table, and updates the catalog for the refresh timestamp and cardinality of the table. The table can exist at the current server or at any DB2 subsystem with which the current server can establish a connection.
Restriction: This topic applies to Windows environments only.

This command is only implemented syntactically in the XDB Server operating environment.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared only if DYNAMICRULES run behavior is implicitly or explicitly specified.

Authorization

The privilege set for REFRESH TABLE must include at least one of the following authorities:

  • Ownership of the materialized query table
  • DBADM or DBCTRL authority on the database that contains the materialized query table
  • SYSADM or SYSCTRL authority

If the statement is embedded in an application program, the privilege set is the privileges that are held by the authorization ID of the owner of the plan or package. If the statements dynamically prepared, the privilege set is determined by the DYNAMICRULES behavior in effect (run, bind, define, or invoke).

Syntax

Bold text indicates clauses or options that are supported only syntactically.

REFRESH TABLE table-name [QUERYNO integer]

Description

table-name

Identifies the table to be refreshed. The name must identify a materialized query table. REFRESH TABLE evaluates the fullselect in the materialized-query-definition clause to refresh the table. The isolation level for the fullselect is the isolation level of the materialized query table recorded when CREATE TABLE or ALTER TABLE was issued.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO column of the plan table for the rows that contain information about this SQL statement. This number is also used in the QUERYNO column of the SYSIBM.SYSSTMT and SYSIBM.SYSPACKSTMT catalog tables.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Note:
  • Automatic query rewrite using materialized query tables is not attempted for the fullselect in the materialized query table definition during the processing of REFRESH TABLE statement.
  • After successful execution of a REFRESH TABLE statement, the SQLCA field SQLERRD(3) will contain the number of rows inserted into the materialized query table.
  • The EXPLAIN output for REFRESH TABLE table-name is the same as the EXPLAIN output for INSERT INTO table-name fullselect where fullselect is from the materialized query table definition.
  • The REFRESH TABLE statement is supported over DRDA protocol, but not supported over DB2 private protocol.
  • If the materialized query table has a security label column, the REFRESH TABLE statement does not do any checking for multilevel security with row-level granularity when it deletes and repopulates the data in the table by executing the fullselect. Instead, DB2 performs the checking for multilevel security with row-level granularity when the materialized query table is exploited in automatic query rewrite or is used directly.
Parent topic: SQL Statements


RELEASE (connection)

The RELEASE statement places one or more connections in the release pending state.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be embedded in an application program, except in REXX programs. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

RELEASE {location-name | host-variable | CURRENT | ALL [SQL] | ALL PRIVATE}

Description

location-name or host-variable

Identifies an SQL connection or a DB2 private connection by the specified location name or the location name contained in the host variable. If a host variable is specified:

  • It must be a character string variable with a length attribute that is not greater than 16. (A C NUL-terminated character string can be up to 17 bytes.)
  • It must not be followed by an indicator variable.
  • The location name must be left-justified within the host variable and must conform to the rules for forming an ordinary location identifier.
  • If the length of the location name is less than the length of the host variable, it must be padded on the right with blanks.

The specified location name or the location name contained in the host variable must identify an existing SQL connection or DB2 private connection of the application process.

If the RELEASE statement is successful, the identified connection is placed in the release pending status and will therefore be ended during the next commit operation. If the RELEASE statement is unsuccessful, the connection state of the application process and the states of its connections are unchanged.

CURRENT

Identifies the current SQL connection of the application process. The application process must be in the connected state.

If the RELEASE statement is successful, the identified connection is placed in the release pending state and will therefore be ended during the next commit operation. If the RELEASE statement is unsuccessful, the connection state of the application process and the states of its connections are unchanged.

ALL or ALL SQL

Identifies all existing connections (including local, SQL, and DB2 private connections) of the application process and places these connections in the release pending status. These connections are ended during the next commit operation. An error or warning does not occur if no connections exist when the statement is executed.

ALL PRIVATE

Identifies all existing DB2 private connections of the application process and places these connections in the release pending status. These DB2 private connections are ended during the next commit operation. An error or warning does not occur if no DB2 private connections exist when the statement is executed.

Example:

The SQL connection to TOROLAB1 is not needed in the next unit of work. The following statement causes it to be ended during the next commit operation:

EXEC SQL RELEASE TOROLAB1
Parent topic: SQL Statements


RELEASE SAVEPOINT

The RELEASE SAVEPOINT statement releases the identified savepoint and any subsequently established savepoints within a unit of recovery.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be imbedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

RELEASE [TO] SAVEPOINT svpt-name

svpt-name

A savepoint identifier that identifies the savepoint to release. If the named savepoint does not exist, an error occurs. The named savepoint and all the savepoints that were subsequently established in the unit of recovery are released. After a savepoint is released, it is no longer maintained and rollback to the savepoint is no longer possible.

Example:

Assume that a main routine sets savepoint A and then invokes a subroutine that sets savepoints B and C. When control returns to the main routine, release savepoint A and any subsequently set savepoints. Savepoints B and C, which were set by the subroutine, are released in addition to A.

RELEASE SAVEPOINT A;
Parent topic: SQL Statements


RENAME

The RENAME statement renames an existing table.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared. However, if the bind option DYNAMICRULES(BIND) applies, the statement cannot be dynamically prepared.

Authorization

The privileges set defined below must include at least one of the following:

  • Ownership of the table
  • DBADM, DBCTRL, or DBMAINT authority for the database that contains the table
  • SYSADM or SYSCTRL authority

Privilege Set: If the statement is embedded in an application program, the privilege set is the privileges held by the authorization ID of the owner of the plan or package. If the statement is dynamically prepared, the privilege set is the union of the privilege sets held by each authorization ID of the process.

If the name of the existing table includes a qualifier that is different from the authorization ID of the statement, the privileges held by the authorization ID of the statement must include administrative authority.

Syntax

RENAME [TABLE] source-table-name TO target-table-name

Parameters:

source-table-name | Identifies the table to be renamed.
target-table-name | Is the new table name.

Description

The source table name, including the implicit or explicit qualifier, must identify a table that already exists at the current server. The name must not identify a table that has a trigger defined on it, a declared temporary table, a catalog table, an active RLST table, a view, or a synonym. The new table name must be a legal table name that does not already exist in the location. The specified source table is renamed to the new name. All privileges and indexes on the table are preserved.

Parent topic: SQL Statements


REVOKE (Database Privileges)

The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
Restriction: This topic applies to Windows environments only.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. The XDB Server cannot functionally utilize these types of privileges, although future catalog support is planned. DB2 users should consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

REVOKE is an executable statement that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

In most instances, the authority needed to revoke a specific privilege must be identical to the authority that originally issued the privilege -- which means that privileges individually granted by a specific AuthID are generally revoked individually by the same AuthID.

Syntax

This format is used to revoke privileges on specified databases. One or more of the privilege option keywords defined below (separated with commas) may be specified after REVOKE, allowing multiple privileges to be revoked in one statement. In every case, the privileges chosen are revoked only from the logical database(s) named in the REVOKE command.

REVOKE
        [DBADM[, ]]
        [DBCTRL[, ]]
        [DBMAINT[, ]]
        [CREATETAB[, ]]
        [CREATETS[, ]]
        [DROP[, ]]
        [STARTDB[, ]]
        [STATS[, ]]
        [STOPDB[, ]]
    ON DATABASE database-name[,...]
    FROM AuthID[,...][PUBLIC]
    [BY AuthID[,...][ALL]]

This format is used to revoke privileges on specified databases. One or more of the privilege option keywords defined below (separated with commas) may be specified after REVOKE, allowing multiple privileges to be revoked in one statement. In every case, the privileges chosen are revoked only from the logical database(s) named in the REVOKE command.

REVOKE
        [DBADM[, ]]
        [DBCTRL[, ]]
        [DBMAINT[, ]]
        [CREATETAB[, ]]
        [CREATETS[, ]]
        [DROP[, ]]
        [STARTDB[, ]]
        [STATS[, ]]
        [STOPDB[, ]]
    ON DATABASE database-name[,...]
    FROM AuthID[,...][PUBLIC]
    [BY AuthID[,...][ALL]]

Parameters:

DBADM | Database administrator authority.
DBCTRL | Database control authority.
DBMAINT | Database maintenance authority.
CREATETAB | Privilege to create new tables.
CREATETS | Privilege to create new table spaces.
DROP | Privilege to issue the DROP or ALTER DATABASE statements for the designated databases.
STARTDB | Privilege to issue the START DATABASE command.
STOPDB | Privilege to issue the STOP DATABASE command.
Note:

The DISPLAYDB, IMAGCOPY, LOAD, RECOVERDB, REORG, REPAIR, and STATS database grant/revoke privileges are specific to the DB2 mainframe environment, and control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, the XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.

database-name | Identifies a database on which privileges are to be revoked. Each database named must exist at the current location. The XDB Server does not support cascading revoke.
AuthID | Identifies a user authorization ID from which the specified privilege(s) are being revoked. The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), revoking the specified privileges from all valid AuthIDs at the current location.

Description

The REVOKE command is used to remove system, database, table, and view privileges from designated AuthID(s). There are three formats for the REVOKE command, depending on the type of privilege being revoked. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

For a TEMP database, you cannot revoke the privilege from PUBLIC. When a TEMP database is created, PUBLIC implicitly receives the CREATETAB privilege (without GRANT authority); this privilege is not recorded in the DB2 catalog, and it cannot be revoked.

Individual grants (or groups of grants) are removed from the catalog tables by executing REVOKE command statements. Each individual revoke (as registered in the catalog tables) involves the removal of one privilege by one revoker from one revokee. The removal of privileges with the REVOKE statement is recorded in the system catalog for the current location. The status of each individual granted or revoked privilege (for each AuthID) is recorded in the catalog tables.

Note:

Since the same privilege can be granted to a single grantee AuthID by several different grantor AuthIDs, the grantee AuthID retains the privilege as long as one (or more) of these grants remains recorded in the system catalog.

Privileges may be revoked from a specific set of users by listing their AuthIDs in the FROM clause of the REVOKE statement. To revoke privileges from all AuthIDs in the current location, use the keyword PUBLIC in the FROM clause. When a privilege is revoked from PUBLIC, the system catalog continues to maintain the list of AuthIDs that were individually granted the privilege.

Example:

The following example revokes DBADM authority for a database named PICTURES from the individual(s) with AuthID usera.

REVOKE DBADM
    ON DATABASE pictures
    FROM usera
Parent topic: SQL Statements
Related reference
REVOKE (Table or View Privileges)
REVOKE (System Privileges)
REVOKE (Function or Procedure Privileges)


REVOKE (Function or Procedure Privileges)

This form of the REVOKE statement revokes privileges on user-defined functions, cast functions that were generated for distinct types, and stored procedures.
Restriction: This topic applies to Windows environments only.

Syntax

REVOKE EXECUTE ON
       {FUNCTION {function-name [(parameter-type[,...])] | * } |
        SPECIFIC FUNCTION specific-name[,...] |
        PROCEDURE {procedure-name[,...] | *}
    FROM {authorization-name[,...] | PUBLIC} [BY {authorization-name[,...] | ALL}]
    RESTRICT

Description

EXECUTE

Revokes the privilege to run the identified user-defined function, cast function that was generated for a distinct type, or stored procedure.

FUNCTION or SPECIFIC FUNCTION

Identifies the function on which the privilege is granted. The function must exist at the current server, and it must be a function that was defined with the CREATE FUNCTION statement or a cast function that was generated by a CREATE DISTINCT TYPE statement.

If the function was defined with a table parameter (the LIKE TABLE was specified in the CREATE FUNCTION statement to indicate that one of the input parameters is a transition table), the function signature cannot be used to identify the function. Instead, identify the function with its function name, if unique, or with its specific name.

FUNCTION function-name

Identifies the function by its name. You can identify a function by its name only if there is exactly one function with function name in the schema. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified on unqualified function-name. An * (or schema-name.*) indicates that the privilege is revoked for all the functions in the schema. You (or the indicated grantors) must have granted the privilege on FUNCTION * to all identified users (including PUBLIC if specified). Privileges granted on specific functions are not affected.

FUNCTION function-name (parameter-type,...)

Identifies the function by its function signature, which uniquely identifies the function.

function-name Specifies the name of the function. If you do not explicitly qualify the function name with a schema name, the function name is implicitly qualified with a schema name as described in the preceding description for FUNCTION function-name.
(parameter-type,...) Identifies the number of input parameters of the function and their data types.

The data type of each parameter must match the data type that was specified in the CREATE FUNCTION statement for the parameter in the corresponding position. The number of data types and the logical concatenation of the data types is used to uniquely identify the function.

For data types that have a length, precision, or scale attribute, you can specify a value or use a set of empty parentheses:

  • Empty parentheses indicate that DB2 ignores the attribute when determining whether the data types match.

    FLOAT cannot be specified with empty parentheses because its parameter value indicates different data types (REAL or DOUBLE).

  • If you use a specific value for a length, precision, or scale attribute, the value must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    The specific value for FLOAT(n) does not have exactly match the defined value of the source function because 1<=n<= 21 indicates REAL and 22<=n<=53 indicates DOUBLE. Matching is based on whether the data type is REAL or DOUBLE.

  • If length, precision, or scale is not explicitly specified, and empty parentheses are not specified, the default length of the data type is implied. For example:

    The implicit length must exactly match the value that was specified (implicitly or explicitly) in the CREATE FUNCTION statement.

    For data types with a subtype or encoding scheme attribute, specifying the FOR DATA clause or CCSID clause is optional. Omission of either clause indicates that DB2 ignores the attribute when determining whether the data types match. If you specify either clause, it must match the value that was implicitly or explicitly specified in the CREATE FUNCTION statement.

SPECIFIC FUNCTION specific-name

Identifies the function by its specific name.

PROCEDURE procedure-name

Identifies a stored procedure that is defined at the current server. If you do not explicitly qualify the procedure name with a schema name, the procedure name is implicitly qualified with a schema name according to the following rules:

  • If the statement is embedded in a program, the schema name is the authorization ID in the QUALIFIER option when the plan or package was created or last rebound. If QUALIFIER was not used, the schema name is the owner of the plan or package.
  • If the statement is dynamically prepared, the schema name is the SQL authorization ID in the CURRENT SQLID special register.

An * can be specified for a qualified or unqualified procedure-name. An * (or schema-name.*) indicates that the privilege is revoked for all the procedures in the schema. You (or the indicated grantors) must have granted the privilege on PROCEDURE * to all identified users (including PUBLIC if specified). Privileges granted on specific procedures are not affected.

RESTRICT

Prevents the EXECUTE privilege from being revoked on a user-defined function or stored procedure if the revokee owns any of the following objects:

  • A function that is sourced on the function
  • A view that uses the function
  • A trigger package that uses the function or stored procedure
  • A table that uses the function in a check constraint or user-defined default clause

Example:

Revoke the EXECUTE privilege on function CALC_SALARY for user JONES. Assume that there is only one function in the schema with function CALC_SALARY.

REVOKE EXECUTE ON FUNCTION CALC_SALARY FROM JONES RESTRICT;

Revoke the EXECUTE privilege on procedure VACATION_ACCR from all users at the current server.

REVOKE EXECUTE ON PROCEDURE VACATION_ACCR FROM PUBLIC RESTRICT;

Revoke the privilege of the administrative assistant to grant EXECUTE privileges on function DEPT_TOTAL to other users. The administrative assistant will still have the EXECUTE privilege on function DEPT_TOTALS.

REVOKE EXECUTE ON FUNCTION DEPT_TOTALS
    FROM ADMIN_A RESTRICT;

Revoke the EXECUTE privilege on function NEW_DEPT_HIRES for HR (Human Resources). The function has two input parameters with data types of INTEGER and CHAR(10), respectively. Assume that the schema has more than one function that is named NEW_DEPT_HIRES.

REVOKE EXECUTE ON FUNCTION NEW_DEPT_HIRES (INTEGER, CHAR(10))
    FROM HR RESTRICT;

You can also code the CHAR(10) data type as CHAR().

Parent topic: SQL Statements
Related information
REVOKE (Table or View Privileges)
REVOKE (System Privileges)
REVOKE (Database Privileges)


REVOKE (Sequence Privileges)

This form of the REVOKE statement revokes the privileges on a user-defined sequence.
Restriction: This topic applies to Windows environments only.

Syntax

REVOKE {ALTER | USAGE} [,...] ON SEQUENCE sequence-name [,...]
FROM {authorization-name | PUBLIC} [,...]
[BY {authorization-name | ALL} [,...]]
[RESTRICT]
Note: The keyword SELECT is an alternative keyword for USAGE.

Description

ALTER

Revokes the privilege to alter a sequence or record a comment on a sequence.

USAGE

Revokes the USAGE privilege to use a sequence. This privilege is needed when the NEXT VALUE or PREVIOUS VALUE expression is invoked for a sequence name.

SEQUENCE sequence-name

Identifies the sequence. The name, including the implicit or explicit schema qualifier, must uniquely identify an existing sequence at the current server. If no sequence by this name exists in the explicitly or implicitly specified schema, an error occurs. sequence-name must not be the name of an internal sequence object that is generated by the system for an identity column.

FROM

Specifies from what authorization IDs the privileges are revoked.

authorization-name,...

Lists one or more authorization IDs. Do not use the same authorization ID more than once. The value of CURRENT RULES determines if you can use the ID of the REVOKE statement itself (to revoke privileges from yourself). When CURRENT RULES is:

DB2 | You cannot use the ID of the REVOKE statement.
STD | You can use the ID of the REVOKE statement.

PUBLIC

Revokes a grant of privileges to PUBLIC.

PUBLIC AT ALL LOCATIONS

Revokes a grant of privileges to PUBLIC AT ALL LOCATIONS.

BY

Lists grantors who have granted privileges and revokes each named privilege that was explicitly granted to some named user by one of the named grantors. Only an authorization ID with SYSADM or SYSCTRL authority can use BY, even if the authorization ID names only itself in the BY clause.

authorization-name,...

Lists one or more authorization IDs of users who were the grantors of the privileges named. Do not use the same authorization ID more than once. Each grantor listed must have explicitly granted some named privilege to all named users.

ALL

Revokes each named privilege from all named users who were explicitly granted the privilege, regardless of who granted it.

RESTRICT

Prevents the USAGE privilege from being revoked on a sequence if the revokee owns one of the following objects and does not have the USAGE privilege from another source:

  • A trigger that specifies the sequence in a NEXT VALUE or PREVIOUS VALUE expression
  • An inline SQL function that specifies the sequence in a NEXT VALUE or PREVIOUS VALUE expression
Parent topic: SQL Statements


REVOKE (System Privileges)

The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
Restriction: This topic applies to Windows environments only.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. The XDB Server cannot functionally utilize these types of privileges, although future catalog support is planned. DB2 users should consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

REVOKE is an executable statement that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

In most instances, the authority needed to revoke a specific privilege must be identical to the authority that originally issued the privilege -- which means that privileges individually granted by a specific AuthID are generally revoked individually by the same AuthID.

Syntax

This format is used to revoke system privileges. In every case, the system privileges chosen are revoked only for those AuthID(s) specified in the FROM clause. One or more of the privilege option keywords defined below (separated with commas) may be specified after REVOKE, allowing multiple system privileges to be revoked in one REVOKE statement.

Bold text indicates clauses or options that are supported only syntactically.

REVOKE
        [CREATEALIAS[, ]]
        [CREATEDBA[, ]]
        [CREATEDBC[, ]]
        [CREATETMTAB[, ]]
        [CREATESG[, ]]
        [SYSADM[, ]]
        [SYSCTRL[, ]]
    FROM AuthID[,...][PUBLIC]
    BY {AuthID[,...] | ALL}

Parameters:

CREATEALIAS | Privilege to use the CREATE ALIAS statement.
CREATEDBA | Privilege to issue the CREATE DATABASE statement and acquire DBADM authority over those databases.
CREATEDBC | Privilege to issue the CREATE DATABASE statement and acquire DBCTRL authority over those databases.
CREATETMTAB | Privilege to issue the CREATE GLOBAL TEMPORARY TABLE statement.
CREATESG | Privilege to create new storage groups.
SYSADM | Revokes system administrator authority for the location.
SYSCTRL | Revokes the system control authority for the location.
Note:

The ARCHIVE, BINDADD, BINDAGENT, BSDS, DISPLAY, MONITOR1, MONITOR2, RECOVER, STOPALL, STOSPACE, SYSOPR, and TRACE system privileges control specific authorities for running mainframe utilities (for example, CHECK, RUNSTATS and QUIESCE). The XDB Server does not functionally support these privileges. However, to maintain maximum compatibility with mainframe DB2 operations, The XDB Server syntactically checks these privileges (if encountered) and updates the appropriate catalog tables.

AuthID Identifies a user authorization ID for which the specified privilege(s) are being revoked. The PUBLIC keyword option can be specified along with (or in place of) an AuthID (or a list of AuthIDs), revoking privileges from each valid AuthID at the current location.

Description

The REVOKE command is used to remove system, database, table, and view privileges from designated AuthID(s). There are three formats for the REVOKE command, depending on the type of privilege being revoked. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

Individual grants (or groups of grants) are removed from the catalog tables by executing REVOKE command statements. Each individual revoke (as registered in the catalog tables) involves the removal of one privilege by one revoker from one revokee. The removal of privileges with the REVOKE statement is recorded in the system catalog for the current location. The status of each individual granted or revoked privilege (for each AuthID) is recorded in the catalog tables.

Note:

Since the same privilege can be granted to a single grantee AuthID by several different grantor AuthIDs, the grantee AuthID retains the privilege as long as one (or more) of these grants remains recorded in the system catalog.

FROM

Privileges may be revoked from a specific set of users by listing their AuthIDs in the FROM clause of the REVOKE statement. To revoke privileges from all AuthIDs in the current location, use the keyword PUBLIC in the FROM clause. When a privilege is revoked from PUBLIC, the system catalog continues to maintain the list of AuthIDs that were individually granted the privilege.

DISPLAY

Revokes the privilege to use the following commands:

  • The DISPLAY ARCHIVE command for archive log information
  • The DISPLAY BUFFERPOOL command for the status of buffer pools
  • The DISPLAY DATABASE command for the status of all databases
  • The DISPLAY FUNCTION SPECIFIC command for statistics about accessed external user-defined functions
  • The DISPLAY LOCATION command for statistics about threads with a distributed relationship
  • The DISPLAY PROCEDURE command for statistics about accessed stored procedures
  • The DISPLAY THREAD command for information on active threads with in DB2
  • The DISPLAY TRACE command for a list of active traces
Parent topic: SQL Statements
Related reference
REVOKE (Database Privileges)
REVOKE (Table or View Privileges)
REVOKE (Function or Procedure Privileges)
Related information
Syntax Support Only


REVOKE (Table or View Privileges)

The REVOKE command cancels database, table or view, or system privileges held by specified AuthIDs. The XDB Server supports three separate REVOKE formats, one each for revoking database, table or view, and system privileges. All relevant objects must be located in the current location. Revoked privileges are recorded in the system catalog for the current location.
Restriction: This topic applies to Windows environments only.

The XDB Server syntactically supports the collection, package, and plan classes of GRANT/REVOKE privilege commands. Also syntactically supported are the use class of GRANT/REVOKE privileges, including the USE OF ALL BUFFERPOOLS clause. The XDB Server cannot functionally utilize these types of privileges, although future catalog support is planned. DB2 users should consult their DB2 documentation for information on these four classes of privilege commands.

Invocation

REVOKE is an executable statement that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

In most instances, the authority needed to revoke a specific privilege must be identical to the authority that originally issued the privilege -- which means that privileges individually granted by a specific AuthID are generally revoked individually by the same AuthID.

Syntax

This format is used to revoke privileges on tables or views. In every case, the privileges chosen are revoked only from the tables or views named in the ON [TABLE] clause. One or more of the privilege keywords (separated with commas) defined below and/or the optional keyword(s) ALL [PRIVILEGES] may be specified after REVOKE, allowing multiple privileges to be revoked in one REVOKE statement.

Bold text indicates clauses or options that are supported only syntactically.

REVOKE
{       [ALTER[, ]]
        [DELETE[, ]]
        [INDEX[, ]]
        [INSERT[, ]]
        [SELECT[, ]]
        [TRIGGER[, ]]
        [UPDATE] | ALL [PRIVILEGES]
}
    ON [TABLE] {table-name[,...] | view-name[,...]}
    FROM AuthID[,...][PUBLIC [AT ALL LOCATIONS]]
    [BY {AuthID[,...] | ALL}]

Parameters:

ALTER | Privilege to use the ALTER TABLE statement (cannot specify a view).
DELETE | Privilege to use the DELETE statement.
INDEX | Privilege to use the CREATE INDEX statement (cannot specify a view).
INSERT | Privilege to use the INSERT statement.
SELECT | Revokes the privilege to create a view or read data from the specified table or view. A view or a materialized query table is dropped when the SELECT privilege that was used to create it is revoked, unless the owner of the view or materialized query table was directly granted the SELECT privilege from another source before the view or materialized query table was created.
TRIGGER | Revokes the privilege to use the CREATE TRIGGER statement
UPDATE | Privilege to use the UPDATE statement on all columns of the tables named in the ON [TABLE] clause. When followed by (column-name[,...]), the update privileges are revoked only from the columns specified in parentheses. Note that (unlike the corresponding GRANT command) the UPDATE privilege can only be revoked from a list of individual column names in XDB mode.
column-name | Specifies an individual column in a table from which the UPDATE privilege is being revoked.
table-name or view-name | Preceded by the keyword(s) ON [TABLE], identifies a table or view from which privileges are being revoked.
AuthID | Identifies a user authorization ID from which the privilege(s) specified are being revoked. The optional PUBLIC [AT ALL LOCATIONS] keyword(s) can be specified along with (or in place of) an AuthID (or a list of AuthIDs). The PUBLIC AT ALL LOCATIONS keyword option revokes the specified table privileges from all users at every location.

ALL [PRIVILEGES]

If the ALL or ALL PRIVILEGES keywords are specified, all table or view privileges (for which the issuer has REVOKE authority) are revoked for the objects identified in the ON [TABLE] clause.

Description

The REVOKE command is used to remove system, database, table, and view privileges from designated AuthID(s). There are three formats for the REVOKE command, depending on the type of privilege being revoked. Database privileges include CREATETAB, DBADM and DROP privileges. Table privileges include ALTER, DELETE, INDEX, INSERT, SELECT, and UPDATE privileges. System privileges that imply other privileges are also characterized as authorities.

Individual grants (or groups of grants) are removed from the catalog tables by executing REVOKE command statements. Each individual revoke (as registered in the catalog tables) involves the removal of one privilege by one revoker from one revokee. The removal of privileges with the REVOKE statement is recorded in the system catalog for the current location. The status of each individual granted or revoked privilege (for each AuthID) is recorded in the catalog tables.

For a declared temporary table, no privileges can be revoked because none can be granted. When a declared temporary table is defined, PUBLIC implicitly receives all table privileges (without GRANT authority) for the table. These privileges are not recorded in the DB2 catalog.

Note: Since the same privilege can be granted to a single grantee AuthID by several different grantor AuthIDs, the grantee AuthID retains the privilege as long as one (or more) of these grants remains recorded in the system catalog.

FROM

Privileges may be revoked from a specific set of users by listing their AuthIDs in the FROM clause of the REVOKE statement. To revoke privileges from all AuthIDs in the current location, use the keyword PUBLIC in the FROM clause. When a privilege is revoked from PUBLIC, the system catalog continues to maintain the list of AuthIDs that were individually granted the privilege.

Examples:

The following example revokes authority for the individuals with the AuthIDs userb and userc to update the PART and SUPPLIER tables.

REVOKE UPDATE
    ON part, supplier
    FROM userb, userc

To revoke privileges from PUBLIC to select, update, delete and insert records in the PART table, use the command:

REVOKE SELECT, UPDATE, DELETE, INSERT
    ON part
    FROM PUBLIC

To revoke the select privilege on all tables from AuthID usera, you might use a command like:

REVOKE SELECT
    ON ALL
    FROM usera

To revoke privileges (XDB mode only) on a subset of the columns in the EMPLOYEE table from AuthID usera, issue the command:

REVOKE UPDATE(address, city, state, zip, phone)
    ON employee
    FROM usera
Parent topic: SQL Statements


ROLLBACK

ROLLBACK is used to mark the end of a transaction and back out of all changes made by the transaction at the current location. The XDB Server does not rollback data definition language (DDL) commands such as CREATE, DROP, ALTER; data control language (DCL) commands such as GRANT, and REVOKE; or utility commands such as SET and COPY. When working in a production environment, it is recommended that you backup your location before and after such commands.
Restriction: This topic applies to Windows environments only.

Invocation

ROLLBACK is an executable command that can be issued interactively or embedded in a host language. ROLLBACK can be dynamically prepared.

Authorization

No special authorization is required for ROLLBACK.

Syntax

ROLLBACK [WORK] [TO SAVEPOINT [svpt-name]]

Description

A transaction begins when a previous transaction ends. A transaction is terminated by a COMMIT or ROLLBACK command. Only the results of SQL commands executed within a single, uncommitted transaction are affected by the ROLLBACK command. When the ROLLBACK command is issued, all changes caused by INSERT, UPDATE and DELETE commands of the transaction are undone. All locks acquired during a transaction are released by the ROLLBACK command. If AUTOCOMMIT is on, a user-invoked ROLLBACK has no effect. However, the system will rollback a failed command.

Backward Logging

If you are using XDB Server Version 5.0 or higher, the ROLLBACK command is available. Previous versions of XDB required a feature called Backward Logging to be turned on in order to use the ROLLBACK command. The functionality provided by the old Backward Logging feature has been incorporated into the XDB Server logging system as a permanent default.

TO SAVEPOINT

Specifies that the unit of recovery is not to be ended and that only a partial rollback (to a savepoint) is to be performed. If a savepoint name is not specified, rollback is to the last active savepoint. For example, if in a unit of recovery, savepoints A, B, and C are set in that order and then C is released, ROLLBACK TO SAVEPOINT causes a rollback to savepoint B.

svpt-name A savepoint-identifier that identifies the savepoint to which to roll back. If the named savepoint does not exist, an error occurs.

All database changes (including changes made to a declared temporary tables but excluding changes made to created temporary tables) that were made after the savepoint was set are backed out. Changes that are made to created temporary tables are not logged and are not backed out; a warning is issued instead. (A warning is also issued when a created temporary table is changed and there is an active savepoint.)

In addition, none of the following items are backed out:

  • The opening or closing of cursors
  • Changes in cursor positioning
  • The acquisition and release of locks
  • The caching of the rolled back statements

Any savepoints that are set after the one to which rollback is performed are released. The savepoint to which rollback is performed is not released.

ROLLBACK with or without the TO SAVEPOINT clause has no effect on connections.

Parent topic: SQL Statements


ROLLFORWARD

ROLLFORWARD allows users to roll forward the transactions stored in supplied log files to a specified location. This command must be run while in exclusive use mode.
Restriction: This topic applies to Windows environments only.

Invocation

ROLLFORWARD can be executed interactively, embedded in a host language, or dynamically prepared.

Authorization

To use the ROLLFORWARD command you must be a super user.

Syntax

ROLLFORWARD location-name USING log-file-path

Parameters

location-name | Identifies the location to be recovered.
log-file-path | Specifies the directory containing the log files that need to be applied to the appropriate location. These log files must have been created as the result of a standard or incremental BACKUP command.

Description

The ROLLFORWARD command is used to roll forward transactions contained in log files for a specified location. These log files must have been created by a standard or incremental BACKUP command.

The ROLLFORWARD command is used when a media or disk failure has occurred. After placing a backup of a location back on disk, ROLLFORWARD commands specifying the appropriate log files can bring the backup location up to date, so that its state is consistent with the location at the time of the crash.

After performing a standard backup (which is mandatory for all recovery scenarios), which type of backup you perform is up to you. Always performing standard backups takes longer than performing incremental backups but the recovery process from them is much easier and quicker. Performing incremental backups is quicker than performing standard backups but more ROLLFORWARD steps might be necessary to recreate your location.

Resetting Logging System

The XDB Server's logging system automatically creates a series of log files when a new location is created. For an existing location, logging should be manually reset as a part of the location backup process.

Follow the steps below to manually reset location logging:

  1. Shut down server.
  2. Copy log files from the location logging directory to a separate archive directory.
  3. Depending on whether you are using the BACKUP LOCATION command or an operating system backup command, do one of the following:
    • Bring the server back up and run the BACKUP LOCATION command from SQLWizard (be sure you execute the BACKUP LOCATION command from a location other than the one you are backing up).
    • Run your operating system (or other) backup utility as appropriate (be sure to archive all directories associated with the XDB Server location).
  4. Shut down the server (if using BACKUP LOCATION).
  5. Delete all log files (*.LOG) from your location logging directory. The next time the location is accessed, a fresh series of log files will automatically be created by the logging system.

COMPACT Commands

Since using a COMPACT command on a location renders that location's current log files useless, a location should be backed up (and the log files for that location reset) immediately after any COMPACT commands are issued against that location. Log files contain internal information that maps to a particular table structure. COMPACT commands alter the table structure of the location, changing this log-to-table mapping, and making ROLLFORWARD with the previous log files impossible.

Example

The following command rolls forward the transactions in MYLOC, using the log files specified in d:\backuplocs\xdb20051017151315000001:

ROLLFORWARD MYLOC USING D:\BACKUPLOCS\XDB20051017151315000001
Parent topic: SQL Statements


SAVEPOINT

The SAVEPOINT statement sets a savepoint within a unit of recovery to identify a point in time within the unit of recovery to which relational database changes can be rolled back.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be imbedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SAVEPOINT svpt-name [UNIQUE]
    ON ROLLBACK RETAIN CURSORS
    [ON ROLLBACK RETAIN LOCKS]

Description

svpt-name

A savepoint identifier that names the savepoint. (A savepoint identifier is like an SQL identifier except that it has maximum length of 128 bytes.)

UNIQUE

Specifies that the application program cannot reuse the savepoint name within the unit of recovery. An error occurs if a savepoint with the same name as svpt-name already exists within the unit of recovery.

Omitting UNIQUE indicates that the application can reuse the savepoint name within the unit of recovery. If svpt-name identifies a savepoint that already exists within the unit of recovery and the savepoint was not created with the UNIQUE option, the existing savepoint is destroyed and a new savepoint is created. Destroying a savepoint to reuse its name for another savepoint is not the same as releasing the savepoint.

Reusing a savepoint name destroys only one savepoint. Releasing a savepoint with the RELEASE SAVEPOINT statement releases the savepoint and all savepoints that have been subsequently set.

ON ROLLBACK RETAIN CURSORS

Specifies that any cursors that are opened after the savepoint is set are not tracked, and thus, are not closed upon rollback to the savepoint.

Although these cursors remain open after rollback to the savepoint, they might not be usable. For example, if rolling back to the savepoint causes the insertion of a row upon which the cursor is positioned to be rolled back, using the cursor to update or delete the row results in an error.

ON ROLLBACK RETAIN LOCKS

Specifies that any locks that are acquired after the savepoint is set are not tracked, and thus, are not released upon rollback to the savepoint.

Example:

Assume that you want to set three savepoints at various points in a unit of recovery. Name the first savepoint A and allow the savepoint name to be reused. Name the second savepoint B and do not allow the name to be reused. Because you no longer need savepoint A when you are ready to set the third savepoint, reuse A as the name of the savepoint.

SAVEPOINT A ON ROLLBACK RETAIN CURSORS;
 . . .
SAVEPOINT B UNIQUE ON ROLLBACK RETAIN CURSORS;
 . . .
SAVEPOINT A ON ROLLBACK RETAIN CURSORS;
Parent topic: SQL Statements


SELECT (SQL Statements)

SELECT

SELECT commands (or queries) all retrieve information from data tables and display this information in a results table. For purposes of classification, SELECT commands can be subdivided into three general categories including, subselects (and subqueries), fullselects and select statements.
Restriction: This topic applies to Windows environments only.

Invocation

SELECT is an executable command that can be issued interactively or embedded in a host language. SELECT can be dynamically prepared.

Authorization

In order to select data from a table or view, users must possess either SELECT authority on the table or view accessed, DBADM authority on the database, SYSADM or SYSCTRL authority for the location, or be the owner of the table or view.

Syntax

SELECT command statements can be composed of six different types of clauses. The SELECT clause and the FROM clause are required for all SELECT commands.

WHERE clauses are permitted in all SELECT commands. You can force the use of an index for a particular indexed column or force the system to not use an index in the query. To force the use of an index when constructing the query, enter an asterisk (*) in parentheses after the name of the indexed column in the WHERE clause.

To force the system to ignore the index, enter a hyphen (-) in parentheses after the name of the indexed column. The (*) and (-) options are valid only for column names that appear in a WHERE clause. You cannot use the (*) and (-) options in GROUP BY, HAVING or ORDER BY clauses (see SELECT Clause for examples).

Depending on the other clauses they contain, SELECT commands may be grouped into the following three classes:

Subselect

A subselect specifies a result table derived from the tables or views identified in the FROM clause of the query.

The subselect syntax appears below:

select-clause from-clause [where-clause] [group-by-clause] [having-clause]

Parameters

select-clause | Required component of a subselect. See SELECT Clause Syntax and Description for a complete syntax analysis of SELECT clauses.
from-clause | Required component of a subselect. See FROM Clause Syntax and Description for a complete syntax analysis of FROM clauses.
where-clause | Optional clause of a subselect. See WHERE Clause Syntax and Description for a complete syntax analysis of WHERE clauses.
group-by-clause | Optional clause of a subselect. See GROUP BY Clause for a complete syntax analysis of GROUP BY clauses.
having-clause | Optional clause of a subselect. See GROUP BY Clause for a complete syntax analysis of HAVING clauses.

Description

In addition to standing on its own, a subselect can be a component of the fullselect or incorporated into CREATE TABLE, UPDATE, INSERT, DELETE, and CREATE VIEW statements. Subselects can also be components of certain predicates, in which case they can be called subqueries. Subselects can contain GROUP BY or HAVING clauses, and the WHERE clause of a subselect can also contain nested subselects. Subselects cannot contain the UNION operator or an ORDER BY clause.

Subselects and Locations

The subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

SELECT * FROM tutorial.tutorial.employeeWHERE e_no IN SELECT e_no FROM debloc.debbie.employee WHERE st = "MD";

Valid:

SELECT * FROM tutorial.tutorial.employeeWHERE e_no IN SELECT e_no FROM tutorial.debbie.employee WHERE st = "MD";

Fullselect

A fullselect can consist of one or more subselects connected with one or more UNION operators. Fullselects can also be issued from SQLWizard -- causing a result table to be displayed. See SELECT Clause for examples of fullselect queries.

Syntax:

The fullselect syntax appears below:

subselect [(fullselect)] [UNION | UNION ALL] [subselect [(fullselect)]]

Description

A fullselect that contains no UNION or UNION ALL clauses is simply a subselect. A fullselect can combine multiple subselects (and fullselects) by repeated use of the UNION and UNION ALL keywords. Only the final query in a fullselect ends with a semicolon. The absence of semicolons after the preceding queries is what makes SQL cognizant that these queries are part of a UNION.

UNION

Combines the results output of columns from two separate tables as though they were one. The column headings are omitted in the result because no columns produced by a union are directly extracted from a single table. In order for two or more queries to undergo a union, their output columns must be union compatible. This means that the queries must each specify the same number of columns and in such an order that the first, second, third, and so on, of each is of a compatible data type with the first, second, third, and so on, of all the others.

UNION ALL

Same as UNION, but includes all duplicate data rows in the output (UNION eliminates all redundant combinations of data values, therefore making every row of result data unique).

AS

The AS clause affects column names in the results of fullselects. If the nth result columns of two queries combined in a UNION have the same result column name (defined with an AS clause), then the nth column of the final UNION result has the same defined column name.

Select Statement

The select statement is the form of a query that can be directly specified in a DECLARE CURSOR statement or prepared and then referenced in a DECLARE CURSOR statement.

Syntax

The select statement syntax appears below:

fullselect [order-by-clause] [update-clause]
    {[FOR FETCH ONLY] [FOR READ ONLY]}
    [optimize-for-clause]
    [with-clause]
    [queryno-clause]
    [fetch-first-clause]

order-by-clause:

ORDER BY {column-name | integer}
    {ASC | DESC}[,...]

update-clause:

FOR UPDATE OF column-name[,...]

optimize-for-clause:

OPTIMIZE FOR integer {ROWS | ROW}

with-clause:

WITH {CS | RR | UR}

queryno-clause:

QUERYNO integer

fetch-first-clause:

FETCH FIRST {1 | integer} {ROW | ROWS} ONLY

Parameters:

column-name | Uniquely identifies a column of the result table. A named column may be identified by an integer or column-name. An unnamed column must be identified by an integer (below).
integer | An integer value greater than zero, and not greater than the number of columns in the result table. The integer n identifies the nth column of the result table.

Description

The table specified by the select statement is the result of a fullselect. The tables or views identified can reside in the currently set location or at any other accessible location under the XDB Server. To access other locations, specify a three-part name (or alias) or issue a CONNECT or SET LOCATION TO command prior to issuing the select statement.

FOR FETCH ONLY

Including this clause or the FOR READ ONLY clause (in DB2 Version 4.1), declares that the result table is read-only. A read-only result table must not be referred to by any UPDATE or DELETE statements. These limitations apply to result tables that are intrinsically read-only (such as those based on read-only views), and those for which the FOR FETCH ONLY or FOR READ ONLY clause is specified by the user.

Cursors with read-only result tables cannot be referred to in positioned UPDATE and DELETE statements, since data is fetched between client and server in large blocks. However, if no positional updates are needed, the FOR FETCH ONLY clause can still be used to improve fetch performance.

Specifying FOR FETCH ONLY activates Bulk Fetching, which improves the performance of FETCH operations. When a query is Bulk Fetched, data is transferred to the client in bulk, instead of one row at a time. The bulk size depends on the number of records that can be transferred, which in turn is influenced by the number of columns selected, data types and the overhead.

ORDER BY

This clause specifies an order for result table rows. If one column-name is identified, the rows are ordered by the data values within the column. If more than one column-name is identified, the rows are ordered by the values of the first column, then by the values of the second column, etc. ASC uses the values of the identified column in ascending order (default), while DESC uses the values of the column in descending order. If the ORDER BY clause is not specified, the rows of the result table have an arbitrary order.

The inclusion of an AS clause in the fullselect allows a named column to be identified by a column name. An unnamed column must be identified by an integer. A column is unnamed if the AS clause is not specified and it is derived from a constant, an expression with operators, or a function. If the fullselect includes a UNION operator, the fullselect rules on named columns apply.

FOR UPDATE OF

The UPDATE clause identifies the columns that can be updated in a later positioned UPDATE statement. The FOR UPDATE OF clause restricts the table columns that can be updated to those specified in the column-name list. These column names must be defined for the table or view appearing in the first FROM clause of the fullselect, and must not be qualified. FOR UPDATE OF cannot be used if the result table is read-only, nor can it be used in a statement containing a FOR FETCH ONLY clause.

OPTIMIZE FOR

This optional clause can be placed either before or after any accompanying FOR FETCH ONLY clause. OPTIMIZE FOR tells the XDB Server to proceed under the assumption that "at most a total of integer rows are to be retrieved from the result table." Without this clause, the XDB Server will assume that all rows of the result table are to be retrieved (and optimized accordingly).

OPTIMIZE FOR does not actually affect the composition or ordering of the result table. Optimizing for a limited (integer) number of rows can improve fetch performance if subsequent fetches are limited to integer rows. Any number of rows can be fetched after using the OPTIMIZE FOR clause, but after a total of integer rows are fetched, subsequent fetch performance may degrade.

WITH

You can override the isolation level for all SQL statements specified in a statement with the ISOLATION option by using the WITH clause on individual SQL statements. The WITH clause overrides the default isolation level only for the statement in which it appears. The WITH clause cannot be used on subselects.

The following three isolation levels can be specified:

CS | Cursor stability
RR | Repeatable read
UR | Uncommitted read

WITH UR can be specified only after SELECT, and only if the result table is read-only. A simple way to assure that a result table is read-only is to specify FOR FETCH ONLY or FOR READ ONLY. More information on isolation levels can be found in the Server Administration Guide.

FETCH FIRST

The FETCH FIRST clause limits the number of rows that can be fetched. It can improve the performance of queries with potentially large result sets when only a limited number of rows are needed. If the clause is specified, the number of rows retrieved will not exceed n, where n is the value of the integer. An attempt to fetch n+1 rows is handled the same way as normal end of data. The value of integer must be positive and non-zero. The default is 1.

If the OPTIMIZE FOR clause is not specified, a default of "OPTIMIZE FOR integer ROWS" is assumed. If both the FETCH FIRST and OPTIMIZE FOR clauses are specified, the lower of the integer values from these clauses is used to influence optimization and the communications buffer size.

If both the FETCH FIRST clause and the ORDER BY clause are specified, the ordering is performed on the entire result set prior to returning the first n rows.

More On SELECT

Due to the relative importance and complexity of SELECT commands (and supporting clauses), this command is described in detail (including numerous examples) in the following topics:

  • SELECT Clause - includes selecting DISTINCT values, retrieving all column values, and selecting constants and expressions.
  • FROM Clause - discusses how to select data from one or more tables or views, and how to use correlation names to qualify the source of data. The newly supported join syntax is also covered.
  • WHERE Clause - describes how to construct simple and complex search conditions using a variety of operators, how to perform string pattern matching using LIKE, how to create join conditions. Covers nested queries using ALL, ANY, EXISTS, etc., and correlated subselects.
  • Other Clauses - include the GROUP BY, HAVING, ORDER BY and FOR UPDATE OF clauses, and the UNION operator.
  • Functions - describes standard SQL functions, as well as special XDB Server functions, including recursive inference functions, aggregate functions, date functions, math functions, and string functions -- most of which can be incorporated into SELECT command statements.
Parent topic: SQL Statements
Related information
SELECT Clause Syntax and Description
FROM Clause Syntax and Description
WHERE Clause Syntax and Description
GROUP BY Clause
Functions Overview


SELECT INTO

The SELECT INTO command (embedded SQL only) retrieves one row of values from a table or view, and then assigns these values to one or more host variables specified in the SELECT INTO command statement.
Restriction: This topic applies to Windows environments only.

Invocation

SELECT INTO is an executable command that can only be embedded in a host language. SELECT cannot be dynamically prepared. Tables or views identified in the SELECT INTO statement can exist at the current location or any other location existing under (or accessible from) the XDB Server.

Authorization

In order to select data from a table or view users must possess either SELECT or EXECUTE authority on the table or view accessed, DBADM authority on the database, SYSADM or SYSCTRL authority for the location, or be the owner of the table or view.

Syntax

SELECT projection-list INTO host-var-list
    FROM table-view-list
    [WHERE search-condition]
    [group-by-clause]
    [having-clause]
    [order-by-clause]
    [WITH {RR [lock-clause] | RS [lock-clause] | CS | UR}]
    [QUERYNO integer]
    [FETCH FIRST [1] {ROW | ROWS} ONLY]
order-by-clause
ORDER BY {sort-key [ASC | DESC] [,...] | INPUT SEQUENCE}
sort-key
{column-name | integer | expression}
lock-clause
USE AND KEEP {EXCLUSIVE | UPDATE | SHARE} LOCKS

Parameters:

projection-list | Preceded by the keyword SELECT, lists one or more columns and/or expressions.
host-var-list | Preceded by the keyword INTO, lists one or more host variables (separated by commas) that have been described in the host program according to the rules for describing host variables. See the examples for additional language specific information.
table-view-list | Preceded by the keyword FROM (see FROM Clause Syntax and Description), lists one or more tables or views separated by commas.
search-condition | Preceded by the keyword WHERE (see WHERE Clause Syntax and Description), describes one or more row selection criteria. Multiple selection conditions can be specified together using the AND and OR logical operators.

Description

A SELECT INTO command can retrieve at most one row from a table or view. If the selected table is empty, the SQLCODE indicator field in the SQLCA is assigned a value of +100. If the statement retrieves more than one row of data an error condition results (assigning SQLCODE a value of -811).

The SELECT INTO command statement differs from other types of SELECT commands in that retrieved row values are assigned directly to host variables specified in the INTO clause. Retrieved table values are derived by first evaluating the FROM clause, followed by the WHERE and SELECT clauses.

The INTO clause cannot appear in nested SELECT commands. ORDER BY and UNION are not allowed in SELECT commands containing an INTO clause. When a SELECT command includes an INTO clause, GROUP BY and HAVING are allowed only in nested select statements.

If no rows are retrieved, +100 is placed in SQLCODE, and the host variables are unchanged. If an error occurs when evaluating any column in the projection list a null value is placed in the host variable. To retrieve multiple rows of table values using an embedded SELECT statement, use a DECLARE CURSOR command statement along with the FETCH command.

WITH Clause

Specifies an isolation level with which the statement is executed. You can override the isolation level of the statement using the WITH {CS | RS | RR | UR} clause. You can only specify the isolation levels that specifically apply to a statement. WITH UR can be specified only after SELECT and only if the result table is read-only. The WITH clause overrides the isolation level only for the statement in which it appears.

When you specify WITH RR KEEP UPDATE LOCKS, XDB Server acquires an exclusive (X) lock, instead of a shared (S) lock, on all the pages or rows that fall within the range of the selection expression. All the X locks are retained until the next commit point.

See the Server Administration Guide for information about locking and isolation levels.

QUERYNO integer

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Example:

The hostvarlist parameter is a list of host variables, the total of which are equal to the number of columns in projection-list.

Here is an example of a SELECT INTO statement. The record returned will be read into the host variables CNO and NAME (like FETCH):

EXEC SQL
    SELECT cno, name
        INTO :CNO, :NAME
        FROM cust
        WHERE name = :incno
END-EXEC
Parent topic: SQL Statements


SET AUTOCOMMIT

The SET AUTOCOMMIT command is used to turn autocommit on or off. When autocommit is on, a command is automatically committed as soon as it is successfully executed.
Restriction: This topic applies to Windows environments only.

Invocation

SET AUTOCOMMIT is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET AUTOCOMMIT can be dynamically prepared.

Authorization

No special authorization is required to set autocommit on or off.

Syntax

SET AUTOCOMMIT {ON | OFF}

Description

You can use autocommit to automatically commit a command as soon as it is successfully executed. If autocommit is on, an implicit COMMIT is issued at command completion or the close of a cursor (for SELECT statements). If Backward Logging is turned on, the autocommit feature causes the contents of the Backward Log to be cleared after each transaction. However, the release of resources such as locks and cursors occurs independently of Backward Logging.

Example:

The command to turn autocommit on is:

SET AUTOCOMMIT ON

To turn autocommit off:

SET AUTOCOMMIT OFF
Parent topic: SQL Statements


SET COMPATIBILITY

The SET COMPATIBILITY command is used to specify a mode of operation. When a particular mode is in effect, SQL commands must adhere to the syntax of that mode.
Restriction: This topic applies to Windows environments only.

Invocation

SET COMPATIBILITY is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET COMPATIBILITY can be dynamically prepared.

Authorization

No special authorization is required to specify an XDB Server compatibility mode.

Syntax

SET COMPATIBILITY {DB2 | XDB | ANSI}

Description

This command allows compatibility to change dynamically so you can mix compatible commands only available in certain modes within a particular program. (The functionality of this command is identical to the DB2 command SET CURRENT RULES.) This is useful within an application that executes predominantly in one mode, but in which you need to change to another mode for a particular operation.

Example:

To specify the DB2 compatibility mode enter the following:

SET COMPATIBILITY DB2
Parent topic: SQL Statements


SET CONNECTION

The SET CONNECTION statement establishes the application server of the process by identifying one of its existing connections.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be embedded in an application program, except in REXX programs. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

SET CONNECTION {location-name | host-variable}

Description

Identifies the SQL connection by the specified location name or the location name contained in the host variable. If a host variable is specified:

  • It must be a character string variable with a length attribute that is not greater than 16. (A C NUL-terminated character string can be up to 17 bytes.)
  • It must not be followed by an indicator variable.
  • The location name must be left-justified within the host variable and must conform to the rules for forming an ordinary location identifier.
  • If the length of the location name is less than the length of the host variable, it must be padded on the right with blanks.

Let S denote the specified location name or the location name contained in the host variable. S must identify an existing SQL connection of the application process. If S identifies the current SQL connection, the state of S and all other connections of the application process are unchanged. The following rules apply when S identifies a dormant SQL connection.

If the SET CONNECTION statement is successful:

  • SQL connection S is placed in the current state.
  • S is placed in the CURRENT SERVER special register.
  • Information about application server S is placed in the SQLERRP field of the SQLCA. If the application server is an IBM product, the information has the form pppvvrrm, where:
    ppp

    One of:

    ARI | DB2 Server for VSE & VM
    DSN | DB2 for OS/390
    QSQ | OS/400
    SQL | all other DB2 products
    vv

    is a two-digit version identifier such as '06'.

    rr

    is a two-digit release identifier such as '01'.

    m

    is a one-digit modification level such as '0'.

For example, if the server is Version 6 of DB2 for OS/390 with the latest maintenance, the value of SQLERRP is 'DSN06011'. Any previously current SQL connection is placed in the dormant state.

If the SET CONNECTION statement is unsuccessful, the connection state of the application process and the states of its SQL connections are unchanged.

Examples:

Execute SQL statements at TOROLAB1, execute SQL statements at TOROLAB2, and then execute more SQL statements at TOROLAB1.

EXEC SQL CONNECT TO TOROLAB1;

(execute statements referencing objects at TOROLAB1)

EXEC SQL CONNECT TO TOROLAB2;

(execute statements referencing objects at TOROLAB2)

EXEC SQL SET CONNECTION TOROLAB1;

(execute statements referencing objects at TOROLAB1)

The first CONNECT statement creates the TOROLAB1 connection, the second CONNECT statement places it in the dormant state, and the SET CONNECTION statement returns it to the current state.

Parent topic: SQL Statements


SET CURRENT DEGREE

This command is supported only syntactically by the XDB Server.
Restriction: This topic applies to Windows environments only.

Invocation

SET CURRENT DEGREE is an executable statement that can be embedded in an application program, issued interactively, or dynamically prepared.

Authorization

No special authorization is required.

Syntax

This command is supported only syntactically.

SET CURRENT DEGREE =
    { string-constant | host-variable }

This command is supported only syntactically.

SET CURRENT DEGREE =
    { string-constant | host-variable }

Parameters:

string-constant | When used with DB2, this string constant value must be a character string not longer than three bytes, and enclosed in quotation marks (see DB2 documentation for allowed values).
host-variable | When used with DB2, this host variable value must be a character string not longer than three bytes (see DB2 documentation for allowed values).

Description

On mainframe DB2 systems, this command assigns a value to the CURRENT DEGREE special register. On the XDB Server, this command also places a value in the CURRENT DEGREE special register, although the "degree of parallelism" is not affected. See your DB2 documentation for more information.

Example:

The following example sets the CURRENT DEGREE special register to the string "ANY".

SET CURRENT DEGREE = 'ANY'
Parent topic: SQL Statements
Related information
Syntax Support Only


SET CURRENT LOCALE LC_CTYPE

The SET CURRENT LOCALE LC_CTYPE statement assigns a value to the CURRENT LOCALE LC_CTYPE special register. The special register allows control over the LC_CTYPE locale for statements that use a function that refers to a locale, such as LCASE, UCASE, and TRANSLATE (with a single argument).
Restriction: This topic applies to Windows environments only.

This command is supported only syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SET {[CURRENT [LOCALE]] LC_CTYPE | CURRENT_LC_CTYPE}
    [=]
    {string-constant | host-variable}

Description

The value of CURRENT LOCALE LC_CTYPE is replaced by the string constant or host variable specified. The value must be a CHAR or VARCHAR character string that is no longer than 50 bytes.

If a host variable is specified, its value must not be null. If it has an associated indicator, the value of the indicator value must not indicate a null value. The locale must:

  • Be left justified within the host variable
  • Be padded on the right with blanks if its length is less than that of the host variable

The value of CURRENT LOCALE LC_CTYPE is replaced by the value specified. The value must not be longer than 50 bytes and must be a valid locale.

string-constant

A character string constant that must not be longer than 50 bytes and must represent a valid locale.

host-variable

A variable with a data type of CHAR or VARCHAR and a length that is not longer than 50 bytes. The value of host-variable must not be null and must represent a valid locale. If the host variable has an associated indicator variable, the value of the indicator variable must not indicate a null value.

The locale must:

  • Be left justified within the host variable
  • Be padded on the right with blanks if its length is less than that of the host variable

A locale can be specified in uppercase characters, lowercase characters, or a combination of the two.

Some examples of locales include:

  • Fr_BE
  • Fr_FR@EURO
  • En_US
  • Ja_JP

Example:

Set the CURRENT LOCALE LC_CTYPE special register to the locale 'En_US'.

EXEC SQL SET CURRENT LOCALE LC_CTYPE = 'En_US';
Parent topic: SQL Statements


SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION

The SET CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION statement changes the value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register.
Restriction: This topic applies to Windows environments only.

This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET CURRENT MAINTAINED [TABLE] TYPES [FOR OPTIMIZATION]
     [=] {ALL | NONE | SYSTEM | USER | host-variable}

Description

The value indicates which materialized query tables that are enabled for optimization are considered when optimizing the processing of dynamic SQL queries.

ALL

Indicates that all materialized query tables will be considered.

NONE

Indicates that no materialized query tables will be considered.

SYSTEM

Indicates that only system-maintained materialized query tables that are refresh deferred will be considered.

USER

Indicates that only user-maintained materialized query tables that are refresh deferred will be considered.

host-variable

A variable of type CHAR or VARCHAR. The length of the contents of host-variable must not exceed 255 bytes. It cannot be set to null. If host-variable has an associated indicator variable, the value of that indicator variable must not indicate a null value.

The characters of host-variable must be left justified. The content of the host variable must be a string that would match what can be specified as keywords for the special register in the exact case intended as there is no conversion to uppercase characters.

Note:
  • The initial value of the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register is determined by the value on the CURRENT MAINT TYPES field on installation panel DSNTIP8. The default value of the field is SYSTEM.
  • The CURRENT REFRESH AGE special register needs to be set to a value other than zero in order for the specified types of objects to be considered for optimizing the processing of dynamic SQL queries.
  • The CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register affects dynamic statement cache matching.
Parent topic: SQL Statements


SET CURRENT OPTIMIZATION HINT

The SET CURRENT OPTIMIZATION HINT statement assigns a value to the CURRENT OPTIMIZATION HINT special register.
Restriction: This topic applies to Windows environments only.

This command is supported only syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SET CURRENT OPTIMIZATION HINT = {string-constant | host-variable}

Description

The value of special register CURRENT OPTIMIZATION HINT is replaced by the value of the string constant or host variable. The value must be a character string that is not longer than 8 bytes.

The initial value of the CURRENT OPTIMIZATION HINT special register is set to the value that was used for the OPTHINT bind option. The OPTHINT bind option specifies whether optimization hints are used in determining the access path of static statements and identifies which user-defined hint (rows in the authid.PLAN_TABLE) is used. Therefore, if the SET CURRENT OPTIMIZATION HINT statement is not executed to change the value of the special register, DB2 uses the same optimization hint for dynamic statements that it uses for static statements. The default of OPTHINT for BIND PLAN and BIND PACKAGE is all blanks. All blanks indicate that DB2 uses normal optimization techniques and ignores optimization hints.

Example:

Assume that delimited identifier 'NOHYB' identifies a user-defined optimization hint in authid.PLAN_TABLE. Set the CURRENT OPTIMIZATION HINT special register so that DB2 uses this optimization hint to generate the access path for dynamic statements.

SET CURRENT OPTIMIZATION HINT = 'NOHYB'
Parent topic: SQL Statements


SET CURRENT PACKAGE PATH

The SET CURRENT PACKAGE PATH assigns a value to the CURRENT PACKAGE PATH special register.
Restriction: This topic applies to Windows environments only.

This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded only in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET CURRENT PACKGE PATH [=]
     {collection-id |
      USER |
      CURRENT PACKAGE PATH |
      host-variable |
      string-constant} [,...]
Note: USER, CURRENT PACKAGE PATH, and CURRENT PATH can be specified only once on the right side of the statement.

Description

The value of CURRENT PACKAGE PATH is replaced by the values specified.

collection-id

Identifies a collection. collection-id must not be a delimited identifier that is empty or contains only blanks.

USER

Specifies the value of the USER special register.

CURRENT PACKAGE PATH

Specifies the value of the CURRENT PACKAGE PATH special register before the execution of the SET CURRENT PACKAGE PATH.

CURRENT PATH

Specifies the value of the CURRENT PATH special register.

host-variable

Specifies a host variable that contains one or more collection IDs, separated by commas. The host variable must:

  • Have a data type of CHAR or VARCHAR. The actual length of the contents of the host variable must not exceed the maximum length of the CURRENT PACKAGE PATH special register.
  • Not be the null value if an indicator variable is provided.
  • Contain an empty or blank string, or one or more collection IDs that are separated by commas.
  • Be padded on the right with blanks if the host variable is fixed-length, or if the actual length of the host variable is longer than the content.
  • Not contain a delimited identifier that is empty or contains only blanks.

string-constant

Specifies a string constant that contains one or more collection IDs, separated by commas. The string constant must:

  • Have a length that does not exceed the maximum length of the CURRENT PACKAGE PATH special register.
  • Contain an empty or blank string, or one or more collection IDs separated by commas.
  • Not contain a delimited identifier that is empty or contains only blanks.
Note:
  • The contents of a host variable or string constant are interpreted as a list of collection IDs if the value contains at least one comma. If multiple collection IDs are specified, they must be separated by commas. Each collection ID in the list must conform to the rules for forming an ordinary identifier or be specified as a delimited identifier.
  • No validation that the collections exist is made at the time that the CURRENT PACKAGE PATH special register is set. For example, a collection ID that is misspelled is not detected, which could affect the way subsequent SQL operates. At package execution time, authorization to the specific package is checked, and if this authorization check fails, an error is issued.
  • The special register string is built by taking each collection ID specified and removing trailing blanks, delimiting with double quotation marks, doubling any double quotation marks within the collection ID as necessary, and then separating each collection ID by a comma. If the same collection ID appears more than once in the list, the first occurrence of the collection is used. The length of the resulting list cannot exceed the length of the special register. For example, assume that the following statements are issued:
    SET CURRENT PACKAGE PATH = MYPKGS, "ABC E", SYSIBM
  SET :HVPKLIST = CURRENT PACKAGE PATH

    These statements result in the value of the host variable being set to: "MYPKGS", "ABC E", "SYSIBM". A collection ID that does not conform to the rules for an ordinary identifier must be specified as a delimited collection ID and must not be specified within a host variable or string constant.

  • A difference exists between specifying a single keyword, such as USER, as a single keyword or as a delimited identifier. To indicate that the current value of a special register that is specified as a single keyword should be used in the package path, specify the name of the special register as a keyword. If you specify the name of the special register as a delimited identifier, it is interpreted as a collection ID of that value. For example, assume that the current value of the USER special register is SMITH and that the following statement is issued:
    SET CURRENT PACKAGE PATH = SYSIBM, USER, "USER"

    The result is that the value of the CURRENT PACKAGE PATH special register is set to: "SYSIBM, "SMITH", "USER".

  • Because a host variable (SQL variable) in an SQL procedure does not begin with a colon, DB2 uses the following rules to determine whether a value that is specified in a SET PACKAGE PATH = name statement is a variable or a collection ID:
    • If name is the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a parameter or SQL variable and assigns the value in name to the package path.
    • If name is not the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a collection ID and assigns and the value in name is the package path.
  • The SET CURRENT PACKAGE PATH statement is executed by the database server and, therefore, is classified as a non-local SET statement in DRDA. The SET CURRENT PACKAGE PATH statement requires a new level of DRDA support. If SET CURRENT PACKAGE PATH is issued when connected to the local server, the SET CURRENT PACKAGE PATH special register at the local server is set. Otherwise, when SET CURRENT PACKAGE PATH is issued when connected to a remote server, the SET CURRENT PACKAGE PATH special register at the remote server is set.
Parent topic: SQL Statements


SET CURRENT PACKAGESET

On mainframe DB2 and XDB Servers, this command assigns a value to the CURRENT PACKAGESET special register. This command is partially supported by the XDB Server, which adopts the CURRENT SQLID as the qualifier for the package.
Restriction: This topic applies to Windows environments only.

Invocation

SET CURRENT PACKAGESET is an executable statement that can only be embedded in an application program. It cannot be dynamically prepared.

Authorization

No special authorization is required.

Syntax

SET CURRENT PACKAGESET =
    { USER | string-constant | host-variable }

Parameters:

USER | The value contained in the USER special register.
string-constant | When used with DB2, this string constant value must be a character string not longer than 128 bytes, and enclosed in quotation marks (see DB2 documentation for allowed values).
host-variable | The CURRENT PACKAGESET special register value can be assigned to a host variable in your program using the SET Host Variable command. When used with DB2, this host variable value must be a character string not longer than 128 bytes (see DB2 documentation for allowed values).

Description

In DB2, each program is bound with a default SQLID. Likewise, each package accessed by a program can be bound with a different default SQLID. The AuthID values comprising these various default SQLIDs must somehow be retrieved into the CURRENT SQLID special register within XDB Server whenever package access changes during program execution. The contents of the CURRENT SQLID special register provides the implicit AuthID qualifier support necessary for one-part table names, and this register value must be updated to match the default SQLID of the currently executing package.

The XDB Server does not directly support binding, but emulates this functionality by retrieving default package SQLIDs into the CURRENT SQLID special register. This retrieval needs to happen whenever a SET CURRENT PACKAGESET command switches package access within an executing program. Therefore, the value of the CURRENT SQLID special register in XDB Server can change depending on the name of the executing program, and the contents of the CURRENT PACKAGESET special register.

XDB Server Precompiler

To take advantage of the packageset functionality above, the program must be precompiled using the PKGSET directive. This directive causes the program name to be passed to the engine for all SQL calls within any program precompiled with this directive. The engine, in turn, uses the program name to look up package information in the system tables.

System Tables

Records must also be manually added to the SYSIBM.SYSPACKLIST and SYSIBM.SYSPACKAGE tables for all programs requiring packageset functionality. These tables will be automatically created with the CREATE LOCATION command. Alternatively, they will be created when a package command is issued. To create these system tables in an existing location, issue the following command from SQLWizard:

SET CURRENT PACKAGESET = 'test'

The records for these tables currently need to be added manually (using SQLWizard or Migrate.). Ideally, these records can be imported directly from DB2. The XDB Server software does not add these records automatically at precompile and compile time. Because these are system tables, the user who edits the records must be a super user. The only record fields that must be added to the SYSIBM.SYSPACKAGE table are the LOCATION, COLLID and QUALIFIER column values. All other data is inconsequential. Likewise, the only field values that must be added to the SYSIBM.SYSPACKLIST table are the LOCATION and COLLID column values.

The SET CURRENT PACKAGESET command functional support consists of the following steps:

  1. When a program precompiled with the PKGSET directive accesses the engine the following query is performed:
    SELECT x.qualifier, x.collid, y.seqno
    FROM sysibm.syspackage x, sysibm.syspacklist y
    WHERE y.name IN ('*', program_name)
      AND y.location IN (' ', current_location)
      AND x.collid = y.collid
      AND x.name = program_name
    ORDER BY y.seqno
  2. If the CURRENT PACKAGESET special register is not empty, the following predicate will be added to the query above:
    AND x.collid = current_packageset_special_register
  3. If a record matches the criteria, the CURRENT SQLID special register is updated with the QUALIFIER column contents of the first record retrieved by the query (lowest SEQNO column value). This new value becomes the implicit AuthID for one-part table names.
  4. Once a value is retrieved for a particular program name and package combination, it is cached. Subsequent calls check the cache prior to checking the catalog using the above query.
  5. If either the program name (due to a subroutine call) or CURRENT PACKAGESET special register (due to a SET CURRENT PACKAGESET COMMAND) changes, an automatic lookup is triggered and the CURRENT SQLID is changed accordingly.

special register with stored procedures and user-defined functions

The initial value of the CURRENT PACKAGESET special register in a stored procedure or user-defined function is the value of the COLLID parameter with which the stored procedure or user-defined function was defined. If the routine was defined without a value for the COLLID parameter, the value of the special register is inherited from the calling program. A stored procedure or user-defined function can use the SET CURRENT PACKAGESET statement to change the value of the special register. This allows the routine to select the version of the DB2 package that is used to process the SQL statements in a called routine that is not defined with a COLLID value.

Example:

The following example assigns a value of 'Staff' to the CURRENT PACKAGESET special register.

SET CURRENT PACKAGESET = 'Staff'
Parent topic: SQL Statements


SET CURRENT PATH

The SET CURRENT PATH statement assigns a value to the CURRENT PATH special register.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

SET {[CURRENT [FUNCTION]] PATH | CURRENT_PATH} [=]
{   schema-name
    | SYSTEM PATH
    | USER
    | {[CURRENT [FUNCTION]] PATH | CURRENT_PATH}
    | CURRENT PACKAGE PATH
    | host-variable
    | string-constant
} [,...]

Description

The value of CURRENT PATH is replaced by the values specified.

schema-name
Identifies a schema. DB2 does not verify that the schema exists. For example, a schema name that is misspelled is not detected, which could affect the way subsequent SQL operates.
SYSTEM PATH
Specifies the schema names "SYSIBM", "SYSFUN" , "SYSPROC". SYSTEM PATH can be specified only once.
USER
Specifies the value of the USER special register. USER can be specified only once.
CURRENT PATH
Specifies the value of the CURRENT PATH special register before the execution of this statement. CURRENT PATH can be specified only once.
host-variable
A variable with a data type of CHAR or VARCHAR. The value of host-variable must not be null and must represent a valid schema name.

The schema name must:

  • Be left justified within the host variable
  • Be padded on the right with blanks if its length is less than that of the host variable
string-constant

A character string constant that represents a valid schema name.

If the schema name specified in string-constant will also be specified in other SQL statements and the schema name does not conform to the rules for ordinary identifiers, the schema name must be specified as a delimited identifier in the other SQL statements.

Restrictions on SET CURRENT PATH
These restrictions apply to the SET CURRENT PATH statement:
  • If the same schema name appears more than once in the path, the first occurrence of the name is used and a warning is issued.
  • The length of the CURRENT PATH special register limits the number of schema names that can be specified. DB2 builds the string for the special register by taking each schema name specified and removing any trailing blanks from it, adding two delimiters around it, and adding one comma after each schema name except the last one. The length of the resulting string cannot exceed 254 bytes.
Specifying SYSIBM and SYSPROC
Schemas SYSIBM and SYSPROC do not need to be specified in the special register. If either of these schemas is not explicitly specified in the CURRENT PATH special register, the schema is implicitly assumed at the front of the SQL path; if both are not specified, they are assumed in the order of SYSIBM, SYSPROC.
Specifying USER versus "USER"

There is a difference between specifying USER with and without escape characters. To indicate that the value of the USER special register should be used in the SQL path, specify the keyword USER. If you specify USER as a delimited identifier instead (for example, "USER"), it is interpreted as a schema name of "USER". For example, assuming that the current value of the USER special register is SMITH, SET CURRENT PATH = SYSIBM, SYSPROC, USER, "USER" results in SYSIBM, SYSPROC, SMITH, USER being used in the SQL path.

Specifying a schema name in an SQL procedure

Because a host variable (SQL variable) in an SQL procedure does not begin with a colon, DB2 uses the following rules to determine whether a value that is specified in a SET CURRENT PATH=name statement is a variable or a string constant:
  • If name is the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a parameter or SQL variable and assigns the value in name to CURRENT PATH.
  • If name is not the same as a parameter or SQL variable in the SQL procedure, DB2 uses name as a string constant and assigns the value name to CURRENT PATH.

Examples:

Set the CURRENT PATH special register to the list of schemas: "SCHEMA1", "SCHEMA#2", "SYSIBM".

SET CURRENT PATH = SCHEMA1,"SCHEMA#2", SYSIBM;

If the special register provides the SQL path, then SYSPROC, which was not explicitly specified in the special register, is implicitly assumed at the front of the SQL path, making the effective value of the path:

SYSPROC, SCHEMA1, SCHEMA#2, SYSIBM
Parent topic: SQL Statements


SET CURRENT REFRESH AGE

The SET CURRENT REFRESH AGE statement changes the value of the CURRENT REFRESH AGE special register.
Restriction: This topic applies to Windows environments only.

The CURRENT REFRESH AGE value corresponding to ANY (99 999 999 999 999) cannot be used in timestamp arithmetic operations because the result would be outside the valid range of dates.

This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET CURRENT REFRESH AGE [=] {numeric-constant | ANY | host-variable}

numeric-constant

A DECIMAL(20,6) value representing a timestamp duration. The value must be 0 or 99 999 999 999 999, the microseconds of which is ignored and thus can be any value.

0 | Indicates that query optimization using materialized query tables will not be attempted.
99999999999999 | Indicates that any materialized query tables identified by the CURRENT MAINTAINED TABLE TYPES FOR OPTIMIZATION special register may be used to optimize the processing of a query. This value represents 9999 years, 99 months, 99 days, 99 hours, 99 minutes, and 99 seconds.

ANY

Shorthand for 99999999999999.

host-variable

A variable of type DECIMAL(20,6) or other type that is assignable to DECIMAL(20,6). It cannot be set to null. If host-variable has an associated indicator variable, the value of that indicator variable must not indicate a null value. The value of host-variable must be 0 or 99 999 999 999 999, the microseconds of which is ignored and thus can be any value.

Note:
  • Materialized query tables created or altered with DISABLE QUERY OPTIMIZATION specified are not eligible for automatic query rewrite. Thus, they are not affected by the setting of this special register.
  • Setting the CURRENT REFRESH AGE special register to a value other than zero should be done with caution. Allowing a materialized query table that may not represent the values of the underlying base table to be used to optimize the processing of a query may produce results that do not accurately represent the data in the underlying table. This situation may be acceptable when you know the underlying data has not changed or you are willing to accept the degree of error in the results based on your knowledge of the data.
Parent topic: SQL Statements


SET CURRENT RULES

The SET CURRENT RULES statement assigns a value to the CURRENT RULES special register.
Restriction: This topic applies to Windows environments only.

Invocation

SET CURRENT RULES is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

None required.

Syntax

SET CURRENT RULES = {'DB2' | 'STD' | host-variable}

Parameters:

DB2 | Causes commands to execute according to DB2 rules.
STD | Causes commands to execute according to ANSI/ISO rules.
host-variable | Names a host variable (character string not longer than eight bytes) containing the value to be assigned to the special register CURRENT RULES. The value must be either 'DB2' or 'STD', and must be a character string three bytes in length.

Description

This statement replaces the value of the CURRENT RULES special register with the value of the string constant or host variable. The functionality of this command is identical to the XDB Server command SET COMPATIBILITY. One particular application of this special register value is that it controls the way table check constraints are enforced. The contents of CURRENT RULES chooses one of two distinct SQL rules that will apply to already populated tables containing check constraints. If the value is STD, a check constraint is enforced as soon as it is defined. If a row does not conform, the table check constraint is not added to the table and an error occurs. If the value is DB2, the check constraint is added to the table description but its enforcement is deferred. Because there might be rows in the table that violate the check constraint, the table is placed in check pending status.

Example:

The example below sets the CURRENT RULES special register to a value of DB2.

SET CURRENT RULES = 'DB2'
Parent topic: SQL Statements


SET CURRENT SQLID

The SET CURRENT SQLID statement changes the AuthID value stored in the CURRENT SQLID special register.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared. The value to which special register CURRENT SQLID is set is used as the SQL authorization ID and the implicit qualifier for dynamic SQL statements only if DYNAMICRULES run behavior is in effect. The CURRENT SQLID value is ignored for the other DYNAMICRULES behaviors.

Authorization

In most cases, the CURRENT SQLID value must equal one of the AuthIDs of the session. If one of these session AuthIDs possesses SYSADM authority for the location, then CURRENT SQLID can be set to any valid AuthID within the location.

Syntax

SET CURRENT SQLID = {USER | string-constant | host-variable}

Parameters:

USER | Is the special register USER, containing a valid AuthID of the session.
string-constant | A character string -- not longer than eight bytes and surrounded by quotes -- identifying a valid AuthID of the session.
host-variable | Identifies a host variable containing a character string (not longer than eight bytes) identifying a valid AuthID of the session.

Description

The initial value of the SQL AuthID (SQLID) is established during connection or XDB Server log on. The value specified in the SET CURRENT SQLID statement remains the SQLID until the XDB Server connection is terminated, the SQLID is changed by executing a new SET CURRENT SQLID statement or when a SET LOCATION command is issued. SET LOCATION resets the SQLID to either the Primary AuthID value stored in CONFIG.XDB (if security is off) or the initial Primary AuthID value established during your security login.

The CURRENT SQLID value is the AuthID used for authorization checking on CREATE, GRANT and REVOKE statements. CURRENT SQLID is also used in all other permission situations, such as SELECT statements or any other DML commands.

Additionally, the CURRENT SQLID owns whatever table spaces, databases, storage groups, or synonyms that are created. CURRENT SQLID is also the implicit AuthID qualifier of all table, view, alias, and index names specified in any SQL statements.

Interactive SQL

When you enter an interactive SQL session, the default AuthID becomes the initial value of the CURRENT SQLID special register. The initial value of this register can also be controlled by a SecondaryIDs specified with the SQLWizard Admin Menu commands or a security exit. The CURRENT SQLID special register retains this default value until you issue a SET CURRENT SQLID command -- replacing the initial AuthID value of CURRENT SQLID with another valid primary AuthID.

Changing CURRENT SQLID

During an interactive SQL session, the AuthID value stored within the CURRENT SQLID special register can be changed only by issuing a SET CURRENT SQLID command (or a SET PACKAGESET command). From that point on, the new AuthID value becomes the owner of any databases, tables, or synonyms created within that interactive SQL session. This new AuthID also becomes the implicit qualifier of all table, view, alias, and index names appearing in any SQL statements issued within the interactive SQL session.

Security

Whenever you start an XDB Server session with security off, the Primary AuthID value specified in the Options Utility becomes the CURRENT SQLID for that XDB Server session. If the Primary AuthID specified in the User Profile maps to a SecondaryID, then that SecondaryID becomes the default session SQLID. When security is on and you start an XDB Server session, the UserID entered becomes the CURRENT SQLID. If the UserID entered by the user has a SecondaryID, then the SecondaryID becomes the CURRENT SQLID.

Parent topic: SQL Statements


SET Host Variable

The SET host-variable assignment statement assigns values, either of expressions or NULL values, to host variables.
Restriction: This topic applies to Windows environments only.

Invocation

SET Host Variable is an executable statement that can only be embedded in a host program. The statement cannot be dynamically prepared.

Authorization

The privileges that are held by the current authorization ID must include those required to execute any of the expressions.

Syntax

SET host-variable =
{   {CURRENT SERVER | CURRENT PACKAGESET}
    | host-variable = {expression | NULL}
    | (host-variable[,...]) = ({expression | NULL} [,...] | VALUES {{expression | NULL} | ({expression | NULL}[,...])}})}

Parameters

host-variable
Identifies one or more host variables or transition variables that are used to receive the corresponding expression or NULL value on the right side of the statement.

If the SET Assignment statement is used in the triggered action of a CREATE TRIGGER statement, each host-variable must identify a transition variable. If the statement is used in any other context, each host-variable must identify a host variable.

The value to be assigned to each host-variable can be specified immediately following the item reference, for example, host-variable = expression, host-variable=expression. Or, sets of parentheses can be used to specify all the host-variables and then all the values, for example, (host-variable, host-variable) = (expression, expression).

Each host variable must be defined in the program as described under the rules for declaring host variables. A parameter marker must not be specified in place of host-variable.

expression
Specifies the value to be assigned to the corresponding host-variable.

When the host-variables are enclosed within parentheses, for example, (host-variable, host-variable, ...) = (expression, expression, ...), the first value is assigned to the first host variable in the list, the second value to the second host variable in the list, and so on.

NULL
Specifies the null value and can only be specified for host variables that have an associated indicator variable.
VALUES
Specifies the value to be assigned to the corresponding host variable. When more than one value is specified, the values must be enclosed in parentheses. Each value can be an expression or NULL, as described above. The following syntax is equivalent:
(host-variable, host-variable) = (VALUES(expression, NULL))
(host-variable, host-variable) = (expression, NULL)

Special Registers

Local special registers can be referenced only in a VALUES host-variable statement that results in the assignment of a single host variable and not those that result in setting more than one value.

Special registers that can be defined to a host variable include:

CURRENT DATE | CURRENT PACKAGESET
CURRENT TIME | CURRENT SERVER
CURRENT TIMESTAMP | CURRENT SQLID
CURRENT TIMEZONE | USER

For example: SET :your-var-name = CURRENT SERVER

The value of CURRENT SQLID can be changed by issuing a SET CURRENT SQLID command. The CURRENT PACKAGESET special register (and the SET CURRENT PACKAGESET command) currently have limited functional support by the XDB Server.

For information about each of these special registers, see Special Registers.

Parent topic: SQL Statements


SET Transitional Variable

The SET transition-variable assignment statement assigns values, either of expressions or NULL values, to transition variables.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can be used as a triggered SQL statement in the triggered action of a before trigger whose granularity is FOR EACH ROW.

Authorization

The privileges that are held by the current authorization ID must include those required to execute any of the expressions or assignments to transition variables.

Syntax

SET transition-variable =
{   {expression | NULL}
    | (transition-variable[,...]) = ({{expression | NULL} | VALUES {{expression | NULL} | ({expression | NULL}[,...])})
}

Description

Identifies a column in the set of affected rows for the trigger that is used to used to receive the corresponding expression or NULL value on the right side of the statement.

The value to be assigned to each transition-variable can be specified immediately following the transition variable, for example, transition-variable = expression, transition-variable=expression. Or, sets of parentheses can be used to specify all the transition-variables and then all the values, for example, (transition-variable, transition-variable) = (expression, expression).

correlation-name | Identifies the correlation name given for referencing the NEW transition variables. The name must match the correlation name specified following NEW in the REFERENCING clause of the CREATE TRIGGER statement.
 | If OLD is not specified in the REFERENCING clause, correlation-name defaults to the correlation name following NEW.
column-name | Identifies the column to be updated. The name must identify a column of the triggering table. The name can identify an identity column that is defined as GENERATED BY DEFAULT but not one defined as GENERATED ALWAYS. You must not specify the same column more than once.
 | The effect of a SET transition-variable statement is equivalent to the effect of an SQL UPDATE statement.

Specifies the value to be assigned to the corresponding transition-variable. A reference to a local special register is the value of that special register at the server when the trigger body is activated.

An expression can contain references to OLD and NEW transition variables that are qualified with a correlation name.

All expressions are evaluated before any result is assigned to a transition variable. If an expression refers to a transition variable that is used in the list of transition variables, the value of the variable in the expression is the value of the variable prior to any assignments.

Assignments are made in sequence through the list. When the transition-variables are enclosed within parentheses, for example, (transition-variable, transition-variable, ...) = (expression, expression, ...), the first value is assigned to the first transition variable in the list, the second value to the second transition variable in the list, and so on.

Specifies the null value and can only be specified for nullable transition variables.

Specifies the value to be assigned to the corresponding transition variable. When more than one value is specified, the values must be enclosed in parentheses. Each value can be an expression or NULL, as described above. The following syntax is equivalent:

  • (transition-variable, transition-variable) = (VALUES(expression, NULL))
  • (transition-variable, transition-variable) = (expression, NULL)

Assume that you want to create a before trigger that sets the salary and commission columns to default values for newly inserted rows in the EMPLOYEE table and that you will define the trigger only with NEW in the REFERENCING clause. Write the SET statement that assigns the default values to the SALARY and COMMISSION columns.

SET (SALARY, COMMISSION) = (50000, 8000);
Parent topic: SQL Statements


SET ISOLATION

The SET ISOLATION command is used to set the isolation level for locking in multi-user versions.
Restriction: This topic applies to Windows environments only.

Invocation

SET ISOLATION is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET ISOLATION can be dynamically prepared.

Authorization

SYSADM or SYSCTRL authority for the location is required for setting isolation level to EU (exclusive use).

Syntax

SET ISOLATION { EU | RR | CS | LC | DR | SR }

Parameters:

EU (Exclusive Use) | Locks the database for the exclusive use of the user issuing the command.
RR (Repeatable Read) | Guarantees identical results if the user issues the same SQL query more than once in a transaction. This isolation level provides minimum concurrency and maximum consistency.
CS (Cursor Stability) | Creates a lock on a record that allows the record to be read but not modified. This lock is held only while the record is the current record. Locks on modified records are held until the transaction is committed. Shared table locks can be unlocked before the end of a transaction using the UNLOCK TABLE command. The CS isolation level provides more concurrency and less consistency than RR.
LC (Lock Current) | Holds a lock on a record only while it is the current record. The LC isolation level provides a high degree of concurrency, and a very low degree of consistency, unless used for read-only operations, or with autocommit on.
DR (Dirty Read) or UR (Uncommitted Read) | Does not acquire locks on records, but reads records regardless of the locks held by others. This isolation level is be used strictly for read-only operations.
SR (Snapshot Read) | Causes a snapshot of the data to be made at the time of execution. Other users can make changes to the data without waiting for the transaction to complete, and the user is ensured that the data will be the same for the life of the transaction. The transaction is limited to read-only operations.

Description

The XDB Server permits you to set an isolation level to control the concurrency and consistency within a multi-user environment.

As described above, six isolation levels are supported. Both Repeatable-Read (RR) and Cursor Stability (CS) provide the following data isolation from other users:

  • An active transaction cannot modify or read any data which other active transactions have modified.
  • A transaction cannot modify a record currently being read by another transaction.

In addition, under Repeatable-Read (RR) no active transaction can modify a record which has been read by another active transaction specifying an RR level of isolation.

Cursor Stability (CS) is used if your application will generate or encounter many lock conflicts.

Exclusive Use (EU) locks are used for those procedures that require that the database be in a quiet state.

Lock Current (LC) locks are used for read-only operations or with autocommit set on. With autocommit on, this level of isolation is very useful for interactive sessions.

Example:

Some sample SET ISOLATION commands appear below:

SET ISOLATION EU
SET ISOLATION RR
SET ISOLATION CS
SET ISOLATION LC
SET ISOLATION DR
SET ISOLATION SR
Note:

If the isolation level is set to any setting other than Repeatable Read, for optimization the isolation level is changed to Dirty Read whenever an ORDER BY or GROUP BY is performed. In future versions of the XDB Server, the isolation level optimization will be configurable by the user.

Parent topic: SQL Statements


SET LOCATION TO

The SET LOCATION command logs a user onto a new location, creating an implied connection between the user's sessions and the specified location. The value of the CURRENT SERVER special register is also updated to reflect the new active location.
Restriction: This topic applies to Windows environments only.

Invocation

SET LOCATION is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET LOCATION can be dynamically prepared.

Authorization

Users must have the CONNECT privilege on the new location, as well as authority to access and/or modify objects stored at that location.

Syntax

SET LOCATION TO location-name

Parameters:

location-name Identifies a location accessible to the XDB Server.

Description

All XDB Server operations are performed and recorded under the currently set (or default) XDB Server location. The default value of the CURRENT SERVER special register is maintained in the XDB Server configuration file CONFIG.XDB. To create objects in a location other than the current location, use the SET LOCATION statement prior to entering other SQL statements.

Use of this command does not permanently change the user's current location, but only sets the location for the commands that immediately follow. The location remains set until the user either issues another SET LOCATION command or exits the utility where the SET LOCATION command was issued.

The SET LOCATION command differs in several respects from the CONNECT command. The CONNECT command can be used only in embedded SQL, and refers solely to locations recorded in the SYSIBM.SYSLOCATIONS catalog table (which includes remote locations). The SET LOCATION command, also refers to locations recorded in the SYSXDB.SYSLOCALS catalog table (which must be local).

XDB Link Locations

If you issue a SET LOCATION command to an XDB Link location, you cannot return to your XDB Server by issuing another SET LOCATION command (DB2 cannot read XDB Server catalog tables). If your application needs this type of functionality, use the CONNECT and CONNECT RESET commands from embedded SQL.

Example:

Take a typical scenario where the user is connected to LOC1 as the current default location, but the user needs to temporarily access another location (LOC2) in order to create a database object there. This user could access SQLWizard and issue the following command:

SET LOCATION TO loc2

All transactions for that user in the current (old) location are automatically committed and acquired locks released. Any SQL commands issued next (object creation or otherwise) operate on the new location specified above. When the user exits SQLWizard, the original default location (LOC1) returns.

Note:

The XDB Server 2.4x (and earlier) SET DATABASE command syntax can still be used to change the active location. However, a location name must be used for the argument.

Parent topic: SQL Statements


SET LOCATION

Use this command to prevent all users, except for those with SYSADM privileges, from logging on to a location on the XDB Server. This command does not affect users who are already using the location.
Restriction: This topic applies to Windows environments only.
Note:

The XDB Server does not allow you to take a location offline while it is in use. You can use the DISABLE LOGIN command to prevent new users from logging on to the server. If you need to take the location offline immediately, you can force active users off the location using the XDB Server Monitor.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSADM privileges

Syntax

SET LOCATION location-name {OFFLINE | ONLINE}

Parameters:

location-name Identifies the location that you want to place online or offline.
Parent topic: SQL Statements


SET LOG

The SET LOG command allows Database Administrators (with SYSADM authority or higher) to suspend logging system operation during an administrative session, and change the path where location log files are stored.
Restriction: This topic applies to Windows environments only.

Invocation

SET LOG is an executable XDB Server utility command that can be issued interactively or embedded in a host language. SET LOG can be dynamically prepared.

Authorization

Database Administrator, Install or SYSADM authority is required to turn the logging system on or off or to set the path where logging files are stored.

Syntax

SET LOG {ON | OFF}
SET LOG FOR location-name TO path-name WITH {MOVE | COPY}

SET LOG FOR location-name TO path-name
         ( ROLLFORWARD [OFF | ON] |
           LOG FILE SIZE n        |
           ROLLFORWARD {OFF | ON} LOG FILE SIZE n }
    WITH RESTART}

SET LOG FOR location-name
         ( ROLLFORWARD [OFF | ON] |
           LOG FILE SIZE n        |
           ROLLFORWARD {OFF | ON} LOG FILE SIZE n }
    WITH REPLACE}

Parameters:

location-name | Identifies an existing XDB Server location.
path-name | New path for the location log files.
n | An integer specifying the new maximum size (in kilobytes) of an individual log file..

Description

The XDB Server automatically maintains a series of log files for each XDB Server location for use in recovery. This new logging system is normally always defaulted to on. The SET LOG command accommodates the location structure of the XDB Server. Log files operate on a specified XDB Server location, recording all changes made to any objects in that location. The directory path where the log files are stored can be changed using the TO path-name option.

Log files record all changes made to the location since the last back up. In the event of a media failure, the log files can be replayed against a backup copy of the location tables, reconstructing the location data to the state immediately preceding the system failure.

The SET LOG command automatically commits the current transaction. See the Server Administration Guide for more information about backup and recovery options.

Interactive SQL

If you have SYSADM authority or higher and exclusive use of the location, you can temporarily turn the logging system off. When issued from SQLWizard, the SET LOG OFF command temporarily suspends logging for the location during the remainder of the current session. Turning logging off for a particular location is a temporary expedient for an exclusive user that does not want to incur the overhead of logging during administrative tasks.

Logging is turned off for the current session, only. Logging can be activated again in the current session by issuing a SET LOG ON command. Exiting the session toggles the status of location logging back to on (the default). The next session that accesses the location therefore has logging turned on. Setting the logging system on or off from an interactive SQL session does not affect the logging configuration settings in your XDBSRVCO.INI file.

ROLLFORWARD [ OFF | ON ]

If set to Off, this keyword deletes old, unneeded logs automatically. If set to On, this keyword keeps log files.

MOVE

This keyword copies (deleting the originals) all logs files from the named location to the path indicated by path-name, and also changes the current log path for the location to the new path named.

COPY

This keyword copies all logs files from the named location to the path indicated by path-name, and also changes the current log path for the location to the new path named.

RESTART

This keyword closes all log files on the current location log file path and opens new log files in the path indicated by path-name. The log path for the named location is also changed to the new path.

REPLACE

This keyword replaces all log files in the current log file path with new log files. The log path for the log file location stays the same.

Discontinued Commands

Because XDB Server Version 5.0 and above no longer support Forward or Backward logs, the old SET FORWARD LOG and SET BACKWARD LOG commands have been discontinued and replaced with the new SET LOG command. The FWDLOGON field in the SYSXDB.SYSLOCALS system table is no longer used.

Comments

If you are setting the value of LOG FILE SIZE or ROLLFORWARD, you cannot specify WITH COPY or WITH MOVE. If the TO path has not been specified, you must specify WITH REPLACE; in this case, the old logs will be removed and replaced with new logs. If the TO path is specified, you must specify WITH RESTART when moving the logs; in this case, the old logs will be left in the old path and the new log files will be created in the new path.

The XDBSTAT.LOGINFO table is available in all local locations. Querying this table gives the current settings for the log files in that particular location. The columns within the table are:

LOG_PATH | Contains the path to the log files for the location.
LOG_STATE | Shows the state of the logs as either CLEAN or DIRTY to indicate whether a transaction has modified the log files.
LOG_VERSION | Internal XDB logging version.
ROLLFORWARD_STATUS | Shows either OFF or ON, where OFF means that logs no longer required for transaction rollback will be purged at the next checkpoint, and ON means that logs will never be purged by the XDB Server.
LOG_FILE_SIZE | Maximum size in bytes of an individual log file. New log files will be created once this limit has been reached.

ExampleS:

The SET LOG command only requires the name of the location when changing the log file path using the MOVE, COPY or RESTART keywords. To turn OFF logging for the current location, issue the following command:

SET LOG OFF

To turn logging back ON for the current location, issue the following command:

SET LOG ON

You can also use the SET LOG command to change the directory where the location's log files will be stored. For example:

SET LOG FOR tutorial TO d:\recover WITH COPY
SET LOG FOR tutorial TO d:\log-path2 WITH MOVE
SET LOG FOR tutorial TO d:\log-path2 WITH RESTART
Parent topic: SQL Statements


SET SCHEMA

The SET SCHEMA statement assigns a value to the CURRENT SCHEMA special register. If the package is bound with the DYNAMICRULES BIND option, this statement does not affect the qualifier that is used for unqualified database object references.
Restriction: This topic applies to Windows environments only.
Restriction: This command is only supported syntactically by the XDB Server.

Invocation

This statement can be embedded in an application program or issued interactively. It is an executable statement that can be dynamically prepared.

Authorization

None required.

Syntax

Bold text indicates clauses or options that are supported only syntactically.

SET {SCHEMA | CURRENT SCHEMA | CURRENT_SCHEMA} [=]
     {schema-name |
      USER |
      host-variable |
      string-constant |
      DEFAULT}

Description

schema-name
Identifies a schema. No validation that the schema exists is made at the time the CURRENT SCHEMA is set. For example, if a schema name is misspelled, it could affect the way subsequent SQL operates.
USER
Specifies the value of the USER special register.
host-variable
Specifies a host variable that contains a schema name. The content is not folded to uppercase. The host variable must:
  • Be a CHAR, VARCHAR, GRAPHIC, or VARGRAPHIC variable. The actual length of the contents of the host-variable must not exceed the length of a schema name.
  • Not be set to null. If host-variable has an associated indicator variable, the value of that indicator variable must not indicate a null value.
  • Include a schema name that is left justified and conforms to the rules for forming an ordinary identifier or delimited identifier. If the identifier is delimited, it must not be empty or contain only blanks.
  • Be padded on the right with blanks if the host variable is fixed length.
  • Not contain USER or DEFAULT.
string-constant
Specifies a string constant that contains a schema name. The content is not folded to uppercase. The string constant must:
  • Have a length that does not exceed the maximum length of a schema name.
  • Include a schema name that is left justified and conforms to the rules for forming an ordinary identifier or delimited identifier. If the identifier is delimited, it must not be empty or contain only blanks.
  • Not contain USER or DEFAULT.
DEFAULT
Specifies that CURRENT SCHEMA is to be set to its initial value, as if it had never been explicitly set during the application process.
Note:
  • There is a difference between specifying a single keyword (such as USER or DEFAULT) as a single keyword or as a delimited identifier. To indicate that the current value of the USER special register should be used for setting the current schema, specify USER as a keyword. To indicate that the special register should be set to its default value, specify DEFAULT as a keyword. If USER or DEFAULT is specified as a delimited identifier instead (for example, "USER"), it is interpreted as a schema name of that value ("USER").
  • The SET SCHEMA statement is not a commitable operation. ROLLBACK has no effect on CURRENT SCHEMA.
  • The value of the CURRENT SCHEMA special register, as set by this statement, is used as the schema name in all dynamic SQL statements. The QUALIFIER bind option specifies the schema name for use as the qualifier for unqualified database object names in static SQL statements.
  • Setting the CURRENT SCHEMA special register does not affect any other special register. Therefore, the CURRENT SCHEMA is not be included in the SQL path that is used to resolve the schema name for unqualified references to function, procedures and user-defined types in dynamic SQL statements. To include the current schema value in the SQL path, whenever the SET SCHEMA statement is issued, also issue the SET PATH statement including the schema name from the SET SCHEMA statement.
Parent topic: SQL Statements


SET SORTSPACE

Use this command to dynamically reset the size of the sort space on the XDB Server. Active sorts are not affected by this command.
Restriction: This topic applies to Windows environments only.

The new sort space size remains in effect until you restart the server or execute another SET SORTSPACE command.

Note:

This command does not write the SORTSPACE value to the server's configuration file, so that when you restart the server, sort space is reset to its original size.

Invocation

This command can be embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSCTRL or SYSADM privileges

Syntax

SET SORTSPACE=Kbytes
SET SORTSPACE=1000

Parameters:

bytes Is the size of the sort space in kilo-bytes. See the Server Administration Guide for guidelines on setting an appropriate size.

For example, the following command sets the sort space to roughly one megabyte (1 million bytes):

SET SORTSPACE=1000
Parent topic: SQL Statements


SHUTDOWN

Use the SHUTDOWN command to close the XDB Server program at a specified time. You can also use a variant of this command to cancel a SHUTDOWN request that you have issued.
Restriction: This topic applies to Windows environments only.

Invocation

This command can embedded in a host language or executed interactively.

Authorization

Any of the following:

  • A super user
  • A user with SYSADM or SYSCTRL privileges

Syntax for SHUTDOWN AT

Use this command to shut down the server at a specific time or on a specific date. The syntax appears below:

SHUTDOWN AT {date-constant | time-constant | timestamp-constant}

For example:

SHUTDOWN AT 23:30:10
SHUTDOWN AT 10/09/1991
SHUTDOWN AT "1991-10-09-23.30.10.0"

Note that the timestamp value must be in double quotes. All users will be rolled back before shutdown.

Syntax for SHUTDOWN IN

Use this command to shut down the server in a specified length of time. The syntax appears below:

SHUTDOWN IN integer-constant duration
integer-constant | Represents any short or long integer.
duration | Represents a time duration descriptor.

For example:

SHUTDOWN IN 10 seconds
SHUTDOWN IN 2 hours
SHUTDOWN IN 6 months

All users will be rolled back before shutdown.

Syntax for SHUTDOWN ON LAST DISCONNECT

Use this command to shut down the server when the last user logs off the system. SHUTDOWN ON LAST DISCONNECT does not prevent new users from logging on to the server while the SHUTDOWN command is pending-- contrast this command with SHUTDOWN QUIESCE, below. If any new users log on to the server while the command is pending, the server will not shut down until after those users disconnect.

The syntax appears below:

SHUTDOWN ON LAST DISCONNECT

Syntax for SHUTDOWN QUIESCE

Use this command to disable new login requests and shut down the server when the last user logs off the system. SHUTDOWN QUIESCE prevents new users from logging on to the server while the SHUTDOWN command is pending-- contrast this command with SHUTDOWN ON LAST DISCONNECT, above.

The syntax appears below:

SHUTDOWN QUIESCE

Syntax for SHUTDOWN CANCEL

Use this command to cancel a SHUTDOWN command that is pending. The syntax appears below:

SHUTDOWN CANCEL
Parent topic: SQL Statements


SIGNAL SQLSTATE

The SIGNAL SQLSTATE statement is used to signal an error. It causes an error to be returned with the specified SQLSTATE and error description.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be used in the triggered action of a trigger.

Authorization

None required.

Syntax

SIGNAL SQLSTATE sqlstate-string-constant
    (diagnostic-string-constant)

sqlstate-string-constant

Represents an SQLSTATE. It must be a character string constant with exactly 5 characters that follow these rules for application-defined SQLSTATEs:

  • Each character must be from the set of digits ('0' through '9') or non-accented uppercase letters ('A' through 'Z').
  • The SQLSTATE class (first two characters) cannot be '00', '01' or '02' because these are not error classes.
  • If the SQLSTATE class (first two characters) starts with the character '0' through '6' or 'A' through 'H', the subclass (last three characters) must start with a character in the range 'I' through 'Z'.
  • If the SQLSTATE class (first two characters) starts with the character '7', '8', '9', or 'I' through 'Z', the subclass (last three characters) can be any of '0' through '9' or 'A' through 'Z'.

diagnostic-string-constant

A character string of up to 70 bytes that describes the error condition. If the string is longer than 70 bytes, it is truncated.

Example:

Consider a trigger for an order system that allows orders to be recorded in an ORDERS table (ORDERNO, CUSTNO, PARTNO, QUANTITY) only if there is sufficient stock in the PARTS tables. When there is insufficient stock for an order, SQLSTATE '75001' is returned along with an appropriate error description.

CREATE TRIGGER CK_AVAIL
    NO CASCADE BEFORE INSERT ON ORDERS
    REFERENCING NEW AS NEW_ORDER
    FOR EACH ROW MODE DB2SQL
    WHEN (NEW_ORDER.QUANTITY > (SELECT ON_HAND FROM PARTS
                                    WHERE NEW_ORDER.PARTNO = PARTS.PARTNO))
        BEGIN ATOMIC
            SIGNAL SQLSTATE '75001' ('Insufficient stock for order');
        END
Parent topic: SQL Statements


START DATABASE

The START DATABASE command allows users access to the contents of a named database.
Restriction: This topic applies to Windows environments only.

Invocation

START DATABASE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the START DATABASE command, users must possess either overall SYSADM, SYSCTRL for the location, DBADM authority on the database, or the STARTDB privilege for the database.

Syntax

START DATABASE (database-name) [ACCESS (RW | RO)]

Parameters:

database-name Identifies the database to be started.

Description

The START and STOP DATABASE commands are used primarily in conjunction with setting up and accessing Read Only Shared (ROSHARE) databases. A START DATABASE command must be issued after a STOP DATABASE command in order to make the tables in a ROSHARE database accessible to other locations.

The START DATABASE command is permanent until a STOP DATABASE command is executed, even if the user logs out or the Server is brought down. When a START DATABASE command is issued to start a database in RW mode, a value of "W" is placed in the IBMREQ column of the SYSIBM.SYSDATABASE table.

The ACCESS clause introduces either the default read-write (RW) option or the read-only (RO) option. ACCESS (RO) must be added to the START DATABASE command to start a ROSHARE database in read-only mode. Read-only mode allows users at other locations to directly read (select) data in the ROSHARE database.

ROSHARE database owners must issue a START DATABASE command (RW option default) before attempting to insert, update or delete records in the database.

Parent topic: SQL Statements


START PROCEDURE

The START PROCEDURE command checks the argument list for a stored procedure already defined to the SQL engine. If the stored procedure meta-data has been imported from another system, this command can be used to check that the argument list is compatible with XDB syntax rules.
Restriction: This topic applies to Windows environments only.

Invocation

START PROCEDURE is an executable command that can be issued interactively.

Authorization

To execute the START PROCEDURE command, users must possess one (or more) privileges listed in the SYSADM or SYSCTRL authority.

Syntax

START PROCEDURE (Proc-item-list)

Proc-item-list:

Proc-item [, Proc-item]

Proc-item:

{ Procedure-name | * }

Parameters:

Procedure-name The procedure name is any long identifier that names the procedure. The procedure name can be a partial name followed immediately by an asterisk. The partial name will identify a set of stored procedures to be checked. If an asterisk is used by itself, all procedures defined to the location will be checked. The SQL engine will stop when it encounters the first error.
Parent topic: SQL Statements


STOP DATABASE

The STOP DATABASE command restricts all access to the named database.
Restriction: This topic applies to Windows environments only.

Invocation

STOP DATABASE is an executable command that can be issued interactively, embedded in a host language, or dynamically prepared.

Authorization

To execute the STOP DATABASE command, users must possess either overall SYSADM or SYSCTRL authority for the location, DBADM authority on the database, or the STOPDB privilege for the database.

Syntax

STOP DATABASE (database-name)

Parameters:

database-name Identifies the database to be stopped.

Description

The STOP and START DATABASE commands are used primarily in conjunction with setting up and accessing Read Only Shared (ROSHARE) databases. A STOP DATABASE command must be issued on the "dummy" database before the owner of the physical (ROSHARE) database can create or alter tables. A STOP command must also be issued against the physical database and all related dummy databases before the ROSHARE database owner can drop tables.

The STOP DATABASE command can also be used by any database owner to restrict access (of any kind) to the database -- perhaps before a backup operation. Users must remember to issue a START command on the "stopped" database, when normal access is desired.

Parent topic: SQL Statements


TRUNCATE TABLE

The TRUNCATE TABLE command performs the same function as the DELETE command, except TRUNCATE TABLE removes all records from a table without recording the changes in the Forward and Backward Log files.
Restriction: This topic applies to Windows environments only.

Invocation

TRUNCATE TABLE is an executable command that can be issued interactively or embedded in a host language. TRUNCATE TABLE can be dynamically prepared.

Authorization

To execute the TRUNCATE TABLE command, users must possess either DBADM authority for the database containing the table, the DELETE privilege on the table, overall SYSADM authority for the location, or be the owner of the table to be truncated.

Syntax

TRUNCATE TABLE table-name

Parameters:

table-name Identifies the table to be truncated.

Description

The TRUNCATE TABLE command has the same functionality as DELETE FROM table-name, but is faster since deletes will not be logged and indexes are not incrementally maintained. The system will not be able to rollback the deleted records. This command is not allowed on a table containing a primary key, since it may be referenced by another table. Additionally, use of the TRUNCATE TABLE command alleviates the need to issue a COMPACT command on the table after records are deleted (to reclaim and reuse storage space).

Note:

The "records deleted" message produced after issuing the TRUNCATE TABLE command can indicate more records removed than originally present in the table. TRUNCATE TABLE does not stop to determine if a record was previously deleted from the table, it just truncates the table file -- counting all records equally, including those marked for deletion.

Parent topic: SQL Statements


UNLOCK TABLE

UNLOCK TABLE is used in multi-user versions to release table locks acquired using the LOCK TABLE command.
Restriction: This topic applies to Windows environments only.

Invocation

UNLOCK TABLE is an executable command that can be issued interactively or embedded in a host language. UNLOCK TABLE can be dynamically prepared.

Authorization

You must be the user who locked the table.

Syntax

UNLOCK TABLE table-name

Parameters:

table-name Identifies the table or view that was locked using a LOCK TABLE command.

Description

The UNLOCK TABLE command is available in both single and multi-user environments; however it is effective only in multi-user environments.

All table locks acquired by the user with the LOCK command can be held until COMMIT or ROLLBACK is issued. If a table is locked in Exclusive Use mode, no record level locks will be recorded by the system. Be sure to COMMIT or ROLLBACK before unlocking a table that has an Exclusive Use lock. Otherwise, uncommitted changes to the database may be lost.

Parent topic: SQL Statements


UPDATE (Searched)

The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.
Restriction: This topic applies to Windows environments only.

Invocation

UPDATE is an executable command that can be issued interactively or embedded in a host language. UPDATE can be dynamically prepared.

Authorization

Authority requirements for the UPDATE command depend on whether a table or view is being modified. If modifying a table, users need either UPDATE privileges on (or ownership of) the table, DBADM authority on the database containing the table, or overall SYSADM or SYSCTRL (some catalog tables only) authority for the location. If updating a view, users need UPDATE privileges on the view or SYSADM authority for the location.

The SELECT privilege is required on a searched update if the option for the SQL standard is set as follows:

  • For static SQL statements, if the SQLRULES(STD) bind option was specified
  • For dynamic SQL statements, if the CURRENT RULES special register is set to STD

If an expression that refers to a function is specified, the privilege set must include any authority that is necessary to execute the function.

Syntax

UPDATE {table-name | view-name}[correlation-name]
    SET assignment-clause
    [WHERE search-condition]
    [WITH {CS | RR | RS}]
    [QUERYNO integer]

assignment-clause:

{column-name = {expression | NULL | scalar-subselect}
| (column-name[,...] = {{expression | NULL} [,...] | row-select}}[,...]

Parameters:

table-name or view-name Identifies the table or view to be updated. If a view, the view must be updatable. The name must not identify:
  • An auxiliary table
  • A created temporary table or a view of a created temporary table
  • A catalog table with no updatable columns or a view of a catalog table with no updatable columns
  • A read-only view.
correlation-name Can be used within search-condition or a positioned UPDATE to designate the table or view.

When updating tables with subselects, the subselect cannot reference a location other than the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

UPDATE tutorial.tutorial.practice
    SET pay = pay + 5 WHERE e_no IN
        SELECT e_no FROM debloc.debbie.employee
            WHERE st = "MD";

Valid:

UPDATE tutorial.tutorial.practice
    SET pay = pay + 5
    WHERE e_no IN
        SELECT e_no FROM tutorial.debbie.employee
            WHERE st = "MD";

Description

The Searched UPDATE, command locates all records that satisfy the conditions specified in the WHERE clause (providing all index, integrity and check conditions are met and reverified). If the WHERE clause is omitted in a Searched UPDATE all records in the table will be updated. The WHERE search condition may be an expression or a nested query. Note that the UPDATE command cannot include an ORDER BY clause.

When performing a Positioned UPDATE, the WHERE CURRENT OF clause must specify the name of an open cursor. Only the current record (as defined in the opened cursor) will be updated, with the SET clause specifying the new values for the indicated columns.

Introduces a list of one or more column names and the values to be assigned to the columns.

column-name Identifies a column to be updated. column-name must identify a column of the specified table or view, but must not identify a ROWID column, an identity column that is defined as GENERATED ALWAYS, or a view column that is derived from a scalar function, constant, or expression. The column names must not be qualified, and the same column must not be specified more than once.

For a positioned update, allowable column names can be further restricted to those in a certain list. This list appears in the FOR UPDATE OF clause of the SELECT statement for the associated cursor. If the SELECT statement is dynamically prepared, the FOR UPDATE OF clause must always be present.

A view column derived from the same column as another column of the view can be updated, but both columns cannot be updated in the same UPDATE statement.

expression Indicates the new value of the column. Specifies an expression made up of constants, column-names, and arithmetic operators +, -, *, / (or the keyword NULL) that will become the new value of column-name. It must not include a column function.

A column-name in an expression must identify a column of the table or view. For each row that is updated, the value of the column in the expression is the value of the column in the row before the row is updated.

NULL | Specifies the null value as the new value of the column. Specify NULL only for nullable columns.
scalar-subselect Specifies a subselect that returns a single row with a single column. The column value is assigned to the corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.
The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect. For example, the following syntax is valid:
UPDATE TABLE T1
    SET COL1 = (SELECT COUNT(*)
        FROM TABLE2 T2
        WHERE T2.COL5 = T2.COL3)
    WHERE COL3 = 'ABC'
row-subselect Specifies a subselect that returns a single row. The number of columns in the row must match the number of column-names that are specified. The column values are assigned to each corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.

The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect.

search-condition | Preceded by the keyword WHERE, specifies a search condition for the optional WHERE clause.

Specifies an isolation level with which the statement is executed during a Searched UPDATE. You can override the isolation level of the statement using the WITH {RR | CS} clause. Because WITH UR only applies to read only operations, you cannot use it in an UPDATE statement. The WITH clause overrides the isolation level only for the statement in which it appears.

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Unless appropriate locks already exist, one or more exclusive locks are acquired by the execution of a successful UPDATE statement. Until a commit or rollback operation releases the locks, only the application process that performed the insert can access the updated row. If LOBs are not updated, application processes that are running with uncommitted read can also access the updated row. The locks can also prevent other application processes from performing operations on the table. However, application processes that are running with uncommitted read can access locked pages and rows.

When a view is updated, the changes are reflected in the underlying database table. For a view to be updatable, the query used to define the view must satisfy the following criteria:

  • The query cannot contain DISTINCT.
  • The SELECT clause can contain only column names (no expressions or functions).
  • The FROM clause can contain only one table name.
  • No GROUP BY or HAVING clauses are permitted.

Examples:

The following are examples of Searched UPDATE commands. The first example changes the value of the COLOR column for part number P2 to BROWN, and then adds 5 to its WEIGHT column value.

UPDATE part
    SET color = "BROWN", weight = weight + 5
    WHERE pno = "P2"

The next command doubles the STATUS column value of all London suppliers:

UPDATE supplier
    SET status = status * 2
    WHERE city = "LONDON"

The WHERE clause may also include a nested query, as in the following example, which updates the PARTSUPP table records containing the part numbers of any part made in Paris:

UPDATE partsupp
    SET qty = qty-100
    WHERE pno IN
        SELECT pno
            FROM part
            WHERE city = "PARIS"

While an update command can only update one table, its WHERE clause may consist of a nested query that is a join of several tables. For example:

UPDATE supplier
    SET status = 30
    WHERE sno IN
        SELECT sno
            FROM partsupp, part
            WHERE partsupp.pno = part.pno
              AND qty > 50
Parent topic: SQL Statements
Related reference
UPDATE (Positioned)


UPDATE (Positioned)

The UPDATE command modifies the values of specified columns in rows of a table or view, if the view is updatable. Modifying a row of a view also modifies the underlying base table of the view. The UPDATE command statement has two configurations, depending on whether a searched update or positioned update is performed. A searched update modifies zero or more rows of a table. These updated rows can be optionally selected with a search condition. A positioned update modifies only one row -- derived as the current position of a previously declared and opened cursor. The table or view being updated can exist at the current location or at any other location accessible from the XDB Server.
Restriction: This topic applies to Windows environments only.

Invocation

UPDATE is an executable command that can be issued interactively or embedded in a host language. UPDATE can be dynamically prepared.

Authorization

Authority requirements for the UPDATE command depend on whether a table or view is being modified. If modifying a table, users need UPDATE privileges on (or ownership of) the table, DBADM authority on the database containing the table, or overall SYSADM or SYSCTRL (some catalog tables only) authority for the location. If updating a view, users need UPDATE privileges on the view or SYSADM authority for the location.

Syntax

The Positioned UPDATE command can only be used with embedded SQL. In DB2 mode the cursor must have been defined with a FOR UPDATE OF clause (or the program precompiled with the NOFOR directive).

The syntax for the Positioned UPDATE appears below:

UPDATE {table-name | view-name} [correlation-name]
    SET assignment-clause WHERE CURRENT OF cursor-name
    [FOR ROW {host-variable | integer-constant} OF ROWSET]

assignment-clause:

{column-name = {expression | NULL | scalar-subselect}
| (column-name[,...] = {{expression | NULL} [,...] | row-select}}[,...]

Parameters:

table-name or view-name Identifies the table or view to be updated. If a view, the view must be updatable. The name must not identify:
  • An auxiliary table
  • A created temporary table or a view of a created temporary table
  • A catalog table with no updatable columns or a view of a catalog table with no updatable columns
  • A read-only view.
correlation-name Can be used within search-condition or a positioned UPDATE to designate the table or view.

Explicit Update to Null (DB2 Mode)

In DB2 mode, you cannot perform an explicit update to null on a table column defined as NOT NULL WITH DEFAULT. For example:

UPDATE empl SET perf = NULL

returns an error message if the column named perf was originally declared as NOT NULL WITH DEFAULT.

Description

The Searched UPDATE, command locates all records that satisfy the conditions specified in the WHERE clause (providing all index, integrity and check conditions are met and reverified). If the WHERE clause is omitted in a Searched UPDATE all records in the table will be updated. The WHERE search condition may be an expression or a nested query. Note that the UPDATE command cannot include an ORDER BY clause.

When performing a Positioned UPDATE, the WHERE CURRENT OF clause must specify the name of an open cursor. Only the current record (as defined in the opened cursor) will be updated, with the SET clause specifying the new values for the indicated columns.

SET Clause

Introduces a list of one or more column names and the values to be assigned to the columns.

column-name Identifies a column to be updated. column-name must identify a column of the specified table or view, but must not identify a ROWID column, an identity column that is defined as GENERATED ALWAYS, or a view column that is derived from a scalar function, constant, or expression. The column names must not be qualified, and the same column must not be specified more than once.

For a positioned update, allowable column names can be further restricted to those in a certain list. This list appears in the FOR UPDATE OF clause of the SELECT statement for the associated cursor. If the SELECT statement is dynamically prepared, the FOR UPDATE OF clause must always be present.

A view column derived from the same column as another column of the view can be updated, but both columns cannot be updated in the same UPDATE statement.

expression Indicates the new value of the column. Specifies an expression made up of constants, column-names, and arithmetic operators +, -, *, / (or the keyword NULL) that will become the new value of column-name. It must not include a column function.

A column-name in an expression must identify a column of the table or view. For each row that is updated, the value of the column in the expression is the value of the column in the row before the row is updated.

NULL | Specifies the null value as the new value of the column. Specify NULL only for nullable columns.
scalar-subselect Specifies a subselect that returns a single row with a single column. The column value is assigned to the corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.

The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect. For example, the following syntax is valid:

UPDATE TABLE T1
    SET COL1 = (SELECT COUNT(*)
        FROM TABLE2 T2
        WHERE T2.COL5 = T2.COL3)
    WHERE COL3 = 'ABC'
row-subselect Specifies a subselect that returns a single row. The number of columns in the row must match the number of column-names that are specified. The column values are assigned to each corresponding column-name. If the subselect returns no rows, the null value is assigned; an error occurs if the column to be updated is not nullable. An error also occurs if there is more than one row in the result.

The subselect must not contain a GROUP BY or HAVING clause, and the subselect (or subquery within the subselect) cannot use the table or view being updated as its target. The subselect, however, can refer to columns of the table or view to be updated. The value of such a column in the subselect is the value of the column in the row before the row is updated. Correlated references to these columns are allowed only in a searched UPDATE and only in the search condition of the subselect.

cursor-name | Preceded by the keywords WHERE CURRENT OF, identifies a previously declared and opened cursor.

Specifies the number to be used for this SQL statement in EXPLAIN output and trace records. The number is used for the QUERYNO columns of the plan tables for the rows that contain information about this SQL statement.

If the clause is omitted, the number associated with the SQL statement is the statement number assigned during precompilation. Thus, if the application program is changed and then precompiled, that statement number might change.

Using the QUERYNO clause to assign unique numbers to the SQL statements in a program is helpful for simplifying the use of optimization hints for access path selection, if hints are used.

Unless appropriate locks already exist, one or more exclusive locks are acquired by the execution of a successful UPDATE statement. Until a commit or rollback operation releases the locks, only the application process that performed the insert can access the updated row. If LOBs are not updated, application processes that are running with uncommitted read can also access the updated row. The locks can also prevent other application processes from performing operations on the table. However, application processes that are running with uncommitted read can access locked pages and rows.

When a view is updated, the changes are reflected in the underlying database table. For a view to be updatable, the query used to define the view must satisfy the following criteria:

  • The query cannot contain DISTINCT.
  • The SELECT clause can contain only column names (no expressions or functions).
  • The FROM clause can contain only one table name.
  • No GROUP BY or HAVING clauses are permitted.

Example:

The following Positioned UPDATE statement changes the current PART table record (pointed to by the cursor PARTCUR) by setting the COLOR column to "BROWN" and the WEIGHT column to 25.

    MOVE "BROWN" TO NEWCOLOR
    MOVE 25 TO NEWWGT
    EXEC SQL
        UPDATE part
            SET color = :NEWCOLOR, weight = :NEWWGT
            WHERE CURRENT OF partcur
    END-EXEC

The following Positioned UPDATE command changes the status of the supplier record (pointed to by the cursor supcur) to a value of ten:

newstatus = 10;
    EXEC SQL
        UPDATE supplier
            SET status = :newstatus
            WHERE CURRENT OF supcur;
Parent topic: SQL Statements
Related reference
UPDATE (Searched)


VALUES

The VALUES statement provides a method for invoking a user-defined function from a trigger. Transition variables and transition tables can be passed to the user-defined function.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be used in the triggered action of a trigger.

Authorization

EXECUTE authority is needed on any user-defined function that is referenced in the VALUES clause.

Syntax

VALUES {expression | (expression[,...])}

Description

Specifies one or more expressions. If more than one expression is specified, the expressions must be enclosed within parentheses.

The expressions are evaluated, but the resulting values are discarded and are not assigned to any output variables.

If a user-defined function is specified as part of an expression, the user-defined function is invoked. If a negative SQLCODE is returned when the function is invoked, DB2 stops executing the trigger and rolls back any triggered actions that were performed.

Example:

Create an after trigger EMPISRT1 that invokes user-defined function NEWEMP when the trigger is activated. An insert operation on table EMP activates the trigger. Pass transition variables for the new employee number, last name, and first name to the user-defined function.

CREATE TRIGGER EMPISRT1
    AFTER INSERT ON EMP
    REFERENCING NEW AS N
    FOR EACH ROW
    MODE DB2SQL
    BEGIN ATOMIC
        VALUES(NEWEMP(N.EMPNO, N.LASTNAME, N.FIRSTNAME));
    END
Parent topic: SQL Statements


VALUES INTO

The VALUES INTO statement assigns one or more values to host variables.
Restriction: This topic applies to Windows environments only.

Invocation

This statement can only be embedded in an application program. It is an executable statement that cannot be dynamically prepared.

Authorization

EXECUTE authority is needed on any user-defined function that is referenced in the VALUES statement.

Syntax

VALUES {{expression | NULL} | {expression | NULL}[,...]} INTO host-variable[,...]

Description

VALUES

Introduces one or more values. If more than one value is specified, the list of values must be enclosed within parentheses.

expression | Must not include a column name.
NULL | The null value. NULL can only be specified for host variables that have an associated indicator variable.

INTO

Introduces one or more host variables. The values that are specified in the VALUES clause are assigned to these host variables. The first value specified is assigned to the first host variable, the second value to the second host variable, and so on.

host-variable Identifies a variable that is described in the program according to the rules for declaring host variables.

Example:

Assign the value of the CURRENT PATH special register to host variable HV1.

EXEC SQL VALUES(CURRENT PATH)
    INTO :HV1;
Parent topic: SQL Statements


WHENEVER

The WHENEVER statement (embedded SQL only) has three different forms, each of which changes the execution of a host language program according to the occurrence of specified exception conditions.
Restriction: This topic applies to Windows environments only.

Invocation

WHENEVER is not an executable command. It can only be embedded in a host language. WHENEVER cannot be dynamically prepared.

Authorization

No special type of authorization is required.

Syntax

WHENEVER {NOT FOUND | SQLERROR | SQLWARNING}
    {CONTINUE | GO TO host-label}

Parameters:

host-label Preceded by the keywords GO TO (or GOTO), specifies a host language statement to which program execution is transferred.

Description

The NOT FOUND, SQLERROR or SQLWARNING clauses are used to look for a certain types of exception conditions resulting from the execution of an SQL statement. The NOT FOUND construction looks for a returned SQL code of +100, while SQLERROR looks for an SQL statement that has returned a negative error code. SQLWARNING looks for a return code value occurring in SQLWARN1 through SQLWARN7 of the SQLCA to determine the type of warning. For more information, see XDB Server SQL Communications Area (SQLCA).

Each occurrence of a WHENEVER statement applies to all SQL statements that follow in the source listing, until the next WHENEVER statement (of that type) is encountered. In a COBOL application, if a single WHENEVER statement is placed at the beginning of the PROCEDURE DIVISION, that statement applies to all SQL statements executed by the application program. Once the WHENEVER statement determines that an error condition has occurred, the CONTINUE option transfers program control to the next sequential statement, while the GO TO clause transfers program control to the application paragraph named in host-label.

Example:

The host-label parameter is a valid section name or unqualified paragraph name.

This assumes that error-proc is a named procedure in your COBOL program.

EXEC SQL
    WHENEVER SQLERROR
        GO TO error-proc
END-EXEC
Parent topic: SQL Statements


Clauses

Restriction: This topic applies to Windows environments only.
  • SELECT Clause Syntax and Description
  • FROM Clause Syntax and Description
  • WHERE Clause Syntax and Description
Parent topic: SQL Reference


SELECT Clause Syntax and Description (SQL)

SELECT Clause Syntax and Description

Restriction: This topic applies to Windows environments only.

Each SQL query statement must contain both a SELECT and a FROM clause. The combination of these two clauses determine the table columns that are searched by the query. The WHERE clause and other advanced clauses further limit data retrieval to specific table rows. The sample queries presented throughout this reference utilize the training tables contained in the TUTORIAL location. See FROM Clause, WHERE Clause, Other Clauses, and XDB Server Tutorial Location for more information.

The SELECT clause specifies the columns from which data values are to be retrieved by the query. Data retrieval is limited to the columns specified. When selecting from two or more tables having duplicate column names, it may be necessary to qualify column names with table or view names. Prefixing column names with a table or view name ensures that the query retrieves the correct column (in the correct table).

Syntax

The SELECT clause format appears below:

SELECT [ALL | DISTINCT] {* | projection-list[,...]}

projection-list:

 {
        expression [[AS] name] | (CASE-statement) AS name |
        {table-name | view-name | correlation-name}.*
   }

CASE-statement:

 (CASE WHEN condition THEN expression [WHEN condition THEN expression] [...]
        ELSE expression END) AS name

Parameters:

ALL

Option (default) which selects all rows that satisfy the WHERE condition. Duplicates are not eliminated.

DISTINCT

Option that eliminates duplicate rows from the result.

* Represents a list of names that identify the columns of the final result table. The first name in the list identifies the first column, the second name identifies the second column, and so on. To retrieve all columns in a table or view, enter a single asterisk in place of projection-list.
expression | A list of one to 750 column names (separated by commas) and possibly including constants, functions, host-variables, special registers, labeled durations and various operators. If duplicate column names from different tables must appear in the list, prefix the column name in the SELECT clause with that column's table name to resolve any ambiguity. To force the use of an index on a particular column during a query, append an asterisk enclosed in parentheses (*) to the name of the indexed column. See the XDB Server Administration Guide for guidelines on using indexes with queries.

AS

The XDB Server includes support for the keyword AS, which can be used to name result columns in a SELECT clause. This is particularly useful for a column derived from an expression or from a function applied to a column value. You can use the name in a GROUP BY clause.

The name of a result column of a subselect is determined as follows:

  • If the AS clause is specified, the name of the result column is the name specified on the AS clause.
  • If the AS clause is not specified and the result column is derived from a column name, the result column name is the unqualified name of that column.
  • All other result columns are unnamed.
CASE-statement XDB Mode only. Allows an item to be conditionally specified in the projection list. For example the CASE statement,
SELECT (CASE
  WHEN A=2
    THEN FIRST_NAME
  ELSE
    LAST_NAME
  END)

inserts the column name FIRST_NAME or LAST_NAME into the projection list, depending on the value of the variable A.

condition | An expression that evaluates to TRUE or FALSE,
expression | (In the CASE statement.) An expression specifying a projection list item. (See expression description above). When condition is TRUE, expression is resolved,
name | A name you assign to the column produced by the CASE statement. (When you include the CASE statement, you must include the AS clause.)
name.* | When selecting columns from one or more tables or views, you can select all columns from a particular table by qualifying the special asterisk character with the table name. name.* represents a list of names that identify the columns of name. name can be a table-name, view-name, or correlation-name, and must designate a table or view named in the FROM clause. The first name in the list identifies the first column of the table or view, the second name in the list identifies the second column of the table or view, and so on.
  • Select Clause Examples
  • SELECT ALL vs. DISTINCT
  • Retrieving All Columns with the SELECT Clause
  • SELECT Expressions
Parent topic: Clauses


Select Clause Examples

Restriction: This topic applies to Windows environments only.

In the sample query statement below, the prefix "part" in front of the CITY column (separated with a period) tells the system to use the CITY column from the PART table, rather than from the SUPPLIER table.

SELECT pno, part.city, qty, sname
FROM partsupp, supplier, part
WHERE part.pno = partsupp.pno
  AND partsupp.sno = supplier.sno

If columns are not prefixed with the name of the owner table, the XDB Server queries the first column with that name that the system encounters.

The next sample query adds a five percent surcharge on all outstanding customer balances in the state of Maryland, and then lists the new adjusted balance for each affected company.

SELECT company,
  balance + balance * .05 AS New_Balance
FROM customer
WHERE state = MD

The AS clause expression calculates the adjusted balance, which it displays under the heading New_Balance.

Parent topic: SELECT Clause Syntax and Description


SELECT ALL vs. DISTINCT

Restriction: This topic applies to Windows environments only.

The SELECT clause of a query statement can include two optional keywords -- ALL or DISTINCT, followed by the projection-list. If the ALL keyword is specified, duplicate rows are not removed from the query result. If the DISTINCT option is specified, all duplicate rows of data values are excluded from the query result. If neither ALL nor DISTINCT are specified, the SELECT clause defaults to ALL.

For example, the query below selects all of the supplier numbers SNO from the PARTSUPP table, including duplicate numbers.

SELECT ALL sno
FROM partsupp

The query results are displayed below:

sno
S1
S1
S2
S3
S1
S1
S1
S1
S2
S4
S4

If we replaced the ALL keyword with DISTINCT, the query retrieves the following set of records:

sno
S1
S2
S3
S4

The DISTINCT keyword, along with the aggregate function COUNT, can be used to tally the distinct records satisfying a WHERE clause condition. See Functions and WHERE Clause for more information. The DISTINCT option keyword may only be used once in a SELECT clause.

Parent topic: SELECT Clause Syntax and Description


Retrieving All Columns with the SELECT Clause

Restriction: This topic applies to Windows environments only.

When an * character is used in the projection-list portion of a SELECT statement, the system retrieves all columns from the tables appearing in the FROM clause. For example, suppose we need to display all columns in the SUPPLIER table. The SELECT statement below would accomplish this objective:

SELECT *
FROM supplier

The result for this query is shown in the table below:

sno | sname | status | city
S1 | SMITH | 20 | LONDON
S2 | JONES | 10 | PARIS
S3 | BLAKE | 30 | PARIS
S4 | CLARK | 20 | LONDON
S5 | ADAMS | 30 | ATHENS

The last query above returns the same result as the longer query statement shown below:

SELECT sno, sname, status, city
FROM supplier

When selecting columns from one or more tables or views, users may select all columns from a particular table by qualifying the special asterisk character with the table name. The sample query statement below demonstrates this approach:

SELECT supplier.*, pno, qty
FROM supplier, partsupp
WHERE supplier.sno = partsupp.sno

The result of the query statement above is the same as the statement below:

SELECT sno, sname, status, city, pno, qty
FROM supplier, partsupp
WHERE supplier.sno = partsupp.sno
Parent topic: SELECT Clause Syntax and Description


SELECT Expressions (SQL)

SELECT Expressions

Restriction: This topic applies to Windows environments only.

The projection-list of a SELECT clause may contain column names, constants and/or expressions. It is sometimes advantageous to use an expression that incorporates data values from one or more columns. Any legal arithmetic expression involving column values, numeric or string constants, functions, and arithmetic operators is permitted in an expression. See Functions In SELECT Clauses. Parentheses may be used as necessary to define evaluation order.

Column names generally match those specified in the SELECT clause. In the case of expressions or column names made up of multiple words (column names over 30 characters long), the XDB Server substitutes the special name Columnn where the second n is the column number -- counting from the left side of the result display.

Numeric constants and string constants can be "selected" just like column names. String constants can be enclosed in single or double quotes. For instance, the query below uses a string constant in the SELECT statement:

SELECT "Supplier", sname, "is located in", city
FROM supplier

The previous query produces the following results display:

Supplier | sname | Column3 | city
Supplier | SMITH | is located in | LONDON
Supplier | JONES | is located in | PARIS
Supplier | BLAKE | is located in | PARIS
Supplier | CLARK | is located in | LONDON
Supplier | ADAMS | is located in | ATHENS

The query below uses an arithmetic expression in the SELECT clause to display shipping costs for each part received from London:

SELECT pno, weight * 1.15
FROM part
WHERE city = "LONDON"

The column rename feature can assign a name to a new column of output computed from an arithmetic expression. For example, the results of the following query would appear under two separate columns named PNO and shipcost:

SELECT pno, shipcost = weight * 1.15
FROM part
WHERE city = "LONDON"
Note:

A NULL value generates a NULL result when used in arithmetic expressions other than aggregate functions. Consider the expression x * y, where the "x" value is NULL. For any "y" value, the XDB Server evaluates this entire expression as NULL. In contrast, NULL values are ignored when determining the results of aggregate functions. For example, consider the query:

SELECT SUM(qty)
FROM partsupp

If the ith record data value in the qty column contains a NULL value, the SUM(qty) function is calculated as if the ith record does not exist.

More:

  • CASE Expressions
  • Concatenation
  • Functions In SELECT Clauses
  • Examples
  • CASE Expressions
  • Concatenation
  • Functions In SELECT Clauses
  • Examples
Parent topic: SELECT Clause Syntax and Description


CASE Expressions

Restriction: This topic applies to Windows environments only.

Use CASE expressions to create conditional logic.

Syntax

CASE {searched-when-clause | simple-when-clause}
  [ELSE NULL | ELSE result-expression]
  END
searched-when-clause:
WHEN search-condition THEN
{result-expression | NULL} ...
simple-when-clause:
expression WHEN expression THEN
  {result-expression | NULL} ...

where:

searched-when-clause | Specifies a search condition that is applied to each row or group of table data presented for evaluation and the result when that condition is true.
simple-when-clause | Specifies that the value of the expression prior to the first WHEN keyword is tested for equality with the value of each expression that follows a WHEN keyword. Also, specifies the result for each WHEN keyword when the expressions are equal.
result-expression | Specifies the result of a case-expression if no case is true. Also, specifies the result of a searched-when-clause or a simple-when-clause when true. There must be at least one result-expression in the CASE expression.
search-condition | Specifies a condition that is true, false, or unknown about a row or group of rows. The search-condition in a searched-when-clause cannot contain a subselect.

Example

Assume that in the a table named EMPLOYEE, the first character of a department number represents the division in the organization. Use a CASE expression to list the full name of the division to which each employee belongs:

SELECT EMPNO, LASTNAME
  CASE SUBSTR(WORKDEPT,1,1)
  WHEN 'A' THEN 'Administration'
  WHEN 'B' THEN 'Human Resources'
  WHEN 'C' THEN 'Design'
  WHEN 'D' THEN 'Operations'
  END
FROM EMPLOYEE
Parent topic: SELECT Expressions


Concatenation

Restriction: This topic applies to Windows environments only.

The special symbol || (also called the concatenation operator) is used to attach string constants and data values appearing in query results. The output rows have the same length as the sum of the individual string constants and data values attached. If any component of the concatenation expression is null (such as a data value from a column), the entire expression is null. The following query uses the concatenation operator to displays last names, followed by a comma and space, and then first names.

SELECT lname||", "||fname
FROM employee
Parent topic: SELECT Expressions


Functions In SELECT Clauses

Restriction: This topic applies to Windows environments only.

The XDB Server provides both ANSI standard and special XDB Server functions that can be used in SELECT clause expressions. Functions (mathematical, string, and date) supported by the XDB Server are listed in Functions.

For example, the XCONCAT function (similar to the || operator) can be nested within itself to concatenate two or more string and column values, as shown by the following query:

SELECT XCONCAT(XCONCAT(color, " "), pname)
FROM part

This query produces the following results:

column1
RED NUT
GREEN BOLT
BLUE CAM
RED SCREW
BLUE CAM
RED COG

When a SELECT clause combines aggregate functions (sum, count, avg, etc.) with column names, the query statement must include a GROUP BY clause. (See Other Clauses for more information on the GROUP BY clause.) Additionally, the column-list of the GROUP BY clause must include all column names that appear in the SELECT clause.

Parent topic: SELECT Expressions


Examples

Restriction: This topic applies to Windows environments only.

The query statement below would generate an error message because there is no GROUP BY clause that instructs the XDB Server to group records on the selected SNO column -- for purposes of calculating average quantities:

SELECT sno, AVG(qty)
FROM partsupp

The next query of the PARTSUPP table is corrected to include the GROUP BY clause:

SELECT sno, AVG(qty)
FROM partsupp
GROUP BY sno

The query results follow:

sno | avg(qty)
S1 | 216.67
S2 | 350.00
S3 | 200.00
S4 | 300.00

If there is no GROUP BY clause, only aggregate functions may be selected in queries that include a HAVING clause.

Note: The GROUP BY and HAVING clauses are covered in Other Clauses. Aggregate functions are covered in Functions.
Parent topic: SELECT Expressions


FROM Clause Syntax and Description

Restriction: This topic applies to Windows environments only.

The FROM clause (like the SELECT clause) must appear in every SQL query statement. See SELECT Clausefor more information. While the SELECT clause specifies from which columns data values are retrieved during query execution, the FROM clause specifies the table(s) in which these data columns are located.

The FROM clause names one or more tables (or views) from which data values are retrieved by the query. Data retrieval is limited to the tables (or views) specified. The XDB Server also allows you to explicitly specify right, left, and full outer joins, and use subselects or nested table expressions. The FROM clause either names a single table or view or produces an intermediate result table that is the result of a subselect or an inner or outer join operation.

The FROM clause is required in a SELECT statement to identify the tables and/or views that are being queried. When more than one table or view is specified in the FROM clause, each of these object names can also be assigned a correlation name. In XDB mode, the FROM clause is extended to allow explicit expression of inner and outer join operations and a subselect or nested table expression.

Syntax

The FROM clause format appears below:

FROM table-ref [,...]

table-ref:

{
  [{table-name | view-name} [[AS] correlation-name]
  | [(subselect) [AS] correlation-name]
  | [joined-table]}
}

joined-table:

table-ref [INNER] | [{LEFT | RIGHT | FULL} [OUTER]]
  JOIN table-ref join-condition
| [(joined-table)]

join-condition:

ON join-expression { = | <> | > | < | >= | <= }
  join-expression AND [...]

join-expression:

column-name [{VALUE | COALESCE} (column-name [,...])]

Parameters:

table-name or view-name | A list of one or more table or view names (separated by commas), from which data values are to be retrieved. Must identify a table or view described in the system catalog of the database subsystem identified by the implicitly or explicitly specified location name.
correlation-name | Can be specified for a table reference, either immediately following the table reference or after the AS keyword which follows the table reference. A correlation name must be specified for a nested table expression that is enclosed in parentheses.
joined-table | Specifies an intermediate result table that is the result of either an inner equi-join or an outer join. The table is derived by applying one of the join-operators; INNER, RIGHT OUTER, LEFT OUTER, or FULL OUTER, to its operands. If a join-operator is not specified, INNER is implicit. The order in which a LEFT OUTER or RIGHT OUTER JOIN is performed can affect the result. A joined-table can be used in any context in which any form of the SELECT statement is used. Both a view and a cursor is read-only if its SELECT statement includes a joined-table.
joined-condition | Defines a search condition in which predicates can be combined only with the keyword AND, and each predicate has the form 'expression operator expression'. The '=' operator is the only operator allowed for a FULL OUTER JOIN or a FULL JOIN.
join-expression | Must include a column name. Only columns and the VALUE and COALESCE functions are allowed in the expression. VALUE and COALESCE are allowed only when the join operator is FULL JOIN or FULL OUTER JOIN. One expression of the predicate must reference only columns of one of the operand tables of the associated join operator, and the other expression of the predicate must reference only columns of the other operand table. Before this rule is applied, column references are resolved using the rules for resolution of column name qualifiers.
  • Correlation Names
  • INNER JOIN
  • FULL [OUTER] JOIN
  • LEFT [OUTER] JOIN
  • RIGHT [OUTER] JOIN
  • VALUE
  • Nested Table Expressions
  • Querying Views
Parent topic: Clauses


Correlation Names

Restriction: This topic applies to Windows environments only.

Correlation names are used in place of the actual table or view name when qualifying columns within a query statement. The correlation name appears immediately after the corresponding table or view name in the FROM clause (separated by a single space). Correlation names must satisfy the same naming conventions as table names, and must be unique among all table, view and other correlation names within a query. The correlation name qualifies columns that appear in either SELECT or WHERE clauses. See WHERE Clause for more information.

The following query shows a correlation name of "p" being assigned to the PART table, and a correlation name of "ps" being assigned to the PARTSUPP table.

SELECT pname, qty
  FROM part p, partsupp ps
  WHERE p.pno = ps.pno

More information on joins and correlation names appears in WHERE Clause and Other Clauses.

  • Using AS
Parent topic: FROM Clause Syntax and Description


Using AS

Restriction: This topic applies to Windows environments only.

The AS keyword is available before correlation names, and after the following:

  • Nested table expressions
  • Table names
  • View names
  • Aliases
  • Synonyms
Parent topic: Correlation Names


INNER JOIN

Restriction: This topic applies to Windows environments only.

When a FROM clause contains two or more tables (or views), that FROM clause is said to join the data values appearing in the two or more tables listed. Up to ten table or view names may be listed in a FROM clause, with each object name separated with a comma. The familiar operation of joining two or more tables, as carried out in XDB Server Versions 5.0 and earlier, can now be called an inner join. This distinction is made in order to distinguish inner joins syntactically from left, right, and full (outer) joins. For example, the inner join queries below (on the PART and PARTSUPP tables) produce the same results:

SELECT part.pno, pname, qty
  FROM part, partsupp
  WHERE part.pno = partsupp.pno

or

SELECT part.pno, pname, qty
  FROM part INNER JOIN partsupp
  ON part.pno = partsupp.pno

In both of these queries the PART and PARTSUPP tables are joined on their commonly named PNO columns. Notice that the second query explicitly defines this query as an inner join, not an outer join. You can use the key words INNER JOIN in the from clause instead of the traditional comma (the comma still works for an inner join). To be consistent with this syntax, you should also use an ON clause when you explicitly state a join condition (however, the WHERE clause will work).

The results of these inner joins cannot contain any unmatched rows from either table. For example, if the PART table contained a record for a RIVET with a PNO column value of P8, this RIVET information would not be retrieved in either of the previous queries, since there is no matching record in the partsupp table with a PNO column value of P8.

Parent topic: FROM Clause Syntax and Description


FULL [OUTER] JOIN

Restriction: This topic applies to Windows environments only.

In contrast to inner joins, outer joins can contain some or all nonmatching rows from both joined tables. Missing values in a row of the result table are filled with nulls. The following sample query creates a full outer join between the PART and PARTSUPP tables:

SELECT part.pno, pname, qty
  FROM part FULL OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The results of this full outer join (the keyword OUTER is optional) contain all matched as well as unmatched rows from either table. For example, if the PART table contained a nonmatching record for a RIVET with a PNO column value of P8, this RIVET information would be part of the result, even though there is no matching record in the PARTSUPP table (with a PNO column value of P8). Likewise, if the PARTSUPP table contained a nonmatching record with a PNO column value of P7, this record information would also appear in the result even though there is no matching P7 PNO column value in the PART table.

Using the FULL [OUTER] JOIN syntax includes nonmatched rows from both joined tables. Full outer joins can only use the equal (=) comparison operator in the join condition (left and right outer joins can use all the comparison operators).

Parent topic: FROM Clause Syntax and Description


LEFT [OUTER] JOIN

Restriction: This topic applies to Windows environments only.

Left outer joins (the keyword OUTER is again optional) include nonmatching rows only from the table named before the LEFT [OUTER] JOIN clause. Missing values in a row are filled with nulls. The following sample query creates a left outer join between the PART and PARTSUPP tables:

SELECT part.pno, pname, qty
  FROM part LEFT OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The results of this query contains all matched rows, plus unmatched rows from the PART table (or, the table on the left hand side of the LEFT OUTER JOIN clause). For example, if the PART table contained a nonmatching record for a WASHER with a PNO column value of P9, this WASHER information would be part of the result, even though there is no matching record in the PARTSUPP table with a PNO column value of P9. If, however, the PARTSUPP table also contained an unmatched record, this record information would not appear in the result rows. Using the LEFT [OUTER] JOIN syntax includes nonmatched rows from only the joined table on the left of the LEFT OUTER JOIN clause.

Parent topic: FROM Clause Syntax and Description


RIGHT [OUTER] JOIN

Restriction: This topic applies to Windows environments only.

Right outer joins (the keyword OUTER is optional) include nonmatching rows only from the table named after the RIGHT [OUTER] JOIN clause. Missing values in a row are filled with nulls. The following sample query creates a right outer join between the PART and PARTSUPP tables:

SELECT part.pno, pname, qty
  FROM part RIGHT OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The results of this query contains all matched rows, plus nonmatched rows from the PARTSUPP table (or, the table on the right hand side of the RIGHT OUTER JOIN clause). For example, if the PARTSUPP table contained a nonmatching record for a PNO column value of P9, this information would be part of the result. If, however, the PART table also contained an nonmatched record, this record information would not appear in the result rows. Using the RIGHT [OUTER] JOIN syntax includes nonmatched rows from only the joined table on the right of the RIGHT OUTER JOIN clause.

  • ON Clause
Parent topic: FROM Clause Syntax and Description


ON Clause

Restriction: This topic applies to Windows environments only.

Clause that can be used in place of the WHERE clause when explicitly stating an INNER JOIN condition (however, the WHERE clause still works). For LEFT and RIGHT OUTER JOIN clauses, however, the join condition must begin with the ON clause.

Parent topic: RIGHT [OUTER] JOIN


VALUE

Restriction: This topic applies to Windows environments only.

The VALUE or COALESCE function (COALESCE is the keyword specified by the ANSI/ISO standard of 1992 as a synonym for the VALUE function of IBM SQL), by either name, can be particularly useful in join operations. Suppose, for example, that in the full outer join sample query below, the PARTSUPP table contained a nonmatched row entry of P9 in the PNO column:

SELECT part.pno, pname, qty
  FROM part FULL OUTER JOIN partsupp
  ON part.pno = partsupp.pno

In this case, the P9 entry would not appear in the first column of the result. The problem is that the PNO column is in the PARTSUPP table, and is not included in the SELECT list of the query. We can, however, capture the PNO column of the PARTSUPP table by using the VALUE (or COALESCE) function as shown in the following query:

SELECT VALUE(part.pno, partsupp.pno) AS
    partnum, pname, qty
  FROM part FULL OUTER JOIN partsupp
  ON part.pno = partsupp.pno

The VALUE clause forces the query to first search the PNO column in the PART table for result data; and if none is found, search the PNO column of the PARTSUPP table. In the example above, the AS clause (AS partnum) provides a synonym for the result of the VALUE function. (See AS clause in SELECT Clause).

Parent topic: FROM Clause Syntax and Description


Nested Table Expressions

Restriction: This topic applies to Windows environments only.

An operand of a join can be more complex than the name of a single table or view. A subselect can be used as a complex operand in the FROM clause. Such an operand is called a nested table expression. Suppose we wanted to join the result of the last sample query with the SUBPART table, which includes a column named SUBPART (containing data similar to the commonly named PNO columns in the PART and PARTSUPP tables). The SUBPART table contains several rows with part numbers (SUBPART column) values that do not appear in either the PART or PARTSUPP tables.

The following sample query joins the SUBPART table with the result of the outer join of the PART and PARTSUPP table (three way join), displaying the nonmatching part number values from SUBPART in the result:

SELECT product, VALUE(subpart.subpart, partnum) AS
    partnum, pname, subpart.qty
  FROM subpart LEFT JOIN
  (SELECT VALUE(part.pno, partsupp.pno) AS
    partnum,pname, subpart.qty
    FROM part FULL OUTER JOIN partsupp
    ON part.pno = partsupp.pno) AS temp
  ON subpart.subpart = partnum

In this example, the correlation name is temp. The optional keyword AS is useful as an eye catcher for the correlation name that follows.

The following restrictions on nested table expressions apply:

  • Must be enclosed in parentheses
  • Must have a correlation name. In our example, the correlation name is temp.
Parent topic: FROM Clause Syntax and Description


Querying Views

Restriction: This topic applies to Windows environments only.

You may query a view just like a table, provided you have SELECT authority on the view. For example, assume that the redparts view was originally defined as follows:

CREATE VIEW redparts
  AS SELECT *
  FROM part
  WHERE color = 'RED'

The following query retrieves a subset of column values from this view (the view itself being a subset of the original PART table):

SELECT pno, city
  FROM redparts

The query result appears below:

pno | city
P1 | LONDON
P4 | LONDON
P6 | LONDON

The next example also queries the redparts view:

SELECT *
  FROM redparts
  WHERE weight < 15

The query results appear below:

pno | pname | color | weight | city
P1 | NUT | RED | 12 | LONDON
P4 | SCREW | RED | 14 | LONDON
Parent topic: FROM Clause Syntax and Description


WHERE Clause Syntax and Description

Restriction: This topic applies to Windows environments only.

Relational databases typically contain many rows of data, with each row constituting a separate record. Most relational database queries retrieve only a portion of the records contained in a table. The WHERE clause qualifies the query command statement to limit the data retrieved to specific rows in the table

The WHERE clause is generally used with a SELECT statement to specify search criteria for retrieving rows of data from a table or group of tables. The WHERE clause can also appear in DELETE and UPDATE command statements.

The optional WHERE clause sets conditions that each record must meet before that record is retrieved by a query. If the SELECT command statement does not include a WHERE clause, every row in the table or tables queried appears in the result.

A predicate states selection criteria that is applied to each row of data values in the table being queried by the SELECT statement. If the data in a particular record matches the selection criteria, then that record is retrieved by the query, otherwise the record is passed over. See Predicates for more information.

WHERE clause selection criteria may include nested subqueries or may connect two or more tables together in a join condition.

Syntax

The WHERE clause format appears below:

WHERE search-condition

where:

search-condition Specifies a predicate (or one or more predicates connected with the AND, OR, or NOT operators).

More:

  • Predicates
  • Joins
  • Predicates
  • Overriding the XDB Optimizer
  • Joins
  • Nested Queries
  • GROUP BY Clause
  • HAVING Clause
  • OPTIMIZE FOR Clause
  • ORDER BY Clause
  • FOR UPDATE OF Clause
  • UNION Clause
Parent topic: Clauses


Predicates

Restriction: This topic applies to Windows environments only.

This topic identifies the many different kinds of predicates that can appear in WHERE clauses. The XDB Server uses the test conditions defined in WHERE clause predicates to qualify table row (record) retrieval in a SELECT command statement. Any of the following predicates may also qualify records in UPDATE and DELETE command statements.

More:

  • Simple Predicates
  • Compound Predicate
  • BETWEEN Operator
  • IN Operator
  • IS [NOT] NULL Operator
  • LIKE Operator
  • SOUNDS LIKE Operator
  • WHERE Clause Expressions
  • CASE Expressions
  • Simple Predicates
  • Compound Predicate
  • BETWEEN Operator
  • IN Operator
  • IS [NOT] NULL Operator
  • LIKE Operator
  • SOUNDS LIKE Operator
  • WHERE Clause Expressions
  • CASE Expressions
Parent topic: WHERE Clause Syntax and Description


Simple Predicates

Restriction: This topic applies to Windows environments only.

Predicates using the following operators in their selection conditions are called simplepredicates:

Operator | Evaluated as
= | equal to
<> | not equal to
!= | not equal to
^= | not equal to
> | greater than
>= | greater than or equal to
!> | not greater than
< | less than
<= | less than or equal to
!< | not less than

The following query displays all rows in the SUPPLIER table containing a value of 20 in their STATUS column:

SELECT *
  FROM supplier
  WHERE status = 20

The query results appear below:

sno | sname | status | city
S1 | SMITH | 20 | LONDON
S4 | CLARK | 20 | LONDON

The WHERE clause in the next example compares a character string "PARIS" with the CITY column. The query below retrieves SNO (supplier number) and STATUS column data for all suppliers in Paris:

SELECT sno, status
  FROM supplier
  WHERE city = "PARIS"

Note that character strings can be enclosed in either double (") or single (') quotes. The display result appears below:

sno | status
S2 | 10
S3 | 30

When one column value is compared against another column value in a query -- and the column data types are different, the XDB Server tries to convert one of the data values to a data type compatible with the other data value before performing the comparison. For example, if integer and float column values are compared, the INT data value is converted to a FLOAT value before the XDB Server performs the comparison.

Spaces in data values are considered when evaluating retrieval conditions. Right justified data with leading spaces does not equal left justified data with trailing spaces. For example, the string "Jones" is read as a completely different value, depending on the number of preceding or trailing blank spaces attached. The LIKE predicate operator (see the LIKE Operator) allows string pattern matching without strict adherence to character string content and order.

All three of the < > or ! = or ^ = predicate operators specify records for retrieval that do not meet the specified condition. For example, the following query retrieves the PNO (part number) column values of all PART table records with a COLOR column value other than "RED."

SELECT pno
  FROM part
  WHERE color != "RED"
Parent topic: Predicates


Compound Predicate

Restriction: This topic applies to Windows environments only.

Compound predicates use the operators OR and AND. For example, to display the SNO column values for all suppliers in "PARIS" with a STATUS column value greater than 20, use the following query:

SELECT sno
  FROM supplier
  WHERE city = "PARIS"
    AND status > 20

Shown next is the same query written with the OR operator rather than the AND operator. This SELECT command statement retrieves PNO column values for those parts that are either "RED" or weigh more than 15 pounds.

SELECT pno
  FROM part
  WHERE color = "RED"
    OR weight > 15

In complex queries, parentheses can be used to indicate the order of evaluation. The condition(s) surrounded by the innermost pair of parentheses are applied first.

SELECT pno, pname
  FROM part
  WHERE color = "green"
    OR (city = 'LONDON'
    AND weight < 15)

This last query retrieves PNO and PNAME column values of all parts that are either green or are both made in London, and have a weight less than 15.

The query result is displayed below:

pno | pname
P1 | NUT
P2 | BOLT
P4 | SCREW
Parent topic: Predicates


BETWEEN Operator

Restriction: This topic applies to Windows environments only.

The BETWEEN operator allows the XDB Server to evaluate whether or not data values sort between a range of values indicated in the predicate.

The format for a predicate with a BETWEEN operator is shown below:

expres1 [NOT] BETWEEN expres2 AND expres3

Each occurrence of the expression expres1 is evaluated to determine if it sorts between and including the range values indicated by expres2 and expres3 (the range values in the BETWEEN clause are also part of the result set). The three variable expressions above can consist of any combination of column data values, constants, etc.

The next query selects all PART table records with WEIGHT column values between 15 and 18:

SELECT pno, pname
  FROM part
  WHERE weight BETWEEN 15 AND 18

The following records are retrieved:

pno | pname
P2 | BOLT
Parent topic: Predicates


IN Operator

Restriction: This topic applies to Windows environments only.

The IN (and NOT IN) operators cause an enumerated list of values appearing in the WHERE clause predicate to be evaluated for a true condition.

SELECT sno, sname
  FROM supplier
  WHERE sno IN ("S1", "S2", "S3")

All data values in the SNO column must match one of the three string constants in order for their corresponding records to be retrieved. This query retrieves the following data values:

sno | sname
S1 | SMITH
S2 | JONES
S3 | BLAKE
Parent topic: Predicates


IS [NOT] NULL Operator

Restriction: This topic applies to Windows environments only.

The IS NULL operator can be used in WHERE clause predicates to match null values occurring in a specified data column. For example, the query below retrieves all PART table records that do not have a NULL value in their COLOR data column:

SELECT *
  FROM part
  WHERE color IS NOT NULL

When used in a predicate, the NULL operator keyword must be preceded with either the IS or IS NOT keywords. Operators such as =, != or ^= can not be used with NULL.

Parent topic: Predicates


LIKE Operator

Restriction: This topic applies to Windows environments only.

The XDB Server supports the DB2 implementation of the LIKE string pattern matching operator. The syntax for a LIKE pattern match predicate appears below:

expression [NOT] LIKE
{special-register | host-variable | string-constant}
[ESCAPE {host-variable | string-constant}]

where:

expression | The expression parameter string value is compared to the pattern string, and can be any valid expression-- as long as the result of the expression is a string. The expression can consist of a single table column name or contain a column name as part of the expression.
special-register | Indicates that the string is stored in the named special register.
host-variable | Indicates that the string is in the named host variable. The host variable must be already be defined in accordance with the rules for declaring string host variables.
string-constant | Includes the pattern as a string constant within the predicate.

In each case, the pattern string value represented by either the special-register, host-variable or string-constant parameter is matched against the string value of expression -- for each table record specified by the query.

Pattern Strings

The host-variable and string-constant parameters can utilize two special reserved characters (wild card characters) -- the percent sign ( % ) and the underscore ( _ ) to perform pattern match searches against the string values in expression. The percent sign character matches any string (of any length), while the underscore character matches any single string character.

ESCAPE

The optional ESCAPE clause designates a special escape character, which if placed immediately before a percent ( % ) or underline ( _ ) character causes that percent or underline character to be literally interpreted as part of the pattern string. The escape character value can be specified with either a string-constant (enclosed in quotes) or host-variable (must not be a structure).

  • LIKE Examples
Parent topic: Predicates


LIKE Examples

Restriction: This topic applies to Windows environments only.

The query shown next retrieves data for those PART table records containing a PNAME column value that begins with "C":

SELECT pno, pname, weight
  FROM part
  WHERE pname LIKE "C%"

In the following example, the query match string "% of Total" is used to search the statistic column of a table called stats:

SELECT *
  FROM stats
  WHERE statistic LIKE "\% of Total"
    ESCAPE "\"

Note that in DB2 mode (for purposes of LIKE operator string comparison) trailing blanks are significant for data values located in fixed length CHAR data type columns. For example, if a character data type column with the a field length of ten contains a data value of "Sales ", a query containing the LIKE operator string "%s " would return a match. However, a LIKE operator string of "%s" in the same query would not return a match.

Parent topic: LIKE Operator


SOUNDS LIKE Operator

Restriction: This topic applies to Windows environments only.

The XDB Server supports a SOUNDS LIKE operator that uses a soundex algorithm to pattern match strings that sound alike. The syntax for a SOUNDS LIKE condition is:

field-name SOUNDS LIKE string

where:

field-name | Refers to a specific column containing the data values to be searches for a match.
string | Is any character string (enclosed in quotes) to be matched against the value of the field-name column in each data record.

For example, the following query retrieves all records from the EMPLOYEE table where the LNAME column value sounds like "herwood":

SELECT fname, lname
  FROM employee
  WHERE lname SOUNDS LIKE "herwood"

The query results appear next:

fname | lname
Roger | Hurwood
Susan | Hurwood
Parent topic: Predicates


WHERE Clause Expressions

Restriction: This topic applies to Windows environments only.

Expressions that compute values from one or more columns can be used advantageously in the WHERE clause of a query. Any legal arithmetic expression involving columns, constants, functions and arithmetic operators (+, -, * and /) is permitted in a WHERE clause. Parentheses may be used as necessary to define evaluation order.

Note:

If null values appear in an expression the result will be null.

The following query is an example of an expression appearing in the WHERE clause of a query:

SELECT pno, weight FROM part
  WHERE city = "LONDON"
    AND weight * 2 > 25
Parent topic: Predicates


CASE Expressions

Restriction: This topic applies to Windows environments only.

Use CASE expressions to create conditional logic.

Syntax

CASE {searched-when-clause | simple-when-clause}
  [ELSE NULL | ELSE result-expression]
  END
searched-when-clause:
WHEN search-condition THEN
{result-expression | NULL} ...
simple-when-clause:
expression WHEN expression THEN
  {result-expression | NULL} ...

where:

searched-when-clause | Specifies a search condition that is applied to each row or group of table data presented for evaluation and the result when that condition is true.
simple-when-clause | Specifies that the value of the expression prior to the first WHEN keyword is tested for equality with the value of each expression that follows a WHEN keyword. Also, specifies the result for each WHEN keyword when the expressions are equal.
result-expression | Specifies the result of a case-expression if no case is true. Also, specifies the result of a searched-when-clause or a simple-when-clause when true. There must be at least one result-expression in the CASE expression.
search-condition | Specifies a condition that is true, false, or unknown about a row or group of rows. The search-condition in a searched-when-clause cannot contain a subselect.

Example

From a table named EMPLOYEE, find all employees who earn more than 25 percent of their income from commission, but who are not fully paid on commission.

SELECT EMPNO, WORKDEPT, SALARY+COMM FROM EMPLOYEE
WHERE (CASE WHEN SALARY=0 THEN 0
  ELSE COMM/(SALARY+COMM) END >0.25;

Note that this example uses the CASE expression to avoid "division by zero" errors.

Parent topic: Predicates


Overriding the XDB Optimizer

Restriction: This topic applies to Windows environments only.

Usually, it is faster to execute a query using one or more indexes than to examine every record in the tables involved in the query. XDB Server's query optimization algorithms automatically examine the indexes available and pick which indexes, if any, to use for a particular query. The user normally does not need to specify which indexes to use.

You can force the use of an index for a particular query or force the system to not use an index. To force the use of an index, enter an asterisk (*) in parentheses after the name of the indexed column when you construct the query. To force the system to ignore the index, enter a hyphen (-) in parentheses after the name of the indexed column when you construct the query.

For example, assuming that an index exists on C_NO:

This query uses the C_NO index.

SELECT c_no, o_no, o_date
  FROM orders
  WHERE c_no(*)<20

This query does not use the index.

SELECT c_no, o_no, o_date
  FROM orders
  WHERE c_no(-)<20

The (*) and (-) options are valid only for column names that appear in a WHERE clause. You cannot use the (*) and (-) options in SELECT, GROUP BY, HAVING or ORDER BY clauses.

Parent topic: WHERE Clause Syntax and Description


Joins

Restriction: This topic applies to Windows environments only.

A join is a form of query that occurs any time more than one table or view name appears in the FROM clause of a query statement -- resulting in column data being retrieved from each table. The XDB Server allows up to 10 table names to appear within each level of a query.

More:

  • Equijoin
  • Non-equijoin
  • Correlation Names
  • Multi-table Joins
  • Outer Join
  • Equijoin
  • Non-equijoin
  • Correlation Names
  • Multi-table Joins
  • Outer Join
Parent topic: WHERE Clause Syntax and Description


Equijoin

Restriction: This topic applies to Windows environments only.

The equijoin is the most commonly used kind of table join. Equijoins include a join condition requiring the values derived from one column of a table or view to equal the values derived from another column of a different table or view. Join conditions may be created on any combination of columns, provided the qualified column names being compared in the WHERE clause have compatible data types.

For example, suppose the supplier numbers and city names for all suppliers that supply part "P2" are needed. The next query illustrates how this could be accomplished:

SELECT sno, city
  FROM partsupp, supplier
  WHERE partsupp.sno = supplier.sno
    AND pno = "P2"

The query results appear below:

sno | city
S2 | PARIS
S3 | PARIS
S1 | LONDON
S4 | LONDON

As demonstrated in the previous query, when the tables to be joined have a common column name appearing in the WHERE clause join condition, these column names should be prefixed (qualified) with their table names to resolve any ambiguity. In the above query, the qualified column name PARTSUPP.SNO specifies that the SNO column of the PARTSUPP table is to be compared with the SNO column of the SUPPLIER table (SUPPLIER.SNO).

Note:

If you do not qualify a column name that is contained in more than one query statement table, the system uses column data from the first table it finds containing the specified column name. This situation can produce unexpected results, and it is advisable to prefix common column names their specific "owning" table names.

If a join condition (such as, partsupp.sno = supplier.sno) is not included in a equijoin query, the result is a Cartesian product. This type of join concatenates every record from a table with every record from the other tables listed in the FROM clause, producing all this information in the query result. Cartesian products have limited practical value and can result in extremely large and often nonsensical results.

Parent topic: Joins


Non-equijoin

Restriction: This topic applies to Windows environments only.

The join condition in the WHERE clause may use operators other than the equal sign (=). For example, to find all employees that are not (!=) managers, the following query can be used:

SELECT lname, fname
  FROM dept, employee
  WHERE employee.e_no != dept.mgr
    AND employee.dept = dept.dept

The query result appears below:

lname | fname
Hurwood | Roger
Gross | Mary
Wilson | Arthur
Chung | Yung
Cox | John
Crisp | Keith
Hurwood | Susan
Haley | Olaf
Parent topic: Joins


Correlation Names

Restriction: This topic applies to Windows environments only.

To avoid repeatedly typing a full table name, a substitute correlation name for the same table may be designated, if desired. For example, to avoid repeating the table name qualifiers "supplier" and "partsupp" throughout the query, single letter correlation names can be assigned to replace the original table names henceforth in the same query.

Correlation names are designated in the FROM clause (immediately following the table name, and separated with a space) to serve as substitutes for qualifying table names later on in the WHERE clause. For example, to display the supplier number and city of all vendors who provide part "P2", the correlation names "p" and "s" can be used as qualifying prefixes instead of the table names (SUPPLIER and PARTSUPP).

SELECT sno, city
  FROM partsupp p, supplier s
  WHERE p.sno = s.sno
    AND pno = "P2"

Notice the correlation names appearing as column name prefixes in the WHERE clause join condition above.

It is possible to join a table to itself, if a correlation name is used to qualify each instance of the table appearing in the WHERE clause. For example, consider a table named personnel containing the columns staff_id, salary, and super_id. The result of the self-join query shown next displays all staff members who earn more than their supervisors:

SELECT a.staff_id
  FROM personnel a, personnel b
  WHERE a.salary > b.salary
    AND a.super_id = b.staff_id
Parent topic: Joins


Multi-table Joins

Restriction: This topic applies to Windows environments only.

The next query joins four tables in the TUTORIAL location to find the name of the customer, order date, product names, and quantities ordered -- for all orders with order number greater than three:

SELECT company, o_date, description, quantity
  FROM customer c, orders o, products p, items i
  WHERE c.c_no = o.c_no
    AND p.p_no = i.p_no
    AND o.o_no = i.o_no
    AND o.o_no > 3

The XDB Server will choose the optimal order for performing the join. Due to query optimization, a join performed on indexed columns may retrieve records in a different order than a join performed on nonindexed columns.

It is not possible to update, delete or insert into table records retrieved by performing a join. However, UPDATE and DELETE commands may contain joins embedded as subqueries in the WHERE clause to specify the target records in a table.

Parent topic: Joins


Outer Join

Restriction: This topic applies to Windows environments only.

An outer join creates two distinct kinds of query output one after the other -- all in the same result (not available in DB2 mode). Records satisfying the join condition appear first in the result, followed immediately by records that do not satisfy the join condition.

For example, an ordinary join between the SUPPLIER and PARTSUPP table could be performed using the following query:

SELECT supplier.sno, sname, pno, qty
  FROM supplier, partsupp
  WHERE supplier.sno = partsupp.sno

However, the output result would not include any information on supplier "S5", since this is the one supplier that does not supply any parts. (See the sample tables in XDB Server TUTORIAL Location.)

By performing an outer join, it is possible to retrieve the information on supplier "S5" from the SUPPLIER table (specifically the SNO and SNAME column values), even though the join condition of the WHERE clause (supplier.sno = partsupp.sno) is not being met for this row of joined output.

SELECT supplier.sno, sname, pno, qty
  FROM supplier, partsupp
  WHERE supplier.sno = partsupp.sno(+)

The sample query above illustrates the syntax for an outer join. Appending a plus sign within parentheses (+) to the PARTSUPP table name in the join condition yields the following results:

sno | sname | pno | qty
S1 | SMITH | P1 | 300
S1 | SMITH | P3 | 400
S1 | SMITH | P2 | 200
S1 | SMITH | P4 | 200
S1 | SMITH | P5 | 100
S1 | SMITH | P6 | 100
S2 | JONES | P2 | 400
S2 | JONES | P1 | 300
S3 | BLAKE | P2 | 200
S4 | CLARK | P2 | 200
S4 | CLARK | P4 | 300
S4 | CLARK | P5 | 400
S5 | ADAMS |  |

Even though the PARTSUPP table contains no rows with a matching "S5" value, the outer join causes the "S5" row of the SUPPLIER table to be output anyway (immediately after all the rows matching the join condition). Since there are no matching PNO or QTY column values from the PARTSUPP table for that joined row of output, the outer join inserts null values in the PNO and QTY columns for this result row.

The outer join conditions must be columns and not expressions. There is a maximum of five outer join conditions per table. Only one master table can be defined.

Parent topic: Joins


Nested Queries

Restriction: This topic applies to Windows environments only.

A nestedquery consists of two or more ordinary queries nested in such a way that the results of each inner query (subselect) are used in the comparison test for the selection clause of the next outer query (or another command statement). The three basic formats for nested queries (also called subqueries) are shown below:

WHERE expression [NOT] IN subselect
WHERE expression operator [ALL | ANY] subselect
WHERE [NOT] EXISTS subselect

where:

expression | Consists of any valid expression.
subselect | Consists of any valid subselect (ORDER BY and UNION clauses not allowed).
operator | Is any of the standard relational operators ( =, <>, !=, ^=, <, <=, >, >= ).
IN | Evaluates to true if at least one value retrieved by the subselect matches the predicate condition (operates the same as the =ANY predicate).
NOT IN | Evaluates to true if no matching values are retrieved by the subselect (operates the same as the !=ALL or ^=ALL predicates).
ALL | Is used with the standard relational operators ( =, >, >=, <, <=, <>, != or ^= ), and evaluates to true if every record retrieved by the subselect satisfies the condition.
ANY | Is used with the standard relational operators ( =, >, >=, <, <=, <>, != or ^= ), and evaluates to true if at least one record retrieved by the subselect satisfies the condition.
EXISTS | Evaluates as true if the subselect retrieves at least one value.
NOT EXISTS | Evaluates as true if the subselect retrieves no values.

The number of levels of subselect nesting permitted by the XDB Server is limited only by system storage. The actual number of nested queries that can be executed depends on the complexity of the queries, and the number of concurrently open queries. When accessing the XDB Server, the number of concurrently opened queries can be set with the XDB Server Configuration Utility.

During subselect execution, the innermost query is executed first, with that result determining the outcome of the comparison test in the next higher level query -- and so on for each nested query level. There are a number of comparison tests that can be performed using nested queries.

More:

Subselects and Locations

IN Special Operator

ALL Special Operator

ANY vs. SOME Operators

Single Value Comparisons

EXISTS Special Operator

Multiple Level Nesting

  • Subselects and Locations
  • IN Special Operator
  • ALL Special Operator
  • ANY vs. SOME Operators
  • Single Value Comparisons
  • EXISTS Special Operator
  • Multiple Level Nesting
  • Correlated Subqueries
Parent topic: WHERE Clause Syntax and Description


Subselects and Locations

Restriction: This topic applies to Windows environments only.

A subselect cannot reference a location different from the one referenced elsewhere in the command. That is, a referenced table and all subselects in a single SQL statement must be from the same location.

Invalid:

SELECT * FROM tutorial.tutorial.employee
WHERE e_no IN
  SELECT e_no FROM debloc.debbie.employee
  WHERE st = "MD";

Valid:

SELECT * FROM tutorial.tutorial.employee
WHERE e_no IN
  SELECT e_no FROM tutorial.debbie.employee
  WHERE st = "MD";
Parent topic: Nested Queries


IN Special Operator

Restriction: This topic applies to Windows environments only.

One of the most frequently used nested query comparison tests determines if a value retrieved by a query is IN (or NOT IN) the set of data values retrieved by a lower level subselect. The following sample query retrieves the names of suppliers who carry part number "P2":

SELECT sname
FROM supplier
WHERE sno IN
  SELECT sno
  FROM partsupp
  WHERE pno = "P2"

The inner (or lower) query is referred to as a nested query (or subselect) since it is located within an outer query statement. To execute the nested query, the system first tests for the PNO (part number) column values of records located in the PARTSUPP table that match "P2". The subselect statement (or subselect) next retrieves SNO (supplier number) column values for the records containing the correct part number.

The results of this first nested subselect appear below:

sno
S1
S2
S3
S4

The final result (shown below) is then produced by the outer query, which retrieves the four SNAME column values from the SUPPLIER table corresponding to the supplier numbers retrieved in the inner query.

sname
SMITH
JONES
BLAKE
CLARK

Note that the last nested query could have been written as a table join, as follows:

SELECT sname
  FROM supplier, partsupp
  WHERE supplier.sno = partsupp.sno
    AND partsupp.pno = "P2"

The processing that occurs for a table join is very similar to that occurring during a nested query execution. This processing consists of selecting a subset of records from one of the tables that meet all conditions except the join condition. The records in the other table are then tested for the join condition against the first subset of records.

The major difference between processing a join and a nested query is that the XDB Server can perform query optimization when a join is executed. For example, query optimization allows the system to decide which table to process first to achieve the most efficient performance. When a nested query is executed, however, the innermost query is always performed first.

Algorithms exist for transforming nested queries into joins (or flat queries) before processing. However, these algorithms are complex and time consuming, and therefore have not been implemented by XDB Server.

When nesting queries, the boolean operator NOT can be included to select those records that do not meet the test conditions set forth in selection criteria. For example, the following query returns the SNO and SNAME column values for all suppliers not found in the PARTSUPP table:

SELECT sno, sname
FROM supplier
WHERE sno NOT IN
  SELECT sno
  FROM partsupp

Supplier S5 (or "ADAMS") is the only supplier that meets this condition.

Parentheses can be added to complex SQL statements to enhance clarity or to change the execution order of the various subqueries and table joins. For example, the following statement performs a series of XDB Server operations equivalent to the descriptive text summary below:

Find all parts carried by suppliers, where the suppliers either have a status of 10 or are located in "PARIS".

SELECT DISTINCT pno, pname
FROM part, partsupp
WHERE part.pno = partsupp.pno
  AND sno IN
    SELECT sno
    FROM supplier
    WHERE status = 10
      OR city = "PARIS"

This last query retrieves the following results:

pno | pname
P1 | NUT
P2 | BOLT

If parentheses are added to the previous complex query, the results are interpreted differently.

The following reformatted query statement is equivalent to the descriptive text summary below:

Find all parts carried by suppliers having a status of 10 or a part made in "PARIS".

SELECT DISTINCT pno, pname
FROM part, partsupp
WHERE part.pno = partsupp.pno
  AND sno IN
    (SELECT sno
    FROM supplier
    WHERE status = 10)
  OR city = "PARIS"

This modified query yields the following result:

pno | pname
P1 | NUT
P2 | BOLT
P3 | CAM
P5 | CAM
Parent topic: Nested Queries


ALL Special Operator

Restriction: This topic applies to Windows environments only.

When the ALL special operator is used in a nested query, the test condition is true only if every record retrieved by the subselect satisfies the condition. The example nested query that follows illustrates how an ordinary relational operator is used in conjunction with the ALL special operator. This query retrieves the supplier numbers and part numbers of all parts supplied in at least as large a quantity as parts "P1" and "P6":

SELECT sno, pno
FROM partsupp
WHERE qty >= ALL
  (SELECT qty
  FROM partsupp
  WHERE pno = "P1"
    OR pno = "P6")

The result of the previous query appears below:

sno | pno
S1 | P1
S1 | P3
S2 | P2
S2 | P1
S4 | P4
S4 | P5
Parent topic: Nested Queries


ANY vs. SOME Operators

Restriction: This topic applies to Windows environments only.

Special care must be taken when performing test conditions with the ANY special operator, since the test may not conform to the common English interpretation. For example, while the English phrase "not equal any" would normally be evaluated as true if there are no values that match, the interpretation of the SQL equivalent operator !=ANY (or ^=ANY) is different. SQL interprets !=ANY to mean that the comparison is true, if there is at least one value that does not match.

The English equivalent for the SQL condition represented by !=ANY is, in fact, "any not equal". Since this test operator is equivalent to the more readily understood NOT IN, we recommend using NOT IN instead of !=ANY. Similar caution is required when using any other operator in conjunction with ANY. We recommended that the SOME special operator be used in place of ANY. The result is the same, however, the query is more intuitively understood.

The difference between the SOME and ALL special operators is illustrated with the nested query below. This query (except for the keyword SOME) is identical to the previous nested query (which used ALL):

SELECT sno, pno
FROM partsupp
WHERE qty > SOME
  (SELECT qty
  FROM partsupp
  WHERE pno = "P1"
    OR pno = "P6")

The following results illustrate how the SOME special operator retrieves a much larger subset of data than the ALL operator:

sno | pno
S1 | P1
S1 | P3
S2 | P2
S3 | P2
S1 | P2
S1 | P4
S2 | P1
S4 | P2
S4 | P4
S4 | P5
Parent topic: Nested Queries


Single Value Comparisons

Restriction: This topic applies to Windows environments only.

In those cases where a nested query can only retrieve one value (as with an aggregate function), the special operators SOME, ANY and ALL may be omitted from the comparison condition.

The next sample query finds the names of all suppliers with a status greater than the average supplier status:

SELECT sname
FROM supplier
WHERE status >
  (SELECT AVG(status)
  FROM supplier)

The results of this query follow:

sname
BLAKE
ADAMS
Parent topic: Nested Queries


EXISTS Special Operator

Restriction: This topic applies to Windows environments only.

To test whether or not a subselect retrieves any records, the EXISTS or NOT EXISTS special operators are used. The following query retrieves the names of all suppliers only if there is at least one part being supplied in quantities greater than zero:

SELECT sname
FROM supplier
WHERE EXISTS
  (SELECT sno
  FROM partsupp
  WHERE qty > 0)
Parent topic: Nested Queries


Multiple Level Nesting

Restriction: This topic applies to Windows environments only.

Queries can be nested up to six levels. For example, retrieve all supplier names -- for suppliers who supply at least one red part -- can be written as the following two level nested query:

SELECT sname
FROM supplier
WHERE sno IN
  (SELECT sno
  FROM partsupp
  WHERE pno IN
    (SELECT pno
    FROM part
    WHERE color = "RED"))

Note that the parentheses around the subqueries are optional. The system first executes the lowest level query to find the part numbers of red parts. The next higher level query is then executed, which finds the supplier numbers for those red parts. Finally, the outer level query (or main query) retrieves the names of the red part suppliers.

Parent topic: Nested Queries


Correlated Subqueries

Restriction: This topic applies to Windows environments only.

In all of the other nested query examples in this reference, the subqueries have been evaluated completely before performing the outer query. In some cases, however, it is necessary to test the subselect against each row in the outer query. This type of query is known as a correlatedsubquery.

The correlated subquery is executed once for each row retrieved by the outer query. One or more tables in the outer level query are given a correlation name, which is used to prefix the correlated columns located in the subqueries. The correlation name is an alternate name that is defined immediately after the corresponding table name or view name in the SELECT statement of the outer level query.

One common use of correlated subqueries is to test for existence. The following query first performs the subquery to qualify each SUPPLIER table record by testing whether or not there is a part made in the city where the supplier is located:

SELECT *
FROM supplier x
WHERE EXISTS
  (SELECT *
  FROM part
  WHERE city = x.city)

The correlation name "x" tells the system that the column name "x.city" is actually referring to the CITY column of the SUPPLIER table that appears in the outer level query. The results of this query are as follows:

sno | sname | status | city
S1 | SMITH | 20 | LONDON
S2 | JONES | 10 | PARIS
S3 | BLAKE | 30 | PARIS
S4 | CLARK | 20 | LONDON

The next sample query finds all employees with a pay rate greater than the average pay rate for the department they work in:

SELECT dept, fname, lname, payrate
FROM employee e
WHERE payrate >
  (SELECT AVG(payrate)
  FROM employee
    WHERE dept = e.dept)

In this example, both the inner and outer SELECT command statements query the EMPLOYEE table. The correlation name "e" tells the system that the column name "e.dept" comes from the outer level EMPLOYEE table.

Parent topic: Nested Queries


GROUP BY Clause

Restriction: This topic applies to Windows environments only.

When a query statement includes a GROUP BY clause, the SELECT clause for that query may list (in addition to ordinary column names) one or more aggregate functions (SUM, COUNT, AVG, etc.) operating on groups of data values in other columns.

The GROUP BY clause contains a column-list argument that must include all simple column names that appear in the SELECT clause. Columns can also be named using the AS Clause (see SELECT Clause). Simple column names are called grouping columns, since they group together records with identical data in that column. This record grouping allows mathematical operations to be performed on the other columns specified as arguments in the aggregate functions. Records can also be grouped by any valid expression appearing in the SELECT clause argument. In these cases, the expression must also be referenced in the GROUP BY clause by a whole number representing its relative column position in the SELECT clause (or output result).

Syntax

The GROUP BY clause format appears below:

GROUP BY column-list

where:

column-list Consists of an ordered list of column names or numbers, separated by commas.
  • GROUP BY Example
Parent topic: WHERE Clause Syntax and Description


GROUP BY Example

Restriction: This topic applies to Windows environments only.

The following query uses functions to produce three output columns in the query results. The query calculates the number of parts made in each city, and the maximum and minimum weight of those parts (in each city):

SELECT city, COUNT(*), MIN(weight), MAX(weight)
FROM part
  GROUP BY city

The query results are as follows:

city | count(*) | min(weight) | max(weight)
LONDON | 3 | 12 | 19
PARIS | 3 | 12 | 17

The next example (not available in DB2 mode) finds the number of orders placed each month, grouping the results by the first output column:

SELECT XMONTH(o_date), COUNT(*)
FROM orders
  GROUP BY 1

The query results are as follows:

column1 | count(*)
9 | 1
10 | 4
Parent topic: GROUP BY Clause


HAVING Clause

Restriction: This topic applies to Windows environments only.

Commonly used in conjunction with the GROUP BY clause, the HAVING clause qualifies aggregate record group results that appear in the query output.

The optional HAVING clause is used to qualify groups of records within a query result, and requires the use of aggregate functions. HAVING can be used with or without a GROUP BY clause. If no GROUP BY clause is specified, the SELECT clause in the query statement may only list aggregate functions -- in which case the conditions specified in the HAVING clause are applied to each aggregate group value. Each item in the search-condition must compare one aggregate property of a group with a constant, expression, nested query result, or another aggregate property of the same group. Nested queries are permitted within a HAVING clause.

Syntax

The HAVING clause format appears below:

HAVING search-condition

where:

search-condition A set of one or more conditions that group values must satisfy in order to qualify for retrieval.
  • HAVING Example
Parent topic: WHERE Clause Syntax and Description


HAVING Example

Restriction: This topic applies to Windows environments only.

The following sample query finds the average quantity of parts supplied for any part distributed by more than one supplier:

SELECT pno, AVG(qty)
FROM partsupp
  GROUP BY pno
  HAVING COUNT(*) >= 2

The query results appear as follows:

pno | AVG(qty)
P1 | 300
P2 | 250
P4 | 250
P5 | 250

The aggregate property evaluated in a HAVING clause may be an expression involving another aggregate function. Aggregate functions in HAVING clauses are demonstrated in the following query:

SELECT pno, AVG(qty)
FROM partsupp
  GROUP BY pno
  HAVING AVG(qty) * 2 > COUNT(*) * 200

The test condition in a HAVING clause may also include nested queries, as illustrated in the following query:

SELECT pno, AVG(qty)
FROM partsupp
GROUP BY pno
  HAVING AVG(qty) * 2 >
    (SELECT qty
    FROM partsupp
    WHERE pno = "P2"
      AND sno = "S2")
Parent topic: HAVING Clause


OPTIMIZE FOR Clause

Restriction: This topic applies to Windows environments only.

This optional clause for a SELECT statement is currently syntactically supported only by the XDB Server. It may appear before or after any accompanying FOR FETCH ONLY clause.

On mainframe DB2 systems, the OPTIMIZE FOR clause allows you to specify how many retrieved rows are to be used when optimizing. If no row limit is specified with the OPTIMIZE FOR clause, the system optimizes according to the total number of rows actually fetched. If more rows are fetched than are specified in this clause, performance could degrade. If the same number or fewer rows are fetched than are specified in this clause, performance should improve. The OPTIMIZE FOR clause does not alter the result table or the order in which the rows are fetched.

Syntax

The OPTIMIZE FOR clause format appears below:

OPTIMIZE FOR integer { ROW | ROWS }

where:

integer Identifies the number of rows expected to be retrieved from the cursor.

See also the OPTIMIZE directive in the precompiler manual for your compiler, and the OPTIMIZE FOR clause under the SELECT command in SQL Commands.

Parent topic: WHERE Clause Syntax and Description


ORDER BY Clause

Restriction: This topic applies to Windows environments only.

The ORDER BY clause specifies the order of rows retrieved by a fullselect. It sorts the rows of a query result according to the data values contained in a sort column (or columns). Sort columns are specified in the ORDER BY clause using either column names or column numbers separated by commas. Columns can also be named using the AS Clause (see SELECT Clause). The first column specified in the ORDER BY clause is the primary sort column. Output rows are ordered first according to the value in the primary sort column. If duplicate values occur in the primary sort column, the secondary sort column values are used to provide the final ordering.

The actual row order of the results depends on the data type of the column being sorted. Character columns are ordered according to the sort sequence specified during installation of the XDB Server (the default is a case insensitive ASCII sequence). Optional ordering parameters ASC (ascending) and DESC (descending) may be specified for each sort column.

When appearing in an SQL query statement, the ORDER BY clause is always the very last clause in the statement. Only one ORDER BY clause is permitted per query. ORDER BY clauses are not permitted in queries used to define views.

Please note that the ORDER BY clause only sorts the row output of query results, not the rows of the base table. To physically sort rows of data values in a base table, issue a CREATE table statement (with the same column configuration as the original table) combined with a SELECT query and ORDER BY clause. This single SQL command statement reproduces the original base table with the rows arranged according to the ORDER BY clause. The original base table remains unchanged.

Syntax

The ORDER BY clause format appears below:

ORDER BY sort-list

where:

sort-list Identifies up to 750 sort column names or numbers. The row order of query results can then be arranged according to the values of the sort column (or columns). Items in the sort list must be separated by commas, and may include an ordering parameter -- ASC (ascending) and DESC (descending) -- for each column name in the list. The default ordering parameter is ASC.
  • ORDER BY Example
Parent topic: WHERE Clause Syntax and Description


ORDER BY Example

Restriction: This topic applies to Windows environments only.

In the following sample query, the retrieved rows are first ordered by supplier number, and then by descending part number order -- within the same supplier number grouping.

SELECT sno, pno, qty
FROM partsupp
  ORDER BY sno, pno DESC

The query results are as follows:

sno | pno | qty
S1 | P6 | 100
S1 | P5 | 100
S1 | P4 | 200
S1 | P3 | 400
S1 | P2 | 200
S1 | P1 | 300
S2 | P2 | 400
S2 | P1 | 300
S3 | P2 | 200
S4 | P5 | 400
S4 | P4 | 300
S4 | P2 | 200
Parent topic: ORDER BY Clause


FOR UPDATE OF Clause

Restriction: This topic applies to Windows environments only.

The FOR UPDATE OF clause identifies the columns that can be updated in a later positioned UPDATE statement. It restricts the table columns that can be updated to those specified in the column-name list. These column names must be defined for the table or view appearing in the first FROM clause of the fullselect, and must not be qualified. FOR UPDATE OF cannot be used if the result table is read-only, nor can it be used in a statement containing a FOR FETCH ONLY clause.

Syntax

The FOR UPDATE OF clause format appears below:

FOR UPDATE OF column-name[,...]

where:

column-name An unqualified column name that must be a column of the table or view identified in the first FROM clause of the fullselect.
  • FOR UPDATE OF Examples
Parent topic: WHERE Clause Syntax and Description


FOR UPDATE OF Examples

Restriction: This topic applies to Windows environments only.

The following sample query changes salaries, bonuses, and commissions in a hypothetical table named earnings. These changes are accomplished with positioned updates using a cursor named alter_up, and are limited to departments A1 and H12.

EXEC SQL DECLARE alter_up CURSOR FOR
  SELECT dept, empno, salary, bonus, comm
  FROM earnings
  WHERE dept IN ('A1','H12')
  FOR UPDATE OF salary, bonus, comm

The columns to be updated are indicated in the FOR UPDATE OF clause in the cursor declaration.

Parent topic: FOR UPDATE OF Clause


UNION Clause

Restriction: This topic applies to Windows environments only.

The UNION clause combines the results of two or more subselects into a single output. It combines the output of from 2 through 33 subselect statements into a single result. The actual number of subselect results that can be attached with UNION clauses depends on the complexity of the queries, and the number of other queries open at the time of execution. The data types and lengths of each column in any two subselect tables must be identical in order for query results to be merged. The column names displayed in the result are taken from the first subselect table. When processing the subqueries of a UNION clause, the XDB Server removes duplicate rows (unless UNION ALL is specified).

Syntax

The format for UNION clause queries appears below:

subselect [(fullselect)]
  [UNION | UNION ALL]
  [subselect [(fullselect)]]

where:

subselect | Components referring to any valid subselect.
ALL | Causes duplicate rows to be included in the output results.
  • Example: UNION Clause
Parent topic: WHERE Clause Syntax and Description


Example: UNION Clause

Restriction: This topic applies to Windows environments only.

The following query retrieves the supplier numbers for all suppliers having a status equal to 30 or more, and then appends to this result the numbers of suppliers who carry green parts.

SELECT sno
FROM supplier
WHERE status >= 30
  UNION
SELECT sno
FROM part p, partsupp ps
WHERE p.pno = ps.pno
  AND p.color = "GREEN"

This query yields the results shown below. Notice that duplicate rows have been omitted from the result since UNION ALL was not specified:

sno
S1
S2
S3
S4
S5

If an ORDER BY clause is used to sort the combined row results of a UNION query, the ORDER BY clause must specify the number of an output column on which to sort the combined output. The first query output column listed in the SELECT clause is column 1, the second column 2, etc.

Also notice in the following sample query how the string "Part" is padded with spaces to make it the same length as the "Supplier" string. Output columns combined with a UNION clause must be of the same data type and character width.

SELECT "Part    ", pno, "Made in England   "
FROM part
WHERE city = "LONDON"
  UNION
SELECT "Supplier", sno, "Located in England"
FROM supplier
WHERE city = "LONDON"
  ORDER BY 2 DESC

The result of this query is:

column1 | pno | column3
Supplier | S4 | Located in England
Supplier | S1 | Located in England
Part | P6 | Made in England
Part | P4 | Made in England
Part | P1 | Made in England

In the final sample query below, two corresponding columns of two hypothetical tables, PART_ON_HAND and PART_ON_ORDER are both defined as Total_Value by the AS clause.

SELECT 'Available', partnum,
  q_on_hn * price AS Total_Value
  FROM part_on_hand
UNION ALL
SELECT 'On Order', partnum,
  q_on_ord * price AS Total_Value
  FROM part_on_order
ORDER BY partno, Total_Value

The corresponding column of the union of the two tables is also named Total_Value, even though it is the result of derived columns.

Parent topic: UNION Clause


Functions Overview

Restriction: This topic applies to Windows environments only.

A function is a syntactic structure that returns a value derived from applying the function to its arguments. The XDB Server provides standard SQL functions, including SUM, MIN, MAX, COUNT, and AVG, as well as XDB Server-specific extensions, which usually begin with an "X".

Functions are frequently used in the SELECT clause and WHERE clause of SELECT commands, as well as in the WHERE clause of UPDATE and DELETE commands. Functions may also appear in HAVING clauses. Their use is not limited to these cases, however. For example, functions that involve arguments that can be evaluated as constants can be used in the VALUES clause of INSERT commands.

For maximum flexibility, many of the functions can be nested within one another. In addition, functions can make use of the special keywords (for example, CURRENT DATE, CURRENT TIME).

  • Compatibility Modes
  • Recursive Inference Functions
  • Aggregate Functions
  • Date And Time Functions (XDB Mode)
  • Date And Time Functions (DB2 Mode)
  • Date/Time Arithmetic
  • Numeric Functions
  • String Functions
Parent topic: SQL Reference


Compatibility Modes

Restriction: This topic applies to Windows environments only.

The XDB Server functions which are provided in addition to the standard SQL functions are normally available only when running in XDB mode. Check the following table or check the mode key below each function name. A diamond character (X) means the function is supported in that mode. The SQL compatibility mode can be set in your client configuration or with the SET COMPATIBILITY command.

 | ANSI | DB2 | XDB
AGE |  |  | X
ASCII |  |  | X
AVG | X | X | X
CEILING |  |  | X
CHAR |  | X | X
CHR |  |  | X
COUNT | X | X | X
DATE |  | X | X
DAY |  | X | X
DAYOFYEAR |  |  | X
DAYS |  | X | X
DECIMAL |  | X | X
DIGITS |  | X | X
FACTORIAL |  |  | X
FINDANY |  |  | X
FINDNOTIN |  |  | X
FINDSTR |  |  | X
FLOAT |  | X | X
FLOOR |  |  | X
HEX |  | X | X
HOUR |  | X | X
INITCAP |  |  | X
INTEGER |  | X | X
LENGTH |  | X | X
LEVEL |  |  | X
LTRIM |  |  | X
MAX | X | X | X
MICROSECOND |  | X | X
MIN | X | X | X
MINUTE |  | X | X
MOD |  |  | X
MONTH |  | X | X
MONTHBEG |  |  | X
MONTHSBTWN |  |  | X
NULLIF | X | X | X
PI |  |  | X
PREVIOUS |  |  | X
QUARTER |  |  | X
QUARTERBEG |  |  | X
REPLICATE |  |  | X
REVCHAR |  |  | X
ROUND |  |  | X
RTRIM |  |  | X
SECOND |  | X | X
SIGN |  |  | X
STRIP |  | X | X
SUBSTR |  | X | X
SUM | X | X | X
TIME |  | X | X
TIMESTAMP |  | X | X
TODAY |  |  | X
TRUNCATE |  |  | X
VALUE |  | X | X
WEEKDAY |  |  | X
WEEKOFYEAR |  |  | X
WEEKSBTWN |  |  | X
XABS |  |  | X
XCONCAT |  |  | X
XDATE |  |  | X
XEXP |  |  | X
XLEFT |  |  | X
XLN |  |  | X
XLOG |  |  | X
XLOWER |  |  | X
XPOWER |  |  | X
XRIGHT |  |  | X
XSQRT |  |  | X
XSTDDEV |  |  | X
XTRIM |  |  | X
XUPPER |  |  | X
XVAR |  |  | X
YEAR |  | X | X
YEARBEG |  |  | X
Parent topic: Functions Overview


Recursive Inference Functions

Restriction: This topic applies to Windows environments only.

Recursive inference is the process of using data already found in a table to infer a relationship with other, related column data (not available in DB2 mode). Recursive inference is frequently used in solving parts assembly problems or the classic "bill-of-materials" problem.

The LEVEL condition is normally used in conjunction with the PREVIOUS function in queries to implement recursive inference. It could be helpful to first read the PREVIOUS function description, before returning to the LEVEL condition description below.

More:

  • LEVEL
  • PREVIOUS
  • LEVEL
  • PREVIOUS
Parent topic: Functions Overview


LEVEL

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The LEVEL condition may be used in conjunction with each PREVIOUS function to qualify the result on the basis of the number of recursions performed. Any of the operators =, <, <=, >, >=, != or ^= may be used in the LEVEL condition, and the right hand side may be either a positive integer (level numbers begin with 0) or the keyword BOTTOM, which indicates the bottom level of each of the recursive branches constructed by the PREVIOUS function.

All other search conditions (except those applied by GROUP BY and HAVING clauses) are applied to the original table before the recursion is performed. After the table has been "exploded" GROUP BY, HAVING and ORDER BY clauses are applied.

For example, if you wanted to know only the second level subparts used in making product P11 (see PREVIOUS function), you could execute the following query. Note that level numbers begin with 0, therefore the second level is level 1.

SELECT subpart
FROM subpart
WHERE product = PREVIOUS(subpart)
  AND LEVEL = 1
  AND product = "P11"

The result of this query is:

subpart
P5
P7
P8
P1
P2

For a graphic depiction of the various levels of recursive inference in the above example, see the figure in the PREVIOUS function description.

Parent topic: Recursive Inference Functions


PREVIOUS

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The PREVIOUS function (XDB mode only) is used in combination with the LEVEL condition to give queries recursive inference capabilities. One PREVIOUS function is permitted per subselect.

The SUBPART table contains the following records:

product | subpart | qty
P7 | P1 | 2
P7 | P2 | 4
P7 | P6 | 6
P8 | P4 | 8
P8 | P7 | 1
P9 | P5 | 3
P9 | P7 | 5
P9 | P8 | 7
P10 | P1 | 9
P10 | P2 | 1
P11 | P9 | 2
P11 | P10 | 3

The SUBPART column lists the part numbers of all subparts used in assembling a complete product, while the part numbers of all products that contain the assembled subparts appear in the PRODUCT column. For instance, product P8 is made up of subparts P4 and P7. However, since product P7 is also made up of subparts P1, P2 and P6, we can infer that subparts P1, P2 and P6 are also required by a completed product P8. Standard SQL cannot easily detect interrelationships between products and subparts in this table.

The following query uses the PREVIOUS function to determine all the subparts which go into the making of a single product P11.

SELECT subpart
FROM subpart
WHERE product = PREVIOUS(subpart)
  AND LEVEL = BOTTOM
  AND product = "P11"

The PREVIOUS function (in combination with the LEVEL condition) uses recursive inference to "explode" the data in the SUBPART column (see the following figure) to match each product with all the subparts required for its assembly.

See the description of the LEVEL condition for a discussion of the BOTTOM keyword. In the example above, BOTTOM causes only the "bottom" level of subpart numbers (only those subparts that are not themselves composed of other subparts) contained in each recursive branch of the figure to appear in the result.

Parent topic: Recursive Inference Functions


Aggregate Functions

Restriction: This topic applies to Windows environments only.

The XDB Server supports a number of aggregate functions that are used with the SELECT command to operate on the values from a specified column. The column-name that follows the function must be enclosed in parentheses. The result of an aggregate function is a single value for every group in the query result. If the query result is not grouped, the entire result is treated as a single group, and the result of an aggregate function is a single value.

More:

  • AVG
  • COUNT
  • MAX
  • MIN
  • SUM
  • XSTDDEV
  • XVAR
  • Example: Aggregate Functions
  • AVG
  • COUNT
  • MAX
  • MIN
  • SUM
  • XSTDDEV
  • XVAR
  • Example: Aggregate Functions
Parent topic: Functions Overview


AVG

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
X | X | X | X

Averages the values in each group of a column. This function is for numeric fields only. Null values will be ignored. The format appears below:

AVG([DISTINCT]x)

where the parameter x is a numeric field. Note that in DB2 mode, performing an AVG on data of type integer or data of type small integer gives a result of an integer with decimal places truncated.

Parent topic: Aggregate Functions


COUNT

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
X | X | X | X

COUNT is a standard SQL function that counts the number of records in each group satisfying the condition(s) specified. COUNT(*) returns the number of rows in the table.

For all modes except DB2 mode, the formats below return the number of non-NULL values in column-name or expression:

COUNT(column-name)

or:

COUNT(expression)

Allowable formats for all modes appear below:

COUNT(*)

or:

COUNT(DISTINCT expression)

which filters out duplicate values to return the number of distinct values in expression. For example, to discover how many suppliers are currently supplying parts, you could use the query:

SELECT COUNT(DISTINCT sno)
FROM partsupp
Parent topic: Aggregate Functions


MAX

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
X | X | X | X

Selects the maximum value in each group of a column. Null values will be ignored. The format appears below:

MAX([DISTINCT]x)

where the parameter x is a column name.

Parent topic: Aggregate Functions


MIN

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
à | à | à | à

Selects the minimum value for each group of a column. Null values will be ignored. The format appears below:

MIN([DISTINCT]x)

where the parameter x is a column name.

Note:

The DISTINCT keyword is ignored in the MAX and MIN functions.

Parent topic: Aggregate Functions


SUM

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
X | X | X | X

Adds up all the values in each group of a column. Null values will be ignored. The format appears below:

SUM([DISTINCT] x)

where the parameter x is a numeric field or expression, and the keyword DISTINCT is used to filter out duplicate values prior to summing. Note that DISTINCT can be used with either a column name or an expression.

Parent topic: Aggregate Functions


XSTDDEV

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

An XDB Server statistical function for finding the standard deviation of a column. Null values are ignored. The format appears below:

XSTDDEV(x)

where the parameter x is a numeric column.

Note that XSTDDEV(x) is the same as (XVAR(x))E+1/2. The formula used for computing standard deviation is:

Formula for standard deviation

Parent topic: Aggregate Functions


XVAR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

An XDB Server statistical function used for finding the variance of a column of data. The format appears below:

XVAR(x)

where x is a column name. The parameter x must be a numeric field.

Note that XVAR(x) is the same as (XSTDDEV(x))E+2. The formula used for computing variance is:

Formula for variance

Parent topic: Aggregate Functions


Example: Aggregate Functions

Restriction: This topic applies to Windows environments only.

All of the aggregate functions are applied only to the set of records retrieved by the SELECT command. Examples of each of the functions are given below.

To find the number of "CAM" parts in the table, enter:

SELECT COUNT(pno) FROM part
WHERE pname = "CAM"

The result is 2. To find the total quantity of P2 supplied, enter:

SELECT SUM(qty) FROM partsupp
WHERE pno = "P2"

The result is 1000. To find the weight of the heaviest part, enter:

SELECT MAX(weight) FROM part

More than one function can be used in a command, as in the query:

SELECT COUNT(pno), AVG(weight), MIN(weight),
  MAX(weight), XSTDDEV(weight)
FROM part

Commands containing both an aggregate function and a simple field-name are not allowed unless the result is grouped by the simple field. For example, the following query is illegal:

SELECT SUM(qty), pno
FROM partsupp

To correct it, add a GROUP BY clause, as shown below:

SELECT SUM(qty), pno
  FROM partsupp
  GROUP BY pno

The next example finds the average weight, and number of parts for every part color that has two or more parts, and displays them in color order.

SELECT color, AVG(weight), COUNT(*)
  FROM part
  GROUP BY color
    HAVING COUNT(*) >= 2
  ORDER BY color

The result is:

color | avg(wt) | count(*)
BLUE | 12 | 2
RED | 15 | 3
Parent topic: Aggregate Functions


Date And Time Functions (XDB Mode)

Restriction: This topic applies to Windows environments only.

Date calculations are fully supported in XDB mode using the following date, time and timestamp functions. The XDB Server also supports date-time arithmetic in XDB mode and DB2 mode, although the results in DB2 mode are different. The expressions and functions documented in this topic can appear in a SELECT or WHERE clause any place a column name for the appropriate column type might appear. Date functions operate on dates between 1/1/0001 and 12/31/9999. Historical dates may differ from the dates under the Gregorian calendar used.

More:

  • AGE
  • CHAR
  • DATE
  • DAY
  • DAYOFYEAR
  • DAYS
  • HOUR
  • MICROSECOND
  • MINUTE
  • MONTH
  • MONTHBEG
  • MONTHSBTWN
  • QUARTER
  • QUARTERBEG
  • SECOND
  • TIME
  • TIMESTAMP
  • TODAY
  • WEEKDAY
  • WEEKOFYEAR
  • WEEKSBTWN
  • YEAR
  • YEARBEG
  • XDATE
  • AGE
  • CHAR
  • DATE
  • DAY
  • DAYOFYEAR
  • DAYS
  • HOUR
  • MICROSECOND
  • MINUTE
  • MONTH
  • MONTHBEG
  • MONTHSBTWN
  • QUARTER
  • QUARTERBEG
  • SECOND
  • TIME
  • TIMESTAMP
  • TODAY
  • WEEKDAY
  • WEEKOFYEAR
  • WEEKSBTWN
  • YEAR
  • YEARBEG
  • XDATE
Parent topic: Functions Overview


AGE

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Calculates the difference in years between date1 and date2. The format appears below:

AGE(date1, date2)

For example, the query below retrieves the names of tasks begun less than 5 years as of TODAY:

SELECT task_name FROM tasks
WHERE AGE(startdate, TODAY) < 5

The AGE function also has a single parameter format that calculates the difference in years between today's date and date1. The format appears below:

AGE(date1)

The following query finds the age of each employee in the EMPLOYEE table.

SELECT lname, AGE(birth)
FROM employee
Parent topic: Date And Time Functions (XDB Mode)


CHAR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The CHAR function can take a mask (XDB mode only) as an optional second parameter. The format appears below:

CHAR(date[,mask])

The parameter mask must be a quoted string that contains a mask for a date or a time, based on existing masking rules.

For example:

SELECT CHAR(datefld, "www") FROM datetable

will give the day of the week (for example, "MON"). For more information on masks, see the SQLWizard User's Guide and the Options User's Guide.

Parent topic: Date And Time Functions (XDB Mode)


DATE

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The DATE function is used to convert a value into a date. The format appears below:

DATE(expres)

The parameter expres can be a character string, a timestamp, a date, a positive number less than 3,652,059, or a null value. If expres is a date, the result is the date. If expres is a timestamp, the result is the date portion of the timestamp. If expres is a character string, it must be in one of the following formats that XDB Server recognizes:

yyyy-mm-dd | ISO or JIS format.
mm/dd/yyyy | USA format.
dd.mm.yyyy | EUR format.

If expres is a number, the result is the number of days since January 1, 0001 (including January 1, 0001). An example of the DATE function is:

UPDATE orders
  SET o_date = DATE("1989245")
  WHERE o_no = 5
Parent topic: Date And Time Functions (XDB Mode)


DAY

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The DAY function (also XDAY) extracts the day of the month from a date or timestamp. The format appears below:

DAY(date-expr)

The following query finds the quantity of parts ordered on the first day of the month:

SELECT p_no, SUM(quantity)
  FROM orders, items
  WHERE DAY(o_date) = 1
  GROUP BY p_no
Parent topic: Date And Time Functions (XDB Mode)


DAYOFYEAR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The DAYOFYEAR function give the number of days (1-366) since the beginning of the year for specified date (a.k.a. Julian date). The format appears below:

DAYOFYEAR(date)

For example:

DAYOFYEAR(06/21/1991) = 173
Parent topic: Date And Time Functions (XDB Mode)


DAYS

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The DAYS function is used to obtain an integer that corresponds to the number of days between January 1, 0001 and the date in date-expr (including January 1, 0001). The format appears below:

DAYS(date-expr)

The parameter date_expr can be a date, timestamp, or a valid string representation of a date. An example is:

SELECT DAYS(TODAY) - DAYS(o_date)
FROM orders
Parent topic: Date And Time Functions (XDB Mode)


HOUR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The HOUR function is used to extract the hour part of a time or timestamp. The result is an integer between 0 and 24 (or null if time-expr evaluates to a null value). The format appears below:

HOUR(time-expr)

For example:

SELECT HOUR(starttime)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


MICROSECOND

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function is used to extract the microsecond part of a timestamp. The result is an integer between 0 and 999999 (or null if time-expr evaluates to a null value). The format appears below:

MICROSECOND(time-expr)

For example:

SELECT MICROSECOND(audit_time)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


MINUTE

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function is used to extract the minute part of a time or timestamp. The result is an integer between 0 and 59 (or null if time-expr evaluates to a null value).

The format appears below:

MINUTE(time-expr)

For example:

SELECT MINUTE(endtime)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


MONTH

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function (also XMONTH) extracts the month from a date or timestamp. The format appears below:

MONTH(date-expr)

For example, a query lists the quantity of parts ordered in January:

SELECT p_no, SUM(quantity)
  FROM orders
  WHERE MONTH(o_date) = 1
  GROUP BY p_no
Parent topic: Date And Time Functions (XDB Mode)


MONTHBEG

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to extract the first day of the month the date resides in. The format appears below:

MONTHBEG(date)

For example:

MONTHBEG(2/14/1991) = 2/1/1991
Parent topic: Date And Time Functions (XDB Mode)


MONTHSBTWN

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the difference between dates in months. The format appears below:

MONTHSBTWN(date1,date2)

For example:

MONTHSBTWN(07/24/1991,10/13/1991) = 3
Parent topic: Date And Time Functions (XDB Mode)


QUARTER

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the numeric value (1-4) of the quarter in which the date resides. The format appears below:

QUARTER(date)

For example:

QUARTER(2/14/1991) = 1
QUARTER(5/14/1991) = 2
Parent topic: Date And Time Functions (XDB Mode)


QUARTERBEG

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the date of the first day of the quarter in which the date resides. The format appears below:

QUARTERBEG(date)

For example:

QUARTERBEG(2/14/1991) = 1/1/1991
QUARTERBEG(5/14/1991) = 4/1/1991
Parent topic: Date And Time Functions (XDB Mode)


SECOND

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

This function is used to extract the seconds part of a time or timestamp. The result is an integer between 0 and 59 (or null if time-expr evaluates to a null value). The format appears below:

SECOND(time-expr)

For example:

SELECT SECOND(endtime)
FROM tasks
Parent topic: Date And Time Functions (XDB Mode)


TIME

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The TIME function is used to convert a value into a time. The format appears below:

TIME(expres)

The parameter expres can be a character string, a timestamp, a time, or a null value. If expres is a time, the result is the time. If expres is null, the result is the null value. If expres is a timestamp, the result is the time portion of the timestamp. If expres is a character string, it must be in one of the following formats that XDB Server recognizes:

hh.mm.ss | ISO, EUR or JIS format
hh:mm: AM | PM | USA format

For example:

UPDATE tasks
SET endtime = TIME(audit_time)
Parent topic: Date And Time Functions (XDB Mode)


TIMESTAMP

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The TIMESTAMP function is used to generate a timestamp. The format appears below:

TIMESTAMP(expres1 [, expres2])

If only one argument is specified, expres1 can be a timestamp or a valid string representation of a timestamp. If two arguments are specified, expres1 must be a date or date string, and expres2 must be a time or time string. If any argument that can be null is null, the result is null.

For example:

UPDATE task
SET audit_time = TIMESTAMP(startdate, starttime)
Parent topic: Date And Time Functions (XDB Mode)


TODAY

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The XDB Server recognizes the keyword TODAY as a reserved name for the current date (data type is date). For compliance with DB2, the XDB Server also recognizes CURRENT DATE as being the same as TODAY within SQL. The XDB Server recognizes the keyword XTIME as a reserved name for the current time (data type is time). For compliance with DB2, The XDB Server also recognizes CURRENT TIME as being the same as XTIME within the SQL Language.

Parent topic: Date And Time Functions (XDB Mode)


WEEKDAY

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to extract the numeric value (1-7) of the day of the week. The format appears below:

WEEKDAY(date)

For example:

WEEKDAY(tuesday) = 2
Parent topic: Date And Time Functions (XDB Mode)


WEEKOFYEAR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the number of weeks (1-53) since the beginning of the year for the specified date. The format appears below:

WEEKOFYEAR(date)

The number of weeks is determined by the number of Sundays. The function starts at week one and adds a week every time a Sunday occurs. For example, if January 6, 1991, is a Sunday:

WEEKOFYEAR(1/5/1991) = 1
WEEKOFYEAR(1/6/1991) = 2
WEEKOFYEAR(1/7/1991) = 2
Parent topic: Date And Time Functions (XDB Mode)


WEEKSBTWN

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to obtain the difference between dates in weeks. The format appears below:

WEEKSBTWN(date1, date2)

The difference in weeks is determined by the number of Sundays between the two dates, including the first date but not the second. For example, if January sixth is a Sunday, and January thirteenth is a Sunday:

WEEKSBTWN(01/06/1991, 01/13/1991) = 1
Parent topic: Date And Time Functions (XDB Mode)


YEAR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

The YEAR function (also XYEAR, XDB mode only) extracts the year from a date or timestamp. The format appears below:

YEAR(date-expr)

For example, the following query finds all employees born the same year as employee Smith:

SELECT lname FROM bdaylist
WHERE YEAR(birth) IN
  (SELECT YEAR(birth) FROM bdaylist
  WHERE lname = "SMITH")
Parent topic: Date And Time Functions (XDB Mode)


YEARBEG

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

This function is used to extract the date of the first day of the year in which the date resides. The format appears below:

YEARBEG(date)

For example:

YEARBEG(2/14/1991) = 1/1/1991
Parent topic: Date And Time Functions (XDB Mode)


XDATE

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

The XDATE function takes 3 integers and converts them into a date. The format appears below:

XDATE(m, d, y)

The m parameter is an expression that evaluates to an integer representing a month of the year (1-12). The d parameter is an expression that evaluates to an integer representing a day of the month (1-31). The y parameter is an expression that evaluates to an integer representing a year. For example, the following command creates an employee birthday calendar for the current year.

SELECT "Birthday for", fname, lname,"is",
  XDATE(XMONTH(birth), XDAY(birth), XYEAR(TODAY))
FROM bdaylist
Parent topic: Date And Time Functions (XDB Mode)


Date And Time Functions (DB2 Mode)

Restriction: This topic applies to Windows environments only.

XDB Server's Date and Time arithmetic functions have been enhanced to provide full DB2 compatibility when operating in DB2 mode. Included are addition and subtraction of date and time field values as well as durations. When operating in XDB mode, arithmetic operations on dates and times are calculated as explained in the Date And Time Functions (XDB mode) section.

SQL Compatibility Mode is set either in the client configuration or by issuing a SET COMPATIBILITY command. Consult your DB2 documentation for further information on date/time functions and expressions.

Date-Time arithmetic under DB2 mode can involve date, time and timestamp field values or durations. The types of durations supported when running in DB2 mode are:

More:

  • Labeled Duration
  • Date Duration
  • Time Duration
  • Timestamp Duration
  • Labeled Duration
  • Date Duration
  • Time Duration
  • Timestamp Duration
Parent topic: Functions Overview


Labeled Duration

Restriction: This topic applies to Windows environments only.

This type of duration represents a specific unit of time as expressed by a number followed by one of the following keywords:

YEAR | YEARS
MONTH | MONTHS
DAY | DAYS
HOUR | HOURS
MINUTE | MINUTES
SECOND | SECONDS
MICROSECOND | MICROSECONDS

The value of the labeled duration can be the result of an expression. It is treated as a DECIMAL(15,0) number. To use a labeled duration in a date-time computation, the other arithmetic operator must be a DATE, TIME or TIMESTAMP data field. Consider the following expression examples where ORDERDATE is a date field being added to two labeled durations (2 MONTHS and 14 DAYS).

ORDERDATE + 2 MONTHS + 14 DAYS
This is a valid entry because the expression is resolved from left to right, with ORDERDATE + 2 MONTHS yielding a DATE. The labeled duration 14 DAYS is then added to the new DATE. This expression is the same as (ORDERDATE + 2 MONTHS) + 14 DAYS.
ORDERDATE + (2 MONTHS + 14 DAYS)
This is not a valid entry because a labeled duration cannot be added to another labeled duration (2 MONTHS cannot be added to 14 DAYS).
Parent topic: Date And Time Functions (DB2 Mode)


Date Duration

Restriction: This topic applies to Windows environments only.

In DB2 mode, this type of duration represents a number of years, months or days expressed as a DECIMAL(8,0) number (in XDB mode the number is expressed in days). The number must have the format YYYYMMDD. For example, the result of subtracting one DATE value from another (such as SHIPDATE-ORDERDATE) is a date duration (in XDB mode the units of the result are days).

Parent topic: Date And Time Functions (DB2 Mode)


Time Duration

Restriction: This topic applies to Windows environments only.

In DB2 mode, this type of duration represents a number of hours, minutes or seconds as expressed as a DECIMAL(6,0) number (in XDB mode the number is expressed in seconds). The number must have the format HHMMSS. For example, the result of subtracting one TIME value from another is a time duration.

Parent topic: Date And Time Functions (DB2 Mode)


Timestamp Duration

Restriction: This topic applies to Windows environments only.

This duration is a DECIMAL(20,6) number that represents an interval of time. In DB2 mode and XDB Modes, the result of subtracting two TIMESTAMP values is a TIMESTAMP duration. The TIMESTAMP duration format yyyyxxddhhmmsszzzzzz defines the years (yyyy), months (xx), days (dd), hours (hh), minutes (mm), seconds (ss), and microseconds (zzzzzz) of the time interval.

Parent topic: Date And Time Functions (DB2 Mode)


Date/Time Arithmetic

Restriction: This topic applies to Windows environments only.

If a date-time value is the operand of addition, the other operand must be a duration. The rules for subtracting are different because a date-time value cannot be subtracted from a duration, and subtracting two date-time values differs from subtracting a duration from a date-time value. The rules for date-time arithmetic are shown in the following table.

Addition Rules

If one operand is a... ...the other operand must be a...
Date
  • Date Duration
  • Labeled Duration of years, months or days
Time
  • Time Duration
  • Labeled Duration of hours, minutes or seconds
Timestamp
  • Timestamp Duration
  • Labeled Duration of years, months, days, hours, minutes or seconds

Subtraction Rules

If the FIRST operand is a... ...the SECOND operand must be a...
Date
  • Date
  • Date Duration
  • String representation of a date
  • Labeled duration of years, months or days
Time
  • Time
  • Time Duration
  • String representation of a time
  • Labeled duration of hours, minutes or seconds
Timestamp
  • Timestamp
  • Timestamp Duration
  • Date Duration
  • Time Duration
  • String representation of a timestamp
  • Labeled duration of years, months, days, hours, minutes or seconds
If the SECOND operand is a... ...the FIRST operand must be a...
Date
  • Date
  • String representation of a date
Time
  • Time
  • String representation of a time
Timestamp
  • Timestamp
  • String representation of a timestamp

More:

  • Subtracting Dates
  • Incrementing and Decrementing Dates
  • Subtracting Times
  • Incrementing and Decrementing Times
  • Subtracting Timestamps
  • Incrementing and Decrementing Timestamps
  • Examples: Date/Time Arithmetic
  • Subtracting Dates
  • Incrementing and Decrementing Dates
  • Subtracting Times
  • Incrementing and Decrementing Times
  • Subtracting Timestamps
  • Incrementing and Decrementing Timestamps
  • Examples: Date/Time Arithmetic
Parent topic: Functions Overview


Subtracting Dates

Restriction: This topic applies to Windows environments only.

In DB2 mode, when one date is subtracted from another, the result is a date duration that indicates the number of years, months and days. For example, the result of:

DATE('2/25/2000') - '12/20/1999'

is 205 (duration of 0 years, 2 months and 5 days). The data type of the result is DECIMAL(8,0).

The rules that apply to the date subtraction calculation are as follows:

  • If DATE1 is greater than or equal to DATE2, then DATE2 is subtracted from DATE1.
  • If DATE1 is less than DATE2, DATE1 is subtracted from DATE2 and the result is negative.

Using the operation RESULT = DATE1 - DATE2, these rules can be illustrated as follows:

If  DAY(DATE2) <= DAY(DATE1)
  Then  DAY(RESULT) = DAY(DATE1) - DAY(DATE2)
If DAY(DATE2) > DAY(DATE1)
  Then  DAY(RESULT) = N + DAY(DATE1) - DAY(DATE2)
  Where  N is the last day of MONTH(DATE2)
  MONTH(DATE2) is then incremented by 1
If MONTH(DATE2) <= MONTH(DATE1)
  Then  MONTH(RESULT) = MONTH(DATE1) - MONTH(DATE2)
If MONTH(DATE2) > MONTH(DATE1)
  Then  MONTH(RESULT) =
        12 + MONTH(DATE1) - MONTH(DATE2)
  And  YEAR(DATE2) is incremented by 1
YEAR(RESULT) = YEAR(DATE1) - YEAR(DATE2)
Parent topic: Date/Time Arithmetic


Incrementing and Decrementing Dates

Restriction: This topic applies to Windows environments only.

When adding durations to dates or subtracting durations from dates, the results are dates between January 1, 0001 and December 31, 9999.

  • Adding/Subtracting Years

    When a duration of years is added or subtracted, only the year portion of the date is affected (except for February 29). If the result of the calculation would be February 29 of a non-leap year, the day portion of the result is set to February twenty-eighth.

  • Adding/Subtracting Months

    When a duration of months is added or subtracted, the month is changed and if necessary, the year. The day portion of the date is changed only if the result would be an invalid date (such as September 31). In this case, the day is set to the last day of the month.

  • Adding/Subtracting Days

    When a duration of days is added or subtracted, the day will change and if necessary the month and year.

    Both positive and negative durations can be added or subtracted when working with date arithmetic. The sequence in which the date is incremented (or decremented) depends on the following:

    • When a positive date duration is added to a date or when a negative date duration is subtracted from a date, the date is incremented by the specified years, months and days in that order.

      For example, entering DATE1+x, where x is a positive decimal number, is equivalent to the expression:

      DATE1 + YEAR(x) YEARS + MONTH(x) MONTHS + DAY(x) DAYS
    • When a positive date duration is subtracted from a date or a negative date duration is added to a date, the date is decremented by the specified number of days, months and years in that order.

      For example, entering DATE1-x, where x is a positive decimal number, is equivalent to the expression:

      DATE1 - DAY(x) DAYS - MONTH(x) MONTHS - YEAR(x) YEARS
Parent topic: Date/Time Arithmetic


Subtracting Times

Restriction: This topic applies to Windows environments only.

In DB2 mode, when one time is subtracted from another, the result is a time duration that indicates the number of hours, minutes and seconds between the two times. For example, the result of:

TIME('10:22:16') - '00:34:46'

is 94730, (duration of 9 hours, 47 minutes and 30 seconds). The data type of the result is DECIMAL(6,0).

The rules that apply to the time subtraction calculation are as follows:

  • If TIME1 is greater than or equal to TIME2, then TIME2 is subtracted from TIME1.
  • If TIME1 is less than TIME2, TIME1 is subtracted from TIME2 and the result is negative.

Using the operation RESULT = TIME1 - TIME2, these rules can be illustrated as follows:

If  SECOND(TIME2) <= SECOND(TIME1)
  Then  SECOND(RESULT) =
    SECOND(TIME1) - SECOND(TIME2)
If SECOND(TIME2) > SECOND(TIME1)
  Then  SECOND(RESULT) =
    60 + SECOND(TIME1) - SECOND(TIME2)
  And  MINUTE(TIME2) is then incremented by 1
If MINUTE(TIME2) <= MINUTE(TIME1)
  Then  MINUTE(RESULT) =
    MINUTE(TIME1) - MINUTE(TIME2)
If MINUTE(TIME2) > MINUTE(TIME1)
  Then  MINUTE(RESULT) =
    60 + MINUTE(TIME1) - MINUTE(TIME2)
  And  HOUR(TIME2) is incremented by 1
HOUR(RESULT) = HOUR(TIME1) - HOUR(TIME2)
Parent topic: Date/Time Arithmetic


Incrementing and Decrementing Times

Restriction: This topic applies to Windows environments only.

When adding durations to times or subtracting durations from times, the results are always times. Overflow or underflow hours are discarded to ensure that the result is always a valid time.

When adding or subtracting hours, only the hours portion of the time is affected. Adding 24 hours to the time '00:00:00' results in the time '24:00:00' while adding 24 hours to any other time results in the same time (for example, adding 24 hours to the time '12:29:37' results in the time '12:29:37').

When adding or subtracting minutes, minutes are changed and if necessary, the hours are changed. The seconds do not change.

When adding or subtracting seconds, seconds are changed and if necessary, the minutes and hours are changed.

Both positive and negative time durations can be added or subtracted. The result is a time that has been incremented (or decremented) by the specified number of hours, minutes and seconds in that order. For example, entering TIME1+x, where x is a positive decimal number, is equivalent to the expression:

TIME1 + HOUR(x)HOURS + MINUTE(x)MINUTES
  + SECOND(x)SECONDS
Parent topic: Date/Time Arithmetic


Subtracting Timestamps

Restriction: This topic applies to Windows environments only.

In DB2 mode and XDB mode, when one timestamp is subtracted from another, the result is a timestamp duration that indicates the number of years, months, days, hours, minutes, and seconds. The data type of the result is DECIMAL(20).

The rules that apply to timestamp subtraction are as follows:

  • If TIMESTAMP1 is greater than or equal to TIMESTAMP2, then TIMESTAMP2 is subtracted from TIMESTAMP1.
  • If TIMESTAMP1 is less than TIMESTAMP2, TIMESTAMP1 is subtracted from TIMESTAMP2 and the result is negative.

Using the operation RESULT = TS1 - TS2, these rules can be illustrated as follows:

If  MICROSECOND(TS2) <= MICROSECOND(TS1)
  Then  MICROSECOND(RESULT) = MICROSECOND(TS1) -
      MICROSECOND(TS2)
If  MICROSECOND(TS2) > MICROSECOND(TS1)
  Then  MICROSECOND(RESULT) = 1000000 +
      MICROSECOND(TS1) - MICROSECOND(TS2)
  And  SECOND(TS2) is incremented by 1
Note:

The rules for subtracting times determine how the time portions of the timestamps are subtracted.

If  HOUR(TS2) <= HOUR(TS1)
  Then  HOUR(RESULT) = HOUR(TS1) - HOUR(TS2)
If  HOUR(TS2) > HOUR(TS1)
  Then  HOUR(RESULT) = 24 + HOUR(TS1) - HOUR(TS2)
  And  DAY(TS2) is incremented by 1
Note:

The rules for subtracting dates determine how the date portions of the timestamps are subtracted.

Parent topic: Date/Time Arithmetic


Incrementing and Decrementing Timestamps

Restriction: This topic applies to Windows environments only.

Adding a duration to a timestamp or subtracting a duration from a timestamp returns a timestamp -- while subtracting a timestamp from a timestamp returns a timestamp duration. An overflow or underflow of hours is carried into the date portion of the result.

Parent topic: Date/Time Arithmetic


Examples: Date/Time Arithmetic

Restriction: This topic applies to Windows environments only.

The examples appearing below reference a table called tasks created with the following command:

CREATE TABLE tasks(task_no SMALLINT, task_name CHAR(10),
  est_hrs_reqd SMALLINT, startdate DATE, enddate
  DATE,starttime TIME, endtime TIME, audit_time
  TIMESTAMP)

date1-date2

In XDB mode, this expression calculates the difference in days between the two dates date1 and date2 (in DB2 mode, subtraction of two dates results in a date duration). As an example (using the TUTORIAL tables), the query below finds the number of orders placed for part P2 during the past 30 days:

SELECT SUM(quantity)
  FROM orders, items
  WHERE TODAY - o_date < 30

time1-time2

In XDB mode, this expression calculates the difference in seconds between the two times time1 and time2. To find the number of minutes, divide the difference between times by 60. To find the number of hours, divide the difference between times by 3600. For example, to find the total number of hours elapsed between the two stored time values starttime and endtime, you could use the query:

SELECT (endtime-starttime)/3600
FROM tasks
Note:

In DB2 mode the difference between two dates or times is expressed in Date/Time Duration values -- consisting of years/months/days or hours/minutes/seconds.

timestamp1-timestamp2

In XDB mode and DB2 mode, this expression calculates the difference between the two timestamps timestamp1 and timestamp2. This difference is expressed as a timestamp duration, where the format yyyyxxddhhmmsszzzzzz defines the years (yyyy), months (xx), days (dd), hours (hh), minutes (mm), seconds (ss), and microseconds (zzzzzz) of the timestamp duration.

time1 + n

In XDB mode, calculates the time generated by adding n seconds to time time1. The parameter n can be any expression that evaluates to a number. To add minutes to a time, multiply the number of minutes by 60. To add hours to a time, multiply the number of hours by 3600. For example, to find out what the estimated end time will be, given an estimated task time in hours, you could use the query:

SELECT "Estimated hours to completion: ",
  starttime + (est_hrs_reqd * )
FROM tasks
Note:

In DB2 mode, you must specify the duration type. For example, n SECONDS, n HOURS, and so on.

Parent topic: Date/Time Arithmetic


Numeric Functions

Restriction: This topic applies to Windows environments only.

These functions can be used any place a numeric value is required. The parameters x and y can be any expression that evaluates to a number. Money fields can only be used in the FLOAT, INTEGER or XABS functions.

The operators +, -, /, and * are also available. In DB2 mode, integer division (/) results in an integer with decimal places truncated.

Note: DB2 truncates expression results. The XDB Server rounds. For example, if result type is 5,2 and expression value is 123.555, DB2 mode retrieves 123.55 while XDB mode retrieves 123.56.

More:

  • CEILING
  • DECIMAL
  • FACTORIAL
  • FLOAT
  • FLOOR
  • INTEGER
  • MOD
  • PI
  • ROUND
  • SIGN
  • TRUNCATE
  • XABS
  • XEXP
  • XLN
  • XLOG
  • XPOWER
  • XSQRT
  • CEILING
  • DECIMAL
  • FACTORIAL
  • FLOAT
  • FLOOR
  • INTEGER
  • MOD
  • PI
  • ROUND
  • SIGN
  • TRUNCATE
  • XABS
  • XEXP
  • XLN
  • XLOG
  • XPOWER
  • XSQRT
Parent topic: Functions Overview


CEILING

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the smallest integer greater than or equal to expr. The format appears below:

CEILING(expr)

For example:

CEILING(12.25) = 13
CEILING(12) = 12
Parent topic: Numeric Functions


DECIMAL

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Transforms a number to the decimal representation of the numeric value having a specified precision and scale. The format appears below:

DECIMAL(x [, precision [, scale]])

The parameter precision, if specified, must be between 1 and 31, inclusive. If precision is omitted, the default precision depends on the data type of the first argument. If x is a floating point number or decimal, the default precision is 15. If the parameter x is an integer the default precision is 11. If x is a small integer, the default precision is 5. The parameter scale, if specified, must be in the range of 0 to precision. If omitted, scale is assumed to be 0. For example:

SELECT DECIMAL(quantity, 5, 2)
FROM items
Parent topic: Numeric Functions


FACTORIAL

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the value of expr factorial. The format appears below:

FACTORIAL(expr)

The value of the parameter expr must be greater than or equal to 0 and less than or equal to 167. For example:

FACTORIAL(6) = 720
Parent topic: Numeric Functions


FLOAT

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Converts a number into the floating point representation of the number, as if the value were assigned to a FLOAT field. The format appears below:

FLOAT(x)

In DB2 compatibility mode, the parameter x cannot be a string. In XDB mode, x can be a string.

Parent topic: Numeric Functions


FLOOR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the largest integer less than or equal to the value of expr. The format appears below:

FLOOR(expr)

For example:

FLOOR(12.25) = 12
FLOOR(12) = 12
Parent topic: Numeric Functions


INTEGER

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Converts a number into an integer value, in the same way that the value would be converted if assigned to an INTEGER field. The format appears below:

INTEGER(x)

In DB2 compatibility mode, the parameter x cannot be a string. In XDB mode, x can be a string.

Parent topic: Numeric Functions


MOD

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the remainder of expr1/expr2. The format appears below:

MOD(expr1,expr2)

For example:

MOD(10,4) = 2
MOD(2,10) = 2
Parent topic: Numeric Functions


PI

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns an approximation of the value of Pi. For example:

PI() = 3.1415926535897936
Parent topic: Numeric Functions


ROUND

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Rounds expr1 to the precision specified in int_expr. The format appears below:

ROUND(expr1,int_expr)

Can also round to negative numbers. For example:

ROUND(549.55,1) = 549.6
ROUND(549.55,-1) = 550.00
ROUND(549.55,-2) = 600.00
Parent topic: Numeric Functions


SIGN

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the sign of the parameter expr. The format appears below:

SIGN(expr)

A value of one is returned if expr is positive, and a value of zero is returned if expr is zero, and -1 is returned if expr is negative. For example:

SIGN(-234.4) = -1
SIGN(234) = 1
SIGN(0) = 0
Parent topic: Numeric Functions


TRUNCATE

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Truncates expr1 to the precision specified in int_expr. The format appears below:

TRUNCATE(expr, int_expr)

Can truncate to negative decimals. For example:

TRUNCATE(549.55,1) = 549.5
TRUNCATE(549.55,-1) = 540.00
TRUNCATE(549.55,-2) = 500
Parent topic: Numeric Functions


XABS

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Calculates the absolute value of parameter x. The format appears below:

XABS(x)
Parent topic: Numeric Functions


XEXP

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the exponential function of parameter x (for example, eE+x). The format appears below:

XEXP(x)
Parent topic: Numeric Functions


XLN

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the natural log of parameter x. The format appears below:

XLN(x)
Parent topic: Numeric Functions


XLOG

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds base 10 logarithm of parameter x. The format appears below:

XLOG(x)
Parent topic: Numeric Functions


XPOWER

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the value of parameter x raised to the power of parameter y. The format appears below:

XPOWER(x, y)
Parent topic: Numeric Functions


XSQRT

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the square root of parameter x. The format appears below:

XSQRT(x)
Parent topic: Numeric Functions


String Functions

Restriction: This topic applies to Windows environments only.

A string can consist of any combination of letters, digits or special characters contained in the standard ASCII character set. String functions can return string values from arguments consisting of other data types or manipulate combinations of existing string arguments to return another string value.

More:

  • ASCII
  • CHAR
  • CHR
  • DIGITS
  • FINDANY
  • FINDNOTIN
  • FINDSTR
  • HEX
  • INITCAP
  • LENGTH
  • LTRIM
  • NULLIF
  • REPLICATE
  • REVCHAR
  • RTRIM
  • STRIP
  • SUBSTR
  • VALUE
  • XCONCAT
  • XLEFT
  • XLOWER
  • XRIGHT
  • XTRIM
  • XUPPER
  • ASCII
  • CHAR
  • CHR
  • DIGITS
  • FINDANY
  • FINDNOTIN
  • FINDSTR
  • HEX
  • INITCAP
  • LENGTH
  • LTRIM
  • NULLIF
  • REPLICATE
  • REVCHAR
  • RTRIM
  • STRIP
  • SUBSTR
  • VALUE
  • XCONCAT
  • XLEFT
  • XLOWER
  • XRIGHT
  • XTRIM
  • XUPPER
Parent topic: Functions Overview


ASCII

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Returns the ASCII code value of the leftmost character of char_expr. The format appears below:

ASCII(char_expr)

For example:

ASCII("XDB") = 88
Parent topic: String Functions


CHAR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Transforms date, time or timestamp value into a character string. The format appears below:

CHAR([x [, format]])

If present, x must evaluate to a date, time or timestamp value. If x is null, the result is null. The parameter format is a string format for date or time, as shown in the table below. If omitted, the system default format is used. The format parameter cannot be specified if x is a timestamp.

Format | Name | Date Format | Time Format
ISO | International Standards Organization Standard | yyyy-mm-dd | hh.mm.ss
USA | IBM USA Standard | mm/dd/yyyy | hh:mm AM or PM
EUR | IBM European Standard | dd.mm.yyyy | hh.mm.ss
JIS | Japanese Industrial Standard Christian Era | yyyy-mm-dd | hh.mm.ss
LOCAL | Configured through the Options Utility. | User Defined | User Defined

Examples are:

CHAR(birth_date, USA)
CHAR(airtime, ISO)
CHAR(auditstamp)
Parent topic: String Functions


CHR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Converts an ASCII code into a character (ASCII code values must be between 0 and 255). The format appears below:

CHR(int_expr)

For example:

CHR(81) = "Q"
Parent topic: String Functions


DIGITS

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Returns a string representation of a number, without decimal points. The x parameter must be an integer or decimal number. The format appears below:

DIGITS(x)

In DB2 compatibility mode, the result is unsigned and padded with leading zeroes so that the string length is 5 if the argument is a small integer, 10 if the argument is an integer, or p if the argument is a decimal number with precision p. In XDB mode the result is a variable length string and may include a sign. An example of the use of DIGITS is:

SELECT DIGITS(o_no)
FROM orders
Parent topic: String Functions


FINDANY

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Searches for any of the characters specified by charexpr2 in charexpr1 and returns the offset from the beginning where the first occurrence is found. The format appears below:

FINDANY(charexpr1, charexpr2)

For example:

FINDANY("abcdef","zd") = 4

because "d" is found at the fourth character. A return value of zero signifies not found.

Parent topic: String Functions


FINDNOTIN

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Finds the offset of the first character in charexpr1 that is not in charexpr2. The format appears below:

FINDNOTIN(charexpr1, charexpr2)

For example:

FINDNOTIN("abdblm","dba") = 5

because "l" is the first character not in the "dba" set. A return value of zero indicates all characters are in the string.

Parent topic: String Functions


FINDSTR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Searches for charexpr2 in charexpr1 and returns the offset from beginning of string when found. The format appears below:

FINDSTR(charexpr1, charexpr2)

For example:

FINDSTR("abcdef", "cd") = 3

A return value of zero means not found, 1 is the first character, etc.

Parent topic: String Functions


HEX

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Returns a string that is the hexadecimal representation of x, where the parameter value x can be any value other than a long string. The format appears below:

HEX(x)

The result is a string of hexadecimal digits, with each consecutive pair of digits representing a byte of the argument, so that the length is twice the length of the argument. In DB2 compatibility mode, bytes are swapped for smallint, integer and date fields. In XDB mode, PC Intel format is used for smallint, int and date fields.

If the location sort sequence is EBCDIC, character fields display in HEX based upon the EBCDIC code page. Also, performing a HEX function on a date field in DB2 mode shows the result as if stored in DB2 format instead of XDB mode format. DB2 format is 4 packed decimal bytes with the year in the first two, the month in the next one, and the day in the next one. For example, the value 19900101 would be displayed if the HEX function was applied to date 01/01/1990.

Parent topic: String Functions


INITCAP

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Capitalizes the first character of each word and makes the rest of each word lower case. The format appears below:

INITCAP(charexpr)

For example:

INITCAP("xdb SYSTEMS") = "Xdb Systems"
Parent topic: String Functions


LENGTH

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Finds the length of x, where x is any field value. XDB mode recognizes either LENGTH or XLENGTH, while DB2 mode only recognizes LENGTH. The format appears below:

LENGTH(x)

The character count returned depends on the compatibility setting in effect at the time the data value was inserted into the table -- not your current compatibility setting. For example, if you inserted the field value when in DB2 mode, the LENGTH function includes trailing blanks in the character count (up to the length of the column). If you inserted the field value when in XDB mode, the LENGTH function does not count trailing blanks.

For example, if the lname column values were inserted while in XDB mode, the following query produces the result shown:

SELECT lname, LENGTH(lname)
FROM employee
lname

length(lname)
Kerin | 5
Wilson | 6
Crisp | 5
Hopkins | 7
Parent topic: String Functions


LTRIM

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Trims leading spaces. The format appears below:

LTRIM(charexpr)

For example:

LTRIM("   XDB") = "XDB"
Parent topic: String Functions


NULLIF

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
X | X |  | X

Use the NULLIF function wherever an expression is used to return null if the two arguments are equal; otherwise, the value of the first argument is returned. The two arguments must be compatible. The attributes of the result are the attributes of the first argument.

For example, if the result of the first argument is a character string, the result of the other must also be a character string; if the result of the first argument is a number, the result of the other must also be a number.

The format of the NULLIF function appears below:

NULLIF (expression,expression)

where:

expression Specifies a single value.
Parent topic: String Functions


REPLICATE

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Repeats charexpr for integer number of times. The format appears below:

REPLICATE(charexpr,integer)

For example:

REPLICATE("*",10) = "**********"
Parent topic: String Functions


REVCHAR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Reverses the order of characters in charexpr. The format appears below:

REVCHAR(charexpr)

For example:

REVCHAR("abc") = "cba"

Data returned are character data.

Parent topic: String Functions


RTRIM

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Trims trailing spaces. The format appears below:

RTRIM(charexpr)

For example:

RTRIM("XDB   ") = "XDB"
Parent topic: String Functions


STRIP

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X | X | X

Use the STRIP function to remove blanks or another specified character from the end, beginning, or both ends of a string expression. The format appears below:

STRIP (expression [,BOTH [,strip-character]|,LEADING |,TRAILING])

where:

expression | A string expression.
strip-character | A single character constant that indicates the character that is to be removed.
Parent topic: String Functions


SUBSTR

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

Extracts n characters from x, beginning with the mth character (also written XMID in XDB mode). The format appears below:

SUBSTR(x, m [,n])

The parameter x is any expression that evaluates to a string. The parameter m is a positive integer indicating the offset from the beginning of the string, and the parameter n is a positive integer indicating the number of characters to extract. If two arguments are specified, the implicit length is LENGTH(x)-m+1 for fixed length fields or the larger of 0 or LENGTH(x)-m+1 for varying length fields. If x is null, the result is null.

For example, suppose the serial number for a deluxe widget is SW1234-4356, where the first two characters indicate the department that made it, the next 4 the model, and the rest the specific unit from the lot. To find the model number "1234" for deluxe widgets:

SELECT SUBSTR(serial_no, 3, 4)
  FROM products
  WHERE description = "Deluxe Widget"
Parent topic: String Functions


VALUE

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 | X |  | X

If x is evaluated as null, VALUE returns the value of the first non-null y. The format appears below:

VALUE(x, y1 [,...yn])

For example, in the query below, the column named COM is null for some employees; the desired value is then the employee's payrate or, failing that, simply the value 10. For example:

SELECT e_no, VALUE(com * $300, payrate, $10)
  FROM employee
  WHERE st = "VA"
e_no

column2
2 | $17.50
4 | $17.50
7 | $9.00
9 | $17.00
Parent topic: String Functions


XCONCAT

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

String concatenation can be performed using the XCONCAT function (concatenation can also be performed with the "||" operator). The format appears below:

XCONCAT(expres1, expres2)

The parameters expres1 and expres2 are expressions that evaluate two strings to be concatenated.

Parent topic: String Functions


XLEFT

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Extracts the n leftmost characters from a string. The format appears below:

XLEFT(x, n)

The parameter x is any expression that evaluates to a character string, and the parameter n is a positive integer indicating the number of characters to extract. For example, suppose you want to extract the area code from all customer phone numbers, you can use the query:

SELECT company, XLEFT(phone, 3)
FROM customer

If n is longer than the string extracted, the string is right padded with spaces until it is n characters long.

For example:

SELECT XLEFT(color, 10)||pname
FROM part
Column1

RED | NUT
GREEN | BOLT
BLUE | CAM
RED | SCREW
BLUE | CAM
RED | COG
Parent topic: String Functions


XLOWER

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Converts a character string to lower case. The parameter x is any expression that evaluates to a character string. The format appears below:

XLOWER(x)

For example:

SELECT XLOWER(lname)
  FROM employee
  WHERE st = "VA"
xlower(lname)
kerin
wilson
crisp
hopkins
Parent topic: String Functions


XRIGHT

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Extracts the last n characters from x. The format appears below:

XRIGHT(x, n)

The parameter x is any expression that evaluates to a character string and the parameter n is a positive integer indicating the number of characters to extract. For example, the following query retrieves phone numbers without the area codes:

SELECT XRIGHT(phone, 8)
FROM customer

If the value of n is longer than the string extracted, the string will be padded on the left with spaces until it is n characters long. For example, to right justify character strings, use a query like:

SELECT XRIGHT(pname, 14)
FROM part
column1
NUT
BOLT
CAM
SCREW
CAM
COG
Parent topic: String Functions


XTRIM

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Trims trailing spaces from a character string. The format appears below:

XTRIM(x)

The parameter x is any expression that evaluates to a character string. For example:

SELECT XTRIM(lname)
FROM employee
Parent topic: String Functions


XUPPER

Restriction: This topic applies to Windows environments only.
ANSI | DB2 | SQL/DS | XDB
 |  |  | X

Converts a character string to upper case. The format appears below:

XUPPER(x)

The parameter x is any expression that evaluates into a character string. For example:

SELECT XUPPER(lname)
  FROM employee
  WHERE st = "VA"
xupper(lname)
KERIN
WILSON
CRISP
HOPKINS
Parent topic: String Functions


System Table Overview

Restriction: This topic applies to Windows environments only.

To view the contents of any system table, use the SQL SELECT command as follows:

SELECT * FROM authid.table-name

where authid is the owner of the table. The AuthID for system tables is either sysxdb, sysibm or xdbstat.

Only a super user has authority to edit (update) the system tables. A user with sysadm authority can edit selected columns in some of the tables within the authorized location. These sysadm-editable columns are so noted in the column descriptions.

All locations, including the system location, contain a set of system catalog tables. These are stored in the dsndb06 database in each location. Additional system tables reside in the xdbacf and dsnddf databases in the system location.

Important: For complete information on system tables, see the documentation for DB2 catalog tables located on the IBM Web site.
Parent topic: SQL Reference


Overview of XDB Server Specifications

Restriction: This topic applies to Windows environments only.

The tables in this topic show the limits imposed by the XDB Server while in XDB mode. (See also Data Types in Basic Concepts) Some XDB Server tools and utilities may have further restrictions, which are described in the applicable documentation.

More:

  • Maximum Identifier Lengths (in bytes)
  • Maximum String Length Limits
  • Date and Time Values
  • Numeric Limits
  • System and Operational Limits
  • Maximum Identifier Lengths (in bytes)
  • Maximum String Length Limits
  • Date and Time Values
  • Numeric Limits
  • System and Operational Limits
Parent topic: SQL Reference


Maximum Identifier Lengths (in bytes)

Restriction: This topic applies to Windows environments only.
Item | Limit
Alias Name | 18
AuthID | 8
Collection ID | 18
Column Name | 18
Correlation Name | 18
Cursor Name | 18
Database Name | 8
Index Name | 18
Location Name | 16
Procedure Name | 18
Referential Constraint Name | 8
Statement Name | 18
Storage Group (stogroup) Name | 8
Synonym Name | 18
Table Name | 18
Table Space Name | 8
View Name | 18
Parent topic: Overview of XDB Server Specifications


Maximum String Length Limits

Restriction: This topic applies to Windows environments only.
Item | Limit
Maximum length of a CHAR field (bytes) | 4,056
Maximum length of a VARCHAR field (bytes) | 32,706
Maximum length of a LONGVARchar field (bytes) | 32,706
Maximum length of a GRAPHIC field | 127
Maximum length of a VARGraphic field | 16,353
Maximum length of a LONGVARGraphic field | 16,353
Parent topic: Overview of XDB Server Specifications


Date and Time Values

Restriction: This topic applies to Windows environments only.
Item | Limit
Smallest DATE Value (shown in ISO format) | 0001-01-01
Largest DATE value (shown in ISO format) | 9999-12-31
Smallest TIME value (shown in ISO format) | 00.00.00
Largest TIME value (shown in ISO format) | 24.00.00
Smallest TIMESTAMP value | 0001-01-01-00.00.00.000000
Largest TIMESTAMP value | 9999-12-31-24.00.00.000000
Parent topic: Overview of XDB Server Specifications


Numeric Limits

Restriction: This topic applies to Windows environments only.
Item | Limit
Smallest SMALLINT value | -32,768
Largest SMALLINT value | 32,767
Smallest INTEGER value | -2,147,483,648
Largest INTEGER value | 2,147,483,647
Smallest DECIMAL value | 1-10E+31
Largest DECIMAL value | 10E+31-1
Largest decimal precision | 31
Smallest 4-byte float value | 1.2E-38
Largest 4-byte float value | 3.4E+38
Smallest 8-byte float value | 2.2E-308
Largest 8-byte float value | 1.8E+308
Largest money value | $10E+12
Smallest money value | -$10E+12
Parent topic: Overview of XDB Server Specifications


System and Operational Limits

Restriction: This topic applies to Windows environments only.
Item | Limit
Maximum number of columns in a table or view | 750
Maximum record length (in bytes) (See note 1.) | 32,767
Maximum number of volume IDs in a storage group | 133
Maximum number of queries open at one time | 50 per user
Maximum length of an SQL statement | 32,767
Maximum projected columns in a SELECT list | 750
Maximum UNION operators in a SELECT statement | 32
Maximum number of predicates in a WHERE or HAVING clause | No Limit
Maximum number of columns in a GROUP BY clause | 750
Maximum number of columns in an ORDER BY clause | 750
Maximum number of tables in a FROM clause (number of tables per JOIN) | 15
Maximum bytes in a compound index | 203
Maximum index field length (in bytes) (See note 2.) | 4056
Maximum number of indexes per table | No limit
Maximum number of columns in an index key | 64
Maximum number of records per table | 2 billion +
Maximum number of databases (See note 3.) | No limit
Maximum number of locations open at a time (single user) | 10
Maximum nested query levels | Limited only by system storage
Maximum queries per level | Limited only by system storage
Maximum recursion levels for PREVIOUS function with index (no limit without index) | 20
Maximum sort fields | 750
Maximum number of elements in a SELECT list | 750

Table Notes:

  1. Including 2 byte record overhead plus 1 byte overhead for odd length character fields and 2 byte overhead for other field types.
  2. Only the first 254 characters of a field are actually used in creating the index.
  3. Limited by storage space and operating system.
Parent topic: Overview of XDB Server Specifications


XDB Server Reserved Words

Restriction: This topic applies to Windows environments only.

This topic lists reserved words or keywords used by the XDB Server and utilities. Other words which may become reserved are listed as well.

XDB Server SQL reserved words should not be used as object (for example, locations, databases, tables, indexes, columns) names. Some XDB Server tools and utilities may place other restrictions on database object names. In general, XDB Server reserved words are not case sensitive.

More:

  • Reserved Words: DB2 Mode
  • Reserved Words: DB2 Mode
  • Reserved Words: XDB Mode
  • Future Reserved Words
Parent topic: SQL Reference


Reserved Words: DB2 Mode

Restriction: This topic applies to Windows environments only.

These words are reserved if you are running in DB2 Mode.

add | delete | grant | obid | stogroup
all | descriptor | group | of | synonym
alter | distinct |  | on |
and | drop | having | optimize | table
any |  |  | or | tablespace
as | editproc | immediate | order | to
audit | end-exec | in |  |
 | erase | index | package | union
between | escape | insert | part | update
bufferpool | except | into | plan | user
by | execute | is | priqty | using
 | exists |  | privileges |
cluster |  | key | program | validproc
collection | fetch |  |  | values
column | fieldproc | like | row | vcat
concat | for | locksize |  | view
count | from |  | secqty | volumes
current |  | not | select |
cursor | go | null | set | where
 | goto | numparts | some | with
database |  |  |  |
Parent topic: XDB Server Reserved Words


Reserved Words: XDB Mode

Restriction: This topic applies to Windows environments only.

These words are reserved if you are running in XDB Mode.

add | distinct | key | select | where
all | double |  | set | with
alter | drop | level | some |
and |  | like | sounds | xabs
any | editproc |  | stogroup | xconcat
as | erase | modify | synonym | xdate
audit | escape | money |  | xday
 | except |  | table | xexp
between | exists | not | tablespace | xleft
bottom |  | null | to | xlength
bufferpool | fetch |  | today | xln
by | fieldproc | of |  | xlog
 | for | on | undelete | xlower
cluster | from | or | union | xmid
coalesce |  | order | unique | xmonth
collection | grant |  | unlock | xpower
column | group | package | update | xright
concat |  | previous | user | xsqrt
connect | having | priqty | using | xstddev
count | host | privileges |  | xtime
current |  | program | validproc | xtimestamp
 | in |  | values | xtoday
database | index | rename | variable | xtrim
datetime | insert | row | vcat | xupper
delete | into |  | view | xvar
directories | is | secqty | volumes | xyear
Parent topic: XDB Server Reserved Words


Future Reserved Words

Restriction: This topic applies to Windows environments only.

The following words are IBM or ANSI SQL reserved words (or possible SQL future reserved words) that are not reserved by the XDB Server. We recommend you avoid the use of these for object names.

applpath | tmppath
dbpath | xdbpath
sysdbpath |

In addition, note that XDB Server extensions will generally use keywords that begin with the letter X. It is therefore recommended that you avoid names beginning with X.

Parent topic: XDB Server Reserved Words


SQL Communications Area (SQLCA)

Restriction: This topic applies to Windows environments only.

The SQL Communications Area (SQLCA) is a data area used to store information on the execution of SQL commands. The SQLCA is used as a diagnostic tool to determine whether an SQL statement executed correctly. The SQLCA is updated after each SQL statement is executed.

  • SQLCA Description
  • SQLCA Structure For COBOL
  • SQLCA Structure For C
  • SQLCA Structure For PL/I
Parent topic: SQL Reference
Related information
SQLCA Description
SQLCA Structure For COBOL
SQLCA Structure For C
SQLCA Structure For PL/I


SQLCA Description

Restriction: This topic applies to Windows environments only.

The SQLCA is described in the following table, including the field names used in each language, the data type, and a discussion of the purpose of each field.

COBOL Name | C Name | Data Type | Purpose
SQLCAID | sqlcaid | char(8) | A character string (SQLCA) that identifies the beginning of the SQLCA.
SQLCABC | sqlcabc | integer | Specifies the length of the SQLCA. Value is always 136.
SQLCODE | sqlcode | integer | Contains a return code pertaining to the most recent SQL statement executed. Important values are: 0 Statement executed successfully (may have had warnings). >0 Executed successfully but with an exception condition. <0 An error occurred. 100 End of data reached.
SQLERRML | sqlerrml | smallint | The length of the SQLERRMC string (0 to 70). If 0, the value of SQLERRMC is not pertinent.
SQLERRMC | sqlerrmc | varchar (70) | One or more tokens, separated by x'ff', that are substituted into error messages to provide specific information about an error condition.
SQLERRP | sqlerrp | char(8) | Indicates the product signature in the format pppvvrrm where: ppp = XDB vv = XDB version number rr = XDB release number m = Operating system: N = NT O = OS/2 D = DOS
SQLERRD(1) | sqlerrd[0] | integer | Reserved for internal use.
SQLERRD(2) | sqlerrd[1] | integer | Reserved for internal use.
SQLERRD(3) | sqlerrd[2] | integer | Number of rows affected by an INSERT, UPDATE or DELETE command.
SQLERRD(4) | sqlerrd[3] | integer | Not used by XDB Server.
SQLERRD(5) | sqlerrd[4] | integer | Contains the position or column of a syntax error for a PREPARE or EXECUTE IMMEDIATE statement.
SQLERRD(6) | sqlerrd[5] | integer | Not used by XDB Server.
SQLWARN0 | sqlwarn0 | char(1) | Flag used to signal warning condition. If blank, then all other SQLWARN variables are blank. If value is W, then at least one other SQLWARN has a W.
SQLWARN1 | sqlwarn1 | char(1) | If value is W, then at least one column's value was truncated when stored in a host variable.
SQLWARN2 | sqlwarn2 | char(1) | If value is W, then at least one null value was eliminated from the argument of a column function. May not be set to W for a MIN function because its results are not dependent on the elimination of null values.
SQLWARN3 | sqlwarn3 | char(1) | If value is W, then the number of columns is larger than the number of host variables. Contains Z if fewer locators were provided in the ASSOCIATE LOCATORS statement than the stored procedure returned.
SQLWARN4 | sqlwarn4 | char(1) | If value is W, then a prepared UPDATE or DELETE statement does not contain a WHERE clause.
SQLWARN5 | sqlwarn5 | char(1) | If value is W, your program tried to create an index that contains a field that exceeds the maximum length for an index. This use is XDB Server-specific.
SQLWARN6 | sqlwarn6 | char(1) | Not used by XDB Server.
SQLWARN7 | sqlwarn7 | char(1) | Not used by XDB Server.
SQLWARN8 | sqlwarn8 | char(1) | Not used by XDB Server.
SQLWARN9 | sqlwarn9 | char(1) | Contains Z if the stored procedure returned multiple result sets.
SQLWARNA | sqlwarna | char(1) | Not used by XDB Server.
SQLSTATE | sqlstate | char(5) | Contains SQLSTATE value for this error.
Parent topic: SQL Communications Area (SQLCA)


SQLCA Structure For COBOL

Restriction: This topic applies to Windows environments only.

The structure of the SQLCA is defined in the copybook sqlca.cpy. It must be included in every COBOL program that contains embedded SQL.

The SQLCA structure for COBOL is as follows:

 01 SQLCA.
     05  SQLCAID         PIC X(8)         VALUE "SQLCA   ".
     05  SQLCABC         PIC S9(9) COMP-5 VALUE 136.
     05  SQLCODE         PIC S9(9) COMP-5 VALUE 0.
     05  SQLERRM.
         49  SQLERRML    PIC S9(4) COMP-5.
         49  SQLERRMC    PIC X(70).
     05  SQLERRP         PIC X(8).
     05  SQLERRD         PIC S9(9) COMP-5 OCCURS 6 VALUE 0.
     05  SQLWARN.
         10  SQLWARN0    PIC X.
         10  SQLWARN1    PIC X.
         10  SQLWARN2    PIC X.
         10  SQLWARN3    PIC X.
         10  SQLWARN4    PIC X.
         10  SQLWARN5    PIC X.
         10  SQLWARN6    PIC X.
         10  SQLWARN7    PIC X.
         10  SQLWARN8    PIC X.
         10  SQLWARN9    PIC X.
         10  SQLWARN10   PIC X.
         10  SQLWARNA    PIC X REDEFINES SQLWARN10.
     05  SQLSTATE    PIC X(5).
Parent topic: SQL Communications Area (SQLCA)


SQLCA Structure For C

Restriction: This topic applies to Windows environments only.

The structure of the SQLCA is defined in the include file SQLCA.H. It must be included in every C program that contains embedded SQL.

#ifndef SQLCODE
struct sqlca
{
  unsigned char  sqlcaid[8];
  long      sqlcabc;
  long      sqlcode;
  short      sqlerrml;
  unsigned char  sqlerrmc[70];
  unsigned char  sqlerrp[8];
  long      sqlerrd[6];
  unsigned char  sqlwarn[11];
  unsigned char  sqlstate[5];
};
#define SQLCODE  sqlca.sqlcode
#define SQLWARN0  sqlca.sqlwarn[0]
#define SQLWARN1  sqlca.sqlwarn[1]
#define SQLWARN2  sqlca.sqlwarn[2]
#define SQLWARN3  sqlca.sqlwarn[3]
#define SQLWARN4  sqlca.sqlwarn[4]
#define SQLWARN5  sqlca.sqlwarn[5]
#define SQLWARN6  sqlca.sqlwarn[6]
#define SQLWARN7  sqlca.sqlwarn[7]
#define SQLWARN8  sqlca.sqlwarn[8]
#define SQLWARN9  sqlca.sqlwarn[9]
#define SQLWARNA  sqlca.sqlwarn[10]
#define SQLSTATE  sqlca.sqlstate
#endif
struct sqlca sqlca;
Parent topic: SQL Communications Area (SQLCA)


SQLCA Structure For PL/I

Restriction: This topic applies to Windows environments only.

The SQLCA structure for PL/I is as follows:

dcl
   1 sqlca,
     2 sqlcaid    char(8),
     2 sqlcabc    fixed bin(31),
     2 sqlcode    fixed bin(31),
     2 sqlerrm    char(70) varying,
     2 sqlerrp    char(8),
     2 sqlerrd(6) fixed bin(31),
     2 sqlwarn,
       3 sqlwarn0 char(1),
       3 sqlwarn1 char(1),
       3 sqlwarn2 char(1),
       3 sqlwarn3 char(1),
       3 sqlwarn4 char(1),
       3 sqlwarn5 char(1),
       3 sqlwarn6 char(1),
       3 sqlwarn7 char(1),
     2 sqlext,
       3 sqlwarn8 char(1),
       3 sqlwarn9 char(1),
       3 sqlwarna char(1),
       3 sqlstate char(5);
Parent topic: SQL Communications Area (SQLCA)


SQL Descriptor Area (SQLDA)

Restriction: This topic applies to Windows environments only.

The SQL Descriptor Area (SQLDA) is a data area that holds information about dynamic SQL commands. An SQLDA might be used in a DESCRIBE statement to find out information about columns returned by a query, and then reused for a FETCH statement when the values are actually selected.

The SQLDA consists of four variables, followed by a variable number of SQLVAR structures. SQLVAR structures describe columns if OPEN, FETCH or EXECUTE statements are involved. For DESCRIBE and PREPARE statements, the SQLVAR structures describe host variables.

This topic provides descriptions of the information provided in the SQLDA and shows the structure for COBOL (all platforms), PL/I (Windows) and C (Windows).

More:

  • SQLDA Elements
  • SQLVAR Elements
  • SQLDA Structure For COBOL
  • SQLDA Elements
  • SQLVAR Elements
  • SQLTYPE Values
  • SQLLEN Values
  • SQLDA Structure For COBOL
  • SQLDA Structure For C
  • SQLDA Structure For PL/I
Parent topic: SQL Reference


SQLDA Elements

Restriction: This topic applies to Windows environments only.

The SQLDA consists of the four elements shown in the table below, followed by the number of SQLVAR structures specified in SQLN.

Each occurrence of SQLVAR describes a column (for DESCRIBE and PREPARE statements) or host variable (for OPEN, FETCH and EXECUTE statements), depending on the type of statement being executed. The number of SQLVAR elements appearing in the SQLDA is defined by the SQLN element of SQLDA, thus the SQLDA structure is variable length. The SQLVAR structure is shown in the following table.

COBOL Name | C Name | PL/I Name | Data Type | Usage in DESCRIBE and PREPARE INTO | Usage in FETCH, OPEN or EXECUTE
SQLDAID | sqldaid | sqldaid | char(8) | The character string (SQLDA) that identifies the beginning of the SQLDA structure. | Same.
SQLDABC | sqlabc | sqlabc | integer | Length of the SQLDA. Computed as SQLN*44+16. | Same.
SQLN | sqln | sqln | smallint | Number of occurrences of SQLVAR. (See the SQLVAR Elementsfor more about SQLVAR.) | Same.
SQLD | sqld | sqld | smallint | Number of columns described by occurrences of SQLVAR. If the statement is not a query, the value is zero. (See the SQLVAR Elementsfor more about SQLVAR.) | Number of host variables described by occurrences of SQLVAR.
Parent topic: SQL Descriptor Area (SQLDA)


SQLVAR Elements

Restriction: This topic applies to Windows environments only.
COBOL Name | C Name | PL/I Name | Data Type | Usage in DESCRIBE and PREPARE INTO | Usage in FETCH, OPEN or EXECUTE
SQLTYPE | sqltype | sqltype | smallint | Code indicating the data type of the column and if null values are allowed. See the table in SQLTYPE Values for SQLTYPE codes. | Indicates the data type of a host variable and if an indicator variable is provided. See the table in SQLTYPE Values for SQLTYPE codes.
SQLLEN | sqllen | sqllen | smallint | Indicates the length attribute of the columns. For date/time columns, the length of the string representation of the value is used. See the table under SQLLEN Values for SQLLEN values. | Indicates the length attribute of the host variable. See the table under SQLLEN Values for SQLLEN values.
SQLDATA | sqldata | sqldata | pointer to a buffer | Contains the CCSID indicator for bit data Format is x'0000'zzzz' where zzzz is X'FFFF' | Contains the address of the host variable.
SQLIND | sqlind | sqlind | pointer | Undefined. | Contains the address of an associated indicator variable if SQLTYPE is odd.
SQLNAME | sqlname | sqlname | char(30) | Name of the column (or a string of length zero if no name exists). | Not used in XDB Server.

More:

  • SQLTYPE Values
  • SQLLEN Values
Parent topic: SQL Descriptor Area (SQLDA)


SQLTYPE Values

Restriction: This topic applies to Windows environments only.

The meanings of SQLTYPE values depend on the type of statement executed, as shown in the table below. The following differences should be noted:

  • For DESCRIBE and PREPARE

    The codes for DB2 mode differ depending on whether or not null values are allowed in the column. An even value for SQLTYPE indicates that the column does not allow nulls. An odd value indicates that the column does allow nulls. In XDB mode, the codes do not differ.

  • For FETCH, OPEN and EXECUTE

    Codes differ depending on whether or not indicator variables are provided for use with the host variable. An even value for SQLTYPE means no indicator variable is provided, an odd value indicates that SQLIND contains the address of an indicator variable.

    In addition, because host variables do not include DATE, TIME or TIMESTAMP data types, these values are usually retrieved using fixed length character strings.

    Data Type | DESCRIBE & PREPARE | FETCH, OPEN & EXECUTE
    DB2 Mode: XDB Mode No Indicator Indicator
    date

    (See note 1.)

             384 385 4 384 385
    time

    (See note 1.)

             388 389 7 388 389
    timestamp

    (See note 1.)

             392 393 11 392 393
    varying-length character string | 448 | 449 | 9 | 448 | 449
    fixed-length character string | 452 | 453 | 6 | 452 | 453
    long varying length character string | 456 | 457 | 10 | 456 | 457
    varying length graphic string | 464 | 465 | 17 | 464 | 465
    fixed length graphic string | 468 | 469 | 16 | 468 | 469
    long varying length graphic string

    (See note 2.)

             472 473 22 472 473
    floating point | 480 | 481 | 3 | 480 | 481
    packed decimal | 484 | 485 | 8 | 484 | 485
    money | 484 | 485 | 5 | 484 | 485
    large integer | 496 | 497 | 2 | 496 | 497
    small integer | 500 | 501 | 1 | 500 | 501

Table Notes:

  1. For host variable, a fixed-length character string representation of the date, time or timestamp is used.
  2. For host variable, a long graphic string.
Parent topic: SQL Descriptor Area (SQLDA)


SQLLEN Values

Restriction: This topic applies to Windows environments only.

The value of SQLLEN depends on the data type of the columns. SQLLEN gives the length of data (in bytes), depending on data type.

Data Type | SQLLEN Value for DESCRIBE | SQLLEN Value for FETCH, OPEN and EXECUTE
date (See note 1.) | 10 bytes | length attribute of the host variable
time (See note 1.) | 8 bytes | length attribute of host variable
timestamp (See note 1.) | 26 bytes | length attribute of the host variable
character strings - varying-length - fixed-length - long varying-length | length attribute of the column | length attribute of the host variable
graphic strings - varying-length - fixed length - long varying-length (See note 2.) | length attribute of the column | length attribute of the host variable
floating point | 4 for single precision 8 for double precision | 4 for single precision 8 for double precision
packed decimal | precision in byte 1 scale in byte 2 | precision in byte 1 scale in byte 2
integer | 4 bytes | 4 bytes
small integer | 2 bytes | 2 bytes

Table Notes:

  1. For host variable, a fixed-length character string representation of the date, time or timestamp is used.
  2. For host variable, a long graphic string.
Parent topic: SQL Descriptor Area (SQLDA)


SQLDA Structure For COBOL

Restriction: This topic applies to Windows environments only.

The SQLDA structure is provided in the copybook sqlda.cpy. Include this copybook in all COBOL programs that make use of dynamic SQL.

 01 SQLDA sync.
     05 SQLDAID               PIC X(8)  VALUE "SQLDA  ".
     05 SQLDABC               PIC S9(9) COMP-5 value 0.
     05 SQLN                  PIC S9(4) COMP-5 value 0.
     05 SQLD                  PIC S9(4) COMP-5 value 0.
     05 SQLVAR OCCURS 0 TO 1489 TIMES DEPENDING ON SQLD.
         10 SQLTYPE            PIC S9(4) COMP-5.
         10 SQLLEN             PIC S9(4) COMP-5.
         10 SQLDATA            USAGE POINTER.
         10 SQLIND             USAGE POINTER.
         10 SQLNAME.
             15 SQLNAMEL        PIC S9(4) COMP-5.
             15 SQLNAMEC        PIC X(30).

If you are using the Precompiler directive SQLDA-VER = 0, you must copy the file sqlda.old to sqlda.cpy. The structure of this SQLDA is below:

01 SQLDA.
  03 SQLDAID    PIC X(8).
  03 SQLDABC    PIC S9(9) COMP.
  03 SQLN    PIC S9(4) COMP.
  03 SQLD    PIC S9(4) COMP.
  03 SQLVAR OCCURS 300.
    05 SQLTYPE  PIC S9(4) COMP.
    05 SQLLEN  PIC S9(4) COMP.
    05 SQLDATA  PIC X(4).
    05 SQLIND  PIC X(4).
    05 SQLNAME  PIC X(30).
Parent topic: SQL Descriptor Area (SQLDA)


SQLDA Structure For C

Restriction: This topic applies to Windows environments only.

The SQLDA structure is provided in the file sqlca.h. Include this file in all C programs that make use of dynamic SQL.

#ifndef SQLDASIZE
struct sqlda
{
  unsigned char  sqldaid[8];
  long      sqldabc;
  short      sqln;
  short      sqld;
  struct sqlvar
  {
    short      sqltype;
    short      sqllen;
    unsigned char    *sqldata;
    short      *sqlind;
    struct sqlname
    {
      short      length;
      unsigned char    data[30];
    } sqlname;
  } sqlvar[1];
};
#define SQLDASIZE(n) (sizeof(struct sqlda)+
      (n-1)*sizeof(struct sqlvar))
#endif
Parent topic: SQL Descriptor Area (SQLDA)


SQLDA Structure For PL/I

Restriction: This topic applies to Windows environments only.

The SQLDA structure is provided in the copybook SQLDA.INC. Include this copybook in all PL/I programs that make use of dynamic SQL.

dcl sqlsize fixed binary(15);
dcl sqldaptr ptr;
dcl
   1 sqlda based (sqldaptr),
     2 sqldaid    char(8),
     2 sqldabc    fixed bin(31),
     2 sqln       fixed bin(15),
     2 sqld       fixed bin(15),
     2 sqlvar     (sqlsize refer (sqln)),
       3 sqltype  fixed bin(15),
       3 sqllen   fixed bin(15),
       3 sqldata  ptr,
       3 sqlind   ptr,
Parent topic: SQL Descriptor Area (SQLDA)


SQL Option Server TUTORIAL Location

Restriction: This topic applies to Windows environments only.
  • Overview of the Tutorial Tables
  • CONSTANT Table
  • CUSTOMER Table
  • DEPT (Department) Table
  • EMPLOYEE Table
  • ITEMS Table
  • ORDERS Table
  • PART Table
  • PARTSUPP Table
  • PRODUCTS Table
  • QMT_STAFF Table
  • SUBPART Table
  • SUPPLIER Table
Parent topic: SQL Reference


Overview of the Tutorial Tables

Restriction: This topic applies to Windows environments only.

Most of the examples in this and other SQL Option Server references are based on the tutorial tables listed below. You can execute the example SQL statements appearing throughout this reference. Any results displayed from these examples should exactly correspond to the results obtained if you execute the same example against the tutorial tables listed below.

  • CONSTANT Table
  • CUSTOMER Table
  • DEPT (Department) Table
  • EMPLOYEE Table
  • ITEMS Table
  • ORDERS Table
  • PART Table
  • PARTSUPP Table
  • PRODUCTS Table
  • QMT_STAFF Table
  • SUBPART Table
  • SUPPLIER Table
Parent topic: SQL Option Server TUTORIAL Location


CONSTANT Table

Restriction: This topic applies to Windows environments only.
o_no | c_no | e_no
6 | 22 | 11
Parent topic: SQL Option Server TUTORIAL Location


CUSTOMER Table

Restriction: This topic applies to Windows environments only.
c_no | company | address | city | state | zip | phone | balance
1 | Great Software | 123 Main St | Baltimore | MD | 21212 | 301 222-2222 | 828.60
2 | Unique Systems | 111 First St | Atlanta | GA | 30303 | 404 987-6543 | 3434.00
3 | Commuter Communication | 333 Last St | Washington | DC | 20002 | 202 123-4567 | 648.00
4 | Popular Consulting | 321 Home Dr | Berkeley | CA | 94004 | 516 444-5555 | 2209.00
5 | Unlimited Supply | 213 River Rd | Berkeley | CA | 94004 | 516 555-6789 | 772.00
6 | ABC Corp. | 1 Any Place | Somewhere | MD | 12345 | 301 456-7890 | 63.60
7 | Perfect Software | 1 Address St | Citytown | CA | 12345 | 516 222-3333 | 0.00
8 | Business Technology | 123 Main St | College Park | MD | 20740 | 301 222-3333 | 418.70
9 | Performance Software | 1 First St | Baltimore | MD | 21212 | 301 999-9999 | 2244.20
10 | Problem Solver | 123 Broadway St | Chicago | IL | 54321 | 555 888-8888 | 2000.00
11 | Technology Leader | 100 Oneway St | New York | NY | 98765 | 777 555-5555 | 3000.00
12 | New Startup, Inc. | 101 Nosuch Rd | New York | NY | 87654 | 777 777-7777 | 2345.00
13 | Database Experts | 123 Expert Rd | College Park | MD | 20740 | 301 232-3232 | 1234.00
14 | Instant Success Corp | 111 Goodluck Rd | Niceplace | NY | 13579 | 777 246-1357 | 123.00
15 | Ace Debug Co. | 999 Last St | Littletown | NJ | 11111 | 999 888-7777 | 987.00
16 | Non Stop Systems | 100 Running Rd | Computown | CA | 99999 | 516 222-3333 | 5000.00
17 | Reliable Software | 1000 Longlive St | Oldtown | CA | 99999 | 516 555-5555 | 7606.10
18 | Brandname Systems | 1001 Wellknown St | Popular | IL | 54321 | 555 444-3333 | 543.00
19 | Survival Technology | 100 Deadend St | Nowhere | IL | 56789 | 555 666-7777 | 5678.00
20 | Success Business | 123 Lucky St | College Park | MD | 20740 | 301 333-2222 | 3407.90
21 | Advanced Systems | 100 Fast St | Bulletown | CA | 54321 | 516 222-1111 | 100.00
Parent topic: SQL Option Server TUTORIAL Location


DEPT (Department) Table

Restriction: This topic applies to Windows environments only.
dept | dname | mgr
1050 | Sales | 9
2020 | Accounting | 2
Parent topic: SQL Option Server TUTORIAL Location


EMPLOYEE Table

Restriction: This topic applies to Windows environments only.
e_no | lname | fname | street | city | st | zip | dept | payrate | com
1 | Hurwood | Roger | 1234 Stirrup La | Green Valley | MD | 20441 | 2020 | 16.00 |
2 | Kerin | Linda | 802 Wilderness Dr | Wild Woods | VA | 33256 | 2020 | 17.50 |
3 | Gross | Mary | 303 Stagecoach Rd | Green Valley | MD | 20441 | 2020 | 10.00 |
4 | Wilson | Arthur | 211 Main St | Yellow Fountain | VA | 33210 | 2020 | 17.50 |
5 | Chung | Yung | 422 Maple St | Garden City | MD | 20331 | 1050 | 12.25 | 0.05
6 | Cox | John | 555 Magnolia Dr | Garden City | MD | 20331 | 2020 | 14.70 |
7 | Crisp | Keith | Rt 2, Box 43 | Yellow Fountain | VA | 33210 | 1050 | 9.00 | 0.05
8 | Hurwood | Susan | 1234 Stirrup La | Green Valley | MD | 20441 | 2020 | 11.25 |
9 | Hopkins | James | 345 Forest Dr | Yellow Fountain | VA | 33210 | 1050 | 17.00 | 0.03
10 | Haley | Olaf | 334 Market St | Green Valley | MD | 20441 | 1050 | 13.70 | 0.06
Parent topic: SQL Option Server TUTORIAL Location


ITEMS Table

Restriction: This topic applies to Windows environments only.
o_no | p_no | quantity | price
1 | 101 | 1 | 50.00
2 | 102 | 1 | 279.00
2 | 103 | 2 | 125.00
3 | 101 | 2 | 50.00
4 | 101 | 2 | 50.00
4 | 103 | 2 | 125.00
5 | 102 | 3 | 279.00
5 | 103 | 3 | 125.00
Parent topic: SQL Option Server TUTORIAL Location


ORDERS Table

Restriction: This topic applies to Windows environments only.
o_no | c_no | o_date | s_no
1 | 1 | 09/10/1991 | 5
2 | 2 | 10/10/1991 | 7
3 | 4 | 10/12/1991 | 5
4 | 1 | 10/25/1991 | 5
5 | 9 | 10/30/1991 | 7
Parent topic: SQL Option Server TUTORIAL Location


PART Table

Restriction: This topic applies to Windows environments only.
pno | pname | color | weight | city
P1 | NUT | RED | 12 | LONDON
P2 | BOLT | GREEN | 17 | PARIS
P3 | CAM | BLUE | 12 | PARIS
P4 | SCREW | RED | 14 | LONDON
P5 | CAM | BLUE | 12 | PARIS
P6 | COG | RED | 19 | LONDON
Parent topic: SQL Option Server TUTORIAL Location


PARTSUPP Table

Restriction: This topic applies to Windows environments only.
sno | pno | qty
S1 | P1 | 300
S1 | P3 | 400
S2 | P2 | 400
S3 | P2 | 200
S1 | P2 | 200
S1 | P4 | 200
S1 | P5 | 100
S1 | P6 | 100
S2 | P1 | 300
S4 | P2 | 200
S4 | P4 | 300
S4 | P5 | 400
Parent topic: SQL Option Server TUTORIAL Location


PRODUCTS Table

Restriction: This topic applies to Windows environments only.
p_no | description | price
101 | Floppy Disk Drive | 50.00
102 | 9600B Modem | 279.00
103 | VGA Graphics Card | 125.00
104 | Mouse | 85.00
201 | 304M Hard Disk | 539.00
202 | Sound Card | 189.00
203 | Game Card | 30.00
204 | VGA Monitor | 329.00
301 | CD ROM Drive | 354.00
302 | Math Coprocessor | 199.00
303 | Tape Backup | 269.00
304 | Laser Printer | 1594.00
Parent topic: SQL Option Server TUTORIAL Location


QMT_STAFF Table

Restriction: This topic applies to Windows environments only.
EMPID | LNAME | FNAME | DEPARTMENT | JOB | YEARS | SALARY | COMMISSION
110 | SIMPSON | MIKE | 120 | MGR | 7 | 18,380.15 | 000500.00
120 | PETREE | STEVE | 120 | SALES | 8 | 18,193.90 | 01,664.73
130 | MILES | LISA | 138 | MGR | 5 | 17,529.00 |
145 | BACON | CARL | 138 | SALES | 2 | 15,000.00 | 01,008.66
150 | HANSON | KATHY | 115 | MGR | 10 | 20,682.45 |
165 | MYERS | ROGER | 138 | SALES | 3 | 16,830.00 | 01,102.23
170 | RODMAN | CHUCK | 115 | SALES | 7 | 16,525.48 | 02,204.28
180 | JASON | JOHN | 120 | CLERK |  | 13,527.25 | 01,180.48
190 | BEAGLE | HUTCH | 142 | SALES | 6 | 18,024.40 | 02,438.98
200 | WENTZ | STEVEEN | 142 | MGR | 7 | 18,375.45 |
210 | ARNA | ISMETT | 115 | CLERK | 5 | 12,530.85 | 01,258.88
225 | MACKEY | DONNA | 138 | CLERK | 1 | 12,077.00 | 000139.28
230 | YAMAGUCHI | KATRINA | 142 | CLERK | 6 | 10,528.55 | 01,127.88
240 | FRITZE | MARY ANN | 151 | MGR | 6 | 21,172.65 |
250 | WILLIAMS | DOUG | 151 | SALES | 6 | 19,479.15 | 01,689.93
260 | MOLITOR | MITCH | 110 | MGR | 7 | 22,981.85 | 01,500.00
270 | KERMIT | JASON | 115 | CLERK | 4 | 12,281.15 | 01,162.38
280 | ABLE | OTTO | 138 | CLERK | 3 | 12,032.00 | 01,288.78
290 | SNEAD | XIAOLIN | 120 | CLERK | 8 | 14,275.40 | 01,178.78
300 | SCOTT | ARLENE | 142 | CLERK |  | 11,531.25 | 01,136.48
310 | KUANG | CHUNG | 110 | MGR | 10 | 20,032.65 |
320 | SMITHERS | JOHN | 151 | SALES | 7 | 17,677.15 | 02,045.08
330 | LILLY | CRAIG | 151 | CLERK | 3 | 13,392.45 | 01,241.93
340 | DAVISON | DAJUN | 110 | MGR | 5 | 19,282.90 |
350 | WHITEHURS | MIKE | 151 | CLERK | 6 | 14,482.65 | 01,565.58
360 | JANNET | JIM | 110 | MGR | 12 | 21,256.65 |
370 | STROM | RAYMOND | 166 | MGR | 9 | 18,578.15 |
380 | WILLIAMS | ROBERT | 166 | SALES | 9 | 18,697.15 | 01,863.78
390 | QUILT | CHRISTINE | 184 | MGR | 10 | 19,840.65 |
400 | DAVIDSON | STORM | 184 | SALES | 5 | 15,477.15 | 01,858.38
410 | GRASON | BILLY | 166 | SALES | 13 | 21,022.65 | 01,252.58
420 | GONZALES | RENEA | 166 | SALES | 4 | 16,880.85 | 01,896.28
430 | BURRELS | RUSTY | 166 | CLERK | 1 | 11,010.65 | 01,107.78
440 | EDEN | EDDIE | 184 | SALES | 7 | 17,866.65 | 02,337.28
450 | GAGNEY | GREG | 184 | CLERK | 5 | 13,053.15 | 01,240.28
140 | BROOKS | DAVID | 138 | SALES | 6 | 25,000.00 | 02,008.66
160 | MISSON | STEVEN | 138 | SALES | 3 | 16,800.00 | 01,900.23
220 | MASSON | STEFANIE | 138 | CLERK | 5 | 22,077.00 | 02,139.28
142 | STANCEL | WILLIAM | 138 | SALES |  | 12,000.00 | 000088.66
133 | ELDER | NANCY | 138 | MGR | 2 | 16,529.00 |
255 | KENNER | CAL | 151 | SALES | 2 | 13,479.15 | 01,000.00
Parent topic: SQL Option Server TUTORIAL Location


SUBPART Table

Restriction: This topic applies to Windows environments only.
product | subpart | qty
P7 | P1 | 2
P7 | P2 | 4
P7 | P6 | 6
P8 | P4 | 8
P8 | P7 | 1
P9 | P5 | 3
P9 | P7 | 5
P9 | P8 | 7
P10 | P1 | 9
P10 | P2 | 1
P11 | P9 | 2
P11 | P10 | 3
Parent topic: SQL Option Server TUTORIAL Location


SUPPLIER Table

Restriction: This topic applies to Windows environments only.
sno | sname | status | city
S1 | SMITH | 20 | LONDON
S2 | JONES | 10 | PARIS
S3 | BLAKE | 30 | PARIS
S4 | CLARK | 20 | LONDON
S5 | ADAMS | 30 | ATHENS
Parent topic: SQL Option Server TUTORIAL Location


Objects Used by the SQL Option Server

Restriction: This topic applies to Windows environments only.

This topic describes the paths and object names that are created and/or used by the SQL Option Server when you create various data objects in SQL Option Server locations. The storage structure and object names depend on the options you specify in your CREATE statements. In the chart, the first two columns of a given row define the condition that is described in the remaining columns of that row (by reading across).

If stogroup is sysdeflt, the location path is used as the stogroup path. When objects are created, the ..\loc-path\dbname\ path is used.

To generate file names for objects that have names greater than 8 characters (for example, 18-character table names), The SQL Option Server truncates the long name to 8 characters. If the resulting file name would not be unique, a unique file name is generated automatically.

The following list explains the abbreviations used in the chart:

Abbreviation | Meaning
Dbname | Database name
Tsname | Table space name
Sto-name | Storage Group name
Dbsto-path | Disk drive and path defined for the database (DB) stogroup.
Tssto-path | Disk drive and path defined for the table space (TS) stogroup.
Loc-path | Disk drive and path defined for the location.

This chart does not list all possible combinations of creation conditions. Only the more common conditions are shown.

If you create a | And you specify a | The SQL Option Server creates or uses ..
 |  | Path | Stogroup | Database | Table/Index Space
Stogroup | Volumes Vcat (No path defined) | ..\loc-path\dbname\ path is used when objects are created | Sto-name you enter | n/a | n/a
Stogroup | Volumes Vcat XdbVolPath | XdbVolPath you enter in SYSIBM.SYSVOLUMES (for example, c:\sto-path) | Sto-name you enter | n/a | n/a
Database | ------ | c:\loc-path\dbname\ | SYSDEFLT | DBname you enter | n/a
Database | Stogroup | c:\DBsto-path\ | Sto-name you enter | DBname you enter | n/a
Table Space | Database | c:\loc-path\dbname\ | SYSDEFLT | DBname you enter | TSname you enter
Table Space | Database Stogroup (Sto-path for the named stogroup is missing from SYSIBM. SYSVOLUMES) | c:\loc-path\dbname\ | SYSDEFLT | DBname you enter | TSname you enter
Table Space | Database Stogroup (Sto-path exists in SYSIBM. SYSVOLUMES and on op system) | c:\TSsto-path\ | Sto-name you enter | DBname you enter | TSname you enter
Table | ------ | c:\loc-path\DSNDB04\*.tab | SYSDEFLT | DSNDB04 | TSname is first 8 characters of table name (or system generated unique name, if needed)
Table | Database (DB has NO stogroup) | c:\loc-path\dbname\*.tab | SYSDEFLT | DBname you enter | TSname is first 8 characters of table name (or system generated unique name, if needed)
Table | Database (DB has a stogroup) | c:\DBsto-path\*.tab | Same sto-name as the database's stogroup | DBname you enter | TSname is first 8 characters of table name (or system generated unique name, if needed)
Table | Database Tablespace (DB has NO stogroup; TS has NO stogroup) | c:\loc-path\dbname\*.tab | SYSDEFLT | DBname you enter | TSname you enter
Table | Database Tablespace (DB has NO stogroup; TS has a stogroup) | c:\TSsto-path\*.tab | Same sto-name as the table space's stogroup | DBname you enter | TSname you enter
Table | Database Tablespace (DB has a stogroup; TS has NO stogroup) | c:\DBsto-path\*.tab | Same sto-name as the database's stogroup | DBname you enter | TSname you enter
Table | Database Tablespace (DB has a stogroup; TS has a stogroup) | c:\TSsto-path\*.tab | Same sto-name as the table space's stogroup | DBname you enter | TSname you enter
Index | Tablename (DB has NO stogroup) | Same path as associated table..\*.idx and ..\*.ptr | SYSDEFLT | DBname to which associated table belongs | Index space name is same as index name
Index | Tablename (DB has a stogroup) | Same path as associated table..\*.idx and ..\*.ptr | Same sto-name as the database's stogroup | DBname to which associated table belongs | Index space name is same as index name
Index | Tablename Stogroup | Same path as associated table..\*.idx and ..\*.ptr | Sto-name you enter | DBname to which associated table belongs | Index space name is same as index name
Parent topic: SQL Reference


XDB Directive Options

Restriction: This topic applies to Windows environments only.
  • ALLOW-HYPHEN
    Enables the preprocessor to allow hyphens in SQL identifiers.
  • APOST
    Causes the preprocessor to recognize apostrophes to delimit literals for quote character in SQL statements.
  • AUTHID
    Causes the preprocessor to include code at SQL initialization that sets the value of your current SQLID to any valid authorization ID.
  • AUTOBIND
    Causes the preprocessor to automatically call the SQL Option Bind utility from within the debugging session after the compiler finishes generating the DBRM if no SQL errors were detected and if the DBRM preprocessor directive was set.
  • AUTOCLOSE
    Causes the SQL Option Server to automatically open and close statements after an insert, update, or delete command.
  • BEHAVIOR
    Causes the SQL Option preprocessor to emulate the behavior of either the DB2 preprocessor or coprocessor.
  • BIND-SQLID
    Sets the current SQLID to this AuthID.
  • BLOCKING
    Specifies the type of block fetching to use.
  • CHANGE-CONTROL
    Controls package creation during the bind process.
  • COLLECTION-ID
    Specifies the collection at the remote DRDA server where the package will be bound.
  • CONCAT
    Specifies the ANSI character code to use for the CONCAT symbol (|).
  • COPY
    Causes the precompiler to expand copybooks included in your source code using standard COBOL COPY statements. Allows EXEC SQL statements and use of host variables to be defined within a COPY statement.
  • CTRACE
    Creates a trace file for submission to technical support if requested.
  • DATE
    Specifies the date format to be used with this program.
  • DB2
    Causes the SQL Option Server to return DB2 error codes and messages when compiling and running, and to close all open cursors at COMMIT and ROLLBACK (the DB2 standard).
  • DB2CLOSE
    Causes the SQL Option Server to close all open statements and cursors at COMMIT and ROLLBACK (the DB2 standard).
  • DB2ERROR
    Causes the SQL Option Server to return DB2 error codes and messages when the program is compiled or executed.
  • DB2VER
    Specifies the DB2 version used by the SQL Option preprocessor for syntax checking.
  • DBRM
    Causes the SQL Option preprocessor to produce a DBRM file.
  • DECLARE
    Tells the preprocessor that host variables are declared in a BEGIN/END DECLARE section of a COBOL program.
  • DEFAULT-CHAR
    Specifies character subtype for all new character columns for which an explicit subtype is not specified.
  • DIRECTIVES
    Causes the SQL Option preprocessor to read the preprocessor directives contained in a separate user-created directives file or in the EXEC SQL options specified in the Build settings.
  • EXIST-CHECK
    Specifies whether to create a package if some DBRM objects do not exist.
  • FILLSYSCAT
    Causes the preprocessor to insert information about EXEC SQL statement in the program into the SYSDBRM and SYSSTMT system catalog tables when the COBOL program is compiled.
  • GENSQLCA
    Generates a SQLCA structure in the program if none is defined.
  • GRANT-EXECUTE
    Specifies AUTHID to grant execute privileges on the package to.
  • HYPHEN-IN-CURSOR
    Permits hyphens in cursor names.
  • IGNORE-NESTED
    Specifies in programs with nested subroutines, the program-id at which to start generating database interface code.
  • ISOLATION-LEVEL
    Controls the way in which locks are acquired and released by the system.
  • LIBINCLUDE
    Causes the precompiler to expand and include copybooks coded with ++INCLUDE or –INC syntax.
  • LOCATION
    Specifies the location to which a DBRM is bound when the AUTOBIND preprocessor directive is used.
  • MAXSQL
    Specifies the maximum number of EXEC SQL statements the preprocessor can handle.
  • NEVERCLOSE
    This directive prevents the closing of open statements or cursors at commit or rollback.
  • NOFOR
    Causes the SQL Option runtime not to require FOR UPDATE clause in DECLARE CURSOR statements when UPDATE CURRENT OF CURSOR is specified.
  • NOT
    Specifies the ASCII character code to use for NOT character (¬).
  • OPTIMIZE
    This directive optimizes the code generated by the precompiler specifically for use on either PC or mainframe.
  • PACKAGE-OWNER
    Specifies the AuthID assigned to the package. This AuthID must have authority to execute all the SQL in the package.
  • PKGSET
    Causes the SQL Option run-time program to send additional information to set the current package set.
  • QUOTE
    Causes the preprocessor to recognize double quotes to delimit literals for quote character in SQL statements.
  • SAVE-RETURN-CODE
    Causes the SQL Option precompiler to save and then restore RETURN-CODE when calling SQL Option functions
  • SQLDA-VER
    The SQLDA structure used in the program for dynamic SQL statements.
  • SQLDS
    Allows the SQL Option Server to accept a PREPARE statement before a DECLARE statement in your source code (which is allowed in SQL/DS)
  • STRICT-DB2
    Enforces strict support for certain DB2 features that are generally permitted in default DB2 mode.
  • TIME
    Specifies the time format to be used with this program.
  • VALIDATE
    Causes the SQL Option preprocessor to verify all data objects referenced in your program's embedded SQL statements against the SQL Option system tables.
  • VALIDATE-ERR-LVL
    Specifies the error level to use for errors produced when the VALIDATE directive is used.
  • VALIDATE-LOGIN
    Causes the SQL Option preprocessor to ensure communications with an SQL Option Server prior to attempting to validate any SQL statements. If the log in fails, a fatal error is generated.
  • VERSION
    Specifies the new version identifier for a replacement package.
  • XDBFUNCS
    Allows use of all SQL Option commands (including SQL Option extensions) in embedded SQL.
Parent topic: Reference
Related concepts
Setting the XDB Preprocessor and Compiler Directive Options


ALLOW-HYPHEN

Enables the preprocessor to allow hyphens in SQL identifiers.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]ALLOW-HYPHEN

Parameters:

None

Properties:

Default: NOALLOW-HYPHEN

Comments:

This directive is only supported in version DB2 V7 or later. Before DB2 V7, hyphens were not allowed in SQL identifiers and caused the token to be flagged as an error.

Parent topic: XDB Directive Options


APOST

Causes the preprocessor to recognize apostrophes to delimit literals for quote character in SQL statements.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]APOST

Parameters:

None

Properties:

Default: NOAPOST

Comments:

Only set APOST if you are using apostrophes to delimit literals in SQL statements and you have set the project BUILD settings for quote character to be QUOTES.

Parent topic: XDB Directive Options


AUTHID

Causes the preprocessor to include code at SQL initialization that sets the value of your current SQLID to any valid authorization ID.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]AUTHID
AUTHID[=authorization-ID#1;authorization-ID#2;...;authorization-ID#10]

Parameters:

authorization-ID | A valid authorization ID defined via SQL Wizard
NOAUTHID | No code will be generated

Properties:

Default: NOAUTHID

Comments:

If AUTHID is used without authorization ID, the current AUTHID is set to the default value specified via Options > SQL for DB2 (Windows) or the User Profile utility (UNIX) from the IDE menus.

If you are doing static binding, the AUTHID directive also sets the value of the default qualifier. Mutliple authorization IDs are only supported when doing AUTOBIND, IDs must be delimited by a semi-colon with no spaces in the string. A maximum of 10 IDs are supported but the same number of DBRMs must be specified or the number of IDs greater than DBRMs will be ignored.

Parent topic: XDB Directive Options


AUTOBIND

Causes the preprocessor to automatically call the SQL Option Bind utility from within the debugging session after the compiler finishes generating the DBRM if no SQL errors were detected and if the DBRM preprocessor directive was set.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]AUTOBIND

Parameters:

None

Properties:

Default: NOAUTOBIND

Comments:

If you don't use AUTOBIND, you can use the SQL Option Bind Utility to bind the program. See your SQL Option Link User's Guide for specific procedures.

The LOCATION preprocessor directive can be used with the AUTOBIND preprocessor directive to specify the location to which the DBRM is bound. If the LOCATION directive is not used, the Bind Utility uses the location specified via the IDE Options > SQL menu.

Parent topic: XDB Directive Options


AUTOCLOSE

Causes the SQL Option Server to automatically open and close statements after an insert, update, or delete command.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]AUTOCLOSE

Parameters:

None

Properties:

Default: AUTOCLOSE

Comments:

Under NOAUTOCLOSE (which is not DB2-compatible), the SQL Option Server allows multiple execution of insert/update/delete commands without closing the statement. Closing is done at commit. This option is used for performance reasons.

Parent topic: XDB Directive Options


BEHAVIOR

Causes the SQL Option preprocessor to emulate the behavior of either the DB2 preprocessor or coprocessor.
Restriction: This topic applies to Windows environments only.

Syntax:

BEHAVIOR={STACKED | COPROCESSOR}

Parameters:

STACKED | The SQL Option preprocessor behaves as if it were a stacked preprocessor, implying that data elements defined in COBOL COPY statements are not visible with SQL.
COPROCESSOR | The SQL Option preprocessor behaves as if it were a coprocessor, which is another module within the compiler, implying that data elements defined anywhere within the COBOL program are visible and available for use as host variables.

Properties:

Default: STACKED
Parent topic: XDB Directive Options


BIND-SQLID

Sets the current SQLID to this AuthID.
Restriction: This topic applies to Windows environments only.

Syntax:

BIND-SQLID=authid

Parameters:

authid Any valid AuthID.

Properties:

Default: None

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


BLOCKING

Specifies the type of block fetching to use.
Restriction: This topic applies to Windows environments only.

Syntax:

BLOCKING={FSR | SR | LB}

Parameters:

block-code The code for type of block fetching to perform when program is statically bound:
FSR | (Forced Single Row) does not use block fetching regardless of cursor type
SR | (Single Row) uses block fetching for read-only cursors and fetches a row at a time for ambiguous cursors
LB | (Limited Block) uses block fetching for read-only and ambiguous cursors
Default: LB

Properties:

Default: LB

Comments:

This directive only has meaning when program has been statically bound.

Multiple collection-ids are only supported when doing AUTOBIND, Collection-ids must be delimited by a semi-colon with no spaces in the string. A maximum of 10 collection-ids are supported but the same number of DBRMs must be specified or the number of collection-ids greater than DBRMs will be ignored. Also, you must specify at least one collection-id or a compile error SQL0335 will be generated when using multiple binds.

Parent topic: XDB Directive Options


CHANGE-CONTROL

Controls package creation during the bind process.
Restriction: This topic applies to Windows environments only.

Syntax:

CHANGE-CONTROL=[ERROK][NOERR]

Parameters:

ERROK | Creates a package even if an error occurs during the bind process.
NOERR | Does not create a package if an error occurs during the bind process.

Properties:

Default: NOERR

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


COLLECTION-ID

Specifies the collection at the remote DRDA server where the package will be bound.
Restriction: This topic applies to Windows environments only.

Syntax:

COLLECTION-ID=collection-id#1;collection-id#2;...;collection-id#10

Parameters:

collection-id The name of the collection to bind package to

Properties:

Default: No bind is done.

Comments:

This directive must be set if the STATIC-DRDA directive is used.

Mutliple collection-ids are only supported when doing AUTOBIND. Collection-ids must be delimited by a semi-colon with no spaces in the string. A maximum of 10 collection-ids are supported but the same number of DBRMs must be specified or the number of collection-ids greater than DBRMs will be ignored. Also, you must specify at least one collection-id or a compile error SQL0335 will be generated when using multiple binds.

Parent topic: XDB Directive Options


CONCAT

Specifies the ANSI character code to use for the CONCAT symbol (|).
Restriction: This topic applies to Windows environments only.

Syntax:

CONCAT=(ansi-character-code}

Parameters:

ansi-character-code The ANSI character code to be mapped to the standard CONCAT symbol

Properties:

Default: 33

Comments:

DB2 uses the symbol (|) as the concatenation character. If your source contains a different character it can be mapped to the correct symbol.

Parent topic: XDB Directive Options


COPY

Causes the precompiler to expand copybooks included in your source code using standard COBOL COPY statements. Allows EXEC SQL statements and use of host variables to be defined within a COPY statement.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]COPY

Parameters:

None

Properties:

Default: NOCOPY

Comments:

This directive must be set if you want to use host variables with a COPY statement. Care should be taken since this may cause compilation errors when porting code to the mainframe unless your installation has software that expands copybooks before passing source to the DB2 precompiler.

Parent topic: XDB Directive Options


CTRACE

Creates a trace file for submission to technical support if requested.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]CTRACE

Parameters:

None

Properties:

Default: NOCTRACE

Comments:

The filename of the file that is created is sqltrace.txt. You also may be requested to use Compiler directive CHKECM(TRACE) which will create file ecmtrace.txt.

Parent topic: XDB Directive Options


DATE

Specifies the date format to be used with this program.
Restriction: This topic applies to Windows environments only.

Syntax:

DATE={date-format}

Parameters:

date-format
The format in which date information is to be returned. One of:
ISO | yyyy-mm-dd
EUR | dd.mm.yyyy
JIS | yyyy-mm-dd
USA | mm/dd/yyyy
LOCAL | format needs to be defined from the IDE, using Options > SQL for DB2 (Windows) or The User Profile utility (UNIX).

Properties:

Default: Use the default settings defined by the IDE, using Options > SQL for DB2 (Windows) or The User Profile utility (UNIX).

Comments:

Use this directive to override the default settings.

Parent topic: XDB Directive Options


DB2

Causes the SQL Option Server to return DB2 error codes and messages when compiling and running, and to close all open cursors at COMMIT and ROLLBACK (the DB2 standard).
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]DB2

Parameters:

None

Properties:

Default: DB2

Comments:

The DB2 directive combines the DB2CLOSE and DB2ERROR directive. If the WITH HOLD clause is included in your SQL statement, cursors remain open after a COMMIT, even if the DB2 preprocessor directive is specified.

Parent topic: XDB Directive Options


DB2CLOSE

Causes the SQL Option Server to close all open statements and cursors at COMMIT and ROLLBACK (the DB2 standard).
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]DB2CLOSE

Parameters:

None

Properties:

Default: DB2CLOSE

Comments:

If the WITH HOLD clause is included in your SQL statement, cursors remain open after a COMMIT, even if the DB2CLOSE preprocessor directive is specified.

Parent topic: XDB Directive Options


DB2ERROR

Causes the SQL Option Server to return DB2 error codes and messages when the program is compiled or executed.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]DB2ERROR

Parameters:

None

Properties:

Default: DB2ERROR
Parent topic: XDB Directive Options


DB2VER

Specifies the DB2 version used by the SQL Option preprocessor for syntax checking.
Restriction: This topic applies to Windows environments only.

Syntax:

DB2VER={V7 | V8 | V9}

Parameters:

V7
Use DB2 V7 rules for syntax checking.
V8
Use DB2 V8 rules for syntax checking.
V9
Use DB2 V9 rules for syntax checking.

Properties:

Default: V8

Comments:

Because some syntax checking takes place on the server when using DB2 V7 or later, VALIDATE is turned on by default.

Specify NOVALIDATE if you do not want SQL statements to be validated. Be aware that doing this could cause errors that are reported only after the SQL statement is executed. VALIDATE also requires all referenced tables and columns to be defined.

Parent topic: XDB Directive Options


DBRM

Causes the SQL Option preprocessor to produce a DBRM file.
Restriction: This topic applies to Windows environments only.

Syntax:

NODBRM or DBRM=filename#1;filename#2;...;filename#10

Parameters:

filename Name of file to write DBRM to

Properties:

Default: NODBRM

Comments:

By default, the SQL Option preprocessor produces only expanded source code. You must specify the DBRM preprocessor directive in order to produce a DBRM. When you specify NODBRM, no file is generated.

Multiple DBRM files can be written only if AUTOBIND is also specified. DBRM file names must be delimited by a semi-colon with no spaces in the string. A maximum of 10 DBRM files are supported. If only one DBRM is specified and more than one collection-id, authid or location is specified, a compile error SQL0334 is generated. If more than one DBRM is specified, then multiple collection-ids, authids and locations can be specified but are limited to the number of DBRM file names specified. Any number in excess are ignored. These options do not have to have the same number as the number of DBRM file names specified as the values used will then default to the previous value if a new one is not specified.

Parent topic: XDB Directive Options


DECLARE

Tells the preprocessor that host variables are declared in a BEGIN/END DECLARE section of a COBOL program.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]DECLARE

Parameters:

None

Properties:

Default: NODECLARE

Comments:

The default is NODECLARE, which makes the BEGIN/END DECLARE section optional.

Parent topic: XDB Directive Options


DEFAULT-CHAR

Specifies character subtype for all new character columns for which an explicit subtype is not specified.
Restriction: This topic applies to Windows environments only.

Syntax:

DEFAULT-CHAR={BITS | SBCS | DBCS | SYSDEFAULT}

Parameters:

default-code
BITS | specifies that the target relational database uses the FOR BITS DATA SQL
SBCS | specifies that the target relational database uses the FOR SBCS DATA SQL
DBCS | specifies that the target relational database uses the FOR MIXED DATA SQL
SYSDEFAULT | (recommended) specifies that the target relational database uses the system default character subtype.
Default: SYSDEFAULT

Properties:

Default: SYSDEFAULT

Comments:

This directive only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


DIRECTIVES

Causes the SQL Option preprocessor to read the preprocessor directives contained in a separate user-created directives file or in the EXEC SQL options specified in the Build settings.
Restriction: This topic applies to Windows environments only.

Syntax:

NODIRECTIVES
or
DIRECTIVES=filename

Parameters:

filename Name of file to get preprocessor directives from

Properties:

Default: NODIRECTIVES

Comments:

When you specify NODIRECTIVES, the system uses only preprocessor directives set in Build settings.

The filename parameter can include a full path, or an environment variable pointing to a path.

Parent topic: XDB Directive Options


EXIST-CHECK

Specifies whether to create a package if some DBRM objects do not exist.
Restriction: This topic applies to Windows environments only.

Syntax:

EXIST-CHECK={REQUIRED|OPTIONAL}

Parameters:

REQUIRED | Specifies that a package will be created only if all DBRM objects exist.
OPTIONAL | Specifies that a package will be created even if some DBRM objects do not exist.

Properties:

Default: OPTIONAL

Comments:

This directive is only relevant for a program that has been statically bound.

Parent topic: XDB Directive Options


FILLSYSCAT

Causes the preprocessor to insert information about EXEC SQL statement in the program into the SYSDBRM and SYSSTMT system catalog tables when the COBOL program is compiled.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]FILLSYSCAT

Parameters:

None

Properties:

Default: NOFILLSYSCAT

Comments:

The default is NOFILLSYSCAT, which causes no catalog information to be created or saved. Use of this directive may slow processing while the preprocessor logs on to the SQL Option Server and writes the information to the system tables. You must have SYSADM privileges on the system tables to use this directive. See the SQL Option SQL Reference for a description of the columns in these system tables.

Parent topic: XDB Directive Options


GENSQLCA

Generates a SQLCA structure in the program if none is defined.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]GENSQLCA

Parameters:

None

Properties:

Default: NOGENSQLCA

Comments:

The structure will be defined if the structure SQLCA is not defined or included. If a separate field SQLCODE is defined in the program, the field SQLCODE in structure will be defined as SQLCADE.

Parent topic: XDB Directive Options


GRANT-EXECUTE

Specifies AUTHID to grant execute privileges on the package to.
Restriction: This topic applies to Windows environments only.

Syntax:

GRANT-EXECUTE={PUBLIC | NONE |(authorization-ID)}

Parameters:

PUBLIC | Grants execute privileges on the package to public.
NONE | No execute privileges granted.
authorization-ID | Grants execute privileges to the given authorization ID, which must be a valid authorization ID defined via SQL Wizard.

Properties:

Default: PUBLIC

Comments:

  • This directive has meaning only when the program has been statically bound.
  • If you do not specify this directive, execute privileges on the package are automatically granted to PUBLIC.
  • To disable this directive, specify GRANT-EXECUTE=NONE.
Parent topic: XDB Directive Options


HYPHEN-IN-CURSOR

Permits hyphens in cursor names.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]HYPHEN-IN-CURSOR

Parameters:

None

Properties:

Default: | NOHYPHEN-IN-CURSOR
Synonym: | HYPHEN

Comments:

The default is NOHYPHEN-IN-CURSOR (or NOHYPHEN), which does not allow hyphens in cursor names. Specify HYPHEN-IN-CURSOR (or HYPHEN) for backward compatibility with older DB2 mode programs that use hyphenated cursor names.

Parent topic: XDB Directive Options


IGNORE-NESTED

Specifies in programs with nested subroutines, the program-id at which to start generating database interface code.
Restriction: This topic applies to Windows environments only.

Syntax:

IGNORE-NESTED={program-id}

Parameters:

program-id Any nested program encountered before the given program-id is ignored and no database interface code is generated for it. You must specify a program-id in the COBOL source code; otherwise, a compile error results.

Properties:

Default: If you specify IGNORE-NESTED without a parameter, the program-id defaults to the program name with the filename extension replaced by .CBL

Comments:

You can only generate database interface code in one program in nested programs. If you need to have SQL statements in multiple programs, compile the subroutines as separate programs.

Parent topic: XDB Directive Options


ISOLATION-LEVEL

Controls the way in which locks are acquired and released by the system.
Restriction: This topic applies to Windows environments only.

Syntax:

ISOLATION-LEVEL=[CS][ALL][RR][CHANGE][NC]

Parameters:

CS | The execution of SQL statements in the package and the current row in which the database cursor is positioned are protected from the actions of concurrent users for changes the requester makes.
ALL | The execution of SQL statements in the package is protected from the actions of concurrent users for rows the requester reads and changes.
RR | The execution of SQL statements in the package and the current row in which the database cursor is positioned are protected from the actions of concurrent users for rows the requester reads and changes, as well as phantom rows.
CHANGE | The execution of SQL statements in the package is protected from the actions of concurrent users for changes the requester makes.
NC | Commitment control is not used. COMMIT and ROLLBACK statements are not required for changes to be visible to concurrent users.

Properties:

Default: CS

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


LIBINCLUDE

Causes the precompiler to expand and include copybooks coded with ++INCLUDE or –INC syntax.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]LIBINCLUDE

Parameters:

None

Properties:

Default: LIBINCLUDE

Comments:

This directive is automatically turned on if you use the PANVALET or LIBRARIAN directive. If you don't want to allow host variables in a –INC or ++INCLUDE copybook, set the NOLIBINCLUDE directive.

Parent topic: XDB Directive Options


LOCATION

Specifies the location to which a DBRM is bound when the AUTOBIND preprocessor directive is used.
Restriction: This topic applies to Windows environments only.

Syntax:

LOCATION=location-name#1;location-name#2;...;location-name#10

Parameters:

location-name Location name to bind DBRM to

Properties:

Default: Use the location specified via the IDE Options > SQL menu.

Comments:

By default, the AUTOBIND preprocessor directive uses the location specified via the IDE Options>SQL menu unless this directive is specified.

Multiple locations are only supported when doing AUTOBIND. Locations must be delimited by a semi-colon with no spaces in the string. A maximum of 10 locations are supported but the same number of DBRMs must be specified or the number of locations greater than DBRMs will be ignored.

Parent topic: XDB Directive Options


MAXSQL

Specifies the maximum number of EXEC SQL statements the preprocessor can handle.
Restriction: This topic applies to Windows environments only.

Syntax:

MAXSQL={ number }

Parameters:

number The maximum number of EXEC SQL statements to process.

Properties:

Default: 750

Comments:

The preprocessor can handle up to 750 EXEC SQL statements per program by default. If your program gets a compiler error COBSQL0299S, use this preprocessor directive to increase the maximum.

Parent topic: XDB Directive Options


NEVERCLOSE

This directive prevents the closing of open statements or cursors at commit or rollback.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]NEVERCLOSE

Parameters:

None

Properties:

Default: NONEVERCLOSE

Comments:

Under NEVERCLOSE (which is not DB2-compatible), the SQL Option Server does not close cursors or open statement when a commit or rollback is encountered. This option is used for performance reasons.

Parent topic: XDB Directive Options


NOFOR

Causes the SQL Option runtime not to require FOR UPDATE clause in DECLARE CURSOR statements when UPDATE CURRENT OF CURSOR is specified.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]FOR

Parameters:

None

Properties:

Default: FOR

Comments:

If not specified, UPDATE CURRENT OF CURSOR clause will generate a SQL error when statement executed.

You cannot specify FOR explicitly.

Parent topic: XDB Directive Options


NOT

Specifies the ASCII character code to use for NOT character (¬).
Restriction: This topic applies to Windows environments only.

Syntax:

NOT={ansi-character-code }

Parameters:

ansi-character-code The ANSI character value to be mapped to the ¬ symbol.

Properties:

Default: 172

Comments:

For compatibility with DB2 on the mainframe this COBOL system allows the use of the NOT symbol in SQL statements. If your source uses a different ANSI code for the NOT symbol, this directive allows you to specify the ANSI value to be mapped for the NOT symbol.

Parent topic: XDB Directive Options


OPTIMIZE

This directive optimizes the code generated by the precompiler specifically for use on either PC or mainframe.
Restriction: This topic applies to Windows environments only.

Syntax:

OPTIMIZE= run-time-environment

Parameters:

run-time-environment Specify OPTIMIZE=MAINFRAME if your program uses COMP as data type for most numeric fields including fields described in SQLCA and SQLDA copybooks.

Specify OPTIMIZE=PC if your program uses COMP-5 as data type for most numeric fields including fields described in SQLCA and SQLDA copybooks.

Properties:

Default: OPTIMIZE=MAINFRAME

Comments:

The precompiler will generate code to swap bytes for all numeric host variables that don't match the optimize setting except for variables defined in an SQLDA. Variables defined in the SQLDA must match the optimize setting or an error message is generated. Obviously, if you intermix defining numeric variables using a mix of COMP/COMP-5 fields, more code is generated by the precompiler to handle this which also affects portability and performance.

Parent topic: XDB Directive Options


PACKAGE-OWNER

Specifies the AuthID assigned to the package. This AuthID must have authority to execute all the SQL in the package.
Restriction: This topic applies to Windows environments only.

Syntax:

PACKAGE-OWNER=authid

Parameters:

authid Any valid AuthID.

Properties:

Default: None

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


PKGSET

Causes the SQL Option run-time program to send additional information to set the current package set.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]PKGSET

Parameters:

None

Properties:

Default: NOPKGSET

Comments:

The default is NOPKGSET, which prevents additional information from being sent to the server, and any set current package set SQL command will fail.

Parent topic: XDB Directive Options


QUOTE

Causes the preprocessor to recognize double quotes to delimit literals for quote character in SQL statements.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]QUOTE

Parameters:

None

Properties:

Default: NOQUOTE

Comments:

Only set QUOTE if you are using double quotes to delimit literals in SQL statements and you have set the project BUILD settings for quote character to be APOST.

Parent topic: XDB Directive Options


SAVE-RETURN-CODE

Causes the SQL Option precompiler to save and then restore RETURN-CODE when calling SQL Option functions
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]SAVE-RETURN-CODE

Parameters:

None

Properties:

Default: SAVE-RETURN-CODE

Comments:

Use NOSAVE-RETURN-CODE if your COBOL dialect doesn't recognize the COBOL special register RETURN-CODE.

Parent topic: XDB Directive Options


SQLDA-VER

The SQLDA structure used in the program for dynamic SQL statements.
Restriction: This topic applies to Windows environments only.

Syntax:

SQLDA-VER={version}

Parameters:

version
Number to identify type of SQLDA structure used.
0 | XDB structure
1 | DB2 mainframe (Windows) or standard (UNIX) structure

Properties:

Default: 1

Comments:

Windows: Set SQLDA-VER=1 when mainframe style SQLDA's are used in the program. Also, all SQLDA structures used in the program must use the same structure. They must all be mainframe style or XDB style or an error message is generated.

UNIX: Set SQLDA-VER=0 when using old style XDB SQLDA in a program. All SQLDA structures in a given program can only use one of these structures, not both simultaneously. They must all be the standard SQLDA structure or the old XDB structure - if not, an error message is generated.

Parent topic: XDB Directive Options


SQLDS

Allows the SQL Option Server to accept a PREPARE statement before a DECLARE statement in your source code (which is allowed in SQL/DS)
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]SQLDS

Parameters:

None

Properties:

Default: NOSQLDS
Parent topic: XDB Directive Options


STRICT-DB2

Enforces strict support for certain DB2 features that are generally permitted in default DB2 mode.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]STRICT-DB2

Parameters:

None

Properties:

Default: NOSTRICT-DB2

Comments:

Mainframe DB2 does not let you declare a cursor before including the SQLCA (something allowed by the DB2 mode of SQL Option. STRICT-DB2 forces SQL Option (when running in DB2 mode) to generate an error in this circumstance. STRICT-DB2 also ensures that an SQLCA is provided by the program.

Parent topic: XDB Directive Options


TIME

Specifies the time format to be used with this program.
Restriction: This topic applies to Windows environments only.

Syntax:

TIME={time-format}

Parameters:

time-format The format in which time information is to be returned. One of:
ISO | hh.mm.ss
EUR | hh.mm.ss
JIS | hh.mm.ss
USA | hh.mm.ss AM or PM
LOCAL | format needs to be defined from the IDE, using Options > SQL for DB2.
Default: Use the default settings defined by the IDE, using Options > SQL for DB2.

Properties:

Default: Use the default settings defined by the IDE, using Options > SQL for DB2.

Comments:

Use this directive to override the default settings.

Parent topic: XDB Directive Options


VALIDATE

Causes the SQL Option preprocessor to verify all data objects referenced in your program's embedded SQL statements against the SQL Option system tables.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]VALIDATE

Parameters:

None

Properties:

Default: VALIDATE if in DB2 V6 mode or NOVALIDATE if in DB2 V5 mode (applies to Windows environments only).

Comments:

When VALIDATE is specified, the SQL Option preprocessor attempts to log on to the SQL Option Server where it checks whether SQL statements can be executed and whether all referenced tables and columns are present. Note that the SQL Option Server must be available when using VALIDATE or a COBSQ0013W error occurs.

Parent topic: XDB Directive Options


VALIDATE-ERR-LVL

Specifies the error level to use for errors produced when the VALIDATE directive is used.
Restriction: This topic applies to Windows environments only.

Syntax:

VALIDATE-ERR-LVL = (error-lvl-code)

Parameters:

error-lvl-code A one-byte character code to indicate what error level to generate when an SQL error results from validating an SQL statement. Choose from one of the following codes:
I | Informational
W | Warning
E | Error
S | Severe error
Default: W

Properties:

Default: W
Parent topic: XDB Directive Options


VALIDATE-LOGIN

Causes the SQL Option preprocessor to ensure communications with an SQL Option Server prior to attempting to validate any SQL statements. If the log in fails, a fatal error is generated.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]VALIDATE-LOGIN

Parameters:

None

Properties:

Default: NOVALIDATE-LOGIN

Comments:

The default is NOVALIDATE-LOGIN, which produces a warning message if communications with the SQL Option Server cannot be established. This directive only affects compilation, not run time.

Parent topic: XDB Directive Options


VERSION

Specifies the new version identifier for a replacement package.
Restriction: This topic applies to Windows environments only.

Syntax:

VERSION=version-id

Parameters:

version-id A valid version identifier. This can be up to 64 bits in length.

Properties:

Default: None

Comments:

This option only has meaning when program has been statically bound.

Parent topic: XDB Directive Options


XDBFUNCS

Allows use of all SQL Option commands (including SQL Option extensions) in embedded SQL.
Restriction: This topic applies to Windows environments only.

Syntax:

[NO]XDBFUNCS

Parameters:

None

Properties:

Default: NOXDBFUNCS

Comments:

The default is NOXDBFUNCS, which limits the embedded SQL functions to standard DB2 SQL functions, and does not permit SQL Option extensions.

Parent topic: XDB Directive Options


Batch SQL Commands

Restriction: This topic applies to Windows environments only.
  • Batch SQL Commands Overview
  • DISPLAY
  • DUMP
  • ERRSTOP
  • IF FAIL
  • IF SUCCEED
  • NODISPLAY
  • NOSTOP
  • SCROLL
  • TERSE
  • VERBOSE
  • WRAP
  • Examples
Parent topic: Reference


Batch SQL Commands Overview

Restriction: This topic applies to Windows environments only.

Batch SQL commands are a set of special commands that can be included in a script file to present messages, display results, and detect errors.

Batch commands can be added to your script file using the SQL Edit window or using an ASCII text editor.

Parent topic: Batch SQL Commands


DISPLAY

Restriction: This topic applies to Windows environments only.

This batch SQL command causes the system to display the query result on the Result window. Since this is the default mode, the DISPLAY command is typically used to return to normal display operation following the execution of a NODISPLAY command (see NODISPLAY command, below).

The syntax is:

DISPLAY;

The DISPLAY command must be placed immediately after the query statement on which you want it to take effect.

For example:

SELECT pno, pname FROM part WHERE color='BLUE';
DISPLAY;

When the system encounters this DISPLAY command, it displays the Result window containing the part number and name for all blue parts.

Once a DISPLAY command is executed, it will remain in effect for the rest of the script, or until a NODISPLAY command is encountered. Together, the DISPLAY and NODISPLAY commands can be used to selectively display or suppress the Result screens at certain points in the batch file.

For example:

SELECT * FROM customer
WHERE state="CA"
NODISPLAY;            --Suppress Result Screen
IF FAIL EXIT;
UPDATE customer SET balance = balance - $50
WHERE state="CA";
SELECT customer.*, orders.o_no, orders.o_date
FROM customer, orders
WHERE state = "CA";
DISPLAY;            --Display Result Screen

This example suppresses the Result window of the first query and displays it for the second.

The Display command only works when the batch script is run from SQLWizard. To see query results when running a script from a command prompt, use the Dump or Print batch SQL command to output the results to files.

Parent topic: Batch SQL Commands


DUMP

Restriction: This topic applies to Windows environments only.

This batch SQL command outputs the query result to a file

The syntax is:

DUMP file_name;

The file name specified by this command is the destination of the output of the query result. If the same file name is used in multiple DUMP commands, each query result set is appended to the one that precedes it in that file.

The DUMP command must be placed immediately after each query statement on which you want it to take effect.

For example:

SELECT * FROM customer
WHERE state="CA"
DUMP ResultSet1.out;  --Write result set to a file named ResultSet1.out

SELECT * FROM customer
WHERE state="MD"
DUMP ResultSet1.out;  --Append result set to ResultSet1.out

SELECT * FROM customer
WHERE state="NY"
DUMP ResultSet2.out;  --Write result set to a file named ResultSet2.out

The DUMP command is only effective when the batch script is run from the development environment's command prompt; it has no effect if the batch script is run from SQLWizard.

Parent topic: Batch SQL Commands


ERRSTOP

Restriction: This topic applies to Windows environments only.

This batch SQL command causes the system to pause for a keystroke when it encounters an error. Since this is the default mode, the ERRSTOP command is typically used to return to ERRSTOP operation following the execution of a NOSTOP command (see NOSTOP command, below).

The syntax is:

ERRSTOP;

The ERRSTOP command must be placed immediately after the query on which you want it to start taking effect. Once an ERRSTOP command is executed, it will remain in effect for the rest of the script, or until a NOSTOP command is encountered. Together, the ERRSTOP and NOSTOP commands can be used to selectively enable or disable error processing at certain points in the batch file.

For example:

UPDATE employee
SET com = 0
WHERE dept = "2020";
NOSTOP;          --Do not stop on error
UPDATE customer SET balance=0
WHERE balance > 0;
ERRSTOP;          --Stop on error

In this example, the system ignores errors that occur when updating the EMPLOYEE table, but stops on errors that occur when updating the CUSTOMER table.

Parent topic: Batch SQL Commands


IF FAIL

Restriction: This topic applies to Windows environments only.

This batch SQL command displays a message or terminates the batch process in the following circumstances:

  • an error occurs.
  • a query retrieves no records.
  • a DELETE, UPDATE or INSERT command affects no records.

The syntax is:

IF FAIL {"message" | EXIT };

where message is the message to be displayed upon failure. After displaying the message, the system waits for the user to press Enter or click OK before continuing with the batch file.

If EXIT is used, the system terminates the batch process when a failure occurs.

The IF FAIL command must be placed after the query statement to which it will apply. If other batch commands are associated with this statement (e.g., DISPLAY, TERSE), IF FAIL must be placed after them.

For example:

UPDATE partsupp
  SET qty=qty*1.25
  WHERE sno IN
(SELECT sno
     FROM supplier
     WHERE city = 'LONDON');
DISPLAY;
IF FAIL "No records updated. Aborting";
IF FAIL exit;

This example updates the partsupp table and displays an error message if the UPDATE command does not update any records. The second IF FAIL terminates the script after the user acknowledges the error message.

Parent topic: Batch SQL Commands


IF SUCCEED

Restriction: This topic applies to Windows environments only.

This batch SQL command displays a message or terminates the batch process if the SQL command retrieves or affects at least one record.

The syntax is:

IF SUCCEED {"message" | EXIT};

where message is the message displayed. After displaying the message, the system waits for the user to press Enter or click OK before continuing with the batch file.

If EXIT is used, the system terminates the batch process.

The IF SUCCEED command must be placed after the query statement to which it will apply. If other batch commands are associated with this statement (e.g., DISPLAY, TERSE), IF SUCCEED must be placed after them.

For example:

UPDATE partsupp
  SET qty=qty*1.25
  WHERE sno IN
(SELECT sno
     FROM supplier
     WHERE city = 'LONDON');
NODISPLAY;
IF SUCCEED "Update successful.";

This example updates the partsupp table and displays a message if the UPDATE command updates any record. Processing continues when the user acknowledges the message.

Parent topic: Batch SQL Commands


NODISPLAY

Restriction: This topic applies to Windows environments only.

This batch SQL command suppresses the query Result window. When NODISPLAY is in effect, query results are not displayed on the Result window.

The syntax is:

NODISPLAY;

The NODISPLAY command must be placed immediately after the query statement on which you want it to take effect.

For example:

SELECT pno, pname FROM part WHERE color='BLUE';
NODISPLAY;

In this example, the results of the SELECT statement will not be displayed.

Once a NODISPLAY command is executed, it will remain in effect for the rest of the script, or until a DISPLAY command is encountered. Together, the DISPLAY and NODISPLAY commands can be used to selectively display or suppress the Result windows at certain points in the batch file.

For example:

SELECT * FROM customer
WHERE state="CA";
NODISPLAY;            --Suppress Result Screen
IF FAIL EXIT;
UPDATE customer SET balance = balance - $50
WHERE state="CA";
SELECT customer.*, orders.o_no, orders.o_date
FROM customer, orders
WHERE state = "CA";
DISPLAY;            --Display Result Screen

This example suppresses the Result screen of the first query and displays it for the second.

Parent topic: Batch SQL Commands


NOSTOP

Restriction: This topic applies to Windows environments only.

This batch SQL command instructs the system to process errors without pausing for user acknowledgment.

The syntax is:

NOSTOP;

The NOSTOP command must be placed immediately after the query on which you want it to start taking effect. Once a NOSTOP command is executed, it will remain in effect for the rest of the script, or until a ERRSTOP command is encountered. Together, the ERRSTOP and NOSTOP commands can be used to selectively enable or disable error processing at certain points in the batch file.

For example:

UPDATE employee
SET com = 0
WHERE dept = "2020";
NOSTOP;          --Do not stop on error
UPDATE customer SET balance=0
WHERE balance > 0;
ERRSTOP;          --Stop on error

This example directs the system to ignore errors that occur when updating the EMPLOYEE table, but to stop on errors that occur when updating the CUSTOMER table.

Parent topic: Batch SQL Commands


SCROLL

Restriction: This topic applies to Windows environments only.

The SCROLL batch SQL command is provided for compatibility with scripts created by earlier versions of XDB Server. This command, when executed, will produce the same results as the DISPLAY command. If you are writing a new script, use DISPLAY rather than SCROLL.

Parent topic: Batch SQL Commands


TERSE

Restriction: This topic applies to Windows environments only.

The TERSE batch SQL command sets "quiet" mode. In quiet mode, SQLWizard suppresses the display of command and status messages. It also automatically responds to all prompts with a "Y." In quiet mode, only system-generated error messages are displayed. TERSE operation can be turned off by issuing the VERBOSE command.

The TERSE command must be placed immediately after the query on which you want it to start taking effect. Once a TERSE command is executed, it will remain in effect for the rest of the script, or until a VERBOSE command is encountered. Together, the TERSE and VERBOSE commands can be used to selectively enable or disable quiet mode operation at certain points in the batch file.

Parent topic: Batch SQL Commands


VERBOSE

Restriction: This topic applies to Windows environments only.

The VERBOSE batch SQL command is used to set "normal" display mode. Under normal mode, all messages, commands and prompts are displayed on the screen. Since VERBOSE is the default mode, this command is typically used to return to normal operation following the execution of a TERSE command (see TERSE command, above).

The VERBOSE command must be placed immediately after the query on which you want it to start taking effect. Once a VERBOSE command is executed, it will remain in effect for the rest of the script, or until a TERSE command is encountered. Together, the TERSE and VERBOSE commands can be used to selectively enable or disable quiet mode operation at certain points in the batch file.

Parent topic: Batch SQL Commands


WRAP

Restriction: This topic applies to Windows environments only.

The WRAP batch SQL command is provided for compatibility with scripts created by earlier versions of XDB Server. This command, when executed, produces the same results as the DISPLAY command. If you are writing a new script, use DISPLAY rather than WRAP.

Parent topic: Batch SQL Commands


Examples

Restriction: This topic applies to Windows environments only.

The example below shows a batch SQL file prompting for a host variable called hDeptName.

SELECT * from dept WHERE dname = :hDeptName;
CREATE TABLE temp
  SELECT dname, e_no, lname, fname
  FROM dept, employee
  WHERE dept.Dept = employee.Dept
  AND dept.Dname = :hDeptName;
SELECT dname, e_no, lname, fname, o_no
  FROM temp, orders
  WHERE temp.e_no = orders.s_no;
UPDATE employee
  SET payrate = payrate * 1.1
  WHERE e_no IN
  (SELECT e_no
  FROM temp);
DROP TABLE temp;

When this script is executed, the user will be prompted to enter a department name, and this value will be is substituted into the query.

The example below shows the same batch SQL file, but this one includes additional batch commands that provide display and error-processing instructions. Notice that there is a semicolon ';' at the end of each command, including the batch commands.

SELECT * from dept WHERE dname = :hDeptName;
NODISPLAY;            --Suppress Result Screen
CREATE TABLE temp
  SELECT dname, e_no, lname, fname
  FROM dept, employee
  WHERE dept.Dept = employee.Dept
  AND dept.Dname = :hDeptName;
SELECT dname, e_no, lname, fname, o_no
  FROM temp, orders
  WHERE temp.e_no = orders.s_no;
DISPLAY;            --Display Result Screen
IF FAIL "No Records Found";  --If no records selected,
IF FAIL EXIT;          --show Message and Exit
UPDATE employee
  SET payrate = payrate * 1.1
  WHERE e_no IN
  (SELECT e_no
  FROM temp);
DROP TABLE temp;
Parent topic: Batch SQL Commands


Batch Import Commands

Restriction: This topic applies to Windows environments only.
  • APPEND_ERR_FILE
  • APPEND_REC_FILE
  • ASCII_CODEPAGE (DSNTIAUL format)
  • BAD_REC_FILE
  • EBCDIC_CODEPAGE (DSNTIAUL format)
  • EBCDIC_TO_ASCII
  • ERR_LOG_FILE
  • FIELDS
  • FILENAME
  • FLD_DELIMITER (Free-format ASCII)
  • FORMAT
  • HEADING
  • INSERT_MODE
  • INS_NULL
  • NULL_PERM
  • ON_ERROR
  • OFFSETS
  • QUOTES
  • REC_DELIMITER
  • REPLACE
  • SPACES
  • SRC_LENS
  • TABLE
  • TYPES
  • USE_PIC
  • Batch Import Examples
Parent topic: Reference


APPEND_ERR_FILE

Restriction: This topic applies to Windows environments only.

Appends errors to an existing error log file. The syntax is:

APPEND_ERR_FILE = { Y | N };

If APPEND_ERR_FILE is set to Y, then errors are appended to the existing error message log file. If APPEND_ERR_FILE is set to N (default), then the old error message log file is overwritten.

The log file appended to is the one specified in the ERR_LOG_FILE command. APPEND_ERR_FILE is an optional Batch Import command.

For example:

APPEND_ERR_FILE = Y;

causes any error messages produced as a result of the Batch Import to be appended to the existing error log file.

Parent topic: Batch Import Commands


APPEND_REC_FILE

Restriction: This topic applies to Windows environments only.

Appends errors to an existing record log file. The syntax is:

APPEND_REC_FILE = { Y | N };

If APPEND_REC_FILE is set to N (default), then the old record log file is overwritten. If APPEND_REC_FILE is set to Y, then records are appended to the existing log file.

The log file appended to is the one specified in the most recent BAD_REC_FILE command. APPEND_REC_FILE is an optional Batch Import command.

For example:

APPEND_REC_FILE = Y;

causes any error messages produced as a result of the Batch Import to be appended to the existing record log file.

Parent topic: Batch Import Commands


ASCII_CODEPAGE (DSNTIAUL format)

Restriction: This topic applies to Windows environments only.

Specifies the destination character set. The syntax is:

ASCII_CODEPAGE = n

where n is the code page number.

By default, Import assumes character data is stored in a DSNTIAUL source file (using the EBCDIC character set) and converts it to the American ASCII character set by inserting it into an XDB Server table.

You can have the Import utility translate character data containing characters from any international EBCDIC character set to any international ASCII character set using the code page feature in Import. For the ASCII code page number, use the default ASCII character set for your country. EBCDIC to ASCII translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM location.

When the Import utility uses code page options, the values entered for EBCDIC_CODEPAGE and ASCII_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert DSNTIAUL data in EBCDIC format to XDB Server data in ASCII.

Parent topic: Batch Import Commands


BAD_REC_FILE

Restriction: This topic applies to Windows environments only.

Causes records containing errors to be written to the file (called the record log file) with the file name specified after this command. This command only used for fixed-format ASCII, free-format ASCII, and DSNTIAUL file formats. The syntax is:

BAD_REC_FILE = filename;

where filename is the name of the file, including extension and path, for the record log file. If you don't specify a path, the record log file is put in your current directory.

If a record contains multiple errors, a copy of that record is written to the record log file for each error.

Note:

If this batch command is used for a batch import of a file type other than DSNTIAUL, Free- or Fixed-format ASCII file, then a warning is generated as a reminder that a record log file is not generated for the import of other file types.

For example:

BAD_REC_FILE = C:\LOGFILES\BATCH.BRF;

saves records with errors to the file batch.brf.

Parent topic: Batch Import Commands


EBCDIC_CODEPAGE (DSNTIAUL format)

Restriction: This topic applies to Windows environments only.

Specifies the source character set. The syntax is:

EBCDIC_CODEPAGE = n

where n is the code page number.

By default, Import assumes character data is stored in a DSNTIAUL source file using the American EBCDIC character set and converts it to the American ASCII character set before inserting it into an XDB Server table. See "ASCII Table" for a listing of ASCII character sets.

You can have the Import utility translate character data containing characters from any international EBCDIC character set to any international ASCII character set using the code page feature in Import. For the EBCDIC code page number, use the default EBCDIC character set for your country. EBCDIC to ASCII translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM.

When the Import utility uses code page options, the values entered for EBCDIC_CODEPAGE and ASCII_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert DSNTIAUL data in EBCDIC format to XDB Server data in ASCII format.

Parent topic: Batch Import Commands


EBCDIC_TO_ASCII

Restriction: This topic applies to Windows environments only.

Specifies whether EBCDIC data should be converted to ASCII during DSNTIAUL imports. The syntax is:

EBCDIC_TO_ASCII = {Y | N | NA} [,{Y | N | NA}]...;

where the number of Ys, Ns and NAs is equal to the number of fields in the table. If EBCDIC_TO_ASCII is set to N, data are not converted to ASCII. If EBCDIC_TO_ASCII is set to Y (default), the data are assumed to be EBCDIC and are converted to the ASCII equivalent. If EBCDIC_TO_ASCII is set to NA, conversion is not applicable for the field type.

EBCDIC_TO_ASCII is an optional Batch Import command.

Note: When saving specifications for DB2 DSNTIAUL format, an EBCDIC_TO_ASCII statement is included with all fields set to Y (yes).

For example:

EBCDIC_TO_ASCII = n,n,n,n;

defines this import command so that none of the fields of a four-column table are converted to ASCII in this transaction.

Parent topic: Batch Import Commands


ERR_LOG_FILE

Restriction: This topic applies to Windows environments only.

Causes error messages from the Import batch transaction to be written to the file name specified after this command (called the error log file). The syntax is:

ERR_LOG_FILE = filename;

where filename is the name of the file, including extension and path, for the error log file.

If you don't specify a path, the error log file is put in your current directory. Error messages are still displayed on the screen. ERR_LOG_FILE is an optional batch Import command.

For example:

ERR_LOG_FILE = C:\LOGFILES\BATCH.ELF;

saves error messages to the batch.elf file.

Parent topic: Batch Import Commands


FIELDS

Restriction: This topic applies to Windows environments only.

Specifies the names of the fields for the XDB Server table being created. The syntax of the statement is:

FIELDS = field-name1 [, field-name2]. . .;

where the field names are listed in order, and separated by commas (,).

The FIELDS Batch Import command is required for every transaction when importing a file that does not include the table headings (as specified with the HEADING Batch Import command). If field names are provided in the file being imported, those names can be used as default field names. Otherwise the field names must be specified.

For example:

FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;

will import a file into a new table with field names similar to the EMPLOYEE table in the TUTORIAL location.

Parent topic: Batch Import Commands


FILENAME

Restriction: This topic applies to Windows environments only.

Specifies the path name of the source file. The syntax of the statement is:

FILENAME = filename

where filename is the full path specification and file of the source file.

For example:

FILENAME = C:\XDB\APPS\employee.asc;

specifies the location of the source file as c:\xdb\apps and the file name employee.asc.

Parent topic: Batch Import Commands


FLD_DELIMITER (Free-format ASCII)

Restriction: This topic applies to Windows environments only.

Specifies the delimiter(s) that separate the fields in delimited, free-format ASCII files. You may specify the delimiter(s) as:

  • A Character String. Quotes are optional when specifying a character string for the delimiter If desired, you may enclose the string in double quotes (" "). Quotes in a delimiter specification are ignored by the Import program. For example, "@@" is the same as @@.
  • ASCII Decimal Notation. If you specify the delimiter in ASCII decimal notation, enclose each ASCII code in angle brackets. For example, to use the decimal notation for a semicolon (;), enter the string <059> either with or without quotes.
  • Combination Character String and ASCII Code. You can mix ASCII codes with keyboard characters to form a delimiter. For example: <59>ab<32>c would be a valid delimiter. See "ASCII Table" for a list of ASCII decimal codes.

The syntax of the FLD_DELIMITER command is:

FLD_DELIMITER = {xx|<ascii1>} [xx|<ascii2>] [...];

where :

xx | is one or more keyboard characters
ascii | is an ASCII decimal code. The angle brackets around the ASCII code are required. Quote marks around delimiters are optional.

For example, to instruct the SQLWizard Import utility that your file uses a comma as the delimiter, use the command:

FLD_DELIMITER = ,;
Note:

You must determine the field delimiter prior to executing the Import function. If you specify a field delimiter that is not found in the file, the Batch Import program will abort and an error message will be displayed.

Use the Source File command from the View menu (or a text editor) to examine the file. If the field delimiter is an invisible ASCII character, you may have to use a hexadecimal editor to examine the contents of the file.

Parent topic: Batch Import Commands


FORMAT

Restriction: This topic applies to Windows environments only.

Specifies the file type of the file being imported. The syntax is:

FORMAT = source-file-type;

where source-file-type is one of the following options:

Source File Type | Used For
DSNTIAUL | IBM DSNTIAUL files
FIXASC | Fixed-format ASCII files
FREASC | Free-format ASCII files

FORMAT is a required Batch Import command for every transaction.

For example:

FORMAT = dsntiaul;

specifies the importing of a DSNTIAUL file.

Parent topic: Batch Import Commands


HEADING

Restriction: This topic applies to Windows environments only.

Specifies that the first row of the source file is a heading that contains field names for the XDB Server table being created. The syntax is:

HEADING = {Y | N}

Set HEADING equal to N if there is no heading in the source file. Set HEADING equal to Y if the first row is to be considered a heading in the source file. All other rows are treated as data.

For example:

HEADING = N;

specifies that there is no heading in the source file.

Parent topic: Batch Import Commands


INSERT_MODE

Restriction: This topic applies to Windows environments only.

Specifies use of the NORMAL, ENGINE DIRECT WRITE. The syntax is:

INSERT_MODE = { NORMAL | EDR};

where NORMAL (default) indicates regular import mode and EDR indicates ENGINE DIRECT WRITE import.

The ENGINE DIRECT WRITE import option bypasses all referential integrity and data checking features normally imposed by the XDB Server.

INSERT_MODE is an optional Batch Import command.

For example:

INSERT_MODE = EDR;

causes data to be imported using Engine Direct Write insert mode.

Parent topic: Batch Import Commands


INS_NULL

Restriction: This topic applies to Windows environments only.

Specifies whether null character data is to be inserted as null values, or blanks. The correct syntax is:

INS_NULL = { Y | N | NULLABLE };

If INS_NULL is set to NULLABLE, the null character data is imported as a NULL if the field is defined to allow null values, and as a space if the field is defined as NOT NULL.

If INS_NULL is set to N, then empty character fields are imported as a space.

If INS_NULL is set to Y (default), then a null character value is imported as a NULL. If the field is defined as NOT NULL, an error is returned if a null value is encountered.

INS_NULL is an optional Batch Import command.

For example:

INS_NULL = N;

will import null characters as spaces.

Parent topic: Batch Import Commands


NULL_PERM

Restriction: This topic applies to Windows environments only.

Specifies null permissions for a field: NULLS ALLOWED, NOT NULL, or NOT NULL WITH DEFAULT. If a table exists then this command is ignored. The syntax is:

NULL_PERM = {Y | N | D} [, {Y | N | D}] ...;

where the specification is listed in the same order as the corresponding field names, and delimited by commas.

If NULL_PERM is Y then null values are permitted in the column. If NULL_PERM is N, then the column is prevented from containing null values. If NULL_PERM is D, then null values are converted to a specified default value for the column (NOT NULL WITH DEFAULT). The default value is dependent on the data type.

For example:

NULL_PERM = n,n,n,y,y,d,d;
Parent topic: Batch Import Commands


ON_ERROR

Restriction: This topic applies to Windows environments only.

Specifies the automatic response to an error condition resulting from reading a field in a data file. The syntax is:

ON_ERROR = { SKIP | INS_NULL | QUIT | END_ALL};

If ON_ERROR is set to SKIP, a record that contains invalid data is skipped and import goes on to the next record. If ON_ERROR is set to INS_NULL then a null is placed in the field if the field is nullable. If ON_ERROR is set to QUIT, then the Batch Import will be terminated if invalid data is found. If ON_ERROR is set to END_ALL (default), then all Batch Import processing is terminated.

ON_ERROR is an optional Batch Import command.

For example:

ON_ERROR = NULL;

will cause Batch Import to place a null in a field that has caused an error, and to continue with the import despite the error.

Parent topic: Batch Import Commands


OFFSETS

Restriction: This topic applies to Windows environments only.

Specifies the starting positions of fields being imported from fixed-format ASCII files. The syntax is:

OFFSETS = start-pos1 [, start-pos2]. . .;

where the starting positions are listed in the same order as the corresponding field names, and delimited by commas.

To determine the starting positions, it might be necessary to examine the file. (Use the Source File command from the View menu, or use a text editor.) The OFFSETS Batch Import command is required for every transaction when importing a fixed-format ASCII file into XDB Server.

For example:

OFFSETS = 1,11,23,35,57,74,78,85,91,113;

specifies the starting positions of the columns in a fixed-format ASCII source file.

Parent topic: Batch Import Commands


QUOTES

Restriction: This topic applies to Windows environments only.

Used when importing free-format ASCII files to specify whether or not character strings are surrounded by double quotes. The syntax is:

QUOTES = {Y | N};

Set QUOTES to N (default) if there are no quotes around character strings in the source file. Set QUOTES to Y if the character strings in the source file are surrounded by quotes. It is common to surround character strings with double quotes in comma-delimited ASCII files. QUOTES is an optional Batch Import command.

For example:

QUOTES = Y;

will import a free-format ASCII file that has character strings enclosed in quotes.

Parent topic: Batch Import Commands


REC_DELIMITER

Restriction: This topic applies to Windows environments only.

Specifies the end-of-record delimiter used to separate records in modified free-format ASCII files. The syntax is:

REC_DELIMITER = {"xx" | "<ascii>"...};

where:

xx | is a character string delimiter
ascii | is an ASCII decimal code. The angled brackets around the ASCII code are required. The default delimiter is a space character (ASCII code <032>).

The end-of-record delimiter can be specified as a character string or in ASCII decimal notation. If the delimiter is specified in ASCII decimal notation, enclose each ASCII code in angled brackets. For example, to use the decimal notation for a semicolon, enter the string <059>.

The delimiter cannot be a character found within the data values unless the values are enclosed in quotes. The most common record delimiter found in ASCII files is a carriage return followed by a line feed.

The REC_DELIMITER Batch Import command is required for every transaction when importing free-format ASCII files into XDB Server.

For example:

REC_DELIMITER = "<013><010>";

sets the record delimiter to a carriage return/line feed combination.

Parent topic: Batch Import Commands


REPLACE

Restriction: This topic applies to Windows environments only.

Specifies whether the data being imported is to be appended to existing data in the table or is to replace it. The syntax is:

REPLACE = {Y | N};

If REPLACE is set to N (default), the imported data will appended to the existing data. If REPLACE is set to Y, the imported data will replace the data in the table.

This command is ignored if the named table does not exist; a new table is then created. The default is to append the data to the end of existing data in the table if found. REPLACE is an optional Batch Import command.

For example:

REPLACE  = N;

will append data to an existing table.

Parent topic: Batch Import Commands


SPACES

Restriction: This topic applies to Windows environments only.

Specifies the number of spaces that separate columns in a fixed-format ASCII data file. The syntax is:

SPACES = {n}

where n is some number between 0-99. The default is 2.

Parent topic: Batch Import Commands


SRC_LENS

Restriction: This topic applies to Windows environments only.

S pecifies the maximum number of spaces a field can use in a fixed-format ASCII source file being read. The syntax is:

SRC_LENS = length1 [, length2] ...;

where the lengths are listed in the same order as the corresponding field names, and delimited by commas.

When importing fixed-format ASCII files, the SRC_LENS command is used to determine the source file length. To determine the field length for ASCII files, it might be necessary to examine the files. (Use the Source File command from the View menu or a text editor.)

The SRC_LENS Batch Import command is required for every transaction when importing a fixed-format ASCII file into XDB Server.

For example:

SRC_LENS = 8,10,20,15,2,5,4,20,30;

specifies the column widths of the fixed-format ASCII source file being read.

Parent topic: Batch Import Commands


TABLE

Restriction: This topic applies to Windows environments only.

S pecifies the name of the XDB Server table to be created by Import. The syntax is:

TABLE = table-name;

where table-name is the name of the table.

If you have super-user privilege, you can qualify the table name with a different AuthID (of up to eight characters), so the table is created with a different owner. The table will be created in the current location. To create it in a different location, enter a three-part name using the format location.authid.tablename.

TABLE is a required Batch Import command for every transaction.

For example:

TABLE = salaries;

sets the name of the imported table to SALARIES.

Parent topic: Batch Import Commands


TYPES

Restriction: This topic applies to Windows environments only.

S pecifies the field types for the XDB Server table being created. The syntax is:

TYPES = field-type1 [, field-type2]. . .;

where field types are listed in the same order as corresponding field names, and delimited by commas. Valid field types are shown below. The two-letter designation defines the field type.

Symbol | Field Type | Symbol | Field Type
CH[(n)] | Char (Character) | LB | Long Varchar For Bit Data
CB[(n)] | Character For Bit Data | LG | Long Vargraphic
DT[(p[s])] | Date | MN | Money
DC | Decimal | SI | Smallint (Small Integer)
SF | Float (4-byte) | TM | Time
FL | Float | TS | Timestamp
GR | Graphic | VC[(n)] | Varchar (Variable Character)
LI | Integer | VB[(n)] | Varchar For Bit Data
LV | Long Varchar | VG[(n)] | Vargraphic
Note:

When importing ASCII files, you can specify a data type of JU (for Julian) to import Julian dates into XDB Server date fields. The system will read dates in the format yyddd (where ddd is the number of days since the beginning of the year) and write them in the regular XDB Server date format.

When specifying fields as DECIMAL, CHARACTER, VARCHAR, CHAR-FOR-BIT-DATA, VARCHAR-FOR-BIT-DATA, GRAPHIC and VARGRAPHIC, include the field length or precision and scale in parentheses immediately after the letter specifying the data type.

TYPES is a required Batch Import command for every transaction.

For example:

TYPES = ch(10),dc(10,2),dt,si;

sets the field types in the imported table to:

  • Character (10 characters field length)
  • Decimal (precision 10, scale 2)
  • Date
  • Small Integer
Parent topic: Batch Import Commands


USE_PIC

Restriction: This topic applies to Windows environments only.

S pecifies whether the format picture (specified in Options) for a DATE, TIME, DECIMAL, or MONEY field is to be used when reading source data. The syntax is:

USE_PIC = {Y | N| NA} [, {Y | N | NA}] ...;

where the specification (Y, N, or NA) is listed in the same order as the corresponding field names, and delimited by commas.

If a field specification is set to Y (default), then Import will apply the Option utility's picture format to the data in that field (be sure the data in the source file matches the PIC format you've specified). If a field specification is set to N, then Import will apply the default mask for that data type, as described in the table below.

Type | Default Picture
Time | hh:mm:ss
Date | mm/dd/yyyy
Decimal | <sign><digits>[.<digits>][E[+-]<digits>]
Money | <sign><digits>[.<digits>][E[+-]<digits>]
 | where: <sign> includes any combination of + - $ >=
 | <digits> are 0 through 9; also comma (,) if to the left of the decimal place.

For fields that are not of type DATE, TIME, DECIMAL, or MONEY, the field specification should be set to NA (not applicable).

Note:

If you know that the format of the file is the same as the SQLWizard Import defaults, you do not need to use the USE_PIC statement.

USE_PIC is an optional Batch Import command.

For example:

USE_PIC = n,n,n,n,n,n,n,n,y,y;

specifies that the ninth and tenth fields are to have profile masks applied to them.

Parent topic: Batch Import Commands


Batch Import Examples

Restriction: This topic applies to Windows environments only.

The following Batch Import command file contains examples of Batch Import transactions for the more common file formats. The [FREE ASCII] import transaction shows an example of error logging. In this example, all of the transactions are grouped into a single Batch Import file.

[DSNTIAUL]
TABLE = TUTORIAL.TUTORIAL.EMPLOYEE;
FILENAME = C:\XDBWIN\TUTORIAL\EMPLOYEE.DSN;
FORMAT = DSNTIAUL;
FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;
TYPES = si,ch(10),ch(10),ch(20),ch(15),ch(2),ch(5),
  ch(4),dc(15,2),dc(2,2);
NULL_PERM = n,n,n,y,y,y,y,y,y,y;
USE_PIC = na,na,na,na,na,na,na,na,y,y;
INS_NULL = n,n,n,y,y,y,y,y,y,y;
EBCDIC_TO_ACSII = y,y,y,y,y,y,y,y,y,y;
REPLACE = y;
INSERT_MODE = normal;
[FREE ASCII]
TABLE = TUTORIAL.TUTORIAL.EMPLOYEE;
FILENAME = C:\XDBWIN\TUTORIAL\EMPLOYEE.FRE;
FORMAT = FREASC;
FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;
TYPES = si,ch(10),ch(10),ch(20),ch(15),ch(2),ch(5),ch(4),
  dc(15,2),dc(2,2);
NULL_PERM = n,n,n,y,y,y,y,y,y,y;
USE_PIC = na,na,na,na,na,na,na,na,y,y;
INS_NULL = n,n,n,y,y,y,y,y,y,y;
HEADING = y;
QUOTES = y;
FLD_DELIMITER = "@";
REC_DELIMITER = "<013><010>";
REPLACE = y;
INSERT_MODE = normal;
ERR_LOG_FILE = c:\xdbwin\tutorial\errors.log;
APPEND_ERR_FILE = y;
BAD_REC_FILE = c:\xdbwin\tutorial\freerecs.log;
APPEND_REC_FILE = n;
[Fixed ASCII]
TABLE = TUTORIAL.TUTORIAL.EMPLOYEE;
FILENAME = C:\XDBWIN\TUTORIAL\EMPLOYEE.FIX;
FORMAT = FIXASC;
FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;
TYPES = si,ch(10),ch(10),ch(20),ch(15),ch(2),ch(5),ch(4),
  dc(15,2),dc(2,2);
NULL_PERM = n,n,n,y,y,y,y,y,y,y;
USE_PIC = na,na,na,na,na,na,na,na,y,y;
INS_NULL = n,n,n,y,y,y,y,y,y,y;
HEADING = y;
SPACES = 2;
OFFSETS = 1,11,23,35,57,74,78,85,91,114;
SRC_LENS = 8,10,10,20,15,2,5,4,21,4;
REPLACE = y;
INSERT_MODE = normal;
Parent topic: Batch Import Commands


Batch Export Commands

Restriction: This topic applies to Windows environments only.
  • APPEND_ERR_FILE
  • ASCII_CODEPAGE (DSNTIAUL format)
  • EBCDIC_CODEPAGE (DSNTIAUL format)
  • ERR_LOG_FILE
  • FIELDS
  • FILENAME
  • FLD_DELIMITER
  • FORMAT
  • HEADING
  • ON_ERROR
  • QUERY
  • QUOTES
  • REC_DELIMITER
  • REPLACE
  • SPACES
  • SQL_OPTS
  • TABLE
  • WHERE
  • Batch Export Examples
Parent topic: Reference


APPEND_ERR_FILE

Restriction: This topic applies to Windows environments only.

Appends errors to an existing error log file. The syntax is:

APPEND_ERR_FILE = { Y | N };

If APPEND_ERR_FILE is set to Y, then errors are appended to the existing error log file. If APPEND_ERR_FILE is set to N (default), then the old error log file is overwritten.

The log file appended to is the one specified in the recent ERR_LOG_FILE command. APPEND_ERR_FILE is an optional Batch Export command.

For example:

APPEND_ERR_FILE = Y;

causes any error messages produced as a result of the Batch Export to be appended to the existing error log file.

Parent topic: Batch Export Commands


ASCII_CODEPAGE (DSNTIAUL format)

Restriction: This topic applies to Windows environments only.

Specifies the ASCII character set. The syntax is:

ASCII_CODEPAGE = n

where n is the code page number.

By default, Export assumes character data is stored in a DSNTIAUL source file using the American ASCII character set and converts it into the American EBCDIC character set by inserting it into a DSNTIAUL target file.

You can have the Export utility translate character data containing characters from any international ASCII character set to any international EBCDIC character set using the code page feature in Export. For the ASCII code page number, use the default ASCII character set for your country. ASCII to EBCDIC translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM location.

When the Export utility uses code page options, the values entered for ASCII_CODEPAGE and EBCDIC_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert XDB Server data in ASCII format to DSNTIAUL data in EBCDIC format.

Parent topic: Batch Export Commands


EBCDIC_CODEPAGE (DSNTIAUL format)

Restriction: This topic applies to Windows environments only.

Specifies the EBCDIC character set. The syntax is:

EBCDIC_CODEPAGE = n

where n is the code page number.

By default, Export assumes character data is stored in a DSNTIAUL source tables using the American ASCII character set and converts it to the American EBCDIC character set inserting it into an XDB Server table.

You can have the Export utility translate character data containing characters from any international ASCII character set to any international EBCDIC character set using the code page feature in Export. For the EBCDIC code page number, use the default EBCDIC character set for your country. ASCII to EBCDIC translation is performed using the translation table that corresponds to the specific ASCII and EBCDIC code pages. This translation table is in the TRANSTAB field of the SYSIBM.SYSSTRINGS table in the SYSTEM. See the section titled "Code Page Support" for the structure of the SYSIBM.SYSSTRINGS table.

When the Export utility uses code page options, the values entered for ASCII_CODEPAGE and EBCDIC_CODEPAGE are compared with values for INCCSID and OUTCCSID, respectively, in the system table SYSIBM.SYSSTRINGS. The matching record in the table contains the translation table used to convert XDB Server data in ASCII format to DSNTIAUL data in EBCDIC format.

Parent topic: Batch Export Commands


ERR_LOG_FILE

Restriction: This topic applies to Windows environments only.

Causes error messages from the Export batch transaction to be written to the filename specified after this command (called the error log file). The syntax is:

ERR_LOG_FILE = filename;

where filename is the name of the file, including extension and path, for the error log file.

If you don't specify a path, the error log file is put in your current directory. Error messages are still displayed on the screen. ERR_LOG_FILE is an optional Batch Export command.

For example:

ERR_LOG_FILE = C:\LOGFILES\BATCH.ELF;

saves error messages to the batch.elf file.

Parent topic: Batch Export Commands


FIELDS

Restriction: This topic applies to Windows environments only.

Specifies the names of the fields for the XDB Server table being created. The syntax of the statement is:

FIELDS = field-name1 [, field-name2]. . .;

where the field names are listed in order, and separated by commas (,).

The FIELDS command is optional if you are creating your own Batch Export file and you are querying all fields in a table. If specific fields are being queried, those fields must be specified using the FIELDS command.

For example:

FIELDS = e_no,lname,fname,street,city,st,zip,dept,payrate,com;

will export a file into a new table with field names similar to the EMPLOYEE table in the tutorial.

Parent topic: Batch Export Commands


FILENAME

Restriction: This topic applies to Windows environments only.

Specifies the destination directory and file name for the target file produced by the export transaction. The syntax is:

FILENAME = filename

where filename is the full path specification and filename for the target file.

For example:

FILENAME= A:\filename;
Parent topic: Batch Export Commands


FLD_DELIMITER

Restriction: This topic applies to Windows environments only.

Specifies the delimiter used to separate fields in free-format ASCII files. The default delimiter is a comma. The syntax is:

FLD_DELIMITER = {"xx" | "<ascii>"...};

where:

xx | is a character string delimiter
ascii | is an ASCII decimal code.

Delimiters can be specified as a character string or in ASCII decimal notation. If the delimiter is specified as a character string it must be enclosed in double-quotation marks (" "). If the delimiter is specified in ASCII decimal notation, enclose each ASCII code in angled brackets. For example, to use the decimal notation for a semicolon, enter the string <59>. (The angled brackets around the ASCII code are required.)

Note:

You must determine the field delimiter prior to executing the Export function. If you specify a field delimiter that is not found in the file, the Batch Export program will abort and an error message will be displayed.

Use the Target File command from the View menu (or a text editor) to examine the file. If the field delimiter is an nonvisible ASCII character, you may have to use a hexadecimal editor to examine the contents of the file.

Take care not to choose a character found in your data as a delimiter. For example, do not use a comma as the delimiter if your data contains numeric or money fields grouped with a comma.

For example:

FLD_DELIMITER = ",";

separates the data with a comma.

Parent topic: Batch Export Commands


FORMAT

Restriction: This topic applies to Windows environments only.

Specifies the file type you are exporting to. The syntax is:

FORMAT = target-file-type;

where target-file-type is one of the following options:

Target File Type | Used For
FIXASC | Fixed-format ASCII files
FREASC | Free format ASCII files
DSNTIAUL | IBM DSNTIAUL files
SQL | SQL statements

This statement is required for each Batch Export transaction.

For example:

FORMAT = fixasc;

sets the export file type to fixed-format ASCII.

Parent topic: Batch Export Commands


HEADING

Restriction: This topic applies to Windows environments only.

Specifies whether the field names are to be included in the first row of free or fixed-format ASCII files. The syntax is:

HEADING = {Y | N};

If HEADING is set to N, then no heading is included in the target file. When HEADING is set to Y (default), the column headings are included as the first record of the file.

For example:

HEADING = N;

will prevent a heading from being included in the target file.

Parent topic: Batch Export Commands


ON_ERROR

Restriction: This topic applies to Windows environments only.

Specifies the automatic response to an error condition resulting from reading a field in a data file. The syntax is:

ON_ERROR = {CONTINUE | QUIT | END_ALL};

If ON_ERROR is set to CONTINUE, then Batch Export will try to recover from any error that occurs. If ON_ERROR is set to QUIT (default), then Batch Export will quit if any errors occur. If ON_ERROR is set to END_ALL, then Batch Export terminates.

For example:

ON_ERROR = CONTINUE;

will cause Batch Export to try to recover from any errors.

Parent topic: Batch Export Commands


QUERY

Restriction: This topic applies to Windows environments only.

Used to hold an SQL SELECT statement that the export is based on. The syntax is:

QUERY = SELECT dept, dname, mgr FROM dept
WHERE dname = "sales" AND mgr > 5;

In the syntax example above, the dept, dname, and mgr fields are selected from the DEPT table only when the dname field is equal to sales and the mgr field is greater than five. This allows specific information to be exported from the selected table.

Parent topic: Batch Export Commands


QUOTES

Restriction: This topic applies to Windows environments only.

Used when exporting free-format ASCII files to specify whether or not character strings are to be surrounded by double quotes. The syntax is:

QUOTES = {Y | N};

If QUOTES is set to N (default), then quotes will not be placed around character strings. If QUOTES is set to Y, then character strings will be surrounded by quotes.

Surrounding character strings with double quotes is a common practice in the creation of comma-delimited ASCII files.

For example:

QUOTES = Y;

will cause the data in the exported file to be enclosed in quotes.

Parent topic: Batch Export Commands


REC_DELIMITER

Restriction: This topic applies to Windows environments only.

Specifies the delimiter for free-format ASCII export types. The syntax is:

REC_DELIMITER = {'xx' | "<ascii>"};

where:

xx | is a character string delimiter
ascii | is an ASCII decimal code. The angled brackets around the ASCII code are required. The default delimiter is a space character (ASCII code <032>).

The end-of-record delimiter can be specified as a character string or in ASCII decimal notation. If the delimiter is specified in ASCII decimal notation, enclose each ASCII code in angled brackets. For example, to use the decimal notation for a semicolon, enter the string <059>.

The delimiter cannot be a character found within the data values unless the values are enclosed in quotes. The most common record delimiter found in ASCII files is a carriage-return, followed by a line-feed.

The REC_DELIMITER Batch Export command is required for every transaction when exporting Free ASCII files to XDB Server.

For example:

REC_DELIMITER = "<013><010>";

sets the record delimiter to a carriage-return/line-feed combination.

Parent topic: Batch Export Commands


REPLACE

Restriction: This topic applies to Windows environments only.

Specifies that the data being exported is to replace the current contents of the destination file. The syntax is:

REPLACE = {Y | N};

If REPLACE is set to N (default), then if the destination file exists, the data is appended. If REPLACE is set to Y, then the data in the target file will be replaced.

If no file of the same name exists, the data in the table being exported will be placed in a newly created file regardless of the parameter specified with the REPLACE command. If the REPLACE command is not included, and the destination file already exists, the data is appended to the file.

This statement is supported for the following formats:

  • Free ASCII
  • Fixed ASCII
  • SQL

With all other formats, the file is replaced instead of being appended to regardless of how REPLACE is set.

For example:

REPLACE = Y;

will cause the exported file to overwrite any existing file with the same name.

Parent topic: Batch Export Commands


SPACES

Restriction: This topic applies to Windows environments only.

Specifies the number of spaces the separate columns in a Fixed ASCII target file. The syntax is:

SPACES = n;

where n is an integer corresponding to the number of spaces (between 0 and 99) to insert between the columns of data. The default is 2.

For example:

SPACE = 1;

will ensure that one space is placed between every field in the exported file.

Parent topic: Batch Export Commands


SQL_OPTS

Restriction: This topic applies to Windows environments only.

Used to specify which SQL statements should be generated when the SQL export type is chosen. The syntax is:

SQL_OPTS = statement-type [, statement-type, ...];

where statement-type is one of the types shown in the table below.

Statement type | SQL Statement
CREATE | CREATE TABLE and CREATE VIEW commands
INSERT | INSERT INTO commands
INDEX | CREATE INDEX commands
SYNONYM | CREATE SYNONYM commands
CHECK | ALTER TABLE ... CHECK commands
COMMENT | COMMENT ON commands

For example:

SQL_OPTS = CREATE, INDEX;

selects CREATE TABLE, CREATE VIEW, and CREATE INDEX SQL commands for use in the target file.

Parent topic: Batch Export Commands


TABLE

Restriction: This topic applies to Windows environments only.

Specifies the name of the XDB Server table or view to be exported. The syntax is:

TABLE = table-name;

where table-name is the name of the XDB Server table or view.

If you are have super-user privilege, you can qualify the table name with a different AuthID (of up to eight characters), so the table is created with a different owner. The table will be created in the current location. To create it in a different location, enter a three-part name using the format location.authid.tablename.

TABLE is a required command for every transaction.

For example:

TABLE = employee;

causes data from the EMPLOYEE table to be exported.

Parent topic: Batch Export Commands


WHERE

Restriction: This topic applies to Windows environments only.

Used with a SELECT statement to specify search criteria for retrieving rows of data from a table or group of tables. The syntax is:

WHERE search-condition;

The WHERE clause can also be used with DELETE and UPDATE. For example:

WHERE city = "Columbia" OR "Annapolis";

will cause all records that have a city of Columbia or Annapolis to be pulled from the table and exported into the desired target file.

Parent topic: Batch Export Commands


Batch Export Examples

Restriction: This topic applies to Windows environments only.

The following Batch Export file contains examples of transactions for each file type. All the transactions are contained into a single file.

[FREE ASCII]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.FRE;
FORMAT = FREASC;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
HEADING = y;
QUOTES = y;
FLD_DELIMITER = ",";
REC_DELIMITER = "<013><010>";
ON_ERROR = CONTINUE;
ERR_LOG_FILE = c:\xdbwin\tutorial\errors.log;
APPEND_ERR_FILE = y;
[FIXED ASCII]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.FIX;
FORMAT = FIXASC;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
HEADING = y;
SPACES = 2;
ON_ERROR = CONTINUE;
ERR_LOG_FILE = c:\xdbwin\tutorial\errors.log;
APPEND_ERR_FILE = y;
[DSNTIAUL]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.DSN;
FORMAT = DSNTIAUL;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
[SQL Statement]
TABLE = SYSTEM.TUTORIAL.QMT_STAFF;
WHERE = "YEARS <= 3";
FILENAME = C:\XDBWIN\SYSTEM\QMT_STAFF.SQL;
FORMAT = SQL;
REPLACE = y;
FIELDS = EMPID,LNAME,FNAME,DEPARTMENT,JOB,YEARS;
SQL_OPTS = INSERT,CHECK,COMMENT;
Parent topic: Batch Export Commands


SQL Option for DB2 Error Messages

Restriction: This topic applies to Windows environments only.
  • COBSQ - SQL ECM Preprocessor Error Messages
  • L - Link Error Messages
  • N - Network Error Messages
  • PIC - Picture Error Messages
  • SQL - SQL PL/I Precompiler Error Messages
  • WADM - SQLWizard Administrator Error Messages
  • WCRT - SQL Wizard Create/Alter Table Error Messages
  • WDG - SQL Wizard Declaration Generator Error Messages
  • WE - SQL Wizard Export Error Messages
  • WI - SQL Wizard Import Error Messages
  • WSQL - SQL Wizard Interactive SQL Error Messages
  • X - Engine Error Messages
  • XMIG - Migrate Error Messages
  • XU - Library Error Messages
Parent topic: Reference
Related information
Data Related


COBSQ - SQL ECM Preprocessor Error Messages

Restriction: This topic applies to Windows environments only.
  • COBSQ0000 - COBSQ0099
    Lists the SQL ECM error messages from COBSQ0000 through COBSQ0099.
  • COBSQ0100 - COBSQ0149
    Lists the SQL ECM error messages from COBSQ0100 through COBSQ0149.
  • COBSQ0150 - COBSQ0199
    Lists the SQL ECM error messages from COBSQ0150 through COBSQ0199.
  • COBSQ0200 - COBSQ0399
    Lists the SQL ECM error messages from COBSQ0200 through COBSQ0399.
  • COBSQ0400 - COBSQ0499
    Lists the SQL ECM error messages from COBSQ0400 through COBSQ0499.
  • COBSQ0900 - COBSQ0999
    Lists the SQL ECM error messages from COBSQ0900 through COBSQ0999.
Parent topic: SQL Option for DB2 Error Messages


COBSQ0000 - COBSQ0099

Lists the SQL ECM error messages from COBSQ0000 through COBSQ0099.
Restriction: This topic applies to Windows environments only.
  • COBSQ0002: token is badly defined
  • COBSQ0003 Program contains more than one definition of token
  • COBSQ0004 Nested or multi-source programs not allowed.
  • COBSQ0005: An error occurred whilst processing the internal dictionary.
  • COBSQ0006 No DB engine could be found.
  • COBSQ0007 Source file name is invalid.
  • COBSQ0012: Host variable used without a colon.
  • COBSQ0013: Login failed. : program-name.
  • COBSQ0015 Host variables data types in UNION do not match.
  • COBSQ0016 This statement will Delete an entire table
  • COBSQ0017 HostVariable is not preceded by a colon.
  • COBSQ0018 SQL statement not currently supported - converted to comment.
  • COBSQ0019 Operation is assumed to apply to Allocate Cursor.
  • COBSQ0021 SQL Option must be selected and available
  • COBSQ0024 EXEC SQL statement found within COPY statement, COPY directive not set. May cause compile error on mainframe.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0100 - COBSQ0149

Lists the SQL ECM error messages from COBSQ0100 through COBSQ0149.
Restriction: This topic applies to Windows environments only.
  • COBSQ0101: Expected token1 found token2.
  • COBSQ0102: Host variable mismatch.
  • COBSQ0104: Illegal symbol variable.
  • COBSQ0106: variable Invalid/Not Declared
  • COBSQ0107: INTO not allowed for DECLARE.
  • COBSQ0110: No INTO clause specified.
  • COBSQ0111: No FROM clause specified.
  • COBSQ0112: Invalid positioning of FROM.
  • COBSQ0114: Invalid file name.
  • COBSQ0115: Token array overflow.
  • COBSQ0117: Invalid in data division.
  • COBSQ0118: Invalid WHENEVER.
  • COBSQ0120: Not valid in current compatibility mode.
  • COBSQ0124: Group variable token is not allowed in the WHERE clause.
  • COBSQ0125: Cursor not found.
  • COBSQ0126: A _ is illegal in a host variable.
  • COBSQ0127: A ( is illegal in the INTO clause.
  • COBSQ0131: SQLCA not found OR comp/comp-5 mixup in SQLCA.
  • COBSQ0135: Host variable type mismatch.
  • COBSQ0137: Indicator variable token is not SMALLINT type.
  • COBSQ0138: The length of a host variable on CONNECT is greater than 16.
  • COBSQ0141: PREPARE before DECLARE is illegal.
  • COBSQ0144: Statement not identified.
  • COBSQ0147: Multiple INTO's only allowed with a UNION.
  • COBSQ0149: Illegal token found on CONNECT line.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0150 - COBSQ0199

Lists the SQL ECM error messages from COBSQ0150 through COBSQ0199.
Restriction: This topic applies to Windows environments only.
  • COBSQ0151: Cursor already DECLARED.
  • COBSQ0154: Login failed.
  • COBSQ0163: Invalid Cursor name
  • COBSQ0164: Syntax error in INTO Clause
  • COBSQ0170: Login failed. Unable to VALIDATE SQL
  • COBSQ0184 Illegal token ':' found. Check to see if previous token was an indicator variable.
  • COBSQ0185 Syntax error, last symbol read is token.
  • COBSQ0189 'ORDER BY' clause not permitted.
  • COBSQ0190 GROUP BY clause on a SELECT INTO will not bind.
  • COBSQ0191 HAVING clause on a SELECT INTO will not bind.
  • COBSQ0198: DB2 emulation mismatch - SERVER is in DB2 V6 mode
  • COBSQ0199: DB2 emulation mismatch - SERVER is in DB2 V5 mode
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0200 - COBSQ0399

Lists the SQL ECM error messages from COBSQ0200 through COBSQ0399.
Restriction: This topic applies to Windows environments only.
  • COBSQ0201 Illegal token variable found on SET line.
  • COBSQ0202 Number of host variables specified in UNION do not match.
  • COBSQ0299 Internal EXEC SQL statement table overflow - use directive MAXSQL to override default.
  • COBSQ0312 Undefined or unusable host variable token
  • COBSQ0324 SQLDA fields defined with incompatible fields for XDB OPTIMIZE directive setting.
  • COBSQ0325 Multiple types of SQLDA's detected - all SQLDA's must use same structure.
  • COBSQ0326 SQL statements not supported in nested subroutine.
  • COBSQ0327 Invalid BLOCKING option specified – valid options are: FSR, SR, or LB.
  • COBSQ0328 Invalid DEFAULT-CHAR option specified – valid options are: BITS, SBCS, DBCS, or SYSDEFAULT.
  • COBSQ0329 Invalid EXIST-CHECK option specified – valid options are: REQUIRED or OPTIONAL.
  • COBSQ0330 Required directive AUTOBIND not specified with directive directive.
  • COBSQ0331 Invalid DATE format specified - valid options are: ISO, EUR, JIS, USA or LOCAL.
  • COBSQ0332 Invalid TIME format specified - valid options are: ISO, EUR, JIS, USA or LOCAL.
  • COBSQ0333 Invalid number of values specified, maximum is 10 per option: token .
  • COBSQ0334 Only one DBRM specified when multiple other directives specified for AUTOBIND.
  • COBSQ0335 No collection-id specified, option required for AUTOBIND.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0400 - COBSQ0499

Lists the SQL ECM error messages from COBSQ0400 through COBSQ0499.
Restriction: This topic applies to Windows environments only.
  • COBSQ0401 Statement is too long.
  • COBSQ0402 Statement contains too many host variables.
  • COBSQ0403 variable does not have a suitable definition to be used as a host variable.
  • COBSQ0404 Bad SQL data declaration.
  • COBSQ0405 Syntax error.
  • COBSQ0406 Filename too long.
  • COBSQ0407 File token not found.
  • COBSQ0408 token is non-unique and should be qualified.
  • COBSQ0409: token is not a data item
  • COBSQ0410 Statement contains more than one SQLDA.
  • COBSQ0411 token is not a table of null indicator variables.
  • COBSQ0412 token should not be a defined with an OCCURS clause.
  • COBSQ0413 token should not be a subordinate to an item defined with an OCCURS clause.
  • COBSQ0415 Statement not allowed in the PROCEDURE DIVISION.
  • COBSQ0416 An error occurred whilst processing the trace file.
  • COBSQ0418 Mismatched DECLARE.
  • COBSQ0419 Host variable name is too long.
  • COBSQ0420 Internal error - dictionary handle is too big.
  • COBSQ0422 Nested INCLUDE's not supported.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


COBSQ0900 - COBSQ0999

Lists the SQL ECM error messages from COBSQ0900 through COBSQ0999.
Restriction: This topic applies to Windows environments only.
  • COBSQ0900 An internal error occurred. Create a trace file using the compiler directive CHKECM(TRACE) and contact your support representative.
  • COBSQ0901 This error prevents SQL processing from continuing - further EXEC SQL statements will be ignored.
Parent topic: COBSQ - SQL ECM Preprocessor Error Messages


L - Link Error Messages

Restriction: This topic applies to Windows environments only.
  • L000 - L099
    Lists the Link error messages from L000 through L099.
  • L100 - L149
    Lists the Link error messages from L100 through L149.
  • L150 - L199
    Lists the Link error messages from L150 through L199.
  • L200 - L299
    Lists the Link error messages from L200 through L299.
  • L300 - L399
    Lists the Link error messages from L300 through L399.
  • L400 - L449
    Lists the Link error messages from L400 through L449.
  • L450 - L499
    Lists the Link error messages from L450 through L499.
  • L500 - L549
    Lists the Link error messages from L500 through L549.
  • L550 - L599
    Lists the Link error messages from L550 through L599.
  • L600 - L649
    Lists the Link error messages from L600 through L649.
  • L650 - L699
    Lists the Link error messages from L650 through L699.
  • L700 - L799
    Lists the Link error messages from L700 through L799.
  • L800 - L899
    Lists the Link error messages from L800 through L899.
  • L900 - L999
    Lists the Link error messages from L900 through L999.
  • L1000 - L1099
    Lists the Link error messages from L1000 through L1099.
  • L30000 - L30099
    Lists the Link error messages from L30000 through L30099.
Parent topic: SQL Option for DB2 Error Messages


L000 - L099

Lists the Link error messages from L000 through L099.
Restriction: This topic applies to Windows environments only.
  • L007: Statement contains the illegal character character.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -007, for information.
  • L010: The string constant beginning character is not terminated.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -010, for information.
  • L029: INTO clause required.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -029, for information.
  • L060: Invalid type specification: spec.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -060, for information.
  • L084: UNACCEPTABLE SQL STATEMENT.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -084, for information.
Parent topic: L - Link Error Messages


L100 - L149

Lists the Link error messages from L100 through L149.
Restriction: This topic applies to Windows environments only.
  • L101: The statement is too long or too complex.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -101, for information.
  • L102: Size of string constant starting string is too great.
    See the Error SQLCODES section of your IBM Database Messages and Codes Manual, message -102, for information.
  • L103: literal is an invalid numeric literal.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -103, for information.
  • L104: Illegal symbol token. Valid symbols are token-list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -104, for information.
  • L105: Invalid string.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -105, for information.
  • L107: The name name is too long. Maximum allowable size is size.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -107, for information.
  • L108: THE NAME name IS QUALIFIED INCORRECTLY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -108, for information.
  • L109: clause clause is not permitted.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -109, for information.
  • L110: Invalid hex literal beginning string.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -110, for information.
  • L111: A column function does not include a column name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -111, for information.
  • L112: The operand of a column function is another column function.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -112, for information.
  • L113: Invalid character found in name: name. Reason code - reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -113, for information.
  • L114: THE LOCATION NAME location DOES NOT MATCH THE CURRENT SERVER
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -114, for information.
  • L115: A predicate is invalid because operation operation is followed by a list, any or all.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -115, for information.
  • L117: The number of insert values is not the same as the number of object columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -117, for information.
  • L118: The object table or view of the insert/delete/update is in a FROM clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -118, for information.
  • L119: A column in a HAVING clause is not included in the GROUP BY clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -119, for information.
  • L120: A WHERE clause or a SET clause includes a column function.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -120, for information.
  • L121: Column name is used more than once in insert or update.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -121, for information.
  • L122: Select with no GROUP BY has column name/function or a column name not in GROUP BY.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -122, for information.
  • L123: THE PARAMETER IN POSITION n IN THE FUNCTION name MUST BE A CONSTANT OR KEYWORD
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -123, for information.
  • L125: An integer in the ORDER BY clause does not identify a column of the result.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -125, for information.
  • L126: The SELECT statement contains both an UPDATE clause and an ORDER BY clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -126, for information.
  • L127: Distinct is specified more than once in a subselect.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -127, for information.
  • L128: Invalid use of NULL in a predicate.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -128, for information.
  • L129: The statement contains too many table names.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -129, for information.
  • L130: Escape clause with more than one char or string contains invalid esc char.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -130, for information.
  • L131: Statement with LIKE predicate has incompatible data types.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -131, for information.
  • L132: AN OPERAND OF value IS NOT VALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -132, for information.
  • L133: Column function in subquery of HAVING invalid because expression applies op to corr ref.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -133, for information.
  • L134: IMPROPER USE OF LONG STRING COLUMN column-name OR AN EXPRESSION OF MAXIMUM LENGTH GREATER THAN 255.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -134, for information.
  • L136: Sort cannot be executed because sort key length > 4000 bytes.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -136, for information.
  • L137: THE LENGTH RESULTING FROM operation IS GREATER THAN maximum-length
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -137, for information.
  • L138: The second or third argument of the SUBSTR function is out of range.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -138, for information.
  • L142: THE SQL STATEMENT IS NOT SUPPORTED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -142, for information.
  • L144: Invalid section number number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -144, for information.
  • L147: ALTER FUNCTION function-name FAILED BECAUSE SOURCE FUNCTIONS CANNOT BE ALTERED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -147, for information.
  • L148: THE SOURCE TABLE source-name CANNOT BE RENAMED OR ALTERED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -148, for information.
Parent topic: L - Link Error Messages


L150 - L199

Lists the Link error messages from L150 through L199.
Restriction: This topic applies to Windows environments only.
  • L150: The INSERT, DELETE or UPDATE object is a view and is not permitted.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -150, for information.
  • L151: Update is invalid because the descr of column name cannot be updated.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -151, for information.
  • L152: THE DROP clause CLAUSE IN THE ALTER STATEMENT IS INVALID BECAUSE constraint-name IS A constraint-type
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -152, for information.
  • L153: The CREATE VIEW statement does not include a required column list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -153, for information.
  • L154: CREATE VIEW failed because definition with union, union all, or remote object.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -154, for information.
  • L156: The statement does not identify a table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -156, for information.
  • L157: name is not the name of a table needed for a foreign key clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -157, for information.
  • L158: Number of columns specified for view is not equal to number of columns in select.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -158, for information.
  • L159: DROP or COMMENT ON token identifies a(n) token.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -159, for information.
  • L160: The WITH CHECK OPTION cannot be used for the specified view.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -160, for information.
  • L161: INSERT or UPDATE not allowed because result row does not satisfy view definition.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -161, for information.
  • L164: authid does not have privilege to create a view with qualification authorization.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -164, for information.
  • L170: The number of arguments specified for function is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -170, for information.
  • L171: The data type, length, or value of argument argument of function is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -171, for information.
  • L173: UR IS SPECIFIED ON THE WITH CLAUSE BUT THE CURSOR IS NOT READ-ONLY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -173, for information.
  • L180: The string representation of a datetime value has invalid syntax.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -180, for information.
  • L181: The string representation of a datetime value is not a valid datetime value.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -181, for information.
  • L182: An arithmetic expression with a datetime value is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -182, for information.
  • L183: Arithmetic operation on date or timestamp has result not in valid range.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -183, for information.
  • L184: Arithmetic expression with a datetime value contains a parameter marker.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -184, for information.
  • L185: Local format option was used with date or time with no local exit.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -185, for information.
  • L186: Local date or time length was increased and the execute program uses old length.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -186, for information.
  • L187: Reference to a current date/time special register is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -187, for information.
  • L188: The string representation of a name is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -188, for information.
  • L189: CCSID ccsid is unknown or invalid for the data type or subtype.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -189, for information.
  • L190: ATTRIBUTES OF column-name IN table-name ARE NOT COMPATIBLE WITH EXISTING COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -190, for information.
  • L191: A string cannot be used because it is invalid mixed data.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -191, for information.
  • L197: QUALIFIED NAMES IN ORDER BY NOT PERMITTED WITH UNION OR UNION ALL
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -197, for information.
  • L198: Operand of the PREPARE or EXECUTE IMMEDIATE statement is blank or empty.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -198, for information.
  • L199: Illegal use of keyword keyword. Token token was expected.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -199, for information.
Parent topic: L - Link Error Messages


L200 - L299

Lists the Link error messages from L200 through L299.
Restriction: This topic applies to Windows environments only.
  • L203: A reference to column name is ambiguous.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -203, for information.
  • L204: name is an undefined name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -204, for information.
  • L205: col is not a column of table tablename.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -205, for information.
  • L206: name is not a column of a table in an INSERT, UPDATE or FROM clause.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -206, for information.
  • L207: ORDER BY invalid because the column name applies to result of UNION or UNION ALL.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -207, for information.
  • L208: ORDER BY invalid because column name is not part of the result table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -208, for information.
  • L212: name IS MULTIPLY SPECIFIED IN TRIGGER REFERENCING CLAUSE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -212, for information.
  • L219: The required explanation table name does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -219, for information.
  • L220: Column name in explanation table name is not defined properly.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -220, for information.
  • L221: "opt cols" in explanation table name is incomplete. Opt col name is missing.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -221, for information.
  • L240: THE PART CLAUSE OF A LOCK TABLE STATEMENT IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -240, for information.
  • L250: Local location name is not defined when procession a 3-part object name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -250, for information.
  • L251: Token name is not valid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -251, for information.
Parent topic: L - Link Error Messages


L300 - L399

Lists the Link error messages from L300 through L399.
Restriction: This topic applies to Windows environments only.
  • L301: Value of input host variable number number not used because wrong data type.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -301, for information.
  • L302: Value of input variable number number is invalid for the target column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -302, for information.
  • L303: Cannot assign value to output host variable number number. Types not comparable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -303, for information.
  • L304: Value with data type type cannot go in host variable at position number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -304, for information.
  • L305: Output host variable number number cannot be NULL when there is no indicator.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -305, for information.
  • L309: Predicate is invalid because a referenced host variable has the NULL value.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -309, for information.
  • L310: DECIMAL HOST VARIABLE OR PARAMETER number CONTAINS NON-DECIMAL DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -310, for information.
  • L311: Length of input host variable number number is negative or greater than the max.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -311, for information.
  • L312: Undefined or unusable host variable name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -312, for information.
  • L313: Number of host variables specified "< >" to number of parameter markers.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -313, for information.
  • L314: The statement contains an ambiguous host variable reference.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -314, for information.
  • L327: CANNOT INSERT ROW BECAUSE IT IS OUTSIDE THE BOUND OF THE PARTITION RANGE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -327, for information.
  • L330: String cannot be translated. Reason reason, char code-point, host var number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -330, for information.
  • L331: String cannot be assigned to a host variable. Reason reason, char code-point, pos number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -331, for information.
  • L332: SYSSTRINGS does not define a translation CCSID ccsid to ccsid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -332, for information.
  • L333: String variable subtype not same as bind time and diff cannot be resolved.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -333, for information.
  • L338: AN ON CLAUSE IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -338, for information.
  • L350: INVALID SPECIFICATION OF A LARGE OBJECT COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -350, for information.
  • L351: UNSUPPORTED SQLTYPE IN POSITION position-number OF SELECT-LIST
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -351, for information.
  • L352: UNSUPPORTED SQLTYPE IN POSITION position-number OF INPUT-LIST
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -352, for information.
  • L355: A LOB COLUMN IS TOO LARGE TO BE LOGGED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -355, for information.
  • L372: ONLY ONE COLUMN DEFINED AS ROWID IS ALLOWED IN A TABLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -372, for information.
  • L390: FUNCTION function-name (specific-name), NOT VALID IN THAT CONTEXT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -390, for information.
  • L392: SQLDA PROVIDED FOR cursor HAS BEEN CHANGED FROM PREVIOUS FETCH
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -392, for information.
  • L396: object-typeobject-name EXECUTED SQL STATEMENT DURING FINAL CALL PROCESSING
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -396, for information.
  • L397: GENERATED OPTION SPECIFIED ON COLUMN THAT IS NOT TYPE ROW ID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -397, for information.
  • L398: LOCATOR REQUESTED FOR HOST VARIABLE position-number BUT VARIABLE NOT A LOB
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -398, for information.
  • L399: ATTEMPTED TO INSERT AN INVALID VALUE INTO A ROWID COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -399, for information.
Parent topic: L - Link Error Messages


L400 - L449

Lists the Link error messages from L400 through L449.
Restriction: This topic applies to Windows environments only.
  • L400: THE CATALOG HAS THE MAXIMUM NUMBER OF USER DEFINED INDEXES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -400, for information.
  • L401: Operands of an arithmetic or comparison operation are not comparable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -401, for information.
  • L402: Arithmetic function/operator "< >" applied to character/datetime data.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -402, for information.
  • L404: THE SQL STATEMENT SPECIFIES A STRING THAT IS TOO LONG
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -404, for information.
  • L405: Numeric literal literal is out of range.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -405, for information.
  • L406: A calculated or derived numeric value not within range of its object column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -406, for information.
  • L407: COLUMN column-name CANNOT CONTAIN NULL VALUES IN INSERT, UPDATE OR SET
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -407, for information.
  • L408: THE VALUE IS NOT COMPATIBLE WITH THE DATA TYPE OF ITS TARGET
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -408, for information.
  • L409: Invalid operand of a count function.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -409, for information.
  • L410: Floating point literal literal contains more than 30 characters.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -410, for information.
  • L411: Current datetime, SQLID or user keyword cannot be used as specified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -411, for information.
  • L412: The SELECT clause of a subquery specifies multiple columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -412, for information.
  • L413: OVERFLOW OCCURRED DURING NUMERIC DATA TYPE CONVERSION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -413, for information.
  • L414: Numeric or datetime column name is specified in a LIKE predicate.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -414, for information.
  • L415: Cols, number, of the operands of a union do not have comparable col. descr.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -415, for information.
  • L416: An operand of a union contains a long string column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -416, for information.
  • L417: PREPARE string includes parameter markers as operand of same operator.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -417, for information.
  • L418: A string to be prepared contains an invalid use of parameter markers.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -418, for information.
  • L419: Decimal divide operation is invalid because the result has a negative scale.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -419, for information.
  • L420: STRING ARGUMENT VALUE NOT ACCEPTABLE TO FUNCTION function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -420, for information.
  • L421: Operand of a union or union all does not have the same number of columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -421, for information.
  • L423: INVALID VALUE FOR LOCATOR IN POSITION position-number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -423, for information.
  • L426: Dynamic commit not valid at application server where updates not allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -426, for information.
  • L427: Dynamic rollback not valid at application server where updates not allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -427, for information.
  • L430: routine-typeroutine-name (specific-name) HAS ABNORMALLY TERMINATED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -430, for information.
  • L433: VALUE value IS TOO LONG
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -433, for information.
  • L435: INVALID SQLSTATE sqlstate SPECIFIED IN RAISE_ERROR OR IN A SIGNAL SQLSTATE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -435, for information.
  • L438: APPLICATION RAISED ERROR WITH DIAGNOSTIC TEXT: text
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -438, for information.
  • L440: NO routine-type NAMED routine-name WITH COMPATIBLE ARGUMENTS WAS FOUND
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -440, for information.
  • L441: INVALID USE OF 'DISTINCT' OR 'ALL' WITH SCALAR FUNCTION function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -441, for information.
  • L443: function-name (specific-name) RETURNED WITH DIAGNOSTIC TEXT msg-text
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -443, for information.
  • L444: USER PROGRAM name COULD NOT BE FOUND
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -444, for information.
  • L449: INVALID EXTERNAL NAME CLAUSE FOR FUNCTION OR PROCEDURE routine-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -449, for information.
Parent topic: L - Link Error Messages


L450 - L499

Lists the Link error messages from L450 through L499.
Restriction: This topic applies to Windows environments only.
  • L450: FUNCTION/STORED PROCEDURE name, PARAMETER NUMBER parmnum, OVERLAYED MEMORY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -450, for information.
  • L451: INVALID data-item DEFINITION IN function-name, INVALID DATA TYPE type
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -451, for information.
  • L453: PROBLEM WITH THE RETURNS CLAUSE FOR FUNCTION function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -453, for information.
  • L454: SIGNATURE FOR FUNCTION function-name NOT UNIQUE WITHIN SCHEMA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -454, for information.
  • L455: function-name, SCHEMA schema-name1 IN SPECIFIC NAME DOES NOT MATCH schema-name2
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -455, for information.
  • L456: FUNCTION function-name, SPECIFIC specific-name EXISTS IN THE SCHEMA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -456, for information.
  • L457: ILLEGAL USE OF name; IT IS RESERVED FOR SYSTEM USE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -457, for information.
  • L458: FUNCTION function-name COULD NOT BE FOUND BY SIGNATURE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -458, for information.
  • L461: VALUE OF TYPE source-data-type CANNOT BE CAST TO target-data-type
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -461, for information.
  • L463: routine-name (specific-name) RETURNED sqlstate, DIAGNOSTIC TEXT text
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -463, for information.
  • L469: CALL STATEMENT NEEDS AN OUTPUT HOST VARIABLE FOR PARAMETER number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -469, for information.
  • L470: CALL STATEMENT SPECIFIED A NULL VALUE FOR INPUT PARAMETER number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -470, for information.
  • L471: INVOCATION OF FUNCTION/PROCEDURE name FAILED DUE TO REASON rc
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -471, for information.
  • L472: CURSOR cursor-name LEFT OPEN BY FUNCTION function-name (specific-name)
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -472, for information.
  • L473: USER DEFINED TYPE CANNOT BE THE SAME NAME AS A BUILT-IN TYPE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -473, for information.
  • L475: type-1 RESULT CANNOT BE CAST TO type-2 RETURN TYPE OF THE function-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -475, for information.
  • L476: FUNCTION function-name NAMED WITHOUT SIGNATURE, FUNCTION NOT UNIQUE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -476, for information.
  • L478: ACTION ON type1 CANNOT BE PROCESSED; name OF TYPE type2 DEPENDENT ON IT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -478, for information.
  • L480: PROCEDURE procedure-name HAS NOT YET BEEN CALLED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -480, for information.
  • L482: PROCEDURE procedure-name RETURNED NO LOCATORS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -482, for information.
  • L483: PARMS FOR function-name DOES NOT MATCH NUMBER OF PARMS OF SOURCE FUNCTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -483, for information.
  • L487: object-typeobject-name USED SQL BUT WAS CREATED WITH NOSQL OPTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -487, for information.
  • L491: FUNCTION function-name MUST HAVE RETURNS, AND EITHER EXTERNAL OR SOURCE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -491, for information.
  • L492: function-name PARAMETER number HAS MISMATCH WITH A SOURCE FUNCTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -492, for information.
  • L495: EST COST OF estimate-amount1 PROCESSOR SECONDS EXCEEDS RESOURCE LIMIT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -495, for information.
  • L496: SQL STATEMENT REFERENCES A RESULT SET NOT CREATED BY THE CURRENT SERVER
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -496, for information.
  • L497: INTERNAL IDENTIFIERS LIMIT HAS BEEN EXCEEDED FOR DATABASE database-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -497, for information.
  • L499: CURSOR cursor-name ALREADY ASSIGNED TO procedure-name RESULT SET
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -499, for information.
Parent topic: L - Link Error Messages


L500 - L549

Lists the Link error messages from L500 through L549.
Restriction: This topic applies to Windows environments only.
  • L500: IDENTIFIED CURSOR WAS CLOSED WHEN THE CONNECTION WAS DESTROYED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -500, for information.
  • L501: Cursor identified in a FETCH or CLOSE statement is not open.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -501, for information.
  • L502: The cursor identified in an OPEN statement is already open.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -502, for information.
  • L503: Column cannot be updated because it is not in the UPDATE clause of the select.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -503, for information.
  • L504: The cursor name name is not defined.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -504, for information.
  • L507: The cursor identified in the UPDATE or DELETE statement is not open.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -507, for information.
  • L508: Cursor identified in an update or delete is not positioned on a row.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -508, for information.
  • L509: The table in an UPDATE or DELETE is not a table designated by cursor.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -509, for information.
  • L510: Table designated by cursor of UPDATE/DELETE statement cannot be modified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -510, for information.
  • L511: FOR UPDATE clause invalid because cursor cannot be modified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -511, for information.
  • L512: Statement reference to remote object is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -512, for information.
  • L513: The alias name must not be defined by another local or remote alias.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -513, for information.
  • L514: The cursor name is not in a prepared state.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -514, for information.
  • L516: The described statement does not identify a prepared statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -516, for information.
  • L517: Cursor name does not identify a prepared SELECT statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -517, for information.
  • L518: The EXECUTE statement does not identify a valid prepared statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -518 for information.
  • L519: PREPARE identifies SELECT statement of the open cursor name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -519, for information.
  • L525: SQL cannot execute, error at bind for section sectno, package pkgname, consistency token Xcontoken.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -519, for information.
  • L526: REQUESTED FUNCTION DOES NOT APPLY TO GLOBAL TEMPORARY TABLES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -526, for information.
  • L530: The INSERT or UPDATE value of foreign key name is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -530, for information.
  • L531: Primary key in parent has dependent rows in relation name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -531, for information.
  • L532: The relation name restricts the deletion of row with RID X number.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -532, for information.
  • L533: Invalid multiple-row insert.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -533, for information.
  • L534: The primary key cannot be updated because of multiple-row update.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -534, for information.
  • L535: Invalid update or delete with WHERE CURRENT OF.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -535, for information.
  • L536: Delete is invalid because table name can be affected by the operation.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -536, for information.
  • L537: Primary key/foreign key identifies column name more than once.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -537, for information.
  • L538: Foreign key name does not match description of primary key of table name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -538, for information.
  • L539: Table name does not have a primary key.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -539, for information.
  • L540: Definition of table name does not have primary index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -540, for information.
  • L541: FOREIGN KEY key-name HAS DUPLICATE REFERENTIAL CONSTRAINT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -541, for information.
  • L542: name cannot be a column of primary key because it can contain NULL values.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -542, for information.
  • L543: CANNOT DELETE ROW IN PARENT TABLE; RESTRICTED BY CONSTRAINT check-constraint
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -543, for information.
  • L544: CANNOT ADD CHECK CONSTRAINT; EXISTING ROW VIOLATES THE CHECK CONSTRAINT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -544, for information.
  • L545: The requested operation is not allowed because of the check constraint CheckConstraint.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -545, for information.
  • L546: CHECK CONSTRAINT constraint-name IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -159, for information.
  • L548: A CHECK CONSTRAINT THAT IS DEFINED WITH column-name IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -548, for information.
  • L549: The Statement statement is not allowed for ObjectType1ObjectName because the bind option dynamicrules in the ObjectType2 is in effect.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -549, for information.
Parent topic: L - Link Error Messages


L550 - L599

Lists the Link error messages from L550 through L599.
Restriction: This topic applies to Windows environments only.
  • L551: Authid does not have privileges to perform operation Name on this object.
    If you are using the ODBC Smart Driver to monitor or record SQL, check that the specified authid has permission to access the ODBC_* tables used by the Static Bind Administrator. For a list of these tables and the permissions required to access them, see the GRANT statements in the ODBCSQL.SQL file located in your Micro Focus program directory.
  • L552: authid does not have the privileges to perform operation operation.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -552, for information.
  • L553: authid specified is not one of the valid AuthIDs.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -553, for information.
  • L554: An AuthID cannot grant a privilege to itself.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -554, for information.
  • L555: An AuthID cannot revoke a privilege from itself.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -555, for information.
  • L556: A privilege cannot be revoked because it is not possessed by authid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -556, for information.
  • L557: Inconsistent grant/revoke keyword keyword. Permitted keywords are keyword-list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -557, for information.
  • L558: Invalid clause or combination of clauses on a grant or revoke.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -558, for information.
  • L559: All authorization functions have been disabled.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -559, for information.
  • L567: bind-type AUTHORIZATION ERROR FOR auth-idpackage-nameprivilege
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -567, for information.
  • L571: The statement would result in a multiple site update.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -571, for information.
  • L573: table-name DOES NOT HAVE UNIQUE KEY WITH SPECIFIED COLUMN NAMES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -573, for information.
  • L574: THE DEFAULT VALUE CONFLICTS WITH DEFINITION OF COLUMN column-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -574, for information.
  • L577: DEFINITION OF object-typeobject-name DID NOT SPECIFY MODIFY DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -577, for information.
  • L579: DEFINITION OF object-typeobject-name DID NOT SPECIFY READ OR MODIFY DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -579, for information.
  • L580: THE RESULT-EXPRESSIONS OF A CASE EXPRESSION CANNOT ALL BE NULL
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -580, for information.
  • L581: RESULT-EXPRESSION DATA TYPES OF CASE EXPRESSION ARE NOT COMPATIBLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -581, for information.
  • L582: WHEN-CLAUSE CONDITION CANNOT BE QUANTIFIED, IN, OR EXISTS PREDICATE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -582, for information.
  • L583: INVALID USE OF FUNCTION; function-name NOT DETERMINISTIC/EXTERNAL ACTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -583, for information.
  • L585: SCHEMA NAME schema-name CANNOT APPEAR MORE THAN ONCE IN THE CURRENT PATH
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -585, for information.
  • L586: TOTAL LENGTH OF CURRENT PATH SPECIAL REGISTER CANNOT EXCEED 254 CHARACTERS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -586, for information.
  • L587: A LIST OF ITEM-REFERENCES ARE NOT IN THE SAME FAMILY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -587, for information.-587, for information.
  • L590: PARAMETER parameter-name NOT UNIQUE FOR ROUTINE routine-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -590, for information.
  • L592: NOT AUTHORIZED TO CREATE FUNCTIONS/PROCEDURES IN WLM ENV env-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -592, for information.
Parent topic: L - Link Error Messages


L600 - L649

Lists the Link error messages from L600 through L649.
Restriction: This topic applies to Windows environments only.
  • L601: Name of the object to be created identical to existing name name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -601, for information.
  • L602: Too many columns specified in a CREATE INDEX.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -602, for information.
  • L603: Unique index cannot be created. The table has rows with duplicate columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -603, for information.
  • L604: Column definition specifies an invalid length, precision, or scale attribute.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -604, for information.
  • L607: Operation operation is not defined for system tables.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -607, for information.
  • L611: ONLY LOCKMAX 0 CAN BE SPECIFIED WHEN LOCK SIZE IS TABLESPACE OR TABLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -611, for information.
  • L612: name is a duplicate column name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -612, for information.
  • L613: The primary key is too long or has too many columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -613, for information.
  • L614: Cannot create index. Sum of internal lengths of columns > allowable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -614, for information.
  • L615: op is not allowed on a package in use.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -615, for information.
  • L616: obj-typeobj-name CANNOT BE DROPPED; REFERENCED BY obj-typeobj-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -616, for information.
  • L617: TYPE 1 INDEX IS NOT VALID FOR TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -617, for information.
  • L618: Operation operation is not allowed on system databases.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -618, for information.
  • L619: Operation disallowed because the workfile database is not stopped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -619, for information.
  • L620: Keyword keyword not allowed for tablespace in workfile database.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -620, for information.
  • L621: Duplicate dbid dbid was detected and previously assigned to dbname.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -621, for information.
  • L622: FOR MIXED DATA is invalid because MIXED DATA inst opt is NO.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -622, for information.
  • L623: A clustering index already exists on table name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -623, for information.
  • L624: Table name already has a primary key.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -624, for information.
  • L625: TABLE table-name DOES NOT HAVE INDEX TO ENFORCE UNIQUENESS OF PARENT KEY
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -625, for information.
  • L626: ALTER statement is not executable because the pageset is not stopped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -626, for information.
  • L627: ALTER statement is invalid because the pageset has user-managed data set.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -627, for information.
  • L628: THE CLAUSES ARE MUTUALLY EXCLUSIVE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -628, for information.
  • L629: No set NULL because foreign key name cannot contain NULL values.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -629, for information.
  • L630: WHERE NOT NULL SPECIFICATION IS INVALID FOR TYPE 1 INDEXES
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -630, for information.
  • L631: Foreign key name is too long or has too many columns.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -631, for information.
  • L632: Cannot define table as dependent of name due to delete rule restriction.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -632, for information.
  • L633: The delete rule must be delete.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -633, for information.
  • L634: The delete rule must not be cascade.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -634, for information.
  • L635: The delete rules cannot be different or cannot be set NULL.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -635, for information.
  • L636: Partitioning keys not specified in ascending/descending order.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -636, for information.
  • L637: Duplicate keyword keyword.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -637, for information.
  • L638: Table name cannot be created. Column definition is missing.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -638, for information.
  • L639: Column of foreign key with delete rule of set NULL cannot be in partition index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -639, for information.
  • L640: LOCKSIZE ROW CANNOT BE SPECIFIED; TABLE HAS TYPE 1 INDEX
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -640, for information.
  • L642: TOO MANY COLUMNS IN UNIQUE CONSTRAINTS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -642, for information.
  • L643: CHECK CONSTRAINT EXCEEDS MAXIMUM ALLOWABLE LENGTH
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -643, for information.
  • L644: INVALID VALUE SPECIFIED FOR KEYWORD keyword IN statement-type STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -644, for information.
  • L646: Cannot create table name in partitioned default tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -646, for information.
  • L647: Bufferpool name cannot be specified. It has not been activated.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -647, for information.
Parent topic: L - Link Error Messages


L650 - L699

Lists the Link error messages from L650 through L699.
Restriction: This topic applies to Windows environments only.
  • L650: THE ALTER INDEX CANNOT BE EXECUTED, REASON reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -650, for information.
  • L651: TABLE DESCRIPTION EXCEEDS MAXIMUM SIZE OF OBJECT DESCRIPTOR
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -651, for information.
  • L652: Violation of installation-defined edit or validation procedure proc.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -652, for information.
  • L653: Table name in partitioned tablespace name not available.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -653, for information.
  • L655: CREATE OR ALTER STOGROUP IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -655, for information.
  • L658: object-type CANNOT BE DROPPED USING THE statement STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -658, for information.
  • L660: Cannot create index name on partitioned tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -660, for information.
  • L661: Cannot create index name on partitioned tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -661, for information.
  • L662: Cannot create a partitioned index on a non-partitioned tablespace name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -662, for information.
  • L663: Number of key limit values is 0, or > number of columns in key of index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -663, for information.
  • L664: Internal length of limit-key fields for partitioned index name is too long.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -664, for information.
  • L665: The PART clause of an ALTER statement is omitted or invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -665, for information.
  • L666: stmt-verbobject cannot be executed because of something in progress.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -666, for information.
  • L667: Clustering index for partitioned tablespace cannot be explicitly dropped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -667, for information.
  • L668: Cannot add column to the table because the table has an edit procedure.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -668, for information.
  • L669: A table in a partitioned tablespace cannot be explicitly dropped.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -669, for information.
  • L670: The record length of the table exceeds the page size limit.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -670, for information.
  • L671: Cannot alter buffpool attr of tablespace because pg size of tablespace would change.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -671, for information.
  • L672: OPERATION DROP NOT ALLOWED ON TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -672, for information.
  • L676: A 32K page bufferpool may not be used for an index.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -676, for information.
  • L677: Insufficient virtual storage for bufferpool expansion.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -677, for information.
  • L678: literal specified for index limit key must conform to data type type.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -678, for information.
  • L679: Object name cannot be created. A drop is pending on the object.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -679, for information.
  • L680: Too many columns specified for a table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -680, for information.
  • L681: Column name in violation of installation-defined field procedure name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -681, for information.
  • L682: Field procedure proc could not be loaded.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -682, for information.
  • L683: Invalid column type for fieldproc or bit data option, column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -683, for information.
  • L684: The length of literal list beginning string is too long.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -684, for information.
  • L685: Invalid field type column.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -685, for information.
  • L686: Cannot compare column defined by one field procedure to one defined by another.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -686, for information.
  • L687: Field types incomparable.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -687, for information.
  • L688: Incorrect data returned from field procedure, column, msgno.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -688, for information.
  • L689: Too many columns defined for a dependent table.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -689, for information.
  • L690: Statement is rejected by data def ctrl support, reason reason.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -690, for information.
  • L691: The required registrations table table does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -691, for information.
  • L692: Unique index index-name in table table-name does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -692, for information.
  • L693: Column column is not defined properly.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -693, for information.
  • L694: DDL STMT CANNOT EXECUTE; DROP PENDING ON DDL REGISTRATION TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -694, for information.
  • L696: TRIGGER trigger-name CONTAINS INVALID USE OF NAME name, REASON reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -696, for information.
  • L697: CORR. NAMES NOT ALLOWED IN TRIGGER WITH "FOR EACH STATEMENT" OR "BEFORE"
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -697, for information.
Parent topic: L - Link Error Messages


L700 - L799

Lists the Link error messages from L700 through L799.
Restriction: This topic applies to Windows environments only.
  • L713: REPLACEMENT VALUE value FOR special-register IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -713, for information.
  • L715: Prog program dep on function of the release from which fallback has occurred.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -715, for information.
  • L716: Program program precompiled with wrong level for this release.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -716, for information.
  • L717: object dependent on function of release from which fallback has occurred.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -717, for information.
  • L718: REBIND failed because IBMREQD of ibmreqd is invalid.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -718, for information.
  • L719: BIND ADD error, package package already exists.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -719, for information.
  • L720: Attempt to replace package package with existing version version.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -720, for information.
  • L721: BIND err CONTOK = contoken X cannot be created because it is not unique.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -721, for information.
  • L722: Package package does not exist.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -722, for information.
  • L723: ERROR IN TRIGGER trigger-name, SECTION NUMBER section-number
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -723, for information.
  • L724: ACTIVATION OF object-typeobject-name WOULD EXCEED MAXIMUM OF SQL CASCADING
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -724, for information.
  • L725: SPECIAL REGISTER register AT location WAS SUPPLIED INVALID VALUE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -725, for information.
  • L726: Cannot replace package package. Enable or disable entries also with package.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -726, for information.
  • L728: DATA TYPE data-type IS NOT ALLOWED IN DB2 PRIVATE PROTOCOL PROCESSING
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -728, for information.
  • L729: COMMIT ON RETURN STORED PROCEDURE CANNOT BE IN NESTED CALL STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -729, for information.
  • L730: The parent of a table in a read-only database must also be in the database.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -730, for information.
  • L731: User-defined dataset dsname must be defined with SHAREOPTIONS(1,3).
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -731, for information.
  • L732: Table space or index space has not been defined on the owning subsystem.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -732, for information.
  • L733: The description of a table space, index space or ROSHARE READ db must be consistent.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -733, for information.
  • L734: The ROSHARE attr of a database cannot be altered from ROSHARE READ.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -734, for information.
  • L735: Database dbid is not longer a shared database.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -735, for information.
  • L736: Invalid OBID obid specified.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -736, for information.
  • L737: Implicit table space not allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -737, for information.
  • L739: ALTER function-name FAILED; PARALLEL PROCESSED FUNCTIONS CANNOT MODIFY DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -739, for information.
  • L740: FUNCTION name THAT MODIFIES SQL DATA IS NOT VALID IN CURRENT CONTEXT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -740, for information.
  • L741: WORK FILE DATABASE IS ALREADY DEFINED FOR MEMBER member-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -741, for information.
  • L742: DSNDB07 IS THE IMPLICIT WORK FILE DATABASE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -742, for information.
  • L746: SQL STATEMENT IN name VIOLATES THE NESTING SQL RESTRICTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -746, for information.
  • L747: table-name NOT AVAILABLE UNTIL AUX TABLES AND INDEXES HAVE BEEN CREATED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -747, for information.
  • L748: AN INDEX ALREADY EXISTS ON AUXILIARY TABLE table-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -748, for information.
  • L750: TABLE source-name CANNOT BE RENAMED; REFERENCED BY EXISTING DEFINITIONS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -750, for information.
  • L751: object-typeobject-name (specific-name) ATTEMPTED TO EXECUTE statement
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -751, for information.
  • L752: CONNECT statement invalid because the process is not in the connectable state.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -752, for information.
  • L763: INVALID TABLE SPACE NAME table-space-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -763, for information.
  • L764: LOB TABLE SPACE AND ITS BASE TABLE SPACE MUST BE IN SAME DATABASE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -764, for information.
  • L765: TABLE IS NOT COMPATIBLE WITH DATABASE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -765, for information.
  • L766: REQUESTED OPERATION NOT PERMITTED ON AUXILIARY TABLE OF STATEMENT OBJECT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -766, for information.
  • L767: MISSING OR INVALID COLUMN SPECIFICATION FOR INDEX index-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -767, for information.
  • L768: AUXILIARY TABLE ALREADY EXISTS FOR THE SPECIFIED COLUMN OR PARTITION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -768, for information.
  • L769: SPECIFICATION OF AUX TABLE DOES NOT MATCH CHARACTERISTICS OF BASE TABLE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -769, for information.
  • L770: TABLE table-name CANNOT HAVE LOB COLUMN UNLESS IT ALSO HAS ROWID COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -770, for information.
  • L771: INVALID SPECIFICATION OF A ROWID COLUMN
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -771, for information.
  • L797: ATTEMPT TO CREATE TRIGGER trigger-name WITH AN UNSUPPORTED SQL STATEMENT
  • L798: ATTEMPT TO INSERT VALUE INTO ROWID GENERATED ALWAYS COLUMN column-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -798, for information.
Parent topic: L - Link Error Messages


L800 - L899

Lists the Link error messages from L800 through L899.
Restriction: This topic applies to Windows environments only.
  • L802: EXCEPTION ERROR exception-type OCCURRED DURING operation-type OPERATION ON data-type DATA
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -802, for information.
  • L803: INSERT/UPDATE INVALID;INDEX SPACE index-space-name RESTRICTS DUP COLUMNS, RID row-id
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -803, for information.
  • L804: Error found in application program input parameters for the SQL statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -804, for information.
  • L805: Program name name not found in plan name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -805, for information.
  • L807: Access denied to package pkg.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -807, for information.
  • L808: CONNECT STATEMENT IS NOT CONSISTENT WITH THE FIRST CONNECT STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -808, for information.
  • L811: Result of embedded select statement is a table with more than one row.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -811, for information.
  • L812: BLANK COLLECTION-ID IN CURRENT PACKAGE SET; PGM program-name.consistency-token USING PLAN plan-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -812, for information.
  • L815: GROUP BY/HAVING clause specified in embedded select statement/subquery.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -815, for information.
  • L817: Cannot execute INSERT/UPDATE/DELETE/DLL/AUTHORIZATION statement.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -817, for information.
  • L818: Timestamp in load module is not the same as bind timestamp built from the DBRM.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -818, for information.
  • L819: Cannot process view. Length of its parse tree in the catalog is zero.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -819, for information.
  • L820: Cannot process SQL statement. catalog contains a value not valid in version.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -820, for information.
  • L822: SQLDA contains invalid data address or indicator variable address.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -822, for information.
  • L840: Too many items returned in a select or insert list.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -840, for information.
  • L842: A CONNECTION TO location-name ALREADY EXISTS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -842, for information.
  • L843: SET CONNECTION OR RELEASE STATEMENT MUST SPECIFY AN EXISTING CONNECTION
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -843, for information.
  • L870: NUMBER OF HOST VARIABLES IN STATEMENT NOT EQUAL TO NUMBER OF DESCRIPTORS
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -870, for information.
  • L872: A VALID CCSID HAS NOT YET BEEN SPECIFIED FOR THIS SUBSYSTEM
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -872, for information.
  • L873: DATA ENCODED WITH DIFFERENT CCSIDS CANNOT BE REFERENCED IN SAME STATEMENT
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -873, for information.
  • L874: object-type ENCODING SCHEME MUST BE SAME AS THE CONTAINING TABLE SPACE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -874, for information.
  • L875: operand CANNOT BE USED WITH THE ASCII DATA REFERENCED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -875, for information.
  • L876: 'object' CANNOT BE CREATED, REASON 'reason'
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message
  • L877: CCSID ASCII IS NOT ALLOWED FOR THIS DATABASE OR TABLE SPACE
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -877, for information.
  • L878: THE PLAN_TABLE USED FOR EXPLAIN CANNOT BE ASCII
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -878, for information.
  • L879: object-name CANNOT DEFINE OBJECT MIXED/GRAPHIC WITH ENCODING SCHEME encoding-scheme
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -879, for information.
Parent topic: L - Link Error Messages


L900 - L999

Lists the Link error messages from L900 through L999.
Restriction: This topic applies to Windows environments only.
  • L900: Cannot EXEC SQL because application is not connected to application server.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -900, for information.
  • L901: System error caused failed execution so subsequent SQL may be successful.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -901, for information.
  • L902: Pointer to the essential ctrl block (CT/RDA) has value 0, rebind required.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -902, for information.
  • L904: Unavailable resource caused failed exec. type type of resource name.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -904, for information.
  • L905: Fail exec due to resource limit, resource name name limit amount.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -905, for information.
  • L906: Cannot execute SQL statement. Function disabled due to a prior error.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -906, for information.
  • L907: Unable to determine if commit of updates made at a remote site failed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -907, for information.
  • L908: bind error using authid authority no bind or rebind are allowed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -908, for information.
  • L909: The object has been deleted.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -909, for information.
  • L910: SQL statement cannot access object on which a drop/alter is pending.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -910, for information.
  • L911: Rollback due to a deadlock/timeout. Reason code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -911, for information.
  • L913: Failed execution cause by deadlock/timeout. Reason code code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -913, for information.
  • L917: Bind package failed.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -917, for information.
  • L918: SQL cannot be executed because connection has been lost.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -918, for information.
  • L919: A ROLLBACK OPERATION IS REQUIRED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -919, for information.
  • L922: AUTHORIZATION FAILURE: error-type ERROR. REASON reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -922, for information.
  • L923: CONNECTION NOT ESTABLISHED: DB2 condition REASON reason-code, TYPE resource-type, NAME resource-name
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -923, for information.
  • L924: DB2 CONNECTION INTERNAL ERROR, function-code, return-code, reason-code
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -924, for information.
  • L925: Commit not valid in IMS/VS or CICS environment.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -925, for information.
  • L926: Rollback not valid in IMS/VS or CICS environment.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -926, for information.
  • L927: Language interface called when the connecting environment was not established.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -927, for information.
  • L929: FAILURE IN A DATA CAPTURE EXIT: token
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -929, for information.
  • L939: ROLLBACK REQUIRED DUE TO UNREQUESTED ROLLBACK OF A REMOTE SERVER
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -939, for information.
  • L947: STATEMENT FAILED;WILL CHANGE TABLE DEFINED BUT DATA CANNOT BE PROPAGATED
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -947, for information.
  • L948: DISTRIBUTED OPERATION IS INVALID
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -948, for information.
  • L950: Location name is invalid or not in comm db.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -950, for information.
  • L981: STATEMENT FAILED;CONNECTION DOES NOT ALLOW SQL OPERATIONS, REASON reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -981, for information.
  • L991: CrossAccess Data Access error ErrorNum (ConditionCode) for IMS/VSAM. Consult CrossAccess System Messages documentation.
    CrossAccess experienced the specified data error while processing an SQL request against IMS/VSAM. For additional information about this error, see your CrossAccess User Documentation.
  • L992: CrossAccess System error ErrorNum while accessing IMS/VSAM. Contact mainframe systems programming.
    CrossAccess has experienced the specified system error while attempting to access IMS/VSAM. For additional information about this error, see your CrossAccess User Documentation.
Parent topic: L - Link Error Messages


L1000 - L1099

Lists the Link error messages from L1000 through L1099.
Restriction: This topic applies to Windows environments only.
  • L1000: Exec failed. Protocol error: Reason reason (type)
  • L1020: Exec failed with dealloc. Protocol error: reason 1218 (02)
    Manager dependency error detected at other node.
  • L1021: :Execution failed. Manager manager at level level not supported.
    Managers must support certain levels.
  • L1040: Unavail resource caused perm failure. Reason Alloc type type.
    Type = Semaphore
  • L1041: Unavail resource caused perm failure. Reason Alloc type type.
    Type = Semaphore
  • L1050: command command or SQL invalid while bind in progress.
    A binding must be completed before other SQL can be issued.
  • L1051: Bind with specified package name and consistency token not active.
    A section of a package could not be bound because a BEGIN BIND has not been called.
  • L1052: Program preparation assumptions are incorrect.
    The program preparation assumptions in effect for binding a statement (i.e. BINDSQLSTT command) are incorrect.
  • L1053: Owner authorization failure.
    A command could not be executed because the user is not authorized.
  • L1060: RDB authorization failure.
    The user is not authorized to access the location specified.
  • L1061: RDB not found.
    The location name is not valid.
  • L1070: command command not supported.
    The code point indicates a request data stream structure that is not supported.
  • L1071: object object not supported error.
    The code point indicates an object data stream structure that is not supported.
  • L1072: parameter parameter not supported error.
    The code point indicates that a data stream structure parameter is not supported.
  • L1073: value parameter value not supported error.
    The code point indicates that a data stream structure parameter value is not supported.
  • L1074: Reply message with codepoint (severity) not supported.
    The reply message returned from the target is not recognized.
  • L1080: Communication error primary (secondary).
    An unmapped APPC error has occurred.
  • L1090: Remote operation invalid for application execution environment.
    An update operation or a dynamic commit or rollback was attempted at a server that was supporting an application that was in a read-only execution environment (IMS or CICS).
Parent topic: L - Link Error Messages


L30000 - L30099

Lists the Link error messages from L30000 through L30099.
Restriction: This topic applies to Windows environments only.
  • L30000: Distribution protocol error: reason reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30000, for information.
  • L30020: Distribution protocol error cause deallocation reason: reason-code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30020, for information.
  • L30021: Distribution protocol error: manager manager at level level not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30021, for information.
  • L30030: Not committed, SQLCODE = orig-sqlcode and SQLSTATE = orig-sqlstate.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30030, for information.
  • L30040: Unavailable resource. Reason reason-code type rsrc-type, name rsrc-name, id pppvvrrm, RDBNAME rdbname.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30040, for information.
  • L30041: Unavailable resource. Reason reason-code type resource-type name resource-name id pppvvrrm RDBNAME rdbname.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30041, for information.
  • L30050: command or SQL statement invalid while bind.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30050, for information.
  • L30051: Bind process with specified package name and consistency token not active.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30051, for information.
  • L30052: Program preparation assumptions are incorrect.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30052, for information.
  • L30053: Owner authorization failure.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30053, for information.
  • L30060: RDB authorization failure.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30060, for information.
  • L30061: RDB not found.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30061, for information.
  • L30070: command command not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30070, for information.
  • L30071: object object not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30071, for information.
  • L30072: parameter: subcode parameter not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30072, for information.
  • L30073: parameter: subcode parameter value not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30073, for information.
  • L30074: Reply message with codepoint (SRVCOD) not supported.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30074, for information.
  • L30080: Communication error code.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30080, for information.
  • L30090: Remote operation invalid for application execution.
    See the section Error SQLCODES in your IBM Database Messages and Codes manual, message -30090, for information.
Parent topic: L - Link Error Messages


N - Network Error Messages

Restriction: This topic applies to Windows environments only.
  • N000 - N099
    Lists the Network error messages from N000 through N099.
  • N300 - N399
    Lists the Network error messages from N300 through N399.
  • N400 - N449
    Lists the Network error messages from N400 through N449.
  • N450 - N499
    Lists the Network error messages from N450 through N499.
  • N500 - N599
    Lists the Network error messages from N500 through N599.
Parent topic: SQL Option for DB2 Error Messages


N000 - N099

Lists the Network error messages from N000 through N099.
Restriction: This topic applies to Windows environments only.
  • N001: Illegal buffer length value.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N002: Undocumented NetBIOS error.
    Undocumented NetBIOS error.
  • N003: Invalid network command.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N004: Undocumented NetBIOS error.
    Undocumented NetBIOS error.
  • N005: NetBIOS command timed out.
    If this error was received while trying to log into the server, then the XDB Server name could not be found. Otherwise, an internal NetBIOS error occurred. Contact Micro Focus Technical Support.
  • N006: Incomplete network message.
    Communications packet was larger than the maximum Receive Buffer size specified by user, either at the server or at the client. If the error was received at the server, check the settings in the XDB Server Configuration utility; if received at the client, check the settings in Options.
  • N008: Illegal local session number number.
    Either the NetBIOS connection to the server was broken (an N024 error preceded this or was ignored) or the connection was never established. For example, this error will occur when a COBOL program attempts and fails to successfully log into the server.
  • N009: Resource is not available.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N010: Session # number closed.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N011: Command canceled.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N012: Undocumented NetBIOS error.
    Undocumented NetBIOS error.
  • N013: Duplicate name name in local name table.
    This error should not be reported to the user. Contact Micro Focus Technical Support if you receive this error.
  • N014: Network name table is full.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N015: Command completed, name has active session and is now de-registered.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N017: Local session table is full.
    Either the maximum number of users specified through the XDB Server Configuration utility are logged into the XDB Server, or the maximum number of NetBIOS sessions allowed by the network software has been reached. In case of the latter, check with your LAN supervisor.
  • N018: Cannot open network session.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N019: Illegal session name identification number.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N020: Cannot find name called or no answer.
    Either the XDB Server is not running, or you are trying to log into an XDB Server that does not exist. Access Options and change the server name. See the XDB Server Administration Guide for instructions on configuring the XDB Server. You may need to increase the timeout period on the client. Also check that NetBIOS is loaded and that your NetBIOS settings are compatible between the server and the client.
  • N021: Name name not found.
    Either the XDB Server is not running, or you are trying to log into an XDB Server that does not exist. Access Options and change the server name. See the XDB Server Administration Guide for instructions on configuring the XDB Server. You may need to increase the timeout period on the client. Also check that NetBIOS is loaded and that your NetBIOS settings are compatible between the server and the client.
  • N022: Name name in use on remote adapter.
    Either the specified server name (if error was received on an XDB Server) or the workstation node name already exists on the network. Try using a different node name. See your Setup guide or the XDB Server Administration Guide for information about configuring the node name for a client workstation or an XDB Server, respectively.
  • N023: Name name was deleted.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N024: Session ended abnormally.
    This error message will appear when the connection between the client and the server is broken. Check to see that the server is up and that there is no problem with the network.
  • N025: Name conflict detected.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N026: Incompatible remote device.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N027 - N032: Undocumented NetBIOS errors.
    Undocumented NetBIOS error.
  • N033: Interface busy.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N034: Too many commands outstanding.
    Internal NetBIOS error. Too many NetBIOS request threads were specified in the XDB Server Configuration. Either reduce the number or edit your NET.CFG for Novell and increase NetBIOS and/or Named Pipe sessions (or in the case of a LAN server increase the number of sessions in the NETBEUI_NIF section of PROTOCOL.INI).
  • N035: Invalid number in NCB_LANA_NUM field.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N036: Command completed while cancel occurring.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N037: Attempt to use reserved name as a group name.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N038: Attempt to issue a command out of sequence.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N040 - N049: Unusual network conditions.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
  • N050: NetBIOS is not loaded.
    The XDB Server requires a NetBIOS-compatible network with NetBIOS running. Check with your Network Administrator. Also you must have both IBM and Novell NetWare in your CONFIG.SYS in OS/2.
  • N051 - N254: Unusual network conditions.
    Internal NetBIOS error. Contact Micro Focus Technical Support.
Parent topic: N - Network Error Messages


N300 - N399

Lists the Network error messages from N300 through N399.
Restriction: This topic applies to Windows environments only.
  • N300: TCP Error errmsgfunction( ) = errorcode
    The indicated TCP/IP error occurred. The list below shows possible error codes and their associated error messages.
  • N301: SPX Error: errmsgfunction() = errcode
    The indicated IPX/SPX error occurred. The list below shows possible error codes and their associated error messages:
  • N302: NETBIOS Error errmsgfunction = errorcode
    The specified NETBIOS error has occurred. For example, if you attempt to connect to a server using an invalid server name, or if the specified server is not up and running, the following message is displayed:
  • N357: Invalid Named Pipe function call (ERROR_INVALID_FUNCTION).
    Internal Named Pipes Error. Contact Micro Focus Technical Support.
  • N358: Invalid path path specified for Named Pipe (ERROR_FILE_NOT_FOUND).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N359: Cannot find Named Pipe name (ERROR_PATH_NOT_FOUND).
    Make sure that the XDB Server configuration (XDBSRVCO.EXE or XDBSRVBT.EXE) setting for the number of Named Pipes threads is greater than zero, and that the Named Pipes protocol is turned on.
  • N360: Access denied to Named Pipe name (ERROR_ACCESS_DENIED).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N361: Invalid handle to Named Pipe specified (ERROR_INVALID_HANDLE).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N362: Not enough memory for Named Pipe operation (ERROR_NOT_ENOUGH_MEMORY).
    Close or remove some programs from your machine or acquire more RAM.
  • N363: Invalid format specified for Named Pipe (ERROR_BAD_FORMAT).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N364: No more structures available for Named Pipe name (ERROR_OF_STRUCTURES).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N365: Invalid parameter specified for Named Pipe call (ERROR_INVALID_PARAMETER).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N366: Named Pipes system call interrupted (ERROR_INTERRUPT).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N367: Named Pipe name is broken (ERROR_BROKEN_PIPE).
    The connection has been broken between the server and the client. Check to see that the server is up and that there is no problem with the network. Check that your Named Pipes configuration matches that in the XDB Server Configuration utility.
  • N368: Buffer too small for Named Pipe (ERROR_BUFFER_OVERFLOW).
    The communications packet was larger than the maximum. See error N006.
  • N369: Semaphore not found (ERROR_SEM_TIMEOUT).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N370: Invalid name name specified for Named Pipe (ERROR_INVALID_NAME).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N371: Invalid level parameter (ERROR_INVALID_LEVEL).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N372: Invalid name name specified for Named Pipe (ERROR_SEM_NOT_FOUND).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N373: Handle does not refer to Named Pipe (ERROR_BAD_PIPE).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N374: All available instances of Named Pipe name are in use (ERROR_PIPE_BUSY).
    The maximum number of users communicating via Named Pipes is logged into the XDB Server. To correct this problem, try increasing the number of Named Pipe Receive Threads (XDB Server Configuration utility, Multi-user Options). Also, if embedding SQL in COBOL, check your code to be sure you have not used the LOGON and LOGOFF directives in subprograms. See the XDB Server Administration Guide for configuration information.
  • N375: Data unavailable on non-blocking read (ERROR_NO_DATA).
    Internal Named Pipes error. Contact Micro Focus Technical Support.
  • N376: Named Pipe name currently not connected (ERROR_PIPE_NOT_CONNECTED).
    The connection has been broken between the server and the client.
  • N377: Buffer too small for Named Pipe name (ERROR_MORE_DATA).
    The communications packet was larger than the maximum. Check the settings in the XDB Server Configuration utility and in Options.
  • N396: Undocumented Named Pipes error number.
    Internal error. If number = 53, and using Novell NetWare, you must put your server name after NPDAEMON.EXE in your CONFIG.SYS file. You may be starting an OS/2 client against a local OS/2 server (make sure the OS/2 environment variable XDBSERVE is set to LOCAL). Otherwise, contact Micro Focus Technical Support.
Parent topic: N - Network Error Messages


N400 - N449

Lists the Network error messages from N400 through N449.
Restriction: This topic applies to Windows environments only.
  • N406: Bad transaction program identifier: identifier.
    The tp_id parameter of the APPC verb is not valid. Either the TP_STARTED verb has failed or the tp_id returned after issuing the TP_STARTED verb was not moved into the current verb control block.
  • N407: Bad conversation identifier: identifier.
    The conv_id parameter used in an APPC verb is invalid. The most likely cause of this error is a failure on the remote system that is severe enough to deallocate the conversation.
  • N408: Bad logical unit alias: alias.
    The local LU alias referenced is not defined. A local LU name in communication manager must be defined with an alias that matches the name of the XDB Server.
  • N409: Allocation failure no retry. Sense code: code.
    A conversation cannot be started due to a permanent error condition requiring intervention. The sense code can be used to isolate the problem.
  • N410: Allocation failure retry. Sense code: code.
    A conversation cannot be started. On a system that has allocated conversations successfully in the past, the error might be recoverable without intervention. The sense code could be used to isolate the problem.
  • N411: Invalid data segment.
    The memory block used to send and receive data is invalid.
  • N412: Bad conversation type parameter.
    The conversation_type APPC verb parameter is invalid. Only basic conversations and mapped conversations are supported.
  • N413: Bad synchronization level parameter.
    The sync_level APPC verb parameter value is invalid. XDB Server uses NONE for DRDA level 1.
  • N414: Bad security parameter.
    The security APPC verb parameter value is invalid. XDB Server uses PGM security.
  • N415: Bad return control parameter.
    The return_control APPC verb parameter value is invalid. XDB Server uses WHEN_SESSION_ALLOCATED.
  • N416: Program initialization parameter length incorrect.
    The pip_data_length APPC parameter value is too large.
  • N417: Use of SNASVCMG or CPSVCMG for mode not allowed.
    The mode names SNASVCMG and CPSVCMG are reserved and should not be used when allocating a conversation.
  • N418: Unknown partner mode/alias:"<".
    The partner LU alias referenced is not defined. A partner LU in communication manager must have an alias that matches the PLU alias name entered when defining a location using XDBGPROF.EXE.
  • N419: Dealloc bad type parameter.
    The type APPC verb parameter value is invalid.
  • N420: Dealloc flush bad state.
    The dealloc APPC verb type parameter value is incorrect for the state of the conversation.
  • N421: Dealloc confirm bad state.
    The dealloc APPC verb type parameter value is incorrect for the state of the conversation.
  • N422: Dealloc not logical length body.
    An incomplete logical record was sent when the dealloc was issued.
  • N423: Dealloc log logical length wrong.
    The log_data_length APPC verb parameter value does not match the LL field.
  • N424: Receive and wait bad state.
    The conversation is not in Receive or Send state.
  • N425: Receive and wait not logical length body.
    An incomplete logical record was sent in Send state when the Receive was issued.
  • N426: Receive and wait bad fill parameter.
    The fill APPC verb parameter value is invalid.
  • N427: Bad return status with data parameter.
    The return_status_with_data APPC verb parameter value is invalid.
  • N428: Bad logical length.
    The Logical record length of the data buffer in invalid. Invalid values are X''0000'', X''0001'', X''8000'', and X''8001''.
  • N429: Send data not in send state.
    An attempt was made to send data when the conversation was in Receive state.
  • N430: Send data invalid type parameter.
    The type APPC verb parameter value is invalid.
  • N431: Send data confirm with synchronization none.
    The type APPC verb parameter value is incorrect for type of the conversation.
  • N432: Send data not logical length body.
    An incomplete record was sent in Send state.
  • N433: Bad type.
    The type APPC verb parameter value is invalid.
  • N434: Undefined transaction program name: name.
    The tp_name referenced was not found. The transaction program must be defined on the host system and match the value configured using XDBGPROF.EXE. When connecting to DB2 using DRDA the tp_name is X07F6C4C2 and the tp runs in the DDF address space.
  • N435: Attach manager already inactive.
    The APPC attach manager is not processing receive_allocate verbs.
  • N436: Allocate not pending.
    A receive_allocate APPC verb was issued and timed out before an incoming allocate request was received.
  • N437: Invalid process.
    A process issued a receive_allocate verb that was not started by the attach manager.
  • N438: Security not valid.
    The partner LU rejected the UserID or password used in the allocate call. Turn on security at the client using the Configuration utility. Make sure the UserID and password are valid for the host environment.
  • N439: Transaction program not available retry.
    The partner LU rejected the allocate call because the transaction program could not be started immediately.
  • N440: Transaction program not available no retry.
    The partner LU rejected the allocate call because the transaction program could not be started.
  • N441: Transaction program name not recognized.
    The partner LU rejected the allocate call because the tp_name was not recognized at the partner location.
  • N442: Program initialization parameter not allowed.
    The partner LU rejected the allocate call because it does not support PIP data or the TP has no PIP variables defined.
  • N443: Program initialization parameter not specified correctly.
    The partner LU rejected the allocate call because the number of PIP variables defined by the local TP does not match the number defined for the remote TP.
  • N444: Conversation type mismatch.
    The partner LU rejected the allocate call because the conversation type of the local TP does not match the conversation type of the remote TP.
  • N445: Synchronization level not supported.
    The sync_level APPC verb parameter value is not supported.
  • N446: Parameter check.
    A verb was issued with an invalid parameter value.
  • N447: State check.
    A verb was issued in a state that was not compatible with the verb.
  • N448: Allocation error.
    APPC failed to allocate a conversation with a remote TP.
  • N449: Dealloc abend.
    The conversation has ended abnormally.
Parent topic: N - Network Error Messages


N450 - N499

Lists the Network error messages from N450 through N499.
Restriction: This topic applies to Windows environments only.
  • N450: Dealloc abend program.
    The conversation has ended abnormally and has been cleaned up.
  • N451: Dealloc abend switched virtual circuit.
    The conversation has ended abnormally and has been cleaned up.
  • N452: Dealloc abend timer.
    The conversation has ended abnormally and has been cleaned up.
  • N453: Dealloc normal.
    The conversation has ended normally.
  • N454: Program error no truncation.
    The remote TP has issued a send_error APPC verb.
  • N455: Program error truncation.
    The remote TP has issued a send_error APPC verb and some of the data received locally was truncated.
  • N456: Program error purging.
    The remote TP has issued a send_error APPC verb and some of the data sent to the remote TP was truncated.
  • N457: Conversation failure retry.
    A temporary failure has ended the conversation.
  • N458: Conversation failure no retry.
    A permanent failure has ended the conversation.
  • N459: Switch virtual circuit error no truncation.
    The remote TP has issued a send_error APPC verb.
  • N460: Switch virtual circuit error truncation.
    The remote TP has issued a send_error APPC verb and some of the data received locally was truncated.
  • N461: Switch virtual circuit error purging.
    The remote TP has issued a send_error APPC verb and some of the data sent to the remote TP was truncated.
  • N462: Unsuccessful.
    An APPC verb could not execute.
  • N463: Conversation type mixed.
    The TP has issued both basic and mapped conversation verbs on the same conversation.
  • N464: Transaction program is busy.
    An APPC verb could not execute because Communication Manager is processing another thread.
  • N465: Communication subsystem abended.
    Communication Manager has ended abnormally and will have to be restarted.
  • N466: Communication subsystem is not loaded.
    Either Communications Manager has not been started or it is not properly configured for APPC.
  • N467: Invalid verb segment.
    The verb crosses a segment boundary.
  • N468: Unexpected DOS error.
    An OS/2 system call in Communication Manager has failed unexpectedly.
  • N469: Stack too small.
    APPC has determined that the TP stack size is too small.
  • N476: Security Location Not Configured.
    First, install the Password Expiration Manager (PEM) on the mainframe (see the host installation and configuration instructions). Then, configure access to the remote host PEM software using the Gateway Profile utility. Select location type PEM (APPC) or PEM (TCP).
  • N477: Invalid Host Authorization.
    The AUTHID used to access the host database is not valid. Check your AUTHID and try again.
  • N478: Invalid Host Password.
    The AUTHID is valid, but the password is not. Check your password and try again.
  • N479: Host Authorization Has Expired.
    Your password has expired. See your host system administrator for assistance.
  • N480: Host Authorization Has Been Revoked.
    The AUTHID used to access the host database has been revoked. See your host system administrator for assistance.
  • N486: Nucleus loopback error.
    AS multiple database support problem. Contact Micro Focus Technical Support.
  • N487: AS target not supported.
    AS multiple database support problem.
  • N488: An AS target module failed to load.
    AS multiple database support problem.
  • N489: An AS target module function address was not found.
    AS multiple database support problem.
  • N496: Protocol memory allocation failure.
    Protocol module problem. Contact Micro Focus Technical Support.
  • N497: Transaction identifier is invalid.
    Protocol module problem. Contact Micro Focus Technical Support.
  • N498: Connection identifier is invalid.
    Protocol module problem. Contact Micro Focus Technical Support.
  • N499: Unsupported protocol.
    Protocol module problem.
Parent topic: N - Network Error Messages


N500 - N599

Lists the Network error messages from N500 through N599.
Restriction: This topic applies to Windows environments only.
  • N500: A protocol module failed to load.
    Protocol module problem.
  • N501: A protocol module function address was not found.
    Protocol module problem.
  • N506: No available connections.
    In memory module problem.
  • N507: Open semaphore failure.
    In memory module problem.
  • N508: Create semaphore failure.
    In memory module problem.
  • N509: Shared memory failure.
    In memory module problem.
  • N510: Open process failure.
    In memory module problem.
  • N511: Cannot communicate with server.
    The client application cannot establish communications with the specified server. An "accept connection" failure has occurred.
  • N512: Connection is closed.
    In memory module problem.
Parent topic: N - Network Error Messages


PIC - Picture Error Messages

Restriction: This topic applies to Windows environments only.
  • PIC000: Error system error: Unknown error errorID.
    The program attempted to display an error that was not found in this error file.
  • PIC001 Syntax error in mask definition.
    The Numeric Format specified in the Options is invalid.
  • PIC002 Grouping character found twice or in illegal position.
    The Numeric Format defined in Options contains two grouping characters (e.g., two commas) or the grouping character is in the wrong position (e.g., after the decimal point).
  • PIC003 No grouping length.
    A serious internal error has occurred in Option's picture parser. Contact Micro Focus Technical Support.
  • PIC004 Decimal character found twice or in illegal position.
    The Numeric Format defined in Options contains two decimal characters (e.g., two decimal points) or the decimal character is in the wrong position (e.g., 99.99,).
  • PIC005 Rounding character in illegal position.
    The Numeric Format defined in Options contains an incorrectly placed rounding character (r). This character, when used, must be the very last character in the picture string (e.g., xxx,9.99+r).
  • PIC006 Illegal character in picture specification.
    A character, other than those allowed, is included in the Date, Time or NumericFormat specified in Options.
  • PIC007 $ character found on both sides of decimal.
    The Numeric Format defined in Options contains a money character (e.g., $) on both sides of the decimal character (e.g., $$$$.$$ is invalid). This character can appear only on the left side of the decimal.
  • PIC008 Sign character found on both sides of the decimal.
    The Numeric Format defined in Options contains a sign character (e.g., +) on both sides of the decimal character (e.g., +$99.99+r is invalid). This character can be placed on the left or the right of the decimal point, but not both.
  • PIC009 Error in substitution portion of picture definition.
    The $=, .=, or ,= clause in the Numeric Format defined in Options is invalid. It may, for example, contain an invalid character or be missing the required delimiters.
  • PIC010 Illegal decimal found in picture.
    The Numeric Format defined in Options contains an invalid decimal sign character. Only a period can be used in the picture portion of a Numeric Format. For example: 999.99 .=',' is valid; 999,99 .=',' is not.
  • PIC011 Illegal rounding character found in picture.
    The Numeric Format defined in Options contains an invalid rounding character. Only an "r" can be used to indicate rounding, and this character must appear at the end of the picture string.
  • PIC012 Illegal dollar sign found in picture.
    The Numeric Format defined in Options contains an invalid money character. Only a dollar sign can be used in the picture portion of the format. For example: $$9.99 .='>=' is valid; >=>=9,99 .='>=' is not.
  • PIC013 Closing single quote not found in substitution string.
    The substitution character string defined in the $=, .=, or ,= clause in the Numeric Format defined in Options does not end with a single quote. For example: $999.99 .$='fl' is valid; $999,99 .='fl is not.
  • PIC014 Value too wide for picture field.
    The numeric value being entered or displayed is larger than the Numeric Format picture defined in Options.
  • PIC015 Error in time/date picture definition.
    The Time Format or the Date Format in Options is incorrectly specified.
  • PIC016: Error trying to identify the picture format type.
    A serious internal error has occurred because the active program received an illegal data type. Contact Micro Focus Technical Support.
  • PIC017 Invalid year value.
    The date value being entered or displayed is inconsistent with the Date Format specified in Options.
  • PIC018 Invalid separator in value.
    The numeric or money value being entered or displayed contains a separator character (e.g., the comma in 1,000) that is inconsistent with the Numeric Format currently specified in Options.
  • PIC019 Invalid character in value.
    A value that is being entered or displayed contains a character that is inconsistent with a picture currently specified in Options.
  • PIC020 Money value error.
    The money value being entered or displayed is inconsistent with the Money Format currently specified in Options.
  • PIC021 Numeric value error.
    The numeric value being entered or displayed is inconsistent with the Numeric Format currently specified in Options.
  • PIC022 Illegal Integer value.
    The integer value that is being entered or displayed is out of range. It contains more digits than specified by the NumericFormat in Options.
  • PIC023 Illegal Time value.
    The time value that is being entered or displayed is inconsistent with the Time Format currently specified in Options.
  • PIC024 Illegal Date value.
    The date value that is being entered or displayed is inconsistent with the Date Format currently specified in Options.
  • PIC025 Scale is bigger than precision.
    The Float Decimal Places value (i.e., scale) specified in Options is larger than the total number of digits allowed for a float value on your system (i.e., precision).
  • PIC026 Invalid separator in time value.
    The time value being entered or displayed contains a separator character (e.g., the colon in 4:00) that is inconsistent with the Time Format currently specified in Options.
  • PIC027 Invalid separator in date value.
    The date value being entered or displayed contains a separator character (e.g., the dash in 03-30-86) that is inconsistent with the Date Format currently specified in Options.
  • PIC028 Invalid separator in timestamp value.
    The timestamp being entered or displayed contains a separator character (e.g., the colon 04:00) that is inconsistent with the Time Format currently specified in Options.
Parent topic: SQL Option for DB2 Error Messages


SQL - SQL PL/I Precompiler Error Messages

Restriction: This topic applies to Windows environments only.
  • SQL0001S DECLARE syntax error, last token read: token
    A syntax error has occurred in the DECLARE section. Check at or near token to find the problem.
  • SQL0002S identifier too long
    The current identifier is too long to be a valid identifier.
  • SQL0003S engine check error: message
    Error message message is being returned from the engine. Refer to message to determine the problem and its resolution.
  • SQL0004S identifier token not defined
    An identifier is being used that is not defined.
  • SQL0005S host variable used without colon
    The host variable is defined without a colon in the SQL statement.
  • SQL0006S UNION of SELECT INTO is deprecated feature with undefined results
    A UNION SQL statement that contains a SELECT INTO has been detected. This feature is no longer supported and the results are undefined.
  • SQL0101S error creating DBRM file: file
    Cannot create the DBRM file file. Likely reasons are that the file already exists or there is a permissions/sharing problem.
  • SQL0102S error opening input file: file
    Cannot open the input file file. Likely reasons are that the file does not exist or there is a permissions/sharing problem.
  • SQL0103S error creating output file: file
    Cannot create the output file file. Likely reasons are that the file already exists or there is a permissions/sharing problem.
  • SQL0104S error writing DBRM file
    Cannot write to the DBRM file. Likely reasons are that it does not exist or there is a permissions/sharing problem.
  • SQL0105S error reading input file
    Cannot read the input file. Likely reasons are that it does not exist or there is a permissions/sharing problem.
  • SQL0106S error writing output file
    Cannot write to the output file. Likely reasons are that it does not exist or there is a permissions/sharing problem.
  • SQL0107S scope mismatch
    The scope of a variable is ambiguous. Check to make sure only one variable is visible to a section with the same name.
  • SQL0108S end of file before end of quoted string
    A closing quote is missing.
  • SQL0109S end of file before end of comment
    A comment was not closed before the end of the file.
  • SQL0110S token buffer overflow
    The internal buffer for the lexical analyzer is full due to an object being too large.
  • SQL0111S statement buffer overflow
    The internal buffer for statement parsing is full due to a statement being too large to parse.
  • SQL0112S parser stack overflow
    The internal buffer for generic parsing is full due to an object being too large to parse.
  • SQL0113S include file file not found
    Cannot find the include file file in the current program path.
  • SQL0114S host variable error in sqlda
    Sqlda is reporting either too many or too few host variables.
  • SQL0115S illegal host variable marker '?'
    The '?' character cannot be used as a host variable marker.
  • SQL0116S invalid directives: directive
    The directives currently being used are invalid.
  • SQL0117S same name specified for the input file and the output file
    The same name is being used for both the input and output files. Modify the name of one of them.
  • SQL0118S host variable hostvar not found
    The preprocessor could not find the host variable hostvar.
  • SQL0119S declaration stack overflow
    The internal buffer for declaration parsing is full due to a declaration is too large to parse.
  • SQL0120S SQL syntax error, last token read: token
    The SQL Option generic syntax parser found an error in the SQL statement.
  • SQL0121S cursor cursor not declared
    An OPEN, FETCH or CLOSE statement references a cursor name that was not DECLAREd.
  • SQL0122S cursor cursor already declared
    The current cursor cursor has already been declared. Make sure the cursor name is valid and remove or rename it.
  • SQL0123S invalid host variable: hostvar
    Host variables must be valid PL/I identifiers
  • SQL0124S invalid null indicator variable: hostvar
    A null indicator variable must be a 2-byte integer.
  • SQL0125S statement statement not declared
    The current statement statement has not been declared.
  • SQL0126S statement statement already declared
    The current statement statement has already been declared.
  • SQL0127S host variable hostvar ambiguous
    The same variable name is being used twice in the same scope.
Parent topic: SQL Option for DB2 Error Messages


WADM - SQLWizard Administrator Error Messages

Restriction: This topic applies to Windows environments only.
  • WADM002: Passwords don't match.
    The password you re-entered did not match the one entered previously. Make sure you enter the same password twice.
  • WADM003: You must enter a UserID before entering a password.
    A UserID must be entered before you will be permitted to enter a password. Enter a UserID.
  • WADM004: Expected number record(s), got number.
    Internal error. Contact Micro Focus Technical Support.
  • WADM005: Password must have at least number characters.
    The password you have entered does not meet the length criterion required by the password enforcement level specified in the Configuration utility.
  • WADM006: Password must contain at least one digit.
    Each password entered must contain at least one digit in order to meet the criteria required by the password enforcement level specified in the Configuration utility.
  • WADM007: Password must contain the characters character and character.
    Each password entered must contain the specified characters in order to meet the criteria required by the password enforcement level specified in the Configuration utility.
  • WADM008: Incomplete information retrieved from table name.
    Internal error. Contact Micro Focus Technical Support.
  • WADM009: User userid belongs to unregistered group name.
    According to the SYSXDB.SYSACFMEMBERS table in the SYSTEM location, user userid belongs to group name. However, group name is missing from the SYSXDB.SYSACFGROUPS table. Any group in SYSASCMEMBERS must also be in SYSACFGROUPS. You may remedy this situation by inserting group name into SYSACFGROUPS by selecting the Insert Group option under the Groups menu in XADMIN. Or you can delete group name from SYSACFMEMBERS by running the following interactive SQL command:
  • WADM010: userid is not a registered user.
    The user you are attempting to update or delete does not exist. Add the user, or enter another UserID.
  • WADM011: Unknown table format in table name.
    Internal error. Contact Micro Focus Technical Support.
  • WADM012: No password specified.
    There is no password specified for this user. A password is required in order to add or update this user. Enter a password.
  • WADM013: User userid is already registered.
    The user you have specified already has an entry in the SYSXDB.SYSACFUSERS table. UserIDs must be unique. Enter a new UserID.
  • WADM014: No UserID specified.
    You must specify a UserID in order to add, delete or update the user.
  • WADM016: No User Comment specified.
    You must specify a user comment in order to add or update the user.
  • WADM017: Memory allocated insufficient for the number of groups found.
    Memory allocated insufficient for the number of groups found.
  • WADM018: Group name already exists.
    You have attempted to create a new group using a group authorization ID that already exists in the SYSXDB.SYSACFGROUPS table. Group auth-IDs must be unique.
  • WADM019: No Group Authorization ID specified.
    You have attempted to add, update, or delete a group but did not specify a group authorization ID. The auth-ID is required to identify the group.
  • WADM020: Group name does not exist.
    You have attempted to delete or update a group, but no group was found in the SYSXDB.SYSACFGROUPS table whose authorization ID matches the one you entered.
  • WADM022: name is not a valid group name.
    The group name you have entered is not a valid database object name. See the SQLWizard online help for the allowable syntax for database object names.
  • WADM023: The priority name does not exist.
    You must enter an existing priority in order to update or delete.
  • WADM027: The User ID entered is invalid.
    The User ID should conform to Ordinary Identifiers. See the SQL Reference for more details.
  • WADM028: Valid range for value value is > 0 and < number.
    One of the governor values was out of the legal range. Enter a valid value.
  • WADM029: name is not a valid priority name.
    The priority name you have entered is not valid.
  • WADM030: No Priority Name specified.
    You must specify a priority in order to add, delete or update a priority.
  • WADM031: Priority name already exists.
    You have attempted to create a new priority using a priority that already exists in the SYSXDB.SYSGOVERNOR table. Priorities must be unique.
  • WADM032: An error occurred while updating an internal list (name).
    Internal error. Contact Micro Focus Technical Support.
  • WADM033: The SecondaryID name is invalid.
    The SecondaryID should conform to Ordinary Identifiers. See the SQL Reference for more details.
  • WADM034: Cannot delete yourself ('name') as a User.
    You are currently logged in as user 'name', so it is not possible to delete 'name' as a user.
Parent topic: SQL Option for DB2 Error Messages


WCRT - SQL Wizard Create/Alter Table Error Messages

Restriction: This topic applies to Windows environments only.
  • WCRT000: Error system error: Unknown error error id.
    SQLWizard attempted to display an error that was not found in the XCRT.XRR error file.
  • WCRT001: Illegal identifier identifier specified for object Name. Last symbol read was symbol.
    An invalid name was specified for the object of type object-type. SQLWizard was only able to validate the name up to the symbol symbol.
  • WCRT004: The data type and/or length of column col1 does not match that of primary key column col2.
    When specifying the foreign key columns of a relationship, you must choose those that match both in data type and length to that of its corresponding primary key column. Check the data type and length of both the foreign key and primary key column to be sure they match.
  • WCRT005: No columns specified for the object.
    Make sure you choose columns for the index or relationship definition. If you are specifying an index, make sure you specify column names in the Index Columns list. If you are specifying a relationship, make sure a foreign key column is specified for each primary key column in the list.
  • WCRT006: Identifier identifier exceeds its maximum length of length for object-type name.
    The identifier specified exceeded its maximum limit of length for an object of type object-type. Enter a shorter name and try again.
  • WCRT007: Incomplete table specification. No object specified.
    A table was incompletely defined. Enter a valid value for the missing item.
  • WCRT008: Referenced table table does not contain a primary key.
    When choosing a referenced table for a relationship, be sure to choose a table that contains a primary key.
  • WCRT009: The index index does not exist for the table table.
    An index with the name index-name was not found in the system catalog for the table table-name.
  • WCRT010: The location name does not exist.
    A location with the name location-name was not found in the SYSXDB.SYSLOCALS catalog table.
  • WCRT011: The synonym/alias name does not exist in the database.
    A synonym/alias with the name name was not found in the system catalog.
  • WCRT012: Incomplete location specification. No object specified.
    A location was incompletely defined. Enter a valid value for the missing item.
  • WCRT013: No name specified for field # fieldnum.
    A field was specified without a name. Specify a valid name for the field.
  • WCRT014: No data type specified for field # fieldnum.
    A field was specified without a data type. Choose a data type from the drop-down list provided in the Data Type entry field.
  • WCRT015: No length specified for field # fieldnum.
    A field was specified without a length. Specify a valid length for the field. Some data types (e.g. Smallint, Integer, Float, Date, Time, etc.) have a fixed length and do not require a length to be entered. Others (e.g. Decimal, Char, Varchar, Graphic, & Vargraphic) require a length to be specified.
  • WCRT016: No column with a matching type found.
    An attempt was made to move a foreign key column to a new position within the Foreign Key Cols -> Referenced Key Cols list. However, no referenced column with a matching data type and length was found in the direction you tried to move. Remember that foreign key columns and referenced key columns must match in data type and length.
  • WCRT017: No foreign key name specified.
    Specify a valid foreign key name and try again.
  • WCRT018: No index name specified.
    Specify a valid index name and try again.
  • WCRT019: No alias name specified.
    Specify a valid alias name and try again.
  • WCRT020: No synonym name specified.
    Specify a valid synonym name and try again.
  • WCRT021: Cannot undo the Drop designation for this primary key index due to the existence of another primary key specification.
    An attempt was made to remove a Drop designation for a primary key index. However, another primary key index has been specified for this table. Since allowing this operation would yield more than one primary key for the table, and only one is allowed per table, this is illegal.
  • WCRT022: No referenced table specified for the relationship.
    The relationship specification is incomplete. Specify a referenced table to complete the specification. Be sure that this referenced table contains a primary key.
  • WCRT023: object name name is already defined for this table.
    An object of type object-type with the name name has already been specified for this table. Choose another name and try again.
  • WCRT024: Location specified in Alias Name.
    There is no need to qualify the alias name with a location, as the location may be chosen from the list. Please enter a one-part (i.e. alias name alone) or a two-part name (i.e. sqlid.alias-name), and specify the locations from the list.
  • WCRT025: No target location(s) specified for the Alias.
    When creating an alias you must specify at least one location where it is to be created. Choose locations from the Target Locations Not Selected list to move over to the Target Locations Selected list.
  • WCRT026: Index creator. index-name already exists in location location.
    All indexes must have unique names within a location. The index name specified already exists in the SYSIBM.SYSINDEXES catalog table for the particular location. Choose another name.
  • WCRT027: Table/View/Synonym/Alias creator. name already exists in location location.
    All tables/views/synonyms/aliases must have unique names within a location. The name specified already exists in the system catalog tables for that particular location. Choose another name.
  • WCRT028: Location name already exists.
    XDB Server locations must be given unique names. The location name specified already exists in the SYSXDB.SYSLOCALS catalog table. Choose another name.
  • WCRT029: Cannot alter/drop table with over number columns using this method.
    This error should not occur under normal circumstances. If you receive this error, please contact Micro Focus Technical Support.
  • WCRT030: The directory directory-name does not exist.
    The directory directory-name does not exist. You have to create this directory before you proceed with the creation of the location.
  • WCRT031: Log cannot be forwarded to a directory-name. It appears to be used by a different location.
    Specify a directory that is not already in use by another location and try again.
  • WCRT032: Invalid format for directory directory-name.
    Specify a valid directory name and try again.
  • WCRT033: Illegal null permission for field Field specified.
    Global temporary tables cannot contain "unique" or "with default" fields.
  • WCRT034: You cannot alter a Global Temporary Table.
    You have tried to alter a global temporary table. This is not allowed.
  • WCRT035: You can not alter a table that contains a distinct type
    An attempt was made to alter a table with a distinct data type. This is not allowed.
  • WCRT036: Altering a table that contains a BLOB column is not supported
    An attempt was made to alter a table with a BLOB column. This is not supported.
Parent topic: SQL Option for DB2 Error Messages


WDG - SQL Wizard Declaration Generator Error Messages

Restriction: This topic applies to Windows environments only.
  • WDG001: name is not a legal table name.
    The table name you have entered is invalid. Select a valid table name.
  • WDG005: Unknown field type in table tablename.
    An illegal field type was specified in the table named.
  • WDG008: name is not a legal language name.
    The target language you have entered is invalid. Valid language names are COBOL, PL/I and C. Enter a valid name.
  • WDG010: Illegal computational value.
    The computation value must be > 0 and < 10.
  • WDG015: Error number spawning editor name.
    This error is not used. May be used in future versions.
  • WDG016: Accessing file name.
    The Declaration Generator cannot access the specified file. Please make sure that it exists and is not locked by any other user.
  • WDG017: Invalid location name nameerrortype.
    The specified location does not exist. Please select an existing location.
  • WDG018: No filename on command line.
    The Declaration Generator was run in batch mode with no batch filename on the command line. Please reissue the batch command with a legal batch filename.
  • WDG019: No table on command line.
    The Declaration Generator was run in batch mode with no batch filename or table name on the command line. Please reissue the batch command with a legal batch filename or a table name on the command line.
  • WDG020: Invalid option on command line.
    The Declaration Generator was run in batch mode with an illegal parameter on the command line. Please check you parameters.
  • WDG021: No filename on command line.
    The Declaration Generator was run in batch mode with no batch filename or output file name on the command line. Please reissue the batch command with a legal output filename on the command line.
  • WDG022: Can't create batch file.
    The Declaration Generator cannot create the selected file to contain a batch file. Make sure that the path exists and the destination file is not read only or locked by another user.
  • WDG023: No table name.
    No table name was specified. There is nothing to do.
  • WDG024: No filename.
    No output filename was specified. Declaration Generator needs to know where to put the output.
  • WDG025: No structure name.
    No output structure name was specified. Declaration Generator needs to know the name of the output structure.
  • WDG026: Error updating the status bar.
    Internal error. Declaration Generator could not display a message on its status bar. Please note what operation was being performed and contact Micro Focus Technical Support.
Parent topic: SQL Option for DB2 Error Messages


WE - SQL Wizard Export Error Messages

Restriction: This topic applies to Windows environments only.
  • WE000 - WE049
    Lists the SQL Wizard Export error messages from WE000 through WE049.
  • WE050 - WE099
    Lists the SQL Wizard Export error messages from WE050 through WE099.
  • WE100 - WE149
    Lists the SQL Wizard Export error messages from WE100 through WE149.
Parent topic: SQL Option for DB2 Error Messages


WE000 - WE049

Lists the SQL Wizard Export error messages from WE000 through WE049.
Restriction: This topic applies to Windows environments only.
  • WE001: Unable to create document window, XVT error error.
    An error occurred while attempting to create a child window. You may be low on resources. Try unloading some programs, or closing other child windows. If you are still having problems, please contact Micro Focus Technical Support.
  • WE002: No query exists on the query screen.
    An internal error has occurred. Please contact Micro Focus Technical Support.
  • WE003: Index is damaged.
    An internal error has occurred. Please contact Micro Focus Technical Support.
  • WE004: Unable to query auth-id.SYSTABLES to get information about item.
    An internal error has occurred. Please contact Micro Focus Technical Support.
  • WE005: Invalid value value for APPEND_ERR_FILE command in group number, groupname.
    The batch file command APPEND_ERR_FILE can only take the values "y" or "n".
  • WE006: No translation table exists with specified INCCSID and OUTCCSID.
    There is no record in the SYSIBM.SYSSTRINGS table whose values in the INCCSID and OUTCCSID fields match the numbers found in XDB.INI. If you are exporting in the DSNTIAUL format, check InCCSID and OutCCSID in the [Export] section of XDB.INI. If you are exporting in a different format, check AscSrcCodePage and AscDstCodePage.
  • WE007: Unable to add field name name to Included list.
    The system was unable to add the specified name to the name of columns that are to be included in the current export specification. You may be out of memory.
  • WE008: Cannot open file filename.
    Couldn't open the specified file.
  • WE009: No more Export windows can be created.
    You have created the maximum allowable number of Export windows. The maximum is 10. To create a new window you must close an existing window.
  • WE010: Table table is empty.
    No data can be exported because the table specified is empty.
  • WE011: Invalid value value for TIMESTAMP command in group number, groupname.
    The batch file command TIMESTAMP can only take the values "y" or "n".
  • WE012: Invalid field type specified for field fieldname.
    An illegal field type was specified for the field named. Check the documentation for a list of valid field types.
  • WE013: Unable to retrieve field information.
    An error occurred when attempting to retrieve field information from a batch specification.
  • WE014: Batch Export file file-name not found.
    Select a batch export file that exists.
  • WE015: Keyboard navigation error.
    An error occurred when trying to resolve the next/previous object in the keyboard navigation list. Contact Micro Focus Technical Support.
  • WE016: No fields in table specification.
    The export cannot proceed because there are no fields in the 'Included' listbox on the screen.
  • WE017: Internal error getting text from screen. Contact Micro Focus Technical Support.
    The system could not process an entry on the screen. Contact Micro Focus Technical Support.
  • WE018: Internal error opening table window. Contact Micro Focus Technical Support.
    The system was unable to open the export specification. Contact Micro Focus Technical Support.
  • WE019: Internal error opening query window. Contact Micro Focus Technical Support.
    The system was unable to open the export specification.
  • WE020: Batch Export file file-name does not contain a group heading
    The first line of a batch export file must be a group heading.
  • WE024: Query result does not contain any records.
    The current query does not retrieve any rows, so there is nothing to export. Check the WHERE condition to make certain it is correct.
  • WE025: Data file filename is empty.
    The file you wish to view does not contain any data.
  • WE026: Float value in field fieldname is larger than the IBM370 limit.
    The float value is not supported by IBM370.
  • WE027: Data exceeds 4K page size.
    The size of a record in the table you are exporting is greater than 4K. When exporting to the DSNTIAUL format, each record must fit within a 4K page size. If the record contains one or more columns of type LONG VARCHAR, the data in those columns is truncated if possible to make the record fit into 4K. However, if the other column lengths are large enough, this won't reduce the size sufficiently.
  • WE028: No output filename specified.
    You have not specified a filename for your export file.
  • WE030: Invalid output file specification filename.
    The file name specified is not a valid file specification.
  • WE031: Invalid table name.
    You have entered a table name that does not satisfy table-naming criterion. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE032: No table name specified.
    You have not specified the name of the table you wish to export. The table name is required when exporting and when saving an export specification to a batch export or batch import file.
  • WE033: Error writing to file filename.
    It was not possible to write to the specified DSNTIAUL file. Your hard disk may be full.
  • WE034: Can't display a join of multiple tables on Export's Design screen.
    You cannot switch to the Design view because the current query contains multiple tables in the FROM clause.
  • WE035: Field fieldname specified in query does not exist in table tablename.
    You have specified a field that is not found in the table named in the FROM clause.
  • WE036: Invalid query.
    The query was not recognized as a valid SQL statement.
  • WE037: Invalid record delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. The record delimiter for standard ASCII files is a carriage-return followed by a line-feed, as indicated by the default <013><010>. SQLWizard allows you to specify an alternate end-of-record delimiter to handle other file structures.
  • WE038: Invalid field delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. When selecting a field delimiter, be sure you do not use a character found in your data or in the default masks for the data types in the exported table. For example, do not use a comma as the delimiter if your data contains numeric or money values grouped with a comma.
  • WE039: Invalid value for number of spaces between fields.
    The number of spaces between fields should be an integer from 0 to 99.
  • WE040: Batch file filename is invalid.
    The specified batch file is not a valid batch export file.
  • WE041: Batch file contains more than one transaction.
    Export cannot display a batch file that contains more than one transaction.
  • WE042: Error opening log file filename.
    An attempt to open the specified log file failed.
  • WE043: Invalid error log file name filename.
    The specified name is an invalid file name for the underlying operating system. Check your operating system documentation for a description of valid file names.
  • WE044: Invalid ON_ERROR value value.
    The ON_ERROR value must be PROMPT, CONTINUE, QUIT, or END_ALL.
  • WE045: Invalid batch file name filename.
    The specified file name is not a valid file name for your operating system. See your operating system documentation for a description of valid file names.
  • WE046: Invalid data file name filename.
    The specified file name is not a valid file name for your operating system. See your operating system documentation for a description of valid file names.
  • WE048: Invalid value for DSETPASS.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE049: Invalid STOGROUP name.
    STOGROUP names must follow the rules for short identifiers. The STOGROUP used is invalid.
Parent topic: WE - SQL Wizard Export Error Messages


WE050 - WE099

Lists the SQL Wizard Export error messages from WE050 through WE099.
Restriction: This topic applies to Windows environments only.
  • WE050: PRIQTY value must be an integer in the range 12 to 4,194,304.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE051: SECQTY value must be an integer in the range 0 to 131,068.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE052: FREEPAGE value must be an integer in the range 0 to 255.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE053: PCTFREE value must be an integer in the range 0 to 99.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE054: No tables found with authid auth-id in location location-name.
    See the CREATE INDEX command description in the SQL Reference for information on the correct parameters.
  • WE055: Invalid DATABASE name.
    Database names must follow the rules for short identifiers. The database name used is invalid.
  • WE056: Invalid TABLESPACE name.
    Tablespace names must follow the rules for long identifiers. The Tablespace used is invalid.
  • WE057: Invalid EDITPROC name.
    EDITPROC names must follow the rules for short identifiers. The name used is invalid.
  • WE058: Invalid VALIDPROC name.
    VALIDPROC names must follow the rules for short identifiers. The name used is invalid.
  • WE059: Internal error reading batch file.
    The system was unable to read the batch file. Check to make sure the file is a valid Export batch script.
  • WE060: Unable to access code page information.
    The system encountered an error when attempting to access the specified code page. Make sure that the code page has been defined in SYSTEM.SYSIBM.SYSSTRINGS, and that it has been correctly specified in the batch script.
  • WE061: Invalid error log file name file-name specified in batch file.
    The specified name is an invalid filename for the underlying operating system. Check your operating system documentation for a description of valid filenames.
  • WE062: Float value in field fieldname is smaller than the IBM370 limit.
    The float value is not supported by IBM370.
  • WE063: Unable to open View Batch window, probably out of memory.
    The system tried to open the view window, but was unable to do so. Try closing down other SQLWizard windows, or other applications that are using system resources.
  • WE064: Unable to open View Data window, probably out of memory.
    The system tried to open the view window, but was unable to do so. Try closing down other SQLWizard windows, or other applications that are using system resources.
  • WE065: Unrecognized value value for SQL_OPTS command in group number, groupname.
    Export found an illegal setting in the batch file. The syntax of this command is:
  • WE066: Invalid value value for ASCII_CODEPAGE in group number, groupname.
    Export found an error in the current batch export file. The syntax of this command is:
  • WE067: Invalid value value for EBCDIC_CODEPAGE in group number, groupname.
    Export found an error in the current batch export file. The syntax of this command is:
  • WE068: Invalid value value for FORMAT command in group number, groupname.
    Export found an error in the current batch export file. The syntax of this command is:
  • WE069: Batch file filename is empty.
    The specified file does not contain any batch specifications.
  • WE070: Unknown batch command command in group number, groupname.
    The batch export file contains invalid or unknown commands.
  • WE071: Invalid value value for FLD_DELIMITER command in group number, groupname.
    The syntax of this command is:
  • WE072: Invalid value value for REC_DELIMITER command in group number, groupname.
    The syntax of this command is:
  • WE073: Invalid value value for HEADING command in group number, groupname.
    The syntax of this command is:
  • WE074: Invalid value value for FILENAME command in group number, groupname.
    The syntax of this command is:
  • WE075: Invalid value value for TABLE command in group number, groupname.
    The syntax of this command is:
  • WE076: Invalid value value for PAGE_SIZE command in group number, groupname.
    The syntax of this command is:
  • WE077: Invalid value value for FIELDS command in group number, groupname.
    The syntax of this command is:
  • WE078: Invalid value value for QUOTES command in group number, groupname.
    The syntax of this command is:
  • WE079: Invalid value value for SPACES command in group number, groupname.
    The syntax of this command is:
  • WE080: Unable to get information about fields in table tablename.
    The system failed in an attempt to get information about the columns in the specified table. Make sure you have privileges on the catalog tables or views, and that the SYSIBM and SYSXDB items in the SQL page of the Options are set to the correct AuthID values.
  • WE081: Invalid value value for REPLACE command in group number, groupname.
    The syntax of this command is:
  • WE082: Invalid value value for DATABASE command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE083: Invalid value value for TABLESPACE command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE084: Invalid value value for EDITPROC command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE085: Invalid value value for VALIDPROC command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE086: Invalid value value for AUDIT command in group number, groupname.
    AUDIT value must be one of NONE, CHANGES or ALL.
  • WE087: Invalid value value for VCAT command in group number, groupname.
    VCAT value must be one of WITH, ROOT, PATH or NAME.
  • WE088: Invalid value value for STOGROUP command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE089: Invalid value value for PRIQTY command in group number, groupname.
    PRIQTY value must be a number from 0 to 4,194,309.
  • WE090: Invalid value value for SECQTY command in group number, groupname.
    SECQTY value must be a number from 0 to 131,068.
  • WE091: Invalid value value for ERASE command in group number, groupname.
    ERASE value must be either Y or N.
  • WE092: Invalid value value for FREEPAGE command in group number, groupname.
    FREEPAGE value must be a number from 0 to 255.
  • WE093: Invalid value value for PCTFREE command in group number, groupname.
    PCTFREE value must be a number from 0 to 99.
  • WE094: Invalid value value for DUPQTY command in group number, groupname.
    DUPQTY value must be either 8, 16, 32, 64 or 128.
  • WE095: Invalid value value for CLUSTER command in group number, groupname.
    CLUSTER value must either Y or N.
  • WE096: Invalid value value for SUBPAGES command in group number, groupname.
    SUBPAGES value must be either 1, 2, 4, 8 or 16.
  • WE097: Invalid value value for BUFFERPOOL command in group number, groupname.
    BUFFERPOOL value must be in one of the following formats:
  • WE098: Invalid value value for DSETPASS command in group number, groupname.
    The value must be a valid database object name. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WE099: Invalid value value for CLOSE command in group number, groupname.
    CLOSE value must be either Y or N.
Parent topic: WE - SQL Wizard Export Error Messages


WE100 - WE149

Lists the SQL Wizard Export error messages from WE100 through WE149.
Restriction: This topic applies to Windows environments only.
  • WE100: Invalid value value for DEFER command in group number, groupname.
    DEFER value must be either Y or N.
  • WE101: Error opening batch file for writing.
    Unable to open file for writing import or export specifications.
  • WE102: Error writing to batch file.
    Unable to write import or export specifications to current batch file.
  • WE103: Invalid value value for SRC_ASCII_CODEPAGE command in group number, groupname.
    Codepage must be a positive integer or 0.
  • WE104: Invalid value value for DST_ASCII_CODEPAGE command in group number, groupname.
    Codepage must be a positive integer or 0.
  • WE105: Warning: No translation table matches the default ASCII source and destination codepages pagenopageno in XDB.INI.
    The values in XDB.INI in the [Export] section for AscSrcCodePage and AscDstCodePage do not correspond to the INCCSID and OUTCCSID values of any record in SYSTEM.SYSIBM.SYSSTRINGS.
  • WE106: Invalid Where clause.
    The WHERE condition specified in the Export window is invalid. Check it for syntax errors.
  • WE107: Export to SQL can't export a query that contains more than one table.
    There is more than one table specified in the FROM clause of your Export query statement. This is not allowed when you are exporting to SQL Statements. In SQL mode, edit the FROM clause so that it contains a single table name, or change to another export format.
  • WE108: Query doesn't start with SELECT.
    The Export query statement doesn't begin with the SELECT keyword. In SQL mode, edit the statement so that it begins with the word SELECT. Make sure that it forms a valid query statement.
  • WE109: Export doesn't understand the query. Last symbol read was symbol.
    SQLWizard could not interpret the SELECT statement in the Export window. Check it for syntax errors. Symbol indicates where the error occurred. See the SQL Reference for a description of the SELECT statement syntax.
  • WE110: Query contains a string that is too long for Export to process.
    The SELECT statement in the Export window contains a name (e.g., field name, table name) that is too long. Names exceeding 1024 characters cannot be processed by Export.
  • WE112: Internal error getting For Bit Data info. Contact Micro Focus Technical Support.
    Export has experienced an internal error while processing the SELECT statement. Contact Micro Focus Technical Support.
  • WE113: Internal error getting Nullable info. Contact Micro Focus Technical Support.
    Export has experienced an internal error while processing the SELECT statement. Contact Micro Focus Technical Support.
  • WE114: Invalid record delimiter – escape character character is not allowed.
    The escape character specified on the SQL tab of Options cannot be used as a record delimiter.
  • WE115: Invalid field delimiter – escape character character is not allowed.
    The escape character specified on the SQL tab of Options cannot be used as a field delimiter.
Parent topic: WE - SQL Wizard Export Error Messages


WI - SQL Wizard Import Error Messages

Restriction: This topic applies to Windows environments only.
  • WI000 - WI049
    Lists the SQL Wizard Import error messages from WI000 through WI049.
  • WI050 - WI099
    Lists the SQL Wizard Import error messages from WI050 through WI099.
  • WI100 - WI149
    Lists the SQL Wizard Export error messages from WI100 through WI149.
Parent topic: SQL Option for DB2 Error Messages


WI000 - WI049

Lists the SQL Wizard Import error messages from WI000 through WI049.
Restriction: This topic applies to Windows environments only.
  • WI001: Premature end of line found, record record.
    Encountered an unexpected end of line on the record specified.
  • WI002: Number field(s) were found in record number; record should contain number field(s).
    A record containing the wrong number of fields exists in the file you are importing. Check the record in your source file (record n) and make sure that it has the same number of fields as the target table.
  • WI003: The character character in position position in heading line of Fixed ASCII file filename is not allowed in a column name.
    A field name in your fixed-ASCII data file contains a character that is not permitted in a database object name. See your SQL Reference for a list of characters that can be used in a column name.
  • WI004: The maximum number of open Import windows has been reached.
    You have opened the maximum number of Import windows. Close some of the Import windows before you continue.
  • WI005: Table name is not specified.
    You must provide a table name for the target table.
  • WI007: Invalid value number for varchar length; length must be no greater than number.
    The length of a varchar field is greater than the page size set for each record.
  • WI008: No translation table exists with specified INCCSID and OUTCCSID.
    There is no record in the SYSIBM.SYSSTRINGS table whose values in the INCCSID and OUTCCSID fields match the numbers found in XDB.INI. If you are importing in the DSNTIAUL format, check InCCSID and OutCCSID in the [Import] section of XDB.INI. If you are importing in a different format, check AscSrcCodePage and AscDstCodePage.
  • WI009: Keyboard navigation error.
    Internal error. Contact Micro Focus Technical Support.
  • WI010: Invalid value value for DSN_CRLF command in group number, groupname.
    The batch file command DSN_CRLF can only take the values "y" or "n".
  • WI011: No source file name specified.
    You must enter the full pathname of the data file you want to import in the File Name edit box of the Source File Information area.
  • WI012: Unable to open Grid window.
    An internal error is preventing SQLWizard from creating the table area in the Import window. This may be caused by insufficient memory. Close any unnecessary applications, then retry the Import command. If this does not resolve the problem, clear memory by restarting SQLWizard or by rebooting.
  • WI013: Data in field fieldname of record record-name is number characters long but field definition inumber characters.
    The data found in a character field in the source file is longer than the length of that field in the target table.
  • WI014: End-of-line delimiter delimiter not found while counting fields in record.
    The current record in your free format ASCII file does not contain the Field Delimiter specified on the screen.
  • WI015: Invalid value value for APPEND_ERR_FILE command in group number, groupname.
    The batch file command APPEND_ERR_FILE can only take the values "y" or "n".
  • WI016: Invalid value value for APPEND_REC_FILE command in group number, groupname.
    The batch file command APPEND_REC_FILE can only take the values "y" or "n".
  • WI017: DSNTIAUL file file-name does not contain a complete record.
    A record in the DSN file contains a record with size that is smaller than the record size in the destination table.
  • WI018: Invalid value value for TIMESTAMP command in group number, groupname.
    The batch file command TIMESTAMP can only take the values "y" or "n".
  • WI019: Batch import file file-name not found.
    Select a batch import file that exists.
  • WI020: Batch Import file filename does not contain a group heading.
    The first line of a batch import file has to be a group heading.
  • WI021: Record number contains more than the maximum of number fields, or end of record not found.
    Import has detected more fields in the current record than are specified in the table definition. Either your data file contains extra fields in this record, or the record delimiter is missing from this record, causing Import to interpret the data in the next record as part of the data for this record.
  • WI022: Table name is not specified in group number, groupname.
    No value was assigned to the batch file command TABLE.
  • WI023: Error writing to logfile filename, errno = error-number.
    The attempt to write to the specified log file failed. Check your operating system documentation for the meaning of the error specified by the errno value.
  • WI024: Error opening logfile filename.
    An attempt to open the specified log file failed. Either it does not exist or is in use.
  • WI025: End quote missing in field fieldname, record record of data file filename.
    A quote is missing from a character field in a free format ASCII file.
  • WI026: Data exceeds 4K page size.
    The size of a record in a DSNTIAUL file must be no greater than 4096 bytes.
  • WI027: Length specification missing from Char, Varchar, Graphic, or, VarGraphic data type, line line-number.
    Specify these types in the following format:
  • WI029: Number fields were specified, but number fields were found in file.
    There are more fields in the fixed-ASCII source file than there are in the target table. Check the source file to make sure that the length of its records matches that of your destination table.
  • WI030: Unable to open file filename.
    Either the file was not found in the indicated directory, is in use, or is invalid. Check to be sure that you have specified the correct file name and directory.
  • WI031: More field names were found than the number of fields specified.
    The number of fields specified for your table is less than the number of fields found in your data file.
  • WI034: Field name for field number, fieldname, is longer than number characters.
    Field names may not be longer than number characters.
  • WI035: Incorrect field type type in ConvertDataStrToInternal().
    Internal error. Call Micro Focus Technical Support.
  • WI036: Invalid field delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255. See your SQLWizard User's Guide for further information on entering delimiters.
  • WI037: Invalid record delimiter delimiter.
    When specifying a delimiter using decimal notation, use the format <nnn>, where nnn is an integer between 0 and 255.
  • WI038: Invalid source file name filename.
    See your operating system documentation for an explanation of valid file names.
  • WI039: Invalid table name.
    See your documentation for an explanation of valid table names. Also see WSQL045.
  • WI040: Invalid value for number of spaces between fields.
    The number of spaces between fields should be an integer from 0 to 99.
  • WI041: Data file filename is empty.
    It is not possible to import the specified data file, as it contains no data.
  • WI044: Invalid character (character) found in field name in field number in header line of data file.
    An illegal column name was found in the source file. See the SQL Reference for rules for identifiers for XDB Server and DB2. Also see WSQL045.
  • WI047: Invalid length in type specification type, field number.
    The length in the specified field is invalid for the field type.
  • WI048: Invalid length in Character or Varchar type specification type, field number.
    Character and Varchar lengths must be no longer than 4048.
  • WI049: Invalid length in Graphic type specification type, field number.
    Graphic length must be no longer than 127.
Parent topic: WI - SQL Wizard Import Error Messages


WI050 - WI099

Lists the SQL Wizard Import error messages from WI050 through WI099.
Restriction: This topic applies to Windows environments only.
  • WI050: Invalid length in Vargraphic type specification type, field number.
    Vargraphic length must be no longer than 2028.
  • WI051: Batch file contains more than one transaction.
    SQLWizard cannot create an Import window for a batch file that contains more than one transaction.
  • WI052: Batch file filename is invalid.
    The file does not exist, or the file is not a valid Batch Import file.
  • WI054: Can't get info from fixed ASCII file that doesn't contain a header line.
    You must provide a complete specification for the ASCII file, since the system is unable to use a header line to help build a specification.
  • WI055: Error opening table file filename.
    Import in Local Direct Write mode encountered an error when trying to open the file specified. The file may not exist, you may not have privileges on the file or on the path, or the file may be in use.
  • WI057: Error writing to table file filename.
    Import in Local Direct Write mode encountered an error when trying to write to an underlying table file directly. Make certain that the table file can be accessed from the client machine.
  • WI058: Can't access table file filename, probably locked by the XDB Server.
    The table file may already be in use by the database server. You must have exclusive use of the file in order to proceed.
  • WI059: Invalid error log file name filename.
    The file name is not a valid file name.
  • WI060: Invalid record log file name filename.
    The file name is not a valid file name.
  • WI063: Invalid error log file name filename specified in batch file filename.
    The file name is not a valid file name for the underlying operating system. Check your operating system documentation for valid filename format.
  • WI064: Invalid record log file name filename specified in batch file filename.
    The file name is not a valid file name for the underlying operating system. Check your operating system documentation for valid file name format.
  • WI065: Unable to access code page information.
    You have specified a translation table to use for DSNTIAUL EBCDIC-to-ASCII conversion, or non-DSNTIAUL ASCII-to-ASCII conversion. However, Import was unable to load the translation from the system table SYSIBM.SYSSTRINGS.
  • WI066: Number of records to recalculate must be an integer from 0 to 4,294,967,296.
    The number you specified is not in range.
  • WI067: Commit interval must be an integer from 0 to 4,294,967,296.
    The number you specified is not in range.
  • WI069: Quotes missing around character value string.
    You have specified that character values are enclosed in quotes, but the specified character value is not quoted.
  • WI071: Float value in field number, fieldname of record number is larger than IBM370's limit.
    The float value is not supported by IBM370.
  • WI072: Float value in field number, fieldname of record number is smaller than IBM370's limit.
    The float value is not supported by IBM370.
  • WI073: Unable to open View Batch window, probably out of memory.
    Check system resources. Close down other SQLWizard windows, or other applications to free resources.
  • WI074: Unable to open View Data window, probably out of memory.
    Check system resources. Close down other SQLWizard windows, or other applications to free resources.
  • WI077: Internal error reading batch file.
    An error occurred when trying to read the batch file. It is most likely a memory allocation error.
  • WI078: Invalid value value for PAGE_SIZE command in group number, groupname.
    The syntax of this command is:
  • WI079: Invalid value string for FORMAT command in group number, groupname.
    Valid formats are FREASC, FIXASC, and DSNTIAUL.
  • WI080: Can't import into a non-XDB Server location using Engine Direct Write
    Engine Direct Write mode is only supported against XDB Server locations.
  • WI082: Data file filename does not contain any data.
    The file appears to be empty.
  • WI083: Invalid value value for ASCII_CODEPAGE command in group number, groupname.
    This must be a positive integer or 0.
  • WI084: Invalid value value for EBCDIC_CODEPAGE command in group number, groupname.
    This must be a positive integer or 0.
  • WI085: Invalid value value for FLD_DELIMITER command in group number, groupname.
    The syntax of the FLD_DELIMITER command is:
  • WI086: Invalid value value for REC_DELIMITER command in group number, groupname.
    The syntax of the REC_DELIMITER command is:
  • WI087: Invalid value value for HEADING command in group number, groupname.
    The correct syntax of this command is:
  • WI088: Invalid value value in position number for EBCDIC_TO_ASCII command in group number, groupname.
    The syntax of this command is:
  • WI089: Invalid value value in position number for SRC_LENS command in group number, groupname.
    The syntax of this command is:
  • WI090: Invalid value value in position number for OFFSETS command in group number, groupname.
    The syntax of this command is:
  • WI091: Invalid value value for SPACES command in group number, groupname.
    The syntax of this command is:
  • WI092: Invalid value value for QUOTES command in group number, groupname.
    The syntax of this command is:
  • WI093: Invalid value value for REPLACE command in group number, groupname.
    The syntax of this command is:
  • WI094: Invalid value value for INSERT_MODE command in group number, groupname.
    The syntax of this command is:
  • WI095: Invalid value value in position number for NULL_PERM command in group number, groupname.
    The syntax of this command is:
  • WI096: Invalid value value in position number for USE_PIC command in group number, groupname.
    The syntax of this command is:
  • WI097: Invalid value value in position number for TYPES command in group number, groupname.
    The syntax of this command is:
  • WI098: Invalid value value in position n for FIELDS command in group number, groupname.
    The syntax of this command is:
  • WI099: Invalid value value for TABLE command in group number, groupname.
    The syntax of this command is:
Parent topic: WI - SQL Wizard Import Error Messages


WI100 - WI149

Lists the SQL Wizard Export error messages from WI100 through WI149.
Restriction: This topic applies to Windows environments only.
  • WI100: Invalid value value for FILENAME command in group number, groupname.
    The syntax of this command is:
  • WI101: Invalid value value for ON_ERROR command in group number, groupname.
    The syntax of this command is:
  • WI102: Invalid value value for COMMIT_INTERVAL command in group number, groupname.
    The syntax of this command is:
  • WI103: The number of values for the FIELDS command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI104: The number of values for the TYPES command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI105: The number of values for the USE_PIC command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI106: The number of values for the NULL_PERM command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI107: The number of values for the OFFSETS command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI108: The number of values for the SRC_LENS command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI109: The number of values for the EBCDIC_TO_ASCII command in group number, groupname does not match the number of fields found in a previous command.
    The number of items in all of the field-list commands must be consistent.
  • WI110: Batch file filename is empty.
    The file does not contain any batch import specifications.
  • WI111: Unknown batch command command in group number, groupname.
    There are invalid commands in the batch file. See your SQLWizard User's Guide for valid batch commands.
  • WI112: Short float value in field number, fieldname of record number is larger than IBM370's limit.
    Float value not supported for IBM370.
  • WI113: Short float value in field number, fieldname of record number is smaller than IBM370's limit.
    Float value not supported for IBM370.
  • WI115: Error opening batch file for writing.
    There is not enough memory to create the internal structure required to write an Import specification file (an IMP file). Close any unnecessary applications, then retry the operation. If this does not resolve the problem, clear memory by restarting SQLWizard or by rebooting.
  • WI116: Error writing to batch file.
    An error has occurred while writing an Import specification file (an IMP file). Check that nothing is preventing a file from being written. For example, check that the drive is operational and that it has sufficient space. Also check that the file is not write protected.
  • WI117: Invalid value value for SRC_ASCII_CODEPAGE command in group Tnumber, Tname.
    The value assigned to a SRC_ASCII_CODEPAGE statement in your Import specification file (IMP file) is incorrect. It must be a positive integer. The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Allowed values are listed in the SQLWizard User's Guide.
  • WI118: Invalid value value for DST_ASCII_CODEPAGE command in group Tnumber, Tname.
    The value assigned to a DST_ASCII_CODEPAGE statement in your Import specification file (IMP file) is incorrect. It must be a positive integer. The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Allowed values are listed in the SQLWizard User's Guide.
  • WI119: Invalid batch file name filename.
    An invalid file name has been given to an Import specification file (IMP file). If you are saving an IMP file, check that you have typed a name allowed by your operating system. If you are running a batch import from the command line, verify that a valid IMP filename was entered on the command line. See your SQLWizard User's Guide for command line syntax.
  • WI121: Can't import data file filename into table tablename because data file has number columns but table has number columns.
    The source file and the target table in your Import operation do not have the same number of fields. If you are running a batch import, verify that the TABLE statement in the IMP file is set to the correct target table. Also verify that the FIELDS, TYPES, NULL_PERM, SRC_LENS, OFFSETS, USE_PIC and EBCDIC_TO_ASCII statements in your IMP file reflect the actual number of columns in your source and destination. See your SQLWizard User's Guide for a complete description of the IMP file and its contents.
  • WI122: Batch specification in group Tnumber, Tname in file filename is not sufficient to create new table tablename.
    A TYPES and/or FIELDS statement for this transaction was not found in the Import specification file (IMP file). The error is located in the transaction represented by Tnumber (e.g., Tnumber 1 is the first transaction in the IMP file) and Tname (Tname is the bracketed string at the top of each transaction). Edit your IMP file and enter the missing statement(s). See your SQLWizard User's Guide for a complete description of the IMP file and its contents.
  • WI123: Table tablename contains number columns but batch file specifies number columns.
    The target table specified in the Import specification file (IMP file) doesn't contain the same number of fields as the source file. Verify that the TABLE statement in the IMP file is set to the correct target table. Also verify that the FIELDS, TYPES, NULL_PERM, SRC_LENS, OFFSETS, USE_PIC and EBCDIC_TO_ASCII statements in your IMP file reflect the actual number of columns in your source and destination. See your SQLWizard User's Guide for a complete description of the IMP file and its contents.
  • WI124: Invalid value Value for varchar length. Length must be no greater than page size Size.
    The import process has been terminated because the DSNTIAUL file you are importing contains a varchar value that exceeds the current page size.
  • WI125: Invalid record delimiter - escape character character is not allowed.
    The escape character specified on the SQL tab of Options cannot be used as a record delimiter.
  • WI126: Invalid field delimiter – escape character character is not allowed.
    The escape character specified on the SQL tab of the Options utility cannot be used as a field delimiter.
Parent topic: WI - SQL Wizard Import Error Messages


WSQL - SQL Wizard Interactive SQL Error Messages

Restriction: This topic applies to Windows environments only.
  • WSQL001: XDB Engine is not loaded.
    The system was unable to load the SQL Engine. Make certain that you have correctly installed and configured SQL RDBMS (or the equivalent) or that you have installed the correct network redirector.
  • WSQL002: Error allocating memory.
    An attempt was made to allocate a block of memory, but that attempt failed. Try removing other programs from memory, and then repeat the task. Try saving your work and exiting from SQLWizard, and then reload it. If the operating system is using a temporary PAGEFILE, make sure there is at least 2MB of free disk space. If attempts to increase available resources fail, contact Micro Focus Technical Support.
  • WSQL003: Error opening file filename.
    An attempt was made to open the file named, but it failed. This usually occurs if the file could not be found. Check that the file exists, and that you have privileges to access it. Make sure the file is not in use by another application. Check to be sure there is enough disk space available, and that the target directory is a valid path.
  • WSQL004: Error creating name window.
    The system was unable to create the window, probably because resources (such as memory) are low. Close down some windows (or other applications) and try again. See WSQL002.
  • WSQL005: Error creating name dialog.
    The system was unable to create the dialog, probably because resources (such as memory) are low. Close down some windows (or other applications) and try again. See WSQL002.
  • WSQL006: Error creating name text editor.
    The system was unable to create the window, or open the specified application. Close down some windows (or other applications) and try again.
  • WSQL007: Error adding line to text editor.
    The system could not add additional text to the current edit control. System resources may be low. Try freeing resources by closing unnecessary programs.
  • WSQL008: Prohibit Cartesian products.
    The system has been set to prohibit Cartesian products. The query you are trying to run has been evaluated as a Cartesian product, and cannot be executed unless you turn off the Prohibit Cartesian Products option through the Query|Current Query Options dialog.
  • WSQL009: Query result cannot be edited.
    The current query result has been evaluated as a non-editable result, and therefore the system cannot switch to edit mode. Reasons for a query to be evaluated as non-editable are that it is/contains a: a) Join b) Union c) GROUP BY clause d) HAVING clause e) Expression or it accesses a read-only view.
  • WSQL010: Error executing menu.
    An error occurred when trying to process the last menu command.
  • WSQL011: Printing failed.
    An error occurred when attempting to print. Check the print manager for additional information.
  • WSQL012: Cannot list windows.
    The system was unable to list the currently open windows.
  • WSQL013: Too many windows.
    The system cannot open another window. Try closing down some of the currently open child windows.
  • WSQL014: Window does not have METRICS data.
    Unable to process window commands.
  • WSQL015: Incomplete line in string.
    Incomplete line in string.
  • WSQL016: No default value in string.
    No default value in string.
  • WSQL017: Prompted number number is out of range, should be 1-100.
    An SQL statement references a variable &n where n is not between 1 and 100. Modify the SQL statement to change &n so that n is within the acceptable range, or change &n to a host variable in the form :hv.
  • WSQL018: Error adding item to prompted list.
    An error occurred attempting to add an item to the prompted query design list. Contact Micro Focus Technical Support.
  • WSQL019: Cannot find the prompted number number.
    An error occurred trying to specify or rebuild a prompted query design. The table SYSXDB.SYSPROMPTQUERY may be damaged or has been incorrectly edited.
  • WSQL020: Invalid characters in string.
    There are illegal characters in the string shown. Correct and try again.
  • WSQL021: Cannot find query.
    The system was unable to find the query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. You may have entered the name incorrectly. The query may have been deleted from the query catalog, or there may be an error reading the catalog tables.
  • WSQL022: Argument is NULL.
    A required argument is NULL. Correct and try again.
  • WSQL023: Cannot open temporary file.
    The system was unable to open a temporary file. Check whether you have privileges to read and write on the temporary path, and that there is enough disk space to write the file.
  • WSQL024: Cannot create temporary file.
    The system was unable to write a temporary file. Check whether you have privileges to read and write on the temporary path, and that there is enough disk space to write the file.
  • WSQL025: You must have a valid connection to use all of SQLWizard's options.
    If you cannot connect to the database engine, you will not be able to access SQLWizard. This error sometimes occurs when you have not connected properly to a remote database server.
  • WSQL026: Invalid entry in field fieldname.
    An attempt was made to enter invalid data in the named field. Modify the data to match the data type.
  • WSQL027: Window does not have METRICS data.
    Unable to process window commands.
  • WSQL028: Cannot open query.
    The system was unable to open a query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. The query may have been partially deleted from the query catalog, or there may be an error reading the catalog tables.
  • WSQL029: Error running batch SQL.
    The system encountered an error in trying to process a batch SQL script.
  • WSQL030: No such Query.
    The system was unable to find the query in SYSXDB.SYSQUERY or SYSXDB.SYSPROMPTQUERY. You may have entered the name incorrectly. The query may have been deleted from the query catalog, or there may be an error reading the catalog tables.
  • WSQL031: No column needs order by.
    There are no unsorted columns in the query. Use the Query|Sort option if you want to remove some columns from the query. You cannot sort by a column that is not selected if you are in DB2 mode (this is a restriction of DB2).
  • WSQL032: Cannot create toolbar.
    The system failed in an attempt to create the toolbar. Check whether resources are low.
  • WSQL033: Error saving file filename.
    An error occurred when trying to save the named file. Make certain the path is valid, the file name is valid, that there is enough space for the file, or that the file does not already exist and is locked by another application.
  • WSQL034: Error seeking file.
    A file could not be found. A seek error occurred when trying to locate it. Make certain the file specification is correct, and that the file exists.
  • WSQL035: Error seeking query.
    A query could not be found. You can query the SYSXDB.SYSQUERY table to see if the query exists in the location that you are querying. You may need to make the location where the query exists the current location.
  • WSQL036: Cannot find table name.
    A table by the specified name could not be found.
  • WSQL037: Cannot paste table name.
    The system was unable to paste a table name into the current context.
  • WSQL038: Cannot open init file.
    The system was unable to open one or more initialization files. Run Options to check XDB.INI. Check the command line of XWIZ40N.EXE for the INI file in use.
  • WSQL039: Cannot paste query.
    An attempt was made to paste an SQL statement into a Query Design window, or to paste a Query Design into an SQL Edit window. Try using the Open button to open the query. Change to SQL view if necessary, and copy the query, then paste to the target SQL Edit window.
  • WSQL040: The editor is read-only.
    You cannot edit or paste into the current edit field.
  • WSQL041: Cannot open a synonym under a different location or AuthID.
    Synonyms can only be accessed from the location in which they are created. Make the synonym location your current location before attempting to open the synonym.
  • WSQL042: Error in querying SYSACFUSERS.
    The system encountered an error when attempting to retrieve information on users from the system catalog. This error occurs if you have not been granted privileges against the system catalog tables. You will be allowed to continue if you receive this error, but you will be connected as a regular user, not a super user.
  • WSQL043: Cannot access SYSIBM tables using AuthID authid.
    This error occurs if you attempt to start SQLWizard when you have not been granted privileges for the system catalog tables.
  • WSQL044: Cannot access SYSXDB tables using AuthID authid.
    This error normally occurs if the current user does not have select privileges on the SYSXDB catalog tables, or on the equivalent views. Check the SYSXDB setting in the Options SQL page to see what AuthID the system is trying to use for SYSXDB catalog views, and contact your administrator to see if you have select privileges on the views created with this AuthID. If you do not, have the administrator grant you the privileges you need to access the catalog tables. If the SYSXDB.SYSQUERY table does not exist, you may see this error. You will still be allowed to access SQLWizard, but you may not be able to list or save queries in the catalog tables. You should still be able to save and run queries in SQL script files.
  • WSQL045: Name name is invalid.
    The name shown is not a valid name based on the current SQL mode, or the system requirements. In general, names must begin with a letter, can contain letters and digits, and the characters # $ % & _ { } in XDB mode or @ # $ _ in DB2 mode.
  • WSQL046: Cannot save query. Please check if disk is full.
    Something is preventing SQLWizard from saving this query.
  • WSQL047: The query has been corrupted.
    SQLWizard cannot open the selected query because it contains corrupt data. This might happen if the SYSPROMPTQUERY table was edited directly.
  • WSQL049: SELECT error. May not have privileges.
    SQLWizard cannot complete this task because you do not have privileges to the specified object.
  • WSQL050: Cannot edit tables with renamed columns.
    You are attempting to edit a table that contains a renamed column. This is not allowed. This error would occur, for example, if you attempted to edit the result of the following query (which changes the name of the e_no column to xemp):
  • WSQL051: Batch error in command number number.
    SQLWizard has encountered an error while processing a batch SQL script.
  • WSQL052: End of statement delimiter not found.
    SQLWizard could not find an end of statement delimiter.
  • WSQL053: Filters yield no results. Filters are reset.
    The filter value entered for the immediate sub-item (database, or AuthID) beneath the location level returns an empty result set. The Catalog Browser display will be refreshed using the latest valid set of filter values stored in XDB.INI.
  • WSQL054: Cannot display result set containing a LOB field.
    The result set contains a Large Object (LOB), which is not displayable.
  • WSQL055: Invalid value, terminator_character, specified for TERMINATOR.
    The SQL terminator character specified in a --#SET TERMINATOR statement is invalid. The following characters are not allowed to be a SQL terminator: blank, comma, double quote, left parenthesis, right parenthesis, single quote, and underscore.
Parent topic: SQL Option for DB2 Error Messages


X - Engine Error Messages

Restriction: This topic applies to Windows environments only.

  • X000 - X049
    Lists the Engine error messages from X000 through X049.
  • X050 - X099
    Lists the Engine error messages from X050 through X099.
  • X100 - X149
    Lists the Engine error messages from X100 through X149.
  • X150 - X199
    Lists the Engine error messages from X150 through X199.
  • X200 - X249
    Lists the Engine error messages from X200 through X249.
  • X250 - X299
    Lists the Engine error messages from X250 through X299.
  • X300 - X349
    Lists the Engine error messages from X300 through X349.
  • X350 - X399
    Lists the Engine error messages from X350 through X399.
  • X400 - X449
    Lists the Engine error messages from X400 through X449.
Parent topic: SQL Option for DB2 Error Messages


X000 - X049

Lists the Engine error messages from X000 through X049.
Restriction: This topic applies to Windows environments only.
  • X001: Cannot perform operation (errornum) on file filename.
    An attempt to close/open/read/write/seek on the file specified failed. File mode may conflict. Device may be full or damaged, or file may not exist. Also, make sure that your temporary path is set to an existing path.
  • X002: Empty query string.
    An attempt was made to execute a command that was discovered to be an empty string. You may have accidentally pressed an execute option before issuing a command. You may have used an empty (NULL) string as the input for a PREPARE command, or for an xcommand() or xprepare() function.
  • X003: INI Error errmsg
    The error message returned can be any of the messages listed under Possible Error Messages below. Each possible error message is followed by a typical XDBNET.INI file error that could have caused the error message. The following notation definitions apply for each possible error message:
  • X004: Number value overflow.
    An attempt was made to place a value that is too large or too small into a numeric field (float, int, smallint, etc.). See XDB Server Specifications in the SQL Reference for maximum and minimum values permitted in numeric data types. Check picture specifications.
  • X005: Date value error.
    An attempt was made to place an illegal date in a date field or attempt to perform date arithmetic on an invalid date. XDB Server performs leap year checking, and verifies that month and day are correct. Check picture specifications.
  • X006: String constant too long.
    String constants selected in a query may be up to 4056 characters long. Varchar and long varchar columns can be longer, so you could store a longer value in a table and retrieve it.
  • X007: Incomplete string. Check for missing quotes.
    A quote without a matching quote was found in a command sent to the SQL Engine. You may use either single or double quotes around character strings. If a single quote is to appear within a string, surround the string with double quotes. For example:
  • X008: Version number incompatibility in user exit file.
    The structure being returned by the user exit procedure procedure is incompatible with this version. Contact your system administrator.
  • X009: Illegal field name name.
    A reference was made to a field that does not exist in the table specified by a command. If using a precompiler to catch an error at precompile time, then add VALIDATE directive in XDBCOB.DIR file. Make sure that all fields are defined in the declaration.
  • X010: No more RAM memory available.
    Insufficient memory (RAM) was available to execute a command sent to the SQL Engine. Try running the application from outside the main menu or application menu to see if that gives you enough memory to continue.
  • X011: Type mismatch within expression.
    A data type conflict occurred within an expression. For example, you may have attempted to perform date arithmetic with a character string.
  • X012: Type mismatch while doing comparison.
    An attempt was made to compare two incompatible data types. Numeric types may be compared to other numeric types (including, for example, money and numeric results of date arithmetic or string functions); dates can only be compared to dates, character strings to character strings, times to times.
  • X013: Order by clause invalid on singleton select statement.
    An embedded SQL singleton select might not contain an older BY clause. The statement should be modified to use the OPEN CURSOR construct.
  • X014: Set location can only be used for local locations.
    The system was unable to locate a table or view in the relational directory (.DDT file), or the table/view is not found in the referenced query control block. In order to add a table or view to the relational directory you must create it using the CREATE command. You can copy tables from one location to another using the COPY command. To include a table or view in a query control block, you must include it in the FROM clause of a query.
  • X015: Attempt to close an unopened location directory.
    An attempt was made to close a location directory that was not open at the time. Check for subroutines that close the location, or logout of subprograms.
  • X016: Undefined query identifier or location not open.
    An attempt was made to access a query control block that does not exist, or to run a command against an unopened location. This error condition may occur if you prematurely close a query or (if using an application programming interface) if you forget to open the location. Also a subroutine may have logged out, automatically closing the location.
  • X017: Illegal record position.
    An attempt was made to access a record at a location outside the result of the query. Typically this occurs when using the application programming interface function xdirect() to move the cursor to a record that does not exist in the current table. To find the position of a record, use the xgetpos() function. It is possible that the record has been modified since the position was saved and re-execution of the query did not include the record in the new result set.
  • X018: Duplicate value in unique index name.
    An attempt was made to insert a duplicate value in a field on which a unique index or primary key exists. Possible fixes: Check for a rollback file (.RB extension) and delete it; Delete all indices and rebuild them; Check if the data is wrapped; Delete all files from temporary storage before transferring new data to the storage area.
  • X019: Query too long.
    The system was unable to allocate enough space to process the query. XDB Server uses dynamic allocation for this task, so the length of query permitted depends on the amount of memory available. Reduce the length of the query, or remove unnecessary programs from memory and try again. See X010 and X050.
  • X020: Syntax error. Last symbol read was string.
    The SQL Engine was unable to parse a command it was sent. When this error occurs, the system tries to display the last token it read. Check the command syntax in the SQL Reference. Make sure that all products are using the same character set (ASCII, EBCDIC, etc.). If using the COBOL, look in the errmc element of the SQLCA structure for the error tokens. SQLCA errd[4] contains the column position of the token. In CAPI, call the function xgeterr() to get the error tokens.
  • X021: Pathname too long.
    XDB Server accepts paths of up to 48 characters.
  • X022: Too many queries open at same time.
    There is no room to open additional query control blocks. A user may open up to 50 queries at one time. The actual number of queries open at one time depends on the complexity of the queries. Try rewriting your program so that it is not necessary to hold so many queries open at the same time. In server versions, use the XDB Server Configuration utility to increase the number of available query control blanks.
  • X023: Length of value exceeds length of destination.
    An attempt was made to place a value in a field too small to accommodate it.
  • X024: Index Name has been damaged.
    The index specified cannot be used by the system. You must drop the index and rebuild it before continuing. NOTE: If you compact a table with deleted records or use the AND INDEX clause, all indices are automatically rebuilt for you.
  • X025: Incomplete comment.
    Comments sent to the SQL Engine should begin with the characters /* and end with the characters */. The system found one comment marker, but not the other.
  • X026: Exceeds max number of tables/views permitted in query.
    You may access up to 15 tables or views per FROM clause; the limit depends on the complexity of the query, as well as the number of expressions and multi-table views involved. In addition, the number of queries already open may impact on the number of tables allowed in a query.
  • X027: Maximum of number connected client nodes has been exceeded.
    The XDB Server cannot process your connection request because the maximum number of licensed users is already attached to the server.
  • X028: Cannot find table/view/synonym name.
    The table, view, or synonym specified does not have a readable entry in the database directory. You may have entered an incorrect table name, or be in the incorrect database. The database directory (.DD? file) may have been damaged or overwritten. You cannot simply copy a .TAB file to a database directory and then access it through XDB Server. You must use the CREATE or COPY commands to create a table or move a table between databases.
  • X029: Invalid hex constant.
    The XDB Server cannot execute the current statement because it contains an invalid hex constant. For example, a closing quote may be missing, or the hex value may contain an invalid character.
  • X030: Invalid field number.
    A low level CAPI function call (e.g. Xdbxgetrec or Xdbxputrec) to access a field failed; the specified field number does not exist in the query.
  • X031: Cannot truncate log file.
    Unable to truncate the backward log file; cannot COMMIT or ROLLBACK. Check access privileges on the drive containing the database. Run operating system program CHKDSK on the database drive. Use Options to turn the Backward Log OFF.
  • X032: Lock Conflict.
    Two or more users are accessing the same object.
  • X033: Column name is ambiguous.
    If the column specified is ambiguous, then you must reference it by a two-part column name (i.e., table/view.column).
  • X034: Illegal correlation name name.
    A query references a correlation name not specified in the FROM clause.
  • X035: Length of input host variable number number is invalid.
    The length of the specified host variable is too long or too short.
  • X036: Default specification for field name is invalid.
    An unexpected internal error occurred when accessing the defined default value for column name.
  • X037: Invalid timeout specification.
    Timeout specification should be an integer greater than 0 and less than 32,767.
  • X038: Cannot acquire read/write access on specified path.
    Unable to read or write any files on a path the system has tried to access as result of a command you issued. If using a network file server, check the current user's privileges. If using a multiuser system, make sure another user is not accessing the file.
  • X039: Abort code.
    The system aborted the current operation upon receipt of an abort code. When you press Esc in most environments, programs send an abort code to the SQL Engine, instructing it to terminate the transaction it is currently processing for you. A partial result may be displayed in some modules. Incomplete transactions involving updates, inserts or deletes are rolled back if the backward log is turned on. You can specify the abort characters through Options.
  • X040: Log system couldn't operation.
    An operation in the log system has failed.
  • X041: Left side of expression incompatible with right side.
    The system is unable to compare the left hand side of an expression to the right hand side of the expression. This is generally due to incompatible data types (e.g. comparing a time field to a date field).
  • X042: Field type not compatible with nested query results.
    The field type of a nested query result is not compatible with the field type it is being compared to.
  • X043: Aggregate function on invalid type.
    An attempt was made to find a numeric aggregate function result for a non-numeric field (e.g. AVG of a character field.)
  • X044: Invalid data type indicator.
    The SQL Engine received an invalid data type indicator from the calling program. This problem is generally due to a programming error in user programs that use one of the language interfaces. Refer to interface documentation for valid data type indicators.
  • X045: Invalid element in structure structure in function function.
    The values structure in CAPI function Xdbxputrec() contains invalid information. Length may be out of range, or type may be invalid.
  • X046: Illegal number of fields specified for compound index.
    An attempt was made to create an index on more than 64 columns.
  • X047: Index name too long.
    An index name is currently limited to 18 characters in length, except when using mainframe syntax.
  • X048: Index name already exists.
    An attempt was made to create an index with the same name as an existing index in the current database. You can view index names in the current database using the query:
  • X049: Duplicate name name in create index list.
    A field name can appear only once in a CREATE INDEX statement. When creating foreign keys, a field name can appear only once in the indexed field list of a referenced table, and only once in the indexed field list of the referencing table.
  • X050: No more RAM available to REDIRECTOR.
    The network redirector (network communications) was unable to allocate the necessary memory required (either for packet transmission or reception).
Parent topic: X - Engine Error Messages


X050 - X099

Lists the Engine error messages from X050 through X099.
Restriction: This topic applies to Windows environments only.
  • X051: Duplicate key value when creating unique index indexname.
    Unable to create unique index because a value appears more than once in the column(s).
  • X052: Cannot update field to incompatible type.
    An attempt was made to update a field using an incompatible value. Check the field types of the table you are updating.
  • X053: String length is larger than field length.
    An attempt was made to insert a character string into a field too short to hold it. Check to see if you are using DB2 compatibility.
  • X054: Unequal number of fields and values.
    When inserting a record, an attempt was made to insert more values than the table has fields. If you supply too few values, the system automatically places NULL values in the other fields.
  • X055: Duplicate names name in insert/alter/create list.
    A field name appears more than once in an INSERT, ALTER, or CREATE command.
  • X056: Table/View name already exists.
    All tables and views in a database must have unique names. To obtain a list of the tables or views in a database, you can perform the query:
  • X057: Specified more fields or values than the table has.
    The number of values listed in an INSERT command exceeds the number of fields in the table named.
  • X058: Field name type incompatible with type type.
    Unable to perform a command because the type of the field named is incompatible with the type displayed (e.g. a time field is incompatible with a date field for comparison operations).
  • X059: Inserting character constant larger than field length specified.
    A character string in an INSERT command values list is longer than the target character field. Value is truncated.
  • X060: value is outside allowable field length boundary.
    See the SQL Reference for description of data type ranges.
  • X061: number is greater than maximum allowable number of fields.
    Tables are limited to 750 fields.
  • X062: Value value is too large to insert into field name.
    Unable to insert the value into the field specified, because it is larger or longer than maximum value permitted.
  • X063: Index name not found.
    Reference was made to an index not found in the current database. For a list of the currently active indices in the current database, execute the query:
  • X064: Not a proper command or command not implemented.
    An attempt was made to execute a command that is not a valid XDB Server or SQL command, or to execute a command that is not yet implemented.
  • X065: Illegal field name name in order specification.
    A field or column in an ORDER BY clause was not selected in the SELECT clause of the query, or does not exist in the table.
  • X066: Illegal number number in order/group specification.
    There is no matching column number for a column number listed in the ORDER BY or GROUP BY clause of the query.
  • X067: Aggregates not allowed in WHERE clause of query.
    XDB Server does not permit an aggregate function in the WHERE clause of a query. Aggregate functions should appear in a HAVING clause if used as a selection criterion.
  • X068: Selecting an expression with a GROUP BY clause.
    XDB Server does not permit use of expressions (other than aggregate functions) in a query having a GROUP BY clause unless you include the expression in the GROUP BY clause using its column number.
  • X069: Too many set clauses in update command.
    There are more SET clauses in the UPDATE command than there are fields in the table being updated.
  • X070: Ordering by field name that is not selected.
    In DB2 mode, the ORDER BY clause must specify one of the fields in the SELECT clause.
  • X071: Selecting more than one item in a nested query.
    The SELECT clause of a subquery can consist of only one column. If you want to select more than one field, try concatenating the fields using the XCONCAT function.
  • X072: Cannot nest aggregate functions.
    Aggregate functions cannot be nested one inside the other. For example, you cannot select:
  • X073: Fields selected must appear in GROUP BY clause or inside an aggregate function.
    If a query selects an aggregate function, any field appearing outside the aggregate function in the SELECT clause must also appear in the GROUP BY clause of the query. This is a common cause of confusion; although users may think they do not want to group a result by a particular column, they often find that adding the column name to the end of the GROUP BY clause yields the desired result.
  • X074: GROUP BY clause invalid on current query.
    A GROUP BY clause can only be used if the SELECT clause of the query includes one or more column names, or one or more aggregate functions (such as COUNT, and AVG.)
  • X075: Cannot mix fields with aggregates without GROUP BY.
    If a query selects an aggregate function, any field appearing outside the aggregate function in the SELECT clause must also appear in a GROUP BY clause.
  • X076: Luname servername does not exist in tablename SYSLUNAMES table.
    You are inbound/outbound mapping to or from a server name that does not exist in SYSLUNAMES. Insert a record for that server name in the SYSLUNAMES table or insert a dummy generic record with blanks.
  • X077: Cannot include join in table expansion.
    PREVIOUS clause cannot be used on a join.
  • X078: Illegal level value for table expansion.
    LEVEL clause specifies a non-positive or non-integer level, or a level beyond the maximum recursive relationship level.
  • X079: Insert/Delete/Update function not allowed on sorted query.
    You cannot perform a positioned update/insert/delete on a query that requires sorting. Queries that may require sorting are those involving ORDER BY, GROUP BY, DISTINCT, and UNION.
  • X080: Only one DISTINCT clause allowed per query.
    XDB Server only allows one DISTINCT clause per query. For example, you cannot:
  • X081: Exceeds maximum number of UNIONed queries.
    A maximum of 32 subselects may be connected by the UNION operator (i.e. UNION should appear no more than 31 times in a command).
  • X082: Each query in a UNION must have the same number of projected fields.
    The number and type of columns selected in subselects connected with the UNION operator must match exactly.
  • X083: Data types in column name do not match.
    When performing a UNION, the data types of each column in one subselect must be type compatible with the corresponding column in all UNIONed subselects.
  • X084: ORDER BY items must be constants for union of queries.
    When the UNION operator and the ORDER BY clause appear in the same query, the ORDER BY criteria must use column numbers instead of column names.
  • X085: ORDER BY must follow all queries when performing a union.
    The ORDER BY clause should be the last clause in any query containing a UNION operator.
  • X086: NULL not allowed in field name.
    An illegal attempt was made to place a NULL in the field named. The field is specified as NOT NULL. You can obtain information on NULL permission from the SYSCOLUMNS table.
  • X087: Table/View name exceeds maximum length of number.
    Table, view and synonym names are limited to the number of characters shown. Some compatibility modes allow longer table names than others.
  • X088: Field name length exceeds maximum length of number characters.
    Table names are limited to the number of characters shown. Some compatibility modes allow longer field names than others.
  • X089: Cannot open location on path. Check location path setting.
    The system is unable to find or open the location-name.DDT or location-name.DDF files on the path specified. These files contain essential information on location table and field specifications. Check whether there is a location in the path specified. Check whether there is more than one set of .DDT or .DDF files in your location directory. Check to see if the location name matches the location name in the SYSXDB.SYSLOCALS table. Verify whether the path is accessible by the program accessing the location. For example, in multi-user, use the drive specifier.
  • X090: Too many users registered.
    The number of users registered is equal to the maximum number of users permitted to register at one time.
  • X091: User has no privilege privilege on objectname.
    The current user has not been granted the privilege to perform the operation attempted on the table, view or database shown. For a listing of privileges available to a user, query the SYSTABAUTH and SYSDBAUTH tables.
  • X092: User account has been disabled.
    The user name has been deactivated. See your database administrator, who can enable the user account.
  • X093: Unknown user name.
    The user name entered is not found in the system, because it has not been registered on the system. See your database administrator. Query the SYSXDB.SYSACFUSERS table in the system location for a list of valid user names.
  • X094: User userid cannot GRANT/REVOKE on table/view/database name.
    User has no authority to grant or revoke privileges on the database, table or view named. For a list of privileges available to a user, query the SYSTABAUTH and SYSDBAUTH tables.
  • X095: Invalid receipt. (Should register first.)
    User did not obtain a valid process ID before entering a module. Exit to the operating system and try reentering the program. In extreme cases you may need to unload the SQL Engine, or in multi-user environments, kill a user session.
  • X096: Illegal password.
    Password does not match password saved for the user name entered. Repeated attempts to log on with an incorrect password will cause this program to abort. If you have forgotten your password, see your database administrator.
  • X097: Illegal attempt to open more than one location.
    XDB Server permits a user to access only one location at a time. This error condition occurs when a programmer attempts to call the C API Xdbxopen() function before closing the current location.
  • X098: Cannot grant a privilege to yourself.
    A user is not permitted to grant a privilege to him/herself. The privilege must be granted by another user possessing sufficient authority to do so.
  • X099: User already exists.
    A user with the same user name is already entered in the SYSXDB.SYSACFUSERS table. User names must be unique.
Parent topic: X - Engine Error Messages


X100 - X149

Lists the Engine error messages from X100 through X149.
Restriction: This topic applies to Windows environments only.
  • X100: Memory Resident Engine not loaded!
    XDB client-side software could not communicate with the XDB Server. Check to make sure that the XDB Server is up. If it is up and listening on the appropriate communications protocol, contact Micro Focus Technical Support.
  • X101: Illegal function code passed to engine.
    Programmer attempted to call the SQL Engine with an illegal function code. Refer to your Application Programming Interface documentation for valid function codes. Another possible cause for this error could be that you are inadvertently trying to access the wrong engine. This can occur if you have been working with a single-user engine on your own computer and then switch to using a multi-user XDB Server.
  • X102: Cannot find view name.
    Unable to find the view named in the SYSVIEWS table, or in the system directory files.
  • X103: Must select aggregates if using HAVING clause with no GROUP BY.
    A HAVING clause can only appear in a query that selects only aggregate functions, or that has a GROUP BY clause.
  • X104: A password is required for connection with LU servername.
    You are trying to connect to a server name that doesn't trust you. You need a password to be connected.
  • X105: Operation not allowed on view name.
    XDB Server cannot perform the operation attempted on the view named. For example, multi-table views are not currently updateable.
  • X106: No translation row in tablename SYSUSERNAMES for LU servername.
    You are trying to do inbound/outbound mapping without specifying a translation row to the AuthID in SYSUSERNAMES.
  • X107: Current AuthID can't be used to reference remote object.
    The XDB Server cannot execute the requested operation because the specified AuthID is not valid for the remote location.
  • X108: Field list must be provided when expressions are selected.
    The SELECT clause of commands that define views can contain expressions only if the resulting columns are explicitly named. For example:
  • X110: Cannot operation logfile filename. Check logpath setting.
    An operation on the logfile named filename has failed. Check the log path in the SYSXDB.SYSLOCALS table to see if it is pointing to the correct directory. Also check to see that there is still disk space left for writing the file.
  • X111: Maximum number records per table in trial version.
    You are running the SQL Engine shipped with Learn, which limits the number of records in tables. The record limit includes deleted records that have not been removed using COMPACT. If you need to add more records to the table you must have a full version of XDB Server.
  • X112: Cannot perform operation (errno) on index index-name.
    An attempt to read/write/seek/open on the files that make up the index named failed. Check to see that the files index-name.IDX and index- name.PTR exist in the database directory. Check whether there is sufficient disk space to write to the index files. Check whether the file has been read or write protected. Increase the number of files in CONFIG.SYS to more than 100. See X001 for a description of operation errors.
  • X113: Cannot perform operation (errno) on table table-name.
    An attempt to read/write/seek on the files that make up the table named failed. Check to see that the file table-name.TAB exists in the database directory. Check whether there is sufficient disk space to write to the index files. Check whether the file has been read or write protected. See X001 for a description of operation errors. Compact the table (or drop it) and rebuild the indices.
  • X114: Cannot close current database. Please exit.
    Internal error code. Please contact Micro Focus Technical Support.
  • X115: Location already exists in the path specified.
    XDB Server permits one location per directory. XDB Server locations must be given unique names. This error condition occurs if you attempt to create a location in a directory that already contains a location, or if you attempt to create a location using a location name found in the SYSXDB.SYSLOCALS table.
  • X116: Time value error.
    An attempt was made to process a command containing an invalid time value. Check time picture specification.
  • X117: Maximum number of open locations exceeded.
    Maximum number of locations open exceeds the number specified through the XDB Server configuration.
  • X118: Location name table already exists.
    XDB Server permits one location per directory. XDB Server locations must be given unique names. This error condition occurs if you attempt to create a location in a directory that already contains a location, or if you attempt to create a location using a location name found in the SYSXDB.SYSLOCALS table.
  • X119: Location name exceeds maximum length of number.
    XDB Server location names are limited to the number of characters specified. Use a shorter location name.
  • X120: Cannot find location name in SYSXDB.SYSLOCALS table.
    An attempt was made to perform an operation on a location not found in the SYSXDB.SYSLOCALS table. Check the location path or location name specified in your command. When a location is created using the CREATE LOCATION command, an entry is inserted into the SYSXDB.SYSLOCALS table. If you are using a location that was not created with the CREATE LOCATION command, you may use the INSERT command to insert a record into the SYSXDB.SYSLOCALS table for the location.
  • X121: Operation requires system level privilege.
    An attempt was made to perform an operation that requires database administrator privileges. Check the authority required for the command you are trying to execute. If you do not have the proper authority, see your database administrator.
  • X122: Incorrect location files on path path.
    This error occurs if a specified location is not found. This might be caused by trying to access files that have been deleted, or by entering a path instead of a location. Otherwise, the problem is with SYSXDB.SYSLOCALS. You might want to check the path selections in Options.
  • X123: Cannot open system location on path path.
    The system was unable to open the system location on the system location path specified. To change the system location path, use the Configuration utility, described in the XDB Server Administration Guide.
  • X124: Illegal operation on system object.
    An illegal attempt was made to alter, insert, update or delete from a system object. XDB Server objects are for system use; they are automatically created and maintained by the system. Users may query the objects but, in general, cannot update or change them except through special commands (e.g. COMMENT ON). See XDB Server System Tables in the SQL Reference for descriptions of the system objects and how they are maintained.
  • X125: Must execute statement before fetch.
    When using dynamic SQL, before issuing a FETCH command you must PREPARE and EXECUTE the command.
  • X126: Cannot GROUP BY an aggregate function.
    Aggregate functions cannot appear in a GROUP BY clause.
  • X127: Pattern matching allowed on character fields only.
    LIKE searches, which use wild card pattern matching, can only be performed on character fields. You may perform range searches on other field types, including date and time. If you want to search a date field by day, month, or year, use XDAY, XMONTH or XYEAR, respectively.
  • X128: Target table cannot also be source table.
    You cannot insert records selected from a table into the same table. In addition, you cannot copy a table to itself.
  • X129: Attempt to insert invalid data into field name.
    An attempt was made to place incompatible data in the field named. Check the command, the data, and the field type, and make any corrections needed.
  • X130: Attempt to drop system location.
    The system location cannot be dropped using the DROP LOCATION command, since it contains the SYSXDB.SYSLOCALS table. If you must drop the system location, use operating system commands to delete all files and remove the location directory.
  • X131: Attempt to drop location in use.
    You cannot drop the current location. Before dropping a location, you must change to another location.
  • X132: Cannot find location name name in SYSXDB.SYSLOCALS table.
    The location named in the command does not have an active entry in the SYSXDB.SYSLOCALS table in the system location. Check the command and the SYSXDB.SYSLOCALS table for the correct location name.
  • X133: Cannot use reserve word word in table/index definition.
    XDB Server and SQL reserved words cannot be used as database object names (e.g. table and field names). For a list of reserved words, see the SQL Reference.
  • X134: error: DOMAIN ERROR.
    A mathematical function contains an argument outside the domain of the function. For example, you cannot use a column containing a negative number as the argument for XSQRT.
  • X135: error: RANGE ERROR.
    The result of a mathematical function is too large to be represented in the data type the system is trying to use.
  • X136: Functionality not available with LITE engine.
    The LITE Server cannot process this statement because it contains commands that are not supported by the LITE software.
  • X137: Cannot perform operation (errno) on location file name.
    The system was unable to perform the operation specified on the location file specified.
  • X138: Illegal operation on view.
    An attempt was made to perform an operation not permitted on a particular view, or not yet implemented in XDB Server. For example, you cannot currently update a multi-table view.
  • X139: Record size exceeds the maximum.
    XDB Server records are limited to 32,767 bytes, including record overhead. For odd length character fields, overhead is one byte; for even length character fields overhead is 2 bytes. For most other data types, overhead is 2 bytes per field in DOS.
  • X140: WITH CHECK OPTION clause not allowed on read only view.
    You cannot specify a CHECK OPTION for a view that is not updateable. For example, you cannot currently update views involving multi-table joins.
  • X141: Record does not satisfy view definition.
    An illegal attempt was made to update or insert an invalid record into a view created using the CHECK OPTION clause. You can see the CHECK OPTION for the view by querying the SYSCHECK table.
  • X142: Operation not allowed on read only view.
    An attempt was made to perform an operation not permitted on a particular view, or not yet implemented in XDB Server. For example, you cannot currently update a multi-table view.
  • X143: Table already has check condition.
    You may only create one CHECK CONDITION per table. However, this CHECK CONDITION may be very complex (to the detriment of performance). If you want to add conditions to the CHECK CONDITION, you must drop and recreate the CHECK CONDITION.
  • X144: Record does not satisfy table name check condition.
    An illegal attempt was made to update or insert an invalid record into a view created using the CHECK OPTION clause. You can see the CHECK OPTION for the view by querying the SYSCHECK table.
  • X145: Key key not found when analyzing referential constraint.
    One of the keys involved in a referential constraint is missing. You must create a key before you can refer to it in a FOREIGN KEY constraint.
  • X146: Violation of constraint between key key1 and key key2.
    An attempt to update, insert or delete a record violates a FOREIGN KEY constraint involving the keys listed. See the ALTER command description in the SQL Reference for a description of FOREIGN KEY.
  • X147: Cannot find key key.
    The command references a key that does not exist. You must create a key before you can refer to it in a FOREIGN KEY constraint.
  • X148: Primary key key already exists on this table.
    Only one PRIMARY KEY is permitted per table; other candidate keys may be defined as UNIQUE.
  • X149: Primary/Unique key fields must be specified as NOT NULL.
    Before creating a PRIMARY KEY, you must specify that the fields involved are NOT NULL. You can do this through the Create/Alter Table module, or by using the ALTER command.
Parent topic: X - Engine Error Messages


X150 - X199

Lists the Engine error messages from X150 through X199.
Restriction: This topic applies to Windows environments only.
  • X150: Referenced fields must be specified as NOT NULL.
    Before you can create a FOREIGN KEY, you must specify that the referenced fields involved are NOT NULL. You can do this through the Create/Alter Table module, or by using the ALTER command.
  • X151: Location path exceeds maximum length of 48.
    Path names are restricted to 48 characters in length.
  • X152: Invalid transaction number.
    Internal error code. Contact Micro Focus Technical Support.
  • X153: No space for locks.
    There is no space to record additional record locks. If the transaction requires many locks on the same table, it is a good idea to lock the entire table, instead of attempting to lock each record. In multi-user XDB Server versions the size of lock tables can be configured through the XDB Server Configuration program.
  • X154: Cannot find table/record lock.
    Internal error code. Contact Micro Focus Technical Support.
  • X155: Table/record currently locked by user at node.
    A lock conflict exists. A record or table lock on the object you are attempting to lock is held by the user at the node (workstation) specified.
  • X156: Table/record currently locked by user at node.
    A lock conflict exists. A record or table lock on the object you are attempting to lock is held by the user at the node (workstation) specified. Note: With CICS, you must commit or use the Dirty Read (DR) option.
  • X157: Cannot obtain exclusive lock or drop lock in isolation level 5 or 6.
    When working at isolation level 5 (dirty read) or level 6 (snapshot read), a transaction cannot acquire or drop exclusive locks on any database object. Levels 5 and 6 are intended for read only. You cannot insert, update, delete, or alter database objects at these levels. You can change the isolation level using the following command:
  • X158: Cannot obtain or delete table locks in isolation level 5 or 6.
    When working at isolation level 5 (dirty read) or level 6 (snapshot read), a transaction cannot acquire or drop table locks. Levels 5 and 6 are intended for read only. You cannot insert, update, delete, or alter database objects at these levels. Tables are accessible by other users.
  • X159: Current location is locked by user at node.
    A lock conflict exists. The location you are attempting to access is locked for exclusive use by the user working at the node specified.
  • X160: Cannot obtain isolation level EU due to existing locks.
    The database you are attempting to lock is in use by others. Isolation level EU (exclusive use) not available until all other users close the database.
  • X161: Not enough memory free on XDB Server to process request.
    The minimum contiguous memory block is a configurable parameter (0-64K) for the XDB Server. The XDB Server does not currently have enough memory to process the request. Increase the size of the memory block. Increase the amount of free space on the server.
  • X162: Logging in to XDB Server name requires security on at user node.
    Security has been turned on at the XDB Server named. Security must also be turned on at the user node via the Configuration utility.
  • X163: No network node name specified. Must be set through XDBCONFIG.
    In the multi-user system, each network node must have a unique name, specified via the Configuration utility. The system is shipped without a default name since names must be unique.
  • X164: Operation cannot be performed in isolation level DR or SR.
    The user is trying to perform an operation other than reading a record while in the Dirty Read (DR) or Snapshot Read (SR) isolation level. Change to a different isolation level using the SET ISOLATION LEVEL command, or through Options.
  • X165: Redirector version does not match XDB Server version.
    The LAN redirector you are using does not generate communication packets that the XDB Server understands.
  • X166: Operation requires isolation level EU (Exclusive Use) with this server.
    Compacting database can only be performed at using an exclusive use isolation level (EU).
  • X167: Redirector does not support the selected protocol protocol.
    The communications protocol specified in Options is not supported by the redirector currently in use. For example, a DOS client can use NetBIOS, but cannot use Named Pipes.
  • X168: User has been deleted by DBA at XDB Server.
    The user's account on the XDB Server has been deleted. Please contact your Database Administrator.
  • X169: Attempted to examine the status of an un-executed command.
    An application issued a set of calls to the Server but not all were executed. An error exists in the application being run. Make sure you are using the correct AuthID for your location, and that you are pointing to the correct server. If the application is a Micro Focus program, please contact Micro Focus Technical Support.
  • X170: Referenced key field type(s) must match foreign key field type(s)
    The fields, taken in order, of the PRIMARY or UNIQUE KEY referenced by a FOREIGN KEY must match the type of the fields in the foreign key.
  • X171: Foreign key already exists on field(s) specified.
    Only one FOREIGN key is permitted on any set of fields. For example, if building a foreign key on item (o_no) that references the ORDERS table, you cannot build a another foreign key in the item (o_no) field.
  • X172: Cannot create directory on path path.
    An attempt to create a directory in the path specified failed. The path may already exist, or an attempt may have been made to create a subdirectory for a directory that does not exist.
  • X173: Cannot flush location file contents to disk.
    An attempt to commit a DDL operation (e.g. CREATE) failed. Disk may be full.
  • X174: Synonym/Table name already exists.
    You cannot create a synonym using a name already used by another synonym, table or view.
  • X175: Synonyms cannot be created on other synonyms.
    Synonyms may be created on tables and views only.
  • X176: Synonym name does not exist.
    You cannot drop a synonym that does not exist.
  • X177: Maximum identifier size exceeded.
    Table names, view names, index names, column names and synonyms are limited to 18 characters.
  • X178: Precision must be a value between 1 and 31.
    XDB Server accepts precision between 1 and 31. Precision is the total number of digits, including scale (number of decimal places) permitted in a decimal field.
  • X179: Scale must be a value between 0 and the precision.
    XDB Server accepts precision between 1 and 31. Precision is the total number of digits, including scale (number of decimal places) permitted in a decimal field. Scale cannot exceed the total number of digits permitted in the decimal field.
  • X180: Cannot truncate table file.
    When deleting all records from a table using the DELETE FROM table-name command, the tables and indices are simply truncated. An error occurred when attempting to truncate a file. Check your disk.
  • X181: Cannot truncate index file.
    When deleting all records from a table using the DELETE FROM table-name command, the tables and indices are simply truncated. An error occurred when attempting to truncate a file. Check your disk.
  • X182: Cannot perform table on forward log file name.
    An error occurred when attempting to read, write, search or truncate the forward log file specified. Check your disk. See X001.
  • X183: Cannot perform operation on backward log file name.
    An error occurred when attempting to read, write, search or truncate the backward log file specified. Check your disk. See X001.
  • X184: Illegal outer join conditions.
    Only five outer join conditions per query are currently permitted.
  • X185: FOR UPDATE OF not allowed with GROUP BY or ORDER BY clause.
    The FOR UPDATE OF clause cannot be used on a query that is not updateable. GROUP BY and ORDER BY queries are not updateable.
  • X186: Maximum number of open files exceeded.
    The system cannot process the current command because it is unable to open another file. You may need to close some queries, remove some indices from your table, or change the limit on the number of concurrently open files. In DOS, the number of files that can be concurrently opened by the system is specified in you computer's CONFIG.SYS file, as described in your Installation documentation.
  • X187: Referenced key and foreign key must have same number of fields.
    When defining a FOREIGN KEY, you must reference an existing key with the same number of fields.
  • X188: Attempt to place NULL value in host variable with no indicator variable.
    Embedded SQL only. If you retrieve a NULL value, you must have a special null indicator variable assigned for it. See the SQL Reference for further information.
  • X189: Source and Target locations have the same name.
    This error occurs when two locations with the same name exist in a system, and an attempt is made to copy a table from one to the other. You should rename one of the locations before attempting the copy.
  • X190: Cannot copy table/view to itself.
    XDB Server does not permit the same table to be used as the source and target for a copy operation. This error may occur when two databases with the same name exist in a system, and an attempt is made to copy a table from one to the other. Rename one of the databases before attempting the copy.
  • X191: View definition too large for memory buffer.
    There is not enough memory to process a view definition. If you have multiple queries open, or if you have unnecessary programs loaded into memory, close or remove them, and try again.
  • X192: Error in source view definition.
    Unable to copy view because of an error in the source view definition. You may need to redefine the view in the source database before attempting to copy it.
  • X193: Outer join condition not allowed on expression predicates.
    Outer join conditions are allowed on fields only and not on expression predicates.
  • X194: Attempt to divide by zero.
    An attempt was made to divide by zero within an expression.
  • X195: User does not have privileges necessary for renaming a table.
    You must be the creator of the table or have DBADM privileges on the database in order to rename a table.
  • X196: Expression in GROUP BY/ORDER BY clause not allowed.
    Only a field name or field number is permitted in a GROUP BY clause. Only a field name or column number is permitted in a ORDER BY clause.
  • X197: Expression not allowed on left side of set clause.
    The left-hand side of a SET clause must be a valid keyword, such as DATABASE or BACKWARD LOG. Expressions, when permitted, may appear only on the right-hand side of the SET clause.
  • X198: Expression not allowed for field of insert clause.
    When specifying the target fields for an INSERT command, you must use field names; expressions are not allowed.
  • X199: Illegal foreign key constraint.
    A FOREIGN KEY cannot be referenced by another FOREIGN KEY. If you want A to reference B, and B to reference C, then instead have A reference C and B reference C.
Parent topic: X - Engine Error Messages


X200 - X249

Lists the Engine error messages from X200 through X249.
Restriction: This topic applies to Windows environments only.
  • X200: Illegal attempt to log out of parent process when dependents exist.
    Internal error. Contact Micro Focus Technical Support.
  • X201: User does not have privilege necessary for operation.
    The user does not have the privilege required for the attempted operation. Check the SQL Reference for privileges required for specific operations.
  • X202: Check condition does not exist.
    An attempt was made to drop a non-existent check condition.
  • X204: Referenced key must be a primary/candidate key.
    Foreign key must reference a Primary or Candidate (Unique) key.
  • X205: Invalid character representation of numeric data.
    A character string that contains invalid or non-numeric data is used in a location that requires numeric data.
  • X206: Compatibility index must be set to group by number.
    The ability to perform a GROUP BY using column numbers in the specification is not supported in any compatibility modes other than the XDB mode. Change compatibility mode or write specification using column names.
  • X207: Check condition/view name incompatible with current version.
    The structure of underlying tables has changed since the view or check conditions were created. Drop the view or condition and recreate using the new database definitions.
  • X208: Table/View exists in target location. Use WITH REPLACE to overwrite.
    If table exists in target location, you must either drop it before overwriting, or use the COPY command with the WITH REPLACE option.
  • X209: Cannot perform GROUP BY on a view containing a GROUP BY.
    If a view contains a GROUP BY clause, a command using the view cannot also contain a GROUP BY clause.
  • X210: Cannot perform join with a view containing a GROUP BY.
    A view containing a GROUP BY clause cannot be joined to other tables.
  • X211: Cannot perform aggregate function on a view containing a GROUP BY.
    If a view contains a GROUP BY clause, no command using that view may contain an aggregate function.
  • X212: Function not available under current compatibility setting.
    The current compatibility setting set through Options does not permit the function being attempted. The setting must be modified to one that allows the functionality/syntax being attempted. See the Options User's Guide.
  • X213: Internal error encountered in function function. Contact Micro Focus.
    An unexpected internal error occurred. Contact Micro Focus Technical Support.
  • X214: The cursor identified in an open statement is already open.
    The application program attempted to execute an OPEN statement for a cursor that was already open. Correct the logic of the application program to ensure that it does not attempt this action.
  • X215: The cursor identified in a fetch/close statement is not open.
    The application program attempted to either (1) FETCH using a cursor, or (2) CLOSE a cursor at a time when a specified cursor was not open. In DB2 mode commit and rollback implicitly close cursor. After a cursor is closed, FETCHes or CLOSE cursor statements will generate this error code.
  • X216: Exceeded maximum outer join conditions.
    An outer join condition is one that contains a plus sign (+) next to a field. The number of outer join conditions allowed has been exceeded. Currently, five outer joins are allowed per query. To proceed, reduce the number of these conditions.
  • X217: Specified more than one primary key clause.
    The CREATE TABLE specified more than one primary key. By definition, a table may not have more than one primary key. Other candidate keys may be defined as unique keys.
  • X218: Referenced table does not contain a primary key.
    The table nominated as the parent in a FOREIGN KEY clause cannot be defined as a parent because it does not have a primary key defined. Correct the statement so that the table nominated as the parent in the FOREIGN KEY clause references a table with a primary key, or define a primary key for the table nominated as parent.
  • X219: Relationship name name already exists on this table.
    The constraint name specified in the FOREIGN KEY must be unique among all constraint names specified for this table. Change the name to one that is unique.
  • X220: Operation not allowed on table with incomplete definition.
    The reference to the table is invalid because it has a primary key, but no primary index. The reference is in a FOREIGN KEY clause or an SQL manipulative statement. Define a unique primary index on the table before referencing it.
  • X221: ALTER TABLE PRIMARY KEY requires existing unique index.
    The ALTER TABLE statement is invalid because the table does not have a unique index with a key that is identical to the nominated PRIMARY KEY. Make sure the key list specified on the ALTER TABLE statement identifies an existing unique index of the table.
  • X222: Relationship name must be less than 8 characters.
    The relationship name specified in the FOREIGN KEY clause is too long. Shorten the name to 8 characters or less.
  • X223: Self-Referencing tables must use the CASCADE delete rule.
    The delete rule specified in the FOREIGN KEY clause of the ALTER statement is invalid. A self-referencing constraint must specify the delete rule of CASCADE. Change the delete rule in the FOREIGN KEY clause.
  • X224: One or more foreign key fields must be nullable for SET NULL rule.
    The SET NULL clause of the FOREIGN KEY statement is invalid because no column of the key allows NULL values. Change a column of the key to allow NULL values, or change the delete rule.
  • X225: Primary key clause does not exist.
    The ALTER DROP PRIMARY KEY command was attempted on a table that does not contain a primary key.
  • X226: Relationship name name cannot be found in system table SYSREF.
    The ALTER DROP FOREIGN KEY command specified a constraint name that could not be found on the SYSREF table. Check the name to make sure it is a valid constraint name.
  • X227: Attempt to update parent having dependents in relationship name.
    An UPDATE operation attempted to update a primary key in the specified row of the object table; however, the primary key in the specified row had dependent rows associated with it. The value of a primary key in a parent row cannot be updated if the parent row has dependent rows. Examine the primary key of the object table and the foreign key of the dependent table to determine if the value of the primary key should be changed. If this does not solve the problem, examine the contents of the object table and the dependent table to determine the cause of the problem.
  • X228: The relationship name restricts the deletion of row with ID number.
    A DELETE operation attempted to delete a specified parent row in the object table and all related dependent rows in the dependent tables. However, a delete rule of RESTRICT was specified for one or more dependent tables.
  • X229: The insert/update value of foreign key name is invalid.
    An UPDATE or INSERT operation attempted to place a value in a foreign key of the object table; however, this value was not equal to some value of the primary key of the parent table.
  • X230: Index name is not compatible with current version.
    The index was not created with the current version and is incompatible. Rebuild the index with the current version. All indices in the location can be rebuilt using the COMPACT LOCATION AND INDEX command. All indices for a particular table can be rebuilt using the COMPACT TABLE `table-name' and INDEX command.
  • X231: Cursor must be declared as FOR UPDATE OF.
    The application program attempted to execute an UPDATE WHERE CURRENT OF statement on a cursor not defined as FOR UPDATE OF. Declare the cursor FOR UPDATE OF.
  • X232: Index name sort sequence different from current setting.
    An attempt was made to access an index that was created using a sort sequence different from the current sort sequence setting. When an index is created, it is sorted using the sort sequence specified in Options. To access this index, your default sort sequence setting must be consistent with that of the index. Rebuild the index with the default sort sequence setting or modify the setting in Options to be consistent with the index. Alternatively, you can drop the index and then recreate it with the new sort sequence setting.
  • X233: Non-quantified predicate followed by a list of values.
    If using a predicate without an ANY or ALL clause, only one value is allowed.
  • X234: Function not available with engine as database engine.
    DB2 link CAPI function not implemented with this engine.
  • X235: XDBXDIRECT function not supported on GROUP BY cursor.
    The Xdbxdirect function is not supported with queries containing a GROUP BY clause.
  • X236: Must use ALTER TABLE DROP PRIMARY KEY to drop index pending.
    An attempt was made to drop the `pending' index, which is a temporary name for a PRIMARY KEY which has not yet had a unique index created for it. To drop this index, use the ALTER TABLE DROP PRIMARY KEY statement.
  • X237: operation not allowed on table name while in use.
    Another user attempted an operation on the specified table while the table was in use. Skip the operation or retry it later.
  • X238: Attempt to update a deleted record.
    The record you are attempting to update has been deleted.
  • X239: Invalid DEGREE specified.
    The SET CURRENT DEGREE command contains an invalid value.
  • X240: Cannot delete field name which has existing referential key.
    An attempt was made to delete a field containing a referential key. To delete the field, first drop the referential key.
  • X241: Cannot modify field name which has existing referential key.
    An attempt was made to modify a field containing a referential key. To modify the field, first drop the referential key.
  • X242: Maximum number of sort fields exceeded.
    The query has exceeded the maximum number of sort fields allowed. The current maximum number of sort fields is 750.
  • X243: Host variable not allowed in current command.
    The command executed does not support host variables.
  • X244: Object table is referenced in nested query FROM clause.
    In DB2 mode, the table that is the object of an update, insert or delete cannot also be referenced in a nested query FROM clause.
  • X245: Requested packet is larger than max buffer size.
    The amount of data being sent from the application program to the engine is too large. Increase the receive buffer size on both the client-side and the server-side.
  • X246: Primary key cannot be target of multiple-row update.
    In DB2 mode, a primary key cannot be updated if an update clause retrieves more than one record.
  • X247: String representation of a date/time value is invalid.
    The character representation of a date or time value is not being recognized. The engine can recognize ISO, JIS, EUR, USA, and LOCAL formats. Compare your date/time representation with the picture specified in CONFIG.XDB through Options.
  • X248: AuthID not allowed on synonym table reference.
    In DB2 mode, a synonym cannot be referenced in a FROM clause with an AuthID. Remove the AuthID.
  • X249: Invalid picture specification.
    The picture used in the CHAR function is not legal.
Parent topic: X - Engine Error Messages


X250 - X299

Lists the Engine error messages from X250 through X299.
Restriction: This topic applies to Windows environments only.
  • X250: Invalid PCTFREE value.
    Valid percent free values are 0 through 99.
  • X251: Only one clustered index allowed per table.
    XDB Server currently supports only one clustered index per table. Make all other indices non-clustered.
  • X252: Truncate not allowed on primary key table.
    The TRUNCATE clause is not allowed on tables that have a PRIMARY KEY.
  • X253: Compact cluster by clause must specify existing clustered index.
    When using the CLUSTER BY clause in a COMPACT statement, and the table has a clustered index, then you must specify the clustered index that already exists. If the table does not have a clustered index, then any index can be specified.
  • X254: DUPQTY value must be 8, 16, 32, 64 or 128.
    The only legal values when using the DUPQTY clause are 8, 16, 32, 64 and 128.
  • X255: Communication Manager out of memory.
    The XDB Server ran out of memory. You may want to reconfigure your system to increase available memory. See the XDB Server Administration Guide for specific performance tuning procedures.
  • X256: Stored Procedure ProcName failed due to reason ReasonCode.
    The XDB Server is not able to execute the CALL statement for the stored procedure ProcName.
  • X257: Engine configuration maximums too large. Reconfigure them smaller.
    The configuration parameters for Windows must fit into 64K. The options selected require more than 64K. Use the XDB Server Configuration utility to reconfigure the options.
  • X258: Out of memory for expressions.
    The total amount of memory required by the query for expressions exceeded the maximum memory that can be supported by XDB Server.
  • X259: Error on Operation (size) Server (server).
    An error has occurred with server-to-server access.
  • X260: Operation cannot be performed on current location version.
    The current location format does not include support for the command. Creating a new location or upgrading the system location will bring the current location version up to date.
  • X261: Redirector not loaded!
    The redirector associated with the selected protocol is not currently running. If your protocol is currently set to NetBIOS, run the NetBIOS redirector.
  • X262: Invalid parameter. A valid window handle was expected.
    A valid window handle is not zero. Pass a valid window handle returned from the CreateWindow() function.
  • X263: XdbWinInit() has not been called. XdbWinInit() must be called first.
    Under Windows, the function XdbWinInit() must be called before all other functions. See your C documentation.
  • X264: A necessary window could not be created.
    A window could not be created due to the number of windows already open or the amount of system resources in use. Close other windows or shut down other applications and try again.
  • X265: User program ProgramName could not be found.
    The XDB Server cannot find the DLL or the function associated with the procedure specified in your SQL CALL statement.
  • X266: Server is shutting down. Accepting no more logins.
    The server has been configured to shut down on last disconnect. No new connections are allowed.
  • X267: Invalid parameter in function function.
    An internal error has occurred. The XDB Server has received an invalid parameter or a different number of parameters than it expected.
  • X268: Server shutdown already in progress.
    Only one server shutdown command may be active at any one time.
  • X269: Illegal shutdown parameter.
    Internal error in shutdown processing. Contact Micro Focus Technical Support.
  • X270: Update/Delete on invalid cursor position.
    An application program tried to update or delete on an invalid cursor position. This is an internal error. If the application is a Micro Focus program, contact Micro Focus Technical Support.
  • X271: The Server failed when trying to begin a thread.
    The maximum number of threads allowed was exceeded. You must reconfigure the number of threads needed to a smaller number. The XDB Server Configuration utility options that affect this are:
  • X272: Cannot open file name. Increase the max number of open files in the XDB Server Configuration utility.
    The specified file could not be opened because the maximum number of open files set in the server configuration was exceeded. Increase the maximum number of open files in XDB Server Configuration utility.
  • X273: AuthID exceeds the maximum length.
    The maximum length of an AuthID is 8 characters.
  • X274: Location name exceeds the maximum length.
    The maximum length of a location name is 16 characters.
  • X275: Column name in explanation table name is not defined properly.
    An error occurred during the insertion of a row into the explanation table. The table is improperly defined for one or both of the following reasons: columns are defined in the wrong order; or a column description is invalid because of its name, data type, length or NULL attributes. Correct the definition of the required explanation table.
  • X276: Invalid number of fields (number) in explanation table name.
    The explanation table does not have a valid number of fields. Correct the definition of the required explanation table.
  • X277: userid does not have privilege to create with qualification authid.
    The specified user attempted to create an object with an invalid AuthID. Only if your AuthID is SYSADM, DBADM or DBCTRL can you create an object with an AuthID other than your valid primary or secondary AuthID. Ensure that AuthID is one of your valid AuthIDs.
  • X278: auth specified is not one of the valid AuthIDs.
    The specified AuthID is not the user's current primary or secondary AuthID. Specify a valid AuthID.
  • X279: Name name is too long. Maximum allowable size is number.
    The specified name has exceeded the maximum allowable length of number characters. Columns, tables, views, indices, aliases and synonyms have a maximum length of 18 characters. Locations have a maximum length of 16 characters. Table qualifiers, view qualifiers, storage group names, database names, tablespace names, and constraint names specified in CREATE or ALTER TABLE statements have a maximum length of 8 characters. Volume serial numbers must contain 6 characters or fewer, and labels must contain 30 characters or fewer. Enter a shorter name for the object.
  • X280: name is an undefined name.
    The object specified by name does not exist in the XDB Server location. Be sure you have entered the correct name.
  • X281: Object name name of object type type already exists.
    There is already an object of the type specified with the name specified. Drop the existing object or enter another name for the new object.
  • X282: Too many volume serial numbers specified.
    The CREATE or ALTER STOGROUP command specified a list of volumes that exceeds the maximum of 133. Shorten the list of volumes specified.
  • X283: The PART clause of an ALTER statement is omitted or invalid.
    The ALTER TABLESPACE command or ALTER INDEX command has an invalid partition clause. Check to be sure that the tablespace or index to be altered is partitioned. If so, be sure you have identified the correct partition; if not, do not include a PART clause.
  • X284: Duplicate keyword keyword.
    The specified keyword has a duplicate specification in the SQL statement. Change the statement so that it only contains one specification for the keyword.
  • X285: Attempt to drop stogroup used by a tablespace.
    An attempt was made to drop a storage group that is being used by one or more tablespaces. You must first alter or drop all tablespaces that use the stogroup before the stogroup itself can be dropped. You can query the STORNAME field of the SYSIBM.SYSTABLEPART system table to find all tablespaces that are dependent on the stogroup.
  • X286: Operation not allowed on system database.
    The attempted operation may not be performed on a system database.
  • X287: Alias name must not be defined on another alias.
    The specified name identifies an alias, which is defined on another alias. Do not use aliases to define other aliases; they should only define base tables or views.
  • X288: Statement reference to remote object is invalid.
    This error can be caused by any of the following conditions:
  • X289: Invalid value specified for keyword keyword.
    The value specified for the keyword is invalid. See the SQL Reference for valid keyword values.
  • X290: Keyword keyword not allowed for tablespace in workfile database.
    The specified keyword cannot be used for a tablespace in the workfile database. Change the SQL statement.
  • X291: Illegal use of keyword keyword.
    A syntax error exists in the SQL statement at the point where the specified keyword appears. Check the statement for errors.
  • X292: Unable to perform operation operation on database name.
    The requested operation is not legal or valid on the specified database.
  • X293: Table/Index ObjectName in use.
    The XDB Server cannot execute the STOP DATABASE command because the specified table or index is being used.
  • X294: Unable to operation stopped database name.
    It is illegal to perform the specified operation on the specified stopped database.
  • X295: Database ROSHARE can only be altered from OWNER to NONE.
    XDB Server only supports the altering of Read-Only Shared Databases from a value of OWNER to a value of NONE. You must create a new ROSHARE database in order to obtain other share options.
  • X296: Location name is not converted. Run location conversion program.
    The location specified is not compatible with the current version of the XDB Server database engine. You must convert the location by running the XDB Server conversion program CONVERT.EXE.
  • X297: FOR FETCH ONLY and FOR UPDATE OF are mutually exclusive clauses.
    You cannot specify both a FOR FETCH ONLY clause and a FOR UPDATE OF clause in your query. If a cursor is to be both fetched and updated you should not specify either clause in the SELECT statement.
  • X298: Synonym target must include an explicit authorization ID.
    The object to which a synonym applies must specify a two-part name that includes a valid AuthID. Modify the table or view name to include an AuthID.
  • X299: A segmented tablespace may not be partitioned.
    The CREATE TABLESPACE statement contains both the SEGSIZE and NUMPARTS specification, but they are mutually exclusive.
Parent topic: X - Engine Error Messages


X300 - X349

Lists the Engine error messages from X300 through X349.
Restriction: This topic applies to Windows environments only.
  • X300: Cannot open configuration file CONFIG.XDB. Check XDBCFG setting.
    CONFIG.XDB was not found in the current directory, or in the directory specified by the XDBCFG environment variable.
  • X301: Cannot open configuration file CONFIG.XDB. Check XDBCFG setting.
    CONFIG.XDB was not found in the current directory, or in the directory specified by the XDBCFG environment variable.
  • X302: Cannot read configuration file CONFIG.XDB.
    The system is unable to open CONFIG.XDB. The file may be missing, damaged, or read-locked.
  • X305: Cannot open help file name.
    The file named was not found in the home directory. The `home' directory is set using Options.
  • X306: Syntax error in mask definition.
    The system was unable to parse a mask definition. Check the mask definition against the Options User's Guide.
  • X307: Grouping character found twice or in illegal position.
    The grouping character cannot appear to the right of the decimal point. A money symbol cannot appear between the grouping symbol and any numeric mask characters.
  • X308: No grouping length.
    No grouping character (,) was found in the mask; therefore, the grouping character cannot be reassigned.
  • X309: Decimal character found twice or in illegal position.
    A decimal point can only appear once in a numeric picture. Make sure you are not using a decimal point as a grouping character.
  • X310: Rounding character in illegal position.
    The rounding character (r) should appear as the rightmost character in a picture.
  • X311: Illegal character in picture specification.
    A character other than one of the characters in +-$,.9zr was found in a numeric picture specification.
  • X312: "$" character found on both sides of decimal.
    A dollar sign can only appear on one side of the decimal point in a money picture. Usually the dollar sign appears to the left. If the dollar sign appears to the right of the decimal point, only one dollar sign should appear.
  • X313: Sign character found on both sides of the decimal.
    A negative (-) or plus (+) sign can only appear on one side of the decimal point in a numeric picture. Usually the sign appears to the left of the decimal point. If the sign appears to the right of the decimal point, only one sign should appear in the picture.
  • X314: Error in substitution portion of picture definition.
    The decimal (.), grouping (,) and money ($) symbols are used when creating a numeric picture. You may substitute other characters for the decimal, grouping or money symbols by assigning a new value to these symbols after specifying the mask, for example:
  • X315: Illegal decimal found in picture.
    Cannot reassign the decimal character as requested, or the period character is not used as a decimal point in the mask portion of the picture.
  • X316: Illegal rounding character found in picture.
    Cannot interpret the rounding character r in its current location in the picture.
  • X317: Illegal dollar sign found in picture.
    Cannot reassign the money character as requested, or $ is not used as a money symbol in the mask portion of the picture.
  • X318: Closing single quote not found in substitution string.
    An expression assigning a new decimal, grouping or money symbol is missing a closing quote.
  • X319: Value too wide for picture field.
    An attempt was made to assign a value, or display a value using a picture that is unable to accommodate the value; for example, an attempt to display the value 1234 in a variable or column with a picture of 999.
  • X320: Error in time/date picture definition.
    The system is unable to parse a time or date picture. See the Options User's Guide for information on creating time and date pictures.
  • X321: Invalid CONFIG.XDB. Run XDBPROFI to reconfigure system.
    The configuration file, CONFIG.XDB, which is stored in the Micro Focus directory, has been damaged or is incompatible with the current version. Run Options as described in the Options User's Guide.
  • X322: Invalid year value.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X323: Invalid separator in value.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X324: Invalid character in value.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X325: Money value error.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X326: Numeric value error.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X327: Integer value error.
    The user input an illegal value in the specified field type. See the SQL Reference for information on data type ranges and domains. Also check the default format specified for the data type through Options (described in the Options User's Guide). Check to make sure that pictures and data match.
  • X328: No more RAM memory available.
    Insufficient RAM available to continue processing. Remove unnecessary programs from memory. For example, bypass the Loader or the Micro Focus application menu.
  • X329: COMMAND.COM not found.
    Please contact Micro Focus Technical Support.
  • X330: Cannot execute program.
    An error occurred when attempting to use the shell facility to temporarily exit to the operating system (possibly insufficient memory). In order to reach the operating system, you will have to exit normally, instead of using the shell facility.
  • X332: Index name does not exist.
    The index named was not found in the current database. Check the database path and the name of your index.
  • X333: Unknown field type in table name.
    An unknown field type was found. A different version of XDB Server may have been used to create the table, or the system path may be set to an earlier version. Check the version.
  • X334: Index name has been damaged.
    Either the named index has been damaged or a different version of XDB Server is running than the one that created the index. Use the version that created the index. The system path may be set to an earlier version. Check the version.
  • X335: Key name does not exist.
    The key named was not found in the current database. Check the database path and the name of your key.
  • X336: Key name has been damaged.
    Either the named key has been damaged or a different version is running than the one that created the key. Use the version that created the key. The system path may be set to an earlier version. Check the version.
  • X337: Synonym name does not exist.
    The synonym named was not found in the current database. Check the database path and the name of your synonym.
  • X338: Table/View name does not exist.
    The table or view named was not found in the current database. Check the database path and the name of your table or view.
  • X339: Error opening file FileName for Page1 to Page2 translation.
    The XDB Server was not able to open this file, which is needed for code page translation.
  • X340: Not enough memory to perform action.
    There was not enough memory to execute the command. A smaller command may be possible. Remove all memory resident tools that you are not currently using and try again.
  • X341: Illegal decimal precision.
    The number has an illegal precision. Check your data and your data type; they are probably not the same.
  • X342: Called function is not compatible with current version.
    This error occurs only when running the COBOL Precompiler. You must precompile and compile your program again for compatibility.
  • X343: An explicit COMMIT is illegal in an IMS/CICS program.
    IMS/CICS performs an implicit COMMIT. This is mainframe-compatible.
  • X344: An explicit ROLLBACK is illegal in an IMS/CICS program.
    IMS/CICS performs an implicit ROLLBACK. This is mainframe-compatible.
  • X345: A negative or zero ABSOLUTE FETCH is illegal.
    An absolute fetch needs a value specifying the offset from the current cursor position, and the offset must be a positive number.
  • X346: Cannot locate files in the directory specified.
    Files needed by the system cannot be found in the path specified by the XDBPATH environment variable. Make sure that you have specified the correct directory in the XDBPATH environment variable. Also make sure that your server names match in Options and the XDB Server Configuration utility.
  • X347: Illegal function code passed to the COBOL interface.
    Internal error. Contact Micro Focus Technical Support.
  • X348: No application path specified.
    There is no application path specified in CONFIG.XDB. IMS/CICS performs an implicit ROLLBACK. This is mainframe-compatible.
Parent topic: X - Engine Error Messages


X350 - X399

Lists the Engine error messages from X350 through X399.
Restriction: This topic applies to Windows environments only.
  • X352: Server violation.
    The server experienced a protection exception while processing a user's command. The exception handling code has rolled back the user's current transaction and logged the user out.
  • X354: Error loading server communications DLL(name).
    Make sure you have the DLL named in the correct DLL subdirectory.
  • X355: Error connecting to remote server(name).
    An error has occurred while trying to connect to server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.
  • X356: Error sending to remote server(name).
    An error has occurred while trying to send to server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.
  • X357: Error receiving from remote server(name).
    An error has occurred while trying to receive from server name. Make sure you have enough remote engine threads and that the server-to-server connectivity setup is correct in your system catalogs.
  • X358: Governor limit exceeded.
    One of the governor limits has been exceeded, and the server logged out the user. You could increase the governor limit for that user. The governor will be active only if the server security is ON.
  • X359: Error initializing remote server gateway.
    An error has occurred while trying to connect to a remote server.
  • X360: Incorrect version of the server configuration file.
    You have an old version of SRVCONFG.XDB. Delete your old SRVCONFG.XDB and run the new XDB Server Configuration utility to create a new one.
  • X361: No remote thread available to process request.
    A client has tried to connect to a remote server and the primary server does not have any thread available to handle the request. In these cases, there are no remote threads set for the primary server, or all the remote threads are already in use.
  • X362: Index error during recovery.
    While XDB Server was recovering a location, a fatal error occurred. You must compact and re-index the location immediately. Do not use the location until the compact and re-index has finished.
  • X363: No protocol threads available to process request.
    The number of protocol threads for TCP/IP, SPX, or Named Pipes must equal the number of users using the protocol.
  • X364: The describe statement does not identify a prepared statement.
    In order to describe a query, the query must first be prepared.
  • X365: Log path cannot be set to path.
    The logging system cannot set the log to the path specified. Ensure that the path exists, and that there are no other logs present in the path.
  • X366: Error replacing alias name with actual table name.
    XDB Server encountered an internal error when forming the alias substitution string. Contact Micro Focus Technical Support with the details of the query.
  • X367: GROUP BY/HAVING not allowed in subquery/embedded select.
    XDB Server and DB2 does not allow a GROUP BY or HAVING clause on a nested query.
  • X368: Illegal string string found.
    XDB Server received a different string than it expected. For example: SET CURRENT RULES <parm> must be either DB2 or STD. Using a different parameter will return an x368.
  • X369: Invalid index type.
    The index type must be 1 or 2.
  • X370: The target location needs to be compatible with DB2 version version.
    An attempt was made to perform new DB2 functionality against an XDB Server location that was created with this functionality. See the ALTER LOCATION command and CREATE LOCATION command in the SQL Reference .
  • X371: The selected locksize and lockmax options do not match.
    The DDL is illegal. See the SQL Reference for correct values.
  • X372: Illegal attempt to convert location to a lower version.
    An ALTER LOCATION can only be used to move forward in DB2 functionality, not backwards (i.e., an ALTER LOCATION cannot be used to convert a location to a lower version).
  • X373: Invalid number of parameters (number expected) for stored procedure ProcName.
    The number of parameters specified in your SQL CALL statement exceeds the number of parameters allowed by the ProcName stored procedure.
  • X374: Stored procedure ProcName received a null value for parameter number.
    The SQL CALL statement for stored procedure ProcName contains a null value in its parameter list, and this stored procedure does not accept null values.
  • X375: Stored procedure ProcName has been placed in a must rollback state.
    The stored procedure ProcName issued one of the following operations:
  • X376: Missing OBID clause when creating a table in a ROSHARE READ database.
    The OBID clause was not specified in the CREATE TABLE command. The OBID clause is required whenever the database containing the table is defined as ROSHARE READ.
  • X377: A privilege cannot be revoked because it is not possessed by AuthID authid.
    An AuthID can revoke only the privileges that it has explicitly granted to other AuthIDs, unless the AuthID has SYSADM or SYSCTRL authority and specifies the BY clause.
  • X378: Attempt to disable login with security off.
    A DISABLE LOGIN command was issued while security was off on the XDB Server.
  • X379: The login was rejected due to logins being disabled.
    The database administrator has disabled logins for this XDB Server, so your login command was rejected.
  • X380: The XDB Server has rejected this connection due to load balance requirements.
    Your connection request was rejected because the XDB Server has exceeded the load balancing limits configured by the database administrator.
  • X381: Cannot connect with requested location. Location is offline.
    The location you have requested is currently offline. (Your database administrator may have taken it offline for maintenance purposes.)
  • X382: Cannot take requested location offline. Location is in use.
    The XDB Server cannot take the requested server offline because it is being used. You are allowed to take a location offline only when there are no users attached to it.
  • X383: Sequence error for reason code (ReasonCode) Message.
    The XDB Server has received a request out of order.
  • X384: Invalid handle.
    The XDB Server has received an invalid handle. This is an internal error.
  • X385: Login error with Reason Code ReasonCode Message (returned Number).
    An error has occurred while logging on to the XDB Server through the Direct Flight software.
  • X386: Conflicting definitions for the same variable or parameter. Description
    The SQL Server has received a parameter or host variable from the client application that does not match the data type it expected.
  • X387: Option conflict with location rules
    The statement being executed has an option that is incompatible with the current location type.
  • X388: Invalid token 'token' found in PARMLIST for procedure proc-name
    A Stored Procedure or Trigger definition has a syntax error.
  • X389: Illegal operation on temporary table
    The current operation is not allowed on a temporary table. Temporary tables are not allowed to have primary/unique keys, or to be referenced by foreign keys. Also, update/delete operations on records in temporary tables are not allowed.
  • X390: Check option not allowed on temporary table
    A view of a temporary table must not specify the CHECK OPTION clause.
  • X391: WITH DEFAULT clause not allowed on CREATE GLOBAL TEMPORARY TABLE
    WITH DEFAULT clauses are not allowed on a CREATE GLOBAL TEMPORARY TABLE statement.
  • X392: Your SQL Option (for DB2 emulation) has expired.
    The XDB component (e.g., XDB Server, XDB Link) you are attempting to use does not have a valid license from Micro Focus.
  • X393: Output host variable PositionNumber is incompatible with the query result.
    The XDB Server is not able to return the result of a CALL, FETCH, or SELECT statement because the data type of the variable at PositionNumber in the output SQLDA (to which the result was to be written) does not match the data type of the result.
  • X394: Input host variable PositionNumber is incompatible with the current query.
    The XDB Server is not able to execute the requested SELECT statement because it contains a host variable whose data type is not correct. (For example, the WHERE clause may be using a numeric host variable to select from a DATE field in the database.) The host variable causing the problem is located at PositionNumber in the input SQLDA.
  • X395: Value for data type Type is out of range for host variable PositionNumber.
    The XDB Server cannot return the requested value because the returned value is larger than the host variable at PositionNumber in the output SQLDA (to which the value was to be written) can accept.
  • X396 ColumnName is not a column of specified table or view in the query.
    The specified name is not a column in the table or view referenced. A bad column name in a FOR UPDATE OF clause can generate this error.
  • X397 Decimal host variable or parameter Identifier contains non-decimal data.
    Data could not be used as specified in the statement because the data is not valid for this type.
  • X398 ColumnName is not an updateable column; it is not identified in the update clause.
    In order to update this column, you need to specify its name in the FOR UPDATE OF clause for this cursor.
  • X399 Improper use of long string data, StringValue.
    The operation is not supported on a long string value in DB2 mode.
Parent topic: X - Engine Error Messages


X400 - X449

Lists the Engine error messages from X400 through X449.
Restriction: This topic applies to Windows environments only.
  • X400 Named cursor already assigned to a result set locator.
    The named cursor could not be reused.
  • X401 Statement can't be issued until the stored procedure has been called.
    Either a DESCRIBE PROCEDURE or an ASSOCIATE LOCATOR statement has been executed prior to the CALL to the stored procedure.
  • X402 Invalid result set locator.
    The result set locator was never assigned a valid value. Result set locators are returned by the ASSOCIATE LOCATORS statement.
  • X403 Cursor name CursorName was not defined.
    The named cursor was not defined.
  • X404 A Rollback is required.
    The transaction is in a must rollback state.
  • X405 An ON clause in a JOIN operator is invalid.
    An ON clause used to specify a JOIN condition is invalid. VALUE/COALESCE functions are only allowed in FULL OUTER JOINs. Only an '=' operator is valid in FULL OUTER JOINs. Also, column may be inappropriately referenced from within the JOIN clause.
  • X406 Stored procedure StoredProcName parameter ParameterName is larger than declared.
    The stored procedure has used a value that is too large for the definition declared in the SYSIBM.SYSPROCEDURES PARMLIST field.
  • X407 Stored procedure StoredProcName requires a host variable for parameter ParameterName.
    The parameter in the stored procedure PARMLIST definition in SYSIBM.SYSPROCEDURES is defined as OUT or INOUT. A host variable must be supplied in the call for that parameter.
  • X408 Stored procedure StoredProcName did not return result sets.
    The stored procedure has not returned any results sets to the caller. Verify that the stored procedure has been coded correctly.
  • X409: Error in trigger trigger-name, section number trigger-section
    A trigger trigger-name executed during an INSERT, UPDATE, or DELETE statement contained an SQL statement that returned an SQL error. The section number trigger-section identifies the statement in error.
  • X410: Function function-name named without signature, function not unique
    The signature of the user defined function function-name is not unique within its schema. Either the CURRENT PATH must be changed or the SPECIFIC name of the function must be used.
  • X411: Signature for function function-name not unique within schema
    The function function-name that is being created does not have a unique signature within the schema.
  • X412: Set transition variable is used for before trigger per row only
    SET transition-variable can only be used within a before trigger whose granularity is FOR EACH ROW.
  • X413: Invalid insert into column %s defined as generated always
    No input value is allowed for a column defined as GENERATED ALWAYS.
  • X414: Internal error, identity column definition not found
    An internal error has occurred. The identity column definition could not be found.
  • X415: Only one rowid or identity column is allowed in a table
    A table contains more than one row ID or identity column. This is not allowed.
Parent topic: X - Engine Error Messages


XMIG - Migrate Error Messages

Restriction: This topic applies to Windows environments only.
  • XMIG000: Error system error: Unknown error errorID.
    Migrate attempted to display an error that was not found in the error file. This usually happens because an obsolete copy of the error file, XMIG.XRR, has somehow been copied into the directory.
  • XMIG001: No more RAM memory available.
    Migrate has experienced an internal error caused by a shortage of memory.
  • XMIG002: No Column in table.
    Migrate has experienced a serious internal error.
  • XMIG003: Cannot open file filename.
    Migrate is not able to open the specified file.
  • XMIG004: Syntax Error.
    Migrate is unable to interpret an SQL command that has been included in your migration.
  • XMIG005: Destination location has not been defined.
    Migrate is attempting to copy records, but a destination location has not been specified.
  • XMIG006: Destination table has not been defined.
    Migrate is attempting to copy records, but a destination table name has not been specified.
  • XMIG007: Error in internal query querystring.
    Migrate is attempting to access the SYSXDB.SYSQUERY table and the table is not in the expected format. Usually this is because the table is in an older format that does not include two fields required by Migrate.
  • XMIG008: Table tablename does not exist.
    The table name was not found in the specified source location.
  • XMIG009: Check source location data consistency.
    Migrate cannot create a foreign key because there is invalid value in the table.
  • XMIG010: Error saving file name.
    Migrate experienced an error when saving the named file.
  • XMIG011: Query window contains more than one query.
    Migrate has found an end-of-statement delimiter in the Query window. Only a single SELECT statement is allowed in this window.
  • XMIG012: Query must be a SELECT statement.
    Migrate has found an invalid SQL statement in the Query window. Only a single SELECT statement is allowed in this window.
  • XMIG013: Table already exists. Illegal with current settings.
    Select Table/Query Options from the Object menu, and check the "If table already exists" settings.
  • XMIG014: Field names in query may not match the field names of the destination table.
    An X009 was returned when the query from a Query window was executed. The database table has been altered since the .MIG file was saved, or there is some other problem with the validity of the SELECT statement in the Query window.
  • XMIG015: No key fields specified in replication query.
    A Query window used for replication must have at least one column defined as the key. Click the Update Rules button, and select True or False under the Key heading for each column returned by the SQL statement defined in the Query window.
  • XMIG017: Cannot find information in system_table for 'table_name'.
    SQL Migrate failed to retrieve information for the specified table from a system table when attempting to add it to the schema viewer.
  • XMIG049: SELECT error. May not have privileges.
    Migrate cannot complete this task because you do not have privileges on the specified object.
  • XMIG053: Filters yield no results. Filters are reset.
    The filter value entered for the immediate sub-item (database, or AuthID) beneath the location level returned an empty result set. The Catalog Browser display will be refreshed using the latest valid set of filter values stored in XDB.INI.
Parent topic: SQL Option for DB2 Error Messages


XU - Library Error Messages

Restriction: This topic applies to Windows environments only.
  • XU001: No more RAM memory available to application.
    Insufficient memory (RAM) was available to execute a command sent to the SQL Engine. Try running the application from outside the main or application menu to see if that gives you enough memory to continue. If you have other memory resident programs loaded, remove them and try again. Load network drivers into high memory or remove them. Reduce DOS memory consumption by using fewer FILES= and fewer BUFFERS= in CONFIG.SYS.
  • XU002: No more EXTENDED memory available to application.
    Insufficient extended memory is available to run the application. Try bypassing the XDB Server Main Menu, or removing other programs from memory. See error XU001.
  • XU004: Filename name is too long.
    The filename you have entered exceeded the maximum length. Filenames must be 8 characters or fewer. Enter a shorter filename.
  • XU005: File name not found.
    Cannot find the file specified. Check to make sure that the correct directory is being used, and that the specified file exists there.
  • XU006: Error opening file name. error-descr.
    The system could not open the file named due to the specific operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU007: Error reading file name. error-descr.
    The system could not read from the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU008: Error writing file name. error-descr.
    The system could not write to the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU009: Error closing file name. error-descr.
    The system could not close the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU010: Error deleting file name. error-descr.
    The system could not delete the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU011: Error seeking file name. error-descr.
    The system could not seek the file named due to the specified operating system error. See your operating system manual for the error described and make any necessary corrections.
  • XU014: Incorrect file version in file name.
    The file specified is not the current version. If it is a help file or error file, you must recompile the file using the current version of the help compiler, XDBHELPC. If the file is a message file, you must recompile it using the message compiler, XDBMSGC.
  • XU015: Corrupted file format in file name.
    The file specified could not be entirely read. Check to see if it is the correct file. You may consider trying a backup file name.
  • XU016: Invalid file or path specification.
    The directory you have specified cannot be accessed.
  • XU017: The file FileName does not have correct read/write permissions.
    FileName has permission settings that prevent the software from reading or writing to it.
  • XU018: Invalid drive in search path.
    The drive letter you have specified does not exist.
  • XU020: Maximum of 3 unsuccessful attempts to login.
    You have attempted to log on to a XDB Server using an invalid user ID and/or password three consecutive times, so XDB Server will automatically exit the client application.
  • XU021: More than 15 errors...
    The active program has issued more error messages than this dialog box can display. Only the first 15 are shown.
  • XU022: Invalid server name.
    The string of characters you have entered does not constitute a valid server name. For example, the string contains an illegal character (such as a space) or is too long.
  • XU023: Invalid location name.
    The string of characters you have entered does not constitute a valid location name. For example, the string contains an illegal character (such as a space) or is too long.
  • XU025: Unknown system error. Errno = ErrNumber. Doserrno = DErrNumber.
    An internal error has occurred, and the error number is out of range.
  • XU030: Object name not found in SYSIBM.SYSTABLES while checking if it's an alias.
    An internal operation did not find a record for the requested alias in SYSIBM.SYSTABLES. This usually indicates an inconsistency in your catalog tables.
  • XU031: Object name is not an alias.
    The alias requested by an internal operation is not defined as an alias in the SYSIBM.SYSTABLES. This usually indicates an inconsistency in your catalog tables.
  • XU032: Error Querying SYSTABLES
    An internal operation encountered an error while attempting to get alias information from SYSTABLES.
Parent topic: SQL Option for DB2 Error Messages


User Interface Reference

Restriction: This topic applies to Windows environments only.
  • Bind Utility
  • The Declaration Generator Window
  • Link Utility
  • Migrate Utility
  • Options Utility
  • SQL Wizard
Parent topic: Reference


Bind Utility

Restriction: This topic applies to Windows environments only.
  • Bind Utility Window
  • Bind Package Dialog Box
  • Bind Options Dialog Box
  • Format Options Dialog Box
  • Rebind Package Dialog Box
  • Rebind Options Dialog Box
  • Drop Package Dialog Box
  • Create Default DBRM Dialog Box
Parent topic: User Interface Reference


Bind Utility Window

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Bind Utility window:

Remote Location
The drop-down list contains all the registered remote locations on the XDB Link. You cannot bind, rebind or drop a package until you select a location from this list.

Use the Gateway Profile Utility to register remote locations.

Current SQLID
Specifies the AuthID under which the bind will be executed. By default, your AuthID appears here.
Note: Do not change this field if you are creating the default package for XDB Link. The AuthID used to log on with the Bind Utility must match the primary AuthID on DB2, and must have the authority (in DB2) to run the initial bind.
Continue on Error
Enables the Bind Utility to continue processing when an error occurs.
Bind
To create a default package for XDB Link, or to modify an existing package, click the Bind button.
Rebind
To change options for an existing package without reading the DBRM, click the Rebind button.
Drop
To delete a package from the DB2 location, click the Drop button.
Default
To create a default DBRM, which you will need in order to create the default package for XDB Link, click Default.
Parent topic: Bind Utility
Related information
SQL Option Link Configuration Guide


Bind Package Dialog Box

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Bind Package dialog box:

Bind Location
The Remote Location you selected in the Bind Utility main window. You cannot modify this field. Click Cancel to return to the main window if you need to select a different Remote Location.
Collection Identifier
The Collection ID of the DBRM you select from the DBRM File Name drop-down list. You cannot modify this field.
Package Name
The package name of the DBRM you select from the DBRM File Name drop-down list. The Bind Utility assigns this name to the package it creates. You cannot modify this field.
DBRM File Name
The drop-down list contains all of the DBRMs (.DBR files) in the XDB application directory on your workstation.
Package Version
If you are maintaining multiple versions of a program, assign a different number for each version of the package. This field is optional.
Note:

If the host on which you are binding this package does not support package versions, leave this field blank.

Isolation Level
Controls the manner in which locks are acquired and released by the system.
No Commit
Allows your program to read modified records even if they haven’t been committed by another process.
Change
If you are using a read-only cursor:
  • Allows your program to read modified records even if they haven’t been committed by another process.
  • Allows other processes to change a record that your application reads, even if your cursor is on that record.

If you are using a non-read-only cursor:

  • Prevents your program from reading a modified record that hasn’t been committed by another process.
  • Prevents other processes from changing a record while your cursor is on it.
Cursor Stability
Allows other processes to change a row that your application reads, but does not change, as long as your cursor is not on that row.

Prevents other processes from changing records that your application has changed until your program commits them or terminates.

Prevents your program from reading a modified record that hasn’t been committed by another process.

All
Prevents other processes from changing records that are read or changed by your application until your program commits them or terminates.

Prevents your application from retrieving a modified record that hasn’t yet been committed by another process when it opens a read-only database cursor.

If your program opens the same query during a single unit of work under this isolation level, the results table may differ from the previous one because it may include committed changes from other processes.

Repeatable Read
Prevents other processes from changing records that are read or changed by your application (including phantom records) until your program commits them or terminates.

Prevents the application from reading a modified record that hasn’t been committed by another process.

If your program opens the same query during a single unit of work under this isolation level, the results table will be identical to the previous table. However, it may contain updates made by your program.

No Commit
Allows your program to read modified records even if they haven't been committed by another process.
Change
If you are using a read-only cursor:
  • Allows your program to read modified records even if they haven't been committed by another process.
  • Allows other processes to change a record that your application reads, even if your cursor is on that record.

If you are using a non-read-only cursor:

  • Prevents your program from reading a modified record that hasn't been committed by another process.
  • Prevents other processes from changing a record while your cursor is on it.
Cursor Stability
Allows other processes to change a row that your application reads, but does not change, as long as your cursor is not on that row.

Prevents other processes from changing records that your application has changed until your program commits them or terminates.

Prevents your program from reading a modified record that hasn't been committed by another process.

All
Prevents other processes from changing records that are read or changed by your application until your program commits them or terminates.

Prevents your application from retrieving a modified record that hasn't yet been committed by another process when it opens a read-only database cursor.

If your program opens the same query during a single unit of work under this isolation level, the results table may differ from the previous one because it may include committed changes from other processes.

Repeatable Read
Prevents other processes from changing records that are read or changed by your application (including phantom records) until your program commits them or terminates.

Prevents the application from reading a modified record that hasn't been committed by another process.

If your program opens the same query during a single unit of work under this isolation level, the results table will be identical to the previous table. However, it may contain updates made by your program.

Action
One of the following options:
  • Replace replaces an existing package with a new package. To replace the version label, enter a new label in the Replace Version field in the Bind Options dialog box.
  • Add creates a new package if one does not already exist. If a package with the current Collection ID already exists, the bind process will fail.
Bind
To set optional parameters for the bind, click the Bind button. This command button is available only when you select a file from the DBRM File Name drop-down list.
Format
To specify data formats associated with the selected DBRM, click the Format button. This command button is available only when you select a file from the DBRM File Name drop-down list.
Parent topic: Bind Utility
Related information
Overview


Bind Options Dialog Box

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Bind Options dialog box:

Replace Version | Specifies the new version name for a replacement package. This field is available only when you select the Replace option from the Action drop-down list in the Bind Package dialog box.
Replace Authorization One of the following options:
  • Retain uses the SQLID assigned to the existing package on the host.
  • Revoke uses the current SQLID specified in the Bind Utility window.

This field is available only when you select the Replace option from the Action drop-down list in the Bind Package dialog box.

Creation Control One of the following options:
  • No Error Allowed does not create a package if an error occurs during the bind process.
  • Error Allowed creates a package even if an error occurs during the bind process.
  • Check Only executes the bind without creating a package. Use this option to test the bind operation without actually creating a package.
Existence Checking One of the following options:
  • Optional creates a package even if database objects referenced in the DBRM do not exist. Use this option to create a package prior to defining all data objects.
  • Required creates a package only if all database objects referenced in the DBRM exist.
Blocking Protocol One of the following options:
  • Single Row returns data one row at a time for all cursors that are read-only or are ambiguous. This option provides maximum control of data transfer.
  • Limited Block returns data in blocks (of the size you have specified in the Gateway Profile Utility) for all cursors that are read-only or are ambiguous. This option can improve performance significantly. It provides maximum data-transfer speed. For more information about specifying block size, see your Link Configuration Guide.
  • Forced Single Row returns data one row at a time regardless of the read-only status of the cursor.
Resource Release One of the following options:
  • Commit releases database resources after a commit. Provides a high level of concurrency.
  • Deallocation releases database resources when the connection is terminated.
Explain One of the following options:
  • No Statements disables the EXPLAIN option to create the package without generating descriptive information.
  • All Statements enables the EXPLAIN option to write descriptive information about the package to owner.PLAN_TABLE. This table must exist before you execute the bind.
Package Owner | The AuthID assigned to the package. This DB2 AuthID must have authority to execute all the SQL in the package.
Default Qualifier | The AuthID used to complete any unqualified (one-part) table names in the DBRM file. If you leave this field blank, the Bind Utility uses the current SQLID.
Dynamicrules Controls the behavior of dynamic SQL with regard to one part name qualification and permissions checking:
  • DYNAMIC RULES RUN: The AuthID used for checking permissions of dynamic SQL statements will be the value of the CURRENT SQLID special register. The default value of the CURRENT SQLID special register is the AuthID of the process. Users with SYSADM authority can change their CURRENT SQLID special register to any value and users with secondary AuthIDs can change their CURRENT SQLID special register to be any of their secondary AuthIDs.

    The AuthID used for qualifying one part names of tables, views, etc. will be the value of the CURRENT SQLID special register. As stated above, the special register value can be changed under certain circumstances.

There are no restrictions on commands that can be executed.

  • DYNAMIC RULES BIND: The AuthIDs of the package is used for checking permissions of dynamic SQL statements.

    The value of the Default Qualifier text box will be used for qualifying one part names of tables, views, etc. If the Default Qualifier text box is left blank, the AuthIDs of the package is used for qualifying one part names of tables, views, etc.

    When this option is in effect, you cannot issue the following dynamic SQL statements: ALTER, CREATE, DROP, GRANT, RENAME, and REVOKE.

If left blank, this option defaults to DYNAMIC RULES RUN.

Parent topic: Bind Utility
Related information
SQL Option Link Configuration Guide


Format Options Dialog Box

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Format Options dialog box:

String Delimiter
The type of quotes (single or double) used to represent constant string values that are referenced by the SQL in the DBRM. This option should match the option used to delimit the literal strings referenced by your embedded SQL.
Note: When you are binding the default DBRM for XDB Link, you must use the Single Quote option.
Decimal Delimiter
You must set this field if the DBRM file contains a decimal literal that does not match the host system's default value.
  • Period indicates that the decimal point is represented with a period (for example 3.17).
  • Comma indicates that the decimal point is represented with a comma (for example 3,17).
Default Decimal Precision
One of the following options:
  • 0 uses the system default value.
  • 15 specifies a decimal precision of 15 places.
  • 31 specifies a decimal precision of 31 places.
Default Char Subtype
Options for storing ambiguous character data in the database:
  • System Default specifies the system default value of the DB2 location to which you are binding.
  • SBCS specifies a single-byte character set.
Parent topic: Bind Utility


Rebind Package Dialog Box

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Rebind Package dialog box:

Bind Location
The Remote Location you selected in the Bind Utility main window. You cannot modify this field. Click Cancel to return to the main window if you need to select a different Remote Location.
Collection Identifier
The Collection ID of the package selected from the Package drop-down list. You cannot modify this field.
Package Name
The name of the package selected from the Package drop-down list. You cannot modify this field.
Package
The drop-down list contains all of the packages on the host that are owned by the current SQLID.
Package Version
If you are maintaining multiple versions of a program, assign a different number for each version of the package. This field is optional.
Note: If the host on which you are binding this package does not support package versions, leave this field blank.
Isolation Level
Controls the manner in which locks are acquired and released by the system.

The options are:

No Commit
Allows your program to read modified records even if they haven’t been committed by another process.
Change
If you are using a read-only cursor:
  • Allows your program to read modified records even if they haven’t been committed by another process.
  • Allows other processes to change a record that your application reads, even if your cursor is on that record.

If you are using a non-read-only cursor:

  • Prevents your program from reading a modified record that hasn’t been committed by another process.
  • Prevents other processes from changing a record while your cursor is on it.
Cursor Stability
Allows other processes to change a row that your application reads, but does not change, as long as your cursor is not on that row.

Prevents other processes from changing records that your application has changed until your program commits them or terminates.

Prevents your program from reading a modified record that hasn’t been committed by another process.

All
Prevents other processes from changing records that are read or changed by your application until your program commits them or terminates.

Prevents your application from retrieving a modified record that hasn’t yet been committed by another process when it opens a read-only database cursor.

If your program opens the same query during a single unit of work under this isolation level, the results table may differ from the previous one because it may include committed changes from other processes.

Repeatable Read
Prevents other processes from changing records that are read or changed by your application (including phantom records) until your program commits them or terminates.

Prevents the application from reading a modified record that hasn’t been committed by another process.

If your program opens the same query during a single unit of work under this isolation level, the results table will be identical to the previous table. However, it may contain updates made by your program.

Bind
To set optional parameters for the package you are rebinding, click the Bind button.
Parent topic: Bind Utility
Related information
Overview


Rebind Options Dialog Box

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Rebind Options dialog box:

Existence Checking
One of the following options:
  • Optional creates a package even if database objects referenced in the DBRM do not exist. Use this option to create a package prior to defining all data objects.
  • Required creates a package only if all database objects referenced in the DBRM exist.
Resource Release
One of the following options:
  • Commit releases database resources after a commit. Provides a high level of concurrency.
  • Deallocation releases database resources when the connection is terminated.
Explain
One of the following options:
  • No Statements disables the EXPLAIN option to create the package without generating descriptive information.
  • All Statements enables the EXPLAIN option to write descriptive information about the package to owner.PLAN_TABLE. This table must exist before you execute the bind.
Package Owner
The AuthID assigned to the package. This DB2 AuthID must have authority to execute all the SQL in the package.
Default Qualifier
The AuthID used to complete any unqualified (one-part) table names in the DBRM file. If you leave this field blank, the Bind Utility uses the current SQLID.
Parent topic: Bind Utility


Drop Package Dialog Box

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Drop Package dialog box:

Bind Location
The Remote Location you selected in the Bind Utility main window. You cannot modify this field. Click Cancel to return to the main window if you need to select a different Remote Location.
Collection Identifier
The Collection ID of the package selected from the Package drop-down list. You cannot modify this field.
Package Name
The name of the package selected from the Package drop-down list. You cannot modify this field.
Package Name
The drop-down list contains all of the packages on the host that are owned by the current SQLID.
Parent topic: Bind Utility


Create Default DBRM Dialog Box

Restriction: This topic applies to Windows environments only.

The following fields and controls are used in the Create Default DBRM dialog box:

Collection ID
The Default Collection ID value you specified in the Gateway Profile utility when you configured XDB Link for the mainframe location.
Package Name
The default Package Name you specified in the Gateway Profile utility when you configured XDB Link for the mainframe location.
Host System
The drop-down list contains options for specifying the type of host system to which you want to bind XDB Link.
Dynamic Sections
The number of statements that the XDB Link package can prepare for a single user.
Parent topic: Bind Utility
Related information
SQL Option Link Configuration Guide


The Declaration Generator Window

Restriction: This topic applies to Windows environments only.

The following fields and controls in the Declaration Generator window are used to create declaration files in COBOL, C or PL/I.

Generate | Generates a declaration file according to the specifications that have been defined in the Declaration Generator window.
Save As Saves the current specifications to a .DGE file. A .DGE file can be used as input to the Declaration Generator when it is run in batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.

If you specify the name of an existing .DGE file, you will be asked whether the current specification should replace the existing file or be appended to it.
Options | Allows you to set options that are specific to the language you have selected.
Exit | Closes the Declaration Generator window.
Location | Specifies the location of the table.
AuthID Specifies the access authority under which you will access the table. In order to create a declaration file, you must have SELECT privileges on the table for which you are generating a declaration, and on the following system tables:
  • SysIBM.SYSLOCATIONS
  • SysIBM.SYSTABLES
  • SysXDB.SYSACFUsers
Table Name | Identifies the table for which the declaration file will be generated.
Declaration | The fields in this group box determine how the declaration file is written.
Output File Specifies the file to which the declaration statements will be written. If you do not specify a path, the file is written to the application path (specified in the PATHS tab in Options) when you select C, or the value of the COBCPY environment variable when you select COBOL or PL/I.

A default file name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.

If you specify a file that already exists, you will be prompted at run time to choose whether you want to replace the existing file or append the statements to it.
Structure Name | Specifies the name of the record definition (COBOL), structure (C) or declaration structure (PL/I) written to the declaration file. A default name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.
Language | The LANGUAGE group box is used to select the programming language in which you want the declaration written. You can select COBOL, C or PL/I.
Text Assign a prefix to each field name as it is written into the declaration file. The following shows how field names would be treated if a prefix of emp_ were used.

Remember to take into account your compiler's variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the programming language or that make the variable's name too long.
Generate | Generates a declaration file according to the specifications that have been defined in the Declaration Generator window.
Save As Saves the current specifications to a .DGE file. A .DGE file can be used as input to the Declaration Generator when it is run in batch mode. See Running in Batch Mode for more information about .DGE files and batch mode.

If you specify the name of an existing .DGE file, you will be asked whether the current specification should replace the existing file or be appended to it.
Options | Allows you to set options that are specific to the language you have selected.
Exit | Closes the Declaration Generator window.
Location | Specifies the location of the table.
AuthID Specifies the access authority under which you will access the table. In order to create a declaration file, you must have SELECT privileges on the table for which you are generating a declaration, and on the following system tables:
  • SysIBM.SYSLOCATIONS
  • SysIBM.SYSTABLES
  • SysXDB.SYSACFUsers
Table Name | Identifies the table for which the declaration file will be generated.
Declaration | The fields in this group box determine how the declaration file is written.
Output File Specifies the file to which the declaration statements will be written. If you do not specify a path, the file is written to the application path (specified in the PATHS tab in Options) when you select C, or the value of the COBCPY environment variable when you select COBOL or PL/I.

A default file name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.

If you specify a file that already exists, you will be prompted at run time to choose whether you want to replace the existing file or append the statements to it.
Structure Name | Specifies the name of the record definition (COBOL), structure (C) or declaration structure (PL/I) written to the declaration file. A default name is automatically created based on the name of the table you select and the language you specify. You can change this name by typing a new one in this field.
Language | The LANGUAGE group box is used to select the programming language in which you want the declaration written. You can select COBOL, C or PL/I.
Text Assign a prefix to each field name as it is written into the declaration file. The following shows how field names would be treated if a prefix of emp_ were used.

Remember to take into account your compiler's variable-naming guidelines when assigning a prefix. Do not assign one containing characters that are disallowed by the programming language or that make the variable's name too long.
Numbered | Replaces a field name with a number in the declaration file. This option can be selected only when a field prefix is assigned in the TEXT field. The following example shows how field names would be treated if the NUMBERED option were set with a prefix of emp_.
If the Field name is... | It will be written as...
ssn | emp_ssn
lname | emp_lname
fname | emp_fname
If the Field name is... | It will be written as...
ssn | emp_001
lname | emp_002
fname | emp_003
 | Numbered | Replaces a field name with a number in the declaration file. This option can be selected only when a field prefix is assigned in the TEXT field. The following example shows how field names would be treated if the NUMBERED option were set with a prefix of emp_.
Computation | Specifies the internal storage format assigned to binary integers in a COBOL record description. The choices are COMP, COMP-4 and COMP-5.
Computation Specifies the internal storage format assigned to binary integers in a COBOL record description. The choices are COMP, COMP-4 and COMP-5.
Parent topic: User Interface Reference


Link Utility

Restriction: This topic applies to Windows environments only.
  • Gateway Facility Main Window Options
  • Location Configuration Window
  • Workstation Configuration Window
Parent topic: User Interface Reference


Gateway Facility Main Window Options

Restriction: This topic applies to Windows environments only.

Select the task you need to perform, or click Close to close this window and exit the Gateway Profile Utility. If you are configuring the Link on a machine where the XDB Server is installed, the Status field shows the status of your connection to the server.

Register... Displays the Location Configuration window, which you use to add, modify, and delete remote locations. Each remote data location (including the location for Password Expiration Manager) must be configured with the Gateway Profile utility before it can be accessed through the Link.
Local... Displays the Workstation Configuration window, which you use to configure the:
  • Code pages the Link uses to translate data
  • Number of clients that can connect to a data source through the Link
  • Settings that control client conversations with the host
Parent topic: Link Utility
Related information
Location Configuration Window
Workstation Configuration Window


Location Configuration Window

Restriction: This topic applies to Windows environments only.

Use the Location Configuration window to:

  • Define a new remote location to the Link
  • Modify an existing definition for a remote location
  • Delete an existing definition for a remote location

You must define a remote location to the Link before client applications can access the data in that location. Remote locations include data sources such as DB2 subsystems and other XDB Servers. If you plan to use XDB's Password Expiration Manager (PEM), you must configure a connection between the Link and the PEM module on the mainframe by defining a remote location.

To open the Location Configuration window, click Register on the main window of the Gateway Profile Utility.

The Location Configuration window is divided into the following sections:

  • General controls (those with no label) and Host Code Pages settings apply to all location types.
  • APPC Setup applies only to DRDA(APPC) and PEM(APPC) connection types.
  • TCP/IP Setup applies only to DRDA(TCP/IP), XDBHOST, and PEM(TCP/IP) connection types.
  • DRDA Setup applies only to DRDA(APPC) and DRDA(TCP/IP) connection types.
Parent topic: Link Utility
Related information
Gateway Facility Main Window Options
Workstation Configuration Window


Workstation Configuration Window

Restriction: This topic applies to Windows environments only.

Use the Workstation Configuration window to configure settings that XDB Link uses to control conversations between the client application and the host system.

To access the Workstation Configuration window, click Local in the Gateway Profile Utility window.

Workstation Code Pages

The values in this group box specify the code pages that represent the national-language format for client workstations using XDB Link. If you are using English (US) machines, leave these settings at their default values. For any other language, enter the code page value for that language. If you are using the XDB Server as your gateway server, you must restart the XDB Server after changing any code page values.
Single Specify the single-byte code page value for client machines connecting to the host through XDB Link. XDB Link converts single-byte character data received from the host through this code page before sending it to the client workstation. It also uses this as the code page identifier for single-byte character data that it transmits to the host. The default is 850.

If you connect through a gateway server, enter the PC's OEM code page. In the United States, the default is 437.

If you connect as a direct client to DB2, enter the ANSI code page value. In the United States, the default is 1252.

If you use binary data or for bit data fields with COBOL programs, set the single code page setting to 911. If you are using the 911 code page while connected to a DB2 host and want to connect to a DB2 host which uses a different code page than that of the current DB2 host, you must restart the server prior to connecting to the new host.

To determine your PC's OEM and ANSI code page settings: at a DOS prompt, change (cd) to the install directory and type codepage.
Mixed | Specify the mixed-byte code page value for client machines connecting to the host through XDB Link. XDB Link converts mixed-byte character data received from the host through this code page before sending it to the client workstation. It also uses this as the code page identifier for mixed-byte character data that it transmits to the host. The default is 932.
Double | Specify the double-byte code page value for client machines connecting to the host through XDB Link. XDB Link converts double-byte character data received from the host through this code page before sending it to the client workstation. It also uses this as the code page identifier for double-byte character data that it transmits to the host. The default is 301.
Close Conversation | Select the setting that determines when XDB Link closes an LU 6.2 conversation. At Dealloc closes the conversation when the client application terminates. At Commit closes the conversation after the client application executes a COMMIT statement. Use the default value, At Dealloc, unless you are tuning the system for OLTP applications or you want to prevent an application from tying up host resources when a client leaves it idle for an extended period of time.
Maximum Clients | Specify the maximum number of concurrent client sessions that XDB Link can carry. Permitted values are 1 to 128. For an XDB Server, select a value that will comfortably accommodate the number of users that will simultaneously access the host system through XDB Link. In a Direct Configuration, use a small value to reduce XDB Link's memory requirements (unused client sessions needlessly consume memory on your machine).
User Buffer Size Specify the size (in kilobytes) of the bulk packet that XDB Link uses to download data from the host. Permitted values are 1 to 63. For most environments, the default value is sufficient. However, adjusting the value can optimize certain client applications:
  • For client applications that frequently download large amounts of data, a large buffer size can improve response time.
  • For client applications that perform brief, online transactions, a small buffer will maximize memory on the machine where XDB Link is installed.
Parent topic: Link Utility
Related information
Gateway Facility Main Window Options
Location Configuration Window


Migrate Utility

Restriction: This topic applies to Windows environments only.
  • The Migrate Window
  • The Table Tab
  • The Query Tab
  • The Migrate Options Dialog Box
  • The Migrate Database Dialog Box
  • The Table Options Dialog Box
  • The Run Dialog Box
  • The Default Options Dialog Box
  • The Query Options Dialog Box
  • The Query Update Rules Dialog Box
  • The Control Menu
  • The File Menu
  • The Edit Menu
  • The View Menu
  • The Object Menu
  • The Commands Menu
  • The Options Menu
  • The Help Menu
  • The Window Menu
Parent topic: User Interface Reference


The Migrate Window

Restriction: This topic applies to Windows environments only.

Once a connection to a server is established, the Migrate window appears. This window contains tools and controls for selecting source tables, specifying a destination and setting migration parameters.

The Menu bar contains Migrate commands you can use to specify migrate options and launch a migration. For a description of each command on the Menu bar, see The Migrate Menus.

The Toolbar contains the following icons that provide quick access to a particular command or function.

Icon | Description
* | Opens the Catalog Browser if it is not already open. If the Catalog Browser is open, this button refreshes its contents.
* | Lets you specify options for the selected table or a query.
* | Runs a migration of the specified tables using the specified parameters.
* | Opens Migrate help.

The Catalog Browser is used to select tables and queries that you want to migrate to another location (i.e., specify the source tables or queries). For more information about the Catalog Browser, see The Catalog Browser.

The Schema Viewer graphically displays the source tables that have been selected for migration. From this window, you can set options, and display dependent and referenced tables. For more information about the Schema Viewer, see The Schema Viewer.

Parent topic: Migrate Utility


The Table Tab

Restriction: This topic applies to Windows environments only.

*
Use the Table tab in the Catalog Browser to locate and select the tables you want to migrate. To show tables in the Browser, click the Table tab on left side of the Catalog Browser window.

To locate a table, click the + buttons to expand the database hierarchy until the table name appears.

To select a table for migration, do one of the following:

  • double-click the table name in the Catalog Browser, or
  • highlight the table name, then drag it into the Schema Viewer.

If you want to select multiple tables, hold the Ctrl or Shift key when you click the table name. Shift lets you select a group of consecutive names in the listCtrl lets you select multiple, non-consecutive names.

For information about migrating tables that you have placed in the Schema Viewer, see Migrating Tables.

Parent topic: Migrate Utility


The Query Tab

Restriction: This topic applies to Windows environments only.

*
Use the Query tab in the Catalog Browser to recall a saved query that has been created with a data management tool such as SQLWizard. For information about using a query during a migration, see Migrating Certain Rows and Columns.

To view a list of the available saved queries, click the Query tab on the left side of the Browser window.

To locate a query, click the + buttons to expand the database hierarchy until the query name appears.

To recall a saved query from the Query tab, do one of the following:

  • double-click the query name, or
  • highlight the query name, then drag it into the Schema Viewer.

The recalled query is displayed in the Query window. You can edit the query or accept it as is.

Note:

If your recalled query contains SQL statements besides SELECT, we recommend that you remove them before running the migration. The Query window should contain only a single SELECT statement to specify the data that is to be migrated to another table. For more information about migrating data from a query, see Migrating Certain Rows and Columns.

Parent topic: Migrate Utility


The Migrate Options Dialog Box

Restriction: This topic applies to Windows environments only.

The Migrate Options dialog box is used to set the default migration options that appear in the Run dialog box when you perform a migration.

The Migrate Options dialog box contains the following controls:

The Output group box

Use this to select defaults for migration output. You can also control whether to execute the migration or not.

Impact Analysis Report
Sets the Impact Analysis Report as a default migration option. The Impact Analysis Report provides detailed information on the tables that will be affected by the migration as it is currently specified. This report is used to analyze the effect of a migration without actually executing it.
Attention: If this report is selected, Migrate will not migrate any information.
Generate SQL
Saves the SQL script file that processes your migration as a default migration option. In the field next to the checkbox, type the name of the file to which you want the SQL script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new script.
Post Execution Report
Sets the Post Execution Analysis Report as a default migration option This report generates a listing of the source and destination tables that are a part of the migration. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

Attention: If the Impact Analysis Report checkbox is selected, you can not run a Post Execution Analysis Report.
Error File
Sets the Error File as a default migration option. The error file records migration errors. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report.

You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.

Browse
Use the Browse button to view a list of filenames on your system. If you want to use an existing file for output, you can select its name from the list.

The Input Files group box

Use this to specify SQL files to be executed during your migration.

Prologue
Causes Migrate to process an SQL script file before it processes the specified tables and queries. In the field next to the checkbox, type the name of the SQL script file to be used.
Epilogue
Causes Migrate to process an SQL script file after it processes the specified tables and queries. In the field next to the checkbox, type the name of the SQL script file to be used.
Parent topic: Migrate Utility


The Migrate Database Dialog Box

Restriction: This topic applies to Windows environments only.
Database list | Lists all of the databases defined to SQL Option for DB2.
Migrate Tables list | Lists all of the tables defined in the database or databases selected on the Database list.
Exclude button | Click this to exclude any tables selected on the Migrate Tables list, moving the table name down to the Not Included list.
Options button | Click this to set table options for the selected tables.
Add button | Click this to add tables selected on the Not Included list back to the Migrate Tables list.
Save button | Click this to generate a .mig script file containing the migration information set on this dialog box.
Execute button | Click this to invoke the Run dialog box, where you specify a location to migrate to and kick off the migration process.
Parent topic: Migrate Utility


The Table Options Dialog Box

Restriction: This topic applies to Windows environments only.

The Table Options dialog box is used to specify destination parameters and define objects you want migrated with the selected table. You can also use this dialog box to determine how to handle duplicate migrations and how to commit data records.

The Table Options dialog box contains the following controls:

Source | Displays information about the selected source table.
AuthID | Displays the owner of the source table.
Table | Displays the name of the source table.
Tbl Space | Displays the table space name for the source table.
Database | Displays the name of the database the source table was selected from.
Destination | Use the Destination group box to specify information about the destination table.
Auth ID Enter the AuthID associated with the destination table. Changing this field assigns a new owner to the destination table.

If you want Migrate to use the source table's Auth ID by default, select the Default To Source checkbox next to the Auth ID text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify an Auth ID by typing it in text box.

Table | Enter a name for the destination table.
Tbl Space Enter the table space name for the destination table.

If you want Migrate to use the name of the source table space by default, select the Default To Source checkbox next to the Tbl Space text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a table space name by typing it in this text box.

Database Enter the database name for the destination table.

If you want Migrate to use the name of the source database from which the source table is selected by default, select the Default To Source checkbox next to the Database text box in the Default Options dialog box before you select Table Options; Migrate will then automatically populate this field with the proper default value. Otherwise, you will need to specify a database name by typing it in this text box. If this field is left blank, the default database name "DSNDB04" is used.

Primary Key | Select this checkbox if you want primary-key columns in the source table to also be primary-key columns in the destination table.
Unique Keys | Select this checkbox if you want unique-key columns in the source table to also be unique-key columns in the destination table.
Indexes | Select this checkbox if you want the index key in the source table to also be the index key in the destination table.
Foreign Keys | Select this checkbox if you want foreign-key columns in the source table to also be foreign-key columns in the destination table.
Synonyms | Select this checkbox if you want any alternate names for the source table to also be alternate names for the destination table.
Comments | Select this checkbox to migrate comments in the source table to be included on the destination location table.
Privileges | Select this checkbox to migrate privileges. The privileges checkbox lets you place the same security standards on the destination tables as on the source tables.
If Table Already Exists | Use the If Table Already Exists group box to specify what Migrate should do if the table you are migrating already exists at its destination.
Abort | Select this option if you want Migrate to terminate the migration if the destination table already exists.
Append Data Select this option if you want Migrate to append the new table to the existing destination table. If the destination table has no primary key, all records are appended to the destination. You can use this option with the No Data option (see below) to migrate just an index.
Note:

You can end up with duplicate records if you use this option on a table without a primary key.
Replace Data | Select this option if you want Migrate to replace all existing records in the destination table with records from the source table. All data in the existing table will be deleted.
Replace Table | Select this option if you want Migrate to drop the destination table and create a new table containing the result of this migration.
Data Options | Use the Data Options group box to specify how much data should be migrated and to specify a commit rate.
Limit Data To Select the number of records you want to copy.
  • Select All Rows to migrate all data records from the source table to the destination.
  • Select No Data to migrate none of the records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature. Or, you might use it to copy certain table attributes without copying any data.

    The behavior of this option depends on the following:

    • If the destination table does not exist, an "empty" table is created.
    • If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).
    • If the destination table exists, and the Append Data option is used, no records are copied to it (you could use this combination of options to copy just an index).
  • Select First N Rows if you only want to migrate the first N records from the source table to the destination.
  • Select Every Nth Row if you want to copy every N records from the source table to the destination.
Commit Work After

Specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). You can specify any number between 0 and 32,767. High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
Parent topic: Migrate Utility


The Run Dialog Box

Restriction: This topic applies to Windows environments only.

Use the Run dialog box to execute the currently specified migration. It also can specify certain options for the migration before you begin, and optionally select scripts that can be executed before and/or after the migration is processed. Clicking OK in this dialog starts the migration.

The Run dialog box contains the following controls:

Migrating | Displays the source and destination of the migration. If the destination is not displayed or is incorrect, change it in the To entry box .
 | From | Displays the location of the source table(s). If you have placed tables in the Schema Viewer, this field displays the location of these tables. Note: If you are migrating tables from the Schema Viewer do not change this field. Changing the From field will clear the Schema Viewer.
 | To | Select the location to which you want the selected tables and/or query results migrated. Note: The destination location must exist in order to migrate a table to it. If it does not, you must first create it using a database management tool such as SQLWizard.
Migrate Options | Use Migrate Options to select the reports and files you want Migrate to produce.
 | Execute Migrate | Determines whether or not any data is migrated when you run a migration. When enabled, Migrate performs a normal migration. When disabled, Migrate executes the migration but does not actually copy any data to the specified destination. This lets you obtain an SQL stream without actually migrating any data. Note: If this checkbox is selected, you cannot generate an Impact Analysis Report.
 | Impact Analysis | Select this checkbox to generate a report that provides detailed information about the migration as it is currently specified. This report lets you analyze the effect of a migration without actually executing it. Type the name of the file to which you want the report written in the field next to the checkbox. Note: When this report is selected, Migrate will not create or copy any information. The entire migration, including queries is executed step-by-step, but no tables are created and no data is written.
 | Generate SQL | Select this checkbox if you want to save the SQL that processes your migration. In the field next to the checkbox, type the name of the file to which you want the SQL script written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new script.
 | Post Execution Analysis Report | Select this checkbox to generate a listing of the source and destination tables that are part of the migration. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report. You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.
 | Error File | Select this checkbox to record migration errors in a file. In the field next to the checkbox, type the name of the file to which you want the report written. If this file does not exist, Migrate creates it. If it exists, Migrate overwrites it with the new report. You can specify the same file name for the Post Execution Report and the Error File to combine these two reports into one file.
Parent topic: Migrate Utility


The Default Options Dialog Box

Restriction: This topic applies to Windows environments only.

The Default Options dialog box is used to assign default migration options for tables and queries.

The Default Options dialog box contains the following controls:

Destination | The options in this group box specify the default destination information for the selected table or query.
Auth ID Enter the AuthID associated with the destination table. Changing this field assigns a new owner to the destination table.

Select the Default To Source checkbox next to this field to indicate that you want to use the source table's Auth ID by default.

Tbl Space Enter the table space name for the destination table.

Select the Default To Source checkbox next to this field to indicate that you want to use the name of the source table space by default.

Database Enter the database name for the destination table.

Select the Default To Source checkbox next to this field to indicate that you want to use the name of the source database by default.

If Table Already Exists | Use the If Table Already Exists group box to specify what Migrate should do if the table you are migrating already exists at its destination.
Abort | Select this option if you want Migrate to terminate the migration if the destination table already exists.
Append Data Select this option if you want Migrate to append the new table to the existing destination table. If the destination table has no primary key, all records are appended to the destination. You can use this option with the No Data option (see below) to migrate just an index.
Note:

You can end up with duplicate records if you use this option on a table without a primary key.
Replace Data | Select this option if you want Migrate to replace all existing records in the destination table with records from the source table. All data in the existing table will be deleted.
Replace Table | Select this option if you want Migrate to drop the destination table and create a new table containing the result of this migration.
Limit Data To Select the number of records you want to copy.
  • Select All Rows to migrate all data records from the source table to the destination.
  • Select No Data to migrate none of the records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature. Or, you might use it to copy certain table attributes without copying any data.

    The behavior of this option depends on the following:

    • If the destination table does not exist, an "empty" table is created.
    • If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).
    • If the destination table exists, and the Append Data option is used, no records are copied to it (you could use this combination of options to copy just an index).
  • Select First N Rows if you only want to migrate the first N records from the source table to the destination.
  • Select Every Nth Row if you want to copy every N records from the source table to the destination.
Commit Work After | Specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). You can specify any number between 0 and 32,767. High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
Migrate

Use the Migrate group box to select the objects you want to migrate with a table.
Primary Key | Select this checkbox if you want primary-key columns in the source table to also be primary-key columns in the destination table.
Unique Keys | Select this checkbox if you want unique-key columns in the source table to also be unique-key columns in the destination table.
Indexes | Select this checkbox if you want the index key in the source table to also be the index key in the destination table.
Foreign Keys | Select this checkbox if you want foreign-key columns in the source table to also be foreign-key columns in the destination table.
Synonyms | Select this checkbox if you want any alternate names for the source table to also be alternate names for the destination table.
Comments | Select this checkbox to migrate comments in the source table to be included on the destination location table.
Privileges | Select this checkbox to migrate privileges. The privileges checkbox lets you place the same security standards on the destination tables as on the source tables.
Distinct Type | Select this checkbox to migrate distinct types used by the source table.
Parent topic: Migrate Utility


The Query Options Dialog Box

Restriction: This topic applies to Windows environments only.

The Query Options dialog box is used to specify how you want the results of a query migrated. For example, you can specify what action Migrate should take if the destination table already exists, or how many total records from the result should be copied.

The Query Options dialog box contains the following controls:

Destination | This group box displays the destination information for the selected query.
Auth ID | Enter the AuthID associated with the table produced by the query.
Table | Enter a table name for the table produced by the query.
Tbl Space Enter the table space name for the result of the query.

If a table space name isn't specified, the destination table name is used.
Database Enter the database name for the table produced by the query.

If a database name isn't specified, the default database name "DSNDB04" is used.
If Table Already Exists | Use the If Table Already Exists group box to determine what to do if the there is an existing table with the same name as the table produced by the query.
Abort | Select this option if you want Migrate to terminate the migration if the destination table already exists.
Append Data Select this option if you want Migrate to append the new table to the existing destination table. If the destination table has no primary key, all records are appended to the destination. You can use this option with the No Data option (see below) to migrate just an index.
Note:

You can end up with duplicate records if you use this option on a table without a primary key.
Replace Data | Select this option if you want Migrate to replace all existing records in the destination table with records from the source table. All data in the existing table will be deleted.
Replace Table | Select this option if you want Migrate to drop the destination table and create a new table containing the result of this migration.
Update No Insert | Select this option if you want Migrate to update data only if the row with they key already exists.
Update Insert | Select this option if you want Migrate to update existing data or insert the row if it doesn't already exist.
Delete Match | Select this option if you want Migrate to delete an existing matching row.
Limit Data To Select the number of records you want to copy.
  • Select All Rows if you want to migrate all data records of the query result.
  • Select No Data to migrate none of the records from the source table to the destination. You might use this option to create an "empty" destination table (which will have a structure identical to the source) into which you can selectively copy records using Migrate's query feature. Or, you might use it to copy certain table attributes without copying any data.

    The behavior of this option depends on the following:

    • If the destination table does not exist, an "empty" table is created.
    • If the destination table exists, and the Replace Data or Replace Table option is used, the destination table's existing records are deleted and no records are copied (an "empty" table is created).
    • If the destination table exists, and the Append Data option is used, no records are copied to it (you could use this combination of options to copy just an index).
  • Select First N Rows if you only want to migrate the first N records from the source table to the destination.
  • Select Every Nth Row if you want to copy every N records from the source table to the destination.
Commit Work After | Specify the number of records Migrate should accrue before permanently writing them to disk (i.e., issuing a COMMIT statement). You can specify any number between 0 and 32,767. High Commit Work After values produce a faster migration but result in fewer records successfully written should the migration be interrupted.
Parent topic: Migrate Utility


The Query Update Rules Dialog Box

Restriction: This topic applies to Windows environments only.

The Query Update Rules dialog box appears when you click the Update Rule button from the Query dialog box. It is available only if you chose the Update No Insert or Update Insert options in the Query Options dialog box. Use this window to specify the key field, and to select specific update rules for each field in the selected row.

Parent topic: Migrate Utility


The Control Menu

Restriction: This topic applies to Windows environments only.

Each table in the Schema Viewer has a Control menu you can use to set table options, select referenced tables and remove a table from a migration. Click the table's Control-menu button to select these commands.

The Control menu contains the following commands:

Table Options Specifies the table's destination parameters and to define objects you want migrated with the table. You can also use this command to specify how to handle duplicate migrations and how to commit data records.

Each table in a migration has its own distinct set of table options. You can use the Table/Query Defaults command on the Options menu to set default table options for your migration.

The Table Options command performs the same function as the Table/Query Options command on the Object menu.
Migrate Determines whether the table is migrated or not. A check mark next to the Migrate command includes the table in the migration. If you deselect the Migrate command (i.e., remove the check mark), the table remains in the Schema Viewer, but is excluded from the migration.
Show Dependent Automatically migrates any table that references the selected table. When you select this command, Migrate automatically places this table's dependent tables in the Schema Viewer.

This Show Dependent command performs the same function as the Show Dependent command on the Object menu.
Show Referenced Automatically migrates any table that is referenced by this table. When you select this command, Migrate automatically places this table's referenced tables in the Schema Viewer.

This Show Referenced command performs the same function as the Show Referenced command on the Object menu.
Remove Takes the table out of the Schema Viewer. If a table is removed from the Schema Viewer, it is not included in the migration. (Only tables within the Schema Viewer are migrated.)

This Remove command performs the same function as the Remove command on the Object menu.
Parent topic: Migrate Utility


The File Menu

Restriction: This topic applies to Windows environments only.

The File menu contains commands for opening new or existing migrate files, (MIG), and other objects, as well as for printing and saving. The Exit command is located under this menu.

The File menu contains the following commands:

New | Opens a new Schema Viewer window. If a Schema Viewer is already open, it is closed before the new one is opened.
Open Displays a dialog box to open existing migration (MIG) files.

When you open a MIG file, the specifications from the file replace the current migrations specifications. If you want to preserve your current specifications, save them using the Save or Save As command before opening a MIG file.
Close | Closes the active window.
Save Saves your current Migrate specifications to the open MIG file. (A MIG file records your table, query and option choices so that you can rerun a migration without having to respecify it manually.)
Note:

You must activate the Schema Viewer to use the Save command. If the Catalog Browser or a Query window is active, the Save command is grayed.

If Migrate specifications have not yet been saved, the Save command displays the Specify Batch File dialog box for you to specify a directory and file name.

Migrate specifications can be saved only after you have completed the Table Options dialog box.
Save As Displays the Save As dialog box to save the current Migrate specifications to a new MIG file. (A MIG file records your table, query and option choices so that you can rerun a migration without having to respecify it manually.)

The Save As command can also be used to save the contents of a Query window to an SQL file. If a Query window is active when you select Save As, you can select *.SQL in the List Files of Type field to save the active query to an SQL script file, or you can select *.MIG to save all migration specifications to a MIG file.

Migrate specifications can be saved only after you have completed the Table Options dialog box.
Execute Batch Runs a migration that has been saved to a MIG file. This command displays the Select Batch File dialog box from which you can select the MIG file you want to run. When you click OK, the migration is immediately executed.

Running a migration with the Execute Batch command does not affect the current migration specifications.

Print Prints the contents of the active window. The contents of the Query window, the SQL window and Migrate report windows (such as an Impact Analysis Report) can be printed. To print a Migrate report, you must first open it using the report commands on the View menu (e.g., the Post Execution Analysis command).

Selecting Print displays a dialog box, letting you specify the pages and number of copies you want to print.
Exit | Exits the program. Before exiting, Migrate prompts you to save any open windows that have changed.
Parent topic: Migrate Utility


The Edit Menu

Restriction: This topic applies to Windows environments only.

The Edit menu allows you to cut, copy and paste data to and from the Query window.

The Edit menu contains the following commands:

Cut | Removes statements from the SQL window or the Query window and copies them to the Clipboard.
Copy | Copies statements from the Query window to the Clipboard.
Paste | Pastes statements from the Clipboard into the Query window.
Parent topic: Migrate Utility


The View Menu

Restriction: This topic applies to Windows environments only.

The View menu lets you redisplay the Catalog Browser if it has been closed. It also lets you display Migrate reports. Once a migration report is displayed, you can print it by selecting Print on the File menu.

The View menu contains the following commands:

View Browser | Displays the Catalog Browser. You can also use the View Browser * button on the toolbar to invoke this command.
Refresh Browser | Refreshes the contents of the Catalog Browser. You must do this at the end of a migration to display the names of the newly-migrated tables.
Impact Analysis | Displays the Impact Analysis Report. To display a report other than the last one, specify the file using Migrate on the Options menu before you select Impact Analysis. You can review this report online or print it using Print on the File menu.
Post Execution Analysis | Displays the Post Execution Analysis Report generated by the last migration. This report displays an analysis of the migration after you execute a migration. To display a report other than the last one, specify the file using Migrate on the Options menu before you select Post Execution Analysis. You can review this report online or print it using Print on the File menu.
SQL | Opens and views an SQL script file. Once a script is open, you can print it or cut and paste it to a Query window.
Batch Commands | Enables you to view the contents of a MIG file. A MIG file contains complete specifications for running a migration. A MIG file can be recalled using Open on the File menu; it can be executed using Execute Batch on the File menu or by calling it from your system command line.
Error File | Displays the error file generated by the last migration. To display a report other than the last one, specify the file using Migrate on the Optionsmenu before you select Error File. You can review this report online or print it using Print on the File menu.
Parent topic: Migrate Utility


The Object Menu

Restriction: This topic applies to Windows environments only.

The Object menu provides different commands for manipulating tables, such as, defining defaults, displaying related tables, and how tables are to be displayed. It is also used to define a query.

The Object menu contains the following commands:

Define Query | Opens a Query window. Using this window, you can define a specific SELECT statement to migrate certain rows or columns of a table or to combine data from different tables into one result.
Table/Query Options | Displays the Table Options or Query Options dialog box (depending on whether a Query window or a table in the Schema Viewer is active). Use this command to set specific options for the selected table or query window. Note: To set default options for all subsequent tables and queries, use Table/Query Defaults on the Options menu.
Show Dependent | Automatically places in the Schema Viewer all tables that are dependent on the selected table. You can also invoke this command from the table's Control-menu * button.
Show Referenced | Automatically places in the Schema Viewer all tables that are referenced by the selected table. You can also invoke this command from the table's Control-menu * button.
Remove | Removes the selected table from the Schema Viewer. You can also invoke this command from the table's Control-menu * button.
Roll Up | Displays tables in the Schema Viewer in abbreviated form. When rolled-up, tables are represented by just a table name. Column information is not shown.
Roll Down | Displays tables in the Schema Viewer in detailed form. When rolled-down, the names of columns are listed with the table.
Arrange | Arranges the tables within the Schema Viewer so that lines of reference can be easily seen.
Parent topic: Migrate Utility


The Commands Menu

Restriction: This topic applies to Windows environments only.

The Commands menu allows you to execute a migration or a query.

The Commands menu contains the following commands (applies to Windows environments only):

Run | Migrates the selected tables and query results. The Run command is available only when a table in the Schema Viewer is selected. You can also use the Run * button on the toolbar to invoke the Run command.
Run SQL | Executes the SQL in the open Query windows without migrating tables that are in the Schema Viewer. Queries are executed in Query window order. The Run SQL command is available only when a Query window is selected.
Parent topic: Migrate Utility


The Options Menu

Restriction: This topic applies to Windows environments only.

The Options menu lets you set default options for migrations.

The Options menu contains the following commands:

Migrate | Displays the Migrate Options dialog box. Use this dialog box to select default migration options. Choices selected on this dialog box will be reflected in the Run dialog box
Table/Query Defaults | Displays the Default Options dialog box. Use this dialog box to set default migrate options. Note: The Table/Query Defaults command does not affect the option settings for tables already in the Schema Viewer and/or queries that are already open. Defaults are applied only to tables and queries that are specified from this point forward.
Parent topic: Migrate Utility


The Help Menu

Restriction: This topic applies to Windows environments only.

The Help Menu command provides access to Migrate's online help system.

The Help menu contains the following commands:

Contents | Displays the table of contents for Migrate's online help system.
Search For Help On | Displays the Search dialog box, which lets you search for a specific topic by keyword.
Getting Started | Gives you an overview of Migrate.
How Do I . . .? | Displays a list of procedures for using Migrate.
About Migrate | Displays the program's version and copyright information.
Parent topic: Migrate Utility


The Window Menu

Restriction: This topic applies to Windows environments only.

The Window menu is a standard system menu used to arrange and size windows and icons, as well as to switch between the currently open document windows.

The Window menu contains the following commands:

Tile | Arranges all open windows in side-by-side fashion (no windows overlap one another).
Cascade | Arranges all open windows in a layered fashion, leaving their title bars and left borders visible.
Arrange Icons | Aligns icons for all minimized windows along the bottom of the application window.
Parent topic: Migrate Utility


Options Utility

Restriction: This topic applies to Windows environments only.
  • The Paths Tab
  • The Format Tab
  • The Multiuser Tab
  • The Browser Tab
  • The Query Tab
  • The Query Run Tab
  • The SQL Tab
  • The Security Tab
  • The Summary Tab
  • The Connect Tab
Parent topic: User Interface Reference


The Paths Tab

Restriction: This topic applies to Windows environments only.

The PATHS tab allows you to specify where SQLWizard files and other executable files are to be found or written.

XDB Executables Path | Full path specification for the directory where the executable files are found. The Executables Path, also referred to as the default directory, is the directory in which the system searches when looking for executable files, help files and error files.
Default Application Path | The default path for all application files, such as SQL scripts and files used by the batch modes of various Micro Focus utilities. This path is also the default path in which output files are placed by the various utilities. When you save or open an application file, SQLWizard gives you the opportunity to choose a different directory.
Temporary Path | This is the path where the system writes temporary files, such as temporary query result files. Do not enter the root directory of your hard disk, as this could cause problems.
Overflow Temporary Path | This is the full path specification to an alternative directory where the system can write temporary files. Do not enter the root directory of your hard disk, as this could cause problems.
Parent topic: Options Utility


The Format Tab

Restriction: This topic applies to Windows environments only.

The FORMAT tab allows you to specify the formats for dates, times, numeric fields, etc.

Date Format | Used to create a picture of the date display format that is used when displaying or entering date values. Choose an International Standard from the list box. Choose LOCAL to define your own date format. You can also set special month and weekday formats. For more information on defining pictures, see Picture Definitions Overview.
 | Standard | Description | Format
 | USA | IBM USA Standard | mm/dd/yyyy
 | EUR | IBM European Standard | dd.mm.yyyy
 | JIS | Japanese Industrial Standard Christian Era | yyyy-mm-dd
Date Picture | A display of the date format you selected. If you select LOCAL for the DATE FORMAT, you can type your own format in the DATE PICTURE field.
Months | Select a picture of the month portion of the date format.
Weekdays Select a picture of the day-of-week portion of the date format. Three formats are available: WW, WWW and WWWW:
  • The WW format causes a number between 1 and 7 to be displayed. 1 corresponds to Monday, 2 to Tuesday, etc.
  • The WWW format displays a three-character text abbreviation (Mon, Tue, etc.).
  • The WWWW format is a string of up to 9 characters that displays the full day of the week in text (Monday, Tuesday, etc.)

For more information on defining pictures, see Picture Definitions Overview.
Time Format This section allows you to specify the default format for displaying or printing time fields. The format is also used for data entry input.

Because the format you select is used as the default time format for display and input in most Micro Focus applications, it is important to select the time mask with care. In some utilities you can override the default time mask by defining masks or pictures for specific columns.

Select from a list of predefined formats (ISO, USA, EUR and JIS). To edit your own time picture position select LOCAL. The cursor will be positioned so that you can enter your own time format. For rules on defining time formats, see Time Pictures Overview.

The following table shows the available time formats.
Standard | Description | Format
USA | IBM USA Standard | hh:mm AM or PM
EUR | IBM European Standard | hh.mm.ss
JIS | Japanese Industrial Standard Christian Era | hh.mm.ss
Time Picture | A display of the time format you selected. If you select LOCAL for the TIME FORMAT, you can type your own format in the TIME PICTURE field.
Time Zone | Used to define the time zone offset from Greenwich Mean Time; this is the difference between your system clock and Greenwich Mean Time (GMT). The intent of the field is to simplify conversion of a timestamp to GMT. To standardize times in your geographically-distributed databases, select the offset from the Time Zone list box. Enter the number of hours offset (-24 to 24) from GMT.
Timestamp Format | Displays the timestamp format used when storing this information in system tables. You cannot change this format.
Numeric Formats | Use this section to specify the following numeric formats. Because the formats you select are used as the default formats for display and input in most Micro Focus utilities, it is important to select the masks with care.
Money Format | Used to define money display/input format. This function allows you to specify the default format for use when displaying or printing money fields. The format is also be used for input in some data entry utilities. Money values are always stored in XDB Server databases as decimal(15,2), but you can set the default money display and input format using this option. Money pictures should be defined according to the rules for numeric picture. See Numeric Masks Overview.
Decimal Format | Used to define decimal display/input format. Decimal values are stored in databases according to the precision and scale you specify, but you can set the default decimal input and display format using this option. Decimal pictures should be defined according to the rules for numeric picture. See Numeric Masks Overview.
Float Decimal Places | Used to specify the default number of decimal places when displaying or printing float fields. XDB Server provides precision of up to 15 places for all float calculations, comparisons and displays. The default precision is set at 2. If you need more than 15 decimal places, use a decimal format instead of float. Decimals can have up to 31 decimal places.
Parent topic: Options Utility


The Multiuser Tab

Restriction: This topic applies to Windows environments only.

The Multiuser tab allows you to specify options relating to the use of a multiuser, XDB Server in a networked environment.

Isolation Level XDB Server provides six levels of isolation so users can control the tradeoff between concurrency and consistency:
  • Concurrency is the ability for multiple transactions to access database resources simultaneously.
  • Consistency is the degree to which changes made by one user have no negative effects on other transactions in a multiuser environment.

Within the maximum degree of consistency and minimum degree of concurrency, the isolation levels are:

Exclusive Use | The entire database is locked for exclusive use of the current transaction.
Repeatable Read | All locks are held until commit point to guarantee that transactions can be done serially.
Cursor Stability | Exclusive (read-write) locks are held until commit, and shared (read-only) locks are released when the next record is accessed.
Lock Current | Only the current record is locked. This level should be used with AUTOCOMMIT ON, or for read-only operations.
Dirty Read | No locks are obtained. Uncommitted record changes are read regardless of locks (other than database locks). A DR transaction is read-only; records cannot be modified.
Snapshot Read | At this level, a snapshot of the data is made at the time of execution. Other users can make changes to the data without waiting for the transaction to complete and the user is ensured that the data will be the same for the life of the transaction. An SR transaction is read-only
Time-out Interval | This is the length of time (in seconds) to wait before retrying, when a lock conflict occurs.
AutoCommit | With AUTOCOMMIT on, an SQL command is committed as soon as it is successfully completed. If AUTOCOMMIT is off, the user needs to explicitly commit transactions by issuing an SQL COMMIT command or by selecting COMMIT from a menu in an application. AUTOCOMMIT is not supported against XDB Link locations.
Backward Logging This option is used only when accessing XDB Server Versions 3.x and 4.x. If using XDB Server Version 5.0 or higher, logging is automatic and this option is ignored.

To perform a rollback operation when using the older XDB Server versions, it is necessary to maintain a log of before images of all changes made to the database during a transaction. This information is stored in a backward log. The backward log contains only the information necessary to roll back the current transaction. Every time a transaction is committed or rolled back, the backward log is erased. When the log is turned off, rollback is not possible, but changes to the database take less time because before images are not written to the log.

For more about backward logging on the older XDB Server versions, see the Backup and Recover chapter of the XDB Server Administration Guide for the XDB Server version you are using.

Parent topic: Options Utility


The Browser Tab

Restriction: This topic applies to Windows environments only.

The Browser tab allows you to specify which database objects you want to display on the Catalog Browser window.

Display | Object types that are checked will appear in the Catalog Browser hierarchy. If unchecked, they are not displayed. Instead the next level in the hierarchy is displayed, if appropriate. The default is to display all objects except databases.
Startup Options | These options specify what the catalog browser will do on startup.
 | AutoRefresh | Not used.
 | AutoStartup | If checked, the Catalog Browser is automatically loaded when SQLWizard is started. If not checked, you can access the Catalog Browser from the View menu or toolbar.
Parent topic: Options Utility


The Query Tab

Restriction: This topic applies to Windows environments only.

The Query tab allows you to specify default options for working with Queries. These options can be overridden for a particular query when you are editing the query. See also the section titled Query Run Tab.

3 Part Names | If checked, queries are defined using fully qualified table names in the format location.authid.table-name.
2 Part Names | If checked, queries are defined using 2-part table names in the format authid.table-name.
Unqualified Names | If checked, queries are defined using unqualified table names.
Show Table Names | If checked, a row is added to the Query Conditions Grid on the Query Design window to show the table where each column resides. This feature is especially helpful when your query joins two or more tables.
Foreign Keys | If checked, the Query Design window automatically defines joins between the columns of any tables that are involved in a foreign key relationship
Primary Keys with Like Name | If checked, the Query Design window automatically creates a join condition between the primary-key columns in one table and any set of primary-key columns with the same names in another table in the query.
Like Column Names | If checked, the Query Design window automatically creates a join condition between tables in the query that have columns with the same name.
Prohibit Cartesian Products | If marked, returns an error if you try to run a join that does not have a WHERE condition involving the joined tables. This only applies to queries run from the Query Design Window.
Parent topic: Options Utility


The Query Run Tab

Restriction: This topic applies to Windows environments only.

The Query Run tab allows you to specify the following options for running queries with SQLWizard. See also Query Tab.

Execute | These options apply to the SQL Edit window and SQL Scripts. They do not affect the running of queries from the Query Design window.
All Commands | Select if you want to run all commands that appear in the current SQL Edit window or SQL script when you begin a run.
First Command | Select if you want to run only the first command in the current SQL Edit window or SQL script when you begin a run.
Current Command | Select if you want to run the currently selected command in the current SQL Edit window when you begin a run.
Edit Options
Allow Editing | Enables the ALLOW EDITING option on for any query you run. The ALLOW EDITING option lets you to enter and change data on the Results window.
Check Unique Key If checked, enables unique-key checking. When this option is set, SQLWizard automatically searches the SYSINDEX and SYSKEYS tables during an edit-mode query, and adds unique key fields to the query, even if the user has not explicitly selected them.

Such action allows SQLWizard to generate the appropriate WHERE clause should the user subsequently choose to update any of the extracted data. On certain databases (e.g., large DB2 3.x locations without a shadow catalog), the search for unique key fields can result in extremely long query times.

If your database has been designed so that a unique key is always selected, this option can be disabled to eliminate the search for unique keys, thereby improving performance.
Read-Only Alert | Enables a pop-up box warning when a query is not editable. Disables the result set "Allow Editing" feature for the SQL Window.
Result Table | If checked, the default view for a Query Result window is the Result Table format. This format displays multiple records in a grid format that looks similar to a spreadsheet.
Result Form | If checked, the default view for a Query Result window is the Result Form. This format displays one record at a time.
NULL= | Select a color from the drop-down list to specify the color you want to use to represent null values. Once you have specified a color, you can toggle the colorization of null values on and off using the Highlight Nulls option on the Query menu when viewing an SQL window, and on the View menu when viewing a Result Table or Result Form window.
Max Records to Retrieve
All | Enable this option if you want to retrieve all rows that meet the criteria of the query and displays them in a Result window.
First n Records | Enable this option if you want to retrieve only the first n rows that meet the criteria of the query and displays them in a Result window. This allows you to limit the amount of data coming back and is very useful when testing a query. If you choose this option, be sure to enter the number of records you want to set as your limit.
For Bit Data Display
Use Hex Format | If checked, columns that are defined as FOR BIT DATA will be displayed in hex in the result set browser. This allows SQLWizard to build a query with a where clause which uses the hex literals of FOR BIT DATA fields to identify the row you would like to delete or update in the result set browser.
No Display | Will suppress the display of empty result sets. If running in interactive mode, a pop-up box will appear notifying you that no rows were retrieved. If running in interactive batch mode (running a batch SQL script from the menu by clicking Run Batch on the File menu) it will prevent the displaying of empty result windows without any warning.
Parent topic: Options Utility


The SQL Tab

Restriction: This topic applies to Windows environments only.

This tab provides a means of setting defaults for various SQL operational parameters, including compatibility and sort sequence defaults.

The SQL tab contains the following settings:

SQL Compatibility Mode Used to set the SQL dialect that XDB Server uses. XDB Server permits you to specify which SQL implementation rules are to be enforced. Options are:
  • XDB
  • DB2
  • ANSI

The XDB mode option has extensions not found in DB2 SQL.

If you are running against an XDB Link gateway to access data on a mainframe or other database system, be sure to select the correct SQL Compatibility Mode. When SQL statements do not provide the results you expect, you should always check your SQL mode to make certain it is correct for your application.
Escape Character In many Micro Focus utilities and client applications, you can use an escape character before some special keys to instruct the system to treat the character as a literal. The default escape character is a backward quote ( ` ). You can redefine the key used as the escape character. For example, to insert a question mark into the database from the Data Entry utility (OS/2), you would type `?. You can also use the escape character in front of % or _ if you want these characters interpreted as literals rather than as pattern matching characters.
Note:

In Micro Focus documentation, the key you select for the escape character is referred to as <EscChar>. For example, the default <EscChar> = `
Embedded COBOL

Specify how you want to treat quoting characters around literals and SQL identifiers (such as column names and table names) when using precompiled COBOL with Embedded SQL.

DEFAULT | Behavior of quoting characters is determined by usage.
APOST | Apostrophe characters are used to quote string literals (and quotation marks are used as escape characters for SQL identifiers)
QUOTE | Quotation marks are used to quote string literals (and apostrophe characters are used as escape characters for SQL identifiers)
By default, SQL Option for DB2 tries to determine the behavior of quoting characters (apostrophe or quotation mark) based upon their usage. In the default mode, either an apostrophe or quotation mark can be used as the string delimiter. If the usage of either quoting character is ambiguous, SQL Option for DB2 assumes that the quoting character is used as a string delimiter surrounding a string literal. Ambiguity typically arises when a one-part object name is quoted and used where either object-names or string literals can be present, as shown in the following example:
SELECT D.'IBMREQD', 'IBMREQD' FROM SYSIBM.SYSDUMMY1 AS D;

In this query, SQL Option for DB2 assumes that the first set of apostrophe characters are being used as SQL escape characters and they surround a column name. This assumption is made because of the two-part dot notation. However, the second set of apostrophe characters are assumed to be string delimiters and the second IBMREQD is assumed to be a literal string.

This can lead to problems when one-part names for database objects are quoted and their usage is not explicit in the statement. For instance, a string literal cannot legally be used in the FROM clause of an SQL statement, so quoting characters in the FROM clause are always considered as escape characters surrounding SQL identifiers. However, as both string literals and SQL identifiers can be present in a SELECT clause, the usage can be ambiguous.

To illustrate this, the following query produces three different results in the three different modes:

SELECT 'IBMREQD', "IBMREQD" FROM SYSIBM.SYSDUMMY1

When using the default, the query returns the following:

-----------------
|IBMREQD|IBMREQD|
-----------------

When using APOST, the query returns the following:

-----------------
|IBMREQD|N |
-----------------

When using QUOTE, the query returns the following:

-----------------
|N |IBMREQD|
-----------------
Default Sort Sequence Choose the default sort sequence to use when creating a location.
Note:

After you define a user defined sort sequence and use it for one or more locations, do not re-define it. The locations using the original sort sequence are likely to have index and other problems.

The sort sequence options are as follows. The first three are standard computer sort sequences.
Case Insensitive ASCII | (A=a, B=b, etc.)
ASCII | Standard ASCII sort
EBCDIC Sensitive | Standard EBCDIC sort where null values sort low
User Defined If you select USER DEFINED, you must specify a sort sequence file that is named with the extension .SEQ. This file is used as the sort sequence for any location that is created with a user defined sort sequence.

To operate with a user-defined sort sequence, you must create a sort sequence file (use any ASCII text editor). The file can be up to 256 lines. Each line represents a rank in the sort sequence. On each line, enter an ASCII decimal code or a character, enclosed in double quotes. (See the US ASCII Table for a list of ASCII decimal codes.) If a rank is shared by multiple characters, enter them on the same line, separated by commas.

Below is a partial sort sequence file. In this example, the decimal code 0 (null) appears on line 1, and is the first element in the sort sequence. The letter A appears on line 2, and is therefore assigned rank 2. Because both upper and lower case A appear on the same line, A is not case-sensitive. The same is true of B, C, etc. The letter E was entered using ASCII decimal codes (69='E' and 101='e'). ASCII decimal codes and characters in quotes can be used interchangeably.

  • 0
  • "A","a"
  • "B","b"
  • "C","c"
  • "D","d"
  • 69,101
  • ...

If characters are missing from your sort sequence file, the missing characters will be treated as null by the system. Save the file with the name of your choosing, and the extension .SEQ.
Classic EBCDIC | Standard EBCDIC sort where null values sort high. This mimics the mainframe sort sequence.
Language EBCDIC | Includes French EBCDIC, Spanish EBCDIC, Italian EBCDIC, UK EBCDIC, Danish (Norwegian) EBCDIC, Swedish (Finnish) EBCDIC, German (Austrian) EBCDIC, US (Portuguese, Dutch) EBCDIC, International EBCDIC, and Turkish EBCDIC. Each sort sequence is the same as the corresponding character set, with null values sorting high.
SysAuthID | These items allow SQLWizard to find the system catalog tables that contain the information to be displayed in the Catalog Browser.
SysXDB Specify the AuthID to be used when issuing queries against system catalog tables owned by SYSXDB. Often you will only have privileges on a view on the system catalog tables. Usually the view is created using the same table name, but a different AuthID than the underlying table. When running against XDB-Link to DB2, you will usually use SYSXDB=XDB instead of SYSXDB=SYSXDB.

If the SYSXDB= setting is incorrect and you get the message:

ISQL043: Cannot access SYSIBM tables using AuthID authid.

then you may not have privileges on the catalog tables. SQLWizard provides script files that grant access to the catalog tables. These scripts must be run by a Database Administrator, or by someone who has SYSADM authority. See your Setup Guide for information about these script files.
Parent topic: Options Utility


The Security Tab

Restriction: This topic applies to Windows environments only.

The Security tab allows you to set your security options. The CLIENT SECURITY option is important if you want to turn security on for your copy of the XDB Server.

Only if security is on for the XDB Server will password security be fully enforced. The global security options are only available with XDB Server 4.0 or later.

If security is on at the XDB Server you will be accessing, you must check the CLIENT SECURITY check box. If security at the XDB Server is off, you can check or not check this box as desired. Using CLIENT SECURITY when security is not required by the XDB Server will provide password security at your workstation.

Specifies the rules that must be satisfied by your password. The password enforcement levels are:

  • Level 1: Password must be four or more characters.
  • Level 2: Password must be six or more characters and include at least one digit.
  • Level 3: Password must be six or more characters, include at least one digit and must include the two randomly generated characters that appear in the prompt message when the user creates or modifies their password.

The passwords created or modified by users must meet the criteria for the current password enforcement level.

Parent topic: Options Utility


The Summary Tab

Restriction: This topic applies to Windows environments only.

The Summary tab presents a scrollable list of all of the configuration settings that are set through the Options window. You cannot make changes to any of the options from the Summary tab, but you can print it for reference.

Parent topic: Options Utility


The Connect Tab

Restriction: This topic applies to Windows environments only.

The Connect tab provides options for configuring the connection between a client application (such as SQLWizard or a program that you have developed) and the XDB Server you will be accessing.

Locations | Specify the name of the default location you want to access when a connection is made (click the BROWSE button if you want to select from a list of locations). You will be able to override this selection at run time if the Connect dialog box is displayed (the AUTOCONNECT option is off and/or CLIENT SECURITY, on the Security tab, is on).
AuthID | Specify the AuthID (user name) you want to appear as the default in the Connect dialog box. You will be able to override this at run time if the Connect dialog box is displayed when you start SQLWizard (i.e., the AUTOCONNECT option is off and/or CLIENT SECURITY, on the Security tab, is on). If security is off, the AuthID entered in Options will automatically become your current SQLID and will be used as the AuthID portion of any database objects you create.
AutoConnect | If AUTOCONNECT is on and CLIENT SECURITY, on the Security tab, is off, the Connect dialog box is suppressed. In this case, you connect to the default Server, Location and AuthID that you specified in Options.
AutoLogoff | Check this to have the user automatically logged off from the system when you exit the Options Utility if you have made any changes to your connection specifications.
Communication Protocol | Specify which protocol you want to use to communicate with the XDB Server specified in Server Name. Options are:
 | Local [or Windows(LOCAL)] | (Windows 3.x only) Communicates with a local XDB Server. If you have an XDB Server on the same machine as your client application, you can use this server to communicate with it using the proprietary internal protocol instead of using the network.
 | Win32Local | (Win32 only) Communicates with a local XDB Server. If you have an XDB Server on the same machine as your client application, you can use this server to communicate with it using the proprietary internal protocol instead of using the network.
 | NetBIOS | Communicates across the network to a remote, multiuser XDB Server using the NetBIOS protocol.
 | Names Pipes | Communicates across the network to a remote, multiuser XDB Server using the Named Pipes protocol. (Also may be used to access a local XDB Server that supports local Named Pipes.)
 | TCP/IP | Communicates across the network to an XDB Server or XDB Link using the TCP/IP protocol. If you choose the TCP/IP protocol, enter the server's IP address in the IP Address text box, and the port number on which the server will receive connection requests in the TCP Port text box. The same port number must be specified on the XDB Server and all clients of the XDB Server. Check with your system administrator if you do not know this information.
 | IPX/SPX | Communicates across the network to an XDB Server or XDB Link using the IPX/SPX protocol. Note: You may need to add information to your xdb.ini file to successfully use some of these protocols. See the PROTOCOL= and PROTOCOLMAP= parameters in the [CONNECTION DEFAULTS] section of the xdb.ini file for more information. Check with your network administrator and your XDB Server Administrator to determine which protocols are supported on your network and on your XDB Server.
Client Node Name | This is the name by which your machine is known to the XDB Server. The name should be unique among all machines that are trying to access any XDB Server or XDB Link on your network.
Parent topic: Options Utility


SQL Wizard

Restriction: This topic applies to Windows environments only.
  • SQLWizard Menus Overview
  • Keyboard Navigation Overview
  • Completing the Connect Dialog Box
  • Create/Alter/Drop Location Dialog Box
  • Create/Alter/Drop Table Dialog Box
  • Table Options Dialog Box
  • Catalog Browser Tabs
  • Add/Modify User Dialog Box
  • Groups Dialog Box
  • Define Priority Dialog Box
Parent topic: User Interface Reference


SQLWizard Menus Overview

Restriction: This topic applies to Windows environments only.

SQLWizard's menu bar also changes as different windows become active. For example, menus displayed when the Query Design window is active are different from the menus displayed when an Import window is active.

There are several menus that are always present and that remain fairly constant. These are:

  • File Menu
  • Edit Menu
  • View Menu
  • Location Menu
  • Table Menu
  • Admin Menu
  • Window Menu
  • Help Menu
  • File Menu
  • Edit Menu
  • View Menu
  • Location Menu
  • Table Menu
  • Admin Menu
  • Window Menu
  • Help Menu
Parent topic: SQL Wizard


File Menu

Restriction: This topic applies to Windows environments only.

The File menu provides commands for opening new or existing queries and other objects, as well as for printing and saving. The Exit command is located on this menu.

New | Provides a submenu for opening various types of SQLWizard documents or Windows.
Open | Displays the Open dialog box for opening queries, import and export specifications, and batch SQL scripts and tables.
Save | Saves the contents of the current window. If the object has not yet been named, the Save As dialog box will be displayed.
Save As | Displays the Save As dialog box you use to specify the name of an object to be saved.
Close | Closes the window that is active.
Close All | Closes all windows that are open, including the active window. If any window contains unsaved data or specifications, a prompt is provided to give you the opportunity to save it.
Run Batch | Displays the Run Batch dialog box, asking you to select an SQL file to load and run.
Print | Prints the contents of the current window or prints the associated report for the current window. When you select Print, the following Print dialog box appears, allowing you to specify the number of copies and the pages you want to print. The Setup button will display the Printer Setup dialog box. When you click OK, SQLWizard formats the data in the active window and sends it to your printer or print queue. Status of the print job is shown in a message box, which constantly updates to indicate the page number that is currently being sent.
Output | Transfers the contents of the current window or the associated report for the current window to a file. When you select Output, your system's standard Save As dialog box appears titled as Output File. The Save As dialog boxes for other operating environments are similar. See your operating system documentation for more information.
Printer Setup | Displays your system's Print Setup dialog box, allowing you to select a printer and set printer options. The Print Setup dialog box for other operating environments are similar. See your operating system documentation for more information.
Exit | Exits SQLWizard. If any windows contain data that has not yet been saved, you are prompted to save it.
Parent topic: SQLWizard Menus Overview


Edit Menu

Restriction: This topic applies to Windows environments only.

Although it is not available when SQLWizard first starts, the Edit menu is available when working with many of SQLWizard's features. The Edit menu typically provides functions to undo the last changes, cut/copy/paste using the clipboard, and perform other edit functions. This menu changes depending on the window that is active.

Undo | If there are changes to the current field that can be restored to their previous state, click this command to undo them.
Redo | If there are changes to the current field that can be entered again, click this command. (This command only appears on the menu when appropriate to the task at hand.)
Cut | Removes the currently selected text or object and saves it to the clipboard.
Copy | Copies the currently selected text or object to the clipboard.
Paste | Pastes the current clipboard contents at the cursor position. If the data on the clipboard is not compatible, it is not pasted.
Delete | Deletes the selected item or the text at the cursor position.
Other menu items | Depending on what kind of SQLWizard window is active, other commands may appear on this menu, such as the Insert Row and Delete Row commands that are used when using a Result table to do data entry. The 72-column Format command is available when a SQL Edit window is the current window.
Parent topic: SQLWizard Menus Overview


View Menu

Restriction: This topic applies to Windows environments only.

The View menu provides access to the Catalog Browser. You also use it to switch between different views of the current window depending on the editing mode you are using. For example, if a Query Design window is active, the View menu provides commands to switch to SQL view.

The three Catalog Browser commands are described here. Specialty View menu commands are described in their respective chapters.

Locations | Brings the Catalog Browser to the front with the Location tab selected so that you can work with locations.
Tables | Brings the Catalog Browser to the front with the Table tab selected so that you can work with tables.
Queries | Brings the Catalog Browser to the front with the Query tab selected so that you can work with queries.
Parent topic: SQLWizard Menus Overview


Location Menu

Restriction: This topic applies to Windows environments only.

You use the Location menu to set and manage locations.

Set Location | Displays the Set Location/SQLID dialog box, which allows you to change your current location and SQLID.
Create | Displays the Create Location dialog box, which allows you to define specifications for a new location and create it.
Alter | Displays the Alter Location dialog box, which allows you to change a location's parameters.
Drop | Displays the Drop Location dialog box, which allows you to drop (delete) the specified location and all its tables.
Parent topic: SQLWizard Menus Overview


Table Menu

Restriction: This topic applies to Windows environments only.

Use the Table menu to open and manage tables.

Open | Opens a table by selecting all columns and rows from it and displaying it in a Result Table window.
Create | Displays the Create Table dialog box so that you can define and create a new table along with its associated indexes, keys, synonyms, and aliases.
Alter | Allows you to select a table for modification. Once you have selected a table, the Alter Table dialog box is displayed so that you can alter the table's specifications, as well as create, alter, or drop its associated indexes, keys, synonyms, and aliases.
Drop | Allows you to select a table that you want to delete from your database. Once you have selected a table, SQLWizard asks for confirmation before actually performing the drop.
Parent topic: SQLWizard Menus Overview


Admin Menu

Restriction: This topic applies to Windows environments only.

Use the Admin menu to create and manage AuthIDs, passwords, groups, and XDB Server priorities.

Change Password | Allows users to change their own passwords and allows a super user to change the passwords of others. You must have the appropriate privileges to change any password other than your own.
Users | Allows you to define, modify, or delete AuthIDs, and assign users to groups. You must be a super user to access this command.
Groups | Allows you to define, modify, or delete user groups. You must be a super user to access this command.
Priorities | Allows you to define, modify, or delete priority definitions to control access to the database and limit XDB Server usage. You must be a super user to access this command.
Parent topic: SQLWizard Menus Overview


Window Menu

Restriction: This topic applies to Windows environments only.

The Window menu is a standard system menu used to arrange and size windows and icons, as well as to switch between the currently open document windows.

Tile | Divides the SQLWizard parent window evenly among the currently open child windows, and resizes the child windows to fit in the space allocated.
Cascade | Makes all of the child windows a standard size and displays them one below the other and slightly offset to the right.
Arrange Icons | Evens out the arrangement of any minimized child windows along the bottom of the parent window.
List of Open SQLWizard Windows | A numbered list of open child windows appears at the bottom of the menu. By clicking on the name of a window, you make that window the active window.
Parent topic: SQLWizard Menus Overview


Help Menu

Restriction: This topic applies to Windows environments only.

The Help menu provides comprehensive help on the SQLWizard interface as well as an online SQL Reference. SQLWizard makes use of the native help system for your operating environment. If you are not familiar with how Help works in your environment, consult your operating environment documentation or click the How To Use Help command on the SQLWizard Help menu.

Contents | This command displays the contents of the SQLWizard help file.
Search for Help On | (Windows systems only.) Displays the Help Search dialog box to assist you in locating a help topic.
How To Use Help | Accesses a general help file that describes how to use help.
SQL Command Tutor | Opens the SQL Option Help, which contains descriptions and syntax for all SQL commands supported by XDB Server. This online reference can assist you in writing SQL statements. You can use help facilities to copy example code to the SQL Edit window or to your editor.
About SQLWizard | Describes the SQLWizard application.

In addition to the Help menu, you can access help to display information about the current context by:

  • Pressing F1.
  • Clicking the Help button on the toolbar.
  • Clicking a Help button on a dialog box.
Parent topic: SQLWizard Menus Overview


Keyboard Navigation Overview

Restriction: This topic applies to Windows environments only.

SQLWizard uses a graphical user interface oriented to mouse usage. However, you can navigate almost all of SQLWizard's windows, dialog boxes and menus using the keyboard.

Menu items can be accessed using the standard keystrokes for your operating environment. For example, in Windows you can hold down Alt while typing the underlined character on the menu you want to use. Many menu commands have keystroke shortcuts, such as Ctrl+O to open a file or Ctrl+S to save a file. These are displayed on the menus.

Navigating within a window or dialog box uses the standard keystrokes for your operating environment. In most cases, you can move from one item to the next on a window or dialog box by pressing Tab. (Use Shift+Tab to tab within a data entry field.)

You can select an item from a drop-down list by tabbing to the list and then pressing Down Arrow. Likewise, to select an item from a group of radio buttons, you can tab to one of the items in the group and press Down Arrow to select it. Use the space bar to press a command button or to change the setting of a checkbox after tabbing to it.

Note:

There are some situations where the customary keystrokes cannot be used, and you will need to use your mouse.

Parent topic: SQL Wizard


Completing the Connect Dialog Box

Restriction: This topic applies to Windows environments only.

The Connect dialog box contains four fields: Server, Location, AuthID, and Password.

Server Use this field to specify the name of the XDB Server you wish to access. You can select from any server in the drop-down list. If you don't see the server you want to use, exit SQLWizard and run the Options utility to add the server to your system. For more information about adding servers to SQLWizard, see the Options utility online help.
Location Use this field to specify the location to which you want to connect. You can type a name or click the Browse button to select a name from the Browse dialog box. The Browse dialog box shows all locations known to the selected XDB Server.
Note: Each time you access the Browse Dialog box, the selected XDB Server is checked for the list of all known locations available and you are logged in to the specified XDB Server with the current AuthID and password. If security is on, you must have SELECT privileges on the XDB Server's system location for this feature to operate correctly.

If you do not click the Browse button, the XDB Server is not accessed until you connect.

AuthID Use this field to specify the AuthID you wish to use when logging in. The AuthID is used for access security, object ownership, and determining database privileges.

The default AuthID that appears in this field reflects your AUTHID entry in the Options utility. You can type in a different name if desired.

Note: Your AuthID may be remapped to a SecondaryID by your XDB Server Administrator. If you have a SecondaryID, you will log in using one AuthID and appear to be doing work as another AuthID.
Password The Password field appears only if Security is turned on in the Options utility. Security must be on in the Options utility if you are accessing an XDB Server that is running with security on. If you are accessing an XDB Server that does not require security to be on, you can choose whether to turn security on or off for your own workstation.

The password you enter must be between four and eight characters and must follow the rules for a short identifier. Your password must meet the specifications for the current "password enforcement level" defined for the XDB Server you are accessing.

Parent topic: SQL Wizard


Create/Alter/Drop Location Dialog Box

Restriction: This topic applies to Windows environments only.

Use the Create/Alter/Drop Location dialog box to define, change, or delete XDB Server locations. You access the Create/Alter/Drop Location dialog box using the Create, Alter, and Drop commands on the Location menu. Regardless of whether you are creating, altering, or dropping a location, this dialog box is essentiallythe same.

The following describes all fields on the Create/Alter/Drop Location dialog box.
Location A location is a collection of databases, tables, indexes, and related objects organized in a specific structure. An XDB Server can have multiple locations, all managed by the same database server.
Name
Specifies the name of the location. A location name may be up to 16 characters long, and must be unique among all of the locations that reside on a given XDB Server.
Creator
Specifies the AuthID of the person who created the location. The default is to use your current SQLID, but you can change this if you are authorized to use a different SQLID.
Path
Specifies the directory where your location files are stored. When creating a location, if you name a directory that does not exist, SQLWizard creates it for you.
Forward Log If using XDB Server version 4.x and earlier, you must specify the name of the file used for forward logging. In XDB Server version 5 and later, this file is automatically created by the system, however you can specify the directory to which it is stored.
Name
Specifies the name of the file that will be used as the Forward Log. SQLWizard uses up to eight characters of the location name as a default forward log file name. You can change it if desired.
Path
Specifies the directory in which the Forward Log will be stored (under XDB Server version 5 and later; the Backward Log is placed in this directory too). SQLWizard uses the location path as the default, but if possible, it is best to use a different physical drive for the Forward Log. Keeping the Forward Log on a different drive will enable you to restore your database in the event of a disk failure on the drive containing your location and database files.
Sort Sequence SQLWizard allows you to specify the sort sequence to be used for ordering and comparing data on a per location basis. Select one of these sort sequences from the drop-down list:
  • Case Insensitive ASCII
  • ASCII
  • EBCDIC Sensitive
  • User Defined
  • Classic EBCDIC
  • Language EBCDIC
Remarks | Type any comments about the location in this field. Comments can be up to 30 characters.
SQL | Click this to examine the SQL statements represented by the entries you have made.
Parent topic: SQL Wizard


Create/Alter/Drop Table Dialog Box

Restriction: This topic applies to Windows environments only.

Through the Create/Alter/Drop Table dialog box, SQLWizard provides an interactive means of creating, altering, and dropping tables. In addition to allowing changes to a table's column definition, the Create Table and Alter Table dialog boxes let you add or change an existing table's indexes, primary keys, foreign keys, synonyms, and aliases.

The following describes all fields on the Create/Alter/Drop Table dialog box.

Table Name | Specifies a table name using a three-part, two-part, or unqualified table name, as appropriate. If you are altering or dropping a table, you can choose the table name from the Catalog Browser dialog box or the Open Table dialog box when you first access the Alter/Drop Table dialog box.
Comments | Describes the table. The comment is stored in the Remarks column in the SYSIBM.SYSTABLES table.
Indexes and Keys | Contains a list of the current or pending indexes on the table. You can choose one of the buttons to create, alter, or drop an index or key.
Relationships | Contains a list of current foreign keys on this table. You can choose one of the buttons to create, alter, or drop a foreign key.
OK button | Accepts all table definition information as shown on the Create/Alter Table dialog box and executes the SQL commands to effect them. On the Drop Table dialog box, the OK button executes the SQL command to drop the table and all its related files and database objects.
Cancel Button | Discards all entries or changes that may have been made on the Create/Alter/Drop dialog box.
Options Button | Accesses the Table Options dialog box where you can define synonyms and aliases, as well as other important options for your table specification.
SQL Button | Opens the Show SQL window to display the pending SQL command(s). Information shown on the Create/Alter/Drop Table dialog box are used by SQLWizard to generate the SQL command(s).
Field (Column) Definitions The grid at the bottom of the Create/Alter/Drop Table dialog box is used to define the columns in your table. Except for the field name, you can either use the default values provided, or change the fields as described below.
Fld. No.
Shows the number of the table row.
Primary Key
The key icon indicates whether the column is part of a primary key. A primary key is used to uniquely identify the rows in a table. Once you have defined a primary key for the table, a key icon appears next to the column.
Field (Column) Name
Identifies each column in a table, view, or result. A column name can be up to 18 characters and must satisfy the rules for a long identifier.
Data Type
Defines the kind or type of data a column may hold. The following lists all available data types:
  • Char
  • Char for bit data
  • Long Varchar
  • Graphic
  • Long Vargraphic
  • Varchar
  • Varchar for bit data
  • Long Varchar for bit data
  • Vargraphic
  • Rowid
  • Time
  • Date
  • Integer
  • Float
  • Float (4)
  • Decimal
  • Money
  • Timestamp
Length
For data types with flexible lengths, type a field length to replace the default field length. If the data type does not have a flexible length, the field length is automatically filled in for you and the field is disabled.
Note: The length shown for some data types is the physical number of bytes used to store the data, rather than a limit on the number of digits or characters in the field. For example, even though the length of a smallint field is shown as 2, a smallint field can contain values between + and - 32767.
Not Null
Allows you to specify whether or not Null values are allowed in the column. Click the down-arrow button to display a drop-down list of options. You may also choose from the list by typing the first character of the option.
False
The column can be null.
True
The column cannot be null. It must contain data.
w/ Default
If the field is null, SQLWizard inserts a default.
Unique
For NOT NULL UNIQUE, used by DB2. If a column is defined as NOT NULL UNIQUE, DB2 allows at most one record to contain a null value.
Comments
Optional. Shows text up to 254 characters for each column in the table. These comments appear in the Catalog Browser dialog box when the Details option is checked.
Parent topic: SQL Wizard


Table Options Dialog Box

Restriction: This topic applies to Windows environments only.

When you create or alter a table, the Table Options dialog box allows you to create, alter, or drop synonyms and aliases related to the table and specify DB2-related options (including the database and table space the table resides in, edit and validation procedures, and audit, data capture, and OBID options). These DB2-related options are provided for those who transfer data between XDB Server and mainframe DB2. For more information on these items, consult your DB2 documentation.

Database/Tablespace
Provides options for organizing your tables and indexes.
Database (In Database clause) An XDB Server database is a collection of tables, indexes, and table spaces. Each database definition occupies a separate directory. A database can consist of a number of files that span several directories. If you use stogroups, it can also span several disks.
Note: The database and/or stogroup must exist before you create the table. To create a database or stogroup, open an SQL Edit window and issue a CREATE DATABASE or CREATE STOGROUP command as explained in the SQL Reference.

Database names are stored in the system catalog table SYSIBM.SYSDATABASE. Every location contains a default database (DSNDB04) for user-defined tables and two XDB Server catalog databases (DSNDB06 and DSNDB07). Also, a location may include any number of additional user-defined databases. The SYSTEM location includes two additional databases: XDBACF, which stores information on security and access, and DSNDDF, which stores information on other locations.

Tablespace (In Tablespace clause) A table space is a physical area of disk space that holds a table. The table space object provides compatibility with DB2, and is optional in XDB Server. By default, XDB Server assumes a table space name that is the same as the table name, and each table is stored in its own table space.
Note: The table space must exist before you create the table. To create a table space, open an SQL Edit window and issue a CREATE TABLESPACE command as explained in the SQL Reference.

In DB2, table spaces and stogroups provide a means of organizing tables and indexes on specific disk storage devices. Generally, you associate each table space and index with a stogroup. You create a table within a specific table space. When you create an index, you can associate it with a stogroup.

Audit
Identifies the types of table access that causes auditing. Audit options are provided for mainframe DB2 compatibility. The options are:
None | Default.
Changes | The table is audited during the first insert, update, or delete operation by each unit of work.
All | The table is audited when the table is accessed during the first operation of any kind by each unit of work. The appropriate audit-trace class must be active and audit is not done when the table is accessed by COPY, RECOVER, REPAIR, or a stand-alone utility.
Procedures
Allows you to enter two kinds of procedures. These procedures are provided for mainframe DB2 compatibility.
Edit Proc | Names an edit routine for the table that is provided by the current server's site. Default is none.
Valid Proc | Names a validation exit routine for the table. Default is none.
OBID
Names the table's internal descriptor within the XDB Server SYSTEM catalog. The OBID option is used with ROSHARE databases.
Data Capture
Specifies if the log records for SQL INSERT, UPDATE, and DELETE commands can contain additional information. This option is provided for mainframe DB2 compatibility.
None | Do not record additional information to the log.
Changes | Write additional data about SQL updates to the log.
Global Temp. Table
Allows you to create the table as a global temporary table.
Synonyms and Aliases
Allows you to create, alter, or drop synonyms and aliases for the table. Altering an alias or a synonym is used only when you wish to remove a dropped status.
Parent topic: SQL Wizard


Catalog Browser Tabs

Restriction: This topic applies to Windows environments only.

There are three tabs arranged along the left side of the Catalog Browser dialog box. Use these tabs to switch between different hierarchical views of the system catalog. Each view provides a different set of buttons on the right side of the Catalog Browser dialog box.

Location Tab | Shows information about known locations, and provides access to location management commands.
*
Table Tab | Shows information about tables and related objects such as databases, indexes, keys, and columns. Also provides access to table management commands.
*
Query Tab | Shows information about queries and SQL statements stored in the system catalog tables, and accessible by the current server.
*
  • Location Tab Buttons
  • Table Tab
  • Query Tab Buttons
  • Object Icons
  • Expanding and Collapsing the Hierarchy
  • Query Window
  • Result Window
  • Import Window
  • Export Window
  • Target File Information
  • Source Table Information (Design Mode)
  • Source Table Information (SQL Mode)
  • Export Options Dialog Box
Parent topic: SQL Wizard


Location Tab Buttons

Restriction: This topic applies to Windows environments only.

The following are the buttons available for the Location view of the Catalog Browser.

Create | The Create button displays the Create Location dialog box.
Alter | The Alter button displays the Alter Location dialog box for the currently selected location.
Drop | The Drop button displays the Drop Location dialog box for the currently selected location.
Set | The Set button displays the Set Location dialog box, allowing you to select a new current location and/or SQLID. This button is available only if a location name is highlighted (selected) on the list of locations. Locations that can be selected in this manner apply only to the server to which you are currently connected. Note: To connect to a location managed by another XDB Server (including XDB Link), use the Set Location command on the Location menu.
Refresh | The Refresh button queries the system catalog to find out current details for all locations. Click this button after you or someone else has made changes to objects, such as inserting, altering, or dropping locations, tables, indexes, queries, etc.
Detail | The Detail checkbox indicates if comments on the locations should be shown to the right of each location name. If checked, comments are displayed. To add comments to a location, use the Alter Location dialog box, and type a remark. Click the OK button to confirm the Alter command. When you return to the Catalog Browser, click the Refresh button to view the changes.
Parent topic: Catalog Browser Tabs


Table Tab

Restriction: This topic applies to Windows environments only.

The following buttons are available from the Table view of the Catalog Browser.

Create * | The Create button displays the Create Table dialog box, allowing you to specify parameters for a new table in the current location.
Alter * | The Alter button displays the Alter Table dialog box to let you change the currently selected table.
Drop * | The Drop button displays the Drop Table dialog box for the currently selected table.
Open * | The Open button displays the contents (data) of the selected table in a Result window. Clicking Open is the same as executing the SQL command: SELECT * FROM tablename FOR FETCH ONLY
Refresh * | The Refresh button queries the system catalog to find out current details for all tables and related objects. Click this button after you or someone else has made changes to objects, such as inserting, altering, or dropping locations, tables, indexes, queries, etc.
Filter * | The Filter button enables you to specify filters to control the databases, AuthIDs and table items that are displayed in the Catalog Browser for any particular location.
Detail * | The Detail checkbox indicates whether comments on the tables, columns, or other objects should be shown to the right of the object name. If checked, comments are displayed. At the column level, the column definition, including data type, is also displayed. You may have to increase the width of the Catalog Browser to see all of the information for each object.
Parent topic: Catalog Browser Tabs


Query Tab Buttons

Restriction: This topic applies to Windows environments only.

The following buttons are available from the Query view of the Catalog Browser.

New * | The New button opens a new Query Design window, and prompts you to select tables for your query.
Batch | The Batch button executes the highlighted query in batch mode. If the Quiet option is on, the query runs in the background. If the Quiet option is off, the query is displayed in an SQL Edit window as it runs; each step is highlighted to show progress as the query executes. To set the Quiet option on or off, you must run the query using the Run Batch command from the File menu.
Delete * | The Delete button deletes a highlighted query from the system catalog. After deleting a query, you need to click the Refresh button to see the updated list of queries.
Open * | The Open button displays the highlighted query for further modification or execution. If the query was saved as a Prompted Query, it is opened in a Query Design window; otherwise, it is opened in an SQL Edit window.
Refresh * | The Refresh button runs a query on the system catalog to find out current details on all objects. Click this button after you or someone else has made changes to objects, such as inserting, altering, or dropping tables, indexes, queries, etc.
Detail * | The Detail checkbox indicates whether comments on the queries or SQL statements should be shown to the right of the query name. If checked, comments are displayed. You may have to increase the width of the Catalog Browser to see all of the information for each object.
Parent topic: Catalog Browser Tabs


Object Icons

Restriction: This topic applies to Windows environments only.

The object icons are displayed next to the name of each object in the Catalog Browser dialog box to help you visually interpret the levels of the hierarchy. Some appear when any tab (Location, Table or Query) is selected and some appear only under one tab. You can configure which levels appear in the hierarchy using the Browser tab of the Options utility.

Parent topic: Catalog Browser Tabs


Expanding and Collapsing the Hierarchy

Restriction: This topic applies to Windows environments only.

The Expand and Collapse buttons appear to the left of the object icons to indicate if an item's subordinate objects are hidden or displayed.

Expand | The Expand button indicates that the item may have sub-items beneath it that are not currently visible. Click the button to open the item and display the sub-items. When you expand the levels, you may need to drag the border of the Catalog Browser dialog box to make it wide enough to read all of the information as shown below.
Collapse | The Collapse button indicates that the item has been expanded, and that the sub-items are currently visible in the hierarchy. Click this button to collapse the hierarchy and hide the sub-items.
Note:

If an Expand button disappears when you click it and there is no replacement Collapse button, then there are no objects in that list.

Parent topic: Catalog Browser Tabs


Query Window

Restriction: This topic applies to Windows environments only.
  • Query Window Menus Overview
  • Query Toolbar
Parent topic: Catalog Browser Tabs


Query Window Menus Overview

Restriction: This topic applies to Windows environments only.

When a Query Design window or the SQL Edit window is active, the Query menu and Column menu are displayed. Depending on which of these windows is active, certain items may be disabled.

In addition to the Query and Column menus, other menus (such as File menu and Edit menu) are available for use when working with queries.

Note: The Column menu that appears when working on a Query is different from the Column menu that appears when viewing a Query Result window.
  • File Menu
  • Edit Menu
  • View Menu
  • Query Menu
  • Column Menu
Parent topic: Query Window


File Menu

Restriction: This topic applies to Windows environments only.

The File menu provides options for opening new or existing queries and other objects, as well as for printing and saving. File menu commands relating to your work with writing queries are listed below.

New |  | Creates a new query. Clicking the New command displays a cascading submenu from which you can select:
 | Query | Opens the Add Table dialog box, allowing you to select tables for your query and place them in a new Query Design window. From this window, you can specify parameters for your query and then run the query.
 | SQL | Opens a new SQL Edit window where you can type your own SQL command statement, save it as a batch SQL script file, and then run it in batch mode.
Open |  | Opens a previously saved query or batch SQL script file. Optionally, use the Catalog Browser dialog box to open an existing query.
Run Batch |  | Allows you to choose a previously saved batch SQL script file and run it in batch mode.
Parent topic: Query Window Menus Overview


Edit Menu

Restriction: This topic applies to Windows environments only.

The Edit menu provides basic editing commands such as Undo, Cut, Copy, and Paste. The Edit menu also provides commands that are specifically for use with the Query Design window.

Insert Row | Inserts a row into the Query Conditions Grid so you can enter additional search conditions.
Delete Row | Deletes the current row from the Query Conditions Grid.

The Edit menu also provides a command that is used only with the SQL Edit window.

72-column Format When this option is selected, SQL statements are allowed to span multiple lines of 72 characters as in IBM mainframe utilities.
Parent topic: Query Window Menus Overview


View Menu

Restriction: This topic applies to Windows environments only.

The View menu allows you to access the Catalog Browser dialog box or switch the views of the current query window between Query Design mode and SQL Edit mode.

Design | If checked, shows the current query in the Query Design window, instead of in an SQL Edit window.
SQL | If checked, shows the current query in the SQL Edit window, instead of in a Query Design window.
Arrange Tables | Rearranges the Column Selection Lists in the Table Display Area in a uniform fashion.
Parent topic: Query Window Menus Overview


Query Menu

Restriction: This topic applies to Windows environments only.

The Query menu provides options for running and designing queries. This menu is available only if a Query Design window or an SQL Edit window is the currently active window.

Run | Executes the statement or statements in the current Query Design or SQL Edit window. If the window contains a SELECT statement, a Query Result window is displayed. If it contains non-SELECT statements, these are executed, and the execution status is shown in the status bar at the bottom of the window.
Step Mode | If checked, steps through one SQL command at a time when there are multiple commands. This command is enabled only if the Execute All Commands option is in effect. See the Query Run tab in the Options utility online help.
Add Table | Displays the Add Table dialog box so that you can add a table to the current Table Display Area of the Query Design window.
Delete Table | Deletes the currently selected table from the Query Design window, thus removing it from the query.
And... | Displays a dialog box so that you can specify an extended WHERE condition or nested query.
Sort... | Displays the Order By dialog box so that you can specify the columns on which the result is to be sorted.
Group... | Displays the Group By dialog box so that you can specify the GROUP BY clause used to create a summary result.
Having... | Displays the Having dialog box so that you can specify search conditions that summary rows must satisfy.
Show Table Names | If checked, adds a row to the Query Conditions Grid. This row displays the name of the table from which each column comes.
Parameters | Displays the Parameters dialog box, so that you can supply values for the host variables in an SQL statement. You can fill this out before running your query, or just run the query and let the system prompt you to supply values for the parameters. Note: The values entered in the Parameters dialog box are saved for use each time you run commands from this window. Use this PARAMETERS command if you want to make changes to the values.
Auto Join | Displays the Auto Join submenu. A checked option causes the system to generate an automatic join condition.
Result Table View | If checked, opens the Result window in the multi-record Result Table view when a query is run.
Result Form View | If checked, opens the Result window in the single-record Result Form view when a query is run.
Highlight Nulls | Check this to enable the highlighting of null values in the color selected in the Options utility. When checked, the highlighting differentiates null values from spaces.
Allow Editing | If checked, attempts to open the Result window directly into Edit mode when a query is run. There is some additional overhead in doing this, so the default is to not go directly to Edit mode.
AutoCommit | If checked, sets AUTOCOMMIT on when a Result window switches to Edit mode.
Show Positive SQL Code | Check this to set SQL Wizard to display a warning message when the server returns either a positive or a negative SQL return code. When unchecked, SQL Wizard displays warnings for negative return codes only.
Current Query Options | Displays the Query Options dialog box for the current query. From this dialog box, you can set query design and query run options, such as the maximum number of rows to retrieve.
Parent topic: Query Window Menus Overview


Column Menu

Restriction: This topic applies to Windows environments only.

The options found in the Column menu are applied to the currently selected column (or columns) of the Query Conditions Grid on the Query Design window. To select a column, double click the column name displayed in the Query Conditions Grid.

Note:

The Column menu that appears when working on a Query is different from the Column menu that appears when viewing a Query Result window.

Create Computed Column | Displays the Create Computed Column dialog box, so that you can define a column based on an expression.
Hide Column | Sets the currently selected column to hidden mode, so that it will not be included in the SELECT clause of the query. If a column is hidden before you run the query, you will not be able to select it from the hidden column list in the Query Result window.
Select Hidden Column | Displays the Select Hidden Column dialog box, and lets you move columns between a list of hidden columns and a list of displayed columns.
Sort Column | Displays the Sort Column submenu. When you pick either ascending or descending order from the submenu, the currently selected columns will be added to the Order By clause with the appropriate sequence.
Function | Displays the Function submenu. When you pick a function, the current column is converted into a computed column by using it as an argument for the function. Since the functions are all aggregate functions, the computed columns defined will retrieve summary rows. For the current column you can:
Delete Column | Deletes the currently selected column(s) from the Query Conditions Grid.
Parent topic: Query Window Menus Overview


Query Toolbar

Restriction: This topic applies to Windows environments only.

When a query window is the active window, the query toolbar is displayed, as shown below. Depending on whether you are in the Query Design window or the SQL Edit window, certain buttons may be disabled.

Figure 1. *
*
Parent topic: Query Window


Result Window

Restriction: This topic applies to Windows environments only.
  • Result Window Menus Overview
  • Directional Commands and Buttons
  • Goto Command
  • Scroll Bars
  • Cut
  • Copy
  • Paste
Parent topic: Catalog Browser Tabs


Result Window Menus Overview

Restriction: This topic applies to Windows environments only.

When a Result window is active, the Result window menu bar is displayed. Depending on whether you are in Result Table view or Result Form view, certain items may be disabled.

Also, some commands (such as Data Entry) are available only if Edit mode is active.

The primary menus used for working with a Result window are:

  • File menu (for printing and saving)
  • Record menu
  • Column menu
  • View menu (for switching between Result Table and Result Form)
  • File Menu
  • Edit Menu
  • View Menu
  • Record Menu
  • Column Menu (Result Table View Only)
Parent topic: Result Window


File Menu

Restriction: This topic applies to Windows environments only.

The File menu provides commands for opening new or existing queries and other objects, as well as for printing and saving. File menu commands relating to your use of a query result are listed below:

  • Save
  • Save As
  • Close
  • Print
  • Output
  • Printer Setup
  • Exit
Parent topic: Result Window Menus Overview


Edit Menu

Restriction: This topic applies to Windows environments only.

The Edit menu provides functions to undo the last changes, to cut/copy/paste using the clipboard, and to perform other edit functions. Information about using these commands with a Result window are described below.

Undo | If there are changes to the current field that can be undone, click this command to undo them. This command is available only if Allow Editing is on. To reverse the last change (insert, update, or delete) to a record, use the Undo Record command from the Record menu.
Redo | If there are changes to the current field that can be redone, click this command to redo them. This command is available only if Allow Editing is on.
Cut | Moves the currently selected text or object to the clipboard. This command is available only if Allow Editing is on.
Copy | Copies the currently selected text or object to the clipboard. This command is available only if Allow Editing is on.
Paste | Pastes the current clipboard contents at the cursor location. If the clipboard contents is not compatible, it is not pasted. This command is available only if Allow Editing is on.
Delete | Deletes the currently selected text or object. This command is available only if Allow Editing is on.
Parent topic: Result Window Menus Overview


View Menu

Restriction: This topic applies to Windows environments only.

The View menu allows you to access the Catalog Browser dialog box, switch the view of the active Result window between Result Table view and Result Form view, and view or edit text for a particular field in a zoom window.

The following View menu commands are applicable to your use of a Result window.

Result Table | If checked, the active Result window is shown in Result Table view. Multiple records are shown in a spreadsheet-like format.
Result Form | If checked, the active Result window is shown in Result Form view. One record is shown at a time, with fields arranged vertically down the screen.
Highlight Nulls | Check this to enable the highlighting of null values in the color selected in the Options utility. When checked, the highlighting differentiates null values from spaces.
Zoom | Displays a window containing the contents of the result field on which the cursor is positioned. This supplemental window is useful for reading or editing data in large character fields where data may be spread over several lines or paragraphs. You can open a Zoom window by clicking on the Zoom command from the View menu, or by double clicking on the desired field in the Result window display.
Parent topic: Result Window Menus Overview


Record Menu

Restriction: This topic applies to Windows environments only.

The Record menu provides commands for moving among records, updating records, and performing other data entry functions. Most of these commands require that you have the Allow Editing command checked. The Record menu is available only when a Result window is the active window.

Update | Explicitly writes the current record's changes to the database. If Autocommit is on, you do not need to click Update; simply moving your cursor to another record or closing the Result window will automatically update the record your cursor was on. The Update command is enabled only if there have been changes to the field(s) of the current record since it was last read from the database. The Allow Editing command must be checked for this command to be enabled.
Delete | Deletes the current record from the database. The Allow Editing command must be checked for this command to be enabled.
Undo Removes the changes made to the record that the cursor is on by re-reading the record from the table. The Undo command is available only if you have made changes to the fields of the current record since you last read it, and you have not moved to another record.

If the last undo-able action is a delete, this command changes to Undo Delete, and choosing it will undelete (restore) the deleted record.

Append Duplicate | Appends a copy of the selected record to the end of a result table when Allow Editing is enabled. If there is a unique index on any of the fields in the record you are appending, you must change the values in these fields before moving from the appended row.
Data Entry | Switches to Data Entry view of the Result window, in which only newly inserted records are displayed. Initially, you see only a blank record into which you enter data for a new record. As you enter the data for each record and move to the next record, the new record is inserted into the database. Enabled only if the Allow Editing command is checked.
Show All Records | Switches from Data Entry view (which only shows newly inserted records) to a regular view that shows all records in the result.
Moving and Scrolling Commands | When using any of the following moving and scrolling commands, SQLWizard updates the current record before moving the cursor and redisplaying the requested records. The directional arrow buttons on the toolbar perform the same functions as these commands.
First

Moves the cursor to the first record of the entire set of results records.
Previous Page

Moves the cursor and displays the results of the previous page of records. This command is only visible in Result Table view.
Previous

Moves the cursor to the previous record. In Result Table view, SQLWizard scrolls the display if the previous record is not completely visible.
Next

Moves the cursor to the next record. In Result Table view, SQLWizard scrolls the display if the next record is not completely visible.
Next Page

Moves the cursor and changes the results display to the next page of records. Next Page is available only in Result Table view.
Last

Moves the cursor to the last record of the entire set of results records. In Result Table view SQLWizard scrolls the table if the last record is not completely visible.
New

Moves to the end of the result set and displays a blank record where you can enter data. Only available if Allow Editing is checked.
Note:

If your result is very large (has many records), the New command will have a negative performance impact because the system must seek to the end of the result set before the data entry can occur. If you want to insert a record without seeking to the end of the result set, switch to Data Entry mode using the Data Entry command on the Record menu.

Goto Click the Goto command to display the Goto Record dialog box. Type the number of the record to which you want to move and click OK. This is particularly useful for very large tables.

If you enter a record number higher than the highest in the table, the last record in the table is displayed.

Refresh Redisplays the current Results table by re-running your original query. The cursor moves to the first record.

If you have changed any fields of the current record, SQLWizard updates that record before refreshing the display. If you made changes to the table which you have not committed (if running with Autocommit off), SQLWizard prompts you to commit changes before refreshing the table.

Commit | Makes all the changes in your current transaction, as well as the current record, permanent, as it saves them to the disk. Commit is not available if you checked Autocommit.
Rollback Rollback is like an Undo. If the Rollback command is active (and the Backward Log is turned on through the Options utility), you can click Rollback to return your data to the condition of the last commit.

Rollback is not available if you checked Autocommit on the Record menu because when Autocommit is on, XDB Server automatically commits each record as you complete it.

See Transaction Processing for more information about the Commit, Rollback, and Autocommit concepts,.

Autocommit When you check Autocommit, changes are saved to each record as soon as you move your cursor to another record. When Autocommit is off, you must explicitly commit changes to the table. You may be able to rollback changes since the last commit; see Rollback command above.

When you click Autocommit on, SQLWizard automatically commits any changes to fields that you have not already committed.

SQLWizard lets you set a default initial setting for Autocommit on the Query Run tab of the Options utility. The status of Autocommit on the Record menu always over-rides the default in the Options utility.

Count

Refreshes the data in the status bar at the bottom of the SQLWizard window, to reflect the current count of records in the result, and the record number where the cursor is currently located.

Sort Displays the Order By dialog box allowing you to sort the records in the result. You can sort the result by one or more columns.

To select a column to sort by, double click its name to move it to the Sorted Columns list. To deselect a column, double click its name to move it to the Unsorted Columns list. You can select one or more columns for your sort.

To indicate if the sort should be ascending or descending for each column, click the Arrow-Toggle button next to each name in the Sorted Columns list.

If sorting by more than one column, you can define your sort priority by re-arranging the items in the Sorted Columns list. To move a column name up or down the list, click to highlight the column name, then click the up or down arrow buttons to the right of the Sorted Columns list to reposition the column name.

Allow Editing If you select Allow Editing, the system attempts to reopen the Result window in Edit mode so that you can update, delete, and insert records. When editing is allowed, SQLWizard displays a check mark next to Allow Editing. You will not be able to check Allow Editing if the query does not support updates, as would be the case if you run a join query.

When you check the Allow Editing command, the following edit commands become available on the Record menu: Update, Delete, Undo, New, Data Entry, Commit, Rollback, and Autocommit. Other requirements may restrict the availability of these features.

If you uncheck Allow Editing, you cannot make changes to the records. SQLWizard disables editing commands on the Record menu.

Note:

When running against a non-XDB Server data source such as mainframe DB2, you will not be able to edit a result table unless the result includes a unique index (or primary key), or unless the Check Unique Key option is disabled.

Parent topic: Result Window Menus Overview


Column Menu (Result Table View Only)

Restriction: This topic applies to Windows environments only.

The Column menu provides commands for controlling how you view data in a Result window. Most of the commands in the Column menu are applied to the currently selected column(s).

To select a column, double click the column name displayed across the top row of the Result window. The Column menu is available only when a Result window is the active window.

Fix Locks the selected column(s) against the left margin of the Result table grid. When you scroll horizontally, other columns scroll past but the fixed column(s) remain in view. This lets you keep one or more identifying columns visible as you look at the information to the right of the spreadsheet grid.
Free Unlocks fixed columns. This command is available only if you select (double click) one or more fixed columns.

Another way to free a fixed column is to drag it to the right, dropping a it one or more columns away from the left fixed boundary of the table. You can monitor this by watching the left arrow on the horizontal scroll bar, as it relocates when you free the fixed fields.
Hide Removes the selected columns from the Result table display. You can hide as many columns as you want, individually or as a group. To redisplay a column, use the Select Hidden command.
Note:

Hiding a column only affects your viewing of the result display. It does not affect the table, where all columns and data remain intact.
Select Hidden Displays the Select Hidden Columns dialog box, allowing you to select which columns should be displayed or hidden. This dialog box displays two lists Hidden Columns and Displayed Columns.

You can move columns between the lists in either of two ways:

  • Click a column name to highlight it. Then clicking on an arrow button to move it to the other list.
  • Double click a column name to move it to the other list.

When you click OK, SQLWizard rearranges the result display to reflect the new set of hidden and displayed columns
Parent topic: Result Window Menus Overview


Directional Commands and Buttons

Restriction: This topic applies to Windows environments only.

In the Record menu you will find commands to go to the First, Previous Page, Previous Record, Next Record, Next Page, and Last rows of a result. These menu commands correspond to the directional arrow buttons you see in the toolbar when a Result window is active.

Figure 1. *
*
Parent topic: Result Window


Goto Command

Restriction: This topic applies to Windows environments only.

There is a Goto command in the Record menu which allows you to move directly to a specific row of the result without having to scroll.

Parent topic: Result Window


Scroll Bars

Restriction: This topic applies to Windows environments only.

You can use the scroll bars to quickly move through a Result window. The behavior of the scroll bars depends on the result view. The Result Table view shows many records at once and Result Form view shows a single record at a time.

To view additional columns in a record:

  • If you are in Result Table view, use the horizontal scroll bar to scroll through the columns in your result.
  • If you are in Result Form view, use the vertical scroll bar to move through all of the fields in a record.

To view other records:

  • If you are in Result Table view, use the vertical scroll bar to move through the rows of your result.
  • If you are in Result Form view, use the toolbar buttons or Record menu items to move from one record of the result to the next.
Parent topic: Result Window


Cut

Restriction: This topic applies to Windows environments only.

*
Deletes the highlighted text from Result window and holds it on the clipboard for a future paste. You can also use the appropriate keystroke for cut in your operating environment. For example, in Microsoft Windows you can use Ctrl+X to cut data to the clipboard.

Parent topic: Result Window


Copy

Restriction: This topic applies to Windows environments only.

*
Copies the highlighted text from Result window and holds it on the clipboard for a future paste. You can also use the appropriate keystroke for cut in your operating environment. For example, in Microsoft Windows you can use Ctrl+C to copy data to the clipboard.

Parent topic: Result Window


Paste

Restriction: This topic applies to Windows environments only.

*
Pastes the clipboard text to the field that the cursor is on in a Result window. You can also use the appropriate keystroke for cut in your operating environment. For example, in Microsoft Windows you can use Ctrl+V to paste data from the clipboard.

Note:

If the pasted data contains more characters than are allowed by the size of the column you are pasting into, the data is truncated.

Parent topic: Result Window


Import Window

Restriction: This topic applies to Windows environments only.
  • Import Window Menus Overview
  • Import Window Toolbar
Parent topic: Catalog Browser Tabs


Import Window Menus Overview

Restriction: This topic applies to Windows environments only.

Once you open an Import window, you can use the File, View, and Import menus to work with your import specifications and batch commands. The primary menus used for working with an Import window are:

  • File Menu
  • View Menu
  • Import Menu
  • File Menu
  • View Menu
  • Import Menu
Parent topic: Import Window


File Menu

Restriction: This topic applies to Windows environments only.

The File menu provides commands for opening an Import window, for saving and retrieving import specifications, and for running Batch Import files. File menu commands relating to your use of an Import specification are provided below.

New | Opens a new Import window where you can enter specifications for importing data.
Open | Presents the Open dialog box, allowing you to retrieve previously saved SQLWizard import specifications into an Import window.
Run Batch | Presents the Run Batch dialog box, allowing you to run a previously saved SQLWizard Batch Import (*.imp) file.
Parent topic: Import Window Menus Overview


View Menu

Restriction: This topic applies to Windows environments only.

In addition to the standard View menu commands, the following commands become available when an Import window is active:

Source File | Opens a window to show the contents of the source file that is specified in the Import window. If no file is specified in the Import window, a File Open dialog box is presented, allowing you to choose a file.
Batch Import Commands | Opens a window showing the Batch Import commands that would be generated from the information currently appearing on the Import window. This is the SQL that would be saved if you use the Save or Save As command.
Parent topic: Import Window Menus Overview


Import Menu

Restriction: This topic applies to Windows environments only.

The Import menu appears in the title bar when an Import window is active. The following functions are available when importing most source file types into XDB Server table definitions:

Run | After you have entered all required information on the Import windows, starts importing your source file into the desired table definition. Optionally, you can click the Run button from the toolbar. When the process is completed, the system shows the number of records imported in the status bar at the bottom of the window. You can then process another file.
End Current | Allows you to abort an import operation while it is running. Data that was already imported up to that point remains imported. When you select this command while running an import batch file that has several transactions, the transaction currently running is ended and the next transaction is started.
End All | Aborts all batch processing when you have more than one transaction in an Batch Import file.
Clear Form | Clears all the current import specifications from the Import window. Values are set to their user-defined defaults as specified in the Defaults dialog box.
Recalculate | When you select a source file to import, automatically calculates a table definition for the data (except for the DSNTIAUL format). This command allows you to prompt the system to reanalyze the currently selected source file and get the system to suggest a table definition. This gives you the ability to revert to the original interpretation of the file's table definition. If you are creating a new table, you can then redefine any fields that are not grayed out in the table-definition display area.
Options Displays the Options dialog box, which allows you to customize your import processes. You can set the import speed to run in Normal or Engine Direct Write modes. You can also write errors to a log file and write records containing errors to a log file.

You can also set error handling options that allow you to:

  • Skip any invalid data and go on to the next record.
  • Insert NULL in fields when invalid data is encountered if the field is nullable.
  • Quit the current import process and continue with the next if an error is encountered.
  • End all Batch Import processing.
Defaults | Displays the Default Settings dialog box. The defaults consist of preset parameters. You can use this command to set format parameters of your own, or you can use the XDB Server defaults when you click the Defaults button. Default settings can be provided for Free-format ASCII, Fixed-format ASCII, and DSNTIAUL formats.
Parent topic: Import Window Menus Overview


Import Window Toolbar

Restriction: This topic applies to Windows environments only.

When an Import window is active, the Import toolbar will be displayed as shown below.

Figure 1. *
*
Parent topic: Import Window


Export Window

Restriction: This topic applies to Windows environments only.
  • Export Window Menus Overview
  • Export Window Toolbar
Parent topic: Catalog Browser Tabs


Export Window Menus Overview

Restriction: This topic applies to Windows environments only.

Once you open an Export window, you can use the File, View, and Export menus to work with your export specifications and batch commands. The primary menus used for working with an Export window are:

  • File Menu (for opening, saving, and printing)
  • View Menu
  • Export Menu
  • File Menu
  • View Menu
  • Export Menu
Parent topic: Export Window


File Menu

Restriction: This topic applies to Windows environments only.

The File menu provides commands for opening an Export window, for saving and retrieving export specifications, and for running Batch Export files. File menu commands relating to your use of an export specification are provided below.

New | Opens a new Export window where you can enter specifications for exporting data.
Open | Presents the Open dialog box, allowing you to retrieve previously saved SQLWizard export specifications into an Export window.
Save or Save As | Allows you to save the specifications that appear in the active Export window. You can save these specifications as a Batch Export file or as a Batch Import file.
Run Batch | Presents the Run Batch dialog box, allowing you to run a previously saved SQLWizard Batch Export file (*exp).
Parent topic: Export Window Menus Overview


View Menu

Restriction: This topic applies to Windows environments only.

In addition to the standard View menu commands, the following commands become available when an Export window is active:

Design Export | Displays the standard Export window, allowing you to interactively select a table to export, specify a file to receive the exported data, specify various format-specific options, and specify a WHERE condition. An alternate Export window view is available if you select the SQL command from the View menu.
SQL | Provides an alternate view of your Export specifications, allowing you enter an SQL SELECT statement instead of using the standard Export window to specify the source table and WHERE condition.
Target File | Allows you to view the data as it appears in the file to which you exported data.
Batch Export Commands | Opens a window showing the Batch Export commands that would be generated from the information currently appearing on the Export window. This is the command list that would be saved if you use the Save or Save As command. It can later be run as a Batch Export file.
Batch Import Commands | Opens a window showing the Batch Import commands that would be generated from the information currently appearing on the Export window. This is the command list that would be saved if you use the Save or Save As command and saved the file as an Import (*.imp) file. Generating a batch import file at the time you are exporting data can help you when you plan to import the data onto another XDB Server. You would take the exported data file and the corresponding batch import file to the other XDB Server. Then use batch import on that machine to transfer the data onto that XDB Server.
Parent topic: Export Window Menus Overview


Export Menu

Restriction: This topic applies to Windows environments only.

The Export menu appears in the SQLWizard title bar when you access the Export utility. The following functions are available from the Export menu when exporting an XDB Server table into a target file:

Run | Starts exporting the desired XDB Server table into a target file. Click the Run button from the toolbar, or click the Run command from the Export menu. When the process is completed, the system shows the number of records exported in the status bar at the bottom of the window.
End Current | Allows you to end an export process while it is running. Data that was already exported up to that point will appear in the destination file. If you select this command while running a Batch Export file that has multiple transactions, the transaction currently running is aborted and the next transaction is started.
End All | Aborts all batch processing when you have more than one transaction in a Batch Export file.
Clear Form | Clears all of the current export specifications from the Export window. Values are set to their user-defined defaults as specified from the Defaults dialog box.
Options | Displays the Export Options dialog box where you can specify error handling preferences.
Defaults | Displays the Export Default Settings dialog box where you can set preferences for various options. These preferences take effect whenever you open a new Export window. You can set default format parameters for each export file type (Free- and fixed-format ASCII and DSNTIAUL) and specify which view of the Export window you prefer (Design mode or SQL mode).
Parent topic: Export Window Menus Overview


Export Window Toolbar

Restriction: This topic applies to Windows environments only.

When an Export window is active on the SQLWizard desktop, the Export toolbar will be displayed as shown below.

Figure 1. *
*
Parent topic: Export Window


Target File Information

Restriction: This topic applies to Windows environments only.

This section of the Export window is where you specify the name of the file to which you want to export your XDB Server data, as well as the format to be used in that file and any other parameters required by the particular format.

File Name | Enter the drive, path, and name of the file to which you want to export data. If you enter the name of a non-existent file, SQLWizard will create it. You can use the Browse button to select an existing file that you want to over-write.
Format | Click the down-arrow button to display the drop-down list; select the format for your target file. SQLWizard can export data to free or fixed ASCII files, and mainframe-readable DSNTIAUL files. SQLWizard can also create SQL statements that you can run on another SQL database system to re-create the source table on that other system. You can include the data from the source file or just the table structure.
Other Target File Parameters | Depending on the format of the target file, additional parameters may be required.
Parent topic: Catalog Browser Tabs


Source Table Information (Design Mode)

Restriction: This topic applies to Windows environments only.

This section of the Export window is where you specify exactly what you want to export. You can export an entire table, selected columns, or selected data.

Table Name | Enter the name of the XDB Server table that you want to extract data from. Use the Browse button to select a table from the Open dialog box.
Not Included/Included Lists | The Not Included and Included lists allow you to choose the columns of the source table that you want to export. Only the columns appearing in the Included list when you run the export will be transferred to the target file. Double click a column name to move it to the other list. You can also re-arrange the order of the columns. For example, if your source table has columns called FIRSTNAME and LASTNAME in that order, you can switch the order to LASTNAME FIRSTNAME in the exported data. After selecting the columns you want to include in the exported data, click a name to highlight it, then move it up or down the Included list until the column names are in the order you want.
WHERE Condition | You can limit the amount of data that will be exported by entering an SQL WHERE clause. For example, when exporting data from the TUTORIAL.TUTORIAL.EMPLOYEE table, you can export information about employees who live in Maryland by entering ST="MD" in the WHERE Condition box. You do not have to type the word WHERE. Note: When the SQL format is selected, the WHERE Condition field is available only when INSERT mode is selected.
Parent topic: Catalog Browser Tabs


Source Table Information (SQL Mode)

Restriction: This topic applies to Windows environments only.

This section of the Export window is where you specify exactly what you want to export. You can export an entire table, selected columns, or selected data.

Query Enter a standard SQL SELECT query to define the data you want to export. The data will be retrieved from the database and stored in the target file and format you specify.
Parent topic: Catalog Browser Tabs


Export Options Dialog Box

Restriction: This topic applies to Windows environments only.

Items appearing on the Export Options dialog box are described below.

On Error |  | Sets error handling options.
 | Continue | Continues processing after encountering a recoverable error.
 | Quit | Aborts the current export transaction. If running a Batch Export file containing multiple transactions, starts the next transaction.
 | End All | Aborts all export processing. If running a Batch Export file containing multiple transactions, cancels all subsequent transactions.
 | Prompt | If an error is encountered, prompts for further action.
ASCII Conversion |  | Translates the character data in the export's output file by indicating the appropriate code page translation to use. This translation happens after the data is presented by the XDB engine.
Error Logging |  | Keeps a list of all errors encountered during an export process. After the export process completes, you can view the listing of errors by editing the file with an ASCII text editor.
 | On | Indicates that you want to write errors to a log file.
 | File | Specifies the name of a file to receive the error listing.
Parent topic: Catalog Browser Tabs


Add/Modify User Dialog Box

Restriction: This topic applies to Windows environments only.

The fields and controls in the Add/Modify User dialog box are described below.

Add | Adds a new AuthID to the system.
Delete | Permanently removes the display AuthID from the system. To temporarily deny access to a user (leaving all AuthID specifications intact), de-select the Access Authority checkbox.
Update | Changes a user's access information using the information currently displayed on the dialog box.
Close | Closes the Add/Modify User dialog box.
User ID | The AuthID (user name or UserID) is used for security purposes when you access the XDB Server, utilities, and database objects. It is also used to determine ownership of database objects. Only an XDB Server Administrator who has super-user authority can change the AuthID.
Password The password must be between four and eight characters long and must follow the rules for a short identifier. If an XDB Server is being accessed and security is on, the password specified for the user must meet the specifications for the current Password Enforcement Level as defined for that XDB Server. The user can specify a higher level access authority using the Options utility. Any super user can modify the password for an existing user, but cannot delete a user's password.

Because XDB Server passwords are stored in an encrypted format, neither a user nor an administrator can view any user's existing password. The password entered is never displayed. Instead, an asterisk (*) is displayed for each character entered.

SQLWizard has three password enforcement levels:

  • Level 1 password must be four or more characters.
  • Level 2 password must be six or more characters and include at least one digit.
  • Level 3 password must be six or more characters, include at least one digit, and must include the two randomly generated characters that appear in the prompt message when the password is created or modified.
    Note:

    Passwords are case sensitive. Be sure to always enter your password in the same combination of upper and lower case characters.

Verification | The Verification field is used to confirm entry of a password. It reassures that you have entered the correct password for a user.
Secondary ID The SecondaryID field is provided so that a variety of users can have the same AuthID for processing queries or for object ownership, but have different accounts for connecting to the XDB Server. The SecondaryID can be up to eight characters long and must follow the rules for a short identifier.

The SecondaryID value is used only when security is on. When a user with a SecondaryID creates an object, the AuthID portion of the object's name is the SecondaryID. All other users who have the same SecondaryID will have all privileges granted to that ID.

It is in this way that users can have controlled access to specific tables and information. An XDB Server Administrator can also grant location, database and table level privileges by assigning GroupIDs to AuthIDs. See Appendix A, "Security and Authority" for more information on using GroupIDs versus SecondaryIDs.

Security Options These options are applicable when accessing an XDB Server with security on. These options are ignored when accessing an XDB Server with security off. Note that these options relate only to accessing the XDB Server itself. An administrator must still grant appropriate location, database, and/or table privileges to each account.

The available security options include:

Password Required | If checked, the user must enter a password when connecting to an XDB Server.
Access Authority | If checked, the user can connect to the XDB Server. If not checked, the user is denied access to the XDB Server. This option provides a temporary way of restricting a user's access without deleting the AuthID and other information from the system.
User Type This option grants the user either User or Super User privileges. The default setting is User. Only a super user can create locations, edit system tables, and give super-user privileges to another user. If you wish to limit a user's access to certain locations or tables, you must use the GRANT and REVOKE commands.

The available User Types include:

User | Those users who are assigned USER for user type can only change their own password. They cannot modify their AuthID, SecondaryID, user comment, priority, user type, security options, or group information and cannot create locations.
Super User If you are granted super-user privileges you can add, delete, and update information for users, groups and priorities. Super users can also create locations, directly edit system catalog tables, and perform other administration functions.
Note:

If security for the XDB Server is off, all users are effectively super users.

User Comments | A descriptive comment about the user or the AuthID. The comment may be longer than the display area (use cursor keys to scroll left and right in this field). The user comment can be up to 254 characters in length.
Group Membership A group is another method available (in addition to using the SecondaryID) for an administrator to control system and location level access. All available groups are displayed in a scrollable list. If no groups exist, the list will be empty.

Groups can be added using the Groups command from the Admin menu. The advantage of using groups is that you can grant/revoke privileges to one group instead of to many individual users. A user can be added to or removed from any group by clicking to highlight the desired group name(s) on the displayed list. Users can have multiple group assignments thus gaining the privileges of all of those groups combined.

Priorities Priorities are a set of usage restrictions imposed on an AuthID. Setting priorities gives an XDB Server Administrator the ability to define XDB Server usage priorities for peak hour processing, or to restrict users who do particularly intensive queries to off-peak hours. A user who exceeds the limits that are set, is disconnected from the XDB Server. This gives an administrator the ability to regulate XDB Server usage for users.

All available priorities are displayed in a scrollable list. If no priorities exist, the list will be empty. Priorities can be added using the Priorities command from the Admin menu. Users can be assigned or removed from any priority by selecting the priority name(s) from the list displayed. If you are not running against an XDB Server version that supports priorities, or if the XDB Server has the Governor feature turned off, the Priorities command is grayed out on the Admin menu.

For more information about the Governor features of the XDB Server, see the description of the Maximum Governor Cycle Time option in the section Governor Cycle Timein the chapter Server Configuration Utility in your SQL Option Server Administration Guide

Parent topic: SQL Wizard
Related information
Governor Cycle Time


Groups Dialog Box

Restriction: This topic applies to Windows environments only.

Items appearing on the Groups dialog box are described in this topic.

Add | Creates a new GroupID. If AuthIDs appear in the MEMBER OF list, they are assigned to the group when the group is added.
Delete | Removes a group and dissociates all assigned AuthIDs from the GroupID.
Update | Changes a GroupID's information, including comments and/or memberships.
Close | Closes the Groups dialog box.
Group Name | Identifies the group. This field is up to eight characters long and must follow the rules for a short identifier.
Comment | Allows for the storage of additional information about the group or its purpose. The comment can be up to 254 characters in length.
Group Membership | Indicates which users belong to the displayed group. AuthIDs in the USER ID list on the left are not members of the group. AuthIDs in the MEMBER OF list on the right are members of the group.
Parent topic: SQL Wizard


Define Priority Dialog Box

Restriction: This topic applies to Windows environments only.

Items appearing on the Define Priority dialog box are shown below.

Add | Defines a new set of priorities for XDB Server usage. Priorities are assigned to AuthIDs to limit server usage.
Delete | Permanently removes an XDB Server usage priority specification.
Update | Changes the parameters that define a priority specification for XDB Server usage.
Close | Closes the Define Priority dialog box.
Priority Name | Identifies a priority. This entry can be up to eight characters long.
Number of API Calls Specifies the maximum number of Application Programming Interface (API) calls allowed during a single session on the XDB Server.

This entry must be greater than or equal to zero. The entry must be greater than or equal to zero, up to a maximum of 999,999,999. When this entry is zero, users with this priority are not limited by the number of API calls in the XDB Server SQL engine.

APIs are routines that are invoked by calls to the SQL engine from the user's application. The number of API calls that users cause the XDB Server engine to invoke is an accurate gauge of their overall use of system resources. The purpose of limiting API calls is to control user access to the system resources.

To limit users to a certain number of API calls, you need to know how many calls the users generally need during the course of their work. In many cases, determining this number is complex because it is dependent on the size of the tables the user accesses. In this case it might be best to set the number of API calls to zero (unlimited number of API calls) while limiting the user with one of the other priorities.

Max Time in Engine | Specifies the maximum cumulative time (in seconds) a user with this priority can use the XDB Server SQL engine during a single session on the XDB Server (called being "in the engine"). This number must be greater than or equal to zero, up to a maximum of 999,999,999 seconds (31 years, 259 days, 1 hour, 40 minutes, and 39 seconds). When set to zero, users with this priority will be allowed unlimited time in the engine. The purpose of this limit is to control the use of system resources.
Max Time Per API | Specifies the maximum time allowed (in seconds) per API from a user with this priority. This number must be greater than or equal to zero, up to a maximum of 9,999 seconds. When set to zero, users with this priority will not be limited by how much SQL engine time is used by an API. The purpose of this limit is to prevent the use of too much SQL engine time on a single API.
Max Idle Time | Specifies the maximum time a user with this priority can be connected to the XDB Server without running any operation on the engine (called "idle time"). This number must be greater than or equal to zero, up to a maximum of 999,999,999 seconds. When set to zero, users with this priority will be allowed unlimited idle time. The purpose of this limit is to prevent users from taking up engine threads while not using the engine.
Max Fetches | Limits a user with this priority to a specified number of records returned (fetches). This number must be greater than or equal to zero, up to a maximum of 999,999,999 fetches. When set to zero, users with this priority will be allowed an unlimited number of fetches. The purpose of this limit is to control the use of system resources.
Start Enforcement Specifies the start of a time period (which ends with END ENFORCEMENT) when engine restrictions are enforced for a user with this priority. The format of the entry is dependent on the time picture defined in Options.
Note:

If the start and end free times are equal and not null (blank entry), then all priority limits are effectively canceled. This is equivalent to saying that the full 24-hour period is free time.
End Enforcement Specifies the end of the time period (which begins with Start Enforcement) when engine restrictions are enforced for a user with this priority. The format of the entry is dependent on the time picture defined in Options.
Note:

If the start and end free times are equal and not null (blank entry), then all priority limits are effectively canceled. This is equivalent to saying that the full 24-hour period is free time.
Comments | Adds an optional description (up to 254 characters) about the general purpose or scope of this priority.
Parent topic: SQL Wizard


Managed COBOL Programming

  • 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.
Parent topic: Programming


Managed COBOL Programming

  • Introduction to Object-Oriented Programming for COBOL Developers
  • 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.
  • 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.
Parent topic: Managed COBOL Programming


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.

Parent topic: Managed COBOL Programming


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 you can develop, compile and debug your applications, for both native and managed code.

When using Micro Focus Enterprise Developer UNIX Components 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 Enterprise Server. JVM COBOL applications are deployed to the platform running the JVM.

Parent topic: Managed COBOL Programming


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
Related reference
ILNAMESPACE


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 (Windows), or $COBDIR/bin (UNIX). The default location for the .jar file is %COBDIR%\bin (Windows), or $COBDIR/lib (UNIX).

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

    Windows:

    cobol caller.cbl jvmgen;
cobol myapp.cbl jvmgen(sub) iloutput(bin) ilnamespace(com.mycompany.desktopapp);

    UNIX:

    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 (Windows), bin/com/mycompany/desktopapp (UNIX) 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.

    Windows:

    java -classpath myapp.jar;.;%CLASSPATH% caller

    UNIX:

    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.
    Note: On Windows platforms, if your CLASSPATH environment variable contains spacey file locations, you may need to enclose %CLASSPATH% in quotation marks.
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 an Enterprise Developer 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.

    Windows:

    cobol caller.cbl jvmgen;
cobol myapp.cbl jvmgen(sub) iloutput(bin) ilnamespace(com.mycompany.desktopapp);

    UNIX:

    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 (Windows), bin/com/mycompany/desktopapp (UNIX) 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, Enterprise Developer 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.

Note that you leave the existing procedural COBOL 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.

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.
Note:
  • 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 the run units will be executing in different threads.

For details of the RunUnit class and further examples see the documentation about com.microfocus.cobol.runtimeservices - see the topic com.microfocus.cobol.runtimeservices.

Parent topic: Multiple user COBOL applications in Java
Related information
com.microfocus.cobol.runtimeservices


Moving Native COBOL Applications to Managed COBOL

Modern deployment architectures such as .NET and JVM 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.

Enterprise Developer is the next generation of COBOL development and deployment environments. It includes powerful modern Integrated Development Environments (Visual Studio or Eclipse) that enable you to deploy key business-critical COBOL applications to .NET, JVM, and the cloud.

Moving to managed code is easy because COBOL has been extended over the years and offers syntax extensions for .NET and JVM integration 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.

  • What is Managed Code?
  • 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


What is Managed Code?

You may be familiar with COBOL compiling to native code in earlier Micro Focus products.

Native code compiles directly to machine code that is native to a device processor and is directly executed on the machine for which it was compiled. The run-time management services are provided by the operating system, and the code has to call the appropriate services depending on the operating system.

Managed code is code that compiles to Intermediate Language (IL) in .NET or to Java byte code on the Java Virtual Machine (JVM) .

Managed code runs in the Common Language Runtime (for .NET) or the JVM (for Java byte code) which are execution environments that provide various services such as checking the code, memory management, and threading.

When you start an application written in managed code, the runtime-aware compiler provided by the respective environment checks the code (IL and Java byte code) for security risks and language violations and compiles it Just In Time to native executable code. The runtime environment ensures type safety, array bound and index checking, exception handling, and garbage collection.

Parent topic: Moving Native COBOL Applications to Managed COBOL


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 .NET framework and in the JVM.

In most cases, in order to move to managed code you can simply recompile the existing COBOL code to managed code in Visual COBOL. Also, there is a Compiler directive, ILSMARTLINKAGE, that you can use to recompile to managed code (see the Examples further on in this section). ILSMARTLINKAGE enables COBOL to interoperate with C# JAVA.

Take full advantage of the capabilities of the .NET framework/the JVM:
  • Use the runtime services provided by the CLR or the JVM - 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 .NET framework and JVM apply many optimizations including ones based on how the code is actually executed at runtime so it could make optimizations that a static analysis cannot perform.
  • Create your own managed COBOL objects - with managed COBOL you can do a lot of what you can do with any other managed language - you can create your own methods, classes, delegates, and interfaces. See An Introduction to Object-Oriented Programming for COBOL Developers, available from the Product Documentation section 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 .NET framework and the JAVA SDK include 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 IL (in .NET)/byte code (JVM), 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 through the use of technologies such as WPF (in .NET) .
Deploy to Java application servers:
Java application servers are required when you provide "thin" client architecture for your applications. The 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 users' requests.

Enterprise Developer supports all major Java application servers (Tomcat, JBOSS, Websphere, WebLogic) and enables you to create and deploy COBOL applications on Java application servers as COBOL Web services or JSPs.

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 (including DECLARE CURSOR, OPEN, FETCH, CLOSE, SELECT, INSERT, UPDATE, DELETE, CONNECT, DISCONNECT, COMMIT and ROLLBACK) are completely compatible and require no change.

The following restrictions apply to database support in managed code:

  • There is no PL/SQL support in managed code, although some PL/SQL statements and blocks may work.
  • 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 General Reference > Library Routines in your product documentation for 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

Enterprise Developer 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 will compile and run in managed environments such as the JVM. However, in order to take a full advantage of all of the features of the managed frameworks and be able to expose your code to other managed languages, you might need to start using managed COBOL syntax. In order to find help with writing managed COBOL, you can explore the following resources:

  • A great way to start with this is the document An Introduction to Object-Oriented Programming for COBOL Developers, available from the Product Documentation section on the Micro Focus SupportLine Web site - click here to download it.
  • See the COBOL for JVM examples installed with Enterprise Developer.

Third Party Software

Examine your existing procedural code for any Third-Party APIs that make operation system calls. Technology provided by other software vendors might need to be rewritten for use with managed code.

Win32 API Routines

The Win32 API routines are not supported in managed code. When you move the procedural code to managed COBOL, you need to remove the call to the Win32 API routine and, instead, use an equivalent .NET or JVM feature to achieve the desired results.

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 and run as single sessions each independent of each other and are not ready for running in a multi-user environment. If you try to run several instances of the same application simultaneously, you can get issues such as file locking and memory isolation breaking down because suddenly the same resource set is being used by multiple users.

It is possible to fix this with rewriting the code but that would require significant code changes.

Micro Focus Enterprise Developer 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 will 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 will not be accessible to a file handling program in another Run Unit in the same process.

Run Units are specified by the runtime assembly Micro Focus Runtime (Interop RuntimeServices) (which appears as a MicroFocus.COBOL.RuntimeServices reference in your project) (for .NET) and the runtime class com.microfocus.cobol.runtimeservices.RunUnit (in JVM COBOL).

In JVM COBOL, the class com.microfocus.cobol.runtimeservices.servlet.ServletRunUnitManager exists to handle the life cycle of Run Units in the context of servlet API HttpSession objects.
  1. Compile the COBOL program that you want to call to produce the required output files.
  2. Call the COBOL program in 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.

  3. Include the run-time support for multiple Run Units, by adding a reference to the Micro Focus Runtime (Interop RuntimeServices) assembly (in Visual Studio) or importing the com.microfocus.cobol.runtimeservices.RunUnit class (in Eclipse).

Note that you leave the existing procedural COBOL unchanged.

Run Units and SQL

Managed COBOL code (including any programs, classes, enum, or valuetypes) that uses EXEC SQL statements must be used in a managed RunUnit with the exception of .NET code executing under the control of the SQL Server as SQLCLR stored procedures or types. This is because this code is automatically executed in managed RunUnits so no change is required for these applications.

If the code being executed requires to be executed in a multi-user environment or a thread pool environment, then the use of managed RunUnits is also recommended but not required provided that the code is naturally coded for thread-safety.

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

Create a managed project

First, you need to create a managed COBOL project to hold the procedural program and the wrapper class:

  1. In Eclipse, create a managed COBOL project - click File > New > COBOL JVM Project.
  2. Specify a name such as calclib, and click Finish.

    This creates a calclib project in your workspace. The project does not include any COBOL programs or class files.

  3. Add a program to hold your procedural code - right-click the project, and click New > COBOL Program.

    This opens the New COBOL Program wizard, which will create the program in the src subfolder of the project, and will add it to the default package.

  4. Specify Calc.cbl in the Name field, and click Finish.

    This adds the new program to the project and opens it in the editor.

  5. Replace the code in the program with the following:
           program-id. Calc.

       data division.
       working-storage section.

       linkage section.
       01 operands.
         03 op1 pic 9(4) comp-5.
         03 op2 pic 9(4) comp-5.

       01 the-result pic 9(8) comp-5.

       01 func-code pic x.
       78 add-op value '+'.
       78 sub-op value '-'.
       78 mult-op value 'x'.
       78 div-op value '/'.

       procedure division using by reference func-code operands the-result.

           evaluate func-code
              when add-op
                 add op1 to op2 giving the-result
              when sub-op
                  subtract op2 from op1 giving the-result
              when mult-op
                   multiply op1 by op2 giving the-result
              when div-op
                    divide op1 by op2 giving the-result
           end-evaluate.

           goback.

       end program Calc.
  6. Click File > Save to save the change.

    By default, Eclipse is set to build projects automatically so saving your changes starts a build. Your project should compile without any errors.

Create wrapper classes

You are now going to create one of the wrapper classes for the procedural program:

  1. Add a new managed COBOL class to the project - right-click the project, and click New > COBOL JVM Class.

    This starts the New COBOL JVM Class wizard. You are going to create a public class in the default package that will be saved in the src subfolder of the project.

  2. Specify a name such as WrapperClass, and click Finish.

    This adds the file to the project and opens it in the editor.

  3. Replace the code in WrapperClass with the following and save the file:
           class-id calclib.WrapperClass.

       working-storage section.

       method-id Add.
       local-storage section.
       01 operands.
         03 op1 pic 9(4) comp-5.
         03 op2 pic 9(4) comp-5.

       linkage section.
       01 the-result pic 9(8) comp-5.

       procedure division using by value p1 as binary-short
                                         p2 as binary-short
                                         returning the-result.

           move p1 to op1
           move p2 to op2

           call "calc" using '+' operands the-result

           goback.
       end method.

       end class.

    WrapperClass defines a method, Add, which uses the same comp-5 data items which are used in the procedural code program. The method maps op1 and op2 to the variables p1 and p2 which are of the equivalent type in managed code. The method then calls the procedural program to perform the addition operation.

    Other managed languages can invoke the Add method using the OO syntax in order to access the functionality of the original procedural program.

  4. The methods for the other three arithmetic operations in the procedural program are not included in this topic so you can write these now.

You are now going to create a slightly different wrapper class that will use a Data Transfer Object (DTO) also known as a property class. You are going to expose the data items in the original program as properties of the wrapper class in order to pass them to other managed languages.

  1. Add a new COBOL JVM class, ClassDTO, to the project and paste the following code to it:
           class-id calclib.ClassDTO.

       working-storage section.

       01 operands property all elementary.
         03 op1 pic 9(4) comp-5.
         03 op2 pic 9(4) comp-5.

       method-id Add.
       linkage section.
       01 the-result pic 9(8) comp-5.
       procedure division returning the-result.

            call "calc" using '+' operands the-result

           goback.
       end method.

       end class.

    The use of the property all elementary on operands means that all elementary group items are exposed as properties of ClassDTO and can be accessed by other managed programs using the OO syntax (for example, ClassDTO::op1 if accessed by other managed COBOL programs).

    ClassDTO defines a similar method Add which calls the procedural program to perform the arithmetic operations.

    An alternative of using the property keyword on the entire group item would be to set it on each individual data item as follows:

           01 operands.
         03 op1 pic 9(4) comp-5 property as "Operand1".
         03 op2 pic 9(4) comp-5 property as "Operand2".

    This would expose only the individual data items as properties of the class under new names, Operand1 and Operand2.

  2. You can now write the methods for the other arithmetic operations in the procedural program.

Write a managed front-end application in COBOL

You are now going to create a project for a front-end application written in managed COBOL that will communicate with both wrapper classes:

  1. Create a new COBOL JVM project - click New > COBOL JVM Project.
  2. Specify a name such as OOCalc, and then click Finish.
  3. Add a new COBOL program to the project, Program1.cbl, and add to it the managed COBOL code that will interact with the wrapper classes in the calclib project:
           program-id. Program1 as "OOCalc.Program1".

       data division.
       working-storage section.

       01 calc1 type calclib.WrapperClass.
       01 the-result pic 9(8) comp-5.

       01 calc2 type calclib.ClassDTO.

       procedure division.

           set calc1 to new type calclib.WrapperClass
           set the-result to calc1::Add(2, 2)

            set calc2 to new calclib.ClassDTO

            set calc2::op1 to 5
            set calc2::op2 to 4

            set the-result to calc2::Add

           goback.

       end program Program1.

    The automatic build fails to compile the code as it does not recognize the classes calclib.ClassDTO and calclib.WrapperClass from the calclib project. To resolve this, you need to add the calclib project to the JVM build path for the OOCalc project.

  4. Right-click OOCalc, and click Properties.
  5. Click Micro Focus > JVM Build Path.
  6. Click the Projects tab, and then click Add.
  7. Enable the checkbox in front of calclib, and then click OK.

    As calclib is now on the JVM build path for OOCalc, the code in OOCalc finds the classes defined in calclib and the subsequent build is successful.

    Program1.cbl defines two objects - calc1 of type of WrapperClass and calc2 of type ClassDTO.

    During the program execution, the code creates instances of calc1 and calc2. Then, the example code demonstrates how to create an instance of calc1 and invoke the Add method in WrapperClass to perform the addition operation.

    Next, an instance of calc2 is created and it accesses op1 and op2 that are exposed as properties of ClassDTO to assign them values. Then, the Add method of ClassDTO is invoked to perform the addition.

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.

Note: The names of the project you are going to create for this demonstration are the same as the ones used for the example of using a wrapper classes. If you have already created the projects for that example, you might need to switch to a different workspace Eclipse does not support projects with the same name in a single workspace.

Create a managed project

First, you are going to create a project to hold the procedural program:

  1. In Eclipse, create a COBOL JVM project - click File > New > COBOL JVM Project.
  2. Specify a name such as calclib, and click Finish.

    This creates a calclib subfolder for your project in the specified location. Next, you need to create a program to hold your procedural code.

  3. Right-click the project, and click New > COBOL Program.
  4. In the New COBOL Program dialog, specify a name such as Calc.cbl, and click Finish.

    This creates the program in the src subfolder of the project, in the default package, and opens the program in the editor.

  5. Replace the code in the program with the following and save the file:
           program-id. Calc.

       data division.
       working-storage section.

       linkage section.
       01 operands.
         03 op-1 pic 9(4) comp-5.
         03 op-2 pic 9(4) comp-5.

       01 the-result pic 9(8) comp-5.

       01 func-code pic x.
       78 add-op value '+'.
       78 sub-op value '-'.
       78 mult-op value 'x'.
       78 div-op value '/'.

       procedure division using by reference func-code operands the-result.

           evaluate func-code
              when add-op
                 add op-1 to op-2 giving the-result
              when sub-op
                  subtract op-2 from op-1 giving the-result
              when mult-op
                   multiply op-1 by op-2 giving the-result
              when div-op
                    divide op-1 by op-2 giving the-result
           end-evaluate.

           goback.

       end program Calc.

    When the automatic build completes, there should be no errors.

    This variant of the example uses hyphenated variables, op-1 and op-2, to illustrate how ILSMARTLINKAGE deals with these.

  6. In the IDE, navigate to the project properties, expand Micro Focus, and click Build Configurations.
  7. Type ILSMARTLINKAGE in the Additional directives field.
  8. Click Apply, and then click OK.

    Compiling with ILSMARTLINKAGE exposes the group item in the program as a new class, and the group items as properties of that class. Other managed languages do not recognize hyphenated data items but ILSMARTLINKAGE caters for that as well - it removes the hyphens from the names of the data items and changes the case to camel case. As a result, other managed languages will see operands exposed as the class Operands, and the variables op-1 and op-2 exposed as the properties Op1 and Op2 of that class. Similarly, func-code is exposed as FuncCode.

Write a front-end application

Next, you are going to create an application in managed COBOL that will access the group item entries of the procedural code in the calclib project which are now exposed as a class and its properties:

  1. Create a new COBOL JVM project - click File > New > COBOL JVM Project.
  2. Specify a name such as OOCalc, and then click Finish.
  3. Create a new managed class Class1 in the project - right-click the project and click New > COBOL JVM Class.
  4. Click Finish.

    This creates Class1.cbl in your project and opens the file in the editor.

  5. Replace the code in the class with the following code that will access the group items in the procedural code:
           class-id OOCalc.Class1.

       working-storage section.
       78 add-op value '+'.
       78 sub-op value '-'.
       78 mult-op value 'x'.
       78 div-op value '/'.

       method-id. main static.
       procedure division.
          declare calculation as type Class1
          set calculation to new Class1
          invoke calculation::Add()
       end method.

       method-id Add public.

       local-storage section.
       01 operand type Operands.
       01 CalcOO type Calc.
       01 func-code type FuncCode.
       01 result pic x(4) comp-5.

       procedure division.

       set func-code to new FuncCode()
       set operand to new Operands()

       set operand::Op1 to 1.
       set operand::Op2 to 2.

       set CalcOO to new Calc()
       set func-code::FuncCode to add-op

       invoke CalcOO::Calc(func-code, operand, result)
       display "The result is " result

           goback.
       end method.

       end class.

    The automatic build fails to compile the code as it does not recognize the types Calc, FuncCode and Operands. To resolve this, you need to add the calclib project to the JVM Build Path for OOCalc.

  6. Right-click OOCalc, and click Properties.
  7. Expand Micro Focus, click JVM Build Path.
  8. Click the Projects tab, and then click Add.
  9. Enable the checkbox in front of calclib, and then click OK.

    As calclib is now on the JVM build path for OOCalc, the code in OOCalc now finds the classes defined in calclib and the subsequent build is successful.

    In Class1, you define the static method main which is the main entry point for your program. main defines the object calculation of type Class1, and then executes the Add method of Class1.

    The code defines the method Add that uses as variables the following objects - operand of type Operands (the group item from the procedural program now exposed as a class); CalcOO of type Calc (the procedural program now seen as a class); func-code of type FuncCode (which is how func-code in the procedural program is exposed).

    You then create instances of func-code, operand, and CalcOO, give values to op-1 and op-2 in the procedural program, specify that you would like to invoke the add-op operation, and invoke the procedural code using func-code, operand and result as parameters to perform the arithmetic calculation - invoke CalcOO::Calc(func-code, operand, result).

Parent topic: Moving Native COBOL Applications to Managed COBOL


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 Enterprise Developer 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 Managed 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"notep

       program-id. c.

        display "INFO: in C"
        display "PASS"

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 prompt, you must use the runm command rather than the run command (applies to Windows environments only).

To run a multi-threaded application from the command line, use the cobrun_t command (applies to UNIX environments only).

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(UNIX only): 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:

  • PARAMCOUNTCHECK - Controls checking of number of entry point parameters
  • 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:

  • NOPARAMCOUNTCHECK
  • 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 whilst in the testing/implementation phase, so that you have a set of results from an application performing at an acceptable level, with which to compare with 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 took 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 PL/I Syntax
    This section covers a range of techniques to streamline the general PL/I syntax.
  • Optimizing Other Areas
    This section covers other syntax and configuration optimizations that are particular to other areas or technologies of Enterprise Developer.
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 Enterprise Developer 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 later.

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 took your benchmarking results, you need to perform a diagnosis to locate the problem.
Enterprise Developer 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 (http://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. For the best performance it is often better to compile to native COBOL code, using a number of simple operations rather than one complex operation.

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.

  • Optimizing Data Definitions
    Defining data items appropriately and aligning them to give the best performance.
  • Optimizing Arithmetic Statements
    Arithmetic operations are at their most efficient when kept to simple two-operand statements.
  • 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 Exponential Operations
    Depending on the exponent, some exponential operations are optimized; for others, use MULTIPLY and DIVIDE operations.
  • Initializing Data Items
    By default, COBOL initializes all data items to spaces or the value specified by the DEFAULTBYTE directive, except for those items given a VALUE clause.
  • Optimizing Data Manipulation and Reference Modification
    Data manipulation through reference modification is optimized depending on the structure of the code.
  • 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 Logical Operations
    Logical operations, such as AND, OR and XOR are, if possible, optimized to produce in-line code.
  • 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 unsigned 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 native code programs, it is more efficient to move integer data items that are not COMP-X or COMP-5 to COMP-5 data items before doing arithmetic operations on them.

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 and use only simple ones such as ZZ9. If possible, use them in a subroutine so that the total number of edited moves in your program is kept to a minimum.

  • 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 Arithmetic Statements

For the best performance from arithmetic statements use simple two-operand arithmetic statements wherever possible. The following operations are optimized for COMP-5 and COMP-X data items up to four bytes long:

 MOVE a TO b
 ADD a TO b
 SUBTRACT a FROM b
 MULTIPLY a BY b
 DIVIDE a INTO b
 IF a condition b

where:

a Is a numeric literal value or data item up to four bytes long.

b Is a numeric data item up to four bytes long.

On other data items, these simple operations result in faster code than more complex instructions, but the benefits are not as great as with COMP-5 or COMP-X items. More complex forms of these instructions, involving more than two operands, might not produce code which is as efficient as the simple form.

Other recommendations for optimizing arithmetic statements include:

  • Do not use the GIVING form of the above verbs. If necessary, create temporary data items and code several simple statements to achieve the same result. For example, write:
     MOVE a TO c
 ADD b TO c

    rather than:

     ADD a TO b GIVING c

    However, if the operands are all of the same type, statements that contain the GIVING phrase are optimized.

  • Do not use the REMAINDER, ON SIZE ERROR or CORRESPONDING phrases.
  • When using the simple operations described above on COMP-5 or COMP-X items, do not use the ROUNDED phrase. In other situations, although the ROUNDED phrase impacts performance, but it is generally faster to use ROUNDED than try to round the result using your own routine.
  • Do not mix items of different sizes in an arithmetic statement (for example, try to use all two-byte items or all four-byte items).
Parent topic: Optimizing COBOL Syntax


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 Exponential Operations
Optimizing Decimal Point Alignment
Initializing Data Items


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 Exponential Operations
Optimizing IF Statements
Initializing Data Items


Optimizing Exponential Operations

Exponential operations in which the exponent is 0.5 (square root), 2 (square) and 3 (cube) are optimized. Other exponential operations are relatively slow as no optimization is carried out by default. Where integer powers are involved, use MULTIPLY and DIVIDE operations instead.
Note: For managed COBOL, you can optimize exponential operations using the ILEXPONENTIATION Compiler directive.
Parent topic: Optimizing COBOL Syntax
Related reference
Optimizing Decimal Point Alignment
Optimizing IF Statements
Initializing Data Items
ILEXPONENTIATION


Initializing Data Items

By default, COBOL initializes all data items in the Working-Storage Section to spaces if no VALUE clause is specified. This includes all numeric items. The effect of arithmetic operations on such an item depends on how the item is used:

Usage | Effect of arithmetic
DISPLAY and COMP-3 | Intermediate code reports run-time error 163 ("Illegal character in numeric field"). Generated code gives unpredictable results.
Any other | Results are unpredictable.

To avoid these problems, initialize all numeric items to numeric values before use, either explicitly or by setting the INIT-BY-TYPE Compiler directive.

Parent topic: Optimizing COBOL Syntax
Related reference
Optimizing Exponential Operations
Optimizing Decimal Point Alignment
Optimizing IF Statements
INIT-BY-TYPE


Optimizing Data Manipulation and Reference Modification

When using the MOVE, INITIALIZE, STRING and UNSTRING statements, reference modified fields are optimized if coded in one of the following forms:

item (literal:)
item (literal:literal)
item (literal:variable)
item (variable:variable)
item (variable + literal:literal)
item (variable - literal:literal)
item (variable + literal:variable)
item (variable - literal:variable)

Other forms of reference modification are inefficient.

If the offset or length of the reference modification is a data item, use a COMP-5 item of the smallest optimum size (one, two or four bytes) that accommodates the range of values involved. Define it in the Working-Storage Section. With this COBOL system, use a four-byte COMP-5 item.

In a MOVE statement, the source item should be the same size as, or larger than, the target. This prevents space-padding code from being generated.

If you try to implement a MOVE between two numeric-edited items, the result is undefined although no error status is returned.

Do not use the CORRESPONDING option of the MOVE statement.

Do not use the INITIALIZE statement.

The STRING or UNSTRING statements can create a large amount of code; therefore, to manipulate file names, use the COBOL system library routines CBL_SPLIT_FILENAME and CBL_JOIN_FILENAME. For other purposes, create your own loops as they are almost always more efficient.

Parent topic: Optimizing COBOL Syntax
Related reference
The MOVE Statement
INITIALIZE Statement
STRING Statement
The UNSTRING Statement
USAGE Clause
CBL SPLIT FILENAME
CBL JOIN FILENAME


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 of the smallest optimum size that accommodates the range of values involved. The optimal size for a subscript is four bytes.

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
Example of Optimizing USAGE DISPLAY Subscripts
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

Do not use 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.

GO TO Statements

Use a GO TO ... DEPENDING statement if the range of possible values is fairly close. Although this construct is not particularly suited to structured programming, it is efficient.

Related reference
The IF Statement
The EVALUATE Statement
The GO TO Statement


Optimizing Logical Operations

A number of COBOL System Library Routines (call-by-name) are available to perform bitwise logical operations on data items. They perform operations such as AND, OR and XOR.

The Compiler recognizes calls to these routines and, if possible, optimizes them to produce in-line code rather than calls to the run-time system. In-line code is native code which performs the function directly without making any calls. The alternative is a call to a generic run-time routine which must allow for many cases.

The calls are optimized if the length is specified as a literal value. Logical AND and logical OR operations can also be carried out using the VALUE clause.

Parent topic: Optimizing COBOL Syntax
Related reference
Manipulating Bits


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. The presence of an ALTER statement in a program prevents optimization of PERFORM 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
Optimizing Logical Operations
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 the 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
  • Example of Optimizing USAGE DISPLAY Subscripts
Parent topic: Optimizing COBOL Syntax


Example of Inefficient Use of the PERFORM Statement

An example of code that uses PERFORM in a way that might give unexpected results, becuase they depend on the setting of the “perform-type” directive. 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


Example of Optimizing USAGE DISPLAY Subscripts

The following code shows the use of USAGE DISPLAY subscripts:

  ...
 01 array   pic x occurs 20.
 01 array-index pic 9(5) value 2.
  ...
     move "a" to array(array-index).
  ...

If the program is compiled without BOUNDOPT, all five digits of array-index are used to evaluate the subscript. If BOUNDOPT is specified, only the last two digits of array-index are used, as only two digits are needed to access all elements of a 20 element table. However, it is much more efficient to use comp-5 subscripts.

Parent topic: Examples
Related information
Optimizing Table Handling


Optimizing PL/I Syntax

This section is intended to provide tips and techniques that enables you to produce highly efficient PL/I applications.

There are many factors that affect an application's performance. These include the choice of task-solving algorithms; choice of implementation language; choice of hosting system/subsystem; choice of computer hardware; etc...

PL/I is an extremely powerful programming language that provides multiple ways of accomplishing the same task; some ways are inherently more complex and thus slower, while others are much more efficient. In some cases, the complex feature may be the only choice. Generally, keeping to the most suitable and simple language features, such as using the most appropriate data types, data structures, and logic constructs, often results in the best performance.

The following topics suggest ways to use language features of PL/I that will result in efficient, yet highly maintainable applications.

  • Constants vs Variables
  • Restricted Expressions
  • Expressions and Assignments
  • Data Types - Arithmetic
  • FIXED BINARY Endian-ness
  • Data Types - Strings
  • Storage Classes
  • Arguments and Parameters
  • Arrays, Structures, and UNIONs
  • Adjustable Arrays and Structures
  • Data Type Conversions
  • Input/Output
  • Language Constructs
  • Preprocessors
  • Compile-time Options
  • Enterprise Server Considerations
  • Tracing and Instrumentation
Parent topic: Performance Programming


Constants vs Variables

If an operand you are using in a PL/I expression, BUILTIN, or any other language construct is a constant value, use a constant, rather than a variable that has been initialized to that constant value; for example:

%replace array_dim by 10; /* or */
DCL array_dim fixed bin(31)
value(10); /* this is a constant NOT a variable */

and

DCL array(array_dim10) fixed bin(31);

is the same as:

DCL array(10) fixed bin(31);

Which is significantly more efficient than:

 DCL arrray_dim fixed bin(31)init(10);
DCL array(array_dim10) fixed bin(31);

Using constant values or compile-time expressions, in many cases, enables the compiler to generate code and/or initialize the data area at compile time, rather than the required code being generated at execution time.

Parent topic: Optimizing PL/I Syntax


Restricted Expressions

Restricted expressions are expressions that can be evaluated at compile time. Operands of such expressions include constants, %replace constants, named constants, and built in functions whose arguments are constants and named constants. These expressions speed up your program's execution, because some or part of these are evaluated when the program is compiled.

Using restricted expressions improves program readability, understanding, and maintainability.

Parent topic: Optimizing PL/I Syntax


Expressions and Assignments

Certain operations can cause fairly long sequences of generated code. Some of these include:

  • || (concatenation) involving operands of non-constant length and/or non-constant starting position.
  • For certain BUILTINs, such as VERIFY, TRANSLATE, etc..., that build large tables (typically 256 bytes), avoid certain run-time evaluated arguments; for example, in the following example of TRANSLATE, which converts all commas and periods to blanks, the first usage is much better performing than the second:
    • target = TRANSLATE(source, ' ', ',.');
    • target = TRANSLATE(source, two_blanks, comma_period); DCL (two_blanks init(''), comma_period init(',.')) char(2) static;
  • Operations on differing operand types; for example:
    DCL f fixed bin(31) init(1111);
DCL c char(8);
c = ‘1234’;
f = f + c;

    Require a conversion from character to fixed binary before the addition can take place.

    Another example:

    c = c + f;

    Requires c to be converted from a character (to fixed binary), and then converted back after the addition. In such cases, declare c as fixed bin(31);

  • In an iterative DO statement, if the BY value is negative, the control variable is decremented by the BY value until it is <= the TO value. This means that unless the BY value is a signed constant, the compiler must generate code that can handle a decrementing as well an incrementing loop. When possible, use a constant value for BY.
Parent topic: Optimizing PL/I Syntax


Data Types - Arithmetic

The arithmetic data types are listed below in the order of their efficiency (most efficient first). Most working variables should use the FIXED BIN(31) data type.

  • FIXED BIN(31), FIXED BIN(15), FIXED BIN(7)
  • FLOAT BIN(21)/DEC(6), FLOAT BIN(53)/DEC(16)
  • FIXED DEC
  • PIC all 9s

To ensure that you do not get the wrong implicit attributes and/or precision, for non-PIC items always specify at least FIXED or FLOAT and BIN or DEC with appropriate precision. Micro Focus recommends that you use the -nolaxdcl compiler option to warn if you are not following these guidelines, in addition to getting warnings for contextual declarations.

The following data types are highly discouraged as arithmetic data types:

  • PIC with other picture characters
  • BIT
  • CHAR [VARYING]
  • GRAPHIC [VARYING], WIDECHAR [VARYING]
Parent topic: Optimizing PL/I Syntax
Related reference
Compiler Options


FIXED BINARY Endian-ness

PL/I supports FIXED BINARY (and the length field of VARYING strings) to be stored in NATIVE (default and native to the machine) order, or in BIGENDIAN order, which may also be the native order of the machine. When BIGENDIAN order is used on LITTLEENDIAN machines, extra instructions need to be generated when the compiler stores or fetches the contents of FIXED BINARY fields.

Use the -bigendian compiler option when mainframe files are being accessed and/or you have FIXED BINARY(31) overlaid on POINTER for arithmetic purposes and/or you are relying on the order of bytes within a FIXED BINARY field.

Parent topic: Optimizing PL/I Syntax
Related reference
Compiler Options


Data Types - Strings

String data (CHAR and CHAR VARYING) may hold data that is either EBCDIC or ASCII.

Use the -ebcdic compiler option when mainframe files are being accessed and/or you require the character comparisons to be compatible with z/OS. This option will use the EBCDIC collating sequence when performing character comparisons, and may cause the compiler to generate extra code.

Parent topic: Optimizing PL/I Syntax
Related reference
Compiler Options


Storage Classes

It is important to understand PL/I storage classes. Each has its advantages and disadvantages.

STATIC

Static storage is allocated and initialized (if INITIAL attribute applies) at compile time. A large amount of static storage makes the size of the executables larger and can lead to longer load times at run time. Any modification of static storage may leave a program in a differing state to its original, and produce incorrect results on subsequent invocations.

If you do modify static storage, make sure it is left in the same state as it was before program execution began. This is known as serially reusable state, and is particularly important for programs running under Enterprise Server (CICS, IMS, and JCL batch), because the programs are generally kept in storage (not reloaded) to improve system performance. In general, this storage class should be used for all 'read-only' storage; for example:

Dcl report_name char(132) static
init('Year to date Performance Report');

Static storage is freed only when the executable containing it is physically deleted. Depending on the operating system, logically deleted executables may get reused with static storage in its last used state.

AUTOMATIC

Automatic storage is allocated and initialized (if INITIAL attribute applies) at run time upon entry to the block (PROCEDURE or BEGIN) in which it is declared. The allocation scheme is the most efficient of all dynamically allocated storage schemes and costs almost nothing. The initialization is the same as an equivalent assignment made to the subject variable. Any changes to such storage may be left as they are, because upon next entry to the block, this storage will be re-allocated and re-initialized.

Automatic storage is automatically freed upon block exit. Any freed storage (all or some of it) is reused by the allocation of automatic storage upon next invocation of the existing or a different block.

This storage class should be used for all working storage. This storage class is inherently suitable for re-entrant code.

BASED

Based storage is allocated and initialized (if INITIAL attribute applies) by the use of the ALLOCATE statement at run time, and is completely under programmer control. ALLOCATE statements allocate storage on the heap via calls to library routines, and effectively generate assignments for the initialization values. The allocation scheme is costly, but it does give the programmer total control over when storage is allocated and how long it lives for before it is freed. This storage is generally good for allocation of objects that need to exist when the program logic warrants it, or are of large or varying sizes. Any changes to such storage may be left as they are.

Based storage is freed using the FREE statement, and is managed by an address held in a locator variable (generally a POINTER, but also an OFFSET) and may be allocated multiple times using a unique locator for each allocation. Storage may be allocated or freed without any order as long a unique locator is used. This storage class is used to maintain lists of data that dynamically grow and shrink.

This storage class should be used when the existence and lifetime of the storage depends on application processing being carried out. This storage class is also inherently suitable for re-entrant code.

Note: Another way to allocate based storage is by setting the locator to the address of another object using the ADDR or ADDRDATA BUILTIN. When this mechanism is used, storage must not be FREE(d) since it was never ALLOCATE(d).
CONTROLLED

Controlled storage is like based storage; it is allocated using the ALLOCATE statement and freed using the FREE statement, but with these important differences:

  • You do not have a locator. PL/I manages the locator on your behalf.
  • The ALLOCATE statement 'pushes down' the current generation (if any) before allocating the new one.
  • The FREE statement frees the current generation and 'pops up' the previous (if any) generation.
  • Any access to the variable will always access the current generation. Only the current generation is visible. All pushed generations are hidden.
  • This allocation scheme is more costly than based, but potentially has more powerful uses.

This storage class should be used for all storage that must be managed as a push down stack where the most recently allocated generation will be freed first. This storage class is also inherently suitable for re-entrant code.

Parameter
Parameter storage, for completeness, is nothing more than a way to map the parameter on the corresponding argument in the invocation of the procedure containing the parameter.
Parent topic: Optimizing PL/I Syntax


Arguments and Parameters

Arguments are references or expressions in the invocation (CALL statement or function reference) of the procedure. Parameters are names by which those arguments can be accessed in the invoked procedure.

By default, arguments are passed by reference. In this case, any change to the parameter is reflected back in the argument, assuming the argument is a reference that has not caused a temporary argument to be created. Such argument/parameter pairs can be input (to the invoked procedure) only, output (from invoked procedure) only, or input and output.

Another way to pass arguments is BYVALUE. BYVALUE arguments are more efficient, but any change to the parameter is never reflected back in the argument. Thus, such argument/parameter pairs are input (to the invoked procedure) only.

Most suitable arguments that can or should be passed BYVALUE are those that fit in a 4-byte (32-bit) or 8-byte (64-bit) field, which can in some cases be passed in machine registers. FIXED BIN, FLOAT, and POINTER are the most common data types that are passed BYVALUE.

Parent topic: Optimizing PL/I Syntax


Arrays, Structures, and UNIONs

By default, most PL/I data is ALIGNED. String data, with IBM compatibility compiler options, by default is UNALIGNED. CHAR VARYING data is unaligned unless you specify the ALIGNED attribute. In general, aligned data gives you better performance.

It is good practice to not allow the compiler to insert padding bytes. Use the compiler option -map to produce the compiler listing; within the listing, look for -pad- which indicates compiler-inserted pad bytes. You can then design your data structures such that you do not give the compiler the opportunity to add padding bytes.

If you are compiling existing 32-bit designed programs in 64-bit mode, it is very likely that you will get padding that you did not get in 32-bit compiled programs. This can occur because POINTERs are now aligned on an 8-byte boundary, whereas they were previously aligned on a 4-byte boundary. In general, there is no reason to be alarmed but you must be aware of this extra padding and thus the change in the size of the structure.

This change may affect other assumptions on your part, which may or may not affect performance. For example:

DCL 1 LIST, 2 next ptr, 2 f fixed bin(31), 2 prev ptr, 2 data char(16);

SIZE(LIST) is 28 on 32-bit systems (no padding) but is 40 (8 + 4 + 4 byte pad + 8 + 16) on 64-bit systems.

UNIONs are the most efficient way to overlay data of like or un-like types. For example:

DCL 1 st, 3 * union,
                     5 binval fixed bin(15),
                     5 *,
                         7 hi_char char(1),
                         7 lo_char char(1);

is much more efficient than:

DCL binval fixed bin(15);
DCL 1 st based(addr(binval)),
                         7 hi_char char(1),
                         7 lo_char char(1);
Parent topic: Optimizing PL/I Syntax


Adjustable Arrays and Structures

Arrays and structures (and even scalars) are said to be adjustable when array extents (upper and/or lower bounds), string (CHAR, GRAPHIC, WIDECHAR, and BIT) lengths, and/or AREA sizes are not known at compile-time, but are determined at run-time based on program logic. Such data can be declared using a BASED storage class with the REFER option, or by using run-time expressions using BASED or AUTOMATIC storage classes. BASED with REFER is a safer approach and always the correct method if the data defined by such structures is transmitted using I/O statements.

An example of BASED storage with REFER:

dcl (an, cn) fixed bin(31), DCL p ptr;
dcl 1 s based(p),
         3 x char(4) init('PL/I'),
         3 (as,cs) fixed bin(31),
         3 array(an refer(as)) char(cn refer(cs));
an = 12;
cn = 16;
allocate s;

Having the last and the only member adjustable is the most efficient method. The more REFERs you have, the longer the generated code sequences are to manipulate the data. You need to be aware that there is a price to be paid for complex uses, but sometimes it may be worth it.

An example of BASED storage without REFER:

dcl (an, cn) fixed bin(31), DCL p ptr;
dcl 1 s based(p),
         3 x char(4) init('PL/I'),
         3 array(an) char(cn);
an = 12;
cn = 16;
allocate s;

An example of a scalar:

dcl (an) fixed bin(31);
an = 12;
begin;
   dcl work char(cn);
   /* ... */
end;

This use is the most efficient example, mostly because it naturally limits you to a minimal number of simple REFERs.

Parent topic: Optimizing PL/I Syntax


Data Type Conversions

The PL/I compiler must generate code to perform conversions when operand data types differ. Whenever possible, use operands of the same type (for example, all FIXED BINARY, all FIXED DEC, or all CHAR).

Parent topic: Optimizing PL/I Syntax


Input/Output

PL/I has very rich I/O capabilities. Record I/O is the most efficient, and STREAM I/O is the least efficient. If you must use STREAM I/O, LIST-directed is the best form to use, followed by EDIT-directed, and lastly DATA-directed.

It is a good practice to:

  • Declare files with all attributes.
  • Explicitly OPEN a file when needed, and CLOSE when done.
  • Establish ON units to handle I/O conditions.
  • Use 'move mode' (that is, READ FILE(x) INTO(s)) for record I/O, as it is the most efficient method.

DISPLAY [REPLY] is generally not suitable for production programs, and should be restricted to use only as a 'quick and dirty' debug aid.

See Enterprise Server Considerations to determine if I/O is suitable in mainframe subsystem environments.

Parent topic: Optimizing PL/I Syntax
Related reference
Record File Attributes
Enterprise Server Considerations


Language Constructs

The following list contains some general performance-related tips and recommendations of the PL/I language.

  • Avoid the use of LABEL variables.
  • Do not use the GOTO statement except to transfer control out of an ON unit. Use LEAVE or RETURN instead.
  • For never-ending loops, use DO LOOP (or DO FOREVER), and LEAVE to exit the do loop when exit conditions are met.
  • For flags, use BIT(1) rather than fields of other types, and combine related flags into the same byte using a structure. Testing such combinations of flags using and/or (&/|) can result in fewer and faster instructions.
  • When testing a non-BIT variable, it is best to include both operands; for example, IF index ^= 0, and not IF index.
  • Avoid implicit comparisons; for example, assuming all operands are BIT(1), it is better to use
      b1 = ''b; IF b2 = b3 then b1 = '1'b; rather than
      b1 = b2 = b3;, which is effectively
      IF b2 = b3 then b1 = '1'b; else b1 = '0'b;
  • If possible, it is recommended to order statements/expressions in order of probability, specifying the most likely comparisons (of being true or false) before others that are less likely.
  • Make use of the REPEAT, UNTIL, WHILE syntax to express program logic: the Compiler will ensure these are processed in the most efficient manner.
  • The SELECT...WHEN...OTHERWISE statement group leads to better program readability and maintainability, and can generate more efficient code than nested IF statements. When using a SELECT group, it is good practice to code an OTHERWISE statement; when one is not coded, the Compiler effectively inserts an OTHERWISE SIGNAL ERROR; statement.
  • Do not use excessive amounts of modularization by creating lots of tiny procedures.
  • Avoid BEGIN statements unless they are the body of an ON-unit, or you need to dynamically allocate an unusual amount of automatic (and possibly only dynamically/demand-needed) storage.
  • Compound statements allow the Compiler to 'see' the target and generally allow for better code generation, particularly for operations such as concatenate (||) that require potentially large temporaries; for example;
    • Target += expression; is better than Target = Target + expression;
    • Target ||= expression; is better than Target = Target || expression;, but works only if Target is VARYING.
    • Do not take advantage of the Compiler closing multiple groups (DO, SELECT) or blocks (BEGIN, PROCEDURE) with a single END statement. It will very likely be incorrect and may impact performance.
    • Multiple entry points (ENTRY statements) in a procedure my result in extra instructions to remap parameters and/or tests to determine use of parameters. If the procedure is a function, it is better to have all entry points be functions, and have them return the same data type. Differing return types can cause conversion code to be generated under the control of a possibly complex Compiler-generated SELECT group.
  • If you are using the FETCH statement, the following:
    DCL fe entry[( …)] options(fetchable […]);
DCL fev entry variable;
fetch fe;
fev = fe;
Call fev [ (….) ]; /* note fev entry variable is being called here */

    is more efficient than:

    DCL fe entry[( …)] options(fetchable […]);
Call fe [ (….) ]; /* note fe entry constant is being called here */

    If appropriate, it may be beneficial to RELEASE a fetched entry when it is no longer needed.

  • When using dynamically allocated storage, if the application logic allows it, it can be more efficient to ALLOCATE storage when needed and FREE it when done. Also, if the application logic permits, it is much more efficient to use a BEGIN block for the life of the storage. AUTOMATIC storage is allocated with just a few instructions and freed with even fewer; for example;
    DCL some_storage char(some_len) based(stg_ptr),
Some_len = expression;
ALLOCATE some_storage;
[ … storage use .. ]
FREE some-storage;
    can be replaced by this much more efficient code:
    BEGIN;
DCL some_storage char(some_len) [AUTO];
[ … storage use .. ]
END;
Parent topic: Optimizing PL/I Syntax


Preprocessors

Preprocessors provide extended functionality to the PL/I language. They allow you to use:

  • PL/I preprocessor statements and PL/I macros for conditional compilation, which leads to better code usability and maintainability.
  • EXEC SQL statements to use relational databases managed by Oracle, IBM DB2 LUW, and SQL Server.
  • EXEC CICS statements to access CICS system facilities, to run PL/I programs as CICS transaction programs. These programs can also use EXEC SQL statements, and access IMS hierarchical databases by using EXEC DLI statements.
  • PL/I programs running as IMS transaction programs, accessing IMS hierarchical databases by using EXEC DLI statements. These programs can also use EXEC SQL statements.

These preprocessors generate native PL/I source that is then compiled by the PL/I compiler. Their use has no direct impact on execution performance of the PL/I programs.

Parent topic: Optimizing PL/I Syntax


Compile-time Options

The following Compiler options should only be set when developing applications, because they affect performance of PL/I programs:

  • -range
  • -noopt

The following compiler options may affect performance of PL/I programs, but usually only if you are using adjustable structures or arrays (run-time extents, string lengths, and area sizes) extensively with more than just the last member of a structure:

  • -zalign
  • -bitsltr (on Intel machines)

The following options result in the most optimized code:

  • -opt 3
Parent topic: Optimizing PL/I Syntax
Related reference
Compiler Options


Enterprise Server Considerations

In pursuit of better performance, an enterprise server tries to not delete (unload) loaded programs.

A program will generally be loaded once and reused time and time again. Therefore, it is necessary that you make you programs serially reusable. This means that when your program receives control, it will not lose control until it terminates. Also, by the time the program exits, it should have restored any STATIC variables back to their original state if they are relied upon by other programs.

These considerations apply to all mainframe subsystems: CICS, IMS, and JCL batch (until job step termination).

  • CICS Considerations
  • IMS Considerations
  • JCL Batch Considerations
Parent topic: Optimizing PL/I Syntax
Related concepts
Input/Output


CICS Considerations

For CICS applications, Micro Focus strongly recommends that you avoid all PL/I I/O (such as READ, WRITE, etc...) and storage allocation (ALLOCATE and FREE) features, and use solely the facilities provided by CICS via EXEC CICS statements. This guideline does not apply to CICS batch programs (running under JCL) using the EXCI interface to communicate from the batch program to programs running under CICS.
Parent topic: Enterprise Server Considerations
Related information
IMS Considerations
JCL Batch Considerations


IMS Considerations

For IMS applications, Micro Focus strongly recommends that you avoid all PL/I I/O (such as READ, WRITE, etc...), and use solely the facilities provided by IMS. This guideline does not apply to IMS batch message processing programs (BMPs) running under JCL.
Parent topic: Enterprise Server Considerations
Related information
CICS Considerations
JCL Batch Considerations


JCL Batch Considerations

Generally, the I/O recommendations discussed elsewhere in this section apply. In general, in this and other environments, you can use Dynamic Dataset Allocation (also known as Dynalloc or SVC99) to control the data sets you need, only when you need them, and only for as long as you need them. This adds some complexity to the application logic, but may allow the system to achieve greater through-put, since other users waiting for the same data set would need to wait for the job step to complete and release the data set allocation. If you are still using JES2 semantics, you may have to wait for END of JOB .

Parent topic: Enterprise Server Considerations
Related information
CICS Considerations
IMS Considerations


Tracing and Instrumentation

CTF tracing (using BUILTINs PLICTF and PLICTFHX, and other means), while extremely useful in diagnosing malfunctioning programs, can impact performance of PL/I programs. The same applies to any instrumentation you may have designed into the application.

Based on the nature of the application, you must decide on the right balance between performance and readily-available diagnostics. Micro Focus recommends protecting all CTF tracing with a bit flag on an IF-THEN statement, so that the tracing logic is only executed if/when you need it. As an example, you may be using concatenation of multiple variables, that requires not only expensive intermediate memory allocation but also data conversions; you do not want this logic executed in production mode unless you are trying to track down a specific problem.

Parent topic: Optimizing PL/I Syntax


Optimizing Other Areas

This section covers other syntax and configuration optimizations that are particular to other areas or technologies of Enterprise Developer.
  • CICS
  • Database Access
  • Enterprise Server
  • File Handling
  • IMS
Parent topic: Performance Programming


CICS

Whilst the Enterprise Server architecture around CICS applications is different to mainframe CICS applications, the majority of the design principles are the same, and are discussed at length on the IBM Knowledge Center (http://www-01.ibm.com/support/knowledgecenter/?lang=en).

For existing CICS applications, performance can be improved by ensuring that the CICSECM directive is not set for non-CICS programs in your application. CICSECM enables the CICS preprocessor, which inserts additional code into programs, and having these set on non-CICS programs causes unnecessary processing.

If you work from within an IDE, the Directives Determination process ensures that the CICS preprocessor is enabled accordingly, but if you are working outside of the IDE, you must ensure the directive is correctly set yourself.

Parent topic: Optimizing Other Areas


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


Enterprise Server

An enterprise server, both with and without mainframe subsystem support, has a number of diagnostics that can be active during run-time.

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.

There is a recommended strategy for setting the right level of diagnostics detailed in the Enterprise and COBOL Product Troubleshooting Guide, which can be downloaded from the Support Resources section of the SupportLine web site (http://supportline.microfocus.com/). Follow the details set out in this guide, and then tweak them for your specific needs.

As well as deciding on the level of diagnostics that will be active, you also need to consider the actual workload expected of the server; there are a number of factors to consider; see Performance Considerations.

  • Performance Considerations
Parent topic: Optimizing Other Areas


Performance Considerations

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

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

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


I/O-bound Services

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

Parent topic: Performance Considerations


CPU-bound Services

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

Parent topic: Performance Considerations


Short-running Client Requests

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

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

Parent topic: Performance Considerations


Long-running Client Requests

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

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

Parent topic: Performance Considerations


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


IMS

Depending on the platform that your IMS application is being deployed on, there are a number of programming techniques and environment variables that you may be able to employ that can benefit its performance.

  • Optimizing IMS Applications - General
    Your IMS applications can be optimized using a number of programming techniques and by removing unnecessary calls.
  • Optimizing IMS DB Applications
    Your distributed and mainframe IMS DB applications can be optimized using a number of config options and environment variables.
Parent topic: Optimizing Other Areas


Optimizing IMS Applications - General

Use the following tips to optimize your mainframe and distributed IMS applications:

  • Ensure that IMS TM applications are serially reusable - this is where the application loops through the message queue until all messages are processed before issuing a GOBACK, and releasing the Message Processing Region (MPR) for another program. When an application is not coded in this way, there is an increased overhead with every transaction.
  • Ensure that your Program Specification Block (PSB) does not contain Program Control Block (PCB) lists that contain references to unused databases, or that it contains unused PCBs that point to the same database. If it does, this can result in Application Control Blocks (ACB) that take up more storage space than is necessary. This problem can occur when a generic PSB has been cloned (for convenience) and your application does not require all the database access specified.
Parent topic: IMS
Related information
Optimizing IMS DB Applications


Optimizing IMS DB Applications

Use the following tips to optimize the access to your distributed and mainframe IMS DB applications:

Data and key compression (distributed only)
Improved functionality exists in Enterprise Server that should replace the use of mainframe segment compression exits. Configure these settings using Server > Properties > MSS > IMS > DB > Compression. For details of the settings, see the File Handling details for DATACOMPRESS and KEYCOMPRESS. The default settings are recommended for all platforms.
Batch application DB sharing options (distributed only)
Batch IMS applications that do not require 'dirty read' support (PROCOPT=GO) on any PCB can specify a global exclusive DB lock configuration that optimizes performance. This is implemented from JCL using the IMSLOCK DD statement:
//IMSLOCK DD *
EXCLUSIVE
/*

All DBs accessed by the batch application are held exclusively; this effectively bypasses IMS DB Control.

Internal Resource Lock Manager (IRLM) (distributed only)
Set the ES_IMS_IRLM=1 environment variable to enable locking that closely parallels mainframe IMS database DB locking behavior. This can reduce data constraint and the potential for deadlock. A system running several applications in an IMS data sharing environment results in less DB segment contention when this is enabled, which results in applications that wait for data less and process faster.
Buffer flushing (distributed only)
The environment variables ES_IMS_DB_COMMIT_FLUSH and ES_IMS_TLOG_FLUSH can have an adverse effect on database performance, and care should be taken if setting these variables to any value other than their defaults.
Parent topic: IMS
Related reference
Internal Resource Lock Manager (IRLM)
IMS-Specific Environment Variables
DATACOMPRESS
Related information
Optimizing IMS Applications - General


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

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

The trace information is displayed dynamically in a console, as soon as it occurs. There is one console for each process ID being debugged.

  • To Enable CTF Tracing
  • To enable CTF tracing of a web application
    Configure CTF tracing to pass tracing information on to the Java logging framework on a web server. Use this method if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.
  • CTF Trace File Formats
  • CTF Viewer
  • CTF perspective
  • Components Traced by CTF
  • Configuration File for CTF
  • Emitter List
  • Tracing Examples
Parent topic: Problem Determination and Diagnostic Tools
Related concepts
Features Added in Enterprise Developer 2.2
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:
    Windows:
    set MFTRACE_CONFIG=c:\ctf\ctf.cfg
    UNIX:
    export MFTRACE_CONFIG=/home/usr/ctf/ctf.cfg

    You can set this environment variable in a debug configuration, so that the trace is automatically enabled when you debug with this configuration.

  2. Set the MFTRACE_LOGS environment variable to specify the location in which to create the CTF trace files. If MFTRACE_LOGS is not set, the current folder is used.
    Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.
  3. Edit the configuration file to specify the information to trace, for example:
    mftrace.dest = binfile
mftrace.emitter.binfile#location  = c:\logs (Windows) or
             /home/usr/logs (UNIX)
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


To enable CTF tracing of a web application

Configure CTF tracing to pass tracing information on to the Java logging framework on a web server. Use this method if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.

Your project must be of type Dynamic Web Application.

  1. In Application Explorer view, right-click the project name, then click New > Folder > Folder.

    The New Folder dialog box appears.

  2. In the Folder name field, type Resources, then click Finish.

    The Resources folder is created in your project hierarchy.

  3. Right-click the Resources folder, then click New > File.

    The New File screen appears.

  4. In the File name field, type mfjvm.cfg, then click Finish.

    The mfjvm.cfg configuration file is added to the Resources folder.

  5. Add the configuration file to the deployment:
    1. Right-click the project name, then click Properties.

      The Properties screen appears.

    2. On the Deployment Assembly tab, click Add > Folder > Resources, then click Finish.
    3. Double-click the Deploy Path entry for the Resources source and update it to WEB/INF/classes, then click OK.

  6. Double-click mfjvm.cfg and add the following:
    mftrace.dest = javalogger
mftrace.emitter.javalogger#Format = ruid=$(RUNUNIT) tid=$(THREAD) $(COMPONENT) $(EVENT) :$(DATA)
  7. Compile and deploy your web application, then configure the Java logging API as per your web server documentation.
Parent topic: The Consolidated Tracing Facility


CTF Trace File Formats

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

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

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

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

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

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

Parent topic: The Consolidated Tracing Facility


CTF Viewer

The Consolidated Tracing Facility (CTF) Viewer is a tool for viewing binary format trace files that were created by configuring the CTF BINFILE emitter. It is installed as a single Eclipse plug-in.

The CTF Viewer enables you to:

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

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

  • Annotation Files for CTF Events
  • Bookmarks in the CTF viewer
  • To create and load a binary trace file into the CTF Viewer
  • To search in the CTF Viewer
  • To enable your annotation files in the CTF Viewer
Parent topic: The Consolidated Tracing Facility


Annotation Files for CTF Events

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

Annotation files are supplied in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\mftrace\annotations (Windows) or $COBDIR/etc/mftrace/annotations (UNIX) directory. There is one annotations file for each supported component.

Parent topic: CTF Viewer


Bookmarks in the CTF viewer

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

  • You can add a bookmark to an event, by right-clicking the event and clicking Add Bookmark.
  • Bookmarked events are shown in the main CTF View by a blue bookmark icon in column one of the event. They are also displayed in the Bookmarks view.
  • Double-click a bookmark in the Bookmarks view to jump to the bookmarked event in the Viewer. If the bookmarked event is in a file that isn't open, the file is automatically opened.
  • You can select multiple events in the main CTF view and set bookmarks on them all. You can also select multiple bookmarked events and remove their bookmarks.
  • Bookmarks persist between IDE sessions.
  • You can create bookmarks only in trace files that have been loaded by the viewer from an Eclipse project, since bookmarks can be associated with Eclipse workspace resources only.
Parent topic: CTF Viewer


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

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

    Alternatively you can create a project containing the trace files.

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


To search in the CTF Viewer

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


To enable your annotation files in the CTF Viewer

  1. Click Window > Preferences > Micro Focus > Consolidated Trace Facility > Annotation File Locations.

    Initially, the Location field is populated with the location of the trace files. This location is defined in the MFTRACE_ANNOTATIONS environment variable, which is set automatically in the Enterprise Developer command environment from which you start Eclipse.

  2. Set the location to point to where your trace files are. You can add multiple locations and retain or remove the default location.
  3. Set the order of the trace file locations, so that the first location is used if trace files are found there.

The locations are preserved between Eclipse IDE sessions.

Parent topic: CTF Viewer


CTF perspective

The CTF perspective consists of the COBOL Explorer and Properties views in the left-hand side of the IDE and the Bookmarks view in the bottom right of the IDE. The remainder of the IDE is the editor area and is used for the display of trace file contents.

You can display the CTF perspective, like any other perspective, by clicking Window > Perspective > Open Perspective > Other > CTF.

We recommend that you select the CTF perspective to view trace files. By default, you are prompted to do this, if the perspective is not already current when you attempt to open a trace file. If you don't want to be prompted, you can configure the default behavior by going to Window > Preferences > Micro Focus > Consolidated Trace Facility.

Parent topic: The Consolidated Tracing Facility


Components Traced by CTF

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

  • mf.cci Properties
    This component provides CCI activity.
  • mf.esmq Properties
    This component provides calls to the WebSphere MQ XA switch module.
  • mf.esxa Properties
    This component provides diagnostics on the various SQL operations invoked by the switch modules when executing SQL applications that have been deployed under Enterprise Server.
  • mf.idmr Properties
    This component handles the interface mapping between a SOAP/BINP message and COBOL fields.
  • mf.mffh.fs Properties
    This component provides Fileshare processing.
  • mf.mffh.xfh Properties
    This component provides the Micro Focus File Handler system.
  • mf.mffh.xsm Properties
    This component provides the Micro Focus Sort module.
  • mf.mvs.casspool Properties
    This component provides JCL workload management, such as job submission, dispatch, printing and held SYSOUT.
  • mf.mvs.mvscatio Properties
    This component supports the JES system catalog, which maintains the relationship between the native file system and the MVS/VSE form of data set names.
  • mf.mvs.mfjcl Properties
    This component provides the main JCL processing functionality.
  • mf.rts Properties
    This component provides behavior of the run-time system.
  • mf.mvs.le37 Properties
    This component provides language environment services support.
Parent topic: The Consolidated Tracing Facility
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.esxa Properties

This component provides diagnostics on the various SQL operations invoked by the switch modules when executing SQL applications that have been deployed under Enterprise Server.

The following table lists the properties of the mf.esxa component, and shows the event information that can be included in the trace for each property. Although you can create your own trace files, Micro Focus recommends that you use the configuration files supplied with the switch module source files as the basis for tracing.

ALL
Enables or disables all of the other properties.
MSSQL
SQL Server switch module events:
Event Level | Event ID | Event Description
INFO | 1 | Initialization of module
ERROR | 2 | Incorrect XA open string provided
INFO | 3 | SQL CONNECT
INFO | 4 | Microsoft Distributed Transaction Coordinator (DTC) initialization
INFO | 5 | XA_START
INFO | 6 | Enlist in DTC transaction
INFO | 7 | XA_COMMIT
INFO | 8 | XA_ROLLBACK
INFO | 9 | XA_CLOSE
INFO | 10 | XA_END
INFO | 11 | De-enlist from DTC transaction
INFO | 12 | XA_OPEN
INFO | 13 | XA_CLOSE
INFO | 14 | XA_RECOVER
INFO | 15 | XA_FORGET
INFO | 16 | XA_COMPLETE
INFO | 17 | Register an XA data source with the current transaction
INFO | 18 | XA_PREPARE
ODBC
Generic ODBC switch module events:
Event Level | Event ID | Event Description
INFO | 21 | BEGIN TRANSACTION
INFO | 22 | SQL COMMIT
INFO | 23 | SQL ROLLBACK
INFO | 24 | SQL DISCONNECT
INFO | 26 | Initialization of module
ERROR | 27 | Incorrect XA Open String
INFO | 28 | SQL CONNECT
INFO | 29 | SQL SYNCPOINT
INFO | 30 | RESET CONNECTION
INFO | 31 | EXECUTE AS
INFO | 32 | REVERT
INFO | 33 | SET XA TRIGGER (for dynamic registration)
INFO | 34 | SYNC ROLLBACK
INFO | 35 | RESET HOST CONNECTION
INFO | 36 | SET CURRENT CONNECTION
INFO | 37 | SET ISOLATION LEVEL
DB2
DB2 switch module events:
Event Level | Event ID | Event Description
INFO | 41 | XA_START
INFO | 42 | XA_END
INFO | 43 | XA_OPEN
INFO | 44 | XA_CLOSE
INFO | 45 | XA_COMMIT
INFO | 46 | XA_ROLLBACK
INFO | 47 | XA_PREPARE
INFO | 48 | Call to IBM DB2 LUW XA initialization
INFO | 49 | Register an XA data source with the current transaction
INFO | 51 | SET ISOLATION LEVEL
ERROR | 61 | Incorrect XA Open String
INFO | 62 | SQL CONNECT
INFO | 63 | SQL COMMIT
INFO | 64 | SQL ROLLBACK
INFO | 65 | SQL DISCONNECT
INFO | 66 | Before SQL CONNECT
INFO | 67 | Before SQL COMMIT
INFO | 68 | Before SQL ROLLBACK
INFO | 69 | Before SQL DISCONNECT
ORA
Oracle switch module events:
Event Level | Event ID | Event Description
INFO | 81 | XA_START
INFO | 82 | XA_END
INFO | 83 | XA_OPEN
INFO | 84 | XA_CLOSE
INFO | 85 | XA_COMMIT
INFO | 86 | XA_ROLLBACK
INFO | 87 | XA_PREPARE
INFO | 88 | Load of Enterprise Server callback module
INFO | 89 | Load of Oracle client-side support
INFO | 90 | Call to Oracle XA initialization entry point
INFO | 91 | XA_RECOVER
INFO | 92 | Register an XA Data Source with the current transaction
INFO | 93 | SET ISOLATION LEVEL
ERROR | 101 | Incorrect XA Open String
INFO | 102 | SQL CONNECT
INFO | 103 | SQL COMMIT
INFO | 104 | SQL ROLLBACK
INFO | 105 | SQL DISCONNECT
INFO | 106 | Before SQL CONNECT
INFO | 107 | Before SQL COMMIT
INFO | 108 | Before SQL ROLLBACK
INFO | 109 | Before SQL DISCONNECT
XDB
XDB switch module events:
Event Level | Event ID | Event Description
INFO | 160 | XA_START
INFO | 161 | XA_END
INFO | 162 | XA_OPEN
INFO | 163 | XA_CLOSE
INFO | 164 | XA_COMMIT
INFO | 165 | XA_ROLLBACK
INFO | 166 | XA_PREPARE
INFO | 167 | Load XDB functions
INFO | 168 | RESET CONNECTION
XDBOPC
XDB one-phase switch module events:
Event Level | Event ID | Event Description
INFO | 180 | CONNECT
INFO | 181 | COMMIT
INFO | 182 | ROLLBACK
INFO | 183 | CLOSE
INFO | 184 | Before CONNECT
INFO | 185 | Before COMMIT
INFO | 186 | Before ROLLBACK
INFO | 187 | Before CLOSE
PGSQL
PostgreSQL switch module events:
Event Level | Event ID | Event Description
INFO | 201 | Initialization of module
ERROR | 202 | Incorrect XA open string provided
INFO | 203 | SQL CONNECT
INFO | 204 | Microsoft Distributed Transaction Coordinator (DTC) initialization
INFO | 205 | XA_START
INFO | 206 | Enlist in DTC transaction
INFO | 207 | XA_COMMIT
INFO | 208 | XA_ROLLBACK
INFO | 209 | XA_CLOSE
INFO | 210 | XA_END
INFO | 211 | De-enlist from DTC transaction
INFO | 212 | XA_OPEN
INFO | 213 | XA_CLOSE
INFO | 214 | XA_RECOVER
INFO | 215 | XA_FORGET
INFO | 216 | XA_COMPLETE
INFO | 217 | Register an XA data source with the current transaction
INFO | 218 | XA_PREPARE
Parent topic: Components Traced by CTF


mf.idmr Properties

This component handles the interface mapping between a SOAP/BINP message and COBOL fields.

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

ALL
Enables/disables all of the other properties
API
API events.
Level | Event ID | Event Description
INFO | 211 | Mapper initialization
INFO | 212 | Mapper termination
INFO | 213 | Set implementation field
INFO | 214 | Get implementation field
INFO | 215 | API completed successfully
ERROR | 216 | API error
CLIENT
Enterprise Server client handler events.
Level | Event ID | Event Description
INFO | 31 | Start of client request
INFO | 32 | End of client request
INFO | 33 | Start of client response
INFO | 34 | End of client response
INFO | 35 | Start of client termination
INFO | 36 | End of client termination
INFO | 38 | Set behavior options
INFO | 39 | Set special registers
INFO | 40 | Get fault information
INFO | 41 | Call program
ERROR | 37 | Client handling error
GEN
IDT generation events.
Level | Event ID | Event Description
INFO | 121 | Start of IDT generation
INFO | 122 | Start of implementation section
INFO | 123 | Start of service section
INFO | 124 | Start of configuration section
INFO | 125 | Set schema location
INFO | 126 | Validate service definition
INFO | 128 | Operation completed successfully
INFO | 129 | Free IDT
INFO | 130 | Set behaviour options
INFO | 131 | Load configuration information
INFO | 132 | Free configuration information
ERROR | 127 | IDT generation error
IDT
IDT processing events.
Level | Event Id | Event Description
INFO | 181 | Get configuration information
MAP
Run-time interface mapping events.
Level | Event ID | Event Description
INFO | 501 | External information events
INFO | 502 | Implementation information
INFO | 503 | IDT information
INFO | 504 | Configuration information
INFO | 505 | Exit handling information
INFO | 506 | Arguments size
INFO | 507 | External message size
INFO | 508 | External message argument count
INFO | 509 | Start of parameter
INFO | 510 | End of parameter
INFO | 511 | Set implementation field
INFO | 512 | Set implementation constant
INFO | 513 | Get implementation field
INFO | 514 | Start of server request mapping
INFO | 515 | End of server request mapping
INFO | 516 | Start of server response mapping
INFO | 517 | End of server response mapping
INFO | 518 | Start of client request mapping
INFO | 519 | End of client request mapping
INFO | 520 | Start of client response mapping
INFO | 521 | End of client response mapping
INFO | 522 | No execution
SERVER
Enterprise Server request handler events.
Level | Event ID | Event Description
INFO | 0 | Start of server request
INFO | 1 | End of server request
INFO | 2 | Start of server response
INFO | 3 | End of server response
INFO | 4 | Start of server termination
INFO | 5 | End of server termination
ERROR | 6 | Server handling error
SYS
System IDT events.
Level | Event ID | Event Description
INFO | 151 | Generate system IDT

Parent topic: Components Traced by CTF


mf.mffh.fs Properties

This component provides Fileshare processing.

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

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


mf.mffh.xfh Properties

This component provides the Micro Focus File Handler system.

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

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


mf.mffh.xsm Properties

This component provides the Micro Focus Sort module.

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

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

Parent topic: Components Traced by CTF


mf.mvs.casspool Properties

This component provides JCL workload management, such as job submission, dispatch, printing and held SYSOUT.

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

Property | Property Description | Level | Event Id | Event Description
ACTIVE | Movement of a job into active status. The job is given to the batch initiator for execution and upon completion of the job the batch initiator signals that it is ready for more work. | DEBUG | 4 | Compiled JCL has been executed.
COMP | Submission of JCL by Enterprise Server to be syntax checked. | DEBUG | 2 | A JCL file has been submitted for syntax scanning.
DELETE Removal of a job from the Input, In Hold, Active, and Complete queues. DEBUG 7 A job has been removed from one of these queues. This could have occurred for the following reasons:
  • an active job has been killed
  • output has been requeued
  • a purge has taken place
DISP | Movement of a job from the Input queue so that it can be executed by a batch initiator. | DEBUG | 3 | The next available compiled JCL for a given class and priority has been requested for scheduling in an available batch initiator.
OPEN | Opening and closing of the spool files. | DEBUG | 10 | Spool files are accessed when starting and stopping an initiator, initializing and terminating an enterprise server, and restarting a generic SEP.
OUTPUT | Movement of a job that has completed from the Active queue to the Complete queue and performing of any associated cleanup tasks. | DEBUG | 5 | Compiled JCL has finished executing.
PRINT | Routing of a job to a batch printer or a batch printer exit. | DEBUG | 9 | This routing occurs upon job completion for active batch printers or when a SYSOUT is driven to the printer by requeuing.
REPL Replacement of a job that has either been made active or had been requested for execution into either the Input or Complete queues. DEBUG 6 A job bas been replaced. This could have happened for the following reasons:
  • the job was previously active and canceled
  • a protection violation occurred in the batch initiator
  • a protection violation occurred in one of your programs
  • job was canceled by the operator

If the job was previously active it is moved to the Complete queue for review. If it was never made active then it is replaced in the Input queue.

RETRIEVE | Requests to retrieve information about a job or SYSOUT DDs that are associated with a job. | DEBUG | 8 | These requests typically occur because of an interaction with ESMAC or when the casout utility needs to retrieve SYSOUT information.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


mf.mvs.mvscatio Properties

This component supports the JES system catalog, which maintains the relationship between the native file system and the MVS/VSE form of data set names.

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

Property | Property Description | Level | Event Id | Event Description
BUFFER | Buffer for MVSCATIO files. | DEBUG | 5 | The buffer used for MVSCATIO files in binary format. This is useful for subrecord tracing.
DELETE | Functions that occur when an MVSCATIO DLET function code is executed. | DEBUG | 3 | Unexpected failures, and information such as whether a file was able to be physically deleted or if alternate indexes were processed.
ENQUE | Enqueues on a record. | DEBUG | 3 | Data set records that are being locked and waited for.
ENTRY | Entry to or exit from MVSCATIO. | DEBUG | 3 | Primary key, file status, and return codes for a given call to MVSCATIO. This is very useful for diagnosing general problems with MVSCATIO.
MFALU | Mainframe Access lookups and their success or failure. | DEBUG | 3 | MVSCATIO calls that caused a Mainframe Access lookup to occur and whether or not the lookup was successful.
PHYS | Physical file name associated with a catalog entry. | DEBUG | 7 | The physical file name. This is useful in conjunction with the ENTRY property when trying to establish which physical files are associated with a given MVS name.
RECORDS | Catalog records. | DEBUG | 6 | The entire catalog record for a given I/O operation in binary form. This provides additional information that is not available when using the ENTRY property.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


mf.mvs.mfjcl Properties

This component provides the main JCL processing functionality.

The following table lists the property of the mf.mvs.mfjcl component and shows the event information that can be included in the trace for it.

Property | Property Description | Level | Event Id | Event Description
memstomp | Memory corruption event | ERROR | 79 | Memory has been corrupted.
Parent topic: Components Traced by CTF
Related information
Introduction to the Consolidated Tracing Facility
Components Traced by CTF


mf.rts Properties

This component provides behavior of the run-time system.

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

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


mf.mvs.le37 Properties

This component provides language environment services support.

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

Property | Property Description | Level | Event Id | Event Description
ENTRY | Entry and exit to each program | DEBUG | 1 | Entry and exit to each program
 |  |  | 2 | Retrieve product and platform information
ENVIR | Environment Values | DEBUG | 3 | Report environment values that affect LE
SETPP | Setting procedure entry points | DEBUG | 4 | Report the setting of procedure entry points
CALL | Calling programs | DEBUG | 5 | Report the call to and response from a program
FILE | Reading configuration files | DEBUG | 6 | Report the actions and contents of LE configuration files
CGPIINFO | Call stack | DEBUG | 7 | Report program call stack
Parent topic: Components Traced by CTF


Configuration File for CTF

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

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

You can use the following entries in configuration files:

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


mftrace.application

Restricts tracing to a specific application.

Syntax:

mftrace.application=executable-name

Parameters:

executable-name
The name of the executable for the application for which tracing is to be performed. This can be either a fully-qualified or unqualified name. Enclosing the executable name within parentheses indicates that the application is being run under a trigger program (such as run (Windows) or cobrun (UNIX)), 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


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


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


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


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


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


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


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


Example CTF Configuration Files

Example ctf.cfg file 1

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

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

Example ctf.cfg file 2

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

mftrace.dest                      = binfile
mftrace.emitter.binfile#location  = c:\logs
mftrace.level.mf.rts              = info
mftrace.comp.mf.rts#pgm           = true
mftrace.comp.mf.rts#pgmload       = true
mftrace.comp.mf.rts#syspgm        = true
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:

  • c:\logs (Windows) or /user/bin/logs (UNIX) is the location where the trace files for the application is created.
  • binfile indicates that a binary trace file is to be generated

Example configuration file for Assembler

This configuration file traces Assembler programs, and creates a text file:

#
#  Demo CTF config file for use with demo CTF programs.
#

mftrace.dest=textfile

mftrace.emitter.textfile#Format = $(TIME) $(THREAD) $(COMPONENT) $(EVENT) $(LEVEL) :$(DATA)
mftrace.emitter.es#level = 9999

# Where do you want the logs to go?
mftrace.emitter.textfile#location = c:\logs

# Maximum file size in "k" bytes
mftrace.emitter.textfile#MaxFilesize = 6000

# Maximum number of log files to keep.
mftrace.emitter.textfile#MaxGeneration = 4

################################################
# CASSPOOL Tracing
################################################

mftrace.level.mf.asm             = debug

mftrace.comp.mf.asm#INS          = true
mftrace.comp.mf.asm#SVC          = true
mftrace.comp.mf.asm#BAL          = true

mftrace.comp.mf.asm#ABEND        = true
mftrace.comp.mf.asm#LOAD         = true
mftrace.comp.mf.asm#DELETE       = true
mftrace.comp.mf.asm#LINK         = true
mftrace.comp.mf.asm#GETMAIN      = true
mftrace.comp.mf.asm#FREEMAIN     = true
#mftrace.comp.mf.asm#REGS         = true

where:

  • INS - trace all instructions
  • SVC - trace all svc calls
  • BAL - trace all branch instructions
  • ABEND - trace abends
  • LOAD - trace all loads
  • DELETE - trace all delete calls
  • LINK - trace all link commands
  • GETMAIN - trace all memory allocation commands
  • FREEMAIN - trace all free memory commands

Example app.config file

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

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


Emitter List

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

  • BINFILE Emitter Properties
    Set the BINFILE emitter properties to control the behavior and appearance of the binary trace file when viewed using the CTF Viewer.
  • IDEDBG Emitter Properties
    Set the IDEDBG emitter properties to output trace information to a debugger that is attached to a running process.
  • JAVALOGGER Emitter Properties
    Set the JAVALOGGER emitter properties to control the details passed to the Java logging framework on a web server.
  • TEXTFILE Emitter Properties
    Set the TEXTFILE emitter properties to control the behavior and appearance of the text trace file.
  • WINEVENT Emitter Properties
    Set the WINEVENT emitter properties to output trace information to the Windows log file.
Parent topic: The Consolidated Tracing Facility


BINFILE Emitter Properties

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

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

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

mftrace.dest = BINFILE

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

Property | Description | Default
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "run" (Windows) or "cobrun" (UNIX).
$(EMITTER)
Always "BINFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
dotnet
For Microsoft .NET processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
$(APPNAME).$(EMITTER).$(PID).ctb, or $(APPNAME).$(EMITTER).$(PID).ctb_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the BINFILE emitter is being used to output trace events for run.exe (Windows) cobrun (all platforms) executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.binfile.3456.ctb (Windows) cobrun.binfile.3456.ctb (all platforms).
  • If the binfile emitter is being used to output trace events for myapp.exe (Windows) myapp (all platforms) executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.binfile.1975.ctb_1, myapp.binfile.1975.ctb_2, and myapp.binfile.1975.ctb_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
FORMAT
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
LOCATION The folder where the trace files are to be written. The folder specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.
Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.

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

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

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)

FALSE, indicating that the configured trace file includes only events from the current process
Rununitid | Controls whether the RunUnit information is included in the trace. | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).ctb

When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

JVM COBOL restrictions:

If a JVM COBOL application is executing in a permissions-restricted environment, use of the MultiProc property on the BINFILE emitter is not available.

Parent topic: Emitter List


IDEDBG Emitter Properties

Set the IDEDBG emitter properties to output trace information to a debugger that is attached to a running process.

The IDEDBG emitter is provided to allow trace records to be output by a debugger, such as your COBOL development system, Visual Studio, or Eclipse at the point which they occur in the application being debugged.

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

mftrace.dest = IDEDBG

To use this emitter with your COBOL development system IDE, you must set the MFTRACE_CONFIG environment variable on the Environment Variables tab of the Configure IDE Environment dialog box. Trace events appear in the Debug messages tab when the application is debugged.

To use this emitter with a third-party debugger such as Visual Studio, you must set the MFTRACE_CONFIG environment variable in the environment before the debugger process is started. Trace events appear in the debugger‘s window where other system debug events would normally be displayed. For example, under Visual Studio 6, debug messages are displayed in the Debug tab.

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

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | SPACE
FORMAT The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm/dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warning
  • 3: error
  • 4: fatal
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)
HEXBLOCKSIZE The number of hexadecimal bytes to be output in each block when outputting binary trace data. Each block of hexadecimal characters will be separated by a '-' character. For example, if HEXBLOCKSIZE is set to 4, and some binary trace data with the value 3132333435363738393A3B3C3D3E3F is specified for output, it would be formatted as follows:
31323334-35363738-393A3B3C-3D3E3F
 8
LEVEL The trace level below which this emitter will not output trace records:
  • 0 = debug
  • 1 = info
  • 2 = warning
  • 3 = error
  • 4 = fatal
  • >4 = no trace records are output
3
QUOTESTRING | Whether or not string trace data is to be output enclosed in double-quote characters. . | TRUE
Parent topic: Emitter List


JAVALOGGER Emitter Properties

Set the JAVALOGGER emitter properties to control the details passed to the Java logging framework on a web server.

Use this type of emitter if you are unable to configure the TEXTFILE or BINFILE emitters due to web server permission restrictions.

Add the required properties for the JAVALOGGER emitter to the mfjvm.ctf configuration file:

Property Description Default
FORMAT The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm/dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warn
  • 3: error
  • 4: fatal
Note: See Comments below.
$(PID)
The current process identifier. Same as $(PROCESS).
$(PROCESS)
The current process identifier. Same as $(PID).
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)

Comments:

The tracing levels set by $(LEVEL) map to the following levels used in the Java logging API:

Micro Focus tracing levels | Java logging API tracing levels
Debug | Config
Info | Info
Warn | Warning
Error | Severe
Fatal | Severe

Refer to your Java logging API documentation for the details traced for each level.

Parent topic: Emitter List


TEXTFILE Emitter Properties

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

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

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

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | SPACE
FILE The name of the trace file to be written. You can use the following pseudo-variables for the construction of the trace file name:
$(APPNAME)
The basename of the executable invoked to start the current process. For example, if run.exeis invoked, $(APPNAME) has the value "run" (Windows) or "cobrun" (UNIX).
$(EMITTER)
Always "TEXTFILE" for this emitter.
$(GEN)
The generation of the file, starting from 1.
$(PID)
The operating system identifier for the current process.
$(PLATFORM)
A platform specific constant, useful when two run-time systems are in the same process, and you require separate trace files. Can be one of:
native
For all native processes
dotnet
For Microsoft .NET processes
jvm
For JVM processes
$(RUNUNIT)
A unique number that represents the managed RunUnit ID (applies to .NET and JVM COBOL only).
$(RUNUNIT_SESSIONNAME)
The session name passed to the managed RunUnit (applies to .NET and JVM COBOL only).
$(RUNUNIT_GUID)
The globally unique identifier associated with the managed RunUnit (applies to .NET and JVM COBOL only).
$(APPNAME).$(EMITTER).$(PID).log, or $(APPNAME).$(EMITTER).$(PID).log_$(GEN) if the MAXGENERATION property has been specified. For example:
  • If the TEXTFILE emitter is being used to output trace events for run.exe (Windows) cobrun (all platforms) executing as process-id 3456 and the MAXGENERATION property has not been specified, the trace file created will be called run.textfile.3456.log (Windows) cobrun.textfile.3456.log (all platforms).
  • If the TEXTFILE emitter is being used to output trace events for myapp.exe (Windows) myapp (all platforms) executing as process-id 1975 and the MAXGENERATION property has been set to 3, the trace files created will be called myapp.textfile.1975.log_1, myapp.textfile.1975.log_2, and myapp.textfile.1975.log_3.
FLUSHEVERY | The number of trace records that will be output before the file is flushed. 0 indicates that the file will never be explicitly flushed. | 1
FORMAT The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm/dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warning
  • 3: error
  • 4: fatal
$(PID)
The current process identifier. Same as $(PROCESS).
$(PROCESS)
The current process identifier. Same as $(PID).
$(RUNUNIT)
A unique number that identifies the RunUnit that relates to the trace event.
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(TIME) $(COMPONENT) $(EVENT) $(LEVEL) $(DATA)
HEXBLOCKSIZE The number of hexadecimal bytes to be output in each block when outputting binary trace data. Each block of hexadecimal characters will be separated by a '-' character. For example, if HEXBLOCKSIZE is set to 4, and some binary trace data with the value 3132333435363738393A3B3C3D3E3F is specified for output, it would be formatted as follows:
31323334-35363738-393A3B3C-3D3E3F
 8
LOCATION The folder where the trace files are to be written. On Windows platforms, the folder is specified by the MFTRACE_LOGS environment variable. If MFTRACE_LOGS is not set, the current folder is used.
Note: Both the 32- and 64-bit Enterprise Developer command prompts set MFTRACE_LOGS to %ProgramData%\Micro Focus\Enterprise Developer\2.x\mftrace\logs.

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

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

if $(RUNUNIT), $(RUNUNIT_SESSIONNAME), or $(RUNUNIT_GUID)" is used, the file name will be unique, therfore MultiProc is not required (applies to .NET and JVM COBOL only)

FALSE, indicating that the configured trace file includes only events from the current process
QUOTESTRING | Whether or not string trace data is to be output enclosed in double-quote characters. . | TRUE

Performance considerations:

When using the MultiProc property, and two or more COBOL run-time systems (native, .NET or JVM) are executing in the same process, sharing the same trace file is not a performant configuration. Using the $(PLATFORM) variable in the filename allows you to use different filenames for different run-time systems. If tracing includes the $(PID) variable, you can safely set the MultiProc property to false. For example:

$(APPNAME). $(EMITTER).$(PID).$(PLATFORM).log

When a JVM or .NET COBOL application executes in a multi-user environment, the user of managed RunUnits should be used. The default filename for both the TEXTFILE and BINFILE emitter collects all the trace events into one or more files. However, if the configuration property #file uses $(RUNUNIT), $(RUNUNIT_SESSIONNAME) or $(RUNUNIT_GUID), separate files can be created for each RunUnit. For example:

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_GUID).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT).log

or

$(APPNAME).$(PLATFORM).$(EMITTER).$(RUNUNIT_SESSIONNAME).log

JVM COBOL restrictions:

If a JVM COBOL application is executing in a permissions-restricted environment, use of the MultiProc property on the TEXTFILE emitter is not available.

Parent topic: Emitter List


WINEVENT Emitter Properties

Set the WINEVENT emitter properties to output trace information to the Windows log file.

The WINEVENT emitter is provided to allow trace records to be output to the Windows event log. By default, to prevent the event log from being filled with unnecessary information, this emitter only outputs trace records with a trace level of error or above.

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

mftrace.dest = WINEVENT

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

Property | Description | Default
DELIMCHAR | The character used in the output file to delimit trace data parts for a trace event. | SPACE
FORMAT The format to be used for each trace data record written to the file. You can use the following pseudo-variables in the format specification:
$(COMPONENT)
The name of the component outputting the trace event.
$(DATA)
The trace data specified by the component to be output for the trace event. Each trace part will be delimited by the character specified by the DELIMCHAR property.
$(DATE)
The current date, output as yyyy/mm/dd
$(EVENT)
The event identifier as specified by the component outputting the trace event.
$(LEVEL)
The tracing level:
  • 0: debug
  • 1: info
  • 2: warning
  • 3: error
  • 4: fatal
$(THREAD)
The current operating system thread identifier.
$(TIME)
The current time, output as hh:mm:ss
$(DATA)
HEXBLOCKSIZE The number of hexadecimal bytes to be output in each block when outputting binary trace data. Each block of hexadecimal characters will be separated by a '-' character. For example, if HEXBLOCKSIZE is set to 4, and some binary trace data with the value 3132333435363738393A3B3C3D3E3F is specified for output, it would be formatted as follows:
31323334-35363738-393A3B3C-3D3E3F
 8
LEVEL The trace level below which this emitter will not output trace records:
  • 0 = debug
  • 1 = info
  • 2 = warning
  • 3 = error
  • 4 = fatal
  • >4 = no trace records are output
3
QUOTESTRING | Whether or not string trace data is to be output enclosed in double-quote characters. . | TRUE
Parent topic: Emitter List


Tracing Examples

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

set MFTRACE_CONFIG=e:\mydir\ctf.cfg
export MFTRACE_CONFIG=/home/mydir/ctf.cfg

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

mftrace.level=error

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

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

mymain.cbl:

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

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

     cancel 'mysub'

     call 'myprog'
     goback.

mysub.cbl:

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

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

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

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

mftrace.level=info

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

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 2820
    # Date             = 2004/12/14
    # Time             = 12:27:04.317
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    12:27:04.317 MF.RTS 128 1
    12:27:04.327 MF.RTS 129 1
    12:27:04.337 MF.RTS 255 3 173 1 "myprog"
    12:27:04.367 MF.RTS 130 1
    12:27:04.367 MF.RTS 131 1
    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 1646624
    # Date             = 2005/01/21
    # Time             = 11:28:09.105
    # Operating System = AIX 5.1
    # Computer Name    = asterix
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    11:28:09.105 MF.RTS 128 1
    11:28:09.135 MF.RTS 129 1
    11:28:09.225 MF.RTS 255 3 173 1 "myprog"
    11:28:09.226 MF.RTS 130 1
    11:28:09.226 MF.RTS 131 1

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

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

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

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 4092
    # Date             = 2004/12/14
    # Time             = 13:44:30.868
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    13:44:30.868 MF.RTS 128 1
    13:44:30.888 MF.RTS 129 1
    13:44:30.888 MF.RTS 19 1 0 0 "mymain" "" ""
    13:44:30.888 MF.RTS 6 1 17 0 "mymain"
    13:44:31.008 MF.RTS 19 1 0 0 "mysub" "gnt" "E:\myprogs"
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.008 MF.RTS 20 1 0 0 "mysub"
1>  13:44:31.008 MF.RTS 6 1 1 0 "MYSUB"
    13:44:31.008 MF.RTS 7 1
    13:44:31.139 MF.RTS 255 3 173 1 "myprog"
    13:44:31.199 MF.RTS 130 1
    13:44:31.199 MF.RTS 20 1 0 0 "mymain"
2>  13:44:31.199 MF.RTS 6 1 17 0 "mymain"
    13:44:31.199 MF.RTS 7 1
    13:44:31.199 MF.RTS 131 1
    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 1622058
    # Date             = 2005/01/21
    # Time             = 11:30:27.441
    # Operating System = AIX 5.1
    # Computer Name    = asterix
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    11:30:27.441 MF.RTS 128 1
    11:30:27.451 MF.RTS 129 1
    11:30:27.452 MF.RTS 19 1 0 0 "mymain" "" ""
    11:30:27.510 MF.RTS 6 1 17 0 "mymain"
    11:30:27.513 MF.RTS 19 1 0 0 "mysub" "gnt" "/home/myprogs"
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.513 MF.RTS 20 1 0 0 "mysub"
1>  11:30:27.513 MF.RTS 6 1 1 0 "MYSUB"
    11:30:27.513 MF.RTS 7 1
    11:30:27.515 MF.RTS 255 3 173 1 "myprog"
    11:30:27.515 MF.RTS 130 1
    11:30:27.515 MF.RTS 20 1 0 0 "mymain"
2>  11:30:27.515 MF.RTS 6 1 17 0 "mymain"
    11:30:27.515 MF.RTS 7 1
    11:30:27.516 MF.RTS 131 1

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

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

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

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

    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 2716
    # Date             = 2004/12/14
    # Time             = 14:33:22.704
    # Operating System = Windows XP Service Pack 1 (Build 2600)
    # Computer Name    = PC-NAME
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    14:33:22.704 MF.RTS 128 1
    14:33:22.714 MF.RTS 129 1
    14:33:22.714 MF.RTS 19 1 0 0 "mymain" "" ""
    14:33:22.714 MF.RTS 6 1 17 0 "mymain"
1>  14:33:22.714 MF.RTS 26 1 "MY_VAR" 9
    14:33:22.714 MF.RTS 19 1 0 0 "mysub" "gnt" "E:\myprogs"
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 20 1 0 0 "mysub"
    14:33:22.724 MF.RTS 6 1 1 0 "MYSUB"
    14:33:22.724 MF.RTS 7 1
    14:33:22.724 MF.RTS 255 3 173 1 "myprog"
    14:33:22.764 MF.RTS 130 1
    14:33:22.764 MF.RTS 20 1 0 0 "mymain"
    14:33:22.764 MF.RTS 6 1 17 0 "mymain"
    14:33:22.764 MF.RTS 7 1
2>  14:33:22.764 MF.RTS 27 1 "MY_VAR"
    14:33:22.764 MF.RTS 131 1
    # -MFTRACE Text Emitter-
    # CommandLine      = mymain
    # ProcessId        = 1073210
    # Date             = 2005/01/21
    # Time             = 11:33:52.015
    # Operating System = AIX 5.1
    # Computer Name    = asterix
    # Format           = $(TIME) $(COMPONENT) $(EVENT) $(LEVEL)$(DATA)
    11:33:52.015 MF.RTS 128 1
    11:33:52.031 MF.RTS 129 1
    11:33:52.032 MF.RTS 19 1 0 0 "mymain" "" ""
    11:33:52.090 MF.RTS 6 1 17 0 "mymain"
1>  11:33:52.091 MF.RTS 26 1 "my_var" 9
    11:33:52.093 MF.RTS 19 1 0 0 "mysub" "gnt" "/home/myprogs"
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.093 MF.RTS 7 1
    11:33:52.093 MF.RTS 20 1 0 0 "mysub"
    11:33:52.093 MF.RTS 6 1 1 0 "MYSUB"
    11:33:52.094 MF.RTS 7 1
    11:33:52.095 MF.RTS 255 3 173 1 "myprog"
    11:33:52.096 MF.RTS 130 1
    11:33:52.096 MF.RTS 20 1 0 0 "mymain"
    11:33:52.096 MF.RTS 6 1 17 0 "mymain"
    11:33:52.096 MF.RTS 7 1
    11:33:52.096 MF.RTS 41 1 0
    11:33:52.096 MF.RTS 41 1 1
2>  11:33:52.096 MF.RTS 27 1 "my_var"
    11:33:52.096 MF.RTS 131 1

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

Parent topic: The Consolidated Tracing Facility
Related information
To enable CTF tracing


Profiler

The Profiler utility enables you to obtain detailed statistics on the run-time performance of a COBOL application. In Enterprise Developer, Profiler is integrated with the IDE.

In order to use Profiler with your applications, you must first enable Profiler in the properties of a project, a build configuration or a file, then compile your project. This causes the Compiler to include code in your programs that produces performance statistics about each paragraph of the programs each time you run the application. To produce Profiler reports, you need to create a run configuration that has Profiler enabled, and then execute the application with it.

If a program contains no paragraphs, no report is produced for it.

The performance statistics produced by Profiler for that run of your application are saved in one or more files called program-name.ipf where program-name is the name of the program that was run. If an executable file is produced, then program-name is the first entry point name in the executable file. These performance statistics are in compact form and you use Profiler to convert them to a readable format saved as one or more .prf files.

The Profiler report file, .prf, is created in a subfolder of your project.

The IDE also produces a Profiler report when your project has dependencies on other projects that have profiling enabled. In such cases, the Profiler report file is saved in a subfolder of the project that contains the main program specified in the launch configuration.

Restriction:
  • Profiling 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.
  • Profiler cannot be used on programs running multiple threads (applies to UNIX environments only).

For information about how to use the Profiler utility from the command line, see Profiler in the General Reference section of this product help.

  • Enabling Profiler
  • Configuring the Profiler Reports
  • Running Your Application with Profiler
    Running your application with Profiler produces profiling reports.
  • Profiler Output
  • Time Spent in Called Programs
Parent topic: Problem Determination and Diagnostic Tools
Related concepts
Using Profiler from the Command Line
Related reference
Profiler


Enabling Profiler

Before you can generate a Profiler report for an application, you must enable Profiler in the properties of a project, a build configuration or a file.

To enable Profiler for a project:

  1. In the IDE, navigate to the project's properties.
  2. Click Micro Focus > Project Settings > COBOL, and check Enable profiler.
  3. Click OK.

To enable Profiler for a build configuration:

  1. In the IDE, navigate to the project's properties.
  2. Click Micro Focus > Build Configurations > COBOL.
  3. Expand Enable configuration specific settings and check Enable configuration specific settings.
  4. Check Enable profiler and click OK.

To enable Profiler for an individual file:

  1. In COBOL Explorer, right-click the file or a selection of files whose properties you want to change.
  2. On the COBOL tab, check Enable file specific settings.
  3. Check Enable profiler and click OK.
Note: If automatic builds are switched off in the IDE, you need to recompile your projects manually in order for these changes to take effect.

If your application executes in an enterprise server, you must also configure the server to run in Profiler mode:

  1. In the IDE, open the Server Explorer view.
  2. Right-click the server that your application uses and click Configure Analysis > Profiler.

    Next time you run your application, you get Profiler reports after stopping the server.

Parent topic: Profiler


Configuring the Profiler Reports

You can configure the format and the contents of the Profiler report and where the reports are generated from the IDE preferences. The preferences you specify apply to all projects that you execute with Profiler.

In the IDE preferences, in Window > Preferences > Micro Focus > COBOL > Profiler, you can specify Profiler report generation options that apply to all projects. You can specify the following options:

Clean old profiler output and generate new reports upon run completion
Check this for Profiler to delete any old Profiler output files and produce a report file, .prf. If this is unchecked, the Profiler only creates .ipf files for your project and you need to produce the report files manually by right-clicking one or more of the .ipf files in your project, and clicking Generate Profiler Report.
Always use the default report generation options
Check this to use the selected report generation options with all projects. If this is unchecked, each time you run an application with Profiler, the IDE displays a dialog box that enables you to choose Profiler options that only apply to the projects that you are currently running.

You can specify the following options:

Full performance profile
Check this for Profiler to output a full performance profile. If this is not enabled, no statistics are produced for sections or paragraphs that are not entered or PERFORMed. Checking this option is equivalent to setting the ALL directive.
Performance statistics in alphabetical order by paragraph name
Check this for Profiler to output performance statistics in alphabetical order by paragraph name. If this is not enabled, statistics are output in descending order of the total percentage time spent in each paragraph. Checking this option is equivalent to setting the ALPHA directive.
Parent topic: Profiler
Related concepts
Running Your Application with Profiler
Related reference
Directives for Profiler


Running Your Application with Profiler

Running your application with Profiler produces profiling reports.

Having enabled Profiler for a project, you need to execute the application with Profiler in order to generate the Profiler data.

If your application does not require an enterprise server, to run it with Profiler and produce a profiling report, you need to create a run configuration that has profiling enabled and then execute your application with it:

  1. Ensure that Profiler is enabled in your project, for a build configuration or for a file.
  2. Optionally, specify Profiler report generation options in Window > Preferences > Micro Focus > COBOL > Profiler.
  3. Right-click your project in COBOL Explorer, and click Run > Run Configurations.
  4. Right-click COBOL Application and then click New to create a new run configuration.
  5. In the right side of the configuration manager, click the Dynamic Analysis tab of the new configuration.
  6. Check Enable profiling.
  7. Specify a Results directory in your project that will hold the results from profiling. The default name for this directory is Profiler.
  8. Click Apply and then click Run.

    If you have not specified any Profiler report generation options in the IDE preferences, the IDE displays a dialog box with the available options.

  9. Check your preferred options and click OK.

    Running your application with Profiler creates one or more files with an .ipf extension in the directory in your project that you specified earlier. If Profiler is not enabled at project level but for only individual programs, this produces separate filename.ipf files for each program that has profiling enabled in the file properties.

If your application requires an enterprise server, to run your application with Profiler you need to configure the server to run with Profiler and then stop the server. The Profiler report is generated after the server stops:

  1. In the IDE, ensure that Profiler is enabled in your project's properties.
  2. Ensure your project is associated with an enterprise server that is configured to run the application.
  3. Ensure that the enterprise server is configured to run with Profiler - right-click the server in Server Explorer and click Configure Analysis > Profiler.
  4. Start the server from Server Explorer.

    This starts a dialog box prompting you to specify a folder in your project to hold the Profiler reports. Specify the folder to use and click OK.

  5. Execute your application in the usual manner.
  6. Right-click the server in Server Explorer and click Stop.

    Running your application with Profiler creates one or more files with an .ipf extension in the directory in your project that you specified earlier. If Profiler is not enabled at project level but for only individual programs, this produces separate filename.ipf files for each program that has profiling enabled in the file properties.

Viewing the Profiler reports

If, in the IDE preferences for Profiler you checked Clean old profiler output and generate new reports upon run completion, running with Profiler also produces a file with the basename of the first file in your project but with an .prf extension in the subfolder of your project that holds the Profiler output. This is the report file and it opens automatically in the editor. If you profile more than one program at the same time, the Profiler output for all programs is appended to the output file for the first program, filename1.ipf.

If Clean old profiler output and generate new reports upon run completion is not checked, the build only produces the .ipf files. In this case, to generate a Profiler report, right-click one or more of the .ipf files in your project, and click Generate Profiler Report.

The IDE also produces a Profiler report when your project has dependencies on other projects that have profiling enabled. In such cases, the Profiler report file is saved in a subfolder of the project that contains the main program specified in the launch configuration.

Parent topic: Profiler
Related concepts
Configuring the Profiler Reports


Profiler Output

When you run Profiler, the following banner is displayed in the report:

* Micro Focus COBOL Profiler
* name-1
.
.
.
* name-n

where name is one of the files in your project or one of the files listed in filenames, if you are running Profiler from the command line.

The Profiler output lists an overview of the number of times that each program is loaded, and gives the total execution time (in milliseconds) for the program. The results are then broken down for each section (and paragraph) in the program:

Output | Description
%time | Total percentage of execution time spent in the named section or paragraph
time | Total time (in milliseconds) spent in the named section or paragraph
entries | Number of times the named section or paragraph was entered
micros/entry | Average time (in milliseconds) per entry to the section or paragraph
(paragraph OF) Section | The section (and paragraph) to which the performance statistics apply.

The product of the micros/entry and the number of entries should equal the total time spent in the section (or paragraph); however, because all three values are truncated, there can be a slight discrepancy.

Note: Profiler reports can include unnamed paragraphs that appear if a program has sections or divisions without subsequent paragraphs, or in-line PERFORM and EVALUATE statements. (applies to Windows environments only)
Parent topic: Profiler
Parent topic: Profiler


Time Spent in Called Programs

How the run-time system treats the time spent in a called COBOL program that has been compiled with profiling enabled (a profiled program) depends on the value of the profile_behavior run-time tunable. You specify this tunable when you run the program or the application that you want to be profiled.

If the profile_behavior run-time tunable is set to 0 (the default), then time spent in a profiled called program is recorded both in the called program and in the calling program.

If the profile_behavior run-time tunable is set to 1, then time spent in a profiled called program is recorded only in the called program.

For example, suppose program prog_a calls program prog_c. prog_a is a profiled COBOL program. Then:

  • If prog_c is not COBOL, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL but is not profiled, time spent in prog_c is recorded in prog_a
  • If prog_c is COBOL and profiled, time spent in prog_c is recorded in prog_c, and not in prog_a

If prog_a actually calls prog_b, which calls prog_c, and prog_b is not a profiled COBOL program, then time in prog_b is always recorded in prog_a, while time in prog_c is recorded as explained above.

Parent topic: Profiler
Parent topic: Profiler


The Micro Focus Unit Testing Framework

The Micro Focus Unit Testing Framework is an xUnit-style testing framework, available from the Enterprise Developer command line or shell prompt, or from the IDE. It supports native COBOL applications, and if you are using the command line version, procedural applications compiled to managed COBOL.

It includes much of the architecture you would expect of an xUnit framework: you can create, compile, run and debug unit tests from either the command line or your IDE.

Similar functionality is offered whether you use the command line or the IDE to perform these tasks. The IDE version provides a quick and easy solution to running all test cases then providing an overview of the test run. The command line solution can output the results in a number of different formats, for easy integration with your third-party testing and development applications, for example, Micro Focus Silk Central, or a Jenkins CI server.

  • 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.
  • Unit Testing in the IDE
    Use the Micro Focus Unit Testing Framework in your IDE to compose and run unit tests for your COBOL source code.
  • Restrictions in Micro Focus Unit Testing Framework
    The Micro Focus Unit Testing Framework has a number of restrictions on the syntax that a test case can contain.
Parent topic: Programming


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 JUnit format. You can package the JUnit 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 .dll (native Windows), .so (native UNIX), or .jar (JVM COBOL) file.
  • Running Tests
    Tests are run from the Enterprise Developer command line or 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: The Micro Focus Unit Testing Framework


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 Enterprise Developer) 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 must code to produce a working unit test.
  • 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 here are using call prototypes found in the mfunit.cpy copybook, available from the cpylib folder of your product installation directory. 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. 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
Related reference
Examples of using Metadata
Related information
Using Dynamic Metadata


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 on UNIX platforms 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
  • 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 example shows 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 example is an excerpt that 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 example is an excerpt that 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.
...
Parent topic: Using Dynamic Metadata
Related concepts
Elements of a Test Fixture


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
Related information
MFU_ASSERT_FAIL
MFUFMSG
MFU_ASSERT_FAIL_Z
MFUFMSGZ


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 Enterprise Developer 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 %PUBLIC%\Documents\Micro Focus\Enterprise Developer\Samples (Windows), or $COBDIR/demo (UNIX).
  • 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.
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 .dll (Windows) or .so (UNIX) (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
Related concepts
Running Tests
Related information
Compiling 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 .dll (Windows) or .so (UNIX) (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
Related concepts
Running Tests
Related information
Compiling Tests


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: .dll (Windows only), .so (UNIX only), .int, or .gnt.

Windows:

cbllink -D mytestfixture.cbl
cobol mytestfixture.cbl gnt"";

UNIX:

cob -zU -e "" mytestfixture.cbl
cob -e "" mytestfixture.cbl

Once it is compiled, you must run the resulting file from the command line or shell.

Procedural managed code

You must compile the procedural managed COBOL programs as .dll using the JVMGEN (sub) Compiler directive. For example:

Windows:

mkdir bin
cobol myunittest.cbl jvmgen(sub) iloutput(bin);
mfjarprogmap -directory bin
jar -cvf myunittest.jar -C bin .
mfurunj myunittest.jar

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
Related reference
Advanced Test Case Example
Simple Test Case Example
Related information
The cbllink Command
The cob Command


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: .dll (Windows), .so (UNIX), .jar, .int, or .gnt.

If you run a test suite from the Enterprise Developer command line or 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 Enterprise Developer command line or shell prompt to run a test suite.
  • 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 Enterprise Developer command line or shell prompt, and for creating skeleton test fixture files.
Parent topic: Unit Testing from the Command Line
Related reference
Advanced Test Case Example
Simple Test Case Example


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 .dll, .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. The .mfgcf file can be generated by creating a unit test project and fixture file, setting the environment variables and switches in the run-time configuration for the project, and then running the standard test case that was created with the fixture file: during this test run, the .mfgcf file is created in the output folder, where you can copy and rename it for use on the command line.
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 .jar, .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 information
Test Runner Syntax Options
Test Fixture Files
Examples


Test Runner Syntax Options

Use the following syntax from the Enterprise Developer command line or 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. It can be one of:
  • mfurun (Windows) - for use with procedural COBOL
  • mfurunj (Windows) - for use with JVM COBOL
  • cobmfurun32[_t](UNIX) - for use with procedural COBOL
  • cobmfurun64[_t] (UNIX) - for use with procedural COBOL
  • cobmfurunj (UNIX) - 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:

Windows:

mfurun -generate-mfu -trait:smoke test-suite.dll

UNIX:

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.
-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.
-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.
test-suite
A COBOL program compiled to .dll (Windows) or .so (UNIX), or an .mfu test fixture file. For procedural managed program, specify a .jar file instead.
Parent topic: Running Tests
Related information
Configuring the Run-Time System Environment
Test Fixture Files
Examples


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 .dll (Windows) or .so (UNIX) 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 information
Configuring the Run-Time System Environment
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 information
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 Enterprise Developer; 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 information
Example Test Fixture File


Examples

Running test suites

The following command runs all test cases in myFullTestsuite, using the default options:

Windows:

mfurun myFullTestsuite.dll

UNIX:

cobmfurun32 myFullTestsuite.so

The following command only runs the mySecondTestcase test case within the test suite, producing verbose output:

Windows:

mfurun -testcase:mySecondTestcase -verbose myFullTestsuite.dll

UNIX:

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:

Windows:

mfurun -report:junit -jit:core myFullTestsuite.dll

UNIX:

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:

Windows:

mfurun -jit:debug myFulltestsuite.dll

UNIX:

cobmfurun32 -jit:debug myFulltestsuite.so

The following command runs all test cases in myFulltestsuite, ignoring any errors encountered:

Windows:

mfurun -ignore-return-code:true myFulltestsuite.dll

UNIX:

cobmfurun32 -ignore-return-code:true myFulltestsuite.so

Creating and running test fixture files

The following command produces an .mfu file with the same base name as the test suite file:

Windows:

mfurun -generate-mfu myFulltestsuite.dll

UNIX:

cobmfurun32 -generate-mfu myFulltestsuite.so

The following command runs all test cases in the test fixture file:

Windows:

mfurun myFulltestsuite.mfu

UNIX:

cobmfurun32 myFulltestsuite.mfu

The following command runs all test cases in the test fixture file, but any options in the .mfu are ignored:

Windows:

mfurun -ignore-options-in-mfu:true myFulltestsuite.mfu

UNIX:

cobmfurun32 -ignore-options-in-mfu:true myFulltestsuite.mfu
Parent topic: Running Tests
Related information
Configuring the Run-Time System Environment
Test Runner Syntax Options
Test Fixture Files


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
Related information
Run-time System Error Messages
COBRT148 Wrong open mode or access mode for write (Recoverable)


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
Related reference
Test Runner Syntax Options


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 Enterprise Developer command line or 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
Parent topic: Viewing Test Results
Related reference
Test Runner Syntax Options


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.

As with normal COBOL applications that encounter fatal run-time errors, each run-time test failure is written to a debug log file. To ensure this information is captured if you encounter multiple failures, each error generates a <test case-name>-mfdebug.log in the current directory.

Parent topic: Unit Testing from the Command Line


Unit Testing in the IDE

The Micro Focus Unit Testing Framework is an xUnit-style testing framework, available from the Enterprise Developer command line or shell prompt, or from the IDE. It supports native COBOL applications, and if you are using the command line version, procedural applications compiled to managed COBOL.

Within the IDE, group your tests into a unit test project, which can either be located in the same workspace as the application under test, or you can have a standalone test project. Integrating your test cases into the same workspace as the application that you plan to test enables you to directly call into the source code of the application. For stand-alone unit test projects, you need to import a copy of the source code into the project in order to test it.

Each test case is capable of performing a setup, running the test case, and then performing a test teardown. You can also apply certain test metadata to the tests, which in certain cases affects how the test case runs.

The Micro Focus Unit Testing view is the control panel where you run, debug and rerun your test cases. It also shows an overview of the number of successful and failed test cases that you have.

  • Organizing your Workspace
    How you organize your workspace to include unit test projects depends on how you plan to structure your unit tests.
  • Creating Tests
    Unit tests are created in a special unit testing project, where they can link into other projects within the workspace.
  • Running Tests in the IDE
    Tests are run from the Micro Focus Unit Testing view.
  • Debugging Test Cases
    You can debug test cases from the Micro Focus Unit Testing view, using all the usual debug techniques and functionality.
Parent topic: The Micro Focus Unit Testing Framework
Related reference
Tutorial: Running Unit Tests in the IDE


Organizing your Workspace

How you organize your workspace to include unit test projects depends on how you plan to structure your unit tests.

If you plan to call into another program and test that source code, your unit test projects must be in the same workspace as the program you plan to test. You can also create self-contained unit test projects, where the code under test is all stored within the unit test project, in which case, the project can be stored in any workspace.

If you are calling into another project from your unit test project, there are a number of pre-requisites that must be satisfied before you can run your tests. Both your project under test and the unit test project must be compiled to the same bitism, and the project under test must be compiled to a target type of Single Native Library File or All Int/Gnt Files.

A unit test project can call into more than one other project. Within the unit test project, create a test fixture for each project under test. so that when creating the fixture file using the Create unit test from program option, the necessary elements to link the test cases directly to the source code in that project are added.

Parent topic: Unit Testing in the IDE


Creating Tests

The COBOL Unit Test Project is the project type that you can use to perform unit testing on native COBOL programs.

Within these projects, you create test fixtures (type COBOL Unit Test), and within the fixture files, you create the test cases.

Within each test case, you can directly add the code that is under test, thus creating a standalone unit test project. However, the real power of the Micro Focus Unit Testing Framework is when your unit test project calls into another project within the workspace, and tests the code directly at source.

In order to call directly into another project, you must ensure that your unit testing project specifies the project under test in its build path (Properties > Micro Focus > Build Path > Projects); then, using procedure pointers, the test cases can access the source code directly. There are other pre-requisites for linking the two projects, which are discussed in Organizing your Workspace.

When you create a test fixture file, you can use the Create unit test from program option, which will add the necessary configuration required to start coding test cases that call directly into the source code.

Test cases have a number of elements to them, which include a setup phase (to ensure that the test environment is correct), the test itself (which calls into the source code, and makes assertions based on success or failure), and a teardown phase (to tidy up after the test run to ensure no negative effects for subsequent tests). There is also a metadata phase, which can help to configure the run time behavior of your test cases.

  • Create a Unit Test Project
    Use this process to create a unit test project in your workspace, where you can either directly populate it with the code under test, or link it to other projects in your workspace.
  • Create a Native Test Fixture
    Use this process to create a test fixture file within a unit test project, for unit testing native COBOL code. You can directly populate it with your test code, or link it to existing code in your workspace that you plan to test.
  • Writing Tests
    Create test cases from within a test fixture. The Micro Focus Unit Testing Framework contains a number of elements that help with the writing of your test cases.
Parent topic: Unit Testing in the IDE
Related reference
Organizing your Workspace


Create a Unit Test Project

Use this process to create a unit test project in your workspace, where you can either directly populate it with the code under test, or link it to other projects in your workspace.
  1. While in the COBOL perspective, click File > New > COBOL Unit Test Project.

    The New COBOL Unit Test Project dialog box appears.

  2. In the Project name field, type a name for the project.
  3. Click Finish.

    The project is created, and displayed in the COBOL Explorer pane.

You should now create a test fixture file, in which you can code your test cases.
Parent topic: Creating Tests


Create a Native Test Fixture

Use this process to create a test fixture file within a unit test project, for unit testing native COBOL code. You can directly populate it with your test code, or link it to existing code in your workspace that you plan to test.
  1. While in the COBOL perspective, select the unit test project in the COBOL Explorer pane.
  2. Click File > New > COBOL Unit Test.

    The New COBOL Unit Test dialog box appears.

  3. In the Containing project field, ensure it states the name of your unit test project.
  4. In the New file name filed, type the name of your test fixture program.
    Restriction: Do not use the file name mfunit, as this will not run within the Micro Focus Unit Testing Framework.
  5. At this point, you can create a test fixture that links into an existing COBOL program, or create a standalone test fixture (in which you will add the code under test directly to the test cases):
    • To create a linked fixture file, select Create unit test for program, then click Browse, select the program that contains the code you want to test, then click OK.
      Note: The selected program must be from a local project that is built to a single native library file or all int/gnt files, and must share the same Platform Target setting as your test project.
    • To create a standalone fixture file, select Create Unit Test from Template, then select Micro Focus template.

      You may have also configured your own templates; in which case, choose an appropriate template.

  6. If you have selected Create unit test from program, you can click Next to review and select the entry points in the program for which you want to create test cases.
  7. Enable the check boxes for the entry points for which you want to create test cases.
  8. Click Finish.

    The test fixture file is created within the unit test project.

Both types of fixture file contain similar stub code. Some of the essential elements and additional configuration (required for linked fixture files) are as follows:
Note: The following excerpts were a result of selecting a program from the AirportDemo project.
  • The two copybooks required by the Micro Focus Unit Testing Framework are copied into the project.

  • A test setup and a test case have been created.

  • A procedure pointer has been added to the test setup that enables you to call into the source code, and a level 78 constant for the test case name has been added (to help when creating the different elements of the test case).

  • The Linkage section from the source program has been replicated in the Working-storage section, initialized, and a CALL statement coded in the test case.

  • The project containing the program under test is added to the Projects tab of the Build Path properties.

Parent topic: Creating Tests
Related reference
Create a Unit Test Project


Writing Tests

When you create a test fixture, stub code is inserted to help you code your first test case.

Some of the elements are optional, and you may not require them; review the Elements of a Test Case for information on which elements are mandatory and the types of content each should contain.

There are also code snippets templates available within the IDE editor that help you to create additional test cases.

If your test fixture is testing source code in another project, the stub code for the first test case created contains additional INITIALIZE and CALL statements, to allow you to call directly into the source under test. Use a similar structure when creating further tests.

The Micro Focus Unit Testing Framework also contains a number of library routines for making test assertions that determine the outcome of a test case.

  • Elements of a Test Case
    Test fixtures can contain one or more test cases, and each test case can have a number of elements to it. These elements are coded as specific entry points that the Micro Focus Unit Testing Framework can recognize.
  • Unit Testing Code Templates
    Code templates enable you to quickly and reliably insert certain common code constructs. Your IDE editor contains a number of snippets relating to coding test cases as part of the Micro Focus Unit Testing Framework.
  • 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.
  • Example - Creating a Test Case
    A simple example of a test case that performs a setup, the test case itself, and a teardown.
Parent topic: Creating Tests


Elements of a Test Case

Test fixtures can contain one or more test cases, and each test case can have a number of elements to it. These elements are coded as specific entry points that the Micro Focus Unit Testing Framework can recognize.

The Micro Focus Unit Testing Framework uses a number of call prototypes to help construct the entry point names. These prototypes are located in the mfunit.cpy copybook, which is available from the cpylib directory of your product installation directory.

Note: If you are unable to use the copybook, due to its use of 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

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
...
Tip: Use the code template testsetup to enter the stub code for a test setup.
The test metadata setup
There are a number of metadata details that you add directly through your source code, such as test description and test timeout; see Using Dynamic Metadata. This section is optional.
...
entry MFU-TC-METADATA-SETUP-PREFIX & "MyTestCase"
*>initial metadata setup code goes here
goback
...
Tip: Use the code template testdata to enter the stub code for adding test metadata.
The test case
This section contains the actual testing logic and test assertions.
...
entry MFU-TC-PREFIX & "MyTestCase"
*>test case code goes here
goback
...
Tip: Use the code template testcase to enter the stub code for a test case.
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
...
Tip: Use the code template testteardown to enter the stub code for a test teardown.

Test cases cannot share setups or teardowns; you must code a separate setup or teardown for each test case that requires one.

The sections relating to a test case can appear in your code in any order, but are run in the order shown here.

Parent topic: Writing Tests


Unit Testing Code Templates

Your IDE editor contains a number of snippets relating to the Micro Focus Unit Testing Framework; to insert one, type the shortcut in your editor and press Ctrl+Space. The snippet is inserted into the code, and you are prompted to enter the test case name: either select the name from a list of level-78 constants that are defined in the program, or type a literal string.

Tip: Before creating a test case, create a level-78 constant for <test-case-name>; the value of this is offered from a list when inserting the template. Using the constant in the entry point names eradicates any spelling mistakes that may occur when creating the different elements for the test.
shortcut snippet description
testcase
entry mfu-tc-prefix & <test-case-name>.
   *> Test code goes here.
   goback returning MFU-PASS-RETURN-CODE
   .
 The main element of a test case. It's the section that contains the actual testing logic and test assertions.
testdata
entry mfu-tc-metadata-setup-prefix & <test-case-name>.  *> the test case meta data
  move "ex. of a dynamic description" to mfu-md-testcase-description
  move 10000 to MFU-MD-TIMEOUT-IN-MS
  move "smoke,dynmeta" to MFU-MD-TRAITS
  set MFU-MD-SKIP-TESTCASE to false
  goback returning 0
  .
 An optional element to a test case. It's the section that associates metadata with the test case. See Using Dynamic Metadata for more information on how to use the options shown here.
testsetup
entry mfu-tc-setup-prefix & <test-case-name>.  *> the test case setup
  goback returning 0
  .
 An optional element to a test case. It's the section that sets up the environment before the testing logic is run.
testteardown
entry mfu-tc-teardown-prefix & <test-case-name>. *> the test case tear-down
  goback returning 0
  .
 An optional element to a test case. It's the section that tidies up after the testing logic has run.
Parent topic: Writing Tests
Related concepts
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.

  • Test Output Examples
Parent topic: Writing Tests
Related reference
MFU_ASSERT_FAIL
MFUFMSG
MFU_ASSERT_FAIL_Z
MFUFMSGZ
Example - Creating a Test Case


Test Output Examples

The following excerpt is taken from the tutorial, and demonstrates how to set the outcome of a test case (if the condition is not met) to failed.

...
           if function numval(distance-km) not equal 4787
               string "Incorrect distance in kilometers returned - "
                       distance-km delimited by size
                       x"0" delimited by size
                       into errormessage
               end-string
               call MFU-ASSERT-FAIL-Z using errormessage
           end-if
...

This code will also display the errormessage text in the output pane if distance-km is not equal to 4,787:

Another way to assert a test to have failed is to set a non-zero return code:

move 1 to return-code

Or (when using mfunit.cpy):

goback returning MFU-FAIL-RETURN-CODE

This results in the following output:

Parent topic: Determining a Test Outcome


Example - Creating a Test Case

The following example creates a simple test case that includes setup code, a simple test that writes to a data file, and a teardown that tidies up the test at the end. You can enhance this test further by including your own test assertions in the main test case section.
  1. Create a unit test project (see link below).
  2. In COBOL Explorer, ensure that the project is selected, then click File > New > COBOL Unit Test.

    The New COBOL Unit Test dialog box appears.

  3. In the Containing project field, ensure it states the name of your unit test project.
  4. In the New file name field, type the name of your test fixture program.
  5. Select Create Unit Test from Template, then select Micro Focus template.
  6. Click Finish.

    The test fixture file is created within the unit test project, and includes the skeleton code required for one test case.

  7. This short example test uses a data file, and so add the following to the configuration section:
    input-output section.
       file-control.
       select cust assign to 'cust.txt'
       organization is line sequential.

    And add the following immediately after the line data division:

           file section.
       fd cust.
       01 cust-file.
          03 customer-id    pic 9(5).
          03 customer-info  pic x(65).
  8. Add the following statement immediately after the line entry MFU-TC-SETUP-PREFIX & TEST-program-name.
           open output cust

    This sets up the test by opening the file, ready for any file operations performed in the test case itself.

    The MFU-TC-METADATA-SETUP-PREFIX & TEST-program-name entry point contains some details about the test case.

  9. Edit the first statement of the MFU-TC-METADATA-SETUP-PREFIX & TEST-program-name entry point to read:
    move "This is a simple test to write to a data file" to MFU-MD-TESTCASE-DESCRIPTION
  10. Add the following code within the test case, which is immediately after the line entry MFU-TC-PREFIX & TEST-program-name:
           move 0 to customer-id
       perform 100 times
        add 1 to customer-id
        move "A customer" to customer-info
        write cust-file
       end-perform.

    The test case performs a simple write operation on the file. if this fails, the test case is marked as failed. This is also the section in which you would add your own test assertions; see Determining a test outcome for more information.

  11. Add the following statement immediately after the line entry MFU-TC-TEARDOWN-PREFIX & TEST-program-name:
           close cust.

    The teardown section tidies up the environment.

    The test case is now complete, ready to be run; refer to Running Unit Tests.

Parent topic: Writing Tests
Related concepts
Determining a Test Outcome
Related tasks
Running Unit Tests


Running Tests in the IDE

The Micro Focus Unit Testing view is where you run your test cases, and where you can view the results of completed test runs. You can run:

  • Individual test cases
  • All test cases in a test fixture
  • All test cases that ran in the previous test run
  • All currently failed test cases

The Test Results pane shows an overview of the test run, breaking it down into the number of passed, failed, and skipped tests; it also displays any output messages when individual test cases are selected.

  • Running Unit Tests
Parent topic: Unit Testing in the IDE


Running Unit Tests

To display unit tests in the Micro Focus Unit Testing view, you must first run the unit test project that contains them. Only then will you see the test fixtures (the .cbl files within the project), and test cases within them.
Note: The first time you run or debug a test fixture, you may be prompted with a Windows security alert, informing you that the Windows firewall has blocked the process. You need to allow Eclipse access to your network before you can continue; this should only be a one-off process.
  1. In the Micro Focus Unit Testing view, do one of the following:
    • To run all test cases in the test fixture file, click [image] (Run All).
    • To run a single test case, right-click it, then select Run.
    • To run multiple test cases, hold down Ctrl and click each required test case, right-click, then select Run.
      Note: The selected test cases can belong to different test fixtures, if required.
    • To re-run the selection of test cases that last ran, click [image] (Rerun Last); all other test cases are marked as skipped.
    • To re-run all failed tests, click [image] (Run Failed); all other test cases are marked as skipped.

    The selected test cases are run. The red indicator bar shows the progress of the test run; when complete, a breakdown of the completed test cases, including number of errors and failures is displayed.

  2. To view any messages that a particular test generated, select it from the hierarchy.

    The results appear in the Test Results pane.

Parent topic: Running Tests in the IDE
Related reference
Unit Testing Routines
Example - Creating a Test Case


Debugging Test Cases

To debug a test case, use the Debug option available in the Micro Focus Unit Testing view, ensuring that you have a breakpoint set at the required point(s) of execution.

Using this option runs the test case (or series of test cases if you have selected a test fixture) within the normal debug engine.

Note: The first time you run or debug a test fixture, you may be prompted with a Windows security alert, informing you that the Windows firewall has blocked the process. You need to allow Eclipse access to your network before you can continue; this should only be a one-off process.
Parent topic: Unit Testing in the IDE


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

  • Application Workflow Manager
  • C Functions for Calling COBOL
  • COBOL Language Reference
  • Codeset Translation
  • Command line reference
  • Compiler Directives
  • Configuring CCI
  • Environment variables (Windows)
  • Environment Variables (UNIX)
  • Error Messages
  • File Handling Reference
  • Integrated Preprocessor Interface
  • Java Artifacts
  • Library Routines
  • Restrictions, Compiler Limits, and System Limits
  • Mainframe Reference
  • Managed COBOL
  • Panels
  • Run-time System Configuration
  • Terminfo Database and Terminal Devices
  • UNIX Key Usage Chart
  • Service Interfaces
Parent topic: Micro Focus Enterprise Developer 4.0 for Eclipse


Application Workflow Manager

  • What is AWM?
  • Workflow Manager Modeling Guide
  • Workflow Manager ChangeMan Attachment
  • Workflow Manager AMB Attachment (Technology Preview)
  • Workflow Manager Endevor Attachment
  • Workflow Manager SCLM Attachment
  • Workflow Manager SVN Attachment
  • Workflow Manager Troubleshooting
  • Installing Micro Focus Modelling Support for Eclipse
Parent topic: General Reference


What is AWM?

The Application Workflow Manager (AWM) is a framework based on the Eclipse Modeling Framework (EMF) which enables you to seamlessly integrate an application development workflow into an Eclipse IDE. Modifying an AWM model enables you to adapt and extend the EMF model so that you can integrate an application development workflow according to your organization's requirements.

At run time the AWM model is loaded and interpreted as an AWM application. The AWM application can modify the functionality and user interface of the views contributed by AWM to the Eclipse IDE enabling you to customize the workflow as required.

AWM provides a number of function packages that contain objects and tools that enable you to develop application workflow in specific areas. For example, a function package containing tools to handle Eclipse resources.

An interface is provided that enables you to extend or develop your own function package. See AWM API Programming and Extension Points for more information.

AWM provides you with the Team Developer perspective that contains views and editors to assist the development process.

The Team Developer perspective provides the following views. See Views for more information.

  • Application Explorer view
  • Error Feedback view
  • Filter Definitions view
  • Jobs view
  • Table Results view

To open the Team Developer perspective:

  1. Click Window > Perspective > Open Perspective > Other.

    This opens the Open Perspective dialog box.

  2. Click Team Developer.
  3. Click OK.
Parent topic: Application Workflow Manager


Workflow Manager Modeling Guide

  • About This Guide
  • Introduction to the Data Model
  • Data Model Details
  • Setting up the Application Workflow Model
  • Function Packages
  • Extending the AWM Meta Model
  • AWM API Programming and Extension Points
  • Example AWM: MVS Projects Sample Application
  • Use Case-Based Modeling Examples
  • AWM Model Maintenance
  • Workflow Manager Modeling Tutorials
Parent topic: Application Workflow Manager


About This Guide

  • Who Should Read This Guide?
  • Preconditions
  • Examples
  • List of Abbreviations
  • Overview
Parent topic: Workflow Manager Modeling Guide


Who Should Read This Guide?

This guide serves as a reference for creating workflow models and for the programming of tools using the attachment interfaces.

The guide is not for users who have not yet worked with the application workflow data model. Those who have not worked with an application workflow data model should attend a training course or a coaching session.

Parent topic: About This Guide


Preconditions

You must have installed either an Enterprise Developer product or IDz with the Application Workflow Manager plug-in on top of IDz.

Some AWM Function Packages described in this guide are only available if a specific product or a specific license is installed:

  • The ISPF, MVS, and USS function packages are only available if a license of Enterprise Developer Connect or Enterprise Developer for z Systems is installed.
  • The Micro FocusEnterprise Server and Micro Focus Project function packages are only available if a license of Enterprise Developer or Enterprise Developer for z Systems is installed. Neither Function Packages are available in IDz.
  • The Micro Focus Editor Function Package is not available in IDz.
  • The IDz function package is only available in IDz.

You need Eclipse plugin development skills to develop your own function packages or to extend a function package. This guide describes the usage of function package which does not require plugin development skills.

You need ISPF programming skills to understand the content related to attaching ISPF tools and REXX procedures.

If the application modeling and attachment of the tools are carried out by different people, precise coordination is necessary between the modeling work and the tool attachment.

Parent topic: About This Guide
Related information
ISPF Function Package
Micro Focus Editor Function Package
Micro Focus Enterprise Server Function Package
Micro Focus Project Function Package
MVS Function Package
IDz Function Package
REXX Procedures
SVN Function Package
USS Function Package


Examples

Some of the examples in this guide are taken from the standard SCLM model supplied by Micro Focus as a tool attachment for mainframe development of sources under source control by IBM SCLM.
Note: These Examples require some minor ISPF REXX knowledge.
Parent topic: About This Guide


List of Abbreviations

API | Application Programming Interface
AWM | Application Workflow Manager
COBOL | Common Business Oriented Language
CSV | Comma Separated Values
ED | Micro Focus Enterprise Developer
EDc | Micro Focus Enterprise Developer Connect
EDz | Micro Focus Enterprise Developer for z
EMF | Eclipse Modeling Framework
ENDEVOR | CA Endevor Change Manager (Environment for Developers and Operations)
GUI | Graphical User Interface
IBM | International Business Machines Corporation
IDE | Integrated Development Environment (in this guide used to refer to ED, EDc, EDz or IDz)
IDz | IBM Developer for z Systems
ISPF | Interactivity System Product Facility
JCL | Job Control Language
JES | IBM Job Entry Subsystem (either JES2 or JES3)
JES2 | IBM Job Entry Subsystem 2
JES3 | IBM Job Entry Subsystem 3
LPEX | Live Parsing Extensible Editor (in this guide used for an IBM Editor integrated in IDz)
MFA | Micro Focus Mainframe Access
MVS | Multiple Virtual Storage, used in this guide to distinguish the MVS file system (datasets and members) from the USS file system.
OS | Operating System
PC | Personal Computer
PDS | Partitioned Data Set, if not explicitly mentioned this could mean PDS or PDSE
PDSE | Partitioned Data Set Extended
PL/I | Programming Language One
PO | Partitioned Organized, this term is used for MVS dataset organizations, either PDS or PDSE
RDz | IBM Rational Developer for z Systems
RSE | Remote Systems Explorer, aka Eclipse Target Management
RSED | IBM RSE Daemon, IBM z/OS server for IDz
SCLM | IBM Software Configuration and Library Manager
SCM | Software Configuration Management
TSO | Time Sharing Option
SVN | Apache Subversion
UI | User Interface
USS | z/OS Unix System Services
VSAM | Virtual Storage Access Method
XML | Extensible Markup Language
z | (for IBM products such as System z, z/OS,..) Zero Downtime
z/OS | (Zero Downtime) Operating System
z/Server | Micro Focus z/OS server for EDc and EDz
Parent topic: About This Guide


Overview

AWM uses the following general expressions to describe the tool integration as flexibly as possible:

Expression | Description
Element An Element usually describes an object that is managed in the tool that is to be integrated in the AWM model. A file or a database record is usually connected to it, and there are tools processing the elements.

Example: COBOL program TEST4711

Project: PRJ4711

Element list | An element list is a list of elements with defined properties that is drawn up according to specific criteria. An element list is presented in the form of a table. The structure of the table can be a flat table or a tree table.
Container A Container is a specific element which contains or references other elements, directly or indirectly. Containers can also include other containers. The Container structure is presented in the form of a tree view.

Example:

PDS file: USER01.TEST.COBOL (contains PDS members)

Project: PRJ4711 (contains applications)

Order: CHG4711 (contains sources connected to this change record)

Container is only a logical concept in AWM. It has no physical representation in the AWM data model.

Filter A Filter describes criteria from which a list of elements can be derived.

Example: All PDS members in USER01.TEST.COBOL, whose names begin with TEST.

Action An Action is an integrally closed function that can be triggered in the user interface, for example, a function in the context menu of an element. An Action can be made up of several working steps (tools), for example, an input dialog box, several tools processing the input data, and an output dialog dox.

Example: Compile (in the context menu for Element TEST4711)

Tool A tool is the smallest processing step that can be described in the AWM model, and generally processes inputs and creates outputs.

Example:

The REX1234 procedure for executing a Compile

The input dialog to enter compile parameters.

Property | Properties are the characteristics of objects. Properties occur with different meanings, for example, as the property of an element, as filter criterion, as the input or output parameter of a tool, as the input or output field in a dialog box.
Resource | A Resource is an object that can be selected in the application user interface, that usually has properties, and on which actions can be carried out. Resources in the sense of this definition are, for example, elements, containers, and filters.
Function Package Bundle of specific functions which can be used within a model. Function packages can also be defined by third-party developers, effectively extending modeling capabilities and functions.

Examples:

  • ISPF function package.
    • Provides ISPF tools like “Execute ISPF Command”.
  • Eclipse function package.
    • Provides standard Eclipse tools to be used in a model.
    • Provides automatic synchronization between Eclipse workspace files and modeled AWM elements.

A complete Eclipse-based user interface for the integration of tools can be described with the help of the AWM model editor and the expressions defined above.

Example

Several Elements can be identified in an SCM system. Elements can either represent the files managed by the SCM system or Containers in which the files are structured, such as projects, stages, and folders.

All elements have Properties. A property is an attribute of a type and is assigned a value at run time, for example, file name.

Tools, on the other hand, use properties as input parameters and assign properties to their output parameters. Tools are components of Actions to which elements can be assigned. Examples include Check-out, Edit, Compile, Delete.

A Delete tool, for example, requires the file name of the file to be deleted as an input parameter. The file exists as an Element, and has the property “File name”. The tool is modeled in the AWM model so that it uses the “File name” property as an input parameter. Used on an element, its file name is transferred to the tool, and the file is deleted.

You can define the elements that you would currently like to work with, using Filter at run time. The criteria by which elements can be searched can be entered in the filter dialog. The corresponding elements can be returned via an action. Returned elements are managed in element lists.

All the object types are shown below:

Major Data model objects and relationships (simplified)
Parent topic: About This Guide


Introduction to the Data Model

The modeling of the user interface and the tool attachment using the Workflow Manager requires a detailed understanding of the data model. This is necessary in order to embed the tools in the development interface in the optimal location to maximise performance while complementing an intuitive user interface.

Through the classification and formal description of the terms introduced in the previous chapter, a model is produced, which is stored in an XML file, the AWM model file. A model of this kind can be created for every application system that you wish to connect.

This section introduces the most important concepts and describes them in more detail.

  • Function Package
  • Element Type
  • Element List Structure
  • Filter Type
  • Property
  • Action Descriptor
  • Tool Descriptor
Parent topic: Workflow Manager Modeling Guide


Function Package

A function package installed in the IDE and used in an AWM model extends the model with additional functionality.

All tools to be used in the model must be derived from a function package. If no function package is installed, you would not be able to define a Tool Type.

A function package can provide the following AWM modeled objects:

  • New AWM tool types and tool type attributes including rules for how to model such tools and validation rules. This also includes the support for how to define tool input and output parameters in a consistent way.
  • Linked Properties which can be modeled in AWM like other properties. Unlike non-linked properties, the values of linked properties are not managed by AWM; the values are directly provided by the function package. There is no specific tool necessary to get or set a value of a linked property and the data consistency is guaranteed.
  • Linked element types which are modeled in AWM as element types. Although elements of linked element types are managed by AWM, the function package can provide the real-time synchronization of the integrated application objects with the corresponding AWM elements. In addition, the function package can dynamically provide the element icons and its icon decorators. There is no need to model those icons as element type icons in AWM.
  • Additional icons which are modeled as AWM icons and are typically used as action icons.
  • Function package attributes add general options to a function package, which can be configured in a AWM model.

Micro Focus provides the following function packages:

Function Package | Description
AWM | Provides AWM-specific features, such as "Open a Modeled Dialog".
Deprecated | Only relevant if a model still contains tool descriptors which were supported before function packages were introduced and which have not been converted into function package tools.
Eclipse | Provides native Eclipse functions, such as "Get Eclipse Projects".
ED Icons | Provides Enterprise Developer-specific action icons.
ISPF | Provides ISPF-specific functions, such as "Execute ISPF Command" and "Execute ISPF Dialog Application".
Micro Focus Editor | Provides functions specific to the editor in Micro FocusEnterprise Developer, such as "Reparse with Refresh".
Micro Focus Enterprise Server | Provides functions to manage Micro FocusEnterprise Server, such as "Submit to Enterprise Server".
Micro Focus Project | Provides functions specific to Micro Focus projects, such as "Compile File".
MVS | Provides MVS-specific functions, such as "Edit MVS File".
OS | Provides basic local operating system functions, such as "Execute OS Command".
IDz | Provides IDz-specific functions, such as "Associate Property Group".
SVN | Provides Subversion-specific functions such as "SVN Commit".
USS | Provides USS-specific functions, such as "Edit USS File".

The topic Preconditions describes which product and/or license must be installed to be able to use a specific function package.

Customers or third party companies can provide their own function packages by extending the AWM model extension point defined for this purpose.

Parent topic: Introduction to the Data Model
Related information
AWM Function Package
Deprecated Function Package
Eclipse Function Package
ISPF Function Package
Micro Focus Editor Function Package
Micro Focus ED Icons Function Package
Micro Focus Enterprise Server Function Package
Micro Focus Project Function Package
MVS Function Package
Operating System Function Package
Preconditions
IDz Function Package
SVN Function Package
USS Function Package


Element Type

A class of elements is called the Element Type.

The element types are derived through analysis of the application systems to be connected. The classification of elements can be rough or fine. The advantage of a fine categorization is that properties and actions can be explicitly assigned to every element type in further modeling processes.

Examples:

  • Element types for an SCM system
    • Editable element (rough categorization)
    • Non-editable element (rough categorization)
    • Program source (fine categorization)
    • COBOL program (very fine categorization)
  • Linked Element Type
  • Container Element Type
Parent topic: Introduction to the Data Model


Linked Element Type

Linked element types are specific element types provided by function packages, that link to resources outside of AWM. Function packages can extend the functionality of these element types in a number of ways.

To define a new linked element type in your AWM model, you have to add the corresponding function package to your model. Then create a new element type by selecting the linked element type from the function package.

Linked element type functions include but are not limited to:

  • Display dynamic custom element icons.
  • Extend the context menu of elements dynamically.
  • Synchronize elements with the target platform in real time.

Examples:

  • Eclipse resource:
    • Provides standard Eclipse icons with decorations.
    • Synchronizes elements of this type with workspace resources, even if changes are made outside of AWM.
    • Provides standard context menu commands like Compare With.
Parent topic: Element Type
Related reference
Linked Element Types for the MVS Function Package
Linked Element Types for the Eclipse Function Package


Container Element Type

Any Element Type can be modeled as a Container Element Type. Container element types represent elements that are able to contain or reference other elements. Therefore container element types are used to define a hierarchical structure of a connected system.

Note: Container Element Type is a logical concept. There is no physical representation of it in the AWM meta model.

Examples:

  • Container Element Types for an SCM system
    • Project (a project may contain development stages as elements)
    • Stage (a development stage may contain source types)
    • Source (an element may contain Includes or Copies)
    • COBOL Copy (a COBOL Copy may contain other Copies)
Parent topic: Element Type


Element List Structure

In order for elements to be shown in a tabular form in the user interface, a formal description of this table structure is needed.

To do this, element lists with the same properties are described as an Element List Structure.

Examples:

  • Structure of a Work Item List with the properties:
    • Work item number
    • File name
    • Change date
    • Last editor
  • Structure of a Version List with the properties:
    • File name
    • Version number
    • Creation date of the version
Parent topic: Introduction to the Data Model


Filter Type

Filters with the same types of filter criteria are referred to as Filter Types.

Filter types are described by Filter Criteria, which determine the rules by which elements will be searched in an application system for further application processing.

Examples:

  • Work Item filter
    • Criteria to determine all files that are allocated to a work item
  • File name filter
Parent topic: Introduction to the Data Model


Property

A Property in the data model is the description of an attribute whose value can be determined at run time.

For example, a "Text document" element type is assigned the properties “File name”, “Change date” or “Write protected”.

These characteristics are called Properties. They represent individual attributes, and describe how their values are to be interpreted. The property value can only be determined at run time.

For example:

Property Data Model | Property Value Data
File name | MyDocument
Change date | 2014/05/25
Write protected | True

The table indicates the three properties that have been assigned to the “Text document” element type. The individual property values have different meanings. “File name” can contain any type of characters, “Change date“ is a date field and “Write protected” is a Boolean value. At run time, these values can be interpreted in different ways in a tool attachment, whereas an exact description of the properties is required in the data model.

Properties can be referenced from different model classes. Depending on the class in which the “File name” property is referenced it is processed differently. If the property is referenced from an element type, the “My Document” property value could be the labelling of the element. A tool can also reference the same property, and use it as an input parameter.

The meaning of a property only becomes clear in context with the reference. In most cases, Properties are referenced via Relationships, see the figure below.

Referencing of Properties

Model classes (blue framed) reference Properties (green framed) through Relationships (red framed)

  • Linked Properties
Parent topic: Introduction to the Data Model


Linked Properties

Linked properties are properties which are linked to other properties and are provided by a function package.

A property can be linked to a function package property when you define it. To do this, the property must be selected from the list displayed under the corresponding function package in the property creation menu.

The corresponding function package's property provider supplies the list of linked properties in the property creation menu.

With linked properties, values are not internally maintained by AWM during run time. When a property value of a linked property is needed during run time, AWM forwards the request to the corresponding function package. The function package can then provide or set the property value.

Most linked properties require a Resource Identifier in order to be resolved, which is a reference to a property which must contain a unique ID of a resource from which to obtain the property value at run time.

Example: Model

  • Linked property: Last Modified (Eclipse function package)
  • Resource identifier: PROP_Eclipse_ResourcePath

Example: Run time

  • Resource identifier value at run time: \TestProject\TestFolder\TestFile.txt
  • Linked property value at run time: "9/21/15 2:50 PM"

Whether or not a resource identifier is required depends on the linked property, or more specifically, whether the property belongs to a specific resource. Linked properties not requiring an identifier are usually global properties like system variables or preferences. In the model editor, the “Resource Identifier” attribute of a linked property only appears if it is necessary for the property, and if not set, a validation error occurs upon validation.

Unlike other properties, for example, properties referenced by input parameters of a tool descriptor, resource identifier properties are only resolved from an element’s properties. This means that a linked property requiring a resource identifier can only be resolved for an element type which also contains the resource identifier as a property.

Example:

In order to resolve the linked property “Last Modified”, see example above, an element must be selected at run time, which contains the “PROP_Eclipse_ResourcePath” property because it is the resource identifier of the linked property.

Parent topic: Property


Action Descriptor

An action is a closed function that is triggered in the user interface. An action can consist of a number of tools. In the data model the description of an action is called the Action Descriptor. An Action Descriptor must refer to at least one Tool Descriptor. The processing sequence of the tools of an action are determined by the sequence of the ActionHasTool relationships.

The execution of an action is usually triggered actively by a user. In some cases, an action can also execute automatically, such as determining an element's properties.

At run time, actions can occur:

  • As an Expand function of structural elements.
  • In the context menus of filters.
  • As a standard action for filters (refresh or double-click).
  • In the context menus of elements.
  • As a standard action for elements (double-click).
  • In the context menus of tables derived from a structured file descriptor.
  • In the Eclipse menu bar.
  • In the context menus of editors.
  • In the context menu of an AWM application.
  • To update the properties of an element.
  • To refresh an element list.
  • As a button in a modeled dialog to retrieve valid property values.
  • As a validate action in a modeled dialog.

The actions that should be carried out for the listed types are defined in the AWM model through the relationships of the types (element type, filter type and so forth) to action descriptors. Actions which do not belong to a certain type must be modeled as a global action. See Global Action for more information.

Parent topic: Introduction to the Data Model
Related information
Global Action


Tool Descriptor

A tool is an executable program that can communicate with the client application via input/output parameters. The prerequisites for the attachment of tools are the implementation of interfaces for the tool call-up and the communication with the target system.

A tool is defined in the AWM model by a Tool Descriptor. Every tool in an AWM model is part of a function package. The attributes of a tool descriptor depend on the attributes defined in the AWM model extension for this tool.

A tool descriptor describes a tool in such a way that the model interpreter can execute it and can react to its outputs.

The following are standard attributes defined in a tool descriptor:

  • The tool identifier
  • Resource operations (for example, Insert element into View)
  • Input parameters
  • Output parameters
  • File parameters

These standard attributes can be extended by attributes defined by the AWM model extension for this tool.

Tool Descriptor (top) and its relationships (dashed boxes, center) to Properties, which are interpreted as input or output parameters.

Example:

The only parameter of the REXX tool “Delete file” is the name of the file that should be deleted. In order to attach this tool, you must define a tool descriptor. The parameter for the file name is described via the “Has_InputParameter” relationship. The relationship should reference a property that fulfils the logical meaning of the parameter itself, namely a property that represents the file name of an element. If the tool descriptor (as a component of an action descriptor) is executed on an element at run time, the property value of the file name property is transferred to the tool as an input parameter (see the figure below).

Workflow Model Tool Descriptor

The “Delete File” tool is shown on the left, together with an associated z/OS file. This situation is transferred to a Workflow model on the right-hand side. The input parameter of the tool descriptor references the same property that the element type has.

If the input parameter is not related to the selected element (or to the selected resource), the “origin” of a parameter can be defined in more detail in the AWM model. An input parameter can also be derived from the output of a previous tool.

Parent topic: Introduction to the Data Model


Data Model Details

The following chapter contains a detailed description of all data model object types, relationships, and attributes.

All the attributes are listed in a table, and more complex attributes and relationships are explained in more detail in the subsequent topics. The most important attribute properties are represented in the tables by the following symbols:

Symbol | Description
* or [M] | Mandatory attribute. This attribute must be assigned a value.
[C] | (Choice) Occurs if there are at least two attributes for a type or relationship. Only one of these attributes may be assigned a value or set to true.
[D] | (Dependency) Occurs if there are at least two attributes for a type or a relationship. These attributes depend on each other and must be modeled in a specific way.
[O] | (Optional) Optional attribute. Optional attributes do not have a standard value and can be left empty.
[U] | (Unique) The value of this attribute must be unique among the siblings of the same type.
[UC] | (Unique Choice) Precisely one type or one relationship among the siblings must set this attribute to true. Only occurs with boolean attributes.

Certain attributes, such as ID and Label are assigned to several object types and relationships. In principle, these always have the same meaning:

ID
Mandatory attribute. The value of this attribute must be unique in the model. The use of a naming convention is recommended.
Label
Optional attribute. Labels are used for the display of objects and fields in the user interface. If the model interpreter does not find a label for an object of a type, the next matching attribute is taken, which could be a label for a higher hierarchy level or the ID of an object type.

Example:

Action Descriptor ACT_DELETE Label = “Delete Member”
Element ELE_Member has Action Descriptor (relationship): Label = “” (empty)
Element ELE_Task has Action Descriptor (relationship): Label = “Delete Task”

For elements of type “ELE_Member”, the label “Delete Member” matches the action, which should delete a member. Elements of type “ELE_Task” should be deleted by clicking Delete Task in the context menu, even if the same action descriptor is hidden behind it. In this case, the label of the action descriptors can be “overwritten” with the label of the relationship. If the action descriptor “ACT_DELETE” has no label, its ID is used.

It is also possible to define sub-menus in context menus by using the forward slash character “/” in label definitions for action descriptors. Every block of characters ending with a “/” results in a submenu at run time. If a forward slash character should be used as part of a label or menu, it must be entered as double slash (//).

Example:

The label definition “Test Submenu/Another Submenu/Some Action” creates two sub-menus in any context menu:

  • Test Submenu
    • Another Submenu
      • Some Action
The label definition “File Actions/PL//I/Browse Includes…” creates two sub-menus in any context menu:
  • File Actions
    • PL/I
      • Browse

Complex attributes are made up of several individual attributes. Relationships and complex attributes can appear several times within a type.

Cardinalities of the following relationships and complex attributes are described in tables in the following topics:

  • 0..1 = Optional
  • 0..* = Any number (also none)
  • 1..* = At least one required
  • 1..1 = Exactly one required
  • Action Descriptor
  • Application Options
  • Element List Structure
  • Element Type
  • Enabled/Visible Condition
  • File Descriptor
  • Filter Type
  • Global Action
  • ID Definition
  • Icon
  • Property
  • Tool Descriptor
  • Variable References
  • Tree View Label Determination
Parent topic: Workflow Manager Modeling Guide


Action Descriptor

An action descriptor describes a sequence of tools. Actions can be executed at the following locations:

  • In the context menus of the application entry and of elements, filters, file descriptors, and jobs. The context menus are modeled for each type using the relationship Has_Action.
  • In the context menu of an Eclipse text editor modeled as a global action.
  • In the IDEs main menu bar and in the context menu of a global action entry visible under the application's entry in the Application Explorer view if the action is defined as a global action.
  • Determining/updating the property values of an element (the Get_All_Properties attribute of the element type).
  • Creating/updating an element list or expanding a container element within tree view.
  • Saving/closing the editor during an editing procedure.
  • Determining the permitted values for a property.
  • Actions associated to Application Options can be executed automatically when the application is loaded or unloaded.
  • Validate the values entered in an AWM modeled dialog.
Attribute | Type | Description
ID * | ID * | The ID of the action descriptor.
Label [O] | String | The labeling of the action descriptor. The label of an action descriptor is mainly seen in the context menu. References to a property within the label are resolved to the current property value.
Execution Mode | Selection | Valid values are MODAL or MODELESS. The action is executed in the background if you are using the MODELESS option which means that the UI is not blocked until the action has finished. For ISPF non-dialog tools, you must make sure that no parallel ISPF requests are sent to one ISPF session.Micro Focus recommends you use the MODAL option, whereas for ISPF dialog tools it is best practice to use the MODELESS execution mode.
Table Structure [O] | Element List Structure | Only to be set if a tool returns an element list. The element list is then assigned to the selected element list structure. See Table Structure for more information.
Key Binding Context [O] | Selection | The binding context in which a set key binding sequence is active, see Key Binding for more information. The key binding context is ignored if no key binding sequence has been set. The default value is AWM Team Developer Element Views.
Key Binding Sequence [O] | Key Sequence | The keystroke combination to execute the action, see Key Binding for more information.
Link Element List | Boolean | Only to be set if a tool returns an element list. If set to true, the created element links to the context resource of the action. Ignored if no element list is created. See Linked Element List for more information. The default value is true.
Mass Processing | Boolean | To be set if enabling mass processing for multi selections. If set to true, the action executes only once, even if several elements are selected. Tools of the action must support mass processing to process the whole selection. See Mass Processing Overview for more information. The default value is false.
Related_Save_Action [O] | ActionDescriptor | To be set if dealing with an Edit action. The selected Save action executes when saving the editor.
Related_Close_Action [O] | ActionDescriptor | To be set if dealing with an Edit or Browse action. The selected Close action executes when closing the editor.
Show Progress Monitor | Boolean | Specifies whether to show a progress monitor dialog while the action is executing. The default value is true.
Refresh_List | Boolean | If the action is executed on elements in the Table Results view and this attribute is set to true, the current element list is refreshed at the end of the action by executing the action that was used to create the list. This attribute does not support refreshing element lists in the Application Explorer view. The default value is false.
Icon [O] | Icon | The icon of an action descriptor can be seen in context menus.
Table_View_ID [O] | String | The Team Developer View secondary ID, which shows element lists created by this action. You can overwrite this value with the value set in the element list structure.
Table_View_Label [O] | String | The label that the Table Results view takes when showing element lists created by this action. You can overwrite this value with the value set in the element list structure.
Custom Error Message [O] | String | This attribute enables you to specify an alternative error message to the default error message displayed in the AWM Error dialog box. Note: Specifying a custom error message does not alter the text displayed when you click Details.
Relationship | Cardinality | Description
Has_Tool | 1..* | Relationship to a tool descriptor. The tool sequence for an action arises through these relationships.

Examples

Action Descriptor SCLM_ACT_DeleteLockEntry

Delete Lock Entry
Attribute | Value | Description
Element List Creation | Not relevant as the action does not create an element list.
Essential: |
ID | SCLM_ACT_DeleteLockEntry | Unique identifier of the action in this model.
Key Binding | Not relevant as no short key is defined for the action.
Optional: |
Custom Error Message | No custom error message defined for this action.
Execution Mode | Modal | Actions containing tools of type "Execute ISPF Command" should always be executed in modal mode.
Icon | Reference to the icon SCLM_ICON_ACT_Delete | Icon shown in the context menu in front of the action label.
Label | Delete Lock-Entry... | Label shown in the context menu for the action.
Mass Processing | false | The tools of this action are designed only to delete a single element per call.
Refresh List | false | The element list should not be refreshed after the execution of this action.
Save/Close | Not relevant as the action is not an edit action.

Action Descriptor SCLM_ACT_DeleteMember

Attribute | Value | Description
Element List Creation | Not relevant as the action does not create an element list.
Essential: |
ID | SCLM_ACT_DeleteMember | Unique identifier of the action in this model.
Key Binding | Not relevant as no short key is defined for the action.
Optional: |
Custom Error Message | No custom error message defined for this action.
Execution Mode | Modal | Actions containing tools of type "Execute ISPF Command" should always be executed in modal mode.
Icon | Reference to the icon SCLM_ICON_ACT_Delete | Icon shown in the context menu in front of the action label.
Label | Delete member... | Label shown in the context menu for the action.
Mass Processing | true | The tools of this action are designed to support processing more than one element. The modelled MassProcessing input parameters for all selected elements are passed to the tools of the action all at once. If the tool is of type "Execute ISPF Command" the parameters are passed via the ISPF table TAUTOTIP.
Refresh List | false | The element list should not be refreshed after the execution of this action.
Save/Close | Not relevant as the action is not an edit action.

Action Descriptor SCLM_ACT_FilterMemlist

Filter Member List
Attribute | Value | Description
Element List Creation |
Link Element List | true | The created element list is linked to its parent. This means among others that the element list is deleted when the parent filter is deleted.
Table Structure | Reference to the Element List Structure SCLM_ELIST_Member | The element list structure to be used when the element list generated by a tool of the action is displayed in the Table Results view.
Table View ID | --- | Only relevant if the element list is shown in a secondary view ID.
Table View Label | --- | Only relevant if the element list is shown in a secondary view. In this case, it is the Label of the secondary view.
Essential: |
ID | SCLM_ACT_FilterMemlist | Unique identifier of the action in this model.
Key Binding | Not relevant as no short key is defined for the action.
Optional: |
Custom Error Message | No custom error message defined for this action.
Execution Mode | Modal | Actions containing tools of type "Execute ISPF Command" should be executed in modal mode.
Icon | --- | For this action no icon is defined.
Label | Filter SCLM Members | Label shown in the context menu for the action.
Mass Processing | false | The tools of this action are not designed to support processing more than one element per call. Typically, an action generating an element list does not support mass processing.
Refresh List | false | The action itself produces an element list.
Save/Close | Not relevant as the action is not an edit action.
  • Relationship: Action Has Tool
  • Table Structure
  • Table View ID
  • Linked Element List
  • Mass Processing Overview
  • Related Save-/Close Action
  • Key Binding
Parent topic: Data Model Details
Related information
Global Action
Linked Element List
Mass Processing Overview
Relationship: Application Options have Application Actions
Table Structure
Table View ID
Key Binding


Relationship: Action Has Tool

The relationships of an action descriptor to the tool descriptors form the Tool sequence of an action. A Tool sequence can consist of different tool types. An action can start, for example, with an AWM input dialog, call some tools to process the input data and end with an AWM output dialog. The Tool sequence is interrupted as soon as a tool returns a return code higher than the acceptable return code or the user cancels an input dialog. See Application Options for information on how to define the maximum allowed return code.

Attribute | Type | Description
TargetID * | ToolDescriptor | The tool descriptor that should be referenced via this relationship.
Affected Resource name [O] | String | Must contain a logical name that was returned by a tool-defined resource operation in a previously executed tool of the same action. See Tool-defined Resource Operations for more information. The tool uses the specified resource as its context.
Parameter_Override [O] | Parameter_Override | Relationship to an input parameter of the referenced tool descriptor. This makes adaptations to the input parameters possible for one action, so that the re-usability of tool descriptors is increased. See Parameter Override for more information.
Enabled Condition [O] | Enabled_Condition | Relationship to a tool enabled condition which lets you define the conditions which are checked at run time and must be true to call the tool. See Enabled/Visible Condition for details on how to define an enabled condition.

Examples

Action Has Tool Enabled Condition

The example above shows several "Action Has Tool" relationships with enabled conditions. The enabled conditions are all dependent on the property SCLM_PROP_DIA_RunInBatch which is set as user input by the first tool of the action. Depending on the value of the SCLM_PROP_DIA_RunInBatch property different tools of the action are executed.

Endevor BrowseElement Action

Endevor Browse Tool

This example shows the use of the Parameter_Override relationship in an "Action Has Tool" relationship.

The Endevor model contains a general tool which retrieves the information for several browse actions. One parameter of the tool is the function code which defines which information should be retrieved. This parameter is overwritten by the appropriate static value in each "Action Has Tool" relationship referencing the NDV_TOOL_ISPF_REX_RetrieveElementInfos2Browse tool making use of a "Parameter Override" relationship. In this scenario, the input parameter NDV_PROP_ElementVVLL is removed from the parameters being passed to the tool as it is not relevant to an element browse action. It is only relevant for an element version browse action.

  • Parameter Override
Parent topic: Action Descriptor
Related information
Application Options
Enabled/Visible Condition
Parameter Override
Tool-defined Resource Operations


Parameter Override

With a parameter override, specific attributes of an input parameter can be overwritten or adapted for exactly one action descriptor.

Attribute | Type | Description
Parm To Override * | Tool_Has_InputParameter | The input parameter of the referenced tool descriptor that should be adapted.
New Parm From [C] Selection Overwrites the “Parameter_From” attribute of the input parameter, see Relationship: Tool Has Input Parameter for more information.

Possible values:

  • Context (standard value)
  • Previous_Tool
  • User_Input
New Static Value [C] String

(multi line)

Overwrites the "Static_Value" attribute of the input parameter, see Relationship: Tool Has Input Parameter for more information.
Remove Parm [C] Boolean Ignores these input parameters for this action descriptor. This is only possible if the input parameter is declared as optional, see Relationship: Tool Has Input Parameter for more information.

Default value is false

The Parameter Override attribute mutually exclude each other. Only one attribute can therefore be interpreted. The "New Parm From" attribute, for example, only works if no static parameter ("New Static Value") has been set. Similarly, a parameter can only assume a static value if it should not be ignored ("Remove Parm").

Examples

Remote Edit Save Parameter Override

Check In Parameter Override

The SCLM remote edit save action is an example of a parameter override of one of its tools. The parameter SCLM_PROP_PARM_FunctionCode which has a default value of 0 is overwritten in the Action_Has_Tool relationship to the tool SCLM_TOOL_ISPF_REX_CheckIn by the value 1. This parameter determines whether an element is only uploaded to the mainframe or also checked-in into SCLM. When the tool is used within a SCLM Check-in action the value of 0 is expected that means the element is check-in into SCLM. If it is used in a remote save scenario of the editor, the check-in into SCLM should not be done because the element still stays open in the editor. The check-in into SCLM is only done with the close action of the editor.

Member Filter Parameter Override

Member Name Parameter Override

Hierarchy Parameter Override

The action SCLM_ACT_ShowContainedMembersFiltered is an example for an action with parameter overrides of two of its tools. The result of the overrides is that the corresponding property values are taken from a preceding tool in the action instead of from the context as defined in the Tool _Has_Input_Parameter relationship.

Parent topic: Relationship: Action Has Tool
Related information
Relationship: Tool Has Input Parameter


Table Structure

Actions that generate new element lists will be defined by a reference in an element list structure by an action descriptor. Note that precisely one tool must output one file, in which all the elements for the element list are contained. If several tools of an action return a file descriptor, the last one will be used for element list creation.

Additional string output parameters returned by the tool which creates the element list will be added as element list properties to the list.

The output file must contain as a minimum all values of the key properties (see ID has Key Property) and the match name (see Element type) of the corresponding element type. If the element list should be represented in the form of a tree table, you must return the hierarchical tree structure in the match name by concatenating the match names of the element types which define the tree. The concatenation sign between the match names is the + sign. In this case, the output file must contain all values of all key properties of all element types which are referenced by one of the match names in the match name concatenation.

This means you can’t define an element type match name containing the + sign. If a tool returns a match name containing a + sign in the element type property, the tool result will always be represented in the form of a tree table. Each segment of the concatenated match name separated by the + sign is interpreted as element type match name.

Additionally, output property values can be assigned to the corresponding element and be shown in the table if these properties have also been assigned to the element type. Every line of the output file will be interpreted as a string of property values for an element.

Example tool output

Here is another example for a tool output which is represented in the form of a tree table:

Creation of a tree table Element List
Parent topic: Action Descriptor
Related information
Element Type
ID Has Key Property


Table View ID

An element list created by an action can be shown in a specific table view. In this case, the view label of the Table Results view will be specified either by an action descriptor or by the Element List Structure (see Element list structure). The main purpose of specifying this attribute is to allow element lists to be grouped by the same action or same element list structure and displayed in different views in the IDE. If this attribute is not specified, all element lists created will be shown in the main Table Results view which has the standard label "Table Results view".

Closing a Table Results view does not close the element lists contained within it, and the view can be restored by calling the action "Restore All Team Developer Views". This action is a toolbar icon in the Application Explorer view.

Parent topic: Action Descriptor
Related information
Element List Structure


Linked Element List

An element list created by an action descriptor can be linked to the context resource. The context resource is usually the one that was selected when the action was executed, which is an element list entry or a filter in most cases. The main purpose of creating linked lists is to have access to parent properties.

A linked element list has the following properties:

  • A linked element list has access to parent properties. This applies even before the element list is created, which means that not all properties of an element must be returned by the tool creating the list as long as they are available through parent properties.
  • Linked lists can also have resources with linked lists, creating a hierarchy. The last linked list has access to the properties of the root resource (see the figure below).
  • If the context resource is deleted or refreshed, the linked element list will be removed as well.
  • If the same properties exists multiple times in the hierarchy, the resources within them only have access to the last occurrence.
  • Parent property values can be changed from child resource by resource operations (UPDATE).
A linked element list created from an element list entry.

Since the list contains only the properties “file name” and “create date”, the “folder name” will be obtained from the hierarchy.

Parent topic: Action Descriptor


Mass Processing Overview

Mass processing is the term for processing several elements in a multi selection at once by passing the data of the whole selection to a tool within an action.

Mass processing can be enabled by setting the “Mass Processing” attribute of an action descriptor to true. The action is then executed only once, even if several elements were selected. The tool types of the tool descriptors within the action must also support mass processing in order to handle all selected elements. Tools which do not support mass processing are called once, and can use the main selection context but not the context of single elements within the selection.

The main context is built from:

  • Parent properties.
  • Element list properties.
  • Static properties.
  • The first element of the selection.
  • Tool output parameters.

Example 1: Delete selected elements (non-mass processing):

  • Action descriptor: ACT_DeleteFileSingle (non-mass processing)
    • Tool descriptor: TOOL_UI_ConfirmDelete
    • Tool descriptor: TOOL_DeleteFile

The action is executed for every selected element, which means both the confirm dialog “TOOL_UI_DeleteFile” and the tool “TOOL_DeleteFile”, once per element. Whilst the repetition of the dialog becomes impractical, the execution of the delete action takes more time for larger selections, especially if it is a remote tool.

Example 2: Delete selected elements (mass processing):

  • Action descriptor: ACT_DeleteFileMass (mass processing)
    • Tool descriptor: TOOL_UI_ConfirmDelete
    • Tool descriptor: TOOL_FileDeleteMass

This action is executed once as the mass processing attribute is set, even if multiple elements are selected. After the first dialog tool is confirmed, all the necessary element properties are passed to the “TOOL_FileDeleteMass” tool which deletes all selected elements in a single call. In this case, the tool must support the processing of a group of elements.

Tools within mass processing actions can use tool-defined resource operations to update elements from the views as they process them. See Tool-defined Resource Operations for more information. A delete tool, for example, returns a REMOVE-ELEMENT: <ID properties> resource operation for every deleted element. This information is used by AWM to delete the elements from the UI.

Mass processing does not necessarily require the selection of several elements. It is also possible for tools to create a multi selection context. For example, an input dialog can be modeled as a table selection dialog, which gives you the opportunity to select several rows from a checkbox table. The properties of these rows can be used by subsequent mass processing tools by setting the “Parameter From” attribute of all their mass input parameters to “Previous Tool”.

Parent topic: Action Descriptor
Related information
Input Dialog
Mass Processing in ISPF Tools
Mass processing in an OS command
Tool-defined Resource Operations


Related Save-/Close Action

A variety of edit scenarios can be modeled. Editing can take place locally or remotely. With local editing, all changes are stored locally and are only written back to the remote system when the user explicitly requests this. When editing on the remote system, all changes are written back to the remote system immediately when saving or closing the editor.

An edit action can be extended by a Related_Save_Action and/or Related_Close_Action. The Save action is carried out every time there is a request to save the file. The Close action is carried out when the editor is closed (this also happens when closing Eclipse).

Note: If an output dialog is modeled in a save action, you cannot open the content of the output dialog in the editor after closing the output dialog. The following error message is displayed:
The resource tree is locked for modifications.

Save actions which imply changes to the workspace should be modelled with an execution mode of modeless.

Example

A usual use case for the definition of an edit close action is that certain SCM activities have to be performed when the element is closed in the editor, for example, the element has to be unlocked in the SCM system. The unlock of the SCM system might require a comment specified by the user. In the example described here the comment should not be asked for when the element is not saved since it is opened in the editor. This is the reason why a save action is needed. The save action sets a save flag which is reset when the editor is opened for this element.

This scenario is modelled in the standard AWM ChangeMan model supplied by Micro Focus. Three properties are needed:

The Property CMG_PROP_PARM_SourceChangedN is defined with default value N. The Property CMG_PROP_PARM_SourceChangedY is defined with default value Y. The AWM tool "Return Property Value" can be used to set or reset the CMG_PROP_PARM_SourceChanged by the value of the property CMG_PROP_PARM_SourceChangedN or CMG_PROP_PARM_SourceChangedY, respectively:

Set Edit Save Property

The tool CMG_TOOL_AWM_ResetEditChanged is modeled as the first tool of the edit action. The tool CMG_TOOL_AWM_SetEditChanged is modeled as a tool of the related save action. The tool to ask for the unlock description in the edit close action CMG_TOOL_AWM_UI_ChangeDescription is only executed when the property CMG_PROP_PARM_SourceChanged contains the value Y:

Parent topic: Action Descriptor


Key Binding

Key Binding Sequence Field

The key binding sequence input field in the AWM model editor can capture valid keystroke combinations for easy configuration. Press the desired key sequences while the cursor is in the input field.

As soon as a valid keystroke (combination) has been captured, no further keys are added to the field. To change or unset a key binding, press Backspace.

Pressing the Enter key while in key capturing mode will not exit the input field, like in other fields in the model editor, because Enter can be used as part of keystroke combinations. To exit the input field, press Tab or simply click any other field or object.

For example, setting the key binding sequence Ctrl+Shift+R:

  1. Select the desired action descriptor in the model editor.
  2. Place the cursor in the Key Binding Sequence field in the properties view.
  3. Press and release the key combination.
    Note: The modifiers Ctrl and Shift must be pressed before R. The order in which modifiers (Ctrl, Shift, Alt) are pressed does not matter.
  4. Press Tab or click outside the input field to exit key capturing mode.

Each key binding is defined by a key sequence, a binding context, and an action. Pressing a keystroke combination will execute the corresponding action, if the binding context is active.

Binding contexts must be used to prevent conflicts with other key bindings. Since there are many existing key bindings in Enterprise Developer, a lot of actions share the same key sequence, for example Find/Replace (Ctrl+F) or Delete (Delete). Most of the time, key bindings are connected to UI components like views or dialogs. These components define their own binding context, which is only active if the specific view or dialog is focused.

AWM defines its own set of binding contexts:

  • AWM Views

    All AWM views

    • AWM Team Developer Element View

      All AWM views displaying modeled elements

      • AWM Team Developer Table View
      • AWM TeamDeveloper Tree View

Binding contexts can have a parent/child hierarchy, meaning that each context can contain other contexts or vice versa. All AWM binding contexts are contained in the standard Eclipse binding context In Windows, which is always active. Click Window > Preferences > General > Keys to see a list of active bindings.

Examples:

  • Setting the binding context AWM Team Developer Element Views will activate a key binding both for the Application Explorer view and the Table Results view.
  • Setting the binding context AWM Team Developer Tree View will activate a key binding only for the Application Explorer view.

If an action descriptor is used in a global faction (see Global Action for more information) and a key binding is desired, you should set the binding context to, for example, In Windows, so that the action can be executed by a keystroke combination when no AWM Views are focused.

Binding conflicts

If more than one key sequence is configured and active due to the same binding context, a key binding conflict will occur. This can be intentional, a selection dialog pops up automatically at the bottom right of the screen, in which the desired action can be chosen manually, see the image below:

Due to the way Eclipse handles key bindings, there can be situations where a binding conflict cause certain actions not to be executable via keystrokes. The reason is that Eclipse always prioritizes actions with non-conflicting bindings.

Example:

Three actions are bound to the key “Delete”.

  1. “Delete” standard Eclipse action.
    • Context: “In Windows"
  2. “Delete File” AWM action.
    • Context: “AWM Team Developer Element Views"
  3. “Delete Folder” AWM action.
    • Context: “AWM Team Developer Element Views"

Because actions 2 and 3 share the same context, they cause a binding conflict. If a user pressed “Delete” on an AWM file element, Eclipse would only try to execute action 1, it prioritizes the non-conflicting action above the conflicting ones.

A workaround is to merge the tools for both AWM actions into a single action. This will eliminate the conflict and cause the AWM action to be prioritized in AWM views, since they have more specific binding contexts. If necessary, tool enabled conditions can be used to only execute tools applicable for the selected element.

User Customization

AWM does not currently support user customization of modeled key bindings. You can view and temporarily change modeled bindings by using the “Keys” preference page (Window > Preferences>General > Keys). Loading an AWM model, (for example, by restarting Enterprise Developer or switching between two AWM applications) will always set modeled key bindings and overwrite any custom key binding changes for affected actions.

Parent topic: Action Descriptor
Related information
Global Action


Application Options

Global settings that apply to the complete application can be defined under the application options.

One attribute of the application options is Version. At run time, the version of the local AWM model is compared with the version entry in the Master Configuration file. See Master Configuration for more information.

The attributes Start Reference and End Reference are used for parsing variable references. See Variable References for more information. By default these have the values “&” and “.”.

In addition, the tool execution can be controlled from the application options. The maximum return code that the tool can return without its execution being interpreted as “failed” is specified in the attribute MaxRC. Failed tools end with an error message, and prevent the execution of further tools in the tool sequence of the action.

The Root Containers Action attribute can be used to refer to an action which returns the root elements used to build up the first hierarchical view of the application which are visible in the Tree view. The referenced action descriptor must return an element list whose match name property typically references a container element type. See Table Structure for more information.

Attribute | Type | Description
Cache Elements Boolean Specifies whether AWM elements, elements lists, and column configurations for element lists are cached during application unloading. An application is unloaded when another application is loaded or when the Eclipse workbench is closed.

Default value: True

Default_Generic_Symbol String The standard wildcard character usually used to match all elements. Generic input fields are automatically filled in with this symbol.

Default value: *

End_Reference [D] String Symbol or character string that should be interpreted as meaning the end of a reference, see above.

Default value: .

Generic_Symbols [O] String Specifies the wildcard characters for a generic search. The characters given here are used to validate generic input fields in dialogs.

The characters can be added via a dialog box opened when you click ....

The characters entered here may depend on the integrated application system. To search files in ISPF, these characters are "*" and "%".

Example: *,%

Independent Affected Resource Contexts Boolean Specifies if the affected resource contexts should be independent from the main context. See Tool-defined Resource Operations for more information.

Default values:

  • true
  • false - for AWM models before ED/VC 3.0
Max_RC * Integer Specifies the maximum permitted return code of a tool that is called from the model interpreter.

The tool execution is interpreted as being faulty if this value is exceeded.

Model ID | String | ID of the model; for internal use only.
Root Containers Action [O] | Action Descriptor | The selected action is executed when the application entry in the tree view is expanded by the user in order to retrieve container elements of the first hierarchy level.
Start_Reference [D] String Symbol or character string that should be interpreted as meaning the start of a reference.

Default value: &

Version * | String (for example, 1.2.1) | Version of the AWM model
Relationship | Cardinality | Description
Has_Application_Action | 0..* | Relationship to an action which is assigned to the application
Has_Application_Property | 0..* | Relationship to a property with application-wide scope
Has_Specific_Attribute | 0..4 | Relationship to a specific attribute.

Examples

Application Options Properties

The application options of the SCLM model have a reference to the application specific attribute SYSLIB. This is used in the Micro Focus COBOL and PL/I editor to find and download COBOL copybooks or PL/I includes in a z/OS remote edit scenario. In this model the value of the application specific property SYSLIB is a reference to a AWM model property. This allows allocating the SYSLIB concatenation dynamically. The SYSLIB concatenation is returned by an ISPF tool which is called in a remote edit action just before the edit tool is called.

Attribute | Value | Description
Container View: |
Root Containers Action | SCLM_ACT_CreateRootentries | Reference to the SCLM action which returns the SCLM projects.
Generic Symbols |
Default Generic Symbol | * | Asterisk is used as default generic symbol in the SCLM application.
Generic Symbols | *,% | Asterisk and % are interpreted as generic symbols in the SCLM application.
Referencing: |
End Reference | . | Dot is used to terminate a property reference in the SCLM application.
Start Reference | & | & is used to start a property reference in the SCLM application.
TAURUS Model: |
Model ID | TAURUS_Model | For internal use only; should not be changed.
Version | 2.3.1 | Version number of this instance of the SCLM application. By changing the version number the AWM model administrator can trigger the local copy of the SCLM application to be replaced by the new instance from the location specified in the master configuration file.
Tool execution: |
Max RC | 4 | If any tool of the SCLM application returns with an RC higher than 4, the tool execution is interpreted as failed and the whole action is terminated with an error message. Subsequent tools in the action are not executed.
  • Relationship: Application Options Have Custom Attributes
  • Relationship: Application Options have Application Actions
  • Relationship: Application Options have Application Properties
Parent topic: Data Model Details
Related reference
Application Options
Related information
ISPF Exits
Master Configuration
Table Structure
Table View ID
Variable References


Relationship: Application Options Have Custom Attributes

The relationship Has_Specific_Attribute has the following attributes:

Attribute | Type | Description
Name * | String | Attribute name.
Value | String | Attribute value.

This relationship is provided to overwrite software specific attribute values with customer specific values.

The following specific attribute names are supported:

Attribute name | Description
Dialog_Ok_Label | The label of the OK button in all modeled dialogs except ISPF dialog boxes.
Dialog_Cancel_Label | The label of the Cancel button in all modeled dialogs except ISPF dialog boxes.
ISPF_Ok_Label | The label of the OK button in modeled ISPF dialog boxes.
ISPF_Cancel_Label | The label of the Cancel button in modeled ISPF dialog boxes.
COMPOPT A list of Micro Focus compiler directives to use when background parsing a COBOL or PL/I program opened in theMicro Focus editor. This attribute is only supported in a z/OS remote edit scenario. Below you can find more information on how to use this attribute.

It is possible to use variable names as part of the COMPOPT attribute. See Variable References for more information.

Default value for COBOL: "DIALECT(ENTCOBOL) CICSECM XDB(NOVALIDATE) EXECDLI NOP64"

Default value for PL/I: "-margins 1,72 -cics"

AUTO_PARSE Controls whether the background parse process of the Micro Focus editor is started automatically or only if explicitly called. This attribute is only supported in a z/OS remote edit scenario. Below you can find more information on how to use this attribute.

It is possible to use a variable name to define the AUTO_PARSE attribute. See Variable References for more information.

Default value: true

INITIAL_PARSE

Controls whether the background parse process of the Micro Focus editor is started when a file is opened in the editor. The attribute is only of relevance when the attribute AUTO_PARSE is defined and set to true.

This attribute is only supported in a z/OS remote edit scenario. Below you can find more information on how to use this attribute.

It is possible to use a variable name to define the INITIAL_PARSE attribute. See Variable References for more information.

DIALOG_RETRIEVE_LABEL | The label of the Retrieve button in modeled dialog boxes.

To receive a correct result from the background parser it is important to specify the correct compiler options.

Use the COMPOPT attribute to specify the compiler options.

Normally, you can use variable names to specify the SYSLIB attribute and the AWM model ensures that the variables are correctly resolved at run time.

If the specific attribute COMPOPT is not defined in the AWM model, the following rules apply for COBOL:

  • If a property with the identifier MFProp_RemoteSyntaxCheckOptions is defined in the AWM model, its value is used.
  • If this property has a specific value at run time, it is used. Otherwise, the default value is used, which is "DIALECT(ENTCOBOL) CICSECM XDB(NOVALIDATE) EXECDLI".

If this specific COMPOPT attribute is not defined in the AWM model the following rules apply for PL/I:

  • If a property with the identifier MFProp_RemotePLISyntaxCheckOptions is defined in the AWM model, its value is used.
  • If this property has a specific value at run time, it is used. Otherwise, the default value is used, which is "-margins 1,72 -cics".
Note: The usage of the properties MFProp_RemoteSyntaxCheckOptions and MFProp_RemotePLISyntaxCheckOptions is deprecated but still supported for compatibility reasons.

By default, background parsing for COBOL and PL/I is done automatically during an edit session. If you have defined a compiler option which includes a mainframe precompiler call (this is currently only supported for COBOL) you may want to decide when to execute a full parse of the edited source.

To do this, specify the value false in the AUTO_PARSE attribute.

Normally, you use a variable name to specify the AUTO_PARSE attribute and the AWM model must make sure that this variable is correctly resolved at run time. It is best practice to use the value false only if the COMPOPT attribute contains an option to invoke a mainframe precompiler. If you want the background parse process to start when a file is opened in the editor, you have to specify the application specific attribute INITIAL_PARSE and set it to true.

Parent topic: Application Options
Related information
Variable References


Relationship: Application Options have Application Actions

Using the Application Options have Application Actions relationship, an AWM application can be assigned actions which are executed on the application level. Action descriptors referenced using this relationship appear either in the context menu of the application entry or are executed automatically on specific conditions. Actions can be hidden or deactivated on certain conditions. An action Visible or Enabled condition determines when an action should be visible and activated. See Enabled/Visible Condition for more information.

Attribute | Type | Description
TargetID * | ActionDescriptor | The reference to the action descriptor.
ActionVisibleCondition | ActionVisibleCondition | This complex attribute lets you define rules for when the action should be visible in the context menu of the application.
ActionEnabledCondition | ActionEnabledCondition | This complex attribute lets you define rules for when the action is activated. Non-activated actions are disabled, and cannot be executed by the user.
Default_Action [U] Boolean Defines whether this action should be carried out by a double-click on the application entry. Only one application action can be declared as the Default_Action.

The default value is false.

Label [O] | String | Labeling of the action in the context menu. If no label is stated, the label of the referenced action descriptor is used.
Separator_After Boolean Determines whether to insert a separation line behind the context menu entry.

The default value is false.

Execution Type * Selection Determines when to execute the action.

Valid values are:

Manual
The action appears in the context menu of the application entry.
OnLoad
The action is executed when the AWM model is loaded. This can be when the application is loaded manually or automatically when starting Eclipse.
OnFirstLoad
The action is executed when the AWM model is loaded but only once during an Eclipse session.
OnUnload
The action is executed when the AWM model is unloaded. This can be when another application is loaded manually or automatically when closing Eclipse.
Note: Manual is the default value.
Skip model update check | Boolean | Determines whether a model update check should be executed if the action is executed. This is only relevant for actions which are executed when loading the model.

Example

Application actions of execution type Manual can be actions to create a new object. Another sample can be an action to display and change application specific options.

Application actions of execution type OnLoad or OnFirstLoad can be actions to initialize the connection to a remote application system, for example, a remote database system. In this case, the execution type depends on the point in time when the connection is shut down (with the unload of the application loading another application or only when closing the Eclipse session).

Application actions of execution type OnUnload could be actions to shutdown the connection to a remote application system, for example, a remote database system.

Parent topic: Application Options
Related information
Enabled/Visible Condition


Relationship: Application Options have Application Properties

The Application Options have Application Properties relationship enables you to assign properties to applications. Properties which are assigned to an application have an application-wide scope, this means they can be accessed within any execution context.

The default value for an Application Property is the value set under Default Value of the target property. If the Property is also defined as a Static Property in the Master Configuration file, the value defined in the Master Configuration is used as the default value for the Application Property and overrides the Default Value set in the target Property.

The value of an Application Property can be reset to its default value by checking the Application Properties option in the Clear Cache dialog box. The Clear Cache dialog box is available as a context menu action of the currently active application.

Attribute | Type | Description
Constant Boolean Specifies whether the Application Property is an invariable value:
True
The value of the application property cannot be changed.
False
The value of the application property can be modified by the execution of a tool with Resource Processing Update.
Target ID | Property | The reference to the property.
Mandatory Boolean Specifies whether the application property is required so that the application can be executed:
True
A default value is required when loading the application. This value can either be retrieved from Static Properties of the Master Configuration or from the Default Value of the target Property.
False
A value is not required when loading the application.

Example

A modifiable application property could be used in a dialog box containing a Remember my decision check box. If the option is checked, the property value can be stored within application properties and the dialog would not be displayed the next time the action is executed.

Parent topic: Application Options


Element List Structure

An element list structure describes a table structure for the table view or a tree table view. This is the definition of columns, in which the property values of elements can be displayed at run time. See Relationship: Element Has Property for more information.

Attribute | Type | Description
ID * | ID * | The ID of the element list structure.
Label [O] | String | The display name of the element list structure. Display names only appear in the Column Configuring dialog box. If no label is stated, the ID is used.
Table_View_ID [O] | String | The Team Developer view secondary ID in which element lists with this structure are shown. See Table View ID for more information.
Table_View_Label [O] | String | The label that the Table Results view takes when showing element lists with this structure.
Relationship | Cardinality | Description
Has_Column | 1..* | Relationship to properties that describes a table column of the element list structure. It is possible to define table columns that consist of multiple properties.
Has_Action | 0..* | Relationship to an action descriptor that has an effect on any element in the list.

Examples

The element list structure SCLM_ELIST_Member is used to display SCLM members in the Table Results view. The relationship Has_Column defines which SCLM member attributes should be shown in the Table Results view. There is one action which is associated with the element list structure itself. This is the action to create a new SCLM element. This action is also available when the table is empty.

Attribute | Value | Description
Essential: |
ID | SCLM_ELIST_Member | Unique identifier of the element list structure in this model
Optional: |
Label | Memberlist Structure | Display name used in the description of the Column Configuring dialog.
Table View ID | --- | As the table view ID is empty the default Table Results view is used to display the element list.
Table View Label | --- | Not needed as the element list is not displayed within a table view.
  • Relationship: Element List Has Action
  • Relationship: Element List Has Column
Parent topic: Data Model Details
Related information
Relationship: Element Has Property
Table View ID


Relationship: Element List Has Action

Use the Element List has Action relationship to define element list actions. Element list actions can appear in the context menu of the element list, but are defined independently of the element types. This lets you define actions that:

  • Can be used on all the elements of an element list.
  • Activate only if no elements have been selected in the list.
  • Can always be carried out.

This is dependent on the Selection Count attribute of the action Enabled or Visible condition. If no action Enabled or Visible condition is defined, the action can always be carried out. See Enabled/Visible Condition for more information.

Examples of element list actions include:

  • Opening an Element (all Element Types) in the Browse mode (Selection Count = 1).
  • Inserting an Element into an empty element list (Selection Count = 0).
Attribute | Type | Description
TargetID * | Action Descriptor | The action descriptor that should be referenced by means of this relationship.
ActionVisibleCondition [O] | ActionVisibleCondition | This complex attribute enables you to define the rules when the action should be shown in the context menu of the element list.
ActionEnabledCondition [O] | ActionEnabledCondition | This complex attribute enables you to specify rules to conditionally activate the action. Non-activated actions are disabled and can not be executed.
Label [O] | String | The display text or the tooltip for the action.
Show In Context Menu [O] | Boolean | Determines whether the action is shown in the context menu of the element list entries.
Show In Tool Bar [O] | Boolean | Determines whether the action is shown in the tool bar of the element list. This feature is currently not supported, but is for future use.

Example

Element List Has Action Relation

Element List Has Action
Attribute | Value | Description
Essential: |
Target ID | Reference to the action SCLM_ACT_InsertSCLMMember | The element list action points to the action SCLM_ACT_InsertSCLMMember to create and insert a new SCLM member. An insert member action is a typical element list action as it does not require the selection of an existing member.
Optional: |
Label | New SCLM Member... | The label to be used for this action when shown as an action of an element list. This value overrides the label defined in the action itself.
Show In Context Menu | true | The action's label is shown in the context menu of every element of this element list.
Show In Toolbar | false | The action's label is not shown in the toolbar of this element list.
Parent topic: Element List Structure
Related information
Enabled/Visible Condition


Relationship: Element List Has Column

You can define element list structure columns in the Element List has Column relationship. Any of the element's property values matching table column's properties display in the table. The modeled structure of the column definition (position, visibility) is only a user default. Columns can be individually interchanged, displayed or hidden using a Column Modeling dialog box.

As a rule, most properties referenced here are also assigned to the element, so they are also properties for the affected element types.

Properties that are only relevant in the context of the element list can also be referenced. They cannot be directly assigned to an element type, as:

  • The property does not logically match the element type.
  • The property values can differ for the same element in different lists.
Attribute | Type | Description
TargetID * | Property | References to properties. The property values are displayed in the column of the element list at run time. You can combine several property values within one table column. Click in the Target ID value field, a ... button is displayed. Click ... to open a dialog displaying a list of all the properties that can be selected.
Label [O] | String | Display name and/or column title for the table column. If no label is stated, the first referenced property's label is used.
Visible [O] | Boolean | Indicates whether the table column is displayed. Columns can be displayed or hidden by the user. The default value is true.
Width [O] | Integer | The column width in the table view in pixels.
Delimiter [O] | String | Specifies the delimiter between property values in a table column if more than one property is modeled for the column.

Example

Element List Has Column Relation

Element List Has Column
Attribute | Value | Description
Essential: |
Target ID | reference to the property SCLM_PROP_ELE_Proj | The content of the column is the value returned under the property SCLM_PROP_ELE_Proj (the SCLM project name).
Optional: |
Label | Project | The column's header is 'Project'.
Visible | true | The column is visible by default.
Width | 85 | The column's width is 85 pixels.

Element List Has Column
Attribute | Value | Description
Essential: |
Target ID | reference to the property SCLM_PROP_LIST_ElementType | The content of the column is the value returned under the property SCLM_PROP_LIST_ElementType (the element type property of the SCLM model).
Optional: |
Label | Element Type | The column's header is 'Element Type'.
Visible | false | The column is not visible by default. The user can make the column visible by the Table Results view's 'Configure columns' dialog.
Width | 85 | The column's width is 85 pixels.
Parent topic: Element List Structure


Element Type

An element type describes a class of elements, including their properties and applicable actions.

Every element must belong to an element type at run time. You assign it via the Match Name. In addition, each element type has a match name attribute, under which a unique name for the type must be defined. A tool that creates a new element must return this name under a designated property.

You can configure element types hierarchically so that they can be displayed in a Tree view. This is done using the Get Children Action relationship.

Depending on function packages installed and used in an AWM model, it is possible to create a linked element type. See Linked Element Types for the Eclipse Function Package for more information.

Attribute | Type | Description
ID * | ID * | The ID of the element type.
Icon [O] | Icon | The icon of the element type.
Matchname * | String | The name by which the element type can be determined.
ID_Definition * | ID Definition | The ID definition of the element type. This definition describes the properties of the element type that uniquely identify an element within an application. See ID definition for more information.
Relationship | Cardinality | Description
Get_Children_Action | 0..1 | Relationship to an action descriptor. The referenced action should return the children elements. If you expand an element in the Tree view, this action displays the next hierarchical level of elements.
Get_All_Properties_Action | 0..1 | Relationship to an action that returns all the property values of an element. See Get All Properties Action for more information.
Has_Action | 0..* | Relationship to an action descriptor. Element-Actions can be executed from the context menu of the corresponding element.
Has_Property | 1..* | Relationship to a property that stands for an attribute of the element.
Has_Filter | 0..* | Relationship to a filter type. A Filter dialog box can be executed from the context menu of the corresponding element.
Has_Text_Decoration | 0..* | Relationship which describes decorations in front or behind of the label of the element type.

Examples

Element Type SCLM_ELE_Project

Attribute | Value | Description
Essential: |
ID | SCLM_ELE_Project | Unique identifier of the element type in this model.
ID Definition | Reference to the ID Definition SCLM_ID_Project | The ID definition consists of a set of properties by which a SCLM project can be uniquely identified during runtime.
Matchname | PROJ | The value tools have to return in the Element_Type property to identify a SCLM project instance.
Optional: |
Icon | Refrence to the Icon SCLM_ICON_ELE_Project | Icon shown in the context menu in front of the element type label.

Element Type SCLM_ELE_Editable

Attribute | Value | Description
Essential: |
ID | SCLM_ELE_Editable | Unique identifier of the element type in this model.
ID Definition | Reference to the ID Definition SCLM_ID_SclmElements | The ID definition consists of a set of properties by which a SCLM element can be uniquely identified during runtime.
Matchname | EDITABLE | The value tools have to return in the Element_Type property to identify an editable SCLM element instance.
Optional: |
Icon | Refrence to the Icon SCLM_ICON_ELE_Editable | Icon shown in the context menu in front of the element type label.

Within the SCLM application model the same ID definition (SCLM_ELE_Editable) is shared by several element types:

  • SCLM_ELE_Editable

  • SCLM_ELE_LockEntry

  • SCLM_ELE_NonEditable

The mapping to the appropriate element type depends on the match name value returned by a tool providing new elements within the special Element_Type property. This means a tool returning new AWM elements must always return values for all key properties of the element as defined in the ID definition and the match name value defined in the attribute Matchname within the special Element_Type property.

The Element_Type property must not necessarily be a property which is associated with the element type via an Element Type_Has_Property relationship. It is sufficient to define just one special Element_Type property in an AWM model which is used by every tool returning a match name.

  • Relationship: Get All Properties Action
  • Relationship: Element Has Get Children Action
  • Relationship: Element Has Action
  • Relationship: Element Has Filter
  • Relationship: Element Has Property
  • Relationship: Element Has Text Decoration
  • Relationship: Text Decoration Has Decoration Value
Parent topic: Data Model Details
Related information
Relationship: Get All Properties Action
ID Definition
Linked Element Type


Relationship: Get All Properties Action

The Get All Properties action is a special action of an element type that returns all properties of a specific element or list of elements. Use it to ensure that all required element properties are available before any other action executes on the element.

The main purpose of this action is to improve performance when working with element lists. It often requires one service to receive a list of elements with a few basic properties, and a second service to retrieve all properties of a specific element. Using both services in a single “Get Element List” action would often cause an immense I/O overhead. For this reason a Get All Properties action can be modelled which executes automatically at a specified point of time before any other action can be executed on an element. The time of execution and the execution rate of the Get All Properties action can be set by the attributes of the Get All Properties action relationship of an element type.

By default, the Get All Properties action is available in the context menu of an element under the label Refresh. The Get All Properties Action is not available in the context menu of an action if the Execution Point is modeled as Before Context Menu and the Execution Rate is modeled as Always. In this case, the action is implicitly called every time the context menu is opened.

It is possible to subsequently execute the Get All Properties action manually from the element’s context menu.

To update the element’s properties, the action contains at least one tool with UPDATE or TOOL-DEFINED resource processing. See Tool-defined Resource Operations for more information.

Attribute | Type | Description
Execution Point * Selection Specifies at which point of time the Get All Properties action should be executed. If Before Context Menu is selected, the Get All Properties action is executed before the context menu is opened. If an action is executed without opening the context menu (Default Action / Get Children Action / Key Binding) the Get All Properties action is also executed. If Before Action is selected, the Get All Properties action is executed before the execution of an action.

Valid values:

  • BeforeAction (Default)
  • BeforeContextMenu
Execution Rate * Selection Specifies how frequently the Get All Properties action is to be executed. If Once is selected then the Get All Properties action executes only once at the specified Execution Point. If Always is selected then the Get All Properties action executes every time the specified Execution Point is reached.

Valid values:

  • Always
  • Once (Default)
Target ID * | ActionDescriptor | The reference to the action descriptor.
Enabled Condition | Enabled Condition | This complex attribute allows you to define rules specifying the conditions in which the Get All Properties action is activated. Non-activated actions are disabled, that is they cannot be executed by the user.

If you allow multi-selections in the model, it is recommended you support mass processing for the Get All Properties action. If executed automatically, the Workflow Manager only adds elements to the mass processing context that require updates to their properties. See Mass Processing Overview for more information.

Note: When designing a custom tool to return all properties of a specific element type, it is not enough to only return “missing” properties of the element (properties which were not returned when the element list was generated). This is not recommended, since the “Get All Properties” action can not be used to refresh elements in this case. As the name suggests, “Get All Properties” actions should always return all available properties for the corresponding element type.
Parent topic: Element Type
Related information
Mass Processing Overview
Tool-defined Resource Operations


Relationship: Element Has Get Children Action

Under the relationship "Element Has Get Children Action" an action descriptor can be modeled which returns the children elements of the selected element. If you expand an element in the Tree view, this action displays the next hierarchical level of elements.

The relationship "Element Has Get Children Action" can be provided with an enabled condition. The enabled condition determines whether the element will get an expanded arrow when shown in the Application Explorer view. The enabled condition should test if a "Has Children" property has the string value "true". As standard this "Has Children" property will be a linked property of a function package. The implementation of the linked "Has Children" property has to return for all linked element types provided by the function package whether an element of this element type has children or not.

For linked element types of the Eclipse function package the linked property "Has Children" should be used as property to test the existence of children. This linked property must be defined in the model as a property. The Resource Identifier of this property must reference the property identifying an Eclipse resource. The property must be defined as element type property of the element type for which the relationship "Element Has Get Children Action" is defined.

Attribute | Type | Description
TargetID * | ActionDescriptor | The reference to the action descriptor.
ActionEnabledCondition | EnabledCondition | This condition should point to a property which determines if the selected element has children or not.
Parent topic: Element Type


Relationship: Element Has Action

Using the element has action relationship, an element type can be assigned actions that can be executed on elements of this type. Action descriptors referenced using this relationship appear in the context menu of all elements of this element type, but could also be deactivated there. An action Enabled or Visible condition determines when an action should be shown or activated. See Enabled/Visible Condition for more information.

Note: You should not create more than one relationship to the same action descriptor from an element type. Doing so results in a validation error and unexpected behavior at runtime.
Attribute | Type | Description
TargetID * | ActionDescriptor | The reference to the action descriptor.
ActionVisibleCondition | ActionVisibleCondition | This complex attribute lets you define the rules for when an action should be shown in the context menu of an element.
ActionEnabledCondition | ActionEnabledCondition | This complex attribute lets you define rules to specify when the action is activated. Non-activated actions are disabled, and cannot be executed by the user.
Default_Action [U] | Boolean | Defines whether this action should be carried out by a double-click on the element or by pressing the enter key when an element is selected. In the Application Explorer view the element type “Get Children” action is executed if it exists and if no default action is configured. In the case of a multiple selection, the default action is executed for each selection. Mass processing is not supported. If more than one action of an element type is set as “default action”, the first applicable action depending on the enabling conditions is executed. The default value is false.
Label [O] | String | Labeling of the action in the context menu. If no label is stated, the label of the referenced action descriptor is used.
Separator_After | Boolean | Determines whether to insert a separation line behind the context menu entry. The default value is false.
Show_In_Table_View | Boolean | Determines whether the referenced action should display in the Table Results view context menu.
Show_In_Tree_View | Boolean | Determines whether the referenced action should be displayed in the Application Explorer view context menu.

Examples

SCLM Action Check Out

SCLM Action Check Out Properties
Attribute | Value | Description
Essential: |
Taget ID | Reference to the action SCLM_ACT_CheckOut | This context menu action references the SCLM check out action.
Optional: |
Default Action | false | Specifies that this is not the default action of an element of element type SCLM_ELE_Editable.
Label | Check-Out | "Check-Out" is shown in the context menu of an element of element type SCLM_ELE_Editable for this action.
Separator After | false | There is no separator in the context menu after this action's label.
Show In Table View | true | This action's label is shown in the context menu of the Table Results view when an element of element type SCLM_ELE_Editable is selected.
Show In Tree View | true | This action's label is shown in the context menu of the Application Explorer view when an element of element type SCLM_ELE_Editable is selected.

The relationship between the element type SCLM_ELE_Editable and the action SCLM_ACT_CHECKOUT has a complex Enabled condition defining that the action is only enabled in the context menu when there is not already a SCLM access key on the selected element and the selected element is a SCLM source element, this means it is not read-only.

Parent topic: Element Type
Related information
Enabled/Visible Condition


Relationship: Element Has Filter

You can create an element filter from the context menu using the relationships of an element type to the filter type. The Filter dialog box modeled in the filter type is automatically opened. This pre-assigns appropriate input fields of the filter criteria with the element's property values.

Attribute | Type | Description
TargetID * | FilterType | The filter type that should be referenced using this relationship. A Filter dialog box of this type is opened when you create a filter via the referenced element type.
Label [O] | String | Label in the context menu for creating a new filter.
Show_In_Table_View | Boolean | Determines whether the Create Filter action should display in the Table Results view context menu.
Show_In_Tree_View | Boolean | Determines whether the Create Filter action should display in the Application Explorer view context menu.

Example

In the standard SCLM model, an element filter is defined for the element type "SCLM Type". It is the filter type SCLM_FIL_Member which is also used as a stand-alone filter type.

When used from the context menu in the Application Explorer view the filter dialog is populated with the properties available from the context.

Parent topic: Element Type


Relationship: Element Has Property

Use the Element has Property relationship to reference the properties of an element type.

Element properties can be seen both in the columns of the Element Table view and in the Properties view when an element has been selected, as shown in the figure below. They are also essential for implementing actions on elements, as they can be used as parameters for tools. See Special Properties for more information.

Figure 1. Properties view
Element Properties in the Properties View
Attribute | Type | Description
TargetID * | Property | References the property.
PropertyVisibleCondition | PropertyVisibleCondition | This complex attribute lets you define rules to specify when the element's property should be displayed in the Eclipse Property view.
Category [O] | String | The category under which the property displays in the Properties view.
Element Name [U] | Boolean | Determines whether the property's value contains the element name. Among other things, the element name is used as the editor title.
Label [O] | String | Labels the property in the Properties view. If no label is stated, the property name is used.
Sort_Direction

[O][Tree View]

Selection Sorts the elements of this type according to the referenced property.

Valid values include:

  • NONE
  • Ascending
  • Descending

The default value is NONE.

TreeView_Label

[O][Tree View]

Boolean Determines whether the property's value should be used as the element label in the Tree view.

At least one relationship of the element type should have this attribute set to true. If more labels are modeled, their values are concatenated and separated by a dash (-).

Consider using Text Decorations instead of several Tree view label properties for an element type.

Some linked element types allow the tree view label to be automatically set. See Linked Element Type for more information.

The default value is false.

Example

Element Has Property Relation

SCLM Proj Property
Attribute | Value | Description
Essential: |
Target ID | Reference to the property SCLM_PROP_ELE_Proj | This property is available in the context of an element of this element type. The value of the property is shown in the Property view when an element of this element type is selected.
Optional: |
Category | --- | No special category is defined; the property is shown under the default category "Element" in the Property view.
Element Name | false | This is not the property defining the element name of this element type.
Label | --- | No special label for the relationship is defined. The label specified in the property is used in the UI.
Tree View: |
Sort Direction | Ascending | This attribute is only relevant for attributes which are defined as Tree view labels. The entries of this element type are sorted in ascending order according to the values in this property.
Tree View Label | true | This property is part of the Tree view label for elements of this element type.
Parent topic: Element Type
Related information
Special Properties


Relationship: Element Has Text Decoration

This relationship can be used to define decorations which should appear in front and/or behind the label defined for the element type.

It is possible to define several text decorations for an element type. Within the relationship, the following attributes can be specified:

  • Position of the decorator.
  • Leading and trailing characters for the decorator.
  • Separator if more than one decorator is used.

A text decoration can reference an arbitrary count of properties or static values. It is possible to provide enabled conditions for the referenced properties or static values, for example, to tell which static value should be shown in the decoration if the respective boolean property has the value true or false.

Note: Some Linked Element Types enable the label decoration to be automatically determined. This functionality is only applied if no Element Has Text Decoration is modeled.
Attribute | Type | Description
Text Decoration Position * | Selection | Valid values are: "Behind the Label" or "In Front of the Label" Defines whether the text decoration should be placed behind or in front of the label. Default: "Behind the Label"
Start Character [O] | String | Defines fixed character(s) with which the text decoration starts. Default: " ("
End Character [O] | String | Defines fixed character(s) with which the text decoration ends. Default: ")"
Separator [O] | String | Defines the separator between decoration values if more than one decoration value is modeled. Default : " - "
Relationship | Cardinality | Description
Text Decoration_Has_Decoration Value | 0..* | Relationship from a text decoration to a static value or a property

Example

The following text decoration is defined in the standard SCLM model for SCLM elements in the Application Explorer view.

SCLM Element Text Decoration

Element Has Text Decoration

The following figure illustrates how the text decoration is represented in the Application Explorer view:

Parent topic: Element Type


Relationship: Text Decoration Has Decoration Value

The relationship Text_Decoration_Has_Decoration_Values enables you to associate property values and/or static values with a text decoration of an element type's label. It is possible to provide visible conditions for the referenced properties or static values. For example, to tell which static value should be shown in the decoration if the respective boolean property has the value true or false.

If both static value and property ID are specified, static value and property value are concatenated into the text decoration in this sequence.

Attribute | Type | Description
Static Value [O] | String | Static value to be shown in the text decoration.
Target ID [O] | Property | Reference to a property whose value should be shown in the text decoration.
ValueVisibleCondition [O] | ValueVisibleCondition | This complex attribute enables you to define rules when a static value or property value should be used.

Example

Text Decoration Has Value
Attribute | Value | Description
Optional: |
Static Value | --- | Empty as a target ID property is defined as decoration value. A single decoration value can either consist of a static value or point to a property.
Target ID | Reference to the property SCLM_PROP_ELE_Group | The value of the SCLM group is displayed at the first position of this text decoration.
Parent topic: Element Type


Enabled/Visible Condition

Enabled/Visible Conditions are two model classes by which relationships can be linked to element types, actions, properties, tools or dialog input fields. These conditions determine when the execution of an action or tool is permitted or when an input dialog field is editable, grayed out, hidden or when a property is visible in the Eclipse Property view.

When modeling an enabled condition for an Action_Has_Tool relationship, the administrator defines the permitted values for certain properties, so that the action can be executed. By doing this, simple and complex rules can be defined, where complex rules link the simple rules via operators.

Simple enabled condition example:

  • If Property “Suffix” has the value "cbl", the action can be executed.

A complex enabled condition contains any number of simple and complex enabled conditions, and links these via operators.

The visible condition defines whether an action, property or dialog input field is shown in the corresponding view, context menu or dialog. You can specify simple and complex rules for the condition in the same way as for enabled conditions.

The following table shows the relationships which enabled or a visible conditions can be defined:

Relationship | Enabled Condition | Visible Condition
Application Options has Application Action | Yes | Yes
Global Action has Workbench Action | Yes | Yes
Global Action has Editor Action | Yes | Yes
Element has GetChildren Action | Yes | No
Element has Action | Yes | Yes
Element has Property | No | Yes
Element List Structure has Action | Yes | Yes
File Descriptor has Action | Yes | Yes
Action has Tool | Yes | No
Tool has Input Parameter | Yes | Yes (modeled dialog)
Text Decoration has Decoration Value | No | Yes
In addition, the number of resources that can or must be selected so that an action is executable can be determined for an enabled condition or visible condition under the attribute Selection_Count. The Selection_Count attribute is only available for the relationships in the following list:
  • Application Option has Application Action
  • Global Action has Workbench Action
  • Global Action has Editor Action
  • Element has Action
  • Element List Structure has Action
  • File Descriptor has Action
The default value of Selection_Count is * this means that the number of selected resources is irrelevant for the evaluation of the condition.

If both an Enabled and Visible condition is defined for a relationship the two conditions are evaluated in the following way:

  1. Evaluate the Visible condition. If the Visible condition evaluates to false, the action is invisible.
  2. If the Visible condition evaluates to true, evaluate the Enabled condition. If the Enabled condition evaluates to false, disable the action.
  3. Otherwise, the action is shown and enabled.
Attribute | Type | Description
Selection_Count [O] | String | Number of resources that must be selected for the referenced action to be executable. Permitted values: * = Number of resources is irrelevant 0 = No resources may be selected n = Exactly n (n = 1,2,3,...) resources must be selected [*|n]-[*|n] = A range of numbers, for example, “2-*” = at least two resources must be selected. Default value: *
Complex_Enabled_Condition (0..1)[D] | Complex Condition | Complex condition. Consists of several combined conditions.
Simple_Enabled_Condition (0..1)[D] | Simple Condition | Simple condition. Checks a property value for a specific value.
Modeling Action Enabled Condition

The enabled condition for an element action is defined here. It begins with a complex enabled condition (green dashed framed), which links the two simple enabled conditions (red framed) with the AND operator. AWM interprets this model as follows:

Action ACT_X from ElementType ELE1 can only be executed if the property value of PROP_Protected is false and corresponds to the property value of Property PROP_Group “TEST”. In addition, exactly one Element must be marked.

A simple enabled condition checks a property value for a defined value or status, and activates or deactivates the action depending on the result of the check. If the check is done during the execution of an action, for example, by a Tool Enabled Condition, a property value is first searched for among output parameters of the previous tools of the action and then in the context of the selected element(s).

Attribute | Type | Description
TargetID | Property | Reference to the property whose value should be checked.
Operator Selection The check operator.

Valid values include:

  • Equals…(+ Value)
  • Equals not…(+ Value)
  • Regular Expression... (+ Value)
  • NULL
  • NOT_NULL
  • TRUE
  • FALSE
Value [D] | String | A fixed value that is compared with that of the Property.

The meanings of the different operators are shown in the following table:

Operator | Description | Example
Equals… | Checks whether the property value of the referenced property has the same value as specified in "Value". | The action can only be executed if the selected element is a COBOL program: TargetID = PROP_Type Operator = Equals… Value = COBOL
Equals not… | Checks whether the property value of the referenced property has a value different from the specified "Value". | The action can only be executed if the selected element is not in production: TargetID = PROP_Stage Operator = Equals not… Value = PROD
Regular Expression | Checks whether the property value of the referenced property matches with the regular expression specified in "Value". This check is not case sensitive. | The action can only be executed on COBOL files: TargetID = PROP_FileSuffix Operator = Regular Expression… Value = (cbl)|(cob)
NULL | Checks whether the referenced property has no property value. | The action can only be executed if the selected element has no access key: TargetID = PROP_AccessKey Operator = NULL
NOT_NULL | Checks whether the referenced property has any property value. | The action can only be executed if the selected element has a change date: TargetID = PROP_ChangeDate Operator = NOT_NULL
TRUE | Checks whether the referenced property has the Boolean value true. The valid value for true which is checked during run time is defined in the property definition. | The action can only be executed if the selected element can be edited: TargetID = PROP_Editable Operator = TRUE
FALSE | Checks whether the referenced property has the Boolean value false. The valid value for false which is checked during run time is defined in the property definition. | The action can only be executed if the selected element is not write-protected: TargetID = PROP_Protected Operator = FALSE

Examples

The CheckOut action is only enabled in the SCLM model for an element that does not have an access key on it and if the element is editable.

The CompareNext action is only enabled in the SCLM model if exactly one element is selected.

The property "COBOL File Dialect" is only visible in the Property view if the file is of type "COBOL Program".

Enable Action Has Tool

The above is an example of enabled conditions and parameter overrides in an Action_Has_Tool relationship. It is an example from the standard Endevor model supplied by Micro Focus. The delete action is designed to be executed in batch or online. Depending on the execution mode different tools are modelled. If the tool is executed in batch mode only the tools NDV_Tool_AWM_UI_Delete and NDV_TOOL_ISPF_REX_DeleteElementBatch are executed. If the tool is executed in online mode, the tools NDV_TOOL_AWM_UI_Delete, NDV_TOOL_ISPF_REX_DeleteElementOnline, NDV_TOOL_AWM_LocalTempFileCreator and NDV_TOOL_ECLIPSE_EditOpener are executed. In online mode the delete protocol is opened in the editor after the delete has been performed in Endevor. In the Action_Has_Tool relationship with the tool NDV_TOOL_AWM_LocalTempFileCreator, the parameter "File Name" is overwritten by the value of the property NDV_PROP_Element concatenated by the string "_DeleteProtocol". The parameter "Suffix" is overwritten by the static value "txt".

Parent topic: Data Model Details


File Descriptor

A file descriptor describes a file and, optionally, the structure of the file. The file can be located both in the Eclipse workspace or in the system to be attached.

The physical name (attribute Name_Physical) of the file does not have to be given in order to describe a file. This can be set by a tool output parameter at run time. If the physical name of the file already exists, a static value can be entered under this attribute. If only the structure of the file path has been defined, a dynamic path can be entered using dynamic references, see Variable References for more information.

A further feature of a file descriptor is the type. The “Workspace_File” type indicates files that should be saved in the workspace or that are to be read from the workspace.

Attribute | Type | Description
ID * | ID * | The ID of the file descriptor.
Name_Physical [O] String The physical name of the file under which the target system can find the file (file path + file name).

Dynamic references are allowed.

PropDelimiter String The delimiter to be used for the interpretation of structured file content.

Standard value: " " (Blank)

Structure Selection Describes the structure of the file.

Permitted values:

  • Unstructured (standard value)
  • Table
Type Selection The type of the file descriptor. This value defines how the described file should be interpreted.

Permitted values:

  • InputStream
  • Local file
  • Workspace_File (standard value)

The following values can only be used at run time if EDc, EDz or IDz is installed:

  • MVS_PO
  • MVS_PO_Member
  • MVS_SEQ
  • USS_File
Relationship | Cardinality | Description
Has_Property | 0..* | Relationship to a Property. Property Values can be assigned to a file content, which enables the further editing of the content. This relationship can only be used for the description of structured files (table structure).
Has_Action | 0..* | Relationship to an action descriptor. Used only if the file descriptor is of structure table and the table is part of a modeled dialog or an ISPF dialog. In this case the actions appear in the context menu of the table items.

Examples

File Descriptor SCLM_FILE_ElelistMember

File Descriptor SCLM_File_ElelistMember

File Descriptor SCLM_FILE_ElelistMember Properties
Attribute | Value | Description
Essential: |
ID | SCLM_FILE_ElelistMember | Unique identifier of the file descriptor in this model.
Prop Delimiter | "," | Comma is used as delimiter in the returned file to separate the values for the properties.
Structure | Table | A table structured file descriptor consists of a sequence of properties. The file has to provide in each line the values for every property defined as a File Descriptor_Has_Property relationship.
Type | MVS_SEQ | The format of the file is a MVS sequential file.
Optional: |
Name Physical | --- | The physical name is not needed as the file descriptor is modelled as file output parameter of an ISPF command tool. The REXX procedure associated with the ISPF command tool returns the file name.

Example content of a SCLM_FILE_ElelistMember file descriptor:

MFI01V,MFIJKH,SCLMTEST,SOURCE,BBANKJKP,MFIJKH,2016/02/05 11:01:22,0,,EDITABLE

MFI01V,MFIJKH,SCLMDEV,SOURCE,BBANKJKP,MFIJKH,2016/03/11 03:57:01,0,,EDITABLE

MFI01V,MFIJKH,SCLMPROD,SOURCE,BBANKZZP,MFIJSS,2014/10/13 12:17:06,0,,EDITABLE

File Descriptor SCLM_FILE_SclmMember

File Descriptor SCLM_FILE_SclmMember
Attribute | Value | Description
Essential: |
ID | SCLM_FILE_SclmMember | Unique identifier of the file descriptor in this model.
Prop Delimiter | " " | Not applicable as it is an unstructured file descriptor.
Structure | unstructured | The file has no internal structure.
Type | MVS_PO_Member | The format of the file is a member of a MVS PO (Partitioned Organised) data set.
Optional: |
Name Physical | &SCLM_PROP_ELE_MemberDatasetName.(&SCLM_PROP_ELE_MemName.) | The physical name of the PO member is defined by the current values of the two properties SCLM_PROP_ELE_MemberDatasetName and SCLM_PROP_ELE_MemName .
  • Relationship: File Descriptor Has Property
  • Relationship: File Descriptor Has Action
Parent topic: Data Model Details
Related information
Variable References


Relationship: File Descriptor Has Property

In addition to creating and reading files, you can interpret and process the content of a file. File contents can also be linked with properties. This can be modeled using the File has Property relationship.

You can link file contents to properties only if the file has records with a defined structure. See the figure below.

Attribute | Type | Description
TargetID * | Property | References a property whose value is part of the structured file.
Label [O] | String | Labels table column if the file should be displayed in a table. If no label is stated, the name is used as a label.
Visible Boolean Determines if this property should be displayed as a column in a table view.

The default value is true.

Editable Boolean Determines whether this table column is editable.

The attribute is used exclusively for the tools "Open Modeled Dialog" and "Execute ISPF Dialog", if the file descriptor is used as an input parameter and structure is "Table".

Editing a property in a table cell does not change any value outside the dialog, for example, it does not write the change back to a file, if the file descriptor describes a physical file, unless the table is part of an ISPF table dialog.

Note: A value changed in the table as part of an "Open Model Dialog" tool can be passed as output parameter to a subsequent tool.

Link between File Content and Properties

The file (black dashed framed) contains several records with a defined structure (Element name, User-ID, Date). These values can be processed further using Relationships to Properties (red dashed framed).

Example

File Has Property Relation

This file descriptor is used in an AWM tool of type "Open Modeled Dialog":

File In Table Dialog

This means the file content is displayed in the form of a table within the dialog box.

File Description Has Property
Attribute | Value | Description
Essential: |
Target ID | Reference to the property SCLM group. | The value on the first position of each row of the file descriptor is assigned to the SCLM group of the table entry.
Optional: |
Editable | false | This table column is not editable.
Label | Group | The table header for this table column is 'Group'.
Visible | true | The corresponding column is visible in the dialog table.
Parent topic: File Descriptor


Relationship: File Descriptor Has Action

If the file descriptor is defined as a structured table and the table is part of a modeled dialog or an ISPF dialog, the actions to appear in the table’s context menu can be modeled using the relation between the file descriptor and an action descriptor.

Attribute | Type | Description
TargetID * | ActionDescriptor | References the action descriptor.
Default_Action [U] | Boolean | Specifies whether this action should be executed by a double-click on the table item. Only one file descriptor action of a structured table can be declared as the Default_Action. The default value is false.
Label [O] | String | Labels the action in the context menu. If no label is stated, the label of the referenced action descriptor is used.
Separator_After | Boolean | Specifies whether to insert a separating line after the context menu entry. The default value is false.
Visible Condition [O] | Visible_Condition | Relationship to a visible condition. The action is only shown in the context menu if the visible condition evaluates to true. See Enabled/Visible Condition for more information.
Enabled Condition [O] | Enabled_Condition | Relationship to an enabled condition. The action is disabled if the condition is false. See Enabled/Visible Condition for more information.

Tools referenced in the action description can make changes to one or more table rows if the tool descriptor is modeled using ResourceProcessing. See Tool Descriptor for more information.

There are some special restrictions when using the resource operation to modify dialog table rows in comparison to rows in the Table Results view:

  • Only the selected table rows can be modified. A tool cannot identify which table rows are modified because the table rows are not of type AWM element and cannot be uniquely identified.
  • Only restricted resource operations are supported when modifying dialog table rows:
    COPY
    Copy the selected table rows with all properties and update the rows with the tool output parameters.
    DELETE
    Delete the selected table rows.
    UPDATE
    Update the selected table rows with the tool output parameters.
    INSERT
    Insert a new table row with the tool output parameters.
Parent topic: File Descriptor
Related information
Enabled/Visible Condition


Filter Type

A filter type describes a class of filters. It contains all the information to generate a Filter dialog, through which filters can be created. The element lists can be generated from a filter using the relationships of the FilterType to action descriptors.

At run time, filters can be created and edited via the Filter Definitions view. If element types have been defined with relationships to filter types, you can also create filters via the context menu of an element. In this case, the input fields of the Filter dialog is initialized with the property values of an element.

Attribute | Type | Description
ID * | ID * | The ID of the filter type.
Label [O] | String | The label of the filter in the context menu of the Filter Definitions view to define a new filter. If not used, the ID is displayed.
Relationship | Cardinality | Description
Has_Action | 1..* | Relationship to an action descriptor, via which an element list can be generated using the filter criteria.
Has_Filtercriterion | 1..* | Relationship to a property that is interpreted as a filter criterion.

Examples

SCLM Filter Types

In the SCLM model, three different SCLM filter types are defined:

Filter Type | Usage
SCLM_FIL_Member | Filter type to filter SCLM member by SCLM key properties.
SCLM_FIL_Member_Dependencies | Filter type to filter the dependencies of a SCLM member.
SCLM_FIL_Member_TextSearch | Filter type to define a textual search within SCLM members.

The properties in the relation Filter_Type_Has_FilterCriterion define the structure of the filter dialog. The action in the relation Filter_Type_Has_Action describes which action is executed when a filter of this type is executed from the Filter Definitions view.

A filter action should always return an element list which has to be modeled in the "Table Structure" attribute of the filter action:

Filter Member List
  • Relationship: Filter Has Action
  • Relationship: Filter Has Filter Criterion
Parent topic: Data Model Details


Relationship: Filter Has Action

Actions that can be carried out on the filter are defined by means of the Filter has Action relationship. By these means the corresponding element lists can be generated from a filter. More than one action can be assigned to a filter type returning different element lists. You can specify a relationship to an action descriptor to have the Default_Action attribute set to true, this enables you to generate an element list by double-clicking this filter.

If an element list for the filter already exists, this is displayed when the action is executed. In order to refresh the content of an element list the Refresh function for the Table Results view must be used.

Attribute | Type | Description
TargetID * | ActionDescriptor | The reference to an action descriptor that is to be carried out by the filter action. Preferably an action descriptor that returns an element list.
Default_Action [UC] | Boolean | Defines whether this action should be carried out by a double-click on the filter. Only one action of a filter type can be declared as a default action. The default value is false.
Label [O] | String | The display name of the action in the context menu of a selected filter.

Example

Filter Has Action Relation

Filter Has Action Properties
Attribute | Value | Description
Essential: |
Target ID | Reference to the action descriptor SCLM_ACT_FilterMemlist | The action SCLM_ACT_FilterMemlist is executed when the action is selected from the context menu of the filter. The filter criteria are available in the context for the tools defined in the action.
Optional: |
Default Action | true | This action is the default action of the filter which is performed when you double-click on a filter of this type.
Label | Filter Members | The label "Filter Members" is shown in the context menu of a filter of this type which can be selected to run the filter.
Parent topic: Filter Type


Relationship: Filter Has Filter Criterion

The Filter has Filter Criterion relationship references properties that are interpreted as filter criteria. The filter criteria are used as input fields for the corresponding filter dialog box.

When you execute an action on the corresponding filter, the filter criteria values and/or the property values of the referenced properties can be used as input parameters.

As a rule, a filter type has at least one action that returns an element list on the basis of the filter criteria.

Attribute | Type | Description
TargetID * | Property | Reference to a property that should be used as a filter criterion.
Label [O] | String | Display text of the input field in the Filter dialog box.
Mandatory | Boolean | Specifies whether the criterion is mandatory for the creation of a filter. If true, the user must specify a value in the generated input field in the Filter dialog box. Mandatory filter criteria are marked with the symbol * besides the label of the input fields. Note: A space value is a valid mandatory input. The default value is true.
Category [O] | String | Group the filter criterion in the Filter dialog box. See Input Dialog for more information.
Generic | Boolean | Specifies whether wildcard characters are permitted as filter criterion value. See Application Options for more information. The default value is false.

Example

Filter Has Action Relation

Filter Has Criterion
Attribute | Value | Description
Essential: |
Target ID | Reference to the property SCLM_PROP_ELE_Proj | The first value entered in the filter dialog is passed to the property SCLM_PROP_ELE_Proj.
Optional: |
Category | Filter criteria | This filter criterion is displayed within the group named 'Filter criteria' in the filter dialog.
Generic | false | Generic input is not allowed for this filter criterion.
Label | Project | The label for this filter criterion in the filter dialog is 'Project'.
Mandatory | true | The filter dialog requires a non-empty input under this filter criterion.
Parent topic: Filter Type
Related information
Application Options
Input Dialog
The "UI Category" Attribute


Global Action

A global action describes the location of an executable action described by an action descriptor. Global actions are usually used for action descriptors that do not necessarily belong to a certain type, for example, element type or filter type.

There are two types of global actions: workbench actions and editor actions.

  • Workbench actions:
    • Appear in the Eclipse menu bar and additionally under the sub menu Global actions of the application in the Application Explorer view.
    • Have action context (initial property values) which are created from the user’s selection.
Note: As a result of an existing restriction in Eclipse 4.x, global actions are currently not shown in the Eclipse menu bar.
  • Editor actions:
    • Appear in the context menus of text editors.
    • Have action context which are created from the opened element and the selection in the editor (depending on the modeled rules).

      See Global Action is an Editor Action for more information.

It is not guaranteed that the Editor Actions are visible in all Eclipse editors. It depends on the Editor provider. Editor Actions are displayed in the context menu of the following editors:

  • All Micro Focus Eclipse text editors integrated in Enterprise Developer (including the COBOL, PL/I, Assembler, and JCL editors).
  • All IDz integrated language editors (including the LPEX, COBOL, PL/I, Assembler, and JCL editors).
  • All standard Eclipse text editors (including the Java, XML, and Text editors).
Attribute | Type | Description
ID * | ID | The ID of the global action.
TargetID * | Action Descriptor | Reference to an action descriptor.
ISA Editor Action [C] | ISA_Editor_Action | Complex attribute for editor actions. See Global Action is an Editor Action for more information.
ISA Workbench Action [C] | ISA_Workbench_Action | Complex attribute for workbench actions. See Global Action is a Workbench Action for more information.
Visible Condition [O] | ActionVisible-Condition | This complex attribute lets you specify when the action is shown in the menu bar or the editor's context menu.
Enabled Condition [O] | ActionEnabled-Condition | This complex attribute lets you specify when the action is activated. If the Enabled Condition does not apply the action is disabled.
Label [O] | String | Specifies the global action label that appears in context menus or the menu bar. If not specified, the referenced action descriptor label is used.
Separator After [o] | Boolean | Specifies whether to insert a separator line behind the menu bar or context menu entry. The default value is false.
Submenu [O] | String | The name of a submenu in which the action should appear. If not specified, the action is created as a top level menu entry.
Icon [O] | Icon | The icon of the global action to display in menus.
  • Global Action is an Editor Action
  • Global Action is a Workbench Action
Parent topic: Data Model Details
Related information
Global Action is a Workbench Action
Global Action is an Editor Action


Global Action is an Editor Action

By specifying the complex attribute ISA Editor Action, the corresponding global action acts as an editor action.

An editor action appears in the context menu of an editor if the file suffix of the opened file matches one of the modeled editor suffixes. See Global Action for information about restrictions.

Editor actions can use the editor’s context if the editor is opened by a modeled action. See Validate Action for more information.

You can also dynamically use the cursor position or text selection to add properties to the action context. To do this, model a selection property mapping. It specifies which value from the user’s editor selection (or cursor position) should be mapped to which property.

Additionally, you can configure a keyword sensitive property mapping. Keywords can be any statement of a specific programming language, such as a COBOL Copy statement. Keywords can only be identified by specific keyword parsers, when the opened editor contains valid program code. The keyword parser can identify a keyword depending on the cursor position, and return its value, for example, the name of the include file of a COBOL Copy statement. The advantage of using keywords for selection property mappings is that you can disable the editor action if the specific keyword is not selected. Without keyword parsers, you must correctly select the desired value in the editor while the editor action always executes without any validation.

Attribute | Type | Description
Editor Suffixes * String[] Blank separated list of file suffixes for which the editor action applies (case insensitive). If the action should appear in all text editors, an asterisk (*) must be used.

The suffix is interpreted in a generic way. All files having a suffix ending with a string within the list determines the editor action. If you want the action only to be shown for files with specific suffixes, you have to specify the suffixes with the preceding period.

For example:

.COB .CBL

Result: The editor action appears in the context menu of any text editor for files with the suffix COB or CBL (such as MYPROG.cbl)

The default value is an asterisk (*).
Modeled Edit Sessions Only Boolean Specifies whether the action should be restricted to editor sessions opened by modeled AWM actions. When set to false, the action is shown in every supported, matching editor, even if no AWM context is available.

The default value is true.

Update Edit Context Boolean Specifies whether tools of the editor action can update the editor’s context.

If set to true, tools of the editor actions can update the editor’s context.

Note: The editor’s context is used by the save/close action. This means, if this attribute is set to true and a tool of the editor action has as output parameter a property used by the save/close action, the save/close action uses the changed value of the property.

The default value is false.

Selection Property Mapping [O] | Selection Property Mapping 0..* | Complex attribute that maps a specific text selection in the editor to a property. Can be used as an input parameter for tools within the action.

Attributes for the relationship: ISA Editor Actor to Selection Property Mapping

Attribute | Type | Description
TargetID * | Property | References a property to which the text selection should be mapped.
Value From Selection Specifies which value from the user’s editor selection (or cursor position) should be mapped to the property.

Valid values include:

  • SelectedText: The selected (marked) text
  • SelectedWord: The selected word (cursor position)
  • SelectedLine: The selected line (cursor position)
  • SelectedKeyword: The selected keyword (cursor position)
Keyword [D] Selection The name of the keyword that should be used for the property mapping. The selectable values for this attribute depend on the installed keyword parsers. By default, these are:
  • COBOL – COPYBOOK
  • COBOL – INCLUDE
  • PL1 - INCLUDE

Only relevant if Value From has the value SelectedKeyword.

Mandatory [D] Boolean If set to true, the editor action does not execute if the cursor is not placed on the specified keyword.

Only relevant if Value From has the value SelectedKeyword.

Example

An example for the use of the "Value From" attribute could be an editor action which returns the count of words of the selected text or selected line.

You have to model a tool with a text input parameter which is the property referenced under "Target ID" in the Selection Property Mapping relation of the ISA_Editor_Action relationship (PROP_AWMTEST_InputLine in the sample below). The tool returns the number of words of the input text. The property which contains the return value with the number of words in the input text could, for example, be modeled as input parameter of an AWM output dialog.

The editor action for this use case could be modeled in this way:

Select Line Editor Action

Select Line Properties
Parent topic: Global Action
Related information
Validate Action


Global Action is a Workbench Action

By specifying the complex attribute ISA Workbench Action, the corresponding global action acts as a workbench action.

A workbench action is designed to appear under its modeled label in the Eclipse menu bar as a main entry or submenu entry.

Caused by an existing restriction in Eclipse 4.x, Global Actions are currently not shown in the Eclipse menu. To make global actions still visible they are displayed in the Application Explorer view in the context menu of the entry Global actions directly under the application entry, see the example below:

The context of a workbench action is created from the user selection in the Eclipse workbench.

Attribute | Type | Description
Tool Tip [O] | String | The text that displays when the mouse hovers over the global action.
Type | Selection | The type of the workbench action. The only available type is currently Menubar.
Parent topic: Global Action


ID Definition

An ID definition is a description of an identifier for the elements of one or more element types.

In order to be able to guarantee the identification of an element, criteria must be defined that make an element unique. The criteria, the key properties, refer to the properties of an element type. The key properties are used to persistently administer elements in the workspace.

Tools that return elements or element lists must return all the key property values of the element as a minimum. An element cannot be created without the availability of all the key property values.

Attribute | Type | Description
ID * | ID * | The ID of the ID-Definition.
Relationship | Cardinality | Description
Has_Key_Property | 1..* | Relationship to a property. The referenced property must also be assigned to the corresponding element types.
  • ID Has Key Property
Parent topic: Data Model Details


ID Has Key Property

With the relationship ID has Key Property, the properties are referenced so that, together, they form an ID for elements of one or more element types.

Attribute | Type | Description
TargetID * | Property | Reference to a property that is a key property of an ID definition.
Parent topic: ID Definition


Icon

Icons can be used to assign symbols to elements and actions. This helps in the differentiation of the displayed types at run time, or for orientation in context menus, table views, tree views and so forth.

Modeled icons can appear, for example, in the following places at run time:

  • As an element icon in the Table Results or Application Explorer view.
  • As an action icon in the context menu of elements.

A function package provider has the possibility to support directly the icons for elements which belong to a linked element type.

Example: The Eclipse function package supports all icons which are used for Eclipse resources (projects, folders, and files), so it is not necessary to create those icons in the AWM model editor.

A function package provider has the possibility to support additional icons which can be used in the AWM model editor. Those icons are typically used to add icons to actions.

Example: The Micro Focus Enterprise Developer Icons function package supports icons which can be used as action icons to create new Micro Focus projects.

Icons are modeled by being defined once and then referenced in the Element Type or Action Descriptor.

There are two available icon types:

  • Pre-defined icons:

    Generic icon type which must have a unique ID and a reference to one of the pre-defined icon images, which can be selected through the “predefined” attribute of the icon. Predefined icons with names starting with “Action” are shown in grey if a modelled action cannot be executed due to an action-enabled condition.

    Attribute | Type | Description
    ID * | ID * | The ID of the icon.
    Predefined | Selection | This attribute is used to select an icon. The selected icon image is visible in the model editor, once the attribute value has been set.
    Note: Pre-defined icons have been deprecated. They can not be modeled anymore, but they can still exist in AWM models.
  • Function package icons:

    Icon defined by a function package. See Extending the AWM Meta Model for more information.

    If a function package containing icons is added to a model, desired icons can simply be created by selecting them under Icons > New Child > function package name > optional icon category > icon name.

    Function package icons can have separate icon images for disabled actions, which are automatically used by AWM if the icon is associated to an action which is disabled due to an enabled condition.

Parent topic: Data Model Details
Related information
Eclipse Function Package
Enabled/Visible Condition
Extending the AWM Meta Model
Global Action is an Editor Action
Micro Focus ED Icons Function Package


Property

A property describes an attribute that can be assigned to nearly all data model types. The value of a property can only be assigned at run time.

Each referenced property is displayed with its property value, if it is available, in the Eclipse Property View when the referencing object is selected.

The display names of elements in the Application Explorer view are also property values that have been referenced with special attributes in the relationship "Element Type has Property", as shown in the following figure.

Display names of Elements in the tree view

All the elements (blue dashed framed) are derived from the element type (blue framed) and share properties (green framed). The property values can be different. The element display name is defined via the relationship with the "Tree View Label" attribute.

Different attributes can be set when defining a property. One is the type of the property. This attribute defines how a property value is interpreted at run time. Its main impact is how a modeled dialog field is displayed and how input fields are validated. The definition of Boolean properties have an impact on the enabled condition checking.

Note: The type attribute specified in the model does not constrain the AWM managed property value to be this type at run time. For example, a property is defined as numeric but at run time the tool returns a character string value which AWM accepts.

The following property types are supported:

Type | Description
String This is the default type.

The property value can contain a text string which can be entered at run time in a modeled input dialog.

Boolean | At run time a control box is displayed in modeled dialogs.
Select_Value At run time a selection box is displayed for modeled input dialogs and the user can only select a value which has been defined in the AWM model.

The values that the user can select are defined by key values.

Optionally, key labels can be specified, which overwrite the display text of the key values in the selection box. If key labels are used, the number of defined labels must match with the number of key values.

Date In modeled input dialogs with date fields, the date can be chosen from a graphical calendar.

The stored date format can be configured in the AWM model. The default format is yyyyddMM.

Time Time properties are used to support time specifications in a modeled input dialog.

The property value is stored using the format HHmmSS.

Password | Password properties create non-readable password field in input dialogs. They do not offer any other password security such as encryption. If AWM is started in debug mode, entered passwords appear in the Eclipse error log.
Numeric | Numeric properties are used to support numeric values. A modeled dialog validates numeric input fields and adds leading zeros, if necessary, corresponding to the minimum value length attribute.
Text Area A text area property can be used to enter formatted text in a modeled input dialog. It can be modeled using the maximum lines attribute and the maximum characters per line attribute.

Depending on their values, the Input dialog box generates a multi-line text field.

At runtime a non-empty line is filled with trailing blanks.

Text Array Text array properties can be used to store a variable number of values. There are two ways to set the values of a text array property:
  • If the text array should always be empty when the dialog is opened (instead of showing cached array values), a space character can be defined as a static value of the corresponding modeled dialog input parameter.
  • Using a text array property as an input parameter in a modeled input dialog. A retrieve all values action must be referenced in the property definition to retrieve valid values.

Both scenarios generate a selection table within a modeled input dialog box so the user can choose which values to apply.

See Input Dialog and Output Dialog for more information.

A further property attribute used in context with dialog boxes is Retrieve_All_Values. You can specify an action descriptor to reference and associate with a tool which returns a list of all the valid values for that property, one line per value. The action is called via a Retrieve button in the input dialog box, and returns the valid values as a selection list in the combo box field. The tools of the referenced action descriptor have access to all the input fields of the dialog box. User inputs in those fields can be used as input parameters.

Retrieve button in a Filter dialog

The combo box is populated with the returned values when the Retrieve action executes. Any field values entered in the dialog box can used as tool input parameters for the retrieve action.

Attribute | Type | Description
ID * | ID * | The ID of the property.
Default_Value [O] | String | The standard value of the property serves as the default entry for input fields or input parameters. As soon as a tool has assigned a property value to this property, the default value is no longer used.
Special_Property Selection Indicates whether this property has a special meaning. See Special Properties for more information.

Valid values are:

  • NONE (default)
  • element type
  • Element_Suffix
  • MarkerLineNumber
  • Property Group
Resource Identifier * (if visible) Selection Only relevant for linked properties which require an additional link to a property which identifies a corresponding linked element. It is not displayed in the model editor's property view if it is not relevant.

Example: all linked properties defined in the Eclipse function package need a resource identifier the modelled property which identifies an Eclipse resource (project, folder or file). Otherwise the function package would not be able to get or set a linked property value.

Label [O] | String | The display text of the property in the Properties view and the default display text, if the property is used in modeled dialogs. If not specified, the property ID is used as the display text.
Value_Keys [D] String [] The permitted property values for a property if it has the typeSelectValue. If no labels are defined for the key values, the key values are used at run time to create the selection list for this property in the input dialog box.

The value must not contain any white spaces.

Label_Keys [D] String [] Defines the display texts for each defined value key. This attribute is only relevant if the property has the type Select Value and it is optional. If labels are specified, the number of labels must match the number of the key value.

The labels must not contain any white spaces. Underscore characters (_) can be used instead as they are converted to white spaces at run time.

RetrieveAll Values [O] | Action Descriptor | Reference to an action descriptor that returns the valid values of this Property. See Retrieve All Values for more information.
Upper case [O] Boolean The value of this property is always converted to upper case if entered in a modeled dialog box.

The default value is false.

Type Selection The type of the property.

Valid values include:

  • String
  • Boolean
  • SelectValue
  • Date
  • Time
  • Password
  • Numeric
  • Text Area
  • Text Array
Max Lines Integer Limits the number of lines of a text area property.

The default value is 0 (unlimited)

Chars Per Line Integer Defines the length of every line of a text area property. Non-empty lines are populated with blanks on dialog box confirmation.

The default value is 80.

Value Max Length [O] Integer Limits the permitted length of a value within an input field for this property.

The default value is 0 (unlimited)

Value Min Length [O] Integer Defines a minimum length for a value within an input field for this property.

The default value is 0 (unlimited)

False Value [O] | String | Only relevant for properties of type Boolean. Specifies the value returned from dialog boxes when the property value is false. In addition, this is the value used to check an enabled condition, if the operator false has been used.
True Value [O] | String | Only relevant for properties of type Boolean. Specifies the value returned from dialog boxes when the property value is true. In addition, this is the value used to check an enabled condition, if the operator true has been used.
Date Format [O] String Only relevant for properties of type Date. Specifies the format of the date for creation and validation in dialog boxes. See Date format for more information.

Default value: yyyyMMdd

For example: MM/dd/yyyy

String Delimiter | String | Only relevant for properties of type TextArray. This value is used to delimit the values of a text array when passed as parameter values to a tool.
  • Special Properties
  • Date Format
  • Property Dependent Values
  • Retrieve All Values
Parent topic: Data Model Details
Related information
Date Format
Input Dialog
Open Modeled Dialog
Output Dialog
Property
Retrieve All Values
Special Properties


Special Properties

A property can have one of several special meanings in the run time context. These can be modeled by the "Special Property" attribute:

Special Property Description
Element Type Indicates whether the property value of this property contains a match name, see Element Type for more information.

This information is used at run time when AWM has to create a new element. Tools have to provide the correct match name as an output parameter or AWM cannot associate the new element to its element type.

Element Suffix Indicates whether the property value of this property contains a file suffix.

This information is used by edit/browse actions to be able to invoke the correct editor.

Marker Line Number Indicates whether the property value of this property contains a line number used to mark the line in an editor.

This information is used if an edit or browse action is called in a tree table, which for example has been created by a search action.

Property Group Indicates whether the property value of this property contains the name of an IDz property group.

This is only used by the Edit Local File tool which is part of the Eclipse Function Package and is only relevant in an IDz installation.

In all other scenarios or if this special property is not used, the "Associate Property Group" tool from the IDz function package is available.

Parent topic: Property
Related information
Associate Property Group
Element Type


Date Format

The date format attribute can be used to specify dynamically how the date value of the property should be formatted and validated in modeled dialogs. It is defined by using certain pattern letters (see the table below) and optional separators.

Examples:

  • yyyyMMdd -> 20011231
  • dd.MMM.yyyy -> 31.Dec.2001
  • MM/dd/yy -> 12/31/01

A date value can be created by clicking on the choose date button on a modeled input dialog with a date field. The date will be generated with the specified format. If the date format contains time pattern letters (like “h” for hours), the current time will be used for the generated date.

If a user chooses to type the date in manually, the dialog will validate the field with the specified date format. The following table shows all available date format pattern letters (all other characters from “A” to “Z” (lower and upper case) are reserved):

Letter | Date or Time Component | Presentation | Examples
G | Era designator | Text | AD
y | Year | Year | 1996; 96
M | Month in year | Month | July; Jul; 07
w | Week in year | Number | 27
W | Week in month | Number | 2
D | Day in year | Number | 189
d | Day in month | Number | 10
F | Day of week in month | Number | 2
E | Day in week | Text | Tuesday; Tue
a | Am/pm marker | Text | PM
H | Hour in day (0-23) | Number | 0
k | Hour in day (1-24) | Number | 24
K | Hour in am/pm (0-11) | Number | 0
h | Hour in am/pm (1-12) | Number | 12
m | Minute in hour | Number | 30
s | Second in minute | Number | 55
S | Millisecond | Number | 978
z | Time zone | General time zone | Pacific Standard Time; PST; GMT-08:00
Z | Time zone | RFC 822 time zone | -0800
Parent topic: Property
Related reference
Text
Year
Month
Number
General time zone
RFC 822 time zone


Property Dependent Values

Property-dependent values can be specified for “Select Value” properties. Using a specific syntax, the administrator can define “Value Keys” for a property that depends on another property value:

<Start_Ref><Dependent Property ID><End_Ref>=<Dependent Value>:<Value>

Example:

&PROP_Language.=COBOL:COBPROC1

Means: If the property with the ID PROP_Language has the value “COBOL”, one of the value keys is COBPROC1.

Property-dependent values only apply to dialog fields within an Input dialog.

Parent topic: Property


Retrieve All Values

The “Retrieve All Values” attribute can be used to dynamically retrieve valid values for a property at run time. The attribute requires an action descriptor to be referenced which must contain a tool that returns a list of values. A file descriptor must be used to model the tool output.

The retrieve all values action can only be executed in a modeled input dialog (see Open Modeled Dialog). If a property with a retrieve all values action is used as an editable input field in a dialog, a Retrieve button will appear next to it. Clicking the button will execute the action and populate the dialog field with the returned values. The modeled retrieve action descriptor needs a tool descriptor which returns a structured file descriptor. The file descriptor must have at least one relationship to a property.

If several tool descriptors of the retrieve action return file descriptors the last one will be used by the Workflow Manager.

The context of the retrieve action will contain all properties from the main context plus all values from the current dialog. Therefore, it is possible to use dialog fields as input parameters for the retrieve action (as shown in the figure below).

A populated input field

Additionally, you can return labels for the retrieved values. The combo box in the dialog will then show only the labels, while selecting an item will put the value into the input field. Simply return two values for each line of the file. AWM will interpret the first value of each line as the retrieved value, and the second as the label. Additional values returned by a tool will be ignored.

You cannot use a property of the type Text Array to support the retrieve all values action.

The label of the Retrieve button can be customized using the specific attribute defined under Application Options.

If the retrieve action returns only one line, its value is directly filled in the editable field and the combo box is not used. Therefore the retrieve action can be used for dialog fields where a user should enter a file or folder.

Example: In a retrieve all values action you can use the select resource tool from the Eclipse function package or the select local OS resource tool from the OS function package to open a standard dialog for file/folder selection. The selected file/folder is directly placed into the dialog input field.

Parent topic: Property
Related information
Application Options
Open Modeled Dialog
Select Local OS Resource
Select Resource


Tool Descriptor

An AWM tool descriptor describes how a tool provided by a function package is called at run time. Tool descriptors can only be referenced by action descriptors where they are defined in a fixed sequence. The return code of a tool is checked against the maximum allowed return code defined under Application Options. If the return is high this prevents the execution of all following tools defined in the action descriptor. Output parameters of tools can be used as input parameters for subsequent tools.

The basic requirement for the implementation of a tool is an implementation of a tool interface. The function package to which the tool descriptor belongs defines the connection between tool descriptors and the communication interfaces. The function package has to implement the AWM model extension point. See the function package topics for details about all provided AWM tool descriptors.

Any tool making changes to one or more AWM elements in the attached application should be specified in the tool descriptor in such a way that AWM can react to such operations. This is modeled using the ResourceProcessing attribute.

Configurable resource operations are based on the following rules:

  • Resource operations are supported for elements.
  • Any new elements added to the Table Results or Application Explorer view by an action are inserted at the bottom of the list or, if the list has been sorted, according to the sorting criteria.
  • Inserted elements must not match the filter criteria after they are inserted. Refreshing the list shows only elements consistent with the filter criteria.
  • Property values returned when updating or inserting an element are assigned to the element except for key properties.
  • By default, resource operations apply for the selected resource. UPDATE and DELETE can be applied on any AWM element if its key properties and match name are provided by the operation. Providing the match name is optional, as long as the action is executed on an element of the same type as the target element.
  • Resource operations are not executed if the corresponding tool execution returns an error code higher than the maximum allowed return code.

The following resource operations can be modeled for a tool descriptor:

Resource Operation | Description
COPY | Creates a new element based on the selected element. All the property values are copied first. Property values returned by the tool are assigned to the copied resource. The copied element is inserted into the Application Explorer or Table Results view. In the tree view the element is inserted on the same hierarchical level as the selected element.
DELETE | Removes the selected elements from all lists. It does not necessarily mean that the elements are deleted in the attached application system. This depends on the modeled tool. Supports deleting specific elements if their key properties and match name are returned with the resource operation.
INSERT | Inserts a new element into the Application Explorer or Table Results view. In the tree view the element is inserted on the same hierarchical level as the selected element. If an element with the same ID already exists, an UPDATE is performed instead.
INSERT-CHILD | Inserts a new element as a child of the current selection. Works only if the selected resource is able to have children, such as an element that has a "Get Children" action and is only relevant for the Application Explorer view. If an element with the same ID already exists, an UPDATE is performed instead.
MOVE | Creates a new element based on the selected element. All the property values are copied first. Property values returned by the tool are assigned to the copied resource. Then it removes the selected element from all lists. It does not necessarily mean that the element is deleted in the attached application system. This depends on the modeled tool. The new element is inserted into the Application Explorer or Table Results view. In the tree view the element is inserted on the same hierarchical level as the selected element.
READ | Standard value. Does not make any changes to elements.
REFRESH | Updates all property values of the selected element by means of the "GetAllProperties" action assigned to the element type. If you want to refresh an element directly after inserting an element, you should use the "Refresh Resource" attribute of the tool descriptor instead.
UPDATE | Updates the selected element with the values returned by the tool. Key property values cannot be updated. Supports updating specific elements if their key properties and match name are returned with the resource operation.
TOOL_DEFINED | The rules about which element operations are to be used for this tool descriptor are set in the attached tools and not in the model. This makes dynamic implementation of resource operations possible. It also allows for dealing with more than one resource. See Tool-defined Resource Operations for more information.

The attributes which are displayed for a tool descriptor in the model editor may depend on the function package provider. The function package specific tool attributes are documented in the function package topics. See Extending the AWM Meta Model for more information.

Attributes that are valid for all tool descriptors are listed in the table below:

Attribute | Type | Description
ID * | ID * | The ID of the tool descriptor.
RefreshResource Boolean Indicates whether the element should be updated after successful execution of the tool. This means that the "GetAllProperties" action of the element is always called after a successful execution of the tool. See Get All Properties Action for more information.

The default value is false.

ResourceProcessing Selection Defines the operations that the tool carries out with elements, so that the AWM can react to this.

Valid values include:

  • COPY
  • DELETE
  • INSERT
  • INSERT-CHILD
  • MOVE
  • READ (default value)
  • REFRESH
  • TOOL_DEFINED
  • UPDATE
In Parm Separator [O] String Separator used to separate input parameter values for command based tools. Can be entered with double quotes, which are removed at run time.

The default value is " " (Blank).

Out Parm Separator [O] String Separator that parses returned output parameter values from command based tools. Can be entered with double quotes, which are removed at run time.

The default value is " " (Blank).

HelpText [O] String

(multi line)

Help text associated with the tool. If this help text is defined for a UI tool, the help text appears when the question mark is clicked in the dialog box.
Relationship | Cardinality | Description
Has Input Parameter | 0..* | Relationship to a property. The property value is passed as an input parameter to the tool.
Has Output Parameter | 0..* | Relationship to a property. The property value is passed as an output parameter to the tool.

Examples

Tool SCLM_TOOL_AWM_UI_ChangeLanguage

Attribute | Value | Description
Essential: |
Dialog Type | Input Dialog | The tool represents an AWM input dialog. All referenced properties are represented as fields in the input dialog. The "Preview Dialog" action can be used in the model editor to show a preview of the dialog. See Open Modeled Dialog for more information.
ID | SCLM_TOOL_AWM_UI_ChangeLanguage | Unique identifier of the tool in this model.
Optional: |
Description | Change or Retrieve a new valid SCLM language. | Informational message shown in the header of the AWM input dialog.
Help Text | --- | No special help text is specified for this dialog box; modelled help text is associated with the question mark in the bottom of the dialog dox.
In Parm Separator | --- | No input parameter separator is needed for a tool of type "Open Modeled Dialog"
Out Parm Separator | --- | No output parameter separator is needed for a tool of type "Open Modeled Dialog"
Title | Change SCLM Language | Text shown as the title of the AWM input dialog.
Validate Action | --- | No validate action is specified for this dialog. A reference to an action could be specified here. The action is executed when the OK button is clicked before the dialog is closed, see Validate Action for more information.
Resource Processing: |
Refresh Resource | false | The GetAllProperties action should not be called after the successful execution of this tool.
Resource Processing | UPDATE | Resource processing UPDATE means that the properties of the selected AWM element are updated after the successful execution of the tool by changes on properties in the dialog, in this case the SCLM language. It is not necessary to explicitly specify the output parameters for resource processing. This is because the AWM input dialog parameters are also treated as output parameters.

Tool SCLM_TOOL_ISPF_REX_CopyElement

Attribute | Value | Description
Essential: |
ID | SCLM_TOOL_ISPF_REX_CopyElement | Unique identifier of the tool in this model.
Invocation Form | REXX | Defines how the ISPF tool is called; for a REXX procedure the invocation form REXX is the default.
Program ID | TAUSCCPY | Name of the REXX to be called.
Run As Job | NO | The tool should be executed directly in the associated server.
Optional: |
Help Text | --- | Help text is irrelevant for tools of type "Execute ISPF Command".
In Parm Separator | " " | The input parameters for the tool are separated by blanks.
Out Parm Separator | " " | The output parameters for the tool are separated by blanks.
Resource Processing: |
Refresh Resource | true | The GetAllProperties action is called after successful execution of the tool.
Resource Processing | COPY | A new AWM element is created and initialized with the property values of the selected AWM element. The new AWM element is updated by property values returned by the tool as output parameters.

Tool SCLM_TOOL_ISPF_REX_PromoteOnline

The tool SCLM_TOOL_ISPF_REX_PromoteOnline is an example of the usage of different tool output parameter types.

Parameter Type | Description
String Output | Return message of the tool under the OUTPARM parameter.
File Output | File descriptors containing additional SCLM information concerning the SCLM action. The corresponding REXX procedure returns the file names under the OUTPARM parameters. Setting the attribute "To Output Dialog" in the relationship Tool_Has_OutputParameter to true has the effect that an AWM output dialog is opened presenting the content of the returned files after all tools of the corresponding action are executed.
ToolDefinedResourceProcessing | Set of properties to which the resource processing values returned by the tool are mapped. If the standard AWM ISPF tool interface is used the resource operation values can be returned in the ISPF table TAUTOTBI.

  • Relationship: Tool Has Input Parameter
  • Relationship: Tool Has Output Parameter
  • Tool-defined Resource Operations
Parent topic: Data Model Details
Related information
Batch Execution
Element Type
Extending the AWM Meta Model
Relationship: Get All Properties Action
Icons
Open Modeled Dialog
Tool-defined Resource Operations
Validate Action


Relationship: Tool Has Input Parameter

The Tool has Input Parameter relationship describes exactly one input parameter of a tool. The reference of the relationship is a property whose property value can be passed as parameter to the tool at run time.

The Parameter From attribute determines where the value of the parameters should be obtained from. There are three ways of determining the origin of parameters:

  • Parameter From = Context

    The context includes all property values that are available at the start of the execution of an action, and does not change during the tool sequence. For example, if you execute an action on an element, all the property values of the element, the element list in which it is located and the resources where it is found (such as filter, element) are available. The Properties view at run time is a good way of obtaining an overview of the available property values of a selected resource.

  • Parameter From = Previous_Tool

    This setting is intended for the transfer of parameters between tools that are temporarily managed in a parameter memory. No property values from this memory are available to the first tool in a tool sequence. As soon as a tool creates an output, the output properties and their values are available for subsequent tools. In the parameter memory, only one property value is saved for a property. See Relationship: Tool Has Output Parameter for more information.

    A tool that outputs a property value for a property that already exists in the memory replaces this value, see the figure below.

  • Parameter From = User_Input

    User_Input means that the parameter should be entered by the user during the execution of the tool. This is used in tools with a user interface, such as the Input dialog box. In this case, parameter value is transferred to the tool.

Transfer of Parameters between tools

The Parameter Memory is the temporary storage area for output tool parameters. The values 123, ABC and XYZ are the concrete outputs of the respective tools and are saved as property values. The illustration shows how the property PROP_2 has been referenced for two tools as an output parameter. The second output (XYZ) overwrites the first (ABC).

Attribute | Type | Description
TargetIDFile[D] | File Descriptor | Reference to a file descriptor. Only important if the type attribute has been set to File.
TargetIDParm[D] | Property | Reference to a property. Only important if the type attribute has been set to Mass Processing or String.
DefaultValue [O] String

(multi line)

The standard value of the parameter. This value is only used if no other property value can be found for the referenced property.

Has no meaning for file parameters.

Initializes a field in an Input dialog box.

Label [O] | String | Label of the parameter in dialog boxes.
Parameter From Selection Determines from where the property value of the parameter property should be obtained.

Valid values include:

  • Context (default)
  • Previous_Tool
  • User_Input
StaticValue [O] String

(multi line)

Sets a fixed value for the parameter. This can only be overwritten via parameter override. See Parameter Override for more information.
Type Selection The type of the parameter. A property or a file descriptor must be referenced on the basis of this attribute.

Valid values include:

  • MassProcessing(+ TargetIDParm)
  • File(+ TargetIDFile)
  • String(+ TargetIDParm)

The default value is String.

Ui Category [O] | String | Categorizes the parameter in dialogs. Categorized parameters are enclosed in a labeled frame. Successive parameters with the same category are enclosed by the same frame and ordered by sequence number. See The "UI Category" Attribute for more information.
Ui Tab [O] | String | Allows the assignment of parameters to tabs. Tabs are individual dialog pages which are activated by clicking the tab label at the top of the dialog. Successive parameters with the same tab are displayed in the same tab page. This works only for Input dialog boxes. See The "UI Category" Attribute for more information.
Ui Editable Boolean Indicates whether the parameter can be edited in input dialog boxes. Fields are never editable in an output dialog box.

The default value is true.

Ui GenericAllowed Boolean Indicates whether wildcard characters are permitted as user input. If false, the input dialog box cannot be confirmed if wildcard characters are present in the input field. See Application Options for more information.

The default value is false.

Ui Mandatory Boolean Indicates whether the field is mandatory in Input dialog boxes. If true, the dialog box cannot be confirmed when the field contains no values.

Mandatory fields are marked with an asterisk *.

The default value is true.

Ui Form [O] | String | Specifies formatting information for the field in Input dialog boxes. Valid values include: BOLD, HIDDEN, RED, GREEN, YELLOW, BLUE, GRAY.
Ui HelpText [O] String

(multi line)

Specifies help text for the field in input dialog boxes which is displayed when the question mark button beside the field is clicked or the F1 key is clicked in the field. Clicking in the input field of the attribute opens a dialog box where the help text can be entered in a formatted way.
Ui MultiSelection Boolean Specifies whether multiple items can be selected. For structured file input parameters only. If set to true, a check box table is created.

The default value is false.

Ui Resizable Boolean

Specifies whether a dialog field can be resized or not.

Properties of types Boolean, TextArea and TextArray cannot be set to be resizable.

The default value is true.

Ui ToolTip [O] String

(multi line)

Specifies a tool tip for the field in Input dialog boxes.
Visible Condition [O] | Visible_Condition | This complex attribute is only relevant for a modeled dialog. It allows you to define rules when the input parameter should be shown in the dialog. See Enabled/Visible Condition for details of how to define an enabled or visible condition.
Enabled Condition [O] | Enabled_Condition | This complex attribute is only relevant for a modeled dialog. It allows you to define rules when the input parameter should be enabled in the dialog. See Enabled/Visible Condition for details of how to define an enabled or visible condition.

Examples

The SCLM Architecture Definition Generation tool (SCLM_TOOL_ISPF_REX_Archgen) is an example of a tool with two different kind of input parameters:

The MassProcessing input parameters are taken from the context in which the action is executed (Parameter From = Context). This means that for each selected item the values of the properties related to the MassProcessing parameters are passed to the tool. In this case, the MassProcessing input parameters are passed to an ISPF REXX tool via the ISPF table TAUTOTIP. The MassProcessing properties of type Parameter From=Context must be available in the context of the selected elements. It is also possible to define all MassProcessing input parameters of type Parameter From=Previous Tool. In this case a preceding tool in the action must supply the MassProcessing input parameters as MassProcessing output parameters. The MassProcessing input parameters of a tool have to come from one source, either the context or from a previous tool.

The String input parameters are taken from the previous tool (Parameter From = Previous_Tool). The values of these properties passed to the tool are identical for each selected element. In this case, the parameters are passed as regular arguments to the ISPF REXX tool. The assumption is that another tool is configured for an action using a preceding tool's parameters. The preceding tool could be an input dialog as in the standard SCLM model or just a tool deriving the String input parameters from some default settings.

The tool SCLM_TOOL_AWM_UI_InputArchgenOptions is of type 'Open Modeled Dialog'. A tool of type 'Open Modeled Dialog' typically has String input parameters which are represented in the dialog as dialog fields. This is where the parameter attributes listed under UI are of relevance. The parameter SCLM_PROP_LIST_StartGrp is derived from the context, the other parameters are taken from user input. A parameter derived from the context presents the value of the dialog field with the current value from the context. Typically, parameters which are mapped to an element type are derived from the context when opening a modeled dialog. Parameters which are not mapped to any element type should be modeled as Parameter From=User_Input in a tool of type 'Open Modeled Dialog'. A tool of type 'Open Modeled Dialog' treats input parameters as output parameters. This means the values entered in the input dialog can be used by following tools in the same action as input parameters with Parameter From=Previous_Tool.

Browse Local File

The OFFL_TOOL_AWM_BrowseOSFile tool is an example of a tool which gets a file as an input parameter. Typically, a file input parameter has a Parameter From=Previous_Tool. The file is returned by a preceding tool and is used as an input parameter for the OFFL_TOOL_AWM_BrowseOSFile tool. In the standard SCLM model the previous tool is the tool OFFL_TOOL_AWM_LocalTempFileCreator:

Parent topic: Tool Descriptor
Related information
Application Options
Enabled/Visible Condition
Parameter Override
Relationship: Tool Has Output Parameter
The "UI Category" Attribute


Relationship: Tool Has Output Parameter

Output parameters of tools are described by the Tool has Output Parameter relationship.

The output parameters of a tool are temporarily saved during the execution of an action, so that subsequent tools can use them as input parameters.

The way in which the output of a tool should be interpreted can be modeled via the type attribute. Depending on the type, a property or a file descriptor must be referenced via the relationship.

  • Type = String

    Standard value. The output is assigned as a property value of the referenced property.

  • Type = ToolDefinedResourceOperation

    To be used if the tool returns TOOL-DEFINED resource operations for a group of elements. See Tool Descriptor for more information about tool-defined resource operations. The count of parameters should map to the property values returned by the tool-defined resource operation of the specified tool.

  • Type = MassProcessing

    To be used if the tool returns property values for a group of elements. The count of parameters should map to the property values per element returned by the specified tool.

  • Type = File

    A tool output that is modeled with the File type is interpreted as a file name. You must reference a file descriptor. If a physical name (Name_Physical) is modeled for the referenced file descriptor, it is temporarily overwritten. The output parameter contains the name of the file, and the referenced file descriptor defines the type and the structure of the file.

Attribute | Type | Description
TargetIDFile[D] | File Descriptor | Reference to a file descriptor. This is only important if the type attribute has been set to “File”.
TargetIDParm[D] | Property | Reference to a property. This is only important if the type attribute has been set to “Element” or “String”.
Label [O] | String | The display text of the parameter in the Output dialog box.
Type Selection Determines how the output parameter should be interpreted.

Valid values include:

  • String
  • File
  • ToolDefinedResourceOperation
  • MassProcessing

Default value is string.

ToOutputDialog [O] | Boolean | Indicates whether the parameter should be displayed in the Output dialog box at the end of the action. This only takes place if there is an Output dialog modeled at the end of the tool sequence.
Ui Category [O] | String | Categorizes the parameter in the Output dialog box. Categorized parameters are enclosed in a labeled frame. Successive parameters with the same categories are enclosed by the same frame in the Output dialog box. See The "UI Category" Attribute for more information.
Ui Resizable Boolean

Specifies whether a dialog field can be resized or not.

Properties of types Boolean, TextArea and TextArray cannot be set to be resizable.

The default value is true.

Examples

SCLM Archgen Input Parameters
The tool SCLM_TOOL_ISPF_REX_Archgen is an example of a tool which returns an output parameter of type String and of type File. If an ISPF REXX tool is modelled to return a parameter of type File, it should return the name of the file in the REXX OUTPARM variable.
Note: The file has to be modeled on the correct type (MVS_PO, MVS_PO_Member or MVS_SEQ).

SCLM Check Out Parameters

The tool SCLM_TOOL_ISPF_REX_CheckOut is an example of a tool with output parameters of type ToolDefinedResourceOperation. The tool has to return a resource operation statement containing the resource operation to be performed and a value for every modeled output parameter of type ToolDefinedResourceOperation. See Tool-defined Resource Operations for more information. In this case, the tool is an ISPF REXX tool which has to return the resource operations in the ISPF table TAUTOTBI.

SCLM Archgen Mass Output Parameter

The tool SCLM_TOOL_ISPF_REX_ArchgenBatchInput is an example of a tool with output parameters of type String and of type MassProcessing. The tool provides the input for a succeeding tool to generate SCLM architecture definitions for a group of SCLM elements. The MassProcessing output parameters of this tool are mapped to the MassProcessing input parameters of the succeeding tool. If the tool is an ISPF REXX tool, the MassProcessing output parameters have to be returned in the ISPF table TAUTOTOP.

Parent topic: Tool Descriptor
Related information
Batch Execution
The "UI Category" Attribute


Tool-defined Resource Operations

Unlike static resource operations such as UPDATE or DELETE, tool-defined resource operations can be dynamically returned by a tool. There are only two reasons for using a tool-defined resource operation instead of a static one:

  • The correct resource operation for an element can be determined only at run time, such as for an update or insert.
  • Based on one input element, the tool creates or updates several elements, for example, a compile tool which creates output files.

Examples

  • A tool Check OutFile either updates an element if it already exists in the application's development stage (UPDATE) or copies a file into the application's development stage (INSERT).
  • The tool Compile Program creates several build output files (multiple INSERT resource operations).
Configuring a tool-defined resource operation in the model requires the following:
  • The Resource Processing attribute of the tool descriptor must be set to TOOL-DEFINED.
  • Properties returned by the resource operation must be modeled as output parameters of the type ToolDefinedResourceOperation.

The resource operations to be processed by AWM are returned by the tool at run time by using specific syntax:

      operation(refid,REFRESH,SELECT): properties

See the table below for more information.

Example

UPDATE-ELEMENT(DDLOCK): SCLM,DEV1,SOURCE,TESTRP1, 2014/03/21 09:16:28

This resource operation updates the changed date and time of an SCLM element with the ID SCLM_DEV1_SOURCE_TESTRP1 and saves the properties in a separate context. This element can be accessed by follow-up tools by the logical name DDLOCK in the 'Affected Resource Name' attribute of the Action_Has_Tool relationship.

Keyword | Description
operation * The resource operation to be executed.
Valid values:
  • INSERT-ELEMENT
  • INSERT-CHILD
  • REMOVE-ELEMENT
  • UPDATE-ELEMENT

The values are equivalent to the static resource operations INSERT, INSERT-CHILD, REMOVE and UPDATE.

refid [O] A reference ID, which is a logical name that creates a separate context that can be accessed by other tools within the action. Properties returned by this resource operation are stored in the separate context instead of the main context.

Any following tools of the action that have the reference ID modeled as Affected Resource Name (relationship Action has Tool) use that separate context. See Relationship: Action Has Tool for more information.

REFRESH [O] | Determines whether to execute the "Get All Properties" action of the element. This action is executed directly after the tool that returned this resource operation.
SELECT [O] | Selects the element in the view where the action was executed. Only relevant if the properties of the resource operation contain a valid element ID (combination of ID definition properties). See ID Definition for more information.
properties Depending on the resource operation, the following rules apply to tool output parameters:
  • INSERT-ELEMENT and INSERT-CHILD

    Requires all key properties of the element that should be created and the match name property. If the returned ID exists, an UPDATE is performed instead. Additional regular properties are added to the inserted or updated element.

  • REMOVE-ELEMENT

    Depending on whether key properties and the match name property are returned by the resource operation, either the identified element or the selected one is removed.

  • UPDATE-ELEMENT

    Only updates properties returned by the resource operation. Key properties and match name update a specific element. Without key properties, the selected element is updated.

Returned resource operation properties must be modeled as output parameters of the type ToolDefinedResourceOperation.

Affected Resource Contexts

Tool-defined resource operations can provide a logical name to create a separate, independent execution context to be used by subsequent tools. This context is called an Affected Resource Context and is only used by tools which refer to its logical name in the relationship Action has Tool . Exceptions to this are related save/close actions, see note below.

Scenarios can occur where the element of interest changes during an action. It is possible to create multiple affected resource contexts during an action.

Example

An action “Create Test Case…” is executed on a program. Its first tool creates a test case element and returns an INSERT tool-defined resource operation with affected resource name TESTCASE and properties for the new test case element. The second tool opens the test case in an editor, using TESTCASE as the affected resource name (relationship Action has Tool). This is necessary, because both the program and the test case element have common properties, for example, path, name, and suffix. The edit tool requires the path, name, and suffix from the test case element, not from the program.

Note:
  • If a tool that supports related save/close actions is used with an Affected Resource Context, related actions are executed on the same referenced context. See Related Save-/Close Action for more information.
  • Before AWM V3.0, affected resource contexts were not independent from the main context. Properties and output parameters in the main context were still resolved in affected resource contexts, which was causing inconsistencies and a lack of transparency. In order to maintain backward compatibility, this behavior can still be enabled by setting the application option Independent Affected Resource Contexts to false. See Application Options for more information.
Parent topic: Tool Descriptor
Related information
ID Definition
Relationship: Action Has Tool


Variable References

Some string attributes in the AWM model support the use of variable references. Referenced variables can be defined dynamically as part of a string and can reference AWM properties, environment properties, and certain static variables. See the table below for more information. If AWM properties are referenced, values are resolved at runtime and preferably taken from the “previous tool” execution context pool, if available.

Variable references are only resolved by the following attributes:

  • Application Option "EXITPARM". See Application Options for more information.
  • Attributes "Static Value" and "Default Value" of the relationship "Tool has Input Parameter". See Relationship: Tool Has Input Parameter for more information.
  • Attribute "New Static Value" of the relationship "Parameter Override". See Parameter Override for more information.
  • Attribute "Name Physical" in "File Descriptor". See File Descriptor for more information.
  • Attribute "Value" in "Simple Enabled Condition". See Enabled/Visible Condition for more information.
  • Attribute "Value" of the relationship "Application Options Have Custom Attributes" for the attributes COMPOPT, AUTO_PARSE, and INITIAL_PARSE. See Relationship: Application Options Have Custom Attributes for more information.
  • Attribute "Concatenation" of the SYSLIB definition within the Micro Focus Background Parser function package.
  • Attribute "Label" of an Action Descriptor. See Action Descriptor for more information.
  • Attribute "Parmfile" used in the Master Configuration file. See Master Configuration for more information.
  • Attribute "Table View Id" in Action Descriptor and Element List Structure. See Action Descriptor and Element List Structure for more information.
  • Attribute "Table View Label" in Action Descriptor and Element List Structure.
  • Attribute "Default Value" in Property. See Property for more information.

  • Attributes "Title", "Description" and "Help Text" of modeled dialogs. See Open Modeled Dialog in the AWM function package for more information.

  • Open Modeled Dialogs Attributes "UI Category", "UI Form", "UI Help Text", "Label", "UI Tab", "UI Tool Tip" in modeled input dialogs. See Input Dialog in the AWM function package and Tool Has Input Parameter for more information.
  • Attribute "Message" of the AWM function package tool "Validate Value". Only the properties defined in the corresponding modeled dialog are available for resolution in this case.

References can be defined by using the Start Reference and End Reference symbols (default "&" and ".") which are defined in the application options. See Application Options for more information. It is possible to define a value containing several references as well as static characters. The following table shows the syntax of all variables that are available:

Variable/Syntax | Description | Example
%<env-var> | Reference to an environment variable on the client’s local operating system | &%PUBLIC. = C:\Users\Public
<property ID> | Reference to a property in the execution context | &PROP_WorkspaceFilename. = /MyProject/MyFile.txt
userid | Client’s user ID on the z/OS system. This variable can only be resolved if a connection to the mainframe has been established. | &userid. = USER123
wspath | Path of the active Eclipse Workspace on the client’s local machine | &wspath. = C:\workspaces\workspace1

Examples

The following examples show the definition of a dynamic file path:

Attribute value of "Name_Physical" (File Descriptor):

Reference | Resolved Value
&%PUBLIC.\MyCache\&PROP_FileName. | C:\Users\Public\MyCache\MyFile.txt
&userid..SOURCE(&PROP_Membername.) | USER123.SOURCE(MEMXYZ)
Parent topic: Data Model Details
Related information
Action Descriptor
Application Options
Element List Structure
Enabled/Visible Condition
File Descriptor
Input Dialog
Master Configuration
Parameter Override
Property
Relationship: Application Options Have Custom Attributes
Relationship: Tool Has Input Parameter


Tree View Label Determination

The label of a resource in the Application Explorer view is determined by the following hierarchy of rules:

  1. If within the Element Type has Property relationships there is at least one which has the Tree View Label attribute set to true, then all values of those attributes are taken as the tree label. If more than one Element Type has Property relationship have Tree View Label attributes set, then the values are concatenated using a minus character as a delimiter.
    Note: The order of concatenation is determined by the sequence of the relationship.
  2. The label decoration of the element type is taken from the text decoration defined for the element type.
  3. If the element type is a Linked Element Type the label is set in accordance to the label of the linked resource if this is supported by the Linked Element Type.
  4. If the element type is a Linked Element Type the label decoration is set in accordance to the linked resource if this is supported by the Linked Element Type.
  5. The first attribute within the Element Type has Property relationships of the Element Type which has the Element Name attribute set is used to define the label.
  6. The property values of the last modelled Element Type has Property relationship within Element Type is used as the label for the element type.
Parent topic: Data Model Details


Setting up the Application Workflow Model

  • The AWM Model Editor
  • Setting up and Configuring AWM
Parent topic: Workflow Manager Modeling Guide


The AWM Model Editor

The AWM Model Editor enables you to create and modify AWM XML models. The editor has the following features:

  • Object types and relationships are displayed and categorized in a tree structure.
  • Creation of object types and relationships are supported through the use of context menus, which allow you to preview modeling options.
  • A validation command recognizes both XML and semantic errors.
  • Attributes are categorized so that, for example, optional attributes are identified.
  • Values and references can be selected from drop-down lists.
  • Descriptions for all attributes are provided.
  • Editor commands, such as copy and paste, drag and drop, undo and redo, enable efficient work.

The following topics explain the use of the editor, starting from the creation of a new AWM model to the use of advanced editor commands:

  • Creating an AWM Model
  • Validating an AWM Model
  • Context Menu Actions in the AWM Model Editor
  • Edit Properties Command in the Context Menu
  • Modeling Function Package Features
  • Groups in the AWM Model Editor
  • Outline View for the AWM Model Editor
  • Relationship Hierarchy View for the AWM Model Editor
  • Drag & Drop Support in the AWM Model Editor
  • Navigation History in the AWM Model Editor
  • Search Function in the AWM Model Editor
Parent topic: Setting up the Application Workflow Model


Creating an AWM Model

To create an AWM Model:

  1. Launch Enterprise Developer. Specify a path for the Eclipse workspace when prompted.

    If this is the first time you start Eclipse, you now see the Eclipse Welcome page, click Open Team Developer Perspective.

  2. Click File > New > Project.

    This opens the New Project dialog box.

  3. Click General > Project, and then click Next.
  4. In the Project Name field, type Model Configuration.
  5. Click Finish.

    This creates an empty project.

  6. Right-click the project, and then click New > Other.

    This opens the New dialog box.

  7. Click AWM > AWM Model, and then click Next.
  8. In the File name field, type CONFIG.model.
  9. Click Finish.

    The CONFIG.model is displayed in the AWM Model editor.

The AWM Model editor shows all modeled types and relationships in a tree structure. You can view and edit the attributes in the Properties view. If the Properties view is not visible, right-click in the AWM Model editor, and then click Show Properties View. When editing an AWM model the editor view and the properties are closely linked. New AWM components are defined in the editor view by right-clicking an AWM component, and then clicking New Child or New Sibling. The attributes of the new component are displayed in the Properties view.

The first line in the Model editor represents the resource that is currently being worked on. You can display the next level of the hierarchy by clicking [image]. This displays the Document Root which is part of every AWM model. The Document Root stores global, non-configurable attribute definitions. Expand the next level in the hierarchy to display the AWM Model. The categories for all object types are defined here. When you are creating a model from scratch the model does not contain any categories at first. You start by defining all categories which you require in your model.

Categories are children of the AWM Model and are created using the context menu's New Child command. For example, to create the Properties category:

  1. Right-click AWM Model.
  2. Click New Child > Properties.

    This adds the Properties category as a child to the AWM Model.

You can add a Property to the Properties category:

  1. Right-click Properties.
  2. Click New Child > Property.

    This opens the New Object dialog box.

  3. In the New ID field, type SAMPLE_PROP_NewProperty.
  4. Click OK.

The attributes of the property are displayed in the Properties view:

Properties view for a selected property

You can modify the values of the attributes in the Value column. You are constrained to type or select values appropriate to the attribute.

You must specify the Special Property attribute. The default value is NONE, see Special Properties for more information.

You must specify the Type attribute. The default value is String, see Property for more information.

The Retrieve All Values attribute requires a reference to an action descriptor. The property is intended to define an action which references a tool to retrieve all valid values for this property. At this point no action descriptor has been defined so the reference to the action descriptor cannot be specified.

The Value Keys attribute enables you to specify multiple values. To specify multiple values:

  1. Click in the Value Keys Value column, and then click [image].

    This opens the Value Keys dialog box.

    Value Keys dialog box
  2. In the Value field, type One.
  3. Click Add.
  4. Repeat steps 2 through 3 for the values Two, Three, and Four.
  5. Click OK.

You can remove values by clicking Remove or change the order of the values by clicking Up or Down.

Some attributes have string values with multiple lines; these are marked with "multi line" in the tables in Tool descriptor, Relationship: Tool Has Input Parameter. Double-click an input field in the Properties view to open an Input dialog with a text area. In this field you can enter or edit a string with several lines.

When typing a value into a field, help text is displayed at the lower left of the Eclipse window. This is either a short description of the attribute or in the case of an incorrect entry, an error message. The value typed into the attribute fields are validated against expected attribute values. For example, typing characters into the Value Min Length field generates a format exception message as the field expects a number.

Help text for selected attributes

Long help messages can be truncated. If this happens, move the pointer over the text to display the message in full.

You can configure relationships and complex attributes. Both are children of the corresponding object types (for example, element type or tool descriptor) and are created by clicking New Child in the context menu. These are then modeled in the Properties view.

Relationships differ from other types in the editor through their presentation. Their Target ID is shown directly in the label. Any sequence numbers (Seq No) that occur are shown in their labels.

Labelling in the model editor

To delete an object type use the Delete command from its context menu. Deleting an object type removes all levels below it. If you delete something by mistake, it can be recovered using the undo command in the context menu of the Model editor.

Parent topic: The AWM Model Editor
Related information
Relationship: Tool Has Input Parameter
Tool Descriptor


Validating an AWM Model

You can validate the AWM model that is open in the editor to ensure that all mandatory entries, such as ID, Special Property, and Type comply with rules. Such as checking that the sequence numbers used for the input parameters of a tool are unique.

To validate the model:

  1. Right-click in the AWM Model editor.
  2. Click Validate.

    If you have not saved the current model it opens the Save All Modified Resources dialog box. Click OK.

Note: If you start the validation from the context menu it only validates the nodes below the point you start the validation.

Alternatively, click Icon - validate to validate the entire model.

If a modeling error is found, a Validation Problems dialog box is displayed. Click Details for more information on the errors found. The error is also displayed in the Problems view. Double-clicking the problem highlights the relevant location in the model editor.

Objects that are defined in the model but are not used generate a validation warning.

Parent topic: The AWM Model Editor


Context Menu Actions in the AWM Model Editor

The following table explains the most important context menu actions available in the AWM Model editor:

Command | Selected object | Description
New Child | Any object or relationship that can have children relationships. | Enables you to define a child relationship to an object.
New Sibling | Any object or relationship. | Enables you to define a sibling of the selected object or relationship on the same level.
Sort Children | Any category, for example, Action Descriptors and Properties. | Sorts the children of the selected object alphabetically including the XML source. This can be undone by clicking Edit > Undo .
Assign to Group | Any object below a category. | Enables you to group objects under a category.
Edit | Any object or relationship. | Opens a dialog box where the properties of the object or relationship can be modified. The dialog box mirrors the Properties view for the corresponding model object. You can modify properties for multiple model objects. Right-click the selected model objects, and then click Edit. See Edit Properties Command in the Context Menu for more information.
Jump To Target | Any relationship with a Target ID attribute, for example, Action has Tool and Tool has Input Parameter. | Highlights the target object in the editor.
Used By (n) where n is the number of referencing objects. | Any object that can be referenced, for example, Property and Tool Descriptor. | Opens the Used by dialog box. The dialog box displays all referencing objects and their parents. Double-click a row in the dialog box to highlight the object in the editor. Click OK to close the dialog box. This action does not appear in an object's context menu if there are no referencing objects.
Show Relationship Hierarchy | Any object or relationship, except groups. | Show the selected object or relationship as root object in the Relationship Hierarchy view. If the view is not already open, the view is opened.
Declare Function Package (type) where type is the selected class, for example, Property, ID Definition. | Any object that can be pre-defined by a function package. | Enables you to declare a manually created object to be a specific pre-defined feature. See Modeling Function Package Features for more information. The action is only visible, if at least one function package is defined which contains at least one unassigned declarable type which matches the selected type, for example, a Property.
Remove Function Package Declaration | Objects that are declared to be pre-defined by a function package. | Removes a specific function package declaration from a pre-defined or manually declared object. See Modeling Function Package Features for more information.

Model Editor Context Menu

You can collapse the active AWM Model tree to the categories level by clicking -.

In addition, the editor supports the following actions and their corresponding shortcut keys and mouse actions:

Model Editor Context Menu
Commands | Context (shortcut key) | Description
Delete | Context menu for all object types. (Ctrl + Del) | Removes the selected object types, including all subordinate elements.
Copy | Context menus including Properties view (Ctrl + C) | Copies object types and attribute values into the clipboard in order to insert them at another location using Paste.
Cut | Context menu for all object types (Ctrl + X) | Works in conjunction with Copy and Delete.
Paste | Context menus including Properties view (Ctrl + V) | Pastes a copied object type or an attribute value from the clipboard. This works only in locations where the value being inserted conforms semantically. For example, insert “Tool Descriptor has Input Parameter” in “Tool Descriptor“.
Undo | Model editor context menu (Ctrl + Z) | Reverses (Undoes) the last action. Repeated use of the function reverses earlier actions.
Redo | Model editor context menu (Ctrl + Y) | Restores an action that has been reversed (by Undo). Repeated use of this command restores earlier edit actions.
Drag and Drop | drag and drop | Enables you to move objects with the mouse. Click the object to be dragged, while holding the mouse button down, drag to the new location and release the mouse button.
Clone | (Ctrl + drag and drop) | Duplicates all of the source object's parameters. To clone an object press and hold Ctrl while dragging and dropping the object in the desired location.
Multiple Selections | (Ctrl + click) | Enables the simultaneous selection of several types of objects. Each object that is clicked on is added to the selection or if already selected, it is removed. Several selected objects can be copied, cut and paste, drag and dropped, deleted, and cloned.
Mass Selection | (Shift + click) | Selects all the objects between the current selection and the first object that was clicked. Supports multiple selections.
Save | Eclipse menu (Ctrl + S) | Saves the AWM Model.
Parent topic: The AWM Model Editor


Edit Properties Command in the Context Menu

You can open a dialog box displaying the objects' properties directly from the AWM model editor. Right-click on an AWM model object, and then click Edit to open a dialog box that displays the properties of the selected model object. The dialog box displays the same attributes displayed in the objects Properties view.

You can use the Edit command to modify multiple model objects as long as the objects selected have the same attribute values:

  1. Select multiple model objects.
  2. Right-click the selected objects, and then click Edit.
    This opens a dialog box for the objects' properties.
    Note: If the objects' attributes have common values then these are displayed. If the attributes have differing values for the same attribute then no value is displayed and you are unable to modify the value for this attribute.
  3. To change a value, double-click the corresponding value field, and then type the new value.
    Note: Once you have changed the value, the corresponding label is marked with an asterisk (*) to identify which attributes have been changed.
  4. Click OK.

    This applies the change to all the selected AWM model objects selected.

Parent topic: The AWM Model Editor


Modeling Function Package Features

You must define a function package in the model before you can use its tools.

A function package must implement the AWM model extension point so that it can be selected in the model editor.

A function package can be added to the model by right-clicking Function Packages, and then clicking New Child followed by the function package required:

Function Package 1

Alternatively, right-click Tool Descriptors, and then click New Child > Add Function Package. This opens the Create Function Package dialog box which displays the number of tools available in each package.

Function Package 2

Click the function package required, and then click OK. Once you have added a function package you can access the list of available tools, right-click Tool Descriptors, and then click New Child followed by the function package you require.

If the model already contains function packages, you can define linked element types, linked properties, or select tools from these function packages.

In order to select a function package tool, right-click Tool Descriptors, and then click New Child followed by the function package and the tool required.

The function package provider can define attributes for the function package which are shown in the Properties view when the function package is selected in the AWM model editor. See the individual function package description for more information.

Function package features can have references to other model objects like tool descriptor parameters or properties. Tool descriptor parameters are always automatically generated when a tool descriptor is created or changed. They can have specific conditions, so they are only created if certain tool attributes are set.

Other function package related features, like linked properties, linked element types, or tool descriptors can reference other model objects which require an ID to be defined before being created. Creating such a feature automatically opens an Enter Object IDs dialog box in which referenced object IDs can be specified. Objects marked with an asterisk (*) are mandatory for the creation of the default references.

Enter Object IDs Dialog Box

Once a referenced model object has been created by the function packages, other features of the package are able to automatically find and reuse it. For example, a linked element type and a linked property can reference the same property. Once any of the features have been defined, including the referenced property, defining other features automatically find and set the reference.

Function package declarations on model objects can be manually set or unset by using the Declare Function Package <type> and Remove Function Package Declaration context menu commands, see Context Menu Actions in the AWM Model Editor for more information. Normally, this is not required since the declaration is automatically set on defining the function package feature, but there are some scenarios where setting the declaration manually might be useful.

The most common scenario is maintaining a model that was created with an older version of AWM, in which the function package features were not able to reference other model objects. The model might already contain features of a function package. For example, linked properties which contain references to manually created objects, for example, resource identifier properties. By setting the correct function package declaration, the model editor automatically finds and reuses the property on newly created function package features referencing it.

Parent topic: The AWM Model Editor


Groups in the AWM Model Editor

To make it easier to see the organization of large models, the AWM Model editor enables you to group certain model objects. An example of object grouping is shown in the figure below:

Groups In Model Editor

You can create model editor groups for all model objects which have an ID attribute, for example, Action Descriptors, Properties, Tool Descriptors, and so on.

You can create a group by selecting one or more objects and clicking the Assign to Group action.

Groups In Model Editor 2

This opens the Assign to Group dialog box. You can specify a new group name or select an existing group.

To create a new model editor group:

  1. In the Group Name field, type a new group name.
  2. Click OK.

To merge the object into an existing group:

  1. In the Existing Groups list, click the group you want to assign the object to.
  2. Click OK.

Alternatively, you can assign objects to existing groups by dragging them onto the desired group. To assign items to a group, copy or cut and then paste. This opens an Enter ID dialog box, prompting you for a new object ID. When using cut and paste you are not required to change the original object ID.

Groups In Model Editor 3

Assigning objects to a group also works on objects which already belong to a group. You can assign objects from different groups, including ungrouped ones, to a single target group.

You can assign newly created model objects to existing groups by executing the corresponding New Child action on an existing group, or New Sibling on a grouped object.

Groups In Model Editor 4

To remove items from a group, right-click the group, and then click Remove from Group. Alternatively, drag them onto an ungrouped object of the same type.

Groups In Model Editor 5

When a group does not contain any more items it automatically disappears. Deleting a group removes all of the objects it contains.

You can rename a group, right-click the group, and then click Rename Group.

Note: AWM Models created in AWM versions 2.3 Update 1 or earlier may contain Tool Category objects. These are comparable to model editor groups, but could only be used for tool descriptors. Tool Categories are now deprecated, since they are not generic and have a negative impact on the model API. You can merge deprecated Tool Categories into model editor groups, click Model Editor > Convert Deprecated Model.
Parent topic: The AWM Model Editor


Outline View for the AWM Model Editor

The outline structure of an AWM model open in the editor is displayed in the Outline view. The Outline view displays AWM object types that are in the first level beneath the model categories. If AWM model objects are grouped in the editor then the groups are displayed in the Outline view.

By default, the following AWM categories are displayed in the Outline view:

  • Action Descriptors
  • Element Types
  • File Descriptors
  • Properties
  • Tool Descriptors

Other categories are filtered out of the outline to keep the view concise. You can change the categories displayed by clicking [image] View Menu, and then clicking the category required.

By default, the Outline view is not linked to the editor. This enables you to navigate through the Outline view without affecting your location in the AWM model editor. Double-clicking an object in the Outline view highlights the corresponding location in the editor.

To link the Outline view with the editor, click [image] View Menu, and then click Link with Editor.

Some editor actions are available from the Outline view. For example, it is possible to edit the properties or delete an AWM model object. Right-click the object in the Outline view, and then click the command required in the context menu.

You can drag and drop or copy & paste model objects from the Outline view to the model editor. For example, you can select several properties in the Outline view and drag and drop them into an element type object in the editor creating Element Type has Property relationships for the element type object.

Parent topic: The AWM Model Editor


Relationship Hierarchy View for the AWM Model Editor

The relationship hierarchy of an AWM model open in the AWM model editor can be displayed in the Relationship Hierarchy view.

The Relationship Hierarchy view helps you visualize the relationships of an object. You can configure the view to display either the object's children and its children references or the object's parents and its used by references.

To open the Relationship Hierarchy view :

  1. Open an AWM model in the AWM model editor.
  2. Right-click an AWM object, and then click Show Releationship Hierarchy. Alternatively, click an AWM object, and then press Ctrl+Alt+R.

    This opens the Relationship Hierarchy view displaying the relationships for the selected object.

To display an object's parent relationships in the Relationship Hierarchy view, click Show Parent Hierarchy ( Show Parent Hierarchy). To display an object's child relationships in the Relationship Hierarchy view, click Show Child Hierarchy ( [image]).

In the Relationship Hierarchy view, you can right-click an object and select one of the following commands:

Go to
Sets the object selection in the AWM model editor based on the object selection in the Relationship Hierarchy view. Double-clicking on an object in the Relationship Hierarchy view has the same result as Go to.
Show Relationship Hierarchy
The object selected is taken as the root object in the Relationship Hierarchy view.
Refresh
Refreshes the content of the Relationship Hierarchy view. This is required to synchronize changes made to objects in the model that are currently being displayed in the Relationship Hierarchy view.
Parent topic: The AWM Model Editor


Drag & Drop Support in the AWM Model Editor

The AWM model editor provides a comprehensive drag and drop support. The drag and drop support is available to the same extent as the copy and paste support.

You can use drag and drop to:

  • Copy model objects within the same AWM model.
  • Create object relationships within the same AWM model.
  • Copy model objects between different AWM models.

For example:

  • Changing the positions of objects in the model.
  • Moving or copying children between parents of the same type, such as moving "Element has Action" relationships from one element type to another.
  • Duplicating objects by dragging them onto their parent.
  • Creating "File Descriptor Has Property" relationships by dragging and dropping properties onto the file descriptor.
  • Merging two AWM models.
  • Copy Model Objects within the Same AWM Model
  • Create Object Relationships within the Same AWM model
  • Copy Model Objects between Different AWM Models
Parent topic: The AWM Model Editor


Copy Model Objects within the Same AWM Model

Objects and relationships can be moved and copied within an AWM model if the parents of source and target are of the same model object type.

See Context Menu Actions in the AWM Model Editor for an example and supported shortcuts for move and copy commands.

Parent topic: Drag & Drop Support in the AWM Model Editor


Create Object Relationships within the Same AWM model

In order to create relationships via drag and drop, dragged objects must be dropped on a target that supports relationships which refer to the source object(s) by a "Target ID" attribute. The relationship can be manually created using the context menu's New Child command.

Example:

Creating property relationships for a structured file descriptor:

Manual/Conventional Methods Using Drag and Drop or Copy and Paste
  1. Right-click on a File Descriptors File Descriptor, and then right-click New Child > Property.
  2. Click the new property, then the empty cell next to Target ID in the Properties view.
  3. Select the target property to be referenced in the Target ID list.
  4. Repeat these steps for all required properties.
  1. Select all of the required properties.
  2. Drag and drop or copy and paste the selection on the File Descriptor. See Figure 1.

    This opens the Create Relationships dialog box which displays a preview of the relationship to be created.

  3. Click OK.

    This adds the property to the File Descriptor.

Figure 1. Creating relationships via drag and drop
Creating relationships via drag & drop.

You can drag and drop relationships (containing a Target ID attribute), in which case the model editor uses the referenced objects of the selected relationships in the command. See Figure 2.

Figure 2. Creating relationships from other relationships
Creating relationships from other relationships

Dropping the selected relationships opens a Create Relationships dialog box. This displays the relationships to be created. If more than one relationship type is possible for the selected objects, the user is prompted to choose the type of relationships to be created. See Figure 3. The type can be chosen by clicking the corresponding option and then clicking OK.

Figure 3. Choosing relationship type
Choosing relationship type

For example:

  • Copying a tool descriptor and pasting it on an action descriptor creates a "has tool" relationship.
  • Dragging several "File Descriptor Has Property" relationships onto an element list structure creates "Element List Has Column" relationships.
  • Copying properties and pasting them on an "Execute OS Command" tool descriptor creates either a "Tool Has Input Parameter" or "Tool Has Output Parameter" relationships, depending on your choice.
  • Nothing happens if a tool descriptor is dragged onto an element type, since element types do not have direct relationships to tool descriptors.
Restriction: It is currently only possible to create parameter relationships on tool types which do not already have predefined parameters.
Parent topic: Drag & Drop Support in the AWM Model Editor


Copy Model Objects between Different AWM Models

The model editor features a copy mechanism that enables you to copy objects and all references from one model into another via drag and drop or copy and paste. It includes an Import dialog which displays potential conflicts in the target model and enables the selective copying of objects. To copy objects from one model into another, select the required objects and copy them using the context menu or press Ctrl+C and paste them anywhere in the target model.

Note: You cannot paste objects on to the resource object at the top of a target model.

You can use drag and drop to copy objects between models. To do this, both models need to be opened in the model editor. Both editors need to be visible at the same time. To achieve this, one editor must be dragged to the edge of the Eclipse editor area.

When both editors are positioned so they are visible, objects can be dragged and dropped from one model to the other.

Copy Model Objects 2

The import mechanism copies not only objects that were selected but all underlying objects including referenced objects. Copying the category "Tool Descriptors" copies all the containing tool descriptors, referenced properties and file descriptors (parameters), action descriptors (Job After Action) and so on. Copying an objects "Document Root" or "Model Configuration" results in the whole model being copied.

It is not possible to copy objects explicitly that do not have an ID attribute, for example, Application Options, relationships or ISA attributes.

Once a copy operation is initiated, all relationships and references are gathered and the Import dialog box opens. The Import dialog shows the dragged object(s) and all their references that are to be copied into the target model, in a table view. The table consists of two columns Before and After. The Before column indicates whether a copied object already exists in the target model. It contains the existing object from the target model or "---" if there is none. The After column always shows the copied objects and relationships from the source model.

If a copied object contains children, like relationships, it can be expanded in the table view. Attributes of objects and relationships can be seen by moving the mouse pointer over the specific object.

Objects that should not be copied or overwritten can be unchecked in the table view. The Import dialog box also uses certain typography to highlight possible conflicts:

Conflict | Description | Highlighting
No conflict | Copied object, relationship or attribute does not exist in target model. | Green
Identical object | The copied object already exists in the target model. | Normal
Change conflict | Copied object, relationship or attribute already exists in target model but with different attributes or children, for example, relationships of an object. | Blue
Remove conflict | Copied attribute/relationship exists in target model but is to be removed since the source object does not contain this attribute/relationship. | Crossed out

If an object already exists in the target model, the dialog shows both source and target objects compared. The mouse pointer can be placed over any object or relationship to display the attributes of that object.

Copy Model Objects 3

Copy Model Objects 4

In the Import dialog box above, a file descriptor is copied from one model into another. The dialog highlights that the file descriptor FILE_DatasetList and the property PROP_DatasetName already exist in the target model but with different attributes. The property PROP_Suffix does not exist in the target model, click OK to continue the import. Other identical and existing objects are hidden because the Identical filter is checked.

Parent topic: Drag & Drop Support in the AWM Model Editor


Navigation History in the AWM Model Editor

The AWM model editor records your navigation history as you move and edit within the model editor. You can move backwards and forwards through your navigation history. Each point in your history corresponds to a position in the editor at a particular time. To move backwards through your navigation history, click Navigate Backward. Alternatively, press Alt+Left. To move forward through your navigation history, click Navigate Forward. Alternatively, press Alt+Right.

The navigation history records the location arrived at when using the Outline view as well as movement between multiple model editors. Moving through your navigation history can restore your location in a previously closed model editor by reopening the model in a new editor.

Parent topic: The AWM Model Editor


Search Function in the AWM Model Editor

The model editor contains a built-in search function which can be used to find specific objects or attribute values within a model.

To run a search query on an open model:

  1. Click Edit > Find/Replace. Alternatively, press Ctrl + F or click Icon - Search in the Eclipse toolbar.

    This opens the Model Editor Search dialog box.

    Model search dialog
  2. In the Search String field, type the string to search for.
  3. Click OK.

See the table below for a description of all available search options and examples:

Search field or option | Description | Example
Search String Searches the model for a value which contains the specified text. Asterisks can be used for wildcard searches.
Note: Searching for "Env*" is a more restrictive search string than "Env", since "Env" is the same as "*Env*".
To find attribute values which contain "Env":
  1. In the Search String field, type Env.
  2. Click OK.

To find attribute values which start with "Env":

  1. In the Search String field, type Env*.
  2. Click OK.

To find attributes which contain references, for example "&Prop_Name":

  1. In the Search String field, type *&*.*.
  2. Click OK.
Case sensitive | Whether the search should be case sensitive. | Self-explanatory.
Search Scope Whether the whole model or only selected categories or objects, including all their underlying objects, should be searched. To only search within Element Types and Properties:
  1. Highlight the Element Types and Properties categories in the model.
  2. In the Search Scope group, click Editor Selection.

To only search within the Tool Descriptors category and its underlying objects:

  1. Highlight the Tool Descriptors category in the model.
  2. In the Search Scope group, click Editor Selection.
Search in Attributes and Relationships When unchecked, it limits the search within object IDs. When checked, it searches within all objects and attributes. To find objects which contain "System" in their ID:
  1. In the Search String field, type System.
  2. In the Advanced group, uncheck Search in Attributes and Relationships.
  3. Click OK.

To find any attribute value which contains "System":

  1. In the Search String field, type System.
  2. In the Advanced group, check Search in Attributes and Relationships.
  3. Click OK.
Attribute Filter Searches within specific attributes. If empty, all attributes are searched. Content assist is available in the Attribute Filter field, press Ctrl + Space to display a list of all the available attributes based on the letters typed.

Several attributes can be specified by using a semicolon (;) as a separator.

To search for all "Static Value" and "Default Value" attributes:
  1. In the Search String field, type *.
  2. In the Attribute Filter field, type staticValue; defaultValue.
  3. Click OK.

To search for a Mass Processing actions:

  1. In the Search String field, type true.
  2. In the Attribute Filter field, type massProcessing.
  3. Click OK.

When you click OK in the Model Editor Search dialog box, the Search view is opened and is populated with the search results.

Double-clicking a match within the search view highlights the corresponding object in the opened model editor.

To copy the search results, highlight one or several matches in the Search view, right-click, and then click Copy Text. The copied text is now available in your clipboard, in CSV format.

Parent topic: The AWM Model Editor


Setting up and Configuring AWM

  • Loading an AWM Application
  • Master Configuration
  • AWM Custom System
  • Defining Default Configurations
  • Micro Focus z/Server Connection Type
  • AWM Support for Enterprise Developer Editors
Parent topic: Setting up the Application Workflow Model


Loading an AWM Application

AWM applications are loaded from the Application Explorer view.

There are two ways an AWM application can be displayed in the Application Explorer view:

  1. As part of an AWM system which uses a Master Configuration file.
  2. As part of an AWM Custom System.

When working in a production environment, Micro Focus recommends that you load an AWM model that uses a master configuration. See Master Configuration for more information. It is best practice to manage your master configuration from a central location. It contains a list of applications to be displayed in the Application Explorer view for a particular AWM system.

When your AWM application is still in the development and test phase, Micro Focus recommends that you load the AWM application without a master configuration in an AWM Custom System. An AWM Custom System enables you to modify the AWM model and reload the resulting modified application. See AWM Custom System for more information.

Parent topic: Setting up and Configuring AWM


Master Configuration

Master configurations are files which define AWM systems with available modeled AWM applications. A successfully parsed master configuration creates an AWM system in the Application Explorer view.

In addition, the master configuration file stores the following information about each application:
  • The logical name of the application.
  • Reference to the central storage location for the AWM model.
  • The version of the current AWM model.
  • Locally cached data that is to be deleted when the AWM model is updated.
  • Static property values.
  • Optionally, the restriction to specific USERIDs which are allowed to access a modeled application.

The version number in the master configuration is used to control model updates for all users of the configuration. As long as this version number is equal to the cached AWM model in a client’s Eclipse workspace, AWM does not update loaded applications. The master configuration is automatically checked to determine if a new model version is available. Due to performance implications, this is done once per session and master configuration, as soon as a user executes any action of a non-checked AWM application.

When working in a production environment, Micro Focus recommends that you load an AWM model that uses a master configuration.

  • Master Configuration on z/OS
  • Local Master Configuration
Parent topic: Setting up and Configuring AWM


Master Configuration on z/OS

Note: This feature is only supported if EDc, EDz or IDz is installed.

If a z/OS system is attached to AWM, the master configuration file is read by a REXX procedure that must be located under the SYSEXEC or SYSPROC allocation. The name of this REXX procedure is TAUZCAPP.

Note: If AWM is used in IDz with an IBM RSED connection type, the name of the REXX procedure is TAULAPPL, instead of TAUZCAPP.

If you attache a new remote system to the Tree view, the new system entry receives the remote system name returned from the master configuration file. The called REXX procedure updates all AWM model entries which are listed in the master configuration file. At this time a specific AWM model is not loaded.

This REXX procedure is called each time you perform an action for the first time during an Eclipse session that requires a link to the remote system. The following checks are performed when the REXX procedure is called:

  • The REXX procedure can be located.

    Could the REXX procedure be located on the remote system. If not, the action is cancelled, producing an error message.

  • The master configuration file is present and consistent.

    The REXX procedure checks the consistency of the master configuration file. If any error occurs it is communicated in an error dialog. Warnings are written into the Eclipse .log file.

The data set name of the master configuration file is specified in TAUZCAPP respectively TAULAPPL. The REXX procedure used with the server installation (REXX TAUZCAPP with a z/Server installation, REXX TAULAPPL with a RSED installation) has to be adapted after the z/Server installation, otherwise the mainframe server is not able to find the master configuration file. See the z/Server Installation Guide for more information.

Parent topic: Master Configuration
Related information
Validate Action


Local Master Configuration

If you do not want users to have a mainframe connection when working with the Workflow Manager, they can use a local master configuration file or default configuration.

A local master configuration file can either be located in the Eclipse root folder with the name MasterConfig.xml or MasterConfig.txt depending on its format. See Master configuration syntax for more information. Alternatively, a master configuration file can be returned by a local operating system command. See Master Configuration for more information. In this case, a local system reference can be created in the Application Explorer view:

  1. Right-click in the Application Explorer view, and then click Add System.

    This opens the Add System(s) dialog box.

  2. Select the Local System entry.
  3. Click OK.

Expanded the local system reference to view all the applications defined in the local master configuration file.

If any application of a local system reference contains mainframe-dependent actions, or the model of one of the applications is stored on the mainframe, you must add the mainframe connection to the local system reference, by right-clicking the local system reference, and then click Associate Remote System, see the figure below:

Associating a remote system to a local system reference

After you have associated the remote system, the label of the local system reference changes and the Properties view shows properties of the selected remote system. The context menu now shows the Remove Associated Remote System command. A local system reference with an associated remote system acts like a remote system reference, except the local master configuration is not provided via the mainframe.

Master configuration syntax

The master configuration can be defined in one of two supported formats: flat format and XML. Both formats use the same keywords. The table below lists all available keywords and their descriptions.

The XML format is currently only supported by local system references, meaning that master configuration files located on the mainframe must be defined in flat format.

The flat format master configuration consists of lines with keywords, together with the respective values. The keywords are separated from the values by a colon and at least one space.

For example, a row in the master configuration file might look like this:

System: System_name

Lines beginning with an asterisk (*) are interpreted as comments.

Flat format | XML format | Description
System | <System> | Name and identifier of the remote system as it is displayed in the Tree view. It is used as a unique identifier for caching application data, so changing the name in a productive system is not recommended.
Appl | <Appl> | Name and identifier of the modeled application as it is displayed in the Tree view.
Conf | <Appl conf="…"/> | Platform, path and name of the model file.
Version | <Appl version="…"/> | Version of the model file.
INFO | <Appl info="…"/> | Optional. Information about the data that is deleted for consistency in the Eclipse Workspace when loading a new version of the model.
User | <Appl user="…"/> | Limits the corresponding application(s) to one or more RACF users. Multiple users can be separated with spaces.
Property: <Property ID>=<Value> | <Property propertyID="…" value="…"/> | Static property values for an application.
EndUser | Not required | End of a user limitation.
EndAppl | </Appl> | End of an application description.
Parmfile | Not required | Optional - This is the name of the remote parameter file that is used to transfer long parameters between the client and the remote system when executing remote commands. The name may contain property references. If the parmfile option is not specified, the standard name of the parameter file is <userid>.TAURUS.PARMFILE.

Any number of modeled applications can be listed for a system. The master configuration file must have at least one application defined.

The Conf entry consists of the specification of the platform together with the platform-dependent fully-qualified or absolute file name. Permissible platform designations are local and mvs.

Examples of correct Conf data:
  • mvs:'hlq.MODEL.XML(MYCONF)'

  • local:c:\config\config.xml (Windows)

The INFO entry determines which persistent information held in the Eclipse workspace have to be deleted in the case of a version change of the modeled application. Permitted information are filters and elements. The information can be combined in any way.

INFO entry | Deleted files | Content of the files
filters | ft_filters.xml | All filters in the application
elements | et_elements.xml eb_elementsinlists.xml li_<listid> lm_Element_Lists.xml | All cached elements that are assigned to the application and all element lists in the application

For example, a master configuration file in XML format:

<?xml version="1.0" encoding="UTF-8"?>
<System name="My Local System">
<Appl name="My Application" conf="local:C:\Models\MyApplication.model" version="1.0" info="">
<Property propertyID="PROP_UserRole" value="ADMIN" />
<Property propertyID="PROP_Environment" value="TEST" />
</Appl>
<Appl name="SCLM Application" conf="MVS:HLQ.APPLS.MODELS(SCLMPROD)"
version="2.1" info="" />
</System>

For example, a master configuration file in flat format:

System: My System
*
* PDS EXPLORER EXAMPLE APPLICATION
*
User:
* application name
Appl : PDS Explorer
* location of the application configuration file
Conf : mvs:'hlq.ZSERVER.XML(PDSECONF)'
* application version number
Version: 1.1
* process information

Master configuration from OS command

A local master configuration can be returned dynamically by an operating system command. The command, which could, for instance, execute a script file to return the configuration, must be specified with the "teamdeveloper.masterconfig" Java system variable. See Setting Java System Variables for more information.

The value of the variable must contain an operating system command, which returns a complete master configuration file in XML format to standard out when executed.

For example (Windows):

  • cmd.exe /c type %HOMEDRIVE%%HOMEPATH%\\localmasterconfig.xml
  • cmd.exe /c H:\batfiles\MasterConfiguration.bat
Parent topic: Master Configuration
Related information
Master Configuration
Setting Java System Variables


AWM Custom System

A Custom System enables you to dynamically add any AWM application to the Application Explorer view.

Micro Focus recommends that you load an AWM application from a Custom System during the applications development and testing phase. The only prerequisite for doing this is that the AWM model defining the application is located in a project within the IDE's workspace.

The whole application change workflow, which includes, load, edit, change, and reload, is directly supported from the context menu of the application under the Custom System.

You can create a Custom System in two ways:

  1. Right-click in the Application Explorer view, and then click Add System(s).
  2. Right-click an existing AWM model, and then click Load Model.

Once you have created a system you can add an AWM application from the system context menu.

This enables you to:

  • Add an AWM application from an existing model.
  • Set application property values for modeled application properties.
  • Create a new empty AWM application.
  • Create a new AWM application from a selection of templates.

Once the application has been added to the Custom System it can be opened for editing.

Making changes to a loaded model requires you to reload the corresponding application. To reload the application, right-click the application, and then click Reload Application. If a model associated with a Custom System has changed and the application has not been reloaded then this is indicated by an asterisk (*) at the end of the application name.

To create a Custom System:

  1. Right-click in the Application Explorer view, and then click Add System(s).

    This opens the Add System(s) dialog box.

  2. Click Custom System in the Name column.
  3. Click OK.

    This opens the New Custom AWM System dialog box.

  4. In the System Name field, type a descriptive system name.
    • Optionally, to add an AWM application, click Next:
      1. In the Model Location field, type the absolute path to the model, or click Browse to use the Select Model dialog to select the location.
      2. In the Application Name field, type the name to be used.
  5. Click Finish.

You can use models with mainframe functions. To do this, associate a remote system to a custom AWM system. You will require a Micro Focus z/Server connection to be specified in the Remote System view.

Parent topic: Setting up and Configuring AWM


Defining Default Configurations

To initiate new Eclipse workspaces with specific configurations, you can define default configurations in an XML file. The following configuration types can be defined within this file:

  • Remote system connections.
    • Including MVS and JES filters for z/Server connections.
  • File mappings.
  • AWM systems.

The default configurations file is only read once per workspace. Modifications to the file do not affect existing workspaces with default configurations applied.

You can add a default configurations file to an existing workspace, but only if default configurations have never been defined in that workspace before.

  • Integrated Enterprise Development Project Application
  • Customizing the Integrated Enterprise Developer Project Model
  • Default Configurations File Location
  • Setting Java System Variables
  • Default Configurations File Syntax
Parent topic: Setting up and Configuring AWM


Integrated Enterprise Development Project Application

The Enterprise Developer IDE provides an integrated AWM application supporting the standard Micro Focus project functions. It provides you with the ability to work in the context of Micro Focus COBOL or PL/I projects, for example, for editing, compiling, or debugging programs.

The application is part of the "Enterprise Developer System", which is automatically added to the Application Explorer view in new Eclipse workspaces. See the figure below:

If the Enterprise Developer system does not appear in the tree view (if, for instance, it was deleted by a user), it can be added by using the Add System(s) dialog:

Parent topic: Defining Default Configurations


Customizing the Integrated Enterprise Developer Project Model

The integrated Enterprise Developer System is intended to reliably offer standard Enterprise Developer functions and therefore cannot be modified. The integrated Enterprise Developer Project Model can be used as a copy base for customization.

After this standard model has been loaded once, it is located under \InternalTDProject\IntegratedEDModel.model.

Note: Every time the integrated Enterprise Developer Project model is loaded, the model file \InternalTDProject\IntegratedEDModel.model is replaced. This model must be copied to another location before being modified.

To load the customized model, you must define another AWM system, see Master Configuration for more information. Ideally the custom AWM system should be defined within a default configuration, see Defining Default Configurations for more information. This can be configured to automatically load the customized application in a new workspaces.

Parent topic: Defining Default Configurations
Related information
Defining Default Configurations
Master Configuration


Default Configurations File Location

AWM attempts to parse the file in one of these locations:

  • <Eclipse root folder>\DefaultConfigurations.xml
  • The path specified in the Java VM argument teamdeveloper.defaultConfigurationsPath

Use one of the following methods to set the Java VM argument:

  • With the -D parameter in the <Eclipse root folder>\eclipse.ini file under -vmargs. For example:
    -vmargs -Dteamdeveloper.defaultConfigurationsPath=C:\default_configs.xml
  • Setting the argument in the mfeclipse.ini file in Enterprise Developer. For example:
    teamdeveloper.defaultConfigurationsPath=C:/default_configs.xml
    Note: The value must be a valid Java string when using mfeclipse.ini. Since \ is an escape character, you can use either \\ or / for file path separators. You can create the mfeclipse.ini file if it does not exist.
Note: If you want to change the default configuration file to adapt it to site specific standards, you should copy it to its own path and set this path in the Java VM argument teamdeveloper.defaultConfigurationsPath. Otherwise the file might be overwritten with the next Enterprise Developer installation.
Parent topic: Defining Default Configurations
Related information
Setting Java System Variables


Setting Java System Variables

Some Enterprise Developer functions rely on specific parameters that can be specified by setting Java system variables, which are simple key-value pairs.

These variables can generally be set in two different ways:

  • By using the "-D" Java virtual machine (JVM) argument on start up. As all JVM arguments, the parameter must be defined under "-vmargs" and has the following syntax:
    • -DmyVariable=myValue

    These arguments can be configured, for example, in the <Eclipse-root-folder>\eclipse.ini file.

    Example:

    -vmargs -Dteamdeveloper.defaultConfigurationsPath=C:\default_configs.xml
  • By using the System.setProperty(…) Java method at runtime.

Enterprise Developer supports an additional way to define Java system variables by parsing the <Eclipse-root-folder>\mfeclipse.ini when started. Variables are simply defined by key value pairs.

Example:

teamdeveloper.defaultConfigurationsPath=C:/default_configs.xml
Note: The value must be a valid Java string when using the mfeclipse.ini file. Since "\" is an escape character, either "\\" or "/" can be used for file path separators. If the file mfeclipse.ini does not exist, it can be created manually.
Parent topic: Defining Default Configurations


Default Configurations File Syntax

The default configurations XML file's root element must always be <defaultConfigurations/>. After that, any configuration type can follow in any order.

To define the default configurations XML file, click File > New > Other. In the New dialog box, click AWM > Default Configurations File.

This adds the XML schema definition to the file, which enables validation and context assist in Eclipse XML editors.

  • Remote System Connections
  • z/Explorer File Mappings
  • Default AWM Systems
  • Default Configuration Extensibility
Parent topic: Defining Default Configurations


Remote System Connections

Default remote system connections are not limited to z/Server connections. Theoretically all system types using the Eclipse Remote System Explorer framework (RSE) can be defined. But in practice, specific remote system connections require additional attributes to work properly.

Syntax

Element | Attribute | Description
remoteSystemConnection | systemTypeID* | The ID of the remote system type. The ID for z/Server connections is com.microfocus.awm.zos
connectionName* | The unique name of the connection as seen in the Remote Systems view.
hostName* | The host name of the connection.
port* | The server port.
defaultUserID | The default user ID that is used when a connection is being established. This can be changed in the credentials dialog box.
description | The description for the remote system connection.
remoteCodePage (z/Server only) | The remote code page that should be used for communication.
ceaPort (z/Server only) | Port of the CEA server task.
filter (z/Server only) | filterString* | The filter string. Note that %userid% can be used which is resolved at run time with the ID of the connected user.
type* The filter type. Valid values are:
  • mvs
  • jes
filterName* | The name of the filter as shown in the Remote Systems view.

Example

<defaultConfigurations>
    <remoteSystemConnection connectionName="zServer"
        systemTypeID="com.microfocus.awm.zos" hostName="MYCOMPANY.ZSERVER"
        port="1111" remoteCodePage="IBM037" defaultUserID="MYUID"
        description="z/Server production environment" ceaPort="2222">
        <filter name="My Files" type="mvs">
            <filterString string="%userid%.**" />
        </filter>
        <filter name="My Jobs" type="jes">
            <filterString string="%userid%.*" />
        </filter>
        <filter name="AWM Models" type="mvs">
            <filterString string="AWM.MODELS.XML" />
            <filterString string="MYUID.AWM.XML" />
        </filter>
    </remoteSystemConnection>
</defaultConfigurations>
Parent topic: Default Configurations File Syntax


z/Explorer File Mappings

There is an entry in the default configuration XML file to define file mappings, these are mappings between generic remote file names and the suffix which is used on the client-side. Among other things, the suffix on the client-side defines which editor is used to open the file.

Syntax:

Element | Attribute | Description
fileMappings* | Main element for all file mappings.
fileMapping genericName* The generic z/OS file name pattern this mapping should apply for.
Examples:
  • *.CBL
  • MYUSER.*XML
  • *.LOAD.*
suffix* The suffix (without the dot) that should be given to files which match the generic name pattern.
Examples:
  • cbl
  • xml
  • model
type The type of file the generic name should be matched with. Valid values include:
  • dataset (default)
  • member
remoteCodePage The code page that should be used for editing files that match the generic name pattern. Do not define this attribute if the code page from the remote system connection should be used.
Examples:
  • IBM037
  • IBM01141

localCodePage The code page of the encoded local file.
transferMode | How the file should be transferred when read or copied. Currently only the value Text is supported.

Example:

<defaultConfigurations>
    <fileMappings>
        <fileMapping genericName="*.XML" suffix="xml"
                     remoteCodePage="IBM037"/>
        <fileMapping genericName="COB*" suffix="cbl" type="member"/>
    </fileMappings>
</defaultConfigurations>
Parent topic: Default Configurations File Syntax


Default AWM Systems

Default AWM systems are automatically added to the Application Explorer view in newly created workspaces. They must either point to a master configuration file or contain a command which returns a master configuration, see Master Configuration for more information. Optionally, default AWM systems can be defined with a remote system association and an application that is loaded by default, see Local Master Configuration for more information.

Default AWM systems can be added at any time, right-click in the Application Explorer view, the then click Add System(s).

Element | Attribute | Description
awmSystem |  | Represents one default AWM system.
 | masterConfigurationPath* | Path to a master configuration file. Depending on the master configuration format, the file suffix must be either xml or txt. Must be defined only if no masterConfigurationCommand has been specified.
 | masterConfigurationCommand* | Operating system command string which returns a complete master configuration. Only supports the XML format. Must only be defined if no masterConfigurationPath has been specified.
 | loadedApplication | Name of the AWM application to be loaded by default. The application must be contained in the referenced master configuration. Only one AWM application can be loaded at a time. By default, the first application referenced is loaded, others are ignored.
 | associatedRemoteSystem | Name of the associated remote system, if any.

Example (Windows):

<awmSystem associatedRemoteSystem="zServer" loadedApplication="AWM Sample Model" masterConfigurationPath="F:\Models\SampleModel.xml"/> </awmSystem>

 <awmSystem masterConfigurationCommand="cmd.exe /c type F:\Models\SampleModel.xml"/>
Parent topic: Default Configurations File Syntax
Related information
Local Master Configuration
Master Configuration


Default Configuration Extensibility

The XML schema of the default configurations file is not restrictive, which means that any additional XML elements can be added to the file without causing syntax errors. AWM will simply ignore those elements, but it is possible to interpret these by implementing a plug-in and using the AWM API. The class which reads the default configurations file is part of the plug-in com.microfocus.awm and is called “DefaultConfigurationsReader”.

Parent topic: Default Configurations File Syntax


Micro Focus z/Server Connection Type

AWM provides its own z/OS connection type within the Eclipse Remote Systems view. The connection type is called Micro Focus z/Server.

The entry created in the Remote System view by a Micro Focus z/Server connection type is called zExplorer.

Note: The zExplorer is only available if a connection to the z/Server can be established. This is supported with EDz, EDc and IDz.

The zExplorer provides basic functions to access the z/OS MVS and USS file systems as well as batch jobs and tasks managed by JES2 and JES3.

The zExplorer includes:

  • MVS Explorer
  • USS Explorer
  • JES Explorer

Cross-system support for copying files between local and remote systems is available.

The zExplorer is located in the Remote Systems view, and can be used after adding a Micro Focus z/Server connection.

The zExplorer within the Remote Systems View
Parent topic: Setting up and Configuring AWM


AWM Support for Enterprise Developer Editors

Some AWM features are designed for special use within the Enterprise Developer editors for COBOL, PL/I or JCL:

  • Application-specific attributes SYSLIB, COMPOPT, and PROCLIB
  • Reparse With Refresh tool of the Micro Focus Editor function package
  • Mainframe precompiler support
  • Application Specific Attributes for Editor Support
  • Reparse With Refresh Tool
  • Mainframe Pre-compiler Support
Parent topic: Setting up and Configuring AWM


Application Specific Attributes for Editor Support

The following application specific attributes can be defined in an AWM model for special use in the Enterprise Developer COBOL or PL/I editor in remote edit scenarios within an AWM model based application.

The background parse process of the editors makes use of these specific attributes:

Attribute | Meaning
SYSLIB | A list of local path information and MVS data set names which are used by the editor's background parse process as search paths for COBOL copybooks or PL/I includes.
PROCLIB | A list of MVS data sets which are used by the editor's background parse process as search paths for JCL includes.
COMPOPT | A list of Micro Focus compiler directives to use when background parsing a COBOL or PL/I program opened in the editor. Default value for COBOL is DIALECT(ENTCOBOL) CICSECM XDB(NOVALIDATE) EXECDLI NOP64 Default value for PL/I is -margins 1,72 -cics
AUTO_PARSE | Controls whether the background parse process of the editor is started automatically or explicitly called. Any value other than "true" (in any combination of upper and lowercase letters) will prevent the automatic reparsing of downloaded programs after they have been changed. You can activate the reparsing manually by modelling the "Reparse With Refresh" tool from the Micro Focus Editor function package. Default value: true
INITIAL_PARSE | Controls whether the background parse process of the editor is started when a file is opened in the editor. Default value: false

These properties can contain a reference to an AWM property which can be used as an output parameter by an AWM tool. You can use this to dynamically define a copybook search path or compiler options at run time, before a program is opened in the editor.

The following fixed named properties can be used to replace the application-specific attributes:

Attribute | Fixed named property
COMPOPT | MFProp_RemoteSyntaxCheckOptions for COBOL programs MFProp_RemotePLISyntaxCheckOptions for PL/I programs

If the application-specific attribute is defined, it has a higher priority.

Parent topic: AWM Support for Enterprise Developer Editors


Reparse With Refresh Tool

The "Reparse With Refresh" tool should be defined as part of an AWM editor action. It can be used in the COBOL or PL/I editor to explicitly trigger a refresh of the copybooks and includes, contained in the edited COBOL or PL/I program respectively.

Parent topic: AWM Support for Enterprise Developer Editors


Mainframe Pre-compiler Support

Note: The Mainframe Pre-compiler Support is available for COBOL only.

It can only be used in conjunction with an AWM modeled remote edit action. See Edit MVS File and Browse MVS File in the AWM function package for more information. There is no support for COBOL programs opened from MVS Explorer in the Mainframe Systems Explorer view.

The Mainframe Pre-compiler Support enables you to call language pre-compilers (also known as pre-compilers) on the mainframe while editing a source file on the client machine. The source file is taken from the editor and pre-compiled on the mainframe. The result is transferred back to the client machine and used as input to the background parsing process, so the editor does not flag syntax errors due to an unknown pre-compiler. You can use all COBOL variables with the Content Assist.

To use the Mainframe Pre-compiler Support, additional configuration is necessary.

Configuring Mainframe Pre-compiler Support on the Mainframe

A mainframe pre-compiler must be configured on the mainframe to be used with the Mainframe Pre-compiler Support. A pre-compiler specific REXX procedure must be written on the mainframe to connect a pre-compiler. That procedure has to set up the required environment for the pre-compiler. For example, by allocating data sets and then call the pre-compiler.

Configuring Mainframe Pre-compiler Support in the Eclipse Client

The Mainframe Pre-compiler Support needs a server instance to be started in the Eclipse client. By default, the server instance is started when the corresponding plug-in is loaded during Eclipse startup under port 2666.

The default port can be changed by specifying a new value for the Eclipse property variable remotePreprocessorPort in the eclipse.ini file under the vmargs section.

For example, to change the port address to 5555, specify:

-DremotePreprocessorPort=5555

If you do not want to make use of the Mainframe Pre-compiler Support in the Eclipse environment you can configure the server not to start under the Eclipse preferences. To prevent the plug-in from activating on startup:

  1. Click Windows > Preferences > General > Startup and Shutdown.
  2. Click AWM Remote Preprocessor.
  3. Click Apply and Close.

Mainframe Pre-compiler Exit Procedure TAUZCXPP

The pre-compiler exit procedure has to be named TAUZCXPP and must be placed on a library that is in the search path in the user server. TAUZCXPP is called with the following parameters:

Parameter | Description
Indsn | Data set name of a cataloged mainframe file containing the input source for the pre-compiler. This is the content of the editor on the client machine when the background parse process is started.
Outdsn | Data set name of a cataloged mainframe file for the output generated by the pre-compiler. This is the translation of the input file as done by the pre-compiler and must be valid COBOL.
Msgdsn | Data set name of a cataloged mainframe file for messages generated by the pre-compiler.
Chgdsn | Data set name of a cataloged mainframe file for information about changes done by the pre-compiler.
Parms | Additional user supplied parameters for the pre-compiler call.

All data sets exist in the mainframe file system when the procedure is called. The procedure must allocate the input and output data sets to the pre-compiler specific DD names. The message and change data sets are optional and need to have a special format as described in the following sections.

The following return codes of TAUZCXPP are supported:

Return code | Description
0 | Changes done by the pre-compiler are known and the change data set is filled.
1 | Changes done by the pre-compiler are unknown and TAUZCXPP did not fill the change data set.

If return code 1 is received, the mainframe pre-compiler interface attempts to set up a change data set by comparing the input data with the output data. A TAUZCXPP might generate the output data set and issue return code 1. In this case, the comparison of the input and output file is done in the REXX procedure TAUZCCMP via the IBM ISPF tool ISRSUPC.

Note: TAUZCCMP has only been tested with ISPF version 7.2. In another ISPF version the output of ISRSUPC might differ, generating unpredictable results. In this case, the customer has two alternatives:
  • Adapt the REXX procedure TAUZCCMP to the actual output of ISRSUPC.
  • Generating the change data set according to the format described below.

Message Data Set Format

Messages from a pre-compiler must be placed in the message data set. The data set is a fixed block data set with a logical record length of 80. It is already cataloged when TAUZCXPP is called.

There must be one line for each message:

Offset | Length | Description
0 | 5 | Number of the line in the input source that this message belongs to (right padded filled with 0).
5 1 Message level:
I
Informational
W
Warning
E
Error
S
Severe error
6 | 74 | Message text.

Changes Data Set Format

The local compiler needs to identify which lines of the original source code were changed, inserted, or deleted by the mainframe pre-compiler. This information may be calculated using the Mainframe Pre-compiler Interface by issuing return code 1 from the exit TAUZCXPP, or may be set by TAUZCXPP itself. The data set is a fixed block data set with a logical record length of 80. It is already cataloged when the exit TAUZCXPP is called.

Changes can be grouped into blocks so that, for example, deleting five consecutive lines is a block of five lines.

There must be one line for each change block:

Offset | Length | Description
0 | 5 | Number of the line in the input source that this change belongs to (right padded filled with 0).
5 | 1 | Reserved (should be blank)
6 1 Type of change
I
Inserted lines
D
Deleted lines
C
Changed (reformatted) lines
7 | 1 | Reserved (should be blank).
8 | 5 | Length of the change block (right padded and filled with 0).
13 | 67 | Reserved (should be blank).

Configuring Mainframe Pre-compiler Integration on the Client Machine

COBOL compiler options can be set in an AWM model by the AWM application specific attribute COMPOPT.

In order to integrate a mainframe pre-compiler, the COMPOPT attribute must contain the call of the local pre-compiler interface:

p(AWMREMPC) ENDP

After p(AWMREMPC) all parameters can be passed which are needed by the mainframe pre-compiler. The parameters are passed through to the mainframe pre-compiler exit.

The integration of the mainframe pre-compiler is realized on the client side as a stackable preprocessor implementing the integrated preprocessor interface as described under "Writing a Preprocessor". Micro Focus recommends you use the standard CP preprocessor as the first preprocessor in the stack. This is because the CP preprocessor ensures that the contents of unsaved edit buffers is retrieved and passed to the succeeding preprocessors. If you require the mainframe pre-compiler integration gets the source from the edit buffers in an unchanged way the CP preprocessor has to be called with the parameters NOSQL NOCOPY. Otherwise the CP preproessor resolves all COPY and EXEC SQL INCLUDE statements in the source before passing the source to the mainframe pre-compiler integration. The COMPOPT attribute typically has the following format:

p(AWMREMPC)  p(CP) NOCOPY NOSQL ENDP

You need to specify all the parameters to be passed to the mainframe pre-compiler exit between p(AWMREMPC) and p(CP).

Another AWM application-specific attribute AUTO_PARSE controls whether the background parse process of the editor is started automatically or only if explicitly called.

Micro Focus recommends that you set AUTO_PARSE to FALSE if a mainframe pre-compiler is configured. In this case, you should model a tool of type “Reparse with Refresh” from the Micro Focus Editor function package, and add it as a related action to the element type representing COBOL programs and as a global editor action. This action can be used to trigger the start of the pre-compiler interface from the context menu of the COBOL program and the editor context menu. If the file should be parsed when it is opened in the editor, you should also specify the AWM application-specific attribute INITIAL_PARSE and set it to true.

Sample Mainframe Pre-compiler Exits

There are two mainframe pre-compiler exit samples provided in the EXEC library of the z/Server delivery:

  • TAUSADCL
  • TAUSADPC

TAUSADCL

TAUSADCL is a mainframe pre-compiler exit which resolves the DB2 EXEC SQL INCLUDE statements within a COBOL program. TAUSADCL requires the list of libraries where the SQL includes are, separated by semicolon.

TAUSADCL generates an output file where all DB2 EXEC SQL INCLUDE statements with the exception of SQLCA and SQLDA are commented out and replaced by the content of the include. The TAUSADCL exit produces the change data set on its own. This results in an exit with a return code of 0 if successfully executed. If an SQL include can not be resolved from the provided include libraries TAUSADCL returns a corresponding message in the message data set.

Specify the following format for the COMPOPT option used to call the exit TAUSADCL:

 p(AWMREMPC) RESOLVEDCLGEN <list of include libraries> p(CP) NOSQL NOCOPY ENDP ENDP DIALECT(ENTCOBOL) XDB

TAUSADPC

TAUSADPC is a mainframe pre-compiler exit which calls the IBM DB2 pre-compiler with the source passed by the Mainframe pre-compiler interface. TAUSADPC expects as input the list of libraries separated by semicolon where to look up the SQL includes.

The output file generated by the IBM DB2 pre-compiler is returned to the mainframe pre-compiler interface under the allocation where the pre-compiled source is expected. TAUSADCL exits with the return code 1 on successful execution. This results in the exit leaving it to the mainframe pre-compiler interface to produce the change data set by comparing the input data set with the output data set. There is only a simple error handling implemented in the exit. If the exit is intended to be used in a production environment it has to be extended with adequate error handling.

Specify the following format for the COMPOPT option used to call the exit TAUSADPC:

p(AWMREMPC) DB2PC <list of include libraries> p(CP) NOSQL NOCOPY ENDP ENDP DIALECT(ENTCOBOL)
Parent topic: AWM Support for Enterprise Developer Editors


Function Packages

  • AWM Function Package
  • Deprecated Function Package
    This function package supports tool types which were available before AWM 2.3 but are now deprecated.
  • Eclipse Function Package
  • ISPF Function Package
  • Micro Focus Background Parser Function Package
  • Micro Focus Editor Function Package
  • Micro Focus ED Icons Function Package
    This function packages supports Enterprise Developer action icons which can be associated with action descriptors.
  • Micro Focus Enterprise Server Function Package
  • Micro Focus Project Function Package
  • Micro Focus Servers Function Package
  • MVS Function Package
  • Operating System Function Package
  • IDz Function Package
  • SVN Function Package
  • USS Function Package
Parent topic: Workflow Manager Modeling Guide


AWM Function Package

This section provides a reference for functions and tools used in AWM function package support.

  • Tool Types for the AWM Function Package
  • Icons for the AWM Function Package
  • Example Scenarios for the Usage of AWM Tool Types
Parent topic: Function Packages


Tool Types for the AWM Function Package

  • Cleanup Edit Session
  • Clear Application File Cache
  • Clear Error Feedback Entries
  • Create Persistent File
  • Create Static Element List
  • Create Temporary File
  • Locate Persistent File
  • Merge Structured Files
  • Open Modeled Dialog
  • Process Error Feedback
  • Refresh Children
  • Return Property Value
  • Set Linked Properties
  • Transfer File
  • Validate Line Length
  • Validate Value
Parent topic: AWM Function Package


Cleanup Edit Session

Function:

This tool cleans up temporary information created during a local edit by deleting the associated file from the workspace. The main action is to delete the associated file from the workspace.

If a file is temporarily edited in the context of an action, the tool "Cleanup Edit Session" is typically a component of the close action. If a persistent local file is created with the help of the tool "Create Persistent File", another action will usually be used (for example, check-in) that contains the tool "Cleanup Edit Session".

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | File | References the local file to be deleted. Usually a file descriptor is used, which is the output parameter of an earlier executed tool "Create Persistent File" or "Create Temporary File".
Parent topic: Tool Types for the AWM Function Package


Clear Application File Cache

Function:

This tool deletes the AWM internal application file cache folder.

This tool needs no input or output parameters.

This file cache contains mainly COBOL copybooks and PL/I Includes which were transferred from the mainframe to the local cache during remote edit scenarios.

Parent topic: Tool Types for the AWM Function Package


Clear Error Feedback Entries

Function:

This tool is used to clear the entries from the Error Feedback view. You should model it before the ‘Process Error Feedback’ tool if the view is to be cleared so that only the errors from the last tool execution are to be displayed.

Note: This tool does not require any input or output parameters.
Parent topic: Tool Types for the AWM Function Package


Create Persistent File

Function:

This tool is used to create a local file permanently in the Eclipse workspace which is managed by AWM. The local file is copied from the file referenced by the input parameter. The path information for the local file is managed by AWM internally and is associated with the corresponding element. The persistent file can be used with the tool "Locate Persistent File".

The tool "Create Persistent File" works only for element actions, which means that an element must be selected during the execution of this tool.

Note: The tool Create Persistent File is typically performed in check-out actions which are used to copy a file from a remote SCM system to the Eclipse workspace. This tool cannot be used to copy a file into a Micro Focus COBOL or PL/I project. Instead, use Transfer File to copy a file from a remote SCM system into a Micro Focus COBOL or PL/I project.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | File | References the (remote) file.
Parent topic: Tool Types for the AWM Function Package
Related information
Locate Persistent File
Transfer File


Create Static Element List

Function:

The Create Static Element List tool is used to create a new AWM element by giving them the property values defined in its complex element attribute.

The Create Static Element List tool contains 1 to n complex attributes. For each complex attribute, a new AWM element is added to the element list file output parameter of the tool. Within the complex attribute the match name of the element has to be defined. For each complex attribute 0 to n properties can be defined. Each property contains a property value. Each property value is added in the order they are defined in the model to the element defined in the file output parameter of the Create Static Element List tool.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | O | File | An element list which can be used to create elements. The element list has to be defined as an input stream in table format.

Relationship: Create Static Element List has Element

Attribute | Type | Description
Match name | String | Match name of the new AWM element. This is written as the first value of the entry into the file output parameter of the Create Static Element List tool.

Relationship: Element has Property

Attribute | Type | Description
Property | String | A property value of the new AWM element. The value is written as a value of the element’s property as defined in the file output parameter of the Create Static Element List tool.

Example

The Create Static Element List tool is suitable to define the root elements of a tree as normally there is no connection to the target system at this point. The usage of the tool is shown in the standard SVN model. On the root level of the SVN model two entries should be shown:

  • SVN Repositories
  • Working Copies

There are element types for both entries defined in the SVN model:

The property SVN_PROP_ELE_ElementType is the Element Type property of the SVN model. This means that in this property the match name of the element type is provided by the tool.

The tool enables you to get the root folders of the SVN model, which is modeled as follows:
SVNGetRootFolders

The tool is an implementation of the AWM Create Static Element List tool, returning two entries. The first has the match name SVN_REPOSITORIES (match name of element type SVN_ELE_SVNRepositories), the second has the match name WORKING_COPIES (match name of element type SVN_ELE_WorkingCopies). For both entries an additional attribute value is returned (SVN Repositories for the first and Working Copies for the second).

The result of the tool is returned in the file descriptor SVN_FD_ELE_SVNRepositories-WorkingCopies of type InputStream and structure Table. The definition of the file descriptor is as follows:

The action SVN_ACT_ROOT_GetRootFolders using this tool is modelled as root containers action of the SVN application:
SVNRootContainersAction

Parent topic: Tool Types for the AWM Function Package


Create Temporary File

Function:

This tool is used to temporarily create a local AWM-managed file in the Eclipse workspace. The local file is copied from the file referenced by the input parameter. The path information for the local file is returned as a file descriptor by the tool, and can be used by later tools of the same action as an input. The file name and the suffix of the file can be determined through input parameters.

The file must be explicitly deleted with the tool "Cleanup Edit Session".

The tool Create Temporary File is typically used in edit actions to check out a file from a remote SCM system, edit this file and check in the file into the SCM system on save or close.

Note: Files created with this tool can only be accessed by other tools within the action that created this file and in the associated save and close actions.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | File | References the input file.
2 [O] | I | String | Requested file name of the temporarily stored file, without a suffix. The default name is tempfile.
3 [O] | I | String | File suffix of the temporarily stored file. If this parameter is not used, the file does not have a suffix.
4 [O] | I | String | Must point to a property of type Boolean. Specifies whether the file should be opened in edit or browse mode. The default is read-only=false, which is the edit mode.
1 [M] | O | File | References the target temporary file created after the execution of the tool.
Note: If one of the optional input parameters is used, the previous input parameters have to be defined.
Parent topic: Tool Types for the AWM Function Package


Locate Persistent File

Function:

This tool is used to locate the file for the selected element that is stored in the local workspace by the tool “Create Persistent File” from the AWM function package. The path of the file is transferred to the property from the Workspace File Type that is given as an output parameter. This output parameter is an input parameter for Eclipse tools, for example, Edit Local File and Close Editor.

The Locate Persistent File tool works only for element actions, which means that an element must be selected during the execution of this tool.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | O | File | References the local file for the selected element.
Parent topic: Tool Types for the AWM Function Package
Related information
Relationship: Get All Properties Action


Merge Structured Files

Function:

This tool allows the file content of two or more structured file descriptors to be selectively merged into one. It parses all property values from the modeled file input parameters, and writes them into a single result file.

Result:

  • The merged result file contains as many lines as all input files in total, in the same order as the modeled file input parameters.
  • Only values of properties modeled as “has property” relationships are written into the output file, others are ignored. This can result in input file descriptors that contain more properties than the output file descriptor.
  • Properties of the output file, which do not occur in any of the input files, are set as empty values in the result file, for example, “value1,value2,,value4”.
  • The result file type and property delimiter is dynamic, which means that type “InputStream” creates an input stream and type “Local_File” that creates a local file on the machine, while values are separated by the modeled delimiter.

Use case:

Merge Structured Files can be used to create a merged AWM element list from the result of two or more separate tools.

Example:

The following simplified model example describes an action which is capable of creating an element list containing members from two different databases. It uses two tools, which each return a separate element list from a specific database. Merge Structured Files is used as the last tool of the action, which creates a merged result of both lists.

  • Action Descriptor “ACT_ListAllDatabaseMembers"
    • Tool Descriptor “TOOL_ListDB2Members"
      • Output file: “FILE_DB2Members"
    • Tool Descriptor “TOOL_ListSQLMembers"
      • Output file: “FILE_OracleMembers"
    • Tool Descriptor “Merge Structured Files"
      • Input file: “FILE_DB2Members"
      • Input file: “FILE_OracleMembers"
      • Output file: “FILE_AllDatabaseMembers"
Note: The input file descriptors in this example must have the attribute “Parameter From” set to “Previous_Tool”.

Parameters:

All parameters must be configured in the following way:

  • A “Target ID File” reference must be set.
  • Referenced file descriptors must have:
    • “Structure” attribute set to “Table”.
    • At least one modeled “has property” relationship.

If the tool is used to merge element lists, all referenced file descriptors must contain exactly one and the same element type property (property with the attribute “Special Property” set to “Element_Type”).

Parameter # | I/O | Type | Description
1 [M] | I | File | First file to be merged.
2 [M] | I | File | Second file to be merged.
3...n [O] | I | File | Any amount of additional file input parameters can be modeled (requirements same as parameter #1 and #2).
1 [M] | O | File | Merged file result.
Parent topic: Tool Types for the AWM Function Package


Open Modeled Dialog

Function:

This tool opens a dialog to enable user inputs and to return tool outputs to the user.

Tool Attribute:

Attribute | Type | Description
Title [O] | String (multi-line) | Specifies the title of a dialog.
Description [O] | String (multi-line) | Specifies the description of a dialog.
Dialog Type | Selection | Specifies whether an input or an output dialog is opened. Allowed values are Input Dialog or Output Dialog.
Validate Action [O] | Action Descriptor | The validate action is used to validate dialog fields before sending the values to the next tool.
Relationship | Cardinality | Description
Table_Row_Selection | 0..* | Enables you to define a condition under which the rows of a dialog table are selected when the dialog is opened.

Parameters:

Input parameters generate dialog fields.

Output parameters are not used.

An input dialog sample

Every input parameter of a Dialog-Tool descriptor generates a dialog box field when executed. The appearance of a dialog box field changes depending on whether a property or a file descriptor is referenced by a parameter. This is shown in the following table:

Parameter reference | Dialog field Input Dialog | Dialog field Output Dialog
Property (Type = String) | Combo box Text input or selection of the last user inputs | Single-line read-only text field
Property (Type = Boolean) | Check box | Read-only check box
Property (Type = Select Value) | Combo box Selection of modeled property values | Single-line read-only text field
Property (Type = Date) | Combo box with Calendar button and selection of the last user inputs | Single-line read-only text field
Property (Type = Password) | Password field | Single-line read-only text field. All characters are replaced by asterisks.
Property (Type = Time) | Time selection field | Single-line read-only text field
Property (Type = TextArea) | Multi-line text field with “remaining lines” indicator | Multi-line read-only text field
Property (Type = TextArray) | Selection list A “Retrieve All Values” action is required for the TextArray property for populating the selection list. |
Property (Type = Numeric) | Combo box with number validation and selection of last user inputs. If the attribute Value_min_length was set to 2 or higher, leading zeros are added on dialog box confirmation. | Single-line read-only text field
File Descriptor (Unstructured) |  | Multi-line read-only text field with the option of opening the content in an editor after the end of the dialog box.
File Descriptor (Structure = Table) | Table in which one row can be marked. All the properties of the marked row are output. Read-only if the UI Editable attribute is set to false. | Read-only table
  • Relationship: Open Modeled Dialog Has Table Row Selection
  • Input Dialog
  • Output Dialog
  • The "UI Category" Attribute
  • Validate Action
Parent topic: Tool Types for the AWM Function Package


Relationship: Open Modeled Dialog Has Table Row Selection

Table Row Selection attributes enable you to specify conditions to preselect one or several table rows when a modeled dialog containing tables is opened.

Table row selection attributes can be added as children of Open Modeled Dialog tools. The actual conditions must be added as further children of the attribute, in the same way as enabled or visible conditions are modelled. See Enabled/Visible Condition for more information.

Attribute | Type | Description
Target ID * | File Descriptor | Reference to the file descriptor to which the row selection is related. The target file descriptor has to be modeled as an input parameter of the dialog tool.
Simple Condition | Enable Condition | Checks a property value for a specific value using a specified operator, for example, equals, equals not, regular expression, and so forth.
Complex Condition | Enable Condition | Combines other conditions such as simple and/or complex using a specified operator, for example AND, OR.

Example:

The tool DOCU_TOOL_AWM_ProgramList has a file input parameter DOCU_FILE_ProgramList and a Table Row Selection specifying that all rows should be selected whose name starts with the string 'FIN'.

Row Selection Modeling

Parent topic: Open Modeled Dialog


Input Dialog

The Input dialog enables you to enter, change, and check parameters for subsequent processing. It generates a dialog field for every input parameter, and outputs the value to the parameter memory when you click OK. Subsequent tools have access to these parameters using the parameter from PREVIOUS_TOOL.

Sample AWM Dialog

Clicking Cancel or closing the dialog box without clicking OK results in cancelling the entire action.

The behavior and appearance of a dialog box can be modified by changing the attributes of the “Tool has Input Parameter” relationship. See Relationship: Tool has Input Parameter for more information.

Attribute | Description
Parameter From | Enables you to fill the dialog field with the “USER_INPUT” attribute value. Note: The field is not preset with a property value.
Default Value [O] | Populates the dialog field with a value or a reference, if no value is available to the referenced property and is dependent on the "Parameter_From" attribute.
Static Value [O] | Specifies a static value or a reference for this parameter. An input field with “Static Value” cannot be edited.
Label [O] | Specifies the label of the dialog field.
UI Category [O] | Groups dialog fields with the same category. See The "UI Category" Attribute for more information. For example, “Group with 4 columns/4/”.
UI Tab [O] | Assigns parameters to tabs. Tabs are created only if at least one parameter has this attribute set. Parameters which do not have a tab set are shown in a tab called General by default. If all output parameters of the same dialog tab are determined to be hidden by the evaluation of property enabling conditions, the tab is not shown in the dialog.
UI Editable, UI Generic Allowed, UI Mandatory | See Relationship: Tool Has Input Parameter for more information.
UI Multi Selection | Specifies whether multiple rows of a dialog table can be selected. If set to true, check boxes are displayed in the first table column and Select All and Deselect All options are added. Checking one or several rows creates a mass processing context. See Input Dialog Mass Processing for more information. Only relevant for structured file input parameters. See Dialog Tables for more information.
  • Dialog Tables
  • Input Dialog Mass Processing
Parent topic: Open Modeled Dialog
Related information
Relationship: Tool Has Input Parameter
The "UI Category" Attribute
Input Dialog Mass Processing


Dialog Tables

AWM enables you to specify dialog boxes that contain tables. The table columns, content, and actions are described by structured file descriptors. The file descriptors must be modelled as file input parameters to enable them to be displayed as a table in a dialog box.

Sample Table Dialog

By default, you can only select a single table row in order to proceed with the action. The selected row’s properties are added to the previous tool's execution context which can be used by subsequent tools in the action. You can customize its behavior by using the following model attributes:

Attribute/Relationship | Description
Input Parameter: UI Editable | Specifies whether the selected table rows have an effect on the action/context. When false, the table is disabled and is greyed out. Default value: true
Input Parameter: UI Mandatory | Specifies whether at least one row must be selected/checked by the user. Default value: true Only relevant if UI Editable is set to true.
Input Parameter: UI Multi Selection | Specifies whether multiple rows can be checked by a user, creating a mass processing context. See Input Dialog Mass Processing for more information. If true, the table row's check box must be clicked to select the row. Only selecting table rows no longer has an effect. Default value: false Only relevant if UI Editable is set to true.
File Descriptor has Action | Action descriptors added to file descriptors enable actions to be executed on a dialog table's rows. Executed actions can modify table rows using resource operations. See Tool Descriptor for more information. Actions can be applied to one or more rows depending on the selection count of the enabled or visible condition (default *). Note: If a modelled action enables you to select and process multiple rows, only the first row selected is passed to the execution context to be processed by the following tools once OK is clicked.
Parent topic: Input Dialog


Input Dialog Mass Processing

Note: Only one multi-selection can be active during the execution of a mass processing action. Micro Focus recommends that you limit mass-processing action descriptors which use dialogs to create a multi-selection to a single element. See Enabled/Visible Condition for more information.

Modeled input dialogs can be used to create a multi-selection for mass processing actions. See Mass Processing Overview for more information. This requires the following setup:

  • A file input parameter must be modeled.
    • The referenced file descriptor must be structured (table).
    • The UI Multi Selection attribute must be set to “true".
    • Only one structured file input parameter is allowed per input dialog.
  • The tool descriptor must be referenced by an action descriptor with the attribute Mass Processing set to “true".

If executed, the dialog displays the referenced file as a table with checkboxes in the first column. See figure below:

The dialog behaves as follows:

  • Depending on the UI Mandatory attribute, the dialog can only be confirmed if at least one line (checkbox) has been selected.
  • On confirmation, the dialog overwrites the current multi-selection (mass processing context).
  • All properties of the selected line(s) are stored in the “previous tool” property pool of the mass processing contexts.
    • Subsequent tools can read those values using input parameters of the type Mass Processing and the parameter from “Previous Tool”, referencing the desired property.

Rows in a dialog can be pre-selected by adding a Table Row Selection condition.

It is possible to define more than one Table Row Selection for an Open Modeled Dialog tool:

  • Each Table Row Selection must refer to a file input parameter of the Open Modeled Dialog tool.

  • Different Table Row Selections cannot refer to the same file input parameter from the Open Model Dialog tool.

  • A Table Row Selection can contain either a complex or a simple condition:

    • A row is pre-selected when the condition is true.

    • If no condition is added to the Table Row Selection all rows are pre-selected.

  • A complex condition can contain any number of complex or simple conditions.

  • See Enabled/Visible Condition for more information on the evaluation of conditions.

Parent topic: Input Dialog
Related information
Enabled/Visible Condition
Mass Processing Overview


Output Dialog

The Output dialog is used to display tool output parameters and output files.

Although tool messages could be passed to AWM as output parameters or output files, it is recommended to pass messages to AWM using the specific message support. This can be supported by specific tools only and cannot be modeled. See Messages for more information.

The tool outputs to be displayed are specified by the To Output Dialog attribute, which is set by preceding tools during the modeling of the output parameters. See Relationship: Tool Has Output Parameter for more information.

The number of dialog box fields depends on the tool descriptors of an action. It is therefore possible to create only one Open Modeled Dialog tool with the attribut Output Dialog, which can be used for all action descriptors. This tool must be referenced as the last tool descriptor of an action descriptor if it is to display all the desired outputs at the end of the action.

Note: If a previous tool within an action has a return code higher than the maximum allowed return code, the action is stopped and an error message dialog box is displayed, but a modeled output dialog is not displayed. This is why it is not recommended to pass tool error messages to an output dialog.
Parent topic: Open Modeled Dialog
Related information
Messages
Relationship: Tool Has Output Parameter


The "UI Category" Attribute

Modeled dialog fields can be grouped by using the attribute "UI Category". The attribute can be found among the tool descriptor and filter type attributes. The group is visualized in the dialog by a frame around the dialog fields which has a label at the top. If several dialog fields share a UI category value, and are grouped within the frame.

By default a UI category has one column which means that all dialog fields of this category are placed underneath each other. Increasing the column number of a category results in dialog fields being displayed next to each other.

The syntax for the UI category attribute is:

Category Name/<number of columns>,<column span>/

The following syntax is also valid but deprecated:

Category Name{<number of columns>,<column span>}
Tip: You only need to specify the column number for the first parameter of the category.

Since the number of columns and the column span are optional attributes with the default value of "one" they do not need to be specified if not required (see the table below).

UI_Category value | Result
Field 1: Example Category Field 2: Example Category | A framed group with the label “Example Category” and one column. The two fields are displayed underneath each other.
Field 1: Example Category Field 2: Example Category Field 3: Another Category | Two framed groups with the labels “Example Category” and “Another Category” are created underneath each other. The first category contains two dialog fields while the second category only contains one field.
Field 1: Example Category/2/ Field 2: Example Category/2/ Field 3: Example Category/2/ Field 4: Example Category/2/ | A framed group with the label “Example Category” and two columns. The four fields are displayed in two rows.
Field 1: Example Category/2,2/ Field 2: Example Category/2/ Field 3: Example Category/2/ | A framed group with the label “Example Category” and two columns and rows. The first field fills up the first row (since it spans both columns) while the second row contains Field 2 and 3.
Field 1: (space character) Field 2: (space character) | One invisible category is created for each field. The visible effect is that the two fields use the full width of the dialog instead of being shifted behind the longest label of other dialog fields.
Parent topic: Open Modeled Dialog


Validate Action

The validate action is used to validate dialog fields before sending the values to the next tool. It is supported by the "Validate Action" attribute of the Open Modeled Dialog and the Execute ISPF Dialog tool descriptors. The validate action is executed when the OK button is clicked in the dialog box.

Tools defined in a validate action can return specific validate messages that are interpreted by AWM. Any AWM tool descriptor is able to return validation messages if additional API programming has been implemented to create these messages.

There is already specific support for validate messages available for the following tool descriptors:

  • Execute ISPF Command, see Messages in Tool Adapter as a REXX subroutine for more information.
  • Execute ISPF Dialog Application, see Messages in Tool Adapter as a REXX subroutine for more information.
  • Execute OS Command, see Execute OS Command for more information.

Messages are identified by the prefix "VALMSG" and are only returned if any of the modeled tools detects validation error(s), warning(s) and/or information(s) in the dialog fields. The prefix "VALMSG" is followed by special keywords. The order of the keywords is not relevant. Permitted keywords are "MSGTEXT", "SEVERITY" and "POS". Values of keywords are given in parentheses. Keywords and their values are not case sensitive.

The keyword "MSGTEXT" is mandatory. It contains the validate text that is shown in the dialog.

The keyword "SEVERITY" contains the severity of a validate message. Permitted values are "I" for Information, "W" for Warning and "E" for Error. The default value is "I".

The keyword "POS" contains the position of the dialog field to which the validate message refers. A validate message can correspond to multiple dialog fields. In this case the positions are separated by blank or comma. Dialog fields corresponding to these positions are decorated with a validation message text depending on the severity. The focus is set to the dialog field corresponding to the lowest position value.

Example of a tool validation message:

VALMSG MSGTEXT (Unfiltered member selection may produce a large  output.) SEVERITY(W) POS(5)

The following table shows how validation messages are processed depending on their severity.

Highest message severity | Message processing
I , W | Display all messages in the header of the dialog marked as information (I) or warning (W). If the user changes a dialog field, the validate action is called again when the OK button is clicked. Otherwise the action directly proceeds with the next tool when the user clicks OK the next time and the validation action is not executed again.
E | Display all messages in the header of the dialog marked as error. The validate action is called again when the OK button is clicked.
Parent topic: Open Modeled Dialog
Related information
Messages
Execute ISPF Command
Execute ISPF Dialog
Execute ISPF Dialog Application
Execute OS Command
Tool Adapter as a REXX Subroutine


Process Error Feedback

Function:

This tool analyzes the compiler's error feedback file, and adds the messages to the Error Feedback view.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | file | References the Error Feedback XML file created by a compiler or a tool that transforms the compiler output into the required XML format.

Error Feedback XML Format

The XML format interpreted by AMW is a subset of the standard XML format supported by the IBM Enterprise PL/I compiler's XML option.

The following shows the XML schema for the error feedback file:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema   xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element   name="FILENUMBER"   type="xsd:string" />
    <xsd:element   name="PACKAGE">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element   ref="FILEREFERENCETABLE"   maxOccurs="1"  minOccurs="1" />
                <xsd:element   ref="MSGTABLE"   maxOccurs="1" minOccurs="1" />
                <xsd:element   ref="MSGTABLE"   maxOccurs="1" minOccurs="1" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element   name="FILENAME"   type="xsd:string" />
    <xsd:element   name="MSGTABLE">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element   ref="MESSAGE"   maxOccurs="unbounded"  minOccurs="0" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element   name="MESSAGE">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element   ref="MSGNUMBER"   maxOccurs="1"	 minOccurs="1" />
                <xsd:element   ref="MSGLINE"   maxOccurs="1" minOccurs="1" />
                <xsd:element   ref="MSGFILE"   maxOccurs="1" minOccurs="1" />
                <xsd:element   ref="MSGTEXT"   maxOccurs="1" minOccurs="1" />
                <xsd:element   ref="CUSTOMATTRIBUTES"   minOccurs="0"		maxOccurs="1" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element   name="MSGNUMBER"   type="xsd:string" />
    <xsd:element   name="MSGTEXT"   type="xsd:string" />
    <xsd:element   name="FILECOUNT"   type="xsd:string" />
    <xsd:element   name="OUTFILENAME"   type="xsd:string" />
    <xsd:element   name="MSGLINE"   type="xsd:string" />
    <xsd:element   name="FILE">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element   ref="FILENUMBER"   maxOccurs="1"		minOccurs="1" />
                <xsd:element   ref="FILENAME"   maxOccurs="1" minOccurs="1" />
                <xsd:element   ref="CUSTOMATTRIBUTES"   minOccurs="0"
                    maxOccurs="1" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element   name="MSGFILE"   type="xsd:string" />
    <xsd:element   name="FILEREFERENCETABLE">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element   ref="FILECOUNT"   maxOccurs="1"  minOccurs="1" />
                <xsd:element   maxOccurs="unbounded"   ref="FILE"  minOccurs="1" />
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element   name="CUSTOMATTRIBUTES" />
</xsd:schema>

The error feedback file contains the following tags:

XML tag | Description
PACKAGE | An encompassing tag for the file reference and message table.
FILEREFERENCETABLE | An encompassing tag which describes the files used during compiling.
MSGTABLE | An encompassing tag which describes the messages created during compiling.
FILECOUNT | Describes the number of files that were used during processing.
FILE | Describes an individual file that is used during compiling.
FILENUMBER | Describes the number assigned to the input file by the compiler.
FILENAME | The name of the file used during the processing. It is the name of the file that corresponds with the FILENUMBER tag.
MESSAGE | Describes a message that is produced by the compiler.
MSGNUMBER | Describes the message number of the message that was produced by the compiler.
MSGLINE | Describes the line in the input file that caused the compiler to produce the message.
MSGFILE | Describes the file number of the input file that caused the compiler to produce the message.
MSGTEXT | The text of the message that is produced by the compiler.
CUSTOMATTRIBUTES | Additional attributes that can be added to the error feedback XML file. The values of the custom attributes are only accessible through the API. See the IErrorFeedbackEntry interface of the ‘com.microfocus.awm.model’ package.

Example of an Error Feedback XML file created in a distributed environment, such as a Micro FocusEnterprise Server environment:

<PACKAGE>
    <FILEREFERENCETABLE>
        <FILECOUNT>01</FILECOUNT>
        <FILE>
            <FILENUMBER>01</FILENUMBER>
            <FILENAME>c:\microfocus\esd\BANKPROD\Sources\cbl\ZBANKULP.CBL</FILENAME>
        </FILE>
    </FILEREFERENCETABLE>
    <MSGTABLE>
        <MESSAGE>
            <MSGNUMBER>COBCH0071 S</MSGNUMBER>
            <MSGLINE>12</MSGLINE>
            <MSGFILE>01</MSGFILE>
            <MSGTEXT>PROCEDURE DIVISION missing or unknown statement</MSGTEXT>
        </MESSAGE>
    </MSGTABLE>
</PACKAGE>

Example of an Error Feedback XML file containing custom attributes:

The <CUSTOMATTRIBUTES> tag can be used to add additional information in the error feedback XML file. The <CUSTOMATTRIBUTES> element can either been defined between the <FILE></FILE> or <MESSAGE></MESSAGE> element in an error feedback XML file.

Parsed custom attributes are added to the corresponding IErrorFeedbackEntry's. The values of the custom attributes can be accessed through the API. See the IErrorFeedbackEntry interface of the ‘com.microfocus.awm.model’ package.

<PACKAGE>
    <FILEREFERENCETABLE>
        <FILECOUNT>01</FILECOUNT>
        <FILE>
            <FILENUMBER>01</FILENUMBER>
            <FILENAME>c:\microfocus\esd\BANKPROD\Sources\cbl\ZBANKULP.CBL
            </FILENAME>
            <CUSTOMATTRIBUTES canEdit="true" group="dev2" />
        </FILE>
    </FILEREFERENCETABLE>
    <MSGTABLE>
        <MESSAGE>
            <MSGNUMBER>COBCH0071 S</MSGNUMBER>
            <MSGLINE>12</MSGLINE>
            <MSGFILE>01</MSGFILE>
            <MSGTEXT>PROCEDURE DIVISION missing or unknown statement</MSGTEXT>
        </MESSAGE>
    </MSGTABLE>
</PACKAGE>

Example of an Error Feedback XML file created on z/OS:

<PACKAGE>
    <FILEREFERENCETABLE>
        <FILECOUNT>2</FILECOUNT>
        <FILE>
            <FILENUMBER>1</FILENUMBER>
            <FILENAME>SCLM.DEV1.SOURCE(TESTUP3)</FILENAME>
        </FILE>
        <FILE>
            <FILENUMBER>2</FILENUMBER>
            <FILENAME>SCLM.DEV1.SOURCE(TESTCPY1)</FILENAME>
        </FILE>
    </FILEREFERENCETABLE>
    <MSGTABLE>
        <MESSAGE>
            <MSGNUMBER>IGYGR1080 S</MSGNUMBER>
            <MSGLINE>2</MSGLINE>
            <MSGFILE>2</MSGFILE>
            <MSGTEXT>A "VALUE" clause literal was not
                compatible with the data category of the subject data item.
                The "VALUE" clause was discarded.</MSGTEXT>
        </MESSAGE>
        <MESSAGE>
            <MSGNUMBER>IGYPS0037 S</MSGNUMBER>
            <MSGLINE>27</MSGLINE>
            <MSGFILE>1</MSGFILE>
            <MSGTEXT>"ERG" was not a uniquely defined name. The
                definition to be used could not be determined from the context.
                The reference to the name was discarded.
            </MSGTEXT>
        </MESSAGE>
    </MSGTABLE>
</PACKAGE>
Parent topic: Tool Types for the AWM Function Package


Refresh Children

Function:

The Children Refresher tool can be used to refresh children of elements in the tree view or resources in the Eclipse work space.

Tool Attribute:

Attribute Type Description
Set Function Selection Valid values are:
  • Refresh children of loaded application
  • Refresh children of specific element
  • Refresh specific workspace resource

Parameters:

The necessary input parameters depend on the selected Set Function attribute:

Function Description
Refresh children of loaded application. No input parameters need to be modeled.

If executed, the “Get Root Containers” action will be called, which refreshes the application children in the tree view. If all “Get Children” actions have the attribute “Linked List = true” (default value), the complete tree view cache will be cleared.

Refresh children of specific element. At least two input parameters must be modeled, which contain the complete identifier of the element that should be refreshed.

The identifier contains:

  • The match name (property with attribute “Special Property = Element Type”).
  • The element ID (all properties of the element type’s ID definition).

The number of modeled properties does not matter, as long as an element type property and all ID properties of the element type are among them. Therefore, it is possible to define one Children Refresher tool for refreshing elements of different element types.

The element children will be refreshed if it is not visible (expanded) at the moment and there will be no exception if the specified element does not exist. An exception will only be caused if no element ID can be created from the given input values (e.g. invalid matchname or missing ID properties for the matchname).

Refresh specific workspace resource. Exactly one string or file input parameter must be modeled, which contains the absolute or relative path of a workspace folder, file or project.

Has no visible effect when executed but can be used in actions which require Eclipse workspace resources to be refreshed (e.g. file has been created within the workspace by a local script).

Does not cause an exception if the specified resource does not exist.

Parent topic: Tool Types for the AWM Function Package


Return Property Value

Function:

This tool is used to return values in the defined tool output parameters. This tool overrides the property values of the modelled output parameters with the values of the modelled input parameters. The tool supports mass processing and a file descriptor as output parameter.

Attributes:

Attribute | Type | Description
Mode [M] | Selection | Specifies the mode of the tool. The values determine the mapping:Property to Property or Property to Structured File Descriptor or Structured File Descriptor to Property. Default = Property to Property

Parameters:

Parameter # | I/O | Type | Description
1[M] | I | String/Mass Processing/File | The source property or structured file descriptor, which value(s) are returned as property value(s) to the target property or are written in the has property relationship(s) of the target file descriptor.
2..* [O] | I | String/Mass Processing | Further source properties, which values are returned as further property values to the target properties or are written in the has property relationships of the target file descriptor. Additional input parameters are not allowed if the first input parameter is of type File.
1 [M] | O | String/Mass Processing /File | The target property or a structured file descriptor. Type “File” is not allowed, if the first input parameter is from type “File”.
2..* [O] | O | String/Mass Processing | Further target properties. It is not possible to combine a structured file descriptor with further target properties.

Supported scenarios:

By specifying a mass processing input and output parameter, the given property values of all given entity contexts are returned by the matching output parameters.

By specifying a single processing input and a mass processing output parameter, the given property value is returned for each mass processing context by the matching output parameter.

By specifying a single processing input and a single processing output parameter, the given property value is returned by the matching output parameter.

By specifying mass processing input parameters and structured file descriptor as an output parameter, a new line with the given property values is written into the file descriptor for every mass processing context.

By specifying single processing input parameters and structured file descriptor as an output parameter, one line with the given property values is written into the file descriptor. If single processing input parameters are used in a mass processing action, a new line with the given property values is written into the file descriptor for every mass processing context. The value in every line of the file descriptor is the same for the single processing input parameters.

By specifying a structured file descriptor as an input parameter and mass processing as an output parameter, property values of each line of the file descriptor are written in a new mass processing context.

By specifying a structured file descriptor as an input parameter and single processing as an output parameter, property values of the first line of the file descriptor are returned to the corresponding output parameters.

Parent topic: Tool Types for the AWM Function Package


Set Linked Properties

Function:

This tool sets linked property values to a linked element. It supports mass processing.

If the properties have to be associated to an element, the actions containing this tool must be element actions and the linked element type must support the requested property updates.

Example:

This tool can be used to associate compiler directives of COBOL and PL/I programs to a file which is managed in a Micro Focus project.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | File | References the XML file containing the linked property IDs and the corresponding values to be set.

XML Structure:

Parent topic: Tool Types for the AWM Function Package


Transfer File

Function:

This tool transfers a file from one platform to another, it supports mass processing.

Note: If the target file of the tool "Transfer File" is an MVS data set, it is not checked if an enqueue is set on the data set before it is overwritten. The tool "Transfer File" does not set an enqueue before overwriting the data set content.

If the target file of the tool "Transfer File" is of type MVS_SEQ the sequential MVS data set must already exist. The creation of a new sequential MVS data set is not supported by the tool.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | File/MassProcessing | References the source of the file transfer.
2 [M] | I | File/MassProcessing | References the target file of the file transfer.

Both input parameters must be either File or MassProcessing type.

Parent topic: Tool Types for the AWM Function Package


Validate Line Length

Function:

This tool is used to validate the maximum number of characters per line. As input, either the active editor or a file input can be used.

Attributes:

Attribute Type Description
Get Content From Select Value Specifies whether the content to validate is a file or the active editor content.
  • Active Editor (Default)
  • File
Message Severity Select Value Specifies the severity of a returned message.

Error messages cause an action to be aborted. Warning messages and information messages are displayed to the user without affecting the workflow. The only difference between warning and information messages are their appearance. This is also dependent on the operating system. Ignore does not affect the workflow at all. Abort cancels the action without any message:

Possible values:

  • Error (Default)
  • Warning
  • Information
  • Ignore
  • Abort
Ignore Blanks Select Value Specifies whether leading or trailing blanks should be used for the validation of the line length or not.

Possible values:

  • Empty (Default)
  • Leading
  • Trailing
  • Leading and Trailing

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/Mass Processing | Maximum line length as number
1 [O] | I | File/Mass Processing | If the ‘Get Content From…’ is set to ‘File’, this file input parameter is used as content that is validated.
2 [O] | O | String/Mass Processing | The result of the validation. This is a Boolean value. It returns true, if no line in the validated content is longer than the maximum line length. It returns false, if at least one line in the validated content is longer than the maximum line length.
Parent topic: Tool Types for the AWM Function Package


Validate Value

Function:

The tool can be used to match a property value or file descriptor physical name against a regular expression and return different message types if a value does not match.

It can either be used as part of a standard action descriptor or a modeled dialog validation action. See Validate Action for more information on how to validate values of modeled dialog box fields.

Attributes:

Attribute | Type | Description
Regex* | String | The regular expression to be used for validation. Only visible if “Regex From” is set to “Attribute” (default).
Regex From Select Value Whether the regular expression to be used should be set by the “Regex” attribute or an input parameter.

Possible values:

  • Attribute (default)
  • Input Parameter
Regex Case Sensitive | Boolean | Whether the validation should be case sensitive (default = true).
Message String Custom message to be returned if the property value is invalid.

If no message is specified, a message is generated by AWM. The generated message syntax takes the form:

The value “&INVALID_VALUE.” of “&VALUE_LABEL.” does not match the validation pattern “&REGEX.”.

While the three variables are resolved as follows:

  • INVALID_VALUE: The validated value(s), which did not match the regular expression. If used with mass processing, all invalid values are included and are separated by comma and enclosed in square brackets: [value1, value2, …]
  • VALUE_LABEL: The label of the property or the file descriptor ID, if the physical name of a file descriptor has been validated.
  • REGEX: The regular expression used to validate the value(s). If used as a mass processing input parameter, all used regular expressions are included in the same format as INVALID_VALUE.

These variables can be included in custom messages. They must be referenced by the “Start Reference” (default “&”) and “End Reference” (default “.”) characters as configured in the application options.

Message Type

Select Value

The type of a returned message.

Tool messages are displayed during every modeled AWM action. If “Message Severity” is set to “Error” it aborts the execution with an error message. See Messages for more information.

Validation messages are only supported if the tool is executed within an AWM modeled dialog’s validation action. See Validate Action for more information.

Possible values:

  • Tool Message (default)
  • Validation Message

Message Severity

Select Value

The severity of a returned message.

Error messages cause an action to be aborted (or prevent you from leaving a dialog after the execution of the validation action) while warning and information messages are just displayed to the user without affecting the workflow. The only difference between warning and information messages are their appearance and depending on the operating system.

Possible values:

  • Error (default)
  • Warning
  • Information

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String/Mass Processing | The value to be validated. File input parameters are not supported, but a file descriptor can be referenced (Target ID File) to validate its physical name.
2 [O] | I | String/Mass Processing | The regular expression to be used for validation. This can be a “String” parameter even for mass processing execution. In this case, it validates all values against the same regular expression. Only visible, if attribute “Regex From” is set to “Input Parameter”.

Mass Processing

The tool supports mass processing by validating all values of a given mass selection. A message is returned if one or more values do not match the regular expression pattern.

If more than one value was invalid or more than one regular expression has been used, all values are displayed in the generated message or custom message, if the corresponding variables have been used. See the “Message” attribute for more information.

Example using tool "Validate Value" in validation action

The following use case describes how to use the tool to validate a z/OS data set name and member name within a modeled dialog.

Two action descriptors must be defined as minimum:

  1. ACT_EnterMemberAndDataSetName

    1. TOOL_InputDialog_EnterMemberAndDataSetName (AWM Open Modeled Dialog)

      1. Validation Action -> ACT_ValidateMemberAndDataSetName

      2. Input parameter #1: PROP_DataSetName

      3. Input parameter #2: PROP_MemberName

  2. ACT_ValidateMemberAndDataSetName

    1. TOOL_ValidateDataSetName (AWM Validate Value)

      1. Regex = ^[A-Z#$@][A-Z0-9#$@-]{0,7}([.][A-Z#$@][A-Z0-9#$@-]{0,7}){0,21}$

      2. Message Type = Validation Message

      3. Input parameter #1: PROP_DataSetName

    2. TOOL_ValidateMemberName (AWM Validate Value)

      1. Regex = ^[A-Z#$@][A-Z0-9#$@]{0,7}$

      2. Message Type = Validation Message

      3. Input parameter #1: PROP_MemberName

The first action descriptor is used to open the modeled dialog and the second one is referenced as validate action of the dialog tool descriptor. As soon as OK is clicked in the modeled dialog, both validate value tools are executed and return a validation message if a value does not match the regular expression. The validation message are displayed in the corresponding fields.

Parent topic: Tool Types for the AWM Function Package


Icons for the AWM Function Package

The AWM function package supports some common action and element related icons.

These icons are used for example in the standard Enterprise Developer Projects model for the copy action.

If the AWM function package has been added to an AWM model, the supported icons can be added through the icons section of the model editor. This can be used to associate icons to any action descriptors or element types.

Parent topic: AWM Function Package


Example Scenarios for the Usage of AWM Tool Types

Example: Browse local file

This is an example from the standard Enterprise Developer Project model which is an integral part of the Enterprise Developer installation.

The action OFFL_ACT_CONT_Browse_LocalOSFile is used to browse a dependent source element in this model, for example, a COBOL copybook.

The action consists of two tools from the AWM function package:

  • Create Temporary File
  • Edit Local File

The action is related to a close action, defined as:

Browse Action Properties

The AWM tool 'Create Temporary File' creates a temporary workspace file depending on the selected element with the fix suffix 'cpy' and the read-only flag set to true:

Temp File Creator Tool

The input file descriptor points to a local OS file. The file descriptor has the following properties:

File Descriptor for a Local File

The output file points to a workspace file with the following properties:

File Descriptor for a Workspace file

The output parameter of the 'Create Temporary File' tool is used by the 'Edit Local File' tool as an input parameter:

Browse Local File Tool

In the related close action the AWM tool 'Cleanup Edit Session' is called. This gets the newly created workspace file as an input parameter to remove it when the editor is closed:

Browse Clean Up Action

Browse Clean Up Tool

Example: Merge structured files

This example is based on the standard Enterprise Developer Project model.

The AWM tool 'Merge Structured Files' is used in this model to merge the dependent elements of a local project. The children of a local project are a mix of folder and files or categories. In this case, IMTK categories.

The action OFFL_ACT_ELIST_GetEclipseChildren is defined as a 'Get Children' action of the element type Eclipse project:

Project Get Children Action

The action OFFL_ACT_ELIST_GetEclipseChildren consists of three tools:

  • A tool to get the IMTK categories belonging to the selected project.
  • A tool to get the children folder and files of the selected project.
  • A tool to merge the result files of the two preceding tools.

Get Eclipse Children Action

Get IMTK Categories Tool

Get Eclipse Children Tool

Merge Resources Tool

The output file descriptors of the first two tools are modeled as follows:

File Descriptor IMTK Categories

File Descriptor Resource Children

The file descriptor returned by the tool 'Merge Structured Files' has the following structure:

File Descriptor Merge Resources

This file descriptor is used to display the children of a local project in the Application Explorer view.

Parent topic: AWM Function Package


Deprecated Function Package

Function packages were introduced with AWM 2.3. All AWM modeled tool descriptors are now associated with function packages.

Tool descriptors modeled with an older version of AWM are still supported and those tools can be executed at run time.

All tool descriptors found in an older model version are automatically associated to the Deprecated Function Package.

Although all deprecated Enterprise Developer supported tool descriptors are still visible if you open an out-dated model and can be updated in the model editor, it is not possible to define a new deprecated tool descriptor. For all those deprecated tool descriptors there are new function package tools available which should be used instead. See Integrated Tools - Function Package Mapping and Extpoint Tools - Function Package Mapping.

Although out-dated tools can still be executed at run time and can still be maintained in the model editor, Micro Focus recommends to convert the models. This can be done if the model is opened in the AWM model editor. All Micro Focus deprecated tool descriptors except the Extpoint tools can be converted automatically. See Converting a Deprecated Model. The Extpoint tool descriptors must currently be converted manually.

Deprecated tool descriptors which were not provided by Enterprise Developer can still be created by selecting these tool descriptors from the Deprecated Function Package.

  • Integrated Tools - Function Package Mapping
  • Extpoint Tools - Function Package Mapping (deprecated)
    Describes which function package tools should be used instead of the deprecated Extpoint tools.
Parent topic: Function Packages
Related information
Converting a Deprecated Model
Extpoint Tools - Function Package Mapping (deprecated)
Integrated Tools - Function Package Mapping


Integrated Tools - Function Package Mapping

In AWM versions prior to V2.3, integrated AWM functions were modeled as so-called "integrated tools". These tools are now deprecated and replaced by different function package tools. The following table shows deprecated integrated tools and their new function package counterpart.

Integrated Tool (before AWM V2.3) | Function Package - Tool
Children Refresher | AWM – Refresh Children
Edit Clean Up | AWM – Clean Edit Session
Edit Closer | Eclipse – Close Editor
Edit Opener | Eclipse – Edit Local File
Error Feedback | AWM – Process Error Feedback
File Compare | Eclipse – Compare Local Files
File Uploader | AWM – Transfer File
Linked File Creator | Eclipse – Create Resource
Local File Creator | AWM – Create Persistent File
Local File Locator | AWM – Locate Persistent File
Local Syntax Check | Not supported.
Property Set Associator | IDz – Create Property Group
Property Set Creator | IDz – Associate Property Group
Property Set Remover | IDz – Remove Property Group
Refresh Dependencies | Not supported.
Remote Browse | MVS – Browse MVS File
Remote Edit | MVS – Edit MVS File
Submit JCL | MVS – Submit JCL

Deprecated integrated tools in old models can be automatically converted by using the "Convert Deprecated Model…" function (see Converting a Deprecated Model).

Parent topic: Deprecated Function Package
Related information
Converting a Deprecated Model


Extpoint Tools - Function Package Mapping (deprecated)

The following Extpoint tools are deprecated and should be replaced by the corresponding function package tools or by the corresponding linked properties:

EXTPOINT | Function Package | Tool/Linked Property | Remarks
MF_NewProjectFromTemplate | Micro Focus Project | New Project From Template |
MF_GetWorkspaceProjects | Eclipse | Get Eclipse Projects |
MF_GetWorkspaceContents | Eclipse | Get Resource Children |
MF_LocalEdit | Eclipse | Edit Local File |
MF_LocalPaint | Eclipse | Edit Local File | Editor ID = com.microfocus.eclipse.edt.ui.editor.BmsTextEditor
MF_LocalDataEdit | Eclipse | Edit Local File | Editor ID = or com.microfocus.eclipse.edt.ui.editor.DataFileExternalLauncher
MF_Properties | Eclipse | Show Properties Dialog |
MF_EclipseCommandHandler | Eclipse | Eclipse Command Handler |
MF_SelectProjectFolder | Eclipse | Select Resource |
MF_SelectFolder | Eclipse | Select Resource |
MF_RefreshResource | Eclipse | Refresh Resource |
MF_DeleteResource | Eclipse | Delete Resource |
MF_MoveResource | Eclipse | Move Resource |
MF_CopyResource | Eclipse | Copy Resource |
MF_RenameResource | Eclipse | Rename Resource |
MF_ClearFileCache | AWM | Clear Application File Cache |
MF_ParseWithRefresh | Micro Focus Editor | Reparse With Refresh |
MF_ResolveResourceToPath | Eclipse | Get File System Path |
MF_ResolvePathToResource | Eclipse | Get Workspace Path |
MF_IsAutoBuilding | Eclipse | Linked Property: Is Auto Build |
Parent topic: Deprecated Function Package
Related information
Clear Application File Cache
Command Handler
Copy Resource
Delete Resource
Edit Local File
Get Eclipse Projects
Get File System Path
Get Resource Children
Get Workspace Path
Linked Properties for the Eclipse Function Package
Move Resource
New Project From Template
Refresh Resource
Rename Resource
Reparse With Refresh
Select Resource
Show Properties Dialog Box


Eclipse Function Package

This section provides a reference for functions and tools used in function package support for Eclipse.

  • Attributes for the Eclipse Function Package
  • Linked Element Types for the Eclipse Function Package
  • Drag and Drop Handling for Linked Eclipse Resources
  • Linked Properties for the Eclipse Function Package
    Lists the linked properties supported by the Eclipse function package.
  • Tool Types for the Eclipse Function Package
Parent topic: Function Packages


Attributes for the Eclipse Function Package

Attribute Type Description
Background Synchronizer Boolean When this attribute is set to true, Eclipse resources (projects, folders, files) relevant for the active AWM application are synchronized immediately when there is a resource change (for example, when resource has been deleted, moved, renamed, or created) and the Team Developer views are refreshed, if necessary.

This only synchronizes resource changes done after the AWM application has been loaded and is still active (see the attribute Synchronize on Load below).

Default: true

Project Name Filter String A filter definition in the form of a regular expression to define the Eclipse project names to be considered by the synchronization process.

Default: .*

Project Nature Filter String A filter definition in the form of a regular expression to define the Eclipse project natures to be considered by the synchronization process.

Default .*

Enable Run Debug Profile Context Menu Actions

Boolean

If this attribute is set to true, the Run As, Debug As and Profile As actions are shown in the context menu of Eclipse elements.

Synchronize on Load Boolean If this attribute is set to true, a one-time synchronization is executed when the AWM application loads. This is to synchronize all relevant Eclipse resources with the AWM application elements.

Default: true

Use Eclipse Menu Bar Extension Boolean If this attribute is set to false, the resource related actions in the Eclipse menu bar are deactivated, otherwise they are activated.

Default: true

Use Element Extensions Boolean Setting this attribute to true has these effects:
  • The context menu of Eclipse resources in the Team Developer perspective is populated with basic Eclipse actions available for the Eclipse resource.
  • The basic Eclipse decorators are shown on the resource’s icons.

Default: true

The synchronization process will only work under the following conditions:

  • Only AWM elements are synchronized which are associated to the linked element type Eclipse Resource with the identifier com.microfocus.awm.functionpackage.eclipse.linkedelementtype.iresource.
  • The AWM ID Definition of the linked element type for an Eclipse resource must be defined with only one key property, which is used for the Eclipse path.
Parent topic: Eclipse Function Package


Linked Element Types for the Eclipse Function Package

  • Eclipse Resource
    Describes the linked element type Eclipse Resource within the Eclipse function package.
Parent topic: Eclipse Function Package
Related information
Linked Element Type


Eclipse Resource

The Eclipse function package contains just one linked element type, called Eclipse Resource.

If a label and its decorator have not been explicitly defined then the linked element type Eclipse Resource determines the resource's label to display in the Application Explorer tree view. The resource label is determined, if the 'Tree View Label' attribute in all element has property relationships is set to false. By default, the 'Tree View Label' attribute is set to false in all relationships.

If no text decoration is explicitly modelled, which is the default, then the label and the text decoration is determined by the linked element type Eclipse Resource.

If the resource's label is determined by the linked element type Eclipse Resource, then the resource's label is displayed in the same way as in the Project Explorer view.

Attributes

The following specific rules apply to the element type Eclipse Resource:

Attribute | Description
ID Definition | The ID definition of an Eclipse resource must consist of just one string property which contains the Eclipse path to the resource.
Matchname Match name provided by a tool type to identify the type of the Eclipse resource. The following three match names are default:
  • ECLIPSE_PROJECT
  • ECLIPSE_FOLDER
  • ECLIPSE_FILE

The tool descriptors Get Resource Children and Get Eclipse Projects provide optional attributes to specify other match names.

Get Children | Reference to an action descriptor which contains tools to fetch the dependent files of the given Eclipse linked element (for example, the files contained in an Eclipse folder). The tool descriptor Get Resource Children can be used to retrieve the Eclipse resource children.
Parent topic: Linked Element Types for the Eclipse Function Package
Related information
Element Type
Get Eclipse Projects
Get Resource Children


Drag and Drop Handling for Linked Eclipse Resources

Drag and drop for linked Eclipse resources are handled as follows:

Source view | Target view | Action
Application Explorer or Table Results view | Application Explorer or Table Results view | Move or copy (depending on the target resource, see note below).
Remote System view (local, MVS Explorer, USS Explorer) | Application Explorer or Table Results view | Copy
Application Explorer or Table Results view | Remote System view (local, MVS Explorer, USS Explorer) | Copy
Windows Explorer | Application Explorer or Table Results view | Copy or link (depending on the response in the prompt dialog).
Application Explorer or Table Results view | Windows Explorer | Move
Eclipse views (Project Explorer, Navigator...) | Application Explorer or Table Results view | Move or copy (depending on the source resource, see note below)
Application Explorer or Table Results view | Eclipse views (Project Explorer, Navigator...) | Move or copy (depending on the target resource, see note below).
Note:
  • By default, a drag and drop operation between Linked Eclipse Resources and other Linked Eclipse Resources or local workspace resources trigger a move operation. By using modifier keys, the drag and drop operation can be changed to a copy or link operation. The modifier key ctrl results in a copy, and the modifier key alt results in a link.
  • By default, a drag and drop operation between Linked Eclipse Resources and non-workspace resources (remote resources) triggers a copy operation.
  • Other drag and drop scenarios of linked Eclipse resources are not supported.
Parent topic: Eclipse Function Package


Linked Properties for the Eclipse Function Package

The following linked properties are supported by the Eclipse function package:

Linked Property Name | Value Type | Content
Editor Properties:
Is Active Editor Dirty | Boolean | Returns true if the active editor in Eclipse is dirty, otherwise false. An editor is marked dirty if the content of the editor has changed since the last save operation.
Preferences:
Is Auto Build | Boolean | Auto build attribute of an Eclipse project.
Resource Properties:
Content Type ID | String | Content type ID of an Eclipse resource, for example, value: org.eclipse.core.runtime.text
Derived | Boolean | Determines whether the Eclipse resource is derived.
Editable | Boolean | Read-only attribute of an Eclipse resource.
Error Count | Numeric | Error count attribute of an Eclipse resource.
Last Modified | Numeric | Last modified attribute of an Eclipse resource in the UNIX system time format, for example, value: 1442839802634
Last Modified (Formatted) | String | Last modified attribute of an Eclipse resource in the local OS date format, for example, value: 9/21/15 2:50 PM
Linked | Boolean | Determines whether the resource is a linked to another resource, folder or file.
Location | String | Absolute path to the Eclipse resource, for example, value: C:\EclipseWorkspaces\MyWorkspace\TestProject\TestFolder\TestFile.txt
Name | String | Name of the Eclipse resource, for example, value: TestFile.txt
Name With Remote Location | String | Name of the Eclipse resource with a remote location in brackets for remote resources.
Paste Allowed | Boolean | Determines whether a paste action on this resource is permitted.
Path | String | Workspace relative path of a resource, for example, value: \TestProject\TestFolder\TestFile.txt
Project Natures | String | Natures of an Eclipse project concatenated by the pipe sign (|), for example, value: com.microfocus.eclipse.project.cobolNature|com.microfocus.eclipse.edt.core.edtNature
Project Open | Boolean | Attribute indicating whether an Eclipse project is open or closed.
Size | Numeric | Size of an Eclipse file in bytes; returns “0” for Eclipse projects and folders.
Suffix | String | Suffix of an Eclipse file (without dot), for example, value: txt
Warning Count | Numeric | Warning Count attribute of an Eclipse resource.
Team Properties:
Author | String | The author of a revision.
Comment | String | The comment for this file revision.
Timestamp | String | The timestamp of this revision in the UNIX system time format, for example: 1442839802634.
Timestamp (Formatted) | String | The timestamp of this revision in the local OS date format, for example: 9/21/15 2:50 PM.
Content Identifier | String | The unique identifier for this file revision.
Local Content Identifier | String | The content identifier for the local resource. In Subclipse this is the revision number.
Local Author | String | The author of the revision corresponding to the local resource.
Kind of Synchronization | String | Describes the kind of synchronization of the local resource. For example, after editing a resource kind of synchronisation has the value “[outgoing change]”.
Change portion | String | Describes the change portion of the kind of synchronization of the local resource. For example, after editing a resource the change portion has the value “[change]”.
Change direction | String | Describes the change direction of the kind of synchronization of the local resource. For example, after editing a resource the change direction has the value “[outgoing]”.
Synchronization Info | String | Describes the difference between the local resource and the repository resource. For example, after editing a resource synchronization has the value “outgoing change”.

The values of the Eclipse linked properties are managed by Eclipse and AWM internally. The Eclipse function package does not provide modeled update operations to change a value of such a linked property directly.

The values of the Eclipse team properties are provided by the Eclipse Team API. Not all of these properties are supported by every source control system. If a team property is not supported, the value of the property is blank.

All those linked properties depend on an Eclipse resource. It is necessary to define the correct Resource Identifier attribute in the property definition.

Linked Property Resource Id
Parent topic: Eclipse Function Package
Related information
Property


Tool Types for the Eclipse Function Package

  • Build Project
  • Check Resource Exists
  • Close Editor
  • Close Project
  • Command Handler
  • Compare Files
  • Copy Resource
  • Copy Resource To Clipboard
  • Create Resource
  • Delete Resource
  • Edit Local File
  • Get Eclipse Projects
  • Get File System Path
  • Get Local History
  • Get Resource Children
  • Get Workspace Path
  • Synchronize Eclipse Elements
  • Move Resource
  • Open Project
  • Open Wizard
  • Paste Resource From Clipboard
  • Refresh Resource
  • Rename Resource
  • Select Resource
  • Show Local History
  • Show Properties Dialog Box
Parent topic: Eclipse Function Package


Build Project

Function:

This tool builds the selected Eclipse projects. It supports mass processing.

Tool Attribute:

Attribute Type Description
Build Type String The type of build.

Valid values include:

Incremental
Build only resources that have been changed since the last build.
Full
Discard all previously built states and builds all resources again.
Clean
Discard any additional state that has been computed as a result of previous builds, and returns the project to a clean state.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | Element/MassProcessing | The Eclipse path to the resource.
Parent topic: Tool Types for the Eclipse Function Package


Check Resource Exists

Function:

This tool can be used to check whether Eclipse resources exist. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/ MassProcessing | Eclipse resource ID of the resource(s) whose existence is to be checked.
2 [M] | O | String/ MassProcessing | Referencing a property of type Boolean which contains the modeled property “True value” if the resource exists, and the modeled property “False value” otherwise.
Parent topic: Tool Types for the Eclipse Function Package


Close Editor

Function:

The tool "Close Editor" is typically a component of the Close action. The tool checks whether the file for the given file input parameter is still open in the editor, and when necessary closes the editor. You are prompted to save any changes if the editor contains unsaved changes.

This tool should be integrated into an element action if the action must not be executed on files opened in an editor, for example, during a check-in action.

Note: This tool is not meant to be used in a modeled close action.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | File | The input parameter normally corresponds to that of the tool "Edit Local File".
Parent topic: Tool Types for the Eclipse Function Package


Close Project

Function:

This tool closes the selected Eclipse project if it is open. It supports mass processing.

Tool Attribute:

Attribute | Type | Description
With UI | Boolean | Specifies whether the Eclipse UI dialog should be used.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | The Eclipse path to the project.
Parent topic: Tool Types for the Eclipse Function Package


Command Handler

Function:

This tool directly executes a defined Eclipse command via the corresponding command handler ID.

Tool Attribute:

Attribute Type Description
Excution Mode Selection Specifies whether the tool is executed synchronously or asynchronous to other tools of the action. Valid values are:
  • Synchronous
  • Asynchronous

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The command ID.
2 [O] | I | String | The command handler ID.
3 [O] | I | String | The Eclipse resource ID of the resource upon which the command should be executed.

Sample command handlers are:

Command ID | Handler ID | Function
com.microfocus.eclipse.project.determineDirectives | com.microfocus.eclipse.project | Determines compile directives for COBOL or PL/I programs.
com.microfocus.eclipse.edt.ui.imsdbu.add | com.microfocus.eclipse.edt.ui | IMS database utility add.
com.microfocus.eclipse.edt.ui.imsdbu.load | com.microfocus.eclipse.edt.ui | IMS database utility load.
com.microfocus.eclipse.edt.ui.imsdbu.unload | com.microfocus.eclipse.edt.ui | IMS database utility unload.
com.microfocus.eclipse.edt.ui.imsdbu.zeroload | com.microfocus.eclipse.edt.ui | IMS database utility zero load.
com.microfocus.eclipse.edt.ui.dfed.str | com.microfocus.eclipse.edt.ui | Create record layout file.
com.microfocus.eclipse.edt.ui.dfed.slf | com.microfocus.eclipse.edt.ui | Create segment layout file.
com.microfocus.eclipse.project.generateCoverageReport | com.microfocus.eclipse.project | Generate coverage report.
com.microfocus.eclipse.project.generateProfilerReport | com.microfocus.eclipse.project | Generate profiler report.
com.microfocus.eclipse.edt.transformAsmIncludeToCopybook | com.microfocus.eclipse.edt.ui | Transform an Assembler macro to a COBOL copybook.
com.microfocus.eclipse.edt.transformCopybookToAsmInclude | com.microfocus.eclipse.edt.ui | Transform a COBOL copybook to an Assembler macro.
com.microfocus.eclipse.project.transformCopybookToProgram | com.microfocus.eclipse.project | Transform a COBOL copybook to a COBOL program.
com.microfocus.eclipse.project.transformProgramToCopybook | com.microfocus.eclipse.project | Transform a COBOL program to a COBOL copybook.
com.microfocus.eclipse.editor.compileDependentPrograms | com.microfocus.eclipse.editor | Compile dependent programs.
Parent topic: Tool Types for the Eclipse Function Package


Compare Files

Function:

The tool "Compare Files" opens two files in an Eclipse compare editor. The tool can be modeled to compare the two files (read only) or to merge them into one file (edit).

Attribute Type Description
Compare TypeD Selection Valid values are:
  • Simple Compare
  • Compare with Each Other

The Simple Compare type needs two file input parameters, whereas Compare with Each Other works on two selected AWM elements.

Enable Edit Input Parameter Boolean If true, an additional input parameter can be used to request edit support.

This attribute is only available if the compare type Simple Compare is selected.

Parameters for Simple Compare

Parameter No | I/O | Type | Description
1 [M] | I | File | File input parameter pointing to the first file to compare (left side in the compare editor).
2 [M] | I | File | File input parameter pointing to the second file to compare (right side in the compare editor)
3 [O] | I | Boolean | Whether the first file should be opened in edit mode; if edit mode is set to true, the first file must either be a workspace or a z/OS (MVS_PO_Member or MVS_SEQ) file.

Parameter for Compare with Each Other

Parameter No | I/O | Type | Description
1 [M] | I | File | File input parameter pointing to the files to be compared.

If using Compare with Each Other, two AWM elements must be selected at run time and the following modeling is required to support this compare type:

  • The compare action descriptor must be marked as a mass processing action.
  • The input file descriptors require the physical file names specified in the attribute Name Physical. If property references are used they must be resolvable by properties of the selected elements.
  • It is recommended to define an action enable condition with a selection count of "2".

The following rules also apply in this scenario:

  • The upper element of the selection is displayed on the left side of the editor.
  • Edit is not supported.
  • Both elements must be selected in one view.
Parent topic: Tool Types for the Eclipse Function Package


Copy Resource

Function:

This tool "Copy Resource" copies Eclipse resource(s) to the specified target path. It supports mass processing.

Tool Attribute:

Attribute | Type | Description
With UI | Boolean | Specifies whether the Eclipse UI dialog box should be used.
Existing Resource Handling Selection Specifies the handling of the scenario that the target resource already exists. Valid values include:
  • Replace: The target resource is replaced without a message issued.
  • Ignore: The target resource stays untouched.
  • Error: An error message is produced.
  • From Parameter: The handling is defined by an additional tool parameter.

Parameters:

Parameter # | I/O | Type | Description
1 [M] I String/MassProcessing The Eclipse path to the source's resource.

If the tool attribute With UI is set to true, this is the only enabled parameter.

2 [M] | I | String | The Eclipse path to the target folder.
3 I String Defines handling when the target resource already exists. Valid values include:
  • Replace
  • Ignore
  • Error (default). Only enabled if the tool attribute Existing Resource Handling is set to From Parameter.
4 [O] | I | String | New name of the target resource. Only enabled if the first input parameter is of type “String”.
Parent topic: Tool Types for the Eclipse Function Package


Copy Resource To Clipboard

Function:

This tool copies the selected Eclipse resource to the clipboard for a later paste action. It supports mass processing.

The corresponding paste action works cross platform.

For example, paste is supported:

  • In a folder of your local operating system.
  • In the MVS Explorer.
  • In the USS Explorer.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | The Eclipse path to the source resource.
Parent topic: Tool Types for the Eclipse Function Package


Create Resource

Function:

This tool creates new Eclipse folders or files. It supports mass processing.

Tool Attribute:

Attribute | Type | Description
Create Link | Boolean | Specifies whether the created resource is a linked resource.
With UI | Boolean | Specifies whether the Eclipse UI dialog box is used to prompt for additional parameters.
Resource Type Selection Specifies the Eclipse resource type to be created. Valid values include:
  • Folder
  • File
  • From Parameter. Use this value to enable the Eclipse resource type to be defined by a tool input parameter.
Existing Resource Handling Selection Specifies handling when the target resource already exists.
Valid values include:
Replace
The target resource is replaced without a message.
Ignore
The target resource stays untouched.
Error
An error message is produced.
From Parameter
The handling is defined by an additional tool parameter.
Path Includes resource Name | Boolean | Specifies whether the name of the Eclipse resource is included in the resource path.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | Eclipse path to the new resource and must be the full path if the attribute “Including Filename” is set to “true”.
2 [O] I String/MassProcessing The type for the new resource.

Only enabled if the tool attribute Resource Type is set to From Parameter.

Valid values include:
  • Folder
  • File.
3 [O] | I | String/MassProcessing | Name of the new resource. Only enabled if the tool attribute Including Filename is set to false.
4 [O] I String Specifies handling when the target resource already exists. Valid values include:
Replace
The target resource is replaced without a message.
Ignore
The target resource stays untouched.
Error
An error message is produced.
Only enabled if the tool attribute Existing Resource Handling is set to From Parameter. Default value: Error
5 [O] | I | String/MassProcessing | Path to the linked resource. Only enabled if the tool attribute With UI is set to false and tool attribute Create Link is set to true. The path can be absolute or relative to the workspace.

Details:

  • This tool is executed as mass processing in the following scenario:
    • Resource path type (first parameter) is set to “MassProcessing":
      • Type of the third input parameter (Name of the new resource) must be set to "MassProcessing" if present.
      • Type of the fifth input parameter (path to the linked resource) must be set to "MassProcessing" if present.
    • Resource path type is set to “String” and
      • Type of the third input parameter (Name of the new resource) is set to "MassProcessing" if present and type of the fifth input parameter (path to the linked resource) is set to "MassProcessing" if present.
      • the input parameter referred to the linked path of the new resource is modeled and is “MassProcessing".
  • The type of the third and fifth input parameter (name and linked path of the new resource) must be the same.
  • If the tool is a mass processing tool, the second input parameter (type of the new resource) may be of type “String” or “MassProcessing".
    • “String”: All new resources will be create with the same type.
    • “MassProcessing”: Each resource will be created with the corresponding type.
Parent topic: Tool Types for the Eclipse Function Package


Delete Resource

Function:

This tool deletes the selected Eclipse resource. It supports mass processing.

Tool Attribute:

Attribute | Type | Description
With UI | Boolean | Specifies whether the Eclipse UI dialog box should be used.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | Element /MassProcessing | The Eclipse path to the resource.
Parent topic: Tool Types for the Eclipse Function Package


Edit Local File

Function:

The tool "Edit Local File" is a component of the Edit action. It is used to open any file in the corresponding editor. The prerequisite for this is that the source to be edited is in the local workspace in the Eclipse project.

In an action, the AWM tool "Locate Persistent File" must precede the tool "Edit Local File" if the local file has been created with the AWM "Create Persistent File" tool.

The tool "Edit Local File" can also be used on temporary local files. For example, in this context it is intended for Remote Edit scenarios in which the Save and Close actions are used.

Tool Attribute:

Attribute | Type | Description
Editor ID [O] | String | Specifies the identifier of the Eclipse editor that should be used to open the file. This attribute is optional and does not have a value by default.

If no editor identifier is specified, the standard Eclipse rules apply to open the file. This means that the editor used to open the file depends on the file suffix or the editor which was used last to open this file.

At run time the user can customize the default editor associated to a file suffix in the Eclipse preferences (Window > Preferences > General > Editors > File Associations). This means that at run time the user could decide which editor is to be used, if the editor identifier is not specified.

If you want to make sure that a specific editor is used for all users, you should specify the editor identifier in the AWM model. To find the editor identifier, open the editor and press Alt+Shift+F1 in the editor pane. A dialog box opens and displays the editor identifier among other information.

Example:

Press Alt+Shift+F1 in the Micro Focus COBOL Editor to see that its editor identifier is com.microfocus.eclipse.editor.cobol.CobolEditor.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | File | The associated file descriptor's type must be Workspace File. In editing scenarios where the file is located on a remote system, this file descriptor typically corresponds to the output parameter of the AWM tool LocatePersistent File or Create Temporary File.
Parent topic: Tool Types for the Eclipse Function Package


Get Eclipse Projects

Function:

This tool returns a file descriptor pointing to a file that contains all Eclipse projects that meet the specified nature and repository provider criterion, if specified.

Note: All closed projects defined in the workspace are returned even if they do not meet the specified nature.

Tool Attribute:

Attribute | Type | Description
Eclipse Project Matchname | String | The match name to be used by the tool to identify Eclipse projects. The default value is ECLIPSE_PROJECT.
Repository Provider Filter | String | The repository provider to be used to filter result of the “Get Eclipse Projects” tool. This attribute is optional. Valid values are, for example, “com.accurev.ide.eclipse.AccuRevProvider” to filter AccuRev projects, “org.tigris.subversion.subclipse.core.svnnature” to filter Subclipse projects or “org.eclipse.egit.core.GitProvider” to filter EGit projects.

Filtering by the 'Repository Provider Filter' attribute is meant to show only projects which are shared by a certain source management system, for example, AccuRev, SVN, GIT, and so on.

How to get the value for the Repository Provider Filter attribute:

Open the Plug-ins view in Enterprise Developer. Find the plug-in of the Repository Provider plug-in that refers to the extension “org.eclipse.team.core.repository”. Normally, the core plug-in of the Repository Provider plug-in refers to the extension.

Open the plug-in and navigate to the “Extensions” tab. Expand the “org.eclipse.team.core.repository” extension and select the “Repository Provider”. The value of the “id:” attribute in the “Extension Element Details box” is the repository provider id that is needed.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Specifies a regular expression filtering the Eclipse projects by project nature.
2 [M] | O | File | Specifies file descriptor pointing to the result file containing the returned Eclipse projects.

The output file descriptor should be of type InputStream and have the following structure:

Number | Target ID
1 [M] | The Eclipse Resource ID of the project.
2 [M] | A Match Name identifying the AWM element type.
Parent topic: Tool Types for the Eclipse Function Package


Get File System Path

Function:

This tool returns the absolute file system path to an Eclipse resource. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | Element /MassProcessing | Specifies the Eclipse path to the resource.
2 [M] | O | String /MassProcessing | Specifies the absolute file system path of the Eclipse resource.
Parent topic: Tool Types for the Eclipse Function Package


Get Local History

Function:

This tool returns the local history entries for the given Eclipse resource in a file descriptor.

Note: Micro Focus recommends that you do not use this tool. There is no other tool available within the Eclipse package which could process the entries generated by Get Local History. Use Show Local History to display and to retrieve history entries within one dialog.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | Specifies the Eclipse resource ID.
2 [M] | O | File | Specifies the file descriptor pointing to the result file containing the local history entries for the given Eclipse resource.

The output file descriptor should be of type InputStream and have the following structure:

Number | Target ID
1 [M] | Modification timestamp of the local history entry.
Parent topic: Tool Types for the Eclipse Function Package


Get Resource Children

Function:

This tool returns the children of an Eclipse resource via a file descriptor. The returned children can be filtered by an optional input parameter.

Tool Attribute:

Attribute | Type | Description
Folder Matchname | String | The match name to be used by the tool to identify Eclipse folders. The default value is ECLIPSE_FOLDER.
File Matchname | String | The match name to be used by the tool to identify Eclipse files. The default value is ECLIPSE_FILE.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse resource ID.
2 [O] | I | String | A regular expression to filter the returned children. The default value is .*.
3 [M] | O | File | A file descriptor pointing to the result file containing the returned children of the given Eclipse resource.

The output file descriptor should be of type InputStream and have the following structure:

No | Target ID
1 [M] | The Eclipse path of the child resource.
2 [M] | The match name used to identify the AWM element type.

Using the attributes Folder Matchname and File Matchname provides a flexible way of associating Eclipse resources to modeled element types. If you want to associate Eclipse files to different AWM element types with only one Get Resource Children tool, you must use a relationship Custom Match Name to map file suffixes to match names.

Example:

If an Eclipse folder contains COBOL and PL/I files and the AWM model contains different element types for COBOL and PL/I programs. In this scenario it is not sufficient to use the attributes Folder Matchname and File Matchname; it is necessary to define the Custom Match Name relationship as described below.

Relationship | Cardinality | Description
Custom Match Name | 0..* | Mapping to return a custom match name for Eclipse files with a certain suffix.

Custom Match Name Relationship

If you need to create elements of different element types, you can define "custom match name" complex attributes for the tool.

Attribute | Type | Description
Suffixes | String | List of suffixes, separated by blank, to return the custom match name for.
Match Name | String | The match name to be returned for Eclipse files with a matching suffix.
Parent topic: Tool Types for the Eclipse Function Package


Get Workspace Path

Function:

This tool returns the workspace path of an Eclipse resource derived from the given absolute file system path. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | Element /MassProcessing | Specifies the absolute file system path of the Eclipse resource.
2 [M] | O | String | Specifies the Eclipse path to the resource.
Parent topic: Tool Types for the Eclipse Function Package


Synchronize Eclipse Elements

Function:

This tool synchronizes AWM linked elements with the corresponding Eclipse resources.

Micro Focus recommends using the Eclipse function package attributes to trigger this synchronization process. If the synchronization process is disabled in the function package attributes, it is still supported to model the synchronization tools in action descriptors, for example, as a global action.

Tool Attribute:

Attribute | Type | Description
Action Selection Specifies the action for the synchronizer to perform.

Possible values include:

SYNCHRONIZE
Executes a once synchronization of all linked Eclipse properties for the loaded AWM application.
START
Starts the background synchronization process for all linked Eclipse properties of the loaded AWM application.
STOP
Stops the background synchronization process for all linked Eclipse properties of the loaded AWM application.
Project Name Filter | Regular expression | Filter for the Eclipse project names to be synchronized.
Project Nature Filter | Regular expression | Filter for the Eclipse project natures to be synchronized.
Parent topic: Tool Types for the Eclipse Function Package
Related information
Attributes for the Eclipse Function Package


Move Resource

Function:

This tool moves an Eclipse resource to the given target path. It supports mass processing.

Tool Attribute:

Attribute | Type | Description
With UI | Boolean | Specifies whether the Eclipse UI dialog box should be used.
Existing Resource Handling Selection Specifies the handling of the scenario that the target resource already exists. Valid values include:
Replace
The target resource is replaced without notification.
Ignore
The target resource stays untouched.
Error
An error message is produced.
From Parameter
The handling is defined by an additional tool parameter.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | The Eclipse path to the resource. All other parameters are disabled if the tool attribute With UI is set to true.
2 [M] | I | String | The Eclipse path to the target resource of the move action.
3 [O] I String Defines the handling of the scenario that the target resource already exists. Valid values include:
Replace
The target resource is replaced without notification.
Ignore
The target resource stays untouched.
Error
An error message is produced.

Default: Error

Parent topic: Tool Types for the Eclipse Function Package


Open Project

Function:

This tool opens the selected Eclipse project, if it is closed. It supports mass processing.

Tool Attribute:

Attribute | Type | Description
With UI | Boolean | Specifies whether the Eclipse UI dialog should be used.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | The Eclipse path to the project.
Parent topic: Tool Types for the Eclipse Function Package


Open Wizard

Use this tool to open an Eclipse wizard.

Tool Attribute:

Attribute Type Description
Wizard Type Selection The type of wizard to be opened. Valid values include:
New Project
Opens the New Project wizard.
New Example
Opens the New Example wizard.
New Other
Opens the New Other wizard.
Import Resource:
Opens the Import wizard.
Export Resource:
Opens the Export wizard.
From Wizard ID
Opens the wizard specified by the tool parameter.

Parameters:

Parameter # | I/O | Type | Description
1 [O] | I | String | The identifier of the wizard to be opened. Only enabled if the attribute Wizard Type is set to From Wizard ID.

Example Wizard IDs are:

Wizard ID | Function
org.eclipse.ui.wizards.new.file | New file wizard
com.microfocus.eclipse.edt.ui.wizards.NewAsmLinkFileWizard | New assembler linked file wizard
com.microfocus.eclipse.edt.ui.wizards.NewAssemblerMacroFileWizard | New assembler macro file wizard
com.microfocus.eclipse.edt.ui.wizards.NewAsmSourceFileWizard | New assembler program wizard
com.microfocus.eclipse.edt.ui.wizards.NewBmsFileWizard | New BMS file wizard
com.microfocus.eclipse.project.ui.NewCopyFileWizard | New COBOL copybook wizard
com.microfocus.eclipse.project.wizards.new_copylib_project | New COBOL copybook wizard
com.microfocus.eclipse.edt.ui.wizards.NewJclFileWizard | New JCL file wizard
com.microfocus.eclipse.edt.ui.wizards.new_mss_project | New mainframe COBOL project wizard
com.microfocus.eclipse.pli.ui.wizards.new_mainframe_pli_project | New mainframe PL/I project wizard
com.microfocus.eclipse.pli.ui.wizards.new_pli_include_file | New PL/I include wizard
com.microfocus.eclipse.remote.wizards.RemoteCopylibProjectWizard | New remote COBOL copybook project wizard
com.microfocus.eclipse.remote.wizards.RemoteCobolProjectWizard | New remote COBOL project wizard
com.microfocus.eclipse.remote.ui.NewRemoteLinkedFolderWizard | New remote linked folder wizard
com.microfocus.eclipse.edt.ui.wizards.NewMainframeRemoteCobolProjectWizard | New remote mainframe COBOL project wizard
com.microfocus.eclipse.pli.ui.wizards.remote.NewMainframeRemotePliProjectWizard | New remote mainframe PL/I project wizard
com.microfocus.eclipse.pli.ui.wizards.new_pli_source_file | New PL/I program wizard
com.microfocus.eclipse.pli.ui.wizards.remote.RemotePliProjectWizard | New remote PL/I project wizard
com.microfocus.eclipse.coboljvm.wizards.NewCobolClassWizard | New COBOL JVM class wizard
com.microfocus.eclipse.coboljvm.wizards.NewInterfaceWizard | New COBOL JVM interface wizard
com.microfocus.eclipse.coboljvm.wizards.CobolJVMPackageWizard | New COBOL JVM package wizard
com.microfocus.eclipse.coboljvm.wizards.CobolJVMProjectWizard | New COBOL JVM project wizard
com.microfocus.eclipse.coboljvm.wizards.CobolJVMSourceFolderWizard | New COBOL JVM source folder wizard
com.microfocus.eclipse.project.wizards.new_project | New COBOL project wizard
com.microfocus.eclipse.project.ui.NewCobolFileWizard | New COBOL program wizard
com.microfocus.eclipse.edt.ui.wizards.new.region | New Enterprise Server wizard
com.microfocus.eclipse.remote.wizards.ImportConvertCobolProjectWizard | Convert MF local Projects to remote projects
com.microfocus.eclipse.remote.wizards.ImportPureRemoteCobolProjectWizard | Import remote projects
com.microfocus.eclipse.migration.wizards.ImportNetExpressProjectWizard | Convert NetExpress projects
Parent topic: Tool Types for the Eclipse Function Package


Paste Resource From Clipboard

Function:

This tool pastes the content of the clipboard to the specified Eclipse path.

Pasting folders and files copied in Windows is supported.

Note: You cannot paste files copied in the MVS or USS Explorer.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the resource where the paste should go. This parameter is optional if the clipboard contains only Eclipse projects.
Parent topic: Tool Types for the Eclipse Function Package


Refresh Resource

Function:

This tool refreshes the selected Eclipse resource by updating the Eclipse resource attributes if they were updated outside of Eclipse. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | The Eclipse path to the resource.
Parent topic: Tool Types for the Eclipse Function Package


Rename Resource

Function:

This tool renames the selected Eclipse resource. It supports mass processing.

Tool Attribute:

Attribute | Type | Description
With UI | Boolean | Specifies whether the Eclipse UI dialog box should be used.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MassProcessing | The Eclipse path to the resource.
2 [M] | I | String/MassProcessing | The new name of the Eclipse resource. Only applies if the tool attribute With UI is set to false.

If the input parameter referring to the Eclipse path of the resource is of type “MassProcessing” and the input parameter referring to the new name is of type “String” all resources are renamed with the same new name.

Parent topic: Tool Types for the Eclipse Function Package


Select Resource

Function:

This tool opens the Eclipse Resource Selection dialog box. The tool returns the path to the selected Eclipse resource. It supports mass processing.

Tool Attributes:

Attribute | Type | Description
Multiple Selection | Boolean | Specifies whether the dialog enables multiple selections.
Initial Selection | Boolean | Specifies whether the dialog field is initialized with the selected resource.
Prompt Text | Boolean | Specifies whether a prompt text is expected as input parameter.
Project Nature | Boolean | Specifies whether a project nature is expected as input parameter.
Project Name | Boolean | Specifies whether a project name is expected as input parameter.
Selection Type | Selection | Specifies the Eclipse resource type that can be selected. Valid values are: Any, Project, Folder, File, From Parameter. From Parameter means the Eclipse resource type is defined by a tool input parameter.

Parameters:

Parameter # | I/O | Type | Description
1 [O] | I | String/MassProcessing | Eclipse resource ID(s) to be preselected. Only enabled if the attribute "Initial Selection" is set to "true".
2 [O] | I | String | Dialog prompt text.
3 [O] | I | String | A regular expression on project natures to filter projects to be shown in dialog.
4 [O] | I | String | A regular expression on project names to filter projects to be shown in dialog.
5 [O] | I | String | Type of resources to be selected. Valid values are: any, project, folder, file (only relevant, if the tool attribute "Selection Type" is set to "From Parameter").
6 [M] | O | File/String/MassProcessing | Eclipse paths to the selected Eclipse resources.

Details:

If the output parameter type is "File", the paths of all selected Eclipse resources are written in the file descriptor.

Parent topic: Tool Types for the Eclipse Function Package


Show Local History

Function:

This tool shows the standard Eclipse local history view for the given Eclipse resource.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/MasProcessing | The Eclipse resource ID.
Parent topic: Tool Types for the Eclipse Function Package


Show Properties Dialog Box

Function:

This tool opens the native Eclipse Properties dialog box for the selected Eclipse resource.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse resource ID.
Parent topic: Tool Types for the Eclipse Function Package


ISPF Function Package

This section details ISPF function package support, and attaching and modeling using ISPF tools and ISPF dialog box tools.

  • Attributes for the ISPF Function Package
  • Tool Types for the ISPF Function Package
  • Details for the ISPF Function Package
Parent topic: Function Packages


Attributes for the ISPF Function Package

Attribute | Type | Description
Exitparm | String | Permits the transfer of parameters to the ISPF tool call-up exit TAUTOXA1. Dynamic references of variables are allowed. Default value: PROD
Parent topic: ISPF Function Package


Tool Types for the ISPF Function Package

  • Execute ISPF Command
    Models ISPF command tools.
  • Execute ISPF Dialog Application
  • Execute ISPF Edit Macro
Parent topic: ISPF Function Package


Execute ISPF Command

Function:

ISPF command tools call a procedure or a program in an ISPF environment. In order to interact correctly with the AWM interface, the ISPF tools must observe certain implementation rules. See Attaching ISPF Tools for more information.

Tool Attributes:

Attribute | Type | Description
Invocation Form [M] Selection Specifies how a procedure or program is called in the ISPF environment. Valid values are:
REXX
Called from AWM as REXX subroutine (REXX call statement) which can only be used for attached REXX procedures.
CMD
The attached procedure or program is called from AWM using the ISPF command ISPEXEC SELECT CMD(…)
PGM
The attached program is called from AWM using the ISPF command ISPEXEC SELECT PGM(...)
Program ID [M] | String | Name of the procedure (REXX, CLIST) or program.
Run_As_Job Selection Specifies whether the tool is executed online or as batch job. Valid values are:
NO
The tool is executed directly in the attached IPSF environment and the UI is blocked until the tool has finished executing.
Tool Job
The tool is submitted to JES by the attached tool, for example, by the attached REXX procedure.
Model Job
The attached tool is submitted to JES by AWM.

See Batch Execution for more information.

After_Job_Action [O] ActionDescriptor Only enabled when "Run As Job" is set to "Tool Job" or "Model Job".

References a modeled action which can be executed when the corresponding job has ended. The action is added to the context menu of the job in the Jobs view.

See Batch Execution for more information.

Tool Parameter

Tool input and output parameters have to be defined corresponding to the expected input and output parameters of the attached ISPF tool.

Parent topic: Tool Types for the ISPF Function Package
Related information
Attaching ISPF Tools
Batch Execution


Execute ISPF Dialog Application

Function:

The "Execute ISPF Dialog Application" tool lets you integrate an ISPF dialog application directly as an AWM application. The ISPF application runs in a user server of the z/Server environment on the remote system. Only the UI is executed on the client side.

Modeling tools of type "Execute ISPF Dialog Application" requires a z/Server installation on z/OS.

Tool Attributes:

Attribute | Type | Description
Invocation Form [M] | Selection | Specifies how the ISPF application is called. Permitted values are REXX, CMD or PGM.
Program Name [M] | String | Name of the ISPF application.

Tool Parameter

Tool input and output parameters have to be defined corresponding to the expected input and output parameters of the attached ISPF tool.

Relationship: Used Panel

Attribute | Type | Description
Panel Name [M] | Execute ISPF Dialog | References a tool for an ISPF panel included in the dialog application.

Further Information:

Calling an ISPF dialog application can be modeled in a number of ways:

  • REXX (called as a REXX subroutine)
  • CMD (called using an ISPF service Select CMD(...))
  • PGM (called using the ISPF service Select PGM(...) Parm(...))

When attaching ISPF dialog tools, the ISPF dialog application runs on z/OS in a separate ISPF batch environment managed by the Micro Focus z/Server. ISPF panel fields are directly exchanged with AWM-modeled dialog fields.

An ISPF tool which displays at least one ISPF panel has to be defined in the AWM model using the tool descriptor "Execute ISPF Dialog".

The advantage of this approach is that the attached ISPF tool which implements the dialog application, does not need to be changed.

Customization is only necessary in the ISPF panels called in the attached application. The ISPF panels are extended by calls to the REXX procedure TAUZCDIF, which handles the communication between the ISPF dialog application and the client dialogs.

The REXX procedure TAUZCDIF can be called in three ISPF panel sections:
  • INIT section
  • REINIT section
  • PROC section
Calling TAUZCDIF in the INIT or REINIT section is used to pass the values of the panel fields and ISPF variables relevant for the dialog between the ISPF application and the client dialog in both directions.

Calling TAUZCDIF in the PROC section is only used for ISPF table processing.

The extension of the ISPF panel in the INIT or REINIT section has the following format:

VGET(TAUTODIA) SHARED
IF (&tautodia = 'Y')

   VGET(TAUERR) SHARED
   &taupanel = '<panel name>'
   &taucurs = .CURSOR
   &tauttl = '<panel title>’
   &taups = 'I'
   &tauparms = ‘<var1> <var2> … <varn>’
   *REXX(*,TAUPANEL,TAURESP,TAUPS,TAUPARMS,TAUCURS,TAUERR,TAUTTL,
         (TAUZCDIF))
   IF (&tauerr ^= &z)
      VGET(TAUTOZCP) SHARED
      &tautozcp = '&tautozcp &tauerr'
      VPUT(TAUTOZCP) SHARED

The ISPF panel extension starts with a VGET statement of the shared pool variable TAUTODIA which is set to ‘Y’ by the ISPF dialog tool adapter TAUZCIFD.

Some special variables are defined and explained in the table below.

The REXX procedure TAUZCDIF is only called from the z/Server and invoked from AWM. This means that the ISPF dialog application still works in an ISPF online session invoked in a 3270 emulator session.

It is important that all ISPF variables which are not fields in the BODY section of the panel are explicitly passed to the panel REXX: this means particularly the special variables explained below but also all other ISPF variables which are not declared as input or output fields in the panel’s BODY section but whose values are to be passed to the Client dialog.

The * in the parameter list of the TAUZCDIF call ensures that all ISPF variables defined as input or output fields in the panel’s BODY section are passed to the Client dialog.

Note: If the panel contains a MODEL section, only the ISPF variables of the MODEL section are passed by the * parameter to the panel REXX. In this case, all other ISPF variables of the BODY section have to be explicitly passed to the panel REXX as well.

The special variable TAUERR is fetched from the ISPF shared pool before calling the panel REXX, so that dialog error conditions detected in a preceding dialog step can be passed to the panel REXX. The panel REXX sends the error message to the client and the user is informed of the error by an error message dialog.

The call to the panel REXX TAUZCDIF is followed by a check that the special variable TAUERR has some content. If it does, the content is concatenated to the actual content of the ISPF variable TAUTOZCP which contains error messages from the tool execution and is evaluated by the tool adapter TAUZCIFD.

Special variable | Description
TAUPANEL | Name of the panel
TAUPS | Panel section (I, R or P)
TAURESP | ISPF variable in which the dialog response (Enter or PF3) is returned
TAUCURS | Name of the field in which the cursor is positioned
TAUTTL | Title of the panel
TAUERR | ISPF variable containing error messages from the dialog tool
TAUPARMS | List of names of all variables to be passed to the SWT dialog. The special variable TAUPARMS contains a list of variable names whose values are passed to the Client dialog in the sequence in which they are written in the TAUPARMS string

On the client side, a standard input dialog corresponding to the ISPF panel must be defined in the AWM model as a tool of type "Execute ISPF Dialog".

The panel fields defined for a tool of type "Execute ISPF Dialog" must correspond exactly to the variables defined under TAUPARMS in the extended ISPF panel. The extension of the ISPF panel in the PROC section of a non TBDISPL panel has the following format:

IF (&tautodia = 'Y')
   IF (&TAURESP = 'Exit')
      .RESP = END

An AWM feature can be used to generate all the AWM model components, which are necessary to model a tool of type "Execute ISPF Dialog Application", from an XML file. See ISPF Panel Model Generator for more information.

  • Execute ISPF Dialog
  • ISPF Table Display Support
  • Special Processing for ISPF Edit or ISPF Browse
  • Execute ISPF Dialog Command
    Models ISPF panel commands representing line commands on an ISPF panel.
  • ISPF Dialog Exits
  • ISPF Panel Model Generator
Parent topic: Tool Types for the ISPF Function Package
Related information
The "UI Category" Attribute


Execute ISPF Dialog

Function:

This tool represents an ISPF panel which is called by a tool of type "Execute ISPF Dialog Application" and describes how the panel fields are displayed in an AWM-modeled dialog.

Tool Attributes:

Attribute | Type | Description
Panel Name [M] | String | Name of the corresponding ISPF panel.
Program ID [M] | String | Name of the ISPF application in which the panel is used.
Dialog Description [O] | String | A short description of the dialog.
Dialog Title | String | The title of the AWM dialog box.
Validate Action | Action Descriptor | A reference to an Action Descriptor used to validate the dialog input fields when the user clicks OK.

Relationship: ISPF Dialog has Panel Fields

Attribute | Type | Description
Field Property [M] | Property | Reference to the property definition describing the panel field. The field contents, which are exchanged when the corresponding ISPF panel is called in the ISPF dialog running on the remote system, are defined by the tool's modeled panel fields. The panel fields defined for a tool of type "Execute ISPF Dialog" must correspond exactly to the variables defined under TAUPARMS in the extended ISPF panel. See Execute ISPF Dialog Application for more information.
Seq No [M] | Integer | Order of the panel fields corresponding to the TAUPARMS definition in the ISPF panel

Tool Parameters:

The layout of the AWM dialog representing the ISPF panel is defined by the tool's modeled input parameters, which are typically references to panel field properties, but could be other properties as well. This tool does not have output parameters.

Further Information

An AWM feature generates all the AWM model components, which are necessary to model a tool of type "Execute ISPF Dialog", from an XML file. See ISPF Panel Model Generator for more information.

Parent topic: Execute ISPF Dialog Application
Related information
Execute ISPF Dialog Application
ISPF Panel Model Generator


ISPF Table Display Support

In order to support an ISPF Table Display dialog, some additional extensions are necessary.

Some additional special variables are provided for the Table Display support as defined in the following table:

Special variable | Description
TAUTAB | Name of the ISPF table to display
TAUTABV | List of the table variable names
TAUSCAN | ‘N’ -> no scan argument is defined for the ISPF table ‘Y’ -> a scan argument is defined for the ISPF table
TAUCRP | Variable containing the value of the current row pointer
TAUSELS | Variable containing the number of selected lines

TAUCRP and TAUSELS are output variables set by the client.

A typical extension of the ISPF Table Display panel in the INIT or REINIT section looks like this:

VGET(TAUTODIA) SHARED
IF (&tautodia = 'Y')
   &resp = ''
   &tausels = 0
   &taupanel = '<panel name>'
   &tautab = '<table name>'
   &tauscan = 'N'
   &taups = 'I'
   &tautabv = ‘<tabvar1> … <tabvarn>’
   &tauparms = <var1> … <varn>'
   &tauerr = ''
   *REXX(*,TAUPANEL,TAURESP,TAUPS,TAUPARMS,TAUSELS,TAUCRP,TAUTAB,
            TAUSCAN,TAUTABV,TAUERR,(TAUZCDIF))
   IF (&tauerr ^= &z)
      VGET(TAUTOZCP) SHARED
      &tautozcp = '&tautozcp &tauerr'
      VPUT(TAUTOZCP) SHARED
   .autosel = YES
   &tau001 = &tabvar1
        .  .  .
   &tau00n = &tabvarn

The table variables must be saved after the call to the panel REXX TAUZCDIF to refresh the content in the PROC section.

Another special extension of Table Display panels is that the panel REXX TAUZCDIF is also called in the PROC section of the panel. This call sets the current row pointer of the table to the value returned by the client. Additionally, in the PROC section, the table variables are refreshed to the content returned by the client, and the ISPF table control variable ZTDSELS is set to the number of selected rows returned by the client.

A typical extension of the ISPF Table Display panel in the PROC section looks like this:

IF (&tautodia = 'Y')
   IF (&TAURESP = 'Ok')
       &taupanel = '<panel name>'
      &tautab = '<table name>'
      &ztdsels = &tausels
      &tabvar1 = &tau001
          .  .  .
      &tabvarn = &tau00n
      &taups = 'P'
      *REXX(*,TAUPANEL,TAUPS,TAUCRP,TAUTAB,(TAUZCDIF))
      IF (&TAURESP = 'Exit')
         .RESP = END

In the AWM model, a tool descriptor representing an ISPF Table Display dialog is characterized by its relation to a file descriptor. The file descriptor has to be defined as a structure Table with the type InputStream (see File descriptor).

The properties referenced by the file descriptor have to map to the table variables defined in the special variable TAUTABV.

By defining relations from the file descriptor to action descriptors, you can configure the panel and line commands of the ISPF table. The action descriptor must point to a tool descriptor of type "Execute ISPF Dialog Command".

Parent topic: Execute ISPF Dialog Application
Related information
File Descriptor


Special Processing for ISPF Edit or ISPF Browse

If the ISPF application contains an ISPF Edit or ISPF Browse call, this needs special treatment. This is the only situation where the ISPF application itself has to be changed. The application must call the Editor interface TAUZCEIF.

The customization in the REXX dialog application looks like this:

Call ISPF "8 VGET (TAUTODIA) SHARED"
If rc = 0 & tautodia = 'Y' Then
   Call TAUZCEIF "Browse "dsn
Else
   Address ISPEXEC “BROWSE “dsn

The Editor interface has the following parameters:

Parameter | Meaning
funccode Function code:
  • EDIT
  • BROWSE
dsn | Dataset name; can be in the form dsn(member)
WAIT [O] | 'WAIT' means the client process is waiting for the editor part to be closed; this parameter is not interpreted by the client process if the function code is BROWSE.
INIT(macro) [O] | The name of an initial ISPF edit macro, that is executed on the data set before it is transferred to the client. An initial ISPF edit macro is honored only with the function code EDIT. ISPF edit macro parameters may be given separated by a space after the name.
Parent topic: Execute ISPF Dialog Application


Execute ISPF Dialog Command

Function:

The "ExecuteISPF Dialog Command" tool is meant to model context menu actions for ISPF Dialog tools which are used to execute ISPF panel commands or ISPF line commands on ISPF tables. See Execute ISPF Dialog and Execute ISPF Dialog Application for more information.

Attributes:

Attribute | Type | Description
Command Name [M] | String | Corresponding value of the command in the ISPF dialog application, for example, line command value i,u,d.
Command Variable [M] | Property | Property which is defined as representation for the command line variable of the corresponding ISPF panel.

Tool Parameters

This tool does not use input or output parameters.

Parent topic: Execute ISPF Dialog Application
Related information
Execute ISPF Dialog
Execute ISPF Dialog Application


ISPF Dialog Exits

The following exits are defined for ISPF dialog support and can or should be adapted.

Exit | Type | Description
TAUTOXMS | REXX | Exit to format the layout of ISPF message in ISPF dialog processing. This exit is called when the ISPF application generates an ISPF message. The message ID and short and long message separated by hex low value are passed to the exit. The exit is expected to format and return the ISPF message in the form in which it should be displayed in the Eclipse dialog message area.
Parent topic: Execute ISPF Dialog Application


ISPF Panel Model Generator

The Workflow Manager client provides a feature to generate the model components which are needed to attach a tool of type "Execute ISPF Dialog Application". This feature needs as input a control file which describes the ISPF dialog application with its associated panels. The feature then generates the workflow model statements for this application as well as the extensions to the ISPF panels which are needed for the communication of the host application with the client dialog.

The control file contains rules in XML format which are necessary for the conversion of an ISPF Panel but cannot be directly interpreted from the ISPF panel source.

The control file can contain multiple ISPF applications. All panels which make up an application, excluding associated help panels, must be referenced in the control file. A panel is linked to its associated help panels by the parser.

Note: The control file must not contain any TAB character.
  • Creating a Panel Model Generator Control File
  • Maintaining a Control File on z/OS
  • Sample Control File
  • ISPF Panel Generator Control File XML Tags
  • Executing the ISPF Panel Model Generator
  • ISPF Panel Conversion Rules
Parent topic: Execute ISPF Dialog Application
Related information
Creating a Panel Model Generator Control File
Execute ISPF Dialog Application


Creating a Panel Model Generator Control File

An Eclipse Wizard lets you generate a panel model generator control file from scratch. The advantage of creating the control file this way is that you have a context-sensitive editing support.

A panel model generator control file can contain one or more panel control include files:

  • In Eclipse, click File > New > Other.
    Creating ISPF panel generator control file 1
  • Expand the sub-menu ISPF Panel Convert Control File then click and select Control File to create a basic panel model generator control file, or click and select Include File to create a panel control include file.

    Click Next to continue.
    Creating ISPF panel generator control file 2

  • Choose a parent folder and enter a valid file name in the File name field, and then click Finish.
    Creating ISPF panel generator control file 3
Parent topic: ISPF Panel Model Generator


Maintaining a Control File on z/OS

You can maintain the control file under your local file system as described above. Alternatively, you can maintain the control file on the mainframe. For this, a MVS PDS with record format VB and record length 1024 must be allocated on the mainframe. Then the local control file can be copied by copy and paste or drag and drop from the local file system (e.g. from the Project Explorer View) into this MVS PDS.

We recommend that you use the XML editor available in Eclipse when editing a control file from MVS Explorer.

Parent topic: ISPF Panel Model Generator


Sample Control File

Below is a sample for a dialog control file which consists of a main control file and an include file. The include file is referenced in the overallAttr XML tag of the main control file.

This control file is used to generate three AWM Execute ISPF Dialog tools for the ISPF "Endevor retrieve" application representing the ISPF panels NDVELIST, NDVSEL and TEST.

<tau:dialogAppls xmlns:tau="http://www.microfocus.com/controlFile/"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.microfocus.com/controlFile/
          bundleentry://824.fwk7518084/XSD/controlFile.xsd">
      <overallAttr location="COMPANY.PROD.PANELS">
            <replaceItem source="==>" target="" />
            <replaceItem source="j/n" target="" inputFormat="checkBox" />
            <include location="COMPANY.PROD.DCTL(GLOBAL)"/>
      </overallAttr>
      <dialogAppl invocationForm="CMD" label="Retrieve"
            location="COMPANY.LOCATION.PANELS" name="Endevor retrieve" pgm="NDVRETR">
            <panel name="NDVELIST" title="Retrieve list panel" table="NDVELIST"
                location="COMPANY.OTHERLOCATION.PANELS">
                <lineCommand value="R" label="Retrieve"/>
            </panel>
            <panel name="NDVSEL" title="Element selection"></panel>
      </dialogAppl>
</tau:dialogAppls>

Include File (optional)

<tau:overallAttr xmlns:tau="http://www.microfocus.com/include/"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.microfocus.com/include/
                 bundleentry://824.fwk19851888/XSD/include.xsd "
             location="COMPANY.LOCATION.PANELS">
             <replaceItem source="==>" target=""/>
             <replaceItem source="j/n" target="" inputFormat="checkBox"/>
             <replaceItem source="Test/Systemtest/Prod" target=""
                   inputFormat="comboBox" selectionValues="Test Systemtest Prod"/>
             <panel name="NDVSELSY" title="Select subsystem" table="NDVSYS">
                   <replaceItem source=". . ." target=""/>
                   <lineCommand value="S" label="Select" default_command="true"/>
             </panel>
</tau:overallAttr>

There is a sample for a dialog generation control file named DIALGDCT in your z/Server installation XML dataset. This sample dialog generation control file can be used to generate the sample dialog applications TAUPDTEL and TAUPDWEK.

Parent topic: ISPF Panel Model Generator


ISPF Panel Generator Control File XML Tags

XML Tag dialogAppls

Serves as Root element for the control file.

XML Tag overallAttr

The XML tag overallAttr summarizes conversion instructions that apply to all panels of the application.

Attribute | Description | Mandatory | Default
location | Fully qualified MVS dataset name where the panels are located. | No |

XML Tag dialogAppl

Attribute | Description | Mandatory | Default
name | Name of the application | No |
pgm | Program-Name: Name of the REXX or load module of the dialog application. | Yes |
label | Label in the context menu of the Eclipse dialog | No | Program name
invocationForm | Usage form of the application; allowed values: "CMD" and "PGM" | Yes |
location | Fully qualified MVS dataset name where the panels are located. | No |
categories | Whether to generate categories for underlying panels of this application; permitted values = “true“, “false”. | No | True
multi_line_command | Whether lineCommands of underlying panels can be executed on multi selections; permitted values = “true“, “false”. | No | False
table_header | Whether the last line in the BODY section before the MODEL section is interpreted as column headers for the table in the Eclipse dialog; permitted values = “true”, “false”. | No | False
tooltip | Whether the text after an input/output field is interpreted as a tooltip for this input/output field or as own output field with static text; permitted values = “true”, “false”. | No | Yes

XML Tag include

The XML tag include must be placed after the tag replaceItem within a XML block (e.g. overallAttr, dialogAppl) respectively at the beginning of the XML block if the XML block doesn’t contain any replaceItem tag.

Attribute | Description | Mandatory | Default
location | Fully qualified name of an MVS file containing outsourced control instructions for the panel conversion, which should be considered during an actual conversion process. | Yes |

XML Tag panel

Attribute | Description | Mandatory | Default
name | Member name of Panel source | Yes |
title | Title in Eclipse Dialog Window | No | Member name
table | ISPF table name | Yes for display table panels |
location | Location of the panel | Yes, if not set in an overlying tag |
categories | Whether to generate categories for this panel; permitted values = “true“, “false”. | No | True
table_header | Whether the last line in the BODY section before the MODEL section is interpreted as column headers for the table in the Eclipse dialog; permitted values = “true”, “false”. | No | False
multi_line_command | Whether lineCommands of this panel can be executed on multi selections Overwrites the multi_line_command attribute from the overlying application; permitted values = “true“, “false”. Default = “false” | No | True
tooltip | Whether the text after an input/output field is interpreted as a tooltip for this input/output field or as own output field with static text; permitted values = “true”, “false”. | No | Yes

XML Tag replaceItem

The XML tag is used to replace specific text in the panels with other texts in the Eclipse dialog window. The tag can be specified across applications, application specific, or just panel based.

The XML tag replaceItem must be the first tag within an XML block (e.g. overallAttr, dialogAppl).

Attribute | Description | Mandatory | Default
source | Panel source code | Yes |
target | Text with which the source code in the associated Eclipse dialog window should be replaced. | Yes |

XML Tag lineCommand

Attribute | Description | Mandatory | Default
value | Value of line commands in Table Display-Panel (In this case, a Verify command must exist in the panel) | Yes |
label | Label for the line command in the context-menu of the Eclipse Dialog-Window | False | Value of the line command
multi_line_command | Whether lineCommands of this panel can be executed on multi selections Overwrites the multi_line_command attribute from the overlying application Permitted values = “true“, “false”. | No | False
Default_command | Whether this line command should be executed on double click Only one line command can effectively be the default line command Permitted values = “true“, “false”. Default = “false” | No | False
Parent topic: ISPF Panel Model Generator


Executing the ISPF Panel Model Generator

The ISPF panel model generator utility can only be executed on a control file which is located as a member in an MVS PO data set. See Maintaining a Control File on z/OS for more information on how to get a control file from the local file system into an MVS PO data set.

  1. Locate a control file in the Remote Systems view.
  2. In the File Mappings view, click Add Mapping.
    Executing the ISPF panel model generator

    This opens the File Mapping Dialog.

  3. In the Generic Name field, type the Member name of the control file and type dctl in the Extension field. From the Type list, choose Member.

    Executing the ISPF panel model generator 3

  4. In the Remote Systems view, open the context menu and select the chosen control file, then click Refresh.

    The control file should now have the suffix .dctl.

  5. Right-click the control file, and then click Generate ISPF Panel Model. This generates the workflow model for the ISPF applications defined in the control file.

    Executing the ISPF panel model generator 4

    Executing the ISPF panel model generator 5

    At the end of the action, the generated model file is opened in the editor. If the option Extend panels by z/Server control statements is specified in the original ISPF, panels are automatically extended by the statements which are needed during execution time to exchange the panel data with the client dialog.

Parent topic: ISPF Panel Model Generator
Related information
Maintaining a Control File on z/OS


ISPF Panel Conversion Rules

The conversion of the ISPF panels to Eclipse dialogs is divided into two steps:

  • Physical parsing
  • Logical parsing

During the physical parsing step, the panel is parsed based on the attribute bytes defined in the panel’s ATTR section. The panel is composed of physical tokens which are separated by the attribute bytes.

Afterwards, the logical parsing step tries to generate the Eclipse dialog from the output of the physical parse process by applying some semantic interpretation rules.

These rules are described as follows:

  • Blank panel lines are ignored.
  • Consecutive lines which do not contain an input or output field are merged to a text area.ISPF variables which are referenced in a text area are converted into properties which are substituted by their current value at run time.

    If such a text block is followed by one or more lines which contain input or output fields, the last line of the text block is interpreted as the title for the following input or output field group.

  • Input fields of the panel are converted into writable combo boxes in the Eclipse dialog.
  • Output fields of the panel are converted into read-only text fields in the Eclipse dialog.
  • If a line of the ISPF panel contains a mixture of input, output and text fields, the logical parse process tries to attach the text fields to the input or output fields according to the following rules:
    • Text fields which precede an input or output field are always assigned to the following input or output field as label.
    • Text fields which follow an input and output field and do not precede another input or output field are assigned to the preceding input or output field as a tooltip.
  • The logical parse process tries to maintain the count of columns of an input/output field area of the original ISPF panel.
  • A MODEL section of an ISPF table panel dialog results in a table in the generated Eclipse dialog.
  • The first input field of the MODEL section of an ISPF table panel is always interpreted as a line command field for the table. This input field does not result in an input field in the generated Eclipse dialog. Rather, it results in a context menu of the generated table.The ISPF panel source must contain a VER condition for the line command field listing all allowed line command values. Moreover, the panel generation control file should contain corresponding line command tags mapping the line command values of the ISPF table panel to meaningful values in the context menu.
  • If a VER condition is found in the panel’s PROC section for an input field, the following VER conditions are interpreted by the logical parse process:
    • NB resp. NONBLANK: A VER non blank condition causes the mandatory flag to be set for the generated input parameter in the Workflow model.
    • LIST: A VER LIST condition causes a combo box to be generated for the input field in the Eclipse dialog which contains the listed values.

    A VER condition in the PROC section for an input file is always evaluated even if it is only a conditional VER condition.

Some of these rules can be overruled by certain phrases in the panel generation control file.

These phrases are:

  • categories=false

    This phrase means that the last line of a text block is not interpreted as the title for the following input/output field group of the Eclipse dialog, but as part of the text block.

  • table_header=true

    This phrase means that the logical parser tries to interpret the last line of the BODY section in a ISPF table panel as column headers for the following table. This interpretation is only done if the count of words of the last line in the BODY section matches the count of columns of the table.

Parent topic: ISPF Panel Model Generator


Execute ISPF Edit Macro

A tool of type "Execute ISPF Edit Macro" should be defined in an action which itself is defined as a global action with an ISA_Editor_Action relation so that it is added to the editor’s context menu. In the ISA_Editor_action relation, you can define the file suffixes for which the editor action should apply.

A tool of type "Execute ISPF Edit Macro" copies the current content from the active editor to a temporary data set on the remote system and then applies a user defined ISPF edit macro to this remote data set. Afterwards the potentially-changed content of the remote file is transferred back to the client and replaces the current content of the editor from where the content was originally taken.

The current cursor position is exchanged between the client and the remote system. That means that the current cursor position in the active editor is read at the beginning of the tool and sent to the remote system. On the remote system the cursor will then be placed in that position in the temporary data set right before the execution of the ISPF edit macro starts. After the ISPF edit macro has finished, the cursor position is read out of the remote editor and pushed back to the client machine, which then puts the cursor in that same position in the client editor after its content is replaced.

Tool Attributes:

Attribute Type Description
Edit Scenario [M] Selection Specifies in which scenario the edit macro tool is executed. This can be either in a local or remote edit scenario.

A remote edit scenario means that the content of the editor is directly retrieved from an MVS resource. The temporary resource is created in the remote edit scenario as follows. The temporary data set has the same data set attributes as the original file but is allocated with less space. If the editor contains a member of a partitioned data set, the temporary file is a partitioned data set with a member that has the same name as the member that is being edited. The name of the remote temporary data set is derived from the name of the parameter file data set. See Master configuration syntax section in the Local Master Configuration topic for more information.

A local edit scenario means that the content of the editor is retrieved from a local file. See the attribute ‘Target File Type’ for more information

Valid values:

  • Remote Edit (Default)
  • Local Edit
Target File Type [O] Selection This attribute is only required if the tool is executed in a local edit scenario.

This attributes defines how the required temporary MVS resource is created.

If the Target File Type is set to Temporary Resource, either a SEQ-dataset or a partitioned data set member will be created at the defined location, with physical name defined in the file descriptor and static attribute values. If the target already exists the content of the resource is overridden.

If the Target File Type is set to Template Resource, the data set attribute values of the template resource are taken to create the new temporary resource. If the template resource is a SEQ-dataset, the same data set attributes are used as the original file, but the data set is allocated with less space. If the template is a member of a partitioned data set, the temporary file is a partitioned data set with a member that has the same name as the template member. The name of the remote temporary data set is derived from the name of the parameter file data set. See Master Configuration for more information.

Valid values:

  • Temporary Resource (Default)
  • Template Resource

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | Macro Name: Name of the ISPF Edit Macro. Maximum length 8 characters.
2 [O] | I | File | Target Resource: The Target MVS resource. This input parameter is only required in case of a local edit scenario. The edit macro runs against a temporary MVS resource which is created based on this input parameter. See the attribute Target File Type for more information.
3 [O] | I | String | Macro parameter: Every parameter following the macro name is interpreted as a parameter for the ISPF macro and all parameters are concatenated in the same sequence as they appear in the model with a space between them. That concatenation is then handed over to the ISPF macro at start up time.
  • Input parameters
  • Output parameters
  • Restrictions
Parent topic: Tool Types for the ISPF Function Package
Related information
Master Configuration
Execute ISPF Edit Macro


Input parameters

The name of the ISPF edit macro and its parameters must be modeled as string type input parameters. While the macro name must always be present as the first parameter and its value must not be empty and must not be longer than eight characters, there is no limitation for the macro parameter. A parameter need not be modeled and may be defined from as many parameters as needed. Every parameter following the macro name is interpreted as a parameter for the ISPF macro and all parameters are concatenated in the same sequence as they appear in the model with a space between them. That concatenation is then handed over to the ISPF macro at startup time.

Simple example:

Edit Macro Call
Parent topic: Execute ISPF Edit Macro


Output parameters

There is no output parameter from that tool.

Parent topic: Execute ISPF Edit Macro


Restrictions

ISPF edit macros that can be used as tools of type "Execute ISPF Edit Macro" have the following restrictions:

  • The ISPF edit macro may not contain any ISPF panel processing.
  • ISPF messages issued from the called ISPF edit macro are not displayed in the client.
  • INFOLINEs, NOTELINEs or MSGLINEs generated by the called ISPF edit macro are not displayed in the Eclipse editor.
  • Commands which control the ISPF edit session (like save, end, cancel) are not supported.
  • ISPF-Edit-Commands with dependencies to the original dataset (like create, replace, copy, move) are not fully supported or will not work as expected. Please note that the Edit Macro is executed on a temporary dataset.
Parent topic: Execute ISPF Edit Macro


Details for the ISPF Function Package

  • Attaching ISPF Tools
  • REXX Debug
Parent topic: ISPF Function Package


Attaching ISPF Tools

The "Execute ISPF Command" tool lets you execute a procedure, for example a REXX procedure, a CLIST or a program, on a remote z/OS system in an ISPF environment.

In this case, a client application communicates with a remote user session running in an ISPF environment. For this tool interface to be used correctly, the TSO/ISPF environment must be correctly configured. See z/Server Installation Guide: Setting up the JCL for a User Server for more information.

The product is delivered with several REXX procedures that are only to be used in the context of attaching ISPF tools. After successful installation of the REXX procedures and configuration of the TSO/ISPF environment, the defined ISPF tools can be used.

Calling an ISPF tool can be modeled in these ways:
  • REXX (Call …)
  • CMD (Select CMD(…)
  • PGM (Select PGM(…) PARM(…))

Regardless of the call-up type, you can configure whether a tool should be executed in the ISPF online or in batch.

In this context, online means that the client carries out the tool execution synchronously.

Batch means the asynchronous execution of an ISPF tool through submitting a batch job. Exits must be adapted for batch support. See ISPF exits for more information.

To integrate an existing ISPF function into the Eclipse client, it is usually necessary to develop a tool adapter that regulates the required parameter input/output and file transfers. This tool adapter is entered as a program or procedure name in the modeled application. The following topics describe how a tool adapter of this kind is developed.

  • Tool Adapter as a REXX Subroutine
  • ISPF Exits
  • Mass Processing in ISPF Tools
Parent topic: Details for the ISPF Function Package
Related information
Batch Execution
Tool Adapter as ISPF Service


Tool Adapter as a REXX Subroutine

If the invoke form REXX is used when modeling an ISPF tool, the call-up of the tool will take place as a REXX subroutine.

We recommend you use this call-up form, as the input and output parameter are then supported in the most flexible way. The REXX TAUTOSAM procedure skeleton can be used as a copy template for a new tool adapter.

  • Input Parameters
  • Output Parameters and Return Code
  • Tool Adapter as ISPF Service
  • Messages
  • Input Files
  • Output Files
  • Batch Execution
  • Resource Processing
  • Resource Transfer to an ISPF Tool
  • Resource Update
  • Creating a Resource
  • Deleting a resource
  • Creating a Resource List
  • Creating a List of Property Values
  • Tool-defined Resource Processing
Parent topic: Attaching ISPF Tools


Input Parameters

Parameters are transferred directly to the REXX procedures. The modeled tool descriptor defines whether there should be separators between the parameters. The standard separator is the space.

Example 1:

/* Get input parameters from the Client (blank separated list) */
Parse Arg parm1 parm2 parm3 parm4 parm5 rest

Example 2:

/* Get input parameters from the Client (comma separated list) */
Parse Arg parm1 ',' parm2 ',' parm3 ',' parm4 ',' parm5 ',' rest
Parent topic: Tool Adapter as a REXX Subroutine


Output Parameters and Return Code

The REXX tool adapter must return both a return code, and, if modeled, output parameters. As the REXX procedure is called up as a sub-routine from the client application, the output parameters will also be transferred to the client application via the EXIT statement, in addition to the return code. The modeled tool descriptor defines whether separators should be used between every two parameters for the output parameters.

The return must take the following form:

EXIT returncode outparmlist

There must be a space between the numerical return code and the parameter list.

Example 1:

/* successful tool execution with a blank separated output parameter list */
outparm = 'PARM1 PARM2 PARM3'
exitrc = 0
Exit exitrc outparm

Example 2:

/* successful tool execution with a comma separated output parameter list */
outparm = 'PARM1,PARM2,PARM3'
exitrc = 0
Exit exitrc outparm
Parent topic: Tool Adapter as a REXX Subroutine


Tool Adapter as ISPF Service

If the invoke forms CMD or PGM are used when modeling an ISPF tool, the call-up of the tool will take place via the ISPF SELECT Service, as follows:
  • SELECT CMD(toolname parmlist)
  • SELECT PGM(toolname) PARM(parmlist)

With CMD, tools can be called up that are implemented as CLIST, REXX or TSO Command. With PGM, compiled programs are called up.

The parameter transfer takes place according to modeled parameter sequence numbers. The rules and restrictions of the ISPF SELECT Service must be observed, however.

The tool adapter must return both a return code, and, if modeled, output parameters to the client application. The output parameters must be made available by the tool in the ISPF Shared Pool Variable named TAUTOPM.

The installation SAMPLIB contains two samples (TAUSAPL1 and TAUSACOB) to demonstrate how to set the ISPF variable TAUTOPM from a PL1 and COBOL program respectively. The sample programs just return the parameter string passed to them via the shared pool variable TAUTOPM.

Parent topic: Tool Adapter as a REXX Subroutine


Messages

Output parameters are only interpreted by AWM if the return code of the attached tool is not higher than the maximum permitted return code specified in the AWM model. Micro Focus recommends that you do not pass tool messages as output parameters to AWM.

If the tool ends with an error or with warnings only messages should be output.

There are two methods that can support this.

If only one message is to be passed to AWM, the tool can be defined with the specific ISPF Shared Pool Variable TAUTOMS with the required message text.

REXX Example 1

/* tool execution finished with errors */
outparm = ''
exitrc = 8
tautoms = 'Here is my error message.'Address ISPEXEC 'VPUT (TAUTOMS) SHARED'
Exit exitrc outparm

REXX Example 2

/* tool execution finished with warnings */
outparm = 'PARM1 PARM2 PARM3'
exitrc = 4
tautoms = 'Here is my warning message.'Address ISPEXEC 'VPUT (TAUTOMS) SHARED'
Exit exitrc outparm

If a tool has more than one line of output messages or a message has to be returned to a modeled validation action, it can use the ISPF table TAUTOTBM to pass the messages to AWM. This ISPF table is provided by the AWM ISPF interface and is empty when the tool is called.

This ISPF table is not sorted and contains no key columns.

The structure of the ISPF table is as follows:

Column | Description
TAUTOMTY Message type (optional)
T
Tool message (default)
V
Validation message
TAUTOSER Message severity (optional)
I
Information
W
Warning
E
Error (default)
Note: Only relevant if message type is T.
TAUTOMSG | Message text (mandatory)
TAUTOVPO Position of the incorrect parameter (optional)

May be a comma separated list of positions.

Default: 1

Note: Only relevant if message type is T.

In this ISPF table, two different types of messages can be stored. The first and standard type is a tool message. The second type is a validation message.

The difference between the two types is the way they are processed by the client.

The tool messages of all the tools of an action are gathered. If at least one tool of an action returns tool messages, the gathered messages are displayed in a dialog window at the end of the action execution. The type of the dialog depends on the maximum return code of the tools in the action as listed in the following table:

Column | Description
rc = 0 | Information dialog
0 < rc <= max RC in application options | Warning dialog
Rc > max RC in application options | Error dialog

See Validate Action for more information on message validation.

REXX Example 3

The following REXX example shows how a validation message can be returned.

ADDRESS ISPEXEC 'VGET (TAUTOTBM) SHARED'
tautomty = 'V'
tautomsg = 'Unfiltered member selection may produce a large output.'
tautoser = 'W'
tautovpo = '5'
ADDRESS ISPEXEC 'TBADD' tautotbm
Parent topic: Tool Adapter as a REXX Subroutine
Related information
Validate Action


Input Files

If a file is created within an action that is to be processed as an input by a tool, it requires no special handling. The name of the input file is modeled in the modeled tool descriptor as an input parameter. The Tool-Adapter receives the file name as a parameter, and can allocate and edit the file.

Parent topic: Tool Adapter as a REXX Subroutine


Output Files

If a tool creates output files that will later be processed by the client application, the file names are modeled as output parameters.

REXX Example 1:

/* Create a seq. file and return the dataset name to the Client  */
outdsn = CREATE_DSN()    /* subroutine to create the dataset */
Call ADD_RECORDS outdsn  /* subroutine to add records        */
outparm = 'PARM1' outdsn 'PARM3'
exitrc = 0
Exit exitrc outparm

REXX Example 2:

/* Create a PDS member and return it to the Client */
outdsn = CREATE_PDS()    /* subroutine to create the PDS    */
member = CREATE_MEM(outdsn) /* Create the PDS member        */
outparm = 'PARM1' outdsn'('member')' 'PARM3'
exitrc = 0
Exit exitrc outparm
Parent topic: Tool Adapter as a REXX Subroutine


Batch Execution

Note: Although there is an AWM model action attribute MODELESS which enables the running of an action in an asynchronous mode, Micro Focus strongly recommends that you model actions containing ISPF command tools as MODAL actions and to use the ISPF batch mode for long running ISPF tasks. The ISPF environment attached to the user does not support the parallel execution of ISPF commands.

An ISPF tool can be modeled to run as an ISPF batch job. Use the attribute RunAsJob of the tool descriptor to model a tool to be executed as a batch job.

Accepted values for this attribute are:
  • NO
  • Model Job
  • Tool Job
The value NO, which is the default value, means the tool is executed in the foreground, which means the tool is executed in the ISPF environment which has been associated to the user. If the execution mode of the associated action is modal, the Eclipse workbench is blocked for other actions during the execution of the associated action.

The value Model Job means the tool is executed as an ISPF batch job. The submission of the tool as a batch job is handled in this case by the AWM ISPF tool interface. Any attached ISPF tool can be configured as Model Job with no need to make any changes to the tool logic. Use this setting for long running background processing tools which do not contain any logic for submitting a batch job, for example, tools to build a program.

The value Tool Job is meant for tools which already contain logic to submit a batch job, for example, by creating a job via ISPF file tailoring and submitting it. If the tool is modeled as Tool Job you should return the job identifier and job name to the AWM client using the ISPF shared pool variables TAUTOJID and TAUTOJNA respectively or setting the corresponding fields in the ISPF table TAUTOJOB, see below.

If a tool submits more than one batch job or a tool submitting a batch job is called in a MassProcessing action the tool can set the variables TAUTOJID and TAUTOJNA in the ISPF table TAUTOJOB. This ISPF table is provided by the AWM ISPF interface and is open when the tool is called. The table TAUTOJOB is not sorted and contains the name columns TAUTOJID, TAUTOJNA, and TAUTOJPD. The two variables TAUTOJID and TAUTOJNA should not be set in the ISPF shared pool in this case. Otherwise, the job would be shown twice in the Jobs view. The table field TAUTOJPD is meant to pass the name of a job output parameter data set. This field is only relevant if the ISPF is modelled as Tool Job. If the ISPF tool is modelled as Model Job, the AWM ISPF tool interface creates the job output parameter data set. If the ISPF tool is modelled as Tool Job, the job output parameter data set is only relevant when a "Job After Action" is modelled for the tool. In this case the content of the job output parameter data set is read and interpreted by AWM when the "Job After Action" is executed. The ISPF tool has to create the job output data set and pass the name of the data set via TAUTOJPD. The job output parameter data set can contain formatted lines which are consumed by AWM. The following table shows sample entries of the job output parameter data set and their meaning.

Sample Line | Description
TOOL: TAUTOXYZ | tool name TAUTOXYZ
RC: 4 | return code of the batch tool (4 in this case)
DATE: 18/12/24 | date
OUTPARM: PGM0001,COBOL,DB2 | output parameters as modelled for the batch tool
ENDPARM: | end marker of the parameter entries
OUTMSG(E): Dataset U1234567.TEST.CBL doesn’t exist! | message to display including severity (I,W,E) in parentheses

The job submit messages should be added to the ISPF table TAUTOTBM if more than one message should be returned by the tool.

The following is a REXX code snippet which shows how a tool can create and submit a batch job and set the shared pool variables TAUTOJID and TAUTOJNA.

REXX Example 1:

wmsg = ''
subdsn = CREATEJOB('PGMBLD')    /* call to the subroutine CREATEJOB (listed below) */
/* Submit batch job */
msgmode = OUTTRAP('submsg.')     /* trap the submit system messages */
submsg.0 = 0
Address TSO "SUBMIT '"subdsn"'"    /* TSO submit the job subdsn */
subrc = rc
msgmode = OUTTRAP('OFF')    /* set the message mode off via OUTTRAP */
If subrc ^= 0 Then Do
   wmsg = 'Batch job not submitted.'
   Call EXIT 12 wsmg
   End
Do k = 1 To submsg.0          /* validate the stem variable submsg */
   Say Strip(submsg.k)
   If subrc ^= 0 Then   /* if the job submit failed, just return the error message lines */
      wmsg = wmsg Strip(submsg.k)
   Else Do
      Parse Value submsg.k With msgid . jname '(' jobid ')' .      /* parse the standard system submit message */
      If msgid = 'IKJ56250I' Then Do
         tautojid = jobid
         tautojna = jname
         ADDRESS ISPEXEC 'VPUT (TAUTOJID, TAUTOJNA) SHARED'  /* put the variables TAUTOJID and TAUTOJNA in the ISPF shared pool */
         wmsg = 'Batch job' jname'('jobid') successfully submitted'
         End
      End
   End
If subrc ^= 0 Then
   Call EXIT subrc wmsg

/********************************************************************
Subroutine to create a Member via ISPF Skeleton

    Parameter:
    xskel:      Skeletonname
********************************************************************/
CREATEJOB:

Parse Upper Arg xskel .
/* standard ISPF file tailoring processing to create a job for batch submission */
/* we use a standard subroutine ISPF in REXX to call ISPF functions */
ADDRESS ISPEXEC   "FTCLOSE"
  "FTOPEN TEMP"
  "FTINCL" xskel
  "FTCLOSE"
  "VGET ZTEMPF SHARED"  /* the ISPF variable ZTEMPF contains the name of the file in which the job was created */
ADDRESS TSO
t_ddname = ztempf

Return t_ddname

The values put into the shared pool variable TAUTOJID and TAUTOJNA are displayed in an informational message window on the client side for tools modeled as Tool Job.

Jobs created by tools modeled as Model Job or Tool Job are listed in the Jobs view. This view monitors the execution status of the created job. The status changes from executing to done when the batch job has finished on the remote system. This also displays a notification message at the bottom right corner (main monitor). The notification automatically fades out after a default duration of 10 seconds. This behavior can be customized under the MVS function package in AWM models. See MVS Function Package for more information.

The Jobs view provides a context menu action to browse the output of the job.

You can model an "Job After Action" for tools modeled as Model Job or Tool Job. The action specified under the "Job After Action" attribute in the tool descriptor is added to the context menu of the generated job in the Jobs view. The "Job After Action" has access to the whole execution context which was available when the batch tool was submitted. The "Job After Action" is typically used to display output information generated by the job, such as build results. An advantage of tools modeled as Model Job and Tool Job is that the result of the tool is kept in the job output and can be reviewed at a later time.

The Jobs view also provides an action to personalize the job card for jobs submitted by tools modeled as Model Job and also for jobs modeled as Tool Job if the batch job submitted by the tool supports the AWM job card. See ISPF Exits for more information.

Parent topic: Tool Adapter as a REXX Subroutine


Resource Processing

In principle, the modeled application determines the form in which element information is exchanged with ISPF tool. See Special properties for more information.

The operation that a tool should execute, such as READ, UPDATE, INSERT, INSERT-CHILD, DELETE, COPY, or MOVE can be explicitly defined in the AWM model. For cases in which the specific tool operation cannot be modeled in advance, the tool can dynamically define the operation and report back to the client application (operation: TOOL-DEFINED).

In addition, there are specially modeled tools that expect the resource lists as output.

In the following topics, the different types of operations are described in terms of the impact on the programming of the tool adapter.

Parent topic: Tool Adapter as a REXX Subroutine
Related information
Special Properties


Resource Transfer to an ISPF Tool

If a modeled action that contains an ISPF tool has an effect on a resource, the tool will be modeled so that the attributes for identifying the resource will be transferred to the tool as input parameters.

REXX example:

/* Get element id (PDS and member name) */
Parse Arg pds member .
Parent topic: Tool Adapter as a REXX Subroutine


Resource Update

For an update operation on a resource, the changed property values must return as output parameters according to the AWM model.

REXX example:

/* Get element type, property set and file suffix for a PDS member */
Parse Arg pds member .
type = GET_ELEMENT_TYPE(pds member)
propgroup = GET_PROPERTY_GROUP(pds member)
suffix = GET_SUFFIX(pds member)
outparm = suffix','propgroup','type
Exit 0 outparm
Parent topic: Tool Adapter as a REXX Subroutine


Creating a Resource

Several of the tool operations that can be defined in the AWM model lead to the creation of a resource (COPY, MOVE, INSERT). In this case, the output parameters must be modeled so that all the properties for the identification of the resource are included.

REXX example:

/* Copy a PDS member */
Parse Arg pds member_old member_new .
copyrc = COPY_MEMBER(pds member_old member_new)
outparm = pds member_new
Exit copyrc outparm
Parent topic: Tool Adapter as a REXX Subroutine


Deleting a resource

If the deletion of a resource is requested in the AWM, it is usually sufficient for the tool to return a return code.

REXX example:

/* Delete a PDS member */
Parse Arg pds member .
del_rc = DELETE_MEMBER(pds member)
Exit del_rc
Parent topic: Tool Adapter as a REXX Subroutine


Creating a Resource List

Used if the creation of an element list is required.

As a rule, the AWM model is designed so that an output parameter is expected from the tool that returns the resource list file name. The resource list must have a structured design. This structure is defined by a corresponding file descriptor in the AWM model.

REXX example:

/* Create a PDS list */
Parse Arg PDS_prefix .
resource_dsn = CREATE_DSN()
resource_dd = ALLOC_DSN(resource_dsn)
Call GET_PDSLIST(PDS_prefix)
Call WRITE_PDS_INFOS(resource_dd)
Call FREE_DSN(resource_dd)
Exit 0 resource_dsn
Parent topic: Tool Adapter as a REXX Subroutine


Creating a List of Property Values

Used if the values of a property should be determined by an ISPF tool in the AWM model, for example, to offer a selection of the valid values in an input field.

The procedure for creating the ISPF tool is similar to that for the creation of the resource list. The tool creates a file that contains one valid value per line. The generated file name normally returns to the client application as an output parameter.

Parent topic: Tool Adapter as a REXX Subroutine


Tool-defined Resource Processing

If resource processing is specified as TOOL-DEFINED in the AWM model, the tool delivers information about the type of resource processing to the client application.

TOOL-DEFINED must be used in the following cases:
  • When the type of resource processing (such as Update or Insert) is only clear during run time of the tool, and can therefore not be modeled.
  • With generating tools (such as Compile tools) that can create several outputs from a single input resource and the outputs are to be processed by the client application.

The ISPF interface already provides a temporary empty ISPF table, in which the tools can store resource information.

The name of the temporary ISPF table is the value of the shared pool variable TAUTOTBI.

The table is not sorted and contains no key columns.

Column name | Description
TAUTOFNC | Resource Operation in the form: operation(<refid>,<REFRESH>,<SELECT>) The term in brackets is optional. operation = INSERT-ELEMENT | REMOVE-ELEMENT | UPDATE-ELEMENT The default value is UPDATE-ELEMENT refid: A unique reference identifier for subsequent tools within an action. REFRESH: Refreshes all the element properties. SELECT: Selects the element in the client table or tree view. See Tool-defined Resource Operations for more information and a description of the values.
TAUTOPRM | List of property values as defined as element output parameters in the AWM model.
Resource Operation | Description
INSERT-ELEMENT or INSERT-CHILD Checks whether the element is already known.

If the element does not yet exist, it is created and added to the list where the Input element is located. In the Application Explorer view the element can be added as a child element, if requested.

If the element already exists, the element properties are updated in line with the output parameters for the tool and, where necessary, the added to the list in which the input element is located.

REMOVE-ELEMENT | Removes the element from all AWM element lists.
UPDATE-ELEMENT Updates an element that already exists with the values returned by the tool.

If the element does not exist in the same list as the input element, it is not added (compare INSERT-ELEMENT).

Tools can generate rows with the ISPF Table Service TBADD in the ISPF table, which is empty at the time of the tool call-up. Tools may not close this table with TBEND or TBCLOSE.

REXX Example

/* Update compiled element and insert compile output elements */
Parse Arg inpds inmem .
. . . .
/* Do the compile and create a list with output members in stem bldrec. */
. . . .
Address ISPEXEC 'VGET (TAUTOTBI) SHARED'        /* get temp. table name */

tautoprm = inpds inmem
tautofnc = 'UPDATE-ELEMENT(COMP_IN,REFRESH,SELECT)'
Address ISPEXEC 'TBADD' tautotbi
Do i = 1 To bldrec.0
   Parse Value bldrec.i With outpds outmem .
   tautoprm = outpds outmem
   tautofnc = 'INSERT-ELEMENT'
   Address ISPEXEC 'TBADD' tautotbi
   End

. . . .
Parent topic: Tool Adapter as a REXX Subroutine
Related information
Tool-defined Resource Operations


ISPF Exits

The ISPF interface delivered with the product consists of REXX procedures and ISPF skeletons.

The following describes the procedures and ISPF skeletons that represent Exits and that can or should be adapted to the respective environment.

Exit | Type | Description
TAUTOXA1 REXX Exit for the dynamic allocation of the ISPF environment.

This exit procedure is always called directly before a modeled ISPF tool is called.

It receives one parameter, which is assigned to the modeled application (see Variable references).

The exit is typically used to carry out dynamic allocations depending on the modeled input parameter, e.g. in order to be able to test modified applications.

TAUTOXA2 REXX Exit for the allocation of (temporary) files.

The allocation of temporary MVS files takes place in this exit.

TAUTOXA3 | REXX | Exit which runs before ISPF is shut down. The exit is meant to do finally processing as long as ISPF is active.
TAUTOXA4 | REXX | Exit which is called when a user connects to the remote server from the REXX TAULAPPL when the server is IBM RSED, or from the REXX TAUZCAPP when the server is the Micro Focus z/Server. The exit is intended to gather login information, for example for floating licence checking.
TAUTOXCC REXX Exit for the integration of the COBOL compiler e.g. for remote syntax check.

This exit is used only in context with add-ons for the support of SCM products, in order to support remote syntax check with Error Feedback.

For these purposes, the exit can also be integrated into home-grown tool attachments as a REXX subroutine.

TAUTOXCP REXX Exit for the integration of the PL/I compiler for remote syntax check.

This exit is used only in connection with add-ons for the support of SCM products, in order to support remote syntax check with Error Feedback.

For these purposes, the exit can also be integrated into home-grown tool attachments as a REXX subroutine.

TAUTOXCA REXX Exit for the integration of ASSEMBLER for remote syntax check.

This exit is used only in connection with add-ons for the support of SCM products, in order to support remote syntax check with Error Feedback.

For these purposes, the exit can also be integrated into home-grown tool attachments as a REXX subroutine.

TAUTOXC3 REXX Exit for the integration of C compile for remote syntax check.

This exit is used only in connection with add-ons for the support of SCM products, in order to support remote syntax check with Error Feedback.

For these purposes, the exit can also be integrated into home-grown tool attachments as a REXX subroutine.

TAUTOXIS | Skeleton | This skeleton must be adapted for the use of the batch interface in order to build up a valid ISPF environment in batch, under which a modeled ISPF batch tool can be started (only relevant for ISPF command tool modeled using the attribute Model Job.
TAUTOXJC | Skeleton | This skeleton must be adapted for the use of the batch interface, in order to support a default job card.

The remote syntax check exits TAUTOXCA, TAUTOXCC, TAUTOXCP and TAUTOXC3 use the data set allocation exit TAUTOXA2 to allocate the XML error feedback data set. The XML error feedback data set is an MVS partitioned organized data set where the remote syntax check exit writes the XML error feedback of the syntax check to a member named the same as the source member of the syntax check.

The client will always display the errors listed in all XML members which are found in this data set.

Therefore this data set should be cleared at the beginning of each syntax check action.

Parent topic: Attaching ISPF Tools
Related information
Variable References


Mass Processing in ISPF Tools

The Workflow Manager is able to pass the properties of multiple selected elements to the ISPF tool.

Provided that an ISPFCOMMAND tool descriptor is used within a mass processing action descriptor, you can define mass parameters which are sent to the ISPF tool for each selected element. Mass input parameters must have the type MassProcessing in order to be passed properly to the tool.

Below is an example of how to model the mass delete of z/OS data set members.

Model:

ISPF Mass Delete
Note: The mass input parameters have the type "MassProcessing". The ToolDefinedResourceOperation output parameters are used for tool-defined resource operations. This tool returns a REMOVE-ELEMENT: resource operation for every deleted member.

The mass input parameters are passed as the standard input parameters by the sequential parameter file from the AWM client, named <userid>.TAURUS.PARMFILE by default.

If the ISPF interface delivered with the product is used, the PARMFILE is read by this interface and the mass input parameters for each selected element are passed to the invoked tool by the ISPF table TAUTOTIP. This table is not sorted and contains no key columns.

The table contains the two columns TAUTOIPN and TAUTOIPC. TAUTOIPN contains an ID for each table entry in the format INPARMnnnn (nnnn is a four-digit sequential number). TAUTOIPC contains the values of the modeled parameter for the corresponding selected element. The parameter values are passed as one string separated by an input parameter separator specified in the model for each selected element. It is the mass tool’s task to parse the parameter values in the correct way according to the sequence and separator defined in the model.

It is possible to pass both string or file input parameters and MassProcessing parameters to an ISPF tool in one call. The string or file input parameters are passed to the ISPF tool as tool arguments, as described in Input parameters. The MassProcessing parameters are passed to the ISPF tool via the ISPF table TAUTOTIP.

The REXX code snippet below shows how the mass delete tool gets and parses the element parameters from the ISPF table TAUTOTIP.

REXX Example:

/* mass delete of PO members */
ADDRESS ISPEXEC
"TBTOP TAUTOTIP”
If rc = 0 Then Do Forever
   “TBSKIP TAUTOTIP”
   If rc <> 0 Then
      Leave
   delentry = tautoipc
   Parse Var delentry deldsn","delmem
   del_rc = DELETE_MEMBER(deldsn delmem)
   If del_rc = 0 Then Do
      /* add a message to the ISPF message table */
      tautoser = 'I'
      tautomsg = deldsn"("delmem") deleted."
      /* maintain TAUTOTBI for resource processing */
      tautoprm = deldsn","delmem
      tautofnc = 'REMOVE-ELEMENT'
      “TBADD TAUTOTBI"
      End
   Else Do
      /* add an error message to the ISPF message table */
      tautoser = 'E'
      tautomsg = "Deletion of "deldsn"("delmem") failed."
      End
   “TBADD TAUTOTBM"
   End

An ISPFCOMMAND tool which is configured within a mass processing action descriptor can also return mass output parameters. These are treated as mass input parameters of a subsequent tool. The output parameters of the ISPFCOMMND tool must be configured, in this case, as type MassProcessing. If the ISPF interface delivered with the product is used, the mass output parameters can be passed by the ISPF table TAUTOTOP. This table is not sorted and contains no key columns. The table is open when the tool is called and should not be closed by the tool. The only name column of the table is TAUTOOPC. In this column the parameter values must be passed as configured in the AWM model as tool output parameters of type MassProcessing separated by the separator modeled under "Out Parm Separator" of the tool descriptor.

The MassProcessing output parameters can be used by a following tool, as MassProcessing input parameters. The input parameters must be defined as "Parameter From" of type Previous_Tool.

Parent topic: Attaching ISPF Tools


REXX Debug

In all the REXX procedures supplied, the trace can be dynamically switched on and off.

Go to the Eclipse Remote Systems view and select Debug, using the context menu of the MVS entry, to open a Debug popup window. Enter valid trace parameters from the table below.

REXX Debug input dialog

You will find the REXX trace in the executing user server if you open the SYSTSPRT DDNAME.

The following debug parameters are supported:

Parameter | Description
? | Display debug status
OFF | Switch off any REXX tracing
ON | Activate the trace in all REXX procedures
procedure list | A blank separated list of REXX procedure names to be traced
+procedure list | Add additional procedure names to be traced
-procedure list | Remove procedure names from the procedure list

There is a special option for debugging ISPF dialog applications. If this option is checked, the debug is switched on for the dialog debug REXX interface.

Parent topic: Details for the ISPF Function Package


Micro Focus Background Parser Function Package

The Micro Focus Background Parser function package is comprised of features and tools that operate in the context of the Micro Focus COBOL, PL/I, or JCL editor's background parser.

The function package enables you to specify the concatenation of SYSLIB or PROCLIB libraries to be used when copybooks or includes are downloaded from a mainframe.

The function package enables you to specify the structure of the local file cache for the downloaded copybooks or includes. The structure of the local file cache for copybooks or includes is specified by the relationship Micro_Focus_Function_Package_Has_Cache. Under this relationship identifiers can be specified to point to AWM properties. The values of those properties in the specified sequence are used during runtime to determine the folder structure to search, or to store downloaded copybooks. The last folder in this structure is always named as the partitioned data set where the copybook or include was located on the mainframe.

The concept is that sources opened from a common context typically have the same copybook or include view.

Note: This cannot prevent a source from opening an incorrect or outdated version of a copybook or include. To prevent this, tools to clear the local copybook or include cache are provided. When the cache is cleared the copybooks or includes are downloaded from the mainframe.

You do not need to explicitly specify the cache structure. In this case, the copybook or include is stored in the internal AWM project under ../FileCache/BackgroundParser/<data_set_name> where <data_set_name> is the name of the data set where the copybook or include was located on the mainframe.

Alternatively, you could specify the cache structure depending on the staging hierarchy or life cycle structure of a Software Configuration Management (SCM) system. In a SCM system, the sources at the same stage typically have the same copybook or include view.

For example, in the SCM system Endevor, the staging hierarchy is defined by the features Environment and Stage. When modeling Endevor you might specify identifiers defining the local copybook/include storage as the properties representing the Endevor Environment and Endevor Stage.

Relationship | Cardinality | Description
Has_SYSLIB_Definition | 0..1 | The relationship to a SYSLIB definition describing the concatenation of mainframe libraries to search for COBOL copybooks, or PL/I includes.
Has_PROCLIB_Definition | 0..1 | The relationship to a PROCLIB definition describing the concatenation of mainframe libraries to search for JCL includes.
Has_Cache | 0..1 | The relationship to a definition determining the structure of the local cache for downloaded COBOL copybooks, PL/I, or JCL includes.
  • Relationship Micro Focus Background Parser Has SYSLIB Definition
  • Relationship Micro Focus Background Parser Has PROCLIB Definition
  • Relationship Micro Focus Background Parser Has Cache
  • Relationship Cache Has Identifier
  • Tool Types for the Micro Focus Background Parser Function Package
Parent topic: Function Packages


Relationship Micro Focus Background Parser Has SYSLIB Definition

The relationship SYSLIB defined under the Micro Focus Background Parser enables you to specify the library concatenation on the mainframe or network drives where COBOL copybooks or PL/I includes are searched for. The SYSLIB definition is used in the Micro Focus COBOL, and PL/I editor when performing a z/OS remote edit.

You can use variable names as part of the SYSLIB concatenation attribute. See Variable References for more information. Full background parsing is available when using the Micro Focus COBOL, and PL/I editors to edit a z/OS file remotely. This means that features such as syntax checking, content assist, and program outline are fully supported.

The background parser needs to resolve COBOL copybooks, and PL/I includes. To use this feature you need to specify the SYSLIB concatenation attribute. Several SYSLIB locations can be specified by concatenating the paths with a semicolon (;). The COBOL copybooks and PL/I includes are searched in the specified locations and in the order from left to right.

A fully-qualified MVS data set name or operating system path can be specified, for example, C:\cobol\copybooks. Operating system paths can point to network resources.
Note: z/OS USS paths are not supported.

You can use variable names in the SYSLIB concatenation attribute and the AWM model ensures that the variables are correctly resolved at runtime.

Attribute | Type | Description
Concatenation * | String | Specifies the SYSLIB concatenation used by the Micro Focus background parser to locate COBOL copybooks, or PL/I includes.

Example

Concatenation = &userid..TEST.COPYLIB;&NDV_PROP_Env..&NDV_PROP_Stage..COPYLIB

Parent topic: Micro Focus Background Parser Function Package


Relationship Micro Focus Background Parser Has PROCLIB Definition

The relationship PROCLIB definition under the Micro Focus Background Parser enables you to specify the library concatenation on the mainframe or network drives where JCL includes are searched for. The PROCLIB definition is used in the Micro Focus JCL editor in a z/OS remote edit scenario.

You can use variable names as part of the PROCLIB concatenation attribute. See Variable References for more information. Full background parsing is available when using the Micro Focus JCL editor to edit a z/OS file remotely. This means that features such as syntax checking, content assist, and program outline are fully supported.

The background parser needs to resolve JCL includes. To use this feature you need to specify the PROCLIB definition. Several PROCLIB locations can be specified by concatenating the paths with a semicolon (;). The JCL includes are searched in the specified locations and in the order from left to right.

A fully-qualified MVS data set name or operating system path can be specified, for example, C:\jcl\includes. Operating system paths can point to network resources.
Note: z/OS USS paths are not supported.

You can use variable names in the PROCLIB concatenation attribute and the AWM model ensures that the variables are correctly resolved at runtime.

Attribute | Type | Description
Concatenation * | String | PROCLIB concatenation used by the Micro Focus background parser to locate JCL includes.

Example

Concatenation = &userid..TEST.PROCLIB;&NDV_PROP_Env..&NDV_PROP_Stage..PROCLIB

Parent topic: Micro Focus Background Parser Function Package


Relationship Micro Focus Background Parser Has Cache

You can use the relationship Cache under the Micro Focus Background Parser to define the structure of the local cache for downloaded copybooks or includes (COBOL, PL/I, or JCL).

The local cache structure is determined by the values of the referenced properties on runtime. The last folder of the cache structure is named like the partitioned data set where the copybook or include was located.

See Micro Focus Background Parser Function Package for more information.

Relationship | Cardinality | Description
Has_Identifier | 0..* | The relationship to a property whose value is used as a folder name as part of the local background parser cache structure.
Parent topic: Micro Focus Background Parser Function Package


Relationship Cache Has Identifier

You can use the relationship Cache_Has_Identifier to specify a property as part of the local background parser cache structure.

Attribute | Type | Description
Target ID * | Property | A pointer to a property whose value is used as a folder name as part of the local background parser cache structure.
Parent topic: Micro Focus Background Parser Function Package


Tool Types for the Micro Focus Background Parser Function Package

  • Check Background Parser Cache Existence
  • Clear Background Parser Cache
Parent topic: Micro Focus Background Parser Function Package


Check Background Parser Cache Existence

Function:

This tool is used to check if a background parser cache already exists.

Attributes:

Attribute Type Description
Scope Select Value Specifies where the background parser cache folder structure is searched:
Program
From function package caching identifiers (Default)
Note: An exception will occur if any caching identifier is modelled in this case.
Custom
From input parameters.
Whole Cache

Parameters:

Parameter # | I/O | Type | Description
1..n [O] | I | String | This is the sub folder name of the background parser cache structure. It is only relevant if the tool attribute scope is set to Custom.
1 [M] | O | Boolean | Specifies whether the cache folder exists. This parameter should reference a boolean property. It returns true, if the cache folder exists, otherwise false.
Parent topic: Tool Types for the Micro Focus Background Parser Function Package


Clear Background Parser Cache

Function:

This tool is used to clear a background parser cache so that copybooks or includes are downloaded again during the next remote edit session.

Attributes:

Attribute Type Description
Scope Select Value Specifies where the background parser cache folder structure is searched for.
Program
From function package caching identifiers (Default)
Note: An exception will occur if any caching identifier is modelled in this case.
Custom
From input parameters
Whole Cache

Parameters:

Parameter # | I/O | Type | Description
1..n [O] | I | String | Specifies the sub folder name of the background parser cache structure. Only relevant if the tool attribute Scope is set to Custom.
Parent topic: Tool Types for the Micro Focus Background Parser Function Package


Micro Focus Editor Function Package

This section provides a reference for functions and tools used in Micro Focus Editor function package support.

  • Tool Types for the Micro Focus Editor Function Package
Parent topic: Function Packages


Tool Types for the Micro Focus Editor Function Package

  • Reparse With Refresh
Parent topic: Micro Focus Editor Function Package


Reparse With Refresh

Function:

This tool performs a background parse of the file open in the current editor, optionally clearing the copybook cache first.

Tool Attribute:

Attribute | Type | Description
Refresh Required | Boolean | Determines whether the copybook cache should be refreshed (cleared before the parse commences).
Parent topic: Tool Types for the Micro Focus Editor Function Package


Micro Focus ED Icons Function Package

This function packages only supports Enterprise Developer action icons which can be associated with action descriptors. The function package does not provide additional tools.

The icons are used, for example, in the standard Enterprise Developer Projects model to associate "New..." actions with icons.

If the ED Icons function package has been added to an AWM model, the supported icons can be added under the icons sections of the model editor and used to associate icons to any action descriptors or element types.

Parent topic: Function Packages
Related information
Icon


Micro Focus Enterprise Server Function Package

This section provides a reference for functions and tools used in Micro Focus Enterprise Server function package support.

  • Tool Types for the Micro Focus Enterprise Server Function Package
Parent topic: Function Packages


Tool Types for the Micro Focus Enterprise Server Function Package

  • Submit To Enterprise Server
Parent topic: Micro Focus Enterprise Server Function Package


Submit To Enterprise Server

Function:

This tool submits a JCL file to an Enterprise Server.

Tool Attribute:

Attribute | Type | Description
Use associated server | Boolean | Determines if the server associated with the project should be the target of the submission. If false, the server is specified as the input parameters.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the source's resource.
2 [O] | I | String | Name of the enterprise server to which the submission should be made (if not using the associated server).
3 [O] | I | String | Name of the Micro Focus Directory server hosting the enterprise server.
Parent topic: Tool Types for the Micro Focus Enterprise Server Function Package


Micro Focus Project Function Package

This section provides a reference for functions and tools used in Micro Focus Project function package support.

  • Linked Properties for the Micro Focus Project Function Package
    Lists the linked properties supported by the Micro Focus Project function package
  • Linked Element Types for the Micro Focus Project Function Package
  • Tool Types for the Micro Focus Project Function Package
  • Details for the Micro Focus Project Function Package
Parent topic: Function Packages


Linked Properties for the Micro Focus Project Function Package

The following linked properties are supported by the Micro Focus Project function package.

Linked Property Name | Content
Build Configuration Properties: |
Build Configuration Additional Directives | The active build configuration level additional directives.
Build Configuration Dialect | The COBOL dialect for the active build configuration.
Build Configuration effective Additional Directives | The effective active build configuration level additional directives.
Build Configuration effective Dialect | The COBOL dialect effective for the active build configuration.
Build Configuration effective System | The PL/I System effective for the active build configuration.
Build Configuration use CICS Preprocessor | Whether CICS directives are enabled for the active build configuration.
Build Configuration use SQL Preprocessor | Whether SQL directives are enabled for the active build configuration.
Build Configuration System | The PL/I System for the active build configuration.
Build Configuration effective use CICS Preprocessor | Whether CICS directives are effective for the active build configuration.
Build Configuration effective use SQL Preprocessor | Whether SQL directives are effective for the active build configuration.
Build Path Properties: |
COBOL Copybook Paths | The search order in which COBOL copybooks are searched for.
Build Precedence | The build precedence that determines which directories are built before others in the same project.
Project Dependencies | A list of projects on which the selected project depends.
JCL Include Paths | The search order in which JCL include files are searched for.
IMS Copy Paths | The search order in which IMS copybooks are searched for.
Assembler Macro Paths | The search order in which Assembler Macro copybooks are searched for.
File Properties: |
Can Compile | Whether a file can be compiled.
File Additional Directives | The file level additional directives.
File Dialect | The COBOL dialect for the file.
File effective Additional Directives | The effective file level additional directives.
File effective Dialect | The COBOL dialect effective for the file.
File effective System | The PL/I System effective for the active build configuration.
File effective use CICS Preprocessor | Whether CICS directives are effective for the file.
File effective use SQL Preprocessor | Whether SQL directives are effective for the file.
File System | The PL/I System for the file.
File use CICS Preprocessor | Whether CICS directives are enabled for the file.
File use SQL Preprocessor | Whether SQL directives are enabled for the file.
Has Children | Whether a program has direct child dependencies such as copy files. Always returns false if used on a copy file.
Project Properties: |
Project Additional Directives | The project level additional directives.
Project level COBOL Dialect | The COBOL dialect for the project.
Project level System | The PL/I System for the project.
Project level use CICS Preprocessor | Whether CICS directives are enabled for the project.
Project level use SQL Preprocessor | Whether SQL directives are enabled for the project.

Properties

In addition to the Micro Focus Project Linked Properties there are some fix named properties with the following meaning which can be used in an AWM model.

These properties are deprecated. Micro Focus recommends using the corresponding linked properties defined in this Micro Focus Project function package or in the Eclipse function package, or using the supported specific attributes which can be defined as application options.

Important: These property identifiers are case-sensitive and must be identical to those shown below.
Properties
Property (String) MFProp_RemoteSyntaxCheckOptions
Property (String) MFProp_RemotePLISyntaxCheckOptions
Property (String) MFProp_WorkspaceName
Property (String) MFProp_WorkspacePath
Property (Boolean) MFProp_CanCompile
Property (String) MFProp_ContentType
Property (String) MFProp_ErrorCount
Property (String) MFProp_WarningCount
Property | Attribute | Meaning
MFProp_RemoteSyntaxCheckOptions | - | A list of the Micro Focus Compiler directives to use when background parsing a COBOL file opened in the editor. If the element has a specific value for this property it is used, otherwise the default value is used. The suggested Default Value value is "DIALECT(ENTCOBOL) CICSECM XDB(NOVALIDATE) EXECDLI".
MFProp_RemotePLISyntaxCheckOptions | - | A list of the Micro Focus Compiler directives to use when background parsing a PL/I file opened in the editor. If the element has a specific value for this property it is used, otherwise the default value is used. The suggested Default Value value is "-margins 1,72 -cics".
MFProp_WorkspaceName | Label = Name | The name of the workspace resource, without any path.
MFProp_WorkspacePath | Label = Path | The full workspace path to the resource.
MFProp_CanCompile | Label = Can Compile | Boolean property which indicates whether single file compile is allowed on the resource.
MFProp_ContentType | Label = Content Type | Eclipse content type ID.
MFProp_ErrorCount | Label = Errors | The number of errors in a file, a folder or a project.
MFProp_WarningCount | Label = Warnings | The number of warnings in a file, a folder or a project.
Parent topic: Micro Focus Project Function Package
Related information
Linked Properties for the Eclipse Function Package
Relationship: Application Options Have Custom Attributes


Linked Element Types for the Micro Focus Project Function Package

  • IMTK Category Resource
  • IMTK Service Resource
  • IMTK Operation Resource
  • Category Resource
Parent topic: Micro Focus Project Function Package


IMTK Category Resource

This linked element type represents an IMTK category, such as Web Services.

Attributes

The following specific rules apply to the element type IMTK Category Resource:

Attribute | Description
ID Definition | The ID definition of an IMTK category resource must consist of a numeric IMTK category ID property.
Matchname | Match name provided by a tool type to identify the type of the category resource. The default match name is "MF_IMTK_CATEGORIES_FILE".
Get Children | Reference to an action descriptor which contains tools to fetch the files and folders appropriate to a given category. The tool descriptor Get IMTK Files can be used to retrieve the category resource children.
Parent topic: Linked Element Types for the Micro Focus Project Function Package


IMTK Service Resource

This linked element type represents an IMTK Service Resource.

Attributes

The following specific rules apply to the element type IMTK Service Resource:

Attribute | Description
ID Definition | The ID definition of an IMTK category resource must consist of a string property representing the service ID.
Matchname | The match name provided by a tool type to identify the type of the category resource. The default match name is "MF_IMTK_SERVICES_FILE".
Get Children | Reference to an action descriptor which contains tools to fetch the files and folders appropriate to a given category. The tool descriptor Get IMTK Operations can be used to retrieve the service resource children.
Parent topic: Linked Element Types for the Micro Focus Project Function Package


IMTK Operation Resource

This linked element type represents an operation on an IMTK Web Service.

Attributes

The following specific rules apply to the element type IMTK Operation Resource:

Attribute | Description
ID Definition | The ID definition of an IMTK operation resource must consist of a string property representing the operation name.
Matchname | The match name provided by a tool type to identify the type of the category resource. The default match name is "MF_IMTK_OPERATIONS_FILE".

Linked IMTK operations are automatically refreshed when changes are made to the corresponding Web Service definition file.

Parent topic: Linked Element Types for the Micro Focus Project Function Package


Category Resource

This linked element type represents a non-IMTK category, such as COBOL Programs or PL/I source files. It also represents a pseudo-category, "Other Files", which contains files which are not normally sorted into a category.

Attributes

The following specific rules apply to the element type Category Resource:

Attribute | Description
ID Definition | The ID definition of a category resource must contain a numeric category ID property, followed by a string property which contains the Eclipse path to the project resource.
Matchname | The match name provided by a tool type to identify the type of the category resource. The default match name is "MF_CATEGORIES_FILE".
Get Children | Reference to an action descriptor which contains tools to fetch the files and folders appropriate to a given category. The tool descriptor Get Micro Focus Files in Category can be used to retrieve the category resource children.

Linked Category Resource elements provide dynamic icons, which are automatically set to have the same look as categories in the COBOL Explorer view. They display error, warning, and information overlays. They are automatically refreshed when changes are made to the files in the corresponding categories.

Parent topic: Linked Element Types for the Micro Focus Project Function Package


Tool Types for the Micro Focus Project Function Package

  • Compile File
  • Get Dependent Elements
  • Get Dependent Programs
  • Get IMTK Files
  • Get IMTK Operations
  • New Project From Template
  • Get Populated IMTK Categories
  • Invoke IMTK Operation Command
  • Invoke IMTK Service Command
  • Open In Context
Parent topic: Micro Focus Project Function Package


Compile File

This tool compiles an individual source file, this is only valid when Build Automatically is turned off and the Can Compile property of the resource is true.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the source's resource.
Parent topic: Tool Types for the Micro Focus Project Function Package


Get Dependent Elements

This tool returns the dependencies of a resource, such as the copy files directly used by a program.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the source's resource.
2 [M] | I | String | The identifier of the parent resource as returned by a previous invocation of this tool (0 for main source file).
3 [M] | O | File | The list of dependencies.

The output file descriptor has the following structure:

No | Target ID
1 [M] | The dependent file's name.
2 [M] | The dependent file's path.
3 [M] | Whether the file is part of the workspace or is an "external" file.
4 [M] | The dependent file's usage identifier.
5 [M] | The Eclipse resource identifier.
6 [M] | The main program's Eclipse resource identifier.
7 [M] | The match name used to identify the AWM element type.
8 [M] | Whether the file has child elements.
Parent topic: Tool Types for the Micro Focus Project Function Package


Get Dependent Programs

This tool returns the programs which depend on a resource, such as the programs which use a copy file.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the source's resource.
2 [M] | O | File | The list of dependent programs.

The output file descriptor has the following structure:

No | Target ID
1 [M] | The input Eclipse resource identifier.
2 [M] | The dependent program's name.
3 [M] | The dependent program's path.
4 [M] | The match name used to identify the AWM element type.
Parent topic: Tool Types for the Micro Focus Project Function Package


Get IMTK Files

This tool returns the service files contained in an IMTK category, that is the list of IMTK services.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the project.
2 [M] | I | String | The category's identifier.
3 [M] | O | File | The list of service files.

The output file descriptor has the following structure:

No | Target ID
1 [M] | The service's identifier.
2 [M] | The service's name.
3 [M] | The service's class identifier.
4 [M] | The match name used to identify the AWM element type.
Parent topic: Tool Types for the Micro Focus Project Function Package


Get IMTK Operations

This tool returns the IMTK operations contained in an IMTK file.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the project.
2 [M] | I | String | The service's identifier.
3 [M] | O | File | The list of operations.

The output file descriptor has the following structure:

No | Target ID
1 [M] | The operation's name.
2 [M] | The file's name.
3 [M] | The match name used to identify the AWM element type.
Parent topic: Tool Types for the Micro Focus Project Function Package


New Project From Template

Function:

This tool creates a new project by copying a template project.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Path to the template project.
2 [M] | I | String | Name for the new project.
3 [M] | I | String | Path to the new project.
Parent topic: Tool Types for the Micro Focus Project Function Package


Get Populated IMTK Categories

This tool returns the IMTK categories for which a project contains services, such as Web Services, Java Services and so forth.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the source's resource.
2 [M] | O | File | The list of categories.

The output file descriptor has the following structure:

No | Target ID
1 [M] | The category name.
2 [M] | The category's identifier.
3 [M] | The project's Eclipse resource identifier.
4 [M] | The match name used to identify the AWM element type.
Parent topic: Tool Types for the Micro Focus Project Function Package


Invoke IMTK Operation Command

This tool directly executes an IMTK command on an IMTK operation.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The command identifier.
2 [M] | I | String | The project path.
3 [M] | I | String | The service's identifier.
4 [M] | I | String | The operation's name.

The command identifiers are:

Command ID | Function
com.microfocus.eclipse.imtk.ui.delete | Delete the operation.
com.microfocus.eclipse.imtk.ui.OperationProperties | Show the properties dialog.
com.microfocus.eclipse.imtk.ui.open | Open the operation editor.
Parent topic: Tool Types for the Micro Focus Project Function Package


Invoke IMTK Service Command

This tool directly executes an IMTK command on an IMTK service.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The command identifier.
2 [M] | I | String | The project path.
3 [M] | I | String | The service's identifier.

The command identifiers are:

Command ID | Function
com.microfocus.eclipse.imtk.ui.NewOperation | Create a new operation for the service.
com.microfocus.eclipse.imtk.ui.delete | Delete the service.
com.microfocus.eclipse.imtk.ui.open | Open the service editor.
com.microfocus.eclipse.imtk.ui.deploy | Deploy the service.
com.microfocus.eclipse.imtk.ui.generateClient | Generate a client application.
com.microfocus.eclipse.imtk.ui.JavaInterfaceProperties | Show the properties for a Java Service.
com.microfocus.eclipse.imtk.ui.validate | Validate the service.
com.microfocus.eclipse.imtk.ui.WebServiceProperties | Show the properties for a Web Service.
Parent topic: Tool Types for the Micro Focus Project Function Package


Open In Context

This tool opens the source file in an editor in the context of the main program, such as opening a copy file used by many programs in the context of a specific program.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | The Eclipse path to the source's resource.
2 [M] | I | String | The Eclipse path to the main programs resource.
Parent topic: Tool Types for the Micro Focus Project Function Package


Details for the Micro Focus Project Function Package

The Eclipse function package provides a linked property called Project Natures (see Linked Properties for the Eclipse Function Package).

This is an important property during modeling, for example, to retrieve project lists or to enable actions dependent on the project type.

The integrated Enterprise Developer Projects model makes extensive use of this property.

The project natures of the Micro Focus project types are listed below.

Project Nature | Micro Focus projects which have associated this nature
com.microfocus.eclipse.project.cobolNature | All COBOL projects
com.microfocus.eclipse.project.remoteCobolNature | All remote COBOL projects
com.microfocus.eclipse.project.pureRemoteCobolNature | Remote COBOL projects using the RSE file system
com.microfocus.eclipse.coboljvm.coboljvmNature | All COBOL JVM projects
com.microfocus.eclipse.project.copylibNature | All COBOL Copylib projects
com.microfocus.eclipse.project.remoteCopylibNature | All remote COBOL Copylibs projects
com.microfocus.eclipse.project.pureRemoteCopylibNature | Remote COBOL Copylib projects using the RSE file system
com.microfocus.eclipse.pli.project.pliNature | All PL/I projects
com.microfocus.eclipse.pli.remote.remotePliNature | All remote PL/I projects
com.microfocus.eclipse.pli.remote.pureRemotePliNature | Remote PL/I projects using the RSE file system
com.microfocus.eclipse.edt.core.edtNature | All Mainframe project (local and remote, COBOL and PL/I)
Micro Focus project | Associated Natures
COBOL project | com.microfocus.eclipse.project.cobolNature
Mainframe COBOL project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.edt.core.edtNature
NFS Remote COBOL project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.project.remoteCobolNature
RSE Remote COBOL project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.project.remoteCobolNature com.microfocus.eclipse.project.pureRemoteCobolNature
Mainframe NFS Remote COBOL project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.project.remoteCobolNature com.microfocus.eclipse.edt.core.edtNature
Mainframe RSE Remote COBOL project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.project.remoteCobolNature com.microfocus.eclipse.project.pureRemoteCobolNature com.microfocus.eclipse.edt.core.edtNature
COBOL JVM project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.coboljvm.coboljvmNature
NFS Remote COBOL JVM project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.coboljvm.coboljvmNature com.microfocus.eclipse.project.remoteCobolNature
RSE Remote COBOL JVM project | com.microfocus.eclipse.project.cobolNature com.microfocus.eclipse.coboljvm.coboljvmNature com.microfocus.eclipse.project.remoteCobolNature com.microfocus.eclipse.project.pureRemoteCobolNature
COBOL Copylib project | com.microfocus.eclipse.project.copylibNature
NFS Remote COBOL Copylib project | com.microfocus.eclipse.project.copylibNature com.microfocus.eclipse.project.remoteCopylibNature
RSE Remote COBOL Copylib project | com.microfocus.eclipse.project.copylibNature com.microfocus.eclipse.project.remoteCopylibNature com.microfocus.eclipse.project.pureRemoteCopylibNature
PL/I project | com.microfocus.eclipse.pli.project.pliNature
Mainframe PL/I project | com.microfocus.eclipse.pli.remote.remotePliNature com.microfocus.eclipse.edt.core.edtNature
NFS Remote PL/I project | com.microfocus.eclipse.pli.project.pliNature com.microfocus.eclipse.pli.remote.remotePliNature
RSE Remote PL/I project | com.microfocus.eclipse.pli.project.pliNature com.microfocus.eclipse.pli.remote.remotePliNature com.microfocus.eclipse.pli.remote.pureRemotePliNature
Mainframe NFS Remote PL/I project | com.microfocus.eclipse.pli.project.pliNature com.microfocus.eclipse.pli.remote.remotePliNature com.microfocus.eclipse.edt.core.edtNature
Mainframe RSE Remote PL/I project | com.microfocus.eclipse.pli.project.pliNature com.microfocus.eclipse.pli.remote.remotePliNature com.microfocus.eclipse.pli.remote.pureRemotePliNature com.microfocus.eclipse.edt.core.edtNature
Parent topic: Micro Focus Project Function Package
Related information
Attributes for the Eclipse Function Package
Get Eclipse Projects
Linked Properties for the Eclipse Function Package
Select Resource


Micro Focus Servers Function Package

This section provides a reference for tools used in Micro Focus Servers function package support.

  • Linked Properties for the Micro Focus Servers Function Package
  • Tool Types for the Micro Focus Servers Function Package
Parent topic: Function Packages


Linked Properties for the Micro Focus Servers Function Package

The following linked properties are supported by the Micro Focus Servers function package:

Linked Property Name | Content
Associated projects | Projects associated with the server.
Status | Server status.
User name | User name used to access the server.
User group | User group the user name belongs to.
Server bitism | Server bitism.
CICS enabled | Indicates whether CICS is enabled on the server.
Debug enabled | Indicates whether debugging is enabled on the server.
Coverage enabled | Indicates whether coverage is enabled on the server.
Profiler enabled | Indicates whether profiler is enabled on the server.
TN3270 port | Returns TN3270 port value.
JES enabled | Indicates whether the region has an associated catalog and if is JES enabled.
JES catalog location | Return the regions JES catalog location.
Parent topic: Micro Focus Servers Function Package


Tool Types for the Micro Focus Servers Function Package

  • Start Server
  • Stop Server
  • Create Server
  • Get Servers
  • Get Directory Servers
  • Clear Credentials
  • Delete Server
  • Associate Region With Project
  • Dissociate Project From Region
Parent topic: Micro Focus Servers Function Package


Start Server

Function:

This tool issues a start command to the server described by the parameters. In addition, it adds the server to the Server Explorer view if the Directory Server is not already known.

Tool Attribute:

Attribute | Type | Description
Display name | String | The name to show for the directory server in the server explorer view.
Host name | String | The name of or the IP address of the host running the directory server.
Host port | String | The port number the directory server is running with. This attribute must only contain digits.
Server name | String | The name of the server that you want to start.
User name | String | The name of the user to supply when starting the region. If this attribute is supplied empty no name is passed.
Password | String | The password for the user supplied. If the User name was empty, this too can be empty
Group (optional) | String | The users group.
Wait String Specifies whether the tool should wait for the server to stop before returning. Valid values are:
  • True
  • False
Parent topic: Tool Types for the Micro Focus Servers Function Package


Stop Server

Function:

This tool issues a stop command to the server described by the parameters. In addition, it adds the server to the Server Explorer view if the Directory Server is not already known.

Tool Attribute:

Attribute | Type | Description
Display name | String | The name to show for the directory server in the server explorer view.
Host name | String | The name of or the IP address of the host running the directory server.
Host port | String | The port number the directory server is running with. This attribute must only contain digits.
Server name | String | The name of the server that you want to stop.
User name | String | The name of the user to supply when stopping the region. If this attribute is supplied empty no name is passed.
Password | String | The password for the user supplied. If the User name was empty, this too can be empty
Group (optional) | String | The users group.
Wait String Specifies whether the tool should wait for the server to start before returning. Valid values are:
  • True
  • False
Parent topic: Tool Types for the Micro Focus Servers Function Package


Create Server

Function:

This tool creates a server described by the parameters under the Directory Server and updates the Server Explorer view.

Tool Attribute:

Attribute | Type | Description
Display name | String | The name to show for the directory server in the server explorer view.
Host name | String | The name of or the IP address of the host running the directory server.
Host port | String | The port number the directory server is running with. This attribute must only contain digits.
Server name | String | The name of the server that you want to create.
Template | String | The path to the template to be used to create the server.
64 bit String Specifies whether the region should be created to run 64-bit binaries. Valid values are:
  • True
  • False
Parent topic: Tool Types for the Micro Focus Servers Function Package


Get Servers

Function:

This tool returns servers inside in a directory server.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Host name of a directory server.
2 [M] | O | File | The list of servers.

The output file descriptor has the following structure:

Parameter # | Description
1 [M] | The server's identifier
2 [M] | Server name.
Parent topic: Tool Types for the Micro Focus Servers Function Package


Get Directory Servers

Function:

This tool returns Micro Focus directory servers listed in the server explorer view.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | O | File | The list of directory servers.

The output file descriptor has the following structure:

Parameter # | Description
1 [M] | Host name.
2 [M] | Server address (IPv4/Hostname).
3 [M] | Port number.
4 [M] | The match name used to identify the AWM element type.
Parent topic: Tool Types for the Micro Focus Servers Function Package


Clear Credentials

Function:

This tool clears the stored credentials on the described region.

Tool Attribute:

Attribute | Type | Description
Display name | String | The name to show for the directory server in the server explorer view.
Host name | String | The name of or the IP address of the host running the directory server.
Host port | String | The port number the directory server is running with. This attribute must only contain digits.
Server name | String | The name of the server that you want to stop.
Parent topic: Tool Types for the Micro Focus Servers Function Package


Delete Server

Function:

This tool deletes a Server from a Directory Server.

Tool Attribute:

Attribute | Type | Description
Display name | String | The name to show for the directory server in the server explorer view.
Host name | String | The name of or the IP address of the host running the directory server.
Host port | String | The port number the directory server is running with. This attribute must only contain digits.
Server name | Mass Processing | The name of the server that you want to delete.
Parent topic: Tool Types for the Micro Focus Servers Function Package


Associate Region With Project

Function:

This tool associates a server with a project.

Tool Attribute:

Attribute | Type | Description
Display name | String | The name to show for the directory server in the server explorer view.
Host name | String | The name of or the IP address of the host running the directory server.
Host port | String | The port number the directory server is running with. This attribute can only contain digits.
Server name | String | The name of the server that you want to stop.
Project name | String | The name of the project to associate with the server.
Parent topic: Tool Types for the Micro Focus Servers Function Package


Dissociate Project From Region

Function:

This tool dissociates a project from its server.

Tool Attribute:

Attribute | Type | Description
Project name | String | The name of the project to dissociate from its server.
Parent topic: Tool Types for the Micro Focus Servers Function Package


MVS Function Package

This section provides a reference for functions and tools used in MVS function package support.

  • Attributes of the MVS Function Package
  • Linked Element Types for the MVS Function Package
  • Copy MVS File into Clipboard/Paste MVS File from Clipboard
  • Linked Properties for the MVS Function Package
  • Tool Types for the MVS Function Package
Parent topic: Function Packages


Attributes of the MVS Function Package

Attribute | Type | Description
Job Ended Notification Time | Integer | The time in seconds “Job Ended” notifications stay visible until they automatically fade out. See tools Submit JCL and Execute ISPF Command for more information. When set to “0”, notifications never fade out and must be closed manually. Default value: 10
Parent topic: MVS Function Package


Linked Element Types for the MVS Function Package

MVS Resource

The MVS function package contains one linked element type, called MVS Resource. Both MVS data set and MVS data set member element types can be defined using this linked element type.

Definition of Linked MVS Resource Element Types

Linked MVS Resource element types must be set up in the following way:

Attribute | Description
ID Definition | The ID definition of linked MVS element types must contain exactly one key property, which must be the “Resource Identifier” value returned by Get Data Sets and Get Members tool types.
Matchname | Match name provided by a tool type to identify the type of the MVS resource. See Get Data Sets and Get Members for more information on possible match names.

Relationship | Description
Has Property -> MVS Resource Identifier | Linked MVS Resource element types require to have the MVS Resource Identifier property as one of their “Has Property” relationships.
Has Property -> Data Set Name / Member Name Element Name = true | In order to support automatic element updates after delete and rename operations, linked MVS elements require to have one Has Property relationship with the attribute “Element Name” set to true. MVS Data Sets: Property “Data Set Name" PO Data Set Members: Property “Member Name"
Get All Properties | It is recommended to define Get All Properties actions for linked MVS Resource elements: MVS Data Sets: Tool “Get Data Set Attributes" PO Data Set Members: Tool “Get Member Attributes" In order to update element properties on execution, the tools need to have the “Resource Processing” attribute set to “UPDATE".

Linked MVS elements provide the following functions:

Drag & Drop Support
Linked MVS elements can be dragged onto other resources and vice versa, allowing the transfer of data from or to the associated remote system. Drag and drop is supported between the following locations:
  • Within AWM element views, such as Tree Views and Table Views.
    • For example, dragging MVS data set members into an Eclipse linked resource, such as a COBOL project.
  • Between AWM element views and locations on the operating system.
    • For example, dragging files from the desktop into a PO data set.
  • Between AWM element views and COBOL Explorer, PL/I Explorer, Project Explorer or Navigator view.
  • Between AWM element views into Remote System view.
    Note: Due to technical limitations of the RSE framework, it is not possible to drag resources from the RSE view into linked MVS resources.
Note: Only “copy” drag & drop operations are supported for MVS resources. If files are to be moved (not copied) between locations, you must delete them manually from the source location.
Copy/Paste Support
Copy and paste actions can be provided on linked MVS resources using the MVS function package tools “Copy MVS File to Clipboard” and “Paste MVS File from Clipboard”. See Copy MVS File into Clipboard/Paste MVS File from Clipboard for more information.
Dynamic Icons
Icons of linked MVS resources are dynamically set to have the same look as in the MVS Explorer, Remote Systems view.
Note: IDz Restriction - When MVS linked elements are created under IBM Developer for z Systems (IDz) with an IDz RSED server connection, dynamic icons only appear if the MVS files have been retrieved from the server. If an MVS linked element is created with a non MVS function package tool or loaded from cache, a generic icon is shown. Icons of cached linked MVS elements can be updated by refreshing the corresponding element lists.

You can avoid displaying generic icons by setting static element icons in the model.

Parent topic: MVS Function Package
Related information
Linked Element Type


Copy MVS File into Clipboard/Paste MVS File from Clipboard

To provide copy and paste support for MVS elements use the two tools "Copy MVS File into Clipboard" and "Paste MVS File from Clipboard".

Neither tool require input parameters and only work if executed on linked MVS element types.

Copy and paste is supported for the following locations:

  • Within AWM element views.
  • Between the operating system to AWM element views.
    Note: Due to a technical limitation of the RSE framework it is not possible to copy linked MVS resources and paste them in an operating system location.
  • Between AWM element views and COBOL Explorer, PL/I Explorer, Project Explorer or Navigator view.
  • Between AWM element views and Remote System view.
Note: The tool “Paste MVS File from Clipboard” triggers an asynchronous transfer operation. This means, that copied files do not appear immediately after the tool was executed. A manual refresh of the parent container is required.
Parent topic: MVS Function Package


Linked Properties for the MVS Function Package

The MVS function package currently only provides the linked property Paste Allowed. It can be used to disable a paste action containing the tool Paste MVS File from Clipboard.

Once created, the linked property’s True Value and False Value attributes should be set like this:

Attribute | Value
True Value | true
False Value | false

It can then be used in a simple enabled condition using the operator TRUE:

Parent topic: MVS Function Package


Tool Types for the MVS Function Package

  • Browse MVS File
  • Delete Data Set
  • Delete Member
  • Dequeue MVS File
  • Edit MVS File
  • Get Data Set Attributes
  • Get Data Sets
  • Get Members
  • Get Member Attributes
  • Rename DataSet
  • Rename Member
  • Submit JCL
Parent topic: MVS Function Package


Browse MVS File

Function:

This tool is used to open the remote file belonging to the selected element in the editor, in read mode (Browse).

Tool Attribute:

Attribute | Type | Description
Editor ID [O] | String | The ID of the editor that should be used to open the file.

If you want to make sure that a specific editor is used for all users, you should specify the editor identifier in the AWM model. To find the editor identifier, open the editor and press Alt+Shift+F1 in the editor pane. A dialog box opens and displays the editor identifier among other information.

Example:

Press Alt+Shift+F1 in the Micro Focus COBOL Editor to see that its editor identifier is com.microfocus.eclipse.editor.cobol.CobolEditor.

Parameter No | I/O | Type | Meaning
1 [M] | I | file | References the file on the remote system that should be opened in browse mode.
Parent topic: Tool Types for the MVS Function Package


Delete Data Set

Function

This tool is used to delete MVS data sets.

Attributes:

Attribute | Type | Description
Mass Processing Error Handling [M] Selection Possible values:
Abort
Abort and return an error on the first failed delete operation. This is the default value.
Ignore
Ignore any errors and continue processing.
Show Confirmation Dialog [M] | Boolean | Determines whether a confirmation dialog box is shown before the deletion of the data sets.

Parameters:

Parameter # | I/O | Type | Description
1[M] | I | String/Mass Processing | The data set name of the data set which is to be deleted.
Note: In order to have the view refreshed after the tool execution, the resource processing of the tool must be defined as follows:

  • DELETE

    All selected data sets are removed from the UI. This is recommended if the attribute “Mass Processing Error Handling” is set to “Abort”. If any exception occurs, the view must be refreshed manually.

  • TOOL_DEFINED

    Only data sets which have been successfully deleted from the host are removed from the UI. This is recommended if the attribute “Mass Processing Error Handling” is set to “Ignore”.

Parent topic: Tool Types for the MVS Function Package


Delete Member

Function

This tool is used to delete members from a PO data set.

Attributes:

Attribute | Type | Description
Mass Processing Error Handling [M] Selection Possible values:
Abort
This is the default value. Abort and return an error on the first failed delete operation.
Ignore
Ignore any errors and continue processing.
Show Confirmation Dialog [M] | Boolean | Determines whether a confirmation dialog is shown before the deletion of members.

Parameters:

Parameter # | I/O | Type | Description
1[M] | I | String/Mass Processing | The data set name of the member which should be deleted.
2[M] | I | String/Mass Processing | The member name of the member which should be deleted.
Note: In order to have the view refreshed after the tool execution, the resource processing of the tool should be defined as follows:
DELETE
All selected members are removed from the UI. This is recommended if the attribute “Mass Processing Error Handling” is set to “Abort”. If any exception occurs, the view must be refreshed manually.
TOOL-DEFINED
Only members which have been successfully deleted from the host are removed from the UI. This is recommended if the attribute “Mass Processing Error Handling” is set to “Ignore”.
Restriction: A combination of String and Mass Processing input parameters are not supported.
Parent topic: Tool Types for the MVS Function Package


Dequeue MVS File

Function:

This tool is used to release the ISPF Edit enqueue of a data set or a member of a PO data set.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | References the MVS sequential data set or a PDS member for which the enqueue should be released. The member must be fully qualified in the form dataset(member).
Note: AWM creates an enqueue automatically if an MVS data set or member is transferred to the client for remote update purposes. This is typically done in remote edit scenarios. The dequeue is also done automatically if the editor is closed. This dequeue function should only be used if AWM is not able to dequeue a file automatically, for example, after a system crash.
Parent topic: Tool Types for the MVS Function Package


Edit MVS File

Function:

This tool is used to open the remote file belonging to the selected element for editing in the editor.

Attribute | Type | Description
Editor ID [O] | String | The ID of the editor that should be used to open the file.

If you want to make sure that a specific editor is used for all users, you should specify the editor identifier in the AWM model. To find the editor identifier, open the editor and press Alt+Shift+F1 in the editor pane. A dialog box opens and displays the editor identifier among other information.

Press Alt+Shift+F1 in the Micro Focus COBOL Editor to see that its editor identifier is com.microfocus.eclipse.editor.cobol.CobolEditor.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | file | References the file on the remote system that should be opened in the editor.
Parent topic: Tool Types for the MVS Function Package


Get Data Set Attributes

Function:

This tool is used to get the attributes of a single MVS data set. It is typically used to refresh the properties of data sets which were returned by “Get Data Sets”.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String/MassProcessing | Data set name. The data set to return properties for.
2 [M] | O | String/MassProcessing | Type of the data set.
3 [M] | O | String/MassProcessing | Data set organisation.
4 [M] | O | String/MassProcessing | Record format of the data set.
5 [M] | O | String/MassProcessing | Record length of the data set.
6 [M] | O | String/MassProcessing | Space units of the data set.
7 [M] | O | String/MassProcessing | Primary quantity of the data set.
8 [M] | O | String/MassProcessing | Secondary quantity of the data set.
9 [M] | O | String/MassProcessing | Total quantity of the data set.
10 [M] | O | String/MassProcessing | Volume serial of the data set.
11 [M] | O | String/MassProcessing | Block size of the data set.
12 [M] | O | String/MassProcessing | Whether the data set is SMS managed.
13 [M] | O | String/MassProcessing | Whether the data set is accessible.
14 [M] | O | String/MassProcessing | Suffix of the data set.
15 [M] | O | String/MassProcessing | Whether the data set can be browsed.
16 [M] | O | String/MassProcessing | Whether the data set is editable.

In order to refresh properties of a single data set element, the “Resource Processing” attribute of the tool descriptor must be set to “UPDATE”.

Note: For mass processing support:
  • The action using the tool must be setup to support mass processing. See Mass Processing Overview for more information.
  • Resource processing is currently not supported for mass processing execution. The resource processing attribute of the tool "Get Data Set Properties" must be set to “READ” for mass processing.
  • Although all parameters should have the type “MassProcessing” for mass processing execution, this tool accepts “String” parameters and treats them depending on the “Mass Processing” attribute of the parent action descriptor. It is not necessary to change all the parameter types to “MassProcessing” for mass processing execution.
  • Currently there is no mass processing server implementation for “Get Data Set Properties”, which means that the tool gets the properties of each data set one by one. If no other mass processing tool is used within the same action descriptor, it is sufficient to model the tool as single processing and simply enable multi selection, for example, in an “element type has action” relationship enabled condition. See Enabled/Visible Condition for more information.
Parent topic: Tool Types for the MVS Function Package


Get Data Sets

Function:

This tool is used to get a list of data sets corresponding to a given filter.

Note: Get Data Sets tool descriptors created in models prior AWM V3.0 are marked as deprecated in models. They still work as before but do not return the “resource identifier” property, which must be used as ID definition property for linked MVS element types.

Tool Attribute:

Get Data Sets can return different data set match names. If required, different match names can be returned for specific data set types, including sequential, partitioned organized, migrated, VSAM, and so on. This is to support simple scenarios, where different element types are not required, as well as complex models, which require different data set element types with specific actions, and properties.

By default, the tool distinguishes three data set types returning three different match names:

  • PO data set
  • PS data set
  • Migrated data set
Attribute | Type | Description
Element Type Distinction | Boolean | Specifies whether different match names should be returned by the tool. When set to false, the tool returns the same match name for all data set types. If true, supported data set types can be customized in more detail. Default value: true
Matchname Data Set | String | Specifies the match name that should be used for returned data sets, if “Element Type Distinction” is set to false. Default value: MVSDATASET
Distinguish GDG Files | Boolean | Specifies whether a specific match name should be returned for GDG files. Only visible if Element Type Distinction is set to true. Default value: false
Distinguish Load Libraries | Boolean | Specifies whether a specific match name should be returned for load libraries. Only visible if Element Type Distinction is set to true. Default value: false
Distinguish Migrated Data Sets | Boolean | Specifies whether a specific match name should be returned for migrated data sets. Only visible if Element Type Distinction is set to true. Default value: true
Distinguish VSAM Files | Boolean | Specifies whether a specific match name should be returned for GDG files. Only visible if Element Type Distinction is set to true. Default value: false
Matchname GDG | String | Specifies the match name returned for GDG files. Only visible if Distinguish GDG Files is set to true. Default value: MVSGDG
Matchname Load | String | Specifies the match name returned for load libraries. Only visible if Distinguish Load Libraries is set to true. Default value: MVSLOADLIB
Matchname Migrated | String | Specifies the match name returned for migrated data sets. Only visible if Distinguish Migrated Data Sets is set to true. Default value: MVSMIGRATED
Matchname PO | String | Specifies the match name returned for PO data sets. Only visible if Element Type Distinction is set to true. Default value: MVSPO
Matchname Sequential | String | Specifies the match name returned for sequential data sets. Only visible if Element Type Distinction is set to true. Default value: MVSSEQ
Matchname VSAM | String | Specifies the match name returned for VSAM files. Only visible if Distinguish VSAM Files is set to true. Default value: MVSVSAM

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | Data Set Filter. Data set filters can be specified in the same way as under z/OS ISPF. The reference variable userid can be used in the filter string. Valid filter specifications are, for example: &userid., &userid.*, SYS1.PROC*, &userid..TEST.*, &userid..TES%.* * is a substitute for any number of characters; % is a substitute for exactly one character. It is possible to specify more than one data set filter separated by a semicolon.
2 [M] | O | File | References the file contained in the Data Set List.

The output file descriptor (Data Set List) should be of type InputStream and have the following structure:

No | Target ID
1 | Name of the data set.
2 | Resource identifier, used for linked MVS element types.
3 | Matchname identifying the data set element type.
4 | Type of the data set.
5 | Organization of the data set.
6 | Record Format of the data set.
7 | Record Length of the data set.
8 | Space Units of the data set.
9 | Primary Quantity of the data set.
10 | Secondary Quantity of the data set.
11 | Total Quantity of the data set.
12 | Volume Serial of the data set.
13 | Block Size of the data set.
14 | SMS Managed of the data set.
15 | Whether the data set is accessible.
16 | Suffix of the data set.
17 | Whether the data set is browsable.
18 | Whether the data set is editable.

When defining the file descriptor you must make sure you define a unique delimiter used to separate the data set properties. The MVS Explorer uses the delimiter "/%/$/".

The match name specified under "Dataset Matchname" must correspond with a match name defined for an element type in the model.

Supported values for the data set type are:

  • LIBRARY
  • HFS
  • PDS
  • LARGE
  • BASIC
  • EXTREQ
  • EXTPREF
  • SEQ
  • VSAM
  • GDG
  • NONE

Supported values for the data set organization are:

  • PS
  • PO
  • DA
  • KSDS
  • ESDS
  • RRDS
  • UNKNOWN (if data set is migrated)
Parent topic: Tool Types for the MVS Function Package


Get Members

Note: Get Members tool descriptors created in models prior AWM V3.0 are marked as deprecated. They still work as before but do not return the properties “resource identifier” and “data set name”. The resource identifier property must be used as ID definition property of linked MVS element types.

Function:

This tool is used to return a list of data set members.

Tool Attribute:

Attribute | Type | Description
Member Matchname | String | Specifies the match name that should be used for returned members. Default: MVSMEMBER

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | Data Set Name.
2 [M] | I | String | Member Filter. Default: *
3 [M] | O | File | References the file contained in the Member List.

The output file descriptor (Member List) should be of type InputStream and has the following structure:

No | Target ID
1 | Name of the member.
2 | Resource identifier, used for linked MVS element types.
3 | Matchname identifying the member element type.
4 | Name of the parent data set.
5 | Size of the member (number of records).
6 | Date when the member was created (format: yyyy/MM/dd).
7 | Date and time when the member was changed (format: yyyy/MM/dd hh:mm:ss).
8 | User ID.
9 | Initial size (number of records) of the member.
10 | Version number.
11 | Member modification level.
12 | Suffix of the member (derived from file mappings ).

When defining the file descriptor you must make sure to define a unique delimiter used to separate the member properties. The MVS Explorer uses the delimiter "/%/$/".

All other properties are returned but always have the value “UNKNOWN”. To obtain those attributes for a member the tool Get Member Attributes can be used, for example, as a Get All Properties Action.

IDz restiction

Due to technical limitations, the tool has less information when executed with an IDz/RDz server instance. The only values returned by the output file are:

No | Target ID
1 | Name of the member.
2 | Resource identifier, used for linked MVS element types.
3 | Matchname identifying the member element type.
4 | Name of the parent data set.
Parent topic: Tool Types for the MVS Function Package


Get Member Attributes

Function:

This tool is used to get the attributes of an MVS PO member.

Parameters:

Parameter # | I/O | Type | Description
1[M] | I | String/Mass Processing | Specifies the name of the PO data set in which the member is located.
2[M] | I | String/Mass Processing | Specifies the name of the PO member
1 [M] | O | String | Specifies the size of the PO member (number of records)
2 [M] | O | String | Specifies the date when the PO member was created (format: yyyy/MM/dd)
3 [M] | O | String | Specifies the date when the PO member was changed (format: yyyy/MM/dd hh:mm:ss)
4 [M] | O | String | Specifies the user ID of the user who changed the PO member
5 [M] | O | String | Specifies the initial size of the PO member (number of records) *
6 [M] | O | String | Specifies the version of the PO member
7 [M] | O | String | Specifies the modification level of the PO member *
8 [M] | O | String | Specifies the suffix of the PO member. This is derived from file mappings.
Note: When the tool is used with an IDz server the value is always “UNKNOWN”.
Parent topic: Tool Types for the MVS Function Package


Rename DataSet

Function:

This tool is used to rename an MVS data set.

Attributes:

Attribute Type Description
Mass Processing Error Handling [M] Selection Possible values:
Abort (Default)
Abort and return an error on the first failed delete operation.
Ignore
Ignore any errors and continue processing.

Parameters:

Parameter # | I/O | Type | Description
1[M] | I | String/Mass Processing | Specifies the name of the data set which should be renamed.
2[M] | I | String/Mass Processing | Specifies the new data set name.

Restrictions:

  • The Resource Processing of the tool can be set to TOOL_DEFINED. In this case, the tool creates a Delete and Insert resource operation. This only works for the current selection. The target property of the data set name input parameter has to be the element type property that describes the data set name of the selected element.
  • A combination of String and Mass Processing input parameters is not supported.
Parent topic: Tool Types for the MVS Function Package


Rename Member

Function:

This tool is used to rename an MVS member.

Attributes:

Attribute Type Description
Mass Processing Error Handling [M] Selection Possible values:
Abort
Abort and return an error on the first failed delete operation (Default).
Ignore
Ignore any errors and continue processing.

Parameters:

Parameter # | I/O | Type | Description
1[M] | I | String/Mass Processing | Specifies the data set name of the member which should be renamed.
1[M] | I | String/Mass Processing | Specifies the name of the member which should be renamed.
2[M] | I | String/Mass Processing | Specifies the new member name.

Restrictions:

  • The Resource Processing of the tool can be set to TOOL_DEFINED. This results in the tool performing a Delete and Insert resource operation. It only works on the current selection. The target property of the member name input parameter has to be equal to the property that describes the member name of the element type.

  • A combination of String and Mass Processing input parameters is not supported.

Parent topic: Tool Types for the MVS Function Package


Submit JCL

Function:

The Submit JCL tool submits JCL from a file or an active editor.

Tool Attributes:

Attribute Type Description
Submit JCL From Selection Specifies whether to submit the JCL from a file or from the editor. Valid values are:
  • An Active Editor
  • File

Parameters:

Parameter # | I/O | Type | Description
1 [O] | I | File | References the file containing the JCL to be submitted, if the JCL should be submitted from a file. This parameter is only necessary when the JCL is submitted from a file. No input parameter is needed if the tool is modeled within an editor action to submit the JCL from the active editor.
Parent topic: Tool Types for the MVS Function Package
Related information
Global Action is an Editor Action


Operating System Function Package

This section provides a reference for functions and tools used in function package support for your OS.

  • Tool Types for the Operating System Function Package
  • Details for the Operating System Function Package
Parent topic: Function Packages


Tool Types for the Operating System Function Package

  • Check File Existence
  • Execute OS Command
  • Select Local OS Resource
Parent topic: Operating System Function Package


Check File Existence

Function:

Checks whether a file or directory exists under a given fully qualified path or symbolic link. Mass processing is supported by the tool.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/File MassProcessing | Specifies a local file system path a symbolic link of a file or directory to check. If a file descriptor is referenced, the resolved value under the “Name Physical” attribute is taken as the path.
2 [M] | O | String/ MassProcessing | Specifies whether a file or folder exists under the given path. Returns either true/false or a property’s True Value/False Value if the referenced property type is “Boolean”.
Parent topic: Tool Types for the Operating System Function Package


Execute OS Command

The tool “Execute OS Command” can schedule commands on the local operating system. Those commands must be specified by using input parameters. Several input parameters are concatenated to a single command string using the input parameter separator attribute as the delimiter.

If a program or a batch file was called by the OS Command, AWM can parse its return values, as long as they obey certain syntax rules:

Syntax | Description | Example
ReturnCode: <returncode> | Return code of the tool (default: 0) | ReturnCode: 12
Message: <message> | Tool message to be displayed in a dialog box (optional) | Message: File %1 was not found!
LogMessage: <message> | Log messages are displayed in the Eclipse Error Log view after the tool is executed. (optional) | LogMessage: Creating file “%filename%”…
OutParm: <parameters> | Output parameters of the tool which must be returned at the very end. Output parameters are optional, but the number of parameters must match with the modeled output parameters. In addition the parameter separator must match with the separator defined in the AWM tool descriptor. | OutParm: value1 value2

The return code indicates whether the called program or batch file executes successfully or ends with warnings or errors. If the return code is higher than 0, a message is returned. If the return code is higher than the maximum allowed return code an error dialog box appears displaying the tool messages, and the action in which the tool executes is aborted. See Application Options for more information.

Messages returned by the OS command are always displayed in a dialog box in the client after the action is executed. As long as the return code is lower than the maximum allowed return code, returned messages from all tools are collected and displayed after the action is finished. Output parameters must be returned at the very end.

Note: Microsoft Windows batch files automatically "echo" every statement, which can cause problems when returning output parameters. Micro Focus strongly recommends you disable statement echoing by using the "@echo off" statement in the batch file.
This example shows a Windows batch file that returns a message, return code and an output parameter:
@echo off
…
echo ReturnCode: 4
echo Message: No customers found for the given filter %1.
echo OutParm: %~dp0customers.txt
Parent topic: Tool Types for the Operating System Function Package
Related information
Application Options


Select Local OS Resource

Function:

The "Select Local OS Resource" tool opens a native file selection dialog from the operating system to enable the user to select one (or several) local files (see figure), or an Eclipse folder selection dialog to select a local folder.

Eclipse folder selection

Attributes:

Attribute | Type | Description
Resource Type Selection Specifies whether the selection dialog should prompt for a folder or file. If the value is “Local OS File”, the dialog does not allow the user to select a folder and vice versa.

Possible values:

  • Local OS File (default)
  • Local OS Folder
File Dialog Behavior Selection Specifies whether to allow selecting multiple files or use the “Selection for Save” mode, which has a slightly different appearance. For example, confirm button is labelled “Save” instead of “Open”.

The attribute is only visible if the Resource Type attribute is “Local OS File”, since multi-selection and “Selection for Save” are currently not supported for folders.

Possible values:

  • Single-selection
  • Multi-selection
  • Selection for Save
Title | String | Specifies the dialog title. If empty, the operating system default title is used, for example, “Open” or “Save”.
Message String Sets a user message for the folder selection dialog.

Only visible if the Resource Type attribute is set to “Local OS Folder”, since the file selection dialog does not have a message field.

Show Optional Parameters | Boolean | Specifies whether to add optional input parameters to the tool descriptor. See Input Parameters for more information.

Parameters:

Parameter No | I/O | Type | Description
1 [O] | I | String | The pre-set path of the selection dialog.
2 [O] | I | String | The pre-set file name of the file selection dialog. Only available if the Resource Type attribute is set to “Local OS File”.
3 [O] | I | String | File extension filters for the file selection dialog. While a file extension filter is active, the dialog only shows files matching the filter. It is possible to define several filters and several extensions for each filter. While the first defined filter is always the default filter on opening the dialog, users can select different filters, if more than one are defined. Each filter is separated by “/”, while every extension must be separated by “;”. Example: *.txt;*.text/*.doc;*.docx Defines two filters with two extensions each. Only available if the Resource Type attribute is set to “Local OS File”. Default value: *.* (show all files)
1 [M] | O | String/File | Used to return the selected OS resources

All input parameters of the tool are optional. They can be enabled by setting the attribute “Show Optional Parameters” to “true”.

Output parameter:

Selected files are always returned by a single output parameter (both for single and multi-selection). Depending on the scenario where the tool should be used, it is possible to return file names in two different ways:

  1. As a property value (default).
    1. Useful for:
      1. Using selected file name(s) as input parameter for a subsequent tool.
      2. Using selected file name as “Name Physical” reference for a local file descriptor.
    2. Modeled by:
      1. Setting file output parameter type to “String”.
      2. Referencing a property as target ID.
    3. Multi selection:
      1. File names are all written as value of the referenced property, separated by the “Out Parm Separator” of the tool descriptor.
  2. As contents of an input stream file descriptor.
    1. Useful for using the tool within a “Retrieve All Values” action. See Retrieve All Values for more information. Users can then select a file or folder for an input field.
    2. Modeled by:
      1. Setting file output parameter type to “File”.
      2. Referencing a file descriptor of the type “Input Stream” as target ID.
    3. Multi selection:
      1. Each selected file is added as a separate row of the input stream.
Parent topic: Tool Types for the Operating System Function Package


Details for the Operating System Function Package

  • Mass processing in an OS command
Parent topic: Operating System Function Package


Mass processing in an OS command

You can pass properties of more than one element to an OS command tool using mass processing.

As soon as an OSCommand tool descriptor is used within a mass processing action descriptor, a parameter file will be generated by the Workflow Manager and added to the OS command. The file is created in the Eclipse workspace, and will contain values of all modeled input parameters of the type MassProcessing. Each selected element will be represented by a single line in the file. The full qualified file name will be added as the last OS command argument in double quotes.

The following pattern is used to create the parameter file:

INPARM0001: <element 1 parm 1><separator>(…)<element 1 parmn>
INPARM0002: <element 1 parm 1><separator>(…)<element 2parmn>
(…)
INPARMnnnn: <element nparm 1><separator>(…)<element nparmn>

Generated Parameter File example:

(3 elements selected):

INPARM0001: Folder_1+_+File 1+_+TEXTFILE
INPARM0002: Folder_1+_+File 2+_+TEXTFILE
INPARM0003: Folder_1+_+File 3+_+TEXTFILE

(The input parameter separator is “+_+”.)

Model:

Note that the mass input parameters have the type "MassProcessing". The "ToolDefinedResourceOperations" output parameters are used for tool-defined resource operations. This tool in particular returns a REMOVE-ELEMENT: resource operation for every deleted file.

Executed OS command (Windows):

cmd.exe /c "C:\bat files\massdelete.bat"  "<workspace path><application path>\PARMLIST.txt"

A called tool will have to parse the parameter file (usually line by line) to process the selection. Tool-defined resource operations or messages can be returned to provide feedback to the user.

Parent topic: Details for the Operating System Function Package
Related information
Mass Processing Overview


IDz Function Package

This function package provides tools which depend on IDz. Therefore this function package is only available in IDz.

AWM supports the IDz specific concept of property groups which are used by IDz editors like the IDz COBOL, PL/I or LPEX editor to support syntax checking, content assist, program outline views and other editor features.

Note: There is a fundamental difference between Micro Focus and IDz editor support in modeled remote edit scenarios. Micro Focus editors require specific properties to support the background parsing process, for example, the SYSLIB property, whereas IDz requires an IDz property group which has to be associated to a file before editing this file. This has some implications on modelling the corresponding IDz tools which are described in this chapter.

Dependent on which edit tool is used, there are different options to associate property groups to an IDz file. If the IDz property group does not exist, it can be created using the Create Property Group tool.

Edit Local File, see Eclipse Function Package for more information.

An IDz local property group need to be associated to the local file.

This can be provided by AWM in two ways:

  1. The AWM element has a property associated which is defined in the model with the special property attribute value “Property Group” and contains the value of an existing IDz local property group at runtime. This IDz local property group is associated automatically to the local file if the Edit Local File tool is called and before the editor pops up.
  2. The IDz tool "Associate Property Group" is used in an edit action before the edit tool is called.

Edit/Browse MVS File, see MVS Function Package for more information.

An IDz remote property group need to be associated to the mainframe data set or member. The IDz tool "Associate Property Group" must be used in an edit action before the edit or browse tool is called.

The "Property Group" tools and the "Open MVS File" tool support the use of a mapping between a z/Server connection and a z/OS IDz connection. The intended scenario is a IDz client using a z/Server connection. In this scenario, the client uses the z/OS IDz connection for setting property groups. This combination results in the full z/Server support and additionally the full IDz editor and property group support.

The mapping can be defined in the group ‘IDz z/OS Server Mapping’ of the Server Settings dialog page of the properties dialog of any subsystem of a Micro Focus z/Server connection:

Properties for MVS Explorer
  • Tool Types for the IDz Function Package
Parent topic: Function Packages
Related information
Browse MVS File
Edit Local File
Edit MVS File
Special Properties


Tool Types for the IDz Function Package

  • Associate Property Group
  • Create Property Group
  • Open MVS File
  • Remove Property Group
Parent topic: IDz Function Package


Associate Property Group

Tool Attribute:

Attribute | Type | Description
Enable System Selection Dialog | Boolean | Specifies whether a dialog should open to select an IDz z/OS Server connection if no valid mapping is defined in the Micro Focus z/Server connection. The behavior of the tool based on this attribute is described in the table below.

Function:

This tool associates an IDz property group to a file. Local IDz property groups can only be associated with local files and remote property groups can only be associated with MVS sequential data sets or PDS members.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | File | File input parameter pointing to the file with which the property group is associated.
2 [M] | I | String | Logical name of the property group that it should be associated with.

The file input parameter can have one of the following types:

  • MVS_PO_Member or MVS_SEQ -> the remote property group with the given logical name is associated with the remote member.
  • Workspace_File -> the local property group with the given logical name is associated with the local file.

If the property group is from parameter type USER_INPUT, a selection dialog appears with all the existing property groups on the system. The property group that is already associated with the member is pre-selected. You have to select the property group that is associated with the input file.

Behavior of the property group tools depending on the ‘Enable System Selection Dialog’ attribute:

Enable Connection Dialog Attribute | IDz z/OS Server Mapping | Dialog Result | Result
True | Not Set | OK pressed | IDz editor opens
True | Not Set | Cancel pressed | Error Message
True | Set and valid |  | IDz editor opens
True | Set and invalid | OK pressed | IDz editor opens
True | Set and invalid | Cancel pressed | Error Message
True | Not set and no IDz z/OS Server connection available |  | Error Message
False | Not Set |  | Error Message
False | Set and invalid |  | Error Message
False | Set and valid |  | IDz editor opens
Parent topic: Tool Types for the IDz Function Package


Create Property Group

Tool Attribute:

Attribute | Type | Description
Enable System Selection Dialog | Boolean | Specifies whether a dialog should open to select an IDz z/OS Server connection if no valid mapping is defined in the Micro Focus z/Server connection. The behavior of the tool based on this attribute is described in the table below.

Function:

This tool creates an IDz property group with a logical name and adds the SYSLIB information to the property group used for the real-time syntax check support in IDz editors.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | The logical name of the property group.
2 [M] | I | String | The programming language category, see below.
3 [M] | I | String | The full list of system libraries used to resolve dependencies (SYSLIB) and optional compile parameters, see below.
4 [O] | I | String | A Boolean value indicating whether the property group is local. Default Value: false
5 [O] | I | String | A Boolean value indicating whether to replace the property group if it already exists. Default value: false
6 [O] | I | String | The name of an existing property group. If this parameter is set, the property group with the passed name is copied and updated with the SYSLIB information specified in the third parameter.

Behavior of the property group tools depending on the ‘Enable System Selection Dialog’ attribute:

Enable Connection Dialog Attribute | IDz z/OS Server Mapping | Dialog Result | Result
True | Not Set | OK pressed | IDz editor opens
True | Not Set | Cancel pressed | Error Message
True | Set and valid |  | IDz editor opens
True | Set and invalid | OK pressed | IDz editor opens
True | Set and invalid | Cancel pressed | Error Message
True | Not set and no IDz z/OS Server connection available |  | Error Message
False | Not Set |  | Error Message
False | Set and invalid |  | Error Message
False | Set and valid |  | IDz editor opens

Language category:

An IDz property group contains different named categories. The tool Create Property Group needs to know which category the SYSLIB information has to be added. The language category is not case sensitive. The following table shows the map from programming languages to the permitted IDz category values.

Property group | Language | Permitted values as language category
IDz local property group | COBOL PL/I | COBOL PLI, PL1
IDz remote property group | COBOL PL/I Assembler C/C++ | COBOL PLI, PL1 Assembler, ASM C_CPP, C, CPP, C/CPP

SYSLIB definition:

The SYSLIB definition in the third input parameter has to be defined with key parameters to differentiate between local and remote system files.

The following key parameters are allowed:

  • localsyslib(): for system libraries which are located locally.
  • remotesyslib(): for system libraries which are located on a remote system.
  • compileoption(): for additional compile options.

Rules:

  • The SYSLIB is the input between "key( " and the last ")" before the next key.
  • If no keys are given, the full value of the parameter SYSLIB is interpreted as system libraries which are located on a remote system.
  • If the value of the parameter SYSLIB is blank, the property group is created with default system libraries, or if the property group template exists, its system libraries are copied.
  • Local SYSLIB definitions which contain blank characters need to be put in quotation marks.
  • A semicolon in remote SYSLIB definitions is replaced with a space.

Example:

Input = localsyslib("c:\Program File\folder“) remotesyslib(hlq.dev.copylib;hlq.prod.copylib) compileoption( co1 co2)

This input is interpreted as follows:

LocalSyslib = "c:\Program File\folder“

RemoteSyslib= hlq.dev.copylib;hlq.prod.copylib

CompileOption= co1 co2

Parent topic: Tool Types for the IDz Function Package


Open MVS File

Function:

This tool is used to open the remote file belonging to the selected element being edited or browsed (read only) in the editor. The tool enables you to use IDz editor facilities (for example, downloading copybooks based on property groups) while working with a Micro Focus z/Server connection. Mapping between the Micro Focus z/Server connection and an IDz z/OS Server connection has to be defined. You can define the mapping in the IDz z/OS Server Mapping list, in the Server Settings dialog page in the properties dialog of any subsystem.

You can use the tool to open an MVS file for editing or browsing if it is associated with an RSED connection. When the connection used with the AWM model containing this tool is an RSED connection, then the RSED connection is used for the remote edit or browse of MVS files.

Tool Attribute:

Attribute | Type | Description
Enable System Selection Dialog | Boolean | Specifies whether a dialog should open to select a IDz z/OS Server connection, if no valid mapping is defined in the Micro Focus z/Server connection. The behavior of the tool based on this attribute is described in the table below.
Mode Selection Specifies whether the tool opens the remote file in edit or browse (read only) mode. The valid values are:
  • Edit
  • Browse

Parameters:

Parameter No | I/O | Type | Description
1[M] | I | File | References the file on the remote system that should be opened in browse or edit mode.

Behavior of the tool depending on the 'Enable Connection Dialog' tool attribute:

Enable Connection Dialog Attribute | IDz z/OS Server Mapping | Dialog Result | Result
True | Not Set | OK pressed | IDz editor facilities are available
True | Not Set | Cancel pressed | IDz editor facilities are not available
True | Set and valid | No dialog is opened | IDz editor facilities are available
True | Set and invalid | OK pressed | IDz editor facilities are available
True | Set and invalid | Cancel pressed | IDz editor facilities are not available
True | Not set and no IDz z/OS Server connection available | No dialog is opened | Error Message
False | Not Set | No dialog is opened | IDz editor facilities are not available
False | Set and invalid | No dialog is opened | Error Message
False | Set and valid | No dialog is opened | IDz editor facilities are available

The connection dialog opens only once. If an RSED connection is selected in the dialog, then the connection is used for later edit/browse scenarios without opening the dialog again.

Parent topic: Tool Types for the IDz Function Package


Remove Property Group

Tool Attribute:

Attribute | Type | Description
Enable System Selection Dialog | Boolean | Specifies whether a dialog should open to select an IDz z/OS Server connection if no valid mapping is defined in the Micro Focus z/Server connection. The behavior of the tool based on this attribute is described in the table below.

Function:

This tool removes an IDz property group with the given logical name.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | The value must be the name of an existing property group.
2 [O] | I | String | A Boolean value indicating whether the property group is local (true) or remote (false)

If the second parameter is not set, the remote and local property group is deleted on the system.

Behavior of the property group tools depending on the ‘Enable System Selection Dialog’ attribute:

Enable Connection Dialog Attribute | IDz z/OS Server Mapping | Dialog Result | Result
True | Not Set | OK pressed | IDz editor opens
True | Not Set | Cancel pressed | Error Message
True | Set and valid |  | IDz editor opens
True | Set and invalid | OK pressed | IDz editor opens
True | Set and invalid | Cancel pressed | Error Message
True | Not set and no IDz z/OS Server connection available |  | Error Message
False | Not Set |  | Error Message
False | Set and invalid |  | Error Message
False | Set and valid |  | IDz editor opens
Parent topic: Tool Types for the IDz Function Package


SVN Function Package

The SVN function package is a function package which provides tool types to support an SVN integration in an AWM model.

The execution of tools from the SVN function packages requires that the Subclipse plug-in is installed in Eclipse.

  • Linked Properties for the SVN Function Package
    Describes the linked properties in the SVN function package.
  • Tool Types for the SVN Function Package
Parent topic: Function Packages


Linked Properties for the SVN Function Package

Function:

The following linked properties are supported by the SVN function package. They can be used in the AWM model as read-only linked properties in addition to the linked properties provided in the Eclipse package. Updates are only provided by SVN functions. The values of all SVN linked properties depend on the Eclipse resource, so it is necessary to associate the resource identifier property when creating the linked property in an AWM model.

Parameters:

Linked Property Name | Content
Locked | SVN Locked mark.
Modified | SVN modify attribute.
Revision | SVN revision number.
Parent topic: SVN Function Package


Tool Types for the SVN Function Package

  • Add
    Description of the SVN Add tool type.
  • Add Repository
    Description of the SVN Add Repository Tool Type.
  • Check Out With UI
    Description of the SVN check out with UI tool type.
  • Clean Up
    Description of the SVN clean up tool type.
  • Commit
    Description of the SVN Commit tool type.
  • Delete SVN Property
    Description of the Delete SVN Property tool type.
  • Discard Repository
    Description of the SVN Discard Repository tool type.
  • Get Properties
    Description of the SVN Get Properties tool type.
  • Get Root Folders
    Defines the first level folders for the SVN application.
  • Get SVN Property
    Description of the Get SVN Property tool type.
  • GET Repositories
    Description of the SVN Get Repositories Tool Type.
  • Get Repository Content
    Description of the SVN get content command tool type.
  • Get Repository Items
    Description of the SVN Tool Type Get Repository Items.
  • Get Working Copy Resources
    Description of the SVN Get Working Copy resources tool type.
  • Get Working Copies
    Description of the SVN Get Working Copies tool type.
  • Lock
    Description of the SVN Lock tool type.
  • Log
    Description of the SVN Log tool type.
  • Remove
    Description of the SVN Remove tool type.
  • Revert
    Description of the SVN Revert tool type.
  • Set SVN property
    Description of the Set SVN Property tool type.
  • Unlock
    Description of the SVN Unlock tool type.
  • Update
    Description of the SVN Update tool type.
Parent topic: SVN Function Package


Add

Function:

This tool adds a working copy entry to the SVN repository. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to the working copy entry to be added.
2 [M] | I | String | Recursion depth up to which the add should be applied (2 = infinite, 1 = one, 0 = zero).
Parent topic: Tool Types for the SVN Function Package


Add Repository

Function:

Adds a new SVN repository entry to the Application Explorer view.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Path to the SVN repository location.
2 [M] | O | String | Path to the SVN repository location returned by the tool.
3 [M] | O | String | Relative path to the SVN repository location (always blank).
4 [M] | O | String | Match name identifying a SVN repository entry.
Parent topic: Tool Types for the SVN Function Package


Check Out With UI

Function:

This tool opens the SVN check out dialog for a SVN repository entry. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Full path to the SVN repository entry.
2 [M] | I | String / Mass Processing | Relative path to the SVN repository entry.
Parent topic: Tool Types for the SVN Function Package


Clean Up

Function:

This tool executes the SVN clean up function on a working copy. This means it tries to get an inconsistent working copy into a workable and usable state. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to the working copy.
Parent topic: Tool Types for the SVN Function Package


Commit

Function:

This tool commits the changes in a SVN working copy to the SVN repository. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to the SVN working copy entry which should be committed.
2 [M] | I | String | Commit message.
3 [M] | I | String | Recursive depth in which the commit should be applied (2 = infinite, 1= one, 0 = zero).
4[M] | I | String | Whether SVN locks should be kept after the commit (Boolean).
Parent topic: Tool Types for the SVN Function Package


Delete SVN Property

Function:

This tool deletes an SVN property of an SVN working copy entry.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Eclipse path to the SVN working copy entry for which the property should be deleted.
2 [M] | I | String | SVN property ID.
3 [M] | I | String | Specifies whether the delete should be applied recursively (Boolean).
Parent topic: Tool Types for the SVN Function Package


Discard Repository

Function:

This tool removes a SVN repository entry from the Application Explorer view. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Path to the SVN repository to be removed from the Application Explorer view.
Parent topic: Tool Types for the SVN Function Package


Get Properties

Function:

This tool retrieves the SVN properties of an SVN working copy entry.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Eclipse path to the working copy entry for which the properties should be retrieved.
2 [M] | O | File | A file descriptor pointing to the file containing the returned SVN properties.

The output file descriptor has the following structure:

No | Target
1 [M] | SVN property ID.
2 [M] | SVN property value.
Parent topic: Tool Types for the SVN Function Package


Get Root Folders

Function:

This tool defines the first level folder structure for the SVN application in the Application Explorer view. This structure is defined in the AWM model by defining input parameters with static values for each root folder.

Parameters:

Parameter # | I/O | Type | Description
1,....,n [M] | I | String | A static value is typically used for each input parameter defining the name of a root folder. All input parameters must reference the same property.
1 [M] | O | File | The output parameter must reference a structured file descriptor of type Input Stream. The file descriptor's table structure has two columns: the property which was used as input parameter and the element type property.

Example:

SVN Create Root Folder
Parent topic: Tool Types for the SVN Function Package


Get SVN Property

Function:

This tool gets the value of an SVN property of an SVN resource in a working copy.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Path to the Eclipse resource in the working copy.
2 [M] | I | String | SVN property ID.
3 [M] | O | String | SVN property ID.
4 [M] | O | String | SVN property value.
Parent topic: Tool Types for the SVN Function Package


GET Repositories

Function:

This tool returns all SVN repository entries defined in the current workspace.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | O | File | A file descriptor pointing to the result file containing the returned repository entries in the workspace.

The output file descriptor has the following structure:

No | Target
1 [M] | Path to the SVN repository location.
2 [M] | Relative path to the SVN repository location (always blank for a repository location).
3 [M] | Match name identifying a SVN repository entry. The matchname returned equals REPOSITORY.
Parent topic: Tool Types for the SVN Function Package


Get Repository Content

Function:

This tool retrieves the content of an SVN controlled file.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | File name inclusively suffix.
2 [M] | I | String | Full SVN path to the repository file.
3 [M] | I | String | Last changed SVN revision.
4 [M] | I | String | SVN PEG revision (default head).
5 [M] | O | File | File content as unstructured input stream.
6 [M] | O | String | File name without file suffix.
7 [M] | O | String | File suffix.
Parent topic: Tool Types for the SVN Function Package


Get Repository Items

Function:

Gets the children of an SVN repository entry (next level).

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Path to the SVN item including the SVN repository location.
2 [M] | I | String | Relative path to the SVN entry within the repository.
3 [M] | O | File | A file descriptor pointing to the result file containing the returned children of the given SVN entry.

The output file descriptor has the following structure:

No | Target
1 [M] | Path to the child entry inclusively the SVN repository location.
2 [M] | Relative path to the SVN child entry within the SVN repository.
3 [M] | Name of the SVN child entry.
4 [M] | Author of the SVN child entry.
5 [M] | Last changed date of the SVN child entry.
6 [M] | SVN revision of the child entry.
7[M] | AWM match name to identify the type of the SVN child entry.
8 [M] | Whether the SVN child entry is locked.
Parent topic: Tool Types for the SVN Function Package


Get Working Copy Resources

Function:

This tool returns all children of a SVN working copy entry.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Eclipse path to the working copy entry for which the children should be retrieved.
2 [M] | O | File | A file descriptor pointing to the result file containing the returned children of a SVN working copy entry.

The output file descriptor should be of type InputStream and have the following structure:

No | Target
1 [M] | Eclipse resource ID of the child.
2 [M] | Match name identifying the Eclipse resource type.
Parent topic: Tool Types for the SVN Function Package


Get Working Copies

Function:

This tool retrieves all working copies derived from SVN into this Eclipse work space.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | O | File | Structured file descriptor of type input stream containing the working copy references.

The output file descriptor has the following structure:

No | Target
1 [M] | Eclipse resource ID.
2 [M] | Match name identifying a SVN repository entry.
Parent topic: Tool Types for the SVN Function Package


Lock

Function:

This tool locks a working copy entry within SVN. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to the working copy entry to be locked.
2 [M] | I | String | SVN force attribute; "steal" the lock of another user by a lock of the executing user (Boolean).
3 [M] | I | String | Lock message.
Parent topic: Tool Types for the SVN Function Package


Log

Function:

This tool provides the SVN log function to show log messages from the repository.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | Eclipse path to the working copy entry for which the log info is requested.
2 [M] | I | String | SVN PEG revision (default: head).
3 [M] | I | String | First revision number to be regarded.
4 [M] | I | String | Last revision number to be regarded or head.
5 [M] | I | String | Whether the log should stop when encountering a copy (Boolean).
6 [M] | I | String | Count limiting the number of messages.
7 [M] | I | String | Whether merged revisions should be included (Boolean).
8 [M] | O | File | Structured file of format input stream containing the log messages.

The output file descriptor has the following structure:

No | Target
1 [M] | SVN user ID.
2 [M] | Log message text.
3 [M] | Merged revisions.
4 [M] | Relative SVN repository path.
5 [M] | Relative SVN project path.
Parent topic: Tool Types for the SVN Function Package


Remove

Function:

Deletes an element in the working copy. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to working copy entry.
2[M] | I | String | Whether unversioned or modified items should be deleted too (Boolean).
Parent topic: Tool Types for the SVN Function Package


Revert

Function:

This tool implements the SVN revert command to undo local changes. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to the working copy entry to be reverted.
2 [M] | I | String | Whether the revert should be executed recursively (Boolean).
Parent topic: Tool Types for the SVN Function Package


Set SVN property

Function:

This tool sets a SVN property on a SVN resource in a working copy. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String/Mass Processing | Eclipse path to the SVN resource in the working copy.
2 [M] | I | String | SVN property ID.
3 [M] | I | String | Value to which the SVN property of the SVN resource should be set.
4 [M] | I | String | Whether the SVN property should be set recursively for the children of the SVN resource (Boolean).
Parent topic: Tool Types for the SVN Function Package


Unlock

Function:

This tool releases the lock on an SVN working copy entry. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to the working copy entry for which a lock should be released.
2 [M] | I | String | Force attribute of the SVN unlock command; used to break a lock of another user (Boolean).
Parent topic: Tool Types for the SVN Function Package


Update

Function:

This tool executes the update function on a SVN resource in the Eclipse working space. It supports mass processing.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String / Mass Processing | Eclipse path to the SVN resource to be updated.
2 [M] | I | String | Revision of the SVN resource to be updated.
3 [M] | I | String | Scope of the SVN update action (5 = Infinite, 4= Immediate, 3 = Files, 2 = Empty, 1 = Exclude, 0 = Unknown).
4 [M] | I | String | SVN force attribute (Boolean).
5 [M] | I | String | SVN ignore external attribute (Boolean).
Parent topic: Tool Types for the SVN Function Package


USS Function Package

This section provides a reference for functions and tools used in USS function package support.

  • Tool Types for the USS Function Package
Parent topic: Function Packages


Tool Types for the USS Function Package

  • USS Create Resource
    USS Create Resource tool type.
  • USS Delete Resource
    USS Delete Resource tool type.
  • USS Edit File
    USS Edit File tool type.
  • USS Get Permissions
    USS Get Permissions tool type.
  • USS Get Resources
    USS Get Resources tool type.
  • USS Rename Resource
    USS Rename Resource tool type
  • USS Set Permissions
    USS Set Permissions tool type.
  • USS Validate Resource Existing
    USS Validate Resource Existing tool type.
Parent topic: USS Function Package


USS Create Resource

Function:

This tool creates a new USS resource (directory or file).

Tool Attribute:

Attribute Type Description
Resource Type Selection Defines the resource type to be created.

Valid values are:

  • Folder
  • File
  • From Parameter

From Parameter means the resource type is defined by a tool input parameter.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | Directory in which the new resource is to be created.
2 [M] | I | String | Name of the new resource.
3 [O] | I | String | Type of the resource to be created (only relevant, if the tool attribute "Resource Type" is set to "From Parameter"). Allowed values are Folder or File.
Parent topic: Tool Types for the USS Function Package


USS Delete Resource

Function:

This tool deletes an USS resource.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | Complete USS path to the resource to be deleted.
Parent topic: Tool Types for the USS Function Package


USS Edit File

Function:

This tool edits an USS file.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | File | File Descriptor of type USS file pointing to the file to be edited.
2 [M] | I | String | Specifies whether the file should be opened read-only (true = read-only, false = editable).
Parent topic: Tool Types for the USS Function Package


USS Get Permissions

Function:

This tool gets the permissions of a USS resource.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | USS path of the resource which permissions should be returned.
2 [M] | O | String | Permission for “Owner Read” (must point to a property of type Boolean).
3 [M] | O | String | Permission for “Owner Write” (must point to a property of type Boolean).
4 [M] | O | String | Permission for “Owner Execute” (must point to a property of type Boolean).
5 [M] | O | String | Permission for “Group Read” (must point to a property of type Boolean).
6 [M] | O | String | Permission for “Group Write” (must point to a property of type Boolean).
7 [M] | O | String | Permission for “Group Execute” (must point to a property of type Boolean).
8 [M] | O | String | Permission for “Other Read” (must point to a property of type Boolean).
9 [M] | O | String | Permission for “Other Write” (must point to a property of type Boolean).
10 [M] | O | String | Permission for “Other Execute” (must point to a property of type Boolean).
Parent topic: Tool Types for the USS Function Package


USS Get Resources

Function:

This tool retrieves the children of an USS resource.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | Complete USS path to the resource for which the children should be retrieved.
2 [M] | O | File | Referencing a file descriptor which contains the attributes of the children of the given resource.

The output file descriptor should be of type InputStream and have the following structure:

No | Target ID
1 [M] | Name of the USS resource.
2 [M] | Type of the resource.
3 [M] | Linked type of the resource.
3 [M] | TRUE, if the USS resource is a directory, otherwise FALSE.
5 [M] | Complete path to the USS resource.
6 [M] | Size of the USS resource.
7 [M] | Format of the USS resource.
8 [M] | Group ID to which the USS resource belongs.
9 [M] | Owner ID to which the USS resource belongs.
10 [M] | Date of the last access to the USS resource.
11 [M] | Date of the last change to the USS resource.
12 [M] | Date when the USS resource was created.
13 [M] | Date of the last modification to the USS resource.
14 [M] | Number of links pointing to the USS resource.
15 [M] | Permissions defined for the USS resource.
16 [M] | Match Name identifying the USS resource type.

When defining the file descriptor you must make sure to define a unique delimiter used to separate the resource properties. The USS Explorer uses the delimiter "|".

Parent topic: Tool Types for the USS Function Package


USS Rename Resource

Function:

This tool renames a USS resource.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | Complete USS path to the resource to be renamed.
2 [M] | I | String | New name of the resource to be renamed.
Parent topic: Tool Types for the USS Function Package


USS Set Permissions

Function:

This tool sets the permissions to a USS resource.

Parameters:

Parameter # | I/O | Type | Description
1 [M] | I | String | USS path of the resource whose permissions are to be set.
2 [M] | I | String | Permission for “Owner Read” (must point to a property of type Boolean).
3 [M] | I | String | Permission for “Owner Write” (must point to a property of type Boolean).
4 [M] | I | String | Permission for “Owner Execute” (must point to a property of type Boolean).
5 [M] | I | String | Permission for “Group Read” (must point to a property of type Boolean).
6 [M] | I | String | Permission for “Group Write” (must point to a property of type Boolean).
7 [M] | I | String | Permission for “Group Execute” (must point to a property of type Boolean).
8 [M] | I | String | Permission for “Other Read” (must point to a property of type Boolean).
9 [M] | I | String | Permission for “Other Write” (must point to a property of type Boolean).
10 [M] | I | String | Permission for “Other Execute” (must point to a property of type Boolean).
Parent topic: Tool Types for the USS Function Package


USS Validate Resource Existing

Function:

This tool checks if a USS resource exists.

Parameters:

Parameter No | I/O | Type | Description
1 [M] | I | String | USS path of the target folder in which the resource should be looked up.
2 [M] | I | String | Name of the resource which should be checked for existence.
Parent topic: Tool Types for the USS Function Package


Extending the AWM Meta Model

The AWM meta model can be extended by using the AWM plug-in API. All available model extensions must be defined under a function package with a unique ID. Function packages, including all their functions, can be defined by extending the Eclipse extension point “com.microfocus.awm.model.extension” with an Eclipse plug-in.

Once a plug-in defining a new function package is installed, the package and its functions are available in the model editor.

The technical documentation for all extensions is contained within the shipped AWM binaries (extension point schema definition) and is available from the Eclipse Manifest Editor.

  • Missing Function Packages
  • Missing Function Package Features
Parent topic: Workflow Manager Modeling Guide


Missing Function Packages

In some situations, function packages or some of their functions cannot be resolved at run time. A model can contain references to specific function packages and/or functions but the required plug-ins defining those functions are not available or the IDs have changed.

Depending on where the model is loaded from, AWM handles this situation in the following ways:

  • Model was loaded from the Application Explorer view:

    AWM loads everything from the model that can be resolved, and ignores unresolved function package references. It depends on the kind of unresolved features and the model itself as to whether the application is still functional. For example, if a missing function package provided new icons, all elements and actions referencing those icons can still be used but their icons are missing.

    If a function package contains functions then fundamental functions like new tool types can be missing intentionally, for example, a function package intended for certain users only. A model can be designed to work without it. For example, actions containing missing tool types can have enabled conditions testing, such as for a static application property (see Master Configuration for more information) which should be set according to the function package availability.

  • Model was opened in the model editor:

    AWM gathers all IDs of missing features and displays a warning message containing these ID, see the figure below. You can click Remove Features to open the model editor with all the features removed. At this point the model is not altered, you must change the model and save to permanently remove the features.

    Alternatively, click OK, to keep all the features.
    Note: The features are no longer visible in the editor. References to those features are also invisible, for example, an action descriptor has references to an unresolved tool type.
Parent topic: Extending the AWM Meta Model
Related information
Master Configuration


Missing Function Package Features

When a model is opened and contains features of function packages which are not installed/ active, the editor will pop up a dialog in which the user can decide whether to ignore or remove those features (for more information see Missing Function Packages).

Parent topic: Extending the AWM Meta Model
Related information
Missing Function Packages


AWM API Programming and Extension Points

This section describes how you can extend the behavior and functionality of applications by using the AWM API to manipulate its standard modeling capabilities.

  • Introduction
  • API Programming
  • AWM Extension Points
Parent topic: Workflow Manager Modeling Guide


Introduction

AWM is a highly extensible framework that you can use in the following ways to customize the behavior of an application:

  • Using the AWM modeling capabilities to define the user interface and tool integration. For example, modeling AWM Properties, Element Types, Action Descriptors, Tool Descriptors, and so on.
  • Using standard AWM tool descriptors to run Eclipse or Enterprise Developer-based functions or to execute programs or scripts on supported platforms. For example, open a file in the COBOL editor, execute a REXX procedure on the mainframe, or run a Windows batch script.
  • Using the AWM plug-in API to access specific AWM functions or interfaces. For example, define a new AWM system type to provide AWM models from custom locations.
  • Extend standard modeling capabilities by implementing new function packages using the AWM plug-in API. For example, create a function package to provide new AWM modeling capabilities for a third party or home-grown software configuration management tool.

An AWM administrator can define complex workflows by using the AWM standard modeling capabilities. This needs an understanding of the AWM model and how to attach tools to AWM which is described in detail in the modeling and tool attachment chapters.

This section explains the capabilities and how to use the AWM API to provide Eclipse extension points where the AWM functionality can be extended.

The following sub topics contain tutorials explaining how to make use of the AWM plug-in functionality and how to extend an AWM extension point. The AWM extension is based on the AWM model extension point which is the most important extension point provided by AWM.

This chapter requires basic knowledge about Java programming and Eclipse plug-in development.

Parent topic: AWM API Programming and Extension Points


API Programming

  • AWM API packages
  • AWM API Usage Hints
  • AWM API Usage Guide
Parent topic: AWM API Programming and Extension Points


AWM API packages

The AWM API consists of all classes in these packages:

Package | Description
com.microfocus.awm.control | Contains basic classes for executing AWM actions, like the ActionExecutor.
com.microfocus.awm.core | Contains central helper classes (like TaurusUtility) and basic implementations of AWM interfaces.
com.microfocus.awm.model | Contains interfaces which provide access to AWM managed resources at run-time like AWM applications, elements, element lists, filters, file descriptors, actions, tools, properties and the master configuration, and so on.
com.microfocus.awm.meta.interfaces | This package provides access to the AWM modeled data like AWM action descriptors, application options, element list structures, element types, file descriptors, filter types, function packages, global actions, icons, tool descriptors, and so on.
com.microfocus.awm.meta.modelextension | This packages provides access to the AWM modeled data which is supported by extension point implementations like the definition of a function package, linked element type, linked property, tool type extensions, and so on.
com.microfocus.awm.remote | This package contains interfaces which provide access to a mainframe system connection, file attribute and file data as well as code page information.

For a detailed description of the AWM API:

  1. Open the Java program editor.
  2. Hover over a class of the API.

  3. Place the cursor into the help window, and then click Open Attached Javadoc in a Browser.

    This opens a browser window with the Java documentation of the API classes in another editor page:

    Technical Documentation
Parent topic: API Programming


AWM API Usage Hints

  • Accessing AWM from a Custom Application
  • Using the API when Implementing an AWM Extension Point
  • Using the API for the Synchronization of AWM Elements
Parent topic: API Programming


Accessing AWM from a Custom Application

The AWM API provides functions to load an AWM model file and to access all modeled features in this model. As a result, any Eclipse plug-in running outside of an AWM application can use the AWM API to get access to AWM elements and actions.

Example:

Retrieve all actions which are modelled for a certain element type in a specific AWM application and populate the context menu of elements of the corresponding type with the modelled actions in a view of a custom application. The ActionExecutor API can be used to execute a selected action from the custom application.

Parent topic: AWM API Usage Hints


Using the API when Implementing an AWM Extension Point

When implementing an AWM extension point it might be necessary to get access to the AWM model.

Example:

To be able to define an AWM tool type in a new function package it is necessary to implement the AWM IToolExecutor interface. The development of a function package is explained in more detail in AWM Extension Points and AWM Extension Point Usage Guide.

Parent topic: AWM API Usage Hints


Using the API for the Synchronization of AWM Elements

Since AWM elements are usually representations of objects stored in an external database, changes to objects can occur that are not caused or handled by a modelled AWM action. In these cases, AWM elements can get out of sync with the database and you must manually execute modeled actions to refresh corresponding element lists. To avoid this problem, AWM provides a programming interface to dynamically refresh AWM elements.

A plug-in must fulfil two conditions to be able to dynamically refresh AWM elements:

  • It must define a linked element type for every type of element it is able to refresh (see Linked Element Type).
  • It must call the method TaurusUtility#refreshLinkedElement(...) of the AWM plug-in com.microfocus.awm.core in order to refresh a particular element. The ID(s) of the supported linked element type(s) is one of the method's parameters (see JavaDoc for more information).

In addition, corresponding AWM models must use the linked element types that support being refreshed, and those element types must have an ID definition as it is proposed by the function package.

Example:

The Eclipse function package defines the linked element type "Eclipse Resource", which represents any resource of the Eclipse file system.

The function package also contains a synchronizer Java class, which listens for Eclipse workspace changes. This synchronizer calls TaurusUtility#refreshLinkedElement(...) every time a change is detected in the workspace, keeping AWM elements of the linked element type "Eclipse Resource" synchronized with the workspace.

AWM models which want to benefit from the synchronizer need to define Eclipse resources representing element types as "Eclipse Resource" linked element types, which need to have an ID definition with exactly one property, which must contain the complete Eclipse resource path.

Parent topic: AWM API Usage Hints


AWM API Usage Guide

To make use of the functionality that AWM provides, the required AWM plug-ins have to be added as dependencies to custom plug-ins.

The following tutorial describes how to create a new Eclipse plug-in which uses the AWM plug-in API.

Plug-in development is done in the Eclipse IDE within the Plug-in Development perspective.

  1. Change to the Eclipse Plug-in Development perspective, click Window > Perspective > Open Perspective > Other.

    This opens the Open Perspective dialog box.

    Eclipse Plug-in Open Perspective
  2. Click Plug-in Development, and then click OK.
    Open Perspective Plug-in Development
  3. To create a new Eclipse plug-in, click File > New > Plug-in Project.
    File New Plug-in Project

    This opens the New Plug-in Project dialog.

  4. Type a Java project name in the Project name field.
    Create a new plug-in project
  5. Click Next.
  6. Change the fields as required, and then click Finish.
    Enter the data required to generate the plug-in

    This creates an Eclipse project for the newly-created plug-in in the Project Explorer:
    New AWM Development Project in the Project Explorer

    The Eclipse plug-in manifest overview is opened in the editor window:
    Eclipse manifest editor for the new Eclipse plug-in

    The Eclipse plug-in manifest editor manages and edits all the meta information of an Eclipse plug-in.

  7. Click the Dependencies tab in the main editor to add the AWM com.microfocus.awm plug-in as a dependency of your plug-in. This enables you to use the AWM API.
  8. In the Required Plug-ins pane, click Add.

  9. Type com.microfocus in the Select a Plug-in field, and click com.microfocus.awm from the Matching items list.
    Plug-in Selection
  10. Click OK.

    The AWM core plug-in, including all of its required dependencies, are added as dependencies to the plug-in so that you can make use of the public classes and methods provided by the AWM API packages.

  11. Click File > Save.

    After saving the changes the Java classes can import classes from AWM packages which are part of the AWM API.

Note: Hovering over a method or class from the imported AWM Java packages displays the API documentation for the class or method.
Parent topic: API Programming


AWM Extension Points

You can use AWM extension points to either add new functionality into AWM or to customize the behavior of AWM.

  • AWM Model Extension Point
  • System Provider Extension Point
  • Initializer Extension Point
  • Keyword Parser Extension Point
  • Conversion Rule Extension Point
  • Global Editor Action Extension Point
  • Error Feedback Extension Point
  • Credentials Provider Extension Point
  • AWM Extension Point Usage Guide
Parent topic: AWM API Programming and Extension Points


AWM Model Extension Point

Extension point: com.microfocus.awm.model.extension

This extension point provides the ability to extend the AWM modeling capabilities by defining new function packages, tools, linked element types and properties. You can add a function package to any AWM model using the model editor. How to extend this extension point is described in AWM Extension Point Usage Guide.

Example:

  • Defining a set of tools to access a DB2 database.
  • Defining a set of tools to integrate a custom Eclipse plug-in into AWM.
  • Defining a set of linked properties for local operating system resources.
Parent topic: AWM Extension Points


System Provider Extension Point

Extension point: com.microfocus.awm.systemprovider

This extension point can be used to contribute AWM systems and applications to the Application Explorer view.

Example:

Add an AWM system to the Application Explorer view with application entries which are described in a custom database.

Parent topic: AWM Extension Points


Initializer Extension Point

Extension point: com.microfocus.awm.preinitializer

The initializer extension is called before the AWM Core plug-in.

The extension can be used to start or initialize plug-ins or functions before AWM starts.

Example:

A plug-in contributes a new AWM system type (using extension point com.microfocus.awm.systemprovider), but must be initialized before AWM starts restoring cached AWM systems.

Parent topic: AWM Extension Points


Keyword Parser Extension Point

Extension point: com.microfocus.awm.keywordparser

This extension point allows adding source parsers that implement the ITaurusKeywordParser interface.

This extension point provides the possibility to implement features depending on certain keywords found in an edited file.

Example:

This extension point could be defined so that the implementation gets control when the word COPY is found in a COBOL program. The implementation could then try to open the COBOL copybook named by the word following the COPY statement.

If you use this extension point the AWM model administrator must define a "Selection Property Mapping" for a global editor action as described in Global Action is an Editor Action.

Parent topic: AWM Extension Points


Conversion Rule Extension Point

Extension point: com.microfocus.awm.metamodel.conversionRule

This extension point enables you to add conversion rules to AWM models that are meant to support the migration of AWM model definitions from an outdated definition format.

Parent topic: AWM Extension Points


Global Editor Action Extension Point

Extension point: com.microfocus.awm.ui.globalactions.editors

This extension point was introduced for editors which do not implement the abstract class org.eclipse.ui.AbstractTextEditor and enables the registration of other editors.

By extending this extension point, global editor actions defined in the corresponding AWM model can be added to this editor's context menu.

Parent topic: AWM Extension Points


Error Feedback Extension Point

Extension point: com.microfocus.awm.errorfeedback.customaction

This extension point enables you to overriding the default double-click action in the AWM Error Feedback view.

Example:

Implementing a specific behavior (for example, locking or check-out) when opening the corresponding file referenced by the error entry.

Parent topic: AWM Extension Points


Credentials Provider Extension Point

Extension point: com.microfocus.zexplorer.zserver.credentialsprovider

This extension point enables you to provide the credentials to connect to z/OS.

Example:

An implementation of this extension point can cause the standard "Enter Password" dialog to be bypassed by providing the login credentials for the connection. A use case is that the login credentials are for example provided by an external login card reader so that there is no need for a password dialog. Another use case could be that there is a central login outside Eclipse for all user applications which has to be used in Eclipse when connecting to a remote system without an additional password request.

Parent topic: AWM Extension Points


AWM Extension Point Usage Guide

The implementation and testing of a new AWM extension is explained in the following topics using the extension point com.microfocus.awm.model.extension by defining a new function package.

  • Describing an AWM Extension
  • Debugging an AWM Extension Point Extension
Parent topic: AWM Extension Points


Describing an AWM Extension

Create an Eclipse plug-in project as described in AWM API Usage Guide, and then perform the following steps:

  1. In the Extensions tab of the manifest editor add the com.microfocus.awm.model.extension extension.
  2. In the All Extensions pane, click Add.
    All Extensions

    This opens the New Extension dialog.

  3. In the Extension Points list, click com.microfocus.awm.model.extension.
    Extension Point Selection
  4. Click Finish.

    This adds the extension to the All Extensions list.

  5. An Eclipse extension has to adhere to the rules that the extension point defines.

    It is the task of the extension point implementer to define the structure of the AWM function package extension within the manifest editor. In the All Extension list, click com.microfocus.awm.model.extension.

    This displays the Extension Details pane.

  6. Click Show extension point description.
    Define extensions for this plug-in

    This opens another editor window containing a comprehensive description of the AWM Model Extension.

  7. You must define at least one ID and a label for the new function package. The ID attribute value must be unique for all components within the function package. The label attribute defines the name of the function package in the AWM model editor.

    In the Extensions tab, expand com.microfocus.awm.model.extension.

  8. Click label (functionPackage).

    This displays the Extension Element Details pane.

    Note: Mandatory properties are marked with an asterisk.
  9. In the id field, type an id. For example, com.microfocus.test.awmextension.simpleFunctionPackage.
  10. In the label field, type a label. For example, Simple Function Package.
  11. Click File > Save.

    When saving the manifest editor content, the information from Extension Element Details pane is added to the left All Extensions pane:

  • Describing Function Package Tools
  • Implementing a Defined Function Package Tool
  • Describing Function Package Linked Properties
Parent topic: AWM Extension Point Usage Guide


Describing Function Package Tools

  1. In the Extensions tab, right-click on the function package entry.

    This opens the function package context window.

  2. To add a new tool to the function package, click New > toolType.
    Function Package Tool Description

    This displays the Extension Element Details pane.

  3. Define an ID for the tool type. The class attribute points to the Java class which implements the IToolExecutor interface of the AWM model extension point. In the Extension Element Details pane, click class.

    This opens the New Java Class dialog. Complete the dialog as required:

  4. Click Finish.

    This opens a template Java class for the tool. You need to define the Java class to implement the tool.

  5. In the label field, type a label name that will be displayed in the AWM model editor when selecting a tool from the function package.
  6. Click File > Save.
  7. You must add an attribute to the newly defined toolType. An attribute is shown in the Eclipse Property view when the AWM administrator defines a new instance of the toolType. An attribute is a tool parameter which is defined during modeling and not at run time. In the All Extensions pane, right-click the new toolType under the function package.

    This opens the toolType context menu.

  8. Click New > attribute.
    Extensions New attribute
  9. This displays the properties for the attribute in the Extension Element Details pane, set the properties as required. See the example below:
    Extensions new attribute properties
Parent topic: Describing an AWM Extension


Implementing a Defined Function Package Tool

After the definition of this extension a Java class implementing the IToolExecutor interface is created in the plug-in project. Edit this Java class to implement the functionality of your tool.

Find below a sample implementation of the Simple Tool which determines the value of the sole tool attribute and lists the values of all modeled tool parameters:

public class SimpleToolExecutor implements IToolExecutor {

    public SimpleToolExecutor() {
            }

    @Override
    public ToolExecutionStatus execTool(IExecutionContext pContext,
            ToolDescriptor pToolDescriptor, String pAffectedResName,
            IProgressMonitor pMon) throws TaurusToolException {
        // Get a modeled attribute value
        Object attributeValue = pToolDescriptor
                .getDynamicValue("update-allowed.attr");
        if (attributeValue instanceof Boolean) {
            Boolean updateAllowed = (Boolean) attributeValue;
            if (updateAllowed)
                System.out.println("Update is allowed.");
            else
                System.out.println("Update is not allowed.");

        }
        // Print every parameter value into console
        for (RToolInParameter inputParameter : pToolDescriptor.getInputParm()) {
            String parameterValue = ActionExecutor.getParameterValue(
                    inputParameter, pContext);
            int sequenceNumber = inputParameter.getSeqNo();
            System.out.println("Input parameter #" + sequenceNumber + ": "
                    + parameterValue);
        }
        // Return OK execution status
        int returnCode = 0;
        return new ToolExecutionStatus(pToolDescriptor.getID(), returnCode);

    }

    @Override
    public IToolOutputReader getOutputReader() {
        // Do nothing
        return null;
    }

    @Override
    public List<String> readParmFile(ISystemImage pImg, String pParmFilePath,
            IProgressMonitor pMon) throws IOException {
        // Do nothing
        return null;
    }

}

The implementation of the new Simple Function Package tool is now complete and will be tested later on.

Parent topic: Describing an AWM Extension


Describing Function Package Linked Properties

The function package can provide the AWM model with Linked Properties.

You can declare your own property provider via the extension point attribute propertyProvider:

  1. In the All Extensions pane, right-click functionPackage.
  2. Click New > propertyProvider.
    Extensions propertyProvider

    This adds a propertyProvider to the functionPackage in the All Extensions list.

By doing this the function package can extend the model by function package own properties. The properties which are supplied by the function package have to be defined under the extension point attribute propertyProvider of the function package:

  1. Right-click propertyProvider.
  2. Click New > property.
    Extensions propertyProvider property

These properties are called linked properties. The linked properties are shown in the model editor under the function package in the New Child dialog of the Properties category. The following image shows the linked property selection for the standard Eclipse function package:

At run time it is the responsibility of the function package's property provider to provide the value of a linked property.

Parent topic: Describing an AWM Extension


Debugging an AWM Extension Point Extension

To be able to test a plug-in within Eclipse start another Eclipse instance. This can be done by defining a new Run or Debug configuration.

Micro Focus recommends that you define a Debug configuration for two reasons:

  • Breakpoints set in the Eclipse development environment are effective.
  • Changes made in the Eclipse development environment are directly applied. In most cases there is no need to restart the Debug Eclipse instance after a code change in the Eclipse development environment.
  1. Click Run > Debug Configurations. Alternatively, click [image], and then Debug Configurations.

    This opens the Debug Configurations dialog box.

    Debug Configurations
  2. Double-click Eclipse Application. Alternatively, click Eclipse Application, and then New launch configuration.

    This opens a new debug configuration in the right pane.

  3. Type the name of your debug configuration in the Name field.
    Debug Configuration Naming
  4. Click Debug.

    This starts a new instance of Eclipse which contains the developed plug-in code for testing.

  5. In the new Eclipse instance, switch to the Team Developer perspective. Click Window > Perspective > Open Perspective > Other.
  6. Click Team Developer.
  7. Click OK.
  8. Open an AWM model with the AWM model editor.
  9. Expand platform > Document Root.
  10. Right-click AWM Model.
  11. Click New Child > Function Packages.

    This adds the Function Packages as a node to the model tree.

  12. Right-click Function Packages.
  13. Click New Child > Simple Function Package.

    This adds your new function package Simple Function Package to the model tree.

  14. After you have added the Simple Function Package to the model it is possible to use the implemented functions, such as tools, linked properties, and so forth. Right-click Function Packages.
  15. Click New Sibling > Tool Descriptors.

    This adds the Tool Descriptors node to the model tree.

  16. Right-click Tool Descriptors.
  17. Click New Child > Simple Function Package > Simple Tool.

    This opens the New Object dialog box.

  18. Type a unique ID in the New ID field.
  19. In the Property view you can see that the tool attribute Update allowed was added to the tool attributes under the category Dynamic with the default value false.
    Property view
  20. For test purposes model an action which uses this new tool and make sure that its action can be executed at run time.
  21. Loading this AWM model and executing the action displays the following lines in the Console view of your development Eclipse instance:
    Update is not allowed.
Input parameter #1: First Element
Input parameter #2: 100
    Note: The output assumes that two input parameters, name and size, were modeled for the Simple Tool.
Parent topic: AWM Extension Point Usage Guide


Example AWM: MVS Projects Sample Application

Note: This example can only be used if one of EDz or EDc is installed.

This topic provides a description of an example AWM model called MVS Projects Sample Application. This example demonstrates the modeling procedure and programming of the tool adapter.

The example is shipped with the AWM model MVSCONF and all REXX procedures (all names starting with TAUPD or TAUZC), and is also included as an entry in the master configuration file. The example is part of the z/Server installation. Using this example in a production environment is not recommended due to the limited functionality.

Most of the model definitions to be carried out are described in the illustrations and tables in subsequent topics.

  • Concept
  • Editing the AWM Sample Model
  • REXX Procedures
  • Editing the Master Configuration
Parent topic: Workflow Manager Modeling Guide
Related information
Use Case-Based Modeling Examples


Concept

Before the implementation and modeling can be started, you must design a concept for how an MVS Projects Application should be connected to Eclipse using the AWM. Consider the following questions:

  1. What structure should the Tree view have (container element types)?
    • How deep should the hierarchy go?
    • What properties are relevant for the application per container element type?
  2. What other element types are there?
    • How fine should the difference between the element types be?
    • What properties are relevant for the application per element type?
    • What properties make an element unique (ID definition)?
  3. How does a user want to search for elements (filter type)?
  4. How should elements be shown in the Element Table view (element list structure)?
    • Which properties are to be defined as columns? The performance of the available tools for the determination of the table contents must be considered here.
  5. What actions are needed (action, tool descriptor)?

These questions have been answered and implemented as follows for the example AWM model:

  1. The first level of the tree view should show a fixed entry “MVS Projects”. It should be possible to add entries, for example, Enterprise Development COBOL Project(s), if required.

    The second level should contain entries for mainframe data set filters, which a user should be able to define in a dialog. It should be possible to define a filter name, filter criteria and to associate default syslib data sets for COBOL, PL/I and maclib data sets for Assembler.

    The third level should show the data sets retrieved based on the filter criteria with supported properties like volume, organization, record format, record length, block size, creation date, last used date.

    The fourth and last level should display the member list for PO data sets. Member properties like creation date, change date, change user, version, modification level and member size should be supported. The following picture shows the expected result of the modeled tree view.

    Tree View Layout
  2. You can expect different properties and actions depending on the data set organization. Different element types have been defined for each supported data set organization; PO, PS, and DS migrated.
  3. What identifies an element? The static entry "MVS Projects" is identified by its name, a defined data set filter is identified by its filter criterion, a data set is identified by its name, and a PO member is uniquely identified through the data set name and its member name.
  4. The user should be able to use generic symbols (* %) when he searches for data sets or member names.
  5. The setup of the element list structure for PO members should contain columns like the member name, date created, date and time modified, change user, file suffix, and member size whereas a data set list should contain columns like the data set name, type, organization, record format record length, block size, default suffix and others. The following picture shows the expected result of the modeled table entries.
    Table Result

    Table Result Member
  6. The following actions should be supported:
    • In the static entry "MVS Projects" you need an action to insert a data set filter and an action to show the next level of the tree view, the defined filters.
    • In a defined filter you need actions to update the filter properties, delete a filter and to show the data sets either in the tree or table view.
    • In a PO or PS data set, you require actions to rename/delete and to copy/paste a data set.
    • In the PO data set you need actions to insert a PO member, to execute a text search within members and to show the contained members either in the tree or table view.
    • On the PO member level you need actions to edit, browse, delete, rename and duplicate a member. In addition you want to support remote syntax check (a compile on the mainframe with error feedback) and would like to manage member specific syslib data sets.

      In addition, you require actions to copy/paste PO members.

  7. It should be possible to manage data set filters not only in the tree but in the filter. The execution of a data set filter defined in the filter view should create a member list in the table view with the same structure as defined above.
  8. The result of a PO data set text search should be displayed in a tree table format including entries with the member lines where a text was found. It is necessary to define an additional element for this member record which is identified by data set name, member name and member line number. The following picture shows the expected result of the modeled tree table entries.
    Search Result
Parent topic: Example AWM: MVS Projects Sample Application


Editing the AWM Sample Model

To understand or modify this example, the AWM model MVSCONF can be opened with the AWM model editor, which will show the complete modeled example. This sample model is part of the z/Server installation data sets and is contained in the data set which ends with the last qualifier XML.

  • Application Options
  • Properties
  • File Descriptors
  • Icons
  • Actions and Tools
  • Element Types
  • Filter Type
  • Element list Structure
Parent topic: Example AWM: MVS Projects Sample Application
Related information
Creating an AWM Model


Application Options

For all the following object types and relationships, the object for the application options is created with the New Child or New Sibling command in the editor context menu. As the availability of the command depends on the selection, the third level of the Tree view in the editor must first be selected (AWM Model). To create a new object, click New Child > Application Options, whose attributes can be modeled in the Properties view. See Creating an AWM Model and Application Options for more information.

Check the following attribute values and adapt them, as required:

Attribute | Value | Description
Default Generic Symbol | * | The standard generic icon is used as a default for generic input fields.
Generic Symbols | *,% | All permitted generic symbols, including Default Generic Symbol.
Version | 3.0 | The version of the AWM model. In principle, the value is arbitrary. A new value must be set for every release of a changed AWM model so that the changes can be activated at run time.

The table indicates only those attributes of the application option that have to be modified for the example model.

You must define a SYSLIB attribute as a child entry of the Application Options, that references the property which contains the correct syslib data sets at run time. This entry is used when editing a COBOL or PL/I file to support syntax checking.

Note: The attribute "Root Containers Action" must be set later because it refers to an action descriptor, which is not yet modeled.

The final modeled application options should look like this:

MVS Project Sample Application Options
Parent topic: Editing the AWM Sample Model
Related information
Application Options


Properties

As many object types and relationships refer to properties, it is good practice to define them early. See Property for more information.

All properties shown below must be defined for the example AWM model:

All values that start with “MVS_PROP_” are IDs of the respective Properties.

The table contains a few properties whose attributes need specific values.

Property | Attribute | Description
MVS_PROP_ELE_MemberName | Value max length = 8 Value min length = 1 | The member name. This cannot contain more than 8 characters.
MVS_PROP_ELE_ChangeDate | Date Format = dd/MM/yyyy | All date properties have this date format.
MVS_PROP_ELE_SearchLine | Special Property = Marker Line Number | Line numbers used to set markers in the editor.
MVS_PROP_ELE_Suffix | Special Property = Element Suffix | File extension.
MVS_PROP_ELE_ElementType | Special Property = ElementType | Creates the connection between the element and the element type at run time via the match name.

Micro Focus recommend you define a Label for each property, so that the properties are displayed in a readable manner in the Property view. The label "Data set name", for example, is suitable for MVS_PROP_ELE_DSName, and "Member name" for MVS_PROP_ELE_MemberName, and so on.

Parent topic: Editing the AWM Sample Model
Related information
Property


File Descriptors

Tools can output files that are to be interpreted as value tables. The contents of these value tables must be described in the AWM model. See File Descriptor in the Data Model Details chapter, for more information.

Files of this kind are returned to the following places in the example AWM model shown below:

  • Expansion of tree elements (MVS_FD_ELE_MVS_DataSetList, MVS_FD_ELE_Memberlist, MVS_FD_ELE_ViewFilter, MVS_FD_ELE_ViewStaticEntry)
  • Return of element lists in the table view ((MVS_FD_ELE_MVS_DataSetList, MVS_FD_ELE_Memberlist, MVS_FD_MemberSearchresult)

The relationships of the file descriptors to properties are shown in the figure below:

MVS PRoject Sample Application File Descriptors

The table below describes a few important file descriptor attributes:

File Descriptor | Attribute | Description
MVS_FD_ELE_MVS_DataSetList MVS_FD_ELE_Memberlist | Type = Input Stream Structure = Table Delimiter = /%/$/ | The data set and member list are provided by MVS function package tools as input streams. The values are separated by /%/$/
MVS_FD_MVS_SequentialFile | Type = MVS_Seq Structure = Unstructured Name Physical = &MVS_PROP_ELE_DSName. | A file descriptor used to edit a sequential file. The "Name Physical" references the property which contains the relevant data set name.
MVS_FD_MVS_Member | Type = MVS_PO_Member Structure = Unstructured Name Physical = &MVS_PROP_ELE_DSName.(&MVS_PROP_ELE_MemberName.) | A file descriptor used to edit a PO member. The "Name Physical" references the property which contains the relevant data set name including the member name.
Parent topic: Editing the AWM Sample Model
Related information
File Descriptor


Icons

In order to be able to assign actions and elements later on in the AWM model, you must first define the icons. See Icon in the Data Model Details chapter, for more information.

The following icons are used within the sample model:

MVS PRoject Sample Application Icons
Parent topic: Editing the AWM Sample Model
Related information
Icon


Actions and Tools

You must first create the tool descriptors, then the action descriptors, and associate the tool descriptors to the action descriptors. See Action Descriptor and Tool Descriptor in the Data Model Details chapter, for more information.

The following actions are used in the example AWM model:

Action Descriptor ID | Description
MVS_ ACT_CONT_AssociateSyslib | Opens a dialog box to associate syslib data sets to a PO member.
MVS_ACT_CONT_CopyMVSResource | Copy a MVS resource to the clipboard.
MVS_ ACT_CONT_CreateDatasetFilter | Opens a dialog box to prompt for new data set filter attributes and calls a REXX procedure to store the filter information in a sequential file on the mainframe. This action is associated to the context menu of the root entry "MVS Projects".
MVS_ACT_CONT_CreateRootentries | Creates the static root entry "MVS Projects" which is provided by an AWM function package tool.
MVS_ACT_CONT_DeleteDatasetFilter | Calls a REXX procedure to delete a filter definition in a sequential file on the mainframe.
MVS_ACT_CONT_DeleteMVSResource | Opens a dialog to confirm the delete requests and deletes a MVS data set or member of a PO data set.
MVS_ACT_CONT_DuplicateMember | Opens a dialog box to ask for a new member name and calls a REXX procedure which copies the member in the PO data set.
MVS_ ACT_CONT_FilterList | Creates an element list with the defined filters using a REXX procedure. This action is associated to the static entry "MVS Projects" and called when this entry is expanded in the tree view.
MVS_ACT_CONT_InsertMember | Opens a dialog to ask for a new member name and calls a REXX procedure which creates the member in the PO data set.
MVS_ACT_CONT_PasteMVSResource | Paste a MVS resource from the clipboard.
MVS_ACT_CONT_RecallDataset | Calls a REXX procedure which recalls a migrated data set and refreshes the data set list.
MVS_ACT_CONT_RefreshDataSet | Refreshes properties of a MVS PO or PS data set. This action is assigned to the PO or PS element type as a Get All Properties action.
MVS_ACT_CONT_RefreshMember | Refreshes properties of an PO member. This action is assigned to the PO member element type as a Get All Properties action.
MVS_ACT_ CONT_RemoteBrowse | Opens a PO member in the editor (read-only access).
MVS_ACT_ CONT_RemoteBrowsesSeq | Opens a sequential data set in the editor (read-only access).
MVS_ACT_ CONT_RemoteEdit | Opens a PO member in the editor and permits changes.
MVS_ACT_ CONT_RemoteEdit_SEQ | Opens a sequential data set in the editor and permits changes.
MVS_ACT_CONT_RemoteJOBSubmit | Submits a JCL member to JES using a MVS function package tool.
MVS_ACT_CONT_RemoteSyntaxCheck | Opens a dialog box to ask for additional compile options and calls a REXX procedure which compiles the source (supported for COBOL, PL/I, Assembler and C). Compiler messages are shown in the Error Feedback view, which is provided by an AWM function packages tool.
MVS_ACT_CONT_RenameDataSet | Opens a dialog box asking for a new data set name and calls the MVS function package tool to rename a MVS data set.
MVS_ACT_CONT_RenameMember | Opens a dialog box asking for a new member name and calls the MVS function package tool to rename a member in a PO data set.
MVS_ACT_CONT_UpdateDatasetFilter | Opens a dialog box prompting for new data set filter attributes and calls a REXX procedure to store the filter information in a sequential file on the mainframe.
MVS_ACT_EDITOR_SubmitJCLFromEditor | Calls the MVS function package tool to submit the editor content to JES.
MVS_ACT_EDIT_ReparseSourceWithRefresh | Is associated as a global action to the PL/I and COBOL editor and refreshes the COBOL copybooks or PL/I includes if selected from the editor's context menu. A Micro Focus Edit Tool supports this action.
MVS_ACT_ELIST_DatasetList | Is associated to a defined filter in the tree or filter view and creates a data set list either as entries in the tree view or in the table view. The action is provided by an MVS function package tool.
MVS_ACT_ELIST_FilterMemberList | Calls the MVS function package tool to create a filtered member list. The action is used as default action of a member filter type.
MVS_ACT_ELIST_Memberlist | Is associated to a PO data set and creates a member list either as entries in the tree view or in the table view. The action is provided by an MVS function package tool.
MVS_ACT_ELIST_SearchMembers | Opens a dialog box prompting for text search options and calls a REXX procedure which performs a string search on the members of a PO data set.

The following tool descriptors have to be defined to support the actions defined above.

Tools required from the AWM function package:

MVS Project Sample Application Tools

Tools required from the MVS function package:

MVS Project Sample Application Tools

Tools required from the Micro Focus Editor function package:

MVS Project Sample Application Tools

Tools required from the ISPF function package. The ISPF tools are all of type "Execute ISPF Command". The following figure does not show all modeled tool input and output parameters.

MVS Project Sample Application Tools

The figure below shows how the action descriptors must be modeled. The figure shows the relationship to tools only if more than one tool descriptor is used within one action.

MVS Project Sample Application Actions
Parent topic: Editing the AWM Sample Model
Related information
Action Descriptor
Tool Descriptor


Element Types

For details on how to model element types, see Data Model Details - Element Type.

For the AWM sample, the following element types must be modeled, as discussed in the topic Concept.

  • Static Entry "MVS Projects"
  • Data Set Filter Definitions
  • Partitioned Data Sets
  • Sequential Data Sets
  • Migrated Data Sets
  • PO Members
  • Search Result (Member)
  • Search Result (Line)
Parent topic: Editing the AWM Sample Model
Related information
Concept
Element Type


Static Entry "MVS Projects"

This element type has two properties and one action in the context menu, which is used to create a filter definition. The following image shows how to model this element type:

MVS Static View Entry

You need an ID definition to describe the property which uniquely identifies an element of this type.

The get children action has to be associated to be able to expand the static element in the tree view.

In addition, a project icon has been associated.

The match name MVSPROJECT must match the name used in the tool definition, which creates this static element:

At run time, this modeled static element is display in the tree view:

Because this is the first level element when expanding the application entry "MVS Projects Sample Application", the root containers action has to be associated in the application options section of the model editor:

Parent topic: Element Types


Data Set Filter Definitions

This element type has seven properties and three actions in the context menu. The following figure shows how to model this element type:

MVS Data Set Filter

You need an ID definition to describe the property which uniquely identifies an element of this type.

The get children action has to be associated to be able to expand a filter definition in the tree view with the data set list. The same action is used in the context menu to show this data set list in the table view.

In addition, a filter icon has been associated with the data set filter.

The match name DATASETFILTER must match the name returned by the tools which are creating filter elements, for example, the REXX procedure TAUPDFIL.

At run time, this modeled data set filter definition is displayed in the tree view, similar to the following:

MVS Project Sample Application Dataset Filter

MVS Project Sample Application Dataset Filter

When associating the properties to the element type, a few more important attributes have to be specified in the model editor. Compare the following definition with the result at run time:

If the Category is set to Filter then it creates this category in the properties view at run time.

If the Sort Direction is set to Ascending then it displays the filter definitions in the tree view sorted by the filter label.

The filter label is displayed in the tree view because the Tree View Label field has been set to true.

Parent topic: Element Types


Partitioned Data Sets

The following image shows how to model this element type:

Partitioned Data Set

You need an ID definition to describe the property which uniquely identifies an element of this type.

The get children action has to be associated to be able to expand a data set in the tree view with the member list. The same action is used in the context menu to show this member list in the table view.

The icon is dynamically associated with the icon in the MVS Explorer. An explicit icon definition is not necessary.

The match name PO must match the name returned by the MVS function package tool which returns the data sets. The data set organization property of this tool is used as element type match name. By definition, the third field of this tool is the returned data set list containing the data set organization, which has been mapped to the element type's match name property as shown below:

MVS Project Sample Application PO Dataset Type

At run time these modeled data sets are displayed in the tree view like in the figure below:

MVS Project Sample Application PO Dataset Type
Parent topic: Element Types


Sequential Data Sets

The following figure shows how to model this element type:

Sequential Data Set

You need an ID definition to describe the property which uniquely identifies an element of this type. The icon is derived from the icon used in the MVS Explorer. An explicit icon definition is not necessary. The match name PS must match the name returned by the MVS function package tool which returns the data sets.

This element type has a text decoration which adds the suffix to be used for editing to the data set name as a label decoration separated by a period.

MVS Project Sample Application PS Data St Type

The edit and browse actions are only executable via the context menu, if the modeled conditions are true. At run time, these modeled data sets are displayed in the tree view similar to the figure below:

MVS Project Sample Application PS Data Set Type
Parent topic: Element Types


Migrated Data Sets

This element type is modeled to support migrated z/OS data sets.

The icon is derived from the MVS Explorer and does not need to be explicitly modeled.

The element type has two actions modelled. The first action recalls the migrated data set. The second action sends a HDELETE command to delete the migrated data.

MVS Migrated Data Sets
Parent topic: Element Types


PO Members

The following figure shows how to model this element type:

MVS PO Member

You need an ID definition to describe the properties which uniquely identify an element of this type.

A "Get All Properties" action has been associated, which ensures that the member properties are correct before any other action is executed. In addition, this action associates the default syslib data sets to the member and ensures that the editor supports syntax checking for COBOL and PL/I programs.

The icon is derived from the MVS Explorer and does not need not to be explicitly modeled.

A text decoration is modelled so that the element suffix is added as a label decoration to the member separated by a period.

MVS Project Sample Application PO Member

The match name MVSMEMBER must match the name returned by the MVS function package tool which returns the member list.

Some actions are only executable via the context menu, if the modeled conditions are true. For example, the action which submits a batch job is only visible in the context menu if the member suffix is "jcl".

At run time, these modeled members are displayed in the tree view like in the figure below:

MVS Project Sample Application PO Member
Parent topic: Element Types


Search Result (Member)

This element type is used to model a PO member in the search result in which the text searched for was found.

The following figure shows how to model this element type:

MVS Search Member

You need an ID definition to describe the properties which uniquely identify an element of this type.

The icon is derived from the icon used in the MVS Explorer for a PO data set member. All actions have modeled enabled or visible conditions that have rules applied:

The match name SEARCHMEM must match the name returned by the REXX procedure TAUTOSRC which returns the result from an ISPF search utility. If the Search action on a partitioned data set is executed at run time, the member records are displayed as a tree table, see the figure below:

MVS Project Sample Application Search Member Type
Parent topic: Element Types


Search Result (Line)

This element type is used to model a line in the search result where the text searched for was found.

The following figure shows how to model this element type:

MVS Search Line

You need an ID definition to describe the properties which uniquely identify an element of this type. In addition, an icon has been associated. The match name SEARCHLINE must match the name returned by the REXX procedure TAUTOSRC which returns the result from an ISPF search utility. If the Search action on a partitioned data set is executed at run time, the member records are displayed as a tree table, as in the figure below:

MVS Project Sample Application Search Line
Parent topic: Element Types


Filter Type

There are two filter types defined in the AWM model. The first filter type is used to define a data set filter together with the action that can return a data set list. It is the same action used in the tree view to expand a data set filter definition. The second filter type is used to define a member filter together with the action that can return a member list of a PO data set.

For details of how to define a filter type, see Filter Type in the Data Model Details chapter, for more information.

The following figure shows how the data set filter type is modeled:

MVS Data Set Filter

The following image shows how the member filter type is modeled:

MVS Project Sample Application Member Filter Type

At run time, the filter dialog can be called from the Filter Definitions view. You can select between the two filter type definitions when you create a new filter.

MVS Project Sample Application Filter View

The Filter Dialog box for MVS data sets is displayed as follows:

MVS Project Sample Application Filter View

The Filter Dialog box for a PO members is displayed as follows:

MVS Project Sample Application Filter View
Parent topic: Editing the AWM Sample Model
Related information
Filter Type


Element list Structure

For details on how to model an element list structure, see Element List Structure in the Data Model Details chapter, for more information.

The AWM sample model contains three element list structures. The first list structure is used to display data sets, the second to display members of a MVS partitioned data set in the Table Results view. The third list structure is used to display the result of the search tool as a tree table in the Table Results view.

The following figure shows how to model an element list structure:

At run time, a data set list is displayed in the table as shown in the following figure:

MVS Project Sample Application Element List Structures
Parent topic: Editing the AWM Sample Model
Related information
Element List Structure


REXX Procedures

The REXX procedures of the AWM sample model are a part of the delivered mainframe components installed with the z/Server. The names of these procedures all start with the prefix TAU. You will find the procedures in the z/Server dataset which ends with the last qualifier EXEC. Only REXX procedures starting with TAUPD are specific to this AWM sample; others which start with TAUZC or TAUTO are general REXX procedures which are used in other AWM context as well.

The REXX procedures can be executed without any adaptation. If any special rules exist for the allocation of temporary user files, however, the REXX procedure TAUPDXA1 must be modified.

The AWM sample also provides an action which supports a remote syntax check. The corresponding REXX procedure TAUPDRSC calls other subroutines which support the compilation of programs. These subroutines have to be customized for the required compiler load libraries. For more details of how to customize TAUTOXCC, TAUTOXCP and TAUTOXCA see ISPF Exits.

  • Remote Syntax Check (REXX TAUPDRSC)
  • Managing Data Set Filters (REXX TAUPDFIL)
  • Recall Data Set (REXX TAUPDDSI)
Parent topic: Example AWM: MVS Projects Sample Application
Related information
ISPF Exits


Remote Syntax Check (REXX TAUPDRSC)

The TAUPDRSC procedure executes a remote syntax check. It also creates an error feedback file which contains the compiler messages. This output file is passed to the AWM error feedback tool which displays the compiler messages in the Error Feedback view.

MVS Project Sample Application Remote Syntax Check

The parameter separator for input is a colon (:).

The following code snippet shows how this is processed for COBOL in REXX:

Parent topic: REXX Procedures


Managing Data Set Filters (REXX TAUPDFIL)

The TAUPDFIL procedure is used to manage the data set filter definitions which a user can create when running the sample application.

All data set filter information which a user defines is stored in a user-specific sequential data set which is allocated in TAUPDXA1, for example:

The REXX procedure is called from the sample model a number of times; it is used to create, update, and delete filter definitions as well as retrieve all the defined filter definitions.

MVS Project Sample Application TAUPDFIL

The input parameters are modeled using "%,%" as a parameter separator.

The REXX procedure must use this value to parse the input parameters. Here is an extract of TAUPDFIL:

Extract of TAUPDFIL

If TAUPDFIL is called with the first parameter GETLIST to retrieve the complete list of filter definitions, it is sufficient to pass the data set name of the sequential data set back to AWM. This corresponds to the modeled file output parameter.

The modeled file descriptor describes the structure of this file with the separator "%,%":

MVS Project Sample Application TAUPDFIL Output Parm

Below is a code snippet which shows how a file record is created:

The file content looks similar to the following sample:

Parent topic: REXX Procedures


Recall Data Set (REXX TAUPDDSI)

The REXX procedure TAUPDDSI is used to recall a migrated MVS data set. The REXX uses the TSO command DSINFO to recall the data set. The only input parameter of the tool is the name of the MVS data set to be recalled.

The tool definition in the model is as follows:

MVS Project Sample Application TAUPDDSI

Parent topic: REXX Procedures


Editing the Master Configuration

In order to be able to test the AWM sample, the application must be entered into the master configuration file. See Master configuration for more information. By default, the master configuration file contains the following content:

        *
        * MVS PROJECTS EXAMPLE APPLICATION
        *
        User:
        * application name
        Appl: MVS Projects Sample Application
        * location of the application configuration file
        Conf: mvs:'hlq.XML(MVSCONF)'
        * application version number
        Version: 3.0
        * process information
        Property: MVS_PROP_STATIC_SYSLIB_ASM=SYS1.MACLIB;SYS1.MODGEN;&userid..BANKVSAM.MACLIB
        Property: MVS_PROP_STATIC_SYSLIB_COBOL=&userid..BANKVSAM.COPYLIB
        Property: MVS_PROP_STATIC_SYSLIB_PLI=&userid..STAFF.INCLUDE
        INFO:
        * end of application definition. do not delete this line
        EndAppl:
        EndUser:

Verify and adapt the z/Server data set qualifiers.

The static syslib data set names entered in the master configuration files are default values only and visible in the modeled AWM dialog when creating a new filter definition for the first time.

Parent topic: Example AWM: MVS Projects Sample Application
Related information
Master Configuration


Use Case-Based Modeling Examples

This section contains some modeling examples based on typical modeling use cases.

  • Usage of Match Name
  • Correct Usage of ID Definition
  • Tool with Input Parameters of Type MassProcessing and String
  • Tool with Input Parameters of Parameter From=User_Input
  • Tool with Input Parameters of Parameter From=Context
  • Tool with Input Parameters of Parameter From=Previous_Tool
  • Tool with Resource Processing
  • Mass Processing from a Dialog Table
  • Validate Dialog Input Value
  • MVS Edit a Data Set Created by a REXX Procedure
Parent topic: Workflow Manager Modeling Guide
Related information
Example AWM: MVS Projects Sample Application


Usage of Match Name

If you develop a new model from scratch, you have to identify the element types used in the model.

In the model, you can provide an element type with a certain icon. An element type can be associated with a set of properties and a set of actions. When an AWM element is selected during run time, all the element type's property values show in the property views. The context menu that opens by right-clicking an element type's element shows all the actions modeled for the element type.

Use the following criteria to decide the element types in the model:
  • Grouping elements with common attributes.
  • Grouping elements on which common actions are allowed.
In the PDS Explorer model, the following elements are identified based on this distinction:
  • Project
  • Data set
  • Editable element
  • Non-Editable element
  • Unknown element
  • Search Result

Example: Element type match name

In AWM, new elements can be created by a tool that provides a list of the element's property values by means of a structured file descriptor. The file descriptor describes the file's line position where each property is delivered. For AWM to create a new element, the tool must at least deliver all the key properties of the element.

Because different element types can have the same or overlapping key properties, providing the key properties is not sufficient to identify the element type of the element to be created.

AWM needs an Element Type property to define the element type of the element. The Element Type property is a property of the AWM special Property Type Element_Type:

PDSSAMP Match Name 1

The AWM administrator must define distinct match names in the model for every element type. The value defined here is the value a tool has to return in the Element Type property when a new element should be created.

To further explain this, consider the tool providing all projects in the PDS Explorer. This is the tool PDSSAMP_TOOL_ISPF_REX_GetProjects which has as output parameter the file descriptor PDSSAMP_FILE_ProjList:

PDSSAMP Match Name 2

The file descriptor contains the following properties:

PDSSAMP Match Name 3

The ID Definition of the element type PDSSAMP_ELE_Project contains only the property PDSSAMP_PROP_ELE_Project:

PDSSAMP Match Name 4

PDSSAMP_PROP_ELE_Project is returned in the first position of the file descriptor. The second position of the file descriptor contains the Element Type property. The tool must return the match name defined for the element type PDSSAMP_ELE_Project in this position, which is the value PROJ:

PDSSAMP Match Name 5
Parent topic: Use Case-Based Modeling Examples


Correct Usage of ID Definition

The ID definition in AWM uniquely identifies elements of a certain element type.

As a unique identifier, an ID definition should consist of the key properties that identify an element in the context of the application. AWM needs a value for each key property of the corresponding ID definition when it creates a new element. A runtime exception occurs if there is a missing key property value at creation time. Elements with identical key property values are considered as identical.

You should only define the exact number of properties in an ID definition of an element that are needed to uniquely identify the element type's elements. If not enough properties are defined, different elements of the application could be considered as the same element. If too many properties are defined, a single element with different values in the non-key properties is considered as two different elements.

In the PDS Explorer model are the following ID definitions, as shown in the graphic:
  • PDSSAMP_ID_MVSMember
  • PDSSAMP_ID_Project
  • PDSSAMP_ID_Dataset
  • PDSSAMP_ID_SearchResult

PDSSAMP ID Definitions

The ID definition mappings to the PDS Explorer element types is as follows:

ID Definition | Element Type(s)
PDSSAMP_ID_Project | PDSSAMP_ELE_Project
PDSSAMP_ID_Dataset | PDSSAMP_ELE_Dataset
PDSSAMP_ID_MVSMember | PDSSAMP_ELE_EDITABLE, PDSSAMP_ELE_NON-EDITABLE, PDSSAMP_ELE_UNKNOWN
PDSSAMP_ID_SearchResult | PDSSAMP_ELE_SEARCHRESULT

The element types PDSSAMP_ELE_EDITABLE, PDSSAMP_ELE_NON-EDITABLE, and PDSSAMP_ELE_UNKNOWN share an ID definition. The mapping to the correct element type is done by the element type property which has to contain the match name defined for the corresponding element type.

Parent topic: Use Case-Based Modeling Examples


Tool with Input Parameters of Type MassProcessing and String

Tool input parameters of type MassProceesing are taken from the selected element's context. Tool input parameters of type String are taken from the context as described in the parameter attribute Parameter From. They can be derived from the context, delivered by a previous tool or provided by user input. The differentiation between MassProcessing and String input parameters is only relevant for mass processing tools, where the MassProcessing parameters are derived from each selected element, whereas the String input parameters are the same for every selected element.

An example of a tool having an MassProcessing parameter as well as a String parameter is a tool to recall migrated MVS data sets.

The MassProcessing parameter would be the property defining the data set name of the selected element. The String parameter would be a property defining whether the recall should be done in foreground or background. The recall mode should apply for all data sets to be recalled.

Example Input Parameters 1

The input parameter SAMPLE_PROP_UI_RecallMode typically comes from a previous tool which is an input dialog box with SAMPLE_PROP_UI_RecallMode as input parameter of Parameter_From=User_input.

Note: If the tool SAMPLE_TOOL_ISPF_RecallDataSet is not modeled as a mass processing tool than the example also works if the first input parameter is modeled as a String input parameter.
Parent topic: Use Case-Based Modeling Examples


Tool with Input Parameters of Parameter From=User_Input

Input parameters of type Parameter From=User Input are used as parameters of an input dialog.

The example below shows an input dialog getting the member name of a MVS PO data set from the user.

SAMPLE TOOL AWM UI

Example In Parms 2
Parent topic: Use Case-Based Modeling Examples


Tool with Input Parameters of Parameter From=Context

An example of a tool with an input parameter with Parameter_From=Context would be an ISPF tool used to delete a member of a PO data set. At run time, the parameter values are set by the member name of the selected PO member.

Example Input Parameters

Both input parameters are of Parameter_From=Context. If the ISPF tool is written to support mass processing, the two input parameters should be modeled as type MassProcessing.

Parent topic: Use Case-Based Modeling Examples


Tool with Input Parameters of Parameter From=Previous_Tool

An example of a tool with an input parameter with a Parameter_From=Previous Tool could be an ISPF tool used to delete a member of a PO data set. In this case, the tool is defined in the context menu of the PO data set. When selecting the delete member action in the PO data set's context menu, an Input dialog box lets you enter the name of the member to be deleted. This name is passed to the following tool as input parameter from the previous tool.

The definition of the delete PO member tool would look like this:

SAMPLE TOOL ISPF Delete PO Member

The second parameter in this instance is of Parameter_From=Previous Tool.

The tool definition to get the member name to be deleted could be as follows:

SAMPLE TOOL AWM UI GetMemberName

In the corresponding action, the tool SAMPLE_TOOL_AWM_UI_GetMemberName has to be modeled to run before the tool SAMPLE_TOOL_ISPF_DeletePOMember:

Example Input Parameters
Parent topic: Use Case-Based Modeling Examples


Tool with Resource Processing

After a tool's successful execution, certain processing should be applied to given resources in the UI. This is known as resource processing. An example of this is that after the execution of a deletion tool, the deleted element should be removed from the UI.

In some situations, the resource processing after the successful execution of a tool is unique and can be directly modelled by the AWM model administrator. For example, the resource processing of a deletion tool should delete, and the resource processing of an insertion tool should insert.

There are other situations when the resource processing depends on the tool's execution logic. In these situations, only the tool can decide what resource processing should be done after the tool's successful execution. For these situations, the resource processing would be tool_defined.

There is a defined protocol for how the tool can inform AWM which resource processing measures should be taken after its successful execution.

The following table shows some typical examples for the resource operation used in a tool definition.

Resource Operation | Example
COPY | Copy a member of a PO data set.
DELETE | Delete a member of a PO data set.
INSERT | Insert a new member in the Table Results view.
INSERT-CHILD | Insert a new PO member into a PO data set.
MOVE | Move a member of PO data set is moved to another PO data set.
READ | Perform no changes to resource attributes, for example, browse a PO member.
REFRESH | Change some attributes of a resource, for example, edit a PO member.
UPDATE | Change some attributes of a resource. In this case, the tool must return all attributes that should be updated in the UI. An example of this is a tool that changes the change code of a source where the change code is one of the attributes of the element visible in the UI.
TOOL_DEFINED | Get results in different effects on the UI. An example of this is a tool that gets a function code and depending of the function code, deletes or inserts an element.

In some scenarios, the resource operation returned by a tool should not be applied to the selected resource, but to another resource, such as a resource that was created by the action. In this type of scenario, the tool must return a link name to the newly created resource with the resource operation. Another tool in the action's tool chain can refer to this link name by the attribute Affected Resource Name in the relation between action descriptor and tool descriptor.

TOOL_DEFINED resource processing example

Consider a somewhat sophisticated example using TOOL_DEFINED resource processing.

The example scenario involves checking out an element from a remote SCM system and creating a local file for a later local edit action. In the UI, the checkout can be done either on a life cycle level from where the element can be edited, or on a higher life cycle level from where the element must be drawn down on an editable level before checkout. The graphics in the following are taken from the corresponding action in the SCLM model.

The action consists of two tools. The first tool does the checkout processing inclusively the draw down if necessary. The second tool is the tool "Create Persistent File" from the AWM function package.

The action is modelled like this:

The tool SCLM_TOOL_ISPF_REX_CheckOut gets the key properties of the SCM element to be checked out as element input parameter. It has to return all properties to be changed as element output parameters.

The graphic below shows how the tool SCLM_TOOL_ISPF_REX_CheckOutis modeled in the AWM SCLM model:

Sample Resource Processing

The resource operation is tool-defined because the resource processing depends on whether or not the element has to be drawn down.

If the element is already on a level to be directly edited, the tool SCLM_TOOL_ISPF_REX_CheckOut has to return the resource operation UPDATE-ELEMENT(CHKOUTELE). This means that the selected resource is updated in the UI by the property values returned by the tool.

If the element has to be drawn down to a level from where it can be edited, the tool SCLM_TOOL_ISPF_REX_CheckOut has to return the resource operation INSERT-ELEMENT(CHKOUTELE,REFRESH,SELECT). This means that a new element is inserted in the UI with the property values returned by the tool. The properties returned by the tool must at least comprise all the key properties for the element to be successfully created. SELECT means that the element is selected in the UI after the execution of the action.

CHKOUTELE is an element reference needed by the subsequent tool SCLM_TOOL_AWM_LocalFileCreator.

This element reference has to be entered under Affected Resource Name in the relation between the action SCLM_ACT_CheckOut and the tool SCLM_TOOL_AWM_LocalFileCreator, as shown in the following graphic:

Parent topic: Use Case-Based Modeling Examples


Mass Processing from a Dialog Table

The use case is an action that shows elements in a dialog table. The elements in the dialog table should be selectable. The selected elements should be processed by a subsequent tool and the changes to the elements should be visible after the action completes.

In the example shown below an action is modelled by which a change qualifier can be set to all selected elements.

The example model assumes that the AWM elements are identified by a name and a type.

The action to set the change qualifier consists of three tools:

  1. Tool to set the list in the dialog.
  2. UI tool to prompt the change qualifier to be set and to display the selection list provided by the previous tool.
  3. Tool to update the selected elements with the specified change qualifier.

It is crucial that the action is defined as a mass processing action.

Table Mass Processing 1

The first tool in the sequence just returns a file descriptor which contains a list of elements.

Table Mass Processing 2

Table Mass Processing 3

The second tool in the sequence is a modelled dialog. The dialog has a property representing the change qualifier as String input parameter from parameter type User_Input. The second input parameter is the file descriptor provided by the preceding tool. It is of parameter type Previous_Tool. In order that the elements in the table are selectable the attribute "UI Multi Selection" in the relationship "Tool has Input Parameter" must be set to true. The modelled dialog tool is modelled like this:

Change Qualifier UI Tool

The last tool in the sequence does the update of the change qualifier to the elements selected in the table dialog. The tool gets as String input parameter the change qualifier property and as MassProcessing input parameter the identifying properties of the selected elements. All input parameters have to be modelled as parameter type Previous_Tool. The tool returns as ToolDefinedResourceOperations the identifying element properties and the new change qualifier value.

The third tool is modelled like this:

Table Mass Processing 4
As in this example, if the tool is a tool of type "Execute ISPF command", the resource operations have to be returned in the ISPF table TAUTOTBI. A resource operation generated by this tool could be:
 UPDATE-ELEMENT: AWMTST01 XML CHANGE123
Parent topic: Use Case-Based Modeling Examples


Validate Dialog Input Value

You can assert that input fields in a dialog can only have specific values. AWM provides two possible solutions for this requirement.

The first solution is to specify a Retrieve All Values action for a property. If the property is defined in an AWM tool Open Modeled Dialog it is displayed as a selection list followed by a Retrieve button. Clicking Retrieve executes the Retrieve All Values action. This selects the values in the list that you have specified for the property.

The second solution is to specify a Validate Action for an AWM tool Open Modelled Dialog. The validate action can contain one or more tools which validate the properties specified in the dialog box.

You can write custom scripts to check one or more dialog properties if there are, for example, dependencies between the properties being checked. You must ensure that the tools generate error messages of an appropriate severity. See Validate Action for more information. The tool's messages are processed and evaluated by the validate action. If there is at least one error message supplied by a tool of the validate action the dialog box is not closed when you click OK.

The tool Validate Value is provided within the AWM function package. You can use it for simple validation, for example, to validate a property values against regular expressions. So that an input field conforms with a specific naming convention.

Example

The following example dialog box contains a Department, Project, and Development Environment field. The Department field has a corresponding Retrieve button. When you click Retrieve it fetches all the values for a department of a company. In addition, the AWM tool Open Modelled Dialog has a validation action which points to two validation tools. One for the property Project and one for the property Development Environment.

The property Department is modeled with a Retrieve All Values action:

Retrieve All Values

This action calls a tool which returns a file descriptor with just one property. The file created by the tool contains all the valid values for the Department. Each Department in a separate line in the file.

The modelling of the tools looks like this:

The Message Severity for the validation tools has been modeled as an Error. The Message Type for the validation tool has been modeled as Validation Message:

The Regex field specifies a regular expression that is used to validate the Project name. In this case, it accepts upper and lower case letters, numbers, #, and $. In addition, the project name must be between 1 and 16 characters long.

The validation action is modeled as follows:

At execution the dialog box looks like:

Create Project Dialog

You can select a Department once you have clicked Retrieve. If the values in the Project and Development Environment fields do not match their corresponding regular expressions then error markers are displayed along with any modeled validation message:

Parent topic: Use Case-Based Modeling Examples


MVS Edit a Data Set Created by a REXX Procedure

This modelling example is based on the following use case.

There are three development test environments:

  • Unit Test

  • Integration Test

  • System Test

The REXX TAUSACDS creates batch JCL via ISPF file tailoring by which test data sets for one of the test environments can be allocated.

The REXX has just one input parameter which defines the test environment by a integer value:
1
Unit Test
2
Integration Test
3
System Test
(1 = , 2 = , 3 = ). The REXX writes the created batch JCL in a sequential MVS dataset and returns the name of this dataset.

You can decide if you want to edit the batch JCL before submitting it or have it directly submitted to MVS.

This use case should be provided by an action which can be modelled as global action or as a context menu action of a test environment.

You need to specify two properties:

  • A property to select the test environment SAMPLE_PROP_UI_SelectTestEnvironment.

    The type of the property is SelectValue. Under Type: Select Value in the Property view, you can specify the labels you want to see in a drop down box within the dialog for this property and the corresponding values which should be passed as input parameters to a REXX procedure.

    Type: Select Value
  • Property to determine whether the generated JCL should be edited before submitting SAMPLE_PROP_UI_IsJCLEdited

    The type of this property is Bolean.

You need to model an AWM dialog so that you can enter the input parameters for the action. The dialog should have the two properties created above as input parameters and should be a tool of type "Open Modelled Dialog" from the AWM function package.

Create Data Set Dialog

With the model editor action "Preview Dialog" you can test how your dialog looks during runtime:

Create Data Set Dialog Preview

You need to model the sequential MVS data set returned by the REXX procedure as a File Descriptor. The file type is MVS_SEQ:

You can now model the ISPF command tool to call the REXX procedure.

Model the REXX procedure as an Execute ISPF Command tool with input and output parameter. The input parameter SAMPLE_PROP_UI_SelectTestEnvironment has to be modeled as a Parameter From Previous_Tool.

The output parameter should be modeled as a File type that points to the File Descriptor modeled before. This ensures that the data set name returned by the REXX procedure is used as the "Name Physical" for the sequential MVS data set during run-time.

The REXX procedure tool is modeled as follows:

Execute ISPF Command

You now need an MVS tool to edit the sequential MVS data set. You can model this as an Edit MVS File tool from the MVS function package. The tool has one input parameter of type File pointing to the File Descriptor modeled earlier. The parameter should be modeled as "Parameter From" Previous_Tool.

Edit MVS File

The last tool you need is the MVS tool to submit the generated JCL. You should model this as Submit JCL tool from the MVS function package. The input parameter has to be modeled in the same way as the input parameter for the tool SAMPLE_TOOL_MVS_EditJCL.

You now need to model the action calling the tools.

Action Generate JCL

The action calls the four tools. The tool SAMPLE_TOOL_MVS_EditJCL has an enabling condition. This means that the tool is only called if the input parameter SAMPLE_PROP_UI_IsJCLEdited is set to true within the preceding input dialog. The tool SAMPLE_TOOL_MVS_SubmitJCL is only called if the input parameter SAMPLE_PROP_UI_IsJCLEdited is set to false.

In addition, you can add an editor action to allow you to submit the editor content as a batch job to MVS. In this case, you need to model another Submit JCL tool from the MVS function package because the tool parameter "Submit JCL from" should be "An Active Editor". When the tool parameter "Submit JCL from" is set to "An Active Editor" in the Property view the file input parameter of the tool is automatically removed in the model editor.

You need to model an action calling the tool.

Submit Edited JCL

This action is modeled as part of a global editor action. The global action needs a "ISA Editor Action" relationship to mark it as an editor action. In this relationship file suffix can be defined so that the editor action is only shown in the editor context menu when the edited file has a suffix contained in the blank separated list.

Editor Action JCL
Parent topic: Use Case-Based Modeling Examples


AWM Model Maintenance

  • Further Development and Maintenance
  • Maintaining the AWM Model
  • Changes to ID Definitions
  • Converting a Deprecated Model
Parent topic: Workflow Manager Modeling Guide


Further Development and Maintenance

Modeled applications can be flexibly maintained. It is possible to modify and test both the AWM and tools of an application without changing the production status.

Parent topic: AWM Model Maintenance


Maintaining the AWM Model

A suitable way to maintain an AWM is to define a test application in the master configuration file.

One way to test model modifications is to specify a local file path for the AWM in the master configuration file. This should point to a project in the administrator's workspace. See Setting up and Configuring AWM for more information. This is so that the project can conveniently maintain the file with the Model editor. It is also possible to make use of the file suffix .model, as the file can be directly opened with the Model editor.
Application cache

For example, the conf attribute of the Master Configuration for a local test AWM:
  • local: c:\config\repository.model
Note: Consider the following points when maintaining and testing this application:
  • The AWM is copied when loading the test application and uses the copy at run time. You should be familiar with the rules that cause an application to be loaded. In particular the remarks regarding the version number in Variable References and Master Configuration. A revised AWM is only loaded if the version number of the application in the master configuration is different from the version number in the modeled application options.
  • You can initiate a load of the application for testing by targeted modification of the version number in the master configuration and in the application options.
  • If ISPF tools that should be verified in the test environment are also changed during maintenance of the AWM, the ISPF test environment can be dynamically allocated for this application with the exit TAUTOXA1. See ISPF Exits, and EXITPARM in Variable References for more information.

Certain changes to an AWM that has already been used could lead to the existing cache no longer being compatible with the AWM. In particular the removal of properties and the modification of IDs. The results are errors at run time and as a rule occur when loading the application.

The parts of the caches that must be deleted can be specified in the master configuration through the entry of a new version. See Master Configuration for more information. If the effects on consistency as a result of the changes carried out are not absolutely clear to the user, a test must be carried out to determine which parts of the cache have to be deleted in the case of an update. In order to do this, the most important components of the cache must first have been generated in the existing AWM. This requires the following actions to have been carried out at least once:
  • Loading an application.
  • Identifying containers, the expansion of the application is sufficient.
  • Creation of a filter.
  • Creation of an element list, for example, by carrying out the filter action.
  • Opening an element in the editor.
  • Restarting Eclipse.

If errors still occur when loading a new version, a number of components have to be deleted in the cache, entries in the master configuration.

If a situation arises when testing that makes the automatic deletion of the cache by the entry no longer possible in the master, the cache can be deleted manually at any time.

The figure above shows the complete cache of an application in the Navigator view. The individual files have the following descriptions:

File name | Description | Critical changes
eb_elementsinlists.xml lm_Element List s.xml li_LI_<listID>.xml et_elements.xml | Contain all the information stored about elements and element lists. Deleting the files removes all element lists and the cached information about elements. They should always be deleted together, or inconsistencies could arise. | Changes to ID definitions, element list structures, elements and all their relationships.
tv_tableviewlists.xml cs_columnsetting.xml er_errorFeedback.xml | Contains all the information about showing element lists on the user interface. Contain all the information about columns of a Table Results view. Contains errors that have been generated by means of the integrated tools Error Feedback. All the error entries of the Error List are lost when the file is deleted. | None None None
ft_filters.xml | Contains all the filters defined by the user. All the filters are lost if the file is deleted. | Changes to filter types and their relationships.
ft_openfiles.xml | Stores references to all files that the user had open when leaving the application in the editor. Once this file has been deleted, a restore of editor changes after an application restart is no longer possible. | None
jt_jobs.xml | Contains all submitted and finished jobs. All the job information is lost if the file is deleted. | None

Even if the Navigator view supports the deletion of files in principle, the cache must be directly deleted from the file system after closing Eclipse. Otherwise, the cache is rewritten when leaving Eclipse, this is because the cache is exclusively created on Close. The Navigator view can be used to locate the cache from the Properties view, see the figure below:

Determining the file path of the Cache

If all changes to a new AWM have been tested locally, they can be released for all users. The following steps must be followed:

  1. Increase the version number of the new AWM.
  2. Adapt the master configuration file:
    • Compare the version number with the new AWM.
    • Where necessary, supplement the INFO entries for the deletion of the cache.
  3. Update the central AWM.
Parent topic: AWM Model Maintenance
Related information
Creating an AWM Model
Master Configuration
Variable References


Changes to ID Definitions

The modification of an ID definition or the reference of element types to an ID definition is a special modification case if the application supports persistent local files to elements (e.g. check-out). Elements that should be edited locally will be created under a unique path in the workspace that is derived from the ID definition. If the ID definition has been changed, any local file which exists at the time of the new AWM replacement can no longer be reached via integrated tools. Changes to ID definitions should therefore be avoided wherever possible.

In order to avoid data losses, a backup folder is generated at every update of the AWM. This contains all the locally stored content of the corresponding application before the update (including the cache). If a user has elements in local processing at the time of an update in which ID definitions will change, he can restore these manually from the backup path by modifying the new folder structure.

Example:

Local Application Data after an ID Definition Update

Here, you can see the file path of the local checked-out element TESTC1 before the update (red) and after it (blue). The new folder structure (blue) has been created manually.

Note: Cached files are there as well but not shown in this picture.
Parent topic: AWM Model Maintenance


Converting a Deprecated Model

AWM models containing deprecated objects can be converted, click Model Editor > Convert Deprecated Model command, see figure below. The Model Editor menu is available when an AWM model editor is opened and focused, while Convert Deprecated Model is only enabled if the opened model contains objects that can be converted.

Converting a deprecated model makes unsaved changes to the model. You can undo these changes, click Edit > Undo. Several undo operations might be required, depending on the applied conversions.

Custom deprecated model conversion rules can be added to AWM using the plug-in API, extension point “com.microfocus.awm.metamodel.conversionRule”.

Parent topic: AWM Model Maintenance


Workflow Manager Modeling Tutorials

The following tutorials are available:

  • Tutorial: Creating an AWM Model with AWM Element Types
    This tutorial walks you through the process of creating an AWM model that uses AWM element types to create a workflow that integrates an issue tracking system into your workbench.
  • Tutorial: Creating an AWM Model with AWM Linked Element Types
    This tutorial walks you through the process of creating an AWM model that uses AWM linked element types from the Eclipse function package.
  • Tutorial: Adding a New Action to an Existing AWM Model
    This tutorial walks you through the process of adding a new context menu to an existing AWM model. In this case, you will modify the Enterprise Developer project's model.
Parent topic: Workflow Manager Modeling Guide


Tutorial: Creating an AWM Model with AWM Element Types

This tutorial walks you through the process of creating an AWM model that uses AWM element types to create a workflow that integrates an issue tracking system into your workbench.

Prerequisites

To complete this tutorial, you need Enterprise Developer for Eclipse installed.

Overview

The Application Workflow Manager (AWM) is a framework based on the Eclipse Modeling Framework (EMF). AWM enables you to develop models to implement the application development workflow of your company. In this tutorial you develop a simplified model of an issue tracking system into your Eclipse workbench. AWM enables you to merge distinct models each supporting different functionality integrating them into a seamless application development workflow within a perspective.

The model you develop will create an application tree that can be viewed in the Application Explorer view:

Tutorial: Application Tree

You will create a context menu action to display the issues in the Table Results view:

Tutorial Table Results

You will create a context menu action for an issue which displays its raiser.

  1. Creating the Project
  2. Creating the Model
  3. Validating the Model
  4. Running and Testing the Model
Parent topic: Workflow Manager Modeling Tutorials


Creating the Project

You will make use of two tools of tool type Execute OS Command from the OS function package:

  • A tool which returns a list of issues filtered by the issue priority.
  • A tool which returns the raiser of a given issue.

You can develop a tool of type Execute OS Command as a local COBOL program to generate an .exe file that can be specified as a tool of type Execute OS Command in the AWM model.

Start by creating a COBOL project:

  1. Launch Enterprise Developer. Specify a path for the Eclipse workspace when prompted.

    If this is the first time you start Eclipse, the IDE displays the Eclipse Welcome page. Click Open Team Developer Perspective which is the default perspective in Enterprise Developer.

    If the IDE does not start in the Team Developer perspective, click Window > Perspective > Open Perspective > Other, click Team Developer (default), and then click OK.
  2. In the Application Explorer view, click File > New > Other.

    This opens the New dialog box.

  3. Click Micro Focus COBOL > COBOL Project.
  4. Click Next.
  5. In the Project name field, type IssueTrackingSystem.
  6. Click Finish.
    Tip: If your project is not visible in the Application Explorer view, right-click Enterprise Developer Projects, and then click Load Application.

You now need to create the two COBOL programs:

  1. In the Application Explorer view, right-click the IssueTrackingSystem project.
  2. Click New > File > COBOL Program.

    This opens the New COBOL Program dialog box.

  3. In the New file name field, type GetIssues.cbl
  4. Click Finish.

    This opens the program in the COBOL editor.

  5. Copy and paste the following COBOL code into the editor, overwriting the existing text:
           program-id. GetIssues as "GetIssues".
      ******************************************************************
      * This COBOL program is part of the AWM tutorial "Issue Tracking *
      * System".                                                       *
      * The program reads the issues from the sample data set and      *
      * creates an output file according to the AWM model file         *
      * descriptor containing the issues to display in the AWM Table   *
      * Results view.                                                  *
      * The program allows to filter the issues by the input parameter *
      * priority.                                                      *
      ******************************************************************
       environment division.
       configuration section.
       input-output section.
       file-control.

       select out-file assign to disk
       organization is line sequential.

       select in-file assign to disk
       organization is line
       sequential
       file status is ws-file-status.

       data division.

       file section.

      * output file cotaining the input for the AWM Table Results view;
      * will be written under c:\temp\issue_list.txt .
       fd out-file
       label records are standard
       value of file-id is"c:\temp\issue_list.txt".

       01 out-rec.
          05 ticket-no         pic 9(8).
          05 filler            pic x.
          05 raiser            pic x(20).
          05 filler            pic x.
          05 creation-date     pic x(10).
          05 filler            pic x.
          05 priority          pic 9.
          05 filler            pic x.
          05 description       pic x(30).
          05 filler            pic x.
          05 issue-status      pic 9.
          05 filler            pic x.
          05 ele-type          pic x(5).

      * file containing the sample issues; expected to reside under    *
      * c:\temp\issue_input.txt .
       fd in-file
       label records are standard
       value of
       file-id is"c:\temp\issue_input.txt".

       01 in-rec.
          05 ticket-no         pic 9(8).
          05 raiser            pic x(20).
          05 creation-date     pic x(10).
          05 priority          pic 9.
          05 description       pic x(30).
          05 issue-status      pic 9.

       working-storage section.
       01 cmdline-text.
          03 issue-prio              pic x(12).
       01 ws-file-status.
          03 ws-file-status-key1     pic x.
          03 ws-file-status-key2     pic x.
          03 ws-file-status-key2-bin
            redefines ws-file-status-key2 pic 99 comp-x.
       01 ws-eof                     pic x.

       procedure division.

       main-section section.

       main-processing-start.
           open input in-file
           if ws-file-status not = "00"
              if ws-file-status-key2-bin = 53
                 display "ReturnCode: 12"
                 display "Message: Input file not found! "
                 goback
              end-if
           end-if

           open output out-file
      * read tool input parameter
           accept cmdline-text from command-line
      * read all records of the input file
           perform until ws-eof = 'Y'
               read in-file into in-rec
                   at end move 'Y' to ws-eof
                   not at end perform process-rec through
                              process-rec-end
               end-read
           end-perform

           close in-file.
           close out-file
      * return the name of the written file as AWM output parameter
           display
              "OutParm: c:\temp\issue_list.txt".
       main-processing-end.
           goback.

       process-rec.
      * ignore blank lines
           if in-rec = spaces then
              go to process-rec-end
           end-if
      * initialize the output record with the parameter delimiter
      * defined in the AWM model
           move all ";" to out-rec
      * entered priority '*' means process all records
           if issue-prio = '*' then
              move corresponding in-rec to out-rec
      * set the element type property
              move "ISSUE" to ele-type
              write out-rec
           else
      * check if priority of the record equals entered priority
              if priority of in-rec = issue-prio then
                 move corresponding in-rec to out-rec
      * set the element type property
                 move "ISSUE" to ele-type
                 write out-rec
               end-if
           end-if.

       process-rec-end.
           exit.
       end program GetIssues.
  6. Click File > Save.
  7. In the Application Explorer view, right-click the IssueTrackingSystem project.
  8. Click New > File > COBOL Program.

    This opens the New COBOL Program dialog box.

  9. In the New file name field, type GetIssueRaiser.cbl
  10. Click Finish.

    This opens the program in the COBOL editor.

  11. Copy and paste the following COBOL code into the editor, overwriting the existing text:
           program-id. GetIssueRaiser as "GetIssueRaiser".
      ******************************************************************
      * This COBOL program is part of the AWM tutorial "Issue Tracking *
      * System".                                                       *
      * The program returns the raiser of a certain issue in the AWM   *
      * output format of a local OS tool.                              *
      ******************************************************************
       environment division.
       configuration section.
       input-output section.
       file-control.

       select in-file assign to disk
       organization is line
       sequential
       file status is ws-file-status.

       data division.

       file section.
      * file containing the sample issues; expected to reside under    *
      * c:\temp\issue_input.txt .                                      *
       fd in-file
       label records are standard
       value of
       file-id is"c:\temp\issue_input.txt".

       01 in-rec.
          05 ticket-no         pic 9(8).
          05 raiser            pic x(20).
          05 creation-date     pic x(10).
          05 priority          pic 9.
          05 description       pic x(30).
          05 issue-status      pic 9.

       working-storage section.
       01 cmdline-text.
          05 ticket-no                 pic    x(12).
       01 ws-eof                       pic x.
       01 ws-file-status.
          03 ws-file-status-key1     pic x.
          03 ws-file-status-key2     pic x.
          03 ws-file-status-key2-bin
            redefines ws-file-status-key2 pic 99 comp-x.

       01 out-line.
          05 outparm                  pic x(9) value 'OutParm: '.
          05 raiser                   pic x(20).
       procedure division.
           open input in-file
           if ws-file-status not = "00"
              if ws-file-status-key2-bin = 53
                 display "ReturnCode: 12"
                 display "Message: Input file not found! "
                 goback
              end-if
           end-if
      * read tool input parameter
           accept cmdline-text from command-line
      * read the file until record with entered ticket number is found
      * or end of file is reached
           perform until ws-eof = 'Y'
               read in-file into in-rec
                   at end move 'Y' to ws-eof
                   not at end perform process-rec through
                              process-rec-end
               end-read
           end-perform
           display out-line

           goback.
       process-rec.
           if ticket-no of in-rec = ticket-no of cmdline-text then
              move raiser of in-rec to raiser of out-line
              move 'Y' to ws-eof
           end-if.
       process-rec-end.
           exit.
       end program GetIssueRaiser.
  12. Click File > Save.
  1. Specifying a Build Configuration to Create two Executables
  2. Creating Sample Data
Parent topic: Tutorial: Creating an AWM Model with AWM Element Types
Next topic: Creating the Model


Specifying a Build Configuration to Create two Executables

You need to modify the project build configuration to create an .exe file for both COBOL programs:

  1. In the Application Explorer view, right-click the IssueTrackingSystem project.
  2. Click Properties.

    This opens the Properties for IssueTrackingSystem dialog box.

  3. Click Micro Focus > Build Configurations > COBOL.
  4. From the Target Type list, select All Executable Files.
  5. Click Apply and Close.

    The project is rebuilt, creating two executable files (GetIssueRaiser.exe and GetIssues.exe) in the Output Path folder. By default, this is New Configuration.bin.

Parent topic: Creating the Project
Next topic: Creating Sample Data


Creating Sample Data

The issue tracking system will use some sample data. To create the sample data for your application to use:

  1. Create the folder C:\temp to store the sample data that will be used by the COBOL programs.
  2. In the C:\temp folder, create a .txt file called issue_input.txt.
  3. Copy and paste the following text into the file:
    97544545Smith               2017/03/122Require new computer mouse    1
45646112Jones               2016/12/191Update version of Visual COBOL3
87576573Williams            2017/04/033Printer is defective          2
76556546Hill                2017/05/050Coffee machine isn't working  3
19452942Taylor              2017/07/072Need a new ED licence         0

    This sample data contains ticket number, raiser, creation date, priority, description, and status information.

Parent topic: Creating the Project
Previous topic: Specifying a Build Configuration to Create two Executables


Creating the Model

To create a model file in your project, first create a new folder for it to go in:

  1. In the Application Explorer view, right-click the IssueTrackingSystem project.
  2. Click New > Folder > Folder.

    This opens the New Folder dialog box.

  3. In the Folder name field, type model.

    To view this new folder:

    1. Click View Menu View Menu, and then click Filters and Customization.

      This opens the Filters and Customization dialog box.

    2. In the Filters tab, uncheck Empty folders outside categories.
    3. Click OK.
  4. Click the model folder.
  5. Click File > New > Other.

    This opens the New dialog box.

  6. Click AWM > AWM Model.
  7. Click Next.
  8. In the File name field, type IssueTracking.model.
  9. Click Finish.

    This opens the model in the AWM editor.

  1. Specifying Application Options & Function Packages
  2. Specifying the Properties
  3. Specifying Element Types with their Properties
  4. Adding Icons to Element Types
  5. Specifying Relationships between Element Types and Properties
  6. Specifying Tree View Labels and Text Decorations
  7. Specifying the ID Definitions
  8. Specifying Tool Descriptors
  9. Specifying File Descriptors
  10. Specifying the Action Descriptors
  11. Specifying the Element List Structure
  12. Associating the Action Descriptors
Parent topic: Tutorial: Creating an AWM Model with AWM Element Types
Previous topic: Creating the Project
Next topic: Validating the Model


Specifying Application Options & Function Packages

In the IssueTracking.model:

  1. Expand platform:/ > Document Root > AWM Model.
  2. Right-click Application Options 0.0.
  3. Click Edit.

    This opens the Edit Properties dialog box.

  4. Double-click the Version value cell, type 1.0.
  5. Click OK.
  6. To specify the required function packages, right-click Function Packages.
  7. Click New Child > AWM.

    This adds the AWM function package.

  8. Right-click Function Packages.
  9. Click New Child > OS - Operating System.

    This adds the OS - Operating System function package.

  10. Click File > Save.
Parent topic: Creating the Model
Next topic: Specifying the Properties


Specifying the Properties

As with all AWM models you need to specify the properties that represent the object attributes of the modeled system. You need to create the following properties:

  1. Right-click Properties.
  2. Click New Child > Property.

    This opens the Enter Object ID dialog box.

  3. In the Property field, type TUTORIAL_PROP_ELE_CreationDate.
  4. Click OK.
  5. Right-click TUTORIAL_PROP_ELE_CreationDate, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Type value cell, and then click Date.
  7. Double-click the Label value cell, and then type Creation Date.
  8. Click OK.
  9. Repeat step 1 through 7 for the following properties, modifying the Property, Type, and Label field values as listed:
    Property | Type | Label
    TUTORIAL_PROP_ELE_TicketNumber | Numeric | Ticket Number
    TUTORIAL_PROP_ELE_Raiser | String | Raiser
    TUTORIAL_PROP_OSCommandString | String | Command
    TUTORIAL_PROP_ELE_Description | String | Description
    TUTORIAL_PROP_ELE_EleType | String | Type
    TUTORIAL_PROP_STATIC_IssueFilter | String | Issue
  10. The following two properties are different from the ones already specified because they are of type SelectValue. These properties are used to restrict the values for the properties to a specified list. The Label Keys are the values displayed in the selection list. The Value Keys are the values passed to a tool when the corresponding label is selected in the list.
    Note: If the Value Keys list is empty then the label value is passed to the tool instead.
    Property | Type | Label | Label Keys | Value Keys | Default Value
    TUTORIAL_PROP_ELE_Status | SelectValue | Status | Open, In_progress, Resolved, Closed | 0, 1, 2, 3
    TUTORIAL_PROP_ELE_Priority SelectValue Priority Low, Medium, High, Urgent 0, 1, 2, 3 *

    To add the label keys for the TUTORIAL_PROP_ELE_Status property:

    1. Double-click Label Keys value cell, and then click Lable Value Button.

      This opens the Label Keys dialog box.

    2. In the Value field, type Open.
    3. Click Add.
    4. Repeat step b through c for each of the remaining label keys.
    5. Click OK.

    To add the value keys for the TUTORIAL_PROP_ELE_Status property:

    1. Double-click Value Keys value cell, and then click Label Value Button.

      This opens the Value Keys dialog box.

    2. In the Value field, type 0.
    3. Click Add.
    4. Repeat step b through c for each of the remaining value keys.
    5. Click OK.

    Repeat the above for the label and value keys for the TUTORIAL_PROP_ELE_Priority property.

  11. Your model requires one property which will return the match name specifying the element type. This is identified by the Special Property which needs to be set to Element_Type. In the issue tracking system model, specify the TUTORIAL_PROP_EleType property as having a Special Property of Element_Type. To do this:
    1. Right-click TUTORIAL_PROP_ELE_EleType, and then click Edit.

      This opens the Edit Properties dialog box.

    2. Double-click the Special Property value cell, and then click Element_Type.
    3. Click OK.
Parent topic: Creating the Model
Previous topic: Specifying Application Options & Function Packages
Next topic: Specifying Element Types with their Properties


Specifying Element Types with their Properties

You need to create three different element types:

  1. An Element Type to represent an issue.
  2. An Element Type to represent the first tree view level with the fixed values 'All Issues' and 'Issues by Priority'.
  3. An Element Type to represent the second tree view level with the fixed values 'Low', 'Medium', 'High', and 'Urgent'.

In the AWM model editor:

  1. Right-click Element Types.
  2. Click New Child > Element Type.

    This opens the Enter Object IDs dialog box.

  3. In the Element Type field, type TUTORIAL_ELE_Issue.
  4. Click OK.
  5. Right-click TUTORIAL_ELE_Issue, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Matchname value cell, and type ISSUE.
  7. Click OK
  8. Repeat steps 1 through 6 for the following Element Types and corresponding Matchtypes:
    Element Type | Matchtype
    TUTORIAL_ELE_IssueFilter | ISSUEFILTER
    TUTORIAL_ELE_PriorityFilter | ISSUEPRIORITY
Parent topic: Creating the Model
Previous topic: Specifying the Properties
Next topic: Adding Icons to Element Types


Adding Icons to Element Types

You can add specific icons to the Element Types. The icons you use need to be specified under the Icons category in the AWM model.

  1. Right-click Icons, and then click New Child > AWM > Element > Database.
  2. Repeat step 1 for the following element icons:
    • Non-editable File
    • Project
  3. Right-click TUTORIAL_ELE_Issue, and then click Edit.
  4. This opens the Edit Properties dialog box.
  5. Double-click Icon value cell, and then click Function Package Icon: Non-editable File.
  6. Click OK.
  7. Repeat steps 3 through 6 for the remaining two Element Types setting the Icon property to:
    Element Types | Icon
    TUTORIAL_ELE_IssueFilter | Function Package Icon: Database
    TUTORIAL_ELE_PriorityFilter | Function Package Icon: Project
Parent topic: Creating the Model
Previous topic: Specifying Element Types with their Properties
Next topic: Specifying Relationships between Element Types and Properties


Specifying Relationships between Element Types and Properties

Properties and their relationships to Element Types need to be specified. In the Properties folder of the AWM Model:

  1. Hold down Ctrl while you click the following properties:
    • TUTORIAL_PROP_ELE_CreationDate
    • TUTORIAL_PROP_ELE_TicketNumber
    • TUTORIAL_PROP_ELE_Raiser
    • TUTORIAL_PROP_ELE_Description
    • TUTORIAL_PROP_ELE_Status
    • TUTORIAL_PROP_ELE_Priority
  2. Drag the selection and drop on the TUTORIAL_ELE_Issue element type.

    This opens the Create Relationship dialog box.

  3. Click OK.

    Your TUTORIAL_ELE_Issue element type should now look like:

    TUTORIAL_ELE_Issue Has Property
  4. Hold down Ctrl while you click the following properties:
    • TUTORIAL_PROP_STATIC_IssueFilter
    • TUTORIAL_PROP_ELE_EleType
  5. Drag the selection and drop on the TUTORIAL_ELE_IssueFilter element type.

    This opens the Create Releationships dialog box.

  6. Click OK.
  7. Hold down Ctrl while you click the following properties:
    • TUTORIAL_PROP_ELE_Priority
    • TUTORIAL_PROP_ELE_EleType
  8. Drag the selection and drop on the TUTORIAL_ELE_PriorityFilter element type.

    This opens the Create Relationships dialog box.

  9. Click OK.
Parent topic: Creating the Model
Previous topic: Adding Icons to Element Types
Next topic: Specifying Tree View Labels and Text Decorations


Specifying Tree View Labels and Text Decorations

Specifying tree view labels

You need to specify a property which is taken as a label if an element of the corresponding element type is displayed in the Application Explorer view. To do this, in the Element Types category folder:

  1. Right-click TUTORIAL_ELE_Issue > Has Property #n -> TUTORIAL_PROP_ELE_TicketNumber.
  2. Click Edit.

    This opens the Edit Properties dialog box.

  3. Double-click the Tree View Label value cell.
  4. Click true.
  5. Click OK.
  6. Repeat steps 1 through 5 for the following element type properties:
    • TUTORIAL_ELE_IssueFilter > Has Property #n -> TUTORIAL_PROP_ELE_IssueFilter
    • TUTORIAL_ELE_PriorityFilter > Has Property #n -> TUTORIAL_PROP_ELE_Priority

Specifying text decoration

You also need to model a text decoration for the element type TUTORIAL_ELE_Issue. The text decoration is displayed as the label of an element in the Application Explorer view.

In this case, the text decoration will display:

  • The priority status and description for an issue displayed under 'All issues'.
  • Status and description for an issue displayed under a priority.

To create the text decoration:

  1. Right-click TUTORIAL_ELE_Issue.
  2. Click New Child > Text Decoration.

    This adds the child element Text Decoration #1 -> Behind the Label.

  3. Right-click Text Decoration #1 -> Behind the Label.
  4. Click New Child > Decoration Value.

    This adds the Decoration Value #1 as a child element.

  5. Right-click Decoration Value #1, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ELE_Priority (SelectValue).
  7. Click OK.
  8. Right-click Decoration Value #1, and then click New Child > Visible Condition.

    This adds the Visible Condition element as a child to the Decoration Value #1 element.

  10. Right-click Visible Condition.
  11. Click New Child > Simple Condition.

    This adds the Condition child element to Visible Condition.

  12. Right-click Condition, and then click Edit.

    This opens the Edit Properties dialog box.

  13. Double-click the Target ID value cell, and then click TUTORIAL_PROP_STATIC_IssueFilter (String).
  14. Double-click the Value value cell, and then type All Issues.
  15. Click OK.
  16. Right-click Text Decoration #1 -> Behind the Label.
  17. Click New Child > Decoration Value.

    This adds the Decoration Value #2 as a child element.

  18. Right-click Decoration Value #2, and then click Edit.

    This opens the Edit Properties dialog box.

  19. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ELE_Status (SelectValue).
  20. Click OK.
  21. Right-click Text Decoration #1 -> Behind the Label.
  22. Click New Child > Decoration Value.

    This adds the Decoration Value #3 as a child element.

  23. Right-click Decoration Value #3, and then click Edit.

    This opens the Edit Properties dialog box.

  24. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ELE_Description (String).
  25. Click OK.

Your TUTORIAL_ELE_Issue element should look like this:

Tutorial_ELE_Issue Text Decoration
Parent topic: Creating the Model
Previous topic: Specifying Relationships between Element Types and Properties
Next topic: Specifying the ID Definitions


Specifying the ID Definitions

The ID definitions must uniquely identify element properties during runtime.

Creating ID Definitions

To specify the required ID definitions:

  1. Right-click ID Definitions, and then click New Child > ID Definition.

    This opens the Enter Object ID dialog box.

  2. In the ID Definition field, type TUTORIAL_IDDEF_IssueID.
  3. In the Properties folder, click TUTORIAL_PROP_ELE_TicketNumber (Numeric) and drag and drop onto the TUTORIAL_IDDEF_Issue.

    This opens the Create Relationships dialog box.

  4. Click OK.
  5. Repeat steps 1 through 4 twice, substituting the following:
    ID Definition and Target for Drag & Drop | Property to Drag and Drop
    TUTORIAL_IDDEF_PriorityFilter | TUTORIAL_PROP_ELE_Priority (SelectValue)
    TUTORIAL_IDDEF_IssueFilter | TUTORIAL_PROP_STATIC_IssueFilter (String)

The resulting ID definitions should look like:

Associating ID Definitions with their Element Types

To associate the ID definitions with their respective Element Types, expand the Element Types folder:

  1. Right-click TUTORIAL_ELE_Issue, and then click Edit.

    This opens the Edit Properties dialog box.

  2. Double-click the ID Definition value cell, click TUTORIAL_IDDEF_IssueID.
  3. Click OK.
  4. Repeat steps 1 through 3 substituting the following:
    Element Type | ID Definition
    TUTORIAL_ELE_IssueFilter | TUTORIAL_IDDEF_IssueFilter
    TUTORIAL_ELE_PriorityFilter | TUTORIAL_IDDEF_PriorityFilter
Parent topic: Creating the Model
Previous topic: Specifying Tree View Labels and Text Decorations
Next topic: Specifying Tool Descriptors


Specifying Tool Descriptors

The issue tracking system requires five tools:

  1. A tool to produce the first Application Explorer tree view level.
  2. A tool to produce the level below the tree view entry, 'Issues by Priority'.
  3. A tool to return the list of issues filtered by the priority.
  4. A tool to return the raiser of an issue.
  5. A tool to display the raiser of an issue.

Specifying the Create Issue Filter Level Tool

The tool Create Static Element List in the AWM function package enables you to return a list of fixed values within a file descriptor:

  1. Right-click Tool Descriptors, and then click New Child > AWM > Create Static Element List.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_AWM_CreateIssueFilterLevel.
  3. Right-click TUTORIAL_TOOL_AWM_CreateIssueFilterLevel, and then click New Child > Element.

    This adds the Element attribute to the TUTORIAL_TOOL_AWM_CreateIssueFilterLevel tool.

  4. Right-click Element, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Matchname value cell, and then type ISSUEFILTER.
  6. Click OK.
  7. Right-click Element [Matchname = ISSUEFILTER], and then click New Child > Property.
  8. Right-click Property, and then click Edit.

    This opens the Edit Properties dialog box.

  9. Double-click the Property Value value cell, and then type All Issues.
  10. Click OK.
  11. Repeat steps 3 through 10 to create another element and child property, this time in the Property Value value cell, type Issues by Priority.

    Your tool should look like:

    Tool: Create Issue Filter Level

Specifying the Create Static Priority Level Tool

You need to create another tool of the same type, Create Static Element List:

  1. Right-click Tool Descriptors, and then click New Child > AWM > Create Static Element List.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_AWM_CreateStaticPriorityLevel.
  3. Click OK.
  4. Right-click TUTORIAL_TOOL_AWM_CreateStaticPriorityLevel, and then click New Child > Element.

    This adds the Element attribute to the TUTORIAL_TOOL_AWM_CreateStaticPriorityLevel tool.

  5. Right-click Element, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Matchname value cell, and then type ISSUEPRIORITY.
  7. Click OK.
  8. Right-click Element [Matchname = ISSUEPRIORITY], and then click New Child > Property.
  9. Right-click Property, and then click Edit.

    This opens the Edit Properties dialog box.

  10. Double-click the Property Value value cell, and then type 0.
  11. Click OK
  12. Repeat steps 4 through 11 three more times replacing the Property Value with 1, 2, and 3 in each iteration.

    Your tool should look like:

    Tool: Create Styatic Priority Level

Specifying the List Issue Tool

The remaining two tools are linked to the COBOL programs GetIssues.cbl, and GetIssueRaiser.cbl, which should now have corresponding executable files (.exe). You can use an existing tool from the OS - Operating System function package to enable calls to an .exe in your local file system:

  1. Right-click Tool Descriptors, and then click New Child > OS - Operating System > Execute OS Command.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_CMD_ListIssues.
  3. Click OK.

    Your tool requires two input parameters:

    • Command string.
    • Issue priority filter.
  4. To add the first input parameter to this tool, right-click TUTORIAL_TOOL_CMD_ListIssues, and then click New Child > Input Parameter.

    This adds a string input parameter to the Execute OS Command tool.

  5. Right-click String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Target ID Parm value cell, and then click TUTORIAL_PROP_OSCommandString (String).
  7. Double-click the Static Value value cell, and then type the absolute path to the GetIssues.exe file in your project.
  8. Click OK.
  9. To add the second input parameter to this tool, right-click TUTORIAL_TOOL_CMD_ListIssues, and then click New Child > Input Parameter.

    This adds a string input parameter to the Execute OS Command tool.

  10. Right-click String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  11. Double-click the Target ID Parm value cell, and then click TUTORIAL_PROP_ELE_Priority (SelectValue).
  12. Click OK.

    Your tool should look like:

    Tool: List Issues

Specifying the Get Raiser Tool

This tool will get the raiser of an issue:

  1. Right-click Tool Descriptors, and then click New Child > OS - Operating System > Execute OS Command.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_CMD_GetRaiser.
  3. Click OK.

    Your tool requires two input parameters:

  4. To add the first input parameter to this tool, right-click TUTORIAL_TOOL_CMD_GetRaiser, and then click New Child > Input Parameter.

    This adds a string input parameter to the Execute OS Command tool.

  5. Right-click String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Target ID Parm value cell, and then click TUTORIAL_PROP_OSCommandString (String).
  7. Double-click the Static Value value cell, and then type the absolute path to the GetIssueRaiser.exe file in your project.
  8. Click OK.
  9. To add the second input parameter to this tool, right-click TUTORIAL_TOOL_CMD_GetRaiser, and then click New Child > Input Parameter.

    This adds a string input parameter to the Execute OS Command tool.

  10. Right-click String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  11. Double-click the Target ID Parm value cell, and then click TUTORIAL_PROP_ELE_TicketNumber (Numeric).
  12. Click OK.
  13. To add an output parameter to this tool, right-click TUTORIAL_TOOL_CMD_GetRaiser, and then click New Child > Output Parameter

    This adds a string output parameter to the Execute OS Command tool.

  14. Right-click String Output Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  15. Double-click the Target ID Parm value cell, and then click TUTORIAL_PROP_ELE_Raiser (String).
  16. Double-click the To Output Dialog value cell, and click true.
  17. Click OK.

    Your tool should look like:

    Tool: Get Raiser

Specifying the Show Raiser Tool

The last tool you create will display the raiser of an issue. You can use the Open Modeled Dialog from the AWM function package:

  1. Right-click Tool Descriptors, and then click New Child > AWM > Open Modeled Dialog.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_AWM_DIA_ShowRaiser.
  3. Click OK.
  4. Right-click TUTORIAL_TOOL_AWM_DIA_ShowRaiser, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Dialog Type value cell, and then click Output Dialog.
  6. Double-click the Title value cell, and then type Issue Tracking System.
  7. Double-click the Description value cell, and then type Raiser of ticket &TUTORIAL_PROP_ELE_TicketNumber.
  8. Click OK.

    Your tool should look like:

    Tool: DIA Show Raiser
Parent topic: Creating the Model
Previous topic: Specifying the ID Definitions
Next topic: Specifying File Descriptors


Specifying File Descriptors

The issue tracking system requires three file descriptors to be modeled:

  • A file descriptor for the list of the first Application Explorer view level.
  • A file descriptor for the list of properties under the Issues by Priority tree view entry.
  • A file descriptor to return the list of issues.

File Descriptors Static Issue Filter List

  1. Right-click File Descriptors, and then click New Child > File Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_FD_StaticIssueFilterList.
  3. Click OK.
  4. Right-click TUTORIAL_FD_StaticIssueFilterList (Workspace_File, Unstructured), and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Prop Delimiter value cell, and then type ",".
  6. Double-click the Structure value cell, and then select Table.
  7. Double-click the Type value cell, and then select InputStream.
  8. Click OK.

    The file descriptor should look like:

    File Descriptor - StaticIssueFilterList

File Descriptors Static Issue Priority List

  1. Right-click File Descriptors, and then click New Child > File Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_FD_StaticIssuePriorityList.
  3. Click OK.
  4. Right-click TUTORIAL_FD_StaticIssuePriorityList (Workspace_File, Unstructured), and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Prop Delimiter value cell, and then type ",".
  6. Double-click the Structure value cell, and then click Table.
  7. Double-click the Type value cell, and then type InputStream.
  8. Click OK.

    The file descriptor should look like:

    File Descriptors - StaticIssuePriorityList

File Descriptors Issue List

  1. Right-click File Descriptors, and then click New Child > File Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_FD_IssueList.
  3. Click OK.
  4. Right-click TUTORIAL_FD_StaticIssuePriorityList (Workspace_File, Unstructured), and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Prop Delimiter value cell, and then type ";".
  6. Double-click the Structure value cell, and then click Table.
  7. Double-click the Type value cell, and then type Local_File.
  8. Click OK.

    The file descriptor should look like:

    File Descriptors - IssueList

Specifying the File Descriptors Table Structure

All three file descriptors are of type Table. You need to specify the structure of a file descriptor of type Table. To do this you need to add property relationships to the file descriptors. Drag and drop properties onto the file descriptors. You need to add the following properties to the file descriptors you have just created:

  1. In the Properties category, highlight TUTORIAL_PROP_ELE_EleType and TUTORIAL_PROP_STATIC_IssueFilter.
  2. Drag and drop onto the TUTORIAL_FD_StaticIssueFilterList file descriptor.

    This opens the Create Relationships dialog box:

    Create Relationships
  3. Click OK.

    The TUTORIAL_FD_StaticIssueFilterList file descriptor should look like this:

  4. Repeat steps 1 through 3 for the TUTORIAL_FD_StaticIssuePriorityList file descriptor. Drag and drop the following properties onto the file descriptor:
    • TUTORIAL_PROP_ELE_EleType
    • TUTORIAL_PROP_ELE_Priority

    The TUTORIAL_FD_StaticIssuePriorityList file descriptor should look like this:

  5. Repeat steps 1 through 3 for the TUTORIAL_FD_IssueList file descriptor. Drag and drop the following properties onto the file descriptor:
    • TUTORIAL_PROP_ELE_TicketNumber
    • TUTORIAL_PROP_ELE_Raiser
    • TUTORIAL_PROP_ELE_CreationDate
    • TUTORIAL_PROP_ELE_Priority
    • TUTORIAL_PROP_ELE_Description
    • TUTORIAL_PROP_ELE_Status
    • TUTORIAL_PROP_ELE_EleType

    The TUTORIAL_FD_IssueList file descriptor should look like this:

Specifying Associations Between Tools & File Descriptors

You need to specify the associations between your tools and the file descriptors:

  1. In the Tool Descriptors category, expand TUTORIAL_TOOL_AWM_CreateIssueFilterLevel, and then right-click File Output Parameter.
  2. Click Edit.

    This opens Edit Properties dialog box.

  3. Double-click the Target ID File value cell, and then click TUTORIAL_FD_StaticIssueFilterList.
  4. Click OK.
  5. In the Tool Descriptors category, expand TUTORIAL_TOOL_AWM_CreateStaticPriorityLevel, and then right-click File Output Parameter.
  6. Click Edit.

    This opens Edit Properties dialog box.

  7. Double-click the Target ID File value cell, and then click TUTORIAL_FD_StaticIssuePriorityList.
  8. Click OK.
  9. In the File Descriptors category folder, click TUTORIAL_FD_IssueList, and then drag the file descriptor and drop it on the TUTORIAL_TOOL_CMD_ListIssues tool descriptor.

    This displays the Create Relationships dialog box.

    Create Relationship: TUTORIAL_FD_IssueList and TUTORIAL_TOOL_CMD_ListIssues
  10. Click Output Parm.
  11. Click OK.
Parent topic: Creating the Model
Previous topic: Specifying Tool Descriptors
Next topic: Specifying the Action Descriptors


Specifying the Action Descriptors

You need to be able to call tools within your application. This is done by adding action descriptors. The issue tracking system requires five actions in total:

  1. An action to return the children at the application level - entries All Issues and Issues by Priority.
  2. An action to return the children of the entry All Issues or Issues by Priority.
  3. An action to return a list of issues filtered by the priority.
  4. An action to display a list of issues filtered by the priority in the Table Results view.
  5. An action to display the raiser of an issue.

To specify the action to generate the first level in the Application Explorer view:

  1. Right-click Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_CreateIssueFilterLevel.
  3. Click OK.
  4. Right-click TUTORIAL_ACT_CreateIssueFilterLevel, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Label value cell, and type Get Issue Filters.
  6. Click OK.
  7. Drag and drop the TUTORIAL_TOOL_AWM_CreateIssueFilterLevel tool onto the TUTORIAL_ACT_CreateIssueFilterLevel action descriptor.

    This opens the Create Relationships dialog box.

    Create Relationships - Action Tool
  8. Click OK.

To specify the action to produce the children of the first tree view level in the Application Explorer view:

  1. Right-click Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_CreateStaticPriorityLevel.
  3. Click OK.
  4. As we have two different tools to generate the children of a first level tree entry depending on whether it is the All Issues or the Issues by Priority entry, you need to associate two tools and specify respective enabling conditions.

    Drag and drop the TUTORIAL_TOOL_CMD_ListIssues, and TUTORIAL_TOOL_AWM_CreateStaticPriorityLevel tools onto the TUTORIAL_ACT_CreateStaticPriorityLevel action descriptor.

    This opens the Create Relationships dialog box.

  5. Click OK.

The TUTORIAL_TOOL_CMD_ListIssues tool must only be enabled when the property TUTORIAL_PROP_STATIC_IssueFilter contains the value All Issues. This can be achieved by specifying an enabling condition on the action for tool relationship. To do this:

  1. In the Action Descriptor category folder, expand the action TUTORIAL_ACT_CreateStaticPriorityLevel.
  2. Right-click TUTORIAL_TOOL_CMD_ListIssues, and then click New Child > Enabled Condition.
  3. Right-click Enabled Condition, and then click New Child > Simple Condition.
  4. Right-click Condition, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Target ID value cell, and then click TUTORIAL_PROP_STATIC_IssueFilter.
  6. Double-click the Value value cell, and type All Issues.
  7. Click OK.

If the action TUTORIAL_ACT_CreateStaticPriorityLevel is called for the All Issues entry in the tree view, the tool TUTORIAL_TOOL_CMD_ListIssues is called with the input value *. You can achieve this by specifying a parameter override:

  1. In the Action Descriptor category folder, expand the action TUTORIAL_ACT_CreateStaticPriorityLevel.
  2. Right-click TUTORIAL_TOOL_CMD_ListIssues, and then click New Child > Parameter Override.
  3. Right-click Parameter Override, and then click Edit.

    This opens the Edit Properties dialog box.

  4. Double-click the New Static Value value cell, and type *.
  5. Double-click the Parm to Override value cell, and click TUTORIAL_PROP_ELE_Priority.
  6. Click OK.

Create an enabling condition for the TUTORIAL_TOOL_AWM_CreateStaticPriorityLevel tool belonging to the TUTORIAL_ACT_CreateStaticPriorityLevel action descriptor in the same way. This time set the attribute operator of the simple condition to equals not:

  1. In the Action Descriptor category folder, expand the action TUTORIAL_ACT_CreateStaticPriorityLevel.
  2. Right-click TUTORIAL_TOOL_AWM_CreateStaticPriorityLevel, and then click New Child > Enabled Condition.
  3. Right-click Enabled Condition, and then click New Child > Simple Condition.
  4. Right-click Condition, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Operator value cell, and click Equals not.
  6. Double-click the Target ID value cell, and then click TUTORIAL_PROP_STATIC_IssueFilter.
  7. Double-click the Value value cell, and type All Issues.
  8. Click OK.

    You action descriptor TUTORIAL_ACT_CreateStaticPriorityLevel should look like:

Create another action and name it TUTORIAL_ACT_ListFilteredIssues:

  1. Right-click Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_ListFilteredIssues.
  3. Click OK.
  4. Drag and drop the TUTORIAL_TOOL_CMD_ListIssues tool onto the TUTORIAL_ACT_ListFilteredIssues action descriptor.

    This opens the Create Relationships dialog box.

  5. Click OK.

Create another action and name it TUTORIAL_ACT_ShowIssues. This is the action that displays a list of issues filtered by the priority in the Table Results view:

  1. Right-click Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_ShowIssues.
  3. Click OK.
  4. Drag and drop the TUTORIAL_TOOL_CMD_ListIssues tool onto the TUTORIAL_ACT_ShowIssues action descriptor.

    This opens the Create Relationships dialog box.

  5. Click OK.
  6. Right-click TUTORIAL_ACT_ShowIssues, and then click Edit.

    This opens the Edit Properties dialog box.

  7. Double-click the Label value cell, and type Show Issues in Table.
  8. Click OK.

Create the final action and name it TUTORIAL_ACT_ShowRaiser:

  1. Right-click Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_ShowRaiser.
  3. Click OK.
  4. Drag and drop the TUTORIAL_TOOL_CMD_GetRaiser, and TUTORIAL_TOOL_AWM_DIA_ShowRaiser tools onto the TUTORIAL_ACT_ShowRaiser action descriptor.

    This opens the Create Relationships dialog box.

  5. Click OK.
  6. Right-click TUTORIAL_ACT_ShowRaiser, and then click Edit.

    This opens the Edit Properties dialog box.

  7. Double-click the Label value cell, and type Show Raiser.
  8. Click OK.

    Your action descriptors should look like:

    All Action Descriptors
Parent topic: Creating the Model
Previous topic: Specifying File Descriptors
Next topic: Specifying the Element List Structure


Specifying the Element List Structure

Element list structures describe the structure of AWM element lists in the Table Results view. In the issue tracking system model, only one element list structure is required. To create this:

  1. Right-click the Elementlist Structures category folder, and then click New Child > Element List Structure.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ELELIST_Issues.
  3. Click OK.

You now need to associate the columns to be displayed in the Table Results view to the newly created element list structure. To do this you need to select the properties that represent the columns in the element list structure:

  1. In the Properties category folder, highlight the following properties:
    1. TUTORIAL_PROP_ELE_TicketNumber
    2. TUTORIAL_PROP_ELE_CreationDate
    3. TUTORIAL_PROP_ELE_Priority
    4. TUTORIAL_PROP_ELE_Description
    5. TUTORIAL_PROP_ELE_Status
    6. TUTORIAL_PROP_ELE_EleType
  2. Drag and drop the properties onto the TUTORIAL_ELELIST_Issues.

    This opens the Create Releationships dialog box.

  3. Click OK.
  4. In the Elementlist Structures category folder, expand TUTORIAL_ELELIST_Issues.
  5. Right-click TUTORIAL_PROP_ELE_EleType, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Visible value cell, and then click false.
    Note: An element list structure always requires an associated element type property, but you do not want it to be displayed as a column in the Table Results view.
  7. Click OK.

You now need to associate this new element list structure with the TUTORIAL_ACT_ShowIssues action:

  1. In the Action Descriptors category folder, right-click TUTORIAL_ACT_ShowIssues, and then click Edit.

    This opens the Edit Properties dialog box.

  2. Double-click the Table Structure value cell, and then click TUTORIAL_ELELIST_Issues.
  3. Click OK.
  4. Ensure your model is saved, click File > Save.
Parent topic: Creating the Model
Previous topic: Specifying the Action Descriptors
Next topic: Associating the Action Descriptors


Associating the Action Descriptors

You need to associate all action descriptors to the correct model objects so they are displayed in the Application Explorer view.

Specifying a Root Containers Action

The TUTORIAL_ACT_CreateIssueFilterLevel action returns the children at the application level:

  1. Right-click Application Options 1.0, and then click Edit.

    This opens the Edit Properties dialog box.

  2. Double-click the Root Containers Action value cell, and then click TUTORIAL_ACT_CreateIssueFilterLevel.
  3. Click OK.

This action will now be executed when the Issue by Priority node in the Application Explorer view is expanded.

Specifying the Get Children Action for TUTORIAL_ELE_IssueFilter

You need to add a Get Children Action to the TUTORIAL_ELE_IssueFilter element types:

  1. In the Element Types category folder, right-click TUTORIAL_ELE_IssueFilter.
  2. Click New Child > Get Children Action.
  3. Right-click Get Children Action, and then click Edit.

    This opens the Edit Properties dialog box.

  4. Double-click the Target ID value cell, and then click TUTORIAL_ACT_CreateStaticPriorityLevel.
  5. Click OK.

Specifying the Get Children Action for TUTORIAL_ELE_PriorityFilter

You need to add a Get Children Action to the TUTORIAL_ELE_IssueFilter element types:

  1. In the Element Types category folder, right-click TUTORIAL_ELE_PriorityFilter.
  2. Click New Child > Get Children Action.
  3. Right-click Get Children Action, and then click Edit.

    This opens the Edit Properties dialog box.

  4. Double-click the Target ID value cell, and then click TUTORIAL_ACT_ListFilteredIssues.
  5. Click OK.

Specifying the Action for TUTORIAL_ELE_IssueFilter and TUTORIAL_ELE_PriorityFilter

You need to add the action TUTORIAL_ACT_ShowIssues to both the TUTORIAL_ELE_IssueFilter and TUTORIAL_ELE_PriorityFilter element types:

  1. In the Element Types category folder, right-click TUTORIAL_ELE_IssueFilter.
  2. Click New Child > Action.
  3. Right-click Action, and then click Edit.

    This opens the Edit Properties dialog box.

  4. Double-click the Target ID value cell, and then click TUTORIAL_ACT_ShowIssues.
  5. Click OK.
  6. Right-click TUTORIAL_ELE_PriorityFilter.
  7. Click New Child > Action.
  8. Right-click Action, and then click Edit.

    This opens the Edit Properties dialog box.

  9. Double-click the Target ID value cell, and then click TUTORIAL_ACT_ShowIssues.
  10. Click OK.

Specifying the Action for TUTORIAL_ELE_Issue

You need to add the TUTORIAL_ACT_ShowRaiser action to the TUTORIAL_ELE_Issue element type:

  1. In the Element Types category folder, right-click TUTORIAL_ELE_Issue.
  2. Click New Child > Action.
  3. Right-click Action, and then click Edit.

    This opens the Edit Properties dialog box.

  4. Double-click the Target ID value cell, and then click TUTORIAL_ACT_ShowRaiser.
  5. Click OK.
Parent topic: Creating the Model
Previous topic: Specifying the Element List Structure


Validating the Model

Now that you have created the issue tracking system model you can validate it. This reports any errors or warnings relating to its structure and relationships. Click Validate the current configuration Validate the current configuration, if there are any errors or warnings it displays a Validation Problems dialog box. See Validating an AWM Model for more information.

Parent topic: Tutorial: Creating an AWM Model with AWM Element Types
Previous topic: Creating the Model
Next topic: Running and Testing the Model


Running and Testing the Model

When you first run and test your AWM model you should start Enterprise Developer for Eclipse in debug mode. To do this:

  1. Right-click the shortcut for Enterprise Developer for Eclipse.
  2. Click Properties.

    This opens the Enterprise Developer for Eclipse Properties dialog box.

  3. In the Target field, at the end of the existing text, type -debug.

    The field content should look like this:

    "C:\Users\Public\Micro Focus\Enterprise Developer\eclipse\eclipse.exe" -debug

  4. Click OK.
  5. Restart Enterprise Developer for Eclipse.
  6. In the Application Explorer view, click Add System(s).

    This opens the Add System(s) dialog box.

  7. Click Custom System, and then click OK.

    This opens the New Custom AWM System dialog box.

  8. In the System Name field, type Issue Tracker.
  9. Click Next.
  10. In the Location field, click Browse and navigate to the IssueTracking.model.

    The Application Name field is automatically populated with text derived from the application name.

  11. Click Finish.

    This adds the Issue Tracker custom system to the Application Explorer view.

  12. In the Application Explorer view, expand the Issue Tracker custom system.
    Issue Tracker Custom System
  13. Right-click IssueTracking, and then click Load Application.

Expand the IssueTracking application folder. Below are the All Issues and Issues by Priority groups. Click either group to display its children. In the case of the All Issues group it is a list of the ticket numbers with the description next to it. For the Issues by Priority it has children folders for the priorities and within these are the appropriate tickets.

On individual tickets you can right-click, and then click Show Raiser. This opens an Issue Tracking System dialog box containing the ticket raisers name.

If you right-click on a group of tickets, and then click Show Issues in Table it displays the group of tickets and their details in the Table Results view.

Parent topic: Tutorial: Creating an AWM Model with AWM Element Types
Previous topic: Validating the Model


Tutorial: Creating an AWM Model with AWM Linked Element Types

This tutorial walks you through the process of creating an AWM model that uses AWM linked element types from the Eclipse function package.

Prerequisites

To complete this tutorial, you need Enterprise Developer for Eclipse installed.

Overview

The Application Workflow Manager (AWM) is a framework based on the Eclipse Modeling Framework (EMF). AWM enables you to develop models to implement the application development workflow of your company. In this tutorial you learn how to integrate Eclipse resources into an AWM model. In this case, it takes projects, folders, and files from your workspace and displays them in the customs systems application folder.

  1. Creating the Project
  2. Creating the Model
  3. Validating the Model
  4. Running and Testing the Model
Parent topic: Workflow Manager Modeling Tutorials


Creating the Project

Start by creating a COBOL project:

  1. In the Application Explorer view, and then click File > New > Other.

    This opens the New dialog box.

  2. Click Micro Focus COBOL > COBOL Project.
  3. Click Next.
  4. In the Project name field, type EclipseSample.
  5. Click Finish.
Parent topic: Tutorial: Creating an AWM Model with AWM Linked Element Types
Next topic: Creating the Model


Creating the Model

Create a model in a new folder:

  1. Right-click the EclipseSample project, and then click New > Folder > Folder.

    This opens the New Folder dialog box.

  2. in the Folder name field, type model.
  3. Click Finish.
  4. Click the model folder, and then click File > New > Other.

    This opens the New dialog box.

  5. Click AWM > AWM Model.
  6. Click Next.
  7. In the File name field, type EclipseTutorial.model.
  8. Click Finish.

    This opens the model in the AWM model editor.

  1. Specifying Application Options
  2. Specifying the Function Packages
  3. Specifying the Element Types
  4. Specifying the Properties
  5. Specifying the Tools Descriptors
  6. Specifying the Action Descriptors
  7. Associating the Action Descriptors
Parent topic: Tutorial: Creating an AWM Model with AWM Linked Element Types
Previous topic: Creating the Project
Next topic: Validating the Model


Specifying Application Options

Global settings that apply to the complete application can be defined under the application options.

Start by specifying the version number:

  1. Expand paltform > Document Root > AWM Model.
  2. Right-click Application Options, and then click Edit.

    This opens the Edit Properties dialog box.

  3. Double-click the Version value cell, and then type 1.0.
  4. Click OK.
Note: An attribute value of an AWM object is stored in the Properties view, not the AWM model editor.
Parent topic: Creating the Model
Next topic: Specifying the Function Packages


Specifying the Function Packages

To specify the function packages that you will use in the model:

  1. Right-click the Function Packages category folder.
  2. Click New Child > AWM.

    This adds the AWM function package as a child of the Function Packages category folder.

  3. Right-click the Function Packages category folder.
  4. Click New Child > Eclipse.

    This adds the Eclipse function package as a child of the Function Packages category folder.

Parent topic: Creating the Model
Previous topic: Specifying Application Options
Next topic: Specifying the Element Types


Specifying the Element Types

The Eclipse function package provides support for three different linked Eclipse element types:

  • Eclipse project
  • Eclipse folder
  • Eclipse file

The resource type of an Eclipse resource is identified by its match name. You need to specify all three linked element types.

Specifying an Eclipse Project

To specify an Eclipse project element type:

  1. Right-click the Element Types category folder, and then click New Child > Eclipse > Eclipse Resource.

    This opens the Enter Object IDs dialog box.

  2. In the New ID field, next to the Eclipse Resource field, type TUTORIAL_ELE_EclipseProject.
  3. In the New ID field, next to the Eclipse Resource Identifier field, type TUTORIAL_PROP_ResourceID.
  4. In the New ID field, next to the Eclipse Resource ID field, type TUTORIAL_IDDEF_EclipseResource.
  5. Click OK.

    An entry in the ID Definitions, Element Types, and Properties category folders.

  6. In the Element Types category folder, right-click TUTORIAL_ELE_EclipseProject.
  7. Click Edit.

    This opens the Edit Properties dialog box.

  8. Double-click the Matchname value cell, and then type ECLIPSE_PROJECT.
  9. Click OK.
  10. You need to add the key property TUTORIAL_PROP_ResourceID as a property reference to the newly created linked element type TUTORIAL_ELE_EclipseProject:

    Right-click TUTORIAL_ELE_EclipseProject, and then click New Child > Property.

    This adds the Has Property as a child to the TUTORIAL_ELE_EclipseProject element type.

  11. Right-click Has Property, and then click Edit.

    This opens the Edit Properties dialog box.

  12. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ResourceID.
  13. Click OK.
  14. You can now create the linked element type Eclipse folder.

    Right-click the Element Types category folder, and then click New Child > Eclipse > Eclipse Resource.

    This opens the Enter Object ID dialog box.

  15. In the New ID field, type TUTORIAL_ELE_EclipseFolder.
  16. Click OK.

    This adds the new linked Eclipse resource in the Elements Types category folder.

  17. Right-click TUTORIAL_ELE_EclipseFolder, and then click Edit.

    This opens the Edit Properties dialog box.

  18. Double-click the Matchname value cell, and type ECLIPSE_FOLDER.
  19. Click OK.
  20. Right-click TUTORIAL_ELE_EclipseFolder, and then click New Child > Property.
  21. Right-click Has Property, and then click Edit.

    This opens the Edit Properties dialog box.

  22. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ResourceID.
  23. Click OK.
  24. Right-click the Element Types category folder, and then click New Child > Eclipse > Eclipse Resource.

    This opens the Enter Object ID dialog box.

  25. In the New ID field, type TUTORIAL_ELE_EclipseFile.
  26. Click OK.
  27. Right-click TUTORIAL_ELE_EclipseFile, and then click Edit.

    This opens the Edit Properties dialog box.

  28. Double-click the Matchname value cell, and type ECLIPSE_FILE.
  29. Click OK.
  30. Right-click TUTORIAL_ELE_EclipseFile, and then click New Child > Property.
  31. Right-click Has Property, and then click Edit.

    This opens the Edit Properties dialog box.

  32. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ResourceID.
  33. Click OK.

    Your element types should look like:

    Eclipse Element Types
Parent topic: Creating the Model
Previous topic: Specifying the Function Packages
Next topic: Specifying the Properties


Specifying the Properties

The Eclipse function package provides comprehensive support for the properties of an Eclipse resource. The properties are available to you as linked properties. To add a linked property to the model right-click the Properties category folder, and then click New Child > Eclipse > Resource Properties and choose one of the resources available. In this tutorial you only need to add the resource properties Name and Has Children:

  1. Right-click the Properties category folder, and then click New Child > Eclipse > Resource Properties > Name.

    This opens the Enter Object ID dialog box.

  2. In the New ID file, type TUTORIAL_PROP_EclipseResName.
  3. Click OK.
  4. Right-click the Properties category folder, and then click New Child > Eclipse > Resource Properties > Has Children.

    This opens the Enter Object ID dialog box.

  5. In the New ID filed, type TUTORIAL_PROP_ResHasChildren.
  6. Click OK.
  7. While pressing Ctrl, click TUTORIAL_PROP_EclipseResName and TUTORIAL_PROP_ResHasChildren
  8. Drag and drop the selection onto TUTORIAL_ELE_EclipseProject.

    This opens the Create Relationships dialog box.

    Create Relationships
  9. Click OK.
  10. Repeat steps 7 through 9 twice, replacing the target of the drag and drop action with TUTORIAL_ELE_EclipseFolder on the first occasion and TUTORIAL_ELE_EclipseFile on the second.
  11. You now need to create four more properties:

    Right-click the Properties category folder, and then click New Child > Properties.

    This opens the Enter Object ID dialog box.

  12. In the New ID field, type TUTORIAL_PROP_EleType.
  13. Click OK.
  14. Create three more properties, repeat steps 11 through 13 replacing the New ID filed with the following names:
    • TUTORIAL_PROP_ProjectNature
    • TUTORIAL_PROP_ResourceFilter
    • TUTORIAL_PROP_NewName
    Note: All four properties are of type String.

    For each of the properties you have just created specify a meaningful Label value. During runtime the Label value is used, for example, as a title in the Table Results view or as a label in an AWM dialog box. For example:

    Property | Label
    TUTORIAL_PROP_EleType | Label Type
    TUTORIAL_PROP_ProjectNature | Project Nature
    TUTORIAL_PROP_ResourceFilter | Filter
    TUTORIAL_PROP_NewName | New Name
  15. Right-click TUTORIAL_PROP_EleType, and then click Edit.

    This opens the Edit Properties dialog box.

  16. Double-click the Label value cell, and then type the label name of your choice.
  17. Click OK.
  18. Repeat steps 15 through 17 for the following properties adding a suitable label name of your choice each time:
    • TUTORIAL_PROP_ProjectNature
    • TUTORIAL_PROP_ResourceFilter
    • TUTORIAL_PROP_NewName
    Note: You must always specify one property in your model which is used to return the match name specifying which element type it is. This is specified by the property Special Property, and in this case, it will have an Element_Type value:
  19. Right-click TUTORIAL_PROP_EleType, and then click Edit.

    This opens the Edit Properties dialog box.

  20. Double-click the Special Property value cell, and then click Element_Type.
  21. Click OK.
  22. Right-click TUTORIAL_PROP_NewName, and then click Edit.

    This opens the Edit Properties dialog box.

  23. Double-click the Label value cell, and then type New Name.
  24. Click OK.
Parent topic: Creating the Model
Previous topic: Specifying the Element Types
Next topic: Specifying the Tools Descriptors


Specifying the Tools Descriptors

You need to specify four tools for this tutorial:

  • A tool to get all projects from the Micro Focus Eclipse nature.
  • A tool to get the children of an Eclipse resource.
  • A tool to rename an Eclipse resource.
  • Dialog tool to accept a new name for an Eclipse resource.

Specifying a Tool to Get All Projects

To specify a tool to get all projects:

  1. Right-click the Tool Descriptors category folder, and then click New Child > Eclipse > Get Eclipse Projects.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_GetProjects.
  3. Click OK.

    This creates a tool with a String Input Parameter and File Output Parameter.

  4. Right-click String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Target ID Parm value cell, and then click TUTORIAL_PROP_ProjectNature.
  6. Double-click the Static Value value cell, and then type .*com.microfocus.eclipse.*
  7. Click OK.

The Get Eclipse Projects tool returns a file descriptor with two properties:

  • Eclipse resource ID.
  • Match name to identify the element type.

See Get Eclipse Projects for more information

You need to specify an appropriate file descriptor for the output:

  1. Right-click the File Descriptors category folder, and then click New Child > File Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_FD_EclipseResources.
  3. Click OK.
  4. Right-click TUTORIAL_FD_EclipseResources, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Prop Delimiter value cell, and then type "<!>".
    Note: This attribute defines the delimiter by which the Eclipse resource names are separated from the match name in the file. You should chose a property delimiter which does not appear in any of your Eclipse resource names including the project path.
  6. Double-click the Structure value cell, and then click Table.
  7. Double-click the Type value cell, and then click InputStream.
  8. Click OK.

    You need to add two Has Property to the file descriptor:

  9. Right-click TUTORIAL_FD_EclipseResource, and then click New Child > Property.
  10. Right-click Has Property, and then click Edit.

    This opens the Edit Properties dialog box.

  11. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ResourceID.
  12. Click OK.
  13. Right-click TUTORIAL_FD_EclipseResource, and then click New Child > Property.
  14. Right-click Has Property, and then click Edit.

    This opens the Edit Properties dialog box.

  15. Double-click the Target ID value cell, and then click TUTORIAL_PROP_EleType.
  16. Click OK.
  17. For the TUTORIAL_TOOL_GetProjects tool, right-click File Output Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  18. Double-click Target ID File, and then click TUTORIAL_FD_EclipseResources.
  19. Click OK.

Specifying a Tool to Get Children of an Eclipse Resource

To specify a tool to get children of an Eclipse resource:

  1. Right-click the Tool Descriptors category folder, and then click New Child > Eclipse > Get Resource Children.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_GetResChildren.
  3. Click OK.

    This creates a tool with two String Input Parameter and a File Output Parameter.

  4. Right-click the first String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Target ID Parm value cell, then click TUTORIAL_PROP_ResourceID.
  6. Click OK.
  7. Right-click the second String Input Parameter, and the click Edit.

    This opens the Edit Properties dialog box.

  8. Double-click the Target ID Parm value cell, then click TUTORIAL_PROP_ResourceFilter.
  9. Click OK.
  10. Right-click the File Output Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  11. Double-click the Target ID File value cell, and then click TUTORIAL_FD_EclipseResources.

    The structure of the output file is the same as the output file of the first tool. This enables you to use the same file descriptor for both tools.

  12. Click OK.

Specifying a Tool to Rename an Eclipse Resource

To specify a tool to rename an Eclipse resource:

  1. Right-click the Tool Descriptors category folder, and then click New Child > Eclipse > Rename Resource.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_RenameRes.
  3. Click OK.

    This creates a tool with two String Input Parameter children.

  4. Right-click the first String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Target ID Parm value cell, then click TUTORIAL_PROP_ResourceID.
  6. Click OK.
  7. Right-click the second String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  8. Double-click the Target ID Parm value cell, then click TUTORIAL_PROP_NewName.
  9. Double-click the Parameter From value cell, and then click Previous_Tool.
  10. Click OK.

Specifying a Dialog Tool to Accept a New Name for an Eclipse Resource

To specify a dialog tool to accept a new name for an Eclipse resource:

  1. Right-click the Tool Descriptors category folder, and then click New Child > AWM > Open Modeled Dialog.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_TOOL_DIA_RenameInput.
  3. Click OK.
  4. Right-click TUTORIAL_TOOL_DIA_RenameInput, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Description value cell, and then type Rename resource &TUTORIAL_PROP_ResourceID..
  6. Double-click the Title value cell, and then type Eclipse Tutorial.
  7. Right-click TUTORIAL_TOOL_DIA_RenameInput, and then click New Child > Input Parameter.
  8. Double-click the Target ID Parm value cell, and then click TUTORIAL_PROP_NewName.
  9. Click OK.
  10. You can now preview the dialog box that the Open Modeled Dialog tool creates:

    Right-click TUTORIAL_TOOL_DIA_RenameInput, and then click Preview Dialog.

    This opens a preview of the Eclipse Tutorial dialog box.

    Eclipse Tutorial Dialog Box
  11. Click Cancel.

    This closes the preview dialog box.

    Your four tool descriptors should look like:

    Tool Descriptors
Parent topic: Creating the Model
Previous topic: Specifying the Properties
Next topic: Specifying the Action Descriptors


Specifying the Action Descriptors

AWM tools require action descriptors to enable the tools to be called within an application, for example, as a context menu command, or as a get children action.

This tutorial requires you to model three action descriptors:

  • An action descriptor to get Eclipse projects.
  • An action descriptor to get the children of an Eclipse resource.
  • An action to rename an Eclipse resource.

Specifying an Action Descriptor to Get Eclipse Projects

To specify an action descriptor to get Eclipse projects:

  1. Right-click the Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_GetProjects.
  3. Click OK.
  4. Right-click TUTORIAL_ACT_GetProjects, and then click New Child > Tool.

    This adds a tool with a missing Target ID.

  5. Right-click Tool, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Target ID value cell, and then click TUTORIAL_TOOL_GetProjects.
  7. Click OK.

Specifying an Action Descriptor to Get the Children of an Eclipse Resource

To specify an action descriptor to get the children of an Eclipse resource:

  1. Right-click the Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_GetResChildren.
  3. Click OK.
  4. Right-click TUTORIAL_ACT_GetResChildren, and then click New Child > Tool.

    This adds a tool with a missing Target ID.

  5. Right-click Tool, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Target ID value cell, and then click TUTORIAL_TOOL_GetResChildren.
  7. Click OK.

Specifying an Action Descriptor to Rename an Eclipse Resource

To specify an action descriptor to rename an Eclipse resource:

  1. Right-click the Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type TUTORIAL_ACT_RenameRes.
  3. Click OK.
  4. Right-click TUTORIAL_ACT_RenameRes, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Label value cell, and then type Rename.
  6. Click OK.
  7. Right-click TUTORIAL_ACT_GetResChildren, and then click New Child > Tool.

    This adds a tool with a missing Target ID.

  8. Right-click Tool, and then click Edit.

    This opens the Edit Properties dialog box.

  9. Double-click the Target ID value cell, and then click TUTORIAL_TOOL_DIA_RenameInput.
  10. Click OK.
  11. Right-click TUTORIAL_ACT_GetResChildren, and then click New Child > Tool.

    This adds a tool with a missing Target ID.

  12. Right-click Tool, and then click Edit.

    This opens the Edit Properties dialog box.

  13. Double-click the Target ID value cell, and then click TUTORIAL_TOOL_RenameRes.
  14. Click OK.

    Your action descriptors should look like:

    Action Descriptors

    You only need to make the associations for the new actions.

  15. Right-click Application Options, and then click Edit.

    This opens the Edit Properties dialog box.

  16. Double-click the Root Containers Action value cell, and then click TUTORIAL_ACT_GetProjects.
  17. Click OK.
  18. In the Element Types category folder, right-click TUTORIAL_ELE_EclipseProject, and then click New Child > Get Children Action.
  19. Right-click Get Children Action, and then click Edit.

    This opens the Edit Properties dialog box.

  20. Double-click the Target ID value cell, and then click TUTORIAL_ACT_GetResChildren.
  21. Click OK.
  22. Right-click TUTORIAL_ELE_EclipseFolder, and then click New Child > Get Children Action.
  23. Right-click Get Children Action, and then click Edit.

    This opens the Edit Properties dialog box.

  24. Double-click the Target ID value cell, and then click TUTORIAL_ACT_GetResChildren.
  25. Click OK.
  26. We want an Eclipse resource (project or folder) to be displayed as expandable only when it actually has children. You can achieve this by specifying an enabling condition depending on the linked property TUTORIAL_PROP_ResHasChildren to an element type's Get Children Action. To do this:

    In the Element Types category folder, expand TUTORIAL_ELE_EclipseProject.

  27. Right-click TUTORIAL_ACT_GetResChildren, and then click New Child > Enable Condition.
  28. Right-click Enable Condition, and then click New Child > Simple Condition.
  29. Right-click Simple Condition, and then click Edit.

    This opens the Edit Properties dialog box.

  30. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ResHasChildren.
  31. Double-click the Value value cell, and then type true.
  32. Click OK.
  33. In the Element Types category folder, expand TUTORIAL_ELE_EclipseFolder.
  34. Right-click TUTORIAL_ACT_GetResChildren, and then click New Child > Enable Condition.
  35. Right-click Enable Condition, and then click New Child > Simple Condition.
  36. Right-click Simple Condition, and then click Edit.

    This opens the Edit Properties dialog box.

  37. Double-click the Target ID value cell, and then click TUTORIAL_PROP_ResHasChildren.
  38. Double-click the Value value cell, and then type true.
  39. Click OK.
Parent topic: Creating the Model
Previous topic: Specifying the Tools Descriptors
Next topic: Associating the Action Descriptors


Associating the Action Descriptors

You need to associate all action descriptors to the correct model objects so they are displayed in the Application Explorer view .

Associating TUTORIAL_ACT_RenameRes with TUTORIAL_ELE_EclipseFolder

You need to add the TUTORIAL_ACT_RenameRes to the TUTORIAL_ELE_EclipseFolder element type:

  1. In the Elements Type folder, right-click TUTORIAL_ELE_EclipseFolder, and then click New Child > Action.
  2. Right-click Action, and then click Edit

    This opens the Edit Properties dialog box.

  3. Double-click the Target ID value cell, and then click TUTORIAL_ACT_RenameRes.
  4. Double-click the Label value cell, and then type Rename folder.
  5. Click OK.

Associating TUTORIAL_ACT_RenameRes with TUTORIAL_ELE_EclipseFile

You need to add the TUTORIAL_ACT_RenameRes to the TUTORIAL_ELE_EclipseFile element type:

  1. In the Elements Type folder, right-click TUTORIAL_ELE_EclipseFile, and then click New Child > Action.
  2. Right-click Action, and then click Edit.
  3. This opens the Edit Properties dialog box.
  4. Double-click the Target ID value cell, and then click TUTORIAL_ACT_RenameRes.
  5. Double-click the Label value cell, and then type Rename file.
  6. Click OK.
Parent topic: Creating the Model
Previous topic: Specifying the Action Descriptors


Validating the Model

Now that you have created your model to manipulate Eclipse resources you can validate it. This reports any errors or warnings relating to its structure and relationships. Click Validate the current configuration Validate the current configuration, if there are any errors or warnings it displays a Validation Problems dialog box. See Validating an AWM Model for more information.
Parent topic: Tutorial: Creating an AWM Model with AWM Linked Element Types
Previous topic: Creating the Model
Next topic: Running and Testing the Model


Running and Testing the Model

When you first run and test your AWM model you should start Enterprise Developer for Eclipse in debug mode. To do this:

  1. Right-click the shortcut for Enterprise Developer for Eclipse.
  2. Click Properties.

    This opens the Enterprise Developer for Eclipse Properties dialog box.

  3. In the Target field, at the end of the existing text, type -debug.

    The field content should look like this:

    "C:\Users\Public\Micro Focus\Enterprise Developer\eclipse\eclipse.exe" -debug

  4. Click OK.
  5. Restart Enterprise Developer for Eclipse.
  6. In the Application Explorer view, click Add System(s).

    This opens the Add System(s) dialog box.

  7. Click Custom System, and then click OK.

    This opens the New Custom AWM System dialog box.

  8. In the System Name field, type Tutorial System.
  9. Click Next.
  10. In the Model Location field, click Browse and navigate to the EclipseTutorial.model.

    The Application Name field is automatically populated with text derived from the application name.

  11. Click Finish.

    This adds the Tutorial System custom system to the Application Explorer view.

  12. In the Application Explorer view, expand the Tutorial System custom system.
    Issue Tracker Custom System
  13. Right-click EclipseTutorial, and then click Load Application.

A list of project folders is displayed under the EclipseTutorial application folder. These project folders mirror the content of the workspace under the default system. If there are no projects in the default system folder then create a test project along with subfolders and files.

Right-click on a resources in the EclipseTutorial application folder, and then click new context menu item Rename resource. This opens the Eclipse Tutorial dialog box.

Parent topic: Tutorial: Creating an AWM Model with AWM Linked Element Types
Previous topic: Validating the Model


Tutorial: Adding a New Action to an Existing AWM Model

This tutorial walks you through the process of adding a new context menu to an existing AWM model. In this case, you will modify the Enterprise Developer project's model.

Prerequisites

To complete this tutorial, you need Enterprise Developer for Eclipse installed.

Overview

You will extend the functionality of an existing model without requiring any Java programming skills. You will add an action to the Eclipse file linked element type. This action enables you to associate a problem number with a file.

  1. Creating the Project
  2. Creating the Model
  3. Validation the Model
  4. Running and Testing the Model
Parent topic: Workflow Manager Modeling Tutorials


Creating the Project

Start by creating a COBOL project:

  1. Launch Enterprise Developer. Specify a path for the Eclipse workspace when prompted.

    If this is the first time you start Eclipse, the IDE displays the Eclipse Welcome page. Click Open Team Developer Perspective which is the default perspective in Enterprise Developer.

    If the IDE does not start in the Team Developer perspective, click Window > Perspective > Open Perspective > Other, click Team Developer (default), and then click OK.
  2. In the Team Developer perspective, click File > New > Other.

    This opens the New dialog box.

  3. Click Micro Focus COBOL > COBOL Project.
  4. Click Next.

    This opens the New COBOL Project dialog box.

  5. In the Project name field, type ActionExample.
  6. Click Finish.
Parent topic: Tutorial: Adding a New Action to an Existing AWM Model
Next topic: Creating the Model


Creating the Model

To create a model file in your project, first create a new folder for it to go in:

  1. In the Project Explorer, right-click the ActionExample project.
  2. Click New > Folder.

    This opens the New Folder dialog box.

  3. In the Folder name field, type model.
  4. Click Finish.
  5. To view this new folder:
    1. Click View Menu View Menu, and then click Filters and Customization.

      This opens the Filters and Customization dialog box.

    2. In the Filters tab, uncheck Empty folders outside categories.
    3. Click OK.
  6. Expand the InternalTDProject project.
  7. Right-click IntegratedEDModel.model, and then click Copy.
    Note: If the IntegratedEDModel.model is not present in the InternalTDProject folder, then in Application Explorer view, right-click Enterprise Developer Projects folder under the Enterprise Developer system, and then click Load Application.
  8. In the ActionExample project, right-click the model folder, and then click Paste.
  9. Right-click IntegratedEDModel.model, and then click Rename.

    This opens the Rename Resource dialog box.

  10. In the New name field, type CustomizedIntegratedEDModel.model.
  11. Click OK.
  12. Right-click in the Application Explorer view, and then click Add System(s).

    This opens the Add System(s) dialog box.

  13. Click Custom System.
  14. Click OK.

    This opens the Custom AWM System dialog box.

  15. In the System Name field, type Action Example.
  16. Click Next.
  17. Next to the Location field, click Browse and navigate to the CustomizedIntegratedEDModel.model, and then click OK.

    The Application Name field is automatically populated with text derived from the application name.

  18. Click Finish.
  19. Expand the new custom system.
  20. Right-click the CustomizedIntegratedEDModel application, and then click Open Model.
  1. Creating a Property to Store a Problem Number
  2. Associating the Problem Number with an Eclipse File
  3. Specifying a Tool to Enable Problem Number Entry
  4. Specifying an Action to Call the Tool
Parent topic: Tutorial: Adding a New Action to an Existing AWM Model
Previous topic: Creating the Project
Next topic: Validation the Model


Creating a Property to Store a Problem Number

You need to add a property that will enable you to store a problem number:

  1. Expand platform > Document Root > AWM Model.
  2. Right-click the Properties category folder, and then click New Child > Property.

    This opens the Enter Object ID dialog box.

  3. In the New ID field, type OFFL_PROP_CONT_ProblemNumber.
  4. Click OK.
  5. You need to specify a label for the property. The label is used during runtime, for example, to be displayed in an AWM dialog box.

    Right-click OFFL_PROP_CONT_ProblemNumber, and then click Edit.

    This opens the Edit Properties dialog box.

  6. Double-click the Label value cell, and then type Problem Number.
  7. Click OK.
Parent topic: Creating the Model
Next topic: Associating the Problem Number with an Eclipse File


Associating the Problem Number with an Eclipse File

The problem number property needs to be associated with an Eclipse file. To do this you need to specify it as a property of this element type:

  1. Expand the Element Types category folder.
  2. Right-click OFFL_ELE_Eclipse_File, and then click New Child > Property.

    This adds a Has Property to the element type OFFL_ELE_Eclipse_File.

  3. Right-click Has Property, and then click Edit.

    This opens the Edit Properties dialog box.

  4. Double-click the Target ID value cell, and then select OFFL_PROP_CONT_ProblemNumber.
  5. Click OK.
Parent topic: Creating the Model
Previous topic: Creating a Property to Store a Problem Number
Next topic: Specifying a Tool to Enable Problem Number Entry


Specifying a Tool to Enable Problem Number Entry

You need to specify a tool which will enable you to enter a problem number which can then be associated with an Eclipse file. You can do this by specifying a dialog box where you can enter the problem number:

  1. Right-click the Tool Descriptors category folder, and then click New Child > AWM > Open Modeled Dialog.

    This opens the Enter Obect ID dialog box.

  2. In the New ID field, type OFFL_TOOL_AWM_Dialog_GetProblemNumber.
  3. Click OK.
  4. Right-click OFFL_TOOL_AWM_Dialog_GetProblemNumber, and the click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Description value cell, and then type Associate problem number with &OFFL_PROP_ECLIPSE_Name.
  6. Double-click the Title value cell, and then type Problem Number Dialog.
  7. Double-click the Resource Processing value cell, and then select UPDATE.
  8. Click OK.
  9. The dialog box should have the problem number as an input field.

    Right-click OFFL_TOOL_AWM_Dialog_GetProblemNumber, and then click New Child > Input Parameter.

  10. Right-click String Input Parameter, and then click Edit.

    This opens the Edit Properties dialog box.

  11. Double-click the Target ID Parm field, and then select OFFL_PROP_CONT_ProblemNumber.
  12. Click OK.
  13. You can now preview the dialog box that the Open Modeled Dialog tool creates:

    Right-click OFFL_TOOL_AWM_Dialog_GetProblemNumber, and then click Preview Dialog.

    This opens a preview of the Problem Number dialog box. It should look like:

    Problem Number Dialog Box
  14. To close the dialog box, click Cancel.
Parent topic: Creating the Model
Previous topic: Associating the Problem Number with an Eclipse File
Next topic: Specifying an Action to Call the Tool


Specifying an Action to Call the Tool

You need to specify an action which calls the newly created tool:

  1. Right-click the Action Descriptors category folder, and then click New Child > Action Descriptor.

    This opens the Enter Object ID dialog box.

  2. In the New ID field, type OFFL_ACT_CONT_AssociateProblemNumber.
  3. Click OK.
  4. Right-click OFFL_ACT_CONT_AssociateProblemNumber, and then click Edit.

    This opens the Edit Properties dialog box.

  5. Double-click the Label value cell, and then type Problem Tracking/Associate Problem Number.

    This action now appears under the Problem Tracking category in the context menu.

  6. Right-click OFFL_ACT_CONT_AssociateProblemNumber, and then click New Child > Tool.

    This creates a new tool under the OFFL_ACT_CONT_AssociateProblemNumber action descriptor.

  7. Right-click Tool, and then click Edit.

    This opens the Edit Properties dialog box.

  8. Double-click the Target ID value cell, and then select OFFL_TOOL_AWM_Dialog_GetProblemNumber.
  9. Click OK.
  10. Finally, you need to specify where the action should be displayed. It should be displayed in the context menu of elements of an Eclipse linked file type. To do this:

    Under the Element Types, right-click OFFL_ELE_Eclipse_File, and then click New Child > Action.

  11. Right-click the new Action, and then click Edit.

    This opens the Edit Properties dialog box.

  12. Double-click the Target ID value cell, and then select OFFL_ACT_CONT_AssociateProblemNumber.
  13. Click OK.
  14. Click File > Save.
Parent topic: Creating the Model
Previous topic: Specifying a Tool to Enable Problem Number Entry


Validation the Model

Now that you have modified the IntegratedEDModel model you can validate your changes. The validation reports any errors or warnings relating to its structure and relationships. With the model open in the AWM model editor, click Validate the current configuration Validates the current configuration, if there are any errors or warnings it displays a Validation Problems dialog box. See Validating an AWM Model for more information.
Parent topic: Tutorial: Adding a New Action to an Existing AWM Model
Previous topic: Creating the Model
Next topic: Running and Testing the Model


Running and Testing the Model

When you first run and test your AWM model you should start Enterprise Developer for Eclipse in debug mode. To do this, first close Enterprise Developer for Eclipse:

  1. Right-click the shortcut for Enterprise Developer for Eclipse.
  2. Click Properties.

    This opens the Enterprise Developer for Eclipse Properties dialog box.

  3. In the Target field, at the end of the existing text, type -debug.

    The field content should look like this:

    "C:\Users\Public\Micro Focus\Enterprise Developer\eclipse\eclipse.exe" -debug

  4. Click OK.
  5. Restart Enterprise Developer for Eclipse.
  6. In the Application Explorer view, click View Menu, and then click Add System(s).

    This opens the Add System(s) dialog box.

  7. Click Custom System, and then click OK.

    This opens the Custom AWM System dialog box.

  8. In the System Name field, type Problem Tracking.
  9. Click Next.
  10. In the Model Location field, click Browse and navigate to the CustomizedIntegratedEDModel.model.

    The Application Name field is automatically populated with text derived from the application name.

  11. Click Finish.

    This adds the Problem Tracking custom system to the Application Explorer view.

  12. In the Application Explorer view, expand the Problem Tracking custom system.
  13. Right-click CustomizedIntegratedEDModel, and then click Load Application.

The content of the default custom system folder is mirrored. Navigate to a file, and then right-click the file. A new Problem Tracking command is displayed in the file's context menu. Click Problem Tracking > Associate Problem Number. This opens the new Problem Number dialog box. In the Problem Number filed, type a six digit number of your choosing. Click OK to store this number against the file. Click Problem Tracking > Associate Problem Number again and the dialog displays the number previously stored.

Parent topic: Tutorial: Adding a New Action to an Existing AWM Model
Previous topic: Validation the Model


Workflow Manager ChangeMan Attachment

  • Introduction
  • Installation
  • The ChangeMan Attachment
  • Server and REXX Customization
  • Customizing the ChangeMan Model
Parent topic: Application Workflow Manager


Introduction

The Workflow Manager ChangeMan Attachment consists of mainframe components that have to be installed in a z/OS environment.

This document is intended for system programmers and/or ChangeMan administrators installing and configuring the Workflow Manager ChangeMan Attachment on their z/OS host system.

Herein, this document refers to the Workflow Manager ChangeMan Attachment components as ChangeMan components.

  • Workflow Manager ChangeMan Attachment
  • Software Requirements
Parent topic: Workflow Manager ChangeMan Attachment


Workflow Manager ChangeMan Attachment

ChangeMan ZMF (ChangeMan) supports the development of mainframe applications under ISPF.

With the Workflow Manager ChangeMan Attachment, you can:

  • Provide the ChangeMan development process in an Eclipse-based development environment.
  • Customize the ChangeMan development process to suit your needs.
  • Model and customize the Eclipse-based ChangeMan user interface without any programming effort.
  • Seamlessly integrate existing home-grown and third party tools.
Parent topic: Introduction


Software Requirements

To use the ChangeMan Attachment, the following software must be installed and configured correctly:

  • Enterprise Developer version 3.0.0 or later.
  • Micro Focus ChangeMan ZMF version 6.x or later.
Parent topic: Introduction


Installation

  • General Considerations
  • Basic Installation Procedure
Parent topic: Workflow Manager ChangeMan Attachment


General Considerations

Determine a dataset prefix that matches the naming conventions in your company. This document will use the prefix HLQ.CMG in all further specifications.

Parent topic: Installation


Basic Installation Procedure

  • Download and Unzip the Software
  • Upload the Software to the Mainframe
  • Receive the Software
Parent topic: Installation


Download and Unzip the Software

Download the ChangeMan Attachment from the download link received from Micro Focus.

Unzip the download file to a temporary folder. A folder named host is created, which contains all mainframe installation components in binary XMIT format.

There are no client components to install.

Parent topic: Basic Installation Procedure


Upload the Software to the Mainframe

The unzipped ChangeMan Attachment contains two XMIT files. Upload both files from the host folder, in binary format, to sequential datasets with a record length of 80 and a block size of 3120, using the following procedure.

  1. On z/OS, allocate the datasets to use as the upload target files. To do this, create a dataset with the same characteristics as the sample job below or by submitting the job below. If you choose to submit the following job, note the following:
    • hlq is the high-level qualifier you choose to use for this dataset.
    • Before submitting, add a job card and modify the parameters to meet your site's requirements.
    • Optionally, add a valid VOLSER and/or change the UNIT parameter.
    //ALLOC1 EXEC PGM=IEFBR14
//*
//FTPALLOC DD DSN=hlq.CMG.EXEC.XMIT,
// DISP=NEW,CATLG,DELETE),
// DSORG=PS,
// RECFM=FB,
// LRECL=80,
// BLKSIZE=3120,
//* VOL=SER=vvvvvv,
// UNIT=SYSALLDA,
// SPACE=(TRK,(45,15))

    Repeat this step for the hlq.CMG.AWMMODEL.XMIT dataset.

  2. To upload the files, you can use FTP from a command prompt.

    In the sample shown below, commands or other information entered by a user are displayed in bold, and the values in the following table are assumed:

    User input | Description
    mvsaddr | The TCP/IP address or hostname of the z/OS system.
    tsouid | Your TSO user ID.
    tsopw | Your TSO password.
    hlq | High-level qualifier used for the dataset allocated in the job above.
    C:\>ftp mvsaddr
Connected to mvsaddr.
220-FTPD1 IBM FTP CS V1R10 at custom.com, 12:03:32 on 2011-08-02.
220 Connection will close if idle for more than 5 minutes.
User (mvsaddr:(none)): tsouid
331 Send password please.
Password: tsopw
230 tsouid is logged on. Working directory is "tsouid.".
ftp> cd ..
250 " " is the working directory name prefix.
ftp> cd hlq
250 "hlq." is the working directory name prefix.
ftp> binary
200 Representation type is Image
ftp> put d:\host\hlq.CMG.EXEC.XMIT
200 Port request OK.
125 Storing data set hlq.CMG.EXEC.XMIT
250 Transfer completed successfully.

    Transfer the file hlq.CMG.AWMMODEL.XMIT to your mainframe system.

    You now have the following files on your mainframe system:
    • HLQ.CMG.EXEC.XMIT
    • HLQ.CMG.AWMMODEL.XMIT
Parent topic: Basic Installation Procedure


Receive the Software

Use the TSO RECEIVE command to create the partitioned datasets from the sequential XMIT files. HLQ.CMG is the assumed installation prefix.

Enter TSO or Workstation commands below:
===> receive indataset('hlq.CMG.EXEC.XMIT')

When prompted, enter:

INMR906A Enter restore parameters or 'DELETE' or 'END' +
restore dataset('hlq.CMG.EXEC’)

The result is a partitioned dataset containing REXX procedures.

Repeat the RECEIVE process for the AWMMODEL dataset.

You should give the received dataset containing the AWM model the low-level qualifier AWMMODEL. In the Team Developer perspective of Enterprise Developer a file mapping is defined for datasets with the low-level qualifier AWMMODEL which ensures that members of an AWMMODEL dataset are downloaded with the code page IBM-037. This ensures that special characters contained in the AWMMODEL member are correctly interpreted when the model is loaded on the client-side.

If you use another low-level qualifier for the model dataset than AWMMODEL, you have to ensure that a corresponding file mapping is defined on the client-side.

Parent topic: Basic Installation Procedure


The ChangeMan Attachment

  • Overview of REXX Procedures
Parent topic: Workflow Manager ChangeMan Attachment


Overview of REXX Procedures

All REXX procedures within the ChangeMan Attachment are listed below.

The following table contains a short description of each procedure, where it is used in the model, and the ChangeMan XML services used:

REXX Name | Description
TAUCMAAT Audit a release area:
  • Used in CMG_TOOL_ISPF_REX_AuditArea
  • Uses RLSMAREA.SERVICE.AUDIT
TAUCMABL Block a release area:
  • Used in CMG_TOOL_ISPF_REX_BlockArea
  • Uses RLSMAREA.SERVICE.BLOCK
TAUCMACI Check-in a release area:
  • Used in CMG_TOOL_ISPF_REX_AreaCheckIn
  • Uses RLSMAREA.SERVICE.CHECKIN
TAUCMACM Calls TAUCMACI for mass input processing:
  • Used in CMG_TOOL_ISPF_REX_CheckinAreaMass
TAUCMADM Demote a release area:
  • Used in CMG_TOOL_ISPF_REX_AreaDemote
  • Uses RLSMAREA.SERVICE.DEMOTE
TAUCMADS Calls TAUCMADM for mass input processing:
  • Used in CMG_TOOL_ISPF_REX_DemoteAreaMass
TAUCMALC Allocate a temporary data set used for a ChangeMan component file transfer:
  • Used in CMG_TOOL_ISPF_REX_GetComponentTempDataset
TAUCMAPM Calls TAUCMAPR for mass input processing:
  • Used in CMG_TOOL_ISPF_REX_PromoteAreaMass
TAUCMAPL Retrieve an approver list for drop-down lists:
  • Used in CMG_TOOL_ISPF_REX_RetrieveApprover
  • Uses APPROVER.APL.LIST
TAUCMAPP Approve a package:
  • Used in CMG_TOOL_ISPF_REX_ApprovePackage
  • Uses PACKAGE.SERVICE.APPROVE
TAUCMAPR Promote a release area:
  • Used in CMG_TOOL_ISPF_REX_AreaPromote
  • Uses RLSMAREA.SERVICE.PROMOTE
TAUCMARC Get components of a release area (name and type) to check-in:
  • Used in TOOL_REXX_RetrieveAreaComponents
  • Uses RLSMAREA.CHK_AREA.LIST
TAUCMAUB Unblock a release area:
  • Used in CMG_TOOL_ISPF_REX_UnblockArea
  • Uses RLSMAREA.SERVICE.UNBLOCK
TAUCMAUD Audit a package:
  • Used in CMG_TOOL_ISPF_REX_AuditPackage
  • Uses PACKAGE.SERVICE.AUDIT
TAUCMAUL Reset an audit lock flag:
  • Used in CMG_TOOL_ISPF_REX_ResetAuditLock
  • Uses PACKAGE.GEN_PARMS.UPDATE
TAUCMBAK Backout a package:
  • Used in CMG_TOOL_ISPF_REX_BackoutPackage
  • Uses PACKAGE.SERVICE.BACKOUT
TAUCMBBV Retrieve a baseline version of a component:
  • Used in CMG_TOOL_ISPF_REX_GetBSV_Browse
  • Uses BASELIB.SERVICE.LIST
  • Uses CMNUPDAT
TAUCMBLC Retrieve a ChangeMan baseline component list:
  • Used in CMG_TOOL_ISPF_REX_ListBaselineComponents
  • Uses DSS.SERVICE.LIST
TAUCMBLD Build a ChangeMan component in a stage library:
  • Used in CMG_TOOL_ISPF_REX_BuildComponent
  • Uses CMPONENT.APL_DPRC.CHECK
  • Uses CMPONENT.SERVICE.BUILD
TAUCMBLI Retrieve a ChangeMan baseline component list:
  • Used in CMG_TOOL_ISPF_REX_GetBaselineComponents
  • Uses DSS.SERVICE.LIST
TAUCMBL2 Build a ChangeMan component in a stage library using options from history (no option dialog box popup):
  • Used in CMG_TOOL_ISPF_REX_BuildComponentSimple
  • Uses CMPONENT.APL_DPRC.CHECK
  • Uses CMPONENT.SERVICE.BUILD

Supports mass processing.

TAUCMBRC Retrieve an SSV version of a component for comparison based on a location:
  • Used in CMG_TOOL_ISPF_REX_GetSSV_Browse2Compare
  • Uses BASELIB.SERVICE.LIST
  • Uses PACKAGE.GEN_PRMS.LIST
  • Uses CMPONENT.SSV_VER.RETRIEV
TAUCMBRL Retrieve a compressed list from a stage library:
  • Used in CMG_TOOL_ISPF_REX_GetComponentPhysicalList_Browse
  • Uses the ChangeMan utility SERCOPY to retrieve a component
TAUCMBR2 Retrieve an SSV version of a component for comparison based on a timestamp:
  • Used in CMG_TOOL_ISPF_REX_GetSSV_Browse2Compare
  • Uses BASELIB.SERVICE.LIST
  • Uses PACKAGE.GEN_PRMS.LIST
  • Uses CMPONENT.SSV_VER.RETRIEVE
TAUCMBRS Retrieve an SSV version of a component:
  • Used in CMG_TOOL_ISPF_REX_GetSSV_Browse
  • Uses BASELIB.SERVICE.LIST
  • Uses PACKAGE.GEN_PRMS.LIST
  • Uses CMPONENT.SSV_VER.RETRIEVE
TAUCMBRW Retrieve a component from a library (stage or baseline):
  • Used in CMG_TOOL_ISPF_REX_GetComponentPhysicalMember_Browse
  • Uses CMPONENT.BROWSE.SERVICE
TAUCMBSV Retrieve a baseline version list:
  • Used in CMG_TOOL_ISPF_REX_GetBSVComponents
  • Uses BASELIB.SERVICE.LIST
  • Uses CMNVNSRD
TAUCMCIN Check in ChangeMan components in a stage library from an external data set:
  • Used in CMG_TOOL_ISPF_REX_CheckInFromPersLib
  • Used in CMG_TOOL_ISPF_REX_CheckInFromPersLib_MultipleComponents
  • Uses CMPONENT.SERVICE.CHECKIN
TAUCMCLI Retrieve a ChangeMan package component list:
  • Used in CMG_TOOL_ISPF_REX_GetPackageComponents
  • Uses CMPONENT.PKG_COMP.LIST
  • Uses CMPONENT.PKG_LOD.LIST
TAUCMCL2 Retrieve a ChangeMan staged component list:
  • Uses CMPONENT.PKG_COMP.LIST
TAUCMCL3 Retrieve a ChangeMan package load dependencies list:
  • Uses CMPONENT.PKG_LOD.LIST
TAUCMCL4 Retrieve a ChangeMan package load dependencies list:
  • Used in CMG_TOOL_ISPF_REX_GetSourceLoad
  • Uses CMPONENT.PKG_LOD.LIST
TAUCMCOU Check out a ChangeMan component:
  • Used in CMG_TOOL_ISPF_REX_CheckOutFromBaseline
  • Used in CMG_TOOL_ISPF_REX_CheckOutFromBaselineBAS
  • Uses CMPONENT.SERVICE.CHECKOUT
TAUCMCPA Create a ChangeMan package:
  • Used in CMG_TOOL_ISPF_REX_CreatePackage
  • Uses PACKAGE.SERVICE.CREATE
TAUCMCPH Retrieve a component history:
  • Used in CMG_TOOL_ISPF_REX_GetComponentHistory
  • Uses CMPONENT.HISTORY.LIST
TAUCMCPY Copy a component:
  • Used in CMG_TOOL_ISPF_REX_CopyComponent
  • Uses CMPONENT.SERVICE.BROWSE
TAUCMDCO Delete a ChangeMan component in stage library:
  • Used in CMG_TOOL_ISPF_REX_DeleteComponent
  • Uses CMPONENT.PKG_COMP.DELETE

Supports mass processing.

TAUCMDPA Memo (un-)delete a ChangeMan package:
  • Used in CMG_TOOL_ISPF_REX_Delete_Undelete_Package
  • Uses PACKAGE.SERVICE.DELETE

Supports mass processing.

TAUCMFRZ Freeze a ChangeMan package:
  • Used in CMG_TOOL_ISPF_REX_FreezePackage
  • Uses PACKAGE.SERVICE.FREEZE
TAUCMGAC Get the application containers used in the tree view:
  • Used in CMG_TOOL_ISPF_REX_GetApplicationContainers
TAUCMGAR Get the areas of a release:
  • Used in CMG_TOOL_ISPF_REX_GetReleaseAreas
  • Uses RLSMAREA.SERVICE.LIST
TAUCMGAP Get the application list:
  • Used in CMG_TOOL_ISPF_REX_GetApplications
  • Uses PARMS.APL.LIST
TAUCMGBL Get the baseline library for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_GetLibraryTypes
  • Uses BASELIB.SERVICE.LIST
TAUCMGCC Get changed components for a release area:
  • Used in TOOL_REXX_GetChangedComponentsInArea
  • Uses RLSMRLSE.CIM.LIST
TAUCMGCS Get component summary for a release area:
  • Used in TOOL_REXX_GetSummaryComponentsInArea
  • Uses RLSMAREA.SUMMARY.CMP_RLSE
TAUCMGCO Retrieve a component from a stage library and lock it:
  • Used in CMG_TOOL_ISPF_REX_GetComponentPhysicalMember
  • Uses CMPONENT.SERVICE.BROWSE
TAUCMGDL | Get data sets matching the generic PDS search criterion.
TAUCMGLA Get language names for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_ListLanguages
  • Uses PROCS.APL.LIST
TAUCMGLI Get library types for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_ListLibraryTypes
  • Uses LIBTYPE.APL.LIST
TAUCMGML | Get member list matching the PDS member search criterion.
TAUCMGPL Get library for a ChangeMan application package:
  • Used in CMG_TOOL_ISPF_REX_GetPackageLibraryTypes
  • Uses CMPONENT.PKG_COMP.LIST
TAUCMGPR Get build procedure and language names for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_RetrieveBuildProcedureAndLanguage
  • Uses PROCS.APL.LIST
TAUCMGP2 Get valid build procedures for a language name:
  • Used in CMG_TOOL_ISPF_REX_LockComponent
  • Uses PROCS.APL.LIST
TAUCMGRC | Get root containers for model ChangeMan application.
TAUCMGRN Get promotion names for a release:
  • Used in CMG_TOOL_ISPF_REX_GetReleasePromotionNames
  • Uses RLSMAPPL.PROMOTE.LIST
TAUCMGRP Get promotion sites for a release:
  • Used in CMG_TOOL_ISPF_REX_GetReleasePromotionSites
  • Uses RLSMAPPL.PROMOTE.LIST
TAUCMGSA Get libraries for a release area (summary):
  • Used in TOOL_REXX_GetLibraryTypesOfSummaryInArea
  • Uses RLSMAREA.SUMMARY.CMP_RLSE
TAUCMGSC Get global security attributes for a user:
  • Used in TOOL_REXXGetUserSecurityAttributes
  • Uses USERSEC.SERVICE.LIST
TAUCMGTA Get libraries for a release area (changed components):
  • Used in TOOL_REXX_GetLibraryTypesInArea
  • Uses RLSMRLSE.CIM.LIST
TAUCMHIS Retrieve a specific component history:
  • Used in CMG_TOOL_ISPF_REX_GetComponentInfo
  • Uses CMPONENT.HISTORY.LIST
  • Uses CMPONENT.HISTORY.LISTBASE
TAUCMIMP Retrieve a ChangeMan impact analysis list:
  • Used in CMG_TOOL_ISPF_REX_GetIAComponents
  • Used in CMG_TOOL_ISPF_REX_GetIADown
  • Used in CMG_TOOL_ISPF_REX_GetIAUp
  • Uses IMPACT.TABLE.LIST
TAUCMLCK Lock a ChangeMan component in a stage library:
  • Used in CMG_TOOL_ISPF_REX_LockComponent
  • Uses CMPONENT.SERVICE.LOCK
TAUCMLST Retrieve a listing from a stage library:
  • Used in CMG_TOOL_ISPF_REX_ListReleases
  • Uses CMPONENT.SERVICE.BROWSE
TAUCMMAL Calls TAUCMALC for mass input processing:
  • Used in CMG_TOOL_ISPF_REX_GetComponentTempDatasetMass
TAUCMMCI Calls TAUCMCIN for mass input processing:
  • Used in CMG_TOOL_ISPF_REX_CheckInFromPersLibMass
TAUCMMCO Calls TAUCMMCO for mass input processing:
  • Used in CMG_TOOL_ISPF_REX_GetComponentPhysicalMemberMass
TAUCMNEW Create a new dummy component and lock it:
  • Used in CMG_TOOL_ISPF_REX_NewComponent
  • Uses CMPONENT.SERVICE.CHECKIN
TAUCMNTY Browse a global notification file:
  • Used in CMG_TOOL_ISPF_REX_GetNotyFile
  • Uses NOTYFILE.SERVICE.DOWNLOAD
TAUCMPAT Attach a package to a release area:
  • Used in CMG_TOOL_ISPF_REX_PackageAttach
  • Uses PACKAGE.SERVICE.ATTACH
TAUCMPCI Check-in package (components) to a release area:
  • Used in CMG_TOOL_ISPF_REX_PackageCheckIn
  • Uses RLSMAREA.PACKAGE.CHECKIN
TAUCMPDS Retrieve a ChangeMan promoted component list:
  • Used in CMG_TOOL_ISPF_REX_GetPromotionComponents
  • Uses DSS.SERVICE.LIST
TAUCMPDT Detach a package from a release area:
  • Used in CMG_TOOL_ISPF_REX_PackageDetach
  • Uses PACKAGE.SERVICE.DETACH
TAUCMPGD Get a package description:
  • Used in CMG_TOOL_ISPF_REX_GetPackageDescription
  • Uses PACKAGE.GEN_DESC.LIST
TAUCMPGI Get a package implementation description:
  • Used in CMG_TOOL_ISPF_REX_GetPackageInstruction
  • Uses PACKAGE.IMP_INST.LIST
TAUCMPGS Retrieve a ChangeMan production site list:
  • Used in CMG_TOOL_ISPF_REX_GetProductionSites
  • Uses SITE.PKG.LIST
TAUCMPIS Insert package installation sites:
  • Used in CMG_TOOL_ISPF_REX_InsertPackageSites
  • Uses SITE.PKG.CREATE
TAUCMPKI Retrieve a specific package information:
  • Used in CMG_TOOL_ISPF_REX_GetPackageGeneralParms
  • Uses PACKAGE.GEN_PRMS.LIST
TAUCMPLI Retrieve a ChangeMan package list with properties:
  • Used in CMG_TOOL_ISPF_REX_GetPackages
  • Uses PACKAGE.GENERAL.SEARCH
TAUCMPL2 Retrieve a ChangeMan package identifier list:
  • Used in CMG_TOOL_ISPF_REX_RetrievePackageIDs
  • Uses PACKAGE.GENERAL.SEARCH
TAUCMPL3 Retrieve a ChangeMan package name list:
  • Used in CMG_TOOL_ISPF_REX_RetrievePackageNames
  • Uses PACKAGE.GENERAL.SEARCH
TAUCMPL4 Retrieve a ChangeMan package list for comparison:
  • Used in CMG_TOOL_ISPF_REX_RetrievePackageNamesHistory
  • Uses PACKAGE.GENERAL.SEARCH
TAUCMPPD Delete a participating package:
  • Used in CMG_TOOL_ISPF_REX_DeleteParticipatingPackage
  • Uses PACKAGE.PRT_PKGS.MDELETE
TAUCMPPG Get a participating package list:
  • Used in CMG_TOOL_ISPF_REX_GetParticipatingPackages
  • Uses PACKAGE.PRT_PKGS.LIST
TAUCMPPI Insert a participating package:
  • Used in CMG_TOOL_ISPF_REX_InsertParticipatingPackage
  • Uses PACKAGE.PRT_PKGS.MCREATE
TAUCMPRC Get member of a package (name and type) for check-in:
  • Used in CMG_TOOL_ISPF_REX_RetrievePackageComponents
  • Uses RLSMAREA.CHK_PKG.LIST
TAUCMPRH Retrieve a component/package promotion history:
  • Used in CMG_TOOL_ISPF_REX_GetPromotionHistory
  • Uses CMPONENT.PRM_HIST.LIST
TAUCMPRL Get promotion libraries for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_GetPromoLibraryTypes
  • Used in CMG_TOOL_ISPF_REX_GetPromoDataSets
  • Uses PROMLIB.LIBRARY.LIST
TAUCMPRM Promote a package or package components:
  • Used in CMG_TOOL_ISPF_REX_DemoteComponentOrPackage
  • Uses PACKAGE.CHECK.PROMOTE
  • Uses PACKAGE.SERVICE.DEMOTE
  • Uses PACKAGE.SERVICE.PROMOTE
TAUCMPRN Retrieve a promotion name list:
  • Used in CMG_TOOL_ISPF_REX_GetPromotionLevel
  • Uses PROMLIB.SITE.LIST
TAUCMPRS Retrieve a promotion site list:
  • Used in CMG_TOOL_ISPF_REX_GetPromotionSites
  • Uses PROMLIB.SITE.LIST
TAUCMPRV Retrieve components from a release area:
  • Used in CMG_TOOL_ISPF_REX_PackageRetrieve
  • Uses RLSMAREA.PACKAGE.RETRIEVE
TAUCMPSD Delete package installation sites:
  • Used in CMG_TOOL_ISPF_REX_DeletePackageSites
  • Uses SITE.PKG.DELETE
TAUCMPUD Update package description:
  • Used in CMG_TOOL_ISPF_REX_UpdatePackageDescription
  • Uses PACKAGE.GEN_DESC.UPDATE
TAUCMPUG Update specific package info:
  • Used in CMG_TOOL_ISPF_REX_UpdatePackageGeneralParms
  • Uses PACKAGE.GEN_PRMS.UPDATE
TAUCMPUI Update package implementation description:
  • Used in CMG_TOOL_ISPF_REX_UpdatePackageInstruction
  • Uses PACKAGE.IMP_INST.UPDATE
TAUCMPUS Update package installation sites:
  • Used in CMG_TOOL_ISPF_REX_UpdatePackageSites
  • Uses SITE.PKG.UPDATE
TAUCMP2D Get members to be demoted:
  • Used in CMG_TOOL_ISPF_REX_RetrieveDemotionComponents
  • Uses CMPONENT.PRM_HIST.LIST
TAUCMP2M Get members that could be promoted:
  • Used in CMG_TOOL_ISPF_REX_RetrievePromotionComponents
  • Uses PACKAGE.PRM_CMP.LIST
TAUCMP2N Get promotion names for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_RetrievePromotionLevelNames
  • Uses PROMLIB.SITE.LIST
TAUCMP2S Get promotion site names for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_RetrievePromotionSites
  • Uses PROMLIB.SITE.LIST
TAUCMP3S Get production site names for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_RetrieveProductionSites
  • Uses PRODLIB.SERVICE.LIST
TAUCMRAC Retrieve components from a release area:
  • Used in CMG_TOOL_ISPF_REX_RetrieveComponentsFromArea
  • Uses RLSMAREA.SERVICE.RETRIEVE
TAUCMRAM Calls TAUCMRAC for mass input processing:
  • Used in CMG_TOOL_ISPF_REX_RetrieveComponentsFromAreaMass
TAUCMREC Recompile a ChangeMan component in stage library:
  • Used in CMG_TOOL_ISPF_REX_RecompileComponent
  • Uses CMPONENT.APL_DPRC.CHECK
  • Uses CMPONENT.SERVICE.RECOMP
TAUCMREL Relink a ChangeMan component in stage library:
  • Used in CMG_TOOL_ISPF_REX_RelinkComponent
  • Uses CMPONENT.APL_DPRC.CHECK
  • Uses CMPONENT.SERVICE.RELINK
TAUCMREV Revert a package:
  • Used in CMG_TOOL_ISPF_REX_RevertPackage
  • Uses PACKAGE.SERVICE.REVERT
TAUCMRLI Retrieve a ChangeMan release list:
  • Used in CMG_TOOL_ISPF_REX_GetReleases
  • Uses RLSMRLSE.SERVICE.SEARCH
TAUCMRPL Retrieve promotion names and levels for a release:
  • Used in CMG_TOOL_ISPF_REX_RetrieveReleaseApplPromotionLevels
  • Uses RLSMAPPL.PROMOTE.LIST
TAUCMRPS Retrieve promotion site names for a release:
  • Used in CMG_TOOL_ISPF_REX_RetrieveReleaseApplPromotionSites
  • Uses RLSMAPPL.PROMOTE.LIST
TAUCMRRA Retrieve the applications joined to a release:
  • Used in CMG_TOOL_ISPF_REX_RetrieveReleaseApplications
  • Uses RLSMAPPL.SERVICE.LIST
TAUCMRSC Remote syntax check for a ChangeMan component:
  • Used in CMG_TOOL_ISPF_REX_RemoteSyntaxCheck
  • Uses CMPONENT.SERVICE.BROWSE
TAUCMSCD Delete a scratch entry:
  • Used in CMG_TOOL_ISPF_REX_DeleteScratchComponent
  • Uses PACKAGE.PKG_UTIL.DELETE
TAUCMSCI Insert a scratch entry:
  • Used in CMG_TOOL_ISPF_REX_InsertScratchComponent
  • Uses PACKAGE.PKG_UTIL.CREATE
TAUCMSCL Retrieve a ChangeMan scratch component list:
  • Used in CMG_TOOL_ISPF_REX_GetScratchComponents
  • Uses PACKAGE.PKG_UTIL.LIST
TAUCMSEC ChangeMan security exit:
  • Used in Rexx procedures to verify security rights
  • Uses USERSEC.SERVICE.CHECK
TAUCMSS2 Retrieve an SSV version list for a compare dialog:
  • Used in CMG_TOOL_ISPF_REX_GetSSVComponents
  • Uses CMPONENT.SSV_VER.LIST
TAUCMSSV Retrieve an SSV version list:
  • Used in CMG_TOOL_ISPF_REX_GetSSVComponents
  • Uses PACKAGE.GEN_PRMS.LIST
  • Uses PACKAGE.PRT_PKGS.LIST
  • Uses BASELIB.SERVICE.LIST
  • Uses PROMLIB.LIBRARY.LIST
TAUCMSYL Building the SYSLIB concatenation for edit:
  • Used in CMG_TOOL_ISPF_REX_GetSYSLIB
  • Uses CMPONENT.SSV_VER.LIST
TAUCMUNL Unlock a ChangeMan component in stage library:
  • Used in CMG_TOOL_ISPF_REX_UnlockComponent
  • Uses CMPONENT.SERVICE.UNLOCK
TAUCMVAP Get an application name list:
  • Used in CMG_TOOL_ISPF_REX_ListApplications
  • Uses PARMS.APL.LIST
TAUCMVAR Retrieve ChangeMan area names for a release:
  • Used in CMG_TOOL_ISPF_REX_ListReleaseAreas
  • Uses RLSMAREA.SERVICE.LIST
TAUCMVRE Get reason codes for ChangeMan unplanned changes:
  • Used in CMG_TOOL_ISPF_REX_ListReasonCodes
  • Uses REASONS.SERVICE.LIST
TAUCMVRL Retrieve ChangeMan release names for model:
  • Used in CMG_TOOL_ISPF_REX_ListReleases
  • Uses RLSMRLSE.SERVICE.SEARCH
TAUCMVSI Get site names for a ChangeMan application:
  • Used in CMG_TOOL_ISPF_REX_RetrieveSiteNames
  • Uses SITE.APL.LIST
TAUCMXA1 Exit to create temporary data sets.

All temporary data sets used by the ChangeMan attachment are created with this exit procedure.

TAUCMXA2 Exit for dynamic allocations of the ZMF environment.

Verify and customize the ZMF system data set names.

TAUCMXA3 | Exit for mapping ChangeMan library types and languages to file suffixes.
TAUCMXA4 | Exit for defining specific ChangeMan library types for source, listing and load modules.
Parent topic: The ChangeMan Attachment


Server and REXX Customization

Before using the ChangeMan Attachment for the first time, you must perform some initial customization.

  • Add the ChangeMan Workflow Model to the Master Configuration File
  • Add the EXEC Dataset to the z/Server User Task
  • Optional: Add the EXEC datasets to ISPF.conf
  • Dataset Security
  • Customizing REXX procedures
Parent topic: Workflow Manager ChangeMan Attachment


Add the ChangeMan Workflow Model to the Master Configuration File

Edit the Master Configuration file and insert the following reference to the ChangeMan workflow model:

*
* APPLICATION for CHANGEMAN Workflow Model V4.0.0
*
User:
* application name
Appl: ChangeMan Application Subsystem P <- Label in the AWM tree view
* location of the application configuration file
Conf:  mvs:'hlq.CMG.AWMMODEL(CMG400)'        <- Location of your ChangeMan model
* application version number
Version: 4.0.0
* process information
INFO:
* properties for this application
Property: CMG_PROP_STATIC_ER_Option=Y 		<- Activate ERO option (Y/N)
Property: CMG_PROP_STATIC_Subsystem=P   <- Your ChangeMan subsystem
Property: CMG_PROP_STATIC_IDE=ED        <- Enterprise Developer IDE
* end of application definition.
EndAppl:
EndUser:

You must customize the Conf: entry to reference the installed XML data set.

Choosing an asterisk (*) as a subsystem name enables simulation mode, which can be used to simulate the most important ChangeMan actions without ChangeMan being installed on the mainframe system. Any other subsystem name must be a valid ChangeMan subsystem identifier.

If the ChangeMan Model is installed in an IDz environment you must set the property CMG_PROP_STATIC_IDE to RDZ instead of ED, and you must use the model CMG400R instead of CMG400.

You can find details of how to create an application entry for the Master Configuration file in your Workflow Manager Modeling Guide.

Parent topic: Server and REXX Customization
Related information
Master Configuration on z/OS


Add the EXEC Dataset to the z/Server User Task

Within the z/Server User Task, you must concatenate the received dataset HLQ.CMG.EXEC to the SYSEXEC allocation.

It is recommended that you customize the JCL of the z/Server User Task to perform this allocation.

……
//STEPLIB  DD DSN=&TAURHLQ..LOADLIB,DISP=SHR
//SYSEXEC  DD DSN=&TAURHLQ..EXEC,DISP=SHR
//         DD DSN=HLQ.CMG.EXEC,DISP=SHR
//         DD DSN=&TAURHLQ..REXX,DISP=SHR
//ISPPLIB  DD DSN=&ISPFHLQ..SISPPENU,DISP=SHR
//         DD DSN=ISF.SISFPLIB,DISP=SHR
//ISPSLIB  DD DSN=&ISPFHLQ..SISPSENU,DISP=SHR
//         DD DSN=ISF.SISFSLIB,DISP=SHR
//ISPMLIB  DD DSN=&ISPFHLQ..SISPMENU,DISP=SHR
//         DD DSN=ISF.SISFMLIB,DISP=SHR
……

For more information on customizing the z/Server User Task see your z/Server Installation Guide.

Alternatively, instead of a static allocation you can dynamically allocate both datasets by customizing the exit procedure TAUTOXA1. See the Worklow Manager Modeling Guide for more details.

Parent topic: Server and REXX Customization
Related information
ISPF Exits


Optional: Add the EXEC datasets to ISPF.conf

If the ChangeMan Attachment is used within IBM Developer for z Systems with the IBM RSE daemon as server, you must add the installation EXEC datasets to the configuration file ISPF.conf in the USS configuration path of the RSE daemon.

Parent topic: Server and REXX Customization


Dataset Security

The ChangeMan Attachment uses several datasets to communicate between ChangeMan and the client software. All datasets defined in certain exits (especially TAUCMXA1) should adhere to the following security rules.

As all actions/jobs are running under the authority of the developer’s TSO user ID, the user must have ALTER rights to these datasets. Also, all actions in ChangeMan, started via XML service calls, are handled under a specific ChangeMan userid, and need the same rights to access datasets used within an XML service on the ChangeMan server.

Therefore, it is recommended that you use your TSO user ID as the first-level qualifier/dataset schema for ChangeMan temporary work datasets. This ensures a regular cleanup process across all relevant datasets.

Parent topic: Server and REXX Customization


Customizing REXX procedures

As ChangeMan is a highly flexible system, you must change some routines to reflect your implementation of ChangeMan.

Check the REXX routines described in the following topics.

  • General Customization
  • TAUCMRSC - Remote syntax check
  • TAUCMSYL - Determine the SYSLIB Concatenation
  • TAUCMXA1 - Allocation Exit
  • TAUCMXA2 - Dynamic Allocation Exit
  • TAUCMXA3 - Determine the File Suffix
  • TAUCMXA4 - Determine Specific ChangeMan Library Types
Parent topic: Server and REXX Customization


General Customization

Regarding the ChangeMan Attachment, the following table listing the general procedure adaptations are of special importance.

REXX procedure | Description
TAUZCAPP | If the ChangeMan Attachment is used within Enterprise Developer with z/Server as server, adjust the reference to the location of the Master Configuration file, as required.
TAULAPPL | If the ChangeMan Attachment is used within IBM Developer for z Systems with the IBM RSE daemon as server, adjust the reference to the location of the master configuration file, as required.
TAUTOXA1 The tool interface exit can be used for dynamic allocations or to set ISPF environment variables necessary to run your specific ChangeMan application.

If the ChangeMan Attachment runs in simulation mode (without a valid ChangeMan subsystem), the ISPF shared pool variable TAUQUAL has to be defined, pointing to the first qualifier of the simulation test datasets.

Micro Focus recommends allocating the ChangeMan libraries necessary to run ChangeMan services in the JCL of the z/Server User task. As an alternative you can use this exit to allocate those libraries dynamically. There is a sample allocation REXX procedure TAUCMXA2 available which has to be customized and called in TAUTOXA1.

Note:

TAUTOXA1 is always called when the client requests the execution of an ISPF tool. You have to make sure that TAUCMXA2 is called only once before the first ISPF tool execution request. For example, add the following lines to TAUTOXA1:

Call ISPF '8 VGET (TAUQUAL) SHARED'
If Result /= 0 Then Do
   Call REXX '0 TAUCMXA2'
   tauqual = 'HLQTEST'
   Call ISPF '0 VPUT (TAUQUAL) SHARED'
   End
TAUTOXA2 | General allocation exit: use this exit to allocate temporary files, for example, for Remote Syntax Check.
TAUTOXCA | Exit for Assembler Remote Syntax Check: customize the library names and allocations, as required.
TAUTOXCC | Exit for COBOL Remote Syntax Check: customize the library names and allocations, as required.
TAUTOXCP | Exit for PLI Remote Syntax Check: customize the library names and allocations, as required.
TAUTOXC3 | Exit for C Remote Syntax Check: customize the library names and allocations, as required.

You will find more details about the general adaptions in your Workflow Manager Modeling Guide

Parent topic: Customizing REXX procedures
Related information
Master Configuration on z/OS
ISPF Exits


TAUCMRSC - Remote syntax check

TAUCMRSC is a sample REXX procedure that compiles a source outside of ChangeMan and returns the Compiler messages to the client. The REXX procedure supports COBOL, PLI, Assembler and C.

This procedure calls the REXX procedure TAUCMSYL to identify the necessary SYSLIB datasets.

Adapt this procedure to support necessary compiler options which have to be used for syntax check.

Based on the ChangMan library type and/or language passed as parameters you will have to decide which compiler has to be called with which compiler options.

The compiler itself is called using the general z/Server exits TAUTOXCC, TAUTOXCA, TAUTOXCP and TAUTOXC3.

Parent topic: Customizing REXX procedures
Related information
ISPF Exits


TAUCMSYL - Determine the SYSLIB Concatenation

Adapt the named library type in the exit to link them to your component types, which should be included into your SYSLIB concatenation. The default library type names used in this exit are CPY and CPG.

Adapt the logic to your specific SYSLIB needs. The default exit is just mirroring the ChangeMan vendor logic of the SYSLIB concatenation, which is not necessarily yours. Please refer to your customized ChangeMan Skeleton CMN$$SYL to find out what is needed here.

Parent topic: Customizing REXX procedures


TAUCMXA1 - Allocation Exit

Temporary files are used for the communication between the client and the ChangeMan Attachment. The creation of the files takes place in the procedure TAUCMXA1. TAUCMXA1 should be adjusted to the available environment, as required.

Files that begin with userid.TAUCMTMP are created by default. These files are temporary in nature, but are not deleted automatically within the tool attachment. Instead, they can be reused once created, if necessary.

Micro Focus recommends that you place these files on a work unit and allow them to be deleted when inactive for a long period of time.

Parent topic: Customizing REXX procedures


TAUCMXA2 - Dynamic Allocation Exit

This exit allocates several datasets required to communicate between the user’s ISPF environment and ChangeMan. You must allocate all required libraries of your ChangeMan subsystem, such as LOAD libraries and the ChangeMan Parmlib.

Note: This is a sample REXX procedure only. It is not called automatically in the ChangeMan Attachment. Call this procedure in the REXX routine TAUTOXA1 if you want to use dynamic allocation of the ChangeMan datasets.
Parent topic: Customizing REXX procedures


TAUCMXA3 - Determine the File Suffix

This exit is used to determine the file suffix for a ChangeMan component based on the component type and its language.

Note: The language parameter is only passed to this exit if the component is a package component.
Parent topic: Customizing REXX procedures


TAUCMXA4 - Determine Specific ChangeMan Library Types

This is a central exit which defines the specific ChangeMan library types for sources, listings and load modules and puts the relevant types into the ISPF shared pool.

Default types are SRC, LST and LOD. If these type names do not match with your installation, please adapt this exit to your needs.

Parent topic: Customizing REXX procedures


Customizing the ChangeMan Model

The ChangeMan model is ready to run without any changes. However in most customer environments, ChangeMan has been heavily customized on the mainframe, especially ISPF panels, workflow, and other parts.

As these changes are very individual, it can not be predicted where and if there is any need for you to change the model.

If you want to customize the ChangeMan model, save the model member beforehand.

  • Jobs view
  • ChangeMan ERO Option
  • Common customizations
Parent topic: Workflow Manager ChangeMan Attachment


Jobs view

In general, the Workflow Manager supports the Jobs view to display batch jobs submitted via modelled actions, which are using the batch job interface. The ChangeMan Attachment does not use this feature, because all jobs (such as build, promote, and audit) are submitted from the ChangeMan server, and not directly from the attachment. The attachment just builds and executes XML service calls, and these XML service calls force ChangeMan to asynchronously submit jobs. This common ChangeMan behavior cannot be changed. This means that you have to use the JES Explorer to find the output of ChangeMan submitted jobs.

Parent topic: Customizing the ChangeMan Model


ChangeMan ERO Option

The ChangeMan ERO functionality can be controlled in the master configuration with the property CMG_PROP_STATIC_ER_Option. The property CMG_PROP_STATIC_ER_Option can take the value Y or N.

When the parameter is set to Y the RELEASE root entry is displayed in the tree view; otherwise, it is not displayed.

To disable the release filter, open the AWM model editor and delete the filter type definition CMG_FIL_ReleaseFilter from the defined filter types.

Parent topic: Customizing the ChangeMan Model


Common customizations

  • Conditions
  • Role Concept
  • Component Types
  • User Options
  • Property Cluster
  • Build Dialog Box
Parent topic: Customizing the ChangeMan Model


Conditions

Many actions are related to certain conditions that control the options in the context menus. To change these, you can adapt them easily in your own model.

For example:

This condition restricts the Recompile context menu entry to just the component type SRC. You could adapt this to your used component types for program sources.

Adapted example condition

This condition restricts the capability of browsing the LOD (load modules) and LST (compressed listings) baseline components, as they cannot be browsed in the regular way.

Parent topic: Common customizations


Role Concept

To reflect ChangeMan's role concept, all information about roles and rights of a user within ChangeMan are now implanted and reflected in the model. Therefore several properties are implemented.

The reflection of user roles and rights in the model

  • All global roles are cached when starting the model (building the root container).
  • A flag is set to determine whether a user has update or read rights on each application (PROP_SEC_ApplUpdate = Y/N). Any application where a user has not even read rights are not shown in the lists and tree views.
  • A new security exit (TAUCMSEC) is provided, where a user can be checked against certain RACF rights.

This information is used within the model to decide if a certain menu function is shown or not. In addition, several retrieve and list functions for promotion and approvals are enhanced to show only valid entries. The update and view panels for package parameter are split to reflect the read or update rights of a user.

Use your own conditions to customize which functions are available for users to use or not use.

The following table shows the flags available for conditions:

Flag | Condition
CMG_PROP_SEC_GlobalAccess | Does the user have Global Access?
CMG_PROP_SEC_AdminAccess | Does the user have Admin Access?
CMG_PROP_SEC_MonitorAcsess | Does the user have Monitor Access?
CMG_PROP_SEC_BackoutAccess | Does the user have Backout Access?
CMG_PROP_SEC_RevertAccess | Does the user have Revert Access?
CMG_PROP_SEC_ReleasManAccess | Does the user have Release Manager Access?
CMG_PROP_SEC_ReleaseApplAccess | Does the user have Release Application Access?
CMG_PROP_SEC_GlobalReadAccess | Does the user have Global Read Access?
CMG_PROP_SEC_AdminReadAccess | Does the user have Admin Read Acces?
CMG_PROP_SEC_ApplUpdate | Does the user have Application Update Access?

The exit and the flags can be used to enhance the model by customer specific needs. All base functions are already reflecting the user rights.

Parent topic: Common customizations


Component Types

In many places, the actions depend on certain library types. As these library types depend on your own ChangeMan customization and implementation, the model only delivers a default value set.

The defaults are:

ChangeMan Library types

SRC | program source
LST | compressed listing
LOD | LOAD module
JCL | JCL member

Client Suffixes

COB | COBOL program
JCL | JCL member

Search the model for these library types and suffixes, and replace/change them as required.

Parent topic: Common customizations


User Options

In ChangeMan, you have the ability to use many general user options, especially for component attributes.

To tailor it for your own use, use the ChangeMan Attachment and specify property labels with more meaningful names.

For example, change the Label property of the Audit parameter from lite to the more meaningful label Audit staging libraries only.

Label property of the Audit parameter

Parent topic: Common customizations


Property Cluster

Because the ChangeMan model has a large number of properties, (ChangeMan itself has a large amount of metadata), the following properties are clustered by use:

Property Prefix | Description
CMG_PROP_ xxx_ | General or common properties, such as CMG_PROP_ELE_Application for the application.
CMG_PROP_xxx_PP_ | For Package parameter. For example CMG_PROP_ELE_PP_auditReturnCode for the audit return code.
CMG_PROP_xxx_AP_ | For Audit parameter. For example CMG_PROP_DIA_AP_FormatReport for the Format Report flag.
CMG_PROP_xxx_CP_ | For Component parameter. For example CMG_PROP_ELE_CP_targetComponent for the target component at build.
CMG_PROP_xxx_IA_ | For impact analysis data. For example CMG_PROP_ELE_IA_relation for the relation type.
CMG_PROP_xxx_SSV_ | For staging version data. For example CMG_PROP_ELE_SSV_timeStamp for the version timestamp.
CMG_PROP_xxx_PR_ | For promotion/demotion related data. For example CMG_PROP_ELE_PR_promoter for the promoter.

Most property names relate to the ChangeMan XML tag names.

Parent topic: Common customizations


Build Dialog Box

The most customized ISPF dialog box in ChangeMan is the Build dialog box for components. To adapt this to your needs, you have to change the delivered build action, as required. This is the AWM Action CMG_ACT_BuildPackageComponent, and the dialog box referenced in this action is CMG_TOOL_AWM_UI_BuildComponent.

Parent topic: Common customizations


Workflow Manager AMB Attachment (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.
  • Introduction (Technology Preview)
  • Installing the AWM AMB Model File (Technology Preview)
Parent topic: Application Workflow Manager
Related concepts
Developing Applications in the Team Developer Perspective (Technology Preview)
AMB Endevor Interface (Technology Preview)


Introduction (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

The AWM AMB (AppMaster Builder) Attachment provides an interface between AMB on your local machine and CA Endevor on your mainframe. The AMB model delivered with the attachment provides the following functionality:

Add to Endevor
You can add AMB project members to Endevor (check in).
Retrieve from Endevor
You can retrieve members from Endevor into your AMB project (check out).
AMB in the Team Developer perspective
Most of the functionality of AppMaster Builder is available in the Team Developer perspective. This enables you to develop applications locally while keeping Endevor source synchronized with changes.

For details on using AMB with Endevor and on using AMB in the Team Developer perspective, see AMB Endevor Interface and Developing Applications in the Team Developer Perspective.

  • Software Requirements (Technology Preview)
  • Prerequisite (Technology Preview)
Parent topic: Workflow Manager AMB Attachment (Technology Preview)


Software Requirements (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

To use the AMB Attachment, you need the following product releases:

  • Enterprise Developer V4.0 or later.
  • Enterprise Developer AMB AddPack V4.0 or later.
  • For the AMB Endevor Interface only, CA Endevor Software Change Manager (SCM) Release 15 RAM (Repository Access Manager) or later.
Parent topic: Introduction (Technology Preview)


Prerequisite (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

If you plan to use the AMB Endevor Interface in addition to using AMB in the Team Developer view, you should Install the Workflow Manager Endevor Attachment on your z/OS host system. See Workflow Manager Endevor Attachment for details.

Parent topic: Introduction (Technology Preview)
Related concepts
Workflow Manager Endevor Attachment
Developing Applications in the Team Developer Perspective (Technology Preview)
AMB Endevor Interface (Technology Preview)


Installing the AWM AMB Model File (Technology Preview)

Restriction: This topic applies only when the AppMaster Builder AddPack has been installed, and applies only to Windows platforms.
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.

There are several ways to make the AWM AMB model available in the AWM Team Developer perspective, see Master Configuration in the Workflow Manager Modeling Guide for more information.

  1. Copy the provided AMB.model file from its default location in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\AMB to an alternative local location of your choice.
  2. To create a local master configuration file with the AMB application entries, copy the sample local master configuration file under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\AMB\MasterConfig.xml into your Eclipse root folder, and adapt the reference to the model location as described in the file. The default Eclipse root folder for Enterprise Developer is %PUBLIC%\Micro Focus\Enterprise Developer\eclipse.
    Note: If a MasterConfig.xml file already exists in the Eclipse root folder, merge the application entries from the AMB master configuration file into this existing master configuration file.
  3. Start Enterprise Developer.
  4. To add the local system to the Application Explorer view and load the AMB model, right-click the Application Explorer view, and then click Add System(s).

    This opens the Add System(s) dialog.

  5. Select AWM system from a local master configuration, and then click OK.
    Add System(s) dialog

    This adds the AppMasterBuilder system to the Application Explorer view.

  6. Right-click the AppMasterBuilder system; then select Load Application.

    This adds the AppMaster Builder default AMB project to the Application Explorer view.

    The installation process is now complete.

Parent topic: Workflow Manager AMB Attachment (Technology Preview)
Related concepts
Master Configuration


Workflow Manager Endevor Attachment

  • Introduction
  • Installation
  • The Endevor Attachment
  • Customization
Parent topic: Application Workflow Manager
Related concepts
AMB Endevor Interface (Technology Preview)


Introduction

The Workflow Manager Endevor Attachment consists of mainframe components which have to be installed in a z/OS environment.

CA Endevor® Software Change Manager (Endevor) supports the software configuration and change management of mainframe applications.

With the Endevor Attachment you can:

  • Provide the Endevor development process in an Eclipse environment.
  • Customize the Endevor development process to suit your needs.
  • Model and customize the Eclipse-based Endevor user interface without any programming effort.
  • Seamlessly integrate existing home-grown and third party tools in Eclipse.

This document is intended for system programmers and/or Endevor administrators installing and configuring the Workflow Manager Endevor Attachment on their z/OS host system.

This document refers to the Workflow Manager Endevor Attachment components as the Endevor Attachment.

  • Software Requirements
Parent topic: Workflow Manager Endevor Attachment


Software Requirements

To use the Endevor Attachment, you need the following product releases:

  • Enterprise Developer V2.3.1 or later
  • CA Endevor Software Change Manager (SCM) Release 15 RAM (Repository Access Manager) or later
Parent topic: Introduction


Installation

  • General considerations
  • Basic installation procedure
Parent topic: Workflow Manager Endevor Attachment


General considerations

Determine a dataset prefix that matches the naming convention in your company. This document uses the prefix HLQ.ENDEVOR in its specifications.

Parent topic: Installation


Basic installation procedure

  • Download and Unzip the Software
  • Upload the software to the mainframe
  • Receive the Software
Parent topic: Installation


Download and Unzip the Software

Download the Endevor Attachment from the download link you will receive from Micro Focus.

Unzip the file to a temporary folder. A folder named ENDEVOR is created, which contains all mainframe installation components.

There are no client components to install.

Parent topic: Basic installation procedure


Upload the software to the mainframe

Upload the endevor\install.xmit in binary format to a sequential dataset with a record length of 80 and a block size of 3120.

Firstly, on z/OS, allocate the datasets to use as the upload target files. To do this, create a dataset with the same characteristics as the sample job below (or by submitting the job below). If you choose to submit the job, note the following:

  • Before submitting, add a job card and modify the parameters to meet your site's requirements.
  • hlq is the high level qualifier you choose to use for this dataset.
  • Optionally, add a valid VOLSER and/or change the UNIT parameter.
//ALLOC1 EXEC PGM=IEFBR14
//*
//FTPALLOC DD DSN=hlq.INSTALL.XMIT,
// DISP=NEW,CATLG,DELETE),
// DSORG=PS,
// RECFM=FB,
// LRECL=80,
// BLKSIZE=3120,
//* VOL=SER=vvvvvv,
// UNIT=SYSALLDA,
// SPACE=(CYL,(5,5))

To upload the files, you can use FTP from a command prompt. In the sample dialog shown below, commands or other information entered by the user are in bold, and the following values are assumed:

User input | Description
mvsaddr | TCP/IP address or hostname of the z/OS system
tsouid | Your TSO user ID
tsopw | Your TSO password
hlq | High-level qualifier used for the dataset you allocated in the job above
C:\>ftp mvsaddr
Connected to mvsaddr.
220-FTPD1 IBM FTP CS V1R10 at custom.com, 12:03:32 on 2011-08-02.
220 Connection will close if idle for more than 5 minutes.
User (mvsaddr:(none)): tsouid
331 Send password please.
Password: tsopw
230 tsouid is logged on. Working directory is "tsouid.".
ftp> cd ..
250 " " is the working directory name prefix.
ftp> cd hlq
250 "hlq." is the working directory name prefix.
ftp> binary
200 Representation type is Image
ftp> put d:\endevor\install.xmit
200 Port request OK.
125 Storing dataset hlq.INSTALL.XMIT
250 Transfer completed successfully.
FTP: 2675840 bytes sent in 7,91 seconds 70,59 KB/sec
Parent topic: Basic installation procedure


Receive the Software

Using the TSO RECEIVE command creates the partitioned dataset from the compressed XMIT file. This document takes hlq.ENDEVOR to be the installation prefix.

Enter TSO or Workstation commands below:

===> receive in dataset('hlq.INSTALL.XMIT')

When prompted, enter:

INMR906A Enter restore parameters or 'DELETE' or 'END' +
restore dataset('hlq.ENDEVOR.INSTALL.XMIT’)

You should receive the following messages:

COPY INDD=((SYS00031,R)),OUTDD=SYS00030
IEB1013I COPYING FROM PDSU  INDD=SYS00031 VOL=USR001DSN= SYS11214.T134430…
IEB1014I         TO PDS  OUTDD=SYS00030 VOL=USR002 DSN=hlq.ENDEVOR.XMIT
IEB167I FOLLOWING MEMBER(S) LOADED FROM INPUT DATA SET REFERENCED BY SYS00031
IEB154I REXX     HAS BEEN SUCCESSFULLY LOADED
IEB154I NDVRECE  HAS BEEN SUCCESSFULLY LOADED
IEB154I CNTL     HAS BEEN SUCCESSFULLY LOADED
IEB154I COBOL    HAS BEEN SUCCESSFULLY LOADED
IEB154I LOAD     HAS BEEN SUCCESSFULLY LOADED
IEB154I SKELS    HAS BEEN SUCCSESSFULLY LOADED
IEB154I AWMMODEL HAS BEEN SUCCESSFULLY LOADED
IEB1098I 7 OF 7 MEMBERS LOADED FROM INPUT DATA SET REFERENCED BY SYS00031
…
IEB147I END OF JOB - 0 WAS HIGHEST SEVERITY CODE
INMR001I Restore successful to dataset 'hlq.ENDEVOR.INSTALL.XMIT'

The result is a partitioned dataset with the following members:

BROWSE       hlq.ENDEVOR.INSTALL.XMIT                         Volume: PROJ00
 Command ===>                                                    Scroll: CSR
            Name     Prompt       Size   Created          Changed          ID
_________ REXX
_________ CNTL
_________ NDVRECE
_________ COBOL
_________ LOAD
_________ SKELS
_________ AWMMODEL
          **End**

Each member except NDVRECE is a compressed dataset:

Member | Description
REXX | REXX procedures to execute Endevor functions called from the Client via TCP/IP
CNTL | JCL samples
NDVRECE | JCL to receive all other members
COBOL | COBOL sources which contain the Endevor API calls
LOAD | LOAD library which can be used as the target library for the compile/link output of the COBOL sources
SKELS | ISPF Skeletons
AWMODEL | The Endevor model file

You must use the TSO RECEIVE command again for the following members to create all necessary datasets:

Member | Receive to PDS
REXX | hlq.ENDEVOR.REXX
CNTL | hlq.ENDEVOR.CNTL
COBOL | hlq.ENDEVOR.COBOL
LOAD | hlq.ENDEVOR.LOAD
SKELS | hlq.ENDEVOR.SKELS
AWMMODEL | hlq.ENDEVOR.AWMMODEL

Member NDVRECE (already received) contains a receive sample batch job:

//STEP1    EXEC PGM=IKJEFT01
//SYSPRINT DD   SYSOUT=*
//SYSTSPRT DD   SYSOUT=*
//SYSTSIN  DD   *
 RECEIVE  INDSNAME('hlq.ENDEVOR.XMIT(REXX)') NONAMES
 DATASET('hlq.ENDEVOR.REXX')
 RECEIVE  INDSNAME('hlq.ENDEVOR.XMIT(CNTL)') NONAMES
 DATASET('hlq.ENDEVOR.CNTL')
 RECEIVE  INDSNAME('hlq.ENDEVOR.XMIT(COBOL)') NONAMES
 DATASET('hlq.ENDEVOR.COBOL')
 RECEIVE  INDSNAME('hlq.ENDEVOR.XMIT(LOAD)') NONAMES
 DATASET('hlq.ENDEVOR.LOAD')
 RECEIVE  INDSNAME('hlq.ENDEVOR.XMIT(SKELS)') NONAMES
 DATASET('hlq.ENDEVOR.SKELS')
 RECEIVE  INDSNAME('hlq.ENDEVOR.XMIT(AWMMODEL)') NONAMES
 DATASET('hlq.ENDEVOR.AWMMODEL')
/*

Verify that each RECEIVE has been successfully processed, e.g. the SYSTSPRT output from the batch job should end with “Restore successful” for each type received:

Restore successful to dataset 'hlq.ENDEVOR.type'

You should give the received dataset containing the AWM model the low-level qualifier AWMMODEL. In the Team Developer perspective of Enterprise Developer a file mapping is defined for datasets with the low-level qualifier AWMMODEL which ensures that members of an AWMMODEL dataset are downloaded with the code page IBM-037. This ensures that special characters contained in the AWMMODEL member are correctly interpreted when the model is loaded on the client-side.

If you use another low-level qualifier for the model dataset than AWMMODEL, you have to ensure that a corresponding file mapping is defined on the client-side.

Parent topic: Basic installation procedure


The Endevor Attachment

  • Overview of REXX procedures
  • Overview of Endevor API COBOL Programs
  • Overview of Endevor ISPF Skeletons
Parent topic: Workflow Manager Endevor Attachment


Overview of REXX procedures

The following REXX procedures are part of the Endevor Attachment:

REXX Name | Description
Endevor Element Actions |
TAUENBEL | Get Endevor element source for Browse
TAUENBLL | Get Endevor element informations (BE, HE, CE, BX, CX, HX, LL)
TAUENBLM | List an Endevor member using the Print function
TAUENEAC | Create a temporary sequential dataset
TAUENEAD | Add an Endevor element
TAUENECR | Create a new Endevor element
TAUENECS | Check if required element action is allowed
TAUENEDE | Delete an Endevor element
TAUENEED | Process functions used during a remote Edit action: retrieve, add, generate
TAUENEGE | Generate an Endevor element in place
TAUENEG1 | Generate an Endevor element
TAUENEMO | Move an Endevor element
TAUENERE | Retrieve an Endevor element
TAUENESI | Sign in / sign out
TAUENETR | Transfer an Endevor element
TAUENEVA | Validate an Endevor element
Endevor Package Actions |
TAUENPA1 | Process Endevor Packages, Actions Approve, Deny, Backin, Backout, Commit, Inspect, Execute, Reset
TAUENPCA | Process Endevor Packages, Actions Create, Modify, Cast
TAUENPDE | Process Endevor Packages, Actions Delete
Endevor Filter Actions | For Table Structures
TAUENFEL | Create an Endevor element table using search filter
TAUENGPK | Create an Endevor package table using search filter
Endevor Table and Tree Actions | For Table and Tree Structures
TAUENGCI | Get list of used CCIDs for tree view
TAUENGEL | Get element list for tree and table view
TAUENGEN | Get environment list for tree view
TAUENGLC | Get component level list for table view
TAUENGLV | Get element level list for table view
TAUENGOP | Get Endevor site options
TAUENGPR | Get processor group list for tree view
TAUENGSB | Get subsystem list for tree view
TAUENGST | Get stage list for tree view
TAUENGSY | Get system list for tree view
TAUENGTV | Get tree view types for tree view (Environment view / CCID view)
TAUENGTY | Get type list for tree view
TAUENPST | Get package status for tree view
Determination of Endevor Properties | To Complete the Properties View
TAUENEPR | Determine the properties of an Endevor element or element level
TAUENGPK | Determine the properties of an Endevor package
Endevor Select Values Actions |
TAUENLEN | Determine valid Endevor environment
TAUENLPR | Determine valid Endevor processor groups
TAUENLSB | Determine valid Endevor subsystems
TAUENGPK | Create an Endevor package table using search filter
TAUENLSI | Determine valid Endevor stage IDs
TAUENLSN | Determine valid Endevorstage numbers
TAUENLSY | Determine valid Endevor systems
TAUENLTY | Determine valid Endevortypes
Utilities | Used as Subroutines
TAUENS01 | Used in an Endevor simulation environment only
TAUENS02 | Get Endevor definitions
TAUENS03 | Get Endevor element container data
TAUENS04 | Get Endevor element level information
TAUENS05 | Get Endevor element listings
TAUENS06 | Get data for container CMP, CMPOBJ, CMPCOM. Scan the component list and extract input and output components
TAUENS07 | Print Endevor member
TAUENS08 | Get Endevor element source
TAUENS09 | Check if a ddname is already allocated
TAUENS10 | Call Endevor API SCL processor in foreground mode
TAUENS11 | Call Endevor API SCL processor in foreground mode
TAUENS12 | Call Endevor API SCL processor batch
TAUENS20 | Call Endevor API for package information
TAUENS21 | Used in an Endevor simulation environment only
Exits for Endevor |
TAUENXA1 | Allocation of temporary files for Endevor Attachment
TAUENXA2 | Change type properties to be returned to the client (for example file extension)
TAUENXCI | Get a list of valid CCIDs to be used for element action association
TAUENXCO | Set local compiler options (COMPOPT) for background parsing (called by REXX TAUENXSL)
TAUENXCS | Check the selected elements before a mass action is processed
TAUENXSL | Set property group and SYSLIB for background parsing
TAUENXTV | Define entries and labels of the tree view
Initialization / End Processing |
TAUENINI | Initialize the Endevor model (must be called in TAUTOXA1)
TAUENEND | Close Endevor
Parent topic: The Endevor Attachment


Overview of Endevor API COBOL Programs

The following COBOL Sources are used:

COBOL Name | Description
TAUENP01 | Get Endevor definitions
TAUENP02 | Get Endevor element information
TAUENP03 | Shutdown the Endevor API
TAUENP04 | Put all element change levels in a dataset
TAUENP05 | Run Endevor actions
TAUENP06 | Get Endevor package information
Parent topic: The Endevor Attachment


Overview of Endevor ISPF Skeletons

The following ISPF Skeletons are used:

COBOL Name | Description
TAUENSAD | Skeleton to process Endevor Administrations SCL
TAUENSEL | Skeleton to process Endevor Element SCL
TAUENSLI | Skeleton to include a single line
TAUENSPK | Skeleton to process Endevor Package SCL
Parent topic: The Endevor Attachment


Customization

Before using the Endevor Attachment for the first time, you must perform some modifications.

  • Compile and Link the COBOL Sources
  • Add the Endevor Workflow Model to the Master Configuration File
  • Allocate Additional Datasets to the z/Server User Task
  • Optional: Add the LOAD, EXEC and SKELS Datasets to ISPF.conf
  • Customizing REXX procedures
  • Customizing Endevor Processors
Parent topic: Workflow Manager Endevor Attachment


Compile and Link the COBOL Sources

You need to compile and link all the COBOL sources in hlq.ENDEVOR.COBOL. The following sample compile and link job COBLNK is delivered in hlq.ENDEVOR.CNTL:

      //JOBCARD
//*---------------------------------------------------------------------
//PCOBLNK  PROC MEMBER=,                      * MEMBER NAME SRC AND LOAD
//         LOADLIB=HLQ.ENDEVOR.LOAD,          * TARGET LOAD LIBRARY
//         SRCDSN=HLQ.ENDEVOR.COBOL,          * SOURCE DATASET
//         TDISK=SYSDA,                       * UNIT
//         LELKED=CEE.SCEELKED,               * LE SCEELKED
//         STEPCOB=IGY420.SIGYCOMP,           * LE COBOL COMPILER
//         COPYLIB=ENDEVOR.CSIQOPTN           * ENDEVOR CSIQOPTN
//**********************************************************************
//* COMPILE THE PROGRAM
//**********************************************************************
//COB      EXEC PGM=IGYCRCTL,
//         COND=(4,LT),
//         PARM='LIST,MAP,LIB,RENT,SOURCE,DYN'
//STEPLIB  DD DISP=SHR,DSN=&STEPCOB
//SYSIN    DD DISP=SHR,DSN=&SRCDSN(&MEMBER)
//SYSLIB   DD DISP=SHR,DSN=&COPYLIB
//SYSLIN   DD DSN=&&SYSLIN,
//            DISP=(NEW,PASS),
//            UNIT=&TDISK,
//            DSORG=PS,RECFM=FB,LRECL=80,BLKSIZE=3120,
//            SPACE=(CYL,(5,5),RLSE)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD SYSOUT=*
//SYSUT1   DD SPACE=(3120,(500,100),,,ROUND),UNIT=&TDISK
//SYSUT2   DD SPACE=(3120,(500,100),,,ROUND),UNIT=&TDISK
//SYSUT3   DD SPACE=(3120,(500,100),,,ROUND),UNIT=&TDISK
//SYSUT4   DD SPACE=(3120,(500,100),,,ROUND),UNIT=&TDISK
//SYSUT5   DD SPACE=(3120,(500,100),,,ROUND),UNIT=&TDISK
//SYSUT6   DD SPACE=(3120,(500,100),,,ROUND),UNIT=&TDISK
//SYSUT7   DD SPACE=(3120,(500,100),,,ROUND),UNIT=&TDISK
//**********************************************************************
//* LINK EDIT THE COBOL PROGRAM
//**********************************************************************
//LNK      EXEC PGM=IEWL,
//         COND=(4,LT),
//         PARM='AMODE=31,RMODE=ANY,LIST,XREF,RENT,REUS'
//SYSLIN   DD  DSN=&&SYSLIN,DISP=(OLD,DELETE)
//SYSLMOD  DD  DISP=SHR,DSN=&LOADLIB(&MEMBER)
//SYSLIB   DD  DISP=SHR,DSN=&LELKED
//SYSUT1   DD  DSN=&&SYSUT1,UNIT=&TDISK,SPACE=(1024,(50,20))
//SYSPRINT DD  SYSOUT=*
//   PEND
//*---------------------------------------------------------------------
// EXEC PCOBLNK,MEMBER=TAUENP01
// EXEC PCOBLNK,MEMBER=TAUENP02
// EXEC PCOBLNK,MEMBER=TAUENP03
// EXEC PCOBLNK,MEMBER=TAUENP04
// EXEC PCOBLNK,MEMBER=TAUENP05
// EXEC PCOBLNK,MEMBER=TAUENP06

Before you submit this job you must perform some customizations:

  • Enter a valid jobcard

  • Change the HLQ to your installation’s first qualifier

  • Verify the dataset name of the link library and change the name if necessary

  • Verify the dataset name where the COBOL compiler is installed and change the name if necessary

  • Enter a valid unit parameter or delete this parameter if it is not necessary in your system environment

  • Change the first qualifiers of the CSIQOPTN dataset to the ENDEVOR installation prefix

  • If your Endevor installation is release R15 or lower, you must change the COBOL source program TAUENP06. You must uncomment the field definitions in the Working-Storage Section belonging to the 01 field level R15-FIELDS.

Submit the job and verify that all compile and link steps were successfully executed.

If the job runs successfully, the load library HLQ.ENDEVOR.LOAD should contain seven members; the member DUMMY and six members TAUENPnn (nn=01 to 06).

Parent topic: Customization


Add the Endevor Workflow Model to the Master Configuration File

Edit the Master Configuration file and insert the following reference to the Endevor workflow model:

*
* Endevor Workflow Model for Enterprise Developer
*
* application name
User:
Appl: Endevor Application
* location of the application configuration file
Conf: MVS:HLQ.ENDEVOR.AWMMODEL(NDV400)
Property: NDV_PROP_STATIC_Client_env=ED
* application version number
Version: 4.0.0
* process information
INFO:
* end of application definition. Do not delete this line
EndAppl:
EndUser:

You must customize the Conf: entry to reference the installed AWMMODEL data set. Create a backup copy of the member NDV400 before you start to customize the Endevor model.

If the Endevor Model is installed in an IDz environment, you must set the property NDV_PROP_STATIC_Client_env to RDZ instead of ED and you must reference the XML member NDV400R instead of NDV400.

The Endevor Attachment delivery contains the model NDVAC40. This model combines the integration of Endevor, AccuRev and the Enterprise Developer projects model. It is intended to be used as part of Enterprise Sync. This model requires installation of Enterprise Developer 3.0 or higher. If this model is used the property NDV_PROP_STATIC_Client_env must be set to ED in the Master Configuration.

Parent topic: Customization


Allocate Additional Datasets to the z/Server User Task

Within the z/Server User Task, you must allocate all datasets necessary to run Endevor and the Endevor Attachment in an ISPF batch environment.

To be able to access the Endevor Attachment, you must allocate the received REXX library to SYSEXEC, and the LOAD library to the STEPLIB and the Skeleton library to ISPSLIB.

It is recommended that you customize the JCL of the z/Server User Task to perform this allocation. Alternatively, instead of a static allocation you can dynamically allocate the REXX and the Skeleton datasets by customizing the exit procedure TAUTOXA1. See the Workflow Manager Modeling Guide for more details.

If the Endevor product load modules don't reside in the LINKLIST you have to allocate the Endevor product load libraries using the STEPLIB of the z/Server user task. This also applies if you want to use another set of Endevor product libraries than those allocated in the LINKLIST for example if you want to test a new Endevor release.

Please keep in mind that Endevor CSIQAUTU and CSIQUATH must be APF authorized libraries. Therefore all other STEPLIB datasets must be APF authorized as well if you are using those libraries in the STEPLIB concatenation. In the following sample you will have to uncomment the relevant DD statements and replace NDVHLQ by the high level qualifier of your Endevor product libraries.

For more information on customizing the z/Server User Task see your z/Server Installation Guide.

……
//STEPLIB  DD DSN=&TAURHLQ..LOADLIB,DISP=SHR
//         DD DSN=HLQ.ENDEVOR.LOADLIB,DISP=SHR
//*        DD DSN=NDVHLQ.CSIQAUTU,DISP=SHR
//*        DD DSN=NDVHLQ.CSQAUTH,DISP=SHR
//*        DD DSN=NDVHLQ.CSIQLOAD,DISP=SHR
//*        DD DSN=NDVHLQ.CAILIB,DISP=SHR
//SYSEXEC  DD DSN=&TAURHLQ..EXEC,DISP=SHR
//         DD DSN=HLQ.ENDEVOR.REXX,DISP=SHR
//ISPPLIB  DD DSN=&ISPFHLQ..SISPPENU,DISP=SHR
//         DD DSN=ISF.SISFPLIB,DISP=SHR
//ISPSLIB  DD DSN=&ISPFHLQ..SISPSENU,DISP=SHR
//         DD DSN=HLQ.ENDEVOR.SKELS,DISP=SHR
//         DD DSN=&TAURUHLQ..SKELS,DISP=SHR
//         DD DSN=ISF.SISFSLIB,DISP=SHR
//ISPMLIB  DD DSN=&ISPFHLQ..SISPMENU,DISP=SHR
//         DD DSN=ISF.SISFMLIB,DISP=SHR
……
Parent topic: Customization
Related information
ISPF Exits


Optional: Add the LOAD, EXEC and SKELS Datasets to ISPF.conf

If the Endevor Attachment is used within IBM Developer for z Systems with the IBM RSE daemon as server, you need to add the installation EXEC and SKELS datasets to the configuration file ISPF.conf in the USS configuration path of the RSE daemon.

Additionally you have to specify the Endevor Attachment load library (HLQ.ENDEVOR.LOADLIB) using STEPLIB assignment of the ISPZXENV REXX procedure which is part of the ISPF Client Gateway. By default, the REXX ISPZXENV resides under /usr/lpp/ispf/bin in the USS subsystem.

If the Endevor product load modules don't reside in the LINKLIST you have to specify the Endevor product load libraries under the STEPLIB assignment of ISPZXENV as well. This also applies if you want to use another set of Endevor product libraries than those allocated in the LINKLIST, for example, if you want to test a new Endevor release.

The STEPLIB assignment in ISPZXENV has the following structure:

      STEPLIB = HLQ.ENDEVOR.LOADLIB:NDVHLQ.CSIQAUTU:NDVHLQ.CSIQAUTH:NDVHLQ.CSIQLOAD:NDVHLQ.CAILIB'

Replace NDVHLQ by the high level qualifier of your Endevor product libraries. Note that Endevor CSIQAUTU and CSIQUATH must be APF-authorized libraries. Thus, all other libraries assigned to STEPLIB must be APF-authorized as well.

Parent topic: Customization


Customizing REXX procedures

  • General Customization
  • Endevor Attachment Initialization Procedure TAUENINI
  • Endevor Allocation Exit TAUENXA1
  • File Extension and Dataset Format Assignment Using the Exit TAUENXA2
  • Selection of valid CCIDs using Exit TAUENXC1
  • Check Elements before Processing an Action using Exit TAUENXCS
  • Set the SYSLIB Datasets for Syntax Checking using TAUENXSL
  • Set Compiler Options (COMOPT) for background parsing TAUENXCO
  • Modify Tree View Entries using Exit TAUENXTV
Parent topic: Customization


General Customization

The following adaptations are of special importance:

REXX Procedure | Description
TAUZCAPP | If the Endevor attachment is used within Enterprise Developer with z/Server as server, adjust the reference to the location of the master configuration file, as required.
TAULAPPL | If the Endevor attachment is used within IBM Developer for z Systems with the IBM RSE daemon as server, adjust the reference to the location of the master configuration file, as required.
TAUTOXA1 Tool interface exit: you may use this exit for dynamic allocations or to set the ISPF environment variables necessary to run your specific Endevor application.
Note: You must add a call of the procedure TAUENINI shipped with the Endevor Attachment in TAUTOXA1.

To minimize the number of calls during a user task session, add the following statements somewhere after the variable TAUTOALC has been retrieved from the ISPF shared pool:

Call ISPF '8 VGET (TAUTOALC) SHARED'
….
/* Endevor Init */
Call ISPF '8 VGET (#ALLVAR) SHARED'
If Result = 0 Then Do
   If tautoalc /= p_parm Then
      Call REXX '0 TAUENINI' p_parm
   End
Else
   Call REXX '0 TAUENINI' p_parm
/* End of Endevor Init */

Skeleton Name | Description
TAUTOXJC | Skeleton for Batch-Support Define a default Job Card. The Endevor Attachment uses this skeleton if the user submits an Endevor batch job.

You will find more details about the general adaptations in your Workflow Manager Modeling Guide.

Parent topic: Customizing REXX procedures
Related information
Master Configuration on z/OS
ISPF Exits


Endevor Attachment Initialization Procedure TAUENINI

The REXX procedure TAUENINI defines ISPF shared pool variables which are used in other REXX procedures. Review these variables and adapt the values to your site standards.

In addition, TAUENINI defines the JCL statements used for generating Endevor batch jobs.

Review the JCL statements and adapt the JCL to your site standards.

Following variables are of special interest:

Variable name | Description
#AREA | Allowed values are SIMU or PROD. The Endevor Attachment allows you to simulate the most important Workflow Manager Endevor actions. Use the value SIMU if Endevor is currently not installed. Otherwise use the value PROD which is the default value. By default the model application options exit parameter is used to pass this execution mode information to TAUENINI. The default model entry is PROD.
#SAMPDSN | This variable is only relevant if the Endevor attachment is used in simulation mode, where #AREA has the value SIMU. #SAMPDSN references a partitioned dataset which contains sample data used to simulate an Endevor repository.
#SEP | This variable defines the parameter separator used in the Endevor model. If you have to change this value it is necessary to change this value in the Endevor model XML file as well.
#HLQ2 | This variable defines the second qualifier for temporary datasets used within the Endevor Attachment. See the description of the exit procedure TAUENXA1 to find more details about the usage of temporary datasets.
#APICLSE | Allowed values are Y or N. Y is the default and Micro Focus does currently not recommend changing this value. Setting the value N would mean that an Endevor API will not close the Endevor connection. By using the value N you must make sure that the REXX procedure TAUENEND is called before ISPF is closed in the z/Server user server.

It is recommended to keep the default values for the variables in the table unless your naming conventions inhibit it.

Parent topic: Customizing REXX procedures


Endevor Allocation Exit TAUENXA1

Data is partially interchanged using files for the communication between the client and the Endevor Attachment. The creation of the temporary files is done as part of the procedure TAUENXA1. TAUENXA1 should be adjusted to the available environment as needed.

Files which begin with userid.TAUENTMP are created by default. These files are temporary but are not deleted automatically within the tool attachment. Instead, once created, they can be reused.

We advise that you place these files on a work unit and allow them to be deleted after being inactive for a long period of time.

Parent topic: Customizing REXX procedures


File Extension and Dataset Format Assignment Using the Exit TAUENXA2

A Workflow Manager local file must contain the correct file extension (for example cbl, jcl) in order for it to be opened with the required editor.

By default, the Endevor Attachment gets the dataset format information from Endevor. This information is passed to the Exit TAUENXA2 where you can adapt specific values if necessary.

If, for example, the file extension is not maintained in Endevor, you should use TAUENXA2 to associate the correct file suffix. To do this, locate the label set_defaults in TAUENXA2 and adapt the file extension variable o_fileext to your needs depending on the input parameter i_type, which contains the value of the Endevor element type.

Note: We recommend you use lowercase file extensions. Although filenames are not case sensitive in a Windows system environment, some standard Eclipse file actions like Copy are case sensitive.
Parent topic: Customizing REXX procedures


Selection of valid CCIDs using Exit TAUENXC1

If you allow your Endevor user to associate only valid CCIDs that are maintained outside of Endevor, you can customize this Exit procedure to create a valid selection list.

TAUENXC1 is called in dialogs using the search button besides the CCID editable field.

Parent topic: Customizing REXX procedures


Check Elements before Processing an Action using Exit TAUENXCS

TAUENXCS supports restricting mass processing actions to specific selected elements.

For example, allowing a MOVE mass processing action only if all elements are selected from the same environment and stage.

It is possible to check the following Endevor keys: Environment, Stage ID, System, Subsystem, Type, and Element.

TAUENXCS is called before the dialog of a mass processing action is displayed.

Parent topic: Customizing REXX procedures


Set the SYSLIB Datasets for Syntax Checking using TAUENXSL

Use the REXX TAUENXSL to set the correct SYSLIB datasets if you want to support syntax checking in the context of the Enterprise Developer COBOL and PLI editor.

The SYSLIB values defined in TAUENXSL allow the editor's background parser to resolve COBOL copybooks or PLI includes.

If the Endevor Attachment is used in an IDz environment you have to set an existing Property Group and the Property Group Category, which will be used as a template to associate the SYSLIB datasets. Although both values are not relevant in the Enterprise Developer IDE, you still have to specify a non-blank value, such as NONE.

Parent topic: Customizing REXX procedures


Set Compiler Options (COMOPT) for background parsing TAUENXCO

The exit TAUENXCO allows you to set the local compiler options for the background parser of the editor. This exit can be used to set the local compiler options depending on the Endevor processor groups. The exit is called from the user exit TAUENXSL.

To activate the exit it is necessary that an application specific attribute is defined in the Endevor model with the name COMPOPT and the value '&NDV_PROP_CompOpt.'. By default, this application specific attribute does not permit changes to TAUENXCO to take effect.

See Compiler Directives for more information on valid local compiler options.

The default local compiler option setting for a COBOL program is:

DIALECT(ENTCOBOL) CICSECM XDB(NOVALIDATE) EXECDLI

The default local compiler option setting for a PL/I program is:

-margins 1,72 -cics

Parent topic: Customizing REXX procedures


Modify Tree View Entries using Exit TAUENXTV

The REXX procedure TAUENXTV defines the high-level entries for the Endevor application, which are displayed in the Application Explorer view.

TAUENXTV allows you to change the labels or remove high-level entries from tree view.

Parent topic: Customizing REXX procedures


Customizing Endevor Processors

Although there is no need to adapt Endevor processors for using the Endevor Attachment you should check and, if required, adapt processors to support the full functionality of the Endevor Attachment.

  • Using the Endevor Keyword MONITOR
  • Supporting Error Feedback in COBOL Processors
  • Supporting Error Feedback in Assembler Processors
  • Supporting Error Feedback in PLI Processors
  • Supporting Error Feedback in C Processors
Parent topic: Customization


Using the Endevor Keyword MONITOR

To support the component actions Show Components, Show Input Components and Show Output Components you should use the MONITOR keyword for input and output components.

Parent topic: Customizing Endevor Processors


Supporting Error Feedback in COBOL Processors

In general AWM supports error feedback for COBOL, a function which displays mainframe COBOL Compiler messages in the Error Feedback view. Double-clicking on a compiler message opens the editor and marks all relevant lines.

To support error feedback in combination with the Endevor Attachment you should adapt all COBOL processors.

The following sample shows how to support error feedback in a COBOL processor:

Sample PROC statement:

//             SYSXMLLD=’Error-Feedback-Dataset',
//             PARMCOB='LIB,NOSEQ,OBJECT,APOST,ADATA',
//             PARMCOBX=',EXIT(ADEXIT(''/N 100 /W 50'',TAURTOCX))',
...

To support error feedback it is necessary to specify the ADATA and ADEXIT options like in the sample above.

Sample COBOL compile step:

//COMPILE EXEC PGM=IGYCRCTL,COND=(0,LT),MAXRC=4,
// PARM='&PARMCOB.&PARMCOBX.'
//STEPLIB DD DISP=SHR,
// DSN=HLQ.ZSERVER.LOADLIB  * zServer Loadlib which contains TAURTOCX
//SYSXMLSD DD DISP=SHR,
// DSN=&SYSXMLLD(&C1ELEMENT),
// MONITOR=COMPONENTS
//SYSADATA DD SPACE=(CYL(2,5)),RECFM=V
...

The error feedback data set must exist as a variable blocked partitioned data set with record length 16383.

Parent topic: Customizing Endevor Processors


Supporting Error Feedback in Assembler Processors

In general AWM supports error feedback for Assembler, a function which displays mainframe Assembler errors in the Error Feedback view. Double-clicking on a message opens the editor and marks all relevant lines.

To support error feedback in combination with the Endevor Attachment you should adapt all Assembler processors.

The following sample shows how to support error feedback in an Assembler processor:

Sample PROC statement:

//             SYSXMLLD=’Error-Feedback-Dataset',
//             PARMASM='XREF(SHORT),LINECOUNT(75),OBJECT,ADATA',
//             PARMASMX=',EXIT(ADEXIT(TAURTOAX(''/N 100 /W 25'')))',
...

To support error feedback you have to specify the ADATA and ADEXIT options as in the above sample.

Sample Assembler step:

//COMPILE EXEC PGM=ASMA90,COND=(0,LT),MAXRC=4,
// PARM='&PARMASM.&PARMASMX.'
//STEPLIB DD DISP=SHR,
// DSN=HLQ.ZSERVER.LOADLIB  * zServer Loadlib which contains TAURTOAX
//SYSXMLSD DD DISP=SHR,
// DSN=&SYSXMLLD(&C1ELEMENT),
// MONITOR=COMPONENTS
//SYSADATA DD SPACE=(CYL(2,5)),RECFM=V
...

The error feedback data set must exist as a variable blocked partitioned data set with record length 16383.

Parent topic: Customizing Endevor Processors


Supporting Error Feedback in PLI Processors

In general AWM supports error feedback for PLI, a function which displays mainframe PLI compiler messages in the Error Feedback view. Double-clicking on a compiler message opens the editor and marks all relevant lines.

To support error feedback in combination with the Endevor Attachment you should adapt all PLI processors.

The following sample shows how to support error feedback in a PLI processor:

Sample PROC statement:

//             SYSXMLLD=’Error-Feedback-Dataset',
//             PARMPLI='MACRO,OBJECT,SOURCE,XREF,XINFO(XML)',
...

The XINFO(XML) compiler option is required to support error feedback.

Sample PLI compile step:

//COMPILE EXEC PGM=IBMZPLI,COND=(0,LT),MAXRC=4,
// PARM='&PARMPLI.'
//SYSXMLSD DD DISP=SHR,
// DSN=&SYSXMLLD(&C1ELEMENT),
// MONITOR=COMPONENTS
...

The error feedback data set must exist as a variable blocked partitioned data set with record length 16383.

Parent topic: Customizing Endevor Processors


Supporting Error Feedback in C Processors

In general AWM supports error feedback for C, a function which displays mainframe C compiler messages in the Error Feedback view. Double-clicking on a compiler message opens the editor and marks all relevant lines.

To support error feedback in combination with the Endevor Attachment you should adapt all C processors.

The following sample shows how to support error feedback in a C processor:

Sample PROC statement:

//             SYSXMLLD=’Error-Feedback-Dataset',
//             PARMC='/EVENTS,SSCOM,SO,LO,NOMAR,RENT',
...

The /EVENTS option is necessary to support error feedback.

Sample C compile step:

//COMPILE EXEC PGM=CCNDRVR,COND=(0,LT),MAXRC=4,
// PARM='&PARMC.'
//SYSEVENT DD DSN=&&SYSEVENT,DISP=(,PASS,DELETE),
//     UNIT=&WRKUNIT,SPACE=(TRK(30,100),RLSE),
//     DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
 ...

Sample error feedback step:

//ERRFB  EXEC PGM=TAURTOEX,MAXRC=4
//STEPLIB DD DISP=SHR,
// DSN=HLQ.ZSERVER.LOADLIB  * zServer loadlib containing TAURTOEX
//SYSXMLSD DD DISP=SHR,
// DSN=&SYSXMLLD(&C1ELEMENT),
// MONITOR=COMPONENTS
//SYSEVENT DD DSN=&&SYSEVENT,DISP=(OLD,DELETE)
...

The error feedback data set must be defined as a variable blocked partitioned data set with record length 16383.

Parent topic: Customizing Endevor Processors


Workflow Manager SCLM Attachment

  • Introduction
  • Installation
  • The SCLM Attachment
  • Server and REXX customization
  • Customizing the SCLM model
Parent topic: Application Workflow Manager


Introduction

The Workflow Manager SCLM Attachment consists of mainframe components that have to be installed in a z/OS environment.

IBM Software Configuration and Library Manager (SCLM) is part of TSO/ISPF and supports the development of mainframe applications under ISPF.

With the Workflow Manager SCLM Attachment, you can:

  • Provide the SCLM development process in an Eclipse-based development environment.
  • Customize the SCLM development process to suit your needs.
  • Model and customize the Eclipse-based SCLM user interface without any programming effort.
  • Seamlessly integrate existing home-grown and third party tools.

This document is intended for system programmers and/or SCLM administrators installing and configuring the Workflow Manager SCLM Attachment on their z/OS host system.

Herein, this document refers to the Workflow Manager SCLM Attachment as the SCLM Attachment.

  • Software requirements
Parent topic: Workflow Manager SCLM Attachment


Software requirements

To use the SCLM Attachment, you require Enterprise Developer version 2.3.1 or later to be installed and configured.

Parent topic: Introduction


Installation

  • General considerations
  • Basic installation procedure
Parent topic: Workflow Manager SCLM Attachment


General considerations

Determine a dataset prefix that matches the naming conventions in your company. This document will use the prefix HLQ.SCLM in all further specifications.

Parent topic: Installation


Basic installation procedure

  • Download and unzip the software
  • Upload the software to the mainframe
  • Receive the software
Parent topic: Installation


Download and unzip the software

Download the SCLM Attachment from a download link you will receive from Micro Focus.

Unzip the download file to a temporary folder. A folder named ‘host’ is created, which contains all mainframe installation components in binary XMIT format.

There are no client components to install.

Parent topic: Basic installation procedure


Upload the software to the mainframe

The unzipped SCLM Attachment contains four XMIT files. Upload all files from the ‘host’ folder, in binary format, to sequential datasets with a record length of 80 and a block size of 3120, using the following procedure:

Firstly, on z/OS, allocate the datasets to use as the upload target files. To do this, create a dataset with the same characteristics as the sample job below or by submitting the job below. If you choose to submit the job, note the following:

  • hlq is the high-level qualifier you choose to use for this dataset.
  • Before submitting, add a job card and modify the parameters to meet your site's requirements.
  • Optionally, add a valid VOLSER and/or change the UNIT parameter.
//ALLOC1 EXEC PGM=IEFBR14
//*
//FTPALLOC DD DSN=hlq.SCLM.EXEC.XMIT,
// DISP=NEW,CATLG,DELETE),
// DSORG=PS,
// RECFM=FB,
// LRECL=80,
// BLKSIZE=3120,
//* VOL=SER=vvvvvv,
// UNIT=SYSALLDA,
// SPACE=(TRK,(45,15))

To upload the files, you can use FTP from a command prompt. In the sample dialog shown below, commands or other information entered by a user are displayed in bold, and the values in the following table are assumed:

User input | Description
mvsaddr | TCP/IP address or hostname of the z/OS system
tsouid | Your TSO user ID
tsopw | Your TSO password
hlq | High-level qualifier used for the data set you allocated in the job above
C:\>ftp mvsaddr
Connected to mvsaddr.
220-FTPD1 IBM FTP CS V1R10 at custom.com, 12:03:32 on 2011-08-02.
220 Connection will close if idle for more than 5 minutes.
User (mvsaddr:(none)): tsouid
331 Send password please.
Password: tsopw
230 tsouid is logged on. Working directory is "tsouid.".
ftp> cd ..
250 " " is the working directory name prefix.
ftp> cd hlq
250 "hlq." is the working directory name prefix.
ftp> binary
200 Representation type is Image
ftp> put d:\host\hlq.SCLM.EXEC.XMIT
200 Port request OK.
125 Storing data set hlq.SCLM.EXEC.XMIT
250 Transfer completed successfully.

Transfer the files hlq.SCLM.ARCHDEF.XMIT, hlq.SCLM.SKELS.XMIT and hlq.SCLM.AWMMODEL.XMIT to your mainframe system.

You now have the following files on your mainframe system:

  • HLQ.SCLM.EXEC.XMIT
  • HLQ.SCLM.ARCHDEF.XMIT
  • HLQ.SCLM.SKELS.XMIT
  • HLQ.SCLM.AWMMODEL.XMIT
Parent topic: Basic installation procedure


Receive the software

Use the TSO RECEIVE command to create the partitioned datasets from the sequential XMIT files. HLQ.SCLM is the assumed installation prefix.

Enter TSO or Workstation commands below:
 ===> receive indataset('hlq.SCLM.EXEC.XMIT')

When prompted, enter:

INMR906A Enter restore parameters or 'DELETE' or 'END' +
restore dataset('hlq.SCLM.EXEC’)

The result is a partitioned dataset containing REXX procedures.

Repeat the RECEIVE process for the SKELS, the AWMMODEL and the ARCHDEF datasets.

You should give the received dataset containing the AWM model the low-level qualifier AWMMODEL. In the Team Developer perspective of Enterprise Developer a file mapping is defined for datasets with the low-level qualifier AWMMODEL which ensures that members of an AWMMODEL dataset are downloaded with the code page IBM-037. This ensures that special characters contained in the AWMMODEL member are correctly interpreted when the model is loaded on the client-side.

If you use another low-level qualifier for the model dataset than AWMMODEL, you have to ensure that a corresponding file mapping is defined on the client-side.

Parent topic: Basic installation procedure


The SCLM Attachment

  • Overview of REXX procedures
  • Overview of ISPF skeletons
Parent topic: Workflow Manager SCLM Attachment


Overview of REXX procedures

All REXX procedures used within the SCLM Attachment are listed in an SCLM HLL architecture member. The architecture member name is TAUSCLM and is contained in HLQ.SCLM.ARCHDEF.

The dataset HLQ.SCLM.ARCHDEF is shipped for documentation only. However, you can migrate the shipped REXX procedures, ISPF skeletons and SCLM architecture members into your own SCLM project and use the architecture member TAUSCLM to build and promote the complete SCLM Attachment.

The following REXX procedures are part of the SCLM Attachment:

REXX name | Description
SCLM Member Actions |
TAUSCINS | Lock a new SCLM member and set its access key. A new member can be edited locally and later with check-in (TAUSCCIN) can be copied under the control of SCLM
TAUSCIN2 | Create a new member under SCLM
TAUSCCPY | Copy an SCLM member
TAUSCCIN | Check-in an SCLM member – After local edit
TAUSCCOU | Check-out an SCLM member – For local edit
TAUSCLCK | Set SCLM access key.
TAUSCBDO | SCLM Build
TAUSCPMO | SCLM Promote
TAUSCDEL | Delete an SCLM member
TAUSCRES | Remove SCLM access key
TAUSCGVM | Copy an SCLM member from the version inventory to the development group
TAUSCARC | Generate an SCLMsource from an SCLMarchitecturedefinition
TAUSCRSC | Remote syntax check for an SCLM source member
TAUSCRFR | Determine copies related to an SCLMsource
TAUSCNDS | Determine the next SCLM dataset in the hierarchythat contains a given member (i.e. relevant in use with Compare Next )
TAUSCSPR | Associate the Change Code and/or Language to an SCLM member
TAUSCBMP | Determine build map Information
TAUSCGCC | Determine information relating to associated Change Codes
SCLM Table Actions | For table structures
TAUSCELT | Create an SCLM member list
TAUSCSRC | Create an SCLM member list from SCLM text search
TAUSCGVE | Create an SCLM list of audit records corresponding to an SCLM member
TAUSCDLI | SCLMlistwith dependentmembers correspondingtoan SCLMmember (Build Map Context)
TAUSCDL2 | SCLM list with dependentmembers correspondingto an Archdef (Build Map Context)
Determination of SCLM Properties | To complete the Properties view
TAUSCEPR | Determine the properties of an SCLM member (SCLM Accounting Record)
TAUSCGVP | Determine the properties of a versioned SCLM member (SCLM Audit Record)
SCLM Structure Actions | For the tree structure
TAUSCGPR | Determine the SCLM project
TAUSCGPD | Determine all SCLM project definitions corresponding to an SCLMproject
TAUSCGGR | Determine all SCLM groups within a project definition
TAUSCGTY | Determine all SCLM types within a project definition
SCLM Value for Retrieve Actions |
TAUSCVPR | Determine valid SCLM projects
TAUSCVPD | Determine valid SCLM project definitions
TAUSCVGR | Determine valid SCLM groups
TAUSCVTY | Determine valid SCLM types
TAUSCGLA | Determine valid SCLM languages
Utilities | Used as subroutines
TAUSCINF | Determine valid SCLM groups, types, and languages from the SCLM project definition
TAUSCPRJ | Determine SCLM projects
TAUSCAPR | Determine SCLM project definitions
TAUSCMSU | Determine the Eclipse file suffix for a given SCLM member
TAUSCNGR | Determine the next SCLM group in the SCLM hierarchy
TAUSCLMS | Remove the SCLM flag from the ISPF statistics
TAUSCBDI | Get SCLM build information
Exits for SCLM |
TAUSCXA1 | Allocation of (temporary) files for the SCLM Attachment
TAUSCXMS | Exit to determine the Eclipse file suffix for a given SCLM member
TAUSCXBI | Exit to determine information from SCLM for the Remote Syntax Check (SYSLIB, Compile Parameter)
TAUSCXSL | Exit to determine the SYSLIB concatenation from SCLM
TAUSCXCO | Exit to determine local compiler options for the background parser. Called by exit TAUSCXSL
TAUSCXP1 | Exit to determine valid SCLM projects
TAUSCXP2 | Exit called when the SCLM project definition is changed
TAUSCXP3 | Exit to determine valid SCLM project definitions
SCLM Translator / Exits |
TAUSCBND | SCLM Build/Promote REXX sample for DB2 relevant languages: Execute Bind Plan or Bind Package
TAUSCPLA | SCLM Build Translator used to allocate SYSXMLSD which is necessary to support error feedback
TAUSCXBD | SCLM Build Notify exit, to inform about generated Build Output member
TAUSCXIN | Skeleton support for a new member
TAUSCXCC | REXX Translator sample supporting error feedback for C programs
Parent topic: The SCLM Attachment


Overview of ISPF skeletons

All ISPF skeletons that are used as part of an SCLM Attachment are listed in the SCLM architecture member named TAUSCLM.

The following ISPF skeletons are used:

Skeleton name | Description
TAUSCCOM | Skeleton for the generation of SCLM architecture definitions Generation of CC Archdef
TAUSCLNK | Skeleton for the generation of SCLM architecture definitions Generation of Link Archdef
TAUSCHLL | Skeleton for the generation of SCLM architecture definitions Generation of High Level Language (HLL) Archdef
TAUSCPKG | Skeleton for the generation of SCLM architecture definitions Generation of Bind Package REXX
TAUSCPLN | Skeleton for the generation of SCLM architecture definitions Generation of Bind Plan REXX
TAUSCSAC | Skeleton for a new COBOL member
TAUSCSAH | Skeleton for a new HLL Archdef member
TAUSCSAP | Skeleton for a new PLI member
TAUSCSAA | Skeleton for a new ASSEMBLER member
Parent topic: The SCLM Attachment


Server and REXX customization

Before using the SCLM Attachment for the first time, you have to perform some modifications to the supplied REXX procedures and ISPF skeletons.

  • Add the SCLM Workflow Model to the Master Configuration File
  • Add the EXEC and SKELS datasets to the z/Server User Task
  • Optional: Add the EXEC and SKELS datasets to ISPF.conf
  • Customizing REXX procedures and ISPF skeletons
Parent topic: Workflow Manager SCLM Attachment


Add the SCLM Workflow Model to the Master Configuration File

Edit the Master Configuration file and insert the following reference to the SCLM workflow model:

*
* SCLM Workflow Model
*
User:
Appl: SCLM Application
* location of the application configuration file
Conf: MVS:HLQ.SCLM.AWMMODEL(SCLM400)
* application version number
Version: 4.0.0
* process information
INFO:
* Application properties:
SCLM_PROP_STATIC_Client_Env=ED
EndAppl:
EndUser:

You must customize the Conf: entry to reference the installed XML data set.

If the SCLM attachment is used within IBM Developer for z Systems with the IBM RSE daemon as the server, you must change the client environment property value from ED to IDz, and the model member name from SCLM400 to SCLM400R.

You can find details of how to create an application entry to the Master Configuration file in your Workflow Manager Modeling Guide.

Parent topic: Server and REXX customization
Related information
Workflow Manager Modeling Guide


Add the EXEC and SKELS datasets to the z/Server User Task

Within the z/Server User Task, you must concatenate the received dataset HLQ.SCLM.EXEC to the SYSEXEC allocation, and add the received dataset HLQ.SCLM.SKELS to the ISPSLIB allocation.

Micro Focus recommends that you customize the JCL of the z/Server User Task to perform this allocation.

……
//IVPISPF  EXEC PGM=IKJEFT1B,PARM='%IVPINIT1 &PORT ',
//            DYNAMNBR=200,REGION=0M
//STEPLIB  DD DSN=&TAURHLQ..LOADLIB,DISP=SHR
//SYSEXEC  DD DSN=&TAURHLQ..EXEC,DISP=SHR
//         DD DSN=HLQ.SCLM.EXEC,DISP=SHR
//         DD DSN=&TAURHLQ..REXX,DISP=SHR
//ISPPLIB  DD DSN=&ISPFHLQ..SISPPENU,DISP=SHR
//         DD DSN=ISF.SISFPLIB,DISP=SHR
//ISPSLIB  DD DSN=&ISPFHLQ..SISPSENU,DISP=SHR
//         DD DSN=HLQ.SCLM.SKELS,DISP=SHR
//         DD DSN=ISF.SISFSLIB,DISP=SHR
//ISPMLIB  DD DSN=&ISPFHLQ..SISPMENU,DISP=SHR
//         DD DSN=ISF.SISFMLIB,DISP=SHR
……

For more information on customizing the z/Server User Task see your z/Server Installation Guide.

Alternatively, instead of a static allocation you can dynamically allocate both datasets by customizing the exit procedure TAUTOXA1. See the Workflow Manager Modeling Guide for more details.

Parent topic: Server and REXX customization
Related information
Workflow Manager Modeling Guide


Optional: Add the EXEC and SKELS datasets to ISPF.conf

If the SCLM attachment is used within IBM Developer for z Systems with the IBM RSE daemon as server, you must add the installation EXEC and SKELS datasets to the configuration file ISPF.conf in the USS configuration path of the RSE daemon.

Parent topic: Server and REXX customization


Customizing REXX procedures and ISPF skeletons

  • General customization
  • Customizing the Generation of SCLM Architecture Members
  • Adjustment of the Skeleton Support for Creating New Members
  • Exit TAUSCXA1: Allocation of Temporary Datasets
  • Exit TAUSCXBD: Tracking Build Outputs Using the SCLM Build Notify Exit
  • Exit TAUSCXMS: File Suffix Assignment
  • Exit TAUSCXP1: Determination of the relevant SCLM projects
  • Exit TAUSCXP2: Additional processing during SCLM project initialization
  • Exit TAUSCXP3: Determine relevant SCLM project definitions
  • Exit TAUSCXBI: Determination of build information
  • Exit TAUSCXSL: Determination of the SYSLIB concatenation
  • Exit TAUSCXCO: Determine local compiler options
  • Support for error feedback during SCLM build for COBOL
  • Support for Error Feedback during SCLM Build for PL/I
  • Support for error feedback during SCLM build for Assembler
  • Support for error feedback during SCLM build for C
Parent topic: Server and REXX customization


General customization

Regarding the SCLM Attachment, the following adaptations are of special importance:

REXX procedure | Description
TAUZCAPP | If the SCLM attachment is used within Enterprise Developer with z/Server as server, adjust the reference to the location of the master configuration file, as required.
TAULAPPL | If the SCLM attachment is used within IBM Developer for z Systems with the IBM RSE daemon as server, adjust the reference to the location of the master configuration file, as required.
TAUTOXA1 | Tool interface exit: use this exit for dynamic allocations or to set ISPF environment variables necessary to run your specific SCLM Application. With a standard SCLM installation you do not need to customize this exit.
TAUTOXA2 | General allocation exit: use the exit to allocate general temporary files. The REXX procedure is used within the SCLM Attachment to allocate temporary datasets when executing a string search in SCLM datasets.
TAUTOXCA | Exit for Assembler Remote Syntax Check: customize the library names and allocations, as required
TAUTOXCC | Exit for COBOL Remote Syntax Check: customize the library names and allocations, as required
TAUTOXCP | Exit for PLI Remote Syntax Check; customize the library names and allocations, as required
TAUTOXC3 | Exit for C Remote Syntax Check; customize the library names and allocations, as required
Skeleton name | Description
TAUTOXIS | Skeleton for batch support: allocates an ISPF batch environment The SCLM Attachment uses this skeleton if you submit an SCLM build for batch execution.
TAUTOXJC | Skeleton for batch support: defines a default job card The SCLM Attachment uses this skeleton if the user submits an SCLM build for batch execution.

You will find more details about the general adaptions in your Workflow Manager Modeling Guide.

Parent topic: Customizing REXX procedures and ISPF skeletons
Related information
Workflow Manager Modeling Guide


Customizing the Generation of SCLM Architecture Members

The SCLM model contains a sample action that generates all necessary architecture members belonging to an SCLM member. Before using this action, you should customize it, as required.

The included generation example uses the following components:

REXX /skeletons | Description
TAUSCMAR | REXX for generating SCLM architecture definitions corresponding to one or more SCLM sources. Adjustments are necessary during variable initialization (type names, language, and member) in the upper part of the procedure.
TAUSCCOM | Skeleton for generating SCLM architecture definitions Adjustments to the layouts for generating CC Archdefs are necessary
TAUSCLNK | Skeleton for generating SCLM architecture definitions Adjustments to the layouts for generating Link Archdefs are necessary
TAUSCHLL | Skeleton for generating SCLM architecture definitions Adjustments to the layouts for generating HLL Archdefs are necessary
TAUSCPKG | Skeleton for generating SCLM architecture definitions Adjustments for generating bind package REXX are necessary
TAUSCPLN | Skeleton for generating SCLM architecture definitions Adjustments for generating bind plan REXX are necessary
TAUSCBND | SCLM REXX sample for DB2 relevant languages: Execute Bind Plan or Bind Package (compare Skeletons TAUSCPKG, TAUSCPLN). Adaptation to the existing promote structure is necessary
Parent topic: Customizing REXX procedures and ISPF skeletons


Adjustment of the Skeleton Support for Creating New Members

The SCLM model contains an action that you can use to create a new SCLM member. A skeleton can be retrieved depending on the SCLM language. If no skeleton is assigned, an empty member is created. Generally, this action, including the skeleton to be used, must be adapted for each implementation.

The included example uses the following components:

REXX /skeletons | Description
TAUSCXIN | Insert exit Depending on the parameter passed as SCLM language, a skeleton is assigned
TAUSCSAC | Skeleton for a new COBOL member
TAUSCSAH | Skeleton for a new HLL Archdef member
TAUSCSAP | Skeleton for a new PL/I member
TAUSCSAA | Skeleton for a new ASSEMBLER member
Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXA1: Allocation of Temporary Datasets

Temporary files are used for communication between the client and the SCLM Attachment. The creation of these files takes place in the procedure TAUSCXA1. TAUSCXA1 should be adjusted to the available environment, as required.

Files that begin with userid.TAUSCTMP are created by default. These files are temporary in nature, but are not deleted automatically within the tool attachment. Instead, they can be reused once created, if necessary.

Micro Focus recommends that you place these files on a work unit and allow them to be deleted when inactive for a long period of time.

Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXBD: Tracking Build Outputs Using the SCLM Build Notify Exit

If the SCLM Attachment is to insert the generated output members directly in the current Table Results or Application Explorer view after a successful SCLM build, the build notify exit of the SCLM language definition must be active, and the procedure TAUSCXBD must be used as an exit name. If this exit has already been used, call the procedure TAUSCXBD as a sub-routine in the already-defined exit procedure.

The definition of a build exit occurs in the project definition using the macro FLMCNTRL:

         FLMCNTRL ACCT=SCLM.ACCOUNT.FILE,                              C
               VERS=SCLM.VERSION.FILE,                                 C
               BLDNTF=SELECT,                                          C
               BLDNTFCM=ISPLNK,                                        C
               BLDNTFOP='NEST CMD(TAUSCXBD,',                          C
               MAXVIO=999999,                                          C
               VIOUNIT=VIO
Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXMS: File Suffix Assignment

A file must contain the correct suffix (e.g. cbl, jcl) in order to be opened with the required editor.

The assignment of an SCLM member to a file suffix typically depends on its assigned SCLM language. In some cases, the SCLM type alone can also be enough to make this assignment possible.

You can use the exit TAUSCXMS to associate the values of the file suffix to the SCLM member.

As long as no specific editor exists for the SCLM member, the value txtshould be assigned as a suffix.

Note: This exit returns two additional output parameters called ‘Property Group’ and 'Property Group Category'; although not supported in an Enterprise Developer environment, you must still return a non-blank value (e.g. NONE). In IBM Developer for z Systems environments, both values can be used to associate an SCLM member with a specific Property Group.
Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXP1: Determination of the relevant SCLM projects

The SCLM application displays SCLM projects as first level elements in its tree structure. Furthermore, different dialogs exist through which SCLM projects can be selected.

You can determine the relevant SCLM projects for each respective user through the exit TAUSCXP1.

If this exit procedure is not adjusted, implying that no SCLM projects are specified, the tool attachment uses the naming convention *.PROJDEFS.LOAD to determine all available SCLM projects in the system. This process of determining all available SCLM projects may lead to unfavorable performance or the process being stopped by the system. In some systems, such dataset queries are not allowed. Therefore, Micro Focus strongly recommends that you provide the exit with the appropriate logic enabling it to determine the relevant SCLM projects.

Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXP2: Additional processing during SCLM project initialization

Exit TAUSCXP2 is invoked whenever the SCLM Attachment accesses or changes an SCLM project definition for the first time. For example, use this exit to set specific environment variables (ISPF shared pool or profile variables) relating to an SCLM project and SCLM project definition.

This is intended for the case where a custom-developed SCLM translator and SCLM exit uses environment variables that are set outside of SCLM. As long as values of the environment variables are not dependent on the SCLM project definition, Micro Focus recommends using the general exit TAUTOXAI instead of its SCLM exit.

Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXP3: Determine relevant SCLM project definitions

The SCLM application displays SCLM project definitions in the second level of its tree structure. You can further select an SCLM project definition using the Retrieve option. Use this exit to determine the relevant SCLM project definitions for each user.

All project definitions are available as load modules in the project.PROJDEFS.LOAD file, and without adaptation the tool attachment would interpret these member names as valid names for the project definitions. Micro Focus recommends that you use exit TAUSCXP3 to determine the relevant project definitions according to appropriate rules (e.g. naming conventions), or to filter out names that do not correspond to any project definition or that are for administrative purposes only.

Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXBI: Determination of build information

The exit TAUSCXBI determines build information from SCLM which is needed for remote syntax check. The shipped exit TAUSCXBI uses the SCLM build info command to determine this information.

The result of the SCLM build information is parsed and returned partly by Shared Pool variables and partly as return values.

The exit has to be adapted when the build info command provides other information on the customer site than that expected by the exit, e.g. another compiler name.

The exit can also be adapted if the required build information can be determined by another, possibly less expensive, way.

Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXSL: Determination of the SYSLIB concatenation

The exit TAUSCXSL determines the SYSLIB concatenation from SCLM. The shipped exit TAUSCXSL determines the SYSLIB concatenation by a call to the exit TAUSCXBI.

The exit should be adapted if there is another, possibly less expensive way, at the customer site to determine the SYSLIB concatenation.

Parent topic: Customizing REXX procedures and ISPF skeletons


Exit TAUSCXCO: Determine local compiler options

The exit TAUSCXCO enables you to set the local compiler options for the background parser of the editor. This exit can be used to set the local compiler options depending on the SCLM language of an element. The exit is called from the user exit TAUSCXSL.

To activate the exit it is necessary that an application specific attribute is defined in SCLMdevor model with the name COMPOPT and the value '&SCLM_PROP_SPECIFIC_CompOpt.'. By default, this application specific attribute is not defined so that changes to TAUSCXCO do not take effect.

See Compiler Directives for valid local compiler options.

The default local compiler option setting for a COBOL program is:
DIALECT(ENTCOBOL) CICSECM XDB(NOVALIDATE) EXECDLI
The default local compiler option setting for a PL/I program is:
-margins 1,72 -cics
Parent topic: Customizing REXX procedures and ISPF skeletons


Support for error feedback during SCLM build for COBOL

The SCLM Attachment supports error feedback for COBOL programs in connection with an SCLM build. Use the compiler option ADATA together with the COBOL exit TAURTOCX, and allocate the error feedback file as a member of a PDS file in a build translator. Use the REXX procedure TAUSCPLA for this purpose.

A maximum of 250 messages are returned from the exit. You can reduce this amount using the option /N. The maximum number of warning and informational messages is specified with /W, and this value must be fewer than the one specified for /N. If not specified, the default value is set to 20.

          FLMTRNSL   CALLNAM='XMLDAT',                                 C
               FUNCTN=BUILD,                                           C
               CALLMETH=ISPLNK,                                        C
               COMPILE=SELECT,                                         C
               VERSION=1.0,                                            C
               GOODRC=0,                                               C
               PDSDATA=Y,                                              C
               PORDER=1,                                               C
               OPTIONS='CMD(TAUSCPLA §§FLMMBR)NEST'
          FLMTRNSL   CALLNAM='ENTERPRISE COBOL COMPILER',              C
               FUNCTN=BUILD,                                           C
               COMPILE=IGYCRCTL,                                       C
               DSNAME=IGY410.SIGYCOMP,                                 C
               VERSION=3.3.1,                                          C
               GOODRC=4,                                               C
               PORDER=1,                                               C
               OPTIONS='FLAG(I,I),ADATA,LIB,LIST,TEST(NOHOOK,SEPARATE),C
               EXIT(ADEXIT(''/N 100 /W 50'',TAURTOCX))'
*         (* SYSADATA *)
          FLMALLOC  IOTYPE=W,RECFM=VB,LRECL=1020,RECNUM=500000,        C
               DDNAME=SYSADATA
Parent topic: Customizing REXX procedures and ISPF skeletons


Support for Error Feedback during SCLM Build for PL/I

The SCLM Attachment supports error feedback for PL/I programs in connection with the SCLM build. Use the XINFO(XML) compiler option for this and ensure that the XML file is allocated before the build starts. You can use the REXX procedure TAUSCPLA as an additional build translator to allocate this file as shown in the following sample.

***********************************************************************
*         BUILD TRANSLATOR                                            *
* (REXX-PROCEDURE CALL TO ALLOCATE XML FILE)                          *
***********************************************************************
*
          FLMTRNSL   CALLNAM='XMLDAT',                                 C
               FUNCTN=BUILD,                                           C
               CALLMETH=ISPLNK,                                        C
               COMPILE=SELECT,                                         C
               VERSION=1.0,                                            C
               GOODRC=0,                                               C
               PDSDATA=Y,                                              C
               PORDER=1,                                               C
               OPTIONS='CMD(TAUSCPLA §§FLMMBR)NEST'
          FLMTRNSL   CALLNAM='ENTERPRISE PL/I COMPILER',               C
               FUNCTN=BUILD,                                           C
               COMPILE=IBMZPLI,                                        C
               DSNAME=IEL370.SIBMZCMP,                                 C
               VERSION=3.3.0,                                          C
               GOODRC=4,                                               C
               PORDER=1,                                               C
               OPTIONS=(MACRO,OBJECT,SOURCE,XREF,XINFO(XML))
Parent topic: Customizing REXX procedures and ISPF skeletons


Support for error feedback during SCLM build for Assembler

The tool attachment supports error feedback for Assembler programs in connection with the SCLM build. Use the compiler option ADATA together with the Assembler exit TAURTOAX, and allocate the error feedback file as a member of a PDS file in an already started build translator. You can use the REXX procedure TAUSCPLA for this purpose.

A maximum of 250 messages are returned from the exit. You can reduce this amount using the option /N. The maximum number of warning and informational messages is specified with /W, and this value must be fewer than the one specified for /N. If not specified, the default value is set to 20.

          FLMTRNSL   CALLNAM='XMLDAT',                                 C
               FUNCTN=BUILD,                                           C
               CALLMETH=ISPLNK,                                        C
               COMPILE=SELECT,                                         C
               VERSION=1.0,                                            C
               GOODRC=0,                                               C
               PDSDATA=Y,                                              C
               PORDER=1,                                               C
               OPTIONS='CMD(TAUSCPLA §§FLMMBR)NEST'
          FLMTRNSL   CALLNAM='ENTERPRISE COBOL COMPILER',              C
               FUNCTN=BUILD,                                           C
               COMPILE=IGYCRCTL,                                       C
               DSNAME=IGY410.SIGYCOMP,                                 C
               VERSION=3.3.1,                                          C
               GOODRC=4,                                               C
               PORDER=1,                                               C
               OPTIONS='XREF(SHORT),LINECOUNT(75),OBJECT,RENT,ADATA,EXIC
               T(ADEXIT(TAURTOAX(''/N 100 /W 25'')))'
*          (* SYSADATA *)
           FLMALLOC  IOTYPE=W,RECFM=VB,LRECL=1020,RECNUM=500000,       C
               DDNAME=SYSADATA

Parent topic: Customizing REXX procedures and ISPF skeletons


Support for error feedback during SCLM build for C

The SCLM Attachment supports error feedback for C programs in connection with an SCLM build. Allocate the error feedback file as a member of a PDS file in a build translator. Use the REXX procedure TAUSCPLA for this purpose.

Unlike COBOL, PLI or Assembler, the language C doesn't provide a compiler exit which can be used to support error feedback. Therefore it is necessary to call the C compiler from a REXX script which calls the error feedback routine after the compiler has been executed.

The SCLM Attachment includes a REXX sample TAUSCXCC which can be used as SCLM translator to support error feedback for C.

To support error feedback for C it is necessary to use the /EVENTS compiler option and to allocate a temporary SYSEVENT dataset.

          FLMTRNSL   CALLNAM='ERRORFB',                                C
               FUNCTN=BUILD,                                           C
               CALLMETH=ISPLNK,                                        C
               COMPILE=SELECT,                                         C
               VERSION=1.0,                                            C
               GOODRC=0,                                               C
               PDSDATA=Y,                                              C
               PORDER=1,                                               C
               OPTIONS='CMD(TAUSCPLA @@FLMMBR) NEST'
          FLMTRNSL   CALLNAM='C     ',                                 C
               FUNCTN=BUILD,                                           C
               CALLMETH=ISPLNK,                                        C
               COMPILE=SELECT,                                         C
               VERSION=1.0,                                            C
               GOODRC=0,                                               C
               PDSDATA=Y,                                              C
               PORDER=1,                                               C
               OPTIONS='CMD(TAUSCXCC /EVENTS,SSCOM,SO,LO,NOMAR,RENT) NEC
               ST'
...
           FLMALLOC  IOTYPE=W,RECFM=VB,LRECL=255,RECNUM=1000,          C
               DDNAME=SYSEVENT
...
Parent topic: Customizing REXX procedures and ISPF skeletons


Customizing the SCLM model

Save the model member before you customize the SCLM model.

Customization of the Default Start Group

The property SCLM_PROP_LIST_StartGrp is initialized with the default value "DEV1". Change this value in the model to an appropriate default value for an SCLM start group in your SCLM environment.

  • Action enabled conditions
Parent topic: Workflow Manager SCLM Attachment


Action enabled conditions

Depending on the SCLM project definitions, it makes sense to add some action-enabled conditions to the SCLM model.

Micro Focus recommends that you define action-enabled conditions (Element Type: SCLM_ELE_Editable), as required. (The given values PROD and SOURCE below are sample values and have to be replaced by the values defined in the SCLM project definition.)

Relationship | Condition(s)
SCLM_ACT_CompareNext | The action should not be executable on the last group, for example: Condition: SCLM_PROP_ELE_Group Equals not… PROD
SCLM_ACT_DeleteMember | The action should not be executable on productive members, for example: Condition: SCLM_PROP_ELE_Group Equals not… PROD
SCLM_ACT_RemoteSyntaxCheck | The action should only be executable on program code, for example: Condition: SCLM_PROP_ELE_Type Equals… SOURCE
SCLM_ACT_GetVersionList | The action should only be executable on versioned members, for example: Condition: SCLM_PROP_ELE_Group Equals… PROD
SCLM_ACT_RetrieveVersion | The action should only be executable on versioned members, for example: Condition: SCLM_PROP_ELE_Group Equals… PROD
SCLM_ACT_Archgen | The action should only be executable on program code, for example: Condition: SCLM_PROP_ELE_Type Equals… SOURCE

Sample "Action Enabled Conditions" in the Model editor

Parent topic: Customizing the SCLM model


Workflow Manager SVN Attachment

  • Introduction
  • Installing Subclipse
  • Installing the AWM SVN Model Files
  • AWM SVN Models
  • Short User Guide to the AWM SVN Model
Parent topic: Application Workflow Manager


Introduction

The AWM SVN Attachment lets you integrate an AWM-modeled development process with SVN tooling, to share the resources of a project in an SVN repository.

Two models are delivered with the attachment:

  • SVN.model - Subversion Application
    • Template model with a comprehensive collection of SVN tools.
  • MF_SVN.model - Enterprise Developer projects with Subversion integration.
    • Full integration of the Micro Focus Enterprise Developer Projects support with SVN.

The SVN models make use of the tools in the SVN function package, see SVN Function Package for more information.

Parent topic: Workflow Manager SVN Attachment
Related information
SVN Function Package
Eclipse Function Package


Installing Subclipse

If you want to use the functionality of the AWM SVN function package you have to install

  • Subclipse
  • AWM SVN Integration

The AWM SVN integration is based on Subclipse with JavaHL. Subclipse is not automatically installed with Enterprise Developer because it might interfere with other Eclipse SVN integrations, like Subversion. To install Enterprise Developer with the Subclipse integration, call the installation script installeclipseplugins.bat with the option installSubclipse:

installeclipseplugins.bat -installSubclipse

If Enterprise Developer is already installed, you must ensure that you have Subclipse 1.6.0 or later installed. You can install Subclipse into Enterprise Developer from the following update site in your local file system:

%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\AWM\SVN Attachment\Subclipse Update Site 1.10.9.zip

After you have installed Subclipse you have to install the AWM SVN Integration feature from the MFUpdateSiteED located under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer \installer\files. Installation of the AWM SVN Integration is an option on the installation dialog when installing the AWM Update Site into Enterprise Developer via Eclipse Help > Install New Software.

Under IDz, you must install Subclipse from the update site AWMUpdateSiteRDz. The AWM Update Site is located in :

%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\installer\files.

Parent topic: Workflow Manager SVN Attachment


Installing the AWM SVN Model Files

There are several ways to make the AWM SVN model available in the AWM Team Developer perspective, see Master Configuration in the Workflow Manager Modeling Guide for more information. This applies to anEnterprise Developer installation as well as to an IDz installation:

  1. To create a local master configuration file with the SVN application entries, copy the sample local master configuration file under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\AWM\SVN Attachment\MasterConfig.xml into your Eclipse root folder, and adapt the reference to the model location as described in the file.
  2. If a MasterConfig.xml file already exists in the Eclipse root folder, merge the application entries from the SVN master configuration file into this existing master configuration file.
  3. After starting Enterprise Developer or IDz, add the local system to the Application Explorer view and load one of the delivered SVN models.
  4. Right-click the Application Explorer view, and then click Add System(s).

    This opens the Add System(s) dialog.

  5. Select the AWM system from a local master configuration, and then click OK.
    Add System(s) dialog

    Two SVN applications are displayed in the Application Explorer view.

    SVN in Local System

    The installation process is now complete.

Parent topic: Workflow Manager SVN Attachment
Related information
Master Configuration


AWM SVN Models

The delivery includes two models. They are located in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc\AWM\SVN Attachment.

  • SVN.model - Subversion Application

    This application provides the Subclipse SVN tooling (check-out, commit, and so on) based on an AWM model, and is an ideal template for integrating SVN into your individual development process, for example, integrating home-grown or other third-party tools with SVN into the Team Developer views.

  • MF_SVN.model - Enterprise Developer Projects with Subversion integration

    This application fully integrates the Micro Focus Enterprise Developer Projects support with SVN. It combines two models:

    • SVN.model
    • IntegratedEDModel.model

    This model is fully customizable and fully supports Micro Focus project work in combination with source management based on SVN.

Parent topic: Workflow Manager SVN Attachment


Short User Guide to the AWM SVN Model

This topic provides a short overview of the recommended development workflow using the AWM ED Projects with SVN Integration model:

  1. Add an SVN repository location under the SVN Repositories entry of the model. Right-click SVN Repositories, and then click Add Repositories.

    This opens the Repository path dialog.

    Note: If SVN repositories have already been added in this Eclipse workspace, for example, from the SVN Repositories view, they are shown under the SVN Repositories entry of the model.
  2. In the URL field, type the URL to your repository location, and then click OK.
  3. Check out a project from the SVN repository. The checked out project is shown under the Working Copies entry of the model. In the Checkout from SVN dialog, click Check out as a project in the workspace. In the Project Name field, type bankdemo.
  4. Click Finish.
  5. Expand the checked out project under the Working Copies entry of the model. You can see the full list of SVN functionality under the Team menu of any checked out component. Right-click the component, and then click Team.

You should perform your development work in a Micro Focus project under the Enterprise Development Projects entry of the model so you can benefit from all Micro Focus project features. You should only check out the components you need to apply and test changes to. Check out the COBOL sources and copybooks of the bankdemo project to a Micro Focus Remote COBOL Project:

  1. Create a Micro Focus project, for example, a Remote COBOL Project under the Enterprise Development Projects entry of the model:
    1. Right-click Enterprise Development Projects, and then click New COBOL Project > Remote COBOL Project.

      This opens the New Remote COBOL Project dialog box.

    2. In the Project name field, type BankDemo Project.
    3. Click Finish.
  2. Link folders or components from the Working Copies entry of the model to the project under the Enterprise Development Projects entry of the model:
    1. Right-click a component from under the Working Copies entry of the model, and then click New > Linked File > Link File to Folder.

      This opens the Eclipse Dialog Selection Dialog box.

    2. Select the folder to which the file should be linked.
    3. Click OK.

You can now work within the Remote COBOL project. Ensure the project's build path are set so that the copybooks are found. Specify Determine Directives so that the correct compile options are used during the build of the project.

After you have changed a component, the corresponding SVN decorator is set to the component under the Working Copies entry of the model.

All SVN actions can be executed from the Working Copies entry of the model. For example, you can commit all your changes back to SVN once they are tested, click Team > Commit on the project level under the Working Copies entry of the model.

Parent topic: Workflow Manager SVN Attachment


Workflow Manager Troubleshooting

  • Troubleshooting
Parent topic: Application Workflow Manager


Troubleshooting

The first step in troubleshooting is to determine in which Application Workflow Manager component the problem occurred.

There is a general difference between the two components:
  • z/Explorer
  • Modeled Application Workflow Manager application

The type of an Application Workflow Manager component, and where the error occurred, determine the analysis methods required.

Some error situations are caused by a temporary failure; for example, the IP communication socket between the client and the z/Server might not be ready for communication.

In such cases, you will typically receive an org.xml.sax.SAXParseException message, sometimes with the reason “Content not allowed in prolog.”. Communication between the client and z/Server scheduler address space is in XML format. When the client does not receive an expected XML response (for instance because the scheduler address space is temporarily unavailable), a SAX exception occurs. In this case, first try to repeat the action, and it might work.

For more information, General problem determination describes general troubleshooting methods which apply to all components, z/Explorer problem determination describes special methods for z/Explorer, and Application Workflow Manager problem determination describes methods for modeled Application Workflow Manager applications.

  • General Problem Determination
  • z/Explorer Problem Determination
  • Application Workflow Manager Problem Determination
  • General Problem Solving Suggestions
  • Gathering information for Micro Focus SupportLine
Parent topic: Workflow Manager Troubleshooting
Related information
General Problem Determination
z/Explorer Problem Determination
Application Workflow Manager Problem Determination


General Problem Determination

In order to determine the cause of a problem, as much information as possible needs to be gathered.

Try to answer as many of the following questions as possible:

  • Which version of the Application Workflow Manager software is installed on your system?
  • What error message, if any, is displayed? What additional information is displayed when you click Details>>.
  • Are there any entries in the error log relating to this error situation?
  • What did you do, how did you expect the system to react, and how did the system really react?
  • Is the problem reproducible?
  • Does the problem only occur under certain conditions (e.g. only with certain input data or on certain types of element)? If so, what are they?
  • Does the problem only occur in your environment or is it a general problem for all users?
  • Does the problem persist after restarting your Eclipse workbench?

If the problem is to be reported to Micro Focus SupportLine, you need to collect a number of things:

  • Detailed problem description
  • Screenshots of error messages
  • Screenshots of unexpected behavior
  • Error logs
  • Determine the original exception
  • Clear the persistent cache in the workspace
  • Deal with code page problems
  • Workspace out of sync
Parent topic: Troubleshooting
Related information
General Problem Solving Suggestions


Determine the original exception

In some cases, the error message dialog will display more than one error message. The reason for that is that special exceptions are wrapped by less specific exceptions before they are issued.

In order to find the basic cause of the error situation, the original exception has to be determined.

Typically, this is the last exception of the list of exceptions in the details window.

Parent topic: General Problem Determination


Clear the persistent cache in the workspace

The information displayed in the Application Workflow Manager view is persistently stored in the Eclipse workspace in several XML files when the Eclipse workbench is shut down or an application is unloaded. See Further development and maintenance in the Workflow Manager Configuration Guide for more information about those cache files.

In some error situations, it might be necessary to clear the cache, for example if the cache has become inconsistent with the model or if there are error messages indicating an inconsistent cache. We strongly recommend you use for this purpose the Clear Cache action on the context menu of an application in the Tree View:

The Clear Cache dialog box

In this way you can ensure that the cache is cleared in a consistent way.

In some special situations, it might be necessary to delete the files directly in the file system. This should only be done in accordance with or by order of SupportLine. In this case, it is important that Eclipse is shut down before the files are deleted.

Parent topic: General Problem Determination


Deal with code page problems

If problems occur which indicate a code page problem although the code page is set correctly in the zServer properties of the MVS Explorer in the Remote System View, always verify if there is a special file mapping for the regarding file. If this is the case, verify the code page setting in this file mapping.

Parent topic: General Problem Determination


Workspace out of sync

The Eclipse workspace where the Application Workflow Manager files are located can get out of synchronization with the underlying file system. This can be corrected by applying the refresh action in the Navigator view to the part of the Application Workflow Manager project which has got out of synchronization.

Parent topic: General Problem Determination


z/Explorer Problem Determination

When an error occurs in z/Explorer, typically an error message is displayed. If the error contains a message ID in the format described in Introduction, refer to z/Server Messages and Diagnostics for more information about the cause and possible responses.

If the error displayed is a software exception message, refer to the error log view for more information.

If none of the above helps in solving the problem, send the error log to Micro Focus; see General problem solving suggestions.

  • Determine the original exception
  • Clear the persistent cache in the workspace
  • Deal with code page problems
  • Workspace out of sync
Parent topic: Troubleshooting
Related information
General Problem Solving Suggestions
Introduction


Determine the original exception

In some cases, the error message dialog will display more than one error message. The reason for that is that special exceptions are wrapped by less specific exceptions before they are issued.

In order to find the basic cause of the error situation, the original exception has to be determined.

Typically, this is the last exception of the list of exceptions in the details window.

Parent topic: z/Explorer Problem Determination
Parent topic: General Problem Solving Suggestions


Clear the persistent cache in the workspace

The information displayed in the Application Workflow Manager view is persistently stored in the Eclipse workspace in several XML files when the Eclipse workbench is shut down or an application is unloaded. See Further development and maintenance in the Workflow Manager Configuration Guide for more information about those cache files.

In some error situations, it might be necessary to clear the cache, for example if the cache has become inconsistent with the model or if there are error messages indicating an inconsistent cache. We strongly recommend you use for this purpose the Clear Cache action on the context menu of an application in the Tree View:

The Clear Cache dialog box

In this way you can ensure that the cache is cleared in a consistent way.

In some special situations, it might be necessary to delete the files directly in the file system. This should only be done in accordance with or by order of SupportLine. In this case, it is important that Eclipse is shut down before the files are deleted.

Parent topic: z/Explorer Problem Determination
Parent topic: General Problem Solving Suggestions


Deal with code page problems

If problems occur which indicate a code page problem although the code page is set correctly in the zServer properties of the MVS Explorer in the Remote System View, always verify if there is a special file mapping for the regarding file. If this is the case, verify the code page setting in this file mapping.

Parent topic: z/Explorer Problem Determination
Parent topic: General Problem Solving Suggestions


Workspace out of sync

The Eclipse workspace where the Application Workflow Manager files are located can get out of synchronization with the underlying file system. This can be corrected by applying the refresh action in the Navigator view to the part of the Application Workflow Manager project which has got out of synchronization.

Parent topic: z/Explorer Problem Determination
Parent topic: General Problem Solving Suggestions


Application Workflow Manager Problem Determination

The functionality of an application in the Application Explorer view is based on an XML model file. In most cases, a problem in a modeled application can be traced back to an error or inconsistency in the application model. As a general rule, the Application Workflow Manager model administrator should validate a model file before it is set as productive. Validate a model file by clicking Validate Button, which is displayed on the Eclipse toolbar when editing a model file. Errors reported by the validation should always be corrected before the model file is set as productive.

If problems in a modeled application are reported to Micro FocusSupportLine, it is important to include the application model file. To do this, open the Project Explorer view from the Eclipse workbench. In Project Explorer view, expand the InternalTDProject entry to the level of the application that is currently active in the Application Explorer view. The corresponding model file TAURCONF.xml for the active application is displayed.

Include a copy of this file in the information to be sent to Micro FocusSupportLine.

The next five topics require some knowledge of Application Workflow Manager application modeling. They are meant as help for the Application Workflow Manager model administrator to correct some typical error situations caused by an inconsistent application model.

  • Modeled Action does not work
  • Element List is not created
  • Tree View is not expandable
  • Tree View Elements do not have a correct label
  • Edit Action (Simple Remote Edit or Browse) does not work properly
Parent topic: Troubleshooting


Modeled Action does not work

  • Check the reference to the action descriptor, for example, “Element has Action”:
    • Is there a reference to an action descriptor in the respective element type?
    • Is the correct action descriptor referenced?
  • Check the action descriptor:
    • Are the references to the tool descriptors correct, including sequence numbers?
  • Check the tool executor(s):
    • Are the parameters correctly modeled?
      • Does the Type attribute match the Target ID used? In most cases, parameters that reference a file descriptor (TargetID File) must be modeled with the attribute Type = File while parameters pointing at a property (TargetID Parm) must have the attribute Type = String.
      • Is the Parameter From attribute of all input parameters correct?

        Context – The value is taken from context (properties of the selected Element).

        Previous Tool – The value is taken from the previous tool of the corresponding action descriptor.

        User Input – No value is used (only for Input Dialogs).Remember that you can also use a Default or Static value.

Parent topic: Application Workflow Manager Problem Determination


Element List is not created

  • If a detailed error dialog is displayed (containing the parsed line for element list creation):
    • Use the “Validate” action of the Application Workflow Modeler. If errors were detected, try to correct them.
    • In the error dialog:
      • Were the values of the parsed line parsed properly?
      • Is the match name (element type name) on the parsed line?
      • Is the match name’s position correct (depending on the position of the element type property)?
      • Does the parsed line contain every property of the element types ID definition?
  • If no detailed error dialog is displayed:
    • If the element list should be shown in Table View (no Get Children action):
      • Is an element list structure modeled for the corresponding action descriptor (attribute Has Elementlist)?
Parent topic: Application Workflow Manager Problem Determination


Tree View is not expandable

  • If the Tree View element is the application itself:
    • Was an action descriptor defined in the Get Root Containers attribute of the application options?
  • If the Tree View element is an element of a modeled element type:
    • Was an action descriptor defined in the Get Children attribute of the corresponding element type?
  • “Refresh” the Tree View element that is not expanding:
    • Explanation: The Application Workflow Manager caches Tree View information. If the expand fails because of an incorrect model, an empty list is cached.
Parent topic: Application Workflow Manager Problem Determination


Tree View Elements do not have a correct label

  • Check the Tree View label attributes of the corresponding element type. The attribute can be found in the “Element Type has Property” relationship.
Parent topic: Application Workflow Manager Problem Determination


Edit Action (Simple Remote Edit or Browse) does not work properly

  • If the editor does not open, check the tool descriptor that should open it:
    • The attribute Integrated Tool must be set to RemoteEdit.
    • An input parameter must be configured:
      • Type = File
      • TargetID File = Unstructured tool descriptor. Check that the Name Physical attribute references the correct property IDs.
  • If the editor opens, but the editor title/label is “null”:
    • Check that exactly one property of the corresponding element type has the element name attribute set to Ttrue. The attribute is in the “Element Type has Property” relationship.
  • The editor opens with the wrong suffix (.txt):
    • Does the corresponding element type have a relationship to a suffix property?
    • Does the suffix property have the attribute Special Property = Element_Suffix?
  • The wrong editor opens up:
    • In Eclipse, click Window > Preferences > General > Editors > File Associations and configure which editor should open up for the file extension (suffix).
Parent topic: Application Workflow Manager Problem Determination


General Problem Solving Suggestions

This topic lists some general methods and techniques which can be helpful for troubleshooting.

  • Determine the original exception
  • Clear the persistent cache in the workspace
  • Deal with code page problems
  • Workspace out of sync
Parent topic: Troubleshooting


Gathering information for Micro Focus SupportLine

When a user issue cannot be resolved by your Application Workflow Manager model or system administrator, you can report the problem to the Micro Focus SupportLine.

Provide debug information from your error logs to enable further analysis of your problem.

Ensure that a .options file is available in the Eclipse directory of the Enterprise Developer installation. The .options file is copied to the Eclipse directory with the product installation.

It must contain the following information:

com.microfocus.awm/debug=true
com.microfocus.awm/debug/flag=true
com.microfocus.awm.metamodel/debug=true
com.microfocus.awm.metamodel/debug/parser/functionPackages=true
com.microfocus.awm.mvssystem/debug=true
com.microfocus.zserver.communicator/tracing=true

If the file does not exist in the Eclipse directory of Enterprise Developer you can create one using Notepad or any similar text editor.

To determine the location of the Eclipse folder when saving the .options file, click Open File Location from the Enterprise Developer shortcut.
The installation path

Start the Eclipse workbench with the –debug option. Append -debug to the Target field, as shown above.

Reproduce the error and export the error log to a local file. To do this, click Error Log View from the Eclipse workbench.
Error log

Add the exported error log file to all the other information, such as problem description and screenshots. Compress the information and attach as a zip file to an incident raised with Micro Focus SupportLine.

Once you have obtained the error log file you can remove the –debug option from the Target field.

You can also add debug information to a remote z/Server user server address space by activating the REXX debug as described in the Workflow Manager Configuration Guide.

Parent topic: Troubleshooting


Installing Micro Focus Modelling Support for Eclipse

Application Workflow Manager (AWM) is an integral feature of Micro Focus Enterprise Developer and Visual COBOL. It enables you to model and seamlessly integrate application development tools into the Eclipse views that developers work with. AWM provides the means to integrate a customer-specific application workflow in the developer's view without any programming requirement.

The modelling support offered by AWM is available as a standalone feature that can be installed into any other Eclipse IDE, for example, into IBM Developer for z Systems (IDz).

To install Modelling Support for Eclipse as a plug-in to an Eclipse IDE:

  1. Run the modsupp_40.exe file and follow the wizard instructions to complete the installation.
    Note: The supported versions of Eclipse are 4.6 and 4.7. As a prerequisite, Enterprise Developer must not be installed.
  2. Start Eclipse, and then click Help > Install New Software.

    This opens the Install dialog box.

  3. Click Add.

    This opens the Add Repository dialog box.

  4. In the Name field, type Modelling Support for Eclipse.
  5. Click Archive, and browse to C:\Program Files (x86)\Micro Focus\Modelling Support for Eclipse\installer\files\ModelingSupportUpdateSite.zip.
  6. Click Open.
  7. Click OK.
    • If you are installing into Eclipse:
      1. At the Available Software stage, expand Micro Focus, and then check all options except AWM IDz Integration.
    • If you are installing into IBM Developer for z Systems (IDz):
      1. At the Available Software stage, check Micro Focus.
  8. Click Next.

    The installation process calculates requirements and dependencies.

    • If a component cannot be installed, a solution is presented at the Install Remediation Page stage, click Next.
  9. At the Install Details stage, click Next.
  10. Accept the license agreement, and then click Finish.
  11. Click Restart Now when prompted to restart Eclipse to finish the installation.
Parent topic: Application Workflow Manager


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.
  • On Windows platforms, if you are calling dynamic link libraries (.dll files) without a specific path, the COBPATH environment variable 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:

Windows:
int width = cobcols();

printf("Width of screen = %d\n", width);

UNIX:

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:

Windows:
int depth = coblines();

printf("Depth of screen = %d\n", depth);
UNIX:
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
Coding Options
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 concepts
Determining Record Lengths
Related information
The PICTURE Clause
The USAGE Clause


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

  • 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 concepts
Features Added in Enterprise Developer 2.1
Compiled File Types
IBM External Call Interface (ECI)
Starting the debugger automatically using just-in-time debugging
Getting Started
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 .NET type Int32 or the Java 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.

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

enum-id DaysOfWeek attribute System.FlagsAttribute.
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 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

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


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

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.

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

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. NET JVM 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. NET JVM Type-name-1 must be a .NET native type.
  15. NET JVM Custom-attribute-clause is as decribed in the section The CUSTOM-ATTRIBUTE clause in the Data Division chapter.
  16. NET JVM YIELDING may be specified only in the context of an Iterator. See Iterator-ID.
  17. NET JVM The type of the item specified in the YIELDING phrase determines the type of the iterator.

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.

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. NET JVM 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. NET JVM 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. NET JVM If the CUSTOM-ATTRIBUTE clause is specified, the custom attribute information is included in the generated code..
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.
Restriction: This function is supported for native COBOL only.

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
Related tasks
To Install a CCSID Translation Table


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
Related tasks
To Install a CCSID Translation Table


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 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 usually in a CICS program.
  • 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


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


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


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


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

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


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


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


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


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


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


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


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


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


The CREATE Collection Statement

Creates or constructs an instance of a list or dictionary.

General Formats

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 Start > All Programs > Micro Focus Enterprise Developer > Samples > Visual COBOL Samples, under COBOL for JVM.

Parent topic: Statements


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 Start > All Programs > Micro Focus Enterprise Developer > Samples > Visual COBOL Samples, under COBOL for JVM.

Parent topic: Statements


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


The DELETE FILE Statement

The DELETE FILE statement physically removes the specified files from the physical devices on which they reside.

General Format

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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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


The JSON GENERATE Statement

The JSON GENERATE statement converts data to JSON format.

General Format

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


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


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


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


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

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


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


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


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. The EXTEND phrase must be used only for files for 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 UnavailableFiles (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


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


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


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


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


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


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


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


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


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


The SERVICE Statement

The SERVICE statement is used to establish addressability to Linkage Section items usually in a CICS program.

General Format

The SERVICE Statement

Syntax Rules

  1. SERVICE LABEL is generated by the mainframe CICS preprocessor to indicate control flow. It is not intended for general use.
  2. The SERVICE LABEL statement can appear only in the Procedure Division, not in the Declaratives Section.
  3. Identifier should be either the first 01-level item representing the BLL-cell block in the Linkage Section, or another Linkage Section 01-level item for which addressability needs to be re-established following an EXEC CICS statement.

General Rules

  1. At the statement following the SERVICE LABEL statement, all registers that can no longer be valid are reloaded.
  2. If the OS/VS COBOL BLL mechanism is used in a CICS program, addressability to the parameter list must be established at the start of the Procedure Division. This is done by adding a SERVICE RELOAD identifier statement at the start of the Procedure Division where the identifier is the first item in the Linkage Section and it includes pointers to all other entries in the Linkage Section.
  3. If a locate-mode EXEC CICS statement is included in a program compiled with the OSVS Compiler directive, then a SERVICE RELOAD statement must follow each such CICS command and the identifier must be the same pointer (BLL-cell reference) used in the CICS command.
  4. In a CICS program compiled with the OSVS Compiler directive, any time a reference is made to a Linkage Section which is greater than 4096 bytes long, a SERVICE RELOAD statement should be made to re-establish addressability to that portion of the data item greater than 4096 bytes.
  5. The SERVICE RELOAD statement is documentary only in a program compiled with the VSC2 Compiler directive.
Parent topic: Statements


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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
Related reference
Coding Options


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 reference
Coding Options
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 a mechanism for selectively compiling part or all of the COBOL source. To benefit fully from the advantages of conditional compilation the use of level 78 (see the topic Level Number) and the CONSTANT Compiler directive is recommended. Conditional compilation is controlled by $IF, $ELSE, $END constructs, which behave in a similar way to the COBOL IF construct. 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. 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. 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 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 conditional compilation.
  • $END Statement
    The $END statement is used in conjunction with the $IF statement to control 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: Compiler-directing Statements
Related information
Level Number


$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: Conditional Compilation


$ELSE Statement

The $ELSE statement is used in conjunction with the $IF statement to control 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 conditional compilation line is encountered. .
Parent topic: Conditional Compilation


$END Statement

The $END statement is used in conjunction with the $IF statement to control 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 conditional compilation line is encountered.
Parent topic: 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 conditional compilation line is encountered.

Examples

  1. An example of using conditional compilation is provided in the topic $IF Statement (Conditional Compilation).
Parent topic: Conditional Compilation
Related information
$IF Statement (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 (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 (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
Related information
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


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

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


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


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


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


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


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


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


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


Codeset Translation

For applications that are required to translate between ASCII and EBCDIC characters, there is inbuilt support for a number of languages. Codeset support is further extended by the ability to utilize conversion tables distributed by IBM; these tables provide access to many more languages and character sets.

The environment variable MFCODESET determines the codesets to be translated. By setting this variable to the appropriate country code or CCSID(s) as detailed in Supported Country Codes, the required translations are made for certain functionality within the product. For example, any program compiled under the CHARSET"EBCDIC" directive uses the value of this variable; programs that call the _CODESET library routine also rely on this variable.

If the codeset you require is not part of the built-in support (that is, not listed in Supported Country Codes), you can install one of the codeset tables distributed by IBM; for more information, see To install a CCSID Translation Table. Once installed, the support explained above is extended to the newly installed codesets.

If the available codesets still do not match your needs, you can create custom translations between EBCDIC and ASCII using the Codecomp utility.

  • Supported Country Codes
    Enterprise Developer has built-in country support for EBCDIC <-> ASCII character set conversions.
  • Installing CCSID Translation Tables
    Enterprise Developer has built-in support for a number of codesets, but if you require a different codeset, you can install a number of additional CCSID translation tables, distributed by IBM, to increase the number of supported codesets.
  • To Configure the Codeset Translation Environment Variable
    Set the MFCODESET variable in your environment to control the codesets being translated.
  • The Codecomp Utility
    The Codecomp utility enables you to create the files containing mapping tables for EBCDIC/ASCII character set translation. You can customise these files and then build them into your applications.
Parent topic: General Reference
Related reference
_CODESET
CHARSET


Supported Country Codes

Enterprise Developer has built-in country support for EBCDIC <-> ASCII character set conversions.

When you use the _CODESET library routine to convert a string between EBCDIC and ASCII, the MFCODESET environment variable manages and selects the appropriate EBCDIC <-> ASCII conversion for your applications, based on its specified value or default behavior.

The table below shows the possible MFCODESET values (also known as country codes), and their corresponding EBCDIC Coded Character Set Identifiers (CCSIDs) and languages.

Originally, this table reflected the country codes established by the International Telecommunication Union (ITU), but it has since been expanded to include Chinese, Japanese, and Korean (CJK) extensions, as well as MFCODESET values for UNIX database applications.

Support is provided for the following character set conversions:

  • EBCDIC <-> ASCII
  • EBCDIC <-> ASCII with Euro support for single-byte character sets

For Euro enablement (€), prefix your MFCODESET value with "E".

Country Code (MFCODESET) | EBCDIC CCSIDs | Language
AUTOMATIC AUTO |  | Operating system default - sets country code based on CBL_GET_OS_INFO
DEFAULT |  | 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.

MFCODESETs marked with a dagger (†) are based on the Japanese International Standard (JIS) X 0208 1978 revision. Additional conversion tables are available based on the Japanese International Standard (JIS) X 0208 1990 revision (and are taken from IBM's conversion tables CCSID 300 - 941); to use these tables instead of the default ones, set the MFCODESET_DBCS environment variable to 941.

Other EBCDIC CCSIDs in parentheses reflect a 'non-Euro, Euro' pair for appropriate country codes.

For database applications using a DBMS server on Windows, use the table above.

For Windows and UNIX 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)
Parent topic: Codeset Translation
Related concepts
Creating a DB2 LUW Database for HCO
Installing CCSID Translation Tables
Related information
To Customize Character Set Conversion
To Configure the Codeset Translation Environment Variable


Installing CCSID Translation Tables

Enterprise Developer has built-in support for a number of codesets, but if you require a different codeset, you can install a number of additional CCSID translation tables, distributed by IBM, to increase the number of supported codesets.

The codesets provided as part of the built-in support as listed in Supported Country Codes.

  • To Install a CCSID Translation Table
Parent topic: Codeset Translation
Related information
Supported Country Codes


To Install a CCSID Translation Table

Note: To complete this task, you must have administrator privileges to the Enterprise Developer installation directory.
  1. If a ccsid directory does not already exist in the etc sub-directory of your installation directory, create one.
  2. In a Web browser, download the IBM CCSID translation tables file from cdctables.zip and extract it to the ccsid directory.
  3. Use the tabindex.txt file (located in the intro.zip file) to identify the package number and filename for each CCSID translation table you need to install.
  4. Within the ccsid directory, create a sub-directory for each table you want to install, using the name of the CCSID translation table filename, specified in the tabindex.txt file, as the directory name.
  5. For each CCSID that you want to install, open its corresponding Packagen.zip file (as specified in tabindex.txt) and extract the files from the appropriate CCSID .zip file to the corresponding directory you created in the previous step.

Example

To install a CCSID translation table to convert Spanish to USA English, create a sub-directory under ccsid named 011C01B5, and then extract the contents of package4.zip\011C01B5.zip (Windows) or package4.zip/011C01B5 (UNIX) to the 011C01B5 sub-directory.

Parent topic: Installing CCSID Translation Tables


To Configure the Codeset Translation Environment Variable

Set the MFCODESET variable in your environment to control the codesets being translated.
  1. Start an Enterprise Developer command prompt. If you need instructions, see To start an Enterprise Developer command prompt.
  2. Do one of the following:
    • To translate between the ASCII character set and the EBCDIC character set for a specific country code, at the command prompt, enter:
      set MFCODESET=nnnn

      where nnnn is either a supported 4-digit country code or the codeset number as detailed in Supported Country Codes, or the codeset number of a customized conversion module.

    • To translate between a specified ASCII character set and a specified EBCDIC character set, at the command prompt, enter:
      set MFCODESET=xxxxyyyy

      where xxxx is a 4-character hexadecimal string representing the SBCDIC CCSID, and yyyy is a 4-character hexadecimal string representing the ASCII CCSID. If the specified CCSID translation table is not currently installed, refer to To install a CCSID Translation Table.

  3. Run your program from within the same environment to use the configured translation.

Example:

To run a program under the CHARSET"EBCDIC" Compiler directive, and have it translate its output between your current ASCII character set and UK English EBCDIC:
set MFCODESET=0285
To run a program under the CHARSET"EBCDIC" Compiler directive, and have it translate its output between the MS-WIN LATIN-1 codeset (CCSID 1252) and the COM EUROPE EBCDIC codeset (CCSID 37):
set MFCODESET=002504E4
Parent topic: Codeset Translation
Related tasks
To Install a CCSID Translation Table
Related information
Supported Country Codes


The Codecomp Utility

The Codecomp utility enables you to create the files containing mapping tables for EBCDIC/ASCII character set translation. You can customise these files and then build them into your applications.

Note: You can only use Codecomp to create customized tables for single-byte character sets.

You can use Codecomp either with or without the /p option, in the following way:

  1. With the /p option, specifying one filename with extension .e2a and one with extension .a2e. Codecomp creates these files, which contain the mapping tables used for the current country setting. You can then edit these files to produce your own customized tables.
  2. Without the /p option, specifying the two files produced in step1. A copybook called codeset.cpy, used for building a customized codeset module from mapping files, is produced.

Syntax

>>--codecomp--.----.--filename--.-----------.--><
              +-/p-+            +-filename2-+

where

/p | Specifies that the mapping table(s) in use for the current country setting are to be written to the specified file(s)
filename | The name of a mapping file. The file must have the extension .e2a for an EBCDIC to ASCII mapping table, or .a2e for an ASCII to EBCDIC mapping table. This file is an output file when the /p option is used, and an input file when it is not.
filename2 | The name of a mapping file. The file must have the extension .e2a for an EBCDIC to ASCII mapping table, or .a2e for an ASCII to EBCDIC mapping table. This file is an output file when the /p option is used, and an input file when it is not.

If you specify only a single filename when using the /p option, only the mapping file that you have specified (EBCDIC to ASCII or ASCII to EBCDIC) is produced.

If you specify only a single filename without using the /p option, Codecomp attempts to produce the corresponding mapping table by inverting the one in the file you provide. This can only succeed if the second column in the table contains all values from 0 through 255, as otherwise it would not be possible to produce round-trip conversions.

  • The Codeset Mapping File Format
    The mapping files generated by the Codecomp utility format consists of an identifying string followed by two columns of hexadecimal numbers, as follows:
  • To Customize Character Set Conversion
    Use the codecomp utility to create the required conversion files, and then compile those, ready for use in your applications.
Parent topic: Codeset Translation


The Codeset Mapping File Format

The mapping files generated by the Codecomp utility format consists of an identifying string followed by two columns of hexadecimal numbers, as follows:

The mapping file format consists of an identifying string followed by two columns of hexadecimal numbers, as follows:

$ <identifying-string>
;
;
00 corresponding-value
01 ....
02 ....
.. ....
0A ....
.. ....
FF ....

<identifying-string> is mandatory. It must be the first non-comment line in the file, and is denoted by the dollar sign ($) as the first non-space character on the line.

The file must contain one mapping per line, with white space separating the columns. The entries do not have to be in an ordered sequence and blank lines are allowed.

The rest of the line following a semicolon (;) anywhere on a line is treated as a comment.

Failure to specify a complete mapping (that is all values from 00 to FF are mapped to a value) causes an error with no creation of codeset.cpy.

The currency-sign, decimal-point, and comma characters must be mapped to three separate characters to enable numeric de-editing to function correctly. A warning message is displayed if these characters are not mapped to three separate characters, although creation of codeset.cpy continues.

The mapping tables must use the following relationships only:

  • one unique source character to one unique target character
  • many source characters to one target character

In the second case you must supply both mapping tables, as it is not possible to create the second table automatically by inverting the first.

Parent topic: The Codecomp Utility


To Customize Character Set Conversion

Note: When creating a customized character set conversion, the resulting program will not be thread safe unless it contains a Local-Storage Section declaration immediately after the Working-Storage Section.

The codeset module must be compiled using DIALECT"MF", and the NOCANCEL directive; otherwise, you may experience RTS114 abends when the module is first called when running through an enterprise server region.

The sample program CSnnnn.cbl, which is supplied in the src\codeset sub-directory of your installation directory, contains the necessary sections, declarations and directives.

  1. (Windows only) Start an Enterprise Developer command prompt. If you need instructions, see To start an Enterprise Developer command prompt.
  2. (UNIX only) Start a shell prompt and ensure the COBOL environment is configured correctly (for example, ensure COBDIR points to your installation directory, and COBMODE is set correctly).
  3. Create a new directory to hold temporary files and make it the current directory. For example:

    Windows:

    md mylang
cd mylang

    UNIX:

    mkdir mylang
cd mylang
  4. At the prompt, enter:

    Windows:

    set mfcodeset=nnnn

    UNIX:

    export MFCODESET=nnnn

    where nnnn refers to an MFCODESET value (listed in the Supported Country Codes topic) whose character set conversion tables are most similar to the customized versions you want to create.

  5. Enter:
    codecomp /p mapfile.a2e mapfile.e2a

    The files mapfile.a2e and mapfile.e2a are created in the current directory.

  6. Edit the conversion tables in the mapfiles to suit your requirements. mapfile.a2e contains the ASCII to EBCDIC conversion table; mapfile.e2a contains the corresponding EBCDIC to ASCII conversion table.
  7. Enter:
    codecomp mapfile.a2e mapfile.e2a

    A codeset.cpy file is created in the current directory.

  8. Enter:

    Windows:

    copy "%ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\codeset\csnnnn.cbl" csnnnn.cbl

    UNIX:

    cp $COBDIR/src/codeset/csnnnn.cbl csnnnn.cbl
    Note: For 32-bit Windows, %ProgramFiles(x86)% becomes %ProgramFiles%.

    where %ProgramFiles(x86)%\Micro Focus\Enterprise Developer is your installation directory and nnnn is a number between 2000 through 9999 (excluding 9122) that you use to refer to your customized codeset module.

  9. Enter:

    Windows:

    cbllink -d csnnnn.cbl

    UNIX:

    cob -z csnnnn.cbl
  10. Copy the resulting executable module CSnnnn.dll (Windows) or CSnnnn.so (UNIX) to a directory that is specified on the PATH (Windows) or the $LD_LIBRARY_PATH (UNIX).
Parent topic: The Codecomp Utility


Command line reference

A range of command line utilities and interfaces are available for creating, building, debugging and running COBOL applications.

Important: This applies to UNIX environments (remote development) only.

If you installed Enterprise Developer in a directory other than the default location, which is /opt/microfocus/EnterpriseDeveloper, 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 Outside the IDE
  • Compiling from the Command Line (Windows)
  • Linking from the Command Line (Windows)
  • Compiling and Linking from the Command Line (UNIX)
  • Converting Header Files Using the H2cpy Utility
  • Service Interfaces
  • CICS Web Services
  • Debugging from the Command Line
  • 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 Outside the IDE

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 within the IDE and 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.
  • Using the CBLPROMP Utility to Export the Environment Settings
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 (applies to UNIX environments only).
  3. On the command line, user default directives contained in cob options in the environment variable COBOPT (applies to UNIX environments only).
  4. The IDE applies the DIALECT directive specified in the project properties.
    Note: This can result in other directives being applied. See DIALECT in the Compiler Directives chapter for more information.
  5. From within the IDE, directives set in the project, build configuration, and file properties, or on the command line, Compile-time directives specified in the cob command (applies to UNIX environments only).
  6. 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 Outside the IDE
Related information
System-wide Directives File, cobol.dir
$SET Statements in the Source Code
User Directives File
Using the CBLPROMP Utility to Export the Environment Settings


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 (UNIX) or %COBDIR%\etc (Windows) 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 Outside the IDE
Related information
The Order in which Compiler Directives are Processed
$SET Statements in the Source Code
User Directives File
Using the CBLPROMP Utility to Export the Environment Settings


$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 Outside the IDE
Related information
The Order in which Compiler Directives are Processed
System-wide Directives File, cobol.dir
User Directives File
Using the CBLPROMP Utility to Export the Environment Settings
COBSQL Compiler Directive Options
DB2 Compiler Directive Options


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 Outside the IDE
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
Setting the XDB 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
Using the CBLPROMP Utility to Export the Environment Settings


Using the CBLPROMP Utility to Export the Environment Settings

Restriction: This topic applies to Windows environments only.

cblpromp is a Windows-only command line utility that outputs the Enterprise Developer environment settings that are required to set up the COBOL and PL/I environment.

Syntax

[<installdir>\bin\]cblpromp [arguments]
no arguments
Execute cblpromp from a regular (non-COBOL) command prompt only. You need to specify the full path to cblpromp.exe. Outputs the Enterprise Developer environment settings as SET statements for environment variables.
-j
Execute cblpromp from either a regular (non-COBOL) command prompt or from Enterprise Developer one. Outputs the Enterprise Developer environment settings as Java properties. These only include the Enterprise Developer environment changes from the registry and not from the entire environment space.

Examples

The following example shows how to use cblpromp from a non-COBOL command prompt and save the Enterprise Developer environment settings to a batch file:

<installdir>\bin\cblpromp > myenv.bat

You can use myenv.bat in various scenarios. For example, call the file from a batch file whenever you want to set up the COBOL environment at the command line when you want to compile, analyze, test or deploy your applications.

The following example shows how to use cblpromp with the -j option to export the Enterprise Developer environment settings to a Java properties file that can be used for JVM applications:

cblpromp -j > myenv.props

This creates an myenv.props file which you can use to set up the COBOL environment - for example, with an Ant call.

Parent topic: Setting Directives Outside the IDE
Related information
The Order in which Compiler Directives are Processed
System-wide Directives File, cobol.dir
$SET Statements in the Source Code
User Directives File


Compiling from the Command Line (Windows)

Before compiling, if the source code 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 Windows locale has been set correctly, to match the source encoding of these characters; this means setting the system locale in the 'Region and Language' section of Control Panel.

You control the way your program is compiled by specifying Compiler directives. For example, you use a Compiler directive to specify that you want the Compiler to produce a file in generated code format. You can also direct the Compiler to produce a source code listing file and an object code listing file.

You can compile (without linking) using the cobol command, and compile and link your program in one step using the cbllink utility.

You can also instruct the Compiler to automatically invoke the Linker to create an executable file.

You can either specify all the information required on the command line, or use the Compiler prompts.

When compiling native code, the Micro Focus COBOL Compiler compiles a program in two phases:

  • In the first phase, the Compiler checks the syntax of your COBOL source code for errors and creates a dictionary file (.idy) for use with the Debugger and, if you are using a Micro Focus INT/GNT project, an intermediate code file with the extension .int.
  • In the second phase, the Compiler creates the appropriate code depending on the parameters you specify. It creates an object code file with the extension .obj and, if you are using a Micro Focus INT/GNT project, a generated code file with the extension .gnt.
  • The cobol command
  • cobol Command Examples
  • Compiling Using Response Files Example
  • Compiler Prompts
  • Compiler Prompts Example
  • Filenames
  • Response Files
  • Error Codes Returned by the Compiler
Parent topic: Command line reference
Related tasks
To specify the corresponding ASCII CCSID for an EBCDIC CCSID
Related information
cbllink


The cobol command

You can use cobol.exe to compile COBOL source and generate native code objects.

Command Line Syntax:

To invoke the compiler prompts:
>>--cobol---><
To invoke the compiler from the command line:
>>--cobol--s-file-,-.--------.-,-.--------.-,-.--------.-.--------.-.---.-><
                    +-o-file-+   +-s-list+-   -+o-list-+ +--dirs-.+ +-;-+
                                                          ^      |
                                                          +------+
Where the parameters are:
s-file
The name of the file containing your source code. By default, the system looks for s-file.cbl. You can override this default by either typing an extension of your choice or using the OSEXT directive.
o-file
The name of the file to contain the compiled object code. By default, the file is named s-file.obj.

If a filename with an extension of .exe or .dll is specified, the Compiler automatically invokes the Linker once compilation is complete, to create the specified executable.

s-list
The name of the file to contain the source code listing. If the command line is terminated by a semicolon before the comma preceding this field, this option is set to NUL (indicating that no list file is produced).

If you specify s-list without an extension or trailing period, the system adds the extension .lst to create the filename s-list.lst.

o-list
The name of the file to contain the object code listing. If the command line is terminated by a semicolon before the comma preceding this field, this option is set to NUL (indicating that no list file is produced).

If you specify o-list without an extension or trailing period, the system adds the file extension .grp to create the filename o-list.grp.

dirs
A sequence of one or more Compiler directives. Directives can appear after any filename. Each directive must be separated by a space and must not be broken across two lines.
;
Terminates the command line, causing the Compiler to use the default setting for any unspecified options. The semicolon can be entered any time after s-file.
When you invoke the Compiler without prompts:
  • You specify the parameters you require and terminate the line with a semicolon
  • The Compiler uses the default settings for any unspecified options
  • If you omit the semicolon, the Compiler prompts you for any options that you did not specify
  • Filenames specified in the command can be either a disk file or a system device
Parent topic: Compiling from the Command Line (Windows)
Related concepts
Compiler Directives
Compiling COBOL code


cobol Command Examples

The following examples illustrate how you could compile a program, myprog, using a number of options from the command line.

To create myprog.obj but first receive prompts for the listing files, enter:

cobol myprog,,

To create myprog.obj but no listing files, terminate the command line with a semicolon instead of a comma:

cobol myprog;

To create myprog.obj and an object code listing in myprog.grp, enter:

cobol myprog,,nul,,

To create the object file myprog.obj in the myobjdir directory, enter:

cobol myprog,\myobjdir\;
Parent topic: Compiling from the Command Line (Windows)


Compiling Using Response Files Example

The following example illustrates how you could compile a program, Myprog, using response files. The example assumes that Enter is pressed at the end of each line.

The file myprog.rsp contains the lines:

myprog.obj
temp.lst, temp.grp
warning"3" ans85 errlist

If you compile myprog.cbl using this response file:

cobol myprog, @myprog.rsp;

the program is compiled with the directives:

warning"3" ans85 errlist

producing myprog.obj, source listing in temp.lst, and an object listing in temp.grp.

Parent topic: Compiling from the Command Line (Windows)


Compiler Prompts

You display the Compiler prompts by typing:

cobol

Do not enter any parameters. The system prompts you for each option as follows:

Native code only:

Source filename [.CBL] :
Object filename [source-filename.OBJ] :
Source listing [NUL] :
Object listing [NUL]:

Managed code only:

Source filename [.CBL] :

After you enter the source filename, you can accept the defaults for subsequent options by pressing Enter after each prompt or by entering a semicolon at any prompt.

You can override the defaults by entering a filename of your choice after the appropriate prompt. You do not need to enter an extension and trailing period with your filename; the Compiler assigns a default extension according to the type of file being produced. However, if you do not want to use the default extension, you can enter one of your own.

If you do not want to create a particular type of file, you enter NUL in response to the prompt.

After you type any of the responses, before you press Enter, you can continue the response without waiting for the next prompt by typing a comma and the answer to the next prompt.

You can enter a semicolon at any point after entering the source filename to terminate the command line and accept the default settings for any unspecified options. Processing then begins immediately.

You can terminate the compilation at any point by pressing Ctrl+Break.

Parent topic: Compiling from the Command Line (Windows)


Compiler Prompts Example

The following example illustrates how you could compile a program, Myprog, using the prompts. The example assumes that Enter is pressed at the end of each line.

At the first prompt, enter the name of your source file, which causes the Compiler to read from myprog.cbl:

Source filename [.CBL] : myprog

At the next prompt, press Enter to create the file myprog.obj.

Object filename [MYPROG.OBJ]:

At the next prompt, enter the name of your source listing file, which creates a file listing your source file, myprog.lst.

Source listing [NUL]:  myprog

At the final prompt, enter specify the name of the listing file of the object code, myprog.grp.

Object listing [NUL]:  myprog
Parent topic: Compiling from the Command Line (Windows)


Filenames

Each specified filename can identify either a disk file or a system device. File descriptions must have the following format:

>>----.---------.-.--------------------------------------.-----><
      +-device:-+ +--.-----------.---filename--.------.--+
                     +-pathname\-+             +-.ext-+

Each filename or directory name can consist of up to 254 characters and contain any number of periods (.).

This COBOL system regards any text following the final period as an extension (or a trailing period as a space extension) and removes it when creating its own names. Therefore, if you do use multiple periods for a source filename, you must specify an extension.

Parent topic: Compiling from the Command Line (Windows)


Response Files

You can supply all or part of the command line as a response file, which is an ASCII text file containing options for the command. You give the name of the response file on the command line, preceded by an at character (@). This name is replaced in the command by the contents of the file. Within the response file, the end of a line is equivalent to a comma separating filenames or a space between directives beyond the last comma.

The maximum length of a line in a response file is 256 characters.

Response files must not refer to other response files.

Parent topic: Compiling from the Command Line (Windows)


Error Codes Returned by the Compiler

The error messages issued by the Compiler are classed according to their severity as follows:

Severity | Return Value | Description
Unrecoverable | 16 | Indicates a fatal error
Severe | 12 | Indicates an error that the Compiler was unable to correct. Compilation continues, but the statement at fault is not compiled
Error | 8 0 | Indicates an error which the Compiler has attempted to correct
Warning | 4 0 | Flags a statement that although is syntactically correct may contain a possible error
Informational | See INFORETURN | Draws your attention to something in your source code of which you should be aware

The Compiler returns a value to the operating system to show the most severe type of message it issued.

For Windows environments

If you invoked the Compiler from within a batch file, you can test this value using the Windows IF ERRORLEVEL n command. This executes a specified command if the return value is n or higher. For example, if your batch file contains:

cobol myprog;
if errorlevel 8 goto abortjob

then control jumps to ABORTJOB if the Compiler issues any message of severity Unrecoverable, Severe, or Error.

Parent topic: Compiling from the Command Line (Windows)
Related reference
Key to Syntax Checking Error Messages
INFORETURN


Linking from the Command Line (Windows)

You use cbllink to compile and link at the command line.

  • cbllink
  • cbllink Options
  • cbllink Examples
Parent topic: Command line reference


cbllink

Restriction: You can use cbllink to compile native COBOL code only.

The cbllink utility is a combined compiler and linker. To use this utility, the Cblnames utility, and the Linker and Library Manager utilities, must be located in the directories indicated by the PATH environment variable.

By default, any run-time support modules required by a COBOL program, for example Adis or Mffh, is automatically linked in to the executable module by this utility. You can instruct Cbllink to link the run-time support modules separately if required.

To invoke cbllink from the command line:
                                       +-sep-+
             +-----,-----+           +-.-----.--+
             v           |           V          |
>>-cbllink----.---------.----------------file----><
              +-option--+
The cbllink options affect the link process. Separate options with a comma or spaces.
Parent topic: Linking from the Command Line (Windows)
Related reference
cbllink Options
cbllink Examples
Compiling from the Command Line (Windows)


cbllink Options

The cbllink options affect the link process.

Separate options with a comma or spaces.

  • -d
    Creates a .dll file. A .def file is also created and used when creating the .dll file.
  • -f[option]
    Links your program with the shared run-time system using an import library.
  • -g
    Specifies that the application is graphical.
  • -isymbol
    Specifies that the function or entry-point symbol should be included in the executable file.
  • -k
    Prevents temporary files created by cbllink from being deleted.
  • -l
    Create a linker .map output file.
  • -mname
    Specifies the main program. name specifies which entry point should be treated as the main entry point. This option should not be used when creating dynamic link libraries.
  • -oname
    Specifies an output filename. name specifies the name of the executable module or dynamic link library to be created.
  • -roption[v]
    Links your program with the shared run-time system using dynamic binding.
  • -s
    Prevents system modules, such as Adis, Adisinit, Adiskey, Adisdyna, and Mffh from being linked into the executable.
  • -udir_file
    Specifies that the Compiler directives contained in the file dir_file be used during compilation.
  • -v
    Enables verbose details to be displayed.
  • -w
    Enables you to pass information to the system linker or the C compiler.
  • -xsymbol
    Specifies that the function or entry-point symbol should be excluded from the executable file.
  • -y
    Specifies that the application is to be built so that it can also run on Windows XP and Windows Server 2003.
Parent topic: Linking from the Command Line (Windows)
Related information
cbllink


-d

Creates a .dll file. A .def file is also created and used when creating the .dll file.
Parent topic: cbllink Options


-f[option]

Links your program with the shared run-time system using an import library.

Where option can be:

m
Multi-threaded shared run-time system.
Parent topic: cbllink Options


-g

Specifies that the application is graphical.
Parent topic: cbllink Options


-isymbol

Specifies that the function or entry-point symbol should be included in the executable file.
Parent topic: cbllink Options


-k

Prevents temporary files created by cbllink from being deleted.
Parent topic: cbllink Options


-l

Create a linker .map output file.
Parent topic: cbllink Options


-mname

Specifies the main program. name specifies which entry point should be treated as the main entry point. This option should not be used when creating dynamic link libraries.
Parent topic: cbllink Options


-oname

Specifies an output filename. name specifies the name of the executable module or dynamic link library to be created.

This overrides the default name of file1.exe or file1.dll.

Parent topic: cbllink Options


-roption[v]

Links your program with the shared run-time system using dynamic binding.

Where:

option

Indicates the run-time system to bind to and is :

  • M - to bind the multi-threaded run-time system
v

Limits dynamic binding to the current release of the run-time system. If you do not specify this parameter the executable can bind with current and future versions of your COBOL run-time system.

The actual run-time system chosen is determined by a run-time launch configuration file, settings specified during Enterprise Server installation, the presence of the run-time system in the same directory as the application executable, or the run-time system being on the system PATH.

This form of linking should be used on any application that is deployed using Enterprise Server.

Parent topic: cbllink Options
Related concepts
Dynamically Binding Run-time Systems to Your Native COBOL Applications
Run-time Launch Configuration Files


-s

Prevents system modules, such as Adis, Adisinit, Adiskey, Adisdyna, and Mffh from being linked into the executable.

Parent topic: cbllink Options


-udir_file

Specifies that the Compiler directives contained in the file dir_file be used during compilation.
Parent topic: cbllink Options


-v

Enables verbose details to be displayed.

The options passed to the Cblnames utility and to the Linker are displayed.

Parent topic: cbllink Options


-w

Enables you to pass information to the system linker or the C compiler.

Where:

-wlxxx
Passes options to the system linker. For example:
cbllink -wl"/verbose" myCobolProg.cbl
passes myCobolProg.cbl to the compile and links it with the /verbose linker option.
-wcxxx
Passes options to the C compiler. For example:
cbllink -wc-DTAG myCProg.c
passes myCProg.c to the C compiler and compiles it with a constant called TAG.

Comments:

To pass options that include quotation marks, prefix each quotation mark with a backslash:
cbllink -wl"/verbose /opt\"1\"" myCobolProg.cbl
Parent topic: cbllink Options


-xsymbol

Specifies that the function or entry-point symbol should be excluded from the executable file.
Parent topic: cbllink Options


-y

Specifies that the application is to be built so that it can also run on Windows XP and Windows Server 2003.
Parent topic: cbllink Options


cbllink Examples

Use the cbllink command to link .obj files, or to compile and link source code files in one step.

To Produce a System Executable File

To compile and link the file myprog.cbl to produce an .exe file, myprog.exe, use the command:

cbllink myprog.cbl
To Produce a Dynamic Link Library File

To compile and link the file mydll.cbl to produce a .dll file, mydll.dll, use the command:

cbllink -d mydll.cbl
To Create a Dynamically Linked Application

To create an application in which the files main.cbl and fast1.cbl are compiled and linked to create the root module of the graphical application myapp.exe, use the command:

cbllink -g -s -omyapp.exe main.cbl fast1.cbl

To create an application in which the files subprog1.cbl and subprog2.cbl are compiled and linked to create a dynamic link library, subprogs.dll, use the command:

cbllink -d -s -osubprogs.dll subprog2.cbl subprog3.cbl
To Create a Dynamically Bound Application

To create a .dll file that can bind to the run-time system, and any version later than or including that supplied with this COBOL development system, use the command:

cbllink -d -r mydll.obj

To create a .dll file that must bind to the version of the run-time system supplied with this COBOL development system, use the command:

cbllink -d -rv mydll.obj
Parent topic: Linking from the Command Line (Windows)
Related information
cbllink


Compiling and Linking from the Command Line (UNIX)

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
Related tasks
To specify the corresponding ASCII CCSID for an EBCDIC CCSID


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 (applies to UNIX environments only).
Shared library files
These are system linkable files that can be linked into executable files (applies to UNIX environments only). They cannot be directly executed themselves.
System executable files
These files are directly executable (applies to UNIX environments only). 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 (UNIX)


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


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 (UNIX)
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 (UNIX)
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.
Restriction: This topic applies to UNIX environments only.

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


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


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


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


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


Service Interfaces

  • imtkmake command
    Enables you to create and deploy a COBOL program-based service interface, and generate a client application to access the service.
  • mfdepinst command
    Installs the service interface contained in deployment package (.car) file to an enterprise server.
  • COBOL to Service Interface Data Type Matches
    Describes which COBOL data types correspond to available Service Interface data types, including Web Services, and .NET and Java Interfaces.
Parent topic: Command line reference
Parent topic: General Reference


CICS Web Services

  • js2ls command
    Generate a CICS application as a Web service provider or requester, starting with one or more JSON schemas.
  • ls2js command
    Exposes a CICS application program as a Web service by generating one or more JavaScript Object Notation (JSON) schema files and a Web service bind (WSBIND) file.
  • ls2ws command
    Exposes a CICS application program as a Web service by generating a Web service description (WSDL) file and a Web service bind (WSBIND) file.
  • ws2ls command
    Expose a CICS application as a Web service provider or construct a Web service requester. Generates COBOL data structures, a skeleton COBOL program, and a Web service bind (WSBIND) file from a Web service description file (WSDL).
Parent topic: Command line reference


Debugging from the Command Line

  • cobdebugremote/cobdebugremote32
    The cobdebugremote (Windows) or cobdebugremote32 (UNIX) process runs on a remote machine and enables you to debug 32-bit applications on that machine using remote connections.
  • cobdebugremote64
    The cobdebugremote64 process runs on a remote machine and enables you to debug 64-bit applications on that machine using remote connections.
Parent topic: Command line reference


cobdebugremote/cobdebugremote32

The cobdebugremote (Windows) or cobdebugremote32 (UNIX) process runs on a remote machine and enables you to debug 32-bit applications on that machine using remote connections.
Restriction: The following applies to native code only.

Syntax:

To start the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process, enter the following at a COBOL command prompt:

Options:

Windows:

cobdebugremote option

UNIX:

cobdebugremote32 option
no options
Starts the process and opens a random port for remote connections. The port number is displayed in the console.
machine=name
Specify the machine that the process is running on. Only valid with the stop option.
port
port=nnnnn
Specify the port to use to listen for connection requests.
port=nnnnn-yyyyy
Specify the range of ports to use. If port nnnnn is in use, the next port is tried until a free port is found. If no free ports are found in the range, the utility returns an error.
Note: You must enter the same number you set as the port option in the cobdebugremote port field of your debug configuration.
repeat
After the debug session has been completed, start listening for another connection. If no option is specified, the process exits after the debug session has completed.
stop
Causes the process that is listening on the port to exit. Must be used with the port option. This is only valid when the process is waiting for a connection.

Example

The following example starts the cobdebugremote (Windows) or cobdebugremote32 (UNIX) process using port 45678 to listen for connection requests. After the debug session has been completed, the process starts listening for another connection.

Windows:
cobdebugremote port=45678 repeat

UNIX:

cobdebugremote32 port=45678 repeat

Comments:

If you intend to remotely debug callable shared objects (.so), you must set the COBIDY environment variable to the location of the .idy file before you start cobdebugremote32 or cobdebugremote64.

Parent topic: Debugging from the Command Line


cobdebugremote64

The cobdebugremote64 process runs on a remote machine and enables you to debug 64-bit applications on that machine using remote connections.
Restriction: The following applies to native code only.

Command Line Syntax:

To start the cobdebugremote64 process, enter the following at a COBOL command prompt:

cobdebugremote64 option

Options:

no options
Starts the cobdebugremote64 process and opens a random port for remote connections. The port number is displayed in the console.
machine=name
Specify the machine that cobdebugremote64 is running on. Only valid with the stop option.
port
port=nnnnn
Specify the port to use to listen for connection requests.
port=nnnnn-yyyyy
Specify the range of ports to use. If port nnnnn is in use, the next port is tried until a free port is found. If no free ports are found in the range, the utility returns an error.
repeat
After the debug session has been completed, start listening for another connection. If no option is specified, cobdebugremote64 exits after the debug session has completed.
stop
Causes the cobdebugremote64 that is listening on the port to exit. Must be used with the port option. This is only valid when cobdebugremote64 is waiting for a connection.

Comments:

If you intend to remote debug callable shared objects (.so), you must set the COBIDY environment variable to the location of the .idy file before you start cobdebugremote32 or cobdebugremote64.

Parent topic: Debugging from the Command Line


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


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 (Windows) or $PATH (UNIX) 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 (applies to UNIX environments only).
Parent topic: Running an Application from the Command Line


cobrun Command

Restriction: This command is supported for native COBOL only.

The name of this command varies depending on the platform: for Windows platforms, use the run command; for UNIX/Linux platforms, use the cobrun command.

To run dynamically loadable programs (that is, callable shared objects, or .int or .gnt files) use the following command(s):

Windows:

run [(switch-params)] program-name [program-params]

UNIX/Linux:

cobrun [switch-params] program-name [program-params]
Note: For multi-threaded programs, use cobrun_t instead (UNIX/Linux platforms only).

where:

switch-params
One or more programmable and run-time switches that control events in a program at run time. On Windows platforms, enclose all switches in parentheses. Your application supplier will tell you which switches to specify.
program-name
The name of a dynamically loadable program.
If you do not specify an explicit filename extension in the run (Windows) cobrun (UNIX) 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:

UNIX only: Use cobrun in conjunction with the effective working mode to run in a 32-bit or 64-bit environment; alternatively, use cobrun32 or cobrun64 to directly invoke those environments.

Parent topic: Running an Application from the Command Line


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:

Windows:

run (-F) demo.int

UNIX:

cobrun -F demo.int

To run demo.int in ANSI debug mode whilst disabling the display of trailing spaces:

Windows:

run (+D+A1) demo.int

UNIX:

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
Related reference
Reverse Debug and Live Recording


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. 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
Reverse Debug and Live Recording


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
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.
ACU2VCOB
Provides emulation of the actions of ACCEPT and DISPLAY statements in ACUCOBOL-GT.
RM2VCOB
Provides emulation of the actions of ACCEPT and DISPLAY statements in RM/COBOL.

See the Compatibility Guide for full details on RM/COBOL, ACUCOBOL-GT, 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


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.

Micro Focus recommends that you use Profiler from within the IDE. See the links at the end of this topic for more information.

This section provides information about how to use the utility from the command line.

  • Introduction to Profiler
  • Running or Invoking Profiler from the Command Line
  • Profiler Output
  • Time Spent in Called Programs
  • Directives for Profiler
Parent topic: Command line reference
Related reference
Directives for Profiler


Introduction to Profiler

Profiler is a facility that enables you to obtain detailed statistics on the run-time performance of a COBOL program.

When you compile a program (Windows) or submit a COBOL source program to the Cob utility (UNIX) you can specify the PROFILE compiler directive. This causes the compiler to include code in your program that produces performance statistics about each paragraph of the program each time you run the compiled program. If your program contains no paragraphs, this report is not produced.

The performance statistics produced using the PROFILE compiler directive for that run of the program are contained in a file called program-name.ipf where program-name is the name of the program that was run. If an executable file is produced, then program-name is the first entry point name in the executable file.

These performance statistics are in compact form and first must be converted to a readable format, using Profiler.

By default, this file is created in the current working directory, but you can change this using the COBPRFDIR environment variable to specify an alternative directory. For example:

Windows:
SET COBPRFDIR=C:\myipfdir
UNIX:
SET COBPRFDIR=/myipfdir

Profiler cannot be used on programs running multiple threads (applies to UNIX environments only).

Parent topic: Profiler


Running or Invoking Profiler from the Command Line

To start Profiler from the Enterprise Developer command prompt, use the following command:

Windows:
profiler filenames directives
UNIX:
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 compile (Windows) or submit to the Cob utility (UNIX) the program prog1 with the PROFILE directive set, run the program, and then enter:

Windows:
profiler prog1 +LIST
UNIX:
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


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 concepts
Profiler


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
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. Enterprise Developer provides IDE integration of test coverage within Visual Studio or Eclipse - 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 (UNIX) or TCReport (Windows). 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. Enterprise Developer 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)
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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\etc (Windows) or $COBDIR/etc (UNIX). 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

Windows:
RESULT .\results\tcresult.tcz ACCUMULATE
UNIX:
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.

Windows:
RESULT c:\myres\tcresult.tcz
UNIX:
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 (UNIX) or TCReport (Windows) 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 TCReport (Windows) or cobtcreport (UNIX) 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 (UNIX) or TCReport (Windows) to identify tags in your source code, enabling cobtcreport (UNIX) or TCReport (Windows) 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…]
Note: On Windows, tcutil is implemented as a batch file. When invoking tcutil from within a batch file or CI command processor, you need to make a call to tcutil in order to execute it - for example:
call tcutil...

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)


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 (UNIX) or TCReport (Windows) to produce reports from the results files. If you want to include information on tags, set the taglines option.
Parent topic: How To...
Related reference
TESTCOVER
Related information
Environment variables (Windows)


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:
    Windows:
    tcreport filename [NO]options
    UNIX:
    cobtcreport filename [NO]options

    where:

    • filename is one of the following:
      • One or more .tcz files, separated by a comma. For example:
        Windows:
        tcreport file1.tcz,file2.tcz,file3.tcz... [NO]options
        UNIX:
        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:

        Windows:
        tcreport @filelist.txt [NO]options
        UNIX:
        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:

Windows:
#tcscan filename
UNIX:
cobtcscan filename

where filename is the name of your .tcz file.

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 (UNIX) or TCReport (Windows).

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:
    Windows:
    tcreport filename taglines(tagfile) [options]
    UNIX:
    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 (UNIX) or tcreport (Windows) options.

    For example:

    Windows:
    tcreport myreport.tcz taglines(tagfile.txt)
    UNIX:
    cobtcreport myreport.tcz taglines(tagfile.txt)
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 Enterprise Developer 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
Note: On Windows, tcutil is implemented as a batch file. When invoking tcutil from within a batch file or CI command processor, you need to make a call to tcutil in order to execute it - for example:
call tcutil...
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)
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 (UNIX) or TCReport (Windows) 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 (UNIX) or TCReport (Windows) 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)
Related concepts
Specific Troubleshooting Advice
Related reference
TESTCOVER
Related information
Environment variables (Windows)


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


The cobutf8 Utility

Note: This utility is only supported on UNIX platforms.

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 information
Setting Compiler Directives on Individual Files


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
Related concepts
Features Added in Enterprise Developer 2.2


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: | DBCS"3" (Windows) or NODBCS (UNIX)
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
IDE equivalent: You can use the following key combinations to add new DBCS characters in the editor:
  • To insert a shift-out character - press Alt+S, release them and then press O
  • To insert a shift-in character - press Alt+S, release them and then press I

You can change the key combinations on the Keys tab in the IDE preferences.

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 concepts
Features Added in Enterprise Developer 2.2
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

FCDCAT

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

FCDCAT

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

FCDCAT

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

FCDCAT

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

FCDCAT

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

FCDCAT

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

FCDCAT

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

FCDCAT

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

FCDCAT

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

FCDCAT

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
Related information
Preprocessor Response Codes


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
Related information
Preprocessor Response Codes


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 (applies to UNIX environments only). 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 (applies to UNIX environments only). 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 (applies to UNIX environments only). 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

  • CICSECM
    Causes EXEC CICS statements in your program to be replaced by CICS API run-time calls.
  • 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.
  • XDB
    Causes EXEC SQL statements in your program to be replaced by XDB 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


CICSECM

Causes EXEC CICS statements in your program to be replaced by CICS API run-time calls.
Restriction: This directive is supported in native COBOL only.

Syntax:

>>-.---.-.----CICSECM-.----------------------.-.><
   +-/-+ |            |   +-----.---.-----+  | |
         |            |   |     +-,-+     |  | |
         |            |   V               |  | |
         |            +-(.-option=setting-.)-+ |
         |                                     |
         +-NO-CICSECM--------------------------+

Parameters:

option
One of the CICSECM options (see below)
setting
The setting for the option

Properties:

Default: | NOCICSECM
Phase: | Syntax check
$SET: | No

Comments:

You normally set this directive by checking EXEC CICS in the Build Settings dialect box.

For more information on the CICS ECM directive options, see the help topic CICS Preprocessor Options.

Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List
Related information
CICS Preprocessor Options
Language Features - Additional Features
Key to Compiler Directives


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


XDB

Causes EXEC SQL statements in your program to be replaced by XDB calls, depending on the options you specify.
Restriction:

This directive is supported in native COBOL only.

Syntax:

 >>-.---.-.----XDB-.----------------------.-.--><
    +-/-+ |        |   +-----.---.-----.  | |
          |        |   |     +-,-+     |  | |
          |        |   v               |  | |
          |        +-(.-option=setting-.)-+ |
          |           |                |    |
          |           +-NO-option------+    |
          +-NO-XDB--------------------------+

Parameters:

option | One of the XDB options listed in the topic XDB Directive Options.
setting | The setting for the option

Properties:

Default: | NOXDB
Phase: | Syntax check
$SET: | Initial
Parent topic: Language Features - Additional Features
Parent topic: Compiler Directives - Alphabetical List


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.
  • GNT
    Specifies the name of the generated code 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.
  • PCOMP
    Enables you to specify a user program as a precompiler for COBOL files.
  • 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" (Windows) or COPYEXT",cbl,cpy" (UNIX)
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 (applies to UNIX environments only).

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: | From the project's properties, expand Micro Focus > Build Path > Dependency Paths, ensure Type is set to COBOL Copybook Paths
Phase | Syntax check
$SET | None

Comments:

You should only use the COPYPATH directive when compiling using the cobol (Windows) or cob (UNIX) 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.

You might need this directive when compiling programs for running under the Enterprise Server Mainframe Subsystem Support.

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: | EOF-1A (Windows) NOEOF-1A (UNIX)
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


GNT

Specifies the name of the generated code file.

Restriction: The GNT directive is supported in Windows environments and native COBOL only.

Syntax:

>>-.---.-.---GNT-.-"pathname\filename"---.-.--><
   +-/-+ +       +-"pathname/filename"---+ +
         +       +-"pathname\"-----------+ +
         +       +-"pathname/"-----------+ +
         +       +-"filename"------------+ +
         +       +-()--------------------+ +
         +-NOGNT---------------------------+

Parameters:

pathname | Specifies the path.
filename | A full file specification.

Properties:

Default: | GNT"source-name.gnt" (with OMF"GNT")
Phase: | Generate
$SET: | Any

Comments:

You should use this directive in preference to the OMF directive.

This directive creates a file in the format specified, with the name specified. For example, if you specify GNT"myprog.gnt", then a file myprog.gnt is produced that contains generated code.

With NOGNT, no generated code file is produced.

If filename is not specified, the Compiler uses source-name.int, where source-name is the basename of the source filename. If you specify pathname but not filename, the Compiler uses the pathname and attaches the filename source-name.gnt.

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.
Note: IDYSRCPATH is deprecated, and provided for backward compatibility only.

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.
Restriction: This directive is supported for JVM COBOL only.

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
Windows: NOP64 on 32-bit systems or P64 if the 64-bit check box in the Build Settings dialog box is set.UNIX: 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
Click Project > Properties > Micro Focus > Build Configurations > COBOL > Platform Target
Phase
Syntax check
$SET
Any

Dependencies:

P64 immediately sets: RTNCODE-SIZE"8" and FCD3

NOP64 immediately sets: RTNCODE-SIZE"4"

Comments:

If you set the P64 directive, your program is compiled to run under a 64-bit development environment, and to manipulate 64-bit pointers.

If you set the P64 directive, your program is compiled to use 64-bit pointers and has access to a 64-bit address space if you are executing on a 64-bit machine with an appropriate setting of the ILTARGET directive.

Parent topic: Compiler Control - Compile/Link Files
Parent topic: Reserved Directives
Parent topic: Compiler Directives - Alphabetical List


PCOMP

Note: This directive is supported on Windows platforms only. It is not supported when accessing the Micro Focus Enterprise Developer UNIX Components from a Windows client machine.
Enables you to specify a user program as a precompiler for COBOL files.

Syntax:

>>-.---.--PCOMP--"userprog"------><
   +-/-+

Parameters:

userprog The user program to be used as a precompiler

Properties:

Default: None

Comments:

The user program should return an external filename.

If userprog is not found, the compilation fails.

The user program can use CBL_EXIT_PROC to perform some post-build processing.

Example:

working-storage section.
       01.
           05 install-flag       pic x comp-x.
           05 install-params.
               10 exit-proc-ptr  usage procedure-pointer.
               10                pic x.

       01 p-exit-block.
           03 p-block-size       pic x(4) comp-5 value 16.
           03 p-return-code      pic x(4) comp-5.
           03 p-rts-error        pic x(4) comp-5.
           03 p-exit-flags       pic x(4) comp-5.

       linkage section.
       01 source-file            pic x(256).

       procedure division using source-file.
           display source-file
      * On exit the file specified in source-file is the one
      * the compiler will actually compile
           move "EMPLOY.BMS" to source-file

           set exit-proc-ptr to entry "exitproc"
           move 0 to install-flag
           call "CBL_EXIT_PROC" using install-flag
                                       install-params
           end-call

      * Zero means continue, non-zero abort
    move 0 to return-code
           exit program
           .

       exitproc section.
       entry "exitproc".
           display "in exit proc"

           call "CBL_GET_EXIT_INFO" using     p-exit-block

           exit program
           .
Parent topic: Compiler Control - Compile/Link Files
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.
  • 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 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


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, in UNIX environments, $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 (UNIX) or a file that appears in a DIRECTIVES or USE directive (all platforms). 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 concepts
Features Added in Enterprise Developer 2.2
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 concepts
Features Added in Enterprise Developer 2.2
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.
  • SOURCEASM
    Makes the Compiler include source code statements in the assembler 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 the debugger (Windows) and Animator (UNIX)). 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


SOURCEASM

Makes the Compiler include source code statements in the assembler listing.
Note: This directive is supported for native COBOL only.

Syntax:

>>-.---.-.----.--SOURCEASM-----------------><
   +-/-+ +-NO-+

Parameters:

None

Properties:

Default: | NOSOURCEASM
Phase: | Generate
$SET: | No

Dependencies:

Set to NOSOURCEASM by NOLIST at end.

SOURCEASM sets ANIM at end.

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: | VERBOSE (Windows) or NOVERBOSE (UNIX)
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: | ANIM (IDE default) or NOANIM (command line default) (Windows) or NOANIM (UNIX) if generated code is produced, and ANIM if intermediate code is produced
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.

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 .obj (Windows) or .o (UNIX) 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.

NOASSIGN-PRINTER causes the output to be sent to the device LST: (applies to Windows environments only).

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.

You should use CALL-RECOVERY when compiling a mixture of CICS and non-CICS programs for running in Mainframe Subsystem Support. Only the non-CICS modules need be compiled with the appropriate directive. When compiling only CICS programs, CALL-RECOVERY is not required.

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 reference
DATACOMPRESS
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
Btrieve with ANSI (Windows) or Reserved (UNIX)
6
Btrieve without ANSI (Windows) or Reserved (UNIX)
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
Btrieve with ANSI (Windows) or Reserved (UNIX)
6
Btrieve without ANSI (Windows) or Reserved (UNIX)
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 reference
KEYCOMPRESS
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
Related concepts
Features Added in Enterprise Developer 2.2


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

When NOILDYNCALL is specified, you also need to set the WARNING Compiler directive in order to enable warning messages. For example, with both of these specified, you will receive a warning if the target method is not found.

This option is also in effect when you select the Use dynamic calls option for a managed JVM COBOL project, which provides a way to build JVM COBOL projects incrementally; see Compiling JVM COBOL for more information on incremental compilation.

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
Related concepts
Features Added in Enterprise Developer 2.2


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


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 concepts
Features Added in Enterprise Developer 2.2
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: | None

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

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

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: | None
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.
  • ILSUBSYSTEM
    Specifies the subsystem directive to the MSIL Assembler (ilasm.exe).
  • 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.
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


ILSUBSYSTEM

Specifies the subsystem directive to the MSIL Assembler (ilasm.exe).
Restriction: This directive is supported for .NET COBOL only.

Syntax:

>>-----.--ILSUBSYSTEM--"value"-.----><
       +-NOILSUBSYSTEM---------+

Parameters:

value
Indicates the output type of the assembly. 2 (Windows application) is the only valid value.

Properties:

Default: | NOILSUBSYSTEM
IDE equivalent: | Click Project > Properties > Application and fill in Output Type
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


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:

On Windows:

cobol a.cbl list jvmgen jvmclasspath(myclasses);

On UNIX:

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


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: | NOLITLINK (Windows) or LITLINK for .o files (UNIX)
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
Related reference
PRE
PRE


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 (applies to UNIX environments only).

For Windows environments

If a program with a four-byte RETURN-CODE calls a program with a two-byte RETURN-CODE, on return the value from the called program is in the lower two bytes of the four-byte RETURN-CODE. The content of the upper two bytes is undefined.

If a program with an eight-byte RETURN-CODE calls a program with a four-byte RETURN-CODE, on return the value from the called program is in the lower four bytes of the eight-byte RETURN-CODE. The content of the upper four bytes is undefined.

When one program calls another, it is not necessary that the size of their RETURN-CODE registers match. If the calling program's RETURN-CODE register is larger than the called program's RETURN-CODE register, then any remaining bytes the calling program's register are undefined. For example, if a program with a two-byte RETURN-CODE calls a program with a four-byte RETURN-CODE, on return the lower two bytes of the value from the called program are in the two-byte RETURN-CODE. The content of the upper two bytes is lost.

If the calling program's RETURN-CODE register is smaller than the called program's RETURN-CODE register, then any bytes that cannot fit into the calling program's register are lost. For example, if a program with a four-byte RETURN-CODE calls a program with a eight-byte RETURN-CODE, on return the lower four bytes of the value from the called program are in the four-byte RETURN-CODE. The content of the upper four bytes is lost.

For UNIX environments

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 UNIX 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 ANSI (Windows) or ASCII (UNIX) 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

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
Related concepts
Features Added in Enterprise Developer 2.2


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.

Note: JCL user exit programs should not be compiled with this 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
Parent topic: Compiler Directives - Alphabetical List
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: | NOCASE (Windows) or CASE (UNIX)
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.

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.
  • AMODE
    Provides support when performing arithmetic on mainframe-style pointers.
  • 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.
  • CICSECM
    Causes EXEC CICS statements in your program to be replaced by CICS API run-time calls.
  • 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.
  • 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.
  • GNT
    Specifies the name of the generated code 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.
  • 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 (Technology Preview)
    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.
  • 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.
  • ILSUBSYSTEM
    Specifies the subsystem directive to the MSIL Assembler (ilasm.exe).
  • 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.
  • 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.
  • PCOMP
    Enables you to specify a user program as a precompiler for COBOL files.
  • 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.
  • SOURCEASM
    Makes the Compiler include source code statements in the assembler listing.
  • 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.
  • XDB
    Causes EXEC SQL statements in your program to be replaced by XDB calls, depending on the options you specify.
  • 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 (Technology Preview)

Identifies and compiles only the programs that have changed since the previous compilation.
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.
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 (Technical preview feature).
$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 concepts
Technology Preview Features
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 Enterprise Developer 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


Configuring CCI

The Common Communications Interface (CCI) is the technology used by Micro Focus products such as Mainframe Access, Fileshare and CICS, to enable communications applications. CCI allows a common approach to configuration and diagnosis of errors for users of Micro Focus distributed applications.

  • CCITCP Configuration
    CCITCP allows an application to connect to another application (on another machine, usually, although it can be another process on the same machine) using the TCP/IP protocol. CCITCP is supported on Windows 95 and later, and UNIX systems.
  • CCI Tracing
    You can trace CCI activity through the Consolidated Tracing Facility (CTF).
  • CCI.INI - The CCI Configuration File
    The CCI.INI file is used to specify selective configuration options for all or some CCI modules installed.
  • CCI Status Messages
    All CCI modules produce text-based messages, describing the status of the completion of the last CCI operation. Some statuses are critical and require remedial action before use of the affected CCI module can continue. Others are warnings and, in most cases, do not require you to take any action.
Parent topic: General Reference


CCITCP Configuration

CCITCP allows an application to connect to another application (on another machine, usually, although it can be another process on the same machine) using the TCP/IP protocol. CCITCP is supported on Windows 95 and later, and UNIX systems.
  • CCI Support For TCP/IP
  • Advanced Features
  • Application Configuration
Parent topic: Configuring CCI
Related information
CCI Tracing
CCI.INI - The CCI Configuration File
CCI Status Messages


CCI Support For TCP/IP

CCI over TCP/IP (CCITCP) allows an application to connect to another application (on another machine, usually, although it can be another process on the same machine) in two ways: directly, by specifying the TCP/IP address and port being used by the application you want to connect to (this is described in the Advanced Features section); or indirectly, by specifying a logical "Server Name" of the service you wish to connect to.

This second method allows the most flexibility: the applications can be moved from machine to machine without being altered; and the details of the machine they are running on are unimportant (as long as they support CCI and TCP/IP, of course). This flexibility is achieved by having an intermediate program which CCI can query when a connection request is made. This program contains or can obtain the necessary details to allow an application to establish a connection with another application of a given Server Name. This program is called the CCITCP2 registration daemon.

Before using CCI over TCP/IP (with or without using CCITCP2) there is some configuration that is necessary, described in the sections below.

  • CCI Support Modules for TCP/IP
  • TCP/IP Configuration
  • Running the CCI Configuration Utility
  • CCI Configuration for UNIX Users
  • Using CCITCP2
Parent topic: CCITCP Configuration
Related information
Advanced Features


CCI Support Modules for TCP/IP

In order to enable CCI support for TCP/IP, three executable modules are provided:

  • CCITC32.DLL(cobtcp.so on UNIX systems) - which enables the CCI interface routines necessary for CCI equipped machines to communicate with each other. The module, its interface, and its associated functionality and other support modules, is generically referred to as CCITCP. Micro Focus products use this (and other protocol-specific CCI modules) so that they do not need to worry about the complexities of the underlying network protocol.
  • CCITCP2.EXE(ccitcp2 on UNIX systems) - a server registration module, which is used to register and advertise CCI server processes that are available for CCI clients to call. It is designed to be run as a background application, and so is sometimes referred to as a "daemon" process.
  • CCIINST.EXE(not supplied on UNIX systems) - adds necessary entries to the TCP/IP services file automatically and registers the name of the machine which CCI clients will use to connect to a CCITCP2 process. It generally needs to be run only once on a machine.
Parent topic: CCI Support For TCP/IP


TCP/IP Configuration

Before the CCI modules can work effectively the appropriate TCP/IP network hardware and software drivers must be already installed, fully configured, and working. Once the TCP/IP software is installed and configured, the network connections should be fully checked out using suitable utilities, such as the TCP/IP standard commands "ping" and "ftp", before attempting to use CCI over TCP/IP. Ensure that if hostnames are going to be used (as opposed to only dotted decimal IP addresses) that the Domain Name Server (DNS) configuration is correct and that the service is working.

Where a network is connected to other networks, ensure that TCP/IP is aware of the gateway(s) to these networks by running "route add" or a similar command. Please see your TCP/IP vendor's installation and configuration guides for details of these steps.

Once you are certain that TCP/IP is fully configured and functional and that the machines which you wish to communicate with are similarly set up and reachable, then the only other configuration issue that needs to be resolved is where (and whether) a CCITCP2 daemon will be run to enable these machines to contact each other.

Parent topic: CCI Support For TCP/IP


Running the CCI Configuration Utility

This section does not apply to UNIX installations. Please refer to CCI Configuration for UNIX users

If a CCITCP2 daemon is used to allow CCITCP clients and servers to establish contact then the "CCI Configuration" utility needs to be run first. It can be started by going to the "Configuration" group under the product Start menu item and selecting "CCI Configuration". Alternatively just run CCIINST from any Micro Focus Command Prompt.

The CCI Configuration Utility asks for the address of the machine in the reachable network which is running a CCITCP2 daemon. You can enter either a hostname or a dotted decimal format address. If you do not know the TCP/IP hostname or address of the system that the CCITCP2 daemon is running on, contact your system/network administrator.

The CCI Configuration Utility also updates the TCP/IP services file with values necessary for CCI to work over TCP/IP.

If you leave the hostname field empty, CCI assumes that the CCITCP2 daemon will be running on the local machine, and the changes to the services file are still made.

If the machine running the CCITCP2 daemon changes, you must rerun the CCI Installation Utility and change the hostname to the new value. If there are any Micro Focus processes running which were started before the value was changed (e.g. Command Prompt, Integrated Development Environment, etc.) then these will need to be re-started before they pick up the new value.

Parent topic: CCI Support For TCP/IP
Related concepts
Using CCITCP2


CCI Configuration for UNIX Users

Prior to using CCITCP with CCITCP2, an entry must be made in the $COBDIR/bin/services file as follows:-

mfcobol 86/udp

Without this entry in the $COBDIR/bin/services file, CCITCP2 cannot function.

On UNIX systems the user is required to set an environment variable "CCITCP2" to select the location of the machine hosting CCITCP2 executable in the network that is being used.

An example of the setting of a CCITCP2 environment variable for korn shell users is

export CCITCP2=myhostmachinename

or

export CCITCP2=192.77.293.1

The method for setting environment variables in other UNIX shells differs slightly from the examples given here, please use the appropriate method for the user shell of your choice.

Please refer to the section Environment Variables and the CCI.INI File for more details of the advanced configuration of CCITCP.

Parent topic: CCI Support For TCP/IP
Related information
Environment Variables and the CCI.INI File


Using CCITCP2

There only needs to be one CCITCP2 process active on a network in order for CCI over TCP/IP to work, as long as all machines have been configured (using the CCI Configuration Utility) to use it. Alternatively, multiple CCITCP2 processes running in the network can coexist and can communicate between each other so that a machine configured to use one daemon can find an application registered with a different daemon in the network. For instance, it is possible for every machine on the network to be running a copy of CCITCP2 and be configured to use their own local copy to search for connections. This would, however, generate a lot more network broadcast traffic compared to having just one daemon which all machines are configured to use.

The CCI Configuration Utility needs to be run on a machine before CCITCP2 can be successfully started on it (enter a blank hostname if the daemon is run locally). Once started, the daemon will accept service registrations until the effective RAM available to the process is exhausted, or until it is shut down.

CCITCP2 can be started manually at any time (as long as it is not already running) by entering:

ccitcp2

at a Micro Focus command prompt, or it can be started automatically at system start-up by including it in the startup folder. Alternatively, on NT, it can be installed as a service.

On UNIX systems CCITCP2 can only be started by a superuser (root).

  • Using Directory Server Instead of CCITCP2
  • CCITCP2 Search Order
  • CCITCP2 Troubleshooting
Parent topic: CCI Support For TCP/IP
Related reference
Running the CCI Configuration Utility


Using Directory Server Instead of CCITCP2

If you have installed Enterprise Server, available with Enterprise Developer and standalone, then the CCITCP2 program will have been replaced by a trigger program that calls the Micro Focus Directory Server program. As far as CCI users are concerned, the Directory Server serves the same purpose as CCITCP2 and behaves in exactly the same way. Each machine that runs Enterprise Server must have the Directory Server program running on it, and for Windows machines it is automatically installed and started as a service. For more information about the Directory Server see your Enterprise Server Configuration and Administration book.

Parent topic: Using CCITCP2


CCITCP2 Search Order

If both the Server Name and Machine Name (see Application Configuration for a definition of these terms) are specified by the client application, the CCITCP2 process returns the machine and port address of the service specified to the client so that it can establish a connection with the named service. If the service is not found, an error is returned.

However, if the Server Name is specified but the Machine Name is not, the CCITCP2 process searches all the registered Server Names in the reachable network in the following order until either the named service is found or an error is returned:

  1. The CCITCP2 process returns the address and port of any occurrence of the Server Name that is registered with it and is running on the same machine as the CCITCP2 process.
  2. The CCITCP2 process returns the address and port of any occurrence of the named service that is registered with it but is running on another machine.
  3. The CCITCP2 process returns the address and port of the first occurrence of the named service that is registered with any other addressable CCITCP2 process. Note that there is no guarantee which particular service this will be.
  4. The CCITCP2 process returns an error to the calling program if the named service still cannot be found. At this point the client will probably keep re-trying for a fixed amount of time, in case the service has been started after the client first began searching for it.

You can avoid the potential problem of producing an undesired connection from the third level search by closely observing the rules followed at the first two search levels or by using a unique name for each server process on the network.

Parent topic: Using CCITCP2
Related information
Application Configuration


CCITCP2 Troubleshooting

This section provides information that may be useful if you experience problems when using CCI over TCP/IP with CCITCP2.

  • "mfcobol port entry not found in services file" error

    Run the CCI Configuration Utility on the machine receiving this error: this should automatically update the TCP/IP services file with the necessary entries.

  • "Cannot find CCITCP2" error

    Run the CCI Configuration Utility on the machine receiving this error. Make sure that the hostname or TCP address value matches that of the machine running the CCITCP2 process you expect to use, and that the CCITCP2 process is running on that machine. Use "ping" and "ftp" to make sure that the machine is reachable using the address you have specified. Check that there are no CCITCP environment variables or CCI.INI file entries over-riding the value specified by the Configuration Utility. If the value has been changed recently, make sure that the failing process has been subsequently re-started.

  • "Registered service found but could not make a connection" error

    There are two main possible causes of this message:

    • This error can occur if the CCI server the client is trying to connect to has abnormally terminated, but still remains registered with the CCITCP daemon that both the client and server are pointed at. (Where possible, CCITCP attempts to detect this sort of abnormal termination and tries to remove the Server Name entry which is no longer valid, however this cannot be guaranteed.) The client then connects to the CCITCP2 daemon, which tells it where to look for the CCI server, but when it then tries to connect to the terminated server and fails it will give the above error.

      To check to see if this is what is happening close and re-start the CCITCP2 daemon that the client is pointed at. This will clear it of all registered Server Names, including any "orphan" servers. (If CCITCP2 is running in debug console mode then you can press F2 and it will list what CCI servers are registered with it.) Check to see that the CCI service is not abnormally terminating.

    • Another reason you may get this error is if both the CCI server and client can see the CCITCP2 daemon, but they cannot contact each other directly (because of the network topology: packets from the client are not reaching the server because a bridge or router is not allowing them through). Check that the client can "ftp" from the machine running the CCI server and visa versa. If they cannot, then notify the system administrator.
  • "A CCITCP call has timed out" error

    This most commonly occurs if the server application that the client is attempting to contact is not running at the time the client is started. However, it can also a be produced in a network topology which includes routers or bridges which have not been configured to allow CCITCP2 daemons to communicate with each other. For example, if a client fails to connect with a registered service as follows:

    • Server A registers itself with the CCITCP2 process running on machine A
    • Client B looks for server A using the CCITCP2 process running on machine B
    • Client B fails to connect to server A.

    The CCITCP2 modules are designed to communicate with each other using the TCP/IP broadcast address mechanism. If this is not correctly configured, CCITCP2 cannot locate services registered with other CCITCP2 modules. If this happens, you should advise your system administrator.

    System administrators should be aware of the following:

    • Bridges and gateways that are not configured to pass broadcast addressed packets will have a blocking effect on CCITCP connectivity. These items must be re-configured to pass broadcast packets if the registration of processes is performed on a leg of a network other than that of the requesting client. The actual configuration operations for these are specific to each device. In this situation, the use of a CCITCP2 module on the same leg of the network for both client and server applications will avoid the problem.
    • Most bridges and routers can be configured to only pass broadcast packets using certain TCP/IP port numbers; that is, a filter is applied. To allow CCITCP2 to communicate across bridged networks, your router or bridge should allow broadcasts using port number 86 in the UDP domain to pass unhindered through the filter.

    For CCITCP2 modules to communicate correctly, your network must be configured to pass broadcast packets to all areas that want to use CCITCP.

Parent topic: Using CCITCP2
Related information
CCI Configuration Utility


Advanced Features

  • Using CCI Over TCP/IP Without CCITCP2
Parent topic: CCITCP Configuration


Using CCI Over TCP/IP Without CCITCP2

  • Direct Connection and Starting Servers on Fixed Ports
  • Environment Variables and the CCI.INI File
Parent topic: Advanced Features


Direct Connection and Starting Servers on Fixed Ports

A CCITCP2 registration daemon is not necessary if the CCI client application and the CCI server application establish a connection directly between each other. This can only be done when the server application starts up on a specific TCP port, and the client knows which address and port the server is using.

In a relatively static application enterprise environment where the server application location is well-defined and persistent, then using direct connection can have advantages over using a CCITCP2 registration process to help establish a connection.

Allowing a server application to listen on a known, fixed port means that clients can contact the server through a security firewall if a gap has been configured for that port and address.

A CCI server can support both direct connection and normal connection via a CCITCP2 daemon simultaneously. If a server starts on a fixed port, and a CCITCP2 daemon is present, then it will register a Server Name with it as normal, but in addition clients will be able to connect to it directly because the port it is using is known. If the CCITCP2 daemon is not present or reachable then a fixed port server will still start successfully, but only clients who attempt to connect directly will be able to contact it.

Parent topic: Using CCI Over TCP/IP Without CCITCP2


Environment Variables and the CCI.INI File

A variety of environment variables and CCI.INI file entries can be used to customize CCI behavior either on a machine-wide or per-process basis. Most users should not need to use either of these methods, but they are provided in case a greater degree of application control is required.

If more than one of the above methods is used for the same purpose or feature, the order of precedence that determines the behavior is:

  1. environment variable
  2. CCI.INI option
  3. the original or default behavior
  • CCITCP Environment Variables
  • CCITCP Options in the CCI.INI File
Parent topic: Using CCI Over TCP/IP Without CCITCP2


CCITCP Environment Variables

In the following sections UNIX users should use the appropriate method of setting environment variables for the user shell which is being used. The examples given are guides using the manner of setting environment variables found on the PC.

  • CCITCP2 Environment Variable

    Instead of using the CCI Configuration Utility to set the TCP address of the machine running the CCITCP2 registration daemon the environment variable "CCITCP2" can be used instead. This may be useful if you need different processes on the same machine to contact different registration daemons. The value can be set from the command prompt by typing:

    set CCITCP2=hostname

    where hostname is the TCP hostname or dotted decimal IP address of the machine running the CCITCP2 daemon you wish to contact from that session.

    The environment variable value will always take precedence over any value set using the Configuration Utility. To restore a process to using the value set by the Configuration Utility simply set the environment variable to an empty string e.g.

    set CCITCP2=

    Alternatively, if this environment variable is set system-wide (by creating a system variable in the system environment settings, or by using a CONFIG.SYS file) then this value will always take precedence over any value set using the Configuration Utility.

  • CCITCPS_ Environment Variable

    If you want to start a CCI server on a fixed port, then you can associate the Server Name with the port value by using the CCITCPS_ environment variable (instead of appending the information on the Server Name itself, as described in the CCITCP Server Name section). If the Server Name is server_name, and you want it to use the fixed TCP port 3000, this can be specified by typing:

    set CCITCPS_server_name=MFPORT:3000

    Note that this will only work if the server application process is started in the same session or process that has this environment variable set.

  • CCITCPT_ Environment Variable

    If a client is known to be trying to connect to a server with Server Name server_name, and the TCP address (server_hostname) and port (e.g. 3000) that the server is using is known, then the client can be made to connect directly to it by setting an environment variable as follows:

    CCITCPT_server_name=MFNODE:server_hostname,MFPORT:3000

    Note that this can be used instead of setting the client Machine Name value (see section CCITCP Machine Name). This is useful if the Machine Name value the client specifies cannot be altered by an application defined method.

Parent topic: Environment Variables and the CCI.INI File
Related information
CCITCP Machine Name
CCITCP Server Name


CCITCP Options in the CCI.INI File

The CCI.INI file is only used by CCITCP if direct connection or a fixed port server is required. In addition, this configuration method is only recommended when the Server Name or Machine Name cannot be modified by the application that is using CCI, and the environment variable method described in the section above is also not considered suitable.

There are two possible sections in the CCI.INI file which are specifically used by CCITCP:

[ccitcp-servers]

which can have entries of the following form:

server_name=MFPORT:xxxxx

This is used exclusively to match a given Server Name server_name (see CCITCP Server Name for a description of valid values) with a fixed TCP port value xxxxxx.

The other CCI.INI section used is:

[ccitcp-targets]

which expects entries of the following form:

server_name=MFNODE:server_hostname,MFPORT:xxxxx

This is used exclusively by clients to associate a target Server Name server_name with a Machine Name value to the right of the "=" character (see CCITCP Machine Name for valid values and uses).

Parent topic: Environment Variables and the CCI.INI File
Related information
CCITCP Server Name
CCITCP Machine Name


Application Configuration

CCITCP Client/Server applications use the CCI Server Name and Machine Name parameters to enable the CCI Client to specify the CCI Server with which to communicate.

The CCI Server identifies itself on the network by using the Server Name parameter. The CCI Client specifies the CCI Server using the Server Name. Additionally, if it only wants to find this Server running on a particular machine in the network, it needs to specify the Machine Name parameter.

  • CCITCP Server Name
  • CCITCP Machine Name
Parent topic: CCITCP Configuration


CCITCP Server Name

Both CCI server and CCI client applications need to have a Server Name specified: server applications need to register themselves as available under this name (or what fixed port to use); and clients need to specify which server they wish to contact. The Server Name is not the same as the TCP host name of the machine the application is running on, but a name chosen by the server application to identify itself on the network so that client applications can find it whichever machine it is running on.

Server Name can be any valid alphanumeric string (up to 127 characters in length). Names beginning with a ',' character, or including the consecutive characters ",MF" are reserved for Micro Focus use.

If you wish to have the server start on a fixed or known TCP port (see Direct Connection and Starting Servers on Fixed Ports), then this can be achieved by appending the string ",MFPORT:xxxxx" to the Server Name, where xxxxx is the decimal value of the port. This string is not used as part of the Server Name, but is interpreted by CCI so that the server uses the specified port for listening for incoming clients. If you do not wish the server to have any name (that is, clients cannot use CCITCP2 to contact the server, but can only specify it directly by using the Machine Name parameter) then the Server Name need only consist of this string.

Note:

It is recommended that you do not use port numbers below 2000 as these may already be in use by standard TCP services. The maximum port value normally supported is 65535. Care should be taken not to use a port value that is already in use by other standard applications: check with the system or network administrator on valid port value ranges that should be used.

Parent topic: Application Configuration
Related information
Direct Connection and Starting Servers on Fixed Ports


CCITCP Machine Name

This is a parameter that only needs to be specified by CCI client applications.

This should be the TCP address (either the hostname if DNS is enabled, or the dotted decimal address if not) of the machine you wish to restrict the client to contacting. If you know that the Server Name of the application the client is trying to contact is unique in the reachable network, or you do not care which server of this same name it connects to, then this parameter is optional.

If you do not wish to use a CCITCP2 daemon to resolve the TCP address and port that the server is using (see Using CCI over TCP/IP without CCITCP2), but want the client to contact the server directly, then the Machine Name must have the following form:

MFNODE:server_hostname,MFPORT:xxxxx

where server_hostname is the hostname or dotted decimal address which the server application is using, and xxxxxx is the decimal port value.

Parent topic: Application Configuration
Related information
Using CCI over TCP/IP without CCITCP2


CCI Tracing

You can trace CCI activity through the Consolidated Tracing Facility (CTF).
  • Enabling CCI Tracing
Parent topic: Configuring CCI
Related information
CCITCP Configuration
CCI.INI - The CCI Configuration File
CCI Status Messages
The Consolidated Tracing Facility


Enabling CCI Tracing

To enable CCI tracing, you must first enable CTF tracing, then edit the CTF configuration file, ctf.cfg, to trace the CCI component:

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

  • CCITRACE Environment Variable
  • Tracing Options for CCI.INI
  • Activating CCI Tracing for Fileshare
Parent topic: CCI Tracing
Related information
To Enable CTF Tracing


CCITRACE Environment Variable

Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by setting the CCITRACE environment variable as follows:

CCITRACE=options

where:

options
Any, or all, of the following:
/F or -F | logs the details of CCI API calls to the trace file. The default is OFF, unless any other trace option is specified, in which case it is ON.
/P or -P | logs the details of protocol-level calls to the trace file. The default is OFF. If this flag is OFF, then only the details of the CCI user-level API will be traced. If this flag is ON, the level of function tracing may be greatly increased.
/D or -D logs the contents of all buffers passed to and from the CCI functions. The default is OFF.
Warning: This type of tracing may not produce the desired results if the application has been coded to prohibit data tracing.

The CCI.INI file ([ccitrace_base] section) can also be used to control trace options, but any values specified by the CCITRACE environment variable will take precedence.

Parent topic: Enabling CCI Tracing
Related information
Tracing Options for CCI.INI
Activating CCI Tracing for Fileshare
To Enable CTF Tracing


Tracing Options for CCI.INI

Part of the process to enable CCI tracing is to specify the degree of information that will be traced, which can be done by configuring the [ccitrace-base] section of the CCI configuration file, CCI.INI. The options are:

Option | Value | Meaning
force_trace_on | yes or no | If yes, details of CCI API calls are logged to the trace file. The default is no. Unless this option is specified, no tracing will be generated, even if the other options are set to yes.
protocol_trace | yes or no | If yes, details of protocol-level calls are logged to the trace file. If this option is yes, the level of function tracing may be greatly increased. The default is no.
data_trace | yes or no | If yes, the contents of all buffers passed to and from the CCI functions are logged. The default is no. Warning: This type of tracing may not produce the desired results if the application has been coded to prohibit data tracing.

For example, to enable CCI API tracing and data tracing, but not protocol-level tracing, add the following:

[ccitrace-base]
force_trace_on=yes
protocol_trace=no
data_trace=yes

The CCITRACE environment variable can also be used to control trace options, and any values specified by the variable will take precedence over values in CCI.INI.

Parent topic: Enabling CCI Tracing
Related information
CCITRACE Environment Variable
Activating CCI Tracing for Fileshare
To Enable CTF Tracing


Activating CCI Tracing for Fileshare

To activate CCI tracing on a Fileshare server, you must add the following /tr parameter setting to the Fileshare Server configuration file:

/tr cci

Prior to starting the Fileshare Server, you also need to have enabled CCI tracing as described in Enabling CCI Tracing.

To prevent unauthorized access to the CCI information traced through Fileshare, you are prompted for the supervisor password (for user-id FSVIEW) when you invoke a Fileshare Server with CCI tracing enabled. If the password is accepted, CCI tracing is enabled, and a second prompt asks if CCI tracing should be activated immediately or not.

CCI tracing can be toggled on and off using the F3 key.

Parent topic: Enabling CCI Tracing
Related information
CCITRACE Environment Variable
Tracing Options for CCI.INI


CCI.INI - The CCI Configuration File

  • What is the CCI.INI File?
  • Where to Locate CCI.INI
  • The Format of CCI.INI
  • General Configuration Options for CCI.INI
Parent topic: Configuring CCI
Related information
CCITCP Configuration
CCI Tracing
CCI Status Messages


What is the CCI.INI File?

The CCI.INI file is used to specify selective configuration options for all or some CCI modules installed on a system. The contents of the CCI.INI file will vary from system to system in a network, depending upon the requirements for tuning each individual system.

Parent topic: CCI.INI - The CCI Configuration File


Where to Locate CCI.INI

CCI.INI may be located in a number of locations for testing and deployment. The Windows root directory is a good location as it is visible from all applications, on Windows systems of all types. The COBOL cobdir/bin installation directory or the application's current directory are good logical locations on UNIX systems. There may be configuration sections for more than one CCI protocol module in any CCI.INI file so care is required when choosing the location for a CCI.INI file. If you only want to affect the behavior of a single application, rather than affecting every application on the system, put the CCI.INI file in the current directory, from where the application is being run.

Parent topic: CCI.INI - The CCI Configuration File


The Format of CCI.INI

CCI.INI is a plain text file, which may be edited or created by any text editor. A CCI.INI file may look like this:-

[cci]
cci_param_check=yes
errlog_path=c:\ccilogdir\
ccitimeout=120000

[ccismem-base]
mem_file_size=8192
max_clients=2048
mem_files_location=c:\ccismem
log_max_sent_trans=yes
use_global_namespace=yes
peer_poll_sleep=300
errlog_path=c:\ccismemlogdir
cci_param_check=no

[ccitcp-servers]
myserver=MFPORT:3000
Parent topic: CCI.INI - The CCI Configuration File


General Configuration Options for CCI.INI

Use the following options in your CCI.INI file:

  • errlog_path
    Enables you to specify a location and filename for the CCI first failure error log file, and filter the types of information written to it.
Parent topic: CCI.INI - The CCI Configuration File
Related concepts
Where to Locate CCI.INI


errlog_path

By default, the CCI first failure log file is called ccierr.log and located in the working directory of the application calling CCI.

To change the name and location, specify the errlog_path option in a protocol-specific section of the configuration file (e.g. [ccitcp]) or in the general section (i.e. [cci]).

There are also other ways to set the location and filename of the log file. A valid setting is searched for in the following order, and when one is found, subsequent settings are ignored:
  1. CCIERRLOG environment variable.
  2. errlog_path setting in a protocol-specific section of CCI.INI.
  3. errlog_path setting in the general section of CCI.INI.
  4. CCI-Option library routine.

Parameters:

The errlog_path setting takes the following parameters:
on/yes
Sets the level of detail recorded to FULL (see filter-type), and uses the default location and log file.
off/no
Turns off tracing.
file-string
Sets the output location and filename of the log file. If the location is omitted, the application's working folder is used. If the filename is omitted, the default name of ccierr.log is used.
Note: If the specified location does not already exist, the log file is not created.
filter-type
Sets the level of detail recorded in the log file. One of:
  • FULL or BASEIO - all options; this is the same as on or yes.
  • INIT - record only session establishment details.
  • TERM - record only session termination details.
  • INIT_TERM - record session creation and termination details.
  • ALL_DATA - record all session data transmissions.
  • SENT_DATA - record session transmission of data.
  • RECEIVED_DATA - record session receipt of data.

Examples:

The following example records errors to the default file ccierr.log in the location c:\ccilogs\ (Windows) or usr/ccilogs/ (UNIX).

Windows:

errlog_path=yes,c:\ccilogs\

UNIX:

errlog_path=yes,usr/ccilogs/
Note: If you are only specifying a location, ensure the pathname ends with \ (Windows) or / (UNIX).
The following example records all listening and client endpoint startup details, plus any failure messages, to the default location and filename.
errlog_path=INIT

The following example records the same level of detail as the previous example to the location and filename specified.

Windows:

errlog_path=INIT,c:\ccilogs\initoutput.log

UNIX:

errlog_path=INIT,usr/ccilogs/initoutput.log
Parent topic: General Configuration Options for CCI.INI
Related concepts
CCI Environment Variables


CCI Status Messages

All CCI modules produce text-based messages, describing the status of the completion of the last CCI operation. Some statuses are critical and require remedial action before use of the affected CCI module can continue. Others are warnings and, in most cases, do not require you to take any action.
  • CCI Status Messages
  • CCI Message Table
Parent topic: Configuring CCI
Related information
CCITCP Configuration
CCI Tracing
CCI.INI - The CCI Configuration File


CCI Status Messages

All CCI modules produce text based error messages describing the status of the completion of the last CCI operation. Some errors are critical and require remedial action before use of the affected CCI module can continue. Others are warnings and, in most cases, do not require you to take any action.

When an error occurs in the communications layer the CCI status codes returned to calling applications will change to reflect the underlying problem that has occurred. All CCI enabled applications can then make a call to CCI to obtain a text message describing the problem.

The manner in which these messages is returned to the application user is specific to each application, however the actual text returned from CCI is the same in all cases. The sections below indicate what the status messages mean, and what steps can be taken by the user to correct the situation which created the error status in the first place.

The text format used for all CCI messages is as follows:-

"CCITCP-0001I A CCITCP call has timed-out."

This is broken down in to the following sections:

  • Protocol issuing the message - "CCITCP"
  • Message number - "0001"
  • Severity level - "I"
  • Message text.- "A CCITCP call has timed-out."

Not all the available messages are produced by all the protocol modules, there are also messages which are specific to individual aspects of configuration on specific protocol environments. Some status are intended for use only during the development of CCI enabled applications, where these status are seen by the end user they should contact our technical support staff and report the situation and applications which generated the status condition.

Parent topic: CCI Status Messages


CCI Message Table

The following is a list of status numbers returned which may be produced from CCI modules, along with a brief explanation of their meaning, and, if applicable, a suggestion as to how to resolve the issue being reported. Status numbers which are produced to aid coding of CCI applications have been included in this list.

Message Number | Severity | Reason | Resolution
0000 | Information | The last operation completed successfully | No action to take
0001 | Information | The last operation timed out prior to completion. | Increase time-out periods if the application allows, or check the status of the remote application to ensure that its host system is still functioning.
0002 | Information | A buffer given to a CCI receiving operation was too small to contain the incoming data stream. | This is a warning intended for applications designers. Contact us if you suspect that this is actually causing a problem.
0003 | Error | A bad parameter was given to a CCI function. | This is a application coding problem. Contact our technical support department and report any of these errors that appear.
0004 | Warning | This is only generated from a Service initiation. This status indicates that a Service with the same name was previously registered at the same network address. | No action required, the current Service is now registered with the network, connecting clients will connect to this Service.
0005 | Error | This is only generated from a Service initiation. This status indicates that a Service with the same name was previously registered at the same network. | Two services cannot exist on some networks with the same Service name, choose another name to start this Service with.
0006 | Error | A name parameter passed being used to start a client or a Service was invalid. | The range of valid names differs for underlying protocols, please see the sections for the relevant CCI module for the protocol in use for this information.
0007 | Error | An attempt was made to use a connection which has already been terminated. | This is a application coding error, contact our technical support department and report any occurrence of this error.
0008 | Error | A broken connection was detected on this link. | Check the status of the network supporting this link and determine whether the problem lies at the network or at the machine at the far end of the link.
0010 | Warning | The CCI module in use was too busy to complete the request. | Allow some of the outstanding CCI actions to complete before trying again.
0011 | Warning | The CCI module discovered that the system was too low on memory to complete an action. | Close any unwanted applications, and free up some memory to allow the application to continue.
0012 | Error | No service was found, the client could not complete a connection request. | Check the address passed as a location to the client and try again.
0013 | Error | The address specified in the direct addressing modes would not accept a client connection. | Check the address passed as a location to the client and try again. The service listening at the far end may not be compatible with a CCI client.
0014 | Error | An error occurred when creating a network endpoint. | The local network service provider was incapable of creating a new connection point, this usually means that a resource limit has been reached, or that the network itself is disabled. Check the system status and raise network resources as appropriate.
0015 | Error | A transport error has occurred | CCI full network transport failure has been reported to CCI from the transport provider. Check the network status, correct any problems that are found and try again.
0016 | Error | A CCI support module was not found on the network. | Some CCI protocols and configurations require network support modules, such as CCITCP2, please check to ensure that you have configured your network correctly to use CCI, and that the required support modules are running before starting CCI, then try again.
0017 | Error | A transport connection error has occurred | Where possible CCI will distinguish between this message and message 0016. This message indicates that an individual connection has failed, rather than a general network failure occurring. Check the application at the far end of the link to ensure that it is still functioning.
0018 | Information | An asynchronous call has not completed yet. | This status is intended for application programmers to monitor the status of an ongoing operation, it may be ignored by end users.
0019 | Information | An asynchronous call has completed correctly. | This status is intended for application programmers to monitor the status of an ongoing operation, it may be ignored by end users. It is functionally equivalent to status "0000".
0020 | Information | An asynchronous call has completed part one of a two part operation.. | This status is intended for application programmers to monitor the status of an ongoing operation, it may be ignored by end users.
0021 | Error | An error occurred when closing a session. | This could be a network or operating system failure, however a failure at this time may not affect the overall running of an application. Contact our technical support department if you suspect that this is actually causing a problem.
0022 | Error | This is only generated from a Service termination. Could not de-register a service | There was a problem when terminating a service that prevented it being de-registered from the CCI support modules such as CCITCP2, or from the network provider itself. Subsequent attempts to start a Service with the same name will generate messages 0004 or 0005 depending upon the network which is being used.
0023 | Error | This is only generated from a Service application. A client connection could not be completed due to a network level error condition. | The network service provider reported a failure to allow a full connection of an incoming client. Check the connecting clients to determine which of them is failing to connect, then check the network provider on the client and server machines for version compatibility.
0024 | Error | A call to HANGUP a server session could not complete as data was still queued. | This is an application coding error. Contact our technical support department.
0025 | Error | Transport initialization failure, INITCLIENT could not find CCITCP2, | The UDP support in the TCP/IP service provider configuration may be switched off, or may have run out of available resources. Ensure that UDP is enabled and that sufficient sockets are available, then try again.
0026 | Error | Transport initialization failure during INITCLIENT. | Check the version details of the network service provider to ensure that CCI is compatible with this level of network provider.
0027 | Error | A call to CCI-Query was made with an invalid session handle. | This is an application coding error. Contact our technical support department.
0028 | Error | A call to CCI-Wait was made with an invalid session handle. | This is an application coding error. Contact our technical support department.
0029 | Error | Parameters were incorrectly passed to the call named in the text. | This is an application coding error. Contact our technical support department.
0030 | Error | A listen call failed as the machine was too busy to receive any more incoming client connections. | The system configuration is too small to support the connection load being used, either increase the system capacity for the protocol in use, or reduce the load on this specific system by examining other possible alternative to using this system.
0031 | Error | A CCI function detected a transport failure during an attempt to receive a data buffer. | The network, or the machine at the far end of the connection, experienced an error condition, correct the network error and try again.
0032 | Error | CCI-Transact function detected a transport failure during an attempt to send a data buffer. | The network, or the machine at the far end of the connection, experienced an error condition, correct the network error and try again.
0033 | Error | CCI-Transact function detected a transport failure during an attempt to receive a data buffer. | The network, or the machine at the far end of the connection, experienced an error condition, correct the network error and try again.
0034 | Error | CCITCP could not find an entry for "mfcobol" in the "services" TCP/IP configuration file. | An entry such as : 'mfcobol <TAB> 86/udp' must be included in the file for CCI to establish a registration ,or make a registration enquiry with a CCITCP2 module.
0035 | Error | The far end of a connection has been reset. | Check this status of the remote end of a connection as it appears to have dropped off the network.
0036 | Information | CCITCP2 could not be found, a CCI Service could not de-register correctly from CCITCP2. | The Service registration module, CCITCP2, may have been closed or the network link to the machine hosting CCITCP2 may have died. If CCITCP2 is still running any requests for this Service will find a registration which is not responding to Client connection attempts. Any further requests to register the Service by the same name will get a status "0004" returned as it was already registered. See the CCITCP configuration guide for further details about using CCITCP2.
0037 | Error | An invalid service handle was passed to the CCI function named in the text. | This is an application coding error. Contact our technical support department.
0038 | Error | An invalid async' request handle was passed to CCI-Query or CCI-Wait. | This message has been superseded by "0027" and "0028" and should only be found on older CCI installations. See "0027" and "0028" for the correct action to take.
0039 | Warning | A data buffer and length combination given to CCI crossed a segment boundary in memory. Data was truncated at this boundary. | This is an application coding error. Contact our technical support department.
0040 | Error | A call to CCI-Suspend was made prior to a call to CCI-Resume. | This is an application coding error. Contact our technical support department.
0041 | Error | A call to initialize a network service provider has failed | Check the network support for the system and correct any problems found, then try again.
0042 | Error | Could not attach to a Network Server | This CCIIPX message indicates that no NetWare server has been found on your network. CCIIPX cannot operate with a NetWare server on its network and so cannot continue.
0043 | Error | Cannot connect to an incompatible version of CCI | A connection has been requested between dissimilar CCI installations, this has been detected and to prevent possible data flow problems a connection cannot be completed. please check the revisions in use and update the CCI installations as required before trying again.
0044 | Error | Could not register a service | This could be a configuration error, see CCITCP2, or the underlying network could have failed to allow the registration due to insufficient capacity of available resources, see message 0025.
0045 | Error | A bad address was passed to a CCI initialization call. | Check that the addresses used in the configuration are of the correct style and content for the CCI module being used, then try again.
0046 | Error | CCIAPPC failed to locate an APPC session | Ensure that the local LU is defined for this session.
0047 | Error | A call to CCI failed as CCI has already been terminated. | This is an application coding error. Contact our technical support department.
0048 | Error | A bad data buffer location was passed to CCI for use in sending or receiving data. | This is an application coding error. Contact our technical support department.
0049 | Error | CCI-Trace was unable to create trace output files for the CCI module named in the text. | There may be insufficient space left on the fixed disk to hold the data trace file. Please clear some space and try again.
0050 | Error | The requested CCI-TRACE output file could not be opened | Check that write permissions are available for the user of the application being traced, and that there is sufficient disk space remaining to store the trace file before trying again.
0051 | Error | An unexpected CCI error has occurred. | This is an internal CCI error. Contact our technical support department.
0052 | Information | This status is reserved for future use. |
0053 | Information | This status is reserved for future use. |
0054 | Information | This status is reserved for future use. |
0055 | Warning | Cannot send or receive data on a suspended session. | This is an application coding error. Contact our technical support department.
0056 | Error | Client found a registered service but could not make a connection. |
0057 | Error | Insufficient permission to complete an operation. | Check the process permissions for the configuration files being used. Note: If this error is reported during a failure to start CCITCP2, MFDS, or a listener on UNIX. All UNIX and Linux environments require root user permission to start TCP/IP services on reserved ports. These are typically port values lower than 1024
0060 | Error | Protocol does not support the requested operation. | Use a different protocol or do not attempt this operation.
0061 | Error | The requested operation has been disabled. | Internal error, please contact Micro Focus SupportLine.
0062 | Error | CCITCP SSL_new call failed - internal resource limitation error. | A system or process limit has been reached. Please retry using fewer TCP/IP connections to the system. If this does not resolve the issue then reduce the number of listeners being used in this process.
0063 | Error | CCITCP SSL_Connect call failed - maybe an un-trusted Server. | CCITCP cannot connect to the specified server because of a cryptographic configuration mismatch between peer and this system. Check your SSL options and ensure that they are compatible between server and client. For example, ECDSA clients may not be able to connect to an RSA certified server.
0064 | Error | SSL could not obtain a certificate from the peer on this link. | The local end is configured to require a trust in the peer. The peer is not providing an identity certificate that can be checked. Confirm that the peer's configuration matches your connection requirements.
0065 | Error | SSL Configuration Error, All connection methods disabled - could not connect. | The local SSL options are incorrectly configured to enable a connection between server and client. Try extending the range of ciphers and/or protocols used in the server configuration.
0066 | Error | CCITCP SSL_accept call failed due to invalid client credentials. | The connecting client does not have the required certificated credentials resulting in the connection being rejected. Correct the client configuration or reduce the server's peer checking requirements.
0067 | Error | An error was found in the 'publicname' parameter syntax. |
0068 | Error | An error was found in the 'machinename' parameter syntax. |
0069 | Error | SSL Configuration requires a CA Root certificate, none was found. |
0070 | Error | SSL Configuration error, ID certificate file not found or corrupted. |
0071 | Error | SSL Configuration error, ID certificate format not acceptable. |
0072 | Error | SSL Configuration error, ID certificate password incorrect. |
0073 | Error | SSL Configuration error, ID private keyfile not found or corrupted. | If the wrong password is used with some types of keyfile then this error message is returned instead of 74. Check the password being used is correct. If the password is correct, check that the keyfile has not been corrupted.
0074 | Error | SSL Configuration error, ID keyfile password incorrect. |
0075 | Error | SSL Configuration error, Password incorrect or Certificate and Keyfiles do not match |
0076 | Error | SSL Server connection context error, internal error. |
0077 | Error | SSL Connection error, Peer ID certificate location content and actual address do not match. |
0078 | Error | SSL Connection error, peer certificate has no subject field content. |
0079 | Error | SSL Connection error, peer certificate has no issuer detail - cannot verify with a CA issuer |
0080 | Warning | SSL Connection error, peer certificate has no revocation list address. | This can be ignored if you do not require certificate revocation list checking. To avoid this warning, modify your certificate to contain the correct information fields to support revocation checks.
0089 | Error | SSL Configuration error, Invalid or unsupported SSL/TLS Protocol. | Check the protocol list configuration.
0090 | Error | SSL Configuration error, Invalid SSL/TLS Cipher List. | Check the cipher list configuration with the OpenSSL cipher list specification.
0091 | Error | SSL Configuration error, Invalid ECC curve list. | Check that you are using a valid range of ECC curve definitions for products that support a per-connection initial ECC curve specification.
Parent topic: CCI Status Messages
Related information
CCITCP2


Environment variables (Windows)

These are the most common environment variables that can be used with the Micro Focus products on Windows.

The following environment variables are set in the system registry. You can change the values using the SET command, but values you set are only added to the values already set in the registry.

CCITCP2 | Specifies the machine that the CCITCP2 daemon is running on.
COBCPY | The location of COBOL copybooks.
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.
COBDIR | The location of the COBOL system directory.
COBHNF | The location of .hnf files.
COBPATH | Specifies the locations in which to search for .int, .gnt and .lbr files. To specify more than one location, use the ; (semicolon) separator (Windows) or the : (colon) separator (UNIX).
LIB | Tells the Linker where to find .lib files.
INCLUDE | Specifies which directories should be searched for such things as resource include files.
PATH | Indicates which directories Windows should search for executable files.

The following environment variables can be set from within your environment using the SET command:

COBCONFIG_ | The location of COBOL configuration files.
COBCONFIG.BLOCK | The location of the application configuration file.
COBFSTATCONV | Specifies name of a user-supplied module that the Callable File Handler should use to convert the file status codes if an I/O error is encountered on a file.
COBIDY | The location of debugger .idy files.
COBLANG | Tells the COBOL system in which language environment you want to run your COBOL program. COBLANG can be used in conjunction with third party products using values of the LANG environment variable which are in a different format than that used by the COBOL system.
COBPRFDIR | Specifies a directory to be used for storing .ipf files created by programs compiled with the PROFILE compiler directive.
COBSW | Used to pass COBOL run-time system and user switch settings to user application programs.
DB2DBDFT | Identifies the DB2 database to be accessed by the application.
DD_ | Used to identify environment variables that define file-name mappings.
ENTRYNAMEMAP | Specifies entry name map files and folders containing them.
EXTFH | Specifies the File Handler configuration file to use.
FHREDIR | Specifies a configuration file to be used by the Fileshare Client.
FSIDXINTEGRITY | When this is set to OFF, this writing to disk any changed nodes held in the index cache, until space in the cache is needed for other nodes.
HCOBND | Sets a directory for storing BIND files.
HELPFILES | The list of files to be loaded at initialization by HyHelp.
LANG | Tells the system in which language environment you want to run your program.
MAINFRAME_FLOATING_POINT | Specifies the floating point format used.
MFCSCFG | Specifies a configuration file to be used by the Client/Server Binding client program. It is also used by the Client/Server Binding server program when the srvtier facility is used.
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 | When this is set 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.
MFEXTMAP | Used by the External File Mapper to locate the file mfextmap.dat.
MFLOGDIR | Specifies a directory to be used by the Client/Server Binding for log files.
OOSW | Used to set run-time switches that effect OO programs.
SORTCOMPRESS | Tells the system whether or not to execute a compression routine on each record to be sorted. SORTCOMPRESS=5 allows for run-length encoding of sort records, resulting in much better performance when records contain multiple repeated characters. Note that 5 is the only valid value for this.
SORTSCHEME | Use in conjunction with SORTSPACE for improved performance. This is activated by setting SORTSCHEME=1. This is the only valid value for the environment variable. See SORTSPACE below for more information.
SORTSPACE The amount of memory to be allocated to internal workspace for SORT operations. This can be specified in different formats: for example, you could specify 64M, 2G, and 1000000 to give sort memory areas of 64 Megabytes, 2 Gigabytes and 1000000 bytes respectively.
Typically, increasing SORTSPACE will improve the overall performance of your SORT. This can be further improved by the use of SORTSCHEME when the files to be sorted are over 1GB. Consider:
  • Setting SORTSCHEME when your files are in excess of 1GB.
  • The size of the record minus the key-size when setting SORTSCHEME on.
  • The SORTSPACE levels for SORTSCHEME. The following are the minimum settings for SORTSCHEME to take effect with the key size:
    • 1Mb or greater - records up to 5k non key
    • 4Mb or greater - records of 12K non key
    • 8Mb or greater - records of 28K non key
    • 16Mb or greater - records of 62k non key
    • For very large SORTs, a greater SORTSPACE maybe required.
  • Setting SORTSPACE to a higher value may result in more temporary file space being used.
SORTTEMPSPACE The amount of temporary memory to be allocated to internal workspace for SORT operations. This can be specified in different formats much like the SORTSPACE environment variable. By using SORTTEMPSPACE, you can maximize available memory.

To maximize the use of available memory to improve performance, particularly in systems suffering from memory fragmentation, the memory allocation strategy used by SORT can be adjusted through use of the SORTTEMPSPACE environment variable. Increasing the amount of SORTTEMPSPACE can help prevent "SORT020U SORT(EXTSM) failed - sort engine status = 9/105" error messages.

SORTTYPE | Setting SORTTYPE=2 forces SORT to use the file handler, so that format modifications are picked up from the extfh.cfg file. Not setting this means SORT will try to use CBL_ routines to read and write files to improve performance. Note that 2 is the only valid value for this environment variable.
SQLPASS.TXT | Supplies the user ID and password for automated compiles done on a remote DB2 server.
STRICTVSAM | When set to ON and under a mainframe emulation, a file status of 37 is returned when you open an existing VSAM file for OUTPUT and the file has or previously had some data written to it, or if the file format is different from the file on disk. The default for this variable is OFF.
TESTCOVER | Enables you to use the test coverage tool, which creates a statistical execution profile of a program. This should be set to the path of the test coverage configuration file.
TMP | Tells the run-time system where to put paging files Normally it puts these files in the current directory. By using TMP you can specify a different drive or path for them.
Parent topic: General Reference
Related concepts
File Not Found Errors
Related information
Run-Time Configuration Properties
Running
To use test coverage from the command line


Environment Variables (UNIX)

This appendix lists all the environment variables that are available on UNIX, 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 the same operating system as it was created.
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
  • PL/I
  • 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
  • IDE Information 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
Overview - H2cpy 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
  • Messages COBCH2000 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.
For syntax errors, ErrorCode is generally of the form COBCHnnnns (applies to Windows environments only). See Explanation of Error Codes for more information on the possible values that ErrorCode can have.
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 regardless of the setting of the E .
  • 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:

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


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


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 MAXERROR 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 MAXERROR directive.
Parent topic: COBCH0081 - COBCH0100


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


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
  • COBCH0472 No CICS directives have been set
  • 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
  • COBCH0476 No IMS directives have been set
    The source contains EXEC DLI statements, but the EXECDLI Compiler directive has not been specified.
  • 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.
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


COBCH0472 No CICS directives have been set

The source code includes some EXEC CICS statements but the CICSECM Compiler directive has not been set at file or a project level.

Parent topic: COBCH0461 - COBCH0480
Related reference
CICSECM
CICSECM Compiler Directive Options


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


COBCH0476 No IMS directives have been set

The source contains EXEC DLI statements, but the EXECDLI Compiler directive has not been specified.

Set the EXECDLI Compiler directive in your source code.

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


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
  • COBCH0536 CICS LINKAGE items generated
  • 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


COBCH0536 CICS LINKAGE items generated

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


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


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


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


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

Parent topic: COBCH0841 - COBCH0860


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


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
    Inline directives ($SET statements) and conditional compilation 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

Inline directives ($SET statements) and conditional compilation 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
  • COBCH1090 Literal contains SBCS Katakana characters
  • COBCH1091 Literal contains DBCS or SBCS Katakana characters
  • COBCH1092 SBCS Katakana character usage in source is not portable
  • COBCH1094 NOPRESERVECASE not supported with ILGEN. Consider removing NOPRESERVECASE.
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


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


COBCH1094 NOPRESERVECASE not supported with ILGEN. Consider removing NOPRESERVECASE.

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 SLiteral is greater in length than data item
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 SLiteral is greater in length than data item

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


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


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


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


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


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


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 (UNIX), or the 32-bit command prompt (Windows), JAVA_HOME must be 32 bit; if using cob64 (UNIX), or the 64-bit command prompt (Windows), 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
Related tasks
JVM COBOL support


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.
  • COBCH1585 Could not find peverify.exe, required for ILVERIFY(CHECK)
    The utility PEVerify.exe, which is called if you compile using ILVERIFY(check), is missing from the local machine.
  • 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


COBCH1585 Could not find peverify.exe, required for ILVERIFY(CHECK)

The utility PEVerify.exe, which is called if you compile using ILVERIFY(check), is missing from the local machine.

PEVerify.exe is installed as default with the full version of Microsoft Visual Studio, but not with the Visual Studio Shell. It is also available as part of the .NET Framework Tools, which you can download and install.

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 "Enterprise Developer"
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.
  • COBCH1630 Restricted compiler license: target file will not be produced
    You are using a restricted license that will not produce an output file as part of the compilation process; only the syntax is checked.
  • 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


COBCH1630 Restricted compiler license: target file will not be produced

You are using a restricted license that will not produce an output file as part of the compilation process; only the syntax is checked.

Enterprise Developer Personal Edition provides a development environment that supports analysis, editing and syntax checking of COBOL and mainframe programs outside of the mainframe environment. However, it does not support the production of an output file (.int, .gnt, .obj, .exe) during compilation; for that, you need to use Enterprise Developer.

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 Enterprise Developer.
  • 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 Enterprise Developer, 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 Enterprise Developer 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 Enterprise Developer, 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 Enterprise Developer.

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.
  • COBCH1726 ILSMARTLINKAGE class <class-name> has multiple definitions
    The ILSMARTLINKAGE directive has caused the generation of more than one class with the same name.
  • 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


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


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


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


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 System.Void (.NET) or java.lang.void (JVM) 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.
  • 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.
  • 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.
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


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


COBCH1821 - COBCH1840

Lists the Syntax Checking error messages from COBCH1821 through COBCH1840.
  • 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


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


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


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


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


Messages COBCH2000 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 COBCH2000 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.
For code generation errors, ErrorCode is generally of the form COBOPnnn-s (applies to Windows environments only). See Explanation of Error Codes for more information on the possible values that ErrorCode can have.
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.
For run-time system errors, ErrorCode is generally of the form COBRTnnnn (applies to Windows environments only).
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 Enterprise Developer.
  • 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 Enterprise Developer.
  • 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 fork().
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 Enterprise Developer.

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

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.

In a Windows environment, this results in the file mfdebug.log being generated in your current directory. However, if the application does not have write permissions to that directory, mfdebug.log is created in a product specific directory instead, under the directory specified by the LOCALAPPDATA environment variable; for example, %LOCALAPPDATA%\Micro Focus\<product name>\<product version>\logs\mfdebug.log.

SupportLine may request you supply this file when troubleshooting the error.

Parent topic: COBRT101 - COBRT120
Related concepts
HOSTFD


COBRT115 Unexpected signal (Fatal)

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

In a Windows environment, this results in the file mfdebug.log being generated in your current directory. However, if the application does not have write permissions to that directory, mfdebug.log is created in a product specific directory instead, under the directory specified by the LOCALAPPDATA environment variable; for example, %LOCALAPPDATA%\Micro Focus\<product name>\<product version>\logs\mfdebug.log.

SupportLine may request you supply this file when troubleshooting the error.

Parent topic: COBRT101 - COBRT120


COBRT116 Cannot allocate memory (Fatal)

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

Resolution:

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

Parent topic: COBRT101 - COBRT120


COBRT117 Bad collating sequence (Fatal)

This is an internal system error.

Resolution:

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

Parent topic: COBRT101 - COBRT120


COBRT118 Symbol not found (Fatal)

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


COBRT119 Symbol redefined (Fatal)

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

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

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

Resolution:

You can recode your application to remove the naming duplication.

Parent topic: COBRT101 - COBRT120


COBRT120 Symbol string table of zero size (Fatal)

You probably have a malformed object file.

Resolution:

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

Parent topic: COBRT101 - COBRT120


COBRT121 - COBRT140

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


COBRT121 Symbol is not in TEXT section (Fatal)

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

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

Resolution:

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

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

Parent topic: COBRT121 - COBRT140


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

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

Resolution:

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

Parent topic: COBRT121 - COBRT140


COBRT123 Unknown relocation type (Fatal)

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

Resolution:

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

Parent topic: COBRT121 - COBRT140


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

See the 9/124 status code in Fileshare Extended Status Codes for more details.

Parent topic: COBRT121 - COBRT140


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

See the 9/125 status code in Fileshare Extended Status Codes for more details.

Parent topic: COBRT121 - COBRT140


COBRT126 Record size exceeds system limit (Fatal)

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

Resolution:

Correct the record size.

Parent topic: COBRT121 - COBRT140


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

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

Resolution:

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

Parent topic: COBRT121 - COBRT140


COBRT128 Connection to Fileshare Server refused

Your request to the Fileshare Server has been rejected, either because the server has been suspended, or your request was not valid at this time.

You should investigate the state of your Fileshare server before continuing.

Note: You will receive this message if you attempt to connect directly to a server that is operating as a secondary server within a high availability group.
Parent topic: COBRT121 - COBRT140
Related concepts
Configuring iFileshare for High Availability
FSView


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

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

Resolution:

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

Parent topic: COBRT121 - COBRT140


COBRT130 Connection to Fileshare Server re-established (Recoverable)

A connection to your Fileshare server has been re-established.

If there were any in-flight transactions at the point of the Fileshare server going down, these will have been rolled back.

Parent topic: COBRT121 - COBRT140


COBRT135 File not found (Recoverable)

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

Resolution:

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

Parent topic: COBRT121 - COBRT140


COBRT136 Corrupt or invalid executable file (Fatal)

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

Resolution:

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

Parent topic: COBRT121 - COBRT140


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.

For Windows environments

If you want the event to appear in the Windows Application Event log you can configure the Consolidated Tracing Facility to do this with configuration entries such as the following:

mftrace.dest = WINEVENT
mftrace.level = WARN

mftrace.emitter.winevent#level = 2
mftrace.comp.mf.rts#api = TRUE

The mftrace.emitter.winevent#level = 2 entry is required because by default the WINEVENT emitter does not output any events below level 3 (ERROR).

In previous versions of this COBOL system, the error returned by the system call was written to the Windows Application Event log. You can revert to this behavior by setting the os_error_log tunable to true. If you set os_error_log to true and configure the Consolidated Tracing Facility as described above, each COBRT199 error causes two entries to be written to the Windows Application Event log.

Parent topic: COBRT181 - COBRT200


COBRT200 Run-time system internal logic error (Fatal)

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

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

Resolution:

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

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

Parent topic: COBRT181 - COBRT200


COBRT201 - COBRT220

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


COBRT201 I-O error in paging system (Fatal)

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

Resolution:

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

Parent topic: COBRT201 - COBRT220


COBRT203 CALL parameter not supplied (Fatal)

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

One possible cause is when an attempt has been made to access the record area, but it has not yet been allocated because a file is not yet in the OPEN state; see the HOSTFD directive for more details.

Resolution:

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

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

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

Resolution:

Check the definition of the class.

Parent topic: COBRT241 - COBRT260


COBRT244 Licensing initialization error (Fatal)

An error occurred initializing the run-time license.

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT245 There are no valid product licenses (Fatal)

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT246 Maximum number of product licenses exceeded (Fatal)

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT247 Licensing error (Fatal)

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

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

Resolution

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

Parent topic: COBRT241 - COBRT260


COBRT249 Process killed (signal-number) (Fatal)

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


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

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


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

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

Resolution:

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

Parent topic: COBRT241 - COBRT260


COBRT252 Memory corruption detected (Fatal)

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

Resolution:

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

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


COBRT253 Cannot load file - unsupported format (Fatal)

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


COBRT254 Keyboard interrupt to ANIMATOR during ACCEPT (Fatal)

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


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


IDE Information Messages

The following messages are only informational ones. Usually, there is a suggested action you can execute to improve the code or resolve an issue.

  • COBQA Error Messages
    Lists the warning messages related to the Visual Studio Quick Action feature.
Parent topic: COBOL


COBQA Error Messages

Lists the warning messages related to the Visual Studio Quick Action feature.
  • COBQA0001: Name can be simplified
    Information message only. An IDE quick action is available if you want to replace the highlighted fully-qualified namespace with its simplified equivalent.
  • COBQA0002 - Use portable COBOL syntax instead
    Information message only. An IDE quick action is available if you want to convert the highlighted .NET type to a COBOL predefined type.
  • COBQA0003 - Extract selected code to a new copybook
    Information message only. An IDE quick action is available if you want to move the selected code into a new copybook in your project.
  • COBQA0007 - Extract the selected code to a new section
    Information message only. An IDE quick action is available if you want to move the selected code into a new section in the current file.
Parent topic: IDE Information Messages


COBQA0001: Name can be simplified

Information message only. An IDE quick action is available if you want to replace the highlighted fully-qualified namespace with its simplified equivalent.

Description

When referencing .NET types in your code, you can either use the fully qualified namespace or only use the simplified name and omit the namespace, if the simplified name can be resolved without ambiguity. For example, instead of typing System.String, you can simply type String provided that String is not used by any other class.

Use the Simplify name Type light bulb quick action in the editor to automatically replace the fully qualified name with the simplified name:

You can choose to simplify the current occurrence of a fully qualified name or simplify all occurrences of that name in the current file (click Document) or in the current file and any copybooks displayed in the expanded copybook view in it (click Program).

Parent topic: COBQA Error Messages


COBQA0002 - Use portable COBOL syntax instead

Information message only. An IDE quick action is available if you want to convert the highlighted .NET type to a COBOL predefined type.

Description

The light bulb quick action, Convert to COBOL Syntax, is available for some .NET types that have a corresponding predefined managed COBOL type. You can convert such types to COBOL predefined types - for example, System.UInt64 converts to binary-double unsigned.

Using COBOL predefined types ensures that your applications are platform independent and you can easily export them from Visual Studio and edit them with Enterprise Developer for Eclipse.

To convert a type:

  • Click the light bulb quick action, Convert to portable COBOL syntax, in the editor:

You can choose to simplify the current occurrence of a fully qualified name or simplify all occurrences of that name in the current file (click Document) or in the current file and any copybooks displayed in the expanded copybook view in it (click Program).

Parent topic: COBQA Error Messages


COBQA0003 - Extract selected code to a new copybook

Information message only. An IDE quick action is available if you want to move the selected code into a new copybook in your project.

Description

There is a Visual Studio quick action, Extract to Copybook, available for the selected code that you can optionally apply. This quick action creates a new copybook in the project and adds the selected code to it.

To apply the action:

  1. Click the Extract to Copybook command in the light bulb tooltip:

  2. Specify a name and location for the copybook when prompted and then click Save.

    This creates the copybook file and adds it to the project.

Parent topic: COBQA Error Messages


COBQA0007 - Extract the selected code to a new section

Information message only. An IDE quick action is available if you want to move the selected code into a new section in the current file.

Description

Note: Applies to native COBOL only.

There is a Visual Studio quick action, Extract to Section, available for the selected code that you can optionally apply. This quick action creates a new section in the file opened in the editor and moves the selected code to it.

To apply the action:

  1. Select the lines of code you want to move.
  2. Click the light bulb icon ( light bulb) to see the suggested fixes:

  3. Click Extract to Section in the drop-down list.

    Executing this command replaces the selection a perform new-section statement. It also adds a new section called new-section.

    The name of the new section is highlighted in the editor and the IDE displays the Rename: new-section widget enabling you to change the name of the section right away.

  4. Enter a new name for the section in the editor.

    The name is automatically updated in the two places where it is referenced.

Parent topic: COBQA 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
Btrieve Error Codes
Btrieve Error/ COBOL File Status Mappings
DB2 ECM Error Messages
File Status Codes
Extended File Status Codes
HCOSS Messages
OpenESQL Preprocessor Error Messages
Rebuild Error, Information and Warning Messages
RM/COBOL File Status Codes
SQL Option for DB2 Error Messages
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


PL/I

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
CodeWatch Error Messages
PL/I Run-time Error Codes
Open PL/I Error Messages


Enterprise

Look in the sections below to find the error messages produced by the area of the product you are working with.

  • Workflow Manager Messages
  • zServer messages and Diagnostics
Parent topic: Error Messages
Related concepts
RJSE Error Messages
Related reference
Enterprise Server Error Messages
Related information
AppMaster Builder Error Messages
Directory Server Error Messages
Drag and Drop Error Messages
JCL Error Messages
IMS Error Messages
Status Codes Returned by the MVS Server


Workflow Manager Messages

  • Introduction
  • Error messages
  • Sample error situations
  • Known issues
Parent topic: Enterprise


Introduction

This guide is meant as a help for error situations that can be traced back to the Workflow Manager.

Generally, we distinguish between expected and unexpected error situations. For example, an expected error situation would be one when the user enters an incorrect connection password.

Unexpected error situations can further be grouped into situations that were foreseen by the software and those that were not. For example, a foreseen error situation would be that the connection to the remote system is broken, and an example of an unforeseen error situation would be a programming error in the software.

Depending on the type of error, the user or system administrator has different sources for help to deal with the situation.

For expected and unexpected but foreseen error situations, an error dialog in the Eclipse Workbench is displayed. For example:

The information in the dialog box should enable a user to handle this type of problem.

If the error was reported by the underlying z/Server software, a z/Server message ID is displayed in the dialog (in the example above this would be SLR0071E). The first three alphabetic characters of the message ID define the z/Server facility that detected the error. The facility’s acronym is followed by four digits which represent the sequential message number within the messages for this z/Server facility. A z/Server message ID ends with a character stating the severity of the message (I: informational, W: warning, E: error, S: severe error).

In some situations, the XML error message is returned in the original XML format, for example:

XML format error

The values of the XML tags FACID, MSGNO and SEVERITY have to be concatenated to give the z/Server message ID, in this case SLR0131E.

The mapping between message prefix and z/Server facility is as follows:

Message Prefix | z/Server Facility
API | Application programming interface (TCPIP)
BND | IEWBND (Binder) interface
CSI | Catalog search interface
DSC | Holder task configuration
EMC | Extended MCS interface
HLD | Holder task interface
IPC | Command task
JES | Job entry subsystem interface
LIC | License interface
MAL | Email interface
REC | Recovery exception handler
REX | REXX command environment
SJB | Started job interface
SLR | TSO scheduler interface
SPR | Standard pool routine
SRV | Server interface
SSI | Interface to z/OS SSI
STA | Started task interface
TAU | Eclipse client interface
UNI | Unicode conversion services
XML | XML system parser interface

Detailed information about z/Server messages and how to handle them can be found in z/Server Messages and Diagnostics.

For unexpected but foreseen error situations, the exception caught is displayed in the text area shown when the Details >> button is pressed.

The exception type often gives a hint as to what caused the problem. In the example above, there is some kind of network connection problem, which could for example mean that the connection to the network was interrupted or that z/Server is not up and running.

If the information found in the error dialog is not sufficient to solve the problem, view the error log for further information. See Troubleshooting for details on how to access the error log, how to enrich it with debug information, and how to send that information to Micro Focus SupportLine.

Unexpected and unforeseen error situations will not normally produce an error dialog, but in some cases, information related to a software exception not caught is recorded in the error log.

Error messages lists all messages and describes the user, workflow modeler or server administrator response.

Troubleshooting contains instructions for the Application Workflow Modeler (the administrator) on how to find the cause of problems that may stem from Application Workflow Modeler, and offers solutions. It also describes the information that Micro Focus SupportLine needs when the Application Workflow Modeler cannot solve the problem.

Sample error situations is designed for support engineers to become accustomed to the way the software reacts during selected error situations.

Known issues shows currently known software errors, including tips on how to deal with them.

Parent topic: Workflow Manager Messages
Related information
Troubleshooting
Error messages
Sample error situations
Known issues


Error messages

The following user roles are used in this documentation:
User
Person who works with the Application Workflow Manager (AWM) software.
Model administrator
Person who maintains the Application Workflow model and develops tools for it.
Server administrator
Person who administers the server which provides the services requested by the Application Workflow Manager client.

Error messages have an ID consisting of nine alphanumeric characters. The first five alphabetic characters determine the internal package in which the error has arisen. The following four digits represent a sequential numbering of the messages within the corresponding package.

Numbers in curly brackets within the message text represent placeholders, which are substituted by variables during execution time, e.g. {0}.

Failed to read the parameter file {0} .

  • CEA support core (ECEAC) messages
  • CEA support UI (ECEAU) messages
  • AWM core (TSCOR) messages
  • AWM IDz (TSRDZ) messages
  • AWM z/Server (TSZSV) messages
  • AWM edit macro (TSMAC) messages
  • AWM ED integration (TSMFI) messages
  • AWM meta model (TSMDL) messages
  • AWM meta model editor (TSMET) messages
  • AWM remote preprocessor (TSRPP) messages
  • AWM MVS system (TSMVS) messages
  • AWM SVN integration (TSSVN) messages
  • AWM UI (TSUIN) messages
  • zExplorer for z/Server (TSXZS) messages
  • zExplorer subsystem JES (TSXJE) messages
  • zExplorer subsystem MVS (TSXMV) messages
  • zExplorer subsystem USS (TSXUS) messages
  • z/Server communicator (SOZCM) messages
  • z/Server ISPF panel support (TSIPS) messages
  • z/Server meta model (SOMDL) messages
Parent topic: Workflow Manager Messages


CEA support core (ECEAC) messages

  • ECEAC0002 Action cancelled by user.
  • ECEAC0003 Failed to parse the message: {0} .
Parent topic: Error messages


ECEAC0002 Action cancelled by user.

The sending of a message was canceled by the user.

User Response:
Self-explanatory.
Parent topic: CEA support core (ECEAC) messages


ECEAC0003 Failed to parse the message: {0} .

Self-explanatory.

User Response:
Self-explanatory.
Parent topic: CEA support core (ECEAC) messages


CEA support UI (ECEAU) messages

  • ECEAU0001 Failed to close the screen.
  • ECEAU0002 Can not open the EditorPart.
  • ECEAU0007 Sending of the TSO message \ {0} \ failed.
  • ECEAU0008 Failed to properly log off from {0} :{1} . You are now disconnected.
  • ECEAU0009 Failed to determine an ISystemImage.
  • ECEAU0011 Sending a key response failed.
  • ECEAU0012 Sending a key response failed.
  • ECEAU0013 Sending a menu item response failed.
  • ECEAU0014 Sending a point and shoot response failed.
  • ECEAU0015 Failed to open the \TSO command shell\.
  • ECEAU0016 The connecting was interreupted.
Parent topic: Error messages


ECEAU0001 Failed to close the screen.

The sending of the close screen message failed. The logical ISPF screen did not close.

User Response:
Reconnect to the z/Server.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0002 Can not open the EditorPart.

The workbench failed to open a new EditorPart.

User Response:
Retry. If it does not work, restart Eclipse.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0007 Sending of the TSO message \ {0} \ failed.

The sending of a TSO message to the CEA user server failed.

User Response:
Check your network connection to the server.

Reconnect to the server.

Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0008 Failed to properly log off from {0} :{1} . You are now disconnected.

The client failed to properly disconnect from the z/Server. Possible reasons are:

  • The network connection was interrupted.
  • The user server ended abnormally and did not shut down.
Server Administrator Response:
Determine what caused the problem. Check the z/Server logs for more information. Contact SupportLine if necessary.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0009 Failed to determine an ISystemImage.

An internal exception occurred because no instance of the ISystemImage type was passed to the method.

User Response:
Disconnect and try to connect again. If it does not work, contact SupportLine.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0011 Sending a key response failed.

The connection to the zServer is closed. This might be caused by a connection or an internal zServer problem.

User Response:
Check your network connection to the server.

Reconnect.

Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0012 Sending a key response failed.

The connection to the zServer is closed. This might be caused by a connection or an internal zServer problem.

User Response:
Check your network connection to the server.

Reconnect.

Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0013 Sending a menu item response failed.

The connection to the zServer is closed. This might be caused by a connection or an internal zServer problem.

User Response:
Check your network connection to the server.

Reconnect.

Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0014 Sending a point and shoot response failed.

The connection to the zServer is closed. This might be caused by a connection or an internal zServer problem.

User Response:
Check your network connection to the server.

Reconnect.

Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: CEA support UI (ECEAU) messages


ECEAU0015 Failed to open the \TSO command shell\.

The workbench failed to open the "TSO command shell".

User Response:
Try to open it manually.

Restart Eclipse.

Parent topic: CEA support UI (ECEAU) messages


ECEAU0016 The connecting was interreupted.

An error occurred while trying to connect to the zServer.

User Response:
Retry.

Restart Eclipse.

Parent topic: CEA support UI (ECEAU) messages


AWM core (TSCOR) messages

  • TSCOR0001 An error occurred during execution of tool {0} or reading its output.
  • TSCOR0002 Failed to read the parameter file {0} .
  • TSCOR0003 Error during execution of tool {0} .
  • TSCOR0004 The tool {0} exceeded the maximum return code of {1} .
  • TSCOR0005 Failed to create the elementlist {0} .
  • TSCOR0007 A resource with the logical name {0} was not found.
  • TSCOR0008 A tool type is missing for tool descriptor {0} .
  • TSCOR0009 The tool {0} did not return a tool execution status.
  • TSCOR0010 Tool Descriptor {0} needs an ISAPlugIn attribute, because its tool-type attribute was set to {1} .
  • TSCOR0011 A bundle (Plug-In) with the ID {0} was not found.
  • TSCOR0012 Activator for Plug-In {0} not found.
  • TSCOR0013 No extension was found for the tool-type {0} .
  • TSCOR0014 Tool {0} returns fewer parameters than expected. {1} parameters were parsed while {2} parameters were specified for this tool!
  • TSCOR0019 The FileDescriptor parameter pFDSource must not be null.
  • TSCOR0024 Failed to execute local syntax check because the element cannot be determined.
  • TSCOR0025 Failed to execute local syntax check. There may be no property group associated with the element.
  • TSCOR0026 The local syntax check could not be performed because a local copy of the element was not found.
  • TSCOR0030 Failed to receive an element with ID {0} .
  • TSCOR0031 Failed to load a cached element list.
  • TSCOR0033 Failed to determine element types for Elementlist creation. {0}{1}
  • TSCOR0034 Failed to generate an element ID for element type {0} . Available properties: {1}{2}
  • TSCOR0035 The element type {0} is not defined in the model.
  • TSCOR0036 Failed to determine an element type. Empty set of properties was given.
  • TSCOR0037 Failed to load a cached filter.
  • TSCOR0040 Failed to get file contents for job submit. File: {0}
  • TSCOR0041 Failed to retrieve a data stream for the job submit. Either a file input parameter was not configured, or a valid editor was not opened in the foreground.
  • TSCOR0042 Could not perform error feedback. The corresponding element could not be retrieved.
  • TSCOR0043 Invalid configuration of integrated tool RefreshDependencies: The integrated tool needs 2 file input parameters. 1) Error Feedback XML. 2) Copybooks XML.
  • TSCOR0044 Context missing for execution of integrated tool RefreshDependencies.
  • TSCOR0045 Element missing for execution of integrated tool RefreshDependencies.
  • TSCOR0046 Failed to refresh dependencies because a local copy of the element was not found.
  • TSCOR0047 The configuration of integrated tool {0} must contain a file output parameter.
  • TSCOR0048 Property sets are not supported by this product variant.
  • TSCOR0049 At least three input parameters must be defined for the Integrated Tool Property Group Creator: {0} 1) Property Set Name{0} 2) Language{0} 3) SYSLIB Path
  • TSCOR0050 {0} resource operation failed due to an exception.
  • TSCOR0051 The input file descriptor must have the type MVSPO_MEMBER,MVSSEQ or WORKSPACE_FILE
  • TSCOR0052 At least two input parameters must be defined for the Integrated Tool Property Group Associator: {0} 1) Property Set Name{0} 2) (File) Data Set / Member
  • TSCOR0054 At least one input parameter must be specified for the Integrated Tool Property Group Remover.
  • TSCOR0055 The parameter {0} does not have a boolean value: {1} .
  • TSCOR0056 Invalid master configuration format parameter: {0} .
  • TSCOR0057 Failed to parse a system from the given master configuration file: {0}{1} .
  • TSCOR0058 Internal master configuration parser error. The line {0} does not contain the {1} -tag.
  • TSCOR0059 Exception occurred while executing OS command: {0} .
  • TSCOR0060 Failed to parse the return code {0} .
  • TSCOR0061 Tool {0} returns fewer parameters than expected. {1} parameters were detected whereas {2} parameters were specified for this tool.
  • TSCOR0062 UPDATE resource operation failed. No Properties found for updating.
  • TSCOR0063 Failed to determine a target element list for INSERT operation.
  • TSCOR0064 INSERT operation failed. No element type could be determined for the new element.
  • TSCOR0065 INSERT-CHILD operation failed. Selected resource does not have a children-list or -action.
  • TSCOR0067 Failed to restore the system reference {0} because the remote system {1} was not found.
  • TSCOR0068 Failed to load the application.
  • TSCOR0069 Invalid extension for extension point {0}
  • TSCOR0070 No ZConnector Extension was found.
  • TSCOR0071 Cannot write on file descriptor of type InputStream.
  • TSCOR0072 The file {0} does not exist.
  • TSCOR0073 {0} is not a valid format for a master configuration parser.{1}
  • TSCOR0074 A newer workflow model version is available. {0} The application will now be updated.
  • TSCOR0076 Pre-init failed.
  • TSCOR0077 System name missing.
  • TSCOR0078 ISystemImage missing.
  • TSCOR0079 The resource with the ID {0} could not be found.
  • TSCOR0080 Failed to create an ID for element type {0} . The key property {1} is missing.
  • TSCOR0081 Missing property value ( {0} ) for resource operation.
  • TSCOR0084 No valid extension found for the local syntax check extension point.
  • TSCOR0085 No valid extension found for the property group manager extension point
  • TSCOR0087 No valid extension found for the error feedback parser extension point
  • TSCOR0089 An I/O error occurred while reading a file input stream.
  • TSCOR0090 An error occurred while creating/opening the Eclipse project {0} .
  • TSCOR0091 Failed to create the internal systems folder in the workspace.
  • TSCOR0092 Failed to create the internal project folder in the workspace.
  • TSCOR0093 Error when parsing input for table. Value for property {0} not found.
  • TSCOR0094 File {0} does not exist.
  • TSCOR0095 The file {0} does not exist.
  • TSCOR0096 The master configuration file was not found. It must either be located in: {0}{1} .xml or {2} .txt or a master configuration provider must be implemented (Eclipse Extension Point).
  • TSCOR0097 Invalid argument. Element type must not be null.
  • TSCOR0099 Wrong parameters for integrated tool FileUploader. Two file input parameters were expected.
  • TSCOR0100 Failed to create the temp file. Input parameters missing.
  • TSCOR0102 Bad extension for extension point {0} .
  • TSCOR0104 Cached elements (et_elements.xml) could not be recovered.
  • TSCOR0105 Elements could not be cached. Failed to save et_elements.xml.
  • TSCOR0107 Failed to save the element list into cache.
  • TSCOR0108 The local Workflow Manager application folder could not be located.
  • TSCOR0109 Failed to store the Element list in file li_ {0} .xml.
  • TSCOR0110 An element list could not be restored: li_ {0} .xml.
  • TSCOR0111 Cached element lists (lm_elementlists.xml) could not be recovered.
  • TSCOR0112 An error occurred when trying to save the file lm_elementlists.xml.
  • TSCOR0113 File lm_elementlists.xml could not be deleted.
  • TSCOR0114 Failed to delete a cached element list (li_ {0} .xml).
  • TSCOR0115 Failed to delete unreferenced Elementlists.
  • TSCOR0116 A thread was interrupted while initializing the element lists.
  • TSCOR0117 Invalid argument. Element type must not be null.
  • TSCOR0118 Failed to interpret the selection count {0} .
  • TSCOR0119 {0} is not a valid file name.
  • TSCOR0121 Failed to load error entries from cache (er_errorFeedback.xml).
  • TSCOR0122 Failed to store error entries into cache (er_errorFeedback.xml).
  • TSCOR0123 The file descriptor with the ID {0} could not be found among previous output parameters.
  • TSCOR0124 The property {0} was not found within the execution context.
  • TSCOR0125 The property {0} was not found among previous output parameters.
  • TSCOR0126 An error occurred while loading a filter.
  • TSCOR0127 An error occurred when trying to create a SAX parser instance
  • TSCOR0128 An error occurred while parsing ft_filters.xml.
  • TSCOR0129 An error occurred when trying to save the file filters.xml.
  • TSCOR0130 Exception occurred when trying to delete ft_filters.xml.
  • TSCOR0131 An error occurred when trying to load the file jt_jobs.xml.
  • TSCOR0132 Failed to load opened files.
  • TSCOR0133 Failed to load error entries.
  • TSCOR0134 Failed to load Jobs.
  • TSCOR0136 Failed to remove cached elements.
  • TSCOR0137 Failed to remove cached filters.
  • TSCOR0138 Failed to {0} .
  • TSCOR0139 Backup folder could not be created.
  • TSCOR0140 Failed to copy the backup folder. {0} .
  • TSCOR0141 Converting an outdated application model failed.
  • TSCOR0142 An error occurred while trying to read the configuration file: {0} .
  • TSCOR0143 The configuration file {0} could not be found.
  • TSCOR0144 System could not create configuration dataset {0} .
  • TSCOR0145 An exception occurred while trying to close the configuration file {0} .
  • TSCOR0146 The given input stream is null. Possible reason: The model configuration file from the master configuration does not exist.
  • TSCOR0147 A system reference for connection {0} already exists!
  • TSCOR0148 Failed to add the system reference because no ISystemImage (remote system) given.
  • TSCOR0149 Failed to load system references.
  • TSCOR0150 An error occurred when trying to create a SAX parser instance
  • TSCOR0151 Failed to recover cached systems (st_systems.xml).
  • TSCOR0152 An error occurred when trying to save the file st_systems.xml.
  • TSCOR0153 Model update check failed. Either the master configuration could not be read or the update itself failed.
  • TSCOR0154 Failed to check for model update. The application does not seem to be loaded.
  • TSCOR0155 The model update was performed but the version numbers still do not match: {0} Master Configuration version number: {1}{0} Model version number: {3}
  • TSCOR0156 Missing location keyword in model path: {0} . {1} .
  • TSCOR0157 Wrong location keyword in model path: {0} . {1}
  • TSCOR0158 A file input parameter must be defined for the integrated tool LocalSyntaxCheck (the program source that should be checked).
  • TSCOR0159 A file output parameter (type = Workspace File) must be defined for the integrated tool file locator.
  • TSCOR0160 A file input parameter must be defined for the integrated tool EDIT_CLEANUP.
  • TSCOR0161 A file input parameter (describing the error XML input) must be defined for the integrated tool ErrorFeedback.
  • TSCOR0163 No input parameters configured for the integrated tool Local File Creator.
  • TSCOR0164 LocalFileCreator: Failed to create a local file because no element type could be determined from the given parameters.
  • TSCOR0165 Physical name of file descriptor {0} missing.
  • TSCOR0166 Could not find a property with the ID {0} . This is normal when the model has been changed and an old cache is loaded.
  • TSCOR0167 No ZConnector Extension was found for a remote system with the name {0} .
  • TSCOR0168 Illegal character # by applications name.
  • TSCOR0170 Missing input parameter target ID of tool {0} .
  • TSCOR0171 The action descriptor {0} contains a tool descriptor relationship without a target ID.
  • TSCOR0172 No element type was found for the match name {0} which is part of the compounded match name {1} .
  • TSCOR0173 No extension found for job utility.
  • TSCOR0174 Validate message parsing error: The validate message cannot be empty.
  • TSCOR0175 Validate message parsing error: Key {0} must be closed.
  • TSCOR0176 Validate message parsing error: MSGTEXT is mandatory.
  • TSCOR0177 UPDATE resource operation failed. No reference element was found for updating.
  • TSCOR0178 Parameter from USER_INPUT are not allowed for mass processing tools. Please change the parameter from attribute of parameter # {0} either to Context or Previous Tool.
  • TSCOR0179 Different Parameter from attributes are not allowed for mass processing tools. All mass processing parameters must either come from the context (e.g. selected elements) or previous tool resources (e.g. selected table rows from an input dialog).
  • TSCOR0180 Failed to find the workspace file for file descriptor {0} because the physical name is null or empty.
  • TSCOR0181 The file {0} already exists.
  • TSCOR0182 The execution of an action failed
  • TSCOR0183 An error occurred while executing the action {0} .
  • TSCOR0184 The cached information for {0} seems to be incompatible with the loaded model.
  • TSCOR0185 Failed to aquire a file descriptor from the given input.
  • TSCOR0186 The integrated tool ChildrenRefresher can only refresh files of the type Workspace_File, but a {0} file input parameter was modelled.
  • TSCOR0187 Failed to create an element ID. Either the input parameters do not contain an element type or all key properties.
  • TSCOR0188 Unable to get property value for parameter # {0} . No target ID property found.
  • TSCOR0189 {0} resource operation failed because no properties for the new element were specified.
  • TSCOR0190 {0} resource operation failed because the element ID for the new element could not be determined from the returned properties.
  • TSCOR0191 Target ID missing for input parameter # {0} .
  • TSCOR0192 The given error feedback XML file could not be parsed because the PACKAGE element was not found.
  • TSCOR0193 An error occurred while parsing the error feedback file.
  • TSCOR0194 A file input parameter (XML) which contains linked properties must be configured by the tool {0} .
  • TSCOR0195 Failed to set the value for linked property \ {0} \.
  • TSCOR0196 Failed to load cached AWM system, because a system provider with the ID \ {0} \ was not found.
  • TSCOR0197 Failed to load cached AWM system, because an error occurred while loading the cached AWM System with the Name \ {0} \.
  • TSCOR0198 An exception occurred while calling the method toolExecuted() of property provider \ {0} \.
  • TSCOR0199 Failed to parse master configuration: {0}{1}
  • TSCOR0200 The AWM application \ {0} \ was parsed before an AWM system name in a master configuration file.
  • TSCOR0201 No target ID of the property with the sequence number {0} is set within the element type {1} .
  • TSCOR0202 Failed to load cached AWM system \ {0} \ or load one if its previously loaded applications.
  • TSCOR0203 Invalid parameter override of tool \ {0} \ in action descriptor \{1} \. Reference \Parm To Override\ missing.
  • TSCOR0204 A default AWM system could not be created, because none of the following attributes has been set: \ {0} \, \{1} \ (one is required).
  • TSCOR0205 AWM system name cannot be null.
  • TSCOR0206 The AWM system \ {0} \ was not returned by parsing the master configuration file and can therefore not be refreshed. Delete the system and add it again, if the system name has changed in the master configuration.
  • TSCOR0207 A deprecated tool type extension could not be resolved.
  • TSCOR0208 A custom default configurations file path has been set, but the file was not found: \ {0} \.
  • TSCOR0209 Failed to instantiate a system provider of contributor \ {0} \.
  • TSCOR0210 Invalid \ {0} \ extension. \class\ attribute does not point to a {1} implementation. Contributor was \{2} \.
  • TSCOR0211 Invalid remote system connection creator extension {0} .
  • TSCOR0212 Failed to get the property value of linked property \ {0} \.
  • TSCOR0213 Exception while getting value of linked property \ {0} \ from property provider \{1} \. Resource identifier was \{2} \.
  • TSCOR0214 Model conversion failed.
  • TSCOR0215 Error while loading the model {0} . Starting model converter.
  • TSCOR0216 At least one problem occurred while loading AWM systems. See error log for more information.
  • TSCOR0217 Failed to create default AWM systems.
  • TSCOR0218 Failed to persist applications for AWM system \ {0} \.
  • TSCOR0219 An error occurred while loading cached elements.
  • TSCOR0220 An exception occurred while initializing the function package \ {0} \.
  • TSCOR0221 Function package \ {0} \ was not properly unloaded.
  • TSCOR0222 FileUploader for mass processing: The number of file sources must be the same as file targets.
  • TSCOR0223 The file descriptor type {0} cannot be opened.
  • TSCOR0224 Missing file name for file descriptor {0} .
  • TSCOR0225 An Eclipse resource path was expected as parameter # {0}{1} for the tool \{2} \ but the tool only contains {3} parameters.
  • TSCOR0226 The resource path \ {0} \ cannot be resolved to an Eclipse resource.
  • TSCOR0227 Invalid table view secondary id.
  • TSCOR0228 Failed to delete an old cached element list: {0} .
  • TSCOR0229 Resource identifier property cannot be the linked property itself: \ {0} \.
  • TSCOR0230 Warnings occurred during the execution of the tool. Maybe some properties have been renamed/deleted. \n\n {0}
  • TSCOR0231 Duplicate occurrence of property \ {0} \ in file descriptor \{1} \. This is only allowed for the file output parameter of this tool.
  • TSCOR0232 Line (line 1) of file \{1} \ contains less values than modeled has property relationships ({2} out of {3} ).{4} Line content is: \{5}\.
Parent topic: Error messages


TSCOR0001 An error occurred during execution of tool {0} or reading its output.

This exception can occur if a "job after action" encounters a problem while reading the tool output from the executed job. This is a top-level exception which usually contains more information in the error details.

User Response:
Refresh the Job View to see if the corresponding job still exists. If it disappears after refreshing, the tool output has probably been deleted already.
Model Administrator Response:
  • Verify that the executed tool returns correct output.
  • Verify that the tool output has been created properly (done by the REXX procedure TAUTOIFA).
Parent topic: AWM core (TSCOR) messages


TSCOR0002 Failed to read the parameter file {0} .

This exception can occur if a "job after action" fails to read the tool output from the executed job.

User Response:
Refresh the Job View to see if the corresponding job still exists. If it disappears after refreshing, the tool output has probably been deleted already.
Model Administrator Response:
Verify that the tool output has been created properly (done by the REXX procedure TAUTOIFA).
Parent topic: AWM core (TSCOR) messages


TSCOR0003 Error during execution of tool {0} .

This is a top-level exception that occurs if any executed tool (defined by a Tool Descriptor) encounters a problem. A more detailed message can usually be found in the error details (usually a message created by the executed tool). Possible causes:

  • An individual error message was created by the executed tool. This depends on the tool type.
  • An integrated tool encountered a problem.
  • The modeled tool type could not be resolved.
  • An executed tool did not return a valid tool execution status.
Model Administrator Response:
Solve the cause of the exception if a detailed message can be found in the error details. If necessary contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0004 The tool {0} exceeded the maximum return code of {1} .

This is a very common top-level exception. It occurs if any modeled tool returns a return code which is higher than the modeled "Max_RC", which is an attribute of the "Application Options" ("4" by default). A tool which returned a high return code most probably also returned a reason message. The reason message should be visible under "Reason" in the error dialog or can be found in the error details.

User Response:
Contact the model administrator if the reason given by the executed tool is not clear or if there is no reason message at all.
Parent topic: AWM core (TSCOR) messages


TSCOR0005 Failed to create the elementlist {0} .

An Action Descriptor with a reference to an Element List Structure (attribute "Has_Elementlist") was executed but the creation of the Element list failed. This is a top-level exception, and a more detailed message can usually be found in the error details. Possible causes:

  • The action was not intended to create an Element list.
  • The Element list cache cannot be saved in the workspace.
  • Modeling errors.
Model Administrator Response:
  • If no Element list should be created by the corresponding action, remove the value of the "Has_Elementlist" attribute from the Action Descriptor.
  • See Element List is Not Created to fix possible model problems.
Parent topic: AWM core (TSCOR) messages
Related information
Element List is not created


TSCOR0007 A resource with the logical name {0} was not found.

An "Action Descriptor has Tool" relationship was defined with an "Affected_Resource" name, but no previously executed tool returned a logical resource name within a tool-defined resource operation.

Model Administrator Response:
  • Correct the affected resource name in the "Action Descriptor has Tool" relationship or in the output of the executed tool. Remove the attribute from the relationship if it was not intended to be used.
  • Verify that a tool which returns the logical resource name is executed before the tool which returns the error message.
Parent topic: AWM core (TSCOR) messages


TSCOR0008 A tool type is missing for tool descriptor {0} .

A tool descriptor was defined without a "Tool_Type" attribute.

Model Administrator Response:
Define a "Tool_Type" or "Integrated_Tool" attribute for the corresponding tool descriptor.
Parent topic: AWM core (TSCOR) messages


TSCOR0009 The tool {0} did not return a tool execution status.

An executed tool did not return a "Tool Execution Status" which is a Java class that belongs to the API.

Model Administrator Response:
If a tool was executed by a custom-created tool executor by using the product API, contact the corresponding programmer. If necessary, contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0010 Tool Descriptor {0} needs an ISAPlugIn attribute, because its tool-type attribute was set to {1} .

A tool descriptor was modeled with a certain tool type which requires an "ISA_Plug-In" attribute but it is missing. This is a modeling error.

Model Administrator Response:
Add an "ISA_Plug-In" attribute to the tool descriptor ("New Child" -> "ISA Plug-In") and define the missing attributes. Example: If an input dialog was modeled (tool type "SWTDIALOG") you must specify a plug-in ID in the ISA Plug-In attribute.
Parent topic: AWM core (TSCOR) messages


TSCOR0011 A bundle (Plug-In) with the ID {0} was not found.

A tool descriptor was modeled with an "ISA_Plug-In" attribute where a certain plug-in ID was defined but no plug-in with the specified ID was found. Either the plug-in ID is not correct or the plug-in is not installed in the Eclipse environment.

Model Administrator Response:
Correct the plug-in ID in the "ISA_Plug-In" attribute of the tool descriptor or install the required plug-in. The "Plug-In Registry" Eclipse View is useful to find installed plug-ins.
Parent topic: AWM core (TSCOR) messages


TSCOR0012 Activator for Plug-In {0} not found.

A tool descriptor was modeled with the tool type "PLUGIN" but the referenced plug-in does not have an activator. This problem can only occur if additional plug-ins were implemented by using the product API.

Model Administrator Response:
Declare the class which implements the "IToolExecutor" interface to be the activator of the plug-in.
Parent topic: AWM core (TSCOR) messages


TSCOR0013 No extension was found for the tool-type {0} .

The tool type of a modeled tool descriptor could not be resolved. Either the "Tool_Type" attribute of the tool descriptor is incorrect or the plug-in which can execute the specified tool type is not installed properly.

Model Administrator Response:
Correct the "Tool_Type" attribute of the corresponding tool descriptor or install the required plug-in which contains a tool executor for the specified tool type.
Parent topic: AWM core (TSCOR) messages


TSCOR0014 Tool {0} returns fewer parameters than expected. {1} parameters were parsed while {2} parameters were specified for this tool!

The number of parameters an executed tool returned was lower than the number of output parameters modeled in its corresponding tool descriptor.

Model Administrator Response:
  • Remove output parameters from the tool descriptor or let the tool return fewer values.
  • If the number of returned values seems to be correct, verify that the output parameter separator does not occur within the output values. Change the separator if necessary.
Parent topic: AWM core (TSCOR) messages


TSCOR0019 The FileDescriptor parameter pFDSource must not be null.

The input file parameter for a tool creating a temporary file (remote edit, remote browse...) could not be found. This can be caused by a modeling error or incorrect usage of the API.

Model Administrator Response:
If the problem is caused by a modeled integrated tool, verify that the input parameters are correctly modeled.
Parent topic: AWM core (TSCOR) messages


TSCOR0024 Failed to execute local syntax check because the element cannot be determined.

A local syntax check could not be performed because no element was found within the execution context of the action.

Model Administrator Response:
Verify that actions containing a local syntax check integrated tool can only be executed on elements (no global actions).
Parent topic: AWM core (TSCOR) messages


TSCOR0025 Failed to execute local syntax check. There may be no property group associated with the element.

A local syntax check failed because no property with the attribute "Special_Property = Property_Group" was associated with the selected element.

Model Administrator Response:
Verify that a property with the attribute "Special_Property" set to "Property_Group" is defined and associated with the corresponding element type.
Parent topic: AWM core (TSCOR) messages


TSCOR0026 The local syntax check could not be performed because a local copy of the element was not found.

A local syntax check can only be perfomed if a local copy of an element exists. The local copy must be created by the integrated tool "LocalFileCreator".

User Response:
If a local copy of the element must be created in a separate action (e.g. a modeled "Check-Out" action), execute the action and retry the local syntax check. If you are working with different workspaces, verify that the local copy was not created in a different workspace.
Model Administrator Response:
Define the integrated tool "LocalFileCreator" in the model and verify that the local syntax check cannot be executed without the local file creator running beforehand.
Parent topic: AWM core (TSCOR) messages


TSCOR0030 Failed to receive an element with ID {0} .

An error occurred trying to get an element with its ID due to:

  • The internal application folder not being found or created, or being out of synchronisation.
  • The element XML file being damaged or not being able to be parsed.
User Response:
  • Refresh the internal project folder.
  • Restart the client.
  • Clear the element and elementlist cache.
Parent topic: AWM core (TSCOR) messages


TSCOR0031 Failed to load a cached element list.

An error occurred when parsing the XML file containing the elementlist. Therefore an element could not be determined with its ID.

  • The internal application folder cannot be found or created or is out of synchronisation.
  • The element XML file is damaged or cannot be parsed.
User Response:
  • Refresh the internal project folder.
  • Restart the client.
  • Clear the element and elementlist cache.
Parent topic: AWM core (TSCOR) messages


TSCOR0033 Failed to determine element types for Elementlist creation. {0}{1}

When trying to fill the element list, its element types could not be determined in the file descriptor properties.

Model Administrator Response:
Verify that the element types are configured under the properties of the file descriptor that creates the element list.
Parent topic: AWM core (TSCOR) messages


TSCOR0034 Failed to generate an element ID for element type {0} . Available properties: {1}{2}

When filling the element list, an element ID could not be generated.

Model Administrator Response:
Ensure that all the ID definitions and element type properties are returned from the file descriptor that creates the element list.
Parent topic: AWM core (TSCOR) messages


TSCOR0035 The element type {0} is not defined in the model.

When trying to fill the element list, an element type could not be determined.

Model Administrator Response:
  • Verify that the element types are configured under the file description properties.
  • Ensure that the element list file returns the element type at the correct position.
Parent topic: AWM core (TSCOR) messages


TSCOR0036 Failed to determine an element type. Empty set of properties was given.

This is a client code error.

User Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0037 Failed to load a cached filter.

The cached filters in the XML file cannot be read or the application folder is asynchronous.

User Response:
  • Refresh the internal application folder.
  • Restart the client.
  • Clear the filter cache.
Parent topic: AWM core (TSCOR) messages


TSCOR0040 Failed to get file contents for job submit. File: {0}

The integrated tool "SubmitJCL" could not submit a job because the input JCL which is passed by a file descriptor could not be read. The file path that was used is returned at the end of this message.

Model Administrator Response:
  • Verify why the file was not found under the given path or could not be read.
  • If the submit tool was modeled within an editor action (global action), remove the file input parameter from the corresponding tool descriptor. This will cause the tool to use the editor's contents as JCL input.
  • See Troubleshooting if the returned path appears to be empty.
Parent topic: AWM core (TSCOR) messages
Related information
Troubleshooting


TSCOR0041 Failed to retrieve a data stream for the job submit. Either a file input parameter was not configured, or a valid editor was not opened in the foreground.

No JCL input was found, to submit a job.

Model Administrator Response:
Define the integrated tool "SubmitJCL" in one of two ways:
  • Model a file input parameter which defines the JCL that should be submitted.
  • Define an editor action (global action) for the submit action. The job can then be submitted from an opened editor containing JCL.
Parent topic: AWM core (TSCOR) messages


TSCOR0042 Could not perform error feedback. The corresponding element could not be retrieved.

The integrated tool "ErrorFeedback" was executed without an element in the execution context. This can occur if the tool is modeled within a global action.

Model Administrator Response:
Ensure that the integrated tool "ErrorFeedback" is not used in a global action. Model "Element Type has Action" relationships as an alternative.
Parent topic: AWM core (TSCOR) messages


TSCOR0043 Invalid configuration of integrated tool RefreshDependencies: The integrated tool needs 2 file input parameters. 1) Error Feedback XML. 2) Copybooks XML.

The integrated tool "RefreshDependencies" was not modeled properly. Two file input parameters are required.

Model Administrator Response:
Ensure that two file input parameters are modeled properly. The first referenced file must contain compile errors and the second must contain all required copybook entries.
Parent topic: AWM core (TSCOR) messages


TSCOR0044 Context missing for execution of integrated tool RefreshDependencies.

This is an internal client error that occurred during execution of the integrated tool "RefreshDependencies".

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0045 Element missing for execution of integrated tool RefreshDependencies.

This is an internal client error that occurred during execution of the integrated tool "RefreshDependencies".

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0046 Failed to refresh dependencies because a local copy of the element was not found.

The "RefreshDependencies" tool can only be executed successfully if a local copy of an element exists. The local copy must be created by the integrated tool "LocalFileCreator".

User Response:
If a local copy of the element must be created in a separate action (e.g. a modeled "Check-Out" action), execute and retry the action. If you are working with different workspaces, verify that the local copy was not created in a different workspace.
Model Administrator Response:
Define the integrated tool "LocalFileCreator" in the model and verify that the "RefreshDependencies" tool cannot be executed without the local file creator running beforehand.
Parent topic: AWM core (TSCOR) messages


TSCOR0047 The configuration of integrated tool {0} must contain a file output parameter.

The integrated tool "LocalTempFileCreator" was not properly modeled. It requires a file output parameter which will be used to set the name of the created file for other tools to use.

Model Administrator Response:
Add a file output parameter to the tool descriptor of the integrated tool "LocalTempFileCreator".
Parent topic: AWM core (TSCOR) messages


TSCOR0048 Property sets are not supported by this product variant.

Property sets are currently only supported in combination with other products and reserved for future use.

Model Administrator Response:
Contact SupportLine for more information about property sets and future plans.
Parent topic: AWM core (TSCOR) messages


TSCOR0049 At least three input parameters must be defined for the Integrated Tool Property Group Creator: {0} 1) Property Set Name{0} 2) Language{0} 3) SYSLIB Path

The integrated tool "PropertySetCreator" was not properly modeled (parameters missing). It requires at least three input parameters: 1. Property Set name 2. Programming language 3. Library path

Model Administrator Response:
Correct any modeling errors concerning the tool descriptor for the integrated tool "PropertySetCreator". Valid parameter options are documented in the Administration Guide.
Parent topic: AWM core (TSCOR) messages


TSCOR0050 {0} resource operation failed due to an exception.

This is a top-level exception that will be printed into the error log if any exception occurs during a resource operation. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0051 The input file descriptor must have the type MVSPO_MEMBER,MVSSEQ or WORKSPACE_FILE

The integrated tool "PropertySetAssociator" was not properly modeled. The "Type" attribute of the File Descriptor which is referenced by a file input parameter must have one of the following values:

  • MVS_PO_Member
  • MVS_SEQ
  • Workspace_File
Model Administrator Response:
Change the "Type" attribute of the referenced file descriptor to one of the supported values (see description).
Parent topic: AWM core (TSCOR) messages


TSCOR0052 At least two input parameters must be defined for the Integrated Tool Property Group Associator: {0} 1) Property Set Name{0} 2) (File) Data Set / Member

The integrated tool "PropertySetAssociator" was not properly modeled (missing parameters).

Model Administrator Response:
Correct any modeling errors concerning the tool descriptor for the "PropertySetAssociator" integrated tool. Valid parameter options are documented in the Administration Guide.
Parent topic: AWM core (TSCOR) messages


TSCOR0054 At least one input parameter must be specified for the Integrated Tool Property Group Remover.

The integrated tool "PropertySetRemover" was not properly modeled (parameter missing).

Model Administrator Response:
Correct any modeling errors concerning the tool descriptor for the "PropertySetRemover" integrated tool. Valid parameter options are documented in the Administration Guide.
Parent topic: AWM core (TSCOR) messages


TSCOR0055 The parameter {0} does not have a boolean value: {1} .

An integrated tool descriptor was modeled with a boolean input parameter but the parameter value was not boolean.

Model Administrator Response:
Correct the parameter value or change the attributes "True_value" and "False_value" of the corresponding property.
Parent topic: AWM core (TSCOR) messages


TSCOR0056 Invalid master configuration format parameter: {0} .

This is an internal error. It occurs when the master configuration reader is called with an invalid format parameter.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0057 Failed to parse a system from the given master configuration file: {0}{1} .

The given master configuration (printed at the end of this message) was invalid.

Model Administrator Response:
  • Validate your master configuration and correct any errors. The syntax is documented in the Administration Guide.
  • If another error message, rather than the master configuration, is printed at the end of the message, correct any errors that prevent the master configuration from being returned.
Parent topic: AWM core (TSCOR) messages


TSCOR0058 Internal master configuration parser error. The line {0} does not contain the {1} -tag.

This error is caused if a line in a master configuration in FLAT format does not contain an expected keyword.

Model Administrator Response:
Correct the corresponding line in the master configuration.
Parent topic: AWM core (TSCOR) messages


TSCOR0059 Exception occurred while executing OS command: {0} .

This is a top-level message which covers several exceptions that can occur while an operating system command is executed:

  • Operating system error messages (e.g. "Invalid command 'XYZ'").
  • I/O exceptions while sending the command or reading the output.
Model Administrator Response:
  • Enable the client trace and verify that the sent commands are valid.
  • Check the error details and fix any operating system-dependent problems.
Parent topic: AWM core (TSCOR) messages


TSCOR0060 Failed to parse the return code {0} .

The return code of the executed tool did not contain a valid numeric value.

Model Administrator Response:
Correct the return code output in the called tool.
Parent topic: AWM core (TSCOR) messages


TSCOR0061 Tool {0} returns fewer parameters than expected. {1} parameters were detected whereas {2} parameters were specified for this tool.

An executed tool returned fewer parameters than modeled output parameters in the corresponding tool descriptor.

Model Administrator Response:
Either correct the tool output or the tool descriptor definition in the model so that the modeled output parameters match the actual tool output.
Parent topic: AWM core (TSCOR) messages


TSCOR0062 UPDATE resource operation failed. No Properties found for updating.

The UPDATE resource operation failed because no property values were returned by the corresponding tool. If no property values are returned, there is nothing to update.

Model Administrator Response:
  • If the "Resource_Processing" attribute of the tool descriptor was set to UPDATE verify that the called tool returns the values that should be updated and that the tool descriptor has modeled output parameters matching those values.
  • If the "Resource_Processing" attribute of the tool descriptor was set to TOOL_DEFINED, verify that the output parameters with the type "Element" are modeled.
  • If the tool was not intended to update properties, change the "Resource_Processing" attribute of the tool descriptor to READ.
Parent topic: AWM core (TSCOR) messages


TSCOR0063 Failed to determine a target element list for INSERT operation.

An INSERT resource operation could not be executed because no element list was found in the execution context. This can be caused by the tool being executed from a global action.

Model Administrator Response:
If the corresponding tool descriptor is referenced by a global action but also an Element-/Elementlist action, create a copy of the tool descriptor, set the "Resource_Processing" attribute of the copy to READ and use it for global actions.
Parent topic: AWM core (TSCOR) messages


TSCOR0064 INSERT operation failed. No element type could be determined for the new element.

This is caused either a property with the "Special_Property" attribute set to "Element_Type" was not returned by the INSERT tool or an element was not selected when the action was executed.

Model Administrator Response:
Return the match name of the element type in the INSERT tool and model it as an output parameter referencing an "Element_Type" property.
Parent topic: AWM core (TSCOR) messages


TSCOR0065 INSERT-CHILD operation failed. Selected resource does not have a children-list or -action.

An INSERT-CHILD resource operation could not be executed because no child element can be associated with the selected element. Child elements can only be added for element types that have an associated "Get_Children" action descriptor.

Model Administrator Response:
Verify that the INSERT-CHILD tool descriptor can only be executed on element types which have a "Get_Children" action associated.
Parent topic: AWM core (TSCOR) messages


TSCOR0067 Failed to restore the system reference {0} because the remote system {1} was not found.

A system reference which is associated with a remote system could not be restored, because the associated remote system could not be determined.

User Response:
  • Verify that the associated remote system still exists and has not been renamed in the Remote System View.
  • Delete the system reference and let it be re-created by connecting to the remote system.
Parent topic: AWM core (TSCOR) messages


TSCOR0068 Failed to load the application.

An exception occurred when loading an application from the local copy. The local copy of the application is probably corrupted.

User Response:
Open the application file from the internal project folder with the model editor and validate it. If it is corrupted, remove it from the internal project folder. Then the application model will be loaded from the remote system again. If necessary, contact the model administrator.
Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0069 Invalid extension for extension point {0}

The zOS functionality is integrated by the Eclipse extension point de.soforte.taurus.zconnector. An exception occurred when searching for an extension for this Eclipse extension point.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0070 No ZConnector Extension was found.

The zOS functionality is integrated by the Eclipse extension point de.soforte.taurus.zconnector. No plug-in which extends this extension point could be found in the workbench.

Model Administrator Response:
If the extension point de.soforte.taurus.zconnector is extended by a customer's own extension, verify that the extension point name is spelled correctly in the plugin.xml. Otherwise contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0071 Cannot write on file descriptor of type InputStream.

The setContents method was called with a parameter of type input stream. It is not possible to write on an input stream.

Model Administrator Response:
Verify your tool output parameters of type file descriptor. The type of a file descriptor that is a tool output parameter may not be of type "InputStream".
Parent topic: AWM core (TSCOR) messages


TSCOR0072 The file {0} does not exist.

The file specified by the given path could not be found.

Model Administrator Response:
If the file path originates from a modeled file descriptor, verify that the value under the attribute "Name Physical" is correct. If the file path is a tool result, verify that the tool returns the correct file path.
Parent topic: AWM core (TSCOR) messages


TSCOR0073 {0} is not a valid format for a master configuration parser.{1}

The function to parse a master configuration file is integrated by an Eclipse extension point. The parser was initialized with an invalid file format. Supported file formats are XML or flat file.

Model Administrator Response:
If the master configuration parser is implemented by a customer's own plug-in, verify that the parser is initialized by one of the valid file formats. Otherwise contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0074 A newer workflow model version is available. {0} The application will now be updated.

The model administrator has delivered a newer model version of the application than the version which is loaded locally in the user's workspace. This is a message informing the user that the newer version of the model is loaded in the workspace.

User Response:
This is an informational message; no user action necessary.
Parent topic: AWM core (TSCOR) messages


TSCOR0076 Pre-init failed.

An internal plug-in initialization error occurred.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0077 System name missing.

The creation of a system reference failed because no name for the system was given.

User Response:
Verify that a name was specified under the field "Connection name" in the New Connection dialog.
Parent topic: AWM core (TSCOR) messages


TSCOR0078 ISystemImage missing.

An internal exception occurred because no instance of the ISystemImage type was passed to the method.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0079 The resource with the ID {0} could not be found.

The persistent cache in the user's workspace seems to be inconsistent. There is a reference in one of the cache files to a resource which has not been reloaded from the element's cache file.

User Response:
Use the "Clear cache..." dialog to re-initialize the persistent cache in the Eclipse workspace.
Parent topic: AWM core (TSCOR) messages


TSCOR0080 Failed to create an ID for element type {0} . The key property {1} is missing.

The creation of an internal AWM element failed because at least one of the configured key properties of the element's element type could not be determined.

Model Administrator Response:
  • Verify that the corresponding file descriptor is modeled correctly. The file descriptor must contain all key properties of the returned element type as a minimum.
  • Verify that the corresponding tool correctly returns values for all modeled key properties.
Parent topic: AWM core (TSCOR) messages


TSCOR0081 Missing property value ( {0} ) for resource operation.

The creation of an internal AWM element ID failed because no property value was provided for at least one of the configured key properties of the element's element type.

Model Administrator Response:
  • Verify that the corresponding file descriptor is modeled correctly. The file descriptor must contain all key properties of the returned element type as a minimum.
  • Verify that the corresponding tool correctly returns values for all modeled key properties.
Parent topic: AWM core (TSCOR) messages


TSCOR0084 No valid extension found for the local syntax check extension point.

The integrated "Local Syntax Check" tool is not supported by the product variant.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0085 No valid extension found for the property group manager extension point

This is an internal program exception. The "Property Group Manager" interface did not find a valid implementation.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0087 No valid extension found for the error feedback parser extension point

This is an internal program exception. The "Error Feedback" interface did not find a valid implementation.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0089 An I/O error occurred while reading a file input stream.

An exception occurred during the attempt to read and parse a tool response. Possible reasons are:

  • Network problems.
  • Invalid API usage by third party plug-ins.
  • An internal program exception.
User Response:
Check your network connection.
Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0090 An error occurred while creating/opening the Eclipse project {0} .

The internal project could not be created/opened because the project/workspace is damaged.

User Response:
If the project is already created, refresh it. If this does not solve the problem, close your workbench and try again or clear your workspace.
Parent topic: AWM core (TSCOR) messages


TSCOR0091 Failed to create the internal systems folder in the workspace.

The system folder could not be created in the internal project because the project/workspace is damaged.

User Response:
If the project is already created, refresh it. If this does not solve the problem, close your workbench and try again or clear your workspace.
Parent topic: AWM core (TSCOR) messages


TSCOR0092 Failed to create the internal project folder in the workspace.

The application folder could not be created in the internal project because the project/workspace is damaged.

User Response:
If the project is already created, refresh it. If this does not solve the problem, close your workbench and try again or clear your workspace.
Parent topic: AWM core (TSCOR) messages


TSCOR0093 Error when parsing input for table. Value for property {0} not found.

There is a file input parameter declared as input for a dialog table. At least one line of the file content does not deliver a value for every property associated with the file descriptor.

Model Administrator Response:
Verify the output file of the tool delivering the content for the dialog table. Ensure that the tool delivers at least as many values as properties are configured for the file descriptor.
Parent topic: AWM core (TSCOR) messages


TSCOR0094 File {0} does not exist.

The local file with the given path could not be found on the user's workspace.

Model Administrator Response:
  • If the file's path was derived from a file descriptor in the model, verify that the value in the attribute "Name_Physical" is correct.
  • If the file path is returned by a modeled tool, verify that the tool returns the correct path name.
Parent topic: AWM core (TSCOR) messages


TSCOR0095 The file {0} does not exist.

No file was found based on a File Descriptor with the attribute "Type" set to "Workspace_File". Typical reasons are:

  • The file is not located in the workspace ("Type" attribute is incorrect).
  • The "Name_Physical" attribute value was not entered correctly.
  • The file path is returned incorrectly by another tool.
  • The file path is correct but the file simply does not exist.
Model Administrator Response:
Correct any errors that might cause the problem.
Parent topic: AWM core (TSCOR) messages


TSCOR0096 The master configuration file was not found. It must either be located in: {0}{1} .xml or {2} .txt or a master configuration provider must be implemented (Eclipse Extension Point).

This is an internal program exception that can be caused by an attempt to read a local master configuration file which cannot be located.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0097 Invalid argument. Element type must not be null.

The element type of an element could not be resolved by filling the element list or by performing a resource processing "tool defined " (insert, update).

Model Administrator Response:
  • Verify that the element types of the element list are configured in the properties of the file descriptor that creates the element list.
  • Verify that the tool descriptors ('TOOL_DEFINED' Resource Processing) that insert/update elements with new element types have an element type output parameter (Property with element type as special parameter).
Parent topic: AWM core (TSCOR) messages


TSCOR0099 Wrong parameters for integrated tool FileUploader. Two file input parameters were expected.

The integrated tool "FileUploader" was not modeled properly. It requires two file input parameters.

Model Administrator Response:
Verify that two file input parameters are modeled for the "FileUploader" tool descriptor. The first one will be used as the source file while the second one will be the target for the transfer operation.
Parent topic: AWM core (TSCOR) messages


TSCOR0100 Failed to create the temp file. Input parameters missing.

The integrated tool "LocalTempFileCreator" was not properly modeled (input parameters missing).

Model Administrator Response:
Correct the modeling errors concerning the tool descriptor for the "LocalTempFileCreator" integrated tool. Valid parameter options are documented in the Administration Guide.
Parent topic: AWM core (TSCOR) messages


TSCOR0102 Bad extension for extension point {0} .

The functionality to provide a system reference is integrated by an Eclipse extension point. An exception occurred when determining the Java class which extends this extension point.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0104 Cached elements (et_elements.xml) could not be recovered.

Failed to load the cached elements in the element XML file. Maybe the internal application folder is asynchronous or does not exist or the element XML file is damaged.

User Response:
  • Refresh the internal application folder.
  • Clear the element list and element caches.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0105 Elements could not be cached. Failed to save et_elements.xml.

Failed to save the elements in the element XML file. Maybe the internal application folder is asynchronous or does not exist or the element XML file is damaged.

User Response:
  • Refresh the internal application folder.
  • Clear the element list and element caches.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0107 Failed to save the element list into cache.

The element list could not be saved in the elementlist XML file. Maybe the internal application folder is asynchronous or does not exist or the element list XML file is damaged.

User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and restart the client.
Parent topic: AWM core (TSCOR) messages


TSCOR0108 The local Workflow Manager application folder could not be located.

The internal application folder does not exist in the workspace. Maybe the internal project folder is asynchronous or damaged.

User Response:
  • Refresh the internal project folder.
  • Restart the workbench.
  • Delete the internal project if it exists and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0109 Failed to store the Element list in file li_ {0} .xml.

An element list could not be saved in its corresponding XML file. Maybe the internal application folder is asynchronous or does not exist or the element list XML file is damaged.

User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0110 An element list could not be restored: li_ {0} .xml.

An element list could not be loaded from its corresponding XML file. Maybe the internal application folder is asynchronous or does not exist or the element list XML file is damaged.

User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0111 Cached element lists (lm_elementlists.xml) could not be recovered.

An element list dependency could not be loaded from the element list XML file. Maybe the internal application folder is asynchronous or does not exist or the element list XML file is damaged.

User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0112 An error occurred when trying to save the file lm_elementlists.xml.

An element list dependency could not be saved in the element list XML file. Maybe the internal application folder is asynchronous or does not exist or the element list xml file is damaged.

User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0113 File lm_elementlists.xml could not be deleted.

The element list file could not be deleted. This can have the following cause:

  • The internal application folder is asynchronous, non-existent or damaged.
  • The element list XML file does not exist or is damaged.
User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0114 Failed to delete a cached element list (li_ {0} .xml).

An element list file could not be deleted. This can have the following cause:

  • The internal application folder is asynchronous, non-existent or damaged.
  • The element list XML file does not exist or is damaged.
User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0115 Failed to delete unreferenced Elementlists.

Some element list files for which no references exist in the element list XML file could not be deleted. This can have the following cause:

  • The internal application folder is asynchronous, non-existent or damaged.
  • The element list XML file does not exist or is damaged.
User Response:
  • Refresh the internal application folder.
  • Clear all the element list cache.
  • Delete the internal application folder and load the application again.
Parent topic: AWM core (TSCOR) messages


TSCOR0116 A thread was interrupted while initializing the element lists.

This is an internal program exception that can occur while a cached element list is loaded.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0117 Invalid argument. Element type must not be null.

The element type is needed to create an element list entry. It can fail for the following reasons:

  • The output file parameter configured by the tool that creates the element list does not return the value of the element type property, or the element type property is not configured as an output file parameter.
  • A tool defined resource processing that creates/updates elements does not return the value of the configured element type.
Model Administrator Response:
  • Verify that the output file parameter configured by the tool that creates the element list is configured correctly and returns the element type for each entry.
  • Verify that tool defined resource processing that creates/updates elements returns the value of the configured element type.
Parent topic: AWM core (TSCOR) messages


TSCOR0118 Failed to interpret the selection count {0} .

The "Selection_Count" attribute of a modeled enabled condition does not contain a valid value.

Model Administrator Response:
Change the "Selection_Count" attribute value to be either numeric or "*" which means that the action is enabled no matter how many elements are selected.
Parent topic: AWM core (TSCOR) messages


TSCOR0119 {0} is not a valid file name.

During the parsing of the Error Feedback XML file, it was noticed that some error file references do not have the structure of a z/OS partitioned data set name.

Model Administrator Response:
Verify that error file references contained in the Error Feedback XML file have the structure of a z/OS partitioned data set name.
Parent topic: AWM core (TSCOR) messages


TSCOR0121 Failed to load error entries from cache (er_errorFeedback.xml).

The error entries cannot be loaded from cache (er_errorFeedback.xml). Maybe the internal application folder is asynchronous, non-existent or the er_errorFeedback.xml is damaged.

User Response:
  • Refresh the internal application folder.
  • Manually delete the file er_errorFeedback.xml while the application is not loaded.
  • Delete the internal application folder and restart the client.
Parent topic: AWM core (TSCOR) messages


TSCOR0122 Failed to store error entries into cache (er_errorFeedback.xml).

The error entries cannot be saved in cache (er_errorFeedback.xml). Maybe the internal application folder is asynchronous, non-existent or the er_errorFeedback.xml is damaged.

User Response:
  • Refresh the internal application folder.
  • Manually delete the file er_errorFeedback.xml while the application is not loaded.
  • Delete the internal application folder and restart the client.
Parent topic: AWM core (TSCOR) messages


TSCOR0123 The file descriptor with the ID {0} could not be found among previous output parameters.

A file input parameter was modeled with the attribute "Parameter_From" set to "Previous_Tool" but the file descriptor was never returned as an output parameter by a previous executed tool in this action.

Model Administrator Response:
Either set the "Parameter_From" value of the file input parameter to "Context" or make sure that the file descriptor is returned as an output parameter by a previous tool in the action sequence. Setting the "Parameter_From" attribute to "Context" requires the file descriptor to have a valid "Name_Physical" attribute value.
Parent topic: AWM core (TSCOR) messages


TSCOR0124 The property {0} was not found within the execution context.

A tool descriptor was modeled with an input parameter with the "Parameter_From" attribute set to "Context", but the referenced property is not available in the execution context.

Model Administrator Response:
Either change the model so that the property will be in the execution context or set the "Parameter_From" attribute of the input parameter to "Context". To see if a property is in the execution context, open the Properties View while an element is selected.
Parent topic: AWM core (TSCOR) messages


TSCOR0125 The property {0} was not found among previous output parameters.

An input parameter was modeled with the attribute "Parameter_From" set to "Previous_Tool", but the property was never returned as an output parameter by a previously executed tool in this action.

Model Administrator Response:
Either set the "Parameter_From" value of the input parameter to "Context" or make sure that the property is returned as an output parameter by a previous tool in the action sequence.
Parent topic: AWM core (TSCOR) messages


TSCOR0126 An error occurred while loading a filter.

An exception occurred when loading the file with the persistently cached filter data from the internal project folder in the workspace of the user.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the Administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0127 An error occurred when trying to create a SAX parser instance

An internal XML parser problem occurred when loading the filter data from the persistent cache in the internal project folder of the user's workspace.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0128 An error occurred while parsing ft_filters.xml.

An internal XML parser problem occurred when loading the filter data from the persistent cache in the internal project folder of the user's workspace.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0129 An error occurred when trying to save the file filters.xml.

Each time a filter is created, deleted or changed, the file which contains the filter data is written to the persistent cache in the internal project folder of the user's workspace. This write action failed.

Model Administrator Response:
  • Verify that the user has the authority to write to the internal project folder.
  • Check the error log for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0130 Exception occurred when trying to delete ft_filters.xml.

The deletion of the cached filter data in the internal project folder failed when requested within the context of the Clear Cache dialog.

Model Administrator Response:
  • Verify that the user has the authority to delete files from the internal project folder.
  • Check the error log for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0131 An error occurred when trying to load the file jt_jobs.xml.

When an application is loaded, the job information of the application is reloaded from the persistent cache in the internal project folder of the user's workspace. This reload failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the Administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0132 Failed to load opened files.

The local cache for opened editor sessions could not be read. This is either caused by a corrupt cache or the Eclipse workspace being out of synchronization.

Model Administrator Response:
  • Refresh the internal project folder (see Workspace out of sync).
  • Clear the persistent cache (see Clear the persistent cache in the workspace ).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync
Clear the persistent cache in the workspace


TSCOR0133 Failed to load error entries.

The local cache for error feedback entries could not be read. This is either caused by a corrupt cache or the Eclipse workspace being out of synchronization.

Model Administrator Response:
  • Refresh the internal project folder (see Workspace out of sync).
  • Clear the persistent cache (see Clear the persistent cache in the workspace ).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync
Clear the persistent cache in the workspace


TSCOR0134 Failed to load Jobs.

The local cache for executed jobs could not be read. This is either caused by a corrupt cache or the Eclipse workspace being out of synchronization.

Model Administrator Response:
  • Refresh the internal project folder (see Workspace out of sync).
  • Clear the persistent cache (see Clear the persistent cache in the workspace ).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync
Clear the persistent cache in the workspace


TSCOR0136 Failed to remove cached elements.

The persistent cache for modeled elements could not be deleted. This is probably caused by the Eclipse workspace being out of synchronization.

Model Administrator Response:
  • Refresh the internal project folder (see Workspace out of sync).
  • Clear the cache manually (see Clear the persistent cache in the workspace ).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync
Clear the persistent cache in the workspace


TSCOR0137 Failed to remove cached filters.

The persistent cache for created filters could not be deleted. This is probably caused by the Eclipse workspace being out of synchronization.

Model Administrator Response:
  • Refresh the internal project folder (see Workspace out of sync).
  • Clear the cache manually (see Clear the persistent cache in the workspace ).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync
Clear the persistent cache in the workspace


TSCOR0138 Failed to {0} .

The cache could not be saved persistently in the workspace. This is most probably caused by the Eclipse workspace being out of synchronization with the file system.

Model Administrator Response:
  • Refresh the internal project folder and restart the client (see Workspace out of sync).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync


TSCOR0139 Backup folder could not be created.

The first step of the application update is to back up the files which contain the persistently cached data in the workspace. In this step the creation of the backup folder failed. This means the complete application update action failed.

Model Administrator Response:
  • Verify that the user has the authority to create a folder in the internal project folder.
  • Refresh the internal project folder (see Workspace out of sync).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync


TSCOR0140 Failed to copy the backup folder. {0} .

The first step of the application update is to back up the files which contain the persistently cached data in the workspace. In this step the copy of the files to the backup folder failed. This means the complete application update action failed.

Model Administrator Response:
  • Verify that the user has the authority to write to the backup folder in the internal project folder.
  • Check the error log for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0141 Converting an outdated application model failed.

This is an internal program exception. An attempt to convert a possibly outdated model failed. A model will be treated as outdated if syntax errors were detected while loading it.

Model Administrator Response:
Please contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0142 An error occurred while trying to read the configuration file: {0} .

This error occurs if a model could not be read. It can be for the following reasons:

  • Network problems.
  • Model does not exist under the configured path from the master configuration.
  • User is not authorized to read the model file.
User Response:
Check your network connection.
Model Administrator Response:
  • Make sure that the Properties View is opened and select the application in the Tree View. The Properties View now shows configured attributes of the application (defined in the master configuration). Verify that the "Model Location" property has a correct value.
  • Verify that the user has read access to the model file.
Parent topic: AWM core (TSCOR) messages


TSCOR0143 The configuration file {0} could not be found.

This error occurs if a model file could not be found locally (or in the local network).

User Response:
Check your network connection.
Model Administrator Response:
  • Make sure that the Properties View is opened and select the application in the Tree View. The Properties View now shows configured attributes of the application (defined in the master configuration). Verify that the "Model Location" property has a correct value.
  • If the model file is located on the mainframe, use the prefix "mvs:" for the model path definition (attribute "conf:") in the master configuration, for example, "mvs:hlq.models(mymodel)".
  • Verify that the user has read access to the model file.
Parent topic: AWM core (TSCOR) messages


TSCOR0144 System could not create configuration dataset {0} .

This is an internal program exception that occurs when a downloaded model could not be saved in the workspace.

Model Administrator Response:
Refresh your internal project folder (see Workspace out of sync).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync


TSCOR0145 An exception occurred while trying to close the configuration file {0} .

This is an internal program exception that occurs when a downloaded model could not be saved in the workspace.

Model Administrator Response:
Refresh your internal project folder (see Workspace out of sync).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync


TSCOR0146 The given input stream is null. Possible reason: The model configuration file from the master configuration does not exist.

This is an internal program exception. It can occur if a model could not be loaded correctly.

Model Administrator Response:
  • Make sure that the Properties View is opened and select the application in the Tree View. The Properties View now shows configured attributes of the application (defined in the master configuration). Verify that the "Model Location" property has a correct value.
  • Verify that the user has read access to the model file.
  • Contact Customer Support.
Parent topic: AWM core (TSCOR) messages


TSCOR0147 A system reference for connection {0} already exists!

This is an internal program exception. It is caused by an attempt to create a system reference that conflicts with an existing one.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0148 Failed to add the system reference because no ISystemImage (remote system) given.

This is an internal program exception. It is caused when a system reference is registered without a system reference (ISystemImage interface).

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0149 Failed to load system references.

This error occurs if a cached system reference cannot be recovered after a client restart. Possible reasons are:

  • A remote system connection associated with a system reference cannot be found. This is caused if the remote system connection was renamed or deleted.
  • The cache is corrupt.
User Response:
  • Execute the "Add System" function in the Tree View to recreate the system reference.
Parent topic: AWM core (TSCOR) messages


TSCOR0150 An error occurred when trying to create a SAX parser instance

This is an internal program exception. It is caused by a failed attempt to instantiate a Java XML parser.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0151 Failed to recover cached systems (st_systems.xml).

This exception is caused by a corrupt system reference cache file (bad XML syntax). A detailed error message can usually be found in the error details.

Model Administrator Response:
Open the cache file in a text- or XML editor to determine and correct the error. The file is named "st_systems.xml" and is located in the internal project. If necessary, contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0152 An error occurred when trying to save the file st_systems.xml.

This is an internal program exception that occurs when a system reference cannot be saved into the cache. This can be caused when the Eclipse workspace is out of synchronization.

User Response:
Refresh the internal project folder (see Workspace out of sync).
Parent topic: AWM core (TSCOR) messages
Related information
Workspace out of sync


TSCOR0153 Model update check failed. Either the master configuration could not be read or the update itself failed.

This is a top-level exception which occurs if updating the model or checking for a new model version fails. It can fail for several reasons, including:
  • The master configuration, containing information about the newest model version, could not be read.
  • The user cancelled an "Enter Password" dialog which was required for reading the master configuration.
  • Loading a new model version failed. A more detailed message can usually be found in the error details. Note that the update-check will only happen once per application and Eclipse session.
User Response:
  • Fix any problems which might prevent the master configuration from being read.
  • The application can be updated manually by refreshing the corresponding system reference in the Tree View and selecting the "Update Application" action in the context menu of the application. If no "Update Application" action is displayed, then there is no newer version available.
Model Administrator Response:
Check the error details for the cause of this message and resolve the problem.
Parent topic: AWM core (TSCOR) messages


TSCOR0154 Failed to check for model update. The application does not seem to be loaded.

This is an internal program exception. An attempt to update an application was made but the application does not seem to be loaded correctly.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0155 The model update was performed but the version numbers still do not match: {0} Master Configuration version number: {1}{0} Model version number: {3}

This problem is caused by an invalid configuration of model version numbers. The version number of an application defined in a master configuration is not equal to the version number of the model it refers to. The version number of a model must be set under "Application Options" in the "Version" attribute.

Model Administrator Response:
Correct the version numbers of the application in the master configuration and the model.
Parent topic: AWM core (TSCOR) messages


TSCOR0156 Missing location keyword in model path: {0} . {1} .

A model location path ("conf" attribute in master configuration) did not contain a location keyword. The location keyword is used to determine on which platform a model is stored, for example, "local:", and "mvs:".

Model Administrator Response:
Add a location keyword in front of the model location. Valid keywords are documented in the Administration Guide. Example: "Conf: local:C:\myModel.xml"
Parent topic: AWM core (TSCOR) messages


TSCOR0157 Wrong location keyword in model path: {0} . {1}

The location keyword of a configured model path in a master configuration is invalid.

Model Administrator Response:
Correct the location keyword in the master configuration. Valid keywords are documented in the Administration Guide.
Parent topic: AWM core (TSCOR) messages


TSCOR0158 A file input parameter must be defined for the integrated tool LocalSyntaxCheck (the program source that should be checked).

A file input parameter for a "LocalSyntaxCheck" integrated tool is missing.

Model Administrator Response:
Ensure that a file input parameter is modeled for the integrated tool "LocalSyntaxCheck".
Parent topic: AWM core (TSCOR) messages


TSCOR0159 A file output parameter (type = Workspace File) must be defined for the integrated tool file locator.

The integrated tool "LocalFileLocator" requires a file output parameter which is missing in the tool descriptor definition.

Model Administrator Response:
Add a file output parameter to the "LocalFileLocator" tool descriptor which references a file descriptor of the type "Workspace_File".
Parent topic: AWM core (TSCOR) messages


TSCOR0160 A file input parameter must be defined for the integrated tool EDIT_CLEANUP.

The integrated tool "Edit_Cleanup" was not properly modeled. It requires a file input parameter which points to the file that should be deleted.

Model Administrator Response:
Add a file input parameter to the "Edit_Cleanup" tool descriptor.
Parent topic: AWM core (TSCOR) messages


TSCOR0161 A file input parameter (describing the error XML input) must be defined for the integrated tool ErrorFeedback.

The integrated tool "ErrorFeedback" was not properly modeled. It requires a file input parameter.

Model Administrator Response:
Add a file input parameter to the "ErrorFeedback" integrated tool. The referenced file descriptor must point to a file which contains compiling errors in XML format.
Parent topic: AWM core (TSCOR) messages


TSCOR0163 No input parameters configured for the integrated tool Local File Creator.

The integrated tool "LocalFileCreator" was not modeled properly (parameters are missing).

Model Administrator Response:
Correct the modeling errors concerning the tool descriptor for the "LocalFileCreator" integrated tool. Valid parameter options are documented in the Administration Guide.
Parent topic: AWM core (TSCOR) messages


TSCOR0164 LocalFileCreator: Failed to create a local file because no element type could be determined from the given parameters.

The integrated tool "LocalFileCreator" was not modeled properly. No required element type for the file creation could be determined based on the modeled parameters.

Model Administrator Response:
Correct the modeling errors concerning the tool descriptor for the "LocalFileCreator" integrated tool. Valid parameter options are documented in the Administration Guide.
Parent topic: AWM core (TSCOR) messages


TSCOR0165 Physical name of file descriptor {0} missing.

A file descriptor, to which content should be written, has no value declared in the attribute "Name Physical".

Model Administrator Response:
Add a valid value to the attribute "Name Physical" of the given file descriptor in the model file.
Parent topic: AWM core (TSCOR) messages


TSCOR0166 Could not find a property with the ID {0} . This is normal when the model has been changed and an old cache is loaded.

Self-explanatory.

User Response:
Clear the persistent cache with the Clear Cache... dialog and refresh the whole element list in the table view.
Parent topic: AWM core (TSCOR) messages


TSCOR0167 No ZConnector Extension was found for a remote system with the name {0} .

Cached system references could not be loaded. As a result no application was loaded. Possible reasons are:

  • Corrupt cache files.
  • Asynchronous Eclipse workspace.
  • Internal problems (e.g. XML parser exceptions).
User Response:
Recreate the system references manually in the Tree View. Refresh your Eclipse workspace if necessary.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0168 Illegal character # by applications name.

The application name must not contain the character '#'.

Model Administrator Response:
Change the application name in the master configuration file (see description).
Parent topic: AWM core (TSCOR) messages


TSCOR0170 Missing input parameter target ID of tool {0} .

The file target ID of a input parameter in tool {0} is not configured.

Model Administrator Response:
Verify your model configuration (see description).
Parent topic: AWM core (TSCOR) messages


TSCOR0171 The action descriptor {0} contains a tool descriptor relationship without a target ID.

Some tool descriptors defined in the action {0} do not have a target ID.

Model Administrator Response:
Check the model configuration (see description).
Parent topic: AWM core (TSCOR) messages


TSCOR0172 No element type was found for the match name {0} which is part of the compounded match name {1} .

A compounded match name could not be completely resolved.

Model Administrator Response:
  • Verify that the correct value of the element list was defined as "Element Type".
  • Correct the match name returned by the tool or the "Matchname" attribute of the corresponding element type.
Parent topic: AWM core (TSCOR) messages


TSCOR0173 No extension found for job utility.

No plug-in extension was found for the job utilities in the user's AWM installation.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0174 Validate message parsing error: The validate message cannot be empty.

Self-explanatory.

Model Administrator Response:
Make sure that the validate tool does not return empty validate messages. If no error(s), warning(s) and/or information message(s) occurred, don't return the key "VAL_MSG". See Validate Action for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0175 Validate message parsing error: Key {0} must be closed.

The keywords of validation messages have to be returned in parentheses.

Model Administrator Response:
Self-explanatory. See Validate Action for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0176 Validate message parsing error: MSGTEXT is mandatory.

The keyword MSGTEXT is mandatory for validation messages.

Model Administrator Response:
Self-explanatory. See Validate Action for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0177 UPDATE resource operation failed. No reference element was found for updating.

The UPDATE resource operation failed because no element was found for updating.

Model Administrator Response:
Either make sure to return a complete element ID (including the matchname) with the resource operation or do not enable the tool in actions which are not element actions. Note that properties returned by resource operation must be modeled as output parameters with the type "ELEMENT".
Parent topic: AWM core (TSCOR) messages


TSCOR0178 Parameter from USER_INPUT are not allowed for mass processing tools. Please change the parameter from attribute of parameter # {0} either to Context or Previous Tool.

A tool descriptor was modeled within a mass processing action descriptor which contains an input parameter with the attribute "Parameter From = User_Input". This is a non-supported combination.

Model Administrator Response:
Change the "Parameter From" attribute of the input parameter either to "Context" or "Previous Tool".
Parent topic: AWM core (TSCOR) messages


TSCOR0179 Different Parameter from attributes are not allowed for mass processing tools. All mass processing parameters must either come from the context (e.g. selected elements) or previous tool resources (e.g. selected table rows from an input dialog).

A tool descriptor which was called within a mass processing action contains mass processing input parameters with different "Parameter From" attribute values. This is invalid, because the number of selected resources can differ from the number of resources created during the action.

Model Administrator Response:
Change the "Parameter From" attribute values of all mass processing input parameters of the tool descriptor either to "Context" or "Previous Tool".
Parent topic: AWM core (TSCOR) messages


TSCOR0180 Failed to find the workspace file for file descriptor {0} because the physical name is null or empty.

A workspace file could not be found because the file descriptor did not have a physical name at runtime.

Model Administrator Response:
Either specify a "Name Physical" attribute in the file descriptor or, if the file name is returned by a tool, set the "Parameter From" attribute of the input parameter using the file descriptor to "Previous Tool".
Parent topic: AWM core (TSCOR) messages


TSCOR0181 The file {0} already exists.

A file could not be created by the integrated tool "Local File Creator" because it already existed. This error only occurs if no user interface is available.

User Response:
Delete the file manually and try again.
Parent topic: AWM core (TSCOR) messages


TSCOR0182 The execution of an action failed

An error occurred during the execution of an action descriptor. This is an internal exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0183 An error occurred while executing the action {0} .

This is a very common top-level exception. It usually occurs if a tool within the action returns a high return code or encounters a problem. A tool which returned a high return code most probably also returned a reason message. The reason message should be visible under "Reason" in the error dialog or can be found in the error details.

User Response:
Contact the model administrator if the reason given by the executed tool is not clear or if there is no reason message at all.
Parent topic: AWM core (TSCOR) messages


TSCOR0184 The cached information for {0} seems to be incompatible with the loaded model.

The cached information to load seems to be incompatible with the load model and there is no UI to ask to reset the corresponding cache files.

User Response:
Delete the corresponding cached file and try the action again.
Parent topic: AWM core (TSCOR) messages


TSCOR0185 Failed to aquire a file descriptor from the given input.

A file descriptor could not be acquired from the given input. This can be caused by a modeled input parameter which has the type "File" but no file descriptor associated under the "Target ID File" attribute. It can also be caused by an internal issue (context parameter is null).

Model Administrator Response:
Verify that the corresponding input parameter is correctly modeled.
Parent topic: AWM core (TSCOR) messages


TSCOR0186 The integrated tool ChildrenRefresher can only refresh files of the type Workspace_File, but a {0} file input parameter was modelled.

A wrong file input parameter type was modeled for the integrated tool "Children Refresher". Only file input parameters of the type "Workspace_File" are permitted. See Children Refresher in the Workflow Manager Configuration Guide for other valid tool configurations.

Model Administrator Response:
Change the input file descriptor to be a "Workspace File" or use a different tool configuration (see Children Refresher in the Workflow Manager Configuration Guide).
Parent topic: AWM core (TSCOR) messages


TSCOR0187 Failed to create an element ID. Either the input parameters do not contain an element type or all key properties.

The integrated tool "ChildrenRefresher" failed to refresh the children of an element because no element ID could be created from the modeled input parameters.

Model Administrator Response:
  • Verify that the integrated tool ChildrenRefresher contains modeled input parameters which include an element type property and ID properties of the element that should be refreshed.
  • Verify that the integrated tool ChildrenRefresher was called with the correct parameter values.
Parent topic: AWM core (TSCOR) messages


TSCOR0188 Unable to get property value for parameter # {0} . No target ID property found.

A "Target ID Parm" attribute was expected from a modeled input parameter but is missing.

Model Administrator Response:
  • Add a value for the "Target ID Parm" attribute of the specific input parameter.
  • Check if the "Type" attribute of the input parameter is correct.
Parent topic: AWM core (TSCOR) messages


TSCOR0189 {0} resource operation failed because no properties for the new element were specified.

A INSERT or COPY resource operation was executed without any output properties.

Model Administrator Response:
Verify that the tool descriptor has modeled output parameters (Type = String if the "Resource Processing" attribute was set to INSERT and Type = Element if the resource processing type is TOOL-DEFINED).

Verify that the called tool returns output values for the resource operation.

If the tool was not intended to insert a new element, change the "Resource Processing" attribute of the tool descriptor to READ.

Parent topic: AWM core (TSCOR) messages


TSCOR0190 {0} resource operation failed because the element ID for the new element could not be determined from the returned properties.

A INSERT or COPY resource operation could not be executed because the provided properties did not contain a valid match name and element ID combination.

Model Administrator Response:
Verify that the tool returns a valid match name (optional) + element ID combination. If no match name is returned, the element type of the selected element will be used. The returned properties must contain all properties of the element types ID definition.

Verify that the called tool returns correct output values for the resource operation.

If the tool was not intended to insert a new element, change the "Resource Processing" attribute of the tool descriptor to READ.

Parent topic: AWM core (TSCOR) messages


TSCOR0191 Target ID missing for input parameter # {0} .

An input parameter of a modeled tool descriptor does not have a target ID.

Model Administrator Response:
Set a target ID ("File" or "Parm") for the corresponding input parameter or remove the parameter if it is not required.
Parent topic: AWM core (TSCOR) messages


TSCOR0192 The given error feedback XML file could not be parsed because the PACKAGE element was not found.

The given error feedback XML file for the AWM tool "Process Error Feedback" was invalid because no "PACKAGE" element was found.

Model Administrator Response:
Verify that the file input parameter of the corresponding tool descriptor points to the correct XML file.

Check why the XML file seems to be invalid, by debugging the tool which creates the XML file.

Parent topic: AWM core (TSCOR) messages


TSCOR0193 An error occurred while parsing the error feedback file.

A general error occurred when the AWM tool "Process Error Feedback" tried to parse the error feedback XML file. This can have several reasons:

  • General connection problem.
  • The given file is not a valid XML file.
  • The Java XML parser encountered an internal problem.
User Response:
Check your connection to the remote system (if available). Note that the error feedback XML file is not necessarily located on a remote system.
Model Administrator Response:
Verify that the file input parameter of the corresponding tool descriptor points to the correct XML file.
Server Administrator Response:
Determine why the XML file seems to be invalid by debugging the tool which should create the XML file.
Parent topic: AWM core (TSCOR) messages


TSCOR0194 A file input parameter (XML) which contains linked properties must be configured by the tool {0} .

An AWM tool "Set Linked Properties" was not properly modeled. The tool requires a file input parameter (XML).

Model Administrator Response:
Verify that at least one file input parameter is modeled by the corresponding tool.
Parent topic: AWM core (TSCOR) messages


TSCOR0195 Failed to set the value for linked property \ {0} \.

Failed to set a linked property value, because the property provider of the linked property could not be found. This can be caused by missing function packages or renamed linked property IDs in function packages.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0196 Failed to load cached AWM system, because a system provider with the ID \ {0} \ was not found.

A cached AWM system could not be recreated because the plug-in which originally created it is not installed or has changed.

Model Administrator Response:
Verify that the required plug-in (identifiable via the provider ID) is correctly installed. Contact the plug-in contributor if necessary.
Parent topic: AWM core (TSCOR) messages


TSCOR0197 Failed to load cached AWM system, because an error occurred while loading the cached AWM System with the Name \ {0} \.

At least one error occurred while loading cached AWM systems. These systems are not loaded.

User Response:
Clear the AWM systems cache.
Parent topic: AWM core (TSCOR) messages


TSCOR0198 An exception occurred while calling the method toolExecuted() of property provider \ {0} \.

An internal exception occurred while calling the method IPropertyProvider#toolExecuted() for one of the registered providers.

Model Administrator Response:
Contact SupportLine if the property provider name starts with the ID "com.microfocus".

If the property provider was developed internally by using the AWM API, contact the plug-in provider.

Parent topic: AWM core (TSCOR) messages


TSCOR0199 Failed to parse master configuration: {0}{1}

The master configuration could not be parsed since it appears to be invalid.

Model Administrator Response:
Check the error log and trace for a more specific error message.

Verify whether the master configuration (printed below the error message) is valid.

If the master configuration appears to be invalid, and it was returned by a z/OS procedure, contact the server administrator.

Parent topic: AWM core (TSCOR) messages


TSCOR0200 The AWM application \ {0} \ was parsed before an AWM system name in a master configuration file.

An AWM application could not be created from a master configuration, since its tag appeared before the mandatory "system" tag.

Model Administrator Response:
Verify that the first tag of the master configuration file is "system".

If the master configuration is located on the mainframe, contact your server administrator.

Parent topic: AWM core (TSCOR) messages


TSCOR0201 No target ID of the property with the sequence number {0} is set within the element type {1} .

A hasProperty relationship of an element type does not contain a target ID.

Model Administrator Response:
Validate the AWM model. Set the missing property in the hasProperty relationship of the element type as target ID.
Parent topic: AWM core (TSCOR) messages


TSCOR0202 Failed to load cached AWM system \ {0} \ or load one if its previously loaded applications.

A cached AWM system could not be recreated, or a previously loaded application could not be loaded again after restarting AWM.

Model Administrator Response:
See the error log for more information.
Parent topic: AWM core (TSCOR) messages


TSCOR0203 Invalid parameter override of tool \ {0} \ in action descriptor \{1} \. Reference \Parm To Override\ missing.

A "parm to override" reference is missing in the AWM model.

Model Administrator Response:
Add the missing reference to the corresponding parameter override. Use the "Validate" function to determine the corresponding override.
Parent topic: AWM core (TSCOR) messages


TSCOR0204 A default AWM system could not be created, because none of the following attributes has been set: \ {0} \, \{1} \ (one is required).

A mandatory attribute is missing in the default configurations file.

Model Administrator Response:
Add one of the returned attributes to the AWM system of the default configurations file.
Parent topic: AWM core (TSCOR) messages


TSCOR0205 AWM system name cannot be null.

This is an unexpected internal program error.

Model Administrator Response:
Please contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0206 The AWM system \ {0} \ was not returned by parsing the master configuration file and can therefore not be refreshed. Delete the system and add it again, if the system name has changed in the master configuration.

Refreshing an AWM system by reading its master configuration did not work, since the master configuration did not contain the system name. This is usually caused by changes to the master configuration file.

User Response:
Delete the AWM system in the Application Explorer view and add it again.
Model Administrator Response:
Verify if the correct master configuration file was used.
Parent topic: AWM core (TSCOR) messages


TSCOR0207 A deprecated tool type extension could not be resolved.

A deprecated tool type plug-in extension (created with AWM V2.2.2 or earlier) could not be resolved. This will make the corresponding tool type unavailable.

Model Administrator Response:
If the system provider was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the provider name is not known.

Parent topic: AWM core (TSCOR) messages


TSCOR0208 A custom default configurations file path has been set, but the file was not found: \ {0} \.

The default configuration file was not found under the specified path.

Model Administrator Response:
Verify that the specified file path is correct and every user has access to it.
Parent topic: AWM core (TSCOR) messages


TSCOR0209 Failed to instantiate a system provider of contributor \ {0} \.

An AWM system provider extension was invalid.

Model Administrator Response:
Contact SupportLine if the system provider name starts with the ID "com.microfocus".

If the system provider was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the provider name is not known.

Parent topic: AWM core (TSCOR) messages


TSCOR0210 Invalid \ {0} \ extension. \class\ attribute does not point to a {1} implementation. Contributor was \{2} \.

A custom error feedback extension was not valid. This is caused by a non-Micro Focus plug-in.

Model Administrator Response:
If the extension was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the contributor name is not known.

Parent topic: AWM core (TSCOR) messages


TSCOR0211 Invalid remote system connection creator extension {0} .

A "remote system connection creator" extension was invalid. This can be caused by a non-Micro Focus plug-in.

Model Administrator Response:
Contact SupportLine if the contributor name starts with the ID "com.microfocus".

If the extension was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the contributor name is not known.

Parent topic: AWM core (TSCOR) messages


TSCOR0212 Failed to get the property value of linked property \ {0} \.

Failed to get a linked property value, because the property provider of the linked property could not be found. This can be caused by missing function packages or renamed linked property IDs in function packages.

Model Administrator Response:
Contact SupportLine if the linked property ID starts "com.microfocus".

If the linked property was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the linked property ID is from a third party plug-in provider.

Parent topic: AWM core (TSCOR) messages


TSCOR0213 Exception while getting value of linked property \ {0} \ from property provider \{1} \. Resource identifier was \{2} \.

An exception occurred while resolving a linked property value.

Model Administrator Response:
Verify that the resource identifier is correct.

See the error log for more information.

Parent topic: AWM core (TSCOR) messages


TSCOR0214 Model conversion failed.

AWM tried to convert a model, but either failed, or converting the model did not resolve the initial problem.

Model Administrator Response:
Check the error log for the reason the model could not be loaded before the conversion.

Check in the error log whether the conversion itself failed with an exception.

Parent topic: AWM core (TSCOR) messages


TSCOR0215 Error while loading the model {0} . Starting model converter.

An error occurred on the first attempt to load a model. This can have many reasons, including the model being created with an older AWM version. AWM will try to convert the model to new version standards and log another error if this isn't the cause of this error.

Model Administrator Response:
This message can be ignored if an old AWM model was loaded which was successfully converted afterwards.

Check the error log for the initial exception, if model conversion fails.

Parent topic: AWM core (TSCOR) messages


TSCOR0216 At least one problem occurred while loading AWM systems. See error log for more information.

At least one cached AWM system could not be recreated due to an exception.

User Response:
Re-add the missing AWM system via the Application Explorer view.
Model Administrator Response:
Check the error log for the initial cause of the exception.
Parent topic: AWM core (TSCOR) messages


TSCOR0217 Failed to create default AWM systems.

An exception occurred during creation of default AWM systems (based on a default configuration file).

User Response:
Create the default AWM system(s) manually via the Add System(s) command in the Application Explorer view.
Parent topic: AWM core (TSCOR) messages


TSCOR0218 Failed to persist applications for AWM system \ {0} \.

AWM applications of a specific system could not be saved to cache.

Model Administrator Response:
See the error log for information.
Parent topic: AWM core (TSCOR) messages


TSCOR0219 An error occurred while loading cached elements.

An error occurred while AWM tried to restore cached (element type) elements.

Model Administrator Response:
See the error log for the initial error.
Parent topic: AWM core (TSCOR) messages


TSCOR0220 An exception occurred while initializing the function package \ {0} \.

The function package initializer of a function package caused an exception during initialization (method "modelLoaded()").

Model Administrator Response:
Contact SupportLine if the function package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the contributor of the function package is not known.

Parent topic: AWM core (TSCOR) messages


TSCOR0221 Function package \ {0} \ was not properly unloaded.

The function package initializer of a function package caused an exception during application unloading (method "modelUnloading()").

Model Administrator Response:
Contact SupportLine if the function package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the contributor of the function package is not known.

Parent topic: AWM core (TSCOR) messages


TSCOR0222 FileUploader for mass processing: The number of file sources must be the same as file targets.

When mass uploading, the size of file sources must match that of file targets.

Model Administrator Response:
Check the error log for more information. If necessary contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0223 The file descriptor type {0} cannot be opened.

The AWM client supports opening files with the following file descriptor type:
  • MVSSEQ
  • MVSPO_MEMBER
  • USS_FILE
  • WORKSPACE_FILE
  • LOCAL_FILE
Model Administrator Response:
Check the error log for more information. If necessary contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0224 Missing file name for file descriptor {0} .

The AWM tool "Process Error Feedback" needs a file descriptor (that contains errors) as input parameter. This file descriptor does not have a physical name, or the physical name is empty.

Model Administrator Response:
Verify that the file input parameter has a valid physical name.
Parent topic: AWM core (TSCOR) messages


TSCOR0225 An Eclipse resource path was expected as parameter # {0}{1} for the tool \{2} \ but the tool only contains {3} parameters.

Self-explanatory.

Model Administrator Response:
Verify that the tool has been properly modeled.

Check the error log for more information.

Parent topic: AWM core (TSCOR) messages


TSCOR0226 The resource path \ {0} \ cannot be resolved to an Eclipse resource.

Self-explanatory.

Model Administrator Response:
Check the error log for more information. If necessary contact SupportLine.
Parent topic: AWM core (TSCOR) messages


TSCOR0227 Invalid table view secondary id.

The table view to show has an illegal secondary ID. View secondary IDs cannot be empty or contain a colon.

Model Administrator Response:
Verify that all modeled table view IDs are not empty or do not contain a colon( ":").
Parent topic: AWM core (TSCOR) messages


TSCOR0228 Failed to delete an old cached element list: {0} .

An element list file could not be deleted. This can have the following cause:

  • The internal application folder is asynchronous, non-existent or damaged.
  • The element list XML file does not exist or is damaged.
User Response:
Refresh the internal application folder.

Clear all the element list cache.

Delete the internal application folder and load the application again.

Parent topic: AWM core (TSCOR) messages


TSCOR0229 Resource identifier property cannot be the linked property itself: \ {0} \.

A resource identifier property cannot be the linked property itself.

Model Administrator Response:
The linked property cannot be used as an identifier for itself. Use a proper linked property identifier.
Parent topic: AWM core (TSCOR) messages


TSCOR0230 Warnings occurred during the execution of the tool. Maybe some properties have been renamed/deleted. \n\n {0}

Warnings occurred during the execution of the tool. Maybe some properties have been renamed/deleted.

Model Administrator Response:
Validate the model again.
Parent topic: AWM core (TSCOR) messages


TSCOR0231 Duplicate occurrence of property \ {0} \ in file descriptor \{1} \. This is only allowed for the file output parameter of this tool.

A file descriptor property occurred twice in a file input parameter of the tool "Merge Structured Files". This is not valid, as each property must occur only once to create the merged file.

Model Administrator Response:
Make sure that the target file descriptors of the tool's input parameters don't contain multiple references to the same property. Define an additional property or consider removing the value from the target file.
Parent topic: AWM core (TSCOR) messages


TSCOR0232 Line (line 1) of file \{1} \ contains less values than modeled has property relationships ({2} out of {3} ).{4} Line content is: \{5}\.

At least one line of an input file for the tool "Merge Structured Files" contains fewer values than modeled "File Descriptor has Property" relationships.

Model Administrator Response:
Verify that the property delimiters do not appear in the file's values. Change the "Prop Delimiter" of the file descriptor, if necessary.
Verify that the number of modeled file descriptor properties is correct.
Verify that the file has been correctly created/ set up.
Parent topic: AWM core (TSCOR) messages


AWM IDz (TSRDZ) messages

  • TSRDZ0001 The remote resource {0} was not found.
  • TSRDZ0002 An error occurred while trying to open the file {0}
  • TSRDZ0003 Connection failed when trying to reach the remote system job utility.
  • TSRDZ0004 Failed to initialize the IDz Job Utility.
  • TSRDZ0005 The job with the ID {0} could not be read.
  • TSRDZ0006 DD {0} of job {1} could not be read.
  • TSRDZ0007 DDs of the job with the ID {0} could not be determined.
  • TSRDZ0008 The return code of the job with the ID {0} could not be determined.
  • TSRDZ0009 Invalid resource during association of property group.
  • TSRDZ0010 A local property group with name {0} does not exist.
  • TSRDZ0011 The error feedback XML file could not be read during the execution of the integrated tool RefreshDependencies.
  • TSRDZ0012 The folder {0} could not be created during execution of the integrated tool Refresh Dependencies.
  • TSRDZ0013 An error occurred while parsing the error feedback XML file.
  • TSRDZ0014 Could not find category for COBOL on the system.
  • TSRDZ0015 Could not find category for PLI on the system.
  • TSRDZ0016 Could not find category for ASSEMBLER on the remote system.
  • TSRDZ0017 Could not find category for C_CPP on the remote system.
  • TSRDZ0018 Duplicate instance of category: {0} .
  • TSRDZ0019 The language: {0} is not supported.
  • TSRDZ0020 SYSLIB parsing error.
  • TSRDZ0021 No container for system: {0} .
  • TSRDZ0022 Parameter property group name is missing.
  • TSRDZ0023 The resource {0} was not found.
  • TSRDZ0024 The property group {0} does not exist.
  • TSRDZ0025 The property group {0} already exists. Parameter Replace was {1} .
  • TSRDZ0026 The name of existing property group {0} to be copied was not found in the system.
  • TSRDZ0027 The Property Group {0} already exists in the system
  • TSRDZ0032 {0} is neither a sequential data set nor a member of a partitioned data set.
  • TSRDZ0033 Failed to get contents of file {0} .
  • TSRDZ0034 Recall for data set {0} failed.
  • TSRDZ0035 Failed to retrieve data set named {0} .
  • TSRDZ0036 Operation cancelled by user.
  • TSRDZ0038 Failed to set contents for data set {0} .
  • TSRDZ0040 Failed to allocate the data set {0} .
  • TSRDZ0041 Deletion of data set failed: {0} .
  • TSRDZ0042 Failed to connect to {0} .
  • TSRDZ0046 Failed to wait for RSE initialization.
  • TSRDZ0047 {0} is not a partitioned data set.
  • TSRDZ0048 {0} does not exist on System {1}
  • TSRDZ0049 {0} is not a valid ZOSDataset, could not retrieve FileAttributes
  • TSRDZ0053 The remote resources {0} and/or {1} were not found.
  • TSRDZ0054 The first and second file descriptor to compare must be of type MVSPO_Member or MVS_SEQ
Parent topic: Error messages


TSRDZ0001 The remote resource {0} was not found.

The remote resource {0} could not be retrieved. This may be a general connection problem, or the data set could not be found in the host system, or a modeled integrated tool is not correctly modeled.

User Response:
Verify that there is a connection to z/OS.
Model Administrator Response:
  • If the problem is caused by a modeled integrated tool, verify that the input parameters are correctly modeled.
  • Check the error log for more information.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0002 An error occurred while trying to open the file {0}

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0003 Connection failed when trying to reach the remote system job utility.

The connection to the remote system could not be established.

Server Administrator Response:
  • Check if there are any network problems.
  • Verify that the server is up and running.
  • Check the server logs and z/OS SYSLOG for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0004 Failed to initialize the IDz Job Utility.

The creation of an instance of the JesJobUtil class failed.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0005 The job with the ID {0} could not be read.

The given job's contents could not be read from the remote system.

Server Administrator Response:
  • Verify that the server is up and running (especially the JMON started task).
  • Check if there are any network problems.
  • Check the server logs and z/OS SYSLOG for more information.
  • Check if the job still exists.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0006 DD {0} of job {1} could not be read.

The given DD contents of the given job could not be read from the remote system.

Server Administrator Response:
  • Verify that the server is up and running (especially the JMON started task).
  • Check if there are any network problems.
  • Check the server logs and z/OS SYSLOG for more information.
  • Check if the job still exists.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0007 DDs of the job with the ID {0} could not be determined.

The DD statements of the given job could not be determined.

Server Administrator Response:
  • Verify that the server is up and running (especially the JMON started task).
  • Check if there are any network problems.
  • Check the server logs and z/OS SYSLOG for more information.
  • Check if the job still exists.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0008 The return code of the job with the ID {0} could not be determined.

The return code of the given job could not be determined.

Server Administrator Response:
  • Verify that the server is up and running (especially the JMON started task).
  • Check if there are any network problems.
  • Check the server logs and z/OS SYSLOG for more information.
  • Check if the job still exists.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0009 Invalid resource during association of property group.

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0010 A local property group with name {0} does not exist.

The property group to be associated with the element could not be found in the local system.

Model Administrator Response:
Make sure that the element special property "Property Group" exists in the local user system.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0011 The error feedback XML file could not be read during the execution of the integrated tool RefreshDependencies.

The input file parameter for a tool refreshing the copybooks could not be read. It may not be modeled correctly or could not be accessed (insufficient RACF authority).

Model Administrator Response:
Verify that the input file parameter of the integrated tool "RefreshDependencies" is modeled correctly.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0012 The folder {0} could not be created during execution of the integrated tool Refresh Dependencies.

Failed to execute the integrated tool "Refresh Dependencies" because the folder could not be created where the copybooks should be copied to. The internal application folder is either out of synchronization or it could not be accessed.

User Response:
  • Refresh the internal application folder.
  • Restart the client.
  • Make sure that you have write access to the internal application folder.
  • See the log file for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0013 An error occurred while parsing the error feedback XML file.

The input file parameter of the tool refreshing the copybooks cannot be parsed. It may be not modeled correctly or the file syntax was incorrect.

Model Administrator Response:
  • Verify that the input file parameter of the integrated tool "RefreshDependencies" is correctly modeled.
  • Verify the syntax of the XML file.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0014 Could not find category for COBOL on the system.

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0015 Could not find category for PLI on the system.

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0016 Could not find category for ASSEMBLER on the remote system.

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0017 Could not find category for C_CPP on the remote system.

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0018 Duplicate instance of category: {0} .

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0019 The language: {0} is not supported.

The language {0} (second input parameter to integrated tool "PropertySetCreator") is not supported.

Model Administrator Response:
Change the language to (COBOL, PLI, PL1, ASM, ASSEMBLER, C, CPP, C_CPP, C/CPP).
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0020 SYSLIB parsing error.

An error occurred when parsing the SYSLIB configured in the integrated tool "PropertySetCreator". This is a modeling error.

Model Administrator Response:
See Defining the SYSLIB attribute to resolve COBOL copybooks in the Workflow Manager Configuration Guide for how to configure the integrated tool "PropertySetCreator".
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0021 No container for system: {0} .

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0022 Parameter property group name is missing.

The name of the property group which is to be associated with the element is missing. This is a modeling error.

Model Administrator Response:
Make sure that the configured property group name will be found in the context.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0023 The resource {0} was not found.

The physical resource of the element whose property group should have been associated was not found on the host during execution of the integrated tool "PropertySetAssociator". This may be a modeling error.

Model Administrator Response:
Ensure that the integrated tool "PropertySetAssociator" is modeled correctly.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0024 The property group {0} does not exist.

The property group to be associated with the element could not be found in the system. This may be a modeling error.

Model Administrator Response:
Ensure that the property group exists on the user system or modify the tool configuration.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0025 The property group {0} already exists. Parameter Replace was {1} .

The property group to be created could not be replaced because the integrated tool "PropertyGroupCreator" is configured in such a way that replacements are not allowed. This property group was already defined in the system.

Model Administrator Response:
Change the first input parameter of 'PropertySetCreator' or delete the existing property group on the user system.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0026 The name of existing property group {0} to be copied was not found in the system.

The integrated tool "PropertySetCreator" is configured in such a way that an existing property group to be copied. But this property group was not found in the system.

Model Administrator Response:
Ensure that the property group to be copied exists in the user system or modify the tool configuration.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0027 The Property Group {0} already exists in the system

The integrated tool "PropertySetCreator" failed during its execution because the property group to be created already exists in the system.

Model Administrator Response:
Change the first input parameter of "PropertySetCreator" or delete the existing property group in the user system.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0032 {0} is neither a sequential data set nor a member of a partitioned data set.

Failed to get the content of the data set that corresponds to the file descriptor of the tool because it is neither a sequential data set nor a member of a partitioned data set.

Model Administrator Response:
Ensure that the remote resource of the file descriptor is a sequential data set or a member of a partitioned data set.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0033 Failed to get contents of file {0} .

Failed to get the content of the remote file. This can have several reasons:

  • General connection problem.
  • Modeling errors.
  • RACF access problem.
User Response:
Verify that you have a connection to z/OS.
Model Administrator Response:
  • If the file is from a modeled tool, verify that it is modeled correctly.
  • Check the error log for more information.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0034 Recall for data set {0} failed.

When attempting to get the contents of a migrated data set {0}, the data set could not be recalled.

Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0035 Failed to retrieve data set named {0} .

The data set {0} could not be found in the remote system. This may be a general connection problem or a modeling error.

Model Administrator Response:
  • If the file is from a modeled tool, verify that it is modeled correctly.
  • Check the error log for more information.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0036 Operation cancelled by user.

Self-explanatory.

User Response:
Retry the action.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0038 Failed to set contents for data set {0} .

Failed to set the content of a remote data set. This can have several reasons:

  • General connection problem.
  • Modeling errors.
  • RACF access problem.
User Response:
Check that you have a connection to z/OS.
Model Administrator Response:
  • If the file is from a modeled tool, verify that it is modeled correctly.
  • Check the error log for more information.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0040 Failed to allocate the data set {0} .

Data set {0} cannot be allocated.

User Response:
Verify that you have a connection to z/OS.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0041 Deletion of data set failed: {0} .

Data set {0} cannot be deleted.

User Response:
Check that you have a connection to z/OS.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0042 Failed to connect to {0} .

The connection to z/OS cannot be established

User Response:
  • Verify the network connection to the server.
  • Verify the server definition in the client (host name, port).
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0046 Failed to wait for RSE initialization.

This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0047 {0} is not a partitioned data set.

Failed to get the members of data set {0} because it is not a partitioned data set. This may be a modeling error.

Model Administrator Response:
If this error occurs during the execution of a modeled tool, verify that the tool description and file descriptor are correctly modeled.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0048 {0} does not exist on System {1}

The client failed to receive attributes of a file because it does not seem to exist on the target system.

Model Administrator Response:
Verify that the file name is correct.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0049 {0} is not a valid ZOSDataset, could not retrieve FileAttributes

Failed to receive the attributes of a z/OS data set because the file name does not seem to be valid.

Model Administrator Response:
Verify that the file name is correct.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0053 The remote resources {0} and/or {1} were not found.

At least one remote resource could not be retrieved for opening a compare editor. Possible reasons are:

  • One or both files do not exist.
  • The integrated tool "File Compare" is not properly modeled.
  • Connection problems to the remote system.
User Response:
Verify that there is a connection to z/OS.
Model Administrator Response:
  • If the problem is caused by a modeled integrated tool, verify that the input parameters are correctly modeled.
  • Check the error log for more information.
Server Administrator Response:
Check the server logs and z/OS hardcopy log for more information.
Parent topic: AWM IDz (TSRDZ) messages


TSRDZ0054 The first and second file descriptor to compare must be of type MVSPO_Member or MVS_SEQ

The execution of the integrated tool FileCompare failed because the first and/or second file descriptor were not declared as type MVSPO_Member or MVSSEQ file descriptor.

Model Administrator Response:
Verify the type of the first and second file descriptor associated as input parameter with the integrated tool FileCompare. The file descriptors must be of type MVSPO_Member or MVSSEQ.
Parent topic: AWM IDz (TSRDZ) messages


AWM z/Server (TSZSV) messages

  • TSZSV0001 The data set is migrated. Do you wish to recall it?
  • TSZSV0002 Data set is migrated.
  • TSZSV0003 Exception when allocating data set: {0} .
  • TSZSV0004 IO exception during dialog processing.
  • TSZSV0005 z/Server exception during dialog processing.
  • TSZSV0006 Data set migration exception during dialog processing.
  • TSZSV0007 XML parse exception during dialog processing.
  • TSZSV0008 No UI Tool configured for {0} .
  • TSZSV0009 z/Server parameter error: Parameter {0} not found in parameter memory.
  • TSZSV0010 Invalid parameter string received from z/Server: {0} .
  • TSZSV0011 z/Server parameter error: Value length missing for {0} .
  • TSZSV0012 z/Server parameter error: Value length for {0} is not numeric.
  • TSZSV0013 z/Server parameter error: Value length too short for {0} .
  • TSZSV0014 Error when parsing input for table. More table properties configured than delivered by the remote tool (file descriptor: {0} ).
  • TSZSV0015 Error when parsing input for table. Value for property {0} not found.
  • TSZSV0016 Error when parsing input for table.
  • TSZSV0017 Failed to parse the response: {0} .
  • TSZSV0018 IO Exception during ISPF dialog processing.
  • TSZSV0019 Exception during ISPF dialog processing.
  • TSZSV0020 Port {0} freed.
  • TSZSV0021 There are no z/OS systems defined. Please define a new connection first.
  • TSZSV0022 Target Management initialization interrupted.
  • TSZSV0023 {0} is incompatible with {1} .
  • TSZSV0025 The file type {0} is not supported by {1} .
  • TSZSV0026 Exception when calling the edit interface during dialog processing.
  • TSZSV0027 Failed to get enqueue info for resource {0} .
  • TSZSV0028 The resource is locked by another user.
  • TSZSV0029 Action cancelled by user.
  • TSZSV0030 The file {0} already exists.
  • TSZSV0031 The first file type {0} is not supported for the FileCompareRemote
  • TSZSV0032 {0} does not exist on System {1}
  • TSZSV0033 {0} does not exist on System {1}
  • TSZSV0034 Error deleting {0} ({1} )
Parent topic: Error messages


TSZSV0001 The data set is migrated. Do you wish to recall it?

This is an informational message indicating that the selected data set is in migrated status on the remote system. It has to be recalled before it can be used.

User Response:
Respond to the dialog.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0002 Data set is migrated.

The selected data set is migrated. The requested action cannot be performed.

User Response:
Use the context menu action Recall to recall the data set. Then repeat the requested action.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0003 Exception when allocating data set: {0} .

A tool execution needs a parameter file to be allocated on the remote system with the given name. This allocation failed.

Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0004 IO exception during dialog processing.

An I/O exception occurred during the execution of an ISPF dialog process.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0005 z/Server exception during dialog processing.

A z/Server exception occurred during the execution of an ISPF dialog process.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0006 Data set migration exception during dialog processing.

An exception occurred during the execution of an ISPF dialog process because a requested data set was migrated.

User Response:
Recall the requested data set and retry the ISPF dialog execution.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0007 XML parse exception during dialog processing.

An XML response from the z/Server could not be interpreted.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0008 No UI Tool configured for {0} .

The ISPF dialog process called a panel for which no tool was configured in the corresponding model file. Each panel called in the ISPF application must have a tool with an ISA_ISPF_Panel relation with attribute Panel Name set to the name of the ISPF panel.

Model Administrator Response:
Correct the tool definition in the model file.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0009 z/Server parameter error: Parameter {0} not found in parameter memory.

A parameter which was expected to be found in the parameter memory was not found.

Model Administrator Response:
Verify the model file. Verify if the attribute "Parameter From" is set correctly.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0010 Invalid parameter string received from z/Server: {0} .

An unexpected message format was send from the z/Server to the client during the execution of an ISPF dialog process.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0011 z/Server parameter error: Value length missing for {0} .

An unexpected message format was sent from z/Server to the client during the execution of an ISPF dialog process.

Model Administrator Response:
  • Check the error log for more information.
  • Verify that the extension of the corresponding ISPF panel is correct (TAUPARMS entry).
  • Verify that the panel field parameters of the corresponding tool are modeled correctly.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0012 z/Server parameter error: Value length for {0} is not numeric.

An unexpected message format was send from z/Server to the client during the execution of an ISPF dialog process.

Model Administrator Response:
  • Check the error log for more information.
  • Verify that the extension of the corresponding ISPF panel is correct (TAUPARMS entry).
  • Verify that the panel field parameters of the corresponding tool are modeled correctly.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0013 z/Server parameter error: Value length too short for {0} .

An unexpected message format was sent from z/Server to the client during the execution of an ISPF dialog process.

Model Administrator Response:
  • Check the error log for more information.
  • Verify that the extension of the corresponding ISPF panel is correct (TAUPARMS entry).
  • Verify that the panel field parameters of the corresponding tool are modeled correctly.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0014 Error when parsing input for table. More table properties configured than delivered by the remote tool (file descriptor: {0} ).

An unexpected message format was sent from z/Server to the client during the execution of an ISPF dialog process with an ISPF table. The remote tool sent fewer values than properties were configured for the corresponding file descriptor.

Model Administrator Response:
  • Verify that the extension of the corresponding ISPF panel is correct (TAUTABV entry).
  • Verify that the properties of the corresponding file descriptor are modeled correctly.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0015 Error when parsing input for table. Value for property {0} not found.

An unexpected message format was sent from z/Server to the client during the execution of an ISPF dialog process with an ISPF table. The value of a property was not sent in the expected length.

Model Administrator Response:
  • Verify that the extension of the corresponding ISPF panel is correct (TAUTABV entry).
  • Verify that the properties of the corresponding file descriptor are modeled correctly.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0016 Error when parsing input for table.

An unexpected message format was sent from z/Server to the client during the execution of an ISPF dialog process with an ISPF table.

Model Administrator Response:
  • Verify that the extension of the corresponding ISPF panel is correct (TAUTABV entry).
  • Verify that the properties of the corresponding file descriptor are modeled correctly.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0017 Failed to parse the response: {0} .

An unexpected message format was sent from z/Server to the client during the execution of an ISPF dialog process. An expected tool parameter could not be found in the response.

Model Administrator Response:
  • Check the error log for more information.
  • Verify that the extension of the corresponding ISPF panel is correct (TAUPARMS entry).
  • Verify that the panel field parameters of the corresponding tool are modeled correctly.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0018 IO Exception during ISPF dialog processing.

An I/O exception occurred during the execution of an ISPF dialog process.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0019 Exception during ISPF dialog processing.

An exception occurred during the execution of an ISPF dialog process.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0020 Port {0} freed.

This is an informational message indicating that the given port is released at the end of an ISPF dialog process.

User Response:
This is an informational message.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0021 There are no z/OS systems defined. Please define a new connection first.

A z/OS connection must be defined before a system reference can be defined.

User Response:
Define a z/OS connection in the Remote System View first.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0022 Target Management initialization interrupted.

The initialization of the target management which is a prerequisite for AWM was interrupted during Eclipse start up.

User Response:
If there are consecutive error situations, restart Eclipse.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0023 {0} is incompatible with {1} .

An ISystemImage instance was loaded which is not compatible with the zSystemUtilities class.

Model Administrator Response:
If this is a customer-own implementation of the ISystemImage, ensure that this implementation complies with the IConnectorService interface. Otherwise contact SupportLine.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0025 The file type {0} is not supported by {1} .

A file descriptor with a file type which is not supported by the zServer edit class was passed to the integrated tool RemoteEdit.

Server Administrator Response:
Contact SupportLine.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0026 Exception when calling the edit interface during dialog processing.

An exception occurred when the ISPF edit interface was called within an ISPF dialog process.

Model Administrator Response:
Verify if there is additional information in the user server's SYSTSPRT output. If necessary repeat the action with the dialog debug option set on.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0027 Failed to get enqueue info for resource {0} .

A z/OS resource was locked by another user and the GETENQI z/Server command caused an exception. This is either caused by a z/Server issue or an internal client exception.

Server Administrator Response:
Check the z/Server scheduler trace for correctly receiving the GETENQI message.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0028 The resource is locked by another user.

A resource was locked by another user and the z/Server GETENQI command was scheduled to retrieve detailed enqueue information. The command was successfully executed but returned an empty response. This can occur if the enqueue was made by another z/Server scheduler which was managed by a different z/Server holder task.

Server Administrator Response:
Verify that the users are not working with different z/Server scheduler tasks which are managed by different holder tasks. If that is the case, consider reconfiguring the z/Server tasks.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0029 Action cancelled by user.

Self-explanatory.

User Response:
This is an informational message.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0030 The file {0} already exists.

A file could not be created by the integrated tool "File Compare" because it already existed. This error only occurs if no user interface is available.

User Response:
Delete the file manually and try again.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0031 The first file type {0} is not supported for the FileCompareRemote

The execution of the integrated tool FileCompare failed because the first file descriptor was not declared as type MVSPO_Member or MVSSEQ file descriptor.

Model Administrator Response:
Verify the type of the first file descriptor associated as input parameter with the integrated tool FileCompare. The file descriptor must be of type MVSPO_Member or MVSSEQ.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0032 {0} does not exist on System {1}

Self-explanatory.

User Response:
Self-explanatory.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0033 {0} does not exist on System {1}

Self-explanatory.

User Response:
Self-explanatory.
Parent topic: AWM z/Server (TSZSV) messages


TSZSV0034 Error deleting {0} ({1} )

Self-explanatory.

User Response:
Self-explanatory. Verify that there is no network problem.
Parent topic: AWM z/Server (TSZSV) messages


AWM edit macro (TSMAC) messages

  • TSMAC0001 The edit macro name must not be an empty string.
  • TSMAC0002 Not a remote edit session.
  • TSMAC0003 An error occurred while sending the host command: {0} .
  • TSMAC0004 The file descriptor {0} is not a member or sequential data set.
Parent topic: Error messages


TSMAC0001 The edit macro name must not be an empty string.

An edit macro tool descriptor was executed with an empty edit macro name parameter.

Model Administrator Response:
Verify in the model that the edit macro tool descriptor cannot be executed with an empty edit macro name parameter.
Parent topic: AWM edit macro (TSMAC) messages


TSMAC0002 Not a remote edit session.

An edit macro tool descriptor was called within a non-remote edit session.

User Response:
Close the editor and open the same file using the MVS Explorer or a "remote edit" action from a modeled application.
Parent topic: AWM edit macro (TSMAC) messages


TSMAC0003 An error occurred while sending the host command: {0} .

The host command for a edit macro was not sent successfully.

Model Administrator Response:
Check the error log for more information.
Parent topic: AWM edit macro (TSMAC) messages


TSMAC0004 The file descriptor {0} is not a member or sequential data set.

A edit macro tool descriptor was executed within an editor which was opened with an invalid file descriptor.

Model Administrator Response:
Verify that modeled edit actions with edit macro support use the integrated tools "RemoteEdit" or "RemoteBrowse" which accept the correct file descriptors only. If other edit actions exist (like local edit), consider adding enabled conditions to the edit macro editor actions.
Parent topic: AWM edit macro (TSMAC) messages


AWM ED integration (TSMFI) messages

  • TSMFI0001 Failed to create the default Enterprise Developer AWM model.
Parent topic: Error messages


TSMFI0001 Failed to create the default Enterprise Developer AWM model.

A exception occurred while creating the standard Enterprise Developer system.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the Administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM ED integration (TSMFI) messages


AWM meta model (TSMDL) messages

  • TSMDL0002 The converter could not detect the reason for the model incompatibility. Please check the Details area after closing this message.
  • TSMDL0003 No property provider was found for the linked property with the ID \ {0} \.
  • TSMDL0004 Failed to initialize function package \ {0} \.
  • TSMDL0005 ID conflict: {0}{1} .
  • TSMDL0006 Duplicate ID detected: {0} . This conflict must be resolved in the corresponding function package definition.
  • TSMDL0007 Failed to load AWM function packages.
  • TSMDL0008 The function package with the ID \ {0} \ could not be parsed.
  • TSMDL0009 Model extension ID conflicts detected: {0} .
  • TSMDL0010 The function package \ {0} \ was defined at least twice and cannot be merged, because {1} .
  • TSMDL0011 Failed to resolve the attribute reference \ {0} \ of object \{1} \.
  • TSMDL0012 Invalid cardinality: \ {0} \ of complex attribute \{1} \.
  • TSMDL0013 Cannot convert model file, since the URI \ {0} \ does not seem to point to a workspace file.
  • TSMDL0014 No complex attribute (EClass) found for ID \ {0} \.
Parent topic: Error messages


TSMDL0002 The converter could not detect the reason for the model incompatibility. Please check the Details area after closing this message.

AWM was trying to convert a model that seems to be incompatible with the current version but failed since no repairable incompatibilities were detected.

Model Administrator Response:
Open the model in the model editor and click the Details button in the editor. A list will open up within the editor containing detailed messages about why the model is incompatible with AWM. Send this information to SupportLine if necessary.
Parent topic: AWM meta model (TSMDL) messages


TSMDL0003 No property provider was found for the linked property with the ID \ {0} \.

The property provider for a linked property was not found. Either the function package is missing or was not properly installed/initialized.

Model Administrator Response:
Contact SupportLine if the linked property ID starts with "com.microfocus".

If the extension was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the contributor name is not known.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0004 Failed to initialize function package \ {0} \.

A function package could not be initialized. This can be caused by invalid function package extensions or errors during Eclipse startup.

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the function package ID is not known.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0005 ID conflict: {0}{1} .

A function package contains conflicting IDs.

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider.

The conflicting IDs must be removed.

Contact SupportLine if the function package ID is not known.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0006 Duplicate ID detected: {0} . This conflict must be resolved in the corresponding function package definition.

A function package contains conflicting IDs.

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider.

The conflicting IDs must be removed.

Contact SupportLine if the function package ID is not known.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0007 Failed to load AWM function packages.

Function packages could not be loaded. This can be caused by invalid function package extensions or errors during Eclipse startup.

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the function package ID is not known or the plug-in contributor is unable to resolve the issue.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0008 The function package with the ID \ {0} \ could not be parsed.

A function package could not be parsed. This can be caused by invalid function package extensions.

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider. The error log should contain more specific information.

Contact SupportLine if the function package ID is not known or the plug-in provider is not able to resolve the issue.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0009 Model extension ID conflicts detected: {0} .

A function package contained ID conflicts (usually duplicates).

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider. The ID conflicts must be resolved.

Contact SupportLine if the function package ID is not known or the plug-in provider is not able to resolve the issue.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0010 The function package \ {0} \ was defined at least twice and cannot be merged, because {1} .

At least two function package extensions containing the same package ID cannot be merged.

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider. The error log should contain more specific information.

Contact SupportLine if the function package ID is not known or the plug-in provider is not able to resolve the issue.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0011 Failed to resolve the attribute reference \ {0} \ of object \{1} \.

A function package attribute reference could not be resolved. This can be caused by invalid reference target IDs.

Model Administrator Response:
Contact SupportLine if the package ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider. The corresponding target ID attribute probably needs to be corrected.

Contact SupportLine if the function package ID is not known or the plug-in provider is not able to resolve the issue.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0012 Invalid cardinality: \ {0} \ of complex attribute \{1} \.

The cardinality attribute of a complex function package attribute was invalid.

Model Administrator Response:
Contact SupportLine if the complex attribute ID starts with "com.microfocus".

If the function package was developed internally by using the AWM API, contact the plug-in provider. The cardinality string must have a value according to the extension point documentation.

Contact SupportLine if the function package ID is not known or the plug-in provider is not able to resolve the issue.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0013 Cannot convert model file, since the URI \ {0} \ does not seem to point to a workspace file.

An outdated or invalid model from outside the workspace was loaded, but the model converter only supports conversion of models in the workspace.

Model Administrator Response:
Check the error log for the initial error message.

Copy the model into your workspace and try opening it with the model editor.

Parent topic: AWM meta model (TSMDL) messages


TSMDL0014 No complex attribute (EClass) found for ID \ {0} \.

This is an unexpected internal program error.

Model Administrator Response:
Please contact SupportLine.
Parent topic: AWM meta model (TSMDL) messages


AWM meta model editor (TSMET) messages

  • TSMET0001 Model import failed.
  • TSMET0002 At least one given object must not be null.
  • TSMET0003 An error occured during the drag and drop operation.
  • TSMET0004 Unable to execute {0} command.
  • TSMET0006 Error creating nested text editor.
  • TSMET0007 Tool type extension \ {0} \ not found.
Parent topic: Error messages


TSMET0001 Model import failed.

The model import action could not be executed. Possible reasons are:

  • At least one of the two models is inconsistent.
  • An internal error occurred during the import process.
User Response:
Use the validate function to find out if both models on their own are consistent. Fix the models if validation errors occur. If both models seem to be valid, contact SupportLine.
Parent topic: AWM meta model editor (TSMET) messages


TSMET0002 At least one given object must not be null.

This is an internal program exception which is not supposed to occur under any circumstances.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM meta model editor (TSMET) messages


TSMET0003 An error occured during the drag and drop operation.

The model import action could not be executed. Possible reasons are:

  • At least one of the two models is inconsistent.
  • An internal error occurred during the import process.
User Response:
Use the validate function to find out if both models on their own are consistent. Fix the models if validation errors occur. If both models seem to be valid, contact SupportLine.
Parent topic: AWM meta model editor (TSMET) messages


TSMET0004 Unable to execute {0} command.

The model import action could not be executed. Possible reasons are:

  • At least one of the two models is inconsistent.
  • An internal error occurred during the import process.
User Response:
Use the validate function to find out if both models are consistent. Fix the models if validation errors occur. If both models seems to be valid, contact SupportLine.
Parent topic: AWM meta model editor (TSMET) messages


TSMET0006 Error creating nested text editor.

The model editor could not be opened and initiated properly. This is an internal program exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM meta model editor (TSMET) messages


TSMET0007 Tool type extension \ {0} \ not found.

A tool type extension could not be found under the installed software.

Model Administrator Response:
Check if all required software is installed for the modeled tools.
Parent topic: AWM meta model editor (TSMET) messages


AWM remote preprocessor (TSRPP) messages

  • TSRPP0001 No AWM application loaded.
  • TSRPP0002 Remote Pre-Processor requires a loaded AWM application of a remote z/Server system.
Parent topic: Error messages


TSRPP0001 No AWM application loaded.

The remote preprocessor could not be executed, because no AWM application was properly loaded.

User Response:
Load an AWM application containing a z/Server reference (either created by z/Server connection or associated manually).
Parent topic: AWM remote preprocessor (TSRPP) messages


TSRPP0002 Remote Pre-Processor requires a loaded AWM application of a remote z/Server system.

The remote preprocessor could not find a remote system connection, because no remote (z/Server) AWM application was loaded.

User Response:
Load an AWM application containing a z/Server reference (either created by z/Server connection or associated manually).
Parent topic: AWM remote preprocessor (TSRPP) messages


AWM MVS system (TSMVS) messages

  • TSMVS0001 The parameter file {0} could not be created.
  • TSMVS0002 A file input parameter must be set.
  • TSMVS0003 File input parameters are not yet supported by the ISPF tool executor.
  • TSMVS0005 Could not connect to z/OS.
  • TSMVS0006 The command \ {0} \ could not be sent.
  • TSMVS0007 Could not write on file: {0} .
  • TSMVS0008 The parameter file {0} could not be read.
  • TSMVS0009 Invalid input parameter configuration: Parameter From = {0} .
  • TSMVS0010 Wrong format for return code of tool {0} {1}{2} .
  • TSMVS0011 The return code {0} of tool {1} exceeds the maximum return code of {2} .
  • TSMVS0012 Unexpected return code of tool {0} . The return code was {1} .
  • TSMVS0013 Tool {0} returns fewer parameters than expected. {1} parameters were detected while {2} parameters were specified for this tool.
  • TSMVS0014 Failed to create the job. The {0} statement is expected before line {1} .
  • TSMVS0015 Failed to parse the out parameter DSN for job {0} : {1} .
  • TSMVS0016 Failed to parse Job ID and name: {0} .
  • TSMVS0023 An error occurred while parsing the error feedback file.
  • TSMVS0024 Missing file name for file descriptor {0} .
  • TSMVS0025 The file {0} contains fewer values than configured properties.
  • TSMVS0026 The given error feedback XML file could not be parsed because the PACKAGE element was not found.
  • TSMVS0027 Missing program ID for tool \ {0} \.
  • TSMVS0028 Tool {0} returns more mass output parameter lines than expected. Expected parameter lines: {1}
Parent topic: Error messages


TSMVS0001 The parameter file {0} could not be created.

The MVS parameter file used to pass long parameters between client and mainframe could not be allocated.

Server Administrator Response:
  • Check if the user has write authority to the parameter file.
  • Delete the parameter file if it already exists, and ask the user to retry the action. It is possible that the parameter file was allocated incorrectly.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0002 A file input parameter must be set.

An integrated tool descriptor for edit or browse was modeled without a file input parameter (which is required).

Model Administrator Response:
Add a file input parameter to the corresponding tool descriptor. Verify that a file descriptor is referenced by the "Target_ID_File" attribute of the input parameter and that the "Type" attribute is set to "File".
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0003 File input parameters are not yet supported by the ISPF tool executor.

An ISPFCOMMAND tool descriptor was modeled with a file input parameter, which is currently not supported.

Model Administrator Response:
Remove the corresponding file input parameter from the tool descriptor or check whether the "Type" attribute of the parameter was accidentally set to "File".
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0005 Could not connect to z/OS.

An ISPFCOMMAND tool could not be executed because a z/OS connection could not be established completely. (XXXX) this is either caused by a network problem or an issue while loading a model while connecting.

User Response:
  • Check your network connection to the server.
  • Check your server definition in the client (host name, port).
Server Administrator Response:
  • Verify that the host server is up and running correctly.
  • Check the error details. If the underlying error message correlates to an issue while loading a model, please verify that the model under the specified location of the "zExpConf" attribute of the master configuration exists, is accessible and valid. If no "zExpConf" attribute is defined in the master configuration, an internal client error occurred.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0006 The command \ {0} \ could not be sent.

An ISPFCOMMAND tool failed executing a TSO or server command. This can either be caused by executing a REXX procedure, communicating with an ISPF panel (XXXX) or an inconsistent client installation.

User Response:
  • Check your network connection to the server.
  • Check your server definition in the client (host name, port).
Model Administrator Response:
Check the error details to see whether the error was caused by an inconsistent client installation. If that is the case, re-install the client on the corresponding machine.
Server Administrator Response:
Check whether the error message was caused while an ISPF dialog was executed.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0007 Could not write on file: {0} .

An ISPFCOMMAND tool failed to write input parameters into the parameter file.

User Response:
  • Check your network connection to the server.
  • Check your server definition in the client (host name, port).
Server Administrator Response:
  • Check whether the user has write rights on the parameter file.
  • Delete the parameter file if it already exists and ask the user to retry the action. It is possible that the parameter file was allocated incorrectly.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0008 The parameter file {0} could not be read.

An ISPFCOMMAND tool failed to receive parameters from the parameter file after the remote function was executed.

User Response:
Check your network connection to the server.
Server Administrator Response:
  • Check if the parameter data set exists and can be read.
  • Check if the user has RACF authority to read the parameter file data set.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0009 Invalid input parameter configuration: Parameter From = {0} .

The "Parameter_From" attribute of an input parameter of a ISPFCOMMAND tool descriptor was set to an unsupported value.

Model Administrator Response:
Change the "Parameter_From" attribute of the corresponding input parameter either to "Context" or "Previous_Tool".
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0010 Wrong format for return code of tool {0} {1}{2} .

The called ISPFCOMMAND tool did not return a return code in the expected format. In most cases, the tool returns an (error) message instead, which will then be printed at the end of the message.

Model Administrator Response:
  • Check whether the corresponding tool received the correct parameters from the client. This can be done by debugging the remote tool itself or enabling the client trace. If the parameter values are not as expected, correct both action descriptor and tool descriptor definitions in the model.
  • Debug the corresponding tool on the z/OS.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0011 The return code {0} of tool {1} exceeds the maximum return code of {2} .

An ISPFCOMMAND tool returned a return code that is higher than the configured maximum return code (Max_RC) configured in the model. In most cases, the corresponding tool also returns a more specific error message that is shown beneath this error message. This can be an expected error situation depending on the called tool.

Model Administrator Response:
  • Verify that the action executed by the user was valid. This depends on the application modeled. Example: The attempt to delete a data set member that is in exclusive use by another user counts as an invalid action.
  • Check if the specific tool received the correct input parameters. If not, check both the action and tool descriptor definition in the model.
  • Debug the ISPFCOMMAND tool.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0012 Unexpected return code of tool {0} . The return code was {1} .

The return code value of the executed ISPFCOMMAND tool was not numeric.

Model Administrator Response:
Verify that the return code values of the specific tool are always numeric and are not led or followed by any other characters.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0013 Tool {0} returns fewer parameters than expected. {1} parameters were detected while {2} parameters were specified for this tool.

An ISPFCOMMAND tool returned fewer parameters than defined in its corresponding tool descriptor.

Model Administrator Response:
Either correct to tool output or the tool descriptor definition in the model so that the modeled output parameters match the actual tool output.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0014 Failed to create the job. The {0} statement is expected before line {1} .

The client failed to parse the output of an ISPFCOMMAND tool which submitted a job or was executed in batch because the "JOBPARM: {jobid} {jobname}" statement was missing or in the wrong position.

Server Administrator Response:
The JOBPARM statement should be created by the TAUTOIFA REXX procedure shipped with the product. If no customizations were made to that procedure, an internal error has occurred. Contact SupportLine.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0015 Failed to parse the out parameter DSN for job {0} : {1} .

The client failed to parse the output of an ISPFCOMMAND tool which submitted a job or was executed in batch because the JOBOUTPARMDSN statement was missing.

Server Administrator Response:
The JOBOUTPARMDSN statement should be created by the TAUTOIFA REXX procedure shipped with the product. If no customizations were made to that procedure, an internal error has occurred. Contact SupportLine.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0016 Failed to parse Job ID and name: {0} .

The client failed to parse the output of an ISPFCOMMAND tool which submitted a job or was executed in batch because the "JOBPARM: {jobid} {jobname}" statement was either missing or invalid.

Server Administrator Response:
The JOBPARM statement should be created by the TAUTOIFA REXX procedure shipped with the product. If no customizations were made to that procedure, an internal error has occurred. Contact SupportLine.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0023 An error occurred while parsing the error feedback file.

A general error occurred when the integrated tool "ErrorFeedback" tried to parse the error feedback XML file. This can have several reasons:

  • General connection problem.
  • The given file is not a valid XML file.
  • The Java XML parser encountered an internal problem.
User Response:
Check your connection to the remote system (if available). Note that the error feedback XML file is not necessarily located on a remote system.
Model Administrator Response:
Verify that the file input parameter of the corresponding tool descriptor points to the correct XML file.
Server Administrator Response:
Determine why the XML file seems to be invalid by debugging the tool which should create the XML file.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0024 Missing file name for file descriptor {0} .

A remote file could not be read because no file name was found for a modeled file descriptor.

Model Administrator Response:
If the file name should be returned from a modeled tool, check why the file name was found in the tool which caused the error message. In this case the "Parameter_From" attribute of the file input parameter must be set to "Previous_Tool". The tool which returns the file name must be called before the tool which requires the file name. If the file name should not have been returned by a tool, the "Name_Physical" attribute of the file descriptor needs to be defined in the model.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0025 The file {0} contains fewer values than configured properties.

The parsed file contains fewer values per line than Properties defined in the corresponding file descriptor.

Model Administrator Response:
Either change the creation of the file (or the file itself if it is not created dynamically) or the corresponding file descriptor in the model so that the number of values per line match the modeled properties of the file descriptor.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0026 The given error feedback XML file could not be parsed because the PACKAGE element was not found.

The given error feedback XML file for the integrated tool "ErrorFeedback" was invalid because no "PACKAGE" element was found.

Model Administrator Response:
  • Verify that the file input parameter of the corresponding tool descriptor points to the correct XML file.
  • Check why the XML file seems to be invalid, by debugging the tool which creates the XML file.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0027 Missing program ID for tool \ {0} \.

The program ID of an "Execute ISPF Command" tool is not set.

Model Administrator Response:
Add the missing program ID to the "Execute ISPF Command" tool.
Parent topic: AWM MVS system (TSMVS) messages


TSMVS0028 Tool {0} returns more mass output parameter lines than expected. Expected parameter lines: {1}

An "Execute ISPF Command" tool returned more parameters than defined in its corresponding tool descriptor.

Model Administrator Response:
Either correct the tool output or the tool descriptor definition in the model so that the modeled output parameters match the actual tool output.
Parent topic: AWM MVS system (TSMVS) messages


AWM SVN integration (TSSVN) messages

  • TSSVN0001 Failed to get an SVN property value.
Parent topic: Error messages


TSSVN0001 Failed to get an SVN property value.

Failed to read an SVN property value.

User Response:
Check the error log for more information.
Parent topic: AWM SVN integration (TSSVN) messages


AWM UI (TSUIN) messages

  • TSUIN0001 The file {0} has been changed\n\nDo you want to save your changes before performing a local syntax check?
  • TSUIN0002 Exception when trying to add a new filter.
  • TSUIN0003 Error opening view {0} .
  • TSUIN0004 Error resolving filter.
  • TSUIN0005 Interruption resolving filter.
  • TSUIN0006 Exception when trying to get resource {0} .
  • TSUIN0007 Failed to re-open an editor from the resource: {0} .
  • TSUIN0008 The output file {0} could not be opened.
  • TSUIN0009 Opening editor for file {0} was interrupted.
  • TSUIN0010 No application active. Please load one.
  • TSUIN0011 Failed to open the internal project while allocating the output file.
  • TSUIN0012 Could not open the editor.
  • TSUIN0013 Compare failed while trying to get the file content.
  • TSUIN0014 Compare failed due to an I/O error.
  • TSUIN0016 Failed to execute the integrated tool EditOpener. The file descriptor {0} must be a workspace file descriptor.
  • TSUIN0017 File does not exist.
  • TSUIN0018 Failed to retrieve the editor (IEditorPart) for the opened file. Save- and close-operations will not work properly. {0} If an external editor was opened, you should check your file associations (Eclipse preferences).
  • TSUIN0019 Interrupted exception while waiting for platform UI initialization.
  • TSUIN0021 Failed to find the local file for Element {0} .
  • TSUIN0024 An error occurred when trying to load the file ft_openfiles.xml.
  • TSUIN0025 An error occurred when trying to save the file ft_openfiles.xml.
  • TSUIN0026 CoreException during save action.
  • TSUIN0027 Failed to open the view with the ID {0} .
  • TSUIN0028 Active editor contents can only be obtained from ITextEditors.
  • TSUIN0029 Failed to close open editors.
  • TSUIN0030 Exception occurred when saving the element information.
  • TSUIN0031 Configuration error: The tool descriptor {0} needs a ISA PlugIn attribute, because its tool type is {1} .
  • TSUIN0032 The plug-in ID {0} for tool descriptor {1} is invalid for the tool type {2} .
  • TSUIN0033 Missing file input parameter for integrated tool EditOpener.
  • TSUIN0034 The file input parameter for the EditOpener contains no physical name.
  • TSUIN0036 The action has been interrupted.
  • TSUIN0037 Failed to delete cached files.
  • TSUIN0038 Exception when trying to get the value for property {0} .
  • TSUIN0039 Please insert a filter name.
  • TSUIN0040 Exception when trying to get the application folder.
  • TSUIN0041 Core Exception when trying to read the job card file.
  • TSUIN0042 IO Exception when trying to read the job card file.
  • TSUIN0043 Exception when trying to write the job card file.
  • TSUIN0044 Core Exception when trying to write the job card file.
  • TSUIN0045 IO Exception when trying to write the job card file.
  • TSUIN0047 Failed to retrieve values for Property {0} .
  • TSUIN0048 Failed to resolve dependent value references.
  • TSUIN0049 Error while reading the output file {0} .
  • TSUIN0050 Output file not found in parameter memory: {0} .
  • TSUIN0051 Unable to set a value for output field {0} .
  • TSUIN0052 Input file for parameter {0} could not be retrieved.
  • TSUIN0053 No properties defined for file descriptor {0} .
  • TSUIN0054 Input file for selection table was not found.
  • TSUIN0055 Input file for selection table could not be read.
  • TSUIN0057 Value for property {0} not found.
  • TSUIN0058 Missing attribute in global editor action: Keyword.
  • TSUIN0059 Failed to parse key word for editor action.
  • TSUIN0060 Failed to save the column configurations.
  • TSUIN0061 Failed to save the column configurations.
  • TSUIN0062 Failed to load the column user settings.
  • TSUIN0063 Error resolving filter.
  • TSUIN0064 Interruption exception while resolving filter.
  • TSUIN0066 Failed to open the file {0} .
  • TSUIN0067 Found a matching editor ( {0} ) but failed to open it.
  • TSUIN0068 Failed to retrieve the physical file of editor {0} .
  • TSUIN0069 Failed to set markers for the file {0} .
  • TSUIN0070 An error occurred while trying to reload the filters.
  • TSUIN0071 Exception when trying to remove a filter.
  • TSUIN0072 Error opening view {0} .
  • TSUIN0073 Exception when trying to add a new filter.
  • TSUIN0074 An error occurred while trying to save the filters.
  • TSUIN0077 Exception when trying to load the job list.
  • TSUIN0078 Exception when trying to get the job parts.
  • TSUIN0079 No extension found for job utility.
  • TSUIN0081 Exception when trying to save the job information.
  • TSUIN0082 Exception when trying to load the job list.
  • TSUIN0084 Exception when trying to synchronize the job information.
  • TSUIN0085 Exception when trying to browse a job with the ID {0} .
  • TSUIN0086 Invalid object given: {0} .
  • TSUIN0087 Failed to get children for {0} .
  • TSUIN0088 An error occurred while searching for Workflow Manager applications.
  • TSUIN0089 The following tool messages were returned during the action:
  • TSUIN0090 No extension found for job utility.
  • TSUIN0091 Failed to delete cached jobs.
  • TSUIN0092 Failed to reset the dirty flag of the editor.
  • TSUIN0093 Failed to create a backup for file {0} .
  • TSUIN0094 Failed to save the member: {0} . A backup was made at: {1} .
  • TSUIN0095 The date format {0} of property {1} is invalid.
  • TSUIN0096 No target ID for the validate action description of tool {0} .
  • TSUIN0098 The first file input parameter of the integrated tool FileCompare with the ID {0} must be of type MVSSEQ or MVSPO_MEMBER or WORKSPACE_FILE.
  • TSUIN0099 Failed to execute the integrated tool FileCompare. The first file descriptor {0} must be a workspace file descriptor or the EDIT flag must be set to false.
  • TSUIN0100 The integrated tool FileCompare with the ID {0} must have exactly two file input parameter but only {1} were found.
  • TSUIN0101 The integrated tool FileCompare with the ID {0} must have two modelled file input parameters unless it is modelled within a mass processing action with two selected elements, in which case one file input parameter is required.
  • TSUIN0102 The integrated file compare tool {0} requires two selected resources in order to work in a mass processing action, while only {1} resources were found in the context.
  • TSUIN0103 The integrated tool FileCompare was modelled incorrectly. Either two file input parameters must be modelled or the tool must be called within a mass processing action with exactly one modelled file input parameter. {0} Modelled file input parameters: {1}{0} Mass processing: {3}
  • TSUIN0104 Failed to restore the {0} . view
  • TSUIN0105 Execution of save action {0} failed with an exception.
  • TSUIN0106 Table views could not be cached. Failed to save tv_tableviewlists.xml.
  • TSUIN0107 Cached table views (tv_tableviewlists.xml) could not be recovered.
  • TSUIN0108 A thread was interrupted while initializing the element lists.
  • TSUIN0109 Failed to expand the system reference {0} .
  • TSUIN0110 Failed to update the application {0} .
  • TSUIN0111 Failed to create a system reference.
  • TSUIN0112 Exception when trying to refresh the system.
  • TSUIN0113 Failed to associate a remote system.
  • TSUIN0114 An error occurred while storing the containers.
  • TSUIN0115 Failed to expand the Tree View to its previous state.
  • TSUIN0116 Failed to expand the system {0} .
  • TSUIN0117 Following z/Server processes are still running: {0}{1}{0} Please close these processes first.
  • TSUIN0118 Exception occurred when trying to load the application.
  • TSUIN0119 The local file {0} doesnt exist.
  • TSUIN0120 Compare failed while trying to set the file content
  • TSUIN0121 Failed to delete the element list {0} .
  • TSUIN0122 Failed to get children for
  • TSUIN0123 Failed to create the resource list because the file descriptor \ {0} \ does not have the type \Input Stream\.
  • TSUIN0124 Failed to get system proxies from provider \ {0} \.
  • TSUIN0125 Failed to synchronize AWM element on resource change event for resource:
  • TSUIN0126 At least one exception occurred during initialization of the AWM meta model. See error log for more information.
  • TSUIN0127 Failed to get remote system images from system provider \ {0} \.
  • TSUIN0128 Failed to remove cached elements.
  • TSUIN0129 Failed to remove cached filters.
  • TSUIN0130 Handler not found for command: {0} .
  • TSUIN0131 An error occurred while executing the command handler \ {0} \.
  • TSUIN0132 Missing target directory for the tool {0} .
  • TSUIN0133 The link path input parameter must be set to type MassProcessing in tool {0} .
  • TSUIN0134 The filename input parameter muss be set to type MassProcessing in tool {0} .
  • TSUIN0135 The link path input parameter must be set to type MassProcessing in tool {0} .
  • TSUIN0136 The mass input parameters of tool {0} don't have the same size.
  • TSUIN0137 The resource type parameter value {0} is invalid for tool {1} . Valid values are FOLDER or FILE.
  • TSUIN0138 Resource type parameter missing for tool {0} . Valid values are FOLDER or FILE.
  • TSUIN0139 Resource identification for tool {0} failed.
  • TSUIN0140 Missing resources for MassProcessing tool {0} .
  • TSUIN0141 Parameters from USER_INPUT are not allowed for mass processing input parameters. Please change the parameter from attribute of parameter # {0} either to Context or Previous Tool.
  • TSUIN0142 The value of the attribute {0} of the tool {1} cannot be determined.
  • TSUIN0143 The project containing the resource {0} is closed.
  • TSUIN0144 The resource path \ {0} \ cannot be resolved to an Eclipse resource.
  • TSUIN0145 The Tool {0} needs {1} input parameters and {2} output parameters
  • TSUIN0146 The resource(s) {0} already exist(s).
  • TSUIN0147 Existing resource handling parameter missing. Valid values are REPLACE, IGNORE or ERROR.
  • TSUIN0148 The existing resource handling parameter value {0} is invalid. Valid values are REPLACE, IGNORE or ERROR.
  • TSUIN0149 Mass processing not allowed for tool {0} .
  • TSUIN0150 At least one output parameter of type FILE must be defined for tool {0} .
  • TSUIN0151 The file output parameter is not modeled for tool {0} .
  • TSUIN0152 The value of the attribute {0} of the tool {1} cannot be determined.
  • TSUIN0153 Values of attributes {0} and/or {1} of the tool {2} cannot be determined.
  • TSUIN0154 The value of the attribute {0} of the tool {1} is set to false but the 2nd input parameter is not configured.
  • TSUIN0155 A resource must be specified where clipboard contents should be copied.
  • TSUIN0156 There are no contents in clipboard or the clipboard contents cannot be pasted to the selected resource.
  • TSUIN0157 Selection resource type parameter is missing from Eclipse tool {0} . Valid values are FILE, FOLDER, PROJECT or ANY.
  • TSUIN0158 The existing resource type parameter value {0} is invalid for tool {1} . Valid values are FILE, FOLDER, PROJECT or ANY.
  • TSUIN0159 Tool {0} does not allow mass processing.
  • TSUIN0160 The given wizard ID in {0} cannot be found in the New Wizard registry.
  • TSUIN0161 An exception occurred while executing a custom error feedback action.
  • TSUIN0162 Cannot set value \ {0} \ for property \{1} \ because the resource identifier is missing.
  • TSUIN0163 Failed to set the \EDITABLE\ linked property value. Linked property ID: \ {0} \.
  • TSUIN0164 Unable to get Eclipse file store for resource \ {0} \.
  • TSUIN0165 Compare failed while trying to get the file content.
  • TSUIN0166 Compare failed while trying to set the file content.
  • TSUIN0167 Failed to open or activate the table view with the secondary ID:
  • TSUIN0168 The file type {0} is not supported by {1} .
  • TSUIN0169 Eclipse element synchronizer: Failed to delete element \ {0} \.
  • TSUIN0170 Eclipse element synchronizer: Failed to refresh children of the resource \ {0} \.
  • TSUIN0171 Eclipse element synchronizer: Failed to refresh the file cache after synchronization.
  • TSUIN0172 Eclipse element synchronizer: Failed to find elements that are out of sync with the Eclipse workspace.
  • TSUIN0173 Eclipse element synchronizer: Failed to delete the element list entry \ {0} \.
  • TSUIN0174 Eclipse element synchronizer: Failed to delete element list entry for removed resource \ {0} \.
  • TSUIN0175 Eclipse element synchronizer: Failed to refresh element \ {0} \.
  • TSUIN0176 Eclipse element synchronizer: Failed to refresh element \ {0} \.
  • TSUIN0177 Handler not found for: {0}
  • TSUIN0178 The key sequence \ {0} \ of action descriptor \{1} \ is invalid.
Parent topic: Error messages


TSUIN0001 The file {0} has been changed\n\nDo you want to save your changes before performing a local syntax check?

This is a confirmation dialog message.

User Response:
Reply OK or Cancel.
Parent topic: AWM UI (TSUIN) messages


TSUIN0002 Exception when trying to add a new filter.

The new filter action failed with an exception.

Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0003 Error opening view {0} .

The filter view could not be opened.

User Response:
Open the filter view from the Eclipse Menu Bar: Window --> Show View --> Other... --> Micro Focus Team Developer --> Filter Definitions and retry.
Parent topic: AWM UI (TSUIN) messages


TSUIN0004 Error resolving filter.

The filter action failed with an exception.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0005 Interruption resolving filter.

The filter action was interrupted.

User Response:
Retry the action.
Parent topic: AWM UI (TSUIN) messages


TSUIN0006 Exception when trying to get resource {0} .

When an application is loaded, all files which were open at the time when the application was unloaded will be re-opened in the editor based on the information in the cache. For the given element, the re-open failed because no entry could be found in the cache. Most probably the cached information is inconsistent.

User Response:
Remove the file ft_openfiles.xml from the application folder in the internal project folder. See Troubleshooting for more information on how to remove the cached information.
Parent topic: AWM UI (TSUIN) messages
Related information
Troubleshooting


TSUIN0007 Failed to re-open an editor from the resource: {0} .

When an application is loaded, all files which were open at the time when the application was unloaded will be re-opened in the editor based on the information in the cache. For the given element, the re-open failed because no entry could be found in the cache. Most probably the cached information is inconsistent. The workspace may have been switched between unload and load of the application.

User Response:
Remove the file ft_openfiles.xml from the application folder in the internal project folder. See Troubleshooting for more information on how to remove the cached information.
Parent topic: AWM UI (TSUIN) messages
Related information
Troubleshooting


TSUIN0008 The output file {0} could not be opened.

Opening the given file in the editor failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: AWM UI (TSUIN) messages


TSUIN0009 Opening editor for file {0} was interrupted.

Opening the given file in the editor was interrupted.

User Response:
Retry the action.
Parent topic: AWM UI (TSUIN) messages


TSUIN0010 No application active. Please load one.

An attempt was made to open an output file when no AWM application was loaded.

User Response:
Load the corresponding AWM application and try the action again.
Parent topic: AWM UI (TSUIN) messages


TSUIN0011 Failed to open the internal project while allocating the output file.

The internal project folder could not be opened for the creation of an output file.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the Administrator.
Model Administrator Response:
Check the error log for more information. If necessary, contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0012 Could not open the editor.

An attempt was made to open an output file in the editor; but the editor cannot be opened.

User Response:
See the message under "Reason:" in the message dialog. If necessary contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0013 Compare failed while trying to get the file content.

An I/O exception occurred during the compare action reading the files to be compared.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0014 Compare failed due to an I/O error.

An I/O exception occurred during the compare action reading the files to be compared.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0016 Failed to execute the integrated tool EditOpener. The file descriptor {0} must be a workspace file descriptor.

The execution of the integrated tool EditOpener failed because the file descriptor was not declared as type workspace file descriptor.

Model Administrator Response:
Verify the type of the file descriptor associated as input parameter with the integrated tool EditOpener. The file descriptor must be of type Workspace_File.
Parent topic: AWM UI (TSUIN) messages


TSUIN0017 File does not exist.

The file to be opened in the editor could not be found in the workspace on the expected path. A possible cause is that the workspace was switched since the last edit of the file.

Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0018 Failed to retrieve the editor (IEditorPart) for the opened file. Save- and close-operations will not work properly. {0} If an external editor was opened, you should check your file associations (Eclipse preferences).

The editor which should be used to open the selected file could not be determined. The consequence is that save and close actions won't work properly. Probably there is a file association missing for this file's extension in the Eclipse preferences.

User Response:
Verify that the file association is set correctly for the file's extension in the Eclipse preferences. If not, add a file association for the extension. Otherwise see the message under "Reason:" in the message dialog. If necessary contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0019 Interrupted exception while waiting for platform UI initialization.

The platform UI initialization process was interrupted.

User Response:
Retry the action.
Parent topic: AWM UI (TSUIN) messages


TSUIN0021 Failed to find the local file for Element {0} .

The file for the given element to be opened in the editor could not be found in the workspace at the expected path. The workspace may have been switched since the last edit of the file.

Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0024 An error occurred when trying to load the file ft_openfiles.xml.

Files which are open locally when an application is unloaded are persistently stored in the workspace file ft_openfiles.xml. This file could not be loaded when the application is loaded again. The workspace may have been switched between unload and reload of the application.

User Response:
If the files need not be opened again, ignore the message. Otherwise, if the cause is a workspace switch, change the workspace back. If this does not help, see the message under "Reason:" in the message dialog. If this does not help either, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0025 An error occurred when trying to save the file ft_openfiles.xml.

All files which are open locally when an application is unloaded are persistently stored in the workspace file ft_openfiles.xml. This file could not be saved in the workspace.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0026 CoreException during save action.

A modeled save action was executed when a file was saved. This save action failed.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0027 Failed to open the view with the ID {0} .

The opening of one of the Team Developer views failed.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0028 Active editor contents can only be obtained from ITextEditors.

An action tried to read the content of the active editor (e.g. an action using the editor content to submit it as a job). This is only possible if the editor is a text editor.

User Response:
If possible, change the type of the edited file to a type which is opened with a text editor.
Parent topic: AWM UI (TSUIN) messages


TSUIN0029 Failed to close open editors.

When the workbench is shut down, all open remote AWM files are closed. This close failed.

User Response:
Determine why the close of the files failed. Ensure that close actions which were not executed are processed manually (e.g. unlock a member in the SCM system).
Parent topic: AWM UI (TSUIN) messages


TSUIN0030 Exception occurred when saving the element information.

When an application is unloaded or the Eclipse workbench is closed, the AWM elements are stored permanently in the workspace. This element's save action has failed. When the element information cannot be saved, no element lists for this application can be restored in the next Eclipse session.

User Response:
See the message under "Reason:" in the message dialog. If this doesn't help, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0031 Configuration error: The tool descriptor {0} needs a ISA PlugIn attribute, because its tool type is {1} .

The given tool which is configured as a UI tool (SWTDIALOG) doesn't have an ISA_PlugIn relation attribute.

Model Administrator Response:
Add the required ISA_PlugIn relation attribute to the given tool in the model file.
Parent topic: AWM UI (TSUIN) messages


TSUIN0032 The plug-in ID {0} for tool descriptor {1} is invalid for the tool type {2} .

The given tool descriptor contains an invalid plug-in ID for the given tool type in the ISA_PlugIn relation attribute. Permitted plugin IDs for tools of tool type SWTDIALOG are "de.soforte.taurus.inputdialog" or "de.soforte.taurus.outputdialog".

Model Administrator Response:
Correct the plug-in ID for the given tool in its ISA_PlugIn relation attribute.
Parent topic: AWM UI (TSUIN) messages


TSUIN0033 Missing file input parameter for integrated tool EditOpener.

The integrated tool EditOpener needs an input parameter of type file. This input parameter is missing.

Model Administrator Response:
Add the missing file input parameter to the integrated tool EditOpener.
Parent topic: AWM UI (TSUIN) messages


TSUIN0034 The file input parameter for the EditOpener contains no physical name.

In the file input parameter for the integrated tool EditOpener, the value for the attribute "physical name" is missing.

Model Administrator Response:
Add the physical name in the file input parameter of the integrated tool EditOpener in the model file.
Parent topic: AWM UI (TSUIN) messages


TSUIN0036 The action has been interrupted.

The current action has been interrupted by the user.

User Response:
Try the action again.
Parent topic: AWM UI (TSUIN) messages


TSUIN0037 Failed to delete cached files.

The deletion of the file cache failed during the execution of the Clear Cache action for an application.

User Response:
  • See the message under "Reason:" in the message dialog.
  • See Troubleshooting for more information on how to delete the cache.
Parent topic: AWM UI (TSUIN) messages
Related information
Troubleshooting


TSUIN0038 Exception when trying to get the value for property {0} .

The value for a property which is part of a table within a dialog could not be determined.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0039 Please insert a filter name.

A filter definition always needs a filter name. The filter name is empty.

User Response:
Enter a name for the filter.
Parent topic: AWM UI (TSUIN) messages


TSUIN0040 Exception when trying to get the application folder.

The application folder within the internal project folder could not be determined.

User Response:
See the message under "Reason:" in the message dialog. See Troubleshooting for more help. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages
Related information
Troubleshooting


TSUIN0041 Core Exception when trying to read the job card file.

The file which contains the user specific job card settings could not be read from the internal project folder in the workspace.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0042 IO Exception when trying to read the job card file.

The file which contains the user specific job card settings could not be read from the internal project folder in the workspace.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0043 Exception when trying to write the job card file.

The values obtained from the job card dialog could not be written to the file which contains the user specific job card settings in the internal project folder in the workspace.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0044 Core Exception when trying to write the job card file.

The values obtained from the job card dialog could not be written to the file which contains the user specific job card settings in the internal project folder in the workspace.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0045 IO Exception when trying to write the job card file.

The values obtained from the job card dialog could not be written to the file which contains the user specific job card settings in the internal project folder in the workspace.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0047 Failed to retrieve values for Property {0} .

The retrieve tool for the given property failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Verify that the retrieve tool is correctly implemented and configured in the model file. Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0048 Failed to resolve dependent value references.

Property dependent values were modeled in the "Value_Keys" attribute of a Select_Value Property but could not be resolved.

Model Administrator Response:
Verify that the Value_Keys of the corresponding property are modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0049 Error while reading the output file {0} .

A file destined for an output dialog could not be read.

Model Administrator Response:
  • Verify that the corresponding tool executed before the output dialog returns the file name correctly.
  • Enable the client trace and verify that the returned file name is mapped to the correct file output parameter.
  • Verify that the user has read access to the file.
Parent topic: AWM UI (TSUIN) messages


TSUIN0050 Output file not found in parameter memory: {0} .

A file descriptor for a file output field (output dialog) was not found. This may be caused by a tool executor which did not save an output parameter correctly into the parameter memory. This is an internal problem if no custom tool executor (tool type) was used.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0051 Unable to set a value for output field {0} .

A property for an output field (output dialog) was not found. This may be caused by a tool executor which did not save an output parameter correctly into the parameter memory. This is an internal problem if no custom tool executor (tool type) was used.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0052 Input file for parameter {0} could not be retrieved.

A file input parameter with the attribute "Parameter_From = Previous_Tool" was modeled for an Input Dialog but the file descriptor was not found in the parameter memory.

Model Administrator Response:
Verify that the action is modeled correctly (see Troubleshooting).
Parent topic: AWM UI (TSUIN) messages
Related information
Troubleshooting


TSUIN0053 No properties defined for file descriptor {0} .

A file input parameter was modeled for an input dialog which refers to a file descriptor with the attribute "Structure = Table". There are no properties defined for the file descriptor.

Model Administrator Response:
Add "has Property" relationships to the corresponding file descriptor or set its "Structure" attribute to "Unstructured".
Parent topic: AWM UI (TSUIN) messages


TSUIN0054 Input file for selection table was not found.

There is a file input parameter declared as input for a dialog table. The file with the content for the table could not be determined. This is probably a modeling error.

Model Administrator Response:
Verify that the corresponding file descriptor has the correct type and optionally the correct physical name. See the information about modeling problems in Application Workflow Manager Problem Determination for further helpful hints.
Parent topic: AWM UI (TSUIN) messages
Related information
Application Workflow Manager Problem Determination


TSUIN0055 Input file for selection table could not be read.

There is a file input parameter declared as input for a dialog table. The file with the content for the table could not be read. This might be a modeling error.

Model Administrator Response:
Verify that the corresponding file descriptor has the correct type and optionally the correct physical name. See the information about modeling problems in Application Workflow Manager Problem Determination for further helpful hints.
Parent topic: AWM UI (TSUIN) messages
Related information
Application Workflow Manager Problem Determination


TSUIN0057 Value for property {0} not found.

There is a file input parameter declared as input for a dialog table. At least one line of the file content does not deliver a value for every property associated with the file descriptor.

Model Administrator Response:
Verify the output file of the tool delivering the content for the dialog table. Ensure that the tool delivers at least as many values as properties are configured for the file descriptor.
Parent topic: AWM UI (TSUIN) messages


TSUIN0058 Missing attribute in global editor action: Keyword.

A global action with an ISA_Editor_Action relation defined in the model file has a SelectionProppertyMapping relation assigned with ValueFrom set to SelectedKeyword. But the value of the keyword is not set.

Model Administrator Response:
Set the value of the attribute Keyword in the global editor action's SelectionPropertyMapping relation (e.g. COBOL-COPYBOOK).
Parent topic: AWM UI (TSUIN) messages


TSUIN0059 Failed to parse key word for editor action.

There is a global action with an ISA_Editor_Action relation defined in the model file. A SelectionPropertyMapping relation is assigned to this editor action with ValueFrom set to SelectedKeyword. The value under the Keyword attribute in the SelectionPropertyMapping relation does not have the expected format.

Model Administrator Response:
Correct the value in the Keyword attribute of the SelectionPropertyMapping relation. Correct values are: COBOL-COPYBOOK, COBOL-INCLUDE or PLI-INCLUDE.
Parent topic: AWM UI (TSUIN) messages


TSUIN0060 Failed to save the column configurations.

When an application is unloaded or the Eclipse workbench is closed, the column settings for the Table View are stored in the local workspace. This save action failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0061 Failed to save the column configurations.

When an application is unloaded or the Eclipse workbench is closed, the column settings for the Table View are stored in the local workspace. This save action failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0062 Failed to load the column user settings.

When an application is unloaded or the Eclipse workbench is closed, the column settings for the Table View are stored in the local workspace. When the application is loaded again, the column settings are restored from this saved file. The restore of the column settings failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0063 Error resolving filter.

The refresh button was pressed in the Table View on an element list created by a filter. This caused the filter action to be called. The filter action failed.

User Response:
Verify if there is a network problem. See the message under "Reason:" in the message dialog. If this doesn't help, contact the administrator.
Parent topic: AWM UI (TSUIN) messages


TSUIN0064 Interruption exception while resolving filter.

The refresh button was pressed in the Table View on an element list created by a filter. This caused the filter action to be called, which was interrupted by the user.

User Response:
This is an informational message.
Parent topic: AWM UI (TSUIN) messages


TSUIN0066 Failed to open the file {0} .

When an entry in the Error Feedback view is double-clicked, the corresponding source member should be opened in the editor. The open of the file failed.

User Response:
Verify that the Location and Resource entry in the Error Feedback view point to the location of the source member. If this is not the case, it might be an error in the error feedback tool. In this case, contact the administrator.
Model Administrator Response:
Verify that the error feedback tool returns the correct location of the source member. Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0067 Found a matching editor ( {0} ) but failed to open it.

When an error feedback entry is double-clicked, the editor for the corresponding source file should be opened. The editor associated with the file type could be determined, but the open failed.

User Response:
Verify if the correct file association is defined for the source member in the Eclipse preferences. See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0068 Failed to retrieve the physical file of editor {0} .

When an error feedback entry is double-clicked, the editor for the corresponding source file should be opened. Opening of the editor failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0069 Failed to set markers for the file {0} .

When an error feedback entry is double-clicked, the editor for the corresponding source file should be opened and the syntax errors marked with editor markers. The setting of the editor markers failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0070 An error occurred while trying to reload the filters.

When an application is loaded, the filter information of the application is reloaded from the cache in the workspace. This reload failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0071 Exception when trying to remove a filter.

The remove action on a filter failed with an exception.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0072 Error opening view {0} .

When a filter is executed, the Element Table View is opened to display the result of the filter action. The opening of the Element Table View failed.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0073 Exception when trying to add a new filter.

A filter which is defined by the user is added to the internal filter list. The new filter list is stored into the user's cache in the workspace. This add filter action ended with an exception.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0074 An error occurred while trying to save the filters.

When an application is unloaded or the Eclipse workbench is closed the filter information is stored into the user's workspace. The save of the filters failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0077 Exception when trying to load the job list.

When the Job View is initiated, the job list input is loaded from the cache in the workspace. This load failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0078 Exception when trying to get the job parts.

When the Go Into action is selected on a job in the Job View, the parts of the job (DDs) are retrieved from the remote system. This retrieve failed.

User Response:
See the message under "Reason:" in the message dialog. Check if the job still exists on the remote system. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0079 No extension found for job utility.

The job utility is integrated by the Eclipse extension point de.soforte.taurus.jobutil. No extension for this extension point could be found.

Model Administrator Response:
If the job utilities are integrated by a customer extension, verify that the extension point id is spelled correctly in the plugin.xml. Otherwise contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0081 Exception when trying to save the job information.

When an application is unloaded or the Eclipse workbench is closed, the job information is stored into the user's workspace. The save of the job information failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0082 Exception when trying to load the job list.

When an application is loaded, the job information of the application is reloaded from the cache in the workspace. This reload failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0084 Exception when trying to synchronize the job information.

The refresh action in the Jobs view failed with an exception.

User Response:
Verify if there is a network problem. See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0085 Exception when trying to browse a job with the ID {0} .

The browse of the given job failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0086 Invalid object given: {0} .

This is an internal exception. A message has been called with an object with an invalid type.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0087 Failed to get children for {0} .

An exception occurred when a branch was expanded in the Tree View.

User Response:
See the message under "Reason:" in the message dialog.
Model Administrator Response:
Check the server logs for more information. Validate that the modeled GetChildren action for the corresponding element type works correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0088 An error occurred while searching for Workflow Manager applications.

An exception occurred when a system reference was expanded in the Tree View.

User Response:
See the message under "Reason:" in the message dialog.
Model Administrator Response:
Check the server logs for more information. Validate that the REXX TAULAPPL and TAUZCAPP respectively work correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0089 The following tool messages were returned during the action:

This is a summary of all tool messages which were issued by one of the tools which were executed when the last action was performed.

User Response:
Check the tool responses.
Parent topic: AWM UI (TSUIN) messages


TSUIN0090 No extension found for job utility.

The job utility is integrated via an Eclipse extension point. No extension for this extension point was found in the workbench.

Model Administrator Response:
If the job utility is integrated using a customer written extension, verify that the extension point ID (de.soforte.taurus.jobutil) is correctly spelled in the extension definition. Otherwise contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0091 Failed to delete cached jobs.

During the execution of the Clear Cache action for an application, the deletion of the job cache failed.

User Response:
  • See the message under "Reason:" in the message dialog.
  • See Troubleshooting for more information on how to delete the cache.
Parent topic: AWM UI (TSUIN) messages
Related information
Troubleshooting


TSUIN0092 Failed to reset the dirty flag of the editor.

The save of an edited file failed, as did the reset of the dirty flag of the editor.

User Response:
Temporarily save the changes in the editor so that they are not lost (e.g. by cutting/pasting the editor contents into a temporary local file). Determine why the edited file could not be saved.
Parent topic: AWM UI (TSUIN) messages


TSUIN0093 Failed to create a backup for file {0} .

The save of an edited file failed, as did the backup of the recovery file.

User Response:
Temporarily save the changes in the editor so that they are not lost (e.g. by cutting/pasting the editor contents into a temporary local file). Determine why the edited file could not be saved.
Parent topic: AWM UI (TSUIN) messages


TSUIN0094 Failed to save the member: {0} . A backup was made at: {1} .

Saving an edited file failed. Therefore a backup of the file was written to the named path.

User Response:
Determine why the save of the file failed.
Parent topic: AWM UI (TSUIN) messages


TSUIN0095 The date format {0} of property {1} is invalid.

A date format attribute of a property in the model contains an invalid value.

Model Administrator Response:
Correct the date format attribute of the property in the model.
Parent topic: AWM UI (TSUIN) messages


TSUIN0096 No target ID for the validate action description of tool {0} .

The validation action which is associated with the tool descriptor {0} does not have a target ID.

Model Administrator Response:
Check the model configuration (see description).
Parent topic: AWM UI (TSUIN) messages


TSUIN0098 The first file input parameter of the integrated tool FileCompare with the ID {0} must be of type MVSSEQ or MVSPO_MEMBER or WORKSPACE_FILE.

Self-explanatory.

Model Administrator Response:
Check the model configuration (see Message).
Parent topic: AWM UI (TSUIN) messages


TSUIN0099 Failed to execute the integrated tool FileCompare. The first file descriptor {0} must be a workspace file descriptor or the EDIT flag must be set to false.

The execution of the integrated tool FileCompare failed because the file descriptor was not declared as type workspace file descriptor.

Model Administrator Response:
Verify the type of the file descriptor associated as input parameter with the integrated tool FileCompare. The file descriptor must be of type Workspace_File.
Parent topic: AWM UI (TSUIN) messages


TSUIN0100 The integrated tool FileCompare with the ID {0} must have exactly two file input parameter but only {1} were found.

The integrated tool FileCompare must be modeled with exactly two file input parameters. There were more or fewer file input parameters found for the integrated tool FileCompare.

Model Administrator Response:
Correct the input parameters for the integrated tool FileCompare in the model file.
Parent topic: AWM UI (TSUIN) messages


TSUIN0101 The integrated tool FileCompare with the ID {0} must have two modelled file input parameters unless it is modelled within a mass processing action with two selected elements, in which case one file input parameter is required.

A "FileCompare" integrated tool was not properly modeled.

Model Administrator Response:
Either model the "FileCompare" tool descriptor with two file input parameters and use it within a single processing action descriptor ("MassProcessing = false"), or model a single file input parameter and use the tool in a mass processing action descriptor ("MassProcessing = true").
Parent topic: AWM UI (TSUIN) messages


TSUIN0102 The integrated file compare tool {0} requires two selected resources in order to work in a mass processing action, while only {1} resources were found in the context.

A FileCompare tool descriptor was modeled for a multi selection (e.g. "Compare With Each Other") but only one resource was selected during execution.

Model Administrator Response:
Add a enabled condition to the "Element has Action" relationship in which the tool descriptor is being called and set the "Selection Count" attribute of the condition to "2".
Parent topic: AWM UI (TSUIN) messages


TSUIN0103 The integrated tool FileCompare was modelled incorrectly. Either two file input parameters must be modelled or the tool must be called within a mass processing action with exactly one modelled file input parameter. {0} Modelled file input parameters: {1}{0} Mass processing: {3}

A "FileCompare" integrated tool was not properly modeled.

Model Administrator Response:
Either model the "FileCompare" tool descriptor with two file input parameters and use it within a single processing action descriptor ("MassProcessing = false"), or model a single file input parameter and use the tool in a mass processing action descriptor ("MassProcessing = true").
Parent topic: AWM UI (TSUIN) messages


TSUIN0104 Failed to restore the {0} . view

A Team Developer view could not be restored. This is most probably caused by an internal exception.

User Response:
Try to open the view manually (Window -> Show View...). If this does not help clear your cache and restart the client.
Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0105 Execution of save action {0} failed with an exception.

The execution of a modeled save action (action descriptor attribute) failed with an exception. This is a top level exception, additional information (exceptions) should be printed

Model Administrator Response:
Check the error log for a more specific error message.
Parent topic: AWM UI (TSUIN) messages


TSUIN0106 Table views could not be cached. Failed to save tv_tableviewlists.xml.

The state of opened AWM table views could not be saved. This can be caused by an asynchronous Eclipse work space.

User Response:
Refresh the internal application folder.
Parent topic: AWM UI (TSUIN) messages


TSUIN0107 Cached table views (tv_tableviewlists.xml) could not be recovered.

Failed to load the cached state of AWM table views. This can be caused by an asynchronous Eclipse work space.

User Response:
  • Refresh the internal application folder.
  • Delete the tv_tableviewlists.xml cache file manually from the internal application folder.
Parent topic: AWM UI (TSUIN) messages


TSUIN0108 A thread was interrupted while initializing the element lists.

This is an internal program exception which can occur while the cached state of AWM table views is being loaded.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0109 Failed to expand the system reference {0} .

The expand state of a cached system reference could not be restored after the client was restarted. This was most probably caused by a model update or an inconsistent model.

User Response:
Restart the client to see if the error occurs a second time. If it does, delete and re-add the system from the tree view.
Parent topic: AWM UI (TSUIN) messages


TSUIN0110 Failed to update the application {0} .

This is a high level exception which occurs if updating the model of an application fails. Possible reasons include:

  • The application could not be loaded with the new model (e.g. the model is invalid).
  • The application could not be unloaded (e.g. cache could not be saved). A more detailed exception should be found in the error log.
User Response:
  • Check the error log for a more detailed exception.
  • Clear your cache and try to update your model manually (both context menu functions of the application in the Tree View).
Model Administrator Response:
  • Verify that the new model is valid and can be loaded by clients.
  • Verify that the model is compatible with the Workflow Manager version of the client.
Parent topic: AWM UI (TSUIN) messages


TSUIN0111 Failed to create a system reference.

An exception occurred during the creation of a system reference. Since this is a top-level exception, more details are usually to be found in the error details. Possible reasons are:

  • The internal project has become asynchronous to Eclipse.
  • The client installation is inconsistent (conflicting plug-ins).
  • A master configuration could not be received or parsed.
User Response:
  • Open the Navigator view and refresh the internal project (right click -> Refresh) and retry the action.
  • If the problem appears to be related to the remote system connection, verify your network connection to the specific system and check your connection definition (host name, port). Model administrator response: If the problem appears to have being caused while the Master Configuration was been parsed, verify the configuration itself and correct any inconsistencies. Usually a more detailed message can be found among the error details.
Server Administrator Response:
If the master configuration file is provided by a remote system, verify that the server is up and running correctly. Verify that all customization steps in the server Installation Guide concerning the location and customization of the Master Configuration file are done correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0112 Exception when trying to refresh the system.

The system reference could not be refreshed properly, meaning that the underlying applications could not be updated by reading the corresponding master configuration. A more detailed exception can usually be found in the error details.

User Response:
If the target system is remote, check your network connection and configuration in the client (host name, port).
Model Administrator Response:
Verify that the master configuration for the corresponding system is valid.
Server Administrator Response:
If the master configuration file is provided by a remote system, verify that the server is up and running correctly. Verify that all customization steps in the server Installation Guide concerning the location and customization of the Master Configuration file are done correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0113 Failed to associate a remote system.

Associating a remote system to a local system reference failed. This is most probably caused by a corrupt client installation (Eclipse plug-in problems).

User Response:
Restart the client with the -clean option and retry the action.
Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0114 An error occurred while storing the containers.

The current state of the Tree View could not be saved into the cache. The reason for this is most likely Eclipse being out of sync with the local file system.

Model Administrator Response:
Refresh the internal project from the Navigator View and restart the client. If the problem still occurs, contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0115 Failed to expand the Tree View to its previous state.

The Tree View could not be expanded to its previous state after Eclipse was restarted. Possible reasons are:

  • Corrupt cache files.
  • Inconsistent model.
  • Asynchronous Eclipse workspace.
  • Internal exceptions.
User Response:
Expand the Tree View elements manually.
Model Administrator Response:
  • Check the error log for more information.
  • Verify that all Element Types and ID definitions in your models are consistent.
  • Contact Customer Support.
Parent topic: AWM UI (TSUIN) messages


TSUIN0116 Failed to expand the system {0} .

An internal error occurred while the Tree View was being refreshed.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0117 Following z/Server processes are still running: {0}{1}{0} Please close these processes first.

Loading an application failed because certain processes are still being executed in the active application.

User Response:
Close the cited processes and retry loading the application.
Parent topic: AWM UI (TSUIN) messages


TSUIN0118 Exception occurred when trying to load the application.

The selected application could not be loaded. A more accurate message can usually be found in the error details.

User Response:
If the model for the application is located on a remote system:
  • Check your network connection.
  • Check the settings of the remote system connection (host name, port).
  • Check if your code page settings (including file mappings) for the remote system connection are correct.
Model Administrator Response:
  • Verify that the application was defined correctly in the master configuration.
  • Verify that the model for the application is located on the defined path in the master configuration.
Server Administrator Response:
If the model for the application is located on the remote system, verify that the user has read access for that file.
Parent topic: AWM UI (TSUIN) messages


TSUIN0119 The local file {0} doesnt exist.

The local file with the given path could not be found on the system.

Model Administrator Response:
  • If the file's path was derived from a file descriptor in the model, verify that the value in the attribute "Name_Physical" is correct.
  • If the file path is returned by a modeled tool, verify that the tool returns the correct path name.
Parent topic: AWM UI (TSUIN) messages


TSUIN0120 Compare failed while trying to set the file content

An I/O exception occurred during the compare action setting the content of the files to be compared.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0121 Failed to delete the element list {0} .

This is a top-level exception that will be printed into the error log if any exception occurs during delete of a element list. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0122 Failed to get children for

An error occurred during the execution of a "get children" action. The ID of the parent resource of the action will be dynamically added to the message at runtime. This is a top level exception, more details are most probably provided in the error dialog.

Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0123 Failed to create the resource list because the file descriptor \ {0} \ does not have the type \Input Stream\.

A resource list could not be saved to a file descriptor, because the modeled file descriptor (usually referenced by a tool output parameter) did not have the type "Input Stream". This is a requirement of most Eclipse function package tools.

Model Administrator Response:
Set the type attribute of the file descriptor to "InputStream.
Parent topic: AWM UI (TSUIN) messages


TSUIN0124 Failed to get system proxies from provider \ {0} \.

An exception was thrown from a specific AWM system provider while getting AWM system proxies.

Model Administrator Response:
Contact SupportLine if the system provider name starts with the ID "com.microfocus".

If the system provider was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the system provider name is not known.

Parent topic: AWM UI (TSUIN) messages


TSUIN0125 Failed to synchronize AWM element on resource change event for resource:

Synchronizing a linked Eclipse AWM element failed. Synchronization is caused by Eclipse resource changes if the loaded model contains the Eclipse function package and "Background Synchronizer" is enabled (function package attribute).

Model Administrator Response:
See the error log for the original error cause.
Parent topic: AWM UI (TSUIN) messages


TSUIN0126 At least one exception occurred during initialization of the AWM meta model. See error log for more information.

The AWM meta model could not be initialized. This is usually caused by invalid function package extensions or exceptions during initialization of Eclipse and installed plug-ins.

Model Administrator Response:
See the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0127 Failed to get remote system images from system provider \ {0} \.

A system provider threw an exception while getting remote system images.

Model Administrator Response:
Contact SupportLine if the system provider name starts with the ID "com.microfocus".

If the system provider was developed internally by using the AWM API, contact the plug-in provider.

Contact SupportLine if the system provider name is not known.

Parent topic: AWM UI (TSUIN) messages


TSUIN0128 Failed to remove cached elements.

The persistent cache for modeled elements could not be deleted. This is probably caused by the Eclipse workspace being out of synchronization.

Model Administrator Response:
Refresh the internal project folder (see "Workspace Out Of Sync").

Clear the cache manually (see Clear The Persistent Cache In The Workspace).

Parent topic: AWM UI (TSUIN) messages


TSUIN0129 Failed to remove cached filters.

The persistent cache for created filters could not be deleted. This is probably caused by the Eclipse workspace being out of synchronization.

Model Administrator Response:
Refresh the internal project folder (see Workspace Out Of Sync).

Clear the cache manually (see Clear The Persistent Cache In The Workspace).

Parent topic: AWM UI (TSUIN) messages


TSUIN0130 Handler not found for command: {0} .

A command handler extension was not found. Either the plug-in containing the handler extension is not installed or the wrong handler ID was modeled.

Model Administrator Response:
Verify that a handler extension ID is required for the command. If not, remove the parameter (it is optional). If yes, verify that the plug-in containing the extension is correctly installed.
Parent topic: AWM UI (TSUIN) messages


TSUIN0131 An error occurred while executing the command handler \ {0} \.

Executing a command caused an exception. The exception is caused by the plug-in containing the command and/or command handler.

Model Administrator Response:
Contact customer support if the command handler class starts with the ID "com.microfocus" (see error log).

If the system provider was developed internally, contact the plug-in provider.

Contact SupportLine if the plug-in name is not known.

Parent topic: AWM UI (TSUIN) messages


TSUIN0132 Missing target directory for the tool {0} .

The attribute "With UI" of Eclipse tool "Copy Resource" was set to false, but the second input parameter which refers to the target directory is missing.

Model Administrator Response:
Verify that at least two input parameters are modeled for the Eclipse tool "Copy Resource".
Parent topic: AWM UI (TSUIN) messages


TSUIN0133 The link path input parameter must be set to type MassProcessing in tool {0} .

The type of the first input parameter of the Eclipse tool "Create Resource" is "MassProcessing", but the link path input parameter type is not "MassProcessing".

Model Administrator Response:
Verify that the link path input parameter type is "MassProcessing".
Parent topic: AWM UI (TSUIN) messages


TSUIN0134 The filename input parameter muss be set to type MassProcessing in tool {0} .

The type of the first input parameter of the Eclipse tool "Create Resource" is "MassProcessing", but the filename input parameter type is not "MassProcessing".

Model Administrator Response:
Verify that the filename input parameter type is "MassProcessing".
Parent topic: AWM UI (TSUIN) messages


TSUIN0135 The link path input parameter must be set to type MassProcessing in tool {0} .

The filename input parameter type of Eclipse tool "Create Resource" is "MassProcessing" while the link path input parameter type is not.

Model Administrator Response:
Verify that the link path input parameter type is "MassProcessing".
Parent topic: AWM UI (TSUIN) messages


TSUIN0136 The mass input parameters of tool {0} don't have the same size.

All input parameter of Eclipse Tool "Create Resource" with type "MassProcessing" must have the same size.

Model Administrator Response:
Verify that all input parameters with type "MassProcessing" have the same size.
Parent topic: AWM UI (TSUIN) messages


TSUIN0137 The resource type parameter value {0} is invalid for tool {1} . Valid values are FOLDER or FILE.

The attribute "Resource Type" of Eclipse tool "Create Resource" is set to "From Parameter" but the resource type input parameter value is not valid.

Model Administrator Response:
Make sure that the resource type input parameter is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0138 Resource type parameter missing for tool {0} . Valid values are FOLDER or FILE.

The attribute "Resource Type" of Eclipse tool "Create Resource" is set to "From Parameter" but the resource type input parameter value cannot be determined.

Model Administrator Response:
Make sure that the resource type input parameter is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0139 Resource identification for tool {0} failed.

No input parameters are configured for an Eclipse tool which requires at least one input parameter for the resource identification.

Model Administrator Response:
Verify that all Eclipse tools are configured properly. For Eclipse function package details, see the Workflow Manager Modelling Guide.
Parent topic: AWM UI (TSUIN) messages


TSUIN0140 Missing resources for MassProcessing tool {0} .

Eclipse resources of a MassProcessing Eclipse tool cannot be determined. This is an internal client error.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0141 Parameters from USER_INPUT are not allowed for mass processing input parameters. Please change the parameter from attribute of parameter # {0} either to Context or Previous Tool.

A modeled Eclipse tool descriptor contains a mass processing input parameter with the attribute "Parameter From = User_Input". This is an unsupported combination.

Model Administrator Response:
Change the "Parameter From" attribute of the input parameter either to "Context" or "Previous Tool".
Parent topic: AWM UI (TSUIN) messages


TSUIN0142 The value of the attribute {0} of the tool {1} cannot be determined.

An attribute value of a modeled Eclipse tool cannot be determined. This is an internal client error.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0143 The project containing the resource {0} is closed.

Most Eclipse tools require the project containing the Eclipse resource (which is affected by the action) to be open.

User Response:
Open the project containing the Eclipse resource.
Parent topic: AWM UI (TSUIN) messages


TSUIN0144 The resource path \ {0} \ cannot be resolved to an Eclipse resource.

Eclipse tools require an Eclipse resource to be processed. The given path does not match an Eclipse resource in the workspace.

Model Administrator Response:
Verify that the input parameter corresponding to the Eclipse path is configured correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0145 The Tool {0} needs {1} input parameters and {2} output parameters

The parameter validation of the given tool fails. The input and/or parameter size is less than the tool's requirements.

Model Administrator Response:
Verify that the tool is modeled as described in the Workflow Manager Modelling Guide.
Parent topic: AWM UI (TSUIN) messages


TSUIN0146 The resource(s) {0} already exist(s).

Some Eclipse tools (Create Resource, Copy Resource, Move Resource, Rename Resource) require that the affected resource does not exist before they will be processed. That is when the tool attribute "Existing Resource Handling" is set to "Error".

User Response:
Delete the affected resource and run the action again.
Parent topic: AWM UI (TSUIN) messages


TSUIN0147 Existing resource handling parameter missing. Valid values are REPLACE, IGNORE or ERROR.

The attribute "Existing Resource Handling" of an Eclipse tool (Create, Copy, Move or Rename tool) is set to "From Parameter" but the existing resource handling input parameter value cannot be determined.

Model Administrator Response:
Verify that the existing resource handling input parameter is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0148 The existing resource handling parameter value {0} is invalid. Valid values are REPLACE, IGNORE or ERROR.

The attribute "Existing Resource Handling" of an Eclipse tool (Create , Copy, Move or Rename tool) is set to "From Parameter" but the existing resource handling input parameter value is invalid.

Model Administrator Response:
Verify that the existing resource handling input parameter is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0149 Mass processing not allowed for tool {0} .

The Eclipse tool "Get Local History" is not able to handle the mass processing input parameter.

Model Administrator Response:
Verify that the modeled input parameter type is not mass processing.
Parent topic: AWM UI (TSUIN) messages


TSUIN0150 At least one output parameter of type FILE must be defined for tool {0} .

The Eclipse tool "Get Local History" needs a file output parameter.

Model Administrator Response:
Verify that the Eclipse tool "Get LocalHistory" has a file output parameter.
Parent topic: AWM UI (TSUIN) messages


TSUIN0151 The file output parameter is not modeled for tool {0} .

The Eclipse tool "Get Local History" needs a file output parameter but the target ID of this parameter is not one.

Model Administrator Response:
Verify that the file output parameter is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0152 The value of the attribute {0} of the tool {1} cannot be determined.

The attribute "Eclipse Project Matchname" of the Eclipse tool "Get Projects" cannot be determined. This is an internal client error.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0153 Values of attributes {0} and/or {1} of the tool {2} cannot be determined.

The attribute "Eclipse Folder Matchname" of the Eclipse tool "Get Resource Children" cannot be determined. This is an internal client error.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0154 The value of the attribute {0} of the tool {1} is set to false but the 2nd input parameter is not configured.

The Eclipse tool "Move Resource" needs two input parameters while the attribute "With UI" is set to false.

Model Administrator Response:
Verify that the Eclipse tool "Move Resource" has two input parameters.
Parent topic: AWM UI (TSUIN) messages


TSUIN0155 A resource must be specified where clipboard contents should be copied.

The Eclipse tool "Paste Resource From Clipboard" needs an Eclipse resource to paste clipboard contents in the following cases:

  • The clipboard contains Eclipse IFolder or IFile.
  • The clipboard contains local files.
User Response:
See description.
Model Administrator Response:
Verify that the tool is correctly modeled.
Parent topic: AWM UI (TSUIN) messages


TSUIN0156 There are no contents in clipboard or the clipboard contents cannot be pasted to the selected resource.

The clipboard contents are empty, or the contents are neither an Eclipse resource nor a local file path.

User Response:
Retry the copy and paste action. Note that you can only copy Eclipse resources or local files.
Parent topic: AWM UI (TSUIN) messages


TSUIN0157 Selection resource type parameter is missing from Eclipse tool {0} . Valid values are FILE, FOLDER, PROJECT or ANY.

The attribute "Selection Type" of the Eclipse tool "Select Resource" is set to "From Parameter" but the selection type input parameter value cannot be determined.

Model Administrator Response:
Make sure that the selection type input parameter is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0158 The existing resource type parameter value {0} is invalid for tool {1} . Valid values are FILE, FOLDER, PROJECT or ANY.

The attribute "Selection Type" of the Eclipse tool "Select Resource" is set to "From Parameter" but the selection type input parameter value is not valid.

Model Administrator Response:
Make sure that the selection type input parameter is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0159 Tool {0} does not allow mass processing.

The Eclipse tool "Show Local History" is not able to handle the mass processing input parameter.

Model Administrator Response:
Verify that the modeled input parameter type is not mass processing.
Parent topic: AWM UI (TSUIN) messages


TSUIN0160 The given wizard ID in {0} cannot be found in the New Wizard registry.

The attribute "wizardType" of Eclipse tool "Open Wizard" was set to "From Wizard ID" but the given wizard ID could not be found in the "New Wizard" registry.

Model Administrator Response:
Make sure that the value of the first input parameter of the tool "Open Wizard" matches an ID from the "New Wizard" registry.
Parent topic: AWM UI (TSUIN) messages


TSUIN0161 An exception occurred while executing a custom error feedback action.

An error occurred while a custom error feedback entry action was executed. This is caused by a non-Micro Focus plug-in.

Model Administrator Response:
Try to determine which plug-in implemented the custom error feedback entry action. If it was developed internally, contact the contributor to fix the problem.
Parent topic: AWM UI (TSUIN) messages


TSUIN0162 Cannot set value \ {0} \ for property \{1} \ because the resource identifier is missing.

AWM was unable to set the "Editable" flag of an Eclipse resource, because the resource identifier could not be resolved.

Model Administrator Response:
Verify that a resource identifier is set for the corresponding linked property (use validate function). If so, verify that a property value for the identifier is set in the context of the executed AWM action.
Parent topic: AWM UI (TSUIN) messages


TSUIN0163 Failed to set the \EDITABLE\ linked property value. Linked property ID: \ {0} \.

The "Editable" flag of an Eclipse resource could not be set via a linked property.

Model Administrator Response:
See the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0164 Unable to get Eclipse file store for resource \ {0} \.

The file store (location) of the selected resource cannot be determined. This is needed to get the size of the resource.

User Response:
Make sure the selected resource exists.

See the message under "Reason:" in the message dialog.

If necessary, contact the Administrator.

Model Administrator Response:
Check the error log for more information. If necessary, contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0165 Compare failed while trying to get the file content.

An I/O exception occurred during the compare action reading the files to be compared.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the Administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0166 Compare failed while trying to set the file content.

An I/O exception occurred during the compare action setting the content of the files to be compared.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the Administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0167 Failed to open or activate the table view with the secondary ID:

This is an internal client error that occurred while showing the TD Element Table View.

Model Administrator Response:
Contact SupportLine.
Parent topic: AWM UI (TSUIN) messages


TSUIN0168 The file type {0} is not supported by {1} .

Failed to get the file to compare during execution of the compare action. The tool "File Compare" only supports file descriptors of type WORKSPACE, LOCAL_FILE, INPUT_STREAM, MVSSEQ, MVSPO_MEMBER.

Model Administrator Response:
Verify that the corresponding file descriptor is modeled correctly.
Parent topic: AWM UI (TSUIN) messages


TSUIN0169 Eclipse element synchronizer: Failed to delete element \ {0} \.

This is a top-level exception that will be printed into the error log if any exception occurs during the delete of a element. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0170 Eclipse element synchronizer: Failed to refresh children of the resource \ {0} \.

This is a top-level exception that will be printed into the error log if any exception occurs during the refresh of an Eclipse resource. A more detailed error message can usually be found in the error details.

User Response:
Refresh the resource manually.
Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0171 Eclipse element synchronizer: Failed to refresh the file cache after synchronization.

This is a top-level exception that will be printed into the error log if any exception occurs during the refresh of the file cache. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0172 Eclipse element synchronizer: Failed to find elements that are out of sync with the Eclipse workspace.

Search for elements that are out of sync failed. Synchronization is caused by Eclipse resource changes if the loaded model contains the Eclipse function package and "Background Synchronizer" is enabled (function package attribute).

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0173 Eclipse element synchronizer: Failed to delete the element list entry \ {0} \.

This is a top-level exception that will be printed into the error log if any exception occurs during the delete of an element list entry. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0174 Eclipse element synchronizer: Failed to delete element list entry for removed resource \ {0} \.

This is a top-level exception that will be printed into the error log if any exception occurs during the delete of a element list entry. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0175 Eclipse element synchronizer: Failed to refresh element \ {0} \.

This is a top-level exception that will be printed into the error log if any exception occurs during the refresh of an element. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0176 Eclipse element synchronizer: Failed to refresh element \ {0} \.

This is a top-level exception that will be printed into the error log if any exception occurs during the refresh of a element. A more detailed error message can usually be found in the error details.

Model Administrator Response:
Check the error details for more information.
Parent topic: AWM UI (TSUIN) messages


TSUIN0177 Handler not found for: {0}

A command handler for executing an Eclipse command was not found.

Model Administrator Response:
If the error occurred during execution of the Eclipse function package tool "Command Handler", check that the "Command Handler ID" parameter was resolved to a valid command handler ID.
Parent topic: AWM UI (TSUIN) messages


TSUIN0178 The key sequence \ {0} \ of action descriptor \{1} \ is invalid.

An invalid key sequence string has been used in a model.

Model Administrator Response:
Use the model editor to capture a valid key sequence string for the corresponding action descriptor.
Parent topic: AWM UI (TSUIN) messages


zExplorer for z/Server (TSXZS) messages

  • TSXZS0001 Failed to load XML file containing default connections.
  • TSXZS0002 {0} is not a valid MVS resource name.
  • TSXZS0003 No file descriptor found for data set list.
  • TSXZS0004 Failed to decrypt the saved password for user {0} .
  • TSXZS0005 Failed to save the password (encryption problem).
  • TSXZS0006 Connect to {0} :{1} was not successful.
  • TSXZS0011 User selected Cancel on disconnect dialog.
  • TSXZS0012 Failed to properly log off from {0} :{1} . You are now disconnected.
  • TSXZS0018 Failed to parse attributes of resource {0} .
  • TSXZS0022 Directory blocks not numeric for {0} .
  • TSXZS0023 List data set error.
  • TSXZS0025 Element name property missing for element type {0} .
  • TSXZS0026 Failed to generate an element ID for element {0} .
  • TSXZS0027 Only subclasses of MvsResource (MvsDataset, MvsDatasetMember) can be renamed.
  • TSXZS0028 Only subclasses of MvsResource (MvsDataset, MvsDatasetMember) can be refreshed.
  • TSXZS0029 Converting an outdated application model failed.
  • TSXZS0030 Failed to load the model configuration file: {0} because it seems to be incompatible with your client version.
  • TSXZS0031 Missing type in zExplorer model: {0} .
  • TSXZS0032 {0} will be opened in read-only mode because non-displayable characters were detected.
  • TSXZS0033 File {0} does not exist.
  • TSXZS0034 User selected Cancel on save editor dialog.
  • TSXZS0035 The file {0} could not be deleted.
  • TSXZS0036 Failed to save file mappings.
  • TSXZS0037 Failed to reload file mappings.
  • TSXZS0042 Failed to create a member list.
  • TSXZS0043 Changing expired password failed.
  • TSXZS0044 The file {0} could not be unlocked.
  • TSXZS0045 Missing generic name for default file mapping.
  • TSXZS0046 Missing suffix for default file mapping \ {0} \.
  • TSXZS0047 Failed to create default file mappings.
  • TSXZS0048 No file descriptor found for member list.
  • TSXZS0049 A filter name is missing for remote system connection \ {0} \.
  • TSXZS0050 Missing filter type for filter \ {0} \.
  • TSXZS0051 Filter type \ {0} \ of filter \{1} \ is invalid.
  • TSXZS0052 The remote system type \ {0} \ does not exist.
  • TSXZS0053 Failed to get data sets for filter \ {0} \.
  • TSXZS0054 Failed to create an AWM system reference. Is the REXX procedure \ {0} \ available and configured?
  • TSXZS0055 More than one AWM system was returned by master REXX procedure \ {0} \. This is not allowed since exactly one AWM system must be associated to a remote system connection.
  • TSXZS0056 Credentials provider extension of contributor \ {0} \ will not be used, since another extension is already registered ({1} ). Only one credentials provider is allowed.
  • TSXZS0057 Invalid object given: {0}
Parent topic: Error messages


TSXZS0001 Failed to load XML file containing default connections.

The XML file containing default z/Server connection definitions could not be loaded properly. The file is named "defaultZConnections.XML" and is located in the Eclipse root folder.

Model Administrator Response:
  • Verify that the file can be read by the user.
  • Open the file in an (XML) editor and correct any syntax errors.
  • Delete the file if it is not required.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0002 {0} is not a valid MVS resource name.

Failed to parse a data set name from the passed MVS resource name. This is an internal problem.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0003 No file descriptor found for data set list.

A data set list could not be created because the file descriptor defining the list was not found. This is an internal error that may have been caused by the zExplorer model not being loaded correctly.

User Response:
  • Retry the action.
  • Reconnect and retry the action
.
Model Administrator Response:
  • Verify that the z/Server EXEC library (containing the TAUZCAPP procedure) is in the SYSEXEC concatenation of the user server.
  • If the zExplorer model was customized, determine the problem in the customized model. Contact Customer Support if necessary.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0004 Failed to decrypt the saved password for user {0} .

Failed to decrypt a stored password. The password was stored, because the user checked the "Save password" check-box in the "Enter password" dialog.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0005 Failed to save the password (encryption problem).

Failed to encrypt and save a password. The password was supposed to be saved because the user had checked the "Save password" check-box in the "Enter password" dialog.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0006 Connect to {0} :{1} was not successful.

The connection to the z/Server could not be established. This is a top-level exception, which means that a more detailed error message can usually be found in the error details. Possible reasons are:

  • Network problems (the host cannot be reached).
  • RACF error (wrong password, user not authorized, etc.).
  • User cancelled the "Enter password" dialog. - z/Server problems.
  • Problems while calling the TAUZCAPP procedure.
User Response:
  • Check your network connection.
  • Verify that a valid user name and password were entered.
Model Administrator Response:
  • Verify that the TAUZCAPP REXX procedure returns a master configuration properly.
  • Verify that the returned master configuration file is valid.
Server Administrator Response:
  • Verify that the z/Server is up and running.
  • Check the z/Server log for more information.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0011 User selected Cancel on disconnect dialog.

If a user tries to disconnect from the z/Server while MVS edit sessions are still open in the client, a confirmation dialog will come up to warn the user that the editor(s) will be closed before disconnecting. If a user selects "Cancel" in this dialog, the disconnect action will be aborted and this message written into the error log.

User Response:
No user action is required since cancelling the disconnect action was probably intended. If not, close any open (non-local) editor or disconnect again and press "OK" in the confirmation dialog. Unsaved changes can still be changed (individual confirmation dialogs will open).
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0012 Failed to properly log off from {0} :{1} . You are now disconnected.

The client failed to properly disconnect from the z/Server. Possible reasons are:

  • The network connection was interrupted.
  • The user server ended abnormally and did not shut down.
  • Open edit sessions could not be properly ended. The connection is shown as "disconnected" in the Remote Systems View. It is possible to (re)connect normally afterwards.
Server Administrator Response:
Determine what causes the problem. Check the z/Server logs for more information. Contact SupportLine if necessary.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0018 Failed to parse attributes of resource {0} .

A z/Server LIST response (LISTDSI for data sets or LISTMEM for members) could not be parsed properly. This message is issued for every data set or member that could not be created.

Server Administrator Response:
Look for distinctive features of the resources that could not be parsed or created (special characters, attributes, etc.) and contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0022 Directory blocks not numeric for {0} .

Failed to determine the number of directory blocks for a data set. This is an internal problem involving REXX procedure TAUZCLDS.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0023 List data set error.

An internal error occurred while executing the REXX procedure TAUZCLDS or parsing its results.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0025 Element name property missing for element type {0} .

No element name property was modeled for the element type in a zExplorer model. Either the model is incomplete or it was not loaded correctly.

User Response:
Reconnect to the z/Server and retry the action. Contact the model administrator if the problem still occurs.
Model Administrator Response:
  • Verify that the master configuration for the system contains the "zExpConf" statement. If it does, verify that the referenced model is valid, and configure an "Element_Name" Property for the Element Type.
  • If no customized zExplorer model is supposed to be used, remove the attribute "zExpConf" from the master configuration (it is commented out by default).
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0026 Failed to generate an element ID for element {0} .

An element ID for a zExplorer element type could not be generated successfully. Either the model is incomplete or it was not loaded properly.

User Response:
Reconnect to the z/Server and retry the action. Contact the model administrator if the problem still occurs.
Model Administrator Response:
  • Verify that the master configuration for the specific system contains the "zExpConf" statement. If it does, correct any problems concerning the ID definitions of the element types.
  • If no customized zExplorer model should be used, remove or comment out the "zExpConf" attribute from the master configuration (commented out by default).
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0027 Only subclasses of MvsResource (MvsDataset, MvsDatasetMember) can be renamed.

This problem occurs if the zExplorer API was used incorrectly and should not occur unless the zExplorer was customized by third party plug-ins.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0028 Only subclasses of MvsResource (MvsDataset, MvsDatasetMember) can be refreshed.

This problem occurs if the zExplorer API was used incorrectly, and should not occur unless the zExplorer was customized by third party plug-ins.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0029 Converting an outdated application model failed.

An internal error occurred while a possibly outdated model was being converted. The conversion will be initiated as soon as the model loader detects syntax errors in the model.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0030 Failed to load the model configuration file: {0} because it seems to be incompatible with your client version.

A model could not be loaded or opened completely because it contains syntax errors. Even the model conversion was not successful.

User Response:
Verify that all code page settings are correct (connection properties and file mappings).
Model Administrator Response:
Open the model in the model editor and click the Details button next to the text box containing an error message. All syntax problems for the loaded model are then listed, including where they occur. Correct the problems manually by editing the model with a text- or XML editor.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0031 Missing type in zExplorer model: {0} .

An explicitly required object from the internal z/Explorer model was not found. This may be caused by incorrect customization of the internal model or by a failure to load the model.

Model Administrator Response:
If the zExplorer model was customized, determine the problem in the customized model. Contact SupportLine if necessary.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0032 {0} will be opened in read-only mode because non-displayable characters were detected.

The file to be opened in the editor contains characters that cannot be converted properly using the indicated code page. Write protection is automatically enabled since saving the file back to the mainframe would corrupt its contents.

User Response:
Verify that your code page settings (including file mappings) are correct, change them if necessary and re-open the file in the editor.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0033 File {0} does not exist.

An internal problem occurred while opening an MVS file in the editor. The file location is within the workspace since a temporary copy of the host resource should have been copied there.

Model Administrator Response:
Contact SupportLine
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0034 User selected Cancel on save editor dialog.

If a user tries to disconnect from the z/Server while MVS edit sessions are still open in the client, a confirmation dialog will warn the user that the editor(s) will be closed before disconnecting. If the user selects 'OK' in this dialog and the editor(s) contain unsaved changes, individual dialogs will appear for each editor, asking whether to save the changes or cancel the disconnect action. If a user selects "Cancel" in one of these dialogs, this message is written to the error log.

User Response:
No response required. If selecting 'Cancel' was not intended, the action (disconnecting from the z/Server or closing Eclipse) can simply be repeated.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0035 The file {0} could not be deleted.

This is an internal problem. It occurs if the temporary copy of the remote file could not be deleted after the editor was closed.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0036 Failed to save file mappings.

An internal error occurred while saving the file mappings into the local cache. This is most likely caused by Eclipse being out of sync with the local file system.

Model Administrator Response:
Refresh the internal project from the Navigator View and restart the client. If the problem recurs, contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0037 Failed to reload file mappings.

An internal error occurred while loading the file mappings from the local cache. This is most likely caused by Eclipse being out of sync with the local file system.

Model Administrator Response:
Refresh the internal project from the Navigator View and restart the client. If the problem recurs, contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0042 Failed to create a member list.

Failed to create a list of members for an MVS data set. This is an internal error which usually contains more information in the error details.

Model Administrator Response:
If the zExplorer model was customized, determine the problem in the customized model. Contact SupportLine if necessary.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0043 Changing expired password failed.

An attempt to change a user password failed. Reasons could be one of the following:

  • Two different passwords were given in the change password dialog.
  • Invalid characters were used in the new password.
  • The old password was re-entered instead of a new password.
User Response:
Start the dialog again and enter a new valid password.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0044 The file {0} could not be unlocked.

This problem occurs if a remote file opened in edit mode could not be unlocked after the editor was closed. Typical reasons are network or server problems.

User Response:
Check your network and server connection.
Server Administrator Response:
Check the server logs for possible problems.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0045 Missing generic name for default file mapping.

The generic name for default file mapping is missing in the default configurations file.

Model Administrator Response:
Add the missing attribute to the file mapping within the default configurations file.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0046 Missing suffix for default file mapping \ {0} \.

The suffix attribute for default file mapping is missing in the default configurations file.

Model Administrator Response:
Add the missing attribute to the file mapping within the default configurations file.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0047 Failed to create default file mappings.

Default file mappings from a default configurations file could not be created.

Model Administrator Response:
Check the error log for the initial exception.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0048 No file descriptor found for member list.

A file output parameter is missing for the MVS function package tool "Get Members".

Model Administrator Response:
Add the mandatory file output parameter to the tool descriptor. See your documentation for how the file descriptor must be configured.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0049 A filter name is missing for remote system connection \ {0} \.

The filter name attribute is missing for a default filter of a default remote system.

Model Administrator Response:
Add the missing attribute to the default filter in the default configurations file.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0050 Missing filter type for filter \ {0} \.

The "type" attribute is missing for a default filter of a default remote system.

Model Administrator Response:
Add the missing attribute to the default filter in the default configurations file.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0051 Filter type \ {0} \ of filter \{1} \ is invalid.

An invalid type attribute value was specified for a default remote system connection filter.

Model Administrator Response:
See your documentation for default filter types and correct the invalid value.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0052 The remote system type \ {0} \ does not exist.

An invalid remote system type was used in a default configurations file.

Model Administrator Response:
See Default Configurations in your documentation for valid remote system types or, if a third party system type should be referenced, verify that the type ID is correct.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0053 Failed to get data sets for filter \ {0} \.

Failed to get data sets for the specified filter. Either the filter was invalid, or executing the server command was not successful.

Model Administrator Response:
Check the error log for the initial error message.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0054 Failed to create an AWM system reference. Is the REXX procedure \ {0} \ available and configured?

Failed to create AWM systems based on the mainframe master REXX procedure response.

Server Administrator Response:
Verify that the master procedure is available and configured properly (e.g. master configuration path entered correctly).

Check the error log for initial error messages.

Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0055 More than one AWM system was returned by master REXX procedure \ {0} \. This is not allowed since exactly one AWM system must be associated to a remote system connection.

A mainframe master configuration contained more than one AWM system. This is not allowed.

Server Administrator Response:
Change the master configuration (or master procedure) to only return a single unique system name.
Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0056 Credentials provider extension of contributor \ {0} \ will not be used, since another extension is already registered ({1} ). Only one credentials provider is allowed.

More than one z/Server credentials provider was configured by third party plug-ins. Only one custom credentials provider is allowed.

Model Administrator Response:
Contact the plug-in contributor, if known. Only one credentials provider can be installed.

Contact SupportLine if the plug-in contributor is not known.

Parent topic: zExplorer for z/Server (TSXZS) messages


TSXZS0057 Invalid object given: {0}

This is an unexpected program exception which can either be caused by an internal program error or invalid API usage from third party developers (plug-ins).

Model Administrator Response:
Check whether this is caused by API usage. If not, contact SupportLine.
Parent topic: zExplorer for z/Server (TSXZS) messages


zExplorer subsystem JES (TSXJE) messages

  • TSXJE0001 Job name is missing.
  • TSXJE0002 Job ID is missing.
  • TSXJE0003 An error occured while searching for a custom JesAdapterFactory.
  • TSXJE0004 Failed to cancel job {0} .
  • TSXJE0005 Failed get contents of job {0} .
  • TSXJE0006 Failed to browse job {0} .
  • TSXJE0007 Failed to cancel the job {0} .
  • TSXJE0008 Failed to get job parts.
  • TSXJE0009 Failed to browse job {0} .
  • TSXJE0010 Unexpected return value null from IJobFacility {0} .
  • TSXJE0011 Retrieving job information encountered a problem.
Parent topic: Error messages


TSXJE0001 Job name is missing.

The job name is missing for at least one job in the XML response of z/Server for a job list request.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0002 Job ID is missing.

The job ID is missing for at least one job in the XML response of z/Server for a job list request.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0003 An error occured while searching for a custom JesAdapterFactory.

This is a top level exception that will be printed into the error log. A more detailed error message can usually be found in the error details.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0004 Failed to cancel job {0} .

The job with the given ID could not be canceled on the remote z/OS system.

User Response:
Verify that the user has the authority to cancel this job.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0005 Failed get contents of job {0} .

The contents of the given job could not be read from the remote z/OS system.

User Response:
Verify that the user has the authority to read this job's contents. If yes, contact the administrator.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0006 Failed to browse job {0} .

The given job could not be read from the remote system.

User Response:
Verify that the user has the authority to read this job's contents. If yes, contact the administrator.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0007 Failed to cancel the job {0} .

The given job could not be canceled on the remote system.

User Response:
Verify that the user has the right to cancel this job.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0008 Failed to get job parts.

The selected job's parts could not be read from the remote system.

User Response:
Verify that the user has the authority to read this job's parts' content. If yes, contact the administrator.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0009 Failed to browse job {0} .

The given job part's content could not be read from the remote system.

User Response:
Verify that the user has the authority to read this job part's content. If yes, contact the administrator.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0010 Unexpected return value null from IJobFacility {0} .

A NullPointer exception occurred when determining the job facility class. This is an internal error.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem JES (TSXJE) messages


TSXJE0011 Retrieving job information encountered a problem.

The job's meta information could not be read from the remote system.

User Response:
Contact the administrator.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem JES (TSXJE) messages


zExplorer subsystem MVS (TSXMV) messages

  • TSXMV0001 An error occurred while searching for a custom MvsAdapterFactory.
  • TSXMV0002 Changing password failed.
  • TSXMV0003 RECALL failed. The data set was not created.
  • TSXMV0004 Logoff failed.
  • TSXMV0005 Failed to set the debug parameter.
  • TSXMV0007 Failed to send the following HEX Characters: {0}{1} .
  • TSXMV0008 Sending hexes cancelled by user.
  • TSXMV0009 Paste error.
  • TSXMV0010 Severe paste error.
  • TSXMV0011 Severe error when trying to paste member list {0} from {1} .
  • TSXMV0012 Severe error when trying to paste member {0} from {1} .
  • TSXMV0013 Severe error when checking member existence of {0} in {1} .
  • TSXMV0014 Severe error when trying to paste member list {0} from {1} .
  • TSXMV0015 Data set allocation error.
  • TSXMV0018 Could not find any z/Server tool with ID {0} .
  • TSXMV0019 The z/Server tool {0} needs at least one input parameter (data set name).
  • TSXMV0020 The tool {0} needs exactly one input parameter (fully qualified data set or member name).
  • TSXMV0021 The z/Server tool {0} needs exactly two input parameters (DSN, member filter).
  • TSXMV0022 The z/Server tool {0} needs exactly one file output parameter ({1} ).
  • TSXMV0023 Getting members of data set {0} failed with message: {1}{2} .
  • TSXMV0024 Invalid filter string.
  • TSXMV0025 Failed to receive files for filter request: {0} .
  • TSXMV0026 Getting data sets for filter string {0} failed with message: {1}{2} .
  • TSXMV0027 At least one LISTDSI parser error occurred.
  • TSXMV0029 Insert of member {0} failed.
  • TSXMV0030 Failed to submit job. No z/OS job support was found (implementation of extension point {0} ).
  • TSXMV0031 Failed to submit job.
  • TSXMV0032 RECALL failed.
  • TSXMV0035 Job submit failed. Failed to find a job support extension.
  • TSXMV0036 Job submit failed.
  • TSXMV0037 Delete error.
  • TSXMV0038 Severe error when trying to duplicate a PO member {0} .
  • TSXMV0040 Failed to dequeue the resource {0} .
  • TSXMV0041 Severe error when trying to paste member list {0} from {1} .
  • TSXMV0042 Severe error when checking for existence of member {0} in {1} .
  • TSXMV0043 Severe error when trying to paste member list {0} from {1} .
  • TSXMV0044 Exception when trying to connect to {0} .
  • TSXMV0045 There is no z connection defined. Please define a new connection first.
  • TSXMV0046 Invalid begin column specified.
  • TSXMV0047 Invalid end column specified.
  • TSXMV0048 No system was specified.
  • TSXMV0049 Error when setting markers for file {0} .
  • TSXMV0050 Failed to browse the file.
  • TSXMV0051 Remote code page does not contain a valid code page.
  • TSXMV0052 Local code page does not contain a valid code page.
  • TSXMV0054 Exception occurred during data set DragAndDrop action.
  • TSXMV0055 The source data set is migrated.
  • TSXMV0056 Exception occurred during member DragAndDrop action.
  • TSXMV0057 Get bind data failed.
  • TSXMV0058 Failed to browse the member {0} .
  • TSXMV0059 The source data set is migrated.
  • TSXMV0060 Delete error.
  • TSXMV0061 Exception occurred when calling search REXX TAUZCSRC.
  • TSXMV0062 Dataset Migrated/Exception when calling search REXX TAUZCSRC.
  • TSXMV0063 Unexpected response from LOGOFF.
  • TSXMV0064 CALLREXX failed.
  • TSXMV0065 Target member name must be different from source member name.
  • TSXMV0066 Data set name must not contain blanks.
  • TSXMV0067 Please enter a value greater than zero as primary space amount.
  • TSXMV0068 Please enter a numeric value as primary space amount.
  • TSXMV0069 Please enter a numeric value as secondary space amount.
  • TSXMV0070 Please enter a numeric value for directory blocks.
  • TSXMV0071 Please enter a numeric value as record length.
  • TSXMV0072 Please enter a numeric value as block size.
  • TSXMV0073 Failed to get members of data set {0} .
  • TSXMV0074 Calling zServer info command failed.
  • TSXMV0075 The zServer info command is not available before the zServer version 2.2.02.
  • TSXMV0076 A data set can only be created from a dataset or from a MVS subsystem.
  • TSXMV0077 Missing input parameter: \Data Set Filter String\.
  • TSXMV0078 Failed to parse CATDCB data set \ {0} \... {1}{2}
Parent topic: Error messages


TSXMV0001 An error occurred while searching for a custom MvsAdapterFactory.

The extension which extends the extension point de.soforte.zexplorer.subsystem.mvs.CustomMvsAdapterFactory could not be loaded.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0002 Changing password failed.

During the change password dialog, an I/O exception occurred. It might be caused by an encryption problem (might be a code page problem).

Model Administrator Response:
  • Verify that a valid code page is set for the MVS Explorer settings.
  • Verify that there is no network problem.
  • Check the error log for more information.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0003 RECALL failed. The data set was not created.

The creation of a new MVS data set was executed on an existing data set. In this case, the attributes of the new data set are taken from the attributes of the selected data set. As the selected data set was migrated, it has to be recalled first. This recall failed. Which means that the new data set is not allocated.

User Response:
If possible, select another data set as the model data set for the data set creation.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0004 Logoff failed.

Logging off the user from z/Server using the hidden command !LOGOFF failed.

Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0005 Failed to set the debug parameter.

The call to the REXX TAUZCDBG to set the debug parameter resulted in an I/O exception.

Server Administrator Response:
Verify that the z/Server EXEC library is in the SYSEXEC concatenation of the user server. Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0007 Failed to send the following HEX Characters: {0}{1} .

A list of characters is shown that could not be sent to z/Server using the hidden command !SENDHEX.

User Response:
This is an informational message.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0008 Sending hexes cancelled by user.

The hidden action !SENDHEX was canceled by the user.

User Response:
This is an informational message.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0009 Paste error.

The paste action for a z/OS data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0010 Severe paste error.

The paste action for a z/OS data set resulted in a severe error.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0011 Severe error when trying to paste member list {0} from {1} .

Pasting a list of z/OS partitioned members failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0012 Severe error when trying to paste member {0} from {1} .

Pasting a list of partitioned data set members failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0013 Severe error when checking member existence of {0} in {1} .

Pasting a member of a partitioned data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Model Administrator Response:
Check the error log for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0014 Severe error when trying to paste member list {0} from {1} .

Pasting a list of z/OS partitioned members failed.

User Response:
See the message under "Reason:" in the message dialog.
Model Administrator Response:
Check the error log for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0015 Data set allocation error.

The allocation of a z/OS data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0018 Could not find any z/Server tool with ID {0} .

There is no z/Server tool defined for the given tool ID.

Model Administrator Response:
If this is a custom z/Explorer model, check the model definition and the plug-in code for the given tool ID. Otherwise contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0019 The z/Server tool {0} needs at least one input parameter (data set name).

There was no input parameter defined for the tool but it needs at least one.

Model Administrator Response:
If this is a custom z/Explorer model, check the model definition and the plug-in code for the given tool ID. Otherwise contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0020 The tool {0} needs exactly one input parameter (fully qualified data set or member name).

It was expected that exactly one input parameter was declared for the tool. The parameter was missing or more than one input parameter was declared for the tool.

Model Administrator Response:
If this is a custom z/Explorer model, check the model and the plug-in code for the given tool ID. Otherwise contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0021 The z/Server tool {0} needs exactly two input parameters (DSN, member filter).

It was expected that exactly one input parameter was declared for the tool. The parameter was missing or more than one input parameter was declared for the tool.

Model Administrator Response:
If this is a custom z/Explorer model, check the model and the plug-in code for the given tool ID. Otherwise contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0022 The z/Server tool {0} needs exactly one file output parameter ({1} ).

It was expected that exactly one file output parameter was declared for the tool. The parameter was missing or more than one output parameter was declared for the tool.

Model Administrator Response:
If this is a custom z/Explorer model, check the model and the plug-in code for the given tool ID. Otherwise contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0023 Getting members of data set {0} failed with message: {1}{2} .

The members of the given data set could not be retrieved from the remote z/OS system.

User Response:
See the included z/Server messages for more details.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0024 Invalid filter string.

An unsupported filter string was used. Unsupported filter strings are *, % or filter strings starting with *.

User Response:
Use a qualifying filter string.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0025 Failed to receive files for filter request: {0} .

The filter request for the given filter string failed.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0026 Getting data sets for filter string {0} failed with message: {1}{2} .

The filter request for the given filter string failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0027 At least one LISTDSI parser error occurred.

The parser analysing the response of the LISTDSI request to z/Server detected at least one error in the response.

User Response:
This is an informational message.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0029 Insert of member {0} failed.

Adding a member to a z/OS partitioned data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0030 Failed to submit job. No z/OS job support was found (implementation of extension point {0} ).

The submit of a job failed. Most likely there was no extension for the extension point de.soforte.zos.JobFacility found.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0031 Failed to submit job.

The submit of a job failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the model administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0032 RECALL failed.

The recall of a migrated data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0035 Job submit failed. Failed to find a job support extension.

Submit of a job failed. Most likely there was no extension for the extension point de.soforte.zos.JobFacility found.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0036 Job submit failed.

The submit of a job failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the model administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0037 Delete error.

Deletion of a member of a z/OS partitioned data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0038 Severe error when trying to duplicate a PO member {0} .

The duplicate action for a member in a z/OS partitioned data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0040 Failed to dequeue the resource {0} .

The dequeue action for a z/OS data set failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0041 Severe error when trying to paste member list {0} from {1} .

The paste action for a z/OS partitioned data set member list failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0042 Severe error when checking for existence of member {0} in {1} .

An exception occurred when checking if the given member exists in the given data set.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0043 Severe error when trying to paste member list {0} from {1} .

The paste action of a list of z/OS partitioned data set members failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0044 Exception when trying to connect to {0} .

The connection to the remote system did not work when the search action was called.

User Response:
Check if there are any network problems. See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0045 There is no z connection defined. Please define a new connection first.

The z/Server search action was called without a z/Server connection defined in the Remote Systems View.

User Response:
Define a z/Server connection in the Remote System View, then repeat the search action.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0046 Invalid begin column specified.

The parameter "Begin column" for the search has an invalid format. It must have a numeric format.

User Response:
Enter a numeric value in the input field "Begin column" or leave it empty.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0047 Invalid end column specified.

The parameter "End column" for the search has an invalid format. It must have a numeric format.

User Response:
Enter a numeric value in the input field "End column" or leave it empty.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0048 No system was specified.

Access to the remote z/Server connection caused a NullPointer exception.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0049 Error when setting markers for file {0} .

The search markers could not be set in the editor when a file was opened from the search result view.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0050 Failed to browse the file.

Browsing a file from the Search Result View failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0051 Remote code page does not contain a valid code page.

The code page entered under "Remote Code page" in the z/Server connection definition is not a valid code page ID.

User Response:
Choose a valid code page for the remote code page.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0052 Local code page does not contain a valid code page.

The code page entered under "Local Code page" in the z/Server connection definition is not a valid code page ID.

User Response:
Choose a valid code page for the local code page (typically UTF-8).
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0054 Exception occurred during data set DragAndDrop action.

The drag/drop action of a z/OS data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0055 The source data set is migrated.

A drag/drop could not be executed because the source data set is migrated.

User Response:
Recall the migrated data set and retry the action.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0056 Exception occurred during member DragAndDrop action.

The drag/drop action of a member of a z/OS partitioned data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0057 Get bind data failed.

The binder information for a z/OS load module could not be retrieved.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the server administrator.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0058 Failed to browse the member {0} .

Browsing of the given member of a z/OS data set failed.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0059 The source data set is migrated.

The source data set of a drag/drop action is migrated.

User Response:
Recall the migrated data set. Retry the drag/drop action.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0060 Delete error.

Deletion of a z/OS data set failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0061 Exception occurred when calling search REXX TAUZCSRC.

The call to the REXX TAUZCSRC failed.

User Response:
See the message under "Reason:" in the message dialog.
Server Administrator Response:
Verify that the z/Server EXEC library is defined in the SYSEXEC concatenation of the z/Server user server. Verify that the z/Server EXEC library contains the REXX TAUZCSRC. Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0062 Dataset Migrated/Exception when calling search REXX TAUZCSRC.

The data set to which the search was applied is migrated.

User Response:
Recall the migrated data set and retry the search action.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0063 Unexpected response from LOGOFF.

The logoff from the z/Server using the hidden command !LOGOFF results in a response from the server that cannot be parsed.

Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0064 CALLREXX failed.

The hidden command !CALLREXX results in a response from the server that cannot be parsed.

Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0065 Target member name must be different from source member name.

The name chosen for the target member is identical to the name of the source member in the duplicate action.

User Response:
Choose a name for the target member which is different from the name of the source member.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0066 Data set name must not contain blanks.

In the data set allocation dialog, a data set name was entered which contains blanks. This is not allowed for z/OS data sets.

User Response:
Enter a data set name without blanks.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0067 Please enter a value greater than zero as primary space amount.

In the data set allocation dialog, a value of zero was entered for the primary space allocation.

User Response:
Enter a value greater than zero as the primary space allocation.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0068 Please enter a numeric value as primary space amount.

In the data set allocation dialog, a non-numeric value was entered as the primary space allocation.

User Response:
Enter a numeric value greater than zero as the primary space allocation.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0069 Please enter a numeric value as secondary space amount.

In the data set allocation dialog, a non-numeric value was entered as the secondary space allocation.

User Response:
Enter a numeric value as secondary space allocation.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0070 Please enter a numeric value for directory blocks.

In the data set allocation dialog, a non-numeric value was entered as the directory block amount.

User Response:
Enter a numeric value for directory blocks.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0071 Please enter a numeric value as record length.

In the data set allocation dialog, a non-numeric value was entered as the record length.

User Response:
Enter a numeric value as the record length.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0072 Please enter a numeric value as block size.

In the data set allocation dialog, a non-numeric value was entered as the block size.

User Response:
Enter a numeric value as the block size.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0073 Failed to get members of data set {0} .

A top-level exception occurred when determining the members of a z/OS partitioned data set.

User Response:
See the message under "Reason:" in the message dialog. Maybe the user does not have the authority to list the members of the partitioned data set. If necessary, contact the administrator.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0074 Calling zServer info command failed.

A error occurred calling the zServer info command.

User Response:
  • See the message under "Reason:" in the message dialog.
  • Verify that there is no network problem.
  • Verify that a valid code page is set for the MVS Explorer settings.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0075 The zServer info command is not available before the zServer version 2.2.02.

Self-explanatory.

User Response:
Self-explanatory.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0076 A data set can only be created from a dataset or from a MVS subsystem.

Self-explanatory.

User Response:
Create the data set from the context menu of a data set or of the MVS subsystem.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0077 Missing input parameter: \Data Set Filter String\.

No data set filter string could be found within the execution of a Get Data Set tool.

Model Administrator Response:
Add the missing property "Data Set Filter String" as an input parameter to the tool descriptor or as a fixed property.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


TSXMV0078 Failed to parse CATDCB data set \ {0} \... {1}{2}

An exception occurred while converting the MFA data set list.

Model Administrator Response:
Check the error log for more information. If necessary contact SupportLine.
Parent topic: zExplorer subsystem MVS (TSXMV) messages


zExplorer subsystem USS (TSXUS) messages

  • TSXUS0001 Element name property missing for element type {0} .
  • TSXUS0002 Failed to generate an element ID for element {0} .
  • TSXUS0003 Failed to set permissions of the USS resource because fewer than {0} input parameters were modeled in tool {1} .
  • TSXUS0004 The target ID of the {0} . input parameter is not modeled for tool {1} .
  • TSXUS0005 Failed to get permissions of the USS resource because fewer than {0} output parameters were modeled.
  • TSXUS0006 The value of the attribute {0} cannot be determined in tool {1} .
  • TSXUS0008 Exception occurred during creation of new resource from filter.
  • TSXUS0009 No file descriptor found for USS resource list.
  • TSXUS0010 Exception occurred during USS resource DragAndDrop action.
  • TSXUS0011 Failed to get children of USS resource {0} .
  • TSXUS0012 Error when getting the parent of the resource {0} .
  • TSXUS0013 Error when getting the children of the resource {0} .
  • TSXUS0014 An error occurred while searching for a custom UssAdapterFactory.
  • TSXUS0015 File permissions must not be null.
  • TSXUS0016 Missing attribute: \ {0} \.
  • TSXUS0017 \ {0} \ is not a valid value for attribute: \{1} \.
  • TSXUS0018 Invalid segment parameter: {0} .
  • TSXUS0019 Octal notation must not be null.
  • TSXUS0020 Octal notation must be three or four bytes long: \ {0} \.
  • TSXUS0021 Octal notation is invalid: \ {0} \.
  • TSXUS0022 Failed to parse a USS resource with the name \ {0} \.
  • TSXUS0023 \BYTES\ attribute of \ {0} \ response does not contain a numeric value.
  • TSXUS0025 The value \ {0} \ is not octal.
Parent topic: Error messages


TSXUS0001 Element name property missing for element type {0} .

No element name property was modeled for the element type in a zExplorer model. Either the model is incomplete or it was not loaded correctly.

User Response:
Reconnect to the z/Server and retry the action. Contact the model administrator if the problem still occurs.
Model Administrator Response:
Verify that the master configuration for the system contains the "zExpConf" statement. If it does, verify that the referenced model is valid, and configure an "Element_Name" Property for the Element Type.

If no customized zExplorer model is supposed to be used, remove the attribute "zExpConf" from the master configuration (it is commented out by default).

Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0002 Failed to generate an element ID for element {0} .

An element ID for a zExplorer element type could not be generated successfully. Either the model is incomplete or it was not loaded properly.

User Response:
Reconnect to the z/Server and retry the action. Contact the model administrator if the problem still occurs.
Model Administrator Response:
Verify that the master configuration for the specific system contains the "zExpConf" statement. If it does, correct any problems concerning the ID definitions of the element types.

If no customized zExplorer model should be used, remove or comment out the "zExpConf" attribute from the master configuration (commented out by default).

Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0003 Failed to set permissions of the USS resource because fewer than {0} input parameters were modeled in tool {1} .

The USS tool "Set Permissions" was not modeled properly. It requires ten input parameters.

Model Administrator Response:
Verify that ten input parameters are modeled for the "Set Permissions" tool descriptor. Valid parameter options are documented in the Workflow Manager Modelling Guide.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0004 The target ID of the {0} . input parameter is not modeled for tool {1} .

The permissions of the USS resource cannot be set because one or more input parameters of tool "Set Permissions" don't have a target ID reference.

Model Administrator Response:
Verify that all input parameters modeled for the USS tool "Set Permissions" have a target ID.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0005 Failed to get permissions of the USS resource because fewer than {0} output parameters were modeled.

The USS tool "Get Permissions" was not modeled properly. It requires nine output parameters.

Model Administrator Response:
Verify that nine input parameters are modeled for the "Get Permissions" tool descriptor. Valid parameter options are documented in the Workflow Manager Modelling Guide.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0006 The value of the attribute {0} cannot be determined in tool {1} .

The value of the tool attribute "Resource Type" is not set.

User Response:
Contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0008 Exception occurred during creation of new resource from filter.

The new Folder/File action of a filter failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0009 No file descriptor found for USS resource list.

A USS resource list could not be created because the file descriptor defining the list was not found. This is an internal error that might have been caused by the zExplorer model not being loaded correctly.

User Response:
Retry the action.

Reconnect and retry the action.

Model administrator response:
Verify that the z/Server EXEC library (containing the TAUZCAPP procedure) is in the SYSEXEC concatenation of the user server.

If the zExplorer model was customized, determine the problem in the customized model. Contact SupportLine if necessary.

Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0010 Exception occurred during USS resource DragAndDrop action.

The drag/drop action of a USS resource failed.

User Response:
See the message under "Reason:" in the message dialog.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0011 Failed to get children of USS resource {0} .

A top-level exception occurred when determining the children of a USS directory.

Model Administrator Response:
See the message under "Reason:" in the message dialog. Possibly the user does not have the authority to list the children of the directory. If necessary, contact the administrator.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0012 Error when getting the parent of the resource {0} .

A top-level exception occurred when determining the parent of a USS directory.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0013 Error when getting the children of the resource {0} .

A top-level exception occurred when determining the children of a USS directory.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0014 An error occurred while searching for a custom UssAdapterFactory.

The UssAdapterFactory for the extension point com.microfocus.zexplorer.subsystem.uss.CustomMvsAdapterFactory could not be loaded.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0015 File permissions must not be null.

This is an unexpected internal program error.

Model Administrator Response:
Please contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0016 Missing attribute: \ {0} \.

This is an unexpected internal program error.

Model Administrator Response:
Please contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0017 \ {0} \ is not a valid value for attribute: \{1} \.

This is an unexpected internal program error.

Model Administrator Response:
Please contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0018 Invalid segment parameter: {0} .

This is an unexpected internal program error.

Model Administrator Response:
Please contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0019 Octal notation must not be null.

This is an unexpected program exception which can either be caused by an internal program error or invalid API usage from third party developers (plug-ins).

Model Administrator Response:
Check whether this is caused by API usage. If not, contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0020 Octal notation must be three or four bytes long: \ {0} \.

This is an unexpected program exception which can either be caused by an internal program error or invalid API usage from third party developers (plug-ins).

Model Administrator Response:
Check whether this is caused by API usage. If not, contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0021 Octal notation is invalid: \ {0} \.

This is an unexpected program exception which can either be caused by an internal program error or invalid API usage from third party developers (plug-ins).

Model Administrator Response:
Check whether this is caused by API usage. If not, contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0022 Failed to parse a USS resource with the name \ {0} \.

A USS resource returned by the server could not be parsed by the client.

Model Administrator Response:
Contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0023 \BYTES\ attribute of \ {0} \ response does not contain a numeric value.

This is an unexpected internal program error.

Model Administrator Response:
Please contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


TSXUS0025 The value \ {0} \ is not octal.

This is an unexpected program exception which can either be caused by an internal program error or invalid API usage from third party developers (plug-ins).

Model Administrator Response:
Check whether this is caused by API usage. If not, contact SupportLine.
Parent topic: zExplorer subsystem USS (TSXUS) messages


z/Server communicator (SOZCM) messages

  • SOZCM0001 Internal file mappings error. The file mapping {0} was not found in the index.
  • SOZCM0002 Failed to restore file mappings.
  • SOZCM0003 The number of the given values does not match the number of the given attributes.
  • SOZCM0004 Password is invalid.
  • SOZCM0005 The entered password is too long.
  • SOZCM0006 The password is too long. Max. length is 8 characters.
  • SOZCM0007 Error from z/Server ADDUSRV command: {0} .
  • SOZCM0008 Action cancelled by user.
  • SOZCM0009 Data set allocation error: {0} .
  • SOZCM0010 {0} is not a fully qualified member name (DSN member name).
  • SOZCM0011 Failed to get contents for data set {0} .
  • SOZCM0012 pMsg must not be null.
  • SOZCM0013 User not defined to RACF.
  • SOZCM0014 Password not authorized.
  • SOZCM0015 The password has expired.
  • SOZCM0016 The new password is invalid.
  • SOZCM0017 User not defined to group.
  • SOZCM0018 User access revoked.
  • SOZCM0019 RACF is not active.
  • SOZCM0020 User access to group revoked.
  • SOZCM0021 OID REQD not supplied.
  • SOZCM0022 OID CARD invalid for user.
  • SOZCM0023 User not authorized to terminal.
  • SOZCM0024 User not authorized to APPL.
  • SOZCM0025 RACF verification for user ID not successful.
  • SOZCM0026 Access to data set {0} denied.
  • SOZCM0027 Unexpected length field: {0} .
  • SOZCM0028 Parsing of GETDATA response failed. Warning Message(s) from server: {0}
  • SOZCM0029 The GETDATA response from server could not be parsed.
  • SOZCM0030 Failed to get DCB for data set \ {0} \.
  • SOZCM0031 Failed to process temporary file \ {0} \.
  • SOZCM0032 Code page \ {0} \ is not supported.
Parent topic: Error messages


SOZCM0001 Internal file mappings error. The file mapping {0} was not found in the index.

The given file mapping could not be found in the internal file mapping cache.

User Response:
If the file mapping is missing in the File Mappings view, add it and retry the action. Verify that the file_mapping.xml file exists in the internal project folder in the user's workspace. Restart Eclipse to see if the file mapping is restored from the local cache.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0002 Failed to restore file mappings.

The file mappings could not be restored from the cached data in the Eclipse workspace.

User Response:
Verify that the file_mapping.xml file exists in the internal project folder in the user's workspace and is accessible. Verify that the file_mapping.xml file is a valid XML file. If not, try to repair it. If not possible, remove the file from the internal project folder and build up the file mappings from scratch.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0003 The number of the given values does not match the number of the given attributes.

This is an internal program exception. An API method was called which generates XML attributes from passed keywords and values but the number of keywords and values were not equal.

Model Administrator Response:
If the call was made from a custom plug-in, correct the passed parameters. Otherwise contact SupportLine.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0004 Password is invalid.

An invalid host password was specified.

User Response:
Use the correct password.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0005 The entered password is too long.

The password entered by the user is too long.

User Response:
Use the correct password.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0006 The password is too long. Max. length is 8 characters.

The password entered by the user is too long.

User Response:
Use the correct password.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0007 Error from z/Server ADDUSRV command: {0} .

The ADDUSRV command to start another z/Server user server failed.

Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0008 Action cancelled by user.

Self-explanatory.

User Response:
This is an informational message.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0009 Data set allocation error: {0} .

An error occurred during the allocation of a z/OS data set.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the administrator.
Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0010 {0} is not a fully qualified member name (DSN member name).

The data set name passed to the routine to browse a load module does not have the expected format.

Model Administrator Response:
Contact SupportLine.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0011 Failed to get contents for data set {0} .

The content of the given z/OS data set could not be read.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0012 pMsg must not be null.

The message parameter passed to the routine which sends messages to the server is null, which is not valid.

Model Administrator Response:
Contact SupportLine.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0013 User not defined to RACF.

The user ID specified is not defined to RACF on the remote z/OS system.

User Response:
Verify that the user specified the correct user ID.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0014 Password not authorized.

The given password is incorrect.

User Response:
Retry with the correct password.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0015 The password has expired.

The given password has expired.

User Response:
Use the change password dialog to get a new password. The change password dialog must be called while not disconnected from z/Server.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0016 The new password is invalid.

The new password specified in the Change Password dialog is not valid.

User Response:
Enter a valid password in the Change Password dialog.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0017 User not defined to group.

The user is not defined to a RACF group.

User Response:
Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0018 User access revoked.

The user ID is revoked in RACF.

User Response:
Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0019 RACF is not active.

The z/OS RACF facility is not active.

User Response:
Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0020 User access to group revoked.

The user's access to the requested RACF group is revoked.

User Response:
Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0021 OID REQD not supplied.

The RACF OID REQD was not supplied.

Server Administrator Response:
Check the z/Server logs and z/OS SYSLOG for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0022 OID CARD invalid for user.

The RACF OID CARD was not valid for the user.

User Response:
Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0023 User not authorized to terminal.

The user is not authorized by RACF to use a terminal.

User Response:
Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0024 User not authorized to APPL.

The user is not authorized in the RACF class APPL.

User Response:
Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0025 RACF verification for user ID not successful.

The given user ID did not pass the RACF user ID validation.

User Response:
Retry with the correct password. Contact the z/OS RACF administrator.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0026 Access to data set {0} denied.

The user does not have access to the given data set.

User Response:
This is an informational message.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0027 Unexpected length field: {0} .

A non-numeric field was detected when reading a file that is encrypted using BASE64. A numeric length field was expected.

Model Administrator Response:
Check the error log for more information. If necessary, contact SupportLine.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0028 Parsing of GETDATA response failed. Warning Message(s) from server: {0}

An error occurred when the response from the remote system was parsed.

User Response:
Check the subsequent message from the z/Server. If necessary, contact the administrator.
Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0029 The GETDATA response from server could not be parsed.

The response from z/Server to a GETDATA request has an invalid format.

Server Administrator Response:
Check the z/Server logs for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0030 Failed to get DCB for data set \ {0} \.

Exception occurred while getting DCB for a data set.

User Response:
See the message under "Reason:" in the message dialog. If necessary, contact the Administrator.
Model Administrator Response:
Check the error log for more information.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0031 Failed to process temporary file \ {0} \.

An exception occurred while translating the MFA response into the configured local system image code page. This is an internal error.

Model Administrator Response:
Contact SupportLine.
Parent topic: z/Server communicator (SOZCM) messages


SOZCM0032 Code page \ {0} \ is not supported.

Self-explanatory.

User Response:
Self-explanatory. If necessary, contact the administrator.
Parent topic: z/Server communicator (SOZCM) messages


z/Server ISPF panel support (TSIPS) messages

  • TSIPS0001 Failed to parse help panel {0} .
  • TSIPS0002 Given options map must not be null.
  • TSIPS0003 XML syntax error: A {0} element contains at least one {1} element. No {2} attribute is set.
  • TSIPS0004 There is no {0} included in {1} element.
  • TSIPS0005 A {0} element contains more than one {1} element with the {2} attribute: {3} .
  • TSIPS0006 XML syntax error: At least one {0} attribute must be specified for {1} attribute ComboBox.
  • TSIPS0007 XML syntax error: No {0} is set.
  • TSIPS0008 Panel extension error: parameter string for panel REXX in panel {0} call too long. Not all panel variables are passed to the panel REXX!
  • TSIPS0009 An error has occurred. See error log for more details.
  • TSIPS0010 Command property is not defined in relation ISA_ISPF_Panel_Command for {0} .
  • TSIPS0011 Relation ISA_ISPF_Panel_Command is missing for {0} .
  • TSIPS0012 Exception occurred during ISPF dialog processing.
  • TSIPS0015 Exception when connecting to system {0} .
  • TSIPS0016 IO exception when trying to read host message.
  • TSIPS0017 IO exception when sending a message to the user server.
  • TSIPS0018 Your dialog has timed out. Please restart the dialog.
  • TSIPS0019 z/Server exception during connection to port: {0} .
  • TSIPS0020 No ISPF help available for {0} .
  • TSIPS0021 User socket is null.
  • TSIPS0022 Tool type extension \
Parent topic: Error messages


TSIPS0001 Failed to parse help panel {0} .

The help panel associated with an ISPF panel could not be located in the given input partitioned data set. This means the help panel could not be parsed and the help information could not be registered to the corresponding attribute of the ISPF dialog tool.

User Response:
If help information should be added to the model, add the missing help panel to the data set specified in the corresponding location attribute in the panel generation control file, and then repeat the model generation.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0002 Given options map must not be null.

An internal object was null where it was not expected to be null.

Model Administrator Response:
Contact SupportLine.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0003 XML syntax error: A {0} element contains at least one {1} element. No {2} attribute is set.

There is an error in the XML structure of the panel model generator control file. A line command is defined for a panel although there is no table defined for the panel.

User Response:
Correct the error in the panel model generator control file. If there are line commands defined for a panel, a table attribute must be specified in the XML panel tag. Remove the line commands or add the table attribute.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0004 There is no {0} included in {1} element.

In the panel model generator control file, an application is defined with no associated panels.

User Response:
This is a warning message. Verify that the XML definition was intended to be this way.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0005 A {0} element contains more than one {1} element with the {2} attribute: {3} .

The same panel was declared more than once for the same application in the panel model generator control file.

User Response:
This is a warning message. Only one ISPF dialog tool will be generated if the same panel is declared more than once for the same application.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0006 XML syntax error: At least one {0} attribute must be specified for {1} attribute ComboBox.

A selection field was defined, but no selection values were given for a panel field in the panel model generator control file.

User Response:
Correct the panel model generator control file by listing the selection values.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0007 XML syntax error: No {0} is set.

The location attribute for a panel entry in the panel model generator control file could not be found.

User Response:
Correct the panel model generator control file by defining the location in the overallAttr, dialogAppl or panel XML tag.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0008 Panel extension error: parameter string for panel REXX in panel {0} call too long. Not all panel variables are passed to the panel REXX!

There is a technical restriction that the length of the field names passed to a ISPF Panel REXX must not exceed 255 characters in total. The conversion of the given panel caused a field name length greater than 255. This means that during the execution of the ISPF dialog in an Eclipse environment, not all of the variables' contents are passed to the client, which will cause unpredictable results.

User Response:
Try to change the ISPF panel so that fewer panel fields must be passed to the Eclipse dialog.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0009 An error has occurred. See error log for more details.

The XML SAX parser detected an error.

User Response:
There is a log file of the panel conversion in the FileCache sub folder of the internal project folder. See this log file for more information about the XML error.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0010 Command property is not defined in relation ISA_ISPF_Panel_Command for {0} .

The command property is missing in the ISA_ISPF_Panel_Command relation for the given tool in the model.

Model Administrator Response:
Correct the error in the ISA_ISPF_Panel_Command relation of the given tool in the XML model file. Select the command property.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0011 Relation ISA_ISPF_Panel_Command is missing for {0} .

The relation ISA_ISPF_Panel_Command for the given tool is missing. This relation is needed if a tool is defined as part of a line command action for a file descriptor.

Model Administrator Response:
Add an ISA_ISPF_Panel_Command relation to the given tool in the XML model file.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0012 Exception occurred during ISPF dialog processing.

An exception occurred during the execution of an ISPF dialog tool.

Model Administrator Response:
Check the z/Server logs for more information.
Server Administrator Response:
Check the error log for more information.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0015 Exception when connecting to system {0} .

The connection to the given remote system could not be established.

User Response:
Verify that there is a network connection problem to the remote system. Verify that the connection attributes of the remote system (IP address and port) are set correctly.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0016 IO exception when trying to read host message.

An I/O exception on the network socket occurred during the execution of an ISPF dialog application.

User Response:
Disconnect and re-connect to the remote system. Contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Verify that there is no network problem between client and server. Check the z/Server logs for more information.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0017 IO exception when sending a message to the user server.

An I/O exception on the network socket occurred during the execution of an ISPF dialog application.

User Response:
Disconnect and re-connect to the remote system. Contact the administrator.
Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Verify that there is no network problem between client and server. Check the z/Server logs for more information.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0018 Your dialog has timed out. Please restart the dialog.

The given dialog was open for a time interval longer than the configured timeout period without any user interaction.

User Response:
This is an informational message. Restart the ISPF dialog application.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0019 z/Server exception during connection to port: {0} .

An exception occurred during the communication of an ISPF dialog application and its associated user server.

Model Administrator Response:
Check the error log for more information.
Server Administrator Response:
Verify that there is no network problem between client and server. Check the z/Server logs for more information.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0020 No ISPF help available for {0} .

There is no help panel defined for the given ISPF dialog tool.

User Response:
This is an informational message.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0021 User socket is null.

The network socket for the communication with the remote system has become undefined.

Model Administrator Response:
Check the error log for more information. Contact SupportLine.
Parent topic: z/Server ISPF panel support (TSIPS) messages


TSIPS0022 Tool type extension \

A tool type extension could not be found while trying to generate an ISPF model.

User Response:
Try to generate the model again.
Parent topic: z/Server ISPF panel support (TSIPS) messages


z/Server meta model (SOMDL) messages

  • SOMDL0001 Invalid License Checker extension. The referenced class is incompatible with ILicenseChecker: {0}
Parent topic: Error messages


SOMDL0001 Invalid License Checker extension. The referenced class is incompatible with ILicenseChecker: {0}

This exception can be caused by an invalid Eclipse extension from a third party plug-in.

Model Administrator Response:
  • Contact the plug-in contributor to resolve the problem.
  • If the exception was not caused by a third party plug-in, please contact SupportLine.
Parent topic: z/Server meta model (SOMDL) messages


Sample error situations

  • z/Server is not active
  • Connection to z/Server is interrupted
  • Connection problem when connection is active
  • No RACF OMVS segment
  • Model error: wrong Program ID
  • Model error: wrong Panel Name
  • Error situations in an attached tool
Parent topic: Workflow Manager Messages


z/Server is not active

If z/Server is not active on the remote system, an error message similar to the one below is displayed when connecting to z/Server:

zServer not active error

Parent topic: Sample error situations


Connection to z/Server is interrupted

If the network connection between client and remote system is interrupted, an error message similar to the one below is displayed when connecting to z/Server:

Connection interrupted error

When z/Server is not active, the same message is received. The same error message can have different reasons.

Parent topic: Sample error situations


Connection problem when connection is active

When network connection problems occur while already connected to a remote system (z/Server), an error message similar to the one below is displayed:

Active connection error

The connection problem occurred while closing a file in the editor. The action "delete the local copy of the file" could not be executed. The reason is a timeout because of connection problems.

Parent topic: Sample error situations


No RACF OMVS segment

If there is no RACF OMVS segment defined to the TSO user ID used to execute an ISPF tool using an Application Workflow Manager modeled application, the following error message is displayed:

RACF OMVS segment error

This message was issued by z/Server (the remote software), the scheduler address space in particular. The scheduler address space had started the user server address space needed to establish the master configuration data set that contains the ISPF application. That address space did come up, but was unable to signal itself READY to the scheduler address space. Message SLR0131E is issued to the client after a predefined wait period to tell the client that it could not talk to the user server address space.

The administrator for z/Server needs to check for errors. For this particular problem, the z/OS hardcopy log shows:

ICH408I USER(user   ) GROUP(group    ) NAME(####################)
  CL(PROCESS )
  OMVS SEGMENT NOT DEFINED

Job output in user server maintask has this error message again detailing the missing OMVS RACF segment:

TAU0143S  07:35:19.091 This indicates an z/OS UNIX process initialisation failure.
                       This is usually an indication that a proper OMVS RACF segment
                       is not defined for the user ID associated with the application
                       The RACF OMVS segment may not be defined or may contain error
                       such as an improper HOME() directory specification.
TAU0139E  07:35:24.094 SVC with function code 00000800 failed with RC 00000008

In this case, the TSO user ID must be defined with an OMVS segment (usually done by the RACF administrator) as detailed in the z/Server Installation and Reference.

Parent topic: Sample error situations


Model error: wrong Program ID

If the Application Workflow Manager model administrator defined a wrong Program ID in the ISA ISPF Tool relation of a tool descriptor, the following error message is displayed:

Wrong program ID error

Parent topic: Sample error situations


Model error: wrong Panel Name

If the Application Workflow Manager model administrator defined a wrong Panel Name in the ISA ISPF Panel relation of a tool descriptor for an ISPF dialog tool, the following error message is displayed:

Wrong panel name error

Parent topic: Sample error situations


Error situations in an attached tool

If one of the pre-configured Application Workflow Manager models (PDS Explorer, SCLM Application, ChangeMan Application) or custom application models based on the REXX tool adapter TAUTOSAM are used, the attached tools will report error situations in a defined way.

For a deeper understanding of the methods and techniques of Application Workflow Manager tool attachment, please see the Workflow Manager Configuration Guide.

Application Workflow Manager displays an error message when the return code of the attached tool is higher than the value specified by the Application Workflow Manager model administrator under the property Max RC of Application Options in the Application Workflow Manager model. The recommended value for Max RC is 4. Then the following error message is displayed:

Max RC error

Within the message, the return code and message returned by the attached tool are shown.

The following table shows special return codes generally used in pre-configured Application Workflow Manager models, specifically in models based on the REXX tool adapter TAUTOSAM.

Return code | Meaning
0 | Attached tool successfully executed; no message window is displayed.
11 | The return code of the facility called (such as TSO or ISPF) is higher than the maximum return code specified in the facility call. The message contains the command called and the return code produced by the facility. Look up the meaning of the return code in the corresponding IBM book under the command reported by the message.
99 | Undefined variable referenced or syntax error in the attached tool.

In addition to these special return codes, attached tools can return custom created return codes and messages. If the REXX TAUTOSAM is used as a template for custom tool adapters, these custom messages are reported with the same formatting.

The following examples shows the error messages displayed when certain error situations occur within an attached tool.

  • Undefined variable used in the attached tool:

    Undefined variable error

  • Syntax error in the attached tool:

  • Call to ISPF command VGET returns a return code higher than the maximum return code allowed ( 4):

    Looking in REXX TAUPDGJK, the error was produced by a call to ISPF command VGET:

     Call ISPF '0 VGET (ZUSERA) SHARED'

    IBM ISPF Services Guide for the command VGET shows the following under return code 8:

    Variable not found. If the SYMDEF parameter was specified: system symbol not found.
  • Custom return code:

    Custom return code

    The custom tool TOOL_Getdatasets returned with a return code of 12, which is higher than Max RC of 4 specified under Application Options in the Application Workflow Manager model. The message returned by the tool is "This is a customer specific error situation…".

Parent topic: Sample error situations


Known issues

In this topic, known issues and possible workarounds are provided.

The port of a z/Server connection is not remembered

Description:
When a new z/Server connection is created and the Eclipse workbench is exited without connecting to this new connection, the port is set back to the default value 1111 when the Eclipse workbench is re-entered.
Auxiliary solution:
You should always connect to a newly created z/Server connection before exiting the Eclipse workbench.

Change password when connected

Description:
If the Change Password… action is used on a z/Server connection that is actively connected to a remote host, this can lead to subsequent problems.
Auxiliary solution:
Use the Change Password… action only on a z/Server connection that is not connected.

Change code page settings when connected

Description:
If the code page settings of the MVS Explorer are changed on a z/Server connection that is actively connected to a remote host, certain actions won’t work correctly afterwards.
Auxiliary solution:
Change the code page settings only on a z/Server connection that is not connected.

Multi-selection in ISPF table dialogs with non-keyed tables

Description:
In modeled ISPF table dialogs with non-keyed tables, multi-selection of table entries doesn't work correctly.
Auxiliary help:
ISPF table dialogs of non-keyed ISPF tables with multi-selection line commands cannot yet be modeled.
Parent topic: Workflow Manager Messages


zServer messages and Diagnostics

  • Introduction
  • Messages
  • Troubleshooting
Parent topic: Enterprise


Introduction

This document provides a description of messages issued by z/Server including possible corrective actions. Every message has an 8-character identification and an associated message text.

Troubleshooting often requires knowledge of configuration settings, such as the name of the holder task, the scheduler task, and the user server task(s). Please see the z/Server Installation Guide for details about these settings.

Most messages only appear in the JESx job log in different DD names and not in the z/OS hardcopy log. True hardcopy log messages are marked.

  • Message format
  • Error message example
  • Warning message example
  • Information message example
  • Messages and GTF
Parent topic: zServer messages and Diagnostics


Message format

The message identification has the form: pfxnnnns, where:

pfx
The z/Server component prefix (facility ID)

The following facility IDs exist:

ID | z/Server component
API | Application programming interface (TCPIP)
BND | IEWBND (Binder) interface
CSI | Catalog search interface
DSC | Holder task configuration
DYN | Dynamic allocation
EMC | Extended MCS interface
HLD | Holder task interface
IPC | Command task
JES | Job entry subsystem interface
LIC | License interface
MAL | Email interface
REC | Recovery exception handler
REX | REXX command environment
SJB | Started job interface
SLR | TSO scheduler interface
SPR | Standard pool routine
SRV | Server interface
SSI | Interface to z/OS SSI
STA | Started task interface
TAU | Eclipse client interface
UNI | Unicode conversion services
USS | UNIX Interface
XML | XML system parser interface
ZCA | CEA TSO/E address space services
nnnn
The message number for the component, for example, 0051. The message numbers are unique within a component.
s
The message severity:
I
Information
W
Warning
E
Error
S
Severe error

Informational messages are normally used for tracing or debugging purposes. Errors apply to the associated service and are typically caused by incorrect arguments. Severe errors may require z/Server to be restarted.

The message description provides information to identify the cause of the problem. Many messages contain placeholders ([mmm], where mmm is a consecutive number; for example, [002] is the second placeholder). These placeholders are replaced with specific values in the actual message.

The message description may contain messages, return and reason codes, etc. passed from invoked services (for example, the XML system parser or the security product). In these cases, the IBM manual to be consulted for details of the problem is given.

With very few exceptions, the first placeholder ([001]) of each message is the timestamp when the message was issued (hh:mm:ss.ttt):

hh
hour
mm
minutes
ss
seconds
ttt
milliseconds

The explanation for any message states whether the message is issued only at a certain IPTRACE level. The message will be issued at that trace level and higher. Trace levels include all messages from lower trace levels.

Parent topic: Introduction


Error message example

Error messages have severity E or S. There are three general classes of error:
  • Errors caused by incorrect user input, such as incorrect password (SLR0071E) or filter did not find any data sets (CSI0051E). Such errors can be rectified by correcting the input and retrying the action. Some of these error messages can only occur due to incorrect input to the set of z/Server APIs, typically from an Eclipse client.
  • Errors that indicate problems in the configuration file, such as EMC0011E (port is not available). Such errors may be corrected by changing the configuration (a task for the system administrator), although they can also indicate some other error that needs to be investigated (also a task for the system administrator).
  • Errors that indicate an internal z/Server error, such as API0007E (error during call to EZASOKET). If the message information provided does not help to identify the problem, please contact SupportLine.

As an example, the CSI0051E message is issued by the CSI facility (CSI prefix) and has a severity of E (=error).

The message is shown as follows in this book:

CSI0051E [001] No data sets for filter [002] found

This message has two placeholders: [001] and [002]. The placeholders are replaced with the timestamp and the associated filter. An actual CSI0051E error message would look like this:

CSI0051E 07:48:53.935 No data sets for filter SYS2 found

The two placeholders have been replaced with the time (07:48) and the filter (SYS2) that could not be resolved. In this case, using a filter that covers available data sets would prevent the error message.

Parent topic: Introduction


Warning message example

Warning messages have severity W. Such messages are normally written to the associated JESx DD name; see below. Warnings normally indicate that some standard action has been taken. If this action or default is not required or wanted, change the appropriate setting.

TAU0019W  09:14:05.443 Environment-Variable REATTACH was not specified, using defaults !
TAU0019W  09:14:05.651 Environment-Variable CCSID was not specified, using defaults !
TAU0019W  09:14:05.652 Environment-Variable TSOE_JOB_CLASS was not specified, using defaults !
TAU0019W  09:14:05.652 Environment-Variable TSOE_SCHED_TAB was not specified, using defaults !
LIC0007W  09:14:05.659 This server may only be used through a licensed client.
Parent topic: Introduction


Information message example

Information messages have severity I. Such messages are normally written to the associated JESx DD name; see below.

SLR0111I  09:14:05.998 TSO/E-Scheduler Init/Term-Routine called with function START
SLR0001I  09:14:06.170 TSO-Scheduler   initialization
HLD0030I  09:14:06.188 User administration ended with RC 00000000 (hex)
Parent topic: Introduction


Messages and GTF

For debugging purposes, we recommend you start GTF and trace user records x'3E8'.

Note, however, that as a result, there will be significantly fewer messages written to the JESx spool. Most messages will be written to GTF only, regardless of the IPTRACE level being set. Using only the messages remaining in the hardcopy log and the JESx job log, it may get difficult to follow what happens within z/Server.

Parent topic: Introduction


Messages

  • API - Application Programming Interface
  • BND - IEWBIND (Binder) Interface
  • CSI - Catalog Search Interface
  • DSC - Holder Task Configuration
  • DYN - Dynamic Allocation
  • EMC - Extended MCS Interface
  • HLD - Holder Task Interface
  • IPC - Command Task
  • JES - Job Entry Subsystem Interface
  • LIC - License Interface
  • MAL - Email Interface
  • REC - Recovery Exception Handler
  • REX - REXX Interface
  • SJB - Started Job
  • SLR - TSO Scheduler Interface
  • SPR - Standard Pool Routine
  • SRV - Server Interface
  • SSI - Subsystem Interface Routine
  • STA - Started Task Interface
  • TAU - Eclipse Client Interface
  • UNI - Unicode code conversion services
  • XML - XML System Parser Interface
  • CEA TSO/E Address Space Services
  • ABEND Code U2222
  • Language Environment abends
Parent topic: zServer messages and Diagnostics


API - Application Programming Interface

All API messages are issued by TAURIP03. It is used as an interface for all TCPIP communication. Standard return codes are described in the table below. This interface is called using z/Server API calls, both internally and externally.

Return Code | Meaning
00 | Function completed successfully.
-4 | Invalid parameter list or last parameter not 'I' or 'T' or timeout < 0.
-8 | Connection closed.
-12 | Timeout during receive.
-20 | Program is not running in a server environment.
-24 | Invalid parameter list.
-28 | Function not allowed in a server environment.
-36 | Only 1 TCB allowed in a non-LE environment
-40 | Invalid value for compress.
-44 | Invalid value for dump.
-48 | Invalid value for version set.
-100*n | Name/token pair not found for non-LE environment; n is the return code from macro IEANTRT.
>0 | Original error number from EZASOKET call.
  • API0001I
  • API0002I
  • API0007E
  • API0008I
  • API0009E
  • API0010I
  • API0011I
  • API0015I
  • API0054S
  • API0065I
  • API0069E
  • API0072W
  • API0076I
  • API0099I
  • API0106W
  • API0107E
  • API0108W
  • API0109I
  • API0110I
  • API0111I
Parent topic: Messages


API0001I

API0001I  hh:mm:ss.ttt Before call IP03 starting call in [002] environment.
                       Function code:  [003]
                       Task area:      [004] [005]
Explanation:
[002] is either server or client.

[003] is described in SC31-8788 z/OS Communications Server IP Sockets Application Programming Interface Guide and Reference.

[004] is the address of the task area.

[005] is global (if [002] is server), otherwise local (if [002] is client)

Issued by:
TAURIP03
User reponse:
None.
Parent topic: API - Application Programming Interface


API0002I

API0002I  hh:mm:ss.ttt After call IP03 ending call. RC is: [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0007E

API0007E  hh:mm:ss.ttt Error during call to EZASOKET.
                       Function   : [002]
                       Reason code: [003]
Explanation:
This message is issued when IPTRACE level 4 is set. See SC31-8788 z/OS Communications Server IP Sockets Application Programming Interface Guide and Reference for details about the function used and the returned error.
Issued by:
TAURIP03
System administrator response:
Determine why the error occurred. If necessary, contact SupportLine.
Parent topic: API - Application Programming Interface


API0008I

API0008I  hh:mm:ss.ttt Timeout for SELECT is [002] seconds and [003] microseconds.
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0009E

API0009E  hh:mm:ss.ttt For function PeekMsg the sixth parameter must be 'P'.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP03
User response:
Correct the calling program.
Parent topic: API - Application Programming Interface


API0010I

API0010I  hh:mm:ss.ttt Using static z/Server environment for client processing at address [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0011I

API0011I  hh:mm:ss.ttt Message flags: [002]
                       1...  ....   Message is encrypted
                       .1..  ....   Message is from a dialog
                       ...1  ....   Message has no IP-Header
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0015I

API0015I  hh:mm:ss.ttt Before call [002] descriptor in hex [003].
Explanation:
This is an informational message due to IPTRACE level 4 being set.

[002] is one of the functions described in SC31-8788 z/OS Communications Server IP Sockets Application Programming Interface Guide and Reference: INITAPI, SOCKET, CONNECT, CLOSE, TERMAPI, WRITE, RECV, SELECT, SO_LINGER, GETTASKAREA, GETHOSTID, SETTIMEOUT, SETBUFFERSIZE, SETCOMPRESSION or TAKESOCKET.

Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0054S

API0054S  hh:mm:ss.ttt Terminating subtask with dump.
Explanation:
The subtask terminates and writes a dump.

System administrator response:
Determine why the subtask terminated. If necessary, contact SupportLine.
Parent topic: API - Application Programming Interface


API0065I

API0065I  hh:mm:ss.ttt After call to [002] RC: [003] ERRNO: [004]
Explanation:
This is an informational message due to IPTRACE level 4 being set.

[002] is one of the functions described in SC31-8788 z/OS Communications Server IP Sockets Application Programming Interface Guide and Reference: INITAPI, SOCKET, CONNECT, CLOSE, TERMAPI, WRITE, RECV, SELECT, SO_LINGER, GETTASKAREA, GETHOSTID, SETTIMEOUT, SETBUFFERSIZE, SETCOMPRESSION or TAKESOCKET.

Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0069E

API0069E  hh:mm:ss.ttt Function code [002] is not supported.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP03
User response:
Use a supported function code.
Parent topic: API - Application Programming Interface


API0072W

API0072W hh:mm:ss.ttt Connection is closed and no data is available
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0076I

API0076I  hh:mm:ss.ttt Flushing input Buffer.  [002] Bytes available.
Explanation:

[002] is number of bytes available.

Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0099I

API0099I ======================================================
          [001]
===============================================================
Explanation:
This is a separator line for the output. It is issued when IPTRACE level 4 is set.

[001] can have the values Socket Communication Area, Data received, Data written, ECB-Table-Entry and Data received after expand.

Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0106W

API0106W  hh:mm:ss.ttt Negative length for receiving [002] bytes specified.
                       Multiple reads are forced until specified length is reached.
Explanation:
This is an informational message due to IPTRACE level 4 being set. Also, it has meaning for API calls only.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0107E

API0107E  hh:mm:ss.ttt Function code [002] is not allowed in a server environment.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP03
User response:
Correct the program.
Parent topic: API - Application Programming Interface


API0108W

API0108W  hh:mm:ss.ttt Delimiter >>[002]<< (hex) is specified.
                       Multiple reads are forced until specified delimiter is found.
Explanation:
This is an informational message due to IPTRACE level 4 being set. Also, it has meaning for API calls only.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0109I

API0109I  hh:mm:ss.ttt Input  message area for client allocated at [002]
                       Output message area for client allocated at [003]
                       Work   message area for client allocated at [004]
                       Each area is [005] bytes long
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0110I

API0110I  hh:mm:ss.ttt Change buffer size for client.
Explanation:
This is an informational message.
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


API0111I

API0111I  hh:mm:ss.ttt Name of IP stack to be addressed changed to [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued when the TAU utility is used (z/OS driver).
Issued by:
TAURIP03
User response:
None.
Parent topic: API - Application Programming Interface


BND - IEWBIND (Binder) Interface

All BND messages are issued by TAURIP49. z/Server uses the IEWBIND service to process load modules (for details, see SA22-7644-xx: MVS Program Management: Advanced Facilities). This interface is called using z/Server API calls.

  • BND0001E
  • BND0002I
  • BND0003I
  • BND0004E
  • BND0005E
  • BND0006I
Parent topic: Messages


BND0001E

BND0001E  hh:mm:ss.ttt Error during call of IEWBIND with function [002]
                       Return code was: [003] (hex)
                       Reason code was: [004] (hex)
Explanation:
The IEWBIND call failed.
Issued by:
TAURIP49
User response:
See SA22-7644-xx: MVS Program Management: Advanced Facilities to determine why the call failed.
Parent topic: BND - IEWBIND (Binder) Interface


BND0002I

BND0002I  hh:mm:ss.ttt Binder utility called with command [002]
                       For dataset [003]
                       And member  [004]
                       Class       [005]
                       Section     [006]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP49
User response:
None.
Parent topic: BND - IEWBIND (Binder) Interface


BND0003I

BND0003I  hh:mm:ss.ttt Binder utility ended with RC [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP49
User response:
None.
Parent topic: BND - IEWBIND (Binder) Interface


BND0004E

BND0004E  hh:mm:ss.ttt Buffer with [002] bytes is too small for the binder interface. A minimum of [003] bytes are required.
Explanation:
Self-explanatory.

Issued by:
TAURIP49
System administrator response:
Increase the buffer size; see BUFFERSIZE/BUFFERUNIT in the z/Server Installation Guide.
Parent topic: BND - IEWBIND (Binder) Interface


BND0005E

BND0005E  hh:mm:ss.ttt Unknown class [002] for binder utility.
Explanation:
Self-explanatory.
Issued by:
TAURIP49
User response:
Use a defined class. If necessary, contact SupportLine.
Parent topic: BND - IEWBIND (Binder) Interface


BND0006I

BND0006I ===========================================================
          Header for Class :     [002]    and Section [003]
====================================================================
Explanation:
This is an informational message due to IPTRACE level 5 being set.

[002] is the binder class name from the link listing.

[003] is the section name from the link listing.

Issued by:
TAURIP49
User response:
None.
Parent topic: BND - IEWBIND (Binder) Interface


CSI - Catalog Search Interface

z/Server uses the IGGCSI00 service to access the catalog (for details, see SC26-7409-xx: z/OS DFSMS Managing Catalogs). Many z/Server API calls involving data set filters result in the use of this interface.

  • CSI0001E
  • CSI0002I
  • CSI0003E
  • CSI0004I
  • CSI0005I
  • CSI0006I
  • CSI0007I
  • CSI0008E
  • CSI0009I
  • CSI0010E
  • CSI0011I
  • CSI0012E
  • CSI0013E
  • CSI0014W
  • CSI0015I
  • CSI0016E
  • CSI0017I
  • CSI0018I
  • CSI0019I
  • CSI0020E
  • CSI0021E
  • CSI0022E
  • CSI0023E
  • CSI0024E
  • CSI0025E
  • CSI0026I
  • CSI0027I
  • CSI0028I
  • CSI0029E
  • CSI0030W
  • CSI0031I
  • CSI0032I
  • CSI0033E
  • CSI0034I
  • CSI0035E
  • CSI0036E
  • CSI0037E
  • CSI0038E
  • CSI0039E
  • CSI0040I
  • CSI0041I
  • CSI0042E
  • CSI0043I
  • CSI0044E
  • CSI0045E
  • CSI0046E
  • CSI0047E
  • CSI0048E
  • CSI0049I
  • CSI0050E
  • CSI0051E
  • CSI0052E
  • CSI0053E
  • CSI0054I
  • CSI0055E
  • CSI0056E
  • CSI0057E
  • CSI0058E
  • CSI0059E
  • CSI0060E
  • CSI0061I
  • CSI0062I
  • CSI0063E
  • CSI0064E
  • CSI0065E
  • CSI0066I
  • CSI0067I
  • CSI0069I
  • CSI0070I
  • CSI0071E
  • CSI0072I
Parent topic: Messages


CSI0001E

CSI0001E  hh:mm:ss.ttt Error during call of IGGCSI00.
                       Return code: [002] (hex)
                       Reason code: [003] (hex)
                       see DFSMS Managing Catalogs for more information
Explanation:
The IGGCSI00 service failed. Refer to message IDC3009I in SA22-7636-xx: MVS System Messages Volume 6 (GOS - IEA) for information on the return and reason codes.
Issued by:
TAURIP22
System administrator response:
Determine why the service failed. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0002I

CSI0002I =====================================================
          [002]
==============================================================
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0003E

CSI0003E  hh:mm:ss.ttt Invalid entry type [002] found.
Explanation:
The entry type described by [002] is invalid.
Issued by:
TAURIP22
System administrator response:
Determine why an invalid entry type was used. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0004I

CSI0004I hh:mm:ss.ttt Entry [002] of type [003] found.
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0005I

CSI0005I hh:mm:ss.ttt Data for entry (hex): [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0006I

CSI0006I  hh:mm:ss.ttt Catalog utility called with command [002]
                       Data set filter: [003]
                       Member   filter: [004]
                       Catalog   flags: [005]    (hex)
                       1... ....   recall if data set is migrated
                       .1.. ....   return userdata with member list
                       ..1. ....   wait for until recall of data set is complete
                       ...1 ....   filter for MEMLIST specified
                       .... 1...   member for GETDATA specified
                       .... .1..   create ENQ
                       .... ..1.   create DEQ
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0007I

CSI0007I hh:mm:ss.ttt [002] Entries found
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0008E

CSI0008E  hh:mm:ss.ttt Dynalloc failed for DDname [002]
                       Verb           :  [003]
                       S99RC          :  [004]
                       S99ERROR       :  [005]
                       S99INFO        :  [006]
                       S99ERSN        :  [007]
                       Dataset        :  [008]
Explanation:
The requested data set could not be allocated.
Issued by:
TAURIP28, TAURIP35, TAURIP48, TAURIP49
System administrator response:
See SA22-7608-xx: MVS Programming Authorized Assembler Services Guide (DYNALLOC macro) for details on the returned information. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0009I

CSI0009I hh:mm:ss.ttt DSCB for data set [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP15
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0010E

CSI0010E hh:mm:ss.ttt Empty data set filter is not allowed.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Specify the correct filter.
Parent topic: CSI - Catalog Search Interface


CSI0011I

CSI0011I hh:mm:ss.ttt Memlist utility called with data set [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued in response to an API call.
Issued by:
TAURIP28
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0012E

CSI0012E hh:mm:ss.ttt Member list valid only for partitioned data sets.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Perform the function against a member of a PO data set.
Parent topic: CSI - Catalog Search Interface


CSI0013E

CSI0013E hh:mm:ss.ttt Obtain of DSCB information of data set [002] failed RC [003].
Explanation:
Data set information could not be retrieved.
Issued by:
TAURIP15
System administrator response:
See SC26-7400-xx: DFSMSdfp Advanced Services under Return Codes from OBTAIN (Reading by Data Set Name). If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0014W

CSI0014W  hh:mm:ss.ttt DSCB information or member list for data set [002]
                      is not available because data set is migrated.
Explanation:
This is an informational message due to IPTRACE level 2 being set. It is issued in response to an API call.
Issued by:
TAURIP15
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0015I

CSI0015I ===========================================================
         DSEB with length [001]
====================================================================
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP28
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0016E

CSI0016E  hh:mm:ss.ttt HSM function [002] for data set [003]
                       failed with RC [004].
                       See message ARC11xx for return codes.
Explanation:
ARCHRCAL macro call failed.
Issued by:
TAURIP31
System administrator response:
See SC35-0420-xx: DFSMShsm Managing Your Own Data for details on the return code. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0017I

CSI0017I hh:mm:ss.ttt Recall utility called for data set [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP31
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0018I

CSI0018I hh:mm:ss.ttt Catalog utility ended with RC [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0019I

CSI0019E  hh:mm:ss.ttt For command [002] the data set type must be A and DSORG must be PO or PS.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Use the correct data set type.
Parent topic: CSI - Catalog Search Interface


CSI0020E

CSI0020E hh:mm:ss.ttt For command [002] the record format must be F or V.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Use the correct record format.
Parent topic: CSI - Catalog Search Interface


CSI0021E

CSI0021E hh:mm:ss.ttt A member must be specified for a partitioned data set.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Specify the appropriate member.
Parent topic: CSI - Catalog Search Interface


CSI0022E

CSI0022E hh:mm:ss.ttt Do not specify a member name for a sequential data set.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Do not specify a member.
Parent topic: CSI - Catalog Search Interface


CSI0023E

CSI0023E hh:mm:ss.ttt Data set/member [002] is in use.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP35
User response:
Wait until data set/member becomes available.
Parent topic: CSI - Catalog Search Interface


CSI0024E

CSI0024E hh:mm:ss.ttt Buffer size [002] (hex) is too small to hold all data. Read terminated after [003] records.
Explanation:
Self-explanatory.
Issued by:
TAURIP35, TAURIP45, TAURIP48, TAURIP49
System administrator response:
Increase buffer size; see BUFFERSIZE/BUFFERUNIT in the z/Server Installation Guide.
Parent topic: CSI - Catalog Search Interface


CSI0025E

CSI0025E hh:mm:ss.ttt Data set open for function [002] was not successful.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP35, TAURIP48
System administrator response:
Determine why OPEN failed. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0026I

CSI0026I  hh:mm:ss.ttt GetData/PutData utility called with command [002].
                       for Data set [003]
                       Member       [004]
                       CCSID        [005]
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued in response to an API call.
Issued by:
TAURIP35, TAURIP48
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0027I

CSI0027I hh:mm:ss.ttt GetData/PutData utility ended with RC [002].
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued in response to an API call.
Issued by:
TAURIP35, TAURIP48
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0028I

CSI0028I  hh:mm:ss.ttt Data for PutData at address [002] with length [003]
                       LRECL is [004]. RECFM is [005].
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued in response to an API call.
Issued by:
TAURIP35
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0029E

CSI0029E hh:mm:ss.ttt Length for PutData is invalid. Length must be a multiple of [002].
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP35
User response:
Use the correct length for PutData.
Parent topic: CSI - Catalog Search Interface


CSI0030W

CSI0030W  hh:mm:ss.ttt Command task is busy. Enqueue/dequeue not possible. Please retry in a few moments.
Explanation:
Enqueue and dequeue system services are issued by the CMDTASK in either the scheduler or a user server. That task was busy with another command when the request came in.
Issued by:
TAURIP35
User response:
If this message was issued in response to an API call, retry the request. Otherwise, check why the command task does not respond. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0031I

CSI0031I  hh:mm:ss.ttt Racroute REQUEST=AUTH failed with
                       RC: [002], RSN: [003]
Explanation:
This message is issued due to IPTRACE level 4 being set. See SA22-7692-xx: Security Server RACROUTE Macro Reference.
Issued by:
TAURIP22
System administrator response:
Determine why the request failed. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0032I

CSI0032I hh:mm:ss.ttt [002] records successfully written.
Explanation:
Self-explanatory.
Issued by:
TAURIP35
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0033E

CSI0033E hh:mm:ss.ttt Attribute FIXED is not allowed for variable record length.
Explanation:
This message is issued in response to an API call.

Issued by:
TAURIP22
User response:
Use the correct attributes for variable record lengths.
Parent topic: CSI - Catalog Search Interface


CSI0034I

CSI0034I hh:mm:ss.ttt Dequeue successful.
Explanation:
This is an informational message.
Issued by:
TAURIP35
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0035E

CSI0035E  hh:mm:ss.ttt Request for shared access to data set [002]
                       failed because resource is in exclusive use by [003]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP28
User response:
Wait until [003] has given up exclusive use of the requested data set.
Parent topic: CSI - Catalog Search Interface


CSI0036E

CSI0036E hh:mm:ss.ttt GQSCAN macro failed with RC [002]
Explanation:
See SA22-7610-xx: MVS Programming: Authorized Assembler Services Reference, Volume 2 (EDT-IXG) for the return code. RC=8 usually means that the resource to be freed via operator command was not held in the first place.
Issued by:
TAURIP28
System administrator response:
Determine why GQSCAN failed. If necessary, contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0037E

CSI0037E hh:mm:ss.ttt [002] access for data set [003] not permitted.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Ask the RACF administrator in your installation for the required access privileges.
Parent topic: CSI - Catalog Search Interface


CSI0038E

CSI0038E  hh:mm:ss.ttt Data set [002] not migrated.
                       Recall not allowed.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0039E

CSI0039E  hh:mm:ss.ttt Requested data set unavailable. The data set is
allocated to another job and its usage attribute conflicts   with
         this request.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP35, TAURIP48, TAURIP49
User response:
Wait until the data set becomes available.
Parent topic: CSI - Catalog Search Interface


CSI0040I

CSI0040I hh:mm:ss.ttt HSM function [002] for data set [003] ended successfully.
Explanation:
This is an informational message.
Issued by:
TAURIP31
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0041I

CSI0041I hh:mm:ss.ttt HSM function [002] for data set [003] successfully queued. Nowait was specified.
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP31
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0042E

CSI0042E  hh:mm:ss.ttt Data set to submit must be defined with fixed length 80.
                       RECFM=F/FB and LRECL=80
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Either reallocate the data set to be submitted from or use a data set with the correct attributes: RECFM=F/FB and LRECL=80.
Parent topic: CSI - Catalog Search Interface


CSI0043I

CSI0043I hh:mm:ss.ttt Job with jobid [002] submitted.
Explanation:
This is an informational message.

Issued by:
TAURIP35
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0044E

CSI0044E hh:mm:ss.ttt ISPF packed format is not supported
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP35
User response:
Use a data set that does not use ISPF packed format.
Parent topic: CSI - Catalog Search Interface


CSI0045E

CSI0045E hh:mm:ss.ttt Invalid token [002] in compressed record found.
Explanation:
Self-explanatory.
Issued by:
TAURIP45
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0046E

CSI0046E hh:mm:ss.ttt LRECL of uncompressed record ([002] bytes) is greater than LRECL with ([003] bytes).
Explanation:
Self-explanatory.
Issued by:
TAURIP45
User response:
Determine why an uncompressed record is shorter than its compressed version.
Parent topic: CSI - Catalog Search Interface


CSI0047E

CSI0047E hh:mm:ss.ttt Binder information is only allowed for data sets with RECFM U
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Do not use this function for data sets that are not allocated with RECFM=U.
Parent topic: CSI - Catalog Search Interface


CSI0048E

CSI0048E  hh:mm:ss.ttt Length of JCL or REXX is invalid.
                       Length is zero or not a multiple of 80.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Either reallocate the data set or use a data set with the correct attributes.
Parent topic: CSI - Catalog Search Interface


CSI0049I

CSI0049I hh:mm:ss.ttt Job with jobid [002] successfully submitted.
Explanation:
This is an informational message.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0050E

CSI0050E  hh:mm:ss.ttt For PUTJCL an ACEE is required at the CB level for userid [002]. You must activate task level security in the IP
         header.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP12
User response:
Activate task level security in the IP header of the calling program.
Parent topic: CSI - Catalog Search Interface


CSI0051E

CSI0051E hh:mm:ss.ttt No data sets found for filter [002].
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
If necessary, correct the filter specification.
Parent topic: CSI - Catalog Search Interface


CSI0052E

CSI0052E hh:mm:ss.ttt Generic filter is not allowed for command [002].
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Correct the filter specification.
Parent topic: CSI - Catalog Search Interface


CSI0053E

CSI0053E hh:mm:ss.ttt Entry [002] is returned with error code [003].
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0054I

CSI0054I  hh:mm:ss.ttt Find utility called for member [002].
                       Function flags:  [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued in response to an API call.
Issued by:
TAURIP91
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0055E

CSI0055E hh:mm:ss.ttt No data sets specified for command [002]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP91
User response:
Specify a data set.
Parent topic: CSI - Catalog Search Interface


CSI0056E

CSI0056E hh:mm:ss.ttt DESERV function [002] ended with RC [003] and RSN [004].
Explanation:
DESERV macro call failed; see SC26-7410-xx: DFSMS Using Data Sets for details on the return code.
Issued by:
TAURIP91
User response:
Determine why the macro call failed.
Parent topic: CSI - Catalog Search Interface


CSI0057E

CSI0057W hh:mm:ss.ttt Member [002] not found.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP91
User response:
Specify an existing member of this data set.
Parent topic: CSI - Catalog Search Interface


CSI0058E

CSI0058E hh:mm:ss.ttt Data set [002] is migrated. Command [003] not possible.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Do not use function [003] on a migrated data set.
Parent topic: CSI - Catalog Search Interface


CSI0059E

CSI0059E hh:mm:ss.ttt Data set saved, but at least one record was truncated to [002] bytes.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP35
User response:
Validate the data set definition.
Parent topic: CSI - Catalog Search Interface


CSI0060E

CSI0060E  hh:mm:ss.ttt An invalid filter key was provided.
                       Filter was : [002]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP22
User response:
Validate the filter key; the filter key should comply with MVS data set naming conventions.
Parent topic: CSI - Catalog Search Interface


CSI0061I

CSI0061I hh:mm:ss.ttt Encrypting data to BASE64
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP35
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0062I

CSI0062I hh:mm:ss.ttt Decrypting data from BASE64
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP35
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0063E

CSI0063E hh:mm:ss.ttt Encrypt/decrypt for BASE64 failed.
Explanation:
Self-explanatory.
Issued by:
TAURIP35
User response:
Determine why de- or encryption failed.
Parent topic: CSI - Catalog Search Interface


CSI0064E

CSI0064E hh:mm:ss.ttt Dequeue for Dataset/Member [002] failed.
Explanation:
This message is issued if a dequeue for major name SPFEDIT and minor name [002] fails. This message does not force an error.
Issued by:
TAURIP35
User response:
Determine why the dequeue failed. There might be no preceding enqueue.
Parent topic: CSI - Catalog Search Interface


CSI0065E

CSI0065E hh:mm:ss.ttt Dequeue failed with RC  [002]. Possible reason
                      Enqueue does not exists
                      Enqueue was not made from Server  [003] and user  [004]
Explanation:
This message is issued if a dequeue of a resource was not successful. This message does not force an error.
Issued by:
TAURIP35
User response:
Determine why the dequeue failed. There might be no preceding enqueues.
Parent topic: CSI - Catalog Search Interface


CSI0066I

CSI0066I hh:mm:ss.ttt z/Server STOW routine called with function [002]
                      for member [003] and data set [004]
Explanation:
This is an informational message due to IPTRACE level 5 being set. This message is only written if the z/Server is customized to maintain ISPF statistics.
Issued by:
TAURSTOW
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0067I

CSI0067I hh:mm:ss.ttt [002] ISPF statistics
Explanation:
This is an informational message due to IPTRACE level 5 being set. This message is only written if the z/Server is customized to maintain ISPF statistics. [002] may be CREATE or UPDATE.
Issued by:
TAURSTOW
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0069I

CSI0069I hh:mm:ss.ttt -----------------------------------------------------
                      Current user data
                      -----------------------------------------------------
Explanation:
This is an informational message due to IPTRACE level 5 being set. This message is only written if the z/Server is customized to maintain ISPF statistics.
Issued by:
TAURSTOW
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0070I

CSI0070I hh:mm:ss.ttt -----------------------------------------------------
                      New directory entry
                      -----------------------------------------------------
Explanation:
This is an informational message due to IPTRACE level 5 being set. This message is only written if the z/Server is customized to maintain ISPF statistics. After this message the new directory entry is written in dump format.
Issued by:
TAURSTOW
User response:
None.
Parent topic: CSI - Catalog Search Interface


CSI0071E

CSI0071E hh:mm:ss.ttt Stow macro failed with RC [002] Reason [003]
                      Member      :  [004]
                      Dataset     :  [005]
Explanation:
This message is written if z/Server is customized to maintain ISPF statistics. The update of a directory entry failed. See DFSMS Macro Instructions for Data Sets SC26-7408-xx for more information.
Issued by:
TAURSTOW
User response:
Set the trace level to 6 and try to recreate the problem. Contact SupportLine.
Parent topic: CSI - Catalog Search Interface


CSI0072I

CSI0072I hh:mm:ss.ttt DIRDATA  [002] contains invalid hex values.
Explanation:
Self-explanatory.
Issued by:
TAURSTOW
User response:
Parent topic: CSI - Catalog Search Interface


DSC - Holder Task Configuration

All DSC messages are issued by TAUHOLD when the configuration file for the holder task IVPHOLD contains invalid statements. They are found in DD statement SYSTSPRT of the holder task.

  • DSC0001E
  • DSC0002E
  • DSC0003E
  • DSC0004E
  • DSC0005E
  • DSC0008E
  • DSC0009E
  • DSC0020E
  • DSC0022E
  • DSC0023W
  • DSC0024W
  • DSC0025W
  • DSC0026W
  • DSC0027E
  • DSC0099I
  • DSC0100E
  • DSC0101I
  • DSC0102I
  • DSC0200E
Parent topic: Messages


DSC0001E

DSC0001E Name required for variable [001]
Explanation:
Variable [001] is one of the following: SVC_PGM, DSP_NAME or CON_NAME.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0002E

DSC0002E Name of [001] is greater than 8 bytes.
Explanation:
Variable [001] is one of the following: SVC_PGM, DSP_NAME or CON_NAME.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0003E

DSC0003E Value required for variable [001]
Explanation:
Variable [001] is one of the following: SVC_NO, CON_QLIMIT, DSP_SIZE, DSP_PORT_LOW, DSP_PORT_High or DSP_MAX_SERV.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0004E

DSC0004E Value for variable [001] is not numeric
Explanation:
Variable [001] is one of the following: SVC_NO, CON_QLIMIT, DSP_SIZE, DSP_PORT_LOW, DSP_PORT_High or DSP_MAX_SERV.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0005E

DSC0005E Value of [001] not between [002] and [003]
Explanation:
Valid combinations for [001], [002] and [003] are:
[001] | [002] | [003]
SVC_NO | 200 | 255
CON_QLIMIT | 100 | 999
DSP_SIZE | 1 | 1000
DSP_PORT_LOW | 1 | 64000
DSP_PORT_High | 1 | 64000
DSP_MAX_SERV | 1 | 20
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0008E

DSC0008E Name required for variable [001]
Explanation:
Variable [001] is one of the following: DSP_TOKEN or CON_TOKEN.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0009E

DSC0009E Name of [001] is greater than 16 bytes
Explanation:
Variable [001] is one of the following: DSP_TOKEN or CON_TOKEN.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0020E

DSC0020E DSP_PORT_HIGH is smaller than DSP_PORT_LOW
Explanation:
Self-explanatory.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0022E

DSC0022E Scheduler name <Server.x> has more than 8 chars
Explanation:
Self-explanatory.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0023W

DSC0023W Parameter IPTRACE not a positive integer. IPTRACE ignored.
Explanation:
Self-explanatory.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0024W

DSC0024W Parameter DELAY not a positive integer. Default used.
Explanation:
Self-explanatory.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0025W

DSC0025W Parameter DELAY out of range. Default used.
Explanation:
Self-explanatory.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DSC0026W

DSC0026W Maximum number of schedulers started. Further scheduler names ignored.
Explanation:
Self-explanatory.
System administrator response:
Correct the SERVER.x statement. The holder task starts.
Parent topic: DSC - Holder Task Configuration


DSC0027E

DSC0027E DSP_MAX_SERV should be at least [001]. Unable to start requested schedulers.
Explanation:
The number of schedulers specified via Server.x statements exceeds the number of schedulers allowed for this holder task. Start-up is terminated.
System administrator response:
Increase the value for DSP_MAX_SRV to at least [001].
Parent topic: DSC - Holder Task Configuration


DSC0099I

DSC0099I Configuration of z/Server holder task [001].
Explanation:
The value of [001] can be:
  • Started
  • ended with RC [002]
System administrator response:
None.
Parent topic: DSC - Holder Task Configuration


DSC0100E

DSC0100E Error during interpretation of configuration file. RC [001]
Explanation:
Self-explanatory.
System administrator response:
Determine why the error occurred.
Parent topic: DSC - Holder Task Configuration


DSC0101I

DSC0101I Line [001]
Explanation:
Self-explanatory.
System administrator response:
Determine why the error occurred.
Parent topic: DSC - Holder Task Configuration


DSC0102I

DSC0102I Config [001]
Explanation:
Self-explanatory.
System administrator response:
Determine why the error occurred.
Parent topic: DSC - Holder Task Configuration


DSC0200E

DSC0200E Invalid value for [001] (not YES or NO)
Explanation:
Variable [001] is one of the following: DSP_CREATE, SVC_INSTALL, CON_INSTALL or ADD_SERVER.
System administrator response:
Correct the statement in error.
Parent topic: DSC - Holder Task Configuration


DYN - Dynamic Allocation

  • DYN0006E
  • DYN0007E
Parent topic: Messages


DYN0006E

DYN0006E hh:mm:ss.ttt Dynalloc failed with RC  [002].
                      Error-Code :  [003]
                      Info-Code  :  [004]
                      Message    :
         [005]
Explanation:
This message is written if a dynalloc SVC99 has failed.
User response:
See the Authorized Assembler Services Guide SA22-7608-xx for more information. Contact SupportLine and provide all the available output. If possible, try to recreate the problem with trace level 6.
Issued by:
TAURIP85
Parent topic: DYN - Dynamic Allocation


DYN0007E

DYN0007E hh:mm:ss.ttt Call to DAIRFAIL routine IKJEFF18 failed with RC  [002]
Explanation:
A call to the DAIRFAIL routine to analyze return codes from dynamic allocation (SVC 99) has failed.

Issued by:
TAURIP85
User response:
See TSO/E Programming Services SA22-7789-xx for more information. Contact SupportLine and provide all available output. If possible, try to recreate the problem with trace level 6.
Parent topic: DYN - Dynamic Allocation


EMC - Extended MCS Interface

z/Server establishes an EMCS console to issue commands to the operating system z/OS. Command responses received through this interface are parsed. If problems are detected, they are reported via messages with the EMC prefix.

  • EMC0001E
  • EMC0002I
  • EMC0003E
  • EMC0004E
  • EMC0005I
  • EMC0006E
  • EMC0007E
  • EMC0008I
  • EMC0009I
  • EMC0010W
  • EMC0011E
  • EMC0012E
  • EMC0013I
  • EMC0014E
  • EMC0015I
  • EMC0016I
  • EMC0017I
  • EMC0018I
  • EMC0019I
  • EMC0020I
  • EMC0021I
  • EMC0022E
  • EMC0023E
Parent topic: Messages


EMC0001E

EMC0001E hh:mm:ss.ttt [002] for EMCS console failed
                       Major-Name   : [003]
                       Minor-Name   : [004]
Explanation:
Self-explanatory.
Issued by:
TAURIP56
System administrator response:
Determine why the EMCS console failed. If necessary, contact SupportLine.
Parent topic: EMC - Extended MCS Interface


EMC0002I

EMC0002I hh:mm:ss.ttt Command for EMCS console is
                     [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0003E

EMC0003E hh:mm:ss.ttt SVC failed for function [002] with RC [003] (hex).
Explanation:

Function [002] (low-order byte):

X'01'
RACROUTE
X'02'
SSICALL
X'03'
CMD for ECMD
X'04'
Internal start
X'06'
Activate EMCS Console
X'07'
Deactivate EMCS Console
X'08'
Command without CART
X'10'
Command with CART
X'18'
Send command to console
X'20'
Get next message
X'40'
Get next command response
X'80'
Get response with CART (command and response token)
X'E0'
Get response from EMCS

Return code [003]:

0-250
RACF return code
252
Callers’ address space is not authorized to call this SVC
253
No task level security environment to delete
254
R1 does not point to a valid TAURACFA control block on entry to SVC routine
255
Address Space has no ACEE
256
Invalid function code
257
Console buffer is too small
Issued by:
TAURIP56
System administrator response:
Determine why the call failed. If necessary, contact SupportLine.
Parent topic: EMC - Extended MCS Interface


EMC0004E

EMC0004E  hh:mm:ss.ttt Function [002] for EMCS console failed with
                       IPSCA_CONSRC was : [003]    (hex)
                       IPSCA_CONSRE was : [004]    (hex)
Explanation:
Self-explanatory. For [002] function (low-order byte), see EMC0003E.
Issued by:
TAURIP56
System administrator response:
Check why the EMCS console failed.
Parent topic: EMC - Extended MCS Interface
Related information
EMC0003E


EMC0005I

EMC0005I hh:mm:ss.ttt Response for EMCS console is [002]
Explanation:
Self-explanatory.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0006E

EMC0006E hh:mm:ss.ttt EMCS console was not activated.
Explanation:
Self-explanatory.
Issued by:
TAURIP56
System administrator response:
Determine why the console was not activated. If necessary, contact SupportLine.
Parent topic: EMC - Extended MCS Interface


EMC0007E

EMC0007E hh:mm:ss.ttt [002] is not a valid function for interface EMCS
Explanation:
Self-explanatory.
Issued by:
TAURIP56
System administrator response:
Determine why an invalid function was used. If necessary, contact SupportLine.
Parent topic: EMC - Extended MCS Interface


EMC0008I

EMC0008I hh:mm:ss.ttt Waiting for console response.
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0009I

EMC0009I hh:mm:ss.ttt Routine for EMCS console invoked with function [002]     (hex)
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0010W

EMC0010W hh:mm:ss.ttt Portcheck for port [002] skipped because
                       EMCS console was not activated.
Explanation:
An EMCS console is needed to issue commands and see command responses. The port check function requires that a TCPIP command is issued.
Issued by:
TAURIP17
System administrator response:
Check why no EMCS console was activated.
Parent topic: EMC - Extended MCS Interface


EMC0011E

EMC0011E hh:mm:ss.ttt Port [002] is not available
Explanation:
z/Server has determined that the requested port [002] is not available for the incoming request. When port check is active (PORTCHECK=1 in the scheduler configuration) there is a DISPLAY NETSTAT command for this port visible in hardcopy log that may give an indication why.
Issued by:
TAURIP17
System administrator response:
Determine why the port is not available. Check the hardcopy log, scheduler and/or holder configuration file (PORT parameter).
Parent topic: EMC - Extended MCS Interface


EMC0012E

EMC0012E  hh:mm:ss.ttt Console buffer of size [002] KB is too small to
                       hold command response. Increase size of buffer.
Explanation:
Self-explanatory.
Issued by:
TAURIP56
System administrator response:
Increase size of buffer in the configuration file (see BUFFERSIZE/BUFFERUNIT in the z/Server Installation Guide).
Parent topic: EMC - Extended MCS Interface


EMC0013I

EMC0013I hh:mm:ss.ttt No REXX exec or LE-enabled program for postprocessing specified
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0014E

EMC0014E hh:mm:ss.ttt REXX exec or program flag is invalid >>[002]<<
                      Specify X'01' for REXX or X'02' for LE-enabled program
Explanation:
Self-explanatory.
Issued by:
TAURIP56
User response:
Specify X'01' if you want to call a REXX exec or X'02' if an LE-enabled program is to be called.
Parent topic: EMC - Extended MCS Interface


EMC0015I

EMC0015I hh:mm:ss.ttt Using [002] [003] for postprocessing of command response
Explanation:
Self-explanatory.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0016I

EMC0016I hh:mm:ss.ttt Calling [002] for postprocessing of command response
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0017I

EMC0017I hh:mm:ss.ttt [002] ended with RC [003]
Explanation:
Self-explanatory.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0018I

EMC0018I hh:mm:ss.ttt Using CART [002] as command and response token
Explanation:
Self-explanatory.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0019I

EMC0019I hh:mm:ss.ttt Using area at address [002] for response
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0020I

EMC0020I hh:mm:ss.ttt Internal console buffer allocated at address [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0021I

EMC0021I hh:mm:ss.ttt Internal console buffer at address [002] released.
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP56
User response:
None.
Parent topic: EMC - Extended MCS Interface


EMC0022E

EMC0022E  hh:mm:ss.ttt Operator command has an invalid length of [002] (hex).
Operator command must be greater than zero and less than 126
Explanation:
Self-explanatory.
Issued by:
TAURIP56
System administrator response:
Use a valid operator command.
Parent topic: EMC - Extended MCS Interface


EMC0023E

EMC0023E  hh:mm:ss.ttt Portcheck unsuccessful because console utility failed with RC [002]
This may be a temporary problem for RC=8 (ENQ failed).
Explanation:
Self-explanatory.
Issued by:
TAURIP17
System administrator response:
Determine why the console utility failed. If necessary, contact SupportLine.
Parent topic: EMC - Extended MCS Interface


HLD - Holder Task Interface

Holder task messages provide information about the resources owned by the holder task (mainly data space and SVC routine responses).

  • HLD0001I
  • HLD0002I
  • HLD0003I
  • HLD0004I
  • HLD0005I
  • HLD0006I
  • HLD0007I
  • HLD0008E
  • HLD0009I
  • HLD0010E
  • HLD0011I
  • HLD0012I
  • HLD0013E
  • HLD0014E
  • HLD0015E
  • HLD0016W
  • HLD0017E
  • HLD0018I
  • HLD0019I
  • HLD0020I
  • HLD0021I
  • HLD0022I
  • HLD0024I
  • HLD0025I
  • HLD0026I
  • HLD0027I
  • HLD0028I
  • HLD0029I
  • HLD0030I
  • HLD0031I
  • HLD0032I
  • HLD0033I
  • HLD0034I
  • HLD0035I
  • HLD0036E
  • HLD0038E
  • HLD0039I
  • HLD0040E
  • HLD0041I
  • HLD0042I
  • HLD0043I
  • HLD0044I
  • HLD0045E
  • HLD0046E
  • HLD0047I
  • HLD0048I
  • HLD0049I
  • HLD0050I
  • HLD0051I
  • HLD0052I
  • HLD0053E
  • HLD0054I
  • HLD0055E
  • HLD0056E
  • HLD0057W
  • HLD0058E
  • HLD0059E
  • HLD0060I
  • HLD0061E
  • HLD0062I
  • HLD0063I
  • HLD0064I
  • HLD0065I
  • HLD0066I
  • HLD0067E
  • HLD0068E
  • HLD0069I
  • HLD0070I
  • HLD0071I
  • HLD0072E
  • HLD0073W
  • HLD0074E
  • HLD2001W
Parent topic: Messages


HLD0001I

HLD0001I hh:mm:ss.ttt [002] holder task [003] startup
Explanation:
This is an informational message sent to the operator console.

[002] Name of the task

[003] Version/release/modification level

Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0002I

HLD0002I hh:mm:ss.ttt [002] holder task ready for commands
Explanation:
This message is sent to the operator console and can be automated. The holder address space is now up and running.

[002] Name of the task

Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0003I

HLD0003I hh:mm:ss.ttt Creating dataspace
                      Name             : [002]
                      Size             : [003] blocks
                      Storagekey       : [004]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0004I

HLD0004I  hh:mm:ss.ttt Writing name/token pair [002]
                       DSPALET    :  [003]
                       DSPORIGIN  :  [004]
                       DSPBLOCK   :  [005]
                       DSPFLAGS   :  [006]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0005I

HLD0005I hh:mm:ss.ttt Deleting alet
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0006I

HLD0006I hh:mm:ss.ttt Deleting name/token pair
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0007I

HLD0007I hh:mm:ss.ttt Deleting dataspace
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0008E

HLD0008E  hh:mm:ss.ttt Function [002] failed with RC [003] and reason code [004]
Explanation:
Function [002] failed.
Issued by:
TAURHOLD
System administrator response:
  • If the function is DSPSERV or ALESERV, see SA22-7609-xx: MVS Programming: Authorized Assembler Services Reference, Volume 1 (ALE-DYN) for the return and reason codes.
  • If the function is SVCUPDTE, see SA22-7612-xx: MVS Programming: Authorized Assembler Services Reference, Volume 4 (SET-WTO) for the return and reason codes.
  • If the function is MCSOPER, see SA22-7611-xx: MVS Programming: Authorized Assembler Services Reference, Volume 3 (LLA-SDU) for the return and reason codes.
  • If the function is IEANTCR or IEANTDL, see SA22-7610-xx: MVS Programming: Authorized Assembler Services Reference, Volume 2 (EDT-IXG) for the return and reason codes.
Parent topic: HLD - Holder Task Interface


HLD0009I

HLD0009I  hh:mm:ss.ttt TSO environment successfully created
                       A (command processor parameter list): [002]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0010E

HLD0010E  hh:mm:ss.ttt Creation of TSO environment failed
                       Return code      : [002]
                       Reason code      : [003]
                       Abend code       : [004]
Explanation:
The IKJTSOEV service failed; see SA22-7789-xx: TSO/E Programming Services for details.
Issued by:
TAURHOLD
System administrator response:
Determine why it failed. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0011I

HLD0011I  hh:mm:ss.ttt Dataspace additional parameters
                       Collect statistics                : [002]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0012I

HLD0012I hh:mm:ss.ttt Creating partition [002] at address [003]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0013E

HLD0013E  hh:mm:ss.ttt SVC Routine [002] could not be loaded.
                       System completion code    : [003]
                       Return code               : [004]
Explanation:
LOAD of the SVC routine named [002] failed.
Issued by:
TAURHOLD
System administrator response:
Determine why the routine could not be loaded. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0014E

HLD0014E hh:mm:ss.ttt ENQ failed: Another copy of TAURHOLD is currently installing the same SVC
Explanation:
Establishing the SVC routine is serialized by an internal ENQ. That ENQ is held in the system. This is due to another holder task implementing or having implemented the same SVC number.
Issued by:
TAURHOLD
System administrator response:
Check which routine is installing the same SVC. If necessary, use a different SVC number.
Parent topic: HLD - Holder Task Interface


HLD0015E

HLD0015E hh:mm:ss.ttt Install of SVC [002] failed with RC [003]
Explanation:
SVCUPDTE failed; see SA22-7612-xx: MVS Programming: Authorized Assembler Services Reference, Volume 4 (SET-WTO) for the return and reason codes.
Issued by:
TAURHOLD
System administrator response:
Determine why SVCUPDTE failed. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0016W

HLD0016W  hh:mm:ss.ttt SVC [002] with current entry address [003] will be replaced with new entry address [004].
                       Waiting for console reply
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
System administrator response:
Respond to the message on the console.
Parent topic: HLD - Holder Task Interface


HLD0017E

HLD0017E  hh:mm:ss.ttt Delete of SVC [002] failed with RC [003]
Explanation:
SVCUPDTE failed to delete the SVC routine from the system at termination; see SA22-7612-xx: MVS Programming: Authorized Assembler Services Reference, Volume 4 (SET-WTO) for the return and reason codes.
System administrator response:
Determine why SVCUPDTE failed. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0018I

HLD0018I ------------------------------------------------------------------
         Installing user SVC [001]
         ------------------------------------------------------------------
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0019I

HLD0019I  hh:mm:ss.ttt User SVC [002] successfully installed.
                       Program: [003] EPA: [004]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0020I

HLD0020I hh:mm:ss.ttt Console reply was [002]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0021I

HLD0021I ------------------------------------------------------------------
         Creating SCOPE=COMMON data space [001]
         ------------------------------------------------------------------
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0022I

HLD0022I ------------------------------------------------------------------
         Creating EMCS console [001]
         ------------------------------------------------------------------
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0024I

HLD0024I  hh:mm:ss.ttt Activation for EMCS console [002] successful
                       ID      :   [003]
                       CSA     :   [004]
                       Message :   [005]
                       ALET    :   [006]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0025I

HLD0025I hh:mm:ss.ttt Function [002] ended successfully
Explanation:
This is an informational message. Function [002] can be one of the following:
  • Create Dataspace
  • Create Alet
  • Create Name/Token
  • Delete Alet
  • Delete Dataspace
  • Delete Name/Token
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0026I

HLD0026I ------------------------------------------------------------------
         Cleanup user SVC
         ------------------------------------------------------------------
Explanation:
Self-explanatory.
Issued by:
TAURHOLD, TAURIP86
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0027I

HLD0027I ------------------------------------------------------------------
         Cleanup data space
         ------------------------------------------------------------------
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0028I

HLD0028I ------------------------------------------------------------------
         Cleanup console
         ------------------------------------------------------------------
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0029I

HLD0029I  hh:mm:ss.ttt User administration called with function >>[002]<<
                      P3            :  [003]
                      Flag is       :  [004]
                                        1... ....  called from holder task
                                        .1.. ....  use data space
Explanation:
This is an informational message due to IPTRACE level 4 being set. [004] can have the following values:
x'80'
Called from holder task
x'40'
Use data space.
Issued by:
TAURIP27
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0030I

HLD0030I hh:mm:ss.ttt User administration ended with RC [002] (hex)
Explanation:
This is an informational message due to IPTRACE level 4 being set.

The return code RC is one of the following:

RC | Meaning
8 | Function INIT not valid.
C | Data space size not big enough.
14 | Invalid function.
64 | Scheduler port range outside defined port range.
65 | Scheduler port range overlaps another server's port range.
66 | Scheduler already in table. Scheduler is not added.
68 | Table is full.
6C | Scheduler not found.
70 | User not found.
72 | User already in table.
76 | User table is full.
7A | CRP is outside table.
7E | User server is not a started job. Timeout is ignored.
82 | Port not found.
86 | User administration not via data space.
8A | Port is not locked. UNLOCK ignored.
8E | Scheduler is locked.
92 | Asid not found.
96 | No free floating license available.
9E | Resource table is full.
A2 | Entry not found in resource table.
A6 | No entry found for user server.
AA | Portrange of server is overlapping with portrange of another server.
nnn | For function code 9 this is not a return code, but rather internal information.
Issued by:
TAURIP27
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0031I

HLD0031I hh:mm:ss.ttt User data on entry
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP27
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0032I

HLD0032I hh:mm:ss.ttt User data on exit
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP27
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0033I

HLD0033I  hh:mm:ss.ttt Server Information
                       Lowest  port over all servers   : [002]
                       Highest port over all servers   : [003]
                       Maximum numbers of    servers   : [004]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0034I

HLD0034I hh:mm:ss.ttt [002] holder task shutdown
Explanation:
This is an informational message issued to the operator console.

[002] Name of the address space

Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0035I

HLD0035I hh:mm:ss.ttt Initializing data space for user administration
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0036E

HLD0036E hh:mm:ss.ttt Unexpected RC [002] from user administration
Explanation:
Return code [002] can be one of the following:
8
INIT function not valid. INIT is allowed from holder task if a data space is used, or from a server if local storage should be used
C
Size of data space or size of local area is not large enough to hold all required tables
14
Invalid function
Issued by:
TAURHOLD
System administrator response:
Determine what caused the unexpected return code. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0038E

HLD0038E  hh:mm:ss.ttt Dataspace too small for user administration
                       Specify at least [002] blocks for DSP_SIZE
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
System administrator response:
Increase the DSP_SIZE parameter in the configuration file to at least the value [002].
Parent topic: HLD - Holder Task Interface


HLD0039I

HLD0039I  hh:mm:ss.ttt Table for internal user administration allocated
                       Size    : [002]      bytes
                       Address : [003]
Explanation:
Self-explanatory.
Issued by:
TAURIP27
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0040E

HLD0040E hh:mm:ss.ttt Command [002] invalid for z/Server holder task
Explanation:
The command issued for the holder task TAURHLD was invalid. This message is issued to the operator console.
Issued by:
TAURHOLD
User response:
Use a valid command.
Parent topic: HLD - Holder Task Interface


HLD0041I

HLD0041I  hh:mm:ss.ttt Calling command REXX exec IPCMDHLD
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0042I

HLD0042I  hh:mm:ss.ttt Command REXX exec IPCMDHLD ended with RC [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.

Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0043I

HLD0043I  hh:mm:ss.ttt Answer from REXX exec IPCMDHLD is :
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0044I

HLD0044I  hh:mm:ss.ttt z/Server holder task received command [002]
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
System administrator response:
None.
Parent topic: HLD - Holder Task Interface


HLD0045E

HLD0045E  hh:mm:ss.ttt Command [002] for z/Server holder task contains invalid syntax.
Explanation:
This is an error message sent to the operator console.
Issued by:
TAURHOLD
System administrator response:
Use the correct syntax for the command.
Parent topic: HLD - Holder Task Interface


HLD0046E

HLD0046E  hh:mm:ss.ttt Scheduler [002] does not exist.
Explanation:
This is an error message sent to the operator console.
Issued by:
TAURHOLD
System administrator response:
Use an existing scheduler task name for the command.
Parent topic: HLD - Holder Task Interface


HLD0047I

HLD0047I  hh:mm:ss.ttt Stopping [002] user server for scheduler [003]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0048I

HLD0048I ------------------------------------------------------------------
Starting server
         ------------------------------------------------------------------
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0049I

HLD0049I  hh:mm:ss.ttt Starting server [002]
Explanation:
Self-explanatory.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0050I

HLD0050I ------------------------------------------------------------------
         Stopping server
         ------------------------------------------------------------------
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0051I

HLD0051I  hh:mm:ss.ttt Stopping server [002]
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0052I

HLD0052I  hh:mm:ss.ttt Stopping user server for user [002] and scheduler [003] with jobid [004] and asid [005]
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0053E

HLD0053E  hh:mm:ss.ttt Scheduler [002] already in table. ADD not processed.
Explanation:
This is an error message sent to the operator console.
Issued by:
TAURHOLD
User response:
Determine why scheduler [002] is already defined. If necessary, contact SupportLine. Issue a MODIFY <holder>,STOP,SCHED=[002] command to clear the scheduler from the user administration control structures.
Parent topic: HLD - Holder Task Interface


HLD0054I

HLD0054I  hh:mm:ss.ttt Canceling user server for user [002] and scheduler [003] with jobid [004] and asid [005]
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0055E

HLD0055E  hh:mm:ss.ttt Port [002] not within port range of z/Server holder task
Explanation:
This is an error message sent to the operator console. The scheduler is configured to use ports that the associated holder address space is not configured to use.
Issued by:
TAURHOLD
System administrator response:
Correct the configuration file(s).
Parent topic: HLD - Holder Task Interface


HLD0056E

HLD0056E  hh:mm:ss.ttt No user server running on port [002]
Explanation:
This is an error message sent to the operator console in response to a stop command for a specific port.
Issued by:
TAURHOLD
System administrator response:
Correct the command.
Parent topic: HLD - Holder Task Interface


HLD0057W

HLD0057W  hh:mm:ss.ttt Scheduler [002] did not respond to STOP command.
                       Scheduler will be canceled.
Explanation:
This is a warning sent to the operator console. The scheduler to be terminated did not terminate after receiving the stop command. The holder task will now use a cancel command to attempt termination.
Issued by:
TAURHOLD
System administrator response:
None.
Parent topic: HLD - Holder Task Interface


HLD0058E

HLD0058E z/Server holder task DD statement DSPPRT missing.
Explanation:
This is an error message sent to the operator console. The requested command response can only be shown when the DD statement DSPPRT is specified in the holder task startup JCL.
Issued by:
TAURDSP
System administrator response:
Add the DSPPRT DD statement and restart the holder task.
Parent topic: HLD - Holder Task Interface


HLD0059E

HLD0059E z/Server holder task oncode : [001] at location [002]
Explanation:
This is an error message sent to the operator console.
Issued by:
TAURDSP
System administrator response:
Determine why the holder task encountered an error. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0060I

HLD0060I  hh:mm:ss.ttt Data space information printed to DD statement DSPPRT.
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0061E

HLD0061E  hh:mm:ss.ttt Data space information failed with RC [002].
Explanation:
This is an error message sent to the operator console. [002] can be one of the following:
08
Invalid function
12
Name/token pair not found
Issued by:
TAURHOLD
System administrator response:
Determine why the failure occurred. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0062I

HLD0062I  hh:mm:ss.ttt [002] ports found for STOP
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
System administrator response:
None.
Parent topic: HLD - Holder Task Interface


HLD0063I

HLD0063I  hh:mm:ss.ttt Scheduler [002] locked
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURIP27
System administrator response:
None.
Parent topic: HLD - Holder Task Interface


HLD0064I

HLD0064I  hh:mm:ss.ttt Scheduler [002] unlocked
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURIP27
System administrator response:
None.
Parent topic: HLD - Holder Task Interface


HLD0065I

HLD0065I  hh:mm:ss.ttt [002] Schedulers locked
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0066I

HLD0066I  hh:mm:ss.ttt [002] Schedulers unlocked
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0067E

HLD0067E  hh:mm:ss.ttt ASID [002] not associated with a user server. STOP command ignored.
Explanation:
This is an error message sent to the operator console.
Issued by:
TAURHOLD
System administrator response:
Determine why a STOP command was issued against an address space that is not a user server. If necessary, contact SupportLine.
Parent topic: HLD - Holder Task Interface


HLD0068E

HLD0068E  hh:mm:ss.ttt Maximum count of [002] schedulers reached.
                       Scheduler [003] not started.
                       Increase value for DSP_MAX_SERV
Explanation:
This is an informational message due to IPTRACE level 4 being set.

Issued by:
TAURHOLD
System administrator response:
Increase the value for DSP_MAX_SRV in the holder configuration and restart the holder task.
Parent topic: HLD - Holder Task Interface


HLD0069I

HLD0069I  hh:mm:ss.ttt Holder task configuration
                       Size data space specified....: [002]      Blocks
                       Size data space required.....: [003]      Blocks
                       Delay........................: [004] seconds
                       Trace-Level..................: [005]
                       Modify limit.................: [006]
                       Size RESTAB in blocks........: [007]
                       Max. # of entries in RESTAB..: [008]
                       Reply........................: [009]
Explanation:
This is an informational message due to IPTRACE level 4 being set. The message shows the global configuration variables for the holder task.
Issued by:
TAURHOLD
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0070I

HLD0070I hh:mm:ss.ttt User  [002] added to floating licensing.
Explanation:
This is an informational message due to IPTRACE level 5 being set. The message is issued if the z/Server licence key contains floating licence information and a new user is added to the floating licence table.
Issued by:
TAUIP27
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0071I

HLD0071I hh:mm:ss.ttt User  [002] removed from floating licensing.
Explanation:
This is an informational message due to IPTRACE level 5 being set. The message is issued if the z/Server licence key contains floating licence information and a user is removed from the floating licence table.
Issued by:
TAUIP27
User response:
None.
Parent topic: HLD - Holder Task Interface


HLD0072E

HLD0072E hh:mm:ss.ttt No free floating licens for user  [002]
Explanation:
This message is issued if the z/Server license key contains floating license information and all floating licenses are used up.
Issued by:
TAURIP27
User response:
A new license key is required to allow more parallel users.
Parent topic: HLD - Holder Task Interface


HLD0073W

HLD0073W Listener port [002] outside the defined portrange of holder [003]
Explanation:
This message is issued if z/Server is started and the listener port PORT [002] is not in the portrange [DSP_PORT_LOW,DSP_PORT_HIGH] of the holder task.
Issued by:
TAURIP27
System administrator response:
This does not indicate an error but the issue should be resolved.
Parent topic: HLD - Holder Task Interface


HLD0074E

HLD0074E Port range [002] – [003] is overlapping with portrange [004] – [005] of scheduler [006]
Explanation:
This message is issued if a scheduler is started and the port range overlaps with the port range of scheduler [006].
Issued by:
TAURIP27
System administrator response:
Ensure that the port ranges do not overlap.
Parent topic: HLD - Holder Task Interface


HLD2001W

HLD2001W SVC not available. Reply O to override or C to cancel
Explanation:
When attempting to establish the SVC for this holder task, the operating system detected that the SVC number is already in use.
Issued by:
TAURHOLD
System administrator response:
Check the configuration file for the holder task to see if the correct SVC number was specified for this holder task. If not, reply C to cancel startup and specify again the SVC number in the configuration file. Reply O to unconditionally use the specified SVC number.
Parent topic: HLD - Holder Task Interface


IPC - Command Task

  • IPC0001W
  • IPC0002W
  • IPC0003W
  • IPC0004W
  • IPC0005I
  • IPC0006W
  • IPC0007W
  • IPC0040I
  • IPC0042I
  • IPC0043I
  • IPC0044I
  • IPC0052I
  • IPC0061I
  • IPC0062I
  • IPC0063I
  • IPC0064I
  • IPC0065E
  • IPC0066I
  • IPC0067I
  • IPC0068I
  • IPC0069E
  • IPC0070E
  • IPC0071I
  • IPC0072E
  • IPC0073I
  • IPC0074I
  • IPC0075I
  • IPC0076I
  • IPC0077E
  • IPC0078E
  • IPC0079I
  • IPC0080I
  • IPC0081E
  • IPC0082I
  • IPC0083E
  • IPC0084I
  • IPC0085E
  • IPC0086W
  • IPC0087E
  • IPC0088E
  • IPC0090I
  • IPC0091I
  • IPC0092E
  • IPC0093E
  • IPC0094I
  • IPC0095I
  • IPC0096I
  • IPC0097E
  • IPC0098I
  • IPC0099I
  • IPC0100E
  • IPC0101I
  • IPC0102I
  • IPC0104I
  • IPC0105W
Parent topic: Messages


IPC0001W

IPC0001W hh:mm:ss.ttt PPT invalid syntax
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP04
System administrator response:
Contact SupportLine.
Parent topic: IPC - Command Task


IPC0002W

IPC0002W hh:mm:ss.ttt PPT does not exist
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP04
System administrator response:
Contact SupportLine.
Parent topic: IPC - Command Task


IPC0003W

IPC0003W hh:mm:ss.ttt Invalid length for module name specified
Explanation:
This message is sent to the operator console.
Issued by:
TAURIP04
System administrator response:
Determine why an invalid length was specified. If necessary, contact SupportLine.
Parent topic: IPC - Command Task


IPC0004W

IPC0004W hh:mm:ss.ttt Module [002] not in PPT
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP04
System administrator response:
Contact SupportLine.
Parent topic: IPC - Command Task


IPC0005I

IPC0005I hh:mm:ss.ttt Task [002] scheduled for delete request of [003]
Explanation:
This is an informational message sent to the operator console.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0006W

IPC0006W hh:mm:ss.ttt Could not delete PPT for program [002] because task [003] is terminated.
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP04
System administrator response:
Contact SupportLine.
Parent topic: IPC - Command Task


IPC0007W

IPC0007W hh:mm:ss.ttt Could not delete PPT for program [002] because task [003] is busy.
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP04
System administrator response:
Contact SupportLine.
Parent topic: IPC - Command Task


IPC0040I

IPC0040I hh:mm:ss.ttt z/Server command task is initializing.
Explanation:
Self-explanatory.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0042I

IPC0042I  hh:mm:ss.ttt Address of Communication event control block : [002]
                       Address of Command input buffer              : [003]
                       Token                                        : [004]
Explanation:
Self-explanatory.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0043I

IPC0043I hh:mm:ss.ttt Command task invoked with [002] command
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0044I

IPC0044I  hh:mm:ss.ttt Data for command : -> [002]<-
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0052I

IPC0052I hh:mm:ss.ttt shutdown
Explanation:
This message is sent to the operator console.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0061I

IPC0061I hh:mm:ss.ttt Command [002] unknown
Explanation:
The command issued is unknown.
Issued by:
IPCMD, IPCMDTSO, TAURIP04
User response:
Use a valid command.
Parent topic: IPC - Command Task


IPC0062I

IPC0062E hh:mm:ss.ttt Invalid syntax for command KILL
Explanation:
The wrong syntax was used.
Issued by:
IPCMD
User response:
Enter the correct syntax F <scheduler | user server>,KILL,TASK=nnn
Parent topic: IPC - Command Task


IPC0063I

IPC0063I hh:mm:ss.ttt Requested task number does not exist
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Use a valid command.
Parent topic: IPC - Command Task


IPC0064I

IPC0064I  hh:mm:ss.ttt Scheduling [002] request to maintask
                       IP address  :  [003]
                       Port        :  [004]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP04 (at trace level 5), TAURIP77 (at trace level 0)
User response:
None.
Parent topic: IPC - Command Task


IPC0065E

IPC0065E hh:mm:ss.ttt Invalid syntax for command TRACE
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Enter the correct syntax F <holder | scheduler | user server>,TRACE,LEVEL=n with n=[0..6]
Parent topic: IPC - Command Task


IPC0066I

IPC0066I hh:mm:ss.ttt Trace level changed to [002]
Explanation:
Self-explanatory. [002] can be one of the values 0 to 6.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0067I

IPC0067E  hh:mm:ss.ttt Invalid syntax for command REATTACH
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Enter the correct syntax F <scheduler | user server>,REATTACH,TASK={nnn | ALL}
Parent topic: IPC - Command Task


IPC0068I

IPC0068I hh:mm:ss.ttt Checking availability of port [002]
Explanation:
Self-explanatory.
User response:
None.
Parent topic: IPC - Command Task


IPC0069E

IPC0069E  hh:mm:ss.ttt Port [002] is not available
                       Port in use by :  [003]
                       Connection ID  :  [004]
                       State          :  [005]
Explanation:
Self-explanatory.
System administrator response:
Determine why the port is in use by [003]. If necessary, contact SupportLine.
Parent topic: IPC - Command Task


IPC0070E

IPC0070E  hh:mm:ss.ttt Call to netstat was not succesful
Explanation:
See DD statement SYSTSPRNT for more information.
System administrator response:
Determine why the call to NETSTAT was unsuccessful. If necessary, contact SupportLine.
Parent topic: IPC - Command Task


IPC0071I

IPC0071I hh:mm:ss.ttt Using command exit [002]
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0072E

IPC0072E hh:mm:ss.ttt Invalid syntax for command TSO
Explanation:
Self-explanatory.
Issued by:
IPCMDTSO
System administrator response:
Use the correct command syntax.
Parent topic: IPC - Command Task


IPC0073I

IPC0073I  hh:mm:ss.ttt Calling command exit [002] with data
                       [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0074I

IPC0074I hh:mm:ss.ttt Using command REXX exec [002]
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0075I

IPC0075I hh:mm:ss.ttt Calling command REXX exec [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0076I

IPC0076I hh:mm:ss.ttt Command REXX exec [002] ended with RC [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set. [002] is the name of the REXX exec being executed, and [003] is the return code set by that exec.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0077E

IPC0077E hh:mm:ss.ttt Call to IP03 ended with RC [002]
Explanation:
The general IP communication module TAURIP03 returned an error [002]. See the section API - Application Programming Interface for an explanation of RC.
Issued by:
TAURIP77
System administrator response:
Determine why an error was returned. If necessary, contact SupportLine.
Parent topic: IPC - Command Task
Related information
API - Application Programming Interface


IPC0078E

IPC0078E  hh:mm:ss.ttt Invalid syntax for command COMPRESS
Explanation:
Self-explanatory.
Issued by:
IPCMD
System administrator response:
Use the correct command syntax.
Parent topic: IPC - Command Task


IPC0079I

IPC0079I hh:mm:ss.ttt Compress level changed to [002]
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0080I

IPC0080I  hh:mm:ss.ttt ----------------------------------------------------
                       Addr : [002] Size : [003] TCB : [004] Name : [005]
                       ----------------------------------------------------
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0081E

IPC0081E hh:mm:ss.ttt Invalid syntax for command RECOVERY
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Use the correct syntax.
Parent topic: IPC - Command Task


IPC0082I

IPC0082I hh:mm:ss.ttt Recovery changed to [002]
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0083E

IPC0083E hh:mm:ss.ttt Invalid syntax for command REFRESH
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Enter the correct syntax: F <scheduler | user server>,REFRESH,PGM=nn (nn = [02..99])
Parent topic: IPC - Command Task


IPC0084I

IPC0084I hh:mm:ss.ttt Answer from REXX exec [002] is :
Explanation:
Self-explanatory.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0085E

IPC0085E  hh:mm:ss.ttt Invalid syntax for command DUMP
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Use the correct syntax:

F <scheduler | user server>,DUMP,AREA=ALL

F<scheduler | user server>, DUMP,ADDR=x,LEN=y

F <scheduler | user server>, DUMP,SVCD

F <scheduler | user server>, DUMP,CONFIG

Parent topic: IPC - Command Task


IPC0086W

IPC0086W hh:mm:ss.ttt VSMLOC for address  [002] and length  [003] failed  with RC :  [004] For RC=4
                      Storage not allocated in PVT
                      Storage overlaps free space
                      Storage overlaps other subpools
Explanation:
Self-explanatory. See SA22-7612-xx MVS Programming: Authorized Assembler Services Reference, Volume 4 (SET-WTO) for an explanation of [004].
Issued by:
TAURIP04
System administrator response:
Determine why the service failed. If necessary, contact SupportLine.
Parent topic: IPC - Command Task


IPC0087E

IPC0087E  hh:mm:ss.ttt Invalid syntax for command REXX
                       f taskname,rexx,[ts!te!ht,rt,hi],subtask=[nn!all]
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Use the correct syntax:

F <scheduler | user server>,REXX,[TS | TE | HT | RT | HI],SUBTASK=[nn | ALLl]

Parent topic: IPC - Command Task


IPC0088E

IPC0088E hh:mm:ss.ttt SVC dump not possible, because user server was not configured to use a SVC routine.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP04
System administrator response:
Contact SupportLine.
Parent topic: IPC - Command Task


IPC0090I

IPC0090I ------------------------------------------------------------------
         Initial configuration settings at address [001]
         ------------------------------------------------------------------
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0091I

IPC0091I [001]
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0092E

IPC0092E  hh:mm:ss.ttt Invalid syntax for command DISPLAY
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Use the correct syntax.
Parent topic: IPC - Command Task


IPC0093E

IPC0093E  hh:mm:ss.ttt GQSCAN failed with RC [002]
Explanation:
This is an informational message issued to the operator console. See SA22-7610-xx: MVS Programming: Authorized Assembler Services Reference, Volume 2 (EDT-IXG) for an explanation of the return code [002].

Issued by:
TAURIP04
System administrator response:
Determine why the service failed. If necessary, contact SupportLine.
Parent topic: IPC - Command Task


IPC0094I

IPC0094I S= [001] [002] [003]
Explanation:
This is an informational message issued to the operator console.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0095I

IPC0095I    SysName  JobName  Asid TCBAddr     EXC/SHR    Status
Explanation:
This is an informational message issued to the operator console.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0096I

IPC0096I    hh:mm:ss.ttt [002] [003] [004]    [005]  [006]
Explanation:
This is an informational message.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0097E

IPC0097E  hh:mm:ss.ttt Invalid syntax for command DEQ
Explanation:
Self-explanatory.
Issued by:
IPCMD
User response:
Use the correct syntax.
Parent topic: IPC - Command Task


IPC0098I

IPC0098I  hh:mm:ss.ttt Current virtual storage map for server [002] printed to ddname CMDTASK.
Explanation:
This is an informational message issued to the operator console in response to a request to print the current virtual storage map. [002] is either the name of a scheduler or of a user server.
Issued by:
TAURIP04
System administrator response:
See DD statement CMDTASK in the job log for the storage map.
Parent topic: IPC - Command Task


IPC0099I

IPC0099I  hh:mm:ss.ttt Resource [002] not held by [003]
Explanation:
This is an informational message issued to the operator console.
Issued by:
TAURIP04
System administrator response:
Determine why resource [002] is not held by [003].
Parent topic: IPC - Command Task


IPC0100E

IPC0100E  hh:mm:ss.ttt Invalid slave command [002]. No action peformed.
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP04
System administrator response:
Contact SupportLine.
Parent topic: IPC - Command Task


IPC0101I

IPC0101I  hh:mm:ss.ttt Slave command [002] received.
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0102I

IPC0101I  hh:mm:ss.ttt Modify limit is [002].
Explanation:
This is an informational message due to IPTRACE level 5 being set. This message shows the setting of the configuration variable MODIFY_LIMIT of the holder task.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


IPC0104I

IPC0104I  hh:mm:ss.ttt Waiting [002] milliseconds for command task.
Explanation:
This is an informational message due to IPTRACE level 5 being set. This message is issued if a remote enqueue or dequeue was requested, and the command task is busy.
Issued by:
TAURIP38
User response:
None.
Parent topic: IPC - Command Task


IPC0105W

IPC0105W hh:mm:ss.ttt Command task for server  [002] is terminating.
Explanation:
The command task is closing and will not accept any more commands.
Issued by:
TAURIP04
User response:
None.
Parent topic: IPC - Command Task


JES - Job Entry Subsystem Interface

The z/Server API calls to the JES interface are used to process spool data sets.

  • JES0001I
  • JES0002I
  • JES0003E
  • JES0004E
  • JES0005E
  • JES0006E
  • JES0007E
  • JES0008I
  • JES0009I
  • JES0010I
  • JES0013E
Parent topic: Messages


JES0001I

JES0001I hh:mm:ss.ttt JES Utility called with command [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP42, TAURIP93
User response:
None.
Parent topic: JES - Job Entry Subsystem Interface


JES0002I

JES0002I hh:mm:ss.ttt JES utility ended with RC [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Return code:
16
Invalid function
20
SSI call failed
24
No filter specified
28
DYNALLOC failed, see LE message file for more information
32
Data set open failed
36
Buffer too small to hold XML document
Issued by:
TAURIP42, TAURIP93
User response:
None.
Parent topic: JES - Job Entry Subsystem Interface


JES0003E

JES0003E  hh:mm:ss.ttt SSI call for function code [002] failed with RC [003]
                       SSOBRETN is ............. : [004]
                       Reason   is ............. : [005]
Explanation:
IEFSSREQ failed. See SA22-7642-xx: MVS Using the Subsystem Interface for details. Keep in mind that the function code, return code, SSOBRETN and Reason code are shown here as hexadecimal values, while the referenced book shows them as decimal values. SSOBRETN [004] and Reason [005] are the return code and reason code returned by the invoked service.

[002] Function code can be:

1 (X'01')
Process JES SYSOUT data sets
11 (X'0B')
Validation/Conversion
15 (X'0F')
Verify subsystem function
20 (X'14')
Request job ID
21 (X'15')
Return job ID
54 (X'36')
Request subsystem version information
70 (X'46')
Scheduler Facilities services
71 (X'47')
JES JOB information
75 (X'4B')
Notify user message service
79 (X'4F')
SYSOUT Application Program Interface (SAPI)
80 (X'50')
Extended Status Function Call
82 (X'52')
JES properties

[003] RC: IEFSSREQ invocation return code. A non-zero return code indicates that a passed parameter was not valid, for example, 8 = subsystem exists but is not active).

Issued by:
TAURIP42, TAURIP93
System administrator response:
IEFSSREQ macro error. Determine why it failed. If necessary, contact SupportLine.
Parent topic: JES - Job Entry Subsystem Interface


JES0004E

JES0004E hh:mm:ss.ttt No filter specified for function [002]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP42, TAURIP93
User response:
Specify a filter.
Parent topic: JES - Job Entry Subsystem Interface


JES0005E

JES0005E  hh:mm:ss.ttt Dynalloc failed for DDname [002]
                       Verb code  :  [003]
                       S99RC      :  [004]
                       S99ERROR   :  [005]
                       S99INFO    :  [006]
                       S99ERSN    :  [007]
                       Data set   :  [008]
Explanation:
The requested data set could not be allocated. See SA22-7608-xx: MVS Programming: Authorized Assembler Services Guide for details on the returned information.
Issued by:
TAURIP42, TAURIP93
System administrator response:
Determine why DYNALLOC failed. If necessary, contact SupportLine.
Parent topic: JES - Job Entry Subsystem Interface


JES0006E

JES0006E hh:mm:ss.ttt Open of data set [002] was not successful.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP42, TAURIP93
System administrator response:
Determine why the data set was not opened successfully. If necessary, contact SupportLine.
Parent topic: JES - Job Entry Subsystem Interface


JES0007E

JES0007E hh:mm:ss.ttt Buffer with size of [002] (hex) too small to hold all data. Read terminated after [003] records.
Explanation:
Self-explanatory.
Issued by:
TAURIP42, TAURIP93
System administrator response:
Increase the buffer size.
Parent topic: JES - Job Entry Subsystem Interface


JES0008I

JES0008I hh:mm:ss.ttt [002] work units (JOES) deleted.
Explanation:
This is an informational message.
Issued by:
TAURIP42
User response:
None.
Parent topic: JES - Job Entry Subsystem Interface


JES0009I

JES0009I hh:mm:ss.ttt Cancel command [002] accepted and routed to console.
Explanation:
This is an informational message issued to the operator console.
Issued by:
TAURIP42
User response:
None.
Parent topic: JES - Job Entry Subsystem Interface


JES0010I

JES0010I hh:mm:ss.ttt Stop command for job [002] accepted.
Explanation:
This is an informational message.
Issued by:
TAURIP42
User response:
None.
Parent topic: JES - Job Entry Subsystem Interface


JES0013E

JES0013E hh:mm:ss.ttt [002] cannot be canceled.
                      CANCEL command only allowed for jobs.
Explanation:
A user tried to cancel an STC or TSU address space.
Issued by:
TAURIP42
User response:
Cancel not allowed for STC or TSU address spaces.
Parent topic: JES - Job Entry Subsystem Interface


LIC - License Interface

The use of z/Server requires a valid license. The license interface performs the associated processing.

  • LIC0001E
  • LIC0002W
  • LIC0003I
  • LIC0004W
  • LIC0005E
  • LIC0006E
  • LIC0007W
  • LIC0008E
  • LIC0009I
  • LIC0010E
  • LIC0011I
  • LIC0012E
  • LIC0013I
Parent topic: Messages


LIC0001E

LIC0001E  hh:mm:ss.ttt License key [002] not valid.
                       Reason : [003]
Explanation:
Self-explanatory. This message is issued to the operator console.

Reason code:

1
License contains non-hexadecimal character
2
Invalid delimiter (not '-')
3
Byte 8 of Key-2 is not 0 or 1
4
Invalid date in key part 3
5
License key expired
6
Part 2 must be binary 0 or 1
Issued by:
TAURIP88
System administrator response:
Update the configuration with the correct license key (LICENCE_KEY parameter).
Parent topic: LIC - License Interface


LIC0002W

LIC0002W hh:mm:ss.ttt This server is licensed for a specific LPAR
Explanation:
Self-explanatory.
Issued by:
TAURIP88
System administrator response:
Ensure that the server runs on the licensed LPAR.
Parent topic: LIC - License Interface


LIC0003I

LIC0003I hh:mm:ss.ttt Value after decrypt [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set and refers to deprecated functionality.
User response:
None.
Parent topic: LIC - License Interface


LIC0004W

LIC0004W hh:mm:ss.ttt License key expires in [002] days.
Explanation:
Self-explanatory. This message is issued to the operator console.
Issued by:
TAURIP88
System administrator response:
Renew the license.
Parent topic: LIC - License Interface


LIC0005E

LIC0005E hh:mm:ss.ttt License key expired. Server stopped.
Explanation:
Self-explanatory.
Issued by:
TAURIP00
System administrator response:
Renew the license.
Parent topic: LIC - License Interface


LIC0006E

LIC0006E hh:mm:ss.ttt Feature for command [002] not licensed.
Explanation:
Self-explanatory.
Issued by:
TAURIP78
System administrator response:
Extend the license for the appropriate facility that supports the command.
Parent topic: LIC - License Interface


LIC0007W

LIC0007W hh:mm:ss.ttt This server may only be used through a licensed client.
Explanation:
Self-explanatory.
Issued by:
TAURIP88
User response:
Use a licensed client.
Parent topic: LIC - License Interface


LIC0008E

LIC0008E  hh:mm:ss.ttt This server requires a version 2 header.
                       You must specify COMPAT=2 for startup
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP88
System administrator response:
Contact SupportLine.
Parent topic: LIC - License Interface


LIC0009I

LIC0009I hh:mm:ss.ttt License flag 2 is : [002]
Explanation:
This is an informational message.
Issued by:
TAURIP88
User response:
None.
Parent topic: LIC - License Interface


LIC0010E

LIC0010E hh:mm:ss.ttt License violation: This server accepts requests from an eclipse client only.
Explanation:
Self-explanatory.
Issued by:
TAURIP73
User response:
Use an Eclipse client.
Parent topic: LIC - License Interface


LIC0011I

LIC0011I  hh:mm:ss.ttt Changing limited to eclipse key information from client to scheduler.
                       Old value :  [002]
                       New value :  [003]
Explanation:
This is an informational message due to trace level 5 being set and refers to deprecated functionality.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: LIC - License Interface


LIC0012E

LIC0012E  hh:mm:ss.ttt This server is not licensed to use the CEA TSOE address space manager.
Explanation:
The used license key does not allow the use of the CEA TSOE address space manager.
Issued by:
TAURIP88
System administrator response:
Apply a valid license key.
Parent topic: LIC - License Interface


LIC0013I

LIC0013I  hh:mm:ss.ttt This server is licensed for [002] parallel users.
Explanation:
This is an informational message and indicates that the used license key is limited to [002] parallel users. The number of floating licenses in use can be determined using the command F <holder>,DISPLAY,DSP,FORMAT.
Issued by:
TAURIP88
System administrator response:
None
Parent topic: LIC - License Interface


MAL - Email Interface

z/Server can send emails to make the administrator aware of problems that happened. This is done through the email interface.

  • MAL0001E
  • MAL0002E
  • MAL0003E
  • MAL0004E
  • MAL0006I
  • MAL0007I
  • MAL0008I
  • MAL0009I
  • MAL0010I
  • MAL0011E
  • MAL0012E
  • MAL0013E
  • MAL0014I
Parent topic: Messages


MAL0001E

MAL0001E  hh:mm:ss.ttt Unable to open DD [002]. RC : [003]
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
Determine why the data set with the DD [002] could not be opened.
Parent topic: MAL - Email Interface


MAL0002E

MAL0002E  hh:mm:ss.ttt I/O error on internal reader. RC : [002]
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
Determine why the I/O error occurred.
Parent topic: MAL - Email Interface


MAL0003E

MAL0003E  hh:mm:ss.ttt Invalid function >>[002]<< for email interface
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
Determine why an invalid function was used.
Parent topic: MAL - Email Interface


MAL0004E

MAL0004E  hh:mm:ss.ttt email interface disabled due to previous error
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
None.
Parent topic: MAL - Email Interface


MAL0006I

MAL0006I  hh:mm:ss.ttt [002] Lines with [003] bytes
                       for email at address [004] allocated.
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
None.
Parent topic: MAL - Email Interface


MAL0007I

MAL0007I  hh:mm:ss.ttt email interface invoked with function >>[002]<<
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
None.
Parent topic: MAL - Email Interface


MAL0008I

MAL0008I  hh:mm:ss.ttt Initializing email interface
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
None.
Parent topic: MAL - Email Interface


MAL0009I

MAL0009I  hh:mm:ss.ttt Email interface successfully initialized
                       DCB header address     :  [002]
                       DCB Email address      :  [003]
                       Threshold              :  [004]
                       Bundle message count   :  [005]
                       Class                  :  [006]
                       Writer                 :  [007]
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
None.
Parent topic: MAL - Email Interface


MAL0010I

MAL0010I  hh:mm:ss.ttt Sending email
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
None.
Parent topic: MAL - Email Interface


MAL0011E

MAL0011E  hh:mm:ss.ttt Error during close of DD [002].
                       RC : [003]
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
Determine why an error occurred.
Parent topic: MAL - Email Interface


MAL0012E

MAL0012E  hh:mm:ss.ttt [002] with major [003] and minor [004] ended
                       with RC [005] (hex). Email interface is now disabled.
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
Determine why the problem occurred.
Parent topic: MAL - Email Interface


MAL0013E

MAL0013E  hh:mm:ss.ttt Dynalloc failed for DDname [002]
                       S99RC       :  [003]
                       S99INFO     :  [004]
                       S99ERROR    :  [005]
                       S99ERSN     :  [006]
Explanation:
Self-explanatory. See SA22-7608-xx: MVS Programming: Authorized Assembler Services Guide for information on [002] - [006].
Issued by:
TAURIP55
User response:
Determine why DYNALLOC failed.
Parent topic: MAL - Email Interface


MAL0014I

MAL0014I  hh:mm:ss.ttt Terminating email interface
Explanation:
Self-explanatory.
Issued by:
TAURIP55
User response:
None.
Parent topic: MAL - Email Interface


REC - Recovery Exception Handler

The Recovery Exception Handler performs the clean-up processing of Language Environment exceptions to ensure orderly task termination. This processing involves tasks such as closing open DCBs and other held resources for the associated job (task). It is also invoked for normal end of task (stop command).

  • REC0001E
  • REC0002E
  • REC0003E
  • REC0004I
  • REC0005I
  • REC0006I
  • REC0007I
  • REC0008I
  • REC0009E
  • REC0010E
  • REC0011E
  • REC0012E
  • REC0013E
  • REC0014W
  • REC0015I
  • REC0016I
  • REC0017I
  • REC0018I
  • REC0019I
  • REC0020S
  • REC0021S
  • REC0022I
  • REC0023I
  • REC0024E
Parent topic: Messages


REC0001E

REC0001E  hh:mm:ss.ttt Recovery exception handler was invoked.
                       CIB flag 5 : [002]
                       CIB flag 6 : [003]
                       Token      : [004]      (hex)
Explanation:
This is an informational message due to IPTRACE level 5 being set.

The two CIB (Language Environment Condition Information Block) flags have the following meanings:

CIB Flag 5 (CEL events)

1... .... ABEND caused

.1.. .... Program check caused

..1. .... Condition management raised TIU (Termination Imminent due to Unhandled condition)

...1 .... New condition result from a promote

.... 1... Signalled condition

.... .1.. Attention interrupt caused

CIB Flag 6 (CEL actions)

1... .... ABEND reason code valid

.1.. .... Math routine condition

..1. .... Resume allowed

...1 .... MRC type 1

.... 1... Enable only pass (no conditional pass)

.... .1.. Hcursor pointing to owning SF

.... ..1. Doing post SF0 scan

.... ...1 All members informed of condition

Issued by:
TAURIP36, TAURIP86
System administrator response:
Determine why recovery was invoked. If necessary, contact SupportLine.
Parent topic: REC - Recovery Exception Handler


REC0002E

REC0002E  hh:mm:ss.ttt Move cursor behind BALR in subtask was not successful.
Explanation:
In language environment recovery scenarios, the "cursor" (next instruction to be executed) can be set to a specific instruction, in this case behind a BALR instruction. This action failed.
System administrator response:
Determine why recovery was invoked. If necessary, contact SupportLine.
Parent topic: REC - Recovery Exception Handler


REC0003E

REC0003E  hh:mm:ss.ttt Error in program [002] at offset [003]
                       Original message : [004]
Explanation:
Self-explanatory. This message is issued to the operator console.
Issued by:
TAURIP36, TAURIP86
System administrator response:
Internal error. Send the appropriate logs to SupportLine.
Parent topic: REC - Recovery Exception Handler


REC0004I

REC0004I hh:mm:ss.ttt Checking for open files
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0005I

REC0005I hh:mm:ss.ttt DCB found
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0006I

REC0006I  hh:mm:ss.ttt Open DCB found for DDname [002] and data set
                       [003]
Explanation:
This message indicates that data set [003] was still open under DD name [002] when the error occurred and will be closed.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0007I

REC0007I hh:mm:ss.ttt DCB closed. RC [002]
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0008I

REC0008I hh:mm:ss.ttt TIU or promote call. No activities.
Explanation:
This message indicates that LE has given control to the z/Server program for retry.
Issued by:
TAURIP36, TAURIP86
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0009E

REC0009E hh:mm:ss.ttt Resume is not allowed. Subtask will terminate.
Explanation:
In language environment terminology, resume is the retry option for (E)STAE routines. In this case, retry is not allowed, so LE enforces percolation and terminates the subtask.
Issued by:
TAURIP36
System administrator response:
Determine why an error occurred. If necessary, contact SupportLine.
Parent topic: REC - Recovery Exception Handler


REC0010E

REC0010W hh:mm:ss.ttt Member not found in data set.
Explanation:
Self-explanatory.
Issued by:
TAURIP36
User response:
Specify a valid member.
Parent topic: REC - Recovery Exception Handler


REC0011E

REC0011E hh:mm:ss.ttt Data set or member already open for output by another user or job.
Explanation:
This message indicates an abend S213-30. See SA22-7626-xx: MVS System Codes.
Issued by:
TAURIP36
User response:
Use a unique member name that is not in use by anyone else.
Parent topic: REC - Recovery Exception Handler


REC0012E

REC0012E hh:mm:ss.ttt Data set opened for output used all available space.
Explanation:
This message indicates an abend SD37-4. See SA22-7626-xx: MVS System Codes.
Issued by:
TAURIP36
User response:
Reallocate the data set with larger space attributes and recreate the data set.
Parent topic: REC - Recovery Exception Handler


REC0013E

REC0013E  hh:mm:ss.ttt Insufficient access authority.
Explanation:
This message indicates an abend S913-38. See message ICH408I in JESYSMSG for details.
Issued by:
TAURIP36
System administrator response:
Provide the necessary access authority.
Parent topic: REC - Recovery Exception Handler


REC0014W

REC0014W hh:mm:ss.ttt Subtask not recovered. Error percolated to LE recovery.
Explanation:
This message is issued to the operator console. z/Server is not attempting to retry the error.
Issued by:
TAURIP36, TAURIP86
System administrator response:
Determine why an error occurred. If necessary, contact SupportLine.
Parent topic: REC - Recovery Exception Handler


REC0015I

REC0015I hh:mm:ss.ttt Cleanup for TSOE scheduler started
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0016I

REC0016I hh:mm:ss.ttt Extra buffer at address [002] freed.
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0017I

REC0017I hh:mm:ss.ttt XML image at address [002] freed.
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0018I

REC0018I hh:mm:ss.ttt Deleting ACEE for user [002] and TCB [003]
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0019I

REC0019I hh:mm:ss.ttt Checking for ACEE
Explanation:
This is an informational message.
Issued by:
TAURIP36
User response:
None.
Parent topic: REC - Recovery Exception Handler


REC0020S

REC0020S hh:mm:ss.ttt Critical error during data space processing. Server is terminating.
Explanation:
A system abend S067 has occurred. z/Server assumes that the data space was lost.
Issued by:
TAURIP36
System administrator response:
Check if the holder task is still running. If the holder task is running, contact SupportLine and provide the joblogs of all z/Server tasks.
Parent topic: REC - Recovery Exception Handler


REC0021S

REC0021S hh:mm:ss.ttt Critical error during SVC processing. Server is terminating.
Explanation:
An error occured when the SVC routine TAURAUTH was running. z/Server now assumes that SVC routine TAURAUTH is lost.
Issued by:
TAURIP36
System administrator response:
Check if the holder task is still running. If the holder task is running, contact SupportLine and provide the joblogs of all z/Server tasks and any system dump that may have occured.
Parent topic: REC - Recovery Exception Handler


REC0022I

REC0022I hh:mm:ss.ttt Condition token [002] hex ignored.
Explanation:
The z/Server recovery was invoked with an LE condition token [002] that is ignored.
Issued by:
TAURIP36
System administrator response:
None
Parent topic: REC - Recovery Exception Handler


REC0023I

REC0023I hh:mm:ss.ttt Cleanup resource table for
                      Data set     :  [002]
                      Member       :  [003]
Explanation:
The z/Server recovery was invoked and the recovery routine detected an ENQ for data set [002] and member [003].
Issued by:
TAURIP36
System administrator response:
None
Parent topic: REC - Recovery Exception Handler


REC0024E

REC0024E hh:mm:ss.ttt Sequential data set for FINDMEM not allowed.
Explanation:
A FINDMEM was issued and the user data set list contains a sequential data set.
Issued by:
TAURIP36
User response:
Remove the sequential data set from the data set list.
Parent topic: REC - Recovery Exception Handler


REX - REXX Interface

  • REX0001E
  • REX0002I
  • REX0003I
  • REX0004I
  • REX0005E
  • REX0006E
  • REX0007I
  • REX0008E
  • REX0009E
  • REX0010E
  • REX0011E
  • REX0012I
  • REX0013W
  • REX0014I
  • REX0015E
  • REX0016W
  • REX0017E
  • REX0018E
  • REX0019S
  • REX0020I
  • REX0021I
  • REX0022E
  • REX0023S
  • REX0024I
  • REX0025E
  • REX0026I
  • REX0027I
  • REX0028I
  • REX0029E
  • REX0030E
  • REX0031I
  • REX0032E
  • REX0033I
  • REX0034I
  • REX0035E
  • REX0036I
  • REX0037I
  • REX0038I
  • REX0039I
  • REX0040I
  • REX0041I
  • REX0042E
  • REX0043I
  • REX0044I
  • REX0045I
  • REX0046I
  • REX0047I
  • REX0048E
  • REX0049E
  • REX0050E
  • REX0051E
  • REX0052E
  • REX0053I
  • REX0054E
  • REX0055I
  • REX0056I
  • REX0057E
  • REX0058I
  • REX0059I
  • REX0060I
  • REX0062E
  • REX0063I
  • REX0064I
  • REX0065E
  • REX0066W
  • REX0067I
  • REX0068I
  • REX0069E
  • REX0070I
  • REX0071E
  • REX0072E
Parent topic: Messages


REX0001E

REX0001E  hh:mm:ss.ttt Error in variable access routine IRXEXCOM
                       Variable  : [002]
                       Access    : [003]
                       Response  : [004]
Explanation:
The IRXEXCOM function failed; see SA22-7790-xx: TSO/E REXX Reference for the meaning of [004].
Issued by:
TAURIP70
System administrator response:
Determine why the error occurred. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0002I

REX0002I  hh:mm:ss.ttt Before call of variable access routine IRXEXCOM
                       Variable  : [002]
                       Access    : [003]
                       SHVVALA   : [004] (hex)
                       SHVBUFL   : [005] (hex)
                       SHVVALL   : [006] (hex)
                       ENVBLOCK  : [007] (hex)
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP70
User response:
None.
Parent topic: REX - REXX Interface


REX0003I

REX0003I  hh:mm:ss.ttt After call of variable access routine IRXEXCOM
                       SHVRET    : [002] (hex)
                       SHVVALL   : [003] (hex)
                       RC        : [004] (hex)
Explanation:
This is an informational message.
Issued by:
TAURIP70
User response:
None.
Parent topic: REX - REXX Interface


REX0004I

REX0004I  hh:mm:ss.ttt Host command environment zComm called with command [002]
                       Using environment at address   : [003]
                       Using environment from subtask : [004]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP30
User response:
None.
Parent topic: REX - REXX Interface


REX0005E

REX0005E hh:mm:ss.ttt Variable [002] not numeric.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP14, TAURIP30, TAURIP71
User response:
Specify a numeric value for [002].
Parent topic: REX - REXX Interface


REX0006E

REX0006E hh:mm:ss.ttt Variable [002] contains invalid IP address.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP30
User response:
Specify a valid IP address for variable [002].
Parent topic: REX - REXX Interface


REX0007I

REX0007I  hh:mm:ss.ttt Address of REXX environment block is [002]
                       Userfield : [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0008E

REX0008E  hh:mm:ss.ttt Call to IRXINIT with function [002] failed.
                       RC : [003] (hex)
                       RC : [004] (hex)
Explanation:
The IRXINIT function [002] failed; see SA22-7790-xx: TSO/E REXX Reference.
Issued by:
TAURIP25
System administrator response:
Determine why the call to IRXINIT failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0009E

REX0009E hh:mm:ss.ttt Call to IRXSUBCM with function [002] failed with RC [003] (hex)
Explanation:
The IRXSUBCM function failed; see SA22-7790-xx: TSO/E REXX Reference.
[002]
IRXSUBCM function
[003]
IRXSUBCM return code
Issued by:
TAURIP25
User response:
Determine why the function failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0010E

REX0010E hh:mm:ss.ttt Call to ISPEXEC with function [002] failed with RC [003] (hex)
Explanation:
The ISPEXEC function failed; see SA22-7790-xx: TSO/E REXX Reference.
[002]
ISPEXEC function
[003]
ISPEXEC return code
User response:
Determine why the call to ISPEXEC failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0011E

REX0011E Call to ISPLINK with function [002] failed with RC [003] (hex)
Explanation:
The ISPLINK function failed; see SA22-7790-xx: TSO/E REXX Reference.
[002]
ISPLINK function
[003]
ISPLINK return code
Issued by:
TAURIP25
User response:
Determine why ISPLINK failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0012I

REX0012I hh:mm:ss.ttt ISPF environment is not available or address of TLD0 could not be found
Explanation:
During startup of the user server, z/Server tests the availability of an ISPF environment. There is no ISPF environment available.
Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0013W

REX0013W  hh:mm:ss.ttt A TSO/E environment already exists.
                       An additional dynamic environment is not created.
Explanation:
During startup of the scheduler or user server, z/Server tests the availability of a TSO environment. Because of the way the address space is started, no additional TSO environment needs to be created.
Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0014I

REX0014I  hh:mm:ss.ttt TSO environment successfully created
                       A (command processor parameter list) : [002]
Explanation:
This is an informational message.
Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0015E

REX0015E  hh:mm:ss.ttt Creation of TSO-Environment failed
                       RC         : [002]
                       RSN        : [003]
                       Abend code : [004]
Explanation:
The IKJTSOEV service failed; see SA22-7789-xx: TSO/E Programming Services.
Issued by:
TAURIP25
User response:
Determine why IKJTSOEV failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0016W

REX0016W  hh:mm:ss.ttt Variable [002] was not specified.
                       Default value is assumed.
Explanation:
This is an informational message due to IPTRACE level 1 being set. It is issued in response to an API call.
Issued by:
TAURIP70
User response:
None.
Parent topic: REX - REXX Interface


REX0017E

REX0017E Acronym for host command environment is invalid.  Either the environment is not available or is damaged.
This may happen if a reusable environment was not terminated.
Explanation:
The acronym ZCOMM is not specified in a control block.
System administrator response:
Determine why the control block acronym is not where it is supposed to be. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0018E

REX0018E Reusable host command environment terminated because communication area was invalid.
         Command for host command environment zComm was not executed.
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: REX - REXX Interface


REX0019S

REX0019S hh:mm:ss.ttt Host command environment not initialized. You must initialize a static environment for a TSO address space.
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: REX - REXX Interface


REX0020I

REX0020I hh:mm:ss.ttt Initializing static z/Server environment for client processing.
Explanation:
This is an informational message due to IPTRACE level 4 being set.
User response:
None.
Parent topic: REX - REXX Interface


REX0021I

REX0021I hh:mm:ss.ttt Terminating static z/Server Environment for client processing.
Explanation:
This is an informational message due to IPTRACE level 4 being set.
User response:
None.
Parent topic: REX - REXX Interface


REX0022E

REX0022E hh:mm:ss.ttt Call to IRXEXCOM failed with RC [002] (hex).
Explanation:
The IRXEXCOM function failed; see SA22-7790-xx: TSO/E REXX Reference.
Issued by:
TAURIP70
User response:
Determine why the call to IRXEXCOM failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0023S

REX0023S  hh:mm:ss.ttt User field of environment block is zero. Invalid environment.
                       Information for subtask is not available.
Explanation:
Self explanatory. This is probably caused by a storage overlay.
Issued by:
TAURIP30
System administrator response:
Obtain an SVC dump of the address space using the z/OS DUMP command and send it to SupportLine along with the job log(s).
Parent topic: REX - REXX Interface


REX0024I

REX0024I hh:mm:ss.ttt Initialize z/Server for [002] parallel REXX environment
Explanation:
This is an informational message. [002] is the configuration variable value named MULTI_REXX.

Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0025E

REX0025E hh:mm:ss.ttt z/Server is configured for single REXX environment but more than one subtask was found.
Explanation:
MULTI_REXX is set to 0 in the configuration file, indicating a single REXX environment. NUMTCB was set to a value other than 1, contradicting the MULTI_REXX setting.
Issued by:
TAURIP30
System administrator response:
Correct the configuration (see MULTI_REXX in the z/Server Installation Guide).
Parent topic: REX - REXX Interface


REX0026I

REX0026I  hh:mm:ss.ttt ISPF is available.
                       Address of TLD1 : [002]
                       Address of TLD0 : [003]
Explanation:
This is an informational message.
Issued by:
TAURIP69
User response:
None.
Parent topic: REX - REXX Interface


REX0027I

REX0027I hh:mm:ss.ttt Host command environment ended with RC [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP30
User response:
None.
Parent topic: REX - REXX Interface


REX0028I

REX0028I  hh:mm:ss.ttt =========================================================
                       ISPF [002]
                       =========================================================
Explanation:
This is an informational message due to IPTRACE level 5 being set. [002] is the ISPF control block being printed.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0029E

REX0029E hh:mm:ss.ttt Invalid acronym for control block [002] at address [003]
Explanation:
The expected acronym is not specified in the control block [002].
Issued by:
TAURIP71
System administrator response:
This may be an internal error. Obtain a dump using the z/OS DUMP command and send it to SupportLine along with the job log(s).
Parent topic: REX - REXX Interface


REX0030E

REX0030E hh:mm:ss.ttt ISPF table [002] not found
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP71
User response:
Determine why table [002] was not found. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0031I

REX0031I hh:mm:ss.ttt Reading table [002] from row [003] to row [004]
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued in response to an API call.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0032E

REX0032E  hh:mm:ss.ttt Specified value for TBFROW [002] or TBTROW [003] is invalid or outside the bounds
                       of table [004] with [005] lines.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP71
User response:
Specify valid values for TBFROW and TBTROW.
Parent topic: REX - REXX Interface


REX0033I

REX0033I hh:mm:ss.ttt Var : [002] Text : [003]
Explanation:
This is an informational message listing variable names and their content.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0034I

REX0034I hh:mm:ss.ttt Row [002] of table [003] contains [004] savenames.
Explanation:
This is an informational message due to IPTRACE level 4 being set. Save names are additional columns in one row.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0035E

REX0035E hh:mm:ss.ttt CRP [002] for table [003] is invalid.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP71
User response:
Specify a valid current row pointer.
Parent topic: REX - REXX Interface


REX0036I

REX0036I hh:mm:ss.ttt CRP for table [002] is set to line [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set. It is issued in response to an API call.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0037I

REX0037I hh:mm:ss.ttt RDA for row [002] at address [003] with EYE [004]
Explanation:
This message is issued in response to an API call. RDA is an ISPF control block, and eye denotes the control block acronym.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0038I

REX0038I hh:mm:ss.ttt Creating a non-reentrant REXX environment for TSO/E and ISPF
Explanation:
This is an informational message indicating that the configuration parameter MULTI_REXX is set to a value greater than 0.
Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0039I

REX0039I hh:mm:ss.ttt Creating a reentrant REXX environment for REXX
Explanation:
This is an informational message indicating that the configuration parameter MULTI_REXX is set to a value greater than 0.
Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0040I

REX0040I hh:mm:ss.ttt Host command environment [002] added on environment block [003].
Explanation:
This is an informational message.
Issued by:
TAURIP25
User response:
None.
Parent topic: REX - REXX Interface


REX0041I

REX0041I hh:mm:ss.ttt First 40 bytes of data : [002]
Explanation:
This is an informational message.
Issued by:
TAURIP70
User response:
None.
Parent topic: REX - REXX Interface


REX0042E

REX0042E hh:mm:ss.ttt No search argument found for table [002].
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP71
User response:
Specify a valid search argument.
Parent topic: REX - REXX Interface


REX0043I

REX0043I hh:mm:ss.ttt Number of entries in SAWA [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set. SAWA is an ISPF control block.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0044I

REX0044I  hh:mm:ss.ttt SAWA entry
                       Length of value for compare  : [002]
                       Address of value for compare : [003]
                       Operator for compare         : [004]
                       Index of varname             : [005]
Explanation:
This is an informational message.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0045I

REX0045I hh:mm:ss.ttt Number of matching rows for TBSCAN was [002]
Explanation:
This is an informational message due to IPTRACE level 3 being set.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0046I

REX0046I hh:mm:ss.ttt Row match for TBSCAN
Explanation:
This is an informational message due to IPTRACE level 3 being set.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0047I

REX0047I hh:mm:ss.ttt Table [002] not found using TLD1, trying TLD0.
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP71
User response:
None.
Parent topic: REX - REXX Interface


REX0048E

REX0048E hh:mm:ss.ttt Invalid severity [002] for command LOGMSG.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP14
User response:
Specify a valid severity for the LOGMSG command.
Parent topic: REX - REXX Interface


REX0049E

REX0049E hh:mm:ss.ttt More than 9 slots defined.
Explanation:
This message is issued in response to an API call. It indicates an LE restriction.
Issued by:
TAURIP14
System administrator response:
Contact SupportLine.
Parent topic: REX - REXX Interface


REX0050E

REX0050E hh:mm:ss.ttt Value for slot [002] greater than 80 bytes.
Explanation:
This message is issued in response to an API call.
User response:
Determine why this value was specified. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0051E

REX0051E hh:mm:ss.ttt Invalid format [002] for slot [003].
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP14
User response:
Specify a valid format.
Parent topic: REX - REXX Interface


REX0052E

REX0052E hh:mm:ss.ttt Invalid options [002] specified for LOGMSG.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP14
User response:
Specify a valid option.
Parent topic: REX - REXX Interface


REX0053I

REX0053I  hh:mm:ss.ttt =========================================================
                       [002]
                       =========================================================
Explanation:
This is an informational message. [002] is the title of the dump.
Issued by:
TAURIP79
User response:
None.
Parent topic: REX - REXX Interface


REX0054E

REX0054E hh:mm:ss.ttt Call to IRXEXEC failed with RC [002] (hex).
Explanation:
The IRXEXEC function failed; see SA22-7790-xx: TSO/E REXX Reference.
Issued by:
TAURIP79
System administrator response:
Determine why IRXEXEC failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0055I

REX0055I hh:mm:ss.ttt Internal REXX executor called with flag [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set. [002] describes the REXX exec to be executed (attribute NO/RENT).
Issued by:
TAURIP79
User response:
None.
Parent topic: REX - REXX Interface


REX0056I

REX0056I hh:mm:ss.ttt Searching for DSECT : [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP89
User response:
None.
Parent topic: REX - REXX Interface


REX0057E

REX0057E hh:mm:ss.ttt DSECT [002] not found
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP89
User response:
Determine why the DSECT was not found. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0058I

REX0058I  hh:mm:ss.ttt Number of DSECTs in table : [002]
                       ----------------------------------------------------
Explanation:
This is an informational message.
Issued by:
TAURIP89
User response:
None.
Parent topic: REX - REXX Interface


REX0059I

REX0059I hh:mm:ss.ttt [002] [003] [004] [005]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
[002]
Variable name
[003]
Variable length
[004]
Variable type
[005]
Variable content
Issued by:
TAURIP89
User response:
None.
Parent topic: REX - REXX Interface


REX0060I

REX0060I hh:mm:ss.ttt [002] variables in DSECT [003]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP89
User response:
None.
Parent topic: REX - REXX Interface


REX0062E

REX0062E  hh:mm:ss.ttt Address for DSECT [002] and length [003] invalid RC from VSMLOC : [004]
                       Storage not allocated in PVT
                       Storage overlaps free space
                       Storage overlaps other subpools
Explanation:
This message is issued in response to an API call. The address to be mapped by DSECT [002] is not a valid storage address. This is validated using the z/OS VSMLOC service. See SA22-7612-xx: MVS Programming: Authorized Assembler Services Reference, Volume 4 (SET-WTO) for the return code [004] from the VSMLOC service.
Issued by:
TAURIP89
User response:
Determine why an invalid storage address was specified to be mapped. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0063I

REX0063I hh:mm:ss.ttt DSECT utility called with function [002]
Explanation:
This is an informational message due to IPTRACE level 3 being set. It is issued in response to an API call.
Issued by:
TAURIP89
User response:
None.
Parent topic: REX - REXX Interface


REX0064I

REX0064I hh:mm:ss.ttt Varpool utility called with function [002]
Explanation:
This is an informational message due to IPTRACE level 3 being set. It is issued in response to an API call.
Issued by:
TAURIP90
User response:
None.
Parent topic: REX - REXX Interface


REX0065E

REX0065E hh:mm:ss.ttt Call to SPR failed with RC [002]
Explanation:
SPR is the standard pool routine. The return codes can be:
8
Variable not found
12
Invalid function
16
Variable pool is full
20
Variable pool not defined
24
Enqueue for VPUT failed
Issued by:
TAURIP90
System administrator response:
Determine why the error occurred. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0066W

REX0066W hh:mm:ss.ttt Variable [002] scope [003] not found
Explanation:
This is an informational message due to IPTRACE level 1 being set. It is issued in response to an API call.
Issued by:
TAURIP90
System administrator response:
Determine why the variable wasn't found. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0067I

REX0067I hh:mm:ss.ttt Varpool utility ended with RC [002]
Explanation:
This is an informational message due to IPTRACE level 3 being set.
Issued by:
TAURIP90
User response:
None.
Parent topic: REX - REXX Interface


REX0068I

REX0068I hh:mm:ss.ttt Call to IRXIC for subtask [002] with command [003] and environment
[004] ended with RC [005] (hex)
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP04
User response:
None.
Parent topic: REX - REXX Interface


REX0069E

REX0069E hh:mm:ss.ttt Reentrant REXX environment does not exist.
Explanation:
Self-explanatory.
Issued by:
TAURIP01
System administrator response:
Determine why a re-entrant REXX environment was expected. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0070I

REX0070I  hh:mm:ss.ttt Call to IRXEXCOM ended with RC [002]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: REX - REXX Interface


REX0071E

REX0071E  hh:mm:ss.ttt Enqueue for [002] [003] failed with RC [004]
Explanation:
Self-explanatory. [002] is the major name of the ENQ, [003] the minor name.
Issued by:
TAURIP14
System administrator response:
Determine why the ENQ failed. If necessary, contact SupportLine.
Parent topic: REX - REXX Interface


REX0072E

REX0072E  hh:mm:ss.ttt Command task is busy. Enqueue/Dequeue not possible. Please retry in a few moments.
Explanation:
The command task can only execute one command at a time. Currently it is busy for another request.
Issued by:
TAURIP14
System administrator response:
Retry the request. If the message persists, contact SupportLine.
Parent topic: REX - REXX Interface


SJB - Started Job

These messages are issued when a user server runs as a started job.

  • SJB0001E
  • SJB0002E
  • SJB0003E
  • SJB0004I
  • SJB0005E
  • SJB0006I
  • SJB0007E
  • SJB0008I
  • SJB0009W
  • SJB0010E
  • SJB0011E
Parent topic: Messages


SJB0001E

SJB0001E hh:mm:ss.ttt Configuration parameter TSOE_SJOB_NAME must be specified if a user server should start as a started task.
Explanation:
Self-explanatory.
Issued by:
TAURIP18
System administrator response:
Correct the configuration (see TSOE_SJOB_NAME in the z/Server Installation Guide).
Parent topic: SJB - Started Job


SJB0002E

SJB0002E hh:mm:ss.ttt Start command for user server [002] failed with return code [003]
Explanation:
Self-explanatory.

Return code:

252
Calling address space user is not authorized to use this user SVC.
253
No task level security environment to delete.
254
R1 does not point to a valid TAURACFA control block on entry to SVC routine.
255
Address Space has no ACEE (Accessor Environment Element).
256
Invalid function code.
257
Console buffer is too small.
Issued by:
TAURIP53
System administrator response:
Determine why the START command failed. If necessary, contact SupportLine.
Parent topic: SJB - Started Job


SJB0003E

SJB0003E hh:mm:ss.ttt A user server can only be started through a z/Server scheduler.
Explanation:
Self-explanatory.
Issued by:
TAURIP83
System administrator response:
Do not start a user server manually; let the scheduler issue the start command.
Parent topic: SJB - Started Job


SJB0004I

SJB0004I  hh:mm:ss.ttt Internal start command
                       [002]
                       RC : [003]    ASID : [004]
Explanation:
This is an informational message due to IPTRACE level 1 being set.
Issued by:
TAURIP53
User response:
None.
Parent topic: SJB - Started Job


SJB0005E

SJB0005E  hh:mm:ss.ttt User server not started. Unable to find JOBID for started task.
                       ASID :  [002]
                       RSN  :  [003]
Explanation:
After starting a user server, the scheduler waits for the user server to report itself ready. The user server did not report itself ready, so the scheduler checks system control blocks to see if the user server address space started correctly but cannot find the job name. Reason is the reason code from LOCASCB; see SA22-7611-xx: MVS Programming: Authorized Assembler Services Reference, Volume 3 (LLA-SDU). This happens typically when there was a JCL error or another startup problem for the user server.
Issued by:
TAURIP53
System administrator response:
Determine why the user server did not report itself ready. If necessary, contact SupportLine.
Parent topic: SJB - Started Job


SJB0006I

SJB0006I  hh:mm:ss.ttt Generated start command for user server :
                       [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP53
User response:
None.
Parent topic: SJB - Started Job


SJB0007E

SJB0007E  hh:mm:ss.ttt Unable to get jobname for ASID [002]
Explanation:
During startup, a z/Server was not able to resolve the jobname for ASID [002].
Issued by:
TAURIP27
System administrator response:
Restart z/Server with trace level 5. If the problem persists, contact SupportLine.
Parent topic: SJB - Started Job


SJB0008I

SJB0008I  hh:mm:ss.ttt Checking ASID [002] for server [003]
Explanation:
This is an informational message. During startup of a z/Server, a duplicate entry was found in the data space. z/Server will check if the entry can be reused or the new started z/Server is duplicated.
Issued by:
TAURIP27
System administrator response:
None.
Parent topic: SJB - Started Job


SJB0009W

SJB0009W  hh:mm:ss.ttt Entry for server [002] with ASID [003] will be reused for ASID [004]
Explanation:
During startup of a z/Server, a duplicate entry was found in the data space. z/Server will check the entry in the data space. Because the entry in the data space is no longer valid, the entry is reused for the new started z/Server. This situation may happen if a z/Server is canceled and was not able to delete its entry in the data space.
Issued by:
TAURIP27
System administrator response:
None.
Parent topic: SJB - Started Job


SJB0010E

SJB0010E  hh:mm:ss.ttt Entry for server [002] with ASID [003] already active. Startup will be terminated
Explanation:
During startup of a z/Server, a duplicate entry was found in the data space. z/Server will check the entry in the data space. Because the entry in the data space is valid, the startup of the new started z/Server is terminated. This situation may happen if a z/Server with the same name is started twice in the scope of the same holder task.
Issued by:
TAURIP27
System administrator response:
Check why the STC is started twice.
Parent topic: SJB - Started Job


SJB0011E

SJB0011E  hh:mm:ss.ttt Portrange for server [002] changed. Entry cannot be reused.
Explanation:
During startup of a z/Server, a duplicate entry was found in the data space. z/Server will check the entry in the data space. Because the entry in the data space is no longer valid, the entry can be reused for the new started z/Server. Because the portrange changed since the last startup, the entry cannot be reused and the startup of the new z/Server is terminated. This situation may happen if a z/Server is canceled and was not able to delete its entry in the data space.
Issued by:
TAURIP27
System administrator response:
Issue the command F <holder>,STOP,SCHED=<scheduler> with <scheduler> the name specified in [002] to delete the entry in the data space.
Parent topic: SJB - Started Job


SLR - TSO Scheduler Interface

These messages are produced when the scheduler TAURISPF is defined as a class 1 or class 2 scheduler.

  • SLR0001I
  • SLR0002I
  • SLR0003I
  • SLR0004I
  • SLR0005E
  • SLR0006E
  • SLR0007I
  • SLR0008E
  • SLR0009E
  • SLR0010E
  • SLR0011E
  • SLR0012E
  • SLR0013E
  • SLR0014E
  • SLR0015E
  • SLR0016E
  • SLR0017E
  • SLR0018I
  • SLR0019I
  • SLR0020S
  • SLR0021S
  • SLR0022S
  • SLR0023I
  • SLR0024E
  • SLR0025E
  • SLR0026I
  • SLR0027W
  • SLR0028E
  • SLR0029W
  • SLR0030I
  • SLR0031S
  • SLR0032E
  • SLR0033E
  • SLR0034E
  • SLR0035I
  • SLR0036I
  • SLR0037I
  • SLR0038W
  • SLR0039I
  • SLR0040I
  • SLR0041I
  • SLR0042I
  • SLR0043I
  • SLR0044I
  • SLR0045E
  • SLR0046I
  • SLR0047I
  • SLR0048I
  • SLR0049I
  • SLR0050E
  • SLR0051E
  • SLR0052E
  • SLR0053W
  • SLR0054I
  • SLR0055E
  • SLR0056E
  • SLR0057I
  • SLR0058I
  • SLR0059E
  • SLR0060E
  • SLR0061E
  • SLR0062E
  • SLR0063E
  • SLR0064I
  • SLR0065E
  • SLR0066E
  • SLR0067E
  • SLR0068I
  • SLR0069E
  • SLR0070I
  • SLR0071E
  • SLR0072E
  • SLR0073E
  • SLR0074I
  • SLR0077I
  • SLR0078E
  • SLR0079E
  • SLR0080E
  • SLR0081I
  • SLR0082E
  • SLR0083I
  • SLR0084E
  • SLR0085E
  • SLR0086I
  • SLR0087E
  • SLR0088E
  • SLR0089E
  • SLR0090E
  • SLR0091E
  • SLR0092E
  • SLR0093E
  • SLR0094E
  • SLR0095E
  • SLR0096E
  • SLR0097E
  • SLR0098E
  • SLR0099E
  • SLR0100E
  • SLR0101I
  • SLR0102W
  • SLR0103E
  • SLR0104E
  • SLR0105E
  • SLR0106E
  • SLR0107I
  • SLR0108E
  • SLR0109I
  • SLR0110I
  • SLR0111I
  • SLR0112E
  • SLR0113I
  • SLR0114E
  • SLR0115I
  • SLR0116I
  • SLR0117E
  • SLR0118E
  • SLR0119E
  • SLR0120E
  • SLR0121E
  • SLR0122E
  • SLR0123E
  • SLR0124E
  • SLR0125E
  • SLR0126I
  • SLR0127E
  • SLR0128E
  • SLR0129E
  • SLR0130E
  • SLR0131E
  • SLR0132E
  • SLR0134E
  • SLR0135S
  • SLR0136I
  • SLR0137E
  • SLR0139E
  • SLR0140E
  • SLR0141E
  • SLR0142I
  • SLR0143I
  • SLR0144E
  • SLR0145E
  • SLR0146I
  • SLR0148E
  • SLR0149E
  • SLR0150E
  • SLR0155E
Parent topic: Messages


SLR0001I

SLR0001I hh:mm:ss.ttt TSO/E scheduler initialization
Explanation:
This is an informational message.
Issued by:
TAURIP74
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0002I

SLR0002I hh:mm:ss.ttt TSO/E scheduler termination
Explanation:
This is an informational message.
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0003I

SLR0003I hh:mm:ss.ttt Stopping user server [002]
Explanation:
This is an informational message.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0004I

SLR0004I  hh:mm:ss.ttt Stop of user server was unsuccessful. RC [002]
Explanation:
This is an informational message.
System administrator response:
Determine why the stop command for the user server did not succeed. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0005E

SLR0005E  hh:mm:ss.ttt User area 1 is not defined. Define area and restart server
Explanation:
This refers to a deprecated parameter.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0006E

SLR0006E hh:mm:ss.ttt User area 1 is too small for [TSOPORTS) ports.
                      User area 1 must have at least [002] bytes.
Explanation:
This refers to a deprecated parameter.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0007I

SLR0007I  hh:mm:ss.ttt Routing message for user [002] to port [003]
                       Message length : [004]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0008E

SLR0008E hh:mm:ss.ttt Unexpected return code [002] (hex)
Explanation:
An unexpected return code was received in response to an API call.
Issued by:
TAURIP78
User response:
Determine why an unexpected return code was received. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0009E

SLR0009E hh:mm:ss.ttt ACEE for TCB is not available or userid of TCB is not the same as specified in input message
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0010E

SLR0010E hh:mm:ss.ttt User table is full. Increase size of User area 1
Explanation:
This refers to a deprecated parameter.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0011E

SLR0011E  hh:mm:ss.ttt Asid for job already exists on this lpar.
Explanation:
This refers to a deprecated parameter.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0012E

SLR0012E hh:mm:ss.ttt Job data set could not be opened
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0013E

SLR0013E hh:mm:ss.ttt I/O error during read of Job data set
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0014E

SLR0014E  hh:mm:ss.ttt User server [002] for user [003] already exists with jobid [004]. User server not started.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP53
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0015E

SLR0015E  hh:mm:ss.ttt TSO/E server [002] for user [003] submitted more than [004] times.
                       Limit reached.
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0016E

SLR0016E hh:mm:ss.ttt Server was marked unusable in a prior error
Explanation:
Self-explanatory.
System administrator response:
Restart the user server or scheduler after correcting the original problem.
Parent topic: SLR - TSO Scheduler Interface


SLR0017E

SLR0017E  hh:mm:ss.ttt Variable in JCL is invalid
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0018I

SLR0018I hh:mm:ss.ttt TSO/E server [002] for user [003] submitted
Explanation:
This is an informational message due to IPTRACE level 4 being set.
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0019I

SLR0019I  hh:mm:ss.ttt TSO/E scheduler initialization completed.
                       Delay after submit : [002] ms
                       Jobclass           : [003]
                       MSGCLASS           : [004]
                       First port         : [005]
                       Last  port         : [006]
                       Cleanup user jobs  : [007]
Explanation:
This is an informational message. [007] can have the values yes or no.
Issued by:
TAURIP74
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0020S

SLR0020S  hh:mm:ss.ttt TSO/E server [002] with JOBID [003] for user [004] had a JCL error.
                       Dispatcher is marked unusable.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0021S

SLR0021S  hh:mm:ss.ttt TSO/E server [002] with JOBID [003] for user [004] is duplicate.
                       Dispatcher is marked unusable.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0022S

SLR0022S  hh:mm:ss.ttt More than one active job [002] for user [003] found.
                       Dispatcher is marked unusable.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0023I

SLR0023I hh:mm:ss.ttt TSO/E server [002] with JOBID [003] for user [004] submitted.
Explanation:
This is an informational message.
Issued by:
TAURIP53
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0024E

SLR0024E  hh:mm:ss.ttt TSO/E server [002] with JOBID [003] for user [004] is not executing.
                       Reason [005]
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0025E

SLR0025E hh:mm:ss.ttt User [002] not found. Stop command ignored.
Explanation:
The user was not found in the user administration, so the requested stop command is not issued.
Issued by:
TAURIP53
System administrator response:
Check the entries in the user administration and determine why the specified user server is not running.
Parent topic: SLR - TSO Scheduler Interface


SLR0026I

SLR0026I hh:mm:ss.ttt Stop command for user [002] accepted.
Explanation:
This is an informational message.
Issued by:
TAURIP53
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0027W

SLR0027W hh:mm:ss.ttt Job [002] ID [003] system [004] phase [005]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0028E

SLR0028E hh:mm:ss.ttt TSO/E server for user [002] is not running. Please connect first.
Explanation:
No user server for user [002] could be found in user administration. Either the user server was addressed invalidly in an API call or the user server had terminated unexpectedly.
Issued by:
TAURIP78
User response:
Determine why the addressed user server could not be found in user administration.
Parent topic: SLR - TSO Scheduler Interface


SLR0029W

SLR0029W hh:mm:ss.ttt Job [002] ID [003] canceled
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0030I

SLR0030I hh:mm:ss.ttt Retrieving status for job [002] and user [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set and refers to deprecated functionality.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0031S

SLR0031S  hh:mm:ss.ttt Job  [002] for user [003] not found. Please reconnect for resubmit.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0032E

SLR0032E hh:mm:ss.ttt Job [002] for user [003] not ready. Please check Job status and wait.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0033E

SLR0033E  hh:mm:ss.ttt Job [002] for user [003] finished.
         Port entry cleared. Contact your administrator.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0034E

SLR0034E  hh:mm:ss.ttt Enqueue for internal reader failed. Please contact your
                       System administrator.
Explanation:
Probably due to a previous error, the ENQ governing the use of the internal reader was not freed.
Issued by:
TAURIP12
System administrator response:
Obtain a dump using the dump command and send it to SupportLine along with the job log(s).
Parent topic: SLR - TSO Scheduler Interface


SLR0035I

SLR0035I hh:mm:ss.ttt Job [002] ID [003] system [004] phase [005]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0036I

SLR0036I hh:mm:ss.ttt [002] [003] [004] [005] [006] [007]
Explanation:
This is an informational message due to IPTRACE level 4 being set. The placeholder values denote:
002
Job name
003
Job ID
004
Job phase
005
Last command used
006
Timestamp of record in user administration
007
Port
Issued by:
TAURIP27
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0037I

SLR0037I Time format : MMDDHHMMSS
         Phase       : 01-0D Not Running     Last-Command : I Initialized
                       0E    Running                        E Error
                       0F-1B Finished                       S Submit
                                                            P Stop
                                                            D Delete entry
         ======================================================================
         JobName  JOBId    userId phase Last command time   Port
         ======================================================================
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP27
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0038W

SLR0038W hh:mm:ss.ttt User [002] not found. Delete command ignored.
Explanation:
The delete command specified a user ID that is not available in the user administration control structures. The delete command is ignored.
Issued by:
TAURIP77
System administrator response:
Specify a valid user ID.
Parent topic: SLR - TSO Scheduler Interface


SLR0039I

SLR0039W hh:mm:ss.ttt User [002] deleted.
Explanation:
Self-explanatory.
Issued by:
TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0040I

SLR0040I ======================================================================
         Server Statistics
         ======================================================================
Explanation:
This is an informational message.
Issued by:
TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0041I

SLR0041I Submit      count [001] times
         Stop        count [002] times
         Communicate count [003] times
         Error       count 004] times
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0042I

SLR0042I ------------------------------------------------------------------
         Server configuration
         Environment variable                Value
         ------------------------------------------------------------------
         TSOE_DELAY_AFTER_SUBMIT : [001]
         TSOE_JOB_CLASS          : [002]
         TSOE_FIRST_PORT         : [003]
         TSOE_LAST_PORT          : [004]
         TSOE_CLEANUP            : [005]
         TSOE_PORTCHECK          : [006]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0043I

SLR0043I hh:mm:ss.ttt [002] for address space ended. RC [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set and refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0044I

SLR0044I hh:mm:ss.ttt Dequeue for major name [002] and minor name [003]
Explanation:
This is an informational message. The named resource is about to be dequeued.
Issued by:
TAURIP04, TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0045E

SLR0045E hh:mm:ss.ttt Dequeue failed. RC [002]
Explanation:
A DEQ failed. [002] can be:
>0
Original return code from DEQ macro; see SA22-7609-xx: MVS Programming: Authorized Assembler Services Reference, Volume 1 (ALE-DYN)
-4
Invalid function
-8
Invalid type
-12
Invalid scope
-16
Invalid length for minor name
Issued by:
TAURIP04, TAURIP77
System administrator response:
Determine why the DEQ failed. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0046I

SLR0046I hh:mm:ss.ttt Dequeue successful
Explanation:
This is an informational message.
Issued by:
TAURIP04, TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0047I

SLR0047I ======================================================================
         Initiator Information
         ======================================================================
Explanation:
This is an informational message.
Issued by:
TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0048I

SLR0048I Class                  : [001]
         Dedicated initiators   : [002]
         Allocated initiators   : [003]
         Used      initatiors   : [004]
Explanation:
This is an informational message.
Issued by:
TAURIP77
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0049I

SLR0049I  hh:mm:ss.ttt
                       Job prefix                    : [002]
                       Job search string             : [003]
                       Scheduler table               : [004]
                       Parallel user servers allowed : [005]
                       Handle ISPF statistics        : [006]
Explanation:
This is an informational message.
Issued by:
TAURIP74
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0050E

SLR0050E hh:mm:ss.ttt No console defined. Checking of ports or initiators will be disabled.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0051E

SLR0051E  hh:mm:ss.ttt [002] Ports defined, but only [003] initiators are dedicated to class [004].
                       Startup of server terminated.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0052E

SLR0052E  hh:mm:ss.ttt All [002] initiators are in use.
                       User server for [003] not submitted.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP53
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0053W

SLR0053W hh:mm:ss.ttt More than 80% of [002] initiators are in use.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0054I

SLR0054I TSOE_Initcheck..................................: [001]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0055E

SLR0055E hh:mm:ss.ttt Port [002] is not available.
Explanation:
The required port is not available for either a user server or scheduler to start. This message is issued to the operator console. More information can be found in one of the DD statements T000000x in job log. If the port check function is active, the command response to a NETSTAT command will be visible in hardcopy log.
Issued by:
TAURIP53
System administrator response:
Determine why the port is not available. If it is used by another product, change the port range of the server in both the scheduler and the holder configuration file.
Parent topic: SLR - TSO Scheduler Interface


SLR0056E

SLR0056E  hh:mm:ss.ttt Invalid console command for initiator check.
                       Startup of server terminated.
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0057I

SLR0057I hh:mm:ss.ttt Submit count for user [002] set to [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0058I

SLR0058I hh:mm:ss.ttt Message was not routed due to <ROUTEMSG>N</ROUTEMSG>
Explanation:
This is an informational message due to IPTRACE level 4 being set.
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0059E

SLR0059E  hh:mm:ss.ttt Error in XML document. Not all elements for PUTVAR or DELVAR specified.
                      PUTVAR requires VARTYPE, VARNAME and VARTEXT
                      DELVAR requires VARTYPE and VARNAME
Explanation:
Self-explanatory.
User response:
Correct the XML document sent.
Parent topic: SLR - TSO Scheduler Interface


SLR0060E

SLR0060E hh:mm:ss.ttt Variable for JOB not found. Check message SPR0007E
Explanation:
This refers to deprecated functionality.

System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0061E

SLR0061E hh:mm:ss.ttt Logon not valid. Userid and/or password missing.
Explanation:
This message is issued in response to an API call.
User response:
Repeat the logon with a correct user ID and password.
Parent topic: SLR - TSO Scheduler Interface


SLR0062E

SLR0062E  hh:mm:ss.ttt [002] for Userid [003] was not successful.
          Reason : [004] hex.
Explanation:
This message is issued if a RACINIT or RACROUTE with REQUEST=VERIFY was not successful. [002] contains the API command used, for instance VERIFY LOGON. [003] contains the user ID. Refer to SA22-7692-xx RACROUTE Macro Reference for the meaning of [004].
Issued by:
TAURIP78
System administrator response:
Determine why RACINIT or RACROUTE failed.
Parent topic: SLR - TSO Scheduler Interface


SLR0063E

SLR0063E  hh:mm:ss.ttt Password/newPassword for Userid [002] is invalid.
                       Password must be hexadecimal
                       Password may have a length of 16 bytes
                       Password must be DES encrypted
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP75
User response:
Use a valid XML document with correct length and valid characters.
Parent topic: SLR - TSO Scheduler Interface


SLR0064I

SLR0064I  hh:mm:ss.ttt Password hexadecimal : [002]
                       Password encrypted   : [003]
                       Password decrypted   : [004]
Explanation:
This is an informational message due to IPTRACE level 4 being set and refers to deprecated functionality.
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0065E

SLR0065E hh:mm:ss.ttt Input message for TSO/E scheduler must be an XML document
Explanation:
Self-explanatory.
User response:
Specify a valid XML document.
Parent topic: SLR - TSO Scheduler Interface


SLR0066E

SLR0066E hh:mm:ss.ttt An XML document for a TSOE/E scheduler must start with the root element <TSOSCHED>
Explanation:
Self-explanatory.
User response:
Specify a valid XML document.
Parent topic: SLR - TSO Scheduler Interface


SLR0067E

SLR0067E hh:mm:ss.ttt Attributes missing for element <ROUTEMSG>
Explanation:
Self-explanatory.
Issued by:
TAURIP78
User response:
Specify a correct <ROUTEMSG> element.
Parent topic: SLR - TSO Scheduler Interface


SLR0068I

SLR0068I hh:mm:ss.ttt Calling program [002] with command [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set and refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0069E

SLR0069E  hh:mm:ss.ttt Stop or logoff command for user [002] unsuccessful.
                       RSN :  [003]
Explanation:
This refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0070I

SLR0070I hh:mm:ss.ttt Verify for userid [002] successful
Explanation:
This is an informational message.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0071E

SLR0071E hh:mm:ss.ttt Verify for userid [002] unsuccessful. RSN [003]
Explanation:
The security check failed; see SA22-7692-xx: Security Server RACROUTE Macro Reference for details.

The hexadecimal reason code can be:

04
The user profile is not defined to RACF
08
The password is not authorized
0C
The password has expired
10
The new password is not valid
14
The user is not defined to the group
Issued by:
TAURIP78
System administrator response:
Determine why the security check failed. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0072E

SLR0072E hh:mm:ss.ttt Changed password invalid. Specify Userid, old password and new password.
Explanation:
Self-explanatory.
User response:
Retry the password word with all required values: User ID, old password, new password.
Parent topic: SLR - TSO Scheduler Interface


SLR0073E

SLR0073E  hh:mm:ss.ttt Password change for userid [002] unsuccessful.
                       RSN [003]
Explanation:
Self-explanatory. [003] is the RACF reason code.
Issued by:
TAURIP78
System administrator response:
Determine why the password change was unsuccessful. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0074I

SLR0074I hh:mm:ss.ttt Password change for userid [002] successful
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0077I

SLR0077I hh:mm:ss.ttt Wait for [002] ms done.
Explanation:
This is an informational message in response to an API call.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0078E

SLR0078E  hh:mm:ss.ttt Command [002] for server [003] not processed.
                       RSN : [004]
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0079E

SLR0079E hh:mm:ss.ttt Unexpected return code [002] from user administration
Explanation:
See message HLD0030I for an explanation of the return code.
Issued by:
TAURIP53, TAURCEA
System administrator response:
Determine why the return code was issued. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface
Related information
HLD0030I


SLR0080E

SLR0080E hh:mm:ss.ttt This server only accepts messages routed from a TSO/E scheduler
Explanation:
Self-explanatory.
Issued by:
TAURIP73
System administrator response:
Correct the configuration; see ROUTE_ONLY in the z/Server Installation Guide.
Parent topic: SLR - TSO Scheduler Interface


SLR0081I

SLR0081I hh:mm:ss.ttt User server policy is: [002]
Explanation:
This is an informational message.
Issued by:
TAURIP74
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0082E

SLR0082E  hh:mm:ss.ttt Invalid value for TSOE_U_POLICY. Valid values are:
                      0    :   Start user server with a job
                      1    :   Start user server with a started job
                      2    :   Start user server ISPF client gateway
                      4    :   Start user server with a started task
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0083I

SLR0083I hh:mm:ss.ttt User server control utility called with command [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set. [002] is one of the following: LOGON, LOGOFF, ADDUSRV, RESTART, VERIFY.
Issued by:
TAURIP53
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0084E

SLR0084E  hh:mm:ss.ttt No response from user server [002] for [003] seconds.
                       Connection terminated due to timeout.
Explanation:
A command was issued to the user server [002] that did not send back a response within the DIALOG_TIMEOUT configuration parameter.
Issued by:
TAURIP78
System administrator response:
Either retry the connection or specify a higher value for DIALOG-TIMEOUT.
Parent topic: SLR - TSO Scheduler Interface


SLR0085E

SLR0085E  hh:mm:ss.ttt If more than one user server is allowed the policy must be a started job or CEA. TSOE_U_POLICY=1 or TSOE_U_POLICY=8
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0086I

SLR0086I hh:mm:ss.ttt [002] user servers found for userid [003]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP27
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0087E

SLR0087E hh:mm:ss.ttt Maximum number of user servers for user [002] reached.
Explanation:
The maximum number of user servers is determined by the port range specified using TSOE_FIRST_PORT and TSOE_LAST_PORT. Each user server will get a port assigned in that range. No more ports are left.
Issued by:
TAURIP53
System administrator response:
Increase the port range by increasing TSOE_FIRST_PORT and TSOE_LAST_PORT in the scheduler configuration and DSP_PORT_LOW and DSP_PORT_HIGH in the holder configuration, if necessary. Restart the scheduler or both the scheduler and the holder task.
Parent topic: SLR - TSO Scheduler Interface


SLR0088E

SLR0088E hh:mm:ss.ttt User table is full. Increase portrange for server.
Explanation:
The maximum number of user servers is determined by the port range specified using TSOE_FIRST_PORT and TSOE_LAST_PORT. Each user server will get a port assigned in that range. No more entries are left in the user table.
Issued by:
TAURIP27
System administrator response:
Increase the port range by increasing TSOE_FIRST_PORT and TSOE_LAST_PORT in the scheduler configuration and DSP_PORT_LOW and DSP_PORT_HIGH in the holder configuration, if necessary. Restart the scheduler or both the scheduler and the holder task.
Parent topic: SLR - TSO Scheduler Interface


SLR0089E

SLR0089E hh:mm:ss.ttt Command ADDUSRV is only allowed for policy started jobs.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP53
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0090E

SLR0090E hh:mm:ss.ttt Timeout or Timeout_Action are not allowed for a TSO/E scheduler. Startup aborted.
Explanation:
TIMEOUT_ACTION is a deprecated keyword.
Issued by:
TAURIP18
System administrator response:
Correct the configuration; a scheduler configuration file must not contain the parameter TIMEOUT.
Parent topic: SLR - TSO Scheduler Interface


SLR0091E

SLR0091E hh:mm:ss.ttt For Timeout_Action = STOP the user administration must be in a common access data space
Explanation:
TIMEOUT_ACTION is a deprecated keyword.
Issued by:
TAURIP18
System administrator response:
Remove the keyword from the configuration file.
Parent topic: SLR - TSO Scheduler Interface


SLR0092E

SLR0092E  hh:mm:ss.ttt User servers with TIMEOUT_ACTION=STOP must be started with POLICY=1 (Started task).
          Timeout is ignored.
Explanation:
The original message referred to deprecated functionality. Today, a user server can no longer terminate if it is not recognized in the user administration control structures. The user server issuing this message has somehow disappeared from the user administration control structures and so cannot terminate. This message is issued to the operator console.
Issued by:
TAURIP27
System administrator response:
Determine why the user server is not present in the user administration control structures. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0093E

SLR0093E  hh:mm:ss.ttt Bad RC [002] from user administration for set timeout.
          Timeout is ignored. User server continues with bad performance
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP00
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0094E

SLR0094E hh:mm:ss.ttt User server [002] for user [003] is no longer active due to timeout.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0095E

SLR0095E hh:mm:ss.ttt Restart of user server for [002] on port [003] failed with RC [004].
Explanation:
When (re)starting the user server, a failure was encountered. RC [004] can be:
4
ASCB NOT FOUND
8
VAB NOT FOUND
C
CAUB NOT FOUND
10
JOBNAME NOT VALID

ASCB, VAB and CAUB are z/OS control block names.

Issued by:
TAURIP78
System administrator response:
Determine why the restart failed. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0096E

SLR0096E hh:mm:ss.ttt Restart for port [002] not possible. No timeout entry found.
Explanation:
A user server is requested to be started at port [002]. Restarting a user server is only possible if there is a so-called timeout entry (STCTIMEO) in the user administration control structures. No such entry was found.
Issued by:
TAURIP78
System administrator response:
Determine why there is no timeout entry or start a user server instead of restarting it.
Parent topic: SLR - TSO Scheduler Interface


SLR0097E

SLR0097E hh:mm:ss.ttt No port for RESTART specified.
Explanation:
This message is issued in response to an API call. Restart without a port specification is only possible when there is exactly one user server running for a user. In all other cases the port number must be specified, too.
User response:
Specify a port number for the RESTART command.
Parent topic: SLR - TSO Scheduler Interface


SLR0098E

SLR0098E  hh:mm:ss.ttt Port for RESTART not numeric or has more than 5 digits.
Explanation:
This message is issued in response to an API call. The specified port is invalid.
User response:
Specify a valid port number.
Parent topic: SLR - TSO Scheduler Interface


SLR0099E

SLR0099E hh:mm:ss.ttt [002] XML document does not contain a valid command for a TSO/E scheduler
Explanation:
Self-explanatory.
Issued by:
TAURIP78
User response:
Specify a correct XML document.
Parent topic: SLR - TSO Scheduler Interface


SLR0100E

SLR0100E hh:mm:ss.ttt Size of extra buffer with [002] bytes is too small to hold all output from XML document.
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0101I

SLR0101I hh:mm:ss.ttt Extra buffer for multiple XML images allocated at address [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0102W

SLR0102W hh:mm:ss.ttt User administration not in a dataspace. Command ignored.
Explanation:
This message is issued to the operator console and refers to deprecated functionality.
Issued by:
TAURIP27
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0103E

SLR0103E hh:mm:ss.ttt If more than one user server is running ROUTEMSG requires the specification of a PORT
Explanation:
This message is issued in response to an API call. Restart without a port specification is only possible when there is exactly one user server running for a user. In all other cases the port number must be specified, too.
Issued by:
TAURIP78
User response:
Specify a port number for the RESTART command.
Parent topic: SLR - TSO Scheduler Interface


SLR0104E

SLR0104E hh:mm:ss.ttt No user server on port [002] found for user [003]
Explanation:
This message is issued in response to an API call if either the specified port or the specified user is not found in the user administration control structures.
Issued by:
TAURIP78
User response:
Use the GETPORT command to get all active ports for a user. Then issue the command specifying the appropriate port.
Parent topic: SLR - TSO Scheduler Interface


SLR0105E

SLR0105E hh:mm:ss.ttt User server on port [002] belongs to user [003] and is invalid for [004]
Explanation:
This message is issued in response to an API call with invalid parameters. The user server [003] listens on port [002], while the API call assumes that port [002] belongs to user server [004] according to the user administration control structures.
Issued by:
TAURIP78
User response:
Use a valid port / user server combination.
Parent topic: SLR - TSO Scheduler Interface


SLR0106E

SLR0106E hh:mm:ss.ttt A deferred LOGON is only allowed for started jobs.
Explanation:
This refers to a deprecated parameter.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0107I

SLR0107I hh:mm:ss.ttt Deferred LOGON for user [002] successful
Explanation:
This is an informational message.
Issued by:
TAURIP53
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0108E

SLR0108E  hh:mm:ss.ttt Load of XML exit [002] failed.
                       MSG : [003]
Explanation:
This message is issued in response to an API call. The specified XML exit program to be used for parsing could not be loaded. [003] is the original LE error message.
Issued by:
TAURIP78
System administrator response:
Check that the specified XML exit program is contained in an accessible load library; if necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0109I

SLR0109I hh:mm:ss.ttt Calling XML exit [002]
Explanation:
This is an informational message due to IPTRACE level 3 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0110I

SLR0110I hh:mm:ss.ttt XML exit [002] ended. RC [003]
Explanation:
This is an informational message due to IPTRACE level 3 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0111I

SLR0111I hh:mm:ss.ttt TSO/E scheduler initialization/termination routine called with function [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP74
System administrator response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0112E

SLR0112E hh:mm:ss.ttt Initialization/termination exit for TSO/E scheduler failed for function [002]. RC [003]
Explanation:
The exit failed, so the user server is not started. This message is issued to the operator console. See message HLD0030I for an explanation of the return code [003].
Issued by:
TAURIP74
System administrator response:
Determine why the exit failed. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface
Related information
HLD0030I


SLR0113I

SLR0113I hh:mm:ss.ttt [002] for port [003] and user [004] successful.
Explanation:
This is an informational message. [002] is the server command issued to the user server [004] on port [003].
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0114E

SLR0114E  hh:mm:ss.ttt Load of command exit [002] for [003] failed.
                       MSG : [004]
Explanation:
This message is issued in response to an API call. The specified program to be used as a command exit could not be loaded. [003] is the command to be executed, [004] is the original LE error message.
Issued by:
TAURIP78
System administrator response:
Check that the named program is contained in an accessible load library; if necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0115I

SLR0115I hh:mm:ss.ttt Calling command exit [002] for [003] at address [004]
Explanation:
This is an informational message due to IPTRACE level 3 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0116I

SLR0116I hh:mm:ss.ttt Command exit [002] ended. RC [003]
Explanation:
This is an informational message due to IPTRACE level 3 being set.
Issued by:
TAURIP78
User response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0117E

SLR0117E hh:mm:ss.ttt Command [002] not executed due to command exit
Explanation:
A command exit prevented the command [002] from being executed.
Issued by:
TAURIP78
User response:
If tracing is active, check the return code from the command exit. Otherwise, reproduce the problem with tracing active.
Parent topic: SLR - TSO Scheduler Interface


SLR0118E

SLR0118E  hh:mm:ss.ttt Deletion of [002] failed
                       RSN : [003]
Explanation:
The specified program [002] failed to be deleted. The reason code from CEERELES is [003]; see SA22-7561-xx: Language Environment Programming Guide
Issued by:
TAURIP78
System administrator response:
Determine why CEERELES failed. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0119E

SLR0119E hh:mm:ss.ttt Command [002] is only allowed for a class 2 scheduler.
Explanation:
Self-explanatory.
Issued by:
TAURIP78
System administrator response:
Correct the configuration; see TSOE_SCHEDULER in the z/Server Installation Guide.
Parent topic: SLR - TSO Scheduler Interface


SLR0120E

SLR0120E hh:mm:ss.ttt No more than 10 slaves allowed.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0121E

SLR0121E hh:mm:ss.ttt Dataspace required to initiate slaves.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0122E

SLR0122E hh:mm:ss.ttt Slaves only allowed for a class 1 scheduler.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0123E

SLR0123E hh:mm:ss.ttt A slave is required to execute command [002] but no slaves are defined.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0124E

SLR0124E hh:mm:ss.ttt No configuration file for slaves defined.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0125E

SLR0125E hh:mm:ss.ttt Only a master server can create slaves.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0126I

SLR0126I  hh:mm:ss.ttt Routing message for command [002] to slave on port [003]
                       Length of message : [004]
Explanation:
This is an informational message due to IPTRACE level 4 being set and refers to deprecated functionality.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0127E

SLR0127E hh:mm:ss.ttt Slaves are only allowed if a server is a started task
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0128E

SLR0128E hh:mm:ss.ttt No proc for slaves defined
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0129E

SLR0129E hh:mm:ss.ttt KILL is not allowed for jobs.
Explanation:
This refers to deprecated functionality.
Issued by:
TAURIP78
System administrator response:
Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0130E

SLR0130E  hh:mm:ss.ttt User server for user [002] and port [003] has an invalid combination for timeout and jobid.
Explanation:
Part of this message refers to deprecated functionality. Either the user server address space was not started with the parameter TSOE_USER=1 or the user server did not set the READY flag in the user administration control structures.
Issued by:
TAURIP53
System administrator response:
Check whether the configuration file for user servers contains TSOE_USER=1 or why the READY flag wasn't set.
Parent topic: SLR - TSO Scheduler Interface


SLR0131E

SLR0131E  hh:mm:ss.ttt User server did not signal READY after a wait period of 10 X [002] ms. Command was not routed to
         the user server.
Explanation:
This message is normally issued when the user server has not marked itself ready yet in the user administration control structures. After the named amount of milliseconds (configuration parameter TSOE_DELAY_SUBMIT) the scheduler informs the client of this and asks the client to retry later.
Issued by:
TAURIP78
System administrator response:
Determine why the user server did not signal itself ready. This may be due to too much CPU load on the z/OS system or wrong WLM settings for user servers.
Parent topic: SLR - TSO Scheduler Interface


SLR0132E

SLR0132E hh:mm:ss.ttt TSOE_DELAY_SUBMIT must be at least 1000 ms for a policy uneven JOB.
Explanation:
The configuration parameter TSOE_DELAY_SUBMIT must be at least 1 second.
Issued by:
TAURIP18
System administrator response:
Define at least TSOE_DELAY_SUBMIT=1 in the configuration.
Parent topic: SLR - TSO Scheduler Interface


SLR0134E

SLR0134E  hh:mm:ss.ttt User server with jobid [002] for user [003] was stopped without logoff.
                       Port entry is cleared
Explanation:
Self-explanatory. This message is issued to the operator console.
Issued by:
TAURIP78
System administrator response:
Determine if the user server had other problems before this message was issued. If necessary, contact SupportLine. The clearing of the port entry may mean that the user server is then unable to terminate itself because its entry in the user administration control structures is gone (msgSLR0092E).
Parent topic: SLR - TSO Scheduler Interface


SLR0135S

SLR0135S  hh:mm:ss.ttt Port [002] for z/Server scheduler [003] locked because port was not available.
Explanation:
This message is issued to the operator console.
Issued by:
TAURIP27
System administrator response:
Determine why the port has become unavailable. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0136I

SLR0136I  hh:mm:ss.ttt Port [002] for z/Server scheduler [003] is now unlocked and available for use.
Explanation:
This is an informational message.
Issued by:
TAURIP77
System administrator response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0137E

SLR0137E  hh:mm:ss.ttt Port [002] for z/Server scheduler [003] is not locked.
Explanation:
The port specified in the unlock command is not locked and cannot be unlocked.
Issued by:
TAURIP77
System administrator response:
Specify a locked port.
Parent topic: SLR - TSO Scheduler Interface


SLR0139E

SLR0139E  hh:mm:ss.ttt Port [002] for unlock is not within portrange of scheduler [003].
Explanation:
The port specified in the unlock command is not in the port range belonging to the scheduler addressed and cannot be unlocked.
Issued by:
TAURIP77
System administrator response:
Specify the command to the scheduler that owns the port.
Parent topic: SLR - TSO Scheduler Interface


SLR0140E

SLR0140E  hh:mm:ss.ttt Scheduler [002] is locked. Start of user server is disabled.
Explanation:
This message is issued to the operator console in response to a lock operator command.

Issued by:
TAURIP27
System administrator response:
Determine why the scheduler is locked. If necessary, unlock it.
Parent topic: SLR - TSO Scheduler Interface


SLR0141E

SLR0141E  hh:mm:ss.ttt Unable to resolve port for ASID [002]
Explanation:
During startup, the user server attempts to resolve its port using the user administration control structures, which was unsuccessful.
Issued by:
TAURIP18
System administrator response:
Determine why the port could not be resolved. If necessary, contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0142I

SLR0142I  hh:mm:ss.ttt Asid [002] is using port [003]
Explanation:
This is an informational message.
Issued by:
TAURIP18
System administrator response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0143I

SLR0143I  hh:mm:ss.ttt Resolving port for ASID [002] using data space
Explanation:
This is an informational message.
Issued by:
TAURIP18
System administrator response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0144E

SLR0144E  hh:mm:ss.ttt Limited server can only be stopped or started through a holder task
Explanation:
An operator tried to stop a scheduler with stop command. The scheduler is defined as limited (LIMITED_SERVER=1).
Issued by:
TAURIP04
System administrator response:
Use F <holder>,STOP,SCHED=<scheduler>instead.
Parent topic: SLR - TSO Scheduler Interface


SLR0145E

SLR0145E hh:mm:ss.ttt User server is running without a corresponding entry in  the user administration. This server is not adminstered and therefore was terminated.
Explanation:
A running user server had no entry in the user administration. Because this situation is not consistent, the running user server is terminated.
Issued by:
TAURIP27
System administrator response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0146I

SLR0146I hh:mm:ss.ttt Call to REXX [002] ended. RC [003] (hex)
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP78
System administrator response:
None.
Parent topic: SLR - TSO Scheduler Interface


SLR0148E

SLR0148E  hh:mm:ss.ttt POST CEATASK can only be used in a user server started with policy 8 (CEA)
Explanation:
A client had sent a message with the POST CEATASK request, but the user server does not belong to a scheduler started with TSOE_U_POLICY=8.
Issued by:
TAURIP78
User response:
Connect to a scheduler that allows the function "Launch ISPF".
Parent topic: SLR - TSO Scheduler Interface


SLR0149E

SLR0148E  hh:mm:ss.ttt POST CEATASK not processed because CEATASK is already busy.
Explanation:
A client had sent an INITIALIZE_CEA_DIALOG request, but CEATASK is already busy.
Issued by:
TAURIP78
User response:
INITIALIZE_CEA_DIALOG can only be sent once. Contact SupportLine.
Parent topic: SLR - TSO Scheduler Interface


SLR0150E

SLR0148E  hh:mm:ss.ttt Givesocket for CEATASK failed
                       Return code ...... : [002] (hex)
                       Reason code .......: [003] (hex)
Explanation:
A client had sent an INITIALIZE_CEA_DIALOG request, but the GIVESOCKET request for CEATASK failed.
Issued by:
TAURIP78
User response:
Restart the user server address space with trace level 6 set in the configuration file. If the error persists, contact SupportLine and provide the trace output.
Parent topic: SLR - TSO Scheduler Interface


SLR0155E

SLR0155E hh:mm:ss.ttt Initialization of the CEA dialog is only allowed for a user server with policy 8.
Explanation:
The client requested an initialization for a CEA dialog, but the owning scheduler was not started with policy=8 (CEA).
Issued by:
TAURIP73
System administrator response:
Start the scheduler with policy=8 (CEA).
Parent topic: SLR - TSO Scheduler Interface


SPR - Standard Pool Routine

The standard pool routine processes variables similar to the ISPF dialog manager.

  • SPR0001I
  • SPR0002E
  • SPR0003E
  • SPR0004I
  • SPR0005I
  • SPR0006I
  • SPR0007E
  • SPR0008W
  • SPR0009E
  • SPR0010S
  • SPR0011I
  • SPR0012I
  • SPR0013I
  • SPR0014I
  • SPR0015I
  • SPR0016I
Parent topic: Messages


SPR0001I

SPR0001I  hh:mm:ss.ttt Standard pool routine called with
                       Function           :   [002]
                       Variable type      :   [003]
                       Variable name      :   [004]
                       Variable content   :   [005]
Explanation:
This is an informational message.
Issued by:
TAURIP20
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0002E

SPR0002E  hh:mm:ss.ttt Standard pool routine called with invalid Function.
                       Function : [002]
Explanation:
Self-explanatory. Valid functions are:
VPUT
Write variable
VGET
Read variable
VDEL
Delete variable
User response:
Specify a valid function.
Parent topic: SPR - Standard Pool Routine


SPR0003E

SPR0003E  hh:mm:ss.ttt Variable pool is too small to hold all variables.
                       Current size is [002]
Explanation:
Self-explanatory.
Issued by:
TAURIP20
User response:
Increase the size of the variable pool. See VPOOLSIZE in the z/Server Installation Guide.
Parent topic: SPR - Standard Pool Routine


SPR0004I

SPR0004I  hh:mm:ss.ttt Variable found in pool at entry [002]
                       FindFlag     : [003]
                       Address      : [004]
                       Entry length : [005]
Explanation:
This is an informational message due to IPTRACE level 4 being set. Find flag [003] can be:
X'01'
Variable found
X'02'
Variable contains the same content
X'04'
The length of the content is equal
Issued by:
TAURIP20
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0005I

SPR0005I hh:mm:ss.ttt Variable [002] found for substitution
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP20
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0006I

SPR0006I hh:mm:ss.ttt Variable [002] contains [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP19
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0007E

SPR0007E hh:mm:ss.ttt Variable [002] not found in variable pool
Explanation:
Self-explanatory.
Issued by:
TAURIP19
User response:
Specify a valid variable name.
Parent topic: SPR - Standard Pool Routine


SPR0008W

SPR0008W  hh:mm:ss.ttt Result after substitution [002] bytes greater than input buffer.
                       Result is truncated.
Explanation:
This is an informational message due to IPTRACE level 2 being set.
Issued by:
TAURIP19
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0009E

SPR0009E hh:mm:ss.ttt No variable pool defined.
Explanation:
Self-explanatory.
Issued by:
TAURIP20
User response:
Define a variable pool using the VPOOLSIZE configuration parameter.
Parent topic: SPR - Standard Pool Routine


SPR0010S

SPR0010S  hh:mm:ss.ttt Enqueue for variable pool failed. Please contact
your                   System administrator.
Explanation:
Self-explanatory.
Issued by:
TAURIP20
System administrator response:
Determine why the enqueue failed. If necessary, contact SupportLine.
Parent topic: SPR - Standard Pool Routine


SPR0011I

SPR0011I Address of pool       : [001]
         Size                  : [002]
         Freespace             : [003] Bytes
         Number of variables   : [004] Bytes
         Variable pool information
         =========================== Pool content ========================
    Type     Name    Content
         =================================================================
Explanation:
The pool statistics are returned.
Issued by:
TAURIP77
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0012I

SPR00012I hh:mm:ss.ttt Variable pool not defined.
Explanation:
The variable pool used is not defined.
Issued by:
TAURIP77
User response:
Use an existing variable pool.
Parent topic: SPR - Standard Pool Routine


SPR0013I

SPR00013I [001]    [002]   [003]
Explanation:
The type ([001]), name ([002]), and content ([003]) of the variable are listed.
Issued by:
TAURIP77
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0014I

SPR00014I hh:mm:ss.ttt Datastream before substitution. Length : [002]
Explanation:
This is an informational message due to IPTRACE level 6 being set.
Issued by:
TAURIP19
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0015I

SPR00015I hh:mm:ss.ttt Datastream after substitution. Length : [002]
Explanation:
This is an informational message due to IPTRACE level 6 being set.
Issued by:
TAURIP19
User response:
None.
Parent topic: SPR - Standard Pool Routine


SPR0016I

SPR00016I [001]
Explanation:
The VGET content is listed.
Issued by:
TAURIP75
User response:
None.
Parent topic: SPR - Standard Pool Routine


SRV - Server Interface

These message are issued for both scheduler and user server.

  • SRV0001I
  • SRV0002I
  • SRV0003E
  • SRV0004W
  • SRV0005I
  • SRV0006I
  • SRV0007I
  • SRV0008I
  • SRV0009I
  • SRV0010I
  • SRV0011E
  • SRV0012I
  • SRV0013I
Parent topic: Messages


SRV0001I

SRV0001I hh:mm:ss.ttt z/Server SRVTASK is initializing
Explanation:
This is an informational message.
Issued by:
TAURIP16
User response:
None.
Parent topic: SRV - Server Interface


SRV0002I

SRV0002I hh:mm:ss.ttt SRVTASK was posted.
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP16
User response:
None.
Parent topic: SRV - Server Interface


SRV0003E

SRV0003E  hh:mm:ss.ttt Subtask [002] TCB [003] consumed more than
                       [004] ms of CPU time. Subtask will be terminated.
Explanation:
The service task can in certain circumstances check the CPU consumption for another subtask. If the value specified by TASK-RUNAWAY is reached or exceeded, the service task will terminate the subtask to prevent CPU loops.
Issued by:
TAURIP16
System administrator response:
Check the REXX or program running in that subtask for loops. If none were found, increase TASK_RUNAWAY if necessary or turn it off altogether.
Parent topic: SRV - Server Interface


SRV0004W

SRV0004W  hh:mm:ss.ttt CPU consumption check is disabled. Possible loops
                       are not detected.
Explanation:
The service task can in certain circumstances check the CPU consumption for another subtask. The configuration parameter TASK-RUNAWAY determines if the check is disabled or running.
Issued by:
TAURIP16
System administrator response:
Specify TASK_RUNAWAY to enable the check. Otherwise this is an informational message.
Parent topic: SRV - Server Interface


SRV0005I

SRV0005I hh:mm:ss.ttt Using service exit [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP16
User response:
None.
Parent topic: SRV - Server Interface


SRV0006I

SRV0006I hh:mm:ss.ttt Calling service exit [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP16
User response:
None.
Parent topic: SRV - Server Interface


SRV0007I

SRV0007I  hh:mm:ss.ttt Checking for outstanding messages and command
                       responses from EMCS console [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP16
User response:
None.
Parent topic: SRV - Server Interface


SRV0008I

SRV0008I hh:mm:ss.ttt Calling initial REXX [002]
Explanation:
This is an informational message.
Issued by:
TAURIP16
User response:
None.
Parent topic: SRV - Server Interface


SRV0009I

SRV0009I hh:mm:ss.ttt Initial REXX [002] ended. RC [003]
Explanation:
This is an informational message.
Issued by:
TAURIP16
User response:
None.
Parent topic: SRV - Server Interface


SRV0010I

SRV0010I hh:mm:ss.ttt -----------------------------------------------------
                      Check for locked ports
                      -----------------------------------------------------
Explanation:
This is an informational message due to IPTRACE level 5 being set. The service task checks for locked ports in the user administration.
Issued by:
TAURIP06
User response:
None.
Parent topic: SRV - Server Interface


SRV0011E

SRV0011E hh:mm:ss.ttt Port [002] for server [003] remains locked
Explanation:
SRVTASK detected a locked port. It has checked the port, which is still in use.. The port remains locked.
Issued by:
TAURIP06
System administrator response:
Check DDNAME SYSTSPRT of scheduler [003] and check who is using the port.Or issue a D,TCPIP,,N,ALLCONN,PORT=[002] command.
Parent topic: SRV - Server Interface


SRV0012I

SRV0012I hh:mm:ss.ttt Port [002] for server [003] unlocked
Explanation:
SRVTASK detected a locked port. It checked the port, and it is no longer in use. The port is unlocked.
Issued by:
TAURIP06
System administrator response:
None.
Parent topic: SRV - Server Interface


SRV0013I

SRV0013I hh:mm:ss.ttt Delay interval is [002] seconds.
Explanation:
This is an informational message due to IPTRACE level 4 being set. The message shows the setting of the configuration variable SERVICE_WAIT.
Issued by:
TAURIP06
User response:
None.
Parent topic: SRV - Server Interface


SSI - Subsystem Interface Routine

These messages are issued by the interface routine to the z/OS subsystem interface (SSI).

  • SSI0001I
  • SSI0002I
  • SSI0003I
  • SSI0004I
  • SSI0005I
  • SSI0006I
  • SSI0007I
  • SSI0008I
  • SSI0009I
Parent topic: Messages


SSI0001I

SSI0001I  hh:mm:ss.ttt SSI call
                       Type      : [002]
                       SVC RC    : [003]
                       SSI RC    : [004]
                       SSI RSN1  : [005]
                       SSI RSNI2 : [006]
Explanation:
This is an informational message.
User response:
None.
Parent topic: SSI - Subsystem Interface Routine


SSI0002I

SSI0002I  hh:mm:ss.ttt Pointer to output (STATJOBF) : [002]
                       Number of matching jobs      : [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP42, TAURIP93
User response:
None.
Parent topic: SSI - Subsystem Interface Routine


SSI0003I

SSI0003I  hh:mm:ss.ttt Pointer to next SJQE   : [002]
                       Pointer to SJQE sysout : [003]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SSI - Subsystem Interface Routine


SSI0004I

SSI0004I  hh:mm:ss.ttt Section length/type/modifier [002]/[003]/[004]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SSI - Subsystem Interface Routine


SSI0005I

SSI0005I  hh:mm:ss.ttt =========================================================
                       Storage for SSOB
                       =========================================================
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SSI - Subsystem Interface Routine


SSI0006I

SSI0006I  hh:mm:ss.ttt =========================================================
                       Storage for SSST
                       =========================================================
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SSI - Subsystem Interface Routine


SSI0007I

SSI0007I  hh:mm:ss.ttt =========================================================
                       JQE terse section
                       =========================================================
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: SSI - Subsystem Interface Routine


SSI0008I

SSI0008I =======================================================================
         Storage for [001]
         =======================================================================
Explanation:
This is an informational message.
Issued by:
TAURIP42, TAURIP93
User response:
None.
Parent topic: SSI - Subsystem Interface Routine


SSI0009I

SSI0009I =======================================================================
         Storage for section    len : [001] type : [002] modifier : [003]
         =======================================================================
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP42, TAURIP93
User response:
None.
Parent topic: SSI - Subsystem Interface Routine


STA - Started Task Interface

  • STA0001E
  • STA0002E
  • STA0003I
  • STA0004E
  • STA0005E
  • STA0006I
  • STA0007E
  • STA0008E
  • STA0009I
  • STA0010E
  • STA0011E
Parent topic: Messages


STA0001E

STA0001E  hh:mm:ss.ttt Invalid value [002] for environment variable TSOE_SCHED_TAB. Valid values are :
                       0 :  Table is in task storage
                       1 :  Table is in shared storage  (common data space)
Explanation:
This message refers to deprecated parameters.
System administrator response:
Contact SupportLine.
Issued by:
TAURIP18
Parent topic: STA - Started Task Interface


STA0002E

STA0002E  hh:mm:ss.ttt Invalid function [002] for scheduler table routine
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: STA - Started Task Interface


STA0003I

STA0003I hh:mm:ss.ttt TSO/E scheduler table routine called with function [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set and refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: STA - Started Task Interface


STA0004E

STA0004E hh:mm:ss.ttt Name of name/token pair is not specified
Explanation:
Self-explanatory.
Issued by:
TAURIP18
System administrator response:
Check the configuration files and specify TSOE_DSP_TOKEN appropriately.
Parent topic: STA - Started Task Interface


STA0005E

STA0005E hh:mm:ss.ttt Read of name/token pair [002] failed with RC [003] (hex).
Explanation:
The search for a token failed; see SA22-7610-xx:MVS Programming: Authorized Assembler Services Reference, Volume 2 (EDT-IXG) for details on the return code (IEANTRT service).
Issued by:
TAURIP18
System administrator response:
Determine why the search failed. If necessary, contact SupportLine.
Parent topic: STA - Started Task Interface


STA0006I

STA0006I  hh:mm:ss.ttt Value of name/token pair [002]
                       DSPALET    :  [003]
                       DSPORIGIN  :  [004]
                       DSPBLOCK   :  [005]
                       DSPFLAGS   :  [006]
Explanation:
This is an informational message.
Issued by:
TAURIP18
User response:
None.
Parent topic: STA - Started Task Interface


STA0007E

STA0007E hh:mm:ss.ttt Name of name/token pair for console is not specified.
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: STA - Started Task Interface


STA0008E

STA0008E hh:mm:ss.ttt Failed to resolve port for JOBID [002].
Explanation:
A user server was started and the required entry was not found in the user administration.
Issued by:
TAURIP83
User response:
Contact SupportLine.
Parent topic: STA - Started Task Interface


STA0009I

STA0009I Port nnnn is in status ssssssss
Explanation:
Information only. Possible states are:
  • Unused
  • Closed
  • Listen
  • SynSent
  • SynRcvd
  • Estab
  • FinWait1
  • FinWait2
  • ClosWait
  • LastAck
  • Closing
  • TimeWait
  • DeletTCB
Issued by:
TAURIP17
System administrator response:
None.
Parent topic: STA - Started Task Interface


STA0010E

STA0010E Port check for [002] returned error status [003] return code [004] reason
code [005]
Explanation:

This is an unrecoverable error message, where [002] is the port number and [003] is the error number. [004] is the return code and [005] is the reason code from EZBNMIFR. See IBM's SC27-3659-xx: IP Programmer's Guide and Reference for more information.

Issued by:
TAURIP17
System administrator response:
Contact SupportLine.
Parent topic: STA - Started Task Interface


STA0011E

STA0011E  Session established. Local address: nnn.nnn.nnn.nnn  Remote address: nnn.nnn.nnn.nnn
Explanation:
This is an unrecoverable error message. The port is in use by hosts at the addresses given.
Issued by:
TAURIP17
System administrator response:
The MVS command D TCPIP,TCPIP,N,CONN,PORT=nnnn will show which job is using the port.
Parent topic: STA - Started Task Interface


TAU - Eclipse Client Interface

  • TAU0001I
  • TAU0002I
  • TAU0003I
  • TAU0004I
  • TAU0005I
  • TAU0006I
  • TAU0007E
  • TAU0008I
  • TAU0009E
  • TAU0010I
  • TAU0011I
  • TAU0012E
  • TAU0013I
  • TAU0014I
  • TAU0015I
  • TAU0016I
  • TAU0017I
  • TAU0018I
  • TAU0019W
  • TAU0020E
  • TAU0021I
  • TAU0022I
  • TAU0023I
  • TAU0024I
  • TAU0025I
  • TAU0026W
  • TAU0027E
  • TAU0028W
  • TAU0029I
  • TAU0030E
  • TAU0031E
  • TAU0032E
  • TAU0033E
  • TAU0035E
  • TAU0036I
  • TAU0037I
  • TAU0038I
  • TAU0039I
  • TAU0040E
  • TAU0042I
  • TAU0043E
  • TAU0044E
  • TAU0045I
  • TAU0046I
  • TAU0047S
  • TAU0048W
  • TAU0049W
  • TAU0050E
  • TAU0051W
  • TAU0052I
  • TAU0053I
  • TAU0054S
  • TAU0055I
  • TAU0056I
  • TAU0057E
  • TAU0058E
  • TAU0059I
  • TAU0060I
  • TAU0061I
  • TAU0063S
  • TAU0064W
  • TAU0065I
  • TAU0066I
  • TAU0067I
  • TAU0068I
  • TAU0069E
  • TAU0070I
  • TAU0071I
  • TAU0072W
  • TAU0073S
  • TAU0074I
  • TAU0075W
  • TAU0076I
  • TAU0077I
  • TAU0078E
  • TAU0079E
  • TAU0080E
  • TAU0081E
  • TAU0082E
  • TAU0083W
  • TAU0084E
  • TAU0085E
  • TAU0086I
  • TAU0087I
  • TAU0088S
  • TAU0089E
  • TAU0090W
  • TAU0091E
  • TAU0092I
  • TAU0093I
  • TAU0099I
  • TAU0100E
  • TAU0101I
  • TAU0102I
  • TAU0103W
  • TAU0104I
  • TAU0105E
  • TAU0106W
  • TAU0107I
  • TAU0108E
  • TAU0109W
  • TAU0111I
  • TAU0112I
  • TAU0113E
  • TAU0114I
  • TAU0115E
  • TAU0116I
  • TAU0117E
  • TAU0118I
  • TAU0119E
  • TAU0120E
  • TAU0121E
  • TAU0122W
  • TAU0123S
  • TAU0124E
  • TAU0125I
  • TAU0126I
  • TAU0127E
  • TAU0128E
  • TAU0129E
  • TAU0130E
  • TAU0131I
  • TAU0132E
  • TAU0133E
  • TAU0134I
  • TAU0135S
  • TAU0136S
  • TAU0137I
  • TAU0138E
  • TAU0139E
  • TAU0140E
  • TAU0141I
  • TAU0142I
  • TAU0143S
  • TAU0144W
  • TAU0145I
  • TAU0146I
  • TAU0147I
  • TAU0148E
  • TAU0149E
  • TAU0150I
  • TAU0151I
  • TAU0152I
  • TAU0153I
  • TAU0154S
  • TAU0155W
  • TAU0156E
  • TAU0157I
  • TAU0158I
  • TAU0159I
  • TAU0160I
  • TAU0161S
  • TAU0162S
  • TAU0163S
  • TAU0164I
  • TAU0165I
  • TAU0166I
  • TAU0167E
  • TAU0168I
  • TAU0169W
  • TAU0171E
  • TAU0172E
  • TAU0173I
  • TAU0174I
  • TAU0176E
  • TAU0177I
  • TAU0178E
  • TAU0179I
  • TAU0182I
  • TAU0183E
  • TAU0187I
  • TAU0192E
  • TAU0195E
Parent topic: Messages


TAU0001I

TAU0001I [001] [002] [003] startup [004]
Explanation:
This is an informational message.
[001]
Product name
[002]
Job name
[003]
Version level
[004]
Date and time
User response:
None.
Issued by:
TAURIP02
Parent topic: TAU - Eclipse Client Interface


TAU0002I

TAU0002I hh:mm:ss.ttt Address of handler communication area : [002]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0003I

TAU0003I hh:mm:ss.ttt Address of server communication area: [002]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0004I

TAU0004I  hh:mm:ss.ttt Socket server is using the following values
                       Maximum number of subtasks : [002]
                       Maximum number of sockets  : [003]
                       Listening on port          : [004]
                       Timeout for IPWAIT         : [005] seconds
                       Name of IP stack           : [006]
                       PPT                        : [007]
                       Dump if API fails          : [008]
                       MULTI_ REXX                : [009]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0005I

TAU0005I  hh:mm:ss.ttt Address of subtask storage table : [002]
                       A(ECB wait list for subtask)     : [003]
                       A(ECB post list for subtask)     : [004]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0006I

TAU0006I hh:mm:ss.ttt Client [002] connected on port [003] desc [004]
Explanation:
This is an informational message. [004] is the IP descriptor.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0007E

TAU0007E  hh:mm:ss.ttt Error during EZASOKET processing
                       Function    : [002]
                       RSN         : [003]
Explanation:
See SC31-8788-xx: IP Sockets Application Programming Interface Guide and Reference for details.
Issued by:
TAURIP00, TAURIP06
System administrator response:
Determine why the EZASOCKET call failed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0008I

TAU0008I hh:mm:ss.ttt Subtask [002] for z/Server is initializing
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0009E

TAU0009E hh:mm:ss.ttt No free ECB available. Waiting for next free ECB.
Explanation:
There is no subtask available for handling the incoming request.
Issued by:
TAURIP00
System administrator response:
If this message is issued frequently, increase NUMTCB in the scheduler configuration file. Otherwise retry later. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0010I

TAU0010I hh:mm:ss.ttt Subtask [002] started A(TCB): [003] A(ECB) : [004]
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0011I

TAU0011I hh:mm:ss.ttt Subtask [002] posted A(TCB): [003] A(ECB) : [004]
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0012E

TAU0012E hh:mm:ss.ttt Timeout for takesocket after [002] seconds
Explanation:
Self-explanatory.
Issued by:
TAURIP00
User response:
This can happen if IP traffic is very high. Retry the request.
Parent topic: TAU - Eclipse Client Interface


TAU0013I

TAU0013I hh:mm:ss.ttt Client IDs are [002] and [003]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0014I

TAU0014I hh:mm:ss.ttt Detaching subtask [002]. TCB [003] with ECB [004]
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0015I

TAU0015I hh:mm:ss.ttt Before call [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP00, TAURIP06, TAURIP63
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0016I

TAU0016I hh:mm:ss.ttt [002] bytes received
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0017I

TAU0017I hh:mm:ss.ttt About to send [002] bytes to client
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0018I

TAU0018I hh:mm:ss.ttt There are [002] bytes available for receive.
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0019W

TAU0019W hh:mm:ss.ttt Environment variable [002] was not specified, using defaults.
Explanation:
Self-explanatory.
Issued by:
TAURIP18
System administrator response:
Verify that the default is sufficient. Otherwise, correct the configuration file.
Parent topic: TAU - Eclipse Client Interface


TAU0020E

TAU0020E  hh:mm:ss.ttt Configuration parameter [002] value >>[002]<< has invalid length or is not numeric.
Explanation:
Self-explanatory.
Issued by:
TAURIP18
System administrator response:
Correct the configuration file for parameter [003].
Parent topic: TAU - Eclipse Client Interface


TAU0021I

TAU0021I hh:mm:ss.ttt Converting message from ASCII to EBCDIC
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0022I

TAU0022I hh:mm:ss.ttt Converting message from EBCDIC to ASCII
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0023I

TAU0023I hh:mm:ss.ttt Subtask for z/Server activated
Explanation:
This is an informational message.
Issued by:
TAURIP01
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0024I

TAU0024I hh:mm:ss.ttt Highest socket number assigned to server is [002]
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0025I

TAU0025I  hh:mm:ss.ttt Subtask input message area at [002]
                       Subtask output message area at [003]
                       Subtask work message area at [004]
                       Each area is [005] bytes long
                       Subtask PIMA area at [006]
                       PIMA area is [007] bytes long
                       Subtask ECI table at [008]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0026W

TAU0026W  hh:mm:ss.ttt Command >>[002]<< invalid.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP73
System administrator response:
Determine why an invalid command was issued. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0027E

TAU0027E  hh:mm:ss.ttt Deletion of module [002] was not successful
                       RSN :   [003]
Explanation:
See SA22-7606-xx: MVS Programming: Assembler Services Reference, Volume 1 (ABEND-HSPSERV) for [003], which is the original DELETE return code.
Issued by:
TAURIP01
System administrator response:
Determine why DELETE failed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0028W

TAU0028W hh:mm:ss.ttt Subtask [002] event has completed with completion code [003]
Explanation:
The task with the name [002] was posted with post code [003], which is either a return code or an ABEND code.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0029I

TAU0029I hh:mm:ss.ttt Load of module [002] was successful  Entry point [003]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP01, TAURIP09
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0030E

TAU0030E  hh:mm:ss.ttt Load of module [002] was not successful
                       System abend :  [003]
                       RSN          :  [004]
Explanation:
See SA22-7626-xx: MVS System Codes for details of the original LOAD failure.
Issued by:
TAURIP01
System administrator response:
Determine why the ABEND occurred. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0031E

TAU0031E hh:mm:ss.ttt Detach for subtask [002] was not successful. RC [003]
Explanation:
See SA22-7606-xx: MVS Programming: Assembler Services Reference, Volume 1 (ABEND-HSPSERV) for [003], which is the original DETACH return code. This is normally the value 4. The DETACH completed successfully, but may be accompanied by a detach ABEND code.
Issued by:
TAURIP00
System administrator response:
If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0032E

TAU0032E hh:mm:ss.ttt IP stack not found. Waiting [002] seconds before retry.
Explanation:
The named IP stack could not be found.
Issued by:
TAURIP00
System administrator response:
Verify the IPNAME parameter in the configuration file. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0033E

TAU0033E hh:mm:ss.ttt Unexpected error in [002]. Server will be terminated
Explanation:
Service [002] failed. If the service was EZASMI: See SC31-8788-xx: IP Sockets Application Programming Interface Guide and Reference for details.
Issued by:
TAURIP00
System administrator response:
If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0035E

TAU0035E hh:mm:ss.ttt No valid method for receive is specified.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP73
User response:
Specify a valid receive method in the IP header.
Parent topic: TAU - Eclipse Client Interface


TAU0036I

TAU0036I hh:mm:ss.ttt Using method 1 for receive for [002] bytes
Explanation:
This message is issued in response to an API call.
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0037I

TAU0037I hh:mm:ss.ttt Using method 2 for receive until encountering [002]
Explanation:
This message is issued in response to an API call.
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0038I

TAU0038I hh:mm:ss.ttt Using method 3 for receive (single receive)
Explanation:
This message is issued in response to an API call.
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0039I

TAU0039I  hh:mm:ss.ttt Socket server information
                       Domain name local host  : [002]
                       IP address current host : [003]
                       VIPA for internal usage : [004]
                       IP address VIPA         : [005]
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0040E

TAU0040E hh:mm:ss.ttt Server startup terminated by [002]
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP00
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0042I

TAU0042I hh:mm:ss.ttt Converting ASCII (UTF-8) header to EBCDIC header
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP73
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0043E

TAU0043E hh:mm:ss.ttt IP ASCII data length or CCSID in ASCII header is not numeric
Explanation:
Self-explanatory.
Issued by:
TAURIP73
User response:
Specify a valid data length in the IP header.
Parent topic: TAU - Eclipse Client Interface


TAU0044E

TAU0044E  hh:mm:ss.ttt Error converting ASCII header to EBCDIC header.
                       See message UNI001E.
Explanation:
This message is issued in response to an API call using ASCII headers. ASCII headers need to be converted to EBCDIC headers. During this process a problem occurred which is described in message UNI001E. UNI001E is found in the T000000x task that handled this API call.
Issued by:
TAURIP73
System administrator response:
Verify that the correct CCSID is used both in the scheduler and user server configuration files and that they match the CCSID specified in the client. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0045I

TAU0045I hh:mm:ss.ttt Using method 4 for receive (via application)
Explanation:
This message is issued in response to an API call.
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0046I

TAU0046I hh:mm:ss.ttt Address of program property table (PPT): [002]
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP02
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0047S

TAU0047S hh:mm:ss.ttt PPT overflow : All [002] entries in use. Request terminated.
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP01
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0048W

TAU0048W hh:mm:ss.ttt Client closed connection before all data was received. Message may be incomplete.
Explanation:
This message is issued in response to an API call.
User response:
Determine why the client closed the connection.
Parent topic: TAU - Eclipse Client Interface


TAU0049W

TAU0049W hh:mm:ss.ttt Timeout occurred before all data was received. Message may be incomplete.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP01
User response:
Determine why a timeout occurred.
Parent topic: TAU - Eclipse Client Interface


TAU0050E

TAU0050E  hh:mm:ss.ttt Input message of length [002] bytes is greater than input buffer of [003] bytes.
                       Increase BUFFERSIZE and restart server.
Explanation:
Self-explanatory.
Issued by:
TAURIP73
System administrator response:
Verify the configuration file; see BUFFERSIZE/BUFFERUNIT in the z/Server Installation Guide.
Parent topic: TAU - Eclipse Client Interface


TAU0051W

TAU0051W hh:mm:ss.ttt Shutdown server
Explanation:
Self-explanatory.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0052I

TAU0052I hh:mm:ss.ttt Setting length in header to [002]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP01
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0053I

TAU0053I hh:mm:ss.ttt Shutdown subtask
Explanation:
This is an informational message.
Issued by:
TAURIP01
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0054S

TAU0054S hh:mm:ss.ttt Terminating subtask with dump
Explanation:
Self-explanatory.
Issued by:
TAURIP06
System administrator response:
Contact SupportLine and provide the dump and all logs.
Parent topic: TAU - Eclipse Client Interface


TAU0055I

TAU0055I hh:mm:ss.ttt Entry point for program [002] disabled.
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP00
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0056I

TAU0056I  hh:mm:ss.ttt ISPF available        : [002]
                       Size of user area1    : [003] bytes
                       Size of user area2    : [004] bytes
                       Address of user area1 : [005]
                       Address of user area2 : [006]
                       Timeout for server    : [007] minutes
                       Reattach after abend  : [008] 0 = No
                       Serialize             : [008]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0057E

TAU0057I  hh:mm:ss.ttt TSO environment successfully created
                      A(Command processor parameter list) : [002]
Explanation:
This is an informational message.
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0058E

TAU0058E  hh:mm:ss.ttt Creation of TSO environment failed
                       RC         : [002]
                       RSN        : [003]
                       Abend code : [004]
Explanation:
Self-explanatory.
System administrator response:
Determine why the creation of the TSO-Environment failed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0059I

TAU0059I hh:mm:ss.ttt [002] ended with RC [003]
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP01
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0060I

TAU0060I  hh:mm:ss.ttt Size of send/receive buffer : [002]/[003]
                       PIMA size                   : [004]
                       CICS EXCI support           : [005]
                       CICS EXCI applid            : [006]
                       Portcheck                   : [007]
                       TSO/E scheduler             : [008]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0061I

TAU0061I  hh:mm:ss.ttt
                       Variable pool size             : [002] bytes
                       A(variable pool)               : [003]
                       Use SVC                        : [004]    SVC [005]
                       Maximum number of user servers : [006]
                       TSO/E user server              : [007]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0063S

TAU0063S hh:mm:ss.ttt Maxerr reached for program [002]. Program is disabled
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP01
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0064W

TAU0064W hh:mm:ss.ttt Write length is zero. No data written.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP01
User response:
Determine if this is intentional behavior. If not, correct the write operation.
Parent topic: TAU - Eclipse Client Interface


TAU0065I

TAU0065I hh:mm:ss.ttt After call [002]. RC : [003] ERRNO : [004]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP00, TAURIP06, TAURIP63
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0066I

TAU0066I hh:mm:ss.ttt Address of IP global data area : [002]
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0067I

TAU0067I hh:mm:ss.ttt startup completed for [002] for [003] and ASID [004]
Explanation:
[002] is the name of the scheduler or user server which has just been started. [003] specifies JES2 or JES3 and [004] is the address space number.
Issued by:
TAURIP00, TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0068I

TAU0068I hh:mm:ss.ttt New date : [002]
Explanation:
This is an informational message.
Issued by:
TAURIP00, TAURIP01
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0069E

TAU0069E hh:mm:ss.ttt Function code [002] is not supported.
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP06
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0070I

TAU0070I hh:mm:ss.ttt Deletion of module [002] completed with RC [003].
Explanation:
This is an informational message.
Issued by:
TAURIP01
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0071I

TAU0071I hh:mm:ss.ttt Kill request for task [002] received.
Explanation:
This message is issued in response to an API call. [002] is the name of the task.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0072W

TAU0072W hh:mm:ss.ttt Connection is closed and no data is available
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP06, TAURIP73
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0073S

TAU0073S hh:mm:ss.ttt Access Denied to $IPSERV [002]
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP01
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0074I

TAU0074I  hh:mm:ss.ttt Security         : [002]
                       Length of Header : [003] bytes
                       Action for no free task  :  [004]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0075W

TAU0075W hh:mm:ss.ttt Access allowed to $IPSERV [002] because security is disabled
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP11
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0076I

TAU0076I hh:mm:ss.ttt Flushing input buffer. [002] bytes available.
Explanation:
This is an informational message.
Issued by:
TAURIP06
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0077I

TAU0077I  hh:mm:ss.ttt SVC for task level security invoked
                       Function : [002]
                       Userid   : [003]
                       SVC  RC  : [004]
                       SAF  RC  : [005]
                       RACF RC  : [006]
                       RACF RSN : [007]
Explanation:
See SA22-7692-xx: Security Server RACROUTE Macro Reference for the function called.
Issued by:
TAURIP59
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0078E

TAU0078E  hh:mm:ss.ttt Creation of task level security was unsuccessful
                       Return code was : [002]
Explanation:
Return code [002] can be:
256
Invalid function code
300
User ID missing
304
Password missing
308
New password missing
400
Not TSO/E Scheduler
Issued by:
TAURIP01
System administrator response:
Determine why task level security could not be established successfully. If necessary contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0079E

TAU0079E  hh:mm:ss.ttt SVC [002] not installed.
                       Startup terminated.
Explanation:
Self-explanatory.
Issued by:
TAURIP02
System administrator response:
Determine why the SVC routine could not be installed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0080E

TAU0080E  hh:mm:ss.ttt Load of module [002] was unsuccessful.
                       System completion code : [003]
                       RSN                    : [004]
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP51
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0081E

TAU0081E hh:mm:ss.ttt Unable to open internal reader. RC : [002]
//READER   DD  SYSOUT=(*,INTRDR)
Explanation:
Self-explanatory.
Issued by:
TAURIP12
System administrator response:
Determine why the internal reader could not be opened. Check for allocation of the DD statement in the scheduler procedure (TAURISPF):
Parent topic: TAU - Eclipse Client Interface


TAU0082E

TAU0082E hh:mm:ss.ttt I/O error on Internal reader. RC : [002]
//READER   DD  SYSOUT=(*,INTRDR)
Explanation:
Self-explanatory.
Issued by:
TAURIP12
System administrator response:
Determine why the I/O error on the internal reader occurred. Check for allocation of the DD statement in the scheduler procedure (TAURISPF):
Parent topic: TAU - Eclipse Client Interface


TAU0083W

TAU0083W  hh:mm:ss.ttt A TSO/E environment already exists.
                       An additional dynamic environment is not created.
Explanation:
During startup, a scheduler or user server tests the availability of a TSO environment. That TSO environment is usually already available due to the way schedulers and user servers are started.
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0084E

TAU0084E hh:mm:ss.ttt No or invalid method for calling exec [002]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP01
User response:
Specify a valid method for calling a REXX exec.
Parent topic: TAU - Eclipse Client Interface


TAU0085E

TAU0085E hh:mm:ss.ttt ISPF environment is not available. Unable to call exec [002]
Explanation:
This message is issued in response to an API call which specified invocation of a REXX exec. The REXX exec needs an ISPF environment which is not available.
Issued by:
TAURIP01
System administrator response:
Determine either why no ISPF environment is available or correct the API call. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0086I

TAU0086I hh:mm:ss.ttt Timeout reached
Explanation:
The user server has been inactive for the amount of time specified by the TIMEOUT value in the user server configuration and will now terminate.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0087I

TAU0087I  hh:mm:ss.ttt
                       Timeout for read          : [002] microseconds
                       Clear buffer              : [003]
                       Private exception handler : [004]
                       Name of exception handler : [005]
                       Service wait time         : [006] ms
                       Task loop time            : [007] ms
                       Console wait time         : [008] ms
                       Console buffer size       : [009] KB
Explanation:
This is an informational message listing certain configuration settings.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0088S

TAU0088S hh:mm:ss.ttt All subtasks failed. Server terminated abnormally
Explanation:
This message is issued when a scheduler is started with REATTACH=0 and all subtasks have failed. The scheduler terminates.
Issued by:
TAURIP00
System administrator response:
Change the configuration file to either specify REATTACH=1 or increase the number of subtasks (NUMTCB). Determine why all the subtasks had failed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0089E

TAU0089E hh:mm:ss.ttt XML parse is only valid with method 3 for receive
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP73
User response:
Change the receive method in the programmed IP header to 3.
Parent topic: TAU - Eclipse Client Interface


TAU0090W

TAU0090W hh:mm:ss.ttt PIMA size must be at least [002]. Size changed.
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0091E

TAU0091E hh:mm:ss.ttt XML support is not activated. Specify PIMASIZE for activation.
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP73
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0092I

TAU0092I hh:mm:ss.ttt Invoking initialization exit [002]
Explanation:
This is an informational message in response to an API call.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0093I

TAU0093I hh:mm:ss.ttt Invoking termination exit [002]
Explanation:
This is an informational message in response to an API call.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0099I

TAU0099I ===============================================================
          [[001]]
===============================================================
Explanation:
This is a heading line for several informations.
Issued by:
TAURIP00, TAURIP06, TAURIP63, TAURIP73, TAURIP78 (trace level 0); TAURIP01, TAURIP06 (trace level 3); TAURIP21 (trace level 4); TAURIP63 (trace level 5);
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0100E

TAU0100E  hh:mm:ss.ttt A CICS applid must be specified if ECI support is
activated.
         ECI support disabled
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0101I

TAU0101I  hh:mm:ss.ttt Entry to enqueue/dequeue routine
                       Function     : [002] E=Enqueue      D=Dequeue
                                        X=Remote Enq Y=Remote Deq
                       Type         : [003] E=Exclusive S=Shared N=None
                       Scope        : [004] 1=Step 2=System 3=Systems
                       Major name   : [005]
                       Minor name   : [006]
                       Retry count  : [007]
                       Wait time    : [008] ms
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP38
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0102I

TAU0102I hh:mm:ss.ttt Exit from enqueue/dequeue routine. RC [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP38
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0103W

TAU0103W  hh:mm:ss.ttt Resource not available. RC [002] from ENQ
                       Waiting for [003] ms.
                       Major name : [004]
                       Minor name : [005]
Explanation:
Self-explanatory.
Issued by:
TAURIP38
User response:
None, z/Server automatically retries the request.
Parent topic: TAU - Eclipse Client Interface


TAU0104I

TAU0104I  hh:mm:ss.ttt Retry limit [002] reached.
                       Resource is marked disabled and will not be used.
Explanation:
This is an informational message in response to an API call. The retry limit is set by the client code.
Issued by:
TAURIP38
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0105E

TAU0105E  hh:mm:ss.ttt Enqueue of internal reader failed.
Explanation:
z/Server serializes the internal reader using the ENQ ZSERVER/INTRDR. When that ENQ cannot be obtained, some problem in the past prevented the ENQ from being released.
System administrator response:
Determine why the internal reader could not be enqueued. If necessary, contact SupportLine. Restart the scheduler or user server.
Parent topic: TAU - Eclipse Client Interface


TAU0106W

TAU0106W  hh:mm:ss.ttt Negative length for receive specified [002] bytes
Multiple reads are forced until specified length is reached.
Explanation:
This message is issued in response to an API call.
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0107I

TAU0107I hh:mm:ss.ttt Registration of exception handler >>[002]<< successful.
Explanation:
This is an informational message. [002] is the module acting as an exception handler.
Issued by:
TAURIP01, TAURIP04, TAURIP16
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0108E

TAU0108E  hh:mm:ss.ttt Registration of exception handler >>[002]<< failed with token [003].
         Continue without exception handler.
Explanation:
This message is issued in response to an API call. [003] is an ECB address.
Issued by:
TAURIP01
System administrator response:
Determine why [002] could not be established as an exception handler. If necessary contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0109W

TAU0109W  hh:mm:ss.ttt Invalid value specified for TIMEOUT_ACTION. Use only
                       N = Normal or  S = Shutdown
                       Value changed to N
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0111I

TAU0111I hh:mm:ss.ttt Reattach request for task [002] received.
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0112I

TAU0112I hh:mm:ss.ttt Activating EMCS console with name [002]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0113E

TAU0113E  hh:mm:ss.ttt Activation of EMCS console failed with RC [002]
                       CA_CONSRC : [003]    (hex)
                       CA_CONSRE : [004]    (hex)
                       Console deactivated
Explanation:
See SA22-7611-xx: MVS Programming: Authorized Assembler Services Reference, Volume 3 (LLA-SDU), macro MCSOPER for details.
Issued by:
TAURIP02
System administrator response:
Determine why the EMCS console could not be activated. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0114I

TAU0114I hh:mm:ss.ttt Deactivating EMCS console with name [002]
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0115E

TAU0115E  hh:mm:ss.ttt Deactivation of EMCS console failed with RC [002]
                       CA_CONSRC : [003]    (hex)
                       CA_CONSRE : [004]    (hex)
Explanation:
See SA22-7611-xx: MVS Programming: Authorized Assembler Services Reference, Volume 3 (LLA-SDU). IPSCA_CONSRC and IPSCA_CONSRE are the original MCSOPER return and reason codes.
Issued by:
TAURIP00
System administrator response:
Determine why the EMCS console deactivation failed. If necessary contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0116I

TAU0116I  hh:mm:ss.ttt Activating of EMCS console [002] successful.
                       Console ID   :  [003]
                       Console Alet :  [004]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0117E

TAU0117E  hh:mm:ss.ttt Getting next message from EMCS console ended with
                       CA_CONSRC : [002]    (hex)
                       CA_CONSRE : [003]    (hex)
Explanation:
See SA22-7611-xx: MVS Programming: Authorized Assembler Services Reference, Volume 3 (LLA-SDU). IPSCA_CONSRC and IPSCA_CONSRE are the original MCSOPMSG return and reason codes.
System administrator response:
Determine why MCSOPMSG failed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0118I

TAU0118I hh:mm:ss.ttt Address of EMCS buffer : [002]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0119E

TAU0119E hh:mm:ss.ttt No console defined. Commands CCALL and XCALL are not supported.
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP01
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0120E

TAU0120E  hh:mm:ss.ttt Console command failed with RC [002] Hex.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP01
System administrator response:
Determine why the console command failed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0121E

TAU0121E  hh:mm:ss.ttt Required configuration parameter [002] was not specified
                       Server startup is terminated
Explanation:
Self-explanatory.
Issued by:
TAURIP18
System administrator response:
Define the required parameters in the configuration file for the scheduler or user server. Refer to the z/Server Installation Guide and Reference.
Parent topic: TAU - Eclipse Client Interface


TAU0122W

TAU0122W  hh:mm:ss.ttt No user SVC is used for authorized functions.
                       Server must run in an authorized environment.
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP02
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0123S

TAU0123S hh:mm:ss.ttt Jobstep is not APF authorized. Startup terminated
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP02
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0124E

TAU0124E hh:mm:ss.ttt No response from server.
Explanation:
This message is issued in response to an API call requesting execution of a command or REXX exec. When the executing program/command does not provide a response by design, this is not an error.
Issued by:
TAURIP01
System administrator response:
Determine why the scheduler or user server did not respond, if a response was expected. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0125I

TAU0125I hh:mm:ss.ttt Additional BELOWHEAP of [002] bytes created. Heapid is [003].
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0126I

TAU0126I hh:mm:ss.ttt BELOWHEAP for subtask allocated at [002]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0127E

TAU0127E hh:mm:ss.ttt No program for HTTP request defined. HTTP request ignored.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP73
User response:
Define a program to accept HTTP requests.
Parent topic: TAU - Eclipse Client Interface


TAU0128E

TAU0128E  hh:mm:ss.ttt Value [002] for compression is invalid. The valid values  are:
                      0 ==> no compression
                      1 ==> compress send buffer before send
                      2 ==> expand receive buffer after receive
                      3 ==> both
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP18
User response:
Specify a valid compression value.
Parent topic: TAU - Eclipse Client Interface


TAU0129E

TAU0129E  hh:mm:ss.ttt Invalid value for COMPAT : [002] Value must be 1 or 2
                       1 ==> use  48 Byte header (compatibility to version 1)
                       2 ==> use 100 Byte header (default                   )
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0130E

TAU0130E hh:mm:ss.ttt DDName [002] not found. Startup terminated.
Explanation:
Self-explanatory.
Issued by:
TAURIP02
System administrator response:
Verify that DDNAME [002] is available in the startup procedure. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0131I

TAU0131I  hh:mm:ss.ttt XMLCA for subtask allocated at [002]
                       TS    for subtask allocated at [003]
Explanation:
This is an informational message. XMLCA is the CML communication area, TS is temporary storage (a working area).
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0132E

TAU0132E hh:mm:ss.ttt Invalid version [002] in ASCII header found. This server is running with version [003]
Explanation:
Self-explanatory.
Issued by:
TAURIP73
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0133E

TAU0133E hh:mm:ss.ttt VIPA [002] could not be resolved
Explanation:
Self-explanatory.
Issued by:
TAURIP02
System administrator response:
Determine why the configured VIPA could not be resolved. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0134I

TAU0134I hh:mm:ss.ttt Server is [002]
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP02
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0135S

TAU0135S hh:mm:ss.ttt Permission denied. [002] not authorized to use port [003].
Explanation:
Self-explanatory.
Issued by:
TAURIP00
System administrator response:
Determine why port [003] could not be used. Check the hardcopy log for the NETSTAT responses to the commands issued by z/Server. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0136S

IPS0136S  hh:mm:ss.ttt The address is in a timed wait because a LINGER  delay
                   from a previous close or another process is using the port.
                   This error can also occur if the port specified in the
                   bind call has been configured as RESERVED on a port
                   reservation statement in the TCP/IP profile
Explanation:
The port ("address") could not be bound because TCPIP did not allow it. This may be due to a LINGER delay from a previous close of a connection. Or another process might be using the port.
Issued by:
TAURIP00
System administrator response:
Determine why the port ("address") is not available. Check the hardcopy log for the NETSTAT responses to the commands issued by z/Server. Check that the port is not reserved to another address space permanently. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0137I

TAU0137I  hh:mm:ss.ttt Create slaves       : [002]
                       Config for slaves   : [003]
                       Proc   for slaves   : [004]
Explanation:
This message refers to deprecated functionality.
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0138E

TAU0138E  hh:mm:ss.ttt Invalid value [002] for MULTI_REXX
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP18
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0139E

TAU0139E hh:mm:ss.ttt SVC with function code [002] failed with RC [003]
Explanation:
Function [002] (low-order byte 000000xx):
X'01'
RACROUTE
X'02'
SSICALL
X'03'
CMD for ECMD
X'04'
Internal start
X'06'
Activate EMCS Console
X'07'
Deactivate EMCS Console
X'08'
Command without CART
X'10'
Command with CART
X'18'
Send command to console
X'20'
Get next message
X'40'
Get next command response
X'80'
Get response with CART (command and response token)
X'E0'
Get response from EMCS

Function [002] (byte 0000xx00):

x'08'
Terminate the address space - a return code of 8 is expected.

Return code [003]:

0-250
RACF return code.
252
Callers’ address space is not authorized to call this SVC.
253
No task level security environment to delete.
254
R1 does not point to a valid TAURACFA control block on entry to SVC routine.
255
Address Space has no ACEE.
256
Invalid function code.
257
Console buffer is too small.
System administrator response:
Determine why the SVC failed. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0140E

TAU0140E hh:mm:ss.ttt Message has invalid length. A minimum length of [002] bytes is required for version [003].
Explanation:
Self-explanatory.
Issued by:
TAURIP73
User response:
User a valid length.
Parent topic: TAU - Eclipse Client Interface


TAU0141I

TAU0141I  hh:mm:ss.ttt z/Server MAINTASK ready for clients
Explanation:
This is an informational message.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0142I

TAU0142I hh:mm:ss.ttt z/Server SUBTASK ready for clients
Explanation:
This is an informational message.
Issued by:
TAURIP01
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0143S

TAU0143S  hh:mm:ss.ttt An OMVS process initialization failure has occurred.
                       A valid OMVS RACF segment may be missing or contain invalid specifications.
Explanation:
Self-explanatory.
Issued by:
TAURIP00
System administrator response:
Check the RACF OMVS segment of the user associated with the application. Check if the RACF OMVS segment is defined. Check if the UID is defined, and check if a proper HOME directory is defined. If necessary, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0144W

IPS0144W  hh:mm:ss.ttt Configuration parameter [002] is no longer supported.
Explanation:
Self-explanatory.
Issued by:
TAURIP18
System administrator response:
Remove parameter [002] from the configuration file.
Parent topic: TAU - Eclipse Client Interface


TAU0145I

TAU0145I  hh:mm:ss.ttt BASE64 utility called with function [002]
Explanation:
This is an informational message due to IPTRACE level 6 being set.
Issued by:
TAURIP47
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0146I

TAU0146I ------------------------------------------------------------------
         BASE64 Input address : [001] Length : [002]
         ------------------------------------------------------------------
Explanation:
This is an informational message.
Issued by:
TAURIP47
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0147I

TAU0147I ------------------------------------------------------------------
         BASE64 Output address : [001] Length : [002]
         ------------------------------------------------------------------
Explanation:
This is an informational message.
Issued by:
TAURIP47
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0148E

IPS0148E  hh:mm:ss.ttt Storage needed for [002] subtasks with a buffer size of [003] is greater than 2GB.
Explanation:
The combination of buffer size and number of subtasks (BUFFERSIZE/BUFFERUNIT and NUMTCB) specified in the scheduler configuration file results in the need for an address space that would be larger than 2GB.
Issued by:
TAURGDA
System administrator response:
Reduce one or more of the three parameters to fit within the limits of a conventional z/OS address space.
Parent topic: TAU - Eclipse Client Interface


TAU0149E

TAU0149E  hh:mm:ss.ttt Storage needed for [002] subtasks with a buffer size of [003] is greater than private region with [004] bytes.
Explanation:
The combination of buffer size and number of subtasks (BUFFERSIZE/BUFFERUNIT and NUMTCB) specified in the scheduler configuration file results in the need for an address space that would be larger than 2GB.
Issued by:
TAURGDA
System administrator response:
Reduce one or more of the three parameters to fit within the limits of a conventional z/OS address space.
Parent topic: TAU - Eclipse Client Interface


TAU0150I

TAU0150I  hh:mm:ss.ttt About [002] bytes of private region used.
                       Maximum would be [003] bytes
Explanation:
This is an informational message.
Issued by:
TAURGDA
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0151I

TAU0151I  hh:mm:ss.ttt New userid of ACEE for TCB [002] is [003]
Explanation:
This is an informational message due to IPTRACE level 5 being set. If it is issued for a scheduler, then the working task T000000x had the identity switch; if it is issued for a user server, then the identity switch occurred between the first and second step.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0152I

TAU0152I  hh:mm:ss.ttt Flags for send : [002]
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP02
System administrator response:
Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0153I

TAU0153I  hh:mm:ss.ttt Address of z/Server statistic area is [002]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0154S

TAU0154S  hh:mm:ss.ttt Current z/OS Release [002] is not supported.
Explanation:
This z/OS release is not supported. Functionality needed to run z/Server is missing. z/Server terminates.
Issued by:
TAURLOGN
System administrator response:
Migrate to a supported operating system (z/OS 1.10 or higher).
Parent topic: TAU - Eclipse Client Interface


TAU0155W

TAU0155W  hh:mm:ss.ttt Current z/OS Release [002] is not supported but may work.
Explanation:
This z/OS release is not supported.
System administrator response:
Run z/Server unsupported and at your own risk. Migrate to a supported operating system (z/OS 1.10 or higher).
Parent topic: TAU - Eclipse Client Interface


TAU0156E

TAU0156E  hh:mm:ss.ttt Command task is busy. ENQ/DEQ not done.
Explanation:
The command task is busy servicing other requests. The API-requested ENQ or DEQ was not executed.
Issued by:
TAURIP02
User response:
Retry the ENQ or DEQ request to ensure data integrity.
Parent topic: TAU - Eclipse Client Interface


TAU0157I

TAU0157I  hh:mm:ss.ttt Post command task for remote ENQ/DEQ
Explanation:
This is an informational message due to IPTRACE level 5 being set. A remote ENQ/DEQ is issued by the CMDTASK on behalf of one of the working tasks T000000x.
Issued by:
TAURIP39
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0158I

TAU0158I  hh:mm:ss.ttt Wait for completion of initialization of service  task
Explanation:
This is an informational message due to IPTRACE level 5 being set. The LISTENER task is waiting for the initialization of the service task (SRVTASK). The maximum time to wait is defined using the configuration variable ECB_TIMEOUT. If SRVTASK could not be initialized until ECB_TIMEOUT has elapsed, message TAU0176E is issued. Startup is terminated.
Issued by:
TAURIPLI
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0159I

TAU0159I  hh:mm:ss.ttt Wait for completion of initialization of message task
Explanation:

The LISTENER task is waiting for the initialization of the message task (MSGTASK). The maximum time to wait is defined using the configuration variable ECB_TIMEOUT. If MSGTASK could not be initialized until ECB_TIMEOUT has elapsed, message TAU0176E is issued. Startup is terminated.

Issued by:
TAURIPLI
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0160I

TAU0160I  hh:mm:ss.ttt Listener posted
Explanation:
This is an informational message. LISTENER task was posted by either CMDTASK, SRVTASK or MSGTASK.
Issued by:
TAURIPLI
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0161S

TAU0161S  hh:mm:ss.ttt Failed to read named/token pair in task exit routine
Explanation:
The task exit routine was unable to read the name/token pair ZCOMMCA. The task exit routine is invoked if a z/Server subtask ended abnormally.
Issued by:
TAURETXR
System administrator response:
Set trace level to 5 and reproduce the problem. Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0162S

TAU0161S  hh:mm:ss.ttt Subtask [002] attached more than [003] times.
                       Due to possible loop, server is terminating.
                       Please check reason for frequent reattach
Explanation:
If a subtask terminates abnormally, z/Server reattaches the subtask. If the subtask is attached more than 21 times, z/Server assumes a loop and terminates. There is a CEEDUMP written for every abnormal end of a subtask. The name of the subtask affected is provided in [002].
Issued by:
TAURIPLI
System administrator response:
Try to find the reason for abnormal termination. Contact SupportLine and provide all joblogs and dumps.
Parent topic: TAU - Eclipse Client Interface


TAU0163S

TAU0163S  hh:mm:ss.ttt Insufficient storage for [002] TCB. Startup terminated.
Explanation:
This message is issued if a CEEGTST request during initialization was not successful. Startup of the scheduler is terminated with RC=88.
Issued by:
TAURIP02
System administrator response:
Increase the REGION size of the STC or do one of the following actions until the message disappears.
  • Reduce the value of NUMTCB (# of worker tasks)
  • Reduce the value of BUFFERSIZE
Parent topic: TAU - Eclipse Client Interface


TAU0164I

TAU0164I  hh:mm:ss.ttt Before calling SR_EXIT [002] as header exit.
Explanation:
This is an informational message due to IPTRACE level 5 being set. If a send/receive exit is defined in the configuration file (SR_EXIT=), this message indicates the invocation of the exit with [002] as a header exit.
Issued by:
TAURIP73
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0165I

TAU0165I  hh:mm:ss.ttt After call SR_EXIT [002] RC was [003].
Explanation:
This is an informational message due to IPTRACE level 5 being set. If a send/receive exit is defined in the configuration file (SR_EXIT=) this message indicates the termination of the exit.
Issued by:
TAURIP73
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0166I

TAU0166I  hh:mm:ss.ttt Generating passticket for userid [002] and application [003].
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP59
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0167E

TAU0167E  hh:mm:ss.ttt Generating passticket failed with RC [002] hex.
Explanation:
Call to RCVTPTGN failed. Possible return codes are:
X’08’
No PTKTDATA profile found for the application
X’0C’
No task or address space ACEE found, and the ACEE pointer was not specified on the input parameter list
X’10’
Caller is not authorized
X’14’
The RACF PTKTDATA class is not active
Issued by:
TAURIP59
System administrator response:
Check RC and correct the problem.
Parent topic: TAU - Eclipse Client Interface


TAU0168I

TAU0168I  hh:mm:ss.ttt Passticket [002] successfully generated.
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP59
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0169W

TAU0169W  hh:mm:ss.ttt Port [002] is in status TIMEWT. Waiting [003] ms before retry.
Explanation:
This message is issued if the configuration variable PORTCHECK is set to one. During port check the scheduler determined that port [002] is in a TIMEWAIT state. This may happen if the address space is restarted immediately after a shutdown. The scheduler address space will wait one second and check the port again. If the port is still in a TIMEWAIT state after 10 attempts, startup is terminated with message TAU0136S.
Issued by:
TAURIP17
System administrator response:
Issue the operator command D TCPIP,<tcpname>,N,ALLCONN,PORT=<port> and determine why the port is in use. Wait until the port is available to be bound again. If the scheduler address space terminated, restart the scheduler. If a user server could not be started, retry the failing operation.
Parent topic: TAU - Eclipse Client Interface


TAU0171E

TAU0171E  hh:mm:ss.ttt All subtasks busy. Request not processed.
Explanation:
The LISTENER task received a message from the client but all worker tasks are busy and the server was configured with NOFTASK=M.
Issued by:
TAURIPLI
System administrator response:
If this message occurs in a scheduler, increase the number of worker tasks (configuration variable NUMTCB). If this message occurs in a user server with an ISPF environment, check why the worker task is busy. This message may appear to indicate a possible loop.
Parent topic: TAU - Eclipse Client Interface


TAU0172E

TAU0172E  hh:mm:ss.ttt User SVC could not be resolved through data space.
                       Startup terminated.
Explanation:
The user administration was called with the function "read header". The call ended with a return code greater than zero.
Issued by:
TAURIP18
System administrator response:
Make sure the holder task is started. Restart the scheduler with trace level of 5. If the problem persists, contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0173I

TAU0173I  hh:mm:ss.ttt Waiting [002] hundredth of one second.
Explanation:
This is an informational message due to IPTRACE level 6 being set. This message is written if z/Server goes into a delay for varying reasons.
Issued by:
TAURIP62
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0174I

TAU0174I  hh:mm:ss.ttt Using EXIT at [002] and ECB at [003] after wait.
Explanation:
This is an informational message due to IPTRACE level 6 being set. This message is written if z/Server is waiting for an ECB. In addition, a timer exit was established that will post another ECB if a timeout occurs.
Issued by:
TAURIP62
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0176E

TAU0176E  hh:mm:ss.ttt [002] did not signal READY within [003] ms
                       Startup terminated.
Explanation:
z/Server was waiting [003] ms for initialization of task [002] (for instance CMDTASK) but the subtask did not signal READY. Because z/Server is not operational in this case, the startup is terminated.
Issued by:
TAURIPLI
System administrator response:
The timeout may be increased with the configuration variable ECB_TIMEOUT. In most cases, this is a performance problem. If the problem cannot be solved, start the server with trace level 5. Contact SupportLine.
Parent topic: TAU - Eclipse Client Interface


TAU0177I

TAU0177I  hh:mm:ss.ttt Cancel timer request with ID [002].
Explanation:
This is an informational message due to IPTRACE level 6 being set. This message is written if z/Server is waiting for an ECB. In addition, a timer exit was established that will post another ECB if a timeout occurs. If the first ECB is posted before the second, the timer request for the second ECB is cancelled.
Issued by:
TAURIP62
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0178E

TAU0178E  hh:mm:ss.ttt Call to STIMER was unsuccessful RC [002] (hex).
Explanation:
Seting a timer interval was unsuccessful.
Issued by:
TAURIP62
System administrator response:
Contact SupportLine and provide all output.
Parent topic: TAU - Eclipse Client Interface


TAU0179I

TAU0179I  hh:mm:ss.ttt Timer established with ID [002].
Explanation:
This is an informational message due to IPTRACE level 6 being set.
Issued by:
TAURIP62
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0182I

TAU0182I [001] termination completed for  [002]
Explanation:
This informational message is issued if a worker task has terminated.
Issued by:
TAURIP00
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0183E

TAU0183E hh:mm:ss.ttt RACROUTE class check for  [002] failed. Startup  terminated.
Explanation:
This message is issued if the RACF class JESSPOOL or $IPSERV was not found during initialization of a scheduler.
Issued by:
TAURIP02
User response:
This message does not necessarily indicate an error. None.
Parent topic: TAU - Eclipse Client Interface


TAU0187I

TAU0187I hh:mm:ss.ttt Subtask [002] for z/Server is terminating.  RC [003] in hex
Explanation:
This message is issued during shutdown and indicates the termination of the subtask defined in slot 002.
Issued by:
TAURIP01 and TAURIPLI
User response:
None.
Parent topic: TAU - Eclipse Client Interface


TAU0192E

TAU0192E  hh:mm:ss.ttt TCP/IP image [002] not usable.
                       Reason : [003] (hex).
Explanation:
The name of the IP stack (IPNAME) specified in the configuration file is not usable. Reason [003] is the reason code:
08
Image not found
40
Image is terminating
20
Image is down
10
Image is stopped or is stopping
Issued by:
TAURIPLI
System administrator response:
Check name of image or reason code.
Parent topic: TAU - Eclipse Client Interface


TAU0195E

TAU0195E  hh:mm:ss.ttt Infrastructure is gone. Holder not available.
                       Server will be terminated
Explanation:
This message indicates that the holder task is no longer available. None of the schedulers and user servers using this holder address space can work any longer because the infrastructure needed is gone. All schedulers and user servers are terminated. Existence of the holder and its infrastructure is verified with each Ip message received from a client or when the SRVTASK wakes up.

Issued by:
TAURIPLI/TAURIP16
System administrator response:
Check why the holder task was lost. If needed, contact SupportLine and provide all joblog from all z/Server address spaces.
Parent topic: TAU - Eclipse Client Interface


UNI - Unicode code conversion services

z/Server uses the Unicode conversion services to perform code page conversions. For details, see SA22-7649-xx: Unicode Services User's Guide and Reference.

  • UNI0001I
  • UNI0002I
  • UNI0003I
  • UNI0004W
  • UNI0005E
  • UNI0006W
  • UNI0007E
  • UNI0008W
  • UNI0009W
  • UNI0010W
  • UNI0011W
  • UNI0012E
  • UNI0013I
Parent topic: Messages


UNI0001I

UNI0001I  hh:mm:ss.ttt Unicode character conversion from CCSID [002] to CCSID [003]
                       A(Input)     : [004]    A(Output) : [005]
                       Input length : [006]
Explanation:
This is an informational message due to IPTRACE level 4 being set. [002] is the source code page, [003] is the target code page.
Issued by:
TAURIP60
User response:
None.
Parent topic: UNI - Unicode code conversion services


UNI0002I

UNI0002I  hh:mm:ss.ttt Unicode character conversion ended with RC [002] and RSN [003].
Explanation:
This is an informational message due to IPTRACE level 4 being set. See SA22-7649-xx: Unicode Services User's Guide and Reference for the return and reason code.
Issued by:
TAURIP60
User response:
None.
Parent topic: UNI - Unicode code conversion services


UNI0003I

UNI0003I ------------------------------------------------------------------
         Result after conversion   Old length : [001] New length : [002]
         ------------------------------------------------------------------
Explanation:
This is an informational message.
Issued by:
TAURIP60
User response:
None.
Parent topic: UNI - Unicode code conversion services


UNI0004W

UNI0004W hh:mm:ss.ttt Unicode character conversion not processed because CCSID of source is equal to CCSID of target.
Explanation:
This is an informational message due to IPTRACE level 1 being set.
Issued by:
TAURIP01, TAURIP35
User response:
None.
Parent topic: UNI - Unicode code conversion services


UNI0005E

UNI0005E  hh:mm:ss.ttt Dynamic CCSID for z/Server in ASCII header is not numeric.
                       Value is [002]
Explanation:
Self-explanatory.
Issued by:
TAURIP73
System administrator response:
Contact SupportLine.
Parent topic: UNI - Unicode code conversion services


UNI0006W

UNI0006W  hh:mm:ss.ttt Change CCSID for z/Server requested
                       Current   z/Server CCSID : [002]
                       Requested z/Server CCSID : [003]
                       Requested client   CCSID : [004]
                       Flags                    : [005]
                      .... ...1 Message has ASCII-Header
                      .... ..1. Copepage translation for send requested
                      .... .1.. Copepage translation for receive requested
                      ...1 .... Change Codepage for z/Server requested
Explanation:
This is an informational message due to IPTRACE level 1 being set. It indicates that the current code page of the z/Server is changed from value [002] to value [003].
Issued by:
TAURIP73
User response:
To avoid unnecessary code page conversions, ensure that the client and z/Server code pages match. The z/Server code page is set in each configuration file using the parameter CCSID.
Parent topic: UNI - Unicode code conversion services


UNI0007E

UNI0007E  hh:mm:ss.ttt Codepage translation from CCSID [002] to CCSID [003] failed with RC [004] and reason [005]
Explanation:
See SA22-7649-xx: Unicode Services User's Guide and Reference for the return and reason code.
Issued by:
TAURIP35, TAURIP73
System administrator response:
Determine why the code page translation failed. If necessary, contact SupportLine.
Parent topic: UNI - Unicode code conversion services


UNI0008W

UNI0008W  hh:mm:ss.ttt Change to an unsupported CCSID for z/Server requested and accepted. Using UTF-8 for parser
                       Current   z/Server CCSID : [002]
                       Requested z/Server CCSID : [003]
                       Requested client   CCSID : [004]
                       Flags                    : [005]
                     .... ...1 Message has ASCII-Header
                      .... ..1. Copepage translation for send requested
                      .... .1.. Copepage translation for receive requested
                      .... 1... No substitution chars are used. Service fails
                      ...1 .... Change Codepage for z/Server requested
                      ..1. .... Codepage for z/Server unsupported
                      .1.. .... Codepage for z/Server ASCII for num. value 0-9
                      1... .... Codepage for z/Server ASCII is DBCSExplanation: This is an informational message due to IPTRACE level 1 being set. Despite being unsupported, the requested code page was set.
Explanation:
This is an informational message due to IPTRACE level 1 being set. Despite being unsupported, the requested code page was set.
Issued by:
TAURIP73
User response:
To avoid unnecessary code page conversions, ensure that the client and z/Server code pages match. The z/Server code page is set in each configuration file using the parameter CCSID.
Parent topic: UNI - Unicode code conversion services


UNI0009W

UNI0009W  hh:mm:ss.ttt Unicode character conversion not processed because an unsupported CCSID for the z/Server was specified.
Explanation:
Self-explanatory.
System administrator response:
Verify that the configuration files (scheduler and user server) specify a valid code page - parameter CCSID.
Parent topic: UNI - Unicode code conversion services


UNI0010W

UNI0010W  hh:mm:ss.ttt Unicode character conversion not processed due to a client request.
Explanation:
Self-explanatory.
User response:
None.
Parent topic: UNI - Unicode code conversion services


UNI0011W

UNI0011W  hh:mm:ss.ttt Unicode character conversion not processed because length of XML document is zero.
Explanation:
Self-explanatory.
User response:
Specify a valid XML document.
Parent topic: UNI - Unicode code conversion services


UNI0012E

UNI0012E  hh:mm:ss.ttt Variable substitution for input message is only allowed if a valid z/Server codepage is specified.
Explanation:
Self-explanatory.
Issued by:
TAURIP73
User response:
Specify a valid code page.
Parent topic: UNI - Unicode code conversion services


UNI0013I

UNI0013I ------------------------------------------------------------------
         Data before conversion
         ------------------------------------------------------------------
Explanation:
This is an informational message.
Issued by:
TAURIP60
User response:
None.
Parent topic: UNI - Unicode code conversion services


XML - XML System Parser Interface

z/Server uses the XML system parser functionality (that can run on specialty engines) for parsing XML formatted documents. Any return and reason codes displayed were originally issued by the XML system parser. For details, see SA23-1350-xx: z/OS XML System Services User's Guide and Reference.

XML is also used for communication inside z/Server. This means that XML errors may be produced in unexpected situations. The logon parameters (user ID and password) are passed as an XML document to the validation routine, and a user ID that is too long (more than eight characters) results in an XML0003E error message.

  • XML0001E
  • XML0002I
  • XML0003E
  • XML0004E
  • XML0005E
  • XML0006I
  • XML0007E
  • XML0008E
  • XML0009I
  • XML0010I
  • XML0011I
  • XML0012I
  • XML0013E
  • XML0014E
  • XML0015E
  • XML0016E
  • XML0017I
  • XML0018I
  • XML0019E
  • XML0020E
  • XML0022E
  • XML0023E
  • XML0024E
  • XML0025E
  • XML0026E
  • XML0028W
Parent topic: Messages


XML0001E

XML0001E hh:mm:ss.ttt  XML Call to [002] ended. RC : [003] and reason [004]
Explanation:
An XML system parser interface function call failed.
[002]
XML System Parser Interface function name
[003]
Return code
[004]
Reason code

Some common reason codes and their possible cause:

1300
Buffer too small
3030
Incorrect data set characteristics (not RECFM=F[B], LRECL=80)
3063
The processed document is not XML
Issued by:
TAURIP63
System administrator response:
Determine why the interface call failed. If necessary, contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0002I

XML0002I hh:mm:ss.ttt Unknown XML record type : [002]
Explanation:
This is an informational message due to IPTRACE level 4 being set.
Issued by:
TAURIP75
User response:
None.
Parent topic: XML - XML System Parser Interface


XML0003E

XML0003E  hh:mm:ss.ttt Attribute value [002] with length [003]
                       is too long for attribute [004]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP75
User response:
Correct the XML document.
Parent topic: XML - XML System Parser Interface


XML0004E

XML0004E hh:mm:ss.ttt Value [002] for elememt [003] is not numeric
Explanation:
Self-explanatory.
Issued by:
TAURIP75
User response:
Correct the XML document.
Parent topic: XML - XML System Parser Interface


XML0005E

XML0005E hh:mm:ss.ttt Unknown attribute [002] for element [003]
Explanation:
Self-explanatory.
Issued by:
TAURIP75
User response:
Correct the XML document.
Parent topic: XML - XML System Parser Interface


XML0006I

XML0006I hh:mm:ss.ttt z/Server is using CCSID [002]
Explanation:
This is an informational message.
Issued by:
TAURIP02
User response:
None.
Parent topic: XML - XML System Parser Interface


XML0007E

XML0007E hh:mm:ss.ttt Invalid value [002] for attribute [003].
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP75
User response:
Correct the XML document.
Parent topic: XML - XML System Parser Interface


XML0008E

XML0008E hh:mm:ss.ttt Attributes required for command [002].
Explanation:
Self-explanatory.
Issued by:
TAURIP75
User response:
Correct the XML document.
Parent topic: XML - XML System Parser Interface


XML0009I

XML0009I hh:mm:ss.ttt New XML image at address [002].
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP75
User response:
None.
Parent topic: XML - XML System Parser Interface


XML0010I

XML0010I hh:mm:ss.ttt XML interface called with function [002] and CCSID [003]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP63
Parent topic: XML - XML System Parser Interface


XML0011I

XML0011I hh:mm:ss.ttt XML interface ended. RC : [002] RSN : [003]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP63
User response:
None.
Parent topic: XML - XML System Parser Interface


XML0012I

XML0012I hh:mm:ss.ttt Offset to XML input area where parser stopped : [002]
Explanation:
This is an informational message.
Issued by:
TAURIP63
User response:
None.
Parent topic: XML - XML System Parser Interface


XML0013E

XML0013E hh:mm:ss.ttt Maximum number of [002] XML images exceeded.
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP75
System administrator response:
Internal restriction; contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0014E

XML0014E hh:mm:ss.ttt For USRENQ or USRDEQ a PORT must be specified.
Explanation:
Self-explanatory.
Issued by:
TAURIP78
User response:
Specify the port in the USRENQ/USRDEQ request.
Parent topic: XML - XML System Parser Interface


XML0015E

XML0015E hh:mm:ss.ttt Port [002] does not belong to user [003].
Explanation:
Self-explanatory.
Issued by:
TAURIP78
User response:
Correct the port number.
Parent topic: XML - XML System Parser Interface


XML0016E

XML0016E hh:mm:ss.ttt Value for attribute [002] must have a length of [003]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP75
User response:
Correct the XML document.
Parent topic: XML - XML System Parser Interface


XML0017I

XML0017I  hh:mm:ss.ttt XML query information
                       Version          :  [002]
                       Autodetect value :  [003]
                       Autodetect CCSID :  [004]
                       Specified  CCSID :  [005]
                       Length of decl   :  [006]
                       Flag 1           :  [007]
                                           1... .... standalone flag
                                           .1.. .... with byte order mark flag
                       Flag 2           :  [008]
                                           1... .... standalone specified
                                           .1.. .... encoding   specified
                                           ..1. .... version    specified
Explanation:
This message refers to deprecated functionality.
Issued by:
TAURIP63
System administrator response:
Contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0018I

XML0018I  hh:mm:ss.ttt Initialzing z/OS XML parser with CCSID [002]
Explanation:
This is an informational message due to IPTRACE level 5 being set.
Issued by:
TAURIP63
User response:
None.
Parent topic: XML - XML System Parser Interface


XML0019E

XML0019E  hh:mm:ss.ttt Invalid codepage [002] for z/Server specified.
                       CCSID is only valid if this is a scheduler and CCSID of
                       client is UTF-8
                       The codepage is also invalid if this is a scheduler, but
                       the scheduler functionality is skipped in this request.
Explanation:
The code page CCSID specified in the configuration is not supported by the z/OS XML parser. The startup of the server is stopped.
Issued by:
TAURIP18, TAURIP73
System administrator response:
Check the code page CCSID specified in the configuration file. Change it to a code page CCSID supported by z/Server.
Parent topic: XML - XML System Parser Interface


XML0020E

XML0020E  hh:mm:ss.ttt Invalid length [002] for attribute [003]
Explanation:
This message is issued in response to an API call.
Issued by:
TAURIP75
User response:
Specify a valid length.
Parent topic: XML - XML System Parser Interface


XML0022E

XML0022E  hh:mm:ss.ttt [002] is not a valid command.
Explanation:
A scheduler received an invalid command through an API request.
Issued by:
TAURIP75
User response:
Contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0023E

XML0023E  hh:mm:ss.ttt Attribute [002] invalid for command [003].
Explanation:
A scheduler received an invalid attribute through an API request.
Issued by:
TAURIP75
User response:
Contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0024E

XML0024E  hh:mm:ss.ttt Missing required attributes for command [003].
Explanation:
A scheduler received command [003] with missing attributes through an API request.
Issued by:
TAURIP75
User response:
Contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0025E

XML0025E  hh:mm:ss.ttt Value [002] for attribute [003] is not numeric.
Explanation:
A scheduler received a non-numeric value for an attribute that requires a numeric value through an API request.
Issued by:
TAURIP75
User response:
Contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0026E

XML0026E  hh:mm:ss.ttt Length of bitstring for attribute [002] not 8 bytes.
Explanation:
A scheduler received a bitstring value for an attribute with a length unequal to 8 through an API request.
Issued by:
TAURIP75
User response:
Contact SupportLine.
Parent topic: XML - XML System Parser Interface


XML0028W

XML0028W  hh:mm:ss.ttt Interpretation of XML document stopped at end of element [002].
Explanation:
This is an informational message due to IPTRACE level 1 being set. The interpretation was stopped when element [002] is closed.
Issued by:
TAURIP75
User response:
None
Parent topic: XML - XML System Parser Interface


CEA TSO/E Address Space Services

  • ZCA0001E
  • ZCA0002I
  • ZCA0006E
  • ZCA0010I
  • ZCA0011E
  • ZCA0012I
  • ZCA0013I
  • ZCA0014I
  • ZCA0015E
  • ZCA0016E
  • ZCA0018I
  • ZCA0019I
  • ZCA0022E
  • ZCA0024I
  • ZCA0025I
  • ZCA0027E
  • ZCA0028I
  • ZCA0029W
  • ZCA0030I
  • ZCA0031I
  • ZCA0032E
  • ZCA0033E
  • ZCA0034I
  • ZCA0035E
  • ZCA0036I
  • ZCA0038E
  • ZCA0039I
  • ZCA0040I
  • ZCA0041I
  • ZCA0042I
  • ZCA0043I
  • ZCA0044I
  • ZCA0045I
  • ZCA0046I
  • ZCA0047E
  • ZCA0048I
  • ZCA0050I
  • ZCA0051E
  • ZCA0052I
  • ZCA0053I
  • ZRM0001E
Parent topic: Messages


ZCA0001E

ZCA0001E hh:mm:ss.ttt  XML A logon procedure is required for policy CEA.
Explanation:
A scheduler was defined with policy 8 and the configuration variable CEA_LOGONPROC was not specified.
Issued by:
TAURIP18
Issued under:
Independent of any trace level
User response:
None
System administrator response:
Specify a valid logon procedure.
Parent topic: CEA TSO/E Address Space Services


ZCA0002I

ZCA0002I hh:mm:ss.ttt  CEA TSO/E address space services
                       Account............. : [002]
                       Group............... : [003]
                       Logon procedure..... : [004]
                       Charset............. : [005]
                       Codepage............ : [006]
                       Screen size......... : [007] X [008]
                       Region size......... : [009]
Explanation:
This message shows all configuration parameters for a scheduler defined with policy 8.
Issued by:
TAURIP74
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0006E

ZCA0006E hh:mm:ss.ttt  Call to CEASAPIT with function [002] ended
                       RC      :  [003]
                       RSN     :  [004]
                       Diag1   :  [005]
                       Diag2   :  [006]
                       Diag3   :  [007]
                       Diag4   :  [008]
Explanation:
A call to DLL CEASAPIT/CEATsoRequest failed.

Possible functions are:

  • CEATSOSTART
  • CEATSOENDS
  • CEATSIQUERY
  • CEATSOATTN
  • CEATSOPING
  • CEATSOQUERYAPP
Issued by:
TAURCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
See SA22-7613-xx callable services for HLL for more information
Parent topic: CEA TSO/E Address Space Services


ZCA0010I

ZCA0010I hh:mm:ss.ttt  Values for new TSO/E address space area
                       Userid         :  [002]
                       Asid           :  [003]
                       MessageQueueID :  [004]
                       Stoken         :  [005]
                       Index          :  [006]
Explanation:
This message is issued for a successful CEATSOSTART and shows the same values as the CEA command f cea,diag,sesstable
Issued by:
TAURCEA
Issued under:
Trace level 4 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0011E

ZCA0011E hh:mm:ss.ttt  Values error in callable service : [002]
                       RC  :  [003]
                       RSN :  [004]
Explanation:
This message is issued if a call to a UNIX message queue service failed.

Possible services are:

  • BPX1QRC - Receive from a message queue
  • BPX1QSN - Send to a message queue
  • BPX1QCT - Control operation
  • BPX1QGT - Create/find a message queue
Issued by:
TAURMSQ
Issued under:
Independent of any trace level
User response:
None
System administrator response:
If you are not able to find the reason, contact SupportLine and provide all available output. If possible, try to recreate the problem with trace level 6.
Parent topic: CEA TSO/E Address Space Services


ZCA0012I

ZCA0012I hh:mm:ss.ttt  [002] bytes received from message queue
Explanation:
This message is issued after a successful read of a UNIX message queue service failed.
[002]
Contains the amount of bytes.
Issued by:
TAURMSQ
Issued under:
Trace level 4 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0013I

ZCA0012I hh:mm:ss.ttt  Sending [002] bytes to message queue
                       Queue ID...... [003]   (hex)
                       Message type.. [004]   (hex)
Explanation:
This message is issued after a successful write to a UNIX message queue.
[002]
Contains the amount of bytes
[003]
Contains the queue ID
[004]
Contains the message type
Issued by:
TAURMSQ
Issued under:
Trace level 4 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0014I

ZCA0014I hh:mm:ss.ttt Information for message queue  [002]
                      Messages on queue      :  [003]
                      Maximum bytes allowed  :  [004]
                      Time of last send      :  [005]
                      Time of last receive   :  [006]
Explanation:
This message is issued in response to a USSQMSGQ (Unix message queue query) command.
[002]
Contains the queue ID
[003]
The number of messages on the queue
[004]
The maximum number of bytes allowed
[005]
The time of the last message sent
[006]
The time of the last message received
Issued by:
TAURMSQ
Issued under:
Trace level 4 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0015E

ZCA0015E hh:mm:ss.ttt  Abend during CEA processing. ECB is [002]
Explanation:
This message is written when the ATTACH of subtask TAURC64 failed. [002] contains the ECB for the abended subtask
Issued by:
TAURCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
Contact SupportLine and provide all available output. If possible, try to recreate the problem with trace level 6
Parent topic: CEA TSO/E Address Space Services


ZCA0016E

ZCA0016E hh:mm:ss.ttt  Start of TSO address space was unsuccessful.
                       Unable to get CAUB_JOBID.
                       ASID   :  [002]
                       RSN    :  [003]
Explanation:
This message is written when z/Server was not able to get the JOBID after a CEA TSO/E address space was successfully created. In most cases, the reason for this message is a JCL error.
Issued by:
TAURCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
Check the logon procedure. If you are not able to find the reason, contact SupportLine and provide all available output. If possible, try to recreate the problem with trace level 6.
Parent topic: CEA TSO/E Address Space Services


ZCA0018I

ZCA0018I hh:mm:ss.ttt  CEA interface called with function [002]
Explanation:
This message is written if module TAURCEA was called. Functions are the same as in message ZCA006E
Issued by:
TAURCEA
Issued under:
Trace Level 5 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0019I

ZCA0018I hh:mm:ss.ttt  CEA interface ended. RC : [002]
Explanation:
This message is written after call to module TAURCEA

Possible return codes:

00 - Call successful

08 - Invalid function

12 - Call to CEATsorequest failed

16 - Call to BPX. API failed

20 - Abend in subtask for CEA processing

40 - Creation of security environment for CEA failed

44 - Invalid screen size

Issued by:
TAURCEA
Issued under:
Trace level 5 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0022E

ZCA0022E hh:mm:ss.ttt  Account information is required scheduler of type
                       CEA.
Explanation:
A scheduler was defined with policy 8 and the configuration variable CEA_ACCOUNT was not specified.
Issued by:
TAURIP18
Issued under:
Independent of any trace level
User response:
None
System administrator response:
Specify ACCOUNT information
Parent topic: CEA TSO/E Address Space Services


ZCA0024I

ZCA0024I hh:mm:ss.ttt  Reading message queue
                       Queue ID...... [002]   (hex)
                       Message type.. [003]   (hex)
                       Read count.... [004]
                       Flags......... [005]
Explanation:
This message is written for a read request of a USS message queuee.
[002]
Contains the queue ID
[003]
Contains the message type
[004]
Contains the # of requested reads
[005]
Contains the read flags
X’00000000’
Wait for next message
X’00000001’
Do not wait for next message
Issued by:
TAURMSQ
Issued under:
Trace level 5 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0025I

ZCA0025I hh:mm:ss.ttt  USS message queue utility called with function
                       [002]
Explanation:
This message is written if module TAURMSQ was called. Possible functions are Read/Write/Query/Create/Delete/Gettoken.
Issued by:
TAURMSQ
Issued under:
Trace level 5 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0027E

ZCA0027E hh:mm:ss.ttt  Creation of task level security for CEA failed
                       UserID      : [002]
                       SAF  RC     : [003]       (hex)
                       RACF RC     : [004]       (hex)
                       RACF RSN    : [005]       (hex)
Explanation:
This message is issued after the creation of an ACEE for CEA failed
Issued by:
TAURCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
See SA22-7692-xx: Security server RACROUTE macro reference. If you are not able to solve the problem, contact SupportLine and provide all output. Try to recreate the problem with trace level 6.
Parent topic: CEA TSO/E Address Space Services


ZCA0028I

ZCA0028I hh:mm:ss.ttt  Ping for application identifier [002]
Explanation:
This message is issued from the command task if a scheduler is defined with policy 8 (CEA). The command task will ping the application ID from [002] in order to keep the CEA userid server alive. If the user servers are not pinged, CEA will terminate the user servers after an idle time of 15 minutes.
Issued by:
TAURIP16
Issued under:
Trace level 3 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0029W

ZCA0029W hh:mm:ss.ttt  TSU session for user [002] and ASID [003] no longer exists. Entry in user administration cleared.
Explanation:
This message is issued from the command task if a scheduler is defined withpolicy 8 (CEA). The command detected an inactive CEA user server. The command task will clear the entry.
Issued by:
TAURIP16
Issued under:
Independent of any trace level
User response:
None
System administrator response:
This is normal if a SERVICE_WAIT of more than 15 minutes is specified. In this case, CEA will terminate the user server after 15 minutes idle time. The scheduler will cleanup the entry one minute later. If a SERVICE_WAIT of less than 14 minutes is specified, the user server should never end without a logoff.
Parent topic: CEA TSO/E Address Space Services


ZCA0030I

ZCA0030I hh:mm:ss.ttt  ----------------------------------------------------
                       CEA request structure
                       ----------------------------------------------------
Explanation:
This message is the header information before the CEA request structure is dumped. This information is only required if SupportLine is contacted to solve problems with CEA.
Issued by:
TAURCEA
Issued under:
Trace level 5 or higher
User response:
None
System administrator response:
None.
Parent topic: CEA TSO/E Address Space Services


ZCA0031I

ZCA0031I hh:mm:ss.ttt  Query TSU session for user [002] and ASID [003]
Explanation:
This message is issued from the command task if a scheduler is defined with policy 8 (CEA). The command checks if a CEA user server defined in the scheduler is still active.
Issued by:
TAURIP16
Issued under:
Trace level 1 or higher
User response:
None
System administrator response:
None.
Parent topic: CEA TSO/E Address Space Services


ZCA0032E

ZCA0032E hh:mm:ss.ttt  Send to client ended. RC : [002] (hex).
Explanation:
This message is issued if the client has initialized a CEA dialog and a send to the client was unsuccessful.
Issued by:
TAURQCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
If you are not able to solve the problem, contact SupportLine and provide all output. Try to recreate the problem with trace level 6.
Parent topic: CEA TSO/E Address Space Services


ZCA0033E

ZCA0033E hh:mm:ss.ttt  Receive from client ended. RC : [002] (hex).
Explanation:
This message is issued if the client has initialized a CEA dialog and a receive from the client was unsuccessful.
Issued by:
TAURQCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
If you are not able to solve the problem, contact SupportLine and provide all output. Try to recreate the problem with trace level 6
Parent topic: CEA TSO/E Address Space Services


ZCA0034I

ZCA0034I hh:mm:ss.ttt  Using alternate screen size [002] X [003] from LOGON.
Explanation:
This message is issued if the client sent a CEA logon request and specified the ROWS and COLUMNS attribute.
Issued by:
TAURCEA
Issued under:
Trace level 5 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0035E

ZCA0035E hh:mm:ss.ttt  Invalid request for CEATASK. Only R,W,Q allowed.
Explanation:
This message is issued if the client has initialized a CEA dialog and an invalid request was sent to the scheduler.
Issued by:
TAURQCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
Contact SupportLine and provide all output. Try to recreate the problem with trace level 6
Parent topic: CEA TSO/E Address Space Services


ZCA0036I

ZCA0036I hh:mm:ss.ttt  CEA message queue handler terminated.
Explanation:
This message is issued if the client has initialized a CEA dialog and the CEA dialog was terminated due to logoff.
Issued by:
TAURQCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0038E

ZCA0038E hh:mm:ss.ttt  Invalid screen size [002] X [003]
                       Only 24x80, 32x80, 43x80, 27x132 and 62x160 allowed
Explanation:
This message is issued if an invalid screen size for a CEA user server was specified.
Issued by:
TAURCEA
Issued under:
Independent of any trace level
User response:
Use a valid screen size
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0039I

ZCA0039I hh:mm:ss.ttt  Initial command..... : [002]
Explanation:
This message prints the content of the configuration variable CEA_INIT_CMD.
Issued by:
TAURIP74
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0040I

ZCA0040I hh:mm:ss.ttt  Before call to CEA initial command [002] via TAURUCA
Explanation:
This message is issued from subtask CEAISPF when a CEA dialog is initialized before the defined initial command is invoked. This message indicates the beginning of a CEA dialog.
Issued by:
TAURIP07
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0041I

ZCA0041I hh:mm:ss.ttt  After call to CEA initial command [002] via TAURUCA
Explanation:
This message is issued from subtask CEAISPF after a CEA dialog was initialized and the defined initial command terminated. This message indicates the end of a CEA dialog.
Issued by:
TAURIP07
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0042I

ZCA0042I hh:mm:ss.ttt  CEAISPF READY for initialization
Explanation:
This message is issued from subtask CEAISPF and indicates that the subtask is now READY for the initialization of a CEA dialog.
Issued by:
TAURIP07
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0043I

ZCA0043I hh:mm:ss.ttt  Initializing z/Server for CEA
Explanation:
This message is issued if a user server for CEA is started.
Issued by:
TAURUCA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0044I

ZCA0044I hh:mm:ss.ttt  Terminating z/Server for CEA
Explanation:
This message is issued if a user server for CEA is terminated.
Issued by:
TAURUCA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0045I

ZCA0045I hh:mm:ss.ttt  Before call to CEA initial command [002] for [003]
Explanation:
This message is issued if the CEA initial REXX is issued. [003] contains the reason for the initialization and may be:
  • for initialization
  • for split screen
Issued by:
TAURUCA
Issued under:
Trace level 4 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0046I

ZCA0046I hh:mm:ss.ttt  After call to CEA initial command [002] for [003]
Explanation:
This message is issued if the CEA initial REXX is terminated. [003] contains the reason for the termination and may be:
  • for initialization
  • for split screen
Issued by:
TAURUCA
Issued under:
Trace level 4 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0047E

ZCA0047E hh:mm:ss.ttt  Underlying z/OS level must be at least z/OS 1.13 when a scheduler of type CEA is started.
Explanation:
This message is issued if the scheduler with policy 8 is started and z/OS 1.13 or higher is not available.
Issued by:
TAURIP18
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0048I

ZCA0047E hh:mm:ss.ttt  CEA Screen count for initial command [002] is [003]
Explanation:
This message is issued if the CEA initial REXX is activated and traces the logical screen count.
Issued by:
TAURUCA
Issued under:
Trace level 4 or higher
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0050I

ZCA0050I hh:mm:ss.ttt  LOGOFF request for CEA received
Explanation:
This message is issued if the CEA dialog is terminated due to a logoff command.
Issued by:
TAURQCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0051E

ZCA0051E hh:mm:ss.ttt  Invalid internal command received.
Explanation:
The client sent an invalid internal command to the CEA dialog.
Issued by:
TAURQCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
Contact SupportLine and provide all output. Try to recreate the problem with trace level 6.
Parent topic: CEA TSO/E Address Space Services


ZCA0052I

ZCA0052I hh:mm:ss.ttt  Internal command [002] specified.
Explanation:
The client sent a valid internal command to the CEA dialog.
Issued by:
TAURQCEA
Issued under:
Independent of any trace level
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZCA0053I

ZCA0053I               Application ID...... : [001]
                       Ping application ID. : [002]
Explanation:
This message shows configuration parameters for a scheduler defined with policy 8.
Issued by:
TAURIP74
Issued under:
Independent of any trace levelAbend Codes
User response:
None
System administrator response:
None
Parent topic: CEA TSO/E Address Space Services


ZRM0001E

ZRM0001E hh:mm:ss.ttt Enqueue of resource was made with userid [002]
                      Dequeue not allowed for userid [003]
Explanation:
Userid 0003 tried to issue a dequeue of a resource that was enqueued (owned) by userid 002.
Issued by:
TAURIP35
User response:
Contact userid 002 if the resource should be freed.
Parent topic: CEA TSO/E Address Space Services


ABEND Code U2222

z/Server has one (user) ABEND code: u2222 with different reason codes.

  • Reason Code 1
Parent topic: Messages


Reason Code 1

Abendu2222 reason code 1 is issued whenever a user server was terminated without first stopping one or more REXX environments that are still running at the time of termination. In that case, task control blocks (TCBs) that are left hanging will not terminate on their own, causing the address space to hang during termination. In that case, the address space will need to be canceled.

This usually happens when an ISPF application encounters a problem and does not send a good explanation to the client or is now in an undefined state. It can also happen when a command was issued in the user server that is listed in the installation’s IKJTSOxx parmlib member under PLATCMD or PLATPGM. z/Server does not tolerate commands executed under the platform TCB as it requires MVS services for task termination (clean-up).

To prevent subsequent abnormal end problems, z/Server terminates all tasks that should not be running anymore using reason code 1.

Parent topic: ABEND Code U2222


Language Environment abends

For an explanation of these abends (U4012, U4034, U4036, U4038, U4039,U4041, U4042, U4043, U4080, U4082, U4083, U4084, U4085, U4086, U4087, U4088, U4089, U4091, U4092, U4093, U4094 and U4095), see SA22-7566: Language Environment Run-Time Messages.

Parent topic: Messages


Troubleshooting

If the user and system administrator responses do not help to correct the problem, the appropriate log files and dumps should be sent to SupportLine. The log files are found as JESx output data sets.

  • Holder
  • Scheduler
  • User server
  • Trace level
  • Required information for SupportLine
Parent topic: zServer messages and Diagnostics


Holder

A standard holder address space job log consists of the following DD names (example from JES2/SDSF):

NP   DDNAME   StepName ProcStep CrDate-CrTime       O-Grp-N  DSID Owner
     SYSTSPRT TAURHLDP          mm/dd/jjjj hh:mm:ss           102 TAUUSR
     MAINTASK TAURHLDP          mm/dd/jjjj hh:mm:ss           105 TAUUSR
     JESYSMSG                   mm/dd/jjjj hh:mm:ss             4 TAUUSR
     JESMSGLG                   mm/dd/jjjj hh:mm:ss             2 TAUUSR
     JESJCL   JES2              mm/dd/jjjj hh:mm:ss             3 TAUUSR

The JESYSMSG, JESMSGLG and JESJCL DD names are the standard names used by JES2.

  • MAINTASK
  • SYSTSPRINT
  • DSPPRT
Parent topic: Troubleshooting


MAINTASK

This DD statement contains the messages issued by MAINTASK running in the holder address space. During startup the configuration parameters used are shown. MAINTASK initialized successfully when this message is issued:

HLD0002I  hh:mm:ss.ttt z/Server for Taurus holder task ready for commands

After startup, it will contain command responses for modify commands directed at the holder.

Parent topic: Holder


SYSTSPRINT

This DD statement contains the messages issued by the holder task configuration component, prefixed DSC. If the holder address space terminates at startup, this is the first place to look for problems.

Parent topic: Holder


DSPPRT

This DD statement contains the output issued in response to a

F <holder>,DISPLAY,DSP,[FORMAT | DUMP]

command.

Parent topic: Holder


Scheduler

A standard holder address space job log consists of the following DD names (example from JES2/SDSF):

NP   DDNAME   StepName ProcStep CrDate-CrTime       O-Grp-N  DSID Owner
     ZCOTSPRT TAURISPP          mm/dd/jjjj hh:mm:ss           104 TAUUSR
     T0000005 TAURISPP          mm/dd/jjjj hh:mm:ss           112 TAUUSR
     T0000004 TAURISPP          mm/dd/jjjj hh:mm:ss           109 TAUUSR
     T0000003 TAURISPP          mm/dd/jjjj hh:mm:ss           113 TAUUSR
     T0000002 TAURISPP          mm/dd/jjjj hh:mm:ss           111 TAUUSR
     T0000001 TAURISPP          mm/dd/jjjj hh:mm:ss           110 TAUUSR
     SYSTSPRT TAURISPP          mm/dd/jjjj hh:mm:ss           103 TAUUSR
     SRVTASK  TAURISPP          mm/dd/jjjj hh:mm:ss           107 TAUUSR
     MAINTASK TAURISPP          mm/dd/jjjj hh:mm:ss           106 TAUUSR
     LISTENER TAURISPP          mm/dd/jjjj hh:mm:ss           105 TAUUSR
     MSGTASK  TAURISPP          mm/dd/jjjj hh:mm:ss           104 TAUUSR
     JESYSMSG                   mm/dd/jjjj hh:mm:ss             4 TAUUSR
     JESMSGLG                   mm/dd/jjjj hh:mm:ss             2 TAUUSR
     JESJCL   JES2              mm/dd/jjjj hh:mm:ss             3 TAUUSR
     CMDTASK  TAURISPP          mm/dd/jjjj hh:mm:ss           108 TAUUSR

The JESYSMSG, JESMSGLG and JESJCL DD names are the standard names used by JES2.

  • MAINTASK
  • LISTENER
  • MSGTASK
  • CMDTASK
  • SRVTASK
  • T000000x
  • SYSTSPRT
  • ZCOTSPRT
Parent topic: Troubleshooting


MAINTASK

This DD statement contains the messages issued by MAINTASK running in the scheduler address space. It shows the important configuration during initialiazation and addresses for important control blocks, all written during startup of the address space.

Parent topic: Scheduler


LISTENER

This DD statement contains the messages issued by LISTENER running in the scheduler address space. It shows the important configuration settings and addresses for important control blocks. LISTENER is successfully initialized when this message is issued:

TAU0141I  hh:mm:ss.ttt z/Server listener READY for clients

After startup, LISTENER shows which worker task T000000x was posted to fulfil the client request and the IP address of the client.

Parent topic: Scheduler


MSGTASK

This DD statement contains the messages issued by MSGTASK running in the scheduler address space. MSGTASK can be used to queue an input message for a scheduler to a USS message queue. A queued message is not processed immediately but rather written to a USS message queue. The QID and a response token are returned to the client. The client can read the result at any time. The queue id of a scheduler can be determined through the dataspace space.

Parent topic: Scheduler


CMDTASK

This DD statement contains the messages issued by the command task running in the scheduler address space. During startup, important control block addresses, configuration parameters used, command exit names and the name of the command REXX exec are listed. The command task successfully initialized when this message is issued:

TAU0107I  hh:mm:ss.ttt Registration for exception handler >>TAURIP86<< successful.

After startup, it will contain command responses for modify commands directed at the scheduler.

Parent topic: Scheduler


SRVTASK

This DD statement contains the messages issued by the service task running in the scheduler address space. During startup, important control block addresses and configuration parameters used are listed. The service task successfully initialized when this message is issued:

TAU0107I  hh:mm:ss.ttt Registration for exception handler >> TAURIP86<< successful.
Parent topic: Scheduler


T000000x

The DD statements named T0000001 to T000000n with n=NUMTCB from the scheduler configuration contain the messages issued by the numbered working task running in the scheduler address space. These tasks get woken up by the main task to fulfil the requests coming in from clients.

During startup, important control block addresses and configuration parameters used are listed. The worker task successfully initialized when this message is issued:

TAU0142I  hh:mm:ss.ttt z/Server subtask READY for clients

After startup, it shows which client the worker task was active for. First it acknowledges that it was activated and then it lists what it was activated for. A typical example would look like this:

TAU0023I  hh:mm:ss.ttt Subtask for z/Server activated
SLR0107I  hh:mm:ss.ttt Deferred LOGON for user userid  successful
Parent topic: Scheduler


SYSTSPRT

This DD statement always contains

IKJ56644I NO VALID TSO USERID, DEFAULT USER ATTRIBUTES USED
Parent topic: Scheduler


ZCOTSPRT

This DD statement contains messages issued by REXX.

Parent topic: Scheduler


User server

Determine the name of the user server that had a problem. That name consists of the TSOE_JOBCHAR parameter from the configuration file, followed by the TSO user ID. Depending on the activity of the client, there may be more than one STC job log with the same name, but different JES job IDs.

A standard user server job log consists of the following DD names (example from JES2/SDSF):

NP   DDNAME   StepName ProcStep CrDate-CrTime       O-Grp-N  DSID Owner
     ZCOTSPRT IVPISPF           mm/dd/jjjj hh:mm:ss 7         106 TAUUSR
     T0000001 IVPISPF           mm/dd/jjjj hh:mm:ss 2         113 userid
     SYSTSPRT IVPISPF           mm/dd/jjjj hh:mm:ss 7         105 TAUUSR
     SYSPRINT IVPISPF           mm/dd/jjjj hh:mm:ss 5         111 userid
     SYSPRINT IVPISPF           mm/dd/jjjj hh:mm:ss 8         116 userid
     SRVTASK  IVPISPF           mm/dd/jjjj hh:mm:ss 4         115 userid
     MAINTASK IVPISPF           mm/dd/jjjj hh:mm:ss 3         112 userid
     LISTENER IVPISPF           mm/dd/jjjj hh:mm:ss 3         105 userid
     JESYSMSG                   mm/dd/jjjj hh:mm:ss 7           4 TAUUSR
     JESMSGLG                   mm/dd/jjjj hh:mm:ss 7           2 TAUUSR
     JESJCL   JES2              mm/dd/jjjj hh:mm:ss 7           3 TAUUSR
     ISPLOG   IVPISPF           mm/dd/jjjj hh:mm:ss 7         103 TAUUSR
     CMDTASK  IVPISPF           mm/dd/jjjj hh:mm:ss 6         114 userid

The JESYSMSG, JESMSGLG and JESJCL DD names are the standard names used by JES2.

  • MAINTASK
  • LISTENER
  • CMDTASK
  • SRVTASK
  • T0000001
  • SYSTSPRT
  • ZCOTSPRT
  • SYSPRINT
  • ISPLOG
Parent topic: Troubleshooting


MAINTASK

Same as scheduler.

Parent topic: User server
Related information
MAINTASK


LISTENER

Same as scheduler.

Parent topic: User server
Related information
LISTENER


CMDTASK

This DD statement contains the messages issued by the command task running in the user server address space. During startup, important control block addresses and used configuration parameters are listed. The command task successfully initialized when this message is issued:

TAU0107I  hh:mm:ss.ttt Registration for exception handler >> TAURIP86<< successful.

After startup, it will contain command responses for modify commands directed at the scheduler.

Parent topic: User server


SRVTASK

This DD statement contains the messages issued by the service task running in the user server address space. During startup, important control block addresses and configuration parameters used are listed. The service task successfully initialized when this message is issued:

TAU0107I  hh:mm:ss.ttt Registration for exception handler >> TAURIP86<< successful.
Parent topic: User server


T0000001

The DD statement T0000001 contains the messages issued by worker task number one running in the user server address space. This task gets woken up by the main task to fulfil the requests coming in from clients.

If the parameter NUMTCB in the user server configuration is bigger than one, there is more than one worker task.

During startup, important control block addresses and configuration parameters used are listed. The worker task successfully initialized when this message is issued:

TAU0142I  hh:mm:ss.ttt z/Server Subtask READY for clients

After startup it shows which client the worker task was active for. First it acknowledges that it was activated and then it lists what it was activated for. A typical example would look like this:

TAU0023I  hh:mm:ss.ttt Subtask for z/Server activated
TAU0059I  hh:mm:ss.ttt TAUZCAPP ended. RC : 00000000
Parent topic: User server


SYSTSPRT

This DD statement contains the output from any REXX exec run in the user server address space. For instance, this can be trace output.

Parent topic: User server


ZCOTSPRT

This DD statement contains messages issued by REXX when the so-called ZCOM environment got addressed by the REXX exec running.

Parent topic: User server


SYSPRINT

The two SYSPRINT DD statements contain the output from the IEBCOPY operation that copies the ISPF profile, one during startup, the other during shutdown, assuming that the provided samples for IVPINIT1/2 were used.

Parent topic: User server


ISPLOG

This is the ISPF transaction log showing the ISPF commands issued in this user server address space.

Parent topic: User server


Trace level

The trace level of an address space specifies how many messages are written to the JESx spool to detail the code paths taken for debugging purposes.

The trace level for all three types of address spaces is specified using the configuration parameter IPTRACE and by default is set to zero. This means that only required messages are written to job log to follow the operation of z/Server to minimize the amount of output generated on the JESx spool.

The IPTRACE level can be dynamically changed using the command

F <holder|scheduler|userserver>,TRACE,LEVEL=x

with x a number from zero to six.

If a problem occurs, most of the time it will be necessary to increase the trace level to a higher setting, generating more messages that can serve as a debugging aid for SupportLine, reproduce the problem and then dynamically decrease the trace level again.

Be aware that trace levels five and six can generate a huge amount of data, depending on the amount of work done in z/Server and the number of users. Indiscriminate use of the higher trace levels can lead to severe JESx spool shortages.

Parent topic: Troubleshooting


Required information for SupportLine

In case of problems that cannot be solved by using the documentation provided in this book and looking up the relevant messages, return and reason codes in the IBM documentation, please provide the following:

  1. A problem description that includes what the client has done in which order, so SupportLine has a chance to try and reproduce the problem.
  2. The full job logs of all address spaces involved in the problem (scheduler job log, all user servers' job logs - this can be more than one).
  3. Any dump that occurred (system dump, CEEDUMP, so-called ZCOMDUMP).
  4. Preferably all configuration parameters specified for holder, scheduler and user server.
Parent topic: Troubleshooting


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

  • Btrieve Error Codes
  • 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


Btrieve Error Codes

Click the number of the error that you require information about.

  • Btrieve Error/ COBOL File Status Mappings
  • 1 - 19
  • 20 - 39
  • 40 - 59
  • 60 - 79
  • 80 - 99
  • 100 - 119
  • 120-139
Parent topic: File Handling Reference
Related information
Data Related


Btrieve Error/ COBOL File Status Mappings

If an error is returned by the Btrieve Record Manager, the Xfh2btr call conversion module maps the Btrieve error to a COBOL file status code which it returns to your program. The mappings are shown below. Any error returned by Btrieve that is not in the table below will be returned as a 9/025 error.

COBOL Status | Btrieve Status
10 | 9 (if READ sequential operation)
21 | 10
22 | 5
23 | 4, 9 (if START operation), 43
35 | 12
42 | 3 (if CLOSE operation)
43 | 8
47 | 3 (if START/READ operation)
48 | 3 (if WRITE operation), 46
49 | 3 (if REWRITE/DELETE operation)
9/004 | 11
9/007 | 2 (if WRITE operation), 18, 38
9/009 | 35
9/013 | 12
9/014 | 40, 47, 86, 87
9/025 | 101, 102, 103, 104, 105, 106, 107, 109, 130, 133
9/027 | 20
9/033 | 2 (if not WRITE or OPEN operation), 14, 15, 16, 17, 19, 33, 54, 66, 67, 68, 69, 71, 72, 73, 75, 76, 79, 100
9/036 | 59
9/037 | 51, 94
9/039 | 2 (if OPEN operation), 30
9/040 | 24, 36, 58, 90, 91, 92, 96
9/041 | 42, 56
9/047 | 6
9/053 | 53
9/065 | 25, 85 (if OPEN operation), 88
9/068 | 77, 80, 83, 84, 85 (if non-OPEN operation)
9/074 | 60, 61, 62, 63, 64, 65
9/077 | 13, 21, 23, 31, 32, 34, 37, 39, 45, 48, 49, 50, 55, 93
9/078 | 26, 29
9/100 | 41, 99
9/124 | 95
9/125 | 74, 78, 98
9/126 | 97
9/139 | 7, 22, 27, 28, 44
9/142 | 3 (if CLOSE operation)
9/143 | 8
9/146 | 82
9/147 | 3 (if START/READ operation)
9/148 | 3 (if WRITE operation), 46
9/149 | 3 (if REWRITE/DELETE operation)
9/161 | 1
9/213 | 81
Parent topic: Btrieve Error Codes
Related information
Data Related


1 - 19

  • 1 The operation parameter is invalid.
    Returned as COBOL status: 9/161
  • 2 The application encountered an I/O error.
  • 3 The file is not open.
    This status should not be encountered if you are using the Xfh2btr module as it generates the appropriate status without calling the Btrieve run-time system.
  • 4 The key value cannot be found.
    Returned as COBOL status: 23
  • 5 The record has a key field containing a duplicate key value.
    Returned as COBOL status: 22
  • 6 The key number parameter is invalid.
    Returned as COBOL status: 9/047
  • 7 The key number has changed.
    Returned as COBOL status: 9/139
  • 8 The current positioning is invalid.
    This indicates that it is not possible to reposition the current record pointer after an operation and that the current positioning is invalid. The positioning needs to be re-established using a READ or START operation.
  • 9 The operation encountered an end-of-file mark.
  • 10 The key field is not modifiable.
    Returned as COBOL status: 21
  • 11 The specified filename is invalid.
    Returned as COBOL status: 9/004
  • 12 Btrieve cannot find the specified file.
    Note that if the file is on a server, you must have FILE SCAN access rights to the directory where the file resides.
  • 13 Extended file error.
    Returned as COBOL status: 9/077
  • 14 Btrieve cannot create or open the pre-image file.
    Returned as COBOL status: 9/033
  • 15 The application encountered an I/O error during pre-imaging.
    Returned as COBOL status: 9/033
  • 16 The application encountered an expansion error.
    Returned as COBOL status: 9/033
  • 17 The application encountered a close error.
    Returned as COBOL status: 9/033
  • 18 The disk is full.
    Returned as COBOL status: 9/007
  • 19 The application encountered an unrecoverable error.
    Returned as COBOL status: 9/033
Parent topic: Btrieve Error Codes


1 The operation parameter is invalid.

Returned as COBOL status: 9/161

This status should not be encountered if you are using the Xfh2btr module.

Parent topic: 1 - 19


2 The application encountered an I/O error.

Returned as COBOL status:

  • 9/039 if performing an OPEN operation
  • 9/007 if performing a WRITE operation
  • 9/033 if performing a different operation
Parent topic: 1 - 19


3 The file is not open.

This status should not be encountered if you are using the Xfh2btr module as it generates the appropriate status without calling the Btrieve run-time system.
Table 1. Returned as COBOL status
Operation | ansi 85 status | ansi 74 status
CLOSE | 42 | 9/142
WRITE | 48 | 9/148
REWRITE/DELETE | 49 | 9/149
START/READ | 47 | 9/147
Parent topic: 1 - 19


4 The key value cannot be found.

Returned as COBOL status: 23
Parent topic: 1 - 19


5 The record has a key field containing a duplicate key value.

Returned as COBOL status: 22
Parent topic: 1 - 19


6 The key number parameter is invalid.

Returned as COBOL status: 9/047

If calling Xfh2btr directly, this indicates that the key-id field in the FCD is incorrect

Parent topic: 1 - 19


7 The key number has changed.

Returned as COBOL status: 9/139

This error should not be encountered if using the Xfh2btr module.

Parent topic: 1 - 19


8 The current positioning is invalid.

This indicates that it is not possible to reposition the current record pointer after an operation and that the current positioning is invalid. The positioning needs to be re-established using a READ or START operation.
Returned as COBOL status:
  • ansi 85 status: 43
  • ansi 74 status: 9/143
Parent topic: 1 - 19


9 The operation encountered an end-of-file mark.

Returned as COBOL status:
  • 23 if performing a START operation
  • 10 if performing a READ (sequential) operation
Parent topic: 1 - 19


10 The key field is not modifiable.

Returned as COBOL status: 21

An attempt was made to perform a REWRITE operation where an attempt to change a key value was made although the key is defined as non-modifiable in the file.

The Xfh2btr module will create the primary key as non-modifiable and the alternate keys as modifiable.

This error implies that the Btrieve file was created outside of the COBOL system, and that an alternate key is defined as non-modifiable.

Parent topic: 1 - 19


11 The specified filename is invalid.

Returned as COBOL status: 9/004

Note that Btrieve filenames cannot have an extension ^^^.

Parent topic: 1 - 19


12 Btrieve cannot find the specified file.

Note that if the file is on a server, you must have FILE SCAN access rights to the directory where the file resides.
Returned as COBOL status:
  • ansi 85 status: 35
  • ansi 74 status: 9/013
Parent topic: 1 - 19


13 Extended file error.

Returned as COBOL status: 9/077

Btrieve v5.x or earlier could not find the extension file for an extended file that the application tried to open.

The Xfh2btr module does not extend files and so this error implies that the file was created outside of the COBOL system. Ensure that the required extended file is available (extension files must be loaded on the logical disk drive specified when the extension was created). In order to access an extended file, both the primary file and its extension file must be online.

Parent topic: 1 - 19


14 Btrieve cannot create or open the pre-image file.

Returned as COBOL status: 9/033

Note that pre-image files are only used of file versions prior to v6.0

Parent topic: 1 - 19


15 The application encountered an I/O error during pre-imaging.

Returned as COBOL status: 9/033

Note that pre-image files are only used of file versions prior to v6.0

Parent topic: 1 - 19


16 The application encountered an expansion error.

Returned as COBOL status: 9/033

The Xfh2btr module does not expand files and so this error should not be encountered.

Parent topic: 1 - 19


17 The application encountered a close error.

Returned as COBOL status: 9/033
Parent topic: 1 - 19


18 The disk is full.

Returned as COBOL status: 9/007
Parent topic: 1 - 19


19 The application encountered an unrecoverable error.

Returned as COBOL status: 9/033
Parent topic: 1 - 19


20 - 39

  • 20 The Btrieve Engine or Requester is inactive.
    Returned as COBOL status: 9/027
  • 21 The key buffer parameter is too short.
    Returned as COBOL status: 9/077
  • 22 The data buffer parameter is too short.
    Returned as COBOL status: 9/139
  • 23 The position block parameter is not 128 bytes long.
    Returned as COBOL status: 9/077
  • 24 The page size or date buffer size is invalid.
    Returned as COBOL status: 9/040
  • 25 The application cannot create the specified file.
    Returned as COBOL status: 9/065
  • 26 The number of keys is invalid.
    Returned as COBOL status: 9/078
  • 27 The key position is invalid.
    Returned as COBOL status: 9/139
  • 28 The record length is invalid.
    Returned as COBOL status: 9/139
  • 29 The key length is invalid.
    Returned as COBOL status: 9/078
  • 30 The file specified is not a Btrieve file.
    Returned as COBOL status: 9/039
  • 31 The file is already extended.
    Returned as COBOL status: 9/077
  • 32 The file cannot be extended.
    Returned as COBOL status: 9/077
  • 33 Btrieve cannot be unloaded.
    Returned as COBOL status: 9/033
  • 34 The specified extension name is invalid.
    Returned as COBOL status: 9/077
  • 35 The application encountered a directory error.
    Returned as COBOL status: 9/009
  • 36 The application encountered a transaction error.
    Returned as COBOL status: 9/040
  • 37 Another transaction is active.
    Returned as COBOL status: 9/077
  • 38 Btrieve enountered a transaction control file I/O error.
    Returned as COBOL status: 9/007
  • 39 A Begin Transaction operation must precede an End/Abort Transaction operation.
    Returned as COBOL status: 9/077
Parent topic: Btrieve Error Codes


20 The Btrieve Engine or Requester is inactive.

Returned as COBOL status: 9/027

You must start the Micro Kernel Database Engine (MKDE) before generating any requests.

Ensure that the MKDE executable is on your PATH or in the top level of your Windows directory.

Ensure that the Btrieve for Windows DLL, wbtrv32.dll, is on your PATH.

By default, in the Windows environment, the Setup utility turns on the Client Engine Usage option. If you want to access server-based Btrieve but do not want to access client-based Btrieve, turn the Local option off and turn the Server option on. If you want to access both client-based Btrieve and server-based Btrieve, turn the Server option on and leave the Local option on.

If the problem persists, ensure that the Btrieve run-time system is configured and running by performing a -STAT function on the file you are attempting to access. The -STAT operation is available with the BUTIL and BUTIL utilities supplied by Btrieve Technologies.

Parent topic: 20 - 39


21 The key buffer parameter is too short.

Returned as COBOL status: 9/077

This error should not be encountered if using Xfh2btr.

Parent topic: 20 - 39


22 The data buffer parameter is too short.

Returned as COBOL status: 9/139

This implies that the record area defined in the program is not large enough to hold the record that is being read from the Btrieve file. Ensure that the record area is large enough.

This status can also indicate a file corruption, especially in files with variable length records.

Parent topic: 20 - 39


23 The position block parameter is not 128 bytes long.

Returned as COBOL status: 9/077

This error should not be encountered if using Xfh2btr.

Parent topic: 20 - 39


24 The page size or date buffer size is invalid.

Returned as COBOL status: 9/040

Ensure that the setting of the BTRPAGE environment variable is correct. The page size must be a multiple of 512 bytes, with a maximum value of 4096. With Btrieve versions prior to 6.1, this status code can indicate that the page size of the file being opened is larger than that specified in the Largest Page Size configuration option. Configure Btrieve with the correct Largest Page Size option.

Parent topic: 20 - 39


25 The application cannot create the specified file.

Returned as COBOL status: 9/065
Parent topic: 20 - 39


26 The number of keys is invalid.

Returned as COBOL status: 9/078
The number of keys allowed for the page size is invalid. The number of key segments must be within the following limits (for Btrieve v6.x format files):
Page Size | Max. Number Key Components
512 | 8
1024 | 23
1536 | 24
2048 | 54
2560 | 54
3072 | 54
3584 | 54
4096 | 119
Parent topic: 20 - 39


27 The key position is invalid.

Returned as COBOL status: 9/139

The key field position specified is less than 1 or exceeds the defined (fixed) record length for the file. Either the key position is greater than the fixed record length, or the key position plus the key length exceeds the fixed record length.

Parent topic: 20 - 39


28 The record length is invalid.

Returned as COBOL status: 9/139

The record length specified (plus overhead for duplicates, record usage count, variable record pointer, key pointer and blank truncation information) must be less than or equal to the page size minus 8 bytes, and greater than or equal to 4 bytes.

Resolution:

Ensure that the page size is set correctly.

Parent topic: 20 - 39


29 The key length is invalid.

Returned as COBOL status: 9/078

The key length specified must be greater than 0 but less than 255 bytes. Btrieve requires that each key page in the file is large enough to hold at least 8 keys.

Resolution:

Ensure that the page size is set correctly.

Parent topic: 20 - 39


30 The file specified is not a Btrieve file.

Returned as COBOL status: 9/039
Parent topic: 20 - 39


31 The file is already extended.

Returned as COBOL status: 9/077

This status should not be encountered by Xfh2btr as files are never extended.

Parent topic: 20 - 39


32 The file cannot be extended.

Returned as COBOL status: 9/077

This status should not be encountered by Xfh2btr as files are never extended.

Parent topic: 20 - 39


33 Btrieve cannot be unloaded.

Returned as COBOL status: 9/033

This status should not be encountered by Xfh2btr.

Parent topic: 20 - 39


34 The specified extension name is invalid.

Returned as COBOL status: 9/077

This status should not be encountered by Xfh2btr as files are never extended.

Parent topic: 20 - 39


35 The application encountered a directory error.

Returned as COBOL status: 9/009

This status should not be encountered by Xfh2btr as directory operations are not used.

Parent topic: 20 - 39


36 The application encountered a transaction error.

Returned as COBOL status: 9/040

Btrieve tried to perform a Begin Transaction operation without configuring Btrieve to allow transactions. Ensure that the Btrieve Record Manager is configured to allow transactions.

Note that the Xfh2btr module will attempt to start a transaction on the first updating operation (REWRITE, WRITE, DELETE) after a file (with the WITH ROLLBACK clause specified in the SELECT statement) has been opened or after a COMMIT or ROLLBACK statement has been processed.

Parent topic: 20 - 39


37 Another transaction is active.

Returned as COBOL status: 9/077

This status should not be encountered by Xfh2btr.

Parent topic: 20 - 39


38 Btrieve enountered a transaction control file I/O error.

Returned as COBOL status: 9/007
Parent topic: 20 - 39


39 A Begin Transaction operation must precede an End/Abort Transaction operation.

Returned as COBOL status: 9/077

This status should not be encountered by Xfh2btr.

Parent topic: 20 - 39


40 - 59

  • 40 The file access request exceeds the maximum number of files allowed.
    Returned as COBOL status: 9/014
  • 41 Btrieve does not allow the attempted operation.
    Returned as COBOL status: 9/100
  • 42 A file previously opened in Accelerated mode was not closed.
    Returned as COBOL status: 9/041
  • 43 The specified record address is invalid.
    Returned as COBOL status: 23
  • 44 The specified key path is invalid.
    Returned as COBOL status: 9/139
  • 45 The specified key flags are invalid.
    Returned as COBOL status: 9/077
  • 46 Access to the requested file is denied.
    You attempted to perform an Insert, Update or Delete operation on a file that was opened in read-only mode by the application.
  • 47 The number of files opened exceeds the maximum allowed.
    Returned as COBOL status: 9/014
  • 48 The alternate collating sequence definition is invalid.
    Returned as COBOL status: 9/077
  • 49 The extended key type is invalid.
    Returned as COBOL status: 9/077
  • 50 The file owner is already set.
    Returned as COBOL status: 9/077
  • 51 The owner name is invalid.
    Returned as COBOL status: 9/037
  • 53 The language interface version is invalid.
    Returned as COBOL status: 9/053
  • 54 The variable-length portion of the record is corrupt.
    Returned as COBOL status: 9/033
  • 55 The application specified an invalid attribute for an auto-increment key.
    Returned as COBOL status: 9/077
  • 56 An index is incomplete.
    Returned as COBOL status: 9/041
  • 58 The compression buffer length is too short.
    Returned as COBOL status: 9/040
  • 59 The specified file already exists.
    Returned as COBOL status: 9/036
Parent topic: Btrieve Error Codes


40 The file access request exceeds the maximum number of files allowed.

Returned as COBOL status: 9/014
Parent topic: 40 - 59


41 Btrieve does not allow the attempted operation.

Returned as COBOL status: 9/100

This status should not be encountered by Xfh2btr.

Parent topic: 40 - 59


42 A file previously opened in Accelerated mode was not closed.

Returned as COBOL status: 9/041

The application tried to open a Btrieve v5.x file that was previously accessed in Accelerated mode by Btrieve v5.x and never successfully closed.

Another cause is that your application tried to open a v5.x format Btrieve file using a v5.x Btrieve engine, however that same file was previously accessed by a Btrieve v6.x engine, which failed to close the file successfully due to an unrecoverable error.

Parent topic: 40 - 59


43 The specified record address is invalid.

Returned as COBOL status: 23

The record address specified in a READ DIRECT (Get Direct) operation is invalid. This can occur if an invalid record address is specified when doing a READ DIRECT operation (calling Xfh2btr directly) is invalid.

Parent topic: 40 - 59


44 The specified key path is invalid.

Returned as COBOL status: 9/139

The application tried to use the Get Direct operation to establish an index path for a key whose value is null in the corresponding record. Btrieve cannot establish positioning based on a null key value.

Parent topic: 40 - 59


45 The specified key flags are invalid.

Returned as COBOL status: 9/077

This status should not be encountered if using Xfh2btr.

Parent topic: 40 - 59


46 Access to the requested file is denied.

You attempted to perform an Insert, Update or Delete operation on a file that was opened in read-only mode by the application.
Returned as COBOL status:
  • ansi 85 status: 48
  • ansi 74 status: 9/148

You attempted to perform an Insert, Update or Delete operation on a file that is flagged as read-only by the operating system.

Note that Xfh2btr attempts to perform an Update operation in order to detect record locks. Use the NODETECTLOCK directive if this error is returned and you are not performing a WRITE, DELETE or REWRITE operation.

The owner name required for updates was not specified correctly when the file was opened.

It is not possible to specify an owner name when using Xfh2btr to access Btrieve files.

Parent topic: 40 - 59


47 The number of files opened exceeds the maximum allowed.

Returned as COBOL status: 9/014

The number of files opened in Accelerated mode exceeded the number of buffers available in Btrieve's cache. In client-based versions of Btrieve prior to v6.0, you should reconfigure Btrieve both with a smaller page size configuration (to allocate more buffers) and a larger memory size option. You will not encounter this error either in v6.x client-based Btrieve, or in server-based Btrieve.

Parent topic: 40 - 59


48 The alternate collating sequence definition is invalid.

Returned as COBOL status: 9/077

This error should not be encountered as Xfh2btr does not use alternate collating sequences.

Parent topic: 40 - 59


49 The extended key type is invalid.

Returned as COBOL status: 9/077

This error should not be encountered as Xfh2btr does not use extended key types or alternate collating sequences.

Parent topic: 40 - 59


50 The file owner is already set.

Returned as COBOL status: 9/077

This error should not be encountered as Xfh2btr does not set ownership of files.

Parent topic: 40 - 59


51 The owner name is invalid.

Returned as COBOL status: 9/037

This error should not be encountered as Xfh2btr does not set ownership of files.

Parent topic: 40 - 59


53 The language interface version is invalid.

Returned as COBOL status: 9/053

This error should not be encountered as Xfh2btr uses the v5.1 language interface.

Parent topic: 40 - 59


54 The variable-length portion of the record is corrupt.

Returned as COBOL status: 9/033
Parent topic: 40 - 59


55 The application specified an invalid attribute for an auto-increment key.

Returned as COBOL status: 9/077

This error should not be encountered using Xfh2btr.

Parent topic: 40 - 59


56 An index is incomplete.

Returned as COBOL status: 9/041

An index can be damaged if a Create Index operation or a Drop Index operation is interrupted before it runs to completion. Perform a Drop Index operation to completely remove the damaged index from the file.

Parent topic: 40 - 59


58 The compression buffer length is too short.

Returned as COBOL status: 9/040

The application tried to read or write a record that is longer than the value specified for the size of the compression buffer. Reconfigure Btrieve, specifying a higher value for the Largest Compressed Record Size option.

Parent topic: 40 - 59


59 The specified file already exists.

Returned as COBOL status: 9/036

This error should not be returned using Xfh2btr.

Parent topic: 40 - 59


60 - 79

  • 60 The specified reject count has been reached.
    Returned as COBOL status: 9/074
  • 61 The work space is too small.
    Returned as COBOL status: 9/074
  • 62 The descriptor is incorrect.
    Returned as COBOL status: 9/074
  • 63 The data buffer parameter specified on an Insert Extended operation is invalid.
    Returned as COBOL status: 9/074
  • 64 The filter limit has been reached.
    Returned as COBOL status: 9/074
  • 65 The field offset is incorrect.
    Returned as COBOL status: 9/074
  • 66 The maximum number of open databases has been exceeded.
    Returned as COBOL status: 9/033
  • 67 Btrieve cannot open the SQL data dictionary files.
    Returned as COBOL status: 9/033
  • 68 Btrieve cannot perform the RI Delete Cascade operation.
    Returned as COBOL status: 9/033
  • 69 The Delete operation specified a file that is damaged.
    Returned as COBOL status: 9/033
  • 71 There is a violation of the RI definitions.
    Returned as COBOL status: 9/033
  • 72 Btrieve cannot open the RI-referenced file.
    Returned as COBOL status: 9/033
  • 73 The RI definition is out of sync.
    Returned as COBOL status: 9/033
  • 74 Btrieve aborted the transaction.
    Returned as COBOL status: 9/125
  • 75 Server routing list too small.
    Returned as COBOL status: 9/033
  • 76 There is a conflict on the referenced file.
    Returned as COBOL status: 9/033
  • 77 The application encountered a wait error.
    Returned as COBOL status: 9/068
  • 78 Btrieve detected a deadlock condition.
    Returned as COBOL status: 9/125
  • 79 A programming error occurred.
    Returned as COBOL status: 9/033
Parent topic: Btrieve Error Codes


60 The specified reject count has been reached.

Returned as COBOL status: 9/074

This error should not be returned using Xfh2btr as Extended operations are not used.

Parent topic: 60 - 79


61 The work space is too small.

Returned as COBOL status: 9/074

This error should not be returned using Xfh2btr as Extended operations are not used.

Parent topic: 60 - 79


62 The descriptor is incorrect.

Returned as COBOL status: 9/074

This error should not be returned using Xfh2btr as Extended operations are not used.

Parent topic: 60 - 79


63 The data buffer parameter specified on an Insert Extended operation is invalid.

Returned as COBOL status: 9/074

This error should not be encountered as Xfh2btr does not use the Insert Extended operation.

Parent topic: 60 - 79


64 The filter limit has been reached.

Returned as COBOL status: 9/074

This error should not be encountered as Xfh2btr does not use Extended operations.

Parent topic: 60 - 79


65 The field offset is incorrect.

Returned as COBOL status: 9/074

This error should not be encountered as Xfh2btr does not use Extended operations.

Parent topic: 60 - 79


66 The maximum number of open databases has been exceeded.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


67 Btrieve cannot open the SQL data dictionary files.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


68 Btrieve cannot perform the RI Delete Cascade operation.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


69 The Delete operation specified a file that is damaged.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


71 There is a violation of the RI definitions.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


72 Btrieve cannot open the RI-referenced file.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


73 The RI definition is out of sync.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


74 Btrieve aborted the transaction.

Returned as COBOL status: 9/125
Parent topic: 60 - 79


75 Server routing list too small.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


76 There is a conflict on the referenced file.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


77 The application encountered a wait error.

Returned as COBOL status: 9/068
Parent topic: 60 - 79


78 Btrieve detected a deadlock condition.

Returned as COBOL status: 9/125
Parent topic: 60 - 79


79 A programming error occurred.

Returned as COBOL status: 9/033
Parent topic: 60 - 79


80 - 99

  • 80 Btrieve encountered a record-level conflict.
    Returned as COBOL status: 9/068
  • 81 Btrieve encountered a lock error.
    Returned as COBOL status: 9/213
  • 82 Btrieve lost positioning.
    Returned as COBOL status: 9/146
  • 83 Btrieve attempted to read a record outside the transaction.
    Returned as COBOL status: 9/068
  • 84 The record or page is locked.
    Returned as COBOL status: 9/068
  • 85 The file is locked.
  • 86 The file table is full.
    Returned as COBOL status: 9/014
  • 87 The handle table is full.
    Returned as COBOL status: 9/014
  • 88 The application encountered an incompatible mode error.
    Returned as COBOL status: 9/065
  • 90 Redirected device table full.
    Returned as COBOL status: 9/040
  • 91 The application encountered a server error.
    Returned as COBOL status: 9/040
  • 92 The transaction table is full.
    Returned as COBOL status: 9/040
  • 93 The record lock types are incompatible.
    Returned as COBOL status: 9/077
  • 94 The application encountered a permission error.
    Returned as COBOL status: 9/037
  • 95 The session is no longer valid.
    Returned as COBOL status: 9/124
  • 96 A communications environment error occurred.
    Returned as COBOL status: 9/040
  • 97 The data buffer is too small.
    Returned as COBOL status: 9/126
  • 98 Btrieve detected an internal transaction error.
    Returned as COBOL status: 9/125
  • 99 Btrieve requester unable to access NetWare Runtime server.
    Returned as COBOL status: 9/100
Parent topic: Btrieve Error Codes


80 Btrieve encountered a record-level conflict.

Returned as COBOL status: 9/068
Parent topic: 80 - 99


81 Btrieve encountered a lock error.

Returned as COBOL status: 9/213
Parent topic: 80 - 99


82 Btrieve lost positioning.

Returned as COBOL status: 9/146

The position of the current record pointer must be re-established using a START or READ (random) operation.

Parent topic: 80 - 99


83 Btrieve attempted to read a record outside the transaction.

Returned as COBOL status: 9/068
Parent topic: 80 - 99


84 The record or page is locked.

Returned as COBOL status: 9/068
Parent topic: 80 - 99


85 The file is locked.

Returned as COBOL status:
  • 9/065 if performing an OPEN operation
  • 9/068 if performing a different operation
Parent topic: 80 - 99


86 The file table is full.

Returned as COBOL status: 9/014
Parent topic: 80 - 99


87 The handle table is full.

Returned as COBOL status: 9/014
Parent topic: 80 - 99


88 The application encountered an incompatible mode error.

Returned as COBOL status: 9/065
Parent topic: 80 - 99


90 Redirected device table full.

Returned as COBOL status: 9/040

Resolution:

Reload the Requester, specifying a larger number for either the Number of File Servers (/S) option or the Number of Mapped Drives (/R) option.

Parent topic: 80 - 99


91 The application encountered a server error.

Returned as COBOL status: 9/040
Parent topic: 80 - 99


92 The transaction table is full.

Returned as COBOL status: 9/040

Resolution:

Reconfigure Btrieve specifying a higher value for the Number of Transactions configuration option.

Parent topic: 80 - 99


93 The record lock types are incompatible.

Returned as COBOL status: 9/077

This error should not be encountered if using Xfh2btr.

Parent topic: 80 - 99


94 The application encountered a permission error.

Returned as COBOL status: 9/037
Parent topic: 80 - 99


95 The session is no longer valid.

Returned as COBOL status: 9/124
Parent topic: 80 - 99


96 A communications environment error occurred.

Returned as COBOL status: 9/040
Parent topic: 80 - 99


97 The data buffer is too small.

Returned as COBOL status: 9/126

Resolution:

Perform one or both of the following:
  • Increase the size of the message buffer by configuring Btrieve with a higher value for the Largest Record Size.
  • Reload the Btrieve Requester and specify a higher value for the Message Buffer Size.
Parent topic: 80 - 99


98 Btrieve detected an internal transaction error.

Returned as COBOL status: 9/125
Parent topic: 80 - 99


99 Btrieve requester unable to access NetWare Runtime server.

Returned as COBOL status: 9/100
Parent topic: 80 - 99


100 - 119

  • 100 No cache buffers are available.
    Returned as COBOL status: 9/033
  • 101 Insufficient operating system memory is available.
    Returned as COBOL status: 9/025
  • 102 Insufficient stack space is available.
    Returned as COBOL status: 9/025
  • 103 The chunk offset is too big.
    Returned as COBOL status: 9/025
  • 104 Btrieve does not recognize the locale.
    Returned as COBOL status: 9/025
  • 105 The file cannot be created with Variable-tail Allocation Tables (VATs).
    Returned as COBOL status: 9/025
  • 106 Btrieve cannot perform a Get Next Chunk operation.
    Returned as COBOL status: 9/025
  • 107 The application attempted to perform a chunk operation on a pre-v6.0 file.
    Returned as COBOL status: 9/025
  • 109 The application's transaction has become too complex.
    Returned as COBOL status: 9/025
Parent topic: Btrieve Error Codes


100 No cache buffers are available.

Returned as COBOL status: 9/033

Resolution:

Reconfigure Btrieve with a higher value for the Cache Allocation option.

Parent topic: 100 - 119


101 Insufficient operating system memory is available.

Returned as COBOL status: 9/025
Parent topic: 100 - 119


102 Insufficient stack space is available.

Returned as COBOL status: 9/025
Parent topic: 100 - 119


103 The chunk offset is too big.

Returned as COBOL status: 9/025

This error should not be encountered as Xfh2btr does not use the Chunk operations.

Parent topic: 100 - 119


104 Btrieve does not recognize the locale.

Returned as COBOL status: 9/025
Parent topic: 100 - 119


105 The file cannot be created with Variable-tail Allocation Tables (VATs).

Returned as COBOL status: 9/025
Parent topic: 100 - 119


106 Btrieve cannot perform a Get Next Chunk operation.

Returned as COBOL status: 9/025

This error should not be encountered as Xfh2btr does not use the Chunk operations.

Parent topic: 100 - 119


107 The application attempted to perform a chunk operation on a pre-v6.0 file.

Returned as COBOL status: 9/025

This error should not be encountered as Xfh2btr does not use the Chunk operations.

Parent topic: 100 - 119


109 The application's transaction has become too complex.

Returned as COBOL status: 9/025
Parent topic: 100 - 119


120-139

  • 130 Btrieve ran out of system locks.
    Returned as COBOL status: 9/025
  • 133 More than 5 concurrent users attempted to access the same Btrieve file.
    Returned as COBOL status: 9/025
Parent topic: Btrieve Error Codes


130 Btrieve ran out of system locks.

Returned as COBOL status: 9/025
Parent topic: 120-139


133 More than 5 concurrent users attempted to access the same Btrieve file.

Returned as COBOL status: 9/025

This error only occurs on the Developer Kit version of client-based Btrieve, which limits the number of concurrent users of a file to five engines.

Parent topic: 120-139


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:

Windows:
set EXTFH=c:\mydir\test.cfg
sets the filename to c:\mydir\test.cfg.
UNIX:
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:

Windows:

  1. The file specified by the EXTFH variable.
  2. The file extfh.cfg in the current directory.
  3. The file %COBDIR%\etc\extfh.cfg.

UNIX:

  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:

Windows:

[FOLDER:C:\\files\\acufiles]
FILESUFFIX=dat

[FOLDER:C:\\files\\rmfiles]
IDXFORMAT=21

UNIX:

[FOLDER:usr/files/acufiles]
FILESUFFIX=dat

[FOLDER:C:/files/rmfiles]
IDXFORMAT=21

sets all files in c:\files\acufiles (Windows) or usr/files/acufiles (UNIX) that do not have a suffix to .dat, and all indexed files in c:\files\rmfiles (Windows) or usr/files/rmfiles (UNIX) to an IDXFORMAT of 21.

Note: When searching along a path, if a FOLDER tag exists for a stage, settings at that stage are applied, with any conflicting settings overwritten by a subsequent stage. Using the example above, if there was also a FOLDER tag for c:\files (Windows) or usr/files (UNIX) that sets IDXFORMAT 2, the subsequent setting of IDXFORMAT 21 would overwrite this.
Important: If you include a path to a file in the tag, you must enter the "\" character twice in order for the configuration file to be parsed correctly. For example, instead of
[C:\SITETEST\EXTFH\TEST2.dat]

you would need to enter

[C:\\SITETEST\\EXTFH\\TEST2.dat]

This applies to Windows environments (local development) only.

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:

Windows:
[INTERNAL:$myfile\outfile.dat]
IDXFORMAT=8
UNIX: .
[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:

Windows:
SELECT MYDATA ASSIGN TO '\directory\subdirectory\datadirectory\myfile'
UNIX: .
SELECT MYDATA ASSIGN TO '/directory/subdirectory/datadirectory/myfile'

you cannot use the INTERNAL option in the configuration file. The literal value in the SELECT statement must be replicated [inside square brackets] in the configuration file.

Filenames can use paths and DD_mappings but not wildcards or logic names. If you set the File Handler configuration option BASENAME=ON, you can specify filenames without paths. Note that the name of a file must match the mapped name in your program.

Parent topic: Format of the Configuration File
Related reference
Configuration File Options


Filename tag

Settings that apply to a specific file are listed under the specific filename tag; for example:

[file1.dat]
IDXFORMAT=17
[file2.dat]
IDXFORMAT=21

sets file1.dat to IDXFORMAT 17 and file2.dat to IDXFORMAT 21.

Comments:

To enable the use of filenames (without a pathname), set BASENAME=ON in the [XFH-DEFAULT] section.

When you use the filename tag, the path to the current directory is assumed, and if a FOLDER tag exists for any folder along the path, settings for that tag are applied. For example, if you have the following file assignment:

SELECT myFile ASSIGN TO 'file1.dat'

and your application is run in the directory c:\files\mffiles (Windows) orusr/files/mffiles (UNIX), then if you have FOLDER tags for the following locations in your configuration file, the settings in them are applied:

Windows:

  • c:\
  • c:\files
  • c:\files\mffiles

UNIX:

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

Windows:

[c:\\acufiles\\file1.dat]
IDXFORMAT=17
[c:\\rmfiles\\file1.dat]
IDXFORMAT=21
Important: If you include a path to a file in the tag, you must enter the "\" character twice in order for the configuration file to be parsed correctly. For example, instead of
[C:\SITETEST\EXTFH\TEST2.dat]

you would need to enter

[C:\\SITETEST\\EXTFH\\TEST2.dat]

This applies to Windows environments (local development) only.

UNIX:

[usr/acufiles/file1.dat]
IDXFORMAT=17
[usr/rmfiles/file1.dat]
IDXFORMAT=21

sets file1.dat in c:\files\acufiles (Windows) or usr/files/acufiles (UNIX) to IDXFORMAT 17 and file1.dat in c:\files\rmfiles (Windows) or usr/files/rmfiles (UNIX) 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.
  • USEVSAMKEYDEFS
    Use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.
  • WRITELINE
    The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.
  • WRITETHRU
    The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.
Parent topic: Configuration File


ACUFH

Enables or disables the use of the ACU file handler (ACUFH).

Data files detected to be of ACUCOBOL-GT type are directed to ACUFH; data files detected to not be of ACUCOBOL-GT type are processed as normal.

Syntax:

ACUFH = { ON } { OFF }

Parameters:

ON
All types of ACUCOBOL-GT data file are handled by the ACUFH.
OFF
No data files are handled by the ACUFH, even if INTEROP=ACU or IDXFORMAT=17 is set.

Properties:

Default: ON

Comments:

To use ACUFH when running under Enterprise Server, you must also set ESACUFH=ON; this option is OFF by default.

Parent topic: Configuration File Options
Related reference
ESACUFH


ASCIIMAINFRAMEPRINT

The ASCIIMAINFRAMEPRINT option specifies whether to use ASCII printer control characters when CHARSET is set to ASCII and the FILETYPE is set to mainframe print format where “WRITE BEFORE ADVANCING SYNTAX” is used.

Syntax:

ASCIIMAINFRAMEPRINT = { ON } { OFF }

Parameters:

ON
Printer Control Characters are in ASCII when CHARSET is set to ASCII.
OFF
Printer Control Characters are in EBCDIC where CHARSET is set to ASCII.

Properties:

Default: OFF

Comments:

You use an entry in the File Handler Configuration File (EXTFH.cfg) to enable the printer control characters to be ASCII when the CHARSET is set to ASCII:

[xfh-default]
 ASCIIMAINFRAMEPRINT=ON

The default value is OFF.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

Parent topic: Configuration File Options


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
Btrieve with ANSI (Windows) or Reserved (UNIX)
6
Btrieve without ANSI (Windows) or Reserved (UNIX)
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
Btrieve with ANSI (Windows) or Reserved (UNIX)
6
Btrieve without ANSI (Windows) or Reserved (UNIX)
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: 0 (Windows) or 1 (UNIX)

Comments:

IDXNAMETYPE only affects the data file for Vision files.

The name of the index file (if present) is derived from that of the data file. For example, if the data file name presented to the File Handler is abc.def, the options shown above give the following data and index filenames:

0 | abc.def and abc.idx
1 | abc.def and abc.def.idx
2 | abc.def.dat and abc.def.idx

If the data file name is abc and FILESUFFIX=dat, the following data and index filenames are given for IDXNAMETYPE=3:

3 abc.dat and abc.idx
Parent topic: Configuration File Options
Related reference
INTEROP
FILESUFFIX


IGNORELOCK

The IGNORELOCK option specifies whether to ignore locks.

Syntax:

IGNORELOCK = { ON } { INPUT } { OFF }

Parameters:

ON
Ignore all locks.
INPUT
Ignore locks only when reading files open for input.
OFF
Do not ignore locks.

Properties:

Default: OFF
Parent topic: Configuration File Options


INDEXCOUNT

The INDEXCOUNT option specifies the number of index nodes to be cached for an indexed file.

Syntax:

INDEXCOUNT = node-count

Parameters:

node-count
The number of nodes to be cached. It can be any value between 4 and 255.

Properties:

Default: 32
Parent topic: Configuration File Options


INDEXFILE

The INDEXFILE option maps the name of the index file (for those indexed file formats that have a separate index file). This name can include full path information.

Syntax:

INDEXFILE = name

Parameters:

name
The name of the index file.

Properties:

Default: The name of the index file is derived from the name of the data file by adding the extension .idx (see also IDXNAMETYPE).
Parent topic: Configuration File Options
Related information
IDXNAMETYPE


INSERTNULL

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL option determines whether to insert NULL (x"00") characters before non-printable characters. The option also determines whether to strip out those NULL characters during READ operations.

Syntax:

INSERTNULL = { ON } { OFF }

Parameters:

ON
Insert NULL characters before non-printable characters. Strip out NULL characters during READ operations.
OFF
Do not insert NULL characters before non-printable characters. Do not strip out NULL characters during READ operations.

Properties

Default: ON

Comments:

INSERTNULL takes precedence over the N run-time switch.

If you do not set INSERTNULL, the setting of the N run-time switch determines whether or not NULL characters are inserted before non-printable characters.

Parent topic: Configuration File Options


INSERTTAB

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB option determines whether to replace sequences of spaces with TAB characters.

Syntax:

INSERTTAB = { ON } { OFF }

Parameters:

ON
Replace sequences of spaces with TAB characters.
OFF
Do not replace sequences of spaces with TAB characters.

Properties:

Default: OFF

Comments:

The setting of the T switch can affect the default setting.

Parent topic: Configuration File Options
Related information
EXPANDTAB


INTEROP

The INTEROP option determines which file handler is used for all file organizations in a given folder.

Syntax:

INTEROP = {ACU} {RM}

Parameters:

Note: These options are case sensitive.
ACU
All Vision file organizations in the specified folder (and sub-folders) use Vision, the ACUCOBOL-GT file handler.
RM
All file organizations in the specified folder (and sub-folders) use RMFM, the RM/COBOL file handler.

Example:

In the following excerpt of the configuration file, all file organizations in the folder c:\files\acufiles (Windows) or usr/files/acufiles (UNIX) use the Vision file handler, and all file organizations in the folder c:\files\rmfiles (Windows) or usr/files/rmfiles (UNIX) use the RMFM file handler:

Windows:

[XFH-DEFAULT]
[FOLDER:C:\\files\\acufiles]
INTEROP=ACU

[FOLDER:C:\\files\\rmfiles]
INTEROP=RM
Important: If you include a path to a file in the tag, you must enter the "\" character twice in order for the configuration file to be parsed correctly. For example, instead of
[C:\SITETEST\EXTFH\TEST2.dat]

you would need to enter

[C:\\SITETEST\\EXTFH\\TEST2.dat]

This applies to Windows environments (local development) only.

UNIX:

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

This option overrides the XFHLOG environment variable if both are set.

Use the program cobfhprint to create and display a text version of the log file:

cobfhprint filename
Parent topic: Configuration File Options
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: ON (Windows) or OFF (UNIX)

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 (UNIX) or 0D0A (Windows).
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: 0D0A (Windows) or 0A (UNIX).
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


USEVSAMKEYDEFS

Use the keys defined in the catalog via the JCL and IDCAMS instead of the keys defined in the executing program.

Syntax:

USEVSAMKEYDEFS = { ON } { OFF }

Parameters:

ON
Use the catalog's key definitions.
OFF
Use executing program's key definitions.

Properties:

Default: ON
Parent topic: Configuration File Options


WRITELINE

The WRITELINE parameter determines whether mainframe or PC behavior is used for WRITE record.

Syntax:

WRITELINE = { ON } { OFF }

Parameters:

ON
Mainframe behavior is used for WRITE record.
OFF
PC behavior is used for WRITE record.

Properties:

Default: OFF

Comments:

Set WRITELINE=OFF if you want PC print behavior for WRITELINE when using mainframe dialects.

Parent topic: Configuration File Options


WRITETHRU

The WRITETHRU option determines whether modifications to a file are written out to disk immediately or buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.

Syntax:

WRITETHRU = { ON } { OFF }

Parameters:

ON
Write out all modifications to disk immediately.
OFF
Flush modifications later.

Properties:

Default: OFF

Comments:

You can obtain greater security, at the cost of significantly reduced performance, by setting this parameter to ON.

Parent topic: Configuration File Options


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
Windows: Reserved. Must be set to binary zeros.
UNIX: 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"
5 | btrieve-ansi (applies to Windows environments only)
6 | btrieve-non-ansi (applies to Windows environments only)
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 (applies to UNIX environments only)
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 API
  • FSVIEW Command Line
Parent topic: File Handling Reference


FSVIEW API

  • FSVIEW Datablock
  • FSVW2 Datablock
  • FSV-C
    Initializes the FSVIEW module.
  • FSV-C-add-login-user
    This callback adds a temporary Fileshare user for the lifetime of the Fileshare process.
  • FSV-C-add-to-dbase-list
    This callback iteratively processes lists of database information.
  • FSV-C-add-to-user-list
    This callback iteratively processes lists of users.
  • FSV-C-add-to-file-list
    This callback iteratively processes lists of files.
  • FSV-C-auto-rename-logfile
    Automatically renames the log file.
  • FSV-C-shutdown-server
    Shuts down the currently accessed server.
  • FSV-C-change-server
    Changes the currently accessed server.
  • FSV-C-check-password
    Sets the FSVIEW password for a specific server.
  • FSV-C-close-file
    Closes a specific file for all users.
  • FSV-C-close-user-file
    Closes a file for a specific user.
  • FSV-C-get-comms-info
    Gets the communications information for the currently accessed server.
  • FSV-C-get-database-info
    Gets the database information for the currently accessed server.
  • FSV-C-get-files-users
    Gets the logged-on user information for a specific file.
  • FSV-C-get-log-file-info
    Gets the log file information for the currently accessed server.
  • FSV-C-get-open-files
    Gets the information about the files that are open for the server being currently accessed.
  • FSV-C-get-open-user-files
    Gets the open files for a specific user.
  • FSV-C-get-server-info
    Gets the server information for the currently accessed server.
  • FSV-C-get-user-info
    Gets the information about the logged-on users for the server being currently accessed.
  • FSV-C-logoff-user
    Logs off a specific user.
  • FSV-C-long-password
    Initializes the FSVIEW module and enables long username and password support.
  • FSV-C-rename-logfile
    Renames the log file.
  • FSV-C-toggle-open-trace
    Toggles the XFH Open trace.
  • FSV-C-toggle-trace
    Toggles the FS trace.
  • FSV-C-toggle-XFH-trace
    Toggles the XFH trace.
  • FSVIEW-C-TERM
    Exits from FSVIEW.
Parent topic: FSView


FSVIEW Datablock

FSVIEW calls make extensive use of the FSVIEW datablock. Add the following data definitions to the datablock in your FSVIEW calls:

      *Server Information
          fsvw-server-name                  pic x(20).
          fsvw-server-startup               pic x(20).
          fsvw-server-usage                 pic x(4).
          fsvw-trace-on                     pic x comp-x.
      *Log file Information
          fsvw-log-filename                 pic x(255).
          fsvw-timings-table redefines fsvw-log-filename
             fsvw-timing-fs                 Reserved
             fsvw-timing-receiveall         Reserved
             fsvw-timing-query              Reserved
             fsvw-timing-comms-other        Reserved
             fsvw-timing-fh                 Reserved
             fsvw-timing-io-cnt             pic x(4) comp-x.

          fsvw-log-filename-size            pic x(2) comp-x.
          fsvw-log-filesize                 pic x(16).
          fsvw-disk-space                   pic x(16).
          fsvw-disk-size                    pic x(16).
      *Database Information
          fsvw-dbase-filename-size          pic x(2) comp-x.
          fsvw-dbase-filesize               pic x(16).
      *Various flags
          fsvw-exit-flg                     pic 9.
          fsvw-exit-flg-true                value 1.
          fsvw-function                     pic 9(2).
          fsvw-status-key-1                 pic x(2) comp-x.
          fsvw-status-key-2                 pic x(2) comp-x.
          fsvw-date-format                  pic x.
          fsvw-fsview-user-id               pic x(5).
      *Windows show flags
          fsvw-log-win-flg                  Reserved
             fsvw-log-win-flg-true          Reserved
          fsvw-dbase-win-flg                Reserved
             fsvw-dbase-win-flg-true        Reserved
          fsvw-user-win-flg                 Reserved
             fsvw-user-win-flg-true         Reserved
          fsvw-user-file-win-flg            Reserved
             fsvw-user-file-win-flg-true    Reserved
          fsvw-file-info-win-flg            Reserved
             fsvw-file-info-win-flg-true    Reserved
          fsvw-file-user-win-flg            Reserved
             fsvw-file-user-win-flg-true    Reserved
          fsvw-comms-win-flg                Reserved
             fsvw-comms-win-flg-true        Reserved
          fsvw-password-win-flg             Reserved
             fsvw-password-win-flg-true     Reserved
          fsvw-change-srvr-win-flg          Reserved
             fsvw-change-srvr-win-flg-true  Reserved
          fsvw-logid-needed-flg             Reserved
             fsvw-logid-needed-flg-true     Reserved
          fsvw-comms-too-small-flg          Reserved
             fsvw-comms-too-small-flg-true  Reserved
      *
          fsvw-insert-list-box
             fsvw-insert-list-box-item      occurs 10.
                fsvw-list-box-data          pic x(255).
      *User details
          fsvw-number-of-users              pic 9(5).
          fsvw-peak-number-of-users         pic 9(5).
          fsvw-logoff-id                    pic x(5).
          fsvw-file-list-user-id            pic x(5).
          fsvw-extracted-user-id            pic x(5).
      *
          fsvw-number-files-open            pic 9(10).
          fsvw-peak-files-open              pic 9(10).
      *Various fs state flags
          fsvw-user-not-found-flg           Reserved
             fsvw-user-not-found-flg-true   Reserved
          fsvw-invalid-password-flg         Reserved
             fsvw-invalid-password-flg-true Reserved
          fsvw-file-not-found-flg           Reserved
             fsvw-file-not-found-flg-true   Reserved
          fsvw-no-server-flg                Reserved
             fsvw-no-server-flg-true        Reserved
          fsvw-shutdown-already-flg         Reserved
             fsvw-shutdown-already-flg-true Reserved
          fsvw-rename-error-flg             Reserved
             fsvw-rename-error-flg-true     Reserved
          fsvw-rename-clash                 Reserved
             fsvw-rename-clash-true         Reserved
      *
          fsvw-comms-module-line2           pic x(42).
          fsvw-comms-module-line1           pic x(42).
          fsvw-send-failures                pic 9(10).
          fsvw-comms-busy                   pic 9(10).
          fsvw-comms-timeouts               pic 9(10).
      *Miscellaneous
          fsvw-filename                     Reserved
          fsvw-start-pt                     Reserved
          fsvw-user-tbl-z                   Reserved
          fsvw-server-error-flg             Reserved
             fsvw-server-error-flg-true     Reserved
      *Password check data
          fsvw-supervisor-mode              pic 9.
             fsvw-supervisor-mode-true      value 1.
          fsvw-password                     pic x(20).
          fsvw-title                        pic x(255).
          fsvw-help-topic                   pic 9(2).
          fsvw-user-id                      pic x(20).
          fsvw-user-password                pic x(20).
          fsvw-version                      pic x(8).

This data definition copybook file (fsdatab.cpy) can be found in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/copylib (UNIX).

Parent topic: FSVIEW API


FSVW2 Datablock

When FSVIEW is initialized using FSC-C-long-password it makes extensive use of the FSVW2 datablock.

This data definition copybook file (fsdatabv2.cpy) can be found in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/copylib (UNIX).

Add the following data definitions to the datablock in your FSVIEW calls:

01 fsvw2-data-block.
      *server information
          03 fsvw2-server-name                pic x(20).
          03 fsvw2-server-startup             pic x(20).
          03 fsvw2-server-usage               pic x(4).
          03 fsvw2-trace-on                   pic x comp-x.
      *log file information
          03 fsvw2-log-filename               pic x(255).
          03 fsvw2-timings-table redefines fsvw2-log-filename.
             05  fsvw2-timing-fs              pic x comp-x.
             05  fsvw2-timing-receiveall      pic x comp-x.
             05  fsvw2-timing-query           pic x comp-x.
             05  fsvw2-timing-comms-other     pic x comp-x.
             05  fsvw2-timing-fh              pic x comp-x.
             05  fsvw2-timing-io-cnt          pic x(4) comp-x.

          03 fsvw2-log-filename-size          pic x(2) comp-x.
          03 fsvw2-log-filesize               pic x(16).
          03 fsvw2-disk-space                 pic x(16).
          03 fsvw2-disk-size                  pic x(16).
      *database information
          03 fsvw2-dbase-filename-size        pic x(2) comp-x.
          03 fsvw2-dbase-filesize             pic x(16).
      *various flags
          03 fsvw2-exit-flg                   pic 9.
             88 fsvw2-exit-flg-true           value 1.
          03 fsvw2-function                   pic 9(2).
          03 fsvw2-status-key-1               pic x(2) comp-x.
          03 fsvw2-status-key-2               pic x(2) comp-x.
          03 fsvw2-date-format                pic x.
          03 fsvw2-fsview-user-id             pic x(5).
      *windows show flags
          03 fsvw2-log-win-flg                pic 9.
             88 fsvw2-log-win-flg-true        value 1.
          03 fsvw2-dbase-win-flg              pic 9.
             88 fsvw2-dbase-win-flg-true      value 1.
          03 fsvw2-user-win-flg               pic 9.
             88 fsvw2-user-win-flg-true       value 1.
          03 fsvw2-user-file-win-flg          pic 9.
             88 fsvw2-user-file-win-flg-true  value 1.
          03 fsvw2-file-info-win-flg          pic 9.
             88 fsvw2-file-info-win-flg-true  value 1.
          03 fsvw2-file-user-win-flg          pic 9.
             88 fsvw2-file-user-win-flg-true  value 1.
          03 fsvw2-comms-win-flg              pic 9.
             88 fsvw2-comms-win-flg-true      value 1.
          03 fsvw2-password-win-flg           pic 9.
             88 fsvw2-password-win-flg-true   value 1.
          03 fsvw2-change-srvr-win-flg        pic 9.
             88 fsvw2-change-srvr-win-flg-true value 1.
          03 fsvw2-logid-needed-flg           pic 9.
             88 fsvw2-logid-needed-flg-true   value 1.
          03 fsvw2-comms-too-small-flg        pic 9.
             88 fsvw2-comms-too-small-flg-true value 1.
      *
          03 fsvw2-insert-list-box.
             04 fsvw2-insert-list-box-item    occurs 10.
                05 fsvw2-list-box-data        pic x(255).
      *user details
          03 fsvw2-number-of-users            pic 9(5).
          03 fsvw2-peak-number-of-users       pic 9(5).
          03 fsvw2-logoff-id                  pic x(5).
          03 fsvw2-file-list-user-id          pic x(5).
          03 fsvw2-extracted-user-id          pic x(5).
      *
          03 fsvw2-number-files-open          pic 9(10).
          03 fsvw2-peak-files-open            pic 9(10).
      *various fs state flags
          03 fsvw2-user-not-found-flg         pic 9.
             88 fsvw2-user-not-found-flg-true value 1.
          03 fsvw2-invalid-password-flg       pic 9.
             88 fsvw2-invalid-password-flg-true value 1.
          03 fsvw2-file-not-found-flg         pic 9.
             88 fsvw2-file-not-found-flg-true value 1.
          03 fsvw2-no-server-flg              pic 9.
             88 fsvw2-no-server-flg-true      value 1.
          03 fsvw2-shutdown-already-flg       pic 9.
             88 fsvw2-shutdown-already-flg-true value 1.
          03 fsvw2-rename-error-flg           pic 9.
             88 fsvw2-rename-error-flg-true   value 1.
          03 fsvw2-rename-clash               pic 9.
             88 fsvw2-rename-clash-true       value 1.
      *
          03 fsvw2-comms-module-line2         pic x(42).
          03 fsvw2-comms-module-line1         pic x(42).
          03 fsvw2-send-failures              pic 9(10).
          03 fsvw2-comms-busy                 pic 9(10).
          03 fsvw2-comms-timeouts             pic 9(10).
      *misc
          03 fsvw2-filename                   pic x(255).
          03 fsvw2-start-pt                   pic x(2) comp-x.
          03 fsvw2-user-tbl-z                 pic x(2) comp-x.
          03 fsvw2-server-error-flg           pic 9.
             88 fsvw2-server-error-flg-true   value 1.
      *password check data
          03 fsvw2-supervisor-mode            pic 9.
             88 fsvw2-supervisor-mode-true    value 1.
          03 fsvw2-password                   pic x(100).
          03 fsvw2-title                      pic x(255).
          03 fsvw2-help-topic                 pic 9(2).
          03 fsvw2-version                    pic x(8).
          03 fsvw2-user-id-len                pic x(2) comp-5 value 20.
          03 fsvw2-user-password-len          pic x(2) comp-5 value 20.
          03 fsvw2-user-id.
              05
                       occurs 20 to 78-user-name-length
                       times depending on fsvw2-user-id-len pic x.
          03 fsvw2-user-password.
              05
                       occurs 20 to 78-user-password-length
                       times depending on fsvw2-user-password-len pic
Parent topic: FSVIEW API


FSV-C

Initializes the FSVIEW module.

Syntax:

call FSV-C

Parameters:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSVIEW-C-TERM


FSV-C-add-login-user

This callback adds a temporary Fileshare user for the lifetime of the Fileshare process.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

FSV-C-add-login-user  using      l-new-user-name
                                        l-new-password-name

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

FSV-C-add-login-user  using      l2-new-user
                                        l2-new-user-password
                                        l2-user-name-length
                                        l2-user-password-length

Parameters:

Parameters when the fsview has been initialized using FSV-C:

l-new-user-name
pic x(20)
l-new-password
pic x(20)

Parameters when the fsview has been initialized using FSC-C-long-password:

l2-new-user
pic x(100)
l2-new-user-password
pic x(100)
l2-user-name-length
pic x(2) comp-x
l2-user-password-length
pic x(2) comp-x

On Entry:

When the fsview has been initialized using FSV-C:

l-new-user-name
The new user name
l-new-password
The password associated with the new user

When the fsview has been initialized using FSC-C-long-password:

l2-new-user
The new long user name
l2-new-user-password
The long password associated with the new user
l2-user-name-length
Specifies the new long username length
l2-user-password-length
Specifies the new long password length

On Exit:

None.

Comments:

Only applicable if you have security enabled. The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API


FSV-C-add-to-dbase-list

This callback iteratively processes lists of database information.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

FSV-C-add-to-dbase-list list using      number-of-entries
                                        fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

FSV-C-add-to-dbase-list list using      number-of-entries
                                        fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

number-of-entries
pic xx comp-x.
fsvw-data-block
A group item defined as:
fsvw-insert-list-box-item ( i )
occurs 10.

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

number-of-entries
pic xx comp-x.
fsvw2-data-block
A group item defined as:
fsvw2-insert-list-box-item ( i )
occurs 10.

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

When fsview has been initialized using FSV-C:

number-of-entries
The number of entries
fsvw-insert-list-box-item ( i )
The user information for a specific user

When fsview has been initialized using FSV-C-long-password:

number-of-entries
The number of entries
fsvw2-insert-list-box-item ( i )
The user information for a specific user

On Exit:

None.

Comments:

RETURN-CODE must be set to 0 before returning.

Parent topic: FSVIEW API
Related reference
FSV-C-get-database-info


FSV-C-add-to-user-list

This callback iteratively processes lists of users.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

FSV-C-add-to-user-list using      number-of-entries
                                  fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

FSV-C-add-to-user-list using      number-of-entries
                                  fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

number-of-entries
pic xx comp-x.
fsvw-data-block
A group item defined as:
fsvw-insert-list-box-item ( i )
occurs 10.

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

number-of-entries
pic xx comp-x.
fsvw2-data-block
A group item defined as:
fsvw2-insert-list-box-item ( i )
occurs 10.

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

When fsview has been initialized using FSV-C:

number-of-entries
The number of entries.
fsvw-insert-list-box-item ( i )
The user information for a specific user.

When fsview has been initialized using FSV-C-long-password:

number-of-entries
The number of entries.
fsvw2-insert-list-box-item ( i )
The user information for a specific user.

On Exit:

None.

Comments:

RETURN-CODE must be set to 0 before returning.

Parent topic: FSVIEW API
Related reference
FSV-C-get-files-users


FSV-C-add-to-file-list

This callback iteratively processes lists of files.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

FSV-C-add-to-file-list using      number-of-entries
                                  fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

FSV-C-add-to-file-list using      number-of-entries
                                  fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

number-of-entries
pic xx comp-x.
fsvw-data-block
A group item defined as:
fsvw-insert-list-box-item ( i )
occurs 10

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

When fsview has been initialized using FSV-C:

number-of-entries
The number of entries.
fsvw-insert-list-box-item ( i )
The user information for a specific user.

When fsview has been initialized using FSV-C-long-password:

number-of-entries
The number of entries.
fsvw2-insert-list-box-item ( i )
The user information for a specific user.

On Exit:

None.

Comments:

RETURN-CODE must be set to 0 before returning.

Parent topic: FSVIEW API
Related reference
FSV-C-get-open-user-files
FSV-C-get-open-files


FSV-C-auto-rename-logfile

Automatically renames the log file.

Syntax:

call FSV-C-auto-rename-logfile

Parameters:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-get-log-file-info
FSV-C-rename-logfile


FSV-C-shutdown-server

Shuts down the currently accessed server.

Syntax:

call FSV-C-shutdown-server

Parameters:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-change-server
FSV-C-get-server-info
FSV-C-get-database-info
FSV-C-check-password
FSV-C-get-comms-info


FSV-C-change-server

Changes the currently accessed server.

Syntax:

When the fsview has been initialized using FSV-C it uses the following syntax:

call FSV-C-change-server using      l-server-name
                                    l-user-name
                                    l-server-password

When the fsview has been initialized using FSC-C-long-password it uses the following syntax:

call FSV-C-change-server using      l2-server-name
                                    l2-server-userid
                                    l2-server-password
                                    l2-user-name-length
                                    l2-user-password-length

Parameters:

Parameters when fsview has been initialized using FSV-C:

l-server-name
pic x(20).
l-user-name
pic x(20).
l-server-password
pic x(20).

Parameters when fsview has been initialized using FSV-C-long-password:

l2-server-name
pic x(20).
l2-server-userid
pic x(100).
l2-server-password
pic x(100).
l2-user-name-length
pic x(2) comp-x.
l2-user-password-length
pic x(2) comp-x.

On Entry:

When the fsview has been initialized using FSV-C:

l-server-name
The name of the server
l-user-name
The user ID
l-server-password
The password associated with the user ID

Parameters to use when FSV-C-long-password has been used to initialize the fsview:

l2-server-name
The name of the server
l2-server-userid
The server user ID
l2-server-password
The long password associated with the user ID
l2-user-name-length
Username length
l2-user-password-length
User password length

On Exit:

None.

Comments:

You need to set l-user-name and l-server-password only if you have Fileshare

security enabled.

The success of the call can be checked by examining RETURN-CODE. In the event of a password error, the error message Access Denied is returned.

Parent topic: FSVIEW API
Related reference
FSV-C-get-server-info
FSV-C-get-database-info
FSV-C-check-password
FSV-C-get-comms-info
FSV-C-shutdown-server


FSV-C-check-password

Sets the FSVIEW password for a specific server.

Syntax:

When the fsview has been initialized using FSV-C it uses the following syntax:

call FSV-C-check-password using      l-server-password

When the fsview has been initialized using FSC-C-long-password it uses the following syntax:

call FSV-C-check-password using      l2-server-password
                                       l2-user-password-length

Parameters:

Parameters when fsview has been initialized using FSV-C:

l-server-password
pic x(20)

Parameters when fsview has been initialized using FSV-C-long-password:

l2-server-password
pic x(100)
l2-user-password-length
pic x(2) comp-x

On Entry:

When fsview has been initialized using FSV-C:

l-server-password
The FSVIEW password

When fsview has been initialized using FSV-C-long-password:

l2-server-password
The FSVIEW long password
l2-user-password-length
The FSVIEW long password length

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-change-server
FSV-C-get-server-info
FSV-C-get-database-info
FSV-C-get-comms-info
FSV-C-shutdown-server


FSV-C-close-file

Closes a specific file for all users.

Syntax:

call FSV-C-close-file using      l-filename

Parameters:

l-filename
pic x(260)

On Entry:

l-filename
The name of a file. The name must contain the full path.

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-logoff-user
FSV-C-get-open-user-files
FSV-C-close-user-file
FSV-C-get-files-users
FSV-C-get-user-info


FSV-C-close-user-file

Closes a file for a specific user.

Syntax:

call FSV-C-close-user-file using      l-user-id
                                      l-filename

Parameters:

l-user-id
pic 9(5)
l-filename
pic x(260)

On Entry:

l-user-id
A valid user ID
l-filename
The name of a file. The name must contain the full path.

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-close-file
FSV-C-logoff-user
FSV-C-get-open-user-files
FSV-C-get-files-users
FSV-C-get-user-info


FSV-C-get-comms-info

Gets the communications information for the currently accessed server.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

call FSV-C-get-comms-info using      fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

call FSV-C-get-comms-info using      fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

fsvw-comms-module-line1
pic x(42).
fsvw-comms-module-line2
pic x(42).
fsvw-send-failures
pic 9(10).
fsvw-comms-busy
pic 9(10).
fsvw-comms-timeouts
pic 9(10).

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

fsvw2-comms-module-line1
pic x(42).
fsvw2-comms-module-line2
pic x(42).
fsvw2-send-failures
pic 9(10).
fsvw2-comms-busy
pic 9(10).
fsvw2-comms-timeouts
pic 9(10).

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

None.

On Exit:

When fsview has been initialized using FSV-C:

fsvw-comms-module-line1
A list of the communications modules in use.
fsvw-comms-module-line2
A list of the communications modules in use. fsvw-comms-module-line2 is an extension of fsvw-comms-module-line1.
fsvw-send-failures
The number of send failures.
fsvw-comms-busy
The number of times communications reported status busy.
fsvw-comms-timeouts
The number of times communications reported timeouts

When fsview has been initialized using FSV-C-long-password:

fsvw2-comms-module-line1
A list of the communications modules in use.
fsvw2-comms-module-line2
A list of the communications modules in use. fsvw-comms-module-line2 is an extension of fsvw-comms-module-line1.
fsvw2-send-failures
The number of send failures.
fsvw2-comms-busy
The number of times communications reported status busy.
fsvw2-comms-timeouts
The number of times communications reported timeouts

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-change-server
FSV-C-get-server-info
FSV-C-get-database-info
FSV-C-check-password
FSV-C-shutdown-server


FSV-C-get-database-info

Gets the database information for the currently accessed server.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

call FSV-C-get-database-info using      fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

call FSV-C-get-database-info using      fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

fsvw-dbase-filename
pic x(255).
fsvw-dbase-filename-size
pic x(2) comp-x.
fsvw-dbase-filesize
pic x(16).

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

fsvw2-dbase-filename
pic x(255).
fsvw2-dbase-filename-size
pic x(2) comp-x.
fsvw2-dbase-filesize
pic x(16).

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

None.

On Exit:

When fsview has been initialized using FSV-C:

fsvw-dbase-filename
The database file name of the currently selected server.
fsvw-dbase-filename-size
Length of the name stored in fsvw-dbase-filename

A value of 0 (zero) means that no database in use.

fsvw-dbase-filesize
The size of the database file.

When fsview has been initialized using FSV-C-long-password:

fsvw2-dbase-filename
The database file name of the currently selected server.
fsvw2-dbase-filename-size
Length of the name stored in fsvw-dbase-filename

A value of 0 (zero) means that no database in use.

fsvw2-dbase-filesize
The size of the database file.

Comments:

This call does not directly return information to the calling program but makes repeated calls back to a user-defined call. Up to 10 entries at a time are sent to the callback. You must provide the callback specified in the FSVIEW function FSV-C-add-to-dbase-list.

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-add-to-dbase-list
FSV-C-change-server
FSV-C-get-server-info
FSV-C-check-password
FSV-C-get-comms-info
FSV-C-shutdown-server


FSV-C-get-files-users

Gets the logged-on user information for a specific file.

Syntax:

call FSV-C-get-files-users using      l-filename

Parameters:

l-filename
pic x(260)

On Entry:

l-filename
The name of a file. The name must contain the full path.

On Exit:

None.

Comments:

This call does not directly return information to the calling program but makes repeated calls back to a user-defined call. Up to 10 entries at a time will be sent to the callback. You must provide the callback specified in the FSVIEW function FSV-C-add-to-user-list.

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-add-to-user-list
FSV-C-close-file
FSV-C-logoff-user
FSV-C-get-open-user-files
FSV-C-close-user-file
FSV-C-get-user-info


FSV-C-get-log-file-info

Gets the log file information for the currently accessed server.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

call FSV-C-get-log-file-info using      fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

call FSV-C-get-log-file-info using      fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

fsvw-log-filename
pic x(255).
fsvw-log-filename-size
pic x(2) comp-x.
fsvw-log-filesize
pic x(16).
fsvw-disk-space
pic x(16).
fsvw-disk-size
pic x(16).

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

fsvw2-log-filename
pic x(255).
fsvw2-log-filename-size
pic x(2) comp-x.
fsvw2-log-filesize
pic x(16).
fsvw2-disk-space
pic x(16).
fsvw2-disk-size
pic x(16).

See the topic FSVIEW Datablock for a complete definition of fsvw-data-block.

On Entry:

None.

On Exit:

When the fsview has been initialized using FSV-C:

fsvw-log-filename
The log file name of the server currently selected.
fsvw-log-filename-size
Length of the name stored in fsvw-log-filename

A value of 0 (zero) means that no log file is in use.

fsvw-log-filesize
The size of the log file.
fsvw-disk-space
The amount of space remaining on the disk.
fsvw-disk-size
The size of the disk.

When the fsview has been initialized using FSC-C-long-password:

fsvw-log-filename
The log file name of the server currently selected.
fsvw-log-filename-size
Length of the name stored in fsvw-log-filename

A value of 0 (zero) means that no log file is in use.

fsvw-log-filesize
The size of the log file.
fsvw-disk-space
The amount of space remaining on the disk.
fsvw-disk-size
The size of the disk.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-auto-rename-logfile
FSV-C-rename-logfile


FSV-C-get-open-files

Gets the information about the files that are open for the server being currently accessed.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

call FSV-C-get-open-files using fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

call FSV-C-get-open-files using fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

fsvw-log-filename
pic x(255).
fsvw-filename-size
pic x(16).
fsvw-log-filesize
pic x(16).
fsvw-disk-space
pic x(16).
fsvw-disk-size
pic x(16).

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

fsvw2-log-filename
pic x(255).
fsvw2-filename-size
pic x(16).
fsvw2-log-filesize
pic x(16).
fsvw2-disk-space
pic x(16).
fsvw2-disk-size
pic x(16).

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

When fsview has been initialized using FSV-C:

fsvw-server-name
The name of the currently selected server. This is the name that the Fileshare Server was started with in the /s option.

When fsview has been initialized using FSV-C-long-password:

fsvw2-server-name
The name of the currently selected server. This is the name that the Fileshare Server was started with in the /s option.

On Exit:

None

Comments:

This call does not directly return information to the calling program but makes repeated calls back to a user defined call. Up to 10 entries at a time are sent to the callback. See the FSVIEW function FSV_C_add-to_file_list.

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-add-to-file-list
FSV-C-get-open-user-files


FSV-C-get-open-user-files

Gets the open files for a specific user.

Syntax:

call FSV-C-get-open-user-files using      l-user-id

Parameters:

l-user-id
pic 9(5).

On Entry:

l-user-id
A valid user ID

On Exit:

None.

Comments:

This call does not directly return information to the calling program but makes repeated calls back to a user defined call. Up to 10 entries at a time will be sent to the callback. You must provide the callback specified in the FSVIEW function FSV-C-add-to-file-list.

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-add-to-file-list
FSV-C-close-file
FSV-C-logoff-user
FSV-C-close-user-file
FSV-C-get-files-users
FSV-C-get-user-info
FSV-C-get-open-files


FSV-C-get-server-info

Gets the server information for the currently accessed server.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

call FSV-C-get-server-info using      fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

call FSV-C-get-server-info using      fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

fsvw-server-name
pic x(20).
fsvw-server-startup
pic x(20).
fsvw-server-usage
pic x(4).
fsvw-timing-io-cnt
pic x(4) comp-x.
fsvw-trace-on
pic x comp-x.

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

fsvw2-server-name
pic x(20).
fsvw2-server-startup
pic x(20).
fsvw2-server-usage
pic x(4).
fsvw2-timing-io-cnt
pic x(4) comp-x.
fsvw2-trace-on
pic x comp-x.

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

None.

On Exit:

When fsview has been initialized using FSV-C:

fsvw-server-name
The name of the currently selected server. This is the name that the Fileshare Server was started with in the /s option.
fsvw-server-startup
The time and date when the server was started, in the format hh:mm:ss dd-mm-yy.
fsvw-server-usage
The proportion of current execution time that the server is actually processing requests.
fsvw-timing-io-cnt
The number of input and output operations per second.
fsvw-trace-on
The trace modes that are currently on.

When fsview has been initialized using FSV-C-long-password:

fsvw2-server-name
The name of the currently selected server. This is the name that the Fileshare Server was started with in the /s option.
fsvw2-server-startup
The time and date when the server was started, in the format hh:mm:ss dd-mm-yy.
fsvw2-server-usage
The proportion of current execution time that the server is actually processing requests.
fsvw2-timing-io-cnt
The number of input and output operations per second.
fsvw2-trace-on
The trace modes that are currently on.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-change-server
FSV-C-get-database-info
FSV-C-check-password
FSV-C-get-comms-info
FSV-C-shutdown-server


FSV-C-get-user-info

Gets the information about the logged-on users for the server being currently accessed.

Syntax:

When the fsview has been initialized using FSV-C the callback uses the following syntax:

call FSV-C-get-user-info using      fsvw-data-block

When the fsview has been initialized using FSC-C-long-password the callback uses the following syntax:

call FSV-C-get-user-info using      fsvw2-data-block

Parameters:

Parameters when the fsview has been initialized using FSV-C (fsvw-data-block):

fsvw-log-filename
pic x(255).
fsvw-filename-size
pic x(16).
fsvw-log-filesize
pic x(16).
fsvw-disk-space
pic x(16).
fsvw-disk-size
pic x(16).

Parameters when the fsview has been initialized using FSC-C-long-password (fsvw2-data-block):

fsvw2-log-filename
pic x(255).
fsvw2-filename-size
pic x(16).
fsvw2-log-filesize
pic x(16).
fsvw2-disk-space
pic x(16).
fsvw2-disk-size
pic x(16).

See FSVIEW Datablock or FSVW2 Datablock for a complete definition of the fsvw-data-block or fsvw2-data-block respectively.

On Entry:

When fsview has been initialized using FSV-C:

fsvw-server-name
The name of the currently selected server. This is the name that the Fileshare Server was started with in the /s option.

When fsview has been initialized using FSV-C-long-password:

fsvw2-server-name
The name of the currently selected server. This is the name that the Fileshare Server was started with in the /s option.

On Exit:

None.

Comments:

This call does not directly return information to the calling program but makes repeated calls back to a user-defined call. Up to 10 entries at a time will be sent to the call back. You must provide the callback specified in the FSVIEW function FSV_C_add-to_user_list.

You can check the success of the call by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-close-file
FSV-C-logoff-user
FSV-C-get-open-user-files
FSV-C-close-user-file
FSV-C-get-files-users


FSV-C-logoff-user

Logs off a specific user.

Syntax:

When the fsview has been initialized using FSV-C it uses the following syntax:

call FSV-C-logoff-user using      l-user-id

When the fsview has been initialized using FSC-C-long-password it uses the following syntax:

call FSV-C-logoff-user using      l2-user-name
                                       l2-user-name-length

Parameters:

Parameters when fsview has been initialized using FSV-C:

l-user-id
pic 9(5)

Parameters when fsview has been initialized using FSV-C-long-password:

l2-new-user
pic x(100)
l2-user-name-length
pic x(2) comp-x

On Entry:

When the fsview has been initialized using FSV-C:

l-user-id
The user ID of the user to be logged off

When the fsview has been initialized using FSV-C-long-password:

l2-new-user
The new long user name
l2-user-name-length
Specifies the new long username length

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-close-file
FSV-C-get-open-user-files
FSV-C-close-user-file
FSV-C-get-files-users
FSV-C-get-user-info


FSV-C-long-password

Initializes the FSVIEW module and enables long username and password support.

Syntax:

call FSV-C-long-password

Parameters:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE. This is used instead of calling FSV-C.

Parent topic: FSVIEW API


FSV-C-rename-logfile

Renames the log file.

Syntax:

call FSV-C-rename-logfile using      l-filename

Parameters:

l-filename
pic x(260).

On Entry:

l-filename
The log file name

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-auto-rename-logfile
FSV-C-get-log-file-info


FSV-C-toggle-open-trace

Toggles the XFH Open trace.

Syntax:

call FSV-C-toggle-open-trace using      l-set-state

Parameters:

l-set-state
pic x comp-x.

On Entry:

l-set-state
Reserved for future use

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-toggle-trace
FSV-C-toggle-XFH-trace


FSV-C-toggle-trace

Toggles the FS trace.

Syntax:

call FSV-C-toggle-trace using      l-set-state

Parameters:

l-set-state
pic x comp-x.

On Entry:

l-set-state
Reserved for future use

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-toggle-open-trace
FSV-C-toggle-XFH-trace


FSV-C-toggle-XFH-trace

Toggles the XFH trace.

Syntax:

call FSV-C-toggle-XFH-trace using      l-set-state

Parameters:

l-set-state
pic x comp-x.

On Entry:

l-set-state
Reserved for future use

On Exit:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C-toggle-open-trace
FSV-C-toggle-trace


FSVIEW-C-TERM

Exits from FSVIEW.

Syntax:

call FSVIEW-C-TERM

Parameters:

None.

Comments:

The success of the call can be checked by examining RETURN-CODE.

Parent topic: FSVIEW API
Related reference
FSV-C


FSVIEW Command Line

All of the features of FSVIEW are available to you as a command line utility.

The commands you specify on the command line define the operation to be carried out by FSVIEW. Information is returned as a scrolling screen output.

  • Redirection of Information
  • Command Files
  • FSVIEW Command Line Syntax
Parent topic: FSView


Redirection of Information

All information displayed by the FSVIEW command line utility can be redirected to a text file using standard operating system redirection:

> | Creates a new file
>> | Extends an existing file

For example:

@fred.ctl >> fsview.txt

redirects the output from fred.ctl to the existing file fsview.txt.

Parent topic: FSVIEW Command Line
Related information
Command Files
FSVIEW Command Line Syntax


Command Files

On the FSVIEW command line, an at character (@) followed by a filename indicates that the named file contains FSVIEW commands.

If you use a file to supply FSVIEW commands, the file must be an ASCII text file.

Within the FSVIEW command file:

  • Commands should be separated by spaces.
  • Line ends are treated as spaces but a new command must start on a new line.
  • Any text between an exclamation mark (!) and the line end is treated as a comment.

The following example shows an FSVIEW command file that identifies a file and lists the users currently accessing it:

    ! Demo of fsview command file
    ! Identify file and list its users

    option upcase
    option no-echo
    admin logon FSVIEW MFTEST
    server set NWB-GLEN
    server get
    users get
    files get
    file get-users F:\testing\fsvtests\fresh\testfile1.dat
    user-file close 7 F:\testing\fsvtests\fresh\testfile1.dat
    users get
    files get

    exit

    ! All done

Note that if your command file does not use the FSVIEW exit command, you will remain in FSVIEW after the file has been executed.

Parent topic: FSVIEW Command Line
Related information
Redirection of Information
FSVIEW Command Line Syntax


FSVIEW Command Line Syntax

The following commands can be entered on an FSVIEW command prompt:

  • Admin logon
    Logs on a user to administer Fileshare.
  • Admin password
    Sets the password for secure commands.
  • Exit
    Exits FSVIEW.
  • File close
    Closes a specific file for all users.
  • File get-locks
    Gets the list of record locks held by Fileshare for a specific file.
  • File get-users
    Gets the list of users accessing a specific file.
  • Files get
    Gets the list of open files.
  • Help
    Displays the list of FSVIEW Command Line commands.
  • Logfile autorename
    Invokes the automatic log file rename on the server.
  • Logfile rename
    Renames the log file.
  • Opentrace toggle
    Toggles the XFH open trace.
  • Option echo
    Sets the echo command option on.
  • Option no-echo
    Sets the echo command option off.
  • Option no-upcase
    Sets the case of filenames to lower case.
  • Option upcase
    Sets the case of filenames to upper case.
  • Server get
    Gets the server information from the connected server.
  • Server set
    Connects to the named server.
  • Server shutdown
    Shuts down the server.
  • Trace toggle
    Toggles the Fileshare trace.
  • User-file close
    Terminates file access for a specific file and user.
  • User get-files
    Gets the list of open files for a specific user.
  • User logoff
    Logs off a user.
  • Users get
    Gets the list of logged-on users.
  • XFH trace toggle
    Toggles the XFH trace.
Parent topic: FSVIEW Command Line
Related information
Redirection of Information
Command Files


Admin logon

Logs on a user to administer Fileshare.

Syntax:

admin logon user-ID
            user-passwd

Parameters:

user-ID
A valid user ID
user-passwd
The password associated with user-ID

Comments:

This command is required if Fileshare security is enabled but the FSVIEW user ID is not going to be used.

Note: Long usernames and passwords that contain spaces must be surrounded with double quotes. In addition, if the username or password contains a double quote then you must escape it by adding an extra double quote immediately after.
Parent topic: FSVIEW Command Line Syntax
Related reference
Exit
Help
Admin password


Admin password

Sets the password for secure commands.

Syntax:

admin password supervisor-passwd

Parameters:

supervisor-passwd
The supervisor password to be set

Comments:

This command is required if you want to access secure commands and Admin logon has not been used (Fileshare security is not enabled).

Note: Long passwords that contain spaces must be surrounded with double quotes. In addition, if the password contains a double quote then you must escape it by adding an extra double quote immediately after.
Parent topic: FSVIEW Command Line Syntax
Related reference
Admin logon
Exit
Help
Server get
Server set
Server shutdown


Exit

Exits FSVIEW.

Syntax:

exit

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Admin logon
Help
Admin password


File close

Closes a specific file for all users.

Syntax:

file close filename

Parameters:

filename
The name of the file. The name must contain the full path.

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
Files get
File get-users


File get-locks

Gets the list of record locks held by Fileshare for a specific file.

Syntax:

file get-locks filename

Parameters:

filename
The name of a file. The name must contain the full path.
Parent topic: FSVIEW Command Line Syntax


File get-users

Gets the list of users accessing a specific file.

Syntax:

file get-users filename

Parameters:

filename
The name of a file. The name must contain the full path.
Parent topic: FSVIEW Command Line Syntax
Related reference
File close
Files get


Files get

Gets the list of open files.

Syntax:

files get

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
File close
File get-users
User-file close
Users get
User get-files
User logoff


Help

Displays the list of FSVIEW Command Line commands.

Syntax:

help

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Admin logon
Exit
Admin password


Logfile autorename

Invokes the automatic log file rename on the server.

Syntax:

logfile autorename

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Logfile rename


Logfile rename

Renames the log file.

Syntax:

logfile rename log-file

Parameters:

log-file
The log file to be renamed
Parent topic: FSVIEW Command Line Syntax
Related reference
Logfile autorename


Opentrace toggle

Toggles the XFH open trace.

Syntax:

opentrace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Trace toggle
XFH trace toggle


Option echo

Sets the echo command option on.

Syntax:

option echo

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-echo.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option no-echo


Option no-echo

Sets the echo command option off.

Syntax:

option no-echo

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-echo.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option echo


Option no-upcase

Sets the case of filenames to lower case.

Syntax:

option no-upcase

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-upcase.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option upcase


Option upcase

Sets the case of filenames to upper case.

Syntax:

option upcase

Parameters:

None.

Comments:

The default setting for FSVIEW is option no-upcase.

Parent topic: FSVIEW Command Line Syntax
Related reference
Option no-upcase


Server get

Gets the server information from the connected server.

Syntax:

server get

Parameters:

None.

Comments:

The information returned by this command includes activity statistics, log file information and database information.

Parent topic: FSVIEW Command Line Syntax
Related reference
Server set
Server shutdown
Admin password


Server set

Connects to the named server.

Syntax:

server set fileshare-name

Parameters:

fileshare-name
The name of the Fileshare server to connect to
Parent topic: FSVIEW Command Line Syntax
Related reference
Server get
Server shutdown
Admin password


Server shutdown

Shuts down the server.

Syntax:

server shutdown

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
Server get
Server set
Admin password


Trace toggle

Toggles the Fileshare trace.

Syntax:

trace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Opentrace toggle
XFH trace toggle


User-file close

Terminates file access for a specific file and user.

Syntax:

user-file close user-ID
                filename

Parameters:

user-ID
A valid user ID associated with filename
filename
The name of a file. The name must contain the full path.

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
Users get
User get-files
Files get
User logoff


User get-files

Gets the list of open files for a specific user.

Syntax:

user get-file user-ID

Parameters:

user-ID
A valid user ID
Parent topic: FSVIEW Command Line Syntax
Related reference
User-file close
Users get
Files get
User logoff


User logoff

Logs off a user.

Syntax:

user logoff user-ID

Parameters:

user-ID
A valid user ID

Comments:

You must be logged on as FSVIEW to use this command.

Parent topic: FSVIEW Command Line Syntax
Related reference
User-file close
Users get
User get-files
Files get


Users get

Gets the list of logged-on users.

Syntax:

users get

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
User-file close
User get-files
Files get
User logoff


XFH trace toggle

Toggles the XFH trace.

Syntax:

xfhtrace toggle

Parameters:

None.

Parent topic: FSVIEW Command Line Syntax
Related reference
Trace toggle
Opentrace toggle


File Status

  • File Status Codes
  • Extended File Status Codes
  • Microsoft COBOL V2 File Status Codes
Parent topic: File Handling Reference


File Status Codes

The following are the possible two-byte codes returned as the file status after each I/O operation.

00
Successful completion.
02
Indexed files only. One of two possibilities: For a READ statement, the key value for the current key is equal to the value of that same key in the next record in the current key of reference. For a WRITE or REWRITE statement, the record just written created a duplicate key value for at least one alternate record key for which duplicates are allowed.
04
The length of the record being processed does not conform to the fixed file attributes for that file.
05
The referenced optional file is not present at the time the OPEN statement is executed.
07
Sequential files only. For an OPEN or CLOSE statement with the REEL/UNIT phrase the referenced file is a non-reel/unit medium.
10
No next logical record exists. You have reached the end of the file.
14
Relative files only. The number of significant digits in the relative record number is larger than the size of the relative key data item described for that file.
21
Sequentially accessed files only. Indicates a sequence error. The ascending key requirements of successive record key values has been violated, or, the prime record key value has been changed by a COBOL program between successful execution of a READ statement and execution of the next REWRITE statement for that file.
22
Indexed and relative files only. Indicates a duplicate key condition. Attempt has been made to store a record that would create a duplicate key in the indexed or relative file OR a duplicate alternate record key that does not allow duplicates.
23
Indicates no record found. An attempt has been made to access a record, identified by a key, and that record does not exist in the file. Alternatively a START or READ operation has been tried on an optional input file that is not present.
24
Relative and indexed files only. Indicates a boundary violation arising from one of the following conditions: an attempt is made to write beyond the externally defined boundaries of a file; a sequential WRITE operation has been tried on a relative file, but the number of significant digits in the relative record number is larger than the size of the relative key data item described for the file.
30
The I/O statement was unsuccessfully executed as the result of a boundary violation for a sequential file or as the result of an I/O error, such as a data check parity error, or a transmission error.
34
The I/O statement failed because of a boundary violation. This condition indicates that an attempt has been made to write beyond the externally defined boundaries of a sequential file.
35
An OPEN operation with the I-O, INPUT, or EXTEND phrases has been tried on a non-OPTIONAL file that is not present.
37
An OPEN operation has been tried on a file which does not support the open mode specified in the OPEN statement.
38
An OPEN operation has been tried on a file previously closed with a lock.
39
A conflict has been detected between the fixed file attributes and the attributes specified for that file in the program.
41
An OPEN operation has been tried on a file already opened.
42
A CLOSE operation has been tried on a file already closed.
43
Files in sequential access mode. The last I/O statement executed for the file, before the execution of a DELETE or REWRITE statement, was not a READ statement.
44
A boundary violation exists. Possible violations are:
  • An attempt has been made to WRITE or REWRITE a record that is larger than the largest, or smaller than the smallest record allowed by the RECORD IS VARYING clause of the associated file.
  • An attempt has been made to REWRITE a record to a file, and the record is not the same size as the record being replaced.
46
A sequential READ operation has been tried on a file open in the INPUT or I-O mode but no valid next record has been established.
47
A READ or START operation has been tried on a file not opened INPUT or I-O.
48
A WRITE operation has been tried on a file not opened in the OUTPUT, I-O, or EXTEND mode, or on a file open I-O in the sequential access mode.
49
A DELETE or REWRITE operation has been tried on a file that is not opened I-O.
51
Couldn't find the index in the specified C-ISAM indexed file.
52
Attempted to add an index that already exists in the specified C-ISAM indexed file.
53
Attempted to delete the prime index in the specified C-ISAM indexed file.
54
The specified C-ISAM indexed file is open for sharing in a distributed environment.
Parent topic: File Status
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
IDXFORMAT 9 | 4080 bytes
All other file types | 62 Kbytes
Note:

IDXFORMAT 9 files have a single primary key without duplicates.

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.

Note:
  • 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 the chapter Rebuild in your File Handling book.

Parent topic: Rebuild Command Line Options
Related reference
Rebuild through Fileshare
Rebuild


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

-c:d1i6

specifies data compression routine 1, and index compression of leading characters and trailing spaces.

-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.
    Windows:
    -k:1+20
    UNIX:
    /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.
    Windows:
    -k:5+5:20+1d:40+2,43+10
    UNIX:
    /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.
    Windows:
    -k:1+5:20+10dsZ
    UNIX:
    /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.
    Windows:
    -k:1+5:20+10dsh0
    UNIX:
    /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).
    Windows:
    -k:1+10:11+20dc3
    UNIX:
    /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.
    Windows:
    -k:a:1+3d
    UNIX:
    /k:a:1+3d
  • This example removes the key that starts at character position 10 and is 5 characters in length.
    Windows:
    -k:r:10+5
    UNIX:
    /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.
    Windows:
    rebuild infile.dat, outfile.dat -k:1+5:6:10d -s:MF4
    UNIX:
    rebuild infile.dat, outfile.dat /k:1+5:6:10d /s:MF4
Parent topic: Rebuild Command Line Options


Rebuild Options - /l

Specifies the loading and unloading of files.

Use the /l option when you are loading to and unloading from IDXFORMAT 9 files.

For loading, you need to define the record size and key definition (one key only).

All records must be the key order of the target file and there must be no records which result in duplicate keys.

You do not need to define the record size and key definition for unloading.

Parameters

r9 | Load a record sequential file to an IDXFORMAT 9 file
9r | Unload an IDXFORMAT 9 file to a record sequential file

Examples

rebuild /l:r9 file1, file2 /k:1+10 /r:v20-30

This example loads a record sequential file to an IDXFORMAT 9 file, with the key structure specified by the /k option and the recording mode and record lengths specified with the /r option.

rebuild /l:9r file1, file2

This example unloads an IDXFORMAT 9 file to a record sequential file.

Parent topic: Rebuild Command Line Options


Rebuild Options - /n

Displays information about a file.

The /n option displays the same information as the /i option, plus the number of data records in the file, but without performing any other processing.

Parent topic: Rebuild Command Line Options
Related reference
Rebuild Options - /i


Rebuild Options - /o

Specifies the organization of the input and output files.

If the input file is line sequential and the record contains COMP or COMP-3 items, the file must have been created with the INSERTNULL configuration option set to ON. If the file has been created with INSERTNULL set to OFF, or has come from a third party and does not precede non-printable characters with null bytes, the file will not be correctly processed if the COMP/COMP-3 items contain bytes with the values x"00", x"09" (tab), x"0A" (newline) or x"0D" (carriage return).

Parameters

/o:infile-org[,outfile-org]

infile-org and outfile-org can be any of the following:

Value | Description
lseq | line sequential
seq | sequential
rel | relative
ind | indexed

This format enables you to convert from any one file organization to another.

If outfile-org is omitted, the output file will have the same organization as the input file.

Using this syntax, you can convert a line sequential file to an indexed file, or an indexed file to a variable sequential file, and so on.

Examples

rebuild in-file, out-file /o:lseq,ind /t:mf /k:1+10 /r:v20-30

converts a line sequential file to an indexed file with the key structure specified by the /k option, the file format specified by the /t option, and the recording mode and recording lengths specified by the /r option. The key information must be wholly contained within the minimum record length.

rebuild in-file, out-file /o:ind,seq /r:v20-30

converts an indexed file to a variable length sequential file with the recording mode and record lengths specified by the /r option.

Parent topic: Rebuild Command Line Options


Rebuild Options - /p

Instructs Rebuild to rebuild an IDXFORMAT"8" file in place.

The rebuild uses less disk space, but if it fails the file is lost. You must back up the file before you attempt a rebuild with this option.

Parent topic: Rebuild Command Line Options


Rebuild Options - /q

Instructs Rebuild to rebuild an IDXFORMAT"12" index file.

The rebuild process is performed using the .idx file that is used with IDXFORMAT"12" files. This rebuild process is considerably quicker than other rebuild processes such as a data scrape or Rebuild option /p, which could be a consideration for using this particular format of index file. The consequence of using it is that any corrupted information found in the file is not deleted; however, when the index is rebuilt, this information cannot be reached.

Parent topic: Rebuild Command Line Options


Rebuild Options - /r

Defines the record structure of the input and output files.

You can specify a different record structure for the output file, and if the record length of the output file is greater than the record length of the input file, you can specify a padding character. You need to specify the record structure of the input file only where the file does not have a header. If you do not specify the record structure of the output file it will have the same structure as the input file. If you only specify one record structure, it is taken to be the record structure of the output file, unless the input file has no header, in which case it is taken to be the record structure of the input file.

If you convert to and from Btrieve format indexed files using the /s and /t options, you might need to supply the /r option, even where you are not changing the record structure. This is because some indexed file features are implemented differently by Btrieve. An example is that Btrieve does not store the maximum record length. Therefore, on conversion from a COBOL format file to a Btrieve file and back again, certain record length and recording mode information can be lost. This makes the file unreadable to a COBOL program using the original file description. Using the /r option, you can specify the record length and recording mode information on the command line to retain the correct record definitions during conversion. You can determine the correct options from the COBOL format file using the /n option.

Parameters

frecord-length | specifies a fixed-length record format with records of record-length
vmin-record-length-max-record-length | specifies a variable-length format where min-record-length is the minimum record length and max-record-length is the maximum record length. Separate the lengths with a hyphen
ppad-character|[ddecimal-value] | specifies the padding character where the output record length is greater than the input record length. The default is spaces for line sequential files and NULLs for all other file organizations. d indicates that the padding character is supplied as a decimal value in the range 0 through 255, indicating the ANSI character to be used

Examples

r:f100

(where the input file has no header) specifies that the input file has a fixed record length of 100 bytes and that the output file will have the same fixed record length.

-r:v100-200

(where the input file has a header) specifies that the output file will have a variable record length with a minimum record length of 100 bytes and a maximum record length of 200 bytes.

r:f20,f30pZ

specifies that the input file has a fixed record length of 20 bytes, and that the output file will have a fixed record length of 30 bytes with Z used as a padding character.

r:f40pd49

specifies that the output file will have a fixed record length of 40 bytes with the character "I" used as a padding character.

Parent topic: Rebuild Command Line Options


Rebuild Options - /s

Specifies the format of the input file.

Parameters

/s:btrv | Btrieve format
 | C-ISAM format
 | 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
 | C-ISAM format
 | 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 tasks
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, BTRV, LII, L2.

Parent topic: Syntax Errors


Invalid key length - cannot be zero

One of the keys you defined has a zero length, which is illegal. This may be due to incorrect use of separator characters.

Resolution:

Make sure that any keys you define have a valid length.

Parent topic: Syntax Errors


Invalid key specification - key not contained in record

One of the keys, as defined, is not wholly contained in the record. This is illegal.

Resolution:

Ensure that the key is wholly contained in the record. For variable length records, the key must be wholly contained in the minimum length record.

Parent topic: Syntax Errors


Invalid key start - cannot be zero

One of the keys defined has a start character position of zero, which is illegal. This may be due to incorrect use of separator characters.

Resolution:

Make sure that any keys you define have a valid start character.

Parent topic: Syntax Errors


Invalid key structure - '+' expected

A key part parameter of the /k option is incorrect.

Resolution:

Make sure that you specify each key part as start character position and length separated by a plus (+) or L.

Parent topic: Syntax Errors


Invalid option

Parent topic: Syntax Errors


Invalid organization

The syntax of the /o option is incorrect.

Resolution:

Specify a valid organization, one of: lseq, seq, rel and ind. The forms s, r, i, si and ri are also permitted for compatibility with previous products.

Parent topic: Syntax Errors


Invalid organization - must be indexed for index rebuild

You have specified a non-indexed input file with no output file. If there is no output file Rebuild assumes that you want to rebuild an indexed file.

Resolution:

Make sure that you specify an output file if your input file is not an indexed file.

Parent topic: Syntax Errors


Invalid record length - cannot be zero

You have specified that the length of a record is zero. This is invalid.

Resolution

Specify a length greater than zero which falls within the limits for record lengths for this COBOL system.

Parent topic: Syntax Errors


Invalid record lengths - maximum must not be less than minimum

The integers you have used to specify the maximum and minimum lengths of a record indicate that the maximum length is less than the minimum length. This is invalid.

Resolution

Reenter the maximum or minimum record length, ensuring that the maximum length is greater than the minimum length.

Parent topic: Syntax Errors


Invalid record parameter - '-' expected

When specifying the record structure of a variable length file, you have not separated the minimum record length and the maximum record length with a hyphen (-).

Resolution:

Use the correct format: /r:vminreclen-maxreclen

Parent topic: Syntax Errors


Invalid record type - 'F' or 'V' expected

You have entered record type other than fixed or variable. This is invalid.

Resolution

Reenter the record type using either f (fixed) or v (variable).

Parent topic: Syntax Errors


Invalid format

The format of the /s or /t option is incorrect.

Resolution:

For details of the correct format see the help topic Rebuild Options - /s or the help topic Rebuild Options - /t.

Parent topic: Syntax Errors
Related information
Rebuild Options - /s
Rebuild Options - /t


No output file specified for /t option to refer to

You did not specify a name for the output file which was referred to with the /t option.

Resolution:

Specify the name of an output file for this option.

Parent topic: Syntax Errors


No output file specified for data compression

You did not specify an output filename for data compression.

Resolution:

Specify a valid output filename.

Parent topic: Syntax Errors


Number expected

You have specified another character where a number was expected.

Resolution:

Specify a numeric value for this parameter.

Parent topic: Syntax Errors


Output organization was specified but not output file name

You did not supply a filename although you specified an output organization.

Resolution:

Specify an output filename.

Parent topic: Syntax Errors


Options file not found

The options file specified on the command line cannot be found.

Resolution:

Check that the file exists, and the specification used on the command line is correct.

Parent topic: Syntax Errors


Execution Errors

These occur when the program sets the return code to a value other than zero to indicate the type of error that has occurred.
  • ***Error on input file - disk space exhausted
    File processing cannot continue because there is insufficient disk space to do so.
  • ***Error on input file - duplicate key - record not written:
    The record was not written to the output file as this would have created an invalid duplicate key.
  • ***Rebuild aborted - file is not as specified in s option (s option not required)
    The file specified by the /s option was not recognized.
  • ***Error on input file - File locked
    The file you specified as your input file is locked by another process.
  • ***Error on input file - file not found
    The input file cannot be found. The return code is set to 1.
  • ***Error on input file - illegal filename specified
    A filename does not conform to the standards imposed by the operating system or COBOL system.
  • ***Error on input file - invalid key of reference specified in x option
    The number specified in the key-of-reference option (/x) is greater than or equal to the number of keys for the given file. The return code is set to 1.
  • ***Error on input file - status xx, and ***Error on input file - status 9/yyy
    An error other than one of the above input file errors has occurred while processing the input file.
  • ***Error on output file - record length << min or >> max
    Rebuild attempted to write a record to the output file with a record length less than the minimum or greater than the maximum length for the file.
  • ***Error on output file - status xx, and ***Error on output file - status 9/yyy
    An error has occurred processing the output file.
Parent topic: Rebuild Error, Information and Warning Messages


***Error on input file - disk space exhausted

File processing cannot continue because there is insufficient disk space to do so.

Resolution:

Ensure that the input file is not corrupt. The output file is closed and should be usable, even if the rebuild is not complete.

Parent topic: Execution Errors


***Error on input file - duplicate key - record not written:

The record was not written to the output file as this would have created an invalid duplicate key.
Parent topic: Execution Errors


***Rebuild aborted - file is not as specified in s option (s option not required)

The file specified by the /s option was not recognized.

Resolution:

Either remove the /s option or correct it.

Parent topic: Execution Errors


***Error on input file - File locked

The file you specified as your input file is locked by another process.

Resolution:

Try again when the file is free to be accessed.

Parent topic: Execution Errors


***Error on input file - file not found

The input file cannot be found. The return code is set to 1.

Resolution:

Check that the filename you entered is correct, and the file does actually exist.

Parent topic: Execution Errors


***Error on input file - illegal filename specified

A filename does not conform to the standards imposed by the operating system or COBOL system.

Resolution:

Try the file operation again using a correct filename.

Parent topic: Execution Errors


***Error on input file - invalid key of reference specified in x option

The number specified in the key-of-reference option (/x) is greater than or equal to the number of keys for the given file. The return code is set to 1.

Resolution:

Check the key required, and try again.

Parent topic: Execution Errors


***Error on input file - status xx, and ***Error on input file - status 9/yyy

An error other than one of the above input file errors has occurred while processing the input file.

Possible causes are:

  • The file does not exist
  • A hardware error has occurred opening or reading the file
  • The file is corrupt

The status xx is a COBOL file status. If the first byte is a 9, then the status yyy is a COBOL run-time error number. The output file is closed, and should be usable, even if the rebuild is not complete. The return code is set to 1.

Resolution:

Investigate the error. For run-time system error messages see the help topic Run-time System Error Messages.

Parent topic: Execution Errors
Related reference
***Error on output file - status xx, and ***Error on output file - status 9/yyy
File Status Codes
Run-time System Error Messages


***Error on output file - record length << min or >> max

Rebuild attempted to write a record to the output file with a record length less than the minimum or greater than the maximum length for the file.

Resolution:

Change the record lengths specified in the /r option.

Parent topic: Execution Errors


***Error on output file - status xx, and ***Error on output file - status 9/yyy

An error has occurred processing the output file.
Possible causes are:
  • The file cannot be created
  • A hardware error has been encountered on opening or writing the file
  • The parameters specified are incorrect.

The status xx is a COBOL file status. If the first byte is a 9, then the status yyy is a COBOL run-time error number. The return code is set to 2.

Resolution:

Investigate the error. For run-time system error messages see the help topic Run-time System Error Messages.

Parent topic: Execution Errors
Related reference
***Error on input file - status xx, and ***Error on input file - status 9/yyy
File Status Codes
Run-time System Error Messages


Information Messages

These messages are displayed for information purposes only.
  • Rebuild successful
    The file you specified has been successfully rebuilt.
  • Records processed
    The indicated number of records were processed when the file was rebuilt or reorganized.
Parent topic: Rebuild Error, Information and Warning Messages


Rebuild successful

The file you specified has been successfully rebuilt.
Parent topic: Information Messages


Records processed

The indicated number of records were processed when the file was rebuilt or reorganized.
Parent topic: Information Messages


Warning Messages

Depending on the operation selected, some command line options are unnecessary. In these cases, the incorrect usage will be indicated, but the option will be ignored and processing will continue. Note that the option may be correct, but omission of other information may have caused Rebuild to select the wrong process. If this is the case, correct the command line and rerun.
  • Option ignored - k option not needed with n option
    A key definition option has been together with a request for file information. The k option is ignored.
  • Option ignored - x option not needed for index rebuild
    A key-of-reference option has been used when an action other than indexed file reorganization has been selected. The option is ignored.
Parent topic: Rebuild Error, Information and Warning Messages


Option ignored - k option not needed with n option

A key definition option has been together with a request for file information. The k option is ignored.
Parent topic: Warning Messages


Option ignored - x option not needed for index rebuild

A key-of-reference option has been used when an action other than indexed file reorganization has been selected. The option is ignored.
Parent topic: Warning Messages


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:

  • MFJSABCODE
    Used to override the default abend code when MFJSERET=ABEND is specified.
  • MFJSENGINE
    Determines which sort engine the utility MFJSORT is to emulate.
  • MFJSERET
    Determines the response to an unsuccessful sort, copy or merge operation.
  • MFJSSTRICTSORT
    Enables strict mainframe emulation behavior during a sort.
  • MFJSTATS
    Produces a report for the COBOL SORT operation.
  • MFJSWINDOW
    Determines the sliding or fixed century window.
  • SORTCOMPRESS
    Determines whether to compress each record in a SORT operation.
  • SORTSCHEME
    To increase performance of a SORT operation, configure SORT to retain more of the record information in memory.
  • SORTSPACE
    Determines the amount of memory allocated to internal workspace for SORT operations.
  • SORTTEMPSPACE
    Determines the amount of temporary memory allocated for SORT operations.
  • SORTTYPE
    Determines the method for reading and writing files during SORT operations.
  • TEMPDIR/ TMP/ TEMP
    Determines where the run-time system of the directory stores paging files.
Parent topic: Sorting Files


MFJSABCODE

Determines the abend code issued when MFJSERET=ABEND is in effect.

If this environment variable is not set, and MFJSERET=ABEND is in effect, an abend S00D (decimal code 16) is issued when a Sort or Merge operation fails with an unrecoverable error.

Parameters

Abend code (decimal) between 1 and 99

If a Sort or Merge the operation fails with an unrecoverable error, it will abend with a code between S001 and S063

The default is that the variable is not set. Any specified value outside of the range 1 to 99 will result in an abend code of S00D being issued.

Example

MFJSABCODE=77

(results in abend code S04D)

Parent topic: SORT Environment Variables


MFJSENGINE

Determines which sort engine the utility MFJSORT is to emulate.

Use this variable with Enterprise Server only.

Parameters

DFSORT
Emulates DFSORT
SYNCSORT
Emulates SYNCSORT

The default is DFSORT.

Example

Parent topic: SORT Environment Variables
Related concepts
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSERET

Determines the response to an unsuccessful sort, copy or merge operation.

If this environment variable is not set, an unsuccessful operation and its program will terminate with an unrecoverable error (return code 16). See also MFJSABCODE.

Parameters

ABEND
The operation will abend and its program will continue instead of terminating with an unrecoverable error (return code 16)

The default is that the variable is not set.

Example

MFJSERET=ABEND
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSSTRICTSORT

Enables strict mainframe emulation behavior during a sort.

Parameters

ON/OFF
Enables or disables the following mainframe behavior:
  • All JCL statements must contain a SYSOUT parameter, otherwise they will abend.
  • Modification of a ZD number with value 0 through INREC or OUTREC processing now keeps its sign value.
  • Records that are shorter than the output file's LRECL will be padded with low-values instead of spaces.
  • Input RECFM is identical to the output RECFM or OUTFIL RECFM (unless FTOV or VTOF/CONVERT has been specified), otherwise it errors with return code 16.

The default is OFF.

Example

MFJSSTRICTSORT=ON
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


MFJSTATS

Produces a report for the COBOL SORT operation.

Parameters

ON
The report is displayed to SYSOUT. If a report file already exists for a previous SORT operation, the new report is appended to it.
OFF
A report is not produced.

The default value is OFF.

Example

MFJSTATS=ON

Comments

If you are running a COBOL program with a SORT statement in a non-mainframe environment, set MFJSTATS=ON and in the same command prompt, run your COBOL program.

In a mainframe environment, if you run a COBOL program from your JCL, and that JCL uses COBOL syntax, you need to add //MFJSTATS DD SYSOUT=* to your JCL card.

Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS
Related reference
Creating a Statistics Report


MFJSWINDOW

Determines the sliding or fixed century window.

Use this environment variable for Y2K compatibility, when two-digit year values are used.

Parameters

To set a sliding century window, set a value between 0 and 100. For example, a value of 80 would set a century window of 1931-2030 in 2011, 1932-2031 in 2012, and so on.

To set a fixed century window, set a value between 1000 and 3000. For example, a value of 1973 would set a century window of 1973-2072.

The default is a sliding value of 80 when emulating DFSORT, and a default value of 0 when emulating SYNCSORT. A value of 0 equates to a century window, starting in the current year.

Example

MFJSWINDOW=25

Comments

You can use this environment variable instead of the Y2PAST sort option.

Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


SORTCOMPRESS

Determines whether to compress each record in a SORT operation.

When SORTCOMPRESS is set, run-length encoding of sort records results in much better performance when records contain multiple repeated characters.

Parameters

0
No compression.
Any number not equal to 0
Compression of records.

The default value is 0.

Example

SORTCOMPRESS=5
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME


SORTSCHEME

To increase performance of a SORT operation, configure SORT to retain more of the record information in memory.

You should consider setting this environment variable if the total size of files in your SORT operation is over 1GB.

Parameters

0
During a SORT operation, temporary files are created to hold the non-key data portions of a record that are greater than 1024 bytes.
1

During a SORT operation, non-key data portions of a record are held in memory depending on the size of SORTSPACE:

Size of SORTSPACE | Maximum non-key data portion held in memory
1MB or greater | 5KB
4MB or greater | 12KB
8MB or greater | 28KB
16MB or greater | 62KB
Note: In general, the non-key data portion is the size of the record minus the size of the key data.

The default value is 0.

Example

SORTSCHEME=1
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTCOMPRESS


SORTSPACE

Determines the amount of memory allocated to internal workspace for SORT operations.

Typically, increasing SORTSPACE will improve the overall performance of SORT operations. This can be improved further by the use of SORTSCHEME when the files to be sorted are over 1GB.

If you are receiving COBRT105 Memory allocation error (Fatal) errors during your SORT operations, you should set SORTTEMPSPACE, and reduce the value of SORTSPACE; see SORTTEMPSPACE for more details.

Parameters

workspace size

Specify the amount of memory in one of the following formats:

Format | Workspace size
64M | 64 megabytes
2G | 2 gigabytes
1000000 | 1,000,000 bytes

The default value is 1,048,576 bytes (1MB).

The minimum value is 65,536 bytes (64KB).

The maximum value is 4,294,967,295 bytes (4GB - 1 byte).

Examples

SORTSPACE=64M
SORTSPACE=2G
SORTSPACE=1000000
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTTEMPSPACE
SORTSCHEME
SORTCOMPRESS


SORTTEMPSPACE

Determines the amount of temporary memory allocated for SORT operations.

If you cannot set SORTSPACE to allocate enough contiguous memory for a SORT operation, set SORTTEMPSPACE to the required amount, and then set SORTSPACE to a smaller value. Memory is then allocated in chunks of the size specified by SORTSPACE, until it has allocated the value set by SORTTEMPSPACE.

We recommend that you use SORTTEMPSPACE only if you are receiving COBRT105 Memory allocation error (Fatal) errors.

Parameters

workspace size

Specify the amount of memory in one of the following formats:

Format | Workspace size
64M | 64 megabytes
2G | 2 gigabytes
1000000 | 1,000,000 bytes
The minimum value is 33,554,432 bytes (32MB).
Note: The minimum value is made up of the settings for SORTSPACE and SORTTEMPSPACE combined.

The maximum value is 4,294,967,295 bytes (4GB - 1 byte).

Example

SORTTEMPSPACE=64M
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTYPE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


SORTTYPE

Determines the method for reading and writing files during SORT operations.

Parameters

0 or 1
SORT operations use CBL_ routines, where possible, which improves performance.
2
SORT operations use the file handler, so that format modifications are picked up from the extfh.cfg file.

The default value is 0.

Example

SORTTYPE=2
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
TEMPDIR/ TMP/ TEMP
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


TEMPDIR/ TMP/ TEMP

Determines where the run-time system of the directory stores paging files.

By default, the paging files are stored in the current directory.

Parameters

pathname
Specify the pathname for the paging files, using the correct environment variable for your operating system:
Platform | Environment variable
UNIX | TMPDIR
Windows or other | TMP (or TEMP if TMP is not set)

Example

TMPDIR=/home/temp	*> UNIX
TMP=C:\temp		 *> WINDOWS
Parent topic: SORT Environment Variables
Related concepts
MFJSENGINE
MFJSTATS
MFJSERET
MFJSSTRICTSORT
MFJSWINDOW
SORTTYPE
SORTTEMPSPACE
SORTSPACE
SORTSCHEME
SORTCOMPRESS


Mfsort Error Messages

Select the range containing your message number:

  • Messages 0001 to 0099
  • Messages 0100 to 0199
  • Messages 0200 to 0399
Parent topic: Sorting Files


Messages 0001 to 0099

Select the number of the message you require details about:

  • SORT011U SYSIN dataset value missing
  • SORT012U SYSIN dataset value missing
  • SORT013U I/O error on dataset value
  • SORT014U Status = value
  • SORT015U Command statement error(s) detected
    The sort will not execute because of errors found during the parsing of the command.
  • SORT019I Key length truncated to 4096 bytes
  • SORT020U SORT(EXTSM) failed - sort engine status = Value
    An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.
  • SORT021U SORT failed - sort engine status = <value>
  • SORT032I Number records sorted
  • SORT033I Number records merged
  • SORT034I Number records copied
  • SORT035U SORTIN DSORG or RECFM missing
    At least one of the instructions RECORD and ORG was required and was not specified.
  • SORT036U SORTIN record length missing or invalid
    You did not specify a record length in the RECORD instruction, or else you specified an invalid length.
  • SORT037U SYSIN RECFM value invalid
  • SORT038U SORTIN RECFM value invalid
    The record format in the RECORD instruction for the input file is invalid.
  • SORT039U SORTOUT RECFM value invalid
    The record format in the RECORD instruction for the output file is invalid.
  • SORT040U SORT terminated by E15 Operator
    The user exit routine E15 has terminated the sort process.
  • SORT041U SORT terminated by E35 Operator
    The user exit routine E35 has terminated the sort process.
  • SORT042U Memory allocation failure
    The mfsort utility was unable to allocate the required memory.
  • SORT043U Too many OUTFIL files specified
    You have specified too many files in the OUTFIL option.
  • SORT044U Too many USE files specified
    You have specified too many files in the USE instruction.
  • SORT045U Too many GIVE files specified
    You have specified too many files in the GIVE instruction.
  • SORT046U OUTFIL RECFM <value> invalid
  • SORT050U ICETOOL input file not found
    The file that is to be sorted has not been found.
  • SORT051U ICETOOL output file not found
  • SORT052U SORTIN DSORG VSAM invalid
  • SORT090U SORT terminated - missing SYSOUT
    No catalog entry has been found for the SYSOUT file.
  • SORT091U SORT terminated - missing SYSIN
  • SORT092U SORT terminated - missing SORTOUT
  • SORT093U SORT terminated - missing SORTIN or SORTIN01
  • SORT094U SORT terminated - missing SORTOFvalue
  • SORT095U SORT terminated - Bad data in CHANGE field
    Please see the CHANGE and DFSORT documentation on the IBM web site for further details.
  • SORT096U SORT terminated - missing FNAMES dataset value
    Please see the FNAMES and DFSORT documentation on the IBM web site for further details.
  • SORT097U SORTXSUM RECFM <value> invalid
  • SORT098U SORT terminated - missing SORTXSUM
  • SORT099I Header or trailer larger than record
Parent topic: Mfsort Error Messages


SORT011U SYSIN dataset value missing

Message

No SYSIN has been found for the SORT step.

Resolution

Recode the SORT step to include a SYSIN.

Parent topic: Messages 0001 to 0099


SORT012U SYSIN dataset value missing

Parent topic: Messages 0001 to 0099


SORT013U I/O error on dataset value

Parent topic: Messages 0001 to 0099


SORT014U Status = value

Parent topic: Messages 0001 to 0099


SORT015U Command statement error(s) detected

The sort will not execute because of errors found during the parsing of the command.
Parent topic: Messages 0001 to 0099


SORT019I Key length truncated to 4096 bytes

Parent topic: Messages 0001 to 0099


SORT020U SORT(EXTSM) failed - sort engine status = Value

An unexpected failure occured after the sort had been initiated. This message indicates the returned sort file status value.

Resolution:

Investigate the file status. See the topic File Status.

Parent topic: Messages 0001 to 0099
Related reference
File Status Codes


SORT021U SORT failed - sort engine status = <value>

Message

A failure in the SORT engine detailed caused the sort to fail.

Parent topic: Messages 0001 to 0099


SORT032I Number records sorted

Message

Details the number of records sorted.

Parent topic: Messages 0001 to 0099


SORT033I Number records merged

Parent topic: Messages 0001 to 0099


SORT034I Number records copied

Parent topic: Messages 0001 to 0099


SORT035U SORTIN DSORG or RECFM missing

At least one of the instructions RECORD and ORG was required and was not specified.

Resolution:

Provide the missing instruction and resubmit the sort.

Parent topic: Messages 0001 to 0099


SORT036U SORTIN record length missing or invalid

You did not specify a record length in the RECORD instruction, or else you specified an invalid length.

Resolution:

Provide or correct the record length and resubmit the sort.

Parent topic: Messages 0001 to 0099


SORT037U SYSIN RECFM value invalid

Parent topic: Messages 0001 to 0099


SORT038U SORTIN RECFM value invalid

The record format in the RECORD instruction for the input file is invalid.

Resolution:

Correct the record format and resusbmit the sort.

Parent topic: Messages 0001 to 0099


SORT039U SORTOUT RECFM value invalid

The record format in the RECORD instruction for the output file is invalid.

Resolution:

Correct the record format and resusbmit the sort.

Parent topic: Messages 0001 to 0099


SORT040U SORT terminated by E15 Operator

The user exit routine E15 has terminated the sort process.
Parent topic: Messages 0001 to 0099


SORT041U SORT terminated by E35 Operator

The user exit routine E35 has terminated the sort process.
Parent topic: Messages 0001 to 0099


SORT042U Memory allocation failure

The mfsort utility was unable to allocate the required memory.

Resolution:

Try reducing the value of the SORTSPACE environment variable.

Parent topic: Messages 0001 to 0099


SORT043U Too many OUTFIL files specified

You have specified too many files in the OUTFIL option.

Resolution:

Respecify your mfsort command with an OUTFIL instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT044U Too many USE files specified

You have specified too many files in the USE instruction.

Resolution:

Respecify your mfsort command with a USE instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT045U Too many GIVE files specified

You have specified too many files in the GIVE instruction.

Resolution:

Respecify your mfsort command with a GIVE instruction that names up to 100 files.

Parent topic: Messages 0001 to 0099


SORT046U OUTFIL RECFM <value> invalid

Message

The RECFM specified for OUTFIL is invalid.

Resolution

Verify that the RECFM for OUTFIL matches SORTIN or use either FTOV or VTOF as appropriate.

Parent topic: Messages 0001 to 0099


SORT050U ICETOOL input file not found

The file that is to be sorted has not been found.

Message

The input file for ICETOOL that is to be sorted was not found.

Resolution

Check your SORTCARD to ensure that the input file is correct and can be accessed.

Parent topic: Messages 0001 to 0099


SORT051U ICETOOL output file not found

Message

The definition for the output file for ICETOOL was not found.

Resolution

Check your SORTCARD to ensure that the output file is correct.

Parent topic: Messages 0001 to 0099


SORT052U SORTIN DSORG VSAM invalid

Message

A concatenated SORTIN cannot have a DSORG of VSAM.

Parent topic: Messages 0001 to 0099


SORT090U SORT terminated - missing SYSOUT

No catalog entry has been found for the SYSOUT file.
Parent topic: Messages 0001 to 0099


SORT091U SORT terminated - missing SYSIN

Message

SORT has terminated as SYSIN cannot be found.

Resolution

Recode your SORTCARD to include a SYSIN.

Parent topic: Messages 0001 to 0099


SORT092U SORT terminated - missing SORTOUT

Parent topic: Messages 0001 to 0099


SORT093U SORT terminated - missing SORTIN or SORTIN01

Parent topic: Messages 0001 to 0099


SORT094U SORT terminated - missing SORTOFvalue

Parent topic: Messages 0001 to 0099


SORT095U SORT terminated - Bad data in CHANGE field

Please see the CHANGE and DFSORT documentation on the IBM web site for further details.
Note: Refer to DFSORT and ICETOOL Emulation for details of the DFSORT syntax supported in Enterprise Developer
Parent topic: Messages 0001 to 0099
Related concepts
DFSORT and ICETOOL Emulation


SORT096U SORT terminated - missing FNAMES dataset value

Please see the FNAMES and DFSORT documentation on the IBM web site for further details.
Note: Refer to DFSORT and ICETOOL Emulation for details of the DFSORT syntax supported in Enterprise Developer
Parent topic: Messages 0001 to 0099
Related concepts
DFSORT and ICETOOL Emulation


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
  • Integrating Preprocessors into Enterprise Developer
    This document walks you through the process of integrating additional preprocessors with Micro Focus Enterprise Developer. It is intended for third-party vendors who want to extend Enterprise Developer with their own tooling and for administrators who are implementing the integration with the additional preprocessors.
Parent topic: General Reference
Related information
Creating Preprocessors for Enterprise Developer


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
FLAG
MF, MFLEVEL
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
FLAG
MF, MFLEVEL
PREPROCESS, P
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
FLAG
MF, MFLEVEL
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
Related reference
The COPY Statement
FLAG
MF, MFLEVEL
The REPLACE Statement
Related information
Handling COPY Statements


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
FLAG
MF, MFLEVEL


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 tasks
Additional Preprocessors
Related reference
The COPY Statement
The REPLACE Statement
FLAG
MF, MFLEVEL


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

To do the same using the Additional Preprocessors properties, the CP preprocessor must appear after the COBSQL preprocessor in the list. You can click Up/Down to change the order of the preprocessors.

  • 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
Related reference
The COPY Statement
FLAG
MF, MFLEVEL
The REPLACE Statement
Related information
Handling COPY Statements


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
FLAG
MF, MFLEVEL


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


Integrating Preprocessors into Enterprise Developer

This document walks you through the process of integrating additional preprocessors with Micro Focus Enterprise Developer. It is intended for third-party vendors who want to extend Enterprise Developer with their own tooling and for administrators who are implementing the integration with the additional preprocessors.
Note: Additional preprocessors integrated with Enterprise Developer are supported only in native COBOL applications.

Enterprise Developer is a contemporary development suite for Microsoft Visual Studio or Eclipse that enables mainframe developers to maintain, develop and modernize mainframe applications environments regardless of whether they are to be deployed back on the mainframe or onto an alternative platform.

Enterprise Developer is the smart and simple way to modernize, develop and maintain mainframe applications. It offers advanced capabilities editing, debugging, compiling, and integrated testing.

Some of the Enterprise Developer functionality can be extended with third-party tooling for which several extension points exist. For example, Enterprise Developer can be extended with additional code generation tools such as preprocessors and precompilers.

Though often the two terms are used interchangeably, there is a slight difference between the two:

  • A preprocessor is a technology that converts the source code before it is passed to the COBOL Compiler. A preprocessor takes and modifies the original source code in the memory, and does not generate a new source file. Background syntax checking is supported for preprocessors and debugging debugs the original source file.
  • Precompilers take the original source code and generate a COBOL source file from it. This new COBOL source file is the one that is compiled by the COBOL Compiler. Background syntax checking is not supported in the generated file and debugging only debugs the generated file and not the original source file.

This guide uses the term preprocessors but the instructions equally apply when you are integrating precompilers.

Note:
  • Currently, Micro Focus supports the integration of additional preprocessors and precompilers with Enterprise Developer. To integrate other tools with Enterprise Developer you need to create either Visual Studio extensions or standard Eclipse plugins.
  • If you need assistance with technical issues regarding the integration of additional preprocessors, contact Micro Focus SupportLine.
  • Creating Preprocessors for Enterprise Developer
  • Integrating a Preprocessor with Enterprise Developer
  • Installing an Additional Preprocessor
  • Invoking the Integrated Preprocessor from within Enterprise Developer
Parent topic: Integrated Preprocessor Interface


Creating Preprocessors for Enterprise Developer

The Integrated Preprocessor Interface in Enterprise Developer enables you to write your own preprocessors that read the original source files and pass modified code to the COBOL Compiler. When you configure a project or a file to use additional preprocessors, the preprocessing is done before invoking the COBOL Compiler.

The Enterprise Developer documentation contains information on how to create your own preprocessors for use with Enterprise Developer. Choose General Reference > Integrated Preprocessor Interface from the Table-of-Contents for more information.

  • The existing Micro Focus preprocessor architecture is fully supported in Enterprise Developer.
  • You can stack preprocessors – this means you can use multiple preprocessors to handle the source code before passing it to the COBOL Compiler.
  • The Integrated Preprocessor Interface enables preprocessors to pass error messages to the COBOL Compiler. The Compiler automatically formats the messages and presents the text in the IDE in the same way as it does for a regular COBOL error message.

Preprocessor Requirements

When writing an additional preprocessor you must ensure that it:

  • Caters for setting any environment configurations required by the preprocessor itself or by any sub-modules. To achieve this, the preprocessor needs to read the configurations information in the registry for the ADDONS registry keys – see the information further in this document.
  • Does not assume that any environment variables have being set prior to invoking it.
  • Is responsible for ensuring that the code inserted in the user application is self-contained.
  • Does not assume that Enterprise Developer sets any environment variables before the preprocessor is called.
Parent topic: Integrating Preprocessors into Enterprise Developer
Related information
Integrating a Preprocessor with Enterprise Developer
Installing an Additional Preprocessor
Invoking the Integrated Preprocessor from within Enterprise Developer


Integrating a Preprocessor with Enterprise Developer

You integrate additional preprocessors with Enterprise Developer through the use of specific registry keys and settings. These enable Enterprise Developer to locate the additional preprocessor and display its details within the project and the file properties.

Parent topic: Integrating Preprocessors into Enterprise Developer
Related tasks
Additional Preprocessors
Related information
Creating Preprocessors for Enterprise Developer
Installing an Additional Preprocessor
Invoking the Integrated Preprocessor from within Enterprise Developer


Installing an Additional Preprocessor

There are two ways to install an additional preprocessor:

  • Using a setup file – you can supply a setup file that installs the preprocessor executable and creates the required registry settings – see Creating Registry Settings.
  • Manually - you can manually create the required registry settings that point to the preprocessor executable.
Warning: Before you make changes to a registry key or subkey, Micro Focus recommends that you export, or make a backup copy, of the registry key values.
  • Creating Registry Entries
Parent topic: Integrating Preprocessors into Enterprise Developer
Related information
Creating Preprocessors for Enterprise Developer
Integrating a Preprocessor with Enterprise Developer
Invoking the Integrated Preprocessor from within Enterprise Developer


Creating Registry Entries

In order for Enterprise Developer to recognize a preprocessor which is installed on the same machine, you need to create the following registry structure and registry entries to integrate a single or multiple instances of an additional preprocessor.

In the following steps, we assume that you are integrating the preprocessor "XYZ preprocessor" from MyCompany and "ABC preprocessor" from AnotherCompany.

  • To add an instance of an additional preprocessor
  • To add another instance of the same preprocessor
  • To add more additional preprocessors
Parent topic: Installing an Additional Preprocessor


To add an instance of an additional preprocessor

  1. Click Start.
  2. Type regedit in the Search programs and files field.
  3. Press Enter, this starts the Registry Editor application.
  4. Create a root node key ADDONS for all Enterprise Developer add-ons:

    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Micro Focus\Visual COBOL\2.3\ADDONS

  5. Create the following subtree of registry keys within the root node:
    1. Create a key, MyAddon1 - this is the brand name of your add-on as it will appear in the project and file properties. In our example, MyAddon1 is MyCompany:

      HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Micro Focus\Visual COBOL\2.3\ADDONS\MyCompany

  6. For the MyAddon1 key, create a registry value for the version of the preprocessor to use – Version with value of 1.0 if that is the version of the preprocessor to use:

  7. Create a subkey versionPreproc1 under MyAddon1 for the version number of the preprocessor to use. This indicates the active preprocessor to be used and should match the value of the registry entry Version specified for MyAddon1 .

    In this example, the key should be 1.0:

    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Micro Focus\Visual COBOL\2.3\ADDONS\MyCompany\1.0

  8. Create a subkey PreProcessor under the versionPreproc1 key:

    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Micro Focus\Visual COBOL\2.3\ADDONS\MyCompany\1.0\PreProcessor

  9. Within this node, create the following group of registry entries:
    Registry entry | Value | Description
    PP_01 P(path\mypreprocessor.ext)

    or, for precompilers (Windows only):

    PCOMP(path\myprecompiler.ext)

            Where path\mypreprocessor.ext is the full path to the executable file for your preprocessor or precompiler.
    PPName_01 PreprocessorName

    The name of the preprocessor or the precompiler (Windows only) as it should appear in Enterprise Developer.

    For example: “XYZ preprocessor”.

    PPOptions_01 Preprocessor arguments

    Arguments to pass to the preprocessor when it is selected in Enterprise Developer. Optional (you do not need to specify PPOptions_01 if the preprocessor does not take any arguments).

    For example, the XYZ preprocessor might recognize “-r -s” as valid arguments.

    PPExtension_01 ext File extensions that should be treated as COBOL by Enterprise Developer so they are recognized as a valid resource for the COBOL Compiler. Optional.

    (Windows only) Source code that needs to be processed by a precompiler often does not have a .cbl extension. If the extension is not defined using this registry entry, such files will be ignored.

    PPBGP_01 | 1 or 0 | A Boolean to specify if background parsing is supported (1) or not (0).

In our example, your registry entries look as follows:

This is how you can select your preprocessor in the project properties in Enterprise Developer

Parent topic: Creating Registry Entries
Related information
To add another instance of the same preprocessor
To add more additional preprocessors


To add another instance of the same preprocessor

In the table in the previous task, To add an instance of an additional preprocessor, note that the preprocessor keys have a numeric suffix "_01". You can use the subsequent numbers "_02", "_03" and so on to create multiple preprocessor instances from the same ADDONS, if required. This might be helpful if you need to use the same preprocessor with different directives and you do not want to type them every time.

To create another instance of the same preprocessor:

  1. Add a second set of the same registry entries for the PreProcessor key but use a different numeric suffix – for example, PP_02, PPName_02, and so on.

    You can name this second instance of the preprocessor – "XYZ preprocessor (no directives)“ – as this instance will not use any arguments.

For example, you can create another instance of the "XYZ preprocessor" for which you do not pass preprocessor options:

The image below shows how the two instances of the preprocessor will appear in the project and file properties in Visual Studio:

This is how Enterprise Developer shows the two instances of the same preprocessor in the project properties in Enterprise Developer

Parent topic: Creating Registry Entries
Related information
To add an instance of an additional preprocessor
To add more additional preprocessors


To add more additional preprocessors

You can add more additional preprocessors by adding the required registry keys and entries in the ADDONS root node following the process described earlier. As an example, we shall integrate the "ABC preprocessor" from AnotherCompany.

  1. In the registry editor, under the ADDONS key, create a subkey AnotherTool, then a subkey for the version of the ABC preprocessor, and a subkey PreProcessor:

    \AnotherTool\versionPreproc2\PreProcessor

    For example, if you want to use version 2.5 of the ABC preprocessor from AnotherCompany, the registry tree looks like this:

    HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Micro Focus\Visual COBOL\2.3\ADDONS\AnotherCompany\2.5\PreProcessor

  2. Create a new value, Version, for the AnotherTool key and assign to it the value 2.5 which points to the active version of the preprocessor to use and must match the versionPreproc2 subkey.

  3. For the PreProcessor subkey, create the group of registry entries To add an instance of an additional preprocessor

This is how Enterprise Developer shows the ABC preprocessor within the project and the file properties:

Parent topic: Creating Registry Entries
Related information
To add an instance of an additional preprocessor
To add another instance of the same preprocessor


Invoking the Integrated Preprocessor from within Enterprise Developer

When Enterprise Developer searches for additional preprocessors it checks the ADDONS registry tree and enumerates through all preprocesors’ names. It then provides a list of the additional preprocessors within the project and the file property pages, and the build configuration pages. The information about any additional preprocessors and preprocessor arguments is then saved with the other build and compile settings in the COBOL project file (.cobolProj).

Specify a preprocessor to use with your project

To specify an additional preprocessor for use with your project:

  1. Click Project > Properties.
  2. Click Micro Focus > Project Settings > COBOL > Additional Preprocessors.
  3. Specify a preprocessor to use with your project:
    • To specify your own or third-party preprocessor to use with your project:
      1. Click New. This displays the Add Custom Preprocessor dialog box.
      2. Type the name of the preprocessor in the Name field.
      3. Specify the location of the preprocessor in the Location field. Alternatively, click Browse and navigate to the preprocessor location.
      4. Type the directives in the Directives field. Use space to separate multiple directives.
    • To specify an installed preprocessor to use with your project:
      1. Click Installed, this will display the Add Installed Preprocessor dialog box.
      2. In the Name list, select the installed preprocessor to use.
      3. Type any required directives in the Directives field.
      4. Click OK.

        If you name the preprocessor the same as an existing preprocessor, the IDE prompts you for confirmation to overwrite the existing preprocessor.

      Note: It is not possible to combine the "Micro Focus - EHTML Preprocessor" and "Micro Focus - XML Preprocessor" with other preprocessors. Selecting one of these preprocessors will prevent you from adding any other additional preprocessors. See Integrating Preprocessors into Enterprise Developer for instructions about how to integrate an additional preprocessor with the list in Enterprise Developer.
  4. Click OK to save your changes.

Each preprocessor you add is inserted at the top of the list on the Preprocessor page. The order of execution of preprocessors is from the top to the bottom of the list.

Specify a preprocessor to use with a build configuration

To enable an additional preprocessor for a build configuration:

  1. Click Project > Properties.
  2. Expand Micro Focus > Build Configurations > COBOL.
  3. Click Additional Preprocessors.
  4. Select the Build Configuration.
  5. Check Enable configuration specific settings.
  6. Specify a preprocessor to use with your selected build configuration:
    • To specify your own or third-party preprocessor to use with your build configuration:
      1. Click New, this will display the Add Custom Preprocessor dialog box.
      2. Type the name of the preprocessor in the Name field.
      3. Specify the location of the preprocessor in the Location field. Alternatively, click Browse and navigate to the preprocessor location.
      4. Type the directives in the Directives field. You can add multiple directives by creating a space separated list.
    • To specify an installed preprocessor to use with your build configuration:
      1. Click Installed, this will display the Add Installed Preprocessor dialog box.
      2. In the Name list, select the installed preprocessor to use.
      3. Type any required directives in the Directives field.
      4. Click OK.

        If you name the preprocessor the same as an existing preprocessor, the IDE will prompt you for confirmation to overwrite the existing preprocessor.

      Note: It is not possible to combine the "Micro Focus - EHTML Preprocessor" and "Micro Focus - XML Preprocessor" with other preprocessors. Selecting one of these preprocessors will prevent you from adding any other additional preprocessors. See Integrating Preprocessors into Enterprise Developer for instructions about how to integrate an additional preprocessor with the list in Enterprise Developer.
  7. Click OK to save your changes.

Each preprocessor you add is inserted at the top of the list on the Preprocessor page. The order of execution of preprocessors is from the top to the bottom of the list.

Specify a preprocessor to use with a file

To enable an additional preprocessor for an individual file in your project:

  1. In COBOL Explorer, right-click a COBOL program in your project, and click Properties.
  2. Click COBOL > Additional Preprocessors.
  3. Check Enable file specific settings.
  4. Specify a preprocessor to use with the selected file:
    • To specify your own or third-party preprocessor to use with your file:
      1. Click New, this will display the Add Custom Preprocessor dialog box.
      2. Type the name of the preprocessor in the Name field.
      3. Specify the location of the preprocessor in the Location field. Alternatively, click Browse and navigate to the preprocessor location.
      4. Type the directives in the Directives field. You can add multiple directives by creating a space separated list.
    • To specify an installed preprocessor to use with your file:
      1. Click Installed, this will display the Add Installed Preprocessor dialog box.
      2. In the Name list, select the installed preprocessor to use.
      3. Type any required directives in the Directives field.
      4. Click OK.

        If you name the preprocessor the same as an existing preprocessor, the IDE will prompt you for confirmation to overwrite the existing preprocessor.

      Note: It is not possible to combine the "Micro Focus - EHTML Preprocessor" and "Micro Focus - XML Preprocessor" with other preprocessors. Selecting one of these preprocessors will prevent you from adding any other additional preprocessors. See Integrating Preprocessors into Enterprise Developer for instructions about how to integrate an additional preprocessor with the list in Enterprise Developer.
  5. Click OK to save your changes.

Each preprocessor you add is inserted at the top of the list on the Preprocessor page. The order of execution of preprocessors is from the top to the bottom of the list.

Parent topic: Integrating Preprocessors into Enterprise Developer
Related information
Creating Preprocessors for Enterprise Developer
Integrating a Preprocessor with Enterprise Developer
Installing an Additional Preprocessor


Java Artifacts

  • Micro Focus Resource Adapters
  • ECI Implementation (mfccl.jar)
Parent topic: General Reference


Micro Focus Resource Adapters

  • COBOL Resource Adapter
  • CICS Resource Adapter
  • CICS IBM ECI 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.
  • COBOL Connector Class Library
    Provides instructions for viewing COBOL connector class library documentation.
  • 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

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 batch command (Windows) or shell script (UNIX), ravaluesupdater, and runs from the command line. The ravaluesupdater utility file is located by default in your %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee (Windows) or $COBDIR/javaee (UNIX) directory.

To run the COBOL Resource Adapter utility

Windows:

  1. Start an Enterprise Developer command prompt as an administrator. If you need instructions, see Starting an Enterprise Developer command prompt as an administrator.
  2. Change to the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee directory.
  3. Enter ravaluesupdater.bat.
  4. Follow the prompts to change appropriate parameter values.

UNIX:

  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
Related tasks
To start an Enterprise Developer command prompt as an administrator


COBOL Connector Class Library

Documentation for all COBOL connector classes and supported Java EE versions are provided in HTML format and located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee\docs\javaeex (Windows) or $COBDIR/javaee/docs/javaeex (UNIX) directory, where x represents the Java EE version of 5, 6, or 7.

To view the documentation, navigate to the appropriate subdirectory of the javaee\docs (Windows) or javaee/docs (UNIX) directory and open the index.html file in your browser.

For additional information on the layout of the Java COBOL connector classes documentation, open the help-doc.html file in the same location.

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 %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee (Windows) or /javaee (UNIX) 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


CICS Resource Adapter

  • WebSphere 8.5 CICS Resource Adapter Configuration
    Describes the steps required to install and configure the WebSphere 8.5 CICS resource adapter.
  • JBoss EAP 6.4 CICS Resource Adapter Configuration
    Describes the steps required to install and configure the JBoss EAP 6.4 CICS resource adapter.
  • ra.xml file
    Describes the contents of the ra.xml file, which includes a list of properties that configure your CICS resource adapter.
  • CICS (ECI) Connector Class Library
    Provides instructions for viewing CICS (ECI) connector class library documentation.
  • Using SSL with the CICS Resource Adapter
    Describes how to configure an enterprise server to use SSL with the Micro Focus CICS resource adapter.
  • Sample EJBs
    Sample EJB code that includes the code required to connect to the Micro Focus CICS resource adapter.
Parent topic: Micro Focus Resource Adapters


WebSphere 8.5 CICS Resource Adapter Configuration

Describes the steps required to install and configure the WebSphere 8.5 CICS resource adapter.
Install the CICS resource adapter:
  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 mfcics-notx-ws85.rar file. The new resource adapter is now listed on the right.

Create a new J2C Connection Factory
  1. From the WebSphere Administrative Console, click the new CICS resource adapter it to display its properties.
  2. Under Additional Properties, click J2C Connection Factories; then click New.
  3. Follow the instructions on the screen to specify:
    • CCIMFCICS_v1.5 as the reference name for the connection factory
    • eis/MFCICS_v1.5 as the JNDI name for the connection factory
  4. Confirm that the CCIMFCICS resource adapter is now listed on the J2C connection factories page of the console.
Configure the CCIMFCICS Resource Adapter for SSL (if required)
  1. Click the J2C Connection Factory that corresponds to the new CCIMFCICS resource adapter; then click Custom Properties.
  2. On the list of resources, make the following changes:
    • To enable SSL, set the secureConnection value to true
    • To enable access to your enterprise server, provide appropriate values for ServerHost and ServerPort
    • To enable tracing, set the trace value to true (optional)
    • Provide appropriate values for KeyRingClass and KeyRingPassword
    This enables the SSL connection.
Parent topic: CICS Resource Adapter
Related reference
Using SSL with the CICS Resource Adapter
ra.xml file


JBoss EAP 6.4 CICS Resource Adapter Configuration

Describes the steps required to install and configure the JBoss EAP 6.4 CICS resource adapter.
  1. Copy the mfcics-notx-jb_eap64.rar file, located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee-ccl\javaee6\jboss64EAP (Windows) or $COBDIR/javaee-ccl/javaee6/jboss64EAP (UNIX) directory, to the standalone\deployments (Windows) or standalone/deployments (UNIX) directory of your JBoss installation.
  2. Add the following code as a first-level child to the <profile> element in the JBoss standalone.xml file, usually located in the standalone\configuration (Windows) or standalone/configuration (UNIX) directory of your JBoss installation:
    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
   <resource-adapters>
      <resource-adapter>
         <archive>mfcics-notx-jb_eap64.rar</archive>
         <transaction-support>NoTransaction</transaction-support>
         <connection-definitions>
            <connection-definition
                class-name="com.microfocus.cics.connector.spi.MFECINoTxManagedConnectionFactory"
                jndi-name="java:/eis/MFCICS_IBM_v1.5" pool-name="MFECIConnectionFactory">
              <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>
  3. In the standalone.xml file, edit the <archive-validation> element (child element of <subsystem xmlns="urn:jboss:domain:jca:1.1">) to read as follows:
    <archive-validation enabled="false" fail-on-error="true" fail-on-warn="false"/>
Parent topic: CICS Resource Adapter
Related reference
Using SSL with the CICS Resource Adapter
ra.xml file


ra.xml file

Describes the contents of the ra.xml file, which includes a list of properties that configure your CICS resource adapter.

The ra.xml file is in the META-INF subdirectory of the resource adapter, located by default in the appropriate application-server-specific directory under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee-ccl (Windows) or $COBDIR/javaee-ccl (UNIX). Its contents include a list of properties in XML format. You can edit this file to configure your CICS resource adapter by modifying the property values.

<config-property>
  <config-property-name>ServerHost</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>localhost</config-property-value>
</config-property>
<config-property>
  <config-property-name>ServerPort</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>9003</config-property-value>
</config-property>
<config-property>
  <config-property-name>Trace</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>
<config-property>
  <config-property-name>SecureGUID</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>
<config-property>
  <config-property-name>secureConnection</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>
<config-property>
  <config-property-name>ReadTimeoutInSeconds</config-property-name>
  <config-property-type>java.lang.Integer</config-property-type>
  <config-property-value>0</config-property-value>
</config-property>
<config-property>
  <config-property-name>OpenTimeoutInSeconds</config-property-name>
  <config-property-type>java.lang.Integer</config-property-type>
  <config-property-value>120</config-property-value>
</config-property>
<config-property>
  <config-property-name>EnterpriseServerSocketCloseDueToInactivity</config-property-name>
  <config-property-type>java.lang.Integer</config-property-type>
  <config-property-value>72</config-property-value>
</config-property>

The following describes each property:

ServerHost
Sets the server host name.
Valid values: Server host machine name or IP address
Default: localhost
ServerPort
Specifies the port used by Enterprise Server Web Services and J2EE listeners.
Valid value: The port number used by Enterprise 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
secureConnection
Turns SSL on or off.
Valid values: true or false
Default: false
ReadTimeoutInSeconds
Sets the wait period, in seconds, that a socket waits before timing out on a read.
Valid values: 0 - timeout wait period is infinite

Any positive integer - represents the number of seconds to wait before timing out

Default: 0
OpenTimeoutInSeconds
Sets the wait period, in seconds, that a socket waits before timing out on a connect.
Valid values: 0 - timeout wait period is infinite

Any positive integer - represents the number of seconds to wait before timing out

Default: 120
EnterpriseServerSocketCloseDueToInactivity
Sets the wait period, in hours, that Enterprise Server waits before closing a socket due to inactivity.
Valid values: 0 - timeout wait period is infinite

Any positive integer - represents the number of hours that Enterprise Server waits before closing a socket

Default: 72
Parent topic: CICS Resource Adapter
Related reference
WebSphere 8.5 CICS Resource Adapter Configuration
JBoss EAP 6.4 CICS Resource Adapter Configuration


CICS (ECI) Connector Class Library

Documentation for all CICS (ECI) connector classes are provided in HTML format and contained in an archive located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee-ccl\docs (Windows) or $COBDIR/javaee-ccl/docs (UNIX) directory.

To view the documentation:

  1. From the javaee-ccl\docs (Windows) or javaee-ccl/docs (UNIX) directory, extract mfcicsra.docs.zip (Windows) or mfcicsra.docs.tgz (UNIX) to a directory of your choice.
  2. Change to the directory that now contains the extracted HTML files.
  3. Open index.html in your browser.

For additional information on the layout of the CICS (ECI) connector classes documentation, open the help-doc.html file located in the same directory as index.html.

Parent topic: CICS Resource Adapter


Using SSL with the CICS Resource Adapter

After installing and configuring the Micro Focus CICS resource adapter, including enabling SSL, you can perform further configuration to establish secure communication between the resource adapter and Enterprise Server. To do this, generate a Java keystore that includes Enterprise Server trusted certificates that can be used by CICS resource adapter programs; then import your trusted root certificate into the keystore.

Configure the RA and Enable SSL
For complete instructions, see either the WebSphere or Java version of the CICS Resource Adapter Configuration topic listed under Related reference below.
Generate a Keystore
  1. Generate a Java keystore using the keytool command provided with the JDK. For example:
    keytool -genkey -alias esServer -keyalg RSA -keystore estrustStore.jks
  2. Provide a password for the generated keystore. (Optional)
Import the Trusted Root Certificate
Here, you set the trusted root certificate to verify the certificate provided by Enterprise Server.
  1. Import the trusted root certificate into your generated Java keystore using the keytool command. For example:
    keytool -import -alias esrootcert
-file CARootcert.pem -keystore estrustStore.jks
  2. If prompted, provide a password for the keystore.

For more information on Enterprise Server and CA certificates, see the Secure Communications (SSL) topic under Deployment. We also provide a demo CA you can use to test your SSL connections. See Using the Demonstration Certificate Authority for details.

We also recommend that you review the additional topics listed below.

Parent topic: CICS Resource Adapter
Related concepts
Secure Communications (SSL)
Using the Demonstration Certificate Authority
Related reference
Using SSL with ECI Programs
CICS Program Call with Commarea using SSL
WebSphere 8.5 CICS Resource Adapter Configuration
JBoss EAP 6.4 CICS Resource Adapter Configuration


Sample EJBs

Sample EJB code that includes the code required to connect to the Micro Focus CICS resource adapter.
Note: To enable SSL for any of these sample EJBs, include the SSL code snippet that shows in bold within the CICS Program Call with Commarea Using SSL sample code.
  • Nonextended LUW (Logical Unit of Work) Samples
  • Extended LUW (Logical Unit of Work) Samples
Parent topic: CICS Resource Adapter


Nonextended LUW (Logical Unit of Work) Samples

  • CICS Program Call with Commarea
    Sample EJB accessing the WebSphere 8.5 or JBoss EAP 6.4 CICS resource adapter using CommArea without extended LUW.
  • CICS Program Call with Commarea using SSL
    Sample EJB for SSL, accessing a CICS resource adapter using CommArea without extended LUW.
  • CICS Program Call with Channels and Containers
    Sample EJB accessing a CICS resource adapter using Channel, without extended LUW.
Parent topic: Sample EJBs


CICS Program Call with Commarea

Sample EJB accessing the WebSphere 8.5 or JBoss EAP 6.4 CICS resource adapter using CommArea without extended LUW.
File CommAreaEJB.java:
package com.mypackage.commareaEJB ;
import javax.ejb.Remote;
@Remote
public interface CommareaEJB {
    public byte[] callMyCICSProgram(byte[] commarea);
    public int getCobolReturnCode();
}
WebSphere 8.5 - File CommareaEJBBean.java:
package com.mypackage.commareaEJB ;

import javax.ejb.Stateless;
import javax.ejb.Stateful;
import javax.ejb.EJB;
import javax.ejb.Init;
import javax.ejb.Remove;
import javax.ejb.PostActivate;
import javax.ejb.PrePassivate;
import javax.ejb.EJBException;
import javax.annotation.Resource;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.ejb.Remote;
import com.microfocus.cics.connector.ccl.CCLExtendMode;
import com.microfocus.cics.connector.ccl.CommArea;
import com.microfocus.cics.connector.ccl.AbendException;
import com.microfocus.cics.connector.ccl.AbendCodeType;
import com.microfocus.cics.connector.ccl.CommAreaSizeException;

@Stateless(name="commareaEJB", mappedName="ejb/commareaEJB")
@Remote(com.mypackage.commareaEJB.CommareaEJB.class)

public class CommareaEJBBean implements CommareaEJB, java.io.Serializable {

    @Resource (name="CCIMFCICS_v1.5", authenticationType=Resource.AuthenticationType.CONTAINER, shareable=true)
    private transient javax.resource.cci.ConnectionFactory cf;
    private boolean disposed = false;
    private String sessionId = null;
    public static final int DEFAULT_COBOL_RETURN_CODE = 2147483647;
    private int cobolReturnCode = DEFAULT_COBOL_RETURN_CODE;

    public javax.resource.cci.ConnectionFactory getConnectionFactory() {
          return cf ;
    }

    @PostConstruct
    public void create() {
       sessionId = null;
    }

     @TransactionAttribute(TransactionAttributeType.NEVER)
    public byte[] callMyCICSProgram(byte[] commarea) throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = null;
        try {
            initialize(true, con);
            ix = con.createInteraction();
            iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("CASA_ECI_Function");
            iSpec.setArgument(0, com.microfocus.cobol.lang.Pointer.class,
                     com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY);
            iSpec.setArgument(1, com.microfocus.cobol.lang.Pointer.class,
                    com.microfocus.cobol.RuntimeProperties.BY_VALUE);
        iSpec.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);
        iSpec.setUserName("SYSAD");
          iSpec.setPassword("SYSAD");
        iSpec.setProgramName("EC01");
        iSpec.setCommArea(new CommArea(commarea));

          rf = cf.getRecordFactory();
          javax.resource.cci.IndexedRecord iRec = iSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(iSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = iSpec.getReturnCode();
            CommArea returnCommArea = iSpec.getReturnCommArea();
        byte[] retCommArea = returnCommArea.getCommArea();
        return retCommArea;

    } catch(javax.resource.ResourceException ex) {
            cobolReturnCode = iSpec.getReturnCode();
        Exception linkedEx = ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(java.io.UnsupportedEncodingException ex) {
            cobolReturnCode = iSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(CommAreaSizeException ex) {
            cobolReturnCode = iSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        }

        finally {
            closeCobolConnection(con);
            con = null; iSpec = null; ix = null; rf = null;
            sessionId = null;
        }
    }

    void cleanup() throws javax.ejb.EJBException {
    }

    public int getCobolReturnCode() throws javax.ejb.EJBException {
         return cobolReturnCode;
    }

    @PrePassivate
    public void passivate() throws javax.ejb.EJBException {
    }

    @PostActivate
    public void activate() throws javax.ejb.EJBException {
    }

    private void initialize(boolean isInitial, javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            javax.resource.cci.Interaction ix = con.createInteraction();
            com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("initialize");
            javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord irec = rf.createIndexedRecord("beanArgs");
            irec.add(new Boolean(isInitial));
            javax.resource.cci.Record orec = ix.execute(iSpec, irec);
            ix.close();
            rf = null ; ix = null ; iSpec = null ; irec = null ;
        } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("initialize threw ResourceException: ", ex);
        }
    }

    private javax.resource.cci.Connection getCobolConnection() throws javax.ejb.EJBException {

            com.microfocus.cics.connector.cci.MFECIConnection con = null;
        try {
            con = (com.microfocus.cics.connector.cci.MFECIConnection) cf.getConnection(new com.microfocus.cics.connector.cci.MFECIConnectionSpec(false, sessionId));

        } catch (javax.resource.ResourceException ex) {
             throw new javax.ejb.EJBException("Error getting a Cobol Connection: ", ex);
        }
        return con ;
    }

    private void closeCobolConnection(javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            if(con != null) {
              con.close();
            }
        } catch (javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error closing a Cobol Connection: ", ex);
        }
    }

}
JBoss EAP 6.4 - File CommareaEJBBean.java:
package com.mypackage.commareaEJB ;

import javax.ejb.Stateless;
import javax.ejb.Stateful;
import javax.ejb.EJB;
import javax.ejb.Init;
import javax.ejb.Remove;
import javax.ejb.PostActivate;
import javax.ejb.PrePassivate;
import javax.ejb.EJBException;
import javax.annotation.Resource;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.ejb.Remote;
import com.microfocus.cics.connector.ccl.CCLExtendMode;
import com.microfocus.cics.connector.ccl.CommArea;
import com.microfocus.cics.connector.ccl.AbendException;
import com.microfocus.cics.connector.ccl.AbendCodeType;
import com.microfocus.cics.connector.ccl.CommAreaSizeException;

@Stateless(name="commareaEJB", mappedName="ejb/commareaEJB")
@Remote(com.mypackage.commareaEJB.CommareaEJB.class)

public class CommareaEJBBean implements CommareaEJB, java.io.Serializable {

    @Resource (name="CCIMFCICS_v1.5", authenticationType=Resource.AuthenticationType.CONTAINER, shareable=true, mappedName="java:/eis/MFCICS_v1.5")
    private transient javax.resource.cci.ConnectionFactory cf;
    private boolean disposed = false;
    private String sessionId = null;
    public static final int DEFAULT_COBOL_RETURN_CODE = 2147483647;
    private int cobolReturnCode = DEFAULT_COBOL_RETURN_CODE;

    public javax.resource.cci.ConnectionFactory getConnectionFactory() {
          return cf ;
    }

    @PostConstruct
    public void create() {
       sessionId = null;
    }

     @TransactionAttribute(TransactionAttributeType.NEVER)
    public byte[] callMyCICSProgram(byte[] commarea) throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = null;
        try {
            initialize(true, con);
            ix = con.createInteraction();
            iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("CASA_ECI_Function");
            iSpec.setArgument(0, com.microfocus.cobol.lang.Pointer.class,
                     com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY);
            iSpec.setArgument(1, com.microfocus.cobol.lang.Pointer.class,
                    com.microfocus.cobol.RuntimeProperties.BY_VALUE);
        iSpec.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);
        iSpec.setUserName("SYSAD");
          iSpec.setPassword("SYSAD");
        iSpec.setProgramName("EC01");
        iSpec.setCommArea(new CommArea(commarea));

          rf = cf.getRecordFactory();
          javax.resource.cci.IndexedRecord iRec = iSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(iSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = iSpec.getReturnCode();
            CommArea returnCommArea = iSpec.getReturnCommArea();
        byte[] retCommArea = returnCommArea.getCommArea();
        return retCommArea;

    } catch(javax.resource.ResourceException ex) {
            cobolReturnCode = iSpec.getReturnCode();
        Exception linkedEx = ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(java.io.UnsupportedEncodingException ex) {
            cobolReturnCode = iSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(CommAreaSizeException ex) {
            cobolReturnCode = iSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        }

        finally {
            closeCobolConnection(con);
            con = null; iSpec = null; ix = null; rf = null;
            sessionId = null;
        }
    }

    void cleanup() throws javax.ejb.EJBException {
    }

    public int getCobolReturnCode() throws javax.ejb.EJBException {
         return cobolReturnCode;
    }

    @PrePassivate
    public void passivate() throws javax.ejb.EJBException {
    }

    @PostActivate
    public void activate() throws javax.ejb.EJBException {
    }

    private void initialize(boolean isInitial, javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            javax.resource.cci.Interaction ix = con.createInteraction();
            com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("initialize");
            javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord irec = rf.createIndexedRecord("beanArgs");
            irec.add(new Boolean(isInitial));
            javax.resource.cci.Record orec = ix.execute(iSpec, irec);
            ix.close();
            rf = null ; ix = null ; iSpec = null ; irec = null ;
        } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("initialize threw ResourceException: ", ex);
        }
    }

    private javax.resource.cci.Connection getCobolConnection() throws javax.ejb.EJBException {

            com.microfocus.cics.connector.cci.MFECIConnection con = null;
        try {
            con = (com.microfocus.cics.connector.cci.MFECIConnection) cf.getConnection(new com.microfocus.cics.connector.cci.MFECIConnectionSpec(false, sessionId));

        } catch (javax.resource.ResourceException ex) {
             throw new javax.ejb.EJBException("Error getting a Cobol Connection: ", ex);
        }
        return con ;
    }

    private void closeCobolConnection(javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            if(con != null) {
              con.close();
            }
        } catch (javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error closing a Cobol Connection: ", ex);
        }
    }

}
Parent topic: Nonextended LUW (Logical Unit of Work) Samples
Related reference
CICS Program Call with Commarea using SSL


CICS Program Call with Commarea using SSL

Sample EJB for SSL, accessing a CICS resource adapter using CommArea without extended LUW.
Note: Code in bold is specifically for SSL. You can include this same snippet in any of the sample EJBs to enable SSL.
File CommAreaEJB.java:
package com.mypackage.commareaEJB ;

import javax.ejb.Remote;
@Remote
public interface CommareaEJB {
    public byte[] First(byte[] commarea);
    public int getCobolReturnCode();
}
File CommareaEJBBean.java:
package com.mypackage.commareaEJB ;

import javax.ejb.Stateless;
import javax.ejb.Stateful;
import javax.ejb.EJB;
import javax.ejb.Init;
import javax.ejb.Remove;
import javax.ejb.PostActivate;
import javax.ejb.PrePassivate;
import javax.ejb.EJBException;
import javax.annotation.Resource;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.ejb.Remote;
import com.microfocus.cics.connector.ccl.CCLExtendMode;
import com.microfocus.cics.connector.ccl.CommArea;
import com.microfocus.cics.connector.ccl.AbendException;
import com.microfocus.cics.connector.ccl.AbendCodeType;
import com.microfocus.cics.connector.ccl.CommAreaSizeException;

@Stateless(name="commareaEJB", mappedName="ejb/commareaEJB")
@Remote(com.mypackage.commareaEJB.CommareaEJB.class)

public class CommareaEJBBean implements CommareaEJB, java.io.Serializable {

    @Resource (name="CCIMFCICS_v1.5", authenticationType=Resource.AuthenticationType.CONTAINER, shareable=true)
    private transient javax.resource.cci.ConnectionFactory cf;
    private boolean disposed = false;
    private String sessionId = null;
    public static final int DEFAULT_COBOL_RETURN_CODE = 2147483647;
    private int cobolReturnCode = DEFAULT_COBOL_RETURN_CODE;

    public javax.resource.cci.ConnectionFactory getConnectionFactory() {
          return cf ;
    }

    @PostConstruct
    public void create() {            sessionId = null;
    }

    /**
     *     @ejb:interface-method
     *     @ejb:transaction type="RequiresNew"
     *
     *     @output byte[]	commarea
     */
     @TransactionAttribute(TransactionAttributeType.NEVER)
    public byte[] First(byte[] commarea) throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = null;
        try {
            initialize(true, con);
            ix = con.createInteraction();
            iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("CASA_ECI_Function");
            iSpec.setArgument(0, com.microfocus.cobol.lang.Pointer.class,
                     com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY);
            iSpec.setArgument(1, com.microfocus.cobol.lang.Pointer.class,
                    com.microfocus.cobol.RuntimeProperties.BY_VALUE);
        iSpec.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);
        iSpec.setUserName("SYSAD");
            iSpec.setPassword("SYSAD");
        iSpec.setProgramName("EC01");
        iSpec.setCommArea(new CommArea(commarea));

            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord iRec = iSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(iSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = iSpec.getReturnCode();
            CommArea returnCommArea = iSpec.getReturnCommArea();
        byte[] retCommArea = returnCommArea.getCommArea();
        return retCommArea;

    } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = iSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = iSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(CommAreaSizeException __ex) {
            cobolReturnCode = iSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }

        finally {
            closeCobolConnection(con);
            con = null; iSpec = null; ix = null; rf = null;
            sessionId = null;
        }
    }

    void cleanup() throws javax.ejb.EJBException {
    }

    public int getCobolReturnCode() throws javax.ejb.EJBException {
         return cobolReturnCode;
    }

    @PrePassivate
    public void passivate() throws javax.ejb.EJBException {
    }

    @PostActivate
    public void activate() throws javax.ejb.EJBException {
    }

    private void initialize(boolean isInitial, javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            javax.resource.cci.Interaction ix = con.createInteraction();
            com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("initialize");
            javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord irec = rf.createIndexedRecord("beanArgs");
            irec.add(new Boolean(isInitial));
            javax.resource.cci.Record orec = ix.execute(iSpec, irec);
            ix.close();
            rf = null ; ix = null ; iSpec = null ; irec = null ;
        } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("initialize threw ResourceException: ", ex);
        }
    }

    private javax.resource.cci.Connection getCobolConnection() throws javax.ejb.EJBException {

            com.microfocus.cics.connector.cci.MFECIConnection con = null;
        try {
            con = (com.microfocus.cics.connector.cci.MFECIConnection) cf.getConnection(new com.microfocus.cics.connector.cci.MFECIConnectionSpec(false, sessionId));
    //SSL
        try {
            con.setTrustStoreName("C:/test/estrustStore.jks");
            con.setTrustStorePassword("srvrootpwd");
            } catch (Exception e) {
                throw new javax.ejb.EJBException(e);
            }

        } catch (javax.resource.ResourceException ex) {
             throw new javax.ejb.EJBException("Error getting a Cobol Connection: ", ex);
        }
        return con ;
    }
    private void closeCobolConnection(javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            if(con != null) {
              con.close();
            }
        } catch (javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error closing a Cobol Connection: ", ex);
        }
    }

}
Parent topic: Nonextended LUW (Logical Unit of Work) Samples
Related reference
Using SSL with the CICS Resource Adapter
Using SSL with the CICS IBM ECI Resource Adapter


CICS Program Call with Channels and Containers

Sample EJB accessing a CICS resource adapter using Channel, without extended LUW.
Note: To enable SSL, include the SSL code snippet shown in bold in the CICS Program Call with Commarea Using SSL sample.
File Container.java:
package com.mypackage.channelEJB ;

public class Container extends com.microfocus.cics.connector.cci.MFECICustomRecord {

    private static String EMPTY_STRING = "";
    private java.lang.String containerData = EMPTY_STRING;

    public Container() {
    }

    public java.lang.String getContainerData() {
        return containerData;
    }

    public void setContainerData(java.lang.String ___p) {
        containerData = ___p ;
    }

    public Object[] getParameters() {        Object[] objs = new Object[1];

        objs[0] = containerData;
        return objs;
    }

    public void setParameters(Object[] objs) {
        containerData = (java.lang.String) objs[0];
    }

}
File Channel.java:
package com.mypackage.channelEJB ;

public class Channel extends com.microfocus.cics.connector.cci.MFECICustomRecord {

    private static String EMPTY_STRING = "";
    private Container2 container2;
    private Container1 container1;

    public class Container2 extends com.microfocus.cics.connector.cci.MFECICustomRecord {

        private java.lang.String containerData = EMPTY_STRING;

        public Container2() {
        }

        public java.lang.String getContainerData() {
            return containerData;
        }

        public void setContainerData(java.lang.String ___p) {
            containerData = ___p ;
        }

        public Object[] getParameters() {
            Object[] objs = new Object[1];
            objs[0] = containerData;
            return objs;
        }

        public void setParameters(Object[] objs) {
            containerData = (java.lang.String) objs[0];
        }

    }
    public class Container1 extends com.microfocus.cics.connector.cci.MFECICustomRecord {

        private java.lang.String containerData = EMPTY_STRING;

        public Container1() {
        }

        public java.lang.String getContainerData() {
            return containerData;
        }

        public void setContainerData(java.lang.String ___p) {
            containerData = ___p ;
        }

        public Object[] getParameters() {
            Object[] objs = new Object[1];
            objs[0] = containerData;
            return objs;
        }

        public void setParameters(Object[] objs) {
            containerData = (java.lang.String) objs[0];
        }

    }
    public Channel() {
        container2 = new Container2();
        container1 = new Container1();
    }

    public Container2 getContainer2() {
        return container2;
    }

    public void setContainer2(Container2 ___p) {
        container2 = ___p ;
    }

    public Container1 getContainer1() {
        return container1;
    }

    public void setContainer1(Container1 ___p) {
        container1 = ___p ;
    }

    public Object[] getParameters() {        Object[] objs = new Object[2];

        objs[0] = container2;
        objs[1] = container1;
        return objs;
    }

    public void setParameters(Object[] objs) {
        container2.setParameters(((Container2)objs[0]).getParameters());
        container1.setParameters(((Container1)objs[1]).getParameters());
    }

}
File ChannelEJB.java:
package com.mypackage.channelEJB ;

import javax.ejb.Remote;
@Remote
public interface ChannelEJB {
    public com.mypackage.channelEJB.Channel First(com.mypackage.channelEJB.Channel channel);
    public int getCobolReturnCode();
}
File ChannelEJBBean.java

package com.mypackage.channelEJB ;

import javax.ejb.Stateless;
import javax.ejb.Stateful;
import javax.ejb.EJB;
import javax.ejb.Init;
import javax.ejb.Remove;
import javax.ejb.PostActivate;
import javax.ejb.PrePassivate;
import javax.ejb.EJBException;
import javax.annotation.Resource;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.ejb.Remote;
import com.microfocus.cics.connector.ccl.CCLExtendMode;
import com.microfocus.cics.connector.ccl.CCLChannel;
import com.microfocus.cics.connector.ccl.CCLContainer;
import com.microfocus.cics.connector.ccl.ContainerData;
import com.microfocus.cics.connector.ccl.AbendException;
import com.microfocus.cics.connector.ccl.AbendCodeType;

import java.util.List;

@Stateless(name="channelEJB", mappedName="ejb/channelEJB")
@Remote(com.mypackage.channelEJB.ChannelEJB.class)

public class ChannelEJBBean implements ChannelEJB, java.io.Serializable {

    @Resource (name="CCIMFCICS_v1.5", authenticationType=Resource.AuthenticationType.CONTAINER, shareable=true)
    private transient javax.resource.cci.ConnectionFactory cf;
    private boolean disposed = false;
    private String sessionId = null;
    public static final int DEFAULT_COBOL_RETURN_CODE = 2147483647;
    private int cobolReturnCode = DEFAULT_COBOL_RETURN_CODE;

    public javax.resource.cci.ConnectionFactory getConnectionFactory() {
          return cf ;
    }

    @PostConstruct
    public void create() {            sessionId = null;
    }

     @TransactionAttribute(TransactionAttributeType.NEVER)
    public com.mypackage.channelEJB.Channel First(com.mypackage.channelEJB.Channel channel) throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = null;
        try {
            initialize(true, con);
            ix = con.createInteraction();
            iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("channel.First");
            iSpec.setFunctionName("CASA_ECI_Function");
            iSpec.setArgument(0, com.microfocus.cobol.lang.Pointer.class,
                     com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY);
            iSpec.setArgument(1, com.microfocus.cobol.lang.Pointer.class,
                    com.microfocus.cobol.RuntimeProperties.BY_VALUE);
        iSpec.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);
        iSpec.setUserName("SYSAD");
            iSpec.setPassword("SYSAD");
        iSpec.setProgramName("EC03");

            CCLChannel cclChannel = new CCLChannel("GenChannel");
        CCLContainer cclContainer1 = new CCLContainer("GenCon1");
        CCLContainer cclContainer2 = new CCLContainer("GenCon2");
        byte[] cData1 = channel.getContainer1().getContainerData().getBytes();
        byte[] cData2 = channel.getContainer2().getContainerData().getBytes();
        ContainerData cd1 = new ContainerData(cData1);
            ContainerData cd2 = new ContainerData(cData2);
        cclContainer1.setContainerData(cd1);
            cclContainer2.setContainerData(cd2);
            cclChannel.addContainer(cclContainer1);
            cclChannel.addContainer(cclContainer2);
        iSpec.setChannel(cclChannel);
            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            javax.resource.cci.IndexedRecord iRec = iSpec.getInputRecord();
            ix.execute(iSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = iSpec.getReturnCode();
             CCLChannel returnChannel = iSpec.getReturnChannel();
        com.mypackage.channelEJB.Channel retFromEJBChannel = new com.mypackage.channelEJB.Channel();
        if(returnChannel != null) {
            List<CCLContainer> containers = returnChannel.getContainers();
            int count = 0;
            for(CCLContainer container: containers) {
                        if(count == 0) {
                retFromEJBChannel.getContainer1().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            if(count == 1) {
                retFromEJBChannel.getContainer2().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            System.out.println(container.getContainerName());
            System.out.println(container.getContainerData().getContainerData());
                }
        }
        return retFromEJBChannel;

        } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = iSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = iSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }
        finally {
            closeCobolConnection(con);
            con = null; iSpec = null; ix = null; rf = null;
            sessionId = null;
        }
    }

    void cleanup() throws javax.ejb.EJBException {
    }

    public int getCobolReturnCode() throws javax.ejb.EJBException {
         return cobolReturnCode;
    }

    @PrePassivate
    public void passivate() throws javax.ejb.EJBException {
    }

    @PostActivate
    public void activate() throws javax.ejb.EJBException {
    }

    private void initialize(boolean isInitial, javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            javax.resource.cci.Interaction ix = con.createInteraction();
            com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("initialize");
            javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord irec = rf.createIndexedRecord("beanArgs");
            irec.add(new Boolean(isInitial));
            javax.resource.cci.Record orec = ix.execute(iSpec, irec);
            ix.close();
            rf = null ; ix = null ; iSpec = null ; irec = null ;
        } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("initialize threw ResourceException: ", ex);
        }
    }

    private javax.resource.cci.Connection getCobolConnection() throws javax.ejb.EJBException {

            com.microfocus.cics.connector.cci.MFECIConnection con = null;
        try {
            con = (com.microfocus.cics.connector.cci.MFECIConnection) cf.getConnection(new com.microfocus.cics.connector.cci.MFECIConnectionSpec(false, sessionId));

        } catch (javax.resource.ResourceException ex) {
             throw new javax.ejb.EJBException("Error getting a Cobol Connection: ", ex);
        }
        return con ;
    }

    private void closeCobolConnection(javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            if(con != null) {
              con.close();
            }
        } catch (javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error closing a Cobol Connection: ", ex);
        }
    }

}
Parent topic: Nonextended LUW (Logical Unit of Work) Samples
Related reference
CICS Program Call with Commarea using SSL


Extended LUW (Logical Unit of Work) Samples

  • CICS Program Call with Commarea
    Sample EJB accessing a CICS resource adapter using CommArea with extended LUW.
  • CICS Program Call with Channels and Containers
    Sample EJB accessing the WebSphere 8.5 or JBoss EAP 6.4 CICS resource adapter using Channel with extended LUW.
Parent topic: Sample EJBs


CICS Program Call with Commarea

Sample EJB accessing a CICS resource adapter using CommArea with extended LUW.
Note: To enable SSL, include the SSL code snippet shown in bold in the CICS Program Call with Commarea Using SSL sample.
File CommAreaEJB.java:
package com.mypackage.commareaEJB ;
import javax.ejb.Remote;
import javax.ejb.EJBException;
@Remote
public interface CommareaEJB {
    public byte[] First(byte[] commarea) throws javax.resource.ResourceException;
    public int getCobolReturnCode();
    public void removeSF() throws EJBException;
    public void passivate() throws EJBException;
    public void activate() throws EJBException;
}
File CommAreaEJBBean.java:
package com.mypackage.commareaEJB ;
import javax.ejb.Stateless;
import javax.ejb.Stateful;
import javax.ejb.EJB;
import javax.ejb.Init;
import javax.ejb.Remove;
import javax.ejb.PostActivate;
import javax.ejb.PrePassivate;
import javax.ejb.EJBException;
import javax.annotation.Resource;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.ejb.Remote;
import com.microfocus.cics.connector.ccl.CCLExtendMode;
import com.microfocus.cics.connector.ccl.CommArea;
import com.microfocus.cics.connector.ccl.AbendException;
import com.microfocus.cics.connector.ccl.AbendCodeType;
import com.microfocus.cics.connector.ccl.CommAreaSizeException;

@Stateful(name="commareaEJB", mappedName="ejb/commareaEJB")
@Remote(com.mypackage.commareaEJB.CommareaEJB.class)

public class CommareaEJBBean implements CommareaEJB, java.io.Serializable {

    @Resource (name="CCIMFCICS_v1.5", authenticationType=Resource.AuthenticationType.CONTAINER, shareable=false)
    private transient javax.resource.cci.ConnectionFactory cf;
    private boolean disposed = false;
    private String sessionId = null;
    private transient javax.resource.cci.Connection lastConnectionHandle = null;
    private boolean doInitialize = true;
    public static final int DEFAULT_COBOL_RETURN_CODE = 2147483647;
    private int cobolReturnCode = DEFAULT_COBOL_RETURN_CODE;
    com.microfocus.cics.connector.cci.MFECIInteractionSpec interactionSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();

    public javax.resource.cci.ConnectionFactory getConnectionFactory() {
          return cf ;
    }

    @PostConstruct
    public void create() {
        disposed = false;
            sessionId = null;
        interactionSpec.setFunctionName("CASA_ECI_Function");
            interactionSpec.setArgument(0, com.microfocus.cobol.lang.Pointer.class,
                     com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY);
            interactionSpec.setArgument(1, com.microfocus.cobol.lang.Pointer.class,
                    com.microfocus.cobol.RuntimeProperties.BY_VALUE);
        interactionSpec.setUserName("SYSAD");
            interactionSpec.setPassword("SYSAD");
        interactionSpec.setProgramName("EC01");
    }

     @TransactionAttribute(TransactionAttributeType.NEVER)
    public byte[] First(byte[] commarea) throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();

        interactionSpec.setExtendMode(CCLExtendMode.CCL_EXTENDED);
        interactionSpec.setCommArea(new CommArea(commarea));
            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            iRec.add(new com.microfocus.cobol.lang.Pointer(commarea));
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
            CommArea returnCommArea = interactionSpec.getReturnCommArea();
        byte[] retCommArea = returnCommArea.getCommArea();
        return retCommArea;

        } catch(javax.resource.ResourceException ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(java.io.UnsupportedEncodingException ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(CommAreaSizeException ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        }
        finally {
            closeCobolConnection(con);
            ix = null; rf = null;
        }
    }

         @TransactionAttribute(TransactionAttributeType.NEVER)
    public byte[] commit() throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();
        interactionSpec.setExtendMode(CCLExtendMode.CCL_COMMIT);
        rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
            CommArea returnCommArea = interactionSpec.getReturnCommArea();
        byte[] retCommArea = returnCommArea.getCommArea();
        return retCommArea;

        } catch(javax.resource.ResourceException ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(java.io.UnsupportedEncodingException ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        }
        finally {
            closeCobolConnection(con);
            interactionSpec = null; ix = null; rf = null;
        }
    }

             @TransactionAttribute(TransactionAttributeType.NEVER)
    public byte[] rollback() throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();
        interactionSpec.setExtendMode(CCLExtendMode.CCL_BACKOUT);
            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
            CommArea returnCommArea = interactionSpec.getReturnCommArea();
        byte[] retCommArea = returnCommArea.getCommArea();
        return retCommArea;

        } catch(javax.resource.ResourceException ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        } catch(java.io.UnsupportedEncodingException ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", ex);
        }
        finally {
            closeCobolConnection(con);
            interactionSpec = null; ix = null; rf = null;
        }
    }

    @Remove
    public void removeSF() {
            cleanup();
    }

    void cleanup() throws javax.ejb.EJBException {
       try {
            if(!disposed) {
                if(lastConnectionHandle != null) {
                  com.microfocus.cics.connector.cci.MFECIConnection.dispose(sessionId);
                  closeCobolConnection(lastConnectionHandle);
                }
                else {
                  com.microfocus.cics.connector.cci.MFECIConnection.dispose(sessionId);
                }
              disposed = true ;
            }
       } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error disposing a Cobol Connection: ", ex);
       }
       finally {
           lastConnectionHandle = null;
           cf = null;
       }
    }

    public int getCobolReturnCode() throws javax.ejb.EJBException {
         return cobolReturnCode;
    }

    @PrePassivate
    public void passivate() throws javax.ejb.EJBException {
    }

    @PostActivate
    public void activate() throws javax.ejb.EJBException {
    }

    private void initialize(boolean isInitial, javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            javax.resource.cci.Interaction ix = con.createInteraction();
            com.microfocus.cics.connector.cci.MFECIInteractionSpec iSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            iSpec.setFunctionName("initialize");
            javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord irec = rf.createIndexedRecord("beanArgs");
            irec.add(new Boolean(isInitial));
            javax.resource.cci.Record orec = ix.execute(iSpec, irec);
            ix.close();
            rf = null ; ix = null ; iSpec = null ; irec = null ;
        } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("initialize threw ResourceException: ", ex);
        }
    }

    private javax.resource.cci.Connection getCobolConnection() throws javax.ejb.EJBException {

            com.microfocus.cics.connector.cci.MFECIConnection con = null;
        try {
            con = (com.microfocus.cics.connector.cci.MFECIConnection) cf.getConnection(new com.microfocus.cics.connector.cci.MFECIConnectionSpec(true, true, sessionId));
            lastConnectionHandle = con;

        } catch (javax.resource.ResourceException ex) {
             throw new javax.ejb.EJBException("Error getting a Cobol Connection: ", ex);
        }
        return con ;
    }

    private void closeCobolConnection(javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            if(con != null) {
             if(sessionId == null) {
                 sessionId = ((com.microfocus.cics.connector.cci.MFECIConnection)con).getSessionId();
             }
              con.close();
            }
        } catch (javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error closing a Cobol Connection: ", ex);
        }
    }
Parent topic: Extended LUW (Logical Unit of Work) Samples
Related reference
CICS Program Call with Commarea using SSL


CICS Program Call with Channels and Containers

Sample EJB accessing the WebSphere 8.5 or JBoss EAP 6.4 CICS resource adapter using Channel with extended LUW.
Note: To enable SSL, include the SSL code snippet shown in bold in the CICS Program Call with Commarea Using SSL sample.
File Container.java:
package com.mypackage.channelEJB ;

public class Container extends com.microfocus.cics.connector.cci.MFECICustomRecord {

    private static String EMPTY_STRING = "";
    private java.lang.String containerData = EMPTY_STRING;

    public Container() {
    }

    public java.lang.String getContainerData() {
        return containerData;
    }

    public void setContainerData(java.lang.String ___p) {
        containerData = ___p ;
    }

    public Object[] getParameters() {        Object[] objs = new Object[1];

        objs[0] = containerData;
        return objs;
    }

    public void setParameters(Object[] objs) {
        containerData = (java.lang.String) objs[0];
    }

}
File Channel.java:
package com.mypackage.channelEJB ;

public class Channel extends com.microfocus.cics.connector.cci.MFECICustomRecord {

    private static String EMPTY_STRING = "";
    private Container2 container2;
    private Container1 container1;

    public class Container2 extends com.microfocus.cics.connector.cci.MFECICustomRecord {

        private java.lang.String containerData = EMPTY_STRING;

        public Container2() {
        }

        public java.lang.String getContainerData() {
            return containerData;
        }

        public void setContainerData(java.lang.String ___p) {
            containerData = ___p ;
        }

        public Object[] getParameters() {
            Object[] objs = new Object[1];
            objs[0] = containerData;
            return objs;
        }

        public void setParameters(Object[] objs) {
            containerData = (java.lang.String) objs[0];
        }

    }
    public class Container1 extends com.microfocus.cics.connector.cci.MFECICustomRecord {

        private java.lang.String containerData = EMPTY_STRING;

        public Container1() {
        }

        public java.lang.String getContainerData() {
            return containerData;
        }

        public void setContainerData(java.lang.String ___p) {
            containerData = ___p ;
        }

        public Object[] getParameters() {
            Object[] objs = new Object[1];
            objs[0] = containerData;
            return objs;
        }

        public void setParameters(Object[] objs) {
            containerData = (java.lang.String) objs[0];
        }

    }
    public Channel() {
        container2 = new Container2();
        container1 = new Container1();
    }

    public Container2 getContainer2() {
        return container2;
    }

    public void setContainer2(Container2 ___p) {
        container2 = ___p ;
    }

    public Container1 getContainer1() {
        return container1;
    }

    public void setContainer1(Container1 ___p) {
        container1 = ___p ;
    }

    public Object[] getParameters() {        Object[] objs = new Object[2];

        objs[0] = container2;
        objs[1] = container1;
        return objs;
    }

    public void setParameters(Object[] objs) {
        container2.setParameters(((Container2)objs[0]).getParameters());
        container1.setParameters(((Container1)objs[1]).getParameters());
    }

}
File ChannelEJB.java:
package com.mypackage.channelEJB ;

import javax.ejb.Remote;
import javax.ejb.EJBException;

@Remote
public interface ChannelEJB {
    public com.mypackage.channelEJB.Channel First(com.mypackage.channelEJB.Channel channel);
    public int getCobolReturnCode();
    public void removeSF() throws EJBException;
    public void passivate() throws EJBException;
    public void activate() throws EJBException;
}
WebSphere 8.5 - File ChannelEJBBean.java:
package com.mypackage.channelEJB ;

import javax.ejb.Stateless;
import javax.ejb.Stateful;
import javax.ejb.EJB;
import javax.ejb.Init;
import javax.ejb.Remove;
import javax.ejb.PostActivate;
import javax.ejb.PrePassivate;
import javax.ejb.EJBException;
import javax.annotation.Resource;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.ejb.Remote;
import com.microfocus.cics.connector.ccl.CCLExtendMode;
import com.microfocus.cics.connector.ccl.CCLChannel;
import com.microfocus.cics.connector.ccl.CCLContainer;
import com.microfocus.cics.connector.ccl.ContainerData;
import com.microfocus.cics.connector.ccl.AbendException;
import com.microfocus.cics.connector.ccl.AbendCodeType;

import java.util.List;

@Stateful(name="channelEJB", mappedName="ejb/channelEJB")
@Remote(com.mypackage.channelEJB.ChannelEJB.class)

public class ChannelEJBBean implements ChannelEJB, java.io.Serializable {

     @Resource (name="CCIMFCICS_v1.5", authenticationType=Resource.AuthenticationType.CONTAINER, shareable=false)
    private transient javax.resource.cci.ConnectionFactory cf;
    private boolean disposed = false;
    private String sessionId = null;
    private transient javax.resource.cci.Connection lastConnectionHandle = null;
    private boolean doInitialize = true;
    public static final int DEFAULT_COBOL_RETURN_CODE = 2147483647;
    private int cobolReturnCode = DEFAULT_COBOL_RETURN_CODE;
    com.microfocus.cics.connector.cci.MFECIInteractionSpec interactionSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();

    public javax.resource.cci.ConnectionFactory getConnectionFactory() {
          return cf ;
    }

    @PostConstruct
    public void create() {
        disposed = false;
            sessionId = null;
        interactionSpec.setFunctionName("CASA_ECI_Function");
            interactionSpec.setArgument(0, com.microfocus.cobol.lang.Pointer.class,
                     com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY);
            interactionSpec.setArgument(1, com.microfocus.cobol.lang.Pointer.class,
                    com.microfocus.cobol.RuntimeProperties.BY_VALUE);
        interactionSpec.setUserName("SYSAD");
            interactionSpec.setPassword("SYSAD");
        interactionSpec.setProgramName("EC03");
    }

     @TransactionAttribute(TransactionAttributeType.NEVER)
    public com.mypackage.channelEJB.Channel First(com.mypackage.channelEJB.Channel channel) throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();

        interactionSpec.setExtendMode(CCLExtendMode.CCL_EXTENDED);
            ix = con.createInteraction();

            CCLChannel cclChannel = new CCLChannel("GenChannel");
        CCLContainer cclContainer1 = new CCLContainer("GenCon1");
        CCLContainer cclContainer2 = new CCLContainer("GenCon2");
        byte[] cData1 = channel.getContainer1().getContainerData().getBytes();
        byte[] cData2 = channel.getContainer2().getContainerData().getBytes();
        ContainerData cd1 = new ContainerData(cData1);
            ContainerData cd2 = new ContainerData(cData2);
        cclContainer1.setContainerData(cd1);
            cclContainer2.setContainerData(cd2);
            cclChannel.addContainer(cclContainer1);
            cclChannel.addContainer(cclContainer2);
        interactionSpec.setChannel(cclChannel);
            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
            CCLChannel returnChannel = interactionSpec.getReturnChannel();
        com.mypackage.channelEJB.Channel retFromEJBChannel = new com.mypackage.channelEJB.Channel();
        if(returnChannel != null) {
            List<CCLContainer> containers = returnChannel.getContainers();
            int count = 0;
            for(CCLContainer container: containers) {
                        if(count == 0) {
                retFromEJBChannel.getContainer1().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            if(count == 1) {
                retFromEJBChannel.getContainer2().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
                }
        }
        return retFromEJBChannel;

        } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }
        finally {
            closeCobolConnection(con);
            ix = null; rf = null;
        }
    }

        @TransactionAttribute(TransactionAttributeType.NEVER)
    public  com.mypackage.channelEJB.Channel commit() throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();
        interactionSpec.setExtendMode(CCLExtendMode.CCL_COMMIT);
        rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
            CCLChannel returnChannel = interactionSpec.getReturnChannel();
        com.mypackage.channelEJB.Channel retFromEJBChannel = new com.mypackage.channelEJB.Channel();
        if(returnChannel != null) {
            List<CCLContainer> containers = returnChannel.getContainers();
            int count = 0;
            for(CCLContainer container: containers) {
                        if(count == 0) {
                retFromEJBChannel.getContainer1().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            if(count == 1) {
                retFromEJBChannel.getContainer2().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
                }
        }
        return retFromEJBChannel;
        } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }
        finally {
            closeCobolConnection(con);
            interactionSpec = null; ix = null; rf = null;
        }
    }

             @TransactionAttribute(TransactionAttributeType.NEVER)
    public  com.mypackage.channelEJB.Channel rollback() throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();
        interactionSpec.setExtendMode(CCLExtendMode.CCL_BACKOUT);
            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
             CCLChannel returnChannel = interactionSpec.getReturnChannel();
        com.mypackage.channelEJB.Channel retFromEJBChannel = new com.mypackage.channelEJB.Channel();
        if(returnChannel != null) {
            List<CCLContainer> containers = returnChannel.getContainers();
            int count = 0;
            for(CCLContainer container: containers) {
                        if(count == 0) {
                retFromEJBChannel.getContainer1().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            if(count == 1) {
                retFromEJBChannel.getContainer2().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
                }
        }
        return retFromEJBChannel;

        } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }
        finally {
            closeCobolConnection(con);
            interactionSpec = null; ix = null; rf = null;
        }
    }

    @Remove
    public void removeSF() {
            cleanup();
    }

    void cleanup() throws javax.ejb.EJBException {
       try {
            if(!disposed) {
                if(lastConnectionHandle != null) {
                  com.microfocus.cics.connector.cci.MFECIConnection.dispose(sessionId);
                  closeCobolConnection(lastConnectionHandle);
                }
                else {
                  com.microfocus.cics.connector.cci.MFECIConnection.dispose(sessionId);
                }
              disposed = true ;
            }
       } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error disposing a Cobol Connection: ", ex);
       }
       finally {
           lastConnectionHandle = null;
           cf = null;
       }
    }

    public int getCobolReturnCode() throws javax.ejb.EJBException {
         return cobolReturnCode;
    }

    @PrePassivate
    public void passivate() throws javax.ejb.EJBException {
    }

    @PostActivate
    public void activate() throws javax.ejb.EJBException {
    }

    private void initialize(boolean isInitial, javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            javax.resource.cci.Interaction ix = con.createInteraction();
            com.microfocus.cics.connector.cci.MFECIInteractionSpec interactionSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            interactionSpec.setFunctionName("initialize");
            javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord irec = rf.createIndexedRecord("beanArgs");
            irec.add(new Boolean(isInitial));
            javax.resource.cci.Record orec = ix.execute(interactionSpec, irec);
            ix.close();
            rf = null ; ix = null ; interactionSpec = null ; irec = null ;
        } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("initialize threw ResourceException: ", ex);
        }
    }

    private javax.resource.cci.Connection getCobolConnection() throws javax.ejb.EJBException {

    //SSL
        try {
           con.setTrustStoreName("C:/test/estrustStore.jks");
           con.setTrustStorePassword("srvrootpwd");
        } catch (Exception e) {
            throw new javax.ejb.EJBException(e);
        }

            com.microfocus.cics.connector.cci.MFECIConnection con = null;
        try {
            con = (com.microfocus.cics.connector.cci.MFECIConnection) cf.getConnection(new com.microfocus.cics.connector.cci.MFECIConnectionSpec(true, true, sessionId));
            lastConnectionHandle = con;

        } catch (javax.resource.ResourceException ex) {
             throw new javax.ejb.EJBException("Error getting a Cobol Connection: ", ex);
        }
        return con ;
    }

    private void closeCobolConnection(javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            if(con != null) {
             if(sessionId == null) {
                 sessionId = ((com.microfocus.cics.connector.cci.MFECIConnection)con).getSessionId();
             }
              con.close();
            }
        } catch (javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error closing a Cobol Connection: ", ex);
        }
    }
}
JBoss EAP 6.4 - File ChannelEJBBean.java:
package com.mypackage.channelEJB ;

import javax.ejb.Stateless;
import javax.ejb.Stateful;
import javax.ejb.EJB;
import javax.ejb.Init;
import javax.ejb.Remove;
import javax.ejb.PostActivate;
import javax.ejb.PrePassivate;
import javax.ejb.EJBException;
import javax.annotation.Resource;
import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.ejb.TransactionAttribute;
import javax.ejb.TransactionAttributeType;
import javax.ejb.Remote;
import com.microfocus.cics.connector.ccl.CCLExtendMode;
import com.microfocus.cics.connector.ccl.CCLChannel;
import com.microfocus.cics.connector.ccl.CCLContainer;
import com.microfocus.cics.connector.ccl.ContainerData;
import com.microfocus.cics.connector.ccl.AbendException;
import com.microfocus.cics.connector.ccl.AbendCodeType;

import java.util.List;

@Stateful(name="channelEJB", mappedName="ejb/channelEJB")
@Remote(com.mypackage.channelEJB.ChannelEJB.class)

public class ChannelEJBBean implements ChannelEJB, java.io.Serializable {

     @Resource (name="CCIMFCICS_v1.5", authenticationType=Resource.AuthenticationType.CONTAINER, shareable=false, mappedName="java:/eis/MFCICS_v1.5")
    private transient javax.resource.cci.ConnectionFactory cf;
    private boolean disposed = false;
    private String sessionId = null;
    private transient javax.resource.cci.Connection lastConnectionHandle = null;
    private boolean doInitialize = true;
    public static final int DEFAULT_COBOL_RETURN_CODE = 2147483647;
    private int cobolReturnCode = DEFAULT_COBOL_RETURN_CODE;
    com.microfocus.cics.connector.cci.MFECIInteractionSpec interactionSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();

    public javax.resource.cci.ConnectionFactory getConnectionFactory() {
          return cf ;
    }

    @PostConstruct
    public void create() {
        disposed = false;
            sessionId = null;
        interactionSpec.setFunctionName("CASA_ECI_Function");
            interactionSpec.setArgument(0, com.microfocus.cobol.lang.Pointer.class,
                     com.microfocus.cobol.RuntimeProperties.OUTPUT_ONLY);
            interactionSpec.setArgument(1, com.microfocus.cobol.lang.Pointer.class,
                    com.microfocus.cobol.RuntimeProperties.BY_VALUE);
        interactionSpec.setUserName("SYSAD");
            interactionSpec.setPassword("SYSAD");
        interactionSpec.setProgramName("EC03");
    }

     @TransactionAttribute(TransactionAttributeType.NEVER)
    public com.mypackage.channelEJB.Channel First(com.mypackage.channelEJB.Channel channel) throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();

        interactionSpec.setExtendMode(CCLExtendMode.CCL_EXTENDED);
            ix = con.createInteraction();

            CCLChannel cclChannel = new CCLChannel("GenChannel");
        CCLContainer cclContainer1 = new CCLContainer("GenCon1");
        CCLContainer cclContainer2 = new CCLContainer("GenCon2");
        byte[] cData1 = channel.getContainer1().getContainerData().getBytes();
        byte[] cData2 = channel.getContainer2().getContainerData().getBytes();
        ContainerData cd1 = new ContainerData(cData1);
            ContainerData cd2 = new ContainerData(cData2);
        cclContainer1.setContainerData(cd1);
            cclContainer2.setContainerData(cd2);
            cclChannel.addContainer(cclContainer1);
            cclChannel.addContainer(cclContainer2);
        interactionSpec.setChannel(cclChannel);
            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
            CCLChannel returnChannel = interactionSpec.getReturnChannel();
        com.mypackage.channelEJB.Channel retFromEJBChannel = new com.mypackage.channelEJB.Channel();
        if(returnChannel != null) {
            List<CCLContainer> containers = returnChannel.getContainers();
            int count = 0;
            for(CCLContainer container: containers) {
                        if(count == 0) {
                retFromEJBChannel.getContainer1().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            if(count == 1) {
                retFromEJBChannel.getContainer2().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
                }
        }
        return retFromEJBChannel;

        } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }
        finally {
            closeCobolConnection(con);
            ix = null; rf = null;
        }
    }

        @TransactionAttribute(TransactionAttributeType.NEVER)
    public  com.mypackage.channelEJB.Channel commit() throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();
        interactionSpec.setExtendMode(CCLExtendMode.CCL_COMMIT);
        rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
            CCLChannel returnChannel = interactionSpec.getReturnChannel();
        com.mypackage.channelEJB.Channel retFromEJBChannel = new com.mypackage.channelEJB.Channel();
        if(returnChannel != null) {
            List<CCLContainer> containers = returnChannel.getContainers();
            int count = 0;
            for(CCLContainer container: containers) {
                        if(count == 0) {
                retFromEJBChannel.getContainer1().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            if(count == 1) {
                retFromEJBChannel.getContainer2().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
                }
        }
        return retFromEJBChannel;
        } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }
        finally {
            closeCobolConnection(con);
            interactionSpec = null; ix = null; rf = null;
        }
    }

             @TransactionAttribute(TransactionAttributeType.NEVER)
    public  com.mypackage.channelEJB.Channel rollback() throws javax.ejb.EJBException {
        javax.resource.cci.Connection con = null;
        disposed = false;
        con = getCobolConnection();
        javax.resource.cci.RecordFactory rf = null;
        javax.resource.cci.Interaction ix = null;
        try {
            if(doInitialize) {
                initialize(false, con);
                doInitialize = false;
            }
            ix = con.createInteraction();
        interactionSpec.setExtendMode(CCLExtendMode.CCL_BACKOUT);
            rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord iRec = interactionSpec.getInputRecord();
            javax.resource.cci.IndexedRecord oRec = rf.createIndexedRecord("FirstOut");
            ix.execute(interactionSpec, iRec, oRec);
            ix.close();
            cobolReturnCode = interactionSpec.getReturnCode();
             CCLChannel returnChannel = interactionSpec.getReturnChannel();
        com.mypackage.channelEJB.Channel retFromEJBChannel = new com.mypackage.channelEJB.Channel();
        if(returnChannel != null) {
            List<CCLContainer> containers = returnChannel.getContainers();
            int count = 0;
            for(CCLContainer container: containers) {
                        if(count == 0) {
                retFromEJBChannel.getContainer1().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
            if(count == 1) {
                retFromEJBChannel.getContainer2().setContainerData(new String(container.getContainerData().getContainerData()));
                count++;
            }
                }
        }
        return retFromEJBChannel;

        } catch(javax.resource.ResourceException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
        Exception linkedEx = __ex.getLinkedException();
        if(linkedEx instanceof AbendException) {
        AbendException aex = (AbendException) linkedEx;
        System.out.println("AbendCode = " + aex.getAbendCode());
        System.out.println("Abend Code Type = " + aex.getAbendCodeType());
        }
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        } catch(java.io.UnsupportedEncodingException __ex) {
            cobolReturnCode = interactionSpec.getReturnCode();
            throw new javax.ejb.EJBException("First threw a resource Exception", __ex);
        }
        finally {
            closeCobolConnection(con);
            interactionSpec = null; ix = null; rf = null;
        }
    }

    @Remove
    public void removeSF() {
            cleanup();
    }

    void cleanup() throws javax.ejb.EJBException {
       try {
            if(!disposed) {
                if(lastConnectionHandle != null) {
                  com.microfocus.cics.connector.cci.MFECIConnection.dispose(sessionId);
                  closeCobolConnection(lastConnectionHandle);
                }
                else {
                  com.microfocus.cics.connector.cci.MFECIConnection.dispose(sessionId);
                }
              disposed = true ;
            }
       } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error disposing a Cobol Connection: ", ex);
       }
       finally {
           lastConnectionHandle = null;
           cf = null;
       }
    }

    public int getCobolReturnCode() throws javax.ejb.EJBException {
         return cobolReturnCode;
    }

    @PrePassivate
    public void passivate() throws javax.ejb.EJBException {
    }

    @PostActivate
    public void activate() throws javax.ejb.EJBException {
    }

    private void initialize(boolean isInitial, javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            javax.resource.cci.Interaction ix = con.createInteraction();
            com.microfocus.cics.connector.cci.MFECIInteractionSpec interactionSpec = new com.microfocus.cics.connector.cci.MFECIInteractionSpec();
            interactionSpec.setFunctionName("initialize");
            javax.resource.cci.RecordFactory rf = cf.getRecordFactory();
            javax.resource.cci.IndexedRecord irec = rf.createIndexedRecord("beanArgs");
            irec.add(new Boolean(isInitial));
            javax.resource.cci.Record orec = ix.execute(interactionSpec, irec);
            ix.close();
            rf = null ; ix = null ; interactionSpec = null ; irec = null ;
        } catch(javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("initialize threw ResourceException: ", ex);
        }
    }

    private javax.resource.cci.Connection getCobolConnection() throws javax.ejb.EJBException {

    //SSL
        try {
           con.setTrustStoreName("C:/test/estrustStore.jks");
           con.setTrustStorePassword("srvrootpwd");
        } catch (Exception e) {
            throw new javax.ejb.EJBException(e);
        }

            com.microfocus.cics.connector.cci.MFECIConnection con = null;
        try {
            con = (com.microfocus.cics.connector.cci.MFECIConnection) cf.getConnection(new com.microfocus.cics.connector.cci.MFECIConnectionSpec(true, true, sessionId));
            lastConnectionHandle = con;

        } catch (javax.resource.ResourceException ex) {
             throw new javax.ejb.EJBException("Error getting a Cobol Connection: ", ex);
        }
        return con ;
    }

    private void closeCobolConnection(javax.resource.cci.Connection con) throws javax.ejb.EJBException {
        try {
            if(con != null) {
             if(sessionId == null) {
                 sessionId = ((com.microfocus.cics.connector.cci.MFECIConnection)con).getSessionId();
             }
              con.close();
            }
        } catch (javax.resource.ResourceException ex) {
            throw new javax.ejb.EJBException("Error closing a Cobol Connection: ", ex);
        }
    }
}
Parent topic: Extended LUW (Logical Unit of Work) Samples
Related reference
CICS Program Call with Commarea using SSL


CICS IBM ECI Resource Adapter

  • WebSphere 8.5 CICS IBM ECI Resource Adapter Configuration
    Describes the steps required to install and configure the WebSphere 8.5 CICS IBM ECI resource adapter.
  • JBoss EAP 6.4 CICS IBM ECI Resource Adapter Configuration
    Describes the steps required to install and configure the JBoss EAP 6.4 CICS IBM ECI resource adapter.
  • ra.xml file
    Describes the contents of the ra.xml file, which includes a list of properties that configure your CICS IBM ECI resource adapter.
  • Using SSL with the CICS IBM ECI Resource Adapter
    Describes how to configure an enterprise server to use SSL with the Micro Focus CICS IBM ECI resource adapter.
  • Sample EJBs
    For sample java programs that use the IBM CICS ECI resource adapter, see the IBM CICS ECI Resource Adapter programming documentation.
Parent topic: Micro Focus Resource Adapters


WebSphere 8.5 CICS IBM ECI Resource Adapter Configuration

Describes the steps required to install and configure the WebSphere 8.5 CICS IBM ECI resource adapter.
Install the CICS resource adapter:
  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 mf-ibm-cics-notx-ws85.rar file. The new resource adapter is now listed on the right.

Create a new J2C Connection Factory
  1. From the WebSphere Administrative Console, click the new CICS resource adapter to display its properties.
  2. Under Additional Properties, click J2C Connection Factories; then click New.
  3. Follow the instructions on the screen to specify:
    • CCIMFCICS_IBM_v1.5 as the reference name for the connection factory
    • eis/MFCICS_IBM_v1.5 as the JNDI name for the connection factory
  4. Confirm that the CCIMFCICS resource adapter is now listed on the J2C connection factories page of the console.
Configure the CCIMFCICS_IBM Resource Adapter for SSL (if required)
  1. Click the J2C Connection Factory that corresponds to the new CCIMFCICS_IBM resource adapter; then click Custom Properties.
  2. On the list of resources, make the following changes:
    • To enable SSL, set the secureConnection value to true
    • To enable access to your enterprise server, provide appropriate values for ServerHost and ServerPort
    • To enable tracing, set the trace value to true (optional)
    This enables the SSL connection.
Parent topic: CICS IBM ECI Resource Adapter
Related reference
Using SSL with the CICS IBM ECI Resource Adapter
ra.xml file


JBoss EAP 6.4 CICS IBM ECI Resource Adapter Configuration

Describes the steps required to install and configure the JBoss EAP 6.4 CICS IBM ECI resource adapter.
  1. Copy the mf-ibm-cics-notx-jb_eap64.rar file, located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee-ccl\javaee6\jboss64EAP (Windows) or $COBDIR/javaee-ccl/javaee6/jboss64EAP (UNIX) directory, to the standalone\deployments (Windows) or standalone/deployments (UNIX) directory of your JBoss installation.
  2. Add the following code as a first-level child to the <profile> element in the JBoss standalone.xml file, usually located in the standalone\configuration (Windows) or standalone/configuration (UNIX) directory of your JBoss installation:
    <subsystem xmlns="urn:jboss:domain:resource-adapters:1.0">
   <resource-adapters>
      <resource-adapter>
         <archive>mf-ibm-cics-notx-jb_eap64.rar</archive>
         <transaction-support>NoTransaction</transaction-support>
         <connection-definitions>
            <connection-definition
                class-name="com.ibm.cics.connector2.cics.ECIManagedConnectionFactory"
                jndi-name="java:/eis/MFCICS_IBM_v1.5" pool-name="MFECIConnectionFactory">
              <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>
  3. In the standalone.xml file, edit the <archive-validation> element (child element of <subsystem xmlns="urn:jboss:domain:jca:1.1">) to read as follows:
    <archive-validation enabled="false" fail-on-error="true" fail-on-warn="false"/>
Parent topic: CICS IBM ECI Resource Adapter
Related reference
Using SSL with the CICS IBM ECI Resource Adapter
ra.xml file


ra.xml file

Describes the contents of the ra.xml file, which includes a list of properties that configure your CICS IBM ECI resource adapter.

The ra.xml file is in the META-INF subdirectory of the resource adapter, located by default in the appropriate application-server-specific directory under %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee-ccl (Windows) or $COBDIR/javaee-ccl (UNIX). Its contents include a list of properties in XML format. You can edit this file to configure your CICS resource adapter by modifying the property values.

<config-property>
  <config-property-name>ServerHost</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>localhost</config-property-value>
</config-property>

<config-property>
  <config-property-name>ServerPort</config-property-name>
  <config-property-type>java.lang.String</config-property-type>
  <config-property-value>9003</config-property-value>
</config-property>

<config-property>
  <config-property-name>Trace</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>

<config-property>
  <config-property-name>SecureGUID</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>

<config-property>
  <config-property-name>secureConnection</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>

<config-property>
  <config-property-name>ReadTimeoutInSeconds</config-property-name>
  <config-property-type>java.lang.Integer</config-property-type>
  <config-property-value>0</config-property-value>
</config-property>

<config-property>
  <config-property-name>OpenTimeoutInSeconds</config-property-name>
  <config-property-type>java.lang.Integer</config-property-type>
  <config-property-value>120</config-property-value>
</config-property>

<config-property>
  <config-property-name>EnterpriseServerSocketCloseDueToInactivity</config-property-name>
  <config-property-type>java.lang.Integer</config-property-type>
  <config-property-value>72</config-property-value>
</config-property>
<config-property>
  <config-property-name>JavaCommAreaEBCDIC</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>

<config-property>
  <config-property-name>CicsCommAreaEBCDIC</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>true</config-property-value>
</config-property>

<config-property>
  <config-property-name>JavaContainerEBCDIC</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>

<config-property>
  <config-property-name>CicsContainerEBCDIC</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>true</config-property-value>
</config-property>

<config-property>
  <config-property-name>CommAreaAndChannelLogging</config-property-name>
  <config-property-type>java.lang.Boolean</config-property-type>
  <config-property-value>false</config-property-value>
</config-property>

<config-property>
   <config-property-name>KeyRingClass</config-property-name>
   <config-property-type>java.lang.String</config-property-type>
   <config-property-value>.\estruststore.jks</config-property-value>
</config-property>

<config-property>
   <config-property-name>KeyRingPassword</config-property-name>
   <config-property-type>java.lang.String</config-property-type>
   <config-property-value>password</config-property-value>
</config-property>

The following describes each property:

ServerHost
Sets the server host name.
Valid values: Server host machine name or IP address
Default: localhost
ServerPort
Specifies the port used by Enterprise Server Web Services and J2EE listeners.
Valid value: The port number used by Enterprise 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
secureConnection
Turns SSL on or off.
Valid values: true or false
Default: false
ReadTimeoutInSeconds
Sets the wait period, in seconds, that a socket waits before timing out on a read.
Valid values: 0 - timeout wait period is infinite

Any positive integer - represents the number of seconds to wait before timing out

Default: 0
OpenTimeoutInSeconds
Sets the wait period, in seconds, that a socket waits before timing out on a connect.
Valid values: 0 - timeout wait period is infinite

Any positive integer - represents the number of seconds to wait before timing out

Default: 120
EnterpriseServerSocketCloseDueToInactivity
Sets the wait period, in hours, that Enterprise Server waits before closing a socket due to inactivity.
Valid values: 0 - timeout wait period is infinite

Any positive integer - represents the number of hours that Enterprise Server waits before closing a socket

Default: 72
JavaCommAreaEBCDIC
Indicates whether or not the Java CommArea is ASCII or EBCDIC.
Valid values: true - Java CommArea is EBCDIC

false - Java CommArea is ASCII

Default: false
CicsCommAreaEBCDIC
Indicates whether or not the CICS CommArea is ASCII or EBCDIC.
Valid values: true - CIC CommArea is EBCDIC

false - CICS CommArea is ASCII

Default: false
CommAreaAndChannelLogging
Turns logging for CommAreas and Channels on or off.
Valid values: true or false
Default: false
JavaContainerEBCDIC
Indicates whether or not the Java Container is ASCII or EBCDIC.
Valid values: true - Java Container is EBCDIC

false - Java Container is ASCII

Default: false
CICSContainerEBCDIC
Indicates whether or not the CICS Container is ASCII or EBCDIC.
Valid values: true - CICS Container is EBCDIC

false - CICS Container is ASCII

Default: false
KeyRingClass
The path to the truststore.
Valid value: The path to the truststore
Default: .\estruststore.jks
KeyRingPassword
The password for the truststore.
Valid value: The password for the truststore
Default: password
Parent topic: CICS IBM ECI Resource Adapter
Related reference
WebSphere 8.5 CICS IBM ECI Resource Adapter Configuration
JBoss EAP 6.4 CICS IBM ECI Resource Adapter Configuration


Using SSL with the CICS IBM ECI Resource Adapter

After installing and configuring the Micro Focus CICS IBM ECI resource adapter, including enabling SSL, you can perform further configuration to establish secure communication between the resource adapter and Enterprise Server. To do this, generate a Java keystore that includes Enterprise Server trusted certificates that can be used by CICS resource adapter programs; then import your trusted root certificate into the keystore.

Configure the RA and Enable SSL
See CICS IBM ECI Resource Adapter Configuration for complete instructions.
Generate a Keystore
  1. Generate a Java keystore using the keytool command provided with the JDK. For example:
    keytool -genkey -alias esServer -keyalg RSA -keystore estrustStore.jks
  2. Provide a password for the generated keystore. (Optional)
Import the Trusted Root Certificate
Here, you set the trusted root certificate to verify the certificate provided by Enterprise Server.
  1. Import the trusted root certificate into your generated Java keystore using the keytool command. For example:
    keytool -import -alias esrootcert
-file CARootcert.pem -keystore estrustStore.jks
  2. If prompted, provide a password for the keystore.

For more information on Enterprise Server and CA certificates, see the Secure Communications (SSL) topic under Deployment. We also provide a demo CA you can use to test your SSL connections. See Using the Demonstration Certificate Authority for details.

We also recommend that you review the topics listed under Related reference below.

Parent topic: CICS IBM ECI Resource Adapter
Related concepts
Secure Communications (SSL)
Using the Demonstration Certificate Authority
Related reference
Using SSL with ECI Programs
CICS Program Call with Commarea using SSL
WebSphere 8.5 CICS IBM ECI Resource Adapter Configuration
JBoss EAP 6.4 CICS IBM ECI Resource Adapter Configuration


Sample EJBs

For sample java programs that use the IBM CICS ECI resource adapter, see the IBM CICS ECI Resource Adapter programming documentation.

Parent topic: CICS IBM ECI Resource Adapter


ECI Implementation (mfccl.jar)

Note: For information concerning known issues with ECI implementation, see the Java Artifacts topic under Known Issues and Restrictions.
  • Micro Focus ECI
  • IBM ECI
  • Using SSL with ECI Programs
    Describes how to configure an enterprise server to use SSL with ECI via either the Micro Focus or the IBM API.
Parent topic: Java Artifacts
Related concepts
Application Server JCA Support for Enterprise Server


Micro Focus ECI

  • Java API Classes
    Provides instructions for viewing Java API classes documentation.
  • Sample Programs
Parent topic: ECI Implementation (mfccl.jar)


Java API Classes

Documentation for all Java API classes are provided in HTML format and contained in an archive file located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\javaee-ccl\docs (Windows) or $COBDIR/javaee-ccl/docs (UNIX) directory.

To view the documentation:

  1. From the javaee-ccl\docs (Windows) or javaee-ccl/docs (UNIX) directory, extract mfccl-docs.zip (Windows) or mfccl-docs.tgz (UNIX) to a directory of your choice.
  2. Change to the directory that now contains the extracted HTML files.
  3. Open index.html in your browser.

For additional information on the layout of the CICS (ECI) connector classes documentation, open the help-doc.html file located in the same directory as index.html.

Parent topic: Micro Focus ECI


Sample Programs

Sample program code that includes the code required to connect using the Micro Focus ECI.

  • Nonextended LUW (Logical Unit of Work) Samples
  • Extended LUW (Logical Unit of Work) Samples
Parent topic: Micro Focus ECI


Nonextended LUW (Logical Unit of Work) Samples

  • CICS Program Call with Commarea
    Shows the contents of a sample program that executes a CICS program call using a Commarea and non-extended LUW.
  • CICS Program Call with Channels and Containers
    Shows the contents of a sample program that executes a CICS program call with channels and containers using non-extended LUW.
Parent topic: Sample Programs


CICS Program Call with Commarea

Shows the contents of a sample program that executes a CICS program call using a Commarea and non-extended LUW.
File: SampleCommArea.java
import java.io.UnsupportedEncodingException;

import com.microfocus.cics.client.AbendException;
import com.microfocus.cics.client.CCLCallType;
import com.microfocus.cics.client.CommArea;
import com.microfocus.cics.client.CCLExtendMode;
import com.microfocus.cics.client.CCLParams;
import com.microfocus.cics.client.CCLVersion;
import com.microfocus.cics.client.CICSException;
import com.microfocus.cics.client.CommAreaSizeException;
import com.microfocus.cics.client.ConnectionType;
import com.microfocus.cics.client.ContainerData;
import com.microfocus.cics.client.ECIBINPConnection;
import com.microfocus.cics.client.ECIBINPRequest;
import com.microfocus.cics.client.ECIConnection;
import com.microfocus.cics.client.ECIRequest;
import com.microfocus.cics.client.ECIResponse;
import com.microfocus.cics.client.MalformedResponseException;
import com.microfocus.cics.client.ExciRespException;
import com.microfocus.cics.client.AbendCodeType;
import java.util.List;

public class SampleCommArea {

    public static void main(String[] args) throws UnsupportedEncodingException, CICSException, AbendException, MalformedResponseException, CommAreaSizeException {
        SampleCommArea sc = new SampleCommArea();
        sc.commareaTest1();
    }

    public void commareaTest1() throws CICSException, UnsupportedEncodingException, AbendException, MalformedResponseException, CommAreaSizeException {
                ECIConnection aConn = null;
        ECIRequest aReq = null;
        ECIResponse aResp = null;
        CommArea ca = null;
        CCLParams theParams = null;
        try {
            aConn = new ECIBINPConnection()
                    .setConnectionType(ConnectionType.NO_LUW)
                    .setHost("localhost").setPort(9003)
                    .setTrace(true);
            aConn.open();
            aReq = new ECIBINPRequest(aConn);

            // set parameters

            // ca = new CommArea(" COMMIT  _JAVA _01_LUW ");
            ca = new CommArea("Bonjour le monde");
            theParams = new CCLParams();
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setCommArea(ca);
            theParams.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);
            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp, CommArea.ISO_8859_1);
        } catch (CICSException e) {
            System.out.println(e.getMessage());
        } catch (AbendException ae) {
            String abCode = ae.getAbendCode();
            AbendCodeType abendCodeType = ae.getAbendCodeType();
            System.out.println("Abend Code = " + abCode);
            System.out.println("Abend Code Type= " + abendCodeType);
        } catch (MalformedResponseException bre) {
            bre.printStackTrace();
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        } catch (CommAreaSizeException ce) {
            ce.printStackTrace();
        } catch(ExciRespException e) {
                e.printStackTrace();
                System.out.println("ExciResp1 = " + e.getExciResp1() + " and ExciResp2 = " + e.getExciResp2() + " and rc = " + e.getRcMsg());
        } finally {
            ca = null;
            theParams = null;
            if (aReq != null)
                aReq.close();
            if (aResp != null)
                aResp.close();
            if (aConn != null) {
                try {
                    aConn.close();
                } catch (CICSException e) {
                    e.printStackTrace();
                }
            }
        }
    }

        private void handleResponse(ECIResponse aResp, String encoding)
            throws UnsupportedEncodingException {
        System.out.println("Response1 = " + aResp.getExciResp1());
        System.out.println("Response2 = " + aResp.getExciResp2());
        CommArea ca = aResp.getCommArea();
        if (ca != null) {
            byte[] caBytes = ca.getCommArea();
            if (caBytes != null) {
                String asciiCommArea = new String(ca.getCommArea(), encoding);
                System.out.println("CommArea = " + asciiCommArea);
            } else {
                System.out.println("CommArea = null");
            }
        }
        System.out.println("Abend code = " + aResp.getAbendCode());
        System.out.println("Abend code type = " + aResp.getAbendCodeType());
        System.out.println("Return Code = " + aResp.getReturnCode());
    }

}
Parent topic: Nonextended LUW (Logical Unit of Work) Samples


CICS Program Call with Channels and Containers

File SampleChannel.java
import java.io.UnsupportedEncodingException;

import com.microfocus.cics.client.AbendException;
import com.microfocus.cics.client.CCLCallType;
import com.microfocus.cics.client.CCLChannel;
import com.microfocus.cics.client.CCLContainer;
import com.microfocus.cics.client.CCLExtendMode;
import com.microfocus.cics.client.CCLParams;
import com.microfocus.cics.client.CCLVersion;
import com.microfocus.cics.client.CICSException;
import com.microfocus.cics.client.CommAreaSizeException;
import com.microfocus.cics.client.ConnectionType;
import com.microfocus.cics.client.ContainerData;
import com.microfocus.cics.client.ECIBINPConnection;
import com.microfocus.cics.client.ECIBINPRequest;
import com.microfocus.cics.client.ECIConnection;
import com.microfocus.cics.client.ECIRequest;
import com.microfocus.cics.client.ECIResponse;
import com.microfocus.cics.client.MalformedResponseException;
import com.microfocus.cics.client.ExciRespException;
import java.util.List;

public class SampleChannel {

    public static void main(String[] args) throws UnsupportedEncodingException, CICSException,
    AbendException, MalformedResponseException, CommAreaSizeException, ExciRespException {
        SampleChannel sc = new SampleChannel();
        sc.containerTest1();
    }

    public void containerTest1() throws CICSException, UnsupportedEncodingException, AbendException,
    MalformedResponseException, CommAreaSizeException, ExciRespException {
        ECIConnection aConn = null;
        ECIRequest aReq = null;
        ECIResponse aResp = null;
        CCLChannel ca = null;
        CCLParams theParams = null;
            try {
                aConn = new ECIBINPConnection()
                    .setConnectionType(ConnectionType.NO_LUW)
                    .setHost("localhost").setPort(9003)
                    .setTrace(true);
            aConn.open();
            aReq = new ECIBINPRequest(aConn);

            // set parameters
            ca = new CCLChannel("Bonjour le monde");
            CCLContainer aContainer = new CCLContainer("Container1");
            ContainerData data = new ContainerData();
            data.setContainerData("Hello1".getBytes());
            aContainer.setContainerData(data);
            ca.addContainer(aContainer);

              CCLContainer aContainer2 = new CCLContainer("Container2");
            ContainerData data2 = new ContainerData();
            data2.setContainerData("Hello2".getBytes());
            aContainer2.setContainerData(data2);
            ca.addContainer(aContainer2);

            theParams = new CCLParams();
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setChannel(ca);
            theParams.setUseChannel(true);
            theParams.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);

            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            List<CCLContainer> containers = aResp.getChannel().getContainers();
            for(CCLContainer c: containers) {
                ContainerData cd = c.getContainerData();
                if(cd != null) {
                    byte[] cData = cd.getContainerData();
                    System.out.println(new String(cData));
                }
            }

        } finally {
            ca = null;
            theParams = null;
            if (aReq != null)
                aReq.close();
            if (aResp != null)
                aResp.close();
            if (aConn != null) {
                try {
                    aConn.close();
                } catch (CICSException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}
Parent topic: Nonextended LUW (Logical Unit of Work) Samples


Extended LUW (Logical Unit of Work) Samples

  • Multiple CICS Program Calls with Commarea
    Shows the contents of a sample program that executes multiple CICS program calls and uses a Commarea and extended LUW.
  • Multiple CICS Program Calls with Channels and Containers
    Shows the contents of a sample program that executes multiple CICS program calls using Channel and extended LUW.
Parent topic: Sample Programs


Multiple CICS Program Calls with Commarea

Shows the contents of a sample program that executes multiple CICS program calls and uses a Commarea and extended LUW.
File SampleCommAreaWithELUW.java:
import java.io.UnsupportedEncodingException;

import com.microfocus.cics.client.AbendException;
import com.microfocus.cics.client.CCLCallType;
import com.microfocus.cics.client.CommArea;
import com.microfocus.cics.client.CCLExtendMode;
import com.microfocus.cics.client.CCLParams;
import com.microfocus.cics.client.CCLVersion;
import com.microfocus.cics.client.CICSException;
import com.microfocus.cics.client.CommAreaSizeException;
import com.microfocus.cics.client.ConnectionType;
import com.microfocus.cics.client.ContainerData;
import com.microfocus.cics.client.ECIBINPConnection;
import com.microfocus.cics.client.ECIBINPRequest;
import com.microfocus.cics.client.ECIConnection;
import com.microfocus.cics.client.ECIRequest;
import com.microfocus.cics.client.ECIResponse;
import com.microfocus.cics.client.MalformedResponseException;
import com.microfocus.cics.client.ExciRespException;
import com.microfocus.cics.client.AbendCodeType;
import java.util.List;

public class SampleCommAreaWithELUW {

    public static void main(String[] args) throws UnsupportedEncodingException, CICSException, AbendException, MalformedResponseException, CommAreaSizeException {
        SampleCommAreaWithELUW sc = new SampleCommAreaWithELUW();
        sc.commareaTest1();
    }

    public void commareaTest1() throws CICSException, UnsupportedEncodingException, AbendException, MalformedResponseException, CommAreaSizeException {
                ECIConnection aConn = null;
        ECIRequest aReq = null;
        ECIResponse aResp = null;
        CommArea ca = null;
        CCLParams theParams = null;
        try {
            aConn = new ECIBINPConnection()
                    .setConnectionType(ConnectionType.LUW)
                    .setHost("localhost").setPort(9003)
                    .setTrace(true);
            aConn.open();
            aReq = new ECIBINPRequest(aConn);

            // set parameters

            ca = new CommArea("Bonjour le monde");
            theParams = new CCLParams();
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setCommArea(ca);
            theParams.setExtendMode(CCLExtendMode.CCL_EXTENDED);
            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp, CommArea.ISO_8859_1);

            // call CICS again
            ca = new CommArea("Bonjour le monde 2");
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setCommArea(ca);
            theParams.setExtendMode(CCLExtendMode.CCL_EXTENDED);
            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp, CommArea.ISO_8859_1);

            // mark end of LUW
            ca = new CommArea("Au Revior");
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setCommArea(ca);
            theParams.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);
            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp, CommArea.ISO_8859_1);

            // commit
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setExtendMode(CCLExtendMode.CCL_COMMIT);
            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp, CommArea.ISO_8859_1);

        } catch (CICSException e) {
            System.out.println(e.getMessage());
        } catch (AbendException ae) {
            String abCode = ae.getAbendCode();
            AbendCodeType abendCodeType = ae.getAbendCodeType();
            System.out.println("Abend Code = " + abCode);
            System.out.println("Abend Code Type= " + abendCodeType);
        } catch (MalformedResponseException bre) {
            bre.printStackTrace();
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        } catch (CommAreaSizeException ce) {
            ce.printStackTrace();
        } catch(ExciRespException e) {
                e.printStackTrace();
                System.out.println("ExciResp1 = " + e.getExciResp1() + " and ExciResp2 = " + e.getExciResp2() + " and rc = " + e.getRcMsg());
        } finally {
            ca = null;
            theParams = null;
            if (aReq != null)
                aReq.close();
            if (aResp != null)
                aResp.close();
            if (aConn != null) {
                try {
                    aConn.close();
                } catch (CICSException e) {
                    e.printStackTrace();
                }
            }
        }
    }

        private void handleResponse(ECIResponse aResp, String encoding)
            throws UnsupportedEncodingException {
        System.out.println("Response1 = " + aResp.getExciResp1());
        System.out.println("Response2 = " + aResp.getExciResp2());
        CommArea ca = aResp.getCommArea();
        if (ca != null) {
            byte[] caBytes = ca.getCommArea();
            if (caBytes != null) {
                String asciiCommArea = new String(ca.getCommArea(), encoding);
                System.out.println("CommArea = " + asciiCommArea);
            } else {
                System.out.println("CommArea = null");
            }
        }
        System.out.println("Abend code = " + aResp.getAbendCode());
        System.out.println("Abend code type = " + aResp.getAbendCodeType());
        System.out.println("Return Code = " + aResp.getReturnCode());
    }

}
Parent topic: Extended LUW (Logical Unit of Work) Samples


Multiple CICS Program Calls with Channels and Containers

Shows the contents of a sample program that executes multiple CICS program calls using Channel and extended LUW.
File SampleChannelWithELUW.java:
import java.io.UnsupportedEncodingException;

import com.microfocus.cics.client.AbendException;
import com.microfocus.cics.client.CCLCallType;
import com.microfocus.cics.client.CCLChannel;
import com.microfocus.cics.client.CCLContainer;
import com.microfocus.cics.client.CCLExtendMode;
import com.microfocus.cics.client.CCLParams;
import com.microfocus.cics.client.CCLVersion;
import com.microfocus.cics.client.CICSException;
import com.microfocus.cics.client.ConnectionType;
import com.microfocus.cics.client.ContainerData;
import com.microfocus.cics.client.ECIBINPConnection;
import com.microfocus.cics.client.ECIBINPRequest;
import com.microfocus.cics.client.ECIConnection;
import com.microfocus.cics.client.ECIRequest;
import com.microfocus.cics.client.ECIResponse;
import com.microfocus.cics.client.MalformedResponseException;
import com.microfocus.cics.client.CommAreaSizeException;
import com.microfocus.cics.client.ExciRespException;
import java.util.List;

public class SampleChannelWithELUW {

    public static void main(String[] args) throws UnsupportedEncodingException, CICSException,
    AbendException, MalformedResponseException, CommAreaSizeException, ExciRespException {
        SampleChannelWithELUW sc = new SampleChannelWithELUW();
        sc.containerTest1();
    }

    public void containerTest1() throws CICSException, UnsupportedEncodingException, AbendException,
    MalformedResponseException, CommAreaSizeException, ExciRespException {
        ECIConnection aConn = null;
        ECIRequest aReq = null;
        ECIResponse aResp = null;
        CCLChannel ca = null;
        CCLParams theParams = null;
        try {
            aConn = new ECIBINPConnection()
                    .setConnectionType(ConnectionType.LUW)
                    .setHost("localhost").setPort(9003)
                    .setTrace(true);
            aConn.open();
            aReq = new ECIBINPRequest(aConn);

            // set parameters
            ca = new CCLChannel("Bonjour le monde");
            CCLContainer aContainer = new CCLContainer("Container1");
            ContainerData data = new ContainerData();
            data.setContainerData("Hello1".getBytes());
            aContainer.setContainerData(data);
            ca.addContainer(aContainer);

            CCLContainer aContainer2 = new CCLContainer("Container2");
            ContainerData data2 = new ContainerData();
            data2.setContainerData("Hello2".getBytes());
            aContainer2.setContainerData(data2);
            ca.addContainer(aContainer2);

            theParams = new CCLParams();
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setChannel(ca);
            theParams.setUseChannel(true);
            theParams.setExtendMode(CCLExtendMode.CCL_EXTENDED);

            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp);

            // Set data for second call
            CCLChannel ca2 = new CCLChannel("Bonjour le monde2");
            CCLContainer aContainer3 = new CCLContainer("Container3");
            ContainerData data3 = new ContainerData();
            data3.setContainerData("Hello3".getBytes());
            aContainer3.setContainerData(data3);
            ca2.addContainer(aContainer3);

            CCLContainer aContainer4 = new CCLContainer("Container4");
            ContainerData data4 = new ContainerData();
            data4.setContainerData("Hello4".getBytes());
            aContainer4.setContainerData(data4);
            ca2.addContainer(aContainer4);

            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setChannel(ca);
            theParams.setUseChannel(true);
            theParams.setExtendMode(CCLExtendMode.CCL_EXTENDED);

            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp);

            // mark end of ELUW
            CCLChannel ca3 = new CCLChannel("Au Revoir");
            CCLContainer aContainer5 = new CCLContainer("Container5");
            ContainerData data5 = new ContainerData();
            data5.setContainerData("Bye1".getBytes());
            aContainer5.setContainerData(data5);
            ca3.addContainer(aContainer5);

            CCLContainer aContainer6 = new CCLContainer("Container6");
            ContainerData data6 = new ContainerData();
            data6.setContainerData("Bye2".getBytes());
            aContainer6.setContainerData(data6);
            ca3.addContainer(aContainer6);

            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setChannel(ca);
            theParams.setUseChannel(true);
            theParams.setExtendMode(CCLExtendMode.CCL_NO_EXTEND);

            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp);

            // commit
            theParams.setVersion(CCLVersion.CCL_VERSION_2);
            theParams.setCallType(CCLCallType.CCL_SYNC);
            theParams.setProgramName("OKTEST");
            theParams.setUserId("SYSAD");
            theParams.setPassword("SYSAD");
            theParams.setExtendMode(CCLExtendMode.CCL_COMMIT);
            aReq.setRequestParameter(theParams);
            aResp = aReq.send();
            handleResponse(aResp);
        } finally {
            ca = null;
            theParams = null;
            if (aReq != null)
                aReq.close();
            if (aResp != null)
                aResp.close();
            if (aConn != null) {
                try {
                    aConn.close();
                } catch (CICSException e) {
                    e.printStackTrace();
                }
            }
        }
    }

    private void handleResponse(ECIResponse aResp) throws UnsupportedEncodingException {
        List<CCLContainer> containers = aResp.getChannel().getContainers();
            for(CCLContainer c: containers) {
                ContainerData cd = c.getContainerData();
                if(cd != null) {
                    byte[] cData = cd.getContainerData();
                    System.out.println(new String(cData));
                }
            }
    }
}
Parent topic: Extended LUW (Logical Unit of Work) Samples


IBM ECI

  • Java API
  • Sample Programs
    For sample java programs that use the IBM ECI API, see the IBM CICS Transaction Gateway programming documentation.
Parent topic: ECI Implementation (mfccl.jar)


Java API

  • Package com.ibm.ctg.client
Parent topic: IBM ECI


Package com.ibm.ctg.client

  • listSystem.properties file
    Describes the contents of the listSystem.properties file, which includes a list of servers and a list of properties.
Parent topic: Java API


listSystem.properties file

Describes the contents of the listSystem.properties file, which includes a list of servers and a list of properties.

The listSystem.properties file is part of the com.ibmctg.client package in the mfccl.jar file. Its contents consist of a list of servers specified using the following form:

serverName=url

The list of properties is:

Default=http://127.0.0.1:9003
# Default target Enterprise Server local region

ECINOCTG=http://127.0.0.1:9004
# Another target Enterprise Server local region

ECINOCTG_Remote=http://192.168.1.10:9003
# Yet another target Enterprise Server remote region

debug=false
#flag to indicate debug information to be emitted.
#Possible values are true or false

javaCommAreaEBCDIC=false
#flag to indicate what the comm area encoding on the java side is.
#Possible values are true i.e. EBCDIC or false i.e. ASCII

cicsCommAreaEBCDIC=true
#flag to indicate what the comm area encoding on the COBOL CICS side is.
# Possible values are true i.e. EBCDIC or false i.e. ASCII

javaContainerEBCDIC=false
#flag to indicate what the Channel/Container encoding on the java side is.
# Possible values are true i.e. EBCDIC or false i.e. ASCII

cicsContainerEBCDIC=true
#flag to indicate what the Channel/Container encoding on the COBOL CICS side is.
# Possible values are true i.e. EBCDIC or false i.e. ASCII

commAreaAndChannelLogging=false
#channel and comm area HEXA logging.
#Possible values are true or false

socketReadTimeout=60
#Socket will timeout after 60 seconds

socketOpenTimeout=60
#socket will timeout if it cannot connect in 60 seconds

You can edit this file to include alternative server specifications and/or properties.

You can also use an external listSystem.properties file that takes priority over the file in mfccl.jar by specifying its location when you start java:

-DmfListSystemLocation=anyDirectory\listSystem.properties
Parent topic: Package com.ibm.ctg.client


Sample Programs

For sample java programs that use the IBM ECI API, see the IBM CICS Transaction Gateway programming documentation.
Parent topic: IBM ECI


Using SSL with ECI Programs

Describes how to configure an enterprise server to use SSL with ECI via either the Micro Focus or the IBM API.

To establish secure communication between the ECI API (Micro Focus or IBM) and Enterprise Server, you need a Java keystore that includes Enterprise Server trusted certificates that can be used by Java ECI programs. You then import your trusted root certificate into the keystore. Once the keystore is ready, execute the java command to complete the configuration.

Generate a Keystore
  1. Generate a Java keystore using the keytool command provided with the JDK. For example:
    keytool -genkey -alias esServer -keyalg RSA -keystore estrustStore.jks
  2. Provide a password for the generated keystore. (Optional)
Import the Trusted Root Certificate
Here, you set the trusted root certificate to verify the certificate provided by Enterprise Server.
  1. Import the trusted root certificate into your generated Java keystore using the keytool command. For example:
    keytool -import -alias esrootcert
-file CARootcert.pem -keystore estrustStore.jks
  2. If prompted, provide a password for the keystore.
Execute the java Command
Execute the java command for your ECI programs using the following command-line arguments:
-Djavax.net.ssl.trustStoreType=jks
-Djavax.net.ssl.trustStore=c:/MySubversionProjects/ccl/ssl/esRootCert.jks
-Dcom.sun.net.ssl.checkRevocation=true
Important: If you are using the ECI library with the IBM JRE, include the following additional command-line argument:
-Dmf.ssl.algorithm=Ibmx509

For more information on Enterprise Server and CA certificates, see the Secure Communications (SSL) topic under Deployment. We also provide a demo CA you can use to test your SSL connections. See Using the Demonstration Certificate Authority for details.

Parent topic: ECI Implementation (mfccl.jar)
Related reference
Using SSL with the CICS Resource Adapter
Using SSL with the CICS IBM ECI Resource Adapter


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
  • Mouse Routines
  • Multi-threading Routines
  • National Locale Support (NLS) Library Routines
  • Operating System Information Routines
  • Portability Routines
  • Printer 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 UNIXWindows, 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_FREE_RECORD_LOCK
    Releases a record lock on a file.
  • 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_FREE_RECORD_LOCK

Releases a record lock on a file.

Note: This routine is not supported in JVM COBOL.

Syntax:

call "CBL_FREE_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 unlocked.
record-length
The number of bytes to unlock, starting from record-offset.
reserved
Reserved - must be zero.

On Exit:

return-code
One of the following codes:
0 | Lock successfully released
9/nnn | File status code indicating an error condition
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 (ANSI characters (Windows) or current locale (UNIX))
4 | EBCDIC character (CHARSET"EBCDIC" encoding)
5 | ASCII/MBCS characters (OEM characters (Windows) or current locale (UNIX))
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 (ANSI characters (Windows) or current locale (UNIX))
4 | EBCDIC character (CHARSET"EBCDIC" encoding)
5 | ASCII/MBCS characters (OEM characters (Windows) or current locale (UNIX))
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
Parent topic: Alphabetical List of Library 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
Parent topic: Alphabetical List of Library 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
Parent topic: Alphabetical List of Library 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_DEBUGBREAK
    Enables a COBOL program to invoke the debugger (Windows) or Animator (UNIX).
  • 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_DEBUGBREAK

Enables a COBOL program to invoke the debugger (Windows) or Animator (UNIX).
Restriction: This routine is not supported in JVM COBOL.

Syntax:

call "CBL_DEBUGBREAK"

Parameters:

None.

Comments:

You can use this call to invoke the debugger (Windows) or Animator (UNIX). If the program is not being debugged when it calls CBL_DEBUGBREAK, it starts the debugger (Windows) or Animator (UNIX) and then comes to a halt, as if you had been debugging it already and then pressed the Stop button on the toolbar (Windows) or interrupt key (UNIX).

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 Stop button (Windows) or interrupt key (UNIX).

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 debugging comes to a halt in Animator, as if you had pressed the interrupt key.

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
Related information
Creating a Debug Configuration


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 CBL_JOIN_FILENAME and CBL_SPLIT_FILENAME routines enable you to parse a filename into its component strings and to join strings together to form a filename. They can be used together to replace components of a filename, such as the extension. They can handle both null-terminated and space-terminated filenames.

A filename is split up into path, basename and extension. For example, in the filename d:\dir1\dir2\file.dat the path is "d:\dir1\dir2", the basename is "file", and the extension is "dat".

These two routines can work with filenames up to 65,535 characters long, but your environment or run-time system imposes a limit of 256 characters on the maximum length of basename.ext , and 261 characters on the maximum length of the entire filename.

  • 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-hundredths   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
   03 attribute        cblt-x4-comp5. *> pic x(4) comp-5
   03 date-stamp
      05 year          cblt-x4-comp5. *> pic x(4) comp-5
      05 month         cblt-x2-comp5. *> pic x(2) comp-5
      05 day           cblt-x2-comp5. *> pic x(2) comp-5
      05 hour          cblt-x2-comp5. *> pic x(2) comp-5
      05 minute        cblt-x2-comp5. *> pic x(2) comp-5
      05 second        cblt-x2-comp5. *> pic x(2) comp-5
      05 millisec      cblt-x2-comp5. *> pic x(2) comp-5
      05 dst           cblt-x1-comp5. *> pic x comp-5
      05 size          cblt-x8-comp5. *> pic x(8) comp-5
      05 name
         07 max-len    cblt-x2-comp5. *> pic x(2) comp-5
         07 entry-name 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.
max-len
The length of the entry-name field.

On Exit:

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.
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.
size
The size of the file in bytes.
entry-name
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 max-len 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 "/" (UNIX) or "\"Windows . 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 slash (/) or colon (:) and basename-buffer is not empty, the routine inserts a backslash (\) 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.

If path consists of a valid drive letter, but no colon (:), the routine adds one. It does not do this for a device (for example LPT1) that does not need one. You cannot join a device (as opposed to a drive letter) to a non-empty basename. This applies to Windows environments (local development) only.

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.
user-mode
Specifies what to do with user-file-spec:
0 Check whether the file exists in a library or as a separate disk file.

.NET does not support embedded library names. If user-file-spec includes an embedded library-name, that library is opened (if it exists) and searched for the file. The library is left open afterward.

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.

1 | 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.
2 | 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 user-mode = 1 or 2. See path-flag below.
128 | As 0, except user-file-spec is a null-terminating string. On exit, actual-file-spec is also produced as a null-terminating string.
129 | As 1, except user-file-spec is a null-terminating string. On exit, actual-file-spec is also produced as a null-terminating string.
130 | As 2, except user-file-spec is a null-terminating string. On exit, actual-file-spec is also produced as a null-terminating string.
path-flag
If user-mode = 2, this data item should contain the value that was returned in this item from the previous user-mode = 1 or 2 call.
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 (applies to UNIX environments only).

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
Parent topic: Alphabetical List of Library 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
Parent topic: Alphabetical List of Library 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
Parent topic: Alphabetical List of Library 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. This applies to UNIX environments (remote development) only.

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. This applies to UNIX environments (remote development) only.

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 (unless the -l run-time switch is set).

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. Windows: The default is 65536, and the minimum is 8192 bytes.UNIX: 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 (unless the -l run-time switch is set).

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
                       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)
status-code | See Library Routines - Key |

On Entry:

mem-size
The number of bytes of memory to allocate.

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 default is 65536, and the minimum is 8192 bytes (applies to Windows environments only). The size for shared memory allocated using this routine is limited to a maximum of around 64000 bytes (applies to UNIX environments only).

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.

Parent topic: Memory Allocation Routines
Parent topic: Alphabetical List of Library Routines


Mouse Routines

Note: The CBL_mouse routines do not work with the x"AF" mouse routines.

Using the Routines

The mouse is useful for applications that require users to select from a list of options or move objects around on the screen.

To use these routines, you must ensure that your system knows that you have a mouse attached.

You must hide the mouse during the execution of any ANSI ACCEPT or DISPLAY statement that operates on the area of the screen where the mouse pointer is located.

The attributes referred to in the descriptions of routines are screen attributes, not user attributes. The top left-hand corner of the screen is row 0, column 0.

Mouse Events

Whenever the mouse is moved or a button on the mouse is pressed or released, the mouse hardware causes an interrupt. The mouse device driver takes control and, depending on a mask you have set, either saves it in a queue or ignores it. This prevents events being lost if a subsequent interrupt occurs before the application has read the event. With the mouse routines, you can read the event queue and determine how many events are in the queue.

When an event is generated, a description of it is stored in a data structure called the event-data. If the mask allows (see below), this is added to the queue. The layout of event-data is:

   event-type           pic x(2) comp-x.
         event-time           pic x(4) comp-x.
         event-row            pic x(2) comp-x.
         event-col            pic x(2) comp-x.

where the parameters are:

event-type
The action (that is, change of state) that took place:
bit 7-4 | reserved
bit 3 | set = button 3 pressed
bit 2 | set = button 2 pressed
bit 1 | set = button 1 pressed
bit 0 | set = mouse moved
A button release is indicated by the bit for that button changing from 1 to 0. For example, if the mouse moves and button 1 is pressed at the same time, event-type contains 3.
event-time
The time elapsed between when the event took place and some arbitrary but fixed starting time.
event-row
Gives the row in which the mouse was positioned when the event took place.
event-col
Gives the column in which the mouse was positioned when the event took place.

The Event Mask

The event mask, which you supply, tells the system which kinds of event should be queued and which ignored. It has the same structure as event-type. An event is queued only if it happens while the corresponding mask bit is on, or while another state is on whose mask bit is on. When an event-data is queued, the bit for each state is set correctly; that is, the mask does not mask them out.

For example, the operator moving the mouse generates an event if either the mask bit for "mouse moved" is off or the operator is holding down a button and the mask bit for that button is off.

  • CBL_GET_MOUSE_MASK
    Returns the mouse event mask.
  • CBL_GET_MOUSE_POSITION
    Returns the screen position of the mouse pointer.
  • CBL_GET_MOUSE_STATUS
    Finds out the number of events in the queue.
  • CBL_HIDE_MOUSE
    Makes the mouse pointer invisible.
  • CBL_INIT_MOUSE
    Initializes mouse support. This routine must be called before other mouse routines can be called.
  • CBL_READ_MOUSE_EVENT
    Reads the mouse event queue and returns information about an event.
  • CBL_SET_MOUSE_MASK
    Sets the mouse event mask.
  • CBL_SHOW_MOUSE
    Makes the mouse pointer visible.
  • CBL_TERM_MOUSE
    Terminates mouse support, releasing internal resources.
Parent topic: Library Routines
Related information
Alphabetical List of Library Routines


CBL_GET_MOUSE_MASK

Returns the mouse event mask.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_GET_MOUSE_MASK" using     mouse-handle
                                    event-mask
                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
event-mask | cblt-x2-compx | pic x(2) comp-x.
status-code | See Library Routines - Key |

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

event-mask See Mouse Routines

Comments:

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_MOUSE_POSITION

Returns the screen position of the mouse pointer.

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_GET_MOUSE_POSITION" using     mouse-handle
                                        mouse-position
                              returning status-code

Parameters

mouse-handle
Call prototype (see Key): cblt-x4-compx
Picture: pic x(4) comp-x.
mouse-position
Group predefined as cblt-mouse-pos containing
01 cblt-mouse-pos      typedef.
  03 cblte-mpos-row    cblt-x2-compx. 	*> pic x(2) comp-5.
  03 cblte-mpos-col    cblt-x2-compx. 	*> pic x(2) comp-5.
status-code
See Library Routines - Key.

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

mouse-position The screen position of the mouse pointer.

Comments:

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_GET_MOUSE_STATUS

Finds out the number of events in the queue.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_GET_MOUSE_STATUS"  using     mouse-handle
                                      mouse-queue-size
                            returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
mouse-queue-size | cblt-x2-compx | pic x(2) comp-x.
status-code | See Library Routines - Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

mouse-queue-size The number of events in the queue.

Comments:

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_HIDE_MOUSE

Makes the mouse pointer invisible.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_HIDE_MOUSE" using      mouse-handle
                      returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
status-code | See Library Routines - Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

None.

Comments:

After this routine has been called, mouse events still take place, but the mouse pointer is not displayed.

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_INIT_MOUSE

Initializes mouse support. This routine must be called before other mouse routines can be called.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_INIT_MOUSE" using     mouse-handle
                                mouse-buttons
                      returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
mouse-buttons | cblt-x2-compx | pic x(2) comp-x.
status-code | See Library Routines - Key

On Entry:

None.

On Exit:

mouse-handle | Mouse identifier. You pass this to any mouse routines you call subsequently.
mouse-buttons | The number of buttons on the mouse.

Comments:

If status-code (or RETURN-CODE) contains a nonzero status on return from this routine, mouse handling is not available and calls to any of the mouse routines should not be made.

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_READ_MOUSE_EVENT

Reads the mouse event queue and returns information about an event.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_READ_MOUSE_EVENT" using     mouse-handle
                                      event-data
                                      read-type
                            returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
event-data | See Mouse Routines
read-type | cblt-x1-compx | pic x comp-x.
status-code | See Library Routines - Key

On Entry:

mouse-handle
Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.
read-type
Indicates what to do if there are no events in the queue:
0 | Return immediately
1 | Wait for an event and then return

On Exit:

event-data
See Mouse Routines

Comments:

If there are no events in the event queue, the return from this routine depends on the value of read-type. If read-type is zero, the routine returns immediately with all zero values in event-data. If read-type has a value of one, return is delayed until an event has been queued.

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_SET_MOUSE_MASK

Sets the mouse event mask.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SET_MOUSE_MASK" using      mouse-handle
                                    event-mask
                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
event-mask | cblt-x2-compx | pic x(2) comp-x.
status-code | See Library Routines - Key

On Entry:

mouse-handle | Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.
event-mask | See Mouse Routines

On Exit:

None

Comments:

CBL_GET_MOUSE_MASK should be called first to find out which events are enabled.

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_SHOW_MOUSE

Makes the mouse pointer visible.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_SHOW_MOUSE" using      mouse-handle
                      returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
status-code | See Library Routines - Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

None

Comments:

When the mouse support has been initialized by the CBL_INIT_MOUSE call, the pointer is not displayed until this routine is called. After this call the system displays the mouse pointer until a routine to hide the mouse or terminate mouse support is called. This routine cancels any collision area defined earlier by PC_SET_MOUSE_HIDE_AREA.

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse Routines
Parent topic: Alphabetical List of Library Routines


CBL_TERM_MOUSE

Terminates mouse support, releasing internal resources.

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_TERM_MOUSE" using     mouse-handle
                      returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
mouse-handle | cblt-x4-compx | pic x(4) comp-x.
status-code | See Library Routines - Key

On Entry:

mouse-handle Mouse identifier, obtained by earlier call to CBL_INIT_MOUSE.

On Exit:

None

Comments:

The routine releases internal resources allocated by CBL_INIT_MOUSE. After this routine, mouse-handle is no longer valid and calling any mouse routine other than CBL_INIT_MOUSE results in an error.

The CBL_ mouse routines do not work with the x"AF" mouse routines.

Parent topic: Mouse 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. Note: For 64-bit Windows applications, this value is limited to 32-bit values, and so cannot be used to return memory addresses.
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 c-0              cblt-x1-compx.
 01 foo-item         pic 9(9) value 0.
 01 thredid          pic xxxx comp-5.
 01 thread-handle    cblt-pointer.
 01 thread-entry     cblt-ppointer.

 01 exitparms        cblt-exit-params.

 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'
*>
*> Set up for clean exit
*>
     move low-values  to exitparms
     set cblte-ep-install-addr   to entry 'exitproc'
     move 0    to c-0
     call 'CBL_EXIT_PROC'    using c-0 exitparms

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

 entry "exitproc".
     call "CBL_TSTORE_GET" using by value     tstore-handle
                                 by reference tl-ptr
     set address of tstore-item to tl-ptr
     if tl-ptr = NULL
     or not TSTORE-INIT
     or tstore-count not = THREAD-COUNT
         display "FAIL: TSTORE not initialized properly!"
     else
         display "PASS: Main thread has count " tstore-count
     end-if
     call "CBL_TSTORE_CLOSE" using by value tstore-handle
     exit program.

 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 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-thredid
     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 file (Windows) or catalog (UNIX) returning an identifying handle that you can use with the CBL_NLS_READ_MSG and CBL_NLS_CLOSE_MSG_FILE routines.

Windows: You can create different message files for each language you want your program to work with, using the same call to access each message in the appropriate national language. You can use a default message file, or create your own.

UNIX: 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 (Windows):

In each message file, messages are divided into sets; this enables you to define your own message set in the default message file if you want. This routine also enables you to insert portions of text in a message fetched from the message file in the order appropriate to the rules of the grammar for the national language

Comments (UNIX):

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

UNIX: Reserved; set to zero.

Windows: Country code. See your operating system documentation for an explanation of country codes.

cblte-osi-code-page

UNIX: Reserved; set to zero.

Windows: Code page. See your operating system documentation for an explanation of code page codes.

cblte-osi-process-type

UNIX: Reserved; undefined.

Windows: Process type:
0 | Process is running in a full screen session
3 | Process is running as a true graphical application
cblte-osi-rts-capabilities
Characteristics of run-time system. Set as follows:
Bit | Description
0

multi-threading multi-threaded rts

1 | Mainframe offloading capabilities, namely mainframe pointer emulation
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-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 | Enterprise Developer
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


Printer Routines

Restriction: These routines are not currently supported on UNIX platforms.

The printer handling routines enable greater control over printing than the standard COBOL syntax.

  • PC_PRINT_FILE
    Prints the contents of the specified file, optionally displaying printer control, font, and progress indicator dialog boxes, before commencing the print.
  • PC_PRINTER_CLOSE
    Closes a previously opened printer channel.
  • PC_PRINTER_CONTROL
    Sends a print command to a printer.
  • PC_PRINTER_DEFAULT_FONT
    Sets the default font for all PC_PRINTER_ routines.
  • PC_PRINTER_DEFAULT_NAME
    Sets the default printer for all PC_PRINTER_ routines.
  • PC_PRINTER_DEFAULT_PROPERTIES
    Sets one or more of the properties of the default printer for all PC_PRINTER_ routines.
  • PC_PRINTER_DRAW_RECTANGLE
    Draws an outline or filled rectangle at position start-x, start-y to end-x, end-y.
  • PC_PRINTER_ENUM_CLOSE
    Ends the process of enumerating printers.
  • PC_PRINTER_ENUM_NEXT
    Gets the name of the next enumerated printer.
  • PC_PRINTER_ENUM_START
    Starts the process of enumerating printers.
  • PC_PRINTER_FREE_BMP
    Frees a bitmap from memory, releasing its image and palette back to the operating system.
  • PC_PRINTER_GET_BMP_INFO
    Retrieves the width and height of a loaded bitmap.
  • PC_PRINTER_GET_COLOR
    Gets the color on the printer.
  • PC_PRINTER_GET_FONT
    Gets the font on the printer.
  • PC_PRINTER_INFO
    Returns a native device context handle, and other information that can be used to enhance the printing of a document by calling native graphics functions directly.
  • PC_PRINTER_INFO_DOTNET
    Enables the access to the native Hdc for a printer. Invokes a delegate with the current .NET Graphics object for the printer handle along with a Rectangle object and the PageSettings object.
  • PC_PRINTER_LINE_FROM_TO
    Draws a line from start-x,start-y to end-x,end-y.
  • PC_PRINTER_LOAD_BMP
    Loads a bitmap or other supported file format into memory ready for the PC_PRINTER_WRITE_BMP function.
  • PC_PRINTER_OPEN
    Opens a printer channel, giving it a document title, and optionally displaying printer control, font, and progress indicator dialog boxes
  • PC_PRINTER_REDIRECTION_PROC
    Registers a user function that is called when a program uses OPEN OUTPUT syntax and the ASSIGN TO PRINTER clause.
  • PC_PRINTER_SET_BACKGROUND_MIX_MODE
    Sets background printing mode.
  • PC_PRINTER_SET_COLOR
    Sets the color on the printer.
  • PC_PRINTER_SET_DEFAULT
    Sets a process-wide default printer before a printer is opened.
  • PC_PRINTER_SET_FONT
    Sets the current font for the printer.
  • PC_PRINTER_SET_PEN
    Set the width, style and colour for lines and rectangles when drawn using a printer.
  • PC_PRINTER_SET_POSITION
    Move the logical printer position ready for the next PC_PRINTER_WRITE.
  • PC_PRINTER_WRITE
    Writes a text string to the printer.
  • PC_PRINTER_WRITE_BMP
    Write a loaded bitmap to a printer at a specified position with a given size.
  • Printer Handling Routines Return Codes
Parent topic: Library Routines


PC_PRINT_FILE

Prints the contents of the specified file, optionally displaying printer control, font, and progress indicator dialog boxes, before commencing the print.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

CALL "PC_PRINT_FILE" using     filename
                               document-title
                     by value  flags
                     by value  window-handle
                     returning status-code

Parameters:

filename
Group predefined as cblt-printer-name containing:
01 cblt-printer-name       typedef
  03 cblt-pn-name-length   cblt-x2-comp5  *> pic x(2) comp-5
  03 cblt-pn-name          pic x(n).      *> pic x(n).
document-title
Group predefined as cblt-printer-name containing:
01 cblt-printer-name       typedef
  03 cblt-pn-name-length   cblt-x2-comp5  *> pic x(2) comp-5
  03 cblt-pn-name          pic x(n).      *> pic x(n).
flags
Using call prototype (see Key) : Numeric literal or cblt-x4-comp5.
Picture: Numeric literal or pic x(4) comp-5.
window-handle
Using call prototype (see Key) : Numeric literal or cblt-x4-comp5.
Picture: Numeric literal or pic x(4) comp-5.
status-code
See Library Routines - Key

On Entry:

filename
The name of the file to be printed (null or space terminated)
document-title
The title of the document to be printed
flags
A set of bits to define printer options:
bit 0 | Display a printer control dialog to allow you to define the printer characteristics - cannot be used with bit 2 or bit 3
bit 1 | Display a font dialog box to allow you to define the default font for the document
bit 2 | Print in portrait orientation - cannot be used with bit 0 or bit 3
bit 3 | Print in landscape orientation - cannot be used with bit 0 or bit 2
bit 4 | Display a progress indicator dialog box
bit 5 | Directs raw output through the Windows spooler - only bit 0 can be used with this bit
window-handle
Handle of parent window. The parent window is used as a reference for positioning dialog boxes. If window-handle is 0 the dialog boxes will be positioned in a system dependent position on the screen.

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_CLOSE

Closes a previously opened printer channel.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_CLOSE" using     printer-handle
                        returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
status-code | See Library Routines - Key

On Entry:

printer-handle The printer handle returned when the printer was opened

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_CONTROL

Sends a print command to a printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_CONTROL" using     printer-handle
                          by value  print-command
                          returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
print-command | Numeric literal or cblt-x4-comp5 | Numeric literal or pic x(4) comp-5.
status-code | See Library Routines - Key

On Entry:

printer-handle
The printer handle returned when the printer was opened.
print-command
The command to send to the printer:
1 | Abort printing the document and close the printer
2 | Throw a page
3 | Flush the print buffers
4 | Start a new line

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_DEFAULT_FONT

Sets the default font for all PC_PRINTER_ routines.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_DEFAULT_FONT" using     font-family-name
                               by value  font-size
                               by value  font-style
                               returning status-code

Parameters

font-family-name
Group predefined as cblt-printer-name containing:
01 cblt-printer-name       typedef.
  03 cblte-pn-name-length  cblt-x2-comp5. *> pic x(2) comp-5.
  03 cblte-pn-name         cblt-x1.       *> Occurs depending on
                                          *> cblte-pn-name-length.  pic x(n).
font-size
Call prototype (see Key): Numeric literal or cblt-x4-comp5
Picture: Numeric literal or pic x(4) comp-5.
font-style
Call prototype (see Key): Numeric literal or cblt-x4-comp5
Picture: Numeric literal or pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

cblte-pn-name-len | The length of the font family name.
cblte-pn-name | The family name of the font to be used (for example, Courier, Helvetica, Times, Symbol, Times New Roman, Roman, and so on).
font-size | Point size of font. If the point size is zero the font is reset to the system defaults.
font-style The font-style set:
Bit 15
The high-order 32-bits contain a printer character set as defined by Windows
Bit 3
Bold
Bit 2
Strikeout
Bit 1
Underline
Bit 0
Italic

All remaining bits are reserved for future use and should not be set.

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

Default parameters are not validated until the default printer is opened.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_DEFAULT_NAME

Sets the default printer for all PC_PRINTER_ routines.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_DEFAULT_NAME" using by value     flags
                                     by reference printer-name
                                     returning    status-code

Parameters

flags
Call prototype (see Key): Numeric literal or cblt-x4-comp5
Picture: Numeric literal or pic x(4) comp-5.
printer-name
Group predefined as cblt-printer-name containing:
01 cblt-printer-name       typedef.
  03 cblte-pn-name-length  cblt-x2-comp5. *> pic x(2) comp-5.
  03 cblte-pn-name         cblt-x1.       *> Occurs depending on
                                          *> cblte-pn-name-length.  pic x(n).
status-code
See Library Routines - Key.

On Entry:

flags | Flags controlling the behavior of the call. Must be set to 1.
cblte-pn-name-len | The length of the printer name.
cblte-pn-name | The text of the printer name to be used as the default printer.

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_DEFAULT_PROPERTIES

Sets one or more of the properties of the default printer for all PC_PRINTER_ routines.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_DEFAULT_PROPERTIES" using by value     flags
                                           by reference properties
                                           returning    status-code

Parameters

flags
Using call prototype (see Library Routines - Key) : cblt-os-flags
Picture: Numeric literal, pic x(4) comp-5, or pic x(8) comp-5 (64-bit native programs only).
properties
Group predefined as cblt-printer-properties containing:
01 cblt-printer-properties typedef
  03 cblte-pp-len           cblt-x2-comp5    pic x(2) comp-5.
  03 cblte-pp-papersize     cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-paperlength   cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-paperwidth    cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-scale         cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-copies        cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-papertray     cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-printquality  cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-color         cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-duplex        cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-orientation   cblt-sx2-comp5   pic s9(4) comp-5.
  03 cblte-pp-yresolution   cblt-sx2-comp5   pic s9(4) comp-5.
status-code
See Library Routines - Key

On Entry:

flags
Flags controlling which of the properties to change. Value is a combination of the following:
P-PAPERSIZE | 1
P-PAPERLENGTH | 2
P-PAPERWIDTH | 4
P-SCALE | 8
P-COPIES | 16
P-PAPERTRAY | 32
P-PRINTQUALITY | 64
P-COLOR | 128
P-DUPLEX | 256
P-ORIENTATION | 512
P-YRESOLUTION | 1024
cblte-pp-len
Must be set to the size of the properties buffer.
cblte-pp-papersize
Paper size, using one of the DMPAPER- constants defined in the file WINDOWS.CPY.
cblte-pp-paperlength
Paper length in tenths of a millimeter.
cblte-pp-paperwidth
Paper width in tenths of a millimeter.
cblte-pp-scale
Factor by which the output is to be scaled.
cblte-pp-copies
The number of copies to be printed.
cblte-pp-papertray
The number of the paper tray to be used, using one of the DMBIN- constants defined in the file WINDOWS.CPY.
cblte-pp-printquality
The print quality, using one of the DMRES- constants defined in the file WINDOWS.CPY, or if a positive value is used, the horizontal resolution in dots per inch.
cblte-pp-color
Switch between monochrome and color printing using one of the DMCOLOR- constants.
cblte-pp-duplex
Select duplex or double-sided printing using one of the DMDUP- constants.
cblte-pp-orientation
Select the paper orientation using one of the DMORIENT- constants.
cblte-pp-yresolution
The vertical resolution in dots per inch.

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

The file WINDOWS.CPY is provided with this COBOL system.

Default parameters are not validated until the default printer is opened.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_DRAW_RECTANGLE

Draws an outline or filled rectangle at position start-x, start-y to end-x, end-y.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_DRAW_RECTANGLE" using
                                 by value printer-handle
                                 by value draw-rectangle-options
                                 by value box-style
                                 by value start-x
                                 by value start-y
                                 by value end-x
                                 by value end-y
end-call

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5
draw-rectangle-options | cblt-x4-comp5 | pic x(4) comp-5
box-style | cblt-x4-comp5 | pic x(4) comp-5
start-x, start-y | cblt-x4-comp5 | pic x(4) comp-5
end-x, end-y | cblt-x4-comp5 | pic x(4) comp-5

On Entry:

printer-handle
The printer handle returned when the printer was opened; see PC_PRINTER_OPEN.
draw-rectangle-options
The options to apply to the rectangle. The valid options are:
Value | Meaning
0 | Use logical units of measurement
box-style
The style of rectangle to be drawn.
Value | Meaning
0 | outline
1 | filled
start-x, start-y
The starting point of the rectangle along the x-axis and y-axis.
end-x, end-y
The ending point of the rectangle along the x-axis and y-axis.

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

Drawing the resulting rectangle does not change the logical position on the page used by other printer routines.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_ENUM_CLOSE

Ends the process of enumerating printers.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_ENUM_CLOSE" using by reference enum-handle

Parameters

enum-handle
Call prototype (see Key): cblt-pointer.
Picture: pointer.

On Entry:

enum-handle
A valid enum-handle returned from PC_PRINTER_ENUM_START

On Exit:

return-value
One of:
0
Enumeration close completed
!= 0
PC_PRINTER error code

Example

01 enum-handle           pointer.
01 printer-name.
   03 p-name-len           pic x(2) comp-5.
   03 p-name               pic x(255).
01 enum-flags              pic x(4) comp-5 value 0.
01 enum-printers-found     pic x(4) comp-5 value 0.
01 p-counter      binary-long.

procedure division.
  move 1 to p-counter
  set p-name-len to length of p-name
  call "PC_PRINTER_ENUM_START" using
          by reference enum-handle
          by value enum-flags
          by reference enum-printers-found
  end-call
  if return-code not equal 0
       display "RC: Enum-Start : " return-code
  end-if
  display "Printers found : " enum-printers-found
  perform until return-code not equal 0
       set p-name-len to length of p-name
       call "PC_PRINTER_ENUM_NEXT" using
              by value enum-handle
              by reference printer-name
       end-call
       if return-code not equal 0
              display "RC: Enum-Next : " return-code
       else
              display p-counter " " p-name(1:p-name-len)
                   " size " p-name-len
       end-if
       add 1 to p-counter
  end-perform

  call "PC_PRINTER_ENUM_CLOSE" using
                  by reference enum-handle
  end-call
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines
Related information
Printer Handling Routines Return Codes


PC_PRINTER_ENUM_NEXT

Gets the name of the next enumerated printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_ENUM_NEXT" using by value enum-handle
                                   by reference printer-name

Parameters

enum-handle
Call prototype (see Key): cblt-pointer
Picture: pointer.
printer-name
A group predefined as
01 printer-name typedef.
  03 cblte-pn-name-len  pic x(2) comp-5.
  03 cblte-pn-name      pic x(n).

On Entry:

enum-handle
Valid enum-handle returned from PC_PRINTER_ENUM_START.
cblte-pn-name-len
The length of cblte-pn-name.
cblte-pn-name
Not set.

On Exit:

cblte-pn-name-len
The length of the printer name returned.
cblte-pn-name
The actual printer name.
return-value
One of:
0
Enumeration started
29
End of enumeration
30
cblte-pn-name is too small
or another PC_PRINTER error code

Example

01 enum-handle           pointer.
01 printer-name.
   03 p-name-len           pic x(2) comp-5.
   03 p-name               pic x(255).
01 enum-flags              pic x(4) comp-5 value 0.
01 enum-printers-found     pic x(4) comp-5 value 0.
01 p-counter      binary-long.

procedure division.
  move 1 to p-counter
  set p-name-len to length of p-name
  call "PC_PRINTER_ENUM_START" using
          by reference enum-handle
          by value enum-flags
          by reference enum-printers-found
  end-call
  if return-code not equal 0
       display "RC: Enum-Start : " return-code
  end-if
  display "Printers found : " enum-printers-found
  perform until return-code not equal 0
       set p-name-len to length of p-name
       call "PC_PRINTER_ENUM_NEXT" using
              by value enum-handle
              by reference printer-name
       end-call
       if return-code not equal 0
              display "RC: Enum-Next : " return-code
       else
              display p-counter " " p-name(1:p-name-len)
                   " size " p-name-len
       end-if
       add 1 to p-counter
  end-perform

  call "PC_PRINTER_ENUM_CLOSE" using
                  by reference enum-handle
  end-call

Comments

If cblte-pn-name-len is zero on entry, then cblte-pn-name-len is updated with the size required for cblte-pn-name (not the size of the group) and the enumeration remains on the current entry.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_ENUM_START

Starts the process of enumerating printers.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_ENUM_START" using by reference enum-handle
                                   by value enum-flags
                                   by reference number-of-printers-found

Parameters

enum-handle
Call prototype (see Key): cblt-pointer
Picture: pointer.
enum-flags
Call prototype (see Key): cblt_os_flags
Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
number-of-printers-found
Call prototype (see Key): cblt_os_size
Picture: pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).

On Entry:

enum-handle
Not set.
enum-flags
Flags controlling the behavior of the call. Must be set to 0.
number-of-printers-found
Not set.

On Exit:

enum-handle
Valid enumeration handle if number of printers > 0
number-of-printers-found
Number of printers found
return-value
One of:
0
Enumeration started
!= 0
PC_PRINTER error code

Example

01 enum-handle           pointer.
01 printer-name.
   03 p-name-len           pic x(2) comp-5.
   03 p-name               pic x(255).
01 enum-flags              pic x(4) comp-5 value 0.
01 enum-printers-found     pic x(4) comp-5 value 0.
01 p-counter      binary-long.

procedure division.
  move 1 to p-counter
  set p-name-len to length of p-name
  call "PC_PRINTER_ENUM_START" using
          by reference enum-handle
          by value enum-flags
          by reference enum-printers-found
  end-call
  if return-code not equal 0
       display "RC: Enum-Start : " return-code
  end-if
  display "Printers found : " enum-printers-found
  perform until return-code not equal 0
       set p-name-len to length of p-name
       call "PC_PRINTER_ENUM_NEXT" using
              by value enum-handle
              by reference printer-name
       end-call
       if return-code not equal 0
              display "RC: Enum-Next : " return-code
       else
              display p-counter " " p-name(1:p-name-len)
                   " size " p-name-len
       end-if
       add 1 to p-counter
  end-perform

  call "PC_PRINTER_ENUM_CLOSE" using
                  by reference enum-handle
  end-call
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines
Related information
Printer Handling Routines Return Codes


PC_PRINTER_FREE_BMP

Frees a bitmap from memory, releasing its image and palette back to the operating system.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_FREE_BMP" using     printer-handle
                           by value  bmp-id
                           returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
bmp-id | cblt-x4-comp5 | pic x(4) comp-5.
status-code | See Library Routines - Key

On Entry:

printer-handle
The printer handle returned when the printer was opened.
bmp-id
The unique id of the loaded bitmap, returned when the bitmap was loaded.

On Exit:

status-code
Printer status code:
0 | Successful
3 | Printer device not open
20 | Failed to free bitmap

Example:

call "PC_PRINTER_FREE_BMP" using     printer-handle
                           by value  bmp-idlogo
                           returning printer-retcode
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_GET_BMP_INFO

Retrieves the width and height of a loaded bitmap.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_GET_BMP_INFO" using
                               by reference printer-handle
                               by value bmp-id
                               by reference bmp-width
                               by reference bmp-height
                               returning status-code
end-call

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5
bmp-id | cblt-x4-comp5 | pic x(4) comp-5
bmp-width | cblt-x4-comp5 | pic x(4) comp-5
bmp-height | cblt-x4-comp5 | pic x(4) comp-5
status-code | See Library Routines - Key

On Entry:

printer-handle | The printer handle returned when the printer was opened
bmp-id | A valid ID returned from PC_PRINTER_LOAD_BMP

On Exit:

bmp-width | Width of the loaded bitmap
bmp-height | Height of the loaded bitmap
status-code | See Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_GET_COLOR

Gets the color on the printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_GET_COLOR" using        printer-handle
                            by value     fore-or-back
                            by reference color-red
                            by reference color-green
                            by reference color-blue
                            returning    status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
fore-or-back | cblt-x2-comp5 | pic x(2) comp-5.
color-red | cblt-x2-comp5 | pic x(2) comp-5.
color-green | cblt-x2-comp5 | pic x(2) comp-5.
color-blue | cblt-x2-comp5 | pic x(2) comp-5.
status-code | See Library Routines - Key |

On Entry:

printer-handle
The printer handle returned when the printer was opened.
fore-or-back
Whether to get the foreground or background color:
1 | Foreground
2 | Background

On Exit:

color-red
A value between 0 and 255, giving the intensity of red.
color-greem
A value between 0 and 255, giving the intensity of green.
color-blue
A value between 0 and 255, giving the intensity of blue.
status-code
Printer status code:
0 | Successful
3 | Printer device not open
22 | Failed to free bitmap

Comments:

You must open the printer before using this routine.

You can find out if your printer supports color by using the PC_PRINTER_INFO library routine.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_GET_FONT

Gets the font on the printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_GET_FONT" using     printer-handle
                                      font-family-name
                                      font-size
                                      font-style
                            returning status-code

Parameters

printer-handle
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
font-family-name
Group predefined as cblt-printer-name containing:
01 cblt-printer-name       typedef.
  03 cblte-pn-name-length  cblt-x2-comp5. *> pic x(2) comp-5.
  03 cblte-pn-name         cblt-x1.       *> Occurs depending on
                                          *> cblte-pn-name-length.  pic x(n).
font-size
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
font-style
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

printer-handle | The printer handle returned when the printer was opened.
cblte-pn-name-len | The length of the buffer for the font-family name.

On Exit:

printer-handle
The printer handle returned when the printer was opened.
cblte-pn-name-len
The length of the buffer for the font-family name.
name-len
The length of the buffer for the font-family name. If the length is zero no font is returned, and the operating system default is used (font-size and font-style are then invalid).
name-text
The family name of the font to be used (for example, Courier, Helvetica, Times, and so on).
font-size
The point-size of the font.
font-style
The font-style set:
3 | Bold
2 | Strikeout
1 | Underline
0 | Italic

All remaining bits are reserved for future.

Example:

 working-storage section.
 01.
   03 document-title.
     05 title-len           pic x(2) comp-5.
     05 title-text          pic x(20).

   03 font-family.
     05 font-family-namelen  pic x(2) comp-5 value 80.
     05 font-family-name     pic x(80).

   03 font-size              pic x(4) comp-5.
   03 font-style             pic x(4) comp-5.

   03 abort                  pic x(4) comp-5 value 1.
   03 control                pic x(4) comp-5 value 2.
   03 flags                  pic x(4) comp-5 value 3.
   03 handle                 pic x(4) comp-5.

 procedure division.
     move 17 to title-len
     move "Printer Info Test" to title-text

     call "PC_PRINTER_OPEN" using by reference handle
                                  by reference document-title
                                  by value flags
                                  by value 0
     end-call

     if return-code = zero
         call "PC_PRINTER_GET_FONT"
                               using by reference handle
                                     by reference font-family
                                     by reference font-size
                                     by reference font-style
         end-call
         if return-code equal zero
             if font-size equal zero
                 display "Current Font   : no font selected"
             else
                 display "Current Font   : "
                       font-family-name(1:font-family-namelen)
                 display "Font size      : " font-size
                 display "Raw Font Style : " font-style
             end-if
         else
             display "PC_PRINTER_GET_FONT failed"
         end-if
     end-if

     perform close-down-printer
     .

 close-down-printer section.
     call "PC_PRINTER_CONTROL" using by reference handle
                                     by value abort
     end-call

     call "PC_PRINTER_CLOSE" using by reference handle
     end-call
     .
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_INFO

Returns a native device context handle, and other information that can be used to enhance the printing of a document by calling native graphics functions directly.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_INFO using     cblt-pi-printer-handle
                                cblt-pi-printer-info-struct
                      returning status-code

Parameters:

cblt-pi-printer-handle
Using call prototype (see Library Routines - Key) : cblt-x4-comp5
Picture: pic x(4) comp-5.
cblt-pi-printer-info-struct
Group containing
01 print-info-struct
  03 cblt-pi-struct-size               cblt-os-size   *> pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
  03 cblt-pi-printer-hdc               cblt-pointer   *> pointer.
  03 cblt-pi-printer-hps               cblt-os-size   *> pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
  03 cblt-pi-printer-orientation       cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-rows              cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-cols              cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-rows-left         cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-max-horiz         cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-max-vert          cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-min-horiz         cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-min-vert          cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-curr-horiz        cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-curr-vert         cblt-x4-comp5  *> pic x(4) comp-5.
  03 cblt-pi-printer-copies            cblt-x2-comp5  *> pic 9(4) comp-5.
  03 cblt-pi-printer-quality           cblt-x2-comp5  *> pic 9(4) comp-5.
  03 cblt-pi-printer-color             cblt-x1-comp5  *> pic 99 comp-5.
  03 cblt-pi-reserved-item1            cblt-x1-comp5  *> pic 99 comp-5.
  03 cblt-pi-printer-device-ver        cblt-x2-comp5  *> pic 9(4) comp-5.
  03 cblt-pi-printer-name
    05 cblt-pi-printer-pname-size      cblt-os-size   *> pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
    05 cblt-pi-printer-pname           cblt-pointer   *> pointer.
  03 cblt-pi-printer-type
    05 cblt-pi-printer-ptype-size      cblt-os-size   *> pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
    05 cblt-pi-printer-ptype           cblt-pointer   *> pointer.
  03 cblt-pi-printer-device
    05 cblt-pi-printer-pdevice-size    cblt-os-size   *> pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
    05 cblt-pi-printer-pdevice         cblt-pointer   *> pointer.
  03 cblt-pi-printer-location
    05 cblt-pi-printer-plocation-size  cblt-os-size   *> pic x(4) comp-5 or	pic x(8) comp-5 (64-bit native only).
    05 cblt-pi-printer-plocation       cblt-pointer   *> pointer.
  03 p-comment
    05 cblt-pi-printer-pcomment-size   cblt-os-size   *> pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
    05 cblt-pi-printer-pcomment        cblt-pointer   *> pointer.
  03 cblt-pi-printer-type
    05 cblt-pi-printer-papersize-size  cblt-os-size   *> pic x(4) comp-5 or pic x(8) comp-5 (64-bit native only).
    05 cblt-pi-printer-papersize       cblt-pointer   *> pointer.
status-code
See Library Routines - Key

On Entry:

printer-handle
The printer handle returned when the printer was opened
cblt-pi-struct-size
The size of the structure
cblt-pi-printer-papersize
The size of the associated buffers
cblt-pi-printer-pcomment
The address of the buffer

On Exit:

cblt-pi-printer-hdc
Handle to the printer device context
cblt-pi-printer-hps
Reserved
cblt-pi-printer-orientation
Orientation of the printed output:
1 | portrait
2 | landscape
cblt-pi-printer-cols
Total number of columns on a page in the current font
cblt-pi-printer-rows_left
Number of rows left on the current page in the current font
cblt-pi-printer-max-horiz
Maximum value of graphics coordinate available in the horizontal axis
cblt-pi-printer-max-vert
Maximum value of graphics coordinate available in the vertical axis
cblt-pi-printer-min-horiz
Minimum value of graphics coordinate available in the horizontal axis
cblt-pi-printer-min-vert
Minimum value of graphics coordinate available in the vertical axis
cblt-pi-printer-curr-horiz
Current graphics X coordinate
cblt-pi-printer-curr-vert
Current graphics Y coordinate
cblt-pi-printer-copies
Number of copies
cblt-pi-printer-quality
The quality the printer is set to. Can be one of:
0 | Draft
1 | Low
2 | Medium
3 | High
4 | Printer's default
Otherwise the DPI is returned.
cblt-pi-printer-color
Color capabilities of the printer:
0 | Monochrome
1 | Color
cblt-pi-printer-version
Version number of the printer driver
cblt-pi-printer-pname-size
Size of the printer name
cblt-pi-printer-pname
Pointer to the name of the printer
cblt-pi-printer-ptype-size
Size of the printer type
cblt-pi-printer-ptype
Pointer to the cblt-pi-printer-type
cblt-pi-printer-pdevice-size
Size of the printer device
cblt-pi-printer-pdevice
Pointer to the printer device
cblt-pi-printer-plocation-size
Size of the printer's location
cblt-pi-printer-plocation
Pointer to the location of the printer
cblt-pi-printer-pcomment-size
Size of the printer's comment
cblt-pi-printer-pcomment
Pointer to the printer's comment
cblt-pi-printer-papersize-size
Size of the printer's paper size
cblt-pi-printer-papersize
Pointer to the printer's paper size
status-code
Printer Handling Routines Return Codes

Comments:

cblt-pi-printer-type specifies the type of printer; for example, HP or Canon.

cblt-pi-printer-device specifies the printer device; for example, lpt1:, :file or :com1. This parameter can be set to multiple devices; each device is separated by a comma (for example, lpt1:,lpt2:).

cblt-pi-printer-comment specifies any comment associated with the printer (for example, the printer might have the comment "Printer for accounts" defined for it).

paper-size defines the paper-size; for example, A4, or Letter.

Example:

$set remove(control)
working-storage section.
copy "cbltypes.cpy".
01 PRT-INFO-1 is typedef.
  03 pi-struct-size      cblt-os-size.
  03 hdc                 cblt-pointer.
  03 hps                 cblt-os-size.
  03 orientation         pic x(4) comp-5.
  03 rows                pic x(4) comp-5.
  03 cols                pic x(4) comp-5.
  03 rows-left           pic x(4) comp-5.
  03 max-horiz           pic x(4) comp-5.
  03 max-vert            pic x(4) comp-5.
 03 min-horiz           pic x(4) comp-5.
  03 min-vert            pic x(4) comp-5.
  03 curr-horiz          pic x(4) comp-5.
  03 curr-vert           pic x(4) comp-5.
  03 copies              pic 9(4) comp-5.
  03 quality             pic 9(4) comp-5.
  03 color               pic 99 comp-5.
  03 reserved1           pic x comp-5.
  03 driver-ver          pic 9(4) comp-5.
  03 pname.
    05 cbsize            cblt-os-size.
    05 buffer            pointer.
  03 ptype.
    05 cbsize            cblt-os-size.
    05 buffer            pointer.
  03 pdevice.
    05 cbsize            cblt-os-size.
    05 buffer            pointer.
  03 plocation.
    05 cbsize            cblt-os-size.
    05 buffer            pointer.
  03 pcomment.
    05 cbsize            cblt-os-size.
    05 buffer            pointer.
  03 ppapersize.
    05 cbsize            cblt-os-size.
    05 buffer            pointer.
01.
  03 document-title.
    05 title-len         pic x(2) comp-5.
    05 title-text        pic x(20).
      03  font-family.
    05 font-family-namelen  pic x(2) comp-5 value 80.
    05 font-family-name     pic x(80).
  03 print-info          PRT-INFO-1.
  03 abort               pic x(4) comp-5 value 1.
  03 control             pic x(4) comp-5 value 2.
  03 flags               pic x(4) comp-5 value 3.
  03 handle              pic x(4) comp-5.
01 cblt-pi-printer-name          pic x(255).
01 cblt-pi-printer-type          pic x(255).
01 cblt-pi-printer-device        pic x(255).
01 cblt-pi-printer-location      pic x(255).
01 cblt-pi-printer-comment       pic x(255).
01 cblt-pi-printer-papersize     pic x(255).

procedure division.
    move 17 to title-len
    move "Printer Info Test" to title-text

    call "PC_PRINTER_OPEN" using by reference handle
                                 by reference document-title
                                 by value flags
                                 by value 0
    end-call

    if return-code = zero
        move all x"0" to print-info
        move length of print-info to pi-struct-size
        set buffer of pname of print-info
            to address of cblt-pi-printer-name
        move 255 to cbsize of pname of print-info
        set buffer of ptype of print-info
            to address of cblt-pi-printer-type
        move 255 to cbsize of ptype of print-info
        set buffer of pdevice of print-info
             to address of cblt-pi-printer-device
        move 255 to cbsize of pdevice of print-info
        set buffer of plocation of print-info
            to address of cblt-pi-printer-location
        move 255 to cbsize of plocation of print-info
        set buffer of pcomment of print-info
            to address of cblt-pi-printer-comment
        move 255 to cbsize of pcomment of print-info
        set buffer of ppapersize of print-info
            to address of cblt-pi-printer-papersize
        move 255 to cbsize of ppapersize of print-info
        call "PC_PRINTER_INFO" using by reference handle
                                     by reference print-info
        end-call
        display return-code
        if return-code not equal zero
            display "PC_PRINTER_INFO failed (return-code)"
            display "   === " return-code
            perform close-down-printer
            stop run
        end-if
        display "Orientation   : " orientation of print-info
        display "Rows          : " rows of print-info
        display "Cols          : " cols of print-info
        display "Rows Left     : " rows-left of print-info
        display "Max horz      : " max-horiz of print-info
        display "Max vert      : " max-vert of print-info
        display "Min horz      : " min-horiz of print-info
        display "Min vert      : " min-vert of print-info
        display "Current horz  : " curr-horiz of print-info
        display "Current vert  : " min-vert of print-info
        display "Copies        : " copies of print-info
        display "Quality       : " no advancing
        evaluate quality of print-info
         when 0 display "Draft"
         when 1 display "Low"
         when 2 display "Medium"
         when 3 display "High"
         when 4 display "printers default used"
         when other display quality of print-info " DPI"
        end-evaluate
        display "Color         : " no advancing
        if color of print-info equals 0
            display "Mono Chrome"
        else
            display "Color"
        end-if
        if cbsize of pname of print-info equal 0
            display "Printer name  : not available"
        else
            display "Printer name  : "
                    cblt-pi-printer-name(1:
                         cbsize of pname of print-info)
           display "Printer name  size : "
                   cbsize of pname of print-info
        end-if
        if cbsize of ptype of print-info equal 0
           display "Printer type  : not available"
        else
            display "Printer type  : "
                    cblt-pi-printer-type(1:
                         cbsize of ptype of print-info)
            display "Printer type size : "
                    cbsize of ptype of print-info
        end-if
        if cbsize of pdevice of print-info equal 0
            display "Printer device: not available"
        else
            display "Printer device(s): "
                    cblt-pi-printer-device(1:
                         cbsize of pdevice of print-info)
            display "Printer device size : "
                    cbsize of pdevice of print-info
        end-if
        if cbsize of plocation of print-info equal 0
            display "Printer location: not available"
        else
            display "Printer location: "
                    cblt-pi-printer-location(1:
                         cbsize of plocation of print-info)
            display "Printer location size : "
                    cbsize of plocation of print-info
        end-if
        if cbsize of pcomment of print-info equal 0
            display "Printer comment: not available"
        else
            display "Printer comment: "
                    cblt-pi-printer-comment(1:
                         cbsize of pcomment of print-info)
            display "Printer comment size : "
                    cbsize of pcomment of print-info
        end-if
        if cbsize of ppapersize of print-info equal 0
            display "Printer papersize: not available"
        else
            display "Printer papersize: "
                    cblt-pi-printer-papersize(1:
                         cbsize of ppapersize of print-info)
            display "Printer papersize size : "
                    cbsize of ppapersize of print-info
        end-if
        display "Driver version : "driver-ver of print-info
    end-if
    perform close-down-printer
    .

close-down-printer section.
    call "PC_PRINTER_CONTROL" using by reference handle
                                    by value abort
    end-call

    call "PC_PRINTER_CLOSE" using by reference handle
    end-call
    .
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_INFO_DOTNET

Enables the access to the native Hdc for a printer. Invokes a delegate with the current .NET Graphics object for the printer handle along with a Rectangle object and the PageSettings object.
Restriction:
  • This routine is supported in .NET COBOL only.
  • This routine is not currently supported on UNIX platforms.

Syntax:

    call "PC_PRINTER_INFO_DOTNET" using
                                    by reference cblt-pi-printer-handle
                                    by value cblt-printer-info-delegate
                                    by value user-object
                          returning status-code
    end-call

Parameters:

 | Using call prototype | Picture (32-bit systems) | Picture (64-bit systems)
printer-handle | cblt-pi-printer-handle | pic x(4) comp-5 | pic x(8) comp-5
delegate | cblt-printer-info-delegate | see delegate-id above | see delegate-id above
user-object | object | object | object
cblt-printer-info-delegate
A delegate defined as:
    delegate-id PrinterInfoDelegate.
            procedure division using by value gr as type Graphics
                                 by value pb as type Rectangle
                                 by value ps as type PageSettings
                                 by value uo as object
                                .
    end delegate.
status-code
See Library Routines - Key

On Entry:

printer-handle
The printer handle returned when the printer was opened
delegate
A delegate that receives either the Graphics, Rectangle, PageSettings or the user-object
user-object
Any object you might want to use in the delegate.

On Exit:

delegate
The delegate parameter is invoked with the required parameters
status-code
Printer Handling Routines Return Codes

Accessing native resources:

The PC_PRINTER_INFO is unable to return the underlying Hdc attribute for a printer connection on the .NET platform as the attribute is only available during a page-event. You can use the PC_PRINTER_INFO_DOTNET API, however, to access the native Hdc for the printer.

In the delegate, you can use the GetHdc() and the ReleaseHdc() methods on the graphics object. For example:

    declare dn-hdc = gr::GetHdc()
    try
        *> use the dn-hdc
    finally
       invoke gr::ReleaseHdc()
    end-try

Examples:

The following example shows how to use the PC_PRINTER_INFO_DOTNET API:

        $set iltarget"x86"
        $set ilref"System.Drawing"
        $set ilusing"System.Drawing".
        $set ilusing"System.Drawing.Printing".

        program-id. pcid.
        special-names.
            call-convention 74 is winapi.
        working-storage section.
        copy "cbltypes.cpy".
        01.
            03 document-title.
            05 title-len         pic x(2) comp-5.
            05 title-text        pic x(20).
                03  font-family.
            05 font-family-namelen  pic x(2) comp-5 value 80.
            05 font-family-name     pic x(80).
            03 abort               pic x(4) comp-5 value 1.
            03 ctrl                pic x(4) comp-5 value 2.
            03 flags               pic x(4) comp-5 value 1.
            03 handle              pic x(4) comp-5.
        01 status-code cblt-os-size value zeroes.

        procedure division.
            move 30 to title-len
            move "PC_PRINTER_INFO_DOTNET Example" to title-text

            call "PC_PRINTER_OPEN" using by reference handle
                                            by reference document-title
                                            by value flags
                                            by value 0
                                            returning status-code
            end-call
            if status-code not equal 0
                exhibit named status-code
                stop run
            end-if

            declare pinfo-delegate as type PrinterInfoDelegate
            set pinfo-delegate to
                delegate(gr as type Graphics,
                        pb as type Rectangle,
                        ps as type PageSettings
                        uo as object )

                *> create an Eclipse the side of the page
                    declare customColor = type Color::FromArgb(50, type Color::Blue)
                    declare shadowBrush = new SolidBrush(customColor)

                    invoke gr::FillEllipse(shadowBrush, pb)

                    declare bigText as string = uo as string
                    declare drawFormat = new StringFormat
                    set drawFormat::Alignment to type StringAlignment::Center
                    set drawFormat::LineAlignment to type StringAlignment::Center

                    invoke gr::DrawString(bigText, new Font("Courier New", 24), new SolidBrush(type Color::Red), pb, drawFormat)

                end-delegate

            declare nullObject as object = null

            call "PC_PRINTER_INFO_DOTNET" using
                    by reference handle
                    by value pinfo-delegate
                    by value "Big Red text in the middle"
                    returning status-code
            end-call
            if status-code not equal 0
                exhibit named status-code
            end-if

            call "PC_PRINTER_CLOSE" using
                by reference handle
                returning status-code
            end-call
            if status-code not equal 0
                exhibit named status-code
                stop run
            end-if
            goback.
        end program.

        delegate-id PrinterInfoDelegate.
            procedure division using by value gr as type Graphics
                                    by value pb as type Rectangle
                                    by value ps as type PageSettings
                                    by value uo as object
                                    .
        end delegate.

The following example shows how to create an anonymous delegate (without specifying a name for the delegate) and then use it with the PC_PRINTER_INFO_DOTNET API:

        declare pinfo-delegate as type PrinterInfoDelegate
        set pinfo-delegate to
                delegate(gr as type Graphics,
                        pb as type Rectangle,
                        ps as type PageSettings
                        uo as object)

                    display "DpiX = " gr::DpiX
                    display "DpiY = " gr::DpiY

                    display "Page Boundary : " pb
                    display "Page Settings : " ps
               end-delegate

You can use this delegate with the PC_PRINTER_INFO_DOTNET API as follows:

        call "PC_PRINTER_INFO_DOTNET" using
                    by reference handle
                    by value pinfo-delegate
                    by value self  *> user-object is the program itself
                                    *> so you can do a pinfo-delegate to the entry-point
        end-call
Parent topic: Printer Routines


PC_PRINTER_LINE_FROM_TO

Draws a line from start-x,start-y to end-x,end-y.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_LINE_FROM_TO" using
                               by value printer-handle
                               by value lineFrom-options
                               by value start-x
                               by value start-y
                               by value end-x
                               by value end-y
end-call

Parameters:

 | Using call prototype (see Key) | Picture
lineFrom-options | cblt-x4-comp5 | pic x(4) comp-5.
start-x, start-y | cblt-x4-comp5 | pic x(4) comp-5.
end-x, end-y | cblt-x4-comp5 | pic x(4) comp-5.

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

The resulting line does not change the logical position on the page for use with other printer routines.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_LOAD_BMP

Loads a bitmap or other supported file format into memory ready for the PC_PRINTER_WRITE_BMP function.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_LOAD_BMP"  using        printer-handle
                           by reference bmpfilename
                           by reference bmp-id
                           returning    status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
bmpfilename | pic x(n). | pic x(n).
bmp-id | cblt-x4-comp5 | pic x(4) comp-5.
status-code | See Library Routines - Key

On Entry:

printer-handle
The printer handle returned when the printer was opened.
bmpfilename
The name of the bitmap or other supported file format to be loaded (the name should be terminated with a null or space).

On Exit:

bmp-id
A unique identifier for the loaded file.
status-code
Printer status code:
0 | Successful
3 | Printer device not open
18 | Failed to load bitmap
19 | Invalid bitmap identifier

Comments:

The following file formats are supported: BMP.

This routine is available only in the Windows environment.

Example:

call "PC_PRINTER_LOAD_BMP" using printer-handle
                             by reference "mflogo.bmp" & x"0"
                             by reference bmp-id
                           returning  printer-retcode.
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_OPEN

Opens a printer channel, giving it a document title, and optionally displaying printer control, font, and progress indicator dialog boxes
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_OPEN" using     printer-handle
                                 document-title
                       by value  flags
                       by value  window-handle
                       returning status-code

Parameters

printer-handle
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
document-title
Group predefined as cblt-printer-name containing:
01 cblt-printer-name       typedef.
  03 cblte-pn-name-length  cblt-x2-comp5. *> pic x(2) comp-5.
  03 cblte-pn-name         cblt-x1.       *> Occurs depending on
                                          *> cblte-pn-name-length.  pic x(n).
flags
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
window-handle
Call prototype (see Key): Numeric literal or cblt-x4-comp5
Picture: Numeric literal or pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

cblte-pn-name-length | The length of the document title
cblte-pn-name | The title of the document to be printed
flags A set of bits to define printer options:
Bit 0
Display a printer control dialog to allow you to define the printer characteristics (cannot be used with bit 2 or bit 3)
Bit 1
Display a font dialog box to allow you to define the default font for the document
Bit 2
Print in portrait orientation (cannot be used with bit 0 or bit 3)
Bit 3
Print in landscape orientation (cannot be used with bit 0 or bit 2)
Bit 4
Display a progress indicator dialog box

All remaining bits are reserved for future use and should not be set

window-handle | Handle of parent window to use for positioning of dialog boxes. If handle is 0 the dialog boxes will be positioned in a system-dependent position on the screen.
printer-handle | Returns a handle to be used for subsequent printer operations for a successful open.

On Exit:

printer-handle | Returns a handle to be used for subsequent printer operations for a successful open.
status-code | Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_REDIRECTION_PROC

Registers a user function that is called when a program uses OPEN OUTPUT syntax and the ASSIGN TO PRINTER clause.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_REDIRECTION_PROC" by value flags
                                            user-func

Parameters:

 | Using call prototype (see Key) | Picture
flags | cblt-x4-comp5 | pic x(4) comp-5.
user-func | cblt-ppointer | usage procedure pointer.

On Entry:

flags | Reserved for future use. Must be set to 0.
user-func | A pointer to a procedure that will manipulate the printer.

Comments:

This routine enables you to set and manipulate fonts on the printer while using standard COBOL OPEN OUTPUT syntax and the ASSIGN TO PRINTER clause.

You must set the tunable printer-redirection in order for this call to operate correctly.

You must set the COBOL clause local-storage section in the program, to avoid run-time system error 166.

A call to PC_PRINTER_REDIRECTION_PROC registers the user function pointed to by user-func with the run-time system.

The user function should have the form:

entry "user-func" using by value printer-handle
 ...
 ...
exit program returning return-value.

printer-handle should be defined as a pic x(4) comp-5 data item.

When an OPEN statement opens a printer the user function is called and the printer handle returned in printer-handle. The user function can then manipulate the printer using the PC_PRINTER_ library routines. The user function should return a value to the run-time system to determine the next sequence of events.

You should code your user procedure to return a return-code 0 if it is called successfully, and any other value if it is not. If your user function does return a non-zero value, the run-time system closes the printer and a file status 9/005 is returned on the OPEN OUTPUT statement that invoked the user function.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_SET_BACKGROUND_MIX_MODE

Sets background printing mode.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_SET_BACKGROUND_MIX_MODE" using
                                          by value printer-handle
                                          by value background-mode
end-call

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
background-mode | cblt-x4-comp5 | pic x(4) comp-5.

On Entry:

 | Value | Meaning
printer-handle |  | The printer handle returned when the printer was opened.
background-mode | 0 | transparent
 | 1 | opaque

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_SET_COLOR

Sets the color on the printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_SET_COLOR"  using    printer-handle
                            by value  fore-or-back
                            by value  color-red
                            by value  color-green
                            by value  color-blue
                            returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
fore-or-back | cblt-x2-comp5 | pic x(2) comp-5.
color-red | cblt-x2-comp5 | pic x(2) comp-5.
color-green | cblt-x2-comp5 | pic x(2) comp-5.
color-blue | cblt-x2-comp5 | pic x(2) comp-5.
status-code | See Library Routines - Key

On Entry:

printer-handle
The handle of the printer, returned when the printer was opened.
fore-or-back
Whether to set the foreground or background color:
1 | Foreground
2 | Background
color-red
Value between 0 and 255; intensity of red
color-green
Value between 0 and 255; intensity of green
color-blue
Value between 0 and 255; intensity of blue

On Exit:

status-code No status codes are returned by this routine.

Comments:

You must open the printer before using this routine.

You specify the color you want by combinations of values showing the intensity of the three primary colors. For example, to get the colors in the following table, you set the RGB values as shown:

Color | Red | Green | Blue
Red | 255 | 0 | 0
Yellow | 255 | 255 | 0
Green | 0 | 255 | 0
Cyan | 0 | 255 | 255
Blue | 0 | 0 | 255
Magenta | 255 | 0 | 255
White | 255 | 255 | 255
Black | 0 | 0 | 0

Some other, more unusual, colors are:

Color | Red | Green | Blue
Dark orange | 255 | 140 | 0
Navy blue | 0 | 0 | 128
Violet | 238 | 120 | 238
Beige | 245 | 245 | 220

If your printer does not support color, it is up to the printer device driver to interpret these values. For example, some perform gray-shading; others choose either black or white for each color.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_SET_DEFAULT

Sets a process-wide default printer before a printer is opened.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_SET_DEFAULT" using by value default-option
                              by reference   default-struct
                              returning      status-code

Parameters

default-option
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
default-struct
Group predefined as cblt-printer-default containing:
01 cblt-printer-default                typedef.
  03 cblte-pd-printer-name.
    05 cblte-pd-printer-name-length    cblt-x2-comp5.	*> pic x(2) comp-5.
    05 cblte-pd-printer-name           cblt-x1.       *> Occurs depending on
                                                      *> cblte-pd-printer-name-length.
                                                      *> pic x (printer name length)
  03 cblte-pd-printer-browse REDEFINES cblte-pd-printer-name.
    05 cblte-pd-printer-browse-hwnd    cblt-HWND.     *> pic x(4) comp-5.
    05 cblte-pd-printer-browse-namelen cblt-x2-comp5. *> pic x(2) comp-5.
    05 cblte-pd-reserved               cblt-x2-comp5. *> pic x(2) comp-5.
    05 cblte-pd-printer-browse-name    cblt-x1.       *> Occurs depending on
                                                      *> cblte-pd-printer-browse-namelen.
                                                      *> pic x (printer name length)
status-code
See Library Routines - Key.

On Entry:

default-option
Specifies the default option:
1 | Sets the default printer to be used
2 | Browses for a default printer.
Whendefault-option is set to 1:
printer-name-length
The length of the printer-name
printer-name
The name of the printer
Whendefault-option is set to 2:
browser-hwnd
The handle for the printer browser

On Exit:

When default-option is set to 2:
printer-name-length
The length of the printer-name
printer-name
The name of the printer
reserved
Reserved.
status-code
Printer Handling Routines Return Codes

Comments:

If you set default-option to 2, this function returns the user-selected printer but does not set it as the default printer.

The printer name must be entered as UNC format (that is, the device's full name as it appears on the network).

Examples:

Example 1:

The following example shows how to use PC_PRINTER_SET_DEFAULT to set the default printer.

 working-storage section.
 01 MyDocumentInfo.
   03 filename.
     05 len              pic x(2) comp-5.
     05 body             pic x(128).
   03 document.
     05 len              pic x(2) comp-5.
     05 body             pic x(128).
   03 document-flags     pic x(4) comp-5.
   03 window-hwnd        pic x(4) comp-5.
 01 Printer-RetCode pic  9(4) comp-5.

 78 USE-OPEN-DIALOG      value 1.
 78 USE-FONT-DIALOG      value 2.
 78 USE-FORCE-PORTRAIT   value 4.
 78 USE-FORCE-LANDSCAPE  value 8.
 78 USE-PROGRESS-DIALOG  value 16.

 01 default-info.
   03 option             pic x(4) comp-5.
   03 ourprinter.
     05 len              pic x(2) comp-5.
     05 body             pic x(128).

 78 SET-DEFAULT-PRINTER  value h"0001".
 procedure division.

     move "My Color PS"
       to body of ourprinter of default-info
     move 11 to len of ourprinter of default-info
     move SET-DEFAULT-PRINTER to option of default-info

     call "PC_PRINTER_SET_DEFAULT" using
                     by value option of default-info,
                     by reference ourprinter of default-info
           returning Printer-RetCode
     end-call

     if Printer-RetCode not equal zero
         display "Unable to setup a default printer"
         display " + Retcode = " Printer-RetCode
         stop run
     end-if

     move "c:\config.sys" to body of filename
     move 13 to len of filename

     move "My Config.sys" to body of document
     move 13 to len of document

     move USE-PROGRESS-DIALOG to document-flags
     move zero to window-hwnd

     call "PC_PRINT_FILE" using by reference filename
                                by reference document
                                by value document-flags
                                by value window-hwnd
                                returning Printer-RetCode
     end-call

     if Printer-RetCode not equal zero
         display "PC_PRINT_FILE failed.. " Printer-RetCode
     else
         display "PC_PRINT_FILE: OK"
     end-if
     .

Example 2:

The following example shows how to use PC_PRINTER_SET_DEFAULT to browse for a printer.

 working-storage section.
 01 MyDocumentInfo.
   03 filename.
     05 len                 pic x(2) comp-5.
     05 body                pic x(128).
   03 document.
     05 len                 pic x(2) comp-5.
     05 body                pic x(128).
   03 document-flags        pic x(4) comp-5.
   03 window-handle         pic x(4) comp-5.

 01 MyDefaultPrinter.
   03 hwnd                  pic x(4) comp-5.
   03 len                   pic x(2) comp-5.
   03 reserved              pic x(2) comp-5.
   03 body                  pic x(128).

 01 Printer-RetCode         pic 9(4) comp-5.

 78 USE-OPEN-DIALOG         value 1.
 78 USE-FONT-DIALOG         value 2.
 78 USE-FORCE-PORTRAIT      value 4.
 78 USE-FORCE-LANDSCAPE     value 8.
 78 USE-PROGRESS-DIALOG     value 16.

 01 default-info.
   03 option                pic x(4) comp-5.
   03 ourprinter.
     05 len                 pic x(2) comp-5.
     05 body                pic x(128).

 78 SET-DEFAULT-PRINTER     value h"0001".
 78 BROWSE-DEFAULT-PRINTER  value h"0002".

 procedure division.
     move BROWSE-DEFAULT-PRINTER to option of default-info
     move 0 to hwnd of MyDefaultPrinter
     move 127 to len of MyDefaultPrinter

     call "PC_PRINTER_SET_DEFAULT" using
                             by value option of default-info
                             by reference MyDefaultPrinter
                   returning Printer-RetCode
     end-call

     if Printer-RetCode not equal zero
         display "Unable to browse for a default printer"
         display " + Retcode = " Printer-RetCode
         stop run
     end-if

     display "Browse Printer : "
         body of MyDefaultPrinter(1:len of MyDefaultPrinter)

     move SET-DEFAULT-PRINTER to option of default-info
     move len of MyDefaultPrinter to len of ourprinter
     move body of MyDefaultPrinter(1:len of MyDefaultPrinter)
         to body of ourprinter

     call "PC_PRINTER_SET_DEFAULT" using
                     by value option of default-info
                     by reference ourprinter of default-info
                     returning Printer-RetCode
     end-call

     if Printer-RetCode not equal zero
         display "Unable to set a default printer"
         display " + Retcode = " Printer-RetCode
         stop run
     end-if

     move "c:\config.sys" to body of filename
     move 13 to len of filename

     move "My Config.sys" to body of document
     move 13 to len of document

     move USE-PROGRESS-DIALOG to document-flags
     move zero to window-handle

     call "PC_PRINT_FILE" using by reference filename
                                by reference document
                                by value document-flags
                                by value window-handle
                          returning Printer-RetCode
     end-call

     if Printer-RetCode not equal zero
         display "PC_PRINT_FILE failed.. " Printer-RetCode
     else
         display "PC_PRINT_FILE: OK"
     end-if.
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_SET_FONT

Sets the current font for the printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_SET_FONT" using     printer-handle
                                     font-family-name
                           by value  font-size
                           by value  font-style
                           returning status-code

Parameters

printer-handle
Call prototype (see Key): cblt-x4-comp5
Picture: pic x(4) comp-5.
font-family-name
Group predefined as cblt-printer-name containing:
01 cblt-printer-name       typedef.
  03 cblte-pn-name-length  cblt-x2-comp5. *> pic x(2) comp-5.
  03 cblte-pn-name         cblt-x1.       *> Occurs depending on
                                          *> cblte-pn-name-length.  pic x(n).
font-size
Call prototype (see Key): Numeric literal or cblt-x4-comp5
Picture: Numeric literal or pic x(4) comp-5.
font-style
Call prototype (see Key): Numeric literal or cblt-x4-comp5
Picture: Numeric literal or pic x(4) comp-5.
status-code
See Library Routines - Key.

On Entry:

printer-handle | The printer handle returned when the printer was opened.
name-len | The length of the font family name.
name-text | The family name of the font to be used (for example, Courier, Helvetica, Times, Symbol, Times New Roman, Roman, and so on).
font-size | Point size of font.
font-style Set of bits defining the required font style:
Bit 15
The high-order 32-bits contain a printer character set as defined by Windows
Bit 3
Bold
Bit 2
Strikeout
Bit 1
Underline
Bit 0
Italic

All remaining bits are reserved for future use and should not be set.

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_SET_PEN

Set the width, style and colour for lines and rectangles when drawn using a printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_SET_PEN" using
                          by value Printer-Handle
                          by value Pen-Width
                          by value Pen-Style
                          by value Pen-red
                          by value Pen-blue
                          by value Pen-green
end-call

Parameters:

 | Using call prototype (see Key) | Picture
pen-width | cblt-x4-comp5 | pic x(4) comp-5.
pen-width | cblt-x4-comp5 | pic x(4) comp-5.
pen-red | cblt-x | pic x
pen-blue | cblt-x | pic x
pen-green | cblt-x | pic x

On Entry:

 | Value | Meaning
pen-style | 0 | solid line
 | 1 | dash
 | 2 | dot
 | 3 | dash, Dot
 | 4 | dash, dot, dot
 | 5 | invisible
pen-width |  | width of line when drawing lines or rectangles
pen-red | Value between 0 and 255 | intensity of red
pen-green | Value between 0 and 255 | intensity of green
pen-blue | Value between 0 and 255 | intensity of blue

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_SET_POSITION

Move the logical printer position ready for the next PC_PRINTER_WRITE.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_SET_POSITION" using
                               by value printer-handle
                               by value set-options
                               by value new-x
                               by value new-y
end-call

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
set-options | cblt-x4-comp5 | pic x(4) comp-5.
new-x | cblt-x4-comp5 | pic x(4) comp-5.
new-y | cblt-x4-comp5 | pic x(4) comp-5.

On Entry:

printer-handle
The printer handle returned when the printer was opened.
set-options
Units of measurement. Can be one of:
0 | use logical units
1 | use char units
new-x
position on the x-axis.
new-y
position on the y-axis.

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

If SET-OPTIONS-USE-CHAR-UNITS is used, ensure you have selected a fixed pitch/monospace font such as Courier New and Lucida Console.

Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_WRITE

Writes a text string to the printer.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_WRITE" using     printer-handle
                                  print-buffer
                        by value  print-buffer-len
                        returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
print-buffer | pic x(n). | pic x(n).
print-buffer-len | Numeric literal or cblt-x4-comp5 | Numeric literal or pic x(4) comp-5.
status-code | See Library Routines - Key |

On Entry:

printer-handle | The printer handle returned when the printer was opened
print-buffer | The buffer from which the bytes are to be printed
print-buffer-len | The number of bytes to print

On Exit:

status-code Printer Handling Routines Return Codes
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


PC_PRINTER_WRITE_BMP

Write a loaded bitmap to a printer at a specified position with a given size.
Restriction: This routine is not currently supported on UNIX platforms.

Syntax:

call "PC_PRINTER_WRITE_BMP" using      printer-handle
                            by value  bmp-id
                            by value  options
                            by value  bmp-row
                            by value  bmp-col
                            by value  bmp-width
                            by value  bmp-height
                            returning status-code

Parameters:

 | Using call prototype (see Key) | Picture
printer-handle | cblt-x4-comp5 | pic x(4) comp-5.
options | cblt-x4-comp5 value 0 | pic x(4) comp-5 value 0.
bmp-id | cblt-x4-comp5 | pic x(4) comp-5.
bmp-row | cblt-x4-comp5 | pic x(4) comp-5.
bmp-col | cblt-x4-comp5 | pic x(4) comp-5.
bmp-width | cblt-x4-comp5 | pic x(4) comp-5.
bmp-height | cblt-x4-comp5 | pic x(4) comp-5.
status-code | See Library Routines - Key

On Entry:

printer-handle
The printer handle returned when the printer was opened.
options
Bit 1: Preserve the aspect ratio of the bitmap.
Bit 2: Center the bitmap if bitmap aspect ratio is preserved.
Bit 9: Use bmp-row, bmp-col, bmp-width, bmp-height as logical units rather than character positions.
bmp-id
The unique id of the bitmap to print.
bmp-row
The row at which the bitmap is to be printed.
bmp-width
The width of the bitmap in characters. The value you specify is multiplied by the width of the currently selected font to determine the width that is used when printing the bitmap.
bmp-height
The height of the bitmap in characters. The value you specify is multiplied by the height of the currently selected font to determine the height that is used when printing the bitmap.
status-code
Printer status code:
0 | Successful
3 | Printer device not open
4 | Out of memory while printing
5 | Disk full while spooling file
7 | Print job aborted, no file spooled to Print Manager
11 | Write failure
21 | Failed to print bitmap
31 | Bad position; x or y out of bounds
32 | Move to x,y failed
33 | Line to x,y failed
34 | Rectangle failed to be drawn

On Exit:

status-code Printer Handling Routines Return Codes

Comments:

Restrictions:

  • This routine works with PostScript and HP PCL printers.
  • This routine is not supported on HP DeskJet or dot matrix printers.

Example:

 call "PC_PRINTER_WRITE_BMP" USING printer-handle
                                   BY VALUE  bmp-id-logo
                                   BY VALUE  3 size 4
                                   BY VALUE  7 size 4
                                   BY VALUE  5 size 4
                                   BY VALUE  25 size 4
                                   BY VALUE  15 size 4
                                                     RETURNING printer-retcode
 end-call
Parent topic: Printer Routines
Parent topic: Alphabetical List of Library Routines


Printer Handling Routines Return Codes

Possible return codes from the printer handling library routines are:

0 | Success
1 | Could not open printer device
2 | Invalid printer control code specified
3 | No printer device associated with specified handle
4 | Out of memory while printing
5 | Failed to open file
6 | Disk full while spooling file
7 | Print job aborted. No job sent to print spooler
8 | Printer information structure badly constructed
9 | No default printer found
10 | Error attempting to display dialog
11 | Write failure
12 | No fonts found usable with this printer
13 | The font requested does not exist
14 | User aborted print job
15 | Reserved
16 | Reserved
17 | Reserved
18 | Failed to load bitmap
19 | Invalid bitmap id
20 | Failed to free bitmap
21 | Failed to print bitmap
22 | Bad parameter
23 | Internal error
24 | User pressed Cancel on the printer setup dialog or on the font selection dialog
25 | Unsupported function
26 | Duplex not supported
27 | Paper tray not found
28 | Paper size not supported
29 | Printer enumeration started
30 | End of printer enumeration
31 | Bad position - x or y out of bounds
32 | Move to x,y failed
33 | Line to x,y failed
34 | Rectangle failed to be drawn
Parent topic: Printer Routines
Related information
Alphabetical List of Library 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 is more convenient than using a cblte-cppb-userdata-length parameter set to zero (applies to Windows environments only), but 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. In this case it is probably more appropriate for the application to allocate and copy the entire data structure itself, and pass the copy using a cblte-cppb-userdata-length of zero.

In .NET, do not specify a cblte-cppb-userdata-length of zero.

Specifying a cblte-cppb-userdata-length parameter of zero

If the cblte-cppb-userdata-length parameter is set to zero (and therefore the original cblte-cppb-userdata parameter specified to the registration process is passed to the cblte-cppb-callback), it is up to the cblte-cppb-callback to delete or deallocate all data structures within that block.

It should be noted that special care must be taken when using this method to pass a cblte-cppb-userdata parameter, especially if the same cblte-cppb-userdata area is registered to more than one registration-handle (the registration handle is returned on exit by the cblte-cppb-handle parameter). Specifically, care must be taken to ensure that any allocated resources are deallocated exactly once, and that allocated resources remain valid until after the last registration-handle to which they are associated has been destroyed. This can usually be accomplished by having a usage-count field somewhere in the cblte-cppb-userdata area, which is incremented each time the cblte-cppb-userdata parameter is registered to a registration-handle and decremented each time a cblte-cppb-callback is called with it as a parameter.

Priorities (set using a value of 1 to function) must be between 0 and 127 for user-code. Priorities 200 to 209 are reserved for File Handler usage. Specifying any other priority value will cause unpredictable results. The default value of 64 should be acceptable for most applications.

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
200 | Windows: A run-time error occurred in the run unit, or the called program was not found, or an internal logic error occurred
255 | UNIX: 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.

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

In .NET, this call only works within a run unit, meaning that memory cannot be shared across run units.

Named values provide a way of passing pointers between different run units using a name agreed at run time. Named values can be read simultaneously by all units in the coru because the run-time system protects and serializes any updates. The maximum number of named values depends on how much memory your machine has.

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:

In .NET, this call only works within a run unit, meaning that memory cannot be shared across run units.

Named values provide a way of passing pointers between different run-units using a name agreed at run-time. Named values can be read simultaneously by all units in the coru because the run-time system protects and serializes any updates. The maximum number of named values depends on how much memory your machine has.

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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:

Windows platforms:

B"10000000" | BACKGROUND HIGHLIGHT
B"01000000" | BACKGROUND-COLOR (RED)
B"00100000" | BACKGROUND-COLOR (GREEN)
B"00010000" | BACKGROUND-COLOR (BLUE)
B"00001000" | FOREGROUND HIGHLIGHT
B"00000100" | FOREGROUND-COLOR (RED)
B"00000010" | FOREGROUND-COLOR (GREEN)
B"00000001" | FOREGROUND-COLOR (BLUE)

UNIX platforms:

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
Parent topic: Alphabetical List of Library 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
Parent topic: Alphabetical List of Library Routines


PC_WIN_INIT

Returns the Windows startup values.

Note: This topic applies to Windows environments only.

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
Parent topic: Alphabetical List of Library 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 14
    Reads 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:

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:

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 14

Reads 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 14

On Exit:

parameter | Each byte represents one of the switch letters and each bit in a byte is the state of 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.
result | Set to zero if the call was successful, nonzero otherwise.
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_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 the debugger (Windows) or Animator (UNIX).
  • 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_RECORD_LOCK
    Releases a record lock on a file.
  • 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_MOUSE_MASK
    Returns the mouse event mask.
  • CBL_GET_MOUSE_POSITION
    Returns the screen position of the mouse pointer.
  • CBL_GET_MOUSE_STATUS
    Finds out the number of events in the queue.
  • 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_HIDE_MOUSE
    Makes the mouse pointer invisible.
  • CBL_IMP
    Does a logical IMPLIES between the bits of two data items.
  • CBL_INIT_MOUSE
    Initializes mouse support. This routine must be called before other mouse routines can be called.
  • 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_MOUSE_EVENT
    Reads the mouse event queue and returns information about an event.
  • 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_SET_MOUSE_MASK
    Sets the mouse event mask.
  • CBL_SHOW_MOUSE
    Makes the mouse pointer visible.
  • 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_TERM_MOUSE
    Terminates mouse support, releasing internal resources.
  • 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.
  • PC_FIND_DRIVES
    Returns all valid drives on a PC.
  • PC_ISAPI_GET_EXT
    Returns the ISAPI extension block.
  • PC_PRINT_FILE
    Prints the contents of the specified file, optionally displaying printer control, font, and progress indicator dialog boxes, before commencing the print.
  • PC_PRINTER_CLOSE
    Closes a previously opened printer channel.
  • PC_PRINTER_CONTROL
    Sends a print command to a printer.
  • PC_PRINTER_DEFAULT_FONT
    Sets the default font for all PC_PRINTER_ routines.
  • PC_PRINTER_DEFAULT_NAME
    Sets the default printer for all PC_PRINTER_ routines.
  • PC_PRINTER_DEFAULT_PROPERTIES
    Sets one or more of the properties of the default printer for all PC_PRINTER_ routines.
  • PC_PRINTER_DRAW_RECTANGLE
    Draws an outline or filled rectangle at position start-x, start-y to end-x, end-y.
  • PC_PRINTER_ENUM_CLOSE
    Ends the process of enumerating printers.
  • PC_PRINTER_ENUM_NEXT
    Gets the name of the next enumerated printer.
  • PC_PRINTER_ENUM_START
    Starts the process of enumerating printers.
  • PC_PRINTER_FREE_BMP
    Frees a bitmap from memory, releasing its image and palette back to the operating system.
  • PC_PRINTER_GET_BMP_INFO
    Retrieves the width and height of a loaded bitmap.
  • PC_PRINTER_GET_COLOR
    Gets the color on the printer.
  • PC_PRINTER_GET_FONT
    Gets the font on the printer.
  • PC_PRINTER_INFO
    Returns a native device context handle, and other information that can be used to enhance the printing of a document by calling native graphics functions directly.
  • PC_PRINTER_LINE_FROM_TO
    Draws a line from start-x,start-y to end-x,end-y.
  • PC_PRINTER_LOAD_BMP
    Loads a bitmap or other supported file format into memory ready for the PC_PRINTER_WRITE_BMP function.
  • PC_PRINTER_OPEN
    Opens a printer channel, giving it a document title, and optionally displaying printer control, font, and progress indicator dialog boxes
  • PC_PRINTER_REDIRECTION_PROC
    Registers a user function that is called when a program uses OPEN OUTPUT syntax and the ASSIGN TO PRINTER clause.
  • PC_PRINTER_SET_BACKGROUND_MIX_MODE
    Sets background printing mode.
  • PC_PRINTER_SET_COLOR
    Sets the color on the printer.
  • PC_PRINTER_SET_DEFAULT
    Sets a process-wide default printer before a printer is opened.
  • PC_PRINTER_SET_FONT
    Sets the current font for the printer.
  • PC_PRINTER_SET_PEN
    Set the width, style and colour for lines and rectangles when drawn using a printer.
  • PC_PRINTER_SET_POSITION
    Move the logical printer position ready for the next PC_PRINTER_WRITE.
  • PC_PRINTER_WRITE
    Writes a text string to the printer.
  • PC_PRINTER_WRITE_BMP
    Write a loaded bitmap to a printer at a specified position with a given size.
  • PC_READ_DRIVE
    Returns the current default drive letter.
  • PC_SET_DRIVE
    Sets the default drive letter.
  • PC_WIN_CHAR_TO_OEM
    Translates a buffer of ANSI characters into the OEM character set.
  • PC_WIN_HANDLE
    Returns the handle of the window used for screen I/O.
  • PC_WIN_INIT
    Returns the Windows startup values.
  • 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.
  • 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 14
    Reads 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
  • Maximum Number of Methods in a Class
  • Maximum Number of Problem Error Markers
  • 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 255 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 (applies to UNIX environments only) | 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


Maximum Number of Methods in a Class

The maximum number of methods allowed in a class is limited to 999.

This limit does not apply to managed (.NET) programs.

Parent topic: Restrictions, Compiler Limits, and System Limits


Maximum Number of Problem Error Markers

Specifying a program level limit

You can specify a program level limit for the number of error markers processed before the build process is stopped. This is specified in the COBOL build configurations. To modify the program level limit:

  1. Right-click your project in the Application Explorer view and select Properties.
  2. Click Micro Focus > Build Configurations > COBOL.
  3. Expand Override project COBOL settings.
  4. Check Enable configuration specific settings.
  5. In the Stop after field, type the new program level limit for problem error markers.
Note: The default program-level limit for the number of problem error markers is 100.

Specifying a project level limit

You can specify a limit to the number of problem error markers displayed as part of a build. By default, this is limited to 10,000. The maximum number of problem error markers displayed during a build is specified by the build.errors.limit system property. You can modify this property by editing it in the eclipse.ini file. This file can be found in the C:\Users\Public\Micro Focus\Enterprise Developer\eclipse (Windows) or /opt/microfocus/EnterpriseDeveloper/eclipse/eclipse (UNIX) folder. For example, add the following to the eclipse.ini file to limit the problem error markers to 1000.

-Dbuild.errors.limit=1000

Set the property value to 0 to specify that there is no project limit to the number of problem error markers displayed for a build.

Note: When the maximum limit of project problem error markers is reached, a new build problem error marker is created explaining that there are too many build errors. Building a project without limiting the number of problem error markers can result in large numbers of problem error markers. Too many error markers can cause an internal error due to too much heap space being consumed. Micro Focus recommends that you limit your problem error markers to 10,000.
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
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
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
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 Enterprise 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

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


Mainframe Reference

  • Assembler Reference
  • CICS Support Commands
    Lists the CICS Support commands
  • Micro Focus FTP Utility MFFTP
    The MFFTP Utility allows FTP batch processing from JCL on a mainframe.
  • Micro Focus BMS Painter
  • Open PL/I Reference
  • CICSECM Compiler Directive Options
  • Working with Mainframe Files
Parent topic: General Reference


Assembler Reference

The implementation of Assembler provided by Enterprise Developer is as defined in the following IBM manuals, with certain exceptions and differences:

High Level Assembler for MVS, VM and VSE Language Reference SC26-4940-03

ESA/390 Principles of Operation SA22-7201-07

z/Architecture Principles of Operation SA22-7832-00

  • Assembler File Types
    Lists the file types you can use with Assembler applications, and a description of each.
  • Assembler Input and Output Directories
    Specify input and output directories for Assembler macros, copybooks and other files using environment variables, a configuration file or both.
  • Assembler Command Line Reference
  • Assembler Compiler Directives
  • Assembler Linker Directives
  • Assembler Link Files
    Describes the format and usage of .lin files containing linker commands.
  • Assembler Link File Commands
  • Macros and SVCs
  • Assembler Pseudo Operations
  • Configuring an Enterprise Server for Assembler Support
    Describes the configuration requirements for an enterprise server instance that runs assembler applications using JCL and CICS.
Parent topic: Mainframe Reference


Assembler File Types

Lists the file types you can use with Assembler applications, and a description of each.
The most commonly used assembler file type is .mlc, which represents an Assembler source file.You can also use the following file types:
  • .asm – Assembler source file (same as .mlc)
  • .mac – Assembler macro file
  • .lin – Linker input file (refer to “Assembler Link File Commands” section)
  • .cap – CICS Assembler program (Assembler program that contains EXEC CICS statements)
  • .obj – Assembler object modules produced by Assembler
  • .390 – Executable assembler modules
  • .MOD – CICS table files created by the assembler linker
  • .lst – Linker list file
  • .prn – Assembler list file
Parent topic: Assembler Reference


Assembler Input and Output Directories

Important: Enclose path names in double quotes if the path contains one or more spaces.

MF370CTL.CFG Configuration File

We supply a configuration file, MF370CTL.CFG you can use to customize your input and output directories by editing the values for a series of SYS variables. This file is located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin directory.

The assembler looks for MF370CTL.CFG in the current working directory before searching for it in the default location.

All output variables take a single directory specification.

Output Variables | Description
SYSIN | Macro input .mlc files
SYSLIST | Assemble and Link listing files .mat, .prn, and .lst
SYSWORK | Assemble, Link and debugger 370 work files .bal, .idf, and .idx
SYSPUNCH | Assemble output .pch files for PUNCH statements
SYSMPC | Assemble input precompiled macros .mpc
SYSLIN | Link input .lin files and Assemble output .obj files
SYSLMOD | Link output load-member .390 files

The SYSLIB and OBJ370 input variables take multiple directories, separated by semicolons, allowing you to specify several search directories for macros and copybooks. The SYSPARM input variable takes a single parameter.

Input Variables | Description
SYSLIB | Assemble input macro and copy files .mac and .cpy
OBJ370 | Link input .obj files (must contain SYSLIN specification)
SYSPARM | Macro input SYSPARM value. The default is MF370.

For example, to specify an output directory:

SET SYSLIB=.;C:\SYSLIB;C:\USERLIB1;"C:\USERLIB2 MFASM TEST.MLC"

This example instructs the assembler to search the listed directories, in order, for macro and copybooks as they are encountered during assembly. By setting SYSLMOD, output files such as .390 files can be directed to specific output directories.

Environment Variables

You can override any variable specified in the MF370CTL.CFG file by setting it directly in the environment, using the same name as found in the MF370CTL.CFG file.

Note: The Assembler support provided with Enterprise Developer is essentially the same support as found in the Micro Focus Mainframe Express product.
Parent topic: Assembler Reference


Assembler Command Line Reference

You can use the MFASM command, or a series of run commands to assemble and link executable modules and data tables for Assembler applications.

All commands must be executed from an Enterprise Developer command prompt, 32-bit.

  • MFASM
    Use the MFASM command to assemble and link Assembler applications in one step, producing executable subroutines, and debugging modules.
  • mm370asm
    Assembles an Assembler source (.mlc) file.
  • mf370lnk
    Links an object (.obj) file into an executable file (.390).
  • mf370chk
    Assembles an Assembler source (.mlc) file and links it to an executable (.390) file.
Parent topic: Assembler Reference


mm370asm

Assembles an Assembler source (.mlc) file.

Syntax:

run mm370asm filename[.mlc] [compDirective[ ...]][;]

Parameters:

filename
The name of an assembler source file.
compDirective
One or more Assembler compiler directives, separated by a space. See Assembler Compiler Directives for more information.

Comments:

Command line compatibility with the assembler component of the Micro Focus Mainframe Express product is maintained. Batch files used with Mainframe Express should work correctly under Enterprise Developer. In particular the MF370CHK (Micro Focus 370 Checker) module along with the MM370ASM (standalone assembler) and the MF370LNK (standalone assembler linker) are present. So command lines used under Mainframe Express to assemble and link assembler modules do work

Examples:

Mainframe Express Command Line

RUN MF370CHK TEST.MLC OMF(390) NOANIM NOLIST;

Assemble and Link Modules in Separate Commands

RUN MM370ASM TEST.MLC NOANIM; RUN MF370LNK TEST.OBJ NOANIM NOLIST ;
Parent topic: Assembler Command Line Reference


mf370lnk

Links an object (.obj) file into an executable file (.390).

Syntax:

run mm370lnk filename[.obj] [linkerDirective[ ...]] | linkfile.LIN][;]

Parameters:

filename
The name of an object file.
linkerDirective
One or more linker directives, separated by a space. See Assembler Linker Directives for more information.
linkfile
The name of a link file containing linker directives. See Assembler Link Files for more information.
Parent topic: Assembler Command Line Reference


mf370chk

Assembles an Assembler source (.mlc) file and links it to an executable (.390) file.

Syntax:

run mf370chk filename[.mlc] compDirective[ ...]][{linkerDirective ... | linkfile.LIN}][;]

Parameters:

filename
The name of an assembler source file.
compDirective
One or more Assembler compiler directives, separated by a space. See Assembler Compiler Directives for more information.
linkerDirective
One or more linker directives, separated by a space. See Assembler Linker Directives for more information.
linkfile
The name of a link file containing linker directives. See Assembler Link Files for more information.
Parent topic: Assembler Command Line Reference


Assembler Compiler Directives

You can specify Assembler compiler directives on the command line when building from the command line, or in your project properties when building from the IDE.

Note: Take care when setting compiler directives in the Additional Directives field on the Assembler tab of your project properties Assembler page as these could conflict with a default setting.
  • AAT
    Generate Assembler Analysis Tool (AAT) outputs; used to determine required macro and copybook files, all external references to called modules, all SVCs, MNOTEs generated, etc.
  • ALLOW
    Suppress error and warning messages.
  • AMODE
    Set the memory address type.
  • ANIM
    Generate .idf and .idx files required to debug an Assembler module during execution.
  • ASCII
    Defines all DC C'...' variables using ASCII instead of EBCDIC characters.
  • ASM
    Perform a complete compilation, that is, both pre-process macros and assemble the resulting .bal file, producing an .obj file.
  • BAL
    Create a source file (.bal) in the load library; this file contains the output from the macro pre-process stage of compilation.
  • BALLIST
    Create a listing file of the .bal file that shows each macro call and the relative byte address of each expanded macro instruction.
  • BALWTO
    Create a listing file of the .bal file that shows each macro call and the relative byte address of each expanded macro instruction, and display each line on the Output Window. Also reduces the output buffer for the .mop file to 1,000 bytes to ensure that the .mop file and the current screen between them supply a complete record of the pre-process phase in the event of a failure.
  • CACHE
    Cache all access to the virtual files used during compilation. The cache is a pool of 4 kilobyte (Kb) buffers with least recently used replacement.
  • CALL
    Attempt to automatically resolve any remaining external references by repeatedly searching the load library for .obj files matching external names.
  • CICS
    Enables the use of the EXEC CICS preprocessor to convert the CICS commands you supply into calls to the CICS command-level API.
  • COMPATM
    Force all macro parameters not in quotes to be upper case for compatibility with the previous Micro Focus Assembler product, MF370.
  • COMPATS
    Treat all sublists in macro parameters as character strings for compatibility with the previous Micro Focus Assembler product, MF370.
  • EID2
    Generate two-byte external symbol ids in object code. If you specify NOEID2, one-byte external symbol ids are generated; this format is compatible with versions of the previous Micro Focus Assembler product, MF370, before 4.0.06.
  • EPILOG
    Insert DFHEIRET macro in the EXEC CICS code.
  • ESD
    Include external symbol directory (ESD) records in .370 files.
  • LINK
    Create a .390 file when compilation is complete, by linking in all other modules called by the main module.
  • LIST
    Create a compilation listing in filename.prn in the output library.
  • LISTCALL
    Include macro call statements with parameters in the .bal file.
  • LISTPARM
    Create a trace of all macro parameters and their values (including all nested macro calls).
  • MACLIST
    Create a macro listing in filename.prn in the output library.
  • MCALLS
    Execute called macros during macro pre-process stage.
  • MOPLIST
    Create a detailed macro execution trace file showing each line of code executed with the name of the macro, the relative byte address, the opcode, the current variable name or macro sequence symbol name, and the current seta, setb, and setc values. The listing file has the extension .mop.
  • MOPWTO
    In addition to the functionality of MOPLIST, MOPWTO displays each line in the Output Window. It also reduces the output buffer for the .mop file to 1,000 bytes to ensure that the .mop file and the current screen between them supply a complete record of the pre-process phase in the event of a failure.
  • MPC
    Determines the level of macro processing.
  • MPCGEN
    Recreate new .mpc files containing compiled macro code replacing previous versions if any.
  • MPCLIST
    List generated macro code after each macro source line during macro pre-process phase.
  • OBJ370
    Generate mainframe-compatible sequential fixed-block object code file, filename.370, in the load library.
  • OBJECT
    Generate object code in either filename.obj (default) or filename.370 format depending on current OBJ370 setting.
  • OMF
    Specifies the type of output - load module or CICS data table.
  • OPT
    Make an extra pass of macro object code to resolve references to addresses.
  • OLDCICS
    Specify the level of the CICS preprocessor to use.
  • PLISTUB
    Generate a PLI stub program in the source directory for each entry point in the Assembler module being compiled.
  • PROLOG
    Insert DFHEIENT, DFHEIEND, and DFHEISTG macros in the EXEC CICS code. You can set this directive only if you have set the CICS directive.
  • RENT
    Mark module as re-entrant; this prevents reloading of the module each time it is called.
  • REUS
    Mark load module as serially reusable; this prevents reloading of the module each time it is called.
  • RLD
    Generate relocation records for relocatable address constants in the object code file filename.obj.
  • RMODE
    Specify a residence mode for the load module.
  • STATIC
    Generate code from macro statements with no symbolic parameters without parsing them for parameter substitution.
  • SYSPARM
    Define string to be substituted in macros for the variable symbol &SYSPARM.
  • TOTALS
    Write totals to syslist.wto showing internal statistics on macro compiles, symbol table lookups, external symbols, literals, physical file input/output, virtual file input/output, memory usage, etc.
  • TRACE
    Generate trace of events during compilation in syslist.wto
  • UFUNC
    Specify how to handle unsupported CICS functions.
  • UOPT
    Specify how to handle unsupported CICS options.
  • VSECOMP
    Set a macro variable that allows the Enterprise Developer Assembler implementation to correctly interpret DOS/VSE macro operands where these differ from their MVS counterparts.
  • XMAC
    Include a cross-reference listing in filename.prn for all macros and copybooks showing the relative line numbers of the generated statements.
  • XREF
    Include a cross-reference listing in filename.prn for all labels and literals showing the relative line numbers of the generated statements.
  • XSVC
    Include an entry for each SVC in the module in filename.prn in a cross-reference table that shows the relative line numbers of all the statements that reference that SVC.
Parent topic: Assembler Reference


AAT

Generate Assembler Analysis Tool (AAT) outputs; used to determine required macro and copybook files, all external references to called modules, all SVCs, MNOTEs generated, etc.

Syntax:

[NO]AAT

Properties:

Default: NOAAT

Build Settings:

Check Create Assembler Analysis Tool (AAT) information on the Assembler tab of your project properties Assembler page.

Comments:

The AAT directive creates the following output files in the load library:
  • filename.aat - Contains summary messages about files, SVCs, etc.
  • filename.aas - Contains a table of all the symbols defined in the module showing for each symbol its name, type, address, length and the file and line number of the definition; there are also entries for each SVC and MNOTE in the module.
  • filename.aaf - Contains the file number and fully qualified filename.
  • filename.aax - Contains a table showing the file and relative number of each reference to each symbol, macro, copybook, SVC and MNOTE in the module.

You can view these four files in any text editor.

Parent topic: Assembler Compiler Directives


ALLOW

Suppress error and warning messages.

Syntax:

[NO]ALLOW

Properties:

Default: ALLOW

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

The purpose of the ALLOW option is to provide compatibility with the mainframe, which does not generate error or warning messages for these cases. You may choose to use NOALLOW to improve the quality of your code. One particular benefit is that you can identify all undefined macro labels at macro compile time rather than only when a branch to a label is attempted at execution time.

Enables the following compilation behavior:

  • Allow duplicate variable definitions within macros and ignore all but the first one (that is, allow definitions in a macro that duplicate earlier definitions; whether the earlier definition is in the same macro or is a parameter it overrides the later definition).
  • Allow branches to undefined labels in AIF instructions. (Such branches cause errors during execution). Allow fullword and halfword definitions to have values enclosed in parentheses as well as single quotes; for example you can code F(D0) or F'D0'
  • Allow the instruction DROP for registers with no current USING.
  • Suppress string sublist function and return entire string; for example, &T SETC '(ABC)'(1) returns (ABC), not ABC.
  • Allow literal pool references across CSECT boundaries. This works on the PC, but on the mainframe the Assembler Linker may replace or reorder CSECTS, thereby rendering some literal pool references invalid. Under these circumstances specify NOALLOW.
  • Allow conditional assembly macro references to the length (L' operator) of symbols defined on EQU statements with no third operand that explicitly defines the length; during the macro pre-process stage the length defaults to one, but during the assembly phase it is set to its actual value, and the code generated is incorrect.
  • Issue no warning about the presence of blank lines.
  • Issue no warning about the presence of dead code, that is code that can never be executed.
  • Issue no warning about a POP instruction without a preceding PUSH.

When NOALLOW is specified, error or warning messages are issued for the above.

Parent topic: Assembler Compiler Directives


AMODE

Set the memory address type.

Syntax:

AMODE({24|31})

Parameters:

24
Use three-byte (24-bit addresses), compatible with memory below the line on the mainframe.
31
Use 31-bit addresses, compatible with memory above and below the line on the mainframe.

Properties:

Default: AMODE(31)

Build Settings:

Choose an AMODE setting from the Addressing mode list on the Assembler tab of your project properties Assembler page.

Comments:

All COBOL programs passing parameters to Assembler subroutines must be compiled with the AMODE(24) or AMODE(31) compile option themselves or a SOC5 (addressing error) abend occurs at call time. Unless they are specifically coded to accept ASCII data, Assembler subroutines expect all alphanumeric data to be EBCDIC, so the calling COBOL module should be compiled with the CHARSET(EBCDIC) option to override the default of CHARSET(ASCII).

Parent topic: Assembler Compiler Directives


ANIM

Generate .idf and .idx files required to debug an Assembler module during execution.

Syntax:

[NO]ANIM

Properties:

Default: ANIM

Build Settings:

Check Create debug information on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives
Parent topic: Assembler Linker Directives


ASCII

Defines all DC C'...' variables using ASCII instead of EBCDIC characters.

Syntax:

[NO]ASCII

Properties:

Default: NOASCII

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

  • The ASCII directive affects C'...' items only. For example, EBCDIC characters defined using DC X'F1' are not affected.
  • Use of the ASCII directive could cause application logic to fail if the application assumes character data is in EBCDIC collating sequence order.
Parent topic: Assembler Compiler Directives


ASM

Perform a complete compilation, that is, both pre-process macros and assemble the resulting .bal file, producing an .obj file.

Syntax:

[NO]ASM

Properties:

Default: ASM

Dependencies:

If you specify NOASM, directives BAL, NOOBJECT and NOLIST are set automatically.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

NOASM only performs the macro pre-process stage, and it passes undefined opcodes and macros through to the .bal file. Setting NOASM is equivalent to just running the macro pre-process stage of the previous Micro Focus Assembler product, MF370. NOASM is particularly useful when you want to preprocess BMS macros to produce a file than can be input to the CICS BMS screen painter. See BMS Screen Painter for more information.

Parent topic: Assembler Compiler Directives


BAL

Create a source file (.bal) in the load library; this file contains the output from the macro pre-process stage of compilation.

Syntax:

[NO]BAL

Properties:

Default: NOBAL

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

The .bal file created is very similar but not identical to the .bal file created by the previous Micro Focus Assembler product, MF370. The files are functionally equivalent but the formatting is not identical. If you specify the LISTCALL directive, each macro call statement is included in the .bal file for cross reference purposes.

Parent topic: Assembler Compiler Directives


BALLIST

Create a listing file of the .bal file that shows each macro call and the relative byte address of each expanded macro instruction.

Syntax:

[NO]BALLIST

Properties:

Default: NOBALLIST

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

The listing file has the extension .mop. If XFLN is on, the listing also includes the relative line number of each expanded macro instruction.

This listing of the .bal file is sometimes useful for debugging large macros since it shows parameters passed to each macro and where each call was issued from. You can obtain a more detailed listing by specifying the MOPLIST directive.

Parent topic: Assembler Compiler Directives


BALWTO

Create a listing file of the .bal file that shows each macro call and the relative byte address of each expanded macro instruction, and display each line on the Output Window. Also reduces the output buffer for the .mop file to 1,000 bytes to ensure that the .mop file and the current screen between them supply a complete record of the pre-process phase in the event of a failure.

Syntax:

[NO]BALLIST

Properties:

Default: NOBALWTO

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


CACHE

Cache all access to the virtual files used during compilation. The cache is a pool of 4 kilobyte (Kb) buffers with least recently used replacement.

Syntax:

[NO]CACHE

Properties:

Default: NOCACHE

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

A new buffer is allocated for each request for file access until the pool reaches 64Kb (that is, 16 buffers). From this point, if the hit rate drops below 98%, where hit rate is the percentage of requests for data that is already in existing buffers, a request for data that is not already in existing buffers results in the allocation of a another new buffer, until a maximum of 1 megabyte (Mb) is in use. If the hit rate stays at or above 98%, a request for data that is not already in existing buffers results in the reuse of the least recently used buffer. The cache includes macro code, local and global macro variables, symbols, literals, working .bal file, working token file, and working relocation record file. You can save up to 1Mb of main memory by specifying NOCACHE, but your compilations can take longer.

Parent topic: Assembler Compiler Directives


CALL

Attempt to automatically resolve any remaining external references by repeatedly searching the load library for .obj files matching external names.

Syntax:

{CALL | NCAL}

Properties:

Default: CALL

Build Settings:

Check Resolve external calls at link time on the Assembler tab of your project properties Assembler page.

Comments:

If the loading of these modules in turn adds additional external references, the process is repeated until there are no remaining unresolved external references or until the last pass fails to resolve any additional external references.

Error messages are issued for any unresolved external references.

Parent topic: Assembler Compiler Directives


CICS

Enables the use of the EXEC CICS preprocessor to convert the CICS commands you supply into calls to the CICS command-level API.

Syntax:

[NO]CICS

Properties:

Default: NOCICS

Build Settings:

Check EXEC CICS on the Assembler tab of your project properties Assembler page.

Comments:

If the compiler finds an EXEC CICS statement in the source, CICS is automatically specified.

See also EPILOG and PROLOG.

Parent topic: Assembler Compiler Directives


COMPATM

Force all macro parameters not in quotes to be upper case for compatibility with the previous Micro Focus Assembler product, MF370.

Syntax:

[NO]COMPATM

Properties:

Default: NOCOMPATM

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


COMPATS

Treat all sublists in macro parameters as character strings for compatibility with the previous Micro Focus Assembler product, MF370.

Syntax:

[NO]COMPATS

Properties:

Default: NOCOMPATS

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


EID2

Generate two-byte external symbol ids in object code. If you specify NOEID2, one-byte external symbol ids are generated; this format is compatible with versions of the previous Micro Focus Assembler product, MF370, before 4.0.06.

Syntax:

[NO]EID2

Properties:

Default: EID2

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


EPILOG

Insert DFHEIRET macro in the EXEC CICS code.

Syntax:

[NO]EPILOG

Properties:

Default: NOEPILOG

Dependencies:

To use EPILOG, you must also specify CICS.

Build Settings:

Check EXEC CICS on the Assembler tab of your project properties Assembler page; then check Insert standard epilog macro on the EXEC CICS Options dialog box.

Comments:

If the compiler finds an EXEC CICS statement in the source, CICS is automatically specified.

Parent topic: Assembler Compiler Directives


ESD

Include external symbol directory (ESD) records in .370 files.

Syntax:

[NO]ESD

Properties:

Default: ESD

Dependencies:

You must also set the OBJ370 directive.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


LINK

Create a .390 file when compilation is complete, by linking in all other modules called by the main module.

Syntax:

[NO]LINK

Properties:

Default: LINK

Dependencies:

If the CALL directive is also specified, an attempt is made to resolve any remaining external references.

Build Settings:

Check Automatically link moduleon the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


LIST

Create a compilation listing in filename.prn in the output library.

Syntax:

[NO]LIST

Properties:

Default: NOLIST

Build Settings:

Check Generate listing file on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


LISTCALL

Include macro call statements with parameters in the .bal file.

Syntax:

[NO]LISTCALL

Properties:

Default: NOLISTCALL

Dependencies:

You must also set the BAL directive.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

Macro calls are always shown on filename.prn unless suppressed by PRINT NOGEN.

Parent topic: Assembler Compiler Directives


LISTPARM

Create a trace of all macro parameters and their values (including all nested macro calls).

Syntax:

[NO]LISTPARM

Properties:

Default: NOLISTPARM

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

This trace is useful for verifying which parameter value was passed to which parameter in applications where there are many parameters. The trace is put in syslist.wto, in the project folder.

Parent topic: Assembler Compiler Directives


MACLIST

Create a macro listing in filename.prn in the output library.

Syntax:

[NO]MACLIST

Properties:

Default: NOMACLIST

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

This listing shows macro source lines with their relative byte addresses. Dead code in macros is listed with type code "DEAD" so you can scan for it.

Parent topic: Assembler Compiler Directives


MCALLS

Execute called macros during macro pre-process stage.

Syntax:

[NO]MCALLS

Properties:

Default: MCALLS

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

If you specify NOMCALLS, the macros are not executed, just expanded. You can use this option in conjunction with MPC or MPCGEN to compile macros without expanding them. To create .mpc files for all the macros in a folder just copy the folder list into a .mlc file and compile it using options MPCGEN and NOMCALLS.

Parent topic: Assembler Compiler Directives


MOPLIST

Create a detailed macro execution trace file showing each line of code executed with the name of the macro, the relative byte address, the opcode, the current variable name or macro sequence symbol name, and the current seta, setb, and setc values. The listing file has the extension .mop.

Syntax:

[NO]MOPLIST

Properties:

Default: NOMOPLIST

Dependencies:

You must also set the BALLIST directive.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

This listing is extremely useful for debugging difficult macro execution errors. However, the output can be very large (around 50 MB); We recommend that you use this directive with some caution, preferably on reduced test cases which contain the problem.

Parent topic: Assembler Compiler Directives


MOPWTO

In addition to the functionality of MOPLIST, MOPWTO displays each line in the Output Window. It also reduces the output buffer for the .mop file to 1,000 bytes to ensure that the .mop file and the current screen between them supply a complete record of the pre-process phase in the event of a failure.

Syntax:

[NO]MOPWTO

Properties:

Default: NOMOPWTO

Dependencies:

You must also set the BALLIST directive.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


MPC

Determines the level of macro processing.

Syntax:

[NO]MPC

Properties:

Default: NOMPC

Build Settings:

Check Use pre-assembled macros on the Assembler tab of your project properties Assembler page.

Comments:

If a valid pre-processed macro file (.mpc) is found, it is used as input to the assembly phase, and the macro pre-process phase is bypassed. If a valid .mpc file is not found or one is found but it predates the corresponding macro source file, the macro from source is compiled and saved as an .mpc file for future use.

Using .mpc files can shorten compilation time by up to 50% for large assemblies that use many complex macros.

This directive is not available on the mainframe.

The Assembler compiler does not check whether macro copybooks have changed since the .mpc file was created, so if you change macro copybooks, you should delete all .mpc files or use the MPCGEN directive to force regeneration.

Setting the MPC directive also has the effect of removing the file and relative line number information from the compilation error messages displayed and from the reports produced by setting the BALLIST, MACLIST, XMAC and XREF directives.

Parent topic: Assembler Compiler Directives


MPCGEN

Recreate new .mpc files containing compiled macro code replacing previous versions if any.

Syntax:

[NO]MPCGEN

Properties:

Default: NOMPCGEN

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

You can use MPCGEN in conjunction with MCALLS to compile entire macro library in one assembly.

Parent topic: Assembler Compiler Directives


MPCLIST

List generated macro code after each macro source line during macro pre-process phase.

Syntax:

[NO]MPCLIST

Properties:

Default: NOMPCLIST

Dependencies:

When you specify MPCLIST, MACLIST is set automatically.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

Both MACLIST and MPCLIST show the relative byte address of each macro statement. This is unique and is the easiest way to distinguish between possible multiple instances of macro copybook code generated within a single macro.

If there is an error during the macro pre-process stage the relative byte address of the failing statement is shown to help you pinpoint error location and the point from which the macro was called.

Parent topic: Assembler Compiler Directives


OBJ370

Generate mainframe-compatible sequential fixed-block object code file, filename.370, in the load library.

Syntax:

[NO]OBJ370

Properties:

Default: NOOBJ370

Dependencies:

When you specify NOOBJECT, the OBJ370 directive is ignored and no object code output is generated.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

If default NOOJB370 is set, then Assembler generates a compressed binary object file called filename.obj in the load library.

Parent topic: Assembler Compiler Directives


OBJECT

Generate object code in either filename.obj (default) or filename.370 format depending on current OBJ370 setting.

Syntax:

[NO]OBJECT

Properties:

Default: OBJECT

Dependencies:

When you specify NOOBJECT, the OBJ370 directive is ignored and no object code output is generated.

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


OMF

Specifies the type of output - load module or CICS data table.

Syntax:

OMF({390|MOD})

Parameters:

390
Executable format in filename.390.
MOD
Non-executable table format in filename.MOD. The file contains assembled object code with no header and no relocation data. This option is often used to create CICS tables.

Properties:

Default: OMF(390)

Build Settings:

Choose an OMF setting from the Linker output list on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


OPT

Make an extra pass of macro object code to resolve references to addresses.

Syntax:

[NO]OPT

Properties:

Default: NOOPT

Build Settings:

Check Create optimized code on the Assembler tab of your project properties Assembler page.

Comments:

If the compilation of your program involves the execution of many macros, you can reduce the total compilation time by specifying this directive.

When OPT is on, the MOPLIST and MOPWTO macro trace output does not include AGO labels or local variable symbol names since the extra pass eliminates them.

Parent topic: Assembler Compiler Directives


OLDCICS

Specify the level of the CICS preprocessor to use.

Syntax:

[NO]OLDCICS

Properties:

Default: NOOLDCICS

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

Use NOOLDCICS if you want to use the version that is compatible with IBM's CICS Transaction Server 1.3. Use OLDCICS if you want to use the previous version.

NOOLDCICS generates more efficient run-time code.

You can run programs compiled with OLDCICS with programs compiled with NOOLDCICS.

Parent topic: Assembler Compiler Directives


PLISTUB

Generate a PLI stub program in the source directory for each entry point in the Assembler module being compiled.

Syntax:

[NO]PLISTUB

Properties:

Default: NOPLISTUB

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

The name of the stub program is #nnnnnnn where nnnnnnn is the entry point name.

Use this directive where you have a PL/I application that issues calls to Assembler modules without specifying the language option ASM You must add the stub programs to the PL/I project and compile them along with the PL/I program that calls them.

Parent topic: Assembler Compiler Directives


PROLOG

Insert DFHEIENT, DFHEIEND, and DFHEISTG macros in the EXEC CICS code. You can set this directive only if you have set the CICS directive.

Syntax:

[NO]PROLOG

Properties:

Default: NOPROLOG

Build Settings:

Check EXEC CICS and Options on the Assembler tab of your project properties Assembler page; then check Insert standard prolog macros on the EXEC CICS Options dialog box.

Comments:

If the compiler finds an EXEC CICS statement in the source, CICS is automatically specified.

Parent topic: Assembler Compiler Directives


RENT

Mark module as re-entrant; this prevents reloading of the module each time it is called.

Syntax:

[NO]RENT

Properties:

Default: RENT

Build Settings:

Check Mark module as reentrant on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


REUS

Mark load module as serially reusable; this prevents reloading of the module each time it is called.

Syntax:

[NO]REUS

Properties:

Default: REUS

Build Settings:

Check Mark load module as serially reusable on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


RLD

Generate relocation records for relocatable address constants in the object code file filename.obj.

Syntax:

[NO]RLD

Properties:

Default: RLD

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


RMODE

Specify a residence mode for the load module.

Syntax:

RMODE({24|31})

Parameters:

24
Load the module into memory below the line, for compatibility with mainframe 24-bit (3-byte) addresses.
31
Load the module into memory either above or below the line, for compatibility with mainframe 31-bit (4-byte) addresses.

Properties:

Default: RMODE(31)

Build Settings:

Choose an RMODE setting from the Residency mode list on the Assembler tab of your project properties Assembler page.

Comments:

If the link process run by the Compiler detects any 24-bit address fields in the load module, it issues a warning message and automatically changes the directive to RMODE(24), while leaving the AMODE setting unchanged.

Parent topic: Assembler Compiler Directives


STATIC

Generate code from macro statements with no symbolic parameters without parsing them for parameter substitution.

Syntax:

[NO]STATIC

Properties:

Default: STATIC

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

If you specify NOSTATIC, all macro statements are parsed for parameter substitution. This directive only affects speed of compilation, and the output is identical.

Parent topic: Assembler Compiler Directives


SYSPARM

Define string to be substituted in macros for the variable symbol &SYSPARM.

Syntax:

SYSPARM(value)

Parameters:

value
A string to substitute for the &SYSPARM variable.

Properties:

Default: SYSPARM() (null string)

Build Settings:

Type a value into the $SYSPARM substitution value field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


TOTALS

Write totals to syslist.wto showing internal statistics on macro compiles, symbol table lookups, external symbols, literals, physical file input/output, virtual file input/output, memory usage, etc.

Syntax:

[NO]TOTALS

Properties:

Default: NOTOTALS

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

The syslist.wto file is created in the project folder.

Parent topic: Assembler Compiler Directives


TRACE

Generate trace of events during compilation in syslist.wto

Syntax:

Format 1:

TRACE{5|7|8|9|#nnnnn}

Format 2:

NOTRACE

Parameters:

5
Each macro line is traced.
7
All virtual and physical input/output is traced.
8
All tokens are traced.
9
Program calls and temporary memory usage are traced.
#nnnnn
A level 9 trace for just statement nnnnn is generated.

Properties:

Default: NOTRACE

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

The traces are cumulative, and so can become voluminous.

Parent topic: Assembler Compiler Directives


UFUNC

Specify how to handle unsupported CICS functions.

Syntax:

UFUNC({A|N|E})

Parameters:

A
Issue a warning when the program is compiled and an abend at run time
N
Issue a warning when the program is compiled and treat the function as a NO-OP. User response fields are updated only if you set directive NOOLDCICS.
E
Issue an error when the program is compiled.

Properties:

Default: UFUNC(E)

Build Settings:

Check EXEC CICS and Options on the Assembler tab of your project properties Assembler page; then choose the type of handling you require from the Unsupported function handling list on the EXEC CICS Options dialog box.

Parent topic: Assembler Compiler Directives


UOPT

Specify how to handle unsupported CICS options.

Syntax:

UOPT({A|N|I|E})

Parameters:

A
Issue a warning when the program is compiled and an abend at run time
N
Issue a warning when the program is compiled and treat the function as a NO-OP. User response fields are updated only if you set directive NOOLDCICS.
I
Issue a warning when the program is compiled and ignore the option at run time.
E
Issue an error when the program is compiled.

Properties:

Default: UOPT(E)

Build Settings:

Check EXEC CICS and Options on the Assembler tab of your project properties Assembler page; then choose the type of handling you require from the Unsupported option handling list on the EXEC CICS Options dialog box.

Parent topic: Assembler Compiler Directives


VSECOMP

Set a macro variable that allows the Enterprise Developer Assembler implementation to correctly interpret DOS/VSE macro operands where these differ from their MVS counterparts.

Syntax:

[NO]VSECOMP

Properties:

Default: NOVSECOMP

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


XMAC

Include a cross-reference listing in filename.prn for all macros and copybooks showing the relative line numbers of the generated statements.

Syntax:

[NO]XMAC

Properties:

Default: NOXMAC

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

If you also specify the XFLN directive, the cross-reference listing shows the file and relative line numbers of the original statements that reference the macros and copybooks.

Parent topic: Assembler Compiler Directives


XREF

Include a cross-reference listing in filename.prn for all labels and literals showing the relative line numbers of the generated statements.

Syntax:

[NO]XREF

Properties:

Default: NOXREF

Build Settings:

Check Include cross-reference listing on the Assembler tab of your project properties Assembler page.

Comments:

If you also specify the XFLN directive, the cross-reference listing shows the file and relative line numbers of the original statements that reference the labels and literals, in addition to the numbers of the generated statements.

Parent topic: Assembler Compiler Directives


XSVC

Include an entry for each SVC in the module in filename.prn in a cross-reference table that shows the relative line numbers of all the statements that reference that SVC.

Syntax:

[NO]XSVC

Properties:

Default: NOXSVC

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Parent topic: Assembler Compiler Directives


Assembler Linker Directives

You can specify Assembler Linker directives on the command line when building from the command line, or in your project properties when building from the IDE.

Note: Take care when setting compiler directives in the Additional Directives field on the Linker tab of your project properties Assembler page as these could conflict with a default setting.
  • AMODE
    Set the memory address type.
  • ANIM
    Generate .idf and .idx files required to debug an Assembler module during execution.
  • ASM
    Specify the Assembler language.
  • AUTOALIAS
    Create entries in the mfentmap.dat file for all entry points in all included Assembler modules.
  • CALL
    Attempt to automatically resolve any remaining external references by repeatedly searching the load library for .obj files matching external names.
  • COMPOSITE
    Do not automatically include the main module in the executable program file.
  • EXPORT
    Export all CSECT names and entry names so that COBOL modules can call them at run time (using LOAD and BALR instructions).
  • LIST
    Create a listing of the CSECTs in filename.390 with their addresses relative to the beginning of the program, entry points, and external cross references in filename.lst in the listing library.
  • NONCAN
    Mark the filename.390 file as re-entrant and non-cancel; this prevents it from being removed from storage at the end of execution, even if it is executed from IMS or CICS.
  • OMF
    Specifies the type of output - load module or CICS data table.
  • RENT
    Mark the filename.390 file as re-entrant; this prevents reloading of the module each time it is called.
  • REUS
    Mark load module as serially reusable; this prevents reloading of the module each time it is called.
  • RMODE
    Specify a residence mode for the load module.
  • TRACE
    Display trace of Assembler Linker execution to aid in debugging linking problems.
Parent topic: Assembler Reference


AMODE

Set the memory address type.

Syntax:

AMODE({24|31})

Parameters:

24
Use three-byte (24-bit addresses), compatible with memory below the line on the mainframe.
31
Use 31-bit addresses, compatible with memory above and below the line on the mainframe.

Properties:

Default: AMODE(31)

Build Settings:

Choose an AMODE setting from the Addressing mode list on the Linker tab of your project properties Assembler page.

Parent topic: Assembler Linker Directives


ASM

Specify the Assembler language.

Syntax:

[NO]ASM

Properties:

Default: ASM

Build Settings:

Type directly into the Additional Directives field on the Assembler tab of your project properties Assembler page.

Comments:

Directives ASM and PLI are alternatives to one another.

Parent topic: Assembler Linker Directives


AUTOALIAS

Create entries in the mfentmap.dat file for all entry points in all included Assembler modules.

Syntax:

[NO]AUTOALIAS

Properties:

Default: NOAUTOALIAS

Build Settings:

Type directly into the Additional Directives field on the Linker tab of your project properties Assembler page.

Parent topic: Assembler Linker Directives


CALL

Attempt to automatically resolve any remaining external references by repeatedly searching the load library for .obj files matching external names.

Syntax:

[NO]CALL

Properties:

Default: CALL

Build Settings:

Check Resolve external calls at link time on the Linker tab of your project properties Assembler page.

Comments:

If the loading of these modules in turn adds additional external references, the process is repeated until there are no remaining unresolved external references or until the last pass fails to resolve any additional external references.

Error messages are issued for any unresolved external references.

Parent topic: Assembler Linker Directives


COMPOSITE

Do not automatically include the main module in the executable program file.

Syntax:

[NO]COMPOSITE

Properties:

Default: NOCOMPOSITE

Dependencies:

When this option is specified, you must add an INCLUDE statement for the main module to the link file.

Build Settings:

Type directly into the Additional Directives field on the Linker tab of your project properties Assembler page.

Parent topic: Assembler Linker Directives


EXPORT

Export all CSECT names and entry names so that COBOL modules can call them at run time (using LOAD and BALR instructions).

Syntax:

[NO]EXPORT

Properties:

Default: EXPORT

Build Settings:

Type directly into the Additional Directives field on the Linker tab of your project properties Assembler page.

Comments:

Specify NOEXPORT if there are names in statically linked modules that match names in dynamically linked modules, and the dynamically linked modules are to be executed. When NOEXPORT is specified, only entry names specified on ALIAS link file commands are exported.

Parent topic: Assembler Linker Directives


LIST

Create a listing of the CSECTs in filename.390 with their addresses relative to the beginning of the program, entry points, and external cross references in filename.lst in the listing library.

Syntax:

[NO]LIST

Properties:

Default: NOLIST

Build Settings:

Check Generate listing file on the Linker tab of your project properties Assembler page.

Comments:

The actual load address of each CSECT is determined at load time and all address constants are then updated.

Parent topic: Assembler Linker Directives


NONCAN

Mark the filename.390 file as re-entrant and non-cancel; this prevents it from being removed from storage at the end of execution, even if it is executed from IMS or CICS.

Syntax:

[NO]NONCAN

Properties:

Default: NONONCAN

Build Settings:

Type directly into the Additional Directives field on the Linker tab of your project properties Assembler page.

Parent topic: Assembler Linker Directives


OMF

Specifies the type of output - load module or CICS data table.

Syntax:

OMF({390|MOD})

Parameters:

390
Executable format in filename.390.
MOD
Non-executable table format in filename.MOD. The file contains assembled object code with no header and no relocation data. This option is often used to create CICS tables.

Properties:

Default: OMF(390)

Build Settings:

Choose an OMF setting from the Linker output list on the Linker tab of your project properties Assembler page.

Parent topic: Assembler Linker Directives


RENT

Mark the filename.390 file as re-entrant; this prevents reloading of the module each time it is called.

Syntax:

[NO]RENT

Properties:

Default: RENT

Build Settings:

Check Mark load module as reentrant on the Linker tab of your project properties Assembler page.

Parent topic: Assembler Linker Directives


REUS

Mark load module as serially reusable; this prevents reloading of the module each time it is called.

Syntax:

[NO]REUS

Properties:

Default: REUS

Build Settings:

Check Mark load module as serially reusable on the Linker tab of your project properties Assembler page.

Parent topic: Assembler Linker Directives


RMODE

Specify a residence mode for the load module.

Syntax:

RMODE({24|31})

Parameters:

24
Load the module into memory below the line, for compatibility with mainframe 24-bit (3-byte) addresses.
31
Load the module into memory either above or below the line, for compatibility with mainframe 31-bit (4-byte) addresses.

Properties:

Default: RMODE(31)

Build Settings:

Choose an RMODE setting from the Residency mode list on the Linker tab of your project properties Assembler page.

Comments:

If the link process run by the Compiler detects any 24-bit address fields in the load module, it issues a warning message and automatically changes the directive to RMODE(24), while leaving the AMODE setting unchanged.

Parent topic: Assembler Linker Directives


TRACE

Display trace of Assembler Linker execution to aid in debugging linking problems.

Syntax:

[NO]TRACE

Properties:

Default: NOTRACE

Build Settings:

Type directly into the Additional Directives field on the Linker tab of your project properties Assembler page.

Comments:

The information displayed includes an external symbol dictionary (ESD) table, information about each ESD type entry in the load module, information about each pass made by the linker while attempting to resolve undefined external CALLs, and information about each relocation address generated to allow the module to be loaded at any location in memory.

Parent topic: Assembler Linker Directives


Assembler Link Files

Describes the format and usage of .lin files containing linker commands.

The Assembler linker takes commands from both the linker command line and also an optional linker input file with the extension .lin. The commands contained in the .lin file tell the linker what to include in the executable file, and the filename and other properties of the executable output file. By default, the assembler linker input file exists in the same directory as the Assembler .obj files. The linker looks first for a .lin, and if found, processes it before any found .obj files.

For example, if the Assembler object filename is test.obj, you can write a linker input file called test.lin and specify the following include commands:
// INCLUDE TEST2.OBJ
// INCLUDE TEST3.OBJ
// INCLUDE TEST4.OBJ

The resulting .390 executable module has four assembler modules linked into it.

A common usage of the linker command is to specify which entry points are actually in COBOL modules. Take the following example:
// INCLUDE TEST2.OBJ
// INCLUDE TEST3.OBJ,TYPE=CBL

In this example, TEST3 is an external symbol in a COBOL module. The linker does not look for test.obj. Instead the linker generates a small stub Assembler module so that if the TEST3 entry point is ever branched to by an Assembler module, a transfer of control is be done to give the COBOL TEST3 module control.

Parent topic: Assembler Reference


Assembler Link File Commands

In the link file command descriptions, square brackets, "[]", indicate optional parameters that can be omitted, braces, "{}", indicate parameters of which at least one must be selected, "{}..." indicates parameters that can be repeated, and vertical bars, "|", indicate alternative parameters of which no more than one can be selected.

Assembler link file command usually have the extension .LIN and can have optional slashes put in front of the commands, for example:

// include asm1.obj
// include cob1,type=CBL

Comments may be placed in the file by preceding them, either with a semicolon as follows:

// include asm1.obj   ; main assembler entry point comment

Or by placing an asterick character in column one as follows:

*this is the main assembler entry point
// include asm1.obj

The link file commands can start anywhere after the first column.

  • ALIAS Link File Command
    Creates an entry in the mfentmap.dat file to allow the load module (filename.390) to be called by an alternate name.
  • CHANGE Link File Command
    Provides compatibility with the IBM binder that replaces the IBM linkage editor. However, the Enterprise Developer Assembler implementation emulates the linkage editor, not the binder.
  • ENTRY Link File Command
    Specifies an entry point for the load module (.390 file), where its external name is not the entry point.
  • INCLUDE Link File Command
    Specifies an object file to be linked into the executable file.
  • Name Link File Command
    Specifies a name for the load module.
Parent topic: Assembler Reference


ALIAS Link File Command

Creates an entry in the mfentmap.dat file to allow the load module (filename.390) to be called by an alternate name.

Syntax:

ALIAS aliasname

Parameters:

aliasname
The alternate name to be used to call the load module.

Comments:

The ALIAS command can start anywhere after the first column.

Parent topic: Assembler Link File Commands


CHANGE Link File Command

Provides compatibility with the IBM binder that replaces the IBM linkage editor. However, the Enterprise Developer Assembler implementation emulates the linkage editor, not the binder.

Syntax:

CHANGE {oldname(newname),}...

Parameters:

oldname
The external symbol to be changed.
newname
The new name to which the external symbol is to be changed.

Comments:

You can repeat the parameters to change multiple external symbols. Continuation lines are not accepted, so use multiple CHANGE commands if you have more entries than will fit on one line.

If you want to change external symbols in the main module, use the COMPOSITE linker directive to suppress the automatic inclusion of the main module, then specify your CHANGE commands followed by an INCLUDE command for the main module.

Parent topic: Assembler Link File Commands


ENTRY Link File Command

Specifies an entry point for the load module (.390 file), where its external name is not the entry point.

Syntax:

ENTRY esdname

Parameters:

esdname
The name of the entry point for the load module.

Comments:

The ENTRY command can start anywhere after the first column.

Parent topic: Assembler Link File Commands


INCLUDE Link File Command

Specifies an object file to be linked into the executable file.

Syntax:

INCLUDE SYSLIB(filename),[TYPE={ASM|CBL}],[PARMS={VL|IMS|nnn}]

Parameters:

SYSLIB(filename)
Module to include.
TYPE
Module type. Optional. Default: ASM
ASM | Assembler object module (.obj)
CBL | COBOL module (.int or .gnt)
PARMS
Parameter processing. Required only when TYPE=CBL and register 0 is not available for passing the number of parameters.
VL | Scan for high bit in last parameter address to determine number of parameters.
IMS | Check first parameter for full-word integer value between 1 and 19. If found, set parameter count to value + 1. If not found, perform VL scan of up to 19 parameters including null parameters. Set parameter count to 19 if no VL bit found.
nnn | Set parameter count to specific value.

Comments:

The INCLUDE command can start anywhere after the first column.

If TYPE=CBL, you must either specify the PARMS parameter, or pass the number of parameters in register 0, using the high byte of the register to indicate the method. A value of h"00" indicates that the number of parameters is in the bottom 24 bits of register 0. A value of h"80" is equivalent to PARMS=VL, and a value of h"40' is equivalent to PARMS=IMS.

Parent topic: Assembler Link File Commands


Name Link File Command

Specifies a name for the load module.

Syntax:

NAME filename (R)

Parameters:

SYSLIB(filename)
Module to include.
(R)
Replace the load module if it already exists (optional). If you do not specify R and the load module already exists, it is not replaced.

Comments:

The NAME command can start anywhere after the first column.

If omitted, the name is the same as the name of the source module, with the extension .390.

Parent topic: Assembler Link File Commands


Macros and SVCs

Assembler support incorporates a number of macros and SVCs (supervisor calls). Those that are supported are, in general, not compatible with the equivalent macros and SVCs on the mainframe, so wherever possible, use macros to get the desired SVC function.

Some macro options are not fully supported in that they do compile, but have no effect when executed. There are also some macros which are supported in stub form, that is, macro code exists but it simply returns control to the calling program. These stubs are provided for macros that perform tasks that have no meaning on the PC. An example stub macro is provided in %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\include\stub.mac; you can use this to create your own stub macros.

There are two categories of macro:

  • Assembler services macros. These provide services for interfacing with the Assembler run-time system, managing memory, calling other programs and for general functions such as saving and restoring registers. There are also services for accessing the catalog and for dynamically allocating and deallocating data sets at execution time.
  • File handling macros. These provide access to files.

Many Assembler services macros equate to SVCs. You can choose whether to code the macro or its equivalent SVC, but in general it is easier to use the macros. The following table relates the SVCs and service macros:

SVC | Macro | Description
4 | GETMAIN L LC LU E EC EU, VC, VU | Get memory (list, element and variable requests).
5 | FREEMAIN L LC LU E EC EU, VC, VU | Free memory (list, element and variable requests).
6 | LINK | Link to another Assembler program.
8 | LOAD | Load another Assembler program or a COBOL program.
9 | DELETE | Delete a loaded module.
10 | GETMAIN R | Get memory (R type register requests).
11 | TIME | Get the time of day and the date.
13 | ABEND | Terminate the program and open the Assembler debugger if possible, or display information about the state of the program when the abend occurred.
14 | SPIE | Handle a program exception within the executing module.
26 | CATALOG and LOCATE | Uncatalog a data set; return a volume list for a data set.
29 | SCRATCH | Delete a data set.
35 | WTO WTOR | Display a message on the screen. Display a message on the screen and wait for a reply.
39 | LINKC2 | Link to a COBOL program.
41 | IDENTIFY | Associate a name you specify with an already loaded program.
62 |  | Remove the executing program. There is no corresponding macro.
99 | DYNALLOC | Allocate or deallocate a resource at execution time.
103 | XLATE | Convert between ANSI and EBCDIC.
120 | GETMAIN RU, RC, VRC, VRU; FREEMAIN R, RU, RC, VRC and VRU; STORAGE | Get memory (RU and RC type register requests) Free memory (all types of register requests). Get memory or free memory
 | CALL | Transfer control to a statically linked module. There is no corresponding SVC.
 | CAMLST | Create parameter list for CATALOG, LOCATE or SCRATCH. There is no corresponding SVC.
 | DEQ | Relinquish control of one or more serially reusable resources. There is no corresponding SVC.
 | ENQ | Request control of one or more serially reusable resources. There is no corresponding SVC.
 | EXTRACT | Obtain information from control block. There is no corresponding SVC.
 | RETURN | Restore registers and sets the address to return to. There is no corresponding SVC.
 | SAVE | Save registers. There is no corresponding SVC.
 | SPLEVEL | Test or set the level of MVS macro compatibility. There is no corresponding SVC.
 | WAIT | Wait for event completion. There is no corresponding SVC.
  • Macro Instructions
  • Supervisor Services (SVCs)
Parent topic: Assembler Reference


Macro Instructions

The following topics contain information on macro instructions.

  • MVS Macro Instructions
  • DOS/VSE Macro Instructions
Parent topic: Macros and SVCs


MVS Macro Instructions

The MVS macro instructions supported for Assembler are divided into the groups described below. Please select the group you require.

  • Assembler services macro instructions. These provide services for interfacing with the Assembler run-time system, managing memory, calling other programs and performing general functions such as saving and restoring registers.
  • File handling macro instructions. These provide access to files.
The descriptions of the macros provided in this online help are intended just to remind you of their purpose and use. For full descriptions and background information you need to consult the IBM manuals:
  • OS/390 MVS Assembler Services Reference SC26-8265
  • OS/390 MVS Macro Instructions for Data Sets SA22-7201

The conventions used in the macro specifications are explained in the Key to Macro Instructions help topic.

Many macros are available in list and execute forms as well as the standard form. Some of the file handling macros are also available in generate form. The help topic for each macro states which other forms are available in addition to the standard form. The help topic for WTO provides syntax and examples for list and execute forms.

We provide stubs for some macros that perform no useful function on the PC. The stub code simply returns control to the calling program. The stub macros are as follows:

AMODE

FREEPOOL

MODESET

RMODE

There are no help topics for these macros.

Parent topic: Macro Instructions


DOS/VSE Macro Instructions

Enterprise Developer Assembler support includes many DOS/VSE macros, essentially by mapping DOS/VSE functions onto MVS functions. The VSECOMP Assembler Compiler directive allows Assembler Option to correctly interpret DOS/VSE macro operands where these differ from their MVS counterparts.

DOS/VSE-specific macros other than those listed above are not supported.

For more information, please consult the IBM manual VSE/ESA System Macros Reference SC33-6516.

  • Macros That Require VSECOMP Directive
  • Macros Common with MVS
  • DOS/VSE-specific Macros
Parent topic: Macro Instructions


Macros That Require VSECOMP Directive

The following DOS/VSE macros require the use of the VSECOMP directive to ensure that their operands are interpreted correctly:

  • CLOSE
  • GET
  • LOAD
  • OPEN
  • PUT
Parent topic: DOS/VSE Macro Instructions


CLOSE

[label] CLOSE (address[,(options)],...)

[,MODE=24|31]

Parameters

address
The address of the ACB or DCB for each file to close.
MODE=24|31
For QSAM and BSAM files, specifies whether the program is running in 24-bit or 31-bit mode. No effect for VSAM files.

Comments

Closes an active VSAM, BSAM or QSAM file or files at execution time.

List and execute forms are also available.

If the VSECOMP compiler directive is specified, Enterprise Developer Assembler support includes emulating the DOS/VSE version of this macro. In this case the expanded code is larger than that produced on the mainframe and may cause NO BASE REGISTER error messages. The unusual DOS/VSE register conventions for register 1 are also supported, so syntax of the form CLOSE (1) is accepted. However, the multiple operand syntax of the DOS/VSE CLOSE macro is not supported, so use the MVS syntax instead.

The DOS/VSE-specific macro CLOSER (Close a File Relocatable) is simply mapped to the standard CLOSE macro. Self-relocating code is not generated as it would be under the DOS/VSE environment so modules using CLOSER cannot be relocated at execution time by simply copying the generated machine code from one address to another.

CLOSE VSAMFILE
Parent topic: Macros That Require VSECOMP Directive


GET

[label] GET RPL=address|dcb-address,[area-address]

Parameters

RPL=address
RPL to use with a VSAM GET request.
dcb-address
Data control block to use with a QSAM GET request.
area-address
Address of the area to hold the record read from the QSAM file.

Comments

Retrieves a record from a VSAM or QSAM file.

If the VSECOMP compiler directive is specified, Enterprise Developer Assembler support includes emulating the DOS/VSE version of this macro. In this case the expanded code is larger than that produced on the mainframe and may cause NO BASE REGISTER error messages. The unusual DOS/VSE register conventions for register 1 and 0 are also supported, so syntax of the form GET (1) or GET (1)(0) is accepted.

A utility macro SADV (Save Address Value) used by GET expands slightly differently when VSECOMP is specified. Normally, SADV expands to LA register,dcb-address. With VSECOMP specified the instruction L register,=A(dtf-address) is produced instead.

Examples

GET RPL=INRPL

GET INFILE,RECORD

Parent topic: Macros That Require VSECOMP Directive


LOAD

[label] LOAD EP=program-name|EPLOC=program-address|DE=list-entry-addr

[,DCB=dcb-addr]

[,ERRET=err-rtn-addr]

[,LSEARCH=NO|YES]

[,LOADPT=addr]

[,RELATED=value]

Parameters

EP= program-name
Name of the program to be loaded, up to a maximum of eight characters. A file extension is not required; the LOAD routine first attempts to load a file with the extension .390 and then a file with the extension .mod. If it fails to find either, it generates a stub Assembler program that loads and links to a COBOL program called program-name.
EPLOC= program-address
Name of the data element that contains the address of the program name.
ERRET=err-rtn-addr
The address of an exit to receive control when an error condition is detected. err-rtn-addr is an A-type address or register (2) through (12).
LOADPT=addr
The starting address at which the program was loaded. addr is an A-type address or register (2) through (12).

Comments

Loads the specified program into memory.

Assembler LOADs:

The LOAD macro loads the program in memory above or below the line depending on its RMODE setting. At the completion of the LOAD, register 15 has a binary value of zero, register 0 has the address of where the program was loaded, register 1 contains the length of the program, and the high order bit of register 0 is set to indicate the AMODE setting of the loaded program, as follows:

0=AMODE(24)

1=AMODE(31)

COBOL LOADs:

The LOAD macro loads the stub Assembler program below the line. When the stub Assembler program is executed, it loads the COBOL program above or below the line depending on its AMODE setting; a COBOL program's Working-Storage Section may be loaded separately if the program's DATA directive does not match its AMODE directive. If an AMODE(31) Assembler program LOADs an AMODE(24) COBOL program, then an 0C5 abend occurs at the time the stub code is executed, since the 31-bit Assembler parameter addresses cannot be successfully passed to the 24-bit COBOL program.

DOS/VSE compatibility:

If the VSECOMP compiler directive is specified, Enterprise Developer Assembler support includes emulating the DOS/VSE version of this macro. In this case the first positional parameter is the name of a program to load (the EP keyword is not required). At the completion of the LOAD, register 1 has the address of where the program was loaded, with the high order bit set to indicate the AMODE setting of the loaded program.

Examples

LOAD EP=MYPROG

LOAD  EPLOC=PNAME
    PNAME    DC    CL8'MYPROG'
Parent topic: Macros That Require VSECOMP Directive


OPEN

[label] OPEN (address[,INPUT|OUTPUT|UPDAT|EXTEND],...)

[,MODE=24|31]

Parameters

address
Address of an ACB or DCB associated with the file to be activated.
INPUT|OUTPUT |UPDAT|EXTEND
These options are specified for QSAM and BSAM files only and indicate the type of processing to be enabled for the opened file. Option UPDAT is not available for BSAM files. Options specified for VSAM files are ignored.
MODE=24|31
For QSAM and BSAM files, specifies whether the program is running in 24-bit or 31-bit mode. No effect for VSAM files.

Comments

Opens a QSAM, BSAM or VSAM file or files for file handling.

List and execute forms are also available.

If the VSECOMP compiler directive is specified, Enterprise Developer Assembler support includes emulating the DOS/VSE version of this macro. In this case the expanded code is larger than that produced on the mainframe and may cause NO BASE REGISTER error messages. The unusual DOS/VSE register conventions for register 1 are also supported so syntax of the form OPEN (1) is accepted. However, the multiple operand syntax of the DOS/VSE OPEN macro is not supported, so use the MVS syntax instead.

The DOS/VSE-specific macro OPENR (Open a File Relocatable) is simply mapped to the standard OPEN macro. Self-relocating code is not generated as it would be under the DOS/VSE environment so modules using OPENR cannot be relocated at execution time by simply copying the generated machine code from one address to another.

Example

OPEN (INDCB,(OUTPUT))

OPEN ((2))

Parent topic: Macros That Require VSECOMP Directive


PUT

[label] PUT RPL=address|dcb-address,[area-address]

Parameters

RPL=address
Request parameter list to use for writing to a VSAM file.
dcb-address
Data control block to use for writing to a QSAM file.
area-address
Address of the record to be written to a QSAM file.

Comments

Writes a data record to an open QSAM or VSAM file.

If the VSECOMP compiler directive is specified, Enterprise Developer Assembler emulates the DOS/VSE version of this macro. In this case the expanded code is larger than that produced on the mainframe and may cause NO BASE REGISTER error messages. The unusual DOS/VSE register conventions for register 1 and 0 are also supported, so syntax of the form PUT (1) or PUT (1)(0) is accepted.

A utility macro SADV (Save Address Value) used by PUT expands slightly differently when VSECOMP is specified. Normally, SADV expands to LA register,dcb-address. With VSECOMP specified the instruction L register,=A(dtf-address) is produced instead.

Example

PUT RPL=OUTRPL

PUT OUTDCB,RECORD

Parent topic: Macros That Require VSECOMP Directive


Macros Common with MVS

The following DOS/VSE macros are common with MVS:

  • CALL DOS/VSE Macro
  • DEQ
  • ENQ
  • EXTRACT
  • READ
  • RETURN
  • SAVE
  • WTO
  • WTOR
Parent topic: DOS/VSE Macro Instructions


CALL DOS/VSE Macro

[label] CALL progname

,(parm01,parm02,...)

[,VL]

[,ID=id-number]

Parameters

progname
Name of the CSECT to be called.
parm01,parm02
Names of the parameters that will be used to create a parameter address list for loading into register 1.
VL
Cause the high-order bit of the address of the last parameter to be set on; include this if the CSECT can be passed a variable number of parameters.
ID=id-number
Generate a NOP branch instruction with the id-number in the low order 12 bits. The purpose of this is to enable you to identify each call uniquely during debugging. Id-number can be a value between 0 and 4095.

Comments

Passes control to another program.

Examples

CALL MYPROG

CALL MYPROG,(PARM1,PARM2,PARM3),VL

Parent topic: Macros Common with MVS


DEQ

[label] DEQ (qname-addr

,rname-addr

,[rname-length]

,[STEP|SYSTEM|SYSTEMS])

[,LOC=BELOW|ANY]

[,RET=HAVE|NONE]

[,RNL=YES|NO]

[,RELATED=value]

[,UCB=ucb-address]

Parameters

qname-addr
Address of major resource name. The name may contain up to 8 characters.
rname-addr
Address of minor resource name. The name may contain up to 255 characters. The first byte must contain the length if rname-length is 0.
rname-length
Length of rname, between 0 and 255. 0 indicates that the length is in the first byte of rname. If omitted the assembled rname label length is used.
STEP|SYSTEM |SYSTEMS
Defines the scope of the request:

STEP=This job step only (default)

SYSTEM=This system only

SYSTEMS=Multiple systems

RET=HAVE |NONE
Type of resource request:

HAVE=Request now if not previously requested

NONE=Request unconditionally (default)

RNL=YES|NO
YES requests that global resource serialization perform resource name list (RNL) processing, which can cause the scope value of a resource to change.
RELATED= value
Specifies where related documentary text is located.

List and execute forms are also available.

Comments

Relinquishes control of one or more serially reusable resources.

The first four parameters (qname-addr through STEP|SYSTEM|SYSTEMS) may be repeated to specify multiple requests, up to a limit of 255 characters.

The final five parameters (LOC through UCB) apply to all the requests specified.

Example

DEQ (MAJOR1,MINOR1,,SYSTEM)

This example relinquishes ownership of one resource. The length of the minor resource name defaults to the assembled length.

DEQ (MAJOR2,MINOR2,12,,MAJOR3,MINOR3,,)RET=HAVE,RNL=NO

This example relinquishes ownership of two resources. The length of the second minor resource name defaults to the assembled length. The scope of both requests defaults to this job step only. Both requests are implemented only if the resources are immediately available. The requests are subject to resource name list processing.

Parent topic: Macros Common with MVS


ENQ

[label] ENQ (qname-addr

,rname-addr

,E|S

[,rname-length]

[,{STEP|SYSTEM|SYSTEMS}])

[,RET=CHNG|HAVE|TEST|USE|NONE]

[,RNL=YES|NO]

[,RELATED=value]

Requests control of one or more serially reusable resources.

List and execute forms are also available.

Parameters

qname-addr
Address of major resource name. The name may contain up to 8 characters.
rname-addr
Address of minor resource name. The name may contain up to 255 characters. The first byte must contain the length if rname-length is 0.
E|S E
indicates exclusive ownership. S indicates shared ownership.
rname-length
Length of rname, between 0 and 255. 0 indicates that the length is in the first byte of rname. If omitted the assembled rname label length is used.
STEP|SYSTEM |SYSTEMS

Defines the scope of the request:

STEP=This job step only (default)

SYSTEM=This system only

SYSTEMS=Multiple systems

RET=CHNG| HAVE|TEST| USE|NONE

Type of resource request:

CHNG=Change from shared to exclusive

HAVE=Request now if not previously requested

TEST=Test if available

USE=Request if immediately available. Program continues if not available.

NONE=Request unconditionally (default). Program waits.

RNL=YES|NO
YES requests that global resource serialization perform resource name list (RNL) processing, which can cause the scope value of a resource to change.
RELATED= value
Specifies where related documentary text is located.

Comments

The first five parameters (qname-addr through STEP|SYSTEM|SYSTEMS) may be repeated to specify multiple requests, up to a limit of 255 characters.

The final three parameters (RET through RELATED) apply to all the requests specified.

Examples

Example 1:

ENQ (MAJOR1,MINOR1,E,,SYSTEM)

This example requests exclusive ownership of one resource. The length of the minor resource name defaults to the assembled length.

Example 2:

ENQ (MAJOR2,MINOR2,E,12,,MAJOR3,MINOR3,S,,)RET=USE,RNL=YES

Parent topic: Macros Common with MVS


EXTRACT

[label] EXTRACT answer-addr

[,tcb-addr]

,FIELDS=(tcb-info)

Parameters

answer-addr
The address of the answer area to contain the requested information. A-type address or register (2) through (12).
tcb-info
The task control block information requested. The only currently supported value is FIELDS=(TIOT).

Comments

Causes the system to provide information from specified fields of the task control block or a subsidiary control block for either the active task or one of its subtasks.

Example

EXTRACT ANSADDR,FIELDS=(TIOT)

Parent topic: Macros Common with MVS


READ

[label] READ decb

,SF|SB

,dcb-address

,area-address

[,length|'S']

Parameters

decb
Label to use for generated data event control block.
dcb-address
Address of DCB for file to read.
area-address
Address of buffer to receive data.
length|'S'
Number of bytes to transfer or 'S' to indicate entire block should be read (default). The single quote marks around the S are required.

The format of the data event control block is as follows:

Bytes | Contains
0-3 | Full word of zeroes.
4 | Type flag: x'80' if 'S' parameter used in macro else x'00'.
5 | Subtype flag: always x'20'.
6 - 7 | Two-byte binary field set to value of the length parameter unless 'S' specified or register notation used in which case the field will be set to 0.
8 - 11 | Address of DCB.
12 - 15 | Address of area to receive data.

Comments

Causes one block of a BSAM file to be transferred from a file to a buffer in memory. The user program is responsible for any deblocking or other processing that may be required if the block contains more than one logical record.

The data event control block (DECB) generated by the macro is mainframe-compatible, however, each READ operation is synchronous, that is, control is not returned to the calling program until the operation is complete.

Input/output parameter blocks are not generated or used.

Examples

Example 1:

QREAD READ INDECB,SF,INFILE,INBUF,'S'

This example reads one entire block from file identified by the open DCB at INFILE into a buffer identified by INBUF.

Example 2:

READ RDECB5,SF,(*,FILEADDR),(3)

This example reads one block from DCB identified by the indirect S type address constant (*,FILEADDR) into the buffer whose address is held in register 3.

Parent topic: Macros Common with MVS


RETURN

[label] RETURN (lit1,lit2)

,[T]

,RC=n|(n)

Parameters

(lit1,lit2)
T
Causes the control program to flag the save area used by the calling program.
RC=n
Sets the return code to the numeric value specified by n.
RC=(n)
Numeric values from 0 through 15 that specify the from and to registers to restore from the register save area. This area is normally pointed to by register 13.

Comments

Sets the return code to the numeric value in register n.

Restores the specified registers and returns to the calling program.

lit1 is the first register to restore. lit2 is the last register to restore. lit1 and lit2 must be values between 0 and 15. If lit1 is greater than lit2 then the registers saved are lit1 through 15 and 0 through lit2. However, register 15 is never restored, because it is always used to hold the return code.

If the calling program is in Assembler the return code is available in register 15. If the calling program is in COBOL, the return code is available in RETURN-CODE.

Examples

Example 1

RETURN (14,12)

Restores the contents of registers 14 and 0 through 12 from the register save area specified in register 13.

Example 2

RETURN (14,12),,RC=0

Restores the contents of registers 14 and 0 through12 and sets the return code (and hence register 15) to zero.

Example 3

RETURN (14,12),,RC=(15)

Restores the contents of register 14 and 0 through 12 and sets the return code to the current value of register 15.

Parent topic: Macros Common with MVS


SAVE

[label] SAVE (lit1,lit2)

,[T]

,id-name

Parameters

(lit1,lit2)
Numeric values from 0 through 15 that specify the from and to registers to save into the register save area. This area is normally pointed to by register 13.
T
Specifies that registers 14 and 15 are to be stored in word 4 and 5, respectively, of the save area.
Id-name
Specifies an identifier to be associated with the SAVE macro. If an asterisk (*) is coded, the identifier is the label associated with the SAVE macro, or, if the label field is blank, the control section name is used.

Comments

Saves the specified general-purpose registers.

lit1 is the first register to save. lit2 is the last register to save. lit1 and lit2 must be values between 0 and 15. If lit1 is greater than lit2 then the registers saved are lit1 through 15 and 0 through lit2.

Examples

SAVE (14,12)

Saves the contents of registers 14 through 15 and 0 through 12 to the register save area specified by register 13.

Parent topic: Macros Common with MVS


WTO

Standard Form:

[label] WTO 'message'|('text',line-type)|TEXT=(text-addr,line-type)

[,ROUTCDE=]

[,MCSFLAG=]

[,DESC=]

[,CART=]

[,KEY=]

[,TOKEN=]

[,CONSID=]

[,CONSNAME=]

Execute Form:

[label] WTO TEXT=(text-addr,line-type)

[,ROUTCDE=]

[,MCSFLAG=]

[,DESC=]

[,CART=]

[,KEY=]

[,TOKEN=]

[,CONSID=]

[,CONSNAME=]

,MF=(E,label1)

List Form:

[label1] WTO 'message'|('text',line-type)|TEXT=(text-addr,line-type)

[,ROUTCDE=]

[,MCSFLAG=]

[,DESC=]

[,CART=]

[,KEY=]

[,TOKEN=]

[,CONSID=]

[,CONSNAME=]

,MF=L

Parameters

message
Message text to be displayed. It must be in quotes.
text
Message text to be displayed. It must be in quotes.
text-area
Address of message text to be displayed
label1
Label of either list form WTO instruction or parameter block

Comments

Examples

Example 1

WTO 'THIS IS A SIMPLE WTO MACRO INSTRUCTION'

Example 2

WTO MF=(E,MESSAGE)

MESSAGE WTO 'THIS IS A WTO-LIST MESSAGE',MF=L

Example 3

WTO MF=(E,MESSAGE)

MESSAGE EQU *

DC H'84' MESSAGE LENGTH PLUS 4

DC H'0'

DC CL80'THIS IS MY MESSAGE'

Parent topic: Macros Common with MVS


WTOR

[label] WTOR 'message'|('text',line-type)|TEXT=(text-addr,line-type)

,reply

,reply-length

,ecb-addr

[,ROUTCDE=]

[,MCSFLAG=]

[,DESC=]

[,CART=]

[,KEY=]

[,TOKEN=]

[,CONSID=]

[,CONSNAME=]

Parameters

message
Message text to be displayed. It must be in quotes.
text
Message text to be displayed. It must be in quotes.
text-addr
Address of message text to be displayed
reply
The field that will contain the reply. It may be a symbolic label or be in register notation.
reply-length
Length of the reply field. It may be an arithmetic value or be in register notation.

Comments

Writes to operator and waits for a reply, that is, displays a message in the Application Output window and waits for the operator to type a value and press the Enter key.

Examples

WTOR 'THIS IS MY MESSAGE',REPLY,10

REPLY DC CL10'

Parent topic: Macros Common with MVS


DOS/VSE-specific Macros

The following DOS/VSE-specific macros are supported:

  • CANCEL
  • CCB
  • CDLOAD
  • COMRG
  • DTFMT
  • DTFCD
  • DTFPR
  • DTFSD
  • EOJ
  • EXCP
  • FREEVIS
  • GETIME
  • GETVIS
  • WAIT

DOS/VSE-specific macros other than those listed above are not supported.

Parent topic: DOS/VSE Macro Instructions


Supervisor Services (SVCs)

Select the supervisor call (SVC) you require from the list:

  • SVC 4, GETMAIN (all E and L options, VU and VC)
  • SVC 5, FREEMAIN (all E and L options, VU and VC)
  • SVC 6, LINK
  • SVC 8, LOAD
  • SVC 9, DELETE
  • SVC 10, GETMAIN (R option)
  • SVC 11, TIME
  • SVC 13, ABEND
  • SVC 14, SPIE
  • SVC 26, CATALOG and LOCATE
  • SVC 29, SCRATCH
  • SVC 35, WTO and WTOR
  • SVC 39, LINKC2
  • SVC 41, IDENTIFY
  • SVC 62, Detach
  • SVC 99, DYNALLOC
  • SVC 103, XLATE
  • SVC 120
Parent topic: Macros and SVCs


SVC 4, GETMAIN (all E and L options, VU and VC)

INPUT
  • Register 1

    Address of parameter list.

OUTPUT
  • Register 0

    Amount of memory obtained

  • Register 1

    Address of allocated memory.

  • Register 15
    Return code:
    • 0=Successful
    • 4=Insufficient memory available

Parameter list, 10 bytes in length.

Bytes | Description
0-3 Element request: length requested

Variable request: address of a double-word containing the minimum and maximum lengths requested. Format is:

0 Zero

1-3 Minimum length

4 Zero

5-7 Maximum length

List request: address of a list of lengths requested (one word per request, the last word contains X'80' in byte 0.)

4 | Zero
5-7 Element request: address of a word GETMAIN initialized with the address of the area acquired

Variable request: address of a double-word GETMAIN initialized with the address of the area acquired and the actual length allocated.

List request: address of a list area GETMAIN initialized with the addresses of the areas allocated for each requested length in the list.

8 8 Flag byte:

10 Request is for storage aligned on a page boundary.

00 Unconditional element request.

20 Conditional element request.

80 Unconditional list request.

A0 Conditional list request.

C0 Unconditional variable request.

E0 Conditional variable request.

9 | Subpool to which memory should be allocated.
Parent topic: Supervisor Services (SVCs)


SVC 5, FREEMAIN (all E and L options, VU and VC)

INPUT
  • Register 1

    Address of parameter list.

OUTPUT
  • Register 15
    Return code:
    • 0=Successful
    • 4=4=Status of memory unchanged

Parameter list, 10 bytes in length.

Bytes | Description
0-3 | Element request: length requested List request: address of a list of lengths requested (one word per request, the last word contains X'80' in byte 0.)
4 -7 | Single area request: address of a word containing the address of the area to be freed. List-request: address of a list of addresses of areas to be freed. Variable request: address of a double-word containing the address to be freed in the first word and the length to be freed in the second word.
8 | Flag byte: 10 Request is for storage aligned on a page boundary. 00 Unconditional element request. 20 Conditional element request. 80 Unconditional list request. A0 Conditional list request. C0 Unconditional variable request. E0 Conditional variable request.
9 | Subpool that the memory belongs to
Note: A conditional request with a failure should result in an abend without returning to the calling program.
Parent topic: Supervisor Services (SVCs)


SVC 6, LINK

INPUT
  • Register 0

    Number of parameters being passed

  • Register 1

    Address of list of addresses of parameters being passed

  • Register 15

    Address of parameter list

Parameter list, 12 bytes in length.

Bytes | Description
0

Flag byte:

  • 00: EP and EPLOC form of macro instruction
  • 80: DE form of macro instruction
1-3

Address of directory entry if byte 0 = 80

Address of entry point name if byte 0 = 00

4 | Indicates extended parameter list if 80
5-7 | DCB address or zero
8-11 | Contains address of routine to get control on error (ERRET parameter) if byte 4 = 80
Parent topic: Supervisor Services (SVCs)


SVC 8, LOAD

INPUT
  • Register 15

    Return code:

OUTPUT
  • Register 0

    Load address of module. The high-order bit is set to indicate the AMODE setting of the loaded module:

    0=AMODE(24)

    1=AMODE(31).

  • Register 1

    Length of program module.

  • Register 15

    Return code:

    • 0=Successful
    • 1=Module size exceeds available memory
    • 4=Module not found
    • 8=Not enough memory available
Note: The module is loaded above or below the line depending on its RMODE setting.
Parent topic: Supervisor Services (SVCs)


SVC 9, DELETE

INPUT
  • Register 0

    Address of the name of the module to be deleted.

OUTPUT
  • Register 15

    Return code:

    • 0=Successful
    • 4=Module not found in load list
    • 8=Module in load list multiple times
Parent topic: Supervisor Services (SVCs)


SVC 10, GETMAIN (R option)

INPUT
Register 0
Bits | Meaning
0-23 | Amount of memory to obtain; always below the line
23-31 | Subpool number, in the range 0 through 127, 131 and 132
OUTPUT
  • Register 1

    Address of memory obtained.

  • Register 15

    Return code:

    • 0=Memory obtained
    • 4=Memory not obtained
Parent topic: Supervisor Services (SVCs)


SVC 11, TIME

INPUT
  • Register 0

    Indicates LINKAGE parameter setting:

    • 5 LINKAGE=SYSTEM
    • Not 5 LINKAGE=SVC: Address of the area into which the microsecond elapsed time or the current time-of-day clock value is to be placed.
  • Register 1 Register 0=5

    Holds the address of a parameter list

    • Register 0 not = 5
      Contains flag bits that designate the format in which time is to be returned, whether the time to be returned is local or GMT, and whether an error routine I in use:
      • . . . 0000 32-bit unsigned binary number representing the number of elapsed timer units (A timer unit is approximately 26.04 microseconds) (equivalent to TIME macro unit parameter value of TV)
      • . . . . 0001 Elapsed time in hundredths of a second (equivalent to TIME macro unit parameter value of BIN).
      • . . . . 0010 Packed decimal digits representing elapsed time in hours, minutes, seconds, and hundredths of a second (HHMMSShh) (equivalent to TIME macro unit parameter value of DEC).
      • . . . . 0011 Microseconds, where bit 51= 1 microsecond (equivalent to TIME macro unit parameter value of MIC).
      • . . . . 0100 The current TOD clock value (equivalent to TIME macro unit parameter value of STCK).
      • . 1. . . . . . The routine specified by the ERRET operand is to get control if an error occurs.
      • 1. . . . . . . GMT values are to be returned.
OUTPUT
  • Register 0

    If LINKAGE is SVC, and time units are DEC, BIN or TV, contains the time of day in the format specified on input.

  • Register 1

    If LINKAGE is SVC, contains the date in packed decimal format in the form CCYYDDDF, where CC is the century, YY is the last two digits of the year, and DDD is the day of the year. CC is set to 0 to indicate 1900 and to 01 to indicate 2000. F is the sign bit.

Parameter list, 12 bytes in length.

Bytes | Description
0-1 | Unused
2 | Date format flag: 0=YYYYDDD (default) 1=MMDDYYYY 2=DDMMYYYY 3=YYYYMMDD
3 | Time format flag that uses the same bit settings as Register 0 when LINKAGE=SVC
4-11 | Unused
12-25 | Output area to hold the time (first two words) and date (third word)
Parent topic: Supervisor Services (SVCs)


SVC 13, ABEND

The service call used by the ABEND macro to identify an application problem.

ABEND macro expansion using SVC 13:

608          ABEND 4095,DUMP
609+         DS    0H
610+         LA    1,4095
611+         LA    0,128(0,0)
612+         SLL   0,24(0)
613+         OR    1,0
614+         SVC   13

and

615          ABEND 4094
616+         DS    0H
617+         LA    1,4094
618+         SVC   13
Parent topic: Supervisor Services (SVCs)


SVC 14, SPIE

INPUT
Register 1

Address of parameter list

OUTPUT
Register 1

If a SPIE environment is already active when you issue the SPIE macro, the address of the previous PICA (Program Interruption Control Area) is returned in register 1. If no previous SPIE environment is active, a 0 is returned in register 1.

Parameter list, 6 bytes in length.

Bytes | Description
0-3 | Address of SPIE exit routine to be enabled.
4-5 | 2-byte field where bits 0 to 15 correspond to the 16 possible program interruption types to be handled by this exit. A bit setting of 1 indicates that the exit routine is to handle the corresponding interruption type. For example, the vale x'4000' would enable the handler for interruption type 1.
Parent topic: Supervisor Services (SVCs)


SVC 26, CATALOG and LOCATE

INPUT
Register 1

Address of parameter list generated by the CAMLST macro

OUTPUT
Register 15

Return code:

0=Successful

Any other value indicates an error. For further details see the IBM manual DFSMS DFP Advanced Services SC26-4921.

Parameter list, 20 bytes in length.

Bytes Description
0

Bits Meaning

0=1 CVOL specified

1=1 CAMLST macro generated

2=1 CATALOG or CATBX specified

3=1 RECAT specified

4=1 UNCAT or UCATDX specified

5=1 Reserved

6=1 LOCATE by TTR specified

7=1 Reserved

1

Bits Meaning

0=1 Do not allocate CVOL

1=1 BLDX or CATBX specified

2=1 BLDG specified

3=1 BLDA specified

4=1 LNKX specified

5=1 DLTX or UCATDX specified

6=1 DSCB TTR specified

7=1 RLTA specified

2

Bits Meaning

0=1 DRPX specified

1=1 DELETE specified

2=1 RENAME specified

3=1 SYSZTIOT is enqueued exclusively

4=1 EMPTY specified

5=1 Reserved

6=1 Reserved

7=0 Caller supplied a CAMLST

7=1 Caller supplied a CTGPL

3

Maximum generation count for a generation data group or zeros.

4-7

Address of the data set name or TTR if byte 0, bit 6 is on.

8-11

Address of the volume serial number of the CVOL catalog, or zeros if byte 0, bit 0 is zero.

12-15

If CATALOG was specified, the address of the volume list.

The address of an 8-byte area that contains an alias for a high-level index

If LNKX was specified, the address of a 10-byte area that contains a 4-byte device code followed by the 6-byte volume serial number of the CVOL to be connected

If the LOCATE macro was coded, the address of a 265-byte work area that must start on a doubleword boundary. if the issuer of LOCATE has a non-zero protect key, then the work area must have a matching storage protect key.

16-19

Address of the DSCB TTR if CATALOG was specified and byte 1 bit 6 is set to 1.

Parent topic: Supervisor Services (SVCs)


SVC 29, SCRATCH

INPUT
Register 1

Address of parameter list generated by the CAMLST macro

OUTPUT
Register 15

Return code:

0=Successful

Any other value indicates an error. For further details see the IBM manual DFSMS DFP Advanced Services SC26-4921.

Parameter list, 20 bytes in length.

Bytes | Description
0 | x'41': the opcode for SCRATCH
1 | Bits Meaning 0=1 Dynamic deallocation by job or step termination 1=1 If the JSCBPASS bit in the job step control block is on, then password protection is bypassed. If it is off, password protection is not bypassed. 2-7 Reserved (set to zeros)
2 | Bits Meaning 0=1 Dynamic deallocation; TIOT is enqueued by the caller 1=1 & 3=0 Check purge date 1=1 & 3=1 Override purge date 2 Reserved 4=1 If caller is in supervisor state, RACF processing is bypassed. 5-7 Reserved
3 | Reserved; set to zeros
4 | Bits Meaning 0=1 SVC called by job or step termination 1=1 SVC called by reader or writer 2-7 Reserved (set to zeros)
5-7 | Address of data set name.
8-11 | Reserved; set to zeros
12-15 | Address of the volume list.
Parent topic: Supervisor Services (SVCs)


SVC 35, WTO and WTOR

This SVC displays a message on the screen (WTO and WTOR)).

INPUT
Register 1

Address of the WTO or WTOR buffer.

OUTPUT
Register 15

Return code.

The WTO buffer must be in the following format:

Bytes | Description
0 | Binary zero.
1 | Length of display message plus 4
2-3 | Multiple console routing flags (not used)
4-nn | The text to be displayed on the screen.

The WTOR buffer must be in the following format:

Bytes | Description
0 | x'80'.
1-3 | Address of reply buffer.
5-7 | Address of reply event control block (not used)
8 | Binary zero
9 | Length of reply in bytes
10 | Length of display message plus 4
11-12 | Multiple console routing flags (not used)
13-nn | The text to be displayed on the screen.
Parent topic: Supervisor Services (SVCs)


SVC 39, LINKC2

INPUT

Register 15 Address of 8-byte COBOL program name in EBCDIC

Register 0 If bits 24-31 = 0, then bits 0-23 = parameter count.

  • If bits 24-31 = x'80', then find last parameter with high bit on and set r0 to number of parameters found.
  • If bits 24-31 = x'40', then process IMS parameters as follows: If first parameter <= F'18' then set r0 to value in first parameter + 1 else if first parameter > F'18' then find last parameter with high bit on and set r0 to number of parameters found.

Register 1 Address of list of addresses of parameters being passed

OUTPUT

Register 15 Return code:

  • 0=Successful
  • 16=Failure due to invalid name, duplicate name, or invalid address.
Parent topic: Supervisor Services (SVCs)


SVC 41, IDENTIFY

INPUT

Register 1 Address of parameter list

OUTPUT

Register 15 Return code.

0=Successful

Anything else means Identify failed.

Parameter list, 8 bytes in length.

Bytes | Description
0-3 | Address of 8-byte entry name
4-7 | Address of full word address of entry
Parent topic: Supervisor Services (SVCs)


SVC 62, Detach

DETACH just removes the currently executing program from the system. There is no corresponding macro and no SVC input or output parameters.

Parent topic: Supervisor Services (SVCs)


SVC 99, DYNALLOC

INPUT
Register 1

Address of request parameter block pointer

OUTPUT
Register 15

Return code:

0=Successful

Any other value indicates an error. For further details see the IBM manual MVS Programming: Authorized Assembler Services Guide GC28-1763.

Request parameter block pointer (S99RBPTR): Holds the 31-bit address of the request parameter block). High-order bit must be set on.

Request parameter block (S99RB), 20 bytes in length.

Bytes | Description
0 | Length of request block (always 20 bytes)
1 | One-byte verb code: x'01' Data set name allocation x'02' Data set name deallocation x'03' Not supported x'04' Not supported x'05' Not supported x'06' Not supported x'07' DD name allocation
2-3 | 2-byte flag field
4-5 | 2-byte error code field
6-7 | 2-byte information code field
8-9 | Address of text unit parameter list
12-15 | Address of request block extension
16-19 | 4-byte flag field

Text unit parameter list (S99TUPL): array of 31-bit addresses with each address pointing to one text unit. Last address must have high-order bit set.

Text unit (S99TUNIT): data structure containing the following fields:

Bytes | Field | Description
0-1 | Key | Contains hexadecimal code indicating which function is being requested
2-3 | Number | Number of length and parameter combinations in the text unit (the next two fields)
 | Length | The length of the following parameter field
 | Parameter | A variable-length field containing input information specific to the particular key function being requested

Request parameter block extension (S99RBX), 34 bytes in length.

Bytes | Description
0-5 | Identifier string ' S99RBX'
6 | Version number
7 | Processing options
8 | Message block subpool number
9 | Storage key
10 | Severity level
11 | Severity level
12 | Number of message blocks
13-16 | CPPL address
17-18 | Reserved
19 | Message processing reason code
20 | Message block freeing reason code
21-24 | PUTLINE or WTO return code
25-28 | Message block chain address
29-30 | Information retrieval error code
31-32 | Erroneous information retrieval key
33 | SMS reason code
Note: You should use the equates and DSECTs provided by the IBM macros IEFZB4D0 and IEFZB4D2 to construct the SVC99 parameter structures.
Parent topic: Supervisor Services (SVCs)


SVC 103, XLATE

INPUT
Register 0

Number of bytes to translate

Register 1

Bits Meaning

0=0 Convert ANSI to EBCDIC

0=1 Convert EBCDIC to ANSI

2-31 Address of first byte of area to translate

Parent topic: Supervisor Services (SVCs)


SVC 120

GETMAIN (options RU, RC, VRC and VRU), FREEMAIN (options R, RU, RC, VRC and VRU), and STORAGE

INPUT
Register 0 Number of bytes of memory to obtain or free.
Register 1 Address of memory to free (zero for GETMAIN)
Register 15
Byte | Meaning:
0 | Zero
1 | Key of memory to obtain or free (not supported)
2 | Subpool number of memory to obtain or free
3 Option byte: 00 Conditional GETMAIN

01 Conditional FREEMAIN

02 Unconditional GETMAIN

03 Unconditional FREEMAIN

04 Page boundary bit (not supported)

OUTPUT
Register 1 Address of allocated storage if GETMAIN

Register 15 Return code:

0= Memory obtained or freed

4= Memory not obtained or freed

Parent topic: Supervisor Services (SVCs)


Assembler Pseudo Operations

This section lists:

  • Fully supported pseudo operations.

    Refer to the IBM documentation for usage details

  • The pseudo operations for which only the name is supported.

    These pseudo-operations provide no functionality, but the usage does not generate errors. The compiler ignores them.

  • Supported Pseudo Operations
  • Pseudo Operations with Name Only Support
Parent topic: Assembler Reference


Supported Pseudo Operations

Enterprise Developer Assembler support includes the following pseudo operations.

Name Only Support
These operations provide no functionality, and are treated as comments when they occur in code:
  • actr
  • aeject
  • aif
  • amode
  • aread
  • aspace
Full Support
  • ago
  • anop
  • ccw
  • ccw1
  • ceject
  • chkcst
  • cnop
  • com
  • copy
  • csect
  • cxd
  • dc
  • drop
  • ds
  • dsect
  • dxd
  • eject
  • end
  • entry
  • equ
  • extrn
  • gbla
  • gblb
  • gblc
  • ictl
  • instr
  • iseq
  • lcla
  • lclb
  • lclc
  • loctr
  • ltorg
  • macro
  • mend
  • mexit
  • mhelp
  • mnote
  • opsyn
  • org
  • pop
  • print
  • punch
  • push
  • repro
  • rmode
  • rsect
  • seta
  • setaf
  • setb
  • setc
  • setcf
  • space
  • start
  • title
  • using
  • wtrn
Parent topic: Assembler Pseudo Operations


Pseudo Operations with Name Only Support

This section lists the pseudo operations where the name usage is treated as a comment, and the functionality is not supported.

  • actr
  • aeject
  • aif
  • amode
  • aread
  • aspace
Parent topic: Assembler Pseudo Operations


Configuring an Enterprise Server for Assembler Support

All Enterprise Servers

When you add an enterprise server instance using Enterprise Server Administration, configure it as follows:

  • Set the Working Mode to 32-bit.
  • Set the Server Type to Micro Focus Enterprise Server with Mainframe Subsystem Support.
  • If you want to be able to see the console daemon when you start the enterprise server, check Show Local Console.
  • For JCL-enabled enterprise servers, uncheck Create TN3270 listener.
  • For CICS-enabled enterprise servers, check Create TN3270 listener and specify a port.

JCL Support

On the Server > Properties > MSS > JES > General tab:

  • Uncheck Create TN3270 listener.
  • Specify the path to your program files as the JES Program Path and the Default Allocated Dataset Location.
  • Specify the path and filename of the catalog.dat file as the System Catalog.
  • Specify SYS1.PROCLIB for the System Procedure Library.

From the Server > Properties > MSS > JES > Initialize tab, Add an initiator, specifying a Name and Class of your choice.

CICS Support

On the Server > Properties > General tab, type the following into the Configuration Information field:
[ES-Environment]
ES_MFASM_SUPPORT=Y

On the Server > Properties > MSS > CICS tab:

  • Set the System Initialization Table to ASMIVP.
  • Check Mainframe Subsystem Support enabled.
  • In the Transaction Path and File Path fields, specify the location of your program executables.
  • In the Map Path field, specify the path to your BMS modules (.mod files). This is usually the \bin\x86\debug subdirectory under the directory containing your program executables.
  • Point the Resource Definition File Path to your resource definition (.rdf) file.
Parent topic: Assembler Reference


CICS Support Commands

Lists the CICS Support commands

The following commands are available for CICS support:

  • CICS API Calls
  • CICS SPI Calls
Parent topic: Mainframe Reference


CICS API Calls

  • ABEND
    The ABEND function is supported.
  • ADD SUBEVENT
    The ADD SUBEVENT function is not supported.
  • ADDRESS
    The ADDRESS function is supported.
  • ADDRESS SET
    The ADDRESS SET function is supported.
  • ALLOCATE
    The ALLOCATE function is supported.
  • ASKTIME
    The ASKTIME function is supported.
  • ASSIGN
    The ASSIGN function is supported.
  • BIF DEEDIT
    The BIF DEEDIT function is supported.
  • BIF DIGEST
    The BIF DIGEST function is not supported.
  • BUILD ATTACH
    The BUILD ATTACH function is not supported.
  • CANCEL
    The CANCEL function is supported.
  • CHANGE PASSWORD
    The CHANGE PASSWORD function is not supported.
  • CHANGE PHRASE
    The CHANGE PHRASE function is supported.
  • CHECK ACQACTIVITY
    The CHECK ACQACTIVITY function is not supported.
  • CHECK ACQPROCESS
    The CHECK ACQPROCESS function is not supported.
  • CHECK ACTIVITY
    The CHECK ACTIVITY function is not supported.
  • CHECK TIMER
    The CHECK TIMER function is not supported.
  • CONNECT PROCESS
    The CONNECT PROCESS function is supported.
  • CONVERSE
    The CONVERSE function is supported.
  • CONVERTTIME
    The CONVERTTIME function is supported.
  • DEFINE ACTIVITY
    The DEFINE ACTIVITY function is not supported.
  • DEFINE COMPOSITE EVENT
    The DEFINE COMPOSITE EVENT function is not supported.
  • DEFINE COUNTER
    The DEFINE COUNTER function is not supported.
  • DEFINE DCOUNTER
    The DEFINE DCOUNTER function is not supported.
  • DEFINE INPUT EVENT
    The DEFINE INPUT EVENT function is not supported.
  • DEFINE PROCESS
    The DEFINE PROCESS function is not supported.
  • DEFINE TIMER
    The DEFINE TIMER function is not supported.
  • DELAY
    The DELAY function is supported.
  • DELETE
    The DELETE function is supported.
  • DELETE ACTIVITY
    The DELETE ACTIVITY function is not supported.
  • DELETE CONTAINER
    The DELETE CONTAINER function is supported.
  • DELETE COUNTER
    The DELETE COUNTER function is not supported.
  • DELETE DCOUNTER
    The DELETE DCOUNTER function is not supported.
  • DELETE EVENT
    The DELETE EVENT function is not supported.
  • DELETE RIDFLD
    The DELETE RIDFLD function is supported.
  • DELETE TIMER
    The DELETE TIMER function is not supported.
  • DELETEQ
    The DELETEQ function is supported.
  • DELETEQ TD
    The DELETEQ TD function is supported.
  • DELETEQ TS
    The DELETEQ TS function is supported.
  • DEQ
    The DEQ function is supported.
  • DOCUMENT CREATE
    The DOCUMENT CREATE function is supported.
  • DOCUMENT DELETE
    The DOCUMENT DELETE function is supported.
  • DOCUMENT INSERT
    The DOCUMENT INSERT function is supported.
  • DOCUMENT RETRIEVE
    The DOCUMENT RETRIEVE function is supported.
  • DOCUMENT SET
    The DOCUMENT SET function is supported.
  • DUMP
    The DUMP function is supported.
  • DUMP SYSTEM
    The DUMP SYSTEM function is supported.
  • DUMP TRANSACTION
    The DUMP TRANSACTION function is supported.
  • ENDBR
    The ENDBR function is supported.
  • ENDBROWSE ACTIVITY
    The ENDBROWSE ACTIVITY function is not supported.
  • ENDBROWSE CONTAINER
    The ENDBROWSE CONTAINER function is supported.
  • ENDBROWSE EVENT
    The ENDBROWSE EVENT function is not supported.
  • ENDBROWSE PROCESS
    The ENDBROWSE PROCESS function is not supported.
  • ENQ
    The ENQ function is supported.
  • ENTER TRACEID
    The ENTER TRACEID function is supported.
  • ENTER TRACENUM
    The ENTER TRACENUM function is supported.
  • FEPI
    The FEPI function is not supported.
  • FORCE TIMER
    The FORCE TIMER function is not supported.
  • FORMATTIME
    The FORMATTIME function is supported.
  • FREE
    The FREE function is supported.
  • FREEMAIN
    The FREEMAIN function is supported.
  • GDS ALLOCATE
    The GDS ALLOCATE function is supported.
  • GDS ASSIGN
    The GDS ASSIGN function is supported.
  • GDS CONNECT PROCESS
    The GDS CONNECT PROCESS function is supported.
  • GDS EXTRACT ATTRIBUTES
    The GDS EXTRACT ATTRIBUTES function is supported.
  • GDS EXTRACT PROCESS
    The GDS EXTRACT PROCESS function is supported.
  • GDS FREE
    The GDS FREE function is supported.
  • GDS ISSUE ABEND
    The GDS ISSUE ABEND function is supported.
  • GDS ISSUE CONFIRMATION
    The GDS ISSUE CONFIRMATION function is supported.
  • GDS ISSUE ERROR
    The GDS ISSUE ERROR function is supported.
  • GDS ISSUE PREPARE
    The GDS ISSUE PREPARE function is supported.
  • GDS ISSUE SIGNAL
    The GDS ISSUE SIGNAL function is supported.
  • GDS RECEIVE
    The GDS RECEIVE function is supported.
  • GDS SEND
    The GDS SEND function is supported.
  • GDS WAIT
    The GDS WAIT function is supported.
  • GET CONTAINER
    The GET CONTAINER function is supported.
  • GET COUNTER
    The GET COUNTER function is not supported.
  • GET DCOUNTER
    The GET DCOUNTER function is not supported.
  • GETMAIN
    The GETMAIN function is supported.
  • GETNEXT ACTIVITY
    The GETNEXT ACTIVITY function is not supported.
  • GETNEXT CONTAINER
    The GETNEXT CONTAINER function is supported.
  • GETNEXT EVENT
    The GETNEXT EVENT function is not supported.
  • GETNEXT PROCESS
    The GETNEXT PROCESS function is not supported.
  • HANDLE ABEND
    The HANDLE ABEND function is supported.
  • HANDLE AID
    The HANDLE AID function is supported.
  • HANDLE CONDITION
    The HANDLE CONDITION function is supported.
  • IGNORE CONDITION
    The IGNORE CONDITION function is supported.
  • INVOKE SERVICE
    The INVOKE SERVICE function is supported.
  • INVOKE WEBSERVICE
    The INVOKE WEBSERVICE function is supported.
  • ISSUE ABEND
    The ISSUE ABEND function is supported.
  • ISSUE ABORT
    The ISSUE ABORT function is not supported.
  • ISSUE ADD
    The ISSUE ADD function is not supported.
  • ISSUE CONFIRMATION
    The ISSUE CONFIRMATION function is supported.
  • ISSUE COPY
    The ISSUE COPY function is not supported.
  • ISSUE DISCONNECT
    The ISSUE DISCONNECT function is supported.
  • ISSUE END
    The ISSUE END function is not supported.
  • ISSUE ENDFILE
    The ISSUE ENDFILE function is not supported.
  • ISSUE ENDOUTPUT
    The ISSUE ENDOUTPUT function is not supported.
  • ISSUE EODS
    The ISSUE EODS function is not supported.
  • ISSUE ERASE
    The ISSUE ERASE function is not supported.
  • ISSUE ERASEAUP
    The ISSUE ERASEAUP function is supported.
  • ISSUE ERROR
    The ISSUE ERROR function is supported.
  • ISSUE LOAD
    The ISSUE LOAD function is not supported.
  • ISSUE NOTE
    The ISSUE NOTE function is not supported.
  • ISSUE PASS
    The ISSUE PASS function is not supported.
  • ISSUE PREPARE
    The ISSUE PREPARE function is supported.
  • ISSUE PRINT
    The ISSUE PRINT function is supported.
  • ISSUE QUERY
    The ISSUE QUERY function is not supported.
  • ISSUE RECEIVE
    The ISSUE RECEIVE function is not supported.
  • ISSUE REPLACE
    The ISSUE REPLACE function is not supported.
  • ISSUE RESET
    The ISSUE RESET function is supported.
  • ISSUE SEND
    The ISSUE SEND function is not supported.
  • ISSUE SIGNAL
    The ISSUE SIGNAL function is supported.
  • ISSUE WAIT
    The ISSUE WAIT function is not supported.
  • JOURNAL
    The JOURNAL function is supported.
  • LINK
    The LINK function is supported.
  • LINK ACQACTIVITY
    The LINK ACQACTIVITY function is not supported.
  • LINK ACQPROCESS
    The LINK ACQPROCESS function is not supported.
  • LINK ACTIVITY
    The LINK ACTIVITY function is not supported.
  • LOAD
    The LOAD function is supported.
  • MONITOR
    The MONITOR function is not supported.
  • MOVE CONTAINER
    The MOVE CONTAINER function is supported.
  • POINT
    The POINT function is not supported.
  • POP
    The POP function is supported.
  • POP HANDLE
    The POP HANDLE function is supported.
  • POST
    The POST function is supported.
  • PURGE MESSAGE
    The PURGE MESSAGE function is supported.
  • PUSH
    The PUSH function is supported.
  • PUSH HANDLE
    The PUSH HANDLE function is supported.
  • PUT CONTAINER
    The PUT CONTAINER function is supported.
  • QUERY COUNTER
    The QUERY COUNTER function is not supported.
  • QUERY DCOUNTER
    The QUERY DCOUNTER function is not supported.
  • QUERY SECURITY
    The QUERY SECURITY function is supported.
  • READ
    The READ function is supported.
  • READNEXT
    The READNEXT function is supported.
  • READPREV
    The READPREV function is supported.
  • READQ
    The READQ function is supported.
  • READQ TD
    The READQ TD function is supported.
  • READQ TS
    The READQ TS function is supported.
  • RECEIVE
    The RECEIVE function is supported.
  • RECEIVE MAP
    The RECEIVE MAP function is supported.
  • RECEIVE MAP MAPPINGDEV
    The RECEIVE MAP MAPPINGDEV function is not supported.
  • RECEIVE MAPSET
    The RECEIVE MAPSET function is supported.
  • RECEIVE PARTN
    The RECEIVE PARTN function is not supported.
  • RELEASE
    The RELEASE function is supported.
  • REMOVE SUBEVENT
    The REMOVE SUBEVENT function is not supported.
  • RESET ACQPROCESS
    The RESET ACQPROCESS function is not supported.
  • RESET ACTIVITY
    The RESET ACTIVITY function is not supported.
  • RESETBR
    The RESETBR function is supported.
  • RESUME
    The RESUME function is not supported.
  • RETRIEVE
    The RETRIEVE function is supported.
  • RETRIEVE REATTACH
    The RETRIEVE REATTACH function is not supported.
  • RETRIEVE SUBEVENT
    The RETRIEVE SUBEVENT function is not supported.
  • RETURN
    The RETURN function is supported.
  • REWIND COUNTER
    The REWIND COUNTER function is not supported.
  • REWIND DCOUNTER
    The REWIND DCOUNTER function is not supported.
  • REWRITE
    The REWRITE function is supported.
  • ROUTE
    The ROUTE function is not supported.
  • RUN
    The RUN function is not supported.
  • SEND
    The SEND function is supported.
  • SEND CONTROL
    The SEND CONTROL function is supported.
  • SEND MAP
    The SEND MAP function is supported.
  • SEND MAP MAPPINGDEV
    The SEND MAP MAPPINGDEV function is not supported.
  • SEND MAPSET
    The SEND MAPSET function is supported.
  • SEND PAGE
    The SEND PAGE function is supported.
  • SEND PARTNSET
    The SEND PARTNSET function is not supported.
  • SEND TEXT
    The SEND TEXT function is supported.
  • SEND TEXT MAPPED
    The SEND TEXT MAPPED function is supported.
  • SEND TEXT NOEDIT
    The SEND TEXT NOEDIT function is supported.
  • SIGNAL EVENT
    The SIGNAL EVENT function is not supported.
  • SIGNOFF
    The SIGNOFF function is supported.
  • SIGNON
    The SIGNON function is supported.
  • SOAPFAULT ADD
    The SOAPFAULT ADD function is supported.
  • SOAPFAULT CREATE
    The SOAPFAULT CREATE function is supported.
  • SOAPFAULT DELETE
    The SOAPFAULT DELETE function is supported.
  • SPOOLCLOSE
    The SPOOLCLOSE function is supported.
  • SPOOLCLOSE REPORT
    The SPOOLCLOSE REPORT function is supported.
  • SPOOLOPEN ESCAPE
    The SPOOLOPEN ESCAPE function is not supported.
  • SPOOLOPEN INPUT
    The SPOOLOPEN INPUT function is not supported.
  • SPOOLOPEN MAPNAME
    The SPOOLOPEN MAPNAME function is not supported.
  • SPOOLOPEN OUTPUT
    The SPOOLOPEN OUTPUT function is supported.
  • SPOOLOPEN REPORT ASA
    The SPOOLOPEN REPORT ASA function is supported.
  • SPOOLOPEN REPORT JCL
    The SPOOLOPEN REPORT JCL function is supported.
  • SPOOLOPEN REPORT MCC
    The SPOOLOPEN REPORT MCC function is supported.
  • SPOOLOPEN REPORT NOCC
    The SPOOLOPEN REPORT NOCC function is supported.
  • SPOOLOPEN REPORT SCS
    The SPOOLOPEN REPORT SCS function is not supported.
  • SPOOLOPEN REPORT T3270
    The SPOOLOPEN REPORT T3270 function is not supported.
  • SPOOLOPEN RESUME
    The SPOOLOPEN RESUME function is not supported.
  • SPOOLREAD
    The SPOOLREAD function is not supported.
  • SPOOLWRITE
    The SPOOLWRITE function is supported.
  • SPOOLWRITE MAPNAME
    The SPOOLWRITE MAPNAME function is not supported.
  • SPOOLWRITE REPORT
    The SPOOLWRITE REPORT function is supported.
  • START
    The START function is supported.
  • START ATTACH
    The START ATTACH function is not supported.
  • START BREXIT
    The START BREXIT function is supported.
  • START CHANNEL
    The START CHANNEL function is supported.
  • STARTBR
    The STARTBR function is supported.
  • STARTBROWSE ACTIVITY
    The STARTBROWSE ACTIVITY function is not supported.
  • STARTBROWSE CONTAINER
    The STARTBROWSE CONTAINER function is supported.
  • STARTBROWSE EVENT
    The STARTBROWSE EVENT function is not supported.
  • STARTBROWSE PROCESS
    The STARTBROWSE PROCESS function is not supported.
  • SUSPEND
    The SUSPEND function is supported.
  • SYNCPOINT
    The SYNCPOINT function is supported.
  • TEST EVENT
    The TEST EVENT function is not supported.
  • TRACE
    The TRACE function is not supported.
  • TRANSFORM DATATOXML
    The TRANSFORM DATATOXML function is supported.
  • TRANSFORM XMLTODATA
    The TRANSFORM XMLTODATA function is supported.
  • UNLOCK
    The UNLOCK function is supported.
  • UPDATE COUNTER
    The UPDATE COUNTER function is not supported.
  • UPDATE DCOUNTER
    The UPDATE DCOUNTER function is not supported.
  • VERIFY PASSWORD
    The VERIFY PASSWORD function is supported.
  • VERIFY PHRASE
    The VERIFY PHRASE function is supported.
  • WAIT CONVID
    The WAIT CONVID function is supported.
  • WAIT EVENT
    The WAIT EVENT function is supported.
  • WAIT EXTERNAL
    The WAIT EXTERNAL function is not supported.
  • WAIT JOURNAL
    The WAIT JOURNAL function is supported.
  • WAIT JOURNALNAME
    The WAIT JOURNALNAME function is not supported.
  • WAIT JOURNALNUM
    The WAIT JOURNALNUM function is supported.
  • WAIT SIGNAL
    The WAIT SIGNAL function is not supported.
  • WAIT TERMINAL
    The WAIT TERMINAL function is not supported.
  • WAITCICS
    The WAITCICS function is supported.
  • WEB CLOSE
    The WEB CLOSE function is supported.
  • WEB CONVERSE
    The WEB CONVERSE function is supported.
  • WEB ENDBROWSE FORMFIELD
    The WEB ENDBROWSE FORMFIELD function is supported.
  • WEB ENDBROWSE HTTPHEADER
    The WEB ENDBROWSE HTTPHEADER function is supported.
  • WEB ENDBROWSE QUERYPARM
    The WEB ENDBROWSE QUERYPARM function is supported.
  • WEB EXTRACT
    The WEB EXTRACT function is supported.
  • WEB OPEN
    The WEB OPEN function is supported.
  • WEB PARSE
    The WEB PARSE function is supported.
  • WEB READ FORMFIELD
    The WEB READ FORMFIELD function is supported.
  • WEB READ HTTPHEADER
    The WEB READ HTTPHEADER function is supported.
  • WEB READ QUERYPARM
    The WEB READ QUERYPARM function is supported.
  • WEB READNEXT FORMFIELD
    The WEB READNEXT FORMFIELD function is supported.
  • WEB READNEXT HTTPHEADER
    The WEB READNEXT HTTPHEADER function is supported.
  • WEB READNEXT QUERYPARM
    The WEB READNEXT QUERYPARM function is supported.
  • WEB RECEIVE
    The WEB RECEIVE function is supported.
  • WEB RECEIVE SESSTOKEN
    The WEB RECEIVE SESSTOKEN function is supported.
  • WEB RETRIEVE
    The WEB RETRIEVE function is supported.
  • WEB SEND
    The WEB SEND function is supported.
  • WEB SEND SESSTOKEN
    The WEB SEND SESSTOKEN function is supported.
  • WEB STARTBROWSE FORMFIELD
    The WEB STARTBROWSE FORMFIELD function is supported.
  • WEB STARTBROWSE HTTPHEADER
    The WEB STARTBROWSE HTTPHEADER function is supported.
  • WEB STARTBROWSE QUERYPARM
    The WEB STARTBROWSE QUERYPARM function is supported.
  • WEB WRITE
    The WEB WRITE function is supported.
  • WRITE
    The WRITE function is supported.
  • WRITE JOURNALNAME
    The WRITE JOURNALNAME function is not supported.
  • WRITE JOURNALNUM
    The WRITE JOURNALNUM function is supported.
  • WRITE OPERATOR
    The WRITE OPERATOR function is supported.
  • WRITEQ
    The WRITEQ function is supported.
  • WRITEQ TD
    The WRITEQ TD function is supported.
  • WRITEQ TS
    The WRITEQ TS function is supported.
  • WSACONTEXT BUILD
    The WSACONTEXT BUILD function is not supported.
  • WSACONTEXT DELETE
    The WSACONTEXT DELETE function is not supported.
  • WSACONTEXT GET
    The WSACONTEXT GET function is not supported.
  • WSAEPR CREATE
    The WSAEPR CREATE function is not supported.
  • XCTL
    The XCTL function is supported.
Parent topic: CICS Support Commands
Related reference
CWS API Calls


ABEND

The ABEND function is supported.

Operand | Support
ABCODE (data-value) | Full
CANCEL | Full
NODUMP | Full
Parent topic: CICS API Calls


ADD SUBEVENT

The ADD SUBEVENT function is not supported.

Parent topic: CICS API Calls


ADDRESS

The ADDRESS function is supported.

Operand | Support
ACEE (ptr-ref) | Full
COMMAREA (ptr-ref) | Full
CSA (ptr-ref) | Partial: returns a NULL pointer
CWA (ptr-ref) | Full
EIB (ptr-ref) | Full
TCTUA (ptr-ref) | Full
TWA (ptr-ref) | Full
Parent topic: CICS API Calls


ADDRESS SET

The ADDRESS SET function is supported.

Operand | Support
SET (ptr-ref) | Full
USING (ptr-ref) | Full
Parent topic: CICS API Calls


ALLOCATE

The ALLOCATE function is supported.

Operand | Support
NOQUEUE | Full
NOSUSPEND | Full
PARTNER (data-value) | Validated
PROFILE (data-value) | Validated
SESSION (data-value) | Validated
STATE (cvda) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


ASKTIME

The ASKTIME function is supported.

Operand | Support
ABSTIME (data-area) | Full
Parent topic: CICS API Calls


ASSIGN

The ASSIGN function is supported.

Operand | Support
ABCODE (data-area) | Full
ABDUMP (data-area) | Partial: returns x"00" meaning "No dump has been produced"
ABPROGRAM (data-area) | Partial: returns x"00" meaning "Indeterminable"
ACTIVITY (data-area) | Validated
ACTIVITYID (data-area) | Validated
ALTSCRNHT (data-area) | Full
ALTSCRNWD (data-area) | Full
APLKYBD (data-area) | Partial: returns x"00" meaning "No"
APLTEXT (data-area) | Partial: returns x"00" meaning "No"
APPLID (data-area) | Full
ASRAINTRPT (data-area) | Partial: returns x"00"
ASRAKEY (data-area) | Validated
ASRAPSW (data-area) | Partial: returns x"00"
ASRAREGS (data-area) | Partial: returns x"00"
ASRASPC (data-area) | Validated
ASRASTG (data-area) | Validated
BRIDGE (data-area) | Full
BTRANS (data-area) | Partial: returns x"00" meaning "No"
CHANNEL (data-area) | Full
CMDSEC (data-area) | Partial: returns Blank meaning "No"
COLOR (data-area) | Full
CWALENG (data-area) | Full
DEFSCRNHT (data-area) | Full
DEFSCRNWD (data-area) | Full
DELIMITER (data-area) | Partial: returns x"00"
DESTCOUNT (data-area) | Partial: returns x"0000"
DESTID (data-area) | Partial: INVREQ occurs
DESTIDLENG (data-area) | Partial: INVREQ occurs
DS3270 (data-area) | Partial: returns x"00" meaning "No"
DSSCS (data-area) | Partial: returns x"00" meaning "No"
EWASUPP (data-area) | Full
EXTDS (data-area) | Full
FACILITY (data-area) | Full
FCI (data-area) | Full
GCHARS (data-area) | Full
GCODES (data-area) | Full
GMMI (data-area) | Full
HILIGHT (data-area) | Full
INITPARM (ptr-ref) | Partial: returns x"00" meaning "No parameters"
INITPARMLEN (data-area) | Partial: returns x"00" meaning "No parameter"
INPARTN (data-area) | Partial: returns spaces
INVOKINGPROG (data-area) | Full
KATAKANA (data-area) | Partial: returns x"00" meaning "No"
LANGINUSE (data-area) | Validated
LDCMNEM (data-area) | Partial: returns x"00"
LDCNUM (data-area) | Partial: returns x"00"
MAPCOLUMN (data-area) | Full
MAPHEIGHT (data-area) | Full
MAPLINE (data-area) | Full
MAPWIDTH (data-area) | Full
MSRCONTROL (data-area) | Partial: returns x"00" meaning "No"
NATLANGINUSE (data-area) | Partial: returns "E" meaning "English (US)"
NETNAME (data-area) | Full
NEXTTRANSID (data-area) | Full
NUMTAB (data-area) | Partial: returns x"00"
OPCLASS (data-area) | Full
OPERKEYS (data-area) | Full
OPID (data-area) | Full
OPSECURITY (data-area) | Full
ORGABCODE (data-area) | Full
OUTLINE (data-area) | Full
PAGENUM (data-area) | Full
PARTNPAGE (data-area) | Partial: returns spaces
PARTNS (data-area) | Partial: returns x"00" meaning "No"
PARTNSET (data-area) | Partial: returns spaces meaning "No application partition set"
PRINSYSID (data-area) | Full
PROCESS (data-area) | Validated
PROCESSTYPE (data-area) | Validated
PROGRAM (data-area) | Full
PS (data-area) | Full
QNAME (data-area) | Full
RESSEC (data-area) | Full
RESTART (data-area) | Partial: returns x"00" meaning "Normal Start"
RETURNPROG (data-area) | Full
SCRNHT (data-area) | Full
SCRNWD (data-area) | Full
SIGDATA (data-area) | Partial: returns spaces
SOSI (data-area) | Full
STARTCODE (data-area) | Full
STATIONID (data-area) | Partial: returns x"00"
SYSID (data-area) | Full
TASKPRIORITY (data-area) | Full
TCTUALENG (data-area) | Full
TELLERID (data-area) | Partial: returns x"00"
TERMCODE (data-area) | Full
TERMPRIORITY (data-area) | Full
TEXTKYBD (data-area) | Partial: returns x"00" meaning "No"
TEXTPRINT (data-area) | Partial: returns x"00" meaning "No"
TRANPRIORITY (data-area) | Full
TWALENG (data-area) | Full
UNATTEND (data-area) | Full
USERID (data-area) | Full
USERNAME (data-area) | Partial: returns spaces
USERPRIORITY (data-area) | Full
VALIDATION (data-area) | Partial: returns x"00" meaning "No"
Parent topic: CICS API Calls


BIF DEEDIT

The BIF DEEDIT function is supported.

Operand | Support
FIELD (data-area) | Full
LENGTH (data-value) | Full
Parent topic: CICS API Calls


BIF DIGEST

The BIF DIGEST function is not supported.

Parent topic: CICS API Calls


BUILD ATTACH

The BUILD ATTACH function is not supported.

Operand | Support
ATTACHID (data-value) | Recognized
DATASTR (data-area) | Recognized
IUTYPE (data-area) | Recognized
PROCESS (data-value) | Recognized
QUEUE (data-value) | Recognized
RECFM (data-area) | Recognized
RESOURCE (data-value) | Recognized
RPROCESS (data-value) | Recognized
RRESOURCE (data-value) | Recognized
Parent topic: CICS API Calls


CANCEL

The CANCEL function is supported.

Operand | Support
REQID (data-value) | Full
SYSID (data-value) | Full
TRANSID (data-value) | Full
Parent topic: CICS API Calls


CHANGE PASSWORD

The CHANGE PASSWORD function is not supported.

Operand | Support
ESMREASON (data-area) | Recognized
ESMRESP (data-area) | Recognized
NEWPASSWORD (data-value) | Recognized
PASSWORD (data-value) | Recognized
USERID (data-value) | Recognized
Parent topic: CICS API Calls


CHANGE PHRASE

The CHANGE PHRASE function is supported.

Operand | Support
ESMREASON (data-area) | Full
ESMRESP (data-area) | Full
NEWPHRASE (data-area) | Full
NEWPHRASELEN (data-value) | Full
PHRASE (data-area) | Full
PHRASELEN (data-value) | Full
USERID (data-value) | Full
Parent topic: CICS API Calls


CHECK ACQACTIVITY

The CHECK ACQACTIVITY function is not supported.

Parent topic: CICS API Calls


CHECK ACQPROCESS

The CHECK ACQPROCESS function is not supported.

Parent topic: CICS API Calls


CHECK ACTIVITY

The CHECK ACTIVITY function is not supported.

Parent topic: CICS API Calls


CHECK TIMER

The CHECK TIMER function is not supported.

Parent topic: CICS API Calls


CONNECT PROCESS

The CONNECT PROCESS function is supported.

Operand | Support
CONVID (data-value) | Full
PARTNER | Validated
PIPLENGTH (data-value) | Full
PIPLIST (data-area) | Full
PROCLENGTH (data-value) | Full
PROCNAME (data-area) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
SYNCLEVEL (data-value) | Full
Parent topic: CICS API Calls


CONVERSE

The CONVERSE function is supported.

Operand | Support
ALTERNATE | Full
ASIS | Full
CONVID (data-value) | Full
CTLCHAR (data-value) | Full
DEFAULT | Full
DEFRESP | Validated
DEST (data-value) | Validated
ERASE | Full
FMH | Full
FROM (data-area) | Full
FROMFLENGTH (data-value) | Full
FROMLENGTH (data-value) | Full
INTO (data-area) | Full
MAXFLENGTH (data-value) | Full
MAXLENGTH (data-value) | Full
NOTRUNCATE | Full
SESSION (data-value) | Full
SET (ptr-ref) | Full
STATE (cvda) | Full
STRFIELD | Full
TOFLENGTH (data-area) | Full
TOLENGTH (data-area) | Full
Parent topic: CICS API Calls


CONVERTTIME

The CONVERTTIME function is supported.

Operand | Support
ABSTIME (data-area) | Full
ASKTIME (data-area) | Full
DATESTRING (data-area) | Full
Parent topic: CICS API Calls


DEFINE ACTIVITY

The DEFINE ACTIVITY function is not supported.

Parent topic: CICS API Calls


DEFINE COMPOSITE EVENT

The DEFINE COMPOSITE EVENT function is not supported.

Parent topic: CICS API Calls


DEFINE COUNTER

The DEFINE COUNTER function is not supported.

Operand | Support
COUNTER (data-value) | Recognized
MAXIMUM (data-value) | Recognized
MINIMUM (data-value) | Recognized
POOL (data-value) | Recognized
VALUE (data-value) | Recognized
Parent topic: CICS API Calls


DEFINE DCOUNTER

The DEFINE DCOUNTER function is not supported.

Operand | Support
DCOUNTER (data-value) | Recognized
MAXIMUM (data-area) | Recognized
MINIMUM (data-area) | Recognized
POOL (data-value) | Recognized
VALUE (data-area) | Recognized
Parent topic: CICS API Calls


DEFINE INPUT EVENT

The DEFINE INPUT EVENT function is not supported.

Parent topic: CICS API Calls


DEFINE PROCESS

The DEFINE PROCESS function is not supported.

Parent topic: CICS API Calls


DEFINE TIMER

The DEFINE TIMER function is not supported.

Parent topic: CICS API Calls


DELAY

The DELAY function is supported.

Operand | Support
FOR | Full
HOURS (data-value) | Full
INTERVAL (data-value) | Full
MINUTES (data-value) | Full
REQID (data-value) | Full
SECONDS (data-value) | Full
TIME (data-value) | Full
UNTIL | Full
Parent topic: CICS API Calls


DELETE

The DELETE function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
GENERIC | Full
KEYLENGTH (data-value) | Full
NUMREC (data-area) | Full
RBA | Validated
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Full
TOKEN (data-area) | Full
Parent topic: CICS API Calls


DELETE ACTIVITY

The DELETE ACTIVITY function is not supported.

Parent topic: CICS API Calls


DELETE CONTAINER

The DELETE CONTAINER function is supported.

Operand | Support
CHANNEL (data-value) | Full
CONTAINER (data-value) | Full
Parent topic: CICS API Calls


DELETE COUNTER

The DELETE COUNTER function is not supported.

Operand | Support
COUNTER (data-value) | Recognized
POOL (data-value) | Recognized
Parent topic: CICS API Calls


DELETE DCOUNTER

The DELETE DCOUNTER function is not supported.

Operand | Support
DCOUNTER (data-value) | Recognized
POOL (data-value) | Recognized
Parent topic: CICS API Calls


DELETE EVENT

The DELETE EVENT function is not supported.

Parent topic: CICS API Calls


DELETE RIDFLD

The DELETE RIDFLD function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
GENERIC | Full
KEYLENGTH (data-value) | Full
NUMREC (data-area) | Full
RBA | Validated
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Full
TOKEN (data-area) | Validated
Parent topic: CICS API Calls


DELETE TIMER

The DELETE TIMER function is not supported.

Parent topic: CICS API Calls


DELETEQ

The DELETEQ function is supported.

Operand | Support
QNAME (data-value) | Full
QUEUE (data-value) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


DELETEQ TD

The DELETEQ TD function is supported.

Operand | Support
QUEUE (data-value) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


DELETEQ TS

The DELETEQ TS function is supported.

Operand | Support
QNAME (data-value) | Full
QUEUE (data-value) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


DEQ

The DEQ function is supported.

Operand | Support
LENGTH (data-value) | Full
LUW (cvda) | Full
MAXLIFETIME (data-value) | Full
RESOURCE (data-value) | Full
TASK (cvda) | Full
Parent topic: CICS API Calls


DOCUMENT CREATE

The DOCUMENT CREATE function is supported.

Operand | Support
BINARY (data-area) | Full
DELIMITER (data-value) | Full
DOCSIZE (data-area) | Full
DOCTOKEN (data-area) | Full
FROM (data-area) | Full
FROMDOC (data-area) | Full
HOSTCODEPAGE (data-value) | Full
LENGTH (data-value) | Full
LISTLENGTH (data-value) | Full
SYMBOLLIST (data-area) | Full
TEMPLATE (data-value) | Full
TEXT (data-area) | Full
UNESCAPED | Full
Parent topic: CICS API Calls


DOCUMENT DELETE

The DOCUMENT DELETE function is supported.

Operand | Support
DOCTOKEN (data-area) | Full
Parent topic: CICS API Calls


DOCUMENT INSERT

The DOCUMENT INSERT function is supported.

Operand | Support
AT (data-value) | Full
BINARY (data-area) | Full
BOOKMARK (data-value) | Full
DOCSIZE (data-area) | Full
DOCTOKEN (data-area) | Full
FROM (data-area) | Full
FROMDOC (data-area) | Full
HOSTCODEPAGE (data-value) | Full
LENGTH (data-value) | Full
SYMBOL (data-value) | Full
TEMPLATE (data-value) | Full
TEXT (data-area) | Full
TO (data-value) | Full
Parent topic: CICS API Calls


DOCUMENT RETRIEVE

The DOCUMENT RETRIEVE function is supported.

Operand | Support
CLNTCODEPAGE (data-value) | Full
DATAONLY | Full
DOCTOKEN (data-area) | Full
INTO (data-area) | Full
LENGTH (data-area) | Full
MAXLENGTH (data-value) | Full
Parent topic: CICS API Calls


DOCUMENT SET

The DOCUMENT SET function is supported.

Operand | Support
DELIMITER (data-value) | Full
DOCTOKEN (data-area) | Full
LENGTH (data-value) | Full
SYMBOL (data-value) | Full
SYMBOLLIST (data-area) | Full
UNESCAPED | Full
VALUE (data-area) | Full
Parent topic: CICS API Calls


DUMP

The DUMP function is supported.

Operand | Support
COMPLETE | Full
DCT | Full
DUMPCODE (data-value) | Full
FCT | Full
FLENGTH (data-value) | Full
FROM (data-area) | Full
LENGTH (data-value) | Full
PCT | Full
PPT | Full
PROGRAM | Full
SIT | Full
STORAGE | Full
TABLES | Full
TASK | Full
TCT | Full
TERMINAL | Full
Parent topic: CICS API Calls


DUMP SYSTEM

The DUMP SYSTEM function is supported.

Operand | Support
CALLER (data-value) | Full
CALLERLENGTH (data-value) | Full
DUMPCODE (data-value) | Full
DUMPID (data-area) | Full
TITLE (data-value) | Full
TITLELENGTH (data-value) | Full
Parent topic: CICS API Calls


DUMP TRANSACTION

The DUMP TRANSACTION function is supported.

Operand | Support
COMPLETE | Full
DCT | Full
DUMPCODE (data-value) | Full
DUMPID (data-area) | Full
FCT | Full
FLENGTH (data-value) | Full
FROM (data-area) | Full
LENGTH (data-value) | Full
LENGTHLIST (data-area) | Full
NUMSEGMENTS (data-area) | Full
PCT | Full
PPT | Full
PROGRAM | Full
SEGMENTLIST (data-area) | Full
SIT | Full
STORAGE | Full
TABLES | Full
TASK | Full
TCT | Full
TERMINAL | Full
TRT | Full
Parent topic: CICS API Calls


ENDBR

The ENDBR function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
REQID (data-value) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


ENDBROWSE ACTIVITY

The ENDBROWSE ACTIVITY function is not supported.

Parent topic: CICS API Calls


ENDBROWSE CONTAINER

The ENDBROWSE CONTAINER function is supported.

Operand | Support
BROWSETOKEN (data-area) | Full
Parent topic: CICS API Calls


ENDBROWSE EVENT

The ENDBROWSE EVENT function is not supported.

Parent topic: CICS API Calls


ENDBROWSE PROCESS

The ENDBROWSE PROCESS function is not supported.

Parent topic: CICS API Calls


ENQ

The ENQ function is supported.

Operand | Support
LENGTH (data-value) | Full
LUW (cvda) | Full
MAXLIFETIME (data-value) | Full
NOSUSPEND | Full
RESOURCE (data-value) | Full
TASK (cvda) | Full
UOW (cvda) | Full
Parent topic: CICS API Calls


ENTER TRACEID

The ENTER TRACEID function is supported.

Operand | Support
ACCOUNT (data-area) | Validated
ENTRYNAME (data-value) | Validated
FROM (data-area) | Full
MONITOR | Validated
PERFORM | Validated
RESOURCE (data-value) | Validated
TRACEID (data-value) | Full
Parent topic: CICS API Calls


ENTER TRACENUM

The ENTER TRACENUM function is supported.

Operand | Support
EXCEPTION | Full
FROM (data-area) | Full
FROMLENGTH (data-value) | Full
RESOURCE (data-value) | Full
TRACENUM (data-value) | Full
Parent topic: CICS API Calls


FEPI

The FEPI function is not supported.

Parent topic: CICS API Calls


FORCE TIMER

The FORCE TIMER function is not supported.

Parent topic: CICS API Calls


FORMATTIME

The FORMATTIME function is supported.

Operand | Support
ABSTIME (data-area) | Full
DATE (data-area) | Full
DATEFORM (data-area) | Full
DATESEP (data-value) | Full
DATESTRING (data-area) | Full
DAYCOUNT (data-area) | Full
DAYOFMONTH (data-area) | Full
DAYOFWEEK (data-area) | Full
DDMMYY (data-area) | Full
DDMMYYYY (data-area) | Full
FULLDATE (data-area) | Full
MILLISECONDS (data-area) | Full
MMDDYY (data-area) | Full
MMDDYYYY (data-area) | Full
MONTHOFYEAR (data-area) | Full
RFC1123 (cvda) | Full
RFC3339 (cvda) | Full
STRINGFORMAT (data-value) | Full
TIME (data-area) | Full
TIMESEP (data-value) | Full
YEAR (data-area) | Full
YYDDD (data-area) | Full
YYDDMM (data-area) | Full
YYMMDD (data-area) | Full
YYYYDDD (data-area) | Full
YYYYDDMM (data-area) | Full
YYYYMMDD (data-area) | Full
Parent topic: CICS API Calls


FREE

The FREE function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


FREEMAIN

The FREEMAIN function is supported.

Operand | Support
DATA (data-area) | Full
DATAPOINTER (ptr-ref) | Full
Parent topic: CICS API Calls


GDS ALLOCATE

The GDS ALLOCATE function is supported.

Operand | Support
CONVID (data-area) | Full
MODENAME (data-value) | Validated
NOQUEUE | Full
PARTNER (data-value) | Validated
RETCODE (data-area) | Full
STATE (cvda) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


GDS ASSIGN

The GDS ASSIGN function is supported.

Operand | Support
PRINCONVID (data-area) | Full
PRINSYSID (data-area) | Full
RETCODE (data-area) | Full
Parent topic: CICS API Calls


GDS CONNECT PROCESS

The GDS CONNECT PROCESS function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
PARTNER (data-value) | Validated
PIPLENGTH (data-value) | Full
PIPLIST (data-area) | Full
PROCLENGTH (data-value) | Full
PROCNAME (data-area) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
SYNCLEVEL (data-value) | Full
Parent topic: CICS API Calls


GDS EXTRACT ATTRIBUTES

The GDS EXTRACT ATTRIBUTES function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS EXTRACT PROCESS

The GDS EXTRACT PROCESS function is supported.

Operand | Support
CONVID (data-area) | Full
MAXPROCLEN (data-area) | Full
PIPLENGTH (data-area) | Full
PIPLIST (ptr-ref) | Full
PROCLENGTH (data-area) | Full
PROCNAME (data-area) | Full
RETCODE (data-area) | Full
SYNCLEVEL (data-area) | Full
Parent topic: CICS API Calls


GDS FREE

The GDS FREE function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS ISSUE ABEND

The GDS ISSUE ABEND function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS ISSUE CONFIRMATION

The GDS ISSUE CONFIRMATION function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS ISSUE ERROR

The GDS ISSUE ERROR function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS ISSUE PREPARE

The GDS ISSUE PREPARE function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS ISSUE SIGNAL

The GDS ISSUE SIGNAL function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS RECEIVE

The GDS RECEIVE function is supported.

Operand | Support
BUFFER | Full
CONVDATA (data-area) | Full
CONVID (data-area) | Full
FLENGTH (data-area) | Full
INTO (data-area) | Full
LLID | Full
MAXFLENGTH (data-value) | Full
RETCODE (data-area) | Full
SET (ptr-ref) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GDS SEND

The GDS SEND function is supported.

Operand | Support
CONFIRM | Full
CONVDATA (data-area) | Full
CONVID (data-value) | Full
FLENGTH (data-value) | Full
FROM (data-area) | Full
INVITE | Full
LAST | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
WAIT | Full
Parent topic: CICS API Calls


GDS WAIT

The GDS WAIT function is supported.

Operand | Support
CONVDATA (data-area) | Full
CONVID (data-value) | Full
RETCODE (data-area) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


GET CONTAINER

The GET CONTAINER function is supported.

Operand | Support
ACQACTIVITY | Validated
ACQPROCESS | Validated
ACTIVITY (data-value) | Validated
CCSID (data-area) | Full
CHANNEL (data-value) | Full
CONTAINER (data-value) | Full
CONVERTST (data-value) | Full
FLENGTH (data-area) | Full
INTO (data-area) | Full
INTOCCSID (data-area) | Full
INTOCODEPAGE (data-value) | Full
NOCONVERT (cvda) | Full
NODATA | Full
PROCESS | Validated
SET (ptr-ref) | Full
Parent topic: CICS API Calls


GET COUNTER

The GET COUNTER function is not supported.

Operand | Support
COMPAREMAX (data-value) | Recognized
COMPAREMIN (data-value) | Recognized
COUNTER (data-value) | Recognized
INCREMENT (data-value) | Recognized
POOL (data-value) | Recognized
REDUCE | Recognized
VALUE (data-area) | Recognized
WRAP | Recognized
Parent topic: CICS API Calls


GET DCOUNTER

The GET DCOUNTER function is not supported.

Operand | Support
COMPAREMAX (data-area) | Recognized
COMPAREMIN (data-area) | Recognized
DCOUNTER (data-value) | Recognized
INCREMENT (data-area) | Recognized
POOL (data-value) | Recognized
REDUCE | Recognized
VALUE (data-area) | Recognized
WRAP | Recognized
Parent topic: CICS API Calls


GETMAIN

The GETMAIN function is supported.

Operand | Support
BELOW | Validated
CICSDATAKEY | Validated
FLENGTH (data-value) | Full
INITIMG (data-value) | Full
LENGTH (data-value) | Full
NOSUSPEND | Full
SET (ptr-ref) | Full
SHARED | Full
USERDATAKEY | Validated
Parent topic: CICS API Calls


GETNEXT ACTIVITY

The GETNEXT ACTIVITY function is not supported.

Parent topic: CICS API Calls


GETNEXT CONTAINER

The GETNEXT CONTAINER function is supported.

Operand | Support
BROWSETOKEN (data-area) | Full
CONTAINER (data-area) | Full
Parent topic: CICS API Calls


GETNEXT EVENT

The GETNEXT EVENT function is not supported.

Parent topic: CICS API Calls


GETNEXT PROCESS

The GETNEXT PROCESS function is not supported.

Parent topic: CICS API Calls


HANDLE ABEND

The HANDLE ABEND function is supported.

Operand | Support
CANCEL | Full
LABEL (label) | Full
PROGRAM (data-value) | Full
RESET | Full
Parent topic: CICS API Calls


HANDLE AID

The HANDLE AID function is supported.

Parent topic: CICS API Calls


HANDLE CONDITION

The HANDLE CONDITION function is supported.

Parent topic: CICS API Calls


IGNORE CONDITION

The IGNORE CONDITION function is supported.

Parent topic: CICS API Calls


INVOKE SERVICE

The INVOKE SERVICE function is supported.

Operand | Support
CHANNEL (data-value) | Full
OPERATION (data-value) | Full
SCOPE (data-value) | Validated
SCOPELEN (data-value) | Validated
SERVICE (data-value) | Full
URI (data-value) | Full
URIMAP (data-value) | Full
WEBSERVICE (data-value) | Full
Parent topic: CICS API Calls


INVOKE WEBSERVICE

The INVOKE WEBSERVICE function is supported.

Operand | Support
CHANNEL (data-value) | Full
OPERATION (data-value) | Full
SCOPE (data-value) | Validated
SCOPELEN (data-value) | Validated
SERVICE (data-value) | Full
URI (data-value) | Full
URIMAP (data-value) | Full
WEBSERVICE (data-value) | Full
Parent topic: CICS API Calls


ISSUE ABEND

The ISSUE ABEND function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


ISSUE ABORT

The ISSUE ABORT function is not supported.

Parent topic: CICS API Calls


ISSUE ADD

The ISSUE ADD function is not supported.

Parent topic: CICS API Calls


ISSUE CONFIRMATION

The ISSUE CONFIRMATION function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


ISSUE COPY

The ISSUE COPY function is not supported.

Operand | Support
CTLCHAR (data-value) | Recognized
TERMID (data-value) | Recognized
WAIT | Recognized
Parent topic: CICS API Calls


ISSUE DISCONNECT

The ISSUE DISCONNECT function is supported.

Parent topic: CICS API Calls


ISSUE END

The ISSUE END function is not supported.

Parent topic: CICS API Calls


ISSUE ENDFILE

The ISSUE ENDFILE function is not supported.

Parent topic: CICS API Calls


ISSUE ENDOUTPUT

The ISSUE ENDOUTPUT function is not supported.

Parent topic: CICS API Calls


ISSUE EODS

The ISSUE EODS function is not supported.

Parent topic: CICS API Calls


ISSUE ERASE

The ISSUE ERASE function is not supported.

Parent topic: CICS API Calls


ISSUE ERASEAUP

The ISSUE ERASEAUP function is supported.

Operand | Support
WAIT | Full
Parent topic: CICS API Calls


ISSUE ERROR

The ISSUE ERROR function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


ISSUE LOAD

The ISSUE LOAD function is not supported.

Parent topic: CICS API Calls


ISSUE NOTE

The ISSUE NOTE function is not supported.

Parent topic: CICS API Calls


ISSUE PASS

The ISSUE PASS function is not supported.

Operand | Support
FROM (data-area) | Recognized
LENGTH (data-value) | Recognized
LOGMODE (data-value) | Recognized
LOGONLOGMODE | Recognized
LUNAME (data-value) | Recognized
NOQUIESCE | Recognized
Parent topic: CICS API Calls


ISSUE PREPARE

The ISSUE PREPARE function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


ISSUE PRINT

The ISSUE PRINT function is supported.

Parent topic: CICS API Calls


ISSUE QUERY

The ISSUE QUERY function is not supported.

Parent topic: CICS API Calls


ISSUE RECEIVE

The ISSUE RECEIVE function is not supported.

Parent topic: CICS API Calls


ISSUE REPLACE

The ISSUE REPLACE function is not supported.

Parent topic: CICS API Calls


ISSUE RESET

The ISSUE RESET function is supported.

Parent topic: CICS API Calls


ISSUE SEND

The ISSUE SEND function is not supported.

Parent topic: CICS API Calls


ISSUE SIGNAL

The ISSUE SIGNAL function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


ISSUE WAIT

The ISSUE WAIT function is not supported.

Parent topic: CICS API Calls


JOURNAL

The JOURNAL function is supported.

Operand | Support
FROM (data-area) | Full
JFILEID (data-value) | Full
JOURNALNUM (data-value) | Full
JTYPEID (data-value) | Full
LENGTH (data-value) | Full
NOSUSPEND | Full
PFXLENG (data-value) | Full
PREFIX (data-area) | Full
REQID (data-area) | Full
STARTIO | Full
WAIT | Full
Parent topic: CICS API Calls


LINK

The LINK function is supported.

Operand | Support
CHANNEL (data-value) | Full
COMMAREA (data-area) | Full
DATALENGTH (data-value) | Full
INPUTMSG (data-area) | Full
INPUTMSGLEN (data-value) | Full
LENGTH (data-value) | Full
PROGRAM (data-value) | Full
SYNCONRETURN | Full
SYSID (data-value) | Full
TRANSID (data-value) | Full
Parent topic: CICS API Calls


LINK ACQACTIVITY

The LINK ACQACTIVITY function is not supported.

Parent topic: CICS API Calls


LINK ACQPROCESS

The LINK ACQPROCESS function is not supported.

Parent topic: CICS API Calls


LINK ACTIVITY

The LINK ACTIVITY function is not supported.

Parent topic: CICS API Calls


LOAD

The LOAD function is supported.

Operand | Support
ENTRY (ptr-ref) | Full
FLENGTH (data-area) | Full
HOLD | Full
LENGTH (data-area) | Full
PROGRAM (data-value) | Full
SET (ptr-ref) | Full
Parent topic: CICS API Calls


MONITOR

The MONITOR function is not supported.

Operand | Support
DATA1 (data-area) | Recognized
DATA2 (data-area) | Recognized
ENTRYNAME (data-area) | Recognized
POINT (data-value) | Recognized
Parent topic: CICS API Calls


MOVE CONTAINER

The MOVE CONTAINER function is supported.

Operand | Support
AS (data-value) | Full
CHANNEL (data-value) | Full
CONTAINER (data-value) | Full
TOCHANNEL (data-value) | Full
Parent topic: CICS API Calls


POINT

The POINT function is not supported.

Parent topic: CICS API Calls


POP

The POP function is supported.

Parent topic: CICS API Calls


POP HANDLE

The POP HANDLE function is supported.

Parent topic: CICS API Calls


POST

The POST function is supported.

Operand | Support
AFTER | Full
AT | Full
HOURS (data-value) | Full
INTERVAL (data-value) | Full
MINUTES (data-value) | Full
REQID (data-value) | Full
SECONDS (data-value) | Full
SET (ptr-ref) | Full
TIME (data-value) | Full
Parent topic: CICS API Calls


PURGE MESSAGE

The PURGE MESSAGE function is supported.

Parent topic: CICS API Calls


PUSH

The PUSH function is supported.

Parent topic: CICS API Calls


PUSH HANDLE

The PUSH HANDLE function is supported.

Parent topic: CICS API Calls


PUT CONTAINER

The PUT CONTAINER function is supported.

Operand | Support
ACQACTIVITY | Validated
ACQPROCESS | Validated
ACTIVITY (data-value) | Validated
APPEND (cvda) | Full
BIT (cvda) | Full
CHANNEL (data-value) | Full
CHAR (cvda) | Full
CONTAINER (data-value) | Full
DATATYPE (data-value) | Full
FLENGTH (data-area) | Full
FROM (data-area) | Full
FROMCCSID (data-area) | Full
FROMCODEPAGE (data-value) | Full
PROCESS | Validated
Parent topic: CICS API Calls


QUERY COUNTER

The QUERY COUNTER function is not supported.

Operand | Support
COUNTER (data-value) | Recognized
MAXIMUM (data-area) | Recognized
MINIMUM (data-area) | Recognized
POOL (data-value) | Recognized
VALUE (data-area) | Recognized
Parent topic: CICS API Calls


QUERY DCOUNTER

The QUERY DCOUNTER function is not supported.

Operand | Support
DCOUNTER (data-value) | Recognized
MAXIMUM (data-area) | Recognized
MINIMUM (data-area) | Recognized
POOL (data-value) | Recognized
VALUE (data-area) | Recognized
Parent topic: CICS API Calls


QUERY SECURITY

The QUERY SECURITY function is supported.

Operand | Support
ALTER (data-area) | Full
CONTROL (data-area) | Full
LOG (cvda) | Full
LOGMESSAGE (data-value) | Full
NOLOG (cvda) | Full
READ (data-area) | Full
RESCLASS (data-value) | Full
RESID (data-value) | Full
RESIDLENGTH (data-value) | Full
RESTYPE (data-value) | Full
UPDATE (data-area) | Full
Parent topic: CICS API Calls


READ

The READ function is supported.

Operand | Support
CONSISTENT | Validated
DATASET (data-value) | Full
DEBKEY | Validated
DEBREC | Validated
EQUAL | Full
FILE (data-value) | Full
GENERIC | Full
GTEQ | Full
INTO (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-area) | Full
NOSUSPEND | Full
RBA | Full
REPEATABLE | Validated
RIDFLD (data-area) | Full
RRN | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
TOKEN (data-area) | Full
UNCOMMITTED | Validated
UPDATE | Full
XRBA | Full
Parent topic: CICS API Calls


READNEXT

The READNEXT function is supported.

Operand | Support
CONSISTENT | Validated
DATASET (data-value) | Full
FILE (data-value) | Full
INTO (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-area) | Full
RBA | Full
REPEATABLE | Validated
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
TOKEN (data-area) | Full
UNCOMMITTED | Validated
UPDATE | Full
XRBA | Full
Parent topic: CICS API Calls


READPREV

The READPREV function is supported.

Operand | Support
CONSISTENT | Validated
DATASET (data-value) | Full
FILE (data-value) | Full
INTO (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-area) | Full
RBA | Full
REPEATABLE | Validated
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
TOKEN (data-area) | Full
UNCOMMITTED | Validated
UPDATE | Full
XRBA | Full
Parent topic: CICS API Calls


READQ

The READQ function is supported.

Operand | Support
INTO (data-area) | Full
ITEM (data-value) | Full
LENGTH (data-area) | Full
NEXT | Full
NUMITEMS (data-area) | Full
QNAME (data-value) | Full
QUEUE (data-value) | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


READQ TD

The READQ TD function is supported.

Operand | Support
INTO (data-area) | Full
LENGTH (data-area) | Full
NOSUSPEND | Full
QUEUE (data-value) | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


READQ TS

The READQ TS function is supported.

Operand | Support
INTO (data-area) | Full
ITEM (data-value) | Full
LENGTH (data-area) | Full
NEXT | Full
NUMITEMS (data-area) | Full
QNAME (data-value) | Full
QUEUE (data-value) | Full
SET (ptr-ref) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


RECEIVE

The RECEIVE function is supported.

Operand | Support
ASIS | Full
BUFFER | Full
CONVID (data-value) | Full
FLENGTH (data-area) | Full
INTO (data-area) | Full
LEAVEKB | Validated
LENGTH (data-area) | Full
MAXFLENGTH (data-value) | Full
MAXLENGTH (data-value) | Full
NOTRUNCATE | Full
SESSION (data-value) | Full
SET (ptr-ref) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


RECEIVE MAP

The RECEIVE MAP function is supported.

Operand | Support
ASIS | Full
FROM (data-area) | Full
INPARTN (data-value) | Validated
INTO (data-area) | Full
LENGTH (data-value) | Full
MAP (data-value) | Full
MAPSET (data-value) | Full
SET (ptr-ref) | Full
TERMINAL | Full
Parent topic: CICS API Calls


RECEIVE MAP MAPPINGDEV

The RECEIVE MAP MAPPINGDEV function is not supported.

Operand | Support
AID (data-area) | Recognized
CURSOR (data-value) | Recognized
FROM (data-area) | Recognized
INTO (data-area) | Recognized
LENGTH (data-value) | Recognized
MAP (data-value) | Recognized
MAPPINGDEV (data-value) | Recognized
MAPSET (data-value) | Recognized
SET (ptr-ref) | Recognized
Parent topic: CICS API Calls


RECEIVE MAPSET

The RECEIVE MAPSET function is supported.

Operand | Support
ASIS | Full
FROM (data-area) | Full
INPARTN (data-value) | Validated
INTO (data-area) | Full
LENGTH (data-value) | Full
MAP (data-value) | Full
MAPSET (data-value) | Full
SET (ptr-ref) | Full
TERMINAL | Full
Parent topic: CICS API Calls


RECEIVE PARTN

The RECEIVE PARTN function is not supported.

Operand | Support
ASIS | Recognized
INTO (data-area) | Recognized
LENGTH (data-area) | Recognized
PARTN (data-area) | Recognized
SET (ptr-ref) | Recognized
Parent topic: CICS API Calls


RELEASE

The RELEASE function is supported.

Operand | Support
PROGRAM (data-value) | Full
Parent topic: CICS API Calls


REMOVE SUBEVENT

The REMOVE SUBEVENT function is not supported.

Parent topic: CICS API Calls


RESET ACQPROCESS

The RESET ACQPROCESS function is not supported.

Parent topic: CICS API Calls


RESET ACTIVITY

The RESET ACTIVITY function is not supported.

Parent topic: CICS API Calls


RESETBR

The RESETBR function is supported.

Operand | Support
DATASET (data-value) | Full
EQUAL | Full
FILE (data-value) | Full
GENERIC | Full
GTEQ | Full
KEYLENGTH (data-value) | Full
RBA | Full
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Full
XRBA | Full
Parent topic: CICS API Calls


RESUME

The RESUME function is not supported.

Parent topic: CICS API Calls


RETRIEVE

The RETRIEVE function is supported.

Operand | Support
INTO (data-area) | Full
LENGTH (data-area) | Full
QUEUE (data-area) | Full
RTERMID (data-area) | Full
RTRANSID (data-area) | Full
SET (ptr-ref) | Full
WAIT | Full
Parent topic: CICS API Calls


RETRIEVE REATTACH

The RETRIEVE REATTACH function is not supported.

Parent topic: CICS API Calls


RETRIEVE SUBEVENT

The RETRIEVE SUBEVENT function is not supported.

Parent topic: CICS API Calls


RETURN

The RETURN function is supported.

Operand | Support
CHANNEL (data-value) | Full
COMMAREA (data-area) | Full
ENDACTIVITY | Validated
IMMEDIATE | Full
INPUTMSG (data-area) | Full
INPUTMSGLEN (data-value) | Full
LENGTH (data-value) | Full
TRANSID (data-value) | Full
Parent topic: CICS API Calls


REWIND COUNTER

The REWIND COUNTER function is not supported.

Operand | Support
COUNTER (data-value) | Recognized
INCREMENT (data-value) | Recognized
POOL (data-value) | Recognized
Parent topic: CICS API Calls


REWIND DCOUNTER

The REWIND DCOUNTER function is not supported.

Operand | Support
DCOUNTER (data-value) | Recognized
INCREMENT (data-area) | Recognized
POOL (data-value) | Recognized
Parent topic: CICS API Calls


REWRITE

The REWRITE function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
FROM (data-area) | Full
LENGTH (data-value) | Full
SYSID (data-value) | Full
TOKEN (data-area) | Full
Parent topic: CICS API Calls


ROUTE

The ROUTE function is not supported.

Operand | Support
AFTER | Recognized
AT | Recognized
ERRTERM (data-value) | Recognized
HOURS (data-value) | Recognized
INTERVAL (data-value) | Recognized
LDC (data-value) | Recognized
LIST (data-area) | Recognized
MINUTES (data-value) | Recognized
NLEOM | Recognized
OPCLASS (data-area) | Recognized
REQID (data-value) | Recognized
SECONDS (data-value) | Recognized
TIME (data-value) | Recognized
TITLE (data-area) | Recognized
Parent topic: CICS API Calls


RUN

The RUN function is not supported.

Parent topic: CICS API Calls


SEND

The SEND function is supported.

Operand | Support
ALTERNATE | Full
ATTACHID (data-value) | Validated
CNOTCOMPL | Validated
CONFIRM | Full
CONVID (data-value) | Full
CTLCHAR (data-value) | Full
DEFAULT | Full
DEFRESP | Validated
DEST (data-value) | Validated
ERASE | Full
FLENGTH (data-value) | Full
FMH | Full
FROM (data-area) | Full
INVITE | Full
LAST | Full
LEAVEKB | Validated
LENGTH (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
STRFIELD | Full
WAIT | Full
Parent topic: CICS API Calls


SEND CONTROL

The SEND CONTROL function is supported.

Operand | Support
ACCUM | Full
ACTPARTN (data-value) | Validated
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Full
DEFAULT | Full
ERASE | Full
ERASEAUP | Full
FORMFEED | Full
FREEKB | Full
FRSET | Full
HONEOM | Full
L40 | Full
L64 | Full
L80 | Full
LAST | Full
LDC (data-value) | Validated
MSR (data-value) | Validated
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Full
REQID (data-value) | Validated
SET (ptr-ref) | Full
TERMINAL | Full
WAIT | Full
Parent topic: CICS API Calls


SEND MAP

The SEND MAP function is supported.

Operand | Support
ACCUM | Full
ACTPARTN (data-value) | Validated
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Full
DATAONLY | Full
DEFAULT | Full
ERASE | Full
ERASEAUP | Full
FMHPARM | Validated
FORMFEED | Full
FREEKB | Full
FROM (data-area) | Full
FRSET | Full
HONEOM | Full
L40 | Full
L64 | Full
L80 | Full
LAST | Full
LDC (data-value) | Validated
LENGTH (data-value) | Full
MAP (data-value) | Full
MAPONLY | Full
MAPSET (data-value) | Full
MSR (data-value) | Validated
NLEOM | Full
NOFLUSH | Validated
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Full
REQID (data-value) | Validated
SET (ptr-ref) | Full
TERMINAL | Full
WAIT | Full
Parent topic: CICS API Calls


SEND MAP MAPPINGDEV

The SEND MAP MAPPINGDEV function is not supported.

Operand | Support
ALARM | Recognized
CURSOR (data-value) | Recognized
DATAONLY | Recognized
ERASE | Recognized
ERASEAUP | Recognized
FORMFEED | Recognized
FREEKB | Recognized
FROM (data-area) | Recognized
FRSET | Recognized
LENGTH (data-value) | Recognized
MAP (data-value) | Recognized
MAPONLY | Recognized
MAPPINGDEV (data-value) | Recognized
MAPSET (data-value) | Recognized
PRINT | Recognized
SET (ptr-ref) | Recognized
Parent topic: CICS API Calls


SEND MAPSET

The SEND MAPSET function is supported.

Operand | Support
ACCUM | Full
ACTPARTN (data-value) | Validated
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Full
DATAONLY | Full
DEFAULT | Full
ERASE | Full
ERASEAUP | Full
FMHPARM | Validated
FORMFEED | Full
FREEKB | Full
FROM (data-area) | Full
FRSET | Full
HONEOM | Full
L40 | Full
L64 | Full
L80 | Full
LAST | Full
LDC (data-value) | Validated
LENGTH (data-value) | Full
MAP (data-value) | Full
MAPONLY | Full
MAPSET (data-value) | Full
MSR (data-value) | Validated
NLEOM | Full
NOFLUSH | Validated
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Full
REQID (data-value) | Validated
SET (ptr-ref) | Full
TERMINAL | Full
WAIT | Full
Parent topic: CICS API Calls


SEND PAGE

The SEND PAGE function is supported.

Operand | Support
ALL | Validated
AUTOPAGE | Full
CURRENT | Validated
FMHPARM (data-value) | Validated
LAST | Full
NOAUTOPAGE | Full
OPERPURGE | Full
RELEASE | Full
RETAIN | Full
SET (ptr-ref) | Full
TRAILER (data-area) | Full
TRANSID (data-value) | Full
Parent topic: CICS API Calls


SEND PARTNSET

The SEND PARTNSET function is not supported.

Operand | Support
PARTNSET (data-value) | Recognized
Parent topic: CICS API Calls


SEND TEXT

The SEND TEXT function is supported.

Operand | Support
ACCUM | Full
ACTPARTN (data-value) | Validated
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Full
DEFAULT | Full
ERASE | Full
FMHPARM (data-value) | Validated
FORMFEED | Full
FREEKB | Full
FROM (data-area) | Full
HEADER (data-area) | Full
HONEOM | Full
JUSFIRST (cvda) | Full
JUSLAST (cvda) | Full
JUSTIFY (data-value) | Full
L40 | Full
L64 | Full
L80 | Full
LAST | Full
LDC (data-value) | Validated
LENGTH (data-value) | Full
MSR (data-value) | Validated
NLEOM | Full
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Full
REQID (data-value) | Validated
SET (ptr-ref) | Full
TERMINAL | Full
TRAILER (data-area) | Full
WAIT | Full
Parent topic: CICS API Calls


SEND TEXT MAPPED

The SEND TEXT MAPPED function is supported.

Operand | Support
FROM (data-area) | Full
LAST | Full
LENGTH (data-value) | Full
PAGING | Full
REQID (data-value) | Validated
TERMINAL | Full
WAIT | Full
Parent topic: CICS API Calls


SEND TEXT NOEDIT

The SEND TEXT NOEDIT function is supported.

Operand | Support
ALARM | Full
ALTERNATE | Full
CURSOR (data-value) | Validated
DEFAULT | Full
ERASE | Full
FREEKB | Full
FROM (data-area) | Full
HONEOM | Full
L40 | Full
L64 | Full
L80 | Full
LAST | Full
LENGTH (data-value) | Full
OUTPARTN (data-value) | Validated
PAGING | Full
PRINT | Full
REQID (data-value) | Validated
TERMINAL | Full
WAIT | Full
Parent topic: CICS API Calls


SIGNAL EVENT

The SIGNAL EVENT function is not supported.

Parent topic: CICS API Calls


SIGNOFF

The SIGNOFF function is supported.

Parent topic: CICS API Calls


SIGNON

The SIGNON function is supported.

Operand | Support
ESMREASON (data-area) | Full
ESMRESP (data-area) | Full
GROUPID (data-value) | Full
LANGINUSE (data-area) | Validated
LANGUAGECODE (data-value) | Validated
NATLANG (data-value) | Validated
NATLANGINUSE (data-area) | Validated
NEWPASSWORD (data-value) | Full
NEWPHRASE (data-area) | Full
NEWPHRASELEN (data-value) | Full
OIDCARD (data-value) | Validated
PASSWORD (data-value) | Full
PHRASE (data-area) | Full
PHRASELEN (data-value) | Full
USERID (data-value) | Full
Parent topic: CICS API Calls


SOAPFAULT ADD

The SOAPFAULT ADD function is supported.

Operand | Support
FAULTSTRING (data-value) | Full
FAULTSTRLEN (data-value) | Full
FROMCCSID (data-value) | Full
NATLANG (data-value) | Validated
SUBCODELEN (data-value) | Validated
SUBCODESTR (data-value) | Validated
Parent topic: CICS API Calls


SOAPFAULT CREATE

The SOAPFAULT CREATE function is supported.

Operand | Support
CLIENT (cvda) | Full
DETAIL (data-value) | Full
DETAILLENGTH (data-value) | Full
FAULTACTLEN (data-value) | Full
FAULTACTOR (data-value) | Full
FAULTCODE (data-value) | Full
FAULTCODELEN (data-value) | Full
FAULTCODESTR (data-value) | Full
FAULTSTRING (data-value) | Full
FAULTSTRLEN (data-value) | Full
FROMCCSID (data-value) | Full
NATLANG (data-value) | Validated
RECEIVER (cvda) | Full
ROLE (data-value) | Full
ROLELENGTH (data-value) | Full
SENDER (cvda) | Full
SERVER (cvda) | Full
Parent topic: CICS API Calls


SOAPFAULT DELETE

The SOAPFAULT DELETE function is supported.

Parent topic: CICS API Calls


SPOOLCLOSE

The SPOOLCLOSE function is supported.

Operand | Support
DELETE | Full
KEEP | Full
TOKEN (data-value) | Full
Parent topic: CICS API Calls


SPOOLCLOSE REPORT

The SPOOLCLOSE REPORT function is supported.

Operand | Support
DELETE | Full
DISP (data-value) | Full
HOLD | Full
KEEP | Full
LOG | Validated
RELEASE | Full
REPORT (data-value) | Full
RESUME | Validated
TOKEN (data-value) | Full
Parent topic: CICS API Calls


SPOOLOPEN ESCAPE

The SPOOLOPEN ESCAPE function is not supported.

Parent topic: CICS API Calls


SPOOLOPEN INPUT

The SPOOLOPEN INPUT function is not supported.

Operand | Support
CLASS (data-value) | Recognized
TOKEN (data-area) | Recognized
USERID (data-value) | Recognized
Parent topic: CICS API Calls


SPOOLOPEN MAPNAME

The SPOOLOPEN MAPNAME function is not supported.

Parent topic: CICS API Calls


SPOOLOPEN OUTPUT

The SPOOLOPEN OUTPUT function is supported.

Operand | Support
ASA | Full
CLASS (data-value) | Full
MCC | Full
NOCC | Full
NODE (data-value) | Full
OUTDESCR (ptr-ref) | Partial: handles USERID and recognizes other values
PRINT | Full
PUNCH | Full
RECORDLENGTH (data-value) | Full
TOKEN (data-area) | Full
USERID (data-value) | Partial: handles * and recognizes other values
Parent topic: CICS API Calls


SPOOLOPEN REPORT ASA

The SPOOLOPEN REPORT ASA function is supported.

Operand | Support
ASA | Full
BOTHNUM | Validated
CLASS (data-value) | Full
COPIES | Validated
DATETIME | Validated
DESTINATION | Validated
FCB | Validated
FOOT (data-area) | Validated
FOOTNUM | Validated
FORMS | Validated
HEAD (data-area) | Validated
HEADNUM | Validated
LINELENGTH (data-value) | Full
LINES | Validated
LOG | Validated
LOGICAL | Validated
MCC | Full
NOCC | Full
NODE (data-value) | Full
NONUM | Validated
NOSEP | Validated
OUTDESCR (ptr-ref) | Full
PHYSICAL | Validated
PRINTFAIL | Validated
PRIORITY | Validated
PWRSYSID | Validated
REPORT (data-value) | Full
RSL | Validated
SEP | Validated
SOSI1 | Validated
SOSI2 | Validated
TITLE (data-area) | Validated
TOKEN (data-area) | Full
USERDATA | Validated
USERID (data-value) | Full
Parent topic: CICS API Calls


SPOOLOPEN REPORT JCL

The SPOOLOPEN REPORT JCL function is supported.

Operand | Support
JCL | Full
LOG | Validated
REPORT (data-value) | Full
TOKEN (data-area) | Full
Parent topic: CICS API Calls


SPOOLOPEN REPORT MCC

The SPOOLOPEN REPORT MCC function is supported.

Operand | Support
ASA | Full
BOTHNUM | Validated
CLASS (data-value) | Full
COPIES | Validated
DATETIME | Validated
DESTINATION | Validated
FCB | Validated
FOOT (data-area) | Validated
FOOTNUM | Validated
FORMS | Validated
HEAD (data-area) | Validated
HEADNUM | Validated
LINELENGTH (data-value) | Full
LINES | Validated
LOG | Validated
LOGICAL | Validated
MCC | Full
NOCC | Full
NODE (data-value) | Full
NONUM | Validated
NOSEP | Validated
OUTDESCR (ptr-ref) | Full
PHYSICAL | Validated
PRINTFAIL | Validated
PRIORITY | Validated
PWRSYSID | Validated
REPORT (data-value) | Full
RSL | Validated
SEP | Validated
SOSI1 | Validated
SOSI2 | Validated
TITLE (data-area) | Validated
TOKEN (data-area) | Full
USERDATA | Validated
USERID (data-value) | Full
Parent topic: CICS API Calls


SPOOLOPEN REPORT NOCC

The SPOOLOPEN REPORT NOCC function is supported.

Operand | Support
ASA | Full
BOTHNUM | Validated
CLASS (data-value) | Full
COPIES | Validated
DATETIME | Validated
DESTINATION | Validated
FCB | Validated
FOOT (data-area) | Validated
FOOTNUM | Validated
FORMS | Validated
HEAD (data-area) | Validated
HEADNUM | Validated
LINELENGTH (data-value) | Full
LINES | Validated
LOG | Validated
LOGICAL | Validated
MCC | Full
NOCC | Full
NODE (data-value) | Full
NONUM | Validated
NOSEP | Validated
OUTDESCR (ptr-ref) | Full
PHYSICAL | Validated
PRINTFAIL | Validated
PRIORITY | Validated
PWRSYSID | Validated
REPORT (data-value) | Full
RSL | Validated
SEP | Validated
SOSI1 | Validated
SOSI2 | Validated
TITLE (data-area) | Validated
TOKEN (data-area) | Full
USERDATA | Validated
USERID (data-value) | Full
Parent topic: CICS API Calls


SPOOLOPEN REPORT SCS

The SPOOLOPEN REPORT SCS function is not supported.

Parent topic: CICS API Calls


SPOOLOPEN REPORT T3270

The SPOOLOPEN REPORT T3270 function is not supported.

Parent topic: CICS API Calls


SPOOLOPEN RESUME

The SPOOLOPEN RESUME function is not supported.

Parent topic: CICS API Calls


SPOOLREAD

The SPOOLREAD function is not supported.

Operand | Support
INTO (data-area) | Recognized
MAXFLENGTH (data-value) | Recognized
TOFLENGTH (data-value) | Recognized
TOKEN (data-value) | Recognized
Parent topic: CICS API Calls


SPOOLWRITE

The SPOOLWRITE function is supported.

Operand | Support
FLENGTH (data-value) | Full
FROM (data-area) | Full
LINE | Full
PAGE | Full
TOKEN (data-value) | Full
Parent topic: CICS API Calls


SPOOLWRITE MAPNAME

The SPOOLWRITE MAPNAME function is not supported.

Parent topic: CICS API Calls


SPOOLWRITE REPORT

The SPOOLWRITE REPORT function is supported.

Operand | Support
FLENGTH (data-value) | Full
FROM (data-area) | Full
LOG | Validated
REPORT (data-value) | Full
TOKEN (data-value) | Full
Parent topic: CICS API Calls


START

The START function is supported.

Operand | Support
AFTER | Full
AT | Full
FMH | Validated
FROM (data-area) | Full
HOURS (data-value) | Full
INTERVAL (data-value) | Full
LENGTH (data-value) | Full
MINUTES (data-value) | Full
NOCHECK | Full
PROTECT | Full
QUEUE (data-value) | Full
REQID (data-value) | Full
RTERMID (data-value) | Full
RTRANSID (data-value) | Full
SECONDS (data-value) | Full
SYSID (data-value) | Full
TERMID (data-value) | Full
TIME (data-value) | Full
TRANSID (data-value) | Full
USERID (data-value) | Full
Parent topic: CICS API Calls


START ATTACH

The START ATTACH function is not supported.

Operand | Support
FROM (data-area) | Recognized
LENGTH (data-value) | Recognized
TRANSID (data-value) | Recognized
Parent topic: CICS API Calls


START BREXIT

The START BREXIT function is supported.

Operand | Support
BRDATA (data-area) | Full
BRDATALENGTH (data-area) | Full
BREXIT (data-value) | Full
TRANSID (data-value) | Full
USERID (data-value) | Full
Parent topic: CICS API Calls


START CHANNEL

The START CHANNEL function is supported.

Operand | Support
CHANNEL (data-value) | Full
SYSID (data-value) | Full
TERMID (data-value) | Full
TRANSID (data-value) | Full
USERID (data-value) | Full
Parent topic: CICS API Calls


STARTBR

The STARTBR function is supported.

Operand | Support
DATASET (data-value) | Full
DEBKEY | Validated
DEBREC | Validated
EQUAL | Full
FILE (data-value) | Full
GENERIC | Full
GTEQ | Full
KEYLENGTH (data-value) | Full
RBA | Full
REQID (data-value) | Full
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Full
XRBA | Full
Parent topic: CICS API Calls


STARTBROWSE ACTIVITY

The STARTBROWSE ACTIVITY function is not supported.

Parent topic: CICS API Calls


STARTBROWSE CONTAINER

The STARTBROWSE CONTAINER function is supported.

Operand | Support
ACTIVITYID (data-value) | Validated
BROWSETOKEN (data-area) | Full
CHANNEL (data-value) | Full
PROCESS (data-value) | Validated
PROCESSTYPE (data-value) | Validated
Parent topic: CICS API Calls


STARTBROWSE EVENT

The STARTBROWSE EVENT function is not supported.

Parent topic: CICS API Calls


STARTBROWSE PROCESS

The STARTBROWSE PROCESS function is not supported.

Parent topic: CICS API Calls


SUSPEND

The SUSPEND function is supported.

Parent topic: CICS API Calls


SYNCPOINT

The SYNCPOINT function is supported.

Operand | Support
ROLLBACK | Full
Parent topic: CICS API Calls


TEST EVENT

The TEST EVENT function is not supported.

Parent topic: CICS API Calls


TRACE

The TRACE function is not supported.

Parent topic: CICS API Calls


TRANSFORM DATATOXML

The TRANSFORM DATATOXML function is supported.

Operand | Support
CHANNEL (data-value) | Full
DATCONTAINER (data-value) | Full
ELEMNAME (data-area) | Full
ELEMNAMELEN (data-area) | Full
ELEMNS (data-area) | Full
ELEMNSLEN (data-area) | Full
TYPENAME (data-area) | Validated
TYPENAMELEN (data-area) | Validated
TYPENS (data-area) | Validated
TYPENSLEN (data-area) | Validated
XMLCONTAINER (data-value) | Full
XMLTRANSFORM (data-value) | Full
Parent topic: CICS API Calls


TRANSFORM XMLTODATA

The TRANSFORM XMLTODATA function is supported.

Operand | Support
CHANNEL (data-value) | Full
DATCONTAINER (data-value) | Full
ELEMNAME (data-area) | Full
ELEMNAMELEN (data-area) | Full
ELEMNS (data-area) | Full
ELEMNSLEN (data-area) | Full
NSCONTAINER (data-value) | Validated
TYPENAME (data-area) | Validated
TYPENAMELEN (data-area) | Validated
TYPENS (data-area) | Validated
TYPENSLEN (data-area) | Validated
XMLCONTAINER (data-value) | Full
XMLTRANSFORM (data-value) | Full
Parent topic: CICS API Calls


UNLOCK

The UNLOCK function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
SYSID (data-value) | Full
TOKEN (data-area) | Full
Parent topic: CICS API Calls


UPDATE COUNTER

The UPDATE COUNTER function is not supported.

Operand | Support
COMPAREMAX (data-value) | Recognized
COMPAREMIN (data-value) | Recognized
COUNTER (data-value) | Recognized
POOL (data-value) | Recognized
VALUE (data-value) | Recognized
Parent topic: CICS API Calls


UPDATE DCOUNTER

The UPDATE DCOUNTER function is not supported.

Operand | Support
COMPAREMAX (data-area) | Recognized
COMPAREMIN (data-area) | Recognized
DCOUNTER (data-value) | Recognized
POOL (data-value) | Recognized
VALUE (data-area) | Recognized
Parent topic: CICS API Calls


VERIFY PASSWORD

The VERIFY PASSWORD function is supported.

Operand | Support
CHANGETIME (data-area) | Full
DAYSLEFT (data-area) | Full
ESMREASON (data-area) | Full
ESMRESP (data-area) | Full
EXPIRYTIME (data-area) | Full
INVALIDCOUNT (data-area) | Full
LASTUSETIME (data-area) | Full
PASSWORD (data-value) | Full
USERID (data-value) | Full
Parent topic: CICS API Calls


VERIFY PHRASE

The VERIFY PHRASE function is supported.

Operand | Support
CHANGETIME (data-area) | Full
DAYSLEFT (data-area) | Full
ESMREASON (data-area) | Full
ESMRESP (data-area) | Full
EXPIRYTIME (data-area) | Full
INVALIDCOUNT (data-area) | Full
LASTUSETIME (data-area) | Full
PHRASE (data-area) | Full
PHRASELEN (data-value) | Full
USERID (data-value) | Full
Parent topic: CICS API Calls


WAIT CONVID

The WAIT CONVID function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS API Calls


WAIT EVENT

The WAIT EVENT function is supported.

Operand | Support
ECADDR (ptr-ref) | Full
NAME (data-value) | Full
Parent topic: CICS API Calls


WAIT EXTERNAL

The WAIT EXTERNAL function is not supported.

Operand | Support
ECBLIST (data-area) | Recognized
NAME (data-value) | Recognized
NOTPURGEABLE (cvda) | Recognized
NUMEVENTS (data-value) | Recognized
PURGEABILITY (data-value) | Recognized
PURGEABLE (cvda) | Recognized
Parent topic: CICS API Calls


WAIT JOURNAL

The WAIT JOURNAL function is supported.

Operand | Support
JFILEID (data-value) | Full
JOURNALNUM (data-value) | Full
REQID (data-value) | Full
STARTIO | Full
Parent topic: CICS API Calls


WAIT JOURNALNAME

The WAIT JOURNALNAME function is not supported.

Operand | Support
JOURNALNAME (data-value) | Recognized
REQID (data-value) | Recognized
Parent topic: CICS API Calls


WAIT JOURNALNUM

The WAIT JOURNALNUM function is supported.

Operand | Support
JFILEID (data-value) | Full
JOURNALNUM (data-value) | Full
REQID (data-value) | Full
STARTIO | Full
Parent topic: CICS API Calls


WAIT SIGNAL

The WAIT SIGNAL function is not supported.

Parent topic: CICS API Calls


WAIT TERMINAL

The WAIT TERMINAL function is not supported.

Parent topic: CICS API Calls


WAITCICS

The WAITCICS function is supported.

Operand | Support
ECBLIST (data-area) | Full
NAME (data-value) | Full
NOTPURGEABLE (cvda) | Full
NUMEVENTS (data-value) | Full
PURGEABILITY (data-value) | Full
PURGEABLE (cvda) | Full
Parent topic: CICS API Calls


WEB CLOSE

The WEB CLOSE function is supported.

Operand | Support
SESSTOKEN (data-area) | Full
Parent topic: CICS API Calls


WEB CONVERSE

The WEB CONVERSE function is supported.

Operand | Support
ACTION (data-value) | Full
AUTHENTICATE (data-value) | Full
BASICAUTH (cvda) | Full
BODYCHARSET (data-area) | Full
CHANNEL (data-value) | Full
CHARACTERSET (data-value) | Full
CLICONVERT (cvda) | Full
CLIENTCONV (data-value) | Full
CLOSE (cvda) | Full
CLOSESTATUS (data-value) | Full
CONTAINER (data-value) | Full
DELETE (cvda) | Full
DOCDELETE (cvda) | Full
DOCSTATUS (data-value) | Full
DOCTOKEN (data-value) | Full
EXPECT (cvda) | Full
FROM (data-area) | Full
FROMLENGTH (data-value) | Full
GET (cvda) | Full
HEAD (cvda) | Full
INTO (data-area) | Full
MAXLENGTH (data-value) | Full
MEDIATYPE (data-value) | Full
METHOD (data-value) | Full
NOCLICONVERT (cvda) | Full
NOCLOSE (cvda) | Full
NODOCDELETE (cvda) | Full
NOINCONVERT (cvda) | Full
NONE (cvda) | Full
NOOUTCONVERT (cvda) | Full
NOTRUNCATE | Full
OPTIONS (cvda) | Full
PASSWORD (data-area) | Full
PASSWORDLEN (data-value) | Full
PATH (data-area) | Full
PATHLENGTH (data-value) | Full
POST (cvda) | Full
PUT (cvda) | Full
QUERYSTRING (data-area) | Full
QUERYSTRLEN (data-value) | Full
SESSTOKEN (data-area) | Full
SET (ptr-ref) | Full
STATUSCODE (data-value) | Full
STATUSLEN (data-value) | Full
STATUSTEXT (data-area) | Full
TOCHANNEL (data-value) | Full
TOCONTAINER (data-value) | Full
TOLENGTH (data-area) | Full
TRACE (cvda) | Full
URIMAP (data-value) | Full
USERNAME (data-area) | Full
USERNAMELEN (data-value) | Full
Parent topic: CICS API Calls


WEB ENDBROWSE FORMFIELD

The WEB ENDBROWSE FORMFIELD function is supported.

Operand | Support
FORMFIELD | Full
Parent topic: CICS API Calls


WEB ENDBROWSE HTTPHEADER

The WEB ENDBROWSE HTTPHEADER function is supported.

Operand | Support
HTTPHEADER | Full
SESSTOKEN (data-area) | Full
Parent topic: CICS API Calls


WEB ENDBROWSE QUERYPARM

The WEB ENDBROWSE QUERYPARM function is supported.

Operand | Support
QUERYPARM | Full
Parent topic: CICS API Calls


WEB EXTRACT

The WEB EXTRACT function is supported.

Operand | Support
HOST (data-area) | Full
HOSTLENGTH (data-value) | Full
HOSTTYPE (data-value) | Full
HTTPMETHOD (data-area) | Full
HTTPVERSION (data-area) | Full
METHODLENGTH (data-value) | Full
PATH (data-area) | Full
PATHLENGTH (data-value) | Full
PORTNUMBER (data-area) | Full
QUERYSTRING (data-area) | Full
QUERYSTRLEN (data-value) | Full
REALM (data-area) | Full
REALMLEN (data-value) | Full
REQUESTTYPE (cvda) | Full
SCHEME (cvda) | Full
SESSTOKEN (data-area) | Full
URIMAP (data-area) | Full
VERSIONLEN (data-value) | Full
Parent topic: CICS API Calls


WEB OPEN

The WEB OPEN function is supported.

Operand | Support
CERTIFICATE (data-value) | Full
CIPHERS (data-value) | Full
CODEPAGE (data-value) | Full
HOST (data-value) | Full
HOSTLENGTH (data-value) | Full
HTTP (cvda) | Full
HTTPRNUM (data-area) | Full
HTTPS (cvda) | Full
HTTPVNUM (data-area) | Full
NUMCIPHERS (data-value) | Full
PORTNUMBER (data-value) | Full
SCHEME (data-value) | Full
SESSTOKEN (data-area) | Full
URIMAP (data-value) | Full
Parent topic: CICS API Calls


WEB PARSE

The WEB PARSE function is supported.

Operand | Support
HOST (data-area) | Full
HOSTLENGTH (data-value) | Full
HOSTTYPE (data-value) | Full
PATH (data-area) | Full
PATHLENGTH (data-value) | Full
PORTNUMBER (data-area) | Full
QUERYSTRING (data-area) | Full
QUERYSTRLEN (data-value) | Full
SCHEMENAME (data-area) | Full
URL (data-value) | Full
URLLENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB READ FORMFIELD

The WEB READ FORMFIELD function is supported.

Operand | Support
CHARACTERSET (data-value) | Full
CLNTCODEPAGE (data-value) | Full
FORMFIELD (data-area) | Full
HOSTCODEPAGE (data-value) | Full
NAMELENGTH (data-value) | Full
SET (ptr-ref) | Full
VALUE (data-area) | Full
VALUELENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB READ HTTPHEADER

The WEB READ HTTPHEADER function is supported.

Operand | Support
HTTPHEADER (data-area) | Full
NAMELENGTH (data-value) | Full
SESSTOKEN (data-area) | Full
VALUE (data-area) | Full
VALUELENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB READ QUERYPARM

The WEB READ QUERYPARM function is supported.

Operand | Support
HOSTCODEPAGE (data-value) | Full
NAMELENGTH (data-value) | Full
QUERYPARM (data-area) | Full
SET (ptr-ref) | Full
VALUE (data-area) | Full
VALUELENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB READNEXT FORMFIELD

The WEB READNEXT FORMFIELD function is supported.

Operand | Support
FORMFIELD (data-area) | Full
NAMELENGTH (data-value) | Full
VALUE (data-area) | Full
VALUELENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB READNEXT HTTPHEADER

The WEB READNEXT HTTPHEADER function is supported.

Operand | Support
HTTPHEADER (data-area) | Full
NAMELENGTH (data-value) | Full
SESSTOKEN (data-area) | Full
VALUE (data-area) | Full
VALUELENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB READNEXT QUERYPARM

The WEB READNEXT QUERYPARM function is supported.

Operand | Support
NAMELENGTH (data-value) | Full
QUERYPARM (data-area) | Full
VALUE (data-area) | Full
VALUELENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB RECEIVE

The WEB RECEIVE function is supported.

Operand | Support
BODYCHARSET (data-area) | Full
CHARACTERSET (data-value) | Full
CLNTCODEPAGE (data-value) | Full
HOSTCODEPAGE (data-value) | Full
INTO (data-area) | Full
LENGTH (data-area) | Full
MAXLENGTH (data-value) | Full
MEDIATYPE (data-value) | Full
NOSRVCONVERT (cvda) | Full
NOTRUNCATE | Full
SERVERCONV (data-value) | Full
SET (ptr-ref) | Full
SRVCONVERT (cvda) | Full
TOCHANNEL (data-value) | Full
TOCONTAINER (data-value) | Full
TYPE (cvda) | Full
Parent topic: CICS API Calls


WEB RECEIVE SESSTOKEN

The WEB RECEIVE SESSTOKEN function is supported.

Operand | Support
BODYCHARSET (data-area) | Full
CLICONVERT (cvda) | Full
CLIENTCONV (data-value) | Full
INTO (data-area) | Full
LENGTH (data-value) | Full
MAXLENGTH (data-area) | Full
MEDIATYPE (data-area) | Full
NOCLICONVERT (cvda) | Full
NOTRUNCATE | Full
SESSTOKEN (data-area) | Full
SET (ptr-ref) | Full
STATUSCODE (data-value) | Full
STATUSLEN (data-value) | Full
STATUSTEXT (data-area) | Full
TOCHANNEL (data-value) | Full
TOCONTAINER (data-value) | Full
Parent topic: CICS API Calls


WEB RETRIEVE

The WEB RETRIEVE function is supported.

Operand | Support
DOCTOKEN (data-value) | Full
Parent topic: CICS API Calls


WEB SEND

The WEB SEND function is supported.

Operand | Support
ACTION (data-value) | Full
CHANNEL (data-value) | Full
CHARACTERSET (data-value) | Full
CHUNKEND (cvda) | Full
CHUNKING (data-value) | Full
CHUNKNO (cvda) | Full
CHUNKYES (cvda) | Full
CLNTCODEPAGE (data-value) | Full
CLOSE (cvda) | Full
CLOSESTATUS (data-value) | Full
CONTAINER (data-value) | Full
DOCDELETE (cvda) | Full
DOCSTATUS (data-value) | Full
DOCTOKEN (data-value) | Full
EVENTUAL (cvda) | Full
FROM (data-area) | Full
FROMLENGTH (data-value) | Full
HOSTCODEPAGE (data-value) | Full
IMMEDIATE (cvda) | Full
LENGTH (data-value) | Full
MEDIATYPE (data-value) | Full
NOCLOSE (cvda) | Full
NODOCDELETE (cvda) | Full
NOSRVCONVERT (cvda) | Full
SERVERCONV (data-value) | Full
SRVCONVERT (cvda) | Full
STATUSCODE (data-value) | Full
STATUSLEN (data-value) | Full
STATUSTEXT (data-area) | Full
Parent topic: CICS API Calls


WEB SEND SESSTOKEN

The WEB SEND SESSTOKEN function is supported.

Operand | Support
ACTION (data-value) | Full
AUTHENTICATE (data-value) | Full
BASICAUTH (cvda) | Full
CHANNEL (data-value) | Full
CHARACTERSET (data-value) | Full
CHUNKEND (cvda) | Full
CHUNKING (data-value) | Full
CHUNKNO (cvda) | Full
CHUNKYES (cvda) | Full
CLICONVERT (cvda) | Full
CLIENTCONV (data-value) | Full
CLOSE (cvda) | Full
CLOSESTATUS (data-value) | Full
CONTAINER (data-value) | Full
DELETE (cvda) | Full
DOCDELETE (cvda) | Full
DOCSTATUS (data-value) | Full
DOCTOKEN (data-value) | Full
EXPECT (cvda) | Full
FROM (data-area) | Full
FROMLENGTH (data-value) | Full
GET (cvda) | Full
HEAD (cvda) | Full
MEDIATYPE (data-value) | Full
METHOD (data-value) | Full
NOCLICONVERT (cvda) | Full
NOCLOSE (cvda) | Full
NODOCDELETE (cvda) | Full
NONE (cvda) | Full
OPTIONS (cvda) | Full
PASSWORD (data-area) | Full
PASSWORDLEN (data-value) | Full
PATH (data-area) | Full
PATHLENGTH (data-value) | Full
POST (cvda) | Full
PUT (cvda) | Full
QUERYSTRING (data-area) | Full
QUERYSTRLEN (data-value) | Full
SESSTOKEN (data-area) | Full
TRACE (cvda) | Full
URIMAP (data-value) | Full
USERNAME (data-area) | Full
USERNAMELEN (data-value) | Full
Parent topic: CICS API Calls


WEB STARTBROWSE FORMFIELD

The WEB STARTBROWSE FORMFIELD function is supported.

Operand | Support
CHARACTERSET (data-value) | Full
CLNTCODEPAGE (data-value) | Full
FORMFIELD (data-value) | Full
HOSTCODEPAGE (data-value) | Full
NAMELENGTH (data-value) | Full
Parent topic: CICS API Calls


WEB STARTBROWSE HTTPHEADER

The WEB STARTBROWSE HTTPHEADER function is supported.

Operand | Support
HTTPHEADER | Full
SESSTOKEN (data-area) | Full
Parent topic: CICS API Calls


WEB STARTBROWSE QUERYPARM

The WEB STARTBROWSE QUERYPARM function is supported.

Operand | Support
HOSTCODEPAGE (data-value) | Full
NAMELENGTH (data-value) | Full
QUERYPARM (data-value) | Full
Parent topic: CICS API Calls


WEB WRITE

The WEB WRITE function is supported.

Operand | Support
HTTPHEADER (data-area) | Full
NAMELENGTH (data-value) | Full
SESSTOKEN (data-area) | Full
VALUE (data-area) | Full
VALUELENGTH (data-value) | Full
Parent topic: CICS API Calls


WRITE

The WRITE function is supported.

Operand | Support
DATASET (data-value) | Full
FILE (data-value) | Full
FROM (data-area) | Full
KEYLENGTH (data-value) | Full
LENGTH (data-value) | Full
MASSINSERT | Full
NOSUSPEND | Validated
RBA | Full
RIDFLD (data-area) | Full
RRN | Full
SYSID (data-value) | Full
XRBA | Full
Parent topic: CICS API Calls


WRITE JOURNALNAME

The WRITE JOURNALNAME function is not supported.

Operand | Support
FLENGTH (data-value) | Recognized
FROM (data-area) | Recognized
JOURNALNAME (data-value) | Recognized
JTYPEID (data-value) | Recognized
NOSUSPEND | Recognized
PFXLENG (data-value) | Recognized
PREFIX (data-area) | Recognized
REQID (data-area) | Recognized
WAIT | Recognized
Parent topic: CICS API Calls


WRITE JOURNALNUM

The WRITE JOURNALNUM function is supported.

Operand | Support
FROM (data-area) | Full
JFILEID (data-value) | Full
JOURNALNUM (data-value) | Full
JTYPEID (data-value) | Full
LENGTH (data-value) | Full
NOSUSPEND | Full
PFXLENG (data-value) | Full
PREFIX (data-area) | Full
REQID (data-area) | Full
STARTIO | Full
WAIT | Full
Parent topic: CICS API Calls


WRITE OPERATOR

The WRITE OPERATOR function is supported.

Operand | Support
ACTION (data-value) | Full
CRITICAL (cvda) | Full
EVENTUAL (cvda) | Full
IMMEDIATE (cvda) | Full
MAXLENGTH (data-value) | Full
NUMROUTES (data-value) | Validated
REPLY (data-area) | Partial: not yet implemented
REPLYLENGTH (data-area) | Full
ROUTECODES (data-value) | Validated
TEXT (data-value) | Full
TEXTLENGTH (data-value) | Full
TIMEOUT (data-value) | Full
Parent topic: CICS API Calls


WRITEQ

The WRITEQ function is supported.

Operand | Support
AUXILIARY | Full
FROM (data-area) | Full
ITEM (data-area) | Full
LENGTH (data-value) | Full
MAIN | Full
NOSUSPEND | Validated
NUMITEMS (data-area) | Full
QNAME (data-value) | Full
QUEUE (data-value) | Full
REWRITE | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


WRITEQ TD

The WRITEQ TD function is supported.

Operand | Support
FROM (data-area) | Full
LENGTH (data-value) | Full
QUEUE (data-value) | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


WRITEQ TS

The WRITEQ TS function is supported.

Operand | Support
AUXILIARY | Full
FROM (data-area) | Full
ITEM (data-area) | Full
LENGTH (data-value) | Full
MAIN | Full
NOSUSPEND | Validated
NUMITEMS (data-area) | Full
QNAME (data-value) | Full
QUEUE (data-value) | Full
REWRITE | Full
SYSID (data-value) | Full
Parent topic: CICS API Calls


WSACONTEXT BUILD

The WSACONTEXT BUILD function is not supported.

Parent topic: CICS API Calls


WSACONTEXT DELETE

The WSACONTEXT DELETE function is not supported.

Parent topic: CICS API Calls


WSACONTEXT GET

The WSACONTEXT GET function is not supported.

Parent topic: CICS API Calls


WSAEPR CREATE

The WSAEPR CREATE function is not supported.

Parent topic: CICS API Calls


XCTL

The XCTL function is supported.

Operand | Support
CHANNEL (data-value) | Full
COMMAREA (data-area) | Full
INPUTMSG (data-area) | Full
INPUTMSGLEN (data-value) | Full
LENGTH (data-value) | Full
PROGRAM (data-value) | Full
Parent topic: CICS API Calls


CICS SPI Calls

  • ACQUIRE TERMINAL
    The ACQUIRE TERMINAL function is not supported.
  • COLLECT STATISTICS
    The COLLECT STATISTICS function is not supported.
  • CREATE CONNECTION
    The CREATE CONNECTION function is not supported.
  • CREATE CORBASERVER
    The CREATE CORBASERVER function is not supported.
  • CREATE DB2CONN
    The CREATE DB2CONN function is not supported.
  • CREATE DB2ENTRY
    The CREATE DB2ENTRY function is not supported.
  • CREATE DB2TRAN
    The CREATE DB2TRAN function is not supported.
  • CREATE DJAR
    The CREATE DJAR function is not supported.
  • CREATE DOCTEMPLATE
    The CREATE DOCTEMPLATE function is not supported.
  • CREATE ENQMODEL
    The CREATE ENQMODEL function is not supported.
  • CREATE FILE
    The CREATE FILE function is not supported.
  • CREATE JOURNALMODEL
    The CREATE JOURNALMODEL function is not supported.
  • CREATE LSRPOOL
    The CREATE LSRPOOL function is not supported.
  • CREATE MAPSET
    The CREATE MAPSET function is not supported.
  • CREATE PARTITIONSET
    The CREATE PARTITIONSET function is not supported.
  • CREATE PARTNER
    The CREATE PARTNER function is not supported.
  • CREATE PROCESSTYPE
    The CREATE PROCESSTYPE function is not supported.
  • CREATE PROFILE
    The CREATE PROFILE function is not supported.
  • CREATE PROGRAM
    The CREATE PROGRAM function is not supported.
  • CREATE REQUESTMODEL
    The CREATE REQUESTMODEL function is not supported.
  • CREATE SESSIONS
    The CREATE SESSIONS function is not supported.
  • CREATE TCPIPSERVICE
    The CREATE TCPIPSERVICE function is not supported.
  • CREATE TDQUEUE
    The CREATE TDQUEUE function is not supported.
  • CREATE TERMINAL
    The CREATE TERMINAL function is not supported.
  • CREATE TRANCLASS
    The CREATE TRANCLASS function is not supported.
  • CREATE TRANSACTION
    The CREATE TRANSACTION function is not supported.
  • CREATE TSMODEL
    The CREATE TSMODEL function is not supported.
  • CREATE TYPETERM
    The CREATE TYPETERM function is not supported.
  • DISABLE PROGRAM
    The DISABLE PROGRAM function is supported.
  • DISCARD AUTINSTMODEL
    The DISCARD AUTINSTMODEL function is not supported.
  • DISCARD CONNECTION
    The DISCARD CONNECTION function is not supported.
  • DISCARD CORBASERVER
    The DISCARD CORBASERVER function is not supported.
  • DISCARD DB2CONN
    The DISCARD DB2CONN function is not supported.
  • DISCARD DB2ENTRY
    The DISCARD DB2ENTRY function is not supported.
  • DISCARD DB2TRAN
    The DISCARD DB2TRAN function is not supported.
  • DISCARD DJAR
    The DISCARD DJAR function is not supported.
  • DISCARD DOCTEMPLATE
    The DISCARD DOCTEMPLATE function is supported.
  • DISCARD ENQMODEL
    The DISCARD ENQMODEL function is supported.
  • DISCARD FILE
    The DISCARD FILE function is not supported.
  • DISCARD JOURNALMODEL
    The DISCARD JOURNALMODEL function is not supported.
  • DISCARD JOURNALNAME
    The DISCARD JOURNALNAME function is not supported.
  • DISCARD PARTNER
    The DISCARD PARTNER function is not supported.
  • DISCARD PIPELINE
    The DISCARD PIPELINE function is supported.
  • DISCARD PROCESSTYPE
    The DISCARD PROCESSTYPE function is not supported.
  • DISCARD PROFILE
    The DISCARD PROFILE function is not supported.
  • DISCARD PROGRAM
    The DISCARD PROGRAM function is supported.
  • DISCARD REQUESTMODEL
    The DISCARD REQUESTMODEL function is not supported.
  • DISCARD TCPIPSERVICE
    The DISCARD TCPIPSERVICE function is supported.
  • DISCARD TDQUEUE
    The DISCARD TDQUEUE function is not supported.
  • DISCARD TERMINAL
    The DISCARD TERMINAL function is not supported.
  • DISCARD TRANCLASS
    The DISCARD TRANCLASS function is not supported.
  • DISCARD TRANSACTION
    The DISCARD TRANSACTION function is not supported.
  • DISCARD TSMODEL
    The DISCARD TSMODEL function is supported.
  • DISCARD URIMAP
    The DISCARD URIMAP function is supported.
  • DISCARD WEBSERVICE
    The DISCARD WEBSERVICE function is supported.
  • ENABLE PROGRAM
    The ENABLE PROGRAM function is supported.
  • EXTRACT ATTACH
    The EXTRACT ATTACH function is not supported.
  • EXTRACT ATTRIBUTES
    The EXTRACT ATTRIBUTES function is supported.
  • EXTRACT CERTIFICATE
    The EXTRACT CERTIFICATE function is supported.
  • EXTRACT EXIT
    The EXTRACT EXIT function is supported.
  • EXTRACT LOGONMSG
    The EXTRACT LOGONMSG function is not supported.
  • EXTRACT PROCESS
    The EXTRACT PROCESS function is supported.
  • EXTRACT TCPIP
    The EXTRACT TCPIP function is supported.
  • EXTRACT TCT
    The EXTRACT TCT function is not supported.
  • EXTRACT WEB
    The EXTRACT WEB function is supported.
  • INQUIRE ACTIVITYID
    The INQUIRE ACTIVITYID function is not supported.
  • INQUIRE AUTINSTMODEL
    The INQUIRE AUTINSTMODEL function is not supported.
  • INQUIRE AUTOINSTALL
    The INQUIRE AUTOINSTALL function is not supported.
  • INQUIRE BEAN
    The INQUIRE BEAN function is not supported.
  • INQUIRE BRFACILITY
    The INQUIRE BRFACILITY function is not supported.
  • INQUIRE CFDTPOOL
    The INQUIRE CFDTPOOL function is not supported.
  • INQUIRE CONNECTION
    The INQUIRE CONNECTION function is supported.
  • INQUIRE CONTAINER
    The INQUIRE CONTAINER function is not supported.
  • INQUIRE CORBASERVER
    The INQUIRE CORBASERVER function is not supported.
  • INQUIRE DATASET
    The INQUIRE DATASET function is supported.
  • INQUIRE DB2CONN
    The INQUIRE DB2CONN function is not supported.
  • INQUIRE DB2ENTRY
    The INQUIRE DB2ENTRY function is not supported.
  • INQUIRE DB2TRAN
    The INQUIRE DB2TRAN function is not supported.
  • INQUIRE DELETSHIPPED
    The INQUIRE DELETSHIPPED function is not supported.
  • INQUIRE DISPATCHER
    The INQUIRE DISPATCHER function is not supported.
  • INQUIRE DJAR
    The INQUIRE DJAR function is not supported.
  • INQUIRE DOCTEMPLATE
    The INQUIRE DOCTEMPLATE function is supported.
  • INQUIRE DSNAME
    The INQUIRE DSNAME function is not supported.
  • INQUIRE DUMPDS
    The INQUIRE DUMPDS function is not supported.
  • INQUIRE ENQ
    The INQUIRE ENQ function is not supported.
  • INQUIRE ENQMODEL
    The INQUIRE ENQMODEL function is supported.
  • INQUIRE EVENT
    The INQUIRE EVENT function is not supported.
  • INQUIRE EXCI
    The INQUIRE EXCI function is not supported.
  • INQUIRE EXITPROGRAM
    The INQUIRE EXITPROGRAM function is not supported.
  • INQUIRE FILE
    The INQUIRE FILE function is supported.
  • INQUIRE IRC
    The INQUIRE IRC function is not supported.
  • INQUIRE JOURNALMODEL
    The INQUIRE JOURNALMODEL function is not supported.
  • INQUIRE JOURNALNAME
    The INQUIRE JOURNALNAME function is not supported.
  • INQUIRE JOURNALNUM
    The INQUIRE JOURNALNUM function is supported.
  • INQUIRE JVMPOOL
    The INQUIRE JVMPOOL function is not supported.
  • INQUIRE MODENAME
    The INQUIRE MODENAME function is not supported.
  • INQUIRE MONITOR
    The INQUIRE MONITOR function is not supported.
  • INQUIRE NETNAME
    The INQUIRE NETNAME function is supported.
  • INQUIRE PARTNER
    The INQUIRE PARTNER function is not supported.
  • INQUIRE PIPELINE
    The INQUIRE PIPELINE function is supported.
  • INQUIRE PROCESS
    The INQUIRE PROCESS function is not supported.
  • INQUIRE PROCESSTYPE
    The INQUIRE PROCESSTYPE function is not supported.
  • INQUIRE PROFILE
    The INQUIRE PROFILE function is not supported.
  • INQUIRE PROGRAM
    The INQUIRE PROGRAM function is supported.
  • INQUIRE REQID
    The INQUIRE REQID function is supported.
  • INQUIRE REQUESTMODEL
    The INQUIRE REQUESTMODEL function is not supported.
  • INQUIRE RRMS
    The INQUIRE RRMS function is not supported.
  • INQUIRE STATISTICS
    The INQUIRE STATISTICS function is not supported.
  • INQUIRE STORAGE
    The INQUIRE STORAGE function is not supported.
  • INQUIRE STREAMNAME
    The INQUIRE STREAMNAME function is not supported.
  • INQUIRE SYSDUMPCODE
    The INQUIRE SYSDUMPCODE function is not supported.
  • INQUIRE SYSTEM
    The INQUIRE SYSTEM function is supported.
  • INQUIRE TASK
    The INQUIRE TASK function is supported.
  • INQUIRE TASK LIST
    The INQUIRE TASK LIST function is supported.
  • INQUIRE TCLASS
    The INQUIRE TCLASS function is supported.
  • INQUIRE TCPIP
    The INQUIRE TCPIP function is not supported.
  • INQUIRE TCPIPSERVICE
    The INQUIRE TCPIPSERVICE function is supported.
  • INQUIRE TDQUEUE
    The INQUIRE TDQUEUE function is supported.
  • INQUIRE TERMINAL
    The INQUIRE TERMINAL function is supported.
  • INQUIRE TIMER
    The INQUIRE TIMER function is not supported.
  • INQUIRE TRACEDEST
    The INQUIRE TRACEDEST function is not supported.
  • INQUIRE TRACEFLAG
    The INQUIRE TRACEFLAG function is not supported.
  • INQUIRE TRACETYPE
    The INQUIRE TRACETYPE function is not supported.
  • INQUIRE TRANCLASS
    The INQUIRE TRANCLASS function is supported.
  • INQUIRE TRANDUMPCODE
    The INQUIRE TRANDUMPCODE function is not supported.
  • INQUIRE TRANSACTION
    The INQUIRE TRANSACTION function is supported.
  • INQUIRE TSMODEL
    The INQUIRE TSMODEL function is supported.
  • INQUIRE TSPOOL
    The INQUIRE TSPOOL function is not supported.
  • INQUIRE TSQNAME
    The INQUIRE TSQNAME function is supported.
  • INQUIRE TSQUEUE
    The INQUIRE TSQUEUE function is supported.
  • INQUIRE UOW
    The INQUIRE UOW function is not supported.
  • INQUIRE UOWDSNFAIL
    The INQUIRE UOWDSNFAIL function is not supported.
  • INQUIRE UOWENQ
    The INQUIRE UOWENQ function is not supported.
  • INQUIRE UOWLINK
    The INQUIRE UOWLINK function is not supported.
  • INQUIRE URIMAP
    The INQUIRE URIMAP function is supported.
  • INQUIRE VOLUME
    The INQUIRE VOLUME function is not supported.
  • INQUIRE VTAM
    The INQUIRE VTAM function is not supported.
  • INQUIRE WEB
    The INQUIRE WEB function is not supported.
  • INQUIRE WEBSERVICE
    The INQUIRE WEBSERVICE function is supported.
  • INQUIRE XMLTRANSFORM
    The INQUIRE XMLTRANSFORM function is supported.
  • PERFORM CORBASERVER
    The PERFORM CORBASERVER function is not supported.
  • PERFORM DELETSHIPPED
    The PERFORM DELETSHIPPED function is not supported.
  • PERFORM DJAR
    The PERFORM DJAR function is not supported.
  • PERFORM DUMP
    The PERFORM DUMP function is supported.
  • PERFORM ENDAFFINITY
    The PERFORM ENDAFFINITY function is not supported.
  • PERFORM RESETTIME
    The PERFORM RESETTIME function is supported.
  • PERFORM SECURITY REBUILD
    The PERFORM SECURITY REBUILD function is not supported.
  • PERFORM SHUTDOWN
    The PERFORM SHUTDOWN function is supported.
  • PERFORM STATISTICS RECORD
    The PERFORM STATISTICS RECORD function is not supported.
  • RESYNC ENTRYNAME
    The RESYNC ENTRYNAME function is not supported.
  • SET AUTOINSTALL
    The SET AUTOINSTALL function is not supported.
  • SET BRFACILITY
    The SET BRFACILITY function is not supported.
  • SET BUNDLE
    The SET BUNDLE function is supported.
  • SET CONNECTION
    The SET CONNECTION function is supported.
  • SET CORBASERVER
    The SET CORBASERVER function is not supported.
  • SET DATASET
    The SET DATASET function is supported.
  • SET DB2CONN
    The SET DB2CONN function is not supported.
  • SET DB2ENTRY
    The SET DB2ENTRY function is not supported.
  • SET DB2TRAN
    The SET DB2TRAN function is not supported.
  • SET DELETSHIPPED
    The SET DELETSHIPPED function is not supported.
  • SET DISPATCHER
    The SET DISPATCHER function is not supported.
  • SET DOCTEMPLATE
    The SET DOCTEMPLATE function is supported.
  • SET DSNAME
    The SET DSNAME function is not supported.
  • SET DUMPDS
    The SET DUMPDS function is not supported.
  • SET ENQMODEL
    The SET ENQMODEL function is supported.
  • SET FILE
    The SET FILE function is supported.
  • SET IRC
    The SET IRC function is not supported.
  • SET JOURNALNAME
    The SET JOURNALNAME function is not supported.
  • SET JOURNALNUM
    The SET JOURNALNUM function is supported.
  • SET JVMPOOL
    The SET JVMPOOL function is not supported.
  • SET MODENAME
    The SET MODENAME function is not supported.
  • SET MONITOR
    The SET MONITOR function is not supported.
  • SET NETNAME
    The SET NETNAME function is supported.
  • SET PIPELINE
    The SET PIPELINE function is supported.
  • SET PROCESSTYPE
    The SET PROCESSTYPE function is not supported.
  • SET PROGRAM
    The SET PROGRAM function is supported.
  • SET STATISTICS
    The SET STATISTICS function is not supported.
  • SET SYSDUMPCODE
    The SET SYSDUMPCODE function is not supported.
  • SET SYSTEM
    The SET SYSTEM function is supported.
  • SET TASK
    The SET TASK function is supported.
  • SET TCLASS
    The SET TCLASS function is supported.
  • SET TCPIP
    The SET TCPIP function is not supported.
  • SET TCPIPSERVICE
    The SET TCPIPSERVICE function is supported.
  • SET TDQUEUE
    The SET TDQUEUE function is supported.
  • SET TERMINAL
    The SET TERMINAL function is supported.
  • SET TRACEDEST
    The SET TRACEDEST function is not supported.
  • SET TRACEFLAG
    The SET TRACEFLAG function is not supported.
  • SET TRACETYPE
    The SET TRACETYPE function is not supported.
  • SET TRANCLASS
    The SET TRANCLASS function is supported.
  • SET TRANDUMPCODE
    The SET TRANDUMPCODE function is not supported.
  • SET TRANSACTION
    The SET TRANSACTION function is supported.
  • SET TSQNAME
    The SET TSQNAME function is not supported.
  • SET TSQUEUE
    The SET TSQUEUE function is not supported.
  • SET UOW
    The SET UOW function is not supported.
  • SET UOWLINK
    The SET UOWLINK function is not supported.
  • SET URIMAP
    The SET URIMAP function is supported.
  • SET VOLUME
    The SET VOLUME function is not supported.
  • SET VTAM
    The SET VTAM function is not supported.
  • SET WEB
    The SET WEB function is not supported.
  • SET WEBSERVICE
    The SET WEBSERVICE function is supported.
Parent topic: CICS Support Commands
Related reference
CWS SPI Calls


ACQUIRE TERMINAL

The ACQUIRE TERMINAL function is not supported.

Parent topic: CICS SPI Calls


COLLECT STATISTICS

The COLLECT STATISTICS function is not supported.

Operand | Support
AUTOINSTALL | Recognized
CONNECTION (data-value) | Recognized
CORBASERVER | Recognized
DISPATCHER | Recognized
DTB | Recognized
FILE (data-value) | Recognized
IRCBATCH | Recognized
JOURNALNUM (data-value) | Recognized
JVMPOOL | Recognized
LASTRESET (data-area) | Recognized
LASTRESETHRS (data-area) | Recognized
LASTRESETMIN (data-area) | Recognized
LASTRESETSEC (data-area) | Recognized
LSRPOOL (data-value) | Recognized
MONITOR (data-value) | Recognized
PROGRAM (data-value) | Recognized
REQUESTMODEL | Recognized
SET (ptr-ref) | Recognized
STORAGE | Recognized
SYSDUMPCODE (data-value) | Recognized
TABLEMGR | Recognized
TASKCONTROL | Recognized
TCLASS (data-area) | Recognized
TCPIP | Recognized
TCPIPSERVICE | Recognized
TDQUEUE (data-value) | Recognized
TERMINAL (data-value) | Recognized
TRANDUMPCODE (data-value) | Recognized
TRANSACTION (data-value) | Recognized
TSQUEUE | Recognized
VTAM | Recognized
Parent topic: CICS SPI Calls


CREATE CONNECTION

The CREATE CONNECTION function is not supported.

Parent topic: CICS SPI Calls


CREATE CORBASERVER

The CREATE CORBASERVER function is not supported.

Parent topic: CICS SPI Calls


CREATE DB2CONN

The CREATE DB2CONN function is not supported.

Parent topic: CICS SPI Calls


CREATE DB2ENTRY

The CREATE DB2ENTRY function is not supported.

Parent topic: CICS SPI Calls


CREATE DB2TRAN

The CREATE DB2TRAN function is not supported.

Parent topic: CICS SPI Calls


CREATE DJAR

The CREATE DJAR function is not supported.

Parent topic: CICS SPI Calls


CREATE DOCTEMPLATE

The CREATE DOCTEMPLATE function is not supported.

Operand | Support
ATTRIBUTES (data-area) | Recognized
ATTRLEN (data-value) | Recognized
DOCTEMPLATE (data-value) | Recognized
LOG (cvda) | Recognized
LOGMESSAGE (data-value) | Recognized
NOLOG (cvda) | Recognized
Parent topic: CICS SPI Calls


CREATE ENQMODEL

The CREATE ENQMODEL function is not supported.

Parent topic: CICS SPI Calls


CREATE FILE

The CREATE FILE function is not supported.

Parent topic: CICS SPI Calls


CREATE JOURNALMODEL

The CREATE JOURNALMODEL function is not supported.

Parent topic: CICS SPI Calls


CREATE LSRPOOL

The CREATE LSRPOOL function is not supported.

Parent topic: CICS SPI Calls


CREATE MAPSET

The CREATE MAPSET function is not supported.

Parent topic: CICS SPI Calls


CREATE PARTITIONSET

The CREATE PARTITIONSET function is not supported.

Parent topic: CICS SPI Calls


CREATE PARTNER

The CREATE PARTNER function is not supported.

Parent topic: CICS SPI Calls


CREATE PROCESSTYPE

The CREATE PROCESSTYPE function is not supported.

Parent topic: CICS SPI Calls


CREATE PROFILE

The CREATE PROFILE function is not supported.

Parent topic: CICS SPI Calls


CREATE PROGRAM

The CREATE PROGRAM function is not supported.

Parent topic: CICS SPI Calls


CREATE REQUESTMODEL

The CREATE REQUESTMODEL function is not supported.

Parent topic: CICS SPI Calls


CREATE SESSIONS

The CREATE SESSIONS function is not supported.

Parent topic: CICS SPI Calls


CREATE TCPIPSERVICE

The CREATE TCPIPSERVICE function is not supported.

Parent topic: CICS SPI Calls


CREATE TDQUEUE

The CREATE TDQUEUE function is not supported.

Parent topic: CICS SPI Calls


CREATE TERMINAL

The CREATE TERMINAL function is not supported.

Parent topic: CICS SPI Calls


CREATE TRANCLASS

The CREATE TRANCLASS function is not supported.

Parent topic: CICS SPI Calls


CREATE TRANSACTION

The CREATE TRANSACTION function is not supported.

Parent topic: CICS SPI Calls


CREATE TSMODEL

The CREATE TSMODEL function is not supported.

Parent topic: CICS SPI Calls


CREATE TYPETERM

The CREATE TYPETERM function is not supported.

Parent topic: CICS SPI Calls


DISABLE PROGRAM

The DISABLE PROGRAM function is supported.

Operand | Support
ENTRYNAME (data-value) | Full
EXIT (data-value) | Full
EXITALL | Full
FORMATEDF | Validated
PROGRAM (data-value) | Full
SHUTDOWN | Full
STOP | Full
TASKSTART | Full
Parent topic: CICS SPI Calls


DISCARD AUTINSTMODEL

The DISCARD AUTINSTMODEL function is not supported.

Operand | Support
AUTINSTMODEL (data-value) | Recognized
Parent topic: CICS SPI Calls


DISCARD CONNECTION

The DISCARD CONNECTION function is not supported.

Parent topic: CICS SPI Calls


DISCARD CORBASERVER

The DISCARD CORBASERVER function is not supported.

Parent topic: CICS SPI Calls


DISCARD DB2CONN

The DISCARD DB2CONN function is not supported.

Parent topic: CICS SPI Calls


DISCARD DB2ENTRY

The DISCARD DB2ENTRY function is not supported.

Parent topic: CICS SPI Calls


DISCARD DB2TRAN

The DISCARD DB2TRAN function is not supported.

Parent topic: CICS SPI Calls


DISCARD DJAR

The DISCARD DJAR function is not supported.

Parent topic: CICS SPI Calls


DISCARD DOCTEMPLATE

The DISCARD DOCTEMPLATE function is supported.

Operand | Support
DOCTEMPLATE (data-value) | Full
Parent topic: CICS SPI Calls


DISCARD ENQMODEL

The DISCARD ENQMODEL function is supported.

Operand | Support
ENQMODEL (data-value) | Full
Parent topic: CICS SPI Calls


DISCARD FILE

The DISCARD FILE function is not supported.

Operand | Support
FILE (data-value) | Recognized
Parent topic: CICS SPI Calls


DISCARD JOURNALMODEL

The DISCARD JOURNALMODEL function is not supported.

Parent topic: CICS SPI Calls


DISCARD JOURNALNAME

The DISCARD JOURNALNAME function is not supported.

Parent topic: CICS SPI Calls


DISCARD PARTNER

The DISCARD PARTNER function is not supported.

Operand | Support
PARTNER (data-value) | Recognized
Parent topic: CICS SPI Calls


DISCARD PIPELINE

The DISCARD PIPELINE function is supported.

Operand | Support
PIPELINE (data-value) | Full
Parent topic: CICS SPI Calls


DISCARD PROCESSTYPE

The DISCARD PROCESSTYPE function is not supported.

Parent topic: CICS SPI Calls


DISCARD PROFILE

The DISCARD PROFILE function is not supported.

Operand | Support
PROFILE (data-value) | Recognized
Parent topic: CICS SPI Calls


DISCARD PROGRAM

The DISCARD PROGRAM function is supported.

Operand | Support
PROGRAM (data-value) | Full
Parent topic: CICS SPI Calls


DISCARD REQUESTMODEL

The DISCARD REQUESTMODEL function is not supported.

Parent topic: CICS SPI Calls


DISCARD TCPIPSERVICE

The DISCARD TCPIPSERVICE function is supported.

Operand | Support
TCPIPSERVICE (data-value) | Full
Parent topic: CICS SPI Calls


DISCARD TDQUEUE

The DISCARD TDQUEUE function is not supported.

Parent topic: CICS SPI Calls


DISCARD TERMINAL

The DISCARD TERMINAL function is not supported.

Parent topic: CICS SPI Calls


DISCARD TRANCLASS

The DISCARD TRANCLASS function is not supported.

Parent topic: CICS SPI Calls


DISCARD TRANSACTION

The DISCARD TRANSACTION function is not supported.

Operand | Support
TRANSACTION (data-value) | Recognized
Parent topic: CICS SPI Calls


DISCARD TSMODEL

The DISCARD TSMODEL function is supported.

Operand | Support
TSMODEL (data-value) | Full
Parent topic: CICS SPI Calls


DISCARD URIMAP

The DISCARD URIMAP function is supported.

Operand | Support
URIMAP (data-value) | Full
Parent topic: CICS SPI Calls


DISCARD WEBSERVICE

The DISCARD WEBSERVICE function is supported.

Operand | Support
WEBSERVICE (data-value) | Full
Parent topic: CICS SPI Calls


ENABLE PROGRAM

The ENABLE PROGRAM function is supported.

Operand | Support
ENTRY (ptr-ref) | Full
ENTRYNAME (data-value) | Full
EXIT (data-value) | Full
FORMATEDF | Validated
GAENTRYNAME (data-value) | Full
GALENGTH (data-value) | Full
LINKEDITMODE | Validated
PROGRAM (data-value) | Full
SHUTDOWN | Full
START | Full
TALENGTH (data-value) | Full
TASKSTART | Full
Parent topic: CICS SPI Calls


EXTRACT ATTACH

The EXTRACT ATTACH function is not supported.

Parent topic: CICS SPI Calls


EXTRACT ATTRIBUTES

The EXTRACT ATTRIBUTES function is supported.

Operand | Support
CONVID (data-value) | Full
SESSION (data-value) | Full
STATE (cvda) | Full
Parent topic: CICS SPI Calls


EXTRACT CERTIFICATE

The EXTRACT CERTIFICATE function is supported.

Operand | Support
CERTIFICATE (data-area) | Full
COMMONNAME (data-area) | Full
COMMONNAMLEN (data-area) | Full
COUNTRY (data-area) | Full
COUNTRYLEN (data-area) | Full
ISSUER | Full
LENGTH (data-area) | Full
LOCALITY (data-area) | Full
LOCALITYLEN (data-area) | Full
ORGANIZATION (data-area) | Full
ORGANIZATLEN (data-area) | Full
ORGUNIT (data-area) | Full
ORGUNITLEN (data-area) | Full
OWNER | Full
SERIALNUM (data-area) | Full
SERIALNUMLEN (data-area) | Full
STATE (data-area) | Full
STATELEN (data-area) | Full
USERID (data-area) | Full
Parent topic: CICS SPI Calls


EXTRACT EXIT

The EXTRACT EXIT function is supported.

Operand | Support
ENTRYNAME (data-value) | Full
GALENGTH (data-area) | Full
GASET (ptr-ref) | Full
PROGRAM (data-value) | Full
Parent topic: CICS SPI Calls


EXTRACT LOGONMSG

The EXTRACT LOGONMSG function is not supported.

Operand | Support
INTO (data-area) | Recognized
LENGTH (data-area) | Recognized
SET (ptr-ref) | Recognized
Parent topic: CICS SPI Calls


EXTRACT PROCESS

The EXTRACT PROCESS function is supported.

Operand | Support
CONVID (data-area) | Full
MAXPROCLEN (data-area) | Full
PIPLENGTH (data-area) | Full
PIPLIST (ptr-ref) | Full
PROCLENGTH (data-area) | Full
PROCNAME (data-area) | Full
SESSION (data-area) | Full
SYNCLEVEL (data-area) | Full
Parent topic: CICS SPI Calls


EXTRACT TCPIP

The EXTRACT TCPIP function is supported.

Operand | Support
AUTHENTICATE (cvda) | Full
CADDRLENGTH (data-area) | Full
CLIENTADDR (data-area) | Full
CLIENTADDRNU (data-area) | Full
CLIENTNAME (data-area) | Full
CNAMELENGTH (data-area) | Full
MAXDATALEN (data-area) | Full
PORTNUMBER (data-area) | Full
PORTNUMNU (data-area) | Full
PRIVACY (data-area) | Partial: returns "NOTSUPPORTED"
SADDRLENGTH (data-area) | Full
SERVERADDR (data-area) | Full
SERVERADDRNU (data-area) | Full
SERVERNAME (data-area) | Full
SNAMELENGTH (data-area) | Full
SSLTYPE (cvda) | Full
TCPIPSERVICE (data-area) | Full
Parent topic: CICS SPI Calls


EXTRACT TCT

The EXTRACT TCT function is not supported.

Parent topic: CICS SPI Calls


EXTRACT WEB

The EXTRACT WEB function is supported.

Operand | Support
HOST (data-area) | Full
HOSTLENGTH (data-value) | Full
HOSTTYPE (data-value) | Full
HTTPMETHOD (data-area) | Full
HTTPVERSION (data-area) | Full
METHODLENGTH (data-value) | Full
PATH (data-area) | Full
PATHLENGTH (data-value) | Full
PORTNUMBER (data-area) | Full
QUERYSTRING (data-area) | Full
QUERYSTRLEN (data-value) | Full
REALM (data-area) | Full
REALMLEN (data-value) | Full
REQUESTTYPE (cvda) | Full
SCHEME (cvda) | Full
SESSTOKEN (data-area) | Full
URIMAP (data-area) | Full
VERSIONLEN (data-value) | Full
Parent topic: CICS SPI Calls


INQUIRE ACTIVITYID

The INQUIRE ACTIVITYID function is not supported.

Parent topic: CICS SPI Calls


INQUIRE AUTINSTMODEL

The INQUIRE AUTINSTMODEL function is not supported.

Operand | Support
AUTINSTMODEL (data-value) | Recognized
NEXT | Recognized
Parent topic: CICS SPI Calls


INQUIRE AUTOINSTALL

The INQUIRE AUTOINSTALL function is not supported.

Operand | Support
CURREQS (data-area) | Recognized
ENABLESTATUS (data-area) | Recognized
MAXREQS (data-area) | Recognized
PROGRAM (data-area) | Recognized
Parent topic: CICS SPI Calls


INQUIRE BEAN

The INQUIRE BEAN function is not supported.

Parent topic: CICS SPI Calls


INQUIRE BRFACILITY

The INQUIRE BRFACILITY function is not supported.

Parent topic: CICS SPI Calls


INQUIRE CFDTPOOL

The INQUIRE CFDTPOOL function is not supported.

Parent topic: CICS SPI Calls


INQUIRE CONNECTION

The INQUIRE CONNECTION function is supported.

Operand | Support
ACCESSMETHOD (cvda) | Partial: returns "VTAM"
ACQSTATUS (cvda) | Full
AUTOCONNECT (cvda) | Partial: returns "NONAUTOCONN"
CONNECTION (data-value) | Full
CONNSTATUS (cvda) | Full
EXITTRACING (cvda) | Partial: returns "NOEXITTRACE"
NETNAME (data-area) | Full
NEXT | Full
PENDSTATUS (cvda) | Partial: returns "NOTPENDING"
PROTOCOL (cvda) | Partial: returns "APPC"
SERVSTATUS (cvda) | Full
XLNSTATUS (cvda) | Partial: returns "XNOTDONE"
ZCPTRACING (cvda) | Partial: returns "NOZCPTRACE"
Parent topic: CICS SPI Calls


INQUIRE CONTAINER

The INQUIRE CONTAINER function is not supported.

Parent topic: CICS SPI Calls


INQUIRE CORBASERVER

The INQUIRE CORBASERVER function is not supported.

Parent topic: CICS SPI Calls


INQUIRE DATASET

The INQUIRE DATASET function is supported.

Operand | Support
ACCESSMETHOD (cvda) | Partial: returns "VSAM"
ADD (cvda) | Full
BASEDSNAME (data-area) | Full
BASENAME (data-area) | Full
BLOCKFORMAT (cvda) | Partial: returns "BLOCKED"
BLOCKKEYLEN (data-area) | Partial: returns 0
BLOCKSIZE (data-area) | Partial: returns 0
BROWSE (cvda) | Full
CATNAME (data-area) | Validated
CFDTPOOL (data-area) | Validated
DATASET (data-value) | Full
DELETE (cvda) | Full
DISPOSITION (cvda) | Partial: returns "SHARE"
DSNAME (data-area) | Full
EMPTYSTATUS (cvda) | Full
ENABLESTATUS (cvda) | Full
EXCLUSIVE (cvda) | Partial: returns "NOTAPPLIC"
FILE (data-value) | Full
FWDRECSTATUS (cvda) | Partial: returns "NOTFWDRCVBLE"
JOURNALNUM (data-area) | Partial: If the Journal is a remote file, returns -1 If FWDRECSTATUS=NOTFWDRCVBLE, returns 0 If FWDRECSTATUS=FWDRECOVBLE, returns 1
KEYLENGTH (data-area) | Full
KEYPOSITION (data-area) | Full
LOADTYPE (cvda) | Validated
LSRPOOLID (data-area) | Partial: returns 0
MAXNUMRECS (data-area) | Partial: returns 0
NEXT | Full
OBJECT (cvda) | Full
OBJECTNAME (data-area) | Full
OPENSTATUS (cvda) | Full
READ (cvda) | Full
READINTEG (cvda) | Validated
RECORDFORMAT (cvda) | Full
RECORDSIZE (data-area) | Full
RECOVSTATUS (cvda) | Full
RELTYPE (cvda) | Partial: returns "NOTAPPLIC"
REMOTENAME (data-area) | Full
REMOTESYSTEM (data-area) | Full
REMOTETABLE (cvda) | Validated
RLSACCESS (cvda) | Validated
STRINGS (data-area) | Partial: returns 1
TABLE (cvda) | Partial: returns "NOTTABLE"
TABLENAME (data-area) | Validated
TYPE (cvda) | Full
UPDATE (cvda) | Full
UPDATEMODEL (cvda) | Validated
Parent topic: CICS SPI Calls


INQUIRE DB2CONN

The INQUIRE DB2CONN function is not supported.

Parent topic: CICS SPI Calls


INQUIRE DB2ENTRY

The INQUIRE DB2ENTRY function is not supported.

Parent topic: CICS SPI Calls


INQUIRE DB2TRAN

The INQUIRE DB2TRAN function is not supported.

Parent topic: CICS SPI Calls


INQUIRE DELETSHIPPED

The INQUIRE DELETSHIPPED function is not supported.

Parent topic: CICS SPI Calls


INQUIRE DISPATCHER

The INQUIRE DISPATCHER function is not supported.

Parent topic: CICS SPI Calls


INQUIRE DJAR

The INQUIRE DJAR function is not supported.

Parent topic: CICS SPI Calls


INQUIRE DOCTEMPLATE

The INQUIRE DOCTEMPLATE function is supported.

Operand | Support
APPENDCRLF (cvda) | Full
CACHESIZE (data-area) | Full
DDNAME (data-area) | Full
DOCTEMPLATE (data-value) | Full
DSNAME (data-area) | Full
EXITPGM (data-area) | Full
FILE (data-area) | Full
HFSFILE (data-area) | Full
MEMBER (data-area) | Full
NEXT | Full
PROGRAM (data-area) | Full
TDQUEUE (data-area) | Full
TEMPLATENAME (data-area) | Full
TEMPLATETYPE (cvda) | Full
TSQUEUE (data-area) | Full
TYPE (cvda) | Full
Parent topic: CICS SPI Calls


INQUIRE DSNAME

The INQUIRE DSNAME function is not supported.

Operand | Support
ACCESSMETHOD (cvda) | Recognized
BACKUPTYPE (cvda) | Recognized
BASEDSNAME (data-area) | Recognized
BKOUTSTATUS (cvda) | Recognized
DSNAME (data-value) | Recognized
FILECOUNT (data-area) | Recognized
FWDRECOVLOG (data-area) | Recognized
NEXT | Recognized
OBJECT (cvda) | Recognized
RECOVSTATUS (cvda) | Recognized
VALIDITY (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE DUMPDS

The INQUIRE DUMPDS function is not supported.

Operand | Support
CURRENTDDS (data-area) | Recognized
INITIALDDS (data-area) | Recognized
OPENSTATUS (cvda) | Recognized
SWITCHSTATUS (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE ENQ

The INQUIRE ENQ function is not supported.

Parent topic: CICS SPI Calls


INQUIRE ENQMODEL

The INQUIRE ENQMODEL function is supported.

Operand | Support
ENQMODEL (data-value) | Full
ENQNAME (data-area) | Full
ENQSCOPE (data-area) | Full
NEXT | Full
STATUS (cvda) | Full
Parent topic: CICS SPI Calls


INQUIRE EVENT

The INQUIRE EVENT function is not supported.

Parent topic: CICS SPI Calls


INQUIRE EXCI

The INQUIRE EXCI function is not supported.

Parent topic: CICS SPI Calls


INQUIRE EXITPROGRAM

The INQUIRE EXITPROGRAM function is not supported.

Parent topic: CICS SPI Calls


INQUIRE FILE

The INQUIRE FILE function is supported.

Operand | Support
ACCESSMETHOD (cvda) | Partial: returns "VSAM"
ADD (cvda) | Full
BASEDSNAME (data-area) | Full
BASENAME (data-area) | Full
BLOCKFORMAT (cvda) | Partial: returns "BLOCKED"
BLOCKKEYLEN (data-area) | Partial: returns 0
BLOCKSIZE (data-area) | Partial: returns 0
BROWSE (cvda) | Full
CATNAME (data-area) | Validated
CFDTPOOL (data-area) | Validated
DATASET (data-value) | Full
DELETE (cvda) | Full
DISPOSITION (cvda) | Partial: returns "SHARE"
DSNAME (data-area) | Full
EMPTYSTATUS (cvda) | Full
ENABLESTATUS (cvda) | Full
EXCLUSIVE (cvda) | Partial: returns "NOTAPPLIC"
FILE (data-value) | Full
FWDRECSTATUS (cvda) | Partial: returns "NOTFWDRCVBLE"
JOURNALNUM (data-area) | Partial: If the Journal is a remote file, returns -1 If FWDRECSTATUS=NOTFWDRCVBLE, returns 0 If FWDRECSTATUS=FWDRECOVBLE, returns 1
KEYLENGTH (data-area) | Full
KEYPOSITION (data-area) | Full
LOADTYPE (cvda) | Validated
LSRPOOLID (data-area) | Partial: returns 0
MAXNUMRECS (data-area) | Partial: returns 0
NEXT | Full
OBJECT (cvda) | Full
OBJECTNAME (data-area) | Full
OPENSTATUS (cvda) | Full
READ (cvda) | Full
READINTEG (cvda) | Validated
RECORDFORMAT (cvda) | Full
RECORDSIZE (data-area) | Full
RECOVSTATUS (cvda) | Full
RELTYPE (cvda) | Partial: returns "NOTAPPLIC"
REMOTENAME (data-area) | Full
REMOTESYSTEM (data-area) | Full
REMOTETABLE (cvda) | Validated
RLSACCESS (cvda) | Validated
STRINGS (data-area) | Partial: returns 1
TABLE (cvda) | Partial: returns "NOTTABLE"
TABLENAME (data-area) | Validated
TYPE (cvda) | Full
UPDATE (cvda) | Full
UPDATEMODEL (cvda) | Validated
Parent topic: CICS SPI Calls


INQUIRE IRC

The INQUIRE IRC function is not supported.

Operand | Support
OPENSTATUS (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE JOURNALMODEL

The INQUIRE JOURNALMODEL function is not supported.

Parent topic: CICS SPI Calls


INQUIRE JOURNALNAME

The INQUIRE JOURNALNAME function is not supported.

Parent topic: CICS SPI Calls


INQUIRE JOURNALNUM

The INQUIRE JOURNALNUM function is supported.

Operand | Support
ARCHSTATUS (cvda) | Partial: returns "NOAUTOARCH"
CURRENTVOL (data-area) | Partial: returns spaces
DISKASTATUS (cvda) | Partial: returns "CURRENT"
DISKBSTATUS (cvda) | Partial: returns "NOTAPPLIC"
DISKXSTATUS (cvda) | Partial: returns "NOTAPPLIC"
JOURNALNUM (data-value) | Full
JTYPE (cvda) | Partial: returns "DISK1"
NEXT | Full
OLDESTPART (data-area) | Partial: returns spaces
OPENSTATUS (cvda) | Full
Parent topic: CICS SPI Calls


INQUIRE JVMPOOL

The INQUIRE JVMPOOL function is not supported.

Parent topic: CICS SPI Calls


INQUIRE MODENAME

The INQUIRE MODENAME function is not supported.

Operand | Support
ACTIVE (data-area) | Recognized
AUTOCONNECT (cvda) | Recognized
AVAILABLE (data-area) | Recognized
CONNECTION (data-value) | Recognized
MAXIMUM (data-area) | Recognized
MAXWINNERS (data-area) | Recognized
MODENAME (data-value) | Recognized
NEXT | Recognized
Parent topic: CICS SPI Calls


INQUIRE MONITOR

The INQUIRE MONITOR function is not supported.

Operand | Support
EVENTCLASS (cvda) | Recognized
EXCEPTCLASS (cvda) | Recognized
PERFCLASS (cvda) | Recognized
STATUS (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE NETNAME

The INQUIRE NETNAME function is supported.

Operand | Support
ACCESSMETHOD (cvda) | Partial: returns "VTAM"
ACQSTATUS (cvda) | Partial: returns "ACQUIRED"
ALTPAGEHT (data-area) | Full
ALTPAGEWD (data-area) | Full
ALTPRINTER (data-area) | Partial: returns spaces
ALTPRTCOPYST (cvda) | Partial: returns "NOALTPRTCOPY"
ALTSCRNHT (data-area) | Full
ALTSCRNWD (data-area) | Full
ALTSUFFIX (data-area) | Partial: returns spaces
APLKYBDST (cvda) | Partial: returns "NOAPLKYBD"
APLTEXTST (cvda) | Partial: returns "NOAPLTEXT"
ASCII (cvda) | Full
ATISTATUS (cvda) | Partial: returns "ATI"
AUDALARMST (cvda) | Partial: returns "AUDALARM"
AUTOCONNECT (cvda) | Full
BACKTRANSST (cvda) | Partial: returns "NOBACKTRANS"
COLORST (cvda) | Full
COPYST (cvda) | Partial: returns "NOCOPY"
CREATESESS (cvda) | Partial: returns "NOCREATE"
DATASTREAM (data-area) | Full
DEFPAGEHT (data-area) | Full
DEFPAGEWD (data-area) | Full
DEFSCRNHT (data-area) | Full
DEFSCRNWD (data-area) | Full
DEVICE (cvda) | Partial: returns "T3277L"
DEVICEST (cvda) | Full
DISCREQST (cvda) | Partial: returns "DISCREQ"
DUALCASEST (cvda) | Partial: returns "DUALCASE"
EXITTRACING (cvda) | Partial: returns "NOEXITTRACE"
EXTENDEDDSST (cvda) | Partial: returns "EXTENDEDDS"
FMHPARMST (cvda) | Partial: returns "NOFMHPARM"
FORMFEEDST (cvda) | Partial: returns "NOFORMFEED"
GCHARS (data-area) | Full
GCODES (data-area) | Full
HFORMST (cvda) | Partial: returns "NOHFORM"
HILIGHTST (cvda) | Partial: returns "HILIGHT"
KATAKANAST (cvda) | Partial: returns "NOKATAKANA"
LIGHTPENST (cvda) | Partial: returns "NOLIGHTPEN"
MODENAME (data-area) | Full
MSRCONTROLST (cvda) | Partial: returns "NOMSRCONTROL"
NATLANG (data-area) | Partial: returns "E" (meaning US English)
NATURE (cvda) | Full
NETNAME (data-value) | Full
NEXTTRANSID (data-area) | Partial: returns spaces
OBFORMATST (cvda) | Partial: returns "NOOBFORMAT"
OBOPERIDST (cvda) | Partial: returns "NOOBOPERID"
OPERID (data-area) | Full
OUTLINEST (cvda) | Partial: returns "NOOUTLINE"
PAGEHT (data-area) | Full
PAGESTATUS (cvda) | Partial: returns "PAGEABLE"
PAGEWD (data-area) | Full
PARTITIONSST (cvda) | Partial: returns "NOPARTITIONS"
PRINTADAPTST (cvda) | Partial: returns "NOPRINTADAPT"
PRINTER (data-area) | Partial: returns spaces
PROGSYMBOLST (cvda) | Partial: returns "NOPROGSYMBOL"
PRTCOPYST (cvda) | Partial: returns "NOPRTCOPY"
QUERYST (cvda) | Partial: returns "NOQUERY"
RELREQST (cvda) | Partial: (VTAM only) returns "NORELREQ"
REMOTENAME (data-area) | Partial: returns spaces
REMOTESYSTEM (data-area) | Partial: returns spaces
SCREENHEIGHT (data-area) | Full
SCREENWIDTH (data-area) | Full
SCRNHT (data-area) | Full
SCRNWD (data-area) | Full
SECURITY (cvda) | Partial: returns "NOPRESETSEC"
SERVSTATUS (cvda) | Full
SESSIONTYPE (cvda) | Partial: returns "NOTAPPLIC"
SIGNONSTATUS (cvda) | Full
SOSIST (cvda) | Partial: returns "NOSOSI"
TASKID (data-area) | Partial: returns 0 meaning no task is using the terminal
TCAMCONTROL (data-area) | Partial: returns x"00" meaning null
TERMINAL (data-area) | Full
TERMMODEL (data-area) | Partial: returns 2
TERMPRIORITY (data-area) | Full
TERMSTATUS (cvda) | Full
TEXTKYBDST (cvda) | Partial: returns "NOTEXTKYBD"
TEXTPRINTST (cvda) | Partial: returns "NOTEXTPRINT"
TRACING (cvda) | Partial: returns "STANTRACE"
TRANSACTION (data-area) | Full
TTISTATUS (cvda) | Partial: returns "TTI"
UCTRANST (cvda) | Full
USERAREA (data-area) | Full
USERAREALEN (data-area) | Full
USERID (data-area) | Full
USERNAME (data-area) | Partial: returns spaces
VALIDATIONST (cvda) | Partial: returns "NOVALIDATION"
VFORMST (cvda) | Partial: returns "NOVFORM"
ZCPTRACING (cvda) | Partial: returns "NOZCPTRACE"
Parent topic: CICS SPI Calls


INQUIRE PARTNER

The INQUIRE PARTNER function is not supported.

Operand | Support
NETNAME (data-area) | Recognized
NETWORK (data-area) | Recognized
NEXT | Recognized
PARTNER (data-value) | Recognized
PROFILE (data-area) | Recognized
TPNAME (data-area) | Recognized
TPNAMELEN (data-area) | Recognized
Parent topic: CICS SPI Calls


INQUIRE PIPELINE

The INQUIRE PIPELINE function is supported.

Operand | Support
CONFIGFILE (data-area) | Full
ENABLESTATUS (cvda) | Full
MODE (data-area) | Full
NEXT | Full
PIPELINE (data-value) | Full
RESPWAIT (data-area) | Full
SHELF (data-area) | Full
SOAPLEVEL (data-area) | Full
WSDIR (data-area) | Full
Parent topic: CICS SPI Calls


INQUIRE PROCESS

The INQUIRE PROCESS function is not supported.

Parent topic: CICS SPI Calls


INQUIRE PROCESSTYPE

The INQUIRE PROCESSTYPE function is not supported.

Parent topic: CICS SPI Calls


INQUIRE PROFILE

The INQUIRE PROFILE function is not supported.

Operand | Support
NEXT | Recognized
PROFILE (data-value) | Recognized
Parent topic: CICS SPI Calls


INQUIRE PROGRAM

The INQUIRE PROGRAM function is supported.

Operand | Support
CEDFSTATUS (cvda) | Partial: returns "NOCEDF"
COBOLTYPE (cvda) | Partial: If the program has a PPT, returns "COBOLII" If not, returns "NOTAPPLIC"
CONCURRENCY (cvda) | Validated
COPY (cvda) | Full
DATALOCATION (cvda) | Partial: returns "ANY"
DYNAMSTATUS (cvda) | Validated
ENTRYPOINT (ptr-ref) | Full
EXECKEY (cvda) | Partial: returns "CICSEXECKEY"
EXECUTIONSET (cvda) | Partial: returns "FULLAPI"
HOLDSTATUS (cvda) | Full
HOTPOOLING (cvda) | Validated
JVMCLASS (data-area) | Validated
JVMDEBUG (cvda) | Validated
JVMPROFILE (cvda) | Validated
LANGDEDUCED (cvda) | Validated
LANGUAGE (cvda) | Partial: returns "ASSEMBLER", "C", "COBOL", "PLI" or "NOTAPPLIC" (based on the program's PPT entry).
LENGTH (data-area) | Full
LOADPOINT (ptr-ref) | Full
LPASTATUS (cvda) | Partial: returns "NOTLPA"
NEXT | Full
PROGRAM (data-value) | Full
PROGTYPE (cvda) | Partial: returns "PROGRAM"
REMOTENAME (data-area) | Full
REMOTESYSTEM (data-area) | Full
RESCOUNT (data-area) | Full
RUNTIME (cvda) | Validated
SHARESTATUS (cvda) | Partial: if program is local, returns "PRIVATE"; if program is remote, returns "NOTAPPLIC"
STATUS (cvda) | Full
TRANSID (data-area) | Full
USECOUNT (data-area) | Full
Parent topic: CICS SPI Calls


INQUIRE REQID

The INQUIRE REQID function is supported.

Operand | Support
AFTER (data-area) | Validated
AT (data-area) | Validated
FMHSTATUS (cvda) | Validated
INTERVAL (data-area) | Full
LENGTH (data-value) | Validated
NEXT | Full
REQID (data-value) | Full
REQTYPE (cvda) | Validated
RTERMID (data-value) | Validated
RTRANSID (data-value) | Validated
SET (ptr-ref) | Validated
TERMID (data-value) | Validated
TIME (data-area) | Validated
TRANSID (data-value) | Full
Parent topic: CICS SPI Calls


INQUIRE REQUESTMODEL

The INQUIRE REQUESTMODEL function is not supported.

Parent topic: CICS SPI Calls


INQUIRE RRMS

The INQUIRE RRMS function is not supported.

Parent topic: CICS SPI Calls


INQUIRE STATISTICS

The INQUIRE STATISTICS function is not supported.

Operand | Support
ENDOFDAY (data-area) | Recognized
ENDOFDAYHRS (data-area) | Recognized
ENDOFDAYMIN (data-area) | Recognized
ENDOFDAYSEC (data-area) | Recognized
INTERVAL (data-area) | Recognized
INTERVALHRS (data-area) | Recognized
INTERVALMIN (data-area) | Recognized
INTERVALSEC (data-area) | Recognized
NEXTTIME (data-area) | Recognized
NEXTTIMEHRS (data-area) | Recognized
NEXTTIMEMIN (data-area) | Recognized
NEXTTIMESEC (data-area) | Recognized
RECORDING (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE STORAGE

The INQUIRE STORAGE function is not supported.

Parent topic: CICS SPI Calls


INQUIRE STREAMNAME

The INQUIRE STREAMNAME function is not supported.

Parent topic: CICS SPI Calls


INQUIRE SYSDUMPCODE

The INQUIRE SYSDUMPCODE function is not supported.

Operand | Support
CURRENT (data-area) | Recognized
MAXIMUM (data-area) | Recognized
NEXT | Recognized
SHUTOPTION (cvda) | Recognized
SYSDUMPCODE (data-value) | Recognized
SYSDUMPING (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE SYSTEM

The INQUIRE SYSTEM function is supported.

Operand | Support
ACTOPENTCBS (data-area) | Validated
AKP (data-area) | Partial: returns 0 meaning keypoints are not being taken
AMAXTASKS (data-area) | Full
CDSASIZE (data-area) | Partial: returns 0
CICSSTATUS (cvda) | Full
CICSSYS (data-area) | Partial: returns "U", "2" or "D"
CICSTSLEVEL (data-area) | Validated
CMDPROTECT (cvda) | Validated
COLDSTATUS (cvda) | Validated
CSCS (data-area) | Partial: returns 0
DB2CONN (data-area) | Validated
DFLTUSER (data-area) | Validated
DSALIMIT (data-area) | Validated
DSRTPROGRAM (data-area) | Validated
DTRPROGRAM (data-area) | Partial: returns spaces
DUMPING (cvda) | Partial: returns "SYSDUMP"
ECDSASIZE (data-area) | Partial: returns 0
ECSCS (data-area) | Partial: returns 0
EDSALIMIT (data-area) | Validated
ERDSASIZE (data-area) | Partial: returns 0
ERSCS (data-area) | Partial: returns 0
ESDSASIZE (data-area) | Validated
EUDSASIZE (data-area) | Partial: returns 0
EUSCS (data-area) | Partial: returns 0
FORCEQR (cvda) | Validated
GMMLENGTH (data-area) | Validated
GMMTEXT (data-area) | Validated
GMMTRANID (data-area) | Full
INITSTATUS (cvda) | Validated
JOBNAME (data-area) | Full
LOGDEFER (data-area) | Validated
MAXOPENTCBS (data-area) | Validated
MAXTASKS (data-area) | Partial: returns 999 (x"03E7")
MROBATCH (data-area) | Partial: returns 0
OPREL (data-area) | Full
OPSYS (data-area) | Partial: returns "U", "2" or "D"
OSLEVEL (data-area) | Validated
PROGAUTOCTLG (cvda) | Validated
PROGAUTOEXIT (data-area) | Validated
PROGAUTOINST (cvda) | Validated
PRTYAGING (data-area) | Partial: returns 0
RDSASIZE (data-area) | Validated
REENTPROTECT (cvda) | Validated
RELEASE (data-area) | Full
RLSSTATUS (cvda) | Validated
RUNAWAY (data-area) | Partial: returns 0
SCANDELAY (data-area) | Partial: returns 0
SDSASIZE (data-area) | Validated
SDTRAN (data-area) | Validated
SECURITYMGR (cvda) | Partial: returns "NOSECURITY"
SHUTSTATUS (cvda) | Full
SOSSTATUS (cvda) | Validated
STARTUP (cvda) | Partial: returns "COLDSTART"
STARTUPDATE (data-area) | Validated
STOREPROTECT (cvda) | Partial: returns "INACTIVE"
TIME (data-area) | Partial: returns 0
TRANISOLATE (cvda) | Validated
UDSASIZE (data-area) | Partial: returns 0
USCS (data-area) | Partial: returns 0
XRFSTATUS (cvda) | Partial: returns "PRIMARY"
Parent topic: CICS SPI Calls


INQUIRE TASK

The INQUIRE TASK function is supported.

Operand | Support
ACTIVITY (data-area) | Validated
ACTIVITYID (data-area) | Validated
ATTACHTIME (data-area) | Full
BRIDGE (data-area) | Full
CMDSEC (cvda) | Partial: returns "CMDSECNO"
DB2PLAN (data-area) | Validated
DTB (cvda) | Partial: returns "BACKOUT"
DTIMEOUT (data-area) | Partial: returns 0
DUMPING (cvda) | Full
FACILITY (data-area) | Full
FACILITYTYPE (cvda) | Full
IDENTIFIER (data-area) | Full
INDOUBT (cvda) | Validated
INDOUBTMINS (data-area) | Validated
INDOUBTWAIT (cvda) | Validated
ISOLATEST (cvda) | Partial: returns "ISOLATE"
PRIORITY (data-area) | Full
PROCESS (data-area) | Validated
PROCESSTYPE (data-area) | Validated
PROFILE (data-area) | Partial: returns "DFHCICST"
PROGRAM (data-area) | Full
PURGEABILITY (cvda) | Partial: returns "NOTPURGEABLE"
RECUNITID (data-area) | Full
REMOTENAME (data-area) | Full
REMOTESYSTEM (data-area) | Full
RESNAME (data-area) | Full
RESSEC (cvda) | Full
ROUTING (cvda) | Full
RTIMEOUT (data-area) | Full
RUNAWAY (data-area) | Partial: returns 0
RUNSTATUS (cvda) | Partial: returns "RUNNING" or "SUSPENDED"
SCRNSIZE (cvda) | Partial: returns "DEFAULT"
STARTCODE (data-area) | Full
STORAGECLEAR (cvda) | Partial: returns "NOCLEAR"
SUSPENDTIME (data-area) | Partial: returns 0 meaning the task is running or dispatchable
SUSPENDTYPE (data-area) | Partial: returns spaces meaning the task is running or dispatchable
SUSPENDVALUE (data-area) | Partial: returns spaces meaning the task is running or dispatchable
TASK (data-value) | Full
TASKDATAKEY (cvda) | Partial: returns "USERDATAKEY"
TASKDATALOC (cvda) | Partial: returns "ANY"
TCB (cvda) | Validated
TCLASS (data-area) | Full
TRACING (cvda) | Full
TRANCLASS (data-area) | Partial: returns "DFHTCL00"
TRANPRIORITY (data-area) | Full
TRANSACTION (data-area) | Full
TRPROF (data-area) | Partial: returns spaces
TWASIZE (data-area) | Full
UOW (data-area) | Validated
USERID (data-area) | Full
Parent topic: CICS SPI Calls


INQUIRE TASK LIST

The INQUIRE TASK LIST function is supported.

Operand | Support
DISPATCHABLE | Full
LISTSIZE (data-area) | Full
RUNNING | Full
SET (ptr-ref) | Full
SETTRANSID (ptr-ref) | Full
SUSPENDED | Full
Parent topic: CICS SPI Calls


INQUIRE TCLASS

The INQUIRE TCLASS function is supported.

Operand | Support
CURRENT (data-area) | Full
MAXIMUM (data-area) | Full
TCLASS (data-value) | Full
Parent topic: CICS SPI Calls


INQUIRE TCPIP

The INQUIRE TCPIP function is not supported.

Parent topic: CICS SPI Calls


INQUIRE TCPIPSERVICE

The INQUIRE TCPIPSERVICE function is supported.

Operand | Support
ATTACHSEC (cvda) | Full
AUTHENTICATE (cvda) | Full
BACKLOG (data-area) | Full
CERTIFICATE (data-area) | Full
CIPHERS (data-area) | Full
CLOSETIMEOUT (data-area) | Full
CONNECTIONS (data-area) | Partial: returns 0
DNSGROUP (data-area) | Full
DNSSTATUS (cvda) | Partial: returns "UNAVAILABLE"
GRPCRITICAL (cvda) | Full
IPADDRESS (data-area) | Full
MAXDATALEN (data-area) | Full
NEXT | Full
NUMCIPHERS (data-area) | Full
OPENSTATUS (cvda) | Partial: returns only "OPEN" or "CLOSED"
PORT (data-area) | Full
PRIVACY (cvda) | Full
PRIVACY (cvda) | Full
PROTOCOL (cvda) | Full
SOCKETCLOSE (cvda) | Full
SSLTYPE (cvda) | Full
TCPIPSERVICE (data-value) | Full
TRANSID (data-area) | Full
TSQPREFIX (data-area) | Full
Parent topic: CICS SPI Calls


INQUIRE TDQUEUE

The INQUIRE TDQUEUE function is supported.

Operand | Support
ATIFACILITY (cvda) | Full
ATITERMID (data-area) | Full
ATITRANID (data-area) | Full
BLOCKFORMAT (cvda) | Full
EMPTYSTATUS (cvda) | Full
ENABLESTATUS (cvda) | Full
INDIRECTNAME (data-area) | Full
IOTYPE (cvda) | Full
NEXT | Full
NUMITEMS (data-area) | Full
OPENSTATUS (cvda) | Full
PRINTCONTROL (cvda) | Full
RECORDFORMAT (cvda) | Full
RECORDLENGTH (data-area) | Full
RECOVSTATUS (cvda) | Full
REMOTENAME (data-area) | Full
REMOTESYSTEM (data-area) | Full
TDQUEUE (data-value) | Full
TRIGGERLEVEL (data-area) | Full
TYPE (cvda) | Full
Parent topic: CICS SPI Calls


INQUIRE TERMINAL

The INQUIRE TERMINAL function is supported.

Operand | Support
ACCESSMETHOD (cvda) | Partial: returns "VTAM"
ACQSTATUS (cvda) | Partial: (VTAM only) returns "ACQUIRED"
ALTPAGEHT (data-area) | Full
ALTPAGEWD (data-area) | Full
ALTPRINTER (data-area) | Partial: returns spaces
ALTPRTCOPYST (cvda) | Partial: returns "NOALTPRTCOPY"
ALTSCRNHT (data-area) | Full
ALTSCRNWD (data-area) | Full
ALTSUFFIX (data-area) | Partial: returns spaces
APLKYBDST (cvda) | Partial: returns "NOAPLKYBD"
APLTEXTST (cvda) | Partial: returns "NOAPLTEXT"
ASCII (cvda) | Full
ATISTATUS (cvda) | Partial: returns "ATI"
AUDALARMST (cvda) | Partial: returns "AUDALARM"
AUTOCONNECT (cvda) | Full
BACKTRANSST (cvda) | Partial: returns "NOBACKTRANS"
COLORST (cvda) | Full
COPYST (cvda) | Partial: returns "NOCOPY"
CREATESESS (cvda) | Partial: returns "NOCREATE"
DATASTREAM (data-area) | Full
DEFPAGEHT (data-area) | Full
DEFPAGEWD (data-area) | Full
DEFSCRNHT (data-area) | Full
DEFSCRNWD (data-area) | Full
DEVICE (cvda) | Partial: returns "T3277L"
DEVICEST (cvda) | Full
DISCREQST (cvda) | Partial: returns "DISCREQ"
DUALCASEST (cvda) | Partial: returns "DUALCASE"
EXITTRACING (cvda) | Partial: returns "NOEXITTRACE"
EXTENDEDDSST (cvda) | Partial: returns "EXTENDEDDS"
FMHPARMST (cvda) | Partial: returns "NOFMHPARM"
FORMFEEDST (cvda) | Partial: returns "NOFORMFEED"
GCHARS (data-area) | Full
GCODES (data-area) | Full
HFORMST (cvda) | Partial: returns "NOHFORM"
HILIGHTST (cvda) | Partial: returns "HILIGHT"
KATAKANAST (cvda) | Partial: returns "NOKATAKANA"
LIGHTPENST (cvda) | Partial: returns "NOLIGHTPEN"
MAPNAME (data-area) | Validated
MAPSETNAME (data-area) | Full
MODENAME (data-area) | Full
MSRCONTROLST (cvda) | Partial: returns "NOMSRCONTROL"
NATLANG (data-area) | Partial: returns "E" meaning US English
NATURE (cvda) | Full
NETNAME (data-area) | Full
NEXT | Full
NEXTTRANSID (data-area) | Full
OBFORMATST (cvda) | Partial: returns "NOOBFORMAT"
OBOPERIDST (cvda) | Partial: returns "NOOBOPERID"
OPERID (data-area) | Full
OUTLINEST (cvda) | Partial: returns "NOOUTLINE"
PAGEHT (data-area) | Full
PAGESTATUS (cvda) | Partial: returns "PAGEABLE"
PAGEWD (data-area) | Full
PARTITIONSST (cvda) | Partial: returns "NOPARTITIONS"
PRINTADAPTST (cvda) | Partial: returns "NOPRINTADAPT"
PRINTER (data-area) | Partial: returns spaces
PROGSYMBOLST (cvda) | Partial: returns "NOPROGSYMBOL"
PRTCOPYST (cvda) | Partial: returns "NOPRTCOPY"
QUERYST (cvda) | Partial: returns "NOQUERY"
RELREQST (cvda) | Partial: returns "NORELREQ"
REMOTENAME (data-area) | Partial: returns spaces
REMOTESYSTEM (data-area) | Partial: returns spaces
SCREENHEIGHT (data-area) | Full
SCREENWIDTH (data-area) | Full
SCRNHT (data-area) | Full
SCRNWD (data-area) | Full
SECURITY (cvda) | Partial: returns "NOPRESETSEC"
SERVSTATUS (cvda) | Full
SESSIONTYPE (cvda) | Partial: returns "NOTAPPLIC"
SIGNONSTATUS (cvda) | Full
SOSIST (cvda) | Full
TASKID (data-area) | Partial: returns 0 meaning no task is using the terminal
TCAMCONTROL (data-area) | Partial: returns x"00" meaning null
TERMINAL (data-value) | Full
TERMMODEL (data-area) | Partial: returns 2
TERMPRIORITY (data-area) | Full
TERMSTATUS (cvda) | Full
TEXTKYBDST (cvda) | Partial: returns "NOTEXTKYBD"
TEXTPRINTST (cvda) | Partial: returns "NOTEXTPRINT"
TRACING (cvda) | Partial: returns "STANTRACE"
TRANSACTION (data-area) | Full
TTISTATUS (cvda) | Partial: returns "TTI"
UCTRANST (cvda) | Full
USERAREA (ptr-ref) | Full
USERAREALEN (data-area) | Partial: returns 0
USERID (data-area) | Full
USERNAME (data-area) | Partial: returns spaces
VALIDATIONST (cvda) | Partial: returns "NOVALIDATION"
VFORMST (cvda) | Partial: returns "NOVFORM"
ZCPTRACING (cvda) | Partial: returns "NOZCPTRACE"
Parent topic: CICS SPI Calls


INQUIRE TIMER

The INQUIRE TIMER function is not supported.

Parent topic: CICS SPI Calls


INQUIRE TRACEDEST

The INQUIRE TRACEDEST function is not supported.

Operand | Support
AUXSTATUS (cvda) | Recognized
CURAUXDS (data-area) | Recognized
GTFSTATUS (cvda) | Recognized
INTSTATUS (cvda) | Recognized
SWITCHSTATUS (cvda) | Recognized
TABLESIZE (data-area) | Recognized
Parent topic: CICS SPI Calls


INQUIRE TRACEFLAG

The INQUIRE TRACEFLAG function is not supported.

Operand | Support
SINGLESTATUS (cvda) | Recognized
SYSTEMSTATUS (cvda) | Recognized
TCEXITSTATUS (cvda) | Recognized
USERSTATUS (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE TRACETYPE

The INQUIRE TRACETYPE function is not supported.

Operand | Support
AP (data-area) | Recognized
APPLICATION (data-area) | Recognized
BF (data-area) | Recognized
BM (data-area) | Recognized
CP (data-area) | Recognized
CPI (data-area) | Recognized
DC (data-area) | Recognized
DI (data-area) | Recognized
DISPATCHER (data-area) | Recognized
DM (data-area) | Recognized
DOMAINMGR (data-area) | Recognized
DS (data-area) | Recognized
DU (data-area) | Recognized
DUMP (data-area) | Recognized
EI (data-area) | Recognized
FC (data-area) | Recognized
GC (data-area) | Recognized
GLOBALCATLG (data-area) | Recognized
IC (data-area) | Recognized
IS (data-area) | Recognized
JC (data-area) | Recognized
KC (data-area) | Recognized
KE (data-area) | Recognized
KERNEL (data-area) | Recognized
LC (data-area) | Recognized
LD (data-area) | Recognized
LM (data-area) | Recognized
LOADER (data-area) | Recognized
LOCALCATLG (data-area) | Recognized
LOCKMGR (data-area) | Recognized
ME (data-area) | Recognized
MESSAGE (data-area) | Recognized
MN (data-area) | Recognized
MONITOR (data-area) | Recognized
PA (data-area) | Recognized
PARAMGR (data-area) | Recognized
PC (data-area) | Recognized
SC (data-area) | Recognized
SM (data-area) | Recognized
SP (data-area) | Recognized
SPECIAL | Recognized
ST (data-area) | Recognized
STANDARD | Recognized
STATISTICS (data-area) | Recognized
STORAGE (data-area) | Recognized
SZ (data-area) | Recognized
TC (data-area) | Recognized
TD (data-area) | Recognized
TI (data-area) | Recognized
TIMER (data-area) | Recognized
TR (data-area) | Recognized
TRACE (data-area) | Recognized
TS (data-area) | Recognized
UE (data-area) | Recognized
Parent topic: CICS SPI Calls


INQUIRE TRANCLASS

The INQUIRE TRANCLASS function is supported.

Operand | Support
ACTIVE (data-area) | Full
MAXACTIVE (data-area) | Full
NEXT | Full
PURGETHRESH (data-area) | Full
QUEUED (data-value) | Full
TRANCLASS (data-value) | Full
Parent topic: CICS SPI Calls


INQUIRE TRANDUMPCODE

The INQUIRE TRANDUMPCODE function is not supported.

Operand | Support
CURRENT (data-area) | Recognized
MAXIMUM (data-area) | Recognized
NEXT | Recognized
SHUTOPTION (cvda) | Recognized
SYSDUMPING (cvda) | Recognized
TRANDUMPCODE (data-value) | Recognized
TRANDUMPING (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE TRANSACTION

The INQUIRE TRANSACTION function is supported.

Operand | Support
BREXIT (data-area) | Full
CMDSEC (cvda) | Partial: returns "CMDSECNO"
DTB (cvda) | Full
DTIMEOUT (data-area) | Partial: returns 0
DUMPING (cvda) | Full
FACILITYLIKE (data-area) | Full
ISOLATEST (cvda) | Full
NEXT | Full
OTSTIMEOUT (data-area) | Validated
PRIORITY (data-area) | Full
PROFILE (data-area) | Partial: returns spaces
PROGRAM (data-area) | Full
PURGEABILITY (cvda) | Full
REMOTENAME (data-area) | Full
REMOTESYSTEM (data-area) | Full
RESSEC (cvda) | Full
ROUTING (cvda) | Partial: returns "STATIC"
RTIMEOUT (data-area) | Full
SCRNSIZE (cvda) | Partial: returns "DEFAULT"
STATUS (cvda) | Full
TASKDATAKEY (cvda) | Partial: returns "CICSDATAKEY"
TASKDATALOC (cvda) | Partial: returns "ANY"
TCLASS (data-area) | Partial: returns 0
TRACING (cvda) | Partial: returns "STANTRACE"
TRANCLASS (data-area) | Partial: returns spaces
TRANSACTION (data-value) | Full
TRPROF (data-area) | Partial: returns spaces
TWASIZE (data-area) | Full
Parent topic: CICS SPI Calls


INQUIRE TSMODEL

The INQUIRE TSMODEL function is supported.

Operand | Support
EXPIRYINT (data-area) | Full
LOCATION (cvda) | Full
NEXT | Full
POOLNAME (data-area) | Full
PREFIX (cvda) | Full
RECOVSTATUS (data-area) | Full
REMOTEPREFIX (data-area) | Full
REMOTESYSTEM (data-area) | Full
SECURITYST (cvda) | Full
TSMODEL (data-value) | Full
Parent topic: CICS SPI Calls


INQUIRE TSPOOL

The INQUIRE TSPOOL function is not supported.

Parent topic: CICS SPI Calls


INQUIRE TSQNAME

The INQUIRE TSQNAME function is supported.

Operand | Support
FLENGTH (data-area) | Partial: returns -1
LASTUSEDINT (data-area) | Validated
LOCATION (cvda) | Partial: returns "AUXILIARY"
MAXITEMLEN (data-area) | Partial: returns -1
MINITEMLEN (data-area) | Partial: returns -1
NEXT | Full
NUMITEMS (data-area) | Full
POOLNAME (data-value) | Validated
RECOVSTATUS (data-area) | Validated
SYSID (data-value) | Validated
TRANSID (data-value) | Validated
TSQNAME (data-value) | Full
Parent topic: CICS SPI Calls


INQUIRE TSQUEUE

The INQUIRE TSQUEUE function is supported.

Operand | Support
FLENGTH (data-area) | Partial: returns -1
LASTUSEDINT (data-area) | Validated
LOCATION (cvda) | Partial: returns "AUXILIARY"
MAXITEMLEN (data-area) | Partial: returns -1
MINITEMLEN (data-area) | Partial: returns -1
NEXT | Full
NUMITEMS (data-area) | Full
POOLNAME (data-value) | Validated
RECOVSTATUS (data-area) | Validated
SYSID (data-value) | Validated
TRANSID (data-value) | Validated
TSQUEUE (data-value) | Full
Parent topic: CICS SPI Calls


INQUIRE UOW

The INQUIRE UOW function is not supported.

Operand | Support
AGE (data-area) | Recognized
LINK (data-area) | Recognized
NETNAME (data-area) | Recognized
NETUOWID (data-area) | Recognized
NEXT | Recognized
SYSID (data-area) | Recognized
TASKID (data-area) | Recognized
TERMID (data-area) | Recognized
TRANSID (data-area) | Recognized
UOW (data-value) | Recognized
UOWSTATE (data-area) | Recognized
USERID (data-area) | Recognized
WAITCAUSE (cvda) | Recognized
WAITSTATE (cvda) | Recognized
Parent topic: CICS SPI Calls


INQUIRE UOWDSNFAIL

The INQUIRE UOWDSNFAIL function is not supported.

Parent topic: CICS SPI Calls


INQUIRE UOWENQ

The INQUIRE UOWENQ function is not supported.

Parent topic: CICS SPI Calls


INQUIRE UOWLINK

The INQUIRE UOWLINK function is not supported.

Parent topic: CICS SPI Calls


INQUIRE URIMAP

The INQUIRE URIMAP function is supported.

Operand | Support
ANALYZERSTAT (cvda) | Full
CERTIFICATE (data-area) | Full
CHARACTERSET (data-area) | Full
CIPHERS (data-area) | Full
CONVERTER (data-area) | Full
ENABLESTATUS (cvda) | Full
HFSFILE (data-area) | Full
HOST (data-area) | Full
HOSTCODEPAGE (data-area) | Full
LOCATION (data-area) | Full
MEDIATYPE (data-area) | Full
NEXT | Full
NUMCIPHERS (data-area) | Full
PATH (data-area) | Full
PIPELINE (data-area) | Full
PROGRAM (data-area) | Full
REDIRECTTYPE (cvda) | Full
SCHEME (cvda) | Full
TCPIPSERVICE (data-area) | Full
TEMPLATENAME (data-area) | Full
TRANSACTION (data-area) | Full
URIMAP (data-value) | Full
USAGE (cvda) | Full
USERID (data-area) | Full
WEBSERVICE (data-area) | Full
Parent topic: CICS SPI Calls


INQUIRE VOLUME

The INQUIRE VOLUME function is not supported.

Operand | Support
AVAILSTATUS (cvda) | Recognized
DATE (data-area) | Recognized
EMPTYSTATUS (cvda) | Recognized
JOURNALNUM (data-area) | Recognized
NEXT | Recognized
OPENSTATUS (cvda) | Recognized
PART (data-area) | Recognized
TIME (data-area) | Recognized
VOLUME (data-value) | Recognized
Parent topic: CICS SPI Calls


INQUIRE VTAM

The INQUIRE VTAM function is not supported.

Operand | Support
OPENSTATUS (data-area) | Recognized
Parent topic: CICS SPI Calls


INQUIRE WEB

The INQUIRE WEB function is not supported.

Parent topic: CICS SPI Calls


INQUIRE WEBSERVICE

The INQUIRE WEBSERVICE function is supported.

Operand | Support
BINDING (cvda) | Full
CCSID (data-area) | Full
CONTAINER (data-area) | Full
ENDPOINT (data-area) | Full
LASTMODTIME (data-area) | Partial: returns 0
MAPPINGLEVEL (data-area) | Full
MAPPINGRNUM (cvda) | Full
MAPPINGVNUM (cvda) | Full
MINRUNLEVEL (data-area) | Full
MINRUNRNUM (cvda) | Full
MINRUNVNUM (cvda) | Full
NEXT | Full
PGMINTERFACE (cvda) | Full
PIPELINE (data-area) | Full
PROGRAM (data-area) | Full
STATE (cvda) | Full
URIMAP (data-area) | Full
VALIDATIONST (cvda) | Full
WEBSERVICE (data-value) | Full
WSBIND (data-area) | Full
WSDLFILE (data-area) | Full
Parent topic: CICS SPI Calls


INQUIRE XMLTRANSFORM

The INQUIRE XMLTRANSFORM function is supported.

Operand | Support
BUNDLE (data-area) | Full
CCSID (data-area) | Full
ENABLESTATUS (cvda) | Full
MAPPINGLEVEL (data-area) | Full
MAPPINGRNUM (cvda) | Full
MAPPINGVNUM (cvda) | Full
MINRUNLEVEL (data-area) | Full
MINRUNRNUM (cvda) | Full
MINRUNVNUM (cvda) | Full
NEXT | Full
VALIDATIONST (cvda) | Partial: returns "NOVALIDATION"
XMLSCHEMA (data-area) | Full
XMLTRANSFORM (data-value) | Full
XSDBIND (data-area) | Full
Parent topic: CICS SPI Calls


PERFORM CORBASERVER

The PERFORM CORBASERVER function is not supported.

Parent topic: CICS SPI Calls


PERFORM DELETSHIPPED

The PERFORM DELETSHIPPED function is not supported.

Parent topic: CICS SPI Calls


PERFORM DJAR

The PERFORM DJAR function is not supported.

Parent topic: CICS SPI Calls


PERFORM DUMP

The PERFORM DUMP function is supported.

Operand | Support
CALLER (data-value) | Full
CALLERLENGTH (data-value) | Full
DUMPCODE (data-value) | Full
DUMPID (data-area) | Full
TITLE (data-value) | Full
TITLELENGTH (data-value) | Full
Parent topic: CICS SPI Calls


PERFORM ENDAFFINITY

The PERFORM ENDAFFINITY function is not supported.

Parent topic: CICS SPI Calls


PERFORM RESETTIME

The PERFORM RESETTIME function is supported.

Parent topic: CICS SPI Calls


PERFORM SECURITY REBUILD

The PERFORM SECURITY REBUILD function is not supported.

Operand | Support
ESMRESP (data-area) | Recognized
Parent topic: CICS SPI Calls


PERFORM SHUTDOWN

The PERFORM SHUTDOWN function is supported.

Operand | Support
DUMP | Full
IMMEDIATE | Full
NORESTART | Full
NOSDTRAN | Validated
PLT (data-value) | Full
SDTRAN (data-value) | Validated
TAKEOVER | Validated
XLT (data-value) | Validated
Parent topic: CICS SPI Calls


PERFORM STATISTICS RECORD

The PERFORM STATISTICS RECORD function is not supported.

Operand | Support
ALL | Recognized
AUTOINSTALL | Recognized
CONNECTION | Recognized
CORBASERVER | Recognized
DISPATCHER | Recognized
DTB | Recognized
FILE | Recognized
IRCBATCH | Recognized
JOURNALNUM | Recognized
JVMPOOL | Recognized
LSRPOOL | Recognized
MONITOR | Recognized
PROGRAM | Recognized
REQUESTMODEL | Recognized
RESETNOW | Recognized
STATS | Recognized
STORAGE | Recognized
SYSDUMP | Recognized
TABLEMGR | Recognized
TASKCONTROL | Recognized
TCLASS | Recognized
TCPIP | Recognized
TCPIPSERVICE | Recognized
TDQUEUE | Recognized
TERMINAL | Recognized
TRANDUMP | Recognized
TRANSACTION | Recognized
TSQUEUE | Recognized
VTAM | Recognized
Parent topic: CICS SPI Calls


RESYNC ENTRYNAME

The RESYNC ENTRYNAME function is not supported.

Operand | Support
ENTRYNAME (data-value) | Recognized
IDLIST (data-value) | Recognized
IDLISTLENGTH (data-value) | Recognized
QUALIFIER (data-value) | Recognized
Parent topic: CICS SPI Calls


SET AUTOINSTALL

The SET AUTOINSTALL function is not supported.

Operand | Support
MAXREQS (data-value) | Recognized
PROGRAM (data-value) | Recognized
Parent topic: CICS SPI Calls


SET BRFACILITY

The SET BRFACILITY function is not supported.

Parent topic: CICS SPI Calls


SET BUNDLE

The SET BUNDLE function is supported.

Operand | Support
BUNDLE (data-value) | Full
DISABLED (cvda) | Full
ENABLED (cvda) | Full
ENABLESTATUS (data-value) | Full
Parent topic: CICS SPI Calls


SET CONNECTION

The SET CONNECTION function is supported.

Operand | Support
ACQSTATUS (data-value) | Full
ACQUIRED (cvda) | Full
CONNECTION (data-value) | Full
CONNSTATUS (data-value) | Full
EXITTRACE (cvda) | Full
EXITTRACING (data-value) | Full
FORCEPURGE (cvda) | Full
INSERVICE (cvda) | Full
NOEXITTRACE (cvda) | Full
NOTPENDING (cvda) | Full
NOZCPTRACE (cvda) | Full
OUTSERVICE (cvda) | Full
PENDSTATUS (data-value) | Partial: requires "NOTPENDING"
PURGE (cvda) | Full
PURGETYPE (data-value) | Full
RELEASED (cvda) | Full
SERVSTATUS (data-value) | Full
ZCPTRACE (cvda) | Full
ZCPTRACING (data-value) | Partial: requires "NOZCPTRACE"
Parent topic: CICS SPI Calls


SET CORBASERVER

The SET CORBASERVER function is not supported.

Parent topic: CICS SPI Calls


SET DATASET

The SET DATASET function is supported.

Operand | Support
ADD (data-value) | Full
ADDABLE (cvda) | Full
BROWSABLE (cvda) | Full
BROWSE (data-value) | Full
BUSY (data-value) | Full
CFDTPOOL (data-value) | Validated
CFTABLE (cvda) | Validated
CICSTABLE (cvda) | Validated
CLOSED (cvda) | Full
CONSISTENT (cvda) | Validated
CONTENTION (cvda) | Validated
DATASET (data-value) | Full
DELETABLE (cvda) | Full
DELETE (data-value) | Full
DISABLED (cvda) | Full
DISPOSITION (data-value) | Partial: requires "SHARE"
DSNAME (data-area) | Full
EMPTYREQ (cvda) | Full
EMPTYSTATUS (data-value) | Full
ENABLED (cvda) | Full
ENABLESTATUS (data-value) | Full
EXCLUSIVE (data-value) | Partial: requires "NOTAPPLIC"
EXCTL (cvda) | Full
FILE (data-value) | Full
FORCE (cvda) | Full
KEYLENGTH (data-value) | Validated
LOAD (cvda) | Validated
LOADTYPE (data-value) | Validated
LOCKING (cvda) | Validated
LSRPOOLID (data-area) | Partial: requires 0
MAXNUMRECS (data-area) | Partial: requires 0
NOEMPTYREQ (cvda) | Full
NOEXCTL (cvda) | Full
NOLOAD (cvda) | Validated
NOTADDABLE (cvda) | Full
NOTAPPLIC (cvda) | Validated
NOTBROWSABLE (cvda) | Full
NOTDELETABLE (cvda) | Full
NOTREADABLE (cvda) | Full
NOTRLS (cvda) | Validated
NOTTABLE (cvda) | Validated
NOTUPDATABLE (cvda) | Full
NOWAIT (cvda) | Full
OBJECTNAME (data-area) | Full
OLD (cvda) | Validated
OPEN (cvda) | Full
OPENSTATUS (data-value) | Full
READ (data-value) | Full
READABLE (cvda) | Full
READINTEG (data-value) | Validated
RECORDSIZE (data-value) | Validated
REPEATABLE (cvda) | Validated
RLS (cvda) | Validated
RLSACCESS (data-value) | Validated
SHARE (cvda) | Full
STRINGS (data-area) | Partial: requires 1
TABLE (data-value) | Validated
TABLENAME (data-value) | Validated
UNCOMMITTED (cvda) | Validated
UPDATABLE (cvda) | Full
UPDATE (data-value) | Full
UPDATEMODEL (data-value) | Validated
USERTABLE (cvda) | Validated
WAIT (cvda) | Full
Parent topic: CICS SPI Calls


SET DB2CONN

The SET DB2CONN function is not supported.

Parent topic: CICS SPI Calls


SET DB2ENTRY

The SET DB2ENTRY function is not supported.

Parent topic: CICS SPI Calls


SET DB2TRAN

The SET DB2TRAN function is not supported.

Parent topic: CICS SPI Calls


SET DELETSHIPPED

The SET DELETSHIPPED function is not supported.

Parent topic: CICS SPI Calls


SET DISPATCHER

The SET DISPATCHER function is not supported.

Parent topic: CICS SPI Calls


SET DOCTEMPLATE

The SET DOCTEMPLATE function is supported.

Operand | Support
COPY (data-value) | Full
DOCTEMPLATE (data-value) | Full
NEWCOPY (cvda) | Full
Parent topic: CICS SPI Calls


SET DSNAME

The SET DSNAME function is not supported.

Operand | Support
ACTION (data-value) | Recognized
AVAILABILITY (data-value) | Recognized
AVAILABLE (cvda) | Recognized
BACKOUT (cvda) | Recognized
BKOUTSTATUS (data-value) | Recognized
BUSY (data-value) | Recognized
COMMIT (cvda) | Recognized
DSNAME (data-value) | Recognized
FAILEDBKOUT (cvda) | Recognized
FORCE (cvda) | Recognized
IMMQUIESCED (cvda) | Recognized
NORMALBKOUT (cvda) | Recognized
NOWAIT (cvda) | Recognized
QUIESCED (cvda) | Recognized
QUIESCESTATE (data-value) | Recognized
RECOVERED (cvda) | Recognized
REMOVE (cvda) | Recognized
RESETLOCKS (cvda) | Recognized
RETRY (cvda) | Recognized
UNAVAILABLE (cvda) | Recognized
UNQUIESCED (cvda) | Recognized
UOWACTION (data-value) | Recognized
WAIT (cvda) | Recognized
Parent topic: CICS SPI Calls


SET DUMPDS

The SET DUMPDS function is not supported.

Operand | Support
CLOSED (cvda) | Recognized
INITIALDDS (data-value) | Recognized
NOSWITCH (cvda) | Recognized
OPEN (cvda) | Recognized
OPENSTATUS (data-value) | Recognized
SWITCH (cvda) | Recognized
SWITCHNEXT (cvda) | Recognized
SWITCHSTATUS (data-value) | Recognized
Parent topic: CICS SPI Calls


SET ENQMODEL

The SET ENQMODEL function is supported.

Operand | Support
DISABLED (cvda) | Full
ENABLED (cvda) | Full
ENQMODEL (data-value) | Full
STATUS (data-value) | Full
Parent topic: CICS SPI Calls


SET FILE

The SET FILE function is supported.

Operand | Support
ADD (data-value) | Full
ADDABLE (cvda) | Full
BROWSABLE (cvda) | Full
BROWSE (data-value) | Full
BUSY (data-value) | Full
CFDTPOOL (data-value) | Validated
CFTABLE (cvda) | Validated
CICSTABLE (cvda) | Validated
CLOSED (cvda) | Full
CONSISTENT (cvda) | Validated
CONTENTION (cvda) | Validated
DATASET (data-value) | Full
DELETABLE (cvda) | Full
DELETE (data-value) | Full
DISABLED (cvda) | Full
DISPOSITION (data-value) | Partial: requires "SHARE"
DSNAME (data-area) | Full
EMPTYREQ (cvda) | Full
EMPTYSTATUS (data-value) | Full
ENABLED (cvda) | Full
ENABLESTATUS (data-value) | Full
EXCLUSIVE (data-value) | Partial: requires "NOTAPPLIC"
EXCTL (cvda) | Full
FILE (data-value) | Full
FORCE (cvda) | Full
KEYLENGTH (data-value) | Validated
LOAD (cvda) | Validated
LOADTYPE (data-value) | Validated
LOCKING (cvda) | Validated
LSRPOOLID (data-area) | Partial: requires 0
MAXNUMRECS (data-area) | Partial: requires 0
NOEMPTYREQ (cvda) | Full
NOEXCTL (cvda) | Full
NOLOAD (cvda) | Validated
NOTADDABLE (cvda) | Full
NOTAPPLIC (cvda) | Validated
NOTBROWSABLE (cvda) | Full
NOTDELETABLE (cvda) | Full
NOTREADABLE (cvda) | Full
NOTRLS (cvda) | Validated
NOTTABLE (cvda) | Validated
NOTUPDATABLE (cvda) | Full
NOWAIT (cvda) | Full
OBJECTNAME (data-area) | Full
OLD (cvda) | Validated
OPEN (cvda) | Full
OPENSTATUS (data-value) | Full
READ (data-value) | Full
READABLE (cvda) | Full
READINTEG (data-value) | Validated
RECORDSIZE (data-value) | Validated
REPEATABLE (cvda) | Validated
RLS (cvda) | Validated
RLSACCESS (data-value) | Validated
SHARE (cvda) | Full
STRINGS (data-area) | Partial: requires 1
TABLE (data-value) | Validated
TABLENAME (data-value) | Validated
UNCOMMITTED (cvda) | Validated
UPDATABLE (cvda) | Full
UPDATE (data-value) | Full
UPDATEMODEL (data-value) | Validated
USERTABLE (cvda) | Validated
WAIT (cvda) | Full
Parent topic: CICS SPI Calls


SET IRC

The SET IRC function is not supported.

Operand | Support
CLOSED (cvda) | Recognized
IMMCLOSE (cvda) | Recognized
OPEN (cvda) | Recognized
OPENSTATUS (data-value) | Recognized
Parent topic: CICS SPI Calls


SET JOURNALNAME

The SET JOURNALNAME function is not supported.

Parent topic: CICS SPI Calls


SET JOURNALNUM

The SET JOURNALNUM function is supported.

Operand | Support
ADVANCE (cvda) | Full
CLOSED (cvda) | Full
CLOSELEAVE (cvda) | Full
JOURNALNUM (data-value) | Full
OPENOUTPUT (cvda) | Full
OPENSTATUS (data-value) | Full
Parent topic: CICS SPI Calls


SET JVMPOOL

The SET JVMPOOL function is not supported.

Parent topic: CICS SPI Calls


SET MODENAME

The SET MODENAME function is not supported.

Operand | Support
ACQSTATUS (data-area) | Recognized
ACQUIRED (cvda) | Recognized
AVAILABLE (data-value) | Recognized
CLOSED (cvda) | Recognized
CONNECTION (data-value) | Recognized
MODENAME (data-value) | Recognized
Parent topic: CICS SPI Calls


SET MONITOR

The SET MONITOR function is not supported.

Operand | Support
EVENT (cvda) | Recognized
EVENTCLASS (data-value) | Recognized
EXCEPT (cvda) | Recognized
EXCEPTCLASS (data-value) | Recognized
NOEVENT (cvda) | Recognized
NOEXCEPT (cvda) | Recognized
NOPERF (cvda) | Recognized
OFF (cvda) | Recognized
ON (cvda) | Recognized
PERF (cvda) | Recognized
PERFCLASS (data-value) | Recognized
STATUS (data-value) | Recognized
Parent topic: CICS SPI Calls


SET NETNAME

The SET NETNAME function is supported.

Operand | Support
EXITTRACE (cvda) | Full
EXITTRACING (data-value) | Partial: requires "NOEXITTRACE"
NETNAME (data-value) | Full
NOEXITTRACE (cvda) | Full
Parent topic: CICS SPI Calls


SET PIPELINE

The SET PIPELINE function is supported.

Operand | Support
DISABLED (cvda) | Full
ENABLED (cvda) | Full
ENABLESTATUS (data-value) | Full
PIPELINE (data-value) | Full
RESPWAIT (data-area) | Full
Parent topic: CICS SPI Calls


SET PROCESSTYPE

The SET PROCESSTYPE function is not supported.

Parent topic: CICS SPI Calls


SET PROGRAM

The SET PROGRAM function is supported.

Operand | Support
CEDF (cvda) | Full
CEDFSTATUS (data-value) | Partial: requires "NOCEDF"
COPY (data-value) | Full
DISABLED (cvda) | Full
DPLSUBSET (cvda) | Full
ENABLED (cvda) | Full
EXECUTIONSET (data-value) | Partial: requires "FULLAPI"
FULLAPI (cvda) | Full
HOTPOOL (cvda) | Validated
HOTPOOLING (data-value) | Validated
JVM (cvda) | Validated
JVMCLASS (data-area) | Validated
NEWCOPY (cvda) | Full
NOCEDF (cvda) | Full
NOJVM (cvda) | Validated
NOTHOTPOOL (cvda) | Validated
PHASEIN (cvda) | Full
PRIVATE (cvda) | Full
PROGRAM (data-value) | Full
RUNTIME (data-value) | Validated
SHARED (cvda) | Full
SHARESTATUS (data-value) | Partial: accepts "PRIVATE" and "SHARED" but ignored
STATUS (data-value) | Full
VERSION (data-value) | Partial: requires "NEWCOPY"
Parent topic: CICS SPI Calls


SET STATISTICS

The SET STATISTICS function is not supported.

Operand | Support
ENDOFDAY (data-value) | Recognized
ENDOFDAYHRS (data-value) | Recognized
ENDOFDAYMINS (data-value) | Recognized
ENDOFDAYSECS (data-value) | Recognized
INTERVAL (data-value) | Recognized
INTERVALHRS (data-value) | Recognized
INTERVALMINS (data-value) | Recognized
INTERVALSECS (data-value) | Recognized
OFF (cvda) | Recognized
ON (cvda) | Recognized
RECORDING (data-value) | Recognized
RECORDNOW | Recognized
RESETNOW | Recognized
Parent topic: CICS SPI Calls


SET SYSDUMPCODE

The SET SYSDUMPCODE function is not supported.

Operand | Support
ACTION (data-value) | Recognized
ADD (cvda) | Recognized
MAXIMUM (data-value) | Recognized
NOSHUTDOWN (cvda) | Recognized
NOSYSDUMP (cvda) | Recognized
REMOVE (cvda) | Recognized
RESET (cvda) | Recognized
SHUTDOWN (cvda) | Recognized
SHUTOPTION (data-value) | Recognized
SYSDUMP (cvda) | Recognized
SYSDUMPCODE (data-value) | Recognized
SYSDUMPING (data-value) | Recognized
Parent topic: CICS SPI Calls


SET SYSTEM

The SET SYSTEM function is supported.

Operand | Support
AKP (data-value) | Partial: requires "FULLAPI"
AMAXTASKS (data-value) | Full
CSCS (data-value) | Partial: requires ""
CUSHION (data-value) | Partial: requires ""
DTRPROGRAM (data-value) | Full
DUMPING (data-value) | Partial: requires ""
ECSCS (data-value) | Validated
ECUSHION (data-value) | Validated
ERSCS (data-value) | Validated
EUSCS (data-value) | Validated
MAXTASKS (data-value) | Partial: requires 999
MROBATCH (data-value) | Full
NEWMAXTASKS (data-value) | Full
NOSYSDUMP (cvda) | Full
PRTYAGING (data-value) | Full
RUNAWAY (data-value) | Full
SCANDELAY (data-value) | Full
SYSDUMP (cvda) | Full
TIME (data-value) | Full
USCS (data-value) | Validated
Parent topic: CICS SPI Calls


SET TASK

The SET TASK function is supported.

Operand | Support
FORCEPURGE (cvda) | Full
KILL (cvda) | Full
PRIORITY (data-value) | Validated
PURGE (cvda) | Full
PURGETYPE (data-value) | Full
TASK (data-value) | Full
Parent topic: CICS SPI Calls


SET TCLASS

The SET TCLASS function is supported.

Operand | Support
MAXIMUM (data-value) | Full
TCLASS (data-value) | Full
Parent topic: CICS SPI Calls


SET TCPIP

The SET TCPIP function is not supported.

Parent topic: CICS SPI Calls


SET TCPIPSERVICE

The SET TCPIPSERVICE function is supported.

Operand | Support
BACKLOG (data-area) | Full
CLOSED (cvda) | Full
DEREGISTERED (cvda) | Full
DNSSTATUS (data-value) | Partial: not yet implemented
IMMCLOSE (cvda) | Full
MAXDATALEN (data-area) | Full
OPEN (cvda) | Full
OPENSTATUS (data-value) | Partial: IMMCLOSE sets CLOSED
TCPIPSERVICE (data-value) | Full
URM (data-value) | Full
Parent topic: CICS SPI Calls


SET TDQUEUE

The SET TDQUEUE function is supported.

Operand | Support
ATIFACILITY (data-value) | Full
ATITERMID (data-value) | Full
ATITRANID (data-value) | Full
CLOSED (cvda) | Full
DISABLED (cvda) | Full
ENABLED (cvda) | Full
ENABLESTATUS (data-value) | Full
NOTERMINAL (cvda) | Full
OPEN (cvda) | Full
OPENSTATUS (data-value) | Full
TDQUEUE (data-value) | Full
TERMINAL (cvda) | Full
TRIGGERLEVEL (data-value) | Full
Parent topic: CICS SPI Calls


SET TERMINAL

The SET TERMINAL function is supported.

Operand | Support
ACQSTATUS (data-value) | Partial: accepts "RELEASED"
ACQUIRED (cvda) | Validated
ALTPRINTER (data-value) | Partial: requires spaces
ALTPRTCOPY (cvda) | Validated
ALTPRTCOPYST (data-value) | Partial: requires "NOALTPRTCOPY"
ATI (cvda) | Validated
ATISTATUS (data-value) | Validated
AUTOPAGEABLE (cvda) | Validated
CANCEL (cvda) | Validated
COLDACQ (cvda) | Validated
CREATE (cvda) | Validated
CREATESESS (data-value) | Partial: requires "NOCREATE"
DISCREQ (cvda) | Full
DISCREQST (data-value) | Partial: requires "DISCREQ"
EXITTRACE (cvda) | Validated
EXITTRACING (data-value) | Partial: requires "NOEXITTRACE"
FORCEPURGE (cvda) | Full
INSERVICE (cvda) | Full
KILL (cvda) | Full
NEXTTRANSID (data-value) | Full
NOALTPRTCOPY (cvda) | Full
NOATI (cvda) | Validated
NOCREATE (cvda) | Full
NODISCREQ (cvda) | Validated
NOEXITTRACE (cvda) | Full
NOOBFORMAT (cvda) | Full
NOPRTCOPY (cvda) | Full
NORELREQ (cvda) | Full
NOTTI (cvda) | Validated
NOUCTRAN (cvda) | Full
NOZCPTRACE (cvda) | Full
OBFORMAT (cvda) | Validated
OBFORMATST (data-value) | Partial: requires "NOOBFORMAT"
OPERID (data-value) | Full
OUTSERVICE (cvda) | Full
PAGEABLE (cvda) | Validated
PAGESTATUS (data-value) | Validated
PRINTER (data-value) | Full
PRTCOPY (cvda) | Validated
PRTCOPYST (data-value) | Partial: requires "NOPRTCOPY"
PURGE (cvda) | Full
PURGETYPE (data-value) | Partial: accepts "PURGE", "FORCEPURGE" and "KILL"
RELEASED (cvda) | Full
RELREQ (cvda) | Validated
RELREQST (data-value) | Partial: requires "NORELREQ"
SERVSTATUS (data-value) | Full
SPECTRACE (cvda) | Validated
STANTRACE (cvda) | Full
TCAMCONTROL (data-value) | Partial: requires x"00" meaning no change
TERMINAL (data-value) | Full
TERMPRIORITY (data-value) | Full
TERMSTATUS (data-value) | Partial: accepts "RELEASED"
TRACING (data-value) | Partial: requires "STANTRACE"
TRANIDONLY (cvda) | Full
TTI (cvda) | Validated
TTISTATUS (data-value) | Validated
UCTRAN (cvda) | Full
UCTRANST (data-value) | Full
ZCPTRACE (cvda) | Validated
ZCPTRACING (data-value) | Partial: requires "NOZCPTRACE"
Parent topic: CICS SPI Calls


SET TRACEDEST

The SET TRACEDEST function is not supported.

Operand | Support
AUXPAUSE (cvda) | Recognized
AUXSTART (cvda) | Recognized
AUXSTATUS (data-value) | Recognized
AUXSTOP (cvda) | Recognized
GTFSTART (cvda) | Recognized
GTFSTATUS (data-value) | Recognized
GTFSTOP (cvda) | Recognized
INTSTART (cvda) | Recognized
INTSTATUS (data-value) | Recognized
INTSTOP (cvda) | Recognized
NOSWITCH (cvda) | Recognized
SWITCH (cvda) | Recognized
SWITCHACTION (data-value) | Recognized
SWITCHALL (cvda) | Recognized
SWITCHNEXT (cvda) | Recognized
SWITCHSTATUS (data-value) | Recognized
TABLESIZE (data-value) | Recognized
Parent topic: CICS SPI Calls


SET TRACEFLAG

The SET TRACEFLAG function is not supported.

Operand | Support
SINGLEOFF (cvda) | Recognized
SINGLEON (cvda) | Recognized
SINGLESTATUS (data-value) | Recognized
SYSTEMOFF (cvda) | Recognized
SYSTEMON (cvda) | Recognized
SYSTEMSTATUS (data-value) | Recognized
TCEXITALL (cvda) | Recognized
TCEXITALLOFF (cvda) | Recognized
TCEXITNONE (cvda) | Recognized
TCEXITSTATUS (data-value) | Recognized
TCEXITSYSTEM (cvda) | Recognized
USEROFF (cvda) | Recognized
USERON (cvda) | Recognized
USERSTATUS (data-value) | Recognized
Parent topic: CICS SPI Calls


SET TRACETYPE

The SET TRACETYPE function is not supported.

Operand | Support
AP (data-value) | Recognized
APPLICATION (data-value) | Recognized
BF (data-value) | Recognized
BM (data-value) | Recognized
CP (data-value) | Recognized
CPI (data-value) | Recognized
DC (data-value) | Recognized
DI (data-value) | Recognized
DISPATCHER (data-value) | Recognized
DM (data-value) | Recognized
DOMAINMGR (data-value) | Recognized
DS (data-value) | Recognized
DU (data-value) | Recognized
DUMP (data-value) | Recognized
EI (data-value) | Recognized
FC (data-value) | Recognized
GC (data-value) | Recognized
GLOBALCATLG (data-value) | Recognized
IC (data-value) | Recognized
IS (data-value) | Recognized
JC (data-value) | Recognized
KC (data-value) | Recognized
KE (data-value) | Recognized
KERNEL (data-value) | Recognized
LC (data-value) | Recognized
LD (data-value) | Recognized
LM (data-value) | Recognized
LOADER (data-value) | Recognized
LOCALCATLG (data-value) | Recognized
LOCKMGR (data-value) | Recognized
ME (data-value) | Recognized
MESSAGE (data-value) | Recognized
MN (data-value) | Recognized
MONITOR (data-value) | Recognized
PA (data-value) | Recognized
PARAMGR (data-value) | Recognized
PC (data-value) | Recognized
SC (data-value) | Recognized
SM (data-value) | Recognized
SP (data-value) | Recognized
SPECIAL | Recognized
ST (data-value) | Recognized
STANDARD | Recognized
STATISTICS (data-value) | Recognized
STORAGE (data-value) | Recognized
SZ (data-value) | Recognized
TC (data-value) | Recognized
TD (data-value) | Recognized
TI (data-value) | Recognized
TIMER (data-value) | Recognized
TR (data-value) | Recognized
TRACE (data-value) | Recognized
TS (data-value) | Recognized
UE (data-value) | Recognized
Parent topic: CICS SPI Calls


SET TRANCLASS

The SET TRANCLASS function is supported.

Operand | Support
MAXACTIVE (data-area) | Full
PURGETHRESH (data-area) | Full
TRANCLASS (data-value) | Full
Parent topic: CICS SPI Calls


SET TRANDUMPCODE

The SET TRANDUMPCODE function is not supported.

Operand | Support
ACTION (data-value) | Recognized
ADD (cvda) | Recognized
MAXIMUM (data-value) | Recognized
NOSHUTDOWN (cvda) | Recognized
NOSYSDUMP (cvda) | Recognized
NOTRANDUMP (cvda) | Recognized
REMOVE (cvda) | Recognized
RESET (cvda) | Recognized
SHUTDOWN (cvda) | Recognized
SHUTOPTION (data-value) | Recognized
SYSDUMP (cvda) | Recognized
SYSDUMPING (data-value) | Recognized
TRANDUMP (cvda) | Recognized
TRANDUMPCODE (data-value) | Recognized
TRANDUMPING (data-value) | Recognized
Parent topic: CICS SPI Calls


SET TRANSACTION

The SET TRANSACTION function is supported.

Operand | Support
DISABLED (cvda) | Full
DUMPING (data-value) | Full
ENABLED (cvda) | Full
NOTPURGEABLE (cvda) | Full
NOTRANDUMP (cvda) | Full
OTSTIMEOUT (data-area) | Validated
PRIORITY (data-value) | Full
PRIORITY (data-value) | Validated
PURGEABILITY (data-value) | Full
PURGEABLE (cvda) | Full
RUNAWAYTYPE (data-value) | Validated
SHUTDISABLED (cvda) | Validated
SHUTDOWN (data-value) | Validated
SHUTENABLED (cvda) | Validated
SPECTRACE (cvda) | Full
SPRSTRACE (cvda) | Full
STANTRACE (cvda) | Full
STATUS (data-value) | Full
SYSTEM (cvda) | Validated
TCLASS (data-value) | Full
TRACING (data-value) | Partial: requires "STANTRACE"
TRANCLASS (data-value) | Full
TRANDUMP (cvda) | Full
TRANSACTION (data-value) | Full
USER (cvda) | Validated
Parent topic: CICS SPI Calls


SET TSQNAME

The SET TSQNAME function is not supported.

Operand | Support
ACTION (data-value) | Recognized
DELETE (cvda) | Recognized
LASTUSEDINT (data-value) | Recognized
POOLNAME (data-value) | Recognized
SYSID (data-value) | Recognized
TSQNAME (data-value) | Recognized
Parent topic: CICS SPI Calls


SET TSQUEUE

The SET TSQUEUE function is not supported.

Operand | Support
ACTION (data-value) | Recognized
DELETE (cvda) | Recognized
LASTUSEDINT (data-value) | Recognized
POOLNAME (data-value) | Recognized
SYSID (data-value) | Recognized
TSQUEUE (data-value) | Recognized
Parent topic: CICS SPI Calls


SET UOW

The SET UOW function is not supported.

Operand | Support
BACKOUT (cvda) | Recognized
COMMIT (cvda) | Recognized
FORCE (cvda) | Recognized
UOW (data-value) | Recognized
UOWSTATE (data-value) | Recognized
Parent topic: CICS SPI Calls


SET UOWLINK

The SET UOWLINK function is not supported.

Parent topic: CICS SPI Calls


SET URIMAP

The SET URIMAP function is supported.

Operand | Support
DISABLED (cvda) | Full
ENABLED (cvda) | Full
ENABLESTATUS (data-value) | Full
LOCATION (data-area) | Full
NONE (cvda) | Full
PERMANENT (cvda) | Full
REDIRECTTYPE (cvda) | Full
TEMPORARY (cvda) | Full
URIMAP (data-value) | Full
Parent topic: CICS SPI Calls


SET VOLUME

The SET VOLUME function is not supported.

Operand | Support
ACTION (data-value) | Recognized
ADD (cvda) | Recognized
AVAILSTATUS (data-value) | Recognized
JOURNALNUM (data-value) | Recognized
NOWRITE (cvda) | Recognized
OK (cvda) | Recognized
REMOVE (cvda) | Recognized
VOLUME (data-value) | Recognized
Parent topic: CICS SPI Calls


SET VTAM

The SET VTAM function is not supported.

Operand | Support
CLOSED (cvda) | Recognized
FORCECLOSE (cvda) | Recognized
IMMCLOSE (cvda) | Recognized
OPEN (cvda) | Recognized
OPENSTATUS (data-value) | Recognized
Parent topic: CICS SPI Calls


SET WEB

The SET WEB function is not supported.

Parent topic: CICS SPI Calls


SET WEBSERVICE

The SET WEBSERVICE function is supported.

Operand | Support
NOVALIDATION (cvda) | Full
VALIDATION (cvda) | Full
VALIDATIONST (data-value) | Full
WEBSERVICE (data-value) | Full
Parent topic: CICS SPI Calls


Micro Focus FTP Utility MFFTP

The MFFTP utility provides a support mechanism for batch processes that takes advantage of FTP from JCL on the mainframe. It also provides FTP support for JCL-enabled enterprise servers within Micro Focus Enterprise Server . .

The MFFTP utility is not a rewrite of an FTP client. It makes use of the platform's existing FTP client or of any third party FTP client installed on the machine.

  • Prerequisites
  • Major Features of the MFFTP Utility
  • Basic Operation
    Describes the three phases of the MFFTP utility. Reading standard FTP control cards, invoking the client and reading the output from the client.
  • Configuring the MFFTP Utility
    Details the environment variables, DD statements, input and output files, manipulation of end-of-line markers, error codes and messages.
  • Running the MFFTP Utility
  • Writing a Module to Support a Third Party FTP Client
    How to configure MFFTP to invoke a third party client.
Parent topic: Mainframe Reference
Related concepts
Features Added in Enterprise Developer 2.3


Prerequisites

The MFFTP utility is installed as part of Micro Focus Enterprise Developer.

MFFTP requires:

  • An FTP client on the host system - for example, WS_FTP Pro.
  • A JCL-enabled enterprise server configured to receive JCL jobs.

Known Issues

If the FTP client connects to the FTP server using invalid credentials, and the server neither accepts anonymous access nor performs a timeout after a period of inactivity, the FTP client waits indefinitely and never returns to MFFTP. To resolve this, ensure that the correct credentials are supplied.

Parent topic: Micro Focus FTP Utility MFFTP


Major Features of the MFFTP Utility

The following features of the MFFTP utility relate to MVS datasets:

Fixed Block (FB) file support

Provides support for uploading and downloading FB files to and from the mainframe or non-mainframe servers.

The default values for MFFTP are RECFM=VB and LRECL=256, which are also the default values when uploading to the mainframe.

To upload a file to the mainframe as an FB file, use the following command to change the defaults:

QUOTE SITE RECFM=FB LRECL=XX

To download an MVS dataset as an FB file, use the LOCSITE command.

Variable Block (VB) file support

Provides support for downloading files from the mainframe or from non-mainframe servers in VB format when the control variable MFFTP_SENDEOL is set to a value other than ‘NONE’ or when the LOCSITE SBSENDEOL command is used.

If MFFTP_SENDEOL is not set (its default value is ‘NONE’) while downloading, the files are cataloged as VB but there is no file header in the physical file. Because of this, this file is not in a suitable format for uploading back to the mainframe. In such cases, the job ends with MAXCC=U00001 and you receive a message “File status of 39 (attributes mismatch)” in the console.

If MFFTP_SENDEOL is set to ‘CRLF’ while downloading VB files from the mainframe, it correctly creates a VB file with Micro Focus format-style file header and with the contents from the file on the mainframe. Similarly, in the case of non-mainframe servers, if MFFTP_SENDEOL is set to ‘CRLF’, ’CR’ or ’LF’, MFFTP correctly creates the VB file for a ‘GET’ command of a text file with ‘CRLF’, ’CR’, ’LF’ for end-of-line markers, respectively.

A VB file with an appropriate header record can be uploaded to the mainframe, either when MFFTP_SENDEOL is set to a value other than ‘NONE’ or if the LOCSITE command is used with SBSENDEOL=XX. If MFFTP_SENDEOL is not set while uploading a VB file, the ftp fails with error message “451-File transfer failed. File contains records that are longer than the LRECL of the new file.” To indicate the end-of-each record, you need to use the LOCSITE command with SBSENDEOL=CRLF or set MFFTP_SENDEOL=CRLF. If the file to be uploaded is in ASCII format, you must use the ftp command ‘ASCII’.

If SENDEOL is specified, MFFTP creates a temporary file as part of the FTP process. It is called fxxxxxxx.snnn.eol.zzzz, where xxxxxxx is the JES job number, nnn is the step number and zzzz is a sequence number. This temporary file is created by reading the file to be uploaded and copying its contents. The file is used in the transfer instead of the original physical file. For the PUT command, an end-of-line file (Line Sequential) is always created and used for the transfer of VB files, even if the SENDEOL parameter is not set.

Generation Data Group (GDG) file support

Provides support for uploading and downloading GDG files to and from the mainframe or non-mainframe servers. The GDG files can have different DCB parameters depending on the values specified by the LOCSITE and QUOTE SITE commands. If LOCSITE and QUOTE SITE are not specified, the generated files have default DCB values of RECFM=VB and LRECL=256. This is the same behavior as on the mainframe.

Parent topic: Micro Focus FTP Utility MFFTP
Related reference
MFFTP Statements
MFFTP Control Variables


Basic Operation

FTP clients in distributed environments do not understand mainframe dataset names. The primary goal of MFFTP is to provide a shell such that mainframe names are translated to distributed file system names and to interact with the catalog.

In addition, other functions are available to reformat data, such as converting text files, in Micro Focus line sequential format, to mainframe format, fixed or variable length records, as well as converting between character sets.

To achieve this, MFFTP goes through three phases:

  1. Reading standard FTP control cards to create an input file for the client.

    The cards are examined and certain ones are changed before being written to the client input file. Most notable of these are the GET and PUT statements. The local filename in these cases is a mainframe name which will be converted to a distributed file system name as would be seen in the catalog. If any errors occur, the program terminates.

  2. Invoking the client.

    MFFTP creates a command line and then invokes the command. The client receives the created input cards and executes them to produce an output.

  3. Reading the output from the client.

    MFFTP checks the output to ensure the commands executed correctly. If a command fails, MFFTP terminates with a non-zero return code or aborts. In addition, if files were fetched and need to be reformatted, MFFTP performs this at this point.

  • Differences Between FTP clients on a Mainframe and Distributed Platforms
  • MFFTP Statements
    List of commands with descriptions of action.
Parent topic: Micro Focus FTP Utility MFFTP


Differences Between FTP clients on a Mainframe and Distributed Platforms

There are many differences between the FTP client on the mainframe and those on the distributed platforms, most of these being related to the environment. For example, the distributed platform does not have access to DCB information or space allocations. The MFFTP utility uses the catalog facilities to provide both the missing links between the application requirements of attributes such as DCB and a means to translate between mainframe dataset names and the actual filenames on the distributed platform. When a request is made to FTP to GET or PUT a mainframe dataset, this has to be translated to a native filename.

You can specify default values on the mainframe in one of two ways: hard-code the values in the FTP application or use the SYSFTPD DD statement to specify them. MFFTP supports both methods.

You can make changes at execution time with a LOCSITE statement. Use a LOCSTAT command to display the relevant values and where they came from, for example - SYSFTPD, LOCSITE, an environment variable or a default value.

MFFTP scans the FTP control cards and either checks them, acts upon them, or simply passes them through. The utility expects control cards to start in column 1.

Parent topic: Basic Operation


MFFTP Statements

The following statements are checked and processed:

Command | Description
# or ; or * | Indicates a comment line.
APPEND | See PUT.
ASCII | Specifies that the transfer is in ASCII mode.
BINARY | Specifies that the transfer is in BINARY mode.
BYE | Ends the FTP session. If MFFTP does not find a BYE statement, it inserts one.
CD | Changes directory on remote machine. MFFTP performs a check that "spacey" directory names have been double quoted. If not then it will surround it in double quotes. If single quotes have been used they are replaced with double quotes.
GET

When this is executed, the local name, which would be a mainframe style name, is converted to native format.

If the file does not exist, it is cataloged with the current values as shown by LOCSTat.

If the file already exists within the catalog, the REPlace option must be used, and the existing catalog attributes will be used and the existing file overwritten.

LCD | Changes the directory on the local machine. MFFTP performs a check for "spacey" directory names in the same way that CD does.
LOCSIte

Many of the options of LOCSIte are not relevant to the Enterprise Developer

environment and are ignored.

The following options are supported:

  • BLKsize or BLOCKSize
  • LRecl
  • PRImary (space allocation)
  • RECfm
  • SECondary (space allocation)
  • SPACETYPE
  • SBSENDEOL
  • MBSENDEOL
  • SBDATACONN
  • MBDATACONN
LOCSTat | Provides a list of the current settings.
MFFTP_VARS | Lists the current settings of all MFFTP variables.
MGET

In order to obtain the list of files to be transferred and cataloged, the utility will attempt to connect to the server to produce a list of matches.

This list will be used to create a series of simple GET statements.

Note: All files are processed and cataloged with the same attributes.
MPUT | The catalog will be scanned to obtain a list of the files that match the filter criteria. A simple PUT will be created for each file that matches the criteria.
OPEN

If used, this must be the first statement.

If the OPEN statement has an IP address or host name, this will be overridden by any on the EXEC statement.

PROMPT | By default, MGET or MPUT prompts for confirmation. If no PROMPT is seen before an MGET or MPUT is encountered, one will be inserted before and after the generated simple statements.
PUT | When this is executed, MFFTP converts the local name, which would be a mainframe style name, to native format.
QUIT | Equivalent to BYE.
TYPE

The distributed platform expects ASCII or BINARY, while the mainframe allows A (ASCII) and I (BINARY).

MFFTP changes the command as appropriate for the respective platform. Using other values causes an error.

USER | MFFTP requires that you specify a user. If the keyword “USER” is not seen, it is assumed to be either the first (if no OPEN statement found) or second (if OPEN statement found) statement.
Parent topic: Basic Operation
Related concepts
Major Features of the MFFTP Utility


Configuring the MFFTP Utility

  • Specifying Control Variables
    You can set control variables from within Enterprise Server Administration or, put them into a dataset called FTP.DATA or , optionally, by specifying the ENVVAR DD statement in JCL.
  • MFFTP Control Variables
  • MFFTP DD Statements
    List of the DD statements required with MFFTP and their definition.
  • Input and Output Temporary Files
  • MFFTP Using SFTP As An FTP Client
    Using SFTP as an ftp client.
  • Configuring the End-of-Line Marker
    Change the end-of-line marker in the transferred files.
  • Configuring Error Codes
    How FTP client return codes relate to MFFTP error codes.
  • Configuring the Text of Messages
    Specifies how the text for the messages can be altered using sample programs as an example.
  • Using Data Conversion Modules with MFFTP
    To translate data before and after sending, you can either use the in-built ASCII-EBCDIC conversion modules, or you can write your own conversion module to handle other translations.
Parent topic: Micro Focus FTP Utility MFFTP


Specifying Control Variables

You set control variables for MFFTP in the JCL-enabled enterprise server from within Enterprise Server Administration as follows:

  1. Open Enterprise Server Administration.
  2. Click Edit on the row for your server.
  3. On the General page, enter the following in the Configuration Information field:
    [ES-Environment]
MFFTP_var-name=var-value
  4. Click OK.

You can create a cataloged DATASET called FTP.DATA that contains the control variables required . An example is provided in the example given in Running MFFTP.

You can use an optional ENVVAR DD statement to specify control variable values. You add this in the JCL STEP that runs MFFTP. This can be a physical dataset or instream data, as in the example given in Running MFFTP. The advantage of using this approach is that the values pertain only to the current execution and override any values set within Enterprise Server Administration.

For example - set MFFTP_KEEP to ‘N’ in the Enterprise Server Administration. When the files are required to diagnose an issue you can keep the files by adding the following DD entry in the JCL step:
//ENVVAR   DD *
MFFTP_KEEP=Y
Parent topic: Configuring the MFFTP Utility
Related reference
Running the MFFTP Utility


MFFTP Control Variables

You can use the following control variables to configure the MFFTP utility:

MFFTP_ABCODE=nnnn
If MFFTP has to abend, it defaults to a code of U0001. Use this variable to set a value in the range 1-4095.
MFFTP_ABEND=RC8
If MFFTP finds an error in the input stream or encounters an I/O error, the default action is to terminate with a user abend code U0001. Using this control variable instead stops the program immediately with a return code of 8.
MFFTP_CATALOG_CHARSET=xxx
By default, new datasets are cataloged with the servers character set. You can use this variable to override the character set. Acceptable values are:
  • A
  • ASC
  • ASCII
  • E
  • EBC
  • EBCDIC

If the specified character set does not match the server’s character set, you receive a warning message.

MFFTP_CHECK_221={Y | N}

When MFFTP processes a BYE or a QUIT command, the host FTP client should receive a message prefixed with 221. If no such message is received, this indicates a network or a similar failure.

If this variable is set to Y and the 221 message is not received, the return code is set to 4.

MFFTP_EXIT_EQUALS={N |Y}

By default, if MFFTP detects an error, it exits with a non-zero return code or abends with a U0001. See MFFTP_ABCODE for information about how to change the abend code.

If EXIT=nnnn is coded on the EXEC card PARM, setting this to Y causes MFFTP to return with a return code of nnnn.

MFFTP_CLIENT={FTP | USER}

Sets the FTP client to be invoked.

If this is not specified or is set to FTP, the host's default FTP client is used.

If USER is specified, you also need to specify MFFTP_USR_FTP_PGM, and point to a module that invokes an FTP client.

MFFTP_EPSV={N | Y}

Some FTP servers need to be sent the EPSV command after the USER command. The default is to keep the session as active.

Setting this to Y causes the server to enter into a passive FTP session. Use this if the server uses the IPv6 communications protocol. This enables FTP connections where the user is behind routers or firewalls, where connections over an active PORT/EPRT ftp session might not work.

MFFTP_FTP_DEBUG={1 | 2}

Inserts an FTP DEBUG command into the FTP command stream.

  • A value of 1 inserts the command as the first statement.
  • A value of 2 inserts the command after the logon credentials.
MFFTP_KEEP={N | Y | C}

If set to Y, all work files are kept at the end of the step unless MFFTP_KEEP_IP=N (see below) is also set, in which case the input work file is always deleted.

If set to C, the file is deleted if the return code from the FTP client is 0; otherwise the work files are kept.

MFFTP_KEEP_IP={N | Y}
If set to N, the input work files are deleted at the end of the step, even if MFFTP_KEEP is set to Y.
MFFTP_OUTPUT_LRECL=xxx
By default, the record size (LRECL) of the OUTPUT DD statement is 133-bytes. You can use this variable to change the record size to a maximum value of 512-bytes.
MFFTP_PREFIX={N | Y}
When set to Y, causes the server instance name to be used as a prefix to the temporary filenames.
MFFTP_PROCESS_TRAILS_ONGET={TRUE | FALSE}
Determines whether trailing spaces are processed during a GET command. The default is TRUE. Set to FALSE, in conjunction with the LOCSTAT value TRAILINGBLANKS=FALSE, to ignore any trailing blank spaces.
MFFTP_RETCODE=n1,n2,n3,n4
Determines the return code (condition code) returned to JES. By default, the return codes indicate:
0
No problems encountered.
4
MFFTP received output from the host FTP client that suggested an error, for example an error message in the 5nn or 4nn series. One or more commands might have failed. The “pass” or “fail” defaults can be seen in the supplied code for the MFFTPURR module which you can modify, if necessary.
8
MFFTP did not receive any output from the host FTP client that started with a recognized message number. This usually occurs if the FTP client fails to connect to the FTP server.
16
Some other fatal error.
The above four codes represent n1, n2, n3 and n4 respectively. These may be modified so that, for example, a return code of 8 is always required (MFFTP_RETCODE=0,8,8,8).
Note: All four values must be coded.
MFFTP_SENDEOL={NONE | CR | LF | CRLF}
Specifies the end-of-line characters that are typically found on text files on distributed systems. As an enterprise server instance with Mainframe Subsystem Support (MSS) is emulating a mainframe, using GET scans for the specified characters and removes them, and using a PUT command appends the specified characters to each logical record.
MFFTP_SYSPRINT_LRECL=xxx
By default, the record size (LRECL) of the SYSPRINT DD statement is 133 bytes. You can use this variable to change the record size to a maximum value of 512 bytes.
MFFTP_TEMP_DIR=dir
Specifies an absolute directory path rather than the default data directory where MFFTP creates the temporary files. The directory must already exist and be accessible by the server instance.
Note: On UNIX, ensure that this is entered using the same case as the target directory.
MFFTP_TIME={N | C | L | B}
MFFTP makes a record of the time it starts and ends, and calculates the elapsed time. It also makes a record of the time the FTP client is running. To display these times, set this directive with the following values:
N
Default, indicates no display.
C
Console
L
Listing
B
Both console and listing
MFFTP_TRANSLATE_SAFETY={ON | OFF}
By default, when code page translation is requested (by using the TRAN option on the EXEC card), MFFTP checks that a “round trip” will not corrupt data. It does this by simulating a PUT of a 256 byte area containing x’00’ through x’ff’. It then takes the resulting output and simulates a GET with that data. If the tables are correct, the result from the GET should equal the original data. Use this variable to ignore any warnings if the data does not match.
Note: Use this variable with caution.
MFFTP_UFLAG={N | Y}
Some FTP clients need to have the -u flag set. It stops MFFTP from attempting auto-authentication during the initial connection.
MFFTP_USR_FTP_PGM=program-name
This is required if MFFTP_CLIENT is set to USER. Specifies the name of a user-supplied module that invokes the FTP client.
Note: On UNIX, ensure that this is entered using the same case as the module or MFFTP reports that it is unable to call the module.
MFFTP_VERBOSE_OUTPUT={ON | OFF}
Determines what is written to the print file. By default, MFFTP prints a lot of information, including the original input cards and any errors that were encountered with them. When set to OFF, MFFTP only prints the output from the FTP client and server.
Parent topic: Configuring the MFFTP Utility
Related concepts
Major Features of the MFFTP Utility


MFFTP DD Statements

MFFTP requires one of the following DD statements:

INPUT
For JES2. Defines the command that will be sent to the native FTP client together with the actual FTP commands.
SYSIPT
For VSE. Defines the command that will be sent to the native FTP client together with the actual FTP commands.

MFFTP will use the following DD statements, if present:

OUTPUT
Specifies the preferred destination of all output including, for example, messages from MFFTP and the ftp client.
SYSPRINT
This can be used as an alternative to OUTPUT DD statement, to define preferred output destinations.
SYSFTPD
As on the mainframe. Only the keyword values described in the LOCSITE command are supported.
NETRC
As on the mainframe. This file, or in-stream data contains some login and initialization information. It is used to hide the login details in the JCL job card.
ENVVAR
Use this to code most of the control variables, one per line. It overrides any values set at a global level by, for example, the values in the FTP.DATA dataset.
Note: This is especially useful if you need to set MFFTP_KEEP to Y to resolve a problem when the same variable is set to N at system level.
Note: If neither OUTPUT nor SYSPRINT is present, a SYSOUT file is dynamically allocated to show the messages as well as display them in the console.

The default record length of OUTPUT and SYSPRINT is 133 characters. This may be overwritten with the variables MFFTP_OUTPUT_LRECL and MFFTP_SYSPRINT_LRECL, respectively. These variables accept a numeric value of up to 512.

Parent topic: Configuring the MFFTP Utility


Input and Output Temporary Files

MFFTP reads the input stream and creates a control file. It then invokes the appropriate FTP program, passes the control commands to it and redirects the output to a file, which is then parsed. These input and output files are created in the default data directory and are removed at the end of the task.

The naming conventions for these temporary input and output files are:

ftp.jxxxxxxx.snnn.ip and ftp.jxxxxxxx.snnn.op

Where:

  • xxxxxxx is the JES job number where MFFTP is running
  • nnn is the step number within the job
  • ip indicates this is the input file
  • op indicates this is the output file

This mechanism enables concurrent execution of multiple instances of MFFTP. The file names of the temporary files are unique because of the use of the job number and step number.

To override the location of these temporary files, set the environment variable MFFTP_TEMP_DIR.

To use the name of the enterprise server instance as a prefix in the filenames of these files, set MFFTP_PREFIX to Y. This helps make the files unique if several enterprise server instances are sharing the same MFFTP_TEMP_DIR location.

To keep these files after the end of the task for documentation, debugging or other purposes, optionally set the environment variable MFFTP_KEEP.

Parent topic: Configuring the MFFTP Utility


MFFTP Using SFTP As An FTP Client

Secure FTP or sftp is achieved by the main MFFTP program shelling out and invoking the putty sftp implementation.

This is FTP over secure shell or ssh , not FTPS or FTP using TLS.

Prerequisites

The putty toolset needs to be installed and on the path.

More specifically, the putty sftp executable psftp.exe is required.

These utilities can be downloaded from here

If you are going to use a certificate-based authorisation, a certificate needs to be available. Please refer to the putty documentation for the process used to do this.

Configuration

The following control Variables need to be configured:

MFFTP_CLIENT=SFTP
This configures the MFFTP program to use psftp as the ftp client.
MFFTP_SFTP_AUTH=n

Used to determine the artifacts to be used for authentication as follows:

Each of the 4 variables is assigned a value as follows:

1 – userid

2 – password

4 – certificate

8 – passphrase

Add the required values together to get elements to be used for authentication as follows:

1 - user id only

2 - password only

3 - userid plus password

4 - certificate only

5 - certificate plus userid

6 - certificate plus password

7 - certificate plus userid plus password

8 - invalid (need a certificate to have a passphrase)

9 - invalid

10 - invalid

11 - invalid

12 - certificate plus passphrase

13 - certificate plus passphrase plus userid

14 - certificate plus passphrase plus password

The following DD definitions provide the ability to configure authorisation parameters

  • //SFTPAUTH DD .....

    The following parameters are valid, replacing the text within <> with correct values

    machine <machine name>
    The machine name to connect for the session
    user <username>
    The user name to log in as
    pass <password>
    keypcn <path to ppk certificate file >
    Optional, only when using certificate authentication. It is preferable to store the certificate within a catalog-controlled dataset and use it in the SFTPPPK DD described below.
    keypass <pass phrase for use with ppk certificate >
    Optional. Only when using certificate and passphrase authentication.
    hostkey <specific hostkey for machine connecting to >
    This is optional. If not provided, this hostkey must exist in the machine's host key store. Please refer to putty documentation for more information.
  • //SFTPPPK DD .... Contains the ppk certificate to be used to connect to the sftp server . This method of storing the certificate is preferable to storing it on disk somewhere.

An example JCL to configure control variables in a dataset called FTP.DATA , and place the ppk certificate in a dataset called FTP.PRIV.DATA

//SETUP02 JOB 'FTP.DATA',MSGCLASS=X,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=FTP.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//DEL2    DD DSN=FTP.AUTH.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//DEL3    DD DSN=FTP.PRIV.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       FTP.PRIV CONFIGURATION FILE
//*==========================================================
//DEFPRIV  EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
PuTTY-User-Key-File-2: ssh-rsa
Encryption: aes256-cbc
Comment: slesz1
Public-Lines: 6
AAAAB3NzaC1yc2EAAAABJQAAAQEAmTd1uLtTsQ6RoyTuhzr3VxFBa0zAK7p91XbQ
sa1NRh9lcVs8zeI3xOzNfW4fyTAe4YUyLCxF0dSXTChDvJtqNeNa9bXiY/noTzc8
WmnWklGzOI+JoxLGIfFvzEN/LjxkB3Tzmc5ESsLLC/xTJrvcuCw/H5Wbh377xaKH
6S4NfXCtaYxWJ3vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv0MRfH15y8DqF9bWhOP6
ywmZAmIZqJeL+0cgeGFtADiV7DSGSrMyEvKayh1OTTRpgebJ40fFaqWvPW6D5yQW
LafvaQLh+OIuMc9iAUwhoetw7VNBLekIFUvwtpS6Pdrs98f0ZQ==
Private-Lines: 14
Wo+ACSDjbOHFd3XXSaYI+meJ5wgJklTLIRjYzJe6QB3bRelm0iSdPTo+lJ8Gtn0u
7mXHsszk0hXAtkv1nWAVPYszk5tk+kY/zuT9YVRp03nwsuW/WQkofNAn5C205/sC
WfvlklaYIBe5FBVmVUYu+p4FzTJYmshZDqMRLYGougB8LLI8knlRfmJn3jgjWR3Z
yRS7XIzgBExy+NX6dyv6UA1mWHU2kV22ao7NBot9M9p2BrVh8NTyYwc4SDz238H9
JIV50m+BZkmZLhRHUokABY3DwAzDQnQHMRFLJ8rOFkPw4WfrJHyy9Do1wU5PlqJ/
SF7FSpTVlzilP7aI5mzexdrXs5WZtxJ5wDvSHTUmtcQSh2YDLxAZf4IPavHsD+eM
nJh4AsU8Pvd4Op5ONPBJY1xrCdQ0AtfrvudFWjPlLJgm8901wo7Mzokbk3ys5sR+
IVu6FWCBk9iN+0KLLPxxxxxxxxxxxVmVzUK8AtbWkBr01bFSAbHiLgnwm1M4LwJz
r1vY96CrBGEfj7wCKeaFmw7FIvc1r8n3WyYcmUfiv0WqZeuBX+yb90QwxzarQBuD
Cbn7hgXgQq6ckE2BerhpM8TRpa2xHk5t0ACrZNyOIrfyRs6E+Bk6dmseMqWJYdRb
7lqdHH6smXW/fMLMurFv0P4WX7f4IPF4OrBG3CoJ3rBCTFXa6/+RaUjaC0/RKUtu
n09m8WLdxVemHhlrg99NQmLx9JEUSr+GbiriAgj5bdppZB5Niz3YiKodZVtcH3ow
90rND6pMrKF/Fs6Zkt7Oxf8bIX3yzs7dpq9OqWU0AuyS5oMwtyMdBjmDrTBEumoF
tKtHuQxX95/TXOJasCaMNRCb1RmGo7bbzo00Xjiq0UHj/fDZuGg9E1Dm2oXYGxg8
Private-MAC: 54aba03aff3cd77f65335b92b6a72df08034462b
/*
//SYSUT2  DD DSN=FTP.PRIV.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(RECFM=LSEQ,LRECL=80),DISP=(NEW,CATLG)
/
//*==========================================================
//*       FTP.AUTH CONFIGURATION FILE
//*==========================================================
//* keypcn d:\util\putty\keys\slesz11-3private.ppk
//DEFAUTH  EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *
machine slesz1 user fred pass password
keypass slesz1ABCDEF
hostkey 12:03:da:81:ea:49:6d:96:ed:6f:46:eb:84:27:4d:12
/*
//SYSUT2  DD DSN=FTP.AUTH.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
/
//*==========================================================
//*       FTP.DATA CONFIGURATION FILE
//*==========================================================
//DEFFTP   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *

; ---------------------------------------------------------------------
; MFFTP SETTINGS
; ---------------------------------------------------------------------

MFFTP_ABCODE 3085 ; SET DEFAULT ABEND CODE FOR MFFTP

MFFTP_OUTPUT_LRECL 120

MFFTP_PREFIX=Y
MFALLOC_LOC d:\temp\j1
;MFFTP_VERBOSE_OUTPUT ON
;MFFTP_KEEP_IP Y
;MFFTP_KEEP Y
MFFTP_CLIENT=SFTP
MFFTP_SFTP_AUTH=13
..... and so on

/*
//SYSUT2  DD DSN=FTP.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
//
An example JCL to use FTP using sftp.
//MFFTP05  JOB 'MFFTP TEST',CLASS=A,MSGCLASS=A
//* sftp flavour .
//*
//* Delete files
//*
//DEL1  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
 DELETE MFI01.MFFTP.FBFILE.TOUPLD FORCE
 DELETE MFI01.FTPDATA.FBFILE FORCE
 DELETE MFI01.MFFTP.GDG FORCE
 SET MAXCC=0
/*
//*
//* Allocate GDG base
//*
//ALLOC  EXEC  PGM=IDCAMS
//SYSPRINT DD  SYSOUT=*
//SYSIN    DD  *
  DEFINE  GDG -
         (NAME(MFI01.MFFTP.GDG) -
          LIMIT(5) -
          NOEMPTY -
          SCRATCH)
/*
//*
//* Create an FB/10 dataset
//*
//STEP0 EXEC PGM=IEBGENER
//SYSPRINT  DD SYSOUT=*
//SYSIN     DD DUMMY
//SYSUT1    DD *
AAAAAAAAAA
BBBBBBBBBB
/*
//SYSUT2    DD DSN=MFI01.MFFTP.FBFILE.TOUPLD,
//             DISP=(NEW,CATLG,DELETE),
//             DCB=(RECFM=FB,LRECL=10)
//*
//* Upload an MVS dataset
//*
//STEP1 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT  DD *
cd MFFTP_TEST
mkdir machine_os
cd machine_os
put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
quit
/*
//*
//* Download a text file to an MVS dataset (FB/10)
//*
//STEP2 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT DD *
cd MFFTP_TEST/machine_os
locsite recfm=fb lrecl=10
get MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
MFFTP_VARS
quit
/*
//*
//* Download a text file to a new GDG bias
//*
//STEP3 EXEC PGM=MFFTP,PARM='slesz11-3.microfocus.com'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//SFTPAUTH DD DSN=FTP.AUTH.DATA,DISP=(SHR)
//SFTPPPK  DD DSN=FTP.PRIV.DATA,DISP=(SHR)
//INPUT DD *
cd MFFTP_TEST/machine_os
locsite recfm=fb lrecl=10
locstat
get MFFTP01.txt MFI01.MFFTP.GDG(+1)
del MFFTP01.txt
cd ..
rmdir machine_os
/*
Parent topic: Configuring the MFFTP Utility


Configuring the End-of-Line Marker

The mainframe FTP appends an end-of-line marker to each record. FTP clients on distributed platforms do not do this as they have no concept of a record.

An instruction to append this end-of-line marker can be sent to MFFTP when issuing a PUT command.

By default, no marker is added. You can set it either at the job step level using the ENVVAR DD statement or at server level using the following control variable:

MFFTP_SENDEOL=xxxx

Where xxxx equals one of the following:

NONE
Adds nothing
CRLF
Adds a carriage return and a line feed (x’0D0A’)
CR
Adds a carriage return (x'0D')
LF
Adds a line feed (x’0A’)

You can also use the LOCSITE command to set the end-of-line marker. In this case, the variable name is either SBSENDEOL or MBSENDEOL, and the supported values are NONE, CRLF, CR, or LF. For example:

LOCSITE SBSENDEOL=CRLF

The LOCSITE command overwrites any other control settings and may be varied during a session. This allows you to transfer one file with a CRLF and the next one - without it.

If you use an SBSENDEOL or an MBSENDEOL followed by a space, the variable can be placed in the SYSFTPD file.

Note: If SENDEOL is specified, the original physical file is not transferred. Instead, a copy of the file is made with the name ftp.jxxxxxxx.snnn.eol.zzzz (where xxxxxxx is the JES job number, nnn is the step number and zzzz is a sequence starting at 1 for this invocation of MFFTP). This file contains the appropriate end-of-line characters and is the file that is transferred.

By default, when MFFTP terminates, this file is deleted. To keep the file, you need to set MFFTP_KEEP to Y. If SENDEOL is set to NONE and a GET is performed for a variable record file, the results are unlikely to be as expected, as the program has no way of determining the end of each record in the fetched file.

Parent topic: Configuring the MFFTP Utility


Configuring Error Codes

Once the FTP client program executes, MFFTP scans the output looking for standard FTP responses. These take the form of 3-digit codes – for example, 331 which means the user id is correct but a password is required. Based on these codes, MFFTP sets the JCL condition code to either 0 for no errors or 4 for one or more errors.

Generally, error 332 and the codes in the 4nn and 5nn range are treated as errors.

If no messages are found, this indicates that the client was unable to connect to the server and the return code is set to 8.

If the messages which are predefined as errors do not meet your needs, you can change them using the user-configurable module, MFFTPURR. Each message is given a “pass” or “fail” rating which you can change and compile. If an MFFTPURR load module is found, its definitions will be used instead of the default ones.

Parent topic: Configuring the MFFTP Utility


Configuring the Text of Messages

The text of each message is determined by the FTP server in use rather than by MFFTP, and varies depending on the server implementation. When checking the pass or fail status of each message, another user-configurable module, MFFTPMSG, is available to alter the text of the message.

MFFTPMSG provides an example of how to replace the text of the message identified by code 230 with the simple text “User logged on”. Replacing the text in this way can be useful when you want to hide the name of the user. As with MFFTPURR, the load module is used, if located.

MFFTPMSG and MFFTPURR are sample programs shipped with the product in the src directory of the <install-dir> directory. If you want to use any of these modules, you need to compile them and put them in a location where they can be loaded by the run-time system - on the PATH defined as the ‘JES Program Path’ in the definition of the enterprise server instance.

Parent topic: Configuring the MFFTP Utility


Using Data Conversion Modules with MFFTP

If you are required to perform some type of translation of data before sending a file or after receiving it, there are several options that you can use.

You can call MFFTP with a parameter stating that a conversion module should be used (for example, EXIT TRAN ASC2EBC), which would call the in-built ASCII to EBCDIC module. This would translate the file from ASCII to EBCDIC if the ftp action is PUT; the same module would be called to translate the received file from EBCDIC to ASCII if the ftp action is GET. Conversely, the in-built EBC2ASC module performs the reserve of these actions: EBCDIC to ASCII on PUT and ASCII to EBCDIC on GET).

You can also specify these data conversion modules using the SBDATACONN or MBDATACONN parameters of the LOCSITE command:

LOCSITE ENCODING=SBCS
LOCSITE SBDATACONN=ASC2EBC

If you need to perform any other type of translation, you can write your own conversion module - see Writing Your Own Data Conversion Module.

The jcl-examples section of the Samples Browser contains two sample conversion modules and the jobs required to run them.

  • MFTPDEM1.JCL uses a conversion module called MYE2A to perform a translation from EBCDIC to ASCII. This module uses a copybook (codeset.cpy) generated by the Codecomp module. Please note that MYE2A is just a sample, and should not be used as a general EBCDIC to ASCII conversion module.
  • MFTPDEM2.JCL uses a more specialised translation, by taking ASCII input and using the CBL_CONVERT_STRING function to produce UTF-8 output. This module is called IBM-1252.
  • Writing Your Own Data Conversion Module
Parent topic: Configuring the MFFTP Utility
Related reference
The Codecomp Utility
Codeset Translation


Writing Your Own Data Conversion Module

If you are writing your own data conversion module, because your require translations not offered by the in-built modules, the module:

  • Should have a name no longer than 8 characters.
  • be compiled with CHARSET"ASCII".
  • is called using the following interface:
    linkage section.
01  lk-function          pic x(3). *> PUT or GET
01  lk-len               pic 9(5). *> len of lk-data
01  lk-data.                       *> data to translate
    05  lk-bytes         pic x(1)
         occurs 32767 times.

procedure division using lk-function
                         lk-len
                         lk-data.
...

If the purpose of your module is to perform a translation from ASCII to EBCDIC, lk-function should be set to 'PUT', and if it is to perform a translation from EBCDIC to ASCII, lk-function should be set to 'GET'.

On return from your conversion module, lk-len should hold the length of the returned data. For a single-byte character set, these values will be unchanged, but for a double-byte character set, the length may be different. The retuned value is used by MFFTP to write the output record.

Your Micro Focus product already supports many different codesets, but with the Micro Focus development products, you can install additional ones - see The Codecomp Utility in the Codeset Translation section of the development documentation. The module you create for translation in MFFTP will be similar to the module described there using the sample CSnnnn.cbl program provided (described in To Customize Character Set Conversion). One notable difference is that the interface described above should not be compiled as 'NOCANCEL', as it is only being called from MFFTP.

If you find you have a more general need for a specialist codeset conversion module, and you create a CSnnnn program, you can code your MFFTP conversion module to call into that module.

The conversion module is called at least twice by MFFTP for each job step it is used in. The first 2 calls are to check that a 'round trip' translation works.

  • The first call is made with a data length (lk-len) of 256 and the data (lk-data) contains hexadecimal values from x'00' through to x'FF', and the function (lk-function) is PUT.
  • The second call contains the output from the first call, and the function is GET.

A comparison is then made to see that the return from the GET call is the same as the input to the PUT call. If the module fail this check, a warning message is issued and the module is not used unless the setting MFFTP_TRANSLATE_SAFETY=OFF is set.

The third and subsequent calls to the module is the translation of the data set, record by record.

Parent topic: Using Data Conversion Modules with MFFTP
Related reference
The Codecomp Utility
Codeset Translation


Running the MFFTP Utility

The following is a sample JCL job that creates the FTP.DATA control dataset and populates it with some variables.

The file format is based on the IBM FTP.DATA format .

//SETUP01 JOB 'FTP.DATA',MSGCLASS=X,CLASS=A,MSGLEVEL=(1,1)
//*--------------------------------------------------------
//DEL     EXEC PGM=IEFBR14
//DEL1    DD DSN=FTP.DATA,SPACE=(TRK,1),DISP=(MOD,DELETE)
//*==========================================================
//*       FTP.DATA CONFIGURATION FILE
//*==========================================================
//DEFFTP   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSIN    DD DUMMY
//SYSUT1   DD *

;***********************************************************************
;                                                                      *
;   Name of File:             SEZAINST(FTCDATA)                        *
;                                                                      *
;   Descriptive Name:         FTP.DATA  (for FTP Client)               *
;                                                                      *
;   SMP/E Distribution Name:  EZAFTPAC                                 *
;                                                                      *
;   Copyright:    Licensed Materials - Property of IBM                 *
;                                                                      *
;                 "Restricted Materials of IBM"                        *
;                                                                      *
;                 5694-A01                                             *
;                                                                      *
;                 Copyright IBM Corp. 1977, 2011                       *
;                                                                      *
;                 US Government Users Restricted Rights -              *
;                 Use, duplication or disclosure restricted by         *
;                 GSA ADP Schedule Contract with IBM Corp.             *
;                                                                      *
;   Status:       CSV1R13                                              *
;                                                                      *
;                                                                      *
;   This FTP.DATA file is used to specify default file and disk        *
;   parameters used by the FTP client.                                 *
;                                                                      *
;   Note: For an example of an FTP.DATA file for the FTP server,       *
;   see the FTPSDATA example.                                          *
;                                                                      *
;   Syntax Rules for the FTP.DATA Configuration File:                  *
;                                                                      *
;   (a) All characters to the right of and including a ; will be       *
;       treated as a comment.                                          *
;                                                                      *
;   (b) Blanks and <end-of-line> are used to delimit tokens.           *
;                                                                      *
;   (c) The format for each statement is:                              *
;                                                                      *
;       parameter value                                                *
;                                                                      *
;                                                                      *
;   The FTP.DATA options are grouped into the following groups in      *
;   this sample FTP client FTP.DATA configuration data set:            *
;                                                                      *
;   0.  MFFTP settings
;   1.  Basic configuration options                                    *
;   2.  Unix System Services file options                              *
;   3.  Default attributes for MVS data set creation                   *
;   4.  MVS data set transfer options                                  *
;   5.  Code page conversion options                                   *
;   6.  DB2 (SQL) interface options                                    *
;   7.  Security options                                               *
;   8.  Timers                                                         *
;   9.  Return codes                                                   *
;   10. Checkpoint / Restart options                                   *
;   11. Socks server access                                            *
;   12. Debug (trace) options                                          *
;   13. Additional advanced options                                    *
;                                                                      *
;   For options that have a pre-selected set of values, a (D) indicates*
;   the default value for the option.                                  *
;                                                                      *
;   Options that can be changed via LOCSITE subcommands are identified *
;   with an (S).                                                       *
;                                                                      *
;***********************************************************************

; ---------------------------------------------------------------------
; MFFTP SETTINGS
; ---------------------------------------------------------------------

MFFTP_ABCODE 3085 ; SET DEFAULT ABEND CODE FOR MFFTP

MFFTP_OUTPUT_LRECL 120

MFFTP_PREFIX=Y
MFFTP_VERBOSE_OUTPUT ON
MFFTP_KEEP_IP Y
MFFTP_KEEP Y

; ---------------------------------------------------------------------
;
; 1. Basic FTP client configuration options
;
; ---------------------------------------------------------------------
;SUPPRESSIGNOREWARNINGS  FALSE   ; Suppress message EZYFT47I
                                     ; while processing remaining
                                     ; statements in this FTP.DATA
                                     ; TRUE - Yes
                                     ; FALSE (D) - No. EZYFT47I is
                                     ; issued to warn of ignored
                                     ; statements
 FILETYPE          SEQ           ; (S) Client mode of operation
                                     ; SEQ = transfer data sets or
                                     ;       files (D)
                                     ; SQL = submit queries to DB2
;SEQNUMSUPPORT FALSE             ; Support sequence numbers when input
                                     ; read from //INPUT DD file
                                     ; FALSE = (D) Do not support
                                     ;         sequence numbers.
                                     ;         EZYFS33I issued if
                                     ;         sequence numbers detected

; etcetera ......
/*
//SYSUT2  DD DSN=FTP.DATA,SPACE=(TRK,1),UNIT=SYSDA,
//        DCB=(LRECL=80,RECFM=FB,DSORG=PS),DISP=(NEW,CATLG)
//

The following is a sample JCL job that executes MFFTP:

//MFFTP01  JOB 'MFFTP TEST',CLASS=A,MSGCLASS=A
//*
//* Upload an MVS dataset
//*
//STEP1 EXEC PGM=MFFTP,PARM='my.ftp.server'
//SYSOUT DD  SYSOUT=*
//OUTPUT DD  SYSOUT=*
//INPUT  DD *
anonymous/test
cd MFFTP_TEST
put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
locsite recfm=fb lrecl=10
locstat
;
get +
MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
MFFTP_VARS
quit
/*
//ENVVAR  DD *
MFFTP_CLIENT=FTP
MFFTP_KEEP=Y
MFFTP_TIME=L
/*
//*

When this JCL is submitted, assuming there are no errors, you should see messages in the console similar to the ones in When FTP is the Transport Client (MFFTP_CLIENT=FTP).

  • When FTP is the Transport Client (MFFTP_CLIENT=FTP)
    Example of messages output when operating with the MFFTP_CLIENT set to FTP.
  • When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)
    Output when operating with the MFFTP_CLIENT set to USER.
Parent topic: Micro Focus FTP Utility MFFTP
Related concepts
Specifying Control Variables


When FTP is the Transport Client (MFFTP_CLIENT=FTP)

When the JCL provided in Running MFFTP is submitted and there are no errors, you should see messages in the console similar to the ones below:

141211 15545316      10472 EDMFFTP  JCLCM0188I JOB01158 MFFTP01  JOB  STARTED 15:54:52
141211 15545356      10472 EDMFFTP  Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10:02 15:54:53
141211 15545376      10472 EDMFFTP  ftp -s:"C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip" > "C:\data\example\EDMFFTP\DATA\ftp01158.s001.op" 2>&1 15:54:53
141211 15545776      10472 EDMFFTP  JCLCM0182I JOB01158 MFFTP01  JOB  ENDED   - COND CODE 0000 15:54:57

The output from this job is similar to the following:

                Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10

INFO..............: V3.00.09  (32 bit) Created: 26Nov2014 10:02
INFO..............: MFFTP_CLIENT set to "FTP"
INFO..............: MFFTP_TIME set to "L"
INFO..............: Using user ftp error code checking module (MFFTPURR)
INFO..............:
INFO..............: Exec parm is "my.ftp.server".
INFO..............: 1st parm "my.ftp.server" used as remote host.
WARNING...........: Other exec parm options ignored
FTP Input.........: C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip
FTP Output........: C:\data\example\EDMFFTP\DATA\ftp01158.s001.op
FTP EOL temp file.: C:\data\example\EDMFFTP\DATA\ftp01158.s001.eol
FTP GET temp file.: C:\data\example\EDMFFTP\DATA\ftp01158.s001.wk1
INFO..............: SYSFTPD not found. Trying to work without it.
INFO..............: NETRC not found. Trying to work without it.
INPUT (data)......: anonymous/****
INFO..............: Assuming the above record is the userid & password.
INPUT (data)......: cd MFFTP_TEST
INPUT (data)......: put MFI01.MFFTP.FBFILE.TOUPLD MFFTP01.txt
INPUT (data)......: locsite recfm=fb lrecl=10
INPUT (data)......: locstat
LOCSTAT...........: The following options are in effect:
LOCSTAT...........:     - blksize=6233 from hard coded DEFAULTS
LOCSTAT...........:     - lrecl=10 from LOCSITE command
LOCSTAT...........:     - recfm=FB from LOCSITE command
LOCSTAT...........:     - space_units=TRK from hard coded DEFAULTS
LOCSTAT...........:     - primary_space_units=1 from hard coded DEFAULTS
LOCSTAT...........:     - secondary_space_units=1 from hard coded DEFAULTS
LOCSTAT...........:     - volume_serial=000000 from hard coded DEFAULTS
LOCSTAT...........:     - sendeol=NONE from hard coded DEFAULTS
LOCSTAT...........:     - dataconn=NONE from hard coded DEFAULTS
LOCSTAT...........:     - trailingblanks=TRUE from hard coded DEFAULTS
INPUT (comment)...: ;
INPUT (data)......: get +
INFO..............: Continuation marker found. Getting next record.
INPUT (data)......: MFFTP01.txt MFI01.FTPDATA.FBFILE (rep
WARNING...........: "MFI01.FTPDATA.FBFILE" already exists
WARNING...........:   and will be overwritten.
INPUT (data)......: MFFTP_VARS
MFFTP Variable....: MFFTP_ABCODE=(not_set)
MFFTP Variable....: MFFTP_ABEND=(not_set)
MFFTP Variable....: MFFTP_CHECK_221=(not_set)
MFFTP Variable....: MFFTP_CLIENT=FTP
MFFTP Variable....: MFFTP_DATACONN=(not_set)
MFFTP Variable....: MFFTP_DEBUG=(not_set)
MFFTP Variable....: MFFTP_ECHO_INPUT=(not_set)
MFFTP Variable....: MFFTP_EPSV=(not_set)
MFFTP Variable....: MFFTP_EXIT_EQUALS=(not_set)
MFFTP Variable....: MFFTP_KEEP=Y
MFFTP Variable....: MFFTP_KEEP_IP=(not_set)
MFFTP Variable....: MFFTP_OUTPUT_LRECL=(not_set)
MFFTP Variable....: MFFTP_PREFIX=(not_set)
MFFTP Variable....: MFFTP_RETCODE=(not_set)
MFFTP Variable....: MFFTP_SENDEOL=(not_set)
MFFTP Variable....: MFFTP_SFTP_AUTH=(not_set)
MFFTP Variable....: MFFTP_SFTP_CONNECT_TIMEOUT=(not_set)
                Micro Focus FTP Utility V3.00.09  (32 bit) Created: 26Nov2014 10

MFFTP Variable....: MFFTP_SFTP_ERRLVL=(not_set)
MFFTP Variable....: MFFTP_SFTP_IDLE_TIMEOUT=(not_set)
MFFTP Variable....: MFFTP_SYSPRINT_LRECL=(not_set)
MFFTP Variable....: MFFTP_TEMP_DIR=(not_set)
MFFTP Variable....: MFFTP_TIME=L
MFFTP Variable....: MFFTP_TRANSLATE_SAFETY=(not_set)
MFFTP Variable....: MFFTP_UFLAG=(not_set)
MFFTP Variable....: MFFTP_USRMSG=(not_set)
MFFTP Variable....: MFFTP_USR_FTP_PGM=(not_set)
MFFTP Variable....: MFFTP_VERBOSE_OUTPUT=(not_set)
MFFTP Variable....: MF_CHARSET=A
MFFTP Variable....: MFALLOC_LOC=C:\data\example\EDMFFTP\DATA
MFFTP Variable....: MFSYSCAT=C:\data\example\EDMFFTP\CATALOG.DAT
MFFTP Variable....: ES_SERVER=EDMFFTP
INPUT (data)......: quit
OUTPUT............: ftp> Connected to my.ftp.server.
OUTPUT............: open my.ftp.server
OUTPUT............: 220 Microsoft FTP Service
OUTPUT............: User (my.ftp.server:(none)):
OUTPUT............: 331 Password required for user
OUTPUT............:
OUTPUT............: 230 User logged in
OUTPUT............: ftp> cd MFFTP_TEST
OUTPUT............: 250 CWD command successful.
OUTPUT............: ftp> Local file Remote file put
OUTPUT............: C:\data\example\EDMFFTP\DATA\MFI01.MFFTP.FBFILE.TOUPLD.DAT
OUTPUT............: MFFTP01.txt
OUTPUT............: 200 PORT command successful.
OUTPUT............: 150 Opening ASCII mode data connection for MFFTP01.txt.
OUTPUT............: 226 Transfer complete.
OUTPUT............: ftp: 20 bytes sent in Seconds Kbytes/sec.
OUTPUT............: ftp> 0.350.06Local directory now C:\data\example\EDMFFTP\DAT
OUTPUT............: ftp> lcd "C:\data\example\EDMFFTP\DATA"
OUTPUT............: Remote file Local file get
OUTPUT............: MFFTP01.txt
OUTPUT............: C:\data\example\EDMFFTP\DATA\MFI01.FTPDATA.FBFILE.DAT
OUTPUT............: 200 PORT command successful.
OUTPUT............: 150 Opening ASCII mode data connection for MFFTP01.txt(20 by
OUTPUT............: 226 Transfer complete.
OUTPUT............: ftp: 20 bytes received in Seconds Kbytes/sec.
OUTPUT............: ftp> 0.0020.00bye
OUTPUT............: 221
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.op
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.wk1
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.log
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.ip
INFO..............: Kept: C:\data\example\EDMFFTP\DATA\ftp01158.s001.mget.log
INFO..............: Start............15:54:53.48
INFO..............: FTP Start........15:54:53.74
INFO..............: FTP End..........15:54:57.44
INFO..............: End..............15:54:57.45
INFO..............: Elapsed run time.   3.97 seconds
INFO..............: Elapsed FTP time.   3.70 seconds
Parent topic: Running the MFFTP Utility
Related information
When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)


When Using a Third Party as the Transport Client (MFFTP_CLIENT=USER)

The precise output depends on the client being used and what is coded within the module specified by MFFTP_USR_FTP_PGM, so no example is provided. The output will be similar to that which is provided in the example when FTP is the client - see When FTP is the Transport Client (MFFTP_CLIENT=FTP) . The lines prefixed with “OUTPUT” are from the client and may be different. The others, for example “INPUT” and “INFO”, will be the same as they are generated by MFFTP.

Parent topic: Running the MFFTP Utility
Related information
When FTP is the Transport Client (MFFTP_CLIENT=FTP)


Writing a Module to Support a Third Party FTP Client

By default, MFFTP uses the host's default FTP client for transfers. To support a third party client - for example, to provide FTPS support - it must be possible to invoke the client from a standard command line. As there could be an infinite number of variations of the commands to invoke a third party client, you need a user-written module to generate and invoke them.

The following sections describe how to configure MFFTP to invoke a third party client, the parameter block that will be passed to the user module, and what is expected of it.

  • MFFTP Invoking a Third Party Client
    MFFTP environment variables required to invoke a third party FTP client.
  • The Parameter Block
    Copybook code for the parameter block that is passed to the user module.
  • MFFTP Processing the User Module
    Requirements for writing a user module.
Parent topic: Micro Focus FTP Utility MFFTP


MFFTP Invoking a Third Party Client

You need to set the following two control variables to invoke the client:
  • Configure MFFTP to use a third party program.
    MFFTP_CLIENT=USER

  • A user-written module which is specified using MFFTP_USR_FTP_PGM invokes the third party program.

    MFFTP_USR_FTP_PGM=module

    This configures MFFTP to call the specified module, that will invoke the third part client.

If MFFTP-CLIENT is set to USER, MFFTP_USR_FTP_PGM must also be set and must name a module that is accessible to the batch process. If these conditions are not met, MFFTP aborts after validating the control cards.

Parent topic: Writing a Module to Support a Third Party FTP Client
Related information
The Parameter Block
MFFTP Processing the User Module


The Parameter Block

The code below is from the copybook MFUSRPRM.CPY. It describes the parameter block that is passed to the user module. The copybook is located in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\cpylib (Windows) or $COBDIR/cpylib (UNIX) directory. See the comments in the code for descriptions of each field:

      *===============================================================
      *   Copyright (C) 2007-2015 Micro Focus Limited.
      *   All rights reserved.
      *===============================================================

      *****************************************************************
      * Data items related to the module specified by MFFTP_USR_PGM   *
      *                                                               *
      * (tag)-usr-ftp-function-init                               *
      *   Function to be performed set as follows:                    *
      *   if (tag)-usr-ftp-function-init                          *
      *      used to cause the module to be loaded to ensure it exists*
      *   if (tag)-usr-ftp-function-call                          *
      *      normal call                                              *
      * (tag)-usr-ftp-return-code                                 *
      *   Indicate result of the call                                 *
      *   set (tag)-usr-ftp-ok true on an INIT call or if a       *
      *       normal call was deemed successful. The calling routine  *
      *       will scan the output to determine if the call to the    *
      *       FTP client was successful                               *
      *   set (tag)-usr-ftp-fail true if this module determines   *
      *       that there was a problem and that the calling module    *
      *       should not check the output                             *
      * (tag)-usr-ftp-ip-file-data.                               *
      *   Contains the length and fully qualified name of the file    *
      *   holding the normalised FTP control statements. This may be  *
      *   used directly or read to created an edited version as input *
      *   to the FTP client                                           *
      *    (tag)-usr-ftp-ip-name-len                              *
      *      actual length of the data in (tag)-usr-ftp-ip-name   *
      *    (tag)-usr-ftp-ip-name                                  *
      *      actual file name of the file holding the normalised FTP  *
      *      control statements                                       *
      * (tag)-usr-ftp-op-file-data.                               *
      *   Contains the length and fully qualified name of the file    *
      *   to hold the output from the FTP client that will be checked *
      *   (if appropriate) and printed by the calling routine. This   *
      *   may be the actual output from the FTP client or this        *
      *   routine may write an edited version here, for example to    *
      *   remove sensitive information.                               *
      *    (tag)-usr-ftp-op-name-len                              *
      *      actual length of the data in (tag)-usr-ftp-op-name   *
      *    (tag)-usr-ftp-op-name                                  *
      *      actual file name of the file to hold the output from the *
      *      FTP client (actual or edited)                            *
      * (tag)-usr-ftp-tmp-file-data.                              *
      *   Contains the length and the name of a directory that may be *
      *   used as a work are to hold temporary files.                 *
      *    (tag)-usr-ftp-tmp-name-len                             *
      *      actual length of the data in (tag)-usr-ftp-tmp-nam   *
      *    (tag)-usr-ftp-tmp-name                                 *
      *      The name of a directory that may be used to create       *
      *      temporary files, for example an edited input file or the *
      *      output from the FTP client before it is edited           *
      *****************************************************************
      *                                                               *
       01  (tag)-mfftp-usr-ftp-parm.
         05  (tag)-usr-ftp-function                pic x(1).
           88  (tag)-usr-ftp-function-init         value '0'.
           88  (tag)-usr-ftp-function-call         value '1'.
         05  (tag)-usr-ftp-return-code             pic x(1).
           88  (tag)-usr-ftp-ok                    value '0'.
           88  (tag)-usr-ftp-fail                  value '1'.
         05  (tag)-usr-ftp-msg1                    pic x(64).
         05  (tag)-usr-ftp-msg2                    pic x(64).
         05  (tag)-usr-ftp-pass-ip-data.
           10  (tag)-usr-ftp-pass-ip-fname-len     pic 9(3).
           10  (tag)-usr-ftp-pass-ip-fname         pic x(512).
         05  (tag)-usr-ftp-pass-op-data.
           10  (tag)-usr-ftp-pass-op-fname-len     pic 9(3).
           10  (tag)-usr-ftp-pass-op-fname         pic x(512).
         05  (tag)-usr-ftp-user-ip-data.
           10  (tag)-usr-ftp-user-ip-fname-len     pic 9(3).
           10  (tag)-usr-ftp-user-ip-fname         pic x(512).
         05  (tag)-usr-ftp-user-op-data.
           10  (tag)-usr-ftp-user-op-fname-len     pic 9(3).
           10  (tag)-usr-ftp-user-op-fname         pic x(512).
         05  (tag)-usr-ftp-temp-data.
           10  (tag)-usr-ftp-temp-fname-len        pic 9(3).
           10  (tag)-usr-ftp-temp-fname            pic x(512).
Parent topic: Writing a Module to Support a Third Party FTP Client
Related information
MFFTP Invoking a Third Party Client
MFFTP Processing the User Module


MFFTP Processing the User Module

The parameter block specified in the topic The Parameter Block is passed to the user module.

As a minimum, set the return code in the INIT function and return the call. This enables the user module to call MFFTP. If the user module requires any other initialization, you need to specify the required parameters at this point.

In the CALL function, the user module should do its normal processing. The module passes four unique filenames, two of which are required by MFFTP and two that might be used by this module.

While it is not a requirement to use these names, they must be unique within the Enterprise Server environment, allowing concurrent execution without locking files.

The “PASS-IP” (ftpxxxxx.snnn.ip) is a dynamically created text file which contains the control cards that MFFTP has checked and performed any reformatting on. As a minimum, the file should include the following four records:

  • Record 1: The open statement which holds the target server and potentially the port number. The format is “open”, target-server, port (if present) each separated by a space.
  • Record 2: The user id
  • Record 3: The password
  • Record 4: "bye"

The user module writes any output from the client to this file, as it is this file that MFFTP writes to the designated print file. The client could write directly to this file or to an intermediate file, and the user module can edit the output, for example, to mask any sensitive information such as the user id or the password.

Two sample modules are provided:

  • MFWSFTP. This uses the third-party client called WS_FTP Pro and shows a few examples of “editing” that can be done before actually invoking the client. It also shows how to invoke the client.
  • MFWINFTP. This uses the Windows FTP client. This is essentially the same as setting MFFTP_CLIENT=FTP.

The two sample modules can be found in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src (Windows) or $COBDIR/src/enterpriseserver/exit (UNIX) directories.

Different clients are likely to have different requirements. Micro Focus recommends that, if you wish to use this option, you either start from scratch by creating new modules or make a copy of one of the sample modules rather than modify the original files.

To access any of the control variables, you need to call MFFTP12 rather than use the DISPLAY ENVIRONMENT-NAME / ACCEPT ENVIRONMENT-VALUE method. This is because if the variable was set using the ENVVAR DD statement or configured in the FTP.DATA dataset , it does not exist within the environment space.

To retrieve any variable, call MFFTP12 as follows:

01  ws-var-name                             pic x(32).
01  ws-var-value                            pic x(256).

move "MFFTP_var-name" to ws-var-name.
call "MFFTP12" using ws-var-name
                     ws-var-value
end-call

After the call, if MFFTP locates the variable, it is in the second parameter.

If the value in the first parameter is not an MFFTP control variable, the first byte of the second parameter is set to x’FF’.

Parent topic: Writing a Module to Support a Third Party FTP Client
Related information
MFFTP Invoking a Third Party Client
The Parameter Block


Overview of the BMS Painter

The BMS Painter is a powerful, flexible tool for designing maps and generating the BMS macros necessary for creating displayable mapset objects. The painter can also generate the corresponding copybooks needed for using these maps from your program, and compile them into executable modules.

It is assumed that you are familiar with BMS fields, maps and mapsets and with the DFHMDF, DFHMDI and DFHMSD macros.

The following terminology is used both in this chapter and by the painter itself:

Field
An area, of a specified number of columns on an entry or display panel, designed to contain a single item of information of specified attributes and properties. Fields are arranged for display on a map. A painter field corresponds to a BMS field and is generated as a DFHMDF macro.
Attributes
Settings for the visible appearance of a field, for example, foreground and background color and highlighting.
Properties
Settings for the behavior and internal representation of a field or a map (for example, picture, justification, validation) or of a mapset (for example, BMS level, language, storage).
Map
An arrangement of fields on a display panel, designed for the entry and display of related items of information. A painter map corresponds to a BMS display map and is generated into the BMS macro file as a DFHMDI macro.
Mapset
A collection of related maps that generally are used for a single transaction. A painter mapset corresponds to a BMS mapset and is generated into the BMS macro file as a DFHMSD macro.
  • Using the BMS Painter
    Use the painter to design and define panels for the entry and display of data.
  • The Painter Window
    Use the painter window to create and edit maps.
Parent topic: Micro Focus BMS Painter


Using the BMS Painter

Use the painter to design and define panels for the entry and display of data.

To do this, you define maps and mapsets and generate these definitions into the corresponding BMS macros and COBOL and Assembler copybooks. You can create new maps or edit existing ones, whether created by you or downloaded from the mainframe (see the section Working with Previously Created Maps). You can create and edit a mapset either within a project or independently of any project.

You create a map by painting on it fields with specified attributes and properties. You design the map on-screen, so you can control precisely how it should appear.

Everything you paint on a map in a painter session is either static text or a named field. Both are automatically defined as fields (DFHMDF macros) when you generate the BMS macro file. For example:

  • If you only specify the text Name: on a map and then generate the BMS macro file, the painter defines that text as a 5-character autoskip (display-only) field with a constant value. (This is an unnamed DFHMDF macro.)
  • If, on the other hand, you want to control the usage of an area on the screen and the type of values it can contain, you must use the painter to define it explicitly as a field. This results in either a protected or an unprotected field defined in the BMS macro file and the appropriate variable described in the copybook.

By default, the painter generates copybook data descriptions for each field at the same level. You can, however, create group items by defining groups of fields in the painter.

Each field you create in the painter is generated as a BMS DFHMDF macro. Each field is also part of a map. With the painter you can group a collection of maps into a mapset. When you generate the BMS macro file, a DFHMDI macro defines each map and a DFHMSD macro defines the mapset.

The BMS Painter generates a BMS macro file (.bms file) as its output. By compiling this BMS macro file from the Files View you can generate a BMS COBOL copybook (.cpy file), Assembler copybook (.mac file) and a BMS load module (.mod file). Output options are explained in more detail in the section Generating Output from the Painter.

Parent topic: Overview of the BMS Painter
Related concepts
Working with Previously Created Maps
Generating Output from the BMS Painter


The Painter Window

Use the painter window to create and edit maps.

The window, shown in the figure below, is divided into two panes.

The left-hand pane contains a tree view of the mapset that is being edited. At the top level of the tree is the mapset name and beneath it, at the second level, are the names of the maps within the mapset. Beneath each map name, at the third level, are the names of the individual fields within the map. If a field does not have a name because it is a protected field that cannot receive input, the tree shows the field as "static text". You can expand and contract the tree view by clicking the + and - symbols to the left of the mapset and map names.

The right-hand pane of the painter window shows the contents of the map you are editing as it would appear on the terminal screen when displayed by the CICS transaction that uses it. In the right-hand pane you can add and delete fields and move and copy individual fields or groups of fields. You can initialize fields with text and define whether or not they can receive input. While you are editing the map in the right-hand pane, the tree view in the left-hand pane is constantly updated to highlight the field that is being edited.

You can edit more than one map in a painter session by using the new window function of the IDE (click New Window on the Window menu). You can then use the painter clipboard to copy from one map to another within a mapset. You can also have more than one painter session open (although they must be for different mapsets) and, again using the painter clipboard, you can copy between mapsets.

Note: You cannot copy and paste between the painter and the system clipboard.

The title bar at the top of the painter window shows the name of the BMS macro (.bms) file you are editing (unless this is a new file which you have not yet saved). You see an asterisk to the right of this filename whenever there are unsaved changes during the painter session. The asterisk disappears when the BMS macro file is saved.

The status line at the bottom of the IDE window shows, on the left, the painter operation being performed and, on the right, the position of the cursor. The cursor position is shown both as the line number and column number within the map and as the absolute position (or offset) from the start of the map.

Parent topic: Overview of the BMS Painter


Starting the BMS Painter Utility

Note: This option is only available for projects of type Mainframe Subsystem Application.
  • In COBOL Explorer, right-click a .bms file in your project and click Open With > BMS Painter.

    This starts the standalone Micro Focus BMS Painter utility and opens the .bms file in it.

Parent topic: Micro Focus BMS Painter


Configuring the BMS Painter

You can configure the BMS Painter using the settings available from the Options menu.

To specify your preferences for a fonts face and font size to use in the BMS painter screen and within the Output window:

  1. Click Options > Customize IDE.
  2. On the Fonts page, click BMS Painter and click Change choose your preferences for the font
  3. Click Output Window and click Change choose your preferences for the font

To specify BMS Screen painter options such as the BMS support level, map size, or options for tree or field display:

  • Click Options > BMS Painter to display this dialog box as shown in the figure below:

    The default settings on this dialog box should enable you to edit an existing BMS macro file or create a new mapset.

    See the popup help for each field for a description of what it does - click ? in the title bar, then click the field.

    You can see the View page of this dialog box in the figure below:

    Here you can specify whether the tree view shows macro entries or copybook entries.

Parent topic: Micro Focus BMS Painter


Build Settings for the BMS Painter

You specify BMS build settings for the BMS Painter in the properties of the BMS file within Enterprise Developer.

When the BMS file is opened from the Enterprise Developer IDE, the BMS build settings are passed to the BMS Painter.

You can use the Enterprise Developer templates to create and add BMS mapsets to your projects. In the IDE, you can open the BMS file properties and set the required BMS build settings. These settings are then used when you invoke the BMS Painter from Enterprise Developer.

The BMS build settings enable you to:

  • Specify what types of output you want the BMS Painter to produce
  • Specify an SDF prefix
  • Specify alignment
  • Override the default names given to output files (but only if you are specifying build settings for an individual .bms file)
  • Specify what COBOL levels you want to be used for data items generated by the BMS Painter
  • Specify that long macro lines can be used
  • Specify additional directives
Parent topic: Micro Focus BMS Painter
Related concepts
Generating Output from the BMS Painter
Working with Maps
Working with Previously Created Maps
Copybooks and Load Modules


Working with Maps

Use the BMS Painter to configure the contents of your map, such as creating fields, then grouping them together or creating an array of a particular field.

When you have a map open in the BMS Painter, you can:

  • Define individual fields

    Fields can be single or repeating and you define them by specifying text or by marking the relevant area on the map in the painter window.

    Any string of characters that you specify on a map is automatically generated by the painter as an autoskip BMS field. You must explicitly define any field you intend to use for displaying or accepting variable data; see the section Defining Field Properties.

  • Define groups of fields: standard BMS groups and SDF groups

    You can define groups of fields, for which you can specify common attributes for all the fields in the group. When you define a standard BMS group, you generate both a value for the BMS GRPNAME operand and a group item in the copybook.

  • Define SDF arrays

    You can define an SDF array by creating additional occurrences of a single field that you have already defined. The field must have a name defined for it on the Field Properties dialog box either in Field Name on the General page or in Name in the Field section on the SDF page. In the latter case the painter generates a field name on the General page.

    To create an SDF group or an SDF array you must have enabled the SDF option in the BMS file properties. See Build Settings for the BMS Painter.

  • Move fields

    You can move fields within a map either as single fields or in groups of fields. You can move fields between maps using the clipboard

  • Copy fields and groups

    You can copy fields within a map either as single fields or in groups of fields. When a field is copied, its properties are copied as well, except for any SDF array or SDF group information.

  • Delete fields

    You can delete fields and groups of fields.

Parent topic: Micro Focus BMS Painter
Related concepts
Build Settings for the BMS Painter


Defining Field, Map and Mapset Properties

You define the properties of fields, maps and mapsets using the Field Properties, Map Properties and Mapset Properties dialog boxes.

Many properties appear in all three dialog boxes, and where such properties are concerned, there is a hierarchy, with field properties at the top and mapset properties at the bottom. For example, you can specify at mapset level that entry fields are white; you can override this setting at the map level for all the fields in a map, and at field level for an individual field.

Note:

If you specify the blink attribute, each affected field is displayed in the BMS Painter window exactly as it would appear on the terminal screen. However, this attribute cannot be displayed in the Application Output window when the project is being run or debugged within the development system

  • Defining Field Properties
    Use the Field Properties dialog box to define the properties of a field.
  • Defining Map Properties
    Use the Map Properties dialog box to define the properties of the map.
  • Defining Mapset Properties
    Use the Mapset Properties dialog box to define the properties of the mapset.
Parent topic: Micro Focus BMS Painter


Defining Field Properties

Use the Field Properties dialog box to define the properties of a field.

Right-click the field in the right-hand pane of the painter window and click Properties to display the Field Properties dialog box shown in the figure below.

The properties shown on the General page are the ones you are most likely to want to set. In particular, to make a field able to accept input you must set it as unprotected. To do this, click Unprot in the Attrb area of the General page.

Parent topic: Defining Field, Map and Mapset Properties


Defining Map Properties

Use the Map Properties dialog box to define the properties of the map.

Double-click the map name in the tree view in the left-hand pane of the painter window to display the Map Properties dialog box, shown in the figure below.

These properties set the operand values for the corresponding BMS map definition macro DFHMDI.

Pages on the dialog box show the map properties. Depending on the configuration options set for the painter, some of the pages may not be displayed.

  • The Standard BMS page is displayed only if the painter is configured for standard or full BMS.
  • The Full BMS page is displayed only if the painter is configured for full BMS.

DBCS attributes are displayed on the DBCS page but they cannot be changed.

Note:

You can use the painter to specify values for all the DFHMDI operands, even though they might not be applied to the BMS macro file that is generated.

Parent topic: Defining Field, Map and Mapset Properties


Defining Mapset Properties

Use the Mapset Properties dialog box to define the properties of the mapset.

Double-click the mapset name in the tree view in the left-hand pane of the painter window to display the Mapset Properties dialog box, shown in the figure below.

These properties set the operand values for the corresponding BMS map definition macro DFHMSD.

Pages on the dialog box show the mapset properties. The Standard BMS page is displayed only if the painter is configured for standard or full BMS. DBCS attributes are displayed on the DBCS page but they cannot be changed

Parent topic: Defining Field, Map and Mapset Properties


Working with Previously Created Maps

You can open and work on a mapset that has been downloaded to your PC from the mainframe but as yet does not belong to a project.

When working on maps and mapsets created on the mainframe, you should bear the following in mind:

Maps and mapsets created on the mainframe may use the
      POS=number convention (as opposed to
      POS=(row,col)). The BMS macros are generated always in the
      POS=(row,col) format.

Overlapping fields are supported on downloaded maps but cannot be created with the painter. You can move an overlapping field by dragging it, but once it has been fixed on another part of the map it cannot be returned to its original overlapping position.

BMS files that contain conditional Assembler statements or COPY statements cannot be directly read. Before opening the files in the BMS Painter, you can edit them in Enterprise Developer to specify the PREPASM directive in the BMS file properties. See Build Settings for the BMS Painter.

Parent topic: Micro Focus BMS Painter
Related concepts
Build Settings for the BMS Painter


Generating Output from the BMS Painter

The painter can generate the following types of file:

  • BMS macro (.bms) files
  • Copybook (.cpy and .mac) files. Copybooks are generated when you have specified TYPE=DSECT in the mapset definition or by means of the SYSPARM build settings.
  • Load module mapset (.mod) files. A load module is also known as a CSECT and is generated when you have specified TYPE=MAP in the mapset definition or by means of the SYSPARM build settings.
  • Generated files list (.bmsx) file. Used by Enterprise Developer to keep track of the generated BMS Painter files and their locations. It resides in the same folder as .mod files.

The painter generates the files using the name that you gave to the mapset. You can specify different filenames using build settings; see the section Build Settings for the BMS Painter.

  • BMS Macro Files
    You create a BMS macro (.bms) file by saving the file that is open in the painter. You can save the file at any time while working on it in the painter or you can save it when you exit from the painter.
  • Copybooks and Load Modules
    You generate the copybook and load module files by compiling the BMS (.bms) file.
Parent topic: Micro Focus BMS Painter
Related concepts
Build Settings for the BMS Painter


BMS Macro Files

You create a BMS macro (.bms) file by saving the file that is open in the painter. You can save the file at any time while working on it in the painter or you can save it when you exit from the painter.

To save the file from the painter click Save on the File menu of the IDE. If you want to create a new BMS macro file click Save As on the File menu of the IDE and specify the new filename.

To save the file and exit from the painter click the close icon on the title bar of the painter and click Yes to save the changes. You cannot specify a new filename if you save the file in this way.

Parent topic: Generating Output from the BMS Painter


Copybooks and Load Modules

You generate the copybook and load module files by compiling the BMS (.bms) file.

You do this in Enterprise Developer.

The files generated are determined by the options specified on the General page of the Mapset Properties dialog box.

The language selected in the Lang group specifies the value of the LANG operand of the DFHMSD macro in the BMS source file. When you compile a BMS macro file, the value of the LANG operand is used to determine which type of copybook or include file to generate:

  • COBOL for a COBOL copybook (.cpy file)
  • ASM for an Assembler copybook (.mac file)
Note:

Generation of C DSECT (include) files is not currently supported.

The option selected in Type determines the files generated:

  • DSECT for a copybook
  • MAP for a load module
  • &&SYSPARM to indicate that the files to be generated are specified in the BMS build settings

If &&SYSPARM is selected you must specify whether you want to generate the copybook, the load module, or both, in the BMS file properties. See Build Settings for the BMS Painter.

It is not possible to compile the BMS file in Enterprise Developer while it is still open in the BMS painter. You need to save the file and close it in the BMS painter, then go to Enterprise Developer and compile the file with it.

The copybook (.cpy or .mac file) is created in the copylib folder of the project and the load module (.mod file) is created in the loadlib folder of the project.

Parent topic: Generating Output from the BMS Painter
Related concepts
Build Settings for the BMS Painter


BMS Compiler

Compiles BMS mapsets from the command line.

Syntax:

mfbmscl mymapset.bms/options

Parameters:

mymapset.bms
The file containing the BMS maps to be compiled
options
For details of the optional parameters, type mfbmscl in a Enterprise Developer command prompt, without defining any parameters or options
Parent topic: Micro Focus BMS Painter


BMS Painter Technical Details

The following section assumes that you are familiar with BMS fields, maps, and mapsets, and with the DFHMDF, DFHMDI, and DFHMSD macros.
  • The EXTATT, MAPATTS, and DSATTS Operands
  • Examples of SDF Copybooks
  • Handling Comments in BMS Macros
Parent topic: Micro Focus BMS Painter


The EXTATT, MAPATTS, and DSATTS Operands

The painter allows you to specify only the MAPATTS and DSATTS operands for map and mapset properties. You cannot specify the EXTATT operand (this was the old method of specifying attributes in the DFHMDI macro). You can find the MAPATTS and DSATTS operands on the Common Attributes page of the Map Properties and Mapset Properties dialog boxes.

Note:

The DSATTS attributes are generated in the order CPHVUMTO for the output portion of the symbolic description map to correspond to the CICS/ESA V3.3 data areas layout. The attributes are as follows:

C | Field Color
P | Programmed Symbol Set (PSS)
H | Field Highlight
V | Field Validation
U | Field Outlining
M | SO/SI Creation
T | Field Transparency
O | Output Data
Parent topic: BMS Painter Technical Details


Examples of SDF Copybooks

The following examples show the copybook entries created for different SDF arrays and groups. All these examples assume that the BMS Painter is set up for SDF and displays copybook entries in the tree view.

  • SDF Array
  • SDF Group
Parent topic: BMS Painter Technical Details


SDF Array

To create a one-dimensional SDF array:

  1. Create a field and name it on the Field Properties dialog box.
  2. Right-click the field and click Make Horizontal Array on the popup menu.
  3. Right-click the field and click Add Array Column on the popup menu.
  4. Right-click the field and click Add Array Row on the popup menu.
  5. Right-click the field and click Add Array Row on the popup menu.

Although the fields on the screen look as though they are arranged in a two-dimensional array, the copybook entry shows a one-dimensional SDF array. See the figure below.

The BMS macro file generated is:

SDFARR  DFHMSD LANG=COBOL,    -
               MODE=INOUT,    -
               STORAGE=AUTO,  -
               TIOAPFX=YES,   -
               TYPE=&&SYSPARM
SDFARR  DFHMDI SIZE=(24,80)
* FIELD
FIELD   DFHMDF LENGTH=4,      -
               POS=(5,9)
* FIELD
FIELD2  DFHMDF LENGTH=4,      -
               POS=(5,14)
* FIELD
FIELD3  DFHMDF LENGTH=4,      -
               POS=(5,19)
* FIELD
FIELD6  DFHMDF LENGTH=4,      -
               POS=(6,9)
* FIELD
FIELD5  DFHMDF LENGTH=4,      -
               POS=(6,14)
* FIELD
FIELD4  DFHMDF LENGTH=4,      -
               POS=(6,19)
* FIELD
FIELD9  DFHMDF LENGTH=4,      -
               POS=(7,9)
* FIELD
FIELD8  DFHMDF LENGTH=4,      -
               POS=(7,14)
* FIELD
FIELD7  DFHMDF LENGTH=4,      -
               POS=(7,19)
        DFHMSD TYPE=FINAL
        END

You can see that this is a horizontal array by looking at the SDF properties of the second field of the top row:

  1. Double-click the second field of the top row.
  2. Click the SDF tab.

This shows the field as "Index 2 of 9". The fields are counted across the screen.

If you make the array a vertical array by checking Vertical Array and look at the SDF properties again, the field is now shown as "Index 4 of 9". The fields are now counted down the screen.

Parent topic: Examples of SDF Copybooks


SDF Group

To create an SDF group:

  1. Create a field and name it on the Field Properties dialog box.
  2. Create a second and third field and name them.
  3. Select all three fields.
  4. Right-click one of the selected fields and click Make SDF Group on the popup menu.

Look at the SDF properties for one of the fields. The BMS Painter has assigned a default SDF group name. If you want to refer explicitly to the group array in the copybook, you must change this default group name. If you don't change the SDF group name, it will not be included in the BMS macro file.

Having created the SDF group you can repeat it:

  1. Right-click one of the fields in the group.
  2. Click Add Group Row on the popup menu.

The copybook entries show that this is a one-dimensional array (a repeated group).

The map now looks like the one shown in the figure below.

The default group name (assigned by the BMS Painter) was not changed and so does not appear in the generated BMS macro file:

SDFGRP1  DFHMSD
               LANG=COBOL,    -
               MODE=INOUT,    -
               STORAGE=AUTO,  -
               TIOAPFX=YES,   -
               TYPE=&&SYSPARM
SDFGRP  DFHMDI SIZE=(24,80)
* FIELDA
FIELDA  DFHMDF LENGTH=4,      -
               POS=(3,10)
* FIELDB
FIELDB  DFHMDF LENGTH=5,      -
               POS=(3,19)
* FIELDC
FIELDC  DFHMDF LENGTH=6,      -
               POS=(3,29)
* FIELDA
FIELDA2 DFHMDF LENGTH=4,      -
               POS=(4,10)
* FIELDB
FIELDB2 DFHMDF LENGTH=5,      -
               POS=(4,19)
* FIELDC
FIELDC2 DFHMDF LENGTH=6,      -
               POS=(4,29)
        DFHMSD TYPE=FINAL
        END
Parent topic: Examples of SDF Copybooks


Handling Comments in BMS Macros

The painter can recognize several types of comment embedded in the BMS macros. These comments are generated in the BMS macros by products such as IBM SDF and SDF II, and are used to specify long names for COBOL fields that are generated in the copybook (.cpy file). The painter also uses a special comment type that is used for fields that are repeated vertically or horizontally.

It is important to know what type of comments are embedded in your BMS macros before you try to import them into the painter. If you specify the wrong type, you might encounter problems because certain fields are not imported properly.

Note:

The painter only processes SDF comments and ignores any incidental comments that are embedded in the BMS source. Incidental comments are those that are for documentation and are not related to COBOL field names as described above. These incidental comments are ignored during BMS import and are not regenerated in the output BMS produced by the BMS Painter.

The comment formats that the painter can handle when the Enable SDF features check box is selected on the BMS build settings are as follows:

* 'COBOL-Name'
    DFHMDF POS=
* COBOL-Name
    DFHMDF POS=
* Group-Name.COBOL-name
DFHMDF POS=
* 'Group-Name.COBOL-Name'
    DFHMDF POS=
Parent topic: BMS Painter Technical Details


BMS Directives

There are a number of Compiler directives that are applicable to BMS files, and, depending on the directive, can be set in one of two ways.

There are two categories of BMS directives:

  1. Directives that you set in Enterprise Developer from the options within the BMS file properties. You should not try to set these explicitly.
    • ALIGN
    • ASM
    • BINARY
    • COBOL
    • CS
    • DP
    • DSECT
    • HLL
    • IGNORE
    • LEVEL
    • MAP
    • PLI
    • PREFIX
    • PREPASM
    • REDEFINPUT
    • SDF
    • SYSPARM
    • VERBOSE
  2. Directives that you set explicitly by typing them into Additional Directives:
    • DASH
    • DEPONLY
    • DSIZE
    • IE
    • NAMES
    • PCOMP
    • STRNAME
    • SYSLIB
  • Key to BMS Directives
    Descriptions for all of the BMS directives appear alphabetically.
  • ALIGN
    Specifies that data items are to be aligned on halfword boundaries.
  • ASM
    Specifies the output path of the assembler DSECT.
  • BINARY
    Specifies the output path of the map set load module (.mod).
  • COBOL
    Specifies the output path of the COBOL copybook.
  • CS
    Specifies the character to be used as the currency sign.
  • DASH
    Specifies that each field's generated DSECT name has an underscore separator between the name and the suffix.
  • DEPONLY
    Specifies that the only processing for the .bms file is a copybook dependency check; no output files are generated.
  • DP
    Specifies the character used as the decimal point.
  • DSECT
    Specifies the filename you want to use for the copybook to be created when the .bms file is compiled.
  • DSIZE
    Specifies that a half-word binary field containing the size of each map within an SDF map set is to be generated.
  • HLL
    Specifies whether or not long labels can be used for macros in .bms files.
  • IE
    Instructs the BMS compiler to ignore errors in the source file, and to create the output files irrespective of any error.
  • IGNORE
    Specifies that any SDF comment lines are to be ignored.
  • LEVEL
    Specifies that data definitions generated in the copybook are to use a specific set of level numbers.
  • MAP
    Specifies the filename you want to use for the load module to be created when the .bms file is compiled.
  • NAMES
    Specifies additional NLS (National Locale Support) characters that are to be allowed in macro labels.
  • PCOMP
    Enables you to specify a user program as a precompiler for BMS files.
  • PLI
    Specifies the output path of the PL/I include module.
  • PREFIX
    Specifies the SDF prefix to be used for SDF data items generated in the copybook.
  • PREPASM
    Specifies that the Assembler preprocessor is to be called before the BMS source is compiled, to expand COPY statements and hand-coded BMS macros in the BMS files into standard BMS statements. The pre-processor creates a BAL source file containing the BMS source file with COPY files expanded. The compiler references error messages in the BAL file.
  • REDEFINPUT
    Specifies that each field's attribute byte redefines the flag byte in the input map.
  • SDF
    Specifies that the .bms file contains SDF features.
  • STRNAME
    Specifies a top-level name for a map to be generated in the copybook.
  • SYSLIB
    Specifies the location of the Assembler macro library when the /PREPASM directive is specified.
  • SYSPARM
    Specifies which files are to be generated when the .bms file is compiled.
  • VERBOSE
    Specifies that informational and warning messages will be displayed during the compilation of the .bms file.
Parent topic: Micro Focus BMS Painter


Key to BMS Directives

Descriptions for all of the BMS directives appear alphabetically.

DIRECTIVE-NAME

A brief description of the function of DIRECTIVE-NAME.

Syntax:

>>--/-----.-----DIRECTIVE-NAME=parameter(s)-.---><
          +-----DIRECTIVE-NAME--------------+

The syntax of the Compiler 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.

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.

Parameters:

Lists and describes valid parameter(s), if any, for the directive.

Properties:

Default
Indicates the directive's default setting.
Setting in the IDE:
Describes how to set the directive from the file properties in the IDE.

Comments:

Contains any additional information about the directive.

Parent topic: BMS Directives


ALIGN

Specifies that data items are to be aligned on halfword boundaries.

Syntax:

>>--/----ALIGN-------------><

Parameters:

None

Properties:

Default
Data items are not aligned on halfword boundaries.
Setting in the IDE:
In the BMS file properties, check Align data items on half word boundaries .
Parent topic: BMS Directives
Related reference
Key to BMS Directives


ASM

Specifies the output path of the assembler DSECT.

Syntax:

>>--/----ASM=output-path-------------><

Parameters:

output-path
The directory to contain the generated assembler DSECT.

Properties:

Default
The directory is the same as that for the BMS input file.
Setting in the IDE:
In the BMS properties Outputs section, type a file path in the DSECT output field, or select one using the Browse... button.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


BINARY

Specifies the output path of the map set load module (.mod).

Syntax:

>>--/----BINARY=output-path-------------><

Parameters:

output-path
The directory to contain the compiled map set load module (.mod).

Properties:

Default
The directory is the same as that for the BMS input file.
Setting in the IDE:
In the BMS properties Outputs section, type a file path in the Binary Output field, or select one using the Browse... button.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


COBOL

Specifies the output path of the COBOL copybook.

Syntax:

>>--/----COBOL=output-path-------------><

Parameters:

output-path
The directory to contain the generated COBOL copybook.

Properties:

Default
The directory is the same as that for the BMS input file.
Setting in the IDE:
In the BMS properties Outputs section, type a file path in the DSECT output field, or select one using the Browse... button.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


CS

Specifies the character to be used as the currency sign.

Syntax:

>>--/----CS=currency-sign-------------><

Parameters:

currency-sign
The character to be used as the currency sign in the .bms file or files.

Properties:

Default
CS=$
Setting in the IDE:
In the BMS file properties, specify a character to use in the Currency character field.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


DASH

Specifies that each field's generated DSECT name has an underscore separator between the name and the suffix.

Syntax:

>>--/----DASH-------------><

Parameters:

None

Properties:

Default
Each field's generated DSECT name has no underscore separator.
Setting in the IDE:
Specify in Additional directives in the BMS file properties.

Example:

BMS

BENEF1   DFHMDF ATTRB=(ASKIP,BRT),                               X
               INITIAL='XX-X-XXXXXXX-X',LENGTH=14,POS=(07,28)

COBOL copybook

03 BENEF1_L                       PIC S9(4) COMP.
03 BENEF1_F                       PIC X.
03 FILLER REDEFINES BENEF1_F.
   05 BENEF1_A                    PIC X.
03 BENEF1_I                       PIC X(14).
Parent topic: BMS Directives
Related reference
Key to BMS Directives


DEPONLY

Specifies that the only processing for the .bms file is a copybook dependency check; no output files are generated.

Syntax:

>>--/----DEPONLY-------------><

Parameters:

None

Properties:

Default
The .bms file is compiled normally.
Setting in the IDE:
Specify in Additional directives in the BMS file properties.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


DP

Specifies the character used as the decimal point.

Syntax:

>>--/----DP=decimal-point-------------><

Parameters:

decimal-point
The character to be used as the decimal point in the .bms file or files, either . (period) or , (comma)

Properties:

Default
DP=.
Setting in the IDE:
In the BMS file properties, select a value in the Decimal point character field.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


DSECT

Specifies the filename you want to use for the copybook to be created when the .bms file is compiled.

Syntax:

>>--/----DSECT=dsect-name-------------><

Parameters:

dsect-name
The filename you want the copybook to have. The value *member* indicates that the copybook is to use the name of the PDS member for the mapset.

Properties:

Default
The name for the copy book is taken from the label of the DFHMSD macro.
Setting in the IDE:
In the BMS properties, check Use DSECT name in the Advanced section and specify the name in the respective field.

Comments:

The filename extension is .cpy if the option selected in the Lang group on the General page of the Mapset properties is COBOL, and .mac if the option selected is ASM.

Parent topic: BMS Directives
Related reference
Key to BMS Directives


DSIZE

Specifies that a half-word binary field containing the size of each map within an SDF map set is to be generated.

Syntax:

>>--/----DSIZE-------------><

Parameters:

None

Properties:

Default
No map size field is generated.
Dependencies
You must also specify the SDF directive.
Setting in the IDE:
Specify in Additional directives in the BMS file properties.

Example:

Generated COBOL copybook snippet

      ***************************************************************** 00000010
      *     LENGTH OF STRUCTURE                                         00000020
      ***************************************************************** 00000030
       01   CMMRES.                                                     00000040
           02 CMMRES-LENGTH  COMP PIC S9(4)  VALUE +362    .            00000050
      ***************************************************************** 00000060
      * MRES - CRUISE SYSTEM MAIN MENU                                  00000070
      ***************************************************************** 00000080
       01   CMMRESI.                                                    00000090
           02 FILLER    PIC X(12).                                      00000100
           02 CMMRES-H1MAPL  COMP PIC S9(4).                            00000110
           02 CMMRES-H1MAPF  PIC X.                                     00000120
           02 FILLER    PIC X(2).                                       00000130
           02 CMMRES-H1MAPI  PIC X(4).                                  00000140
Parent topic: BMS Directives
Related reference
Key to BMS Directives
SDF


HLL

Specifies whether or not long labels can be used for macros in .bms files.

Syntax:

>>--/----HLL-------------><

Parameters:

None

Properties:

Default
Macros can have only standard-length labels, that is, labels with up to seven characters.
Setting in the IDE:
In the BMS file properties, check Allow long macro label names in the Advanced section.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


IE

Instructs the BMS compiler to ignore errors in the source file, and to create the output files irrespective of any error.

Syntax:

>>--/----IE-------------><

Parameters:

None

Properties:

Default
The output files are not created if there are errors (return code >= 8) .
Setting in the IDE:
Specify in Additional directives in the BMS file properties.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


IGNORE

Specifies that any SDF comment lines are to be ignored.

Syntax:

>>--/----IGNORE-------------><

Parameters:

None

Properties:

Default
None.
Setting in the IDE:
In the BMS properties, on the BMS tab, ensure Enable SDF features is unchecked.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


LEVEL

Specifies that data definitions generated in the copybook are to use a specific set of level numbers.

Syntax:

>>--/----LEVEL=xx,yy,zz-------------><

Parameters:

LEVEL
The level numbers to be used.

Properties:

Default
LEVEL=01,03,05
Setting in the IDE:
In the BMS file properties, check Use levels and specify the levels to use.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


MAP

Specifies the filename you want to use for the load module to be created when the .bms file is compiled.

Syntax:

>>--/----MAP=map-name-------------><

Parameters:

map-name
The filename you want the load module to have. The value *member* indicates that the load module is to use the name of the PDS member for the mapset.

Properties:

Default
The name for the load module (.mod file) is taken from the label of the DFHMSD macro.
Setting in the IDE:
In the BMS file properties, on the BMS page, check Use MAP name in the Advanced section, and specify a name in the entry field.

Comments:

You can set this directive only for individual .bms files.

Parent topic: BMS Directives
Related reference
Key to BMS Directives


NAMES

Specifies additional NLS (National Locale Support) characters that are to be allowed in macro labels.

Syntax:

>>--/----NAMES=nls-characters-------------><

Parameters:

nls-characters

Properties:

Default
No NLS characters are allowed in macro labels other than those allowed by IBM CICS.
Setting in the IDE:
Specify in Additional directives in the BMS file properties.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


PCOMP

Enables you to specify a user program as a precompiler for BMS files.

Syntax:

>>--/----PCOMP=userprog-------------><

Parameters:

userprog
The user program to be used as a precompiler.

Properties:

Default
None

Comments:

The user program should return an internal filename.

If userprog is not found, the compilation fails.

The user program can use CBL_EXIT_PROC to perform some post-build processing.

Example:

working-storage section.
       01.
           05 install-flag       pic x comp-x.
           05 install-params.
               10 exit-proc-ptr  usage procedure-pointer.
               10                pic x.

       01 p-exit-block.
           03 p-block-size       pic x(4) comp-5 value 16.
           03 p-return-code      pic x(4) comp-5.
           03 p-rts-error        pic x(4) comp-5.
           03 p-exit-flags       pic x(4) comp-5.

       linkage section.
       01 source-file            pic x(256).

       procedure division using source-file.
           display source-file
      * On exit the file specified in source-file is the one
      * the compiler will actually compile
              move "EMPLOY.BMS" to source-file

           set exit-proc-ptr to entry "exitproc"
           move 0 to install-flag
           call "CBL_EXIT_PROC" using install-flag
                                       install-params
           end-call

      * Zero means continue, non-zero abort
       move 0 to return-code
           exit program
           .

       exitproc section.
       entry "exitproc".
           display "in exit proc"

           call "CBL_GET_EXIT_INFO" using     p-exit-block

           exit program
           .
Parent topic: BMS Directives
Related reference
Key to BMS Directives


PLI

Specifies the output path of the PL/I include module.

Syntax:

>>--/----PLI=output-path-------------><

Parameters:

output-path
The directory to contain the generated PL/I include module.

Properties:

Default
The directory is the same as that for the BMS input file.
Setting in the IDE:
In the BMS properties Outputs section, type a file path in the DSECT output field, or select one using the Browse... button.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


PREFIX

Specifies the SDF prefix to be used for SDF data items generated in the copybook.

Syntax:

>>--/----PREFIX=prefix-------------><

Parameters:

prefix
The prefix to use for SDF data items. The string "*map*" signifies that you want the map name to be used as a prefix. You can follow the string with an optional separator character, for example: "*map*-", "*map*_".

Properties:

Default
No prefix is used.
Setting in the IDE:
In the BMS file properties, on the BMS page, check Use SDF prefix in the Advanced section, and specify the prefix in the entry field. To set this directive, you must have checked Enable SDF features.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


PREPASM

Specifies that the Assembler preprocessor is to be called before the BMS source is compiled, to expand COPY statements and hand-coded BMS macros in the BMS files into standard BMS statements. The pre-processor creates a BAL source file containing the BMS source file with COPY files expanded. The compiler references error messages in the BAL file.

Syntax:

>>--/----PREPASM-.------.------><
                 +=KEEP-+

Parameters:

KEEP
By default, the BAL file is deleted at the end of the compilation. The KEEP parameter prevents the BAL file from being deleted so that positioning to reported errors can occur.

Properties:

Default
The Assembler preprocessor is not called.
Setting in the IDE:
Specify in Additional directives in the BMS file properties.

Comments:

You must have Enterprise Developer Assembler support installed on your machine to make use of this directive.

You can specify the location of the copybook requiring preprocessing with the SYSLIB directive.

Parent topic: BMS Directives
Related reference
Key to BMS Directives


REDEFINPUT

Specifies that each field's attribute byte redefines the flag byte in the input map.

Syntax:

>>--/----REDEFINPUT-------------><

Parameters:

None

Properties:

Default
Each field's attribute byte does not redefine the flag byte in the input map.
Setting in the IDE:
Specify in Additional directives in the BMS file properties.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


SDF

Specifies that the .bms file contains SDF features.

Syntax:

>>--/----SDF-------------><

Parameters:

None

Properties:

Default
None.
Setting in the IDE:
In the BMS file properties, on the BMS tab, check Enable SDF features.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


STRNAME

Specifies a top-level name for a map to be generated in the copybook.

Syntax:

>>--/----STRNAME=DFHMDI-name(map-structure-name)-------------><

Parameters:

DFHMDI-name
Name of map in .bms file, that is, the name of the DFHMDI macro for the map
map-structure-name
Name to be generated in the copybook

Properties:

Default
The name in the copybook is the same as the name in the .bms file.
Setting in the IDE:
Specify in Additional directives in the BMS file properties.

Comments:

You can repeat this directive for different map names within the mapset.

Parent topic: BMS Directives
Related reference
Key to BMS Directives


SYSLIB

Specifies the location of the Assembler macro library when the /PREPASM directive is specified.

Syntax:

>>--/----SYSLIB=directory-name-------------><

Parameters:

directory-name
The name of the directory containing the Assembler macro library.

Properties:

Default
mfe\mfasm\include
Setting in the IDE:
Specify in Additional directives in the BMS file properties.

Comments:

You must have Enterprise Developer Assembler support installed on your machine to make use of this directive.

You should specify this directive only if you also specify the /PREPASM directive.

Parent topic: BMS Directives
Related reference
Key to BMS Directives


SYSPARM

Specifies which files are to be generated when the .bms file is compiled.

Syntax:

>>--/----SYSPARM=output-type-------------><

Parameters:

output-type
The type of output file to be generated: MAP Load module containing screen-handling code
DSECT
Copybook containing data definitions for the screen

Properties:

Default
No files are generated, unless you have the TYPE= statement coded in the DFHMSD macro.
Setting in the IDE:
In the BMS file properties, on the BMS tab, under SYSPARM, check Map to set this directive for the value MAP or check DSECT to set this directive for the value DSECT.

Comments:

You can specify both Map and DSECT.

Parent topic: BMS Directives
Related reference
Key to BMS Directives


VERBOSE

Specifies that informational and warning messages will be displayed during the compilation of the .bms file.

Syntax:

>>--/----VERBOSE-------------><

Parameters:

None

Properties:

Default
Informational and warning messages are not displayed.
Setting in the IDE:
In the BMS file properties, on the BMS tab, check Verbose.
Parent topic: BMS Directives
Related reference
Key to BMS Directives


BMS Painter Keyboard Shortcuts

The following actions and navigational tools have the following keyboard shortcuts:

Menu Action | Key Sequence
Context menu | Shift+F10
Enable BMS Painter menu | ALT
Save mapset | Ctrl+S
Navigation | Key Sequence
Context menu | Shift+F10
Enable IDE menu | ALT
Save mapset | Ctrl+S
Bottom of map | End, End
End of line | End
First map (in mapset) | Ctrl+Home
Last map (in mapset) | Ctrl+End
Next field | Ctrl+Right
Next map | Ctrl+PgDn
Previous field | Ctrl+Left
Previous map | Ctrl+PgUp
Select field | Ctrl+Space
Start of field | Home
Start of line | Home, Home
Top of map | Home, Home, Home
Parent topic: Micro Focus BMS Painter


BMS Painter Compile Messages

  • BMSCH1003S - BMSCH1020E
    Lists the BMS Painter compile messages from BMSCH1003S through BMSCH1020E.
  • BMSCH1021E - BMSCH1040W
    Lists the BMS Painter compile messages from BMSCH1021E through BMSCH1040W.
  • BMSCH1041E - BMSCH1060I
    Lists the BMS Painter compile messages from BMSCH1041E through BMSCH1060I.
  • BMSCH1061I - BMSCH1080I
    Lists the BMS Painter compile messages from BMSCH1061I through BMSCH1080I.
  • BMSCH1081S - BMSCH1104I
    Lists the BMS Painter compile messages from BMSCH1081S through BMSCH1104I.
Parent topic: Micro Focus BMS Painter


BMSCH1003S - BMSCH1020E

Lists the BMS Painter compile messages from BMSCH1003S through BMSCH1020E.
  • BMSCH1003S Error opening filename
    File filename could not be opened.
  • BMSCH1004W Warning filename may already be open. Read only access acquired
    The painter could not obtain read/write access to the source file. It may be open in another process or the file may be marked as read only.
  • BMSCH1005I Opening file filename
    File filename is being opened.
  • BMSCH1008W feature is invalid if MAPATTS(feature) omitted
    feature is specified in a DFHMDF macro but not at the map or map set level.
  • BMSCH1009W Null (X'00') found in source - generated BMS may be incorrect
  • BMSCH1010W Field overlaps another with MODE=IN/INOUT
    The field attribute byte of one field falls within another field. This often occurs with stopper bytes that are defined with a length of one; the preferred length is zero. If editing, overlapping fields will be displayed correctly but once moved cannot be put back into an overlapping location.
  • BMSCH1011E Unexpected scanning error on filename
    Unexpected I/O error encountered reading source file, file may contain bad characters.
  • BMSCH1012S No DFHMSD macro was found
    The source file does not contain a DFHMSD macro.
  • BMSCH1013E Multiple DFHMSD macros found, only one permitted per file
    The source file contains more than one DFHMSD macro.
  • BMSCH1014E Unexpected verb verb-name found, remainder of macro discarded
    Whilst scanning for the DFHMSD new macro an unexpected or unrecognized keyword was found.
  • BMSCH1015E Error closing file
    The file could not be closed.
  • BMSCH1016W Mutually exclusive operands operands found in macro-name macro, last value assumed
    Two mutually exclusive operands were found in the same macro, for example INITIAL and XINIT operands on a DFHMDF macro.
  • BMSCH1017W Duplicate operands (operands) found in macro-name macro, last value assumed
    The same operand was found twice within the same macro.
  • BMSCH1018E Unrecognized option option-name found processing operand operand of macro-name macro
    An unrecognized or unsupported option was found processing the specified operand. For each operand (for example COLOR) there are a set of valid options that can be specified (for example BLUE, RED, PINK, GREEN, TURQUOISE, YELLOW, and NEUTRAL).
  • BMSCH1019E The length option (HONEOM, L40, L64, or L80) for the CTRL operand for the macro-name macro was encountered more than once
  • BMSCH1020E name was expected but found name
    An error occurred when tokenizing a macro. For example, options for the ATTRB operand can be enclosed in parenthesis such as ATTRB=(UNPROT,NORM).
Parent topic: BMS Painter Compile Messages


BMSCH1003S Error opening filename

File filename could not be opened.

Resolution:

Check that the file exists.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1004W Warning filename may already be open. Read only access acquired

The painter could not obtain read/write access to the source file. It may be open in another process or the file may be marked as read only.

Resolution:

You can still edit a mapset that has read-only access. Selecting "Save" for a read-only file results in a "Save As" dialog that lets you save the file with a different filename.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1005I Opening file filename

File filename is being opened.
Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1008W feature is invalid if MAPATTS(feature) omitted

feature is specified in a DFHMDF macro but not at the map or map set level.

Resolution:

Remove feature from the DFHMDF macro or specify it at the map or map set level.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1009W Null (X'00') found in source - generated BMS may be incorrect

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1010W Field overlaps another with MODE=IN/INOUT

The field attribute byte of one field falls within another field. This often occurs with stopper bytes that are defined with a length of one; the preferred length is zero. If editing, overlapping fields will be displayed correctly but once moved cannot be put back into an overlapping location.
Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1011E Unexpected scanning error on filename

Unexpected I/O error encountered reading source file, file may contain bad characters.

Resolution:

Correct the file.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1012S No DFHMSD macro was found

The source file does not contain a DFHMSD macro.

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1013E Multiple DFHMSD macros found, only one permitted per file

The source file contains more than one DFHMSD macro.

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1014E Unexpected verb verb-name found, remainder of macro discarded

Whilst scanning for the DFHMSD new macro an unexpected or unrecognized keyword was found.

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1015E Error closing file

The file could not be closed.

Resolution:

Check that connections to the mainframe are still operational.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1016W Mutually exclusive operands operands found in macro-name macro, last value assumed

Two mutually exclusive operands were found in the same macro, for example INITIAL and XINIT operands on a DFHMDF macro.

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1017W Duplicate operands (operands) found in macro-name macro, last value assumed

The same operand was found twice within the same macro.

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1018E Unrecognized option option-name found processing operand operand of macro-name macro

An unrecognized or unsupported option was found processing the specified operand. For each operand (for example COLOR) there are a set of valid options that can be specified (for example BLUE, RED, PINK, GREEN, TURQUOISE, YELLOW, and NEUTRAL).

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1019E The length option (HONEOM, L40, L64, or L80) for the CTRL operand for the macro-name macro was encountered more than once

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1020E name was expected but found name

An error occurred when tokenizing a macro. For example, options for the ATTRB operand can be enclosed in parenthesis such as ATTRB=(UNPROT,NORM).

This error would be produced if the closing parenthesis was not found.

Resolution:

Correct the source.

Parent topic: BMSCH1003S - BMSCH1020E


BMSCH1021E - BMSCH1040W

Lists the BMS Painter compile messages from BMSCH1021E through BMSCH1040W.
  • BMSCH1021E Missing label for DFHMSD macro
    The DFHMSD macro has no label.
  • BMSCH1022W Operand operand of the macro-name macro is not supported at Minimum BMS level (Standard/Full required)
  • BMSCH1023I The painter is currently at the level BMS support level
  • BMSCH1024S End of file encountered before DFHMDI
  • BMSCH1025E Bad char found processing FLDSEP, length should be <= value
  • BMSCH1026W Operand keyword keyword of the macro-name macro only available at FULL BMS support level
  • BMSCH1027E DFHMSD label (label) too long - truncating to label
  • BMSCH1028E FLDSEP hex value's length should be <= value
  • BMSCH1029E LDC string value length should be value
  • BMSCH1030E Unexpected option option-name found processing operand operand of macro-name macro
  • BMSCH1031I BOX cannot be specified for OUTLINE with LEFT, RIGHT, OVER, or UNDER
  • BMSCH1032W Duplicate options (option-name) found for operand operand of the macro-name macro
  • BMSCH1033E Bad char found processing PS, length should be <= value
  • BMSCH1034E PS hex value's length should be <= value
  • BMSCH1035E Bad value specified for SUFFIX parameter, length should be value
  • BMSCH1036E Mutually exclusive operands operand found in macro-name macro, last value ignored
  • BMSCH1037S Missing label for DFHMDI macro
  • BMSCH1038E Mutually exclusive options option-name for operand operand in macro-name macro
  • BMSCH1039W Option option-name for the operand operand of the macro-name macro only available at FULL BMS support level
  • BMSCH1040W DFHMSD label mismatch - original (label), ending (label)
Parent topic: BMS Painter Compile Messages


BMSCH1021E Missing label for DFHMSD macro

The DFHMSD macro has no label.

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1022W Operand operand of the macro-name macro is not supported at Minimum BMS level (Standard/Full required)

Resolution:

Delete the operand or change the level of BMS that the screen painter is using.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1023I The painter is currently at the level BMS support level

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1024S End of file encountered before DFHMDI

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1025E Bad char found processing FLDSEP, length should be <= value

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1026W Operand keyword keyword of the macro-name macro only available at FULL BMS support level

Resolution:

Delete the keyword or change the level of BMS that the screen painter is using.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1027E DFHMSD label (label) too long - truncating to label

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1028E FLDSEP hex value's length should be <= value

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1029E LDC string value length should be value

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1030E Unexpected option option-name found processing operand operand of macro-name macro

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1031I BOX cannot be specified for OUTLINE with LEFT, RIGHT, OVER, or UNDER

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1032W Duplicate options (option-name) found for operand operand of the macro-name macro

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1033E Bad char found processing PS, length should be <= value

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1034E PS hex value's length should be <= value

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1035E Bad value specified for SUFFIX parameter, length should be value

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1036E Mutually exclusive operands operand found in macro-name macro, last value ignored

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1037S Missing label for DFHMDI macro

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1038E Mutually exclusive options option-name for operand operand in macro-name macro

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1039W Option option-name for the operand operand of the macro-name macro only available at FULL BMS support level

Resolution:

Correct the source or change the level of BMS that the screen painter is using.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1040W DFHMSD label mismatch - original (label), ending (label)

Resolution:

Correct the source.

Parent topic: BMSCH1021E - BMSCH1040W


BMSCH1041E - BMSCH1060I

Lists the BMS Painter compile messages from BMSCH1041E through BMSCH1060I.
  • BMSCH1041E A bad token, token-name, was encountered before processing DFHMDI
  • BMSCH1042S End of file encountered before end of DFHMDI processing
  • BMSCH1043E Duplicate DFHMDI label label, skipping map
  • BMSCH1044S COPY not supported
  • BMSCH1045E Invalid hex value value specified for operand operand of macro-name macro
  • BMSCH1046E DFHMDF label (label) too long - truncating to label
  • BMSCH1047E Duplicate DFHMDF label label, skipping field
  • BMSCH1048W Single quote found in INITIAL string
  • BMSCH1049W Single ampersand found in INITIAL string
  • BMSCH1050W Truncating PARTN name from name to name
  • BMSCH1051W Unrecognized operand operand found processing macro-name macro
  • BMSCH1052W DSATTS option-name option specified, assuming corresponding MAPATTS for macro-name macro
  • BMSCH1053S Out of memory, allocating new item
  • BMSCH1054S End of file encountered before end of DFHMDF processing
  • BMSCH1055E Error (value) occurred verifying name at position value of name
    The picture clause specified in the PICIN/PICOUT statement was determined to be illegal.
  • BMSCH1056E Hex string string is not even length, ignoring last character
  • BMSCH1057E DFHMDI label (label) too long - truncating to label
  • BMSCH1058W Fields starting at bottom right corner of map cannot have ATTRB=IC - ignoring option
  • BMSCH1059E Error interpreting SDF information - continuing with SDF support disabled
    SDF features are enabled for the file but an unexpected error occurred processing the comment fields preceding the DFHMDF macros. The file may not contain valid SDF information or may be in a format not recognized by the screen painter.
  • BMSCH1060I BMS source load complete, interpreting SDF information
Parent topic: BMS Painter Compile Messages


BMSCH1041E A bad token, token-name, was encountered before processing DFHMDI

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1042S End of file encountered before end of DFHMDI processing

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1043E Duplicate DFHMDI label label, skipping map

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1044S COPY not supported

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1045E Invalid hex value value specified for operand operand of macro-name macro

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1046E DFHMDF label (label) too long - truncating to label

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1047E Duplicate DFHMDF label label, skipping field

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1048W Single quote found in INITIAL string

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1049W Single ampersand found in INITIAL string

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1050W Truncating PARTN name from name to name

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1051W Unrecognized operand operand found processing macro-name macro

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1052W DSATTS option-name option specified, assuming corresponding MAPATTS for macro-name macro

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1053S Out of memory, allocating new item

Resolution:

Close some applications on your PC to make more memory available.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1054S End of file encountered before end of DFHMDF processing

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1055E Error (value) occurred verifying name at position value of name

The picture clause specified in the PICIN/PICOUT statement was determined to be illegal.

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1056E Hex string string is not even length, ignoring last character

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1057E DFHMDI label (label) too long - truncating to label

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1058W Fields starting at bottom right corner of map cannot have ATTRB=IC - ignoring option

Resolution:

Correct the source.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1059E Error interpreting SDF information - continuing with SDF support disabled

SDF features are enabled for the file but an unexpected error occurred processing the comment fields preceding the DFHMDF macros. The file may not contain valid SDF information or may be in a format not recognized by the screen painter.

Resolution:

Correct the source or turn off SDF features for the file.

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1060I BMS source load complete, interpreting SDF information

Parent topic: BMSCH1041E - BMSCH1060I


BMSCH1061I - BMSCH1080I

Lists the BMS Painter compile messages from BMSCH1061I through BMSCH1080I.
  • BMSCH1061I Detected repeating group of fields in map mapname, generating implied SDF group (groupname)
    An duplicate SDF field name was found separated by other named fields. This is assumed to be a repeating SDF group. An implied SDF group name was generated to logically identify fields belonging to the SDF group.
  • BMSCH1062I Detected repeating field (fieldname) in map mapname, processing as SDF field array
    A duplicate SDF field name that was not separated by other named fields was found. This is assumed to be an SDF array.
  • BMSCH1063I Processing map mapname
  • BMSCH1064S Missing comma after operand with continuation, continuation cards ignored
  • BMSCH1065E Quoted string missing terminating quote
  • BMSCH1066S value syntax errors found, parsing terminated at line value
    Multiple errors were found during the loading of the source file so loading was terminated. These errors may be a result of an earlier parsing error so try to determine the cause of the initial error.
  • BMSCH1067S Error interpreting SDF field array (name) - all array fields must be equal length
  • BMSCH1068S Invalid or unrecognized SDF comment format (name)
  • BMSCH1069S Error processing SDF group (groupname), continuing with SDF support disabled
  • BMSCH1070I Detected repeating SDF group (groupname) in map mapname
  • BMSCH1071I SDF interpretation complete
  • BMSCH1072S Found DFHMDF macro before DFHMDI
    The DFHMDI macro must precede any DFHMDF macros.
  • BMSCH1073S Found DFHMDI macro before DFHMSD
    The DFHMSD macro must precede any DFHMDI macros.
  • BMSCH1074W ATTRB option name conflicts with name, defaulting to ASKIP
  • BMSCH1075E Length of picture clause picture specified for PICIN/PICOUT does not match field length of length"
    The picture length specified with either a PICIN or PICOUT operand does not match the field length specified with the LENGTH operand in the DFHMDF macro.
  • BMSCH1076E Illegal character found at position posn of PICIN/PICOUT picture clause picture
    The character at position posn in the PICIN / PICOUT operand is not a valid picture character for the language specified with the LANG operand in the DFHMSD macro.
  • BMSCH1077E PICIN/PICOUT picture clause is too long (picture)
    COBOL has a limit of 30 characters in a picture clause. The picture you have specified in the PICIN or PICOUT field exceeds this limit.
  • BMSCH1078W Unable to locate picture clause validation routines, unable to validate picture picture specified in PICIN/PICOUT
    Enterprise Developer has been unable to find the picture clause validation routines. These routines are installed as part of the Enterprise Developer installation procedure and may have been deleted, moved or corrupted.
  • BMSCH1079W PICIN/PICOUT is illegal for languages other than COBOL and PL/I
    The PICIN and PICOUT operands are only valid for mapsets created for COBOL and PL/I programs. Enterprise Developer disregards PICIN and PICOUT operands for languages other than COBOL and PL/I.
  • BMSCH1080I Enabling SDF features to convert BMS/GT format source
    This message is displayed when you open a map created with GT Software's BMS/GT program. These maps make use of SDF features so Enterprise Developer enables SDF support.
Parent topic: BMS Painter Compile Messages


BMSCH1061I Detected repeating group of fields in map mapname, generating implied SDF group (groupname)

An duplicate SDF field name was found separated by other named fields. This is assumed to be a repeating SDF group. An implied SDF group name was generated to logically identify fields belonging to the SDF group.
Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1062I Detected repeating field (fieldname) in map mapname, processing as SDF field array

A duplicate SDF field name that was not separated by other named fields was found. This is assumed to be an SDF array.
Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1063I Processing map mapname

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1064S Missing comma after operand with continuation, continuation cards ignored

Any information which is included in the continuation cards is being ignored.

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1065E Quoted string missing terminating quote

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1066S value syntax errors found, parsing terminated at line value

Multiple errors were found during the loading of the source file so loading was terminated. These errors may be a result of an earlier parsing error so try to determine the cause of the initial error.

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1067S Error interpreting SDF field array (name) - all array fields must be equal length

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1068S Invalid or unrecognized SDF comment format (name)

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1069S Error processing SDF group (groupname), continuing with SDF support disabled

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1070I Detected repeating SDF group (groupname) in map mapname

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1071I SDF interpretation complete

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1072S Found DFHMDF macro before DFHMDI

The DFHMDI macro must precede any DFHMDF macros.

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1073S Found DFHMDI macro before DFHMSD

The DFHMSD macro must precede any DFHMDI macros.

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1074W ATTRB option name conflicts with name, defaulting to ASKIP

Resolution:

Correct the source.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1075E Length of picture clause picture specified for PICIN/PICOUT does not match field length of length"

The picture length specified with either a PICIN or PICOUT operand does not match the field length specified with the LENGTH operand in the DFHMDF macro.
Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1076E Illegal character found at position posn of PICIN/PICOUT picture clause picture

The character at position posn in the PICIN / PICOUT operand is not a valid picture character for the language specified with the LANG operand in the DFHMSD macro.

Resolution:

Change the illegal picture character specified in the PICIN / PICOUT operand to one that is valid for the specified language.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1077E PICIN/PICOUT picture clause is too long (picture)

COBOL has a limit of 30 characters in a picture clause. The picture you have specified in the PICIN or PICOUT field exceeds this limit.

Resolution:

Specify a picture that doesn't exceed the 30-character limit.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1078W Unable to locate picture clause validation routines, unable to validate picture picture specified in PICIN/PICOUT

Enterprise Developer has been unable to find the picture clause validation routines. These routines are installed as part of the Enterprise Developer installation procedure and may have been deleted, moved or corrupted.

Resolution:

You should be able to fix this problem by reinstalling Enterprise Developer.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1079W PICIN/PICOUT is illegal for languages other than COBOL and PL/I

The PICIN and PICOUT operands are only valid for mapsets created for COBOL and PL/I programs. Enterprise Developer disregards PICIN and PICOUT operands for languages other than COBOL and PL/I.

Resolution:

If this mapset is intended for use with a COBOL or PL/I program, correctly set the language on the Mapset Properties dialog box.

If this mapset is not intended for use with a COBOL or PL/I program, delete the PICIN or PICOUT picture definition on the Other page of the Field Properties dialog box.

Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1080I Enabling SDF features to convert BMS/GT format source

This message is displayed when you open a map created with GT Software's BMS/GT program. These maps make use of SDF features so Enterprise Developer enables SDF support.
Parent topic: BMSCH1061I - BMSCH1080I


BMSCH1081S - BMSCH1104I

Lists the BMS Painter compile messages from BMSCH1081S through BMSCH1104I.
  • BMSCH1081S LENGTH operand missing for labeled DFHMDF macro
    The LENGTH operand describes the length of the field (1 – 256 bytes) and is required for all labeled DFHMDF macros (unless you specify a picture with PICIN or PICOUT).
  • BMSCH1082E PICIN/PICOUT picture clause invalid with specified MODE
    A PICIN picture has been specified for a field in a MODE=OUT mapset or a PICOUT picture has been specified for a field in a MODE=IN mapset.
  • BMSCH1083W Truncating initial data to match field length
    The initial data specified is too large to fit the field length, and has been truncated.
  • BMSCH1084W Continuation statement may be in error
    A line in the macro being processed ends in a comma but there is no continuation statement.
  • BMSCH1085W Detected old format BMS source with no DFHMSD: upgrading during import
  • BMSCH1065E Invalid length specified for field with INITIAL data
  • BMSCH1087W -INC not supported
  • BMSCH1088E Invalid SDF format for BMS GRPNAME field label %1!s!
  • BMSCH1089I Using MFASM to preprocess BMS source
  • BMSCH1090W Unable to invoke MFASM to preprocess BMS source
  • BMSCH1091I Expanded BMS source file : %1!s!
  • BMSCH1092E MFASM preprocessor not supported in painter, command line function only
  • BMSCH1093W Duplicate field label %1!s! renamed to %2!s!
  • BMSCH1094W IC requested for a protected field
  • BMSCH1095E Begin-to-continue columns not blank - %1!s!
  • BMSCH1096S No labelled DFHMDI macro was found
  • BMSCH1097I Using precompiler %1 to process BMS source
  • BMSCH1098W Unable to invoke %1 to precompile BMS source
  • BMSCH1099W Null string found processing operand-name operand of macro-name macro, option ignored
  • BMSCH1100S COPY file filename not found
    The copybook specified was not found.
  • BMSCH1101S COPY file expansion requires directive /PREPASM
    The /PREPASM directive was not specified when compiling with COPY file expansion.
  • BMSCH1103S Error found preprocessing BMS source for COPY file expansion
  • BMSCH1104I COPY file <filename> ignored
Parent topic: BMS Painter Compile Messages


BMSCH1081S LENGTH operand missing for labeled DFHMDF macro

The LENGTH operand describes the length of the field (1 – 256 bytes) and is required for all labeled DFHMDF macros (unless you specify a picture with PICIN or PICOUT).

Resolution:

Correctly set Length on the General page of the Field Properties dialog box to the length of the field.

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1082E PICIN/PICOUT picture clause invalid with specified MODE

A PICIN picture has been specified for a field in a MODE=OUT mapset or a PICOUT picture has been specified for a field in a MODE=IN mapset.

Resolution:

If MODE=IN (and this is correct), move the offending PICOUT picture clause to PICIN (or delete it).

If MODE=OUT (and this is correct), move the offending PICIN picture clause to PICOUT (or delete it).

If the MODE is set incorrectly, change the Mode setting on the General page of the Mapset Properties dialog box.

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1083W Truncating initial data to match field length

The initial data specified is too large to fit the field length, and has been truncated.

Resolution:

Correctly set the field length large enough to accommodate the initial data.

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1084W Continuation statement may be in error

A line in the macro being processed ends in a comma but there is no continuation statement.

Resolution:

Correct the source.

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1085W Detected old format BMS source with no DFHMSD: upgrading during import

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1065E Invalid length specified for field with INITIAL data

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1087W -INC not supported

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1088E Invalid SDF format for BMS GRPNAME field label %1!s!

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1089I Using MFASM to preprocess BMS source

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1090W Unable to invoke MFASM to preprocess BMS source

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1091I Expanded BMS source file : %1!s!

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1092E MFASM preprocessor not supported in painter, command line function only

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1093W Duplicate field label %1!s! renamed to %2!s!

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1094W IC requested for a protected field

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1095E Begin-to-continue columns not blank - %1!s!

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1096S No labelled DFHMDI macro was found

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1097I Using precompiler %1 to process BMS source

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1098W Unable to invoke %1 to precompile BMS source

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1099W Null string found processing operand-name operand of macro-name macro, option ignored

The named operand in the named macro does not have the expected associated value. The option has been ignored.

Resolution:

Correct the source.

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1100S COPY file filename not found

The copybook specified was not found.

Resolution:

Specify the correct path and/or filename of the copybook; then recompile.

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1101S COPY file expansion requires directive /PREPASM

The /PREPASM directive was not specified when compiling with COPY file expansion.

Resolution:

Recompile the source using the /PREPASM directive.

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1103S Error found preprocessing BMS source for COPY file expansion

Parent topic: BMSCH1081S - BMSCH1104I


BMSCH1104I COPY file <filename> ignored

Parent topic: BMSCH1081S - BMSCH1104I


BMS Painter Generate Messages

  • BMSCM1001I Saving BMS file filename
  • BMSCM1002I Generating type DSECT : filename (1)
  • BMSCM1003I Generating CSECT filename
  • BMSCM1012W Generation of C DSECT not currently supported
  • BMSCM1013W DFHMSD TYPE=name does not match requested SYSPARM (sysparm)
    The DFHMSD macro contains a TYPE operand that does not match the requested SYSPARM options in the build settings. For example, TYPE=DSECT implies that only a copybook should be generated from this BMS source file. To control the objects created during compilation through the build settings, specify TYPE=&&SYSPARM in the DFHMSD macro.
  • BMSCM1014W No SYSPARM specified, defaulting to MAP and DSECT
    No SYSPARM settings were passed to the BMS compilation process. Both TYPE=MAP and TYPE=DSECT are assumed.
  • BMSCM1015W No SYSPARM specified. Specify type of map to be generated in build settings
    No SYSPARM settings were passed to the BMS compilation process. An illegal command line must have been specified.
  • BMSCM1017W DFHMSD TYPE=MAP does not match specified SYSPARM, forcing DSECT generation as SDF features are enabled
    The TYPE operand of the DFHMSD macro indicates that a copybook should not be generated as part of the compilation process. As SDF features are enabled, the value of the TYPE operand is ignored.
  • BMSCM1018E Error saving filename, could not open file for output
  • BMSCM1019E A file error occurred whilst saving filename
  • BMSCM1020E An error occured re-opening filename following the save request, read only access assumed
  • BMSCM1021E Error opening output file for language DSECT : filename (1)
    An error occurred while trying to create the DSECT output file. This is usually due to insufficient free disk space or file access permissions preventing you from writing the file.
  • BMSCM1022W Assuming TIOAPFX=YES (required for command-level applications)
    TIOAPFX=YES should always be specified for command-level applications. If the program is a command-level application and TIOAPFX=YES has not been specified in the DFHMSD macro, Mainframe Express will display this warning and assume TIOAPFX=YES.
  • BMSCM1030I
  • BMSCM1031E Unable to establish the COM library for adding Maps to Net Express.
  • BMSCM1032E Unable to create an Inventory class object for adding Maps to Net Express.
  • BMSCM1033E Unable to load %1!s! for adding Maps to Net Express.
  • BMSCM1034E An invalid parameter was passed.
  • BMSCM1035E A memory allocation failed. Returning to application.
  • BMSCM1036E An invalid folder (%1!s!) was selected. Returning to application.
  • BMSCM1037S License protection error: %1!s!
  • BMSCM1102W MAP name exceeds 7 characters, name truncated to <mapname>
Parent topic: Micro Focus BMS Painter


BMSCM1001I Saving BMS file filename

The changes are being saved to the specified BMS file.

Parent topic: BMS Painter Generate Messages


BMSCM1002I Generating type DSECT : filename (1)

The generation produces copybook files (.cpy, .mac and .inc).

Parent topic: BMS Painter Generate Messages


BMSCM1003I Generating CSECT filename

The generation produces the load module mapset (.mod) files.

Parent topic: BMS Painter Generate Messages


BMSCM1012W Generation of C DSECT not currently supported

Generation of a copyfile for the C programming language is not supported.

Parent topic: BMS Painter Generate Messages


BMSCM1013W DFHMSD TYPE=name does not match requested SYSPARM (sysparm)

The DFHMSD macro contains a TYPE operand that does not match the requested SYSPARM options in the build settings. For example, TYPE=DSECT implies that only a copybook should be generated from this BMS source file. To control the objects created during compilation through the build settings, specify TYPE=&&SYSPARM in the DFHMSD macro.

Resolution:

Correct the source or change the build settings.

Parent topic: BMS Painter Generate Messages


BMSCM1014W No SYSPARM specified, defaulting to MAP and DSECT

No SYSPARM settings were passed to the BMS compilation process. Both TYPE=MAP and TYPE=DSECT are assumed.
Parent topic: BMS Painter Generate Messages


BMSCM1015W No SYSPARM specified. Specify type of map to be generated in build settings

No SYSPARM settings were passed to the BMS compilation process. An illegal command line must have been specified.

Resolution:

Correct the build settings.

Parent topic: BMS Painter Generate Messages


BMSCM1017W DFHMSD TYPE=MAP does not match specified SYSPARM, forcing DSECT generation as SDF features are enabled

The TYPE operand of the DFHMSD macro indicates that a copybook should not be generated as part of the compilation process. As SDF features are enabled, the value of the TYPE operand is ignored.
Parent topic: BMS Painter Generate Messages


BMSCM1018E Error saving filename, could not open file for output

Resolution:

Try saving the file with a different file name or in a different directory.

Parent topic: BMS Painter Generate Messages


BMSCM1019E A file error occurred whilst saving filename

Resolution:

Try saving the file with a different file name or in a different directory.

Parent topic: BMS Painter Generate Messages


BMSCM1020E An error occured re-opening filename following the save request, read only access assumed

Resolution:

Try saving the file with a different file name or in a different directory.

Parent topic: BMS Painter Generate Messages


BMSCM1021E Error opening output file for language DSECT : filename (1)

An error occurred while trying to create the DSECT output file. This is usually due to insufficient free disk space or file access permissions preventing you from writing the file.

Resolution:

If there is enough free disk space, check your write access permission on both the file (if it already exists) and the directory where the file is being created.

Parent topic: BMS Painter Generate Messages


BMSCM1022W Assuming TIOAPFX=YES (required for command-level applications)

TIOAPFX=YES should always be specified for command-level applications. If the program is a command-level application and TIOAPFX=YES has not been specified in the DFHMSD macro, Mainframe Express will display this warning and assume TIOAPFX=YES.

Resolution:

Specify TIOAPFX=YES in the DFHMSD macro.

Parent topic: BMS Painter Generate Messages


BMSCM1030I

Parent topic: BMS Painter Generate Messages


BMSCM1031E Unable to establish the COM library for adding Maps to Net Express.

Parent topic: BMS Painter Generate Messages


BMSCM1032E Unable to create an Inventory class object for adding Maps to Net Express.

Parent topic: BMS Painter Generate Messages


BMSCM1033E Unable to load %1!s! for adding Maps to Net Express.

Parent topic: BMS Painter Generate Messages


BMSCM1034E An invalid parameter was passed.

Parent topic: BMS Painter Generate Messages


BMSCM1035E A memory allocation failed. Returning to application.

Parent topic: BMS Painter Generate Messages


BMSCM1036E An invalid folder (%1!s!) was selected. Returning to application.

Parent topic: BMS Painter Generate Messages


BMSCM1037S License protection error: %1!s!

Parent topic: BMS Painter Generate Messages


BMSCM1102W MAP name exceeds 7 characters, name truncated to <mapname>

Parent topic: BMS Painter Generate Messages


Open PL/I Reference

  • Open PL/I Error Messages
  • Open PL/I Language Reference Manual
Parent topic: Mainframe Reference


Open PL/I Error Messages

  • MFCWD - PL/I Debugger Messages
  • MFLDP - PL/I Linker Messages
  • MFPLI - PL/I Compiler Messages
  • MFPLX - PL/I Compilation System Messages
  • MFPPP - PL/I Macro Preprocessor Messages
  • MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages
  • MPLIR - PL/I Runtime Messages
Parent topic: Open PL/I Reference
Related information
PL/I


MFCWD - PL/I Debugger Messages

  • MFCWD02000 - MFCWD02019
  • MFCWD02020 - MFCWD02039
  • MFCWD02060 - MFCWD02079
  • MFCWD02080 - MFCWD02099
  • MFCWD06000 - MFCWD06019
  • MFCWD06020 - MFCWD06039
  • MFCWD06040 - MFCWD06059
  • MFCWD06060 - MFCWD06079
  • MFCWD06080 - MFCWD06099
  • MFCWD06100 - MFCWD06119
  • MFCWD06120 - MFCWD06139
  • MFCWD06140 - MFCWD06159
  • MFCWD06160 - MFCWD06179
  • MFCWD06180 - MFCWD06199
  • MFCWD06200 - MFCWD06219
  • MFCWD06220 - MFCWD06239
  • MFCWD06240 - MFCWD06259
  • MFCWD06260 - MFCWD06279
  • MFCWD06280 - MFCWD06299
  • MFCWD06300 - MFCWD06319
  • MFCWD06320 - MFCWD06339
  • MFCWD06340 - MFCWD06359
  • MFCWD06360 - MFCWD06379
  • MFCWD06380 - MFCWD06399
  • MFCWD06400 - MFCWD06419
  • MFCWD06420 - MFCWD06439
  • MFCWD06440 - MFCWD06459
  • MFCWD06460 - MFCWD06479
  • MFCWD06480 - MFCWD06499
  • MFCWD06500 - MFCWD06519
  • MFCWD06520 - MFCWD06539
  • MFCWD06600 - MFCWD06619
  • MFCWD06620 - MFCWD06639
  • MFCWD06640 - MFCWD06659
  • MFCWD06660 - MFCWD06679
  • MFCWD06680 - MFCWD06699
  • MFCWD06700 - MFCWD06719
Parent topic: Open PL/I Error Messages


MFCWD02000 - MFCWD02019

  • MFCWD02000U Internal consistency error: invalid symbol table access. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: invalid symbol table access.
  • MFCWD02001U Symbol table overflow. The total number of internal symbol table pages exceeds the implementation's limit. Reduce the number and size of names, constants, extent-expressions, and argument or returns descriptors.
    Symbol table overflow.
  • MFCWD02002U Symbol table overflow. Please contact Micro Focus Support Line.
    Symbol table overflow.
  • MFCWD02003U Too many errors. The total number of diagnosed errors exceeds the %1$s limit. processing aborted.
    The number of errors of the severity specified in the -maxmsg option has been exceeded.
  • MFCWD02004U Internal consistency error: too many open files. The number of concurrently open files needed to continue processing exceeds the implementation's limit. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: too many open files.
  • MFCWD02005U Internal consistency error: internal value table overflow. Reduce the complexity of large expressions. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: internal value table overflow.
  • MFCWD02006E Internal consistency error: attempt to free an already freed internal value. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: attempt to free an already freed internal value.
  • MFCWD02007U Internal consistency error: out of memory. Not enough heap storage is available from the system to continue processing. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: out of memory.
  • MFCWD02008U Internal consistency: unable to copy internal list. Attempt to copy an internal list failed when the new list could not be extended to the required size. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency: unable to copy internal list.
  • MFCWD02009U Internal consistency error: invalid type for target conversion. An internal conversion failed when called with an unknown data type. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: invalid type for target conversion.
  • MFCWD02010U Internal consistency error: invalid size for target conversion. An internal conversion to target representation failed when called with an invalid size value.
  • MFCWD02011U Internal consistency error: invalid size for host conversion. An internal conversion to host representation failed when called with an invalid size value.
  • MFCWD02012U Internal IL overflow. Unable to continue processing. Try breaking the compilation unit apart into smaller modules if possible, or reducing the number of executable statements. If this message persists, contact Micro Focus Support Line.
    Internal input list overflow.
  • MFCWD02013U Unable to open file "%1$s". Include file nesting limit exceeded. Reduce the nesting level of included source files.
    Unable to open file "file-name".
  • MFCWD02014U Internal heap storage exhausted. Unable to continue processing. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal heap storage exhausted.
  • MFCWD02015U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFCWD02016U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFCWD02017W Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFCWD02018U Internal consistency error. Unable to open existing node list file. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFCWD02019W Internal consistency error. Unable to create temp file for new node list. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD02000U Internal consistency error: invalid symbol table access. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: invalid symbol table access.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
OBJOUT.PL1, STBV.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02001U Symbol table overflow. The total number of internal symbol table pages exceeds the implementation's limit. Reduce the number and size of names, constants, extent-expressions, and argument or returns descriptors.

Symbol table overflow.

The total number of internal symbol table pages exceeds the implementation's limit.

Resolution:
Reduce the number and size of names, constants, extent-expressions, and argument or returns descriptors.
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02002U Symbol table overflow. Please contact Micro Focus Support Line.

Symbol table overflow.
Resolution:
Please contact Micro Focus Support Line.
Module:
STBV.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02003U Too many errors. The total number of diagnosed errors exceeds the %1$s limit. processing aborted.

The number of errors of the severity specified in the -maxmsg option has been exceeded.
Resolution:
Either amend the source to reduce the number of errors of this severity diagnosed or increase the number of messages specified in the -maxmsg option.
Module:
XERROR.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02004U Internal consistency error: too many open files. The number of concurrently open files needed to continue processing exceeds the implementation's limit. If this message persists, contact Micro Focus Support Line.

Internal consistency error: too many open files.

The number of concurrently open files needed to continue processing exceeds the implementation's limit.

Resolution:
If this message persists, contact Micro Focus Support Line.
Module:
IO_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02005U Internal consistency error: internal value table overflow. Reduce the complexity of large expressions. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: internal value table overflow.

Possible compiler error.

Resolution:
Reduce the complexity of large expressions. Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
VAL_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02006E Internal consistency error: attempt to free an already freed internal value. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: attempt to free an already freed internal value.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
VAL_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02007U Internal consistency error: out of memory. Not enough heap storage is available from the system to continue processing. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: out of memory.

Not enough heap storage is available from the system to continue processing.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
MEM_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02008U Internal consistency: unable to copy internal list. Attempt to copy an internal list failed when the new list could not be extended to the required size. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency: unable to copy internal list.

Attempt to copy an internal list failed when the new list could not be extended to the required size.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02009U Internal consistency error: invalid type for target conversion. An internal conversion failed when called with an unknown data type. If this message persists, contact Micro Focus Support Line.

Internal consistency error: invalid type for target conversion.

An internal conversion failed when called with an unknown data type.

Resolution:
If this message persists, contact Micro Focus Support Line.
Module:
CVT_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02010U Internal consistency error: invalid size for target conversion. An internal conversion to target representation failed when called with an invalid size value.

Module:
CVT_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02011U Internal consistency error: invalid size for host conversion. An internal conversion to host representation failed when called with an invalid size value.

Module:
CVT_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02012U Internal IL overflow. Unable to continue processing. Try breaking the compilation unit apart into smaller modules if possible, or reducing the number of executable statements. If this message persists, contact Micro Focus Support Line.

Internal input list overflow.

Unable to continue processing.

Resolution:
Try breaking the compilation unit apart into smaller modules if possible, or reducing the number of executable statements. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02013U Unable to open file "%1$s". Include file nesting limit exceeded. Reduce the nesting level of included source files.

Unable to open file "file-name".

Include file nesting limit exceeded.

Resolution:
Reduce the nesting level of included source files.
Module:
SRC_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02014U Internal heap storage exhausted. Unable to continue processing. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal heap storage exhausted.

Unable to continue processing. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
HEAPD.PL1, HEAPM.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02015U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
MAIN.PL1, MFPLIZ.PL1, OBJ_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02016U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
OBJ_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02017W Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
OBJ_U.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02018U Internal consistency error. Unable to open existing node list file. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Unable to open existing node list file. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02019W Internal consistency error. Unable to create temp file for new node list. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Unable to create temp file for new node list. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFCWD02000 - MFCWD02019


MFCWD02020 - MFCWD02039

  • MFCWD02020U Internal consistency error. List node size exceeds limit. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFCWD02021U Internal consistency error. Node list file is an unrecognized format. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFCWD02022U Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE. Reduce the size or complexity of the PROCEDURE that contains this statement.
    Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD02020U Internal consistency error. List node size exceeds limit. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

List node size exceeds limit. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFCWD02020 - MFCWD02039


MFCWD02021U Internal consistency error. Node list file is an unrecognized format. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Node list file is an unrecognized format. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFCWD02020 - MFCWD02039


MFCWD02022U Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE. Reduce the size or complexity of the PROCEDURE that contains this statement.

Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE.
Resolution:
Reduce the size or complexity of the PROCEDURE that contains this statement.
Module:
XOPERU.PL1
Parent topic: MFCWD02020 - MFCWD02039


MFCWD02060 - MFCWD02079

  • MFCWD02070S Unable to open file: %1$s
  • MFCWD02071S Compilation interrupted ...
  • MFCWD02072S I/O error on file
  • MFCWD02073S Unable to open file
  • MFCWD02074S Read error: Line too long
  • MFCWD02075S System error
  • MFCWD02076S Compilation aborted.
  • MFCWD02077S Compiling file
  • MFCWD02078S compiled successfully.
  • MFCWD02079S The -maxmsg option requires I|W|E|S[,n]
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD02070S Unable to open file: %1$s

Module:
ERR_U.PL1, STARP.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02071S Compilation interrupted ...

Module:
ERR_U.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02072S I/O error on file

Module:
ERR_U.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02073S Unable to open file

Module:
ERR_U.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02074S Read error: Line too long

Module:
ERR_U.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02075S System error

Module:
ERR_U.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02076S Compilation aborted.

Module:
ERR_U.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02077S Compiling file

Parent topic: MFCWD02060 - MFCWD02079


MFCWD02078S compiled successfully.

Parent topic: MFCWD02060 - MFCWD02079


MFCWD02079S The -maxmsg option requires I|W|E|S[,n]

Module:
XINIUT.PL1
Parent topic: MFCWD02060 - MFCWD02079


MFCWD02080 - MFCWD02099

  • MFCWD02080W The -%1$s option is deprecated and may be removed in a future product release or update.
  • MFCWD02081S Only -rc 0,0 OR -rc 4,0 OR -rc 8,0 is allowed; -rc 4,0 is the default.
  • MFCWD02082I No object file produced.
  • MFCWD02083I Object file produced.
  • MFCWD02084U Unrecoverable error encountered.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD02080W The -%1$s option is deprecated and may be removed in a future product release or update.

Module:
XINIFE.PL1
Parent topic: MFCWD02080 - MFCWD02099


MFCWD02081S Only -rc 0,0 OR -rc 4,0 OR -rc 8,0 is allowed; -rc 4,0 is the default.

Module:
XINIUT.PL1
Parent topic: MFCWD02080 - MFCWD02099


MFCWD02082I No object file produced.

Parent topic: MFCWD02080 - MFCWD02099


MFCWD02083I Object file produced.

Parent topic: MFCWD02080 - MFCWD02099


MFCWD02084U Unrecoverable error encountered.

Module:
XINIT.PL1
Parent topic: MFCWD02080 - MFCWD02099


MFCWD06000 - MFCWD06019

  • MFCWD06001E Syntax error
  • MFCWD06002E Invalid command
  • MFCWD06003E End of line or ; expected
  • MFCWD06005E Missing close quote
  • MFCWD06006E Missing right bracket
  • MFCWD06008E Conflicting or duplicate keyword
  • MFCWD06009E Attempt to define too many macros
  • MFCWD06010E Undefined macro
  • MFCWD06011E Macro name or action too long
  • MFCWD06012E Macros nested too deep
  • MFCWD06014E = expected.
  • MFCWD06017E Must specify pid no and filename to attach to.
  • MFCWD06018E Log file must be specified.
  • MFCWD06019E Integer expected.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06001E Syntax error

Module:
DCNVRT.PL1, DGMR.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06002E Invalid command

Parent topic: MFCWD06000 - MFCWD06019


MFCWD06003E End of line or ; expected

Parent topic: MFCWD06000 - MFCWD06019


MFCWD06005E Missing close quote

Module:
DGMR.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06006E Missing right bracket

Module:
DGMR.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06008E Conflicting or duplicate keyword

Module:
DDCMD.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06009E Attempt to define too many macros

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06010E Undefined macro

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06011E Macro name or action too long

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06012E Macros nested too deep

Module:
DGMR.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06014E = expected.

Parent topic: MFCWD06000 - MFCWD06019


MFCWD06017E Must specify pid no and filename to attach to.

Module:
EXCMD.PL1
Parent topic: MFCWD06000 - MFCWD06019


MFCWD06018E Log file must be specified.

Parent topic: MFCWD06000 - MFCWD06019


MFCWD06019E Integer expected.

Parent topic: MFCWD06000 - MFCWD06019


MFCWD06020 - MFCWD06039

  • MFCWD06020E Statement ID required.
  • MFCWD06021E Statement ID or /ALL required.
  • MFCWD06022E Macro name expected.
  • MFCWD06023E File name must be specified.
  • MFCWD06024E Action List required [ ... ]
  • MFCWD06025E Signal name or integer expected
  • MFCWD06026E Machine address must be an integer or hex 0x... value.
  • MFCWD06027E Macro name or /ALL expected.
  • MFCWD06028E %%ENTRY or %%EXIT expected.
  • MFCWD06029E POKE data value must be an integer or hex 0x... value.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06020E Statement ID required.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06021E Statement ID or /ALL required.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06022E Macro name expected.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06023E File name must be specified.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06024E Action List required [ ... ]

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06025E Signal name or integer expected

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06026E Machine address must be an integer or hex 0x... value.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06027E Macro name or /ALL expected.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06028E %%ENTRY or %%EXIT expected.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06029E POKE data value must be an integer or hex 0x... value.

Parent topic: MFCWD06020 - MFCWD06039


MFCWD06040 - MFCWD06059

  • MFCWD06051E Zero divide
  • MFCWD06052E Arithmetic underflow.
  • MFCWD06053E Arithmetic overflow
  • MFCWD06054E Evaluation error
  • MFCWD06055E Arithmetic error.
  • MFCWD06056E Invalid character in BIT constant.
  • MFCWD06057E Invalid quoted constant.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06051E Zero divide

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06040 - MFCWD06059


MFCWD06052E Arithmetic underflow.

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06040 - MFCWD06059


MFCWD06053E Arithmetic overflow

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06040 - MFCWD06059


MFCWD06054E Evaluation error

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06040 - MFCWD06059


MFCWD06055E Arithmetic error.

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06040 - MFCWD06059


MFCWD06056E Invalid character in BIT constant.

Module:
DGMR.PL1
Parent topic: MFCWD06040 - MFCWD06059


MFCWD06057E Invalid quoted constant.

Module:
DGMR.PL1
Parent topic: MFCWD06040 - MFCWD06059


MFCWD06060 - MFCWD06079

  • MFCWD06061E Missing digits in exponent.
  • MFCWD06063E Too few arguments to built-in function function-name (argument-count minimum).
  • MFCWD06064E Too many arguments to built-in function function-name (argument-count maximum).
  • MFCWD06066E Argument must be arithmetic or string.
  • MFCWD06067E Argument must be a variable reference.
  • MFCWD06068E Missing subscripts in array reference.
  • MFCWD06069E No ranges allowed in ADDR.
  • MFCWD06071E Dimension dimension-number invalid - must be 1 to high-bound.
  • MFCWD06072E Invalid data type for conversion.
  • MFCWD06075E Built-in function TRIM needs one or three arguments.
  • MFCWD06076E CHARACTER VARYING string not on proper boundary.
  • MFCWD06077I CHARACTER VARYING string length > declared length or < 0
  • MFCWD06078E Arguments to SUBSTR out of range.
  • MFCWD06079E Too many dimensions.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06061E Missing digits in exponent.

Module:
DGMR.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06063E Too few arguments to built-in function function-name (argument-count minimum).

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06064E Too many arguments to built-in function function-name (argument-count maximum).

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06066E Argument must be arithmetic or string.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06067E Argument must be a variable reference.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06068E Missing subscripts in array reference.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06069E No ranges allowed in ADDR.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06071E Dimension dimension-number invalid - must be 1 to high-bound.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06072E Invalid data type for conversion.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06075E Built-in function TRIM needs one or three arguments.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06076E CHARACTER VARYING string not on proper boundary.

Module:
DBIF.PL1, DEVAL.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06077I CHARACTER VARYING string length > declared length or < 0

Module:
DBIF.PL1, DEVAL.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06078E Arguments to SUBSTR out of range.

Module:
DBIF.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06079E Too many dimensions.

Module:
DARLVL.PL1
Parent topic: MFCWD06060 - MFCWD06079


MFCWD06080 - MFCWD06099

  • MFCWD06081E Error setting breakpoint.
  • MFCWD06082E Error clearing breakpoint.
  • MFCWD06083E Invalid conversion
  • MFCWD06086E Unknown %%REPLACE value.
  • MFCWD06087E Undefined variable or built-in function
  • MFCWD06088E Too many arguments and/or subscripts.
  • MFCWD06089E Cannot find local base address.
  • MFCWD06091E [STB] bad storage class.
  • MFCWD06092E Non-BASED variable does not take a locator.
  • MFCWD06093E PROCEDURE inactive when looking for AUTOMATIC variable.
  • MFCWD06094E BASED variable requires locator.
  • MFCWD06095E Locator must be of type POINTER.
  • MFCWD06096E Constant name not LABEL, ENTRY, or EXTERNAL ENTRY.
  • MFCWD06097E Defined variable requires locator.
  • MFCWD06098E Compiler error - level 1 member found.
  • MFCWD06099E PROCEDURE inactive when looking for parameter
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06081E Error setting breakpoint.

Module:
RESUME.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06082E Error clearing breakpoint.

Module:
DBREAK.PL1, RESUME.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06083E Invalid conversion

Module:
DCNVRT.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06086E Unknown %%REPLACE value.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06087E Undefined variable or built-in function

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06088E Too many arguments and/or subscripts.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06089E Cannot find local base address.

Module:
DEXPNV.PL1, DFINDV.PL1, DSTMNT.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06091E [STB] bad storage class.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06092E Non-BASED variable does not take a locator.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06093E PROCEDURE inactive when looking for AUTOMATIC variable.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06094E BASED variable requires locator.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06095E Locator must be of type POINTER.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06096E Constant name not LABEL, ENTRY, or EXTERNAL ENTRY.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06097E Defined variable requires locator.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06098E Compiler error - level 1 member found.

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06099E PROCEDURE inactive when looking for parameter

Module:
DFINDV.PL1
Parent topic: MFCWD06080 - MFCWD06099


MFCWD06100 - MFCWD06119

  • MFCWD06100E Value parameter not found.
  • MFCWD06101E Parameter POINTER not found.
  • MFCWD06102E EXTERNAL variable not found in map.
  • MFCWD06103E Subscript out of range
  • MFCWD06104E Cannot perform a CALL with no execution point defined.
  • MFCWD06105E Arguments given to non-ENTRY.
  • MFCWD06106E Not enough arguments for PROCEDURE call.
  • MFCWD06107E Array cannot be partially subscripted.
  • MFCWD06108E Subscript range not valid.
  • MFCWD06109E Array or STRUCTURE cannot be passed by value.
  • MFCWD06110E Cannot allocate byte-count bytes for CALL argument argument-number.
  • MFCWD06112E Too many arguments for PROCEDURE call.
  • MFCWD06113E PROCEDURE does not return a value.
  • MFCWD06114E Variable reference required.
  • MFCWD06115E Specified activation does not exist.
  • MFCWD06118E Unsupported value node opcode opcode-value.
  • MFCWD06119E Unknown PROCEDURE name.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06100E Value parameter not found.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06101E Parameter POINTER not found.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06102E EXTERNAL variable not found in map.

Module:
DFINDV.PL1, MACT.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06103E Subscript out of range

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06104E Cannot perform a CALL with no execution point defined.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06105E Arguments given to non-ENTRY.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06106E Not enough arguments for PROCEDURE call.

Module:
DEXPNV.PL1, DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06107E Array cannot be partially subscripted.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06108E Subscript range not valid.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06109E Array or STRUCTURE cannot be passed by value.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06110E Cannot allocate byte-count bytes for CALL argument argument-number.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06112E Too many arguments for PROCEDURE call.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06113E PROCEDURE does not return a value.

Module:
DFINDV.PL1, EXCMD.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06114E Variable reference required.

Module:
DFINDV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06115E Specified activation does not exist.

Module:
DACT.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06118E Unsupported value node opcode opcode-value.

Module:
DEXPNV.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06119E Unknown PROCEDURE name.

Module:
PCLUTL.PL1
Parent topic: MFCWD06100 - MFCWD06119


MFCWD06120 - MFCWD06139

  • MFCWD06120E [STB] Cannot find PROCEDURE symbol node.
  • MFCWD06121E Invalid type to fetch.
  • MFCWD06122E Not enough subscripts.
  • MFCWD06123E Subscript ranges valid only at top level.
  • MFCWD06124E Error reading memory.
  • MFCWD06125E Variable not found
  • MFCWD06127E command-name interrupted.
  • MFCWD06128E No environment
  • MFCWD06129E Environment is inactive
  • MFCWD06130E Debug symbol not implemented
  • MFCWD06131E DISASSEMBLE failed.
  • MFCWD06132E FIND argument is null
  • MFCWD06133E GOTO target not active.
  • MFCWD06134E Cannot GOTO ENTRY point
  • MFCWD06135E Cannot GOTO exit point
  • MFCWD06136E LRETURN valid only at PROCEDURE exit
  • MFCWD06137E Left side of LET must be a variable reference.
  • MFCWD06139E Cannot write user memory.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06120E [STB] Cannot find PROCEDURE symbol node.

Module:
PCLUTL.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06121E Invalid type to fetch.

Module:
DFTREF.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06122E Not enough subscripts.

Module:
DFTREF.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06123E Subscript ranges valid only at top level.

Module:
DFTREF.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06124E Error reading memory.

Module:
DEVAL.PL1, DFTREF.PL1, ISTEP.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06125E Variable not found

Module:
DPRTYP.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06127E command-name interrupted.

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06128E No environment

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06129E Environment is inactive

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06130E Debug symbol not implemented

Module:
DDCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06131E DISASSEMBLE failed.

Module:
DDCMD.PL1, ISTEP.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06132E FIND argument is null

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06133E GOTO target not active.

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06134E Cannot GOTO ENTRY point

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06135E Cannot GOTO exit point

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06136E LRETURN valid only at PROCEDURE exit

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06137E Left side of LET must be a variable reference.

Module:
DDCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06139E Cannot write user memory.

Module:
DDCMD.PL1
Parent topic: MFCWD06120 - MFCWD06139


MFCWD06140 - MFCWD06159

  • MFCWD06140E PEEK failed.
  • MFCWD06141E Command not implemented.
  • MFCWD06142E Statement name nesting too deep.
  • MFCWD06143E No execution environment
  • MFCWD06146E Cannot handle value with length length-value.
    Length must be greater than or equal to zero and less than or equal to 32767.
  • MFCWD06147E Environment stack overflow.
  • MFCWD06148E Missing operand.
  • MFCWD06149E No expression to evaluate.
  • MFCWD06153E Operands must both be of COMPLEX type.
  • MFCWD06154E Operand must be arithmetic.
  • MFCWD06156E Operand must be BIT string.
  • MFCWD06157E Incompatible types in comparison
  • MFCWD06158E Both types must be CHARACTER
  • MFCWD06159E Illegal operator for CHARACTER arguments
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06140E PEEK failed.

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06141E Command not implemented.

Module:
DDCMD.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06142E Statement name nesting too deep.

Module:
DDCMD.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06143E No execution environment

Module:
DDCMD.PL1, DSTACK.PL1, SETENV.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06146E Cannot handle value with length length-value.

Length must be greater than or equal to zero and less than or equal to 32767.
Module:
VAREA.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06147E Environment stack overflow.

Module:
DEVAL.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06148E Missing operand.

Module:
DEVAL.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06149E No expression to evaluate.

Module:
DEVAL.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06153E Operands must both be of COMPLEX type.

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06154E Operand must be arithmetic.

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06156E Operand must be BIT string.

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06157E Incompatible types in comparison

Module:
PERFORM_OP.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06158E Both types must be CHARACTER

Module:
SERROR.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06159E Illegal operator for CHARACTER arguments

Module:
SERROR.PL1
Parent topic: MFCWD06140 - MFCWD06159


MFCWD06160 - MFCWD06179

  • MFCWD06160E Unary + and - only on numeric types
  • MFCWD06161E Attempt to change type on expression
  • MFCWD06162E String expression required
  • MFCWD06163E Numeric expression required
  • MFCWD06164E in expression
  • MFCWD06165E No environment defined.
  • MFCWD06166E Symbol is not a label constant
  • MFCWD06167E Subscript required on label array.
  • MFCWD06170E [STB] Label not associated with any code.
  • MFCWD06171E Label array element not found.
  • MFCWD06172E Label not found
  • MFCWD06173E Labels numbers not valid in this environment.
  • MFCWD06174E Statement ID must be 0 to 32767.
  • MFCWD06176E No execution point defined.
  • MFCWD06177E Invalid GOTO format.
  • MFCWD06178E Cannot STEP OVER GOTO.
  • MFCWD06179E Invalid non-local GOTO format.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06160E Unary + and - only on numeric types

Module:
SERROR.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06161E Attempt to change type on expression

Module:
SERROR.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06162E String expression required

Module:
SERROR.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06163E Numeric expression required

Module:
SERROR.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06164E in expression

Module:
SERROR.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06165E No environment defined.

Module:
DSTMNT.PL1, EXCMD.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06166E Symbol is not a label constant

Module:
DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06167E Subscript required on label array.

Module:
DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06170E [STB] Label not associated with any code.

Module:
DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06171E Label array element not found.

Module:
DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06172E Label not found

Module:
DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06173E Labels numbers not valid in this environment.

Module:
DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06174E Statement ID must be 0 to 32767.

Module:
DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06176E No execution point defined.

Module:
DSTEP.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06177E Invalid GOTO format.

Module:
DSTEP.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06178E Cannot STEP OVER GOTO.

Module:
DSTEP.PL1, DSTMNT.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06179E Invalid non-local GOTO format.

Module:
DSTEP.PL1, NLGOTO.PL1
Parent topic: MFCWD06160 - MFCWD06179


MFCWD06180 - MFCWD06199

  • MFCWD06180E Cannot STEP OVER non-local GOTO.
  • MFCWD06182E Invalid CALL format.
  • MFCWD06183E [STB] Branch target not found.
  • MFCWD06184E Non-constant labels not yet supported.
  • MFCWD06185E [STB] STEP to other than label or ENTRY.
  • MFCWD06187E Specified (non-debug) activation does not exist.
  • MFCWD06188E Subscripts not valid on environment names.
  • MFCWD06189E Unknown EXTERNAL PROCEDURE name.
  • MFCWD06190E Undefined environment reference "environment-reference"
  • MFCWD06191E Ambiguous environment name.
  • MFCWD06192E Address not in known module.
  • MFCWD06193E No debugging information for insert-name.
  • MFCWD06194E [STB] Address not found among PROCEDURE statements.
  • MFCWD06197E Error reading user memory while setting up watchpoint.
  • MFCWD06198E Too many watchpoints.
  • MFCWD06199E Watchpoint name "insert-name" not valid.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06180E Cannot STEP OVER non-local GOTO.

Module:
DSTEP.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06182E Invalid CALL format.

Module:
DSTEP.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06183E [STB] Branch target not found.

Module:
DSTEP.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06184E Non-constant labels not yet supported.

Module:
DSTEP.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06185E [STB] STEP to other than label or ENTRY.

Module:
DSTEP.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06187E Specified (non-debug) activation does not exist.

Module:
NDACT.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06188E Subscripts not valid on environment names.

Module:
DENV.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06189E Unknown EXTERNAL PROCEDURE name.

Module:
DENV.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06190E Undefined environment reference "environment-reference"

Module:
DENV.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06191E Ambiguous environment name.

Module:
DENV.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06192E Address not in known module.

Module:
DENV.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06193E No debugging information for insert-name.

Module:
DDCMD.PL1, DENV.PL1, EXCMD.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06194E [STB] Address not found among PROCEDURE statements.

Module:
DENV.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06197E Error reading user memory while setting up watchpoint.

Module:
DWATCH.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06198E Too many watchpoints.

Module:
DWATCH.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06199E Watchpoint name "insert-name" not valid.

Module:
DWATCH.PL1
Parent topic: MFCWD06180 - MFCWD06199


MFCWD06200 - MFCWD06219

  • MFCWD06200E Watchpoint not found for insert-name.
  • MFCWD06203E Error reading user memory while handling watchpoint.
  • MFCWD06204E No activation for (non-debug) frame.
  • MFCWD06205E Cannot clear breakpoint
  • MFCWD06206E Cannot clear internal breakpoint
  • MFCWD06207E Cannot reset breakpoint
  • MFCWD06208E Cannot allocate space for CALL return value.
  • MFCWD06209E Cannot write breakpoint for CALL.
  • MFCWD06210E Cannot write argument # argument-number for CALL.
  • MFCWD06211E Cannot write return address for CALL.
  • MFCWD06212E CALL failed.
  • MFCWD06213E Cannot read CALL return value.
  • MFCWD06214E Cannot read return value address.
  • MFCWD06215E Cannot read return value.
  • MFCWD06216E Cannot write return value.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06200E Watchpoint not found for insert-name.

Module:
DWATCH.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06203E Error reading user memory while handling watchpoint.

Module:
DONBRK.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06204E No activation for (non-debug) frame.

Module:
NDACT.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06205E Cannot clear breakpoint

Module:
DBREAK.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06206E Cannot clear internal breakpoint

Module:
DBREAK.PL1, DRTS.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06207E Cannot reset breakpoint

Module:
DBREAK.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06208E Cannot allocate space for CALL return value.

Module:
DOCALL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06209E Cannot write breakpoint for CALL.

Module:
DOCALL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06210E Cannot write argument # argument-number for CALL.

Module:
DOCALL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06211E Cannot write return address for CALL.

Module:
DOCALL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06212E CALL failed.

Module:
DOCALL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06213E Cannot read CALL return value.

Module:
DOCALL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06214E Cannot read return value address.

Module:
GETRVL.PL1, SETRVL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06215E Cannot read return value.

Module:
GETRVL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06216E Cannot write return value.

Module:
SETRVL.PL1
Parent topic: MFCWD06200 - MFCWD06219


MFCWD06220 - MFCWD06239

  • MFCWD06221E Context requires an INTEGER value.
  • MFCWD06223E Environment stack underflow.
  • MFCWD06224E PEEK must used before PEEK /NEXT
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06221E Context requires an INTEGER value.

Module:
DDCMD.PL1, MACT.PL1, REG.PL1
Parent topic: MFCWD06220 - MFCWD06239


MFCWD06223E Environment stack underflow.

Module:
DEVAL.PL1
Parent topic: MFCWD06220 - MFCWD06239


MFCWD06224E PEEK must used before PEEK /NEXT

Module:
EXCMD.PL1
Parent topic: MFCWD06220 - MFCWD06239


MFCWD06240 - MFCWD06259

  • MFCWD06242E Cannot perform BASIC string assignment unless the program contain a string assignment; run-time "insert-name" needed.
  • MFCWD06243E Cannot perform BASIC string assignment
  • MFCWD06244E Unknown user run-time call (insert-name)
  • MFCWD06245E No activation for frame
  • MFCWD06246E Current frame not on stack
  • MFCWD06247E Cannot continue with tracing or watchpoints set
  • MFCWD06250E ISTEP not implemented
  • MFCWD06252E LPATH not implemented
  • MFCWD06253E PATH not implemented
  • MFCWD06254E Source file "file-name" not available
  • MFCWD06256E Command file nesting is too deep
  • MFCWD06257E Cannot open command file "file-name"
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06242E Cannot perform BASIC string assignment unless the program contain a string assignment; run-time "insert-name" needed.

Module:
CALLRT.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06243E Cannot perform BASIC string assignment

Module:
CALLRT.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06244E Unknown user run-time call (insert-name)

Module:
CALLRT.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06245E No activation for frame

Module:
DACT.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06246E Current frame not on stack

Module:
DACT.PL1, NDACT.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06247E Cannot continue with tracing or watchpoints set

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06250E ISTEP not implemented

Module:
DDCMD.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06252E LPATH not implemented

Module:
DDCMD.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06253E PATH not implemented

Module:
DDCMD.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06254E Source file "file-name" not available

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06256E Command file nesting is too deep

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06257E Cannot open command file "file-name"

Module:
DDCMD.PL1, EXCMD.PL1, GO.PL1
Parent topic: MFCWD06240 - MFCWD06259


MFCWD06260 - MFCWD06279

  • MFCWD06261W CALL argument passed by value
  • MFCWD06264E insert-name only allows %%ENTRY statement for non-debug routine
  • MFCWD06265E Line line-number extends beyond all PROCEDUREs
  • MFCWD06268W Bit OFFSET in POINTERs not supported
  • MFCWD06269I Initializing EXTERNAL symbol table
  • MFCWD06270I Done Initializing EXTERNAL symbol table
  • MFCWD06271S Initializing EXTERNAL symbol table (error error-number)
  • MFCWD06272I Looking for known RTS symbols
  • MFCWD06273I Done Looking for known RTS symbols
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06261W CALL argument passed by value

Module:
DFINDV.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06264E insert-name only allows %%ENTRY statement for non-debug routine

Module:
DSTMNT.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06265E Line line-number extends beyond all PROCEDUREs

Module:
DSTMNT.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06268W Bit OFFSET in POINTERs not supported

Module:
PTRBLD.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06269I Initializing EXTERNAL symbol table

Module:
INTSY.PL1, RELOAD.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06270I Done Initializing EXTERNAL symbol table

Module:
INTSY.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06271S Initializing EXTERNAL symbol table (error error-number)

Module:
INTSY.PL1, RELOAD.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06272I Looking for known RTS symbols

Module:
INTSY.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06273I Done Looking for known RTS symbols

Module:
INTSY.PL1
Parent topic: MFCWD06260 - MFCWD06279


MFCWD06280 - MFCWD06299

  • MFCWD06289W No environment for label/ENTRY constant
  • MFCWD06291E Unimplemented debugger command cannot perform LET on string variables
  • MFCWD06292E Debugger cannot perform LET cmd on string variables unless user program contain at least one string assignment.
  • MFCWD06293E on LET command. String variable unchanged. (Unable to read/write to user address space).
  • MFCWD06294E User program state maybe incorrectly modified.
  • MFCWD06295E User program terminated unexpectedly on LET.
  • MFCWD06296E reading process state on LET: insert-name
  • MFCWD06297E Unexpected breakpoint encountered on LET.
  • MFCWD06298E Unexpected trap encountered on LET.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06289W No environment for label/ENTRY constant

Module:
CONBLD.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06291E Unimplemented debugger command cannot perform LET on string variables

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06292E Debugger cannot perform LET cmd on string variables unless user program contain at least one string assignment.

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06293E on LET command. String variable unchanged. (Unable to read/write to user address space).

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06294E User program state maybe incorrectly modified.

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06295E User program terminated unexpectedly on LET.

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06296E reading process state on LET: insert-name

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06297E Unexpected breakpoint encountered on LET.

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06298E Unexpected trap encountered on LET.

Module:
USRWRT.PL1
Parent topic: MFCWD06280 - MFCWD06299


MFCWD06300 - MFCWD06319

  • MFCWD06303E Starting ENTRY point not found in Symbol Table.
  • MFCWD06310I **Interrupt** ... ignored.
  • MFCWD06315I Program exited with status status-value
  • MFCWD06316W Program interrupt not correctly handled
  • MFCWD06317I CodeWatch Quit...Bye!
  • MFCWD06318I Program not compiled in debug (-deb) mode.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06303E Starting ENTRY point not found in Symbol Table.

Module:
RELOAD.PL1
Parent topic: MFCWD06300 - MFCWD06319


MFCWD06310I **Interrupt** ... ignored.

Module:
GO.PL1, SIG.C
Parent topic: MFCWD06300 - MFCWD06319


MFCWD06315I Program exited with status status-value

Module:
DOCALL.PL1, DRESUM.PL1
Parent topic: MFCWD06300 - MFCWD06319


MFCWD06316W Program interrupt not correctly handled

Module:
DOCALL.PL1, DRESUM.PL1
Parent topic: MFCWD06300 - MFCWD06319


MFCWD06317I CodeWatch Quit...Bye!

Module:
DMAIN.PL1
Parent topic: MFCWD06300 - MFCWD06319


MFCWD06318I Program not compiled in debug (-deb) mode.

Module:
DDCMD.PL1, EXCMD.PL1, RELOAD.PL1
Parent topic: MFCWD06300 - MFCWD06319


MFCWD06320 - MFCWD06339

  • MFCWD06320W Unable to find or open STB file "file-name".
  • MFCWD06324E Cannot redirect output
  • MFCWD06325E Log file must be specified
  • MFCWD06326I No macros defined
  • MFCWD06327I Ending debugger command logging to "insert-name"
  • MFCWD06328I Logging debugger commands to "insert-name"
  • MFCWD06329I entry-name does not return a value
  • MFCWD06330I No watchpoints are currently set
  • MFCWD06331E File name must be specified.
  • MFCWD06332I Environment saved to file "file-name"
  • MFCWD06334E Sub-line sub-line-number not found on statement statement-number
  • MFCWD06335E Statement statement-number extends beyond environment environment-name
  • MFCWD06336W Statement statement-number not found in environment environment-name ...
  • MFCWD06337W CALL not supported for this target.
  • MFCWD06339I Program terminated abnormally (core dumped).
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06320W Unable to find or open STB file "file-name".

Module:
ENTDAT.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06324E Cannot redirect output

Module:
DDCMD.PL1, DMPBLK.PL1, DMPLIN.PL1, DMPPCL.PL1, DONBRK.PL1, EXCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06325E Log file must be specified

Module:
EXCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06326I No macros defined

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06327I Ending debugger command logging to "insert-name"

Module:
EXCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06328I Logging debugger commands to "insert-name"

Module:
EXCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06329I entry-name does not return a value

Module:
DDCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06330I No watchpoints are currently set

Module:
DDCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06331E File name must be specified.

Module:
DDCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06332I Environment saved to file "file-name"

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06334E Sub-line sub-line-number not found on statement statement-number

Module:
DSTMNT.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06335E Statement statement-number extends beyond environment environment-name

Module:
DSTMNT.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06336W Statement statement-number not found in environment environment-name ...

Module:
DSTMNT.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06337W CALL not supported for this target.

Module:
DOCALL.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06339I Program terminated abnormally (core dumped).

Module:
DOCALL.PL1, DRESUM.PL1
Parent topic: MFCWD06320 - MFCWD06339


MFCWD06340 - MFCWD06359

  • MFCWD06340I Program terminated abnormally.
  • MFCWD06343I Modifying existing breakpoint
  • MFCWD06344I Break set at insert-name
  • MFCWD06346I Continuing execution from insert-name
  • MFCWD06347I Environment reset to insert-name
  • MFCWD06348E Cannot GOTO from a non-debug routine routine-name
  • MFCWD06349I No breakpoints are currently set
  • MFCWD06350I No breakpoint set
  • MFCWD06351I Evaluation environment is environment-name
  • MFCWD06352I Environment(s) in "insert-name":
  • MFCWD06353I insert-name
  • MFCWD06354I insert-name = [insert-name]
  • MFCWD06355E cannot perform LRETURN in a non-debug routine routine-name
  • MFCWD06358I Current display source file is "file-name" (PL/I) insert-name
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06340I Program terminated abnormally.

Module:
DOCALL.PL1, DRESUM.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06343I Modifying existing breakpoint

Module:
DBREAK.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06344I Break set at insert-name

Module:
DBREAK.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06346I Continuing execution from insert-name

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06347I Environment reset to insert-name

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06348E Cannot GOTO from a non-debug routine routine-name

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06349I No breakpoints are currently set

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06350I No breakpoint set

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06351I Evaluation environment is environment-name

Module:
DDCMD.PL1, DENV.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06352I Environment(s) in "insert-name":

Module:
DENV.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06353I insert-name

Module:
DENV.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06354I insert-name = [insert-name]

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06355E cannot perform LRETURN in a non-debug routine routine-name

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06358I Current display source file is "file-name" (PL/I) insert-name

Module:
EXCMD.PL1
Parent topic: MFCWD06340 - MFCWD06359


MFCWD06360 - MFCWD06379

  • MFCWD06365I Symbol table file is "file-name"
  • MFCWD06366I Debug source file(s):
  • MFCWD06367I STEP IN, Execute BREAKPOINT action
  • MFCWD06368I STEP IN, Execute BREAKPOINT and STEP actions
  • MFCWD06369I STEP IN, Execute STEP action
  • MFCWD06370I STEP OVER, Execute BREAKPOINT action
  • MFCWD06371I STEP OVER, Execute BREAKPOINT and STEP actions
  • MFCWD06372I STEP OVER, Execute STEP action
  • MFCWD06373I Action = [insert-name]
  • MFCWD06374I No trace set
  • MFCWD06375I TRACE STATEMENT
  • MFCWD06376I TRACE ENTRY [insert-name] /IF {insert-name}
  • MFCWD06377I Redefining macro macro-name
  • MFCWD06378E Cannot perform RETURN in a non-debug routine routine-name
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06365I Symbol table file is "file-name"

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06366I Debug source file(s):

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06367I STEP IN, Execute BREAKPOINT action

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06368I STEP IN, Execute BREAKPOINT and STEP actions

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06369I STEP IN, Execute STEP action

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06370I STEP OVER, Execute BREAKPOINT action

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06371I STEP OVER, Execute BREAKPOINT and STEP actions

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06372I STEP OVER, Execute STEP action

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06373I Action = [insert-name]

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06374I No trace set

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06375I TRACE STATEMENT

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06376I TRACE ENTRY [insert-name] /IF {insert-name}

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06377I Redefining macro macro-name

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06378E Cannot perform RETURN in a non-debug routine routine-name

Module:
DDCMD.PL1
Parent topic: MFCWD06360 - MFCWD06379


MFCWD06380 - MFCWD06399

  • MFCWD06380E entry-name must return a value
  • MFCWD06381E Cannot STEP from a non-debug routine routine-name
  • MFCWD06382I Current execution point is insert-name
  • MFCWD06384I *** Continued line too long ***
  • MFCWD06385E Cannot set internal breakpoint at "insert-name" (insert-name)
  • MFCWD06387I Stack contains frame-count frame(s).
  • MFCWD06388I CALL Stack contains frame-count frame(s).
  • MFCWD06391I insert-name: Owner is "insert-name"
  • MFCWD06393N Arguments: None
  • MFCWD06394N Arguments:
  • MFCWD06395I Locals:
  • MFCWD06396I Locals: None
  • MFCWD06397I Globals:
  • MFCWD06398I Globals: None
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06380E entry-name must return a value

Module:
DDCMD.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06381E Cannot STEP from a non-debug routine routine-name

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06382I Current execution point is insert-name

Module:
DDCMD.PL1, DRESUM.PL1, DSTACK.PL1, EXCMD.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06384I *** Continued line too long ***

Module:
DGMR.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06385E Cannot set internal breakpoint at "insert-name" (insert-name)

Module:
DRTS.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06387I Stack contains frame-count frame(s).

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06388I CALL Stack contains frame-count frame(s).

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06391I insert-name: Owner is "insert-name"

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06393N Arguments: None

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06394N Arguments:

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06395I Locals:

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06396I Locals: None

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06397I Globals:

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06398I Globals: None

Module:
DSTACK.PL1
Parent topic: MFCWD06380 - MFCWD06399


MFCWD06400 - MFCWD06419

  • MFCWD06400I Called from routine-name
  • MFCWD06405I Stepping out of CALLed routine
  • MFCWD06406I Stepping out of main program
  • MFCWD06407I insert-name using statement statement-number instead.
  • MFCWD06408I Line line-number is not an executable statement ...
  • MFCWD06410I Modifying existing watchpoint watchpoint-name
  • MFCWD06411I Illegal to set watchpoint on non-debug data. insert-name
  • MFCWD06412I Watchpoint set for insert-name
  • MFCWD06413I Ambiguous reference can match the following:
  • MFCWD06415I Program stopped due to signal #signal-number
  • MFCWD06416I Program stopped due to a Watchpoint
  • MFCWD06417I Program stopped due to a RUN-TIME signal
  • MFCWD06418I Execution was at insert-name in "(unknown)"
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06400I Called from routine-name

Module:
DSTACK.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06405I Stepping out of CALLed routine

Module:
DSTEP.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06406I Stepping out of main program

Module:
DSTEP.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06407I insert-name using statement statement-number instead.

Module:
DSTMNT.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06408I Line line-number is not an executable statement ...

Module:
DSTMNT.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06410I Modifying existing watchpoint watchpoint-name

Module:
DWATCH.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06411I Illegal to set watchpoint on non-debug data. insert-name

Module:
DWATCH.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06412I Watchpoint set for insert-name

Module:
DWATCH.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06413I Ambiguous reference can match the following:

Module:
XLOOKCW.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06415I Program stopped due to signal #signal-number

Module:
DOCALL.PL1, DRESUM.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06416I Program stopped due to a Watchpoint

Module:
DONBRK.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06417I Program stopped due to a RUN-TIME signal

Module:
DOCALL.PL1, DRESUM.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06418I Execution was at insert-name in "(unknown)"

Module:
DOCALL.PL1
Parent topic: MFCWD06400 - MFCWD06419


MFCWD06420 - MFCWD06439

  • MFCWD06423I Initial evaluation environment is (unknown)
  • MFCWD06424I Initial evaluation environment is insert-name
  • MFCWD06425I Execution point is now insert-name
  • MFCWD06426I STEP (and break) at insert-name
  • MFCWD06427I STEP at insert-name
  • MFCWD06428I Break at insert-name
  • MFCWD06429I Break (interrupts STEP) at insert-name
  • MFCWD06430I **** insert-name
  • MFCWD06438I Watched variable variable-name modified about line line-number
  • MFCWD06439I Old Value: old-value
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06423I Initial evaluation environment is (unknown)

Module:
RELOAD.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06424I Initial evaluation environment is insert-name

Module:
RELOAD.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06425I Execution point is now insert-name

Module:
DONBRK.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06426I STEP (and break) at insert-name

Module:
DONBRK.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06427I STEP at insert-name

Module:
DONBRK.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06428I Break at insert-name

Module:
DONBRK.PL1, DRESUM.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06429I Break (interrupts STEP) at insert-name

Module:
DONBRK.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06430I **** insert-name

Module:
DONBRK.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06438I Watched variable variable-name modified about line line-number

Module:
DONBRK.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06439I Old Value: old-value

Module:
DWATCH.PL1
Parent topic: MFCWD06420 - MFCWD06439


MFCWD06440 - MFCWD06459

  • MFCWD06440I New Value: new-value
  • MFCWD06443E Cannot single STEP at insert-name in "insert-name"
  • MFCWD06444E reading process state (errno error-number)
  • MFCWD06445E writing process state (errno error-number)
  • MFCWD06446I Command line : insert-name
  • MFCWD06449E Loading insert-name (errno error-number) ... exit
  • MFCWD06450I **Error** Cannot exec insert-name... exit.
  • MFCWD06451I - Program program-name is running as another process.
  • MFCWD06452I usage: insert-name [ -x | -classic ]
  • MFCWD06453I [ -version ]
  • MFCWD06454I [ -stbpath STB_directory[:STB_directory]... ]
  • MFCWD06455I [ -srcpath source_directory[:source_directory]... ]
  • MFCWD06456I [ -path directory[:directory]... ]
  • MFCWD06457I [ program_to_debug ]
  • MFCWD06458I [ program_arguments ]
  • MFCWD06459I insert-name: bad flag (insert-name)
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06440I New Value: new-value

Module:
DONBRK.PL1
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06443E Cannot single STEP at insert-name in "insert-name"

Module:
JMPADR.PL1
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06444E reading process state (errno error-number)

Module:
DOCALL.PL1, GETRVL.PL1, JMPADR.PL1, NLGOTO.PL1, RESUME.PL1
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06445E writing process state (errno error-number)

Module:
JMPADR.PL1, NLGOTO.PL1, RESUME.PL1
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06446I Command line : insert-name

Module:
CMDARG.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06449E Loading insert-name (errno error-number) ... exit

Module:
LDUSER.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06450I **Error** Cannot exec insert-name... exit.

Module:
PROCFS.C, PTRACE.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06451I - Program program-name is running as another process.

Module:
PROCFS.C, PTRACE.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06452I usage: insert-name [ -x | -classic ]

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06453I [ -version ]

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06454I [ -stbpath STB_directory[:STB_directory]... ]

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06455I [ -srcpath source_directory[:source_directory]... ]

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06456I [ -path directory[:directory]... ]

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06457I [ program_to_debug ]

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06458I [ program_arguments ]

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06459I insert-name: bad flag (insert-name)

Module:
STRTUP.C
Parent topic: MFCWD06440 - MFCWD06459


MFCWD06460 - MFCWD06479

  • MFCWD06460I insert-name: can't find "insert-name"
  • MFCWD06461I CodeWatch setting up "insert-name". Wait...
  • MFCWD06462I Can't find user AREA address ... exit.
  • MFCWD06465I **DebugError** signal insert-name insert-name ... exit
  • MFCWD06466I Cannot open file "file-name".
  • MFCWD06467I File exists. Use "
  • MFCWD06471W Error getting file time/date stamp for "insert-name" (errno=error-number).
  • MFCWD06473E command-name is not a valid command.
  • MFCWD06477E LDUSER dup for input failed with ret = return-value.
  • MFCWD06478E LDUSER dup for output failed with ret = return-value.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06460I insert-name: can't find "insert-name"

Module:
STRTUP.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06461I CodeWatch setting up "insert-name". Wait...

Module:
STRTUP.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06462I Can't find user AREA address ... exit.

Module:
STRTUP.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06465I **DebugError** signal insert-name insert-name ... exit

Module:
SIG.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06466I Cannot open file "file-name".

Module:
SYSLOG.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06467I File exists. Use "

Module:
SYSLOG.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06471W Error getting file time/date stamp for "insert-name" (errno=error-number).

Module:
STRTUP.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06473E command-name is not a valid command.

Module:
DGMR2.PL1
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06477E LDUSER dup for input failed with ret = return-value.

Module:
LDUSER.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06478E LDUSER dup for output failed with ret = return-value.

Module:
LDUSER.C
Parent topic: MFCWD06460 - MFCWD06479


MFCWD06480 - MFCWD06499

  • MFCWD06481I String not found: "string-value"
  • MFCWD06482I [ -usrin redirected_input_filename ]
  • MFCWD06483I [ -usrout redirected_output_filename ]
  • MFCWD06484I [ -8bit ]
  • MFCWD06485I Source file of current environment is "file-name" (PL/I) insert-name
  • MFCWD06492I [ -nowarn ]
  • MFCWD06497I Cannot determine user AREA address (insert-name).
  • MFCWD06498I Enter this address if you know it (hex): 0x
  • MFCWD06499I Using 0xinsert-name as the USER AREA address.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06481I String not found: "string-value"

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06482I [ -usrin redirected_input_filename ]

Module:
STRTUP.C
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06483I [ -usrout redirected_output_filename ]

Module:
STRTUP.C
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06484I [ -8bit ]

Module:
STRTUP.C
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06485I Source file of current environment is "file-name" (PL/I) insert-name

Module:
EXCMD.PL1
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06492I [ -nowarn ]

Module:
STRTUP.C
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06497I Cannot determine user AREA address (insert-name).

Module:
PRSTATE.C
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06498I Enter this address if you know it (hex): 0x

Module:
PRSTATE.C
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06499I Using 0xinsert-name as the USER AREA address.

Module:
PRSTATE.C
Parent topic: MFCWD06480 - MFCWD06499


MFCWD06500 - MFCWD06519

  • MFCWD06503W Unable to open STB file "file-name".
  • MFCWD06504W Unsupported symbol table format for file "file-name". ** This STB file is an older format than the one currently ** supported by this version of CodeWatch. Refer to the ** current release notes for more information.
  • MFCWD06505I Program stopped due to unknown breakpoint at PC=insert-name.
  • MFCWD06510E Program already loaded via commandline or LOAD. Use KILL or NLOAD to abort this process.
  • MFCWD06512E Debug process must be loaded or attached. Only LOAD/ATTach/Help/Quit allowed here.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06503W Unable to open STB file "file-name".

Module:
XINITV.PL1
Parent topic: MFCWD06500 - MFCWD06519


MFCWD06504W Unsupported symbol table format for file "file-name". ** This STB file is an older format than the one currently ** supported by this version of CodeWatch. Refer to the ** current release notes for more information.

Module:
XINITV.PL1
Parent topic: MFCWD06500 - MFCWD06519


MFCWD06505I Program stopped due to unknown breakpoint at PC=insert-name.

Module:
DOCALL.PL1
Parent topic: MFCWD06500 - MFCWD06519


MFCWD06510E Program already loaded via commandline or LOAD. Use KILL or NLOAD to abort this process.

Module:
EXCMD.PL1
Parent topic: MFCWD06500 - MFCWD06519


MFCWD06512E Debug process must be loaded or attached. Only LOAD/ATTach/Help/Quit allowed here.

Module:
EXCMD.PL1
Parent topic: MFCWD06500 - MFCWD06519


MFCWD06520 - MFCWD06539

  • MFCWD06524I [ -e ]
  • MFCWD06525I [ -prompt prompt_string ]
  • MFCWD06527I RELOAD/LOAD not allowed while attached. Must DETACH first.
  • MFCWD06528E Already attached; must detach first.
  • MFCWD06529I Not currently attached.
  • MFCWD06530E Invalid character(s) in hex expression.
  • MFCWD06531E Hex expression too large for numeric binary conversion.
  • MFCWD06532E The number of single-bytes in a W or G string constant should be a multiple of 2.
  • MFCWD06533E Dynamically executing user program functions is not supported. Results may be vary.
  • MFCWD06534E Current source file is not debuggable - no symbols currently loaded.
  • MFCWD06535E SHLIB of main program or shared library is not allowed.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06524I [ -e ]

Module:
STRTUP.C
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06525I [ -prompt prompt_string ]

Module:
STRTUP.C
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06527I RELOAD/LOAD not allowed while attached. Must DETACH first.

Module:
EXCMD.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06528E Already attached; must detach first.

Module:
EXCMD.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06529I Not currently attached.

Module:
EXCMD.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06530E Invalid character(s) in hex expression.

Module:
DGMR.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06531E Hex expression too large for numeric binary conversion.

Module:
DGMR.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06532E The number of single-bytes in a W or G string constant should be a multiple of 2.

Module:
DGMR.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06533E Dynamically executing user program functions is not supported. Results may be vary.

Module:
DFINDV.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06534E Current source file is not debuggable - no symbols currently loaded.

Module:
DSTMNT.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06535E SHLIB of main program or shared library is not allowed.

Module:
EXCMD.PL1
Parent topic: MFCWD06520 - MFCWD06539


MFCWD06600 - MFCWD06619

  • MFCWD06608I Break (interrupts call) at insert-name
  • MFCWD06609I Continued out of CALL. Execution now at insert-name
  • MFCWD06619I Program stopped at exit point.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06608I Break (interrupts call) at insert-name

Module:
DONBRK.PL1
Parent topic: MFCWD06600 - MFCWD06619


MFCWD06609I Continued out of CALL. Execution now at insert-name

Module:
DONBRK.PL1
Parent topic: MFCWD06600 - MFCWD06619


MFCWD06619I Program stopped at exit point.

Module:
DRESUM.PL1
Parent topic: MFCWD06600 - MFCWD06619


MFCWD06620 - MFCWD06639

  • MFCWD06622E Cannot locate line line-number in source file "file-name".
  • MFCWD06623E Cannot call user function when program has just been loaded.
  • MFCWD06624E Cannot call user function after program exception.
  • MFCWD06625E No symbols found in executable.
  • MFCWD06628W Unknown frame number. Current frame number is frame-number.
  • MFCWD06629E "UP frame-count1" goes beyond top of stack. Only frame-count2 frames currently on stack.
  • MFCWD06630E Already at the bottom of the current Call stack.
  • MFCWD06631I Moved down frame-count frames.
  • MFCWD06632I Current evaluation environment is insert-name
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06622E Cannot locate line line-number in source file "file-name".

Module:
DSTMNT.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06623E Cannot call user function when program has just been loaded.

Module:
DOCALL.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06624E Cannot call user function after program exception.

Module:
DOCALL.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06625E No symbols found in executable.

Module:
INTSY.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06628W Unknown frame number. Current frame number is frame-number.

Module:
DSTACK.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06629E "UP frame-count1" goes beyond top of stack. Only frame-count2 frames currently on stack.

Module:
DSTACK.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06630E Already at the bottom of the current Call stack.

Module:
DSTACK.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06631I Moved down frame-count frames.

Module:
DSTACK.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06632I Current evaluation environment is insert-name

Module:
DDCMD.PL1, DENV.PL1, EXCMD.PL1, RELOAD.PL1
Parent topic: MFCWD06620 - MFCWD06639


MFCWD06640 - MFCWD06659

  • MFCWD06642E Cannot attach to process process-name (errno = error-number).
  • MFCWD06643I Attaching to process process-name.
  • MFCWD06646I [ -pid process-id ]
  • MFCWD06647E Illegal register name 'register-name'.
  • MFCWD06649I ISTEP IN
  • MFCWD06650I ISTEP OVER
  • MFCWD06651E Cannot read memory at memory-location.
  • MFCWD06652I [ -core corefile ]
  • MFCWD06653I Cannot open core file "file-name".
  • MFCWD06654I CodeWatch setting up "insert-name" (core file is "file-name"). Wait...
  • MFCWD06655I CodeWatch setting up [no executable] (core file is "file-name"). Wait...
  • MFCWD06658W Core file "file-name" does not match "insert-name". Ignoring core file...
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06642E Cannot attach to process process-name (errno = error-number).

Module:
PTRACE.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06643I Attaching to process process-name.

Module:
PTRACE.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06646I [ -pid process-id ]

Module:
STRTUP.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06647E Illegal register name 'register-name'.

Module:
REG.PL1
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06649I ISTEP IN

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06650I ISTEP OVER

Module:
DDCMD.PL1, EXCMD.PL1
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06651E Cannot read memory at memory-location.

Module:
MACT.PL1
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06652I [ -core corefile ]

Module:
STRTUP.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06653I Cannot open core file "file-name".

Module:
STRTUP.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06654I CodeWatch setting up "insert-name" (core file is "file-name"). Wait...

Module:
STRTUP.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06655I CodeWatch setting up [no executable] (core file is "file-name"). Wait...

Module:
STRTUP.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06658W Core file "file-name" does not match "insert-name". Ignoring core file...

Module:
STRTUP.C
Parent topic: MFCWD06640 - MFCWD06659


MFCWD06660 - MFCWD06679

  • MFCWD06661E Cannot detach from process process-name (errno = error-number).
  • MFCWD06662I Detaching from process process-name.
  • MFCWD06663E Cannot watch the given expression.
  • MFCWD06665I Program stopped due to an condition-name condition.
  • MFCWD06668E Error setting breakpoint at line-number.
  • MFCWD06670I Reloading..
  • MFCWD06671N ok
  • MFCWD06673I [ -defaultfont ]
  • MFCWD06674I **** Reading commands from "file-name" ...
  • MFCWD06675I **** Done reading commands from "file-name"
  • MFCWD06676I Ending debugger command and output logging to "insert-name"
  • MFCWD06677I Logging debugger commands and output to "insert-name"
  • MFCWD06679E Cannot read GOTO run-time argument
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06661E Cannot detach from process process-name (errno = error-number).

Module:
CTERMT.C
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06662I Detaching from process process-name.

Module:
CTERMT.C
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06663E Cannot watch the given expression.

Module:
DWAVAR.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06665I Program stopped due to an condition-name condition.

Module:
DRESUM.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06668E Error setting breakpoint at line-number.

Module:
DBREAK.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06670I Reloading..

Module:
RELOAD.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06671N ok

Module:
RELOAD.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06673I [ -defaultfont ]

Module:
STRTUP.C
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06674I **** Reading commands from "file-name" ...

Module:
SYSTT.C
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06675I **** Done reading commands from "file-name"

Module:
SYSTT.C
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06676I Ending debugger command and output logging to "insert-name"

Module:
EXCMD.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06677I Logging debugger commands and output to "insert-name"

Module:
EXCMD.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06679E Cannot read GOTO run-time argument

Module:
NLGOTO.PL1
Parent topic: MFCWD06660 - MFCWD06679


MFCWD06680 - MFCWD06699

  • MFCWD06680E Cannot read non-local GOTO target
  • MFCWD06681E Cannot read GOTO run-time display
  • MFCWD06682W Source file "file-name1" is newer than STB file "file-name2". It may be necessary to recompile this module and relink your program.
  • MFCWD06683W STB file "file-name1" is newer than executable file "file-name2". It may be necessary to relink your program.
  • MFCWD06687I insert-name-ing file "file-name"...
  • MFCWD06688I The following files have been un-insert-name-ed during this debug session:
  • MFCWD06689E Cannot find compress command "command-name" on PATH
  • MFCWD06690I Forked off process process-name to insert-name these files.
  • MFCWD06691I [ -nocompress ]
  • MFCWD06692W No compression suffix specified (CW_COMPRESS_SUFFIX environment variable). Using "compress", "uncompress", and ".Z", instead.
  • MFCWD06694I Do you want these files recompressed? (y or n)
  • MFCWD06695I Please answer "y" or "n":
  • MFCWD06696W Cannot open lock file "file-name". Continuing...
  • MFCWD06697I Problems might include:
  • MFCWD06698I - Not enough memory.
  • MFCWD06699I - Corrupted executable file.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06680E Cannot read non-local GOTO target

Module:
NLGOTO.PL1
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06681E Cannot read GOTO run-time display

Module:
NLGOTO.PL1
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06682W Source file "file-name1" is newer than STB file "file-name2". It may be necessary to recompile this module and relink your program.

Module:
DENV.PL1
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06683W STB file "file-name1" is newer than executable file "file-name2". It may be necessary to relink your program.

Module:
DENV.PL1
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06687I insert-name-ing file "file-name"...

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06688I The following files have been un-insert-name-ed during this debug session:

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06689E Cannot find compress command "command-name" on PATH

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06690I Forked off process process-name to insert-name these files.

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06691I [ -nocompress ]

Module:
STRTUP.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06692W No compression suffix specified (CW_COMPRESS_SUFFIX environment variable). Using "compress", "uncompress", and ".Z", instead.

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06694I Do you want these files recompressed? (y or n)

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06695I Please answer "y" or "n":

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06696W Cannot open lock file "file-name". Continuing...

Module:
SFILE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06697I Problems might include:

Module:
PROCFS.C, PTRACE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06698I - Not enough memory.

Module:
PROCFS.C, PTRACE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06699I - Corrupted executable file.

Module:
PROCFS.C, PTRACE.C
Parent topic: MFCWD06680 - MFCWD06699


MFCWD06700 - MFCWD06719

  • MFCWD06700I [ -forcecompress ]
  • MFCWD06701E Waiting for child process "process-name" (insert-name)
  • MFCWD06702E Setting signals for child process process-name
  • MFCWD06703I [ -ptrace | -proc ]
  • MFCWD06705E Cannot perform CALL command unless the program is linked with a "insert-name" run-time routine.
  • MFCWD06706E Argument to function-name built-in function cannot be negative.
  • MFCWD06707E Second argument to COPY built-in function must be positive.
  • MFCWD06708E First argument to built-in function must be a scalar.
  • MFCWD06710I Program stopped due to a load event for a pending shared object.
  • MFCWD06711S The LENGTH or MAXLENGTH built-in requires a scalar CHARACTER variable-reference.
  • MFCWD06712W The LENGTH or MAXLENGTH built-in argument should be a scalar.
  • MFCWD06713S The first argument of the HEXIMAGE built-in should of type POINTER.
  • MFCWD06714S The second argument of the HEXIMAGE built-in should of type FIXED BINARY.
  • MFCWD06715E Argument must be a POINTER.
  • MFCWD06716I Program stopped due to a call to PLITEST().
  • MFCWD06717S WATCH expression with multi-dimensional array and array slices not allowed.
  • MFCWD06718S WATCH expression with NONCONNECTED array reference not allowed.
  • MFCWD06719S Current environment not set - LSOURCE failed.
Parent topic: MFCWD - PL/I Debugger Messages


MFCWD06700I [ -forcecompress ]

Module:
STRTUP.C
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06701E Waiting for child process "process-name" (insert-name)

Module:
PROCFS.C
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06702E Setting signals for child process process-name

Module:
PROCFS.C
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06703I [ -ptrace | -proc ]

Module:
STRTUP.C
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06705E Cannot perform CALL command unless the program is linked with a "insert-name" run-time routine.

Module:
DOCALL.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06706E Argument to function-name built-in function cannot be negative.

Module:
DBIF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06707E Second argument to COPY built-in function must be positive.

Module:
DBIF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06708E First argument to built-in function must be a scalar.

Module:
DBIF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06710I Program stopped due to a load event for a pending shared object.

Module:
DRESUM.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06711S The LENGTH or MAXLENGTH built-in requires a scalar CHARACTER variable-reference.

Module:
DBIF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06712W The LENGTH or MAXLENGTH built-in argument should be a scalar.

Module:
SIZEOF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06713S The first argument of the HEXIMAGE built-in should of type POINTER.

Module:
DBIF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06714S The second argument of the HEXIMAGE built-in should of type FIXED BINARY.

Module:
DBIF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06715E Argument must be a POINTER.

Module:
DBIF.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06716I Program stopped due to a call to PLITEST().

Module:
DRESUM.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06717S WATCH expression with multi-dimensional array and array slices not allowed.

Module:
DWATCH.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06718S WATCH expression with NONCONNECTED array reference not allowed.

Module:
DWATCH.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFCWD06719S Current environment not set - LSOURCE failed.

Module:
EXCMD.PL1
Parent topic: MFCWD06700 - MFCWD06719


MFLDP - PL/I Linker Messages

  • MFLDP08500 - MFLDP08519
Parent topic: Open PL/I Error Messages


MFLDP08500 - MFLDP08519

  • MFLDP08500E Only insert-name allowed.
  • MFLDP08501E Illegal to export spacey ENTRY point name "insert-name" for def file "insert-name".
  • MFLDP08502E Usage: command-name [MS-LINKER switches] [Micro Focus switches] [objects] [libraries]
    command-name has been executed without arguments.
  • MFLDP08503E Nested @files not allowed. Sorry.
  • MFLDP08504E Error. Cannot open file insert-name.
Parent topic: MFLDP - PL/I Linker Messages


MFLDP08500E Only insert-name allowed.

Module:
LDPLI.C
Parent topic: MFLDP08500 - MFLDP08519


MFLDP08501E Illegal to export spacey ENTRY point name "insert-name" for def file "insert-name".

Module:
LDPLI.C
Parent topic: MFLDP08500 - MFLDP08519


MFLDP08502E Usage: command-name [MS-LINKER switches] [Micro Focus switches] [objects] [libraries]

command-name has been executed without arguments.
Resolution:
Supply the required arguments.
Module:
LDPLI.C
Parent topic: MFLDP08500 - MFLDP08519


MFLDP08503E Nested @files not allowed. Sorry.

Module:
LDPLI.C
Parent topic: MFLDP08500 - MFLDP08519


MFLDP08504E Error. Cannot open file insert-name.

Module:
LDPLI.C
Parent topic: MFLDP08500 - MFLDP08519


MFPLI - PL/I Compiler Messages

  • MFPLI00000 - MFPLI00019
  • MFPLI00020 - MFPLI00039
  • MFPLI00040 - MFPLI00059
  • MFPLI00060 - MFPLI00079
  • MFPLI00080 - MFPLI00099
  • MFPLI00100 - MFPLI00119
  • MFPLI00120 - MFPLI00139
  • MFPLI00140 - MFPLI00159
  • MFPLI00160 - MFPLI00179
  • MFPLI00180 - MFPLI00199
  • MFPLI00200 - MFPLI00219
  • MFPLI00220 - MFPLI00239
  • MFPLI00240 - MFPLI00259
  • MFPLI00260 - MFPLI00279
  • MFPLI00280 - MFPLI00299
  • MFPLI00300 - MFPLI00319
  • MFPLI00320 - MFPLI00339
  • MFPLI00340 - MFPLI00359
  • MFPLI00360 - MFPLI00379
  • MFPLI00380 - MFPLI00399
  • MFPLI00400 - MFPLI00419
  • MFPLI00420 - MFPLI00439
  • MFPLI00440 - MFPLI00459
  • MFPLI00460 - MFPLI00479
  • MFPLI01100 - MFPLI01119
  • MFPLI01120 - MFPLI01139
  • MFPLI01140 - MFPLI01159
  • MFPLI01160 - MFPLI01179
  • MFPLI01200 - MFPLI01219
  • MFPLI01220 - MFPLI01239
  • MFPLI01240 - MFPLI01259
  • MFPLI01260 - MFPLI01279
  • MFPLI01280 - MFPLI01299
  • MFPLI01300 - MFPLI01319
  • MFPLI01980 - MFPLI01999
  • MFPLI02000 - MFPLI02019
  • MFPLI02020 - MFPLI02039
  • MFPLI02060 - MFPLI02079
  • MFPLI02080 - MFPLI02099
  • MFPLI03000 - MFPLI03019
  • MFPLI04020 - MFPLI04039
  • MFPLI04040 - MFPLI04059
  • MFPLI04200 - MFPLI04219
  • MFPLI04220 - MFPLI04239
  • MFPLI04440 - MFPLI04459
  • MFPLI04460 - MFPLI04479
  • MFPLI04500 - MFPLI04519
  • MFPLI10000 - MFPLI10019
  • MFPLI10020 - MFPLI10039
  • MFPLI10040 - MFPLI10059
  • MFPLI10060 - MFPLI10079
  • MFPLI10080 - MFPLI10099
  • MFPLI10100 - MFPLI10119
  • MFPLI10120 - MFPLI10139
Parent topic: Open PL/I Error Messages


MFPLI00000 - MFPLI00019

  • MFPLI00001S The source text contains extraneous data. Check for excess END statements, unbalanced quotes, and unbalanced /* */.
    Source text has been encountered after the END statement that corresponds to the PROCEDURE statement.
  • MFPLI00002E Insufficient END statements. An additional END statement has been supplied.
    End of source before END statements have been encountered for all PROCEDURE, BEGIN and DO statements.
  • MFPLI00003S This is an unrecognizable statement.
    Either the keyword is not recognised as a valid keyword or the syntax is not recognized.
  • MFPLI00004S Syntax error.
    The syntax of the statement is in error.
  • MFPLI00005S "attribute-name" is an unrecognizable attribute keyword.
    attribute-name is being used as an attribute but is not recognized.
  • MFPLI00006S "format-item-name" is an unrecognizable format-item.
    format-item-name is being used in a format list but is not recognized.
  • MFPLI00007S "label-prefix" is a label prefix but has previously been declared.
    label-prefix has also been declared somewhere else.
  • MFPLI00008S "label-prefix" is a subscripted label prefix but has previously been declared with a different data type or a different number of dimensions.
    label-prefix has either been declared as something other than an array of LABEL variables or the subscript is not within the bounds of the array.
  • MFPLI00009S This statement contains a label prefix that has appeared on a previous statement in the same block.
    The same label prefix appears on two different statements in the same block.
  • MFPLI00010U An expression or reference contained within this DECLARE or DEFAULT statement is excessively complex and has caused the compiler's expression buffer to overflow. Reduce the complexity and recompile.
    The expression or reference is too complicated for the compiler.
  • MFPLI00011E A colon cannot follow a WHEN or OTHERWISE statement. The colon has been ignored.
    WHEN or OTHERWISE clauses are not label prefixes and so should not be followed by a colon.
  • MFPLI00012S If any ENTRY of a PROCEDURE has a RETURNS option, all entries must have a RETURNS option. A PROCEDURE cannot be both a subroutine and a function.
    Whan a procedure has multiple entry points all the ENTRY statements must have a RETURNS option if and only if the PROCEDURE statement has a RETURNS option.
  • MFPLI00013I Extraneous comma ignored.
    An unnecessary comma has been specified.
  • MFPLI00014S "parameter-name" is a parameter but has been declared with a storage class or as a label.
    CONTROLLED is the only additional storage class that may be specified for a parameter and then only if the corresponding arguments are CONTROLLED.
  • MFPLI00015S "identifier-name" as used in this statement conflicts with its usage in a previous statement within the same block.
    identifier-name has been contextually declared in another statement but its use in this statement conflicts with that declaration.
  • MFPLI00016S A label prefix cannot appear on a statement used as an on-unit.
    An on-unit can only be entered by raising the corresponding condition not from a GO TO statement.
  • MFPLI00017S "identifier-name" is an apparent STRUCTURE member, but does not immediately follow a variable with a level-number.
    identifier-name follows an apparent level-number but the previous identifier was not an element of a structure.
  • MFPLI00018S "format-label" must be the label of a FORMAT statement.
    format-label in the remote (or R) format item must be the label of a FORMAT statement.
  • MFPLI00019S The closure label in this statement does not match the label prefix of any containing DO, BEGIN, or PROCEDURE statement. This statement has closed the EXTERNAL PROCEDURE and will probably cause false errors to be reported.
    The label on the END statement does not match the label of any unclosed DO group, BEGIN block or PROCEDURE.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00001S The source text contains extraneous data. Check for excess END statements, unbalanced quotes, and unbalanced /* */.

Source text has been encountered after the END statement that corresponds to the PROCEDURE statement.
Resolution:
Check for excess END statements, unbalanced quotes, and comments without an ending deliminator.
Module:
PLSP1.TB
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00002E Insufficient END statements. An additional END statement has been supplied.

End of source before END statements have been encountered for all PROCEDURE, BEGIN and DO statements.
Resolution:
Check that all PROCEDURE, BEGIN and DO statements have a corresponding END statement.
Module:
PASS1.PL1, PLSP1.TB
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00003S This is an unrecognizable statement.

Either the keyword is not recognised as a valid keyword or the syntax is not recognized.
Resolution:
Check the spelling of the statement keyword and the syntax of the statement.
Module:
PASS1.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00004S Syntax error.

The syntax of the statement is in error.
Resolution:
Check the syntax of the statement.
Module:
PASS1.PL1, PLSP1.TB
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00005S "attribute-name" is an unrecognizable attribute keyword.

attribute-name is being used as an attribute but is not recognized.
Resolution:
Check the spelling of attribute-name.
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00006S "format-item-name" is an unrecognizable format-item.

format-item-name is being used in a format list but is not recognized.
Resolution:
Check the spelling of format-item-name.
Module:
PASS1.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00007S "label-prefix" is a label prefix but has previously been declared.

label-prefix has also been declared somewhere else.
Resolution:
Correct or remove label-prefix or remove the declaration.
Module:
PASS1.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00008S "label-prefix" is a subscripted label prefix but has previously been declared with a different data type or a different number of dimensions.

label-prefix has either been declared as something other than an array of LABEL variables or the subscript is not within the bounds of the array.
Resolution:
Correct the subscript or the array bounds.
Module:
PASS1.PL1, SUBLAB.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00009S This statement contains a label prefix that has appeared on a previous statement in the same block.

The same label prefix appears on two different statements in the same block.
Resolution:
Correct or remove one of the label prefixes.
Module:
PASS1.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00010U An expression or reference contained within this DECLARE or DEFAULT statement is excessively complex and has caused the compiler's expression buffer to overflow. Reduce the complexity and recompile.

The expression or reference is too complicated for the compiler.
Resolution:
Simplify the expression or reference.
Module:
PASS1.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00011E A colon cannot follow a WHEN or OTHERWISE statement. The colon has been ignored.

WHEN or OTHERWISE clauses are not label prefixes and so should not be followed by a colon.
Resolution:
Remove the colon.
Module:
PLSP1.TB
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00012S If any ENTRY of a PROCEDURE has a RETURNS option, all entries must have a RETURNS option. A PROCEDURE cannot be both a subroutine and a function.

Whan a procedure has multiple entry points all the ENTRY statements must have a RETURNS option if and only if the PROCEDURE statement has a RETURNS option.
Resolution:
Either add RETURNS options to all ENTRY statements or remove the RETURNS option from all ENTRY statements.
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00013I Extraneous comma ignored.

An unnecessary comma has been specified.
Resolution:
Remove the extraneous comma.
Module:
PASS1.PL1, PLSP1.TB
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00014S "parameter-name" is a parameter but has been declared with a storage class or as a label.

CONTROLLED is the only additional storage class that may be specified for a parameter and then only if the corresponding arguments are CONTROLLED.
Resolution:
Remove the storage class from the declaration of parameter-name.
Module:
DCLPCS.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00015S "identifier-name" as used in this statement conflicts with its usage in a previous statement within the same block.

identifier-name has been contextually declared in another statement but its use in this statement conflicts with that declaration.
Resolution:
Correct the conflict.
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00016S A label prefix cannot appear on a statement used as an on-unit.

An on-unit can only be entered by raising the corresponding condition not from a GO TO statement.
Resolution:
Remove the label prefix.
Module:
PLSP1.TB
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00017S "identifier-name" is an apparent STRUCTURE member, but does not immediately follow a variable with a level-number.

identifier-name follows an apparent level-number but the previous identifier was not an element of a structure.
Resolution:
Correct the level-numbers.
Module:
PASS1.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00018S "format-label" must be the label of a FORMAT statement.

format-label in the remote (or R) format item must be the label of a FORMAT statement.
Resolution:
Correct the reference.
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00019S The closure label in this statement does not match the label prefix of any containing DO, BEGIN, or PROCEDURE statement. This statement has closed the EXTERNAL PROCEDURE and will probably cause false errors to be reported.

The label on the END statement does not match the label of any unclosed DO group, BEGIN block or PROCEDURE.
Resolution:
Correct the label on the END statement.
Module:
PASS1.PL1
Parent topic: MFPLI00000 - MFPLI00019


MFPLI00020 - MFPLI00039

  • MFPLI00020S An IF, ON, DO, RETURN, LEAVE, or SELECT statement cannot be used as an on-unit.
    An ON-unit can only be a single unlabeled simple statement or an unlabeled BEGIN block.
  • MFPLI00021E This statement contains a duplicate declaration of "identifier-name" and will be ignored.
    identifier-name is declared more than once in the current PROCEDURE or BEGIN block.
  • MFPLI00022U The total number of declarations, parameter descriptors, and RETURNS descriptors in this DECLARE statement exceeds the implementation's limit.
    There are too many declarations in one statement for the compiler.
  • MFPLI00023S This statement contains duplicate WHILE options.
    An iterative DO statement may only contain one WHILE clause.
  • MFPLI00024W The ENVIRONMENT option "environment-name" is not implemented.
    environment-name is not supported and may not be applicable to the current platform.
  • MFPLI00025S Attributes declared for "identifier-name" conflict with factored attributes.
    After applying the factored attributes there is a conflict between attributes for identifier-name, for example, FIXED and FLOAT.
  • MFPLI00026S This statement contains unbalanced parentheses.
    There are not the same number of left and right parentheses or they are not nested properly.
  • MFPLI00027S Invalid syntax in this SELECT statement.
    The syntax of the SELECT statement is incorrect.
  • MFPLI00028S Invalid end of text. Check for unbalanced quotes or unbalanced comments.
    The end of source before closing quote or closing comment.
  • MFPLI00029E An identifier contains more than 100 characters. Only the first 100 characters will be used.
    Only the first 100 characters of an identifier are used.
  • MFPLI00030S A FORMAT, ENTRY, PROCEDURE, END, DECLARE, or DEFAULT statement appears in a context that requires an executable single statement, DO group, or BEGIN block.
    The context requires a single executable statement, for example, in a THEN, ELSE or WHEN clause.
  • MFPLI00031S A factored level cannot be applied to "identifier-name".
    Some members of a structure have a factored level number.
  • MFPLI00032U Previous errors prevent continued compilation. If no previous errors were diagnosed, contact Micro Focus Support Line.
    Compilation has been prevented from continuing due to previous errors.
  • MFPLI00033S Invalid syntax in attribute list.
    The attribute list contains invalid syntax.
  • MFPLI00034S "identifier-name" is declared with the TYPE attribute in a list of factored declarations, but the list of factored attributes also contains a TYPE attribute.
  • MFPLI00035S PROCEDURE, ENTRY, and FORMAT statements must have an unsubscripted label.
    PROCEDURE, ENTRY, and FORMAT statements may not have subscripted labels.
  • MFPLI00036S "attribute-name" is an unrecognizable attribute.
    The attribute "attribute-name" is not recognised.
  • MFPLI00037W An END statement has been supplied to close an open DO, SELECT, BEGIN, or PROCEDURE.
    An END statement has specified the label on a previous DO or SELECT group, BEGIN or PROCEDURE block and one or more END statements have been supplied to close the intervening blocks or groups.
  • MFPLI00038S The scale-factor of a constant exceeds the implementation's limits.
    The scaling factor must not be less than minus 128 or greater than plus 127.
  • MFPLI00039S The TYPE attribute has been used more than once.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00020S An IF, ON, DO, RETURN, LEAVE, or SELECT statement cannot be used as an on-unit.

An ON-unit can only be a single unlabeled simple statement or an unlabeled BEGIN block.
Resolution:
Put the statements in a BEGIN block.
Module:
PLSP1.TB
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00021E This statement contains a duplicate declaration of "identifier-name" and will be ignored.

identifier-name is declared more than once in the current PROCEDURE or BEGIN block.
Resolution:
Remove one of the declarations or change the name of one of the identifiers.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00022U The total number of declarations, parameter descriptors, and RETURNS descriptors in this DECLARE statement exceeds the implementation's limit.

There are too many declarations in one statement for the compiler.
Resolution:
Split the DECLARE statement into two or more statements.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00023S This statement contains duplicate WHILE options.

An iterative DO statement may only contain one WHILE clause.
Resolution:
Combine the conditions into a single WHILE clause.
Module:
PLSP1.TB
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00024W The ENVIRONMENT option "environment-name" is not implemented.

environment-name is not supported and may not be applicable to the current platform.
Resolution:
Remove the ENVIRONMENT option.
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00025S Attributes declared for "identifier-name" conflict with factored attributes.

After applying the factored attributes there is a conflict between attributes for identifier-name, for example, FIXED and FLOAT.
Resolution:
Resolve the conflict.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00026S This statement contains unbalanced parentheses.

There are not the same number of left and right parentheses or they are not nested properly.
Resolution:
Correct the placing of the parentheses.
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00027S Invalid syntax in this SELECT statement.

The syntax of the SELECT statement is incorrect.
Resolution:
Correct the syntax of the SELECT statement.
Module:
PLSP1.TB
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00028S Invalid end of text. Check for unbalanced quotes or unbalanced comments.

The end of source before closing quote or closing comment.
Resolution:
Supply the missing closing quote or closing comment.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00029E An identifier contains more than 100 characters. Only the first 100 characters will be used.

Only the first 100 characters of an identifier are used.
Resolution:
Shorten the identifier to 100 characters.
Module:
LEXSTATE.IN
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00030S A FORMAT, ENTRY, PROCEDURE, END, DECLARE, or DEFAULT statement appears in a context that requires an executable single statement, DO group, or BEGIN block.

The context requires a single executable statement, for example, in a THEN, ELSE or WHEN clause.
Resolution:
Put the statements in a DO group or BEGIN block.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00031S A factored level cannot be applied to "identifier-name".

Some members of a structure have a factored level number.

However the member identifier-name also has an explicit level number.

Resolution:
Either remove the explicit level number or rearrange the factoring.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00032U Previous errors prevent continued compilation. If no previous errors were diagnosed, contact Micro Focus Support Line.

Compilation has been prevented from continuing due to previous errors.
Resolution:
Correct the previous errors and contact Micro Focus Support Line if this does not solve the problem.
Module:
DCLPCS.PL1, DGMR2.PL1, PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00033S Invalid syntax in attribute list.

The attribute list contains invalid syntax.
Resolution:
Correct the invalid syntax.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00034S "identifier-name" is declared with the TYPE attribute in a list of factored declarations, but the list of factored attributes also contains a TYPE attribute.

Resolution:
Either remove this variable from the factored list and declare it separately or remove the TYPE attribute on this name within the list.
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00035S PROCEDURE, ENTRY, and FORMAT statements must have an unsubscripted label.

PROCEDURE, ENTRY, and FORMAT statements may not have subscripted labels.
Resolution:
Use an unsubscripted label for the statement.
Module:
PASS1.PL1, PLSP1.TB
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00036S "attribute-name" is an unrecognizable attribute.

The attribute "attribute-name" is not recognised.

This may be because the attribute is not yet supported, for example, PRECISION.

Resolution:
Check the spelling and syntax of the attribute "attribute-name".
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00037W An END statement has been supplied to close an open DO, SELECT, BEGIN, or PROCEDURE.

An END statement has specified the label on a previous DO or SELECT group, BEGIN or PROCEDURE block and one or more END statements have been supplied to close the intervening blocks or groups.
Resolution:
Supply matching END statements to avoid the message.
Module:
PASS1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00038S The scale-factor of a constant exceeds the implementation's limits.

The scaling factor must not be less than minus 128 or greater than plus 127.
Resolution:
Adjust the scaling factor to within those bounds.
Module:
DCLPL1.PL1
Parent topic: MFPLI00020 - MFPLI00039


MFPLI00039S The TYPE attribute has been used more than once.

Parent topic: MFPLI00020 - MFPLI00039


MFPLI00040 - MFPLI00059

  • MFPLI00040S This LEAVE statement is either not contained within a DO group, or it attempts to transfer control out of the current PROCEDURE or BEGIN block.
    A LEAVE statement may only transfer control out of a DO group within the current PROCEDURE or BEGIN block.
  • MFPLI00041S This statement contains an ambiguous reference to "identifier-name".
    The compiler cannot determine which instance of "identifier-name" is being referenced.
  • MFPLI00042U Possible compiler error. The compiler is unable to find a value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Internal compiler error.
  • MFPLI00043S Both the FILE and the STRING options have been used in this statement.
    Only one of the options FILE and STRING may be used in a GET or PUT statement.
  • MFPLI00044S "array-name" has been declared with an INITIAL attribute. An INITIAL attribute cannot be specified for AUTOMATIC arrays with nonconstant extents.
    The INITIAL attribute may only be specified for AUTOMATIC arrays that have constant extents.
  • MFPLI00045S Both the DATA and the LIST options have been used in this statement.
    Only one of the options DATA and LIST may be used in a GET or PUT statement.
  • MFPLI00046S "identifier-name" is declared with conflicting or duplicate attributes.
    "identifier-name" is either declared with the same attribute twice or with conflicting attributes, for example, FIXED and FLOAT, or BINARY and DECIMAL.
  • MFPLI00047S Both the KEY and the KEYTO options have been used in this statement.
    The KEY and KEYTO options are mutually exclusive and no more than one can be used in a READ statement.
  • MFPLI00048S Both the SET and the INTO options have been used in this statement.
    Only one of the options SET and INTO may be used in a READ statement.
  • MFPLI00049S An expected type-name value was not found. One of the values in this statement has a data type which is inconsistent with the context in which the value is used.
    A type-name value was expected but a value of an inconsistent type was encountered.
  • MFPLI00050E The precision specified for "variable-name" exceeds the implementation's limit of FIXED BINARY variables. The maximum precision has been supplied. Use FIXED DECIMAL for larger values.
    The maximum precision that may be specified for a FIXED BINARY variable is 63 if it is SIGNED or 64 if it is UNSIGNED.
  • MFPLI00051E The precision specified for "variable-name" exceeds the implementation's limit for FIXED DECIMAL variables. The maximum precision has been supplied.
    The maximum precision that may be specified for a FIXED DECIMAL variable is 31.
  • MFPLI00052E The scale-factor specified for "variable-name" exceeds the implementation's limit. The scale-factor has been set to zero.
  • MFPLI00053E The precision specified for "variable-name" exceeds the implementation's limit for FLOAT BINARY variables. The maximum precision has been supplied.
    The maximum precision that may be specified for a FLOAT BINARY variable is 52.
  • MFPLI00054E The precision specified for "variable-name" exceeds the implementation's limit for FLOAT DECIMAL variables. The maximum precision has been supplied.
    The maximum precision that may be specified for a FLOAT DECIMAL variable is 16.
  • MFPLI00055E Size or precision must be part of a VALUE clause; ignored.
  • MFPLI00056S More than 8 dimensions have been specified in a DIMENSION attribute.
    The maximum number of dimensions that may be specified for an array is 8.
  • MFPLI00057U PASS2 has overflowed its stack. Reduce the complexity of this statement and recompile.
    This statement is too complex to compile.
  • MFPLI00058S A descriptor is an apparent STRUCTURE member, but does not immediately follow a descriptor with a level-number.
    A parameter descriptor in the declaration of an ENTRY has one of more attributes preceded by a level number but this is not part of the descriptor for a structure parameter.
  • MFPLI00059S "variable-name" is declared with an * extent but is not a parameter or a descriptor.
    Only parameters, parameter descriptors or CONTROLLED variables may have asterisk extents.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00040S This LEAVE statement is either not contained within a DO group, or it attempts to transfer control out of the current PROCEDURE or BEGIN block.

A LEAVE statement may only transfer control out of a DO group within the current PROCEDURE or BEGIN block.
Resolution:
Correct the LEAVE statement.
Module:
PASS1.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00041S This statement contains an ambiguous reference to "identifier-name".

The compiler cannot determine which instance of "identifier-name" is being referenced.
Resolution:
Include sufficient higher-level structure names so that the reference is unambiguous.
Module:
XLOOK.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00042U Possible compiler error. The compiler is unable to find a value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Internal compiler error.
Resolution:
Contact Micro Focus Support Line if this message persists after correcting all program errors and recompiling.
Module:
FINDVL.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00043S Both the FILE and the STRING options have been used in this statement.

Only one of the options FILE and STRING may be used in a GET or PUT statement.
Resolution:
Remove the unwanted FILE or STRING option. If neither is specified, GET FILE (SYSIN) or PUT FILE (SYSPRINT) is assumed.
Module:
PLSP2.TB
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00044S "array-name" has been declared with an INITIAL attribute. An INITIAL attribute cannot be specified for AUTOMATIC arrays with nonconstant extents.

The INITIAL attribute may only be specified for AUTOMATIC arrays that have constant extents.
Resolution:
Remove the INITIAL attribute and initialise the array "array-name" on block entry.
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00045S Both the DATA and the LIST options have been used in this statement.

Only one of the options DATA and LIST may be used in a GET or PUT statement.
Resolution:
Remove the unwanted DATA or LIST option. If neither is specified, LIST is assumed.
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00046S "identifier-name" is declared with conflicting or duplicate attributes.

"identifier-name" is either declared with the same attribute twice or with conflicting attributes, for example, FIXED and FLOAT, or BINARY and DECIMAL.
Resolution:
Remove the conflicting or duplicate attribute.
Module:
DCLPCS.PL1, PASS1.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00047S Both the KEY and the KEYTO options have been used in this statement.

The KEY and KEYTO options are mutually exclusive and no more than one can be used in a READ statement.
Resolution:
If the KEY option is used the key must be known and the KEYTO option is unnecessary.
Module:
PLSP2.TB
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00048S Both the SET and the INTO options have been used in this statement.

Only one of the options SET and INTO may be used in a READ statement.
Resolution:
Remove the SET option if move-mode is required or remove the INTO option if locate-mode is required.
Module:
PLSP2.TB
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00049S An expected type-name value was not found. One of the values in this statement has a data type which is inconsistent with the context in which the value is used.

A type-name value was expected but a value of an inconsistent type was encountered.
Resolution:
Correct the value so that it is of a type consistent with the context.
Module:
INTRP2.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00050E The precision specified for "variable-name" exceeds the implementation's limit of FIXED BINARY variables. The maximum precision has been supplied. Use FIXED DECIMAL for larger values.

The maximum precision that may be specified for a FIXED BINARY variable is 63 if it is SIGNED or 64 if it is UNSIGNED.
Resolution:
Reduce the precision of variable-name to 63 if it is SIGNED or 64 if it is UNSIGNED.
Module:
DCLPCS.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00051E The precision specified for "variable-name" exceeds the implementation's limit for FIXED DECIMAL variables. The maximum precision has been supplied.

The maximum precision that may be specified for a FIXED DECIMAL variable is 31.
Resolution:
Reduce the precision of variable-name to 31.
Module:
DCLPCS.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00052E The scale-factor specified for "variable-name" exceeds the implementation's limit. The scale-factor has been set to zero.

Module:
DCLPCS.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00053E The precision specified for "variable-name" exceeds the implementation's limit for FLOAT BINARY variables. The maximum precision has been supplied.

The maximum precision that may be specified for a FLOAT BINARY variable is 52.
Resolution:
Reduce the precision of variable-name to 52.
Module:
DCLPCS.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00054E The precision specified for "variable-name" exceeds the implementation's limit for FLOAT DECIMAL variables. The maximum precision has been supplied.

The maximum precision that may be specified for a FLOAT DECIMAL variable is 16.
Resolution:
Reduce the precision of variable-name to 16.
Module:
DCLPCS.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00055E Size or precision must be part of a VALUE clause; ignored.

Module:
PLSP1.TB
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00056S More than 8 dimensions have been specified in a DIMENSION attribute.

The maximum number of dimensions that may be specified for an array is 8.
Resolution:
Reduce the number of dimensions to 8.
Module:
PASS1.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00057U PASS2 has overflowed its stack. Reduce the complexity of this statement and recompile.

This statement is too complex to compile.
Resolution:
Reduce the complexity of this statement and recompile.
Module:
INTRP2.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00058S A descriptor is an apparent STRUCTURE member, but does not immediately follow a descriptor with a level-number.

A parameter descriptor in the declaration of an ENTRY has one of more attributes preceded by a level number but this is not part of the descriptor for a structure parameter.
Resolution:
Remove the level-number unless the parameter is a structure. If the parameter is a structure provide a structure descriptor.
Module:
PASS1.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00059S "variable-name" is declared with an * extent but is not a parameter or a descriptor.

Only parameters, parameter descriptors or CONTROLLED variables may have asterisk extents.
Resolution:
Either provide non-asterisk extents or correct the storage class of "variable-name".
Module:
DCLPCS.PL1
Parent topic: MFPLI00040 - MFPLI00059


MFPLI00060 - MFPLI00079

  • MFPLI00060S "array-name" is declared with nonconstant extents but is not an AUTOMATIC, BASED, CONTROLLED, or DEFINED variable.
  • MFPLI00061S An expected type-name value was not found. One of the values in this statement has a data type that cannot be converted to the type required by the context in which the value is used.
    A type-name value was expected but a value was encountered that cannot be converted to the required type.
  • MFPLI00062S Possible compiler error. An invalid code has been given to the convert subroutine of PASS2. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    The compiler has possibly encountered an error.
  • MFPLI00063U The length of a name or constant exceeds the implementation's limit. Check to see if all string constants are properly quoted with ' and that any contained 's occur in pairs. Also check for unbalanced /* */.
    The maximum length of a PL/I token created externally in the source code is 3072.
  • MFPLI00064S A built-in function has been referenced with the wrong number of arguments.
    Built-in functions must be referenced with the correct number of arguments.
  • MFPLI00065S Because POINTERs are not capable of pointing to bit-addresses, the argument of ADDR must be aligned on a byte or higher storage boundary.
    The argument of ADDR cannot be a bit-string that is not aligned on a byte boundary.
  • MFPLI00066U The nesting depth of a STRUCTURE exceeds the implementation's limit.
    The maximum structure nesting depth is 16.
  • MFPLI00067U A statement exceeds the implementation's limit of tokens.
    This statement is too complicated.
  • MFPLI00068S Invalid syntax in an arithmetic constant.
    This arithmetic constant contains invalid syntax.
  • MFPLI00069W An arithmetic constant must be separated from the following symbol by a delimiter. A blank delimiter has been supplied.
  • MFPLI00070W A symbol begins with _. The _ has been ignored.
  • MFPLI00071U The total number of errors exceeds the implementation's limit.
  • MFPLI00072S The second argument of the ROUND built-in function must be an optionally signed decimal integer constant.
    The second argument of the ROUND built-in function cannot be a variable or an expression.
  • MFPLI00073S The R-format must reference a format value.
    The bracketed identifier following an R-format item must be the label on a FORMAT statement.
  • MFPLI00074S The only values that can be converted to POINTER types are OFFSET variables that have been declared with an AREA name.
  • MFPLI00075S A floating-point value is required by this statement, but a noncomputational value has been used. It cannot be converted.
    A non-computational value cannot be converted to a floating point value as required by this statement.
  • MFPLI00076S One of the bounds declared for "array-name" is invalid because the lower bound is greater than the upper bound.
    For each dimension of an array the upper bound of must not be less than the lower bound.
  • MFPLI00077S This statement contains an unrecognizable condition name.
    This is an ON, SIGNAL or REVERT statement referencing a condition name or is preceded by a condition prefix consisting of a condition name in parenetheses followed by a colon.
  • MFPLI00078S A parenthesized name is not valid with this condition.
    Some conditions, for example, CONDITION, ENDFILE, ENDPAGE, KEY and RECORD, are followed by a qualification, for example, condition name or file name, in parentheses.
  • MFPLI00079U Excessive complexity of this statement has caused the compiler's parse output stack to overflow. Reduce the complexity and recompile.
    The compiler's parse output stack has overflowed due to the excessive complexity of this statement.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00060S "array-name" is declared with nonconstant extents but is not an AUTOMATIC, BASED, CONTROLLED, or DEFINED variable.

Module:
DCLPCS.PL1 (commented out)
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00061S An expected type-name value was not found. One of the values in this statement has a data type that cannot be converted to the type required by the context in which the value is used.

A type-name value was expected but a value was encountered that cannot be converted to the required type.
Resolution:
Correct the value so that it can be converted to a type required by the context.
Module:
CVTPL1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00062S Possible compiler error. An invalid code has been given to the convert subroutine of PASS2. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

The compiler has possibly encountered an error.
Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CVTPL1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00063U The length of a name or constant exceeds the implementation's limit. Check to see if all string constants are properly quoted with ' and that any contained 's occur in pairs. Also check for unbalanced /* */.

The maximum length of a PL/I token created externally in the source code is 3072.
Resolution:
Check that all string constants and comments are properly formed.
Module:
PASS1.PL1, LEXSTATE.IN
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00064S A built-in function has been referenced with the wrong number of arguments.

Built-in functions must be referenced with the correct number of arguments.
Resolution:
Correct the number of arguments.
Module:
EXPEXP.PL1, INTRP2.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00065S Because POINTERs are not capable of pointing to bit-addresses, the argument of ADDR must be aligned on a byte or higher storage boundary.

The argument of ADDR cannot be a bit-string that is not aligned on a byte boundary.
Resolution:
Ensure the bit-string argument of ADDR is aligned on a byte boundary.
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00066U The nesting depth of a STRUCTURE exceeds the implementation's limit.

The maximum structure nesting depth is 16.
Resolution:
Reduce the structure nesting depth to 16.
Module:
PASS1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00067U A statement exceeds the implementation's limit of tokens.

This statement is too complicated.
Resolution:
Reduce the complexity of this statement.
Module:
PASS1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00068S Invalid syntax in an arithmetic constant.

This arithmetic constant contains invalid syntax.

Correct the syntax of the arithmetic constant.

Module:
LEXSTATE.IN
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00069W An arithmetic constant must be separated from the following symbol by a delimiter. A blank delimiter has been supplied.

Module:
LEXSTATE.IN
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00070W A symbol begins with _. The _ has been ignored.

Module:
LEXSTATE.IN
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00071U The total number of errors exceeds the implementation's limit.

Parent topic: MFPLI00060 - MFPLI00079


MFPLI00072S The second argument of the ROUND built-in function must be an optionally signed decimal integer constant.

The second argument of the ROUND built-in function cannot be a variable or an expression.
Resolution:
If different rounding is required depending on particular conditions then use a SELECT statement to choose between evaluating expressions using ROUND with different integer constant second arguments.
Module:
RESIS.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00073S The R-format must reference a format value.

The bracketed identifier following an R-format item must be the label on a FORMAT statement.
Resolution:
Correct the R-format item.
Module:
PASS2.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00074S The only values that can be converted to POINTER types are OFFSET variables that have been declared with an AREA name.

Parent topic: MFPLI00060 - MFPLI00079


MFPLI00075S A floating-point value is required by this statement, but a noncomputational value has been used. It cannot be converted.

A non-computational value cannot be converted to a floating point value as required by this statement.
Resolution:
Supply a computational value that can be converted to floating point.
Module:
CVTPL1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00076S One of the bounds declared for "array-name" is invalid because the lower bound is greater than the upper bound.

For each dimension of an array the upper bound of must not be less than the lower bound.
Resolution:
Correct the dimensions of "array-name".
Module:
DCLPCS.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00077S This statement contains an unrecognizable condition name.

This is an ON, SIGNAL or REVERT statement referencing a condition name or is preceded by a condition prefix consisting of a condition name in parenetheses followed by a colon.

However the condition name is not recognized.

Resolution:
Correct the condition name or remove the condition prefix.
Module:
PASS1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00078S A parenthesized name is not valid with this condition.

Some conditions, for example, CONDITION, ENDFILE, ENDPAGE, KEY and RECORD, are followed by a qualification, for example, condition name or file name, in parentheses.

However the condition in this ON, SIGNAL or REVERT statement does not have such a parenthesized name.

Resolution:
Remove the parenthesized name.
Module:
PASS1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00079U Excessive complexity of this statement has caused the compiler's parse output stack to overflow. Reduce the complexity and recompile.

The compiler's parse output stack has overflowed due to the excessive complexity of this statement.
Resolution:
Reduce the complexity of this statement.
Module:
PASS1.PL1
Parent topic: MFPLI00060 - MFPLI00079


MFPLI00080 - MFPLI00099

  • MFPLI00080S Unrecognizable condition prefix name.
  • MFPLI00081S A complex arithmetic value is required by this statement, but a noncomputational value has been used. It cannot be converted.
  • MFPLI00082S Invalid syntax in this statement. A token-name was found where another token was expected.
  • MFPLI00083S Invalid syntax in this statement. A keyword-name keyword was not found in the expected position.
  • MFPLI00084S Invalid conversion. Noncomputational data cannot be converted to string or arithmetic data.
  • MFPLI00085S A STRUCTURE qualified reference to "identifier-name" cannot be resolved to any declaration known to this block.
    The element "identifier-name" together with its structure qualification cannot be resolved to any structure element declared in this or a containing block.
  • MFPLI00086S A locator-qualified reference to "identifier-name" cannot be resolved to any declaration known to this block.
    The locator-qualifed reference cannot be resolved possibly because "identifier-name" is not a BASED variable.
  • MFPLI00087S A STRUCTURE qualified reference contains more than 15 qualifying names.
    A reference to a structure element may include the names of at most 15 higher level structures.
  • MFPLI00088S A PROCEDURE reference contains more than 240 arguments.
    The maximum number of arguments in a procedure reference is 240.
  • MFPLI00089S The scale-factor specified in a conversion built-in function exceeds the implementation's limit.
    The scaling factor must not be less than minus 128 or greater than plus 127.
  • MFPLI00090W The undeclared name "identifier-name" has been declared with the default type as a variable in the current PROCEDURE.
  • MFPLI00091S "variable-name" is a non-BASED variable referenced with a locator qualifier.
    "variable-name" is referenced with a locator qualifier but is not a BASED variable.
  • MFPLI00092S "variable-name" is a BASED variable referenced without a locator qualifier.
    If a BASED variable is not declared with a locator-reference then all references to the variable must include a locator qualifier.
  • MFPLI00093S The base-reference declared for "array-name" contains more * subscripts than this reference has subscripts. This reference cannot be mapped into a valid reference to the base-variable.
  • MFPLI00094W "argument-name" has been passed via a dummy argument because its attributes did not match those of the corresponding parameter. Enclose the argument in parentheses to suppress this warning.
    The attributes of the argument argument-name and the corresponding parameter do not match and so the argument will be passed by value rather than by reference.
  • MFPLI00095S "entry-name" has been referenced with too many arguments.
    The entry "entry-name" has been declared with fewer parameters than the number of arguments specified in this reference.
  • MFPLI00096S "array-name" has been referenced with too many subscripts.
    The array "array-name" has been declared with fewer dimensions than the number of subscripts specified in this reference.
  • MFPLI00097S The precision arguments of BINARY, DECIMAL, FIXED, FLOAT, DIVIDE, MULTIPLY, ADD, and SUBTRACT built-in functions must be decimal integer constants.
    Only decimal integer constants can be specified as precision arguments to the arithmetic built-in functions.
  • MFPLI00098S "entry-name" has been referenced with an argument list which is incompatible with its declaration. An empty argument list is required to satisfy the declaration.
    "entry-name" has been declared with an empty list of parameter descriptors but this reference has included a list of one or more arguments.
  • MFPLI00099S This statement contains inconsistent FILE description attributes.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00080S Unrecognizable condition prefix name.

Parent topic: MFPLI00080 - MFPLI00099


MFPLI00081S A complex arithmetic value is required by this statement, but a noncomputational value has been used. It cannot be converted.

Parent topic: MFPLI00080 - MFPLI00099


MFPLI00082S Invalid syntax in this statement. A token-name was found where another token was expected.

Module:
PASS1.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00083S Invalid syntax in this statement. A keyword-name keyword was not found in the expected position.

Module:
PASS1.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00084S Invalid conversion. Noncomputational data cannot be converted to string or arithmetic data.

Module:
CVTPL1.PL1, INTRP2.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00085S A STRUCTURE qualified reference to "identifier-name" cannot be resolved to any declaration known to this block.

The element "identifier-name" together with its structure qualification cannot be resolved to any structure element declared in this or a containing block.
Resolution:
Correct the name of the element or its structure qualification.
Module:
RESREF.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00086S A locator-qualified reference to "identifier-name" cannot be resolved to any declaration known to this block.

The locator-qualifed reference cannot be resolved possibly because "identifier-name" is not a BASED variable.
Resolution:
Correct the locator-qualified reference.
Module:
RESREF.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00087S A STRUCTURE qualified reference contains more than 15 qualifying names.

A reference to a structure element may include the names of at most 15 higher level structures.
Resolution:
Remove any one of the qualifying names that is not essential to ensure that the reference resolves to the correct structure element.
Module:
PASS1.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00088S A PROCEDURE reference contains more than 240 arguments.

The maximum number of arguments in a procedure reference is 240.
Resolution:
Reduce the number of arguments to 240.
Module:
PASS1.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00089S The scale-factor specified in a conversion built-in function exceeds the implementation's limit.

The scaling factor must not be less than minus 128 or greater than plus 127.
Resolution:
Adjust the scaling factor to within those bounds.
Module:
INTRP2.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00090W The undeclared name "identifier-name" has been declared with the default type as a variable in the current PROCEDURE.

Parent topic: MFPLI00080 - MFPLI00099


MFPLI00091S "variable-name" is a non-BASED variable referenced with a locator qualifier.

"variable-name" is referenced with a locator qualifier but is not a BASED variable.
Resolution:
Correct the reference.
Module:
EXPEXP.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00092S "variable-name" is a BASED variable referenced without a locator qualifier.

If a BASED variable is not declared with a locator-reference then all references to the variable must include a locator qualifier.
Resolution:
Correct the reference.
Module:
PASS2.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00093S The base-reference declared for "array-name" contains more * subscripts than this reference has subscripts. This reference cannot be mapped into a valid reference to the base-variable.

Parent topic: MFPLI00080 - MFPLI00099


MFPLI00094W "argument-name" has been passed via a dummy argument because its attributes did not match those of the corresponding parameter. Enclose the argument in parentheses to suppress this warning.

The attributes of the argument argument-name and the corresponding parameter do not match and so the argument will be passed by value rather than by reference.
Resolution:
Enclose the argument in parentheses to suppress this warning.
Module:
EXPARG.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00095S "entry-name" has been referenced with too many arguments.

The entry "entry-name" has been declared with fewer parameters than the number of arguments specified in this reference.
Resolution:
Adjust the number of parameters in the declaration of "entry-name" and/or the number of arguments in the reference so that they match.
Module:
PRCSCALL.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00096S "array-name" has been referenced with too many subscripts.

The array "array-name" has been declared with fewer dimensions than the number of subscripts specified in this reference.
Resolution:
array-name.
Module:
INTRP2.PL1, PRCSCALL.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00097S The precision arguments of BINARY, DECIMAL, FIXED, FLOAT, DIVIDE, MULTIPLY, ADD, and SUBTRACT built-in functions must be decimal integer constants.

Only decimal integer constants can be specified as precision arguments to the arithmetic built-in functions.
Resolution:
If different precisions are required depending on particular conditions then use a SELECT statement to choose between evaluating expressions using the arithmetic built-in function with different integer constant precision arguments.
Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00098S "entry-name" has been referenced with an argument list which is incompatible with its declaration. An empty argument list is required to satisfy the declaration.

"entry-name" has been declared with an empty list of parameter descriptors but this reference has included a list of one or more arguments.
Resolution:
Either correct the declaration or supply an empty argument list.
Module:
PRCSCALL.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00099S This statement contains inconsistent FILE description attributes.

Module:
PASS1.PL1
Parent topic: MFPLI00080 - MFPLI00099


MFPLI00100 - MFPLI00119

  • MFPLI00100S "entry-name" has been referenced with too few arguments.
    The entry "entry-name" has been referenced with fewer arguments than the number of parameter descriptors in the declaration.
  • MFPLI00101S "entry-name" has been referenced with too many empty argument lists.
  • MFPLI00102S This statement contains duplicate options.
    The statement contains the same option more than once, for example a DO statement with two TO options.
  • MFPLI00103S Invalid option for this statement or invalid syntax in an option.
    Either an option on this statement or its syntax is invalid.
  • MFPLI00104S One of the iSUBs used in the base-reference of "variable-name" cannot be replaced by a subscript from this reference. This reference cannot be mapped into a valid reference to the base-variable.
  • MFPLI00105S The precision specified for the result of this built-in function exceeds the implementation's maximum allowed for the resulting data type.
    The precision specified for the result of this conversion built-in function is too big.
  • MFPLI00106S A reference to "array-name" contains a subscript that has not been used as a replacement for an iSUB or an asterisk in the base-reference. This reference cannot be mapped into a valid reference to the base variable.
  • MFPLI00107S "array-name" has been referenced with too few subscripts. Asterisk subscripts must be used to reference a cross-section. All subscripted references must have as many subscripts as the array has dimensions - including any inherited dimensions.
    An array reference must either have no subscript list or a list with the same number of subscripts as the number of dimensions in the declaration of the array.
  • MFPLI00108S An array or STRUCTURE value has been used in a context that requires a scalar value.
    A scalar value is required by the context, for example the control variable of a DO statement, but an aggregate value has been supplied.
  • MFPLI00109W BIT operators should only be applied to BIT operands.
  • MFPLI00110E A string constant exceeds the implementation's maximum length of length-limit. Truncation will occur.
    This implementation's maximum length for a string constant is length-limit.
  • MFPLI00111S An operation on two STRUCTUREs is possible only when both STRUCTUREs have the same number of immediate members.
  • MFPLI00112S An operation on two arrays is possible only when both arrays have the same number of dimensions and the exact same lower and upper bounds.
  • MFPLI00113S A bit-string constant contains an invalid digit following the B. Only 1, 2, 3, or 4 are permitted.
    Bit-string constants can be expressed in binary, quaternary, octal or hexadecimal.
  • MFPLI00114W %%preprocessor-statement is an unrecognizable %% statement; ignored.
    %%preprocessor-statement is not recognized as a pre-processor statement.
  • MFPLI00115S Invalid syntax in %%REPLACE statement. The correct syntax is %%REPLACE id BY c; where id is an identifier and c is: a character-string constant, a bit-string constant, or an arithmetic constant preceded by an optional minus sign.
    The syntax of the %%REPLACE statement is invalid;.
  • MFPLI00116S "constant" could not be converted to its internal representation. Check for too many digits, an exponent that is too large or too small, or an invalid character in a string constant.
  • MFPLI00117U The number of nested %%INCLUDE statements has exceeded the implementation's limit.
  • MFPLI00118S Invalid syntax in %%INCLUDE statement. The correct syntax is one of the following forms: %%INCLUDE 'string-constant'; %%INCLUDE identifier; or %%INCLUDE (identifier); or %%INCLUDE identifier(identifier);
    The syntax of the %%INCLUDE statement is invalid;.
  • MFPLI00119S The first argument to a LBOUND, HBOUND, or DIM built-in function must be an array reference.
    The LBOUND, HBOUND and DIMENSION built-in functions require an array reference as the first argument.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00100S "entry-name" has been referenced with too few arguments.

The entry "entry-name" has been referenced with fewer arguments than the number of parameter descriptors in the declaration.
Resolution:
Either correct the declaration or supply the correct number of arguments.
Module:
PRCSCALL.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00101S "entry-name" has been referenced with too many empty argument lists.

Module:
PRCSCALL.PL1 (commented out)
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00102S This statement contains duplicate options.

The statement contains the same option more than once, for example a DO statement with two TO options.
Resolution:
Remove the duplicate option.
Module:
PASS1.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00103S Invalid option for this statement or invalid syntax in an option.

Either an option on this statement or its syntax is invalid.
Resolution:
Remove or correct the option.
Module:
PASS1.PL1, PLSP1.TB
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00104S One of the iSUBs used in the base-reference of "variable-name" cannot be replaced by a subscript from this reference. This reference cannot be mapped into a valid reference to the base-variable.

Parent topic: MFPLI00100 - MFPLI00119


MFPLI00105S The precision specified for the result of this built-in function exceeds the implementation's maximum allowed for the resulting data type.

The precision specified for the result of this conversion built-in function is too big.
Resolution:
Reduce the precision to the maximum allowed for the resulting data type.
Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00106S A reference to "array-name" contains a subscript that has not been used as a replacement for an iSUB or an asterisk in the base-reference. This reference cannot be mapped into a valid reference to the base variable.

Parent topic: MFPLI00100 - MFPLI00119


MFPLI00107S "array-name" has been referenced with too few subscripts. Asterisk subscripts must be used to reference a cross-section. All subscripted references must have as many subscripts as the array has dimensions - including any inherited dimensions.

An array reference must either have no subscript list or a list with the same number of subscripts as the number of dimensions in the declaration of the array.
Resolution:
Either remove the subscript list if the entire array is required or supply the missing subscripts.
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00108S An array or STRUCTURE value has been used in a context that requires a scalar value.

A scalar value is required by the context, for example the control variable of a DO statement, but an aggregate value has been supplied.
Resolution:
Supply a scalar value instead of the aggregate value.
Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00109W BIT operators should only be applied to BIT operands.

Module:
PLSP2.TB
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00110E A string constant exceeds the implementation's maximum length of length-limit. Truncation will occur.

This implementation's maximum length for a string constant is length-limit.
Resolution:
Reduce the length of the string constant.
Module:
RESIS.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00111S An operation on two STRUCTUREs is possible only when both STRUCTUREs have the same number of immediate members.

Parent topic: MFPLI00100 - MFPLI00119


MFPLI00112S An operation on two arrays is possible only when both arrays have the same number of dimensions and the exact same lower and upper bounds.

Parent topic: MFPLI00100 - MFPLI00119


MFPLI00113S A bit-string constant contains an invalid digit following the B. Only 1, 2, 3, or 4 are permitted.

Bit-string constants can be expressed in binary, quaternary, octal or hexadecimal.
Resolution:
Express the bit-constant in one of the permitted bases.
Module:
DCLPL1.PL1, UTCNVCO.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00114W %%preprocessor-statement is an unrecognizable %% statement; ignored.

%%preprocessor-statement is not recognized as a pre-processor statement.
Resolution:
Correct the pre-processor statement.
Module:
PASS1.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00115S Invalid syntax in %%REPLACE statement. The correct syntax is %%REPLACE id BY c; where id is an identifier and c is: a character-string constant, a bit-string constant, or an arithmetic constant preceded by an optional minus sign.

The syntax of the %%REPLACE statement is invalid;.
Resolution:
Correct the syntax of the %%REPLACE statement.
Module:
PASS1.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00116S "constant" could not be converted to its internal representation. Check for too many digits, an exponent that is too large or too small, or an invalid character in a string constant.

Module:
UTCNVCO.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00117U The number of nested %%INCLUDE statements has exceeded the implementation's limit.

Parent topic: MFPLI00100 - MFPLI00119


MFPLI00118S Invalid syntax in %%INCLUDE statement. The correct syntax is one of the following forms: %%INCLUDE 'string-constant'; %%INCLUDE identifier; or %%INCLUDE (identifier); or %%INCLUDE identifier(identifier);

The syntax of the %%INCLUDE statement is invalid;.
Resolution:
Correct the syntax of the %%INCLUDE statement.
Module:
PASS1.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00119S The first argument to a LBOUND, HBOUND, or DIM built-in function must be an array reference.

The LBOUND, HBOUND and DIMENSION built-in functions require an array reference as the first argument.
Resolution:
Correct the first argument.
Module:
INTRP2.PL1
Parent topic: MFPLI00100 - MFPLI00119


MFPLI00120 - MFPLI00139

  • MFPLI00120S Invalid dimension specified in HBOUND, LBOUND, or DIM.
    If the first argument to the LBOUND, HBOUND or DIMENSION built-in function is a one-dimensional array reference the second argument is optional.
  • MFPLI00121W The INITIAL attribute specified for "array-name" contains fewer values than are required to fully initialize the variable.
    Some elements of the array "array-name" have been left uninitialized by the INITIAL attribute.
  • MFPLI00122S The ALLOCATION built-in function must reference a non-member CONTROLLED variable.
    Either the argument to the ALLOCATION built-in function is not a CONTROLLED variable or it is an element of a CONTROLLED array or a member of a CONTROLLED structure.
  • MFPLI00123S Addition of POINTERs is invalid.
    Under normal circumstances it does not make sense to add POINTERs.
  • MFPLI00124S One of the initial values specified for "array-name" cannot be converted to this variable type.
  • MFPLI00125S More than 240 operands have been used with an operator, function, or call.
  • MFPLI00126E Excess initial values have been specified for "array-name".
    More values have been specified in the INITIAL attribute than there are elements in the array "array-name".
  • MFPLI00127S Invalid picture picture-specification.
  • MFPLI00128S "constant" specifies more than 15 decimal digits.
  • MFPLI00129S The picture specification "picture-specification" results in a compiled picture that exceeds the implementation limit. Reduce the size of the picture and recompile.
  • MFPLI00130S The picture specification "picture-specification" contains a field of more than 255 characters.
  • MFPLI00131S The picture specification "picture-specification" contains multiple sign symbols.
  • MFPLI00132E "identifier-name" is declared as AUTOMATIC but is outside the scope of any PROCEDURE. It has been changed to STATIC. If no previous errors were diagnosed, contact Micro Focus Support Line.
    Variables declared in a PACKAGE but outside the scope of any PROCEDURE cannot be AUTOMATIC.
  • MFPLI00133U The nesting level of DO, PROCEDURE, and BEGIN statements exceeds the implementation's limit.
  • MFPLI00134S One of the targets of this assignment is not a variable or pseudovariable reference.
  • MFPLI00135S BY NAME expansion is invalid because the left-most target of the assignment is a STRUCTURE that contains more than 20 elementary members.
  • MFPLI00136S A reference to the function "entry-name" would return a STRUCTURE or an array value but the returns type of the function was not declared with the TYPE attribute.
    A function can be declared to return an aggregate value only by using the TYPE attribute in the RETURNS option.
  • MFPLI00137S A subscript is out-of-range in this statement.
    The compiler option "-prefix subscriptrange" (or the deprecated option "-range") is in effect and a subscript is not between the lower and upper bound of the corresponding dimension.
  • MFPLI00138W "entry-name" is a function that has been called by a CALL statement.
    Entries declared with the RETURNS attribute must be invoked by a function reference either used in an expression or as the source of an assignment.
  • MFPLI00139W "entry-name" is a subroutine that has been called as a function.
    Entries invoked by a function reference must have the RETURNS attribute.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00120S Invalid dimension specified in HBOUND, LBOUND, or DIM.

If the first argument to the LBOUND, HBOUND or DIMENSION built-in function is a one-dimensional array reference the second argument is optional.

If a second argument is specified it must be a positive integer not greater than the number of dimensions.

Resolution:
Correct the second argument.
Module:
INTRP2.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00121W The INITIAL attribute specified for "array-name" contains fewer values than are required to fully initialize the variable.

Some elements of the array "array-name" have been left uninitialized by the INITIAL attribute.
Resolution:
Supply the missing values to avoid the message.
Module:
AISCLR.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00122S The ALLOCATION built-in function must reference a non-member CONTROLLED variable.

Either the argument to the ALLOCATION built-in function is not a CONTROLLED variable or it is an element of a CONTROLLED array or a member of a CONTROLLED structure.
Resolution:
Correct the argument to the ALLOCATION built-in function.
Module:
INTRP2.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00123S Addition of POINTERs is invalid.

Under normal circumstances it does not make sense to add POINTERs.
Resolution:
Under abnormal circumstances addition of pointers x and y can be obtained by PTRVALUE ( BINVALUE (x) + BINVALUE (y)).
Module:
PLSP2.TB
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00124S One of the initial values specified for "array-name" cannot be converted to this variable type.

Module:
AISCLR.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00125S More than 240 operands have been used with an operator, function, or call.

Module:
PASS1.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00126E Excess initial values have been specified for "array-name".

More values have been specified in the INITIAL attribute than there are elements in the array "array-name".
Resolution:
Reduce the number of values in the INITIAL attribute to the number of element in the array.
Module:
ALIVAL.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00127S Invalid picture picture-specification.

Module:
DCLPIC.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00128S "constant" specifies more than 15 decimal digits.

Parent topic: MFPLI00120 - MFPLI00139


MFPLI00129S The picture specification "picture-specification" results in a compiled picture that exceeds the implementation limit. Reduce the size of the picture and recompile.

Module:
DCLPIC.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00130S The picture specification "picture-specification" contains a field of more than 255 characters.

Module:
DCLPIC.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00131S The picture specification "picture-specification" contains multiple sign symbols.

Module:
DCLPIC.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00132E "identifier-name" is declared as AUTOMATIC but is outside the scope of any PROCEDURE. It has been changed to STATIC. If no previous errors were diagnosed, contact Micro Focus Support Line.

Variables declared in a PACKAGE but outside the scope of any PROCEDURE cannot be AUTOMATIC.
Resolution:
Change the storage class of "identifier-name" to STATIC, BASED or CONTROLLED.
Module:
DCLPCS.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00133U The nesting level of DO, PROCEDURE, and BEGIN statements exceeds the implementation's limit.

Module:
PASS1.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00134S One of the targets of this assignment is not a variable or pseudovariable reference.

Module:
VALASS.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00135S BY NAME expansion is invalid because the left-most target of the assignment is a STRUCTURE that contains more than 20 elementary members.

Parent topic: MFPLI00120 - MFPLI00139


MFPLI00136S A reference to the function "entry-name" would return a STRUCTURE or an array value but the returns type of the function was not declared with the TYPE attribute.

A function can be declared to return an aggregate value only by using the TYPE attribute in the RETURNS option.
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00137S A subscript is out-of-range in this statement.

The compiler option "-prefix subscriptrange" (or the deprecated option "-range") is in effect and a subscript is not between the lower and upper bound of the corresponding dimension.
Resolution:
Correct the subscript.
Module:
EVAL.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00138W "entry-name" is a function that has been called by a CALL statement.

Entries declared with the RETURNS attribute must be invoked by a function reference either used in an expression or as the source of an assignment.
Resolution:
Invoke the function "entry-name" by assigning the reference to a variable that can hold the returned value.
Module:
INTRP2.PL1, PRCSCALL.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00139W "entry-name" is a subroutine that has been called as a function.

Entries invoked by a function reference must have the RETURNS attribute.
Resolution:
Invoke the the subroutine "entry-name" by a CALL statement.
Module:
PRCSCALL.PL1
Parent topic: MFPLI00120 - MFPLI00139


MFPLI00140 - MFPLI00159

  • MFPLI00140U The size of a dope-vector exceeds the implementation's limit. Either eliminate the use of * extents in this ENTRY point, or pass STRUCTUREs by passing a POINTER to them.
    The size of a dope-vector exceeds the implementation's limit.
  • MFPLI00141W "parameter-name" is an undeclared parameter. It has been declared in its containing block and will acquire default attributes.
    Parameters listed in an internal procedure parameter list must be declared within that procedure.
  • MFPLI00142W "entry-name" has been declared with a RETURNS attribute but no ENTRY attribute. An ENTRY attribute has been supplied.
    The ENTRY attribute, without a parameter descriptor list, is implied by the RETURNS attribute.
  • MFPLI00143W "variable-name" has been declared without a data type. The default type has been supplied.
    The default data type has been supplied for "variable-name", declared without a data type.
  • MFPLI00144W "variable-name" has been declared with a nonzero scale-factor. A zero scale-factor has been supplied.
    Fixed-point binary numbers with fractional parts are not supported.
  • MFPLI00145W The INITIAL attribute specified for "variable-name" cannot be applied to variables of this storage class; INITIAL attribute ignored.
    Defined and parameter variables do not have their own storage and so cannot be initialized.
  • MFPLI00146S All functions must have a return descriptor with constant size.
    Functions may not return strings with adjustable lengths or AREAs with adjustable sizes.
  • MFPLI00147S "array-name" is an ENTRY or FILE constant and as such it cannot be declared with a DIMENSION attribute.
    Although arrays of ENTRY and FILE VARIABLEs are permitted, ENTRY and FILE constants must be scalars.
  • MFPLI00148S An expected optionally signed short integer was not found.
  • MFPLI00149S "array-name" has been declared with mixed asterisk and constant bounds. If any bound is an asterisk, all bounds must be asterisks.
  • MFPLI00150S "variable-name" has been declared FLOAT with a scale-factor. The scale-factor will be ignored.
    Scaling factors are only used for fixed-point variables.
  • MFPLI00151S "variable-name" has been declared with a negative size. A size of one has been supplied.
    Strings must not have negative lengths and AREAs must not have negative sizes.
  • MFPLI00152S "variable-name" is undeclared and has been used in an ALLOCATE or LOCATE statement as the name of a BASED or CONTROLLED variable.
    Variables cannot be implicitly declared as BASED or CONTROLLED.
  • MFPLI00153S "variable-name" cannot be allocated because no SET option or implied SET option is available.
    The SET option was not specified in the declaration of "variable-name" nor on the ALLOCATE or LOCATE statement.
  • MFPLI00154S "variable-name" cannot be allocated because no IN option or implied IN option is available.
  • MFPLI00155S "variable-name" cannot be allocated because the SET option or implied SET option does not reference a POINTER or OFFSET variable.
    Either a POINTER or OFFSET variable must be specified in the SET option in the declaration of a BASED variable or in the SET option on the ALLOCATE or LOCATE statement.
  • MFPLI00156E An ALLOCATE statement for the CONTROLLED variable "variable-name" cannot specify the SET option. The SET option has been ignored.
    The SET option may only be specified on ALLOCATE statements for BASED variables.
  • MFPLI00157S "variable-name" cannot be allocated because it is neither a BASED nor a CONTROLLED variable. Only BASED or CONTROLLED non-member variables can be allocated by an ALLOCATE statement.
    Only BASED and CONTROLLED variables can be allocated and "variable-name" is neither BASED nor CONTROLLED.
  • MFPLI00158S All RETURN statements in a function must return values.
  • MFPLI00159S A RETURN statement in a subroutine cannot return a value.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00140U The size of a dope-vector exceeds the implementation's limit. Either eliminate the use of * extents in this ENTRY point, or pass STRUCTUREs by passing a POINTER to them.

The size of a dope-vector exceeds the implementation's limit.
Resolution:
Either eliminate the use of * extents in this ENTRY point, or pass STRUCTUREs by passing a POINTER to them.
Module:
MAKEDO.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00141W "parameter-name" is an undeclared parameter. It has been declared in its containing block and will acquire default attributes.

Parameters listed in an internal procedure parameter list must be declared within that procedure.

The declaration of "parameter-name" in the containing block will not be used.

Resolution:
Move the declaration of the parameter within the procedure to which it is a parameter.
Module:
DCLPCS.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00142W "entry-name" has been declared with a RETURNS attribute but no ENTRY attribute. An ENTRY attribute has been supplied.

The ENTRY attribute, without a parameter descriptor list, is implied by the RETURNS attribute.
Resolution:
Additionally specify the ENTRY attribute.
Module:
DCLPCS.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00143W "variable-name" has been declared without a data type. The default type has been supplied.

The default data type has been supplied for "variable-name", declared without a data type.
Resolution:
Supply the required data type.
Module:
DCLPCS.PL1, EXPTYP.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00144W "variable-name" has been declared with a nonzero scale-factor. A zero scale-factor has been supplied.

Fixed-point binary numbers with fractional parts are not supported.
Resolution:
Use floating-point if binary numbers with fractional parts are needed.
Module:
DCLPCS.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00145W The INITIAL attribute specified for "variable-name" cannot be applied to variables of this storage class; INITIAL attribute ignored.

Defined and parameter variables do not have their own storage and so cannot be initialized.
Resolution:
Remove the INITIAL attribute from "variable-name".
Module:
DCLPCS.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00146S All functions must have a return descriptor with constant size.

Functions may not return strings with adjustable lengths or AREAs with adjustable sizes.
Resolution:
Specify constant string lengths or AREA sizes in RETURN descriptors.
Module:
DCLREE.PL1, INTRP2.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00147S "array-name" is an ENTRY or FILE constant and as such it cannot be declared with a DIMENSION attribute.

Although arrays of ENTRY and FILE VARIABLEs are permitted, ENTRY and FILE constants must be scalars.
Resolution:
Remove the DIMENSION attribute.
Module:
DCLPCS.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00148S An expected optionally signed short integer was not found.

Module:
PASS1.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00149S "array-name" has been declared with mixed asterisk and constant bounds. If any bound is an asterisk, all bounds must be asterisks.

Module:
DCLPCS.PL1 (commented out)
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00150S "variable-name" has been declared FLOAT with a scale-factor. The scale-factor will be ignored.

Scaling factors are only used for fixed-point variables.
Resolution:
Remove the scaling factor.
Module:
DCLPCS.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00151S "variable-name" has been declared with a negative size. A size of one has been supplied.

Strings must not have negative lengths and AREAs must not have negative sizes.
Resolution:
Correct the size of "variable-name".
Module:
DCLPCS.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00152S "variable-name" is undeclared and has been used in an ALLOCATE or LOCATE statement as the name of a BASED or CONTROLLED variable.

Variables cannot be implicitly declared as BASED or CONTROLLED.
Resolution:
Explicitly declare the BASED or CONTROLLED variable "variable-name".
Module:
CTLALL.PL1, INTRP2.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00153S "variable-name" cannot be allocated because no SET option or implied SET option is available.

The SET option was not specified in the declaration of "variable-name" nor on the ALLOCATE or LOCATE statement.
Resolution:
Supply the SET option in the declaration of "variable-name" or on the ALLOCATE or LOCATE statement.
Module:
INTRP2.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00154S "variable-name" cannot be allocated because no IN option or implied IN option is available.

Parent topic: MFPLI00140 - MFPLI00159


MFPLI00155S "variable-name" cannot be allocated because the SET option or implied SET option does not reference a POINTER or OFFSET variable.

Either a POINTER or OFFSET variable must be specified in the SET option in the declaration of a BASED variable or in the SET option on the ALLOCATE or LOCATE statement.
Resolution:
Supply a POINTER or OFFSET variable in the SET option in the declaration of "variable-name" or on the ALLOCATE or LOCATE statement.
Module:
INTRP2.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00156E An ALLOCATE statement for the CONTROLLED variable "variable-name" cannot specify the SET option. The SET option has been ignored.

The SET option may only be specified on ALLOCATE statements for BASED variables.
Resolution:
Remove the SET option from the ALLOCATE statement for the CONTROLLED variable "variable-name".
Module:
INTRP2.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00157S "variable-name" cannot be allocated because it is neither a BASED nor a CONTROLLED variable. Only BASED or CONTROLLED non-member variables can be allocated by an ALLOCATE statement.

Only BASED and CONTROLLED variables can be allocated and "variable-name" is neither BASED nor CONTROLLED.
Resolution:
Either declare "variable-name" as BASED or CONTROLLED or remove the ALLOCATE statement.
Module:
INTRP2.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00158S All RETURN statements in a function must return values.

Module:
INTRP2.PL1, OPTMIZ.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00159S A RETURN statement in a subroutine cannot return a value.

Module:
INTRP2.PL1
Parent topic: MFPLI00140 - MFPLI00159


MFPLI00160 - MFPLI00179

  • MFPLI00160S A RETURN statement cannot be contained within an on-unit.
  • MFPLI00161S A FREE statement must free a nonmember BASED or CONTROLLED variable.
  • MFPLI00162E In order to prevent the creation of an array whose elements are of unequal length, a default length of 128 has been used for the element length of an array temporary.
  • MFPLI00163S A RETURNS option or attribute must specify a scalar, array, or STRUCTURE. It cannot specify a list of values. Check for missing or incorrect level-numbers.
  • MFPLI00164S Invalid conversion required by an assignment or RETURN statement.
  • MFPLI00165S "insert-name" is declared as TYPE(x), but the declaration of "x" contains a REFER option which refers to a variable outside of "x". All REFER options in a type definition can refer only to other members within the definition.
  • MFPLI00166S Subscripts are not valid in the reference of a REFER option. The referenced variable must not be an array or member of a dimensioned STRUCTURE.
  • MFPLI00167E "entry-name" is not a built-in function known to this implementation. If this is an EXTERNAL ENTRY, it should be properly declared. ENTRY EXTERNAL is assumed.
  • MFPLI00168S The argument of ADDR must be a reference to a variable.
  • MFPLI00169S A built-in function that produces a floating-point result cannot specify a scale-factor.
  • MFPLI00170S "insert-name" is declared as TYPE(x), but the declaration of "x" (or one of its members) contains an invalid REFER option. The REFER option refers to a variable which is not contained within same level-1 STRUCTURE as "x".
  • MFPLI00171S The argument of UNSPEC must be a scalar, array, STRUCTURE, or UNION expression. Function return values and NONCONNECTED arrays are not supported as an argument to UNSPEC.
  • MFPLI00172W ADDR of an unaligned BIT variable does not materialize a possible bit address.
    The argument of ADDR cannot be a bit-string that is not aligned on a byte boundary.
  • MFPLI00173S Possible compiler error. PASS2 attempted to free an already freed value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
  • MFPLI00174S The operands of ^<, ^>, >, <, >=, or <= must be real arithmetic or string values.
  • MFPLI00175U The declaration of "insert-name" specifies a locator that depends on the original symbol, causing a circular reference in the declaration.
  • MFPLI00176W "insert-name" used in an INTO or FROM option might not be byte-aligned.
  • MFPLI00177S The name given in an I/O condition must be the name of a FILE value.
  • MFPLI00178S The number of single-bytes in a W or G string constant should be a multiple of 2.
  • MFPLI00179S The INTO option must be specified on a READ statement.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00160S A RETURN statement cannot be contained within an on-unit.

Module:
INTRP2.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00161S A FREE statement must free a nonmember BASED or CONTROLLED variable.

Module:
INTRP2.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00162E In order to prevent the creation of an array whose elements are of unequal length, a default length of 128 has been used for the element length of an array temporary.

Parent topic: MFPLI00160 - MFPLI00179


MFPLI00163S A RETURNS option or attribute must specify a scalar, array, or STRUCTURE. It cannot specify a list of values. Check for missing or incorrect level-numbers.

Module:
DCLPCS.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00164S Invalid conversion required by an assignment or RETURN statement.

Module:
INTRP2.PL1, VALASS.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00165S "insert-name" is declared as TYPE(x), but the declaration of "x" contains a REFER option which refers to a variable outside of "x". All REFER options in a type definition can refer only to other members within the definition.

Module:
EXPTYP.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00166S Subscripts are not valid in the reference of a REFER option. The referenced variable must not be an array or member of a dimensioned STRUCTURE.

Parent topic: MFPLI00160 - MFPLI00179


MFPLI00167E "entry-name" is not a built-in function known to this implementation. If this is an EXTERNAL ENTRY, it should be properly declared. ENTRY EXTERNAL is assumed.

Module:
EXPEXP.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00168S The argument of ADDR must be a reference to a variable.

Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00169S A built-in function that produces a floating-point result cannot specify a scale-factor.

Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00170S "insert-name" is declared as TYPE(x), but the declaration of "x" (or one of its members) contains an invalid REFER option. The REFER option refers to a variable which is not contained within same level-1 STRUCTURE as "x".

Resolution:
Try using a fully qualified reference in the REFER option in the declaration of "x".
Module:
EXPTYP.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00171S The argument of UNSPEC must be a scalar, array, STRUCTURE, or UNION expression. Function return values and NONCONNECTED arrays are not supported as an argument to UNSPEC.

Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00172W ADDR of an unaligned BIT variable does not materialize a possible bit address.

The argument of ADDR cannot be a bit-string that is not aligned on a byte boundary.
Resolution:
Ensure the bit-string argument of ADDR is aligned on a byte boundary.
Module:
INTRP2.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00173S Possible compiler error. PASS2 attempted to free an already freed value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Module:
FREEVL.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00174S The operands of ^<, ^>, >, <, >=, or <= must be real arithmetic or string values.

Module:
INTRP2.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00175U The declaration of "insert-name" specifies a locator that depends on the original symbol, causing a circular reference in the declaration.

Module:
EXPEXP.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00176W "insert-name" used in an INTO or FROM option might not be byte-aligned.

Module:
INTRP2.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00177S The name given in an I/O condition must be the name of a FILE value.

Module:
INTRP2.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00178S The number of single-bytes in a W or G string constant should be a multiple of 2.

Module:
LEXSTATE.IN
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00179S The INTO option must be specified on a READ statement.

Module:
INTRP2.PL1
Parent topic: MFPLI00160 - MFPLI00179


MFPLI00180 - MFPLI00199

  • MFPLI00180S The FROM option must be specified on a WRITE or REWRITE statement.
  • MFPLI00181S Declaration of "insert-name" exceeds the nesting limit for the use of TYPE. Redeclare this variable (or one of the variables on which it depends) without using TYPE.
  • MFPLI00182S The typed variable "insert-name" can only have those members which it inherits from the type definition. Additional substructures or members cannot be added to the created STRUCTURE.
  • MFPLI00183S "insert-name" is declared with TYPE(x) but "x" does not resolve to a declaration of a variable. A type definition cannot be a parameter, a built-in function, or a named constant (such as FILE, ENTRY, or LABEL).
  • MFPLI00184S "insert-name" is declared with the TYPE attribute; TYPE must not be used with any of: PICTURE, FIXED, FLOAT, BINARY, DECIMAL, CHARACTER, BIT, ALIGNED, VARYING, POINTER, ENTRY, LABEL, FILE, or UNION.
  • MFPLI00185S "insert-name" is declared as TYPE(x) and with dimensions; the declaration with TYPE or the type definition "x" can be an array, but not both.
  • MFPLI00186S "variable-name" is declared as TYPE(x), but "x" is also declared with TYPE. A declaration used as a type definition cannot itself use the TYPE attribute (its members can use TYPE, however).
    A DEFINE ALIAS statement cannot use the TYPE attribute.
  • MFPLI00187S The declaration of "variable-name" is part of a circular use of the TYPE attribute. The declaration either directly or indirectly depends on itself. The type dependency graph must be a "tree".
  • MFPLI00188S "insert-name" is declared as TYPE(x) but "x" is a POINTER qualified or subscripted reference. The reference to the type definition in a TYPE attribute must not be POINTER qualified or subscripted.
  • MFPLI00189S "variable-name" is declared with the TYPE attribute but the type definition uses a non-constant extent for a string length or an array bound.
    A type definition using non-constant extents cannot be used for a parameter, for a parameter ENTRY descriptor, or for a function returns descriptor.
  • MFPLI00190S "insert-name" has been declared as TYPE(x) but "x" has not been declared. The declaration has been left without a data type.
  • MFPLI00191S Excess initial values have been specified for "insert-name".
  • MFPLI00192S Incomplete attributes have been specified for "insert-name".
  • MFPLI00193S "insert-name" is declared as TYPE(x), but "x" is a member of a STRUCTURE declared with TYPE. A type definition must not be a member of a STRUCTURE declared with TYPE.
  • MFPLI00194S An array bound, string length, repeat factor or OFFSET was specified with an invalid constant. A value of 1 is being supplied.
  • MFPLI00195S "insert-name" has been declared with a length greater than 32767. A length of 32767 has been supplied.
  • MFPLI00196S "insert-name" has been declared with an invalid iteration factor. The iteration factor must be an integer value between 1 and 2**31. An iteration factor of 1 has been supplied.
  • MFPLI00197S "insert-name" has been declared with a nonconstant initial value. STATIC variables must have constant initial values.
  • MFPLI00198S "insert-name" has been declared with an INITIAL attribute containing more than 32 levels of nesting.
  • MFPLI00199S The INITIAL value specified for "insert-name" exceeds the implementation limit.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00180S The FROM option must be specified on a WRITE or REWRITE statement.

Module:
INTRP2.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00181S Declaration of "insert-name" exceeds the nesting limit for the use of TYPE. Redeclare this variable (or one of the variables on which it depends) without using TYPE.

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00182S The typed variable "insert-name" can only have those members which it inherits from the type definition. Additional substructures or members cannot be added to the created STRUCTURE.

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00183S "insert-name" is declared with TYPE(x) but "x" does not resolve to a declaration of a variable. A type definition cannot be a parameter, a built-in function, or a named constant (such as FILE, ENTRY, or LABEL).

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00184S "insert-name" is declared with the TYPE attribute; TYPE must not be used with any of: PICTURE, FIXED, FLOAT, BINARY, DECIMAL, CHARACTER, BIT, ALIGNED, VARYING, POINTER, ENTRY, LABEL, FILE, or UNION.

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00185S "insert-name" is declared as TYPE(x) and with dimensions; the declaration with TYPE or the type definition "x" can be an array, but not both.

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00186S "variable-name" is declared as TYPE(x), but "x" is also declared with TYPE. A declaration used as a type definition cannot itself use the TYPE attribute (its members can use TYPE, however).

A DEFINE ALIAS statement cannot use the TYPE attribute.
Resolution:
Try changing the declaration of "variable-name" from TYPE(x) to TYPE(y), where "y" is the variable referenced in the TYPE attribute in the declaration of "x".
Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00187S The declaration of "variable-name" is part of a circular use of the TYPE attribute. The declaration either directly or indirectly depends on itself. The type dependency graph must be a "tree".

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00188S "insert-name" is declared as TYPE(x) but "x" is a POINTER qualified or subscripted reference. The reference to the type definition in a TYPE attribute must not be POINTER qualified or subscripted.

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00189S "variable-name" is declared with the TYPE attribute but the type definition uses a non-constant extent for a string length or an array bound.

A type definition using non-constant extents cannot be used for a parameter, for a parameter ENTRY descriptor, or for a function returns descriptor.
Resolution:
Either declare "variable-name" without the TYPE attribute or ensure the type definition uses constant extents.
Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00190S "insert-name" has been declared as TYPE(x) but "x" has not been declared. The declaration has been left without a data type.

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00191S Excess initial values have been specified for "insert-name".

Parent topic: MFPLI00180 - MFPLI00199


MFPLI00192S Incomplete attributes have been specified for "insert-name".

Module:
DCLPCS.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00193S "insert-name" is declared as TYPE(x), but "x" is a member of a STRUCTURE declared with TYPE. A type definition must not be a member of a STRUCTURE declared with TYPE.

Module:
EXPTYP.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00194S An array bound, string length, repeat factor or OFFSET was specified with an invalid constant. A value of 1 is being supplied.

Module:
PASS1.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00195S "insert-name" has been declared with a length greater than 32767. A length of 32767 has been supplied.

Module:
DCLPCS.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00196S "insert-name" has been declared with an invalid iteration factor. The iteration factor must be an integer value between 1 and 2**31. An iteration factor of 1 has been supplied.

Module:
DCLREE.PL1, PASS1.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00197S "insert-name" has been declared with a nonconstant initial value. STATIC variables must have constant initial values.

Module:
ANEXTV.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00198S "insert-name" has been declared with an INITIAL attribute containing more than 32 levels of nesting.

Parent topic: MFPLI00180 - MFPLI00199


MFPLI00199S The INITIAL value specified for "insert-name" exceeds the implementation limit.

Module:
AISCLR.PL1
Parent topic: MFPLI00180 - MFPLI00199


MFPLI00200 - MFPLI00219

  • MFPLI00200W Possible compiler error. PASS2 has insert-name unclaimed nodes. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
  • MFPLI00201S A reference to the function "entry-name" would return a STRUCTURE or array value but the declaration of the aggregate type returned contains non-constant extents.
    Functions can be declared to return an aggregate by using the TYPE attribute in the RETURNS option only if the referenced type definition contains only constant extents.
  • MFPLI00202S A value used in this statement cannot be converted to the data type required by the context in which it is used.
  • MFPLI00203S The argument of the STRING built-in function must be a variable that is suitable for string overlay defining, must contain only BIT or CHARACTER data, and must not be ALIGNED.
  • MFPLI00204S The 2nd argument of the LBOUND, HBOUND, or DIM built-in function must be an integer constant.
    The 2nd arguments to these built-in functions must be integer constants.
  • MFPLI00205W The declaration of the named constant "constant-name" requires an unexpected conversion. If this is intended, this diagnostic can be ignored.
    The constant type in the VALUE clause does not match the type of the named constant.
  • MFPLI00206S "insert-name" has been declared with the ALIGNED attribute. Only BIT or CHARACTER string variables may be declared ALIGNED.
  • MFPLI00207S "variable-name" has been declared with the VARYING attribute. Only CHARACTER string variables may be declared VARYING.
    The VARYING attribute is not supported for BIT strings.
  • MFPLI00208S The scale-factor of FIXED BINARY values must be zero.
  • MFPLI00209I Scaled BINARY is not supported. The divide operator when applied to FIXED BINARY data will produce an integer result. Use the DIVIDE BUILTIN if you wish to obtain a scaled result.
  • MFPLI00210I Open PL/I does not support scaled FIXED BINARY; expressions containing BINARY and scaled DECIMAL operands produce a scaled DECIMAL result. Use the DECIMAL BUILTIN to avoid this message.
  • MFPLI00211S Assignment of arrays or STRUCTUREs is only valid if both sides of the assignment have identical size, shape, and component data types.
  • MFPLI00212S Multiple labels on a statement are not permitted. To achieve the effect of multiple labels on any statement except PROCEDURE, ENTRY, or FORMAT, write L1:; L2:; statement; do not put labels on a THEN, ELSE, or ON.
  • MFPLI00213E String constants used with repetition factors in an INITIAL attribute must be enclosed in parentheses in order to be compatible with standard PL/I.
  • MFPLI00214S The PACKAGE statement (if used) must be the first statement in a compilation module.
  • MFPLI00215S The level number for a STRUCTURE member is invalid. Level numbers must be integer constants between 1 and 32767.
  • MFPLI00216S A precision value in this statement is too large or is negative.
  • MFPLI00217S Data list names must not be subscripted on input.
  • MFPLI00218E The magnitude of an array bound exceeds the implementation limit of 2**31. A value of 1 is being supplied.
  • MFPLI00219E PROCEDURE insert-name is declared with the EXTERNAL attribute, but is an INTERNAL PROCEDURE. The EXTERNAL has been ignored.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00200W Possible compiler error. PASS2 has insert-name unclaimed nodes. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Module:
PASS2.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00201S A reference to the function "entry-name" would return a STRUCTURE or array value but the declaration of the aggregate type returned contains non-constant extents.

Functions can be declared to return an aggregate by using the TYPE attribute in the RETURNS option only if the referenced type definition contains only constant extents.
Resolution:
Ensure the referenced type definition contains only constant extents.
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00202S A value used in this statement cannot be converted to the data type required by the context in which it is used.

Module:
CVTPL1.PL1, INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00203S The argument of the STRING built-in function must be a variable that is suitable for string overlay defining, must contain only BIT or CHARACTER data, and must not be ALIGNED.

Module:
RESIS.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00204S The 2nd argument of the LBOUND, HBOUND, or DIM built-in function must be an integer constant.

The 2nd arguments to these built-in functions must be integer constants.
Resolution:
Depending on the value of the expression invoke the built-in function with different constant 2nd arguments.
Module:
INTRP2.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00205W The declaration of the named constant "constant-name" requires an unexpected conversion. If this is intended, this diagnostic can be ignored.

The constant type in the VALUE clause does not match the type of the named constant.
Resolution:
Check the declaration of the named constant to be sure this is intended. Usually these types match.
Module:
DCLPCS.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00206S "insert-name" has been declared with the ALIGNED attribute. Only BIT or CHARACTER string variables may be declared ALIGNED.

Parent topic: MFPLI00200 - MFPLI00219


MFPLI00207S "variable-name" has been declared with the VARYING attribute. Only CHARACTER string variables may be declared VARYING.

The VARYING attribute is not supported for BIT strings.
Resolution:
Remove the VARYING attribute and maintain a separate variable holding the length of the BIT string currently in use.
Module:
DCLPCS.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00208S The scale-factor of FIXED BINARY values must be zero.

Module:
CVTPL1.PL1, INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00209I Scaled BINARY is not supported. The divide operator when applied to FIXED BINARY data will produce an integer result. Use the DIVIDE BUILTIN if you wish to obtain a scaled result.

Module:
RESIS.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00210I Open PL/I does not support scaled FIXED BINARY; expressions containing BINARY and scaled DECIMAL operands produce a scaled DECIMAL result. Use the DECIMAL BUILTIN to avoid this message.

Module:
INTRP2.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00211S Assignment of arrays or STRUCTUREs is only valid if both sides of the assignment have identical size, shape, and component data types.

Module:
VALASS.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00212S Multiple labels on a statement are not permitted. To achieve the effect of multiple labels on any statement except PROCEDURE, ENTRY, or FORMAT, write L1:; L2:; statement; do not put labels on a THEN, ELSE, or ON.

Parent topic: MFPLI00200 - MFPLI00219


MFPLI00213E String constants used with repetition factors in an INITIAL attribute must be enclosed in parentheses in order to be compatible with standard PL/I.

Parent topic: MFPLI00200 - MFPLI00219


MFPLI00214S The PACKAGE statement (if used) must be the first statement in a compilation module.

Module:
PLSP1.TB
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00215S The level number for a STRUCTURE member is invalid. Level numbers must be integer constants between 1 and 32767.

Module:
PASS1.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00216S A precision value in this statement is too large or is negative.

Module:
PASS1.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00217S Data list names must not be subscripted on input.

Module:
INTRP2.PL1, PASS1.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00218E The magnitude of an array bound exceeds the implementation limit of 2**31. A value of 1 is being supplied.

Module:
DCLREE.PL1, PASS1.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00219E PROCEDURE insert-name is declared with the EXTERNAL attribute, but is an INTERNAL PROCEDURE. The EXTERNAL has been ignored.

Module:
PASS1.PL1
Parent topic: MFPLI00200 - MFPLI00219


MFPLI00220 - MFPLI00239

  • MFPLI00220S "insert-name" is a label variable and as such cannot be used as a label prefix. Remove the DECLARE statement that declared the label variable.
  • MFPLI00221S A XN or XU hexadecimal constant contains illegal characters or too many significant digits.
  • MFPLI00222S 'insert-name' must have an INITIAL((n)EMPTY) attribute, where n is the number of elements in the array.
  • MFPLI00223S An asterisk cannot be used as a subscript.
  • MFPLI00224E insert-name is an AUTOMATIC variable initialized in prologue of its block to an uninitialized AUTOMATIC variable declared in the same block.
  • MFPLI00225W The AUTOMATIC storage initialization of insert-name has ordering dependencies in the prologue of its declared block which cannot be guaranteed.
  • MFPLI00226W An arithmetic operation with a FIXED DECIMALinsert-name operand will be converted to FIXED BINARY(31); significant digits may be lost.
  • MFPLI00227S Too many MAIN parameters for insert-name.
  • MFPLI00228S MAIN parameter insert-name must be a scalar of POINTER type.
  • MFPLI00229S MAIN parameter insert-name must be a scalar of CHAR VAR type without * extents.
  • MFPLI00230S A WIDECHAR or GRAPHIC string has been declared with a negative repetition factor, or the resulting string length exceeds 16383.
  • MFPLI00231S A format's repeat field, w field, or d field is negative or exceeds the implementation's limit.
  • MFPLI00232S A format has a missing field.
  • MFPLI00233S Possible compiler error. A P-format or a R-format without the appropriate operand. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
  • MFPLI00234S A complex variable cannot be used as an index of a DO statement.
  • MFPLI00235S The STRING and SKIP options are incompatible.
    The SKIP option can only be specified for STREAM files and not for GET or PUT statements transmitting to or from a character string.
  • MFPLI00236S The STRING and LINE options are incompatible.
    The LINE option can only be specified for PRINT files and not for PUT statements transmitting to a character string.
  • MFPLI00237S The STRING and PAGE options are incompatible.
    The PAGE option can only be specified for PRINT files and not for PUT statements transmitting to a character string.
  • MFPLI00238S A Built-in function or concatenation produced a result string whose length exceeds 32767 or is negative.
  • MFPLI00239S Missing FILE option.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00220S "insert-name" is a label variable and as such cannot be used as a label prefix. Remove the DECLARE statement that declared the label variable.

Parent topic: MFPLI00220 - MFPLI00239


MFPLI00221S A XN or XU hexadecimal constant contains illegal characters or too many significant digits.

Module:
LEXSTATE.IN
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00222S 'insert-name' must have an INITIAL((n)EMPTY) attribute, where n is the number of elements in the array.

Parent topic: MFPLI00220 - MFPLI00239


MFPLI00223S An asterisk cannot be used as a subscript.

Parent topic: MFPLI00220 - MFPLI00239


MFPLI00224E insert-name is an AUTOMATIC variable initialized in prologue of its block to an uninitialized AUTOMATIC variable declared in the same block.

Module:
DCLPL1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00225W The AUTOMATIC storage initialization of insert-name has ordering dependencies in the prologue of its declared block which cannot be guaranteed.

Module:
DCLPL1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00226W An arithmetic operation with a FIXED DECIMALinsert-name operand will be converted to FIXED BINARY(31); significant digits may be lost.

Parent topic: MFPLI00220 - MFPLI00239


MFPLI00227S Too many MAIN parameters for insert-name.

Module:
DCLPL1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00228S MAIN parameter insert-name must be a scalar of POINTER type.

Module:
DCLPL1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00229S MAIN parameter insert-name must be a scalar of CHAR VAR type without * extents.

Module:
DCLPL1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00230S A WIDECHAR or GRAPHIC string has been declared with a negative repetition factor, or the resulting string length exceeds 16383.

Module:
PASS1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00231S A format's repeat field, w field, or d field is negative or exceeds the implementation's limit.

Module:
PASS1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00232S A format has a missing field.

Module:
PASS1.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00233S Possible compiler error. A P-format or a R-format without the appropriate operand. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Parent topic: MFPLI00220 - MFPLI00239


MFPLI00234S A complex variable cannot be used as an index of a DO statement.

Parent topic: MFPLI00220 - MFPLI00239


MFPLI00235S The STRING and SKIP options are incompatible.

The SKIP option can only be specified for STREAM files and not for GET or PUT statements transmitting to or from a character string.
Resolution:
Either remove the SKIP option or change the STRING option to a FILE option.
Module:
PLSP2.TB
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00236S The STRING and LINE options are incompatible.

The LINE option can only be specified for PRINT files and not for PUT statements transmitting to a character string.
Resolution:
Either remove the LINE option or change the STRING option to a FILE option.
Module:
PLSP2.TB
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00237S The STRING and PAGE options are incompatible.

The PAGE option can only be specified for PRINT files and not for PUT statements transmitting to a character string.
Resolution:
Either remove the PAGE option or change the STRING option to a FILE option.
Module:
PLSP2.TB
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00238S A Built-in function or concatenation produced a result string whose length exceeds 32767 or is negative.

Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00239S Missing FILE option.

Module:
PLSP2.TB
Parent topic: MFPLI00220 - MFPLI00239


MFPLI00240 - MFPLI00259

  • MFPLI00240S The first argument of ROUND must be a FIXED DECIMAL value with a nonzero scale-factor.
  • MFPLI00241W A noninteger value has been converted to an integer for use as a subscript or as an integer argument to a built-in function.
  • MFPLI00242S An IGNORE option cannot be given with an INTO or SET option.
  • MFPLI00243W Conversion of an arithmetic expression to a CHAR(1) target always results in a space " " due to conversion rules. Use the BYTE BUILTIN if direct assignment as a byte-value is intended.
  • MFPLI00244S The SIZE built-in function requires a CONNECTED level-one variable reference with no * subscripts as its argument.
  • MFPLI00245S insert-name is a STRUCTURE containing the UNION attribute and cannot be used in a STREAM I/O statement.
  • MFPLI00246E "insert-name" contains an illegal use of the UNION attribute. It is ignored. The UNION attribute may be used only on a STRUCTURE.
  • MFPLI00247S Possible Compiler Error: Unable to determine size_units of "insert-name" for the SIZE built-in function.
  • MFPLI00248E Possible preprocessor error: mismatched %%ENDFILE at physical line: line-number in FILE: file-name. Please contact Micro Focus Support Line.
  • MFPLI00249S Missing argument in call to "entry-name" is not valid unless the OPTIONAL attribute is present or OPTIONS(VARIABLE) is specified in the ENTRY declaration.
  • MFPLI00250S Only integers are allowed with K, M, or G suffix.
  • MFPLI00251S "insert-name" has been declared with the UNALIGNED attribute. OFFSET, LABEL, and AREA cannot be unaligned.
  • MFPLI00252E A target variable "insert-name" in the assignment BY NAME is not a STRUCTURE.
  • MFPLI00253I No assignments are generated by this BY NAME assignment statement.
  • MFPLI00254S Negative arguments are not allowed for HIGH or LOW intrinsic functions.
  • MFPLI00255W Number of parameters for PROCEDURE "insert-name" does not agree with the EXTERNAL ENTRY declaration for the same PROCEDURE.
  • MFPLI00256W Parameter "insert-name" type conflicts with the parameter type and/or attributes declared in the EXTERNAL ENTRY declaration for the same PROCEDURE.
  • MFPLI00257W There is a return descriptor mismatch between PROCEDURE "insert-name" and the EXTERNAL ENTRY declaration for the same PROCEDURE.
  • MFPLI00258W RETURNS descriptor type of function "insert-name" conflicts with the return type declared in the EXTERNAL ENTRY declaration for the same function.
  • MFPLI00259S Array built-ins require an array of scalars as an argument.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00240S The first argument of ROUND must be a FIXED DECIMAL value with a nonzero scale-factor.

Parent topic: MFPLI00240 - MFPLI00259


MFPLI00241W A noninteger value has been converted to an integer for use as a subscript or as an integer argument to a built-in function.

Module:
EXPEXP.PL1, INTRP2.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00242S An IGNORE option cannot be given with an INTO or SET option.

Parent topic: MFPLI00240 - MFPLI00259


MFPLI00243W Conversion of an arithmetic expression to a CHAR(1) target always results in a space " " due to conversion rules. Use the BYTE BUILTIN if direct assignment as a byte-value is intended.

Module:
VALASS.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00244S The SIZE built-in function requires a CONNECTED level-one variable reference with no * subscripts as its argument.

Module:
INTRP2.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00245S insert-name is a STRUCTURE containing the UNION attribute and cannot be used in a STREAM I/O statement.

Module:
INTRP2.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00246E "insert-name" contains an illegal use of the UNION attribute. It is ignored. The UNION attribute may be used only on a STRUCTURE.

Module:
DCLPCS.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00247S Possible Compiler Error: Unable to determine size_units of "insert-name" for the SIZE built-in function.

Module:
INTRP2.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00248E Possible preprocessor error: mismatched %%ENDFILE at physical line: line-number in FILE: file-name. Please contact Micro Focus Support Line.

Module:
PASS1.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00249S Missing argument in call to "entry-name" is not valid unless the OPTIONAL attribute is present or OPTIONS(VARIABLE) is specified in the ENTRY declaration.

Module:
EXPARG.PL1 (commented out)
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00250S Only integers are allowed with K, M, or G suffix.

Module:
LEXSTATE.IN
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00251S "insert-name" has been declared with the UNALIGNED attribute. OFFSET, LABEL, and AREA cannot be unaligned.

Module:
DCLPCS.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00252E A target variable "insert-name" in the assignment BY NAME is not a STRUCTURE.

Module:
BYNAME.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00253I No assignments are generated by this BY NAME assignment statement.

Module:
BYNAME.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00254S Negative arguments are not allowed for HIGH or LOW intrinsic functions.

Module:
RESIS.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00255W Number of parameters for PROCEDURE "insert-name" does not agree with the EXTERNAL ENTRY declaration for the same PROCEDURE.

Module:
DCLPL1.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00256W Parameter "insert-name" type conflicts with the parameter type and/or attributes declared in the EXTERNAL ENTRY declaration for the same PROCEDURE.

Module:
DCLPL1.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00257W There is a return descriptor mismatch between PROCEDURE "insert-name" and the EXTERNAL ENTRY declaration for the same PROCEDURE.

Module:
DCLPL1.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00258W RETURNS descriptor type of function "insert-name" conflicts with the return type declared in the EXTERNAL ENTRY declaration for the same function.

Module:
DCLPL1.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00259S Array built-ins require an array of scalars as an argument.

Module:
EXPLPS.PL1
Parent topic: MFPLI00240 - MFPLI00259


MFPLI00260 - MFPLI00279

  • MFPLI00260S Bit(*) arrays are not supported for ANY and ALL array built-ins in this implementation.
  • MFPLI00261S Incorrect DEFAULT RANGE syntax.
  • MFPLI00262S DEFAULT is declared with conflicting attributes.
  • MFPLI00263S Incomplete VALUE specification in a DEFAULT statement.
  • MFPLI00264S Incorrect precision, scale or string length specified in a DEFAULT statement.
  • MFPLI00265S A CHARACTER or BIT string has been declared with a negative repetition factor, or the resulting string length exceeds 32767.
  • MFPLI00266W FILE attributes in DECLARATION and OPEN statements for FILE insert-name.
  • MFPLI00267E The *PROCESS MARGINS(l,r) directive must have an integer pair l,r with a valid range between 1,256. Left margin of 1 will be used.
  • MFPLI00268W The precision and scale of "insert-name" is being converted to FIXED DECinsert-name. Expect a possible loss of digits.
  • MFPLI00269E Invalid syntax in %%SKIP statement. The correct syntax is %%SKIP [(unsigned-integer-constant)];
  • MFPLI00270W The variable "insert-name" used in FREE must not be subscripted.
  • MFPLI00271S "insert-name" has been declared with an invalid asterisk iteration factor. Asterisk iteration factor cannot be used to initialize part of an array; it can only be used to initialize all elements of the array to the same value.
  • MFPLI00272S "insert-name" has been declared with an invalid asterisk iteration factor. Asterisk iteration factor can only be used to initialize all elements of the array to the same value.
  • MFPLI00273S The maximum number of dimensions for array "insert-name" has been exceeded.
  • MFPLI00274E VALUE and VARYING are conflicting attributes; VALUE ignored.
  • MFPLI00275S "insert-name" cannot be allocated because it is a self-defining STRUCTURE.
  • MFPLI00276S First argument of POSINT/INT must be a reference to CONNECTED storage.
  • MFPLI00277S Implicit conversion from OFFSET to POINTER or from POINTER to OFFSET in assignments or relational operations is valid only if the OFFSET is associated, in its declaration, with an AREA.
  • MFPLI00278S The OFFSET variable "variable-name" may be used as a locator only if it was associated, in its declaration, with an AREA.
  • MFPLI00279S Assignment of AREAs is valid only if the assignment target is of equal or greater size to the assignment source.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00260S Bit(*) arrays are not supported for ANY and ALL array built-ins in this implementation.

Module:
EXPLPS.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00261S Incorrect DEFAULT RANGE syntax.

Module:
DEFLT.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00262S DEFAULT is declared with conflicting attributes.

Module:
DEFLT.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00263S Incomplete VALUE specification in a DEFAULT statement.

Module:
DEFLT.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00264S Incorrect precision, scale or string length specified in a DEFAULT statement.

Module:
PASS1.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00265S A CHARACTER or BIT string has been declared with a negative repetition factor, or the resulting string length exceeds 32767.

Module:
PASS1.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00266W FILE attributes in DECLARATION and OPEN statements for FILE insert-name.

Module:
INTRP2.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00267E The *PROCESS MARGINS(l,r) directive must have an integer pair l,r with a valid range between 1,256. Left margin of 1 will be used.

Parent topic: MFPLI00260 - MFPLI00279


MFPLI00268W The precision and scale of "insert-name" is being converted to FIXED DECinsert-name. Expect a possible loss of digits.

Module:
EXPARG.PL1, VALASS.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00269E Invalid syntax in %%SKIP statement. The correct syntax is %%SKIP [(unsigned-integer-constant)];

Module:
PASS1.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00270W The variable "insert-name" used in FREE must not be subscripted.

Module:
INTRP2.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00271S "insert-name" has been declared with an invalid asterisk iteration factor. Asterisk iteration factor cannot be used to initialize part of an array; it can only be used to initialize all elements of the array to the same value.

Module:
INIT.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00272S "insert-name" has been declared with an invalid asterisk iteration factor. Asterisk iteration factor can only be used to initialize all elements of the array to the same value.

Module:
INIT.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00273S The maximum number of dimensions for array "insert-name" has been exceeded.

Module:
PASS1.PL1, PREPBD.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00274E VALUE and VARYING are conflicting attributes; VALUE ignored.

Module:
DCLPCS.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00275S "insert-name" cannot be allocated because it is a self-defining STRUCTURE.

Module:
INTRP2.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00276S First argument of POSINT/INT must be a reference to CONNECTED storage.

Module:
INTRP2.PL1, RESIS.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00277S Implicit conversion from OFFSET to POINTER or from POINTER to OFFSET in assignments or relational operations is valid only if the OFFSET is associated, in its declaration, with an AREA.

Module:
CVTPL1.PL1, VALASS.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00278S The OFFSET variable "variable-name" may be used as a locator only if it was associated, in its declaration, with an AREA.

Module:
EXPEXP.PL1, INTRP2.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00279S Assignment of AREAs is valid only if the assignment target is of equal or greater size to the assignment source.

Module:
VALASS.PL1
Parent topic: MFPLI00260 - MFPLI00279


MFPLI00280 - MFPLI00299

  • MFPLI00280S The variable "insert-name" using LIKE can only have those members which it inherits from the LIKE definition. Additional substructures or members cannot be added to the created STRUCTURE.
  • MFPLI00281S "insert-name" is declared with the LIKE attribute but also with one or more data type attributes. LIKE must not be used with any of: PICTURE, FIXED, FLOAT, BINARY, DECIMAL, CHARACTER, BIT, POINTER, ENTRY, LABEL, or FILE.
  • MFPLI00282S "insert-name" has been declared as LIKE x but "x" has not been declared. The declaration has been left without a data type.
  • MFPLI00283S "insert-name" is declared with LIKE x, but "x" does not resolve to a declaration of a STRUCTURE variable. A LIKE definition must be a major or minor STRUCTURE.
  • MFPLI00284S "insert-name" is declared as LIKE x, but "x" is also declared with LIKE. Neither the STRUCTURE variable "x" nor any of its substructures can be declared with the LIKE attribute.
  • MFPLI00285S "insert-name" is declared as LIKE x, but "x" is a member of a STRUCTURE declared with LIKE. A like definition must not be a member of a STRUCTURE declared with LIKE.
  • MFPLI00286S "insert-name" is declared as LIKE x, but "x" contains a REFER option. The STRUCTURE variable "x" that is a LIKE definition must not contain a REFER option.
  • MFPLI00287S "insert-name" is declared as LIKE x but "x" is a POINTER qualified or subscripted reference. The reference to the type definition in a LIKE attribute must not be POINTER -qualified or subscripted.
  • MFPLI00288S "insert-name" is declared with the LIKE attribute but the type definition uses a non-constant extent for a string length or an array bound.
  • MFPLI00289S The use of variable length records require that the minimum record size be specified by the use of the MINRECSIZE(n) option. An alternative is to use fixed size records with the SCALARVARYING option.
  • MFPLI00290S The reference in the CONDITION condition must have condition data type.
  • MFPLI00291S Parameter descriptors cannot have condition data type.
  • MFPLI00292S "variable-name" with condition data type cannot be passed as an argument to a PROCEDURE or function.
  • MFPLI00293S The usage of condition data type as the return descriptor type of function "insert-name" is invalid.
  • MFPLI00294S Invalid data type for parameter "insert-name". Dummy parameters cannot have condition data type.
  • MFPLI00295S "insert-name" has been declared with an INITIAL attribute. An INITIAL attribute cannot be specified for variables of condition data type.
  • MFPLI00296W The "built-in-name" built-in has been parsed but is not supported.
    The ONLOC built-in function is not supported.
  • MFPLI00297W This type of FILE organization requires that the record size be set. You can specify the RECSIZE environment option in this declaration or it will be determined by the initial write or read performed to this FILE.
  • MFPLI00298W insert-name has been declared with conflicting attributes; the CONNECTED and NONCONNECTED attributes can only be applied to parameters and descriptors.
  • MFPLI00299S A data-list item must be a scalar, element, array, or structure reference (not an expression).
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00280S The variable "insert-name" using LIKE can only have those members which it inherits from the LIKE definition. Additional substructures or members cannot be added to the created STRUCTURE.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00281S "insert-name" is declared with the LIKE attribute but also with one or more data type attributes. LIKE must not be used with any of: PICTURE, FIXED, FLOAT, BINARY, DECIMAL, CHARACTER, BIT, POINTER, ENTRY, LABEL, or FILE.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00282S "insert-name" has been declared as LIKE x but "x" has not been declared. The declaration has been left without a data type.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00283S "insert-name" is declared with LIKE x, but "x" does not resolve to a declaration of a STRUCTURE variable. A LIKE definition must be a major or minor STRUCTURE.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00284S "insert-name" is declared as LIKE x, but "x" is also declared with LIKE. Neither the STRUCTURE variable "x" nor any of its substructures can be declared with the LIKE attribute.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00285S "insert-name" is declared as LIKE x, but "x" is a member of a STRUCTURE declared with LIKE. A like definition must not be a member of a STRUCTURE declared with LIKE.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00286S "insert-name" is declared as LIKE x, but "x" contains a REFER option. The STRUCTURE variable "x" that is a LIKE definition must not contain a REFER option.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00287S "insert-name" is declared as LIKE x but "x" is a POINTER qualified or subscripted reference. The reference to the type definition in a LIKE attribute must not be POINTER -qualified or subscripted.

Module:
EXPTYP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00288S "insert-name" is declared with the LIKE attribute but the type definition uses a non-constant extent for a string length or an array bound.

Module:
EXPTYP.PL1 (commented out)
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00289S The use of variable length records require that the minimum record size be specified by the use of the MINRECSIZE(n) option. An alternative is to use fixed size records with the SCALARVARYING option.

Parent topic: MFPLI00280 - MFPLI00299


MFPLI00290S The reference in the CONDITION condition must have condition data type.

Module:
INTRP2.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00291S Parameter descriptors cannot have condition data type.

Module:
DCLPCS.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00292S "variable-name" with condition data type cannot be passed as an argument to a PROCEDURE or function.

Module:
EXPARG.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00293S The usage of condition data type as the return descriptor type of function "insert-name" is invalid.

Module:
DCLPCS.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00294S Invalid data type for parameter "insert-name". Dummy parameters cannot have condition data type.

Module:
DCLPCS.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00295S "insert-name" has been declared with an INITIAL attribute. An INITIAL attribute cannot be specified for variables of condition data type.

Module:
DCLPCS.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00296W The "built-in-name" built-in has been parsed but is not supported.

The ONLOC built-in function is not supported.
Resolution:
Remove dependency on the ONLOC built-in function.
Module:
EXPEXP.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00297W This type of FILE organization requires that the record size be set. You can specify the RECSIZE environment option in this declaration or it will be determined by the initial write or read performed to this FILE.

Module:
PASS1.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00298W insert-name has been declared with conflicting attributes; the CONNECTED and NONCONNECTED attributes can only be applied to parameters and descriptors.

Module:
DCLPCS.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00299S A data-list item must be a scalar, element, array, or structure reference (not an expression).

Module:
INTRP2.PL1
Parent topic: MFPLI00280 - MFPLI00299


MFPLI00300 - MFPLI00319

  • MFPLI00300S The reference to the BASED variable "insert-name" may not have an explicit locator qualifier in a DATA clause.
  • MFPLI00301S The number of data and format list pairs in the edit-directed specification exceeds the implementation's limit of insert-name.
  • MFPLI00302E Data types specified in the DECLARE statement and ALLOCATE statement for CONTROLLED variable "insert-name" do not match.
  • MFPLI00303S A subscript has been specified for the non-array variable "insert-name".
  • MFPLI00304S In the ALLOCATE statement for CONTROLLED variables only the following data types are valid - CHARACTER, BIT, and AREA.
  • MFPLI00305S For CONTROLLED arrays in the ALLOCATE or DECLARE statement the asterisk must be used for every dimension of the array.
  • MFPLI00306U Variable "insert-name" must be CONTROLLED variable in the current context of ALLOCATE statement.
  • MFPLI00307W Implicit conversion from FIXED BIN(31) to FIXED BIN(15) in the assignment.
  • MFPLI00308W Explicit conversion of an argument from FIXED BIN(15) to FIXED BIN(31).
  • MFPLI00309W A RETURN statement in a function should return a value; results will be undefined.
  • MFPLI00310E X or BX string constant contains invalid hex characters.
  • MFPLI00311E Invalid binary floating point literal constant - contains invalid hex characters, sign is present but exponent is missing, or constant is too large to be represented by the largest float decimal constant.
  • MFPLI00312E Imaginary constants are not supported.
  • MFPLI00313E Expressions cannot be used as pseudovariable arguments.
  • MFPLI00314E STRUCTURE expressions are valid only if both operands have identical structuring.
    The operands in a STRUCTURE expression must have the same shape so that the expression can be evaluated using correponding members from each operand.
  • MFPLI00315S Array expressions are not yet supported in this context.
  • MFPLI00316S STRUCTURE expressions are not yet supported in this context.
  • MFPLI00317S Internal compiler error - unimplemented pass2 action .
  • MFPLI00318E X string constants should contain even number of hexadecimal digits.
  • MFPLI00319S Internal compiler error - unimplemented pass1 action .
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00300S The reference to the BASED variable "insert-name" may not have an explicit locator qualifier in a DATA clause.

Module:
INTRP2.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00301S The number of data and format list pairs in the edit-directed specification exceeds the implementation's limit of insert-name.

Module:
PASS1.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00302E Data types specified in the DECLARE statement and ALLOCATE statement for CONTROLLED variable "insert-name" do not match.

Module:
CTLALL.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00303S A subscript has been specified for the non-array variable "insert-name".

Module:
CTLALL.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00304S In the ALLOCATE statement for CONTROLLED variables only the following data types are valid - CHARACTER, BIT, and AREA.

Module:
CTLALL.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00305S For CONTROLLED arrays in the ALLOCATE or DECLARE statement the asterisk must be used for every dimension of the array.

Module:
CTLALL.PL1 (commented out)
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00306U Variable "insert-name" must be CONTROLLED variable in the current context of ALLOCATE statement.

Module:
CTLALL.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00307W Implicit conversion from FIXED BIN(31) to FIXED BIN(15) in the assignment.

Module:
VALASS.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00308W Explicit conversion of an argument from FIXED BIN(15) to FIXED BIN(31).

Module:
EXPARG.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00309W A RETURN statement in a function should return a value; results will be undefined.

Module:
INTRP2.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00310E X or BX string constant contains invalid hex characters.

Module:
LEXSTATE.IN
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00311E Invalid binary floating point literal constant - contains invalid hex characters, sign is present but exponent is missing, or constant is too large to be represented by the largest float decimal constant.

Module:
LEXSTATE.IN
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00312E Imaginary constants are not supported.

Parent topic: MFPLI00300 - MFPLI00319


MFPLI00313E Expressions cannot be used as pseudovariable arguments.

Parent topic: MFPLI00300 - MFPLI00319


MFPLI00314E STRUCTURE expressions are valid only if both operands have identical structuring.

The operands in a STRUCTURE expression must have the same shape so that the expression can be evaluated using correponding members from each operand.
Resolution:
Ensure that the operands have the same shape or expand the statement to a sequence of evaluations using the required members from each operand.
Module:
AGGEXP.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00315S Array expressions are not yet supported in this context.

Module:
AGGEXP.PL1, RESIS.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00316S STRUCTURE expressions are not yet supported in this context.

Module:
AGGEXP.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00317S Internal compiler error - unimplemented pass2 action .

Module:
INTRP2.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00318E X string constants should contain even number of hexadecimal digits.

Module:
LEXSTATE.IN
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00319S Internal compiler error - unimplemented pass1 action .

Module:
PASS1.PL1
Parent topic: MFPLI00300 - MFPLI00319


MFPLI00320 - MFPLI00339

  • MFPLI00320S Internal compiler error - unimplemented resis rule.
  • MFPLI00321W The RECURSIVE attribute is not allowed on an ENTRY statement; ignored.
  • MFPLI00322E Mixed string (M) constants are only partially supported.
  • MFPLI00323E CHARGRAPHIC option is not fully supported.
  • MFPLI00324E The argument of the STRING function cannot be NONCONNECTED array with non-constant extents.
  • MFPLI00325E Internal compiler error - incorrect nesting of initial factors for symbol insert-name.
  • MFPLI00326E The nesting level of initial repeat factors for symbol insert-name exceeds the implementation limit if 32.
  • MFPLI00327E PLISRTx BUILTIN has fewer than required number of parameters.
  • MFPLI00328E PLISRTx routine has excessive number of parameters. Extra parameters are ignored.
  • MFPLI00329E Declared LABEL array array-name has been implicitly initialized with the subscripted labels, however these arrays must be non-STATIC.
  • MFPLI00330E Declared LABEL scalar variable label-name cannot be implicitly initialized with the subscripted labels. Only LABEL arrays can be initialized this way.
  • MFPLI00331E Declared LABEL array array-name has more than one dimension. Only one-dimensional LABEL arrays can be implicitly initialized by subscripted labels.
  • MFPLI00332E Declared LABEL array array-name is being implicitly initialized with subscripted label(s) whose subscript is out of range.
  • MFPLI00333E Explicitly initialized LABEL array array-name is being initialized implicitly with subscripted label(s). Only one form of initialization is allowed.
  • MFPLI00334W VARIABLE attribute is ignored in the DEFAULT statement.
  • MFPLI00335E Number of dimensions in the subscripted LABEL does not match the declared LABEL array array-name .
  • MFPLI00336W The undeclared name insert-name has been contextually declared.
  • MFPLI00337W An unlikely conversion occurred in the evaluation of a constant array dimension or extent. If this is intended, this diagnostic can be ignored.
    The constant array dimension or extent is of type CHAR or BIT.
  • MFPLI00338W STRUCTURE structure-name contains padding between some of its elements.
  • MFPLI00339W Assignment of arrays with non-constant extents may only be valid if both sides of the assignment have identical size.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00320S Internal compiler error - unimplemented resis rule.

Module:
AGGEXP.PL1, RESIS.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00321W The RECURSIVE attribute is not allowed on an ENTRY statement; ignored.

Module:
PASS1.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00322E Mixed string (M) constants are only partially supported.

Module:
LEXSTATE.IN
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00323E CHARGRAPHIC option is not fully supported.

Parent topic: MFPLI00320 - MFPLI00339


MFPLI00324E The argument of the STRING function cannot be NONCONNECTED array with non-constant extents.

Module:
EXPLPS.PL1 (commented out)
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00325E Internal compiler error - incorrect nesting of initial factors for symbol insert-name.

Parent topic: MFPLI00320 - MFPLI00339


MFPLI00326E The nesting level of initial repeat factors for symbol insert-name exceeds the implementation limit if 32.

Parent topic: MFPLI00320 - MFPLI00339


MFPLI00327E PLISRTx BUILTIN has fewer than required number of parameters.

Module:
INTRP2.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00328E PLISRTx routine has excessive number of parameters. Extra parameters are ignored.

Module:
INTRP2.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00329E Declared LABEL array array-name has been implicitly initialized with the subscripted labels, however these arrays must be non-STATIC.

Module:
SUBLAB.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00330E Declared LABEL scalar variable label-name cannot be implicitly initialized with the subscripted labels. Only LABEL arrays can be initialized this way.

Module:
SUBLAB.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00331E Declared LABEL array array-name has more than one dimension. Only one-dimensional LABEL arrays can be implicitly initialized by subscripted labels.

Module:
SUBLAB.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00332E Declared LABEL array array-name is being implicitly initialized with subscripted label(s) whose subscript is out of range.

Module:
SUBLAB.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00333E Explicitly initialized LABEL array array-name is being initialized implicitly with subscripted label(s). Only one form of initialization is allowed.

Module:
SUBLAB.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00334W VARIABLE attribute is ignored in the DEFAULT statement.

Module:
DEFLT.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00335E Number of dimensions in the subscripted LABEL does not match the declared LABEL array array-name .

Module:
SUBLAB.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00336W The undeclared name insert-name has been contextually declared.

Parent topic: MFPLI00320 - MFPLI00339


MFPLI00337W An unlikely conversion occurred in the evaluation of a constant array dimension or extent. If this is intended, this diagnostic can be ignored.

The constant array dimension or extent is of type CHAR or BIT.
Resolution:
Check the constant array dimension or extent to be sure this is intended. Usually this is an integer number.
Module:
PASS1.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00338W STRUCTURE structure-name contains padding between some of its elements.

Module:
STRFIL.PL1
Parent topic: MFPLI00320 - MFPLI00339


MFPLI00339W Assignment of arrays with non-constant extents may only be valid if both sides of the assignment have identical size.

Parent topic: MFPLI00320 - MFPLI00339


MFPLI00340 - MFPLI00359

  • MFPLI00340E function-name is function without a RETURN statement.
  • MFPLI00341W A previous non-qualified declaration has the same name as STRUCTURE member insert-name.
  • MFPLI00342W A previous declaration of a STRUCTURE member has the same name as this declaration of insert-name.
  • MFPLI00343E The precision and/or scale of variable-name is not large enough to accept the assigned constant. Expect a loss of digits.
    Significant digits will be lost assigning the constant to variable-name.
  • MFPLI00344I Open PL/I does not support scaled FIXED BINARY; the DIVIDE operator applied to fixed binary values produces a scaled DECIMAL result. Use the DIVIDE built-in to avoid this message.
  • MFPLI00345S The letter insert-name is an unsupported or illegal string constant suffix character.
  • MFPLI00346S "insert-name" has been declared without a data type. NOLAXDCL is in effect.
  • MFPLI00347S The name "insert-name" is undeclared. NOLAXDCL is in effect.
  • MFPLI00348S Assignment of STRUCTUREs is only valid if both sides of the assignment have identical shape.
  • MFPLI00349W insert-name in the STRUCTURE assignment has shorter length than the source.
  • MFPLI00350S Assignment of arrays is only valid if both sides of the assignment have identical bounds, size, and type.
  • MFPLI00351S An array bound of insert-name could not be evaluated as a restricted expression at compile-time. STATIC arrays must have a constant size.
  • MFPLI00352W The HEX built-in will present STRUCTUREs in native storage order.
  • MFPLI00353S Only ENTRY constants are FETCHABLE.
  • MFPLI00354S RELEASE requires a FETCHABLE ENTRY constant.
  • MFPLI00355S FETCH SET (ref) requires a POINTER reference.
  • MFPLI00356S The number of digits in a Wx or Gx string constant should be a multiple of 4.
  • MFPLI00357W A function call with no arguments is assumed for "insert-name".
  • MFPLI00358W An ENTRY assignment is assumed for "insert-name"; use parentheses () with an empty argument list if CALL function returning ENTRY is intended.
  • MFPLI00359I Only the current generation of "insert-name" will be passed as a non-CONTROLLED variable reference.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00340E function-name is function without a RETURN statement.

Module:
INTRP2.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00341W A previous non-qualified declaration has the same name as STRUCTURE member insert-name.

Parent topic: MFPLI00340 - MFPLI00359


MFPLI00342W A previous declaration of a STRUCTURE member has the same name as this declaration of insert-name.

Parent topic: MFPLI00340 - MFPLI00359


MFPLI00343E The precision and/or scale of variable-name is not large enough to accept the assigned constant. Expect a loss of digits.

Significant digits will be lost assigning the constant to variable-name.
Resolution:
Either adjust the precision and/or scale of variable-name to accommodate all the significant digits in the constant or replace the digits that will be lost with zeros to avoid the message.
Module:
DCLPL1.PL1, VALASS.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00344I Open PL/I does not support scaled FIXED BINARY; the DIVIDE operator applied to fixed binary values produces a scaled DECIMAL result. Use the DIVIDE built-in to avoid this message.

Module:
RESIS.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00345S The letter insert-name is an unsupported or illegal string constant suffix character.

Module:
LEXSTATE.IN
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00346S "insert-name" has been declared without a data type. NOLAXDCL is in effect.

Module:
DCLPCS.PL1, EXPTYP.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00347S The name "insert-name" is undeclared. NOLAXDCL is in effect.

Module:
RESREF.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00348S Assignment of STRUCTUREs is only valid if both sides of the assignment have identical shape.

Module:
VALASS.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00349W insert-name in the STRUCTURE assignment has shorter length than the source.

Module:
VALASS.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00350S Assignment of arrays is only valid if both sides of the assignment have identical bounds, size, and type.

Parent topic: MFPLI00340 - MFPLI00359


MFPLI00351S An array bound of insert-name could not be evaluated as a restricted expression at compile-time. STATIC arrays must have a constant size.

Module:
DCLREE.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00352W The HEX built-in will present STRUCTUREs in native storage order.

Module:
RESIS.PL1 (commented out)
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00353S Only ENTRY constants are FETCHABLE.

Module:
DCLPCS.PL1, DCLPL1.PL1, FETCH.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00354S RELEASE requires a FETCHABLE ENTRY constant.

Module:
FETCH.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00355S FETCH SET (ref) requires a POINTER reference.

Module:
FETCH.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00356S The number of digits in a Wx or Gx string constant should be a multiple of 4.

Module:
LEXSTATE.IN
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00357W A function call with no arguments is assumed for "insert-name".

Module:
CHECKF.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00358W An ENTRY assignment is assumed for "insert-name"; use parentheses () with an empty argument list if CALL function returning ENTRY is intended.

Module:
CHECKF.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00359I Only the current generation of "insert-name" will be passed as a non-CONTROLLED variable reference.

Module:
EXPARG.PL1
Parent topic: MFPLI00340 - MFPLI00359


MFPLI00360 - MFPLI00379

  • MFPLI00360S Only CONTROLLED variables can be passed to CONTROLLED parameters; argument insert-name.
  • MFPLI00361W The value specified for the named constant insert-name cannot be converted to this constant type.
  • MFPLI00362E insert-name is declared with conflicting storage attributes.
  • MFPLI00363E insert-name is a STRUCTURE member and cannot be declared with a storage class.
  • MFPLI00364E The specified precision and/or scale is not large enough to accept an assigned constant. Expect a loss of digits.
  • MFPLI00365E PACKAGES should not contain FETCHABLE PROCEDUREs.
  • MFPLI00366S The character length of insert-name could not be evaluated as a restricted expression at compile-time. Parameters of type CHAR, BIT, and AREA must have a constant length or a star-extent.
  • MFPLI00367S The first argument to the XMLCHAR built-in must be a non-array STRUCTURE reference.
  • MFPLI00368S The second argument to the XMLCHAR built-in must be a POINTER.
  • MFPLI00369S An XMLCHAR STRUCTURE reference must not contain any substructures which use an * in place of a name.
  • MFPLI00370S An XMLCHAR STRUCTURE reference must not contain any arrays which are not completely subscripted.
  • MFPLI00371S An XMLCHAR STRUCTURE reference must not contain any base elements of non-computational type.
  • MFPLI00372E insert-name is an illegal overlay define. Only CHARACTER, BIT or PICTURE types are allowed with the POSITION attribute and the overlay types must be compatible.
  • MFPLI00373W Argument number insert-name in entry invocation "insert-name" is longer than the corresponding parameter; truncation will occur.
  • MFPLI00374S The compile-time switch "-initcall insert-name" conflicts with a declaration of the same name; if declared it must be an ENTRY compatible with ENTRY (CHAR(*)).
  • MFPLI00375S The argument of the OMITTED built-in must be a parameter variable reference.
  • MFPLI00376S The OMITTED built-in does not allow a parameter reference passed BYVALUE.
  • MFPLI00377S The REPLY option requires a scalar CHARACTER reference.
  • MFPLI00378S "insert-name" has been declared with a non-constant INITIAL repeat factor. STATIC variables must have constant initial repeat factors.
  • MFPLI00379E "insert-name" is a scalar item declared with a non-asterisk INITIAL repeat factor (ignored).
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00360S Only CONTROLLED variables can be passed to CONTROLLED parameters; argument insert-name.

Module:
EXPARG.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00361W The value specified for the named constant insert-name cannot be converted to this constant type.

Module:
AISCLR.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00362E insert-name is declared with conflicting storage attributes.

Module:
DCLPCS.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00363E insert-name is a STRUCTURE member and cannot be declared with a storage class.

Module:
PASS1.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00364E The specified precision and/or scale is not large enough to accept an assigned constant. Expect a loss of digits.

Module:
DCLPL1.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00365E PACKAGES should not contain FETCHABLE PROCEDUREs.

Module:
PASS1.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00366S The character length of insert-name could not be evaluated as a restricted expression at compile-time. Parameters of type CHAR, BIT, and AREA must have a constant length or a star-extent.

Module:
DCLREE.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00367S The first argument to the XMLCHAR built-in must be a non-array STRUCTURE reference.

Module:
RESIS.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00368S The second argument to the XMLCHAR built-in must be a POINTER.

Module:
RESIS.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00369S An XMLCHAR STRUCTURE reference must not contain any substructures which use an * in place of a name.

Module:
XMLCHAR.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00370S An XMLCHAR STRUCTURE reference must not contain any arrays which are not completely subscripted.

Module:
XMLCHAR.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00371S An XMLCHAR STRUCTURE reference must not contain any base elements of non-computational type.

Module:
XMLCHAR.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00372E insert-name is an illegal overlay define. Only CHARACTER, BIT or PICTURE types are allowed with the POSITION attribute and the overlay types must be compatible.

Module:
DCLPL1.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00373W Argument number insert-name in entry invocation "insert-name" is longer than the corresponding parameter; truncation will occur.

Module:
EXPARG.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00374S The compile-time switch "-initcall insert-name" conflicts with a declaration of the same name; if declared it must be an ENTRY compatible with ENTRY (CHAR(*)).

Module:
DCLPCS.PL1, DCLPL1.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00375S The argument of the OMITTED built-in must be a parameter variable reference.

Module:
RESIS.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00376S The OMITTED built-in does not allow a parameter reference passed BYVALUE.

Module:
RESIS.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00377S The REPLY option requires a scalar CHARACTER reference.

Module:
INTRP2.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00378S "insert-name" has been declared with a non-constant INITIAL repeat factor. STATIC variables must have constant initial repeat factors.

Module:
ANEXTV.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00379E "insert-name" is a scalar item declared with a non-asterisk INITIAL repeat factor (ignored).

Module:
INIT.PL1
Parent topic: MFPLI00360 - MFPLI00379


MFPLI00380 - MFPLI00399

  • MFPLI00380S The number of single-byte characters in a W or G string constant should be a multiple of 2.
  • MFPLI00381E insert-name is a named constant declared with a conflicting storage attribute; attribute ignored.
  • MFPLI00382S DISPLAY requires a scalar expression.
  • MFPLI00383W insert-name is shorter than the string assigned and will be truncated.
  • MFPLI00384W insert-name is shorter than the supplied INITIAL value and will be truncated.
  • MFPLI00385S INDEX BUILTIN starting position will cause a run-time STRINGRANGE condition.
  • MFPLI00386E A NONCONNECTED array reference should not be used as an argument to the ADDR, SIZE, STG, or CSTG built-in functions.
  • MFPLI00387S A NONCONNECTED array reference cannot be used in a READ INTO or WRITE FROM option.
  • MFPLI00388S A NONCONNECTED array reference cannot be used as the base reference of a DEFINED variable.
  • MFPLI00389S A NONCONNECTED array reference cannot be used as an argument that is passed by-reference to a parameter that has constant extents.
  • MFPLI00390E insert-name uses the REFER option; BASED variables should not contain both refer-extents and other extents with non-constant values.
  • MFPLI00391S insert-name cannot use the REFER option; BASED variables cannot contain both refer-extents and other extents with non-constant values.
  • MFPLI00392W There is an OPTIONS attribute mismatch between PROCEDURE "insert-name" and the EXTERNAL ENTRY declaration for the same PROCEDURE.
  • MFPLI00393E PLITDLI is a special IMS name and should not be declared with an ENTRY descriptor list or as a function; assuming "DCL PLITDLI ENTRY;" for IMS linkage.
  • MFPLI00394E insert-name is an invalid DEFINED overlay.
  • MFPLI00395E insert-name is declared as DEFINED but requires more storage than its base variable.
  • MFPLI00396E insert-name is BASED on ADDR("x") but requires more storage than its BASED reference.
  • MFPLI00397S An array is not a valid argument to PLITDLI.
  • MFPLI00398S The ITERATIVE label-constant insert-name is not present within a containing iterative DO-group.
  • MFPLI00399E The DIVIDE built-in scale-factor for FIXED BINARY arguments should be zero. Integer result, ignoring quotient, will be produced.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00380S The number of single-byte characters in a W or G string constant should be a multiple of 2.

Parent topic: MFPLI00380 - MFPLI00399


MFPLI00381E insert-name is a named constant declared with a conflicting storage attribute; attribute ignored.

Module:
DCLPCS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00382S DISPLAY requires a scalar expression.

Module:
INTRP2.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00383W insert-name is shorter than the string assigned and will be truncated.

Module:
VALASS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00384W insert-name is shorter than the supplied INITIAL value and will be truncated.

Module:
DCLREE.PL1, VALASS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00385S INDEX BUILTIN starting position will cause a run-time STRINGRANGE condition.

Module:
RESIS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00386E A NONCONNECTED array reference should not be used as an argument to the ADDR, SIZE, STG, or CSTG built-in functions.

Module:
INTRP2.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00387S A NONCONNECTED array reference cannot be used in a READ INTO or WRITE FROM option.

Module:
INTRP2.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00388S A NONCONNECTED array reference cannot be used as the base reference of a DEFINED variable.

Module:
DCLPL1.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00389S A NONCONNECTED array reference cannot be used as an argument that is passed by-reference to a parameter that has constant extents.

Parent topic: MFPLI00380 - MFPLI00399


MFPLI00390E insert-name uses the REFER option; BASED variables should not contain both refer-extents and other extents with non-constant values.

Module:
DCLPCS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00391S insert-name cannot use the REFER option; BASED variables cannot contain both refer-extents and other extents with non-constant values.

Module:
DCLPCS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00392W There is an OPTIONS attribute mismatch between PROCEDURE "insert-name" and the EXTERNAL ENTRY declaration for the same PROCEDURE.

Module:
DCLPL1.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00393E PLITDLI is a special IMS name and should not be declared with an ENTRY descriptor list or as a function; assuming "DCL PLITDLI ENTRY;" for IMS linkage.

Module:
DCLPCS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00394E insert-name is an invalid DEFINED overlay.

Module:
DCLPL1.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00395E insert-name is declared as DEFINED but requires more storage than its base variable.

Module:
DCLPL1.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00396E insert-name is BASED on ADDR("x") but requires more storage than its BASED reference.

Module:
DCLPL1.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00397S An array is not a valid argument to PLITDLI.

Parent topic: MFPLI00380 - MFPLI00399


MFPLI00398S The ITERATIVE label-constant insert-name is not present within a containing iterative DO-group.

Module:
PASS1.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00399E The DIVIDE built-in scale-factor for FIXED BINARY arguments should be zero. Integer result, ignoring quotient, will be produced.

Module:
RESIS.PL1
Parent topic: MFPLI00380 - MFPLI00399


MFPLI00400 - MFPLI00419

  • MFPLI00400S "insert-name" has been declared with the VARYINGZ attribute. Only CHARACTER string variables may be declared VARYINGZ.
  • MFPLI00401W Z/OS STRUCTURE mapping of structure-name may require "-bitsltr" to map little-endian bit-fields left-to-right.
  • MFPLI00402S ENTRY constants used in STATIC INITIAL must be non-nested.
  • MFPLI00403E LABEL variables cannot be initialized with STATIC INITIAL; the required stack frame address is unknown at compile-time.
  • MFPLI00404W insert-name condition raised during a compile-time conversion check; this will likely result in the same condition raised at run-time.
  • MFPLI00405I The undeclared name "insert-name" has been declared with the default type as a variable in the outermost PROCEDURE.
  • MFPLI00406I The undeclared name "variable-name" has been contextually declared as a variable in the outermost block-type.
  • MFPLI00407S GET input-item "insert-name" must be computational.
  • MFPLI00408E OPTIONS(MAIN) is not allowed on a nested procedure; ignored.
    OPTIONS(MAIN) is not allowed on a nested procedure.
  • MFPLI00409E OPTIONS(CICSMAIN) is not allowed on a nested procedure; ignored.
    OPTIONS(CICSMAIN) is not allowed on a nested procedure.
  • MFPLI00414S The second argument to the JSONxxx built-ins must be FIXED BIN but a non-computational value has been used.
  • MFPLI00415S The third argument to the JSONxxx built-ins must not contain any elements that have * names, UNION or GRAPHIC attributes, non-computational data, scaled FIXED BINARY, or FIXED DECIMAL(p,q) where q < 0 or q > p.
  • MFPLI00416S The first argument to the JSONxxx built-ins must be a locator (OFFSET with explicit AREA declaration or a POINTER).
  • MFPLI00417S A precision/length exceeds the implementation limit of insert-name.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00400S "insert-name" has been declared with the VARYINGZ attribute. Only CHARACTER string variables may be declared VARYINGZ.

Module:
DCLPCS.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00401W Z/OS STRUCTURE mapping of structure-name may require "-bitsltr" to map little-endian bit-fields left-to-right.

Module:
ZALIGN.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00402S ENTRY constants used in STATIC INITIAL must be non-nested.

Module:
DCLPL1.PL1 (commented out)
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00403E LABEL variables cannot be initialized with STATIC INITIAL; the required stack frame address is unknown at compile-time.

Module:
DCLPL1.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00404W insert-name condition raised during a compile-time conversion check; this will likely result in the same condition raised at run-time.

Module:
PLICONV.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00405I The undeclared name "insert-name" has been declared with the default type as a variable in the outermost PROCEDURE.

Module:
RESREF.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00406I The undeclared name "variable-name" has been contextually declared as a variable in the outermost block-type.

Module:
RESREF.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00407S GET input-item "insert-name" must be computational.

Module:
INTRP2.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00408E OPTIONS(MAIN) is not allowed on a nested procedure; ignored.

OPTIONS(MAIN) is not allowed on a nested procedure.
Resolution:
Remove OPTIONS(MAIN) from the nested procedures and apply it to the outermost procedure (if applicable).
Module:
PASS1.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00409E OPTIONS(CICSMAIN) is not allowed on a nested procedure; ignored.

OPTIONS(CICSMAIN) is not allowed on a nested procedure.
Resolution:
Remove OPTIONS(CICSMAIN) from the nested procedures and apply it to the outermost procedure (if applicable).
Module:
PASS1.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00414S The second argument to the JSONxxx built-ins must be FIXED BIN but a non-computational value has been used.

Module:
RESIS.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00415S The third argument to the JSONxxx built-ins must not contain any elements that have * names, UNION or GRAPHIC attributes, non-computational data, scaled FIXED BINARY, or FIXED DECIMAL(p,q) where q < 0 or q > p.

Module:
JSONFE.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00416S The first argument to the JSONxxx built-ins must be a locator (OFFSET with explicit AREA declaration or a POINTER).

Module:
RESIS.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00417S A precision/length exceeds the implementation limit of insert-name.

Module:
DCLREE.PL1, PASS1.PL1
Parent topic: MFPLI00400 - MFPLI00419


MFPLI00420 - MFPLI00439

  • MFPLI00436W This %%REPLACE statement is a duplicate of one that appeared previously. Please remove one of them.
  • MFPLI00437S Invalid syntax in a %%REPLACE statement. Check to see if the identifier appeared in another %%REPLACE statement with a different replace value.
  • MFPLI00438S Invalid picture specification insert-name. Char picture may contain only A, X or 9.
  • MFPLI00439S AMODE option is only supported for Windows 32-bit platform.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00436W This %%REPLACE statement is a duplicate of one that appeared previously. Please remove one of them.

Parent topic: MFPLI00420 - MFPLI00439


MFPLI00437S Invalid syntax in a %%REPLACE statement. Check to see if the identifier appeared in another %%REPLACE statement with a different replace value.

Module:
PASS1.PL1
Parent topic: MFPLI00420 - MFPLI00439


MFPLI00438S Invalid picture specification insert-name. Char picture may contain only A, X or 9.

Module:
DCLPIC.PL1
Parent topic: MFPLI00420 - MFPLI00439


MFPLI00439S AMODE option is only supported for Windows 32-bit platform.

Parent topic: MFPLI00420 - MFPLI00439


MFPLI00440 - MFPLI00459

  • MFPLI00440S AMODE option is not supported for 64-bit platforms.
  • MFPLI00441S options(asm) is only supported for Windows 32-bit platform.
  • MFPLI00442S The first argument to the MEMINDEX built-ins must be a POINTER or OFFSET.
  • MFPLI00443S The third argument to the MEMINDEX built-ins must be a POINTER or OFFSET.
  • MFPLI00444S The second argument to the ALLOCATE built-ins must be of AREA type.
  • MFPLI00445I OPTIONS(REORDER) is parsed but ignored.
  • MFPLI00446S The VALUE attribute may be used on a structure member only if it is used on all base members of that structure.
  • MFPLI00447S The VALUE attribute may be used on a structure member only if no parent has the UNION attribute.
  • MFPLI00448S The VALUE attribute conflicts with the DIMENSION attribute.
  • MFPLI00449S The VALUE attribute may be used on a structure member only if no dimension attributes are specified for its parents.
  • MFPLI00450S References to a structure containing elements with the VALUE attribute are invalid.
  • MFPLI00451S Invalid conversion while evaluating restricted expression.
  • MFPLI00452W BIT operators should only be applied to BIT operands.
  • MFPLI00453E The INOUT, INONLY, and OUTONLY attributes should only be applied to parameters or parameter descriptors.
  • MFPLI00454S Only one of the attributes INOUT, INONLY, and OUTONLY may be applied to parameter declaration.
  • MFPLI00455E The INONLY attribute conflicts with the OPTIONAL attribute; INONLY ignored.
  • MFPLI00456W "identifier-name" has the INONLY attribute on assignment.
  • MFPLI00457W "insert-name" has the OUTONLY attribute and may not be initialized when first used.
  • MFPLI00458S Premature exit; Eclipse .dcf information is probably incomplete.
    The compiler has possibly encountered an error.
  • MFPLI00459E Error saving Eclipse repository information file.
    The compiler has possibly encountered an error.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00440S AMODE option is not supported for 64-bit platforms.

Module:
PASS1.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00441S options(asm) is only supported for Windows 32-bit platform.

Module:
DCLPL1.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00442S The first argument to the MEMINDEX built-ins must be a POINTER or OFFSET.

Module:
RESIS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00443S The third argument to the MEMINDEX built-ins must be a POINTER or OFFSET.

Module:
RESIS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00444S The second argument to the ALLOCATE built-ins must be of AREA type.

Module:
RESIS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00445I OPTIONS(REORDER) is parsed but ignored.

Module:
PASS1.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00446S The VALUE attribute may be used on a structure member only if it is used on all base members of that structure.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00447S The VALUE attribute may be used on a structure member only if no parent has the UNION attribute.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00448S The VALUE attribute conflicts with the DIMENSION attribute.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00449S The VALUE attribute may be used on a structure member only if no dimension attributes are specified for its parents.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00450S References to a structure containing elements with the VALUE attribute are invalid.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00451S Invalid conversion while evaluating restricted expression.

Module:
INTRP2.PL1, VALASS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00452W BIT operators should only be applied to BIT operands.

Module:
INTRP2.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00453E The INOUT, INONLY, and OUTONLY attributes should only be applied to parameters or parameter descriptors.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00454S Only one of the attributes INOUT, INONLY, and OUTONLY may be applied to parameter declaration.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00455E The INONLY attribute conflicts with the OPTIONAL attribute; INONLY ignored.

Module:
DCLPCS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00456W "identifier-name" has the INONLY attribute on assignment.

Module:
VALASS.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00457W "insert-name" has the OUTONLY attribute and may not be initialized when first used.

Module:
WRITET.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00458S Premature exit; Eclipse .dcf information is probably incomplete.

The compiler has possibly encountered an error.
Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00459E Error saving Eclipse repository information file.

The compiler has possibly encountered an error.
Module:
DC.PL1
Parent topic: MFPLI00440 - MFPLI00459


MFPLI00460 - MFPLI00479

  • MFPLI00460S Result of concatenating two string literals exceeds the implementation limit of insert-value.
    A concatenation of two string literals resulted in a length greater than the allowed limit.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI00460S Result of concatenating two string literals exceeds the implementation limit of insert-value.

A concatenation of two string literals resulted in a length greater than the allowed limit.
Resolution:
Reduce the resultant string length to <= 32767.
Module:
RESIS.PL1
Parent topic: MFPLI00460 - MFPLI00479


MFPLI01100 - MFPLI01119

  • MFPLI01100S Inconsistent or duplicate option: option-name
  • MFPLI01101S Invalid option: option-name
  • MFPLI01103S The -setnull option requires an integer argument.
  • MFPLI01104S Missing -isuffix string.
  • MFPLI01105S Duplicate isuffix: insert-name
  • MFPLI01106S isuffix string too long.
  • MFPLI01107S Inconsistent option: option-name
  • MFPLI01108S Incorrect margins option syntax,correct syntax is: -margins l,m where l and m are positive integers.
  • MFPLI01109S The -highbif option requires a decimal integer argument.
  • MFPLI01110S The -firstbyte option requires a decimal integer argument.
  • MFPLI01111S The -shiftout option requires a decimal integer argument).
  • MFPLI01112S The -shiftin option requires a decimal integer argument.
  • MFPLI01113S The option-name option requires single quoted strings or hex constants of the form 0xDD..DD
  • MFPLI01114S The option-name option requires a single char, decimal number (0-255) or a hex constant of the form 0xDD.
  • MFPLI01116S -langlvl SAA2 expected.
  • MFPLI01117S Missing -sql string argument odbc, oci or db2.
  • MFPLI01118S Missing insert-name output FILE name.
  • MFPLI01119S Missing insert-name string argument.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01100S Inconsistent or duplicate option: option-name

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01101S Invalid option: option-name

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01103S The -setnull option requires an integer argument.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01104S Missing -isuffix string.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01105S Duplicate isuffix: insert-name

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01106S isuffix string too long.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01107S Inconsistent option: option-name

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01108S Incorrect margins option syntax,correct syntax is: -margins l,m where l and m are positive integers.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01109S The -highbif option requires a decimal integer argument.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01110S The -firstbyte option requires a decimal integer argument.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01111S The -shiftout option requires a decimal integer argument).

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01112S The -shiftin option requires a decimal integer argument.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01113S The option-name option requires single quoted strings or hex constants of the form 0xDD..DD

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01114S The option-name option requires a single char, decimal number (0-255) or a hex constant of the form 0xDD.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01116S -langlvl SAA2 expected.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01117S Missing -sql string argument odbc, oci or db2.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01118S Missing insert-name output FILE name.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01119S Missing insert-name string argument.

Module:
XINIFE.PL1
Parent topic: MFPLI01100 - MFPLI01119


MFPLI01120 - MFPLI01139

  • MFPLI01120S The option -ppcics requires -cics.
  • MFPLI01121S The option -ppsql requires -sql <arg>.
  • MFPLI01122S The option -ppdli requires -dli.
  • MFPLI01123S The options -systemcics, -systemmvs, and -systemims must be mutually exclusive.
    Only one of these options may be specified.
  • MFPLI01124S The options -cics, -sql, -dli, -systemmvs, -systemcics, and/or -systemims conflict with option-name
  • MFPLI01125S The -window option requires an integer argument.
  • MFPLI01126S The option -ppincl requires -incl.
  • MFPLI01127S The option -optcics requires -cics.
  • MFPLI01128S The option -optsql requires -sql <arg>.
  • MFPLI01129S The option -optdli requires -dli.
  • MFPLI01130S The option -optincl requires -incl.
  • MFPLI01131S The -fdmaxp option requires an integer argument >= 15 & <= 31.
  • MFPLI01132S The -margins option must have an integer pair l,r with a valid range between 1,256.
  • MFPLI01133S The -fbmaxp option requires an integer argument 31 or 63.
  • MFPLI01134S Incorrect prefix option syntax. Correct syntax is: -prefix condition[,condition]... .
  • MFPLI01135S Invalid or null condition prefix "condition-name" specified.
  • MFPLI01136S The option-name option requires a string sub-option "conn" or "connected".
  • MFPLI01137S The MARGINI option requires an optionally quoted single-character.
  • MFPLI01138E The option-name option allows a maximum of 7 characters; truncated.
  • MFPLI01139S Incorrect -ctf option syntax, correct syntax is: -ctf [n,m] where n and m are optional positive integers.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01120S The option -ppcics requires -cics.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01121S The option -ppsql requires -sql <arg>.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01122S The option -ppdli requires -dli.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01123S The options -systemcics, -systemmvs, and -systemims must be mutually exclusive.

Only one of these options may be specified.
Resolution:
Remove the options not required.
Module:
PROCESS.PL1, XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01124S The options -cics, -sql, -dli, -systemmvs, -systemcics, and/or -systemims conflict with option-name

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01125S The -window option requires an integer argument.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01126S The option -ppincl requires -incl.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01127S The option -optcics requires -cics.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01128S The option -optsql requires -sql <arg>.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01129S The option -optdli requires -dli.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01130S The option -optincl requires -incl.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01131S The -fdmaxp option requires an integer argument >= 15 & <= 31.

Module:
PROCESS.PL1, XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01132S The -margins option must have an integer pair l,r with a valid range between 1,256.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01133S The -fbmaxp option requires an integer argument 31 or 63.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01134S Incorrect prefix option syntax. Correct syntax is: -prefix condition[,condition]... .

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01135S Invalid or null condition prefix "condition-name" specified.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01136S The option-name option requires a string sub-option "conn" or "connected".

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01137S The MARGINI option requires an optionally quoted single-character.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01138E The option-name option allows a maximum of 7 characters; truncated.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01139S Incorrect -ctf option syntax, correct syntax is: -ctf [n,m] where n and m are optional positive integers.

Module:
XINIFE.PL1
Parent topic: MFPLI01120 - MFPLI01139


MFPLI01140 - MFPLI01159

  • MFPLI01140S The -xmlcase option requires a string sub-option "upper" or "asis".
  • MFPLI01141S The -xmlattr option requires a string sub-option "apostrophe" or "quote".
  • MFPLI01142S The -dummy option requires a string sub-option "aligned" or "unaligned".
  • MFPLI01143S The -dc option requires "all" or a subset of the pattern "pattern-name" (w/o quotes).
  • MFPLI01150S Duplicate source FILE name: file-name
  • MFPLI01151S Unknown option: option-name
  • MFPLI01152S Missing source FILE name.
  • MFPLI01153S Conflicting list and source FILE names.
  • MFPLI01154S Conflicting source and object FILE names.
  • MFPLI01155S Conflicting list and object FILE names.
  • MFPLI01156S Inconsistent or duplicate option: option-name
  • MFPLI01157S Invalid option: option-name
  • MFPLI01158S Missing output FILE name.
  • MFPLI01159S Duplicate output FILE name: file-name
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01140S The -xmlcase option requires a string sub-option "upper" or "asis".

Module:
XINIFE.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01141S The -xmlattr option requires a string sub-option "apostrophe" or "quote".

Module:
XINIFE.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01142S The -dummy option requires a string sub-option "aligned" or "unaligned".

Module:
XINIFE.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01143S The -dc option requires "all" or a subset of the pattern "pattern-name" (w/o quotes).

Module:
XINIUT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01150S Duplicate source FILE name: file-name

Module:
XINIT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01151S Unknown option: option-name

Module:
XINIT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01152S Missing source FILE name.

Module:
PROCESS.PL1, XINIT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01153S Conflicting list and source FILE names.

Module:
XINIT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01154S Conflicting source and object FILE names.

Module:
XINIT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01155S Conflicting list and object FILE names.

Module:
XINIT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01156S Inconsistent or duplicate option: option-name

Module:
XINIAL.PL1, XINICG.PL1, XINIOP.PL1, XINIUT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01157S Invalid option: option-name

Module:
XINIAL.PL1, XINICG.PL1, XINIOP.PL1, XINIUT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01158S Missing output FILE name.

Module:
XINIUT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01159S Duplicate output FILE name: file-name

Module:
XINIUT.PL1
Parent topic: MFPLI01140 - MFPLI01159


MFPLI01160 - MFPLI01179

  • MFPLI01160S Duplicate list FILE name: file-name
  • MFPLI01161S The -errtext option requires an argument.
  • MFPLI01162S Duplicate errortext FILE name: file-name
  • MFPLI01163S Duplicate error FILE name: file-name
  • MFPLI01164S Missing include search path.
  • MFPLI01165S The -oplimit option requires a positive integer argument.
  • MFPLI01166S The -flag option requires an argument.
  • MFPLI01167S The -flag option requires I, W, E or S.
  • MFPLI01168S Duplicate adt FILE name: file-name
  • MFPLI01169S Invalid integer argument: insert-name
  • MFPLI01170S Amode option requires integer argument (24 or 31).
  • MFPLI01171W Max oplimit value is insert-number. insert-number used.
  • MFPLI01172S The -dcfout option requires an argument.
  • MFPLI01173W The -dcfout option specifies an unexpected path or filename.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01160S Duplicate list FILE name: file-name

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01161S The -errtext option requires an argument.

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01162S Duplicate errortext FILE name: file-name

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01163S Duplicate error FILE name: file-name

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01164S Missing include search path.

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01165S The -oplimit option requires a positive integer argument.

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01166S The -flag option requires an argument.

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01167S The -flag option requires I, W, E or S.

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01168S Duplicate adt FILE name: file-name

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01169S Invalid integer argument: insert-name

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01170S Amode option requires integer argument (24 or 31).

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01171W Max oplimit value is insert-number. insert-number used.

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01172S The -dcfout option requires an argument.

Module:
XINIUT.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01173W The -dcfout option specifies an unexpected path or filename.

Module:
DC.PL1
Parent topic: MFPLI01160 - MFPLI01179


MFPLI01200 - MFPLI01219

  • MFPLI01200S Could not find file insert-name in any directory in include path.
  • MFPLI01201S Invalid conversion required by argument number argument-number.
  • MFPLI01202S The BYVALUE attribute may be applied only to a parameter or a parameter descriptor.
  • MFPLI01203W An argument being passed by immediate value should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY, POINTER, CHAR of length <= 4, or BIT of length <= 32; a copy is being passed by reference.
  • MFPLI01204S The parameter insert-name has the BYVALUE attribute and is a multipositional parameter.
  • MFPLI01205S Invalid syntax in this statement. A insert-name was encountered unexpectedly. Check the previous statement for a missing semi-colon.
  • MFPLI01206S This condition requires an associated expression as in: COND(EXP).
  • MFPLI01207S Expression not permitted with this condition. Only FILE related conditions may have associated expressions.
  • MFPLI01208U Premature end of file encountered. Check for zero length file.
  • MFPLI01209E insert-name has been declared with conflicting attributes; the INITIAL attribute is not permitted with the GLOBALREF attribute; The INITIAL attribute will be ignored, and no initialization will be performed.
  • MFPLI01210S Invalid use of an asterisk in an expression. Array cross-sections are not supported.
  • MFPLI01211S ALLOCATE IN requires an AREA reference.
  • MFPLI01212S Subscripts are not valid in the reference to the REFER object, "insert-name". The referenced variable must not be an array or a member of a dimensioned STRUCTURE.
  • MFPLI01213S The STRUCTURE "insert-name" has been declared with REFER options but does not have a BASED storage class. REFER extents are only valid within BASED STRUCTUREs.
  • MFPLI01214S The object of a REFER option "insert-name" must precede the member whose size it defines, and it must be a member of the STRUCTURE being declared.
  • MFPLI01215S The reference to the REFER object, "insert-name" has been locator qualified. The referenced variable must not be locator qualified.
  • MFPLI01216S The variable that defines the size of the REFER extent, "insert-name" is a dimensioned STRUCTURE or an array. This variable must be a scalar.
  • MFPLI01217S A NONCONNECTED array cannot be passed as an argument to a PROCEDURE, function or input/output routine.
  • MFPLI01218S When array cross-sections are used within expressions or an assignment, all cross-sections must have exactly the same number of star extents.
    The number of dimensions and any star extents of each operand in an array expression or assignment must be the same.
  • MFPLI01219S A format has too many fields.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01200S Could not find file insert-name in any directory in include path.

Module:
PASS1.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01201S Invalid conversion required by argument number argument-number.

Module:
EXPEXP.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01202S The BYVALUE attribute may be applied only to a parameter or a parameter descriptor.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01203W An argument being passed by immediate value should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY, POINTER, CHAR of length <= 4, or BIT of length <= 32; a copy is being passed by reference.

Parent topic: MFPLI01200 - MFPLI01219


MFPLI01204S The parameter insert-name has the BYVALUE attribute and is a multipositional parameter.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01205S Invalid syntax in this statement. A insert-name was encountered unexpectedly. Check the previous statement for a missing semi-colon.

Module:
PASS1.PL1, LEXSTATE.IN
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01206S This condition requires an associated expression as in: COND(EXP).

Module:
PASS1.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01207S Expression not permitted with this condition. Only FILE related conditions may have associated expressions.

Module:
INTRP2.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01208U Premature end of file encountered. Check for zero length file.

Module:
PASS1.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01209E insert-name has been declared with conflicting attributes; the INITIAL attribute is not permitted with the GLOBALREF attribute; The INITIAL attribute will be ignored, and no initialization will be performed.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01210S Invalid use of an asterisk in an expression. Array cross-sections are not supported.

Parent topic: MFPLI01200 - MFPLI01219


MFPLI01211S ALLOCATE IN requires an AREA reference.

Module:
INTRP2.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01212S Subscripts are not valid in the reference to the REFER object, "insert-name". The referenced variable must not be an array or a member of a dimensioned STRUCTURE.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01213S The STRUCTURE "insert-name" has been declared with REFER options but does not have a BASED storage class. REFER extents are only valid within BASED STRUCTUREs.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01214S The object of a REFER option "insert-name" must precede the member whose size it defines, and it must be a member of the STRUCTURE being declared.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01215S The reference to the REFER object, "insert-name" has been locator qualified. The referenced variable must not be locator qualified.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01216S The variable that defines the size of the REFER extent, "insert-name" is a dimensioned STRUCTURE or an array. This variable must be a scalar.

Module:
DCLPCS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01217S A NONCONNECTED array cannot be passed as an argument to a PROCEDURE, function or input/output routine.

Module:
CONNEC.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01218S When array cross-sections are used within expressions or an assignment, all cross-sections must have exactly the same number of star extents.

The number of dimensions and any star extents of each operand in an array expression or assignment must be the same.
Resolution:
Ensure that the number of dimensions and star extents of both operands are the same.
Module:
COMPAT.PL1, VALASS.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01219S A format has too many fields.

Module:
PASS1.PL1
Parent topic: MFPLI01200 - MFPLI01219


MFPLI01220 - MFPLI01239

  • MFPLI01220S When array cross-sections are used within expressions or an assignment, all cross-sections must have exactly the same bound for each dimension. A lower bound differs in this expression.
    Not only must the difference between the lower and upper bounds of each dimension of both operands in an array expression or assignment be the same, but the lower bounds of each dimension must also be the same.
  • MFPLI01221S When array cross-sections are used within expressions or an assignment, all cross-sections must have exactly the same bound for each dimension. An upper bound differs in this expression.
    Not only must the difference between the lower and upper bounds of each dimension of both operands in an array expression or assignment be the same, but the upper bounds of each dimension must also be the same.
  • MFPLI01222S Array cross-sections are not allowed as arguments to built-in functions.
  • MFPLI01223S OPTIONS(MAIN) is only valid in a PROCEDURE statement.
  • MFPLI01224E Duplicate OPTIONS(MAIN) encountered; this one has been ignored.
  • MFPLI01225E An escape sequence starts at the end of a string. The escape will be ignored. Note that backslash cannot be used to escape a single quote; use two single quotes to include one quote in the string.
  • MFPLI01226E Undefined escape sequence. The backslash will be ignored.
  • MFPLI01227W Argument number argument-number is being passed via a dummy argument; an argument being passed BYVALUE should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY LIMITED, PTR, CHAR or BIT, each having a storage requirement of length-limit-bytes or less.
  • MFPLI01228S The dynamic setting of the RECSIZE(n) attribute for $ is not supported.
  • MFPLI01229E A hexadecimal escape sequence is not followed by any hexadecimal digits.
  • MFPLI01230S Unable to open file insert-name
  • MFPLI01231E The value of this escape sequence is too large.
  • MFPLI01232E The %%ONCE statement has no arguments and must appear only once in an include file.
  • MFPLI01233E insert-name is a conflicting storage class and is ignored.
  • MFPLI01234E The bounds of an array parameter must be specified by constants or asterisks. A constant 1 has been supplied.
  • MFPLI01235S The size of insert-name could not be evaluated at compile-time. STATIC variables must have constant size.
  • MFPLI01236S Invalid syntax in this statement. A character value of insert-name outside the ASCII range of 0-127 was found unexpectedly. Check for EBCDIC source characters.
  • MFPLI01237S Invalid syntax in this statement. A character value of insert-name was found unexpectedly.
  • MFPLI01238E The parameter insert-name has star extents which conflicts with OPTIONS(NODESCRIPTOR); ignoring the nodescriptor attribute.
  • MFPLI01239U Unrecoverable error. Exception in insert-name.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01220S When array cross-sections are used within expressions or an assignment, all cross-sections must have exactly the same bound for each dimension. A lower bound differs in this expression.

Not only must the difference between the lower and upper bounds of each dimension of both operands in an array expression or assignment be the same, but the lower bounds of each dimension must also be the same.
Resolution:
Ensure the lower bounds of each dimension of both operands are the same.
Module:
COMPAT.PL1, VALASS.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01221S When array cross-sections are used within expressions or an assignment, all cross-sections must have exactly the same bound for each dimension. An upper bound differs in this expression.

Not only must the difference between the lower and upper bounds of each dimension of both operands in an array expression or assignment be the same, but the upper bounds of each dimension must also be the same.
Resolution:
Ensure the upper bounds of each dimension of both operands are the same.
Module:
COMPAT.PL1, VALASS.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01222S Array cross-sections are not allowed as arguments to built-in functions.

Parent topic: MFPLI01220 - MFPLI01239


MFPLI01223S OPTIONS(MAIN) is only valid in a PROCEDURE statement.

Module:
PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01224E Duplicate OPTIONS(MAIN) encountered; this one has been ignored.

Module:
PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01225E An escape sequence starts at the end of a string. The escape will be ignored. Note that backslash cannot be used to escape a single quote; use two single quotes to include one quote in the string.

Module:
PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01226E Undefined escape sequence. The backslash will be ignored.

Module:
PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01227W Argument number argument-number is being passed via a dummy argument; an argument being passed BYVALUE should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY LIMITED, PTR, CHAR or BIT, each having a storage requirement of length-limit-bytes or less.

Module:
EXPARG.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01228S The dynamic setting of the RECSIZE(n) attribute for $ is not supported.

Parent topic: MFPLI01220 - MFPLI01239


MFPLI01229E A hexadecimal escape sequence is not followed by any hexadecimal digits.

Module:
PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01230S Unable to open file insert-name

Parent topic: MFPLI01220 - MFPLI01239


MFPLI01231E The value of this escape sequence is too large.

Module:
PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01232E The %%ONCE statement has no arguments and must appear only once in an include file.

Module:
PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01233E insert-name is a conflicting storage class and is ignored.

Module:
DCLPCS.PL1, PASS1.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01234E The bounds of an array parameter must be specified by constants or asterisks. A constant 1 has been supplied.

Module:
DCLPCS.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01235S The size of insert-name could not be evaluated at compile-time. STATIC variables must have constant size.

Module:
DCLPCS.PL1 (commented out)
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01236S Invalid syntax in this statement. A character value of insert-name outside the ASCII range of 0-127 was found unexpectedly. Check for EBCDIC source characters.

Parent topic: MFPLI01220 - MFPLI01239


MFPLI01237S Invalid syntax in this statement. A character value of insert-name was found unexpectedly.

Parent topic: MFPLI01220 - MFPLI01239


MFPLI01238E The parameter insert-name has star extents which conflicts with OPTIONS(NODESCRIPTOR); ignoring the nodescriptor attribute.

Module:
DCLPCS.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01239U Unrecoverable error. Exception in insert-name.

Module:
DCLPL1.PL1, EXPARG.PL1, LINKDO.PL1, PASS1.PL1, PASS2.PL1, PRCSCALL.PL1
Parent topic: MFPLI01220 - MFPLI01239


MFPLI01240 - MFPLI01259

  • MFPLI01240E A STRUCTURE can be initialized only by the separate initialization of its elementary names. The INITIAL attribute on insert-name is being ignored.
  • MFPLI01241S The NAMES ExtraLinguals and ExtraLinguals Uppercase strings must be the same length and should have a 1-1 character mapping.
  • MFPLI01242S The character insert-name cannot be added as a valid character in an identifier.
  • MFPLI01243S A character value of insert-name was found as part of an identifier. Check for possible ASCII or EBCDIC source characters, or use the Extralinguals compiler option -names.
  • MFPLI01244S A character value of insert-name cannot be used for the OR (|) or NOT (^) symbol.
    Only characters that are not part of the PL/I character set may be used as alternate or-signs or not-signs.
  • MFPLI01245S The argument of *PROCESS OR ('|') must be a character string of 1-7 chars.
  • MFPLI01246S The argument of *PROCESS NOT ('^') must be a character string of 1-7 chars.
  • MFPLI01247E The PACKAGENAME BUILTIN is undefined in this context.
  • MFPLI01248S An EXEC statement has been encountered; it should first be processed by the appropriate preprocessor.
  • MFPLI01249S The named constant insert-name could not be evaluated as a restricted expression at compile-time.
  • MFPLI01250E Named constants are NONASSIGNABLE.
  • MFPLI01251S The RECSIZE(n) attribute for insert-name must be an optionally signed integer, a named integer constant or a STATIC scalar with the attributes FIXED BIN(31).
  • MFPLI01252I The RECSIZE ENV attribute for insert-name.
  • MFPLI01253W The RECSIZE(n) attribute for insert-name is a named integer constant which is accepted as a language extension.
  • MFPLI01254S The second argument of the HEX built-in function must be of type char(1) nonvarying.
  • MFPLI01255S The character length of variable-name could not be evaluated as a restricted expression at compile-time. STATIC variables must have a constant size.
  • MFPLI01256S The third argument of the HEXIMAGE built-in function must be of type char(1) nonvarying.
  • MFPLI01257S Argument insert-name to the insert-name built-in must be a locator (OFFSET with explicit AREA declaration or a POINTER).
  • MFPLI01258W A dummy array argument has been created for argument number argument-number.
  • MFPLI01259E The PROCEDURENAME BUILTIN is undefined in this context.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01240E A STRUCTURE can be initialized only by the separate initialization of its elementary names. The INITIAL attribute on insert-name is being ignored.

Module:
DCLPCS.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01241S The NAMES ExtraLinguals and ExtraLinguals Uppercase strings must be the same length and should have a 1-1 character mapping.

Module:
DGMR2.PL1, PASS1.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01242S The character insert-name cannot be added as a valid character in an identifier.

Module:
DGMR2.PL1, PASS1.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01243S A character value of insert-name was found as part of an identifier. Check for possible ASCII or EBCDIC source characters, or use the Extralinguals compiler option -names.

Module:
PASS1.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01244S A character value of insert-name cannot be used for the OR (|) or NOT (^) symbol.

Only characters that are not part of the PL/I character set may be used as alternate or-signs or not-signs.
Resolution:
Correct the associated compiler option.
Module:
DGMR2.PL1, PASS1.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01245S The argument of *PROCESS OR ('|') must be a character string of 1-7 chars.

Parent topic: MFPLI01240 - MFPLI01259


MFPLI01246S The argument of *PROCESS NOT ('^') must be a character string of 1-7 chars.

Parent topic: MFPLI01240 - MFPLI01259


MFPLI01247E The PACKAGENAME BUILTIN is undefined in this context.

Module:
RESIS.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01248S An EXEC statement has been encountered; it should first be processed by the appropriate preprocessor.

Module:
PASS1.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01249S The named constant insert-name could not be evaluated as a restricted expression at compile-time.

Module:
DCLREE.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01250E Named constants are NONASSIGNABLE.

Module:
VALASS.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01251S The RECSIZE(n) attribute for insert-name must be an optionally signed integer, a named integer constant or a STATIC scalar with the attributes FIXED BIN(31).

Module:
DCLREE.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01252I The RECSIZE ENV attribute for insert-name.

Module:
DCLREE.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01253W The RECSIZE(n) attribute for insert-name is a named integer constant which is accepted as a language extension.

Module:
DCLREE.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01254S The second argument of the HEX built-in function must be of type char(1) nonvarying.

Module:
RESIS.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01255S The character length of variable-name could not be evaluated as a restricted expression at compile-time. STATIC variables must have a constant size.

Module:
DCLREE.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01256S The third argument of the HEXIMAGE built-in function must be of type char(1) nonvarying.

Module:
RESIS.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01257S Argument insert-name to the insert-name built-in must be a locator (OFFSET with explicit AREA declaration or a POINTER).

Module:
RESIS.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01258W A dummy array argument has been created for argument number argument-number.

Module:
EXPARG.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01259E The PROCEDURENAME BUILTIN is undefined in this context.

Module:
RESIS.PL1
Parent topic: MFPLI01240 - MFPLI01259


MFPLI01260 - MFPLI01279

  • MFPLI01260U Exception in ALLOC - ONCODE: "insert-name".
  • MFPLI01261S The total amount of STATIC data exceeds 2GB. Reduce the amount of STATIC data.
  • MFPLI01262U Internal compiler error; please contact Micro Focus Support Line.
  • MFPLI01263E A negative constant is being assigned to an UNSIGNED FIXED BIN variable.
  • MFPLI01265S Unexpected invalid assignment encountered. If no previous errors were diagnosed, contact Micro Focus Support Line.
  • MFPLI01266S The attributes of CONTROLLED parameters and CONTROLLED arguments must match exactly.
  • MFPLI01267E The resultant size of the STRING built-in is > the implementation limit of 32K.
  • MFPLI01268W "insert-name" may not be initialized when first used.
  • MFPLI01269S The argument "insert-name" has type ENTRY, which is invalid for a corresponding parameter type of ENTRY LIMITED.
  • MFPLI01270S Assignment to an ENTRY LIMITED target requires the source to be ENTRY LIMITED or a non-nested ENTRY constant.
  • MFPLI01271E IF, WHILE, UNTIL or WHEN requires a BIT(1) expression when NOLAXIF is in effect.
  • MFPLI01272E A BIT(1) assignment to a non-BIT(1) target appears as-if a multiple right-to-left assignment may have been intended, which is not allowed when NOLAXIF is in effect; use parentheses to avoid this diagnostic.
  • MFPLI01273S Parameter descriptor is not a STRUCTURE of the proper shape to receive the STRUCTURE argument being passed to it.
  • MFPLI01274W An argument being passed by immediate value should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY LIMITED, PTR, OFFSET, CHAR or BIT, each with a size of 4-bytes of less; "insert-name" is being passed as-if enclosed by parentheses.
  • MFPLI01275W An argument being passed by immediate value should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY LIMITED, PTR, or OFFSET, or CHAR or BIT with a size of 8-bytes of less; "insert-name" is being passed as-if enclosed by parentheses.
  • MFPLI01276S The argument to the POINTERVALUE built-in must be computational.
  • MFPLI01277S The argument to the BINARYVALUE built-in must be of type POINTER or OFFSET.
  • MFPLI01278W "insert-name" is being initialized to EMPTY; conflicting initial attribute ignored.
  • MFPLI01279E The CONSTANT attribute may only be applied to FILE or ENTRY; ignored.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01260U Exception in ALLOC - ONCODE: "insert-name".

Module:
ALLOC.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01261S The total amount of STATIC data exceeds 2GB. Reduce the amount of STATIC data.

Module:
AZEROF.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01262U Internal compiler error; please contact Micro Focus Support Line.

Module:
ALSTK.PL1, RESIS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01263E A negative constant is being assigned to an UNSIGNED FIXED BIN variable.

Module:
ALSTK.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01265S Unexpected invalid assignment encountered. If no previous errors were diagnosed, contact Micro Focus Support Line.

Module:
VALASS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01266S The attributes of CONTROLLED parameters and CONTROLLED arguments must match exactly.

Module:
MATCHDCL.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01267E The resultant size of the STRING built-in is > the implementation limit of 32K.

Module:
EXPLPS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01268W "insert-name" may not be initialized when first used.

Module:
WRITET.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01269S The argument "insert-name" has type ENTRY, which is invalid for a corresponding parameter type of ENTRY LIMITED.

Module:
MATCHDCL.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01270S Assignment to an ENTRY LIMITED target requires the source to be ENTRY LIMITED or a non-nested ENTRY constant.

Module:
VALASS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01271E IF, WHILE, UNTIL or WHEN requires a BIT(1) expression when NOLAXIF is in effect.

Module:
INTRP2.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01272E A BIT(1) assignment to a non-BIT(1) target appears as-if a multiple right-to-left assignment may have been intended, which is not allowed when NOLAXIF is in effect; use parentheses to avoid this diagnostic.

Module:
VALASS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01273S Parameter descriptor is not a STRUCTURE of the proper shape to receive the STRUCTURE argument being passed to it.

Module:
MATCHDCL.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01274W An argument being passed by immediate value should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY LIMITED, PTR, OFFSET, CHAR or BIT, each with a size of 4-bytes of less; "insert-name" is being passed as-if enclosed by parentheses.

Parent topic: MFPLI01260 - MFPLI01279


MFPLI01275W An argument being passed by immediate value should be a scalar of type FIXED BIN, FLOAT BIN, ENTRY LIMITED, PTR, or OFFSET, or CHAR or BIT with a size of 8-bytes of less; "insert-name" is being passed as-if enclosed by parentheses.

Parent topic: MFPLI01260 - MFPLI01279


MFPLI01276S The argument to the POINTERVALUE built-in must be computational.

Module:
RESIS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01277S The argument to the BINARYVALUE built-in must be of type POINTER or OFFSET.

Module:
RESIS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01278W "insert-name" is being initialized to EMPTY; conflicting initial attribute ignored.

Module:
DCLPCS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01279E The CONSTANT attribute may only be applied to FILE or ENTRY; ignored.

Module:
DCLPCS.PL1
Parent topic: MFPLI01260 - MFPLI01279


MFPLI01280 - MFPLI01299

  • MFPLI01280E The second & third arguments applied to SUBSTR are out-of-range.
  • MFPLI01281E The second argument applied to SUBSTR is <= 0; 1 will be used instead.
  • MFPLI01282E The second argument applied to SUBSTR is too large; this will result in a zero-length string.
  • MFPLI01283S The first argument to the EDIT built-in must be computational.
  • MFPLI01284S The second argument to the EDIT built-in must character type.
  • MFPLI01285S The ITERATE statement is only valid within an iterative DO-group.
  • MFPLI01286E ITERATE consistency error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
  • MFPLI01287S The first operand of the PICSPEC built-in must be of type CHARACTER NONVARYING.
  • MFPLI01288S The second operand of the PICSPEC built-in must be character-string literal with a valid picture specification.
  • MFPLI01289S The length of PICPSEC operand-1 is not a constant length.
  • MFPLI01290S The length of PICPSEC operand-1 does not match the picture specification length of operand-2.
  • MFPLI01291S READ INTO a named constant is not allowed.
  • MFPLI01292E insert-name can only be applied to structure members; ignored.
  • MFPLI01293S XMLATTR cannot be applied to "insert-name"; XMLATTR is invalid when applied to structures or unions.
  • MFPLI01294S insert-name cannot be applied to unnamed structure members.
  • MFPLI01295S XMLATTR cannot be applied to "insert-name"; XMLATTR is invalid unless the previous element at the same level has the XMLATTR attribute.
  • MFPLI01296S XMLOMIT cannot be applied to "insert-name"; XMLOMIT is invalid when applied to structures or unions.
  • MFPLI01297S XMLATTR cannot be applied to "insert-name"; XMLATTR is invalid when applied to arrays.
  • MFPLI01298S "insert-name" has NONASSIGNABLE attribute on assignment.
  • MFPLI01299S "insert-name" contains NONASSIGNABLE members on assignment.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01280E The second & third arguments applied to SUBSTR are out-of-range.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01281E The second argument applied to SUBSTR is <= 0; 1 will be used instead.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01282E The second argument applied to SUBSTR is too large; this will result in a zero-length string.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01283S The first argument to the EDIT built-in must be computational.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01284S The second argument to the EDIT built-in must character type.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01285S The ITERATE statement is only valid within an iterative DO-group.

Module:
PASS1.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01286E ITERATE consistency error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Module:
PASS1.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01287S The first operand of the PICSPEC built-in must be of type CHARACTER NONVARYING.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01288S The second operand of the PICSPEC built-in must be character-string literal with a valid picture specification.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01289S The length of PICPSEC operand-1 is not a constant length.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01290S The length of PICPSEC operand-1 does not match the picture specification length of operand-2.

Module:
RESIS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01291S READ INTO a named constant is not allowed.

Module:
PRODIO.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01292E insert-name can only be applied to structure members; ignored.

Module:
DCLPCS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01293S XMLATTR cannot be applied to "insert-name"; XMLATTR is invalid when applied to structures or unions.

Module:
DCLPCS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01294S insert-name cannot be applied to unnamed structure members.

Module:
DCLPCS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01295S XMLATTR cannot be applied to "insert-name"; XMLATTR is invalid unless the previous element at the same level has the XMLATTR attribute.

Module:
DCLPCS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01296S XMLOMIT cannot be applied to "insert-name"; XMLOMIT is invalid when applied to structures or unions.

Module:
DCLPCS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01297S XMLATTR cannot be applied to "insert-name"; XMLATTR is invalid when applied to arrays.

Module:
DCLPCS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01298S "insert-name" has NONASSIGNABLE attribute on assignment.

Module:
VALASS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01299S "insert-name" contains NONASSIGNABLE members on assignment.

Module:
VALASS.PL1
Parent topic: MFPLI01280 - MFPLI01299


MFPLI01300 - MFPLI01319

  • MFPLI01300S The REPLACEBY2 built-in second argument must be twice the length of the third argument.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01300S The REPLACEBY2 built-in second argument must be twice the length of the third argument.

Module:
RESIS.PL1
Parent topic: MFPLI01300 - MFPLI01319


MFPLI01980 - MFPLI01999

  • MFPLI01998E DC data file has invalid ("signature-value") signature. Contact Micro Focus Support.
    Data Collection file has invalid signature signature-value.
  • MFPLI01999E condition-name condition raised. ONCODE=oncode-value ONSUBCODE=onsubcode-value for function function-name. Contact Micro Focus Support.
    Condition condition-name raised with ONCODE oncode-value and ONSUBCODE onsubcode-value for function function-name.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI01998E DC data file has invalid ("signature-value") signature. Contact Micro Focus Support.

Data Collection file has invalid signature signature-value.
Resolution:
Contact Micro Focus Support.
Module:
MFPLINFO.PL1 (hard-coded)
Parent topic: MFPLI01980 - MFPLI01999


MFPLI01999E condition-name condition raised. ONCODE=oncode-value ONSUBCODE=onsubcode-value for function function-name. Contact Micro Focus Support.

Condition condition-name raised with ONCODE oncode-value and ONSUBCODE onsubcode-value for function function-name.
Resolution:
Contact Micro Focus Support.
Module:
MFPLINFO.PL1 (hard-coded)
Parent topic: MFPLI01980 - MFPLI01999


MFPLI02000 - MFPLI02019

  • MFPLI02000U Internal consistency error: invalid symbol table access. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: invalid symbol table access.
  • MFPLI02001U Symbol table overflow. The total number of internal symbol table pages exceeds the implementation's limit. Reduce the number and size of names, constants, extent-expressions, and argument or returns descriptors.
    Symbol table overflow.
  • MFPLI02002U Symbol table overflow. Please contact Micro Focus Support Line.
    Symbol table overflow.
  • MFPLI02003U Too many errors. The total number of diagnosed errors exceeds the error-limit limit. processing aborted.
    The number of errors of the severity specified in the -maxmsg option has been exceeded.
  • MFPLI02004U Internal consistency error: too many open files. The number of concurrently open files needed to continue processing exceeds the implementation's limit. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: too many open files.
  • MFPLI02005U Internal consistency error: internal value table overflow. Reduce the complexity of large expressions. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: internal value table overflow.
  • MFPLI02006E Internal consistency error: attempt to free an already freed internal value. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: attempt to free an already freed internal value.
  • MFPLI02007U Internal consistency error: out of memory. Not enough heap storage is available from the system to continue processing. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: out of memory.
  • MFPLI02008U Internal consistency: unable to copy internal list. Attempt to copy an internal list failed when the new list could not be extended to the required size. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency: unable to copy internal list.
  • MFPLI02009U Internal consistency error: invalid type for target conversion. An internal conversion failed when called with an unknown data type. If this message persists, contact Micro Focus Support Line.
    Internal consistency error: invalid type for target conversion.
  • MFPLI02010U Internal consistency error: invalid size for target conversion. An internal conversion to target representation failed when called with an invalid size value.
  • MFPLI02011U Internal consistency error: invalid size for host conversion. An internal conversion to host representation failed when called with an invalid size value.
  • MFPLI02012U Internal IL overflow. Unable to continue processing. Try breaking the compilation unit apart into smaller modules if possible, or reducing the number of executable statements. If this message persists, contact Micro Focus Support Line.
    Internal input list overflow.
  • MFPLI02013U Unable to open file "file-name". Include file nesting limit exceeded. Reduce the nesting level of included source files.
    Unable to open file "file-name".
  • MFPLI02014U Internal heap storage exhausted. Unable to continue processing. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal heap storage exhausted.
  • MFPLI02015U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFPLI02016U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFPLI02017W Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFPLI02018U Internal consistency error. Unable to open existing node list file. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFPLI02019W Internal consistency error. Unable to create temp file for new node list. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI02000U Internal consistency error: invalid symbol table access. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: invalid symbol table access.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
OBJOUT.PL1, STBV.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02001U Symbol table overflow. The total number of internal symbol table pages exceeds the implementation's limit. Reduce the number and size of names, constants, extent-expressions, and argument or returns descriptors.

Symbol table overflow.

The total number of internal symbol table pages exceeds the implementation's limit.

Resolution:
Reduce the number and size of names, constants, extent-expressions, and argument or returns descriptors.
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02002U Symbol table overflow. Please contact Micro Focus Support Line.

Symbol table overflow.
Resolution:
Please contact Micro Focus Support Line.
Module:
STBV.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02003U Too many errors. The total number of diagnosed errors exceeds the error-limit limit. processing aborted.

The number of errors of the severity specified in the -maxmsg option has been exceeded.
Resolution:
Either amend the source to reduce the number of errors of this severity diagnosed or increase the number of messages specified in the -maxmsg option.
Module:
XERROR.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02004U Internal consistency error: too many open files. The number of concurrently open files needed to continue processing exceeds the implementation's limit. If this message persists, contact Micro Focus Support Line.

Internal consistency error: too many open files.

The number of concurrently open files needed to continue processing exceeds the implementation's limit.

Resolution:
If this message persists, contact Micro Focus Support Line.
Module:
IO_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02005U Internal consistency error: internal value table overflow. Reduce the complexity of large expressions. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: internal value table overflow.

Possible compiler error.

Resolution:
Reduce the complexity of large expressions. Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
VAL_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02006E Internal consistency error: attempt to free an already freed internal value. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: attempt to free an already freed internal value.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
VAL_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02007U Internal consistency error: out of memory. Not enough heap storage is available from the system to continue processing. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error: out of memory.

Not enough heap storage is available from the system to continue processing.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
MEM_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02008U Internal consistency: unable to copy internal list. Attempt to copy an internal list failed when the new list could not be extended to the required size. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency: unable to copy internal list.

Attempt to copy an internal list failed when the new list could not be extended to the required size.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02009U Internal consistency error: invalid type for target conversion. An internal conversion failed when called with an unknown data type. If this message persists, contact Micro Focus Support Line.

Internal consistency error: invalid type for target conversion.

An internal conversion failed when called with an unknown data type.

Resolution:
If this message persists, contact Micro Focus Support Line.
Module:
CVT_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02010U Internal consistency error: invalid size for target conversion. An internal conversion to target representation failed when called with an invalid size value.

Module:
CVT_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02011U Internal consistency error: invalid size for host conversion. An internal conversion to host representation failed when called with an invalid size value.

Module:
CVT_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02012U Internal IL overflow. Unable to continue processing. Try breaking the compilation unit apart into smaller modules if possible, or reducing the number of executable statements. If this message persists, contact Micro Focus Support Line.

Internal input list overflow.

Unable to continue processing.

Resolution:
Try breaking the compilation unit apart into smaller modules if possible, or reducing the number of executable statements. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02013U Unable to open file "file-name". Include file nesting limit exceeded. Reduce the nesting level of included source files.

Unable to open file "file-name".

Include file nesting limit exceeded.

Resolution:
Reduce the nesting level of included source files.
Module:
SRC_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02014U Internal heap storage exhausted. Unable to continue processing. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal heap storage exhausted.

Unable to continue processing. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
HEAPD.PL1, HEAPM.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02015U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
MAIN.PL1, MFPLIZ.PL1, OBJ_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02016U Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
OBJ_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02017W Internal consistency error. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
OBJ_U.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02018U Internal consistency error. Unable to open existing node list file. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Unable to open existing node list file. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02019W Internal consistency error. Unable to create temp file for new node list. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Unable to create temp file for new node list. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFPLI02000 - MFPLI02019


MFPLI02020 - MFPLI02039

  • MFPLI02020U Internal consistency error. List node size exceeds limit. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFPLI02021U Internal consistency error. Node list file is an unrecognized format. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.
    Internal consistency error.
  • MFPLI02022U Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE. Reduce the size or complexity of the PROCEDURE that contains this statement.
    Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI02020U Internal consistency error. List node size exceeds limit. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

List node size exceeds limit. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFPLI02020 - MFPLI02039


MFPLI02021U Internal consistency error. Node list file is an unrecognized format. Possible compiler error. Correct all other errors. If this message persists, contact Micro Focus Support Line.

Internal consistency error.

Node list file is an unrecognized format. Possible compiler error.

Resolution:
Correct all other errors. If this message persists, contact Micro Focus Support Line.
Module:
NLSTD.PL1
Parent topic: MFPLI02020 - MFPLI02039


MFPLI02022U Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE. Reduce the size or complexity of the PROCEDURE that contains this statement.

Excessive size and complexity of a PROCEDURE caused the number of intermediate operators to exceed the compiler's limit for a single PROCEDURE.
Resolution:
Reduce the size or complexity of the PROCEDURE that contains this statement.
Module:
XOPERU.PL1
Parent topic: MFPLI02020 - MFPLI02039


MFPLI02060 - MFPLI02079

  • MFPLI02070S Unable to open file: file-name
  • MFPLI02071S Compilation interrupted ...
  • MFPLI02072S I/O error on file
  • MFPLI02073S Unable to open file
  • MFPLI02074S Read error: Line too long
  • MFPLI02075S System error
  • MFPLI02076S Compilation aborted.
  • MFPLI02077S Compiling file
  • MFPLI02078S compiled successfully.
  • MFPLI02079S The -maxmsg option requires I|W|E|S[,n]
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI02070S Unable to open file: file-name

Module:
ERR_U.PL1, STARP.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02071S Compilation interrupted ...

Module:
ERR_U.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02072S I/O error on file

Module:
ERR_U.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02073S Unable to open file

Module:
ERR_U.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02074S Read error: Line too long

Module:
ERR_U.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02075S System error

Module:
ERR_U.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02076S Compilation aborted.

Module:
ERR_U.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02077S Compiling file

Parent topic: MFPLI02060 - MFPLI02079


MFPLI02078S compiled successfully.

Parent topic: MFPLI02060 - MFPLI02079


MFPLI02079S The -maxmsg option requires I|W|E|S[,n]

Module:
XINIUT.PL1
Parent topic: MFPLI02060 - MFPLI02079


MFPLI02080 - MFPLI02099

  • MFPLI02080W The -option-name option is deprecated and may be removed in a future product release or update.
  • MFPLI02081S Only -rc 0,0 OR -rc 4,0 OR -rc 8,0 is allowed; -rc 4,0 is the default.
  • MFPLI02082I No object file produced.
  • MFPLI02083I Object file produced.
  • MFPLI02084U Unrecoverable error encountered.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI02080W The -option-name option is deprecated and may be removed in a future product release or update.

Module:
XINIFE.PL1
Parent topic: MFPLI02080 - MFPLI02099


MFPLI02081S Only -rc 0,0 OR -rc 4,0 OR -rc 8,0 is allowed; -rc 4,0 is the default.

Module:
XINIUT.PL1
Parent topic: MFPLI02080 - MFPLI02099


MFPLI02082I No object file produced.

Parent topic: MFPLI02080 - MFPLI02099


MFPLI02083I Object file produced.

Parent topic: MFPLI02080 - MFPLI02099


MFPLI02084U Unrecoverable error encountered.

Module:
XINIT.PL1
Parent topic: MFPLI02080 - MFPLI02099


MFPLI03000 - MFPLI03019

  • MFPLI03000S Optimizer internal consistency error.
  • MFPLI03001E The optimizer detected an infinite loop of GOTO operations.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI03000S Optimizer internal consistency error.

Parent topic: MFPLI03000 - MFPLI03019


MFPLI03001E The optimizer detected an infinite loop of GOTO operations.

Module:
OPTMIZ.PL1
Parent topic: MFPLI03000 - MFPLI03019


MFPLI04020 - MFPLI04039

  • MFPLI04032U Previous errors prevent code generation. If no previous errors were diagnosed, contact Micro Focus Support Line.
    Previous errors prevent code generation.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI04032U Previous errors prevent code generation. If no previous errors were diagnosed, contact Micro Focus Support Line.

Previous errors prevent code generation.
Resolution:
If no previous errors were diagnosed, contact Micro Focus Support Line.
Module:
PL1UTL.PL1, UNPOPD.PL1
Parent topic: MFPLI04020 - MFPLI04039


MFPLI04040 - MFPLI04059

  • MFPLI04042U Possible compiler error. The code generator is unable to find a value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI04042U Possible compiler error. The code generator is unable to find a value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator is unable to find a value node.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CODGEN.PL1
Parent topic: MFPLI04040 - MFPLI04059


MFPLI04200 - MFPLI04219

  • MFPLI04200W Possible compiler error. The code generator has node-count unclaimed nodes. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI04200W Possible compiler error. The code generator has node-count unclaimed nodes. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator has node-count unclaimed nodes.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CKLOST.PL1
Parent topic: MFPLI04200 - MFPLI04219


MFPLI04220 - MFPLI04239

  • MFPLI04224S A member of a dimensioned STRUCTURE is considered to be an interleaved array and as such cannot be used in an aggregate assignment or other context that requires CONNECTED storage.
  • MFPLI04227U Possible compiler error. The code generator's save-exit stack has overflowed. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04230S Possible compiler error. The code generator tried to free an already freed value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI04224S A member of a dimensioned STRUCTURE is considered to be an interleaved array and as such cannot be used in an aggregate assignment or other context that requires CONNECTED storage.

Module:
P3SIZE.PL1
Parent topic: MFPLI04220 - MFPLI04239


MFPLI04227U Possible compiler error. The code generator's save-exit stack has overflowed. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator's save-exit stack has overflowed.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
UNPACK.PL1
Parent topic: MFPLI04220 - MFPLI04239


MFPLI04230S Possible compiler error. The code generator tried to free an already freed value node. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator tried to free an already freed value node.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CTD3.PL1
Parent topic: MFPLI04220 - MFPLI04239


MFPLI04440 - MFPLI04459

  • MFPLI04447U The amount of static storage exceeds the implementation's limit. Reduce the size or number of static variables and recompile.
    The amount of static storage exceeds the implementation's limit.
  • MFPLI04450S Possible compiler error. The code generator cannot generate code for intermediate opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04452S Possible compiler error. The code generator tried to move or convert an operand to operand class operand-class. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04453S Possible compiler error. The code generator tried to convert a node to itself. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04454S Possible compiler error. The code generator has no MOVE pattern for moving data to node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04455S Possible compiler error. The code generator found a bad address mode address-mode. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04456S Possible compiler error. The code generator patterns specify OFFSET with arg opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04457S Possible compiler error. The code generator cannot evaluate pattern opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04458S Possible compiler error. The code generator FREE_VALUE op found pattern opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04459S Possible compiler error. The code generator tried to address node node-name without loading its index or base register. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI04447U The amount of static storage exceeds the implementation's limit. Reduce the size or number of static variables and recompile.

The amount of static storage exceeds the implementation's limit.
Resolution:
Reduce the size or number of static variables and recompile.
Module:
TOCFNS.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04450S Possible compiler error. The code generator cannot generate code for intermediate opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator cannot generate code for intermediate opcode operation-code.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
SRCHI.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04452S Possible compiler error. The code generator tried to move or convert an operand to operand class operand-class. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator tried to move or convert an operand to operand class operand-class.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CONV.PL1, MOVE.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04453S Possible compiler error. The code generator tried to convert a node to itself. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator tried to convert a node to itself.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CONV.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04454S Possible compiler error. The code generator has no MOVE pattern for moving data to node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator has no MOVE pattern for moving data to node node-name.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
MOVE.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04455S Possible compiler error. The code generator found a bad address mode address-mode. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator found a bad address mode address-mode.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
EMITOP.PL1, UNPOPD.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04456S Possible compiler error. The code generator patterns specify OFFSET with arg opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator patterns specify OFFSET with arg opcode operation-code.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
UNPACK.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04457S Possible compiler error. The code generator cannot evaluate pattern opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator cannot evaluate pattern opcode operation-code.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
EVLPAT.PL1, UNPACK.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04458S Possible compiler error. The code generator FREE_VALUE op found pattern opcode operation-code. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator FREE_VALUE op found pattern opcode operation-code.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
UNPACK.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04459S Possible compiler error. The code generator tried to address node node-name without loading its index or base register. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator tried to address node node-name without loading its index or base register.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
UNPOPD.PL1
Parent topic: MFPLI04440 - MFPLI04459


MFPLI04460 - MFPLI04479

  • MFPLI04462S Possible compiler error. The code generator cannot retransform node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04463S Possible compiler error. The code generator cannot set up a memory address to fetch node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04464S Possible compiler error. The code generator cannot find pattern node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04465S Possible compiler error. The code generator cannot compute size for data type data-type. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04466S Possible compiler error. The code generator length meta-op found an argument of argument-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04467S Possible compiler error. The code generator tried to count down a non-busy node from line line-number. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
  • MFPLI04468S The current module requires more than 2GB bytes of AUTOMATIC storage. Reduce the size or number of AUTOMATIC variables and recompile.
    The current module requires more than 2GB bytes of AUTOMATIC storage.
  • MFPLI04469S Possible compiler error. The code generator found a non-busy temp when counting down node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Possible compiler error.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI04462S Possible compiler error. The code generator cannot retransform node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator cannot retransform node node-name.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
TRANSF.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04463S Possible compiler error. The code generator cannot set up a memory address to fetch node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator cannot set up a memory address to fetch node node-name.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
SETA.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04464S Possible compiler error. The code generator cannot find pattern node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator cannot find pattern node node-name.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
BRCOMP.PL1, CONV.PL1, CTD3.PL1, EVLPAT.PL1, FPNODE.PL1, GENCAL.PL1, MOVE.PL1, PEEP.PL1, SELECT.PL1, SETA.PL1, SRCHI.PL1, SUBST.PL1, TRANSF.PL1, UNPACK.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04465S Possible compiler error. The code generator cannot compute size for data type data-type. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator cannot compute size for data type data-type.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
P3SIZE.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04466S Possible compiler error. The code generator length meta-op found an argument of argument-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator length meta-op found an argument of argument-name.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
UNPACK.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04467S Possible compiler error. The code generator tried to count down a non-busy node from line line-number. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator tried to count down a non-busy node from line line-number.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CTD3.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04468S The current module requires more than 2GB bytes of AUTOMATIC storage. Reduce the size or number of AUTOMATIC variables and recompile.

The current module requires more than 2GB bytes of AUTOMATIC storage.
Resolution:
Reduce the size or number of AUTOMATIC variables and recompile.
Module:
AXLATE.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04469S Possible compiler error. The code generator found a non-busy temp when counting down node node-name. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Possible compiler error.

The code generator found a non-busy temp when counting down node node-name.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CTD3.PL1, UNPACK.PL1
Parent topic: MFPLI04460 - MFPLI04479


MFPLI04500 - MFPLI04519

  • MFPLI04500E Consistency error error-name. Possible compiler error. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Consistency error error-name.
  • MFPLI04501S Code generator internal error. error-name. Possible compiler error. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
    Code generator internal error.
  • MFPLI04502E EXTERNAL name "external-name" has been defined more than once. Check for multiple entries with the same name, a variable with the same name as an ENTRY, or a variable initialized in more than one place.
    EXTERNAL name "external-name" has been defined more than once.
  • MFPLI04503U Unable to create essential compiler temporary files. Please ensure you have appropriate read/write permissions for the current working directory and/or your TMPDIR environment variable is set correctly.
    Unable to create essential compiler temporary files.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI04500E Consistency error error-name. Possible compiler error. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Consistency error error-name.

Possible compiler error.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CGGCER.PL1, OEDERR.PL1
Parent topic: MFPLI04500 - MFPLI04519


MFPLI04501S Code generator internal error. error-name. Possible compiler error. Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.

Code generator internal error.

error-name. Possible compiler error.

Resolution:
Correct all program errors and recompile. If this message persists, contact Micro Focus Support Line.
Module:
CGGCER.PL1
Parent topic: MFPLI04500 - MFPLI04519


MFPLI04502E EXTERNAL name "external-name" has been defined more than once. Check for multiple entries with the same name, a variable with the same name as an ENTRY, or a variable initialized in more than one place.

EXTERNAL name "external-name" has been defined more than once.
Resolution:
Check for multiple entries with the same name, a variable with the same name as an ENTRY, or a variable initialized in more than one place.
Module:
DEFESD.PL1
Parent topic: MFPLI04500 - MFPLI04519


MFPLI04503U Unable to create essential compiler temporary files. Please ensure you have appropriate read/write permissions for the current working directory and/or your TMPDIR environment variable is set correctly.

Unable to create essential compiler temporary files.
Resolution:
Please ensure you have appropriate read/write permissions for the current working directory and/or your TMPDIR environment variable is set correctly.
Module:
P3IOIN.PL1
Parent topic: MFPLI04500 - MFPLI04519


MFPLI10000 - MFPLI10019

  • MFPLI10001E This statement contains an unsupported condition "condition-name".
    The conditions CHECK, NAME, PENDING and TRANSMIT are not supported.
  • MFPLI10002E This statement contains an unsupported condition prefix "condition-name".
    The condition prefixes CHECK, NOCONVERSION, NOFIXEDOVERFLOW, NOOVERFLOW, NOUNDERFLOW, NOZERODIVIDE and NOINVALIDOP are not supported.
  • MFPLI10003E EVENT option not supported.
    Multitasking not supported.
  • MFPLI10004E TASK option not supported.
    Multitasking not supported.
  • MFPLI10005E PRIORITY option not supported.
    Multitasking not supported.
  • MFPLI10007E COPY option not supported.
    The COPY option on a GET statement is not supported.
  • MFPLI10009S LOCATE statement not supported.
    Locate mode output not supported.
  • MFPLI10012E BACKWARDS attribute not supported.
    BACKWARDS files used for datasets on magnetic tape are not supported.
  • MFPLI10013E EXCLUSIVE attribute not supported.
    EXCLUSIVE files are not supported.
  • MFPLI10014E TRANSIENT attribute not supported.
    TRANSIENT files used for teleprocessing applications are not supported.
  • MFPLI10015E BACKWARDS option not supported.
    BACKWARDS files used for datasets on magnetic tape are not supported.
  • MFPLI10016E EXCLUSIVE option not supported.
    EXCLUSIVE files are not supported.
  • MFPLI10017E TRANSIENT option not supported.
    TRANSIENT files used for teleprocessing applications are not supported.
  • MFPLI10018E NOLOCK option not supported.
    EXCLUSIVE files are not supported.
  • MFPLI10019S UNLOCK statement not supported.
    EXCLUSIVE files are not supported.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI10001E This statement contains an unsupported condition "condition-name".

The conditions CHECK, NAME, PENDING and TRANSMIT are not supported.
Resolution:
Remove dependencies on unsupported conditions.
Module:
PASS1.PL1
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10002E This statement contains an unsupported condition prefix "condition-name".

The condition prefixes CHECK, NOCONVERSION, NOFIXEDOVERFLOW, NOOVERFLOW, NOUNDERFLOW, NOZERODIVIDE and NOINVALIDOP are not supported.
Resolution:
Remove dependencies on unsupported prefix conditions.
Module:
PASS1.PL1
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10003E EVENT option not supported.

Multitasking not supported.
Resolution:
Remove multitasking processing.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10004E TASK option not supported.

Multitasking not supported.
Resolution:
Remove multitasking processing.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10005E PRIORITY option not supported.

Multitasking not supported.
Resolution:
Remove multitasking processing.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10007E COPY option not supported.

The COPY option on a GET statement is not supported.
Resolution:
Remove the COPY option and emulate the behaviour by adding a suitable PUT statement after the GET statement.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10009S LOCATE statement not supported.

Locate mode output not supported.
Resolution:
Use move mode output using WRITE statement instead.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10012E BACKWARDS attribute not supported.

BACKWARDS files used for datasets on magnetic tape are not supported.
Resolution:
Remove dependency on BACKWARDS files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10013E EXCLUSIVE attribute not supported.

EXCLUSIVE files are not supported.
Resolution:
Remove dependency on EXCLUSIVE files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10014E TRANSIENT attribute not supported.

TRANSIENT files used for teleprocessing applications are not supported.
Resolution:
Remove dependency on TRANSIENT files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10015E BACKWARDS option not supported.

BACKWARDS files used for datasets on magnetic tape are not supported.
Resolution:
Remove dependency on BACKWARDS files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10016E EXCLUSIVE option not supported.

EXCLUSIVE files are not supported.
Resolution:
Remove dependency on EXCLUSIVE files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10017E TRANSIENT option not supported.

TRANSIENT files used for teleprocessing applications are not supported.
Resolution:
Remove dependency on TRANSIENT files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10018E NOLOCK option not supported.

EXCLUSIVE files are not supported.
Resolution:
Remove dependency on EXCLUSIVE files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10019S UNLOCK statement not supported.

EXCLUSIVE files are not supported.
Resolution:
Remove dependency on EXCLUSIVE files.
Module:
PLSP1.TB
Parent topic: MFPLI10000 - MFPLI10019


MFPLI10020 - MFPLI10039

  • MFPLI10020S WAIT statement not supported.
    Multitasking is not supported.
  • MFPLI10021E EVENT attribute not supported.
    Multitasking is not supported.
  • MFPLI10022E TASK attribute not supported.
    Multitasking is not supported.
  • MFPLI10023E GENERIC attribute not supported.
    Selection between entries depending on the attributes of the arguments is not supported.
  • MFPLI10025E COMPLEX attribute not supported.
    COMPLEX number processing is not supported.
  • MFPLI10032S A NONCONNECTED array reference used as an argument that is passed by-reference to a parameter that has constant extents is not yet supported; argument number argument-number.
    A NONCONNECTED array reference used as an argument can only be passed by-reference to a parameter with adjustable extents.
  • MFPLI10034S DEFINE ORDINAL not supported.
  • MFPLI10035S DEFINE STRUCTURE not supported.
  • MFPLI10036S DIM, LBOUND or HBOUND built-ins with expression arguments not supported.
  • MFPLI10038S PICTURE symbols (E, F, and K) not supported.
    E and K picture characters for exponent fields in floating point decimal numbers and F picture characters for scaling factors in fixed point decimal numbers not yet supported.
  • MFPLI10039S C-FORMAT item not supported.
    COMPLEX number processing is not supported.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI10020S WAIT statement not supported.

Multitasking is not supported.
Resolution:
Remove multitasking processing.
Module:
PLSP1.TB
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10021E EVENT attribute not supported.

Multitasking is not supported.
Resolution:
Remove multitasking processing.
Module:
PLSP1.TB
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10022E TASK attribute not supported.

Multitasking is not supported.
Resolution:
Remove multitasking processing.
Module:
PLSP1.TB
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10023E GENERIC attribute not supported.

Selection between entries depending on the attributes of the arguments is not supported.
Resolution:
Replace the GENERIC entry with the the actual entry that would have been invoked dependent on the attributes of the arguments.
Module:
PLSP1.TB
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10025E COMPLEX attribute not supported.

COMPLEX number processing is not supported.
Resolution:
Remove COMPLEX number processing.
Module:
PLSP1.TB
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10032S A NONCONNECTED array reference used as an argument that is passed by-reference to a parameter that has constant extents is not yet supported; argument number argument-number.

A NONCONNECTED array reference used as an argument can only be passed by-reference to a parameter with adjustable extents.
Resolution:
Use asterisks instead of constant extents for the array parameters.
Module:
EXPARG.PL1
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10034S DEFINE ORDINAL not supported.

Module:
PLSP1.TB
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10035S DEFINE STRUCTURE not supported.

Module:
PLSP1.TB
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10036S DIM, LBOUND or HBOUND built-ins with expression arguments not supported.

Module:
INTRP2.PL1
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10038S PICTURE symbols (E, F, and K) not supported.

E and K picture characters for exponent fields in floating point decimal numbers and F picture characters for scaling factors in fixed point decimal numbers not yet supported.
Resolution:
Remove dependencies on unsupported PICTURE symbols.
Module:
DCLPIC.PL1
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10039S C-FORMAT item not supported.

COMPLEX number processing is not supported.
Resolution:
Remove COMPLEX number processing.
Module:
PASS1.PL1
Parent topic: MFPLI10020 - MFPLI10039


MFPLI10040 - MFPLI10059

  • MFPLI10040S L-FORMAT item not supported.
    The format item that indicates the remainder of the input or output line is not supported.
  • MFPLI10041S E-FORMAT item with significant digits specifier not supported.
    The number of significant digits is assumed to be one more than the number of fractional digits.
  • MFPLI10043S The COMPLETION built-in/pseudovariable is not supported.
    Multitasking is not supported.
  • MFPLI10044S The COMPLEX built-in/pseudovariable is not supported.
    COMPLEX number processing is not supported.
  • MFPLI10045S The ENTRYADDR built-in/pseudovariable is not supported.
    The ability to store an entry point in a pointer variable for subsequently assignment to an entry variable is not supported.
  • MFPLI10046S The IMAG built-in/pseudovariable is not supported.
    COMPLEX number processing is not supported.
  • MFPLI10047S The PRIORITY built-in/pseudovariable is not supported.
    Multitasking is not supported.
  • MFPLI10048S The REAL built-in/pseudovariable is not supported.
    COMPLEX number processing is not supported.
  • MFPLI10049S The STATUS built-in/pseudovariable is not supported.
    Multitasking is not supported.
  • MFPLI10050S The DEFAULT statement with an attribute expression is not supported; only the construct "DEFAULT (RANGE(range-spec) & ^PARAMETER)" is allowed.
    DEFAULT statements only apply attributes based on RANGE, optionally excluding PARAMETERs.
  • MFPLI10051S The CONJG built-in is not supported.
    COMPLEX number processing is not supported.
  • MFPLI10054S The MPSTR built-in is not supported.
    Strings containing a mixture of single and double-byte characters are not supported.
  • MFPLI10057E PUT DATA with no argument list is not supported; statement ignored.
    Only data-list items that are specified will be transmitted.
  • MFPLI10058S The ONCOUNT built-in is not supported.
    This built-in function is not supported.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI10040S L-FORMAT item not supported.

The format item that indicates the remainder of the input or output line is not supported.
Resolution:
Use alternative coding.
Module:
PASS1.PL1
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10041S E-FORMAT item with significant digits specifier not supported.

The number of significant digits is assumed to be one more than the number of fractional digits.
Resolution:
Explain different output format to end-users.
Module:
PASS1.PL1
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10043S The COMPLETION built-in/pseudovariable is not supported.

Multitasking is not supported.
Resolution:
Remove multitasking processing.
Module:
INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10044S The COMPLEX built-in/pseudovariable is not supported.

COMPLEX number processing is not supported.
Resolution:
Remove COMPLEX number processing.
Module:
INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10045S The ENTRYADDR built-in/pseudovariable is not supported.

The ability to store an entry point in a pointer variable for subsequently assignment to an entry variable is not supported.
Resolution:
Consider storing the entry point directly in the entry variable.
Module:
INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10046S The IMAG built-in/pseudovariable is not supported.

COMPLEX number processing is not supported.
Resolution:
Remove COMPLEX number processing.
Module:
INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10047S The PRIORITY built-in/pseudovariable is not supported.

Multitasking is not supported.
Resolution:
Remove multitasking processing.
Module:
INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10048S The REAL built-in/pseudovariable is not supported.

COMPLEX number processing is not supported.
Resolution:
Remove COMPLEX number processing.
Module:
INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10049S The STATUS built-in/pseudovariable is not supported.

Multitasking is not supported.
Resolution:
Remove multitasking processing.
Module:
INTRP2.PL1, PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10050S The DEFAULT statement with an attribute expression is not supported; only the construct "DEFAULT (RANGE(range-spec) & ^PARAMETER)" is allowed.

DEFAULT statements only apply attributes based on RANGE, optionally excluding PARAMETERs.
Resolution:
Remove dependency on DEFAULT statements completing attributes based on the attributes specified.
Module:
PASS1.PL1
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10051S The CONJG built-in is not supported.

COMPLEX number processing is not supported.
Resolution:
Remove COMPLEX number processing.
Module:
PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10054S The MPSTR built-in is not supported.

Strings containing a mixture of single and double-byte characters are not supported.
Resolution:
Use the CHARACTER built-in function if the argument contains single-byte characters or the GRAPHIC built-in function if the argument contains double-byte characters.
Module:
PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10057E PUT DATA with no argument list is not supported; statement ignored.

Only data-list items that are specified will be transmitted.
Resolution:
Supply a data-list specifying the particular items required.
Module:
PASS1.PL1
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10058S The ONCOUNT built-in is not supported.

This built-in function is not supported.
Resolution:
Remove dependency on number of conditions that remain to be handled.
Module:
PLSP2.TB
Parent topic: MFPLI10040 - MFPLI10059


MFPLI10060 - MFPLI10079

  • MFPLI10060E The built-in-name built-in is not yet supported.
    The COUNT built-in function is not yet supported.
  • MFPLI10061S Structure arrays containing CHAR varying data items when applied as the argument to the STRING built-in or pseudovariable is not yet supported.
    The STRING built-in function and pseudovariables currently only support CHAR VARYING members of non-array structures.
  • MFPLI10062S The POLY built-in is not supported.
    This built-in function is not supported.
  • MFPLI10065S Structures containing a mix of arrays and CHAR VARYING data items when applied as the argument to the STRING pseudovariable is not yet supported.
    The STRING pseudovariable currently only supports structures that do not have both array and CHAR VARYING members.
  • MFPLI10066W The ONLOC built-in is not supported.
    The ONLOC built-in function is not supported and will return the value '**UNKNOWN**'.
  • MFPLI10067W The ABNORMAL attribute is parsed but ignored.
    The ABNORMAL attribute is not supported and the variable is considered to be NORMAL.
  • MFPLI10068S The -graphic compile-time switch is required for GRAPHIC support.
    If the program contains GRAPHIC strings the -graphic compiler option should be specified.
  • MFPLI10069E The built-in-name built-in subroutine is not yet supported.
    The GRAPHIC built-in function is not yet supported on this platform.
  • MFPLI10070S EBCDIC GRAPHIC is not yet supported on this platform.
    Only ASCII GRAPHIC is currently supported on this platform.
  • MFPLI10071S The built-in-name built-in subroutine is not supported.
    Checkpoint restart is not supported.
  • MFPLI10072S Assignment of a non-array structure to array of structure requiring conversion is not yet supported.
    Assignment of a non-array structure to an array of structures is currently only supported if no conversion is required.
  • MFPLI10073E FIXED DECIMAL fractions with precision < scale are not yet supported.
    FIXED DECIMAL fractions are currently only supported if the scale factor is not greater than the precision.
  • MFPLI10074E Conversion error encountered on NUMERIC (N) literal constant; zero assumed.
    The string between the quotes must represent a valid arithmetic constant optionally preceded by a sign and surrounded by blanks.
  • MFPLI10076S ENTRY variables are not yet supported with STATIC INITIAL on this platform.
    STATIC ENTRY variables may not yet have the INITIAL attribute on this platform.
  • MFPLI10077S Use of the BYVALUE attribute with type FLOAT BINARY and precision > 23 is only supported for arguments passed to non-PL/I routines.
    The declaration of a FLOAT BINARY parameter with precision > 23 may not also have the BYVALUE attribute.
  • MFPLI10079S ENVIRONMENT option TP not supported.
    Teleprocessing datasets are not supported.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI10060E The built-in-name built-in is not yet supported.

The COUNT built-in function is not yet supported.
Resolution:
Remove dependency on the COUNT builtin-in function.
Module:
RESIS.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10061S Structure arrays containing CHAR varying data items when applied as the argument to the STRING built-in or pseudovariable is not yet supported.

The STRING built-in function and pseudovariables currently only support CHAR VARYING members of non-array structures.
Resolution:
Assign the instances of the structure array separately, possibly using an iterative DO-loop.
Module:
RESIS.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10062S The POLY built-in is not supported.

This built-in function is not supported.
Resolution:
If the first argument x has lower bound m and upper bound n and the second argument is y replace with x(m) + x(m+1)*y + x(m+2)*y**2 + ... + x(n)*y**(n-m).
Module:
PLSP2.TB
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10065S Structures containing a mix of arrays and CHAR VARYING data items when applied as the argument to the STRING pseudovariable is not yet supported.

The STRING pseudovariable currently only supports structures that do not have both array and CHAR VARYING members.
Resolution:
Assign the members of the structure separately.
Module:
RESIS.PL1, PLSP2.TB
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10066W The ONLOC built-in is not supported.

The ONLOC built-in function is not supported and will return the value '**UNKNOWN**'.
Resolution:
Remove the use of the built-in function to avoid the message.
Module:
EXPEXP.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10067W The ABNORMAL attribute is parsed but ignored.

The ABNORMAL attribute is not supported and the variable is considered to be NORMAL.
Resolution:
Remove the possibility of the value of the variable changing between statements or within a statement.
Module:
DCLPCS.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10068S The -graphic compile-time switch is required for GRAPHIC support.

If the program contains GRAPHIC strings the -graphic compiler option should be specified.
Resolution:
Specify the -graphic compiler option.
Module:
PL1UTL.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10069E The built-in-name built-in subroutine is not yet supported.

The GRAPHIC built-in function is not yet supported on this platform.
Resolution:
Remove the dependency on the GRAPHIC built-in function.
Module:
PL1UTL.PL1, PL1UTLCW.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10070S EBCDIC GRAPHIC is not yet supported on this platform.

Only ASCII GRAPHIC is currently supported on this platform.
Resolution:
Remove the dependency on EBCDIC GRAPHIC.
Module:
PL1UTL.PL1, PL1UTLCW.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10071S The built-in-name built-in subroutine is not supported.

Checkpoint restart is not supported.
Resolution:
Remove dependency on checkpoint restart.
Module:
DCLPCS.PL1, EXPEXP.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10072S Assignment of a non-array structure to array of structure requiring conversion is not yet supported.

Assignment of a non-array structure to an array of structures is currently only supported if no conversion is required.
Resolution:
Assign the instances of the structure array separately, possibly using an iterative DO-loop.
Module:
VALASS.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10073E FIXED DECIMAL fractions with precision < scale are not yet supported.

FIXED DECIMAL fractions are currently only supported if the scale factor is not greater than the precision.
Resolution:
If possible increase the precision to match the scale factor.
Module:
DCLPL1.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10074E Conversion error encountered on NUMERIC (N) literal constant; zero assumed.

The string between the quotes must represent a valid arithmetic constant optionally preceded by a sign and surrounded by blanks.
Resolution:
Correct the literal constant.
Module:
LEXSTATE.IN
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10076S ENTRY variables are not yet supported with STATIC INITIAL on this platform.

STATIC ENTRY variables may not yet have the INITIAL attribute on this platform.
Resolution:
Remove the INITIAL attribute and use a first-time switch to initialise the variable the first time the block is entered.
Module:
DCLPL1.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10077S Use of the BYVALUE attribute with type FLOAT BINARY and precision > 23 is only supported for arguments passed to non-PL/I routines.

The declaration of a FLOAT BINARY parameter with precision > 23 may not also have the BYVALUE attribute.
Resolution:
Remove the BYVALUE attribute (or change it to BYADDR) and enclose the corresponding arguments in parentheses to ensure the values are passed in dummy arguments.
Module:
DCLPCS.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10079S ENVIRONMENT option TP not supported.

Teleprocessing datasets are not supported.
Resolution:
Remove dependency on teleprocessing datasets.
Module:
PASS1.PL1
Parent topic: MFPLI10060 - MFPLI10079


MFPLI10080 - MFPLI10099

  • MFPLI10081S ENVIRONMENT option CTL360 not supported.
    IBM S/360 machine code control characters are not supported.
  • MFPLI10082S ENVIRONMENT option PASSWORD not supported.
    VSAM datasets defined with READ or UPDATE passwords are not supported.
  • MFPLI10083S ENVIRONMENT option NCP not supported.
    Multitasking is not supported.
  • MFPLI10085S Arrays containing CHAR VARYING data items when applied as the argument to the STRING pseudovariable is not yet supported.
    Only arrays of CHARACTER strings that are non-varying may be assigned using the STRING pseudovariable.
  • MFPLI10086E Structure expressions not supported.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI10081S ENVIRONMENT option CTL360 not supported.

IBM S/360 machine code control characters are not supported.
Resolution:
Convert to ANSI control characters and use the option CTLASA instead.
Module:
PASS1.PL1
Parent topic: MFPLI10080 - MFPLI10099


MFPLI10082S ENVIRONMENT option PASSWORD not supported.

VSAM datasets defined with READ or UPDATE passwords are not supported.
Resolution:
Remove dependency on VSAM datasets with associated passwords.
Module:
PASS1.PL1
Parent topic: MFPLI10080 - MFPLI10099


MFPLI10083S ENVIRONMENT option NCP not supported.

Multitasking is not supported.
Resolution:
Remove multitasking processing.
Module:
PASS1.PL1
Parent topic: MFPLI10080 - MFPLI10099


MFPLI10085S Arrays containing CHAR VARYING data items when applied as the argument to the STRING pseudovariable is not yet supported.

Only arrays of CHARACTER strings that are non-varying may be assigned using the STRING pseudovariable.
Resolution:
Expand the assignment so the individual array elements are assigned separately.
Module:
RESIS.PL1
Parent topic: MFPLI10080 - MFPLI10099


MFPLI10086E Structure expressions not supported.

Module:
PLSP2.TB
Parent topic: MFPLI10080 - MFPLI10099


MFPLI10100 - MFPLI10119

  • MFPLI10105S iSUB defining not supported.
    Defining an array as parts of another array through the use of iSUB variables is not supported.
  • MFPLI10108E CHARGRAPHIC option is not fully supported.
    Strings containing a mixture of single and double-byte characters are not supported.
  • MFPLI10109E ITERATE with multiple comma-separated DO controls is not supported.
    ITERATE is only supported for an iterative DO-group with a single specification.
  • MFPLI10114S The BIGENDIAN & NONNATIVE attributes are not yet supported on POINTER, OFFSET, and AREA data types.
    The BIGENDIAN and NONNATIVE attributes are only supported for FIXED BINARY and VARYING CHARACTER variables.
  • MFPLI10115U CONTROLLED storage class declaration for "variable-name" appearing outside the scope of any EXTERNAL PROCEDURE is not yet supported.
    CONTROLLED variables may not yet be declared in a PACKAGE outside any EXTERNAL PROCEDURE.
  • MFPLI10116S EBCDIC WIDECHAR is not yet supported on this platform.
    Only ASCII WIDECHAR is currently supported on this platform.
  • MFPLI10117S The attribute-name attribute is not yet supported.
    The attribute attribute-name is not yet supported.
  • MFPLI10118S Use of type(x) in a define alias statement is not yet supported.
    The TYPE attribute is not supported in a DEFINE ALIAS statement.
  • MFPLI10119W PLISAXD routine is not yet supported.
    SAX-style parsing with XML validation is not yet supported.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI10105S iSUB defining not supported.

Defining an array as parts of another array through the use of iSUB variables is not supported.
Resolution:
Remove dependency on iSUB defining.
Module:
LEXSTATE.IN
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10108E CHARGRAPHIC option is not fully supported.

Strings containing a mixture of single and double-byte characters are not supported.
Resolution:
Remove dependency on CHARGRAPHIC option.
Module:
PLSP1.TB
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10109E ITERATE with multiple comma-separated DO controls is not supported.

ITERATE is only supported for an iterative DO-group with a single specification.
Resolution:
Replace the ITERATE with a GOTO the END statement of the iterative DO-group;.
Module:
PASS1.PL1, PLSP1.TB
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10114S The BIGENDIAN & NONNATIVE attributes are not yet supported on POINTER, OFFSET, and AREA data types.

The BIGENDIAN and NONNATIVE attributes are only supported for FIXED BINARY and VARYING CHARACTER variables.
Resolution:
Remove dependency on the internal representation of POINTER, OFFSET or AREA variables.
Module:
DCLPCS.PL1, PASS1.PL1
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10115U CONTROLLED storage class declaration for "variable-name" appearing outside the scope of any EXTERNAL PROCEDURE is not yet supported.

CONTROLLED variables may not yet be declared in a PACKAGE outside any EXTERNAL PROCEDURE.
Resolution:
Move the declaration inside the EXTERNAL PROCEDUREs in which it is referenced and, if it is referenced in more than one procedure, add the EXTERNAL attribute.
Module:
DCLPCS.PL1
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10116S EBCDIC WIDECHAR is not yet supported on this platform.

Only ASCII WIDECHAR is currently supported on this platform.
Resolution:
Remove the dependency on EBCDIC WIDECHAR.
Module:
PL1UTL.PL1, PL1UTLCW.PL1
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10117S The attribute-name attribute is not yet supported.

The attribute attribute-name is not yet supported.
Resolution:
Remove the attribute attribute-name.
Module:
PASS1.PL1
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10118S Use of type(x) in a define alias statement is not yet supported.

The TYPE attribute is not supported in a DEFINE ALIAS statement.
Resolution:
Replace the TYPE attribute with the attributes that would be provided by the DEFINE ALIAS statement that defined that type.
Module:
PASS1.PL1
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10119W PLISAXD routine is not yet supported.

SAX-style parsing with XML validation is not yet supported.
Resolution:
Use PLISAXA that provides similar functionality without the validation.
Module:
EXPEXP.PL1
Parent topic: MFPLI10100 - MFPLI10119


MFPLI10120 - MFPLI10139

  • MFPLI10120W The PACKAGE statement with the RESERVES option is not yet supported.
    Neither the RESERVED attribute nor the RESERVES option are yet supported.
  • MFPLI10121W The PACKAGE statement with the OPTIONS option is not yet supported.
    The OPTIONS option is not yet supported on the PACKAGE statement.
  • MFPLI10123W The attribute-name attribute is not yet supported; ignored.
    The attribute attribute-name is not yet supported and is ignored.
  • MFPLI10124W Parameters of type AREA(*) with length > 32K are not yet supported; argument number argument-number is variable-sized and could exceed 32K.
    Only AREA arguments with length <= 32K can be passed to AREA(*) parameters.
  • MFPLI10125S Passing arguments of type AREA with length > 32K to AREA(*) is not yet supported; argument number argument-number is > 32K.
    Only AREA arguments with length <= 32K can be passed to AREA(*) parameters.
Parent topic: MFPLI - PL/I Compiler Messages


MFPLI10120W The PACKAGE statement with the RESERVES option is not yet supported.

Neither the RESERVED attribute nor the RESERVES option are yet supported.
Resolution:
Remove dependency on the RESERVES option.
Module:
PLSP1.TB
Parent topic: MFPLI10120 - MFPLI10139


MFPLI10121W The PACKAGE statement with the OPTIONS option is not yet supported.

The OPTIONS option is not yet supported on the PACKAGE statement.
Resolution:
Specify the required OPTIONS on the PROCEDURE statements in the package.
Module:
PLSP1.TB
Parent topic: MFPLI10120 - MFPLI10139


MFPLI10123W The attribute-name attribute is not yet supported; ignored.

The attribute attribute-name is not yet supported and is ignored.
Resolution:
Remove the attribute attribute-name to avoid the message.
Module:
PASS1.PL1
Parent topic: MFPLI10120 - MFPLI10139


MFPLI10124W Parameters of type AREA(*) with length > 32K are not yet supported; argument number argument-number is variable-sized and could exceed 32K.

Only AREA arguments with length <= 32K can be passed to AREA(*) parameters.
Resolution:
Ensure all AREA arguments passed to this parameter are <= 32K or are of the same length and specify that length for the AREA parameter.
Module:
EXPARG.PL1
Parent topic: MFPLI10120 - MFPLI10139


MFPLI10125S Passing arguments of type AREA with length > 32K to AREA(*) is not yet supported; argument number argument-number is > 32K.

Only AREA arguments with length <= 32K can be passed to AREA(*) parameters.
Resolution:
Ensure all AREA arguments passed to this parameter are of the same length and specify that length for the AREA parameter.
Module:
EXPARG.PL1
Parent topic: MFPLI10120 - MFPLI10139


MFPLX - PL/I Compilation System Messages

  • MFPLX08100 - MFPLX08119
  • MFPLX08120 - MFPLX08139
  • MFPLX08200 - MFPLX08219
  • MFPLX08220 - MFPLX08239
Parent topic: Open PL/I Error Messages


MFPLX08100 - MFPLX08119

  • MFPLX08100I Usage: mfplx [options] {source_file | object_file | library_file}
    mfplx has been executed without any options or an input file.
  • MFPLX08101S The "option-name" option is missing a required argument.
    option-name should be followed by an appropriate argument.
  • MFPLX08102W The "option-name" option is not supported (ignored). Try "mfplx -help".
    option-name is not a supported option.
  • MFPLX08103W "option-name" is a duplicate option with a conflicting argument. Last occurrence taken.
    option-name is specified more than once with different arguments.
  • MFPLX08105W "insert-name" is a conflicting -[no] option. Last occurrence taken.
  • MFPLX08106I "insert-name" is a duplicate option.
  • MFPLX08107W Default listing names used due to multiple sources with -l <filename> or -list <filename>.
  • MFPLX08109U Compilation aborted.
  • MFPLX08110S No input files to process.
    Either no input file has been specified or the input file follows an option that is missing a required argument.
  • MFPLX08111W "insert-name" requires the INCL preprocessor. Use "-incl" or "-pporder".
  • MFPLX08112W "insert-name" requires the DLI preprocessor. Use "-dli" or "-pporder".
  • MFPLX08113W "insert-name" requires the SQL preprocessor. Use "-sql" or "-pporder".
  • MFPLX08114W "insert-name" requires the CICS preprocessor. Use "-cics" or "-pporder".
  • MFPLX08115W "insert-name" requires the MACRO preprocessor. Use "-pp" or "-pporder".
  • MFPLX08116W "insert-name" is applied to the MFPLI compiler only; no source files present.
  • MFPLX08117I "insert-name" must be the only option (ignored).
  • MFPLX08118S Mismatched quote starting at: "text-extract".
    There is no closing quote corresponding to the opening quote at text-extract.
  • MFPLX08119S The "option-name" option requires an integer argument.
    Non-integer argument specified for option-name.
Parent topic: MFPLX - PL/I Compilation System Messages


MFPLX08100I Usage: mfplx [options] {source_file | object_file | library_file}

mfplx has been executed without any options or an input file.
Resolution:
Supply any required options and an input file.
Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08101S The "option-name" option is missing a required argument.

option-name should be followed by an appropriate argument.
Resolution:
Supply the required argument.
Module:
PROCESS.PL1, XINIOE.IN
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08102W The "option-name" option is not supported (ignored). Try "mfplx -help".

option-name is not a supported option.
Resolution:
Check the spelling of option-name.
Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08103W "option-name" is a duplicate option with a conflicting argument. Last occurrence taken.

option-name is specified more than once with different arguments.
Resolution:
Remove the incorrect specification of option-name.
Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08105W "insert-name" is a conflicting -[no] option. Last occurrence taken.

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08106I "insert-name" is a duplicate option.

Module:
PROCESS.PL1 (commented out)
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08107W Default listing names used due to multiple sources with -l <filename> or -list <filename>.

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08109U Compilation aborted.

Module:
PROCESS.PL1 (commented out)
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08110S No input files to process.

Either no input file has been specified or the input file follows an option that is missing a required argument.
Resolution:
Supply either the input file or the missing argument.
Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08111W "insert-name" requires the INCL preprocessor. Use "-incl" or "-pporder".

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08112W "insert-name" requires the DLI preprocessor. Use "-dli" or "-pporder".

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08113W "insert-name" requires the SQL preprocessor. Use "-sql" or "-pporder".

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08114W "insert-name" requires the CICS preprocessor. Use "-cics" or "-pporder".

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08115W "insert-name" requires the MACRO preprocessor. Use "-pp" or "-pporder".

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08116W "insert-name" is applied to the MFPLI compiler only; no source files present.

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08117I "insert-name" must be the only option (ignored).

Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08118S Mismatched quote starting at: "text-extract".

There is no closing quote corresponding to the opening quote at text-extract.
Resolution:
Supply the closing quote.
Module:
PROCESS.PL1, XINIAL.PL1, XINICG.PL1, XINIFE.PL1, XINIOE.PL1, XINIOP.PL1, XINIT.PL1, XINIUT.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08119S The "option-name" option requires an integer argument.

Non-integer argument specified for option-name.
Resolution:
Supply integer argument.
Module:
PROCESS.PL1
Parent topic: MFPLX08100 - MFPLX08119


MFPLX08120 - MFPLX08139

  • MFPLX08120S The "option-name" option requires a positive integer argument.
    Non-integer or non-positive integer specified for option-name.
  • MFPLX08121W "insert-name" requires the INCL preprocessor. Use mfplx.
  • MFPLX08122W "insert-name" requires the DLI preprocessor. Use mfplx.
  • MFPLX08123W "insert-name" requires the SQL preprocessor. Use mfplx.
  • MFPLX08124W "insert-name" requires the CICS preprocessor. Use mfplx.
  • MFPLX08125W "insert-name" requires the MACRO preprocessor. Use mfplx.
  • MFPLX08126I Usage: mfpli [options] source_file
    mfpli has been executed without any options or an input file.
  • MFPLX08127S -pporder preprocessor names must be one of MACRO, SQLDB2, SQLOCI, SQLODBC, CICS, or DLI.
    These are the only valid preprocessor names in the -pporder option and at least one must be specified.
  • MFPLX08128S -pporder preprocessor-name("string") required.
    The preprocessor preprocessor-name requires an argument.
  • MFPLX08129S -pporder MACRO option if present must be one of CASE(ASIS) or CASE(UPPER).
    These are the only valid arguments for the MACRO option in the -pporder option.
  • MFPLX08130S -pporder mismatched parentheses.
    The arguments for each preprocessor in the -pporder option must be in parentheses.
Parent topic: MFPLX - PL/I Compilation System Messages


MFPLX08120S The "option-name" option requires a positive integer argument.

Non-integer or non-positive integer specified for option-name.
Resolution:
Supply positive integer argument.
Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08121W "insert-name" requires the INCL preprocessor. Use mfplx.

Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08122W "insert-name" requires the DLI preprocessor. Use mfplx.

Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08123W "insert-name" requires the SQL preprocessor. Use mfplx.

Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08124W "insert-name" requires the CICS preprocessor. Use mfplx.

Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08125W "insert-name" requires the MACRO preprocessor. Use mfplx.

Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08126I Usage: mfpli [options] source_file

mfpli has been executed without any options or an input file.
Resolution:
Supply any required options and an input file.
Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08127S -pporder preprocessor names must be one of MACRO, SQLDB2, SQLOCI, SQLODBC, CICS, or DLI.

These are the only valid preprocessor names in the -pporder option and at least one must be specified.
Resolution:
Correct the preprocessor name.
Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08128S -pporder preprocessor-name("string") required.

The preprocessor preprocessor-name requires an argument.
Resolution:
Supply the missing argument.
Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08129S -pporder MACRO option if present must be one of CASE(ASIS) or CASE(UPPER).

These are the only valid arguments for the MACRO option in the -pporder option.
Resolution:
Correct or remove the MACRO argument.
Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08130S -pporder mismatched parentheses.

The arguments for each preprocessor in the -pporder option must be in parentheses.
Resolution:
Correct the parentheses.
Module:
PROCESS.PL1
Parent topic: MFPLX08120 - MFPLX08139


MFPLX08200 - MFPLX08219

  • MFPLX08200W *PROCESS "option-name" is an unrecognized option; ignored.
    "%1%s" is specified on a *PROCESS statement but is not recognised as an option.
  • MFPLX08201W *PROCESS "option-name" is not supported; note, behavioral differences might occur.
    "option-name" is a valid option for other PL/I compilers but is not supported by this compiler.
  • MFPLX08205I *PROCESS "option-name" is a duplicate option with a conflicting argument. Last occurrence taken.
    The same option has been specified more than once and with different values.
  • MFPLX08207I *PROCESS "option-name" is a conflicting -[no] option. Last occurrence taken.
  • MFPLX08209E *PROCESS too many "insert-name" symbols; max 7 allowed.
    At most seven alternate symbols may be specified for the or-sign or not-sign.
  • MFPLX08212W *PROCESS "insert-name" unclosed comment assumed at end-of-line.
    Comments on *PROCESS statements cannot span lines.
  • MFPLX08214I *PROCESS option-name occurs more than once and differs. Last occurrence taken.
    The same option has been specified more than once and with different values.
  • MFPLX08215W *PROCESS MARGINS ignores the optional carriage control character position.
    The optional carriage control character position is not supported.
  • MFPLX08216W *PROCESS MARGINS(l,r) must have an integer pair l,r with a valid range between 1,100; 2,72 used.
    The column number of the left source margin must not exceed 100 and the column number of the right source margin must be greater than the left source margin and not exceed 100.
  • MFPLX08217W *PROCESS insert-name ignored; -pporder must be used for equivalent functionality. Refer to the Open-PLI documentation.
  • MFPLX08218W *PROCESS statements are not allowed under -noprocess; all ignored.
    If the -noprocess option is specified *PROCESS statements are not allowed.
  • MFPLX08219W *PROCESS OPT(x) requires 0,1,2,3 or TIME; 0 used;
    Only 0 to 3 or TIME are permitted as arguments to the OPTIMIZE option.
Parent topic: MFPLX - PL/I Compilation System Messages


MFPLX08200W *PROCESS "option-name" is an unrecognized option; ignored.

"%1%s" is specified on a *PROCESS statement but is not recognised as an option.
Resolution:
Correct or remove the unrecognized option.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08201W *PROCESS "option-name" is not supported; note, behavioral differences might occur.

"option-name" is a valid option for other PL/I compilers but is not supported by this compiler.
Resolution:
Remove any dependency on support for "option-name".
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08205I *PROCESS "option-name" is a duplicate option with a conflicting argument. Last occurrence taken.

The same option has been specified more than once and with different values.
Resolution:
If the last occurrence of option-name is the one required remove the earlier occurrences to avoid the message. If an earlier occurrence of option-name is the one required remove the later occurrences.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08207I *PROCESS "option-name" is a conflicting -[no] option. Last occurrence taken.

Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08209E *PROCESS too many "insert-name" symbols; max 7 allowed.

At most seven alternate symbols may be specified for the or-sign or not-sign.
Resolution:
Reduce the number of insert-name symbols to seven.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08212W *PROCESS "insert-name" unclosed comment assumed at end-of-line.

Comments on *PROCESS statements cannot span lines.
Resolution:
Either remove the unclosed comment or close it on the same line.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08214I *PROCESS option-name occurs more than once and differs. Last occurrence taken.

The same option has been specified more than once and with different values.
Resolution:
If the last occurrence of option-name is the one required remove the earlier occurrences to avoid the message. If an earlier occurrence of option-name is the one required remove the later occurrences.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08215W *PROCESS MARGINS ignores the optional carriage control character position.

The optional carriage control character position is not supported.
Resolution:
Remove the carriage control character position.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08216W *PROCESS MARGINS(l,r) must have an integer pair l,r with a valid range between 1,100; 2,72 used.

The column number of the left source margin must not exceed 100 and the column number of the right source margin must be greater than the left source margin and not exceed 100.
Resolution:
Correct the source margins.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08217W *PROCESS insert-name ignored; -pporder must be used for equivalent functionality. Refer to the Open-PLI documentation.

Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08218W *PROCESS statements are not allowed under -noprocess; all ignored.

If the -noprocess option is specified *PROCESS statements are not allowed.
Resolution:
Remove the -noprocess option or the *PROCESS statements.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08219W *PROCESS OPT(x) requires 0,1,2,3 or TIME; 0 used;

Only 0 to 3 or TIME are permitted as arguments to the OPTIMIZE option.
Resolution:
Correct the OPTIMIZE option.
Module:
STARP.PL1
Parent topic: MFPLX08200 - MFPLX08219


MFPLX08220 - MFPLX08239

  • MFPLX08220W *PROCESS MARGINS(n,m) requires numeric arguments; 2,72 used.
    Only numeric arguments are permitted for the MARGINS option.
  • MFPLX08221S *PROCESS XML requires at least one of CASE(UPPER) CASE(ASIS) XMLATTR(APOSTROPHE) XMLATTR(QUOTE).
    At least one of CASE(UPPER) CASE(ASIS) XMLATTR(APOSTROPHE) XMLATTR(QUOTE) are required for the XML option.
  • MFPLX08222W *PROCESS DEFAULT currently supports DUMMY(ALIGNED|UNALIGNED) only; DEFAULT sub-options ignored. Note, behavioral differences might occur.
    Only *PROCESS DEFAULT(DUMMY(ALIGNED|UNALIGNED)) is currently supported.
Parent topic: MFPLX - PL/I Compilation System Messages


MFPLX08220W *PROCESS MARGINS(n,m) requires numeric arguments; 2,72 used.

Only numeric arguments are permitted for the MARGINS option.
Resolution:
Correct the MARGINS option.
Module:
STARP.PL1
Parent topic: MFPLX08220 - MFPLX08239


MFPLX08221S *PROCESS XML requires at least one of CASE(UPPER) CASE(ASIS) XMLATTR(APOSTROPHE) XMLATTR(QUOTE).

At least one of CASE(UPPER) CASE(ASIS) XMLATTR(APOSTROPHE) XMLATTR(QUOTE) are required for the XML option.
Resolution:
Correct the XML option.
Module:
STARP.PL1
Parent topic: MFPLX08220 - MFPLX08239


MFPLX08222W *PROCESS DEFAULT currently supports DUMMY(ALIGNED|UNALIGNED) only; DEFAULT sub-options ignored. Note, behavioral differences might occur.

Only *PROCESS DEFAULT(DUMMY(ALIGNED|UNALIGNED)) is currently supported.
Resolution:
Expect possbile behavorial differences in program execution.
Module:
STARP.PL1
Parent topic: MFPLX08220 - MFPLX08239


MFPPP - PL/I Macro Preprocessor Messages

  • MFPPP09000 - MFPPP09019
  • MFPPP09020 - MFPPP09039
  • MFPPP09040 - MFPPP09059
  • MFPPP09060 - MFPPP09079
  • MFPPP09080 - MFPPP09099
  • MFPPP09100 - MFPPP09119
  • MFPPP09120 - MFPPP09139
  • MFPPP09140 - MFPPP09159
  • MFPPP09160 - MFPPP09179
  • MFPPP09180 - MFPPP09199
  • MFPPP09200 - MFPPP09219
  • MFPPP09220 - MFPPP09239
  • MFPPP09240 - MFPPP09259
Parent topic: Open PL/I Error Messages


MFPPP09000 - MFPPP09019

  • MFPPP09001S Invalid format for %%ACTIVATE statement.
    The format of the statement is a comma-list of preprocessor variables each optionally followed by SCAN, RESCAN or NORESCAN.
  • MFPPP09002S Invalid format for %%DEACTIVATE statement.
    The format of the statement is a comma-list of preprocessor variables.
  • MFPPP09003W Variable variable-name implicitly declared as CHARACTER by ACTIVATE.
  • MFPPP09004W Identifier to DEACTIVATE hasn't been declared.
  • MFPPP09005S keyword-name is an invalid keyword for ANSWER.
    The valid keywords are COLUMN, MARGINS, PAGE and SKIP.
  • MFPPP09006S Error parsing ANSWER Statement
    The format of the statement is ANSWER followed by a character expression in parentheses optionally followed by COLUMN, MARGINS, PAGE or SKIP.
  • MFPPP09007E COLUMN Parameter of ANSWER statement incorrect format
    The COLUMN keyword must be followed by an arithmetic expression for the column number in which the answer text is placed.
  • MFPPP09008W Source has caused too many rescans
  • MFPPP09009E Missing or invalid expression in ANSWER statement
    The ANSWER keyword must be followed by a character expression in parentheses.
  • MFPPP09010I There were error-count errors detected.
  • MFPPP09011I There was 1 error detected.
  • MFPPP09012S Invalid format for an assignment statement.
    The format of the statement is preprocessor-variable = preprocessor-expression optionally preceded by one or more labels each followed by a colon.
  • MFPPP09013S Invalid format for a replace statement.
    The format of the statement is REPLACE identifier BY or WITH string-constant or arithmetic-constant optionally preceded by one or more labels each followed by a colon.
  • MFPPP09014W Variable variable-name has been implicitly declared CHARACTER
  • MFPPP09015W Identifier variable-name is multiply defined, but with different attributes.
  • MFPPP09016W Built-in function not recognized
  • MFPPP09017E Invalid format for DECLARE statement.
  • MFPPP09018E Invalid format for %%DECLARE statement.
  • MFPPP09019E Program logic error - declare identifier not found.
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09001S Invalid format for %%ACTIVATE statement.

The format of the statement is a comma-list of preprocessor variables each optionally followed by SCAN, RESCAN or NORESCAN.
Resolution:
Correct the format.
Module:
PREACT.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09002S Invalid format for %%DEACTIVATE statement.

The format of the statement is a comma-list of preprocessor variables.
Resolution:
Correct the format.
Module:
PREACT.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09003W Variable variable-name implicitly declared as CHARACTER by ACTIVATE.

Module:
PREACT.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09004W Identifier to DEACTIVATE hasn't been declared.

Module:
PREACT.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09005S keyword-name is an invalid keyword for ANSWER.

The valid keywords are COLUMN, MARGINS, PAGE and SKIP.
Resolution:
Check the spelling of the keyword keyword-name.
Module:
PREANSWER.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09006S Error parsing ANSWER Statement

The format of the statement is ANSWER followed by a character expression in parentheses optionally followed by COLUMN, MARGINS, PAGE or SKIP.

The MARGINS and SKIP keywords may, and the COLUMN keyword must, be followed by an expression in parentheses.

Resolution:
Correct the format.
Module:
PREANSWER.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09007E COLUMN Parameter of ANSWER statement incorrect format

The COLUMN keyword must be followed by an arithmetic expression for the column number in which the answer text is placed.
Resolution:
Correct the format.
Module:
PREANSWER.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09008W Source has caused too many rescans

Module:
PRESCAN.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09009E Missing or invalid expression in ANSWER statement

The ANSWER keyword must be followed by a character expression in parentheses.
Resolution:
Correct the format.
Module:
PREANSWER.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09010I There were error-count errors detected.

Module:
PREINPUT.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09011I There was 1 error detected.

Module:
PREINPUT.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09012S Invalid format for an assignment statement.

The format of the statement is preprocessor-variable = preprocessor-expression optionally preceded by one or more labels each followed by a colon.
Resolution:
Correct the format.
Module:
PREASS.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09013S Invalid format for a replace statement.

The format of the statement is REPLACE identifier BY or WITH string-constant or arithmetic-constant optionally preceded by one or more labels each followed by a colon.
Resolution:
Correct the format.
Module:
PREASS.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09014W Variable variable-name has been implicitly declared CHARACTER

Module:
PREASS.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09015W Identifier variable-name is multiply defined, but with different attributes.

Module:
PREDCL.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09016W Built-in function not recognized

Module:
PREDCL.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09017E Invalid format for DECLARE statement.

Module:
PREDCL.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09018E Invalid format for %%DECLARE statement.

Module:
PREDCL.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09019E Program logic error - declare identifier not found.

Module:
PREDCL.C
Parent topic: MFPPP09000 - MFPPP09019


MFPPP09020 - MFPPP09039

  • MFPPP09020S Missing source file name.
  • MFPPP09021S Couldn't open file-name for reading.
  • MFPPP09022S Couldn't open file-name for writing
  • MFPPP09023S Out of memory.
  • MFPPP09024W The file file-name specified by an INSCAN or XINSCAN cannot be found
  • MFPPP09025S Couldn't open file-name for writing
  • MFPPP09026S Couldn't open file-name for writing
  • MFPPP09027S Exceeds max_buffer constant in PREPTYPE.H
  • MFPPP09028E Missing or invalid expression in DO statement
  • MFPPP09029E Missing or invalid expression in %%DO statement
  • MFPPP09030S Invalid format for DO statement.
  • MFPPP09031S Invalid format for %%DO statement.
  • MFPPP09032S No closing END for DO statement
  • MFPPP09033S No closing %%END for %%DO statement
  • MFPPP09034S Invalid format for END statement.
  • MFPPP09035S Invalid format for %%END statement.
  • MFPPP09036S No matching label found for PROCEDURE %%END statement.
  • MFPPP09037S No matching label found for END statement.
  • MFPPP09038S No matching label found for %%END statement.
  • MFPPP09039S END with no matching DO.
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09020S Missing source file name.

Module:
PREINIT.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09021S Couldn't open file-name for reading.

Module:
PREINIT.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09022S Couldn't open file-name for writing

Module:
PREINIT.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09023S Out of memory.

Module:
PREDEBUG.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09024W The file file-name specified by an INSCAN or XINSCAN cannot be found

Module:
PREINC.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09025S Couldn't open file-name for writing

Module:
PREINIT.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09026S Couldn't open file-name for writing

Module:
PREINIT.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09027S Exceeds max_buffer constant in PREPTYPE.H

Module:
PREDEBUG.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09028E Missing or invalid expression in DO statement

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09029E Missing or invalid expression in %%DO statement

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09030S Invalid format for DO statement.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09031S Invalid format for %%DO statement.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09032S No closing END for DO statement

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09033S No closing %%END for %%DO statement

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09034S Invalid format for END statement.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09035S Invalid format for %%END statement.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09036S No matching label found for PROCEDURE %%END statement.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09037S No matching label found for END statement.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09038S No matching label found for %%END statement.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09039S END with no matching DO.

Module:
PREEND.C
Parent topic: MFPPP09020 - MFPPP09039


MFPPP09040 - MFPPP09059

  • MFPPP09040S %%END with no matching %%DO.
  • MFPPP09041E Missing or invalid expression in DO statement.
  • MFPPP09042E Missing or invalid expression in %%DO statement.
  • MFPPP09043E Program logic error - loop variable not found
  • MFPPP09044E Loop variable is no longer an integer
  • MFPPP09045E GOTO into a non-iterative DO block is not allowed.
  • MFPPP09046E %%GOTO into a non-iterative %%DO block is not allowed.
  • MFPPP09048S Invalid format for expression.
  • MFPPP09049S Unmatched parentheses in expression
  • MFPPP09050W Extra operands on GOTO statement will be ignored.
  • MFPPP09051W Extra operands on %%GOTO statement will be ignored.
  • MFPPP09052S Label expected as GOTO operand.
  • MFPPP09053S Label expected as %%GOTO operand.
  • MFPPP09054E %%GOTO label cannot be a PROCEDURE statement.
  • MFPPP09055W %%GOTO label cannot be a DECLARE statement.
  • MFPPP09056E GOTO label not found.
  • MFPPP09057E %%GOTO label not found.
  • MFPPP09058S Invalid format for IF statement.
  • MFPPP09059S Invalid format for %%IF statement.
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09040S %%END with no matching %%DO.

Module:
PREEND.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09041E Missing or invalid expression in DO statement.

Module:
PREEND.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09042E Missing or invalid expression in %%DO statement.

Module:
PREEND.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09043E Program logic error - loop variable not found

Module:
PREEND.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09044E Loop variable is no longer an integer

Module:
PREEND.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09045E GOTO into a non-iterative DO block is not allowed.

Module:
PREEND.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09046E %%GOTO into a non-iterative %%DO block is not allowed.

Module:
PREEND.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09048S Invalid format for expression.

Module:
PREEXPR.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09049S Unmatched parentheses in expression

Module:
PREEXPR.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09050W Extra operands on GOTO statement will be ignored.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09051W Extra operands on %%GOTO statement will be ignored.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09052S Label expected as GOTO operand.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09053S Label expected as %%GOTO operand.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09054E %%GOTO label cannot be a PROCEDURE statement.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09055W %%GOTO label cannot be a DECLARE statement.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09056E GOTO label not found.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09057E %%GOTO label not found.

Module:
PREGOTO.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09058S Invalid format for IF statement.

Module:
PREIF.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09059S Invalid format for %%IF statement.

Module:
PREIF.C
Parent topic: MFPPP09040 - MFPPP09059


MFPPP09060 - MFPPP09079

  • MFPPP09060E Missing or invalid expression in IF statement
  • MFPPP09061E Missing or invalid expression in %%IF statement
  • MFPPP09062W insert-name has not been declared. CHARACTER attribute assumed.
  • MFPPP09063S Invalid format for %%INCLUDE statement
  • MFPPP09064S Invalid format for %%OPTION statement
  • MFPPP09065S Path name of include file too long, truncated
  • MFPPP09066S Path name of include file too long, truncated
  • MFPPP09067S Couldn't open INCLUDE file insert-name
  • MFPPP09068S Invalid format for LEAVE statement.
  • MFPPP09070S Invalid format for %%LINE, statement ignored.
  • MFPPP09071S LEAVE used without active DO block.
  • MFPPP09072S LEAVE label insert-name not present on any active DO block.
  • MFPPP09073I insert-name insert-name
  • MFPPP09075W Invalid format for %%FILE, statement ignored.
  • MFPPP09079S Invalid hex digit in insert-name insert-name
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09060E Missing or invalid expression in IF statement

Module:
PREIF.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09061E Missing or invalid expression in %%IF statement

Module:
PREIF.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09062W insert-name has not been declared. CHARACTER attribute assumed.

Module:
PREIF.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09063S Invalid format for %%INCLUDE statement

Module:
PREINC.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09064S Invalid format for %%OPTION statement

Module:
PREINC.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09065S Path name of include file too long, truncated

Module:
PREINC.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09066S Path name of include file too long, truncated

Module:
PREINC.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09067S Couldn't open INCLUDE file insert-name

Module:
PREINC.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09068S Invalid format for LEAVE statement.

Module:
PREGOTO.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09070S Invalid format for %%LINE, statement ignored.

Module:
PREINC.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09071S LEAVE used without active DO block.

Module:
PREGOTO.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09072S LEAVE label insert-name not present on any active DO block.

Module:
PREGOTO.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09073I insert-name insert-name

Module:
PRENOTE.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09075W Invalid format for %%FILE, statement ignored.

Module:
PREINC.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09079S Invalid hex digit in insert-name insert-name

Module:
PREINIT.C
Parent topic: MFPPP09060 - MFPPP09079


MFPPP09080 - MFPPP09099

  • MFPPP09080E Hex constants for -names must have an even number of digits
  • MFPPP09081E A character value of insert-name cannot be used in insert-name
  • MFPPP09082E No hex digits specified in insert-name insert-name
  • MFPPP09083E Invalid decimal digit in insert-name insert-name
  • MFPPP09084E This option requires a single char, decimal number (0-255) or a hex constant of the form 0xDD in insert-name insert-name
  • MFPPP09085E Value should be in the range (0-255) in insert-name insert-name
  • MFPPP09086W Argument insert-name ignored
  • MFPPP09087E Missing argument for -or_symbol option
  • MFPPP09088E Missing argument for -o option
  • MFPPP09089E Missing argument for -ipath option
  • MFPPP09090E Missing argument for -isuffix option
  • MFPPP09091E Missing argument for -incafter option
  • MFPPP09092E Inconsistent or duplicate option: insert-name
  • MFPPP09093S Inconsistent or duplicate option: insert-name
  • MFPPP09094E Missing or invalid argument for -names option insert-name
  • MFPPP09095E Missing argument for -not_symbol option
  • MFPPP09096W Missing argument for -pp option
  • MFPPP09097W -rc option must be 0,0 or 4,0 or 8,0
  • MFPPP09098W Missing argument for -rc option
  • MFPPP09099W Missing argument for -s option
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09080E Hex constants for -names must have an even number of digits

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09081E A character value of insert-name cannot be used in insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09082E No hex digits specified in insert-name insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09083E Invalid decimal digit in insert-name insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09084E This option requires a single char, decimal number (0-255) or a hex constant of the form 0xDD in insert-name insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09085E Value should be in the range (0-255) in insert-name insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09086W Argument insert-name ignored

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09087E Missing argument for -or_symbol option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09088E Missing argument for -o option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09089E Missing argument for -ipath option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09090E Missing argument for -isuffix option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09091E Missing argument for -incafter option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09092E Inconsistent or duplicate option: insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09093S Inconsistent or duplicate option: insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09094E Missing or invalid argument for -names option insert-name

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09095E Missing argument for -not_symbol option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09096W Missing argument for -pp option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09097W -rc option must be 0,0 or 4,0 or 8,0

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09098W Missing argument for -rc option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09099W Missing argument for -s option

Module:
PREINIT.C
Parent topic: MFPPP09080 - MFPPP09099


MFPPP09100 - MFPPP09119

  • MFPPP09100W Incorrect margins
  • MFPPP09101W Missing argument for -currency_symbol option
  • MFPPP09102W Missing argument for -c option
  • MFPPP09103W Missing argument for -variant variant_name option
  • MFPPP09104W Unrecognized option 'insert-name' ignored
  • MFPPP09105W Missing argument for -isuffix option
  • MFPPP09106W Unrecognized option 'insert-name' ignored
  • MFPPP09107E Program logic error - file not in open list
  • MFPPP09109E Program logic error: ANSWER statement outside of a PROCEDURE.
  • MFPPP09110E Program logic error: RETURN statement outside of a PROCEDURE.
  • MFPPP09111E Program logic error - unexpected statement encountered.
  • MFPPP09112E Program logic error - unrecognized statement encountered.
  • MFPPP09113W Invalid format for %%CONTROL statement.
  • MFPPP09114W Invalid format for %%SKIP, statement ignored.
  • MFPPP09115E Missing name on %%REPLACE, statement ignored.
  • MFPPP09116E Missing name on %%REPLACE, statement ignored.
  • MFPPP09117E Illegal format for %%REPLACE
  • MFPPP09118U Fatal PL/I preprocessor error on line insert-name of file insert-name. Correct all previous PL/I preprocessor errors.
  • MFPPP09119E Failed to locate insert-name.
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09100W Incorrect margins

Module:
PREINIT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09101W Missing argument for -currency_symbol option

Module:
PREINIT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09102W Missing argument for -c option

Module:
PREINIT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09103W Missing argument for -variant variant_name option

Module:
PREINIT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09104W Unrecognized option 'insert-name' ignored

Module:
PREINIT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09105W Missing argument for -isuffix option

Module:
PREINIT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09106W Unrecognized option 'insert-name' ignored

Module:
PREINIT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09107E Program logic error - file not in open list

Module:
PREINPUT.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09109E Program logic error: ANSWER statement outside of a PROCEDURE.

Module:
PREINTRP.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09110E Program logic error: RETURN statement outside of a PROCEDURE.

Module:
PREINTRP.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09111E Program logic error - unexpected statement encountered.

Module:
PREINTRP.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09112E Program logic error - unrecognized statement encountered.

Module:
PREINTRP.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09113W Invalid format for %%CONTROL statement.

Module:
PRELIST.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09114W Invalid format for %%SKIP, statement ignored.

Module:
PRELIST.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09115E Missing name on %%REPLACE, statement ignored.

Module:
PRELIST.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09116E Missing name on %%REPLACE, statement ignored.

Module:
PRELIST.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09117E Illegal format for %%REPLACE

Module:
PRELIST.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09118U Fatal PL/I preprocessor error on line insert-name of file insert-name. Correct all previous PL/I preprocessor errors.

Module:
PREP.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09119E Failed to locate insert-name.

Module:
PREP.C
Parent topic: MFPPP09100 - MFPPP09119


MFPPP09120 - MFPPP09139

  • MFPPP09120E Failed to load insert-name.
  • MFPPP09121E Failed to locate insert-name in insert-name.
  • MFPPP09122E Failed to locate or load CTF shared library.
  • MFPPP09123E Command line identifier insert-name too long.
  • MFPPP09124E Command line definition too long.
  • MFPPP09134E Program logic error - replace identifier insert-name not found
  • MFPPP09135E Program logic error - replace identifier insert-name not found
  • MFPPP09136S Invalid format for NOTE statement.
  • MFPPP09137S Invalid format for %%NOTE statement.
  • MFPPP09138E Return code is not an integer
  • MFPPP09139E No message on %%NOTE statement.
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09120E Failed to load insert-name.

Module:
PREP.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09121E Failed to locate insert-name in insert-name.

Module:
PREP.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09122E Failed to locate or load CTF shared library.

Module:
PREP.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09123E Command line identifier insert-name too long.

Module:
PRELIST.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09124E Command line definition too long.

Module:
PRELIST.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09134E Program logic error - replace identifier insert-name not found

Module:
PRELIST.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09135E Program logic error - replace identifier insert-name not found

Module:
PRELIST.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09136S Invalid format for NOTE statement.

Module:
PRENOTE.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09137S Invalid format for %%NOTE statement.

Module:
PRENOTE.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09138E Return code is not an integer

Module:
PRENOTE.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09139E No message on %%NOTE statement.

Module:
PRENOTE.C
Parent topic: MFPPP09120 - MFPPP09139


MFPPP09140 - MFPPP09159

  • MFPPP09146S Invalid label prefix
  • MFPPP09147W Bad format for %%NOPRINT statement
  • MFPPP09148W Bad format for %%PRINT statement
  • MFPPP09149W Bad format for %%LIST statement
  • MFPPP09150W Bad format for %%NOLIST statement
  • MFPPP09151E Bad format for %%NULL statement
  • MFPPP09152W Bad format for %%ENDFILE statement
  • MFPPP09153S Unrecognized preprocessor statement - insert-name.
  • MFPPP09155S Unrecognized preprocessor statement
  • MFPPP09156S No end of statement before end of file
  • MFPPP09157W %%ACTIVATE statement invalid in a PROCEDURE
  • MFPPP09158W ANSWER statement invalid outside a PROCEDURE
  • MFPPP09159W %%CONTROL statement invalid in a PROCEDURE
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09146S Invalid label prefix

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09147W Bad format for %%NOPRINT statement

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09148W Bad format for %%PRINT statement

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09149W Bad format for %%LIST statement

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09150W Bad format for %%NOLIST statement

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09151E Bad format for %%NULL statement

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09152W Bad format for %%ENDFILE statement

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09153S Unrecognized preprocessor statement - insert-name.

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09155S Unrecognized preprocessor statement

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09156S No end of statement before end of file

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09157W %%ACTIVATE statement invalid in a PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09158W ANSWER statement invalid outside a PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09159W %%CONTROL statement invalid in a PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09140 - MFPPP09159


MFPPP09160 - MFPPP09179

  • MFPPP09160W %%DEACTIVATE statement invalid in a PROCEDURE
  • MFPPP09161S %%DECLARE statement may not BEGIN an IF statement.
  • MFPPP09162S %%END statement may not BEGIN an IF statement.
  • MFPPP09163W %%INCLUDE statement invalid in a PROCEDURE
  • MFPPP09164W %%XINCLUDE statement invalid in a PROCEDURE
  • MFPPP09165S %%PROCEDURE statement may not BEGIN an IF statement.
  • MFPPP09166W %%PROCEDURE statement invalid in a PROCEDURE
  • MFPPP09167W RETURN statement only valid in a PROCEDURE.
  • MFPPP09168S %%THEN or %%ELSE clause must be a preprocessor statement
  • MFPPP09169W Preprocessor statement invalid in PROCEDURE
  • MFPPP09170W Undefined operand in expression
  • MFPPP09171W Fixed overflow truncated to rightmost insert-name digits.
  • MFPPP09174W String invalid for conversion to fixed: 'insert-name'
  • MFPPP09175W String invalid for conversion to BIT string:'insert-name'
  • MFPPP09176W TRANSLATE first argument not CHARACTER.
  • MFPPP09177W TRANSLATE second argument too short .
  • MFPPP09178W ARCHITECTURE invoked with no argument.
  • MFPPP09179E Argument 1 to DIMENSION BUILTIN is not an array: insert-name
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09160W %%DEACTIVATE statement invalid in a PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09161S %%DECLARE statement may not BEGIN an IF statement.

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09162S %%END statement may not BEGIN an IF statement.

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09163W %%INCLUDE statement invalid in a PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09164W %%XINCLUDE statement invalid in a PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09165S %%PROCEDURE statement may not BEGIN an IF statement.

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09166W %%PROCEDURE statement invalid in a PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09167W RETURN statement only valid in a PROCEDURE.

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09168S %%THEN or %%ELSE clause must be a preprocessor statement

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09169W Preprocessor statement invalid in PROCEDURE

Module:
PREPARSE.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09170W Undefined operand in expression

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09171W Fixed overflow truncated to rightmost insert-name digits.

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09174W String invalid for conversion to fixed: 'insert-name'

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09175W String invalid for conversion to BIT string:'insert-name'

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09176W TRANSLATE first argument not CHARACTER.

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09177W TRANSLATE second argument too short .

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09178W ARCHITECTURE invoked with no argument.

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09179E Argument 1 to DIMENSION BUILTIN is not an array: insert-name

Module:
PREPEVAL.C
Parent topic: MFPPP09160 - MFPPP09179


MFPPP09180 - MFPPP09199

  • MFPPP09180W Specified dimension invalid for array insert-name : insert-name
  • MFPPP09181E Argument 1 to LBOUND Built-in function is not an array: insert-name
  • MFPPP09182E Argument 1 to HBOUND Built-in function is not an array: insert-name
  • MFPPP09183W COUNTER exceeding insert-name. reset to 0.
  • MFPPP09184W INDEX invoked with fewer than two arguments.
  • MFPPP09185E REPEAT invoked with no argument.
  • MFPPP09186E REPEAT invoked with negative repetition factor.
  • MFPPP09187W LENGTH invoked with no argument.
  • MFPPP09188W PARMSET invoked with no argument.
  • MFPPP09189W Invalid argument to PARMSET.
  • MFPPP09190W Requested SUBSTR begins before string start
  • MFPPP09192W Requested SUBSTR length is negative
  • MFPPP09193W Requested SUBSTR extends beyond string length
  • MFPPP09194W Undefined operand in expression
  • MFPPP09195W LOWERCASE invoked with no argument.
  • MFPPP09196W UPPERCASE invoked with no argument.
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09180W Specified dimension invalid for array insert-name : insert-name

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09181E Argument 1 to LBOUND Built-in function is not an array: insert-name

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09182E Argument 1 to HBOUND Built-in function is not an array: insert-name

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09183W COUNTER exceeding insert-name. reset to 0.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09184W INDEX invoked with fewer than two arguments.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09185E REPEAT invoked with no argument.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09186E REPEAT invoked with negative repetition factor.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09187W LENGTH invoked with no argument.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09188W PARMSET invoked with no argument.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09189W Invalid argument to PARMSET.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09190W Requested SUBSTR begins before string start

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09192W Requested SUBSTR length is negative

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09193W Requested SUBSTR extends beyond string length

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09194W Undefined operand in expression

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09195W LOWERCASE invoked with no argument.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09196W UPPERCASE invoked with no argument.

Module:
PREPEVAL.C
Parent topic: MFPPP09180 - MFPPP09199


MFPPP09200 - MFPPP09219

  • MFPPP09207E Unmatched parentheses
  • MFPPP09208W ENTRY name previously declared, previous declaration replaced.
  • MFPPP09209W ENTRY name previously declared, previous declaration replaced.
  • MFPPP09210S Invalid format for RETURN statement.
  • MFPPP09211S PROCEDURE must have an ENTRY name.
  • MFPPP09212I Deprecated PL/X KEYS option for %%PROCEDURE statement mapped as if STATEMENT used in its place.
  • MFPPP09213W Duplicate parameter name
  • MFPPP09214S Invalid format for %%PROCEDURE statement.
  • MFPPP09215S No RETURN statement in a PROCEDURE.
  • MFPPP09216S No %%END statement for PROCEDURE.
  • MFPPP09217S Unclosed DO statements in PROCEDURE.
  • MFPPP09219E Unable to interpret function
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09207E Unmatched parentheses

Module:
PREPEVAL.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09208W ENTRY name previously declared, previous declaration replaced.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09209W ENTRY name previously declared, previous declaration replaced.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09210S Invalid format for RETURN statement.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09211S PROCEDURE must have an ENTRY name.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09212I Deprecated PL/X KEYS option for %%PROCEDURE statement mapped as if STATEMENT used in its place.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09213W Duplicate parameter name

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09214S Invalid format for %%PROCEDURE statement.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09215S No RETURN statement in a PROCEDURE.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09216S No %%END statement for PROCEDURE.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09217S Unclosed DO statements in PROCEDURE.

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09219E Unable to interpret function

Module:
PREPROC.C
Parent topic: MFPPP09200 - MFPPP09219


MFPPP09220 - MFPPP09239

  • MFPPP09221W Program logic error - identifier (insert-name) not found in text
  • MFPPP09222W Program logic error - token not found in text
  • MFPPP09223E Program logic error - couldn't find token in scan.
  • MFPPP09224E Unexpected token in function argument.
  • MFPPP09225E Invalid token, expected keyword argument
  • MFPPP09226E Keyword argument not found.
  • MFPPP09227W Keyword argument insert-name ignored, previously specified.
  • MFPPP09230E Function reference function-name() incorrectly formatted
  • MFPPP09239S Invalid format for SELECT statement.
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09221W Program logic error - identifier (insert-name) not found in text

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09222W Program logic error - token not found in text

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09223E Program logic error - couldn't find token in scan.

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09224E Unexpected token in function argument.

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09225E Invalid token, expected keyword argument

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09226E Keyword argument not found.

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09227W Keyword argument insert-name ignored, previously specified.

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09230E Function reference function-name() incorrectly formatted

Module:
PRESCAN.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09239S Invalid format for SELECT statement.

Module:
PRESELECT.C
Parent topic: MFPPP09220 - MFPPP09239


MFPPP09240 - MFPPP09259

  • MFPPP09240S Invalid format for %%SELECT statement.
  • MFPPP09241S Missing open bracket after SELECT
  • MFPPP09242S Premature end of file while processing a SELECT statement
  • MFPPP09243S WHEN clause after OTHERWISE
  • MFPPP09244S Missing open bracket after WHEN
  • MFPPP09245S More than one OTHERWISE clause
  • MFPPP09246S Expected WHEN, SELECT OTHERWISE or END found: insert-name
  • MFPPP09247S Expected WHEN, SELECT OTHERWISE or END
  • MFPPP09248E Badly formed SELECT statement - no body
  • MFPPP09249E Badly formed SELECT statement - wrong statement type
  • MFPPP09250S String literal maximum size of insert-name exceeded
  • MFPPP09251S No close quote before end-of-file
  • MFPPP09252S %%INCLUDE Nesting limit of 2046 exceeded
  • MFPPP09253E Possible mismatch of single or double quotes detected - please check your code.
  • MFPPP09254S Hex literal string of uneven length: insert-name
  • MFPPP09255S Invalid Hex Literal Constant Value: insert-name
  • MFPPP09257S Max identifier size of insert-name exceeded for insert-name
  • MFPPP09258S No statement terminator (semicolon).
  • MFPPP09259S Recursive nesting of %%INCLUDE(s) detected: insert-name
Parent topic: MFPPP - PL/I Macro Preprocessor Messages


MFPPP09240S Invalid format for %%SELECT statement.

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09241S Missing open bracket after SELECT

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09242S Premature end of file while processing a SELECT statement

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09243S WHEN clause after OTHERWISE

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09244S Missing open bracket after WHEN

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09245S More than one OTHERWISE clause

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09246S Expected WHEN, SELECT OTHERWISE or END found: insert-name

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09247S Expected WHEN, SELECT OTHERWISE or END

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09248E Badly formed SELECT statement - no body

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09249E Badly formed SELECT statement - wrong statement type

Module:
PRESELECT.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09250S String literal maximum size of insert-name exceeded

Module:
PRETOKEN.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09251S No close quote before end-of-file

Module:
PRETOKEN.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09252S %%INCLUDE Nesting limit of 2046 exceeded

Module:
PREINC.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09253E Possible mismatch of single or double quotes detected - please check your code.

Module:
PRETOKEN.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09254S Hex literal string of uneven length: insert-name

Module:
PRETOKEN.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09255S Invalid Hex Literal Constant Value: insert-name

Module:
PRETOKEN.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09257S Max identifier size of insert-name exceeded for insert-name

Module:
PRETOKEN.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09258S No statement terminator (semicolon).

Module:
PRETOKEN.C
Parent topic: MFPPP09240 - MFPPP09259


MFPPP09259S Recursive nesting of %%INCLUDE(s) detected: insert-name

Module:
PREINPUT.C
Parent topic: MFPPP09240 - MFPPP09259


MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages

  • MPLIE00000 - MPLIE00019
  • MPLIE00020 - MPLIE00039
  • MPLIE00040 - MPLIE00059
  • MPLIE00080 - MPLIE00099
  • MPLIE00100 - MPLIE00119
  • MPLIE00180 - MPLIE00199
  • MPLIE00400 - MPLIE00419
  • MPLIE09980 - MPLIE09999
Parent topic: Open PL/I Error Messages


MPLIE00000 - MPLIE00019

  • MPLIE00002E EXEC statement is invalid or incomplete.
    The preprocessor encountered unexpected syntax parsing the EXEC statement.
  • MPLIE00003U ERROR condition detected. ONCODE=oncode-value. Contact Micro Focus Support.
    The ERROR condition has been raised.
  • MPLIE00004S Input source file not found. Make sure the file exists in correct directory.
    The input source file is not found in the specified directory.
  • MPLIE00005S Output source file cannot be created. Make sure the directory exists and attributes are correct.
    The output source input file cannot be created in the specified directory.
  • MPLIE00006S Listing file cannot be created. Make sure the directory exists and attributes are correct.
    The listing file cannot be created in the specified directory.
  • MPLIE00007S More than file-count source files. Contact Micro Focus Support.
    The internal array FILETAB can only hold information about file-count source files.
  • MPLIE00008S Module module-name could not be loaded. Contact Micro Focus Support.
    The ERROR condition was raised with ONCODE=9250 fetching module module-name.
  • MPLIE00009S Statement > line-count source lines. Contact Micro Focus Support.
    The statement spans more lines than can be processed.
  • MPLIE00010I A ";" appears within a comment. Ending comment delimiter may be missing.
    A semicolon appearing within a comment may indicate that an ending comment delimiter is missing.
  • MPLIE00011I A ";" appears within a string constant. Ending string delimiter may be missing.
    A semicolon appearing within a string constant may indicate that an ending string delimiter is missing.
  • MPLIE00012E Unbalanced parentheses. Missing ")" supplied.
    There is a left parenthesis that is not balanced by a corresponding right parenthesis.
  • MPLIE00013E Error saving Eclipse repository information file.
    Error opening .dcf file.
  • MPLIE00016S END statement encountered when there are no open groups/blocks.
    There is an END statement that does not correspond to an open DO or SELECT group, PROCEDURE or BEGIN block.
  • MPLIE00017E Invalid Preprocessor option: "option-name".
    Uexpected syntax encountered parsing the preprocessor option "option-name".
  • MPLIE00018S More than procedure-count system generated internal procedures. Contact Micro Focus Support.
    The internal array INT_PROC_NAMES can only hold information about procedure-count generated internal procedures.
  • MPLIE00019W Option "option-name" has a syntax error or has incorrect number of argument(s).
    Unexpected syntax encountered parsing the option "option-name" and/or the number of arguments.
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE00002E EXEC statement is invalid or incomplete.

The preprocessor encountered unexpected syntax parsing the EXEC statement.
Resolution:
Correct the syntax of the EXEC statement.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00003U ERROR condition detected. ONCODE=oncode-value. Contact Micro Focus Support.

The ERROR condition has been raised.

The values returned by the ONCODE built-in function are listed in the Open PL/I User's Guide.

Resolution:
Contact Micro Focus Support.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00004S Input source file not found. Make sure the file exists in correct directory.

The input source file is not found in the specified directory.
Resolution:
Check the directory and name of the input source file.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00005S Output source file cannot be created. Make sure the directory exists and attributes are correct.

The output source input file cannot be created in the specified directory.
Resolution:
Check the existence and attributes of the directory.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00006S Listing file cannot be created. Make sure the directory exists and attributes are correct.

The listing file cannot be created in the specified directory.
Resolution:
Check the existence and attributes of the directory.
Module:
MPLICNV.PLI (hard-coded)
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00007S More than file-count source files. Contact Micro Focus Support.

The internal array FILETAB can only hold information about file-count source files.
Resolution:
Contact Micro Focus Support.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00008S Module module-name could not be loaded. Contact Micro Focus Support.

The ERROR condition was raised with ONCODE=9250 fetching module module-name.
Resolution:
Contact Micro Focus Support.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00009S Statement > line-count source lines. Contact Micro Focus Support.

The statement spans more lines than can be processed.
Resolution:
Contact Micro Focus Support.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00010I A ";" appears within a comment. Ending comment delimiter may be missing.

A semicolon appearing within a comment may indicate that an ending comment delimiter is missing.
Resolution:
Check that the semicolon within the comment was intentional.
Module:
MPLICNV.PLI, MPLIEXEC.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00011I A ";" appears within a string constant. Ending string delimiter may be missing.

A semicolon appearing within a string constant may indicate that an ending string delimiter is missing.
Resolution:
Check that the semicolon within the string constant was intentional.
Module:
MPLICNV.PLI, MPLIEXEC.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00012E Unbalanced parentheses. Missing ")" supplied.

There is a left parenthesis that is not balanced by a corresponding right parenthesis.
Resolution:
Supply the missing right parenthesis.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00013E Error saving Eclipse repository information file.

Error opening .dcf file.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00016S END statement encountered when there are no open groups/blocks.

There is an END statement that does not correspond to an open DO or SELECT group, PROCEDURE or BEGIN block.
Resolution:
Remove the end statement or supply the missing DO, SELECT, PROCEDURE or BEGIN statement.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00017E Invalid Preprocessor option: "option-name".

Uexpected syntax encountered parsing the preprocessor option "option-name".
Resolution:
Check the syntax of the preprocessor option.
Module:
MPLICNV.PLI, MPLIEXEC.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00018S More than procedure-count system generated internal procedures. Contact Micro Focus Support.

The internal array INT_PROC_NAMES can only hold information about procedure-count generated internal procedures.
Resolution:
Contact Micro Focus Support.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00019W Option "option-name" has a syntax error or has incorrect number of argument(s).

Unexpected syntax encountered parsing the option "option-name" and/or the number of arguments.
Resolution:
Correct the syntax of the option and/or the number of arguments.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00000 - MPLIE00019


MPLIE00020 - MPLIE00039

  • MPLIE00020W Option "option-name" has invalid numeric argument(s).
    One or more numeric arguments to option "option-name" is invalid.
  • MPLIE00021W Option "option-name" has argument(s) that are invalid or out of range.
    One or more arguments to option "option-name" is invalid or out of range.
  • MPLIE00022W Option "option-name" must have its argument enclosed in quotes.
    The argument to option "option-name" is not enclosed in quotes.
  • MPLIE00023W Option "option-name" has incorrect length argument.
    The length argument to option "option-name" is incorrect.
  • MPLIE00024W Option "option-name" has invalid argument.
    The argument to option "option-name" is invalid.
  • MPLIE00025W Option PP specifies more than preprocessor-count preprocessor. Excess ignored.
    Only preprocessor-count preprocessors may be specified in the PP option.
  • MPLIE00026W Option PP specifies more than character-count characters for a preprocessor option. Excess ignored.
    A preprocessor option in this context may specify up to character-count characters.
  • MPLIE00027W Warnings have been issued during initialization (FERC=front-end-return-code).
    During initialization warnings have been issued.
  • MPLIE00030W An END statement has been generated to close an open DO, SELECT, BEGIN, or PROCEDURE group/block.
    An END statement has specified the label on a previous DO or SELECT group, BEGIN or PROCEDURE block and one or more END statements have been generated to close the intervening blocks or groups.
  • MPLIE00031E Lower array bound specification for "array-name" will likely produce incorrect results. Use of such arrays with SQL not recommended.
    The lower bound of array "array-name" (which defaults to 1) is specified to be a value other than 1.
  • MPLIE00032E Number of dimensions for "array-name" is > 1. First dimension used.
    Only one-dimensional arrays are supported in this context.
  • MPLIE00033S END statement label "label-name" does not match any open labeled DO, SELECT, BEGIN, or PROCEDURE statement. Outermost procedure closed.
    The label "label-name" on the END statement does not match the label on any unclosed DO or SELECT group, BEGIN or PROCEDURE block.
  • MPLIE00035S Statement has too many tokens. Contact Micro Focus Support.
    The internal structure STMT only allows 250 Kb for tokens.
  • MPLIE00036E Output def file cannot be created. Make sure the directory exists and attributes are correct.
    The output DEF file cannot be created in the specified directory.
  • MPLIE00037S Severe errors have been detected during initialization (FERC=front-end-return-code). Correct the errors and retry.
    During initialization severe errors have been detected.
  • MPLIE00038S < 2 command parameters specified. Input and output filenames are required.
    Fewer than two command parameters have been specified.
  • MPLIE00039I Language element modified.
    Character string constant contains imbedded hex.
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE00020W Option "option-name" has invalid numeric argument(s).

One or more numeric arguments to option "option-name" is invalid.
Resolution:
Correct the numeric argumants.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00021W Option "option-name" has argument(s) that are invalid or out of range.

One or more arguments to option "option-name" is invalid or out of range.
Resolution:
Correct the arguments.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00022W Option "option-name" must have its argument enclosed in quotes.

The argument to option "option-name" is not enclosed in quotes.
Resolution:
Enclose the argument in quotes.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00023W Option "option-name" has incorrect length argument.

The length argument to option "option-name" is incorrect.
Resolution:
Correct the length argument.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00024W Option "option-name" has invalid argument.

The argument to option "option-name" is invalid.
Resolution:
Correct the argument.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00025W Option PP specifies more than preprocessor-count preprocessor. Excess ignored.

Only preprocessor-count preprocessors may be specified in the PP option.
Resolution:
Remove the excess preprocessors.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00026W Option PP specifies more than character-count characters for a preprocessor option. Excess ignored.

A preprocessor option in this context may specify up to character-count characters.
Resolution:
Shorten the preprocessor option to character-count characters or fewer.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00027W Warnings have been issued during initialization (FERC=front-end-return-code).

During initialization warnings have been issued.
Resolution:
Amend the source as required to avoid the warnings.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00030W An END statement has been generated to close an open DO, SELECT, BEGIN, or PROCEDURE group/block.

An END statement has specified the label on a previous DO or SELECT group, BEGIN or PROCEDURE block and one or more END statements have been generated to close the intervening blocks or groups.
Resolution:
Supply matching END statements to avoid the message.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00031E Lower array bound specification for "array-name" will likely produce incorrect results. Use of such arrays with SQL not recommended.

The lower bound of array "array-name" (which defaults to 1) is specified to be a value other than 1.
Resolution:
Arrays with lower bounds of 1 are recommended for use with SQL.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00032E Number of dimensions for "array-name" is > 1. First dimension used.

Only one-dimensional arrays are supported in this context.
Resolution:
Use a one-dimensional array instead.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00033S END statement label "label-name" does not match any open labeled DO, SELECT, BEGIN, or PROCEDURE statement. Outermost procedure closed.

The label "label-name" on the END statement does not match the label on any unclosed DO or SELECT group, BEGIN or PROCEDURE block.
Resolution:
Correct the label on the END statement.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00035S Statement has too many tokens. Contact Micro Focus Support.

The internal structure STMT only allows 250 Kb for tokens.
Resolution:
Contact Micro Focus Support.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00036E Output def file cannot be created. Make sure the directory exists and attributes are correct.

The output DEF file cannot be created in the specified directory.
Resolution:
Check the existence and attributes of the directory.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00037S Severe errors have been detected during initialization (FERC=front-end-return-code). Correct the errors and retry.

During initialization severe errors have been detected.
Resolution:
Correct the errors and retry.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00038S < 2 command parameters specified. Input and output filenames are required.

Fewer than two command parameters have been specified.
Resolution:
Specify both input and output files.
Module:
MPLICNV.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00039I Language element modified.

Character string constant contains imbedded hex.
Module:
MPLICNV.PLI
Parent topic: MPLIE00020 - MPLIE00039


MPLIE00040 - MPLIE00059

  • MPLIE00040I Preprocessor option "option-name" ignored.
    Preprocessor option "option-name" ignored.
  • MPLIE00041S PACKAGE feature is not supported. Your program may contain only one external procedure.
    Packages are not supported by the EXEC preprocessor.
  • MPLIE00042W Errors have been detected during initialization (FERC=front-end-return-code). Processing continues.
    During initialization errors have been detected.
  • MPLIE00043W Inter-component logic error. %%sdebug count has become -ve. Possible statement stepping/debugging issues when debugging.
  • MPLIE00044S SQL does not support PL/I data type "data-type".
    PL/I data type "data-type" is not supported by SQL.
  • MPLIE00045S Physical end of file reached before logical end. An END statement may be missing.
    Physical end of file reached before END statements have been encountered for all PROCEDURE and BEGIN blocks, or DO and SELECT groups.
  • MPLIE00046S Physical end of file reached before logical end. A ")" may be missing.
    Physical end of file reached before matching right parentheses have been encountered for all left parentheses.
  • MPLIE00047S Physical end of file reached before logical end. A "*/" may be missing.
    Physical end of file reached before matching closing comment delimiters have been encountered for all open comments.
  • MPLIE00048S Physical end of file reached before logical end. A single quote may be missing.
    Physical end of file reached before matching closing quotes have been encountered for all single quoted strings.
  • MPLIE00049S Physical end of file reached before logical end. A double quote may be missing.
    Physical end of file reached before matching closing quotes have been encountered for all double quoted strings.
  • MPLIE00056S SQLCA declaration in a nested block (PROCEDURE or BEGIN) is not allowed. It is allowed only in outermost block(s) or in a PACKAGE.
    SQLCA declaration (usually via include of SQLCA) in a nested block (PROCEDURE or BEGIN)is not allowed.
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE00040I Preprocessor option "option-name" ignored.

Preprocessor option "option-name" ignored.
Resolution:
Remove preprocessor option "option-name".
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00041S PACKAGE feature is not supported. Your program may contain only one external procedure.

Packages are not supported by the EXEC preprocessor.
Resolution:
Create separate compilation units for the external procedures in the PACKAGE and declare any variables in the package as EXTERNAL in the procedures that reference them.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00042W Errors have been detected during initialization (FERC=front-end-return-code). Processing continues.

During initialization errors have been detected.
Resolution:
Correct the errors.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00043W Inter-component logic error. %%sdebug count has become -ve. Possible statement stepping/debugging issues when debugging.

Module:
MPLIEXEC.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00044S SQL does not support PL/I data type "data-type".

PL/I data type "data-type" is not supported by SQL.
Resolution:
Use a different data type.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00045S Physical end of file reached before logical end. An END statement may be missing.

Physical end of file reached before END statements have been encountered for all PROCEDURE and BEGIN blocks, or DO and SELECT groups.
Resolution:
Check that all PROCEDURE, BEGIN, DO and SELECT statements have a corresponding END statement.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00046S Physical end of file reached before logical end. A ")" may be missing.

Physical end of file reached before matching right parentheses have been encountered for all left parentheses.
Resolution:
Check that all left parentheses have a matching right parenthesis.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00047S Physical end of file reached before logical end. A "*/" may be missing.

Physical end of file reached before matching closing comment delimiters have been encountered for all open comments.
Resolution:
Check that all comments have closing comment delimiters.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00048S Physical end of file reached before logical end. A single quote may be missing.

Physical end of file reached before matching closing quotes have been encountered for all single quoted strings.
Resolution:
Check that all single quoted strings have closing quotes.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00049S Physical end of file reached before logical end. A double quote may be missing.

Physical end of file reached before matching closing quotes have been encountered for all double quoted strings.
Resolution:
Check that all double quoted strings have closing quotes.
Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00056S SQLCA declaration in a nested block (PROCEDURE or BEGIN) is not allowed. It is allowed only in outermost block(s) or in a PACKAGE.

SQLCA declaration (usually via include of SQLCA) in a nested block (PROCEDURE or BEGIN)is not allowed.

It is allowed only in outermost block(s) or in a PACKAGE.

Resolution:
Simply remove the declaration from the nested block. If you wish, you may add it to the outermost PROCEDURE or to the PACKAGE.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00040 - MPLIE00059


MPLIE00080 - MPLIE00099

  • MPLIE00099S Internal system error "error-name". Contact Micro Focus Support.
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE00099S Internal system error "error-name". Contact Micro Focus Support.

Resolution:
Contact Micro Focus Support.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00080 - MPLIE00099


MPLIE00100 - MPLIE00119

  • MPLIE00100I EXEC subsystem-name Preprocessor issued information-count I, warning-count W, error-count E, severe-count S, unrecoverable-count U messages.
  • MPLIE00101I EXEC Preprocessor processed statement-count EXEC subsystem-name statements, ending with return code return-code.
  • MPLIE00102I EXEC subsystem-name Preprocessor suppressed pp-message-count messages. User exit suppressed user-exit-message-count messages.
    Counts of the numbers of messages suppressed by the EXEC subsystem-name preprocessor and the user exit.
  • MPLIE00103S Message limit of message-limit exceeded. Processing terminated.
  • MPLIE00104I PL/I Conversion Tool issued information-count I, warning-count W, error-count E, severe-count S, unrecoverable-count U messages.
  • MPLIE00105I PL/I Conversion Tool modified element-count language elements, ending with return code return-code.
  • MPLIE00106S Include nesting exceeds nesting-limit. Contact Micro Focus Support.
  • MPLIE00107S Include file "file-name" not found. Make sure the file exists in correct directory/path.
  • MPLIE00108I Include Preprocessor suppressed pp-message-count messages. User exit suppressed user-exit-message-count messages.
    Counts of the numbers of messages suppressed by the INCLUDE preprocessor and the user exit.
  • MPLIE00109S %%INCLUDE/%%XINCLUDE statement has invalid syntax or is incomplete.
  • MPLIE00110I PL/I Conversion Tool suppressed tool-message-count messages. User exit suppressed user-exit-message-count messages.
    Counts of the numbers of messages suppressed by the PL/I Conversion Tool and the user exit.
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE00100I EXEC subsystem-name Preprocessor issued information-count I, warning-count W, error-count E, severe-count S, unrecoverable-count U messages.

Module:
MPLIEXEC.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00101I EXEC Preprocessor processed statement-count EXEC subsystem-name statements, ending with return code return-code.

Module:
MPLIEXEC.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00102I EXEC subsystem-name Preprocessor suppressed pp-message-count messages. User exit suppressed user-exit-message-count messages.

Counts of the numbers of messages suppressed by the EXEC subsystem-name preprocessor and the user exit.
Module:
MPLIEXEC.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00103S Message limit of message-limit exceeded. Processing terminated.

Module:
MFINCLPPZ.PLI, MPLICNV.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00104I PL/I Conversion Tool issued information-count I, warning-count W, error-count E, severe-count S, unrecoverable-count U messages.

Module:
MPLICNV.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00105I PL/I Conversion Tool modified element-count language elements, ending with return code return-code.

Module:
MPLICNV.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00106S Include nesting exceeds nesting-limit. Contact Micro Focus Support.

Resolution:
Contact Micro Focus Support.
Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00107S Include file "file-name" not found. Make sure the file exists in correct directory/path.

Module:
MFINCLPPZ.PLI, MPLIEXEC.PLI, MPLIINCL.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00108I Include Preprocessor suppressed pp-message-count messages. User exit suppressed user-exit-message-count messages.

Counts of the numbers of messages suppressed by the INCLUDE preprocessor and the user exit.
Module:
MFINCLPPZ.PLI, MPLIINCL.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00109S %%INCLUDE/%%XINCLUDE statement has invalid syntax or is incomplete.

Module:
MFINCLPPZ.PLI, MPLIINCL.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00110I PL/I Conversion Tool suppressed tool-message-count messages. User exit suppressed user-exit-message-count messages.

Counts of the numbers of messages suppressed by the PL/I Conversion Tool and the user exit.
Module:
MPLICNV.PLI
Parent topic: MPLIE00100 - MPLIE00119


MPLIE00180 - MPLIE00199

  • MPLIE00199I message-text.
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE00199I message-text.

Parent topic: MPLIE00180 - MPLIE00199


MPLIE00400 - MPLIE00419

  • MPLIE00400E User program program-name abended. ONCODE=oncode-value PLIRETC=pliretc-value.
  • MPLIE00401E User program abended in non-PL/I code. ONCODE=oncode-value PLIRETC=pliretc-value.
  • MPLIE00402I User program abend caused exit invocation.
  • MPLIE00403I User program terminated with PLIRETC=pliretc-value.
  • MPLIE00404U Internal Error. Contact Micro Focus Support. MF1CICS=mf1cics-value.
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE00400E User program program-name abended. ONCODE=oncode-value PLIRETC=pliretc-value.

Module:
MPLICPPN.PLI (hard-coded)
Parent topic: MPLIE00400 - MPLIE00419


MPLIE00401E User program abended in non-PL/I code. ONCODE=oncode-value PLIRETC=pliretc-value.

Module:
MPLICPPN.PLI (hard-coded)
Parent topic: MPLIE00400 - MPLIE00419


MPLIE00402I User program abend caused exit invocation.

Module:
MPLIPPM.CBL (hard-coded)
Parent topic: MPLIE00400 - MPLIE00419


MPLIE00403I User program terminated with PLIRETC=pliretc-value.

Module:
MPLIPPM.CBL (hard-coded)
Parent topic: MPLIE00400 - MPLIE00419


MPLIE00404U Internal Error. Contact Micro Focus Support. MF1CICS=mf1cics-value.

Resolution:
Contact Micro Focus Support.
Module:
MPLICPPN.PLI (hard-coded)
Parent topic: MPLIE00400 - MPLIE00419


MPLIE09980 - MPLIE09999

  • MPLIE09991I information-message
  • MPLIE09992W warning-message
  • MPLIE09993E error-message
  • MPLIE09994S severe-message
  • MPLIE09995S severe-message
  • MPLIE09996U unrecoverable-message
Parent topic: MPLIE - PL/I CICS, SQL, DLI, and INCLUDE Preprocessor and PL/I Source Conversion Tool Messages


MPLIE09991I information-message

Module:
MPLIEXEC.PLI
Parent topic: MPLIE09980 - MPLIE09999


MPLIE09992W warning-message

Module:
MPLIEXEC.PLI
Parent topic: MPLIE09980 - MPLIE09999


MPLIE09993E error-message

Module:
MPLIEXEC.PLI
Parent topic: MPLIE09980 - MPLIE09999


MPLIE09994S severe-message

Module:
MPLIEXEC.PLI
Parent topic: MPLIE09980 - MPLIE09999


MPLIE09995S severe-message

Module:
MPLIEXEC.PLI
Parent topic: MPLIE09980 - MPLIE09999


MPLIE09996U unrecoverable-message

Module:
MPLIEXEC.PLI
Parent topic: MPLIE09980 - MPLIE09999


MPLIR - PL/I Runtime Messages

  • MPLIR05000 - MPLIR05019
  • MPLIR05100 - MPLIR05119
  • MPLIR05200 - MPLIR05219
  • MPLIR05300 - MPLIR05319
  • MPLIR05400 - MPLIR05419
  • MPLIR05420 - MPLIR05439
  • MPLIR05440 - MPLIR05459
  • MPLIR05460 - MPLIR05479
  • MPLIR05480 - MPLIR05499
  • MPLIR05500 - MPLIR05519
  • MPLIR05520 - MPLIR05539
  • MPLIR05540 - MPLIR05559
  • MPLIR05560 - MPLIR05579
  • MPLIR05580 - MPLIR05599
Parent topic: Open PL/I Error Messages


MPLIR05000 - MPLIR05019

  • MPLIR05000W PLIRETC argument greater than 999. Return code set to 999.
  • MPLIR05001W byte-count bytes of memory starting at address memory-location in use at program exit.
  • MPLIR05002W Unsupported run time option option-name.
  • MPLIR05003W The NAME condition was raised because an invalid element-variable in a STREAM item was encountered during a GET FILE DATA statement (FILE= file-name).
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05000W PLIRETC argument greater than 999. Return code set to 999.

Module:
RTERR.C
Parent topic: MPLIR05000 - MPLIR05019


MPLIR05001W byte-count bytes of memory starting at address memory-location in use at program exit.

Module:
RTERR.C
Parent topic: MPLIR05000 - MPLIR05019


MPLIR05002W Unsupported run time option option-name.

Module:
RTERR.C
Parent topic: MPLIR05000 - MPLIR05019


MPLIR05003W The NAME condition was raised because an invalid element-variable in a STREAM item was encountered during a GET FILE DATA statement (FILE= file-name).

Module:
NAME.PL1
Parent topic: MPLIR05000 - MPLIR05019


MPLIR05100 - MPLIR05119

  • MPLIR05100E Could not ignore SIGINT in default ON ATTENTION.
  • MPLIR05101E Could not unlink FIFO queue.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05100E Could not ignore SIGINT in default ON ATTENTION.

Module:
RTERR.C
Parent topic: MPLIR05100 - MPLIR05119


MPLIR05101E Could not unlink FIFO queue.

Module:
RTERR.C
Parent topic: MPLIR05100 - MPLIR05119


MPLIR05200 - MPLIR05219

  • MPLIR05200S Corrupted stack on nonlocal GOTO.
  • MPLIR05201S Internal error -- return from SIGNAL.
  • MPLIR05202S Attempt to return from ON ERROR.
  • MPLIR05203S Attempt to return from ON OVERFLOW.
  • MPLIR05204S Attempt to return from ON UNDERFLOW.
  • MPLIR05205S Attempt to return from ON ZERODIVIDE.
  • MPLIR05206S Cannot unlink FIFO queue.
  • MPLIR05207S Cannot receive message.
  • MPLIR05208S Cannot send message.
  • MPLIR05209S Could not attach debugger.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05200S Corrupted stack on nonlocal GOTO.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05201S Internal error -- return from SIGNAL.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05202S Attempt to return from ON ERROR.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05203S Attempt to return from ON OVERFLOW.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05204S Attempt to return from ON UNDERFLOW.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05205S Attempt to return from ON ZERODIVIDE.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05206S Cannot unlink FIFO queue.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05207S Cannot receive message.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05208S Cannot send message.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05209S Could not attach debugger.

Module:
RTERR.C
Parent topic: MPLIR05200 - MPLIR05219


MPLIR05300 - MPLIR05319

  • MPLIR05308E Condition condition-name raised.
    SNAP was specified on the ON-unit for the condition condition-name requesting diagnostic information to be printed when the condition is raised.
  • MPLIR05309E ONCODE 99140: The UNDEFINEDFILE condition was raised because a DD statement was not used in (FILE=dd-name).
    At OPEN time it has not been possible to associate the logical FILE with a physical file.
  • MPLIR05310S Unable to allocate memory. byte-count bytes were requested.
  • MPLIR05311E Condition ERROR raised. insert-name.
  • MPLIR05312E Condition ERROR raised.
    Either a SIGNAL ERROR statement has been executed, or a condition has been raised for which there is no ON-unit established and the implicit action is to raise the ERROR condition (for example, CONVERSION, ENDFILE, etc.), or a condition has been raised for which an ON-unit has been established and the normal return is to raise the ERROR condition (for example, SUBSCRIPTRANGE), or as a result of an error during program execution for which no other condition is defined (for example, protection violation).
  • MPLIR05313E Error(insert-name)
  • MPLIR05314E insert-name
  • MPLIR05315I insert-name on
  • MPLIR05316I FILE "file-name"
  • MPLIR05317E FETCHABLE "entry-name" not found. ONCODE=9250.
  • MPLIR05318I at PC
  • MPLIR05319I for
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05308E Condition condition-name raised.

SNAP was specified on the ON-unit for the condition condition-name requesting diagnostic information to be printed when the condition is raised.
Resolution:
For information only.
Module:
SNAP.C, SSNAP.C
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05309E ONCODE 99140: The UNDEFINEDFILE condition was raised because a DD statement was not used in (FILE=dd-name).

At OPEN time it has not been possible to associate the logical FILE with a physical file.
Resolution:
Check that, unless the file is SYSIN or SYSPRINT, the program has been compiled with the -defext option, and that, if using JCL, there is a DD statement and, unless it is an OUTPUT file, the physical file already exists.
Module:
MF1IO.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05310S Unable to allocate memory. byte-count bytes were requested.

Module:
ALCFRE.C
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05311E Condition ERROR raised. insert-name.

Module:
SIGFLT.C
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05312E Condition ERROR raised.

Either a SIGNAL ERROR statement has been executed, or a condition has been raised for which there is no ON-unit established and the implicit action is to raise the ERROR condition (for example, CONVERSION, ENDFILE, etc.), or a condition has been raised for which an ON-unit has been established and the normal return is to raise the ERROR condition (for example, SUBSCRIPTRANGE), or as a result of an error during program execution for which no other condition is defined (for example, protection violation).
Resolution:
For further information generate a CTF trace or look at the PLIDUMP listing.
Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05313E Error(insert-name)

Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05314E insert-name

Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05315I insert-name on

Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05316I FILE "file-name"

Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05317E FETCHABLE "entry-name" not found. ONCODE=9250.

Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05318I at PC

Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05319I for

Module:
ONANY.PL1
Parent topic: MPLIR05300 - MPLIR05319


MPLIR05400 - MPLIR05419

  • MPLIR05401I Not owner.
  • MPLIR05402I No such file or directory.
  • MPLIR05403I No such process.
  • MPLIR05404I Interrupted system call.
  • MPLIR05405I I/O error.
  • MPLIR05406I No such device or address.
  • MPLIR05407I Arg list too long.
  • MPLIR05408I Exec format error.
  • MPLIR05409I Bad file number.
  • MPLIR05410I No children.
  • MPLIR05411I No more processes.
  • MPLIR05412I Not enough core.
  • MPLIR05413I Permission denied.
  • MPLIR05414I Bad address.
  • MPLIR05415I Block device required.
  • MPLIR05416I Mount device busy.
  • MPLIR05417I File exists.
  • MPLIR05418I Cross-device link.
  • MPLIR05419I No such device.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05401I Not owner.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05402I No such file or directory.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05403I No such process.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05404I Interrupted system call.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05405I I/O error.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05406I No such device or address.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05407I Arg list too long.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05408I Exec format error.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05409I Bad file number.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05410I No children.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05411I No more processes.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05412I Not enough core.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05413I Permission denied.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05414I Bad address.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05415I Block device required.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05416I Mount device busy.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05417I File exists.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05418I Cross-device link.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05419I No such device.

Parent topic: MPLIR05400 - MPLIR05419


MPLIR05420 - MPLIR05439

  • MPLIR05420I Not a directory.
  • MPLIR05421I Is a directory.
  • MPLIR05422I Invalid argument.
  • MPLIR05423I File table overflow.
  • MPLIR05424I Too many open files.
  • MPLIR05425I Not a typewriter.
  • MPLIR05426I Text file busy.
  • MPLIR05427I File too large.
  • MPLIR05428I No space left on device.
  • MPLIR05429I Illegal seek.
  • MPLIR05430I Read-only file system.
  • MPLIR05431I Too many links.
  • MPLIR05432I Broken pipe.
  • MPLIR05433I Argument too large.
  • MPLIR05434I Result too large.
  • MPLIR05435I Operation would block.
  • MPLIR05436I Operation now in progress.
  • MPLIR05437I Operation already in progress.
  • MPLIR05438I Socket operation on non-socket.
  • MPLIR05439I Destination address required.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05420I Not a directory.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05421I Is a directory.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05422I Invalid argument.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05423I File table overflow.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05424I Too many open files.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05425I Not a typewriter.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05426I Text file busy.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05427I File too large.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05428I No space left on device.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05429I Illegal seek.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05430I Read-only file system.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05431I Too many links.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05432I Broken pipe.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05433I Argument too large.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05434I Result too large.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05435I Operation would block.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05436I Operation now in progress.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05437I Operation already in progress.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05438I Socket operation on non-socket.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05439I Destination address required.

Parent topic: MPLIR05420 - MPLIR05439


MPLIR05440 - MPLIR05459

  • MPLIR05440I Message too long.
  • MPLIR05441I Protocol wrong type for socket.
  • MPLIR05442I Protocol not available.
  • MPLIR05443I Protocol not supported.
  • MPLIR05444I Socket type not supported.
  • MPLIR05445I Operation not supported on socket.
  • MPLIR05446I Protocol family not supported.
  • MPLIR05447I Address family not supported by protocol family.
  • MPLIR05448I Address already in use.
  • MPLIR05449I Can not assign requested address.
  • MPLIR05450I Network is down.
  • MPLIR05451I Network is unreachable.
  • MPLIR05452I Network dropped connection on reset.
  • MPLIR05453I Software caused connection abort.
  • MPLIR05454I Connection reset by peer.
  • MPLIR05455I No buffer space available.
  • MPLIR05456I Socket is already connected.
  • MPLIR05457I Socket is not connected.
  • MPLIR05458I Can not send after socket shutDOwn.
  • MPLIR05459I Too many references: can not splice.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05440I Message too long.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05441I Protocol wrong type for socket.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05442I Protocol not available.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05443I Protocol not supported.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05444I Socket type not supported.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05445I Operation not supported on socket.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05446I Protocol family not supported.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05447I Address family not supported by protocol family.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05448I Address already in use.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05449I Can not assign requested address.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05450I Network is down.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05451I Network is unreachable.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05452I Network dropped connection on reset.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05453I Software caused connection abort.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05454I Connection reset by peer.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05455I No buffer space available.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05456I Socket is already connected.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05457I Socket is not connected.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05458I Can not send after socket shutDOwn.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05459I Too many references: can not splice.

Parent topic: MPLIR05440 - MPLIR05459


MPLIR05460 - MPLIR05479

  • MPLIR05460I Connection timed out.
  • MPLIR05461I Connection refused.
  • MPLIR05462I Too many levels of symbolic links.
  • MPLIR05463I File name too long.
  • MPLIR05464I Host is down.
  • MPLIR05465I No route to host.
  • MPLIR05466I Directory not empty.
  • MPLIR05467I Too many processes.
  • MPLIR05468I Too many users.
  • MPLIR05469I Disc quota exceeded.
  • MPLIR05470I Stale NFS file handle.
  • MPLIR05471I Too many levels of remote in path.
  • MPLIR05472I Device is not a stream.
  • MPLIR05473I Timer expired.
  • MPLIR05474I Out of streams resources.
  • MPLIR05475I No message of desired type.
  • MPLIR05476I Trying to read unreadable message.
  • MPLIR05477I Identifier removed.
  • MPLIR05478I Deadlock condition..
  • MPLIR05479I No record locks available..
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05460I Connection timed out.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05461I Connection refused.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05462I Too many levels of symbolic links.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05463I File name too long.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05464I Host is down.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05465I No route to host.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05466I Directory not empty.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05467I Too many processes.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05468I Too many users.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05469I Disc quota exceeded.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05470I Stale NFS file handle.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05471I Too many levels of remote in path.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05472I Device is not a stream.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05473I Timer expired.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05474I Out of streams resources.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05475I No message of desired type.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05476I Trying to read unreadable message.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05477I Identifier removed.

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05478I Deadlock condition..

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05479I No record locks available..

Parent topic: MPLIR05460 - MPLIR05479


MPLIR05480 - MPLIR05499

  • MPLIR05480I Machine is not on the network.
  • MPLIR05481I Object is remote.
  • MPLIR05482I the link has been severed.
  • MPLIR05483I advertise error.
  • MPLIR05484I srmount error.
  • MPLIR05485I Communication error on send.
  • MPLIR05486I Protocol error.
  • MPLIR05487I multihop attempted.
  • MPLIR05488I Cross mount point (not an error).
  • MPLIR05489I Remote address changed.
  • MPLIR05490I function not implemented.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05480I Machine is not on the network.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05481I Object is remote.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05482I the link has been severed.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05483I advertise error.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05484I srmount error.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05485I Communication error on send.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05486I Protocol error.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05487I multihop attempted.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05488I Cross mount point (not an error).

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05489I Remote address changed.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05490I function not implemented.

Parent topic: MPLIR05480 - MPLIR05499


MPLIR05500 - MPLIR05519

  • MPLIR05500I Duplicate record.
  • MPLIR05501I File not open.
  • MPLIR05502I Illegal argument.
  • MPLIR05503I Illegal key description.
  • MPLIR05504I Too many files open.
  • MPLIR05505I Bad isam file format.
  • MPLIR05506I Non-exclusive access.
  • MPLIR05507I Record locked.
  • MPLIR05508I Key already exists.
  • MPLIR05509I Is primary key.
  • MPLIR05510I End/Begin of file.
  • MPLIR05511I No record found.
  • MPLIR05512I No current record.
  • MPLIR05513I File locked.
  • MPLIR05514I File name too long.
  • MPLIR05515I Can not create lock file.
  • MPLIR05516I Duplicate record (warning).
  • MPLIR05517I Current record pointer undefined.
  • MPLIR05518I Can not allocate memory.
  • MPLIR05519I Bad custom collating.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05500I Duplicate record.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05501I File not open.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05502I Illegal argument.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05503I Illegal key description.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05504I Too many files open.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05505I Bad isam file format.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05506I Non-exclusive access.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05507I Record locked.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05508I Key already exists.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05509I Is primary key.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05510I End/Begin of file.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05511I No record found.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05512I No current record.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05513I File locked.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05514I File name too long.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05515I Can not create lock file.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05516I Duplicate record (warning).

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05517I Current record pointer undefined.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05518I Can not allocate memory.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05519I Bad custom collating.

Parent topic: MPLIR05500 - MPLIR05519


MPLIR05520 - MPLIR05539

  • MPLIR05520I Invalid operation.
  • MPLIR05521I Boundary violation on write.
  • MPLIR05522I Boundary violation on sq file.
  • MPLIR05523I Not available, closed w/ lock.
  • MPLIR05524I Inconsistent attributes.
  • MPLIR05525I Open -APPEND on KEYED file.
  • MPLIR05526I Open -DAM on non-DIRECT file.
  • MPLIR05527I Open -SAM on KEYED file.
  • MPLIR05528I File not open or open for output only.
  • MPLIR05529I File not open, open for input only or illegal WRITE attempted.
  • MPLIR05530I Open on file not yet closed.
  • MPLIR05531I KEY specified on sequential file.
  • MPLIR05532I KEY specified on stream file.
  • MPLIR05533I No KEY specified on KEYED file.
  • MPLIR05534I Not a PRINT file.
  • MPLIR05535I Not a STREAM file.
  • MPLIR05536I CALL dataname name not found.
  • MPLIR05537I B-format error (35).
  • MPLIR05538I BI format error (36).
  • MPLIR05539I C format error (32).
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05520I Invalid operation.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05521I Boundary violation on write.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05522I Boundary violation on sq file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05523I Not available, closed w/ lock.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05524I Inconsistent attributes.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05525I Open -APPEND on KEYED file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05526I Open -DAM on non-DIRECT file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05527I Open -SAM on KEYED file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05528I File not open or open for output only.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05529I File not open, open for input only or illegal WRITE attempted.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05530I Open on file not yet closed.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05531I KEY specified on sequential file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05532I KEY specified on stream file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05533I No KEY specified on KEYED file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05534I Not a PRINT file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05535I Not a STREAM file.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05536I CALL dataname name not found.

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05537I B-format error (35).

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05538I BI format error (36).

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05539I C format error (32).

Parent topic: MPLIR05520 - MPLIR05539


MPLIR05540 - MPLIR05559

  • MPLIR05540I E format error (34).
  • MPLIR05541I I/O stack overflow.
  • MPLIR05542I Conversion error.
  • MPLIR05543I LIST input to long.
  • MPLIR05544I Implicit open failed.
  • MPLIR05545I EOF found while parsing edited input.
  • MPLIR05546I End of string on GET/PUT STRING.
  • MPLIR05547I Invalid format for GET/PUT STRING.
  • MPLIR05548I Invalid input for GET.
  • MPLIR05549I Cannot intialize RPG screens.
  • MPLIR05550I Not open for read.
  • MPLIR05551I REWRITE on input file.
  • MPLIR05552I File not open on non-optional.
  • MPLIR05553I File open on optional.
  • MPLIR05554I Sequential error on REWRITE or DELETE, COBOL85.
  • MPLIR05555I Sequential error no next record COBOL85.
  • MPLIR05556I Bad record size on current record.
  • MPLIR05557I Cannot read log record.
  • MPLIR05558I Bad log record.
  • MPLIR05559I Cannot open log file.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05540I E format error (34).

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05541I I/O stack overflow.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05542I Conversion error.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05543I LIST input to long.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05544I Implicit open failed.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05545I EOF found while parsing edited input.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05546I End of string on GET/PUT STRING.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05547I Invalid format for GET/PUT STRING.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05548I Invalid input for GET.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05549I Cannot intialize RPG screens.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05550I Not open for read.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05551I REWRITE on input file.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05552I File not open on non-optional.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05553I File open on optional.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05554I Sequential error on REWRITE or DELETE, COBOL85.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05555I Sequential error no next record COBOL85.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05556I Bad record size on current record.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05557I Cannot read log record.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05558I Bad log record.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05559I Cannot open log file.

Parent topic: MPLIR05540 - MPLIR05559


MPLIR05560 - MPLIR05579

  • MPLIR05560I Cannot write log file.
  • MPLIR05561I No transaction.
  • MPLIR05562I No shared memory.
  • MPLIR05563I No BEGIN work yet.
  • MPLIR05564I Can not use nfs.
  • MPLIR05565I Audit trail exists.
  • MPLIR05566I F format error.
  • MPLIR05567I big for data item.
  • MPLIR05568I Open of wrong file type within transaction.
  • MPLIR05569I CLOSE REEL of non reel file ccvs85 only.
  • MPLIR05570I No READ or WRITE before DELETE of record.
  • MPLIR05571I Return from subroutine specified a value.
  • MPLIR05572I Return from function did not specify a value.
  • MPLIR05573I Creating INDEXED file requires keylength, keyloc and recsize.
  • MPLIR05574I file constant not initialized, -defext switch required.
  • MPLIR05575I SET requires files of type INDEXED (vsam) or CONSECUTIVE.
  • MPLIR05576I Omitting FROM clause requires files of type INDEXED (vsam) or CONSECUTIVE.
  • MPLIR05577I Programs linked with -ebm require DCB_ddname when insufficient attributes.
  • MPLIR05578I Unknown file-type specifier in DCB_ddname variable, use VSAM, STREAM or RECORD.
  • MPLIR05579I DCB_ddname has reference to a undefined environment variable.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05560I Cannot write log file.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05561I No transaction.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05562I No shared memory.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05563I No BEGIN work yet.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05564I Can not use nfs.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05565I Audit trail exists.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05566I F format error.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05567I big for data item.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05568I Open of wrong file type within transaction.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05569I CLOSE REEL of non reel file ccvs85 only.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05570I No READ or WRITE before DELETE of record.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05571I Return from subroutine specified a value.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05572I Return from function did not specify a value.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05573I Creating INDEXED file requires keylength, keyloc and recsize.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05574I file constant not initialized, -defext switch required.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05575I SET requires files of type INDEXED (vsam) or CONSECUTIVE.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05576I Omitting FROM clause requires files of type INDEXED (vsam) or CONSECUTIVE.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05577I Programs linked with -ebm require DCB_ddname when insufficient attributes.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05578I Unknown file-type specifier in DCB_ddname variable, use VSAM, STREAM or RECORD.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05579I DCB_ddname has reference to a undefined environment variable.

Parent topic: MPLIR05560 - MPLIR05579


MPLIR05580 - MPLIR05599

  • MPLIR05580I Invalid record length specifier in DCB_ddname value.
  • MPLIR05581I Unknown record format specifier in DCB_ddname value.
  • MPLIR05582I Can not open pathname defined in DCB_ddname environment variable.
  • MPLIR05583I Error reading file specified in DCB_ddname environment variable.
  • MPLIR05584I Error closing file specified in DCB_ddname environment variable.
Parent topic: MPLIR - PL/I Runtime Messages


MPLIR05580I Invalid record length specifier in DCB_ddname value.

Parent topic: MPLIR05580 - MPLIR05599


MPLIR05581I Unknown record format specifier in DCB_ddname value.

Parent topic: MPLIR05580 - MPLIR05599


MPLIR05582I Can not open pathname defined in DCB_ddname environment variable.

Parent topic: MPLIR05580 - MPLIR05599


MPLIR05583I Error reading file specified in DCB_ddname environment variable.

Parent topic: MPLIR05580 - MPLIR05599


MPLIR05584I Error closing file specified in DCB_ddname environment variable.

Parent topic: MPLIR05580 - MPLIR05599


Open PL/I Language Reference Manual

This book provides a reference to the language used in Micro Focus Open PL/I.

  • Language Concepts
    This section provides an overview of the Open PL/I language, explaining the following basic concepts: program structure and statement syntax, block structure, variables, files, input and output.
  • Data Types
    This section discusses the various data types that are available to you in Open PL/I.
  • Storage Classes
    This section describes storage classes and how they are used.
  • Declarations and Attributes
    This section explains how label prefixes and DECLARE statements are used for declarations, and also describes the attributes that can be used in a DECLARE statement.
  • References
    This section describes each type of reference and the rules and basic steps involved in resolving references.
  • Expressions
    This section explains expressions and how they are used.
  • Data Type Conversions
    This chapter defines the conversions that result from assignments to arithmetic variables, bit-string variables, and pictured variables.
  • Statements
    This section defines the Open PL/I statements. The statements are presented in alphabetical order by name.
  • Open PL/I Built-ins
    This section defines the built-in functions and subroutines provided by Open PL/I.
  • Open PL/I Macro Preprocessor
  • Features Unsupported by Open PL/I
    A list of features that are currently unsupported by Open PL/I.
  • Glossary
    This chapter provides definitions for terms used in the Open PL/I manuals.
Parent topic: Open PL/I Reference


Language Concepts

  • Statements
  • Names
  • Constants
  • Punctuation
  • Comments
  • Statement Sub-Groups
  • Text Replacement and Insertion Statements
  • Packages
  • Modules
  • Blocks
  • BEGIN Blocks
  • Variables
  • Files
  • Input and Output
Parent topic: Open PL/I Language Reference Manual


Statements

Open PL/I is a block-structured language. Each block consists of a group of statements. Statements are used to declare constants and variables, and to express actions to be performed by your program. For example:

READ FILE (G) INTO (Y) ;

In this example, the READ statement reads the next record in file G into storage Y.

Each Open PL/I statement consists of a series of elements ending with a semicolon. These elements can be PL/I keywords, user-specified identifiers, literal constants, or punctuation symbols.

Parent topic: Language Concepts


Names

A name used to denote part of a statement such as a verb, option, or clause, is called a keyword. All statements, except the assignment statement, begin with a keyword that identifies the purpose of the statement.

A name can also denote an object operated upon by the program, such as a variable, file, or label. These names are known as identifiers. Their meanings are established by a declaration.

In this example, G and Y are identifiers. READ, FILE, and INTO are keywords.

READ FILE (G) INTO (Y) ;

There are no reserved words in Open PL/I. In this example, TO names a storage location.

GOTO L;
CALL S(B,C,D);
RETURN;
STOP;
DO K = 1 TO 11;
TO = 20; /* ASSIGNMENT STATEMENT*/

The following example shows how names can either establish an object to be operated on or denote part of a statement.

DECLARE X(5) FIXED;
L: X(3) = 25;

Both X and L are identifiers, but DECLARE and FIXED are keywords. X is declared by a DECLARE statement; L is implicitly declared as a label.

A name consists of any combination of the following:

  • letters
  • digits
  • _ (underscore character)
  • @ (at sign character)
  • # (pound sign character)
  • $ (dollar sign character)
  • a sequence of any of the above characters

The following rules apply to names.

  • Any of the alphanumeric characters A through Z, a through z, and 0 through 9 can be used.
  • A name must not contain more than 32 characters.
  • Names cannot contain blanks or hyphens.

Examples:

STREET_NAME
@BETA
#Y7
C
$7

Names can be written using both uppercase and lowercase letters.

By default, all lowercase letters are interpreted as their uppercase equivalents. The -lowercase compiler option causes the reverse of this behavior. Refer to the Open PL/I User's Guide for more information on this option.

Because there are no reserved names in Open PL/I. Names that are used as keywords, 1such as READ or INTO, can also be identifiers. However, this practice makes programs difficult to read and should be avoided whenever possible.

  • Declarations of Names
  • References to Names
Parent topic: Language Concepts
Related information
Open PL/I User's Guide


Declarations of Names

The meaning of a name is normally determined by its declaration. However, in some cases a name can be implicitly declared by the context in which it is used. (For more information, see the sections Compiler-supplied Defaults and DEFAULT .) The declaration of a name consists of a user-specified identifier and the attributes of that name.

Open PL/I permits two kinds of explicit declarations: the DECLARE statement and the label prefix.

The DECLARE statement declares the names of files, variables, and external procedures. A DECLARE statement can appear anywhere within the program, except as part of a compound statement. Regardless of where it appears, DECLARE is not an executable statement and has no effect except to establish the meaning of names.

Examples:

DECLARE F FILE;
DECLARE A(5) FLOAT;
DECLARE (I,J,K) FIXED BINARY(15);

In the previous examples, F is declared as the name of a file constant; A is declared as a floating-point array variable; and I, J, and K are declared as integer variables.

A label, also called a label prefix, is a user-specified identifier that names a statement so that it can be referenced elsewhere in your program. The label comes before the statement and is terminated with a colon (:).

Examples:

F: FORMAT(F(8,2),A(5));
P: PROCEDURE;
L: READ FILE(F) INTO(X);

In these examples, F is declared as a format name, P as a procedure name, and L as a statement label.

Labels can appear on all Open PL/I statements except DECLARE statements, target statements of ON statements (called ON-units), ELSE or THEN clauses in IF statements, and WHEN or OTHERWISE clauses in SELECT statements.

Parent topic: Names
Related information
Compiler-supplied Defaults
DEFAULT
ON


References to Names

Use of a name in any context, other than in a declaration, constitutes a reference to the name. To determine the meaning of the reference, the Compiler searches for a declaration of the name. This search resolves the reference by associating it with a declaration. For example:

DECLARE A FIXED BINARY(15);
DECLARE B FLOAT;

B = B+1;

A = A+1;

In the previous example, the Compiler knows that it must generate a floating-point add for B+1 because it has resolved the reference B to the second DECLARE statement. Likewise, it knows that it must generate an integer add for A+1 because it has resolved the reference A to the first DECLARE statement.

Parent topic: Names
Related information
Reference Resolution


Constants

A constant is a sequence of characters that represents a particular, unchanging value. In Open PL/I, five kinds of constants are permissible:

  • Literal constants

    These are actual numbers or strings written in the source program. Literal constants are restricted to character strings, bit strings, and fixed- or floating-point numbers.

  • Label constants

    These are established using a label prefix in the source program that declares a name either as the name of a format or a procedure, or as a statement label. Label constants cannot be declared in a DECLARE statement.

  • File and entry constants

    These constants are typically established by DECLARE statements. File constants are identifiers declared with the FILE attribute to describe the type of input/output to be performed on a file. Entry constants are used to invoke procedures at certain entry points.

  • Replace constants

    These are identifiers that are to be changed with the %REPLACE statement. Like literal constants, constant identifiers can also be character strings, bit strings, and fixed- or floating-point decimal numbers.

  • Named constants

    These constants are scalar identifiers that are declared by the BYVALUE attribute. They can be declared for arithmetic data, string data, and for pointers and offsets.

Examples:

Constant | Type
25 | Integer constant
7.5 | Fixed-point decimal constant
3.12E-01 | Floating-point decimal constant
'How are you?' | Character-string constant
'1'B | Bit-string constant (binary notation)
'1011'B | Bit-string constant (binary notation)
'775'B3 | Bit-string constant (octal notation)
'A7O'B4 | Bit-string constant (hexadecimal notation)
'100'XN | Binary fixed-point (XN) constant (hexadecimal notation)
STARTUPD: | Label constant
%REPLACE TABLE_SIZE BY 350; | TABLE_SIZE is an identifier to be replaced by an integer constant
DECLARE E ENTRY; | E is an entry constant
DECLARE F FILE; | F is a file constant

For a table showing the expansion of nonbinary notation into binary notation, see the section Bit-String Data.

Arithmetic constants represent decimal values, whereas binary arithmetic values have no constant representation. Nevertheless, any decimal constant can be converted easily to a binary value by using it in a context that expects a binary arithmetic value.

As a result of Open PL/I language rules, all constants that appear as floating-point numbers in a source program are actually of type float decimal and are subject to the rules of float decimal arithmetic.

A character-string constant can contain any character, except that, if an apostrophe is required within a character-string constant, it is written as two apostrophes. For example,

'He said, "I''m fine."'

Open PL/I also supports string constants delimited by double-quotes ("). For example:

"He said, ""I'm fine."""
Note:

The double quotation mark character is not equivalent to a single quotation mark or two adjacent single quotation marks and has no more significance than any other character within a constant.

In Open PL/I, the maximum size of a string constant is 256 characters or bits (for details, see the section Open PL/I Compiler Implementation Limits). The Compiler checks this limit after bit-string constants written in the B2, B3, or B4 format have been expanded. Refer to the data type descriptions in the chapter Language Concepts in your Open PL/I User's Guide for the maximum size limits for floating- and fixed-point data.

A named constant is similar to a scalar declaration with the appropriate data attributes, plus the BYVALUE attribute. The BYVALUE attribute signifies this identifier is a named constant, with all of the attributes taken as applied to the declaration.

Named constants differ from simple constants in that they retain the attributes from the declaration. For example,

dcl i fixed bin (15) byvalue(1);
dcl j fixed bin (15);

J = 1;    /* 1 is fixed dec, requires conversion */
J = I;    /* I is fixed bin (15), no conversion (integer 1 assigned, not "i" ) */

For string data items, the length is determined from the length of the string value when the length is not specified.

declare string char value ('abcdef') ; /* string is char(6) */

An XN constant is a SIGNED fixed binary constant in hexadecimal notation. An XN constant with eight or fewer digits has a precision of 31. An XN constant with more than eight digits has a precision of 63.

The XN constant hexadecimal value is the value specified, padded on the left with hexadecimal zeros if needed. For example:

'102'XN 			/* same as '00000102'XN with value 258 */
'9C40'XN   /* same as '00009C40'XN with value 40,000 */
'7FFF'XN   /* same as '00007FFF'XN with value 32,767 */

An XU constant is an UNSIGNED fixed binary constant in hexadecimal notation. An XU constant with eight or fewer digits has a precision of 32. An XU constant with more than eight digits has a precision of 64.

The XU constant hexadecimal value is the value specified, padded on the left with hexadecimal zeros if needed. For example:
'102'XU /* same as '00000102'XU with value 258 */
'9C40'XU /* same as '00009C40'XU with value 40,000 */
'FFFF'XU /* same as '00007FFF'XU with value 65,535 */

In Open PL/I, named constants can be declared as arithmetic or string; pointers and offsets are not yet supported. Named constants can be declared before or after being used, and the same scoping rules as any declaration apply.

Example:

cool: proc options(main);

   dcl pname char (16) byvalue (procedurename());

   dcl flag bit(1) aligned static init(true);

   dcl true bit(1) byvalue ('1'b);
   dcl false bit(1) byvalue('0'b);

   dcl myarr (n) fixed bin (15);

   dcl n fixed bin(15) byvalue (800);

   dcl arr (k/3) fixed bin (15) static init (k+1, k, k+3);

   dcl arr1 (100+100) fixed bin (15);
   dcl arr2 (n+100) fixed bin (15);

   dcl i fixed bin (15);
   dcl k fixed bin (15) byvalue (9);

   if flag then
       put skip list ('Named Constants are ', pname);

   put skip list(arr);

   i = n + 100;
   arr1 (k) = 99;

   put skip list (size(arr1), size(arr2), i, arr1(K*2-K));

   put skip list(arr);
end;

Named Constants are     COOL
       10               9              12
      400            1800             900              99
       10               9              12

You can punctuate arithmetic, bit, and hexadecimal constants with the break character ( _ ) to improve readability. For example:

'1100_1111'B is the same as '11001111'B

'F_E'B4 is the same as 'fe'b4

16_666_667 is the same as 16666667

Parent topic: Language Concepts
Related information
Text Replacement and Insertion Statements
Bit-String Data
B-Format


Punctuation

In Open PL/I, punctuation symbols are either operators or separators.

Operators define the arithmetic or comparative operations to be performed on expressions in a statement. The table below lists the Open PL/I operators.

Symbol | Meaning
+ | Addition or the plus prefix
- | Subtraction or the minus prefix
* | Multiplication
** | Exponentiation
/ | Division
^ or ~ | Logical NOT
| or ! | Logical OR
& | Logical AND
> | Greater than
< | Less than
= | Equal to
^> or –> | Not greater than
^< or –< | Not less than
^= or ~= | Not equal to
>= | Greater than or equal to
<= | Less than or equal to
|| or !! | String concatenation
–> | Pointer resolution

Separators delimit and separate identifiers, keywords, and constants in statements. The table below lists the Open PL/I separators.

Symbol
 | Meaning
( ) | Encloses lists, defines order of expression evaluation, separates names of statements and options from specific keywords
, (comma) | Separates subscripts and procedure arguments, separates identifiers in a structure name, and precedes the BY NAME option
' (single quote) | Delimits bit strings and character strings
. (period) | Specifies a decimal point. Connects elements of a qualified name
: | Terminates a procedure name or a statement label
; | Delimits statements

Names and constants may be separated from one another by one or more blanks, or tabs, rather than by separators. Additional blanks surrounding punctuation symbols are optional. In the following examples, blanks are represented by boxes ( Blank representation).

Examples of blank usage

The first statement requires no blanks because each name is separated from the next by a punctuation symbol. The second statement shows the optional use of extra blanks. The third statement shows optional blanks surrounding the equal symbol (=) and after the semicolon, the remaining blanks being required blanks.

Note that when an arithmetic constant is followed by a name, at least one blank or punctuation symbol is required to separate the arithmetic constant from the name.

Parent topic: Language Concepts


Comments

Comments are used to document an Open PL/I program. A comment can appear anywhere that a blank can appear and is equivalent to a blank. Comments cannot be nested. The general form of a comment is:

/*Comments open with a slash* and close with a *slash */

For example,

/*HERE IS A COMMENT*/
IF A<25 /* HERE IS ANOTHER ONE */ THEN
/*HERE IS AN /* ERRONEOUS */ COMMENT */

The final comment is invalid because comments cannot be nested; it ends at the first * / in the line and the Compiler attempts to interpret COMMENT */ as code and produces an error message.

The Compiler puts an asterisk (*) into the line number field of the listing file for each line on which a comment is continued from a preceding line. This convention can be used to determine if some text was accidentally included in a comment.

Comments can continue over any number of lines of program text; thus, if the */ is omitted from a comment, all program text up to the next */ is considered part of the comment. This causes part of the program to be ignored by the Compiler and may cause it to produce misleading error messages. The same problem occurs if a character-string or bit-string constant is not terminated with an apostrophe.

Parent topic: Language Concepts


Statement Sub-Groups

This section introduces certain Open PL/I statements that, alone or in conjunction with other statements, provide specific capabilities within Open PL/I.

  • Compound Statements
  • Statements that Alter the Order of Execution
  • Statement that Handles Exception Conditions
Parent topic: Language Concepts
Related information
Statements


Compound Statements

Open PL/I has four compound statements:

  • IF
  • ON
  • DO
  • SELECT

They are called compound statements because they each contain other statements.

  • IF Statement
  • ON Statement
  • DO Statement
  • SELECT Statement
Parent topic: Statement Sub-Groups


IF Statement

The IF statement tests an expression and performs a specified action if the result of the expression is true. Its general form is:

IF expression
    THEN statement;
    [ELSE statement];

where expression is any valid expression that yields a scalar bit-string value, and statement is any unlabeled statement (except DECLARE, END, ENTRY, FORMAT, or PROCEDURE) or an unlabeled DO-group or BEGIN block. For example:

IF A>B
    THEN READ FILE (F) INTO (X);

In this example, the IF statement contains the READ statement. If the expression A>B is true, the READ statement executes.

The IF statement needs no semicolon of its own because each statement contained within it has its own semicolon. IF statements can be nested, as shown in the following example.

IF A>B
    THEN IF D<C
        THEN READ FILE(F) INTO(X);
        ELSE STOP;

In this example, the second IF statement has both a THEN clause and an ELSE clause. An ELSE clause always corresponds to the THEN clause that immediately precedes it. The first IF statement has only a THEN clause. If you want to STOP when A ^> B, you may provide a null ELSE clause to the innermost IF, forcing the ELSE STOP to be associated with the first IF. It is preferable to use structured IF, THEN, and DO statements to accomplish this, as shown in the following example.

IF A>B THEN DO;
    IF D<C THEN READ FILE(F) INTO (X);
    END;
ELSE STOP;
Parent topic: Compound Statements
Related information
Short Circuit Evaluation


ON Statement

The ON statement defines the action to be taken when a specific condition is signaled during the execution of a program. Its general form is:

ON condition–name ON-unit,

or

ON condition–name SYSTEM

where:

condition-name is ANYCONDITION, AREA, ATTENTION, CONDITION(name), CONVERSION, ENDFILE(f), ENDPAGE(f), ERROR, FINISH, KEY(f), OVERFLOW, RECORD(f), SIZE, UNDEFINEDFILE(f), UNDERFLOW, USERCONDITION(expression), USERCONDITION(SS$_UNWIND), or ZERODIVIDE.

ON-unit is a BEGIN block or any statement other than DECLARE, DEFAULT, DO, END, ENTRY, FORMAT, LEAVE, OTHERWISE, PROCEDURE, RETURN, or SELECT.

The keyword SYSTEM indicates that, instead of executing user-specified code in the ON-unit, a system-generated message describing the condition is displayed and the ERROR condition is signaled. For example:

ON ENDFILE (F )
    BEGIN;
       .
       .
       .
    END;

In this example, the block of statements between the BEGIN and END statement executes if the end-of-file condition is reached.

ON is a compound statement, but it cannot be nested. The ON statement's use in responding to exceptional conditions is explained more fully in the section Statement that Handles Exception Conditions.

Parent topic: Compound Statements
Related information
Statement that Handles Exception Conditions


DO Statement

The DO statement begins a sequence of statements to be executed in a group, called a DO-group. Its general form is:

DO;
  .
  .
  .
END;

For example:

IF B < C THEN DO;
   PUT LIST ('ADDED DATA REQUIRED');
   GET LIST (VALUE);
   B = B + VALUE;
   END;

In this example, the PUT LIST, GET LIST, and assignment statements execute if B < C.

DO statements can contain IF statements, other DO-groups, RETURN statements, or GOTO statements that alter the order of execution.

Parent topic: Compound Statements


SELECT (PL/I Language Concepts)

SELECT Statement

The SELECT statement tests a series of expressions and performs the action specified with the first true test, or the action associated with the OTHERWISE clause (if present) and none of the tests evaluates true. Its general form is:

SELECT[select-expression];
    WHEN (e1[,e2[,e3[...]]])    action_1;
    WHEN (e4[,e5[,e6[...]]])    action_2;
       .
       .
       .
    [OTHERWISE action_m;]
END;

where select-expression and e1, e2... are valid expressions, and each action is a single or compound statement or a BEGIN block. For example:

SELECT;
    WHEN (F=40) G=G+1;
    WHEN (F=50) IF G > 0 THEN G=G+2;
       .
       .
       .
    OTHERWISE DO;
              .
              .
              .
              END;
END;

This example shows the SELECT statement used with the expression omitted. When the expression is omitted from the SELECT statement, each WHEN clause expression is evaluated and converted, if necessary, to a bit string. The action after the WHEN clause is performed if the resulting bit string is nonzero. In the above example, if F=40 is true, the action G=G+1 is executed and the SELECT group is exited. If F=50 is true, the IF statement is executed and the SELECT group is exited. If more than one WHEN statement is true, the action associated with the first true WHEN clause is executed. If no WHEN clauses are true, the DO group associated with the OTHERWISE clause is executed.

When control reaches a SELECT statement with a select–expression present, the select-expression is evaluated and its value saved. Next, the expressions in the WHEN clauses are evaluated in the order in which they appear, and each value is compared with the value of select–expression. If a value is found that is equal to the value of select–expression, the action following the corresponding WHEN clause is performed, and no further WHEN clause expressions are evaluated. If none of the expressions in the WHEN clauses is equal to the select–expression, the action specified after the OTHERWISE clause is executed unconditionally. for more information, see the section SELECT in the chapter Statements.

Parent topic: Compound Statements
Related information
SELECT


Statements that Alter the Order of Execution

Statements are typically executed in the order in which they are written; however, certain statements control the order of execution of the program. These statements are GOTO (used with a statement label), IF, and DO.

The GOTO statement causes control to be transferred to a labelled statement in the current procedure or in another active procedure. Its general form is:

GOTO label–reference[OTHERWISE];

or

GO TO label–reference[OTHERWISE];

where:

label–reference is a label constant or an expression that, when evaluated, yields a label value. (A label value denotes a statement in the program.) For example:

A = 5;
   GOTO L2;
L1:
   B = 7;
     .
     .
     .
L2:
   B = 4;

In this example, A is assigned 5 and B is assigned 4. The statements beginning with label L1 can be executed only if a GOTO statement transfers control to the label L1.

Although labels are a convenient means to represent a specific location in a program, programs that contain many labels are generally more difficult to read and modify. The use of labels and GOTOs can be avoided or minimized by using the compound statements IF and DO to control the order of statement execution.

The DO statement causes all statements between the DO statement and its corresponding END statement to be executed a number of times as determined by the form of the DO statement.

Parent topic: Statement Sub-Groups


Statement that Handles Exception Conditions

The ON statement gives your Open PL/I programs the ability to respond to exception conditions that occur during the execution of a program, such as end-of-file, or computational errors such as division by zero. For example:

ON ERROR
   BEGIN;
      .
      .
      .
   END;

ON statement execution establishes the ON-unit as a block of statements that are executed if the specified condition occurs. If the specified condition occurs after the ON statement is executed, processing is interrupted and the specified ON–unit is executed. In the above example, the block of statements between the BEGIN and END statements are established as the ON–unit, which executes if the ERROR condition occurs. Execution of the ON statement does not cause immediate execution of the ON-unit.

An ON-unit is established within its containing block's current activation and remains established until that block returns to its caller, or until another ON-unit is established for the same condition within the same block activation, or until the ON-unit is reverted using the REVERT statement.

If one of the possible conditions occurs during the execution of a block, and that block does not have an established ON-unit for that condition, the calling block's ON-unit is used to respond to the condition. If the calling block has no established ON-unit for the condition, its caller's ON-unit is used, and so on. If no ancestor has an ON-unit for the condition, a default action is taken. Except for the ENDPAGE, FINISH, and UNDERFLOW conditions, this default action ends program execution and issues a run-time error message.

Notifications can be set up whenever a condition is detected that triggers an ON-unit. This allows you to investigate program state at ON-units to aid debugging and set up optional breakpoints. See Checking Program State with ON-unit Notification for more information.

ON-units for the ERROR condition cannot resume execution of the statement in which the error was detected.

Parent topic: Statement Sub-Groups
Related information
Checking Program State with ON-unit Notification


Text Replacement and Insertion Statements

When a program module is being compiled, the Compiler is able to recognize and evaluate two statements that alter the program text: %INCLUDE and %REPLACE. Both of these statements can be used anywhere within a procedure or source file to simplify the job of writing programs.

Other statements that alter program text are described in Open PL/I Macro Preprocessor.

  • The %INCLUDE Statement
  • The %REPLACE Statement
Parent topic: Language Concepts
Related information
Open PL/I Macro Preprocessor


The %INCLUDE Statement

The %INCLUDE statement incorporates text from other files into the current source file during compilation. The general form of this statement is:

%INCLUDE filename[,filename]...;

where:

filename is one of the following:

  • A character string
  • An Open PL/I name
  • An Open PL/I name enclosed in parentheses

The specified filename is used to locate a text file whose content is inserted into the program text in place of the %INCLUDE statement.

Your selection of one of these forms in combination with the presence or absence of the -ipath compiler option affects the search pattern used in locating files to be included. For more information, see the section %INCLUDE in the chapter Statements.

Note:

The Open PL/I Macro Preprocessor has its own %INCLUDE statement. Its use is documented in the appendix Open PL/I Macro Preprocessor.

Parent topic: Text Replacement and Insertion Statements
Related information
%INCLUDE
Open PL/I Macro Preprocessor


The %REPLACE Statement

The %REPLACE statement specifies that an identifier is to be replaced by a specified constant or other name during compilation. The general form of this statement is:

%REPLACE name BY constant-or-name;

Beginning at the point at which the %REPLACE statement is encountered, each occurrence of name that follows the %REPLACE statement is replaced by the specified constant or other name until the end of compilation.

The %REPLACE statement is often used to supply the sizes of tables or to give names to special constants whose meaning would not otherwise be obvious. For example:

%REPLACE TRUE BY '1'B;
%REPLACE TABLE_SIZE BY 400;
%REPLACE MOTOR_POOL BY 5;
%REPLACE X BY -3.0E0;
DECLARE X(TABLE_SIZE) FIXED STATIC;
DO K = 1 TO TABLE_SIZE;
IF DEPARTMENT_NUMBER = MOTOR_POOL
   THEN DO;
    .
    .
    .

Both the %REPLACE and %INCLUDE statements operate on the program text without regard to the meaning of the text.

The %REPLACE statement substitutes all subsequent occurrences of the name without regard to the block structure of the module, as explained in the section Blocks.

Parent topic: Text Replacement and Insertion Statements
Related information
Blocks


Packages

A package is a block that can contain only declarations, default statements, and procedure blocks. The package forms a name scope that is shared by all declarations and procedures contained in the package, unless the names are declared again. Some or all of the level-1 procedures can be exported and made known outside of the package as external procedures. A package can contain zero or more procedures, and any or all procedures in a package can be exported. Use a package to implement multiple entry point applications.

Parent topic: Language Concepts


Modules

If the PACKAGE statement is omitted, one or more external procedures can exist in a single Open PL/I source file as shown in this code sample.

PKG: PACKAGE EXPORTS (SUB1 EXTERNAL(‘PLB’));
   SUB1: PROC;  /* will be external, callable as “PLB”) */
       CALL SUB2();
   END SUB1;

   SUB2: PROC;  /* will be internal, not exported */
       PUT SKIP LIST (‘PACKAGE NAME = ‘, PACKAGENAME());
   END SUB2;

END PKG;

All external procedures within a source file are compiled into a single object file.

A module is defined as a single compilation unit, a source file that is compiled into object code. A module consists of one or more external procedures.

A source file may contain declarations that appear outside the scope of any external procedure, as long as all variables that appear in such declarations are BASED, STATIC, or DEFINED. A variable that is defined this way is known within the scope of all external procedures. If a declaration is provided with the EXTERNAL attribute, it will be known outside the source file.

A source file may also contain %REPLACE statements and declarations of named constants (for example, file and entry constants) before the first external procedure.

The following example illustrates a source file that has declarations and %REPLACE statements preceding the first external procedure. There are two procedures (GETREC and PUTREC) in the source file that can be used as part of the program. By default, Open PL/I declares these entry constants, GETREC and PUTREC, with the EXTERNAL attribute; therefore, a procedure from another module outside of this source file can invoke GETREC or PUTREC. If a procedure in another module needs to reference GETREC and PUTREC, they must be declared within that module with the attributes ENTRY and EXTERNAL.

At the top of this source file are other items (REC, NAME, ADDRESS) that are hidden from any procedures compiled in other modules, and are known only to GETREC and PUTREC. Because Open PL/I, by default, provides file constant declarations with the EXTERNAL attribute, the file DATA_BASE can be known in other modules.

%REPLACE DATA_SIZE BY 80;
DECLARE 1 REC BASED
            2 NAME CHAR(40),
            2 ADDRESS CHAR(DATA_SIZE);
DECLARE DATA_BASE KEYED FILE UPDATE;

GETREC: PROCEDURE(P);
DECLARE P POINTER;
READ FILE(DATA_BASE) INTO(P->REC);
END GETREC;

PUTREC: PROCEDURE(P);
   DECLARE P POINTER;
    REWRITE FILE(DATA_BASE) FROM(P->REC);
END PUTREC;
Parent topic: Language Concepts


Blocks

PL/I is a block-structured language. Just as certain language elements make up statements, groups of statements make up blocks. Two types of blocks exist in Open PL/I:

  • Procedure blocks
  • BEGIN blocks

A procedure block is the basic executable program unit of Open PL/I and is made up of a group of statements contained within the limits of a pair of statements, PROCEDURE and END.

A BEGIN block is a program unit into which control flows during the typical execution of a procedure. The statements within a BEGIN block are contained within the limits of a pair of statements, BEGIN and END.

Whenever a procedure block or BEGIN block is entered, a block activation is created for that block. The block activation consists of the allocation of storage for the variables declared within the block and the system information that links that block to the previous block in the activation chain.

The following sections provide detailed information on procedure and BEGIN blocks and activation of these blocks.

  • Procedure Blocks
Parent topic: Language Concepts


Procedure Blocks

A procedure is a sequence of statements beginning with a PROCEDURE statement and ending with an END statement. The purpose of a procedure is to "package" a set of executable statements and declarations to form a block that can be executed from several places in the program simply by calling it. Because a procedure defines a block of statements, it is typically called a procedure block. The following example shows two procedure blocks, A and B:

A: PROCEDURE;
      .
      .
      .
   END A;

B: PROCEDURE;
      .
      .
      .
   END B;

Procedures contained within other procedures are called nested or internal procedures. Procedures not contained within other procedures are called external procedures. A program module consists of one or more external procedures. For example:

A: PROCEDURE;
      .
      .
      .
   B: PROCEDURE;
             .
             .
             .
   END B;
   C: PROCEDURE
      .
      .
      .
      D: PROCEDURE;
             .
             .
             .
      END D;
   END C;
END A;

In this example, Procedure A is external, and procedures B and C are nested within it. Procedure D is nested within procedure C.

  • Scope
  • Calls and Returns
  • Parameters and Arguments
  • Block Activation and Recursion
  • Guidelines for Using Procedures
  • Dynamic Fetching and Releasing of External Procedures
Parent topic: Blocks


Scope

Each procedure block establishes a distinct region of the program text called "scope," throughout which the names declared within that procedure block are known. The scope of a name is defined as the region of the program in which the name has meaning and can be referenced.

The scope of a name includes the procedure in which the name is declared and all procedures contained within that procedure, except those contained procedures in which the same name is redeclared. For example:

A: PROCEDURE;
   DECLARE (X,Y) FLOAT;
      .
      .
      .
   B: PROCEDURE;
      DECLARE X FILE;
      DECLARE Z FIXED;
            .
            .
            .
   END B;
END A;

In this example, the scope of Y includes both procedure A and procedure B. The scope of X as a float is only procedure A. The scope of X as a file is procedure B. The scope of Z is procedure B. Z cannot be referenced from within procedure A. The scope of the procedure name B includes both procedure A and procedure B.

Parent topic: Procedure Blocks


Calls and Returns

Statements within a procedure block are executed only when the procedure block is called from another procedure block. The CALL statement enables procedure calling. For example:

A: PROCEDURE;
      .
      .
      .
   CALL B;
      .
      .
      .
B: PROCEDURE;
      .
      .
      .
   END B;
      .
      .
      .
   END A;

In this example, procedure B is executed only when it is called from procedure A. Procedure A resumes execution at the statement following the call when B is completed.

A procedure returns to its caller either by executing its END statement or by executing a RETURN statement, as shown in the following example:

A: PROCEDURE;
      .
      .
      .
   IF X<0 THEN RETURN;
      .
      .
      .
   END A;

Control does not "flow" into a procedure; that is, if control reaches a statement immediately preceding a procedure declaration, then (unless the statement is a control-flow statement such as GOTO) control will automatically skip to the statement following the declared procedure.

Parent topic: Procedure Blocks


Parameters and Arguments

The usefulness of a procedure block is increased greatly if it can be made to operate on different values each time it is called. Arguments and parameters enable such operation.

Arguments are the values passed to a procedure block at invocation. Parameters are the names used by the invoked procedure block to refer to these arguments.

Open PL/I typically passes an argument to an invoked procedure by referencing its storage address.

For example:

   CALL P(A,B);
      .
      .
      .
   CALL P(D,E);
      .
      .
      .
P: PROCEDURE(X,Y);
      .
      .
      .
   PUT FILE (F) LIST(X,Y);
      .
      .
      .
   END P;

In this example, A and B are arguments of the first call to the procedure P. While P is executing as a result of the first call, the argument A is said to correspond to the parameter X and the argument B corresponds to the parameter Y. While P is executing as a result of the second call, D corresponds to X and E corresponds to Y.

When an argument is a variable, the actual address of the variable is passed to the called procedure. This allows the invoked procedure to change the value of the argument.

When an argument is a constant or an expression, a temporary location is used to store the current value of the argument, and the address of that temporary location is passed to the called procedure.

Parent topic: Procedure Blocks


Block Activation and Recursion

Each time a procedure block is called, it is said to be active, and it remains active until it returns from the call (or until a non-local GOTO transfers control to a containing block activation). Such procedure activation has an associated block of storage allocated on a stack. This block of storage is called a stack frame, and it is used to hold information (such as the location to which control should return from the activation) that is unique to each procedure activation.

The stack frame contains storage for the automatic data declared within the block. Thus, each activation of the block has its own copy of the automatic data.

If procedure A calls procedure B, the stack frame associated with the activation of A is pushed down by the stack frame associated with the activation of B. When B returns, its stack frame is popped from the stack and the stack frame of A is then the current stack frame.

If procedure A calls itself directly or indirectly by invoking a chain of procedures in which A is again called, A is said to be a recursive procedure. For example:

A: PROCEDURE RECURSIVE;
      .
      .
      .
   CALL A;
      .
      .
      .
   END A;

The following example shows a program that makes a copy of a tree structure using block activation and recursion principles.

   .
   .
NEW = COPY(OLD);
   .
   .
COPY: PROCEDURE(IN) RETURNS(POINTER)| RECURSIVE;
      DECLARE     (IN,OUT) POINTER;
      DECLARE     1 RECORD BASED,
                        2 FIELD1 FLOAT,
                        2 FIELD2 FLOAT,
                        2 DAUGHTER POINTER,
                        2 SON POINTER;
DECLARE NULL BUILTIN;

IF IN = NULL THEN RETURN(NULL);
ALLOCATE RECORD SET(OUT);
OUT->RECORD.FIELD1 = IN->RECORD.FIELD1;
OUT->RECORD.FIELD2 = IN->RECORD.FIELD2; OUT->RECORD.DAUGHTER =
      COPY(IN->RECORD.DAUGHTER);
OUT->RECORD.SON = COPY(IN->RECORD.SON);
RETURN(OUT);

END COPY;

As demonstrated in this example, each record of the original tree structure may be linked using pointers to a SON record and/or a DAUGHTER record. Either the SON or the DAUGHTER field may contain a null pointer value. COPY is called with a pointer to the root in the original tree structure. It returns a pointer to the root in a new tree structure that is a copy of the original. Each activation of the COPY procedure has its own instance of the variables IN and OUT.

For additional information about recursive procedures, see the section Entry Data in the chapter Data Types.

Parent topic: Procedure Blocks
Related information
Entry Data


Guidelines for Using Procedures

Procedures are a natural division of the program and therefore provide the best mechanism to represent program modularity. The program should be organized or structured as a set of modules, each of which is written as a procedure.

Adhere to the following guidelines when using procedures:

  • Write procedures with minimal dependence on their ability to access the values of their containing procedure. All such use of nonlocal variables should be clearly documented by comments in both the declaring and the using procedures.
  • Write procedures that are used only from within a given procedure as internal procedures within the calling procedure. Write internal procedures following the executable statements of the containing procedure.
  • Make each procedure as small as possible to enable understanding of program logic.
Parent topic: Procedure Blocks


Dynamic Fetching and Releasing of External Procedures

An external procedure can be dynamically fetched or released by a program. This means that it can be loaded or deleted by the program using the FETCH and RELEASE statements. When the procedure is not in main storage, it can be loaded into it and then deleted from it at any time during the execution of the calling procedure. This is useful when it is not necessary to call the external procedure every time when the calling procedure is executed.

A procedure has to be loaded into main storage before it can be executed, unless it is already there. Once loaded, the procedure can remain in main storage until the execution of the whole program is completed, or it can be deleted at any time using the RELEASE statement.

A fetched procedure is compiled and linked separately from the calling procedure. For more information, see Compiling, Linking and Debugging of Fetchable Procedures.

Whenever the load module containing the fetched procedure is loaded into memory, the STATIC variables in the fetched procedure are given the initial values indicated by their declarations.

Note that EXTERNAL files and CONDITION conditions are shared across the whole application, including the fetched procedures.

  • FETCH Statement
  • RELEASE Statement
  • Restrictions
Parent topic: Procedure Blocks
Related information
Compiling, Linking and Debugging of Fetchable Procedures


FETCH Statement

Purpose

Dynamically loads an external procedure into main storage.

Syntax

FETCH entry-constant [SET(ptr-ref)][TITLE (char-expr)]

Parameters

entry-constant
The name by which the loaded procedure is known to the operating system. It is the same as the one used in the corresponding CALL statement, or CALL option of an INITIAL attribute, or function reference.
ptr-ref
A pointer reference that is set to the address of the entry point of the module that is loaded.
char-expr
Any character expression.

Description

The FETCH statement is used to dynamically load modules into main storage. It must specify an entry constant, which is the name by which the fetched procedure is known to the operating system. When this name is referenced in a FETCH statement, the procedure can also be loaded into main storage when a CALL statement, or a CALL option of an INITIAL attribute, or a function reference is executed.

Restrictions

See Restrictions under Dynamic Fetching and Releasing of External Procedures.

Parent topic: Dynamic Fetching and Releasing of External Procedures
Related reference
RELEASE Statement
Related information
Dynamic Fetching and Releasing of External Procedures


RELEASE Statement

Purpose

Deletes from main storage a previously fetched procedure.

Syntax

RELEASE entry-constant

Parameters

entry-constant
The RELEASE statement must specify an entry constant. It is the name by which the loaded procedure is known to the operating system. It is the same as the one used in the corresponding FETCH statement, CALL statement, CALL option of an INITIAL attribute, or function reference.

Description

The RELEASE statement releases (deletes) from main storage a previously fetched modules. RELEASE * deletes all previously fetched modules. It must not be executed from within a fetched module.

Restrictions

See Restrictions under Dynamic Fetching and Releasing of External Procedures.
Note: RELEASE* is not currently supported but an API can be provided if this functionality is needed.
Parent topic: Dynamic Fetching and Releasing of External Procedures
Related reference
FETCH Statement
Related information
Dynamic Fetching and Releasing of External Procedures


Restrictions

  • On AIX it is necessary to link with an export list for the entry point within your fetchable procedure that the main program will be calling. If you utilize the mfplx or ldpli command to link your fetchable procedure, it will assume that you have an export list of the same base name with an extension of .exp present. If you manage your own links via the operating system's ld command, you have full control. You can also edit the ldpli shell script that is provided with the product to provide the behavior you consider appropriate.
  • Any fetchable procedure declared with OPTIONS(MAIN) that uses the -cics, -ims, or -mvs compiler options has its own run time context and ON UNIT's memory chains, and its variables are not shared across fetchable boundaries.
  • Any fetchable procedure that is called from an OPTIONS(MAIN) and compiled and/or linked -cics, -ims, or -mvs must be built using the -bigendian compiler option to avoid any conflicts with variables passed between the main program and fetched subroutines. Using a fetchable where the subroutine's procedure statement uses OPTIONS(MAIN) is not recommended.

  • For any program which does any form of file I/O, the following needs to be done:

    • For each FILE declaration it must have storage allocated to its FILE constant. This is achieved through the use of the -defext compile option and/or through the use of an optional parameter called GLOBALDEF. It is important that within a fetchable procedure or a program compiled with OPTIONS(MAIN), this is done exactly one time per FILE constant. If this is not done, the results are completely unpredictable and the behaviors will not be supported.
    • For typical usage, compiling with -defext is more than adequate. If you have two or more subroutines which are all accessing the same FILE constant, and they are linked into a single fetchable procedure or program, only one of the programs should be compiled with -defext. As an alternative approach you can add the attribute GLOBALDEF to one of the file declarations and not use the -defext switch for any of the compiles.
Parent topic: Dynamic Fetching and Releasing of External Procedures


BEGIN Blocks

A BEGIN block is a sequence of Open PL/I statements into which control flows during the routine execution of a program. A BEGIN block differs from a procedure in that it is invoked by executing its BEGIN statement, it cannot have any parameters, and it always returns by executing its END statement. In addition, execution of a RETURN statement within a BEGIN block returns to the caller of the procedure that immediately contains the BEGIN block. And, unlike a procedure, a BEGIN block can be used as the ON–unit of an ON statement.

The BEGIN block groups a set of program statements and defines a scope for the names declared within it. Generally, the reason for using a BEGIN block is to create a new scope and/or a new block activation. BEGIN blocks can contain DO-groups, SELECT groups, DECLARE statements, and procedures, as well as other BEGIN blocks.

The statements of a BEGIN block are bounded by BEGIN and END statements, as shown in the following example:

BEGIN;
   .
   .
   .
END;

Since the BEGIN block contains declarations and ON-units, as well as executable statements, it can be used to permit temporary redefinitions of names and exception handlers, as well as to provide a means of allocating and freeing AUTOMATIC variables within it. (For additional information about AUTOMATIC variables, see the section Storage Classes.) For example:

DECLARE SUM FIXED BINARY;
   .
   .
   .
BEGIN;
DECLARE SUM FILE;
DECLARE X(1000) FLOAT;
   .
   .
   .
END;

In this example, SUM is redeclared within the BEGIN block so that it can be used as a file. A large array X is declared within the BEGIN block and is allocated storage only during the execution of the BEGIN block.

Parent topic: Language Concepts
Related information
Storage Classes


Variables

A variable is a named object that is capable of holding values. Each variable has two properties:

Data type
Determines the kind of values a variable holds.
Storage class
Determines the duration of a variable's existence and how it is referenced.
  • Data Types and Conversion
  • Storage Classes
Parent topic: Language Concepts


Data Types and Conversion

Each variable must be declared to have a data type. Except for cases under control of the DEFAULT statement, failure to specify a data type causes the Compiler to issue a warning and to give the variable a data type of Fixed Binary(15) if its name begins with any of the letters I through N; otherwise, the variable is given a data type of Float Decimal(6).

A complete discussion of data types is contained in the chapter Data Types. The following examples show several data types available in Open PL/I.

Examples:

DECLARE A FLOAT DECIMAL(7);
DECLARE N FIXED BINARY(15);
DECLARE C CHARACTER(30);
DECLARE B BIT(1);

In these examples, variable A is capable of holding any floating-point decimal value with mantissa of up to 7 digits and exponent of up to 3 digits; variable N is capable of holding any binary integer value between -32768 and +32767 inclusive; variable C is capable of holding any string of 30 characters; and variable B is capable of holding either '1'B or '0'B.

Although each variable is capable of holding values of only a specific data type, the Open PL/I language provides a complete set of operations that convert values from one data type to another. Whenever a value is assigned to a variable, it is first converted to the data type of the variable, as illustrated in the following examples (which refer to the declarations in the previous examples).

Examples:

A = 1; /* converts 1 to FLOAT DECIMAL(7) */
N = 2.5; /* converts 2.5 to the FIXED BIN(15) integer 2 */
C = -4.5; /* converts -4.5 to a character string */
B = 0; /* converts integer 0 to '0'B */

For a complete discussion of data type conversions, see the chapter Data Type Conversions.

Parent topic: Variables
Related information
Data Types
Data Type Conversions


Storage Classes

A variable's storage class determines when and for how long storage is to be allocated for the variable. Since this storage holds the variable's value, the storage class of a variable determines how long the variable retains its value.

The Open PL/I language permits the following six storage classes, which are fully explained in the section Storage Classes.

  • AUTOMATIC
  • BASED
  • CONTROLLED
  • DEFINED
  • STATIC (INTERNAL or EXTERNAL)
  • parameter

Unless declared otherwise, a variable's storage class is AUTOMATIC, meaning that it is allocated storage each time its immediately enclosing scope becomes active (as happens during a procedure call or the execution of a BEGIN statement. Exiting the scope frees this allocated storage (as happens at procedure or BEGIN block termination). Consequently, AUTOMATIC variables do not retain their values after deactivation of the block in which they are contained.

If a variable must retain its value between calls of its containing procedure, it should be declared to have the STATIC storage class. For example:

DECLARE K FIXED BINARY STATIC;
DECLARE TABLE(4) CHARACTER(5)
      STATIC INITIAL('A','B','C','D');

In this example, each element of the array TABLE is given an initial value.

Storage for STATIC variables is allocated prior to program execution by the Compiler and linker. Consequently, the length (precision) of each STATIC variable must be constant at compile time.

Parent topic: Variables
Related information
Storage Classes


Files

In Open PL/I, a file is a source of input data or a target for data output. Files are referenced in I/O statements by using a file name declared with the FILE attribute. The file reference actually refers to a file constant or to a file variable that has been assigned a value.

Each file used by the program must be declared in exactly one module in the program. That module must either declare the file with the GLOBALDEF attribute or must be compiled with the -defext option.

  • File Constants
  • File Variables
  • Using Environment Variables
  • ASA Control Character Support
    Brief description of concept. Should be written as a fragment. Contains no more than two sentences.
Parent topic: Language Concepts


File Constants

A file constant is an identifier declared with the FILE attribute and without the VARIABLE attribute. For example:

DECLARE F FILE;

In this example, F is the name of a file constant.

A file constant cannot be the target of an assignment operation, and is external, by default. (For a discussion of assignment statements, see the chapter Statements.)

Each file constant is associated with a block of static storage called a file control block. The file control block retains information about the current status of the file while the file is open. In effect, the file constant is a pointer to, or a designator of, a file control block. File constants require the use of the -defext compiler option.

Each file control block's file identifier (ID) is the NAME of its associated file constant. The file ID in the previous example is F. This ID is used as the default TITLE of the file when it is being opened.

Parent topic: Files
Related information
Statements


File Variables

A file variable is a variable that can be assigned file values. A file variable can be given a value by receiving a file constant passed as an argument, by receiving a file constant as the value of a function, or by simple assignment. A file variable is declared with the VARIABLE attribute. For example:

DECLARE G FILE;
DECLARE F FILE;
DECLARE V FILE VARIABLE;

V=F;
...
V=G;

In this example, F and G are file constants, each of which has an associated file control block. V is a file variable that can be assigned file values. After the first assignment, both F and V designate the same file control block. Any operation performed on V is equivalent to the same operation performed on F. After the second assignment, any operation performed on V is equivalent to the same operation performed on G, because both V and G designate the same file control block.

A file name used as a parameter is a file variable and designates the same file control block as its corresponding argument.

Parent topic: Files


Using Environment Variables

To determine the system name of a file to match with a PL/I file, Open PL/I uses the name specified in the TITLE option of the OPEN statement. If the TITLE option is omitted, Open PL/I uses, by default, the name of the file constant or file variable in the PL/I program (shifted to uppercase). You can, instead, use system environment variables to easily specify the system names of files at run-time. The environment variable must be named in this fashion:

DD_name system-filename

where:

name is the TITLE-specified or default name indicated by the program.

Examples:

DECLARE DATA2 UPDATE FILE;   OPEN FILE(DATA2) /* no title */;
DECLARE FACTS STREAM FILE;   OPEN FILE(FACTS) TITLE('Report');

If you do not use environment variables to connect these openings with systems files, the following system names will be assumed for the files: DATA2 and Report.

Instead, prior to running the application, you could set environment variables as follows, causing the specified system files to be used. (Any directories used in the path names must exist.)

export DD_DATA2 /dir1/dir2/master.data
export DD_Report /doc/reports/deptA/week23.rep

In the second example, DD_Report was used rather than DD_FACTS, because of the TITLE option in that file's OPEN statement.

Parent topic: Files


ASA Control Character Support

American Standards Association (ASA) control characters were defined by ANSI. For PL/I, there are five distinct values for the first byte of each record transmitted by a PRINT file.

Character | Action
(space) | Space 1 line (blank character) before printing
0 | Space 2 lines before printing
? | Space 3 lines before printing
+ | No space before printing
1 | Start new page

Open PL/I only generates ASA control characters for programs run under Enterprise Server, for which the DD is:

  • Defined via JCL
  • Dynamically allocated via SVC99 or a TSO Allocate command
  • Specified in an SSTM configuration file (CICS and IMS/TM).

Open PL/I generates ASA control characters for STREAM files that have been designated as having a CTLASA attribute (internally). The CTLASA attribute is turned on by a variety of combinations:

  • File Declaration (or explicit OPEN) with the STREAM PRINT attributes
  • File Declaration with the ENV option CTLASA specified
  • File DD defined as having a RECFM of VBA or FBA
  • File DD defined as a SYSOUT dataset in the JCL.

File I/O

Open PL/I only supports ASA control character generation for STREAM IO against files with the PRINT/CTLASA attribute. When PRINT is specified, the first data byte of each record of a PRINT file is reserved for an American National Standard (ANS) printer control character. Open PL/I then inserts the control characters. Data values transmitted by list-directed and data-directed data transmission align on the left margin and on implementation-defined preset tab positions.

You can control the layout of a PRINT file by using these options and format items:

Statement | Statement Option | Edit Directed Format Item | Effect
OPEN | LINESIZE(n) | - | Established line width
OPEN | PAGESIZE(n) | - | Establishes page length
PUT | PAGE | PAGE | Skip to new page
PUT | LINE(n) | LINE(n) | Skip to the specified line
PUT | SKIP(n) | SKIP(n) | Skip specified number of lines
PUT | - | COLUMN(n) | Skip to specified character position
PUT | - | X(n) | Places black characters in line to establish position

LINESIZE and PAGESIZE establish print area dimensions, excluding footers.

The LINESIZE option specifies the maximum number of characters included in each printed line. If not specified, 120 characters is used for a PRINT file. There is no default for a non-PRINT file.

The PAGESIZE option specifies the maximum number of lines on each printed page. If not specified, 60 lines is used.

This shows an example of controlling the layout of a file.

open file(ASAFILE) output stream print PAGESIZE(55) LINESIZE(110);
on endpage(ASAFILE)
  begin;
    put file(ASAFILE) skip list (Footer);
    put file(ASAFILE) page list (’Pg: ’|| Pageno(ASAFILE));
    put file(ASAFILE) skip (3);
  end;

The OPEN statement opens the file Report as a PRINT file. The specification PAGESIZE(55) indicates that each page contains a maximum of 55 lines. An attempt to write on a page after 55 lines have already been written (or skipped) raises the ENDPAGE condition. The implicit action for the ENDPAGE condition is to skip to a new page, but you can establish your own action using the ON statement, as shown in the example.

Using the example, LINESIZE(110) indicates that each line on the page can contain a maximum of 110 characters. An attempt to write a line greater than 110 characters places the excess characters on the next line. An attempt to write to line 56 (or to skip beyond line 55), raises an ENDPAGE condition, and the begin-block shown executes. The ENDPAGE condition can be raised only once per page. This means printing can be continued beyond the specified PAGESIZE after the ENDPAGE condition has been raised. This can be useful for writing a footer at the bottom of each page.

The first PUT statement specifies that a line is skipped, and the value of Footer, presumably a character string, is printed on line 57 (when ENDPAGE is raised, the current line is always PAGESIZE+1). The file ASAFILE is set to the next page, and the character constant 'Page' is concatenated with the page number and printed. The final PUT statement skips three lines, so that the next printing is on line 4. Control returns from the begin-block to the PUT statement that raised the ENDPAGE condition. However, any SKIP or LINE option specified in that statement has no further effect.

Parent topic: Files


Input and Output

Open PL/I provides two types of Input/Output processing: stream I/O and record I/O. Each type of I/O has its own statements, and each type operates on its own kind of files. Open PL/I can process more than 32,767 records per file and supports UNIX named pipes, which enables the reading and writing of massive data sets - greater than 2 GB - something not normally permitted in UNIX I/O.

A stream file is a sequence of characters organized into lines and pages. When reading or writing a file using stream I/O, the data is treated as if it formed a continuous stream of ASCII characters. Stream files are written by PUT statements and are read by GET statements.

A record file is a set of discrete records that are accessible either sequentially or by keys. When reading or writing a file using record I/O, only one record is processed upon the execution of the I/O statement. Record files are read and written by READ, WRITE, REWRITE, and DELETE statements.

The following sections provide detailed information on the two types of input and output processing available through Open PL/I: stream I/O and record I/O.

  • Stream I/O
  • Record I/O
Parent topic: Language Concepts


Stream I/O

Stream I/O treats data in the external file as a stream of ASCII, EBCDIC, or GRAPHIC characters. In a stream I/O operation, a list of program variables is associated with actual input or output fields of data.

Two forms of stream I/O statements exist:

  • List-directed stream I/O, as performed by the GET LIST and PUT LIST statements.
  • Edit-directed stream I/O, as performed by the GET EDIT and PUT EDIT statements.

In both list-directed and edit-directed stream I/O, the files are written by the PUT statement and are read by the GET statement. In edit-directed stream I/O, data is transmitted to or from a stream file under the control of a format-list. In list-directed stream I/O, data is transmitted to and from the stream file without a format-list. In edit-directed stream I/O, format-lists can be part of the GET or PUT statement or can be given by a FORMAT statement.

Execution of a GET or PUT statement transmits data from or to the current line of a stream file and may not consume or produce an entire line of the stream file. Several PUT statements can be used to build a given line, or a single PUT statement can be used to output several lines. Similarly, several GET statements can read values from a given line, or a single GET statement can be used to read one or more lines. Lines read from a disk file are not modified by Open PL/I in any way; however, lines read from all other devices have trailing blanks removed and have one blank appended to the end of each line that is read by a GET statement. This blank ensures that a field typed at the beginning of a line is not appended to a field typed at the end of the previous line.

Each stream file has an associated line size that is determined when the file is opened. Lines of an output file contain n characters, where n is the line size of the file. (For more information, see the discussion of the LINESIZE option in the section Stream File Attributes.) A shorter line can be created by using the SKIP option on a PUT statement, as shown in the following example of a list-directed stream I/O statement. The shorter lines are padded to the right with blanks to obtain a length of n characters. For example:

PUT FILE(F) SKIP LIST(A,B,C);
PUT FILE(F) SKIP;

In this example, the current line (consisting of data previously output) is output and one or more new lines containing the values of A, B, and C are created. The second PUT statement forces the last line containing A, B, and C to be output and starts a new line. The SKIP option is always executed before any new data is transmitted.

On input, each line can be of any length up to the value of the line size. Execution of a GET statement reads from the current line until a new line is reached, the new line is ignored, and execution continues reading values and lines until the list of variables has been read. A SKIP option can be used to force a new line to be read prior to reading any values, as shown in the following example.

GET FILE(F) LIST(A,B,C);
GET FILE(F) LIST(D);
GET FILE(F) SKIP LIST(X,Y);

In the previous example, A, B, and C are read from the current line or from as many lines as are necessary. D is read from the same line as C, unless C happened to be the last value on its line. The SKIP option skips to a new line and consequently ignores any values remaining on the line after the value received by D. X and Y are read from the line that is current after the SKIP option, as well as any additional, necessary lines.

The PAGE option can be used in a PUT statement to begin a new page prior to transmitting any values, as shown in the following example.

PUT FILE(F) PAGE LIST(A,B,C);

For a complete discussion of GET, PUT, and FORMAT statements, see the chapter Statements.

Note:

Standard PL/I, in a stream file, does not provide a way to read a variable-length input line from the current position to a newline indicator. Open PL/I provides two nonstandard methods to read all characters from current position to new line into a character varying variable: a READ statement and an edit-directed GET statement. To read a variable-length line with a GET statement, you must use an A-format without a field width.

  • List-Directed Stream I/O
  • Data-Directed Stream I/O
  • Edit-Directed Stream I/O
  • Terminal I/O on a Stream File
Parent topic: Input and Output


List-Directed Stream I/O

Values transmitted by list-directed stream I/O are separated by blanks or commas on input and by blanks on output. Each value is transmitted in a readable format determined by the value's data type.

In a GET LIST operation, Open PL/I automatically converts ASCII input data to the data types of the variables specified in the GET LIST statement. In a PUT LIST operation, Open PL/I converts a computational expression to its ASCII equivalent for output.

The following example of simple terminal output demonstrates list-directed stream I/O:

PUT LIST(A,B);

In this example, if A is an integer declared fixed binary whose current value is -75, and B is a character-string declared character(5) whose current value is HAT Boxes, the example produces:

in the current output line of file F. The field boxes -75 is produced by converting the fixed binary(15) integer to a character-string. The many blanks allow for the maximum possible value, plus sign and decimal point and leading 0 for fractional values, as explained in the section Arithmetic to Character-String Conversion in the chapter Data Type Conversions. A single blank separates the value of A from the value of B. The last blank separates B from the next field.

For input, list-directed I/O considers each blank or comma as a field terminator. Excess commas are not allowed. Excess blanks within a field to be assigned to an arithmetic variable are ignored. Such fields must simply contain a valid constant, as could be written in the text of a program.

A field to be assigned to a character-string variable may contain a character-string constant, as written in the text of a program, or it may contain a sequence of any characters. In the latter case, the sequence begins with the first non-blank character in the field and ends with the character immediately preceding the next comma or blank, as shown in the following example of a GET LIST operation. Note that character sequences containing blanks or commas that are to be treated as a unit must be enclosed in single quotation marks ("). For example:

GET FILE(F) LIST(A,B);

In this example, if A is fixed binary(15) and B is character(5), the following lines have the indicated effect on the values of A and B.

Line | A | B
boxes | 5 | boxes
boxes | -4 5 | boxes
boxes | -4 5 | abc-4
Parent topic: Stream I/O
Related information
Arithmetic to Character-String Conversion


Data-Directed Stream I/O

Data-directed stream I/O is similar to list-directed stream I/O. The difference is that with data-directed stream I/O, the actual Open PL/I program names of the data values are included in the stream file along with the values. For example, if your program contains the structure:

DECLARE 1 STRUC,
            2 NUM(2) FIXED BIN(15) INIT(255,-432),
            2 TEXT CHAR(4) INIT('abcd');

and outputs this data with a PUT DATA statement, the characters emitted for STRUC would be:

STRUC.NUM(1)     255  STRUC.NUM(2)=   -432 STRUC.TEXT='abcd' ;

Each data value is preceded by the fully-qualified and specifically subscripted PL/I program name of that data value, as shown. The values themselves are formatted as they would be by a PUT LIST statement, except that character values are always enclosed in quotes.

Parent topic: Stream I/O


Edit-Directed Stream I/O

Values transmitted by edit-directed stream I/O are transmitted into fixed-length fields whose length and content are controlled by data-formats. Data-formats specifically control the type of conversion to be performed and the number of characters or digits in an input or output field. Each data-format corresponds to an element of the GET or PUT statement's value list and causes that value to be converted and transmitted. For example:

PUT FILE(F) EDIT(A,B) (F(7,2),A(6));

In this example, if A is declared fixed binary(15) and has a current value of -45, and B is declared character(4) and has a current value of HAT box, the following is written into the current line of file F.

Control formats can be used to force new lines and skip parts of lines, as shown in the next example. If there are more format items than values to be transmitted in the statement's I/O list, the extra format items are ignored. For example:

PUT FILE(F) EDIT(A,B) (X(3),F(7,2),SKIP,X(4),A(6),SKIP);

Using the same values of A and B as in the previous example, the above statement produces the following:

In this example, the first line is placed at the end of the current line, and the second line starts a new output line. The PUT statement does not start another new line, because B was the last item output; hence, the PUT statement terminated before the second SKIP was executed.

Edit-directed input requires that each input line be described precisely by the controlling format. If the current input line contains fewer characters than are required to satisfy the format, additional lines are read until the format is satisfied, as shown in the following example.

GET FILE(F) EDIT (X) (A(80));

In this example, if X is declared as character(100) and the current line contains only 60 characters, the 60 characters are read, a new line is read, processing advances to the next line, and 20 additional characters are read from that line. The 80 characters thus read are then assigned to X, and 20 blanks are used to pad the value of X on the right.

Parent topic: Stream I/O


Terminal I/O on a Stream File

If a terminal device is opened as a stream file, the file is unlike any other stream file in the following respects:

  • Each PUT statement transmits data to the device without waiting for the line to be filled.
  • A GET statement resets the current column position used by subsequent PUT statements.
  • Stream File Attributes
  • Print Files
Parent topic: Stream I/O


Stream File Attributes

The following attributes are appropriate for use with stream files. Some may be used in either the DECLARE statement for the file constant or in the OPEN statement, others only in the OPEN statement.

Attribute | Permitted in Specification
STREAM | DECLARE or OPEN
INPUT | DECLARE or OPEN
OUTPUT | DECLARE or OPEN
PRINT | DECLARE or OPEN
LINESIZE | OPEN
PAGESIZE | OPEN
TITLE | OPEN

The use of PRINT implies STREAM OUTPUT. If neither INPUT, OUTPUT, nor PRINT is specified, INPUT is assumed. LINESIZE and PAGESIZE can be used only for PRINT files. If neither STREAM nor RECORD is specified, the default is STREAM. (See the section Record I/O.) STREAM and RECORD are mutually exclusive, as are INPUT and OUTPUT. If attributes are specified both in the DECLARE statement and the OPEN statement for a file, the attributes used are the combination of those in the two statements. The combination may include only one of each mutually exclusive set.

The TITLE option is used to associate a file as declared in the PL/I program with a file or device as known to the operating system. In the following examples of OPEN statements, the quoted text in the TITLE options specifies the system filename or device name to be used in I/O operations with the opening of the PL/I file indicated by the FILE option. If the TITLE option is not specified in an OPEN statement, the declared name of the file constant is used as the default title.

The LINESIZE option is used in an OPEN statement to specify the maximum number of characters that can be output in a single line for a STREAM file. If no line size is specified, a default line size is assumed. For more information on LINESIZE, see the section PUT in the chapter Statements.

The LINESIZE option can appear in the OPEN statement only and is valid only with STREAM OUTPUT files. During output, a newline will be inserted whenever the column position equals (LINESIZE+1). The SKIP or LINE options with a PUT statement cause a newline character to be inserted and the column position to be reset. The COLUMN format with a PUT EDIT statement may cause a newline to be inserted.

The default may vary according to the file name or device. In Open PL/I, the default value of the LINESIZE option is 120.

The PAGESIZE option is used in an OPEN statement to specify the maximum number of lines that can be written to a print file without signaling the ENDPAGE condition. If no page size is specified, a default page size is supplied. In Open PL/I, the default value of the PAGESIZE option is 60.

If a GET or PUT statement is executed on a file that has not been opened, the file is implicitly opened as a STREAM file using the declared name of the file constant as the title. A file so opened by a GET statement is opened as an INPUT file, one so opened by a PUT statement is opened as an OUTPUT file.

You can add text to any existing stream file (any ASCII file) by using the -APPEND option in the TITLE option of the OPEN statement. Thus, if the file you wish to append to is named "logfile," open it with the following TITLE option:

TITLE('logfile -APPEND')

Any subsequent PUT statements to this file simply append their output to the end of the file.

  • Examples:
Parent topic: Terminal I/O on a Stream File
Related information
Record I/O
PUT
TITLE Options


Examples:

OPEN FILE(F) OUTPUT TITLE('thedata');

OPEN FILE(TTY) TITLE('CONSOLE')
   STREAM INPUT;

OPEN FILE(PTR) TITLE('LPT1')
   STREAM OUTPUT PRINT LINESIZE(132)
   PAGESIZE(60);

OPEN FILE(MSG_FILE) INPUT;
                  /* The default title is 'MSG_FILE' */
Parent topic: Stream File Attributes


Print Files

An output stream file opened with the PRINT attribute indicates that the file is a print file. When a file is declared as a print file, the LINESIZE and PAGESIZE options may be specified at file opening to designate the maximum width of an output line and the maximum number of lines per page. The current line number and current page number of the print file can also be accessed using the PAGENO and LINENO built-in functions.

The LINENO built-in function allows you to access the current line number of an output stream file opened with the PRINT attribute. Each time a line is written to the output stream, the line number is incremented by one. Each new line is initially positioned so that the next item is written to column 1 of the line.

The PAGENO built-in function lets you read the current page number of an output stream file opened with the PRINT attribute. The current page number can be set using the PAGENO pseudo-variable. The ENDPAGE condition is signaled when the line to be written has a line number that is the page size plus one, or when a SKIP option positions the file to (or past) page size + 1.

Each time a new page is written, the line number is reset to one and the page number is incremented by one.

If an ON-unit for the ENDPAGE condition does not write a new page, the line number is allowed to increase indefinitely until a new page is written. The ENDPAGE condition is signaled only when the line to be written has a line number that is one greater than the page size.

A new page is written only by a PAGE option of a PUT statement, by a PAGE format-item, and by the default ON-unit for the ENDPAGE condition.

In Open PL/I, tab stops are set every eight columns for a stream file that has the PRINT attribute.

Parent topic: Terminal I/O on a Stream File


Record I/O

In Record I/O, file data is treated in terms of records. Record files are used with the READ, WRITE, REWRITE, and DELETE statements. Execution of one of these statements transmits one record to or from the file and updates the current position of the file.

A record is a contiguous set of bytes of data in the file. The records of the file may all be of the same fixed length, as specified when the file is created, or they may be of varying lengths. Certain files with variable-length records require that a maximum length be specified when the file is created.

The data bytes that comprise a record file may be ASCII characters, but they may also be any kind of binary data, including being paired as halfwords, grouped as binary fullwords or double words, grouped as packed-decimal strings, or considered as bit fields of any length.

Record files may be keyed or not. If a record file does not have keys, its records can be accessed only in sequential order as they exist in the file, one after the other from the beginning of the file to the end. Open PL/I supports two keyed access methods: indexed (VSAM) I/O, which is based on character-string keys, and relative record I/O, which is based on integer record numbers.

  • Record File Attributes
  • Consecutive Record I/O
  • Indexed Record I/O
  • Relative Record I/O
  • REGIONAL(1) Record I/O
  • TITLE Options
Parent topic: Input and Output


Record File Attributes

The following attributes are appropriate for use with record files. Some may be used in either the DECLARE statement for the file constant or in the OPEN statement, others only in the OPEN statement. Some attributes, if present, imply the presence of certain others.

Attribute | Permitted in Specification | Implied
RECORD | DECLARE or OPEN |
INPUT | DECLARE or OPEN |
OUTPUT | DECLARE or OPEN |
UPDATE | DECLARE or OPEN | RECORD
SEQUENTIAL | DECLARE or OPEN | RECORD
KEYED | DECLARE or OPEN | RECORD
DIRECT | DECLARE or OPEN | RECORD KEYED
ENVIRONMENT | DECLARE |
TITLE | OPEN |

If neither INPUT, OUTPUT, nor UPDATE is specified, INPUT is assumed. If neither SEQUENTIAL nor DIRECT is specified, SEQUENTIAL is assumed. If neither STREAM nor RECORD is specified, the default is STREAM. (See the section Stream I/O.) The following sets of attributes are mutually exclusive:

  • STREAM and RECORD
  • INPUT, OUTPUT, and UPDATE
  • SEQUENTIAL and DIRECT

If attributes are specified both in the DECLARE statement and the OPEN statement for a file, the attributes used are the combination of those in the two statements. The combination may include only one of each mutually exclusive set.

The TITLE option is used to associate a file as declared in the PL/I program with a file as known to the operating system. In the following examples of OPEN statements, the quoted text in the TITLE options specifies the system filename to be used in I/O operations with this opening of the PL/I file indicated by the FILE option. If the TITLE option is not specified in an OPEN statement, the declared name of the file constant is used as the default title.

Examples:

OPEN FILE(F) RECORD OUTPUT TITLE('thedata');

OPEN FILE(F) RECORD INPUT; /* The default title is 'F' */

If a READ, WRITE, REWRITE, or DELETE statement is executed on a file that has not been opened, the file is implicitly opened as a RECORD file using the declared name of the file constant as the title. The attributes assigned to the file implicitly opened depend on the I/O statement used, as indicated below:

Record I/O Statement | Assigned Attributes
READ | RECORD INPUT
WRITE | RECORD OUTPUT
REWRITE | RECORD UPDATE
DELETE | RECORD UPDATE

Record input and output operations are restricted to files opened with certain attributes. These restrictions are shown in the following table:

File Attributes | Permitted I/O Operations
INPUT | READ
OUTPUT | WRITE
UPDATE | READ, WRITE, REWRITE, DELETE

If a file opened for INPUT or UPDATE does not exist, an error is signaled.

If a file opened for OUTPUT does not exist, a file is created. If the file has been opened as DIRECT or KEYED SEQUENTIAL, a keyed file is created; otherwise, a non-keyed file is created.

If a file opened for OUTPUT already exists, it is deleted and a new file is created.

However, if the -APPEND option is specified in opening the file, an existing file can be opened for OUTPUT. You can add records to an existing record file by using the -APPEND option in the TITLE option of the OPEN statement. Thus, if the file you wish to append to is named "logfile," open it with the following TITLE option:

TITLE ('logfile -APPEND')

Any subsequent WRITE statements to this file simply append their output to the end of the file.

A REWRITE statement replaces an existing record in an UPDATE file with a new record. A DELETE statement basically removes an existing record from an UPDATE file. A WRITE to an existing record and a READ from a nonexistent record are not allowed. A WRITE to a record past EOF will append the record to the end of the file. A DELETE or REWRITE of a nonexistent record signals a KEY condition. (For further information, see the description of KEY in the section ON in the chapter Statements.)

Record I/O statements copy the storage of a variable to or from a record in a file (except in the case of READ operations using locate mode I/O, see below).

No conversion is performed and no check is made to ensure that the data being read is of the proper type to store into the variable. The variables used in INTO or FROM options cannot be unaligned bit strings or structures consisting entirely of unaligned bit strings, because such variables normally share a portion of their storage with other members of the same array or structure. Also, an expression cannot be used in a FROM or INTO option.

Note:

Structures with the UNION attribute cannot be used as variables in READ, WRITE, PUT, and GET statements.

READ operations can be performed in two "modes": move mode and locate mode. A READ statement that specifies the INTO option causes the input data to be stored directly into the variable referenced by the INTO option. This is called a "move mode" READ. A READ statement that specifies the SET option instead of the INTO option causes the input data to be stored in an unnamed storage buffer and causes the address of this buffer to be assigned to the pointer variable referenced by the SET option. This is called a "locate mode" READ.

A complete discussion of record I/O statements is found in the chapter Statements.

Examples:

READ FILE(CUSTOMERS) KEY(CUST_ID) INTO(CUST_RECORD);
PUT SKIP LIST(CUST_RECORD.NAME);
READ FILE(CUSTOMERS) KEY(CUST_ID) SET(CPTR);
PUT SKIP LIST(CPTR->BASED_RECORD.NAME);
Parent topic: Record I/O
Related information
Stream I/O
TITLE Options
ON
Statements


Consecutive Record I/O

A record file without keys is called a consecutive file. The records of such a file can be read only in the same sequential order in which they were written. Thus, a consecutive file can be read only one record after the other, starting with the first record in the file. A record of a consecutive file can be rewritten, but only immediately after it has been read.

A consecutive file is declared by including the CONSECUTIVE option of the ENVIRONMENT attribute. For example,

DECLARE ULOG RECORD OUTPUT FILE
        ENVIRONMENT(CONSECUTIVE RECSIZE(130));

In this example the RECSIZE option causes all records to be of length 130 bytes. If RECSIZE is omitted, variable length records may be written. In the latter case, there is no information automatically recorded in the file to indicate the length of the records. A program reading the file must have the ability to know how many bytes to read with each READ statement.

Example:

CONFILE: PROCEDURE OPTIONS(MAIN);

   DECLARE TEST RECORD OUTPUT FILE ENV(CONSECUTIVE);
   DECLARE REC1 CHAR(5) INIT('AAAAA');
   DECLARE REC2 CHAR(10) INIT('BEEBBBBBBB');

   OPEN FILE(TEST) TITLE('testdata');
   WRITE FILE(TEST) FROM(REC1);
   WRITE FILE(TEST) FROM(REC2);
   WRITE FILE(TEST) FROM(REC1);
   CLOSE FILE(TEST);

END CONFILE;

The file testdata resulting from this program will contain the following 20 bytes:

AAAAABBBBBBBBBBAAAAA
Note:

Open PL/I has an older method of accomplishing the same thing. It is done by using the TITLE option of the OPEN statement rather than the ENVIRONMENT attribute of the DECLARE statement. The following illustrates the old method.

DECLARE RECORD TEST OUTPUT FILE;
OPEN FILE (TEST) TITLE ('testfile -SAM');
Parent topic: Record I/O
Related information
TITLE Options


Indexed Record I/O

Open PL/I's indexed I/O, also called VSAM (Virtual Storage Access Method), involves the use of character-string keys that are stored in the records of the file. Every record has a key, and the keys are ordered lexicographically in an index that is associated with the file. The records can be accessed randomly by specifying the key of the desired record, or they can be accessed sequentially according to the order of the keys, or they can be accessed by a combination of these methods, as illustrated in the following table:.

File Attributes | Permitted Access
SEQUENTIAL | SEQUENTIAL only
DIRECT | KEYED only
KEYED SEQUENTIAL | SEQUENTIAL and/or KEYED in combination

An INDEXED (equivalently, VSAM) file is declared by including either the INDEXED or the VSAM option of the ENVIRONMENT attribute. For example,

DECLARE MASTER RECORD OUTPUT FILE
   ENVIRONMENT(VSAM KEYLOC(1)
   KEYLENGTH(12) RECSIZE(130));

The KEYLOC option specifies the byte position of the first byte of the key in the records, counting the first byte as KEYLOC(1). The KEYLENGTH option specifies the number of characters in the key. RECSIZE specifies the record length or, in the case of a file of variable-length records, it specifies the maximum record length.

Actually, it is necessary to specify RECSIZE, KEYLOC, and KEYLENGTH for a file only when it is created. Programs that read or update an existing indexed file do not need to include these options, although they may. Open PL/I can determine these characteristics from an existing file. If you are using full IBM mode, file header information is used when opening a VSAM file for output, rather than requiring you to specify RECSIZE, KEYLOC, or KEYLENGTH with the ENVIRONMENT attribute.

There are a number of options that can be specified with the ENVIRONMENT attribute. These options are described in the table below. This table also lists a number of options that are not needed or not supported in Open PL/I, but which a user may expect to find based on experience with other compilers.

Option
 | Description
ASCII | The ASCII option is assumed in Open PL/I.
BKWD | Specifies backward processing for indexed files read in the SEQUENTIAL mode; that is, sequential processing will start with the current record (or last, by default) in the file and proceed to previous records.
BUFFERS | The BUFFERS option is not needed in Open PL/I. If it is used, the Compiler ignores it.
BUFOFF | The BUFOFF option is not needed in Open PL/I. If it is used, the Compiler ignores it.
BUFND | The BUFND option is not needed in Open PL/I. If it is used, the Compiler ignores it.
BUFNI | The BUFNI option is not needed in Open PL/I. If it is used, the Compiler ignores it.
BUFSP | The BUFSP option is not needed in Open PL/I. If it is used, the Compiler ignores it.
CONSECUTIVE | Specifies a file with consecutive organization. For related information, see the description of the -defext compiler option in your Open PL/I User's Guide.
CTLASA | The CTLASA option is ignored.
CTL360 | The CTL360 option is not implemented in Open PL/I. If it is used, the Compiler issues a warning.
EBCDIC | Specifies that EBCDIC data is present.
F | FB | FS | FBS | Specifies record format, where F = fixed length, B = blocked, and S = standard. Open PL/I treats any such specification as though it were F alone — fixed length.
GENKEY | Specifies a generic key, a character string that is a prefix of a key. A READ with a KEY clause returns the first record whose key is greater than or equal to the string specified by the KEY clause. A subsequent sequential READ (no KEY clause) will return the next record greater than the current record.
GRAPHIC | Specifies that GRAPHIC data is present.
INDEXAREA(n) | The INDEXAREA option is not needed in Open PL/I. If it is used, the Compiler ignores it.
INDEXED | Specifies a file with indexed organization. For related information, see the description of the -defext compiler option in your Open PL/I User's Guide.
KEYLENGTH(n) | Specifies the length, n, of the embedded key for indexed files. KEYLENGTH can be specified only when INDEXED or VSAM is specified.
KEYLOC(n) | Specifies the starting location of an embedded key in a record. n must be within the limits: 1 ? n ? recordsize – keylength + 1. The default KEYLOC value is 1. KEYLOC can be specified only when INDEXED or VSAM is specified. Note: Be sure that KEYLOC considers the 2-byte prefix generated by specification of the SCALARVARYING option.
LEAVE | The LEAVE option is not needed in Open PL/I. If it is used, the Compiler ignores it.
MINRECSIZE(n) | Specifies the minimum record length, n. n must be an integer. This option allows for better disk space utilization. The MINRECSIZE option is required with V (variable-length) record formats. It is ignored for F (fixed-length) record formats. The values specified for the KEYLOC and KEYLENGTH options must be within the value specified by the MINRECSIZE option. For more information on the MINRECSIZE option, see below.
NCP(n) | The NCP option is not applicable in Open PL/I. Open PL/I treats INDEXED files the same as VSAM files.
NOWRITE | The NOWRITE option is not needed in Open PL/I. If it is used, the Compiler ignores it.
PASSWORD(pwd) | The PASSWORD option is not implemented in Open PL/I. If it is used, the Compiler issues a warning.
RECSIZE(n) | Specifies the maximum record length, n. n must be a positive integer, or a static variable with an initializer. For the static variable case, the initial value will be used as the maximum fixed record size. Note that “dynamic” RECSIZE usage is not supported - if this is not needed, VALUE is preferable to STATIC INIT.
REGIONAL(1 | 2 | 3) | The REGIONAL(1) option specifies files whose records are identified by their region numbers. The REGIONAL(2) and REGIONAL(3) options are not implemented in Open PL/I. If they are used, the Compiler flags it as an error.
REUSE | The REUSE option specifies that an OUTPUT file associated with a VSAM data set is to be used as a work file. .
SCALARVARYING | Used for the input and output of varying length records. SCALARVARYING enables the recognition of a two-byte prefix that specifies the current length of the records. Note: Be sure that KEYLOC considers the 2-byte prefix generated by specification of the SCALARVARYING option.
SIS | The SIS option is not needed in Open PL/I. If it is used, the Compiler ignores it.
SKIP | The SKIP option is not needed in Open PL/I. If it is used, the Compiler ignores it.
TP(MIR) | The TP(MIR) option is not implemented in Open PL/I. If it is used, the Compiler flags it as an error.
TRKOFL | The TRKOFL option is not needed in Open PL/I. If it is used, the Compiler ignores it.
U | D | DB | Specifies record format. Open PL/I treats any such specification as though it were F – fixed length.
V | VB | VS | VBS | Specifies record format, where V = variable length, B = blocked, and S = spanned. Open PL/I treats any such specification as though it were V.
VSAM | Specifies files organized for the virtual storage access method (VSAM). For related information, see the description of the -defext compiler option in your Open PL/I User's Guide.

A random access read of a record in an indexed (VSAM) file opened with the INPUT or UPDATE attribute is accomplished by a READ statement that includes the KEY option. For example,

READ FILE(PARTS) INTO(PART_REC) KEY(PART_NUM);

A sequential read reads the next record of the file after the last one read — using the key ordering — or the first record of the file, if no record has previously been read. For a sequential READ statement, the KEY option is omitted.

If a record has previously been read from a file opened with the UPDATE attribute, and no other intervening I/O operation has been performed, a REWRITE without key may be executed. In this case, the previously read record is overwritten with the new value. For example,

READ FILE(PARTS) INTO(PART_REC) KEY(PART_NUM);
PART_REC = NEW VALUE;
REWRITE FILE(PARTS) FROM(PART_REC);

However, a record of an indexed file can be randomly updated by specifying the KEYFROM option in the REWRITE statement. For example,

REWRITE FILE(PARTS) FROM(PART_REC) KEYFROM('12XJ04');

If an indexed file has been opened with the OUTPUT or UPDATE attribute, a WRITE statement using the KEYFROM option can be used to add new records to the file. The WRITE statement without KEYFROM is used to sequentially add new records to a file.

The DELETE statement can be used to remove records from an indexed file opened with the UPDATE attribute. The KEY option must be used to delete a record.

All keys used in an indexed (VSAM) file must by of type CHARACTER. If a KEY or KEYFROM option references a value that is not of type CHARACTER, the value is converted to CHARACTER before the I/O operation begins. Note that keys of type PICTURE are converted to CHARACTER without any actual change in the key contents. (See the chapter Data Type Conversions.)

An indexed (VSAM) file can have either fixed-length or variable-length records. The records are fixed-length if the F option is used with the ENVIRONMENT attribute when the file is created; they are variable-length if the V option is used. (See the table above.) If neither F nor V is specified, F is assumed.

In a fixed-length record file, all records must have the same length, which is the length specified by the RECSIZE option of the ENVIRONMENT attribute when the file was created. For a variable-length record file, RECSIZE specifies the maximum record length that is permitted in the file. The MINRECSIZE option must also be specified for a variable-length record file. This value specifies the minimum length that all records in the file must have. The keys of the file must be contained within this minimum portion of the file.

The SCALARVARYING option specifies that there is a two-byte prefix on all records in the data file. A user must take this into account when specifying the KEYLOC value. The KEYLOC value is the absolute byte position of the record starting at 1. This option can be used on either F or V record formats. It allows for more general use of character varying records in I/O statements, although character records can also be transmitted. When a character varying item is used in a WRITE or REWRITE statement, the two-byte prefix is retained with the record as it gets written out to the data file, if the SCALARVARYING option is set. Without the SCALARVARYING option, the prefix is not written; in this case, the remainder of the record is undefined beyond its current length. When a character record is written, a prefix will be added if SCALARVARYING option is set. The SCALARVARYING option lets you write and read records smaller then your max record size, without getting the RECORD condition. It also is useful when doing locate mode I/O.

When setting KEYLOC, it is very important to "compensate" for the two-byte prefix when the SCALARVARYING option is used.

The use of V type records provide a way to transmit partial records. Open PL/I does not require control bytes in the record for this support. The run-time system will automatically retain information concerning the number of bytes transmitted. Since no control information is needed in the record, the user should not change KEYLOC based on the record type. Only the SCALARVARYING option has impact on the KEYLOC location.

Although the PL/I language does not provide a mechanism by which multiple keys can be specified for a file, Open PL/I does provide a means for accessing data via multiple keys. After an indexed file has been created using one key (which is called the primary key), you can use the utility Ipivsam to add additional indexes (that is, keys) to the file. In the PL/I program each different key version of the data must be declared as a separate file. However, all of these declared files can actually be referencing the same set of data. For example,

DECLARE EMPFILE1 RECORD UPDATE FILE
   ENV(VSAM KEYLOC(1) KEYLENGTH(6) RECSIZE(145));
DECLARE EMPFILE2 RECORD UPDATE FILE
   ENV(VSAM KEYLOC(31) KEYLENGTH(3) RECSIZE(145) GENKEY);
DECLARE 1 EMP_
   2 EMP_ID       (CHAR(6),
   2 NAME         (CHAR(24),
   2 DEPARTMT     (CHAR(3),
   ...

OPEN FILE(CUSTFILE1) TITLE('employee');
OPEN FILE(CUSTFILE2) TITLE('employee');
                        /* same file, different key */

The following example program illustrates the use of the ENVIRONMENT variable and its options for I/O on a file with VSAM organization.

/* Example of VSAM I/O */

TEST: PROCEDURE OPTIONS(MAIN);

   %REPLACE TRUE BY '1'B; %REPLACE FALSE BY '0'B;

   DECLARE DB FILE ENV(VSAM KEYLOC(21) KEYLENGTH(120) RECSIZE(244));
   DECLARE DBG FILE ENV(INDEXED GENKEY KEYLOC(21)
      KEYLENGTH(120) RECSIZE(244));

   DECLARE 1 DB_RECORD,
      2 HEADER     CHAR(20),
      2 DBKEY      CHAR(120),
      2 STUFF      CHAR(100),
      2 NUMBER     FIXED BIN(31);

   DECLARE I FIXED BIN(31);
   DECLARE CS CHAR(26) STATIC
                     INIT('THEQUICKBROWNFXJMPSVLAZYDG');
   DECLARE C(26) CHAR DEFINED(CS);
   DECLARE LETTERS CHAR(30);

   /* CREATE DB */
   OPEN FILE(DB) RECORD KEYED SEQUENTIAL OUTPUT
               TITLE('MYFILE1');
   HEADER = 'DATA RECORD HEADER';
   STUFF = COPY('ABCDE',20);
   DO I = 1 TO 26;
      NUMBER = I;
      DBKEY = '@'||C(I) ||COPY('@',118);
      WRITE FILE(DB) FROM(DB_RECORD) KEYFROM(DBKEY);
      END;
   CLOSE FILE(DB);

   /* TRY A GENERIC READ THEN MOVE SEQUENTIALLY THRU THE FILE */
   OPEN FILE(DBG) RECORD KEYED SEQUENTIAL INPUT
               TITLE('MYFILE1');
   ON ENDFILE(DBG) GOTO EXIT_1;
   READ FILE(DBG) KEY('@') INTO(DB_RECORD);
   LETTERS = SUBSTR(DBKEY,2,1);
   DO WHILE(TRUE);
      READ FILE(DBG) INTO(DB_RECORD);
      LETTERS = TRIM(LETTERS) ||SUBSTR(DBKEY,2,1);
      END;
EXIT_1:
   CLOSE FILE(DBG);
   PUT EDIT(LETTERS)(A);
   IF LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' THEN
      PUT SKIP LIST('TEST PASSES');
   ELSE PUT SKIP LIST('TEST FAILS');

   PUT SKIP;
END TEST;
Parent topic: Record I/O
Related information
Open PLI Users Guide
Data Type Conversions


Relative Record I/O

Open PL/I also provides an I/O method for accessing consecutive files by a numeric key representing the relative record numbers of the records in the file. This is called relative record I/O. It can be used only with files of fixed-length records, and it cannot be used with indexed (VSAM) files.

Relative record I/O files are regarded as keyed files, but the keys are not stored in the file. They are just the ordinal numbers of the records in the file. The keys must be positive integers. Any value used in a KEY or KEYFROM option of an I/O statement must be an integer or be capable of conversion to an integer.

The ENVIRONMENT attribute is not used in the declaration of a relative record I/O file. Instead, such a file is specified by using an extension of the TITLE option of the OPEN statement. The format of this TITLE option is as follows:

TITLE('filename -DAM n')

where n is the length of the records in the file. The length n includes two bytes that are normally added to the beginning of each record. This halfword is used to record special information about the file.(See the section TITLE Options.)

In general, the same set of PL/I I/O operations can be used with relative record I/O files as with indexed files.

A relative record I/O file can be created using an additional extension in the TITLE option, as follows:

TITLE('filename -DAM n -NOSIZE')

The -NOSIZE option indicates that the two-byte special field is not to be added to the data records. If -NOSIZE is specified for a file, the DELETE statement cannot be used with the file.

Parent topic: Record I/O
Related information
TITLE Options


REGIONAL(1) Record I/O

A REGIONAL(1) file does not have keys recorded in the records. Instead, each record is identified by its region number, which is an unsigned integer. The keys for a REGIONAL(1) file may be character strings consisting only of decimal digits, possibly preceded by leading spaces (which are interpreted as zeros), or the keys can be of integer type.

A REGIONAL(1) file contains data records and dummy records. A dummy record is identified by having a first byte with the hex value FF. Dummy records represent records that have been deleted or whose region numbers have been skipped over when the file was first created. You can also create them explicitly by writing a record whose first byte has the value hex FF. Dummy records are not ignored when the REGIONAL(1) file is read. An Open PL/I program reading a REGIONAL(1) file must be designed to deal with dummy records. You can replace dummy records with valid data records

You can create a REGIONAL(1) file only by use of DIRECT OUTPUT mode using keyed WRITE statements. The records must be written in ascending region number order, but you may skip over region numbers. When a region number is skipped, a dummy record is written in its place. The KEY condition is raised if you attempt to write records other than in increasing sequence or if you attempt to write a record with a duplicate key.

An existing REGIONAL(1) file can be accessed in SEQUENTIAL INPUT or UPDATE mode, or in DIRECT INPUT or UPDATE mode. (Opening the file in OUTPUT mode causes the existing file to be overwritten.)

If a REGIONAL(1) file is opened for SEQUENTIAL access (INPUT or UP_ DATE), the records are retrieved in ascending order of their region numbers. Dummy records are retrieved as well as valid data records. With SEQUENTIAL INPUT, you can read all records of the file in ascending region number order; with SEQUENTIAL UPDATE, you can so read all records and update those you choose (including changing dummy records to valid data records, and valid data records to dummy records). The rules for sequential READ and REWRITE for REGIONAL(1) are the same as for CONSECUTIVE files.

A REGIONAL(1) file can be opened for INPUT or UPDATE in DIRECT access mode, in which case keyed READ, WRITE, REWRITE, and DELETE statements can be used. READ accesses dummy records as well as valid data records. WRITE and REWRITE are equivalent; either replaces an existing record (data or dummy record) with a replacement record (again, either a data or a dummy record). DELETE converts the record with the specified region number into a dummy record.

  • Example of REGIONAL(1) I/O
Parent topic: Record I/O


Example of REGIONAL(1) I/O

/* This program creates and updates a REGIONAL(1) file */

sample: procedure options(main);
   declare File1 file environment(regional(1) recsize(20));/*requires -defext
   declare Buffer char(20);
   declare FirstByte char(1) defined(Buffer);
   declare Key char(4) varying;
   declare Eof bit;

   put skip list('Creating REGIONAL(1) file with records 1, 5 and 9.');
   open file(File1) output;
   Buffer = copy('1',size(Buffer));
   write file (File1) from(Buffer) keyfrom (1);
   Buffer = copy('5',size(Buffer));
   write file (File1) from(Buffer) keyfrom (5);
   Buffer = copy('9',size(Buffer));
   write file (File1) from(Buffer) keyfrom (9);
   close file(File1);

   open file(File1) update;
   on endfile(File1) Eof = '1'b1;
   Eof '0'b1;       /* Initialize */
   put skip list('Reading file and updating the even numbered records.');
   read file(File1) into(Buffer) keyto(Key);
   do while (^Eof);
     if unspec(FirstByte) = 'FF'b4 then do;  /* dummy record */
       if (mod(fixed(Key,15),2) = 0) then do;  /* change even number ones *
       Buffer = 'rewritten';
       rewrite file(File1) from (Buffer);  /* rewrite current record */
       end;
     end;
    read file(File1) into (Buffer) keyto(Key);
    end;
   Eof = '0'b1; /* Reset */
   put skip(2) list ('Reading and displaying all records in file.');
   Key = '1';
   read file(File1) into(Buffer) key(Key);     /* direct read */
   do while (^Eof);
      if unspec(FirstByte) = 'FF'b4 then put skip list(Key,'<dummy record>');
      else put skip list(Key,Buffer);
      read file(File1) into(Buffer) keyto(Key);  /* sequential read */
      end;
   close file(File1);
   put skip;
end sample;

You can compile, link, execute, and display the output of the above sample program with the following commands:

mfplx sample.pl1 -defext -o sample.out
sample.out

The output is as follows:

Creating REGIONAL(1) file with records 1, 5 and 9.
Reading file and updating the even numbered records.

Reading and displaying all records in file.
1       11111111111111111111
2       rewritten
3       <dummy record>
4       rewritten
5       55555555555555555555
6       rewritten
7       <dummy record>
8       rewritten
9       99999999999999999999
Parent topic: REGIONAL(1) Record I/O


TITLE Options

Open PL/I supports a number of non-standard TITLE options that can be used to indicate the type of file being opened. These are as follows:

-SAM [n]

-DAM [n]

-NOSIZE

-APPEND [n]

-DELABORT [n]

where n is an integer indicating that the file has fixed-length records of length n bytes.

These options are included in the operand of the TITLE option immediately following the filename and separated from it by one or more spaces, as shown in the following examples:

TITLE('recfile.dat       -SAM 80')
TITLE('keyfile -DAM')

The -SAM and -APPEND options can be used with stream files, in which case the length, if specified, is ignored. -SAM is never required for stream files.

-SAM [n] specifies that the file is a consecutive file. If n is specified when the file is created, the file is created with records of fixed length n. The maximum value for n is 131,017 bytes. If n is not specified when the file is created, records written to the file can be of any length and of varying lengths. If -SAM is used when opening a file for OUTPUT, if the file already exists, it is deleted and a new file is created.

-DAM [n] specifies that the file is a relative record I/O file. If n is specified when the file is created, the file is created with records of fixed length n. If n is not specified when the file is created, the file is created as a variable-length record file. If -NOSIZE is not also specified, this length n includes the two bytes that are added as a halfword of length information at the beginning of each record.

-NOSIZE can be used alone or in combination with -DAM [n]. It specifies that the length halfword is not included at the beginning of each record. If -NOSIZE is used without -DAM [n], -DAM is implied.

-APPEND [n] has the same meaning as -SAM, except that when used in opening a file for OUTPUT, it causes an already existing file to be appended to rather than replaced.

-DELABORT causes the file to be deleted when it is closed.

If a file is opened for OUTPUT and none of these TITLE options is specified, and there is no ENVIRONMENT attribute in the file declaration, if the opening is for a DIRECT file, -DAM is assumed, and if the opening is not for a DIRECT file, -SAM is assumed.

Parent topic: Record I/O


Data Types

  • Introduction
  • Arithmetic Data
  • Picture Data
  • Character-String Data
  • Graphic String Data (DBCS Support)
  • Wide Character-String Data (UTF-16 Support)
  • Bit-String Data
  • Area Data
  • Locator Data
  • Label Data
  • Entry Data
  • File Data
  • Arrays
  • Structures
  • Arrays of Structures
  • Data Size and Alignment
Parent topic: Open PL/I Language Reference Manual
Related concepts
Configuring PL/I project's properties


Introduction

Each value has a data type that determines which operations can be performed on the value and the way in which the value is represented in storage.

Data types are declared for variables, function results, named constants (such as files), and external procedures. They are also used with the ENTRY attribute to describe the data type of each parameter of a procedure.

Data types are declared using the following attributes:

Computational Data | Non-Computational Data
FIXED BINARY | POINTER
FIXED DECIMAL | LABEL
FLOAT BINARY | ENTRY
FLOAT DECIMAL | FILE
PICTURE | OFFSET
CHARACTER | AREA
CHARACTER VARYING |
WIDECHAR | AREA
WIDECHAR VARYING |
BIT |

The attributes in the first column represent data items whose values can be manipulated by arithmetic or string operations and are therefore computational. The attributes in the second column refer to data used within a program for control structures and linkage and are therefore non-computational.

The data type of a value produced by an expression is determined by the operands and the built-in functions within the expression. The data type of a constant is determined by the syntax of the constant.

A variable capable of storing only one value, such as an integer or a character string, at any one time is called a scalar variable. An array variable is a collection of variables all of the same type. For example, an array might consist of 20 individual character strings. The variables contained in the array are called elements of the array. These elements all have the same name as the array. They are ordered by a numeric index, or perhaps several indices, and they are referenced by use of these indices. A structure variable is a collection of variables of arbitrarily mixed types. The variables contained in a structure are called members of the structure. The members each have their own name. A member may be referenced by its name alone, or its name may be qualified by the structure name to distinguish it from a member of another structure. A structure can contain subordinate structures as members, as well as array members and scalar members. Also, the elements of an array can be structures.

This chapter discusses each data type, beginning with computational data types.

Parent topic: Data Types
Related information
ENTRY
Types of Operators
Open PL/I Built-Ins


Arithmetic Data

Each arithmetic value is characterized by a base (binary or decimal), a scale (fixed-point or floating-point), and a precision (the number of digits in the value). These three properties collectively constitute the data type of the arithmetic value.

The data type of arithmetic values is expressed using the following attributes:

  • FIXED BINARY(p) and FIXED DECIMAL(p,q) for fixed-point data
  • FLOAT BINARY(p) and FLOAT DECIMAL(p) for floating-point data

where p is the precision and q is the number of fractional digits in the precision.

Each implementation of PL/I imposes limits on the maximum values of p and q, and these limits typically differ for each combination of base and scale. Refer to your Open PL/I User's Guide for information on the default precision and maximum precision for each arithmetic data type in Open PL/I.

  • Fixed-Point Binary Literals
  • Floating-Point Binary Literals
  • Fixed-Point Data
  • Floating-Point Data
Parent topic: Data Types


Fixed-Point Binary Literals

Fixed-point binary literals are treated the same way as fixed-point decimal literals. Examples of fixed-point binary literals are:

1000b, 1000.101B
Parent topic: Arithmetic Data


Floating-Point Binary Literals

The IBM compiler converts binary floating-point literals to short floating-point values if the precision is less than 21. However, Open PL/I ignores precision, and always converts the string to a floating-point decimal with the maximum permitted precision. Examples of floating-point binary literals are:

1000E201b, 1000.101E2B
Parent topic: Arithmetic Data


Fixed-Point Data

Fixed-point numbers contain p digits. For fixed-point decimal numbers, q of those digits may be fractional digits. Fixed-point binary numbers are always integers (q =0). For example:

DECLARE K FIXED BINARY(15);
DECLARE D FIXED DECIMAL(7,2);

In this example, the values of K are fixed-point integers with 15 binary digits. Therefore, K can hold any value in the range -32768 to +32767 or -(2**?15) to (2**?15)-1. The values of D are fixed-point numbers with seven decimal digits, two of which are fractional digits. Therefore, D can hold any value in the range -99999.99 to +99999.99.

DECLARE U FIXED BINARY(16) UNSIGNED;

The values of U are fixed-point integers with 16 binary digits. Therefore, K can hold any value in the range 0 to 65,535 or 0 to (2** 16)-1.

Because most computers operate most efficiently with binary integers, fixed binary variables should be used whenever possible. The relative efficiency of fixed binary variables used as subscripts, string lengths, DO index variables, and so forth is very significant.

Refer to your Open PL/I User's Guide for a description of the -longint compiler option, which alters the default precision of fixed binary variables from 15 to 31.

Fixed decimal values generally require more bits of storage and are often more computationally complex than values represented in binary, but fixed decimal values are more efficiently converted to and from an external form (for example, at input and output). In certain instances, fixed decimal values may also be less prone to rounding error than their binary counterparts.

An attempt to calculate a fixed decimal value too large to be supported results in a signal of the ERROR condition. An attempt to calculate a fixed binary value too large to be supported will not result in any error and may cause unexpected results. For rules on precision and scale, see the chapter Data Type Conversions.

Operations involving both decimal and binary values always produce a binary result value. However, if the operation must yield a result that has a fractional part, the result is decimal.

If a fixed-point value is converted to a character string or bit string, the length of the string is determined by the declared precision of the fixed-point value p. For a discussion of the conversion rules, see the chapter Data Type Conversions.

Fixed-point values are never rounded unless explicitly rounded by the use of a built-in function. Assignment to a fixed-point variable truncates excess low-order digits. All possible roundings can be performed by using the CEIL, FLOOR, TRUNC, or ROUND built-in functions.

Fixed-point decimal values are always stored as an accurate representation of decimal fractions. A fixed-point decimal value of 10.50 is never represented as 10.49.

Fixed-point constants are written as decimal numbers with or without a decimal point, as shown in the following examples:

5
4.5
4100.01

If a fixed-point constant contains a decimal point, it is considered to be a scaled fixed-point value and is stored and accessed like a fixed decimal variable. Fixed-point constants without a decimal point are integer constants and can be used safely in operations with any other arithmetic value, regardless of that value's base or scale. It is advisable to always write integer constants without a decimal point.

The precision of a fixed-point constant is the number of digits in the constant.

Parent topic: Arithmetic Data
Related information
Open PLI Users Guide
Data Type Conversions
Open PL/I Built-ins


Floating-Point Data

Floating-point data is used to represent values whose magnitudes are too great or too small to be represented by fixed-point data. It may also be used to minimize precision loss in calculations where terms differ considerably in magnitude.

Unexpected results may appear when using floating-point values. The limited precision of floating-point variables and the fact that they cannot precisely represent most fractional values combine to produce behavior in a program that may seem strange. Furthermore, the floating-point implementation on many machines carries more precision in intermediate results than is strictly required by the rules of PL/I. Also, floating-point variables and constants are usually limited to only one or two actual internal precision values. For example, most implementations of the IEEE floating-point standard allow only "short" (23-bit) and "long" (52-bit) floating-point values. Finally, precise results may vary depending on the level of program optimization.

For example, consider the following program:

SAMPLE: PROCEDURE OPTIONS (MAIN);
DECLARE
   (F,G)    FLOAT BINARY (23);
   F = 3111;
   G = .14;
   IF F + G ^= 3111.14 THEN
      PUT LIST ('UNEQUAL RESULT');
END SAMPLE;

This program will actually print the UNEQUAL RESULT message when run on many machines, because the constant .14 and 3111.14 are not precisely representable as floating-point binary numbers. The assignment of .14 to G puts about 23 bits of precision of the constant into the variable. On most implementations, the sum is computed with an actual precision of 52 or more bits, preserving the 23 bits of precision that apply to the fractional part. However, that sum is being compared to the constant 3111.14. The constant will have 23 or 52 bits of precision. (In fact, a strict implementation of the rules of the language requires only that it have 20 bits of precision; for more information, see the chapter Data Type Conversions.) If 3111.14 is represented as a short floating-point number, 14 of the 23 bits of precision are taken up to represent 3111 and hence only 9 bits of the fraction appear in the constant. This will not result in an equal comparison to the constant 3111.14. If the constant is a long floating-point number, 38 of the 25 precision bits will be fractional and the comparison will still fail.

One attempt to fix this might be to change the program as follows:

SAMPLE: PROCEDURE OPTIONS (MAIN);
DECLARE
   (F, G, H) FLOAT BINARY (23);
   RESULT    FLOAT BINARY (23) STATIC INITIAL (3111.14)
   F = 3111;
   G = .14;
   H = F + G
   IF H ^= 3111.14 THEN
      PUT LIST ('UNEQUAL RESULT')
END SAMPLE;

This appears to truncate the sum to a "real" 23 bits of precision and to compare it to a constant of known precision. This will normally work. However, in the presence of optimization, the value of F + G may be used without reducing its precision through storing it in H and then reloading it.

Thus, as a general rule, comparing floating-point numbers for equality and inequality does not work reliably. Instead, check for equality using the following method:

ABS(FIRST-SECOND) < EPSILON

where the constant EPSILON must be chosen considering the goal of the application.

Floating-point numbers consist of a mantissa m, a base b, and an exponent e. A floating-point number is represented in the following format:

m*b**e

The mantissa m is a fraction containing at least p digits. The value of b and the possible range of e are defined by each implementation (for information on this implementation, refer to your Open PL/I User's Guide); however, if the base is binary, m contains the equivalent of at least p binary digits, and if the base is decimal, m contains the equivalent of at least p decimal digits. For example:

DECLARE X FLOAT BINARY(23);
DECLARE Y FLOAT DECIMAL(7);

In this example, the values of X are floating-point numbers whose mantissa contains the equivalent of at least 23 binary digits. The values of Y are floating-point numbers whose mantissa contains the equivalent of at least 7 decimal digits.

The representation of floating-point values in storage also depends on the implementation. An implementation may represent the mantissa in any base that it chooses, provided that it contains an equivalent of at least p binary or p decimal digits. On some computers, decimal floating-point values are represented by using a decimal mantissa, while other implementations use a binary or hexadecimal mantissa for all floating-point numbers.

Open PL/I represents floating-point decimal using a decimal mantissa and decimal exponent, and represents floating-point binary using a binary mantissa and binary exponent. For more information, refer to your Open PL/I User's Guide.

Because floating-point values may be represented in either base, and because excess digits may be lost during calculations, floating-point values may be approximate. However, any integer value that is converted to floating-point and converted back to integer retains its original value. Likewise, the floating-point calculations of addition, subtraction, and multiplication, when performed on integer values, produce integer values.

Floating-point constants are written as fixed-point constants followed by an exponent, as shown in the following examples:

5E+02
4.5E1
100E-04
.001E-04
0E0

Floating-point constants have a decimal precision of p, where p is the number of digits in the fixed-point constant. For example, 4.5E1 has a precision of 2.

When fixed-point constants such as 1.5 are used in operations with floating-point values, they should be written with an exponent to avoid run-time conversion of fixed-point decimal values to floating-point.

If floating-point values are converted to character strings or bit strings, the length of the resulting string is determined by p, not by the actual value. For a discussion of conversion rules, see the chapter Data Type Conversions.

Caution is necessary when using floating-point constants in arithmetic expressions. Floating-point constants are considered to be of type Float Decimal, and the rules for the precision of arithmetic results specify that the precision of the result of a floating-point operation is the maximum of the precisions of the operands. Consider the following example:

SAMPLE2: PROCEDURE OPTIONS(MAIN);
DECLARE
   X FLOAT BIN(52);
   X = 1E0 + .4999E0;
   PUT SKIP LIST(X);
END SAMPLE2;

The answer printed by this program is, surprisingly, .500000000000000E+000. This is because the two constants are Float Decimal with precisions of 1 and 4, respectively. The addition is performed and the result is converted to Float Decimal(4); the intermediate result of 1.4999 is rounded to 4 decimal digits, and the result is converted to Float Binary and stored in X. An attempt to correct this might be to change the expression to read

X = BINARY(1E0) + BINARY(.4999E0);

This does the computation in Float Binary. However, this converts the first constant to Float Bin(4) and the second to Float Bin(14), and does the computation in short floating-point on most machines. The short floating-point result is lengthened to Float Bin(52) and is then stored in X, giving an answer of 1.499900013208389E+000. The correct fix is to use the two-argument form of the BINARY built-in function:

X = BINARY(1E0,52) + BINARY(.4999E0,52);

This produces long floating-point constants and the computation is done with maximal precision, printing 1.499900000000000E+000. Another solution would be to rewrite the constants using trailing zeros to indicate a more precise constant:

X = 1.0000000000000000E0 + .4999000000000000E0;

This also gives 1.499900000000000E+000, since the computation is done in large enough precision and the result is converted directly to a high-precision floating-point value.

In general, when using floating-point constants in arithmetic expressions with floating-point variables, the precision of the result can be controlled by using the FLOAT and BINARY built-in functions on the operands. The results of operations on two floating-point constants may not be what is expected.

Exponentiation, MOD, and all transcendental functions (including SORT) operations on floating-point decimal data are actually performed using the floating-point binary operations. Thus, the range of the operands and the results of these operations are limited to the ranges for floating-point binary numbers.

Parent topic: Arithmetic Data
Related information
Open PLI Users Guide
Data Type Conversions


Picture Data

Picture data represents fixed-point decimal or character values that are stored internally as character strings. The strings contain the characters that represent the numeric or character values in a specified-format (as indicated by special embedded symbols, such as a period or a comma).

Picture data is best used to manipulate a string or numeric quantity arithmetically and then print or display its value using a special output format.

A pictured value is any value whose data type is either declared by a PICTURE attribute or is acquired by the P format in a FORMAT statement. Picture characters are the special characters that make up the picture specification in the PICTURE attribute and in the P format item. Following are examples of picture specifications declared by the PICTURE attribute:

DECLARE F PICTURE '$ZZ,ZZZV.99CR';
DECLARE G PICTURE '$$$,$$$V.99-';
DECLARE H PICTURE '$**,***V.999';
DECLARE I PICTURE '----9V.999';
DECLARE J PICTURE '9999V9999S';

If the value -1234.56 was assigned to each of the variables in these examples, the resulting picture values would be as follows:

Repetition factors can be used for sequences of identical picture characters. For example, the following declaration of J is equivalent to the one given above:

DECLARE J PICTURE '(4)9V(4)9S';
  • Picture Specification Characters
  • Rules for Using Numeric Picture Data
  • Picture Repetition Factors
Parent topic: Data Types


Picture Specification Characters

A picture specification is a sequence of picture characters. A picture specification can be either a character picture specification or a numeric character picture specification. The picture specification is enclosed in single or double quotation marks.

The sequence of picture characters describe the contents of each position of either a character data item or numeric character data item, as well as the contents of the output. An A or X character in the picture specification defines it as a character picture specification. A picture specification without an A or X character is a numeric character picture specification.

Character Picture Specification

A character pictured item consists of alphabetic characters, decimal digits, blanks, currency symbols, and punctuation characters.

A character picture specification includes:

Character | Description
X, A, 9 | Validate each character of data with allowed character set.

The character picture characters are:

Character | Description
X | Any character of the 256 possible bit combinations represented by the 8-bit byte.
A | Any alphabetic or extra-lingual (#, @, $) character, or blank.
9 | Any digit, or blank. Blanks are only allowed for character data.

A character picture specification describes a nonvarying character data item. You can specify that any position in the data item contain characters only from certain subsets of the available character set. Data consists of alphabetic characters, decimal digits, and blanks. The only valid characters in a character picture specification are X, A, and 9.

When a character value is assigned or transferred to a picture character data item, the particular character in each position is validated according to the corresponding picture specification character. If the character data does not match the specification at a given position, the CONVERSION condition is raised for the invalid character.

In the following example, valid values for PartNum include:

'BF123M'

'KL092/'

'BT013'

declare PartNum picture'AA999X';
put skip edit(PartNum)(P'AA999X');

Numeric Character Picture Specification

A numeric character pictured item consists only of decimal digits, an optional decimal point, and optional plus or minus signs. While other arithmetic characters such as currency symbols can also be specified, they are not part of the variable's numeric character value. Other arithmetic characters however are stored with the digits and are part of the variable's character value.

A numeric character picture specification includes:

Category | Character | Description
decimal place character | V | Affects the numeric interpretation of the value only. The decimal point character is not actually stored.
digit characters | 9, Z, *, Y | Mark the positions occupied by decimal digits and affect both the numeric interpretation and character representation of the value.
encoded sign characters | T, I, R | Represent a digit that has the sign of the value encoded in the same position with the digit, thereby affecting both the numeric interpretation and character representation of the value. These characters can be used wherever the digit specifier '9' is valid.
drifting characters | $, +, –, S | Indicates digits or symbols to be inserted in the internal representation of a character. (See the section Drifting Characters and Strings.)
insertion characters | Decimal point (.), comma (,), slash (/), and space (B) | Inserted between digits to indicate that characters are inserted in the internal representation of the pictured value. Drifting characters also function as insertion characters when they are used singly.
credit and debit | CR, DB | Always specified as two-character symbols. (See the section Credit and Debit Characters.)
Note: A character picture specification cannot be mixed with numeric picture specification. However the character 9 can be used both as a character picture character and a numeric picture character.

The following describes the numeric picture characters.

Character | Description
V Indicates the position of the "assumed" decimal point. All digit positions to the right of the 'V' are fractional digits.

Any value assigned to a pictured value is first scaled so that its decimal point is aligned with the 'V'. Only one 'V' character can appear in a picture. If a picture does not contain the 'V' character, it is assumed to be at the right end of the picture, implying an integer value.

B, ./ Indicate the positions at which a space (B), comma, decimal point, or slash, respectively, are inserted. These picture characters are inserted into the pictured value only if they are preceded by a nonzero digit or if they are preceded by a '9' or 'V' picture character. If they are not inserted, a zero suppression character (a blank) or an asterisk (*) is inserted instead.

If an asterisk or drifting string occupies the position preceding the insertion character and that position corresponds to a leading zero, the asterisk or drifting string character also suppresses the insertion character.

The 'V' and decimal point (.) must be adjacent to one another to ensure that the decimal point is in the same position in both the numeric and character interpretations. The period should follow the 'V' to ensure that it will be in the correct location and will appear whenever any fractional digit is significant.

Z Indicates a decimal digit with leading zero suppression.

The 'Z' causes zero suppression using a blank as the suppression character. A 'Z' must not be preceded by a '9' or a drifting string. A picture containing a 'Z' must also not contain an asterisk (*).

If 'Z' picture characters appear to the left of 'V', all leading zeros in positions corresponding to those 'Z' characters are suppressed. Nonzero digits and significant zeros are never suppressed. Suppressed zeros are represented by spaces.

If a 'Z' appears to the right of 'V', all digits in the value must be indicated by 'Z' characters. Fractional zeros are then suppressed only if all fractional digits are zero and all integer digits are suppressed. In this case, the internal representation contains only spaces in the digit positions.

Note:

Refer to the examples in the section Rules for Using Picture Data.

* Indicates a decimal digit with leading zero suppression. The '*' causes zero suppression using an asterisk as the suppression character. An '*' must not be preceded by a '9' or a drifting string. A picture containing an '*' must also not contain a 'Z'.

The rules for '*' are otherwise the same as those for 'Z'.

S Indicates the position of the plus sign (+) or minus sign (-), which may or may not be drifting. The 'S' causes the plus sign to be inserted if the numeric value is greater than or equal to zero, and causes the minus sign to be inserted if the value is less than zero.

If an 'S' occurs more than once in a picture, the entire field of 'S's is a drifting string and can only contain a 'V' and one or more 'B' , '.' or '/' picture characters. Such a field cannot be preceded by a '9', 'Z', or '*', and if it contains a 'V' followed by one or more 'S's, it cannot be followed by a '9'.

The total number of digits represented by a drifting string is one less than the number of 'S's in the field. The digits are zero suppressed and a sign of '+' or '-' is inserted immediately preceding the most significant digit of the value.

A single 'S' causes a sign of '+' or '-' to be inserted into the pictured value, at the location implied by the position of 'S' in the picture.

+ Indicates the position of the plus sign (+) to be inserted if the numeric value is greater than or equal to zero. Operates exactly like 'S', except that the sign of negative values is indicated by a blank.
– Indicates the position of the minus sign (–) to be inserted if the numeric value is less than zero. Operates exactly like 'S', except that the sign of positive values is indicated by a blank.
$ Indicates the position of the dollar sign ($) to be inserted. Operates like 'S', except that a '$' is inserted instead of either sign.
9 | Indicates a decimal digit, including leading zeros. The position occupied by '9' always contains a decimal digit, regardless of whether the digit is, or is not, significant in the numeric interpretation of the pictured value.
Y | Indicates the position of a decimal digit in which the zero digit is always suppressed by a blank, regardless of the position of 'Y' relative to other picture characters.
CR | Indicates the position at which 'CR' is inserted if the number is less than zero. These two characters must appear as a pair on the rightmost end of the picture. They are replaced by two blanks in internal representation if the value is not negative.
DB | Indicates the position at which 'DB' is inserted if the number is less than zero. Like 'CR,' these two characters must appear as a pair, may only appear on the rightmost end of the picture, and are replaced by two blanks in internal representation if the value is not negative.
T | Indicates the position of a decimal digit with an encoded plus or minus sign. The digit contains an encoded plus sign if the numeric value is greater than or equal to zero and an encoded minus sign if the value is less than zero. (See table below for representations of encoded sign digits.)
I | Indicates the position of a decimal digit with an encoded plus sign if the numeric value is greater than or equal to zero. If the value is less than zero, the position contains an ordinary digit.
R | Indicates the position of a decimal digit with, possibly, an encoded minus sign if the numeric value is less than zero. If the value is greater than or equal to zero, the position contains an ordinary digit.
Digit | ASCII Character | Digit | ASCII Character
–0 | } | +0 | {
–1 | J | +1 | A
–2 | K | +2 | B
–3 | L | +3 | C
–4 | M | +4 | D
–5 | N | +5 | E
–6 | O | +6 | F
–7 | P | +7 | G
–8 | Q | +8 | H
–9 | R | +9 | I
Parent topic: Picture Data
Related information
Drifting Characters and Strings
Credit and Debit Characters
Rules for Using Picture Data


Rules for Using Numeric Picture Data

The rules for using numeric picture data are as follows:

  1. A numeric picture cannot contain more than one sign character ('+', '–', 'S', 'T', 'I', 'R', 'CR', or 'DB') unless all such sign characters are part of a drifting string.
  2. When a zero value is assigned to a numeric pictured variable and the numeric picture does not contain at least one '9', the entire value is filled with blanks or with asterisks (*), depending on which zero-suppression character was used.
  3. When a nonzero value is assigned to a numeric pictured variable, and the 'V' is followed by zero-suppression characters or by part of a drifting string, the 'V' stops zero suppression. For example:
    DECLARE A PICTURE 'ZZZV.ZZ';
DECLARE B PICTURE '***V.**CR';

    In this example, a value of . 01 assigned to A and B produces boxes and . boxes. A value of zero assigned to A and B produces boxes and ********.

  4. If a 'V' is not given, a 'V' is implied at the rightmost end of the numeric picture.
  5. Each '9', 'Z', or '*' is considered to be a digit of precision. Within a drifting string each 'S', '+', '–', or '$', except the first one, is considered to be a digit of precision. All digits of precision following the 'V' are fractional digits. For example:
    DECLARE A PICTURE 'ZZZV.ZZ'
DECLARE B PICTURE '---V.z--'

    In this example, A has a precision of (5,2), while B has a precision of (4,2).

  6. Negative values cannot be assigned to a numeric pictured variable unless the picture contains a 'CR', 'DB', '–', or 'S'. An error condition is signaled if a negative value is assigned to a numeric pictured variable that does not contain 'S', '+', '–', 'T', 'I', 'R', 'CR', or 'DB'.
  7. Values assigned to numeric pictured variables are truncated and aligned with the `V' as they would be when assigned to a fixed decimal variable of the equivalent precision.
  8. Used in contexts that expect an arithmetic value, or used with a relational operator, numeric pictured values are converted to fixed-point decimal values with a precision p and q that are determined by the numeric picture.
  9. A numeric pictured value is operated upon as if it were a character-string value only when it is assigned to a character-string variable, and when it is an operand of the concatenate operator or of a built-in function that expects character-string operands. In all other contexts, numeric pictured values are operated upon as if they were fixed-point decimal values.

Following are more examples of picture format output.

Example | Data | Picture | Output
1 | 12345.60 | $SSSSSSSSV.99 | $ boxes +12345.60
2 | 1.23 | **********V.99 | .********1.23
3 | 1.23 | ZZZZZZZZZZV.99S | boxes 1.23
4 | 1234.56 | Z.ZZZ ZZZV,99 | boxes 1.234,56
5 | 11011111 | 9999B9999 | 1101 boxes 1111
6 | 011335 | **/**/** | *1/13/35
7 | 1234567890 | 999999999V.99 | 234567890.00
8 | .33 | ZV.ZZ | box .33
9 | .75 | ZV.ZZ | box .75
10 | 1234567.89 | $999,999,999V.99DB | $001,234,567.89
11 | -1234567.89 | $999,999,999V.99CR | $001,234,567.89CR
12 | 1023 | YYYYY | 1 23

In example 1, '$' is a static character because it appears only once, whereas 'S' is a drifting character because it appears all the way to the decimal.

In examples 2, 3, and 4, the characters 'Z' and '*' are zero-suppression characters. The asterisk prints wherever a zero or blank would have printed, and the 'Z' substitutes blanks.

In example 5 the insertion character 'B' results in a space (blank). A blank is inserted wherever the 'B' appears in the numeric picture format unless it is in a field of zero-suppression characters that are suppressing zeros at the time.

In example 7, the appearance of the character '9' results in the printing of a digit. All digits 0 through 9 are printed, except the leading one, which is truncated.

In examples 8 and 9, the character 'V', once encountered, turns off suppression; all characters after the 'V' are printed. Note that in Example 8, 'V' is not used before the decimal point, so the point is turned off, not on.

Examples 10 and 11 show the result of positive and negative data applied to numeric pictures that contain either 'CR' or 'DB'.

  • Drifting Characters and Strings
  • Credit and Debit Characters
Parent topic: Picture Data


Drifting Characters and Strings

Used alone in a picture, one drifting character marks the position where a special symbol or space is to be inserted. It does not affect the value's numeric interpretation. In this context, the character must appear either before or after all characters that specify digit positions.

If a series of n (n >1) drifting characters appears in a picture, the rightmost n-1 of the characters in the series also specify digit positions. If the digit is a leading zero, the leading zero is suppressed, and the leftmost character "drifts" to the right. In internal representation, the character appears either in the position of the last drifting character in the series or immediately to the left of the first significant digit, whichever comes first. In this context, the n-1 drifting characters also define a portion of the numeric precision of the picture variable, because they describe at least some positions occupied by decimal digits.

A drifting string is a series of more than one of the same drifting character. Only one drifting string can be used in a picture; other drifting characters can be used only individually to designate insertion characters, not digits.

The 'Z' and '*' characters cannot appear to the right of a drifting string.

A digit position cannot be specified to the left of a drifting string.

These rules apply to insertion characters embedded in a drifting string:

  • If the drifting string contains an insertion character, the insertion character is inserted in the internal representation only if a significant digit appears to its left. In the position of the insertion character, a space appears if the leftmost significant digit is more than one position to the right; the drifting symbol appears if the next position to the right contains the leftmost significant digit.
  • If the drifting string contains a 'V' character, all digit positions to the right of the 'V' (the fractional digits) must also be part of the drifting string. Insignificant fractional digits are suppressed only if all integral and fractional digits are zeros; if so, they are replaced by spaces in the internal representation. If any digit is not zero, all fractional digits appear as actual digits.
  • Insertion characters that appear to the immediate right of a drifting string are considered part of the drifting string.
Note:

Refer to the examples in the section Rules for Using Numeric Picture Data.

Parent topic: Rules for Using Numeric Picture Data
Related information
Rules for Using Numeric Picture Data


Credit and Debit Characters

Regardless of which character pair is included, 'CR' or 'DB', that character pair appears in the internal representation if the numeric value is less than zero. If the numeric value is greater than or equal to zero, the associated positions in the internal representation contain two spaces.

The credit and debit characters are always inserted with the same case used in the picture; for example, if lowercase 'db' is used in the picture, then lowercase letters are inserted into the pictured value, and if the combination of uppercase and lowercase characters, such as 'Db', is used, 'Db' is inserted into the pictured value. The 'CR' and 'DB' character pairs cannot be used in the same picture, and neither pair can be used in the same picture with any other character that specifies the sign of the value, namely, 'S', '+', '–' and the encoded-sign characters ('T', 'I', 'R').

Parent topic: Rules for Using Numeric Picture Data


Picture Repetition Factors

A picture repetition factor is an integer specifying the number of times the following picture character is to be repeated. The repetition factor is enclosed within parentheses (there can be no blanks within the parentheses). If the value of the repetition is 0, the following picture character is ignored. For example:

pic '(4)9V(2)9'

is the same as

pic '9999V99'
Parent topic: Picture Data


Character-String Data

A character-string value is a sequence of characters. The number of characters in a sequence is called the length of the sequence. In Open PL/I, the maximum length of a string value is 32767 bytes or characters.

A character-string of zero length is called a null string.

A character-string variable or character-string valued function is declared with the following attributes:

CHARACTER(n)

or

CHARACTER(n) VARYING

or

CHARACTER(n) VARYINGZ

where n is an integer valued expression that specifies the maximum length of all string values that can be held by the variable or returned by the function.

The VARYING (VAR) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the length of the varying string is recorded along with the value. Varying strings are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n characters may be held by the variable, and the length of the current string is retained as part of the value.

The VARYINGZ (VARZ) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the varyingz strings are a stored as a sequence of characters terminated by a ‘00’x byte, and are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n characters may be held by the variable.

Without the VARYING attribute, a string variable or function always holds or returns values of length n. An assignment to a nonvarying string always extends short values with blanks on the right to make them n characters long.

Assignments of a string of more than n characters to either a varying or a nonvarying string variable cause only the leftmost n characters to be assigned and excess characters to be truncated.

Character-string values are compared from left to right using the collating sequence of the computer. Strings of unequal length are compared by effectively extending the shorter string with blanks on the right.

Nonvarying character-string variables always occupy exactly n bytes of storage. As elements of arrays or members of a structure, they begin on the next available byte and are not aligned on word or other storage address boundaries. This permits an array of nonvarying characters to be stored and accessed as if it were a single string. See the section Storage Sharing in the chapter Storage Classes.

Varying character-string variables always occupy n+2 bytes of storage. The first 2 bytes contain an integer L (0 <= L <= n) that specifies the length of the string value currently stored in the variable. The string text occupies the first L bytes of the storage following the 2 length bytes. The value of the last n–L bytes of the variable is undefined. The value L can be accessed using the LENGTH built-in function. An array of varying character strings cannot be accessed as if it were a single character string.

Varyingz character-string variables always occupy n+1 bytes of storage. The current length L of a varyingz string is determined by the position of the first ‘00’x byte, where L = index(string, ‘00x’) – 1. The string text occupies the first L bytes of the storage following the ‘00’x terminator. The value of the last n–L bytes of the variable is undefined. The value L can be accessed using the LENGTH built-in function. An array of varyingz character strings cannot be accessed as if it were a single character string.

See the Open PL/I User's Guide for specific alignment of varying character strings.

A character-string constant is written in the following format:

'Any characters except quote'

If an apostrophe is required within the constant, it must be written as an adjacent pair of apostrophes.

Examples:

'ABC'
'He said, "I don"t know."'
''

In these examples, the second string displays a pair of single quotation marks used within the text string "don't". This text string also shows that the double quotation mark is insignificant as a delimiter of a character-string constant. The string in the last example is a null string.

Note: Any string produced as an intermediate result requires storage allocated either on the stack. System area storage is required for the ALLOCATE statement. Allocating a large temporary storage block that exceeds the amount of available storage results in a signal of the ERROR condition.
  • String Repetition Factors
Parent topic: Data Types
Related information
Storage Sharing
Open PLI Users Guide


String Repetition Factors

Repetition factors can be used with character and bit strings. For example:

(4)'Abc'

is equivalent to a character constant where 'Abc' is repeated four times, 'AbcAbcAbcAbc'

and

(4) '10'B

is equivalent to

'10101010'B

The maximum string repetition factor is 32767.

Parent topic: Character-String Data
Related information
Picture Repetition Factors


Graphic String Data (DBCS Support)

A GRAPHIC string is a sequence of DBCS characters (double-byte characters). The number of DBCS characters in a graphic string or sequence is called the length of the graphic string or sequence. In Open PL/I, the maximum length of a graphic string value is 16383 DBCS characters.

A graphic string of zero length is called a null graphic string.

A graphic string variable or graphic string valued function is declared with the following attributes:

GRAPHIC(n)

or

GRAPHIC(n) VARYING

or

CHARACTER(n) VARYINGZ

or

GRAPHIC(n) VARYING BIGENDIAN

where n is an integer valued expression that specifies the maximum length of all graphic string values that can be held by the variable or returned by the function. G can be used as a synonym for GRAPHIC.

The VARYING (VAR) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the length of the varying string is recorded along with the value. Varying strings are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n graphic characters may be held by the variable, and the length of the current string is retained as part of the value. By default, the length field is always stored according the native architecture of the machine for fixed binary (15) data items. If the BIGENDIAN attribute is supplied, the length field is stored in Big Endian format.

The VARYINGZ (VARZ) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the varyingz graphic strings are a stored as a sequence of characters terminated by a ‘0000’x byte, and are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n double-byte characters may be held by the variable.

Without the VARYING attribute, graphic string variable or function always holds or returns values of length n . An assignment to a non-varying string always extends short values with DBCS blanks on the right to make them n graphic characters long.

Assignments of a string of more than n graphic characters to either a VARYING or a non-varying string variable cause only the leftmost n graphic characters to be assigned and excess characters to be truncated.

Graphic string values are compared from left to right using the binary values of the DBCS byte-pairs. Graphic strings of unequal length are compared by effectively extending the shorter string with DBCS blanks on the right.

Non-varying graphic string variables always occupy exactly n*2 bytes of storage. As elements of arrays or members of a structure, they begin on the next available byte and are not aligned on word or other storage address boundaries. This permits an array of non-varying characters to be stored and accessed as if it were a single wide string.

Varying graphic string variables always occupy (n*2)+2 bytes of storage. The first 2 bytes contain an integer L (0 <= L <= n) that specifies the length of the wide string value currently stored in the variable. The string text occupies the first L*2 bytes of the storage following the 2-byte length field. The value of the last n-L byte-pairs of the variable is undefined. The value L can be accessed using the LENGTH built-in function.

Varyingz graphic string variables always occupy n+1 double-bytes of storage. The current length L of a varyingz string is determined by the position of the first '0000'x double-byte, where L = index(string, '0000'Gx) - 1. The string text occupies the first L double-bytes of the storage following the '0000'x double-byte terminator. The value of the last n-L double-bytes of the variable is undefined. The value L can be accessed using the LENGTH built-in function. An array of varyingz graphic strings cannot be accessed as if it were a single character string.

See the Open PL/I User's Guide for specific alignment of graphic varying strings.

Restrictions

  • GRAPHIC characters in source files is not supported.
  • G string constants are not supported.
  • GRAPHIC(x) VARYINGZ is not supported.
  • DBCS SISO sequences embedded in the source code are not supported.
  • Mixed Data is not supported.
  • M Constants are not supported.
  • The GRAPHIC data type is not supported when using the -ebcdic compiler option.

Graphic String Constants

A graphic string constant must be written as a Graphic String Hexadecimal Literal. For example:

Dcl gstr graphic (12) init(‘82678285828C828C828F81408276828F8292828C82848144'Gx) ;

For graphic string literals with DBCS byte-pairs that correspond to the ASCII collating sequence, ASCII character string literals may be used, and the compiler will do the appropriate internal conversion to type GRAPHIC for the set codepage.

For example:

Dcl gstr graphic(12) init ('Hello World.');

Is the equivalent to the above when using Codepage 932 - SHIFT-JIS.

Parent topic: Data Types


Wide Character-String Data (UTF-16 Support)

A wide character-string value is a sequence of double-byte characters or byte-pairs. The number of byte-pairs in a wide character string or sequence is called the length of the string or sequence. In Open PL/I, the maximum length of a wide string value is 16383 byte-pairs or double-byte characters. The byte-pairs are always stored in big-endian format.

A wide character-string of zero length is called a null wide string.

A wide character-string variable or character-string valued function is declared with the following attributes:

WIDECHAR(n)

or

WIDECHAR(n) VARYING

or

CHARACTER(n) VARYINGZ

or

WIDECHAR(n) VARYING BIGENDIAN

where n is an integer valued expression that specifies the maximum length of all wide string values that can be held by the variable or returned by the function. WCHAR can be used as a synonym for WIDECHAR.

The VARYING (VAR) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the length of the varying string is recorded along with the value. Varying strings are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n wide characters may be held by the variable, and the length of the current string is retained as part of the value. The length field is always stored according the native architecture of the machine for fixed binary (15) data items.

The VARYINGZ (VARZ) attribute causes the string variable or function to hold or return values of varying lengths. Internally, the varyingz strings are a stored as a sequence of characters terminated by a ‘0000’x byte, and are not padded to assume their maximum length, n. The representation of a varying string variable in storage is such that any string up to n double-byte characters may be held by the variable.

Without the VARYING attribute, a wide string variable or function always holds or returns values of length n. An assignment to a non-varying string always extends short values with blanks (0x0020) on the right to make them n wide characters long.

Assignments of a string of more than n wide characters to either a VARYING or a non-varying string variable cause only the leftmost n wide characters to be assigned and excess characters to be truncated.

Character-string values are compared from left to right using the binary values of the byte-pairs. Strings of unequal length are compared by effectively extending the shorter string with blanks (0x0020) on the right.

Non-varying character-string variables always occupy exactly n*2 bytes of storage. As elements of arrays or members of a structure, they begin on the next available byte and are not aligned on word or other storage address boundaries. This permits an array of non-varying characters to be stored and accessed as if it were a single wide string.

Varying wide character-string variables always occupy (n*2)+2 bytes of storage. The first 2 bytes contain an integer L (0 <= L <= n) that specifies the length of the wide string value currently stored in the variable. The string text occupies the first L*2 bytes of the storage following the 2-byte length field. The value of the last n-L byte-pairs of the variable is undefined. The value L can be accessed using the LENGTH built-in function. An array of varying wide character strings cannot be accessed as if it were a single wide character string.

Varyingz wide character-string variables always occupy n+1 double bytes of storage. The current length L of a varyingz string is determined by the position of the first '0000'x double-byte, where L = index(string, '0000'Wx) - 1. The string text occupies the first L double-bytes of the storage following the '0000'x double-byte terminator. The value of the last n-L double-bytes of the variable is undefined. The value L can be accessed using the LENGTH built-in function. An array of varyingz wide character-strings cannot be accessed as if it were a single character string.

See the Open PL/I User's Guide for specific alignment of varying character strings.

Note: Any string produced as an intermediate result requires storage allocated either on the stack. System area storage is required for the ALLOCATE statement. Allocating a large temporary storage block that exceeds the amount of available storage results in a signal of the ERROR condition.

Restrictions

  • All WIDECHAR byte-pairs are stored in Big Endian format.
  • WIDECHAR characters in source files is not supported.
  • W string constants is not supported.
  • WIDECHAR expressions in stream I/O is not supported.
  • Implicit conversions to/from WIDECHAR in record I/O are not supported.
  • Implicit endian-ness flags in record I/O are not supported.
  • Only Big Endian byte-pairs within WIDECHAR files is supported.
  • WIDECHAR(x) VARYINGZ is not supported.
  • Surrogate pairs are not supported.
  • UTF-8 is not supported.
  • The WIDECHAR data type is not supported when using the -ebcdic compiler option.

Wide Character String Constants

A wide character-string constant must be written as a Wide Character String Hexadecimal Literal. For example:

Dcl wstr widechar (2) init   (‘039103AA’Wx) ;
/* Greek upper case ALPHA OMEGA */

For wide character string literals with all byte-pair binary values < 0x0080 (ASCII collating sequence 0 - 127 hex), character string literals may be used, and the compiler will do the appropriate internal conversion to type WIDECHAR. For example:

Dcl wstr widechar (32) varying init (‘Hello Widechar!!’);
Parent topic: Data Types


Bit-String Data

A bit-string is a sequence of binary digits (bits). The number of bits in the sequence is called the length of the value.

A bit-string of zero length is called a null string.

A bit-string variable or bit-string valued function is declared with the following attributes:

BIT(n)

or

BIT(n) ALIGNED | UNALIGNED

where n is an integer valued expression that specifies the maximum length of all string values that can be held by the variable or returned by the function.

If a value of less than n bits is assigned to a bit-string variable, the variable is extended on the right with zero bits to make it n bits long. If a value of more than n bits is assigned, only the leftmost n bits are stored, and the excess bits are truncated.

The ALIGNED attribute causes the associated bit-string variable to be aligned on the storage boundary (described in your Open PL/I User's Guide) so as to make it more efficiently accessed. This attribute may also cause the variable to occupy more than n bits, but it does not increase the size of values that can be stored in the variable.

The UNALIGNED attribute causes the associated bit-string variable to be aligned at the next available bit so as to reduce storage requirements. If neither ALIGNED nor UNALIGNED is specified, UNALIGNED is assumed by default.

In the following structure declaration,

DECLARE 1 S ALIGNED,
        2 A BIT(3),
        2 B BIT(7) UNALIGNED,
        2 C BIT(1) UNALIGNED;
        2 D BIT(5);

the bit strings are stored as follows:

Stored Bit Strings

In this example the A and D strings are aligned because they inherit the ALIGNED attribute from the structure declaration. A bit string occupies a full byte. If the structure S had been declared with the UNALIGNED attribute, the A and D strings would be unaligned.

Bit-string values are compared from left to right, a bit at a time until an inequality is found. The shorter operand is effectively extended by zero bits on the right to make it the length of the other operand for purposes of comparison.

A bit-string is not a word of storage in a computer and is not an arithmetic value. It is a sequence of bits that is always operated upon from left to right, just as a character string is operated upon from left to right.

A bit-string constant is written as a quoted string of zeros and ones followed by a B.

A bit string of length one is a boolean value with the possible values of '0'B and '1'B, which denote false and true, respectively.

Note: No assumptions should be made about the form in which a bit-string is stored.

Examples:

'1'B
'10110'B
'O'B
''B

The last string in the previous set of examples is a null bit string.

Bit-string constants may also be written using a string of characters to represent the bit string:

'character string'Bn

where n is 1, 2, 3, or 4 and is the number of bits each character represents. The table below gives the set of permissible characters and shows the corresponding bit-string values. In this table, a '–' indicates 'invalid.'

Character
 | B or B1 | B2 | B3 | B4
0 | 0 | 00 | 000 | 0000
1 | 1 | 01 | 001 | 0001
2 | – | 10 | 010 | 0010
3 | – | 11 | 011 | 0011
4 | – | – | 100 | 0100
5 | – | – | 101 | 0101
6 | – | – | 110 | 0110
7 | – | – | 111 | 0111
8 | – | – | – | 1000
9 | – | – | – | 1001
A | – | – | – | 1010
B | – | – | – | 1011
C | - | - | _ | 1100
D | – | – | – | 1101
E | – | – | – | 1110
F | – | – | – | 1111

For example:

Bit-String | Equivalent Value
'073'B3 | '000111011'B
'A04'134 | '101000000100'B
Parent topic: Data Types


Area Data

An area is a region of storage in which based variables can be allocated and freed. Area variables can have any storage class and may be scalars or arrays. Explicit declaration with an area attribute has the following format:

AREA[(exp [REFER (variable)])]

or

AREA (*)

The exp used with the area attribute specifies the number of bytes reserved for the area. This size is rounded up to an 8-byte boundary as necessary.

For an area with the STATIC storage class, the size must be an integer constant.

For areas having the AUTOMATIC, CONTROLLED, or BASED storage classes, the size is defined by an integer expression; if an area is a member of a BASED structure, however, the size specification can use the REFER option.

If neither expression nor asterisk is specified, the default size is 1000 bytes. For example,

DECLARE AREA1   AREA(4096),
   AREA2        AREA,
   1 S       BASED,
   2 X       FIXED BIN(15),
   2 AREA3(1024 REFER(X));

An alternate way to declare an AREA is implicitly, through its use in the following contexts:

  • The IN option of an ALLOCATE statement. For example:
    ALLOCATE X IN(A1);
  • The OFFSET attribute of an offset variable declaration. For example:
    DECLARE 0 OFFSET(A1);

Area variables are always aligned on 8-byte boundaries. The UNALIGNED attribute is not applicable to AREA variables.

Only based variables can be allocated in an area. Use of an area allows related items to be allocated and freed only in that region of storage reserved for the area. The area can be assigned or transmitted as a unit, complete with all the allocations it contains. To preserve the desired alignment constraints in the area, the size of any allocation within the area is always rounded to an 8-byte boundary.

The amount of reserved storage that is actually in use is known as the "extent" of the area. When first allocated (prior to any allocation in it), the extent of the area is zero. The maximum extent is represented by the "area size." When a based variable is allocated or freed, the extent of the area is updated to reflect the change in the amount of storage in use. In addition, when a based variable is freed, the storage it occupied is added to a chain of available storage blocks within the area. The area extent and the free chain are maintained in an 8-byte control block, adjacent to the space reserved for the area.

Areas may be assigned and passed as arguments. However, areas cannot be compared or otherwise have any operators applied to them.

When an area variable is assigned to another, all allocations in the target area are freed and the extent of the target area is set equal to that of the source area.

The AREA condition is raised for an illegal area assignment detected at run-time. This situation occurs if the maximum size of the source area exceeds that of the target area. The AREA condition is also raised when an attempt is made to allocate a based variable within an area that has too little free storage to accommodate it. For more information about the AREA condition, see the information for AREA in the ON topic in the Statements help section.

Offset variables are used to indicate the locations of based variables within the area. See the discussion in the Offset Data topic of the Data Types help section .

Variables of type AREA display as <...> because of their complex content and potentially large size.

Parent topic: Data Types
Related information
ON
Offset Data


Locator Data

Locator data is data whose purpose is to specify the location of other, usually based or controlled, data. Open PL/I supports two types of locator data: pointers and offsets.

  • Pointer Data
  • Offset Data
Parent topic: Data Types


Pointer Data

A pointer value is the address of a variable's storage. For example:

DECLARE K FIXED BINARY(15);
DECLARE A(5) FIXED BINARY(15);
DECLARE P POINTER;
   .
   .
   .
P = ADDR(A(K));

In this example, P is a pointer variable that is capable of holding the address of any variable, with the possible exception of unaligned bit strings (for more information, see your Open PL/I User's Guide). The assignment statement uses the ADDR built-in function to calculate the address of A (K) and assigns that address as the value of P.

A pointer is used with a template to access the storage to which it points. For example:

DECLARE X FIXED BINARY(15) BASED;
   .
   .
   .
P->X = 10;

In this example, X is a based variable (that is, a template) describing a fixed-point binary integer. P is the pointer variable from the example at the beginning of this section. The assignment assigns 10 to A (K).

Pointers are often used to locate the storage of dynamically allocated based variables as described in the section Based Variables in the chapter Storage Classes, but may provide a mechanism for accessing another variable's storage, as shown in the previous two examples.

The null pointer value is produced by the NULL built-in function. It is a unique value that does not address any variable and is used to indicate that a pointer variable does not currently address anything, as shown in the following example:

DECLARE CHAIN_HEAD POINTER;
   .
   .
   .
CHAIN_HEAD = NULL();

The internal representation of NULL is determined by the -setnull compiler option. For more information on compiler options, see your Open PL/I User's Guide.

If the variable whose storage is addressed by a pointer value is freed, the pointer value should no longer be used. Use of such a pointer to access the storage causes unpredictable results.

The ADDR built-in function must not be used to calculate the address of an unaligned bit data. Consequently, when such a restriction is imposed, pointer values never address unaligned bit-string data. However, all other data can always be addressed by a pointer, regardless of the addressing capabilities of the computer.

Note:

The based variable that is used as a template normally must have the same data type as the variable addressed by the pointer. Violations of this rule cause unpredictable results. Programs that violate this rule and produce "correct" results may fail when compiled with optimization enabled or may fail when moved to another implementation of PL/I.

A pointer value cannot be represented by a constant. However, the NULL built-in function can be used in any context, including an INITIAL attribute, where a constant might be desired.

Parent topic: Locator Data
Related information
Storage Sharing
Based Variables
Open PLI Users Guide


Offset Data

The OFFSET attribute describes a locator data type that is used to specify the location of a based variable within an area. The format of the OFFSET attribute is:

OFFSET [(area-variable)]

An offset variable is a locator used only in conjunction with an area variable. The value of an offset variable specifies the location of a based variable within an area, relative to the beginning of the area. Since an offset value specifies a relative location, the value remains valid even when the area is assigned to another region of storage.

To use an offset variable to identify a particular based variable, the offset variable must be associated with an area. For example:

DECLARE A   AREA,
        O   OFFSET(A),
        X   FIXED BASED(O),
        Z   OFFSET,
        P   POINTER;

ALLOCATE X IN(A) SET(O);
X = 5;                  /* Implies area and offset */

This association can be done in the declaration by specifying the area variable, as shown in the previous example. This type of declaration has the convenience of implicitly referring to the associated area whenever a reference is made to the offset variable used as a locator.

When an offset value is assigned to or compared with another offset variable, only its actual value is used — the implicit area reference is ignored. However, when used as a locator, or when compared to or assigned to a pointer, the offset value is implicitly converted to a pointer by generating an address derived from the offset value combined with the address of the area with which it is associated. If this association was not done in the declaration, it can still be done using the POINTER built-in function:

P = POINTER(Z, A);   /* offset Z was not associated with
                           area A in its declaration */

Note that, if the offset variable did not have an area association in its declaration, then it is only with the POINTER built-in function that the offset variable can be used as a locator to address a variable within an area. For more information, see the description of the POINTER built-in function in the section POINTER in the chapter Open PL/I Built-Ins.

An OFFSET variable may be assigned a value in the following ways:

  • With the ALLOCATE statement

    For example:

    DECLARE X    FIXED BIN(31 BASED(01),
       Al    AREA,
       01    OFFSET(A1);

ALLOCATE X;     /*sets 01 = to the offset
                   of X in area A1 */

    Since the locator for X and the associated area of 01 are both specified in their respective declarations, the previous ALLOCATE statement is equivalent to:

    ALLOCATE X IN(A1) SET(01);
  • By assignment of another locator (offset or pointer) value
  • By assignment of the NULL() built-in function
  • By assignment of the OFFSET built-in function, which complements the POINTER built-in function (see the section POINTER in the chapter Open PL/I Built-Ins).
Parent topic: Locator Data
Related information
POINTER


Label Data

A label prefix on a statement, other than a PROCEDURE or FORMAT statement, is a declaration of a statement label.

The LABEL attribute can be used to declare variables and functions whose values are labels. For example:

A: PROCEDURE;
   DECLARE L LABEL;
      .
      .
      .
   L1:
      .
      .
      .
   L = L1;

In this example, the label variable L is assigned a statement label value. A subsequent GOTO L; would transfer control to the statement labeled L1.

A label value is a descriptor that consists of two parts. One part designates a statement (the instructions compiled for the statement) and the other part designates a stack frame of the block that immediately contains the statement. In the previous example, the assignment of L1 to L assigns a designator to the statement labeled L1 as part one of L, and assigns a designator to the current stack frame of procedure A as part two of L. The execution of a subsequent GOTO statement uses the stack frame designator only if the GOTO statement is executed in a block activation other than that indicated by the label value. For example:

A: PROCEDURE;
   DECLARE L LABEL;
      .
      .
      .
   L1:
      .
      .
      .
   L = L1;
      .
      .
      .
   GOTO L;
      .
      .
      .
   B: PROCEDURE;
      .
      .
      .
      GOTO L;
           .
           .
           .

In this example, execution of the first GOTO statement simply transfers control to L1 because it occurs within the same block activation in which L1 was assigned to L (and consequently, the stack frame component of L designates the stack frame that is current when the GOTO statement is executed). However, execution of the second GOTO statement occurs within a block activation other than that whose designator was assigned to L. Execution of the second GOTO statement first uses the stack frame designator of L to terminate the block activation of B and restore the block activation of A. The second GOTO statement then transfers control to the statement labeled L1. If A were a recursive procedure with more than one activation, the statement GOTO L in B would restore the most recent activation of A. Note that a label variable that is given L as a value will denote the activation of A current at the moment L is assigned, which may not be A's most recent activation. Use of a label variable after its associated block has exited may cause unpredictable results.

A single, optionally signed integer constant in the range -32768 to +32767 may be used to subscript a label. An array of labels is declared by the occurrence of subscripted labels. The elements of the array are all the subscripted labels having the same name and appearing within the same block. The highest subscript used is the upper bound of the array. The lowest subscript used is the lower bound of the array. The number of integers between the lower bound and the upper bound, inclusive, is the extent of the array. The array contains one element of each integer in the extent, although there may not be a subscripted label corresponding to the element. If you refer to an undefined element, the result is unpredictable. For example:

      GOTO CASE(K);
CASE(1):
   .
   .
   .
CASE(2):
   .
   .
   .
CASE(3):
   .
   .
   .
CASE(6):
   .
   .
   .

In this example, CASE is a one-dimensional array of statement labels containing six elements. Elements 4 and 5 are undefined and should not be used. Using an undefined element produces unpredictable results.

Label prefixes on PROCEDURE, FORMAT, BEGIN, and ENTRY statements cannot be subscripted.

Because the label array is declared by label prefixes, it cannot also be declared as a LABEL variable by appearing in a DECLARE statement.

Label values may be assigned, compared for equality or inequality, passed as arguments, and returned from functions, but no calculations or conversions can be performed on them. You may specify potential label values that can be assigned to a LABEL variable. They cannot be transmitted in stream I/O.

Parent topic: Data Types


Entry Data

Entry constants and variables are used to invoke procedures through specific entry points. Entry values specify entry points and block activations of procedures.

  • Entry Constants
  • Entry Variables
  • Entry Values
Parent topic: Data Types


Entry Constants

Entry constants are declared by labels or by PROCEDURE or ENTRY statements.

The leftmost label on a PROCEDURE statement is a declaration of the primary entry point of a procedure. Secondary entry points are established by the ENTRY statement. Names of external procedures that are not part of the compiled module must be declared using an ENTRY attribute and, if they are functions, a RETURNS attribute. For example:

DECLARE E ENTRY(FIXED BINARY(15), POINTER);
DECLARE F ENTRY((5) FLOAT DECIMAL(7))
   RETURNS(FLOAT DECIMAL(7));

In this example, E is declared as a procedure name that requires two arguments and that must be called as a subroutine by a CALL statement. F is declared as a procedure name that must be referenced as a function. F requires an array of five Float Decimal(7) values as its arguments and returns a Float Decimal(7) result.

Procedures, other than external procedures that are not part of the compiled module, are declared by their PROCEDURE statement and cannot be declared in a DECLARE statement.

Failure to declare a referenced external procedure that is part of another program module results in error messages from the Compiler.

Parent topic: Entry Data


Entry Variables

Entry variables are variables, including parameters, that take entry values.

The ENTRY attribute together with the VARIABLE attribute can be used to declare variables whose values are entry values. The ENTRY attribute can be used in a RETURNS attribute to indicate that a function returns entry values. For example:

A: PROCEDURE;
      .
      .
      .
   DECLARE E ENTRY VARIABLE;
      .
      .
      .
   E = A;

In this example, E is an entry variable that is capable of being assigned any entry value. The assignment causes the value of E to become a descriptor of the procedure named A.

Any parameter attribute or RETURNS attribute specified as part of an ENTRY attribute has no effect on the values that can be assigned to the ENTRY variable. However, when the entry variable is called, the value that it currently holds must designate a PROCEDURE statement whose parameters and RETURNS option match those given in the declaration of the entry variable.

In the previous example, a program that calls E as a function or calls E with arguments is invalid and produces unpredictable results.

Parent topic: Entry Data


Entry Values

Like a label value, an entry value is a descriptor containing two parts. The first part designates an entry point of a procedure, and the second part designates a stack frame of the block in which the procedure is declared. The second part of an ENTRY value that designates an external procedure is null.

The second part of the entry value is relevant only when there is more than one activation of a given procedure, as is the case with recursive procedures; otherwise, an entry value can be considered simply as a designator of an entry point.

Entry values can be assigned, compared for equality or inequality, passed as arguments, and returned from functions, but no calculations or conversions can be performed on them, and they cannot be transmitted in stream I/O.

The following discussion explains the second part of the entry value, called the stack frame designator.

  • The Stack Frame Designator
Parent topic: Entry Data


The Stack Frame Designator

If a procedure references variables local to its containing procedure, the inner procedure must be given a designator to the outer procedure's stack frame for it to be able to access the outer procedure's variables. The designator to the outer procedure's stack frame is the stack frame designator.

Except when the outer procedure has been activated recursively, only one stack frame for the outer procedure exists. The existing stack frame is the one that is always used when the inner procedure references variables declared in the outer procedure.

If the outer procedure has been activated recursively, the entry value used to call the inner procedure determines which stack frame is to be used when the inner procedure references the outer procedure's variables. For example:

A: PROCEDURE RECURSIVE;
   DECLARE X FIXED BINARY(15);
   DECLARE E ENTRY VARIABLE STATIC;
   IF FIRST-TIME
      THEN E=B;
      ELSE CALL F;
   CALL G;
.
.
.
B: PROCEDURE;
      .
      .
      .
      X=5;

In this example, assume that A calls G and that G calls A, then A calls F, and F calls the entry value held by E. When E is called, an activation of B results, because B was assigned to E. When that activation of B references X, two stack frames containing an instance of X exist. Two stack frames exist because two calls of A are still active. However, because the first of these two activations of A assigned B to E, E contains a designator to the first stack frame of A. Consequently, B assigns 5 to the first instance of X. If B were called directly from A, B would always use the most recent stack frame of A when referencing X.

An older stack frame is used only when an entry name is assigned to an entry variable or passed as an argument to an entry parameter. When the entry name is thus passed or assigned, the current stack frame of its containing block is assigned as the second component of the entry value produced by that assignment.

If the procedure name being assigned or passed as an argument is not declared within the block that is assigning or passing it, but is declared in a containing block, the containing block's stack frame is found using the same principle as was used to find X in the previous example. Once found, a designator to that stack frame is assigned as part two of the entry value.

Each stack frame for a block A has a designator to a stack frame of the block that contains A. That designator is the designator that was supplied as the second part of the entry value used to activate A. Unless the activation of A was the result of calling an entry variable or entry parameter, and unless recursion has been used, the stack frame thus designated is also the immediately preceding stack frame.

Parent topic: Entry Values


File Data

A file constant is represented by a file control block, which is an internal data structure maintained by Open PL/I. A file control block can be opened or closed and can thereby be connected to various files and devices known to the operating system. For example:

DECLARE F FILE;

In this example, F is a file constant that designates a file control block. That file control block can be opened, closed, and used to perform I/O on files and devices known to the operating system.

A file variable is represented internally as a longword containing a pointer to a file control block. When evaluated, the value of the file variable is the address of the associated file's control block.

A file variable is capable of being assigned any file value; it is declared using both the FILE and VARIABLE attributes. For example:

DECLARE G FILE VARIABLE;
DECLARE F FILE;
   .
   .
   .
   G = F;

In the previous example, G is a file variable assigned the value of the file constant F. After the assignment, operations on G are equivalent to operations on F because they both designate the file control block belonging to F.

File values may be assigned, compared for equality or inequality, passed as arguments, or returned from functions; however, no calculations or conversions can be performed on them, and they cannot be transmitted by stream l/o.

Parent topic: Data Types
Related information
File Constants


Arrays

An array is an ordered set of values all having the same data type. Elements of an array are referenced by their position within the array. Each array has a specified number of dimensions and each dimension has a specified lower and upper bound. The default low bound of a dimension is 1.

Array elements are stored in row-major order. The successive elements of a row are stored in adjacent memory locations. In arrays with more than two dimensions, the net effect is that when the elements are accessed in their storage order, the rightmost subscript varies most rapidly.

Examples:

DECLARE A(1:4) FIXED BINARY(15);
DECLARE B(0:3,0:5) FLOAT BINARY(21);
DECLARE C(-2:10) CHARACTER(5);
DECLARE D(25,4,2) POINTER;

In these examples, A is a one-dimensional array capable of holding fixed-point binary values. The lower bound is 1, the upper bound is 4, and the number of elements is 4.

B is a two-dimensional array capable of holding floating-point binary values. Both lower bounds are zero, and the upper bounds are 3 and 5. Therefore, B has 4 rows of 6 columns each.

C is a one-dimensional array capable of holding character-string values each of which has 5 characters. Its lower bound is -2 and its upper bound is 10, giving it a total of 13 elements.

D is a three-dimensional array capable of holding pointer values. Because no lower bounds are given, they are assumed to be 1. The array has a total of 200 elements organized as 25 planes, each of which is 4 rows in length and 2 columns in width.

The maximum number of array dimensions is 8. An array bound may be any number in the range -2^31 to 2^31 -1. Array bounds are also subject to the following restrictions:

  • The lower bound must be less than or equal to the upper bound.
  • The value (upper bound — lower bound) must be less than 2^31 -1.
  • The total size of the array must be less than 2^31 bytes. For information on calculating the size of an individual array element, see your Open PL/I User's Guide.
Note: The particular implementation of PL/I or the underlying operating system may also impose restrictions on the size of an individual data item, or on the total sizes of static and/or automatic data regions. For more information, see your Open PL/I User's Guide.

The bounds of AUTOMATIC, DEFINED, CONTROLLED, or BASED arrays may be specified by integer-valued expressions, as explained in the chapter Storage Classes. The bounds of STATIC arrays must be integer constants. The bounds of parameter arrays can be either integer constants or an asterisk (*). If an asterisk is given as the bound of a parameter array, it represents both the lower and upper bound and means that the actual bounds of the corresponding array argument are to be used as the bounds of the array parameter. For example:

DECLARE A(0:5) FIXED BINARY;
CALL P(A);
   .
   .
   .
P: PROCEDURE(X);
   DECLARE X(*) FIXED BINARY;
      .
      .
      .

During the call of P in the previous example, the bounds of X are (0:5), and any reference to X is a reference to A.

The elements of an array are referenced using as many subscripts as the array has dimensions. For example:

DECLARE A(-2:5,4,3) FIXED BINARY;

In this example, a reference to A (-2 ,1,1) is a reference to the element in the first column of the first row in the first plane. A reference to A (3,2,1) is a reference to the element in the first column of the second row in the sixth plane.

A subscript of an array must be an integer valued expression. The use of fixed-point fractions or floating-point values as subscripts results in an error message from the Compiler. However, such values can be converted to integer values by use of the TRUNC, CEIL, FLOOR, or ROUND built-in functions.

Each subscript must lie within the range specified by its corresponding lower and upper bound. Unless subscript range checking has been requested, the Compiler does not produce code to check the range of subscript values. If checking is requested, any subscript that exceeds its range results in a signal of the ERROR condition.

Subscripted references to array elements can be used in any context that permits a variable reference.

A cross-section of an array may be referenced by using an asterisk as a subscript. The asterisk refers to the entire range of the corresponding dimension (lower bound through upper bound). In the previous example, a reference to A (*,1,1), refers to the first-row, first-column elements in all eight planes. A reference to A ( *, *,*), refers to all 96 elements of the array.

Array cross-sections may be transmitted in stream or record I/O, passed as arguments, and assigned to other arrays of the same size and shape.

Parent topic: Data Types
Related information
Storage Classes


Structures

A structure is a hierarchically ordered set of values that may be of different data types. The immediate components of a structure are called members of the structure. A structure that is itself a member of another structure is called a substructure. A structure that is not a substructure is called a major structure.

The hierarchical organization of a structure is specified by using level-numbers, as shown in the following example:

DECLARE 1 S,
      2 A FIXED BINARY,
      2 B FLOAT BINARY,
      2 T,
            3 P POINTER,
            3 Q CHARACTER(10);

In this example, S is a major structure, also called a level-one structure. All major structures must have a level-number of 1. The members of S are A, B, and T. T is a substructure with members P and Q.

Members normally have a level-number that is 1 greater than their containing structure; however, they may be given any level-number that is greater than the level-number of their containing structure and less than the level-numbers they contain. For example:

DECLARE 1 S,
      20 A FIXED BINARY,
      20 B FLOAT BINARY,
      20 T,
            30 P POINTER,
            30 Q CHARACTER(10);

The structure shown in this example is equivalent to the structure shown in the example immediately preceding it.

An entire structure may be transmitted in stream or record I/O, passed as an argument, or assigned to another structure of identical size and shape and having members of corresponding identical data types, but no conversions or calculations can be performed on entire structures.

If a structure contains one or more members with a variable size, place all such members at the end of the structure following all the members with a fixed size. This placement improves the addressing of the fixed size members.

Members of structures can be referenced in any context that permits a reference to a variable. If a member's name is not otherwise declared in the same scope (that is, in the same block or containing block), the member may be referenced by its name alone.

The name of a member must be unique within its immediately containing structure, but may be used as the name of members of other structures or as the name of a nonmember. If a member's name has been used for more than one object, each reference to the member must be sufficiently qualified by the names of its containing structures to uniquely identify the intended member. In a qualified reference, the names used are listed in their hierarchical order, separated by periods. For example:

DECLARE        A FIXED BINARY;
DECLARE        1 S,
                  2 A FLOAT BINARY,
                  2 T,
                     3 A POINTER;

In this example, a reference to A is a reference to the fixed-point variable. A reference to S.A is a reference to the floating-point variable. A reference to T.A or S.T.A is a reference to the pointer variable.

Use of the major structure name as a qualifier is recommended. It is also advisable to avoid using the same member name more than once anywhere within the major structure or any contained structures. For more information, see the section Reference Resolution in the chapter References.

A structure may have the UNION attribute applied to it, which causes all immediate members of that structure to occupy the same memory locations. For more information, see the chapter Declarations and Attributes.

Parent topic: Data Types
Related information
Reference Resolution
Declarations and Attributes


Arrays of Structures

Structures, like other variables, can be declared as arrays and can contain arrays as members. For example:

DECLARE 1 S(5),
      2 A FIXED BINARY,
      2 B(4) FLOAT BINARY,
      2 T(3),
            3 P POINTER,
            3 Q(6) CHARACTER(10);

In this example, S is an array of 5 structures. Each structure contains a fixed- point member followed by an array of 4 floating-point values, followed by an array of 3 substructures. Each substructure contains a pointer variable followed by an array of 6 character-string variables. The entire structure contains 5 occurrences of A, 20 occurrences of B, 15 occurrences of T, 15 occurrences of P, and 90 occurrences of Q.

Each member of a structure array is itself an array because there exist as many instances of the member as there are elements in the structure array. If a member is an array in its own right because it has its own dimension information (as do B, T, and Q in the previous example), the array inherits the additional dimensions from its containing structures. For instance, in the previous example, Q is a three-dimensional array whose bounds are (5,3,6).

Any member of a dimensioned structure is an array and must be referenced using a subscript for each of its dimensions. The subscripts may be written anywhere within the structure-qualified reference, but it is preferable to write each subscript immediately following the name to which it applies. Using the previous example to illustrate this recommended programming practice:

S(K) .A | is a reference to the Kth element of A
S(K) .B(J) | is equivalent to B (K, J)
S(K) .T(J) .Q(I) | is equivalent to S.T.Q (K, J, I) or S.T(K,J) .Q(I) or S(K,J, I) .T.Q,

It is not possible to use an asterisk to reference an entire extent (cross section) of a structure array.

Members of dimensioned structures can be used only as arrays in stream I/O and as arguments to array parameters whose bounds have been specified as asterisks. They cannot be assigned, used in record I/O, used in ADDR or DEFINED, or passed to parameters with constant bounds.

Subscripted references to members of dimensioned structures can be used in any context that permits a variable reference.

Parent topic: Data Types


Data Size and Alignment

Refer to your Open PL/I User's Guide for the size and alignment of each Open PL/I data type.

Data not contained in a structure or array is allocated on a word or double word boundary, except for Character(1) and Bit(1) aligned data, which is allocated on a byte boundary.

  • ALIGNED and UNALIGNED Attributes
Parent topic: Data Types
Related information
Open PLI Users Guide


ALIGNED and UNALIGNED Attributes

ALIGNED and UNALIGNED are optional data type attributes that control the storage boundary of data.

ALIGNED allows the Compiler to align the data on an implementation-defined storage boundary, with the possible side effect that more bits of storage are used than specified by the declared length. (Refer to your Open PL/I User's Guide for more information.)

UNALIGNED allows the Compiler to align the data on the next byte boundary (or, in the case of fixed-length bit strings, the next bit) rather than on implementation-defined storage boundaries. This can reduce storage requirements.

ALIGNED or UNALIGNED can be specified for scalar, array, or structure variables. The application of either attribute to a structure is equivalent to applying the attribute to all contained elements that do not have explicit alignment declaration. Operations on ALIGNED data tend to be more efficient; operations on UNALIGNED data usually are slower. They are considered part of the data type for purposes of argument/parameter matching and storage sharing.

The UNALIGNED attribute is the default for non-varying character data types and bit data types, while ALIGNED is the default for all other data types.

The UNALIGNED attribute has no effect with an AREA variable, which is always aligned on an 8-byte boundary.

See the Open PL/I User's Guide for specific alignment of varying character strings.

Parent topic: Data Size and Alignment
Related information
Parameter Storage Class
Storage Sharing
Bit-String Data


Storage Classes

  • Introduction
  • Automatic Storage
  • Static Storage
  • Based Variables
  • Controlled Variables
  • Defined Variables
  • Parameter Storage Class
  • Storage Sharing
Parent topic: Open PL/I Language Reference Manual


Introduction

Every variable has a storage class that determines how and when storage is allocated for it. A variable's storage class specifically determines whether storage will be allocated for it at compile time or dynamically during program execution.

Storage classes are declared for all variables, except those used as parameters, using one of the following attributes:

  • AUTOMATIC
  • STATIC
  • BASED
  • CONTROLLED
  • DEFINED

If no storage class is specified for a variable declared in a procedure, other than a parameter variable, the default is AUTOMATIC. If a variable is declared outside the scope of all external procedures in a source module, the default storage class is STATIC.

A parameter shares storage with its argument. As such, the storage class is ultimately determined by that of the associated argument. For convenience, a parameter may be considered to have a distinct "parameter" storage class.

A variable's storage size is determined by its extents. A string variable's extent is its declared length. An array variable's extents are determined from the number of its dimensions and the range of its subscript bounds. The extents of both types of variables are evaluated when storage is allocated for the variable. The permitted forms for extents differ for each storage class and are described during the discussions of each storage class.

Parent topic: Storage Classes


Automatic Storage

Storage for an automatic variable is allocated with each activation of the procedure or the BEGIN block in which the variable is declared. Storage is allocated within the stack frame that represents that block activation. If a block is activated recursively, each of its stack frames contains a distinct instance of all automatic variables declared in that block.

When a block activation ends, its stack frame is popped from the stack, thereby freeing the storage of all automatic variables allocated within it. This phenomenon normally occurs when a procedure returns to its caller or when a BEGIN block executes its END statement; however, it also occurs when a GOTO statement transfers control back to a previous block activation. In the latter case, all block activations between the one to which control is transferred and the one in which the GOTO was executed are ended. Their stack frames are popped from the stack, releasing the storage for all of their automatic variables. The INITIAL attribute can be specified in the declaration of an automatic variable to initialize the variable.

Extents of automatic character string and array variables may be specified as integer valued expressions, provided these do not contain references to other non-static variables declared in the same block. Extent expressions for these automatic variables are evaluated each time the containing block is activated. The extent expression values are saved in the stack frame and effectively fix the size of the automatic variable for that block activation. Subsequent assignment to a variable used as an extent does not affect the size of the associated automatic variable. For example:

DECLARE STRING_SIZE FIXED;
   .
   .
   .
COPY: BEGIN;
DECLARE TEXT CHARACTER(STRING_SIZE);

When the BEGIN block in this example is activated, the extent of TEXT is evaluated. The variable is allocated storage depending on the value of STRING_SIZE, which must be a valid integer value. For example:

DECLARE A(N) FIXED;
   .
   .
   .
N = 10; /* WILL NOT AFFECT THE SIZE OF ARRAY A */

In this example, the size of A is determined upon entry to the containing block by evaluating N and storing its value in the stack frame. The assignment to N does not change the size of A. Upon entry to the block, N must have a correct value and must not be a non-static variable declared in this block. Use of the HBOUND built-in function within this block activation would return the original value of N that was saved in the stack frame.

Parent topic: Storage Classes
Related information
INITIAL
HBOUND Function


Static Storage

Storage for a static variable is allocated by the Compiler and/or linker prior to program execution. Storage remains allocated throughout program execution.

Only one instance of a static variable's storage is allocated, regardless of whether the variable is declared in a recursive procedure. Values assigned to a static variable are retained between calls to the procedure in which the variable is declared.

All extents specified for static character string, 8-bit area variables, and array variables must be constants.

Static variables can be declared with the INTERNAL or EXTERNAL attribute. If neither attribute is specified, INTERNAL is assumed.

An internal static variable is known in its containing block and in all contained blocks, except those blocks in which the same name is redeclared. This is the normal scope rule that applies to all other variables.

An external static variable is known in its containing block and in all contained blocks, except those blocks in which the same name is redeclared. However, all declarations of the same name that have the EXTERNAL attribute, including those in separate modules of the program, share the same storage and must specify identical attributes, including any initial values. External static variables are known and shared by all program modules in a manner similar to the common variables of FORTRAN, except that each external static variable is shared independently of others.

Parent topic: Storage Classes
Related information
INTERNAL
EXTERNAL


Based Variables

The BASED attribute defines a template for storage that will be accessed through the use of a locator. A based variable differs from all other variables in the sense that it is a description of storage, but does not have storage of its own. Since it has no storage, it has no address. For example:

DECLARE X CHARACTER(30) BASED;
DECLARE P POINTER;
   .
   .
   .
P->X = 'ABC';

In this example, assume that an address or pointer value has been assigned to P. The reference P–>X is called a pointer qualified reference, and it enables assignment to the storage addressed by P as if that storage contained a character-string variable like X.

A pointer value can be obtained in two primary ways: from the address of a variable's storage as calculated and returned by the ADDR built-in function, or from the address of storage obtained dynamically by the ALLOCATE statement. For example:

DECLARE K FIXED BINARY(15);
DECLARE X(5) FLOAT BINARY;
DECLARE Y FLOAT BINARY BASED;
DECLARE P POINTER;
   .
   .
   .
P = ADDR(X(K));
P->Y = 10;

In this example, P is assigned the address of X (K) , which is returned by the ADDR built-in function. The second assignment places the value 10 in the storage location given by P in a manner prescribed by the template Y, effectively assigning 10 to X (K) .

A third way to obtain a pointer value is with the POINTER built-in function, which may be used to convert an area offset value to a pointer.

The indiscriminate use of pointers to access the storage of other variables should be discouraged because of the possibilities of unexpected assignment side effects and because the excessive use of pointers makes a program hard to read. Please also note that no checking is performed to ensure that the based variable provides a data description compatible with the declaration of the reference storage. For instance, the statement P–>Y = 10 might produce undesirable results if Y were declared as a data type incompatible with the data type of elements in X. For a discussion of storage sharing using based variables, see the section Storage Sharing.

The ALLOCATE statement uses a based variable to allocate a block of storage that can later be accessed by a based variable together with the locator returned by the ALLOCATE statement. For example:

DECLARE P POINTER;
DECLARE X(C,N) CHAR BASED(P);
N = 10;
C = 10;
ALLOCATE X SET(P);
   .
   .
   .
P -> X(10,5) = 'A';

In the preceding example, the ALLOCATE statement allocates a storage block of sufficient size to hold a two-dimensional array of 100 one-byte character values and assigns a pointer to that block of storage to P . P–>X thereafter is a reference to that block of storage as an array of 100 one-byte character values.

Based variables can be subscripted just like any other variable. Referring again to the previous example, the statement P–> X (10,5) = ' A' assigns the character 'A' to the element in row 10 and column 5 of the array qualified by P. Since the pointer variable may also be an array, it too can be subscripted. For example:

DECLARE P(3) POINTER;
DECLARE X(10) FLOAT BASED;
   .
   .
   .
ALLOCATE X SET(P(K));

In the preceding example, P (K)–>X refers to the entire array of ten floating-point elements qualified by the Kth pointer element of P. Likewise, P (K) –>X (J) refers to the Jth element of the floating-point array qualified by the Kth element of pointer array P.

The ALLOCATE statement is the only context in which a based variable can be used without an explicit or implicit locator qualifier. In this context, the based variable is used to describe how much storage is to be allocated.

Implicit locator qualification is a shorthand notation that can be used in cases where many of the references to a based variable use the same pointer. For example:

DECLARE X(10) FLOAT BASED(P);
DECLARE P POINTER;
   .
   .
   .
ALLOCATE X SET(P);

Because X was declared to be based on P in the previous example, unqualified references to X such as X (K) , X (5), or X are implicitly qualified by P and are equivalent to P–>X (K) , P–>X (5) , and P–>X. Any explicit qualification, such as Q–>X, may be used to temporarily override the implicit qualification and is unaffected by the specification of P in BASED (P) .

The extents of a based variable may be specified as integer valued expressions. The extents are evaluated for each allocation of the variable and for each reference of the variable. The extents are not captured when storage is allocated by an ALLOCATE statement. The extent expression can reference variables declared in the same block, as long as those variables have a value before the based variable is referenced. Changing the value of a variable referenced by an extent expression changes the extent of the based variable. For example:

DECLARE X(N) CHARACTER(1) BASED;

N = 10;
ALLOCATE X SET(P);
   .
   .
   .
N = M;
P->X(5) = 'A';

In this example, the ALLOCATE statement allocates an array of ten elements. The value of M must be greater than or equal to five and less than or equal to ten; otherwise, the reference to P–>x (5) is invalid and may cause unpredictable results.

A block of storage previously allocated by an ALLOCATE statement can be freed by a FREE statement. For example:

FREE P->X;

Once freed, the storage can no longer be accessed, and any attempt to use a pointer such as P that points to the block produces unpredictable results.

Note:

The storage obtained by an ALLOCATE statement is freed only by an explicit FREE. If a program continually allocates memory without freeing it, the program may run out of space at run-time.

Used with the ALLOCATE statement, based variables are powerful tools for applications in which the size of arrays or strings is not known at block entry and must be determined at run-time. Based variable allocations also supply a means for the dynamic creation of graph structure nodes (which may be linked by pointers to produce list and tree structures). See the example of a based structure in the section Block Activation and Recursion.

It is desirable to restrict the extent of based variables to constant values whenever possible to avoid unexpected side effects and to improve program readability. If the extent must be variable, it is preferable to avoid the use of extent expressions when declaring based variables for the same reasons. The size of the based variable is evaluated for each reference to the variable.

Parent topic: Storage Classes
Related information
POINTER Function
Storage Sharing
Block Activation and Recursion


Controlled Variables

The CONTROLLED attribute specifies a variable whose storage is dynamically allocated and freed in generations, independent of block boundaries. Controlled variables are allocated only when specified in an ALLOCATE statement. After being allocated, a controlled variable remains allocated until a FREE statement names the variable.

A reference to a controlled variable refers to the generation of the variable created by the most recent ALLOCATE statement. The FREE statement frees the most recent generation of the controlled variable, exposing the previous generation. For example:

DECLARE STACK (STACK_ITEM_SIZE) CHAR(32) CTL;
DECLARE STACK_ITEM_SIZE FIXED BIN;
DECLARE I FIXED BIN;

   /* Push a first stack item. */
   STACK_ITEM_SIZE = 4;
   ALLOCATE STACK;

   DO I = 1 TO STACK_ITEM_SIZE;
      STACK(I) = CHAR(I) || '_1';
   END;

   /* Push a second stack item. */
   STACK_ITEM_SIZE = 3;
   ALLOCATE STACK;

   DO I = 1 TO STACK_ITEM_SIZE;
      STACK(I) = CHAR(I) || '_2';
   END;

   PUT SKIP LIST ('Print second item on the stack');
   PUT SKIP LIST (STACK);

   /* Pop the last element on the stack. */
   FREE STACK;

   PUT SKIP LIST ('Print first item on the stack');
   PUT SKIP LIST (STACK);

   /* Pop the last element on the stack.
      The stack is empty now. */
   FREE STACK;

CONTROLLED variables can be declared with asterisk (*) extents, and when such a variable is allocated, its extents can be made explicit by the use of the ALLOCATE statement with specified attributes. CONTROLLED variables can also be declared with explicit extents (constant or variable), and these explicit extents can be overridden by use of the ALLOCATE statement with specified attributes.

It is also possible to specify attributes with asterisk extents in the ALLOCATE statement. This causes the extents to be copied from the corresponding extents used for the previous allocation of the same CONTROLLED variable. If an asterisk is specified in the ALLOCATE statement for one dimension of a variable, it must be specified for all dimensions of that variable.

If level numbers are specified, the first variable in the ALLOCATE statement must be specified with a level-num of 1 and be declared as a level-1 structure, and in this case, all members of the structure must be included in the ALLOCATE statement just as they appear in the declaration of the structure.

Any bound, length, size, or initial value specified in the ALLOCATE statement overrides the corresponding attribute specified in the declaration of the variable. A bound, length, or size can be specified in the ALLOCATE statement with an asterisk, and, in this case, the bound, length, or size is taken from the current generation of that CONTROLLED variable. If a bound, length, size, or initial value specified in the ALLOCATE statement contains a reference to the variable being allocated, the reference is to the current generation of the variable.

Evaluations of expressions for bounds, lengths, sizes, and initial values during the execution of the ALLOCATE statement are done according to the normal rules for PL/I references, and must be capable of logical execution (that is, without circularity). Evaluations depending on the existence of a prior generation of a variable require that that generation has previously been allocated.

Controlled variables provide an easy way to implement a stack, because only the most recent generation is available to the program. The ALLOCATE statement is equivalent to a push operation and the FREE statement is equivalent to a pop operation. The ALLOCATION built-in function is used to determine the number of generations of a controlled variable that are available.

Examples

DECLARE 1 A CONTROLLED,
     2 B CHAR(*),
     2 C CHAR(20),
     2 D(2) FIXED BIN(31),
     2 E(4,4) CHAR(*),
     2 F FIXED BIN(31);
...
ALLOCATE 1 A, 2 B CHAR(12), 2 C, 2 D(6), 2 E CHAR(3), 2 F INIT(128);
...
ALLOCATE 1 A, 2 B CHAR(12), 2 C CHAR(10), 2 D(D(1)), 2 E CHAR(3), 2 F;

In this example, the structure A is first allocated with member B of length 12, with array member D with dimension (6) instead of the declared (2), array member E with its declared dimensions of (4,4) and element lengths of 3, and member F with an initial value of 128. The second generation of A is allocated with member C of length only 10 and with the dimension of array member D the value contained in the first generation of A.D(1).

DECLARE X(*,*) CONTROLLED;
ALLOCATE X(3,7);
ALLOCATE X(*,*);

In the second allocation of array X, the bounds are implicitly (3,7), as derived from the previous allocation.

For CONTROLLED parameters, CONTROLLED must be explicitly stated in the parameter descriptor for the ENTRY declaration. This is required by the PL/I language specification. For example, if you compile and link together the following two procedures:

t.pl1
 TSTENTM: PROC OPTIONS(MAIN);

   DCL   N  CHAR(10) CONTROLLED;

   DCL  TSTENT ENTRY(CHAR(10));

   ALLOCATE N;
   N = 'CONTROLLED';

   CALL TSTENT(N);
 END;

t1.pl1
 TSTENT:  PROC(N);
   DCL   N  CHAR(10) CONTROLLED;
   PUT SKIP LIST ('N = ',N);
   RETURN;
 END;

Upon execution you will get:

*** Condition ERROR raised
*** Unhandled condition SIGSEGV at PC=004011AE
N =

To avoid this, add the controlled attribute to the ENTRY declaration:

DCL  TSTENT ENTRY(CHAR(10)CTL);
Parent topic: Storage Classes


Defined Variables

A defined variable is one for which no storage is allocated. Instead, the variable shares the storage of a specified basis variable.

A defined variable is declared with the DEFINED attribute, which also specifies the basis variable. Any reference to the defined variable is a reference to all or part of the storage of the basis variable.

When the declaration of a variable includes the DEFINED attribute, that variable's description applies to the storage associated with the basis variable. For example:

DECLARE A(5) CHARACTER(1);
DECLARE X CHARACTER(5) DEFINED(A);

In this example, X is a defined character-string variable of length 5. X shares storage with, and is an alternate description of, the array A. Similarly, the following statement:

X = 'abcde';

assigns 'a' to A (1) , 'b' to A(2), and so on.

The extents of a defined variable can be integer valued expressions. They are evaluated upon block entry and stored in the stack frame just like the extents of automatic variables. Such an extent expression must not contain a reference to any non-static variable declared in the same block.

For additional information on defined variables, see the section Storage Sharing, which discusses the rules for giving alternate descriptions of storage.

Parent topic: Storage Classes
Related information
Storage Sharing


Parameter Storage Class

A parameter shares storage with its argument. As such, the storage class is ultimately determined by that of the associated argument. Technically, the parameter variable itself is an AUTOMATIC variable containing the address of the corresponding argument. For convenience, a parameter may be considered to have a distinct "parameter" storage class. For example:

DECLARE X FLOAT;
CALL P (X);
   .
   .
   .
P: PROCEDURE (Y);
      DECLARE Y FLOAT;

In this example, X is an argument and Y is a parameter variable. A parameter variable is declared within a procedure declaration and receives a value when that procedure is invoked. Simple Open PL/I variable arguments are passed by reference.

A parameter has a data type, perhaps a data type with extents, and in the simplest case, an argument passed to the parameter will have the same data type and extents as the parameter. If this is not the case, Open PL/I will, whenever possible, convert the argument to a value with the same data type and extents as the parameter and pass that value to the parameter.

In the absence of specifications to the contrary, when a variable is passed as an argument to a parameter with matching data type and extents, the argument is passed "by reference." This means that it is the address of the actual variable itself that is passed as the argument, and the parameter is sharing storage with this variable. Hence, any assignment to the parameter is actually changing the argument variable itself.

In other cases — that is, when the argument is a variable whose data type and extents do not match the parameter, or when the argument is an expression, a constant, a function reference, or a simple variable enclosed in parentheses — the argument is passed "by value." This means that the value of the argument is converted as described above and stored in a temporary location. It is the address of this temporary location that is passed as the argument. Hence, any assignment to the parameter can have no effect on any variable in the calling procedure.

The precision of arithmetic data is part of its data type. This means that a Float Decimal(7) variable cannot be passed by reference to anything except a Float Decimal(7) parameter. The VARYING and ALIGNED attributes, as well as the declared string length, are part of a string variable's data type and must match those of the corresponding parameter for the parameter to share storage with the actual argument (true pass-by-reference). A picture variable can be passed by reference only if the corresponding parameter has an identical picture. The ALIGNED and UNALIGNED attributes of non-string arguments and parameters must match.

The BYVALUE attribute is an argument-passing attribute that indicates that the value and not the address of the parameter has been passed to the procedure.

An array parameter with constant extents can be passed only those array arguments that have identical constant extents and an identical data type. A parameter structure can be passed only a structure or substructure of identical size, shape, and component data types. Array or structure arguments cannot be passed by value.

The ANY attribute is an argument-passing attribute that specifies, for a parameter, that the corresponding argument can be of any data type.

A procedure that has a character or bit-string parameter with a constant length may be called with string arguments of variable length or differing constant length. Since all such arguments are passed by value, they are effectively converted to the length of the parameter. For example:

CALL P(A,(B));

In this example, A is passed by reference if it matches its corresponding parameter and is passed by value if it does not. B is always passed by value.

If the argument is an expression, function reference, built-in function reference, constant, parenthetical variable reference, or a reference to a variable whose data type does not match that of the parameter, the argument is copied to a temporary block of storage in the caller's stack frame and is said to be passed by value. The value of the variable in the caller will not be modified if it is passed by value. Actually, the address of the temporary storage is passed, and the parameter shares the storage allocated to the temporary storage.

The extents of a parameter can be either integer constants or asterisks (*). If the parameter's extents are integer constants, any argument to be passed by reference must have identical constant extents. If the parameter's extents are asterisks, its corresponding argument may have extents of any value. In the latter case, the extents of the parameter are those of its corresponding argument. For example:

DECLARE A(10) FLOAT;
DECLARE B(25) FLOAT;
   .
   .
   .
CALL P(A);
   .
   .
   .
CALL P(B);
   .
   .
   .
P: PROCEDURE(X);
   DECLARE X(*) FLOAT;

During the first call in this example, the extents of X are (1:10). During the second call, they are (1:25).

Parent topic: Storage Classes
Related information
BYVALUE
ANY


Storage Sharing

Open PL/I provides two storage classes that are explicitly designed to permit storage locations to be shared by several variables. These storage classes are BASED and DEFINED. (Use of the UNION attribute also allows variables to explicitly share storage.)

Based variables are allocated no storage when they are declared. Instead, they serve to determine storage to be allocated by an ALLOCATE statement or to describe storage qualified by a pointer reference.

Defined variables use the storage of a specified basis variable. A defined variable is declared with the DEFINED attribute, which also specifies the basis variable.

A defined variable and its basis reference must satisfy one of the following criteria in order to share storage:

  1. All variables sharing storage have identical data types.
  2. All variables sharing storage are nonvarying character strings and therefore are suitable for character-string overlay defining.
  3. All variables sharing storage are unaligned bit strings and therefore are suitable for bit-string overlay defining.

A variable is suitable for overlay defining if it consists entirely of characters or bits that are packed into adjacent storage without gaps. (Gaps can be caused by the alignment of data in user-defined structures.)Variables suited for overlay defining are arrays, structures containing only the required type of string data, or scalar string variables. For example:

DECLARE X(4,4) CHARACTER(1);
DECLARE Y(16) CHARACTER(1) DEFINED(X);
DECLARE Z CHARACTER(5) DEFINED(X);
DECLARE 1 S BASED,
   2 A CHARACTER(8),
   2 B CHARACTER(8);

In this example, X has a block of storage containing 16 characters. The entire block is shared by Y, but Z shares only the first 5 characters of the block. S could be used to access all 16 characters, while S.A could be used to access the first 8, and S.B could be used to access the last 8. A based character string of more than 16 characters would produce undefined results, but a string of 16 or fewer characters could be used. A similar example could be constructed using all unaligned bit data.

Storage sharing of other data types requires that the data types match exactly, but an element of an array can be shared with a nonarray variable of the same data type. Similarly, a member of a structure can be shared with a nonmember of the same data type.

Members of structures that have the attribute UNION also share physical storage locations with one another. A UNION is a variation of a structure in which all immediate members occupy the same physical storage location. Unions provide capabilities similar to those of defined variables. The UNION attribute, which can be used only in conjunction with a level number in a structure declaration, signifies that all immediate members of the major or minor designated structure occupy the same storage. An immediate member is any member having a level number greater than its containing structure but not greater than the level number of its fellow members. Typically, an immediate member has a level number that is one greater than its containing structure. (For more information on this attribute, see the section Union.)

Arrays can share storage with other arrays only if they have the same data type and/or are equivalent left-to-right. Structures can share storage with other structures only if they are equivalent, left-to-right, to the structure whose storage is being shared.

Left-to-right equivalence means that the sharing structures must be valid descriptions of the left part of the storage being shared. To be a valid description of the left part of storage, the sharing structures must have identical members up to and including all members contained anywhere within the last level-two item being shared. If any part of a level-two item is to be shared, all of it must be shared. For example:

DECLARE   1 S,  DECLARE  1 T BASED,  DECLARE  1 U BASED,
          2 A,           2 A,                 2 A,
          2 B,           2 B,                 2 B,
          3 C,           3 C,                 3 C;
          3 D;           3 D;
          2 E;

In this example, a reference to T.B.C is a valid reference to S.B.C, but a reference to U.B.C is not valid, because the declaration of U does not describe the entire level-two item S.B.

A picture variable can share storage only with other picture variables that have identical pictures.

As is the case for argument/parameter matching, the ALIGNED, UNALIGNED, and VARYING attributes and the declared length of a string variable are part of its data type and must match, unless the strings qualify for string overlay sharing.

The base, scale, and precision of arithmetic variables must always match if they are to share storage.

Parent topic: Storage Classes
Related information
Union


Declarations and Attributes

  • Introduction
  • Label Prefixes
  • DECLARE Statements
  • Attributes of DECLARE Statements
Parent topic: Open PL/I Language Reference Manual


Introduction

All variables in an Open PL/I program (except those under the control of the DEFAULT statement) must be declared. Each name, except the name of a built-in function, must be declared using a DECLARE statement (or if it is a label, by using the label as a statement prefix).

Each declaration is associated with a scope or region of the program in which a reference to the associated name is valid. The scope of a declaration includes the block in which it is declared and all nested blocks, except those in which the name has been redeclared.

Identifier attributes used in DECLARE statements are specified by either keyword or syntax. A name declared with the EXTERNAL attribute has the same scope rule as any other name, except that the object identified by that name is unique throughout the entire program. All declarations of a given name that have the EXTERNAL attribute identify the same object. Only files, static variables, and names of external procedures can have the EXTERNAL attribute. Files and procedures acquire the attribute by default, but static variables have internal scope unless they are explicitly declared with the EXTERNAL attribute.

A given name cannot be declared more than once within the same block, unless it is declared as the name of a structure member. In that case, the name may be redeclared within the same block, provided no two members at the same level of the same structure have the same name. See the help topic Scope for more information.

Parent topic: Declarations and Attributes
Related information
Scope


Label Prefixes

A label prefix declares a name as a procedure name, format name, or statement label, depending on the type of statement to which the prefix is attached.

A label prefix on a PROCEDURE statement declares a name as a procedure name. The name is declared in the block that contains the PROCEDURE statement, and its scope is that containing block and all blocks contained by the procedure. The declaration lists each parameter referenced by the PROCEDURE statement, as well as the data type specified by any RETURNS option in the PROCEDURE statement. For example:

E: PROCEDURE(A,B) RETURNS(POINTER);
   DECLARE A FIXED BINARY;
   DECLARE B FLOAT DECIMAL;

In this example, E is declared as a procedure name in the block that contains the PROCEDURE statement. The attributes of that declaration are RETURNS(pointer) and ENTRY(fixed binary, float decimal).

The label prefix on a FORMAT statement declares a name as a format name. The name is declared in the block that contains the FORMAT statement and all contained blocks. A format name is not a statement label and cannot be used in a GOTO statement. A format name can be used only in a format statement.

The label prefix of a PROCEDURE or FORMAT statement cannot be sub- scripted.

A label prefix attached to statements other than PROCEDURE or FORMAT statements declares a name as a statement label. The declaration is established in the block that contains the statement to which the prefix is attached. For example, a label prefix attached to a BEGIN statement is declared in the block that contains the BEGIN statement and its scope is that containing block and all blocks contained by the BEGIN statement.

The label prefix of a PROCEDURE or FORMAT statement cannot be sub- scripted; however, label prefixes attached to statements other than PROCEDURE or FORMAT may be subscripted by a single optionally signed integer constant. Within its scope, all occurrences of a given name used in this manner must be subscripted, and all such prefixes collectively constitute a declaration of the name as an array of statement labels. For example:

   GOTO CASE(K);
CASE(1):
   .
   .
   .
CASE(2):
   .
   .
   .
CASE(3):
   .
   .
   .
CASE(6):
   .
   .
   .

In this example, CASE is declared as an array of statement labels whose bounds are (1:6) and whose fourth and fifth elements are undefined. Defining arrays with undefined elements is not recommended, as it produces unpredictable results.

An array of statement labels cannot be used as an array value, but its elements can be used in any context that permits a statement label.

Procedure names, format names, and statement labels cannot be declared in a DECLARE statement in the same block, except that the names may be used as the structure member names.

Names of external procedures that are part of another program module must be declared by a DECLARE statement if they are to be referenced by the current program module. (For more information, see the section Modules.) Only external procedure names can be declared by a DECLARE statement.

Parent topic: Declarations and Attributes
Related information
FORMAT
Modules


DECLARE Statements

A DECLARE statement declares one or more names by giving the attributes or properties of the named objects. A DECLARE statement is not an executable statement. It may appear as a part of a WHEN or OTHERWISE clause in a SELECT statement; anywhere within a procedure or BEGIN block, except as the THEN clause or ELSE clause of an IF statement; or as an ON-unit of an ON statement.

For the sake of readability, all DECLARE statements belonging to a given block should be placed at the beginning of that block, rather than among the executable statements.

  • Recommended Forms
  • The General Form
  • Defaults
  • Attribute Consistency
Parent topic: Declarations and Attributes


Recommended Forms

This section describes the recommended forms of the DECLARE statement within the following statement categories: simple declarations, factored declarations, and structure declarations.

  • Simple Declarations
  • Factored Declarations
  • Structure Declarations
Parent topic: DECLARE Statements


Simple Declarations

A simple declaration defines a single name and describes its attributes. Its recommended form is:

DECLARE name a?1 a?2 a?n;

where name is the declared name and a1 through an are attributes. For example:

DECLARE A FIXED BINARY(15);
DECLARE B CHARACTER(10) VARYING STATIC INITIAL('ABC');
DECLARE C DIMENSION(5) FLOAT DECIMAL(7);

The last statement in this example could also be given without the keyword DIMENSION by using the following format:

DECLARE C(5) FLOAT DECIMAL(7);
Parent topic: Recommended Forms


Factored Declarations

Factored declarations define two or more names having the same attributes. The recommended form of a factored declaration is:

DECLARE (name-1[,name-2]…)a?1 a?2…a?n;

where each name is declared to have all of the attributes a?1 through a?n. In factored declarations, the names must be enclosed in parentheses.

Examples:

DECLARE (A,B,C) FIXED BINARY(15);
DECLARE (P,Q) POINTER STATIC INITIAL(NULL);
DECLARE (X,Y)(5) FLOAT DECIMAL(7);

The last example is equivalent to the following statement:

DECLARE (X,Y) DIMENSION(5) FLOAT DECIMAL(7);

The bounds must be the first attribute in an attribute list if they appear without the DIMENSION keyword.

Parent topic: Recommended Forms


Structure Declarations

The declaration of a structure defines the organization of the structure and the names of members at each level of the structure. The general form of this declaration is:

DECLARE 1 structure_name a?1 a?2 … a?n,
       k member_name-1 a?1 a?2 … a?n,
       k member_name-2 a?1 a?2 …. a?n,
           .
           .
           .
       k member_name–m a?1 a?2 … a?n;

where each member_name specifies a member of the structure preceded by a level-number, k, and where the level-number of each member must be greater than the level-number of its containing structure, equal to level-numbers of members at the same level, and less than the level-numbers of members it contains. The major structure name is declared as structure level 1.

The only attributes given to the structure itself are storage class, ALIGNED, UNALIGNED, DIMENSION, REFER, and UNION. Each member is declared to have all attributes following its name up to the next comma or up to the end of the statement. For example:

DECLARE 1 S    STATIC,
            2  A(5) FLOAT DECIMAL(7),
            2  B  FIXED BINARY(15),
            2  C,
                  3 D   POINTER,
                  3 E   CHARACTER(10) INITIAL('ABC');

In this example, S is a static structure with members A, B, and C. C is a substructure with members D and E. Initial attributes can be given to elementary members of static structures, but not to structures themselves.

Parent topic: Recommended Forms


The General Form

Following is the general form of the DECLARE statement:

DECLAREd?1[,d?2 …];

or

DCL d?1 [,d?2 …];

where each d is:

[k]name a?1 a?2 … a?n

or

[k](d?1[,d?2]…)a?1 a?2 … a?n

where k is an optional level number, each a is an attribute, and name is a name to be declared.

Examples:

DECLARE ((A FIXED, B FLOAT) DECIMAL, C BIT) STATIC;
DECLARE 1 S STATIC, 2 (A FIXED, B FLOAT) INITIAL(0);

These examples illustrate more factored declarations, as indicated by the fact that the DECLARE statements contain parenthetical lists of names. Factored declarations can be transformed into nonfactored declarations by copying the level number and attribute list of the innermost set of parentheses onto each name contained within the parentheses, removing the parentheses, and repeating this process with the next set of parentheses.

After defactoring, the previous examples are:

DECLARE A FIXED DECIMAL STATIC;
DECLARE B FLOAT DECIMAL STATIC;
DECLARE C BIT STATIC;
DECLARE 1 S STATIC,
      2 A FIXED INITIAL(0),
      2 B FLOAT INITIAL(0);

Factored declarations, other than as shown in the recommended form (see the section Factored Declarations) are generally more difficult to read than their unfactored equivalents.

If defactoring produces more than one level number for a given name, even if the level numbers are equal, the factored declaration is invalid and causes the Compiler to issue an error message.

Specification of duplicate attributes containing more than a simple keyword is also invalid, even when the attributes are exact duplicates.

Parent topic: DECLARE Statements
Related information
Factored Declarations


Defaults

If the attributes specified for a name in a DECLARE statement are incomplete, the missing attributes can be supplied either by the Compiler or by the user with the DEFAULT statement.

  • Compiler-supplied Defaults
  • The DEFAULT Statement
Parent topic: DECLARE Statements


Compiler-supplied Defaults

The Compiler supplies the required additional attributes, as follows:

Specified | Missing | Supplied
binary | fixed | float | fixed
decimal | fixed | float | fixed
fixed | binary | decimal | decimal
float | binary | decimal | decimal
static | internal | external | internal
bit | length | length of one
character | length | length of one
area | size | size of 1000

Defaults are also supplied for the following conditions.

  • STATIC is supplied if EXTERNAL is specified without a storage class and the declared name is not an entry or file constant.
  • AUTOMATIC is supplied if the name is the name of a nonparameter variable that is not a member of a structure and no storage class was specified.
  • The default precision is supplied if precision is not specified for arithmetic data. For information on the Open PL/I default precisions, see your Open PL/I User's Guide.
  • VARIABLE is supplied if a storage class, array bounds, or member's level number is specified with FILE or ENTRY.
  • EXTERNAL is supplied if FILE or ENTRY is specified and VARIABLE is neither specified nor supplied under the previous rule. In this case, the named object is a constant rather than a variable.
  • UNALIGNED is supplied for bit-string data; ALIGNED for all other types of data.
Parent topic: Defaults
Related information
Open PLI Users Guide


The DEFAULT Statement

You can change Compiler-supplied defaults, or you can apply a completely new set of default attributes, using the DEFAULT statement.

Parent topic: Defaults
Related information
DEFAULT


Attribute Consistency

After default attributes have been supplied, each declaration is checked by the Compiler for consistency and completeness.

If no data type is specified, either explicitly or by the DEFAULT statement, the declaration is invalid and incomplete. The Compiler issues an error message and supplies a type of Fixed Binary(15) for names beginning with any of the letters I through N, and Float Decimal(6) for names beginning with any other alphabetic character.

A declaration is inconsistent and invalid if it specifies more than one data type or more than one storage class.

These are the valid data types:
  • Fixed Binary(p)
  • Fixed Decimal(p[,q])
  • Float Binary(p)
  • Float Decimal(p)
  • Picture
  • Character(n) [Varying]
  • Bit(n)[Aligned]
  • Pointer
  • Offset
  • Area
  • Label
  • Entry [returns][variable]
  • File [variable]
  • Builtin
  • Structure
These are the valid storage classes:
  • automatic
  • based or based(pointer-reference)
  • static internal
  • defined(reference)
  • parameter
  • member of structure

A declaration is also inconsistent and invalid if it violates the following attribute-specific restrictions:

  • A name declared with the BUILTIN attribute cannot have any other attribute.
  • A name declared with the FILE or ENTRY attribute, but without the VARIABLE attribute, is a named constant, not a variable, and its scope is external. (Recall, however, that the presence of a storage class, an array bound, or a member's level-number causes the VARIABLE attribute to be supplied by default to declarations containing the ENTRY and FILE attributes.)
Parent topic: DECLARE Statements


Attributes of DECLARE Statements

This section describes, in alphabetical order, the attributes that are permitted in a DECLARE statement.

The discussion of each attribute assumes that the attributes have been made complete by the application of defaults, as described in the section Defaults.

Each attribute discussed in this section falls into one of the following categories:

  • Arithmetic or string data attributes, which define arithmetic or string data.
    • ALIGNED
    • BIGENDIAN
    • BINARY
    • BIT
    • CHARACTER
    • DECIMAL
    • FIXED
    • FLOAT
    • NATIVE
    • NONNATIVE
    • PICTURE
    • REAL
    • SIGNED
    • UNALIGNED
    • UNSIGNED
    • VARYING
  • Data type attributes, which apply to program data not used for computation.
    • AREA
    • CONDITION
    • DIMENSION
    • ENTRY
    • EXCLUSIVE
    • FILE
    • LABEL
    • LIKE
    • OFFSET
    • POINTER
    • TYPE
  • Storage class and scope attributes, which control the allocation and storage use for a data variable and define the variable's scope.
    • AUTOMATIC
    • BASED
    • CONTROLLED
    • CONNECTED
    • DEFINED
    • EXTERNAL
    • GLOBALDEF
    • GLOBALREF
    • INITIAL
    • INTERNAL
    • NOINIT
    • NONCONNECTED
    • PARAMETER
    • POSITION
    • READONLY
    • REFER
    • STATIC
    • UNION
  • File description attributes, which can be applied to file constants or may be used in OPEN statements (except ENVIRONMENT, which can be used only in the DECLARE statement).
    • DIRECT
    • ENVIRONMENT
    • INPUT
    • KEYED
    • OUTPUT
    • PRINT
    • RECORD
    • SEQUENTIAL
    • STREAM
    • UPDATE
  • Entry name attributes, which can be applied to identifiers of entry points. These include:
    • BUILTIN
    • ENTRY
    • IRREDUCIBLE
    • OPTIONS(DESCRIPTOR)
    • OPTIONS(NODESCRIPTOR)
    • OPTIONS(VARIABLE)
    • REDUCIBLE
    • RETURNS
    • VARIABLE
  • Argument-passing attributes, which describe parameters of external procedures. These include:
    • ANY
    • BYVALUE
    • OPTIONAL
Note:

File description attributes specified in a DECLARE statement apply to all openings of the file control block associated with the file constant. For further discussion of these attributes, see the sections Input and Output in Language Concepts and OPEN in Statements.

  • ALIGNED
  • ANY
  • AREA
  • AUTOMATIC
  • BASED
  • BIGENDIAN
  • BINARY
  • BIT
  • BUILTIN
  • BYVALUE
  • CHARACTER
  • CONDITION
  • CONNECTED
  • CONTROLLED
  • DECIMAL
  • DEFINED
  • DIMENSION
  • DIRECT
  • ENTRY
  • ENVIRONMENT
  • EXCLUSIVE
  • EXTERNAL
  • FILE
  • FIXED
  • FLOAT
  • GLOBALDEF
  • GLOBALREF
  • INITIAL
  • INPUT
  • INTERNAL
  • IRREDUCIBLE
  • KEYED
  • LABEL
  • LIKE
  • NATIVE
  • NOINIT
  • NONCONNECTED
  • NONNATIVE
  • OFFSET
  • OPTIONAL
  • OPTIONS(DESCRIPTOR)
  • OPTIONS(NODESCRIPTOR)
  • OPTIONS(VARIABLE)
  • OUTPUT
  • PARAMETER
  • PICTURE
  • POINTER
  • POSITION
  • PRINT
  • READONLY
  • REAL
  • RECORD
  • REDUCIBLE
  • REFER
  • RETURNS
  • SEQUENTIAL
  • SIGNED
  • STATIC
  • STREAM
  • TYPE
  • UNALIGNED
  • UNION
  • UNSIGNED
  • UPDATE
  • VALUE
  • VARIABLE
  • VARYING
Parent topic: Declarations and Attributes
Related information
Defaults
Input and Output
OPEN


ALIGNED

ALIGNED is a data type attribute that controls the storage boundary of data.

ALIGNED is an optional part of the data type specification. Its presence allows the Compiler to align the data on an implementation-defined storage boundary, with the possible side effect that more bits or bytes of storage are used than specified by the declared length.

Parent topic: Attributes of DECLARE Statements
Related information
ALIGNED and UNALIGNED Attributes
Bit-String Data


ANY

The ANY attribute specifies that the corresponding argument for a parameter can be of any data type. The ANY attribute is applicable only to the declaration of entry names and is valid only in a parameter descriptor. ANY is not valid as an attribute in a PROCEDURE or ENTRY statement.

Parent topic: Attributes of DECLARE Statements
Related information
ENTRY


AREA

AREA is a non-computational data type attribute used to define a region of storage in which based variables can be allocated and freed. The format is:

AREA[(exp[REFER(variable)])]

or

AREA(*)

For a complete description of area data and the use of the AREA attribute, see the section Area Data in the chapter Data Types.

Parent topic: Attributes of DECLARE Statements
Related information
Area Data


AUTOMATIC

Abbreviation: AUTO

AUTOMATIC is a storage class attribute that specifies that the declared name is a variable that is allocated storage with each activation of its containing procedure or BEGIN block.

The AUTOMATIC attribute is supplied by default to any name of a non-parameter variable that is not a member of a structure and that has no storage class.

Parent topic: Attributes of DECLARE Statements
Related information
Automatic Storage


BASED

BASED is a storage class attribute that specifies that the declared name is a based variable. Its format is:

BASED[(r)]

In the optional form, r is a reference to a locator variable or a locator-valued function that serves as the default (implicit) locator qualifier for unqualified references to the name.

Parent topic: Attributes of DECLARE Statements
Related information
Based Variables


BIGENDIAN

BIGENDIAN is a data type attribute (applying to Fixed Binary items only) that specifies the internal storage for a data item is MSB first (or MSB "left -to- right"). This attribute is applicable only to Little-Endian machine architectures (such as Intel). For Big-Endian architectures, this attribute is ignored.

Example:

dcl flag fixed bin (15) static initial (1) bigendian;
Parent topic: Attributes of DECLARE Statements


BINARY

Abbreviation: BIN

BINARY is an arithmetic data type attribute that specifies that the base is binary. Its format is:

BINARY[(p)]

The precision p may be supplied with the BINARY attribute or with the FIXED or FLOAT attribute, but it cannot be specified twice. The precision p must be a positive integer. If no precision is specified, a default precision is supplied. For information on the default precisions, see your Open PL/I User's Guide and the section DEFAULT in the chapter Statements.

If BINARY is specified without FIXED or FLOAT, FIXED is assumed.

When used with FIXED, BINARY specifies integer arithmetic values that contain at least p bits.

When used with FLOAT, BINARY specifies floating-point arithmetic values that have a mantissa that contains the equivalent of at least p bits.

Parent topic: Attributes of DECLARE Statements
Related information
DEFAULT
Arithmetic Data


BIT

BIT is a bit-string data type attribute that identifies a variable as a bit-string variable. Its format is:

BIT[(n)]

Length n is an extent expression or integer constant, depending on the storage class of the declared name. The length n must be a non-negative integer constant or an expression that evaluates to a non-negative integer. A default length of 1 is supplied if no length is given.

For more information on BIT, see the chapter Storage Classes and the section Bit-String Data in the chapter Data Types.

Parent topic: Attributes of DECLARE Statements
Related information
Storage Classes
Bit-String Data


BUILTIN

BUILTIN is an entry name attribute that indicates that the declared name is a built-in function. Unless an empty argument list is used in a reference to a built-in function having no parameters, the function must be declared with the BUILTIN attribute.

BUILTIN can be used to redeclare a built-in function name that was declared as something else in an outer block. The declared name must be one of the names given in the chapter Open PL/I Built–Ins.

Parent topic: Attributes of DECLARE Statements
Related information
Open PL/I Built–Ins


BYVALUE

Note: VALUE is accepted as a synonym for BYVALUE.

BYVALUE can be used as an attribute in an ENTRY declaration, or can be applied to a parameter.

  • When used in a parameter descriptor in an ENTRY declaration, the BYVALUE attribute is a storage class and scope attribute that specifies that the corresponding argument is to be passed by immediate value. (For more information on using BYVALUE in a parameter descriptor, see the section ENTRY.)
  • If applied to a parameter, the BYVALUE attribute is an argument-passing attribute. (As an argument-passing attribute, BYVALUE indicates that the value and not the address of the parameter has been passed to the procedure. A new value assigned to a parameter with the BYVALUE attribute does not change the value of the argument in calling procedures.)

The BYVALUE attribute may only be applied to a parameter and parameter descriptors of the following types:

Fixed Binary(n) | where n ? 31
Float Binary(n) | where n ? 23 (when calling PL/I)
Float Binary(n) | where n ? 52 (when calling non-PL/I)
Aligned Bit(n) | where n ? 32
Character |
Pointer |
Entry |

The BYVALUE attribute is ignored if it is applied to a variable that is not a parameter.

If a parameter is multi-positional (appears in one or more of the PROCEDURE and ENTRY statements in a particular procedure) it may not have the BYVALUE attribute applied to it.

When a procedure is called from an Open PL/I procedure, the BYVALUE attribute should be applied only to a parameter whose corresponding parameter descriptor was also declared with BYVALUE in the calling procedure's ENTRY declaration in the called procedure. For example:

P: PROCEDURE( A, B, Q);
DECLARE
   A FIXED BIN(31) BYVALUE,
   (B,C) FIXED BIN(15),
   Q POINTER BYVALUE,
   X FIXED BIN(15) BASED (Q);
B = A + 2;
A = 2 * B;
C = X;
ALLOCATE X SET(Q);
X = A + C;
END;

In this example, the value passed by A is incremented by 2 and returned to the calling procedure through B. The assignment of 2 * B to A does not affect the calling procedure; the value of the first argument of the CALL is unchanged by the assignment to A in the called procedure. Similarly, the value of the argument in the calling procedure that corresponds to Q is not changed by the ALLOCATE statement.

Parent topic: Attributes of DECLARE Statements
Related information
ENTRY


CHARACTER

Abbreviation: CHAR

CHARACTER is a character-string data type attribute that identifies a variable as a character-string variable. Its format is:

CHARACTER[(n)]

Length n is an extent expression or integer constant, depending on the storage class of the declared name. The length n must be a non-negative integer constant or an expression that evaluates to a non-negative integer. A default length of 1 is supplied if no length is specified. For a discussion of storage classes, see the chapter Storage Classes and the section Character-String Data in the chapter Data Types.

Parent topic: Attributes of DECLARE Statements
Related information
Storage Classes
Character-String Data


CONDITION

Abbreviation: COND

CONDITION is an attribute that indicates that the declared name is a condition name. Its format is:

CONDITION

Condition names can be used only in ON, SIGNAL, or REVERT statements. The default scope of condition name is external. Note that a name that appears with the CONDITION condition in an ON, SIGNAL, or REVERT statement is contextually declared to be a condition name.

Parent topic: Attributes of DECLARE Statements
Related information
ON


CONNECTED

Abbreviation: CONN

The CONNECTED attribute may be used only for parameters. It cannot be specified for a member of a structure and it cannot be specified for CONTROLLED parameters. The CONNECTED attribute asserts that any argument passed to the parameter is in connected storage.

Parent topic: Attributes of DECLARE Statements


CONTROLLED

Abbreviation: CTL

CONTROLLED is a storage class attribute that specifies a variable whose storage is dynamically allocated and freed in generations. Its format is:

CONTROLLED
Parent topic: Attributes of DECLARE Statements
Related information
Controlled Variables


DECIMAL

Abbreviation: DEC

DECIMAL is an arithmetic data type attribute that specifies that the base is decimal. Its format is:

DECIMAL[(p[,q])]

The precision p,q (q is optional and represents fractional digits) may be supplied with the DECIMAL attribute or with the FIXED or FLOAT attribute, but it cannot be specified twice. The precision p and the scale q (if specified) must be positive integers. If a precision or scale is not specified, a default is assumed. For more information on default precisions, see your Open PL/I User's Guide and the section DEFAULT in the chapter Statements.

If DECIMAL is supplied without FIXED or FLOAT, FIXED is the default. If FIXED or FLOAT is specified without BINARY or DECIMAL, DECIMAL is the default.

When used with FIXED, DECIMAL specifies fixed-point arithmetic values that contain at least p decimal digits. If q is specified, p minus q digits are integral digits and q digits are fractional digits. If q is omitted, q = 0 is assumed. These values are integers containing at most p decimal digits.

Note: FIXED DECIMAL fractions with a precision less than the scale are not supported.
declare fd fixed decimal (1,2) init (2)  /* not supported. */

When used with FLOAT, DECIMAL specifies floating-point arithmetic values whose mantissa contains the equivalent of at least p decimal digits. In this case, q cannot be specified.

Parent topic: Attributes of DECLARE Statements
Related information
DEFAULT
Arithmetic Data